aifastdb-devplan 1.0.0 → 1.0.2

package/README.md

@@ -1,27 +1,433 @@
 # aifastdb-devplan
 
-AI-powered development plan management MCP server, powered by [aifastdb](https://github.com/aifastdb/aifastdb).
+<p align="center">
+  <strong>AI-Powered Development Plan Management — MCP Server</strong>
+</p>
 
-## 功能
+<p align="center">
+  <a href="https://www.npmjs.com/package/aifastdb-devplan"><img src="https://img.shields.io/npm/v/aifastdb-devplan.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/aifastdb-devplan"><img src="https://img.shields.io/npm/dm/aifastdb-devplan.svg" alt="npm downloads"></a>
+  <a href="https://github.com/aifastdb/aifastdb-devplan/blob/main/LICENSE"><img src="https://img.shields.io/github/license/aifastdb/aifastdb-devplan" alt="license"></a>
+  <a href="https://github.com/aifastdb/aifastdb-devplan"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version"></a>
+</p>
 
-- **11 种标准文档片段类型**：overview, api_design, technical_notes 等
-- **两级任务层级**：主任务 (MainTask) + 子任务 (SubTask)
-- **功能模块注册表**：按模块维度聚合任务和文档
-- **Git Commit 锚定**：完成任务时记录 Git commit hash，支持回滚检测
-- **自动进度统计**：完成子任务时自动更新主任务进度
-- **Markdown 导出**：生成开发计划的 Markdown 文档
+<p align="center">
+  Let AI assistants (Cursor / Claude Desktop) manage your development plans, task tracking, and project documentation.<br/>
+  Built on the <a href="https://github.com/aifastdb/aifastdb">aifastdb</a> high-performance storage engine, seamlessly integrated with AI via the <a href="https://modelcontextprotocol.io">MCP protocol</a>.
+</p>
 
-## 安装
+<p align="center">
+  让 AI 助手（Cursor / Claude Desktop）直接管理你的开发计划、任务追踪和项目文档。<br/>
+  基于 <a href="https://github.com/aifastdb/aifastdb">aifastdb</a> 高性能存储引擎，通过 <a href="https://modelcontextprotocol.io">MCP 协议</a> 与 AI 无缝集成。
+</p>
+
+<p align="center">
+  <a href="#english">English</a> | <a href="#中文">中文</a>
+</p>
+
+---
+
+<a id="english"></a>
+
+## English
+
+### Why aifastdb-devplan?
+
+In the age of AI-assisted programming, developers collaborate with AI assistants more closely than ever. However, AI assistants lack **persistent project memory** — each conversation starts from scratch, with no knowledge of the overall project plan, current progress, or historical decisions.
+
+**aifastdb-devplan** solves this problem by providing AI assistants with a set of **structured development plan management tools**, enabling AI to:
+
+- 📋 **Understand the big picture** — Read project overviews, technical designs, API specifications, and more
+- 🎯 **Track task progress** — Manage two-level task hierarchies (MainTask → SubTask) with real-time progress updates
+- 🔗 **Anchor to Git history** — Automatically record Git commit hashes when completing tasks, with rollback detection
+- 📦 **Modular management** — Organize tasks and docs by feature modules for a clear project architecture view
+- 📄 **Export documentation** — Generate complete Markdown-formatted development plan documents in one click
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Dual Storage Engine** | Choose between `graph` (SocialGraphV2, default) or `document` (JSONL) per project |
+| **Graph Visualization** | Built-in HTTP server + vis-network page to visualize tasks/modules as an interactive graph |
+| **11 Document Section Types** | overview, requirements, api_design, technical_notes, architecture, and more |
+| **Two-Level Task Hierarchy** | MainTask + SubTask with priority levels (P0–P3) and status transitions |
+| **Module Registry** | Aggregate tasks and docs by module for intuitive project architecture |
+| **Git Commit Anchoring** | Auto-record commit hash on task completion; `sync_git` detects rollbacks |
+| **Auto Progress Tracking** | Automatically update parent task progress when subtasks are completed |
+| **Idempotent Task Import** | `upsert_task` prevents duplicates, ideal for batch initialization |
+| **Data Migration** | Seamlessly migrate between `document` and `graph` engines with backup support |
+| **Markdown Export** | Generate structured development plan documents for sharing and archiving |
+| **Zero-Config Storage** | Local storage in the project's `.devplan/` directory — no external database needed |
+
+### Quick Start
+
+#### Installation
+
+```bash
+npm install -g aifastdb-devplan
+```
+
+#### Option A: As an MCP Server (Recommended)
+
+Configure in Cursor IDE (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "npx",
+      "args": ["aifastdb-devplan"]
+    }
+  }
+}
+```
+
+Or in Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "npx",
+      "args": ["aifastdb-devplan"]
+    }
+  }
+}
+```
+
+Once configured, your AI assistant can use 20 `devplan_*` tools to manage your development plans.
+
+#### Option B: As an npm Package (Programmatic)
+
+```typescript
+import { DevPlanStore, createDevPlan } from 'aifastdb-devplan';
+
+const plan = createDevPlan('my-project');
+
+// Create a main task
+plan.createMainTask({
+  projectName: 'my-project',
+  taskId: 'phase-1',
+  title: 'Phase 1: Foundation Setup',
+  priority: 'P0',
+});
+
+// Add a subtask
+plan.addSubTask({
+  projectName: 'my-project',
+  taskId: 'T1.1',
+  parentTaskId: 'phase-1',
+  title: 'Initialize project structure',
+});
+
+// Complete task (auto-updates progress + Git commit anchoring)
+plan.completeSubTask('T1.1');
+
+// Check progress
+const progress = plan.getProgress();
+console.log(progress);
+```
+
+### MCP Tools (20 total)
+
+#### 📋 Document Management
+
+| Tool | Description |
+|------|-------------|
+| `devplan_init` | Initialize a development plan (auto-detects storage engine) |
+| `devplan_save_section` | Save/update a document section (11 standard types) |
+| `devplan_get_section` | Read a specific document section |
+| `devplan_list_sections` | List all document sections |
+
+#### 🎯 Task Management
+
+| Tool | Description |
+|------|-------------|
+| `devplan_create_main_task` | Create a main task (priority P0–P3) |
+| `devplan_add_sub_task` | Add a subtask to a main task |
+| `devplan_upsert_task` | Idempotent task import (deduplication) |
+| `devplan_complete_task` | Complete a task (auto-updates progress + Git anchoring) |
+| `devplan_list_tasks` | List tasks (filter by status/priority/parent) |
+| `devplan_get_progress` | Get overall project progress |
+
+#### 📦 Module Management
+
+| Tool | Description |
+|------|-------------|
+| `devplan_create_module` | Create a feature module |
+| `devplan_list_modules` | List all feature modules |
+| `devplan_get_module` | Get module details (linked tasks and docs) |
+| `devplan_update_module` | Update module information |
+
+#### 🔧 Utilities
+
+| Tool | Description |
+|------|-------------|
+| `devplan_export_markdown` | Export full Markdown development plan |
+| `devplan_export_graph` | Export graph structure `{ nodes, edges }` for visualization (graph engine only) |
+| `devplan_migrate_engine` | Migrate data between `document` and `graph` engines |
+| `devplan_sync_git` | Sync Git history and detect rollbacks |
+| `devplan_start_visual` | Start the graph visualization HTTP server and open browser |
+
+### Dual Storage Engine
+
+Each project can independently choose its storage engine:
+
+| Engine | Backend | Default | Features |
+|--------|---------|---------|----------|
+| `graph` | SocialGraphV2 (WAL + sharding) | ✅ New projects | Graph visualization, entity-relation model |
+| `document` | EnhancedDocumentStore (JSONL) | Auto-detected for legacy | Lightweight, human-readable files |
+
+Engine selection priority:
+1. Explicit `engine` parameter in `createDevPlan()`
+2. `.devplan/{project}/engine.json` configuration
+3. Auto-detect existing JSONL files → `document`
+4. New projects → `graph`
+
+### Graph Visualization
+
+Visualize your development plan as an interactive graph:
+
+```bash
+npm run visualize -- --project my-project --base-path /path/to/.devplan
+# or
+aifastdb-devplan-visual --project my-project --port 3210
+```
+
+The built-in HTTP server serves a self-contained HTML page with [vis-network](https://visjs.github.io/vis-network/), featuring:
+
+- **5 node types**: project (star), module (diamond), main-task (circle), sub-task (dot), document (box)
+- **Status-based coloring**: completed (green), in-progress (blue), pending (gray)
+- **Interactive features**: click for details panel, filter by type, stats bar with progress
+- **Dark theme**: consistent with modern development tools
+
+### Enable DevPlan in Other Projects (Step-by-Step Guide)
+
+Here's a complete guide to enable devplan in any project (e.g., `my-app`).
+
+#### Method 1: npm Published Version (Recommended)
+
+**Step 1: Install globally**
+
+```bash
+npm install -g aifastdb-devplan
+```
+
+**Step 2: Configure MCP Server in your project**
+
+Create `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "npx",
+      "args": ["aifastdb-devplan"]
+    }
+  }
+}
+```
+
+**Step 3: Start using with AI assistant**
+
+Open Cursor in your project directory and tell the AI:
+
+```
+Initialize a development plan for my-app project
+```
+
+The AI will call `devplan_init` and data will be stored in `.devplan/my-app/` under your project root (auto-detected via `.git` or `package.json`).
+
+#### Method 2: Local Development Version
+
+If you're working with a local clone of `aifastdb-devplan` (not yet published or testing changes):
+
+**Step 1: Build locally**
+
+```bash
+cd /path/to/aifastdb-devplan
+npm install
+npm run build
+```
+
+**Step 2: Configure MCP Server with local path**
+
+Create `.cursor/mcp.json` in your target project:
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "node",
+      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+Windows example:
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "node",
+      "args": ["D:/Project/git/aifastdb-devplan/dist/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+#### Controlling Data Storage Location
+
+By default, devplan auto-detects your project root and stores data in `.devplan/`. You can override this:
+
+**Option A: Environment variable (global override)**
+
+```bash
+# All devplan data will be stored under this path
+export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans
+```
+
+**Option B: `--base-path` for visualization server**
+
+```bash
+# View another project's devplan graph
+aifastdb-devplan-visual --project my-app --base-path /path/to/my-app/.devplan --port 3210
+```
+
+#### `--base-path` Parameter Details
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--project` | Project name (must match the name used in `devplan_init`) | **Required** |
+| `--base-path` | Absolute path to the `.devplan` directory | Auto-detect via `.git` / `package.json`, fallback to `~/.aifastdb/dev-plans/` |
+| `--port` | HTTP server port | `3210` |
+
+**Data directory structure** under `--base-path`:
+
+```
+<base-path>/
+└── <project-name>/
+    ├── engine.json        # Engine config
+    ├── graph-data/        # Graph engine data (WAL shards)
+    ├── documents.jsonl    # Document engine data
+    ├── tasks.jsonl
+    └── modules.jsonl
+```
+
+#### Complete Example: Managing "my-app" from Scratch
 
 ```bash
-npm install aifastdb-devplan
+# 1. Install devplan globally
+npm install -g aifastdb-devplan
+
+# 2. Go to your project
+cd /path/to/my-app
+
+# 3. Create MCP config
+mkdir -p .cursor
+echo '{"mcpServers":{"aifastdb-devplan":{"command":"npx","args":["aifastdb-devplan"]}}}' > .cursor/mcp.json
+
+# 4. Open in Cursor and tell AI:
+#    "Initialize devplan for my-app, create Phase 1 with 3 subtasks"
+
+# 5. Visualize the plan graph
+npx aifastdb-devplan-visual --project my-app --base-path .devplan --port 3210
+```
+
+### Data Storage
+
+Data is stored locally — **no external database required**:
+
+```
+.devplan/{projectName}/
+├── engine.json        # Engine configuration (graph or document)
+├── documents.jsonl    # Document sections (document engine)
+├── tasks.jsonl        # Main tasks + subtasks (document engine)
+├── modules.jsonl      # Feature modules (document engine)
+└── graph-data/        # WAL-based graph storage (graph engine)
+    └── wal/           # Write-ahead log shards
 ```
 
-## 使用方式
+Storage path resolution priority:
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 | `AIFASTDB_DEVPLAN_PATH` env var | Explicitly specify storage directory |
+| 2 | `.devplan/` in project root | Auto-detect via `.git` / `package.json` |
+| 3 | `~/.aifastdb/dev-plans/` | Global fallback path |
+
+### Platform Support
+
+`aifastdb-devplan` is a pure TypeScript/JavaScript project, supporting all platforms with Node.js ≥ 18:
+
+| Platform | Architecture | Supported |
+|----------|-------------|-----------|
+| Windows | x64 | ✅ |
+| macOS | x64 / Apple Silicon (M1/M2/M3/M4) | ✅ |
+| Linux | x64 / ARM64 | ✅ |
+
+> Note: The underlying storage engine [aifastdb](https://github.com/aifastdb/aifastdb) includes Rust native bindings with prebuilt binaries for all listed platforms.
+
+---
+
+<a id="中文"></a>
+
+## 中文
+
+### 为什么需要 aifastdb-devplan？
+
+在 AI 辅助编程时代，开发者与 AI 助手的协作越来越密切。但 AI 助手缺乏**持久化的项目记忆**——每次对话都从零开始，无法了解项目的整体规划、当前进度和历史决策。
 
-### 方式 A：作为 MCP Server（推荐）
+**aifastdb-devplan** 解决了这个问题：它为 AI 助手提供了一套**结构化的开发计划管理工具**，让 AI 能够：
+
+- 📋 **了解项目全貌** — 读取项目概述、技术方案、API 设计等文档片段
+- 🎯 **追踪任务进度** — 管理两级任务层级（主任务 → 子任务），实时更新进度
+- 🔗 **锚定 Git 历史** — 完成任务时自动记录 Git commit hash，支持回滚检测
+- 📦 **模块化管理** — 按功能模块组织任务和文档，清晰展示项目架构
+- 📄 **导出文档** — 一键生成完整的 Markdown 格式开发计划文档
+
+### 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| **双存储引擎** | 每个项目可独立选择 `graph`（SocialGraphV2，默认）或 `document`（JSONL）引擎 |
+| **图谱可视化** | 内置 HTTP 服务器 + vis-network 页面，将任务/模块以交互式图谱展示 |
+| **11 种文档片段** | overview, requirements, api_design, technical_notes, architecture 等标准类型 |
+| **两级任务层级** | 主任务 (MainTask) + 子任务 (SubTask)，支持优先级 (P0-P3) 和状态流转 |
+| **功能模块注册表** | 按模块维度聚合任务和文档，直观展示项目架构 |
+| **Git Commit 锚定** | 完成任务时自动记录 commit hash，`sync_git` 可检测代码回滚 |
+| **自动进度统计** | 完成子任务时自动更新主任务进度百分比 |
+| **幂等任务导入** | `upsert_task` 支持防重复导入，适合批量初始化 |
+| **数据迁移** | 在 `document` 和 `graph` 引擎间无缝迁移，支持备份 |
+| **Markdown 导出** | 生成结构化的开发计划文档，方便分享和归档 |
+| **零配置存储** | 本地存储，数据保存在项目 `.devplan/` 目录中，无需外部数据库 |
+
+### 快速开始
+
+#### 安装
+
+```bash
+npm install -g aifastdb-devplan
+```
+
+#### 方式 A：作为 MCP Server 使用（推荐）
+
+在 Cursor IDE 中配置 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "npx",
+      "args": ["aifastdb-devplan"]
+    }
+  }
+}
+```
 
-在 `.cursor/mcp.json` 或 `claude_desktop_config.json` 中配置：
+或在 Claude Desktop 中配置 `claude_desktop_config.json`：
 
 ```json
 {
@@ -34,7 +440,9 @@ npm install aifastdb-devplan
 }
 ```
 
-### 方式 B：作为 npm 包编程使用
+配置完成后，AI 助手即可使用 20 个 `devplan_*` 工具来管理你的开发计划。
+
+#### 方式 B：作为 npm 包编程使用
 
 ```typescript
 import { DevPlanStore, createDevPlan } from 'aifastdb-devplan';
@@ -65,48 +473,269 @@ const progress = plan.getProgress();
 console.log(progress);
 ```
 
-## MCP 工具列表（18 个）
+### MCP 工具一览（20 个）
+
+#### 📋 文档管理
 
 | 工具 | 说明 |
 |------|------|
-| `devplan_init` | 初始化开发计划 |
-| `devplan_save_section` | 保存/更新文档片段 |
-| `devplan_get_section` | 读取文档片段 |
+| `devplan_init` | 初始化开发计划（自动检测存储引擎） |
+| `devplan_save_section` | 保存/更新文档片段（11 种标准类型） |
+| `devplan_get_section` | 读取指定文档片段 |
 | `devplan_list_sections` | 列出所有文档片段 |
-| `devplan_create_main_task` | 创建主任务 |
-| `devplan_add_sub_task` | 添加子任务 |
-| `devplan_upsert_task` | 幂等导入任务（防重复） |
-| `devplan_complete_task` | 完成任务（自动更新进度） |
-| `devplan_list_tasks` | 列出任务（支持跨主任务查询） |
-| `devplan_get_progress` | 获取项目进度概览 |
-| `devplan_export_markdown` | 导出 Markdown 文档 |
-| `devplan_sync_git` | 同步 Git 历史（回滚检测） |
+
+#### 🎯 任务管理
+
+| 工具 | 说明 |
+|------|------|
+| `devplan_create_main_task` | 创建主任务（支持优先级 P0-P3） |
+| `devplan_add_sub_task` | 添加子任务到主任务 |
+| `devplan_upsert_task` | 幂等导入任务（防重复，适合批量初始化） |
+| `devplan_complete_task` | 完成任务（自动更新进度 + Git 锚定） |
+| `devplan_list_tasks` | 列出任务（支持按状态/优先级/主任务筛选） |
+| `devplan_get_progress` | 获取项目整体进度概览 |
+
+#### 📦 模块管理
+
+| 工具 | 说明 |
+|------|------|
 | `devplan_create_module` | 创建功能模块 |
-| `devplan_list_modules` | 列出功能模块 |
-| `devplan_get_module` | 获取模块详情 |
+| `devplan_list_modules` | 列出所有功能模块 |
+| `devplan_get_module` | 获取模块详情（关联任务和文档） |
 | `devplan_update_module` | 更新模块信息 |
 
-## 数据存储
+#### 🔧 工具
+
+| 工具 | 说明 |
+|------|------|
+| `devplan_export_markdown` | 导出完整 Markdown 格式开发计划 |
+| `devplan_export_graph` | 导出图结构 `{ nodes, edges }` 用于可视化（仅 graph 引擎） |
+| `devplan_migrate_engine` | 在 `document` 和 `graph` 引擎间迁移数据 |
+| `devplan_sync_git` | 同步 Git 历史，检测代码回滚 |
+| `devplan_start_visual` | 启动图谱可视化 HTTP 服务器并自动打开浏览器 |
+
+### 双存储引擎
+
+每个项目可独立选择存储引擎：
+
+| 引擎 | 后端 | 默认 | 特点 |
+|------|------|------|------|
+| `graph` | SocialGraphV2（WAL + 分片） | ✅ 新项目 | 图可视化、实体-关系模型 |
+| `document` | EnhancedDocumentStore（JSONL） | 旧项目自动检测 | 轻量、文件可读 |
+
+引擎选择优先级：
+1. `createDevPlan()` 显式传入 `engine` 参数
+2. `.devplan/{project}/engine.json` 配置文件
+3. 已有 JSONL 数据文件 → 自动识别为 `document`
+4. 新项目 → 默认使用 `graph`
 
-数据以 JSONL 格式存储在项目内的 `.devplan/` 目录中：
+### 图谱可视化
+
+将开发计划以交互式图谱形式展示：
+
+```bash
+npm run visualize -- --project my-project --base-path /path/to/.devplan
+# 或
+aifastdb-devplan-visual --project my-project --port 3210
+```
+
+内置 HTTP 服务器提供自包含 HTML 页面，使用 [vis-network](https://visjs.github.io/vis-network/) 渲染：
+
+- **5 种节点类型**：项目（星形）、模块（菱形）、主任务（圆形）、子任务（小圆点）、文档（方形）
+- **状态着色**：已完成（绿色）、进行中（蓝色）、待开始（灰色）
+- **交互功能**：点击查看详情面板、按类型过滤、顶部统计栏 + 进度条
+- **暗色主题**：与现代开发工具风格一致
+
+### 在其它项目中启用 DevPlan（实战指南）
+
+以下是在任意项目（例如 `my-app`）中启用 devplan 的完整步骤。
+
+#### 方式一：使用 npm 发布版本（推荐）
+
+**第 1 步：全局安装**
+
+```bash
+npm install -g aifastdb-devplan
+```
+
+**第 2 步：在目标项目中配置 MCP Server**
+
+在项目根目录创建 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "npx",
+      "args": ["aifastdb-devplan"]
+    }
+  }
+}
+```
+
+**第 3 步：通过 AI 助手开始使用**
+
+在 Cursor 中打开你的项目目录，对 AI 说：
+
+```
+为 my-app 项目初始化开发计划
+```
+
+AI 会调用 `devplan_init`，数据自动存储在项目根目录下的 `.devplan/my-app/` 中（通过 `.git` 或 `package.json` 自动检测项目根目录）。
+
+#### 方式二：使用本地开发版本
+
+如果你在使用本地克隆的 `aifastdb-devplan`（未发布到 npm 或正在测试修改）：
+
+**第 1 步：本地构建**
+
+```bash
+cd /path/to/aifastdb-devplan
+npm install
+npm run build
+```
+
+**第 2 步：使用本地路径配置 MCP Server**
+
+在目标项目中创建 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "node",
+      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+Windows 示例：
+
+```json
+{
+  "mcpServers": {
+    "aifastdb-devplan": {
+      "command": "node",
+      "args": ["D:/Project/git/aifastdb-devplan/dist/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+#### 控制数据存储位置
+
+默认情况下，devplan 会自动检测项目根目录并将数据存储在 `.devplan/` 下。你可以通过以下方式覆盖：
+
+**方案 A：环境变量（全局覆盖）**
+
+```bash
+# 所有 devplan 数据将存储在此路径下
+export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans
+```
+
+Windows PowerShell：
+
+```powershell
+$env:AIFASTDB_DEVPLAN_PATH = "D:\shared\devplans"
+```
+
+**方案 B：可视化服务器使用 `--base-path`**
+
+```bash
+# 查看另一个项目的 devplan 图谱
+aifastdb-devplan-visual --project my-app --base-path /path/to/my-app/.devplan --port 3210
+```
+
+#### `--base-path` 参数详解
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--project` | 项目名称（必须与 `devplan_init` 时使用的名称一致） | **必填** |
+| `--base-path` | `.devplan` 目录的绝对路径 | 自动检测（通过 `.git` / `package.json`），兜底 `~/.aifastdb/dev-plans/` |
+| `--port` | HTTP 服务器端口 | `3210` |
+
+**`--base-path` 下的数据目录结构**：
+
+```
+<base-path>/
+└── <project-name>/
+    ├── engine.json        # 引擎配置
+    ├── graph-data/        # Graph 引擎数据（WAL 分片）
+    ├── documents.jsonl    # Document 引擎数据
+    ├── tasks.jsonl
+    └── modules.jsonl
+```
+
+#### 完整示例：从零管理 "my-app" 项目
+
+```bash
+# 1. 全局安装 devplan
+npm install -g aifastdb-devplan
+
+# 2. 进入你的项目目录
+cd /path/to/my-app
+
+# 3. 创建 MCP 配置
+mkdir -p .cursor
+echo '{"mcpServers":{"aifastdb-devplan":{"command":"npx","args":["aifastdb-devplan"]}}}' > .cursor/mcp.json
+
+# 4. 在 Cursor 中打开项目，对 AI 说：
+#    "为 my-app 初始化开发计划，创建阶段一并添加 3 个子任务"
+
+# 5. 可视化查看计划图谱
+npx aifastdb-devplan-visual --project my-app --base-path .devplan --port 3210
+```
+
+### 数据存储
+
+数据存储在本地，**无需外部数据库**：
 
 ```
 .devplan/{projectName}/
-├── documents.jsonl    # 文档片段
-├── tasks.jsonl        # 主任务 + 子任务
-└── modules.jsonl      # 功能模块
+├── engine.json        # 引擎配置（graph 或 document）
+├── documents.jsonl    # 文档片段（document 引擎）
+├── tasks.jsonl        # 主任务 + 子任务（document 引擎）
+├── modules.jsonl      # 功能模块（document 引擎）
+└── graph-data/        # WAL 图存储（graph 引擎）
+    └── wal/           # 预写日志分片
 ```
 
 存储路径解析优先级：
-1. `AIFASTDB_DEVPLAN_PATH` 环境变量
-2. 项目内 `.devplan/` 目录（通过 `.git` / `package.json` 定位）
-3. `~/.aifastdb/dev-plans/`（兜底）
 
-## 依赖
+| 优先级 | 路径来源 | 说明 |
+|--------|---------|------|
+| 1 | `AIFASTDB_DEVPLAN_PATH` 环境变量 | 显式指定存储目录 |
+| 2 | 项目内 `.devplan/` 目录 | 自动检测项目根目录（通过 `.git` / `package.json`） |
+| 3 | `~/.aifastdb/dev-plans/` | 全局兜底路径 |
+
+### 平台支持
+
+`aifastdb-devplan` 是纯 TypeScript/JavaScript 项目，支持所有 Node.js ≥ 18 的平台：
+
+| 平台 | 架构 | 支持 |
+|------|------|------|
+| Windows | x64 | ✅ |
+| macOS | x64 / Apple Silicon (M1/M2/M3/M4) | ✅ |
+| Linux | x64 / ARM64 | ✅ |
+
+> 注：底层存储引擎 [aifastdb](https://github.com/aifastdb/aifastdb) 包含 Rust 原生绑定，已为上述平台提供预编译二进制文件。
+
+---
+
+## Tech Stack / 技术栈
+
+- **Storage Engine / 存储引擎**: [aifastdb](https://github.com/aifastdb/aifastdb) — Dual engine: SocialGraphV2 (graph) + EnhancedDocumentStore (JSONL), built with Rust + N-API
+- **Protocol / 通信协议**: [MCP (Model Context Protocol)](https://modelcontextprotocol.io) — Standard protocol for AI assistant tool invocation
+- **Visualization / 可视化**: [vis-network](https://visjs.github.io/vis-network/) — Interactive graph visualization (CDN, zero dependencies)
+- **Runtime / 运行时**: Node.js ≥ 18
+- **Language / 语言**: TypeScript (strict mode)
+
+## Related Projects / 相关项目
 
-- [aifastdb](https://github.com/aifastdb/aifastdb) — 存储引擎
-- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) — MCP 协议支持
+- [aifastdb](https://github.com/aifastdb/aifastdb) — AI-friendly high-performance database engine (vector search + semantic indexing + agent memory)
+- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol official documentation
 
 ## License
 
-MIT
+[MIT](LICENSE)