@wkgeo/cli 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,6 +32,27 @@ npx -y @wkgeo/cli@latest orders list
32
32
  * 完整的给 AI 的说明书见 [`SKILL.md`](./SKILL.md);**也可以一条命令直接取出来**:
33
33
  `npx -y @wkgeo/cli@latest skill`(默认打**纯文本原文**;`--json` 时在 `data.markdown` 里)。
34
34
 
35
+ ### 0.1 建站规范(`spec` / `init`,2026-11-21)
36
+
37
+ 建站不是随便建:栏目类型、每栏目独立模板、`target_type` 兼容、首页版块跳转、图标都有硬规则。
38
+ 这份规范**随包分发**,一条命令就能拿到,也可以写进你的项目让 agent 自动读:
39
+
40
+ ```bash
41
+ npx -y @wkgeo/cli@latest spec # 规范全文(默认纯 markdown,重定向即可存成文件)
42
+ npx -y @wkgeo/cli@latest spec --agents # 只打「给 AI 的精简版」
43
+ npx -y @wkgeo/cli@latest init # 只看计划(默认 dry-run,零写盘)
44
+ npx -y @wkgeo/cli@latest init --confirm # 写进项目:AGENTS.md / CLAUDE.md / .cursorrules / Copilot 指令
45
+ ```
46
+
47
+ * **为什么要写进项目**:agent 读哪个文件是 **agent 自己**决定的(DSH/Codex 读 `AGENTS.md`、
48
+ Claude Code 读 `CLAUDE.md`、Cursor 读 `.cursorrules`、Copilot 读 `.github/copilot-instructions.md`),
49
+ CLI 控制不了它读什么,只能把文件放到它该在的位置 —— 所以 `init` 默认**四个都写**(`--agents` 可只写几个)。
50
+ * **幂等、不动你的内容**:写进去的那一段用 `<!-- wkgeo:site-spec:begin/end -->` 包着,
51
+ 再跑一次是**原地替换**;文件里已有你自己的内容时**只在末尾追加**;内容没变就一个字节都不写。
52
+ * **三处同源**:`spec` 输出、`init` 写进项目的那一段、`wkgeo-site-spec` skill 都出自同一份
53
+ `cli/spec/SITE-SPEC.md`(改规则只改那份;`node cli/scripts/gen-site-spec.mjs --check` 防漂移)。
54
+ * 规范里每条都标了**已实现 / 实现中** —— 实现中的条目不要当既有行为依赖。
55
+
35
56
  ---
36
57
 
37
58
  ## 1. 安装与分发(三条路径,主线是 npm)
package/SKILL.md CHANGED
@@ -43,6 +43,8 @@ version: 1.0.0
43
43
  * 用户问"**这个令牌能干什么 / 还剩多久 / 怎么立刻作废**" → `auth status`(账号 + scopes + 动作面)/ `auth token`(只给前 4 位 + 长度 + 到期)/ `auth revoke`(服务端吊销 + 删本地)
44
44
  * 用户说"**帮我绑自己的域名**" → CLI **没有**域名能力(域名命令已全部删除);引导到会员中心 / CMS 后台的「域名」里操作,**不要**自己编一条域名命令
45
45
  * **你自己需要这份手册**(换机器、上下文被截断、想确认某个参数)→ `skill`(把本文件原文打出来,见 §2)
46
+ * **你要建站 / 改栏目 / 做模板 / 写 `site-manifest.json`** → **先跑 `spec`**(建站规范:栏目类型、每栏目独立模板、`target_type` 兼容、首页版块跳转、图标),见 §2.1
47
+ * 用户说"**让 AI 按我们的规范建站**"/"把规矩写进项目" → `init --confirm`(把规范写进 `AGENTS.md` / `CLAUDE.md` / `.cursorrules` / Copilot 指令,agent 下次开会话自己读)
46
48
 
47
49
  **不要用**:
48
50
 
@@ -85,6 +87,25 @@ npx -y @wkgeo/cli@latest skill > SKILL.md # 直接落一份到本地,离线
85
87
  说明跑的是**被裁剪的包**或只拷了 `lib/` 的开发目录(正常 npm 安装包里一定有这份文件)。
86
88
  换官方包 `npx -y @wkgeo/cli@latest skill` 即可;这不是命令用错了。
87
89
 
90
+ ### ⭐ 建站规范:`wkgeo spec` / `wkgeo init`
91
+
92
+ ```bash
93
+ npx -y @wkgeo/cli@latest spec # 规范全文(栏目 / 模板 / 首页版块 / 图标,逐条标"已实现 / 实现中")
94
+ npx -y @wkgeo/cli@latest spec --agents # 只打"给 AI 的精简版"(= init 写进项目的那一段,逐字节相同)
95
+ npx -y @wkgeo/cli@latest spec --json # 标准信封
96
+ npx -y @wkgeo/cli@latest init # 只看计划(默认 dry-run,零写盘)
97
+ npx -y @wkgeo/cli@latest init --confirm # 写进项目:AGENTS.md / CLAUDE.md / .cursorrules / .github/copilot-instructions.md
98
+ npx -y @wkgeo/cli@latest init --confirm --agents agents,claude # 只写点名的
99
+ ```
100
+
101
+ * **三处同源**:`spec` 命令、`init` 写的约定文件、`wkgeo-site-spec` skill 全部出自同一份
102
+ `cli/spec/SITE-SPEC.md`(改规则只改那一份;生成器 `--check` 防漂移)。
103
+ * `init` **幂等**:内容用 `<!-- wkgeo:site-spec:begin/end -->` 包着 —— 已有那一段就**原地替换**,
104
+ 文件里有用户自己的内容就**只在末尾追加**(不覆盖、不重复);算出来没变就一个字节都不写。
105
+ * `init` **不猜你是哪个 agent**(env 里没有可靠特征),所以默认四个文件都写,`--agents` 可只写几个。
106
+ * 写完要让 agent **重开会话 / 重新读一次**约定文件才生效(多数 agent 只在会话开始时读)。
107
+ * `spec` 与 `skill` 同一条输出例外:**默认永远是纯 markdown**(管道里也是),只有显式 `--json` 才套信封。
108
+
88
109
  ---
89
110
 
90
111
  ## 3. 输出契约(**关键**)
@@ -118,6 +139,8 @@ npx -y @wkgeo/cli@latest skill > SKILL.md # 直接落一份到本地,离线
118
139
 
119
140
  | 命令 | 作用 | 关键参数 |
120
141
  | --- | --- | --- |
142
+ | `spec` | **建站规范全文**(栏目 / 模板 / 首页版块 / 图标,逐条标"已实现 / 实现中");默认纯 markdown,管道里也不套 JSON | `--agents`(只打精简版)、`--json` |
143
+ | `init` | 把规范的精简版写进项目:`AGENTS.md` / `CLAUDE.md` / `.cursorrules` / `.github/copilot-instructions.md`(幂等、不覆盖用户内容、默认 dry-run) | `--agents all\|none\|<名单>`、`--confirm` |
121
144
  | `login` | 授权一次(令牌存本地 30 天;**默认浏览器回调**,设备码仅兜底) | `--device`、`--no-wait`、`--device-continue`、`--no-auto-device`、`--callback-first-wait <秒>`(可选,默认关闭)、`--no-browser`、`--open-browser`、`--scope`、`--timeout <秒>` |
122
145
  | `whoami` | 当前是谁(账号标识) | `--verbose` |
123
146
  | `logout` | 退出(删本地凭据 + 服务端吊销) | `--local-only` |
package/lib/api.mjs CHANGED
@@ -151,8 +151,11 @@ export function fnOf(action, { legacy = legacyEndpointsEnabled() } = {}) {
151
151
  /**
152
152
  * ★ 2026-11-17(task-627):账务域下单**只在 `/cli` 后面**(cli-fc 再转发到 `/billing-core`)。
153
153
  * 逃生阀也回不去:`/order` 没有 `orderCreate` 这个动作,`/user` 更没有。
154
+ *
155
+ * ★ 2026-11-20(cli-price-quote):账务域**只读报价** `orderQuote` 同理(cli-fc 白名单转发)——
156
+ * 加购价的唯一来源是它(与 `orderCreate` 实收同源),逃生阀也不许绕到别的函数。
154
157
  */
155
- if (action === 'orderCreate') return 'cli';
158
+ if (action === 'orderCreate' || action === 'orderQuote') return 'cli';
156
159
  if (legacy) {
157
160
  if (FN_ORDER.has(action)) return 'order';
158
161
  return 'user';
@@ -86,6 +86,15 @@ import {
86
86
  } from './orders.mjs';
87
87
  import { appsListCommand, appsRevokeCommand } from './apps.mjs';
88
88
  import { skillCommand } from './skill.mjs';
89
+ /**
90
+ * ★ 2026-11-21(老板:CLI 里要把建站规范说清楚,最好还有 skill 那样的说明文档):
91
+ * `spec` = 打印随包分发的 **建站规范**(`spec/SITE-SPEC.md`,栏目 / 模板 / 首页版块 / 图标的规则);
92
+ * `init` = 把规范的精简版写进项目的 AGENTS.md / CLAUDE.md / .cursorrules / Copilot 指令
93
+ * (agent 启动时自己读,CLI 只能把文件放到位,控制不了它读什么)。
94
+ * 三处同源:spec 命令 / init 写的约定文件 / `wkgeo-site-spec` skill 都出自同一份 markdown。
95
+ */
96
+ import { specCommand } from './spec.mjs';
97
+ import { initCommand } from './init.mjs';
89
98
  /* ★ 2026-11-19 task-1250(老板:CLI 只做 CMS 内容管理,跟域名没有关系,不在那里操作):
90
99
  命令面已删除 ——
91
100
  · `domainops.mjs` :`domain search|buy|order` / `domain zone *` / `esa *`(12 条)
@@ -367,6 +376,13 @@ export const COMMANDS = [
367
376
  aiAskCommand,
368
377
  aiChatCommand,
369
378
  contextExportCommand,
379
+ /**
380
+ * `spec` / `init`:建站规范的两个出口(2026-11-21)——
381
+ * `spec` 打印全文(/ `--agents` 只打精简版),`init` 把精简版写进项目的四个约定文件。
382
+ * 与 `skill` 同属「(基础)」:不登录也能跑、纯本地。
383
+ */
384
+ specCommand,
385
+ initCommand,
370
386
  /**
371
387
  * `skill`:把随包分发的 `SKILL.md` 原文打印出来(AI 端自取手册)。
372
388
  * 放在 config 前面 —— 两者同属「(基础)」,都是"不登录也能跑"的本地命令。
@@ -571,6 +587,8 @@ export function renderHelp(name = null) {
571
587
  * 没有任何命令能把它取出来 —— AI 只能去 node_modules 里翻,等于"分发了但拿不到"。
572
588
  */
573
589
  out.push(' wkgeo skill # 打印给 AI 端的操作手册(随包分发)');
590
+ out.push(' wkgeo spec # 打印建站规范(栏目/模板/首页版块/图标)');
591
+ out.push(' wkgeo init --confirm # 把规范写进项目的 AGENTS.md / CLAUDE.md / .cursorrules / Copilot');
574
592
  out.push('');
575
593
  out.push('通用参数:--json(机器可读;非终端下默认开启)/ --text(强制人类可读)');
576
594
  out.push(' --base <url>(平台面)/ --cms-base <url>(CMS 面)/ --client-id <id> / --credentials <path>');
@@ -0,0 +1,111 @@
1
+ /**
2
+ * `init` 命令:把建站规范的**精简版**写进项目的四个「agent 启动即读」文件。
3
+ *
4
+ * ## 为什么是"写文件",不是"CLI 主动注入"
5
+ * agent 读什么是 **agent 自己的事**:DSH 读 `AGENTS.md`、Claude Code 读 `CLAUDE.md`、
6
+ * Cursor 读 `.cursorrules`、Copilot 读 `.github/copilot-instructions.md`。
7
+ * CLI 无法控制它读什么,能做的只有**把文件放到它该在的位置** —— 就是这条命令。
8
+ *
9
+ * ⚠️ CLI **不猜**调用者是哪个 agent:`process.env` 里没有可靠特征(`CLAUDECODE` / `CURSOR_*` /
10
+ * `DSH_*` 都可能缺失,用户也可能在任意 shell 里跑、或由别的工具当子进程调)。
11
+ * 所以默认**四个都写**,用 `--agents` 让用户自己挑。
12
+ *
13
+ * ## 幂等与"不动用户已有内容"
14
+ * * 写入内容用 `<!-- wkgeo:site-spec:begin -->` … `<!-- wkgeo:site-spec:end -->` 包起来;
15
+ * * 已有我们的标记 ⇒ **原地替换**(改规范后重跑不会重复追加);
16
+ * * 文件有内容但没有标记 ⇒ **只在末尾追加**,用户写的一个字不动;
17
+ * * 算出来一字节不差 ⇒ `unchanged`,不写盘。
18
+ *
19
+ * ## 默认 dry-run
20
+ * 与全 CLI 的写操作一致:不加 `--confirm` 只打计划(零写盘),`--confirm` 才真写。
21
+ */
22
+
23
+ import path from 'node:path';
24
+
25
+ import { readSpecMarkdown, planAgentFiles, resolveAgentFiles, writeAgentFiles } from '../site-spec.mjs';
26
+
27
+ /** 人读模式下的动作词(JSON 里仍是 created / appended / replaced / unchanged) */
28
+ const ACTION_LABEL = {
29
+ created: '将新建',
30
+ appended: '已有内容 → 追加到末尾(用户内容不动)',
31
+ replaced: '已有规范段 → 原地替换',
32
+ unchanged: '内容没变 → 跳过',
33
+ };
34
+
35
+ export const initCommand = {
36
+ name: 'init',
37
+ summary: '把建站规范写进项目的 AGENTS.md / CLAUDE.md / .cursorrules / Copilot 指令(可重复跑)',
38
+ usage: 'wkgeo init [--agents all|none|<名单>] [--confirm] [--json]',
39
+ flags: {
40
+ agents: {
41
+ type: 'string',
42
+ desc: '写哪些约定文件:all(默认)/ none / 逗号分隔(agents,claude,cursor,copilot,也认 AGENTS.md 这类文件名)',
43
+ },
44
+ 'dry-run': { type: 'boolean', desc: '只看计划不写盘(不加 --confirm 时本来就是 dry-run)' },
45
+ confirm: { type: 'boolean', desc: '真写盘(不加只打计划)' },
46
+ },
47
+ examples: [
48
+ 'wkgeo init # 只看计划(零写盘)',
49
+ 'wkgeo init --confirm # 四个约定文件都写 / 追加',
50
+ 'wkgeo init --confirm --agents agents,claude # 只写 AGENTS.md 与 CLAUDE.md',
51
+ 'wkgeo init --confirm --agents none # 一个都不写(等价于空跑)',
52
+ ],
53
+ notes: [
54
+ '写的是建站规范的**精简版**(与 `wkgeo spec --agents` 逐字节相同);全文跑 `wkgeo spec`。',
55
+ '可重复跑:自己那一段用 `<!-- wkgeo:site-spec:begin/end -->` 包着,改规范后重跑会**原地替换**,不会重复追加。',
56
+ '**不覆盖用户内容**:文件已有你自己的内容时只在末尾追加我们这一段(文件里已有我们的段则只替换那一段)。',
57
+ 'CLI 不判断你用的是哪个 agent,所以默认四个都写;用 `--agents` 可只写其中几个。',
58
+ '写完后让 agent **重新开一个会话 / 重新读一次**约定文件才会生效(多数 agent 只在会话开始时读)。',
59
+ ],
60
+ async run(ctx) {
61
+ const { out, flags } = ctx;
62
+ const dir = process.cwd();
63
+ const info = readSpecMarkdown();
64
+ const files = resolveAgentFiles(flags.agents);
65
+ const plan = planAgentFiles({ dir, markdown: info.markdown, files });
66
+
67
+ /** JSON 里不回整份 content(可能几十 KB),只给动作 + 字节数 + 路径 */
68
+ const rows = plan.map((one) => ({
69
+ path: one.path,
70
+ abs_path: one.absPath,
71
+ label: one.label,
72
+ action: one.action,
73
+ existed: one.existed,
74
+ bytes: Buffer.byteLength(one.content, 'utf8'),
75
+ }));
76
+
77
+ const dryRun = flags.confirm !== true;
78
+ const writeResult = dryRun ? { written: [], skipped: rows.filter((r) => r.action === 'unchanged').map((r) => r.path) } : writeAgentFiles(plan);
79
+ const data = {
80
+ dir,
81
+ source: info.path,
82
+ dry_run: dryRun,
83
+ files: rows,
84
+ written: writeResult.written,
85
+ skipped: writeResult.skipped,
86
+ };
87
+
88
+ if (!out.json) {
89
+ out.head(dryRun ? `建站规范 → ${dir}(dry-run,零写盘)` : `建站规范 → ${dir}`);
90
+ for (const one of rows) {
91
+ const mark = one.action === 'unchanged' ? '·' : '+';
92
+ out.line(` ${mark} ${one.path.padEnd(32)} ${ACTION_LABEL[one.action] || one.action}(${one.bytes} 字节)`);
93
+ }
94
+ out.line('');
95
+ out.info(` 规范来源:${info.path}`);
96
+ out.info(' 全文:wkgeo spec | 只要这一段:wkgeo spec --agents');
97
+ if (files.length === 0) out.warn(' --agents none:没有要写的文件(空跑)。');
98
+ else if (dryRun) out.notice('\n这是 dry-run:加 --confirm 才真写盘。');
99
+ else out.ok(`已写 ${writeResult.written.length} 个文件,跳过 ${writeResult.skipped.length} 个(内容没变)。`);
100
+ out.info(' 提示:多数 agent 只在会话开始时读约定文件,写完请重开会话(或让它重新读一次)。');
101
+ }
102
+
103
+ ctx.done(data);
104
+ return data;
105
+ },
106
+ };
107
+
108
+ /** 供单测直接拿目录解析口径(与命令层保持一致:永远用 cwd,不吃 --site 之类) */
109
+ export function resolveInitDir(cwd = process.cwd()) {
110
+ return path.resolve(String(cwd || process.cwd()));
111
+ }
@@ -16,6 +16,14 @@
16
16
  * ⚠️ 没有做"把余额补到一个已存在的 pending 订单上"的命令 —— 服务端**没有这个 action**
17
17
  * (`placeOrder` 里余额抵扣只在建单那一刻发生)。要做需要服务端新增接口,
18
18
  * 这属于"要主线程决定"的事,已在报告里列出。
19
+ *
20
+ * ## 加购价从哪来(★ 2026-11-20 cli-price-quote):只认服务端报价
21
+ * `orders create` 的金额 / 单价 / 份数**全部来自** `billing.orderQuote{kind:'quota'}`
22
+ * (`/cli` → `wkgeo-cli-fc` 白名单转发 → 网关 `/billing-core`),与实收
23
+ * `orderCreate{kind:'quota'}` **同源**。
24
+ * CLI 不再本地「单价 × 数量」:旧逻辑 `list.find(quota_key === …)` 取到列表第一条
25
+ * (`mandatory` 行 ¥2.00),而服务端实扣 `addon` 行 ¥1.87 ⇒ 显示 ¥2.00、实扣 ¥1.87。
26
+ * 只查价不建单:`wkgeo orders create --product <代码> --units N --dry-run`。
19
27
  */
20
28
 
21
29
  import { UsageError, CliError, EXIT } from '../errors.mjs';
@@ -36,6 +44,137 @@ function newOrderIdempotencyKey() {
36
44
  return `cli-quota-${Date.now().toString(36)}-${rand}`;
37
45
  }
38
46
 
47
+ /* ------------------------------------------------------------------ */
48
+ /* 计价:只问服务端(CLI 一行乘法都不写) */
49
+ /* ------------------------------------------------------------------ */
50
+
51
+ /**
52
+ * 服务端加购报价 —— **CLI 唯一的取价口径**(★ 2026-11-20 cli-price-quote)。
53
+ *
54
+ * ## 为什么要改成"问服务端"(事故背景)
55
+ * 改造前这里是「本地 `list.find(quota_key === … && kind === 'resource')` + 单价 × 数量」:
56
+ * `listProducts` 的排序是 `order by p.sort_order, p.code`,同一个 `quota_key` 下后台有
57
+ * **两条正常配置的行** —— `mandatory`(套餐必选 / 含项,¥2.00)与 `addon`(资源包,¥1.87)。
58
+ * 本地 `find` 命中**列表第一条** = mandatory ⇒ CLI 显示 ¥2.00,而服务端实扣 addon 行 ¥1.87。
59
+ * 估算与余额预检共用那一刻的 `estimateCents` ⇒ 两处都错。
60
+ *
61
+ * ## 现在的口径
62
+ * `orderQuote{kind:'quota', quota_key, quota_amount}` = 会员端「订单确认页」用的那条报价,
63
+ * 它内部调的就是 `orderCreate` 的计价函数(服务端不变量
64
+ * `orderQuote().payable_cents === orderCreate().amount_cents`)。
65
+ * ⇒ 金额 / 单价 / 份数 / 月数**全部照抄服务端回包**,本地不乘、不取整、不挑行算钱。
66
+ * ⇒ 以后后台怎么调价、加购取哪条产品行,CLI 都自动跟对(不会再有第二套算法)。
67
+ *
68
+ * ## 失败策略:**不回落本地估算**
69
+ * 显示一个"看起来对"的金额比报错更糟(这就是钱的事故)。报价拿不到就明确报错、不给金额,
70
+ * 让用户稍后重试或去网页看价 —— 绝不拿目录价糊一个数出来。
71
+ *
72
+ * @returns {Promise<{payable_cents:number, original_cents:number, unit_price_cents:number|null,
73
+ * units:number|null, unit:string|null, months:number|null, product_code:string|null,
74
+ * product_name:string|null, quota_key:string, quota_amount:number,
75
+ * wallet_balance_cents:number|null, via:string}>}
76
+ */
77
+ async function fetchQuotaQuote(ctx, { quotaKey, quotaAmount }) {
78
+ const payload = { kind: 'quota', quota_key: quotaKey, quota_amount: quotaAmount };
79
+ let res;
80
+ try {
81
+ res = await ctx.callData('orderQuote', payload);
82
+ } catch (e) {
83
+ throw new CliError(`查询加购报价失败:${(e && e.message) || e}`, {
84
+ kind: (e && e.kind) || 'error',
85
+ code: e && e.code !== undefined ? e.code : null,
86
+ exitCode: e && e.exitCode !== undefined ? e.exitCode : EXIT.ERROR,
87
+ hint:
88
+ '报价由服务端账务域给出(与实收同一份算法),拿不到报价就**先不要下单**:' +
89
+ '稍后重试;要核对历史金额用 `wkgeo orders list`,要看网页价去会员中心「产品 / 加购」。',
90
+ details: { action: 'orderQuote', ...payload },
91
+ });
92
+ }
93
+
94
+ const numOf = (v) => {
95
+ if (v === undefined || v === null || v === '') return null;
96
+ const n = Number(v);
97
+ return Number.isFinite(n) ? n : null;
98
+ };
99
+ const payable = numOf(res && res.payable_cents);
100
+ if (payable === null || payable <= 0) {
101
+ /** 报价为空 / 0 ⇒ 绝不显示金额(宁可报错,也不给一个错的价格) */
102
+ throw new CliError('服务端没有给出可用的报价金额(未显示任何金额)', {
103
+ kind: 'quote_empty',
104
+ code: 502,
105
+ hint:
106
+ '报价与实收同源,拿不到就**不要下单**:稍后重试;若一直为空,请在会员中心「产品 / 加购」页核对价格,' +
107
+ '或把这条输出发给平台负责人(附 `--verbose` 的脱敏原文)。',
108
+ details: { action: 'orderQuote', ...payload, raw: res || null },
109
+ });
110
+ }
111
+
112
+ const originalCents = numOf(res && res.original_cents);
113
+ const quotedAmount = numOf(res && res.quota_amount);
114
+ return {
115
+ payable_cents: Math.trunc(payable),
116
+ original_cents: originalCents === null ? Math.trunc(payable) : Math.trunc(originalCents),
117
+ discount_cents: Math.trunc(numOf(res && res.discount_cents) || 0),
118
+ unit_price_cents: numOf(res && res.unit_price_cents),
119
+ units: numOf(res && res.units),
120
+ unit: (res && res.unit) || null,
121
+ months: numOf(res && res.months),
122
+ product_code: (res && res.product_code) || null,
123
+ product_name: (res && res.product_name) || null,
124
+ quota_key: String((res && res.quota_key) || quotaKey),
125
+ quota_amount: quotedAmount === null ? quotaAmount : quotedAmount,
126
+ wallet_balance_cents: numOf(res && res.wallet_balance_cents),
127
+ coupon: (res && res.coupon) || null,
128
+ via: (res && res.via) || 'billing.orderQuote',
129
+ };
130
+ }
131
+
132
+ /**
133
+ * 本地挑产品行 —— **只用来定"买多少"(`quota_amount`),绝不用来算钱**。
134
+ *
135
+ * 顺序:① 产品代码精确命中(用户点名的那条;非资源型直接交给调用方报错);
136
+ * ② **同一 `quota_key` 的资源行里优先 `sale_type='addon'`(资源包)** —— 服务端
137
+ * `orderCreate` / `orderQuote` 永远按 `(sale_type='addon') desc, sort_order, code`
138
+ * 取行(`_shared/addon-product-pick.js`),所以倍率必须按同一行算;
139
+ * ③ 没有 addon 行时回落:用户点的 code 行,再不行第一条。
140
+ *
141
+ * ⚠️ 兜底路径说明(方案 ① 的位置):金额一律来自上面的服务端报价,这里的 `price_cents`
142
+ * **一次都不读**;② 只为把 `quota_multiplier`(⇒ 基础单位数量)算成后台配的那条资源包行,
143
+ * 与 `orderCreate` / `orderQuote` 的取行口径一致。
144
+ * 今天的 `listProducts` **还没下发 `sale_type`**,所以 ② 暂时不生效、实际走 ③ —— 一旦后端
145
+ * 补上该列,这里自动与服务端同序,不需要再改 CLI。**没有"未登录也要显示价格"的命令**:
146
+ * `products list` / `orders create` 都必须是登录态,未登录时 CLI 直接报需要登录、不显示金额。
147
+ */
148
+ function pickProductRow(list, wanted) {
149
+ const byCode = list.find((p) => p.code === wanted);
150
+
151
+ /* 非资源型(套餐 / 一次性服务)交给调用方报"CLI 只支持加量包"——不要拿它去猜配额 */
152
+ if (byCode && byCode.kind !== 'resource') return byCode;
153
+
154
+ /** 目标配额键:`--product` 传的可能是产品代码,也可能是配额键,两种都要能落到同一个 quota_key */
155
+ const quotaKey = (byCode && byCode.params && byCode.params.quota_key) || '';
156
+
157
+ const candidates = list.filter(
158
+ (p) =>
159
+ p.kind === 'resource' &&
160
+ p.params &&
161
+ (quotaKey ? p.params.quota_key === quotaKey : p.params.quota_key === wanted),
162
+ );
163
+ const isAddon = (p) => String(p.sale_type || '').trim().toLowerCase() === 'addon';
164
+
165
+ /**
166
+ * ② 服务端为这个 quota_key 实际会取的那一行(addon 优先)—— **数量以它为准**:
167
+ * `orderCreate` / `orderQuote` 永远按 `(sale_type='addon') desc, sort_order, code` 取行,
168
+ * 所以即使用户点的是必选行的 code,倍率也应当按 addon 行算,别买成另一个数量。
169
+ */
170
+ const addon = candidates.find(isAddon);
171
+ if (addon) return addon;
172
+
173
+ /* ③ 没有 addon 行:服务端回落 `sort_order, code` 的第一条 —— 用户点了 code 就用那一行 */
174
+ return byCode || candidates[0] || null;
175
+ }
176
+
177
+
39
178
  /* ------------------------------------------------------------------ */
40
179
  /* products list */
41
180
  /* ------------------------------------------------------------------ */
@@ -78,6 +217,7 @@ export const productsListCommand = {
78
217
  rows,
79
218
  );
80
219
  out.info(' 下单示例:wkgeo orders create --product <产品代码> --units 1');
220
+ out.info(' 查加购价(不建单、不扣款):wkgeo orders create --product <产品代码> --units 1 --dry-run');
81
221
  }
82
222
  ctx.done(data);
83
223
  return data;
@@ -92,8 +232,8 @@ export const ordersCreateCommand = {
92
232
  name: 'orders create',
93
233
  summary: '下单(余额足够时**当场用钱包余额付清**;不会发起真实微信扣款)',
94
234
  usage:
95
- 'wkgeo orders create --product <产品代码> --units <份数> [--allow-wechat]\n' +
96
- 'wkgeo orders create --quota <配额键> --amount <基础单位数> [--allow-wechat]',
235
+ 'wkgeo orders create --product <产品代码> --units <份数> [--allow-wechat] [--dry-run]\n' +
236
+ 'wkgeo orders create --quota <配额键> --amount <基础单位数> [--allow-wechat] [--dry-run]',
97
237
  flags: {
98
238
  product: { type: 'string', desc: '产品代码或配额键(见 `wkgeo products list`)' },
99
239
  units: { type: 'string', desc: '购买份数(默认 1,按产品单位计价)' },
@@ -103,6 +243,10 @@ export const ordersCreateCommand = {
103
243
  type: 'boolean',
104
244
  desc: '余额不足时仍创建订单(会返回微信 code_url,**需要用户自己扫码**;CLI 不会扣款)',
105
245
  },
246
+ 'dry-run': {
247
+ type: 'boolean',
248
+ desc: '只向服务端查**报价**(不建单、不扣款):加购价以它为准,与实收同一份算法',
249
+ },
106
250
  },
107
251
  async run(ctx) {
108
252
  const { out, flags } = ctx;
@@ -117,8 +261,8 @@ export const ordersCreateCommand = {
117
261
  let quotaKey;
118
262
  let quotaAmount;
119
263
  let units = null;
120
- let estimateCents = null;
121
- let productInfo = null;
264
+ /** 本地命中的产品行:**只用来定数量 / 展示名称**,金额一律不从这里取 */
265
+ let catalogHit = null;
122
266
 
123
267
  if (flags.product) {
124
268
  units = flags.units === undefined ? 1 : Number(flags.units);
@@ -129,9 +273,7 @@ export const ordersCreateCommand = {
129
273
  ...p,
130
274
  params: p.params || {},
131
275
  }));
132
- const hit =
133
- list.find((p) => p.code === flags.product) ||
134
- list.find((p) => p.params.quota_key === flags.product && p.kind === 'resource');
276
+ const hit = pickProductRow(list, flags.product);
135
277
 
136
278
  if (!hit) {
137
279
  throw new CliError(`找不到产品(或配额键)「${flags.product}」`, {
@@ -149,15 +291,9 @@ export const ordersCreateCommand = {
149
291
  }
150
292
  const mult = Number(hit.params.quota_multiplier) || 1;
151
293
  quotaKey = hit.params.quota_key;
294
+ /** ★ 基础单位数量 = 份数 × 倍率;**这是"买多少",不是"多少钱"** */
152
295
  quotaAmount = units * mult;
153
- estimateCents = units * (Number(hit.price_cents) || 0);
154
- productInfo = {
155
- code: hit.code,
156
- name: hit.name,
157
- unit: hit.unit || '份',
158
- unit_price_cents: Number(hit.price_cents) || 0,
159
- quota_multiplier: mult,
160
- };
296
+ catalogHit = hit;
161
297
  } else {
162
298
  quotaKey = flags.quota;
163
299
  quotaAmount = Number(flags.amount);
@@ -167,13 +303,78 @@ export const ordersCreateCommand = {
167
303
  units = null;
168
304
  }
169
305
 
306
+ /**
307
+ * ★ 2026-11-20(cli-price-quote):**金额只问服务端**(不再 `单价 × 数量`)。
308
+ * 报价 = 会员端确认页那条 `orderQuote{kind:'quota'}`,与 `orderCreate` 实收同源。
309
+ * 失败直接抛(不显示任何金额),见 `fetchQuotaQuote()` 的说明。
310
+ */
311
+ const quote = await fetchQuotaQuote(ctx, { quotaKey, quotaAmount });
312
+ const estimateCents = quote.payable_cents;
313
+
314
+ /** 展示用的商品信息:优先服务端报价回显(它就是实收那一条产品行) */
315
+ const productInfo = {
316
+ code: quote.product_code || (catalogHit && catalogHit.code) || null,
317
+ name: quote.product_name || (catalogHit && catalogHit.name) || quotaKey,
318
+ unit: quote.unit || (catalogHit && catalogHit.unit) || '份',
319
+ unit_price_cents: quote.unit_price_cents,
320
+ units: quote.units,
321
+ months: quote.months,
322
+ quota_multiplier: catalogHit ? Number(catalogHit.params.quota_multiplier) || 1 : null,
323
+ /** 金额来源(排查用:永远应是服务端报价,不是本地估算) */
324
+ price_source: 'server_quote',
325
+ };
326
+ /** 下单用的配额数量以**报价回显**为准(保证报价与建单是同一单) */
327
+ const chargeQuotaAmount = quote.quota_amount;
328
+
329
+ /* ---- 只查价:不建单、不扣款(加购价的权威查询入口) ---- */
330
+ if (flags.dryRun === true) {
331
+ const data = {
332
+ dry_run: true,
333
+ writes: 0,
334
+ quote,
335
+ amount_cents: quote.payable_cents,
336
+ amount_text: formatMoney(quote.payable_cents),
337
+ product: productInfo,
338
+ quota: { quota_key: quote.quota_key, quota_amount: chargeQuotaAmount, units },
339
+ balance_before_cents: quote.wallet_balance_cents,
340
+ balance_before_text:
341
+ quote.wallet_balance_cents === null ? null : formatMoney(quote.wallet_balance_cents),
342
+ };
343
+ if (!out.json) {
344
+ out.head('加购报价(dry-run:**没有**下单、**没有**扣款)');
345
+ out.line(` 商品:${productInfo.name}${productInfo.code ? `(${productInfo.code})` : ''}`);
346
+ const unitPrice =
347
+ quote.unit_price_cents === null ? '-' : formatMoney(quote.unit_price_cents);
348
+ const unitLabel = productInfo.unit || '份';
349
+ const unitCount = quote.units === null ? quotaAmount : quote.units;
350
+ const months = quote.months === null ? 1 : quote.months;
351
+ out.line(` 单价:${unitPrice} / ${unitLabel} × ${unitCount} × ${months} 个月`);
352
+ if (quote.discount_cents > 0) {
353
+ out.line(` 原价:${formatMoney(quote.original_cents)}(优惠 ${formatMoney(quote.discount_cents)})`);
354
+ }
355
+ out.line(` 合计:${formatMoney(quote.payable_cents)}`);
356
+ if (quote.wallet_balance_cents !== null) {
357
+ const enough = quote.wallet_balance_cents >= quote.payable_cents;
358
+ out.line(
359
+ ` 钱包余额:${formatMoney(quote.wallet_balance_cents)}(${enough ? '够' : `不够,差 ${formatMoney(quote.payable_cents - quote.wallet_balance_cents)}`})`,
360
+ );
361
+ }
362
+ out.info(` 金额来源:${quote.via}(服务端报价,与实收同一份算法)`);
363
+ out.info(' 真下单:去掉 --dry-run(余额够就当场付清;CLI 不会发起微信扣款)。');
364
+ }
365
+ ctx.done(data);
366
+ return data;
367
+ }
368
+
170
369
  /* ---- 钱包预检:余额不足时**默认拒绝**,而不是悄悄建一张要扫码的单 ---- */
171
- let balanceBefore = null;
172
- try {
173
- const w = await ctx.callData('getMyWallet', { limit: 1 });
174
- balanceBefore = Number(w && w.balance_cents) || 0;
175
- } catch (e) {
176
- out.warn(`读取钱包余额失败(继续下单):${e.message}`);
370
+ let balanceBefore = quote.wallet_balance_cents;
371
+ if (balanceBefore === null) {
372
+ try {
373
+ const w = await ctx.callData('getMyWallet', { limit: 1 });
374
+ balanceBefore = Number(w && w.balance_cents) || 0;
375
+ } catch (e) {
376
+ out.warn(`读取钱包余额失败(继续下单):${e.message}`);
377
+ }
177
378
  }
178
379
  if (
179
380
  balanceBefore !== null &&
@@ -200,32 +401,52 @@ export const ordersCreateCommand = {
200
401
  * 不再打 `/order` 的 `createQuotaOrder`(钱路径只留 billing 一条:
201
402
  * `placeOrder` + `fulfillOrder`,金额只从 `product.price_cents` 算)。
202
403
  * ⚠️ 必须带 `idempotency_key`:同键重放回原单(不会多建单、不会二次扣余额)。
404
+ *
405
+ * ★ 2026-11-20(cli-price-quote):`quota_amount` 用**报价回显的那个数**
406
+ * (`chargeQuotaAmount`)—— 保证"报价的单"和"建出来的单"是同一份参数,
407
+ * 不会出现「报价按 A 行算、下单按 B 行算」。
203
408
  */
204
409
  const res = await ctx.callData('orderCreate', {
205
410
  kind: 'quota',
206
- quota_key: quotaKey,
207
- quota_amount: quotaAmount,
411
+ quota_key: quote.quota_key,
412
+ quota_amount: chargeQuotaAmount,
208
413
  idempotency_key: newOrderIdempotencyKey(),
209
414
  });
210
415
  const paid = !!(res && res.paid);
416
+ const chargedCents = res && res.amount_cents !== undefined ? Number(res.amount_cents) : null;
211
417
  const data = {
212
418
  order_id: (res && res.order_id) || null,
213
419
  out_trade_no: (res && res.out_trade_no) || null,
214
420
  paid,
215
421
  amount_cents: Number(res && res.amount_cents) || null,
216
422
  amount_text: res && res.amount_cents !== undefined ? formatMoney(res.amount_cents) : null,
423
+ /** 服务端报价(下单前展示 / 余额预检用的就是这个数) */
424
+ quoted_cents: quote.payable_cents,
425
+ quoted_text: formatMoney(quote.payable_cents),
217
426
  wallet_paid_cents: Number(res && res.wallet_paid_cents) || 0,
218
427
  pay_amount_cents: res && res.pay_amount_cents !== undefined ? Number(res.pay_amount_cents) : null,
219
428
  code_url: (res && res.code_url) || null,
220
429
  expires_at_minutes: (res && res.expires_at_minutes) || null,
221
430
  message: (res && res.message) || null,
222
431
  product: productInfo,
223
- quota: { quota_key: quotaKey, quota_amount: quotaAmount, units },
432
+ quota: { quota_key: quote.quota_key, quota_amount: chargeQuotaAmount, units },
224
433
  balance_before_cents: balanceBefore,
225
434
  balance_after_cents:
226
435
  balanceBefore !== null && paid ? balanceBefore - (Number(res && res.wallet_paid_cents) || 0) : balanceBefore,
436
+ /** 明细:服务端返回的金额行(来自同一份报价/下单快照) */
437
+ quote,
227
438
  };
228
439
 
440
+ /**
441
+ * 报价 ≠ 实收是一条**钱的不变量**(服务端保证 `orderQuote().payable_cents === orderCreate().amount_cents`)。
442
+ * 真出现不一致就明确提示(不改金额、不重试),把这条输出留给平台负责人排查。
443
+ */
444
+ if (chargedCents !== null && chargedCents !== quote.payable_cents) {
445
+ out.warn(
446
+ `注意:报价 ${formatMoney(quote.payable_cents)} 与实收 ${formatMoney(chargedCents)} 不一致 —— 请把这条输出发给平台负责人(订单 ${data.order_id})`,
447
+ );
448
+ }
449
+
229
450
  if (!out.json) {
230
451
  out.head('下单结果');
231
452
  out.line(` 订单号:${data.order_id}`);