@deepexi/datasense-cli 1.8.1

package/README.md

@@ -0,0 +1,78 @@
+# ontos-cli
+
+Ontos 平台命令行工具。
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @deepexi/datasense-cli
+
+# 或直接运行
+npx @deepexi/datasense-cli <command>
+```
+
+需要 Node.js ≥ 18。
+
+npm 包名为 `@deepexi/datasense-cli`，终端命令仍为 `ontos`。
+
+## 发布到 npm
+
+使用具有 `@deepexi` scope 发布权限的 npm 账号，在 `packages/ontos-cli` 目录执行：
+
+```bash
+npm publish --access public
+```
+
+发布前会自动构建 Node.js 产物；当前只发布这一个包名。
+
+## 快速开始
+
+```bash
+# 配置服务地址
+ontos auth host set http://localhost:3000
+
+# 登录
+ontos auth login --email your@email.com
+
+# 查看可访问的项目
+ontos auth project list
+
+# 在项目目录落地上下文（写 ontos.yaml，自动解析所属 tenant）
+ontos auth project set <name>
+```
+
+## 命令
+
+| 命令 | 说明 |
+| :--- | :--- |
+| `auth` | 用户会话上下文：`login`/`logout`、`host get/set`、`project list/set`、`status`（`config` 命令已删除，会话上下文统一走此命令组） |
+| `update` | 升级本机全局安装的 `@deepexi/datasense-cli`（`--check` 只查不装） |
+| `admin project` | 项目管理（含 `project member` 项目成员） |
+| `admin tenant` | 租户 CRUD、用户开户与租户成员 |
+| `admin env` | 环境管理 |
+| `admin resources` | 资源 CRUD（datasource / property-type / object / relation / function / action / skill / scenario / evaluator） |
+| `admin sync` | 声明式 YAML 同步（init / pull / push / diff / schema） |
+| `admin validate` | 本地 YAML spec 离线校验 |
+| `skill list` | 列出可安装的平台技能 |
+| `skill install` | 下载技能到本地 agent 目录 |
+| `codegen` | 生成本地 TypeScript 类型声明 |
+| `query` | 只读执行查询 |
+| `execute` | 运行态一步执行写动作并落库（内联 `--params`，支持分支/版本） |
+| `compute` | 运行态执行已发布函数计算（内联 `--params`，支持分支/版本） |
+| `admin action debug` / `admin function debug` | 维护态调试（流式逐节点 / 本地代码 override，统一支持 `--params '<json>'`/`-f`/`--stdin`；函数业务 `throw` 返回 422 + `code: function_error` 原样透出 message） |
+| `search` | 只读检索对象（语义/全文检索经 `--filter` 表达，命中回传 `scores`） |
+| `kb` | 项目知识库访问：`ls` / `cat` / `fetch` / `usage` / `partitions` / `search <query>` / `reindex`；本地写入仅限 `put`/`rm` 与 `admin sync push` |
+| `simulation branch execute` | 以真实模式重放方案动作序列并落基线数据（写真实数据，须 `--force`） |
+
+## Output Contract for Orchestrators（编排器输出契约）
+
+`ontos` 自我定位为 AI-only CLI，主要消费者是 LLM agent 与脚本（见 [ADR-0017](../../docs/adr/0017-cli-argv-as-agent-interface-not-mcp.md)）。命令输出对托管通用 agent / 编排器构成一份**机器稳定契约**，关键约定如下：
+
+- **默认 `table` 到 stdout（ADR-0061）。** 多数命令默认把结果渲染为 Markdown 表格（递归对象数组 → 表；标量 → `key: value` 行；有损展示，面向 agent 阅读、省 token）。渲染器单源于 `@mu-ontos/shared` 的 `renderMarkdownTable`。
+- **程序化消费一律 `--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，见下）。
+- **错误为结构化 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`）。
+- **退出码粗粒度且稳定。** `0` 成功 / `2` 用法+配置+输入错 / `1` 运行时+远端失败（含 401）。可执行的修复信息装在 stderr JSON 里，退出码只表达类别；agent 用 `code` 分支，不要依赖独立退出码。
+- **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)）。