company-kb/落地方案.md

公司知识库 · 完整落地方案

从架构到实施的一站式方案：整体框架 + 飞书对接 + 分阶段落地 更新时间：2026-07-16

---

第一部分：整体架构

1.1 这是什么系统？

一个 AI 原生的公司知识库：

• 文件柜（Git 仓库） = 存所有知识，无数据库
• 标签纸（frontmatter） = 每篇文档的元数据，让 AI 快速识别
• AI 管理员（Claude） = 常驻，自动采集、生成、问答

核心理念（4 条铁律）：

1. 单一真相源 = Git 仓库本身，文件即真相
2. 编译过的链接 = 不搬原件，提炼精华 + 留 source_link 指回原文
3. 溯源铁律 = 每条结论必挂原始链接，无据报 Gap，绝不编造
4. AI 权限边界 = 安全项自动做（补字段/建链），有损项挂起交人（删除/合并）

1.2 四层架构

┌────────────────────────────────────────────────┐
│ L4 呈现层  Obsidian编辑 + 飞书展示 + Claude问答   │
├────────────────────────────────────────────────┤
│ L3 处理层  lint校验 + AI语义检索 + 去重           │
├────────────────────────────────────────────────┤
│ L2 汇聚层  Git仓库 + OKF frontmatter ★真相源★    │
├────────────────────────────────────────────────┤
│ L1 采集层  飞书 + NAS投递区 + 手动点名            │
└────────────────────────────────────────────────┘

1.3 目录结构

company-kb/                     # Git 根 = 唯一真相源
├── projects/                   # 项目知识
│   ├── <代号>/                 # 每个项目一个档案盒
│   │   ├── _index.md           # 项目门户 (type: project)
│   │   ├── docs/               # 外部文档 (type: doc)
│   │   ├── decisions/          # 决策记录 (type: decision)
│   │   ├── conversations/      # 聊天沉淀 (type: conversation)
│   │   └── assets/             # 原始附件（免 frontmatter）
│   └── _example/               # 示例项目（照抄即合规）
├── company/                    # 公司基本信息（P3 启用）
├── learning/                   # 共享学习库（ai/management/industry）
├── entities/ concepts/ questions/  # 预留 type（未激活）
├── meta/
│   ├── kb-contract.yaml        # ★唯一契约：type/字段/enum 规则
│   ├── ingest-manifest.json    # 去重台账
│   └── stats.md                # 统计观察点
├── tools/                      # 工具脚本
└── .claude/commands/           # Claude 命令面板 (/kb-*)

1.4 两个核心概念

frontmatter = 文件的"标签纸"

每个 .md 文件顶部用 --- 包起来的元数据：

---
type: decision              # 类型（唯一硬必填）
title: "客户A阶梯定价"       # 标题
description: 因预算分期改用阶梯定价  # 一句话描述
tags: [报价, 客户-a]        # 标签（筛选用）
timestamp: 2026-06-20       # 发生时间
source: 飞书群              # 来源渠道
source_link: https://...    # 原始链接（溯源）
status: mature             # 成熟度 seed/developing/mature
created: 2026-06-20         # 创建时间
ingested: 2026-06-24        # 录入时间
related: ["[[项目门户]]"]   # 关联页面
---

作用：让 AI 先看标签筛选（快、准），再读内容；回答时能挂原文链接（可溯源）。

projects/<代号>/ = 项目档案盒

每个项目一个统一结构的文件夹，所有资料按类型放进对应抽屉（docs/decisions/conversations/assets）。好处：结构统一、AI 友好、照抄即合规。

创建方式：bash tools/kb-init.sh <项目代号>（自动生成骨架 + _index.md）

---

第二部分：现状盘点

2.1 已完成（70%）

组件	完成度	功能	位置
feishu-sync.py	✅ 100%	飞书采集+去重+图片下载+简单frontmatter	飞书同步工具包/
run-sync.sh	✅ 100%	定时任务包装	飞书同步工具包/
安装.command	✅ 100%	一键装环境+配定时任务	飞书同步工具包/
kb-lint-fm.py	✅ 100%	frontmatter 校验器	tools/
kb-init.sh	✅ 100%	项目骨架生成	tools/
kb-contract.yaml	✅ 100%	type/字段/enum 契约	meta/
Claude 命令面板	✅ 100%	7个 /kb-* 命令	.claude/commands/
示例项目	✅ 100%	_example/	projects/

关键：你的 feishu-sync.py 已经把「飞书采集」这一最难的环节做完了——递归拉取、docx转markdown、下载图片、去重、定时任务全有。

2.2 待补全（30%）

组件	状态	工作量	优先级	功能
kb-bridge.py	❌ 不存在	1-2天	P0	飞书markdown → 知识库知识页
Git 仓库部署	❌ 未建	半天	P0	NAS Gitea 真相源
auto-sync.sh	❌ 不存在	半天	P0	整合采集+桥接的定时脚本
nas-watch.py	❌ 不存在	1天	P1	监控投递区自动采集
feishu-render.py	❌ 骨架	2天	P1	推送到飞书多维表格
pre-commit hook	❌ 不存在	半天	P1	Git提交前自动校验

---

第三部分：完整流程图

3.1 采集与处理流程

graph TB
    A1[飞书文档] --> B{采集方式}
    A2[飞书群聊] --> B
    A3[NAS投递区] --> B

    B -->|手动| C1["/kb-ingest命令"]
    B -->|定时自动| C2["feishu-sync.py<br/>每天10:00"]
    B -->|实时监控| C3["nas-watch.py"]

    C1 --> D[kb-bridge.py<br/>桥接脚本]
    C2 --> D
    C3 --> D

    D --> E[AI分析<br/>Claude API]
    E --> F{判断type}

    F -->|决策| G1[projects/xxx/decisions/]
    F -->|文档| G2[projects/xxx/docs/]
    F -->|聊天| G3[projects/xxx/conversations/]

    G1 --> H[Git commit + push]
    G2 --> H
    G3 --> H
    H --> I[NAS Git仓库<br/>真相源]

    style C2 fill:#90EE90
    style D fill:#FFB6C1
    style E fill:#87CEEB
    style I fill:#FFD700

3.2 数据存储拓扑

graph LR
    subgraph NAS
    A[Gitea Git仓库<br/>真相源]
    B[投递区]
    C[定时任务]
    end

    subgraph Mac
    D[工作副本]
    E[Obsidian]
    F[Claude Code]
    end

    subgraph 飞书
    G[飞书文档]
    H[多维表格展示]
    end

    G -->|feishu-sync.py| I[临时目录]
    I -->|kb-bridge.py| A
    B -->|nas-watch.py| A
    A <-->|git pull/push| D
    D --> E
    D --> F
    A -->|feishu-render.py| H

    style A fill:#FFD700
    style I fill:#FFB6C1

3.3 日常工作流时序

sequenceDiagram
    participant 飞书
    participant 定时任务
    participant feishu_sync
    participant kb_bridge
    participant Claude
    participant Git仓库

    Note over 飞书,定时任务: 每天10:00
    定时任务->>feishu_sync: 触发
    feishu_sync->>飞书: 扫描新文档
    飞书-->>feishu_sync: 返回docx
    feishu_sync->>feishu_sync: 转markdown+下图
    feishu_sync->>kb_bridge: 传markdown
    kb_bridge->>Claude: 分析+判断type
    Claude-->>kb_bridge: type/tags/要点
    kb_bridge->>kb_bridge: 生成完整frontmatter
    kb_bridge->>Git仓库: commit+push

3.4 三个关键位置

位置1：真相源（NAS Git仓库）
  http://192.168.0.101:3002/robert/company-kb
  作用：唯一权威版本，所有人 pull/push

位置2：工作区（你的Mac）
  ~/work/company-kb/
  作用：Obsidian编辑、Claude问答、Git提交

位置3：投递区（NAS共享文件夹）
  SynologyDrive-zhishiku/知识库投递区/
  作用：同事丢文件，监控脚本自动采集

---

第四部分：分阶段实施

阶段 0：环境准备（半天）

0.1 NAS 建 Git 仓库

# NAS 上（SSH/DSM终端）
cd /volume1/git/repos/robert/
git init --bare company-kb.git

# 本地 clone
cd ~/work/
git clone ssh://用户名@192.168.0.101/volume1/git/repos/robert/company-kb.git
cd company-kb/

# 推送现有知识库
cp -r "现有知识库路径"/* .
git add . && git commit -m "Initial commit" && git push

0.2 整合飞书工具

cd ~/work/company-kb/
cp "飞书同步工具包/feishu-sync.py" tools/
cp "飞书同步工具包/run-sync.sh" tools/
git add tools/ && git commit -m "Add feishu-sync" && git push

阶段 1：核心对接（1-2天，P0）

1.1 创建 kb-bridge.py

作用：把 feishu-sync.py 拉下来的 markdown，用 AI 分析后转成合规知识页。

核心逻辑：

# 伪代码
for md_file in feishu输出目录:
    content = 读取(md_file)
    分析 = Claude_API分析(content)   # 判断type、提取tags、写description
    frontmatter = 生成完整frontmatter(分析, 契约)
    保存到 projects/<代号>/{分析.type对应目录}/
git commit + push

安装：

pip3 install anthropic pyyaml
export ANTHROPIC_API_KEY="你的Key"
cp kb-bridge.py tools/

1.2 测试完整流程

# 步骤1：拉飞书到临时目录
python3 tools/feishu-sync.py --folder ROOT --out /tmp/test --skip-big

# 步骤2：桥接处理到知识库
python3 tools/kb-bridge.py --input /tmp/test --project wanniu-l1

# 步骤3：校验
python3 tools/kb-lint-fm.py projects/wanniu-l1/
# 期望：错误 0 | 警告 0

# 步骤4：推送
git add . && git commit -m "Test ingest" && git push

1.3 创建统一定时脚本 auto-sync.sh

#!/bin/bash
# 1. 拉飞书 → 临时目录
python3 tools/feishu-sync.py --folder ROOT --out /tmp/sync-$(date +%s) --skip-big
# 2. 桥接 → 知识库
python3 tools/kb-bridge.py --input /tmp/sync-* --project auto
# 3. 清理临时目录
rm -rf /tmp/sync-*

1.4 配置定时任务

# NAS cron 或 Mac crontab
0 10 * * * cd ~/work/company-kb && git pull && bash tools/auto-sync.sh

阶段 2：验证（1天，P0）

• 手动跑 bash tools/auto-sync.sh，看日志
• 检查 projects/ 下是否有新知识页
• python3 tools/kb-lint-fm.py 全部通过
• Claude Code 里 /kb-ask 测试问答

阶段 3：锦上添花（P1，可选）

• nas-watch.py：监控投递区，文件一丢就处理（1天）
• feishu-render.py：推送知识库到飞书多维表格（2天）
• pre-commit hook：Git提交前自动校验（半天）

---

第五部分：日常使用

常用命令

# 创建新项目
bash tools/kb-init.sh <项目代号>

# 手动录入
/kb-ingest <项目代号> <飞书链接/文件>

# 查询知识
/kb-ask <问题>

# 校验知识库
python3 tools/kb-lint-fm.py   # 或 /kb-check

# 同步代码
git pull   # 拉最新
git push   # 推更新

# 查看统计
/kb-status

五种使用场景

场景	操作
查信息	/kb-ask 万牛会L1怎么安排的？ → AI答案+溯源
手动录入	/kb-ingest wanniu-l1 <飞书链接>
看自动同步	tail -100 sync.log
编辑知识	Obsidian打开 → 改 → git push
健康检查	/kb-check → 报告缺字段/死链

---

第六部分：关键决策与FAQ

改造前 vs 改造后

改造前（纯手工）：打开飞书→复制→建md→手写12字段frontmatter→粘贴→commit，每篇5-10分钟，累且易错。

改造后（自动化）：每天10:00全自动采集+生成+提交，你只需 git pull 和 /kb-ask，每天0分钟。

FAQ

Q: API 会不会很贵？ Sonnet约$3/百万token，每天10篇×2000字≈$0.12/天，月约$3.6，可接受。

Q: 要不要上向量库/RAG？ 现阶段不用。文档明确 P5（~100源/几百页且定位不准）才考虑，Claude语义检索够用。

Q: 定时任务失败怎么办？ 查 sync.log。常见：飞书登录过期（重新 lark-cli auth login）、API Key失效、Git冲突（手动pull）。

Q: NAS和本地怎么同步？ 用 Git pull/push（可靠），不要用群晖Drive自动同步（易冲突）。

---

快速启动清单（3天跑通）

Day 1：环境搭建

• NAS 建 Git 仓库
• 本地 clone 到 ~/work/company-kb/
• 推送知识库内容
• 整合 feishu-sync.py 到 tools/

Day 2：核心对接

• 安装 kb-bridge.py + 配 API Key
• 测试：feishu-sync → kb-bridge → lint → push
• 创建 auto-sync.sh

Day 3：定时与验证

• 手动跑 auto-sync.sh
• 配置定时任务
• /kb-ask 测试问答
• 记录问题准备优化

---

核心结论：你已完成最难的70%（飞书采集），只需补 kb-bridge.py（1-2天）就能打通全流程。建议先走「快速启动3天」验证价值，再决定是否补 P1 自动化。