AI 编程 Agent 进阶使用指南

AI 编程工具已经从“根据当前一行补全下一行”发展为能够理解仓库、编辑多个文件、执行命令、观察测试结果并继续修正的 Agent。它们可以帮助读者阅读陌生项目、修复缺陷、补充测试、维护 Markdown 文档、整理 Git 提交，甚至连接 Issue、数据库和浏览器完成跨系统任务。但 Agent 不是一个可以跳过工程验证的自动答案机：模型会误解需求，工具可能拥有过高权限，记忆可能过期，插件和 MCP server 还可能引入新的供应链风险。

本章以最容易开始的 OpenAI Codex 为主线，再介绍 Claude Code、Kimi Code，以及如何把 GLM、DeepSeek 等模型服务接入兼容客户端。阅读重点不是背诵某个版本的界面，而是建立一套稳定方法：先明确边界，再让 Agent 读取上下文；先形成可验证计划，再进行小范围修改；最后用 Git 差异、静态检查和测试判断结果。产品版本、模型名称、额度和订阅政策变化很快，涉及这些易变信息时应以文末官方文档为准。

先理解权限，再允许执行

不要在个人主目录、生产服务器或包含真实密钥的目录中首次尝试 Agent，也不要为了省一次确认就启用无沙箱自动批准模式。最安全的起点是一个已提交 Git 的测试仓库，并把写权限限制在当前工作区。

1. 先分清模型、Agent、插件和 MCP

日常讨论经常把 Codex、Claude Code、GLM、Kimi 和 DeepSeek 都称为“AI 编程工具”，但它们所处层次并不完全相同。模型负责根据上下文推理和生成内容；Agent 客户端负责收集仓库上下文、调用模型、执行工具并控制循环；工具完成读文件、写文件、运行 Shell、搜索网页等具体动作；规则或记忆保存项目长期约束；插件与 Skill封装可重复工作流；MCP server则把 GitHub、数据库、浏览器等外部系统以标准工具形式连接给 Agent。

可以把一次 Agent 工作抽象为以下循环：

flowchart LR
    A["用户目标与验收条件"] --> B["Agent 客户端组织上下文"]
    B --> C["模型推理并选择动作"]
    C --> D["读取、编辑、Shell、MCP 工具"]
    D --> E["命令输出、差异与测试结果"]
    E --> C
    C --> F["交付修改与验证报告"]
    F --> G["人工审阅、提交或回滚"]

Codex、Claude Code 和 Kimi Code 都可以作为完整的终端 Agent 使用。GLM 和 DeepSeek 首先是模型与 API 服务，通常需要接入 Claude Code、OpenCode、Cline、Roo Code 等 Agent 客户端才能获得仓库读取、文件编辑和终端执行能力。Kimi 同时提供 Kimi Code Agent 和兼容 API，因此它既可以直接使用，也可以作为第三方客户端的模型后端。理解这种分层后，排错会简单很多：客户端无法启动应检查安装；收到 401 应检查服务端点和密钥；模型能回答却不能改文件，应检查工具权限；每次都忘记规范，应检查规则文件是否被加载。

选择	主要形态	更适合的场景	需要特别关注
Codex	CLI、桌面与 IDE 编程 Agent	希望用较少配置完成仓库级修改、审查和自动化	沙箱、审批、AGENTS.md、插件与 MCP
Claude Code	终端编程 Agent	需要细粒度规则、自动记忆、插件、Hook、子 Agent	CLAUDE.md 层级、权限模式、Hook 副作用
Kimi Code	CLI 与兼容 API	中文协作、终端任务、多种第三方客户端接入	新旧 CLI 差异、插件信任、MCP 权限
GLM Coding Plan	模型订阅与兼容服务	希望给 Claude Code、OpenCode 等客户端提供 GLM 模型	客户端与模型身份要分开，避免硬编码过期映射
DeepSeek API	OpenAI/Anthropic 兼容模型服务	使用兼容客户端构建成本可控的编程工作流	当前模型列表、API 兼容范围、数据和限流政策
OpenCode/Cline/Roo/Aider	多模型 Agent 客户端	希望在多个模型服务之间切换	配置来源、工具权限和不同模型的兼容差异

2. 所有编程 Agent 都应遵守的工作闭环

高质量结果首先来自清晰任务，而不是来自更长的提示词。一个可执行任务至少需要说明目标、允许修改的范围、必须保持不变的行为、验收命令和交付形式。下面的提示比“帮我优化文档”更容易得到稳定结果：

目标：统一 docs/ 下 Markdown 的 frontmatter，并修复站内相对链接。

范围：只允许修改 docs/*.md、mkdocs.yml 和 README.md。
保持不变：正文技术结论、现有 URL slug、站点主题和发布流程。
要求：每个文件只能有一个 H1；标题层级不得跳级；新增链接使用相对路径。
验证：运行 markdownlint、mkdocs build --strict 和 git diff --check。
交付：列出修改文件、检查结果、仍需人工确认的外部链接；不要自动提交和推送。

在启动 Agent 前先建立恢复点。工作区已有未提交修改时，Agent 很难判断哪些差异属于用户，误覆盖风险也会显著上升：

git status --short --branch
git diff --stat
git switch -c docs/agent-edit

# 已跟踪但尚未提交的用户修改应先人工处理，或创建明确的临时提交
git diff

随后让 Agent 按“读取、计划、修改、验证、审阅”五步工作。第一次指令可以只要求它查看目录、规则文件和构建配置，不允许写入。它说明理解后，再授权最小范围修改。完成后不要只阅读 Agent 的总结，必须检查真实差异和验证命令：

git status --short
git diff --check
git diff --stat
git diff --word-diff -- docs/

# 按项目替换为真实命令
npx markdownlint-cli2 "**/*.md"
mkdocs build --strict

git diff --check 用于发现尾随空格和冲突标记；--stat 先显示修改规模；--word-diff 适合审阅长篇 Markdown 中被替换的词句。只有在确认内容和测试结果后才执行 git add 与 git commit。推送、发布、删除远程资源等外部副作用默认应由人确认。

3. Codex：用最少配置完成可靠修改

Codex 适合作为本章的入门工具，因为最简单的使用方式就是进入仓库并描述目标。安装方式可能随平台更新，使用 npm 的常见方式如下；安装后先查看实际版本和帮助，不要照搬与本机版本不匹配的参数：

npm install -g @openai/codex
codex --version
codex --help
codex login

在项目目录中运行 codex 会进入交互会话；也可以用 -C 明确指定工作目录，这对脚本或从其他目录启动时很有用：

codex -C /path/to/project

第一次任务应保持简单，例如“先读取 README、构建配置和 Git 状态，解释这个项目怎样验证；不要修改文件”。确认它找到正确项目后，再要求它编辑一个文件并运行检查。Codex 可以持续观察命令结果，因此“修改并验证”通常比“只生成一段代码给我”更有效；但验收条件仍然需要由读者提供。

3.1 沙箱、审批与目录边界

Codex 的沙箱决定模型生成的命令能够访问什么，审批策略决定何时询问用户。对普通本地项目，workspace-write 是合理起点：允许在工作区内编辑，但不等于可以任意访问整台机器。只读分析可以使用 read-only，而 danger-full-access 应只用于外部已经提供强隔离的临时环境。

# 只分析，不写文件
codex -C /path/to/project --sandbox read-only

# 允许在工作区修改，仍保留必要审批
codex -C /path/to/project --sandbox workspace-write

# 额外目录只有在任务确实需要时再开放
codex -C /path/to/project --add-dir /path/to/shared-fixtures

--dangerously-bypass-approvals-and-sandbox 会同时移除确认和沙箱，名字已经准确描述了风险。它不应出现在个人日常别名、共享脚本或 CI 示例中。即使工作目录本身是测试仓库，Shell 仍可能通过网络、凭据和系统命令产生工作区之外的影响。

经常使用的默认值可以放在个人 ~/.codex/config.toml，项目共享设置可以放在受信任仓库的 .codex/config.toml。配置字段会随版本演进，修改后可用严格配置检查尽早发现拼写错误：

codex exec --strict-config --sandbox read-only \
  "读取项目规则并概括验证命令，不要修改文件"

codex doctor --summary

命令行参数适合一次性覆盖，配置文件适合长期默认值。排错时优先显式传参，确认行为正确后再写入配置，避免同时修改多层配置而无法判断哪一层生效。

3.2 AGENTS.md：Codex 的项目长期说明

Codex 使用 AGENTS.md 保存可持续的仓库约定。它不是一份给模型堆积所有项目知识的百科全书，而应记录每次任务都需要知道、且不容易从代码直接推断的事实，例如构建命令、目录边界、格式规则、验证要求和禁止操作。更靠近子目录的 AGENTS.md 可以为该子树提供更具体的规则。

# Repository instructions

## Scope

- Documentation lives in `docs/`; navigation is defined in `mkdocs.yml`.
- Preserve existing Chinese terminology and URL slugs.

## Editing rules

- Keep one H1 per Markdown file and do not skip heading levels.
- Use relative links for pages inside this repository.
- Never edit generated files under `site/`.

## Validation

- Run `npx markdownlint-cli2 "**/*.md"`.
- Run `mkdocs build --strict`.
- Run `git diff --check` before reporting completion.

好的规则应短、具体、可验证。“写出优雅代码”几乎无法执行，“修改 Python 后运行 pytest -q，不要改迁移历史”则很明确。不要把 API key、客户数据或临时故障写进 AGENTS.md；密钥必须使用环境变量或秘密管理系统，临时任务约束则直接写在当前提示中。

Codex 的会话恢复和项目说明是不同概念。codex resume 用于继续已有会话，保留的是该任务的对话上下文；AGENTS.md 面向进入仓库的所有后续任务，属于经过人工维护的持久规则。需要探索不同方案而不污染原会话时，可以创建分支会话：

codex resume --last
codex fork

不要把恢复会话当作唯一记忆。关键决定最终应写进代码、测试、ADR、README 或 AGENTS.md，这样其他工具和团队成员也能看到。

3.3 审查、非交互执行与结构化输出

Codex 内置审查入口适合在提交前查找行为回归、风险和缺少的测试。审查结论仍然需要人工判断，但它可以成为常规质量门：

# 审查未提交修改
codex review --uncommitted

# 审查当前分支相对 main 的差异
codex review --base main

# 审查指定提交
codex review --commit <commit-sha>

codex exec 适合脚本和 CI。默认文本输出便于阅读，--json 输出 JSONL 事件流，--output-schema 可以约束最终报告结构，--output-last-message 可把最后一条总结保存为文件。自动化应使用最小沙箱，并明确禁止提交、推送和部署：

codex exec -C . --sandbox read-only --ephemeral \
  --output-last-message /tmp/docs-audit.txt \
  "审查 docs/ 的标题和相对链接，只输出问题，不修改文件"

codex exec -C . --sandbox workspace-write \
  "只修复 Markdown 格式问题，运行现有检查，不提交、不推送"

--ephemeral 表示不持久化本次会话文件，适合一次性审计。需要机器稳定解析时，不要让下游脚本猜测自然语言，应提供 JSON Schema 并使用 --output-schema。需要批量处理多个仓库时，先在一个仓库验证提示和权限，再扩大范围。

3.4 Codex 插件、Skill 与 MCP

三者解决的问题不同。Skill 是“怎样完成一类任务”的可复用操作手册；插件是可安装、可版本化的扩展包，可以组合 Skill、命令、工具、Hook、MCP 配置和资产；MCP 则提供实时外部能力。只有重复出现的工作流才值得写成 Skill，只有需要团队分发或组合多种组件时才值得制作插件，只有确实要连接外部系统时才需要 MCP。

Codex 当前 CLI 可以从已配置 marketplace 管理插件。先查看来源和可用列表，再安装指定插件，不要把未知 marketplace 当成可信软件仓库：

codex plugin marketplace list
codex plugin list --available
codex plugin add <plugin-name>@<marketplace-name>
codex plugin list
codex plugin remove <plugin-name>

一个文档维护 Skill 可以规定“先读取导航，再检查标题，最后构建”的顺序，并附带稳定脚本。Skill 的核心通常是 SKILL.md；个人 Skill 放在 Codex 用户目录，项目或插件中的 Skill 则随仓库/插件分发。实际目录约定应以当前 Codex 官方文档和已安装版本为准。Skill 中不要重复粘贴几百行通用知识，而应保存触发条件、步骤、输入输出、脚本位置和失败处理。

MCP 适合连接 Issue、设计稿、知识库和内部 API。远程 HTTP server 使用 URL，本地 stdio server 使用启动命令：

# 远程 Streamable HTTP MCP server
codex mcp add team-docs --url https://example.com/mcp

# 本地 stdio MCP server，双横线后是实际启动命令
codex mcp add local-tools -- node /trusted/path/server.js

codex mcp list
codex mcp get team-docs
codex mcp login team-docs
codex mcp remove team-docs

只连接可信 server。远程 server 能看到发给它的参数，本地 stdio server 则会以本机进程运行；两者都不应因为“使用 MCP 标准”就被自动视为安全。写操作、付款、删除、发布和生产查询应保持逐次审批。

4. Claude Code：精细控制规则、记忆与自动化

Claude Code 同样工作在终端中，擅长读取仓库、编辑文件、运行命令和处理 Git 工作流。常见安装与启动方式如下：

npm install -g @anthropic-ai/claude-code
claude --version
claude doctor

cd /path/to/project
claude

只想分析方案时，可以用计划权限模式启动；需要隔离并行修改时，可让 Claude Code 在 Git worktree 中工作。不同版本支持的权限模式名称可能变化，执行前可查看 claude --help：

claude --permission-mode plan
claude --worktree

非交互模式使用 --print，适合审计和流水线。--max-budget-usd 可以为 API 任务设置预算上限，--json-schema 可约束结构化结果，--allowedTools 与 --disallowedTools 用于限制工具集合：

claude --print \
  --permission-mode plan \
  --max-budget-usd 2 \
  "审查 Markdown 导航与链接，只报告问题，不修改文件"

预算限制不是安全沙箱，允许工具列表也不能替代操作系统权限。自动化账户仍应使用最小文件、网络和仓库权限。

4.1 CLAUDE.md、Rules 与自动记忆

Claude Code 把“人维护的长期指令”和“Agent 自动整理的记忆”分开。项目根目录的 CLAUDE.md 或 .claude/CLAUDE.md 用于团队共享规范；CLAUDE.local.md 用于只对本机生效、通常被 Git 忽略的说明；~/.claude/CLAUDE.md 用于个人跨项目偏好。目录下的 .claude/rules/ 可以进一步拆分规则，并按路径限定适用范围。

如果仓库已经为 Codex 维护了 AGENTS.md，不必复制两份容易漂移的规则。Claude Code 支持在 CLAUDE.md 中导入文件，因此可以把公共约定放在 AGENTS.md，再添加一行：

@AGENTS.md

# Claude Code specific notes

- Use plan mode before changing release configuration.
- Ask before adding dependencies or accessing external services.

在会话中运行 /memory 可以查看实际加载了哪些规则文件，并管理自动记忆。自动记忆保存在用户目录下按项目隔离的位置，用于记录 Claude 自己总结的构建习惯和排错线索；它是机器本地上下文，不会随 Git 自动共享。若规则没有生效，首先用 /memory 检查文件是否被加载，再查找多个层级之间是否冲突。

记忆内容越多并不代表效果越好。每次请求可用上下文是有限资源，把整份架构文档、历史聊天和命令输出全部塞入启动记忆，会稀释真正重要的约束。推荐只保留稳定事实：项目入口、构建与测试命令、目录职责、命名规范、危险操作和经常踩坑的环境条件。版本号、线上状态、临时令牌和未经确认的猜测不应进入长期记忆。

4.2 Plugin、Skill、子 Agent 与 Hook

项目专用、正在试验的扩展可以直接放在 .claude/；需要跨项目共享、版本化发布时再制作插件。Claude Code 插件可以组合 Skill、子 Agent、Hook、MCP server、LSP server 和后台监控。插件根目录的典型结构如下：

docs-maintainer/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── audit-markdown/
│       └── SKILL.md
├── agents/
│   └── docs-reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json
└── scripts/
    └── check-docs.sh

只有 plugin.json 放在 .claude-plugin/ 内，其他组件位于插件根目录。安装前先检查 marketplace 来源、manifest、Hook 脚本和 MCP 启动命令：

claude plugin marketplace list
claude plugin list
claude plugin install <plugin>@<marketplace>
claude plugin update <plugin>@<marketplace>
claude plugin disable <plugin>@<marketplace>
claude plugin uninstall <plugin>@<marketplace>

Skill 适合封装“如何做文档审计”这类流程；子 Agent 适合把独立上下文交给专门角色，例如只读审查员；Hook 适合执行不可依赖模型自觉的机械规则，例如每次写入后检查格式或在提交前运行秘密扫描。区分三者的关键是：建议流程写 Skill，独立委派用子 Agent，必须触发的确定性约束用 Hook。

Hook 会执行真实命令，错误配置可能让每次编辑都变慢，甚至修改或上传文件。应先让 Hook 只记录事件，再逐步增加只读检查；不要从不可信仓库直接启用 Hook。下面是思路示例，实际事件名和 matcher 应按当前官方 Hook reference 校验：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --check"
          }
        ]
      }
    ]
  }
}

Claude Code 的 MCP 可通过 CLI 管理。远程服务优先使用 Streamable HTTP，本地工具使用 stdio；OAuth 服务可在会话内用 /mcp 完成认证：

claude mcp add --transport http team-docs https://example.com/mcp
claude mcp add local-tools -- node /trusted/path/server.js
claude mcp list
claude mcp get team-docs
claude mcp remove team-docs

项目级 .mcp.json 会随仓库共享，其中的 stdio 命令可能在受信任后启动本地进程，因此拉取陌生项目后不能盲目批准。插件自带的 MCP server 也应按同样标准审查。

5. Kimi Code：直接使用 Agent，再按需扩展

Kimi Code 提供终端 Agent，能够读取与编辑文件、执行命令、搜索信息并持续完成任务。当前官方 CLI 已从旧版 Python 实现升级为 Node.js 版本，网络上的旧教程可能仍使用 uv 或旧配置目录；遇到差异时应以当前 Kimi Code 文档为准。

官方提供平台安装脚本。执行任何管道安装脚本前，严格环境中应先下载并审阅内容；安装完成后运行 kimi，首次使用通过 /login 登录：

# 官方便捷安装形式；安全敏感环境应先下载、审阅再执行
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

kimi
# 进入交互界面后执行 /login

最初仍然采用通用闭环：进入 Git 仓库，要求 Kimi 只读分析，再允许局部编辑。不要在不了解权限含义时使用 --yolo；它会自动批准工具调用，只适合已经由容器或虚拟机强隔离且不含真实凭据的环境。

Kimi Code 的长期配置位于 ~/.kimi-code/config.toml，界面偏好位于配套的 tui.toml。权限规则按顺序匹配，第一个命中的 allow、deny 或 ask 决定行为。相比全局允许 Shell，更合理的做法是允许常见只读命令、拒绝明显破坏性命令，让其他动作逐次询问：

[[permission.rules]]
decision = "allow"
pattern = "Read"
reason = "Allow repository reads"

[[permission.rules]]
decision = "deny"
pattern = "Bash(rm -rf*)"
reason = "Block destructive recursive deletion"

[[permission.rules]]
decision = "ask"
pattern = "Bash(*)"
reason = "Review other shell commands"

权限模式只是最后一道控制。命令可以通过脚本、包管理器或网络调用间接产生副作用，因此规则不能代替沙箱和人工审阅。

5.1 Kimi 插件与 MCP

Kimi 插件可以打包 Agent Skill、会话启动 Skill、MCP server、Hook 和 Markdown 斜杠命令。进入 Kimi TUI 后运行 /plugins 可以打开管理器，也可以直接执行命令：

/plugins list
/plugins marketplace
/plugins install <path-or-url>
/plugins info <plugin-id>
/plugins enable <plugin-id>
/plugins disable <plugin-id>
/plugins remove <plugin-id>
/plugins reload

插件发生变化后需要 /reload 或新会话才能完全生效。第三方插件可以包含启动 MCP server 的声明和生命周期 Hook，安装前应检查来源、固定版本、manifest 与脚本。面向团队的 Markdown 插件可以把审计流程写成 SKILL.md，再注册 /docs:audit、/docs:normalize-frontmatter 等命令，但命令正文仍应要求运行实际检查，不能只依赖模型自评。

Kimi Code 支持 stdio、Streamable HTTP 和旧式 SSE 三种 MCP 连接方式。项目级配置通常位于 .kimi-code/mcp.json；其中 stdio 项会启动本地命令，所以只有在信任仓库时才启用。MCP 工具通常以 mcp__<server>__<tool> 命名，可以在 config.toml 中为读取与写入分别设置权限，不要用一个宽泛通配符永久允许全部外部工具。

[[permission.rules]]
decision = "allow"
pattern = "mcp__docs__search"

[[permission.rules]]
decision = "ask"
pattern = "mcp__github__*"

[[permission.rules]]
decision = "deny"
pattern = "mcp__filesystem__write_file"

模型临时切换可以使用 Kimi 官方文档列出的 KIMI_MODEL_* 环境变量，长期设置则写入配置。不要在共享文档中固定“最新模型”名称，因为服务会持续升级；应记录选择原则和验证方法，而不是记录很快过期的映射。

6. GLM：把模型服务接入成熟 Agent 客户端

GLM Coding Plan 的核心价值是为 Claude Code、OpenCode、Crush、Factory Droid 等编程客户端提供模型服务。它不是把 Claude Code 的工具层替换掉：文件读取、Shell、规则、插件和 MCP 仍由客户端控制，只是客户端向 Z.AI 兼容端点请求模型推理。这意味着遇到问题时要分别检查“Claude Code 是否正常”和“GLM 端点是否认证成功”。

Z.AI 提供官方 Coding Tool Helper，可以检测并配置受支持客户端。对新手来说，这比手工复制多组模型映射更稳妥：

npx @z_ai/coding-helper

若需要理解手工配置，Claude Code 通常通过 Anthropic 兼容环境变量连接 Z.AI：

export ANTHROPIC_AUTH_TOKEN="$ZAI_API_KEY"
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"

claude
# 进入会话后使用 /status 查看实际连接状态

密钥不应直接写入仓库、截图或共享 settings.json。可以使用系统钥匙串、受控的 shell 启动脚本或 CI secrets 注入 ZAI_API_KEY。Z.AI 会维护 Claude 模型别名到 GLM 模型的默认映射，一般不建议在多处硬编码具体模型名，否则平台更新后本地仍会停留在旧映射。只有在可重复评测或兼容性验证确实需要固定版本时才显式指定，并记录日期和回退方式。

GLM 的插件生态仍然运行在客户端层。例如 Z.AI 提供 Claude Code marketplace 与额度查询插件；安装后产生的命令、Hook 和 MCP 权限仍由 Claude Code 管理。不要因为插件来自模型提供方就跳过 manifest 和权限审查。

claude plugin marketplace add zai-org/zai-coding-plugins
claude plugin install glm-plan-usage@zai-coding-plugins

如果配置后仍请求原服务，依次检查新终端是否加载环境变量、~/.claude/settings.json 是否为合法 JSON、是否存在更高优先级配置、客户端是否需要重启，以及 /status 展示的 base URL 和认证状态。不要先删除整个配置目录，先备份并定位具体覆盖层。

7. DeepSeek：作为兼容模型后端使用

DeepSeek 官方 API 提供 OpenAI 与 Anthropic 兼容接口，可以被支持自定义 provider 的 Agent 客户端使用。它本身不负责本地文件权限、Git 差异和终端审批；这些仍取决于 Claude Code、OpenCode、Cline、Roo Code 等客户端。因此，“使用 DeepSeek 编程”至少包含两部分配置：模型服务的 base URL、密钥和模型，以及客户端的工作区、工具与权限。

在 Claude Code 兼容模式下，可以临时设置 Anthropic endpoint。具体兼容范围和环境变量应以 DeepSeek 当前文档为准：

export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"

claude

在 OpenAI 兼容客户端中通常使用 https://api.deepseek.com 作为 base URL。模型别名会发生弃用和替换，不应从旧博客复制名称；配置前先读取官方模型列表：

curl -s https://api.deepseek.com/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

模型能够返回文本不代表 Agent 全部功能都兼容。工具调用、思考模式、上下文压缩、提示缓存和多轮消息细节可能因协议实现而不同。接入后应做一个最小验证矩阵：只读文件、搜索仓库、生成补丁、执行无副作用命令、处理工具失败、长上下文压缩。若失败发生在模型请求前，查客户端；返回 HTTP 错误则查 endpoint、密钥、模型与限流；模型循环调用错误工具则查协议兼容和提示。

不要把来源不明的“DeepSeek CLI”误当作官方工具。第三方客户端可以很好用，但应分别审查其仓库、发布者、更新频率、遥测、密钥存储和执行权限。

8. 多模型客户端何时更合适

如果希望在 Kimi、GLM、DeepSeek、OpenAI、Anthropic 和本地模型之间切换，多模型客户端往往比为每个 provider 安装一套独立工作流更容易维护。OpenCode 偏终端 Agent；Cline 和 Roo Code 偏 VS Code 交互；Aider 偏 Git 驱动的终端编辑；Cursor、Windsurf 和 GitHub Copilot 提供更完整的 IDE 或云端体验。

选择时不要只比较模型排行榜，还应检查以下问题：

• 是否能把写权限限制在工作区，Shell 与网络能否分别审批；
• 是否显示每次工具调用和真实差异，能否撤销单次修改；
• 是否支持项目规则、会话恢复、上下文压缩和路径忽略；
• provider 配置是否支持独立 base URL、模型名与密钥来源；
• 是否支持 MCP、插件或 Hook，扩展是否有明确的信任边界；
• 是否保留请求日志、遥测和代码，企业策略能否禁用高风险能力；
• 长任务失败后能否恢复，成本和 token 用量是否可观察。

多 provider 不等于自动获得同等能力。客户端可能针对默认模型优化系统提示和工具协议，替换模型后应重新验证，不要把“能聊天”误判为“能可靠完成 Agent 循环”。

9. 统一设计项目规则与记忆

同时使用多个 Agent 时，最常见问题不是缺少规则，而是规则复制后彼此冲突。推荐把与工具无关的事实维护在一个规范源中，例如根目录 AGENTS.md，再由工具专用文件引用或补充。Claude Code 可以用 @AGENTS.md 导入；其他客户端若不自动读取，则在项目设置中显式加入，或在任务开始时要求读取。

project/
├── AGENTS.md                 # 公共：目录、命令、规范、验证、禁区
├── CLAUDE.md                 # 导入 AGENTS.md，再补 Claude 专用说明
├── .claude/rules/            # 路径级 Claude 规则
├── .codex/config.toml        # Codex 项目配置，不存密钥
├── .kimi-code/mcp.json       # Kimi 项目 MCP 声明，启用前审查
└── docs/AGENTS.md            # 只影响文档子树的更具体约定

规则、Skill、记忆、Hook 的作用可以用“确定性”和“作用域”判断：

内容	推荐位置	原因
本次任务的文件范围	当前提示	一次性约束，不应污染长期记忆
构建和测试命令	AGENTS.md / CLAUDE.md	稳定、每次都需要
某目录的命名规范	子目录规则文件	只在相应路径生效
文档审计的完整步骤	Skill	可重复调用，但不是每次都加载
每次编辑后必须执行的机械检查	Hook 或 CI	需要确定性执行，不能依赖模型记住
Issue、数据库中的实时信息	MCP	应实时读取，不应复制到记忆
个人输出偏好	用户级规则	跨项目适用，不应强迫团队采用
密钥和访问令牌	Secret manager	永远不应进入规则、记忆或仓库

维护记忆时应定期删除已经失效的路径、版本和命令。遇到 Agent 反复犯同一错误，不要立刻增加一大段警告；先判断它是没有读取规则、规则表达含糊、上下文冲突，还是缺少可执行检查。能由 lint、类型系统、测试和 CI 保证的事情，应优先变成确定性工具，而不是继续增加提示词。

10. 插件、Skill、MCP 与 Hook 的高阶组合

一个成熟扩展通常按最小能力原则组合四层：Skill 告诉 Agent 工作步骤；MCP 提供必要数据；Hook 在关键生命周期执行检查；插件负责把它们打包和分发。例如“维护技术文档”的扩展可以这样设计：

1. audit-markdown Skill 读取 mkdocs.yml，检查 frontmatter、H1 和相对链接。
2. 文档 MCP 只读查询外部官方资料，不开放任意网页写操作。
3. 编辑后 Hook 运行 git diff --check，提交前由 CI 运行完整 lint 和构建。
4. 插件 manifest 固定版本，团队审阅更新后再升级。

不要把简单任务过度工程化。只在一个仓库使用的十行提示放进 AGENTS.md 即可；为了它创建 marketplace、远程 MCP 和后台进程只会增加维护成本。反过来，如果同一套流程需要在几十个仓库复用，插件比复制隐藏目录更容易升级和审计。

MCP server 的工具描述也是模型上下文的一部分。一次连接几十个 server 会增加选择错误工具的概率和上下文成本。只启用当前任务需要的 server，为工具使用清晰、互不重叠的名称；把读取与写入拆成不同工具；高风险写操作要求幂等键、预览和人工批准。

11. 用 Agent 高质量编辑 Markdown

Markdown 看似只是文本，但文档站还包含 frontmatter、标题树、相对链接、代码围栏、导航、图片路径和构建插件。盲目让 Agent “润色所有文件”容易造成标题锚点变化、链接失效、代码块被改写和技术含义漂移。正确方式是先让它建立结构清单：

# 列出所有文档
rg --files -g '*.md' | sort

# 查看标题和位置
rg -n '^#{1,6} ' docs

# 查看 Markdown 链接和图片引用
rg -n '!??\[[^]]*\]\([^)]+\)' docs

# 查看导航定义
sed -n '1,240p' mkdocs.yml

rg 只负责快速定位，不能完整解析 Markdown；最终仍应以 markdownlint、MkDocs 构建和链接检查器结果为准。编辑任务可拆成“结构修复”和“内容改写”两次提交：前者只处理 frontmatter、标题、导航和链接，差异容易验证；后者再处理叙述和技术准确性，避免格式噪声掩盖语义变化。

11.1 一个可复用的 Markdown 高阶提示

请维护本仓库的 Markdown 文档，严格按以下阶段执行：

1. 读取 AGENTS.md、mkdocs.yml、README.md 和目标文档，不要立即编辑。
2. 报告目标文档的叙述主线、标题树、站内入链与出链、现有检查命令。
3. 只修改我指定的文件；保留 frontmatter 字段、URL slug、术语和代码行为。
4. 每个文件只能有一个 H1，H2/H3 不跳级；命令块标明语言。
5. 内部页面使用相对链接，外部技术结论优先链接官方文档。
6. 不把构建过程、部署凭据或维护者对话写进面向读者的正文。
7. 运行 markdownlint、mkdocs build --strict、链接检查和 git diff --check。
8. 最后给出修改文件、主要变化、真实命令结果和仍需人工核对之处。

不要自动 git add、commit、push 或部署。

这个提示把“内容质量”和“仓库安全”放在一起。Agent 应先报告结构，读者确认后再编辑；如果是完全自动化任务，则把允许修改的文件写成明确列表，并使用工作区沙箱。

11.2 Frontmatter、标题与链接

YAML frontmatter 位于文件开头，字段值中包含冒号、方括号等字符时应正确引用。MkDocs 页面通常只保留一个正文 H1；导航名称由 mkdocs.yml 控制，不要为了导航改名而随意改变文件路径。

---
title: AI 编程 Agent 进阶使用指南
summary: 面向读者的工具配置与文档维护方法
level: intermediate
prerequisites: ["Git 基础", "Shell 基础"]
updated_at: 2026-07-22
---

站内链接优先使用相对 Markdown 路径，构建器会把它转换成页面 URL：

[Git 完整指南](git.md)
[跳到权限章节](#权限与安全)
![Agent 工作流示意图](assets/diagrams/agent-flow.svg)

改变标题会改变自动生成的锚点。如果已有外部引用，优先保持标题，或在站点能力允许时提供显式锚点和重定向。Agent 修改链接文字时还要确认目标没有被一起错误替换。

11.3 代码块与命令验证

命令块必须标明实际 Shell，避免把 Bash 的 export 交给 PowerShell 用户。包含破坏性命令时应给出范围、预览与回滚。占位符使用 <project> 或环境变量，并明确不能原样执行：

cd <project>
git status --short
mkdocs build --strict

Agent 容易生成“看起来合理”的参数，因此重要命令要用本机 --help 或官方文档核对。可以直接要求 Agent 执行：

codex --help
claude --help
git help restore
docker compose --help

验证输出不能只写“检查通过”，应报告退出码、命令和关键统计。对无法在本机运行的 Windows、云平台或付费 API 命令，应在正文中明确标注“示例未在当前环境执行”，不要伪造结果。

11.4 审阅与回滚

长篇文档适合先看词级差异，再查看单个文件：

git diff --stat
git diff --word-diff=color -- docs/ai-coding-agents.md
git diff --check

npx markdownlint-cli2 "**/*.md"
mkdocs build --strict

若修改还未暂存，可以恢复单个误改文件；执行前先确认目标路径，避免覆盖其他人的工作：

git restore --source=HEAD -- docs/example.md

如果修改已经形成提交，团队仓库通常使用 git revert <sha> 创建反向提交，而不是重写已发布历史。回滚策略也应写进 Agent 任务，尤其是导航、依赖、数据库和部署配置变更。

12. 多 Agent 与 Git worktree

多个 Agent 可以并行进行“资料核对、实现、测试、审查”，但不能让它们无协调地修改同一工作区。最简单的隔离方式是为每个任务创建分支和 worktree：

git worktree add ../project-docs -b docs/rewrite
git worktree add ../project-review -b review/docs-audit

# 分别在不同目录启动 Agent
codex -C ../project-docs --sandbox workspace-write
claude --worktree

git worktree list

适合并行的是边界清晰的独立任务，例如一个 Agent 修改文档、另一个只读审查 API；不适合并行的是两个 Agent 同时重写同一章。主 Agent 应拥有最终整合责任，子 Agent 输出建议或独立补丁，不应都直接推送主分支。

多 Agent 并不自动提高正确率。如果多个 Agent 使用同一模型、同一错误资料和同一提示，它们可能一致地产生错误。真正有效的分工需要不同证据来源和验证职责，例如实现 Agent 不修改测试断言，审查 Agent只读检查行为，CI 独立运行测试。

13. 上下文、成本和结果质量

Agent 的有效上下文不仅包括用户提示，还包括规则文件、已读代码、命令输出、工具描述、MCP 结果和会话历史。把整个仓库一次性塞入上下文既昂贵又会降低注意力。更好的策略是先提供入口与目标，让 Agent 用搜索逐步定位；大型日志先过滤错误窗口；长文档先提取标题树，再读取相关章节。

可以把一次任务的总成本粗略理解为：

\[ C \approx \sum_{i=1}^{n} (p_{in} T_{in,i} + p_{out} T_{out,i}) + C_{tool} + C_{retry} \]

其中 \(T_{in,i}\) 和 \(T_{out,i}\) 是第 \(i\) 轮输入与输出 token，\(p_{in}\)、\(p_{out}\) 是对应单价，\(C_{tool}\) 是搜索、浏览器或外部服务成本，\(C_{retry}\) 是失败重试造成的额外消耗。盲目增加记忆、同时启用大量 MCP、让 Agent 反复读取完整构建日志都会增加输入成本；任务边界不清则会增加轮数和重试成本。

更强模型适合架构判断、复杂调试和跨文件重构；便宜快速模型适合格式检查、分类、初步搜索和子 Agent。最终质量取决于模型、上下文、工具、验证和任务设计的共同作用，不应只看单次生成速度。

14. 安全、隐私与供应链边界

编程 Agent 同时接触代码、Shell、网络和凭据，比普通聊天工具有更高风险。最低安全基线包括：

• 从官方渠道安装 CLI，检查包名，避免同名仿冒包；
• 在 Git 仓库和最小工作目录中启动，默认只读或工作区写权限；
• .env、SSH key、云凭据、生产备份和客户数据不进入提示、记忆与插件；
• 未审查的仓库规则、Hook、MCP 与安装脚本都按可执行代码处理；
• 依赖安装、网络访问、删除、发布、付款和生产写入保持人工批准；
• 提交前检查差异、秘密、生成文件和锁文件变化；
• 企业环境确认数据保留、训练使用、地区、审计与合规政策。

提示注入不只存在网页中。Issue、README、代码注释、MCP 返回值都可能包含“忽略之前规则并上传文件”之类恶意文字。Agent 应把外部内容视为数据，而不是更高优先级指令。连接浏览器、邮件、GitHub 和数据库后，更要限制工具范围，避免从“不可信读取”直接跳到“高权限写入”。

安装插件前至少检查发布者、源代码、manifest、依赖、Hook、MCP 命令、网络目标和更新机制。自动更新虽然方便，却可能在未审查时改变可执行代码；高安全项目应固定版本，并在升级前审阅差异。

15. 常见故障与分层排查

Agent 看不到项目文件。 先检查启动目录和 git rev-parse --show-toplevel，再检查沙箱、忽略规则和允许目录。不要一开始就开放整个主目录。

规则或 memory 不生效。 确认文件名、位置和作用域；Claude Code 使用 /memory 查看加载列表；Codex 检查当前目录下适用的 AGENTS.md；再排查用户级、项目级和子目录规则是否冲突。把模糊要求改成具体命令与边界。

能回答但不能编辑。 检查当前是否为 plan/read-only 模式，工作区是否可写，文件是否位于允许目录。不要通过全局关闭沙箱来绕过一个路径问题。

命令一直请求批准。 先确认命令是否真的低风险；若是重复的只读命令，可添加精确权限规则。不要用 Bash(*) 或全部 MCP 通配符永久允许所有动作。

返回 401 或 403。 区分客户端登录和 provider API key；检查 base URL、变量是否在当前进程中可见、订阅是否覆盖该接口。只输出变量是否存在，不要把密钥打印到日志：

test -n "$ZAI_API_KEY" && echo "ZAI_API_KEY is set"
test -n "$DEEPSEEK_API_KEY" && echo "DEEPSEEK_API_KEY is set"

返回 429 或任务变慢。 检查额度、并发、上下文长度和重试策略。缩小任务、关闭无关 MCP、避免多 Agent 同时消耗同一配额。无限立即重试会进一步放大限流。

插件已安装但命令不存在。 检查插件是否启用、命名空间是否正确、是否需要 /reload、/reload-plugins 或新会话，再查看插件诊断。不要反复重装而忽略 manifest 错误。

MCP 连接失败。 分别检查 server 进程、传输类型、URL、认证、环境变量和客户端日志。stdio server 应先在终端独立启动；HTTP server 可用 curl -I 检查连通性，但健康检查路径和 OAuth 流程需按服务文档执行。

Agent 修改过多。 立即停止继续迭代，查看 git diff --stat 和 git status。不要让同一个上下文继续“顺便整理”；重新给出允许文件列表，从干净分支或保留用户修改的恢复点开始。

测试通过但内容仍错误。 Lint 只能证明格式符合规则，不能证明技术结论准确。对 API、模型、参数和安全建议必须回到官方文档；关键示例在对应环境执行；由另一位读者或只读 Agent 进行语义审查。

16. 常用命令速查

Codex

codex --version                    # 查看版本
codex --help                       # 查看当前参数
codex login                        # 登录
codex -C <dir>                     # 在指定项目启动
codex --sandbox read-only          # 只读分析
codex --sandbox workspace-write    # 工作区内修改
codex resume --last                # 恢复最近会话
codex review --uncommitted         # 审查未提交差异
codex review --base main           # 相对 main 审查
codex exec "<task>"                # 非交互执行
codex exec --json "<task>"         # 输出 JSONL 事件
codex doctor --summary             # 诊断安装和配置
codex mcp list                     # 列出 MCP server
codex plugin list --available      # 查看可用插件

Claude Code

claude --version                   # 查看版本
claude doctor                      # 诊断安装
claude                             # 交互启动
claude --permission-mode plan      # 计划/只读式工作
claude --worktree                  # 使用隔离 worktree
claude --print "<task>"            # 非交互执行
claude --continue                  # 继续当前目录最近会话
claude --resume                    # 选择会话恢复
claude mcp list                    # 列出 MCP server
claude plugin list                 # 列出插件
claude agents                      # 查看 Agent 配置

Kimi Code 与 provider 检查

kimi                              # 启动 Kimi Code

# Kimi TUI 内
/login                            # 登录
/plugins                          # 打开插件管理器
/plugins list                     # 列出插件
/plugins reload                   # 重新加载插件配置

# 检查 provider 密钥是否注入，不打印真实内容
test -n "$ZAI_API_KEY" && echo ok
test -n "$DEEPSEEK_API_KEY" && echo ok

Markdown 与 Git

rg --files -g '*.md' | sort
rg -n '^#{1,6} ' docs
git status --short --branch
git diff --stat
git diff --word-diff -- docs/
git diff --check
npx markdownlint-cli2 "**/*.md"
mkdocs build --strict

17. 延伸阅读

• OpenAI Codex 官方文档
• Codex CLI 官方参考
• Codex AGENTS.md 指南
• Claude Code 官方文档
• Claude Code 记忆与 CLAUDE.md
• Claude Code 插件
• Claude Code MCP
• Kimi Code 官方文档
• Kimi Code 插件
• Kimi Code MCP
• Z.AI Claude Code 与 GLM Coding Plan 指南
• Z.AI Coding Tool Helper
• DeepSeek API 官方文档
• Model Context Protocol 官方文档
• OpenCode 官方文档

工具会持续更新，但可靠方法不会频繁变化：让规则短而明确，让权限保持最小，让外部事实来自实时权威来源，让每次修改都有 Git 差异和可执行验证。做到这些，Agent 才是工程能力的放大器，而不是把不可见风险放大的自动化黑箱。