Amber Protocol

English

状态： 稳定版 | 版本： 1.0.0 · 里程碑与测试状态 →

Amber Protocol 是一个面向 AI 辅助工程的仓库本地治理层。当团队让 AI agent 在仓库里工作时，难的不再是写代码——而是搞清楚做了什么、是否安全保留、如何交接、如何证明已被审查。Amber 把这些环节显式化：它准备面向 agent 的上下文，记录审批与闸门，用只读检查验证状态，并生成交接与审计产物——全部以文件形式存放在你的仓库里。

它刻意保持保守。Amber 创建审查产物、dry-run 计划和审批记录。它不会运行 Dynamic Workflow、不会调用真实 subagent、不会执行你项目的命令，也不会重写你已有的文档。

安装

从 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

快速开始

通过三个安全步骤把 Amber 引入既有仓库：

# 1. 对目标仓库做只读审计（不改动任何东西）
amber audit --target my-project --summary

# 2. 安装 Amber starter 文件（跳过任何已存在的文件）
amber init --target my-project

# 3. 验证仓库现已具备预期的面向 agent 的表面
amber doctor --target my-project

init 和 wiki 永不覆盖已有文件。完整命令面见 CLI 参考。

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。

核心概念

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 | 最小化——Amber 避免成为通用执行运行时或真实 agent 平台。 | 低 |

主线：强化 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
• .workflow/continuous-improvement/state.json
• 最小 docs/wiki/ —— 项目上下文、系统图、runbook、验证、术语表

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

它不会做什么

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

• 不执行 Dynamic Workflow
• 不调用真实 subagent runner
• 不自动执行目标项目命令
• 不自动重写已有项目文档
• 当前产品不执行 scheduled loop

完整边界说明见 SPEC.md。

文档

| 主题 | 链接 | | --- | --- | | 完整 CLI 参考 | docs/CLI_REFERENCE.md | | 快速开始指南 | docs/user-guide/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 | | 贡献指南 | CONTRIBUTING.md |

Web 查看器（apps/web）为会话和时间线提供一个仪表盘：

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

贡献

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

支持

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

许可证

MIT 许可证 —— 详见 LICENSE。

Amber Protocol —— 为工程团队提供仓库本地 AI 编码治理。