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>
89 lines
6.7 KiB
Markdown
Executable File
89 lines
6.7 KiB
Markdown
Executable File
# 公司 AI 知识库 · 项目工作记忆 (OKF Knowledge Base)
|
||
|
||
> 你（CC）现在在公司 AI 知识库根目录。这是一个 **OKF frontmatter + 单一 Git 真相源 + AI 主执行** 的本地知识库。
|
||
> 信条：**单一 Git 真相源 + OKF frontmatter + AI 主执行 + 可生长不重做**。反过度工程：MVP 只做「可溯源 markdown + CC 检索」，编译层(P4)/向量库(P5)按信号延后。
|
||
|
||
## 这是什么
|
||
- **唯一真相源** = 这个 Git 仓库本身（远程家在公司 NAS 的 Gitea）。文件即真相，无 raw/wiki 双层，扁平布局。
|
||
- **前端，同一仓库**：Obsidian 是唯一写路径（编辑 markdown → git push）；飞书是**双向前端**——采集入口（群/kb-link）+ 群机器人问答（读，调 /kb-ask）+ 呈现（云文档+多维表格）。飞书不直接写 Git。
|
||
- **MVP 问答方式**：你直接对 markdown 做目录 + 语义检索回答，**不生成** hot.md/index.md/wiki/（那些 gitignore，P4 才启用）。
|
||
- **采集三通道**：飞书群/文档、NAS 各人投递区（`NAS/<人>/📥知识库投递/`，只扫这个，私人目录不碰）、`/kb-link` 点名任意文件/URL。默认**编译链接**——提炼精华+留 source_link 指针，不搬原件（库不膨胀、原件移动也不丢知识）。
|
||
|
||
## 目录结构
|
||
```
|
||
projects/<代号>/ 项目工作区：_index.md(project) + docs/ decisions/ conversations/ assets/
|
||
_example/ OKF 完整示范（照抄即合规，勿当真实项目）
|
||
company/ 公司基本信息（档案/团队/对外介绍，type: doc）
|
||
learning/ 共享学习知识库，按领域分：ai/ management/ industry/（type: doc）
|
||
entities/ concepts/ questions/ 预留 type 目录（reserved，激活后才用）
|
||
meta/kb-contract.yaml ★唯一机器可读契约（type/字段/enum）
|
||
meta/stats.md 源计数红线观察点
|
||
meta/ingest-manifest.json 摄入去重台账
|
||
tools/ kb-init.sh / kb-lint-fm.py / feishu-pull.py / feishu-render.py / kb-bot/
|
||
docs/ 方案文档 01-12（治理层，改动走 PR+review，见 docs/12）
|
||
```
|
||
|
||
## 硬约束（不可违反）
|
||
1. **type 白名单指向契约，不硬编码**：合法 type / 必填字段 / enum 一律以 `meta/kb-contract.yaml` 为准。当前激活 4 个：`project` `decision` `conversation` `doc`。`entity/concept/question/runbook/metric` 已登记但未激活，用前先改契约 `active: true`。
|
||
2. **每页必带 frontmatter**（除 README/CONVENTIONS/CLAUDE/docs/**/meta/**/assets/**）。硬必填：`type status created ingested`。外部摄入的 doc/decision/conversation 页 `source`+`source_link` 升为必填。
|
||
3. **溯源铁律**：查询回答的**每条结论必挂 source_link**。覆盖不足就明说 Gap，**绝不用训练数据编造**。
|
||
4. **AI 永不擅自有损操作**：删页/解决矛盾/合并/改 type 一律挂起交人。安全项（补可推导字段/建 stub/加 wikilink）可自动做。
|
||
5. **中文目录名禁令**：项目代号用英文/拼音（CC 会把中文编码为 `-` 导致碰撞）。
|
||
6. **人工入口最小化**：人只做「丢资料 + 一句说明 + 对要点点头」。`title/ingested/source/status` 等能推导的字段你自动补齐。
|
||
|
||
## frontmatter 速查（真相在契约文件）
|
||
```yaml
|
||
---
|
||
type: decision # 硬必填，缺失只报不猜
|
||
status: seed # seed/developing/mature，新建默认 seed
|
||
created: 2026-06-20 # 内容产生时间
|
||
ingested: 2026-06-24 # 汇入时间=今天，你自动填
|
||
source: 飞书群 # 外部摄入页必填；enum 见契约
|
||
source_link: https://... # 外部摄入页必填
|
||
title: "..." # 建议，你可从 H1/文件名回填
|
||
tags: [kebab-case]
|
||
timestamp: 2026-06-20 # 可选，信息有效期
|
||
author: 张三 # 可选
|
||
related: ["[[slug]]"] # 可选 wikilink 强边
|
||
---
|
||
```
|
||
|
||
## 命令面 `/kb <verb>`（见 .claude/commands/ 与 docs/07）
|
||
| 命令 | 作用 |
|
||
|---|---|
|
||
| `/kb-new <代号>` | 建项目骨架（= `bash tools/kb-init.sh <代号>`） |
|
||
| `/kb-ingest <代号> <源>` | 录入：Delta去重→落原文→抽要点→写合规页→建 wikilink，矛盾标注挂起不静默覆盖 |
|
||
| `/kb-link <文件/NAS路径/URL>` | 编译链接：点名物料，提炼精华+留 source_link 指针，**不搬原件**；关键易变件才提议快照进 assets/ |
|
||
| `/kb-ask <问题>` | 查询：语义检索 markdown，每条结论挂 source_link，缺口明说 |
|
||
| `/kb-save` | 把对话洞察回写 questions/ 页 |
|
||
| `/kb-check` | frontmatter 校验（= `python3 tools/kb-lint-fm.py`） |
|
||
| `/kb-status` | 源计数 / type 分布 / 红线观察 |
|
||
|
||
## 常用操作
|
||
```bash
|
||
bash tools/kb-init.sh <代号> # 建项目骨架
|
||
python3 tools/kb-lint-fm.py [路径] # frontmatter 体检，退出码非0=需处理（需 pyyaml）
|
||
bash tools/kb-init.sh --stats # 项目数/页数/源数
|
||
python3 tools/feishu-pull.py <代号> --doc <token> # 飞书导出干跑
|
||
python3 tools/feishu-pull.py <代号> --doc <token> --write # 实际落盘
|
||
python3 tools/feishu-render.py --bitable --dry-run # 全库→多维表格呈现（干跑预览）
|
||
python3 tools/feishu-render.py --docs <代号> --dry-run # 项目→飞书云文档（干跑）
|
||
bash tools/kb-bot/subscribe.sh # 起飞书群机器人长连接（收消息）
|
||
python3 tools/kb-bot/handle.py --watch # 消费事件→/kb-ask→回复（常驻在 NAS）
|
||
```
|
||
|
||
## 演进红线（默认不上，等信号）
|
||
- P4 编译层（llm-wiki 全量互链 wiki + hot/index）：触发信号 = `_index` 首读定位失效 + 摄入悖论。
|
||
- P5 向量库：**唯一硬触发** = `~100 源/几百页` + index 首读定位不准。到线前「要不要上 RAG」默认答案 = **不**。向量库只做导航层，type 契约与编译层零改动。
|
||
|
||
## 规则维护（见 docs/12）
|
||
- **物料录入全员参与**；**规则改动**（改 `kb-contract.yaml`/`.claude/commands/`/CONVENTIONS/docs）全员可提 PR，合入需**至少一人 review，不可自审自合**。
|
||
- 改字段必填/enum 前先跑 `kb-lint-fm.py` 扫全库，确认存量页不被误伤；加新 type 走 docs/11 §4 登记流程（契约加条+建目录+飞书加视图）。
|
||
- 处理层(L3)按信号生长，**契约/frontmatter 尽量不动**（上层长、地基稳）。
|
||
|
||
## 部署拓扑（见 docs/10）
|
||
- 仓库家 + 常驻处理（机器人长连接、定时投影）在**公司 NAS**；交互处理（ingest/ask/link）在各人本机读本地 clone。
|
||
- 远程 remote：`http://192.168.0.101:3002/robert/company-kb.git`（NAS Gitea，需内网/VPN）。
|
||
|
||
> 治理文档（docs/、CONVENTIONS.md、README.md、kb-contract.yaml）改动走 PR+review（docs/12），勿随意覆盖。
|