shetengteng 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 | 创建源目录 + wiki/ + 配置 |
| "kc add" / "添加材料" | commands/kc-add.md | 添加文件到源目录 |
| "kc compile" / "编译" / "compile" | commands/kc-compile.md | 编译 Wiki（增量/全量/预览） |
| "kc query" / "问一下" / "查知识库" | commands/kc-query.md | 基于 Wiki 回答问题 |
| "kc lint" / "健康检查" / "检查质量" | commands/kc-lint.md | Hard/Soft Gate 检查 |
| "kc status" / "知识库状态" | commands/kc-status.md | 统计、覆盖度、过期概览 |
| "kc browse" / "浏览知识库" | commands/kc-browse.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。
知识库目录结构
{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。
输出语言
配置 .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。
- Hard Gates（必须通过）：frontmatter 完整、覆盖度标记、来源引用有效、schema 一致、非空内容
- Soft Gates（警告不阻断）：孤立概念、低覆盖集群、过期文档、内容矛盾、断裂链接
交互原则
编译过程中 AI 必须在不确定时暂停并向用户确认，不可擅自决定：
- 主题归属不明确（一个文件可能属于多个主题）
- 新主题与现有主题名称相近（合并还是新建）
- 源文件之间存在矛盾
- 用户手动编辑与新源冲突
- Hard Gate 失败且无法自动修复
详细的确认场景和规则见 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 覆盖或需要验证时读取
规则：
- Layer 1 是入口。AI 收到知识相关问题时，先读 INDEX.md 的 Topic Registry。Registry 包含每个 topic 的 summary/tags/answers，足够做首轮召回。
- Layer 2 做精筛。仅对 Layer 1 召回的候选 topic，读取 frontmatter 确认相关性。
- Layer 3 按需读取。只读与问题相关的 1-2 篇文章正文，优先读 high/medium 覆盖度的章节。
- Layer 4 最后手段。仅在 low 覆盖度章节不足以回答时才读原始文件。
Frontmatter 快速匹配字段：
summary：2-3 句概述，AI 据此判断文章是否与问题相关tags：关键词列表，用于语义匹配answers：该文章能回答的典型问题列表，AI 据此做精准路由
核心约定
- AI 是编译器：不运行外部脚本，AI 读取指令文件后自己执行所有步骤
- 源目录不可变：编译器永远不修改源目录下的文件
- 人机共维：用户手动编辑的内容在重编译时保留
- 按需加载：AI 只在需要时读取对应的指令文件和参考文档，避免一次性加载所有内容
- 不确定则问：遇到歧义时暂停向用户确认，不擅自选择
- 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