84f7950589
- 完整的知识库框架（P0-P5 路线图） - 12篇治理文档 - 工具脚本（kb-init.sh, kb-lint-fm.py, feishu-sync.py, kb-bot） - 7个 Claude 命令 - 示例项目和测试项目（wanniu-l1） - 契约文件（meta/kb-contract.yaml） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
182 lines
13 KiB
Markdown
Executable File
182 lines
13 KiB
Markdown
Executable File
# 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/字段一律禁止——读契约文件。
|