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 # 自动生成的知识索引（支持多层级显示） ``` ## 命令参考 所有命令建议在**项目根目录**下执行。 ```bash # 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。