@xqyz/xq-cli 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -10,12 +10,45 @@
 
 ## [Unreleased]
 
-### 正文阶段安全闸门复核
+## [0.3.8 / WorkBuddy Plugin 0.10.21 / SkillHub 1.0.5] - 2026-08-25
+
+### 规划模式卡住保护
+
+- 解析唤醒后的 `success=2` 只允许在 30 秒内等待后台一致性同步；状态没有推进时返回可诊断的 `TASK_PARSE_NOT_ADVANCED`，不再继续等待到 10/30 分钟超时。
+- WorkBuddy Plugin 固定依赖 `@xqyz/xq-cli@0.3.8`，并把最低版本校验同步提升，避免旧 CLI 重新进入不完整链路。
+- SkillHub 安装说明明确要求重启后核对实际加载的 Plugin/CLI 版本；旧 MCP 进程仍在运行时不得宣称已更新。
+- 新增回归覆盖：`multiBiddingChoice` 延迟推进、持续 `success=2` 快速失败，以及旧版本运行时拒绝。
+
+## [0.3.7 / WorkBuddy Plugin 0.10.20 / SkillHub 1.0.4] - 2026-08-25
+
+### 规划模式解析唤醒修复
+
+- 修复规划模式新任务只调用 `/task/preSet`、没有调用 `/proxy/multiBiddingChoice` 的问题。
+- 规划模式现在与 Web 端一致：先保存用户配置，再唤醒异步解析；解析结果补齐后才展示“智能解读确认”，不会提前生成大纲。
+- 保留规划模式确认闸门：用户确认智能解读后才调用 `plan confirm-outline`，不会因为修复唤醒链路而跳过大纲、目录审阅。
+- 新增真实模拟回归测试，覆盖解析字段为空时的唤醒顺序和禁止提前调用正式生成接口。
+
+## [0.3.6 / WorkBuddy Plugin 0.10.19] - 2026-08-24
+
+### 安装和二次更新闭环
+
+- SkillHub 正式身份统一为 `@org-kkw9656k/xique-ai`；安装器会同步完整 Skill 到正式目录、修正 `.skills_store_lock.json`，并把历史 `xique-bid` 重复目录移入可恢复的 `.skill-backup`。
+- 用户明确安装或更新时通过 npm 受控标签 `workbuddy-stable` 获取最新稳定安装器；安装器解析自身版本后，仍将精确版本写入 `mcp.json`，所以 WorkBuddy 重启不会因浮动标签加载不同构建。
+- 一次更新同时覆盖 Skill、MCP Plugin 和内置 xq-cli。MCP 配置保留其他服务，更新前备份；新 MCP 必须完成 `initialize` 握手，失败会恢复旧配置且不宣称成功。
+- Windows 支持带空格的 Node/npx 路径；macOS/Linux 不依赖 `sort -V`，支持 WorkBuddy 的 `bin/node` 和扁平 Node 布局，并检查执行权限。
+- 新增新装、旧 Skill 身份迁移、锁记录修复、重复更新幂等、MCP 启动失败回滚及 Windows 安装回归测试。
+- npm 正式包并发安装验收发现共享 npx 缓存会在 Windows 产生 `ENOTEMPTY` 和包文件缺失；`0.10.16` 起为每次 bootstrap 使用独立缓存，并为安装器增加跨进程锁和喜鹊专属 MCP 运行缓存。
+- `0.10.17` 在 Windows 上通过隐藏 Node 进程延迟清理 bootstrap 缓存，并在下次安装时回收陈旧目录，避免 npx 子进程短暂占用造成残留。
+- `0.10.18` 查询 `workbuddy-stable` 时强制 `--prefer-online`，避免 npm 本地元数据缓存让已移动的稳定标签继续解析到旧版本。
+- `0.10.19` 改为读取 npm `dist-tags --json` 中的 `workbuddy-stable` 字段，不再依赖 `包@标签 version` 的 CDN 别名解析，避免标签移动后的短暂旧值。
+- 安装前先从 npm 官方 registry 解析 `workbuddy-stable` 的精确版本，安装器再校验自身版本；即使 npx 复用错误缓存，也会在写配置前失败。`0.10.15` 已发布但不作为稳定安装版本。
+
+### 正文阶段安全闸门
 
 - 大纲和目录实际保存前强制读取喜鹊后台权威任务状态，不再因为本机没有任务缓存而绕过“正文已开始/已完成”保护。
 - 状态校验放在 `--dry-run` 和用户确认之后、写接口之前，保留离线差异预览能力，同时覆盖确认后发生的并发状态变化。
 - 新增回归测试：无本地缓存的已完成任务不会调用大纲或目录保存接口；纯预览不会额外依赖任务详情接口。
-- 该修复当前属于未发布改动；npm 上的 `@xqyz/xq-cli@0.3.5` 和已发布 WorkBuddy Plugin `0.10.14` 尚未包含它，发布前必须递增 xq-cli 补丁版本并同步 Plugin 依赖。
+- `@xqyz/xq-cli@0.3.6` 包含该修复，WorkBuddy Plugin `0.10.19` 固定依赖此版本。
 
 ### WorkBuddy Plugin 0.10.14 / SkillHub 1.0.11 发布记录
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xqyz/xq-cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "CLI for xique bid-book task workflows",
   "type": "module",
   "scripts": {

package/src/cli.mjs

@@ -5,7 +5,7 @@ import http from 'http';
 import https from 'https';
 import os from 'os';
 import path from 'path';
-import readline from 'readline/promises';
+import readline from 'node:readline/promises';
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import axios from 'axios';
@@ -35,6 +35,12 @@ const DEFAULT_BASE_URL = 'https://ai.bidfile.qianlima.com/api';
 const DEFAULT_PARSE_INTERVAL_MS = 10_000;
 const DEFAULT_TASK_INTERVAL_MS = 10_000;
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+// multiBiddingChoice acknowledges the request before the extraction service
+// necessarily updates getFileAsyncResult. Give that short async hand-off a
+// bounded window, then fail with diagnostics instead of entering the long
+// outline polling timeout.
+const DEFAULT_PARSER_WAKEUP_TIMEOUT_MS = 30_000;
+const PARSER_WAKEUP_INTERVAL_MS = 2_000;
 const DEFAULT_SOURCE_FROM = 'xique';
 const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 const DEFAULT_EXPORT_TEMPLATE_INDEX = 1;
@@ -1409,8 +1415,8 @@ async function handleOutlineUnlocked(args, state) {
 
     const planningMode = Number(params.planMode) === 1;
     const triggerMode = planningMode
-        ? await preparePlanningAnalysis(client, params)
-        : await triggerOutlineGeneration(client, outlineSnapshot, params);
+        ? await preparePlanningAnalysis(client, state, outlineSnapshot, params, effectiveArgs)
+        : await triggerOutlineGeneration(client, state, outlineSnapshot, params, effectiveArgs);
     saveTaskSnapshot(state, cid, {
         ...outlineSnapshot,
         ...pickTaskSnapshot(params),
@@ -2056,7 +2062,7 @@ function buildOutlineParams(snapshot, args) {
     });
 }
 
-async function triggerOutlineGeneration(client, snapshot, params) {
+async function triggerOutlineGeneration(client, state, snapshot, params, args = {}) {
     // The web flow has two deliberately different paths:
     //
     // * legacy tasks (task_status === 0) already contain the parsed
@@ -2080,16 +2086,99 @@ async function triggerOutlineGeneration(client, snapshot, params) {
         multiBidId: params.multiBidId ?? snapshot.multiBidId,
         epcEngineerType: normalizeEpcEngineerTypeForProxy(params.epcEngineerType ?? snapshot.epcEngineerType),
     }));
+    await verifyParserWakeUp(client, state, snapshot.cid, snapshot.uuid, params, false, args);
     return 'multiBiddingChoice';
 }
 
-async function preparePlanningAnalysis(client, params) {
-    // The backend intentionally pauses plan-mode tasks after parsing. The user
-    // must review that analysis before generateDirectoryByCid starts the outline.
+async function preparePlanningAnalysis(client, state, snapshot, params, args = {}) {
+    // Planning mode pauses before outline generation, but new tasks still need
+    // the same parser wake-up as quick mode. Without multiBiddingChoice,
+    // autoGenerateDirectoryJobHandler never fills requirement/rating/plan and
+    // the analysis poll remains pending until the local timeout.
+    if (Number(snapshot.task_status) === 0) {
+        // Legacy tasks already contain parsed fields and do not need the
+        // asynchronous parser wake-up endpoint.
+        await postJson(client, '/task/preSet', params);
+        return 'planningAnalysisPrepared';
+    }
     await postJson(client, '/task/preSet', params);
+    await getJson(client, '/proxy/multiBiddingChoice', compactObject({
+        uuid: snapshot.uuid,
+        multiBidId: params.multiBidId ?? snapshot.multiBidId,
+        epcEngineerType: normalizeEpcEngineerTypeForProxy(params.epcEngineerType ?? snapshot.epcEngineerType),
+    }));
+    await verifyParserWakeUp(client, state, snapshot.cid, snapshot.uuid, params, true, args);
     return 'planningAnalysisPrepared';
 }
 
+async function verifyParserWakeUp(client, state, cid, uuid, params, planningMode, args = {}) {
+    const expectedMultiBidId = String(params.multiBidId || '').trim();
+    const requestedTimeoutMs = secondsToMs(
+        numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000),
+    );
+    const timeoutMs = Math.min(DEFAULT_PARSER_WAKEUP_TIMEOUT_MS, requestedTimeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    let latest = null;
+
+    // `multiBiddingChoice` returns HTTP 200 before the extraction record is
+    // necessarily visible to the next read. Allow a short consistency window,
+    // but never fall back to the long generation poll while the backend still
+    // advertises "waiting for package selection" (success=2).
+    for (let attempt = 0; ; attempt += 1) {
+        const [taskResponse, parseStatus] = await Promise.all([
+            getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT }),
+            fetchParseStatus(client, state, cid, uuid),
+        ]);
+        const taskDetail = taskResponse?.data || {};
+        const parseSuccess = Number(parseStatus.success);
+        const selectedMultiBidId = String(
+            parseStatus.choiceMultiBiddingId
+            || taskDetail.choiceMultiBiddingId
+            || taskDetail.multiBidId
+            || '',
+        ).trim();
+        const savedPlanMode = normalizePlanModeValue(taskDetail.planMode);
+        latest = {
+            taskDetail,
+            parseStatus,
+            parseSuccess,
+            selectedMultiBidId,
+            savedPlanMode,
+        };
+        saveTaskSnapshot(state, cid, pickTaskSnapshot({
+            ...taskDetail,
+            ...parseStatus,
+            cid,
+            uuid,
+            choiceMultiBiddingId: selectedMultiBidId,
+        }));
+
+        const selectionRequired = expectedMultiBidId && expectedMultiBidId !== 'notMultiBid';
+        const selectionMatches = !selectionRequired || selectedMultiBidId === expectedMultiBidId;
+        const parseAdvanced = [1, 3, 4].includes(parseSuccess);
+        const planModeMatches = !planningMode || savedPlanMode === 1;
+        if (parseAdvanced && selectionMatches && planModeMatches) {
+            return latest;
+        }
+
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            break;
+        }
+        await sleep(Math.min(PARSER_WAKEUP_INTERVAL_MS, remainingMs));
+    }
+
+    const selected = latest?.selectedMultiBidId || '-';
+    const expected = expectedMultiBidId || '-';
+    const success = latest?.parseSuccess ?? '-';
+    const savedPlanMode = latest?.savedPlanMode ?? '-';
+    throw new Error(
+        `[TASK_PARSE_NOT_ADVANCED] 标包/规划配置提交后后端状态没有推进，已停止等待。` +
+        `期望标包=${expected}，后端标包=${selected}，解析状态 success=${success}，` +
+        `后端 planMode=${savedPlanMode}。请不要重复提交同一任务；先查询任务状态或重新安装最新版 WorkBuddy 插件。`,
+    );
+}
+
 async function setPlanModePhase(client, cid, planModePhase) {
     const response = await postJson(client, '/task/setPlanModePhase', { cid, planModePhase });
     const returned = normalizePlanModePhase(response?.data?.planModePhase);
@@ -2607,6 +2696,11 @@ async function waitForPlanningAnalysisReady(client, state, cid, uuid, args) {
             ? await fetchParseStatus(client, state, cid, uuid)
             : { success: 1 };
         const parseSuccess = Number(parseStatus.success);
+        if (parseSuccess === 2) {
+            throw new Error(
+                '[TASK_PARSE_NOT_ADVANCED] 规划模式仍处于等待标包/EPC选择（success=2），未进入解析阶段，已停止等待。',
+            );
+        }
         const issues = collectParseIssues(parseStatus);
         if (parseSuccess === 4 && issues.length > 0) {
             const autoIgnore = resolveAutoIgnoreIssue(issues, args, uuid, handledIssues);
@@ -4912,6 +5006,7 @@ function pickTaskSnapshot(source) {
         blindGenerationMode: source.blindGenerationMode || source.blindBidConfirm?.blindGenerationMode,
         multiBidId: source.multiBidId,
         multiBidType: source.multiBidType,
+        choiceMultiBiddingId: source.choiceMultiBiddingId,
         epcEngineerType: source.epcEngineerType,
         outlineReferenceType: source.outlineReferenceType,
         referenceStatus: source.referenceStatus,