@xqyz/xq-cli

Standalone CLI project for xique brand task workflows.

Project execution rules for agents live in AGENTS.md. That file defines the mandatory config-confirmation flow before any bid generation run.

Project maintenance documents:

• Version changelog
• Version and iteration history
• Release process

Install from npm

Install the published package from the public npm registry:

npm install -g @xqyz/xq-cli

If your local npm registry points to a mirror or private source, use:

npm install -g @xqyz/xq-cli --registry=https://registry.npmjs.org/

Upgrade to the latest published version with:

npm update -g @xqyz/xq-cli --registry=https://registry.npmjs.org/

Install from this repo

npm install -g D:\code\xq-cli

Pack and share

cd D:\code\xq-cli
npm pack

That command produces a .tgz tarball which can be shared and installed with:

npm install -g .\xqyz-xq-cli-0.2.0.tgz

Usage

xq-cli login
xq-cli login --name your-account --password your-password
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
xq-cli outline --cid <cid> --interactive --wait
xq-cli outline --cid <cid> --wait
xq-cli outline view --cid <cid>
xq-cli outline view --cid <cid> --out D:\output\outline.json
xq-cli outline update --cid <cid> --file D:\output\outline.json --dry-run --json
xq-cli outline update --cid <cid> --file D:\output\outline.json --yes
xq-cli directory view --cid <cid>
xq-cli directory view --cid <cid> --out D:\output\directory.json
xq-cli gallery-status --json
xq-cli write --cid <cid> --wait
xq-cli status --cid <cid> --content --json
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 API endpoint.

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.

gallery-status checks the same /image/library/query endpoint as the latest frontend. available=true means “我的图库” contains at least one image and may be enabled for generation; an empty gallery remains unavailable until the user uploads an image in the Xique frontend.

When outline --wait or write --wait hits a required response-basis step, the CLI will pause and ask you to choose 0/1/2 before continuing. It no longer auto-selects a default when you just press Enter.

write --wait now also retries sequelForOutline when the directory phase stalls at the outline-complete step, and auto-calls generateAllUnfinished if the backend reports 100% but still leaves unfinished chapters behind.

write follows the frontend flow:

order/charge -> c/viewStep(101) -> task/autoGenerateContent

View and update an existing outline

View the complete current outline without triggering outline generation:

xq-cli outline view --cid <cid>
xq-cli outline view --cid <cid> --json

Export an editable JSON copy:

xq-cli outline view --cid <cid> --out D:\output\outline.json

Edit the outLine array in that file. Keep an existing chapter's id, change text, theme, or important, reorder the array to reorder chapters, add a chapter without an id, and remove a chapter from the array to delete it. important accepts 1 (key chapter) or 2 (normal chapter).

Always preview the server-side diff first:

xq-cli outline update --cid <cid> --file D:\output\outline.json --dry-run

Apply after reviewing the preview:

xq-cli outline update --cid <cid> --file D:\output\outline.json --yes

Deleting existing chapters has an additional protection flag:

xq-cli outline update --cid <cid> --file D:\output\outline.json --yes --allow-delete

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 子命令推进后续阶段：

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

xq-cli wizard
xq-cli wizard --file D:\bids\tender.docx

The wizard will prompt for:

• source bid file
• article length
• writing mode
• visual style
• table quantity / color / style
• planning mode
• optional image-source toggles
• export template / layout / output path

You can also open menus for a single phase:

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:

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 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.

Config choices

xq-cli now exposes the same major bid-book generation settings that the frontend outline/download flow uses.

Inspect the selectable enums with:

xq-cli choices
xq-cli choices outline
xq-cli choices export --json

Outline generation now supports frontend-backed options such as:

• --page-scope / --page-scope-code
• --base
• --theme-style
• --table-quantity
• --table-color
• --table-style
• --info-img, --scene-img, --online-img, --mermaid-img, --knowledge-img
• --mermaid-style
• --plan-mode
• --multi-bid-id, --multi-bid-type
• --epc-engineer-type

Export now supports frontend-backed style options such as:

• --template
• --style-json
• --start-index
• --auto-number
• --add-mark
• --layout
• --top-margin, --bottom-margin, --left-margin, --right-margin
• --table-color, --table-style
• --skeleton-color
• --img-title-color, --heading4-color, --heading5-color
• --content-title-color, --content-color
• --heading4-text-color, --heading5-text-color, --content-title-text-color, --img-title-text-color

Example outline config:

xq-cli outline --cid <cid> --page-scope 3 --base expert --theme-style 4 --table-quantity rich --table-color blue --table-style zebra --mermaid-style blue --knowledge-img 1 --scene-img 1 --plan-mode quick --wait

Example export config:

xq-cli export --cid <cid> --template 2 --layout enhanced --table-color green --table-style header --auto-number 1 --add-mark 0 --top-margin 2.54 --bottom-margin 2.54 --left-margin 3.18 --right-margin 3.18 --skeleton-color 1276C1 --img-title-color 1276C1 --out D:\output

Advanced export style JSON can mirror the frontend custom format dialog payload:

{
  "startIndex": 1,
  "directorySettings": [
    { "type": 1, "serialNumber": "1", "fontName": "SimSun", "fontSize": "16", "alignment": "1", "bold": "1", "level": "1" }
  ],
  "contentSettings": {
    "serialNumber1": "10",
    "serialNumber2": "11",
    "serialNumber3": "12",
    "serialNumber4": "13",
    "fontName": "SimSun",
    "fontSize": "12",
    "alignment": "3",
    "bold": "0"
  }
}

xq-cli export --cid <cid> --template 5 --style-json D:\styles\custom-style.json --out D:\output

OpenCLI plugin

This repo also includes a local OpenCLI plugin in opencli-plugin-xique/.