内容
# 故事映射器
**产品负责人和 AI 编码代理共同规划的用户故事地图 + 看板，共享同一个 backlog，实时协作，支持浏览器和 MCP 客户端，内置质量方法。**
故事映射器是一个 Node.js 包，提供以下功能：
1. **浏览器 UI** — 用户故事地图（过程步骤 × 发布版本，包含史诗和故事的单元格），看板，表格，依赖图，需求和设置视图。纯 HTML + 模块化 JavaScript，无需构建步骤。
2. **HTTP + WebSocket 服务器** — 将每个项目保存在 SQLite 中，具有完整的项目修订历史，并在约 100 毫秒内将更改推送到连接的浏览器。
3. **MCP 服务器（stdio）+ 直通 CLI** — 提供约 70 种工具，适用于 Claude Desktop / Claude Code 和脚本或其他外壳程序，实现单次命令。任何代理执行的操作都会实时出现在产品负责人的浏览器中，并带有高亮和移动动画；任何手动编辑的内容都会在代理下一次读取时流回。
结果是一个 **共享规划表面**：代理不会写入人类无法看到的数据库 — 两人在实时状态下使用同一个看板。
---
## 为什么存在
AI 辅助开发规划在计划生活在一个地方而工作生活在另一个地方时就会出现问题。故事映射器使计划成为一个实时、双向的产物：
- 您带来产品创意和粗略的构建形状；代理将其布局在看板上 — 史诗、故事、发布版本、依赖关系 — 然后您实时查看并手动重新排列。
- 您重新优先排序、拆分、注释 — 代理在下一次读取时获取并从当前状态继续。
- 每个更改都是一个 **修订版**，您可以检查和恢复。
## 产品层面的质量控制
当代理执行构建时，人类贡献会提升到一个层面：您描述产品，审查其行为，并通过过程控制工作。该过程是故事映射器的实质内容 — 一个完整的质量方法，引擎将其强制为工具级规则：
- **在构建前指定**（Definition of Ready）
- **在计为完成前验证**（Definition of Done + 发布测试计划和记录运行）
您的需求与实现需求的故事和验证需求的测试保持可追溯链接。尝试跳过步骤的代理会收到结构化错误，指出缺少的内容 — 并进行修复。这将专业级质量保证置于每个考虑产品的参与者（创始人、领域专家、产品负责人）手中；该方法使用产品的语言，让您可以验证代理的工作。工作流程本身（状态、转换、门控、看板列）可按项目配置，配套技能教导代理纪律，而不仅仅是工具。
## 设计原则
- **零构建**。无打包器、无转译器、无 TypeScript。浏览器加载经典 `<script src>` 模块；服务器通过 UMD 包装器在 Node 下运行相同的文件。克隆并运行。
- **纯逻辑的单一真相来源**。所有领域逻辑（规范、操作、工作流/治理引擎、图算法）都位于 `shared/core.js` 中，并 **符号链接** 到前端，并由服务器 **重新导出** — 相同的代码在浏览器、HTTP 服务器和 MCP 服务器中运行，无需镜像步骤。
- **原始 HTTP，无框架**。`http.createServer` + 手动路由。小型、可读、依赖轻。
- **同步 SQLite**，通过 `better-sqlite3`、原子保存事务、项目互斥锁和计数有界修订保留。
- **单用户、本地优先**。一人和其代理在一台机器上。参见下面的安全模型。
有关完整情况 — 分层、数据模型、实时同步机制、测试方法和刻意非目标 — 请参见 **[ARCHITECTURE.md](ARCHITECTURE.md)**。
---
## 需求
- **Node.js ≥ 20**（在 20 和 22 上开发和测试；Node 18 已停止支持）。
- `better-sqlite3` 是本机模块。预构建的二进制文件涵盖主流平台（macOS / Linux / Windows 上的 x64 + arm64，适用于支持的 Node 版本），因此 `npm install` 通常可以直接使用。在不支持的平台/Node 组合上，它会从源代码编译，需要 C/C++ 工具链（Xcode Command Line Tools、`build-essential` 或 Windows 构建工具）。
## 安装
```sh
git clone <your-fork-url> storymapper
cd storymapper
npm install
```
## 运行浏览器 UI
```sh
npm start
# → http://localhost:8770/ (数据存储在 ./.storymap-data)
# → Ctrl-C 停止
```
打开 <http://localhost:8770/> — 就是这样。该页面连接到它加载的服务器，并将每个项目存储在那里（SQLite，具有完整的修订历史）。
> **在其他地方托管页面？** 从不同来源提供服务时，UI 在浏览器 `localStorage` 上运行；请将其指向正在运行的服务器，地址为 `?api=<url>`。页面必须从 `localhost` / `127.0.0.1` 加载 — 直接打开 HTML 文件作为 `file://` 页面不受支持（请参见安全模型）。
## 连接到您的 Claude（每个界面一个命令）
故事映射器通过两个部分与代理交互：**MCP 服务器**（工具）和配套 **技能**（工作方法 — DoR/DoD 合同、工作流纪律、何时读取看板和何时写入看板）。安装一个并不安装另一个，因此以下设置命令始终安装 **两者**：
| 界面 | 命令 | 剩余内容 |
|---|---|---|
| **Claude Code** (CLI) | `npm run install-code` | 重启您的 Claude Code 会话 |
| **Claude Desktop** | `npm run install-desktop` | 上传 `dist/storymap-skill.zip` 到 **设置 → 功能 → 技能**，然后完全重启应用程序 — 并使用 **聊天**（参见下文） |
| **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 中的一次上传是脚本无法为您执行的单个步骤。
> **聊天，不是协作**。Claude Desktop 从 **聊天** 对话中访问本地 MCP 服务器 — 在 **协作** 模式下，故事映射器工具不可用。如果协作是您的默认界面，请切换到聊天；如果工具未显示，请检查这是第一件事。
两个命令都是幂等的 — 在拉取新的故事映射器版本后重新运行它们。`--data-dir=DIR` 覆盖数据目录（默认：`<repo>/.storymap-data`）。
### 手动设置（其他 MCP 客户端，其他外壳程序）
任何 stdio MCP 客户端都可以使用以下形状运行服务器：
```json
{
"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`：
```md
在故事映射器看板上规划工作之前，请阅读 storymap/SKILL.md（及其 reference/ 文件）并遵循该工作方法。
```
将 `--data-dir` 指向 **相同** 目录，HTTP 服务器使用它。两个进程可以并发运行，针对一个 SQLite 文件（WAL 模式 + 忙碌超时）；HTTP 服务器通过 WebSocket 将每个 MCP 写入中继到连接的浏览器。
### 无 MCP 脚本：CLI
每个工具也是一个单次 CLI 命令，运行在相同的工具核心上：
```sh
node server/index.js tool list_projects
node server/index.js tool ticket_create '{"projectId": "…", "title": "…"}'
```
结果 JSON 输出到 stdout（退出代码：`0` ok，`1` 工具错误，`2` 未知工具 / 参数错误）；参数来自位置 JSON 字符串、`--json=<json>` 或管道 stdin。这为 shell 脚本、CI 作业和不支持 MCP 的外壳程序打开了完整的工具接口。
> 每个数据目录只能运行一个 `storymapper server`（PID 锁拒绝第二个；`--force` 接管崩溃后的陈旧锁）。MCP 进程是豁免的，并且可以始终共享数据目录。
## 安全模型（单用户，本地）
故事映射器是一个 **本地单用户工具** — 一个人和其代理在一台机器上。故意没有身份验证层：
- 服务器默认绑定到 `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`）已经就位。
## 测试
```sh
npm test # ≈1800 个断言，纯 Node 脚本，无测试框架
```
测试套件是自制运行器（`tests/run.js`）上的 `tests/test-*.js`：纯单元测试、存储/互斥锁/修订测试、进程内和 stdio MCP 往返、JSDOM 渲染器测试和真实服务器端到端测试。CI 在 Node 20 和 22 上运行它。测试永远不会触及您的数据。
## 许可证
根据 **Apache License 2.0** 许可 — 请参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
