From 9f468a13a1f61a5af8970c97ac35d10d0fe832fc Mon Sep 17 00:00:00 2001 From: lanrtop Date: Sun, 23 Aug 2026 16:31:30 +0900 Subject: [PATCH] =?UTF-8?q?feat(onboarding):=20AGENTS=20=E6=A8=A1=E6=9D=BF?= =?UTF-8?q?=E6=B3=A8=E5=85=A5=E3=80=8C=E5=90=8C=E6=BA=90=E5=90=8C=E8=BE=B9?= =?UTF-8?q?=E7=95=8C=20+=20=E6=93=8D=E4=BD=9C=E5=A4=8D=E5=88=BB=E3=80=8D?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E5=8E=9F=E5=88=99=EF=BC=88v1.7.0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 多角度辩证收敛后的 v3.1 外科手术版（真实增量三个半，不重复已有六条）： - 节首总纲：任何功能 = 一个本体 + 两个投影，同源同边界；先定本体后盖投影（原型探索豁免） - 边界单点实现追加同源推论：人的操作序列 agent 皆可复刻，人报障即复现路径（操作+状态） - 三分定位启发式（本体→投影→环境），从"定律"降级——crypto.randomUUID 环境层实锤 - human_verify 否决理由值得记录（飞轮原料；采集机制挂 governance-feedback-loop，不空头承诺） - 炼境自身 AGENTS.md 块内同步 + agents-meta-rules.md 设计草案同步 Feature-Confirmed: true Rules-Applied: R13 --- AGENTS.md | 11 ++++++++--- docs/templates/agents-meta-rules.md | 6 ++++++ src-tauri/resources/onboarding/AGENTS.md.tmpl | 11 ++++++++--- 3 files changed, 22 insertions(+), 6 deletions(-) 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