@guandata/decidex 0.1.2 → 0.2.1

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.5** HTTP API 的零依赖 Node.js CLI(CLI 版本 0.2.1)。要求 Node.js 22+。
4
+
5
+ 适配基线:[tag 0.0.5 / 3e0ad67d9](https://gitlab.mayidata.com/zijie0/decidex/-/tree/0.0.5),2026-11-03。已对照 2026-11-04 的 main 核查差异;本版按 tag 契约执行。
4
6
 
5
7
  ```bash
6
- npm link
7
- decidex version --json
8
+ npm install -g @guandata/decidex@0.2.1
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.5` 是本次适配基线,不是所有命令的首次发布版本。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` 的 `COMMAND_COMPATIBILITY`。后续添加命令时,可依据实际 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` 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,32 @@ 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" }` 暂停。暂停状态不能手动运行,需先用 `status: "ACTIVE"` 恢复。服务端 0.0.5 的调度支持 `HOURLY`、`DAILY`、`WEEKLY`,周日为 `weekday=0`,`timeOfDayMinutes` 为当天分钟数。main 中新增的 `weekdays`、`MONTHLY`、`INTERVAL`、`ONCE` 尚未进入该 tag,本 CLI 明确拒绝这些参数,避免旧服务端静默丢弃后按错误时间调度。执行时区由服务端决定。
310
+
311
+ 文件还可按服务端契约配置 `imPush`、`emailPush`;更新时省略保留原配置,`null` 清空。手动 `run --wait` 等待分析 Run,不代表通知已送达;送达结果查看 `automation runs`。服务端 0.0.5 的启动接口会同步等待执行结果,`--wait --timeout` 覆盖该请求及后续读取的总时间。客户端超时不会取消服务端执行;应先查 `automation runs`,不要直接重试触发。
187
312
 
188
313
  ## 组织
189
314
 
@@ -198,6 +323,9 @@ Galaxy 模式的组织由 BI 租户登录态决定,服务端会拒绝手动切
198
323
  本体构建复用 Decidex 的完整导出/导入契约,避免 CLI 重复维护对象、属性、关系、行动、风险等子资源 schema:
199
324
 
200
325
  ```bash
326
+ decidex ontology versions list ONTOLOGY_ID
327
+ decidex ontology versions get ONTOLOGY_ID VERSION_ID
328
+ decidex ontology versions create ONTOLOGY_ID --description "调整前快照"
201
329
  decidex ontology export ONTOLOGY_ID ontology.json
202
330
  decidex ontology plan ontology.json --name 新本体
203
331
  decidex ontology apply ontology.json --name 新本体
@@ -207,6 +335,8 @@ decidex ontology plan ontology.json --network-id ONTOLOGY_ID
207
335
  decidex ontology apply ontology.json --network-id ONTOLOGY_ID
208
336
  ```
209
337
 
338
+ 覆盖已有本体时不能同时传 `--name`(旧用法会被静默忽略,现会明确报错);重命名需单独调用本体更新接口。
339
+
210
340
  未封装的接口可直接调用:
211
341
 
212
342
  ```bash
@@ -220,6 +350,32 @@ CI 中可使用 `DECIDEX_BASE_URL` 和 `DECIDEX_SESSION`,无需写本地配置
220
350
 
221
351
  ## 当前边界
222
352
 
223
- - CLI 已覆盖交互登录、Agent/本体/Skill 构建、会话续问与停止、产物下载、评测案例同步和评测运行。
353
+ - 本次已补齐版本/身份检查、Agent 使用范围与知识文档绑定、会话模型/附件/历史/队列、Skill 文件与凭证、评测评分项与标签、本体版本、定时任务。
224
354
  - 当前上传与下载会整包载入内存,适合常规场景包和产物;超大文件需要后续增加流式传输。
225
- - 组织列表与服务端已验证身份、评测案例并发版本控制、Runner Pod/OOM/资源诊断、长期机器凭据仍需要后端接口支持。
355
+ - 组织列表当前没有普通用户 GET 接口;已验证身份由 `/api/auth/context` 提供。评测案例并发版本控制、Runner Pod/OOM/资源诊断、长期机器凭据仍缺少本 CLI 可用的契约。
356
+ - 统一成员/组权限、知识库文件夹与文档管理、Agent 记忆、行动/决策跟踪、连接器与消息渠道等服务端能力本次尚未封装专用命令;JSON 接口可先使用 `api`,不据此宣称 CLI 覆盖全部产品功能。
357
+ - 已在 `decidex.guandata.com` 的准确 0.0.5 tag commit 上完成下述真实冒烟;目标部署存在定制或与 tag 不一致时,版本号不能独自证明每项能力可用。
358
+
359
+
360
+ ## 维护与验证
361
+
362
+ ```bash
363
+ npm test
364
+ npm pack --dry-run
365
+ npm install -g . # 更新本机 decidex;不发布到 npm
366
+ ```
367
+
368
+ 测试覆盖版本比较与最低版本/legacy 边界、HTTP 方法/路径/请求体、评测幂等同步与无效输入拒绝、附件与队列、凭证和 fingerprint 冲突,以及既有下载安全与超时行为。
369
+
370
+
371
+ ## 2026-11-04 真实环境冒烟
372
+
373
+ 目标 `https://decidex.guandata.com` 返回 `0.0.5` / `3e0ad67d9aa087b92cf6e60f9d501657ac4a625f`。CLI 0.2.1 使用独立配置和临时私有资源验证,保留原默认环境配置。
374
+
375
+ - 通过目标版本/身份检查、Skill 文件与凭证、评测案例与标签、真实评测(PASSED)、知识文档绑定、本体版本与导入覆盖。
376
+ - 通过附件与历史会话引用、模型/推理参数、续问/改名/分叉/增量读取、历史游标、诊断,以及真实队列编辑/删除/停止/继续;忙时 `--wait` 拒绝后未额外入队。
377
+ - 通过定时任务创建/暂停/恢复/手动运行/历史查询。发现并修复启动 HTTP 请求不受 `--wait --timeout` 约束的问题:真实 1 秒超时测试按时退出,历史仅新增一次执行,随后成功完成。
378
+ - 补充会话标题最多 24 字符、暂停任务不可手动运行的用法说明。两次暂时网络失败经状态回读及显式幂等重试恢复,未确定网络根因,也未增加写请求自动重试。
379
+ - 临时 Agent、普通会话、Skill、凭证、案例/标签、定时任务、知识文档/文件夹和本体均已通过产品接口清理并核验;评测审计及软删除记录遵循服务端保留策略。本地回归 17 项通过。
380
+
381
+ 边界:0.0.4 legacy/低版本拒绝仍由本地测试验证;未验证非空 BI 资产引用、外部通知、大文件、超过 20 轮窗口的历史读取。分析文件下载返回空列表,本次不据此声称验证了 BOE/产物文件内容传输。
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@guandata/decidex",
3
- "version": "0.1.2",
3
+ "version": "0.2.1",
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
8
  "src/cli.js",
9
+ "src/compatibility.js",
9
10
  "README.md"
10
11
  ],
11
12
  "bin": {