# Knowledge Lifecycle Pipeline Design

## 整体流程

```mermaid
graph TB
  subgraph Trigger[触发入口]
    A1["知识沉淀<br/>(单模块)"]
    A2["同步知识<br/>(diff 影响)"]
    A3["项目图谱<br/>(全量)"]
  end

  subgraph Stage1[Stage 1: 架构/影响分析]
    B1["architecture-lens<br/>扫描构建声明 + 目录<br/>输出模块清单"]
    B2["impact-analyzer<br/>读 git diff + 路径/语义匹配<br/>输出影响报告"]
  end

  subgraph Stage2[Stage 2: 模块拆卡]
    C["card-splitter<br/>(逐模块, 可并发)"]
  end

  subgraph Stage4[Stage 4: 知识卡片生成]
    E["card-generator<br/>(仅 status=needs_update, 可并发)"]
  end

  subgraph Stage5[Stage 5: Wiki 生成]
    F["wiki-analyzer<br/>→ project_config.py"]
    G["generate-wiki.py<br/>→ _sidebar.md + README.md + index.html"]
  end

  A1 --> C
  A2 --> B2 --> C
  A3 --> B1 --> C
  C --> E
  E --> F --> G
```

## 存储结构

```
local_knowledge/
├── dev-toolkit/
│   └── skills/knowledge-lifecycle/          ← skill 目录
│       ├── SKILL.md                         ← 编排逻辑
│       ├── design/                          ← 设计文档
│       │   ├── knowledge-lifecycle-design.md
│       │   └── knowledge-graph-structure.md
│       ├── template/                        ← 模板文件
│   │   └── summary.template.md
│       └── prompts/                         ← sub-agent prompt 模板
│           ├── architecture-lens.md
│           ├── card-splitter.md
│           ├── card-generator.md
│           ├── impact-analyzer.md
└── knowledge-card/                          ← 数据目录
    ├── summary/                             ← card-splitter 维护
    │   └── {id}.summary.md
    ├── card/                                ← card-generator 维护
    │   └── {id}.md
    ├── architecture/                        ← architecture-lens 输出
    │   ├── architecture-overview.md
    │   └── module-source-manifest.md

## 分工原则

| 层 | 职责 | 做 | 不做 |
|----|------|----|------|
| **Skill** | 编排层 | dispatch agent、校验结果完整性、提示用户 | codegraph、写文件、更新 frontmatter |
| **card-splitter** | 分析+写入层 | codegraph 分析、写/更新 summary（含正文） | 生成 card、写 map |
| **impact-analyzer** | 影响分析层 | 读 git diff、路径/语义匹配、输出影响报告 | 写文件、调度其他 agent |
| **card-generator** | 卡片生成层 | 读 summary、写/更新 card、校验 card frontmatter | 修改 summary、修改 map |

## 各阶段定义

### Stage 0: 架构扫描 — architecture-lens

| 属性 | 值 |
|------|-----|
| 分析引擎 | codegraph 优先，文件路径启发式兜底 |
| 权限 | read-only |

**职责：**
1. 检测项目类型（Android/iOS/HarmonyOS/Web/Flutter）
2. 扫描构建声明 → 识别所有显式模块
3. 解析第 1 层（项目元信息）
4. 解析第 2 层（外部依赖库）
5. 解析第 5 层（业务模块）← 优先判断
6. 解析第 3 层（基础设施）← 仅非业务模块
7. 解析第 4 层（公共服务）← 仅非业务、非基础模块
8. 解析第 6 层（工程支撑）
9. 解析第 7 层（资源文件）
10. 分析跨层依赖/协作
11. 单模块扁平项目 → 整个 `src/` 兜底为根模块
12. 获取当前 git HEAD，写入 `.lens-config.yaml`

| | 输入 | 输出 |
|--|------|------|
| **内容** | 项目构建文件 + 源码目录 | 架构全景图 + 模块清单 |
| **文件** | settings.gradle / Podfile / build.gradle / package.json / pubspec.yaml / 源码目录 | `architecture/architecture-overview.md`<br/>`architecture/module-source-manifest.md`<br/>`architecture/.lens-config.yaml` |
| **数据** | 构建声明、项目配置、依赖声明、目录结构 | 7 层 + 跨层依赖全景（项目元信息/外部依赖库/基础设施/公共服务/业务模块/工程支撑/资源文件）、每模块一行（name/path/node_type） |

<br/>

### Stage 0': 影响分析 — impact-analyzer

| 属性 | 值 |
|------|-----|
| 分析引擎 | 路径匹配 + codegraph 语义影响分析 |
| 权限 | read-only |

**职责：**
1. 读 git diff（取上次 commit..HEAD）
2. 路径匹配：`code_locations` 精确/前缀匹配
3. 语义影响分析：被变更代码的调用方、继承方
4. 合并去重 → 输出影响报告

| | 输入 | 输出 |
|--|------|------|
| **内容** | git diff + 知识摘要的 code_locations | 受影响模块列表（含 direct_matches + impacted_summaries） |
| **文件** | git diff（`{last_commit}..HEAD`） | `impact-report.json` |
| **数据** | 变更文件路径、变更内容摘要 | direct_matches、impacted_summaries（去重合并后即为待处理模块列表） |

<br/>

### Stage 1: 模块拆卡 — card-splitter

| 属性 | 值 |
|------|-----|
| 调度方式 | 逐模块并发（每批 ≤ 15） |
| 编辑范围 | `knowledge-card/summary/` |
| 单次处理 | 严格一个模块 |

**职责（一次调用完成全部）：**
1. 收模块元信息（模块名、node_type、源码路径、备注）
2. codegraph 分析 → 扫描子目录判断拆分可能性
3. 推断 domain（从模块名或备注）
4. 扫描源码子目录 → 判断被拆子模块可能性
   - 实际拆成多张 summary（一个模块产出 ≥1 个 summary 文件）
   - 不拆时产出 1 个 summary
5. 写/更新 summary（frontmatter + 正文骨架/完整）
6. 设 summary status = `needs_update`（信号给下游）

| | 输入 | 输出 |
|--|------|------|
| **内容** | 模块元信息 + 源码目录 | 模块摘要文件（frontmatter + 正文） |
| **文件** | `architecture/module-source-manifest.md`（从 lens 来）<br/>源码目录 | `summary/{id}.summary.md`（一个模块可能产出多个） |

| **数据** | 模块名、node_type、源码路径、备注 | frontmatter（name/node_type/domain/status）<br/>正文（架构要点/核心接口/关键依赖） |

### 知识卡片生成 — card-generator

| 属性 | 值 |
|------|-----|
| 调度方式 | 遍历 summary → 仅 status=needs_update 的并发处理 |
| 编辑范围 | `knowledge-card/card/` |

**职责：**
1. 读 summary
2. 检查 status：
   - `active` → 跳过
   - `needs_update` → 继续
3. 读 update_scope：
   - `full` → 全量重写 card
   - `incremental` → 检查 `affected_chapters`：
     - 有值（非空数组） → 只重写指定章节
     - 无值或空数组 → 对比 summary 变更，定位受影响章节
4. codegraph/grep 补充源码细节
5. 写/更新 `card/{id}.md`（含 summary_id）
6. 改 summary status = `active`
7. 校验 card frontmatter

| | 输入 | 输出 |
|--|------|------|
| **内容** | summary 文件（frontmatter + 正文） | 完整知识卡片 |
| **文件** | `summary/{id}.summary.md` | `card/{id}.md` |
| **数据** | status（决定是否处理）<br/>update_scope（决定全量/增量）<br/>正文骨架 | 完整卡片（含源码细节扩展）<br/>summary.status 改为 `active` |

### Wiki 生成

| 属性 | 值 |
|------|-----|
| 参与 agent | wiki-analyzer（分析）+ generate-wiki.py（生成） |

**wiki-analyzer 职责：**
1. 读所有 summary frontmatter
2. 分析依赖拓扑 → 推断分组归属
3. 读 card title → 推断中文模块名
4. 生成 project_config.py

**generate-wiki.py 职责：**
1. 读 project_config.py
2. 生成 `_sidebar.md`（侧边栏目录树）
3. 生成 `README.md`（项目总览）
4. 更新 `index.html`（模块数据注入）

| | 输入 | 输出 |
|--|------|------|
| **内容** | 全部 summary + card | Wiki 页面 |
| **文件** | `summary/*.summary.md`<br/>`card/*.md` | `project_config.py`<br/>`_sidebar.md`<br/>`README.md`<br/>`index.html` |
| **数据** | 模块名、依赖关系、分组归属、中文名 | 可浏览的 Wiki 站点 |

## 四条流程

### 流程一：知识沉淀

```
用户: "知识沉淀 sport"

Skill → dispatch card-splitter (single mode)
   输入: 模块名 + node_type + 源码路径 + 备注
   输出: summary/{id}.summary.md (status=needs_update)

Skill → dispatch card-generator
   输入: summary/{id}.summary.md
   输出: card/{id}.md
   副作用: summary.status → active

Skill: 合规检查 → 输出变更摘要
```

### 流程二：同步知识

```
用户: "同步知识" / "同步知识 HEAD~3"

Skill → dispatch impact-analyzer
  输入: git diff {last_commit}..HEAD
  输出: impact-report.json (affected 模块列表)

Skill → 读影响报告 → 逐模块 dispatch card-splitter (并发)
   输入: 模块元信息 (name/node_type/path/备注)
   输出: summary/{id}.summary.md (status=needs_update)

Skill → dispatch card-generator (仅 needs_update 模块, 并发)
   输入: summary/{id}.summary.md
   输出: card/{id}.md
   副作用: summary.status → active

Skill: 合规检查 → 提示用户

Skill: 清理临时文件 → 删除 `impact-report.json`
```

### 流程三：项目图谱

```
用户: "项目图谱"

Skill → dispatch architecture-lens
  输入: 项目构建文件 + 源码目录
  输出:
    - architecture/architecture-overview.md
    - architecture/module-source-manifest.md

Skill → 读 manifest → 逐模块 dispatch card-splitter (并发)
   输入: 模块元信息 (name/node_type/path/备注)
   输出: summary/{id}.summary.md (status=needs_update)
   特点: 可能一模块拆多卡

Skill → dispatch card-generator (仅 needs_update 模块, 并发)
   输入: summary/{id}.summary.md
   输出: card/{id}.md
   副作用: summary.status → active

Skill: 合规检查 → 输出变更摘要
```

### 流程四：初始化 Wiki

```
用户: "初始化 Wiki"

Skill → dispatch wiki-analyzer
  输入: summary/*.summary.md + card/*.md
  输出: project_config.py

Skill → run generate-wiki.py
  输入: project_config.py
  输出: _sidebar.md + README.md + index.html

Skill → start HTTP server (port 8081)
  输出: http://localhost:8081/
```

## 状态机

```
                    card-splitter 创建/更新
                         │
                         ▼
              ┌─────────────────────┐
              │  summary.status     │
              │  = needs_update     │
              └─────────┬───────────┘
                        │
              card-generator 读取
              ┌─────────┴───────────┐
              │                     │
              ▼                     ▼
   ┌──────────────────┐  ┌──────────────────┐
   │ summary.status   │  │ summary.status   │
   │ = active         │  │ = active         │
   │ card.md 已生成   │  │ card.md 已更新   │
   └──────────────────┘  └──────────────────┘
```

- `needs_update` → card-generator 将处理
- `active` → card-generator 跳过
- card-splitter 永远设 `needs_update`，card-generator 永远改 `active`

## 调度规则

### 并发批量上限
无依赖 agent 可并发 dispatch，每批最多 **15 个 Task**，每个 Task 严格对应一个模块。超过 15 个时分批发送，上一批全部完成才发下一批。

### 串行依赖
有上下游依赖的 agent 必须串行，前序完成才 dispatch 后续。

### 禁止合并角色
不得将多个 agent 的职责合入单个 dispatch。

### 必须 prompt 文件
dispatch agent 时，prompt 参数含 Read 对应 prompt 文件的指令，子 agent 启动后自行加载规则。

### 分段禁止 inline
Skill 不得将 agent prompt 全文内联进 prompt 参数，只能写 "Read {path}"。

## 决策记录

| # | 决策 | 理由 |
|---|------|------|
| 1 | Skill 只做编排，不做执行 | 分工清晰，Skill 保持轻量 |
| 2 | card-splitter 每次只处理一个模块 | 单模块独立拆卡，避免上下文过大导致漏拆 |
| 3 | architecture-lens 输出模块源码清单 | card-splitter 不需要推断模块路径，直接使用 |
| 4 | card-splitter 每次只处理一个模块 | 单模块独立拆卡，避免上下文过大导致漏拆 |
| 5 | "项目图谱" dispatch card-generator 批量生成 card | 用户要求图谱更新后立即更新摘要和卡片 |
| 6 | **summary status 是 card-generator 触发的唯一信号** | card-generator 只看 status，不看 diff 或时间戳 |
| 7 | card-splitter 写完设 `needs_update`，card-generator 生成完改 `active` | 避免重复劳动，保证一致性 |
| 8 | code_locations 支持目录前缀 + 精确文件两种粒度 | 灵活性适配大模块和小模块 |
| 9 | impact-analyzer 做两步匹配（路径 + 语义） | 路径匹配快，语义分析补漏，覆盖率更高 |
| 10 | knowledge-doc-format-rewrite 只校验 card | card 是最终交付物 |
| 11 | architecture-lens 只输出模块级清单，不做文件级扫描 | 颗粒度适中的架构概览，文件级归类留给 card-splitter 做深度细化 |
