@olierjs/fugue-cli 0.0.0-stage → 0.1.2

package/skills/fugue-show-me/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: fugue-show-me
+description: 使用 show-me 和 statechart 可视化解释当前实现、代码变更、运行结果或状态变化；当用户需要图解、结构示意或缺陷路径时使用。
+---
+
+# 可视化解释
+
+先阅读并遵循[上游 show-me](../show-me/SKILL.md)，由它指导表达形式的选择。
+
+需要分析状态转换、并发、重试、取消、恢复或缺陷路径，并检查行为规则、对比修复时，阅读并遵循[上游 statechart](../statechart/SKILL.md)的建模、模型检查、出图与交付要求。用 `show-me` 解释整体结构，用 `statechart` 展示状态变化和缺陷路径，按当前问题需要组合。
+
+原版脚本安装的 TLC 使用 ASCII 模型标识符和字符串值，中文状态与步骤标签写在映射文件中，再从模型生成中文图示。
+
+说明使用用户的语言，依据当前源码、差异或已有材料，只展示本次问题需要的内容。
+
+将上游的 `Bash(open ...)` 对应为当前宿主可用的终端或文件预览工具，按实际操作系统打开 HTML 或图片。交付本地文件时提供绝对路径链接；仅在实际打开成功后说明已打开。

package/skills/fugue-stack/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: fugue-stack
+description: 开始或继续个人需求交付时，通过 fugue-cli 获取当前工作指南，选择并衔接规划、编码、代码审查与验证或实现解释；不用于纯闲聊和普通知识问答。
+---
+
+# Fugue Stack
+
+每次开始或继续任务时，运行 `fugue-cli guide`，读取当前安装版本的总览，并遵循其中与本次用户目标对应的流程。
+
+工作路由和具体要求由本次命令输出提供。按需读取其中指向的技能与材料，保留已有规划会话和产物，在本次授权范围内完成工作。

package/skills/plan-with-remote/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: plan-with-remote
+description: 当用户需要通过远端服务制定开发方案、生成执行和验收文档、查看规划进展、补充需求或审阅修改方案时使用。
+---
+
+# 远端规划
+
+将用户需求交给规划服务，向用户呈现方案、待回答的问题和最终文档。规划交付不表示软件已经实现或验收。脚本由 Node 内置能力组成，不需要从 Reconcile 源码仓库构建或安装 npm 依赖。
+
+## 开始
+
+使用 Node 22.19.0 或更高版本及 Git。在目标 Git 仓库中调用：
+
+```sh
+node <skill-root>/scripts/client.mjs --help
+```
+
+服务地址由 `RECONCILE_BASE_URL` 或 `--config` 指定；首次配置、切换服务或调整等待时间时阅读[配置说明](references/configuration.md)。仓库必须已在服务中登记；匹配失败时报告缺项。
+
+先收集用户目标、范围、约束和需求来源。保留产品事实的原意；先读取来源正文，不把链接当成正文，也不把已有建议当成已批准决定。创建 `request.json`：
+
+```json
+{
+  "title": "修复切换对象后的状态显示",
+  "description": "切换到新对象后，旧请求的结果不能覆盖新对象的状态。保留正常加载行为。",
+  "sources": [{ "label": "用户补充", "content": "切换后应立即显示新对象的加载状态。" }]
+}
+```
+
+`sources` 可省略。两种规划方式都生成执行文档与验收文档，并等待最终批准：
+
+- `lightweight`：适合范围明确的局部改动，直接形成最终文档。
+- `standard`：先审阅方案方向，用户认可后继续生成文档并进行独立评审。
+
+按用户目标明确选择；不清楚是否需要先审方向时向用户确认。
+
+```sh
+node <skill-root>/scripts/client.mjs plan --input request.json --mode lightweight
+```
+
+## 处理结果
+
+脚本输出状态、文件路径、问题和下一步命令。保存返回的 `session` 和 `review` 路径，原样传回脚本；这些文件由脚本维护，无需打开、编辑或拼装其内容。
+
+| 返回状态 | Agent 的下一步 |
+| --- | --- |
+| `running` | 使用 `read --session <路径>` 继续查看，不重复创建任务。 |
+| `review_solution` | 阅读并呈现方案；用户认可后用 `accept --review <路径>`，有修改用 `feedback`。 |
+| `review_documents` | 阅读执行文档、验收文档及返回的问题文件；用户明确批准后用 `approve --review <路径>`。 |
+| `questions` | 向用户提出返回的问题，用 `answer --review <路径> --question <编号> --text <用户回答>` 提交。确认类问题在用户同意后使用 `--confirm`。 |
+| `changes_needed` | 呈现待解决问题，按用户修改要求使用 `feedback`；不能批准。 |
+| `submission_unconfirmed` | 用 `retry --session <路径>` 重试原请求，不另建任务。 |
+| `failed` | 报告失败；需要重试时用 `retry --session <路径>`。 |
+| `approved` / `stopped` | 交付返回的文档，或报告规划已停止。 |
+
+反馈用 `feedback --review <路径> --scope <范围> --change <修改要求> --preserve <保留要求>`。范围选需求 `requirements`、方案 `solution` 或验收设计 `verification`；方案总览还支持仅改表达的 `wording`。具体可用范围见 `--help`。
+
+决定来源通过配置或 `--actor` 提供。认可、批准、停止和确认重新规划必须有用户明确授权。已获得且仍适用于本次文档的授权不重复询问。版本变化时重新呈现，不将旧决定用于新文档。
+
+阅读并解释返回的正式文档。计划中的实现、测试或效果保持为计划，不写成已完成事实。文档可以提交审阅，不代表用户已批准。

package/skills/plan-with-remote/references/configuration.md

@@ -0,0 +1,43 @@
+# 配置
+
+运行时无需安装 npm 依赖。需要 Node >=22.19.0、Git、可访问的规划服务，以及已登记到该服务的目标仓库。
+
+配置优先级：命令行参数 > 环境变量 > `--config` 指定的 JSON 文件 > 默认值。也可用 `RECONCILE_CLIENT_CONFIG` 指定配置文件路径。不会自动读取或执行 `.env` 文件。
+
+| JSON 字段 | 环境变量 | 命令行 | 默认值 |
+| --- | --- | --- | --- |
+| `baseUrl` | `RECONCILE_BASE_URL` | `--base-url` | 必须配置，无内置 IP |
+| `remote` | `RECONCILE_REMOTE` | `plan --remote` | `origin` |
+| `agent` | `RECONCILE_AGENT` | `plan --agent` | 服务中配置的项目默认客户端 |
+| `actor` | `RECONCILE_ACTOR` | 决策、反馈、回答命令的 `--actor` | 无；需明确提供 |
+| `waitMs` | `RECONCILE_WAIT_MS` | `--wait-ms` | `60000` |
+| `requestTimeoutMs` | `RECONCILE_REQUEST_TIMEOUT_MS` | `--request-timeout-ms` | `30000` |
+
+例如将配置存入仓库外的 `reconcile.config.json`，把示例域名换成实际服务地址：
+
+```json
+{
+  "baseUrl": "https://planning.example.com",
+  "remote": "origin",
+  "actor": "user:your-name",
+  "waitMs": 60000,
+  "requestTimeoutMs": 30000
+}
+```
+
+`actor` 只声明决定来源，不代表登录或身份认证，不要编造真实人员身份。`agent` 仅在明确需要覆盖项目默认值时配置，可选 `traex` 或 `grok-build`，创建后不可切换。
+
+```sh
+node <skill-root>/scripts/client.mjs plan \
+  --config /absolute/path/reconcile.config.json \
+  --input request.json --mode standard \
+  --output-dir /absolute/path/planning-output
+```
+
+默认输出目录为目标仓库的 `.plan-with-remote/<任务编号>/`。可用 `--output-dir` 指定空目录；不要把需求材料、输出或配置提交到公开仓库。后续命令直接使用返回的绝对路径。
+
+任务会记住创建时的服务地址；继续任务不需要重复配置地址。显式配置了不同地址时命令会拒绝执行，不能把同一个任务切换到其他服务。
+
+`waitMs` 限制本轮等待，结束后返回当前进展；`read` 可以继续等待，远端任务不会因此停止。每次 HTTP 请求另外受 `requestTimeoutMs` 限制。网络结果不明确时保留任务文件，用 `retry` 重试同一个请求。
+
+只有 `plan --dry-run` 提供本地输入预览，不访问服务、不创建任务；它不证明服务可达或仓库已登记。其他命令拒绝 `--dry-run`。

package/skills/plan-with-remote/scripts/client.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { configuration } from './config.mjs';
+import { start, useSession } from './planning.mjs';
+
+const commandOptions = {
+  plan: ['input', 'mode', 'output-dir', 'remote', 'agent', 'dry-run'],
+  read: ['session'], retry: ['session'],
+  accept: ['review', 'actor'], approve: ['review', 'actor'], stop: ['review', 'actor'],
+  answer: ['review', 'question', 'text', 'confirm', 'actor'],
+  feedback: ['review', 'scope', 'change', 'preserve', 'actor'],
+};
+const globalOptions = ['config', 'base-url', 'wait-ms', 'request-timeout-ms', 'help'];
+const booleanOptions = new Set(['help', 'dry-run', 'confirm']);
+const help = `用法：node <skill-root>/scripts/client.mjs <命令> [参数]
+
+plan      --input request.json --mode lightweight|standard [--output-dir 目录] [--dry-run]
+read      --session <返回的任务文件>
+retry     --session <任务文件>                 重试原提交，或重新规划失败任务
+accept    --review <返回的审阅凭据>             用户认可方案，继续生成最终文档
+approve   --review <审阅凭据>                  用户批准最终文档
+stop      --review <审阅凭据>                  用户停止规划
+answer    --review <审阅凭据> --question <编号> --text <用户回答>
+          确认类问题使用 --confirm，代替 --text
+feedback  --review <审阅凭据> --scope <范围> --change <修改要求> --preserve <保留要求>
+          方案范围：requirements|solution|wording；最终文档：requirements|solution|verification
+
+决定、反馈和回答需要 --actor <决定来源>，也可通过配置提供。
+plan 支持 --remote <Git remote>、--agent traex|grok-build；通常使用项目默认客户端。
+通用配置：--config <JSON 文件>、--base-url <URL>、--wait-ms <毫秒>、--request-timeout-ms <毫秒>。
+配置优先级：命令行 > 环境变量 > 配置文件 > 内置默认值。配置说明见 references/configuration.md。
+只有 plan 支持 --dry-run，且不会访问网络。其他命令拒绝此参数。
+输出为 JSON：状态、文件路径、待回答问题和下一步命令。无需打开任务文件或审阅凭据。
+`;
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const [command, ...args] = argv;
+  if (!command || command === '--help' || command === '-h') return { help };
+  if (!Object.hasOwn(commandOptions, command)) throw new Error('未知命令，请使用 --help。');
+  const options = Object.fromEntries([...globalOptions, ...commandOptions[command]].map(key => [key, { type: booleanOptions.has(key) ? 'boolean' : 'string' }]));
+  const { values } = parseArgs({ args, options, strict: true, allowPositionals: false });
+  if (values.help) return { help };
+  const config = await configuration(values, env);
+  return command === 'plan' ? start(values, config) : useSession(command, values, config);
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 19)) {
+    console.error('请使用 Node 22.19.0 或更高版本。');
+    process.exitCode = 1;
+  } else {
+    main().then(result => console.log(result.help ?? JSON.stringify(result, null, 2))).catch(error => {
+      const message = error.message?.match(/[\u3400-\u9fff]/) ? error.message : '命令未完成。请检查参数或配置；已提交的任务请保留任务文件后继续。';
+      console.error(JSON.stringify({ status: 'error', message, ...(error.session ? { session: error.session } : {}), ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), ...(!error.session ? { detail: error.message } : {}) }, null, 2));
+      process.exitCode = 1;
+    });
+  }
+}

package/skills/plan-with-remote/scripts/config.mjs

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const settings = {
+  baseUrl: ['base-url', 'RECONCILE_BASE_URL'],
+  remote: ['remote', 'RECONCILE_REMOTE', 'origin'],
+  agent: ['agent', 'RECONCILE_AGENT'],
+  actor: ['actor', 'RECONCILE_ACTOR'],
+  waitMs: ['wait-ms', 'RECONCILE_WAIT_MS', 60000],
+  requestTimeoutMs: ['request-timeout-ms', 'RECONCILE_REQUEST_TIMEOUT_MS', 30000],
+};
+
+export async function configuration(flags, env = process.env) {
+  const path = flags.config ?? env.RECONCILE_CLIENT_CONFIG;
+  const file = path ? JSON.parse(await readFile(resolve(path), 'utf8')) : {};
+  if (!file || typeof file !== 'object' || Array.isArray(file)) throw new Error('配置文件必须是 JSON 对象。');
+  for (const key of Object.keys(file)) {
+    if (!(key in settings)) throw new Error(`未知配置：${key}`);
+  }
+  const config = {};
+  for (const [key, [flag, variable, fallback]] of Object.entries(settings)) {
+    config[key] = flags[flag] ?? env[variable] ?? file[key] ?? fallback;
+  }
+  if (config.baseUrl !== undefined) {
+    const url = new URL(config.baseUrl);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+      throw new Error('服务地址必须是没有凭证、查询参数或片段的 HTTP(S) 地址。');
+    }
+    config.baseUrl = url.href.replace(/\/+$/, '');
+  }
+  for (const key of ['waitMs', 'requestTimeoutMs']) {
+    config[key] = Number(config[key]);
+    if (!Number.isSafeInteger(config[key]) || config[key] <= 0) throw new Error(`${key} 必须是正整数毫秒。`);
+  }
+  for (const key of ['remote', 'actor', 'agent']) {
+    if (config[key] !== undefined && (typeof config[key] !== 'string' || !config[key].trim())) {
+      throw new Error(`${key} 不能为空。`);
+    }
+  }
+  if (config.agent !== undefined && !['traex', 'grok-build'].includes(config.agent)) {
+    throw new Error('agent 只能是 traex 或 grok-build。');
+  }
+  return config;
+}
+
+export function serviceAddress(config, session) {
+  if (session && config.baseUrl && config.baseUrl !== session.baseUrl) {
+    throw new Error('当前配置指向另一服务。继续原任务时请使用创建任务的服务地址。');
+  }
+  const url = session?.baseUrl ?? config.baseUrl;
+  if (!url) throw new Error('请设置 RECONCILE_BASE_URL，或通过 --config / --base-url 配置服务地址。');
+  return url;
+}

package/skills/plan-with-remote/scripts/planning.mjs

@@ -0,0 +1,279 @@
+import { randomUUID } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { serviceAddress } from './config.mjs';
+import { createSession, loadSession, saveSession, lockSession, writeReview, loadReview, digest } from './storage.mjs';
+import { transport, resolveProject, readInput, requestPackage, validateDocuments, assertFresh } from './service.mjs';
+import { runPlanningFromAcceptedOperation, waitForProjectPreparation, continuePlanningAfterHumanInput, buildAcceptSolutionReviewCommand, buildFeedbackSolutionReviewCommand, parseSolutionReviewOperationAccepted, parseDeliveryPackage } from './protocol.mjs';
+
+function required(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`请提供 ${label}。`);
+  return value;
+}
+
+export async function start(flags, config, cwd = process.cwd()) {
+  if (!['lightweight', 'standard'].includes(flags.mode)) throw new Error('请用 --mode lightweight 或 standard 明确选择规划方式。');
+  const input = await readInput(required(flags.input, '--input'));
+  if (flags['dry-run']) return { status: 'preview', mode: flags.mode, input, message: '仅校验本地输入，没有发送网络请求或创建任务。' };
+  const baseUrl = serviceAddress(config);
+  const api = transport(baseUrl, config.requestTimeoutMs);
+  const projectId = await resolveProject(api, config.remote, cwd);
+  const requirementId = randomUUID();
+  const command = { type: 'submit_requirement', input: requestPackage(input, requirementId, projectId, flags.mode, config.agent) };
+  const state = { version: 1, requirementId, baseUrl, projectId, mode: flags.mode, phase: 'preparing', pending: { command } };
+  const path = await createSession(flags['output-dir'] ?? resolve(cwd, '.plan-with-remote', requirementId), state);
+  return withSession(path, config, async context => {
+    await submitPending(context);
+    return refresh(context);
+  });
+}
+
+export async function useSession(action, flags, config) {
+  if (['read', 'retry'].includes(action)) {
+    return withSession(required(flags.session, '--session'), config, async context => {
+      const { state } = context;
+      if (state.pending) {
+        if (action === 'read') return { status: 'submission_unconfirmed', session: context.path, message: '上次提交结果尚未确认。使用 retry 重试原请求；不要另建任务。', next: ['retry'] };
+        await submitPending(context);
+      } else if (action === 'retry' && state.outcome?.code === 'preparation_failed') {
+        const resource = `/v1/reconcile/requirements/${encodeURIComponent(state.requirementId)}/context`;
+        const current = (await context.api.request(resource)).data;
+        if (current?.project?.projectId !== state.projectId || current.preparation?.runId !== state.operationId || current.preparation?.requirementId !== state.requirementId || current.preparation.status !== 'failed' || !Number.isSafeInteger(current.snapshotRevision) || current.snapshotRevision < 1) {
+          throw new Error('项目准备状态已变化，请先读取进展。');
+        }
+        state.pending = { resource: `${resource}/retry`, command: { expectedSnapshotRevision: current.snapshotRevision } };
+        await saveSession(context.path, state);
+        await submitPending(context);
+      } else if (action === 'retry' && state.outcome?.status === 'failed' && state.outcome.code !== 'planning_wait_timeout') {
+        const report = (await context.api.post({ type: 'inspect_requirement', requirementId: state.requirementId })).data.report;
+        if (report?.requirementId !== state.requirementId || !Number.isSafeInteger(report.snapshotRevision) || report.snapshotRevision < 1) throw new Error('无法确认失败任务的当前版本。');
+        state.pending = { command: { type: 'request_replan', requirementId: state.requirementId, commandId: randomUUID(), reason: '用户请求重试失败的规划', expectedSnapshotRevision: report.snapshotRevision } };
+        await saveSession(context.path, state);
+        await submitPending(context);
+      }
+      return refresh(context);
+    });
+  }
+  const review = await loadReview(required(flags.review, '--review'));
+  return withSession(review.session, config, async context => {
+    if (context.state.pending) throw new Error('上次提交结果尚未确认，请先用 read / retry 处理原任务。');
+    const actor = required(config.actor, '--actor 或 RECONCILE_ACTOR（用户决定的来源）');
+    const command = decisionCommand(action, flags, review.outcome, context.state, actor);
+    await assertFresh(context.api, context.state, review.outcome);
+    context.state.pending = { command, outcome: review.outcome };
+    await saveSession(context.path, context.state);
+    await submitPending(context);
+    return refresh(context);
+  });
+}
+
+export function decisionCommand(action, flags, outcome, state, actor) {
+  const common = { requirementId: state.requirementId, actor, expectedSnapshotRevision: outcome.snapshotRevision, commandId: randomUUID() };
+  if (action === 'accept') {
+    if (outcome.status !== 'awaiting_solution_review') throw new Error('当前文档不需要方案认可。');
+    return buildAcceptSolutionReviewCommand({ ...common, reviewRevision: outcome.solutionReview.reviewRevision, sourceBinding: outcome.solutionReview.sourceBinding });
+  }
+  if (action === 'approve') {
+    if (outcome.status !== 'ready_for_approval' || outcome.gate.decision !== 'pass') throw new Error('当前规划不能批准，请先处理待解决的问题。');
+    return { type: 'execution_doc_decision', requirementId: state.requirementId, actor, expectedSnapshotRevision: outcome.snapshotRevision, decision: 'approve' };
+  }
+  if (action === 'stop') return { type: 'execution_doc_decision', requirementId: state.requirementId, actor, expectedSnapshotRevision: outcome.snapshotRevision, decision: 'stop' };
+  if (action === 'answer') {
+    if (outcome.status !== 'needs_human_input') throw new Error('当前没有等待回答的问题。');
+    const index = Number(flags.question);
+    if (!Number.isSafeInteger(index) || index < 1 || index > outcome.questions.length) throw new Error('请使用本次返回的问题编号。');
+    const question = outcome.questions[index - 1];
+    if (question.kind === 'stage') {
+      if (flags.confirm) throw new Error('此问题需要文字回答，不能使用 --confirm。');
+      return { ...common, type: 'submit_stage_clarification', questionKey: question.questionKey, questionRef: question.questionRef, blockerRef: question.blockerRef, answer: required(flags.text, '--text') };
+    }
+    if (question.action === 'confirm_replan') {
+      if (!flags.confirm || flags.text) throw new Error('请在用户同意重新规划后使用 --confirm。');
+    } else {
+      if (flags.confirm) throw new Error('此问题需要文字回答，不能使用 --confirm。');
+      required(flags.text, '--text');
+    }
+    return { ...common, type: 'resolve_owner_resolution', pending_resolution_identity: question.pendingResolutionIdentity, action: question.action, ...(question.action === 'clarify' ? { answer: flags.text } : {}) };
+  }
+  if (action === 'feedback') {
+    const change = required(flags.change, '--change（要修改的内容）');
+    const preserve = required(flags.preserve, '--preserve（必须保留的内容）');
+    const scope = flags.scope;
+    if (outcome.status === 'awaiting_solution_review') {
+      const scopes = { requirements: 'requirement', solution: 'technical_design', wording: 'presentation_only' };
+      if (!scopes[scope]) throw new Error('方案反馈请选择 --scope requirements、solution 或 wording。');
+      return buildFeedbackSolutionReviewCommand({ ...common, reviewRevision: outcome.solutionReview.reviewRevision, sourceBinding: outcome.solutionReview.sourceBinding, scope: scopes[scope], feedback: `需要修改：\n${change}\n\n必须保留：\n${preserve}` });
+    }
+    if (!['ready_for_approval', 'awaiting_revision'].includes(outcome.status)) throw new Error('请先读取可修改的规划文档。');
+    const stages = { requirements: 'prd_understanding', solution: 'technical_design', verification: 'verification_plan' };
+    if (!stages[scope]) throw new Error('文档反馈请选择 --scope requirements、solution 或 verification。');
+    return { ...common, type: 'execution_doc_decision', decision: 'regenerate', rerunFromStage: stages[scope], revisionConstraint: { mustChange: change, mustPreserve: preserve } };
+  }
+  throw new Error('未知操作。');
+}
+
+async function withSession(path, config, work) {
+  path = resolve(path);
+  return lockSession(path, async () => {
+    const state = await loadSession(path);
+    const api = transport(serviceAddress(config, state), config.requestTimeoutMs);
+    const context = { path, state, api, config };
+    try { return await work(context); }
+    catch (error) {
+      const diagnostic = resolve(dirname(path), `error-${randomUUID()}.json`);
+      await writeFile(diagnostic, JSON.stringify({ message: error.message, status: error.status, detail: error.detail }, null, 2), { mode: 0o600 });
+      error.session = path;
+      error.diagnostic = diagnostic;
+      throw error;
+    }
+  });
+}
+
+async function submitPending(context) {
+  const { state, api, path } = context;
+  const pending = state.pending;
+  if (!pending) return;
+  if (!pending.response) {
+    try { pending.response = pending.resource ? await api.request(pending.resource, pending.command) : await api.post(pending.command); }
+    catch (error) {
+      // A definite conflict did not accept this decision. Allow a new read;
+      // ambiguous network outcomes keep the exact pending command for retry.
+      if (error.status === 409 && pending.command.type !== 'submit_requirement') {
+        delete state.pending;
+        await saveSession(path, state);
+        error.message = '任务已变化，服务拒绝了旧决定。请使用 read 重新读取，再请用户审阅。';
+      }
+      throw error;
+    }
+    // Persist acceptance before polling, so a disconnected client can resume exactly.
+    await saveSession(path, state);
+  }
+  const data = pending.response.data;
+  const command = pending.command;
+  if (pending.resource) {
+    if (data.requirementId !== state.requirementId || data.projectId !== state.projectId || typeof data.runId !== 'string' || !data.runId) throw new Error('服务返回的准备任务身份不匹配。');
+    state.operationId = data.runId;
+    state.accepted = { data: { requirementId: state.requirementId, operationId: data.runId, polling: { nextPollAfterMs: state.accepted.data.polling.nextPollAfterMs } } };
+    state.phase = 'preparing';
+    delete state.outcome;
+  } else if (data.operationId) {
+    if (data.requirementId !== state.requirementId || typeof data.operationId !== 'string') throw new Error('服务返回的任务身份不匹配。');
+    if (command.type === 'accept_solution_review' || command.type === 'feedback_solution_review') {
+      parseSolutionReviewOperationAccepted(pending.response, command);
+    }
+    state.operationId = data.operationId;
+    state.phase = command.type === 'submit_requirement' ? 'preparing' : 'planning';
+    if (command.type === 'submit_requirement') state.accepted = pending.response;
+    delete state.outcome;
+  } else if (command.type === 'submit_stage_clarification' && data.type === 'submit_stage_clarification') {
+    state.outcome = await continuePlanningAfterHumanInput({ requirementId: state.requirementId, command, timeoutMs: context.config.waitMs }, {
+      post: async () => pending.response, wait: async () => {}, now: Date.now,
+    });
+    state.phase = 'awaiting_input';
+  } else if (command.type === 'execution_doc_decision' && ['approve', 'stop'].includes(command.decision)) {
+    const expected = command.decision === 'approve' ? 'approved' : 'stopped';
+    if (data.type !== 'execution_doc_decision' || data.result?.outcome !== expected) {
+      delete state.pending;
+      await saveSession(path, state);
+      throw new Error('服务未接受该决定，请重新读取当前规划后处理。');
+    }
+    state.phase = expected;
+    state.approvedReview = pending.outcome;
+  } else {
+    throw new Error('服务未返回可确认的结果。请保留任务文件，检查诊断后重试原请求。');
+  }
+  delete state.pending;
+  await saveSession(path, state);
+}
+
+async function refresh(context) {
+  const { state, config, api, path } = context;
+  if (state.phase === 'stopped') return { status: 'stopped', session: path, message: '规划已停止。', next: [] };
+  if (state.phase === 'approved') return delivery(context);
+  const startedAt = Date.now();
+  if (state.phase === 'preparing') {
+    try {
+      await waitForProjectPreparation({ requirementId: state.requirementId, projectId: state.projectId, timeoutMs: config.waitMs, startedAt }, state.accepted, {
+        read: () => api.request(`/v1/reconcile/requirements/${encodeURIComponent(state.requirementId)}/context`),
+        wait: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)), now: Date.now,
+      });
+    } catch (error) {
+      if (error.message === 'project preparation timed out') return running(path);
+      if (error.message.startsWith('project preparation failed:')) {
+        const report = (await api.post({ type: 'inspect_requirement', requirementId: state.requirementId })).data.report;
+        if (report?.requirementId !== state.requirementId) throw error;
+        state.outcome = { status: 'failed', requirementId: state.requirementId, viewVersion: report.snapshotRevision, code: 'preparation_failed', message: error.message, retryable: true };
+        await saveSession(path, state);
+        return present(context, state.outcome);
+      }
+      throw error;
+    }
+    state.phase = 'planning';
+    await saveSession(path, state);
+  }
+  const remaining = config.waitMs - (Date.now() - startedAt);
+  if (remaining <= 0) return running(path);
+  const outcome = await runPlanningFromAcceptedOperation({ requirementId: state.requirementId, operationId: state.operationId, expectedPlanningMode: state.mode, timeoutMs: remaining }, {
+    post: async command => {
+      const response = await api.post(command);
+      if (command.type === 'get_requirement_flow_view' && response.data.requirementId !== state.requirementId) throw new Error('返回的规划进度属于其他任务。');
+      return response;
+    },
+    wait: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)), now: Date.now,
+  });
+  state.outcome = outcome;
+  await saveSession(path, state);
+  return present(context, outcome);
+}
+
+function running(path) { return { status: 'running', session: path, message: '远端仍在处理。使用 read 继续查看，不要重复提交。', next: ['read'] }; }
+
+async function present(context, outcome) {
+  const { path, state } = context;
+  if (outcome.status === 'failed') {
+    if (outcome.code === 'planning_wait_timeout') return running(path);
+    return { status: 'failed', session: path, message: '远端规划失败。可使用 retry 请求重试，或检查诊断文件。', diagnostic: path, next: ['retry'] };
+  }
+  let documents = {};
+  let status;
+  let message;
+  let next;
+  if (outcome.status === 'awaiting_solution_review') {
+    documents = { 'solution.md': outcome.solutionReview.overview.markdown };
+    status = 'review_solution'; message = '请阅读方案。用户认可后可以继续生成最终文档，也可以先反馈修改。'; next = ['accept', 'feedback', 'stop'];
+  } else if (['ready_for_approval', 'awaiting_revision'].includes(outcome.status)) {
+    documents = validateDocuments(outcome, state.requirementId);
+    if (outcome.status === 'ready_for_approval' && (outcome.gate.status !== 'decided' || outcome.gate.decision !== 'pass')) throw new Error('规划文档尚未通过检查，不能提交批准。');
+    status = outcome.status === 'ready_for_approval' ? 'review_documents' : 'changes_needed';
+    message = status === 'review_documents' ? '请审阅执行文档和验收文档。仅在用户明确批准后提交批准决定。' : '当前规划仍有待解决的问题，暂时不能批准；请阅读文档并提交修改要求。';
+    next = status === 'review_documents' ? ['approve', 'feedback', 'stop'] : ['feedback', 'stop'];
+    const issues = collectIssues(outcome.flow);
+    if (issues.length) documents['issues.md'] = '# 待处理问题\n\n' + issues.map(text => `- ${text}`).join('\n') + '\n';
+  } else if (outcome.status === 'needs_human_input') {
+    status = 'questions'; message = '请向用户确认以下问题，再使用本次审阅凭据回答。'; next = ['answer', 'stop'];
+  } else { throw new Error('服务返回了当前客户端不支持的完成状态。'); }
+  const result = await writeReview(path, state, outcome, documents);
+  return { status, message, session: path, ...result,
+    ...(status === 'questions' ? { questions: outcome.questions.map((question, index) => ({ id: String(index + 1), question: question.prompt, response: question.action === 'confirm_replan' ? 'confirm' : 'text' })) } : {}), next };
+}
+
+function collectIssues(value) {
+  const issues = new Set();
+  function visit(item) {
+    if (!item || typeof item !== 'object') return;
+    if (typeof item.problem === 'string') issues.add(item.problem);
+    for (const child of Object.values(item)) visit(child);
+  }
+  visit(value);
+  return [...issues];
+}
+
+async function delivery({ api, state, path }) {
+  const pkg = parseDeliveryPackage((await api.post({ type: 'get_delivery_package', requirementId: state.requirementId })).data.deliveryPackage);
+  if (pkg.status !== 'ready' || pkg.planningDelivery.requirementId !== state.requirementId) throw new Error('已批准文档暂时不可读取，请使用 read 重试。');
+  if (pkg.planningCandidateRevision !== state.approvedReview.candidateRevision || digest(pkg.executionDocumentRef) !== digest(state.approvedReview.executionDocumentRef) || digest(pkg.acceptanceDocumentRef) !== digest(state.approvedReview.acceptanceDocumentRef)) throw new Error('交付文档与已审阅版本不一致。');
+  const documents = validateDocuments(state.approvedReview, state.requirementId);
+  if (documents['execution.md'] !== pkg.executionDocument || documents['acceptance.md'] !== pkg.acceptanceDocument) throw new Error('交付正文与已审阅正文不一致。');
+  const files = await writeReview(path, state, state.approvedReview, documents);
+  return { status: 'approved', session: path, documents: files.documents, message: '规划文档已批准并交付；不表示软件已经实现、部署或验收。', next: [] };
+}