# card-generator 设计文档

## 概述

card-generator 负责将 card-splitter 产出的 summary（知识摘要）扩展为完整的知识卡片（card），是知识蒸馏的核心执行层。

## 核心原则

### 入口唯一信号 — summary status

card-generator **只看 status**，不看 diff、时间戳或其他信号：

```
status == needs_update → 继续执行
status == active       → 跳过，直接返回
```

### 回填 key_classes

card-generator 在生成卡片的同时，回填 summary 的 `key_classes` 字段。

| 字段 | 回填方式 |
|------|---------|
| `key_classes` | codegraph/glob 扫描源码，提取对外暴露的公开类/接口（Activity/Service/Component/Provider/Manager/Engine/公共接口），不含内部 Bean/Adapter/Util/Handler/Impl |

该字段由 card-splitter 留空（`[]`），由 card-generator 一次性回填完成。

## 输入/输出

| | 路径 |
|--|------|
| **输入** | `local_knowledge/knowledge-card/summary/{id}.summary.md` |
| **输出** | `local_knowledge/knowledge-card/card/{id}.md` |
| **回填** | 修改 summary 的 `key_classes`、`status`、`update_scope` |

### 输入字段依赖

| summary 字段 | card-generator 是否需要 | 说明 |
|-------------|------------------------|------|
| id | 是 | 写入 card 的 summary_id |
| name | 是 | 推断中文标题 |
| module | 否 | card-generator 不关心 |
| node_type | 是 | 影响卡片分类 |
| domain | 是 | 写入 card frontmatter |
| code_locations | 是 | 确定源码扫描范围 |
| key_classes | 回填目标 | 读取源码后回填 |
| status | 是 | 决定是否执行 |
| update_scope | 是 | 决定全量/增量策略 |

## 工作流程

### 两条路径

```
读 summary
  │
  ├─ status != needs_update → 跳过，直接返回
  │
  └─ status == needs_update
       │
       ├─ update_scope == full
       │    ├─ codegraph 搜索源码补充细节（优先），无 codegraph 时用 grep 兜底
       │    ├─ 按 10 章节范式生成完整卡片
        │    ├─ 提取 key_classes，回填 summary
       │    ├─ 写入 card
       │    └─ 改 summary status = active, update_scope = incremental
       │
       └─ update_scope == incremental
            ├─ 读已有 card
            ├─ 对比 summary 变更，定位受影响章节
            ├─ codegraph 补充细节（优先），重新生成受影响章节
            ├─ 更新 key_classes（如有变化）
            ├─ 未受影响章节原样保留
            ├─ 更新 card 中的 commitId
            └─ 改 summary status = active
```

### 全量生成（full）

1. 读 summary → 确认 status == needs_update，update_scope == full
2. 用 codegraph 搜索源码补充细节（优先），无 codegraph 时用 grep 兜底
3. 按 10 章节范式生成完整卡片
4. 提取对外暴露的公开类/接口，回填 summary 的 `key_classes`
5. 写入 card 时包含 `summary_id` 字段
6. 改 summary status = active，update_scope = incremental
7. 校验 frontmatter

### 增量更新（incremental）

1. 读 summary → 确认 status == needs_update，update_scope == incremental
2. 读已有的 card
3. 检查 summary frontmatter 的 `affected_chapters` 字段：
   - **有值（非空数组）** → 只重写 `affected_chapters` 中指定的章节，其他章节原样保留
   - **无值或空数组** → 对比 summary 正文变更，定位受影响章节后重新生成
4. 用 codegraph 补充细节（优先），无 codegraph 时用 grep 兜底
5. 更新 summary 的 `key_classes`（如有变化）
6. 未受影响的章节原样保留
7. 更新第 10 节中的 commitId
8. 改 summary status = active
9. 校验 frontmatter

## card frontmatter

```yaml
---
doc_id: "K7-{MODULE-ID}"           # 唯一标识
summary_id: {summary.id}            # 关联 summary
knowledge_type: "K7"
title: "{标题}"
description: "{一句话描述}"
status: "active"
scope: "platform"
platforms:
  - "flutter"
domains: "{domain}"
last_analyzed_commit: "{commit}"
---
```

## 正文章节（顺序不可调换）

| # | 章节 | 内容 |
|---|------|------|
| 1 | 功能介绍 | 模块是什么、解决什么问题 |
| 2 | 垂直架构位置 | ASCII 架构图 + 文字说明 + 重点标记本模块 |
| 3 | 模块设计 | Mermaid classDiagram + sequenceDiagram + 设计细节 |
| 4 | 协作模式 | 外部依赖（二方库/三方库/其他模块） + 协作方式表格 |
| 5 | 核心API | 各类的关键 API，表格式详尽列举 |
| 6 | 性能瓶颈 | 模块内可能存在的性能瓶颈及规避方式 |
| 7 | 使用方式 | 日常接入步骤 + 代码示例 + 过程解读 |
| 8 | 使用场景与最佳实践 | 2-4 场景 + 正例 5+ / 反例 5+ |
| 9 | 问题排查 | 表格（问题 / 原因 / 解决）8+ |
| 10 | 参考信息 | 表格（项 / 值）+ 命名约定 + 相关源码路径 |
| | 摘要信息 | 关联 summary 路径 / 摘要ID / commitId / 更新时间 |

## 与 card-splitter 的分工边界

| 职责 | card-splitter | card-generator |
|------|--------------|----------------|
| 目录扫描 & 拆卡 | ✅ 一次性拆解 | ❌ |
| 写 summary frontmatter（id/name/module/node_type/domain/code_locations） | ✅ | ❌ |
| 写 summary 正文（架构要点/核心接口/关键依赖） | ✅ | ❌ |
| 回填 key_classes | ❌ 填 [] | ✅ codegraph 扫描后回填 |

| 生成完整知识卡片（10 章节） | ❌ | ✅ |
| 校验 card frontmatter | ❌ | ✅ |
| 改 summary status | ❌ 设 needs_update | ✅ 改回 active |


## 外部支撑

| 工具 | 用途 |
|------|------|
| codegraph | 主分析引擎，扫描源码补充细节 |
| grep（兜底） | 无 codegraph 时替代 |

## 完成标准

### 正常完成

- card 已写入，含 summary_id
- summary 的 key_classes 已回填
- summary status 已改回 active，update_scope 已改为 incremental
- frontmatter 经过校验
- 10 个内容章节 + 摘要信息完整

### 提前终止

- summary status 不是 needs_update → 直接返回，无操作

## 设计决策

| # | 决策 | 理由 |
|---|------|------|
| 1 | card-generator 每次只处理一张卡 | 单卡单任务，上下文聚焦，避免跨卡混淆 |
| 2 | key_classes 由 card-generator 回填 | card-splitter 不读源码，速度更快；card-generator 本就需要读源码写 10 章节，顺带回填无额外开销 |
| 3 | 全量/增量由 summary.update_scope 控制 | 增量更新避免重写整个 card，节省 token 和时间 |
| 4 | 只依赖 summary，不直接读其他 agent 产物 | 解耦：card-generator 不关心数据是怎么来的 |
