diff --git a/AGENTS.md b/AGENTS.md index b941f2e..be8f15b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,7 +138,7 @@ docs/templates/ 炼境接入包模板草案（设计层） 完整规则（迭代管理、阻塞处理、复盘笔记等）详见 `.blueprint/CONVENTIONS.md`。 - + > ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢（2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示）。 ## 核心开发约束 @@ -189,10 +189,14 @@ docs/templates/ 炼境接入包模板草案（设计层） ## agent 按钮与验证路径 功能的本体是代码层的能力；UI 按钮是它给人的投影，**agent 按钮**是给 agent 的投影 -（可发现 + 可调用 + 有边界的能力声明）。开发任何功能时遵守： +（可发现 + 可调用 + 有边界的能力声明）。**任何功能 = 一个本体 + 两个投影，同源同边界**； +设计交付时先定本体后盖投影（原型探索不受此序约束，交付前本体归位）。开发任何功能时遵守： 1. **边界单点实现**：业务校验只写在能力本体层（API/command），UI 只呈现不复制逻辑—— - 否则人与 agent 的验证路径会分裂 + 否则人与 agent 的验证路径会分裂。同源的直接推论：**人的操作序列 agent 皆可复刻**—— + 人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。 + 三分定位启发式：本体重放正常 → 优先怀疑投影层（接线/渲染/状态同步）→ 再查环境差异 + （安全上下文/网络/OS）；重放失败先怀疑初始状态差异，而非否定问题存在 2. **载体就近选择**（本项目的 agent 按钮是什么，按项目类型对号入座）： | 项目类型 | agent 按钮载体 | |---------|---------------| @@ -214,6 +218,7 @@ docs/templates/ 炼境接入包模板草案（设计层） - `agent_verify:` — 机器可断言（HTTP 状态码、数据库记录、函数返回值）；stop hook / CI 只验此段 - `human_verify:` — 需人眼判断（视觉效果、拖拽手势、30 秒浏览器终验） 纯 API / 命令行任务可省略 `human_verify:`；UI 拖拽 / 动画 / 视觉类必须拆，否则 stop hook 无法收敛。 + human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。 6. **自验报告纪律**：交人终验前的反馈必须含「**没验什么**」一节（未覆盖的路径、依赖的 假设、不确定的地方）；自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是 常规，改测试让功能过需报备）；agent 自验对 acceptance，人终验对意图——acceptance diff --git a/docs/templates/agents-meta-rules.md b/docs/templates/agents-meta-rules.md index e50e81f..f9ad740 100644 --- a/docs/templates/agents-meta-rules.md +++ b/docs/templates/agents-meta-rules.md @@ -109,6 +109,12 @@ AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 三要素缺一不可：**可发现**（清单里有）、**可调用**（结构化命令）、**边界清晰**（通过标准明确）。 +### 同源同边界（设计原则，v1.7.0 起） + +**任何功能 = 一个本体 + 两个投影**：本体是能力层实现（API/command/服务函数），人按钮（UI）与 agent 按钮都是它的投影。同源 = 两投影走同一代码路径；同边界 = 业务校验只在本体层砌一次墙。设计交付时先定本体后盖投影（原型探索豁免此序，交付前本体归位）。 + +同源的直接推论：**人的操作序列 agent 皆可复刻**——人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。三分定位启发式：本体重放正常 → 优先怀疑投影层 → 再查环境差异；重放失败先怀疑初始状态差异，而非否定问题存在。 + ### Acceptance 写法规范 acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言**，不能是描述性语句： diff --git a/src-tauri/resources/onboarding/AGENTS.md.tmpl b/src-tauri/resources/onboarding/AGENTS.md.tmpl index f3125b6..950cad9 100644 --- a/src-tauri/resources/onboarding/AGENTS.md.tmpl +++ b/src-tauri/resources/onboarding/AGENTS.md.tmpl @@ -18,7 +18,7 @@ - + > ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢（2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示）。 ## 核心开发约束 @@ -69,10 +69,14 @@ ## agent 按钮与验证路径 功能的本体是代码层的能力；UI 按钮是它给人的投影，**agent 按钮**是给 agent 的投影 -（可发现 + 可调用 + 有边界的能力声明）。开发任何功能时遵守： +（可发现 + 可调用 + 有边界的能力声明）。**任何功能 = 一个本体 + 两个投影，同源同边界**； +设计交付时先定本体后盖投影（原型探索不受此序约束，交付前本体归位）。开发任何功能时遵守： 1. **边界单点实现**：业务校验只写在能力本体层（API/command），UI 只呈现不复制逻辑—— - 否则人与 agent 的验证路径会分裂 + 否则人与 agent 的验证路径会分裂。同源的直接推论：**人的操作序列 agent 皆可复刻**—— + 人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。 + 三分定位启发式：本体重放正常 → 优先怀疑投影层（接线/渲染/状态同步）→ 再查环境差异 + （安全上下文/网络/OS）；重放失败先怀疑初始状态差异，而非否定问题存在 2. **载体就近选择**（本项目的 agent 按钮是什么，按项目类型对号入座）： | 项目类型 | agent 按钮载体 | |---------|---------------| @@ -94,6 +98,7 @@ - `agent_verify:` — 机器可断言（HTTP 状态码、数据库记录、函数返回值）；stop hook / CI 只验此段 - `human_verify:` — 需人眼判断（视觉效果、拖拽手势、30 秒浏览器终验） 纯 API / 命令行任务可省略 `human_verify:`；UI 拖拽 / 动画 / 视觉类必须拆，否则 stop hook 无法收敛。 + human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。 6. **自验报告纪律**：交人终验前的反馈必须含「**没验什么**」一节（未覆盖的路径、依赖的 假设、不确定的地方）；自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是 常规，改测试让功能过需报备）；agent 自验对 acceptance，人终验对意图——acceptance