# Knowledge Graph Structure

## 核心隐喻

```
       🌳 知识图谱
       │
       ├── 叶子（summary/）     ← 每个节点的摘要卡片
       │   ├── frontmatter → 节点类型 + 依赖关系
       │   └── 正文 → 核心设计决策
       │
       └── 纹理（card/）        ← 叶子展开的完整知识
            └── Cici 展开的详细内容
```

| 层级 | 目录 | 生产者 | 变更顺序 |
|------|------|--------|---------|
| 叶子（摘要） | `summary/` | lifecycle Skill | **1st** — 先更新摘要 |
| 纹理（卡片） | `card/` | Cici | **2nd** — 再更新卡片 |

**变更规则：** 任何修改，必须按 摘要 → 卡片的顺序更新，不可跳跃。

---

## 树枝定义 — 节点类型体系

节点的类型由它在项目中的角色决定，每个节点有且仅有一种类型。不同类型的节点采用不同的分析策略。

### 1. code（代码模块）

项目中的核心代码，可直接通过 codegraph 分析依赖关系。

| 子类型 | 特征 | 示例 |
|--------|------|------|
| core-service | 被多个业务模块引用的基础服务 | native-channel, app-logger, network-request |
| shared-tool | 工具类/UI 组件库，无业务逻辑 | common-utils, custom-widgets, platform-define |
| business | lib/modules/ 下的独立功能模块 | sport, health, setting |

**分析策略：** codegraph 分析 import、继承、调用关系

### 2. resource（共享资源）

多模块共同引用的资源文件，不包含业务逻辑。

| 子类型 | 特征 | 示例 |
|--------|------|------|
| image | 图片资源 | assets/image/ |
| animation | 动画资源 | assets/animations/ |
| font | 字体 | assets/fonts/ |
| json | 配置文件 | assets/json/ |
| sound | 音频 | assets/sounds/ |
| localization | 多语言文件 | l10n/, local_string/ |

**分析策略：** 文件目录扫描 → 统计规模、命名规范、被哪些模块引用

### 3. devops（构建与部署）

项目的构建、部署、CI/CD 工具链。

| 子类型 | 特征 | 示例 |
|--------|------|------|
| build-script | 构建/打包脚本 | lib/script/ |
| code-gen | 自动生成的代码 | gen/, generated/ |

**分析策略：** 文件清单扫描 + 依赖声明解析

### 4. config（项目配置）

项目级别的配置定义。

| 子类型 | 特征 | 示例 |
|--------|------|------|
| platform | 原生平台配置 | .android/, .ios/, .ohos/ |
| dependency | 外部依赖声明 | pubspec.yaml |

**分析策略：** 配置解析 → 获取关键版本/依赖信息

### 域（domain）规则

域是纯导航分组标签，不设固定层级。每个节点可以有 0 或 1 个 domain：

```
business 类型：按目录名关键词推断
  health / heart / blood / temperature / pressure / sleep / mood / exercise → health
  sport → sport
  watch_ → device
  guard / class_mode → security
  setting / message / photo / time / genius → system
  其余 → generic

其他类型：domain 可选，不强制
  core-service → domain 按功能命名：infrastructure / network / data / ui
  resource → domain 按类型：image / animation / font / json / audio
```

### 关键设计原则

1. **不预设层数** — 项目结构由 codegraph 检测到的依赖关系自然呈现，不强制分层
2. **不同类型不同分析策略** — code 走 codegraph，resource 走扫描，devops 走清单
3. **DAG 而非树** — 代码依赖是多对多的，不强求每个节点只有一个父节点
4. **节点类型固定不变** — 代码模块不会变成配置，资源也不会变成代码

---

## 叶子定义 — summary 的挂载规则

### 挂载条件

每个 summary 的 frontmatter 必须声明 `id`、`node_type` 和 `domain`：

```yaml
id: a1b2c3d4e5f6a789-sport        # 必须：16位UUID前缀-模块名，全局唯一
node_type: business                # 必须：code | resource | devops | config
domain: health/exercise            # 可选：按节点类型匹配域规则
```

### 规则

1. **id 全局唯一** — `id` 的值在所有 summary 中不可重复。格式为 `{16位UUID前缀}-{模块名}`，前缀取 UUID v4 前 16 位，项目初始化时生成一次，后续不变
2. **dependency-graph 使用 summary 的 id 而非 name** — id 稳定不可变，模块重命名不影响已有引用
3. **每个节点有且仅有一个 node_type** — 不能同时是 code 和 resource
4. **骨架叶子** — 没有正文展开的 summary，`status: needs_update`，仍可被引用

### status 流转规则

summary 的 `status` + `update_scope` 字段共同决定 Cici 的触发和策略：

```
card-splitter 写完/更新 summary
  → status = needs_update
  → update_scope = full（新建）| incremental（更新）
  → last_analyzed_commit = HEAD
         │
         ▼
Cici：
  读 status → 不是 needs_update → 跳过
  读 update_scope：
    ├─ full → 全量重写 card（新建卡片时）
    └─ incremental → 保留已有内容，仅更新受影响章节
  改 status = active
```

**触发原则：** Cici 只看 status 和 update_scope。`needs_update` + `full` = 全量重写，`needs_update` + `incremental` = 增量更新。`active` = 跳过。

---

## 纹理定义 — card 与 summary 的关系

1. card 是 summary 的详细展开（100-300 字骨架 → 1500+ 字全文）
2. card 不直接挂到树枝上，通过 summary 的 `id` 字段间接关联
3. card 的内容由 Cici 从 summary + codegraph 源码生成
4. card 的 frontmatter 必须通过 `knowledge-doc-format-rewrite` 校验

```
summary/（叶子）──关联──→ card/（纹理）
```

---

---

## 变更顺序规则

```
代码变更 / 新节点加入
        │
        ▼ 1st
摘要更新 ───────────────────── summary/{node}.summary.md
│  ├─ frontmatter（node_type/domain 对齐）
│  ├─ 骨架节点 → 可由"知识沉淀"展开为完整
│  └─ status: needs_update → 标记为待完整化
│
        ▼ 2nd
卡片更新 ───────────────────── card/{node}.md
   └─ 由 Cici 在"知识沉淀"流程中执行
```

---

## 验证规则

| # | 规则 | 违反后果 |
|---|------|---------|
| 1 | 每个 summary 必须有 `node_type` | 无法确定分析策略，应在 card-splitter 阶段自动补齐 |
| 2 | `node_type` 值必须是 `code` / `resource` / `devops` / `config` 之一 | 非法值应在 card-splitter 阶段修正 |
| 3 | `id` 必须符合 `{16位UUID前缀}-{模块名}` 格式且全局唯一 | id 冲突导致引用歧义 |
| 4 | card 必须有 `summary_id` 字段，值与对应 summary 的 `id` 一致 | 知识图谱断链 |
