alongor666/project-knowledge-base

项目知识库管理器

将散落在代码注释、聊天记录、Markdown文档中的项目知识，转化为结构化、可复用的知识资产。

快速开始

场景1: 启动新项目，创建标准化知识库

# 进入技能脚本目录（安装后路径）
cd /mnt/skills/user/project-knowledge-base/scripts
python init_project_kb.py "车险周报自动化" "/home/claude/my-projects"

生成结果:

• 标准目录结构（docs/decisions/patterns/reports）
• 2个文档模板（项目启动文档、技术方案文档）
• README索引文件

场景2: 从现有项目提取知识模式

python extract_patterns.py /path/to/source /home/claude/my-projects/knowledge-base

自动提取:

• 技术决策（@decision标记）
• 代码模式（函数签名+docstring）
• 配置模板（JSON/YAML结构）

场景3: 更新知识库索引

python generate_index.py /home/claude/my-projects/knowledge-base

核心工作流程

工作流A: 新项目启动

用户：我要开始一个新的车险数据分析项目

↓ Step 1: 初始化知识库
  调用 init_project_kb.py 创建目录和模板

↓ Step 2: 填写模板
  引导用户填写项目启动文档：
  - 项目背景与目标
  - 关键指标（保费、赔付率等）
  - 里程碑与时间表

↓ Step 3: 设计技术方案
  引导用户填写技术方案文档：
  - 技术选型（参考insurance-domain.md）
  - 架构设计
  - 关键决策点

↓ 输出
  可直接使用的知识库，包含标准化文档

工作流B: 从现有项目构建知识库

用户：我有一个车险周报项目，代码写了很多，想整理成知识库

↓ Step 1: 确认源代码路径
↓ Step 2: 运行 extract_patterns.py 扫描
↓ Step 3: 保存提取的知识资产到 decisions/ 和 patterns/
↓ Step 4: 运行 generate_index.py 更新README

↓ 输出
  结构化知识库，可复用到新项目

工作流C: 标准化零散文档

用户：我有一些项目笔记和聊天记录，想整理成规范文档

↓ Step 1: 创建目标知识库（init_project_kb.py）
↓ Step 2: 分析现有内容，映射到模板
↓ Step 3: 生成标准化文档保存到docs/目录
↓ Step 4: 更新索引（generate_index.py）

工作流程

完整知识库构建流程

1. 场景识别
   ↓
   ├─ 新项目 → 工作流A
   ├─ 现有项目 → 工作流B
   └─ 零散文档 → 工作流C

2. 初始化
   ↓
   运行 init_project_kb.py
   ├─ 创建标准目录结构
   │   ├─ docs/ (项目文档)
   │   ├─ decisions/ (技术决策记录)
   │   ├─ patterns/ (可复用模式)
   │   └─ reports/ (分析报告)
   ├─ 生成模板文件
   │   ├─ 项目启动文档
   │   └─ 技术方案文档
   └─ 创建 README 索引

3. 知识提取（如适用）
   ↓
   运行 extract_patterns.py
   ├─ 扫描源代码
   │   ├─ 提取 @decision 标记
   │   ├─ 识别设计模式
   │   └─ 收集配置模板
   ├─ 分析技术选型
   └─ 保存到对应目录

4. 内容填充
   ↓
   ├─ 手动填写模板（新项目）
   └─ 整理提取内容（现有项目）

5. 索引更新
   ↓
   运行 generate_index.py
   ├─ 扫描所有文档
   ├─ 生成分类索引
   └─ 更新 README

6. 输出交付
   ↓
   结构化知识库
   ├─ 可复用模板
   ├─ 技术决策文档
   ├─ 代码模式库
   └─ 完整索引

决策逻辑

• 场景识别：根据用户需求自动选择工作流
• 内容提取：智能识别代码中的知识模式
• 标准化：统一文档格式，便于跨项目复用
• 索引生成：自动维护知识库导航

脚本使用指南

脚本1: init_project_kb.py

功能: 初始化项目知识库

python init_project_kb.py <项目名称> [知识库路径]

# 示例
python init_project_kb.py "车险周报自动化"
python init_project_kb.py "数据分析平台" "/home/claude/projects/kb"

输出:

• 目录结构: docs/, decisions/, patterns/, reports/
• 文档模板: 项目启动文档.md, 技术方案文档.md
• README.md

脚本2: extract_patterns.py

功能: 从代码和文档中提取知识模式

python extract_patterns.py <源代码目录> <知识库目录>

# 示例
python extract_patterns.py /mnt/skills/user/insurance-weekly-report /home/claude/kb

提取规则:

• # @decision: xxx → 技术决策记录
• def func(): """docstring""" → 代码模式
• .json 文件 → 配置模板

脚本3: generate_index.py

功能: 扫描知识库并生成README索引

python generate_index.py <知识库目录>

领域知识参考

在以下情况查阅 references/insurance-domain.md:

1. 填写车险业务相关模板时 - 了解术语（保费、赔付率、成本率）和分析维度
2. 设计技术方案时 - 参考麦肯锡风格报告规范、图表类型选择
3. 提取代码模式时 - 理解业务逻辑和数据格式要求

模板说明

模板1: 项目启动文档

适用场景: 新项目启动、明确范围和目标、干系人对齐

核心章节:

1. 项目背景与目标（业务痛点、KPI）
2. 项目范围（功能、数据、分析维度）
3. 干系人与角色
4. 关键里程碑与时间表
5. 风险与应对
6. 成功标准

模板2: 技术方案文档

适用场景: 技术选型与架构设计、关键决策记录

核心章节:

1. 技术选型（语言、框架、依赖库）
2. 系统架构设计（整体架构、模块设计、数据流）
3. 关键技术决策（使用@decision标记便于后续提取）
4. 技术风险与应对
5. 可扩展性设计
6. 测试策略与部署方案

最佳实践

技术决策编写

# @decision: 选择python-pptx而非ReportLab
# 理由: python-pptx支持精确布局控制，满足麦肯锡风格要求
# 权衡: 性能略低但12-13页规模可接受

知识库组织（多项目）

knowledge-base/
├── project-A/
│   ├── docs/
│   ├── decisions/
│   └── patterns/
├── project-B/
└── shared/
    ├── templates/
    └── references/

跨项目复用流程

1. 从旧项目提取模式（extract_patterns.py）
2. 查看 patterns/ 目录找到可复用的代码/配置
3. 在新项目中参考或直接复制
4. 更新新项目的技术方案文档，记录复用的模式

故障排查

| 问题 | 可能原因 | 解决方案 | | ----------------- | ------------------ | ------------------------------- | | 脚本运行失败 | Python版本/依赖 | 确保Python>=3.8，安装pandas | | 提取不到@decision | 格式不对 | 使用 # @decision: 内容 格式 | | README缺少内容 | 无YAML frontmatter | 文档开头添加 --- 包围的元数据 |

---

技能版本: v1.0.0 (MVP) 适用场景: 华安保险车险业务项目知识管理