@wnlen/agent-execution-template 0.8.14

package/template/zh/ai/project/refs/commands.md

@@ -0,0 +1,43 @@
+# 命令
+
+命令按类别授权。
+AI 只能运行 `ai/project/task.md` 和本文件允许的命令。
+
+## 安全验证命令
+
+```bash
+# 在这里添加项目专属的安全命令
+# 示例：
+# npm run lint
+# npm run build
+# mvn test
+```
+
+## 本地运行命令
+
+```bash
+# 在这里添加本地启动命令
+# 示例：
+# npm run dev
+# mvn spring-boot:run
+```
+
+## 危险命令
+
+这些命令需要任务级明确授权：
+
+```bash
+# 数据库迁移
+# 部署
+# 分支重置
+# 文件删除
+```
+
+## 未明确允许则禁止
+
+```bash
+# 生产部署
+# 生产数据迁移
+# 破坏性清理
+# 会暴露密钥的命令
+```

package/template/zh/ai/project/refs/constraints.md

@@ -0,0 +1,24 @@
+# 约束
+
+## 数据
+
+- 保持数据一致性。
+- 除非明确授权，不要引入迁移。
+
+## 安全
+
+- 不要削弱认证、授权、校验或密钥处理。
+- 不要记录敏感数据。
+
+## 兼容性
+
+- 除非明确授权，保持公共 API 兼容。
+
+## 性能
+
+- 没有基准或明确验收标准时，避免大范围重构。
+
+## 部署 / 回滚
+
+- 除非明确授权，不要部署。
+- 优先做可回滚的变更。

package/template/zh/ai/project/refs/decisions.md

@@ -0,0 +1,13 @@
+# 决策
+
+在这里记录持久技术决策。
+
+## D001 - 示例决策
+
+状态：accepted | superseded | rejected
+
+原因：
+
+影响：
+
+除非以下情况，否则不要修改：

package/template/zh/ai/project/refs/final-shape.md

@@ -0,0 +1,54 @@
+# 项目北极星说明书
+
+这个文件是项目方向的宪法层，也可以叫 Product Constitution / Final Shape Spec。
+它稳定保存项目最终形态和判断标准，但允许通过明确流程修订。
+
+普通执行任务不能直接修改本文件。新的灵感应先进入 `ai/project/inbox/ideas/`，
+再通过 `strategy_update` 生成提案，经人类确认后，由 `apply_strategy_update` 合并。
+
+## 一句话定位
+
+-
+
+## 本质问题
+
+-
+
+## 目标用户
+
+-
+
+## 核心痛点
+
+-
+
+## 最终产品形态
+
+-
+
+## 当前阶段不做什么
+
+-
+
+## 核心模块边界
+
+-
+
+## 长期护城河
+
+-
+
+## 任务是否值得做的判断标准
+
+-
+
+## 项目是否跑偏的判断标准
+
+-
+
+## 修订规则
+
+- 灵感不能直接改本文件。
+- AI 不能在普通执行任务中顺手改本文件。
+- 修改必须经过 `proposal -> review -> human confirm -> update`。
+- 已确认修改应同步评估 `module-map.md`、`roadmap.md`、`decisions.md` 和 `constraints.md`。

package/template/zh/ai/project/refs/module-map.md

@@ -0,0 +1,30 @@
+# 模块地图
+
+这个文件描述当前模块结构、边界和依赖方向。
+它回答“系统现在长成什么样”，不替代 `final-shape.md` 的方向判断。
+
+## 模块总览
+
+| 模块 | 职责 | 输入 | 输出 | 所有者/边界 |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## 依赖方向
+
+-
+
+## 稳定边界
+
+-
+
+## 易混淆边界
+
+-
+
+## 待拆分或待合并区域
+
+-
+
+## 与北极星的关系
+
+-

package/template/zh/ai/project/refs/roadmap.md

@@ -0,0 +1,29 @@
+# 路线图
+
+这个文件描述阶段性路线。
+它回答“下一阶段往哪里生长”，不替代 `task.md` 的当前施工单。
+
+## 当前阶段
+
+- 阶段名称：
+- 阶段目标：
+- 成功信号：
+
+## 近期路线
+
+| 阶段 | 目标 | 关键交付 | 不做什么 | 退出标准 |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## 已完成阶段
+
+-
+
+## 暂缓事项
+
+-
+
+## 路线图修订规则
+
+- 普通执行任务可以提出路线图更新建议，但不能直接改本文件。
+- 涉及项目方向、模块边界或阶段目标的修改，必须通过 `strategy_update` 提案。

package/template/zh/ai/project/result.json

@@ -0,0 +1,34 @@
+{
+  "protocol_version": "0.8",
+  "status": "blocked",
+  "task_id": "",
+  "task_summary": "尚未执行任务。",
+  "scope_followed": true,
+  "files_read": [],
+  "refs_read": [],
+  "files_changed": [],
+  "commands_run": [],
+  "verification": {
+    "level": "none",
+    "passed": false,
+    "evidence": []
+  },
+  "evidence": {
+    "git_diff_summary": "",
+    "changed_files_from_git": [],
+    "command_outputs": [],
+    "unverified_claims": []
+  },
+  "assumptions": [],
+  "issues": [
+    "尚未执行当前任务。"
+  ],
+  "next": [
+    "让 Agent 读取 ai/template/bootstrap.md，确认项目上下文，然后在运行 ai/template/prompt.md 前起草并确认 ai/project/task.md。"
+  ],
+  "runtime_update": {
+    "required": false,
+    "changes": [],
+    "reason": ""
+  }
+}

package/template/zh/ai/project/result.md

@@ -0,0 +1,32 @@
+# 结果
+
+## 状态
+
+blocked
+
+## 摘要
+
+尚未执行任务。
+
+## 变更
+
+- 无
+
+## 验证
+
+- 未验证
+
+## 指标
+
+- 模型：未记录
+- 耗时：0 分钟
+- 成功：false
+- 需要人工修复：false
+
+## 问题
+
+- 尚未执行当前任务。
+
+## 下一步
+
+- 读取 `ai/template/bootstrap.md`，确认项目上下文，然后在运行 `ai/template/prompt.md` 前起草并确认 `ai/project/task.md`。

package/template/zh/ai/project/runtime.md

@@ -0,0 +1,74 @@
+# 运行时
+
+## 当前状态
+
+- 阶段：方向层与执行层一致性收口
+- 重点：保持文件协议可安装、可升级、可审计，并让项目方向治理与任务执行约束一致。
+- 阻塞：无
+- 已知风险：
+  - 超出当前任务范围
+  - 询问人类那些 Agent 可以安全推断的细节
+  - 用历史过程笔记污染运行时上下文
+  - 没有验证证据就标记成功
+  - 在明确权限之外运行命令
+  - 只优化 token 节省，而忽略成本可接受前提下的输出质量
+  - 方向层已升级但规则、runtime 或 doctor 仍停留在旧语义
+
+## 硬规则
+
+- 当前任务优先。
+- 不要扩大范围。
+- 不要重写无关文件。
+- 不要重复已知背景。
+- 不要输出教程。
+- 不要把猜测当成事实。
+- 先读取相关文件，再做假设。
+- 优先做最小且安全的改动。
+- 修改后尽可能验证。
+- 最终输出保持简短。
+- 最小化人类交互；只为范围、风险、权限或验收阻塞项提问。
+- 执行前最多问 3 个澄清问题。
+- 除非 `ai/project/task.md` 明确允许，不要编辑 `ai/project/runtime.md`。
+- 如果 `status = "success"`，`verification.passed` 必须为 `true`。
+- 如果验证需要人工检查，除非人工验证已经完成，否则使用 `status = "partial"`。
+- 默认使用 `cheap` 执行；只为规划、判断、重复失败或验收争议升级。
+- 遵守 `ai/project/task.md.model_policy`；默认 `cheap`，需要判断时升级，并记录原因。
+
+## 项目约束
+
+- 引导读取集从 `ai/template/bootstrap.md`、`ai/template/protocol.md`、`ai/template/rules/core.md`、根目录文档、清单、文档、引用开始；当文档不足时，进行有限源码结构检查。
+- 执行读取集是 `ai/template/prompt.md`、`ai/template/protocol.md`、`ai/template/rules/core.md`、`ai/project/project.md`、`ai/project/runtime.md` 和 `ai/project/task.md`。
+- `ai/project/refs/` 文件只在任务要求或任务类型触发时加载。
+- `ai/project/refs/final-shape.md`、`module-map.md`、`roadmap.md` 属于方向层正式文档。
+- 方向层正式文档不能被普通 reconcile 或普通执行任务直接修改。
+- 方向修订必须经过 `strategy_update` proposal 和 `apply_strategy_update`。
+- 默认永远不读取 `ai/project/archive/`。
+- `ai/project/result.json` 是唯一权威的最新结果。
+- `ai/project/result.md` 是最新的人类可读摘要。
+- `ai/project/metrics.json` 是最新的 token 效率和复用记录。
+- 模型档位决策由 `ai/project/task.md.model_policy` 管理，不由临时聊天偏好决定。
+- `ai/project/runtime.md` 只保存稳定且当前有效的上下文。
+- 历史任务和结果属于 `ai/project/archive/`。
+
+## 当前上下文
+
+这个项目是协议 / 模板，不是复杂 Agent 框架。
+当前产品定位是：面向 AI Coding Agent 的项目方向治理 + 可审计任务执行协议。
+当前产品目标是减少人类交互频率和输入量，同时让任务随时间变得更精确，并减少长期方向漂移。
+允许增加少量服务于协议采用和治理闭环的 CLI；不要引入 UI、云同步或多 Agent 编排。
+
+## 引用路由
+
+- 最终形态 / 北极星 / 任务价值判断 -> `ai/project/refs/final-shape.md`
+- 当前模块结构 / 边界 / 依赖方向 -> `ai/project/refs/module-map.md`
+- 阶段目标 / 近期路线 / 暂缓事项 -> `ai/project/refs/roadmap.md`
+- 架构 / API / 模块边界 -> `ai/project/refs/architecture.md`
+- 历史决策 -> `ai/project/refs/decisions.md`
+- 安全 / 兼容性 / 性能 / 数据 / 部署 -> `ai/project/refs/constraints.md`
+- 构建 / 测试 / 部署命令 -> `ai/project/refs/commands.md`
+
+## 运行时更新治理
+
+除非 `ai/project/task.md` 明确允许，AI 不得直接更新这个文件。
+如果任务产生长期有效上下文，将建议写入 `ai/project/result.json.runtime_update`。
+通过单独任务应用运行时更新，该任务唯一允许目标是 `ai/project/runtime.md`。

package/template/zh/ai/project/task.md

@@ -0,0 +1,106 @@
+---
+task_id: ""
+type: "bugfix | feature | refactor | docs | config | test | research | strategy_update | apply_strategy_update"
+priority: "P0 | P1 | P2 | P3"
+risk_level: "low | medium | high"
+depends_on_previous_result: false
+model_policy:
+  default_tier: "cheap"
+  allowed_tiers:
+    - cheap
+    - standard
+    - strong
+  escalation_allowed: true
+  escalation_triggers:
+    - ambiguous_goal
+    - ambiguous_acceptance
+    - high_risk_change
+    - architecture_boundary
+    - repeated_failure
+    - verification_dispute
+  strong_model_roles:
+    - planning
+    - risk_judgment
+    - architecture_review
+    - failure_review
+    - acceptance_judgment
+refs:
+  required: []
+  optional: []
+permission:
+  modify:
+    allowed: []
+    denied: []
+  commands:
+    allowed: []
+    denied: []
+  network: false
+  destructive_actions: false
+  runtime_update: "propose_only"
+---
+
+# 任务
+
+这个文件是当前执行契约。优先在引导模式中，根据简短人类目标和仓库上下文生成，
+然后由人类在执行前检查。
+
+优先使用安全假设，少问额外问题；但不要猜测范围、风险、权限或验收。
+
+## 目标
+
+描述这个任务的准确目标。如果由简短人类请求生成，保留用户意图并明确写出假设。
+
+如果 `type = strategy_update`，目标是生成方向修订提案，不写代码。
+如果 `type = apply_strategy_update`，目标是把已确认提案合并进正式方向文档。
+
+## 范围
+
+允许范围：
+
+-
+
+范围外：
+
+-
+
+## 相关文件
+
+-
+
+## 约束
+
+- 不要重构无关模块。
+- 除非任务要求，不要修改公共 API。
+- 除非明确授权，不要编辑 `ai/project/runtime.md`。
+- 除非 `type = apply_strategy_update` 且已有确认过的提案，不要修改
+  `ai/project/refs/final-shape.md`、`module-map.md` 或 `roadmap.md`。
+
+## 验收
+
+任务完成条件：
+
+-
+
+## 权限
+
+只修改 YAML front matter 允许列表中的文件。
+只运行 YAML front matter 中列出且 `ai/project/refs/commands.md` 允许的命令。
+
+## 模型策略
+
+默认使用 `model_policy.default_tier` 声明的模型档位。
+不要用 `strong` 做常规执行。只为 `model_policy` 声明的角色和触发条件使用 `strong`，
+并在 `ai/project/metrics.json` 中记录原因。
+
+## 停止条件
+
+如果出现以下情况，停止并写入 `status = "blocked"` 的 `ai/project/result.json`、
+`ai/project/result.md` 和 `ai/project/metrics.json`：
+
+- 必需文件缺失。
+- 目标含糊。
+- 验收不可验证。
+- 范围要求修改允许范围之外的文件。
+- 必需引用缺失。
+- 必需命令无法运行。
+- 风险等级高但没有明确授权。

package/template/zh/ai/template/LANG

@@ -0,0 +1 @@
+zh

package/template/zh/ai/template/VERSION

@@ -0,0 +1 @@
+0.8.14

package/template/zh/ai/template/bootstrap.md

@@ -0,0 +1,180 @@
+# AI 执行引导
+
+不要总结这个文件。
+执行下面的引导流程。
+
+你正在为 Agent Execution Template 整理项目上下文。
+
+目标：建立后续任务会依赖的稳定项目理解。
+这是发现与确认步骤，不是实现步骤。
+
+你的任务是检查项目，创建或更新 `ai/project/project.md`
+以及相关的 `ai/project/refs/*`，然后在“引导后交接”处停止。
+
+## 先读
+
+1. `ai/template/protocol.md`
+2. `ai/template/rules/core.md`
+3. 现有的 `ai/project/project.md`
+4. 如果存在，读取现有的 `ai/project/refs/*.md`
+
+## 引导任务
+
+创建或更新：
+
+- `ai/project/project.md`
+- 能推断项目方向、最终形态或任务价值判断时，更新 `ai/project/refs/final-shape.md`
+- 能推断模块职责、边界或依赖方向时，更新 `ai/project/refs/module-map.md`
+- 能推断阶段目标、近期路线或暂缓事项时，更新 `ai/project/refs/roadmap.md`
+- 能推断架构时，更新 `ai/project/refs/architecture.md`
+- 能推断运行、测试、构建命令时，更新 `ai/project/refs/commands.md`
+- 能推断约束时，更新 `ai/project/refs/constraints.md`
+- 只有存在持久决策证据时，更新 `ai/project/refs/decisions.md`
+
+只有在人类同时提供当前任务时，才创建 `ai/project/task.md`。
+如果创建了 `ai/project/task.md`，只起草任务契约，不进入执行。
+
+引导期间不要编辑源码、测试、应用配置、依赖文件、生成文件、
+运行时文件、结果文件或指标文件。
+
+## 阅读顺序
+
+按下面顺序读取高价值项目证据：
+
+1. 根目录文档：`README*`、`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、`CHANGELOG*`
+2. 清单文件：`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、
+   `pom.xml`、`build.gradle*`、`Makefile`
+3. 项目文档：`docs/**`，优先阅读概览、架构、安装、测试、部署、API、ADR 和决策文件
+4. 现有 AI 引用：`ai/project/refs/*.md`
+5. 源码、测试、配置和文档目录的浅层仓库结构
+
+如果文档和清单缺失或不足，可以有限读取代码进行推断：
+
+- 先检查顶层目录和文件名；
+- 检查可能的入口目录，例如 `src/`、`app/`、`lib/`、`packages/`、
+  `services/`、`cmd/`、`internal/`、`server/`、`client/`、`test/`、`tests/`；
+- 只读取足够识别项目目的、模块边界、命令和约束的路由、模块、配置和测试文件；
+- 除非人类明确授权，不要读取整个代码库。
+
+除非人类明确引用或授权，不要读取依赖目录、构建产物、覆盖率输出、锁文件
+（推断包管理器除外）、密钥文件、环境文件或归档目录。
+
+## 确认维度
+
+读取后，总结并请人类确认或修正这些点：
+
+- 项目名称、目的和主要用户；
+- 一句话定位、最终形态和任务是否值得做的判断标准；
+- 当前模块地图、模块边界和依赖方向；
+- 当前阶段、近期路线和当前阶段不做什么；
+- 技术栈、包管理器和测试运行器；
+- 源码、测试、配置和文档布局；
+- 主要模块和边界；
+- 重要的运行、构建、测试和验证命令；
+- 持久约束、安全边界、兼容性要求和高风险区域；
+- 会影响后续任务精度的未知项。
+
+一次最多问 3 个问题。只问答案会改变项目身份、命令、边界、约束、风险、
+权限或验收的问题。
+
+## 输出规则
+
+- 未知事实标记为 `Unknown`；不要把猜测当成事实。
+- 对 `final-shape.md`、`module-map.md`、`roadmap.md` 的初始化内容必须标明证据来源；
+  如果证据不足，保持占位或写 `Unknown`，不要编造愿景。
+- 有帮助时，在相关文件中记录证据来源。
+- 保持 `ai/project/project.md` 稳定、长期有效。
+- 保持 `ai/project/refs/*.md` 聚焦；不要把引用文件写成项目流水账。
+- 写完草稿并请求确认后停止。
+- 不要在同一轮执行实现工作。
+
+## 引导后交接
+
+写完项目上下文草稿后，不要只要求人类打开文件检查。
+你必须在最终回复中给出可确认摘要，让人类可以直接在聊天里确认或修正。
+
+如果人类在引导请求中已经给出当前任务目标，你必须同时起草 `ai/project/task.md`，
+并把项目理解摘要和任务草稿摘要一起交给人类确认。
+
+如果人类没有给出当前任务目标，你必须根据项目现状推荐下一步最值得做的任务。
+
+最终回复必须使用这个结构之一。
+
+当没有当前任务目标时：
+
+```text
+引导已完成，我已写入项目上下文。
+
+我对项目的理解：
+- 项目：
+- 技术栈：
+- 主要模块：
+- 北极星：
+- 路线图：
+- 常用命令：
+- 重要约束：
+- 仍不确定：最多 3 条；没有则写“无”
+
+我建议下一步做：
+1. 优先任务：
+   原因：
+2. 备选任务：
+   原因：
+
+已写入：
+- ai/project/project.md
+- ai/project/refs/final-shape.md
+- ai/project/refs/module-map.md
+- ai/project/refs/roadmap.md
+- ai/project/refs/architecture.md
+- ai/project/refs/commands.md
+- ai/project/refs/constraints.md
+- ai/project/refs/decisions.md
+
+请直接回复：
+- 确认，按建议 1 起草任务
+- 确认，但改做：<一句话任务>
+- 修正：<你要改的地方>
+```
+
+当已经有当前任务目标时：
+
+```text
+引导已完成，我已同时写入项目上下文和任务草稿。
+
+我对项目的理解：
+- 项目：
+- 技术栈：
+- 主要模块：
+- 北极星：
+- 路线图：
+- 常用命令：
+- 重要约束：
+- 仍不确定：最多 3 条；没有则写“无”
+
+任务草稿摘要：
+- 目标：
+- 范围：
+- 不做：
+- 验收：
+- 风险：
+- 需要权限：
+
+已写入：
+- ai/project/project.md
+- ai/project/refs/final-shape.md
+- ai/project/refs/module-map.md
+- ai/project/refs/roadmap.md
+- ai/project/refs/architecture.md
+- ai/project/refs/commands.md
+- ai/project/refs/constraints.md
+- ai/project/refs/decisions.md
+- ai/project/task.md
+
+请直接回复：
+- 确认，执行
+- 修正：<你要改的地方>
+```
+
+如果仍有重要未知项，只在“仍不确定”中列出最多 3 条。
+不要让人类主动去文件管理器里寻找问题；文件路径只作为可追溯记录。