@wnlen/agent-execution-template 0.8.19 → 0.8.21

package/template/zh/ai/template/protocol.md

@@ -1,16 +1,20 @@
 # 协议
 
-Agent Execution Template v0.8 将可复用协议和项目专属执行上下文分开。
+Agent Execution Template v0.8 分离可复用协议和项目现场。
 
 ```text
 ai/template/ = 可复用执行协议
 ai/project/  = 当前项目执行工作区
 ```
 
-`template` 是协议，`project` 是现场工作区。
+`template` 是协议，`project` 是现场。
 
-项目现场不仅保存当前任务，也保存方向层。方向层用于回答“为什么做、往哪里长”，
-执行层用于回答“这次做什么、如何验收”。
+这里的“项目执行工作区”只指当前仓库内的 `ai/project/**` 现场上下文，不是仓库外
+workspace / session / sandbox 运行时。外部运行时可以进入仓库并读取本协议，但不应
+替代 `task.md`、文件修改规则、验收标准或具体编码上下文。
+
+项目现场同时保存任务和方向层。方向层回答“为什么做、往哪里长”，执行层回答
+“这次做什么、如何验收”。
 
 ```text
 ai/project/refs/final-shape.md = 项目北极星说明书
@@ -26,15 +30,14 @@ ai/project/task.md             = 当前执行契约
 ```
 
 1. 项目发现时，执行 `ai/template/bootstrap.md`；不要总结它。
-2. 引导结束时使用“引导后交接”，在聊天里给出可确认摘要和推荐下一步，
-   不要只要求人类打开文件检查。
+2. 引导结束用“引导后交接”，在聊天里给可确认摘要和推荐下一步，不只要求人类打开文件。
 3. 任务执行时，执行 `ai/template/prompt.md`；不要总结它。
-4. 当出现新的权威资料时，放入 `ai/project/inbox/`，执行 `ai/template/reconcile.md`；
-   不要总结它。整合必须先出计划，等确认后再更新上下文。
-5. 当出现会改变项目最终形态、模块边界或路线图的灵感时，先放入
-   `ai/project/inbox/ideas/`，再创建 `strategy_update` 任务生成提案。
-6. 只有人类确认提案后，才能创建 `apply_strategy_update` 任务修改
-   `final-shape.md`、`module-map.md` 或 `roadmap.md`。
+4. 新权威资料放入 `ai/project/inbox/`，执行 `ai/template/reconcile.md`；不要总结它。
+   整合先出计划，确认后更新上下文。
+5. 会改变最终形态、模块边界或路线图的灵感先放入 `ai/project/inbox/ideas/`，
+   再用 `strategy_update` 生成提案。
+6. 人类确认提案后，才可用 `apply_strategy_update` 修改 `final-shape.md`、
+   `module-map.md` 或 `roadmap.md`。
 7. 如果 `ai/project/task.md` 缺失或不完整，根据当前目标和已确认的项目上下文起草它，
    然后用“任务草稿交接”停止。
 8. 任务确认后，检查就绪度、风险、模型策略、引用、权限和验收。
@@ -45,12 +48,10 @@ ai/project/task.md             = 当前执行契约
 
 任务执行前必须读取 `ai/template/execution-policy.md`。
 
-执行策略默认是 `auto`：AI 先拆 L1 任务并判断 Green / Yellow / Red，再决定使用
-`normal` 或 `bounded_continuous`。L1 少于 2 个使用 `normal`；L1 为 2 个或更多
-自动启用 `bounded_continuous`。L1 必须是可独立验收的垂直切片。只有
-`readiness = ready_to_execute` 的既有任务才能执行；本轮新建或重写任务契约时先
-停在确认交接。只有 Red 停止等待人类确认，Yellow 只允许当前 L1/L2 内的局部
-低风险修正。
+默认 `auto`：AI 先拆 L1 并判断 Green / Yellow / Red，再选择 `normal` 或
+`bounded_continuous`。L1 < 2 用 `normal`；L1 >= 2 自动启用 `bounded_continuous`。
+L1 必须是可独立验收的垂直切片。只有既有任务 `readiness = ready_to_execute` 才能执行；
+本轮新建或重写任务契约时先停下确认。Red 停止确认，Yellow 只允许当前 L1/L2 内的局部低风险修正。
 
 任务树、风险分级、Checkpoint 证据和 `task_tree` 写回规则由
 `ai/template/execution-policy.md` 定义。
@@ -62,17 +63,16 @@ ai/project/task.md             = 当前执行契约
 - `ai/project/project.md`
 - `ai/project/refs/*.md`
 
-当 `ai/project/project.md` 为空、只有占位内容、过期、不完整，或用户要求整理项目上下文时，
-使用引导模式。
+当 `project.md` 为空、占位、过期、不完整，或用户要求整理上下文时，使用引导模式。
 
 引导模式必须：
 
 - 先只读取批准的引导来源；
 - 将稳定项目事实总结到 `ai/project/project.md`；
-- 当能推断持久架构、命令、约束或决策事实时，更新聚焦的引用文件；
+- 能推断持久架构、命令、约束或决策事实时，更新聚焦引用文件；
 - 只有在人类同时提供当前任务时，才创建 `ai/project/task.md`，且只起草任务契约；
 - 将未知事实标记为 `Unknown`，不要猜测；
-- 只有答案会改变范围、风险、权限或验收时，最多问 3 个问题；
+- 只有答案会改变范围、风险、权限或验收时，才问问题，最多 3 个；
 - 写完项目上下文草稿后停止；如果已提供当前任务，也可以同时写任务草稿后停止；
 - 永远不要编辑源码、业务、配置、依赖或生成文件。
 
@@ -102,12 +102,12 @@ ai/project/task.md             = 当前执行契约
 5. 浅层仓库结构：
    - 只查看源码、测试、配置和文档目录。
 
-如果文档和清单缺失或不足，可以有限读取代码进行推断：
+文档和清单不足时，可有限读取代码推断：
 
 - 先检查顶层目录和文件名；
 - 检查可能的入口目录，例如 `src/`、`app/`、`lib/`、`packages/`、
   `services/`、`cmd/`、`internal/`、`server/`、`client/`、`test/`、`tests/`；
-- 只读取足够识别项目目的、模块边界、命令和约束的路由、模块、配置和测试文件；
+- 只读取足够识别目的、模块边界、命令和约束的路由、模块、配置和测试文件；
 - 除非人类明确授权，不要读取整个代码库。
 
 默认不要读取：
@@ -118,7 +118,7 @@ ai/project/task.md             = 当前执行契约
 - `.env*` 等密钥或环境文件；
 - 归档或历史目录，除非用户明确引用。
 
-如果仓库很大，先读取根目录文档和清单文件，再询问是否扩展读取范围。
+仓库很大时，先读根文档和清单，再询问是否扩展读取范围。
 
 ### 引导输出
 
@@ -160,8 +160,8 @@ ai/project/task.md             = 当前执行契约
 
 - `ai/project/task.md`
 
-当项目上下文已确认，但 `ai/project/task.md` 为空、只有占位内容、不完整，
-或人类提供了新的任务目标且引导模式尚未起草任务时，使用任务草稿模式。
+项目上下文已确认但 `task.md` 为空、占位、不完整，或人类提供新任务且引导尚未起草时，
+使用任务草稿模式。
 
 任务草稿模式应该：
 
@@ -175,7 +175,7 @@ ai/project/task.md             = 当前执行契约
 
 ## 上下文整合模式
 
-上下文整合模式吸收新的权威资料，并修正现有长期上下文。
+上下文整合模式吸收新权威资料，修正长期上下文。
 
 新资料优先放入：
 
@@ -184,21 +184,20 @@ ai/project/task.md             = 当前执行契约
 
 已整合资料统一移动到 `ai/project/inbox/processed/`，默认不再作为待吸收资料读取。
 
-用户可以直接说“整合 ai/project/inbox/ 里的新资料”。使用上下文整合模式时，
-执行 `ai/template/reconcile.md`。
+用户可直接说“整合 ai/project/inbox/ 里的新资料”。整合时执行 `ai/template/reconcile.md`。
 
 上下文整合模式必须：
 
 - 读取现有 `ai/project/project.md`、`ai/project/runtime.md` 和 `ai/project/refs/*.md`；
 - 读取人类指定的新资料；未指定时读取 `ai/project/inbox/*.md`；
 - 先输出整合计划，不修改文件；
-- 等人类确认后，才更新 `ai/project/project.md`、`ai/project/runtime.md` 和 `ai/project/refs/*.md`；
+- 人类确认后，才更新 `ai/project/project.md`、`ai/project/runtime.md` 和 `ai/project/refs/*.md`；
 - 应用整合后，把本次已处理的 `ai/project/inbox/*.md` 移动到 `ai/project/inbox/processed/`；
 - 不要默认修改 `task.md`、`result.*`、`metrics.json`、源码、测试、配置或依赖文件；
 - 不要把新资料整段塞进 refs，而是吸收长期有效、结构化、可复用的事实。
 
-如果新资料会改变 `final-shape.md`、`module-map.md` 或 `roadmap.md` 的方向性内容，
-上下文整合只能提出 `strategy_update` 建议，不能直接修改这些文件。
+新资料若改变 `final-shape.md`、`module-map.md` 或 `roadmap.md` 的方向性内容，
+整合只能建议 `strategy_update`，不能直接修改。
 
 ## 策略修订模式
 

package/template/zh/ai/template/reconcile.md

@@ -1,16 +1,13 @@
 # AI 上下文整合
 
 不要总结这个文件。
-执行下面的上下文整合流程。
-
-你正在把新的权威资料吸收到现有 Agent Execution Template 项目上下文中。
-这不是重新引导，也不是全量覆盖。
+按下面流程把新权威资料吸收到现有项目上下文。不是重新引导，也不是全量覆盖。
 
 目标：合并新资料中的长期有效事实，修正过期或不准确的旧上下文，保留仍然正确的既有内容。
 
 ## 适用场景
 
-当项目已经使用一段时间后，出现更完整、更权威的业务、产品、架构或流程资料时，使用本流程。
+当出现更完整、更权威的业务、产品、架构或流程资料时，使用本流程。
 
 新资料默认放在：
 
@@ -18,10 +15,10 @@
 - `ai/project/inbox/raw/*.md`
 - `docs/**`
 
-`ai/project/inbox/` 是待吸收资料区。资料被整合确认后，统一移动到
-`ai/project/inbox/processed/`，用于追溯并避免后续重复整合。
-即使用户说“整合整个 inbox”，默认也只处理 `ai/project/inbox/*.md`
-和 `ai/project/inbox/raw/*.md`；不要递归读取 `processed/**` 或 `ideas/**`。
+`ai/project/inbox/` 是待吸收区。资料确认整合后移到 `ai/project/inbox/processed/`，
+用于追溯并避免重复整合。即使用户说“整合整个 inbox”，也默认只处理
+`ai/project/inbox/*.md` 和 `ai/project/inbox/raw/*.md`；不要递归读取
+`processed/**` 或 `ideas/**`。
 
 ## 先读
 
@@ -33,13 +30,13 @@
 6. 人类指定的新资料；未指定时，只读取 `ai/project/inbox/*.md`
    和 `ai/project/inbox/raw/*.md`
 
-不要默认读取 `ai/project/inbox/processed/**`、`ai/project/inbox/ideas/**`、
-`ai/project/archive/**`、源码、测试、配置或依赖文件，除非人类明确要求用它们核对事实。
+不要默认读取 `processed/**`、`ideas/**`、`archive/**`、源码、测试、配置或依赖；
+除非人类明确要求用它们核对事实。
 
 ## 整合原则
 
-- 不要直接覆盖整套文件。
-- 保留仍然正确的既有上下文。
+- 不整套覆盖。
+- 保留仍正确的既有上下文。
 - 将新资料拆分进合适位置：
   - 项目身份、用户、稳定约定 -> `ai/project/project.md`
   - 当前仍有效的执行上下文 -> `ai/project/runtime.md`
@@ -50,10 +47,9 @@
   - 命令 -> `ai/project/refs/commands.md`
   - 约束 -> `ai/project/refs/constraints.md`
   - 持久决策 -> `ai/project/refs/decisions.md`
-- 不要把 `refs/*` 写成原文堆砌；只吸收结构化、长期有效、可复用的内容。
-- 如果新资料会改变北极星、模块地图或路线图的方向性内容，只能建议创建
-  `strategy_update` 提案，不要在上下文整合中直接修改这些方向文件。
-- `task.md`、`result.json`、`result.md`、`metrics.json` 通常不参与业务上下文整合，除非人类明确要求吸收其中仍长期有效的事实。
+- `refs/*` 不堆原文；只吸收结构化、长期有效、可复用的内容。
+- 新资料若改变北极星、模块地图或路线图，只建议创建 `strategy_update`，不要直接改方向文件。
+- `task.md`、`result.json`、`result.md`、`metrics.json` 通常不参与整合；除非人类明确要求吸收其中的长期事实。
 
 ## 两阶段流程
 
@@ -70,13 +66,11 @@
 5. 需要人类确认的问题，最多 3 个
 6. 预计会更新的文件
 
-如果没有需要确认的问题，明确写“无需额外确认”。
-
-阶段 1 结束时必须停止，等待人类确认。
+无问题时写“无需额外确认”。阶段 1 结束必须停止，等待确认。
 
 ### 阶段 2：应用整合
 
-只有在人类明确确认整合计划后，才更新文件。
+只有人类确认整合计划后才更新文件。
 
 允许更新：
 
@@ -97,15 +91,14 @@
 - `ai/project/metrics.json`
 - `ai/project/archive/**`
 
-应用整合完成后，必须把本次已整合的 `ai/project/inbox/*.md` 和
-`ai/project/inbox/raw/*.md` 资料移动到 `ai/project/inbox/processed/`。保留相对路径：
-`ai/project/inbox/raw/file.md` 移动到 `ai/project/inbox/processed/raw/file.md`。
-如果文件名冲突，保留原文件名并添加日期或序号。不要移动
-`ai/project/inbox/ideas/**`；方向灵感应继续走 `strategy_update`。
+整合完成后，把本次已整合的 `ai/project/inbox/*.md` 和 `ai/project/inbox/raw/*.md`
+移到 `ai/project/inbox/processed/`，保留相对路径：`ai/project/inbox/raw/file.md` ->
+`ai/project/inbox/processed/raw/file.md`。文件名冲突时加日期或序号。不要移动 `ideas/**`；
+方向灵感继续走 `strategy_update`。
 
 ## 最终交接
 
-应用整合后，最终回复必须包含：
+应用后，最终回复包含：
 
 ```text
 上下文整合已完成。
@@ -142,4 +135,4 @@
 - 修正：<你要改的地方>
 ```
 
-不要让人类自己去文件管理器里寻找变化；文件路径只作为可追溯记录。
+不要让人类自己找变化；文件路径只作追溯。

package/template/zh/ai/template/rules/core.md

@@ -2,7 +2,7 @@
 
 ## 就绪门
 
-编辑代码前，检查 `ai/project/task.md` 是否清楚定义：
+编辑前，确认 `ai/project/task.md` 已清楚定义：
 
 - 目标
 - 范围
@@ -18,8 +18,8 @@
 
 ## 引导门
 
-如果 `ai/project/project.md` 为空、只有占位内容、不完整，或用户要求整理项目上下文，
-先执行 `ai/template/bootstrap.md`，再进入执行。
+若 `ai/project/project.md` 为空、占位、不完整，或用户要求整理上下文，先执行
+`ai/template/bootstrap.md`。
 
 引导模式只能写项目上下文文件：
 
@@ -32,14 +32,13 @@
 - `ai/project/refs/constraints.md`
 - `ai/project/refs/decisions.md`
 
-只有在人类同时提供当前任务目标时，引导模式才可以写 `ai/project/task.md`。
-此时只能起草任务契约，不能进入实现。
+只有人类同时提供当前任务目标时，引导模式才可写 `ai/project/task.md`；只能起草，不实现。
 
-引导模式不得编辑源码、测试、配置、依赖文件、生成文件、运行时文件、结果文件或指标文件。
+引导模式不得编辑源码、测试、配置、依赖、生成文件、运行时、结果或指标文件。
 
 写完引导草稿后，使用 `ai/template/bootstrap.md` 中的“引导后交接”停止。
 交接必须在聊天里给出可确认摘要和推荐下一步，不要只让人类打开文件检查。
-如果人类已经提供当前任务目标，可以同轮起草 `ai/project/task.md`，但仍必须停止等待确认，不能进入实现。
+若人类已提供任务目标，可同轮起草 `task.md`，但仍必须停止确认，不能实现。
 
 ## 引导读取范围
 
@@ -60,9 +59,8 @@
 
 ## 任务草稿门
 
-如果项目上下文已确认，但 `ai/project/task.md` 为空、只有占位内容、不完整，
-或人类提供了新的任务目标，根据已确认的项目上下文起草 `ai/project/task.md`，
-并在实现前停止等待人类确认。
+项目上下文已确认但 `task.md` 为空、占位、不完整，或人类提供新任务目标时，
+按已确认上下文起草 `task.md`，实现前停止确认。
 
 任务草稿模式只能写：
 
@@ -72,8 +70,8 @@
 
 ## 上下文整合门
 
-如果用户提供新的权威业务、产品、架构或流程资料，并希望合并到既有上下文，
-或说“整合 ai/project/inbox/ 里的新资料”，执行 `ai/template/reconcile.md`，
+用户提供新权威业务、产品、架构或流程资料并希望合并，或说
+“整合 ai/project/inbox/ 里的新资料”时，执行 `ai/template/reconcile.md`。
 不要重新 bootstrap，也不要全量覆盖。
 
 新资料优先放在：
@@ -84,7 +82,7 @@
 
 已整合资料统一移动到 `ai/project/inbox/processed/`，默认不再触发上下文整合。
 
-上下文整合必须先输出整合计划，等待人类确认后才更新文件。
+上下文整合必须先给计划，等确认后再更新文件。
 
 上下文整合默认只能更新：
 
@@ -92,8 +90,7 @@
 - `ai/project/runtime.md`
 - `ai/project/refs/*.md`
 
-如果新资料会改变北极星、模块地图或路线图的方向性内容，只能建议创建
-`strategy_update` 提案，不能在上下文整合中直接修改：
+新资料若改变北极星、模块地图或路线图，只能建议创建 `strategy_update`，不能直接改：
 
 - `ai/project/refs/final-shape.md`
 - `ai/project/refs/module-map.md`
@@ -103,13 +100,12 @@
 
 ## 边界内连续执行门
 
-每次执行前，AI 必须读取 `ai/template/execution-policy.md`，先做任务分解和风险判断，
-而不是等待用户显式说“启用连续执行”。
+每次执行前，AI 必须读取 `ai/template/execution-policy.md`，先分解任务并判断风险，
+不等用户说“启用连续执行”。
 
 硬门禁：
 
-- 只有 `ai/project/task.md.readiness = ready_to_execute` 才能执行；本轮新建或重写
-  `task.md` 时必须停在确认交接。
+- 只有 `task.md.readiness = ready_to_execute` 才能执行；本轮新建或重写 `task.md` 时必须停下确认。
 - L1 必须是可独立验收的垂直切片，不是机械步骤清单。
 - `execution_policy.task_tree` 必须记录 L1 清单和执行状态。
 - 每个任务节点必须有 Green / Yellow / Red 风险评级。
@@ -117,8 +113,8 @@
   权限、安全、架构方向或验收标准。
 - 每个 Checkpoint 必须包含证据；不接受只有主观判断的 Green。
 - Red 必须停止等待人类确认。
-- 任何方向、核心架构、公共 API、持久化数据结构、安全、支付、账号、权限、大量删除、
-  核心重写或高成本方案取舍，都必须停止。
+- 涉及方向、核心架构、公共 API、持久化数据、安全、支付、账号、权限、大量删除、
+  核心重写或高成本取舍时，必须停止。
 - 需要扩大范围、权限、命令、网络或验收时，必须停止。
 - `task_tree` 写回应集中在 L1 开始/完成、Red、blocked、范围变化和最终收尾，
   不要为每个微小 L3 操作写回。
@@ -128,9 +124,8 @@
 
 ## 策略修订门
 
-如果用户要求更新项目北极星、最终形态、产品宪法、模块地图、路线图或项目方向，
-或 `ai/project/inbox/ideas/` 中存在 `.gitkeep` 之外的新灵感，执行
-`strategy_update`。
+用户要求更新北极星、最终形态、产品宪法、模块地图、路线图或项目方向，或
+`ai/project/inbox/ideas/` 有新灵感时，执行 `strategy_update`。
 
 `strategy_update` 只能：
 

package/template/zh/ai/template/rules/output.md

@@ -25,7 +25,9 @@
 
 ## 结果 Markdown
 
-`ai/project/result.md` 是给人看的摘要。保持简短：
+`ai/project/result.md` 是给人看的摘要。保持简短，并默认使用 `ai/template/LANG`
+指定的安装语言。中文模板下，标题和说明默认用中文；代码、命令、文件路径和协议字段
+保留原文。
 
 ```md
 ## 状态