@olierjs/fugue-cli 0.0.0-stage → 0.1.0

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: [] };
+}

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

@@ -0,0 +1,147 @@
+import { digest } from './storage.mjs';
+import { validateDocuments } from './service.mjs';
+
+const record = (value, name) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${name} is invalid`);
+  return value;
+};
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const same = (left, right) => digest(left) === digest(right);
+
+export function buildAcceptSolutionReviewCommand(input) {
+  return { type: 'accept_solution_review', ...input };
+}
+export function buildFeedbackSolutionReviewCommand(input) {
+  return { type: 'feedback_solution_review', ...input };
+}
+export function parseSolutionReviewOperationAccepted(response, command) {
+  const data = record(response?.data, 'solution review acceptance');
+  if (data.type !== 'solution_review_operation_accepted' || data.requirementId !== command.requirementId || data.commandId !== command.commandId || typeof data.operationId !== 'string' || data.polling?.operationId !== data.operationId || data.review?.reviewRevision !== command.reviewRevision || !same(data.review?.sourceBinding, command.sourceBinding) || !positive(data.lifecycle?.snapshotRevision)) throw new Error('solution review operation does not match the submitted decision');
+}
+
+export async function waitForProjectPreparation(input, accepted, deps) {
+  const data = record(accepted?.data, 'preparation acceptance');
+  if (data.requirementId !== input.requirementId || !data.operationId || !positive(data.polling?.nextPollAfterMs)) throw new Error('preparation acceptance identity is invalid');
+  while (deps.now() - input.startedAt < input.timeoutMs) {
+    const response = record((await deps.read())?.data, 'project context');
+    const preparation = response.preparation;
+    if (response.project?.projectId !== input.projectId || preparation?.projectId !== input.projectId || preparation?.requirementId !== input.requirementId || preparation?.runId !== data.operationId) throw new Error('project preparation identity mismatch');
+    if (preparation.status === 'failed') throw new Error(`project preparation failed: ${preparation.error?.code ?? 'unknown'}: ${preparation.error?.message ?? 'no details'}`);
+    if (preparation.status === 'succeeded' && preparation.baselineId && response.baseline?.baselineId === preparation.baselineId) return;
+    await deps.wait(Math.min(data.polling.nextPollAfterMs, input.timeoutMs - (deps.now() - input.startedAt)));
+  }
+  throw new Error('project preparation timed out');
+}
+
+export async function continuePlanningAfterHumanInput(input, deps) {
+  const response = await deps.post(input.command);
+  const data = record(response?.data, 'human input response');
+  if (data.operationId) return runPlanningFromAcceptedOperation({ requirementId: input.requirementId, operationId: data.operationId, timeoutMs: input.timeoutMs }, deps);
+  if (data.type !== 'submit_stage_clarification' || data.requirementId !== input.requirementId) throw new Error('human input response identity mismatch');
+  const pending = record(data.pendingStageResolution, 'pending stage resolution');
+  return { status: 'needs_human_input', requirementId: input.requirementId, viewVersion: pending.expectedSnapshotRevision, snapshotRevision: pending.expectedSnapshotRevision, questions: (pending.actions ?? []).map(action => ({ kind: 'stage', questionKey: action.questionKey, questionRef: action.questionRef, blockerRef: action.blockerRef, prompt: action.question })), resolution: { kind: 'stage', expectedSnapshotRevision: pending.expectedSnapshotRevision } };
+}
+
+export async function runPlanningFromAcceptedOperation(input, deps) {
+  const started = deps.now();
+  while (deps.now() - started < input.timeoutMs) {
+    const response = await deps.post(flowCommand(input.requirementId, input.operationId, 'summary'));
+    const summary = record(response?.data, 'planning flow');
+    summary.polling = response.polling;
+    summary.limits = response.limits;
+    if (summary.requirementId !== input.requirementId || summary.operation?.operationId !== input.operationId) throw new Error('planning flow identity mismatch');
+    if (input.expectedPlanningMode && summary.planningMode !== input.expectedPlanningMode) throw new Error('planning mode differs from the submitted request');
+    const operation = summary.operation;
+    if (summary.pendingStageResolution || summary.pendingOwnerResolution) return humanInput(summary);
+    if (summary.displayStatus === 'awaiting_revision' && ['finished', 'failed'].includes(operation.status)) {
+      const outcome = await readRevisionDocuments(input, deps, summary);
+      if (outcome) return outcome;
+      const remaining = input.timeoutMs - (deps.now() - started);
+      const interval = summary.polling?.nextPollAfterMs;
+      if (!positive(interval)) throw new Error('planning polling interval is invalid');
+      if (remaining > 0) await deps.wait(Math.min(interval, remaining));
+      continue;
+    }
+    const recovering = summary.currentStage === 'failed' && ['queued', 'running'].includes(operation.status);
+    if (summary.currentStage === 'failed' && !recovering || operation.status === 'failed' || summary.currentStage === 'stopped') return { status: 'failed', requirementId: input.requirementId, viewVersion: summary.viewVersion, code: operation.error?.code ?? 'runtime_failed', message: operation.error?.message ?? 'planning failed', retryable: operation.error?.retryable === true };
+    if (summary.currentStage === 'awaiting_solution_review' && operation.status === 'finished') {
+      if (summary.planningMode !== 'standard') throw new Error('lightweight planning cannot require solution acknowledgement');
+      const data = record((await deps.post({ type: 'get_solution_review', requirementId: input.requirementId }))?.data, 'solution review');
+      if (data.requirementId !== input.requirementId || data.snapshotRevision !== summary.viewVersion || data.review?.reviewRevision !== operation.solutionReviewResult?.reviewRevision || !same(data.review?.sourceBinding, operation.solutionReviewResult?.sourceBinding)) throw new Error('solution review is not bound to the current flow');
+      return { status: 'awaiting_solution_review', requirementId: input.requirementId, planningMode: summary.planningMode, viewVersion: summary.viewVersion, snapshotRevision: data.snapshotRevision, solutionReview: data.review, flow: summary };
+    }
+    if (summary.currentStage === 'awaiting_execution_doc_approval' && operation.status === 'finished') {
+      const fullResponse = await deps.post(flowCommand(input.requirementId, input.operationId, 'full'));
+      const flow = record(fullResponse?.data, 'full planning flow');
+      flow.limits = fullResponse.limits;
+      if (flow.requirementId !== input.requirementId || flow.operation?.operationId !== input.operationId || flow.operation?.status !== 'finished' || flow.currentStage !== 'awaiting_execution_doc_approval' || flow.viewVersion !== summary.viewVersion || flow.pageInfo?.hasMore || flow.limits?.omittedCollections?.some(value => ['artifacts', 'gateResults'].includes(value)) || !Array.isArray(flow.gateResults) || !flow.gateResults.length) throw new Error('full planning flow is incomplete or mismatched');
+      if (flow.pendingStageResolution || flow.pendingOwnerResolution) return humanInput(flow);
+      const documents = (await deps.post({ type: 'get_planning_candidate_documents', requirementId: input.requirementId }))?.data?.documents;
+      validateDocuments(documents, input.requirementId);
+      if (documents.snapshotRevision !== flow.viewVersion) throw new Error('candidate document version differs from planning flow');
+      if (flow.displayStatus === 'awaiting_revision') {
+        const revision = flow.planningRevision;
+        if (revision?.available !== true || revision.reason !== 'quality_blocked' || revision.candidateRevision !== documents.candidateRevision) throw new Error('quality revision documents do not match the candidate');
+        for (const [kind, ref] of [['execution_doc', documents.executionDocumentRef], ['acceptance_doc', documents.acceptanceDocumentRef]]) {
+          const entry = flow.planningDocuments?.[kind];
+          if (entry?.candidateRevision !== documents.candidateRevision || !same(entry.documentRef, ref)) throw new Error('quality revision document reference differs from flow');
+        }
+        return { status: 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+      }
+      if (summary.planningMode === 'standard' && !flow.boundedReview) throw new Error('full planning flow is missing bounded review');
+      const gateIds = flow.gateResults.map(gate => gate?.gateId).filter(value => typeof value === 'string');
+      const gate = documents.gate;
+      if (gate.status !== 'decided' || (summary.currentStageStatus === 'gate_blocked' && gate.decision !== 'blocked') || (gateIds.length && !gateIds.includes(`gate-decision-${gate.gateRevision}`))) throw new Error('candidate Gate differs from planning flow');
+      const report = (await deps.post({ type: 'inspect_requirement', requirementId: input.requirementId }))?.data?.report;
+      if (report?.requirementId !== input.requirementId || report.snapshotRevision !== documents.snapshotRevision || report?.approvalReport?.requirement_id !== input.requirementId || report.approvalReport.candidate_revision !== documents.candidateRevision || report.approvalReport.gate_revision !== gate.gateRevision || report.approvalReport.decision !== gate.decision) throw new Error('candidate Gate differs from current approval report');
+      return { status: gate.decision === 'pass' ? 'ready_for_approval' : 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+    }
+    const remaining = input.timeoutMs - (deps.now() - started);
+    const interval = summary.polling?.nextPollAfterMs;
+    if (!positive(interval)) throw new Error('planning polling interval is invalid');
+    await deps.wait(Math.min(interval, remaining));
+  }
+  return { status: 'failed', requirementId: input.requirementId, viewVersion: 0, code: 'planning_wait_timeout', message: 'planning wait timed out', retryable: true };
+}
+
+function flowCommand(requirementId, operationId, mode) {
+  const full = mode === 'full';
+  return { type: 'get_requirement_flow_view', requirementId, operationId, responseMode: mode, include: { stages: true, artifacts: full, runtimeRuns: full, gateResults: true, projectionJobs: full, externalProjections: full, evidenceRefs: full }, limit: { maxArtifacts: 200, maxRuntimeRuns: 200, maxEvidenceRefs: 200 }, maxItemsPerSection: 200 };
+}
+function humanInput(flow) {
+  const resolution = flow.pendingOwnerResolution ?? flow.pendingStageResolution;
+  const owner = !!flow.pendingOwnerResolution;
+  const actions = owner ? [resolution] : resolution.actions ?? [];
+  const questions = actions.map(action => {
+    if (!owner) return { kind: 'stage', questionKey: action.questionKey, questionRef: action.questionRef, blockerRef: action.blockerRef, prompt: action.question };
+    if (!['replan_required', 'human_resolution_required'].includes(action.outcome)) throw new Error('owner resolution outcome is invalid');
+    return { kind: 'owner', pendingResolutionIdentity: action.pendingResolutionIdentity, action: action.outcome === 'replan_required' ? 'confirm_replan' : 'clarify', prompt: action.reason };
+  });
+  return { status: 'needs_human_input', requirementId: flow.requirementId, viewVersion: flow.viewVersion, snapshotRevision: resolution.expectedSnapshotRevision, questions, resolution: { kind: owner ? 'owner' : 'stage', expectedSnapshotRevision: resolution.expectedSnapshotRevision } };
+}
+
+async function readRevisionDocuments(input, deps, summary) {
+  const fullResponse = await deps.post(flowCommand(input.requirementId, input.operationId, 'full'));
+  const flow = record(fullResponse?.data, 'full planning flow');
+  flow.limits = fullResponse.limits;
+  if (flow.requirementId !== input.requirementId || flow.operation?.operationId !== input.operationId) throw new Error('quality revision flow identity mismatch');
+  if (flow.limits?.omittedCollections?.some(value => ['artifacts', 'gateResults'].includes(value)) || !Array.isArray(flow.gateResults)) throw new Error('quality revision flow is missing required collections');
+  if (flow.pageInfo?.hasMore) throw new Error('quality revision flow has more pages');
+  if (!['finished', 'failed'].includes(flow.operation?.status) || flow.displayStatus !== 'awaiting_revision' || flow.viewVersion !== summary.viewVersion) return undefined;
+  if (flow.pendingStageResolution || flow.pendingOwnerResolution) return humanInput(flow);
+  const documents = (await deps.post({ type: 'get_planning_candidate_documents', requirementId: input.requirementId }))?.data?.documents;
+  validateDocuments(documents, input.requirementId);
+  if (documents.snapshotRevision !== flow.viewVersion || flow.planningRevision?.available !== true || flow.planningRevision.reason !== 'quality_blocked' || flow.planningRevision.candidateRevision !== documents.candidateRevision) throw new Error('quality revision documents do not match the candidate');
+  for (const [kind, ref] of [['execution_doc', documents.executionDocumentRef], ['acceptance_doc', documents.acceptanceDocumentRef]]) {
+    const entry = flow.planningDocuments?.[kind];
+    if (entry?.candidateRevision !== documents.candidateRevision || !same(entry.documentRef, ref)) throw new Error('quality revision document reference differs from flow');
+  }
+  return { status: 'awaiting_revision', planningMode: flow.planningMode, flow, ...documents };
+}
+export function parseDeliveryPackage(pkg) {
+  if (!pkg || !['ready', 'not_approved', 'unavailable'].includes(pkg.status)) throw new Error('delivery package is invalid');
+  if (pkg.status === 'ready') {
+    if (!pkg.planningDelivery || typeof pkg.planningDelivery.requirementId !== 'string' || pkg.planningCandidateRevision !== pkg.planningDelivery.planningCandidateRevision || !same(pkg.executionDocumentRef, pkg.planningDelivery.executionDocumentRef) || !same(pkg.acceptanceDocumentRef, pkg.planningDelivery.acceptanceDocumentRef) || typeof pkg.executionDocument !== 'string' || typeof pkg.acceptanceDocument !== 'string') throw new Error('delivery package binding is invalid');
+  }
+  return pkg;
+}

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

@@ -0,0 +1,146 @@
+import { execFileSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { digest } from './storage.mjs';
+
+export function transport(baseUrl, timeoutMs) {
+  async function request(path, command) {
+    const response = await fetch(baseUrl + path, {
+      ...(command ? { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(command) } : {}),
+      signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+    });
+    const text = await response.text();
+    let body;
+    try { body = JSON.parse(text); }
+    catch {
+      const error = new Error('服务未返回有效响应，请检查服务地址或稍后重试原任务。');
+      error.detail = text;
+      error.status = response.status;
+      throw error;
+    }
+    if (!response.ok || body?.ok !== true || !body.data) {
+      const error = new Error('服务未完成请求。请检查服务配置和项目登记；已有任务请勿改用新任务重复提交。');
+      error.detail = body;
+      error.status = response.status;
+      throw error;
+    }
+    return body;
+  }
+  return { request, post: command => request('/v1/reconcile/command', command) };
+}
+
+export async function resolveProject(api, remote, cwd) {
+  const repository = execFileSync('git', ['-C', cwd, 'remote', 'get-url', remote], { encoding: 'utf8' }).trim();
+  const identity = normalizeRepositoryIdentity(repository);
+  if (!identity) throw new Error('目标仓库需要有效的 HTTPS 或 SSH Git remote。');
+  const response = await api.request(`/v1/reconcile/projects/resolve?repository=${encodeURIComponent(repository)}`);
+  const project = response.data;
+  if (!project || typeof project.projectId !== 'string' || typeof project.repositoryIdentity !== 'string') throw new Error('服务返回的项目登记信息无效。');
+  if (project.repositoryIdentity !== identity) throw new Error('服务返回的项目与当前仓库不一致。');
+  return project.projectId;
+}
+
+export async function readInput(path) {
+  const value = JSON.parse(await readFile(path, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('需求文件必须是 JSON 对象。');
+  for (const key of Object.keys(value)) {
+    if (!['title', 'description', 'sources'].includes(key)) throw new Error(`未知需求字段：${key}`);
+  }
+  if (typeof value.description !== 'string' || !value.description.trim()) throw new Error('description 必须包含需求正文。');
+  if (value.title !== undefined && (typeof value.title !== 'string' || !value.title.trim())) throw new Error('title 必须是非空文本。');
+  if (value.sources !== undefined && !Array.isArray(value.sources)) throw new Error('sources 必须是数组。');
+  for (const source of value.sources ?? []) {
+    if (!source || Object.keys(source).some(key => !['label', 'content'].includes(key)) || typeof source.label !== 'string' || !source.label.trim() || typeof source.content !== 'string' || !source.content.trim()) {
+      throw new Error('每项来源只需提供 label 和已读取的 content 正文。');
+    }
+  }
+  return value;
+}
+
+export function requestPackage(input, id, projectId, mode, agent) {
+  return { requestId: id, planningTargetKey: projectId, planningMode: mode,
+    requirement: { description: input.description, ...(input.title ? { title: input.title } : {}) },
+    materials: (input.sources ?? []).map(source => ({ kind: 'text', ...source })),
+    ...(agent ? { agent } : {}),
+  };
+}
+
+function positive(value) { return Number.isSafeInteger(value) && value > 0; }
+function validRef(ref, fields) {
+  return ref && typeof ref === 'object' && fields.every(([key, check]) => check(ref[key]));
+}
+const text = value => typeof value === 'string';
+const nonEmpty = value => text(value) && value.length > 0;
+const integer = value => Number.isSafeInteger(value) && value > 0;
+export function validateDocuments(documents, requirementId) {
+  if (!documents || documents.requirementId !== requirementId || !positive(documents.snapshotRevision) || !positive(documents.candidateRevision)) {
+    throw new Error('返回的规划文档身份或版本无效。');
+  }
+  for (const [key, stage] of [['requirementArtifactRef', 'prd_understanding'], ['technicalDesignArtifactRef', 'technical_design']]) {
+    const ref = documents[key];
+    if (!validRef(ref, [['stage', nonEmpty], ['artifact_revision', integer], ['content_digest', nonEmpty]])) throw new Error('规划来源绑定不匹配。');
+    if (ref.stage !== stage) throw new Error('规划来源绑定不匹配。');
+  }
+  const gate = documents.gate;
+  if (!gate || (gate.status !== 'not_decided' && (gate.status !== 'decided' || !positive(gate.gateRevision) || !['pass', 'blocked'].includes(gate.decision)))) {
+    throw new Error('规划文档的检查信息缺失或无效。');
+  }
+  const rendered = {};
+  for (const [key, type, filename] of [['executionDocumentMarkdown', 'execution_doc', 'execution.md'], ['acceptanceDocumentMarkdown', 'acceptance_doc', 'acceptance.md']]) {
+    const ref = documents[key === 'executionDocumentMarkdown' ? 'executionDocumentRef' : 'acceptanceDocumentRef'];
+    const markdown = documents[key];
+    if (!validRef(ref, [['document_type', nonEmpty], ['document_revision', integer], ['content_digest', nonEmpty]]) || ref.document_type !== type || !nonEmpty(markdown)) throw new Error('正式文档 Markdown 或其版本引用缺失，请更新规划服务后重试。');
+    rendered[filename] = markdown;
+  }
+  return rendered;
+}
+
+export function normalizeRepositoryIdentity(source) {
+  if (source.startsWith('/') || /^[A-Za-z]:[\\/]/u.test(source)) return undefined;
+  let protocol;
+  let host;
+  let port = '';
+  let path;
+  const scp = /^git@([A-Za-z0-9.-]+):([A-Za-z0-9._/-]+)$/u.exec(source);
+  if (scp) {
+    host = scp[1]; path = scp[2]; protocol = 'ssh';
+    if (path.includes('..')) return undefined;
+  } else {
+    if (!/^https:\/\//iu.test(source) && !/^ssh:\/\//iu.test(source)) return undefined;
+    const match = /^(https|ssh):\/\/([^/?#]+)(\/[^?#]*)$/iu.exec(source);
+    const rawPath = match?.[3];
+    if (!match || !rawPath || rawPath.includes('//') || rawPath.includes('\\') || /%2f/iu.test(rawPath) || rawPath.split('/').some(part => part === '.' || part === '..')) return undefined;
+    let url;
+    try { url = new URL(source); } catch { return undefined; }
+    if (!url.hostname || url.password || url.search || url.hash || (url.protocol === 'https:' && url.username) || (url.protocol === 'ssh:' && url.username && url.username !== 'git')) return undefined;
+    protocol = url.protocol === 'https:' ? 'https' : 'ssh'; host = url.hostname.toLowerCase(); port = url.port;
+    try { path = decodeURIComponent(rawPath.replace(/^\//u, '')); } catch { return undefined; }
+    if (!path || path.split('/').some(part => part === '.' || part === '..')) return undefined;
+  }
+  path = path.replace(/\/$/u, '').replace(/\.git$/u, '').replace(/\/$/u, '');
+  if (!path) return undefined;
+  const defaultPort = (protocol === 'https' && port === '443') || (protocol === 'ssh' && port === '22');
+  return !port || defaultPort ? `${host.toLowerCase()}/${path}` : `${protocol}://${host.toLowerCase()}:${port}/${path}`;
+}
+
+export async function assertFresh(api, state, outcome) {
+  if (outcome.status === 'awaiting_solution_review') {
+    const response = await api.post({ type: 'get_solution_review', requirementId: state.requirementId });
+    const current = response.data;
+    if (!current || current.type !== 'get_solution_review' || !current.review || !current.review.overview) throw new Error('服务返回的方案审阅信息无效。');
+    if (current.requirementId !== state.requirementId || current.snapshotRevision !== outcome.snapshotRevision || digest(current.review.sourceBinding) !== digest(outcome.solutionReview.sourceBinding) || current.review.reviewRevision !== outcome.solutionReview.reviewRevision || current.review.overview.markdown !== outcome.solutionReview.overview.markdown) {
+      throw new Error('方案已变化，请重新读取并请用户审阅；旧决定不能用于新方案。');
+    }
+  } else if (['ready_for_approval', 'awaiting_revision'].includes(outcome.status)) {
+    const current = (await api.post({ type: 'get_planning_candidate_documents', requirementId: state.requirementId })).data.documents;
+    validateDocuments(current, state.requirementId);
+    for (const key of ['snapshotRevision', 'candidateRevision', 'gate', 'requirementArtifactRef', 'technicalDesignArtifactRef', 'executionDocumentRef', 'acceptanceDocumentRef']) {
+      if (digest(current[key]) !== digest(outcome[key])) throw new Error('规划文档已变化，请重新读取并请用户审阅；旧决定不能用于新文档。');
+    }
+    for (const key of ['executionDocumentMarkdown', 'acceptanceDocumentMarkdown']) {
+      if (current[key] !== outcome[key]) throw new Error('规划文档正文已变化，请重新读取并请用户审阅；旧决定不能用于新文档。');
+    }
+  } else {
+    const report = (await api.post({ type: 'inspect_requirement', requirementId: state.requirementId })).data.report;
+    if (report?.requirementId !== state.requirementId || report.snapshotRevision !== outcome.snapshotRevision) throw new Error('待处理问题已变化，请重新读取后再回答。');
+  }
+}