eb346ae1fd
运行时可观测性：
- 新增 runtime_logs SQLite 表，提供全局 log_event 写入函数（保留最近 500 条）
- mcp_server/mcp_inject/groups 关键路径接入结构化日志
- MCP 新增 get_diagnostics 工具，返回注入摘要与近期错误
- add_group_member 注入失败时前端显示黄色 toast 警告
健康中心：
- 新增 run_health_check 命令（6 项并行检查：MCP/Git 路径/项目路径/GitHub Token/编辑器/DB 延迟）
- 新增质量指标聚合（休眠项目/孤立项目/注入异常组/无路径项目）
- 侧边栏新增健康中心页面，支持手动刷新和诊断报告复制
- 设置页 MCP 状态改为真实 HTTP ping 检测
项目导师：
- 新增 get_mentor_context 后端命令，聚合健康状态/蓝图摘要/近期错误
- MCP 新增 get_project_mentor_context 工具（含产品组归属校验）
- 项目卡片底部新增 🎓 导师按钮，面板支持复制结构化 Markdown 报告
- 修复 WSL 项目路径识别：wsl_path 存 UNC 格式时自动提取 distro 和 Linux 路径，改用 wsl 命令检查路径存在性（规避 Path::exists() 对 \wsl.localhost\... 不可靠的问题）
AI 工作流：
- 新增 AI-WORKFLOW.md、.claude/skills/ 技能体系配置
- 更新 CLAUDE.md 补充蓝图驱动开发规范
214 lines
6.0 KiB
Markdown
214 lines
6.0 KiB
Markdown
# AI 辅助开发工作流手册
|
||
|
||
> 本项目基于蓝图×飞轮工作流，以下技能需要在合适时机手动触发。
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
| 技能 | 什么时候触发 | 一句话说明 |
|
||
|------|------------|-----------|
|
||
| `/catchup` | **新会话开始时** | 读蓝图状态，找中断任务，告诉你现在在哪、该干嘛 |
|
||
| `/architect` | 需求复杂，不知道从哪里改起 | 先读代码再设计，不要直接开写 |
|
||
| `/splitter` | architect 出设计文档之后 | 把设计拆成可执行的任务卡 |
|
||
| `/spec-check` | 代码写完，提交之前 | 核对是否满足任务卡的验收标准 |
|
||
| `/Dev-edge-case` | M 级任务代码写完之后 | 穷举所有边界情况，找出遗漏 |
|
||
| `/code-review` | 每次提交之前 | 审查正确性、安全性、一致性 |
|
||
| `/smart-commit` | code-review 通过之后 | 生成规范的 Conventional Commits message |
|
||
| `/Dev-deep-think` | 感觉方案不够好但说不清哪里有问题 | 深度迭代，推动思考超越表面 |
|
||
| `/simplify` | 重构场景，代码写得太复杂 | 找出可复用和可简化的地方 |
|
||
|
||
---
|
||
|
||
## 一次会话的完整节奏
|
||
|
||
### 开始会话
|
||
Claude 自动读取 `.blueprint/manifest.yaml`，你无需操作。
|
||
|
||
如果是**跨会话续接**（上次没做完、新开了一个对话），运行：
|
||
```
|
||
/catchup
|
||
```
|
||
它会告诉你上次做到哪里、中断的任务还差什么、可以立即派发的任务有哪些。
|
||
|
||
---
|
||
|
||
### 阶段零：聊需求（无需触发技能，Claude 主动更新蓝图）
|
||
|
||
聊需求时 Claude 会根据你说的话自动更新蓝图，**你不需要触发任何命令**：
|
||
|
||
| 你说的 | Claude 自动做的 |
|
||
|--------|----------------|
|
||
| "我想加个 XX 功能" | 在 manifest.yaml 新增模块（status: concept），建 modules/<id>.md |
|
||
| "这个功能需要 A、B、C 三步" | 在模块文件里拆出 3 张任务卡 |
|
||
| "这个方案确定了" | 模块 status → planned，补充 files 和 acceptance |
|
||
| "开始做 XX" | 模块 status → in_progress，任务卡前缀改为 🔵 |
|
||
| "为什么选这个方案" | 写入模块的「决策记录」 |
|
||
|
||
> **注意**：如果 Claude 没有主动更新蓝图，可以直接说"帮我更新一下蓝图"，它会补上。
|
||
|
||
---
|
||
|
||
### 场景一：简单任务（S 级）
|
||
|
||
```
|
||
1. 告诉 Claude 要做什么
|
||
2. Claude 写代码
|
||
3. /spec-check ← 核对验收标准（可选，有任务卡时推荐）
|
||
4. /code-review ← 审查代码
|
||
5. git add
|
||
6. /smart-commit ← 规范提交
|
||
```
|
||
|
||
---
|
||
|
||
### 场景二：中等任务（M 级）
|
||
|
||
```
|
||
1. 告诉 Claude 要做什么
|
||
2. Claude 写代码
|
||
3. /spec-check ← 核对验收标准（可选）
|
||
4. /Dev-edge-case ← 穷举边界情况
|
||
5. 补充遗漏的处理
|
||
6. /code-review ← 审查代码
|
||
7. git add
|
||
8. /smart-commit ← 规范提交
|
||
```
|
||
|
||
---
|
||
|
||
### 场景三：复杂需求（L 级，需先拆）
|
||
|
||
```
|
||
1. 告诉 Claude 需求背景
|
||
2. /architect ← 先做架构分析，不写代码
|
||
3. 确认设计文档
|
||
4. /splitter ← 拆成 S/M 任务卡，写入蓝图
|
||
5. 逐张任务卡按场景一/二执行
|
||
```
|
||
|
||
---
|
||
|
||
### 场景四：重构 / 代码质量优化
|
||
|
||
```
|
||
1. /simplify ← 找出过度复杂的地方并简化
|
||
2. /code-review ← 确认重构没有引入问题
|
||
3. git add
|
||
4. /smart-commit
|
||
```
|
||
|
||
---
|
||
|
||
## 各技能详解
|
||
|
||
### `/catchup` — 会话续接
|
||
**触发信号**：
|
||
- 新开了一个对话，上次任务没做完
|
||
- 不确定上次做到哪里了
|
||
- 想快速了解当前项目状态和可做的事
|
||
|
||
**产出**：中断任务的续接建议 + 可派发任务列表 + 阻塞任务摘要
|
||
|
||
---
|
||
|
||
### `/architect` — 架构分析
|
||
**触发信号**：
|
||
- 这个需求涉及多个文件，不知道改哪里
|
||
- 需要新增数据表或后端接口
|
||
- 感觉随便改会破坏现有逻辑
|
||
|
||
**不要触发的情况**：
|
||
- 需求很明确，只改一两个文件（直接做，S/M 级）
|
||
|
||
**产出**：设计文档（方案选择 / 受影响文件 / 系统边界 / 风险点）
|
||
|
||
---
|
||
|
||
### `/splitter` — 任务拆解
|
||
**触发信号**：
|
||
- `/architect` 刚出了设计文档
|
||
- 设计文档里有"拆解建议"
|
||
|
||
**前提**：当前对话中必须有 architect 的设计文档，否则结果不可靠。
|
||
|
||
**产出**：写入 `.blueprint/modules/<id>.md` 的任务卡（有 files + acceptance）
|
||
|
||
---
|
||
|
||
### `/spec-check` — 验收核对
|
||
**触发信号**：
|
||
- 代码刚写完，提交之前
|
||
- 任务卡有明确的 acceptance 字段
|
||
|
||
**价值**：避免"代码跑通了但没满足当初说好的验收条件"
|
||
|
||
---
|
||
|
||
### `/Dev-edge-case` — 边界穷举
|
||
**触发信号**：
|
||
- 任务涉及条件判断、数据校验、异步操作
|
||
- M 级任务代码写完后
|
||
- code-review 前
|
||
|
||
**注意**：它只列出缺失的处理，不评价代码好坏。看完它的输出再决定要不要补充。
|
||
|
||
---
|
||
|
||
### `/code-review` — 代码审查
|
||
**触发信号**：每次 `git add` 之后，`git commit` 之前。
|
||
|
||
**审查维度**：正确性 / 安全性 / 一致性 / 可维护性 / 性能
|
||
|
||
**输出**：
|
||
- ✅ 好的做法
|
||
- ⚠️ 建议改进（非阻塞）
|
||
- ❌ 必须修复（阻塞提交）
|
||
|
||
---
|
||
|
||
### `/smart-commit` — 规范提交
|
||
**触发信号**：code-review 没有 ❌ 问题之后。
|
||
|
||
**格式**：Conventional Commits
|
||
```
|
||
feat: 新功能
|
||
fix: 修复
|
||
refactor: 重构
|
||
docs: 文档
|
||
style: 样式
|
||
test: 测试
|
||
chore: 构建/工具
|
||
```
|
||
|
||
**注意**：它会展示生成的 message，等你确认后才执行 `git commit`。
|
||
|
||
---
|
||
|
||
### `/Dev-deep-think` — 深度思考
|
||
**触发信号**：
|
||
- 方案能跑，但感觉哪里不对劲
|
||
- code-review 有 ⚠️ 但不确定怎么改
|
||
- 想在提交前再推敲一遍设计
|
||
|
||
**不要滥用**：S 级任务不需要，会浪费上下文。
|
||
|
||
---
|
||
|
||
### `/simplify` — 简化重构
|
||
**触发信号**：
|
||
- 某段代码越改越复杂
|
||
- 发现有重复逻辑可以合并
|
||
- 明确是重构任务，不是新功能
|
||
|
||
---
|
||
|
||
## 自动触发的技能（无需手动）
|
||
|
||
以下技能 Claude 会根据上下文自动调用，不需要你输入：
|
||
|
||
| 技能 | 自动触发条件 |
|
||
|------|------------|
|
||
| `claude-api` | 代码中出现 `import anthropic` 等 |
|
||
| `update-config` | 你说"每次 XX 时自动做 YY"类需求 |
|