@xqyz/xq-cli 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -10,6 +10,36 @@
 
 ## [Unreleased]
 
+### xq-cli `0.3.1` / WorkBuddy `0.10.1`
+
+- 修复普通项目在后端 `task_status=6`（文件解析中）时被误判为多标包/EPC，导致没有调用正常大纲生成接口、任务长时间停留在解析状态的问题。
+- 轮询 GET 请求统一增加网络重试，并识别 `stream has been aborted`、连接提前关闭等瞬时传输错误；不会因一次流中断误报生成失败。
+- WorkBuddy 对大纲阶段的传输中断保留同一 `cid` 继续核验，禁止重复创建任务；新增回归测试覆盖该恢复路径。
+- 本次配套版本：`@xqyz/xq-cli@0.3.1`、`@xqyz/workbuddy-plugin-xique@0.10.1`、Connector `0.10.1`。
+
+### WorkBuddy / SkillHub（待发布）
+
+- 修复 SkillHub 旧版 Skill 将用户明确选择的“规划”强制改为“快速”的规则冲突；规划模式现在必须传递 `--plan-mode 1`。
+- 增加 Skill 文案回归断言，禁止再次出现“固定使用计划模式=快速”或“不得接受规划模式”。
+- 发布清单新增 SkillHub 同步、客户本地更新和新会话验收步骤，避免 npm Plugin 与 SkillHub Skill 版本脱节。
+
+## [0.3.0] - 2026-08-14
+
+### xq-cli
+
+- 新增 `xq-cli plan` 规划模式命令链，覆盖补充/修正信息、确认生成/重新生成大纲、AI 调整大纲候选、确认采用候选、生成最终目录、重新生成目录、目录查看/修改和正文续写。
+- 补充/修正与 AI 调整结果先保存在本地任务状态，只有在用户明确确认 `plan confirm-outline` 或 `plan directory-generate` / `plan directory-regenerate` 后才会触发对应后台写入或生成请求。
+- AI 大纲候选不再生成本地伪章节 ID；最终保存请求与前端一致，仅提交章节内容、主题、重要度和续写标记，交由后台分配节点 ID。
+- 增加规划模式模拟 API 回归测试，覆盖意见提交、AI 候选不提前落库、候选确认和最终目录生成的顺序。
+
+## [0.10.0] - 2026-08-14
+
+### WorkBuddy
+
+- 固定依赖 `@xqyz/xq-cli@0.3.0`，支持完整规划模式命令链。
+- 更新 Skill、安装脚本、MCP Server、MCP App 和 Connector 启动参数到 `0.10.0`。
+- 通过 32 项 WorkBuddy 功能测试和 npm 包冒烟测试；npm `latest` 已指向 `0.10.0`。
+
 ## [0.2.1] - 2026-08-11
 
 ### 安全性

package/README.md

@@ -7,6 +7,7 @@ Project execution rules for agents live in [AGENTS.md](./AGENTS.md). That file d
 Project maintenance documents:
 
 - [Version changelog](./CHANGELOG.md)
+- [Version and iteration history](./docs/VERSION-HISTORY.md)
 - [Release process](./docs/RELEASING.md)
 
 ## Install from npm
@@ -53,7 +54,8 @@ npm install -g .\xqyz-xq-cli-0.2.0.tgz
 ```bash
 xq-cli login
 xq-cli login --name your-account --password your-password
-xq-cli login --base-url https://xqai.atest.qianlima.com/api --browser
+xq-cli login --api-key xq_sk_xxx
+xq-cli login --browser
 xq-cli wizard
 xq-cli wizard --file D:\bids\tender.docx
 xq-cli init --file D:\bids\tender.docx --wait
@@ -72,9 +74,9 @@ xq-cli export --cid <cid> --interactive --out D:\output
 xq-cli export --cid <cid> --out D:\output
 ```
 
-Fresh installs default to the production API address `https://ai.bidfile.qianlima.com/api`. Use `--base-url` only when you need to target another environment such as `https://xqai.atest.qianlima.com/api`.
+Fresh installs default to the production API address `https://ai.bidfile.qianlima.com/api`. Use `--base-url` only when you need to target another API endpoint.
 
-`login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login.
+`login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login. If you pass `--api-key`, it saves the API key locally and uses it for later requests.
 
 `directory view` reads the complete generated directory tree without triggering outline, directory, or content generation. Add `--json` for the raw API structure, or `--out <file-or-directory>` to save a UTF-8 JSON document.
 
@@ -128,6 +130,39 @@ xq-cli outline update --cid <cid> --file D:\output\outline.json --yes --allow-de
 
 The update command automatically calculates `updateFlag` by comparing the edited file with the latest server outline. Changes to chapter titles or themes may cause the backend to regenerate affected child directories asynchronously.
 
+## 完整规划模式流程
+
+规划模式不是一次命令跑到底，而是把前端的“智能解读 → 大纲 → 目录 → 正文”拆成可恢复的阶段。先用普通 `outline --plan-mode planning` 启动任务；拿到 `cid` 后，用 `plan` 子命令推进后续阶段：
+
+```bash
+# 1. 补充或修正招标文件理解（只写入本地待提交区，不会请求后台）
+xq-cli plan status --cid <cid> --json
+xq-cli plan feedback --cid <cid> --text "补充项目实施边界" --quote "原文片段"
+xq-cli plan correction --cid <cid> --file D:\output\corrections.json
+
+# 2. 用户确认后，提交意见并生成/重新生成大纲
+xq-cli plan confirm-outline --cid <cid> --yes --wait --json
+
+# 3. 查看大纲；需要 AI 调整时先生成候选，不会立即改后台
+xq-cli plan outline-view --cid <cid> --json
+xq-cli plan outline-ai-adjust --cid <cid> --prompt "拆分实施方案和质量保障" --out D:\output
+xq-cli plan outline-ai-apply --cid <cid> --file D:\output\outline-ai-<cid>.json --yes
+
+# 4. 用户确认候选大纲后，保存大纲并生成最终目录（不会生成正文）
+xq-cli plan directory-generate --cid <cid> --yes --wait
+
+# 5. 查看/编辑目录；如果需要重新生成目录，必须明确确认
+xq-cli plan directory-view --cid <cid> --json
+xq-cli plan directory-update --cid <cid> --file D:\output\directory.json --dry-run
+xq-cli plan directory-regenerate --cid <cid> --yes --wait
+
+# 6. 目录确认后才开始正文和导出
+xq-cli plan write --cid <cid> --wait
+xq-cli export --cid <cid> --out D:\output
+```
+
+要点：`plan status` 是恢复和重跑前的权威入口；`plan feedback` / `plan correction` 只写本地暂存，不会重复请求后台；`plan outline-ai-adjust` 会请求 AI 但只返回候选，`plan outline-ai-apply` 仍只写本地候选且不带伪造章节 ID。只有 `plan confirm-outline`、`plan directory-generate` / `plan directory-regenerate` 明确确认后才会产生后台写入或启动阶段；首次目录必须使用 `directory-generate`，已有目录覆盖才使用 `directory-regenerate`。
+
 ## Interactive menus
 
 Use the full wizard if you want a CLI flow close to the frontend configuration panel:
@@ -155,6 +190,55 @@ xq-cli outline --cid <cid> --interactive --wait
 xq-cli export --cid <cid> --interactive --out D:\output
 ```
 
+## Agent / Codex usage
+
+When another agent (Codex, OpenCLI, or an MCP wrapper) invokes `xq-cli`, it
+must treat bid generation as a stateful sequence rather than a single command:
+
+```text
+init (source file) -> outline (confirmed config + plan mode) -> review
+-> directory review (planning mode) -> write -> export
+```
+
+`--plan-mode` belongs on `outline`, not on `write` or `export`:
+
+- `0` / `quick`: enter outline generation quickly; use when the user requests
+  a quick first run or explicitly chooses 快速.
+- `1` / `planning`: enable the backend's fuller planning phase; it can take
+  longer, so use `--wait` and do not shorten the polling timeout. Use the
+  dedicated `plan` commands to collect corrections, review AI candidates,
+  generate/re-generate the directory, and stop at every confirmation gate.
+
+The backend may report `plan_mode_phase=0..3` (`analysis`, `outline`,
+`directory`, `content`) while polling. This is progress information, not a
+subcommand. If the CLI returns `reference_selection_required` or
+`supplement_required`, stop and ask the user for the required choice/input;
+never invent it. `outline view` is read-only and safe for verification.
+
+For planning mode, the agent must pause at three human confirmation gates:
+
+1. collect any `plan feedback` / `plan correction`, then call
+   `plan confirm-outline` only after the user confirms generation;
+2. show the outline. `plan outline-ai-adjust` returns an editable candidate,
+   and `plan outline-ai-apply` accepts it locally without writing the backend;
+3. after the user confirms the final outline, call `plan directory-generate`,
+   show the directory, and wait for final directory confirmation before
+   `plan write`.
+
+Use `plan directory-regenerate` only after an explicit request to replace the
+existing directory. It is not a retry/status command. Fast mode has only the
+outline confirmation gate and can then proceed to `write`.
+
+For non-TTY or JSON automation, do not silently choose generation settings.
+Ask for the missing configuration, print the final summary, wait for a clear
+confirmation (`确认`, `开始`, or `就按这个跑`), then run the commands. Validate
+enum values with `xq-cli choices outline --json` and
+`xq-cli choices export --json` before constructing arguments. See
+[`AGENTS.md`](./AGENTS.md) for the complete confirmation order and value map.
+For the complete meaning of every outline/export choice, defaults, image-style
+dependencies, EPC/multi-bid rules, margins, colors, and `--style-json`, see
+[`docs/AGENT-PARAMETER-GUIDE.md`](./docs/AGENT-PARAMETER-GUIDE.md).
+
 ## Config choices
 
 `xq-cli` now exposes the same major bid-book generation settings that the frontend outline/download flow uses.

package/package.json

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