AI Coding CookBook

AI Coding CookBook

目录

本文是一份面向开发者的 AI 编程工具实战手册，覆盖四大主流工具（OpenCode、Claude Code、Copilot、Cursor）的安装配置与常用指令，梳理了 AI Coding 的四大核心能力（Agent、MCP、Skill、工作流编排），简要解析了 Agent 五项底层概念与原理（Harness、RAG、ReAct、Function Calling、A2A），并提供了 CC Connect 远程连接的完整配置指南。适合 AI Coding 入门者和需要快速查阅配置细节的 AI Coder。

1 AI 工具介绍

本篇将介绍四种常用 AI 工具，能够覆盖 当前大部分主流 AI Coding 场景，帮助阅读者快速查询 AI 工具的安装及其用法。

1.1 OpenCode

一款开源、开放，新手友好且可定制化程度高的 AI 编程工具，可自定义接入各种模型，且对于多种模型都有一定优化。支持MCP，Agent 以及 Skill 等特性，打造高度定制化的专属工作流。

1.1.1 安装与启动

  1. 安装 Node.js，地址：nodejs.org/zh-cn/download
  2. 使用 npm 安装 opencode：npm i -g opencode-ai
  3. 命令行执行 opencode 或者 opencode web 启动
  4. Set-ExecutionPolicy Unrestricted 设置win终端运行PowerShell

如果有 chocolate，也可以使用：choco install opencode

1.1.2 常用指令速查

/init：让 opencode 了解当前项目，并记在一个 md 里面

/models：切换模型。opencode 内置免费模型

/new：创建新对话

/sessions：列举所有对话

/share：分享当前对话 /unshare 取消

/export：将对话导出

/timeline：状态回溯

TAB：切换主 Agent（Plan/Build 模式就是主 Agent）

/undo&/redo：撤销&重试 AI 制造的修改

/connect：连接 LLM API，交互式引导

/skills：查看当前所有安装的 skill

/mcps：查看当前所有安装的 MCP

/compact：压缩上下文。把之前的对话压缩为一个简单的摘要

/themes：切换 opencode 外观配色

/editor：使用外部编辑器编辑对话，需要配置环境变量

/variant：切换模型的变量（low/high/max 等），类似于 Claude Code 的 /effort

/agents：切换 Agent

/rename：对话改名

Ctrl + T：快速切换模型变量

!：进入命令行模式

@：指定文件

Ctrl + X ：进入 agent 浏览模式，按 ↓ 进入第一个子 agent 的对话，按 →/← 在子 agent 之间切换，按 ↑ 返回到主 agent 对话

1.1.3 接入模型

/connect 交互式配置，相关配置会存储在 ~/.local/share/opencode/auth.json 中：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

详细可参考 https://opencode.ai/docs/zh-cn/providers/

1.1.4 OpenCode 能力扩展

1. Skills 配置
点击查看代码

项目级 skill 安装地址 .opencode/skills/<技能名>

全局 skill 安装地址 ~/.config/opencode/skills/<技能名>

将 Skill 文件放到对应的目录下，即可加载 skill。此外，opencode 也支持自动导入 Claude Code 的 skill，无需额外迁移。

2. MCP 配置

参考 OpenCode 官方文档 - MCP

修改文件  ~/.config/opencode/opencode.json

本地：

通过在 MCP 对象中将 type 设置为 "local" 来添加本地 MCP 服务器。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

例如，以下是添加测试用的 @modelcontextprotocol/server-everything MCP 服务器的方法。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

要使用它，可以在提示词中添加 use the mcp_everything tool：use the mcp_everything tool to add the number 3 and 4

远程：

通过将 type 设置为 "remote" 来添加远程 MCP 服务器。url 是远程 MCP 服务器的地址，通过 headers 选项可以传入一组请求头。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}
3. 自定义指令

在 ~/.config/opencode/ 下创建 commands 目录，在目录下即可通过 .md （或者在 json 配置文件中进行添加）自定义指令，详细参考 OpenCode 官方文档 - Commands

创建指令描述文件 test.md：

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

运行 /test 即可执行该指令

4. 自定义智能体

在 ~/.config/opencode/ 下创建 agent 目录，详细定义方式参考 OpenCode 官方文档 - Agents

智能体分为 primary 或者 subagent，前者用于前台模式按 <TAB> 切换，后者只能在后台由 AI 调度

创建 review.md，即可创建一个名为 @review 的智能体

<!-- .opencode/agent/code-reviewer.md -->
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

其中 --- 所包裹的部分是 YAML 标记，其余部分是 Prompt 部分。也可以直接在配置文件中添加这个agent：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

此外，OpenCode 也提供了专门创建 agent 的指令：

opencode agent create

该指令会交互式引导使用者创建 agent，并生成对应的 md 文件

除了内置的 Plan / Build agent，通常建议还可以定义：

  • Review：具有只读访问权限和文档工具的代码审查
  • Debug：专注于问题排查，启用 bash 和读取工具
  • Docs：文档编写，具有文件操作但不使用系统命令

1.2 Claude Code

一款强大、精确，为 Claude 大模型而生的 AI 编程工具，价格昂贵但是适合执行高复杂度的专业编码工作，返工率低。和 OpenCode 一样支持各种能力接入。也可接入其他模型，对于模型性能有一定提升。

1.2.1 安装与启动

1. 使用 npm 进行安装：npm i -g @anthropic-ai/claude-code
2. 安装 CC Switch (建议让 AI 代劳)
3. 在 ~/ 目录下创建 .claude.json
4. 在 CC Switch 中添加大模型 API
5. 执行 claude 启动

.claude.json 文件内容：

{
    "hasCompletedOnboarding": true
}

1.2.2 常用指令速查

常用指令大体上与 OpenCode 差异不大，此处仅列举有差异的部分：

/resume：继续之前的某段对话，类似于 opencode 中 /sessions 的作用

/clear：新开对话，等价于 opencode 的 /new

/context：用于查看上下文信息及其使用情况

Shift + <TAB>：切换 Agent 模式

/agents：创建 & 管理 Agent

/effort：调整模型思考力度

Ctrl+G：使用编辑器编辑对话

/btw：临时对话

/simplify：代码优化

/memory：查看记忆文件，也可以用于开启/关闭 auto memory

/rewind：回滚&撤销，类似于 OpenCode 中的 /timeline 和 /undo

/plugins：插件管理（所谓插件，即一些 Skill，MCP，CLI，Hook 以及 Agent 等构成的集合包）

/background：将当前对话后台化

/schedule：创建定时任务

←（空输入时）：从当前 Session 退到 Agent View，查看所有 session 的工作状态

→ / Enter：进入某个 Session 查看完整对话

Space：快速预览该 Session 的最新输出或问题，无需进入

Ctrl+X：删除某个 agent

启动 claude 时添加 --dangerously-skip-permissions：有完全编辑权限，一路绿灯不做确认

1.2.3 Agent 特性

创建方式：使用 /agents 进行创建 & 管理。

Agent View：claude agents 启动监控面板，查看所有后台 agent 和 subagent 执行状态，用户可中途介入。OpenCode 以主 Agent 对话为单位进行操作、子 agent 只读，而 CC 可同时管理和介入所有 agent 对话。

进入/退出方式：空输入时按 ← 进入，CLI 中 claude agents 启动，Esc 关闭面板回 Shell。使用 → 进入 agent 后不要用 /resume（会创建新对话），退出用 ← 而非 /exit（会终止 session），仅查看状态用 Space。

页面布局：needs input（等待回复）、working（进行中）、completed（已完成），底部输入框可派发新任务。

Dynamic Workflows：通过 JS 脚本编排大批量 subagent 实现交叉验证，适用于大规模、标准化、长流程场景。ultracode/workflow 关键字触发编排，内置 /deep-research 工作流。/workflow 查看运行状态，可保存为命名工作流后通过 /[名称] 直接调用。

其他能力：

  • Hooks：在 CC 执行生命周期节点自动执行 shell 命令
  • Memory：自动维护 MEMORY.md 记录项目关键信息（~/.claude/ 目录）
  • Skill：通过 /[skill名称] 显式调用
  • 后台启动：claude --bg "[提示词]"
  • Work tree 隔离：agent 各自在独立 git 分支工作
  • Subagent 记忆：自动记录跨会话关键信息
  • 定时任务：/schedule 创建定期自动执行
  • StatusLine：自定义状态栏信息显示

1.3 Copilot

一款 IDE AI Coding 对话插件，按 对话次数 计数（即使是一次复杂任务也是按一次对话的钱收费），量大管保，价格实惠，且第一时间接入最新模型。订阅套餐后可以无限使用基础模型 & 自动补全，原生集成 Github，使用便捷。前端能力较差，比较适合后端业务逻辑实现。

注： 2026-06-01 起，Copilot 已更新为按 Token 计费

核心用法（VSCode）

特性 作用 使用要点
TAB 补全 实时预测编写内容，按 Tab 即可补全 1. 先写注释，然后按下 TAB 补全
2. 在注释中引入其他文件，可以让自动补全感知相关文件的内容
Inline Chat 在代码行中启动 AI 对话 1. Ctrl + I 开启
2. 适合小范围修改
Chat 面板 Copilot 的 AI Coding 对话框，支持多种对话模式 1. Ctrl + Shift + I 开启
2. 工作区内所有文件都对 Chat 可见，也可以专门手动指定文件
3. Ask：纯对话，不写代码；Agent：自主读写文件，运行 CLI 命令，自闭环工作；Plan：用户反复确认要点，使用子 Agent 采集信息，输出完整的计划。Plan 完成后点击 start implementation 会切换到 Agent 模式执行
4. 各个模式的各种权限也可以手动开启 or 关闭
Skills Copilot 对于 Skill 的支持 1. 设置项搜索 userAgentSkills 即可找到 skill 配置
2. 可在指定的 skill 目录下添加 skill
3. 支持自定义 skill 目录（复用 opencode，claude code 已有 skill）

智能体类型

新版 Copilot 提供了多种智能体模式供选择，以适应不同的工作场景：

image-20260618010914508

模式 作用
本地模式 默认对话模式，实时对话，实时与ai协作
背景模式 在后台运行任务，只支持agent，适合不需要交互的长时间后台任务
云模式 选择远程仓库，跑在github上，脱离本地环境
claude模式 使用claude的sdk，拥有claude code的特性，token计费依旧遵循copilot

修改建议

OpenCode 和 Claude Code 是终端 Agent，默认直接写文件，改完再 /undo 。Copilot/Cursor 这样的 IDE Agent 多了一层显式确认。Agent 改完先展示修改建议 Diff，直到用户点击 Accept 后才生效，真正落盘。这对 IDE 用户更安全，但多一个操作步骤，如果不接受重新开对话或者关闭聊天，没有落盘的改动会直接丢失。

1.4 Cursor

是目前最强大的 AI IDE 之一，订阅制，价格比 Copilot 更高，执行精准，适合大型复杂项目代码编写以及维护，属于 Copilot 的上位替代。

核心用法类似于加装了 Copilot 的 VSCode（指定工作区/工作文件夹，选择模型&Agent模式，修改建议等），但是页面更加聚焦于 AI 编码，仅包含 AI Chat 区和代码编辑区。代码编辑区可添加 浏览器 / Git / 终端 / 画布（PR review、文档） 页面。

智能体能力（Shift + TAB 做切换）

模式 作用
Debug 用运行时证据查 bug。分析日志，引导复现 bug，完成偶现问题修复
Ask 只读模式。适合理解代码、回答问题、做架构分析，不会改文件、不会跑会改系统的命令
Plan 在写代码之前，先调研代码库、提澄清问题，并输出可审阅的实现计划（Plan 默认保存在用户目录，可 Save to workspace 放到项目里供团队共享）
Multitask 让 Cursor 同时启动多个异步 subagent，而不是把任务排队串行执行

2 AI Coding 核心能力

本章覆盖 AI 编程工具的四大核心构建块：Agent（自主决策-行动闭环）、MCP（外部能力接入协议）、Skill（按需加载的领域知识包）、以及工作流编排。这些概念共同构成了 AI Coding 工具的能力骨架。

2.1 AI Agent

智能体：能感知环境并自主采取行动以实现特定目标的实体或系统。即界定是否是 Agent 的核心在于是否拥有 自主感知-决策-行动 的闭环

               ┌──────────────┐
  感知 ──────▶ │              │ ──────▶ 行动
 (读文件/上下文) │    Agent     │ (写文件/执行命令)
               │              │
               └──────┬───────┘
                      │
                  自主决策
             (不依赖每一步人工确认)

一些常见的名为 Agent 的名词辨析：

Agent（学术概念）
  │
  └── 编程 Agent（整个产品）
        │   例: OpenCode / Claude Code / Codex
        │
        ├── 名为 Agent 的模式
        │     例: Cursor Agent mode / Copilot agent mode
        |		在 Agent 模式下能够查看，分析，编辑项目文件
        │     本质: 自主程度的开关
        │
        ├── Agent 的工作模式
        │     例: OpenCode 自定义 agents: { "code-reviewer": {...} }
    	|		Plan/Build Agent 切换
        │     本质: 角色和权限的限定
        │
        └── SubAgent
              例: 用于搜索 / 分析 / 执行的 sub-agent
              本质: 任务分解和并行执行

Agent 工具核心能力

  • 工具调用：打破次元壁，直接操作文件 & 系统；通过工具提升工作效率
  • ReAct（观察-推理-执行循环）：完成工作自闭环
  • 上下文管理（上下文窗口，上下文压缩）：解决模型上下文窗口限制问题
  • 多智能体（拆分任务，多subagent执行）：并行工作以提效；子 agent 上下文独立，避免主 agent 上下文窗口过长；避免污染主 agent 上下文窗口

Agent 工作流嵌套

对于 CC 或者 OpenCode，可以在 agent 定义的 prompt 里通过 @ 指定子 agent 进行工作，例如：

同时执行：1. 使用 @search-online 联网搜索关键信息；2. 使用 @search-project 检索项目代码

2.1.1 OpenCode 自定义 Agent

完整文档参考 代理 | OpenCode

Opencode 支持针对特定工作场景配置专有 agent，通过手动设定 Agent 提示词，指定 LLM 模型，限定访问权限来实现。可通过前台使用 TAB 进行 agent 切换（主 agent），或者在提示词中显式使用 @ 进行指定（子 agent）。

1. OpenCode 内置 Agent

主 Agent：定义为 primary， 运行在前台，使用 TAB 进行切换，内置的 Build / Plan 即为主 Agent；

子 Agent：定义为 subagent，主 Agent 会在后台对其进行调度，使用 @ 显式指定，OpenCode 内置了 general / explore / scout。

内置 Agent 一览：

名称 模式 是否可显式调用 作用
Build primary 是 能够完全进行文件操作和调用命令&工具，标准 Agent
Plan primary 是 只读不改，适用于列计划 & 问题咨询的 Agent
General subagent 是 后台开启一个名为 general 的子 agent，context 独立，得到结果后返回给主 agent。有读写和调用工具的权限，适合研究复杂问题和并行执行多步骤任务
Explore subagent 是 后台开启一个子 agent，只读不写，适合文件查找、代码搜索
Scout subagent 是 后台开启一个子 agent，只读不写，用于查看搜索三方依赖（即本项目之外）源码。该模式下会把三方源码拉到 OpenCode 内部缓存中，不会污染项目代码本身
Compaction primary 否 自动进行上下文压缩
Title primary 否 自动生成对话标题
Summary primary 否 自动生成对话摘要
2. Agent 配置详解

OpenCode 中 agent 的自定义方法可以参考 AI 工具篇 – 让 OpenCode 更强 – 自定义智能体，这里主要对配置项进行解释：

配置项 作用 详细解释 例子（md 风格，json 同理）
description 描述 agent 的使用场景 & 适用场景 略 description: 从是否是最优实现以及是否存在潜在问题的角度 review 代码
prompt 为 agent 指定自定义的系统提示词 该字段的 value 对应的是提示词具体路径。不过在 *.md 定义的 agent 中，提示词一般是直接写在文件中，和配置信息用 --- 分隔开，不需要额外再用一个文件定义提示词 prompt:
mode 指定 agent 模式（主 agent 还是子 agent） primary：主
subagent：子
all：主、子都可以是
（不指定默认是 all）		 略
model 指定该 agent 使用的 LLM OpenCode 配置中的模型 ID 使用 provider/model-id 格式 model: anthropic/claude-haiku-4-20250514
model: opencode/gpt-5.1-codex（OpenCode Zen 套餐）
temperature 控制 LLM 推理的随机性和创造力 较低的值确定性更高，较高的值创造力更强。
0.0-0.2：适合代码分析和规划
0.3-0.5：适合一般开发任务
0.6-1.0：适合头脑风暴和探索		 略
tools 指定该 agent 工具使用能力 通过将特定工具设置为 true 或 false 来启用或禁用它们。还可以使用 通配符 同时控制多个工具，例如：mytools_* 可以匹配所有以 mytools 开头的工具 tools:
write: false
edit: false
bash: false
permission 用于指定各工具时的权限 权限类型：ask（需要审批），allow（无需审批，直接执行），deny（该工具禁用）
多层级结构，除了直接指定工具的权限，还可以进一步细化权限定义，例如对于 bash 操作。可以定义各个命令的权限，且支持 * 和 ~ 这样的通配符
更多细节详见 权限 - OpenCode		 指定所有工具权限：
permission: ask

指定各个工具的权限：
permission:
edit: deny
bash: allow
webfetch: deny
permission.bash 用于指定 CLI 命令的权限 属于 permission 下的子项，配置项 key 为命令或者基于通配符定义的命令集，value 为 权限类型 permission:
bash:
"*": ask（所有命令先设置为 ask 权限）
"git diff": allow
"git log *": allow
"grep *": allow
permission.task 用于指定 agent 在使用 task 工具时可以调用哪些 subagent 类似 permission.bash，但是配置项的 key 为 subagent 名或者基于通配符定义的 subagent 集 permission:
task:
"*": deny
"orchestrator-*": allow
"code-reviewer": ask
hidden 指定是否在 @ 显示调用中隐藏该 subagent 开启后 subagent 只对 AI 工具可见，对用户不可见 mode: subagent,
hidden: true
disable 指定是否禁用该 agent 如果暂时不想使用这个 agent 又不想删除其实现，可通过该配置进行禁用 disable: true
steps 指定 agent 推理时的最大迭代次数 如果不进行限制，agent 将持续迭代，直到模型选择停止推理或者用户手动中断。
有了该配置项的限制，在达到最大迭代次数后 agent 会收到一个系统提示词，直接回复当前推理结论，从而对成本进行控制		 略
color 定义 agent 在 TUI 中的显示颜色 value 为十六进制的 RGB 颜色，例如 #FF5733
也可以使用预设主题颜色，例如：primary、secondary、accent、success、warning、error、info		 略
top_p 控制 LLM 推理的多样性 和 temperature 不同，top_p 是直接定义了 token 候选池。默认是 1.0，填写范围 0.0 ~ 1.0，值越低确定性越高。
通常搭配 temperature 使用。例如：高 temp 低 p → 创造性强，但是只保留最高质量的 token，其余的直接丢弃		 略
LLM 内置选项 由 LLM 提供，在 agent 配置中的用法与其他配置项类似 查阅 LLM 官方文档了解配置项内容及其能力。例如 OpenAI 的模型提供了 reasoningEffort、textVerbosity 等配置项 参考三方文档
3. 官方文档中的有用示例

docs-writer.md – 文档编写 agent

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

security-auditor.md – 安全审计 agent

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

2.1.2 Claude Code Agent

Claude Code（以下简称 CC） 的 Agent 在定义格式上与 OpenCode 有一定差异，但是在配置以及能力层面有一定区别。

OpenCode 有 CC 没有的配置项：top_p, temperature, hidden, permission（CC 用的是 tools 黑/白名单）, mode（CC 默认子 agent）

CC 特有配置项：

配置项 作用 详细解释 例子（md 风格，json 同理）
name 指定 agent 名称 OpenCode 以文件名指定，CC 可以通过这个字段指定 略
tools 工具白名单 OpenCode 的 tools 是 key-value 风格，CC 是 list 风格 tools: [Read, Bash]
disallowedTools 工具黑名单 字面意思 disallowedTools: [Write]
maxTurns 最大迭代次数 OpenCode 中叫 steps 略
isolation subagent 设置分支隔离 设置成 worktree ，可在临时 git worktree 中运行 subagent，为其提供存储库的隔离副本 isolation: worktree
background 指定该 subagent 是否运行在后台 设置为 true 以始终将此 subagent 作为 background task 运行。默认：false 略
memory 指定该 agent 记忆能力 指定为 user、project 或 local，启用跨会话学习 略
effort 推理强度 可指定为：low / medium / high / xhigh / max 略
mcpServers 指定可用 MCP 服务 略 mcpServers: [...]
hooks 指定该 subagent 使用的 lifecycle hook 略 hooks:
skills 预装 skills 略 skills: [...]
initialPrompt 自动提交初始会话 当此代理作为主会话代理运行时，自动提交为第一个用户轮次，前置于任何用户提供的提示 略

2.1.3 工作流编排

对于多 agent 工作流构建，除了使用 AI 编程工具自身提供的能力，还可以使用更加灵活的方式自定义工作流，这里以 OpenCode 为例。

Step 1：Agent 定义

// opencode.jsonc
{
  "agent": {
    "architect": {
      "description": "需求拆解与架构设计",
      "model": "openai/gpt-5.5",
      "prompt": "你是系统架构师。分析需求文档，输出模块划分、数据流、接口定义。",
      "tools": { "write": true, "edit": true, "bash": false }
    },
    "ui-designer": {
      "description": "UI 截图生成",
      "model": "openai/gpt-5.5",
      "prompt": "根据架构设计生成前端界面的自然语言描述，调用 banana 工具生成截图。",
      "tools": { "write": false, "bash": false },
      "mcp": ["banana-image-gen"]
    },
    "frontend-dev": {
      "description": "前端实现",
      "model": "openai/gpt-5",
      "prompt": "根据 UI 截图和架构设计实现前端代码。",
      "tools": { "write": true, "edit": true, "bash": true }
    },
    "planner": {
      "description": "技术执行方案生成",
      "model": "deepseek/deepseek-v4-pro",
      "prompt": "根据架构设计生成分步骤的技术执行方案，包括技术栈、文件结构、实现顺序。",
      "tools": { "write": true, "edit": true, "bash": false }
    },
    "researcher": {
      "description": "技术调研与方案修正",
      "model": "google/gemini-2.5-pro",
      "prompt": "根据技术方案搜索最新文档和源码参考，修正方案中的过时或错误部分。",
      "tools": { "write": true, "bash": false, "web_search": true }
    },
    "coder": {
      "description": "代码编写与调试",
      "model": "alibaba/qwen-3.7-max",
      "prompt": "严格按照技术方案编写代码，运行测试直到通过。",
      "tools": { "write": true, "edit": true, "bash": true }
    },
    "reviewer": {
      "description": "代码审查与闭环",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "审查代码质量、安全性和方案一致性。如有问题，输出具体修改指令给 coder 修复。",
      "tools": { "write": false, "edit": false }
    }
  }
}

Step 2：编排命令

<!-- .opencode/commands/workflow.md -->
---
description: 多 Agent 流水线：需求 → 架构 → UI → 技术方案 → 编码 → 审查
agent: architect
---

请按以下阶段依次执行，每阶段完成后将产物保存为文件，下一阶段读取文件继续：

**阶段 1 - 需求拆解**（使用 agent:architect）
读取需求文档 $ARGUMENTS，输出架构设计到 `docs/architecture.md`

**阶段 2 - UI 设计**（使用 agent:ui-designer）
读取 `docs/architecture.md`，设计 UI 界面。如果有 Banana MCP 工具，生成截图保存到 `docs/ui/`

**阶段 3 - 前端实现**（使用 agent:frontend-dev）
读取 `docs/architecture.md` 和 UI 截图，实现前端代码

**阶段 4 - 技术方案**（使用 agent:planner）
读取 `docs/architecture.md`，生成 `docs/tech-plan.md`

**阶段 5 - 调研修正**（使用 agent:researcher）
读取 `docs/tech-plan.md`，搜索最新文档，修正方案

**阶段 6 - 编码**（使用 agent:coder）
读取 `docs/tech-plan.md`，编写代码并通过测试

**阶段 7 - 审查闭环**（使用 agent:reviewer）
审查代码。如有问题，输出修复指令，返回阶段 6 让 coder 修复，直到通过。

Step 3：执行

在 opencode 中执行

/workflow docs/requirements.md（需求文档地址）

也可以将 Step 2 & 3 脚本化，自动化程度更高：

param($reqDoc)

opencode run --agent architect "读取 $reqDoc，输出架构设计到 docs/architecture.md"
opencode run --agent planner "读取 docs/architecture.md，生成 docs/tech-plan.md"
opencode run --agent researcher "读取 docs/tech-plan.md，搜索修正"
opencode run --agent coder "读取 docs/tech-plan.md，实现代码"

do {
    opencode run --agent reviewer "审查代码"
    $result = Read-Host "审查通过? (y/n)"
    if ($result -ne 'y') {
        opencode run --agent coder "根据审查意见修复代码"
    }
} while ($result -ne 'y')

2.2 MCP

MCP（Model Context Protocol）即 模型上下文协议，基于这套协议开发的服务又叫 MCP Server。一个 MCP Server 本质上就是一段 Python 或者 Node.js 代码，是将外部能力接入 AI Agent 的标准工具箱。

MCP 和内置工具一样，被 agent 所调用，不过相比于 tools，MCP 可以理解为是一个外部重型工具。

使用方式：在 prompt 中 按名称指定 MCP 使用

2.2.1 OpenCode MCP

参考 MCP 服务器 | OpenCode

使用 opencode mcp list 列出所有 MCP 服务器及其认证状态

启用 MCP：（opencode.jsonc）

可以将 enabled 设置为 false 来禁用某个 server，避免直接删除配置表信息

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

远程 MCP 接入：

指定 type 为 remote，url 是远程 MCP 服务器的地址，通过 headers 选项可以传入一组请求头

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

MCP OAuth 认证，参考 MCP 服务器 | OpenCode

本地 MCP 接入

指定 type 为 local，command 用于指定本地 MCP 服务器的启动命令

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

源码参考 @modelcontextprotocol/server-everything - npm

2.2.2 Claude Code MCP

参考 通过 MCP 将 Claude Code 连接到工具 - Claude Code Docs

使用 claude mcp list 列出所有 MCP 服务器及其认证状态

使用 claude mcp remove [mcp 名称] 删除 MCP

使用 claude mcp add --transport http [MCP 名] [MCP URL] 接入 MCP

在 mcp add 时添加 –-scope user/local/project 指定作用域

本地 MCP：

Playwright：microsoft/playwright-mcp: Playwright MCP server

添加方式：claude mcp add playwright -- npx -y @playwright/mcp@latest

  • 没有 --transport 标志，因为本地服务器使用默认的 stdio 传输
  • -- 分隔符之后的所有内容都是 Claude Code 运行以启动服务器的命令
  • -y 告诉 npx 安装包而不提示
  • 默认使用 chrome，如果要使用其他浏览器，需要在 @playwright/mcp@latest 之后附加 --browser 和浏览器名称，例如 --browser firefox

配置文件：type 为 stdio

"mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
}

远程 MCP：

添加方式：claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

配置文件：type 为 http

"mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
}

2.2.3 MCP 推荐

MCP 作用
figma 将 figma 设计稿转换为代码
zapier 打通各个 app，实现自动化工作流
blender 操作 blender 完成 3d 建模
context7 帮助 AI 查找最新文献&知识
replicate 使用 replicate 生成图片
github 在 github 上进行开发、管理、git 操作

其他 MCP：chrome devtools（网页调试），neon & supabase（后台数据管理平台），stripe（支付功能实现）

2.3 Skill

Skill 是一组可复用的指令、脚本和资源文件夹，AI Agent 按需动态加载，无需常驻系统提示词，可以理解为是 AI 的指导手册。其核心设计理念是 渐进式披露（Progressive Disclosure）：元数据常驻（~100 token），指令体触发时才加载，参考资源按需读取，从而在保持上下文轻量的同时提供深层知识。

本章主要对 skill 的格式、组成以及部分特性进行简要介绍，以供参考。而在实际应用中，skill 一般都是通过 AI 创建。

配置路径

Skill 按作用域存放，CC 与 OC 路径互相兼容：

作用域 Claude Code OpenCode
项目级 ./.claude/skills/<name>/ ./.opencode/skills/<name>/ 或 ./skill/<name>/（v1.0.190+ 原生）
全局级 ~/.claude/skills/<name>/ ~/.config/opencode/skills/<name>/ 或 ~/.config/opencode/skill/<name>/
兼容路径 — 同时扫描 ~/.claude/skills/ 和 .claude/skills/（CC 兼容）

OC 同时支持 skill/（单数）和 skills/（复数）目录；CC 仅使用 skills/。OC 会主动扫描 CC 的路径以实现复用。如果 CC 和 OC 混用，可以直接把 Skill 装在 CC 上，免移植 & 同步。

2.3.1 SKILL.md 编写

文件架构：

skill-name/                  # 文件夹名 = skill 名称（kebab-case）
├── SKILL.md                 # 必需 — YAML frontmatter + Markdown 指令
├── scripts/                 # 可选 — 可执行脚本（py/js/sh），不占上下文
├── references/              # 可选 — 深层参考文档，按需读取
├── assets/                  # 可选 — 模板、配置、图片等
└── config.json              # 可选 — 运行时状态存储（CC 特有概念）

核心文件 SKILL.md 结构：

<!-- SKILL.md -->
---
# ← YAML frontmatter（元数据，始终加载 ~100 token）
name: my-skill
description: 技能描述——Claude/OC 据此决定何时触发
allowed-tools: Read, Grep, Bash(git *)
---

# ← Markdown 指令体（触发时完整加载，建议 ≤ 200 行 / 3500 词）
## 执行流程
1. ...
## 注意事项（Gotchas）
...

基础 Frontmatter 字段（AgentSkills 开放标准，CC & OC 通用）

字段 必需 说明
name ✓ 1–64 字符，kebab-case，必须与文件夹名一致
description 强烈推荐 1–1024 字符，第三人称，写清楚 做什么 + 何时触发。这是 AI 决定是否调用 skill 的核心依据。省略时回退到正文首段
license – SPDX 标识，如 MIT
compatibility – 兼容性声明
metadata – 自由键值对，如 audience: maintainers，主要写给人 & 工具链看（组织和归类）
allowed-tools – 工具白名单，逗号/空格分隔，支持 Bash(cmd *) 模式匹配

CC 扩展字段（仅 Claude Code 支持）

字段 说明
disable-model-invocation: true 禁止 AI 自动触发，仅能通过 /name 手动调用
user-invocable: false 从 / 菜单隐藏，仅 AI 可调用（后台 skill）
argument-hint 自动补全提示，如 [issue-number]，最长 200 字符
model 模型覆盖：sonnet / opus / haiku / inherit
context: fork 在隔离子 agent 上下文中运行
agent 配合 context: fork，指定子 agent 类型
effort 推理力度：low / medium / high / xhigh / max
paths Glob 模式，限定文件匹配时才触发
hooks 生命周期钩子（PreToolUse、PostToolUse 等）
skills 自动加载的依赖 skill 列表
version 版本号（建议遵循 semver）
disallowed-tools 工具黑名单（与 allowed-tools 互斥场景使用）

编写要点

  1. Description 写给模型看，不写给人看。 用第三人称，包含具体触发短语：

    # ✓ 好
description: This skill should be used when processing vendor invoices,
  running "monthly close", or generating reconciliation reports from PDFs.
# ✗ 差
description: Use this skill when working with invoices.

  2. Gotchas 是最高信号内容。 在正文中列出反常约定、陷阱、组织特定规则，这是 skill 区别于 AI 默认知识的核心价值：

    ## Gotchas
- `subscriptions` 表是 append-only，取 `version` 最大而非 `created_at` 最新的行
- 生产环境禁止直接 `DROP TABLE`，必须走 migration 流程

  3. 指令体 ≤ 200 行。 超出时把详细内容拆分到 references/，正文中链接引用。

  4. 提供可执行脚本而非让 AI 反复生成样板代码。 把重复逻辑写成 scripts/helper.py，让 AI 调用而非每次重写。

  5. 用 config.json 存储运行时状态（CC 特有模式）：首次使用时引导用户配置，之后持久化在 skill 目录内。

2.3.2 权限与启用/禁用

Claude Code

通过 allowed-tools 和 disallowed-tools frontmatter 字段限定该 skill 可使用的工具范围。

启用/禁用：

  • 无内置 enable/disable 开关（社区已提 feature request）
  • 当前禁用方式：重命名/删除 SKILL.md 或移出 skills/ 目录
  • Skill 内可通过 disable-model-invocation: true 禁止 AI 自动调用，但用户仍可手动 /name 触发
  • user-invocable: false 则从 / 菜单隐藏（仅 AI 可调用）
  • 两者同时反向设置 = skill 实际上被禁用

OpenCode

权限通过 opencode.json 控制，支持通配符模式匹配：

{
  "permission": {
    "skill": {
      "*": "deny",              // 默认全部禁用
      "safe-skill": "allow",    // 自动批准
      "experimental-*": "ask"   // 每次询问
    }
  }
}
权限值 行为
allow 直接加载使用，无需确认
deny 完全隐藏，AI 不可见
ask 每次调用前请求用户确认

启用/禁用：

  • 通过 permission.skill 的 allow / deny 按 skill 名或通配符控制
  • 可在 agent 定义中将 tools.skill 设为 false，对该 agent 完全禁用 skill 功能
  • Skill 复用 OC 的通用 permission 体系，与 bash/edit 等工具权限一致

2.3.3 重要特性

渐进式披露（Progressive Disclosure）：Skill 的共同核心设计，三级加载

层级 加载内容 时机 Token 消耗
L1 name + description 启动时常驻 ~100
L2 SKILL.md 指令体 AI 决定触发时 ≤ 500 行
L3 references/ scripts/ assets/ 执行中按需读取 无上限（脚本不读入上下文）

自动发现与调用（CC & OC 共有）

  • AI 启动时扫描所有 skill 路径
  • 将 <available_skills> 列表（name + description）注入系统提示词
  • AI 根据用户意图匹配 description，通过内置 Skill 工具自动调用
  • 调用后完整 SKILL.md 加载到上下文中执行

上下文隔离（CC 特有）

通过 frontmatter 设置 context: fork，Skill 在独立子 agent 中运行：

context: fork
agent: Explore          # 子 agent 类型
model: sonnet           # 可选：子 agent 模型
  • 独立上下文窗口，不污染主对话
  • 独立工具和权限沙箱
  • 适用于搜索、审计等独立任务

Hooks 集成（CC 特有）

Skill 可注册生命周期钩子，仅在 skill 激活期间生效：

hooks:
  PreToolUse:
    - matcher: "Bash(rm *)"
      command: "echo '⚠️ 删除操作' && exit 1"

插件系统（CC 特有）

  • Skill 可打包为 Plugin，通过 marketplace 分发
  • /plugin 打开 TUI 面板浏览、安装、管理插件
  • /plugin install <name>@<marketplace> 命令行安装
  • 插件可包含 skill + agent + hook + MCP + 命令的组合

依赖与预加载（CC 特有）

skills: [dependency-skill-1, dependency-skill-2]  # 自动加载依赖 skill

2.3.4 CC vs OC Skill 差异汇总

维度 Claude Code OpenCode
显式调用 /[skill 名称] /skill:[skill 名称]
路径 .claude/skills/ ~/.claude/skills/ .opencode/skills/ skill/ ~/.config/opencode/skill/
兼容 CC 路径 — 自动扫描 .claude/skills/
Frontmatter 扩展 16+ 字段（context fork/hooks/model/effort 等） 核心标准字段为主
权限控制 settings.json 中 permissions.allow/ask/deny opencode.json 中 permission.skill 键值对 + 通配符
启用/禁用 无内置开关（需移动文件）；通过 disable-model-invocation / user-invocable 间接控制 permission.skill 中 deny 直接禁用；agent 级可设 tools.skill: false
上下文隔离 context: fork —
Hooks 内置于 frontmatter —
插件/Marketplace /plugin TUI + marketplace 分发 通过 npm 包分发（如 opencode-autoskills）
依赖加载 skills: [...] —
模型覆盖 model / effort 通过 agent 切换间接实现

社区生态

生态 规模
CC 社区配置 claude-code-kit（197+ skills）、claude-code-config（30+ skills）
OC 社区配置 opencode-config（27+ skills）、opencode-agent-kit（201+ skills）

2.3.5 Skill 管理插件

除了从社区获取 skill 或者自己创建 skill，还可以通过插件更加便捷地完成 skill 的创建 & 获取。

1. find-skills

安装方法：prompt 输入

帮我从 https://github.com/vercel-labs/skills 下载安装 find-skills

使用：输入 我需要一个 xxxx 的 skill，帮我安装 类似的提示词，即可触发该 skill，TUI 会交互式引导查找和安装。或者使用 npx skills find [关键词] 手动触发

2. skill-creator

安装方法：安装 find-skills 之后，直接通过 prompt 进行安装

帮我安装skill creator这个skill

使用：输入 帮我创建一个 xxxx 的 skill 类似的提示词，即可触发。与直接让 LLM 创建 skill 相比，skill-creator 会自动构建标准且结构完整的 skill，并进行结构化循环迭代，以验证 skill 性能。

2.4 浏览器操作自动化

2.4.1 OpenCLI

将网页&本地工具（Electron 应用）等 CLI 化，将成功操作路径图沉淀为固定流程（适配器），以让 AI 直接操作应用或者浏览器（如网页数据拉取），实现低 Token 消耗以及操作流程稳定性。其原理为通过拦截底层 API 请求，直接回放调用，从而实现自动化。

已内置支持的站点：OpenCLI — 把你已登录的浏览器，交给 CLI 和 Agent

配置流程：

1. 通过 Node.js 安装：npm install -g @jackwener/opencli
2. 在浏览器安装 OpenCLI 插件：
	- Opt 1. 插件市场安装（Chrome）
    - Opt 2. 按照 https://github.com/jackwener/OpenCLI 引导手动安装（非 Chrome）
    - Opt 3. AI 代劳（推荐）
3. 验证安装：opencli doctor
4. 安装 opencli skill：npx skills add jackwener/opencli

用法：

  • [浏览器/工具操作提示词]，opencli → 通过 opencli 操作大型网站站点 & 本地工具
  • [构建一个/修改 opencli 适配器，要求：xxxxx] → 对于新的网页 & 操作，通过 opencli-adapter-author & opencli-autofix 沉淀 or 更新适配器

能力边界：

  • 如需登录，需要先在浏览器登录网站
  • 当网站适配完成时不消耗额外 Token，但是如果要是配新网页需要消耗 token 完成探索
  • 使用 doctor、verify、autofix 等操作，应对网站 & 工具的变化

2.4.2 Playwright

类似于 OpenCLI 的浏览器自动化工具，但是与 OpenCLI 相比，Playwright 则通过直接作用于 DOM 元素，操控真实的浏览器 UI，模拟点击输入从而实现自动化流程。

相比浏览器 CC 插件的优势：支持 Headless（后台操作，不打开浏览器），支持并行操作，低 Token 消耗

项目链接：Playwright CLI

配置流程：

1. 通过 Node.js 安装：npm install -g @playwright/cli
2. 安装 playwright 浏览器引擎
	- 如果是 chrome 浏览器，直接执行：npx playwright install chromium
	- 其他浏览器参考官方文档（建议 AI 代劳）
3. 安装 playwright-cli 的 skill：playwright-cli install --skills

用法：直接大白话告诉 playwright 要进行的网页操作 or 测试流程，Headed/Headless，是否要安排 subagent 编排工作流等信息，playwright 会自动进行自动化操作编排

2.5 OpenCode 扩展机制

2.5.1 LSP

LSP 即 语言服务协议（Language Server Protocol），可以让 AI 工具获得 IDE 级别的代码能力，将基于文本搜索（例如 grep）的操作替换为代码语义级别的理解，提升代码检索的准确性、稳定性、检索效率并减少 Token 消耗。

由于 OpenCode 原生支持 LSP，Claude Code 对 LSP 支持不足，这里主要针对 OpenCode 的 LSP 配置以及用法进行简单说明。

启用 LSP：在 opencode.json 中设置 lsp: true 即可启用所有内置 LSP 服务器。启用后，opencode 打开文件时会自动匹配扩展名，如果对应的 LSP 服务未运行则自动启动，诊断信息作为 agent 反馈注入上下文中。也可以传空对象 {} 保留默认行为以便后续覆盖特定服务器：

{ "$schema": "https://opencode.ai/config.json", "lsp": true }

内置 LSP 覆盖：34 种主流语言/框架开箱即用，部分需满足前置条件：

条件 语言
自动安装（无需手动操作） astro, bash, clangd, kotlin, lua, php, svelte, terraform, tinymist, vue, yaml
需系统已有运行时 csharp/fsharp（.NET SDK）, dart, elixir, gleam, go, haskell, java（JDK 21+）, julia, nix, ocaml, ruby, rust, swift（macOS）, zig
需项目已有依赖 deno（deno.json）, eslint, oxlint, prisma, pyright, typescript

配置项：在 lsp 对象中按服务器名配置，支持以下字段：

属性 类型 说明
disabled boolean 设为 true 禁用该 LSP
command string[] 启动命令（自定义 LSP 必填）
extensions string[] 关联的文件扩展名
env object 启动时注入的环境变量
initialization object LSP initialize 请求时透传的服务器特定选项

常用操作示例：

// 禁用特定 LSP（如项目中已有更好的 TS 检查工具）
{ "lsp": { "typescript": { "disabled": true } } }

// 全局关闭 LSP（覆盖其他配置）
{ "lsp": false }

// 添加自定义 LSP 服务器
{ "lsp": { "custom-lsp": { "command": ["custom-lsp-server", "--stdio"], "extensions": [".custom"] } } }

// 向 LSP 透传初始化参数
{ "lsp": { "typescript": { "initialization": { "preferences": { "importModuleSpecifierPreference": "relative" } } } } }

需要注意的是，LSP 开启后对于系统资源的占用会明显提升，因此：

  • 适合：有一定规模的项目，准确语义理解，项目重构，Token 消耗敏感
  • 不适合：小 Demo 项目，设备内存紧张

参考：LSP 服务器 | OpenCode

2.5.2 Tool

Tool 是模型的内联函数，进程内执行，低延迟，无 Token 消耗。Tool 以 TypeScript 或者 JavaScript 定义，支持调用任何语言编写的脚本。

OpenCode 内置 Tool：

默认所有内置工具启用且无需权限，可通过 permission 字段控制。

工具 作用
bash 在项目环境中执行 shell 命令（npm install、git status 等）
read 读取文件内容，支持指定行范围
write 创建新文件或覆盖已有文件
edit 通过精确字符串替换修改文件（LLM 修改代码的主要方式）
grep 正则表达式搜索文件内容，底层使用 ripgrep，遵循 .gitignore
glob Glob 模式匹配查找文件（如 src/**/*.ts），按修改时间排序
lsp 与 LSP 交互：跳转定义、查找引用、悬停信息、调用层次等
patch 将补丁/diff 应用到代码库
skill 加载指定 skill 的 SKILL.md 内容到对话中
todowrite 创建和更新任务列表，跟踪多步骤任务进度
webfetch 获取并读取网页内容（查文档、研究在线资源）
websearch 使用 Exa AI 搜索网络信息（无需 API Key）
question 执行中向用户提问：收集偏好、澄清指令、提供选项

自定义 Tool：

路径类型 路径
By 项目 .opencode/tools/
全局 ~/.config/opencode/tools/

项目结构：

.opencode/tools/                  # 项目级 | ~/.config/opencode/tools/（全局）
├── database.ts                   # 文件名 = 工具名 → 暴露 "database" 工具
├── math.ts                       # 多导出：math_add / math_multiply
├── add.py                        # 其他语言脚本，被 .ts 工具定义调用
└── ...                           # 与内置工具同名时优先使用自定义

一般会通过辅助函数 tool() 来进行创建，支持通过 tool.schema（即 Zod）定义 Tool 参数。文件名即为 Tool 名，如果一个 Tool 文件中有多个 tool() 定义，Tool 名则为 <文件名>_<tool()的export名>。与内置 Tool 冲突时优先使用用户定义的 Tool。

Tool 定义案例：

其他语言编写的脚本：

# .opencode/tools/add.py
import sys

a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

Tool 本体定义：

import { tool } from "@opencode-ai/plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

参考：

工具 | OpenCode

自定义工具 | OpenCode

2.5.3 Command

不同于 Skill，Command 更加轻量，其效果等价于直接给对话框发送一段指定提示词，通过 /[Command名称] 调用。定义方式：

<!-- ~/.config/opencode/commands/test.md -->
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

详细定义 & 配置参考：命令 | OpenCode

3 底层概念与原理

本章梳理 Agent 领域的基础概念与核心机制——Harness（约束框架）、RAG（检索增强生成）、ReAct（推理-行动循环）、Function Calling（工具调用）和 A2A（智能体通信）。其中，Harness 是基础设施层，ReAct 定义编排范式，RAG 和 Function Calling 是具体能力落地，A2A 则是多 Agent 协作协议。

3.1 Harness

定义： Harness（线束/约束框架）是一套围绕 LLM 构建的边界、规则和检查机制，确保 LLM 在受控范围内按预期工作，而非自由发散。

核心公式： Harness = Agent - LLM

Agent 中去除 LLM 决策大脑后，剩下的所有"壳"——规划器、生成器、检验器，以及它们之间的流程管道——就是 Harness。

类比： 就像汽车的安全带 + 刹车 + 方向盘——不是引擎（LLM），但决定了引擎的动力被引导到哪里、在哪里停下。

Agent 循环中的 Harness：

问题 → Context 组装 → LLM → 计划（任务拆分/工具选择/验收标准）
  → 权限检查 → 工具调用 → 输出结果
  → Context 组装（循环）→ ... → 最终结果

去除 LLM 后，Harness 的独立工作流：
需求 → 规划（规划器）→ 生成（生成器）→ 验证（检验器）→ 输出

Harness 基础设施六件套：

组件 作用 无此组件的后果
沙箱 (Sandbox) 隔离 LLM 的文件/网络/进程操作，限制爆破半径 一句 rm -rf / 直接执行
记忆 (Memory) 跨会话持久化用户偏好、项目约定、反馈修正 每次对话都是"新人"，反复纠正相同问题
技能 (Skill) 渐进式披露的领域知识包，按需加载不占常驻上下文 大量固定指令常驻，浪费上下文窗口
会话管理 (Session Mgmt) 对话的创建、恢复、分支、回退、压缩 上下文溢出后丢失历史，无法回退错误步骤
Hooks 生命周期钩子，在特定事件前后自动执行检查/操作 无法在危险操作前拦截，无法在完成时通知
权限控制 (Permissions) 工具/命令粒度的 allow/ask/deny 三级控制 LLM 自由执行任何命令，安全风险不可控

与相关概念的关系：

  • vs Agent： Agent = Harness + LLM，Harness 是 Agent 的"骨架"，LLM 是"大脑"
  • vs Guardrails： Guardrails（护栏）是 Harness 的子集，特指输入/输出的校验规则（如不允许输出敏感信息）；Harness 还包括流程编排、会话管理等更广的范畴
  • vs Skill： Skill 是 Harness 中"知识注入"的一种实现方式——Skills 定义"什么情况下该做什么"，Harness 负责"确保它按这个规则做"

延伸资源：

3.2 RAG

检索增强式生成（Retrieval-Augmented Generation）

一句话定义： 让 LLM 在回答问题之前先查资料，提取关键信息后再生成答案。

核心要解决的问题：

问题 无 RAG 的表现 RAG 如何解决
模型幻觉 LLM 编造不存在的事实 用检索到的真实文档约束生成
信息过时 回答基于训练截止日前的旧知识 检索最新文档/数据库
缺乏私域数据 无法回答公司内部知识 接入内部知识库作为检索源

为什么不直接把整个文档库塞进上下文？

  • 上下文窗口限制： 即使 200K token 的窗口，大型文档库也远远装不下
  • Token 成本： 每次对话都传入全量文档 → 成本线性膨胀，且大部分内容与当前问题无关
  • "大海捞针"效应： 上下文越长，LLM 对中间部分的注意力越分散，反而忽略关键信息

核心流程（两阶段）：

┌─── 离线阶段：数据处理 ──────────────────────────────────────────┐
│  原始文档 → 清洗 → 切分(Chunking) → 向量化(Embedding) → 向量库    │
└──────────────────────────────────────────────────────────────┘

┌─── 在线阶段：问答处理 ────────────────────────────────────────┐
│  用户提问 → Query改写 → 向量化 → Recall(召回) → Rerank(重排)   │
│       → 组装Prompt → LLM生成 → 带引用来源的回答                │
└────────────────────────────────────────────────────────────┘

各环节详解：

  1. 切分 (Chunking)：

    • 按章节、按段落、按固定字数、按语义边界（如 Markdown 标题层级）
    • 核心原则：每个 chunk 信息相对完整，避免关键信息被截断
    • 常见策略：固定大小 + 重叠区 (overlap)，如 512 token 一块，重叠 128 token

  2. 向量化 (Embedding)：

    • 将文本映射到高维语义空间坐标
    • 语义相近的文本 → 向量距离近（余弦相似度高 / 欧氏距离小）
    • 常用模型：OpenAI text-embedding-3、BGE、Jina Embeddings

  3. Recall（召回）：

    • 查询向量与库中所有向量计算相似度，取 Top-K
    • 混合检索（Hybrid Search）： 向量相似度 + BM25 关键词检索 → 加权融合，互补长短（向量擅长语义相关，关键词擅长精确匹配）

  4. Rerank（重排）：

    • 召回阶段追求高召回率（宁可多召），Rerank 追求高精度
    • 用更强的 Cross-encoder 模型对 Top-K 做精细排序，选出最相关的几条

  5. Query Rewrite（查询重写）：

    • 用户原始提问往往简短、模糊、缺乏上下文
    • 改写策略：补全指代、拆分复合问题、生成多视角查询、假设性文档生成 (HyDE)

关键优化维度：

优化点 说明 常用方案
数据清洗 去除文档噪声、格式化不一致内容 去除页眉页脚、统一编码、过滤无意义短文本
切分策略 不同文档类型需不同切法 代码用 AST 切分、表格保持完整、FAQ 按 Q&A 对切
Query Rewrite 用户输入质量决定检索质量 用 LLM 重写 + 多路召回合并
检索策略 单一检索方式有盲区 混合检索（Dense + Sparse）、多路召回 + 融合排序
模型选取 Embedding 和 Rerank 模型各有擅长领域 中文场景选 BGE/M3E，代码场景选 CodeBERT 系

高级 RAG 模式：

模式 思路 适用场景
Self-RAG LLM 自我判断是否需要检索，检索后自评相关性，按需多轮检索 需要判断"什么时候该查"的场景
Corrective RAG 检索后先评估文档质量，质量差则自动重写 Query 重新检索 文档质量参差不齐的知识库
Agentic RAG 将 RAG 作为 Agent 的一个工具，由 ReAct 循环编排多步检索-验证-推理 复杂多步推理 + 需要交叉验证的场景
Graph RAG 将文档转为知识图谱，检索时走图遍历而非纯向量搜索 实体关系密集的领域（法律、医疗）

3.3 ReAct

Reasoning + Action（推理 + 行动），一种让 LLM 一边思考一边执行的 Agent 范式。

核心思想： 传统的 LLM 是"一步到位"——给问题直接出答案。ReAct 将这个过程拆解为"思考→行动→观察→再思考"的TAO 循环（Think-Act-Observe），每一步行动的结果都会影响下一步的推理，直到得出最终答案。

TAO 循环：

思考(Thought) → 行动(Action) → 观察(Observation) → 思考 → ... → 最终回答(Answer)

具体例子：
用户："今天深圳天气怎么样？"

Thought: 需要查询天气，使用 search_weather 工具
Action: search_weather("深圳", "2026-07-04")
Observation: "深圳 7月4日 多云 28°C~33°C"
Thought: 已获得天气数据，整理回答
Answer: 今天（7月4日）深圳多云，气温 28°C~33°C

ReAct 的四大优点：

优点 原理
减少幻觉 每步基于真实工具返回的数据做推理，而非仅靠模型参数记忆
实时性 可调用搜索/API 获取最新信息，无需重新训练模型
灵活容错 工具调用失败时可自适应调整策略重试
可解释性 每一步思考过程可见，便于调试和审计

核心组件：

组件 说明
历史上下文 过去的用户输入 + 所有 Thought/Action/Observation 记录
环境信息 当前外部输入：用户提示词、系统环境、可用工具清单
LLM 推理引擎，负责产出 Thought 和 Action
工具 可执行的代码/API，LLM 通过 Action 调用
观察结果 工具执行的阶段性结论，注入下一轮上下文

标准 ReAct 提示词模板：

## 身份
你是一个具备工具调用能力的 AI 助手。

## 可用工具
{tool_list}

## 工作规则
请严格遵循 Think → Action → Observation 循环：

1. **Think**: 分析当前情况，决定下一步行动
2. **Action**: 调用工具（格式：`Action: tool_name[params]`）
3. **Observation**: 读取工具返回结果
4. 重复 1-3，直到信息充足
5. 输出 **Answer**: 最终回答

## 当前上下文
- 历史记忆：{history_context}
- 环境信息：{env_info}
- 用户目标：{user_goal}

Python 实现 ReAct Agent 示例：

"""
一个最小化的 ReAct Agent 实现，演示 TAO 循环的核心逻辑。
运行前需安装：pip install openai
"""

import openai
import json
import re

class ReActAgent:
    """ReAct Agent — 思考(Thought) → 行动(Action) → 观察(Observation) 循环"""

    def __init__(self, client, model="gpt-4o", max_iterations=8):
        self.client = client
        self.model = model
        self.max_iterations = max_iterations
        self.history = []       # 记录完整 TAO 过程
        self.tools = {}         # {工具名: (函数, 参数schema)}

    def register_tool(self, name, func, description, params_schema):
        """注册一个工具"""
        self.tools[name] = {
            "func": func,
            "description": description,
            "params": params_schema
        }

    def _build_tool_prompt(self):
        """构建工具清单"""
        lines = []
        for name, info in self.tools.items():
            lines.append(f"- {name}: {info['description']}")
            lines.append(f"  参数: {json.dumps(info['params'], ensure_ascii=False)}")
        return "\n".join(lines)

    def _build_system_prompt(self):
        return f"""你是一个遵循 ReAct 范式的 AI Agent。
请严格按以下格式输出每一步:

Thought: <你的推理>
Action: <工具名>[<JSON参数>]

或者当你已经可以回答时:
Thought: <你的推理>
Answer: <最终答案>

## 可用工具
{self._build_tool_prompt()}

## 历史记录
{self._format_history()}
"""

    def _format_history(self):
        return "\n".join(self.history[-10:]) or "(无)"

    def _parse_response(self, text):
        """解析 LLM 输出中的 Action 或 Answer"""
        thought_match = re.search(r"Thought:\s*(.+)", text, re.IGNORECASE)
        action_match = re.search(
            r"Action:\s*(\w+)\s*\[\s*(\{.*?\})\s*\]", text, re.DOTALL
        )
        answer_match = re.search(r"Answer:\s*(.+)", text, re.IGNORECASE | re.DOTALL)

        return {
            "thought": thought_match.group(1).strip() if thought_match else None,
            "action_name": action_match.group(1) if action_match else None,
            "action_params": action_match.group(2) if action_match else None,
            "answer": answer_match.group(1).strip() if answer_match else None,
        }

    def _execute(self, name, params_str):
        """执行工具调用"""
        if name not in self.tools:
            return f"错误: 未找到工具 '{name}'"
        try:
            params = json.loads(params_str)
            result = self.tools[name]["func"](**params)
            return str(result)
        except Exception as e:
            return f"工具执行错误: {e}"

    def run(self, user_query):
        """主循环：TAO 迭代直到产出 Answer"""
        self.history = [f"用户: {user_query}"]

        for i in range(self.max_iterations):
            # --- 调用 LLM ---
            messages = [
                {"role": "system", "content": self._build_system_prompt()},
                {"role": "user", "content": user_query if i == 0 else "继续。"},
            ]
            response = self.client.chat.completions.create(
                model=self.model, messages=messages
            )
            text = response.choices[0].message.content
            print(f"\n--- 第 {i+1} 轮 ---\n{text}")

            # --- 解析输出 ---
            parsed = self._parse_response(text)
            self.history.append(text)

            # --- 如果是 Answer，结束 ---
            if parsed["answer"]:
                return parsed["answer"]

            # --- 如果是 Action，执行并观察 ---
            if parsed["action_name"]:
                obs = self._execute(parsed["action_name"], parsed["action_params"])
                self.history.append(f"Observation: {obs}")
                continue

            # 格式解析失败，将原文作为观察回传
            self.history.append(f"Observation: 请按格式输出 Thought + Action 或 Answer")

        return "已达到最大迭代次数，未能得出结论。"


# ===== 使用示例 =====
if __name__ == "__main__":
    client = openai.OpenAI()  # 需配置 OPENAI_API_KEY 环境变量

    agent = ReActAgent(client, model="gpt-4o", max_iterations=5)

    # 注册一个天气查询工具
    def mock_weather(city, date=None):
        return json.dumps({"city": city, "date": date or "今天", "weather": "多云", "temp": "28-33°C"}, ensure_ascii=False)
    agent.register_tool("search_weather", mock_weather, "查询指定城市的天气", {"city": "string", "date": "string(可选)"})

    # 注册一个计算器工具
    agent.register_tool("calculator", lambda expr: str(eval(expr)), "执行数学计算", {"expr": "string"})

    # 运行
    result = agent.run("深圳今天多少度？")
    print(f"\n===== 最终答案 =====\n{result}")

延伸资源：

3.4 Function Calling

Agent 中将 大脑（LLM）和 手脚（工具）关联起来的核心机制。

一句话理解： LLM 不直接执行操作，而是输出一个标准化的 "我想调用这个函数，参数是这些" 的 JSON，由外部程序实际执行，执行结果再回传给 LLM 继续推理。

核心流程（五步法）：

┌───────────────────────────────────────────────────────────┐
│ 1. 输入构建             2. 意图与参数生成                     │
│ 用户提示词 + 工具清单   LLM 无法直接回答 → 输出函数调用JSON      │
│        ↓                        ↓                         │
│    ┌────────┐             ┌──────────────┐                │
│    │  LLM   │ ←─────────→ │  本地应用     │                │
│    └────────┘             └──────────────┘                │
│        ↑                        ↓                         │
│ 5. 最终生成             3-4. 本地执行 + 数据回传              │
│ 结合回传信息给出最终答案   解析JSON → 执行函数 → 结果回传        │
└───────────────────────────────────────────────────────────┘

两步可靠性保证：

机制 原理 作用
SFT（监督微调） 用海量"用户意图 → 正确的函数调用 JSON"数据对专门训练 让模型学会"什么时候不该调用"、"参数该填什么"
约束解码 (Constrained Decoding) 推理引擎在生成每个 token 时，只允许符合 JSON Schema / 函数签名的 token 通过 从源头强制合规，杜绝格式错误

三个核心难点的处理策略：

难点 表现 解决策略
幻觉调用 输出不存在的函数名或错误的参数值 将报错信息直接丢回 LLM 重写 → 自我纠偏（Self-Correction）。重试 2~3 次仍失败 → 降级为文本回答
格式错误 JSON 语法错误、字段缺失、类型不匹配 鲁棒解析器自动修复（补全括号、修正引号）+ 约束解码兜底
工具过多 上千个函数定义塞不进上下文 用 RAG 动态检索与当前意图最相关的 Top-K 工具定义
多依赖调用链 需要先调 A 再调 B 再调 C 用 ReAct 循环编排：每步只调用一个函数，观察结果后再决定下一步

Function Calling vs Tool Use：

这两个词经常混用，但存在细微差别：

  • Function Calling 特指 LLM 输出结构化函数调用指令的能力（API 厂商提供的接口能力，如 OpenAI 的 function_calling）
  • Tool Use 是更广义的概念，涵盖整个工具定义 → LLM 选择 → 本地执行 → 结果回传的完整链路
  • 可以理解为：Tool Use = Function Calling（LLM 侧）+ Tool Execution（本地侧）

延伸资源：

3.5 A2A

Agent-to-Agent Protocol，Google 提出的智能体间通信开放协议，让不同框架、不同厂商的 Agent 能够互操作。

定位： A2A 之于 Agent 协作，就像 HTTP 之于 Web 服务——定义了一套通用的通信规范，不管 Agent 背后是 Claude、GPT 还是 Gemini，只要支持 A2A 协议就能互相派发任务。

三个核心概念：

1. Agent Card（智能体名片）

┌──────────────────────────────────┐
│  Agent Card（公开）               │
│  • 名称 / 描述 / 版本              │
│  • 能力声明（我能做什么）           │
│  • 输入/输出 Schema               │
│  • Endpoint URL                  │
│  • 支持的传输方式                  │
├──────────────────────────────────┤
│  不暴露（隐藏）                    │
│  ❌ 内部模型 / 上下文              │
│  ❌ 工具链 / Skill 实现           │
│  ❌ 内部 Prompt 设计              │
└──────────────────────────────────┘

2. Task（任务）与状态机

A2A 以 Task 为工作单元。下方是状态机图：

stateDiagram-v2 [*] --> submitted : 客户端提交任务 submitted --> working : Agent 开始处理 working --> completed : 任务成功完成 working --> failed : 执行出错 working --> input_required : 需要用户补充信息 working --> canceled : 用户/客户端取消 input_required --> working : 收到补充信息后继续 completed --> [*] failed --> [*] canceled --> [*] note right of input_required 交互式等待： Agent 发起追问 用户响应后恢复执行 end note

各状态说明：

状态 含义 典型触发条件
submitted 任务已提交，等待 Agent 接收 客户端发送 Task 请求
working Agent 正在执行 Agent 开始处理 Task
input_required 需要用户补充信息 Agent 执行中发现参数不明确，主动追问
completed 任务成功完成 产出最终结果，附带 Artifacts（产物）
failed 任务执行失败 工具调用异常、推理超时等
canceled 任务被主动取消 用户/客户端发起取消请求

3. Transport（传输层）

传输方式 适用场景 实现
HTTP + JSON-RPC 2.0 请求-响应模式，单向派发任务 最基础的方式，所有 Agent 必须支持
SSE (Server-Sent Events) 服务端向客户端推送 Task 状态更新 长连接，Agent 主动推送进度
Webhook 客户端接收任务完成通知 异步回调，避免轮询
gRPC 高性能流式通信 适用于大量数据传输 / 实时协作

A2A vs MCP 对比（常见混淆点）：

维度 A2A MCP
解决的问题 Agent 之间怎么通信、协作 Agent 怎么接入外部工具/资源
类比 HTTP / REST API USB-C 接口标准
通信方向 Agent ↔ Agent Agent ↔ Tool/Resource
提出者 Google Anthropic
核心概念 Agent Card + Task + 状态机 Server + Tool/Resource/Prompt 三合一
协作关系 互补。一个 Agent 通过 A2A 把任务派给另一个 Agent，后者通过 MCP 调用工具完成任务

延伸资源：

4 远程连接

CC Connect 是一款用于远程桥接 AI Agent 的工具，让用户通过 QQ / 微信等通讯软件远程操控本地 AI Agent（Claude Code、OpenCode 等）。源码链接：CC-Connect

安装：

npm install -g cc-connect

配置文件位于 ~/.cc-connect/config.toml。核心结构：一个 [[projects]] = 一个 Agent + 一组通讯平台，一个 cc-connect 实例可同时运行多个 project。

4.1 编写项目脚手架

所有平台在绑定凭证前，都需要 先在 config.toml 中创建 project 框架——setup 命令只负责填平台凭证，不会自动创建 project。

[[projects]]
name = "my-project"                    # 自定义项目名，后续 setup 用 --project 指定

[projects.agent]
type = "claudecode"                    # 或 "opencode"

[projects.agent.options]
work_dir = "C:\\Users\\你的用户名"      # ← Agent 工作在哪个目录
mode = "default"

三种平台的 platform 条目写法不同，如下表。QQ 全部手动填写；微信和飞书先写占位值，setup 扫码后自动替换：

平台 type 占位/填写方式
QQ "qq" 手动填写所有字段（NapCat WebUI 获取）
微信 "weixin" token 写 "待配置"，setup 扫码自动替换
飞书 "feishu" app_id / app_secret 写 "待配置"，setup 扫码自动替换

4.2 QQ 远程连接

使用 NapCatQQ（OneBot v11 桥接器），需注册备用 QQ 号（Bot 需独立身份，第三方客户端有封号风险）。

手机 QQ → NapCat (WebSocket) → cc-connect → Claude Code / OpenCode

4.2.1 配置流程

  1. 安装 NapCat：下载 NapCat.Shell.Windows.OneKey.zip（Releases）→ 解压到无中文路径（如 C:\napcat\）→ 运行 NapCatInstaller.exe

  2. 扫码登录：

    cd C:\napcat\NapCat.xxxxx.Shell
.\NapCatWinBootMain.exe

    打开二维码图片（.../napcat/cache/qrcode.png），用备用 QQ 号扫码授权。

  3. 配置正向 WebSocket：访问 http://127.0.0.1:6099/webui?token=xxxx（token 见启动日志），进入「网络配置 → 新建 → WebSocket 服务器」：

    字段 值
    名称 cc-connect
    监听地址 127.0.0.1
    监听端口 3001
    消息格式 array
    启用 ✅

    保存后 netstat -an | findstr 3001 应显示 127.0.0.1:3001 LISTENING。

    WebUI 生成的 token（如 DF3YUJpjXozl~rUU）必须 填入下方配置，否则 NapCat 会反复断连（close 1005 错误）。

  4. 填写 QQ 平台配置（在 config.toml 对应 project 下）：

    [[projects.platforms]]
type = "qq"

[projects.platforms.options]
ws_url = "ws://127.0.0.1:3001"
token = "DF3YUJpjXozl~rUU"        # WebUI 获取，必填
http_url = "http://127.0.0.1:3000" # 文件发送用
allow_from = "*"
share_session_in_channel = false

  5. 启动：cc-connect，日志出现 qq: logged in qq=你的QQ号 + platform ready platform=qq 即成功。用主号给 Bot 发消息。

4.2.2 多 QQ 号分管不同项目

复制 NapCat 目录到另一路径 → 第二个实例 WebUI 配置不同端口（如 WS:4001）→ 分别扫码 → 不同 project 指向不同 ws_url。

4.2.3 常见问题

问题 原因 解决
ws read error, reconnecting... token 不匹配 config.toml token 必须与 WebUI 一致
消息发过去没回复 session 未创建 检查日志确认 OneBot 已连接
二维码过期 长时间未扫码 杀掉 QQ.exe 重启 NapCat

4.3 微信远程连接

使用 ilinkai 微信开放平台（https://ilinkai.weixin.qq.com）。Bot 是平台分配的独立联系人，非个人微信号，无封号风险。

微信 App → ilink 联系人 → ilinkai 服务器 → cc-connect → Claude Code / OpenCode

4.3.1 配置流程

  1. 编写脚手架 + 微信占位（在 config.toml 对应 project 下）：

    [[projects.platforms]]
type = "weixin"

[projects.platforms.options]
token = "待配置"
allow_from = "*"

  2. 扫码绑定：

    cc-connect --force                         # 停掉已运行的实例
cc-connect weixin setup --project <项目名>  # 终端出现二维码后微信扫码

    二维码约 60 秒过期，需尽快操作。授权后 token 自动替换为 xxxxxxxx@im.bot:060000xxxxxxxx（格式：账号ID@im.bot:密钥）。

  3. 启动：cc-connect，微信中出现 iLink Bot 联系人后发消息即可。

4.4 飞书远程连接

使用飞书自建应用作为 Bot 身份，扫码即可创建，无需注册额外账号。

飞书 App → 飞书开放平台 → cc-connect → Claude Code / OpenCode

4.4.1 配置流程

  1. 编写脚手架 + 飞书占位（在 config.toml 对应 project 下）：

    [[projects.platforms]]
type = "feishu"

[projects.platforms.options]
app_id = "待配置"
app_secret = "待配置"

    多个 Bot 就写多个 [[projects]]，各自 work_dir 不同。

  2. 扫码填凭证：

    cc-connect --force
cc-connect feishu setup --project <项目名>

    飞书扫码后引导创建自建应用，app_id 和 app_secret 自动替换占位。

  3. 发布应用：飞书管理员在「应用管理」中发布（创建新版本 → 申请发布 → 审核通过）。

  4. 使用：在飞书搜索 Bot 名称发起私聊（激活 session），拉入群聊后 @ 目标 Bot 即可：

    你 @Bot1 "帮我看看 C:\Users\ATinker"
你 @Bot2 "帮我整理技术杂记"

    每个 Bot 绑定不同 work_dir，@ 谁谁干活，互不干扰。

4.4.2 群内多 Bot 协作

  • Bot 之间不能互 @：Bot 发 @xxx 是纯文本，非飞书真正 @ 事件，对方收不到
  • relay send 用于目标 Bot 不在群内时跨项目推送消息，语法 cc-connect relay send -p <目标项目> -m "消息"，但只是文本转发，不会触发 Agent 推理
  • 能让不同 Bot 干活的唯一方式：由 你 分别 @ 它们

4.4.3 常见问题

问题 原因 解决
Bot 没反应 session 未创建 先私聊 Bot 发一条消息激活
@Bot 不响应 群内未 @ 飞书群内必须显式 @
Bot 间互 @ 无效 cc-connect 只发纯文本 你手动 @ 目标 Bot
setup 扫码无效 二维码过期 重新执行 feishu setup

4.5 多平台同时接入

一个 project 可以同时配置多个 platform：

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "C:\\Users\\你的用户名"

[[projects.platforms]]
type = "qq"
[projects.platforms.options]
ws_url = "ws://127.0.0.1:3001"
token = "你的QQ-token"
http_url = "http://127.0.0.1:3000"
allow_from = "*"
share_session_in_channel = false

[[projects.platforms]]
type = "weixin"
[projects.platforms.options]
token = "xxxxxxxx@im.bot:060000xxxxxxxx"
allow_from = "*"

[[projects.platforms]]
type = "feishu"
[projects.platforms.options]
app_id = "cli_xxxxxxxxxxxxx"
app_secret = "xxxxxxxxxxxxxxxxxx"

4.6 控制输出显示

cc-connect 默认将 AI 的思考过程、工具调用、最终回复全部发送到 IM。通过 [display] 配置可以控制输出内容：

[display]
mode = "compact"             # 显示模式：full / compact / quiet
thinking_messages = false    # 隐藏思考过程
tool_messages = false        # 隐藏工具调用进度

三种模式对比：

模式 思考过程 工具调用 最终回复
full（默认） ✅ 显示 ✅ 显示 逐段发送，每条单独消息
compact ❌ 隐藏 ❌ 隐藏 逐段发送，每段独立消息
quiet ❌ 隐藏 ❌ 隐藏 合并到一张卡片，完成后发 ✅

按项目覆盖： 也可以只为特定 project 设置不同的显示模式：

[[projects]]
name = "feishu-home"
# ...

[projects.display]
mode = "quiet"
thinking_messages = false

修改后需重启 cc-connect：cc-connect --force

posted @ 2026-07-05 02:31  VegeDodge  阅读(82)  评论(1)    收藏  举报