Amber Protocol

面向真实工程系统的受治理 Agent Harness。

**Amber Protocol 是 AI Agent 与真实系统之间的治理执行边界。**它治理 Agent 能看什么、能用什么、在哪执行、能产生什么副作用、谁批准、发生了什么、结果是否可信——证据在代码旁的仓内文件，而非聊天记录。

Version: 2.0.1 · **状态：**稳定版 · 里程碑与测试状态 →

它是什么？

Amber Protocol 是面向 Coding-Agent-Enabled Repository 的仓库本地治理层：这类项目已经持续使用一个或多个 Coding Agent 做真实交付，并由人类承担审查责任。难点不再只是生成代码，而是换人、换 agent 或换会话后，后继者能否仅凭仓库状态判断发生了什么、什么已获批准、证据是否足够，以及下一步是什么。

Amber 把计划、会话、证据、决策和交接显式留在代码旁。它的核心结果是 Trusted Continuation（可信续接）：另一个人或 agent 不读取旧聊天，也能理解当前状态并正确继续一步。

Amber = 仓内团队复制层：把「如何安全用 AI 改这个仓」写成可交接的文件证据。

它挂在你已有的编码引擎之下，补治理与证据；不是又一个 agent 运行时，也不是组织级平台。

| Amber 是 | Amber 不是 | | --------------------------------- | ---------------------------------- | | 仓库内的治理与证据协议 | 组织级 Skill 市场 / 插件商店 | | 可审查的计划 · 闸门 · 审批 · 交接 | 跨仓网关或跨机器总控看板 | | 可在团队间复制的本地约定 | 常驻调度 / 自动跑项目命令的 daemon |

三层

| 层 | 职责 | | ------------- | ---------------------------------------------------------------- | | 引擎 | 读改代码、调工具、跑模型与 agent loop（由你选用的编码宿主提供） | | 治理（Amber） | 计划、闸门、审批、doctor/audit、handoff；证据写入仓库文件 | | 可选上层壳 | 只经 MCP 消费 Amber；不改 .amber 契约，不把 loop 塞进 Amber 内核 |

主线：引擎干活；Amber 证明「做了什么、是否可留、如何交接」。

硬非目标

这些是产品边界，不是 TODO：

1. 不替代编码引擎 / 不做通用 agent 运行时
2. 不跑动态工作流、不调度 live subagent、不自动执行你的项目命令
3. 不做组织级市场、跨仓网关、跨机器看板、always-on 调度器
4. 不覆盖已有项目文档（init 与 wiki 只补缺失文件）

完整边界见 Team Replication Charter 与 SPEC.md。

适用对象

• 目标环境：Coding-Agent-Enabled Repository——Coding Agent 已经参与持续、真实、受人工审查的交付；一次性试用或只安装了工具不算。
• 主要用户：Repository Maintainer——对仓库结果和连续性负责。
• 工作用户：agent-assisted developer——定义并执行有边界的交付工作。
• 决策用户：reviewer——依据计划、diff 与证据做 go/no-go 决定。

为什么需要 Amber

• 不读旧聊天也能继续：计划、session、证据和 handoff 让状态能跨人、跨 agent 携带。
• 从仓库证据审查：决策依据是可检视产物，而不是 transcript 中的一句“已完成”。
• 在正确阶段恢复：失败与中断保留在产生它的步骤，不被成功叙事覆盖。
• 明确保留人类权限：审批和治理边界是可查记录，不是隐藏的运行时假设。

产品旅程

资格判断 → 安全接入 → 首次可信续接 → 日常交付 → 失败恢复 → 审查 / 验收

| Journey | 用户结果 | 默认表面 | 完成证据 | | ----------------- | --------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- | | J0 · 资格判断 | 确认 Amber 是否解决真实续接或审查问题 | amber audit | 只读发现与明确的采用/暂缓决定 | | J1 · 安全接入 | 不覆盖已有文件地建立最小仓库表面 | amber init、amber doctor | 可复验的 setup | | J2 · 首次可信续接 | 让新上下文正确继续一项真实工作 | amber next、amber plan、amber session、amber handoff | 新人或新 agent 不读旧聊天仍正确行动 | | J3 · 日常交付 | 定义、授权、工作、证明、审查、交接/验收 | Agent journey；CLI 回退 | 计划、session、命令证据和 checkpoint 一致 | | J4 · 失败恢复 | 在失败、暂停或上下文丢失后回到正确阶段 | amber session、amber next、amber handoff | 失败仍可见，恢复动作有边界 | | J5 · 审查 / 验收 | 依据仓库证据做 go/no-go 决定 | 计划、Gate、Evidence、Web Viewer | 不看 transcript 也能解释决定 |

Feature、Bugfix、Refactor 仍由后台 Route 分型；前台只保留一个心智模型：

Frame → Authorize → Work → Prove → Review → Handoff / Accept

上下文修复、持续改进、团队扩展和高保证治理是条件路径，不阻塞首次可信续接。完整定义见功能矩阵与用户旅程。

安装

从 npm 安装（推荐）

npm install -g amber-protocol
amber --version

从源码安装

git clone https://github.com/Bandersnatch0x/amber-protocol.git
cd amber-protocol
npm install
node scripts/amber.js --version

升级到 2.0.0

2.0.0 是破坏性发布：三个在 1.6.0 里已经发布、且当时 help 文本已标记 DEPRECATED 的 命令族被移除。除此之外契约未变——计划、session、Gate、审批、证据与交接保持原有约定。

| 2.0.0 移除 | 改用 | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | amber agent dispatch\|review\|status | amber harness（Contract → Run → Event 主干）；amber governance report | | amber team inspect\|install\|pin\|update\|rollback | amber maintenance（scaffold 漂移、artifact 漂移）；amber doctor | | amber adoption report\|list\|index\|validate\|compare\|gate\|status\|bundle\|next-actions | amber governance report；amber-diagnosis-adoption 旅程 skill |

处置记录是明文可查的，不靠推测——被移除的表面与其替代路径都留在工具里：

amber harness legacy --target .    # 列出每个被移除表面及其替代路径

若你锁的是 ^1.6.0，npm update 不会跨入 2.0.0——该范围有意止步于破坏点。离开那些已移除命令后， 再升到 ^2.0.0。

快速开始（约 10 分钟）

用一项真实工作验证 Amber 是否产生可信续接；只生成文件不算激活。

# J0 — 不修改项目地判断是否适配
amber audit --target my-project

# J1 — 安装最小表面；已有文件一律跳过
amber init --target my-project
amber doctor --target my-project

# J2 — 定义一项真实目标并遵循状态推导出的下一步
amber next --objective "完成当前 API 修改" --target my-project

# 生成仓库本地续接材料
amber handoff --target my-project

然后新开一个不读取旧聊天的 agent 会话，或请另一位维护者只检查仓库。只有当这个新上下文能解释现状并正确继续一步时，Amber 才算完成激活。

init 和 wiki 永不覆盖已有文件。默认帮助只展示七个回退动词：audit、init、doctor、next、plan、handoff、session；专家与兼容表面保留在 amber --all。完整命令面见 CLI 参考。

专家路径（不是首页主线）：只读的持续改进发现通过 amber loop recommend —— 见下方「它不会做什么」里的循环两节。

命令面

默认 amber --help 只投影七个主命令——整条旅程都在里面：

| 命令 | 作用 | | --------------- | ---------------------------------------- | | amber audit | 只读的仓库就绪度检查 | | amber init | 安装最小仓库本地表面（永不覆盖已有文件） | | amber doctor | 校验 Amber 安装 | | amber next | 针对给定目标做确定性路由建议 | | amber plan | 生成 feature 计划骨架 | | amber handoff | 生成可移植的续接材料 | | amber session | 查看或管理 session 生命周期 |

其余都是治理与平台表面，故意只隔一个开关（amber --all）：

• 上下文与知识 —— wiki、context request|ingest|verify|refresh|stats、memory、knowledge
• 受治理记录 —— artifact、principal、evidence、approval、gate、policy
• 控制与保证 —— projection、adapter、maintain、retention、external、breakglass、eval run
• 交付与报告 —— sync session、governance report、loop recommend、learnings、break-loop、harness

把某个族从默认帮助里隐藏，只改变可发现性，不改变能力：每个族都写在 CLI 参考里，而 amber <族> --help 才是其参数权威。

在 DeepSeek Harness 里用

Amber 挂在官方 dsh-plugin topic 下。以原生 dsh bundle 安装，无需手动改路径：

# 安装一次；dsh 把 Amber bundle 层加入 profile
dsh plugin --profile web add dsh-amber-protocol

# 安装后普通启动即加载 Amber（无需重复 --patch）
dsh --profile web

Windows 上默认端口 3080 常被系统保留，监听失败时加 --port 13080。

未发布 checkout fallback： 如果你在开发 Amber 本身且 bundle 尚未发布，改用 overlay patch。编辑 dsh/amber-full.patch.yml，把 /path/to/amber-protocol 换成本仓库路径，启动时叠加，不改 profile：

dsh --profile web --patch /path/to/amber-protocol/dsh/amber-full.patch.yml

完整说明见 dsh/README.md。

核心概念

Amber 把治理组织为七个控制层，并向安全侧倾斜——优先级越高，Amber 投入该层的表面就越多：

| 层 | 在 Amber 中的角色 | 优先级 | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------ | | Governance | 审批记录、安全默认值、策略边界和采纳控制约束行为。 | 最高 | | Verification | doctor、audit、校验、review 和 gate 表面提供显式检查。 | 高 | | Observability | 时间线、manifest、ledger 和报告让行为可检视。 | 高 | | Lifecycle | route、session、checkpoint 和 worktree 在本地组织工作。 | 中 | | Context | starter 文档、wiki 骨架、manifest 和交接产物保持项目上下文显式。 | 中 | | Tooling | CLI 命令、schema、validator、workflow pack 和 profile 暴露显式接口。 | 中 | | Execution | 门禁化且绑定能力注册——受治理的命令执行存在于四道门 + 冻结的 per-attempt 准入之后；没有无门运行时，原生安装也未注册任何 capability。 | 低 |

主线：强化 Governance、Verification 和 Observability；让 Lifecycle 保持仓库本地；避免漂移成完整的 agent 平台。治理模型文档把每一层映射到具体命令。

会安装什么 —— doctor 检查的最小表面：

• AGENTS.md 和 CLAUDE.md —— 面向 agent 的规则
• feature_list.json —— 被追踪的功能状态
• PROGRESS.md、session-handoff.md、clean-state-checklist.md、evaluator-rubric.md
• .amber/continuous-improvement/state.json
• 最小 docs/wiki/ —— 项目上下文、系统图、runbook、验证、术语表

所有 starter 文件都是安全默认值。init 和 wiki 跳过已有文件，并在 dry-run 模式报告将会创建的内容。

它不会做什么

这些边界是产品的一部分，不是 TODO：

• 不执行 Dynamic Workflow
• 不调用真实 subagent runner
• 不自动执行目标项目命令
• 不写外部系统（PR、issue tracker、通知），也不拦截 agent 的工具调用
• 不自动重写已有项目文档
• 当前产品不执行 scheduled loop
• 原生安装不执行任何受治理的 verb 阶段：实现拥有的 adapter 表出厂为空（无回退），session run 的 stage 一律 fail-closed，直到注册 capability——而注册是一次经过评审的代码变更，不是配置修改

完整边界说明见 SPEC.md。

受治理的循环执行（可选、门禁）

自 ADR-0003 起，Amber 可以运行 loop contract 声明的 governed.command——但必须穿过四道门：声明式策略检查 （.amber/governance/rules.json，deny-wins / 默认拒绝）、一次显式 amber loop approve （一次授权只批一次运行）、隔离的 git worktree（你的主检出永不作为 cwd）、以及防篡改的 哈希链 ledger。默认 loop run 仍是 dry-run；执行需要 --execute。

amber loop approve --file <pack> --contract <id> --reviewer <name>
amber loop run --file <pack> --contract <id> --execute
amber loop verify-ledger --contract <id>
amber governance standards --target .   # 诚实的 OWASP-ASI 覆盖度：做了什么、没做什么

完整边界见 SPEC.md。

amber loop recommend —— 安全的持续改进入口

amber loop recommend 是只读命令：它扫描本地 workflow-pack 里的 loop contract， 按维护目标打分，并输出最适合人工审查的 dry-run 命令。它不会调度任务、执行 workflow 步骤、派发 agent，也不会写外部系统。

amber loop recommend --target . --goal "continuous improvement" --json
amber loop run --file workflow-packs/safe-amber-bootstrap.pack.json --contract daily-amber-triage --dry-run --json

当前产品边界仍不支持 live scheduling；loop run 必须带 --dry-run。

治理信任层（trusted-control contracts）

旅程表面之外，Amber 还附带一层经过合同级测试的信任层（四份 canonical contracts，均已交付）：

• 受治理执行 attempt —— session run 的每个 attempt 在任何效果之前冻结其准入输入（scope、policy、capability、请求摘要）；门禁对冻结值复验，授权 grant 绑定冻结三元组并单次消费。漂移在门上拒绝，先于执行。
• 带保证级别的证据 —— 回执携带 unavailable / observed / replayable / verified；replay 包（amber handoff bundle --replay-scope）可离线重建授权链。
• 受治理 memory —— 可持续教训经 amber memory（request → ingest → 人工 approve → book）流转；MEMORY.md 保持人工策展并哈希注册。
• 指令面 evals —— amber eval run 重放确定性的、与模型无关的 agent 面检查。
• MCP Action Types —— 21 个受治理动词的薄投影；变更类动作返回 approvalRequired，MCP 面从不执行。

这些面是协议的参考实现：受治理 verb 阶段当前fail-closed（未注册 capability——见"它不会做什么"），canonical specs 在等待协调者复评。

文档

| 主题 | 链接 | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 完整 CLI 参考 | docs/CLI_REFERENCE.md | | 快速开始指南 | docs/guides/user-getting-started.md | | 架构与治理模型 | docs/architecture/governance-model.md | | 部署与运维 | docs/DEPLOYMENT.md | | 监控 / 通知 / 策略 | MONITORING_SETUP.md · NOTIFICATION_SETUP.md · POLICY_CONFIGURATION.md | | 故障排查 | docs/TROUBLESHOOTING.md | | 完整文档索引 | docs/README.md | | 规格与路线图 | SPEC.md · ROADMAP.md | | DeepSeek Harness（dsh）叠加层 | dsh/README.md | | 贡献指南 | CONTRIBUTING.md |

公开文档站（apps/docs）提供面向读者的指南、概念与单一来源的权威 CLI 参考，并带 100% 离线本地搜索：

npm run docs:build      # 构建静态文档站
npm run docs:verify     # 运行机械验证缝
npm run docs:gen        # 从命令注册表生成 CLI 参考页
npm run docs:gen:check  # 校验代码与 CLI 参考文档零漂移
npm run docs:test       # 运行公开文档测试套件

可选 Web Viewer（apps/web）是旅程感知的判断表面：显示当前 J0–J5 阶段、下一条受治理动作、活跃 session、待处理 Gate 与仓库本地证据。它只反映 Amber 状态，不创建第二套流程，也不取代 Agent/CLI 权威表面。

cd apps/web
npm install --legacy-peer-deps
npm run dev
# 访问 http://localhost:3001

贡献

查看 CONTRIBUTING.md 了解开发设置、CI 和发布流程。

支持

• 📖 文档：docs/
• 🐛 报告问题：GitHub Issues
• 💡 功能建议：GitHub Discussions

许可证

MIT 许可证 —— 详见 LICENSE。