coding-agent · Specification-driven Coding Agent Runtime

A specification-driven coding agent runtime with executable cross-language conformance verification. 一个以行为规范驱动、并通过可执行一致性套件验证多语言实现一致性的 Coding Agent Runtime。

同一套 Agent 行为规范（specs/）在五种语言运行时（impls/）中实现，由可执行一致性套件 （conformance/）机器验证跨版等价。核心主张：行为契约比任何一份实现都稳定。

What is this

• specs/ 是唯一事实源（SSOT）：Agent Loop / Tool Protocol / Permission / Context / Provider / Event / Session 七篇行为规范（另有 Subagent 草案），每篇含本质约束、 语言中立规则与反例清单。
• impls/ 是同一规范的多语言表达，分层实现（ADR-004）： TypeScript（tcode）与 Python（pcode）是一等实现（Tier 1），对齐 ADR-003 能力线 （每次模型调用前的上下文治理、非法/截断参数识别、四态权限、轮次上限事件、 逐条落盘 + 断尾修复、--events-jsonl 事件导出）；Go / Rust / C# 冻结在 v0.5 能力线（Tier 2）——冻结可逆，恢复同步按 five-lang-sync.md 清单执行。 子智能体（task 工具）本轮仅在 TS 实现（ADR-005）。
• conformance/ 是规范的机器执行面：同一 scenario 驱动五个 runtime，归一化后跨版比对， 输出 PASS / ALLOW_DIFF / DRIFT。Tier 1 跑全部场景；Tier 2 的非冻结场景差异按 E9 过渡政策登记 ALLOW_DIFF，不允许静默跳过。
• evals/ 是效果评测框架（ADR-006）：30 个合成代码 任务 × 指标（成功率/轮次/Token/成本/P95）× 消融矩阵（E1–E4 离线版已实现； E5/E6 随真实模型阶段接入），离线先行、真实模型运行前估算费用；报告入 evals/reports/。

Architecture

Behavior Specification (specs/)
        ↓
Runtime Implementations (impls/ × 5)
        ↓
Executable Conformance (conformance/)

裁决链：specs > conformance > tcode 源码（参考实现）> 教程与笔记。 "参考实现不是规范"：期望值只取自 specs，禁止从任何实现的现行为抄录。

Supported Runtime

Runtime	语言目录	依赖	入口	测试
tcode	impls/typescript/	0	node bin/tcode.js	npm test + npm run smoke
pcode	impls/python/	0	python -m pcode	python -m unittest discover -s test + python test/smoke.py
gcode	impls/go/	0	go run ./cmd/gcode	go test ./...（含冒烟）
rcode	impls/rust/	2	cargo run	cargo test（含冒烟）
ccode	impls/csharp/	0	dotnet run	dotnet run --project tests

Conformance Evidence

以下场景验证三条 Agent 生命周期边界。完整场景集 16 个，frozen 13 个 （SC-001、SC-002A/B/C/D、SC-004A～SC-010——后八者于 2026-10-25 以 TS 与 Python 双实现红操演练转红后冻结，记录见 conformance-lessons.md「I5 红操记录」）； SC-011A/B/C（子智能体隔离/权限不升级/取消级联）draft、仅 TS 可达：

Scenario	边界	断言要点
SC-004	Input Boundary	exec 缺 --yolo → 拒绝执行、零模型调用、stderr 指认旗标
SC-001	Decision Boundary	Plan Mode 下写类工具在执行/询问/事件之前被拒；拒写文案逐字一致（规范锁定）；产物零变更
SC-002A	Mutation Boundary	审批确认前不落盘；确认后多文件补丁字节级精确应用
SC-002B	Mutation Boundary	任一编辑预验失败 → 整体零写入 + 错误折叠回流
SC-002C/D	Mutation Boundary（frozen）	五版拒绝相同目标及 . / .. 别名且保留原字节；移除保护的反例准确转红

可验证执行链：每次运行输出构建新鲜度门（sha256 + 时间戳，防"单测绿/冒烟红"的陈旧产物 假象，见 docs/conformance-lessons.md L1）；diff 采用 fail closed——不可归类的差异一律判漂移（normalization policy）； 每个场景冻结前必须通过红操演练（手工注入漂移，套件必须单点转红）。

Design Principles

• Spec first：规范先于实现；实现与 spec 冲突时要么改代码要么改规范，不允许各说各话。
• Fail closed：一致性判定宁可红灯误报，不可绿灯假阳。
• Implementation independent：场景源零实现词（grep 门强制）——第六语言 = 一个 adapter， scenario 零改动。

快速开始

# 一致性套件（需 node 24 / python 3.12 / go / rust / dotnet 8）
node conformance/run.mjs all

# 单语言运行
node impls/typescript/bin/tcode.js          # 或 python -m pcode / go run ./cmd/gcode（impls/go）/ cargo run（impls/rust）/ dotnet run（impls/csharp）

无真实 API Key 时各版自动要求本地假端点；离线一致性验证全程使用脚本化假 provider， 不依赖任何真实模型。

Limitations

• apply_patch 的零写入保证仅适用于预验失败；通过后按文件写入，磁盘失败、取消或崩溃不保证回滚，不提供多文件事务。路径判重基于绝对词法路径，不合并符号链接或硬链接。

• 不是生产 IDE 集成（无编辑器插件、无 LSP）；

• 不是自主部署方案（无沙箱隔离、无云端执行）；

• 平台允许偏差显式登记于 specs（如同步语言 Python/Rust 无轮中取消，Ctrl+C 退出进程）。

目录结构

coding-agent/
├── ARCHITECTURE.md      # 结构一页图 + 裁决链 + 阅读路径
├── specs/               # 行为规范（SSOT，正文 v1）
├── conformance/         # 可执行一致性套件（scenario / adapter / normalizer / diff）
├── impls/               # 五语言实现
│   ├── typescript/      # tcode —— 参考实现（非规范）
│   ├── python/          # pcode
│   ├── go/              # gcode
│   ├── rust/            # rcode
│   └── csharp/          # ccode
├── docs/                # ADR、一致性审计/Schema/Policy/Risks/Lessons、路线图
└── references/history/  # 并仓前独立历史 git bundle 存档

行为约定（Tier 1 现状）

• 行为规格：内置工具 TS 注册 10 个（read/write/edit/bash/glob/grep/todo/web_fetch/ apply_patch/memory_append；web_fetch 带 SSRF 三道闸）、Python 注册 9 个（缺 memory_append，见 impls/python/docs/parity-map.md）、四态权限（allow / deny / always / scoped「本会话 允许此类」；复合 shell 命令不可 scoped）、轮次上限可配（缺省 40，触发先发 limit 事件再强制总结）、双协议（OpenAI 兼容 + Anthropic，按 BASE_URL 含 /anthropic 识别）。
• 统一事件模型：AgentEvent（turn_start/user/text_delta/tool_call/tool_result/ permission/trimmed/compact/context_edit/tool_error/limit/usage/turn_end+终态原因）， turn 唯一生产者，壳只订阅渲染；exec --events-jsonl <path> 逐行导出 （specs/event.md R10–R13）。
• 上下文治理：轮前 + 每次模型调用前执行"清理旧工具输出 → 压缩 → 裁剪" （阈值 context_limit × 80%，压缩摘要保留工具名与参数/结果片段，同轮最多压缩 2 次）。
• 非法/截断的工具参数不再静默变 {}：拒绝执行、回灌固定话术并发 tool_error 事件（finish_reason=length 视为截断）。
• 会话：每产生一条消息即落盘，加载时修复断尾（悬空 tool_call 补占位）。
• Plan Mode：/plan 只读规划，写类工具在权限闸门之前被拒并引导产出计划。
• 无交互模式：exec "任务"（须 --yolo），退出码携带成败；@文件引用；审批策略 normal|never。
• 配置目录各自独立（~/.tcode 等）；会话 JSONL schema 五版通用。
• 修 bug 请对照笔记查其余版本的对应模块——Tier 1 一份修、TS/Python 两版同步 （conformance 会替你盯住）；Tier 2 冻结，恢复同步按 five-lang-sync.md 清单排期。

Subagent（TS 实现，draft）

task 工具派生上下文隔离的子智能体（specs/subagent.md、 ADR-005）：不继承父会话消息、有效工具集 = 声明集 ∩ 父当前可用集合（权限只降不升）、独立预算（轮次/Token/墙钟）、取消级联、 结构化结果回传；TCODE_SUBAGENT=on 启用，默认 off 行为不变。并发调度（只读 上限 3）已定义、当前接线为顺序执行（偏差登记见 spec）。一致性场景 SC-011A/B/C（draft）覆盖隔离、权限不升级与取消级联。