project-to-obsidian

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 スキーマを統一する

# 项目文档统一使用以下字段
---
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/CD

STEP 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名称}}

> {{描述}}

## 请求

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

パラメーター

パラメーター	型	必須	説明
{{パラメーターテーブル}}

リクエスト例

{{请求示例}}

レスポンス

成功レスポンス

{{响应示例}}

関連項目

• [[{{関連API}}]]
• [[{{関連モジュール}}]]

### 模块说明模板

```markdown
---
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 に除外設定を追加する（任意） └─ ドキュメントとコードのバージョン管理を同期する

---

## 🎯 使用示例

### 示例 1: 完整转换

ユーザー：/p2o /Users/jun/Projects/my-api

Claude：

1. プロジェクトをスキャン中… Node.js + Express プロジェクトを検出しました
2. コードを分析中… API エンドポイント 15 件、主要モジュール 8 件を検出しました
3. 質問：出力先はどこにしますか？
   • [1] 現在の Obsidian vault（Projects/ フォルダー）
   • [2] 新しいフォルダーを作成
   • [3] プロジェクト内の /docs
4. ユーザーが [1] を選択
5. Obsidian vault にドキュメントを生成
6. 完了！ノートファイルを 23 件生成しました

### 示例 2: 快速概览

ユーザー：/p2o ~/code/rust-project --quick

Claude：

1. プロジェクト構造をクイックスキャン
2. 以下を生成：
   • プロジェクト概要.md
   • ディレクトリ構造.md
   • 技術スタック.md
3. 指定された場所に 3 ファイルを出力

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

ユーザー：/p2o ./backend --api

Claude：

1. API ルートファイルをスキャン
2. すべてのエンドポイントを抽出
3. API ドキュメント一式を生成
4. Obsidian に出力

---

## 🔗 与其他工具集成

### 与 obsidian-helper 集成

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

/daily → 日記に「今日は [[my-api-知识库/03-API文档/用户认证|ユーザー認証 API]] を調査した」と記録します

/capture API設計 新しい設計パターンを発見 → 関連する API ドキュメントに自動でリンクします

/review weekly → プロジェクト関連ノートの変更を振り返りに含めます

### 与 MCP 工具集成

生成後は MCP ツールを使用できます： ├─ obsidian_simple_search - プロジェクトドキュメントを検索 ├─ obsidian_patch_content - ドキュメントを更新 ├─ obsidian_get_file_contents - ドキュメントを読み込む └─ obsidian_append_content - 新しいドキュメントを追加

---

## ⚙️ 配置选项

在目标 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

---

🚨 エラー処理

状況	対応
プロジェクトのパスが存在しない	パスを確認するようユーザーに案内
プロジェクトが大きすぎる（>1000 ファイル）	--quick モードの使用、またはサブディレクトリの指定を提案
プロジェクトの種類を判別できない	言語／フレームワークを手動で指定するようユーザーに尋ねる
MCP に接続されていない	ローカルファイルへの出力に自動で切り替える
書き込みに失敗	ロールバックし、エラーの原因を通知

---

📚 対応するプロジェクトの種類

言語／フレームワーク	判別サイン	特別な処理
Node.js	package.json	scripts、dependencies を抽出
TypeScript	tsconfig.json	型定義を抽出
Python	pyproject.toml, setup.py	docstrings を抽出
Go	go.mod	パッケージ構造を抽出
Rust	Cargo.toml	crate 構造を抽出
Java	pom.xml, build.gradle	クラスとインターフェースを抽出
React/Vue/Angular	フレームワーク設定	コンポーネント構造を抽出
Express/FastAPI/Gin	ルートファイル	API エンドポイントを抽出

---

📎 クイックリファレンス

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

---

Project to Obsidian v1.0.0 - コードの知識を可視化