---
concept-type: skill
name: knowledge-lifecycle
description: 知识生命周期管理。编排「知识沉淀」「同步知识」「项目图谱」「初始化 Wiki」四条流程。Skill 只做 dispatch + 合规校验 + 提示用户，所有分析/写入由 Agent 完成。
triggers:
    keywords:
      - "知识沉淀"
      - "同步知识"
      - "项目图谱"
      - "初始化 Wiki"
filePatterns:
     - "local_knowledge/knowledge-card/summary/*.summary.md"
     - "local_knowledge/knowledge-card/card/*.md"
---

# Knowledge Lifecycle Skill

## 核心规则 — status 流转

card-generator 触发条件只有一条：**summary status == needs_update**

```
card-splitter 写完/更新 summary → status = needs_update
         │
         ▼
card-generator 读 summary.status：
  ├─ needs_update → 生成/更新 card → 改 status = active
  └─ active       → 跳过
```

所有 card-generator dispatch 都遵循此规则。

## 分工原则

| 层 | 做 | 不做 |
|----|----|------|
| **Skill** | 编排执行流程、校验输出完整性、提示用户决策 | 代码分析、生成知识内容、修改卡片数据 |
| **architecture-lens** | 架构扫描、输出架构全景图 | 写 summary、修改代码 |
| **card-splitter** | 读模块元信息、扫描源码子目录、拆卡、写 summary、设 status = needs_update | 生成 card、写 map |
| **impact-analyzer** | 读 diff、路径+语义影响分析、输出 JSON 报告 | 写文件 |
| **card-generator** | 读 summary.status → 生成/更新 card → 改 status = active、校验 card | 修改 summary/map |

## 调度约束

以下约束适用于全部四条流程，**不可违反**：

### 任务跟踪
**全程使用 `todowrite` 跟踪每条流程的每个阶段。** 按阶段粒度创建 todo（如"card-splitter 第 1 批"、"card-generator 全量"），而非按模块粒度。涉及并发 dispatch 时，每批完成后更新对应阶段的状态。流程结束前确保所有 todo 均为 `completed`。

### 禁止合并 agent 角色
不得将多个 agent 的职责合入单个 dispatch。反例：`"你同时承担 architecture-lens 和 card-splitter"` 是严重违规。每个 `Task tool` dispatch 仅对应一个 agent 角色。

### 禁止跳过前序 agent
每个 agent 的输出是下一 agent 的输入。前序 agent 产出未就绪时，不得 dispatch 后续 agent。

### 必须 prompt 文件
dispatch agent 时，`prompt` 参数中必须包含 `Read` 对应 prompt 文件的指令（子 agent 启动后自行加载完整规则，不要内联全文，也不要凭记忆编造 prompt 内容）。

### 并发批量上限
无依赖的 agent 可并发 dispatch，**每批最多 15 个 Task tool 调用**，每个 Task 仅处理一个模块。超过 15 个时分批发送，上一批全部完成后才发下一批。
**禁止在一个 Task 中打包多个模块** — 每个 `Task tool` dispatch 严格对应一个模块、一个 agent 角色。

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

## 产物合规校验

每个流程末尾的「合规校验 + 输出摘要」步骤，dispatch artifact-validator 执行：

```
Task tool:
  subagent_type: general
  description: "artifact-validator 产物合规校验"
  prompt: >-
    Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/artifact-validator.md 获取完整规则，然后校验本次流程所有产物
```

## 存储结构与归属

```
local_knowledge/
│
├── dev-toolkit/skills/knowledge-lifecycle/              ← skill 目录（非产物）
│   ├── design/     ─── 设计文档
│   ├── template/   ─── 模板文件（summary / impact report 格式）
│   └── prompts/    ─── sub-agent prompt 模板
│   └── SKILL.md    ─── 编排逻辑
│
└── knowledge-card/                                       ← 数据目录
    │
    ├── architecture/                                     ← ← architecture-lens 输出
    │   └── architecture-overview.md                        架构全景图（7层结构）
    │
    ├── summary/                                          ← ← card-splitter 输出
    │   └── {id}.summary.md                                 每个独立单元一张摘要
    │
    ├── card/                                             ← ← card-generator 输出
    │   └── {id}.md                                        基于摘要展开的完整知识卡片
    │
```

## 指令识别

用户调用 skill 时，先识别应进入哪个流程。如有模糊，提示用户选择四种流程之一：单模块知识沉淀、同步知识更新、全量项目图谱构造、初始化 Wiki。

## 通用 dispatch 方式

所有 sub-agent 统一按以下步骤调度：

1. 在 `prompt` 参数中写入 `Read` 指令，让子 agent 启动后自行加载对应的 prompt 文件。**不要内联** prompt 全文进 prompt 参数。
2. 使用 `Task tool` dispatch `subagent_type: general`，每次仅对应一个 agent 角色。

**prompt 文件路径前缀**：`local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/`。

### 并发 dispatch card-splitter（逐模块）

```
for each module in list:
  Task tool:
    subagent_type: general
    description: "card-splitter ... {module.模块名}"
    prompt: >-
      步骤 1：Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/card-splitter.md 获取完整规则
      步骤 2：按规则处理以下模块——
      模块名：{module.模块名}
      node_type：{module.node_type}
      源码路径：{module.源码路径}
      备注：{module.备注}
```

产物：`local_knowledge/knowledge-card/summary/*.summary.md`，返回实际产出的卡片数量（可能 ≥1）

---

```
读取 summary/ 目录，筛选 status == needs_update 的 summary，并发 dispatch：

for each summary (status == needs_update):
  Task tool:
    subagent_type: general
    description: "card-generator 生成卡片 {summary.name} ({summary.id})"
    prompt: >-
      Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/card-generator.md 获取完整规则，然后处理：{summary.id}
      完成前必须运行自校验：
        python3 local_knowledge/dev-toolkit/skills/knowledge-lifecycle/scripts/validate-mermaid.py local_knowledge/knowledge-card/card/{summary.id}.md
```

产物：`local_knowledge/knowledge-card/card/{id}.md`（summary status 改回 active，update_scope 改为 incremental，Mermaid 图已通过语法校验）

---

## 流程一：知识沉淀

```
用户: "知识沉淀 sport、新增知识模块、生成知识卡片"
```

**产物链路**: card-splitter → card-generator

1. 从 manifest 或已有 summary 查找模块元信息，**dispatch card-splitter**（单次，一个模块）

2. **dispatch card-generator**（`status == needs_update` 的 summary）

3. **合规校验 + 输出摘要**

---

## 流程二：同步知识

```
用户: "同步知识、更新知识、增量知识更新、知识变更"
```

Skill 执行：
  1. 读取 `.lens-config.yaml` 中的 `last_analyzed_commit` 字段
  2. 以 `{上次commit}..HEAD` 作为 diff 范围

**产物链路**: impact-analyzer → card-splitter → card-generator

1. **dispatch impact-analyzer**
   ```
   Task tool:
     subagent_type: general
     description: "impact-analyzer 影响分析"
      prompt: >-
        Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/impact-analyzer.md 获取完整规则，
        diff_range：{上次commit}..HEAD
        summary_dir：local_knowledge/knowledge-card/summary/
        manifest_path：local_knowledge/knowledge-card/architecture/module-source-manifest.md
   ```
   产物：`local_knowledge/knowledge-card/impact-report.json`

2. **读取影响报告**：解析 `impact-report.json`，遍历 `modules[]` 数组，逐模块处理：

   | modules[].operation | 处理 |
   |--------------------|------|
   | `new` | ↓ dispatch architecture-lens 增量模式 |
   | `deleted` | ↓ 清理该模块所有卡片文件 + manifest 行 |
   | `modified` | ↓ 遍历 card_operations，分别处理 update/delete |

3. **dispatch architecture-lens（增量）**：有 `operation=new` 时执行
   ```
   Task tool:
     subagent_type: general
     description: "architecture-lens 增量扫描"
     prompt: >-
       Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/architecture-lens.md 获取完整规则，
       mode: incremental
       candidate_modules: {modules[].candidate_path 列表}
   ```
   产物：`module-source-manifest.md` 追加新模块行

4. **提取新模块信息**：architecture-lens 增量完成后，重新读取 `module-source-manifest.md`，遍历 `candidate_modules` 列表，按 `candidate_path` 匹配 manifest 中各行的 `源码路径` 列，提取匹配行的 `模块名`、`node_type`、`源码路径`、`备注`，作为后续 card-splitter 的输入。

5. **处理模块/卡片删除**：有 `operation=deleted` 或 `card_operations[].action=delete` 时：
   ```
   # 删除模块的下所有卡片
   for each module where operation=deleted:
     rm -f local_knowledge/knowledge-card/summary/{id}.summary.md
     rm -f local_knowledge/knowledge-card/card/{id}.md
     从 module-source-manifest.md 中移除该模块行

   # 删除单张卡片
   for each card_operations where action=delete:
     rm -f local_knowledge/knowledge-card/summary/{summary_id}.summary.md
     rm -f local_knowledge/knowledge-card/card/{summary_id}.md
   ```

6. **dispatch card-splitter（逐模块）**：

   | 条件 | 输入 | action |
   |------|------|--------|
   | `modified` + `card_operations[].action=update` | 模块名 + node_type + 源码路径 + 备注 + change_details | `needs_update` |
   | `modified` + `module_impacts[]` 非空 | 模块名 + node_type + 源码路径 + 备注 | `needs_rescan`（补拆卡） |
   | `new`（lens 增量后） | 模块名 + node_type + 源码路径 + 备注 | 正常拆卡 |

    每个 dispatch 携带各自 change_details（有则写入 summary 的 affected_chapters）。

7. **并发 dispatch card-generator**（`status == needs_update` 的 summary）

8. **合规校验 + 输出摘要**

9. **清理临时文件**：删除 `local_knowledge/knowledge-card/impact-report.json`

---

## 流程三：项目图谱

```
用户: "项目图谱、生成项目图谱、全量项目图谱、生成全景图、全量知识图谱"
```

**产物链路**: architecture-lens → card-splitter → card-generator

1. **dispatch architecture-lens**
   ```
   Task tool:
     subagent_type: general
     description: "architecture-lens 全量架构分析"
     prompt: >-
       Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/architecture-lens.md 获取完整规则，
       输出到 local_knowledge/knowledge-card/architecture/architecture-overview.md
   ```
    产物：`local_knowledge/knowledge-card/architecture/architecture-overview.md`

2. 读取 `module-source-manifest.md`，提取所有模块行。**并发 dispatch card-splitter**（逐模块）

3. **并发 dispatch card-generator**（`status == needs_update` 的 summary）

4. **汇总校验报告**：统计 card-generator 的完成率，确认无遗漏

---

## 流程四：初始化 Wiki

```
用户: "初始化 Wiki、生成Wiki、项目知识库生成"
```

**产物链路**: `summary/*` + `card/*` → `project_config.py` → `_sidebar.md` + `README.md` + Wiki 页面

**前置检测**：执行前检查 `local_knowledge/knowledge-card/summary/` 和 `local_knowledge/knowledge-card/card/` 目录是否存在且有文件。若任一目录为空或不存在，说明前置流程未走，**自动执行「流程三：项目图谱」**，流程三完成后，继续：

1. **dispatch wiki-analyzer**
   ```
   Task tool:
     subagent_type: general
     description: "wiki-analyzer 项目分析"
     prompt: >-
       Read local_knowledge/dev-toolkit/skills/knowledge-lifecycle/prompts/wiki-analyzer.md 获取完整规则，
       任务：全量分析
   ```
   产物：`project_config.py`（模块分组、中文名、依赖拓扑）

2. **运行 generate-wiki.py**
   ```
   Task tool:
     subagent_type: bash
     description: "运行 generate-wiki.py"
     prompt: >
        cd local_knowledge/dev-toolkit/skills/knowledge-lifecycle && python3 scripts/generate-wiki.py
   ```
   产物：`_sidebar.md`、`README.md`、`index.html`

3. **启动 HTTP 服务**
   ```
    cd local_knowledge/knowledge-card && python3 -c "
   import os, yaml, http.server
   config_path = os.path.join(os.getcwd(), 'architecture', '.lens-config.yaml')
   if os.path.exists(config_path):
       with open(config_path) as f:
           config = yaml.safe_load(f)
       wiki_cfg = config.get('wiki', {})
       platform = wiki_cfg.get('current_platform', 'iOS')
       PORT = wiki_cfg.get('ports', {}).get(platform, 8081)
   else:
       PORT = 8081
   class H(http.server.SimpleHTTPRequestHandler):
       def do_GET(self):
           if self.path == '/':
               self.path = '/.wiki/index.html'
           return super().do_GET()
       def end_headers(self):
           self.send_header('Cache-Control','no-cache')
           super().end_headers()
   http.server.HTTPServer(('0.0.0.0', PORT), H).serve_forever()
   "
   ```

4. **提示用户**
    - "Wiki 已生成，端口定义在 architecture/.lens-config.yaml 的 wiki.ports 中"

---

## code_locations 匹配规则

impact-analyzer 使用以下规则匹配变更文件：

- `path` 以 `/` 结尾 → 目录前缀匹配：`changed_file.startsWith(path)`
- `path` 不以 `/` 结尾 → 精确文件匹配：`changed_file === path`

---

## 参数说明

| 参数 | 流程 | 默认值 | 说明 |
|------|------|--------|------|
| 模块名 | 知识沉淀 | 必填 | 模块名称或路径 |
| diff 范围 | 同步知识 | `.lens-config.yaml` 的 `last_analyzed_commit` | 自动取上次分析 commit 到 HEAD |
