# 04 · 架构

> 本文是知识库物理形态与数据流的权威描述。目录布局以此为准，`tools/kb-init.sh` 与 `CONVENTIONS.md` 必须与之一致。
> 核心信条：**单一 Git 真相源 + OKF frontmatter + AI 主执行 + 可生长不重做**。

---

## 1. 四层架构

知识从产生到被消费，流经四层。每层职责单一，层间靠**文件 + frontmatter**解耦，不靠数据库或服务。

```
┌──────────────────────────────────────────────────────────────┐
│ L4 呈现层  Presentation                                        │
│   Obsidian（个人主编辑器·wikilink·图谱） + 飞书（公司呈现）      │
│   CC 问答（cd 进目录语义检索，MVP 默认查询方式）                 │
├──────────────────────────────────────────────────────────────┤
│ L3 处理层  Processing（MVP 极薄，按信号生长）                   │
│   kb-lint-fm.py 校验 · CC 语义检索 · Delta Check 去重           │
│   [P4 触发] llm-wiki 全量编译：raw markdown → 互链 wiki+hot+index│
│   [P5 红线] 向量库仅作导航层，替代 index.md                     │
├──────────────────────────────────────────────────────────────┤
│ L2 汇聚层  Aggregation ★唯一真相源★                            │
│   公司AI/ Git 仓库 · 扁平 projects/ 布局 · 每页带 OKF frontmatter│
│   文件本身即真相，无 raw//wiki/ 双层，无中间数据库               │
├──────────────────────────────────────────────────────────────┤
│ L1 采集层  Collection                                          │
│   人工丢资料（Obsidian 直接写） · feishu-pull.py 半自动导出      │
│   本地/NAS 文件 · 会议记录 · 聊天摘录                            │
└──────────────────────────────────────────────────────────────┘
```

**各层要点：**

- **L1 采集层**：知识入口。唯一强人工动作是「点名物料 + 一句说明」。三条采集通道（见下）汇入同一真相源。飞书文档经 `tools/feishu-pull.py` 半自动单向导出流入 `projects/*/docs/`；个人手记直接在 Obsidian 里写。凭据走环境变量，不入库。

  **三条采集通道：**

  | 通道 | 适合物料 | 方式 | 落成 |
  |---|---|---|---|
  | 飞书群/文档 | 对话、临时决策、协作文档 | `feishu-pull.py`（P2） | `conversation`/`doc` |
  | NAS 各人投递区 | 文件类（PDF/Word/Excel/扫描件） | 点名或投递区扫描 | `doc`+可选 `assets` |
  | 工作目录/URL 点名 | 任意单个文件/链接 | `/kb-link` 编译链接 | `doc`/`decision` |

  **「编译过的链接」模型（核心，抗膨胀+抗失联）**：默认**不把原件搬进库**。人点名一个物料（工作目录文件 / NAS 路径 / URL），AI 读一遍→提炼精华写成一页知识→页面留 `source_link` 指向原件。好处：①库只存提炼后 markdown，不膨胀；②精华进库可检索可溯源；③原件日后移动/删除，提炼的知识仍在（纯快捷方式做不到）。少数关键且易变的原件，AI 提议、用户点头后才复制进 `assets/` 兜底。

  **NAS 投递区（每人各自）**：`NAS/<同事>/📥知识库投递/`——AI 只扫这个专用子目录，**私人工作目录永不主动触碰**（隐私隔离 + 噪音从源头掐掉）。投递区跟各自 NAS 同步走，不新增基建。MVP 按需扫描，不做常驻监听 daemon（过度工程，投递频繁再说）。
- **L2 汇聚层（真相源）**：整个体系的地基。就是 `公司AI/` 这个 Git 仓库本身。**文件即真相源**——没有 raw/ 和 wiki/ 双层，没有中间数据库。每个知识页顶部有 OKF frontmatter（见第 2 节 schema，唯一契约在 `meta/kb-contract.yaml`）。版本、审计、冲突仲裁、回滚全靠 Git。
- **L3 处理层（MVP 极薄）**：MVP 阶段只有 `kb-lint-fm.py`（校验）+ CC 直接对 markdown 做目录/语义检索 + Delta Check 去重。**不生成** `hot.md`/`log.md`/`wiki/` 等导航产物。llm-wiki 全量编译到 **P4** 才启用，向量库到 **P5 红线**才上。
- **L4 呈现层**：三个视图共享同一真相源。Obsidian 是个人主编辑器，飞书是公司**双向前端**（采集入口 + 群问答查询 + 呈现面），CC 是问答入口。飞书呈现走**双载体**：云文档（叙事型：项目概览/决策）+ 多维表格 Bitable（结构型：全库可筛选/看板）。群机器人问答是**读**操作（调 `/kb-ask`），不构成第二条写路径。详见 `docs/08-飞书双向前端方案.md`。

---

## 2. 扁平目录树

```
公司AI/                          # Git 根 = 唯一真相源
├── README.md                    # 总索引 + 快速上手
├── CLAUDE.md                    # CC 项目级工作记忆
├── CONVENTIONS.md               # 录入宪法（引用 kb-contract.yaml）
├── .gitignore                   # .obsidian/ .trash/ 生成产物 大 assets
│
├── docs/                        # 方案文档
│   ├── 01-方案总览.md            # 【不动】
│   ├── 02-首个闭环-项目资料.md    # 【不动】
│   ├── 03-知识库框架选型调研.md    # 【不动】
│   ├── 04-架构.md               # 本文
│   ├── 05-路线图.md
│   ├── 06-工具链.md
│   ├── 07-AI-native工作流.md
│   └── obsidian-setup.md        # 共享插件清单
│
├── meta/
│   ├── kb-contract.yaml         # ★唯一机器可读契约：type 集 + 必填矩阵 + enum
│   ├── ingest-manifest.json     # 摄入 hash 台账（去重）
│   └── stats.md                 # 源计数/页数（红线观察点）
│
├── projects/                    # 项目知识（首个闭环即用）
│   ├── _example/                # OKF 完整示例，照抄即合规
│   │   ├── _index.md            # type: project
│   │   ├── docs/                # type: doc
│   │   ├── decisions/           # type: decision
│   │   ├── conversations/       # type: conversation
│   │   └── assets/              # 原始附件（唯一免 frontmatter 目录）
│   └── <代号>/ ...              # 英文/拼音代号，禁纯中文目录名
│
├── entities/                    # type: entity（reserved，首次真实需要时建）
├── concepts/                    # type: concept（reserved）
├── questions/                   # type: question（reserved，查询回写）
│
├── tools/
│   ├── kb-init.sh               # 建项目骨架
│   ├── kb-lint-fm.py            # frontmatter 校验（读 kb-contract.yaml）
│   └── feishu-pull.py           # 飞书半自动导出
│
└── .claude/commands/            # /kb-new /kb-ingest /kb-ask /kb-save /kb-check /kb-status
```

**布局裁决要点：**

- **扁平 `projects/`**，不建 `raw//wiki/` 双层。文件本身即真相源。
- **免 frontmatter 目录**：`assets/`（原始附件）；仓库脚手架 `README.md`/`CONVENTIONS.md`/`docs/*`。
- **禁纯中文目录名**：项目代号用英文/拼音（CC 会把中文编码为 `-` 导致 ID 碰撞）。
- **reserved type 目录**（`entities/`/`concepts/`/`questions/`）首次真实需要时才建，激活即在 `kb-contract.yaml` 标记 active。

---

## 3. gitignore 与生成产物策略

编译/导航产物**不进 Git**，本地按需由 CC 重建 → 消除多人并发合并冲突。

| 类别 | 是否入 Git | 说明 |
|---|---|---|
| markdown 知识页 + frontmatter | ✅ | 真相源，全部提交 |
| `_index.md`（项目门户，人写/CC 维护） | ✅ | 项目导航锚点 |
| `meta/kb-contract.yaml` / `stats.md` | ✅ | 契约与观察点 |
| `hot.md` / `log.md` / `wiki/`（全库导航产物） | ❌ | gitignore，本地按需重建；P4 起由**单一执行者**生成并提交 |
| `index.md`（全库索引） | ❌ | 同上 |
| `.obsidian/` | ❌ | gitignore，插件清单共享在 `docs/obsidian-setup.md` |
| `.trash/` | ❌ | Obsidian 回收站 |
| 大体积 assets（视频/大图/二进制） | ❌ | 按需，超阈值不入库 |

> **杀掉合并冲突磁石**：`_index.md` 之外的全库导航（`hot.md`/`log.md`/`wiki/`/`index.md`）不进 Git。MVP 阶段 CC 直接对 markdown 做检索，根本不生成这些文件。

---

## 4. 双前端映射

两个前端物理坐在**同一个 Git 仓库** `公司AI/`，是同一真相源的两种视图。**MVP 只有一条写路径**（避免两个前端同时写 Git 起冲突）。

| 前端 | 角色 | 读 | 写 |
|---|---|---|---|
| **Obsidian** | 个人主编辑器 | 直接把 `公司AI/` 当 vault 打开，wikilink/图谱浏览 | **唯一写路径**：直接编辑 markdown → `git push` |
| **飞书** | 公司双向前端 | 全员看项目概览/决策（云文档+Bitable）；群 @机器人 问答 | **不直接写库**：文档经 `feishu-pull.py` 单向导入；群问答是读操作（`/kb-ask`），不写库 |
| **CC** | AI 问答与自动化执行 | `cd` 进目录语义检索 | 录入/回写循环产出合规 markdown（受 lint 约束） |

- `.obsidian/` **gitignore**，共享插件清单在 `docs/obsidian-setup.md`（装 Dataview）。Git 同步交给 CC/命令行，**不用** Obsidian Git 插件自动提交。
- **个人草稿隐私边界**：个人未定稿走各自**本地 vault（不入共享仓）**；经一次轻量评审晋升后，文件才移入 `projects/`/`entities/`，`source` 记晋升来源。公司仓无 `personal/` 分区。
- **删除**（对 5 人是重型基建）：飞书双向 API、机器人写回 `conversations/`、双前端一致性校验脚本。

---

## 5. 下游消费接口

知识库对下游 agent / 工具的暴露接口，全部基于文件系统，无需服务：

1. **文件系统接口**：任何 agent `cd` 进 `公司AI/` 即可 grep/read markdown。这是最低层、最稳定的接口。
2. **frontmatter 过滤接口**：下游按 `type`/`status`/`tags`/`source` 过滤页面（例：只喂 `type: decision && status: mature` 给报价 agent）。契约在 `meta/kb-contract.yaml`，生产者与消费者依赖同一契约。
3. **CC 子 agent 接口**：主 CC 派生子 agent 做检索/编译/校验，子 agent 读同一真相源，结论必带 `source_link` 溯源。
4. **溯源锚点**：每页 `source` + `source_link` 是所有下游答案的强制溯源依据——**无据即报 Gap，绝不用训练数据编造**。

> 未来出现**非 CC 消费方**时再建 MCP server；出现 P5 红线时向量库只做「找到相关页」的导航层，type 契约与编译层原样保留。

---

## 6. 演进阶梯（架构如何生长）

架构分阶段生长，**后阶段是生长而非重做**；frontmatter/type 契约从 P0 到 P5 稳定不变。

| 阶段 | 架构增量 | 触发信号 |
|---|---|---|
| **P0** | L2 真相源物理形态定死 + `kb-contract.yaml` + 命令雏形 | 照规范建页、`/kb-check` 通过、CC 能读并引用 |
| **P1** | 首个项目全汇入，L3 仅 lint + CC 检索 | 该项目问答稳定，产生复制需求 |
| **P2** | L1 加 `feishu-pull.py` 半自动增量导入 | 项目数 ≥3，飞书成主要文档源 |
| **P3** | L2 加 `company/`/`domains/` 分区，Obsidian 成团队习惯 | 库覆盖主要知识，产生编译/喂 agent 需求 |
| **P4** | L3 启用 llm-wiki 全量编译（互链 wiki + hot/index），下游 agent 消费接口 | **`_index` 首读定位失效 + 摄入悖论显现** |
| **P5** | L3 加向量库导航层（仅替代 index.md，编译层零改动） | `~100 源/几百页` + index 首读定位不准/摄入悖论 |

> **P5 向量库红线（唯一硬触发点）**：在 `~100 源/几百页` 且出现 `index 首读定位不准`/`摄入悖论` 之前，坚决不上向量库/RAG——任何「要不要上 RAG」的默认答案是「不」。详见 `docs/05-路线图.md`。

---

## 附：架构层面的单一真相源

| 契约 | 唯一存放处 | 谁读它 |
|---|---|---|
| type 集 + 字段必填矩阵 + enum | `meta/kb-contract.yaml` | kb-lint-fm.py 运行时读 |
| 目录布局 | 本文 `docs/04-架构.md` | kb-init.sh / CONVENTIONS 与之一致 |
| 溯源锚点 | 每页 `source`/`source_link` | 所有下游 agent 答案必带 |

任何脚本硬编码 type/字段一律禁止——读契约文件。