extract-concepts

name	extract-concepts
description	当需要理解模块的核心概念、领域术语、概念关系、或命名规范时使用。读取结构地图，逐模块提取概念术语文档。

Extract Concepts — 概念术语提取

读取结构地图，逐模块提取概念术语文档。

`{KB_DATA_ROOT}/raw//_map.md` 必须存在（由 scan 技能产出）。如果没有，先调用 scan 技能。

输入

参数	必填	默认值	说明
--target <path>	是	-	目标代码库路径
--project <name>	是	-	项目名称
--module <name>	否	全量	只分析指定模块
--kb-data-root <path>	否	插件 data 目录绝对路径	数据根目录

前置条件

• {KB_DATA_ROOT}/raw/<project>/_map.md 必须存在

输出

• {KB_DATA_ROOT}/raw/<project>/concepts/_index.md（带 frontmatter 的索引）
• {KB_DATA_ROOT}/raw/<project>/concepts/modules/<module>.md（每个模块一份概念术语文档）

反模式

想法	问题
"术语表只列生僻词就行"	领域常见词对新人同样是障碍，术语表需全量覆盖
"概念关系凭经验画"	概念关系必须有代码证据支撑，凭经验推断会产生错误关联
"命名规范从 README 抄"	README 可能过时，必须从实际代码提取命名模式
"概念层次按目录结构来"	目录结构是组织视角，概念层次是抽象视角，两者经常不一致

执行流程

1. 读取 _map.md，获取模块清单
2. 如果指定了 --module，只分析该模块；否则分析所有模块
3. 对每个模块： a. 扫描核心代码文件（模型定义、常量声明、类型别名、配置结构） b. 提取术语定义（领域术语、缩写、行话） c. 识别核心概念（关键抽象、设计模式、领域实体） d. 构建概念关系（依赖、组合、继承、关联） e. 提取命名规范（变量命名模式、函数命名约定、缩写表） f. 识别概念演进（废弃术语、重命名历史、版本间概念变化） g. 生成 Mermaid 概念关系图和概念层次图 h. 生成概念术语文档，写入 concepts/modules/<module>.md
4. 生成 concepts/_index.md（概念清单 + 跨模块概念关系图 + frontmatter）

_index.md frontmatter

---
project: <project>
dimension: concepts
date: YYYY-MM-DD
status: unprocessed
tags: [...]
---

模板

每份概念术语文档必须包含以下章节：术语表（表格：术语 | 英文对照 | 定义 | 首次出现位置，按字母排序）、核心概念（定义 + 角色 + 代码路径 + Mermaid 图）、概念层次（Mermaid 层次图）、命名规范（模式 + 约定 + 缩写表）。

关键原则

• 概念必须有代码证据： 每个核心概念必须关联到具体的代码路径，不接受无代码支撑的纯理论概念
• 术语表需全量覆盖： 所有领域特定术语都必须收录，包括看似常见的词——对新成员而言没有"显而易见"的术语
• 概念层次是推断： 概念的抽象层次基于代码中的使用模式推断，可能与设计者意图不一致，后续 Transform 可修正

质量约束

• 每个模块文档至少 2 张 Mermaid 图（概念关系图 + 概念层次图）
• 术语表必须表格形式（术语 | 英文对照 | 定义 | 首次出现位置）
• 每个核心概念必须有代码路径
• 每个模块文档至少 1 张对比表格

验收标准

交付前逐项勾选，P0 未满足必须补充：

P0 — 必含章节

• 术语表（表格形式，按字母排序）
• 核心概念（定义 + 角色 + 代码路径 + Mermaid 图）
• 概念层次（Mermaid 层次图）
• 命名规范（模式 + 约定 + 缩写表）

P1 — 深度

• ≥ 2 张 Mermaid 图
• 术语表为表格形式
• ≥ 1 张对比表格