编程子智能体 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

Crab Claw 内置的编程子智能体（Open Coder）不是一个简单的代码补全工具，而是一个拥有完整自主能力的编程智能体——它能独立规划、自主执行、实时汇报，主系统替代人类担任监工角色，全程无人值守。

为什么选择 Open Coder

自主规划与执行

接收一句话需求后自动生成执行计划，三层决策系统（规则→LLM→人类）自动审批，无需人工逐步确认。

可视化终端监控

独立的 Bubble Tea TUI 终端窗口，实时显示计划进度、代码 Diff、交互面板。像看 CI/CD 一样看 AI 编程。

心跳与崩溃恢复

周期性心跳汇报执行进度，超时自动告警。上下文压缩子系统确保长任务不溢出。

Rust MCP 编辑引擎

基于 oa-coder Rust MCP Server 的代码编辑能力，9 层模糊匹配确保精准编辑，原生性能零延迟。

技术架构分析

自动分析项目结构、技术栈、依赖关系、代码行数统计。为架构文档生成和著作权申请提供数据支撑。

软件著作权一键申请

集成中国版权保护中心，从代码分析到材料生成到在线提交，编程智能体全流程自动化。

架构总览

shell

┌──────────────────────────────────────────────────────────────┐
│ 用户: "帮我重构 auth 模块" → 主系统 → 放手离开                 │
├──────────────────────────────────────────────────────────────┤
│ Gateway Server (枢纽)                                         │
│  ├─ SpawnSubagent → handleSubagentMessage()                  │
│  │   ├─ MsgHelpRequest → SupervisorLLM 自主回答               │
│  │   ├─ MsgPlanProposal → 三层决策 (规则→LLM→黑名单)          │
│  │   ├─ MsgHeartbeat → 更新状态 + 广播 + ack                  │
│  │   └─ MsgStatusUpdate → 进度更新                            │
│  ├─ Broadcaster → WS 事件 → 系统终端窗口                      │
│  └─ LaunchCoderTerminal() → 自动弹出宿主终端                   │
├──────────────────────────────────────────────────────────────┤
│ 系统终端窗口 (独立进程)                                         │
│  crabclaw coder-terminal --session=XYZ --gateway=ws://...    │
│  ├─ 计划/进度/Diff/交互面板 (Bubble Tea TUI)                  │
│  └─ 常驻运行，仅收到 q/Ctrl+C 时退出                          │
├──────────────────────────────────────────────────────────────┤
│ Open Coder (独立 LLM Session)                                 │
│  ├─ 系统提示词: BuildCoderSubagentSystemPrompt()              │
│  ├─ propose_plan → 阻塞等待 → report_heartbeat               │
│  └─ request_help → SupervisorLLM 自主回答                     │
├──────────────────────────────────────────────────────────────┤
│ oa-coder (Rust MCP Server)                                    │
│  └─ 9 层模糊匹配编辑引擎                                      │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ 用户: "帮我重构 auth 模块" → 主系统 → 放手离开                 │
├──────────────────────────────────────────────────────────────┤
│ Gateway Server (枢纽)                                         │
│  ├─ SpawnSubagent → handleSubagentMessage()                  │
│  │   ├─ MsgHelpRequest → SupervisorLLM 自主回答               │
│  │   ├─ MsgPlanProposal → 三层决策 (规则→LLM→黑名单)          │
│  │   ├─ MsgHeartbeat → 更新状态 + 广播 + ack                  │
│  │   └─ MsgStatusUpdate → 进度更新                            │
│  ├─ Broadcaster → WS 事件 → 系统终端窗口                      │
│  └─ LaunchCoderTerminal() → 自动弹出宿主终端                   │
├──────────────────────────────────────────────────────────────┤
│ 系统终端窗口 (独立进程)                                         │
│  crabclaw coder-terminal --session=XYZ --gateway=ws://...    │
│  ├─ 计划/进度/Diff/交互面板 (Bubble Tea TUI)                  │
│  └─ 常驻运行，仅收到 q/Ctrl+C 时退出                          │
├──────────────────────────────────────────────────────────────┤
│ Open Coder (独立 LLM Session)                                 │
│  ├─ 系统提示词: BuildCoderSubagentSystemPrompt()              │
│  ├─ propose_plan → 阻塞等待 → report_heartbeat               │
│  └─ request_help → SupervisorLLM 自主回答                     │
├──────────────────────────────────────────────────────────────┤
│ oa-coder (Rust MCP Server)                                    │
│  └─ 9 层模糊匹配编辑引擎                                      │
└──────────────────────────────────────────────────────────────┘

三层自动决策系统

Open Coder 提交执行计划后，系统通过三层决策自动审批，最大化减少人工干预：

shell

propose_plan(proposal)
     │
     ▼
L1: SupervisorPolicyEngine (规则引擎, O(1), 零 LLM 调用)
  ├─ scope 内 + 白名单命令 + 预算内 → 自动批准 ✓
  ├─ scope 外 / 未知命令 / 超预算 → 升级到 L2
  └─ 硬编码黑名单 (rm -rf /, git push --force main) → 自动拒绝 ✗
     │
     ▼
L2: SupervisorLLM (语义评估, 1-3s, 单轮 LLM 调用)
  ├─ 合理 → 批准 ✓
  └─ 不合理 → 拒绝或升级到 L3
     │
     ▼
L3: 人类确认 (CoderPlanConfirmManager → 终端/消息频道)
propose_plan(proposal)
     │
     ▼
L1: SupervisorPolicyEngine (规则引擎, O(1), 零 LLM 调用)
  ├─ scope 内 + 白名单命令 + 预算内 → 自动批准 ✓
  ├─ scope 外 / 未知命令 / 超预算 → 升级到 L2
  └─ 硬编码黑名单 (rm -rf /, git push --force main) → 自动拒绝 ✗
     │
     ▼
L2: SupervisorLLM (语义评估, 1-3s, 单轮 LLM 调用)
  ├─ 合理 → 批准 ✓
  └─ 不合理 → 拒绝或升级到 L3
     │
     ▼
L3: 人类确认 (CoderPlanConfirmManager → 终端/消息频道)

决策层	响应时间	消耗	适用场景
L1 规则引擎	<1ms	零 LLM	常见操作：文件读写、代码编辑、测试运行
L2 LLM 评估	1-3s	单轮	边界操作：新依赖安装、配置修改
L3 人类确认	用户决定	零	高风险：系统级操作、生产环境变更

中途再规划

propose_plan 支持两种类型：

initial：首次计划，全量评估
revision：执行中修订，只评估新增部分（delta 评估），比首次更宽容

版本号自动追踪（1=initial, 2+=revision），历史计划自动归档。

可视化终端

自动弹出的独立终端窗口，基于 Bubble Tea TUI 框架构建：

bash

# 自动弹出（spawn 子智能体时 Gateway 自动调用）
crabclaw coder-terminal --session=XYZ --gateway=ws://localhost:19001
# 自动弹出（spawn 子智能体时 Gateway 自动调用）
crabclaw coder-terminal --session=XYZ --gateway=ws://localhost:19001

终端面板

面板	功能
计划面板	显示当前执行计划、审批状态、修订历史
进度面板	实时进度条、当前步骤、已完成步骤列表
Diff 面板	代码变更实时预览，语法高亮
交互面板	人类指令输入、L3 审批确认

设计特点

零侵入主 TUI：独立进程，不修改主聊天界面的任何代码
自动弹出：Gateway 通过 LaunchCoderTerminal() 在新窗口中启动，启动失败不影响主流程
常驻运行：终端窗口持续显示，直到用户主动关闭（q/Ctrl+C）
跨平台：macOS shellQuote()、Linux 参数数组、Windows cmdQuote() 三平台转义保护

心跳与进度监控

Open Coder 在执行过程中通过 report_heartbeat 工具周期性汇报进度：

消息类型	方向	用途
`plan_proposal`	子→主	提交执行计划
`plan_decision`	主→子	批准/拒绝决策
`heartbeat`	子→主	周期性进度汇报
`heartbeat_ack`	主→子	确认 + 可选指令

超时检测：心跳间隔超过 300s 触发 coder.heartbeat.timeout 告警事件。

5 阶段感知心跳：心跳内容随执行阶段变化——分析阶段汇报发现、规划阶段汇报方案、编码阶段汇报进度、测试阶段汇报结果、收尾阶段汇报总结。

oa-coder 编辑引擎

Open Coder 的代码编辑能力由 Rust 实现的 MCP Server 驱动：

9 层模糊匹配

当 LLM 输出的代码片段与文件内容不完全匹配时，oa-coder 逐层尝试：

层级	匹配策略	说明
L1	精确匹配	完全一致
L2	去尾空白	忽略行尾空格/制表符
L3	大小写不敏感	忽略大小写差异
L4	缩进归一化	统一缩进格式
L5	空行折叠	忽略多余空行
L6	注释剥离	忽略注释差异
L7	前缀匹配	匹配开头部分
L8	相似度匹配	基于编辑距离
L9	上下文锚定	根据上下文定位

原生性能：Rust 实现，文件操作延迟 <1ms，不受 LLM 输出波动影响。

上下文生命周期管理

长编程任务容易导致上下文窗口溢出。Open Coder 内置专用压缩子系统：

心跳驱动压缩：每次心跳检查上下文使用率，超过阈值自动触发压缩
计划主轴摘要：围绕执行计划的 7 段结构化摘要，保留关键上下文
跨会话恢复：压缩后的摘要可用于恢复执行状态
双重压缩防护：coderCompressed 标志位防止重复压缩
UHMS 记忆注入：压缩后自动将关键信息写入记忆系统

技术架构分析能力

Open Coder 不仅能写代码，还能深度分析项目架构：

技术栈识别：自动识别语言、框架、构建工具（通过 go.mod/package.json/Cargo.toml 等）
代码统计：通过 cloc 等工具分析代码行数、语言分布
依赖分析：解析依赖树，识别关键依赖和版本冲突
架构图生成：分析模块关系，输出结构化架构描述
运行环境推理：从 Dockerfile/docker-compose 推断部署环境

软件著作权一键申请

Open Coder 集成了中国版权保护中心（ccprccn.com.cn），实现软件著作权登记全流程自动化：

六层集成架构

shell

┌──────────────────────────────────────────────────────────────┐
│  L6: 子智能体内嵌管理面板                                      │
│      账户管理 · 材料预览 · 提交确认 · 进度追踪                  │
├──────────────────────────────────────────────────────────────┤
│  L5: RPC 层 (copyright.* namespace)                           │
├──────────────────────────────────────────────────────────────┤
│  L4: 业务逻辑层                                               │
│      AccountStore · SourceClipper · DocumentBuilder ·         │
│      SubmissionEngine · StatusTracker                         │
├──────────────────────────────────────────────────────────────┤
│  L3: 登录执行器层 (复用 LoginExecutor 模式)                    │
├──────────────────────────────────────────────────────────────┤
│  L2: 浏览器自动化层 (CDP/Playwright)                          │
├──────────────────────────────────────────────────────────────┤
│  L1: 安全存储层 (Keyring + Encrypted Config)                  │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│  L6: 子智能体内嵌管理面板                                      │
│      账户管理 · 材料预览 · 提交确认 · 进度追踪                  │
├──────────────────────────────────────────────────────────────┤
│  L5: RPC 层 (copyright.* namespace)                           │
├──────────────────────────────────────────────────────────────┤
│  L4: 业务逻辑层                                               │
│      AccountStore · SourceClipper · DocumentBuilder ·         │
│      SubmissionEngine · StatusTracker                         │
├──────────────────────────────────────────────────────────────┤
│  L3: 登录执行器层 (复用 LoginExecutor 模式)                    │
├──────────────────────────────────────────────────────────────┤
│  L2: 浏览器自动化层 (CDP/Playwright)                          │
├──────────────────────────────────────────────────────────────┤
│  L1: 安全存储层 (Keyring + Encrypted Config)                  │
└──────────────────────────────────────────────────────────────┘

全流程自动化

步骤	由谁完成	说明
分析代码语言/行数/架构	Coder 自己	读取项目文件 + bash(cloc)
撰写软件说明书	Coder 自己	基于架构分析用 LLM 生成
推理运行环境	Coder 自己	分析 Dockerfile/go.mod
源代码裁剪（前后各 30 页）	copyright 模块	纯机械操作
PDF/Word 文档输出	copyright 模块	纯格式转换
浏览器填表上传	copyright 模块	CDP 自动化
提交进度追踪	copyright 模块	定时轮询状态

安全设计

不代填密码：用户手动在浏览器中登录版权中心
敏感信息加密：密码存 OS Keyring，证件号字段自动脱敏
Cookie 持久化：0600 权限文件存储
多账户支持：支持多个著作权人主体，独立管理

能力树工具

Open Coder 在能力树中注册了 2 个专属工具：

工具	意图层级	审批类型	说明
`propose_plan`	task_write	plan_confirm	提交执行计划（阻塞等待审批）
`report_heartbeat`	task_light	无	周期性进度汇报（非阻塞）

启用自主模式

在 crabclaw.json 中启用自主编程模式：

json

{
  "subAgents": {
    "openCoder": {
      "autonomousMode": true
    }
  }
}
{
  "subAgents": {
    "openCoder": {
      "autonomousMode": true
    }
  }
}

默认关闭（false），开启前行为与传统委托模式完全一致。

实时 WS 事件

所有编程子智能体事件通过 WebSocket 广播，终端和 UI 均可订阅：

事件	触发时机
`coder.plan.auto_approved`	规则引擎 L1 自动批准
`coder.plan.llm_decided`	LLM L2 决策完成
`coder.plan.requested`	升级到人类 L3 确认
`coder.plan.rejected`	黑名单自动拒绝
`coder.heartbeat`	心跳进度更新
`coder.heartbeat.timeout`	心跳超时告警 (300s)
`coder.help.auto_answered`	自主回答 Coder 求助
`coder.terminated`	会话终止

相关文档：子智能体工厂 · 能力树与权限 · 安全与审批