> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 用Claude Agent SDK构建CLI工具
- URL: https://www.hubwiz.com/blog/build-cli-tools-with-claude-agent-sdk/
- Published: 2026-04-09T11:59:09.000Z
- Updated: 2026-04-09T16:28:01.000Z
- Description: Claude Agent SDK为你的CLI提供了任何参数解析器都无法提供的东西。它可以对模糊输入进行推理，迭代调用工具，并根据在代码库或环境中的发现调整其方法。
- Author: admin
- Tags: LIBRARY, CLAUDE AGENT SDK, #Import 2026-10-14 14:41

我已经向我的团队说了几个月，Claude Code包装器将成为2026年的Cursor。在花了大量时间深入研究Claude Agent SDK后，是的，在像其他人一样仔细研究了泄露的源代码之后，我比以往任何时候都更加确信。转变是真实的：不再是来回复制粘贴上下文，而是让AI控制自己的环境。它在需要时读取文件，在需要时写入，运行命令检查是否有效。

而将其变成可交付产品的最快方式？CLI。

以下是我会如何着手，以及我认为你也应该如何着手。

## 1、为什么终端是正确的前门

如果你为开发者构建，或为开发者越来越多地将其接入工作流的智能体构建，CLI就是原生界面。它可以与管道组合。它在CI/CD中运行。它不需要与浏览器标签争夺注意力。

但真正值得关注的事情：Claude Agent SDK为你的CLI提供了任何参数解析器都无法提供的东西。它可以对模糊输入进行推理，迭代调用工具，并根据在代码库或环境中的发现调整其方法。这不是终端里的聊天机器人。这是一个带有命令行前门的自主智能体。

我一直在企业项目中使用这个确切的过滤器：如果Claude Code不能在一日内搭建解决方案，那么问题要么是范围界定不清，要么是真正新颖的。无论哪种情况，你都能快速学到东西。A CLI agent built on this SDK gives you that same rapid feedback loop, but for your users.

10年前，你可以筹集100万美元，从FAANG聘请一个精英团队，花几个月时间构建产品，最终仍然获得0个客户。现在你可以将反馈循环缩短到几小时（仍然获得0个客户）。CLI是你如何将同样的速度交给使用你工具的人。

## 2、核心循环：异步生成器，到此为止

如果你研究过Claude Code在底层实际如何工作，你就知道整个智能体作为单个异步生成器运行。每个事件（模型输出、工具调用、错误）都会即时流式传输。`query()`函数是一个为一次性任务设计的异步生成器，在消息到达时流式传输消息。UI逐字符渲染，而不是在30秒的沉默后。你可以中止它、暂停它，或将它嵌套在子智能体中。

以同样的方式构建你的。

在高层次上，你的CLI智能体有三个工作：

1. **解析用户意图。** 从命令行接受自然语言提示或结构化标志。
2. **运行智能体循环。** 将提示交给SDK，SDK管理对话、工具执行和多轮推理。
3. **返回结果。** 将输出流式传输到终端，或生成结构化产物。

这是最简单的版本：

```python
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="读取配置文件并解释其作用",
        options=ClaudeAgentOptions(
            cwd="/path/to/project",
            allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
        )
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

anyio.run(main)

```

SDK附带用于文件操作、shell命令和代码搜索的内置工具。你不需要自己实现这些。智能体决定何时以及如何使用它们。这就是重点：你定义工具箱，智能体处理编排。

## 3、通过MCP自定义工具：你的领域API层

内置工具涵盖通用内容。但当你需要领域特定逻辑（查询数据库、调用内部API、检查服务健康）时，你需要定义自定义MCP（模型上下文协议）工具。

这就是让我觉得不同的地方。我最近写道，SaaS的未来是一个后端，两个前门：一个给人类，一个给他们的智能体。你的用户点击按钮。他们的智能体调用你的API。两者做同样的事情。当你的CLI智能体通过MCP暴露领域工具时，你正是在构建这种架构。技能成为新的分销渠道。你的产品成为他们智能体的工具，而不是他们必须访问的标签页。

我在管理AI产品项目中艰难学到的一些设计原则：

- **一个工具，一个任务。** `check_service_health`和`restart_service`比`service_operation(action, name)`更好。模型用专注的工具推理得更好。
- **将错误作为内容返回，而不是异常。** 智能体可以对失败进行推理并重试。这反映了Claude Code内部如何处理错误：错误恢复不是循环的包装器，它*就是*循环本身。
- **对危险操作设限。** 删除资源或推送到生产的工具需要确认逻辑或试运行模式。没有例外。开发者可以使用`allowed_tools`来控制智能体自主性，自动批准特定操作，或使用`permission_mode`对敏感操作（如文件编辑）要求用户确认。

## 4、将其接入你的CLI

使用你喜欢的任何CLI框架：`argparse`、`click`、`typer`。真正的决定是你的界面模式：

**自然语言模式**，自由形式提示：

```bash
$ mycli "将数据库模块重构为使用连接池"

```

**混合模式**，常见任务的子命令，自由形式回退：

```bash
$ mycli scaffold --template fastapi my-project
$ mycli ask "为什么这个测试不稳定？"

```

无论哪种方式，提示都会流入SDK的`query()`函数，或者为了更多控制，流入`ClaudeSDKClient`，后者维护多轮对话的会话历史和上下文。TypeScript SDK V2预览版通过`send()`和`stream()`方法使这一点更加清晰，用于多轮对话。如果你在那个生态系统中构建，值得关注。

CLI位于"针对API编写代码"和"使用GUI"之间。它为你提供编程控制，而无需编写完整集成。管道输出、链式命令、在CI/CD中运行、将复杂工作流别名为单行命令。REST API用于应用程序。MCP用于模型到工具通信。CLI用于在终端中思考的人类。不同的用户，不同的界面，相同的后端。

## 5、流式输出：因为冻结的终端会扼杀信任

没有人喜欢盯着空白光标。让Claude Code感觉神奇的事情之一是UI逐字符渲染。Agent SDK为你提供同样的能力：

```python
async with ClaudeSDKClient(options=options) as client:
    await client.query("解释认证模块")
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="", flush=True)
        elif isinstance(message, ResultMessage):
            print(f"\n\n完成 (停止原因: {message.stop_reason})")

```

`ClaudeSDKClient`为你提供对智能体生命周期的细粒度控制：流式传输、中断、运行时MCP服务器管理。当你只需要最终结果时，使用更简单的`query()`。

Claude Code还会在用户输入时预计算响应，这是响应时间感觉比应该更快的原因之一。对于像"yes"这样的简单输入，系统在你按下回车之前就开始处理你的可能结果。在设计自己的UX时，关于感知延迟，这是值得记住的事情。

## 6、上下文、状态和压缩秘密

CLI调用通常是无状态的。但智能体从上下文中受益匪浅。SDK支持几种策略：

- **项目文件作为上下文。** 通过`setting_sources=["project"]`自动加载`CLAUDE.md`，或传递自定义`system_prompt`。
- **会话恢复。** 从init消息捕获`session_id`，在下次调用时传递`resume=session_id`以继续完整上下文。
- **环境感知。** 将`cwd`设置为项目目录，以便智能体自我定位。

这是大多数人错过的东西：Claude Code按成本顺序运行四种压缩策略。**微压缩**缓存未更改的工具结果（每轮运行）。**剪切**修剪旧消息同时保护最近上下文。**自动压缩**在剪切不够时对先前对话进行摘要。**上下文折叠**为最长会话进行分段压缩。最便宜的先运行。最贵的只在其他都不起作用时才触发。这是长会话感觉如此良好的重要部分。

如果你在这个SDK之上构建自己的编排层，将管理背景细节作为首要关注点，而不是事后考虑。这就像一般的软件开发：关注关键点，而不是试图一次监控所有事情。

## 7、真正有效的护栏

智能体可能会失控。我在生产中见过。SDK提供真正的护栏，你应该在其上叠加你自己的：

- `max_turns`：限制工具调用轮次以防止无限循环。
- `max_budget_usd`：限制每次调用的支出。对于面向客户的任何东西都是不可协商的。
- `permission_mode`：`"default"`在危险操作前提示；`"acceptEdits"`自动接受文件更改，同时对shell命令设限。
- `PreToolUse`钩子：在执行前拦截和验证工具调用。记录它们、阻止模式、要求确认。
- 错误处理：捕获`CLINotFoundError`、`CLIConnectionError`和`ProcessError`以处理SDK级故障。

这反映了Claude Code内部的7阶段批准链：输入验证、拒绝规则、允许规则、工具特定检查、钩子、ML分类器、用户提示。不是一个开关。一个内置渐进信任的规则引擎。说真的，用规则约束智能体的解决方案空间、边学边做的习惯、以及护栏， paradoxically increases productivity and reliability. 以同样的理念构建你的。

## 8、完整图景

这是一个最小但生产就绪的CLI智能体，带有自定义工具：

```python
import sys
import anyio
from claude_agent_sdk import (
    tool, create_sdk_mcp_server, ClaudeSDKClient,
    ClaudeAgentOptions, AssistantMessage, TextBlock, ResultMessage,
)

@tool("deploy_service", "将服务部署到预发或生产环境", {
    "service": str, "environment": str,
})
async def deploy_service(args):
    service, env = args["service"], args["environment"]
    return {"content": [{"type": "text", "text": f"已将 {service} 部署到 {env}"}]}

server = create_sdk_mcp_server("deploy-tools", tools=[deploy_service])

async def main():
    prompt = " ".join(sys.argv[1:]) or "你能帮我什么？"
    options = ClaudeAgentOptions(
        cwd=".",
        allowed_tools=["Read", "Glob", "Grep", "Bash"],
        mcp_servers={"deploy": server},
        permission_mode="default",
        max_turns=20,
        system_prompt="你是部署助手。使用可用工具帮助用户管理他们的服务。",
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query(prompt)
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text, end="", flush=True)
            elif isinstance(message, ResultMessage):
                print()

anyio.run(main)

```

对于生产环境，使用`--bare`模式跳过自动发现本地钩子和插件。这对确定性的CI/CD行为至关重要。

## 9、这种模式何时有意义

当任务涉及探索和判断、当用户输入模糊或多样、当工作流是多步骤时，使用这种方法。对于简单的CRUD CLI或完全确定性的工具，这是过度设计。

但这是我的看法：符合"探索和判断"的任务范围正在快速扩展。每周，智能体在处理模糊性方面都变得更好。你今天在这个SDK上构建的工具不仅仅是解决当前问题。它们让你站在浪潮的正确一边。与Cursor首次推出时，每个人仍在争论Copilot vs no Copilot时的能量相同。

## 10、入门

```bash
pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-key-here

```

从内置工具和`query()`开始。随着你发现领域需要什么，添加自定义MCP工具。随着智能体赢得信任，叠加钩子和权限控制。

SDK处理对话管理、工具调度和会话生命周期。你的工作是定义正确的工具和正确的护栏。这就是整个模型，老实说，公平地说，如果你一直在关注Anthropic如何构建Claude Code本身，你知道它是有效的。

---

原文链接: [Building CLI Tools with the Claude Agent SDK](https://medium.com/@anand.butani/building-cli-tools-with-the-claude-agent-sdk-0bc1641352ce?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处