# Knowledge Compiler

> 将知识材料编译为结构化 Wiki。AI 即编译器，Markdown-in Markdown-out，覆盖度追踪，增量编译。

- Skill: `shetengteng/knowledge-compiler` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add shetengteng/knowledge-compiler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shetengteng/knowledge-compiler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: shetengteng (https://skillmd.com/u/shetengteng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shetengteng/knowledge-compiler

---


# Knowledge Compiler

将团队知识材料（设计文档、架构决策、技术调研、会议纪要）编译为结构化 Wiki，让人和 AI 都能高效使用。

**核心理念**：AI 即编译器 — 读取本文件的指令，扫描文件、分类主题、生成 Wiki 文章。纯 Markdown，零代码，零依赖。

## 跨平台兼容

本 Skill 兼容所有支持读取 Markdown 指令的 AI IDE：
- **Cursor**：作为 Skill 安装，AI 读取 SKILL.md 及引用文件执行
- **Claude Code**：作为 Skill 或 AGENTS.md 引用使用
- **Codex**：作为 Skill 读取，AI 按指令执行

所有命令的详细步骤存储在本目录的 `.md` 文件中（见下方命令路由表）。AI 读取对应文件后自行执行，不依赖任何 IDE 特定的命令注册机制。

## 命令路由

当用户表达以下意图时，读取对应的指令文件并按步骤执行：

| 用户意图 | 指令文件 | 说明 |
|---------|---------|------|
| "kc init" / "初始化知识库" | [commands/kc-init.md](commands/kc-init.md) | 创建源目录 + wiki/ + 配置 |
| "kc add" / "添加材料" | [commands/kc-add.md](commands/kc-add.md) | 添加文件到源目录 |
| "kc compile" / "编译" / "compile" | [commands/kc-compile.md](commands/kc-compile.md) | 编译 Wiki（增量/全量/预览） |
| "kc query" / "问一下" / "查知识库" | [commands/kc-query.md](commands/kc-query.md) | 基于 Wiki 回答问题 |
| "kc lint" / "健康检查" / "检查质量" | [commands/kc-lint.md](commands/kc-lint.md) | Hard/Soft Gate 检查 |
| "kc status" / "知识库状态" | [commands/kc-status.md](commands/kc-status.md) | 统计、覆盖度、过期概览 |
| "kc browse" / "浏览知识库" | [commands/kc-browse.md](commands/kc-browse.md) | 知识地图浏览 |

编译命令内部调用 [skills/wiki-compiler.md](skills/wiki-compiler.md) 执行 5 阶段管道。

## 编译管道概览

```
Phase 1: Scan    — 读 .compile-state.json，对比源文件 mtime，找出 new/changed/deleted
Phase 2: Classify — 读标题+前500字，推断 topic slug，匹配已有概念
Phase 3: Compile  — 读全文，生成/更新概念文章，标记覆盖度，标注来源
Phase 3.5: Schema — 首次生成 / 增量更新 schema.md
Phase 4: Index    — 更新 INDEX.md + Hard Gate 验证
Phase 5: State    — 更新 .compile-state.json + log.md
```

详细管道指令见 [skills/wiki-compiler.md](skills/wiki-compiler.md)。

## 知识库目录结构

```
{project}/
├── .kc-config.json              # 配置
├── .compile-state.json          # 编译状态（mtime 快照）
├── {sources}/                   # 源目录（只读约定，默认 raw/，也可使用 doc/、design/ 等已有目录）
│   ├── designs/                 # ← 使用默认 raw/ 结构时的子目录
│   ├── decisions/
│   ├── research/
│   └── notes/
└── wiki/                        # 编译产物
    ├── INDEX.md                 # 概念索引（分类 + 覆盖度）
    ├── schema.md                # 结构契约（分类 + 命名规则 + 交叉引用）
    ├── log.md                   # 编译日志
    ├── concepts/
    │   └── {topic-slug}.md      # 概念文章（frontmatter + 覆盖度标记）
    └── analyses/
        └── {date}-{slug}.md     # 保存的查询分析（kc query --save 产物）
```

## 覆盖度标记

| 级别 | 含义 | AI 行为 |
|------|------|---------|
| high | 多个一致来源 | 直接引用 |
| medium | 单一来源 | 引用但标注"可能需补充" |
| low | 推断或稀疏 | 自动回查源目录中的原始文件 |

详细说明见 [references/coverage-tags.md](references/coverage-tags.md)。

## 输出语言

配置 `.kc-config.json` 中的 `language`：

| 值 | 含义 |
|----|------|
| `zh` | 中文（默认）— 文章正文、章节标题、摘要均为中文 |
| `en` | English — 正文和章节标题切换为英文（按 wiki-compiler.md 中的映射表） |

**检索字段语言策略：** `summary`、`tags`、`answers` 固定使用项目主语言（即 `language` 配置值），不做跨语言混合。这确保 AI 检索时语义匹配一致。YAML frontmatter key 始终为英文。

## 会话模式

配置 `.kc-config.json` 中的 `session_mode`：

| 模式 | 行为 |
|------|------|
| staging | Wiki 可用，按需查阅 |
| recommended | 先读 Wiki 再读原始文件 |
| primary | Wiki 为主，low 覆盖才看源目录 |

进入含 `.kc-config.json` 的目录时自动识别，未找到则静默退出。

## 质量保障

采用 Hard/Soft Gate 分级验证，详见 [references/quality-gates.md](references/quality-gates.md)。

- **Hard Gates**（必须通过）：frontmatter 完整、覆盖度标记、来源引用有效、schema 一致、非空内容
- **Soft Gates**（警告不阻断）：孤立概念、低覆盖集群、过期文档、内容矛盾、断裂链接

## 交互原则

编译过程中 AI **必须在不确定时暂停并向用户确认**，不可擅自决定：
- 主题归属不明确（一个文件可能属于多个主题）
- 新主题与现有主题名称相近（合并还是新建）
- 源文件之间存在矛盾
- 用户手动编辑与新源冲突
- Hard Gate 失败且无法自动修复

详细的确认场景和规则见 [skills/wiki-compiler.md](skills/wiki-compiler.md) 的"交互式确认"章节。

## AI 渐进式披露协议

生成的知识库面向 AI 消费。AI 按以下层级逐步深入，避免一次性读取所有内容：

```
Layer 0: .kc-config.json           → 知识库是否存在、源目录、语言、模式
Layer 1: wiki/INDEX.md Registry    → Topic Registry 表，包含 summary/tags/answers（首轮召回）
Layer 2: wiki/concepts/*.md        → 仅读 YAML frontmatter 做精筛
Layer 3: wiki/concepts/*.md        → 读完整文章正文
Layer 4: 源目录中的原始文件          → 仅在 low 覆盖或需要验证时读取
```

**规则：**
1. **Layer 1 是入口**。AI 收到知识相关问题时，**先读 INDEX.md 的 Topic Registry**。Registry 包含每个 topic 的 summary/tags/answers，足够做首轮召回。
2. **Layer 2 做精筛**。仅对 Layer 1 召回的候选 topic，读取 frontmatter 确认相关性。
3. **Layer 3 按需读取**。只读与问题相关的 1-2 篇文章正文，优先读 high/medium 覆盖度的章节。
4. **Layer 4 最后手段**。仅在 low 覆盖度章节不足以回答时才读原始文件。

**Frontmatter 快速匹配字段：**
- `summary`：2-3 句概述，AI 据此判断文章是否与问题相关
- `tags`：关键词列表，用于语义匹配
- `answers`：该文章能回答的典型问题列表，AI 据此做精准路由

## 核心约定

1. **AI 是编译器**：不运行外部脚本，AI 读取指令文件后自己执行所有步骤
2. **源目录不可变**：编译器永远不修改源目录下的文件
3. **人机共维**：用户手动编辑的内容在重编译时保留
4. **按需加载**：AI 只在需要时读取对应的指令文件和参考文档，避免一次性加载所有内容
5. **不确定则问**：遇到歧义时暂停向用户确认，不擅自选择
6. **Mermaid 图表**：架构类、流程类、状态机类 topic 推荐包含 mermaid 图表；概念类和配置类不强制

## Skill 文件结构

```
skills/knowledge-compiler/
├── SKILL.md                      # 本文件（入口 + 命令路由）
├── commands/                     # 命令指令（AI 读取后执行）
│   ├── kc-init.md
│   ├── kc-add.md
│   ├── kc-compile.md
│   ├── kc-query.md
│   ├── kc-lint.md
│   ├── kc-status.md
│   └── kc-browse.md
├── skills/
│   └── wiki-compiler.md          # 5阶段编译管道（核心逻辑）
├── templates/                    # 生成内容时使用的模板
│   ├── article.md
│   ├── schema.md
│   └── index.md
└── references/                   # 详细规范（按需加载）
    ├── quality-gates.md
    └── coverage-tags.md
```