company-kb/docs/04-架构.md

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/字段一律禁止——读契约文件。