Back to Details

project-wiki

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Wiki - 项目知识库构建工具

Project Wiki - Project Knowledge Base Construction Tool

📋 目录

📋 Table of Contents

核心价值

Core Values

与传统文档的区别：
维度传统文档知识库 Wiki
更新方式手动维护，易过时代码变更自动增量更新
组织方式线性目录知识图谱网络
知识类型显性文档（API/配置）显性 + 隐性知识（设计决策/最佳实践）
检索方式文件树浏览多维度标签搜索 + 关联推荐
核心能力：
  • 🏗️ 架构解析：自动识别项目结构、模块划分、技术栈
  • 🧠 隐性知识挖掘：提取代码中的设计模式、架构决策、最佳实践
  • 🔗 知识图谱构建：生成模块/API/概念的关系网络（Mermaid 可视化）
  • 📚 结构化文档生成：README、API 文档、架构文档自动生成
适用场景：
  • 新人入职：快速理解项目架构和核心模块
  • 代码重构：评估影响范围，识别技术债
  • 知识传承：将资深开发者的隐性知识显性化
  • 架构评审：可视化展示系统设计
Differences from Traditional Documentation：
AspectTraditional DocumentationKnowledge Base Wiki
Update MethodManually maintained, prone to obsolescenceAutomatic incremental updates on code changes
Organization MethodLinear directoryKnowledge graph network
Knowledge TypeExplicit documentation (API/configuration)Explicit + implicit knowledge (design decisions/best practices)
Retrieval MethodFile tree browsingMulti-dimensional tag search + related recommendations
Core Capabilities：
  • 🏗️ Architecture Parsing: Automatically identifies project structure, module division, and tech stack
  • 🧠 Implicit Knowledge Mining: Extracts design patterns, architecture decisions, and best practices from code
  • 🔗 Knowledge Graph Construction: Generates relationship networks of modules/APIs/concepts (Mermaid visualization)
  • 📚 Structured Document Generation: Automatically generates README, API documentation, and architecture documentation
Applicable Scenarios：
  • New employee onboarding: Quickly understand project architecture and core modules
  • Code refactoring: Assess impact scope and identify technical debt
  • Knowledge inheritance: Externalize implicit knowledge from senior developers
  • Architecture review: Visually display system design

快速开始

Quick Start

最简使用（1 分钟）

Minimal Usage (1 Minute)

bash
undefined
bash
undefined

1. 分析项目

1. Analyze project

python3 scripts/analyze_project.py --path ./your-project
python3 scripts/analyze_project.py --path ./your-project

2. 查看结果

2. View results

cat project-analysis.json

输出示例：
```json
{
  "languages": ["Python", "JavaScript"],
  "frameworks": ["fastapi", "vue"],
  "project_structure": {...}
}
cat project-analysis.json

Sample Output：
```json
{
  "languages": ["Python", "JavaScript"],
  "frameworks": ["fastapi", "vue"],
  "project_structure": {...}
}

完整流程（5 分钟）

Complete Workflow (5 Minutes)

bash
undefined
bash
undefined

1. 项目分析

1. Project analysis

python3 scripts/analyze_project.py --path ./your-project
python3 scripts/analyze_project.py --path ./your-project

2. 构建知识图谱

2. Build knowledge graph

python3 scripts/knowledge_graph.py --path ./your-project --format mermaid
python3 scripts/knowledge_graph.py --path ./your-project --format mermaid

3. 提取隐性知识

3. Extract implicit knowledge

python3 scripts/knowledge_extractor.py --path ./your-project --language python
python3 scripts/knowledge_extractor.py --path ./your-project --language python

4. 查看结果

4. View results

- project-analysis.json: 项目结构分析

- project-analysis.json: Project structure analysis

- knowledge-graph.json: 知识图谱数据

- knowledge-graph.json: Knowledge graph data

- knowledge-graph.mmd: Mermaid 图表

- knowledge-graph.mmd: Mermaid diagram

- implicit-knowledge.json: 隐性知识提取

- implicit-knowledge.json: Implicit knowledge extraction


---

---

操作步骤

Operation Steps

步骤 1：项目结构分析

Step 1: Project Structure Analysis

目的：识别编程语言、框架、构建工具和项目结构
bash
python3 scripts/analyze_project.py --path ./your-project
输出文件：
project-analysis.json
关键字段：
  • languages
    : 编程语言列表（Python、JavaScript、Java、Go、Rust 等）
  • frameworks
    : 框架列表（全小写，与框架指引锚点对应）
  • build_tools
    : 构建工具（npm、pip、maven、gradle、cargo 等）
  • project_structure
    : 目录树结构
框架识别说明：
  • 支持识别 13+ 主流框架（见框架支持）
  • 基于特征关键词和文件模式识别，即使没有明确依赖也能检测
  • 返回的框架名可直接用于查阅对应的框架指引
Purpose: Identify programming languages, frameworks, build tools, and project structure
bash
python3 scripts/analyze_project.py --path ./your-project
Output File: 
project-analysis.json
Key Fields：
  • languages
    : List of programming languages (Python, JavaScript, Java, Go, Rust, etc.)
  • frameworks
    : List of frameworks (all lowercase, corresponding to framework guide anchors)
  • build_tools
    : Build tools (npm, pip, maven, gradle, cargo, etc.)
  • project_structure
    : Directory tree structure
Framework Identification Notes：
  • Supports identification of 13+ mainstream frameworks (see Framework Support)
  • Identified based on feature keywords and file patterns, detectable even without explicit dependencies
  • Returned framework names can be directly used to access corresponding framework guides

步骤 2：查阅框架指引

Step 2: Access Framework Guides

触发条件：步骤 1 返回了 
frameworks
字段
查找方式：
方式 1：直接跳转
undefined
Trigger Condition: Step 1 returns the 
frameworks
field
Access Methods：
Method 1: Direct Jump
undefined

示例：frameworks: ["fastapi", "vue"]

Example: frameworks: ["fastapi", "vue"]

→ 查看 references/frameworks/index.md 中的 FastAPI 和 Vue 章节 → 使用锚点跳转：#fastapi、#vue

**方式 2：框架选择推荐**
根据 `languages` 和项目特征选择最适合的框架指引：
- **Python Web** → Django（企业级）/Flask（轻量级）/FastAPI（异步）
- **前端** → React（生态丰富）/Vue（易上手）/Svelte（高性能）
- **桌面应用** → Electron（成熟）/Tauri（轻量）

---
→ View FastAPI and Vue sections in references/frameworks/index.md → Use anchor jumps: #fastapi, #vue

**Method 2: Framework Selection Recommendations**
Select the most suitable framework guide based on `languages` and project characteristics：
- **Python Web** → Django (enterprise-level)/Flask (lightweight)/FastAPI (asynchronous)
- **Frontend** → React (rich ecosystem)/Vue (easy to learn)/Svelte (high performance)
- **Desktop Applications** → Electron (mature)/Tauri (lightweight)

---

步骤 3：构建知识图谱

Step 3: Build Knowledge Graph

目的：生成模块/API/配置的关系网络
bash
python3 scripts/knowledge_graph.py --path ./your-project --format mermaid
输出文件：
  • knowledge-graph.json
    : 结构化数据（节点和边）
  • knowledge-graph.mmd
    : Mermaid 流程图（可直接渲染）
知识图谱包含：
  • 节点类型：模块、API、配置、数据库、外部服务
  • 关系类型：包含、依赖、调用、数据流
  • 可视化：目录结构图、模块关系图、API 调用图
Purpose: Generate relationship networks of modules/APIs/configurations
bash
python3 scripts/knowledge_graph.py --path ./your-project --format mermaid
Output Files：
  • knowledge-graph.json
    : Structured data (nodes and edges)
  • knowledge-graph.mmd
    : Mermaid flow chart (directly renderable)
Knowledge Graph Includes：
  • Node types: Modules, APIs, Configurations, Databases, External Services
  • Relationship types: Contains, Depends on, Calls, Data Flow
  • Visualization: Directory structure diagram, module relationship diagram, API call diagram

步骤 4：提取隐性知识

Step 4: Extract Implicit Knowledge

目的：挖掘代码中的设计决策、最佳实践、代码约定
bash
python3 scripts/knowledge_extractor.py --path ./your-project --language python
输出文件：
implicit-knowledge.json
提取内容：
  • 设计模式识别（单例、工厂、观察者等）
  • 架构决策记录（为什么选择某个方案）
  • 最佳实践提取（命名规范、注释风格）
  • 代码约定总结（模块划分、接口设计）
Purpose: Mine design decisions, best practices, and code conventions from code
bash
python3 scripts/knowledge_extractor.py --path ./your-project --language python
Output File: 
implicit-knowledge.json
Extracted Content：
  • Design pattern recognition (Singleton, Factory, Observer, etc.)
  • Architecture decision records (why a certain solution was chosen)
  • Best practice extraction (naming conventions, comment styles)
  • Code convention summary (module division, interface design)

步骤 5：生成文档（智能体主导）

Step 5: Generate Documents (Agent-led)

基于提取的数据，智能体生成以下文档：
文档类型生成方式输出格式
README参考模板 + 项目数据Markdown
API 文档AST 解析 + 注释提取Markdown + JSON
架构文档知识图谱 + 架构决策Markdown + Mermaid
知识库首页知识分类 + 时间线Markdown
智能体职责：
  • 根据框架指引生成特定框架的文档结构
  • 将隐性知识转化为可读的自然语言描述
  • 生成可视化图表（架构图、时序图、流程图）
Based on extracted data, the agent generates the following documents：
Document TypeGeneration MethodOutput Format
READMEReference template + project dataMarkdown
API DocumentationAST parsing + comment extractionMarkdown + JSON
Architecture DocumentationKnowledge graph + architecture decisionsMarkdown + Mermaid
Knowledge Base HomepageKnowledge classification + timelineMarkdown
Agent Responsibilities：
  • Generate framework-specific document structures based on framework guides
  • Convert implicit knowledge into readable natural language descriptions
  • Generate visual diagrams (architecture diagrams, sequence diagrams, flow charts)

框架支持

Framework Support

支持的框架（13 个）

Supported Frameworks (13)

⭐ 最常用框架（推荐优先查阅）：
  • React: 企业级前端，生态最丰富
  • Vue: 渐进式前端，易上手
  • Django: Python 全栈，快速开发
  • Spring Boot: Java 企业级，Spring 生态
桌面应用（3 个）：
  • Electron - 成熟生态、跨平台
  • Tauri - 小体积、高安全性
  • Wails - 开发友好、配置简单
前端框架（4 个）：
  • React - 虚拟 DOM、大型生态
  • Vue - 响应式、渐进式
  • Svelte - 编译型、高性能
  • SolidJS - 细粒度响应式
Web API 框架（5 个）：
  • Django - Python 全栈、ORM
  • Flask - Python 轻量级
  • FastAPI - Python 现代异步
  • Spring Boot - Java 企业级
  • Gin - Go 高性能
跨平台 UI 框架（1 个）：
  • Flutter - Dart、多平台
完整索引：references/frameworks/index.md
框架选择指南：根据 
project-analysis.json
返回的框架名，直接查阅对应指引即可。
⭐ Most Commonly Used Frameworks (Recommended for Priority Access)：
  • React: Enterprise-level frontend, richest ecosystem
  • Vue: Progressive frontend, easy to learn
  • Django: Python full-stack, rapid development
  • Spring Boot: Java enterprise-level, Spring ecosystem
Desktop Applications (3)：
  • Electron - Mature ecosystem, cross-platform
  • Tauri - Small size, high security
  • Wails - Developer-friendly, simple configuration
Frontend Frameworks (4)：
  • React - Virtual DOM, large ecosystem
  • Vue - Reactive, progressive
  • Svelte - Compiled, high performance
  • SolidJS - Fine-grained reactivity
Web API Frameworks (5)：
  • Django - Python full-stack, ORM
  • Flask - Python lightweight
  • FastAPI - Python modern asynchronous
  • Spring Boot - Java enterprise-level
  • Gin - Go high performance
Cross-platform UI Frameworks (1)：
  • Flutter - Dart, multi-platform
Complete Index: references/frameworks/index.md
Framework Selection Guide: Directly access the corresponding guide using the framework name returned in 
project-analysis.json
.

资源索引

Resource Index

核心脚本

Core Scripts

脚本用途参数输出
analyze_project.py项目结构分析
--path
项目路径
project-analysis.json
knowledge_graph.py知识图谱构建
--path
项目路径<br>
--format
输出格式
knowledge-graph.json
<br>
knowledge-graph.mmd
knowledge_extractor.py隐性知识提取
--path
项目路径<br>
--language
编程语言
implicit-knowledge.json
extract_docs.py文档和 API 提取
--path
项目路径<br>
--language
编程语言
docs-metadata.json
analyze_dependencies.py依赖关系分析
--path
项目路径<br>
--format
输出格式		依赖图（JSON/Mermaid）
ScriptPurposeParametersOutput
analyze_project.pyProject structure analysis
--path
Project path
project-analysis.json
knowledge_graph.pyKnowledge graph construction
--path
Project path<br>
--format
Output format
knowledge-graph.json
<br>
knowledge-graph.mmd
knowledge_extractor.pyImplicit knowledge extraction
--path
Project path<br>
--language
Programming language
implicit-knowledge.json
extract_docs.pyDocumentation and API extraction
--path
Project path<br>
--language
Programming language
docs-metadata.json
analyze_dependencies.pyDependency relationship analysis
--path
Project path<br>
--format
Output format		Dependency graph (JSON/Mermaid)

参考文档

Reference Documents

文档用途何时读取
frameworks/index.md框架指引索引（最重要）检测到框架后查阅
knowledge-base-guide.md知识库构建指南构建知识库时参考
knowledge-structure.md知识结构组织设计知识分类时参考
readme-template.mdREADME 生成模板生成项目 README
api-doc-guide.mdAPI 文档生成规范生成 API 文档
architecture-guide.md架构文档生成指南生成架构文档
mermaid-syntax.mdMermaid 图表语法生成可视化图表
DocumentPurposeWhen to Read
frameworks/index.mdFramework Guide Index (Most Important)After detecting frameworks
knowledge-base-guide.mdKnowledge base construction guideWhen building a knowledge base
knowledge-structure.mdKnowledge structure organizationWhen designing knowledge classification
readme-template.mdREADME generation templateWhen generating project README
api-doc-guide.mdAPI documentation generation specificationWhen generating API documentation
architecture-guide.mdArchitecture documentation generation guideWhen generating architecture documentation
mermaid-syntax.mdMermaid diagram syntaxWhen generating visual diagrams

常见问题

FAQs

Q1: 如何快速定位框架指引？

Q1: How to quickly locate framework guides?

A: 步骤 1 执行后，查看 
project-analysis.json
的 
frameworks
字段，例如：
json
{
  "frameworks": ["fastapi", "vue"]
}
然后在 
references/frameworks/index.md
中搜索 
#fastapi
和 
#vue
即可跳转到对应章节。
A: After executing Step 1, check the 
frameworks
field in 
project-analysis.json
, for example：
json
{
  "frameworks": ["fastapi", "vue"]
}
Then search for 
#fastapi
and 
#vue
in 
references/frameworks/index.md
to jump to the corresponding sections.

Q2: 支持哪些编程语言？

Q2: Which programming languages are supported?

A: 当前支持的语言：
  • Python、JavaScript、Java、Go、Rust
  • C/C++、Ruby、PHP、Dart
A: Currently supported languages：
  • Python, JavaScript, Java, Go, Rust
  • C/C++, Ruby, PHP, Dart

Q3: 框架检测准确吗？

Q3: Is framework detection accurate?

A: 基于多维度特征识别：
  1. 依赖包检测（package.json、requirements.txt 等）
  2. 文件模式检测（.vue、.jsx、manage.py 等）
  3. 目录结构检测（src-tauri/、android/ 等）
  4. 代码模式检测（@app.route、@SpringBootApplication 等）
即使没有明确依赖，也能通过文件和代码特征推断。
A: Identified based on multi-dimensional features：
  1. Dependency package detection (package.json, requirements.txt, etc.)
  2. File pattern detection (*.vue, *.jsx, manage.py, etc.)
  3. Directory structure detection (src-tauri/, android/, etc.)
  4. Code pattern detection (@app.route, @SpringBootApplication, etc.)
It can infer frameworks through file and code features even without explicit dependencies.

Q4: 知识图谱如何可视化？

Q4: How to visualize the knowledge graph?

A: 两种方式：
方式 1：直接渲染 Mermaid
bash
undefined
A: Two methods：
Method 1: Directly Render Mermaid
bash
undefined

生成 Mermaid 文件

Generate Mermaid file

python3 scripts/knowledge_graph.py --path ./your-project --format mermaid
python3 scripts/knowledge_graph.py --path ./your-project --format mermaid

使用支持的 Markdown 编辑器（如 Typora、GitHub）打开 knowledge-graph.mmd

Open knowledge-graph.mmd with a Markdown editor that supports Mermaid (e.g., Typora, GitHub)


**方式 2：在线渲染**
- 复制 `knowledge-graph.mmd` 内容到 https://mermaid.live/
- 或使用 VS Code 的 Mermaid 插件

---

**Method 2: Online Rendering**
- Copy the content of `knowledge-graph.mmd` to https://mermaid.live/
- Or use the Mermaid plugin for VS Code

---

Q5: 如何增量更新知识库？

Q5: How to incrementally update the knowledge base?

A: 重新执行受影响的步骤：
  • 代码变更 → 重新运行 
    analyze_project.py
  • 架构调整 → 重新运行 
    knowledge_graph.py
  • 需求更新 → 重新运行 
    knowledge_extractor.py
建议将上述脚本集成到 CI/CD 流程中。
A: Re-execute the affected steps：
  • Code changes → Re-run 
    analyze_project.py
  • Architecture adjustments → Re-run 
    knowledge_graph.py
  • Requirements updates → Re-run 
    knowledge_extractor.py
It is recommended to integrate the above scripts into the CI/CD pipeline.

Q6: 隐性知识提取的原理是什么？

Q6: What is the principle of implicit knowledge extraction?

A: 通过以下方式挖掘隐性知识：
  • 注释分析：提取设计理由和权衡说明
  • 代码模式：识别设计模式（单例、工厂等）
  • 命名约定：分析类名、函数名的设计意图
  • 依赖关系：通过模块依赖推断架构决策
智能体会将这些结构化数据转化为自然语言描述。
A: Implicit knowledge is mined through the following methods：
  • Comment Analysis: Extract design rationales and trade-off explanations
  • Code Patterns: Identify design patterns (Singleton, Factory, etc.)
  • Naming Conventions: Analyze the design intent of class names and function names
  • Dependency Relationships: Infer architecture decisions through module dependencies
The agent converts this structured data into natural language descriptions.

Q7: 生成文档的格式可以自定义吗？

Q7: Can the format of generated documents be customized?

A: 可以。参考 
references/
目录下的模板文件：
  • readme-template.md - README 模板
  • api-doc-guide.md - API 文档格式
  • architecture-guide.md - 架构文档格式
智能体会根据模板生成文档，你可以修改模板来自定义格式。
A: Yes. Refer to the template files in the 
references/
directory：
  • readme-template.md - README template
  • api-doc-guide.md - API documentation format
  • architecture-guide.md - Architecture documentation format
The agent generates documents based on the templates, and you can modify the templates to customize the format.