企业官网建设流程全解析

cc-haha 桌面端子 Agent 完整指南：任务委派、内置 Agent 与自定义配置

【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha

子 Agent（Subagent）是 cc-haha 桌面端多 Agent 协作的核心机制：主 Agent 将一个边界清晰的任务交给一个携带独立上下文的副本去执行，副本只把结论与证据交回主对话。本文以 docs/en/desktop/agents.md（中文对照见 docs/desktop/agents.md）为主线，结合 Agent 系统原理 与桌面端 AgentManager.tsx、agentStore.ts、agents.ts 的实现细节，系统讲解：什么时候该委派、六个内置 Agent 各自擅长什么、如何在「设置 → Agents」中浏览与调整、以及如何从零创建并持久化一个属于自己的 Agent。读完后，你将能在 cc-haha 桌面端独立完成子 Agent 的选型、调优与自定义开发。

什么是子 Agent

子 Agent 是「被派出去干一件明确小任务的 Claude 副本」。它与主 Agent 的最大区别在于上下文边界：子 Agent 在一个独立的上下文窗口中工作，只把结论和证据返回给主对话，中间的调查过程、工具调用记录都留在它自己的上下文里，不会污染主对话的上下文预算。

这个设计让两种任务尤其受益：

• 独立调查可以整体委派。例如「调查某个模块的认证流程」涉及多个文件、有明确的问题、范围和预期证据，交给子 Agent 后主 Agent 可以继续推进其他工作。
• 轻量查询不必委派。例如查找validateUser的调用位置，通常一次定向搜索就能完成，为此启动一个子 Agent 反而浪费启动时间和上下文传输成本。

需要强调的是，委派本身有成本：启动耗时、上下文传递、结果整合。下文会给出更具体的取舍标准。

什么时候该派，什么时候不该派

适合委派的场景（源自文档）：

1. 可以独立站住的调查—— 需要阅读多个文件，且能明确约定问题、范围和应返回的证据；
2. 可并行执行的独立工作—— 比如前端、后端分开调查；涉及代码编辑时，给每个子 Agent 划清文件归属，由主 Agent 负责整合与最终验证；
3. 有特定关注点的独立复核—— 例如把「权限边界」和「会话恢复」分开检查，而不是无差别地重复一整轮审查。

通常应留在主 Agent 的任务：

• 简单搜索；
• 已明确位置的小改动；
• 短任务且下一步必须等待其结果才能继续；
• 任何「结果立刻要用」的中间步骤。

委派后的可视化

被派出的子 Agent 会出现在活动面板的SubAgents区块，工具活动实时冒泡展示；点开任意一个，可以看到它的完整运行记录和最终结果。后台运行（run_in_background）的子 Agent 同样如此——你不必等它跑完，就能实时看到它在做什么。这一交互对应的数据来自桌面端的 subagent API 模块 subagents.ts 与其测试 subagents.test.ts。

内置 Agent：开箱即用的六个角色

无需任何配置即可直接使用的内置 Agent 共有六个，文档给出的速览表如下：

在会话中可以直接点名委派（「用 Explore 去找一下……」），也可以不指定，让 Claude 根据任务性质自行判断该派谁。

各内置 Agent 的工具池与模型特征

根据 Agent 系统原理 中记录的内部实现，六个内置 Agent 在工具池、模型与读写能力上有明确分工：

注意两个容易被忽略的点：

• Explore 虽然不能改文件，但它的工具池包含 Bash—— 它能执行任意命令，只是无法落盘写文件；
• 文档明确提示，Explore与claude-code-guide默认走 Haiku（快、便宜），statusline-setup走 Sonnet，这是按「速度与成本」而非「输出质量」做的出厂选择——如果你更看重质量，可以按后文方法单独调整。

浏览已安装的 Agent：设置 → Agents

打开桌面端设置 → Agents，即可看到当前环境下的全部 Agent（该入口实现在 AgentManager.tsx，由 Settings.tsx 挂载）。

页面布局分两层：

• 顶部三张汇总卡：Agent 总数、当前生效数（active）、来源类型数（sources）。对应代码中 SummaryCard 渲染的三个统计项，其中生效数来自activeAgents，来源数按AGENT_SOURCE_ORDER过滤出非空分组后计数。

• 来源分组列表：按固定顺序分组展示，顺序为

  User（用户）→ Project（项目）→ Local（本地）→ Managed（托管策略）→ Plugin（插件）→ CLI arg（CLI 参数）→ Built-in（内置）

  这一顺序在源码中定义于 AGENT_SOURCE_ORDER，对应的 Agent 来源类型（userSettings/projectSettings/localSettings/policySettings/plugin/flagSettings/built-in）定义在 agents.ts。

同名覆盖规则

当多个来源存在同名 Agent 时，排位靠前的来源会覆盖靠后的，被覆盖的那个会被标记为「Overridden by X」。这一点在列表行的 overriddenBy 徽标 和详情页都有体现，且底层列表数据（overriddenBy字段）由服务端跨来源统一计算，见 agentStore.ts 中「覆盖关系需要全量列表才能一致」的注释。

日常最常打交道的两组：

• User（用户）：你自己创建的 Agent，对所有项目生效，文件存放在~/.claude/agents/；
• Project（项目）：仅对当前项目生效，文件存放在项目目录的.claude/agents/下，会随仓库一起分发。

详情页与行内操作

点击任意一行进入详情页，可以看到该 Agent 的模型、推理强度（effort）、工具范围、完整系统提示词，实现见 AgentDetailView（其中DetailStat展示配置模型与 effort，MarkdownRenderer 渲染系统提示词）。

• 内置与插件来源是只读的：详情页右上角显示锁形「只读」标记（LockKeyhole图标 +settings.agents.readOnly文案），没有编辑/删除按钮；只有用户与项目来源可编辑。
• 悬停行出现操作按钮：用户/项目 Agent 显示「编辑」「删除」；内置 Agent 显示「调整模型」（AgentRowActions组件，AgentManager.tsx）。编辑和删除也会同步出现在详情页右上角。
• 可调整的内置 Agent：只有overridable === true的内置 Agent 才显示「调整模型」按钮（agents.ts 中overridable字段的注释明确：仅内置 Agent 可通过 override 调整模型与 effort）。

调整内置 Agent 的模型与推理强度

内置 Agent 的模型与 effort 是可覆盖的，但系统提示词、工具范围和颜色不可改，仍由内置定义锁定。

操作入口与可选项

点击内置 Agent 行上的「调整模型」，或详情页右上角同名按钮，打开覆盖弹窗（BuiltInAgentOverrideModal）。只有两项可编辑：

• 模型（Model）：内置默认 / 继承主会话（Inherit from parent）/ Haiku / Sonnet / Opus / Fable 别名 / 当前 Provider 已配置的模型；
• 推理强度（Effort）：内置默认，或 low / medium / high / xhigh / max 五档。

其中模型别名常量定义在 BUILT_IN_MODELS，effort 档位定义在 EFFORTS。模型选择器（AgentModelSelector）会列出当前 Provider 的可用模型、四个别名与「继承」选项。

「内置默认」与「继承主会话」的区别

这是文档特别强调的易混点，二者不是一回事：

• 内置默认（Built-in default）：该 Agent 出厂时钉死的模型。以Explore为例，就是它默认绑定的 Haiku；
• 继承主会话（Inherit from parent）：跟随主对话当前正在使用的模型。

想恢复出厂设置，选「内置默认」或直接点「Reset to built-in default」按钮。底层实现上，弹窗保存时选择「内置默认」会提交null，从而删除该覆盖记录而不是写入默认值的字面量——见 AgentManager.tsx 中「永远不要把默认值的字面量写死进用户配置文件」的注释逻辑，以及 agentStore.ts 中「内置默认是什么由服务端决定，store 绝不在本地重建」的注释。

覆盖记录的落盘位置

覆盖写入~/.claude/settings.json的builtInAgentOverrides字段，对所有项目生效。手工编辑等价于：

{ "builtInAgentOverrides": { "Explore": { "model": "sonnet", "effort": "low" }, "general-purpose": { "effort": "high" } } }

（示例来自 Agent 系统原理。）key 是 spawn 时使用的 agentType，大小写敏感。

覆盖的几个易踩规则

1. 只有 model / effort 两个字段可改。覆盖不会改变source（仍是built-in），因此内置 Agent 的工具特权保持不变；
2. 清除覆盖 = 删除字段，而不是写inherit。各内置 Agent 的出厂默认互不相同（Explore默认haiku、Plan默认继承父会话、general-purpose甚至不写 model），所以model: "inherit"是一个正常的取值（表示跟随主会话），与「恢复默认」含义不同；
3. 未知的 agentType 会被忽略但不会被清理：内置 Agent 集合随 feature flag 与 entrypoint 变化，自动清理会在开关翻转时销毁有效配置；
4. 同名用户 Agent 会完全遮蔽内置 Agent：如果你手写了一个name: Explore的用户 Agent，它会把内置的Explore完全盖住，此时调整内置的模型不会产生任何效果——弹窗里会提示这一点（对应 AgentManager.tsx 中overrideShadowed警告逻辑）；
5. 策略限制：当组织策略strictPluginOnlyCustomization包含agents时，用户级与项目级覆盖在解析阶段即被忽略，只有 managed 来源生效；
6. 生效时机：与 Agent Markdown 文件一样，手工改 settings.json 不会自动作用于已在运行的会话；桌面端保存时会触发一次会话重载，手工改文件则需要重启会话或执行/reload-plugins。

模型与 Provider 的绑定关系

Agent 配置里保存的是模型 ID，而不是 Provider。模型选择器列出的是当前 Provider 的可用模型；以后如果切换 Provider：

• 别名（Haiku / Sonnet / Opus / Fable）会按新 Provider 的映射重新解析；
• 完整模型 ID则要求新 Provider 也支持该模型，否则不可用。

创建自己的 Agent

点击「设置 → Agents」右上角的Create Agent按钮，打开创建弹窗（AgentFormModal）。各字段说明如下：

1. 配置范围（Scope）—— 用户还是项目。选「项目」时需确认目标项目路径（弹窗内提供目录选择器DirectoryPicker，仅创建模式可选，编辑模式下 Scope 被禁用）。用户范围写入~/.claude/agents/，项目范围写入目标项目的.claude/agents/；
2. 名称（Name）—— 1–64 位小写字母、数字、连字符或下划线。这是主 Agent 调用它时使用的名字。源码中校验正则见 NAME_PATTERN：/^a-z0-9?$/，即必须以字母或数字开头和结尾，中间可含连字符与下划线，例如code-reviewer；
3. 描述（Description）—— 说明主 Agent 应该在什么场景下委派给它。这是最重要的字段：主 Agent 正是靠它来决定要不要调用这个 Agent。写得太含糊，这个 Agent 就永远不会被叫到。创建/编辑时该字段为必填（descriptionRequired校验见 handleSubmit）；
4. 系统提示词（System prompt）—— 定义职责、边界和预期输出。创建模式下必填；
5. 模型（Model）—— 继承主 Agent，或选择 Haiku / Sonnet / Opus / Fable 别名，或选择当前 Provider 已配置的模型。简单重复的活交给 Haiku 更快更省；
6. 推理强度（Effort）—— 继承，或指定 low / medium / high / xhigh / max。模型不支持某档时会自动降级或忽略该字段；
7. 工具（Tools）—— 三选一：全部工具（inherit）、不允许使用工具（none）、自定义列表（custom）。自定义模式下，内置工具按「读取与搜索 / 修改文件 / 执行命令 / 工作流」四类分组勾选（分组元数据见 TOOL_METADATA 与 ToolPicker），下方还有一个自由输入框，用于填写 MCP 工具名或形如Bash(git:*)的权限规则；自由输入框的解析器 parseTools 专门处理了括号配对，因此带参权限规则可以安全地包含空格与逗号；
8. 颜色（Color）—— 可选，仅用于在界面上区分不同 Agent。可选色板见 AGENT_COLORS，共 9 种（red / orange / yellow / green / blue / purple / pink / cyan）。

最小权限原则（文档中的原话提示）：只给任务必需的工具。一个只负责读代码并汇报结论的 Agent，不需要 Write 和 Bash——权限收窄了，它跑偏的空间也就小了。

保存与热重载行为

保存操作会把配置写成 Markdown 文件到对应目录，并尝试刷新当前会话。刷新失败不会回滚已经写好的文件——重启后定义仍然生效。桌面端的完整行为链在 agentStore.ts 中可见：

• 增/改/删/覆盖都会走runAgentMutation（agentStore.ts）：先调用 agentsApi 的create/update/delete/setOverride/clearOverride接口，再list全量刷新（注释明确：覆盖关系跨来源计算，只有全量列表才一致）；
• 随后通过POST /api/agents/reload（agentsApi.reload，超时 120 秒）热重载运行中的会话；若会话未运行或重载失败，会返回not_running/failed原因，界面顶部出现不阻塞操作的警告条（mutationWarning+ 重试按钮，见 AgentManager.tsx）。

Agent 文件的格式与来源优先级

标准 Markdown 定义格式

在用户或项目的agents目录下创建.md文件即可定义 Agent，frontmatter 示例（来自 Agent 系统原理）：

--- name: code-reviewer description: 专业代码审查代理 tools: - Read - Grep - Glob - Bash model: sonnet effort: high permissionMode: dontAsk maxTurns: 10 --- 你是一个专业的代码审查员。请检查以下方面： 1. 代码质量和可读性 2. 潜在的安全漏洞 3. 性能问题 4. 最佳实践遵循

可配置字段一览

继承的写法：想继承当前会话，最清楚的做法是省略对应字段——不写model就继承主会话模型，不写effort就继承当前会话的推理强度。model: inherit是模型字段的等价显式写法；effort没有inherit值。另外需注意：Agent工具的单次调用没有effort参数，因此 effort 应在 Agent 定义或会话层设置；整数形式的effort仅为既有 SDK/JSON 兼容而保留，桌面端 Agent 管理器只写入上述五个命名档位。

同名 Agent 的来源优先级

多个来源定义同名 Agent 时，实际生效的定义按以下优先级选择（从高到低，见 Agent 系统原理）：

1. 策略 Agent（policy）—— 组织托管策略；
2. CLI 参数 Agent（flag）—— 通过--agents注册；
3. 项目 Agent（project）—— 项目目录的.claude/agents/；
4. 用户 Agent（user）——~/.claude/agents/；
5. 插件 Agent（plugin）—— 由插件提供；
6. 内置 Agent（built-in）—— 系统预定义。

桌面端列表会展示被覆盖的定义及其来源，但真正 spawn 时使用的是优先级最高的活动定义。

模型与推理强度的解析优先级

模型（从高到低）：

1. CLAUDE_CODE_SUBAGENT_MODEL的具体模型值（设为inherit时不锁定模型）；
2. 本次Agent({ ..., model: "..." })调用指定的模型；
3. Agent Markdown frontmatter 中的model；
4. settings.json 中builtInAgentOverrides指定的model（仅内置 Agent）；
5. 主会话模型。

推理强度（从高到低）：

1. CLAUDE_CODE_EFFORT_LEVEL；
2. Agent Markdown frontmatter 中的effort；
3. settings.json 中builtInAgentOverrides指定的effort（仅内置 Agent）；
4. 当前会话的 effort；
5. 模型默认值。

low、medium、high、xhigh、max是否可用取决于解析后的真实模型及提供商能力：Claude 模型会向下回退到可用档位，其他提供商按各自的模型目录规范化，不支持 effort 的模型不会应用该字段。子 Agent 通常继承主会话的扩展思考（extended thinking）开关，但解析后的模型强制要求优先（例如 Fable 5 会规范化为 adaptive thinking）。

权限模式参考

每个 Agent 可设置的权限模式（permissionMode）：

快速参考

本文所有 UI 行为均可在 AgentManager.tsx 及其配套的 agentStore.ts、agents.ts 中找到对应实现与测试（如 AgentManager.test.tsx、agentStore.test.ts），可继续深入阅读验证。

【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha