@guandata/decidex 0.1.2 → 0.3.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,10 +1,14 @@
1
1
  # Decidex CLI
2
2
 
3
- 基于 Decidex 当前 HTTP API 的零依赖 Node.js CLI。要求 Node.js 22+。
3
+ 基于 Decidex **0.0.6** HTTP API 的零依赖 Node.js CLI(CLI 版本 0.3.0)。要求 Node.js 22+。
4
+
5
+ 适配基线:[tag 0.0.6 / 73901fa03](https://gitlab.mayidata.com/zijie0/decidex/-/tree/0.0.6),2026-11-06。按实际部署的 release 契约执行,保留 0.0.5 调度兼容。
4
6
 
5
7
  ```bash
6
- npm link
7
- decidex version --json
8
+ npm install -g @guandata/decidex@0.3.0
9
+ decidex version --json # 本地 CLI 版本
10
+ decidex server version # 目标服务端版本与 commit
11
+ decidex server check auth whoami
8
12
  decidex auth login --base-url https://decidex.example.com
9
13
  decidex auth status
10
14
  decidex context show
@@ -18,6 +22,40 @@ decidex context show
18
22
  pbpaste | decidex auth import --base-url https://decidex.example.com
19
23
  ```
20
24
 
25
+ ## 版本检查与兼容规则
26
+
27
+ ```bash
28
+ decidex server version --json
29
+ decidex version --server --json # 同上
30
+ decidex server check # 列出已声明的兼容规则
31
+ decidex server check auth whoami # 检查指定命令,低于最低版本时退出码为 1
32
+ decidex auth whoami # 服务端 >= 0.0.5,返回已验证的用户/组织身份
33
+ ```
34
+
35
+ 版本来自已登录目标的 `GET /api/app-version`,每次 CLI 进程重新读取,不持久缓存。`version` 查询即使遇到 `dev` 等版本也会显示原值和 `comparable=false`;需要版本决策的命令遇到无法比较的版本、认证失败或版本查询失败会明确报错,不猜测版本或在写入失败后重试另一种协议。
36
+
37
+ `server check` 对没有版本规则的命令返回 `supported=null`、`reason=no_version_rule`,表示尚未声明版本边界,不能据此断言目标支持。`0.0.6` 是本次适配基线,不是所有命令的首次发布版本。SemVer 比较支持 `v` 前缀、预发布和构建信息;例如 `0.0.8-rc.1` 低于正式 `0.0.8`。
38
+
39
+ 已核实的版本差异:
40
+
41
+ | 命令 | 目标 < 0.0.5 | 目标 >= 0.0.5 |
42
+ | --- | --- | --- |
43
+ | `auth whoami` | 提示最低版本,停止执行 | `/api/auth/context` |
44
+ | `auth status` / `auth login` 的登录验证 | 原有 Agent 列表验证,`legacy=true`,用户/组织身份未验证 | `/api/auth/context`,返回已验证身份 |
45
+ | `context show` | 本地上下文,`organizationIdVerified=false` | 读取服务端身份;可在没有活动组织时使用 |
46
+
47
+ 常用命令的兼容规则在 `src/compatibility.js`,操作目录的路由版本在 `src/api-catalog.json`。后续添加命令时,可依据实际 release tag 声明:
48
+
49
+ ```js
50
+ "example create": { minVersion: "0.0.8" },
51
+ "example get": {
52
+ protocol: "v2",
53
+ legacy: { before: "0.0.8", protocol: "v1" },
54
+ },
55
+ ```
56
+
57
+ 声明规则后,主入口会在命令分发前自动检查最低版本。需要 legacy 协议时,命令处理函数再调用 `commandCompatibility(command, values)`,根据返回的 `protocol` 选择相应请求实现(同一进程复用版本查询)。`auth login` 在获得登录态后执行版本选择。新增协议需同时补边界版本测试。上面 `example` 仅演示规则,未对现有命令附加虚构的 0.0.8 限制。
58
+
21
59
  ## Agent
22
60
 
23
61
  创建 `agent.json`:
@@ -32,13 +70,16 @@ pbpaste | decidex auth import --base-url https://decidex.example.com
32
70
  }
33
71
  ```
34
72
 
35
- 创建后,把响应里的 `agent.id` 写回文件顶层即可执行更新:
73
+ 创建后,把响应里的 `agent.id` 写回文件顶层即可执行更新。`apply` 使用服务端 PUT 契约:保留完整配置文件,尤其是 `name`、`description`、`instructions`;更新时省略后两项会被服务端置空。CLI 拒绝未知顶层字段,防止拼写错误被服务端静默忽略:
36
74
 
37
75
  ```bash
38
76
  decidex agent apply agent.json
39
77
  decidex agent export AGENT_ID agent.zip
40
78
  decidex agent import agent.zip
41
79
  decidex agent publish AGENT_ID --email user@example.com
80
+ decidex agent publications AGENT_ID
81
+ decidex agent use-scope AGENT_ID OWNER # 或 SPECIFIC_USERS / ORGANIZATION
82
+ decidex agent delete AGENT_ID
42
83
  ```
43
84
 
44
85
  `agent.json` 也可以直接声明本体、BI 资产、Skill、默认模型和推理强度:
@@ -55,17 +96,31 @@ decidex agent publish AGENT_ID --email user@example.com
55
96
  }
56
97
  ```
57
98
 
99
+ 每个 Agent 最多绑定一个业务本体;`versionId` 可以使用固定版本 ID 或 `latest`。`contextReferences` 的 BI 资产需要保留来源环境(`guandataEnvRef` 或有效的 `guandataBaseUrl`);也可按服务端契约传钉钉/飞书文档引用。`builtInInstructions` 仅支持更新已有 Agent。
100
+
58
101
  上传参考文件和执行冒烟问题:
59
102
 
60
103
  ```bash
61
104
  decidex agent file add AGENT_ID references/*.md
62
105
  decidex agent file list AGENT_ID
63
106
  decidex agent models AGENT_ID
107
+ decidex agent run AGENT_ID --message "分析销售" --model-entry-id MODEL_ENTRY_ID --reasoning-effort high --attach sales.csv --wait
64
108
  decidex agent run AGENT_ID --message "分析本月销售异常" --wait
65
109
  decidex agent run AGENT_ID --input smoke.md --wait --follow --output smoke-result.json
66
110
  printf '%s' '分析本月销售异常' | decidex agent run AGENT_ID --input - --wait
67
111
  ```
68
112
 
113
+ `--attach FILE` 可重复传入,也可仅发送附件。`--context-references FILE` 和 `--conversation-references FILE` 分别接收服务端定义的引用数组 JSON。`--reasoning-effort null` 表示使用模型默认值;具体模型支持的推理档位以 `agent models` 返回的目录为准,CLI 不推断所有模型都支持所有档位。
114
+
115
+ 绑定知识库中已有文档(不等同于 Agent 参考文件上传):
116
+
117
+ ```bash
118
+ decidex agent knowledge list AGENT_ID --query 销售
119
+ decidex agent knowledge list AGENT_ID --cursor NEXT_CURSOR
120
+ decidex agent knowledge add AGENT_ID DOCUMENT_ID
121
+ decidex agent knowledge remove AGENT_ID DOCUMENT_ID
122
+ ```
123
+
69
124
  `--follow` 只把状态和工作轨迹写入 stderr;最终 JSON 仍可稳定写入文件:
70
125
 
71
126
  ```json
@@ -92,28 +147,61 @@ decidex session list --status running
92
147
  decidex session view SESSION_ID
93
148
  decidex session send SESSION_ID --message "继续拆解渠道" --wait --follow
94
149
  decidex session stop SESSION_ID
150
+ decidex session rename SESSION_ID "渠道分析"
151
+ decidex session model SESSION_ID MODEL_ENTRY_ID
152
+ decidex session fork SESSION_ID RUN_ID
153
+ decidex session delete SESSION_ID
95
154
  decidex session artifacts list SESSION_ID
96
155
  decidex session artifacts download SESSION_ID --all --dir ./artifacts
97
- decidex session evidence list SESSION_ID
98
- decidex session evidence download SESSION_ID --all --dir ./evidence
156
+ decidex session files list SESSION_ID --scope analysis
157
+ decidex session files download SESSION_ID --scope analysis --suffix .boe --all --dir ./evidence
99
158
  decidex run diagnose RUN_ID --session-id SESSION_ID --json
100
159
  ```
101
160
 
161
+ `session rename` 的标题不能为空,最多 24 个字符。
162
+
163
+ 会话列表按页返回;`--cursor` 接收 `nextCursor` 原值,`--agent-id` 查询指定 Agent 的历史页。`--status` 只过滤当前页,`completed` 表示非 RUNNING(含 ERROR),空页仍可能有下一页。`--query` 不可与 `--cursor` / `--agent-id` 同用。`session view --before OLDER_CURSOR` 读取更早消息,`--since LIVE_CURSOR` 读取增量;两者互斥。
164
+
165
+ `session send` 同样支持附件、引用数组和推理档位。切换模型需先执行 `session model`,不能把模型参数混入续问接口。
166
+
167
+ ```bash
168
+ decidex session queue list SESSION_ID
169
+ decidex session queue edit SESSION_ID DRAFT_ID --message "修改后的问题"
170
+ decidex session queue delete SESSION_ID DRAFT_ID
171
+ decidex session queue continue SESSION_ID --wait --follow
172
+ ```
173
+
174
+ `queue continue` 启动队首消息,可等待该 Run;不会等待整个队列清空。
175
+
102
176
  `session send --wait` 要求消息立即启动;会话正忙时服务端会在入队前返回冲突,避免 CLI 假失败后重试造成重复入队。不带 `--wait` 时结果可能是 `kind=direct` 或 `kind=queued`。
103
177
 
104
- `session evidence` 通过服务端会话文件索引发现实际 `.boe` 文件;证据文件位于 `workspace/analysis/biz-ontology-evidence/`,不会混入普通产物列表。下载默认拒绝覆盖已有文件,也拒绝通过符号链接写出目标目录;确认覆盖普通文件时加 `--overwrite`。`run diagnose` 未显式传 `--session-id` 时会使用最近 50 条本地 Run 映射;若本地配置不可写,远端 Run 仍会继续,CLI 会先输出 Session/Run ID,之后可用显式 ID 恢复诊断。当前后端未向用户 API 暴露 Runner 的 Pod termination reason 和资源指标,结果会将这两项标记为 `not_exposed`。
178
+ `session files --scope analysis` 列出 `workspace/analysis/` 下的全部分析文件,包含 `.boe`;`--suffix` 按文件后缀过滤且不区分大小写。下载默认拒绝覆盖已有文件,也拒绝通过符号链接写出目标目录;确认覆盖普通文件时加 `--overwrite`。`run diagnose` 未显式传 `--session-id` 时会使用最近 50 条本地 Run 映射;若本地配置不可写,远端 Run 仍会继续,CLI 会先输出 Session/Run ID,之后可用显式 ID 恢复诊断。当前后端未向用户 API 暴露 Runner 的 Pod termination reason 和资源指标,结果会将这两项标记为 `not_exposed`。
105
179
 
106
180
  ## Skill
107
181
 
108
182
  ```bash
109
- decidex skill list
183
+ decidex skill list --origin all # 默认 personal;可选 builtin
184
+ decidex skill references SKILL_ID
110
185
  decidex skill upload skill.zip
111
186
  decidex skill update SKILL_ID skill.zip
112
187
  decidex skill download SKILL_ID skill.zip
113
188
  decidex skill delete SKILL_ID
114
189
  ```
115
190
 
116
- `skill update` 会先读取线上 fingerprint,再执行乐观锁更新,避免覆盖并发修改。
191
+ `skill update` 默认先读取线上 fingerprint,再进行整包更新,检测读取后的并发修改。已有快照时可显式传 `--fingerprint SHA256`,防止覆盖快照之后的修改。
192
+
193
+ 逐文件编辑必须使用读取时的 fingerprint;`files get` 的结果还包含 `truncated`、`editable`,截断或不可编辑的文件应改用下载整包等方式处理:
194
+
195
+ ```bash
196
+ decidex skill files list SKILL_ID
197
+ decidex skill files get SKILL_ID SKILL.md
198
+ decidex skill files put SKILL_ID SKILL.md ./SKILL.md --fingerprint sha256:...
199
+ decidex skill credentials status SKILL_ID
200
+ pbpaste | decidex skill credentials set SKILL_ID API_KEY
201
+ decidex skill credentials delete SKILL_ID API_KEY
202
+ ```
203
+
204
+ 凭证值只通过 stdin 传入,CLI 不在输出中回显;状态接口只返回声明和已配置的变量名。写操作、整包下载和凭证操作针对 personal Skill;builtin 支持列表和文件读取。
117
205
 
118
206
  ## Evaluation
119
207
 
@@ -124,7 +212,10 @@ decidex skill delete SKILL_ID
124
212
  "cases": [
125
213
  {
126
214
  "task": "本月销售下滑来自流量、转化率还是客单价?",
127
- "rubric": "必须给出时间范围、指标证据和拆解过程;证据不足时降低结论强度。"
215
+ "criteria": [
216
+ { "text": "给出时间范围与指标证据。", "weight": 2, "veto": true },
217
+ { "text": "说明拆解过程;证据不足时降低结论强度。", "weight": 1, "veto": false }
218
+ ]
128
219
  }
129
220
  ]
130
221
  }
@@ -141,7 +232,16 @@ decidex eval cases plan AGENT_ID cases.json --prune
141
232
  decidex eval cases apply AGENT_ID cases.json --prune
142
233
  ```
143
234
 
144
- 同步以 `task` 为稳定键;本地或线上存在重复 task 时会停止。`apply` 先新增和更新,最后才执行 `--prune` 删除。当前后端没有案例版本号或幂等键:同一个 Agent 的评测案例只能由一个写入者同步,禁止并发执行 `apply`/`--prune`。
235
+ 旧版 `rubric` 输入已过期,需显式改成 `criteria`。每个案例 1–50 条评分项,`text` 最多 2000 字符,`weight` 默认为 1 且必须为正整数,`veto` 默认为 false。可选 `tagIds`:省略时保留已有标签,传 `[]` 清空;标签 ID 必须属于当前 Agent。
236
+
237
+ ```bash
238
+ decidex eval tags list AGENT_ID
239
+ decidex eval tags create AGENT_ID 冒烟
240
+ decidex eval tags rename AGENT_ID TAG_ID 回归
241
+ decidex eval tags delete AGENT_ID TAG_ID
242
+ ```
243
+
244
+ 同步以 `task` 原文为稳定键;本地或线上存在重复 task 时会停止。`apply` 先新增和更新,最后才执行 `--prune` 删除。评分文本不变时保留现有条目 ID;导出文件省略评分条目 ID,便于新建案例。跨 Agent 迁移时需自行映射或移除 `tagIds`。当前后端没有案例版本号或幂等键:同一个 Agent 的评测案例只能由一个写入者同步,禁止并发执行 `apply`/`--prune`。
145
245
 
146
246
  评测运行文件复用服务端契约:
147
247
 
@@ -158,7 +258,7 @@ decidex eval run AGENT_ID eval-run.json --cases all --wait --output eval-result.
158
258
  decidex eval stop AGENT_ID RUN_ID
159
259
  ```
160
260
 
161
- CLI 按最新 `origin/main` 校验该文件:只接受 `caseIds`、`targetModelSelection` 和 `judgeModelSelection`。使用 `--cases all` 时由 CLI 获取并覆盖 `caseIds`;Agent 没有评测案例时会在本地停止。
261
+ CLI 按服务端 `0.0.5` / `0.0.6` tag 的共同契约校验该文件:只接受 `caseIds`、`targetModelSelection` 和 `judgeModelSelection`。使用 `--cases all` 时由 CLI 获取并覆盖 `caseIds`;Agent 没有评测案例时会在本地停止。
162
262
 
163
263
  查询、接管或批量监控已经启动的评测:
164
264
 
@@ -167,7 +267,7 @@ decidex eval runs list AGENT_ID
167
267
  decidex eval runs get AGENT_ID RUN_ID
168
268
  decidex eval runs wait AGENT_ID RUN_ID --follow --output result.json
169
269
  decidex eval runs watch evaluation-runs.json --parallel 3 --follow --output summary.json
170
- decidex eval evidence download AGENT_ID RUN_ID --all --dir ./evidence
270
+ decidex eval files download AGENT_ID RUN_ID --scope analysis --suffix .boe --all --dir ./evidence
171
271
  ```
172
272
 
173
273
  `evaluation-runs.json`:
@@ -183,7 +283,116 @@ decidex eval evidence download AGENT_ID RUN_ID --all --dir ./evidence
183
283
 
184
284
  `watch` 只在状态或计数变化时向 stderr 输出进度,最终 JSON 保留每个 Run 的完整 Case 结果;任一 Run 失败、停止或监控出错时退出码为 1。
185
285
 
186
- `eval evidence download` 按 Case 分目录下载评测会话中的 `.boe`。该命令要求服务端评测详情返回 `targetSessionId`;旧版服务端会给出明确升级提示。
286
+ `eval files download` 按 Case 分目录下载评测会话文件;用 `--scope analysis --suffix .boe` 可只下载证据链。该命令要求服务端评测详情返回 `targetSessionId`;旧版服务端会给出明确升级提示。
287
+
288
+ ## 定时任务
289
+
290
+ 创建文件 `automation.json`:
291
+
292
+ ```json
293
+ {
294
+ "personalAgentId": "AGENT_ID",
295
+ "name": "每周销售分析",
296
+ "instructions": "分析上周销售并给出证据。",
297
+ "schedule": { "kind": "WEEKLY", "weekday": 1, "timeOfDayMinutes": 600 }
298
+ }
299
+ ```
300
+
301
+ ```bash
302
+ decidex automation list
303
+ decidex automation apply automation.json
304
+ decidex automation run AUTOMATION_ID --wait --follow --output result.json
305
+ decidex automation runs AUTOMATION_ID --cursor NEXT_CURSOR
306
+ decidex automation delete AUTOMATION_ID
307
+ ```
308
+
309
+ 文件包含 `id` 时用 PATCH 更新;可只传 `{ "id": "...", "status": "PAUSED" }` 暂停,改为 `ACTIVE` 恢复。暂停状态不能手动运行;单次调度完成后由服务端写入 `FINISHED`,不能手动设置、恢复或再次运行。
310
+
311
+ 服务端 >= 0.0.6 支持以下调度:
312
+
313
+ | schedule 示例 | 含义 |
314
+ | --- | --- |
315
+ | `{ "kind": "DAILY", "timeOfDayMinutes": 600 }` | 每天 10:00 |
316
+ | `{ "kind": "WEEKLY", "weekdays": [3, 5], "timeOfDayMinutes": 600 }` | 每周三、五 10:00,周日为 0 |
317
+ | `{ "kind": "MONTHLY", "monthDays": [1, 15], "timeOfDayMinutes": 600 }` | 每月 1 日、15 日 10:00;短月不存在的日期跳过 |
318
+ | `{ "kind": "INTERVAL", "intervalMinutes": 60 }` | 每隔 60 分钟,范围 5..2147483647 分钟 |
319
+ | `{ "kind": "ONCE", "runOnceAt": "2099-01-01T10:00:00+08:00" }` | 固定时间执行一次,保存时必须晚于当前时间 |
320
+
321
+ `timeOfDayMinutes` 范围 0..1439,缺省 540(09:00);周期调度按服务端时区执行。ONCE 建议显式填写时区。
322
+
323
+ CLI 根据目标版本选择协议:0.0.6 的旧 `weekday` 转为 `weekdays`,旧 `HOURLY` 转为 `INTERVAL(60)`;目标 0.0.5 保留原协议,单元素 `weekdays` 可转换为 `weekday`,多元素及新调度模式在写入前拒绝。`server check automation apply` 查看所选协议。
324
+
325
+ 文件还可按服务端契约配置 `imPush`、`emailPush`;更新时省略保留原配置,`null` 清空。手动 `run --wait` 等待分析 Run,不代表通知已送达;送达结果查看 `automation runs`。服务端 0.0.5 的启动接口会同步等待执行结果,`--wait --timeout` 覆盖该请求及后续读取的总时间。客户端超时不会取消服务端执行;应先查 `automation runs`,不要直接重试触发。
326
+
327
+ ## 任务中心
328
+
329
+ ### 行动任务
330
+
331
+ Agent 配置中设置 `actionSuggestionsEnabled: true`,运行产生行动建议后再创建任务:
332
+
333
+ ```bash
334
+ decidex action-task suggestions SESSION_ID --run-id RUN_ID
335
+ decidex action-task members SESSION_ID --query 张
336
+ decidex session view SESSION_ID # 读取回答的消息 ID
337
+ decidex action-task create SESSION_ID action-task.json
338
+ decidex action-task list --status PENDING
339
+ decidex action-task get TASK_ID
340
+ decidex action-task adopt TASK_ID --version 0
341
+ decidex action-task complete TASK_ID --version 1
342
+ ```
343
+
344
+ `action-task.json` 使用回答消息 ID、建议 ID 和分配信息:
345
+
346
+ ```json
347
+ {
348
+ "messageId": "ASSISTANT_MESSAGE_ID",
349
+ "suggestionId": "SUGGESTION_ID",
350
+ "draft": { "title": "核查异常", "description": "核实异常原因并记录结果", "assigneeIds": ["USER_ID"] }
351
+ }
352
+ ```
353
+
354
+ `--run-id` 从当前会话窗口查找回答;较早的回答用 `session view --before CURSOR` 找到消息后传 `--message-id`。采纳后可完成或取消,待处理时可拒绝。`reject`、`cancel` 必须传 `--note 理由`。每次操作使用 `get` 返回的当前 `task.version`;409 表示任务已变化,应重新确认,不自动重试。平台没有行动任务删除接口。
355
+
356
+ ### 指标追踪
357
+
358
+ 追踪任务从会话内已有的候选与 BOE 证据链创建;这里的路径是远端会话路径:
359
+
360
+ ```bash
361
+ decidex tracking preview SESSION_ID --candidate-path workspace/analysis/decision-tracking/turn.json --boe-path workspace/analysis/biz-ontology-evidence/turn.boe
362
+ decidex tracking create SESSION_ID --candidate-path workspace/analysis/decision-tracking/turn.json --boe-path workspace/analysis/biz-ontology-evidence/turn.boe --wait
363
+ decidex tracking list --filter due
364
+ decidex tracking get TASK_ID
365
+ decidex tracking review TASK_ID --wait
366
+ decidex tracking report TASK_ID report.html
367
+ ```
368
+
369
+ `create` 使用服务端校验后的候选和 `evidenceVersion`,证据变化时保留 409。相同来源重复创建返回原任务;`lookup` 可按会话和两个路径查找。初始报告异步生成,用 `wait TASK_ID` 继续等待;失败后可显式 `retry TASK_ID --wait`;已有初始报告时返回原结果,不重复启动。
370
+
371
+ 支持 `rename TASK_ID 标题`、`pause/resume/close/delete TASK_ID`、`reviews TASK_ID --cursor CURSOR`。`schedule TASK_ID schedule.json` 接收 `{ "reviewFrequency": "WEEKLY", "nextReviewAt": "2026-11-12T01:00:00.000Z" }`,频率也可为 `MONTHLY`、`QUARTERLY`。初始报告完成后才能暂停、恢复、结束或复核。
372
+
373
+ `review --data FILE` 可指定 `{ "requestedReviewWindow": { "startDate": "2026-10-01", "endDate": "2026-10-31", "grain": "month" } }`。`--wait` 等待报告或明确失败,不把已入队的复核占位记录当作完成。成功生成报告时退出码为 0,`DATA_NOT_READY` 等业务结果及原因保留原值;后台生成失败且无报告时退出码为 1。`report --initial` 下载初始报告,`--review-id ID` 下载指定复核报告。
374
+
375
+ `--timeout` 覆盖请求和等待的总时间,默认 600 秒。客户端超时不会取消后台任务;先用 `get` / `reviews` 查状态,避免重复发起复核。
376
+
377
+ ## 平台操作目录
378
+
379
+ 除常用专用命令外,`platform` 按真实路由注册操作,覆盖知识库、权限与成员、记忆、连接器、消息渠道、运营统计及平台管理等 API:
380
+
381
+ ```bash
382
+ decidex platform list --query knowledge-library
383
+ decidex platform show knowledge-library.folders.documents.create
384
+ decidex platform call knowledge-library.folders.list
385
+ decidex platform call knowledge-library.folders.documents.create --folder-id FOLDER_ID --file files=./reference.pdf
386
+ decidex platform call knowledge-library.documents.original.list --document-id DOCUMENT_ID --output original.pdf
387
+ decidex platform call action-tasks.list --query-param status=all --query-param q=异常
388
+ decidex platform coverage
389
+ ```
390
+
391
+ `show` 显示方法、路径、必填路径参数和最低版本。调用支持 `--data JSON文件`、可重复的 `--query-param KEY=VALUE`、`--file FIELD=FILE` / `--field KEY=VALUE`;原始二进制用 `--body-file FILE`,下载用 `--output FILE`。`--dry-run` 只检查和展示请求,不联网。
392
+
393
+ 版本边界来自 release tag 中的路由存在性,**不等于该版本所有业务字段均兼容**;字段与权限仍以服务端契约为准。仅在 main 存在的操作默认拒绝,确认目标已部署后才能显式 `--allow-unreleased`,不猜测未来版本号。`inputHints` 是路由文件线索,不是完整请求 schema。
394
+
395
+ 当前目录覆盖 444/444 个纳入范围的操作,全部存在于 0.0.6 tag。全部 549 个路由操作中另有 105 个运行时、服务令牌、公开分享、回调、流式或代理协议,未纳入浏览器登录态 CLI;按全部路由计为 80.9%。这表示操作入口覆盖,不是逐接口业务验证或真实冒烟覆盖。详见 [覆盖审计](docs/api-coverage.md)。
187
396
 
188
397
  ## 组织
189
398
 
@@ -198,6 +407,9 @@ Galaxy 模式的组织由 BI 租户登录态决定,服务端会拒绝手动切
198
407
  本体构建复用 Decidex 的完整导出/导入契约,避免 CLI 重复维护对象、属性、关系、行动、风险等子资源 schema:
199
408
 
200
409
  ```bash
410
+ decidex ontology versions list ONTOLOGY_ID
411
+ decidex ontology versions get ONTOLOGY_ID VERSION_ID
412
+ decidex ontology versions create ONTOLOGY_ID --description "调整前快照"
201
413
  decidex ontology export ONTOLOGY_ID ontology.json
202
414
  decidex ontology plan ontology.json --name 新本体
203
415
  decidex ontology apply ontology.json --name 新本体
@@ -207,6 +419,8 @@ decidex ontology plan ontology.json --network-id ONTOLOGY_ID
207
419
  decidex ontology apply ontology.json --network-id ONTOLOGY_ID
208
420
  ```
209
421
 
422
+ 覆盖已有本体时不能同时传 `--name`(旧用法会被静默忽略,现会明确报错);重命名需单独调用本体更新接口。
423
+
210
424
  未封装的接口可直接调用:
211
425
 
212
426
  ```bash
@@ -220,6 +434,44 @@ CI 中可使用 `DECIDEX_BASE_URL` 和 `DECIDEX_SESSION`,无需写本地配置
220
434
 
221
435
  ## 当前边界
222
436
 
223
- - CLI 已覆盖交互登录、Agent/本体/Skill 构建、会话续问与停止、产物下载、评测案例同步和评测运行。
437
+ - 常用命令已包含任务中心行动任务和指标追踪;其余纳入范围的 API 可通过有版本约束的 `platform call` 调用。
224
438
  - 当前上传与下载会整包载入内存,适合常规场景包和产物;超大文件需要后续增加流式传输。
225
- - 组织列表与服务端已验证身份、评测案例并发版本控制、Runner Pod/OOM/资源诊断、长期机器凭据仍需要后端接口支持。
439
+ - 组织列表当前没有普通用户 GET 接口;已验证身份由 `/api/auth/context` 提供。评测案例并发版本控制、Runner Pod/OOM/资源诊断、长期机器凭据仍缺少本 CLI 可用的契约。
440
+ - 权限、知识库、记忆、连接器、消息渠道、运营及平台管理多数使用操作目录,尚未提供与页面流程等价的专用命令。内部 Runner、服务令牌、分享/认证回调、SSE 和代理不在本次范围内。
441
+ - 已在 `decidex.guandata.com` 的准确 0.0.5 与 0.0.6 tag commit 上完成下述真实冒烟;目标部署存在定制或与 tag 不一致时,版本号不能独自证明每项能力可用。
442
+
443
+
444
+ ## 维护与验证
445
+
446
+ ```bash
447
+ npm test
448
+ npm pack --dry-run
449
+ # 更新 API 目录:必须指定已核对的源码 commit 和适配 tag
450
+ python3 scripts/sync-api-catalog.py --repo /path/to/decidex --ref COMMIT --baseline 0.0.6
451
+ npm install -g . # 更新本机 decidex;不发布到 npm
452
+ ```
453
+
454
+ 测试覆盖版本比较与最低版本/legacy 边界、HTTP 方法/路径/请求体、评测幂等同步与无效输入拒绝、附件与队列、凭证和 fingerprint 冲突,以及既有下载安全与超时行为。
455
+
456
+
457
+ ## 2026-11-04 真实环境冒烟
458
+
459
+ 目标 `https://decidex.guandata.com` 返回 `0.0.5` / `3e0ad67d9aa087b92cf6e60f9d501657ac4a625f`。CLI 0.2.1 使用独立配置和临时私有资源验证,保留原默认环境配置。
460
+
461
+ - 通过目标版本/身份检查、Skill 文件与凭证、评测案例与标签、真实评测(PASSED)、知识文档绑定、本体版本与导入覆盖。
462
+ - 通过附件与历史会话引用、模型/推理参数、续问/改名/分叉/增量读取、历史游标、诊断,以及真实队列编辑/删除/停止/继续;忙时 `--wait` 拒绝后未额外入队。
463
+ - 通过定时任务创建/暂停/恢复/手动运行/历史查询。发现并修复启动 HTTP 请求不受 `--wait --timeout` 约束的问题:真实 1 秒超时测试按时退出,历史仅新增一次执行,随后成功完成。
464
+ - 补充会话标题最多 24 字符、暂停任务不可手动运行的用法说明。两次暂时网络失败经状态回读及显式幂等重试恢复,未确定网络根因,也未增加写请求自动重试。
465
+ - 临时 Agent、普通会话、Skill、凭证、案例/标签、定时任务、知识文档/文件夹和本体均已通过产品接口清理并核验;评测审计及软删除记录遵循服务端保留策略。本地回归 17 项通过。
466
+
467
+ 边界:0.0.4 legacy/低版本拒绝仍由本地测试验证;未验证非空 BI 资产引用、外部通知、大文件、超过 20 轮窗口的历史读取。分析文件下载返回空列表,本次不据此声称验证了 BOE/产物文件内容传输。
468
+
469
+
470
+ ## 0.3.0 / 2026-11-05
471
+
472
+ 新增任务中心行动任务与指标追踪命令,以及按源码/tag 生成的平台操作目录。真实 0.0.5 环境完成任务生命周期、报告、版本限制和多种传输验证;修复异步复核提前结束和业务结果被误判为执行失败的问题。25 项本地回归通过。详细验证记录保存在代码仓库;API 入口覆盖与未验证范围见 [覆盖审计](docs/api-coverage.md)。
473
+
474
+
475
+ ## 2026-11-06 / 服务端 0.0.6 适配
476
+
477
+ 适配 tag `0.0.6 / 73901fa03`,CLI 0.3.0 在此补充 0.0.6 适配。新增多星期、月度、固定间隔和单次调度,保留 0.0.5 legacy 协议并拒绝不兼容写入;操作目录更新为已发布的 444 项,新增 BI 用户同步入口。机器人成员候选需传 `botId`,可用机器人支持 `purpose=push|channel`、`transport=STREAM|WEBHOOK`;使用授权支持成员或 BI 组。在线文档不支持下载或替换上传原件。权限与业务字段仍以目标服务端为准。
@@ -0,0 +1,51 @@
1
+ # API 覆盖审计
2
+
3
+ 更新:2026-11-06;CLI:0.3.0;适配服务端:0.0.6。
4
+
5
+ 源码依据与适配基线:[0.0.6 / 73901fa03](https://gitlab.mayidata.com/zijie0/decidex/-/tree/0.0.6),与生产 `server version` 返回的 commit 一致。逐一扫描 `src/app/api/**/route.ts` 的 HTTP 方法导出,以“方法 + 路径”计数,未把 `decidex api` 兜底算作覆盖。
6
+
7
+ ## 覆盖口径
8
+
9
+ | 范围 | 操作数 | CLI 入口 |
10
+ | --- | ---: | --- |
11
+ | 用户/管理员主动调用的 HTTP 操作 | 444 | 全部注册到 `platform list/show/call`,目录覆盖 100% |
12
+ | 其中存在于 0.0.6 tag | 444 | 默认可调用,实际权限由服务端判断 |
13
+ | 其中仅在 main | 0 | 本次目录仅取部署 release |
14
+ | 运行时、分享、认证回调等协议 | 105 | 不纳入浏览器登录态 CLI |
15
+ | 全部路由操作 | 549 | 按全部路由计算为 80.9% |
16
+
17
+ **90% 目标在“用户/管理员主动操作”的入口范围内达到;若包含服务协议全部路由,仍未达到 90%。** 目录注册证明请求入口可发现、路径参数可校验、传输可执行,不证明每个接口字段已适配或业务功能经过冒烟。特殊协议不应通过替换认证头强行视为普通管理 API。
18
+
19
+ ## 补齐的能力
20
+
21
+ - 行动任务:建议/成员读取、创建/幂等、查询、采纳/拒绝/完成/取消,保留版本冲突与操作理由。
22
+ - 指标追踪:候选与证据确认、创建/查询/等待、标题与调度、暂停/恢复/结束、复核历史、HTML 报告、失败重试与删除。
23
+ - 操作目录:补足既有专用命令之外的知识库 CRUD/文件、Agent 记忆/权限/发布/自进化、Skill 治理、组织成员/渠道/机器人/邮件、MCP 连接器、运营分析和平台管理等调用入口。支持 JSON、查询参数、multipart、二进制上传与下载。
24
+
25
+ ## 仍有的差距
26
+
27
+ - 上述扩展领域多数没有专用流程命令;请求字段仍需依据对应服务端 route/契约,`inputHints` 只提供线索。
28
+ - 版本元数据只证明路由在哪个 tag 已存在,不保证相同路由的请求字段、语义或权限始终不变;字段协议变化仍需单独适配与测试。
29
+ - 未支持内部运行时 24 项、服务令牌协议 61 项、外部消息回调/投递 5 项、认证回调/元数据 7 项、事件流 2 项、代理/预览 catch-all 3 项、公开分享 3 项。
30
+ - 当前上传/下载整包载入内存;外部消息实际送达、管理员写配置及每个接口的业务成功路径未全量验证。
31
+
32
+ ## 0.0.6 版本差异
33
+
34
+ - 原 main 独有的 9 项已进入 0.0.6,最低版本改为有 tag 依据的 0.0.6;另外增加 BI 用户同步配置、搜索及触发等 4 个操作。低于 0.0.6 时在请求前拒绝。
35
+ - `automation apply` 根据版本选择 schedule-v1 / schedule-v2:旧单星期、HOURLY 兼容转换,多星期/月度/间隔/单次仅在 0.0.6 可用。新增模式的参数范围和状态限制见 README。
36
+ - 机器人成员候选查询要求 `botId`;可用机器人增加 `purpose=push|channel`、`transport=STREAM|WEBHOOK`。授权写入可使用成员或 BI 组;本轮不修改生产权限或发送消息。
37
+ - `organizations.current.bi-user-sync.users.list` 必须传 `--query-param q=关键词`,`offset` 默认 0;省略 q 的实际请求返回服务端 500,补齐参数后成功。CLI 保留原始错误,没有改写服务端错误码。
38
+ - 在线知识文档不支持上传原件的下载/替换协议;该限制由目标服务端判断,普通上传文档传输保持可用。
39
+
40
+ ## 复核方法
41
+
42
+ ```bash
43
+ python3 scripts/sync-api-catalog.py --repo /path/to/decidex --ref COMMIT --baseline 0.0.6
44
+ decidex platform coverage
45
+ decidex platform list --group knowledge-library
46
+ decidex platform show knowledge-library.folders.documents.create
47
+ npm test
48
+ npm pack --dry-run
49
+ ```
50
+
51
+ 每次升级先固定 commit/tag,再更新目录与字段适配;新增业务操作应补代表性契约测试及真实环境冒烟。不能用目录计数替代测试结果。
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@guandata/decidex",
3
- "version": "0.1.2",
3
+ "version": "0.3.0",
4
4
  "description": "CLI for building and operating Decidex ontologies, agents, skills, sessions, and evaluations.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
7
7
  "files": [
8
- "src/cli.js",
9
- "README.md"
8
+ "src/",
9
+ "README.md",
10
+ "docs/api-coverage.md"
10
11
  ],
11
12
  "bin": {
12
13
  "decidex": "src/cli.js"