一款在终端中运行的 AI 编程智能体(coding agent)——一个从零手写的 Agent Harness,用 Go 实现。
设计目标:把「用框架」变成「掌握框架」。核心机制(agent 循环、会话、上下文、记忆、工具运行时、权限、子 agent 编排、评测审计)全部手写,底层模型框架只退化为一个被隔离的「模型客户端」。
这个项目不是又一个「调 API 的壳」,而是对 AI 编程智能体全部核心机制的一次系统实现。以下设计经过了从 P0 到 P11 共 12 个阶段的演进打磨,每一条都对应真实踩过的坑:
| 不变量 | 含义 | 解决的问题 |
|---|---|---|
| 事件驱动的三层循环 | run / turn / step 三层,流式增量(delta)与定稿消息分离 | 可观测、可中断、可测试,UI 与执行解耦 |
| 追加式 JSONL 是唯一真相源 | 会话转录 = trace = eval 输入,同一份文件 | 审计、恢复、回放、评测共用一套数据 |
| Tool/Runtime 分离 + 纯函数审批 | Tool(面向模型的声明)≠ Runtime(进程引擎);审批 = Resolve(tier, mode) 纯函数 |
无副作用、可单测、权限边界不被绕过 |
agent.Context 接口把循环与上下文治理解耦:每一步都从 session 重新 Build() 模型输入,不持有私有消息切片。因为有三个写入方(steering 注入、mid-turn 压缩、工具结果记录)随时在改真相源——内存副本必然过期。这是 mid-turn 压缩能安全生效的前提。
- L6 剪枝(零模型调用):保护窗内保留最近 40k token 工具结果,旧结果替换为
[Output truncated · artifact://N]占位,永不拆散 tool_call/tool_result 配对; - 外置(shake):更早的大块结果写入 artifact 留指针;
- 摘要(模型调用):六字段任务导向摘要(目标/状态/决策/文件/失败/下一步),切点必须落在 user 消息或无工具调用的 assistant 消息——绝不把「工具调用」与「它的结果」劈开(否则 API 报
insufficient tool messages)。
触发点覆盖 turn 内:mid-turn 压缩(下一次模型调用前)修掉了「同一 turn 里 20 次工具调用撑爆窗口」;溢出与重试互斥——溢出不该走重试通道。
主 agent 派发子 agent 不是「并行调几个函数」,而是一组有契约、可观察、可干预、寿命受约束的执行单元:
- TaskBatch 契约 + 预检:整批共享 Goal/Constraints/Contract;任务描述 < 40 字符整批拒绝(外包者看不到父历史,一句话派发只能靠猜);深度上限、同名冲突、spawn 白名单逐项校验;
- 每人一份独立装备:独立 sidecar 会话(可审计、可 revive)、独立 Bash/cwd(
cd不影响他人)、裁剪过的工具集(reviewer 只有只读工具)、继承父审批而非 yolo(派发 ≠ 放行); - yield 三态完成协议:
yield(data)终止 /yield(data, section)增量提交 /yield(error)主动放弃;产出按 outputSchema 校验,不合格退回重试 ≤3 次; - 完成度五层保证:契约 → 协议 → 驱动(idle 提醒 ≤3 次,第 3 次工具集只剩 yield;软预算 → 1.5× 强制收尾 → 宽限 5 次硬杀)→ 验证(completed ≠ 验收,须派 reviewer)→ 可恢复(失败也保留转录与部分产物,可
hub send唤醒续跑); - 状态机如实记账:
pending/running/idle/completed/failed/timeout/killed/aborted/parked——超时就是 timeout,被杀就是 killed,绝不把半成品报成 completed; - 后台作业 + hub 邮箱:
background: true立即返回 job id,结果恰好一次投递回主会话;子 agent 间通过hub {list,send,inbox,wait,jobs,cancel}协调接口契约,消息以[hub from X]记入对方会话可审计;后台作业挂在 Manager 根 ctx(Esc 不会连带取消); - 可 resize 并发闸:令牌通道 + 「债」计数,缩容不打断正在跑的任务。
- SQLite + FTS5 trigram 分词(unicode61 不切中文,trigram 才能搜中文);
- 召回是纯代码算术融合:
0.45·bm25 + 0.2·importance + 0.15·recency + 0.1·access + 0.1·scopeBoost,recency 72h 半衰期; - FTS 查询清洗:问句永不直传
MATCH(标点会语法报错且被静默吞掉)——分词、CJK 滑窗、双引号包裹、OR 连接; - upsert 去重(key / 近重复 trigram Jaccard ≥0.85)、失效(superseded_by)、双库(global + project);
- 按用户 turn 刷新 + turn 内前缀缓存:新用户消息触发召回刷新,同一轮的工具循环复用前缀,避免“会话首轮召回后一直陈旧”;
- 项目知识层
file_notes+ 项目地图注入,跨会话减少「从零 explore」的重复读取。
数据落在 ~/.codeclaw/projects/<encoded-cwd>/,按规范化 cwd 分桶(先 EvalSymlinks),同一目录不同写法落同一桶,不同项目互不可见——修掉「所有项目会话/记忆混在一个仓库目录」的根因。配置三层合并:用户 → 项目 → 仓库内 legacy。
- 条目一旦写入不可变,可变状态只有 leaf;
reset_boundary封存旧上下文;fork 保留 id 链复制; - 回放修复悬空 tool_call:Ctrl+C 打断后留下「有调用没结果」,恢复时自动合成
[interrupted: tool did not run]——这是/resume首个请求不被 API 拒绝的原因(仅在内存修复,不落盘)。
permissions.{allow,ask,deny}规则语法tool(args*)通配,五步决策(工具 deny → 用户 deny → Override 强制询问 → yolo 放行其余调用 → 工具显式 policy → 用户规则 → tier×mode),deny 与高风险 Override 在 yolo 下也生效;参数规则会同时匹配解码值与规范化路径,不能靠 JSON 转义或foo/../.env绕过;- 工具调用在权限匹配前执行运行时 Schema 校验,拒绝缺失必填项、类型/枚举/嵌套约束错误和未知顶层参数;模型、MCP、
permissions.allow等能力只能由用户级配置授予,项目配置只能收紧审批; - bash 危险命令分类器(纯函数):按 shell 词法切段逐段保守判定——只读白名单(git status/go list)免审批;危险模式(
rm -rf、curl | sh、sudo、fork bomb)标记为 Override,所有模式都强制询问;不认识或会执行项目代码的命令回落 exec 档(write 模式询问;漏判危险是事故,误判只读只是多一次审批); - bash 超时 + 进程组回收:默认 120s,SIGTERM 进程组 → 5s 后 SIGKILL(只杀直接子进程留不住管道孙进程);env 自动剔除密钥类(
*API_KEY*/*TOKEN*/*SECRET*)。
- JSONL 即 trace;eval 夹具
prompt.md + input/ + expected/,字节 diff 验证,坚持不用 LLM judge; - 记忆召回提供可复现的
HitRate@K / Recall@K / MRR / DuplicateRate离线评测,覆盖跨库排序与重复压力; - 最有价值的部分:脚本化 fake model 回归套件——不联网、不花钱、几秒钟跑完,钉死 harness 自身行为(yield 三态、schema 重试、idle 阶梯、软预算三段、状态机、并发闸缩容、后台投递恰好一次)。harness 的正确性不依赖真实模型。
einoclaw-build/
├── cmd/
│ ├── agent/ TUI / headless 入口(装配层:配置、工具工厂、Manager)
│ └── eval/ 评测入口
└── internal/
├── message/ 共享消息类型(零依赖:Role + ContentBlock 四类块)
├── model/ 【唯一 import 模型框架的包】流式模型客户端 + 错误分类
├── agent/ 事件驱动三层循环 + AgentEvent + 流累积器 + Context 接口
├── session/ 追加式 JSONL 会话(entry 树/回放/压缩/fork)+ 多会话 Manager
├── context/ 上下文真相源:Build/Record/ShouldCompact/Compact/RecoverOverflow
├── memory/ SQLite + FTS5 多信号召回 + file_notes 项目知识
├── instructions/ L1 项目指令层(AGENTS.md 层级 + @import + RULES 粘性)
├── tool/ Tool 接口 + Registry + Executor(审批+并发+截断)+ MCP 桥
├── runtime/ Sink(截断落盘)+ ArtifactStore(URL 路由)+ Bash(独立 cwd + 分类器)
├── permission/ 纯函数审批策略(tier × mode × 规则引擎)
├── subagent/ 委派运行时:发现/预检/驱动/yield/schema/名册/邮箱/后台作业/hub
├── bus/ 进程内发布订阅(非阻塞,满即丢,只服务观测)
├── paths/ 数据落点:$CODECLAW_HOME、按 cwd 分桶的项目目录
├── trace/ JSONL 聚合统计
├── eval/ 夹具 + 字节 diff
└── tui/ BubbleTea TUI + markdown 渲染 + 审批弹窗 + Agent Hub 面板
依赖方向单向无环:cmd → agent/subagent → {model, session, context, memory, tool, permission, runtime, bus} → message。
生产运行时初版已接入:文件工具绑定工作区、默认原生进程沙箱、Go AST/LSP、可恢复变更日志与可配置验证门禁。升级前请阅读 配置与使用说明 和 逐步设计/代码构造。默认禁止子进程联网;Go 工具链/模块缓存等额外读取目录在用户配置中授权。
# 配置(复制模板并填入模型 API key)
cp example.yaml config.yaml
# 示例模型:deepseek-v4-flash(见 config.yaml)
# 交互式 TUI
go run ./cmd/agent
# Headless(非交互,适合脚本/CI;等待后台作业最多 N 个)
go run ./cmd/agent -p "你的任务" --wait-jobs 3
# 评测
go run ./cmd/eval <eval-name>
# 跑测试(含 fake model 回归套件)
go test ./...常用命令:/new 新会话 · /sessions 列会话 · /resume <id> 恢复 · /agent <Name> <文本> 唤醒 parked 子 agent · ctrl+a Agent Hub 面板 · ctrl+e steering 注入。
TUI 启动页使用青蓝/紫色 CODECLAW 电路字标,窄窗口自动切换紧凑布局。顶部显示运行/审批状态,输入框随内容增高(最多 5 行)。
| 操作 | 快捷键 |
|---|---|
| 发送 / 换行 | Enter / Ctrl+J(或终端支持的 Shift+Enter) |
| 中断当前运行,保留界面 | Esc(Hub 打开时先关闭面板;审批中表示拒绝) |
| 注入修正 / 退出 | Ctrl+E / Ctrl+C |
| 翻阅历史 / 回到最新输出 | 滚轮、PgUp、PgDown / Ctrl+End |
| 补全命令 / 查看帮助 | Tab / /help |
| 查看长审批参数 | 审批中使用滚轮、PgUp、PgDown 或上下方向键 |
翻阅历史时,新输出保持当前阅读位置;发送消息或按 Ctrl+End 恢复跟随。Tab 补全唯一匹配,多个匹配时显示候选命令(包含可由用户调用的 skills)。
持久化 CLI 的并发与数据保护回归样例见 examples/kvnote,可运行 go test -race ./examples/kvnote。运行审计、消息唤醒和安全恢复设计见 可靠性说明。
approval_mode: write # write | always-ask | yolo(默认 write:read/write 放行、exec 询问)
delegation_mode: preferred # conservative | preferred | always(always = 主 agent 只有只读 + task/remember)
permissions:
allow: ["bash(git status*)", "bash(go test*)", "read(**)"]
# deny: ["bash(rm -rf *)", "read(./.env*)"]
bash:
timeout: 120s # 超时 SIGTERM 进程组、5s 后 SIGKILL;env 自动剔除密钥类
subagent:
max_concurrency: 4 # 并行子 agent 上限(可运行时 resize)
soft_budget: 200 # 模型请求软预算;未配置或 0 使用默认 200
max_recursion_depth: 2 # 委派递归深度上限
min_task_chars: 40 # 任务描述最短长度(拒绝一句话派发)
memory:
global: true # 项目库之外再开全局库
recall_top_k: 5| 里程碑 | 内容 | 状态 |
|---|---|---|
| P0–P7 | 地基 / 循环 / 会话 / 上下文 / 工具运行时 / HITL / 记忆 / 子 agent+MCP / trace+eval | ✅ |
| P8 (M1) | 项目作用域数据目录、Session v2、压缩正确性、子 agent 运行时修正 | ✅ |
| P9 (M2) | 委派运行时:frontmatter agent、TaskBatch 预检、yield 三态、Agent Hub、后台作业、hub 邮箱 | ✅ |
| P10 (M3) | 记忆正确性、前缀缓存、L1 项目层、剪枝阶梯、项目知识、read 去重 | ✅ |
| P11 (M4) | 审批规则引擎 + bash 分类器/超时/进程组/env 脱敏(P11.1);edit 工具与文件守卫(P11.2);hooks / trace.db / eval v2(后续) | 🚧 P11.1–P11.2 完成 |
| 生产化第一轮 | Workspace / 原生 sandbox / Go AST + stdio LSP / 哈希前置条件与恢复日志 / verify + 完成检查 | 初版落地;平台验收与限制见设计文档 |
详细演进方案见 docs/specs/2026-08-24-evolution-plan.md,完整开发记录见 docs/DEVELOPMENT_LOG.md。