Project to Obsidian - 项目知识库生成器
将任意代码项目转换为结构化的 Obsidian 知识库，让项目知识可搜索、可链接、可扩展。
🎯 核心功能
| 命令 | 功能 | 说明 | |------|------|------| | /p2o <项目路径> | 完整转换 | 分析项目并生成完整 Obsidian 库 | | /p2o <路径> --quick | 快速概览 | 只生成项目概览和结构 | | /p2o <路径> --api | API 文档 | 专注生成 API/函数文档 | | /p2o <路径> --arch | 架构文档 | 生成架构和设计文档 |
⚡ 执行流程
用户意图: "把这个项目转成知识库" / /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 写入规则（必须遵守）
规则 1: 默认落地到 AI 专区
首选位置: 00_Inbox/AI/{{项目名}}-知识库/
用户确认后可移动到: 30_Resources/Projects/规则 2: 使用追加式写入
✅ obsidian_append_content - 创建新文件
✅ obsidian_patch_content - 追加到指定位置
❌ 不要覆盖已存在的笔记规则 3: 统一 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}}
---规则 4: 生成 Dataview 索引
在项目概览中自动添加 Dataview 查询：
- 模块列表
- API 端点列表
- 最近修改📋 详细执行步骤
STEP 0: 用户确认（必须先执行）
当 skill 被触发时，Claude 必须首先使用 AskUserQuestion 工具询问用户：
AskUserQuestion:
question: "检测到你想将项目转换为 Obsidian 知识库"
header: "确认"
options:
- label: "写入 Obsidian vault"
description: "使用 MCP 直接写入你的 Obsidian 库（推荐）"
- label: "创建本地文件夹"
description: "在指定位置创建新的知识库文件夹"
- label: "输出到 /docs"
description: "在当前项目目录下创建 docs/obsidian/"
- label: "取消"
description: "不执行转换"用户选择「取消」时，立即停止，不执行后续步骤。
用户确认后，继续显示项目信息并询问生成模式：
AskUserQuestion:
question: "选择生成模式"
header: "模式"
options:
- label: "完整模式"
description: "生成全部文档：概览、架构、API、模块说明"
- label: "快速模式"
description: "只生成项目概览和目录结构"
- label: "API 文档"
description: "专注生成 API/接口文档"STEP 1: 项目扫描
# 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/CDSTEP 3: 代码分析
对每个关键文件，Claude 需要提取：
├─ 入口文件 (main.*, index.*, app.*)
│ ├─ 应用初始化流程
│ ├─ 路由配置
│ └─ 中间件设置
│
├─ API/路由文件
│ ├─ 端点路径
│ ├─ HTTP 方法
│ ├─ 请求参数
│ └─ 响应格式
│
├─ 模型/类型定义
│ ├─ 数据结构
│ ├─ 接口定义
│ └─ 类型别名
│
├─ 服务/业务逻辑
│ ├─ 核心函数
│ ├─ 业务流程
│ └─ 外部调用
│
└─ 配置文件
├─ 环境变量
├─ 功能开关
└─ 第三方配置STEP 4: 生成 Obsidian 结构
生成的 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📝 文档模板
项目概览模板 (MOC)
---
tags: [project, moc, {{项目类型}}]
created: {{日期}}
---
# {{项目名}} 知识库
> {{一句话描述}}
## 🚀 快速导航
- [[01-快速开始|快速开始]] - 5 分钟上手
- [[02-架构设计/整体架构|架构设计]] - 了解系统设计
- [[03-API文档/_API索引|API 文档]] - 接口参考
## 📊 项目信息
| 属性 | 值 |
|------|-----|
| 语言 | {{主语言}} |
| 框架 | {{框架}} |
| 版本 | {{版本}} |
| 仓库 | {{仓库地址}} |
## 🗂️ 目录结构
{{项目结构树}}
## 🔗 核心模块
{{模块链接列表}}
## 📅 最近更新
- {{更新记录}}
---
*由 project-to-obsidian 自动生成*API 文档模板
---
tags: [api, {{模块}}]
endpoint: {{路径}}
method: {{方法}}
---
# {{API名称}}
> {{描述}}
## 请求
{{方法}} {{路径}}
### 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
{{参数表}}
### 请求示例
{{请求示例}}
## 响应
### 成功响应
{{响应示例}}
## 相关
- [[{{相关API}}]]
- [[{{相关模块}}]]模块说明模板
---
tags: [module, {{标签}}]
path: {{文件路径}}
---
# {{模块名}}
> {{模块描述}}
## 职责
{{职责说明}}
## 核心函数
### `{{函数名}}`
{{函数签名}}
**参数：**
{{参数说明}}
**返回：**
{{返回说明}}
**示例：**{{使用示例}}
## 依赖关系
graph LR {{模块}} --> {{依赖1}} {{模块}} --> {{依赖2}}
## 相关模块
- [[{{相关模块1}}]]
- [[{{相关模块2}}]]🔧 输出选项
选项 1: 输出到 Obsidian Vault (推荐)
如果检测到 Obsidian MCP 可用：
├─ 询问用户选择目标 vault
├─ 在 vault 中创建项目文件夹
├─ 使用 obsidian_append_content 写入文件
└─ 完成后可直接使用 obsidian-helper 功能选项 2: 创建本地文件夹
├─ 询问输出路径
├─ 创建 {{项目名}}-knowledge-base/ 文件夹
├─ 使用 Write 工具写入所有文件
└─ 提示用户在 Obsidian 中打开该文件夹选项 3: 输出到项目 /docs
├─ 在项目目录创建 /docs/obsidian/ 文件夹
├─ 写入所有文档
├─ 添加 .gitignore 排除（可选）
└─ 文档与代码同步版本控制-