withvibe-roadmap

WithVibe 路线图插件

面向 WithVibe 的按环境划分的实现路线图看板——由 Postgres 提供支持，并配有 AI 编排器可直接驱动的 MCP 服务。

多阶段功能容易偏离计划。执行过程中计划会发生变化。经过几次会话后，你就会搞不清哪些已交付、哪些待处理，以及目前进行到哪一步。此插件为 AI 提供一个结构化空间来保存这些状态，也让用户能够实时查看。

Feature: Auth rewrite                          ▓▓▓▓░░░░░░ 4/11 tasks
you are here →  API layer  ›  Wire DTO validation

[x] Phase 1: Schema (done)
[~] Phase 2: API layer (in progress)
    [x] Endpoint scaffolding
    [x] Auth guard
    [~] Wire DTO validation     ← active
    [ ] Error envelope
[ ] Phase 3: Web
[ ] Phase 4: QA

— Plan changes —
2026-05-28  AI added Phase 4 (QA) — reason: integration tests not in original scope
2026-05-29  user removed "Add caching" — reason: deferred to follow-up

包含内容

• 分层路线图——功能 → 阶段 → 任务，状态包括 pending / in_progress / done / blocked / deferred / canceled。
• “你在这里”标记——同一时间只有一个任务处于活动状态；切换上下文后返回时，横幅就是恢复工作的锚点。
• 计划变更日志——每次添加、移除、重命名或更改状态都会记录操作者（ai 或 user）以及可选原因。变更轨迹能让计划偏移一目了然。
• AI 编排器无需提示即可使用的 MCP 工具：propose_plan、set_active_task、complete_task、add_note、update_task、log_change，等等。
• 实时 UI——基于 htmx，通过轮询轻量级版本端点，使 iframe 在 AI 做出任何更改后约 4 秒内更新，且不会跳动滚动位置。
• 持久化——使用 WithVibe 的 shared-postgres 插件存储，因此容器重启后状态仍会保留。

架构

manifest.yaml ──→ WithVibe spawns one container per env
       ↓
   server.js (express)
   ├── /health         platform health probe
   ├── /mcp            AI orchestrator's MCP endpoint  ─→ mcp.js
   ├── /ui             dark-themed htmx UI             ─→ ui.js
   └── /ui/version     cheap freshness check (drives live updates)
                ↓
              db.js (pg)
                ↓
          shared-postgres
          per-env schema
          plan / phase / task / plan_event

• 范围：env——每个（环境、插件）对应一个容器。每个环境都有自己的路线图、Postgres schema 和端口。
• 存储：shared-postgres——平台会在 withvibe_plugins 数据库中配置专用角色和 schema，并在启动时注入 DATABASE_URL 和 PGSCHEMA。插件角色无法访问主 withvibe 数据库。
• 状态数据：db.js 中的四张表——plan（单例）、phase、task、plan_event（变更日志）。

MCP 工具

所有工具都会在末尾的文本中返回完整更新后的计划，因此 AI 不会持有过时状态。

工具	用途
get_plan	读取完整路线图、活动标记和最近 20 条事件。
propose_plan	替换整个路线图（用于初始规划或重大重新规划）。
add_phase / add_task	在执行过程中追加工作；记录 reason。
set_active_task	开始工作前，标记“你在这里”的锚点。
complete_task	标记为已完成，并记录一行结果；若阶段中的所有任务均已完成，则自动关闭该阶段。
update_task / update_phase	在提供原因的同时编辑标题、描述或状态（blocked、deferred、canceled）。
add_note	追加 Markdown 备注——决策、尝试过的事项和参考资料。
log_change	记录计划层面的决策说明，但不修改数据。

完整 schema 请参阅 mcp.js。

构建

docker build -t local/roadmap:2.0 .

该镜像使用 Node 20 Alpine，兼容多架构，大小约为 150 MB，且无需原生构建步骤。

在 WithVibe 中安装

1. 工作区管理员 → 插件 → 安装插件。
2. 将 manifest.yaml 的内容粘贴到编辑器中。
3. 平台会拉取或定位镜像，并注册插件。
4. 打开任意环境 → 插件面板中会出现 路线图 标签页。

重建镜像后如需更新，请在管理员列表中的插件行点击 更新——运行中的实例会停止，因此下次启动环境时会使用新镜像。

Manifest

Manifest 是完整的安装输入。此插件中重要的字段如下：

id: withvibe.roadmap          # URL + tool prefix; reverse-DNS-ish
name: Roadmap                 # display name in the env's plugin panel
version: 2.0.0
icon: list-todo               # Lucide icon
image: local/roadmap:2.0    # OCI ref

scope: env                    # one container per env
storage:
  kind: shared-postgres       # platform-managed Postgres role + schema

ui:
  path: /ui                   # iframe entry point
  websocket: false

mcp:
  enabled: true
  path: /mcp                  # MCP endpoint the AI auto-discovers

本地开发

# Build
docker build -t local/roadmap:2.0 .

# Run standalone (requires a Postgres reachable via DATABASE_URL)
docker run --rm -p 8080:8080 \
  -e DATABASE_URL="postgres://user:[email protected]:5432/withvibe_plugins" \
  -e PGSCHEMA="roadmap_dev" \
  local/roadmap:2.0

# Then open http://localhost:8080/ui

针对实际的 WithVibe 安装进行开发时，每次重建后都要在管理员的插件页面中点击 更新——这会停止运行中的实例，因此下次启动环境时会使用新镜像。

仓库目录结构

manifest.yaml   WithVibe plugin manifest
Dockerfile      builds the runtime image
package.json    npm deps (express, pg, @modelcontextprotocol/sdk, zod)
server.js       express entry, HTTP + MCP routes
db.js           pg pool, schema init, query helpers
mcp.js          MCP tool registrations
ui.js           htmx UI rendering + dark-themed CSS

参与贡献

欢迎提交问题和 PR。请让更改保持聚焦，并在提交信息中说明 原因。

许可证

Apache License 2.0。署名信息请参阅 NOTICE。