Add kb-bridge.py + 文档整理
- tools/kb-bridge.py: 原始物料→知识页核心脚本（384行完整实现） 功能：读取PDF/CSV/markdown → Claude API分析 → 生成frontmatter → 保存到projects/ - 完整落地链路.md: 端到端实施方案（Phase 0-3完整路径） - 完整项目现状报告.md: 真实状态验证（脚本真相+架构梳理） - docs/bot-comparison-analysis.md: kb-bot vs bot-v2 深度对比 - docs/kb-bot-usage-guide.md: kb-bot 使用指南 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
yangqianqian
510
完整落地链路.md
Normal file
510
完整落地链路.md
Normal file
@@ -0,0 +1,510 @@
|
||||
# 公司知识库完整落地链路（端到端）
|
||||
|
||||
> 从现状到最终可用的完整路径，不是散点方案
|
||||
> 更新时间：2026-07-16 18:50
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最终目标
|
||||
|
||||
**一句话验证标准**：
|
||||
```bash
|
||||
cd /知识库目录
|
||||
/kb-ask 万牛会L1怎么安排的？
|
||||
# AI 返回：根据 [[课程大纲v1]]（来源：飞书文档），万牛会L1...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 当前状态矩阵
|
||||
|
||||
| 组件 | 状态 | 位置 | 说明 |
|
||||
|------|------|------|------|
|
||||
| **知识库框架** | ✅ 完整 | company-kb-v0.1-mvp-20260707/ | 目录结构、契约、工具、命令都有 |
|
||||
| **Git 真相源** | ✅ 已建 | http://192.168.0.101:3002/qianqian/company-kb | Gitea仓库，可push/pull |
|
||||
| **本地工作副本** | ✅ 已建 | Synology Drive同步盘/company-kb/ | 就是知识库目录，有.git/ |
|
||||
| **原始物料** | ⚠️ 未处理 | 飞书同步/（564文件）+ 会议记录/（4文件） | 没frontmatter，AI读不到 |
|
||||
| **知识页** | ⚠️ 只有示例 | projects/wanniu-l1/（7页）+ _example/ | 真实内容很少 |
|
||||
| **AI查询** | ⚠️ 能跑但没内容 | /kb-ask命令存在 | 能执行，但查不到东西（内容太少） |
|
||||
| **自动化** | ❌ 不存在 | 无 | 飞书→知识库没有自动链路 |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 完整数据流（端到端）
|
||||
|
||||
### 阶段 0：环境搭建（已完成✅）
|
||||
|
||||
```
|
||||
NAS Gitea 真相源
|
||||
↕ git push/pull
|
||||
本地 company-kb/（工作副本）
|
||||
↕ Synology Drive
|
||||
NAS 物理存储
|
||||
```
|
||||
|
||||
**验证**：
|
||||
```bash
|
||||
cd company-kb目录
|
||||
git status # 能看到状态
|
||||
git push # 能推送
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段 1：物料汇入（核心，当前卡在这里❌）
|
||||
|
||||
```
|
||||
原始物料（飞书同步/、会议记录/）
|
||||
↓
|
||||
【处理脚本】kb-bridge.py
|
||||
├─ 读取原始文件
|
||||
├─ 提取文本（PDF用pdfplumber，CSV用pandas）
|
||||
├─ 调用Claude API分析
|
||||
│ └─ 判断type（doc/decision/conversation）
|
||||
│ └─ 生成title、description、tags
|
||||
│ └─ 提炼关键内容
|
||||
├─ 生成完整frontmatter
|
||||
│ ├─ type: doc
|
||||
│ ├─ title: ...
|
||||
│ ├─ source: 飞书文档
|
||||
│ ├─ source_link: file://...
|
||||
│ ├─ status: seed
|
||||
│ ├─ created: 2026-xx-xx
|
||||
│ └─ ingested: 2026-07-16
|
||||
└─ 保存到 projects/xxx/docs/或decisions/或conversations/
|
||||
↓
|
||||
合规知识页（.md + frontmatter）
|
||||
↓
|
||||
【校验】kb-lint-fm.py
|
||||
└─ 检查frontmatter是否符合契约
|
||||
↓
|
||||
【提交】git add + git commit + git push
|
||||
↓
|
||||
Git 真相源（Gitea）
|
||||
```
|
||||
|
||||
**验证**：
|
||||
```bash
|
||||
# 处理一个测试文件
|
||||
python3 tools/kb-bridge.py \
|
||||
--input "../飞书同步/AI内容反推工作流.csv" \
|
||||
--output projects/ai-workflow/docs/
|
||||
|
||||
# 检查
|
||||
python3 tools/kb-lint-fm.py projects/ai-workflow/
|
||||
# 期望：错误 0
|
||||
|
||||
# 查看生成的文件
|
||||
cat projects/ai-workflow/docs/AI内容反推工作流.md
|
||||
# 期望：有完整frontmatter + 内容
|
||||
|
||||
# 提交
|
||||
git add projects/ai-workflow/
|
||||
git commit -m "Add AI工作流文档（测试）"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段 2：AI 查询（自然就能用✅）
|
||||
|
||||
```
|
||||
你在本地工作副本
|
||||
↓
|
||||
cd company-kb目录
|
||||
↓
|
||||
/kb-ask 问题
|
||||
↓
|
||||
【Claude Code 执行】
|
||||
├─ 扫描 projects/ 下所有 .md 文件
|
||||
├─ 解析每个文件的 frontmatter
|
||||
├─ 根据 type、tags 筛选相关文件
|
||||
├─ 语义检索文件内容
|
||||
├─ 综合答案
|
||||
└─ 挂 source_link（从frontmatter读取）
|
||||
↓
|
||||
AI 返回答案 + 溯源链接
|
||||
```
|
||||
|
||||
**验证**：
|
||||
```bash
|
||||
cd company-kb目录
|
||||
/kb-ask AI内容反推工作流是什么？
|
||||
# 期望：AI能找到刚才生成的知识页，返回答案 + 溯源
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段 3：自动化（可选，手动跑通后再建）
|
||||
|
||||
```
|
||||
【定时任务】每天 10:00
|
||||
↓
|
||||
【扫描】知识库投递区/
|
||||
├─ 发现新文件
|
||||
├─ 调用 kb-bridge.py 处理
|
||||
├─ lint 检查
|
||||
├─ git commit + git push
|
||||
└─ 记录日志
|
||||
↓
|
||||
知识库自动更新
|
||||
```
|
||||
|
||||
**验证**：
|
||||
```bash
|
||||
# 在投递区丢个新文件
|
||||
cp 新文件.pdf 知识库投递区/
|
||||
|
||||
# 第二天看
|
||||
cd company-kb目录
|
||||
git pull
|
||||
ls projects/ # 应该能看到新项目
|
||||
|
||||
/kb-ask 新文件里的内容
|
||||
# AI能查到
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 分阶段实施计划
|
||||
|
||||
### Phase 0：环境准备（已完成✅，今天）
|
||||
|
||||
- [x] NAS Gitea 真相源
|
||||
- [x] 本地 Git 工作副本
|
||||
- [x] 能 git push/pull
|
||||
|
||||
**用时**：已完成
|
||||
**交付物**：Git仓库可用
|
||||
|
||||
---
|
||||
|
||||
### Phase 1A：开发处理脚本（明天上午，3小时）
|
||||
|
||||
**任务**：
|
||||
1. 创建 kb-bridge.py（核心脚本）
|
||||
2. 实现功能：
|
||||
- 读取文件（支持 PDF、CSV、markdown）
|
||||
- 调用 Claude API 分析
|
||||
- 生成 frontmatter
|
||||
- 保存到 projects/
|
||||
|
||||
**交付物**：
|
||||
- `tools/kb-bridge.py`（完整可运行）
|
||||
- 依赖安装说明
|
||||
- 使用文档
|
||||
|
||||
**验证标准**：
|
||||
```bash
|
||||
python3 tools/kb-bridge.py --input test.pdf --output projects/test/
|
||||
ls projects/test/docs/test.md # 文件生成
|
||||
python3 tools/kb-lint-fm.py projects/test/ # 错误 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1B：测试处理流程（明天下午，2小时）
|
||||
|
||||
**任务**：
|
||||
1. 选 5 个代表性文件测试：
|
||||
- 1 个会议记录 PDF
|
||||
- 1 个飞书同步 CSV
|
||||
- 1 个 markdown 文件
|
||||
- 1 个图片（测试 assets）
|
||||
- 1 个长文档（测试分段）
|
||||
|
||||
2. 逐个处理 → lint → git push
|
||||
|
||||
3. AI 查询验证
|
||||
|
||||
**交付物**：
|
||||
- 5 个测试项目生成
|
||||
- Git 提交记录
|
||||
- AI 查询测试通过
|
||||
|
||||
**验证标准**：
|
||||
```bash
|
||||
/kb-ask 会议纪要里的决策
|
||||
# AI能找到并回答
|
||||
|
||||
/kb-ask AI工作流
|
||||
# AI能找到并回答
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1C：批量处理（明天晚上或后天，按需）
|
||||
|
||||
**任务**：
|
||||
1. 批量处理所有 564 个飞书同步文件
|
||||
2. 批量处理所有 4 个会议记录
|
||||
3. 处理公司资产信息里的 md 文件
|
||||
|
||||
**方式**：
|
||||
- 选项A：一次性全跑（API成本 ~$20-50）
|
||||
- 选项B：分批跑（每天处理 50 个）
|
||||
- 选项C：只处理重要的（手动挑选）
|
||||
|
||||
**交付物**：
|
||||
- 所有原始物料变成知识页
|
||||
- 全部 lint 通过
|
||||
- 全部 git push
|
||||
|
||||
**验证标准**：
|
||||
```bash
|
||||
find projects/ -name "*.md" | wc -l
|
||||
# 应该有几百个文件
|
||||
|
||||
/kb-ask 随机问题
|
||||
# AI 能从大量知识页中找到答案
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2：飞书机器人打通（下周）
|
||||
|
||||
**任务**：
|
||||
1. bot-v2（阿里云）clone 知识库
|
||||
2. 配置定期 git pull
|
||||
3. 群里 @机器人 → 调 /kb-ask → 回复
|
||||
|
||||
**验证标准**：
|
||||
```
|
||||
飞书群里：@机器人 万牛会L1怎么安排？
|
||||
机器人回复：根据[[课程大纲v1]]（来源：飞书文档），...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3：自动化（按需）
|
||||
|
||||
**任务**：
|
||||
1. 创建定时任务脚本
|
||||
2. 监控投递区新文件
|
||||
3. 自动处理 + git push
|
||||
|
||||
**验证标准**：
|
||||
- 丢个新文件到投递区
|
||||
- 第二天自动出现在知识库
|
||||
- AI 能查到
|
||||
|
||||
---
|
||||
|
||||
## 🔧 关键组件详细设计
|
||||
|
||||
### kb-bridge.py 核心逻辑
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
知识桥接脚本：原始物料 → 知识页
|
||||
"""
|
||||
import anthropic
|
||||
import yaml
|
||||
import os
|
||||
from pathlib import Path
|
||||
import pdfplumber # PDF提取
|
||||
import pandas as pd # CSV处理
|
||||
|
||||
def process_file(input_path, output_dir, kb_root):
|
||||
"""处理单个文件"""
|
||||
# 1. 读取文件内容
|
||||
content = extract_content(input_path)
|
||||
|
||||
# 2. 调用 Claude API 分析
|
||||
analysis = analyze_with_claude(content, input_path)
|
||||
# 返回：{
|
||||
# "type": "doc",
|
||||
# "title": "...",
|
||||
# "description": "...",
|
||||
# "tags": ["...", "..."],
|
||||
# "key_points": "...",
|
||||
# "project": "ai-workflow" # AI建议的项目归属
|
||||
# }
|
||||
|
||||
# 3. 生成 frontmatter
|
||||
frontmatter = generate_frontmatter(analysis, input_path)
|
||||
|
||||
# 4. 生成内容（原文 + AI提炼）
|
||||
content_md = f"{frontmatter}\n\n{analysis['key_points']}\n\n## 原始内容\n\n{content}"
|
||||
|
||||
# 5. 保存
|
||||
save_to_kb(content_md, analysis, output_dir, kb_root)
|
||||
|
||||
return analysis
|
||||
|
||||
def extract_content(file_path):
|
||||
"""提取文件内容"""
|
||||
ext = Path(file_path).suffix.lower()
|
||||
|
||||
if ext == '.pdf':
|
||||
with pdfplumber.open(file_path) as pdf:
|
||||
return "\n".join(page.extract_text() for page in pdf.pages)
|
||||
|
||||
elif ext == '.csv':
|
||||
df = pd.read_csv(file_path)
|
||||
return df.to_string()
|
||||
|
||||
elif ext in ['.md', '.txt']:
|
||||
return Path(file_path).read_text()
|
||||
|
||||
else:
|
||||
raise ValueError(f"不支持的文件类型：{ext}")
|
||||
|
||||
def analyze_with_claude(content, source_file):
|
||||
"""Claude API 分析"""
|
||||
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
|
||||
|
||||
prompt = f"""分析这个文件，返回 JSON：
|
||||
|
||||
文件：{source_file}
|
||||
内容（前5000字符）：
|
||||
{content[:5000]}
|
||||
|
||||
返回格式：
|
||||
{{
|
||||
"type": "doc|decision|conversation", // 判断文档类型
|
||||
"title": "一句话标题",
|
||||
"description": "一句话描述",
|
||||
"tags": ["关键词1", "关键词2"],
|
||||
"key_points": "3-5条关键要点（markdown格式）",
|
||||
"project": "建议的项目代号（kebab-case）"
|
||||
}}
|
||||
|
||||
判断规则：
|
||||
- type=doc：外部文档、参考资料
|
||||
- type=decision：决策记录、方案选择
|
||||
- type=conversation：会议纪要、聊天记录
|
||||
"""
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-sonnet-3-5-20240620",
|
||||
max_tokens=2000,
|
||||
messages=[{"role": "user", "content": prompt}]
|
||||
)
|
||||
|
||||
return parse_json(response.content[0].text)
|
||||
|
||||
def generate_frontmatter(analysis, source_file):
|
||||
"""生成 frontmatter"""
|
||||
from datetime import date
|
||||
|
||||
fm = {
|
||||
"type": analysis["type"],
|
||||
"title": analysis["title"],
|
||||
"description": analysis["description"],
|
||||
"tags": analysis["tags"],
|
||||
"timestamp": str(date.today()),
|
||||
"source": guess_source(source_file), # 飞书文档/会议/NAS
|
||||
"source_link": f"file://{os.path.abspath(source_file)}",
|
||||
"status": "seed",
|
||||
"created": str(date.today()),
|
||||
"ingested": str(date.today()),
|
||||
}
|
||||
|
||||
return "---\n" + yaml.dump(fm, allow_unicode=True) + "---\n"
|
||||
|
||||
def save_to_kb(content, analysis, output_dir, kb_root):
|
||||
"""保存到知识库"""
|
||||
project = analysis["project"]
|
||||
type_dir = {
|
||||
"doc": "docs",
|
||||
"decision": "decisions",
|
||||
"conversation": "conversations"
|
||||
}[analysis["type"]]
|
||||
|
||||
# 创建项目目录（如果不存在）
|
||||
project_dir = Path(kb_root) / "projects" / project
|
||||
if not project_dir.exists():
|
||||
# 用 kb-init.sh 创建骨架
|
||||
os.system(f"cd {kb_root} && bash tools/kb-init.sh {project}")
|
||||
|
||||
# 保存文件
|
||||
output_path = project_dir / type_dir / f"{slugify(analysis['title'])}.md"
|
||||
output_path.write_text(content)
|
||||
|
||||
print(f"✓ Saved: {output_path}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
import argparse
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--input", required=True, help="输入文件路径")
|
||||
parser.add_argument("--output", help="输出目录（可选，默认自动判断）")
|
||||
parser.add_argument("--kb-root", default=".", help="知识库根目录")
|
||||
args = parser.parse_args()
|
||||
|
||||
process_file(args.input, args.output, args.kb_root)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 成本估算
|
||||
|
||||
### API 成本（Claude API）
|
||||
- 每个文件处理：~$0.05-0.10（取决于大小）
|
||||
- 564 个飞书文件：~$30-60
|
||||
- 4 个会议记录：~$1-2
|
||||
- **总计**：~$30-70
|
||||
|
||||
### 时间成本
|
||||
- Phase 1A（开发脚本）：3 小时
|
||||
- Phase 1B（测试）：2 小时
|
||||
- Phase 1C（批量处理）：API调用时间 + 1小时监控
|
||||
- **总计**：1-2 天
|
||||
|
||||
---
|
||||
|
||||
## ✅ 验收标准（怎么算完成）
|
||||
|
||||
### Phase 1 完成标准
|
||||
```bash
|
||||
# 1. 能处理各种文件
|
||||
python3 tools/kb-bridge.py --input test.pdf # 成功
|
||||
|
||||
# 2. 生成的文件合规
|
||||
python3 tools/kb-lint-fm.py projects/ # 错误 0
|
||||
|
||||
# 3. AI 能查到
|
||||
cd company-kb目录
|
||||
/kb-ask 随机问题 # 能返回答案 + 溯源
|
||||
|
||||
# 4. Git 有记录
|
||||
git log # 能看到提交历史
|
||||
|
||||
# 5. 同事能用
|
||||
# 同事 git pull → /kb-ask → 也能查到
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 风险与对策
|
||||
|
||||
### 风险 1：API 成本超预算
|
||||
**对策**：先测试 10 个文件，评估成本，再决定是否全量处理
|
||||
|
||||
### 风险 2：AI 分析不准确
|
||||
**对策**：Phase 1B 测试时人工核查，调整 prompt
|
||||
|
||||
### 风险 3：文件格式太复杂
|
||||
**对策**：复杂文件先跳过，手动处理
|
||||
|
||||
### 风险 4：知识页太多，AI 检索不准
|
||||
**对策**：先做到 P1（100页内），检索不准时再考虑 P4/P5（编译层/向量库）
|
||||
|
||||
---
|
||||
|
||||
## 📌 立刻开始（今晚或明天）
|
||||
|
||||
**今晚**：
|
||||
1. 我生成完整的 kb-bridge.py
|
||||
2. 你配置依赖（`pip3 install anthropic pdfplumber pandas pyyaml`）
|
||||
3. 测试处理 1 个文件
|
||||
|
||||
**明天**：
|
||||
1. 测试 5 个代表性文件
|
||||
2. 验证 AI 能查到
|
||||
3. 决定是否批量处理
|
||||
|
||||
---
|
||||
|
||||
**这次是完整链路，不是散点。你觉得清楚了吗？**
|
||||
Reference in New Issue
Block a user