project-to-obsidian

Project to Obsidian - Project Knowledge Base Generator

Convert any code project into a structured Obsidian knowledge base, making project knowledge searchable, linkable, and extensible.

🎯 Core Features

Command	Feature	Description
`/p2o <项目路径>`	Full Conversion	Analyze the project and generate a complete Obsidian vault
`/p2o <路径> --quick`	Quick Overview	Generate only the project overview and structure
`/p2o <路径> --api`	API Documentation	Focus on generating API/function documentation
`/p2o <路径> --arch`	Architecture Documentation	Generate architecture and design documentation

⚡ Execution Flow

用户意图: "把这个项目转成知识库" / /p2o
              ↓
┌─────────────────────────────────────────────────────────┐
│  PHASE 0: 用户确认（必须）                                │
│                                                         │
│  Claude 使用 AskUserQuestion 工具询问：                   │
│                                                         │
│  "检测到你想将项目转换为 Obsidian 知识库，请确认："        │
│                                                         │
│  📁 项目路径: /path/to/project                           │
│                                                         │
│  选择输出方式：                                           │
│  [1] 写入 Obsidian vault（需要 MCP）                     │
│  [2] 创建本地文件夹                                       │
│  [3] 输出到项目 /docs 目录                                │
│  [4] 取消                                                │
│                                                         │
│  用户选择后才继续执行。                                    │
└─────────────────────────────────────────────────────────┘
              ↓
        用户确认后
              ↓
┌─────────────────────────────────────────────────────────┐
│  PHASE 1: 项目扫描                                       │
│  ├─ 读取项目结构 (Glob + Bash ls/find)                   │
│  ├─ 识别项目类型 (package.json/Cargo.toml/go.mod 等)     │
│  ├─ 检测主要语言和框架                                    │
│  └─ 生成文件清单                                         │
└─────────────────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────┐
│  PHASE 2: 代码分析                                       │
│  ├─ 读取关键文件 (入口、配置、核心模块)                    │
│  ├─ 提取：                                               │
│  │   ├─ 函数/类/接口定义                                 │
│  │   ├─ API 端点                                        │
│  │   ├─ 依赖关系                                        │
│  │   ├─ 配置项                                          │
│  │   └─ 注释和文档字符串                                 │
│  └─ 构建代码知识图谱                                     │
└─────────────────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────┐
│  PHASE 3: 文档生成                                       │
│  ├─ 生成 Obsidian 目录结构                               │
│  ├─ 创建各类文档：                                       │
│  │   ├─ 00-项目概览.md (MOC)                            │
│  │   ├─ 01-快速开始.md                                  │
│  │   ├─ 02-架构设计.md                                  │
│  │   ├─ 03-API文档/                                     │
│  │   ├─ 04-模块说明/                                    │
│  │   ├─ 05-配置参考.md                                  │
│  │   └─ 06-开发指南.md                                  │
│  └─ 添加双向链接 [[]] 和标签 #tag                        │
└─────────────────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────┐
│  PHASE 4: 输出到 Obsidian                                │
│  ├─ 方式A: 写入 00_Inbox/AI/{{项目名}}/ (推荐，先落地)    │
│  ├─ 方式B: 写入 30_Resources/Projects/{{项目名}}/        │
│  └─ 方式C: 创建本地文件夹                                 │
└─────────────────────────────────────────────────────────┘
              ↓
         完成报告

⚠️ AI Write Rules (must be followed)

Rule 1: Land by default in the AI zone

首选位置: 00_Inbox/AI/{{项目名}}-知识库/
用户确认后可移动到: 30_Resources/Projects/

Rule 2: Use append-style writes

✅ obsidian_append_content - 创建新文件
✅ obsidian_patch_content - 追加到指定位置
❌ 不要覆盖已存在的笔记

Rule 3: Unified Properties Schema

# 项目文档统一使用以下字段
---
type: project-doc          # project-doc | api | module | architecture
project: "{{项目名}}"
source: "{{项目路径}}"
language: ""               # typescript | python | go | rust | java
framework: ""              # react | express | fastapi | gin
tags: []
created: {{date}}
---

Rule 4: Generate a Dataview index

在项目概览中自动添加 Dataview 查询：
- 模块列表
- API 端点列表
- 最近修改

📋 Detailed Execution Steps

STEP 0: User Confirmation (must be executed first)

When the skill is triggered, Claude must first use the AskUserQuestion tool to ask the user:

AskUserQuestion:
  question: "检测到你想将项目转换为 Obsidian 知识库"
  header: "确认"
  options:
    - label: "写入 Obsidian vault"
      description: "使用 MCP 直接写入你的 Obsidian 库（推荐）"
    - label: "创建本地文件夹"
      description: "在指定位置创建新的知识库文件夹"
    - label: "输出到 /docs"
      description: "在当前项目目录下创建 docs/obsidian/"
    - label: "取消"
      description: "不执行转换"

When the user selects "Cancel", stop immediately and do not execute subsequent steps.

After the user confirms, continue to display the project information and ask about the generation mode:

AskUserQuestion:
  question: "选择生成模式"
  header: "模式"
  options:
    - label: "完整模式"
      description: "生成全部文档：概览、架构、API、模块说明"
    - label: "快速模式"
      description: "只生成项目概览和目录结构"
    - label: "API 文档"
      description: "专注生成 API/接口文档"

STEP 1: Project Scan

# Claude 执行的分析逻辑

# 1. 获取项目结构
使用 Glob 工具扫描：
- **/*.{js,ts,py,go,rs,java,rb,php,swift,kt}  # 代码文件
- **/package.json, **/Cargo.toml, **/go.mod   # 项目配置
- **/*.{md,txt}                                # 文档
- **/.env*, **/config.*                        # 配置文件

# 2. 识别项目类型
检测标志文件：
- package.json → Node.js/前端项目
- Cargo.toml → Rust 项目
- go.mod → Go 项目
- pyproject.toml/setup.py → Python 项目
- pom.xml/build.gradle → Java 项目
- Gemfile → Ruby 项目

# 3. 识别框架
检测特征：
- next.config.* → Next.js
- vite.config.* → Vite
- tsconfig.json → TypeScript
- Dockerfile → Docker 化项目
- .github/workflows → CI/CD

STEP 3: Code Analysis

对每个关键文件，Claude 需要提取：

├─ 入口文件 (main.*, index.*, app.*)
│   ├─ 应用初始化流程
│   ├─ 路由配置
│   └─ 中间件设置
│
├─ API/路由文件
│   ├─ 端点路径
│   ├─ HTTP 方法
│   ├─ 请求参数
│   └─ 响应格式
│
├─ 模型/类型定义
│   ├─ 数据结构
│   ├─ 接口定义
│   └─ 类型别名
│
├─ 服务/业务逻辑
│   ├─ 核心函数
│   ├─ 业务流程
│   └─ 外部调用
│
└─ 配置文件
    ├─ 环境变量
    ├─ 功能开关
    └─ 第三方配置

STEP 4: Generate Obsidian Structure

生成的 Obsidian 目录结构：

{{项目名}}-知识库/
├─ 00-项目概览.md          # MOC - 主入口
├─ 01-快速开始.md          # 安装、运行、基本使用
├─ 02-架构设计/
│   ├─ 整体架构.md
│   ├─ 目录结构.md
│   └─ 技术栈.md
├─ 03-API文档/
│   ├─ _API索引.md         # API MOC
│   ├─ 用户相关.md
│   ├─ 订单相关.md
│   └─ ...
├─ 04-模块说明/
│   ├─ _模块索引.md        # 模块 MOC
│   ├─ 核心模块.md
│   ├─ 工具函数.md
│   └─ ...
├─ 05-配置参考.md          # 环境变量、配置项
├─ 06-开发指南/
│   ├─ 本地开发.md
│   ├─ 测试指南.md
│   └─ 部署流程.md
└─ _templates/             # Obsidian 模板
    ├─ 新功能模板.md
    └─ Bug记录模板.md

📝 Document Templates

Project Overview Template (MOC)

---
tags: [project, moc, {{项目类型}}]
created: {{日期}}
---

# {{项目名}} 知识库

> {{一句话描述}}

## 🚀 快速导航

- [[01-快速开始|快速开始]] - 5 分钟上手
- [[02-架构设计/整体架构|架构设计]] - 了解系统设计
- [[03-API文档/_API索引|API 文档]] - 接口参考

## 📊 项目信息

| 属性 | 值 |
|------|-----|
| 语言 | {{主语言}} |
| 框架 | {{框架}} |
| 版本 | {{版本}} |
| 仓库 | {{仓库地址}} |

## 🗂️ 目录结构


## 🔗 核心模块

{{模块链接列表}}

## 📅 最近更新

- {{更新记录}}

---
*由 project-to-obsidian 自动生成*

API Documentation Template

---
tags: [api, {{模块}}]
endpoint: {{路径}}
method: {{方法}}
---

# {{API名称}}

> {{描述}}

## 请求

```http
{{方法}} {{路径}}

Parameter

Parameter	Type	Required	Description
{{parameter table}}

Request Example

{{请求示例}}

Response

Success Response

{{响应示例}}

[[{{related API}}]]
[[{{related module}}]]


### 模块说明模板

```markdown
---
tags: [module, {{标签}}]
path: {{文件路径}}
---

# {{模块名}}

> {{模块描述}}

## 职责

{{职责说明}}

## 核心函数

### `{{函数名}}`

```{{语言}}
{{函数签名}}

Parameters: {{parameter description}}

Returns: {{return description}}

Example:

{{使用示例}}

Dependencies

graph LR
    {{模块}} --> {{依赖1}}
    {{模块}} --> {{依赖2}}

Related Modules

[[{{related module 1}}]]
[[{{related module 2}}]]


---

## 🔧 输出选项

### 选项 1: 输出到 Obsidian Vault (推荐)

If Obsidian MCP is detected as available: ├─ Ask the user to select a target vault ├─ Create the project folder in the vault ├─ Use obsidian_append_content to write files └─ After completion, the obsidian-helper feature can be used directly


### 选项 2: 创建本地文件夹

├─ Ask for the output path ├─ Create the {{project name}}-knowledge-base/ folder ├─ Use the Write tool to write all files └─ Prompt the user to open that folder in Obsidian


### 选项 3: 输出到项目 /docs

├─ Create the /docs/obsidian/ folder in the project directory ├─ Write all documentation ├─ Add .gitignore exclusions (optional) └─ Documentation and code are synchronized under version control


---

## 🎯 使用示例

### 示例 1: 完整转换

User: /p2o /Users/jun/Projects/my-api

Claude:

Scanning project... Node.js + Express project detected
Analyzing code... found 15 API endpoints, 8 core modules
Prompt: Where to output?
- [1] Current Obsidian vault (Projects/ folder)
- [2] New folder
- [3] In-project /docs
User selected [1]
Generate documentation to Obsidian vault
Done! Generated 23 note files


### 示例 2: 快速概览

User: /p2o ~/code/rust-project --quick

Claude:

Quickly scan project structure
Generate:
- Project Overview.md
- Directory Structure.md
- Tech Stack.md
Output 3 files to the specified location


### 示例 3: 只生成 API 文档

User: /p2o ./backend --api

Claude:

Scan API route files
Extract all endpoints
Generate API documentation collection
Output to Obsidian


---

## 🔗 与其他工具集成

### 与 obsidian-helper 集成

生成的知识库完全兼容 obsidian-helper：

/daily → Record in the diary: "Today I studied [[my-api-knowledge-base/03-API-Documentation/User Authentication|User Authentication API]]"

/capture API design Discovered a new design pattern → Automatically link to related API documentation

/review weekly → The review includes modifications to project-related notes


### 与 MCP 工具集成

After generation, you can use MCP tools: ├─ obsidian_simple_search - Search project documentation ├─ obsidian_patch_content - Update documentation ├─ obsidian_get_file_contents - Read documentation └─ obsidian_append_content - Add new documentation


---

## ⚙️ 配置选项

在目标 vault 创建 `_config/project-to-obsidian.md` 自定义：

```markdown
# Project to Obsidian 配置

## 生成选项
- 生成 Mermaid 图表: true
- 生成代码示例: true
- 提取注释: true
- 最大文件大小: 100KB

## 忽略规则
- 忽略文件夹: node_modules, .git, dist, build, __pycache__
- 忽略文件: *.min.js, *.map, *.lock

## 输出设置
- 默认输出位置: Projects/
- 文档语言: zh-CN
- 链接样式: wiki-link

🚨 Error Handling

Situation	Handling
Project path does not exist	Prompt the user to check the path
Project too large (>1000 files)	Recommend using --quick mode or specifying a subdirectory
Unable to identify project type	Ask the user to manually specify the language/framework
MCP not connected	Automatically switch to local file output
Write failed	Roll back and indicate the reason for the error

📚 Supported Project Types

Language/Framework	Identification Marker	Special Handling
Node.js	package.json	Extract scripts, dependencies
TypeScript	tsconfig.json	Extract type definitions
Python	pyproject.toml, setup.py	Extract docstrings
Go	go.mod	Extract package structure
Rust	Cargo.toml	Extract crate structure
Java	pom.xml, build.gradle	Extract classes and interfaces
React/Vue/Angular	Framework configuration	Extract component structure
Express/FastAPI/Gin	Route files	Extract API endpoints

📎 Quick Reference

/p2o <路径>              → 完整转换项目到 Obsidian
/p2o <路径> --quick      → 快速生成概览
/p2o <路径> --api        → 只生成 API 文档
/p2o <路径> --arch       → 只生成架构文档
/p2o <路径> -o <输出>    → 指定输出位置

Project to Obsidian v1.0.0 - Make code knowledge visual

About this skill

🎯 Core Features

⚡ Execution Flow

⚠️ AI Write Rules (must be followed)

Rule 1: Land by default in the AI zone

Rule 2: Use append-style writes

Rule 3: Unified Properties Schema

Rule 4: Generate a Dataview index

📋 Detailed Execution Steps

STEP 0: User Confirmation (must be executed first)

STEP 1: Project Scan

STEP 3: Code Analysis

STEP 4: Generate Obsidian Structure

📝 Document Templates

Project Overview Template (MOC)

API Documentation Template

Parameter

Request Example

Response

Success Response

Related

Dependencies

Related Modules

🚨 Error Handling

📚 Supported Project Types

📎 Quick Reference