English | 简体中文
一个 30 秒可安装的 AI Coding Agent 执行协议。 把它装进任意代码仓库，让 AI 从现有文档整理项目上下文，人类确认任务契约，然后在可复用、可验证、可复盘的协议里执行。
npx -y @wnlen/agent-execution-template init默认安装中文模板；也可以显式指定：
npx -y @wnlen/agent-execution-template init --lang zh然后发给你的 AI 编程工具：
/init
Agent Execution Template 不是新的 Agent 框架。它是代码仓库和 Codex、Claude Code、Cursor、Aider 等 AI Coding Agent 之间缺失的执行层。 更准确地说，它是 AI Repo Execution Protocol：只约束 AI 在某个仓库内如何读取上下文、确认任务、遵守文件修改边界、验收并记录结果。
它不管理 workspace 切换、Session 隔离、sandbox 生命周期或 worker 调度。这些属于外部 workspace/session runtime。
它把 AI 编程从：
聊天提示词 -> 临时改代码 -> 验证不清楚 -> 上下文丢在聊天记录里
变成：
整理项目 -> 确认上下文 -> 生成任务 -> 确认契约 -> 执行 -> 结果落盘
AI Coding Agent 已经很强，但大多数项目仍然在用松散聊天上下文驱动它们。这会带来一些稳定复现的问题：
- 每次都要重新解释项目背景。
- AI 容易越过任务边界，做多、改多。
- 风险、权限、验收标准没有明确落到文件里。
- 代码改了，但验证记录不可靠。
- 有价值的执行历史散落在聊天记录中。
- 模板升级容易误伤项目自己的上下文。
- 便宜模型和强模型没有清晰分工。
- 直接影响执行精度的两个文件经常还需要人手写。
- 执行很稳定，但缺少判断任务是否值得做、项目是否跑偏的方向层。
Agent Execution Template 用一个很小的项目内文件协议解决这些问题：
ai/template/ 可复用执行协议
ai/project/ 当前项目现场和方向层
update 只刷新协议区，项目现场保持受保护。
在当前仓库安装协议：
npx -y @wnlen/agent-execution-template init英文项目可使用：
npx -y @wnlen/agent-execution-template init --lang en让 Agent 从现有文档和 manifest 里整理项目上下文：
/init
init 会在仓库根目录安装 AGENTS.md 和 CLAUDE.md 兼容入口托管块。两者内容相同，
不是两套协议；它们分别适配通用 Agent / Codex 和 Claude Code 的自动发现约定。
支持这些入口的 AI 工具会先读取 ai/template/prompt.md，再路由到 ai/template/bootstrap.md。
如果你的 AI 工具没有自动读取根目录入口文件，请先让它读取 AGENTS.md 或
CLAUDE.md，再发送上面的 slash command。
Agent 会生成项目上下文，并在聊天里给出需要确认的摘要、风险和建议下一步：
ai/project/project.md
ai/project/refs/*
回复修正意见，或确认后继续：
/continue
Agent 会根据当前上下文起草或执行：
ai/project/task.md
当任务草稿已确认后，也可以直接发送：
/continue
查看执行结果：
ai/project/result.md
ai/project/result.json
ai/project/metrics.json
检查安装状态：
npx -y @wnlen/agent-execution-template doctor忘了下一步怎么走：
npx -y @wnlen/agent-execution-template next重新总结和优化项目上下文：
npx -y @wnlen/agent-execution-template refresh只升级可复用协议文件：
npx -y @wnlen/agent-execution-template update查看方向修订入口：
npx -y @wnlen/agent-execution-template strategy常用发给 AI 的 slash command：
/init 第一次整理项目上下文
/init-with-inbox 初始化时吸收 ai/project/inbox/ 里的资料
/reconcile 整合新资料
/strategy 生成方向修订提案
/apply-strategy 合并已确认的方向提案
/continue 继续起草或执行当前任务
/next 只判断下一步
/doctor 检查安装
/update 更新协议
/refresh 重整项目上下文
/improve-context 优化项目上下文
/help 查看可用命令
| 能力 | 含义 |
|---|---|
| 可安装执行协议 | 几秒钟给任意仓库加入 AI 执行契约。 |
| Agent 无关 | 可用于 Codex、Claude Code、Cursor、Aider 和其他编程 Agent。 |
| Bootstrap 模式 | 读取受控范围内的文档和 manifest，必要时从代码做有边界推断，生成 project.md 和 refs 草稿后停下来等人确认。 |
| 项目北极星 | 在 ai/project/refs/final-shape.md 保存最终形态、价值判断和跑偏标准。 |
| 策略修订门禁 | 新方向先进入 inbox/ideas/，生成 proposal，人类确认后才合并进北极星、模块地图或路线图。 |
| 保护项目现场 | update 刷新 ai/template/**，不会覆盖 ai/project/**。 |
| 项目上下文重整 | refresh 备份旧 ai/project/**，生成新项目上下文，并把旧上下文放入 inbox 供 AI 整理。 |
| 自动连续执行 | AI 执行前自动拆 L1/L2/L3 任务树；L1 两个以上自动启用边界内连续执行，只有 Red 风险停下来确认。 |
| 可审计结果 | 每次执行都可以留下人类可读结果、机器可读事实和 metrics。 |
| Token-efficient 模型策略 | 便宜模型处理边界清楚的工作，强模型只用于关键判断点。 |
| 可升级模板 | 协议可以持续改进，不丢失项目本地记忆。 |
| Doctor 检查 | 执行前检查必要文件和模板版本。 |
用户仍然只需要说自然语言目标，例如：
实现设置页，包括资料编辑、通知开关和导出入口
AI 会在执行前先拆 L1 任务。L1 必须是可独立验收的垂直切片，不是机械步骤清单：
- [ ] L1-1 资料编辑 Green
- [ ] L1-2 通知开关 Green
- [ ] L1-3 导出入口 Yellow
简单任务不会被完整流程表单淹没。单 L1、Green、低风险任务使用 compact task
contract，只保留目标、范围、验收、权限、验证命令和最小 task_tree。多 L1、
Yellow/Red、跨模块、连续执行或高不确定任务才使用 expanded task contract。
因为 L1 有两个以上，协议会自动使用边界内连续执行。执行每个 L1 前，AI 再规划
自然衍生的 L2/L3；完成一个 L1 后，在清单中打勾并划掉。task_tree 只在
L1 开始/完成、Red/blocked、范围变化或最终收尾时写回，避免为微小步骤反复改文件。
只有 Red 风险会停下来让你确认。Green 自动继续，Yellow 只允许当前 L1/L2 内的 局部低风险修正，不能改变公共接口、数据模型、权限、安全、架构方向或验收标准。 用户默认只看 L1、风险结论、证据、Red 确认和最终结果；内部协议细节不默认展示。
如果 AI 本轮刚新建或重写了 ai/project/task.md，必须先停下来交接确认；
只有已有任务明确处于 ready_to_execute 时，才允许进入执行。
ai/
README.md
template/
VERSION
bootstrap.md
execution-policy.md
prompt.md
reconcile.md
protocol.md
rules/
core.md
output.md
schemas/
result.schema.json
metrics.schema.json
project/
project.md
runtime.md
task.md
result.json
result.md
metrics.json
inbox/
ideas/
raw/
proposals/
final-shape-updates/
refs/
final-shape.md
module-map.md
roadmap.md
archive/
核心设计就是这条边界：
ai/template/**是可复用协议，可以安全地从 npm 包升级。ai/project/**是项目现场，保存本地上下文、任务、参考资料、结果和 metrics。
npx -y @wnlen/agent-execution-template init在当前项目创建 ai/。
- 更新或创建
ai/template/**。 - 创建缺失的
ai/project/**文件。 - 保留已有的
ai/project/**文件。 - 创建或更新根目录
AGENTS.md/CLAUDE.md中的同内容兼容托管块，让不同 AI 工具能发现协议入口。 - 默认安装中文模板；英文模板使用
--lang en。
npx -y @wnlen/agent-execution-template next根据当前项目状态打印下一步：
- 未安装时，提示先运行
init。 ai/project/inbox/有资料时，提示执行上下文整合。ai/project/inbox/ideas/有灵感时，提示生成方向修订提案。- 有待确认方向提案时，提示先审查并确认。
- 任务草稿待确认、ready 任务待执行、失败结果待处理时，提示
/continue。 - 没有待处理事项时，提示暂无必须动作。
默认只输出决策和下一步；使用 --verbose 查看判断依据。
npx -y @wnlen/agent-execution-template update只更新 ai/template/**。
当协议升级，但项目上下文不应该被覆盖时使用它。
默认沿用 ai/template/LANG 中记录的已安装语言。
npx -y @wnlen/agent-execution-template refresh重新总结和优化项目上下文。
- 将旧
ai/project/**改名备份为ai/project.backup.<timestamp>。 - 生成新的
ai/project/**。 - 将旧上下文复制到
ai/project/inbox/raw/old-project/。 - 输出下一句要交给 AI 的整理指令。
也可以使用更直白的别名：
npx -y @wnlen/agent-execution-template improve-contextnpx -y @wnlen/agent-execution-template doctor检查已安装模板版本和必要文件。
默认只输出总体状态、下一步和需要修复的问题：
已就绪已就绪，但存在警告需要修复
通过项、版本详情、源码仓库维护者提示和逐项检查只在 --verbose 下展示。
npx -y @wnlen/agent-execution-template reconcile打印上下文整合的最短操作说明。
npx -y @wnlen/agent-execution-template strategy打印方向修订的最短操作说明。新灵感先进入 ai/project/inbox/ideas/，
再由 AI 生成 strategy_update 提案；人类确认后再执行 apply_strategy_update。
Agent Execution Template 定义了一个简单循环：
项目引导 -> 项目确认 -> 任务草稿 -> 任务确认 -> 计划 -> 执行 -> 复核 -> 结果
重点不是构建复杂调度器，而是让一次 AI 辅助编码任务足够清晰，可以执行、验证、重跑和审计。
协议会记录：
- 允许读取的 bootstrap 来源；
- 任务契约；
- 假设和风险；
- 验证尝试；
- 人类可读结果；
- 机器可读执行事实；
- 模型档位和成本信号。
当项目使用一段时间后，出现更完整、更权威的业务、产品、架构或流程资料时，先放到：
ai/project/inbox/
然后发给 AI：
/reconcile
AI 必须先输出整合计划，等待确认后，再把长期有效事实合并进 project.md、runtime.md 和 refs/*。
整合完成后，已处理资料统一移动到 ai/project/inbox/processed/，保留用于追溯。
默认只吸收 ai/project/inbox/*.md 和 ai/project/inbox/raw/*.md；
processed/** 不会再次参与整合，ideas/** 走方向修订提案。
长期方向不要塞进当前任务。Agent Execution Template 把方向层放在受保护的
ai/project/** 中：
ai/project/refs/final-shape.md # 项目北极星 / 最终形态
ai/project/refs/module-map.md # 当前模块地图
ai/project/refs/roadmap.md # 阶段路线图
ai/project/inbox/ideas/ # 新灵感输入区
ai/project/proposals/final-shape-updates/
ai/project/proposals/final-shape-updates/_template.md
普通执行任务不能直接修改北极星、模块地图或路线图。方向变化应走：
idea -> strategy_update proposal -> human confirm -> apply_strategy_update
这样 task.md 负责当前施工单，final-shape.md 负责判断任务为什么值得做、项目往哪里生长。
可选的 token-efficient profile 给 Agent 一条模型分工规则：
cheap模型处理有边界的阅读、小改动、草稿、重复检查和机械整理。standard模型处理中等复杂度实现。strong模型用于规划、架构评审、风险判断、失败复盘和验收争议。
目标不是单纯减少 token，而是提高每单位模型成本产出的可接受工作量。
更多内容见 Token-Efficient AI Execution Protocol v0.1。
Agent Execution Template 有意保持工具无关。只要一个 Agent 能读取项目文件并遵循指令，就可以使用它。
常见组合：
- Codex
- Claude Code
- Cursor
- Aider
- 自定义编程 Agent
- 用于边界清晰任务的低成本模型执行器
- 在多个仓库里频繁使用 AI Coding Agent 的开发者。
- 想要可重复 AI 执行流程，但不想引入完整 Agent 平台的团队。
- 任务边界、验证和审计记录很重要的项目。
- 默认使用便宜模型，只在关键判断点升级模型的工作流。
- 希望 AI 上下文存在于文件里，而不是只存在于聊天记录里的仓库。
- 希望 AI 生成关键上下文文件、人类只确认边界和验收标准的用户。
Agent Execution Template 不是：
- IDE；
- Agent 平台；
- 多 Agent 调度器；
- workspace / sandbox / session 运行时；
- 多仓库上下文管理器；
- 云服务；
- 提示词合集；
- Codex、Claude Code、Cursor 或 Aider 的替代品。
它是一个小型文件协议，用来让这些工具在真实软件项目中表现得更稳定。
它不负责 workspace 切换、sandbox 生命周期、session fork / rollback 或 worker 调度。反过来，外部运行时不应该替代仓库内的任务定义、文件修改规则、acceptance criteria 或具体编码上下文。
当前包信息：
Package: @wnlen/agent-execution-template
Protocol: v0.8
License: MIT
运行自测：
npm test发布前检查：
npm run check:release测试会验证核心 CLI 契约：
init创建预期的协议和项目文件。update不覆盖ai/project/**。doctor正确报告缺失文件和空的必要文件。check:release验证版本号、模板结构、安装态协议和规格文档一致。
维护这个 npm 包源码仓库时，用 node bin/agent-execution-template.js <command>
测试当前 checkout；用户项目才使用 npx -y @wnlen/agent-execution-template <command>。
维护者本地 ai/project/** 初始化内容不应作为产品改动提交。
欢迎提交 issue 和 pull request。
适合贡献的方向包括：
- 更清晰的任务契约；
- 更安全的 project/template 边界；
- 更好的结果 schema；
- 更好的模型成本和验证 metrics；
- 更贴近真实 AI Coding Agent 工作流的示例；
- 更适合团队采用的文档。