knowledge-base

Knowledge Base Skill

一个旨在消除认知偏差、显式化隐性知识的知识库管理工具。它结合代码扫描（ace-tool）、网络搜索和结构化文档管理，构建项目的"第二大脑"。

核心理念：打破“知识诅咒”

"知识诅咒"（Curse of Knowledge）是指当我们掌握某种知识后，很难想象不懂这种知识的人的状态。在软件工程中，这表现为：

• 资深开发者假设新人“应该知道”某些上下文。
• 代码中充斥着特定领域的缩写和隐喻。
• 架构决策的背景被遗忘，只留下结果。

本技能通过以下方式解决此问题：

1. 显式化（Explicitness）：强制将默会知识（Tacit Knowledge）转化为显性知识（Explicit Knowledge）。
2. 上下文对齐（Context Alignment）：通过代码扫描提取领域术语，建立统一词汇表。
3. 认知共识（Cognitive Consensus）：记录“为什么这样做”而不仅仅是“怎么做”。

执行环境

路径类型	路径	说明
技能目录	~/.pi/agent/skills/knowledge-base/	脚本和模板位置
主脚本	~/.pi/agent/skills/knowledge-base/lib.ts	核心逻辑脚本
知识库目录	./docs/knowledge/	项目根目录下的文档存储位置

目录结构

docs/knowledge/
├── concepts/             # 领域概念与术语 (名词解释)
│   ├── [Term].md         # 一级文档：e.g. "DoubleEntryBookkeeping.md"
│   └── auth/             # 二级分类
│       ├── User.md
│       └── Session.md
│   └── frontend/         # 二级分类
│       ├── responsive/   # 三级分类
│       │   └── design/   # 四级分类
│       │       └── MobileFirst.md
│       └── pwa/          # 三级分类
│           └── advanced/ # 四级分类
│               └── optimization/  # 五级分类
│                   └── ProgressiveWebApp.md
├── guides/               # 操作指南与最佳实践 (How-to)
│   ├── [Topic].md        # 一级文档：e.g. "ErrorHandlingStrategy.md"
│   └── backend/          # 二级分类
│       ├── API.md
│       └── Database.md
│   └── frontend/         # 二级分类
│       └── css/          # 三级分类
│           └── flexbox/  # 四级分类
│               └── ResponsiveLayout.md
├── decisions/            # 认知决策记录 (Why)
│   ├── [Date]-[Topic].md # 一级文档：e.g. "20240101-WhyChooseRestOverGraphQL.md"
│   └── database/         # 二级分类
│       └── 20240101-WhyUsePostgres.md
│   └── frontend/         # 二级分类
│       └── layout/       # 三级分类
│           └── modern/   # 四级分类
│               └── strategies/  # 五级分类
│                   └── 20260107-WhyUseCSSGrid.md
├── external/             # 行业共识与外部参考
│   ├── [Source].md       # e.g. "ReactPatternConsensus.md"
│   └── standards/        # 二级分类
│       └── RESTfulAPI.md
├── GLOSSARY.md           # 专业术语表（自动生成，包含定义摘要）
└── index.md              # 自动生成的知识索引（支持多层级显示）

命令参考

所有命令建议在项目根目录下执行。

# 1. 初始化
bun ~/.pi/agent/skills/knowledge-base/lib.ts init

# 2. 扫描代码提取概念 (集成 ace-tool)
bun ~/.pi/agent/skills/knowledge-base/lib.ts scan

# 3. 发现项目结构并生成文档清单
bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

# 4. 创建知识条目（支持目录分类）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create term "术语名称" [分类路径]     # alias for concept
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "术语名称" [分类路径]
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "指南标题" [分类路径]
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "决策标题" [分类路径]

# 示例：创建带分类的文档（支持无限层级）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "UserAuthentication" auth/user
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "ErrorHandling" backend/api
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "WhyUsePostgres" database

# 三级和四级分类示例
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "MobileFirst" frontend/responsive/design
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "ProgressiveWebApp" frontend/pwa/advanced/optimization
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "ResponsiveLayout" frontend/css/flexbox
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "WhyUseCSSGrid" frontend/layout/modern/strategies

# 4. 搜索知识库
bun ~/.pi/agent/skills/knowledge-base/lib.ts search "关键词"

# 5. 生成专业术语表 (GLOSSARY.md)
bun ~/.pi/agent/skills/knowledge-base/lib.ts glossary

# 6. 生成/更新索引
bun ~/.pi/agent/skills/knowledge-base/lib.ts index

核心功能详解

1. 智能扫描 (scan)

利用 ace-tool 分析代码库，识别高频词汇、特定类名和复杂逻辑，自动建议需要创建的“概念文档”。

• 输入：代码库状态
• 输出：推荐创建的概念列表 (docs/knowledge/suggested_concepts.md)

2. 结构化文档 (create)

提供标准化模板，强制包含：

• Definition: 一句话定义（防歧义）。
• Context: 出现的场景。
• Anti-patterns: 常见的误解（解决认知偏差）。
• References: 代码引用或外部链接。

3. 行业共识集成

通过 external 目录管理通用知识（如 RESTful 规范、React Hooks 规则），避免重复造轮子，明确本项目是遵循标准还是有特殊定制。

4. 专业术语表维护 (glossary)

自动扫描 concepts/ 目录下的所有文档，提取定义（Definition）部分，生成扁平化的 GLOSSARY.md 表格。

• 用途：提供快速查阅的术语字典，适合非技术人员或快速上下文对齐。
• 格式：包含 Term (Link), Category, Definition 的 Markdown 表格。

最佳实践

1. 遇到不懂的缩写时：立即运行 create concept [缩写]，查明后填入。
2. 代码 Review 时：如果需要解释一段逻辑超过 3 句，创建一个 guide 并链接。
3. 新成员加入时：让他阅读 docs/knowledge/index.md，并要求他记录所有困惑点作为新的 Issue。