WorkRelay · 工作接力

WorkRelay is a local, single-project workbench for following a changed requirement through compare → approve → repair → resume. Inspect original evidence, review affected tasks and documents, and explicitly approve each saved change. The Alexa+ experience is a clearly labeled guided simulation using real MCP tools; it has no live Alexa connection, voice input or remotely hosted service. No model account or API key is required.

Quick start — Node.js 22 or later: run these commands from the repository root:

npm ci
npm run dev

Open WorkRelay locally. For the English walkthrough, select English, open Workspace settings, then choose Confirm: load English demo. This explicitly replaces the current workspace with fictional example data; export anything you want to keep first.

English reviewer guide · English demo video · MIT License

中文说明

从会议决定到最终交付的本地项目工作台。主场景是“如果要求变了，哪些任务和交付需要跟着检查？”：比较有来源的方案，确认决定，选择准确的文档修复与任务日期，再接续剩余工作。会议跟进、反馈协调、需求变更、工作恢复、项目交接与交付检查共享一份项目记录。

本项目按 Build, Ship, Shape: Amazon Developer Hackathon / Alexa+ 方向开发。当前提供可操作的网页体验模拟和本地 MCP 服务；未连接真实 Alexa 服务。参见产品取舍与参赛方案、英文演示脚本、本地交付状态与提交待办。

English setup, architecture and reproduction steps: Reviewer guide.

Related MCP server: @runablejs/mcp

启动

需要 Node.js 22 或以上版本。

在仓库根目录（包含 package.json 的目录）运行，适用于 macOS、Linux 和 Windows：

npm ci
npm run dev

打开 本地工作台。首次启动载入明确标注的中文演示项目；已有项目重启后保持原样。顶部可显式切换 中文 / English，默认中文，保存界面语言偏好；项目名称、人员和来源原话不随语言切换翻译。

英文评审可先选 English，再打开 Workspace settings，明确选择 Confirm: load English demo。这会替换当前工作区为独立的英文示例，先导出需要保留的项目。也可在这里确认建立空白项目：发布日期、价格与渠道保持待确认，允许先只改项目名称，不会默认填入今天或零元。

npm test          # 业务、存储、HTTP、模型边界与 MCP 测试
npm run build    # TypeScript 检查和前端构建
npm start        # 使用已构建的 dist 启动

服务只监听 127.0.0.1。可用 WORKRELAY_PORT 指定端口；可用 WORKRELAY_DATA_DIR 指定独立的数据目录。同一目录只允许一个服务写入。

已实现的流程

可以新建任务和文档、修改项目名称、编辑任务与交付正文、导出文档和 JSON 备份，并撤销最近的项目变更。

在“任务与交付”中，新建任务只需填写名称，负责人和截止日期可以留空；确认提案后创建一项待开始任务，并保留本次录入来源。编辑任务可改名、调整负责人/日期/状态、添加或移除前置任务及要求关联；文档也可单独编辑要求关联并保留正文。预览会展示变更前后值及关联要求的来源，并检查循环依赖、前后任务排期，以及前置任务是否完成；未通过校验的修改不会写入。任务更新保留原始来源并追加操作记录，文档每次确认只增加一个版本，保留旧全文与关联变更记录。导入任务默认没有要求关联，需要用户明确选择；关联待确认或已替代要求不会使其生效。

规则提取支持以下会议文本；CSV 文件可以作为文本导入，但不等于支持任意 CSV 表结构：

任务：准备活动海报；负责人：小林；截止：2026-10-05
核对报名页面 | 阿周 | 2026-10-06
Task: Prepare launch page; Owner: Sam; Due: 2026-10-05
Review accessibility | TBD | ?

英文标签支持 Task / Owner / Due（也可用 Due date），大小写不敏感。?、TBD 等明确未知值保持待确认；不会把 tomorrow 或 next week 推测为日期。

没有识别到行动项时，只保存原文并明确提示。任意自然语言的任务提取需要连接模型，或通过 MCP 让外部 Agent 提出带逐字引用的结构化任务。

决策 → 准确修复 → 接续工作

首页“决策工作台”使用 DecisionJourney 串起三个步骤：

1. 做决定：针对同一要求，比较 2–3 个方案，可包含“保持当前约定”基线。查看来源原话、直接关联与下游任务、文档以及检查差异。任务逐项解释要求变化、实际日期冲突及前置依赖，可直接打开对应任务核对。每个方案分别从同一保存版本计算；不替用户选优，也不把问题数量当作工时或完成率。保持当前约定不会生成无变化提案；采纳一条反馈不会自动拒绝其他反馈。

2. 准备修复：决定确认后，读取当前已生效要求，选择文档中可准确核验的独立行，查看行号、文档版本、原文和替换值；任务日期必须明确输入。先预览组合后的排期与检查结果，再审阅一份 repair_plan 提案。确认时一起保存所选改动，每份被改文档增加一个版本；未选择的正文、负责人、状态与依赖保持不变。未知基准、缺失标注、无法解析或含歧义的字段交由人工处理。

3. 接着推进：查看已保存的决定、仍待处理的反馈、文档、排期、依赖、交接与未知信息，进入具体对象继续处理。保存工作断点后，刷新或重启可从项目记录恢复。历史预演不被当成已完成工作。

比较、影响推演、修复候选和修复预览均只读，不写项目、历史或待审提案。准备审核时才保存提案；只有在审核抽屉明确点击“确认应用”，项目才改变。版本或修复选择改变后需要重新预览。

有上下文的 Alexa+ 引导体验

“Alexa+ 体验模拟”由 ConversationWorkbench 和 /api/conversation 提供，不需要模型、账户或凭据。它是明确标注的本地规则引导：保留同一项目版本下的比较方案和选中项，让用户追问具体文档与来源，再返回所选方案。

可通过引导按钮或受支持的中英文表达操作，例如：

服务通过真实 MCP SDK 的内存传输调用只读工具，工具轨迹只列已完成调用。对话上下文每轮按项目 ID、版本、实际对象与领域规则重验；旧结果保留供回看，不能直接生成新提案。页面最近对话保存在浏览器会话中，不属于项目备份。相对日期、否定、复合或不受支持的要求会要求澄清，不自动猜测。

它不是 Alexa 远程连接、语音输入或通用语言模型。旧的 /api/simulation 仍作为兼容的有界命令接口保留，不是当前主对话入口。

演示路径

1. 载入中文或英文示例，在决策工作台比较保持 2026-10-09 与采纳 2026-10-07 的建议。检查原话与影响，确认选择前项目版本不变。

2. 审阅并明确确认较早日期对应的反馈决定。该条反馈被采纳，另一条仍待决；旧文档与任务日期保留，检查指出差异。

3. 进入准备修复，只选一份文档的日期行，预览并确认修复。该文档增加一个版本，其他文档的日期问题仍存在。任务排期可另外明确输入后纳入同一修复提案。

4. 接续步骤查看剩余反馈和依赖，保存“下次先做什么”的断点。刷新后查看断点和真实剩余工作。

5. 可另走引导对话：比较方案 → 选择 → 追问文档 → 打开原始来源 → 输入另一明确日期 → 取消。此阶段不保存提案、不改变项目。点击“审阅此方案”后仍需最后确认。

完整的英文复验步骤见 Reviewer guide。检查没有问题也不代表实际交付已经发送或通过验收。

自然语言模型（可选）

默认不连接模型，表单工作流程可以独立使用。应用不会读取已有 AI 工具的凭据，也不会默认调用付费 API。

若你已经安装 Ollama 并下载本地模型，可以在启动服务时显式选择：

WORKRELAY_AGENT_PROVIDER=ollama WORKRELAY_OLLAMA_MODEL='你的本地模型名称' npm run dev

WORKRELAY_OLLAMA_URL 默认是 http://127.0.0.1:11434，仅支持本机地址。应用检查模型是否在本机可用，再发送当前项目上下文；模型输出经过相同业务校验后成为待审核提案。当前未做真实模型推理验收，自动测试使用模拟服务验证格式、失败处理和执行边界。

接入依据：Ollama Chat API、模型列表 API。不支持 Ollama 云模型，不自动下载模型，不自动启动 Codex CLI。以上为 macOS/Linux 的环境变量写法；Windows 可在 PowerShell 设置对应 $env: 变量后运行 npm run dev。此可选模型助理使用 /api/chat，与无需模型的引导对话分开；每次模型请求独立携带当前项目状态，其聊天气泡不持久化，多轮追问时请写明对象和要求。

外部 Agent / MCP

先启动 WorkRelay。stdio 入口可在仓库根目录运行 npm run mcp。客户端配置示例（将 <REPO_ROOT> 替换成你的仓库绝对路径，按客户端格式调整；Windows JSON 路径可使用 /）：

{
  "mcpServers": {
    "workrelay": {
      "command": "node",
      "args": ["<REPO_ROOT>/node_modules/tsx/dist/cli.mjs", "<REPO_ROOT>/server/mcp.ts"],
      "env": { "WORKRELAY_URL": "http://127.0.0.1:4317" }
    }
  }
}

提供九个工具：workrelay_read_state、workrelay_audit、workrelay_resume、workrelay_readiness、workrelay_compare_options、workrelay_preview_impact、workrelay_repair_candidates、workrelay_preview_repair、workrelay_propose。前八个只读；最后一个只保存待审提案，不提供批准、撤销、备份导入或清空工具。提案需在工作台确认。外部客户端如何处理读取到的项目数据，取决于该客户端及其模型服务设置。

同一服务也提供 http://127.0.0.1:4317/mcp Streamable HTTP 入口，已通过真实 SDK 客户端的 MCP 2025-11-25 协议测试。它仅在本机可访问；配置、边界和复验方式见 MCP HTTP 文档。

直接新建任务可通过 workrelay_propose 提出 create_task，参数为 {title, owner?, dueDate?, dependencies?:[], requirementIds?:[]}。update_task 支持 {taskId, title?, status?, owner?, dueDate?, dependencies?:[], requirementIds?:[]}；省略字段表示保留原值，dependencies 和 requirementIds 分别完整替换前置任务与要求关联，传空列表明确解除对应关联。负责人传空字符串表示待分配，截止日期传空字符串表示待确认。

update_document 支持 {documentId, content?, requirementIds?:[]}。只传 requirementIds 可调整关联并保留原始正文；只传 content 则完整替换正文并保留关联。至少一项必须实际改变，相同 ID 集合仅调整顺序不算变化。所有 ID 必须来自当前项目且不能重复；不自动推测关联，关联操作不采纳反馈、不激活历史要求、不转移负责人。

例如，先读取当前项目中的真实任务、文档与要求 ID，再在用户明确选择后提出以下两个独立提案；示例中的占位 ID 不能直接执行，每份提案均需分别审核确认：

{"action":"update_task","params":{"taskId":"<task ID>","requirementIds":["<requirement ID>"]}}
{"action":"update_document","params":{"documentId":"<document ID>","requirementIds":["<requirement ID>"]}}

每次读取并传入当时的 expectedRevision，确认首份提案后应重新读取版本，再提出下一份。

数据与限制

• 数据保存在 .data/workspace.json，不加入 Git。事务串行写入，先落盘再返回成功；损坏文件不会被静默重置。

• 提案绑定项目版本。其他窗口变更或撤销后，旧提案不能执行；应用后也不能重复执行同一提案。

• 在同一版本重复提交完全相同的已验证操作类型与规范化参数，会复用已有待审提案的 ID，避免重复点击形成多份相同提案。调整原因、来源内容和列表顺序仍属于参数；不会把仅仅“看起来类似”的决定合并，也不复用过期或已应用提案。

• 最近最多 20 次项目变更可撤销，历史总量限制 20 MB。导入与重置也可撤销。JSON 导出包含当前项目、来源和活动，不包含待审核提案和撤销历史。

• 单个项目数据上限 4 MB，导入请求上限 5 MB。文本支持 TXT、Markdown 和 CSV 原文；未接入 PDF、Office、邮件或企业网盘解析。

• 这是单机、单项目工作区。交接签收是本地记录，没有多人登录或身份验证，不会向接收人发送通知。

• 检查针对独立行 发布日期：YYYY-MM-DD、价格：299、渠道：官网、小红书，以及 Launch date:、Price:、Channels: 等受支持标注，不覆盖任意正文语义、图片、附件内容或真实交付质量。问题计数、未完成任务与字段覆盖分别呈现，不构成完成率或上线许可。

• Alexa+ 网页模拟为明确标注的本地规则体验；未连接真实 Alexa+ 或其他语音平台，尚无远程托管的在线服务。源码与演示视频的发布不代表已接入 Alexa 或已部署服务。

代码入口

• server/domain.ts：业务校验、提案、六项工作流程与检查规则。

• server/impact.ts：在副本上预演变更，追溯关联并比较前后检查。

• server/comparison.ts / server/repair.ts / server/readiness.ts：方案比较、准确修复与剩余工作视图。

• server/store.ts：原子持久化、串行事务、版本保护与撤销。

• server/index.ts：本地 HTTP API 和前端服务。

• server/agent.ts / server/mcp.ts：可选模型规划与 MCP。

• server/mcp-http.ts / server/conversation.ts：Streamable HTTP MCP 与有上下文的本地引导；server/simulation.ts 保留兼容命令接口。

• src/App.tsx / src/styles.css：响应式工作台与提案审核。

• src/DecisionJourney.tsx / src/ConversationWorkbench.tsx：比较—修复—接续工作台和主引导体验入口。

• src/i18n.tsx / src/workflow-types.ts / src/conversation-types.ts：界面语言、工作流和对话契约。

• tests/：领域、持久化、HTTP 和 Agent 边界测试。