@deepexi/datasense-cli 1.15.1 → 1.16.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.
Files changed (3) hide show
  1. package/README.md +48 -90
  2. package/dist/ontos.js +1 -1
  3. package/package.json +1 -2
package/README.md CHANGED
@@ -1,97 +1,73 @@
1
- # ontos-cli
1
+ # ontos
2
2
 
3
- Ontos 平台命令行工具。
3
+ Ontos 平台命令行工具。npm 包名为 `@deepexi/datasense-cli`，终端命令为 `ontos`。
4
+
5
+ 需要 Node.js ≥22.12.0 与 npm。
4
6
 
5
7
  ## 安装
6
8
 
9
+ 向目标环境安装，不要直接 `npm install -g @deepexi/datasense-cli@latest`：
10
+
7
11
  ```bash
8
12
  curl -fsSL https://your-host/api/cli/install.sh | sh -s -- https://your-host
9
13
  ontos auth host set https://your-host
10
14
  ```
11
15
 
12
- 需要 Node.js ≥22.12.0 与 npm。安装脚本会查询目标 host 的兼容清单，再安装推荐的精确版本。不要追随 npm `latest`。
13
-
14
- npm 包名为 `@deepexi/datasense-cli`，终端命令仍为 `ontos`。
15
-
16
- ## 发布到 npm
16
+ Windows 使用 `/api/cli/install.ps1`。安装脚本会按该 host 的兼容清单安装对应版本。
17
17
 
18
- CLI 使用自身 semver（当前 **1.15.1**），与服务端镜像 tag **不是同一套号**。服务端在部署时指定日期 tag。当前兼容矩阵为 **`v2026.09.14` 推荐 CLI 1.15.1**（范围 `>=1.13.0 <2.0.0`）；更旧的 CLI 会被 Gateway 拒绝。CLI 1.10.0 的 Workbench 互信需要服务端部署对应的认证改动并开启外部身份，不能只凭日期 tag 判断已支持。部署命令示例：
18
+ 升级：
19
19
 
20
20
  ```bash
21
- bun run deploy:test -- v2026.09.14
21
+ ontos update # 按当前 host 兼容范围升级
22
+ ontos update --check # 只查看，不安装
22
23
  ```
23
24
 
24
- 兼容范围见 [docs/compatibility](../../docs/compatibility/README.md)。安装与更新都先查询目标 host 的 `/api/cli/compatibility`，再安装范围内精确版本：
25
+ 查看 CLI 版本：`ontos -v` / `ontos --version`。子命令里的 `--version <n>` 是该命令自己的版本参数，例如 `kb cat`。
26
+
27
+ ## 快速开始
25
28
 
26
29
  ```bash
27
- curl -fsSL https://your-host/api/cli/install.sh | sh -s -- https://your-host
28
- ontos update # 按当前 host 兼容范围升级
29
- ontos update --check # 只看范围、推荐版本和可安装版本
30
+ ontos auth host set https://your-host
31
+ ontos auth login
32
+ ontos project list
33
+ ontos project set <name>
30
34
  ```
31
35
 
32
- 使用具有 `@deepexi` scope 发布权限的 npm 账号，在 `packages/ontos-cli` 目录执行：
36
+ `project set` 会在当前目录写入 `ontos.yaml`。
33
37
 
34
- ```bash
35
- npm publish --access public
36
- ```
38
+ ## 常用命令
37
39
 
38
- 发布前会自动构建 Node.js 产物；当前只发布这一个包名。查看 CLI 包版本用 `ontos -v` / `ontos --version`（`-V` / `--cli-version` 同样可用）。子命令里的 `--version <n>` 仍表示该命令自己的版本参数，例如 `kb cat` 与 `simulation version evaluate`。
40
+ | 命令 | 说明 |
41
+ | :--- | :--- |
42
+ | `auth` | 登录、退出、查看会话；`host get` / `host set` |
43
+ | `project` | 项目列表、落地与成员 |
44
+ | `update` | 按当前 host 升级 CLI |
45
+ | `skill list` / `skill install` / `skill context` / `skill prune` | 列出、安装技能存根，运行时取技能内容，清理已下线存根 |
46
+ | `query` | 只读查询 |
47
+ | `search` | 检索对象 |
48
+ | `execute` | 执行动作 |
49
+ | `compute` | 执行已发布函数 |
50
+ | `kb` | 知识库读取：`ls` / `cat` / `fetch` / `history` / `search` |
51
+ | `simulation` | 场景推演 |
52
+ | `admin` | 平台管理（租户、环境、资源、同步、校验等），详见 `ontos admin --help` |
39
53
 
40
- ## 快速开始
54
+ 完整命令与参数以 `ontos --help` 和各子命令 `--help` 为准。
41
55
 
42
- ```bash
43
- # 配置服务地址
44
- ontos auth host set http://localhost:3000
56
+ ## 技能
45
57
 
46
- # 登录
47
- ontos auth login --email your@email.com
58
+ `ontos skill install <skill...>` 只在当前目录写入技能存根（一份 `SKILL.md`：触发描述、所属项目，以及「先运行 `ontos skill context <name>`」）。默认同时写入 `.opencode/skills`、`.agents/skills`、`.claude/skills`；`--agent` 选择子集，`--global` 写到各宿主的用户目录。能力内容不落盘：agent 每次用 `ontos skill context <name>` 按当前身份、环境和快照取得；`--ref <path>` 取单篇参考。平台升级和项目发布后不用重装。技能删了用 `ontos skill prune` 清掉本地存根。
48
59
 
49
- # 查看可访问的项目
50
- ontos project list
60
+ Grok 和 Codex 在仓库未被信任时不加载项目级技能，把仓库标为信任后才会看到存根。OpenCode v1 不热加载技能文件，存根改写之后要新开一个会话，description 才会更新；`ontos skill context` 取到的内容不受影响。
51
61
 
52
- # 在项目目录落地上下文（写 ontos.yaml，自动解析所属 tenant）
53
- ontos project set <name>
54
- ```
62
+ ## 输出
55
63
 
56
- ## 命令
64
+ 默认输出 Markdown 表格。脚本与编排器请显式使用 `--format json`（或 `ONTOS_FORMAT=json`）。
57
65
 
58
- | 命令 | 说明 |
59
- | :--- | :--- |
60
- | `auth` | 用户会话：`login`/`logout`、`host get/set`、`status`/`whoami`（`config` 命令已删除） |
61
- | `project` | 项目发现、落地与治理：`list`/`set`/`get`/`create`/`update`/`archive`/`member` |
62
- | `update` | 升级本机全局安装的 `@deepexi/datasense-cli`（`--check` 只查不装） |
63
- | `admin tenant` | 租户 CRUD、用户开户与租户成员 |
64
- | `admin env` | 环境管理 |
65
- | `admin resources` | 资源 CRUD（datasource / property-type / object-type / relation / function / action / skill / scenario / evaluator） |
66
- | `admin datasource test <name>` | 测试已保存数据源连通性（服务端解析 SecretReference） |
67
- | `admin sync` | 声明式 YAML 同步（init / pull / push / diff / schema / migrate-manifest） |
68
- | `admin validate` | 本地 YAML spec 离线校验 |
69
- | `skill list` | 列出可安装的平台技能 |
70
- | `skill install` | 下载技能到本地 agent 目录 |
71
- | `admin codegen` | 生成本地 TypeScript 类型声明 |
72
- | `query` | 只读执行查询 |
73
- | `execute` | 运行态一步执行写动作并落库（内联 `--params`，支持分支/版本） |
74
- | `compute` | 运行态执行已发布函数计算（内联 `--params`，支持分支/版本） |
75
- | `admin action debug` / `admin function debug` | 维护态调试（流式逐节点 / 本地代码 override，统一支持 `--params '<json>'`/`-f`/`--stdin`；函数业务 `throw` 返回 422 + `code: function_error` 原样透出 message） |
76
- | `search` | 只读检索对象（语义/全文检索经 `--filter` 表达，命中回传 `scores`） |
77
- | `kb` | 项目知识库访问：`ls` / `cat` / `fetch` / `usage` / `partitions` / `search <query>` / `reindex`；本地写入仅限 `put`/`rm` 与 `admin sync push` |
78
- | `simulation branch execute` | 以真实模式重放方案动作序列并落基线数据（写真实数据，须 `--force`） |
79
-
80
- ## Output Contract for Orchestrators（编排器输出契约）
81
-
82
- `ontos` 自我定位为 AI-only CLI，主要消费者是 LLM agent 与脚本（见 [ADR-0017](../../docs/adr/0017-cli-argv-as-agent-interface-not-mcp.md)）。命令输出对托管通用 agent / 编排器构成一份**机器稳定契约**，关键约定如下：
83
-
84
- - **默认 `table` 到 stdout（ADR-0061）。** 多数命令默认把结果渲染为 Markdown 表格（递归对象数组 → 表；标量 → `key: value` 行；有损展示，面向 agent 阅读、省 token）。渲染器单源于 `@mu-ontos/shared` 的 `renderMarkdownTable`。
85
- - **程序化消费一律 `--format json`（或 `ONTOS_FORMAT=json`）。** 全局 `--format <table|json|yaml>` 只切换序列化形态；解析层级为 `--format` > `ONTOS_FORMAT` 环境变量 > per-command fallback。`get` / spec 类读路径默认仍 YAML（`printYamlResult`）；`--format json` 恒可强制 JSON。机器契约字段只增不删不改名，破坏性变更走 CLI major 版本（semver，见下）。
86
- - **错误为结构化 JSON 到 stderr。** 失败时把 `CliErrorPayload`（含稳定 `code`、`message`、可选 `hint` / `details`）以 JSON 打印到 **stderr**（`core/output.ts` 的 `printError`），与 stdout 的正常结果分离；错误 payload **不受** `--format` 影响。agent 应按 stderr JSON 的 `code` 字段分支（含 `auth_required`），而非正则抠 `message`。远端失败优先透出服务端 `code`（如 `function_error`），否则按 HTTP status 映射（`not_found` / `validation_error` / `conflict` / `forbidden` / `auth_required` / `server_error`）。
87
- - **退出码粗粒度且稳定。** `0` 成功 / `2` 用法+配置+输入错 / `1` 运行时+远端失败（含 401）。可执行的修复信息装在 stderr JSON 里，退出码只表达类别；agent 用 `code` 分支，不要依赖独立退出码。
88
- - **NDJSON 用于流式。** 流式命令（如 `admin action debug` 的 SSE 逐节点调试）逐事件输出 NDJSON（每行一条 JSON 事件）；此时 `--format` 不影响流式帧。
89
- - **面向人的展示态**（默认 `table`、`--format yaml`、`--layout ascii`）不宜被编排器当机器契约依赖；需要可解析结构时显式 `--format json`。
90
- - **稳定性承诺按 semver。** 契约字段只增不删不改名；破坏性变更随包 major 版本号 bump，并在 README / CHANGELOG 标注（[ADR-0017](../../docs/adr/0017-cli-argv-as-agent-interface-not-mcp.md) / [ADR-0061](../../docs/adr/0061-cli-default-output-markdown-table.md)）。
91
-
92
- ## 多项目配置
93
-
94
- 每个本地项目各放一份 `ontos.yaml`，例如 `sales/ontos.yaml`、`inventory/ontos.yaml`。父目录不放指向某个子项目的默认清单。
66
+ 失败时错误 JSON 写在 stderr，含稳定的 `code` 字段；不要解析 `message` 文本。退出码：`0` 成功，`2` 用法/配置/输入错误，`1` 运行时或远端失败。
67
+
68
+ ## 项目清单
69
+
70
+ 每个项目目录一份 `ontos.yaml`：
95
71
 
96
72
  ```yaml
97
73
  tenant: acme
@@ -102,29 +78,11 @@ sync:
102
78
  ```
103
79
 
104
80
  ```bash
105
- ontos --cwd ./sales auth status --format json
81
+ ontos --cwd ./sales project list
106
82
  ontos --cwd ./sales admin sync diff
107
- ontos --manifest ./ontos.inventory.yaml admin sync push
108
83
  ```
109
84
 
110
- - `--cwd` 指定执行目录，命令行相对路径以此为基准；`--manifest` > `ONTOS_MANIFEST` > 目录发现。显式清单不存在或损坏时直接失败。
111
- - 自动发现向上止于最近 Git 根（含 worktree `.git` 文件）、home 或文件系统根；不搜索子目录/兄弟项目，不合并父级清单。无 Git 的普通子目录仍会继承父清单。
112
- - `.yaml` 和 `.yml` 均可发现，同层共存时报错。新文件统一写 `.yaml`；自定义名称用 `--manifest` 选择。
113
- - specDir 与缺省 `ontos-project` 相对清单目录解析；`--dir` 为命令行资源目录。它命中另一项目清单时，租户、项目、同步域一起切换；显式清单与目录清单不一致时拒绝执行。
114
- - `-p` / `ONTOS_PROJECT` 仍是远端项目覆盖。同步、remote validate、codegen 不允许借此改绑另一项目；name/id 经只读校验等价才允许。
115
- - `project set` 写显式或最近清单；更换已有绑定必须加 `--rebind`，保留原 specDir，并输出旧/新绑定。日常切换项目使用 `--cwd` / `--manifest`。损坏 YAML 不会被清空重建。
116
- - `sync init` 不在继承祖先清单的目录中创建影子清单；请定位项目根或独立目录。`specDir: .` 时可以直接 `sync diff` / `sync push`：清单文件、点开头的目录（如 `.git`）和 `node_modules` 不会被当作资源上传。`sync pull` 仍拒绝这一布局，因为它会替换整个目录并删除清单。资源目录也不要设成清单的祖先。
117
- - status 的 `context` 展示清单路径、本地目录和字段来源；保留已有 status 顶层字段。
118
- - 跨 Host 使用对应 token 或独立 `XDG_CONFIG_HOME`；不会把旧 Host 的登录 token 发给覆盖后的新 Host。清单不存凭据。`auth host set` 更换实例时会清除旧登录身份，需要登录新实例。
119
-
120
- 旧清单缺少 `sync.domains` 时，在对应项目根执行 `ontos admin sync migrate-manifest --dry-run`，核对后去掉 `--dry-run` 迁移为 `[ontology]`；只有明确需要安全声明时才开启 `security`。跨 Git 根继承的旧脚本改为 `--manifest <原清单>`。此前依赖 cwd 漂移的默认资源目录请显式设置 specDir。
121
-
122
- ### Deepworks 注入会话
123
-
124
- 存在 `DEEPEXIOS_AUTHORIZATION` 时，CLI 使用 Workbench 注入凭据；空值或非法值直接报错，不读取本地 token 或默认租户。不得同时配置 `ONTOS_INTERNAL_SERVICE_TOKEN`。裸 token 和单个 `Bearer ` 前缀均支持；身份信息只以服务端 `/auth/me` 返回的 `credential` 为准。
125
-
126
- Host 始终按 `--host`、`ONTOS_HOST`、本地 `config.host` 的顺序选择完整地址，保留路径，不自动添加 `/datasense`，不读取 `DEEPEXIOS_BASE_URL`。受控 HTTP 测试须把 `ONTOS_WORKBENCH_ALLOW_HTTP_HOST` 设置为目标精确 `hostname:port`；默认拒绝 HTTP。
127
-
128
- Workbench 请求禁止跟随重定向，401 不刷新本地登录态。`auth status` / `auth whoami` 显示已验证身份；`auth login` 验证注入会话，`auth logout` 提示在 Workbench 结束会话，两者均不改本地配置。默认租户来自 `credential.boundTenantId`，显式 flag、环境变量和清单仍是由服务端校验的资源选择。SSE 流式命令沿用相同的注入认证与业务权限校验。
129
-
130
- Workbench 凭据映射为 Ontos 用户后，与普通 token 使用相同的角色、capability 和资源授权；不按身份来源限制 Skill 下载、查询、函数、Action 或写入。注入态支持 `auth host set <url>` 配置机器 host（更换 host 会清除旧的本地登录身份，注入凭据不落盘），也可用 `--host`/`ONTOS_HOST` 指定本次目标。`auth host get` 展示本次解析的目标。
85
+ - `--cwd` 指定工作目录；`--manifest` 显式指定清单文件。
86
+ - 自动发现从当前目录向上查找，止于最近 Git 根或用户主目录。
87
+ - 切换已绑定项目使用 `--cwd` / `--manifest`。覆盖已有绑定需 `ontos project set --rebind`。
88
+ - 清单不存放登录凭据。更换 `auth host set` 后需要重新登录。