@deepexi/datasense-cli 1.8.1 → 1.9.0

package/README.md

@@ -18,13 +18,21 @@ npm 包名为 `@deepexi/datasense-cli`，终端命令仍为 `ontos`。
 
 ## 发布到 npm
 
+CLI 使用自身 semver（当前 **1.9.0**），与服务端镜像 tag **不是同一套号**。服务端在部署时指定日期 tag，本版对应 **`v2026.09.08`**：
+
+```bash
+bun run deploy:test -- v2026.09.08
+```
+
+兼容范围见 [docs/compatibility](../../docs/compatibility/README.md)。Gateway 兼容门禁尚未落地，发布后 `ontos update` 仍会追随 npm `latest`。
+
 使用具有 `@deepexi` scope 发布权限的 npm 账号，在 `packages/ontos-cli` 目录执行：
 
 ```bash
 npm publish --access public
 ```
 
-发布前会自动构建 Node.js 产物；当前只发布这一个包名。
+发布前会自动构建 Node.js 产物；当前只发布这一个包名。查看 CLI 包版本用 `ontos -V` / `ontos --cli-version`（`--version` 留给 `simulation version evaluate`）。
 
 ## 快速开始
 
@@ -76,3 +84,33 @@ ontos auth project set <name>
 - **NDJSON 用于流式。** 流式命令（如 `admin action debug` 的 SSE 逐节点调试）逐事件输出 NDJSON（每行一条 JSON 事件）；此时 `--format` 不影响流式帧。
 - **面向人的展示态**（默认 `table`、`--format yaml`、`--layout ascii`）不宜被编排器当机器契约依赖；需要可解析结构时显式 `--format json`。
 - **稳定性承诺按 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)）。
+
+## 多项目配置
+
+每个本地项目各放一份 `ontos.yaml`，例如 `sales/ontos.yaml`、`inventory/ontos.yaml`。父目录不放指向某个子项目的默认清单。
+
+```yaml
+tenant: acme
+project: sales
+specDir: ./spec
+sync:
+  domains: [ontology]
+```
+
+```bash
+ontos --cwd ./sales auth status --format json
+ontos --cwd ./sales admin sync diff
+ontos --manifest ./ontos.inventory.yaml admin sync push
+```
+
+- `--cwd` 指定执行目录，命令行相对路径以此为基准；`--manifest` > `ONTOS_MANIFEST` > 目录发现。显式清单不存在或损坏时直接失败。
+- 自动发现向上止于最近 Git 根（含 worktree `.git` 文件）、home 或文件系统根；不搜索子目录/兄弟项目，不合并父级清单。无 Git 的普通子目录仍会继承父清单。
+- `.yaml` 和 `.yml` 均可发现，同层共存时报错。新文件统一写 `.yaml`；自定义名称用 `--manifest` 选择。
+- specDir 与缺省 `ontos-project` 相对清单目录解析；`--dir` 为命令行资源目录。它命中另一项目清单时，租户、项目、同步域一起切换；显式清单与目录清单不一致时拒绝执行。
+- `-p` / `ONTOS_PROJECT` 仍是远端项目覆盖。同步、remote validate、codegen 不允许借此改绑另一项目；name/id 经只读校验等价才允许。
+- `auth project set` 写显式或最近清单；更换已有绑定必须加 `--rebind`，保留原 specDir，并输出旧/新绑定。日常切换项目使用 `--cwd` / `--manifest`。损坏 YAML 不会被清空重建。
+- `sync init` 不在继承祖先清单的目录中创建影子清单；请定位项目根或独立目录。资源目录不要使用清单所在目录或其祖先，否则 pull 会拒绝，避免清单被目录替换删除。
+- status 的 `context` 展示清单路径、本地目录和字段来源；保留已有 status 顶层字段。
+- 跨 Host 使用对应 token 或独立 `XDG_CONFIG_HOME`；不会把旧 Host 的登录 token 发给覆盖后的新 Host。清单不存凭据。`auth host set` 更换实例时会清除旧登录身份，需要登录新实例。
+
+旧清单缺少 `sync.domains` 时，在对应项目根执行 `ontos admin sync migrate-manifest --dry-run`，核对后去掉 `--dry-run` 迁移为 `[ontology]`；只有明确需要安全声明时才开启 `security`。跨 Git 根继承的旧脚本改为 `--manifest <原清单>`。此前依赖 cwd 漂移的默认资源目录请显式设置 specDir。