用 Claude Agent SDK 构建只读仓库分析器

用 Claude Agent SDK 构建只读仓库分析器

把 Agent 接进脚本后，最大的变化不是调用方式，而是模型可以发起工具操作。一个“总结仓库 TODO”的任务，如果运行目录错误或权限没有收窄，可能读取无关项目，甚至请求修改与命令工具。本文从只读分析器开始：安装官方 Python 包，限定仓库工作目录，只预批准读取、文件匹配和文本搜索工具，消费消息流，并明确 allowed_tools 不等于完整拒绝列表。

先确认 SDK 是否适合任务

普通文本生成只需要模型基于输入返回内容；仓库分析还需要遍历文件、搜索文本并保留工具执行过程。Agent SDK 适合后者，但也增加了文件访问、工具权限和运行状态管理。

第一个任务选择只读场景，验收目标如下：

只分析一个明确仓库。
查找 TODO 文本并按文件汇总。
不修改文件，不执行 shell 命令。
输出能够被调用程序消费。
运行前后 Git 工作区没有新增变更。

“TODO”只是演示输入，不代表注释一定对应有效待办；结果仍需项目维护者判断。

安装当前官方包

Claude Agent SDK 官方概览当前提供 TypeScript 与 Python 包：

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

也可以按项目已有 Python 工具使用 uv add claude-agent-sdk。不要在同一个项目里混用多套依赖管理流程。安装前核对官方页面的当前运行时要求，并在虚拟环境中固定最终解析的版本。

本文使用 Python。认证方式、账号条件和环境变量应按官方认证文档配置；不要把密钥直接写进源码、提示词或普通日志。

使用官方只读示例形态

下面代码改编自官方概览中的 query、ClaudeAgentOptions 和消息流写法。为适配只读仓库分析场景，示例使用中文的仓库专用提示词，通过 allowed_tools=["Read", "Glob", "Grep"] 只预批准读取类工具，并且只打印含有 result 的消息：

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="查找仓库中的 TODO 注释，按文件汇总；不要修改文件。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

把脚本放在独立工具目录时，应从目标仓库根目录运行，或按照当前 SDK 文档显式设置工作目录。运行前先打印或记录调用程序确认过的绝对路径，避免 Agent 在用户目录或相邻仓库中搜索。

正确理解 allowed_tools

官方概览说明，allowed_tools 会预批准列表中的 Read、Glob 和 Grep，让这些工具无需额外提示即可运行。它不表示“列表之外的工具从系统中消失”：未列出的工具会进入当前 permission mode；若要彻底阻止工具，需要使用官方文档提供的 disallowed_tools 等权限机制。

因此，生产只读边界至少需要两层：

1. 在 SDK 权限配置中明确预批准和禁止的工具，而不是只依赖提示词。
2. 让进程使用权限受限的账号或隔离环境，从操作系统层阻止写入和敏感目录访问。

具体工具名称、permission mode 和审批回调会随 SDK 版本演进，应从当前 权限与用户输入文档核对。不要根据旧示例猜测一个配置就能覆盖全部工具。

不要只打印最终字符串

示例只在消息含有 result 时打印，便于展示最小流程。真实集成还要处理消息流中的状态、工具调用、错误、取消和最终结果，并避免把敏感文件内容原样写入普通日志。

调用程序可以记录：

任务 ID
目标仓库和确认后的工作目录
SDK 与应用版本
预批准工具和明确禁止工具
开始、结束与取消状态
工具调用的类型和脱敏目标
最终结果或错误

日志的目的是回答“实际发生了什么”，不是保存所有输入内容。源码、凭据和内部路径要按组织的数据分级处理。

为输出增加证据要求

默认汇总可能只给结论。提示词应要求每项结果引用仓库位置：

只查找当前仓库中的 TODO 注释。
按文件分组，每项给出相对路径、行号和原始注释摘要。
忽略依赖目录、构建产物和版本控制目录。
不要修改文件，不执行命令。
无法读取或无法判断的内容单独列出。

忽略目录应与仓库结构一致。若需要可靠排除，应通过工作目录、文件匹配规则或工具权限实现，而不是假设模型每次都能识别生成目录。

运行前后的验证

如果仓库由 Git 管理，运行前记录：

git status --short

运行脚本后再次执行同一命令，并与基线对比。工作区原本可能有用户修改，因此不能简单要求输出为空；验收目标是 Agent 没有新增变化。

同时抽查：

• 输出路径是否都位于目标仓库。
• 行号和注释是否能回到原文件核对。
• 依赖与构建目录是否按任务边界排除。
• 任务失败时是否返回错误，而不是不完整的成功摘要。
• 取消后是否仍有后台工具运行。

只读工具配置不证明数据访问范围合规。进程能读取的敏感文件仍可能进入模型上下文，因此运行账号和仓库内容边界同样重要。

从只读扩展到写入前的门槛

只有当只读流程的路径、消息、错误、取消和日志都可控后，才评估编辑工具。写入任务还需要：

允许修改的文件集合
修改前计划与人工确认
Diff 审查
项目已有测试
命令执行的独立权限
失败后的恢复方式
提交或发布仍由谁负责

不要把编辑、shell 和网络同时加入第一次扩展。每增加一种工具，单独设计成功、拒绝、失败和取消测试。

结论与限制

Claude Agent SDK 的只读仓库分析器应从明确工作目录、少量读取工具、可消费消息流和前后 Git 基线开始。最容易误解的一点是：allowed_tools 用于预批准，不是完整的工具拒绝策略；真正的只读边界还需要当前 SDK 权限配置和受限运行环境共同保证。

本文代码依据当前官方概览的最小 Python 形态，不覆盖认证部署、长时间任务和写入审批。SDK 接口与工具权限会更新，接入前仍需以项目锁定版本的官方文档和实际测试为准。