Reorganize workspace and archive skill artifacts
This commit is contained in:
zhuyongxin
@@ -0,0 +1,270 @@
|
||||
# Explore / Essence / Follow 最新设计总结
|
||||
|
||||
**版本基线**：v0.5.0
|
||||
**对应 skill 本体**：`skill-workbench/generated-skills/skills/`
|
||||
**历史来源**：
|
||||
|
||||
- `skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md`
|
||||
- `skill-workbench/history/docs/superpowers/specs/`
|
||||
- `skill-workbench/history/docs/superpowers/changelog/`
|
||||
|
||||
## 一句话定位
|
||||
|
||||
`explore`、`essence`、`follow` 是一组学习型 skill family：
|
||||
|
||||
- `explore` 负责项目级理解。
|
||||
- `essence` 负责深挖 1-2 个最值得迁移的核心设计。
|
||||
- `follow` 负责基于已有报告做交互式跟学。
|
||||
|
||||
三者不是“深浅不同的同一个技能”，而是学习链路中的三个不同角色。
|
||||
|
||||
## 设计背景
|
||||
|
||||
早期 superpowers 设计试图覆盖完整学习过程，但在实践中出现了几个问题：
|
||||
|
||||
1. 阶段过多，`explore` 同时承担项目理解、深度分析、教学输出，边界不清。
|
||||
2. `/essence` 曾被误设计成 `/explore` 的轻量版，导致无法稳定聚焦“值得偷走的设计”。
|
||||
3. `/follow` 曾倾向重新扫描项目，削弱了它“基于已有报告教学”的定位。
|
||||
4. HTML、Deep Fission、Verify 等输出阶段让 skill 变重，增加上下文和执行成本。
|
||||
5. 历史 docs 中存在过时 proposal、plan 和已删除技能引用，需要收敛为当前真实实现。
|
||||
|
||||
v0.5.0 的核心改造是：**拆清职责，减少阶段，只保留能稳定触发、稳定产出的学习动作。**
|
||||
|
||||
## 三技能职责边界
|
||||
|
||||
| Skill | 核心问题 | 输入 | 输出 | 不做什么 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `explore` | 这个项目是什么，为什么值得学，从哪里开始？ | 新项目、代码仓库、文档仓库、skill 仓库 | 项目学习报告、结构图、2-3 个核心设计概览 | 不做深度模式提取，不做互动教学 |
|
||||
| `essence` | 这个项目最值得偷走的设计是什么？ | 明确设计目标，或需要自动找 standout design | 设计模式卡、证据链、迁移示例 | 不做全项目概览，不做普通代码讲解 |
|
||||
| `follow` | 如何基于已有报告一步步学会？ | 已有 `/explore` 或 `/essence` 报告 | Runnable 或 Reader 跟学会话 | 不重新扫描项目，不替用户执行代码 |
|
||||
|
||||
## 推荐学习链路
|
||||
|
||||
```text
|
||||
第一次接触项目
|
||||
↓
|
||||
/explore
|
||||
产出项目定位、结构、主流程、核心设计候选
|
||||
↓
|
||||
/essence
|
||||
选择一个核心设计做深挖，提炼可迁移模式
|
||||
↓
|
||||
/follow
|
||||
基于 explore/essence 报告做交互式学习
|
||||
```
|
||||
|
||||
也可以单独使用：
|
||||
|
||||
- 只想快速建立全局认知：只用 `explore`。
|
||||
- 已经知道要研究哪个设计：直接用 `essence` 的 User-directed 模式。
|
||||
- 已经有报告，想按教程学：直接用 `follow`。
|
||||
|
||||
## Explore 最新设计
|
||||
|
||||
### 定位
|
||||
|
||||
`explore` 是项目地图绘制器。它回答：
|
||||
|
||||
- 这个项目是什么？
|
||||
- 为什么值得研究？
|
||||
- 顶层结构如何组织？
|
||||
- 学习入口在哪里？
|
||||
- 有哪 2-3 个核心设计值得后续深挖？
|
||||
|
||||
### 当前阶段
|
||||
|
||||
v0.5.0 将原来的 5 Phase 收敛为 4 Phase：
|
||||
|
||||
1. **Positioning & Structure**
|
||||
- 合并早期 Positioning 和 Structure。
|
||||
- 输出项目定位、学习价值、顶层结构、入口区域。
|
||||
2. **Flow**
|
||||
- 仅代码仓库执行。
|
||||
- 追踪主运行流或请求流，聚焦 golden path。
|
||||
3. **Start Path**
|
||||
- 仅代码仓库且可运行/可观察时执行。
|
||||
- 给出最小启动路径、第一条命令或第一处观察点。
|
||||
4. **Core Designs**
|
||||
- 总结 2-3 个核心设计或核心想法。
|
||||
- 保持概览深度，为 `essence` 提供候选对象。
|
||||
|
||||
### 类型分流
|
||||
|
||||
`explore` 必须先识别项目类型：
|
||||
|
||||
- **Code repository**：执行完整 4 Phase。
|
||||
- **Skill / docs / knowledge repository**：跳过 Flow 和 Start Path，改用结构图、概念图或 workflow 图。
|
||||
- **Template / scaffold repository**：Flow 和 Start Path 可以保持轻量。
|
||||
|
||||
### 关键约束
|
||||
|
||||
- 不做 `/essence` 级别深挖。
|
||||
- 不做 `/follow` 式互动教学。
|
||||
- 不保留 Verify、Deep Fission、HTML Output 等已退休阶段。
|
||||
- 最终必须至少包含一个图：代码仓库用架构/流程图，非代码仓库用结构/想法/workflow 图。
|
||||
|
||||
## Essence 最新设计
|
||||
|
||||
### 定位
|
||||
|
||||
`essence` 是“宝石检查器”。它不是 `/explore` 的轻量版，而是专门回答：
|
||||
|
||||
> 这个项目里哪 1-2 个设计最值得迁移到我自己的工程里？
|
||||
|
||||
### 模式
|
||||
|
||||
| Mode | 触发场景 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| User-directed | 用户已有目标，或来自 `/explore` 的核心设计候选 | 直接深挖用户指定设计 |
|
||||
| Auto-detect | 独立启动，用户希望 AI 自动找亮点 | 扫 README、docs、结构和信号，提出 1-2 个候选 |
|
||||
| Lens-guided | 用户指定 mechanical / intentional / evolution 视角 | 按透镜选择证据来源和输出框架 |
|
||||
|
||||
### 透镜
|
||||
|
||||
- **Mechanical**：它如何工作？读代码、接口、调用链。
|
||||
- **Intentional**：为什么这样设计？读设计文档、RFC、PR、权衡。
|
||||
- **Evolution**：它如何演化到这里？读 changelog、git 历史、迁移记录。
|
||||
|
||||
### 当前阶段
|
||||
|
||||
1. **Locate**
|
||||
- 找到 1-2 个候选设计方向。
|
||||
- 自动模式要求 standout design 至少满足 2 个信号。
|
||||
2. **Deep Dive**
|
||||
- 最多读 10 个核心文件。
|
||||
- 追踪调用链或证据链，避免扩散成全项目分析。
|
||||
3. **Extract Pattern**
|
||||
- 提炼问题、模式、替代方案、权衡和证据。
|
||||
4. **Migrate**
|
||||
- 给出可迁移方式和最小示例。
|
||||
- 示例必须足够小，避免复制生产代码。
|
||||
5. **Self-review**
|
||||
- 检查是否有证据、是否解释了权衡、是否能迁移。
|
||||
|
||||
### 关键约束
|
||||
|
||||
- “代码干净”不是 essence 信号。
|
||||
- 如果没有 standout design，应明确建议改用 `explore`。
|
||||
- 如果设计边界超过 10 个文件且无法收敛，应改用 `explore`。
|
||||
- HTML Card 只是显式请求时的可选输出，不是默认阶段。
|
||||
|
||||
## Follow 最新设计
|
||||
|
||||
### 定位
|
||||
|
||||
`follow` 是跟学教练。它不做新分析，只基于已有 `/explore` 或 `/essence` 报告，带用户一步步学习。
|
||||
|
||||
### 前置条件
|
||||
|
||||
必须存在以下之一：
|
||||
|
||||
- `/explore` 报告
|
||||
- `/essence` 报告
|
||||
|
||||
如果没有，必须拒绝并引导用户先运行 `explore` 或 `essence`。
|
||||
|
||||
### 模式
|
||||
|
||||
| Mode | 来源 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| Runnable | `/explore` 报告确认是可运行代码仓库 | 从环境、启动、观察和安全修改开始 |
|
||||
| Reader | 非代码仓库，或来自 `/essence`，或用户专注设计学习 | 围绕核心设计做分层阅读和推理练习 |
|
||||
|
||||
### 当前流程
|
||||
|
||||
**Runnable**：
|
||||
|
||||
1. 确认环境和依赖。
|
||||
2. 让用户运行项目。
|
||||
3. 让用户做一个安全小改动。
|
||||
4. 一起走主流程。
|
||||
5. 给一个小练习。
|
||||
6. 回顾学习结果。
|
||||
|
||||
**Reader**：
|
||||
|
||||
1. 围绕设计或架构想法设定学习目标。
|
||||
2. 按“问题 → 方法 → 实现 → 权衡”讲解。
|
||||
3. 通过问题检查理解。
|
||||
4. 用图或结构总结连接文件和设计。
|
||||
5. 给一个迁移/推理练习。
|
||||
6. 回顾学习结果。
|
||||
|
||||
### 关键约束
|
||||
|
||||
- 不重新扫描项目。
|
||||
- 不执行命令或替用户写代码。
|
||||
- 不新增第三种模式。
|
||||
- 不只说“去读这个文件”，必须说明这个文件体现什么设计、为什么重要、看什么。
|
||||
|
||||
## v0.5.0 最重要的收敛
|
||||
|
||||
### 1. Explore 从 5 Phase 收敛到 4 Phase
|
||||
|
||||
早期 Positioning 和 Structure 拆开导致报告啰嗦。v0.5.0 合并为 `Positioning & Structure`，让 `explore` 更像项目地图，而不是流水账。
|
||||
|
||||
### 2. Essence 补齐上下文感知
|
||||
|
||||
`essence` 会先判断是否已有 `/explore` 结果：
|
||||
|
||||
- 有结果：默认 User-directed，让用户从候选设计中选择。
|
||||
- 无结果：默认 Auto-detect，自行寻找 standout design。
|
||||
|
||||
这避免了 `essence` 在已有上下文时重复扫描。
|
||||
|
||||
### 3. Follow 不再重扫
|
||||
|
||||
`follow` 的核心价值是“基于报告教学”。如果它重新扫描项目，就会变成另一个 explore。v0.5.0 明确它必须读取前置报告，按报告决定 Runnable 或 Reader。
|
||||
|
||||
### 4. Reader 模式从文件级提升到设计级
|
||||
|
||||
早期 Reader 容易变成“带你读一个文件”。v0.5.0 改成围绕设计概念学习：问题、方法、实现、权衡。
|
||||
|
||||
### 5. 删除过期阶段和死引用
|
||||
|
||||
已退休内容包括：
|
||||
|
||||
- Deep Fission
|
||||
- Verify 阶段
|
||||
- 默认 HTML Output
|
||||
- 旧 `/map`、`/fission` 等已不存在技能引用
|
||||
|
||||
## 当前产物边界
|
||||
|
||||
```text
|
||||
skill-workbench/
|
||||
├── generated-skills/
|
||||
│ └── skills/
|
||||
│ ├── explore/
|
||||
│ ├── essence/
|
||||
│ └── follow/
|
||||
├── docs/
|
||||
│ └── explore-essence-follow/
|
||||
│ └── latest-design.md
|
||||
└── history/
|
||||
├── changelog/
|
||||
└── docs/superpowers/
|
||||
```
|
||||
|
||||
- `generated-skills/skills/` 只放可安装 skill 本体。
|
||||
- `docs/explore-essence-follow/latest-design.md` 保存最新设计总结。
|
||||
- `history/` 保留旧设计、changelog、handoff 和过时 specs，作为考古来源。
|
||||
|
||||
## 何时修改哪一层
|
||||
|
||||
| 变更类型 | 修改位置 |
|
||||
| --- | --- |
|
||||
| skill 行为变更 | `skill-workbench/generated-skills/skills/{skill}/SKILL.md` |
|
||||
| 最新设计说明变更 | `skill-workbench/docs/explore-essence-follow/latest-design.md` |
|
||||
| 历史记录 | `skill-workbench/history/`，不要覆盖 |
|
||||
| 验证材料 | `skill-workbench/validation/` |
|
||||
|
||||
## 当前结论
|
||||
|
||||
这组三技能已经形成清晰分工：
|
||||
|
||||
- `explore` 是入口：建立项目级地图。
|
||||
- `essence` 是深挖：提炼可迁移设计。
|
||||
- `follow` 是教学：基于报告引导用户学会。
|
||||
|
||||
后续改进应避免把三者重新合并。最重要的维护原则是：**保持边界比增加功能更重要。**
|
||||
@@ -0,0 +1,383 @@
|
||||
# 增强版工作流总结
|
||||
|
||||
## 旧工作流 vs 新工作流
|
||||
|
||||
```
|
||||
旧： 新：
|
||||
Phase 1 手动整理PRD Phase 0 手动初始PRD（入口，保留人的判断）
|
||||
Phase 2 openspec:explore Phase 1 openspec:propose → research
|
||||
Phase 3 grill-me Phase 1.5 to-prd → 结构化PRD（替代初始PRD）
|
||||
Phase 4 openspec:apply Phase 2 grill-with-docs → CONTEXT.md + ADR
|
||||
Phase 2.5 zoom-out → 架构审计
|
||||
Phase 3 openspec:apply → 执行
|
||||
diagnose → bug排查
|
||||
tdd → 质量闭环
|
||||
横切： 横切：
|
||||
无 git-guardrails → 安全锁
|
||||
```
|
||||
|
||||
关键变化：**手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"**——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。
|
||||
|
||||
## 旧工作流的三个关键缺口
|
||||
|
||||
1. **需求澄清后缺少可行性验证**
|
||||
- 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现
|
||||
- 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行"
|
||||
|
||||
2. **openspec 产出不能沉淀到长期记忆**
|
||||
- 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢
|
||||
- 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文
|
||||
|
||||
3. **apply 完成后缺少验证闭环**
|
||||
- 旧：apply → 完成。功能对不对取决于人肉测试
|
||||
- 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor）
|
||||
|
||||
## 新增技能的投入产出
|
||||
|
||||
| 技能 | 学多久 | 一次省多少 | 什么时候用 |
|
||||
|------|--------|-----------|-----------|
|
||||
| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
|
||||
| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
|
||||
| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
|
||||
| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
|
||||
| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
|
||||
| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
|
||||
|
||||
## 为什么这套组合优于单纯依赖 openspec
|
||||
|
||||
openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题：
|
||||
|
||||
- **领域知识沉淀**：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐
|
||||
- **质量验证**：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环
|
||||
- **流程安全**：openspec 不管 AI 误操作 → git-guardrails 补齐安全层
|
||||
|
||||
一句话：**openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。**
|
||||
|
||||
## v2.0：devflow/ 产物聚合层
|
||||
|
||||
### 问题
|
||||
|
||||
v1.0 一次完整流程的产物散落在 **5 个位置**：
|
||||
|
||||
```
|
||||
CONTEXT.md ← Phase 2 (根目录)
|
||||
docs/adr/ ← Phase 2 (docs/)
|
||||
docs/agents/ ← Phase 1.5 (docs/)
|
||||
openspec/changes/ ← Phase 1+3 (openspec/)
|
||||
knowledge/entries/ ← /knowledge-absorber
|
||||
```
|
||||
|
||||
三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按**工具来源**组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按**项目本身**组织。
|
||||
|
||||
### 借鉴 CodeStable 的单一聚合根设计
|
||||
|
||||
CodeStable 的核心设计决策：所有产物集中在 `codestable/` 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。
|
||||
|
||||
dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个**人类可读的档案层**：
|
||||
|
||||
```
|
||||
devflow/ ← 单一入口
|
||||
├── projects/YYYY-MM-DD-{slug}/ ← 一个 PRD→实现 闭环
|
||||
│ ├── {slug}-prd.md # Phase 0+1.5 需求文档
|
||||
│ ├── {slug}-research.md # Phase 1 技术方案（从 openspec 提取）
|
||||
│ ├── {slug}-design.md # Phase 1+2.5 设计 + 架构审计
|
||||
│ ├── {slug}-tasks.md # Phase 1 任务清单（从 openspec 提取）
|
||||
│ ├── {slug}-acceptance.md # Phase 3+4 验收报告
|
||||
│ └── adr/ # Phase 2 架构决策
|
||||
├── glossary/
|
||||
│ └── CONTEXT.md # 跨项目领域词汇表
|
||||
├── compound/ # 跨项目知识沉淀
|
||||
│ └── YYYY-MM-DD-{type}-{slug}.md # type ∈ {learning, trick, decision, explore}
|
||||
└── reference/ # 共享模板/规范
|
||||
```
|
||||
|
||||
### 两层架构
|
||||
|
||||
| | openspec/changes/ | devflow/projects/ |
|
||||
|------|-----------|-------------------|
|
||||
| 角色 | 工具工作区（WAL） | 人类档案层（Tables） |
|
||||
| 谁读 | 机器 | 人 |
|
||||
| 生命周期 | 活跃变更期 → Archive 后清空 | 永久保留 |
|
||||
| 组织方式 | 按变更名 | 按日期 + 项目 |
|
||||
|
||||
**关键**：openspec archive 后 `openspec/changes/` 清空，但 `devflow/projects/` 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。
|
||||
|
||||
### 各 Phase 产物路径变化
|
||||
|
||||
| Phase | v1.0 | v2.0 |
|
||||
|-------|------|------|
|
||||
| 1.5 PRD | `docs/agents/<name>-prd.md` | `devflow/projects/{date}-{slug}/{slug}-prd.md` |
|
||||
| 2 CONTEXT | 根目录 `CONTEXT.md` | `devflow/glossary/CONTEXT.md` |
|
||||
| 2 ADR | `docs/adr/` | `devflow/projects/{slug}/adr/` |
|
||||
| 2.5 架构审计 | 对话中，丢失 | `devflow/projects/{slug}/{slug}-design.md` |
|
||||
| 4 验收 | `docs/agents/lessons/` | `devflow/projects/{slug}/{slug}-acceptance.md` |
|
||||
| 4 经验沉淀 | 无 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||||
| 4 从 openspec 提取 | 无 | 提炼到 `{slug}-research.md` + `{slug}-tasks.md` |
|
||||
|
||||
## 一键启动
|
||||
|
||||
已固化为 skill：**`/dev-flow`**
|
||||
|
||||
```
|
||||
/dev-flow # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程
|
||||
/dev-flow --prd docs/my-idea.md # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1
|
||||
/dev-flow --from phase2 # 已有 research，从 grill 开始
|
||||
/dev-flow --from apply # 已有 PRD + 文档，直接执行
|
||||
/dev-flow --quick # 小需求，跳 PRD 精化 + zoom-out
|
||||
```
|
||||
|
||||
Skill 位置：`.claude/skills/dev-flow/SKILL.md`
|
||||
|
||||
## Skill 评估结论（2026-05-19）
|
||||
|
||||
详细评估报告见：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`。
|
||||
|
||||
### 总体判断
|
||||
|
||||
`dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。
|
||||
|
||||
最有价值的设计是 `devflow/` 产物聚合层：
|
||||
|
||||
- `openspec/changes/` 负责机器可执行的变更工作区。
|
||||
- `devflow/projects/` 负责人类可回溯的项目档案。
|
||||
- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。
|
||||
- `devflow/compound/` 负责沉淀可复用工程知识。
|
||||
|
||||
评估中发现的核心问题是：早期 `SKILL.md` 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。
|
||||
|
||||
### 已确认的亮点
|
||||
|
||||
1. **产物聚合层设计清晰**
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。
|
||||
- 工具工作区和人类档案层分离，职责边界明确。
|
||||
|
||||
2. **阶段顺序合理**
|
||||
- Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。
|
||||
|
||||
3. **Phase 4 很有价值**
|
||||
- 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
|
||||
- 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。
|
||||
|
||||
4. **文档化追问方向正确**
|
||||
- Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。
|
||||
- 这符合“边澄清边沉淀”的工作方式。
|
||||
|
||||
5. **质量闭环意识强**
|
||||
- Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
|
||||
- TDD 被设计为可选增强，避免对所有任务强制套用重流程。
|
||||
|
||||
### 主要改进点
|
||||
|
||||
| 问题 | 改进方向 |
|
||||
| --- | --- |
|
||||
| 触发描述不够完整 | 明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景 |
|
||||
| Claude 工具耦合较强 | 保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback |
|
||||
| 依赖安装状态写死 | 改为启动时检查 required / optional / fallback |
|
||||
| 子 skill 调用方式不稳 | 优先调用子 skill；不可调用时读取对应 `SKILL.md`；不存在时执行最小协议 |
|
||||
| 缺少初始化算法 | 明确 `devflow/` 目录骨架、slug 生成、重名处理和旧 `CONTEXT.md` 迁移规则 |
|
||||
| 缺少模板 | 拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板 |
|
||||
| quick 模式与约束冲突 | quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档 |
|
||||
| Phase 退出条件不足 | 为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径 |
|
||||
|
||||
### 产品化方向
|
||||
|
||||
评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”：
|
||||
|
||||
- `SKILL.md` 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。
|
||||
- `references/` 承载长内容：Phase 契约、模板、归档规则、fallback 协议。
|
||||
- 每个 Phase 都要有明确的进入条件和退出条件。
|
||||
- quick 模式、fallback、归档确认、人类检查点必须写成硬规则。
|
||||
- `devflow/` 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。
|
||||
|
||||
### 后续演进：sm-flow 产品化
|
||||
|
||||
基于这次评估，`dev-flow` 的设计被重构为 `.agents/skills/sm-flow/`。这一步仍属于 **v2 产品化**：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。
|
||||
|
||||
```
|
||||
.agents/skills/sm-flow/
|
||||
├── SKILL.md # 短执行协议
|
||||
└── references/
|
||||
├── phase-contracts.md # Phase 输入/动作/输出/退出条件
|
||||
├── templates.md # PRD/ADR/验收等模板
|
||||
├── archive-rules.md # 从 openspec 提取到 devflow 的规则
|
||||
└── fallbacks.md # 子 skill 不可用时的最小协议
|
||||
```
|
||||
|
||||
v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 `devflow/` 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。
|
||||
|
||||
## v3.0：OpenSpec-first / Devflow-assisted
|
||||
|
||||
### 背景
|
||||
|
||||
v2 跑通后暴露出一个更深的问题：`devflow/` 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。
|
||||
|
||||
这会导致两套“执行依据”并存：
|
||||
|
||||
```
|
||||
devflow/projects/{slug}/... # 人类档案层，也包含 PRD/design/tasks
|
||||
openspec/changes/{change}/... # 工具工作区，也包含 proposal/design/specs/tasks
|
||||
```
|
||||
|
||||
如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。
|
||||
|
||||
### v3 的核心判断
|
||||
|
||||
v3 不重新设计一套替代 openspec 的工作流，而是明确：
|
||||
|
||||
> **devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。**
|
||||
|
||||
职责分层变为：
|
||||
|
||||
| 层 | 角色 | 负责回答 |
|
||||
| --- | --- | --- |
|
||||
| `devflow/` | 上下文真理源 / 长期记忆 | 为什么这样做？术语是什么？历史决策是什么？之前怎么验收？ |
|
||||
| `openspec/changes/` | 执行真理源 / 当前变更规格 | 这次到底改什么？验收标准是什么？任务是否完成？ |
|
||||
| code | 实现结果 | OpenSpec apply 后实际落地的代码 |
|
||||
|
||||
### v2 vs v3
|
||||
|
||||
| 维度 | v2：devflow 聚合层 | v3：OpenSpec-first / Devflow-assisted |
|
||||
| --- | --- | --- |
|
||||
| 核心目标 | 防止 openspec archive 后上下文丢失 | 防止 devflow 与 openspec 成为并列执行源 |
|
||||
| devflow 角色 | 人类可读档案层 | 上下文增强层 + 归档层 |
|
||||
| openspec 角色 | 工具工作区 | 当前变更的唯一默认执行真理源 |
|
||||
| Phase 1 | openspec propose 产出 research | 基于 devflow 上下文生成/修正 OpenSpec 产物 |
|
||||
| Phase 2 | grill-with-docs 更新 glossary/ADR | human-in-the-loop 澄清后必须回写 OpenSpec |
|
||||
| Phase 2.5 | zoom-out 产出架构审计 | 架构审计若影响实现，必须回写 OpenSpec design/tasks |
|
||||
| Phase 3 | openspec apply + diagnose/tdd | 默认只能依赖 OpenSpec apply；devflow 只作参考上下文 |
|
||||
| Phase 4 | 从 openspec 提炼到 devflow | 轻量回填 devflow 必要档案，避免重复 OpenSpec |
|
||||
|
||||
### v3.1：Devflow 产物瘦身
|
||||
|
||||
v3 继续跑完整流程后，又暴露出一个实践问题：`devflow` 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。
|
||||
|
||||
因此 v3.1 明确：**devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。**
|
||||
|
||||
默认必要产物收敛为：
|
||||
|
||||
```text
|
||||
devflow/projects/YYYY-MM-DD-{slug}/
|
||||
├── brief.md # 背景、目标、范围、非目标、关联 OpenSpec
|
||||
├── evidence.md # 代码/文档证据、evidence-driven 结论和汇报状态
|
||||
├── decisions.md # user-interview 确认、关键取舍、OpenSpec 回写记录
|
||||
└── acceptance.md # 实现结果、验证、未验证项、archive 状态
|
||||
```
|
||||
|
||||
扩展产物只在有明确理由时创建：
|
||||
|
||||
- `prd.md`：复杂需求、对外协作或用户明确要求。
|
||||
- `research.md`：真实调研、代码考古、竞品/API 对比或复杂方案比较。
|
||||
- `design.md`：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。
|
||||
- `tasks.md`：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
|
||||
- `alignment.md` / `clarifications.md`：冲突或澄清问题很多时拆出；否则并入 `decisions.md`。
|
||||
|
||||
规模分档：
|
||||
|
||||
| 分档 | 适用场景 | devflow 默认产物 |
|
||||
| --- | --- | --- |
|
||||
| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md` |
|
||||
| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` |
|
||||
| `complex` | 高风险、跨模块、需求不清、多人协作 | standard + 按需 PRD/research/design/tasks/alignment |
|
||||
|
||||
### v3 新增 Phase 0.5
|
||||
|
||||
v3 在 Phase 0 和 Phase 1 之间增加：
|
||||
|
||||
```
|
||||
Phase 0.5 Devflow Context Harvest
|
||||
```
|
||||
|
||||
读取：
|
||||
|
||||
- `devflow/glossary/CONTEXT.md`
|
||||
- 相关项目 PRD/design/tasks/acceptance
|
||||
- 相关 ADR
|
||||
- `devflow/compound/` 中的 learning、trick、decision、explore
|
||||
|
||||
目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。
|
||||
|
||||
|
||||
### v3 中各 skill 的参与方式
|
||||
|
||||
这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”：
|
||||
|
||||
| 阶段 | 主要 skill / 工具 | 作用 | 产物去向 |
|
||||
| --- | --- | --- | --- |
|
||||
| Phase 0 初始需求 / PRD / research | `sm-flow` | 收集原始需求、已有 PRD 或 research，判断启动模式 | 入口摘要、初步 slug |
|
||||
| Phase 0.5 Devflow Context Harvest | `sm-flow` | 读取 `devflow/` 的 glossary、ADR、历史 PRD、acceptance、compound knowledge | 作为 Phase 1 的 OpenSpec 输入上下文 |
|
||||
| Phase 1 OpenSpec propose | `openspec-propose` | 生成或修正 `proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md` | `openspec/changes/<change>/` |
|
||||
| Phase 1.5 PRD / OpenSpec 对齐 | `to-prd` + `sm-flow` | 检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD | `brief.md` / 按需 `prd.md`；冲突回写 OpenSpec |
|
||||
| Phase 2 Human-in-the-loop 澄清 | `grill-with-docs` | 追问术语、边界、验收；区分 `evidence-driven` 和 `user-interview` | `evidence.md` / `decisions.md`；影响实现的结论回写 OpenSpec |
|
||||
| Phase 2.5 架构审计 | `zoom-out` | 拉高视角审查模块、数据流、耦合、架构风险 | 默认写入 decisions/evidence；复杂审计才拆 `design.md`；影响实现则回写 OpenSpec |
|
||||
| Phase 3 OpenSpec apply | `openspec-apply-change` | 按 OpenSpec specs/tasks 执行实现 | 代码变更、OpenSpec task 状态 |
|
||||
| Phase 3 bug/不确定行为 | `diagnose` | 复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归 | 根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance |
|
||||
| Phase 3 高风险/复杂行为 | `tdd` | 按 OpenSpec specs 做纵向切片测试驱动 | 测试与实现代码 |
|
||||
| Phase 4 回填 devflow | `sm-flow` + `openspec-archive-change` | 从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive | `devflow/projects/`、`devflow/compound/`；用户确认后 archive |
|
||||
|
||||
说明：`grill-me` 在 v3 中不再作为主要入口，已被 `grill-with-docs` 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。
|
||||
|
||||
### v3 的执行规则
|
||||
|
||||
1. **OpenSpec 是执行真理源**
|
||||
- Phase 3 默认必须依赖 `openspec/changes/<change>/proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md`。
|
||||
- 不允许直接基于 `devflow/projects/...` 绕过 OpenSpec 写代码。
|
||||
|
||||
2. **Devflow 是上下文真理源**
|
||||
- 术语、历史决策、项目背景、踩坑记录来自 `devflow/`。
|
||||
- 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。
|
||||
|
||||
3. **冲突先修 OpenSpec**
|
||||
- 如果 devflow 和 OpenSpec 冲突，不能直接执行。
|
||||
- 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。
|
||||
|
||||
4. **evidence-driven 也必须汇报**
|
||||
- 证据驱动不是“AI 自己确认完就继续”。
|
||||
- 代理必须汇报查了什么、得出什么结论、是否需要用户确认。
|
||||
|
||||
5. **user-interview 必须等待确认**
|
||||
- 涉及范围、偏好、验收口径、风险接受度时，必须问用户。
|
||||
|
||||
6. **归档仍回到 devflow**
|
||||
- OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。
|
||||
- Phase 4 询问是否 archive OpenSpec change，不默认执行。
|
||||
|
||||
7. **devflow 产物按需生成**
|
||||
- 默认只生成 brief、evidence、decisions、acceptance。
|
||||
- PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。
|
||||
- 小需求走 `micro`，不能让文档成本超过实现成本。
|
||||
|
||||
### v3 流程图
|
||||
|
||||
```
|
||||
Phase 0 初始需求 / PRD / research
|
||||
skill: sm-flow
|
||||
↓
|
||||
Phase 0.5 读取 devflow 上下文
|
||||
skill: sm-flow
|
||||
↓
|
||||
Phase 1 生成或修正 OpenSpec proposal/design/specs/tasks
|
||||
skill: openspec-propose
|
||||
↓
|
||||
Phase 1.5 PRD / Devflow / OpenSpec 对齐检查
|
||||
skill: to-prd + sm-flow
|
||||
↓
|
||||
Phase 2 human-in-the-loop 澄清，并回写 OpenSpec
|
||||
skill: grill-with-docs
|
||||
↓
|
||||
Phase 2.5 架构审计；影响实现则回写 OpenSpec
|
||||
skill: zoom-out
|
||||
↓
|
||||
Phase 3 OpenSpec apply 执行
|
||||
skill: openspec-apply-change；按需 diagnose / tdd
|
||||
↓
|
||||
Phase 4 回填 devflow，并确认是否 archive
|
||||
skill: sm-flow；用户确认后 openspec-archive-change
|
||||
```
|
||||
|
||||
### v3 一句话定位
|
||||
|
||||
`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,259 @@
|
||||
---
|
||||
name: essence
|
||||
description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Essence: Extract Core Design Patterns
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
|
||||
|
||||
**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
First, check whether an `/explore` result exists:
|
||||
|
||||
- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
|
||||
- No `/explore` result → this is an independent launch, default to **Auto-detect**.
|
||||
|
||||
Always confirm before proceeding:
|
||||
|
||||
| Mode | When | Entry |
|
||||
|---|---|---|
|
||||
| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
|
||||
| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
|
||||
| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
|
||||
|
||||
### Lens definitions
|
||||
|
||||
| Lens | Core question | Guided behavior |
|
||||
|---|---|---|
|
||||
| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
|
||||
| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
|
||||
| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
|
||||
|
||||
A lens shapes which sources to read and how to frame the output, but does not add separate phases.
|
||||
|
||||
### Auto-detect signals
|
||||
|
||||
A design is "essence" if it passes 2 or more of these signals:
|
||||
|
||||
| Signal | Evidence |
|
||||
|---|---|
|
||||
| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
|
||||
| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
|
||||
| Heavily discussed in Issues/PRs | Design decisions debated by community |
|
||||
| Unique among similar projects | Competitors don't do it this way |
|
||||
| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
|
||||
| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
|
||||
| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
|
||||
| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
|
||||
|
||||
**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
|
||||
|
||||
If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
|
||||
|
||||
## Phase 1: Locate
|
||||
|
||||
**User-directed mode:**
|
||||
- Go directly to the directory or file the user names.
|
||||
- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
|
||||
|
||||
**Auto-detect mode:**
|
||||
- Scan README, CLAUDE.md, and top-level docs for architecture claims.
|
||||
- Identify 1-2 standout design directions.
|
||||
- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
|
||||
- If user doesn't choose, pick the strongest one and state why.
|
||||
|
||||
**Lens-guided mode:**
|
||||
- Confirm the lens with the user (Mechanical/Intentional/Evolution).
|
||||
- Frame the search in terms of the lens.
|
||||
- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
|
||||
|
||||
**Output:** 1-2 design directions to analyze + lens confirmation.
|
||||
|
||||
**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
|
||||
|
||||
## Phase 2: Deep Dive
|
||||
|
||||
Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
|
||||
|
||||
**For each file:**
|
||||
- What role does it play in this design?
|
||||
- What interfaces does it expose?
|
||||
- How does it connect to other parts of the system?
|
||||
|
||||
**Trace the call chain:**
|
||||
- Start from the entry point that uses this design.
|
||||
- Follow the flow until you understand the full pattern.
|
||||
- Stop when you hit boilerplate, config, or test files.
|
||||
|
||||
**Output:** Core file list (≤10) + call chain + lens-specific annotations.
|
||||
|
||||
**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
|
||||
|
||||
## Phase 3: Extract Pattern
|
||||
|
||||
Analyze the design at a higher level. Let the lens shape the analysis angle:
|
||||
- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
|
||||
- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
|
||||
- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
|
||||
|
||||
**Universal analysis dimensions** (all lenses):
|
||||
|
||||
- **Problem:** What specific problem does this design solve? What was the pain before?
|
||||
- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
|
||||
- **Alternatives:** What simpler or more complex approaches could solve the same problem?
|
||||
- **Tradeoffs:** Why did the author choose this? What does it give up?
|
||||
- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
|
||||
|
||||
**Output:** Design pattern card (lens-framed).
|
||||
|
||||
**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
|
||||
|
||||
## Phase 4: Migrate
|
||||
|
||||
Make the learning actionable. Let the lens tailor the output:
|
||||
- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
|
||||
- **Intentional** → decision framework (checklist for evaluating tradeoffs)
|
||||
- **Evolution** → migration path (step-by-step refactor plan)
|
||||
|
||||
**Universal deliverables** (all lenses):
|
||||
|
||||
- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
|
||||
- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
|
||||
- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
|
||||
|
||||
**Output:** Migration example + pitfall list (lens-tailored).
|
||||
|
||||
**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
|
||||
|
||||
## Phase 5: Self-review
|
||||
|
||||
Check the report is honest:
|
||||
|
||||
**All modes:**
|
||||
- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
|
||||
- [ ] The analysis is deep enough that you could explain it out loud.
|
||||
- [ ] The migration example captures the core idea, not surface syntax.
|
||||
- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
|
||||
|
||||
**Stall signals (any one → return to relevant phase):**
|
||||
- Cannot name a file that proves the pattern → back to Phase 2
|
||||
- Cannot explain why it's better than alternatives → back to Phase 3
|
||||
- Migration example is over 20 lines → simplify, back to Phase 4
|
||||
- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
|
||||
|
||||
**Output:** Essence report with lens annotation.
|
||||
|
||||
## Optional: HTML Card
|
||||
|
||||
**Only when the user explicitly requests it.**
|
||||
|
||||
Generate an HTML visualization card as a shareable deliverable.
|
||||
|
||||
### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>{Project Name} - Essence Report</title>
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
/* Same glassmorphism styles as /explore */
|
||||
:root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
|
||||
[data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
|
||||
.glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
|
||||
.pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
|
||||
</style>
|
||||
</head>
|
||||
<body class="p-8">
|
||||
<nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
|
||||
<span class="font-bold text-xl">💎 {Project Name} 精华</span>
|
||||
<span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
|
||||
</nav>
|
||||
|
||||
<main class="max-w-4xl mx-auto mt-24 space-y-6">
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
|
||||
<p>{one-line description}</p>
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
|
||||
<!-- Lens-framed pattern card -->
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
|
||||
<pre class="mermaid">{diagram}</pre>
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
|
||||
<pre class="pattern-diagram"><code>{code_example}</code></pre>
|
||||
<p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
|
||||
</section>
|
||||
</main>
|
||||
|
||||
<script>mermaid.initialize({ startOnLoad: true });</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
```markdown
|
||||
### HTML Card Generated
|
||||
|
||||
- **Path:** `outputs/{project}-essence.html`
|
||||
- **Theme:** {modern/ink}
|
||||
- **Accent Color:** Purple (essence = jewel)
|
||||
```
|
||||
|
||||
**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
|
||||
- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
|
||||
- **Stop after the report.** Do not modify the user's project or the target project.
|
||||
- **HTML is optional.** Do not block analysis on HTML generation.
|
||||
|
||||
## Gotchas
|
||||
|
||||
| What happened | Rule |
|
||||
|---|---|
|
||||
| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
|
||||
| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
|
||||
| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
|
||||
| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
|
||||
| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
|
||||
| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
|
||||
| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
|
||||
| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
|
||||
| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Essence Report: {project name}
|
||||
Lens: mechanical / intentional / evolution
|
||||
Design analyzed: {one-line description}
|
||||
Files examined: {count}
|
||||
Pattern: {pattern name or custom description}
|
||||
Migration: {steal-it example, ≤20 lines}
|
||||
HTML generated: yes / no
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the report, stop. No modifications. No follow-ups.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Essence Detection Signals
|
||||
|
||||
How to identify the standout design in a project when the user doesn't specify a direction.
|
||||
|
||||
## Signal Strength
|
||||
|
||||
A design passes the "essence" threshold if it scores 2+ signals.
|
||||
|
||||
### Strong Signals (score = 1 each)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
|
||||
| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
|
||||
| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
|
||||
| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
|
||||
| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
|
||||
|
||||
### Objective Signals (score = 1 each, no subjective judgment needed)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
|
||||
| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
|
||||
| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
|
||||
|
||||
### Weak Signals (score = 0.5 each)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
|
||||
| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
|
||||
| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
|
||||
| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
|
||||
|
||||
## Not Signals
|
||||
|
||||
These do NOT count as essence:
|
||||
|
||||
- "Clean code" or "well organized" — that's quality, not design
|
||||
- "Uses TypeScript" — that's a language choice, not architecture
|
||||
- "Has good tests" — that's engineering discipline, not design
|
||||
- "Many stars on the repo" — popularity ≠ design quality
|
||||
- "Uses the latest framework" — following trends ≠ standing out
|
||||
- Utility functions — even well-written ones are tools, not designs
|
||||
|
||||
## Auto-detect Procedure
|
||||
|
||||
When the user says "find the essence":
|
||||
|
||||
1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
|
||||
2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
|
||||
3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
|
||||
4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
|
||||
5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
|
||||
6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
|
||||
|
||||
### Example Output Format
|
||||
|
||||
```
|
||||
Standout designs in {project}:
|
||||
|
||||
A) {Design A name} — evidenced by {README claim / file / doc}
|
||||
What it does: {one sentence}
|
||||
|
||||
B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
|
||||
What it does: {one sentence}
|
||||
|
||||
Which should we dive into? (or I can pick the strongest)
|
||||
```
|
||||
|
||||
## Failure Modes
|
||||
|
||||
| Situation | Response |
|
||||
|---|---|
|
||||
| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
|
||||
| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
|
||||
| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
|
||||
| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: explore
|
||||
description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Explore: Project Understanding and Onboarding
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start.
|
||||
|
||||
`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching.
|
||||
|
||||
## Project Type Detection
|
||||
|
||||
After the initial scan, classify the target before continuing:
|
||||
|
||||
| Type | Signals | What changes |
|
||||
|---|---|---|
|
||||
| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases |
|
||||
| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) |
|
||||
| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal |
|
||||
|
||||
State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type.
|
||||
|
||||
## Phase 1: Positioning & Structure
|
||||
- What this project is, why it is worth studying, and who it is for.
|
||||
- Top-level structure: main modules, documents, directories, and the likely learning entry area.
|
||||
- Tradeoffs vs alternatives when evidence exists.
|
||||
|
||||
## Phase 2: Flow
|
||||
**Code repositories only.**
|
||||
- Skip for non-code and template repositories.
|
||||
- Trace the main runtime or request flow.
|
||||
- Produce at least one architecture or core-flow diagram.
|
||||
- Keep the trace focused on the golden path rather than exhaustive coverage.
|
||||
|
||||
## Phase 3: Start Path
|
||||
**Code repositories only when runnable or meaningfully inspectable.**
|
||||
- Provide the minimal path to start learning or running the project.
|
||||
- Give the first command or first inspection step.
|
||||
- Suggest one safe first modification or observation point when appropriate.
|
||||
|
||||
## Phase 4: Core Designs
|
||||
- Summarize 2-3 core implementations or ideas.
|
||||
- Keep this at overview depth.
|
||||
- For each item, include what it is, where it lives, and why it matters.
|
||||
|
||||
## Minimum Deliverables
|
||||
|
||||
The final `/explore` report must include:
|
||||
- Project positioning
|
||||
- Why it is worth studying
|
||||
- 2-3 core implementations or core ideas
|
||||
- Tradeoffs or comparisons when applicable
|
||||
- At least 1 diagram:
|
||||
- code repository → architecture diagram or core flow diagram
|
||||
- non-code repository → structure diagram, idea map, or workflow diagram
|
||||
|
||||
## Boundary Rules
|
||||
|
||||
`/explore` may:
|
||||
- scan structure
|
||||
- explain the main flow
|
||||
- provide a minimal start path
|
||||
- summarize 2-3 core designs
|
||||
|
||||
`/explore` must not:
|
||||
- perform `/essence`-level deep extraction
|
||||
- act as `/follow`-style guided teaching
|
||||
- include Verify, Deep Fission, or HTML Output phases
|
||||
- preserve no retired lightweight fallback behavior
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Explore Report: {project name}
|
||||
Project type: code / skill-docs / template
|
||||
Phases completed: 4/4 (or note skipped code-only phases)
|
||||
Diagram included: yes / no
|
||||
Core designs: 2-3
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the report, stop. Do not proceed to `/essence` or `/follow` automatically.
|
||||
@@ -0,0 +1,98 @@
|
||||
# Project Analysis Methods
|
||||
|
||||
How to read and understand an unfamiliar code project.
|
||||
|
||||
## 1. Identify the Entry Point
|
||||
|
||||
Every project has a door. Find it first.
|
||||
|
||||
### By Language
|
||||
|
||||
| Language | Look for |
|
||||
|---|---|
|
||||
| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
|
||||
| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
|
||||
| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
|
||||
| **Rust** | `src/main.rs` or `src/bin/*.rs` |
|
||||
| **Java** | Class with `public static void main(String[] args)` |
|
||||
| **C/C++** | `main()` function, conventionally in `src/main.c` |
|
||||
| **Swift** | `main.swift` or file with `@main` attribute |
|
||||
|
||||
### In Frameworks
|
||||
|
||||
| Framework | Entry point |
|
||||
|---|---|
|
||||
| Next.js | `app/` or `pages/` directory, `next.config.js` |
|
||||
| React (Vite) | `src/main.tsx` or `src/main.jsx` |
|
||||
| Vue (Vite) | `src/main.ts` or `src/main.js` |
|
||||
| Express | File that calls `app.listen()` |
|
||||
| FastAPI | File that creates `FastAPI()` instance |
|
||||
| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
|
||||
| Flask | `app.py` or `app/__init__.py` |
|
||||
| Spring Boot | `*Application.java` with `@SpringBootApplication` |
|
||||
|
||||
## 2. Judge Project Complexity
|
||||
|
||||
Don't over-engineer simple projects. Don't under-analyze complex ones.
|
||||
|
||||
### Simple (<50 files, single language)
|
||||
- Read every source file.
|
||||
- No need for flow diagrams beyond a simple sequence.
|
||||
- A light `/explore` pass is probably enough.
|
||||
|
||||
### Standard (50-500 files, 1-2 languages)
|
||||
- Read entry point + core modules + 1-2 feature files.
|
||||
- Build 1-2 flow diagrams.
|
||||
- `/explore` is the right level.
|
||||
|
||||
### Complex (>500 files, multi-language, monorepo)
|
||||
- Read entry point + architecture docs + one representative module.
|
||||
- Use `/essence` to find standout designs, or `/explore` for one package at a time.
|
||||
- Do NOT try to understand the whole project in one pass.
|
||||
|
||||
## 3. Separate Core Code from Scaffolding
|
||||
|
||||
Not all files are worth reading.
|
||||
|
||||
### Ignore (scaffolding)
|
||||
- `*.config.js`, `*.config.ts` — configuration, not logic
|
||||
- `dist/`, `build/`, `out/` — generated output
|
||||
- `node_modules/`, `vendor/`, `.venv/` — dependencies
|
||||
- `*.lock`, `yarn.lock`, `go.sum` — lock files
|
||||
- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
|
||||
- `test/fixtures/`, `test/data/` — test data
|
||||
|
||||
### Read (core)
|
||||
- Entry point file
|
||||
- Router/middleware/config handlers
|
||||
- Model/entity/schema definitions
|
||||
- Core algorithm or business logic files
|
||||
- Files referenced most in imports
|
||||
|
||||
### Hint: Follow imports
|
||||
|
||||
```
|
||||
entry file → import A → import B → core logic
|
||||
```
|
||||
|
||||
Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
|
||||
|
||||
## 4. Read Unfamiliar Framework Code
|
||||
|
||||
You don't know every framework. That's fine.
|
||||
|
||||
### Strategy
|
||||
|
||||
1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
|
||||
|
||||
2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
|
||||
|
||||
3. **Identify the framework's conventions.** Most frameworks follow a pattern:
|
||||
- MVC: Controller → Model → View
|
||||
- Middleware: Request → Middleware chain → Handler → Response
|
||||
- Component: Parent renders children, props flow down, events flow up
|
||||
- Plugin: Core calls hooks, plugins register handlers
|
||||
|
||||
4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
|
||||
|
||||
5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.
|
||||
@@ -0,0 +1,173 @@
|
||||
# Flow Pattern Library
|
||||
|
||||
Common architecture patterns and how to identify them in code.
|
||||
|
||||
## MVC / MVVM / MVX
|
||||
|
||||
### What it is
|
||||
Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel).
|
||||
|
||||
### File signatures
|
||||
| Pattern | Directories/Files |
|
||||
|---|---|
|
||||
| **MVC** | `controllers/`, `models/`, `views/` |
|
||||
| **MVVM** | `viewmodels/`, `views/`, `models/` |
|
||||
| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Request → Controller → Model (data) → View (render) → Response
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does the file handle data, display, or coordination?" If yes → MVC-family.
|
||||
|
||||
---
|
||||
|
||||
## Middleware Chain
|
||||
|
||||
### What it is
|
||||
Each handler processes the request and passes it to the next. Like an assembly line.
|
||||
|
||||
### File signatures
|
||||
| Framework | Indicator |
|
||||
|---|---|---|
|
||||
| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` |
|
||||
| **FastAPI** | `@app.middleware("http")`, `Depends()` |
|
||||
| **Next.js** | `middleware.ts` at root or in `app/` |
|
||||
| **Gin (Go)** | `router.Use(middleware1, middleware2)` |
|
||||
| **Koa** | `app.use(async (ctx, next) => { ... })` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Request → Middleware A → Middleware B → Handler → Response
|
||||
↓ ↓
|
||||
auth check log request
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does this function call `next()` or pass control to something else?" If yes → middleware.
|
||||
|
||||
### Common middleware order
|
||||
```
|
||||
1. CORS / Security headers
|
||||
2. Logging / Request ID
|
||||
3. Authentication / Authorization
|
||||
4. Body parsing / Validation
|
||||
5. Rate limiting
|
||||
6. Route handler
|
||||
7. Error handler (catches everything above)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin / Extension System
|
||||
|
||||
### What it is
|
||||
Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` |
|
||||
| **Interface-based** | Abstract class or interface that plugins implement |
|
||||
| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention |
|
||||
| **VSCode-style** | `contributes` in `package.json`, activation events |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Core starts
|
||||
↓
|
||||
Scans for plugins
|
||||
↓
|
||||
Each plugin registers itself
|
||||
↓
|
||||
Core fires hooks → plugins respond
|
||||
↓
|
||||
Core runs with extended capabilities
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Can I add functionality without modifying core code?" If yes → plugin architecture.
|
||||
|
||||
---
|
||||
|
||||
## Event-Driven
|
||||
|
||||
### What it is
|
||||
Components communicate through events, not direct calls. Publishers emit, subscribers listen.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` |
|
||||
| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` |
|
||||
| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` |
|
||||
| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` |
|
||||
| **Signals (Python)** | `@signal.connect`, `signal.send()` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Component A emits "user.created"
|
||||
↓
|
||||
Listener B hears it → sends welcome email
|
||||
Listener C hears it → creates default settings
|
||||
Listener D hears it → logs analytics
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does code communicate without importing or calling each other directly?" If yes → event-driven.
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
### What it is
|
||||
Centralized storage for application state. Components read and update through defined interfaces.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` |
|
||||
| **Zustand** | `create((set) => ({ ... }))` |
|
||||
| **Jotai** | `atom(value)`, `useAtom(atom)` |
|
||||
| **MobX** | `@observable`, `@action`, `@computed` |
|
||||
| **React Context** | `createContext()`, `useContext()`, `Provider` |
|
||||
| **Pinia (Vue)** | `defineStore()`, `state`, `actions` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Component dispatches action
|
||||
↓
|
||||
Reducer processes action + current state
|
||||
↓
|
||||
New state emitted
|
||||
↓
|
||||
Subscribed components re-render
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Where does the app store data that multiple components need?" If it's a single store → state management pattern.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline / Chain of Responsibility
|
||||
|
||||
### What it is
|
||||
Data flows through a series of processors. Each processor transforms the data and passes it on.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Stream processing** | `.pipe(transform1).pipe(transform2)` |
|
||||
| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate |
|
||||
| **Data pipeline** | `input → transform → validate → output` |
|
||||
| **Makefile** | Target depends on prerequisites, each is a step |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Raw input → Tokenizer → Parser → Transformer → Generator → Output
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline.
|
||||
@@ -0,0 +1,120 @@
|
||||
#!/usr/bin/env bash
|
||||
# Collect project structure for /explore analysis.
|
||||
# Usage: Run from project root, or pass project path as argument.
|
||||
# Output: Structured text with directory tree, file counts, language distribution.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
PROJECT_DIR="${1:-.}"
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
echo "=== PROJECT STRUCTURE ==="
|
||||
echo ""
|
||||
|
||||
# Directory tree (depth 3, exclude common noise)
|
||||
echo "--- Directory Tree (depth 3) ---"
|
||||
if command -v tree &>/dev/null; then
|
||||
tree -L 3 \
|
||||
-I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \
|
||||
--dirsfirst
|
||||
elif command -v find &>/dev/null; then
|
||||
find . -maxdepth 3 \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
-not -path "*/__pycache__/*" \
|
||||
-not -path "*/.egg-info/*" \
|
||||
-not -path "*/coverage/*" \
|
||||
-not -path "./.nyc_output/*" \
|
||||
-print | head -100 | sort
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== FILE COUNTS ==="
|
||||
echo ""
|
||||
|
||||
# Count files by extension (top 10)
|
||||
echo "--- Top 10 File Types ---"
|
||||
find . -type f \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
-not -path "*/__pycache__/*" \
|
||||
-printf '%f\n' | \
|
||||
sed 's/.*\.//' | \
|
||||
grep -v '^\.[^/]*$' | \
|
||||
sort | uniq -c | sort -rn | head -10
|
||||
|
||||
echo ""
|
||||
echo "=== TOTAL FILE COUNT ==="
|
||||
echo ""
|
||||
|
||||
# Total files (excluding noise)
|
||||
total=$(find . -type f \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
| wc -l)
|
||||
echo "Total source files: $total"
|
||||
|
||||
echo ""
|
||||
echo "=== DEPENDENCY FILES ==="
|
||||
echo ""
|
||||
|
||||
# List dependency declaration files found
|
||||
for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do
|
||||
if [ -f "$dep_file" ]; then
|
||||
echo "FOUND: $dep_file"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check for workspace/monorepo configs
|
||||
echo ""
|
||||
echo "=== WORKSPACE / MONOREPO ==="
|
||||
echo ""
|
||||
|
||||
for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do
|
||||
if [ -f "$ws_file" ]; then
|
||||
echo "FOUND: $ws_file"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check Cargo.toml for workspace
|
||||
if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then
|
||||
echo "FOUND: Cargo.toml [workspace]"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== ENTRY POINTS ==="
|
||||
echo ""
|
||||
|
||||
# Try to identify entry points
|
||||
if [ -f "package.json" ]; then
|
||||
main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "")
|
||||
bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "")
|
||||
dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "")
|
||||
[ -n "$main" ] && echo "package.json main: $main"
|
||||
[ -n "$bin" ] && echo "package.json bin: $bin"
|
||||
[ -n "$dev" ] && echo "package.json dev/start: $dev"
|
||||
fi
|
||||
|
||||
for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do
|
||||
if [ -f "$entry" ]; then
|
||||
echo "FOUND: $entry"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== COLLECTED ==="
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: follow
|
||||
description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Follow: Guided Learning Session
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it.
|
||||
|
||||
`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result.
|
||||
|
||||
## Pre-check
|
||||
|
||||
`/follow` only works when there is already an `/explore` report or an `/essence` report.
|
||||
|
||||
- `/explore` report exists → use it as the main learning path
|
||||
- `/essence` report exists → use it for design-focused guided study
|
||||
- Neither exists → refuse clearly
|
||||
|
||||
Refusal behavior:
|
||||
"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first."
|
||||
|
||||
Load the existing report before continuing.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
After the pre-check, select one mode based on the prerequisite report:
|
||||
|
||||
- From `/explore` + code repository → default **Runnable**
|
||||
- From `/explore` + non-code repository → force **Reader**
|
||||
- From `/essence` → default **Reader** (user is in design-analysis state)
|
||||
|
||||
| Mode | When | Entry |
|
||||
|---|---|---|
|
||||
| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution |
|
||||
| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading |
|
||||
|
||||
State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide.
|
||||
|
||||
## Teaching Interaction Rules
|
||||
|
||||
`/follow` must teach by guidance, not by dumping answers:
|
||||
- explain the purpose of the current step first
|
||||
- give the user an observation point or action point
|
||||
- ask the user to predict, try, or explain before revealing the answer
|
||||
- then reveal, correct, or deepen the explanation
|
||||
- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to
|
||||
|
||||
## Runnable Check
|
||||
|
||||
Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project):
|
||||
- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable.
|
||||
- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why.
|
||||
- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists.
|
||||
- Do not introduce a third mode.
|
||||
|
||||
## Runnable Mode Flow
|
||||
1. Confirm environment and prerequisites.
|
||||
2. Let the user run the project.
|
||||
3. Let the user make one safe change.
|
||||
4. Walk the main flow together.
|
||||
5. Give one small exercise.
|
||||
6. Review what they learned.
|
||||
|
||||
## Reader Mode Flow
|
||||
1. Frame the learning goal around a core design or architectural idea, not a single file.
|
||||
2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff.
|
||||
3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?").
|
||||
4. Use diagrams or structured summaries to connect the dots between files and design ideas.
|
||||
5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere.
|
||||
6. Review what they learned.
|
||||
|
||||
## Boundary Rules
|
||||
|
||||
`/follow` must:
|
||||
- depend on `/explore` or `/essence`
|
||||
- guide the user interactively
|
||||
- adapt between code and non-code repositories through Runnable or Reader emphasis
|
||||
|
||||
`/follow` must not:
|
||||
- rescan the whole project as a new analyzer
|
||||
- reference retired skills as prerequisites
|
||||
- add any third learning mode
|
||||
- execute commands or write code for the user
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Follow Session: {project name}
|
||||
Mode: runnable / reader
|
||||
Prerequisite report: /explore or /essence
|
||||
Exercise result: completed / partial / too hard
|
||||
Next direction: {suggested follow-up}
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the review, stop. Ask whether the user wants another exercise or wants to end the session.
|
||||
@@ -0,0 +1,113 @@
|
||||
# Environment Detection Rules
|
||||
|
||||
How to detect the runtime environment and guide the user through setup in `/follow`.
|
||||
|
||||
## Language Detection from Config
|
||||
|
||||
Check these files in order. The first match is the primary language.
|
||||
|
||||
| Config file | Language | Runtime check | Install command |
|
||||
|---|---|---|---|
|
||||
| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer |
|
||||
| `pyproject.toml` | Python | `python --version` | pyenv or python.org |
|
||||
| `go.mod` | Go | `go version` | golang.org/dl |
|
||||
| `Cargo.toml` | Rust | `rustc --version` | rustup |
|
||||
| `pom.xml` | Java | `java -version` | SDKMAN or official |
|
||||
| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN |
|
||||
| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv |
|
||||
| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK |
|
||||
| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager |
|
||||
| `swift package.json` | Swift | `swift --version` | Xcode or swift.org |
|
||||
|
||||
## Dependency Installation
|
||||
|
||||
Once language is detected, guide the user:
|
||||
|
||||
### JavaScript/TypeScript
|
||||
```bash
|
||||
# Check which package manager is used
|
||||
if [ -f "yarn.lock" ]; then yarn install
|
||||
elif [ -f "pnpm-lock.yaml" ]; then pnpm install
|
||||
elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install
|
||||
else npm install
|
||||
fi
|
||||
```
|
||||
|
||||
### Python
|
||||
```bash
|
||||
# Modern Python projects
|
||||
pip install -e .
|
||||
# Or with requirements
|
||||
pip install -r requirements.txt
|
||||
# Or with poetry
|
||||
poetry install
|
||||
# Or with uv
|
||||
uv pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Go
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
### Rust
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
### Java (Maven)
|
||||
```bash
|
||||
mvn install
|
||||
```
|
||||
|
||||
### Java (Gradle)
|
||||
```bash
|
||||
./gradlew build
|
||||
# or
|
||||
gradle build
|
||||
```
|
||||
|
||||
## Run Command Detection
|
||||
|
||||
How to start the project:
|
||||
|
||||
| Source | Command |
|
||||
|---|---|
|
||||
| `package.json` → `scripts.dev` | `npm run dev` |
|
||||
| `package.json` → `scripts.start` | `npm start` |
|
||||
| `Makefile` → `dev` target | `make dev` |
|
||||
| `Makefile` → `run` target | `make run` |
|
||||
| `pyproject.toml` (Poetry) | `poetry run python main.py` |
|
||||
| `go.mod` → `package main` | `go run main.go` |
|
||||
| `Cargo.toml` → `[[bin]]` | `cargo run` |
|
||||
| `docker-compose.yml` exists | `docker-compose up` |
|
||||
| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` |
|
||||
|
||||
## Common Environment Issues
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|---|---|---|
|
||||
| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) |
|
||||
| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` |
|
||||
| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo |
|
||||
| `ENOENT: no such file` | Wrong working directory | `cd` to project root first |
|
||||
| `port already in use` | Another process on same port | Kill the process or use different port |
|
||||
| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` |
|
||||
| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` |
|
||||
| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement |
|
||||
| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` |
|
||||
|
||||
## Detection Script for /follow
|
||||
|
||||
```bash
|
||||
# Quick environment check
|
||||
echo "=== Environment ==="
|
||||
node --version 2>/dev/null || echo "Node.js: not installed"
|
||||
python --version 2>/dev/null || echo "Python: not installed"
|
||||
go version 2>/dev/null || echo "Go: not installed"
|
||||
rustc --version 2>/dev/null || echo "Rust: not installed"
|
||||
java -version 2>/dev/null || echo "Java: not installed"
|
||||
echo "PWD: $(pwd)"
|
||||
```
|
||||
|
||||
Run this at the start of `/follow` Step 1 to understand what's available.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
name: sm-flow
|
||||
description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
|
||||
---
|
||||
|
||||
# SM Flow
|
||||
|
||||
SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。
|
||||
|
||||
## 真理源分层
|
||||
|
||||
- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
|
||||
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
|
||||
- 代码是实现结果：只能在执行真理源足够明确后修改。
|
||||
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
|
||||
|
||||
## 核心规则
|
||||
|
||||
- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。
|
||||
- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
|
||||
- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
|
||||
- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
|
||||
- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
|
||||
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
|
||||
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
|
||||
- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
|
||||
- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
|
||||
- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
|
||||
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
|
||||
|
||||
## 首次加载
|
||||
|
||||
执行前只读取当前任务需要的 reference 文件：
|
||||
|
||||
- 需要逐阶段执行时，读取 `references/phase-contracts.md`。
|
||||
- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
|
||||
- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
|
||||
- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
|
||||
|
||||
## 启动检查
|
||||
|
||||
1. 判断启动模式：
|
||||
- 完整模式：用户提供粗略想法或初始 PRD。
|
||||
- Research 模式：用户已有 research，需要转成或修正 OpenSpec。
|
||||
- PRD 文件模式：用户提供已有 PRD 路径。
|
||||
- 指定阶段模式：用户要求从某个 Phase 恢复。
|
||||
- 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
|
||||
2. 如果缺少 `devflow/`，初始化：
|
||||
- `devflow/projects/`
|
||||
- `devflow/glossary/CONTEXT.md`
|
||||
- `devflow/compound/`
|
||||
- `devflow/reference/`
|
||||
3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
|
||||
4. 检查 OpenSpec 和子 skill 是否可用：
|
||||
- OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
|
||||
- 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
|
||||
5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
|
||||
|
||||
## 项目标识
|
||||
|
||||
整个流程使用同一个 slug：
|
||||
|
||||
- 优先使用 OpenSpec change name。
|
||||
- 如果还没有 change name，则从功能标题生成 kebab-case slug。
|
||||
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
|
||||
- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
|
||||
|
||||
## Devflow 产物分层
|
||||
|
||||
devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
|
||||
|
||||
**必须产物**：
|
||||
|
||||
- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
|
||||
- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
|
||||
- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
|
||||
- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
|
||||
|
||||
**按需产物**：
|
||||
|
||||
- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
|
||||
- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
|
||||
- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
|
||||
- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
|
||||
- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
|
||||
- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
|
||||
|
||||
**规模分档**：
|
||||
|
||||
- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。
|
||||
- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
|
||||
- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。
|
||||
|
||||
## 阶段总览
|
||||
|
||||
1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
|
||||
2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
|
||||
4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
|
||||
5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
|
||||
6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
|
||||
7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
|
||||
8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
|
||||
|
||||
每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
|
||||
|
||||
## 快速模式
|
||||
|
||||
快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
|
||||
|
||||
- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
|
||||
- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
|
||||
- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
|
||||
- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
|
||||
|
||||
## 完成标准
|
||||
|
||||
一次流程只有在满足以下条件时才算完成：
|
||||
|
||||
- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
|
||||
- 实现或规划任务已经完成，且执行依据来自 OpenSpec。
|
||||
- 已运行验证，或明确记录未运行验证的原因。
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
|
||||
- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
# 归档规则
|
||||
|
||||
Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
|
||||
|
||||
## 目录规则
|
||||
|
||||
项目档案路径：
|
||||
|
||||
```text
|
||||
devflow/projects/YYYY-MM-DD-{slug}/
|
||||
```
|
||||
|
||||
默认创建以下必要文件：
|
||||
|
||||
- `brief.md`
|
||||
- `evidence.md`
|
||||
- `decisions.md`
|
||||
- `acceptance.md`
|
||||
|
||||
按需创建以下扩展文件：
|
||||
|
||||
- `prd.md`
|
||||
- `research.md`
|
||||
- `design.md`
|
||||
- `tasks.md`
|
||||
- `alignment.md`
|
||||
- `adr/*.md`
|
||||
|
||||
不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。
|
||||
|
||||
## 产物分档
|
||||
|
||||
| 分档 | 适用场景 | 必须文件 | 扩展文件 |
|
||||
| --- | --- | --- | --- |
|
||||
| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` |
|
||||
| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound |
|
||||
| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` |
|
||||
|
||||
## 提取映射
|
||||
|
||||
| 来源 | 提取内容 | 写入位置 |
|
||||
| --- | --- | --- |
|
||||
| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
|
||||
| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
|
||||
| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
|
||||
| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
|
||||
| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
|
||||
| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
|
||||
| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
|
||||
| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
|
||||
| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||||
|
||||
## 验收记录规则
|
||||
|
||||
必须真实记录验证情况，并按类型分类：
|
||||
|
||||
- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。
|
||||
- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。
|
||||
- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。
|
||||
- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。
|
||||
|
||||
记录要求：
|
||||
|
||||
- 如果验证通过，记录命令/步骤和覆盖范围。
|
||||
- 如果验证失败，记录失败摘要和是否阻塞验收。
|
||||
- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
|
||||
|
||||
## ADR 规则
|
||||
|
||||
同时满足以下条件时创建 ADR：
|
||||
|
||||
1. 决策难以逆转。
|
||||
2. 缺少上下文会让未来维护者困惑。
|
||||
3. 决策来自真实权衡，而不是简单偏好。
|
||||
|
||||
项目内 ADR 存放于：
|
||||
|
||||
```text
|
||||
devflow/projects/YYYY-MM-DD-{slug}/adr/
|
||||
```
|
||||
|
||||
跨项目可复用决策或经验存放于：
|
||||
|
||||
```text
|
||||
devflow/compound/YYYY-MM-DD-decision-{slug}.md
|
||||
```
|
||||
|
||||
## 归档确认
|
||||
|
||||
OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
|
||||
|
||||
- Phase 4 可以建议 archive，但必须先询问用户。
|
||||
- 在用户确认前，不要执行 archive。
|
||||
- 如果用户暂不归档，在 acceptance 中记录原因或状态。
|
||||
- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
|
||||
|
||||
## 归档交接
|
||||
|
||||
Phase 4 结束时告诉用户：
|
||||
|
||||
- 创建或更新了哪些档案文件。
|
||||
- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
|
||||
- 还剩哪些风险或后续事项。
|
||||
- 明确询问：是否现在 archive OpenSpec change？
|
||||
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# Fallback 协议
|
||||
|
||||
当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
|
||||
|
||||
## OpenSpec 提案 fallback
|
||||
|
||||
1. 创建或识别 `openspec/changes/{slug}/`。
|
||||
2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
|
||||
3. 写入 `proposal.md`，包含：
|
||||
- 问题
|
||||
- 建议方案
|
||||
- 范围
|
||||
- 非目标
|
||||
- 来自 devflow 的上下文约束
|
||||
- 风险
|
||||
4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
|
||||
5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
|
||||
6. 只为外部可见行为或发生变化的需求编写 specs。
|
||||
7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
|
||||
|
||||
## OpenSpec 修正 fallback
|
||||
|
||||
当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
|
||||
|
||||
1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
|
||||
2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
|
||||
3. 向用户汇报冲突和推荐修正。
|
||||
4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
|
||||
5. 再同步更新 devflow 文档；不要只改 devflow。
|
||||
|
||||
## OpenSpec 执行 fallback
|
||||
|
||||
仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
|
||||
|
||||
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
|
||||
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
|
||||
3. 修改前先检查现有代码。
|
||||
4. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
5. 用最窄但有效的命令验证每个切片。
|
||||
6. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
7. 如果失败原因不确定，停止并进入 diagnose。
|
||||
8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
|
||||
## PRD fallback
|
||||
|
||||
优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
|
||||
|
||||
规则：
|
||||
|
||||
- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
|
||||
- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
|
||||
- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
|
||||
|
||||
## 文档化追问 fallback
|
||||
|
||||
1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
|
||||
2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
|
||||
3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
|
||||
4. 对 user-interview 问题，一次只问一个并等待用户确认。
|
||||
5. 术语确认后立即更新词汇表。
|
||||
6. 影响实现的澄清必须回写 OpenSpec。
|
||||
7. 只为难以逆转的真实权衡创建 ADR。
|
||||
|
||||
快速模式的最小问题：
|
||||
|
||||
- 术语：这个概念应该使用哪个领域术语？证据是什么？
|
||||
- 边界：哪些内容明确不在范围内？是否需要用户确认？
|
||||
- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
|
||||
|
||||
## 架构审计 fallback
|
||||
|
||||
产出一份短架构审计：
|
||||
|
||||
1. 画出输入 → 处理 → 输出。
|
||||
2. 列出相关模块和调用方。
|
||||
3. 识别耦合、数据所有权和生命周期风险。
|
||||
4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
|
||||
5. 用不超过五句话总结最大风险。
|
||||
6. 如果影响实现，回写 OpenSpec design/tasks。
|
||||
|
||||
## Diagnose fallback
|
||||
|
||||
1. 复现问题，或捕获准确失败信息。
|
||||
2. 最小化失败案例。
|
||||
3. 生成 3-5 个假设，并按可能性和验证成本排序。
|
||||
4. 修改代码前，先添加仪器化或定向检查。
|
||||
5. 判断根因属于实现问题还是 OpenSpec 规格问题。
|
||||
6. 如果是实现问题，修复被证明的最小原因。
|
||||
7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
|
||||
8. 运行回归验证。
|
||||
|
||||
## TDD fallback
|
||||
|
||||
使用纵向切片，不要水平批量写测试：
|
||||
|
||||
1. 从 OpenSpec specs 中选择一个外部可见行为。
|
||||
2. 写一个失败测试。
|
||||
3. 实现刚好让测试通过的最小代码。
|
||||
4. 只在测试通过时重构。
|
||||
5. 对下一个 OpenSpec 行为重复以上步骤。
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
# 阶段契约
|
||||
|
||||
本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
|
||||
|
||||
## Phase 0 — 入口澄清
|
||||
|
||||
**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
|
||||
|
||||
**动作**：
|
||||
- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。
|
||||
- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
|
||||
- 如果输入过于模糊，最多追加三轮聚焦问题。
|
||||
- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
|
||||
|
||||
**退出条件**：
|
||||
- 问题可以用 1-2 句话说清楚。
|
||||
- 期望结果可以用 1-2 句话说清楚。
|
||||
- 已列出已知影响代码或模块；如果未知，也明确标记。
|
||||
- 可以生成 OpenSpec change slug。
|
||||
|
||||
**输出**：
|
||||
- 入口摘要。
|
||||
- 初步 slug。
|
||||
- devflow 规模分档：`micro` / `standard` / `complex`。
|
||||
|
||||
## Phase 0.5 — Devflow 上下文收集
|
||||
|
||||
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
|
||||
|
||||
**动作**：
|
||||
- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
|
||||
- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
|
||||
- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
|
||||
- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
|
||||
- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。
|
||||
|
||||
**退出条件**：
|
||||
- 已形成“OpenSpec 输入上下文摘要”。
|
||||
- 已列出相关 ADR 和不能违反的历史决策。
|
||||
- 已列出需要写入或修正 OpenSpec 的上下文点。
|
||||
|
||||
**输出**：
|
||||
- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。
|
||||
|
||||
## Phase 1 — OpenSpec propose
|
||||
|
||||
**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
|
||||
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-propose`。
|
||||
- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。
|
||||
- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
|
||||
- proposal 写清为什么做、做什么、范围和非目标。
|
||||
- design 写入上下文约束、历史 ADR、关键技术决策。
|
||||
- specs 写成可验收的外部行为。
|
||||
- tasks 写成可执行的纵向切片。
|
||||
- 在承诺设计细节前，先检查相关仓库代码。
|
||||
|
||||
**退出条件**：
|
||||
- `openspec/changes/<slug>/proposal.md` 存在。
|
||||
- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
|
||||
- 关键假设已显式记录在 OpenSpec 或 research 中。
|
||||
|
||||
**输出**：
|
||||
- OpenSpec proposal、design、specs 和 task list。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
|
||||
- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 1.5 — PRD / OpenSpec 对齐
|
||||
|
||||
**进入条件**：Phase 1 已有 OpenSpec 产物。
|
||||
|
||||
**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。
|
||||
|
||||
**动作**：
|
||||
- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
|
||||
- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
|
||||
- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
|
||||
- OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
|
||||
- OpenSpec 是否使用 glossary 中的正确术语。
|
||||
- OpenSpec 是否遵守相关 ADR。
|
||||
- specs 是否能表达可观察行为。
|
||||
- tasks 是否能驱动实现，而不是泛泛描述。
|
||||
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
|
||||
|
||||
**退出条件**：
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
- `brief.md`，以及按需创建的 `prd.md`。
|
||||
- OpenSpec 对齐检查记录。
|
||||
- 必要的 OpenSpec 修正。
|
||||
|
||||
## Phase 2 — Human-in-the-loop 澄清
|
||||
|
||||
**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
|
||||
|
||||
**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
|
||||
|
||||
**动作**：
|
||||
- 优先使用 `grill-with-docs`。
|
||||
- 先声明本阶段采用的澄清模式，并逐项标记：
|
||||
- `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
|
||||
- 至少覆盖三个维度：术语、边界、验收。
|
||||
- 一次只问一个 `user-interview` 问题。
|
||||
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
|
||||
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
|
||||
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
|
||||
|
||||
**退出条件**：
|
||||
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
|
||||
- 所有 evidence-driven 结论已向用户汇报。
|
||||
- 所有 user-interview 决策已获得用户确认。
|
||||
- 影响实现的结论已回写 OpenSpec。
|
||||
|
||||
**输出**：
|
||||
- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
|
||||
- 更新后的 OpenSpec。
|
||||
- 更新后的词汇表和 ADR。
|
||||
|
||||
## Phase 2.5 — 架构审计
|
||||
|
||||
**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
|
||||
|
||||
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
|
||||
|
||||
**动作**：
|
||||
- 画出输入 → 处理 → 输出的模块链路。
|
||||
- 识别跨模块依赖、数据所有权、生命周期和耦合风险。
|
||||
- 检查是否与既有架构、ADR、OpenSpec design 冲突。
|
||||
- 用不超过五句话写出架构风险评估。
|
||||
- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
|
||||
|
||||
**退出条件**：
|
||||
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
|
||||
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
|
||||
|
||||
**输出**：
|
||||
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
|
||||
- 必要的 OpenSpec design/tasks 修正。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
|
||||
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
|
||||
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-apply-change`。
|
||||
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
|
||||
- 按 OpenSpec tasks 的纵向切片实现。
|
||||
- 当用户要求、行为复杂或回归风险高时使用 TDD。
|
||||
- 当测试失败、行为意外或原因不确定时使用 diagnose。
|
||||
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
|
||||
- 修改文件前遵守仓库指令，例如 `AGENTS.md`。
|
||||
|
||||
**退出条件**：
|
||||
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
|
||||
- 已运行验证，或记录了未验证原因。
|
||||
- 已列出已知限制。
|
||||
|
||||
**输出**：
|
||||
- 代码变更、必要测试和实现说明。
|
||||
- 更新后的 OpenSpec task 状态。
|
||||
|
||||
## Phase 4 — 回填 Devflow
|
||||
|
||||
**进入条件**：实现或规划工作已经达到可交接状态。
|
||||
|
||||
**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
|
||||
|
||||
**动作**：
|
||||
- 遵循 `references/archive-rules.md`。
|
||||
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
|
||||
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
|
||||
- 如果本次流程产生可复用经验，写入 compound knowledge。
|
||||
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
|
||||
|
||||
**退出条件**：
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
|
||||
- 用户已被询问是否 archive OpenSpec change。
|
||||
|
||||
**输出**：
|
||||
- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。
|
||||
|
||||
@@ -0,0 +1,290 @@
|
||||
# 模板
|
||||
|
||||
这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。
|
||||
|
||||
## Brief 模板
|
||||
|
||||
```markdown
|
||||
# {标题} Brief
|
||||
|
||||
## 背景
|
||||
|
||||
- 用户目标：{goal}
|
||||
- 当前问题：{problem}
|
||||
- 关联 OpenSpec：`openspec/changes/{slug}/`
|
||||
- devflow 分档：micro | standard | complex
|
||||
|
||||
## 范围
|
||||
|
||||
- 本次要做：{in scope}
|
||||
- 本次不做：{out of scope}
|
||||
- 影响区域：{modules/files if known}
|
||||
|
||||
## OpenSpec 对齐
|
||||
|
||||
- proposal 覆盖状态：已覆盖 / 待修正 / 不适用
|
||||
- specs 覆盖状态：已覆盖 / 待修正 / 不适用
|
||||
- tasks 覆盖状态：已覆盖 / 待修正 / 不适用
|
||||
```
|
||||
|
||||
## Evidence 模板
|
||||
|
||||
```markdown
|
||||
# {标题} Evidence
|
||||
|
||||
## 证据
|
||||
|
||||
| 来源 | 证据 | 结论 | 是否已汇报 |
|
||||
| --- | --- | --- | --- |
|
||||
| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 |
|
||||
|
||||
## Evidence-driven 结论
|
||||
|
||||
- 结论：{conclusion}
|
||||
- 证据：{evidence}
|
||||
- 风险：{risk if any}
|
||||
- 用户确认：需要 / 不需要 / 已确认
|
||||
```
|
||||
|
||||
## Decisions 模板
|
||||
|
||||
```markdown
|
||||
# {标题} Decisions
|
||||
|
||||
## User-interview
|
||||
|
||||
| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
|
||||
| --- | --- | --- | --- |
|
||||
| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 |
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- 决策：{decision}
|
||||
- 原因：{why}
|
||||
- 影响：{impact}
|
||||
- 风险接受：{accepted by whom/when}
|
||||
```
|
||||
|
||||
## PRD 模板
|
||||
|
||||
```markdown
|
||||
# {标题} PRD
|
||||
|
||||
## 问题陈述
|
||||
|
||||
用用户视角描述问题。
|
||||
|
||||
## 解决方案
|
||||
|
||||
用用户视角描述预期解决方案。
|
||||
|
||||
## 用户故事
|
||||
|
||||
1. 作为{角色}，我希望{能力}，以便{收益}。
|
||||
|
||||
## 实现决策
|
||||
|
||||
- 决策：{decision}
|
||||
- 原因：{why}
|
||||
- 影响：{affected modules or behavior}
|
||||
|
||||
## 测试决策
|
||||
|
||||
- 好测试应该通过{public interface}验证{observable behavior}。
|
||||
- 必须覆盖：{critical paths}
|
||||
- 不测试：{explicit exclusions}
|
||||
|
||||
## 非目标
|
||||
|
||||
- {excluded behavior}
|
||||
|
||||
## 补充说明
|
||||
|
||||
- {open question or useful context}
|
||||
```
|
||||
|
||||
## 词汇表模板
|
||||
|
||||
```markdown
|
||||
# 上下文词汇表
|
||||
|
||||
## 术语
|
||||
|
||||
### {术语}
|
||||
|
||||
- 定义：{precise definition}
|
||||
- 使用场景：{feature/module/context}
|
||||
- 备注：{ambiguities, synonyms, or rejected meanings}
|
||||
|
||||
## 业务规则
|
||||
|
||||
- {rule}: {meaning and source}
|
||||
```
|
||||
|
||||
## ADR 模板
|
||||
|
||||
```markdown
|
||||
# ADR-{编号}: {决策标题}
|
||||
|
||||
**状态**：提议中 | 已接受 | 已废弃
|
||||
**日期**：YYYY-MM-DD
|
||||
|
||||
## 背景
|
||||
|
||||
是什么情况迫使我们做这个决策？
|
||||
|
||||
## 决策
|
||||
|
||||
我们选择了什么？
|
||||
|
||||
## 替代方案
|
||||
|
||||
| 方案 | 拒绝原因 |
|
||||
| --- | --- |
|
||||
| {option} | {reason} |
|
||||
|
||||
## 后果
|
||||
|
||||
### 正面
|
||||
|
||||
- {benefit}
|
||||
|
||||
### 负面
|
||||
|
||||
- {cost or risk}
|
||||
```
|
||||
|
||||
## 技术调研模板
|
||||
|
||||
```markdown
|
||||
# {标题} 技术调研
|
||||
|
||||
## 摘要
|
||||
|
||||
- 变更原因：{reason}
|
||||
- 变更范围：{scope}
|
||||
- 主要技术方案：{approach}
|
||||
|
||||
## 源产物
|
||||
|
||||
- OpenSpec change: `openspec/changes/{slug}/`
|
||||
- 关联 PRD: `prd.md` 或 `brief.md`
|
||||
|
||||
## 关键发现
|
||||
|
||||
- {finding}
|
||||
|
||||
## 假设
|
||||
|
||||
- {assumption and validation status}
|
||||
```
|
||||
|
||||
## 设计模板
|
||||
|
||||
```markdown
|
||||
# {标题} 设计
|
||||
|
||||
## 架构摘要
|
||||
|
||||
描述输入 → 处理 → 输出。
|
||||
|
||||
## 关键决策
|
||||
|
||||
- {decision}: {reason}
|
||||
|
||||
## 模块地图
|
||||
|
||||
| 模块 | 职责 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| {module} | {responsibility} | {notes} |
|
||||
|
||||
## 架构审计
|
||||
|
||||
- 风险：{risk}
|
||||
- 缓解：{mitigation}
|
||||
```
|
||||
|
||||
## 任务模板
|
||||
|
||||
```markdown
|
||||
# {标题} 任务
|
||||
|
||||
## 需求追踪
|
||||
|
||||
| 需求 | 状态 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} |
|
||||
|
||||
## 实现任务
|
||||
|
||||
- [ ] {task}
|
||||
```
|
||||
|
||||
## 验收模板
|
||||
|
||||
```markdown
|
||||
# {标题} 验收
|
||||
|
||||
## 结果
|
||||
|
||||
已接受 / 部分接受 / 未接受。
|
||||
|
||||
## 验证
|
||||
|
||||
### 静态验证
|
||||
|
||||
- 命令/检查：`{command or check}`
|
||||
- 结果：{passed/failed/not run}
|
||||
- 备注：{important output or reason not run}
|
||||
|
||||
### 脚本验证
|
||||
|
||||
- 命令：`{command}`
|
||||
- 结果：{passed/failed/not run}
|
||||
- 备注：{important output or reason not run}
|
||||
|
||||
### 浏览器/人工验证
|
||||
|
||||
- 步骤：{manual steps}
|
||||
- 结果：{passed/failed/not run}
|
||||
- 备注：{observations or reason not run}
|
||||
|
||||
## 已完成范围
|
||||
|
||||
- {completed behavior}
|
||||
|
||||
## 已知限制
|
||||
|
||||
- {limitation}
|
||||
|
||||
## Bug 修复和诊断
|
||||
|
||||
- {bug}: {diagnosis summary and regression coverage}
|
||||
|
||||
## 交接
|
||||
|
||||
- 下一步：{archive, deploy, review, or follow-up}
|
||||
- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
|
||||
```
|
||||
|
||||
## 复合知识模板
|
||||
|
||||
```markdown
|
||||
# {标题}
|
||||
|
||||
**类型**：learning | trick | decision | explore
|
||||
**日期**：YYYY-MM-DD
|
||||
|
||||
## 背景
|
||||
|
||||
这条经验来自哪里？
|
||||
|
||||
## 经验
|
||||
|
||||
未来代理应该复用什么经验？
|
||||
|
||||
## 适用性
|
||||
|
||||
什么时候适用？什么时候不适用？
|
||||
```
|
||||
|
||||
@@ -0,0 +1,136 @@
|
||||
# Skills v0.5.0 整合修复记录
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致
|
||||
|
||||
---
|
||||
|
||||
## 一句话摘要
|
||||
|
||||
在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。
|
||||
|
||||
---
|
||||
|
||||
## 已完成的改动
|
||||
|
||||
### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏）
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| 版本号 | `0.3.0` → `0.5.0` |
|
||||
| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 |
|
||||
| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point |
|
||||
| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` |
|
||||
| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 |
|
||||
| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect |
|
||||
| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） |
|
||||
|
||||
### 2. `/follow` — 消除旧引用和设计偏差
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader |
|
||||
| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） |
|
||||
| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" |
|
||||
| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 |
|
||||
|
||||
### 3. `/explore` — 合并冗余阶段
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` |
|
||||
| 阶段总数 | 5 Phase → 4 Phase |
|
||||
| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 |
|
||||
| Outcome 模板 | `5/5` → `4/4` |
|
||||
|
||||
### 4. References 清理
|
||||
|
||||
| 文件 | 操作 |
|
||||
|---|---|
|
||||
| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 |
|
||||
| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 |
|
||||
|
||||
### 5. docs 存档清理
|
||||
|
||||
| 文件 | 操作 | 原因 |
|
||||
|---|---|---|
|
||||
| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 |
|
||||
| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 |
|
||||
| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 |
|
||||
| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 |
|
||||
|
||||
---
|
||||
|
||||
## docs 存档最终结构
|
||||
|
||||
```
|
||||
docs/superpowers/
|
||||
├── specs/
|
||||
│ ├── issue.md # 原始需求
|
||||
│ ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md
|
||||
│ └── 2026-04-21-skills-v0.5.0-changelog-design.md
|
||||
└── changelog/
|
||||
├── 2026-04-21-skills-v0.5.0-slim-architecture.md # 第一次改造 changelog
|
||||
├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令
|
||||
└── 2026-04-30-skills-v0.5.0-consolidation.md # 本次整合（本文件）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 当前 skill 状态
|
||||
|
||||
| 技能 | 版本 | Phase/Mode | 备注 |
|
||||
|---|---|---|---|
|
||||
| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure |
|
||||
| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection |
|
||||
| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 |
|
||||
|
||||
---
|
||||
|
||||
## 实践验证结果
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**测试目标仓库：**
|
||||
- 非代码仓库：explore-skill-family（自身）
|
||||
- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent）
|
||||
|
||||
| # | 验证路径 | 目标 | 结果 |
|
||||
|---|---|---|---|
|
||||
| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ |
|
||||
| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start |
|
||||
| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 |
|
||||
| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 |
|
||||
| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 |
|
||||
| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 |
|
||||
| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 |
|
||||
|
||||
### 验证发现的额外修复
|
||||
|
||||
验证过程中对 SKILL.md 的追加修改（已在代码中反映）：
|
||||
- `/essence` Phase 6 → Optional: HTML Card
|
||||
- `/essence` Mode Selection 上下文感知
|
||||
- `/essence` Most imported file → Cross-module contract
|
||||
- `/follow` Mode Selection 来源感知
|
||||
- `/follow` Runnable Check 不再重扫，引用前置报告
|
||||
- `/follow` Reader Mode Flow 提升到设计层
|
||||
- `/follow` Teaching Interaction Rules 收紧
|
||||
- `/explore` Phase 1+2 合并，5→4 Phase
|
||||
- `/explore` Project Type Detection 信号改为后端导向
|
||||
- 删除 `skills/explore/references/deep-fission.md`
|
||||
|
||||
### handoff 10 条检查清单逐项结论
|
||||
|
||||
| # | 问题 | 结论 |
|
||||
|---|---|---|
|
||||
| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 |
|
||||
| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 |
|
||||
| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 |
|
||||
| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 |
|
||||
| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 |
|
||||
| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 |
|
||||
| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 |
|
||||
| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 |
|
||||
| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 |
|
||||
| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 |
|
||||
|
||||
**总体验收结论：通过。** 文档、边界、行为三者一致。
|
||||
@@ -0,0 +1,39 @@
|
||||
# ADR-001: 目录名作为日期和标题的真理源
|
||||
|
||||
**状态**：已接受
|
||||
**日期**：2026-05-18
|
||||
|
||||
## 背景
|
||||
|
||||
知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter，其中也有 `date`/`created` 和 `title` 字段，但实际使用中发现字段名不一致（`date` vs `created`）和格式差异。
|
||||
|
||||
索引重建脚本需要确定日期和标题的权威来源。
|
||||
|
||||
## 决策
|
||||
|
||||
**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
|
||||
|
||||
- 日期从目录名的 `YYYYMMDD` 部分提取
|
||||
- 短标识符从目录名的 `Slug` 部分提取（用于文件路径构建，不用于显示）
|
||||
- 显示标题从 YAML frontmatter 的 `title` 字段提取
|
||||
- `tags` 和 `author` 从 YAML frontmatter 提取
|
||||
|
||||
## 替代方案
|
||||
|
||||
| 方案 | 被拒原因 |
|
||||
|------|---------|
|
||||
| YAML 全优先 | 字段名不一致（date vs created） |
|
||||
| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失（如 `mattpocock_skills` → `mattpocock skills`，实际标题更长更精确）
|
||||
|
||||
## 后果
|
||||
|
||||
### 正面
|
||||
- 索引脚本不需要处理日期字段名变体（date vs created）
|
||||
- 目录名是可见的、可审计的——与 `ls` 输出完全一致
|
||||
- bash 用 glob 匹配 `knowledge_*` 目录，天然获取了日期和 slug
|
||||
- 显示标题从 YAML 取，支持完整的、精确的标题文本（含标点、中文）
|
||||
|
||||
### 负面
|
||||
- 索引脚本需要解析 YAML frontmatter（复杂度比仅取目录名高）
|
||||
- 如果目录被重命名，slug 会变化但显示标题不受影响（可接受的行为）
|
||||
- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定
|
||||
@@ -0,0 +1,57 @@
|
||||
# PRD: 知识库索引面板 (Knowledge Index Panel)
|
||||
|
||||
## Problem Statement
|
||||
|
||||
用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。
|
||||
|
||||
## Solution
|
||||
|
||||
在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。
|
||||
|
||||
## User Stories
|
||||
|
||||
1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when
|
||||
2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders
|
||||
3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics
|
||||
4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber`
|
||||
5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup
|
||||
6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied
|
||||
7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query
|
||||
8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most
|
||||
|
||||
## Implementation Decisions
|
||||
|
||||
- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies
|
||||
- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()`
|
||||
- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support
|
||||
- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `<mark>` tags for highlighting
|
||||
- **Tag system**: In-memory `Map<tag, entry[]>` built at load time. Click to filter, click again to deselect
|
||||
- **Related Content**: Computed from shared tags, displayed per-entry
|
||||
- **No pagination**: Designed for < 50 entries. Full list rendered at once
|
||||
- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state
|
||||
- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures
|
||||
- **Edge cases to verify**:
|
||||
- Missing directory (manifest lists a name that doesn't exist) → skip gracefully
|
||||
- Malformed YAML → display directory name as fallback
|
||||
- Empty tags array → no tag badges rendered
|
||||
- No search results → show "没有找到相关条目" message
|
||||
- Browser CORS when opened via `file://` protocol → document the workaround
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Google Drive / cloud sync
|
||||
- Editing knowledge entries
|
||||
- Full YAML 1.2 spec compliance
|
||||
- Pagination or virtual scrolling
|
||||
- Fuse.js or other fuzzy search libraries (keep it zero-dependency)
|
||||
- Dark mode toggle (can add later, not in v1)
|
||||
|
||||
## Further Notes
|
||||
|
||||
- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array
|
||||
- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality
|
||||
- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"version": 1,
|
||||
"skills": {
|
||||
"diagnose": {
|
||||
"source": "mattpocock/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skill-workbench/validation/project/skills/skills/engineering/diagnose/SKILL.md",
|
||||
"computedHash": "1c3c85517ac42116fe5f2bfb5150f7b3e38ad23808e40b33fbb01f1afb611983"
|
||||
},
|
||||
"grill-with-docs": {
|
||||
"source": "mattpocock/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skill-workbench/validation/project/skills/skills/engineering/grill-with-docs/SKILL.md",
|
||||
"computedHash": "499b742470fe169976bacdba2f30d7a6a25b526629cb42ab21dfa06e1eb286dc"
|
||||
},
|
||||
"tdd": {
|
||||
"source": "mattpocock/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skill-workbench/validation/project/skills/skills/engineering/tdd/SKILL.md",
|
||||
"computedHash": "78b31b2120c5fe7aced1cebfd4c7c94acb0037fd4f89c83c67584414aa4173bd"
|
||||
},
|
||||
"to-prd": {
|
||||
"source": "mattpocock/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skill-workbench/validation/project/skills/skills/engineering/to-prd/SKILL.md",
|
||||
"computedHash": "a80acb8760af6521a37ea4f079e617712fcaa800f8a766e247f815c5dabb20d2"
|
||||
},
|
||||
"zoom-out": {
|
||||
"source": "mattpocock/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skill-workbench/validation/project/skills/skills/engineering/zoom-out/SKILL.md",
|
||||
"computedHash": "a8b8ed45609fdfa9f184d0c9f69326e43822a42eebea14db2792d777373de562"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,216 @@
|
||||
# Essence 报告：AI Pipeline 架构
|
||||
|
||||
**项目：** Lumina
|
||||
**Lens（透镜）：** Mechanical（技术实现）
|
||||
**设计分析：** Article AI Pipeline Service
|
||||
**文件数：** 6 个核心文件
|
||||
**状态：** 完成
|
||||
|
||||
---
|
||||
|
||||
## 定位
|
||||
|
||||
** standout design：** 模块化 AI 内容处理管道，支持配置化 Prompt 和 Model。
|
||||
|
||||
**为什么值得学：**
|
||||
- 解决「AI 处理步骤硬编码」的通病
|
||||
- 结构化输出协议可复用到其他 AI 项目
|
||||
- 任务状态机设计可迁移到任意异步处理系统
|
||||
|
||||
---
|
||||
|
||||
## 核心文件
|
||||
|
||||
| 文件 | 角色 | 关键内容 |
|
||||
|------|------|----------|
|
||||
| `article_ai_pipeline_service.py:102` | Pipeline 编排器 | `ArticleAIPipelineService` 主类 |
|
||||
| `article_ai_pipeline_service.py:114` | 输出契约定义 | `STRUCTURED_OUTPUT_CONTRACTS` |
|
||||
| `article_ai_pipeline_service.py:2039` | 清洗阶段 | `process_article_cleaning` |
|
||||
| `article_ai_pipeline_service.py:3567` | AI 内容生成 | `process_ai_content` |
|
||||
| `task_state.py:1` | 状态机 | `ALLOWED_TASK_STATUS_TRANSITIONS` |
|
||||
|
||||
---
|
||||
|
||||
## Call Chain 调用链
|
||||
|
||||
```
|
||||
submit_article(url)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ ingest_service │
|
||||
│ - fetch raw HTML │
|
||||
└───────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────┐
|
||||
│ process_article_cleaning│────▶│ process_article_validate│
|
||||
│ - 清洗原始内容为 Markdown│ │ - 验证内容合规性 │
|
||||
└───────────┬─────────────┘ └───────────┬─────────────┘
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌─────────────────────────┐
|
||||
│ │ process_article_classify│
|
||||
│ │ - 自动分类 │
|
||||
│ └───────────┬─────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────┐
|
||||
│ process_article_tagging │ │ 其他 AI 任务... │
|
||||
│ - 自动打标签 │ │ │
|
||||
└───────────┬─────────────┘ └─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ process_ai_content │
|
||||
│ - summary/key_points/ │
|
||||
│ quotes/outline/ │
|
||||
│ infographic │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心设计模式
|
||||
|
||||
### 1. 结构化输出契约（Structured Output Contract）
|
||||
|
||||
**文件:** `article_ai_pipeline_service.py:114-205`
|
||||
|
||||
```python
|
||||
STRUCTURED_OUTPUT_CONTRACTS = {
|
||||
"classification": PromptOutputContract(
|
||||
mode="structured_json",
|
||||
response_format={
|
||||
"type": "json_schema",
|
||||
"json_schema": {
|
||||
"name": "article_classification_result",
|
||||
"schema": {"type": "object", "properties": {
|
||||
"category_id": {"type": "string"}
|
||||
}, "required": ["category_id"]}
|
||||
}
|
||||
},
|
||||
system_instruction="固定输出协议：必须返回单个 JSON 对象..."
|
||||
),
|
||||
# ... tagging, validation, outline
|
||||
}
|
||||
```
|
||||
|
||||
**作用：** 将「AI 输出格式不稳定的」问题在系统设计层面解决，不再依赖 Prompt Engineering。
|
||||
|
||||
### 2. 可配置 Prompt + Model 绑定
|
||||
|
||||
**文件:** `article_ai_pipeline_service.py:255-334`
|
||||
|
||||
**查询优先级：**
|
||||
1. 传入的 `model_config_id` / `prompt_config_id`
|
||||
2. Category 级别的配置
|
||||
3. 全局默认配置
|
||||
|
||||
**迁移价值：**
|
||||
- 无需重启服务即可切换模型
|
||||
- A/B 测试不同 Prompt 效果
|
||||
- 支持多模型混用（强项模型处理特定任务）
|
||||
|
||||
### 3. Pipeline 状态机
|
||||
|
||||
**文件:** `task_state.py:12-23`
|
||||
|
||||
```python
|
||||
ALLOWED_TASK_STATUS_TRANSITIONS = {
|
||||
TASK_STATUS_PENDING: {TASK_STATUS_PROCESSING, TASK_STATUS_CANCELLED},
|
||||
TASK_STATUS_PROCESSING: {
|
||||
TASK_STATUS_PENDING, TASK_STATUS_COMPLETED, TASK_STATUS_FAILED
|
||||
},
|
||||
TASK_STATUS_FAILED: {TASK_STATUS_PENDING}, # 支持重试
|
||||
TASK_STATUS_CANCELLED: {TASK_STATUS_PENDING}, # 取消后可恢复
|
||||
}
|
||||
```
|
||||
|
||||
**扩展点：** 状态流转规则集中定义，新增状态只需改一行。
|
||||
|
||||
### 4. 续写/修复机制
|
||||
|
||||
**文件:** `article_ai_pipeline_service.py:3567-3598`
|
||||
|
||||
```python
|
||||
async def process_ai_content(
|
||||
self,
|
||||
article_id: str,
|
||||
content_type: str,
|
||||
continuation_source_usage_id: str | None = None, # 续写源头
|
||||
continuation_feedback: str | None = None, # 用户反馈
|
||||
...
|
||||
):
|
||||
```
|
||||
|
||||
**设计意图：** 不是一轮生成完事，而是支持「反馈 → 修复 → 续写」的迭代循环。
|
||||
|
||||
---
|
||||
|
||||
## Pattern 分析
|
||||
|
||||
| 维度 | 内容 |
|
||||
|------|------|
|
||||
| **问题** | 如何为同一篇文章批量生成摘要、标签、分类、翻译等 AI 内容？ |
|
||||
| **模式** | 配置驱动的 Pipeline + 结构化输出契约 |
|
||||
| **替代方案** | A) 每个功能独立 endpoint，各自调用 AI（重复配置）；B) 固定流程硬编码（不可配置） |
|
||||
| **Tradeoff** | 放弃实时性（Pipeline 异步执行），换取可配置性和失败隔离 |
|
||||
| **证据** | `article_ai_pipeline_service.py:102-205` 定义契约；`task_state.py:1-60` 状态机 |
|
||||
|
||||
---
|
||||
|
||||
## Migration 示例（可执行）
|
||||
|
||||
**场景：** 为自己的项目实现「User Content → AI Processed Content」管道。
|
||||
|
||||
```python
|
||||
# pipeline.py - 核心骨架（≤20 行）
|
||||
from dataclasses import dataclass
|
||||
from typing import Callable
|
||||
|
||||
@dataclass
|
||||
class PipelineStep:
|
||||
name: str
|
||||
processor: Callable[[str], str]
|
||||
output_type: str = "text"
|
||||
|
||||
class ContentPipeline:
|
||||
def __init__(self):
|
||||
self.steps: list[PipelineStep] = []
|
||||
|
||||
def add_step(self, step: PipelineStep):
|
||||
self.steps.append(step)
|
||||
|
||||
async def process(self, content: str) -> dict:
|
||||
results = {"input": content}
|
||||
for step in self.steps:
|
||||
results[step.name] = await step.processor(results.get(step.output_type, content))
|
||||
return results
|
||||
|
||||
# 使用
|
||||
pipeline = ContentPipeline()
|
||||
pipeline.add_step(PipelineStep("clean", clean_html, "text"))
|
||||
pipeline.add_step(PipelineStep("summarize", generate_summary, "clean"))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pitfalls 陷阱
|
||||
|
||||
| 陷阱 | 原因 | 规避方法 |
|
||||
|------|------|----------|
|
||||
| AI 输出格式不稳定 | 未定义结构化契约 | 复制 `STRUCTURED_OUTPUT_CONTRACTS` 思想 |
|
||||
| Pipeline 某步失败导致整体失败 | 无状态隔离 | 每步独立状态，失败可重试 |
|
||||
| Prompt 调优困难 | Prompt 与代码耦合 | 数据库存储，支持按 category 配置 |
|
||||
| 成本不可控 | 无 Token 统计 | 每步记录 `price_input_per_1k` / `price_output_per_1k` |
|
||||
|
||||
---
|
||||
|
||||
## 证据核对
|
||||
|
||||
- [x] 设计真实存在（`article_ai_pipeline_service.py:102`）
|
||||
- [x] 文件列表 ≤ 10（实际 6 个）
|
||||
- [x] Pattern 可解释（配置驱动 + 结构化契约）
|
||||
- [x] Migration ≤ 20 行（上面示例 19 行）
|
||||
- [x] Pitfalls 具体（有代码/配置对应）
|
||||
@@ -0,0 +1,235 @@
|
||||
# Explore 报告：Lumina（优化版）
|
||||
|
||||
**项目类型：** 代码仓库
|
||||
**完成阶段：** 5/5
|
||||
**包含图示：** 是
|
||||
**核心设计：** 3 个
|
||||
**状态：** 完成
|
||||
|
||||
---
|
||||
|
||||
## 阶段 1：定位
|
||||
|
||||
**是什么：** Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。
|
||||
|
||||
**为什么值得学习：**
|
||||
- 完整的内容处理 AI Pipeline 架构
|
||||
- 领域驱动分层设计，关注点分离清晰
|
||||
- 支持多租户的内容管理，内置治理功能
|
||||
|
||||
**目标用户：** 需要构建自托管知识库或 AI 增强 CMS 的开发者。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 2：结构
|
||||
|
||||
```
|
||||
lumina-main/
|
||||
├── backend/ # FastAPI Python 后端
|
||||
│ ├── app/
|
||||
│ │ ├── api/routers/ # 16 个 REST 端点模块
|
||||
│ │ ├── domain/ # 业务逻辑层 ⭐
|
||||
│ │ ├── core/ # 配置与依赖
|
||||
│ │ └── schemas/ # Pydantic 数据模型
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── ai_client.py # AI 客户端抽象
|
||||
│ └── models.py # SQLAlchemy ORM 定义
|
||||
└── frontend/ # Next.js React 前端
|
||||
└── src/
|
||||
├── app/ # App Router 结构
|
||||
└── components/ # 可复用 UI 组件
|
||||
```
|
||||
|
||||
**入口点：**
|
||||
- 后端：`backend/app/domain/` - 业务逻辑
|
||||
- 前端：`frontend/src/app/(routes)/` - 页面路由
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3：流程（优化版 - 黄金路径视角）
|
||||
|
||||
### 端到端用户流程图
|
||||
|
||||
```
|
||||
用户视角:
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ 输入URL │──────▶│ 等待处理 │──────▶│ 查看文章 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
|
||||
系统视角:
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ API接收请求 │──────▶│ URL获取内容 │──────▶│ 内容清洗 │
|
||||
└──────────────┘ └──────────────┘ └───────┬──────┘
|
||||
│
|
||||
┌──────────────┐ ┌──────────────┐ ┌───────▼──────┐
|
||||
│ 向量存储 │◀────│ 信息提取 │◀────│ AI处理链 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 响应用户 │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 模块调用链
|
||||
|
||||
**文章导入完整调用链：**
|
||||
|
||||
```
|
||||
POST /api/articles/ingest
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ article_router.py │
|
||||
│ - 接收 URL payload │
|
||||
└──────────────┬───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ article_url_ingest_service.py │
|
||||
│ - 获取原始 HTML │
|
||||
└──────────────┬───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ article_ai_pipeline_service.py │
|
||||
│ ┌──────────────┬──────────────┐ │
|
||||
│ │ clean_text │ extract_tags │ │
|
||||
│ └──────────────┴──────────────┘ │
|
||||
│ ┌──────────────┬──────────────┐ │
|
||||
│ │ summarize │ embed │ │
|
||||
│ └──────────────┴──────────────┘ │
|
||||
└──────────────┬───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ article_command_service.py │
|
||||
│ - 持久化到数据库 │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**优化点说明：**
|
||||
- 原报告只展示了 `pipeline_service` 单文件内部流程
|
||||
- 优化版增加了**用户视角的端到端流程**和**完整的模块调用链**
|
||||
- 让读者理解从 URL 到数据库的完整路径，不只是中间某个环节
|
||||
|
||||
---
|
||||
|
||||
## 阶段 4：起步路径（优化版 - 可执行命令）
|
||||
|
||||
**前置要求：**
|
||||
- Python 3.11+
|
||||
- PostgreSQL
|
||||
|
||||
**步骤 1：环境准备**
|
||||
```bash
|
||||
cd backend
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
**步骤 2：数据库初始化**
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
**步骤 3：启动服务**
|
||||
```bash
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
**首个观察点：**
|
||||
打开 `backend/app/api/routers/article_router.py`，搜索 `ingest` 端点，观察：
|
||||
- 接收什么参数（URL、可选的 category_id）
|
||||
- 调用哪个 service 方法
|
||||
- 返回什么响应
|
||||
|
||||
**第一个可执行的修改（颗粒度细化）：**
|
||||
|
||||
原报告只说了"修改 AI_MODEL"，没有具体命令。以下是可落地的步骤：
|
||||
|
||||
```bash
|
||||
# 1. 复制示例配置文件
|
||||
cp backend/.env.example backend/.env
|
||||
|
||||
# 2. 查看当前 AI 模型设置
|
||||
grep AI_MODEL backend/.env
|
||||
# 输出: AI_MODEL=gpt-3.5-turbo
|
||||
|
||||
# 3. 修改为其他模型（举例）
|
||||
sed -i 's/AI_MODEL=.*/AI_MODEL=gpt-4o-mini/' backend/.env
|
||||
|
||||
# 4. 确认修改成功
|
||||
grep AI_MODEL backend/.env
|
||||
# 输出: AI_MODEL=gpt-4o-mini
|
||||
|
||||
# 5. 重启服务（如果已运行）
|
||||
# Ctrl+C 停止，然后重新运行:
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# 6. 验证：测试 AI 摘要功能
|
||||
# 在浏览器打开: http://localhost:8000/docs
|
||||
# 找到 POST /api/articles/ingest，Try it out
|
||||
# 输入: {"url": "https://example.com/article"}
|
||||
# 观察响应中的 summary 字段质量变化
|
||||
```
|
||||
|
||||
**安全边界：**
|
||||
- 只改 `.env` 文件，不动源码
|
||||
- 随时可以 `cp backend/.env.example backend/.env` 恢复
|
||||
- 改模型不影响数据库，只影响 AI 调用
|
||||
|
||||
---
|
||||
|
||||
## 阶段 5：核心设计
|
||||
|
||||
| # | 设计 | 位置 | 重要性 |
|
||||
|---|------|------|--------|
|
||||
| 1 | **领域服务层** | `app/domain/*.py` | API 与数据库解耦；AI 集成可独立演进 |
|
||||
| 2 | **AI Pipeline 架构** | `article_ai_pipeline_service.py` | AI 处理不耦合 ORM；可配置、可追踪 |
|
||||
| 3 | **路由注册器** | `api/router_registry.py` | 集中注册；新增模块无需改动 main.py |
|
||||
|
||||
---
|
||||
|
||||
## 架构图示
|
||||
|
||||
**后端领域架构：**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ API 路由层 │
|
||||
│ (article, ai_tasks, auth, settings...) │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────────▼──────────────────────┐
|
||||
│ 领域服务层 │
|
||||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │article_query │ │article_command │ │
|
||||
│ └──────────────┘ └──────────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ai_pipeline │ │ingest_service │ │
|
||||
│ └──────────────┘ └──────────────────┘ │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────────▼──────────────────────┐
|
||||
│ SQLAlchemy 模型层 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 优化点总结
|
||||
|
||||
| 优化项 | 原报告 | 优化版 | 改进原因 |
|
||||
|--------|--------|--------|----------|
|
||||
| Phase 3 流程 | 单文件内部流程 | 端到端用户流程 + 完整调用链 | 让读者理解全貌，不只是某个环节 |
|
||||
| Phase 4 修改 | "修改 AI_MODEL"（笼统） | 给具体命令：copy → sed → grep → 重启 → 测试 | 用户可直接执行，有验证环节 |
|
||||
|
||||
---
|
||||
|
||||
## 验证备注
|
||||
|
||||
- 按 v0.5.0 规范完成 5 个阶段
|
||||
- 未进行 essence 级别的深度提取
|
||||
- 未进行交互式教学
|
||||
- 遵守边界规则
|
||||
- Phase 4 的修改建议已通过 `sed` 命令细化到可操作级别
|
||||
@@ -0,0 +1,134 @@
|
||||
# Explore 报告：Lumina
|
||||
|
||||
**项目类型：** 代码仓库
|
||||
**完成阶段：** 5/5
|
||||
**包含图示：** 是
|
||||
**核心设计：** 3 个
|
||||
**状态：** 完成
|
||||
|
||||
---
|
||||
|
||||
## 阶段 1：定位
|
||||
|
||||
**是什么：** Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。
|
||||
|
||||
**为什么值得学习：**
|
||||
- 完整的内容处理 AI Pipeline 架构
|
||||
- 领域驱动分层设计，关注点分离清晰
|
||||
- 支持多租户的内容管理，内置治理功能
|
||||
|
||||
**目标用户：** 需要构建自托管知识库或 AI 增强 CMS 的开发者。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 2：结构
|
||||
|
||||
```
|
||||
lumina-main/
|
||||
├── backend/ # FastAPI Python 后端
|
||||
│ ├── app/
|
||||
│ │ ├── api/routers/ # 16 个 REST 端点模块
|
||||
│ │ ├── domain/ # 业务逻辑层 ⭐
|
||||
│ │ ├── core/ # 配置与依赖
|
||||
│ │ └── schemas/ # Pydantic 数据模型
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── ai_client.py # AI 客户端抽象
|
||||
│ └── models.py # SQLAlchemy ORM 定义
|
||||
└── frontend/ # Next.js React 前端
|
||||
└── src/
|
||||
├── app/ # App Router 结构
|
||||
└── components/ # 可复用 UI 组件
|
||||
```
|
||||
|
||||
**入口点：**
|
||||
- 后端：`backend/app/domain/` - 业务逻辑
|
||||
- 前端：`frontend/src/app/(routes)/` - 页面路由
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3：流程
|
||||
|
||||
**核心流程：文章导入 → AI 处理 → 存储**
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
|
||||
│ URL 提交 │────▶│ ingest_service │────▶│ Router │
|
||||
└─────────────┘ └──────────────────┘ └──────┬──────┘
|
||||
│
|
||||
┌─────────────┐ ┌──────────────────┐ │
|
||||
│ 响应 │◀────│ pipeline_service │◀──────────┘
|
||||
└─────────────┘ └──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ ORM │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**关键文件：** `backend/app/domain/article_ai_pipeline_service.py` - 模块化 AI 处理链，支持可配置步骤（清洗 → 打标签 → 摘要 → 嵌入）。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 4：起步路径
|
||||
|
||||
**前置要求：**
|
||||
- Python 3.11+
|
||||
- PostgreSQL
|
||||
|
||||
**设置命令：**
|
||||
```bash
|
||||
cd backend
|
||||
pip install -e .
|
||||
alembic upgrade head # 初始化数据库模式
|
||||
uvicorn app.main:app --reload # 启动开发服务器
|
||||
```
|
||||
|
||||
**首个观察点：** 在 router 中查看 `article_ai_pipeline_service.py` 的调用链。
|
||||
|
||||
**安全的首个修改：** 修改 `core/settings.py` 中的 `AI_MODEL`，观察不同的 AI 行为。
|
||||
|
||||
---kanyii
|
||||
|
||||
## 阶段 5：核心设计
|
||||
|
||||
| # | 设计 | 位置 | 重要性 |
|
||||
|---|------|------|--------|
|
||||
| 1 | **领域服务层** | `app/domain/*.py` | API 与数据库解耦；AI 集成可独立演进 |
|
||||
| 2 | **AI Pipeline 架构** | `article_ai_pipeline_service.py` | AI 处理不耦合 ORM；可配置、可追踪 |
|
||||
| 3 | **路由注册器** | `api/router_registry.py` | 集中注册；新增模块无需改动 main.py |
|
||||
|
||||
---
|
||||
|
||||
## 架构图示
|
||||
|
||||
**后端领域架构：**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ API 路由层 │
|
||||
│ (article, ai_tasks, auth, settings...) │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────────▼──────────────────────┐
|
||||
│ 领域服务层 │
|
||||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │article_query │ │article_command │ │
|
||||
│ └──────────────┘ └──────────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ai_pipeline │ │ingest_service │ │
|
||||
│ └──────────────┘ └──────────────────┘ │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────────▼──────────────────────┐
|
||||
│ SQLAlchemy 模型层 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证备注
|
||||
|
||||
- 按 v0.5.0 规范完成 5 个阶段
|
||||
- 未进行 essence 级别的深度提取
|
||||
- 未进行交互式教学
|
||||
- 遵守边界规则
|
||||
Reference in New Issue
Block a user