# 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:

```sh
npm ci
npm run dev
```

Open [WorkRelay locally](http://127.0.0.1:4317). 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](docs/competition/reviewer-guide.md) · [English demo video](https://youtu.be/CIQKDzVymJs) · [MIT License](LICENSE)

## 中文说明

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

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

English setup, architecture and reproduction steps: [Reviewer guide](docs/competition/reviewer-guide.md).

## 启动

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

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

```sh
npm ci
npm run dev
```

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

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

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

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

## 已实现的流程

| 能力 | 操作与结果 |
| --- | --- |
| 会议跟进 | 粘贴或导入文本，预览行动项和原文，确认后保存来源与任务。未明确的信息保留待确认状态。 |
| 反馈协调 | 保存反馈原话及建议值，对照当前要求，逐条采纳或拒绝；不同的待决值会提示冲突。 |
| 需求变更 | 预览项目字段与受影响的任务、文档。新要求生效后，旧文档保留原版本并显示检查问题。 |
| 工作恢复 | 保存断点与关注任务，展示之后的变更、阻塞和下一步；刷新或重启后继续。 |
| 项目交接 | 发起待接收交接，记录进度与下一步；确认接收后才转移负责人。支持导出交接包。 |
| 交付检查 | 检查明确标注的日期、价格、渠道、任务依赖与交接状态，定位文档及原文；修订后重新计算。 |

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

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

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

```text
任务：准备活动海报；负责人：小林；截止：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` 提供，不需要模型、账户或凭据。它是明确标注的**本地规则引导**：保留同一项目版本下的比较方案和选中项，让用户追问具体文档与来源，再返回所选方案。

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

| 请求 | 结果 |
| --- | --- |
| `Compare options` / `比较方案` | 比较当前待决反馈与保持当前约定的基线；不同字段先要求选择。 |
| `Choose option 2` / `选择第2个方案` | 选择本轮已返回的方案，读取影响；不保存提案。 |
| `Why Product landing page copy?` / 文档旁“为什么要检查” | 查看对应文档原文、所选方案的前后检查与来源。文档名称须来自当前项目。 |
| `What about 2026-10-08?` / `那改为 2026-10-08 呢？` | 预演明确日期，可保留上一轮选中方案作对比；不会自动处理已有反馈。 |
| `Prepare repairs` / `准备修复` | 根据已保存要求读取准确修复候选，未确认的对话方案不成为基准。 |
| `Where was I?` / `继续工作`；`Check delivery readiness` / `检查交付` | 读取工作断点或当前检查，列出实际剩余工作。 |
| `Cancel` / `取消` | 清除当前比较与选择，不改项目；已保存的待审提案仍需在审核列表中单独放弃。 |

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

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

## 演示路径

1. 载入中文或英文示例，在决策工作台比较保持 `2026-10-09` 与采纳 `2026-10-07` 的建议。检查原话与影响，确认选择前项目版本不变。
2. 审阅并明确确认较早日期对应的反馈决定。该条反馈被采纳，另一条仍待决；旧文档与任务日期保留，检查指出差异。
3. 进入准备修复，只选一份文档的日期行，预览并确认修复。该文档增加一个版本，其他文档的日期问题仍存在。任务排期可另外明确输入后纳入同一修复提案。
4. 接续步骤查看剩余反馈和依赖，保存“下次先做什么”的断点。刷新后查看断点和真实剩余工作。
5. 可另走引导对话：比较方案 → 选择 → 追问文档 → 打开原始来源 → 输入另一明确日期 → 取消。此阶段不保存提案、不改变项目。点击“审阅此方案”后仍需最后确认。

完整的英文复验步骤见 [Reviewer guide](docs/competition/reviewer-guide.md)。检查没有问题也不代表实际交付已经发送或通过验收。

## 自然语言模型（可选）

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

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

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

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

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

## 外部 Agent / MCP

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

```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 文档](docs/mcp-http.md)。

直接新建任务可通过 `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 不能直接执行，每份提案均需分别审核确认：

```json
{"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 边界测试。