aifastdb-devplan

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

npm install -g aifastdb-devplan

Option A: As an MCP Server (Recommended)

Configure in Cursor IDE (.cursor/mcp.json):

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

Or in Claude Desktop (claude_desktop_config.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)

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:

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, 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

npm install -g aifastdb-devplan

Step 2: Configure MCP Server in your project

Create .cursor/mcp.json in your project root:

{
  "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

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:

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

Windows example:

{
  "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)

# All devplan data will be stored under this path
export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans

Option B: --base-path for visualization server

# 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

# 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 includes Rust native bindings with prebuilt binaries for all listed platforms.

中文

为什么需要 aifastdb-devplan？

在 AI 辅助编程时代，开发者与 AI 助手的协作越来越密切。但 AI 助手缺乏持久化的项目记忆——每次对话都从零开始，无法了解项目的整体规划、当前进度和历史决策。

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/ 目录中，无需外部数据库 |

快速开始

安装

npm install -g aifastdb-devplan

方式 A：作为 MCP Server 使用（推荐）

在 Cursor IDE 中配置 .cursor/mcp.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

或在 Claude Desktop 中配置 claude_desktop_config.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

配置完成后，AI 助手即可使用 20 个 devplan_* 工具来管理你的开发计划。

方式 B：作为 npm 包编程使用

import { DevPlanStore, createDevPlan } from 'aifastdb-devplan';

const plan = createDevPlan('my-project');

// 创建主任务
plan.createMainTask({
  projectName: 'my-project',
  taskId: 'phase-1',
  title: '阶段一：基础搭建',
  priority: 'P0',
});

// 添加子任务
plan.addSubTask({
  projectName: 'my-project',
  taskId: 'T1.1',
  parentTaskId: 'phase-1',
  title: '初始化项目结构',
});

// 完成任务（自动更新主任务进度 + Git commit 锚定）
plan.completeSubTask('T1.1');

// 查看进度
const progress = plan.getProgress();
console.log(progress);

MCP 工具一览（20 个）

📋 文档管理

| 工具 | 说明 | |------|------| | devplan_init | 初始化开发计划（自动检测存储引擎） | | devplan_save_section | 保存/更新文档片段（11 种标准类型） | | devplan_get_section | 读取指定文档片段 | | devplan_list_sections | 列出所有文档片段 |

🎯 任务管理

| 工具 | 说明 | |------|------| | 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_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

图谱可视化

将开发计划以交互式图谱形式展示：

npm run visualize -- --project my-project --base-path /path/to/.devplan
# 或
aifastdb-devplan-visual --project my-project --port 3210

内置 HTTP 服务器提供自包含 HTML 页面，使用 vis-network 渲染：

• 5 种节点类型：项目（星形）、模块（菱形）、主任务（圆形）、子任务（小圆点）、文档（方形）
• 状态着色：已完成（绿色）、进行中（蓝色）、待开始（灰色）
• 交互功能：点击查看详情面板、按类型过滤、顶部统计栏 + 进度条
• 暗色主题：与现代开发工具风格一致

在其它项目中启用 DevPlan（实战指南）

以下是在任意项目（例如 my-app）中启用 devplan 的完整步骤。

方式一：使用 npm 发布版本（推荐）

第 1 步：全局安装

npm install -g aifastdb-devplan

第 2 步：在目标项目中配置 MCP Server

在项目根目录创建 .cursor/mcp.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 步：本地构建

cd /path/to/aifastdb-devplan
npm install
npm run build

第 2 步：使用本地路径配置 MCP Server

在目标项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["D:/Project/git/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

控制数据存储位置

默认情况下，devplan 会自动检测项目根目录并将数据存储在 .devplan/ 下。你可以通过以下方式覆盖：

方案 A：环境变量（全局覆盖）

# 所有 devplan 数据将存储在此路径下
export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans

Windows PowerShell：

$env:AIFASTDB_DEVPLAN_PATH = "D:\shared\devplans"

方案 B：可视化服务器使用 --base-path

# 查看另一个项目的 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" 项目

# 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}/
├── 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/ | 全局兜底路径 |

平台支持

aifastdb-devplan 是纯 TypeScript/JavaScript 项目，支持所有 Node.js ≥ 18 的平台：

| 平台 | 架构 | 支持 | |------|------|------| | Windows | x64 | ✅ | | macOS | x64 / Apple Silicon (M1/M2/M3/M4) | ✅ | | Linux | x64 / ARM64 | ✅ |

注：底层存储引擎 aifastdb 包含 Rust 原生绑定，已为上述平台提供预编译二进制文件。

Tech Stack / 技术栈

• Storage Engine / 存储引擎: aifastdb — Dual engine: SocialGraphV2 (graph) + EnhancedDocumentStore (JSONL), built with Rust + N-API
• Protocol / 通信协议: MCP (Model Context Protocol) — Standard protocol for AI assistant tool invocation
• Visualization / 可视化: vis-network — Interactive graph visualization (CDN, zero dependencies)
• Runtime / 运行时: Node.js ≥ 18
• Language / 语言: TypeScript (strict mode)

Related Projects / 相关项目

• aifastdb — AI-friendly high-performance database engine (vector search + semantic indexing + agent memory)
• MCP Protocol — Model Context Protocol official documentation

License

MIT