cf86ab688a
- R01 confidence 0.90→0.95（12 命中 0% 返工，最稳信号） - R13 confidence 0.80→0.88（11 命中 9% 返工，高频高效） - R08 confidence 0.87→0.72（3 命中 100% 返工，补 failure_case + boundaries） - R10 confidence 0.85→0.60（6 命中 83% 返工，补 failure_case + boundaries） - 追加梦核写入纪律：蒸馏替换而非追加，规则上限 ≤ 25 条 - 数据来源：2026-07-04 梦核分析，40 条复盘笔记 + Rules-Applied trailer
1026 lines
43 KiB
Markdown
1026 lines
43 KiB
Markdown
---
|
||
version: 1.10.0
|
||
updated: 2026-07-03
|
||
source: dev-manager-tauri
|
||
---
|
||
|
||
# 蓝图更新规则
|
||
|
||
> ⚠️ 本文件由 dev-manager-tauri 统一管理，请勿手动修改。规则更新请在 dev-manager-tauri 项目中进行。
|
||
|
||
本文件定义了 `.blueprint/` 目录的维护规范，供 Claude 在对话中遵循。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.blueprint/
|
||
├── manifest.yaml ← 模块列表、关系、布局坐标
|
||
├── CONVENTIONS.md ← 本文件（Claude 行为规则 + 全局推荐规则库）
|
||
├── rules.md ← 项目私有规则（可选，优先级高于全局规则）
|
||
├── usage.json ← 飞轮外环快照数据（炼境自动写入）
|
||
└── modules/
|
||
└── <module-id>.md ← 每个模块的详情 + 任务卡
|
||
```
|
||
|
||
## 蓝图定位（意图层）
|
||
|
||
蓝图只记录 git 永远无法自动产生的三类信息：
|
||
|
||
| 类型 | 内容 | 为什么 git 做不到 |
|
||
|------|------|----------------|
|
||
| **结构** | 模块列表 + 关系图（dependency/related） | git 只知道文件，不知道模块意图和边界 |
|
||
| **意图** | 为什么做 + 验收标准 + 复杂度 + 复盘笔记 | commit 记录"做了什么"，不记录"为什么" |
|
||
| **规划** | concept / planned 方向 | 还没有代码，git 里什么都没有 |
|
||
|
||
**不属于蓝图的**（交给 git 信号，蓝图不手动维护）：
|
||
- 任务状态（in_progress / done）→ 从 branch / commit 推断
|
||
- 涉及文件（files）→ 从 git diff 读取，蓝图里为可选提示
|
||
- 进度数字（progress）→ 从任务卡完成比例自动算
|
||
- 更新时间（updated）→ 从 git log 读取
|
||
|
||
> 蓝图是项目的"架构意图层"，不是任务追踪系统。任务追踪的职责交还给 git。
|
||
|
||
---
|
||
|
||
## 何时更新蓝图
|
||
|
||
| 事件 | 操作 |
|
||
|------|------|
|
||
| 用户确认了新需求 | 在 manifest.yaml 新增模块，创建 modules/<id>.md |
|
||
| **开始执行任务卡（信息1）** | **任务卡前缀改为 🔵，status → in_progress（第一行代码之前）** |
|
||
| **完成了功能实现（信息2）** | **任务卡前缀改为 ✅，status → done（验收通过之后）** |
|
||
| 拆分了大需求为子任务 | 在 modules/<id>.md 中添加任务卡 |
|
||
| 调整了架构方向 | 更新 edges 关系，可能调整 area |
|
||
| 放弃了某个方向 | 删除对应模块和文件，或标记 status: abandoned |
|
||
| **重构已完成的模块（迭代）** | **manifest.iteration 递增，旧任务卡保留，新建替代任务卡，模块加 `## 迭代记录`** |
|
||
|
||
## 任务卡复杂度定义
|
||
|
||
| complexity | 含义 | 判断标准 | 推荐执行模型 |
|
||
|-----------|------|--------|------------|
|
||
| `S` | Simple | 单文件或机械操作；无需理解现有 pattern；可独立完成 | Haiku |
|
||
| `M` | Medium | 跨 2-4 个文件；需理解现有代码风格和上下文；有隐式依赖 | Sonnet |
|
||
| `L` | Large/Complex | 系统架构级；**无法直接执行，必须先 `/architect` 设计再 `/splitter` 拆分** | Opus（设计）+ Sonnet（执行） |
|
||
|
||
### 判断速查
|
||
|
||
- 改动涉及 3 个以上文件且分属不同功能区域 → 至少 M
|
||
- 需要先理解现有代码的内在逻辑或约定才能动手 → 至少 M
|
||
- 无法在派发时清晰描述完整实现方案 → L，需先 `/architect`
|
||
- 单纯的 SQL 建表、类型文件、配置修改 → S
|
||
|
||
> **注**：`/auto-execute` 技能会按此定义自动路由模型：S 卡委托 Haiku 子 agent，M 卡由当前 Sonnet 执行，L 卡直接标记 blocked 并提示走 `/architect`。
|
||
|
||
## 模块状态定义
|
||
|
||
| 状态 | 含义 | 色标 |
|
||
|------|------|------|
|
||
| `done` | 已实现并验证 | 🟢 绿色 |
|
||
| `in_progress` | 正在开发 | 🔵 蓝色 |
|
||
| `planned` | 已规划，需求明确 | 🟡 黄色 |
|
||
| `concept` | 构思中，信息不完整 | ⚪ 灰色 |
|
||
| `blocked` | 执行受阻，需架构师介入 | 🔴 红色 |
|
||
| `abandoned` | 方向已放弃或功能已退役，模块保留作历史记录 | ⚫ 深灰 |
|
||
|
||
## 任务卡格式
|
||
|
||
modules/<id>.md 中的每个二级标题（`###`）是一张任务卡：
|
||
|
||
```markdown
|
||
### 📋 任务标题
|
||
- status: todo
|
||
- complexity: M
|
||
- files: src/path/to/file.tsx（可选，规划时填预期路径；实际文件由 git diff 追踪，无需回填）
|
||
- depends: other-module-id
|
||
- acceptance: 简要描述完成标准
|
||
- blocked_reason: （仅 status: blocked 时填写）执行受阻的具体原因
|
||
- iteration: 1 # 可选，省略时继承 manifest 顶层 iteration 值
|
||
- replaces: 旧任务标题 # 可选，仅重构任务填写，说明本卡替代哪张旧卡
|
||
|
||
详细说明（可选）。
|
||
```
|
||
|
||
### 状态前缀
|
||
|
||
| 前缀 | status | 含义 |
|
||
|------|--------|------|
|
||
| ✅ | done | 已完成（信息1 + 信息2 均已写入） |
|
||
| 🔵 | in_progress | 执行中或被中断（只有信息1，等待信息2） |
|
||
| 📋 | todo | 可派发（信息充足） |
|
||
| 💭 | concept | 构思中 |
|
||
| 🔴 | blocked | 执行受阻 |
|
||
|
||
### 可派发标准（📋）
|
||
|
||
任务卡同时满足以下条件时标记为 📋：
|
||
1. status 为 `todo`
|
||
2. 有明确的 `acceptance`（验收标准）
|
||
3. complexity 为 `S` 或 `M`
|
||
|
||
`files` 为可选提示字段，有则帮助 agent 更快定位，无则从 git diff 推断，不作派发门槛。
|
||
|
||
不满足条件的 todo 任务保持无前缀，说明还需补充信息。
|
||
|
||
### Acceptance 写法规范
|
||
|
||
acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言**，禁止描述性语句：
|
||
|
||
```
|
||
❌ "功能正常运行"（描述性，agent 无法判断完成）
|
||
❌ "代码正确"（主观，无可执行路径）
|
||
✅ "pnpm typecheck 无报错"
|
||
✅ "cargo test 通过（src-tauri/）"
|
||
✅ "MCP tool list_projects 返回新增项目名"
|
||
✅ "pnpm vitest run <测试文件> 全绿"（仅适用于有纯逻辑层的项目，见前端可测试性规范）
|
||
```
|
||
|
||
最小结构：`[载体] 调用/运行什么(参数) → 断言什么`。
|
||
|
||
含 Rust 业务逻辑的 M/L 卡，acceptance 还须包含（详见 Rust 代码可测试性规范）：
|
||
- `cargo test 通过` + 依赖注入写法确认
|
||
|
||
> acceptance 是整个 agent 按钮体系的核心关节。可执行 = 真自验；描述性 = 假闭合。
|
||
> 完整体系见 `docs/ai-context/agent-button-system.md`。
|
||
|
||
### 💭 concept 卡的极简写法
|
||
|
||
concept 卡是想法 inbox，**不要求 files / acceptance / complexity**，随想随记：
|
||
|
||
```markdown
|
||
### 💭 ServerManagerPanel 表格和软件块有重复逻辑
|
||
- status: concept
|
||
```
|
||
|
||
一行就够。等某次对话中方向变清晰，再补全字段、升格为 📋。
|
||
**不要因为"信息不全就不记"而让想法消失**——concept 卡存在的意义就是承接碎片。
|
||
|
||
## manifest.yaml 规范
|
||
|
||
### 顶层字段
|
||
|
||
```yaml
|
||
version: 1
|
||
name: 项目名称
|
||
iteration: 1 # 当前迭代号（默认 1，重构已完成模块时手动递增）
|
||
updated: YYYY-MM-DD
|
||
agent_button_carrier: tauri # 项目主验证载体（见下方说明），新建蓝图时必填
|
||
```
|
||
|
||
**`agent_button_carrier` 取值**（就近原则，与 AGENTS.md 载体谱系对应）：
|
||
|
||
| 值 | 适用场景 | 对应验证方式 |
|
||
|----|---------|-------------|
|
||
| `tauri` | Tauri 桌面应用 | `cargo test` / Tauri command 函数 |
|
||
| `http` | Web 服务 / REST API | `curl` / HTTP 端点 |
|
||
| `cli` | CLI 工具 / npm scripts | 命令行调用 |
|
||
| `playwright` | 纯 UI 呈现层（最后手段） | Playwright 真界面驱动 |
|
||
|
||
> 新建蓝图时 AI 必须根据技术栈自动推断并填入此字段。`splitter` 生成任务卡时直接从此字段继承载体，无需每次重新推断。
|
||
|
||
### 模块字段
|
||
|
||
```yaml
|
||
- id: kebab-case-id # 唯一标识，同时是 modules/ 下的文件名
|
||
name: 显示名称
|
||
area: frontend # 所属领域 ID
|
||
status: done # planned/concept 手动设；in_progress/done 优先从 git 信号推断，人工确认
|
||
progress: 100 # 由任务卡完成比例自动算，无需手填；App 根据 done 卡比例渲染
|
||
position: [x, y] # React Flow 画布坐标（可选）
|
||
```
|
||
|
||
### 边字段
|
||
|
||
```yaml
|
||
- from: module-a
|
||
to: module-b
|
||
type: dependency # dependency（实线）/ related（虚线）
|
||
```
|
||
|
||
### 领域字段
|
||
|
||
```yaml
|
||
- id: frontend
|
||
name: 前端
|
||
color: "#3B82F6" # 节点边框/分组背景色
|
||
```
|
||
|
||
## 进度计算
|
||
|
||
模块的 progress 由其任务卡的完成比例推算：
|
||
- 无任务卡的模块：手动设置 progress
|
||
- 有任务卡的模块（单迭代）：`完成数 / 总数 × 100`（取整）
|
||
- 有任务卡的模块（多迭代）：**只计当前 iteration 的任务卡**，旧迭代 done 任务不计入分母，避免历史完成率虚高
|
||
|
||
## 迭代管理
|
||
|
||
### 何时递增 iteration
|
||
|
||
**需要递增**（重构已完成的功能）：
|
||
- 一个已有 ✅ done 任务卡的模块需要重新设计或重写
|
||
- 核心交互/架构方案被替换（不是在原有基础上扩展）
|
||
|
||
**不需要递增**（正常演进）：
|
||
- 在现有模块上添加新功能
|
||
- 修复 bug
|
||
- 新增模块
|
||
|
||
### 重构时的操作步骤
|
||
|
||
1. **manifest.yaml 顶层** `iteration` +1，更新 `updated` 日期
|
||
2. **旧任务卡**：保留原位，在卡片末尾加一行注释说明被替代（不改 status、不删除）：
|
||
```markdown
|
||
### ✅ 旧功能实现
|
||
- status: done
|
||
- iteration: 1
|
||
...
|
||
> ⚠️ 已被迭代 2「新功能实现」替代，仅作历史记录。
|
||
```
|
||
3. **新任务卡**：新建替代卡，标注 `iteration` 和 `replaces`：
|
||
```markdown
|
||
### 📋 新功能实现
|
||
- status: todo
|
||
- iteration: 2
|
||
- replaces: 旧功能实现
|
||
- complexity: M
|
||
- files: ...
|
||
- acceptance: ...
|
||
```
|
||
4. **模块文件**：追加 `## 迭代记录` 段落（见下方格式）
|
||
5. **模块 status**：重置为 `in_progress`，progress 按当前迭代任务卡重新计算
|
||
|
||
### 迭代记录格式
|
||
|
||
模块文件末尾追加，每次迭代一条：
|
||
|
||
```markdown
|
||
## 迭代记录
|
||
|
||
### 迭代 2（YYYY-MM-DD）
|
||
- **原因**：React Flow 在 50+ 节点时性能卡顿，重构为虚拟化渲染方案
|
||
- **替代**：「React Flow 节点图渲染（迭代1）」→「节点图虚拟化渲染」
|
||
- **保留**：迭代1的任务卡作为历史记录，不删除
|
||
```
|
||
|
||
### 梦核如何感知迭代
|
||
|
||
- usage.json 快照携带 `iteration` 字段（见飞轮外环章节）
|
||
- 飞轮数据层按 iteration 分组计算完成率，迭代跳变（如 1→2 后完成率骤降）是正常信号
|
||
- 梦核 prompt 会展示「完成率跳变项目」摘要，Opus 据此判断是主动重构还是项目失控
|
||
|
||
## 决策记录格式
|
||
|
||
模块文件中可添加 `## 决策记录` 段落，记录架构决策的 WHY：
|
||
|
||
```markdown
|
||
## 决策记录
|
||
|
||
- 选择阿里云 OSS 而非 GitHub Releases 作为更新源，因为国内用户访问 GitHub 不稳定
|
||
- 使用 document-driven 蓝图而非数据库存储，因为 Claude 天然支持文件读写且可版本控制
|
||
```
|
||
|
||
桌面 App 会以琥珀色卡片展示在模块详情面板中。
|
||
|
||
## 飞轮工作流
|
||
|
||
Claude 在每次对话中应遵循以下流程：
|
||
|
||
### 阶段 1：进入对话 — 读取蓝图
|
||
|
||
```
|
||
1. 读取 .blueprint/manifest.yaml ← 项目全景和当前状态
|
||
2. 读取 .blueprint/CONVENTIONS.md ← 工作流规则 + 全局推荐规则
|
||
3. 读取 .blueprint/rules.md ← 项目私有规则（若存在，合并应用，优先级更高）
|
||
```
|
||
|
||
- 识别哪些模块 in_progress，哪些有可派发任务
|
||
- 用简短话语告诉用户当前项目进展（如 "18/22 模块已完成，2 个进行中"）
|
||
|
||
### 阶段 2：讨论需求 — 同步更新蓝图
|
||
| 用户说的 | Claude 应做的 |
|
||
|----------|--------------|
|
||
| "我想加个 XX 功能" | 确认需求后：manifest 加模块 (status: concept)，创建 modules/<id>.md |
|
||
| "XX 功能需要 A、B、C 三步" | 在模块文件中拆分为 3 张任务卡 |
|
||
| "这个方案确定了" | 模块 status → planned，补充任务卡的 acceptance（files 可选，有则更准确） |
|
||
| "开始做 XX" | 模块 status → in_progress |
|
||
| "为什么选这个方案" | 记录到模块的 `## 决策记录` |
|
||
|
||
### 阶段 3：实现功能 — 两阶段执行锁
|
||
|
||
任务卡执行遵循**两阶段提交**：开始写第一行代码前加锁（信息1），全部完成后解锁（信息2）。只有信息1没有信息2，说明任务被中断。
|
||
|
||
```
|
||
📋 todo
|
||
↓ 【信息1：加锁】第一行代码改动之前，先更新任务卡
|
||
🔵 in_progress
|
||
↓ 执行代码改动
|
||
↓
|
||
├─ 成功 → 【信息2：解锁】更新任务卡前缀为 ✅ → status: done
|
||
│ 所有任务卡完成 → 模块 status: done
|
||
│ 更新 manifest.yaml 的 updated 日期
|
||
│
|
||
├─ 失败且可自行解决 → 继续尝试，保持 🔵
|
||
│
|
||
└─ 失败且无法独立解决 → 🔴 blocked + blocked_reason → 留给架构师处理
|
||
```
|
||
|
||
#### 锁悬空时的续接规则
|
||
|
||
新会话读蓝图发现 🔵 任务卡（只有信息1，没有信息2）时：
|
||
1. 检查任务卡的 `files` 字段，读取相关文件的**当前代码状态**
|
||
2. 判断已完成什么、还缺什么
|
||
3. 从断点继续执行，**不重头来过**
|
||
4. 完成后补写 ✅（信息2），关锁
|
||
|
||
#### 架构师处理 blocked 任务
|
||
当 Opus 读蓝图发现 🔴 blocked 任务时：
|
||
1. 分析 `blocked_reason`，定位根因
|
||
2. 根据情况采取行动：
|
||
- **拆**：任务本身拆得不好 → 标记原任务 abandoned → 产出新任务卡
|
||
- **补**：缺少前置依赖 → 创建前置任务卡 → 原任务加 depends
|
||
- **调**：架构方向需调整 → 更新模块设计/决策记录 → 重新拆任务卡
|
||
3. 新任务卡就绪后，原 blocked 任务可标记为 abandoned 或更新为 todo
|
||
|
||
### 阶段 4：回顾 — 用户在桌面 App 查看
|
||
用户打开蓝图可视化：
|
||
- 看到全景进度
|
||
- 在「下一步」面板查看可派发任务
|
||
- 点击「复制派发」→ 粘贴给新 Claude 会话
|
||
|
||
### 飞轮的反馈信号
|
||
Claude 应关注这些信号来决定是否更新蓝图：
|
||
- 用户说"这个做完了" → 标记 done
|
||
- 用户说"这个不做了" → 标记 abandoned 或删除
|
||
- 用户说"这个要拆一下" → 拆分任务卡
|
||
- 用户说"记住这个决策" → 写入决策记录
|
||
- 用户没提蓝图但在讨论功能 → 主动提议更新蓝图
|
||
- 执行模型遇到无法解决的问题 → 标记 🔴 blocked + blocked_reason
|
||
- Opus 看到 blocked 任务 → 分析原因，拆/补/调后产出新任务卡
|
||
|
||
### 对话中的复杂度漂移检测
|
||
|
||
碎片化想法在对话中自然累积，有时从样式调整演变为架构改动。Claude 应主动识别并叫停。
|
||
|
||
**漂移信号**（以下任一出现即触发）：
|
||
- 原始请求是样式/布局，但现在涉及组件 state、props 或后端命令
|
||
- 本次对话累计改动文件 ≥ 4 个，且分属不同功能区域
|
||
- 用户说了"顺便"、"既然这样"、"要不也把 XX"
|
||
- 前端改动已延伸到 DB 结构或 Rust 命令
|
||
|
||
**Claude 的应对动作**：检测到漂移信号时暂停执行，输出：
|
||
|
||
> ⚠️ 范围漂移：我们从「[原始请求]」走到了「[当前方向]」，累计涉及 [N] 个文件。建议：
|
||
> A) 完成当前这步，其余记为 💭 concept 卡待下次处理
|
||
> B) 现在拉清单，走 /architect 重新规划
|
||
> C) 继续执行，我在 session 结束前汇总成任务卡
|
||
|
||
**Session 结束汇总**：任何有代码改动但无预建任务卡的会话，结束前 Claude 应输出：
|
||
|
||
> 📋 本次会话实际改动：[文件列表 + 简述]
|
||
> 是否整理为蓝图任务卡？
|
||
|
||
## 交互质量复盘笔记
|
||
|
||
> 本章节仅适用于**开发执行阶段**（实现代码时），初始化蓝图或同步蓝图时无需执行。
|
||
|
||
每完成一张 **M 或 L 复杂度**的任务卡后，Claude 应通过 `append_project_note`（MCP 工具）写入一条结构化复盘笔记。这是飞轮外环的原始数据来源——积累足够多条后，Claude 读一遍即可识别高频坑点和高效模式。
|
||
|
||
### 笔记格式
|
||
|
||
```
|
||
【复盘】<任务标题>
|
||
任务类型: 后端命令 | 前端组件 | 数据层 | MCP工具 | 架构调整
|
||
复杂度: S | M | L
|
||
实际轮数: N轮（预估 M 轮）
|
||
是否返工: 是/否
|
||
返工原因: <若返工，一句话说明根因，如"WSL路径格式未预料">
|
||
有效策略: <本次奏效的做法，一句话>
|
||
遗留风险: <若有，一句话>
|
||
auto_applied_rules: R01, R06 ← 本次任务触发并执行了哪些规则（无则省略）
|
||
rule_effectiveness: R01=有效, R06=有效 ← 规则是否阻止了问题（有效/无效/未验证）
|
||
```
|
||
|
||
**`auto_applied_rules` 填写说明**：
|
||
- 仅记录本次任务实际触发（Claude 主动检查或提示）的规则
|
||
- 若规则触发但用户选择跳过，也应记录（用于统计触发频率）
|
||
- `rule_effectiveness=无效` 表示规则触发了但没有阻止问题，这是最有价值的信号——梦核据此降低该规则置信度
|
||
|
||
### 触发时机
|
||
|
||
| 情况 | 操作 |
|
||
|------|------|
|
||
| M/L 任务卡标记为 ✅ done | 写一条复盘笔记（source: mcp） |
|
||
| 遇到非预期的系统边界或平台差异 | 额外写一条"陷阱记录"，遗留风险填具体复现条件 |
|
||
| 同类问题第二次出现 | 在新笔记中引用旧笔记时间戳，说明"同类问题复发" |
|
||
|
||
### 示例
|
||
|
||
```
|
||
【复盘】WSL项目路径检测
|
||
任务类型: 后端命令
|
||
复杂度: M
|
||
实际轮数: 6轮（预估 2 轮）
|
||
是否返工: 是
|
||
返工原因: wsl_path 字段存的是 Windows UNC 格式（\\wsl.localhost\Ubuntu-22.04\...），而非 Linux 路径，导致 wsl 子命令收到错误参数
|
||
有效策略: 在函数入口统一用 unc_to_distro_and_linux() 转换，一次解析，全程复用
|
||
遗留风险: Path::exists() 对 \\wsl.localhost\ 路径无效，所有 WSL 路径存在性检查必须走 wsl -d distro -- test -d/f
|
||
auto_applied_rules: R10
|
||
rule_effectiveness: R10=未验证（任务开始前未触发，事后归因）
|
||
```
|
||
|
||
> 这些笔记不替代决策记录（决策记录记架构 WHY，复盘笔记记执行 HOW 和踩坑）。两者都写。
|
||
|
||
---
|
||
|
||
## 飞轮外环（跨项目数据反哺）
|
||
|
||
内环描述的是单项目的执行流程。外环负责**把多个项目的执行数据聚合起来，反哺 CONVENTIONS 本身**。
|
||
|
||
### 数据采集：usage.json 快照
|
||
|
||
每次 Claude 读取 `.blueprint/manifest.yaml`（通过炼境打开蓝图时触发），炼境自动向项目的 `.blueprint/usage.json` 追加一条当日快照：
|
||
|
||
```json
|
||
{
|
||
"project_name": "my-project",
|
||
"snapshots": [
|
||
{
|
||
"at": "2026-04-05T10:00:00Z",
|
||
"conventions_version": "1.3.0",
|
||
"iteration": 1,
|
||
"modules": { "total": 22, "done": 18, "in_progress": 2, "planned": 1, "concept": 1, "blocked": 0, "stalled": [] },
|
||
"tasks": { "total": 45, "done": 38, "in_progress": 3, "blocked": 0, "todo": 4, "dispatched": 3 },
|
||
"blocked_reasons": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `dispatched` = 当前满足📋可派发条件的任务数（有 acceptance + complexity S/M；files 可选）
|
||
- 节流：同一 UTC 日期只写一条，避免多次打开导致数据膨胀
|
||
- 文件存于项目本地，不上传服务器
|
||
|
||
### 数据聚合：飞轮指标
|
||
|
||
炼境跨项目读取所有 usage.json，按 `conventions_version` 分组，对每个版本队列计算 4 项指标：
|
||
|
||
| 指标 | 计算方式 | 含义 |
|
||
|------|----------|------|
|
||
| 可派发率 | dispatched / total tasks | 任务卡规划质量，越高说明任务定义越清晰 |
|
||
| 任务完成率 | done / total tasks | 整体执行进度均值 |
|
||
| 飞轮持续率 | 30天内有快照的项目比例 | 外环是否在持续运转 |
|
||
| 阻塞密度 | blocked / total tasks | 系统性阻塞程度，越低越好 |
|
||
|
||
迭代感知：同一项目若 `iteration` 值增大，说明发生了主动重构。飞轮数据层对此类项目单独计算「当前迭代完成率」，与历史累计值区分展示，避免虚高。梦核 prompt 中标注「完成率跳变项目」供 Opus 分析是健康重构还是项目失控。
|
||
|
||
### 梦核分析：记忆巩固
|
||
|
||
炼境将聚合数据 + 当前 CONVENTIONS 全文格式化为提示词，发给 **Claude Opus** 做两件事：
|
||
|
||
- **固化**：哪些跨项目重复出现的阻塞模式、哪些有效实践，值得写进 CONVENTIONS
|
||
- **遗忘**：哪些休眠项目（90天无快照）的 AI 文档可以归档，哪些 CONVENTIONS 规则已过时
|
||
|
||
### 梦核写入纪律（蒸馏，不是追加）
|
||
|
||
梦核的产出是**替换操作，不是追加**。每次梦核后遵守：
|
||
|
||
1. **项目专属规则不进全局** → 写到该项目的 `.blueprint/rules.md`，不写入 CONVENTIONS
|
||
2. **全局规则上限 ≤ 25 条** → 超出则先合并/删除再新增；规则总量是飞轮健康度的信号
|
||
3. **改原条目，不加新条目** → R10 置信度需降，直接修改 R10 的 confidence 字段，不在旁边另起一条注释
|
||
4. **置信度元数据就地维护** → confidence / evidence_count / failure_cases 内嵌在各规则条目中，不另建文件
|
||
5. **一次性洞察不固化** → 梦核分析在对话中消费完毕，不另存 .md 文件；原料（复盘笔记）已在飞轮中，随时可重新生成
|
||
|
||
### 闭环路径
|
||
|
||
两条并行的反馈路径，速度不同：
|
||
|
||
```
|
||
【快速路径 — 项目级，无需发版】
|
||
执行任务 → 复盘笔记（auto_applied_rules）
|
||
↓
|
||
梦核分析项目笔记
|
||
↓
|
||
输出项目私有规则草案
|
||
↓
|
||
用户确认 → 写入 .blueprint/rules.md
|
||
↓
|
||
下次对话立即生效
|
||
|
||
【慢速路径 — 全局级，需发版】
|
||
执行任务 → usage.json 快照
|
||
↓
|
||
炼境跨项目聚合指标
|
||
↓
|
||
梦核提示词 → Claude Opus 分析
|
||
↓
|
||
用户/维护者审核建议
|
||
↓
|
||
更新 CONVENTIONS.md 源码 + 版本号
|
||
↓
|
||
发布新版炼境
|
||
↓
|
||
治理面板 sync_blueprint_rules → 分发到各项目
|
||
```
|
||
|
||
> **设计意图**：快速路径响应单个项目的学习，慢速路径沉淀跨项目的共识。CONVENTIONS.md 编译进炼境二进制保证全局规则版本可追溯；rules.md 存于项目本地实现快速迭代。两条路径互补，共同构成择升环。
|
||
|
||
## 无 MCP 环境兼容（Qwen Code / 其他 AI）
|
||
|
||
部分 AI 助手（如 Qwen Code）不支持 MCP 协议，无法调用炼境工具。此时用等价文件操作代替，行为与 MCP 调用一致：
|
||
|
||
| MCP 工具 | 等价文件操作 |
|
||
|---|---|
|
||
| `get_project_blueprint` | 直接读取 `.blueprint/manifest.yaml` |
|
||
| `get_project_file` | 直接读取对应文件路径 |
|
||
| `append_project_note` | 直接编辑 `.blueprint/modules/<id>.md`，在对应任务卡末尾追加复盘笔记 |
|
||
| `get_diagnostics` | 跳过，不影响主流程 |
|
||
| `list_group_projects` | 跳过，由用户告知上下文 |
|
||
|
||
### 飞轮外环的缺口
|
||
|
||
无 MCP 环境下，`usage.json` 快照**不会被炼境自动写入**（触发写入的是炼境响应 MCP 调用时的副作用）。
|
||
|
||
影响范围：飞轮外环的跨项目统计数据本次会话不计入。飞轮内环（单项目蓝图维护、任务卡状态、复盘笔记）不受影响。
|
||
|
||
补偿方式：Qwen Code 会话结束后，在炼境中手动打开该项目蓝图，触发一次快照写入即可。
|
||
|
||
---
|
||
|
||
## 复杂功能分析流程（/architect）
|
||
|
||
当需求复杂度为 **L 级**时，在写任何代码之前执行本流程。
|
||
|
||
### 步骤
|
||
|
||
1. 读取 `manifest.yaml`，定位相关模块和依赖关系
|
||
2. 读取受影响的核心文件，理解现有实现模式和系统边界
|
||
3. 输出设计文档，格式如下：
|
||
|
||
```
|
||
## 设计决策：<功能名>
|
||
|
||
### 背景
|
||
<关联的现有模块>
|
||
|
||
### 方案选择
|
||
<2-3 个方案及取舍，标注选定方案>
|
||
|
||
### 受影响文件
|
||
- 新增：<路径> — <用途>
|
||
- 修改：<路径> — <改动说明>
|
||
|
||
### 系统边界变更
|
||
<新增接口 / 数据表 / 字段定义>
|
||
|
||
### 风险点
|
||
- <风险>：<规避方式>
|
||
|
||
### 拆解建议
|
||
建议拆为 N 张任务卡，依赖顺序：卡A → 卡B → 卡C
|
||
```
|
||
|
||
4. **不写任何代码**，设计文档经用户确认后再进入拆解流程
|
||
|
||
---
|
||
|
||
## 任务拆解流程（/splitter）
|
||
|
||
在设计文档确认后执行，产出可派发任务卡并写入蓝图文件。
|
||
|
||
### 步骤
|
||
|
||
1. 确认目标模块 id，读取对应 `modules/<id>.md`
|
||
2. 按以下原则拆解：
|
||
- **粒度**：每张卡 complexity 必须是 S 或 M，不允许 L
|
||
- **依赖顺序**：数据层 → 后端命令 → 前端封装 → UI 组件
|
||
- **可派发标准**：每张卡必须有 `acceptance` + `complexity`；`files` 建议填入预期路径，有则更准确
|
||
3. 将任务卡追加到 `modules/<id>.md`
|
||
4. 更新 `manifest.yaml`：status → `planned`，更新 `updated` 日期
|
||
5. 输出拆解摘要（卡名、complexity、执行顺序）
|
||
|
||
### 质量检查
|
||
- [ ] 每张卡有 `acceptance`
|
||
- [ ] complexity 全部是 S 或 M
|
||
- [ ] 有依赖的卡填了 `depends`
|
||
- [ ] 任务卡按执行顺序排列
|
||
- [ ] `files` 尽量填入（建议项，有则帮助 agent 更快定位）
|
||
|
||
---
|
||
|
||
## 技能依赖
|
||
|
||
本蓝图工作流依赖以下 Claude Code 技能处理 L 级复杂任务：
|
||
|
||
| 技能 | 触发词 | 用途 |
|
||
|------|--------|------|
|
||
| architect | `/architect` | 复杂功能架构分析，输出设计文档 |
|
||
| splitter | `/splitter` | 将设计文档拆解为可派发任务卡 |
|
||
|
||
### 检测方式
|
||
|
||
在 Claude Code 中输入 `/architect`，若 Claude 开始执行架构分析步骤则已就绪。
|
||
若提示找不到技能，按以下方式安装。
|
||
|
||
### 安装方式
|
||
|
||
技能文件随本项目分发，位于 `.claude/skills/`：
|
||
|
||
```bash
|
||
# 复制到全局技能目录（任意项目均可使用）
|
||
cp -r .claude/skills/architect ~/.claude/skills/
|
||
cp -r .claude/skills/splitter ~/.claude/skills/
|
||
|
||
# 或仅在当前项目使用（.claude/skills/ 已存在则无需操作）
|
||
```
|
||
|
||
> 若通过炼境同步本蓝图规则，`.claude/skills/` 会随蓝图一并分发，无需手动安装。
|
||
|
||
---
|
||
|
||
## Rust 代码可测试性规范
|
||
|
||
> 本规范仅适用于**新增** Rust 函数，存量代码不强制回填。
|
||
|
||
### 强制规则
|
||
|
||
**禁止在业务函数内部调用 `pool().get()`**，改为由调用方传入连接：
|
||
|
||
```rust
|
||
// ❌ 禁止（无法在测试中注入 in-memory DB）
|
||
pub fn my_fn(args: Vec<String>) -> Result<Vec<Foo>, String> {
|
||
let conn = crate::db::pool().get()?;
|
||
...
|
||
}
|
||
|
||
// ✅ 正确（依赖注入，测试可传入 in-memory DB）
|
||
pub fn my_fn(conn: &rusqlite::Connection, args: Vec<String>) -> Result<Vec<Foo>, String> {
|
||
...
|
||
}
|
||
|
||
// Tauri command 层负责获取连接并调用
|
||
#[tauri::command]
|
||
pub fn my_command(args: Vec<String>) -> Result<Vec<Foo>, String> {
|
||
let conn = crate::db::pool().get().map_err(|e| e.to_string())?;
|
||
my_fn(&conn, args)
|
||
}
|
||
```
|
||
|
||
### 测试要求
|
||
|
||
| 函数类型 | 测试要求 |
|
||
|---------|---------|
|
||
| 纯逻辑函数（无 DB） | 必须附带 `#[cfg(test)]` 测试 |
|
||
| 含 DB 的业务函数 | 必须使用依赖注入写法，附带 in-memory DB 测试 |
|
||
| Tauri command 薄包装层 | 无需测试（只做连接获取 + 函数调用） |
|
||
|
||
### 任务卡 acceptance 模板补充
|
||
|
||
含 Rust 业务逻辑的 M/L 任务卡，acceptance 须包含：
|
||
|
||
```
|
||
- [ ] 新增函数使用依赖注入（conn 作为参数）
|
||
- [ ] 附带 #[cfg(test)] 测试，覆盖主路径 + 空数据边界
|
||
- [ ] cargo test 通过
|
||
```
|
||
|
||
### 测试写法模板
|
||
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use rusqlite::Connection;
|
||
|
||
fn setup() -> Connection {
|
||
let conn = Connection::open_in_memory().unwrap();
|
||
// 建表语句（从 db::migrate 复制对应部分）
|
||
conn.execute_batch("CREATE TABLE IF NOT EXISTS ...").unwrap();
|
||
conn
|
||
}
|
||
|
||
#[test]
|
||
fn test_主路径() {
|
||
let conn = setup();
|
||
// 插入测试数据
|
||
// 调用函数
|
||
// 断言结果
|
||
}
|
||
|
||
#[test]
|
||
fn test_空数据返回空集合() {
|
||
let conn = setup();
|
||
let result = my_fn(&conn, vec![]);
|
||
assert!(result.unwrap().is_empty());
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端代码可测试性规范
|
||
|
||
> **适用范围**：有独立纯逻辑层的项目（Web 服务、Node CLI 等）。
|
||
> Tauri 桌面应用的主测试路径是 `cargo test`（Rust 层）；
|
||
> 前端大量代码是 Tauri IPC 薄包装（`invoke()` 调用），无法在 Node 环境运行，不适合 vitest。
|
||
> 炼境自身属于 Tauri 项目，**前端暂不配置 vitest**，以下规范待引入真实纯逻辑模块时生效。
|
||
|
||
### 何时引入 vitest
|
||
|
||
满足以下条件之一时才引入：
|
||
|
||
1. 项目有可独立运行（不依赖 Tauri 运行时）的纯逻辑模块，且该模块代码量 ≥ 200 行
|
||
2. 某个 bug 在纯逻辑层反复出现，需要回归测试固化
|
||
|
||
引入时配置 `vitest.config.ts`，使用 `pnpm add -D vitest`。
|
||
|
||
### 测试文件位置
|
||
|
||
前端测试文件与源文件同目录，命名约定：`<filename>.test.ts(x)`。
|
||
|
||
```
|
||
src/lib/utils.ts
|
||
src/lib/utils.test.ts ← vitest 自动发现（仅纯逻辑文件）
|
||
```
|
||
|
||
### 测试要求（适用时）
|
||
|
||
| 代码类型 | 测试要求 |
|
||
|---------|---------|
|
||
| 纯逻辑函数（数据处理、格式化、解析、校验） | M 级任务卡强制附带测试，覆盖主路径 + 空/边界 |
|
||
| Tauri IPC 薄包装层（invoke 调用） | 无需测试（主路径走 cargo test） |
|
||
| React 组件 | 无需测试（UI 由人工终验） |
|
||
|
||
### 任务卡 acceptance 模板（适用时）
|
||
|
||
含前端纯逻辑的 M 级任务卡：
|
||
|
||
```
|
||
- [ ] 附带 vitest 测试，覆盖主路径 + 空数据边界
|
||
- [ ] pnpm vitest run 全绿
|
||
```
|
||
|
||
### 测试写法模板
|
||
|
||
```typescript
|
||
import { describe, it, expect } from "vitest";
|
||
import { myFunction } from "./utils";
|
||
|
||
describe("myFunction", () => {
|
||
it("正常路径", () => {
|
||
expect(myFunction("input")).toBe("expected");
|
||
});
|
||
|
||
it("空输入不报错", () => {
|
||
expect(myFunction("")).toBeNull();
|
||
});
|
||
|
||
it("非法输入返回安全默认值", () => {
|
||
expect(myFunction("invalid")).toBeNull();
|
||
});
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 项目私有规则（rules.md）
|
||
|
||
每个项目可以在 `.blueprint/rules.md` 中维护**仅对本项目生效**的推荐规则，格式与全局规则库完全相同。
|
||
|
||
### 优先级
|
||
|
||
```
|
||
项目私有规则（.blueprint/rules.md）> 全局规则（CONVENTIONS 自动推荐规则库）
|
||
```
|
||
|
||
项目私有规则更精准（来自该项目真实数据），全局规则更广泛（来自跨项目共识）。冲突时项目规则优先。
|
||
|
||
### 对话开始时的读取顺序
|
||
|
||
```
|
||
1. manifest.yaml ← 项目全景
|
||
2. CONVENTIONS.md ← 协议定义 + 全局规则
|
||
3. .blueprint/rules.md ← 项目私有规则（若存在，合并应用）
|
||
```
|
||
|
||
### 梦核写入路径
|
||
|
||
梦核（飞轮阶段三启动后）分析项目复盘笔记后，除了输出 CONVENTIONS 更新建议，还应输出**项目私有规则草案**，格式如下：
|
||
|
||
```markdown
|
||
## 建议新增项目私有规则
|
||
|
||
| rule_id | 触发条件 | 自动动作 | confidence | evidence_count | derived_from |
|
||
|---------|---------|---------|-----------|---------------|-------------|
|
||
| P01 | <本项目特有触发条件> | <自动动作> | 0.70 | 3 | <复盘笔记引用> |
|
||
```
|
||
|
||
用户确认后，Claude 直接将规则写入 `.blueprint/rules.md`，**无需等待炼境发版**。这是项目级择升环与全局发版解耦的关键路径。
|
||
|
||
### rules.md 文件格式
|
||
|
||
```markdown
|
||
# 项目私有规则
|
||
|
||
> 本文件由梦核分析 + 用户确认后生成，Claude 每次对话开始时读取并合并应用。
|
||
> 规则格式与 CONVENTIONS 自动推荐规则库相同，优先级高于全局规则。
|
||
|
||
## 规则列表
|
||
|
||
### P01 — 规则标题
|
||
- **触发条件**：xxx
|
||
- **自动动作**：xxx
|
||
- **confidence**: 0.70
|
||
- **evidence_count**: 3
|
||
- **derived_from**: 复盘笔记 YYYY-MM-DD，任务"xxx"中发现
|
||
```
|
||
|
||
### 何时创建 rules.md
|
||
|
||
- 梦核首次输出项目私有规则建议时创建
|
||
- 也可手动创建，记录人工识别的项目特有模式
|
||
- 文件不存在时跳过，不影响全局规则生效
|
||
|
||
---
|
||
|
||
## 自动推荐规则库
|
||
|
||
> 本章节定义了 Claude 在开发过程中应**主动触发**的高收益决策规则。
|
||
> 规则有置信度（confidence）和证据数（evidence_count），置信度越高越应自动执行，无需用户确认。
|
||
|
||
### 执行策略
|
||
|
||
| confidence 范围 | 执行方式 |
|
||
|----------------|---------|
|
||
| ≥ 0.80 | 直接执行，仅一行说明（"按 R01 检查..."） |
|
||
| 0.60 ~ 0.79 | 执行前单句说明原因，用户可跳过 |
|
||
| < 0.60 | 仅作提醒，不自动执行 |
|
||
|
||
置信度由梦核（阶段三启动后）根据 evidence_count 和有效率自动更新；在此之前由人工在复盘中维护。
|
||
|
||
### scope 字段
|
||
|
||
每条规则有 `scope` 字段，标明适用范围。Claude 应在应用规则前检查当前项目是否匹配：
|
||
|
||
| scope 值 | 含义 |
|
||
|---------|------|
|
||
| `universal` | 适用于任何代码项目 |
|
||
| `tauri` | 仅适用于 Tauri 项目 |
|
||
| `rust` | 仅适用于含 Rust 后端的项目 |
|
||
| `sqlite` | 仅适用于使用 SQLite 的项目 |
|
||
| `react` | 仅适用于 React 前端项目 |
|
||
|
||
多个 scope 用 `+` 连接，如 `tauri+rust`。**scope 不匹配时跳过该规则，不作提醒。**
|
||
|
||
项目私有规则（`rules.md`）无需 scope 字段，默认对本项目全部生效。
|
||
|
||
### boundaries 与 failure_cases 字段（可选）
|
||
|
||
scope 描述规则的正向适用范围，**boundaries 描述已知的反向边界**——规则在什么条件下会失效。失败案例是边界的证据来源：
|
||
|
||
```markdown
|
||
- **boundaries**: <已知不适用条件，如"squash merge 项目下 commit 数≈轮数 不成立">
|
||
- **failure_cases**:
|
||
- YYYY-MM-DD：<触发条件> → <规则未能阻止的现象>（项目：xxx）
|
||
```
|
||
|
||
- 规则**没有 failure_cases ≠ 规则完美**，只说明边界还未被探测到
|
||
- 梦核分析时应把 failure_cases 视为最高价值信号：同一条件下反复失效 → 拆分规则为带条件的变体（原规则收窄 scope + 新增变体规则），而非简单降低 confidence
|
||
- 边界记录使经验"细化"而不是"被推翻"——这是规则库因果自洽的核心机制
|
||
|
||
### 规则列表
|
||
|
||
#### R01 — 新增 Tauri command 时检查前端封装层
|
||
- **scope**: `tauri`
|
||
- **触发条件**：在 `src-tauri/src/commands/` 下新增 `#[tauri::command]` 函数
|
||
- **自动动作**：读取 `src/lib/commands.ts`，确认是否有对应封装；缺失则提示补写，不阻止执行
|
||
- **confidence**: 0.95
|
||
- **evidence_count**: 12
|
||
- **derived_from**: 多次发生前后端接口断层（命令已实现但 commands.ts 未同步，前端调用报错）；梦核 2026-07-04：12 次命中，0 次返工，最稳信号
|
||
|
||
#### R02 — 任务卡无 acceptance 时先补写再动代码
|
||
- **scope**: `universal`
|
||
- **触发条件**：任务卡 `acceptance` 字段为空或缺失，但已准备开始执行
|
||
- **自动动作**：暂停执行，根据任务描述推导验收标准草稿，请用户确认后再写第一行代码
|
||
- **confidence**: 0.92
|
||
- **evidence_count**: 18
|
||
- **derived_from**: 无验收标准导致完成定义模糊，任务频繁反复（"做完了但感觉不对"）
|
||
|
||
#### R03 — M/L 任务标记 done 后写复盘笔记
|
||
- **scope**: `universal`
|
||
- **触发条件**：M 或 L 复杂度的任务卡状态变更为 ✅ done
|
||
- **自动动作**：调用 `append_project_note` 写入复盘笔记（见"交互质量复盘笔记"章节格式）
|
||
- **confidence**: 0.88
|
||
- **evidence_count**: 24
|
||
- **derived_from**: 飞轮外环数据来源，无复盘笔记则梦核无输入，整个飞轮断链
|
||
|
||
#### R04 — 对话改动 ≥ 4 个跨功能区文件时触发漂移警告
|
||
- **scope**: `universal`
|
||
- **触发条件**：单次对话累计改动文件 ≥ 4 个，且分属不同功能区（frontend/backend/infra）
|
||
- **自动动作**：输出范围漂移提示（见"对话中的复杂度漂移检测"章节），给出 A/B/C 三个选项
|
||
- **confidence**: 0.85
|
||
- **evidence_count**: 12
|
||
- **derived_from**: 多次"样式改动演变成后端重构"的失控扩散，最终要么返工要么留下技术债
|
||
|
||
#### R05 — SQLite 涉及新表或新字段时检查 migration
|
||
- **scope**: `sqlite`
|
||
- **触发条件**：在项目中出现 `CREATE TABLE` / `ALTER TABLE` / 新增列定义
|
||
- **自动动作**：检查是否有对应 migration 逻辑；缺失则提示添加，防止旧版本升级后 schema 断裂
|
||
- **confidence**: 0.82
|
||
- **evidence_count**: 7
|
||
- **derived_from**: 数据库 schema 变更未同步 migration，导致旧安装版本升级后启动报错
|
||
|
||
#### R06 — Rust 业务函数含 DB 操作时强制依赖注入
|
||
- **scope**: `rust+sqlite`
|
||
- **触发条件**：新增 Rust 函数内部直接获取 DB 连接（`pool().get()` 或等价写法）
|
||
- **自动动作**：提示改为依赖注入写法，连接由调用方传入；command 层负责获取连接
|
||
- **confidence**: 0.93
|
||
- **evidence_count**: 15
|
||
- **derived_from**: 飞轮阶段一实现时无测试导致静默 bug 上线；依赖注入是唯一能让 in-memory DB 测试覆盖业务逻辑的方式
|
||
|
||
#### R07 — 数据关键路径函数必须附带单元测试
|
||
- **scope**: `universal`
|
||
- **触发条件**：新增函数负责数据采集、聚合、解析等关键路径（影响下游分析或展示的正确性）
|
||
- **自动动作**：在实现函数前提醒附带单元测试，覆盖正常路径 + 空数据边界；完成后验证测试全绿
|
||
- **confidence**: 0.95
|
||
- **evidence_count**: 6
|
||
- **derived_from**: 飞轮阶段一数据采集 bug 因无测试静默上线，污染所有下游分析
|
||
|
||
#### R08 — UI 状态显示必须来自真实检测
|
||
- **scope**: `universal`
|
||
- **触发条件**：前端组件显示运行状态、健康状态、操作结果等实时信息
|
||
- **自动动作**：检查对应后端是否做了真实检测而非硬编码；发现硬编码状态时标记为需修复
|
||
- **confidence**: 0.72
|
||
- **evidence_count**: 3
|
||
- **derived_from**: 设置页 MCP 状态硬编码为"运行中"，注入失败时 toast 始终显示成功——UI 掩盖真实问题
|
||
- **boundaries**: 展示类状态（loading spinner、空状态提示）属 UI 职责，不适用本规则；本规则仅限"系统真实运行状态"类展示
|
||
- **failure_cases**:
|
||
- 2026-07-04（梦核归因）：3 次命中全部伴随返工（100%），规则触发但未阻止问题——根因是"状态硬编码"发生在编写时，规则检查发生在展示层，时序错位；建议在写 Tauri command 时即检查返回值是否真实（与 R01 联动）
|
||
|
||
#### R09 — 自动化边界：事件触发只标 🔵，不标 ✅
|
||
- **scope**: `universal`
|
||
- **触发条件**：讨论或实现基于外部事件（git commit、CI 结果等）自动更新任务卡状态
|
||
- **自动动作**：确认自动化只将任务卡置为 🔵 in_progress，绝不自动置为 ✅ done；完成语义需人工或 Claude 验收确认
|
||
- **confidence**: 0.91
|
||
- **evidence_count**: 4
|
||
- **derived_from**: 代码提交 ≠ 功能验收通过，自动标完成导致数据与实际不符
|
||
|
||
#### R10 — 对接外部协议/API 前先验证客户端实际行为
|
||
- **scope**: `universal`
|
||
- **触发条件**：实现与外部客户端的协议对接（MCP、LSP、WebSocket、SSE、OAuth 等）
|
||
- **自动动作**：在开始实现前，先通过文档或工具（curl、抓包）确认客户端实际发出的请求格式；不基于"通用规范"假设行为
|
||
- **confidence**: 0.60
|
||
- **evidence_count**: 6
|
||
- **derived_from**: Claude Code MCP 客户端用 GET 发起 SSE 握手，炼境只接受 POST 导致 405，MCP 整体失效
|
||
- **boundaries**: 实时协议（WebSocket、SSE）的完整握手序列难以通过 curl 完全预验证，需配合协议库调试工具（MCP Inspector 等）；本规则防的是"基于规范假设而不看实际请求"，不能防"验证了但实现仍有差"
|
||
- **failure_cases**:
|
||
- 2026-07-04（梦核归因）：6 次命中中 5 次伴随返工（83%），显示规则触发后问题仍发生——根因是协议对接本身复杂度高，"验证客户端行为"这一步经常被跳过或验证不够深入；建议将规则收窄为强制前置步骤：实现前必须有一条 curl/工具调用记录证明验证已执行
|
||
|
||
#### R11 — 自动执行规则失效时必须记录失败案例
|
||
- **scope**: `universal`
|
||
- **触发条件**：confidence ≥ 0.80 的规则被自动执行后，其本应阻止的问题仍然发生（返工、报错、验收失败）
|
||
- **自动动作**：在该规则条目下追加一条 failure_case（日期 + 触发条件 + 现象 + 项目）；若为项目私有规则写入 rules.md，全局规则则在复盘笔记中记录并标注 rule_effectiveness=无效，等梦核汇总
|
||
- **confidence**: 0.80
|
||
- **evidence_count**: 1
|
||
- **derived_from**: 规则库只有正向 scope 无反例结构，失败信息流失导致置信度虚高、边界永远探测不到（2026-07-02 经验飞轮设计评审）
|
||
|
||
#### R12 — 边界单点实现：业务校验只写在能力本体层
|
||
- **scope**: `universal`
|
||
- **触发条件**：实现或修改带业务边界的功能（哪些允许、什么条件下允许、非法时如何拒绝）
|
||
- **自动动作**：校验逻辑只写在能力本体层（API / command / 服务函数）；UI 层只呈现状态（置灰/提示），不复制业务判断。发现前端 guard 承载业务边界时标记为需下沉
|
||
- **confidence**: 0.85
|
||
- **evidence_count**: 2
|
||
- **derived_from**: 空契约生成静默 return（边界错写进 UI 层，与文案承诺冲突）、改 Token 假成功（UI 报成功但本体未执行）——两例均为"人与 agent 验证路径空间分裂"症状（2026-07-03）
|
||
- **boundaries**: 纯展示逻辑（排序、折叠、格式化）属 UI 职责，不适用本规则
|
||
|
||
#### R13 — M/L 任务完成前，验收路径须被真实走通
|
||
- **scope**: `universal`
|
||
- **触发条件**：M 或 L 复杂度任务卡准备标记 ✅ done
|
||
- **自动动作**：acceptance 所述验证路径须由人或 agent **通过功能自身入口**真实走通一次（agent 按钮载体就近选择：Web 服务=HTTP API、CLI=命令、桌面应用=测试调用同一函数、UI 呈现层=Playwright 兜底）。禁止绕过功能手改产物冒充验证；agent 走通的关键路径顺手固化为一条测试（侦察→驻军），一次性验收不固化
|
||
- **confidence**: 0.88
|
||
- **evidence_count**: 11
|
||
- **derived_from**: noteapp manifest 被手改导致 schema 约束修复未获真实验证、autoforphone 接线被命令行代办导致 G7 按钮未走通——手动替代掩盖功能真实状态（2026-07-03 用户裁决 + MCP 治理三件套 agent 实测首证）；梦核 2026-07-04：11 次命中，9% 返工率，高频高效
|
||
|
||
### 规则演进路径
|
||
|
||
```
|
||
人工识别（初始）
|
||
↓ evidence_count 累积 5+ 次
|
||
低置信验证期（confidence 0.60~0.79）
|
||
↓ 持续有效，evidence_count 15+
|
||
自动执行期（confidence ≥ 0.80）
|
||
↓ 发现无效或场景已变化
|
||
降级/归档（confidence 跌至 0.4 以下）
|
||
```
|
||
|
||
梦核（飞轮阶段三启动后）将根据复盘笔记中的 `auto_applied_rules` 和 `rule_effectiveness` 字段自动更新 confidence。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- 不要删除已完成的任务卡，它们是项目历史的一部分
|
||
- 模块 id 一旦确定尽量不要修改（会影响 edges 引用）
|
||
- 每次更新后修改 manifest.yaml 顶部的 `updated` 日期
|
||
- progress 由桌面 App 自动从任务卡完成比例计算，不需要手动维护
|
||
- 当用户的操作隐含了蓝图变更但没有明说时，Claude 应主动提议更新（而非沉默）
|
||
- **批量执行完成后须做完整性检查**：同一会话内连续完成多张任务卡时，结束前必须逐一确认：① 每张已完成的子任务 status 改为 done，前缀改为 ✅；② manifest.yaml 中对应模块的 status 已同步更新。两层缺一不可。（背景：单卡两阶段流程天然同步，批量执行时容易只改模块级 status 而漏掉子任务级更新，导致 App 看板 progress 数据失真）
|