Knowledge Base

Name: Knowledge Base
Author: dwsy

dwsy/knowledge-base-skill

54 installs
1 repo stars
Updated January 23, 2026
dwsy/knowledge-base-skill

Builds a project 'second brain' by scanning code, searching the web and structuring docs so tacit knowledge, domain terms and decisions become explicit and shareable.

About

knowledge-base is a documentation skill that fights the curse of knowledge by scanning code, searching the web and writing structured docs, turning a project's tacit understanding into an explicit 'second brain'. A solo builder reaches for it to capture domain vocabulary, architecture decisions and reasoning so context is preserved for future sessions or teammates.

Turns tacit knowledge explicit
Extracts domain terms via code scanning
Records decisions and rationale
Combines code scan and web search

Knowledge Base by the numbers

54 all-time installs (skills.sh)
Ranked #791 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Jul 29, 2026 (Skillselion catalog sync)

npx skills add https://github.com/dwsy/knowledge-base-skill --skill knowledge-base

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/dwsy/knowledge-base-skill/knowledge-base.svg)](https://skillselion.com/skills/dwsy/knowledge-base-skill/knowledge-base)

Installs	54
repo stars	★ 1
Last updated	January 23, 2026
Repository	dwsy/knowledge-base-skill ↗

What it does

Builds a project 'second brain' by scanning code, searching the web and structuring docs so tacit knowledge, domain terms and decisions become explicit and shareable.

Who is it for?

preserving project context and decisions

Skip if: quick one-off tasks

Files

SKILL.mdMarkdownGitHub ↗

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。

# Dependencies
node_modules/
.pnp
.pnp.js

# Test coverage
coverage/
*.lcov

# Production
build/
dist/

# Misc
.DS_Store
*.pem

# Debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Local env files
.env*.local
.env

# Logs
logs/
*.log

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
Thumbs.db
.ace-tool/

import { readdir, stat, readFile, mkdir, writeFile, copyFile } from "fs/promises";
import { join, resolve, dirname, extname } from "path";
import { fileURLToPath } from "url";
import { exec } from "child_process";
import { promisify } from "util";

const execAsync = promisify(exec);

// 自动定位当前项目的 docs/knowledge 目录
const KNOWLEDGE_ROOT = resolve(process.cwd(), "docs/knowledge");

// 技能模板目录
const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "templates");

// 标准目录结构
const REQUIRED_DIRS = [
  "concepts",   // 概念
  "guides",     // 指南
  "decisions",  // 决策
  "external"    // 外部参考
];

async function exists(path: string) {
  try {
    await stat(path);
    return true;
  } catch {
    return false;
  }
}

// 生成 ISO 日期字符串 (yyyy-mm-dd)
function getISODateString(): string {
  const now = new Date();
  const year = now.getFullYear();
  const month = String(now.getMonth() + 1).padStart(2, "0");
  const day = String(now.getDate()).padStart(2, "0");
  return `${year}-${month}-${day}`;
}

// 替换模板中的占位符
function replaceTemplatePlaceholders(content: string, date: string, name: string, category?: string): string {
  return content
    .replace(/{{date}}/g, date)
    .replace(/{{name}}/g, name)
    .replace(/{{category}}/g, category || "general");
}

// 1. Init
async function init() {
  console.log(`🧠 Initializing Knowledge Base at: ${KNOWLEDGE_ROOT}\n`);

  if (!(await exists(KNOWLEDGE_ROOT))) {
    await mkdir(KNOWLEDGE_ROOT, { recursive: true });
    console.log(`✅ Created: ${KNOWLEDGE_ROOT}`);
  }

  for (const dir of REQUIRED_DIRS) {
    const path = join(KNOWLEDGE_ROOT, dir);
    if (!(await exists(path))) {
      await mkdir(path, { recursive: true });
      console.log(`✅ Created: ${path}/`);
    }
  }

  const indexPath = join(KNOWLEDGE_ROOT, "index.md");
  if (!(await exists(indexPath))) {
    await writeFile(indexPath, "# Knowledge Base Index\n\n> Generated automatically\n");
    console.log(`✅ Created: index.md`);
  }

  console.log(`\n✨ Knowledge Base structure initialized!`);
}

// 2. Scan
async function scan() {
  console.log(`🔍 Scanning project structure for undocumented concepts...\n`);

  const projectRoot = resolve(process.cwd(), "src");
  if (!(await exists(projectRoot))) {
    console.log("❌ src/ directory not found. Run from project root.");
    process.exit(1);
  }

  const { stdout } = await execAsync(`find ${projectRoot} -name "*.ts" -type f 2>/dev/null`);
  const files = stdout.trim().split("\n").filter(Boolean);

  const concepts = new Set<string>();

  for (const file of files) {
    const fileName = extname(file).replace(".ts", "");
    const fileNameConcepts = fileName
      .split(/[-_.]/)
      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
      .filter(word => word.length > 2);

    fileNameConcepts.forEach(concept => concepts.add(concept));

    const content = await readFile(file, 'utf-8');
    const classMatches = content.matchAll(/export (?:class|interface|type) (\w+)/g);
    for (const match of classMatches) {
      concepts.add(match[1]);
    }
  }

  const sortedConcepts = Array.from(concepts).sort();

  const reportPath = join(KNOWLEDGE_ROOT, "SCAN_REPORT.md");
  let reportContent = "# Undocumented Concepts\n\n";
  reportContent += `Scan Date: ${new Date().toISOString()}\n`;
  reportContent += `Total Files: ${files.length}\n`;
  reportContent += `Found Concepts: ${sortedConcepts.length}\n\n`;
  reportContent += "## Concepts\n\n";

  for (const concept of sortedConcepts) {
    const existsInDocs = await exists(join(KNOWLEDGE_ROOT, "concepts", `${concept}.md`));
    const mark = existsInDocs ? "✅" : "⬜";
    reportContent += `- [${mark}] **${concept}**\n`;
  }

  reportContent += "\n\n## Next Steps\n";
  reportContent += "Run `bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept <Name>` to document these.";

  await writeFile(reportPath, reportContent);
  console.log(`✅ Scan complete. Suggestions saved to: ${reportPath}`);
  console.log(reportContent);
}

// 3. Create
async function create(type: string, name: string, category?: string) {
  if (!['concept', 'guide', 'decision', 'term'].includes(type)) {
    console.error("❌ Invalid type. Use: concept, guide, decision, or term");
    process.exit(1);
  }

  if (!name) {
    console.error("❌ Please provide a name.");
    process.exit(1);
  }

  const actualType = type === 'term' ? 'concept' : type;

  const filename = name.replace(/[^a-zA-Z0-9\-_]/g, '') + ".md";
  let subDir = actualType + "s";
  let templateName = `${actualType}-template.md`;

  let targetDir = join(KNOWLEDGE_ROOT, subDir);
  if (category) {
    const sanitizedCategory = category.replace(/[^a-zA-Z0-9\-_/]/g, '');
    targetDir = join(targetDir, sanitizedCategory);
    if (!(await exists(targetDir))) {
      await mkdir(targetDir, { recursive: true });
      console.log(`✅ Created category directory: ${sanitizedCategory}/`);
    }
  }

  if (type === 'decision') {
    const date = new Date().toISOString().slice(0, 10).replace(/-/g, "");
    const safeName = name.replace(/\s+/g, '-');
    const finalFilename = `${date}-${safeName}.md`;

    const targetPath = join(targetDir, finalFilename);
    if (await exists(targetPath)) {
      console.error(`❌ File exists: ${targetPath}`);
      process.exit(1);
    }

    let content = await readFile(join(TEMPLATES_DIR, templateName), 'utf-8');
    content = content.replace(/\[Decision Title\]/, name);
    content = replaceTemplatePlaceholders(content, getISODateString(), name, category);

    await writeFile(targetPath, content);
    console.log(`✅ Created: ${targetPath}`);
    return;
  }

  const targetPath = join(targetDir, filename);
  if (await exists(targetPath)) {
    console.error(`❌ File exists: ${targetPath}`);
    process.exit(1);
  }

  let content = await readFile(join(TEMPLATES_DIR, templateName), 'utf-8');
  content = content.replace(/\[Concept Name\]|\[Guide Title\]/, name);
  content = replaceTemplatePlaceholders(content, getISODateString(), name, category);

  await writeFile(targetPath, content);
  console.log(`✅ Created: ${targetPath}`);
}

// 4. Index
async function generateIndex() {
  console.log("🔄 Generating Knowledge Index...");

  let content = "# Knowledge Base Index\n\n";
  content += "> Generated automatically. Do not edit manually.\n\n";

  for (const dir of REQUIRED_DIRS) {
    const dirPath = join(KNOWLEDGE_ROOT, dir);
    if (!(await exists(dirPath))) continue;

    content += `## ${dir.charAt(0).toUpperCase() + dir.slice(1)}\n`;

    const docs: { path: string; title: string; relativePath: string }[] = [];
    
    async function collectDocs(currentDir: string, relativePath: string = "") {
      const entries = await readdir(currentDir);
      for (const entry of entries) {
        const fullPath = join(currentDir, entry);
        const statInfo = await stat(fullPath);
        
        if (statInfo.isDirectory()) {
          await collectDocs(fullPath, join(relativePath, entry));
        } else if (entry.endsWith('.md') && entry !== 'index.md') {
          const fileContent = await readFile(fullPath, 'utf-8');
          const titleMatch = fileContent.match(/^#\s+(.+)$/m) || fileContent.match(/^title:\s+"(.+)"$/m);
          const title = titleMatch ? titleMatch[1] : entry.replace('.md', '');
          docs.push({
            path: fullPath,
            title: title,
            relativePath: join(relativePath, entry)
          });
        }
      }
    }
    
    await collectDocs(dirPath);
    
    if (docs.length === 0) {
      content += "*No documents yet*\n\n";
      continue;
    }

    docs.forEach(doc => {
      content += `- [${doc.title}](knowledge/${doc.relativePath})\n`;
    });
    content += "\n";
  }

  await writeFile(join(KNOWLEDGE_ROOT, "index.md"), content);
  console.log("✅ Index generated!");
}

// CLI
const command = process.argv[2];

switch (command) {
  case 'init':
    init();
    break;
  case 'scan':
    scan();
    break;
  case 'create':
    const type = process.argv[3];
    const name = process.argv[4];
    const category = process.argv[5];
    create(type, name, category);
    break;
  case 'index':
    generateIndex();
    break;
  default:
    console.log(`
Knowledge Base Skill v1.0

Usage:
  bun lib.ts init                 Initialize knowledge base structure
  bun lib.ts scan                 Scan project for undocumented concepts
  bun lib.ts create <type> <name> [category]  Create a document
  bun lib.ts index                Generate index.md

Types:
  concept, guide, decision, term

Examples:
  bun lib.ts create concept "UserAuthentication" auth
  bun lib.ts create guide "ErrorHandling" backend
  bun lib.ts create decision "UsePostgres" database
`);
}

MIT License

Copyright (c) 2026 Pi Agent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Knowledge Base Skill

专业的知识库管理系统，旨在解决"知识诅咒"（Curse of Knowledge）和认知偏差问题。通过显式化隐性知识、扫描代码提取领域概念、整合行业最佳实践，构建结构化的 Markdown 知识库。

特性

🧠 打破知识诅咒: 强制显式化隐性知识，记录常见误区
📂 多级分类: 支持任意层级的目录结构，灵活组织知识
🔍 代码扫描: 自动识别代码中的领域概念，建议文档化
📖 结构化模板: Concept、Guide、Decision 三种文档类型
🔗 智能索引: 自动生成层级化的知识索引
🔎 全文搜索: 支持关键词搜索所有知识文档
💡 认知对齐: 决策记录包含"认知对齐"章节
📚 行业共识: 整合标准规范，避免重复定义
🤖 AI 驱动: 可配合 Knowledge Builder Extension 实现自动化文档生成

快速开始

1. 初始化项目知识库

cd /path/to/project
bun ~/.pi/agent/skills/knowledge-base/lib.ts init

这将创建以下结构：

docs/knowledge/
├── concepts/    # 领域概念与术语
├── guides/      # 操作指南与最佳实践
├── decisions/   # 架构决策记录
├── external/    # 行业共识与外部参考
└── index.md     # 自动生成的索引

2. 创建文档

# 创建一级文档（无分类）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "UserAuthentication"

# 创建二级分类文档
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "User" auth
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "API" backend

# 创建三级分类文档
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "AceTool" core/tools
bun ~/.pi/agent/skills/knowledge-base/lib.ts create guide "ErrorHandling" backend/api
bun ~/.pi/agent/skills/knowledge-base/lib.ts create decision "Redis" database/cache

# 创建四级或更深分类文档（支持无限层级）
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

3. 扫描代码

bun ~/.pi/agent/skills/knowledge-base/lib.ts scan

自动分析代码库，识别需要文档化的概念。

4. 发现项目结构并生成文档清单

bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

分析项目目录结构，识别技术目录，并生成知识库文档清单和建议。

功能特点:

自动识别常见技术目录（auth, api, components, database 等）
为每个目录推荐相关的概念和指南
提供创建文档的完整命令
显示文档完成进度
支持去重（已存在的文档不会重复建议）

5. 生成索引

bun ~/.pi/agent/skills/knowledge-base/lib.ts index

6. 搜索知识

bun ~/.pi/agent/skills/knowledge-base/lib.ts search "keyword"

文档类型

Concept（概念）

定义领域术语和核心概念，包含：

Definition（定义）
Context（上下文）
Implementation（实现位置）
Common Misconceptions（常见误区）
Relationships（关联）
References（参考）

Guide（指南）

操作指南和最佳实践，包含：

Goal（目标）
Prerequisites（前置知识）
Steps（步骤）
Best Practices（最佳实践）
Examples（示例）

Decision（决策）

架构决策记录，包含：

Context（背景）
Options Considered（考虑过的选项）
The Decision（最终决策）
Cognitive Alignment（认知对齐）
Consequences（后果）

目录结构示例

docs/knowledge/
├── concepts/
│   ├── KnowledgeBase.md                    # 一级文档
│   ├── CurseOfKnowledge.md                 # 一级文档
│   ├── core/                               # 二级分类
│   │   ├── tools/
│   │   │   └── AceTool.md                  # 三级文档
│   │   ├── workflow/
│   │   │   └── Workhub.md                  # 三级文档
│   │   └── architecture/
│   │       └── SkillSystem.md              # 三级文档
│   └── frontend/                           # 二级分类
│       ├── responsive/                     # 三级分类
│       │   └── design/                     # 四级分类
│       │       └── MobileFirst.md          # 四级文档
│       └── pwa/                            # 三级分类
│           └── advanced/                   # 四级分类
│               └── optimization/           # 五级分类
│                   └── ProgressiveWebApp.md # 五级文档
├── guides/
│   ├── HowToUseKnowledgeBase.md            # 一级文档
│   ├── core/                               # 二级分类
│   │   ├── development/
│   │   │   └── HowToCreateSkill.md         # 三级文档
│   │   └── management/
│   │       └── HowToOrganizeKnowledge.md   # 三级文档
│   └── frontend/                           # 二级分类
│       └── css/                            # 三级分类
│           └── flexbox/                    # 四级分类
│               └── ResponsiveLayout.md     # 四级文档
├── decisions/
│   ├── 20260107-WhyWeBuiltKnowledgeBase.md # 一级文档
│   ├── core/                               # 二级分类
│   │   └── language/
│   │       └── 20260107-WhyUseTypeScript.md # 三级文档
│   └── frontend/                           # 二级分类
│       └── layout/                         # 三级分类
│           └── modern/                     # 四级分类
│               └── strategies/             # 五级分类
│                   └── 20260107-WhyUseCSSGrid.md # 五级文档
└── external/
    └── RESTfulAPIConsensus.md

最佳实践

分类策略

按模块分类（推荐用于功能模块清晰的项目）

concepts/
├── auth/              # 认证模块
├── payment/           # 支付模块
└── common/            # 通用概念

按层级分类（推荐用于复杂系统）

concepts/
├── core/              # 核心概念
├── domain/            # 领域概念
└── infrastructure/    # 基础设施

使用建议

✅ 遇到不懂的术语时，立即创建概念文档
✅ 代码 Review 时，如果需要解释超过 3 句，创建指南
✅ 记录"为什么"而不仅仅是"怎么做"
✅ 分类层级不超过 5 层
✅ 定期运行 discover 查看文档完成进度
✅ 使用 discover 生成的清单系统化构建知识库
❌ 不要使用递归定义
❌ 不要忽略常见误区记录

Discover 功能详解

运行命令:

bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

输出内容:

discovery_report.md: 详细的发现报告

报告包含: 1. 项目概览: 发现的技术目录数量、置信度统计 2. 目录详情: 每个技术目录的建议文档（概念和指南） 3. 快速开始指南: 系统化构建知识库的步骤 4. 进度追踪: 文档完成度百分比

支持的技术目录类型:

auth: 认证和授权
api: API 设计和开发
components: 前端组件
config: 配置管理
database: 数据库相关
utils: 工具函数
services: 服务层
models: 数据模型
hooks: React Hooks
store: 状态管理
middleware: 中间件
routes: 路由
tests: 测试
docker: Docker 容器化
deploy: 部署

使用流程:

# 1. 运行发现
bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

# 2. 查看报告
cat docs/knowledge/discovery_report.md

# 3. 根据建议创建文档（复制报告中的命令）
bun ~/.pi/agent/skills/knowledge-base/lib.ts create concept "Authentication" auth

# 4. 重新运行发现查看进度
bun ~/.pi/agent/skills/knowledge-base/lib.ts discover

核心原则

1. 显式化（Explicitness）

强制将默会知识（Tacit Knowledge）转化为显性知识（Explicit Knowledge）。

2. 上下文对齐（Context Alignment）

通过代码扫描提取领域术语，建立统一词汇表。

3. 认知共识（Cognitive Consensus）

记录"为什么这样做"而不仅仅是"怎么做"。

4. SSOT（Single Source of Truth）

每个知识领域只有一个权威文档。

依赖

Node.js / Bun
无外部依赖（纯 TypeScript 实现）

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

作者

Created for Pi Agent System

---

状态: ✅ 生产就绪

[Concept Name]

Definition (定义)

用简单的一句话定义这个概念，避免使用递归定义。

Context (上下文)

Domain: [e.g. 支付系统 / 用户认证]
Role: [该概念在系统中的角色]

Implementation (实现)

代码中可以在以下位置找到相关实现：

path/to/file.ts

// 关键代码片段或接口定义

Common Misconceptions (常见误区)

记录新人容易理解错误的地方，解决“知识诅咒”。

❌ 误区：[...描述...]
✅ 真相：[...描述...]

Relationships (关联)

Contains: [[SubConcept]]
Related to: [[OtherConcept]]

References (参考)

[链接到外部文档]

[Guide Title]

Goal (目标)

这份指南旨在解决什么问题？

Prerequisites (前置知识)

[[RelatedConcept]]

Steps (步骤)

1. [Step Name]

详细说明...

2. [Step Name]

详细说明...

Best Practices (最佳实践)

✅ Do: ...
❌ Don't: ...

Examples (示例)

// Good example

Related skills

Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.451k

Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.391k15.9k

Lark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.387k15.9k

Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k72

Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k72

Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.267k192k

Documentationdocsintegrations

About

Knowledge Base by the numbers

Add your badge

What it does

Who is it for?

Files

Knowledge Base Skill

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

执行环境

目录结构

命令参考

核心功能详解

1. 智能扫描 (scan)

2. 结构化文档 (create)

3. 行业共识集成

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

最佳实践

Knowledge Base Skill

特性

相关项目

快速开始

1. 初始化项目知识库

2. 创建文档

3. 扫描代码

4. 发现项目结构并生成文档清单

5. 生成索引

6. 搜索知识

文档类型

Concept（概念）

Guide（指南）

Decision（决策）

目录结构示例

最佳实践

分类策略

使用建议

Discover 功能详解

核心原则

1. 显式化（Explicitness）

2. 上下文对齐（Context Alignment）

3. 认知共识（Cognitive Consensus）

4. SSOT（Single Source of Truth）

依赖

许可证

贡献

相关资源

作者

[Concept Name]

Definition (定义)

Context (上下文)

Implementation (实现)

Common Misconceptions (常见误区)

Relationships (关联)

References (参考)

[Decision Title]

Context (背景)

Options Considered (考虑过的选项)

Option A: [Option Name]

Option B: [Option Name]

The Decision (最终决策)

Cognitive Alignment (认知对齐)

Consequences (后果)

[Guide Title]

Goal (目标)

Prerequisites (前置知识)

Steps (步骤)

1. [Step Name]

2. [Step Name]

Best Practices (最佳实践)

Examples (示例)

Related skills

This week in AI coding

1. 智能扫描 (`scan`)

2. 结构化文档 (`create`)

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