Story Mapper

Storymapper

一款用户故事地图 + Kanban 看板，由产品负责人和编码 Agent 共同规划——通过浏览器和 MCP 客户端实时共享同一份待办事项，并内置质量方法。

Storymapper 是一个 Node.js 软件包，包含三项功能：

1. 浏览器 UI — 用户故事地图（流程步骤 × 发布版本，单元格中包含史诗和用户故事）、Kanban 看板，以及表格、依赖关系图、需求和设置视图。采用纯 HTML + 模块化 JavaScript，无需构建步骤。
2. HTTP + WebSocket 服务 — 将每个项目及其完整的项目修订历史持久化到 SQLite，并在约 100 ms 内将变更推送给已连接的浏览器。
3. MCP 服务（stdio）加直通 CLI — 同一组约 70 个工具，可供 Claude Desktop / Claude Code 通过 MCP 使用，也可作为一次性命令供脚本或其他工具框架使用。Agent 执行的任何操作都会实时显示在产品负责人的浏览器中，并以高亮和移动动画呈现；手动编辑的内容也会在 Agent 下次读取时同步给它。

最终得到的是一个共享的规划界面：Agent 不会写入人类看不到的数据库——双方实时使用同一块看板。

---

它为何存在

当计划和工作分散在不同地方时，AI 辅助开发的规划就会失效。Storymapper 让计划成为实时、双向同步的产物：

• 你提出产品构想，并粗略描述要构建的内容；Agent 会将其整理到看板上——包括史诗、用户故事、发布版本和依赖关系——你可以看着它们出现，并亲手重新排列。
• 你调整优先级、拆分任务、添加注释；Agent 会在下次读取时获取这些变更，并基于看板的当前状态继续工作。
• 每项变更都会生成一个修订版本，你可以查看并恢复。

产品层面的质量引导

当 Agent 负责构建时，人类的贡献就会上升到更高层次：描述产品、审查产品行为，并通过流程引导工作。这个流程正是 Storymapper 的核心——一套由引擎通过工具级规则强制执行的完整质量方法：工单必须先完成规格定义，再开始构建（就绪定义），并且必须先通过验证，才能视为完成（完成定义，加上已发布且记录了执行结果的测试计划）；此外，需求始终可追溯地关联到实现它们的用户故事和验证它们的测试。试图跳过步骤的 Agent 会收到一条结构化错误，其中明确指出缺少的内容——然后进行修正。这让每一位以产品为思考中心的人——创始人、领域专家和产品负责人——都能运用专业级质量保证：这套方法使用产品语言沟通，让你能够按照可验证的标准审视 Agent 的工作。工作流本身（状态、转换、关卡、看板列）可按项目配置，配套技能则教会 Agent 遵循规范，而不只是使用工具。

设计原则

• 零构建。 不需要打包器、转译器或 TypeScript。浏览器通过经典的 <script src> 模块加载，服务器通过 UMD 包装器在 Node 中运行相同的文件。克隆并运行即可。
• 纯逻辑的单一事实来源。 所有领域逻辑（规范化、操作、工作流／治理引擎、图算法）都位于 shared/core.js 中，并通过符号链接引入前端、由服务器重新导出——浏览器、HTTP 服务器和 MCP 服务运行的是同一份代码，不需要可能导致代码偏离的镜像步骤。
• 原生 HTTP，不使用框架。 使用 http.createServer 和手动路由。体积小、易读、依赖少。
• 同步 SQLite。 通过 better-sqlite3 实现，具有每次保存的原子事务、每个项目的互斥锁，以及按数量限制保留的修订版本。
• 单用户、本地优先。 一台机器上的一个用户及其 Agent。请参阅下方的安全模型。

如需全面了解分层结构、数据模型、实时同步机制、测试方法和有意不实现的功能，请参阅 ARCHITECTURE.md。

---

要求

• Node.js ≥ 20（使用 Node.js 20 和 22 开发并测试；Node.js 18 已停止维护）。
• better-sqlite3 是原生模块。主流平台均有预编译二进制文件（受支持的 Node.js 版本对应的 macOS／Linux／Windows x64 和 arm64），因此 npm install 通常可以直接运行。如果平台与 Node.js 版本的组合不受支持，则会从源代码编译，需要 C/C++ 工具链（Xcode Command Line Tools、build-essential 或 Windows 构建工具）。

安装

git clone <your-fork-url> storymapper
cd storymapper
npm install

运行浏览器界面

npm start
# → http://localhost:8770/   (data in ./.storymap-data)
# → Ctrl-C to stop

打开 http://localhost:8770/ 即可。页面会连接到加载它的服务器，并将每个项目存储在那里（使用 SQLite，并保留完整的修订历史）。

要将页面托管在其他位置？ 如果页面由不同源提供，界面会改用浏览器的 localStorage；使用 ?api=<url> 指向正在运行的服务器。页面必须从 localhost／127.0.0.1 加载——不支持将 HTML 作为 file:// 页面直接打开（请参阅安全模型）。

将其连接到 Claude（每种接入方式一个命令）

Storymapper 通过两部分连接到 Agent：MCP 服务（工具） 和配套的技能（工作方法——DoR/DoD 约定、 工作流规范、何时读取看板以及何时向看板写入）。 安装其中一项并不会安装另一项，因此下面的设置命令始终会安装两者：

接入方式	命令	后续操作
Claude Code（CLI）	npm run install-code	重启 Claude Code 会话
Claude Desktop	npm run install-desktop	在 Settings → Capabilities → Skills 下上传 dist/storymap-skill.zip，然后彻底重启应用——并使用 Chat（见下文）
浏览器中的 claude.ai	—	仅支持远程连接器；无法连接本地服务。请使用 Claude Code 或 Claude Desktop。

npm run install-code 会将技能复制到 ~/.claude/skills/storymap，并通过 claude mcp add（用户范围）注册 MCP 服务。如果无法使用 claude CLI，它会打印一条可直接使用的命令。

npm run install-desktop 会将服务条目写入平台的 claude_desktop_config.json（保留已有条目，并创建 .bak 备份），同时构建技能 zip 包。Claude Desktop 中的技能库由应用管理，因此你必须在 UI 中上传一次，这是脚本无法替你完成的唯一操作。

使用 Chat，而不是 Cowork。 Claude Desktop 只能在 Chat 对话中连接本地 MCP 服务——在 Cowork 模式下，Storymapper 工具不可用。如果 Cowork 是你的默认接入方式，请切换到 Chat；如果工具没有显示出来，这是首先要检查的事项。

这两个命令都是幂等的——拉取新的 Storymapper 版本后可以重新运行。--data-dir=DIR 可覆盖数据目录（默认值： <repo>/.storymap-data）。

手动设置（其他 MCP 客户端、其他运行框架）

任何 stdio MCP 客户端都可以按以下形式运行服务：

{
  "mcpServers": {
    "storymapper": {
      "command": "node",
      "args": [
        "/absolute/path/to/storymapper/server/index.js", "mcp",
        "--data-dir=/absolute/path/to/storymapper/.storymap-data"
      ]
    }
  }
}

技能包（npm run package-skill → dist/storymap-skill.zip）是纯 Markdown——包含 storymap/SKILL.md 和其中的 reference/ 文件。对于 Codex 这类运行框架，可将其解压到存放指令的位置，并让运行框架指向该位置，例如在 AGENTS.md 中：

Before planning work on the Storymapper board, read storymap/SKILL.md
(and the reference/ files it names) and follow that working method.

将 --data-dir 指向 HTTP 服务使用的同一目录。两个进程可以同时使用同一个 SQLite 文件运行（WAL 模式 + busy-timeout）； HTTP 服务会通过 WebSocket 将每次 MCP 写入操作转发给已连接的浏览器。

不使用 MCP 进行脚本编写：CLI

每个工具也都可以作为一次性 CLI 命令运行，并使用同一套工具核心：

node server/index.js tool list_projects
node server/index.js tool ticket_create '{"projectId": "…", "title": "…"}'

结果 JSON 会输出到 stdout（退出代码：0 表示成功，1 表示工具错误，2 表示未知 工具／参数错误）；参数可通过位置 JSON 字符串、 --json=<json> 或管道 stdin 传入。这使 shell 脚本、CI 作业以及不支持 MCP 的运行框架也能使用完整的工具集。

每个数据目录只能运行一个 storymapper server（PID 锁会拒绝第二个进程；崩溃后可通过 --force 接管过期锁）。MCP 进程不受此限制，始终可以共享数据目录。

安全模型（单用户、本地）

Storymapper 是一款本地单用户工具——一名用户和其 Agent 在一台机器上使用。我们刻意不设置身份验证层：

• 服务默认绑定到 localhost。不要在非环回接口上公开它（--host=0.0.0.0、反向代理、Docker 端口映射），除非你先自行设置身份验证——任何能访问该端口的人都可以读取和写入所有项目。
• CORS 仅允许环回源：跨源浏览器请求不会收到 Access-Control-Allow-Origin，且会拒绝修改数据的方法——这样可以防止你访问的随机网站操控本地 API。WebSocket 升级也会以相同方式检查来源。
• 提供的 HTML 带有 Content-Security-Policy；所有响应都会发送 X-Content-Type-Options: nosniff。
• X-Actor-* 标头用于归属标记，而非身份验证——它们会在修订历史中标记执行操作的人，但不会经过验证。
• 经验证的身份、令牌控制的远程访问和 RBAC 是后续阶段的计划；授权接口（server/identity.js）已就绪。

测试

npm test          # ≈1800 assertions, plain Node scripts, no test framework

测试套件使用自建的运行器（tests/run.js）运行 tests/test-*.js：纯单元测试、存储／互斥锁／修订测试、进程内和 stdio MCP 往返测试、JSDOM 渲染器测试，以及真实服务端端到端测试。CI 会在 Node 20 和 22 上运行测试。测试只会访问临时目录——运行测试绝不会触及你的数据。

许可证

根据 Apache License 2.0 授权——请参阅 LICENSE 和 NOTICE。