@dmall-inc/wd-cli 0.0.0-stage → 0.1.0

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
@@ -1,3 +1,366 @@
1
- # Temporary Holding Version
1
+ # @dmall-inc/wd-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 水滴平台的命令行工具。用统一身份登录一次,选定工作空间,就能在终端里访问平台上你看得到的技能、知识库、应用、会话、评测与可观测数据。
4
+
5
+ ```bash
6
+ npm i -g @dmall-inc/wd-cli
7
+
8
+ wd-cli auth login --base-url https://agents.example.com
9
+ wd-cli workspace use 42
10
+ wd-cli skill list
11
+ ```
12
+
13
+ 免安装试一下:`npx @dmall-inc/wd-cli auth login --base-url https://agents.example.com`
14
+
15
+ 需要 Node.js 18 或更高版本。零运行时依赖。
16
+
17
+ ---
18
+
19
+ ## 目录
20
+
21
+ - [登录](#登录)
22
+ - [选工作空间](#选工作空间)
23
+ - [CI 与脚本:令牌直连](#ci-与脚本令牌直连)
24
+ - [配置](#配置)
25
+ - [输出与退出码](#输出与退出码)
26
+ - [命令参考](#命令参考)
27
+ - [api:通用逃生口](#api通用逃生口)
28
+ - [常见问题](#常见问题)
29
+ - [给编码 agent 用](#给编码-agent-用)
30
+ - [开发与发布](#开发与发布)
31
+
32
+ ---
33
+
34
+ ## 登录
35
+
36
+ ```bash
37
+ wd-cli auth login --base-url https://agents.example.com
38
+ ```
39
+
40
+ 会在本机起一个临时回调服务,打开浏览器让你完成统一身份登录,拿到令牌后存在本地。整个过程用的是 OAuth2 授权码 + PKCE,密钥不落在命令行里,也不写进任何日志。
41
+
42
+ **没有浏览器**(SSH 会话、容器、远程开发机):
43
+
44
+ ```bash
45
+ wd-cli auth login --base-url https://agents.example.com --no-browser
46
+ ```
47
+
48
+ 会打印一段授权地址。在任意能上网的浏览器里打开、登录,然后把浏览器地址栏里的整段回调地址粘回终端即可。
49
+
50
+ **令牌会自动续期**:快过期时 CLI 会先静默换新再发请求,你不会感觉到。只有 refresh token 也失效了才会让你重新登录。
51
+
52
+ ```bash
53
+ wd-cli auth status # 看当前身份、工作空间、令牌存在哪儿
54
+ wd-cli auth logout # 撤销令牌并清除本地凭据
55
+ ```
56
+
57
+ ## 选工作空间
58
+
59
+ 平台上你能看到什么,取决于「你是谁」加「当前在哪个工作空间」。登录后先选一个:
60
+
61
+ ```bash
62
+ wd-cli workspace list # 我属于哪些工作空间
63
+ wd-cli workspace use 42 # 选定(也可以写名称:wd-cli workspace use 数据组)
64
+ wd-cli workspace current # 当前是哪个
65
+ ```
66
+
67
+ 选定后会记在配置里,之后每条命令都带着它。想只影响这一次调用,加 `--workspace`:
68
+
69
+ ```bash
70
+ wd-cli skill list --workspace 43
71
+ ```
72
+
73
+ ## CI 与脚本:令牌直连
74
+
75
+ 流水线里没法开浏览器,用令牌:
76
+
77
+ ```bash
78
+ export WD_CLI_BASE_URL=https://agents.example.com
79
+ export WD_CLI_TOKEN=wat_xxxxxxxx # 工作空间访问令牌
80
+ wd-cli skill list --output json
81
+ ```
82
+
83
+ 两类令牌,能访问的东西不一样:
84
+
85
+ | 令牌 | 哪里拿 | 能访问 |
86
+ |------|--------|--------|
87
+ | 工作空间访问令牌(`wat_` 开头) | 平台「工作空间 → 访问令牌」 | 技能、知识库 |
88
+ | 应用访问密钥 | 平台 Agent 的「集成」页 | 对话、会话、凭证、评测、数据集、可观测、自动化 |
89
+
90
+ 令牌自带工作空间,不需要也不接受 `--workspace`。`WD_CLI_TOKEN` 存在时会压过登录态,这点与 `GH_TOKEN` 一致。
91
+
92
+ 命令跟当前令牌类型对不上时,CLI 会在发请求前就告诉你该换哪种令牌、去哪拿。确认服务端放开了某条路径而本地判断偏保守,可以加 `--no-principal-check` 交给服务端裁决。
93
+
94
+ ## 配置
95
+
96
+ 配置目录按 XDG 约定,默认 `~/.config/wd-cli`(Windows 是 `%AppData%\wd-cli`):
97
+
98
+ | 文件 | 内容 |
99
+ |------|------|
100
+ | `config.json` | 平台基址、认证中心、当前工作空间等。可以放进 dotfiles 仓库 |
101
+ | `hosts.json` | 令牌。权限 `0600`,不要提交 |
102
+
103
+ 能用系统密钥链时(macOS 钥匙串、Linux libsecret),令牌存进密钥链,`hosts.json` 里只留一个标记。`wd-cli auth status` 会告诉你当前存在哪儿。想强制用文件,设 `WD_CLI_INSECURE_STORAGE=1`。
104
+
105
+ ```bash
106
+ wd-cli config list # 所有 profile,当前项带 *
107
+ wd-cli config use prod # 切 profile
108
+ wd-cli config set baseUrl https://... # 改一项配置
109
+ wd-cli config path # 配置文件在哪
110
+ ```
111
+
112
+ 多套环境用 profile 隔开:
113
+
114
+ ```bash
115
+ wd-cli auth login --profile prod --base-url https://agents.example.com
116
+ wd-cli auth login --profile test --base-url https://test-agents.example.com
117
+ wd-cli skill list --profile test
118
+ ```
119
+
120
+ 取值优先级是**命令行参数 > 环境变量 > profile**。全部环境变量见 `wd-cli help environment`。
121
+
122
+ ## 输出与退出码
123
+
124
+ 终端里默认表格,管道里默认 JSON——直接 `| jq` 或重定向都不用加参数。
125
+
126
+ ```bash
127
+ wd-cli skill list # 表格
128
+ wd-cli skill list | jq '.[0]' # 自动变 JSON
129
+ wd-cli skill list --json id,name # 只要这几个字段
130
+ wd-cli skill list --jq '.[] | select(.skillType == "personal") | .name'
131
+ wd-cli skill download 123 --output raw
132
+ ```
133
+
134
+ `--jq` 是内置的 jq 子集(路径、`.[]`、`select`、比较、管道、字符串插值)。碰上它不支持的表达式会明说,让你改用 `--output json | jq`,而不是给一个看着对的错结果。
135
+
136
+ 数据永远走标准输出,提示和错误走标准错误。退出码:
137
+
138
+ | 码 | 含义 |
139
+ |----|------|
140
+ | 0 | 成功 |
141
+ | 1 | 业务失败(资源不存在、参数被拒等) |
142
+ | 2 | 用法错误(参数写错、缺凭据、没选工作空间) |
143
+ | 3 | 鉴权失败(自动刷新后仍失败) |
144
+ | 4 | 网络问题或超时 |
145
+
146
+ 完整说明:`wd-cli help exit-codes`。
147
+
148
+ ## 命令参考
149
+
150
+ ### skill 技能
151
+
152
+ ```bash
153
+ wd-cli skill list [--q 关键词]
154
+ wd-cli skill search --q python --scope personal --page 1 --page-size 20
155
+ wd-cli skill versions 123
156
+ wd-cli skill download 123 [--version 2] [-O ./skill.zip]
157
+ wd-cli skill import ./my-skill.zip --skill-type personal
158
+ wd-cli skill install @team/report-generator [--agents universal,claude-code] [--yes]
159
+ ```
160
+
161
+ `install` 的引用可以是技能 id、`@owner/name`,或平台上那条安装链接。装到哪儿跟 `skills-cli` 完全一致:
162
+
163
+ | `--agents` | 目录 |
164
+ |------------|------|
165
+ | `universal`(默认) | `~/.agents/skills/<name>` |
166
+ | `claude-code` | `~/.claude/skills/<name>` |
167
+ | `codex` | `~/.codex/skills/<name>` |
168
+ | `openclaw` | `~/.openclaw/skills/<name>` |
169
+ | `qoder` | `~/.qoder/skills/<name>` |
170
+ | `hermes-agent` | `~/.hermes/skills/<name>` |
171
+
172
+ 目标目录已有同名技能时,旧的先挪到同级 `.backup/` 再装新的(`--force` 直接覆盖)。解压依赖系统的 `unzip`。
173
+
174
+ ### kb 知识库
175
+
176
+ ```bash
177
+ wd-cli kb list
178
+ wd-cli kb get 12
179
+ wd-cli kb search 12 --query 报销流程 --top-k 5 [--catalog 3]
180
+ wd-cli kb tags 12
181
+
182
+ wd-cli kb doc list 12 [--page 1]
183
+ wd-cli kb doc get|content 12 99
184
+ wd-cli kb doc download 12 99 -O ./doc.pdf
185
+ wd-cli kb doc upload 12 ./a.pdf ./b.md [--catalog 3]
186
+ wd-cli kb doc delete 12 99 --yes
187
+ wd-cli kb doc reindex 12 99
188
+ wd-cli kb doc catalog-set|catalog-unset 12 99 --catalog 3
189
+
190
+ wd-cli kb catalog tree|create|rename|move|delete|contents 12 ...
191
+ wd-cli kb lark import|sources|sync 12 ...
192
+ wd-cli kb folder add|list|sync|policy|delete 12 ...
193
+ wd-cli kb acl list|grant|revoke|external 12 ...
194
+ wd-cli kb share create|list 12 99
195
+ ```
196
+
197
+ 批量上传时单个文件失败不会中断其余文件,最后按整体结果给退出码。
198
+
199
+ ### agent 应用与对话
200
+
201
+ ```bash
202
+ wd-cli agent list
203
+ wd-cli agent list --q 客服 --published
204
+ wd-cli agent list --type high-agent --paginate --json agentCode,name
205
+ ```
206
+
207
+ `agent list` 列出当前工作空间的应用,按更新时间倒序;可见范围与平台界面一致(工作空间成员能看到空间内全部应用)。`--published` 只留已发布的,也就是能拿去对话的;`--type` 直接用列表里「类型」列的值。输出里的 ID 就是后续命令要的 agentCode。登录态或工作空间令牌可用,应用访问密钥不行——它只代表单个应用。
208
+
209
+ ```bash
210
+ wd-cli agent info --agent-code 66
211
+ wd-cli agent metadata 66
212
+ wd-cli agent revision 66
213
+ wd-cli agent model 3 --agent-code 66
214
+
215
+ wd-cli agent chat 66
216
+ wd-cli agent chat 66 -m "你好"
217
+ wd-cli agent chat 66 -m "写一段介绍" --stream
218
+ wd-cli agent chat 66 -i --stream
219
+ cat prompt.txt | wd-cli agent chat 66 -m - --session-id s1
220
+ ```
221
+
222
+ 不带 `-m` 直接 `wd-cli agent chat 66` 会进入**连续对话**:同一个会话反复发问,上下文由服务端维持。已经用 `-m` 发了一句还想接着聊,就加 `-i`。
223
+
224
+ ```
225
+ $ wd-cli agent chat 66
226
+ 会话 id:3fbf7db2-…(下次加 --session-id 3fbf7db2-… 可接着聊)
227
+ 连续对话已开始,/help 看可用命令,/exit 或 Ctrl-D 退出。
228
+ > 你好
229
+ 你好!有什么可以帮你的吗?
230
+ > /exit
231
+ ```
232
+
233
+ 连续对话里可用 `/new`(换新会话,清空上下文)、`/session`(看当前会话 id)、`/help`、`/exit`(Ctrl-D 同效),Tab 可补全这些命令。提示符和提示信息都走标准错误,所以 `wd-cli agent chat 66 > out.txt` 只会把回复落进文件。标准输入不是终端时(脚本、管道)不进连续对话,缺 `-m` 直接报错,免得 CI 里挂住。
234
+
235
+ 不传 `--session-id` 会先建一个会话,把服务端生成的 id 打印出来,下次带上它就能接着聊。会话 id 由服务端分配——平台按落库的会话行校验,自己编一个 id 传过去会被判为不存在,所以指定的会话不存在时不会自动新建,而是提示你去掉 `--session-id`。
236
+
237
+ `--stream` 下文本增量即时打出来;加 `--output json` 则逐行输出原始事件,方便脚本处理。
238
+
239
+ ### session 会话
240
+
241
+ ```bash
242
+ wd-cli session list 66 [--user-id 7] [--paginate]
243
+ wd-cli session get|info 66 s-1
244
+ wd-cli session rename 66 s-1 --title 季度复盘
245
+ wd-cli session history 66 s-1
246
+ wd-cli session exists 66 s-1 # 存在退出 0,不存在退出 1
247
+ wd-cli session delete 66 s-1 --yes
248
+ wd-cli session drop 66 s-1 --yes
249
+ ```
250
+
251
+ ### credential 凭证
252
+
253
+ ```bash
254
+ wd-cli credential list --agent-code 66
255
+ wd-cli credential get feishu-bot --agent-code 66 # 明文默认隐藏
256
+ wd-cli credential get feishu-bot --agent-code 66 --reveal # 确实要明文
257
+ wd-cli credential authorize-url feishu-bot --agent-code 66
258
+ ```
259
+
260
+ 登录态下用 `--agent-code` 指明目标应用;用应用访问密钥时改用 `--session-id`。
261
+
262
+ ### eval / dataset 评测
263
+
264
+ ```bash
265
+ wd-cli eval plan list --agent-code 66
266
+ wd-cli eval plan items 8 --agent-code 66
267
+ wd-cli eval plan update 8 15 --data @item.json --agent-code 66
268
+ wd-cli eval execute --data @run.json --agent-code 66
269
+ wd-cli eval task list|create|get|items 66 ...
270
+
271
+ wd-cli dataset list|create|get|update|delete 66 ...
272
+ wd-cli dataset items 66 3
273
+ wd-cli dataset items add 66 3 --data @items.json
274
+ wd-cli dataset test-cases 66
275
+ ```
276
+
277
+ 所有 `--data` 都接受内联 JSON、`@文件`、或 `-`(标准输入),发出去之前先校验是合法 JSON。
278
+
279
+ ### trace / obs / score 可观测
280
+
281
+ ```bash
282
+ wd-cli trace list 66 --from 2026-09-01 --to 2026-09-12
283
+ wd-cli trace get 66 <traceId>
284
+ wd-cli obs spans|sessions|metrics|logs|summary 66
285
+ wd-cli score list 66
286
+ wd-cli score add 66 --data '{"traceId":"abc","name":"helpful","value":1}'
287
+ ```
288
+
289
+ ### automation / download-link
290
+
291
+ ```bash
292
+ wd-cli automation list --session-id s-1
293
+ wd-cli automation create --session-id s-1 --data @task.json
294
+ wd-cli download-link create --data '{"path":"/data/report.xlsx"}'
295
+ ```
296
+
297
+ ### completion 补全
298
+
299
+ ```bash
300
+ eval "$(wd-cli completion bash)" # bash,可写进 ~/.bashrc
301
+ wd-cli completion zsh > "${fpath[1]}/_wd-cli" # zsh
302
+ ```
303
+
304
+ ## api:通用逃生口
305
+
306
+ 平台上了新端点、或某个端点还没包成子命令时,直接打:
307
+
308
+ ```bash
309
+ wd-cli api /diwork/message-channels
310
+ wd-cli api /datasets/66 -f name=回归集 -F enabled=true -F size=100
311
+ wd-cli api /skills/import -F file=@my-skill.zip -f skillType=personal
312
+ wd-cli api /skills/search -X GET -f q=report --paginate --output json
313
+ wd-cli api /evaluate/execute --input @run.json
314
+ ```
315
+
316
+ 形态与 `gh api` 一致:`-f` 是字符串字段,`-F` 带类型推断且支持 `@文件`,`--input` 直接给请求体,`--paginate` 自动翻页。鉴权头和工作空间头照常带上。给了字段而没写 `-X` 时默认 POST,要放进 query 就显式 `-X GET`。
317
+
318
+ ## 常见问题
319
+
320
+ **提示「未登录,也未提供令牌」**
321
+ 执行 `wd-cli auth login`,或在 CI 里设 `WD_CLI_TOKEN`。
322
+
323
+ **提示「尚未选定工作空间」**
324
+ `wd-cli workspace list` 看一眼,再 `wd-cli workspace use <id>`。
325
+
326
+ **提示「此命令需要工作空间令牌」**
327
+ 用的是应用访问密钥,但这条命令要工作空间令牌。换令牌,或干脆用登录态(登录态对所有命令都有效)。
328
+
329
+ **登录时浏览器没打开**
330
+ 终端里已经把授权地址打出来了,手动复制到浏览器即可。也可以设 `BROWSER` 环境变量指定用哪个命令打开,或用 `--no-browser`。
331
+
332
+ **`unzip: command not found`**
333
+ `skill install` 需要系统的 unzip,先装上。
334
+
335
+ **对话命令报 404**
336
+ 平台把对话端点和其余开放接口拆在不同域名时,设一下:`wd-cli config set chatBaseUrl https://<对话域名>`。
337
+
338
+ **企业代理**
339
+ 当前不读 `HTTPS_PROXY`。需要经代理访问时,请在网络层解决。
340
+
341
+ ## 给编码 agent 用
342
+
343
+ 仓库里带了一份可直接加载的使用技能:[`docs/wd-cli/SKILL.md`](../../../docs/wd-cli/SKILL.md)(相对仓库根是 `docs/wd-cli/`)。装到本地技能目录后,Claude Code / Codex 这类 agent 就知道该怎么用这个工具——包括几条它自己想不到的约束:
344
+
345
+ - `auth login` 会开浏览器并阻塞,**agent 不能代跑**,得引导用户自己执行。
346
+ - 解析结果一律加 `--output json`;删除类命令必须带 `--yes`,否则在非交互环境直接失败。
347
+ - 按退出码分诊(2 是用法错误、3 才是真的没权限),而不是猜 stderr 文本。
348
+
349
+ ```bash
350
+ cp -r docs/wd-cli ~/.claude/skills/wd-cli # 或 ~/.agents/skills/wd-cli
351
+ ```
352
+
353
+ 装好后重开会话才会被识别。
354
+
355
+ ## 开发与发布
356
+
357
+ ```bash
358
+ npm run lint # 语法检查
359
+ npm test # 全量测试,离线跑,不碰真实服务
360
+ ```
361
+
362
+ 测试用进程内的 mock 平台与 mock 认证中心,跑的是真实入口进程,验的是退出码与标准输出 / 标准错误的实际分工。
363
+
364
+ 发布沿用 `skills-cli` 的流程:改 `package.json` 的 `version`,`npm publish` 到内部 registry。
365
+
366
+ 设计取舍与对标的项目(`gh`、`gcloud`、`kubectl`、AWS CLI、clig.dev)见 [`docs/design-references.md`](./docs/design-references.md)。
package/bin/wd-cli.js ADDED
@@ -0,0 +1,106 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ /**
5
+ * wd-cli 入口:只做「解析 → 找命令 → 建上下文 → 执行 → 翻译退出码」。
6
+ * 具体能力都在 lib/commands/* 里,帮助与补全都从命令表生成。
7
+ */
8
+
9
+ const { parseArgv, renderRootHelp, renderTopicHelp, renderCommandHelp } = require('../lib/args');
10
+ const { buildRegistry } = require('../lib/commands');
11
+ const config = require('../lib/config');
12
+ const { assertPrincipalAllowed } = require('../lib/auth');
13
+ const { Context } = require('../lib/http');
14
+ const output = require('../lib/output');
15
+ const { CliError, EXIT } = output;
16
+
17
+ function version() {
18
+ try {
19
+ return require('../package.json').version;
20
+ } catch {
21
+ return '0.0.0';
22
+ }
23
+ }
24
+
25
+ async function main(argv) {
26
+ const registry = buildRegistry();
27
+
28
+ if (argv.includes('--version') || argv.includes('-v')) {
29
+ process.stdout.write(`${version()}\n`);
30
+ return EXIT.OK;
31
+ }
32
+
33
+ const parsed = parseArgv(argv, registry);
34
+ const flags = parsed.flags;
35
+
36
+ if (!parsed.topic) {
37
+ process.stdout.write(`${renderRootHelp(registry)}\n`);
38
+ return EXIT.OK;
39
+ }
40
+
41
+ const topic = registry.topics[parsed.topic];
42
+ if (!topic) {
43
+ throw new CliError(`未知命令:${parsed.topic}`, EXIT.USAGE, { hint: '用 wd-cli --help 查看全部命令' });
44
+ }
45
+ if (parsed.wantsHelp && parsed.command === null) {
46
+ process.stdout.write(`${renderTopicHelp(topic)}\n`);
47
+ return EXIT.OK;
48
+ }
49
+
50
+ const commandName = parsed.command === null ? '' : parsed.command;
51
+ const command = topic.commands.find((c) => c.name === commandName);
52
+ if (!command) {
53
+ if (!commandName) {
54
+ process.stdout.write(`${renderTopicHelp(topic)}\n`);
55
+ return EXIT.OK;
56
+ }
57
+ throw new CliError(`未知动作:${parsed.topic} ${commandName}`, EXIT.USAGE, {
58
+ hint: `用 wd-cli ${topic.id} --help 查看可用动作`,
59
+ });
60
+ }
61
+ if (parsed.wantsHelp) {
62
+ process.stdout.write(`${renderCommandHelp(topic, command)}\n`);
63
+ return EXIT.OK;
64
+ }
65
+
66
+ // 位置参数必填校验
67
+ const argDefs = command.args || [];
68
+ for (let i = 0; i < argDefs.length; i += 1) {
69
+ if (argDefs[i].required && parsed.args[i] === undefined) {
70
+ throw new CliError(`缺少参数 <${argDefs[i].name}>`, EXIT.USAGE, {
71
+ hint: `用法见 wd-cli ${topic.id}${command.name ? ` ${command.name}` : ''} --help`,
72
+ });
73
+ }
74
+ }
75
+
76
+ const runtime = config.resolveRuntime(flags, process.env);
77
+ const principal = config.principalOf(runtime);
78
+ if (!command.skipPrincipalCheck) {
79
+ assertPrincipalAllowed(runtime, principal, topic, command, flags);
80
+ }
81
+
82
+ const ctx = new Context({ runtime, principal, flags, env: process.env });
83
+ ctx.args = parsed.args;
84
+ ctx.registry = registry;
85
+ ctx.topic = topic;
86
+ ctx.command = command;
87
+
88
+ const result = await command.run(ctx);
89
+ return typeof result === 'number' ? result : EXIT.OK;
90
+ }
91
+
92
+ main(process.argv.slice(2))
93
+ .then((code) => {
94
+ process.exitCode = code;
95
+ })
96
+ .catch((error) => {
97
+ const flags = (() => {
98
+ try {
99
+ return parseArgv(process.argv.slice(2), buildRegistry()).flags;
100
+ } catch {
101
+ return {};
102
+ }
103
+ })();
104
+ output.printError(error, flags);
105
+ process.exitCode = error && error.exitCode ? error.exitCode : EXIT.BUSINESS;
106
+ });
@@ -0,0 +1,75 @@
1
+ # wd-cli 对标参考(实现基准)
2
+
3
+ 本工具的命令形态、参数命名、输出与错误约定,一律对标下列公认项目,不自创约定。本文件记录「借鉴点 → 本工程对应模块」,实现与评审时按此对照;遇到本文未覆盖的细节,先看这些项目怎么做,再决定。
4
+
5
+ ## 1. GitHub CLI(`gh`)
6
+
7
+ 仓库:https://github.com/cli/cli
8
+
9
+ | 借鉴点 | `gh` 中的位置 | 本工程对应 |
10
+ |--------|---------------|-----------|
11
+ | `auth login / status / logout` 命令族与文案(`✓ Logged in as X`、状态按 host 分组列出) | `pkg/cmd/auth/**` | `lib/commands/auth.js` |
12
+ | 通用逃生口:`-X` 方法、`-f` 字符串字段、`-F` 带类型推断字段、`--input` 请求体、`-H` 头、`--paginate` | `pkg/cmd/api/api.go` | `lib/commands/api.js` |
13
+ | `--json <fields>` 选字段 + `--jq <expr>` 过滤,非 TTY 自动机器可读 | `pkg/cmdutil/json_flags.go` | `lib/output.js`、`lib/jq.js` |
14
+ | 令牌优先存 OS 密钥链,不可用时回落配置文件 | `internal/keyring` | `lib/keyring.js`(P2),回落 `hosts.json` |
15
+ | 环境变量令牌覆盖登录态(`GH_TOKEN`) | `internal/config` | `WD_CLI_TOKEN`,语义完全一致 |
16
+ | 配置与凭据分文件(`config.yml` / `hosts.yml`) | `internal/config` | `config.json` / `hosts.json` |
17
+ | help 排版:Usage / Commands / Flags / Examples / Learn more | `pkg/cmd/root/help.go` | `lib/args.js` 的 help 生成器 |
18
+ | `gh help environment`、`gh help exit-codes` 这类「非命令的文档主题」 | `pkg/cmd/root/help_topic.go` | `wd-cli help environment` / `help exit-codes` |
19
+
20
+ **刻意不照搬**:`--template`(Go template)不做,复杂格式化建议管道给系统 `jq`。
21
+
22
+ ## 2. Google Cloud SDK(`gcloud`)
23
+
24
+ | 借鉴点 | 本工程对应 |
25
+ |--------|-----------|
26
+ | `auth login` 走授权码 + PKCE,本机起回环 HTTP 服务收回调,端口由系统分配 | `lib/oidc.js` 的 `startLoopbackServer` + `buildAuthorizeUrl` |
27
+ | `--no-launch-browser`:打印授权 URL,用户在别处登录后把回调地址贴回终端 | `auth login --no-browser` |
28
+ | 令牌临近过期静默刷新,用户无感 | `lib/http.js` 的 `ensureFreshToken` |
29
+ | 多套配置(configurations)与切换 | profile + `config use` |
30
+
31
+ ## 3. kubectl
32
+
33
+ | 借鉴点 | 本工程对应 |
34
+ |--------|-----------|
35
+ | `config use-context` / `current-context` 的「当前上下文」模型 | `workspace use` / `workspace current` |
36
+ | `--namespace` 单次覆盖当前上下文而不改配置 | `--workspace` 单次覆盖 |
37
+ | `-o json\|yaml\|wide\|name` | `--output table\|json\|raw`(`-o`) |
38
+
39
+ ## 4. AWS CLI
40
+
41
+ | 借鉴点 | 本工程对应 |
42
+ |--------|-----------|
43
+ | 命名 profile(`--profile` / `AWS_PROFILE`) | `--profile` / `WD_CLI_PROFILE` |
44
+ | 凭据解析链:命令行 > 环境变量 > 配置文件 | `lib/config.js` 的 `resolveRuntime` |
45
+ | `--query`(JMESPath)做结果投影 | 以 `--jq` 实现(更贴近 `gh` 的用户群) |
46
+
47
+ ## 5. Stripe CLI / Vercel CLI
48
+
49
+ | 借鉴点 | 本工程对应 |
50
+ |--------|-----------|
51
+ | 浏览器登录后本地回调页给一句「可以关掉这个页面了」 | `lib/oidc.js` 的成功页 |
52
+ | `-y` / `--yes` 跳过确认 | 全局 `--yes` |
53
+ | 非 TTY 自动降级为机器可读输出、不打颜色 | `lib/output.js` 的 TTY 检测 |
54
+
55
+ ## 6. Command Line Interface Guidelines(clig.dev)
56
+
57
+ - 标准输出只放数据,提示 / 进度 / 错误一律走标准错误——管道里只会拿到数据。
58
+ - 错误信息要给下一步动作,例如「未登录,请先执行 `wd-cli auth login`」而不是「401」。
59
+ - `--help` 处处可用;破坏性操作在交互终端二次确认,`--yes` 跳过。
60
+ - 尊重 `NO_COLOR`、`TERM=dumb`,以及「输出不是终端」这三种情形。
61
+ - 参数一律 `--kebab-case`,短写只给高频项(`-o` / `-q` / `-y` / `-f` / `-F` / `-H` / `-X`)。
62
+
63
+ ## 7. 12 Factor CLI Apps
64
+
65
+ - 配置遵循 XDG:`$XDG_CONFIG_HOME/wd-cli/`,缺省 `~/.config/wd-cli/`。
66
+ - 敏感数据(令牌)与普通配置分文件,前者 `0600`。
67
+ - 启动要快:零运行时依赖,`npx` 冷启动无需装依赖树。
68
+
69
+ ## 8. 不照搬的地方与原因
70
+
71
+ | 项目做法 | 本工程选择 | 原因 |
72
+ |----------|-----------|------|
73
+ | `gh` 用 Go + cobra,oclif 用 TypeScript 框架 | Node + 零依赖手写命令表 | 与同目录 `skills-cli` 一致;`npx` 启动最快;无供应链审计负担。命令声明形态仍对齐 oclif(`{ id, summary, args, flags, examples, run }`),日后要迁移框架成本低 |
74
+ | `gh` 的 `--jq` 用完整 gojq | 手写 jq 子集(路径、`.[]`、`select`、`\|`、字符串插值) | 零依赖约束;不支持的表达式明确报错并建议管道给系统 `jq`,而不是悄悄给错结果 |
75
+ | `gcloud` 支持设备码授权 | 只做回环回调 + `--no-browser` 回贴 | 平台认证中心当前没有 device code 授权类型 |