# 06 · 工具链

> 三档工具清单：立即复用 / 立即轻量自建 / 未来再建。附各脚本用途与 gitignore 策略。
> 反过度工程：MVP 只落地「立即」两档，未来档按信号触发。

---

## 【立即复用】现成能力，零自建

| 工具 | 用途 | MVP 边界 |
|---|---|---|
| **llm-wiki SKILL** (`~/.claude/skill-repository/pkm-suite/llm-wiki/SKILL.md`) | 其 lint 检查项、Delta Check、hot cache 模式作参考 | **MVP 仅借用查询/lint 思路**，全量 raw→wiki 编译 P4 才启用 |
| **Git** | 版本 = 审计 + 冲突仲裁 + 回滚 | 唯一同步与真相源机制 |
| **Obsidian** | 直接打开 `公司AI/` 当 vault，零镜像 | wikilink/图谱浏览；不用 Obsidian Git 插件自动提交 |
| **CC 文件系统检索** | MVP 默认问答方式（`cd` 进目录直接语义检索 markdown） | 不生成 index/hot/wiki，直接对 markdown 检索 |

---

## 【立即轻量自建】P0 落地

### `CLAUDE.md`（项目级）
让 CC 感知库结构 / type / frontmatter / 溯源硬约束。type 白名单**指向契约文件不复制清单**。

### `tools/kb-init.sh`
一键幂等建 `projects/<代号>/` 骨架：
- 建 `_index.md`（`type: project` + `status: seed`）+ `docs/` `decisions/` `conversations/` `assets/` 子目录。
- 幂等：已存在不覆盖。
- 目录布局与 `docs/04-架构.md` 一致。

### `tools/kb-lint-fm.py`
frontmatter 校验器：
- **PyYAML 解析**（正确解析 `related`/`tags` 列表，不用正则）。
- **读 `meta/kb-contract.yaml`** 判定 type 白名单 + 必填矩阵 + status/source enum，**不硬编码**。
- 退出码非 0 供 CC 判定；输出分级（阻断 / 提示）。
- 检查项见 `CONVENTIONS.md` §6。

### `tools/feishu-pull.py`
飞书半自动单向导出：
- **凭据走环境变量，不入库**。
- 拉取飞书文档 → 落 `projects/*/docs/`。
- AI 自动补 `title`/`ingested`/`source`/`source_link`。
- 单向（飞书→仓库），**不写回飞书**。

### `.claude/commands/`
`/kb *` 薄封装（命令表见 `docs/07-AI-native工作流.md`，此处引用不复述）：
`/kb-new` `/kb-ingest` `/kb-ask` `/kb-save` `/kb-check` `/kb-status`。

---

## 【未来再建】按信号触发，不预建

| 工具 | 触发信号 | 说明 |
|---|---|---|
| **llm-wiki 全量编译层** | P4（`_index` 首读失效 + 摄入悖论） | raw→wiki 全量编译，产物单一执行者生成 |
| **向量库导航层** | P5 红线（~100 源/几百页 + index 定位不准） | 仅做「找到相关页」，编译层零改动 |
| **飞书机器人查询入口** | 非 CC 消费方出现 | 飞书内直接问答 |
| **多维表格录入** | 结构化录入需求 | 飞书多维表格 → 仓库 |
| **MCP server** | 出现非 CC 消费方 | 对外暴露知识库接口 |

> **默认答案是「不」**：任何「要不要上 RAG / 编译 / MCP」的默认答案是「不」，直到对应信号出现。

---

## gitignore 策略汇总

| 类别 | 入 Git | 说明 |
|---|---|---|
| markdown 知识页 + frontmatter | ✅ | 真相源 |
| `_index.md` | ✅ | 项目门户锚点 |
| `meta/kb-contract.yaml` / `stats.md` / `ingest-manifest.json` | ✅ | 契约 + 台账 |
| `tools/*` | ✅ | 脚本 |
| `hot.md` / `log.md` / `index.md` / `wiki/` | ❌ | 生成产物，本地按需重建；消除并发冲突 |
| `.obsidian/` | ❌ | gitignore，插件清单在 `docs/obsidian-setup.md` |
| `.trash/` | ❌ | Obsidian 回收站 |
| 大体积 assets | ❌ | 超阈值不入库 |
| 凭据 / `.env` | ❌ | 走环境变量，绝不入库 |

详见 `docs/04-架构.md` §3。