@inf-monkeys-tech/monkeys-cli 0.10.0

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@inf-monkeys-tech/monkeys-cli",
+  "version": "0.10.0",
+  "packageManager": "bun@1.3.14",
+  "description": "面向 AI Agent、自动化和人工操作的 Monkeys 命令行客户端",
+  "type": "module",
+  "bin": {
+    "monkeys": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "oclif.manifest.json",
+    "README.md",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./contracts": "./dist/contracts/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && oclif manifest . && node ./scripts/sort-manifest.mjs",
+    "benchmark": "node ./scripts/benchmark.mjs",
+    "checksums": "node ./scripts/checksums.mjs",
+    "ci:prepare-version": "bun ./scripts/ci/prepare-npm-version.ts",
+    "ci:create-release": "bun ./scripts/ci/create-gitlab-release.ts",
+    "clean": "node ./scripts/clean.mjs",
+    "dev": "tsx ./bin/dev.ts",
+    "format": "prettier --write package.json tsconfig.json tsconfig.build.json .prettierrc.json bin scripts src test",
+    "format:check": "prettier --check package.json tsconfig.json tsconfig.build.json .prettierrc.json bin scripts src test",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "pack:standalone": "bun run build && oclif pack tarballs -r . -t win32-x64,linux-x64,darwin-x64",
+    "prepack": "bun run clean && bun run build",
+    "smoke:installer": "node ./scripts/install-wizard-smoke.mjs",
+    "smoke:npm": "node ./scripts/npm-install-smoke.mjs",
+    "smoke:standalone": "node ./scripts/standalone-smoke.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "bun run format:check && bun run lint && bun run test && bun run build && bun run version:smoke && bun run smoke:installer && bun run smoke:npm && bun run benchmark",
+    "version:smoke": "node ./bin/run.js version show --output json && node ./bin/run.js version check --output json"
+  },
+  "oclif": {
+    "bin": "monkeys",
+    "dirname": "monkeys",
+    "commands": "./dist/commands",
+    "topicSeparator": " ",
+    "update": {
+      "node": {
+        "version": "24.18.0"
+      }
+    }
+  },
+  "dependencies": {
+    "@oclif/core": "4.13.2",
+    "ajv": "8.20.0",
+    "csv-parse": "6.1.0",
+    "csv-stringify": "6.6.0",
+    "exceljs": "4.4.0",
+    "saxes": "5.0.1",
+    "undici": "7.29.0",
+    "unzipper": "0.10.14",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "7zip-bin": "5.2.0",
+    "oclif": "4.23.29",
+    "prettier": "3.9.6",
+    "tsx": "4.23.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "1.3.0"
+  },
+  "overrides": {
+    "ejs": "6.0.1",
+    "uuid": "11.1.1"
+  },
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "monkeysReleaseCommit": "f1a5f9f8303b653b747765f6fb2d144587c13060"
+}

package/skills/monkeys/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: monkeys
+description: 理解并通过 monkeys CLI 安全操作 Monkeys 平台的多租户/私有化部署、认证、Workflow、Execution、Agent Work、文件、Data/Ontology 与 Kernel System Config。用户询问平台能力、Ontology、View、增强视图、Asset、Field、Tag 等概念，要求管理平台资源，或 Agent 需要选择 Profile、处理结构化错误和执行受控 OpenAPI 降级时使用。
+---
+
+# Monkeys CLI
+
+只通过 `monkeys` CLI 操作平台。不要直接发送 HTTP 请求，也不要把 Tool/Workflow 的 capability 声明当作平台 API。
+
+## 执行流程
+
+1. 运行 `monkeys version show --output json`，确认 CLI 可用和命令 Schema 兼容。
+2. 选择明确的 `--profile`。Data 任务按[Data 视角路由](references/data-perspective.md)选择显式 `--perspective`：Kernel 全局读取默认不传 `--team`，只有用户明确筛选时才传；Field、View、Feature Value、Advanced Search 和 Asset Export 等需要数据资源定位时传已确认的 `--resource-team`。Studio 使用明确的 Team 上下文。不要在任务中途隐式切换上下文。
+3. 在第一次使用命令或参数不确定时运行 `monkeys <命令> --help`。以 CLI 帮助为参数真相，不凭记忆补参数。
+4. 优先调用 Workflow、Execution、Agent Work、File、Data、System Config 等语义命令，并使用 `--output json`。解析结构化结果和退出码，不解析面向人的 Text 文案。
+5. 写操作前向用户回显 Profile、`teamMode`、实际生效的 Team（若有）、Ontology、实际 Data 合同、Data Perspective、精确目标 ID 或 System Config Key。目标模糊时先查询，禁止猜测。
+6. 只按[受控降级](references/fallback.md)处理语义兼容性故障；认证、授权、确认和输入错误不得降级。
+7. 返回执行结果、关键资源 ID、Context Fingerprint；失败时返回错误 code、恢复建议和是否可能已产生副作用。
+
+## 按需读取
+
+- 解释平台有哪些功能、某项需求应进入哪个领域或当前 CLI 是否覆盖：必须读取[平台能力地图](references/platform-overview.md)。
+- 涉及 Ontology、View、增强视图、Asset、Field、Feature Value、Tag、Membership 或筛选语义：必须读取[Ontology 领域模型](references/ontology-model.md)。
+- 配置部署、切换租户、API Key 或账户登录：读取[认证与上下文](references/authentication.md)。
+- 查询、创建、导入、更新、删除或运行 Workflow，等待 Execution 或传文件：读取[工作流、执行与文件](references/workflow-execution-files.md)。
+- 查询、创建、分配、对话、审批、验收或观察 Agent Work：必须读取[Agent Work](references/agent-work.md)。
+- 查询、搜索或抽样 Data：读取[Data 读取](references/data-read.md)。按 Feature Column 的结构化值搜索 Asset 时，还必须读取[Ontology Feature 结构化检索](references/ontology-feature-search.md)。
+- 创建、修改或删除 Data 资源：读取[Data 写入](references/data-write.md)。
+- 管理 Ontology、移动/复制 Container、回收或恢复：必须读取[Data 治理](references/data-governance.md)。
+- 导入或导出 Ontology 结构、JSONL、CSV 或 XLSX 数据：必须读取[Data 导入导出](references/data-transfer.md)。
+- 任何 Data 操作：必须读取[Data 视角路由](references/data-perspective.md)。
+- 查看、校验、导出或按 Key 修改 Kernel System Config：必须读取[System Config](references/system-config.md)。
+- 语义命令返回 `fallbackEligible=true`：必须读取[受控降级](references/fallback.md)。
+- 处理错误、确认、批处理或 Secret：读取[安全与错误](references/safety-errors.md)。
+- 检查 CLI/Skill 版本：读取[兼容性](references/compatibility.md)。
+
+## 不可违反的边界
+
+- 不主动索要、接收或在回答中复述密码、API Key、Bearer Token。账户认证只允许通过 `auth login` 返回的 Deployment 浏览器地址完成；CLI 和 Agent 都不得处理账户密码。
+- 首次登录以订阅 `--url` 为唯一 Endpoint 输入，不要求预建 Deployment/Profile。API Key 只经 `--api-key-stdin` 或 `--api-key-env` 导入；浏览器登录只把服务端签发的 Session Token 写入系统 Keyring。
+- Agent 必须使用 `auth login --url <Endpoint> --no-wait --output json` 发起浏览器登录，把原样授权 URL 交给用户，并在用户确认完成后用同一次返回的临时 `profile` 与 `--device-code` 完成轮询；不得自行填写网页登录表单或跨 Endpoint 复用 Device Code。
+- 登录成功后必须以 `/api/configs` 返回的已认证 `tenantId` 作为订阅/Profile 名；不得从 URL 主机名猜租户名。
+- 不覆盖认证、Tenant、Team、Data Perspective 等受保护 Header。
+- 不把 Session 的 `currentTeamId` 或 CLI 返回的 `resourceLocator.teamId` 描述为 Kernel 全局查询作用域，也不为 Kernel 全局读取手工补 `--team`。不得用 Ontology owner Team 猜测 `--resource-team`；缺少已确认值时在聊天中告知并停止。
+- 不把 Public/Shared/可读理解为可写；服务端授权是最终判断。
+- 不执行 Ontology/Bucket Delete、Container Purge、批量 Trash 或语义层未提供的永久清理。
+- 不把 `data container remove` 描述为删除 Asset；它只移除 Membership，可从 Trash 恢复。
+- 不在聊天或普通 HTTP 工具中处理 Asset/附件 URL，也不自行生成对象存储签名；始终使用 CLI 下载命令。CLI 可匿名读取公开 HTTPS 对象，访问受限时必须改由 Server 返回签名 URL，任何 URL 都不得显示在聊天中。
+- 不把 View Feature 中的 PDF/文件误当成 Asset 封面；使用 `data asset attachment download`，只展示本地文件结果和审计信息，不展示 Feature Value URL。
+- 不把筛选失败当成 View 类型不正确，不得为了实现 Tag/Field 筛选而自动执行 Filter View 到 Container View 的转换。
+- 不把 Feature 结构化检索描述为语义、向量、模糊或全文搜索；不使用 Feature 展示名、Field ID 或 ES path 代替 `config.fieldKey`，也不在 HTTP 400/503 后改用 Raw API、PG 扫描或其他静默兜底。
+- 不自动重放已发送或结果未知的写操作。
+- Workflow 写操作不得使用 Raw API 降级；Update 不使用 ETag，并依赖 CLI 写前快照与写后回读恢复。
+- Data 文件未显式指定 `--format` 时始终按 JSONL 处理；不得根据扩展名猜测 CSV/XLSX。真实导入必须先完成全量预检，并要求用户对精确 Profile、Perspective、Ontology 和文件明确授权。
+- Data 文件迁移使用 `data asset import/export`；需要 Server 后台原生 JSONL 任务时使用 `data asset import-jsonl`；只给已有 Asset 回填图片/文本 Feature 时优先使用 `data asset feature-backfill`。不要根据文件名或数据量在这些写路径间静默切换。`data asset enrich-jsonl` 只是已弃用兼容入口；若被显式调用，必须把结果中的替代命令以当前聊天界面可读方式告诉用户。
+- 完整 Ontology 迁移必须区分 owner Team 与 data resource Team：结构命令显式传 `--team` 和需要时的 `--resource-team`；Kernel Asset Export 用 `--resource-team` 定位读取资源，Asset Import 等写命令仍用 `--team` 指定目标数据 Team。包含 Field、Tag 或 View 引用的 Asset 导入必须传同一次真实 Ontology 导入生成的 `--ontology-report`，并在聊天中说明目标视角与 Team；不得用同名匹配或来源 ID 猜测。
+- System Config 只允许 Kernel Profile；Team 仅是身份上下文，不是配置作用域。敏感 Key 只允许通过 `config set --value-stdin` 写入。
+- Agent Work 只允许 Kernel Profile，固定 `teamMode=none`，不得传入或继承 Team，也不得在权限不足时静默改用 Studio。
+- Agent Work 出现 `user_input_required`、`spec_approval_required`、`awaiting_acceptance`、失败或超时时，必须在聊天中明确告诉用户；`MUTATION_OUTCOME_UNKNOWN` 时只做只读恢复检查。
+- Agent Work 的聊天反馈必须面向人的任务与决策，并按当前 Agent 和聊天界面的可靠显示能力自适应呈现；不得把某个 Profile、租户或 Markdown 组件写成固定前提，也不得默认倾倒原始 JSON。

package/skills/monkeys/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Monkeys CLI'
+  short_description: '理解平台能力并通过 CLI 安全操作 Agent Work、Ontology 与系统配置'
+  default_prompt: '使用 $monkeys 理解平台领域，并通过 CLI 安全完成操作，优先选择语义命令。'

package/skills/monkeys/references/agent-work.md

@@ -0,0 +1,108 @@
+# Agent Work
+
+Agent Work 是 Kernel Agent Console 的工作单能力。只使用明确声明 Kernel Surface 的 Profile；命令不接受、不继承 Team，结构化输出必须为 `teamMode=none`。权限不足时显式报告，不切换到 Studio。
+
+## 推荐流程
+
+1. 运行 `monkeys agent work list --profile <Kernel Profile> --limit 20 --output json`。
+2. 用精确 ID 运行 `monkeys agent work get <ID> --profile <Kernel Profile> --output json`。
+3. 只有用户目标明确后才执行创建、编辑、分配、对话、审批、控制或验收。
+4. 长任务优先用 `wait`；需要逐次状态流时用 `watch`。
+5. 根据 `status`、`phase`、`attentionState` 和错误恢复建议在聊天中报告下一步。
+
+OpenAPI 不可用时，CLI 可以使用经过测试的精确内置合同；输出会显示 `schemaSource=builtin` 和 `schemaFresh=false`。这不是切换身份或绕过授权。若响应不兼容，停止语义操作，按受控降级规则判断，不直接发送 HTTP。
+
+## 读取与发现
+
+```bash
+monkeys agent work list --profile <Profile> --limit 20 --output json
+monkeys agent work list --profile <Profile> --attention-required --output json
+monkeys agent work get <ID> --profile <Profile> --output json
+monkeys agent work collaborators --profile <Profile> --output json
+monkeys agent work runtime list [<ID>] --profile <Profile> --output json
+```
+
+- `list` 默认最多输出 20 条；以 `serverTotal`、`returned`、`truncated` 判断截断，不循环无界获取。
+- 临时引用图、Preview 和对象存储 URL 不在稳定输出中。不得要求 Raw API 回显这些 URL。
+- 普通 Kernel 用户可能只能看到自己创建的工作单，超级管理员可能看到全局列表；空结果不能解释为 Team 过滤。
+
+## 创建与编辑
+
+```bash
+monkeys agent work create --profile <Profile> --title <标题> --description @requirement.md --repo-url <URL> --repo-ref <Ref> --output json
+monkeys agent work update <ID> --profile <Profile> --description @requirement.md --output json
+```
+
+- `--reference-image` 最多重复 3 次，只支持本地 PNG/JPEG/WebP，单张不超过 10 MiB。
+- CLI 把图片上传给 Server；签名和对象存储处理属于 Server。CLI 不自行签名。
+- 创建可选 `--assignment auto|existing_runtime|new_runtime`。现有 Runtime 必须同时传 `--runtime-id`；新 Runtime 必须传 `--resource-id` 与 `--image`。
+- 更新是窄更新，只提交明确给出的字段；不要用更新命令模拟 pause、resume 或验收。
+
+## 分配与运行控制
+
+```bash
+monkeys agent work assign existing <ID> --profile <Profile> --runtime-id <Runtime ID> --yes --output json
+monkeys agent work assign new <ID> --profile <Profile> --resource-id <Resource ID> --image <Image> --yes --output json
+monkeys agent work pause <ID> --profile <Profile> --reason @reason.md --output json
+monkeys agent work resume <ID> --profile <Profile> --prompt @prompt.md --output json
+monkeys agent work retry <ID> --profile <Profile> --reason @reason.md --yes --output json
+```
+
+分配与 retry 是 privileged 操作。调用前在聊天中说明 Profile、工作单 ID、目标 Runtime/Resource 和副作用；非交互执行必须由用户明确授权 `--yes`。
+
+## 对话、Spec 与验收
+
+```bash
+monkeys agent work conversation send <ID> --profile <Profile> --message @message.md --output json
+monkeys agent work spec approve <ID> --profile <Profile> --revision-id <Revision ID> --yes --output json
+monkeys agent work spec request-revision <ID> --profile <Profile> --revision-id <Revision ID> --feedback @feedback.md --output json
+monkeys agent work review approve <ID> --profile <Profile> --note @note.md --yes --output json
+monkeys agent work review request-changes <ID> --profile <Profile> --prompt @prompt.md --output json
+monkeys agent work delete <ID> --profile <Profile> --yes --output json
+```
+
+- Spec 操作必须使用详情返回的精确 `currentSpecRevisionId`，不得猜测或复用旧 Revision。
+- `spec approve`、`review approve` 会推进业务状态；`review approve` 还会释放 Runtime 绑定。执行前必须获得明确授权。
+- `delete` 是 destructive 操作，会删除工作单并释放绑定；只接受精确 ID 和明确 `--yes`。
+
+## 等待与聊天反馈
+
+```bash
+monkeys agent work wait <ID> --profile <Profile> --until terminal --output json
+monkeys agent work wait <ID> --profile <Profile> --until attention --output json
+monkeys agent work wait <ID> --profile <Profile> --until review --output json
+monkeys agent work watch <ID> --profile <Profile>
+```
+
+### 自适应呈现合同
+
+把 CLI 的结构化输出作为事实来源，不把原始 JSON 直接当作面向用户的回答。根据当前 Agent 和聊天界面已知且可靠的显示能力选择表达方式：可可靠渲染时使用简洁标题、卡片或小表格；能力有限时改用编号列表；纯文本环境使用短段落。不要假设表格、折叠区、颜色、图标、附件预览或可点击操作一定可用。
+
+无论采用哪种形式，都按以下信息优先级组织：
+
+1. 先说明结果摘要，例如总数、返回数、是否截断，以及当前是否需要用户处理。
+2. 把需要关注的工作单放在普通结果之前。
+3. 每个需要关注的工作单至少展示标题、工作单 ID、面向人的当前状态、已经完成的关键结果、风险或副作用，以及用户现在需要作出的具体决定。
+4. 只保留足以避免误操作的上下文，例如实际 Profile、Kernel Surface 和 `teamMode=none`；从当前命令结果读取这些值，不写死环境、租户、Runtime 或仓库。
+5. 只有用户要求技术详情或执行下一步必须依赖时，才补充原始状态码、Revision ID、Runtime ID、测试明细和错误恢复信息。
+
+把 `status`、`phase` 和 `attentionState` 组合成符合当前对话语言的自然表述；必要时在自然表述后保留原始枚举，禁止仅显示内部枚举让用户自行解释。默认隐藏 Request ID、Adapter、对象存储 URL、无关邮箱和完整响应；工作单 ID 以及当前操作所必需的精确 ID 不得隐藏。
+
+列表列数较多、单元格内容较长或界面能力未知时，不强行使用表格。创建或执行写操作前，用当前界面能稳定显示的方式回显 Profile、Kernel/`teamMode=none`、标题、类型、优先级、仓库与 Ref、分配方式及可能副作用，再等待对该精确操作的明确授权。
+
+- `until=attention`：`user_input_required`、`spec_approval_required` 或 `blocked`。
+- `until=review`：需要 Spec 审批或进入 `awaiting_acceptance`。
+- `watch` 使用 NDJSON，只在 `status/phase/attentionState` 变化时输出；Ctrl+C 只停止本地观察。
+- 遇到 `user_input_required`：在聊天中展示工作单 ID 和安全摘要，向用户索取决定。
+- 遇到 `spec_approval_required`：读取详情，报告 Spec Revision ID 与摘要，等待批准或修订意见。
+- 遇到 `awaiting_acceptance`：报告 Review Pack 的安全摘要和测试状态，等待验收决定。
+- 遇到 `failed`、`blocked` 或超时：报告最后状态、阶段、错误 code 和恢复建议，不自动 retry。
+
+## 结果未知
+
+任何写命令返回 `MUTATION_OUTCOME_UNKNOWN` 时：
+
+1. 明确告诉用户“请求可能已经生效”。
+2. 只运行错误中的 `agent work list/get` 恢复检查。
+3. 不自动重复创建、上传、分配、消息、审批、验收、retry 或 delete。
+4. 恢复读取仍无法确认时停止并请求用户决定。

package/skills/monkeys/references/authentication.md

@@ -0,0 +1,44 @@
+# 认证与上下文
+
+## 原则
+
+- 把 Deployment、Tenant、Team、Credential 共同视为不可变请求上下文。
+- 首次登录传订阅 `--url`；登录成功后，后续自动化都传服务端确认的租户 Profile。跨 Team 操作同时传 `--team`。
+- 用 `profile current/show/test` 和 `auth status/whoami` 核对上下文，不从名称猜测身份。
+- 私有部署可能配置私有 CA；由 Deployment 配置处理，不关闭 TLS 校验。
+
+## 配置顺序
+
+1. 浏览器登录使用 `monkeys auth login --url <Endpoint>`；CLI 自动创建 Endpoint 映射并打开浏览器。
+2. API Key 登录使用 `monkeys auth login --url <Endpoint> --api-key-stdin` 或 `--api-key-env <变量名>`。
+3. 登录成功后，CLI 读取已认证 `/api/configs` 的 `tenantId`，用它命名订阅/Profile 并设为当前 Profile。
+4. 后续用 `monkeys auth status --profile <tenantId> --output json` 与 `profile test` 验证身份和 Team。
+
+订阅 URL 是登录前唯一需要的上下文。CLI 用规范化 Endpoint 创建稳定的本地 Deployment 映射；在认证成功前只使用临时 Profile，成功后必须以服务端确认的 `tenantId` 重命名并设为当前订阅。不得用 URL 主机名、页面标题或用户输入猜租户名。
+
+浏览器 Session 和通过登录命令导入的 API Key 都写入系统 Keyring。API Key 不能进入命令参数、输出或 Profile 配置文件；无头 CI 应使用显式 `env:` Profile，而不是模拟浏览器登录。
+
+## Agent 发起浏览器登录
+
+CLI 和 Agent 都不得索要或处理账户密码。用户登录只发生在当前 Deployment 的浏览器页面。
+
+执行顺序：
+
+1. 发起不阻塞的授权，URL 必须是用户明确提供的订阅 Endpoint：
+
+   ```bash
+   monkeys auth login --url <Endpoint> --no-wait --output json
+   ```
+
+2. 将返回的 `verification_url` 原样交给用户，让用户在自己的浏览器登录。不得由 Agent 填写登录表单，不得修改 URL。
+3. 用户明确回复已完成后，用同一次响应中的 Device Code 和临时 Profile 完成登录：
+
+   ```bash
+   monkeys auth login --profile <临时Profile> --device-code <device_code> --output json
+   ```
+
+4. 命令成功返回 `subscription=<tenantId>`。运行 `monkeys auth status --profile <tenantId> --output json`，核对 Principal、Team、Surface、Context Fingerprint 和 `provider`；只报告非敏感摘要。
+
+Device Code 只用于返回它的临时 Profile、Endpoint 和当前一次短期授权，不得跨上下文复用。过期、拒绝、网络失败或结果未知时停止，不通过 Raw API 降级。
+
+`SESSION_PERSIST_FAILED` 表示浏览器授权已成功但 Session 未确认保存；修复 Store 后，只能在 Device Code 未过期时按 recovery 恢复轮询，不重新创建授权。`AUTH_PROFILE_UPDATE_FAILED` 表示 Session 已保存但 Profile 指纹更新失败，按 recovery 运行只读状态检查。`SESSION_STORAGE_PROBE_CLEANUP_FAILED` 表示预检条目未确认删除，必须停止登录并修复存储。

package/skills/monkeys/references/compatibility.md

@@ -0,0 +1,21 @@
+# 兼容性
+
+- 本 Skill 面向命令 Schema Major `1`，最低 CLI 版本 `0.10.0`。
+- 开始任务时运行 `monkeys version show --output json`。
+- CLI Major、命令 Schema Major 或 Skill 声明不兼容时停止写操作，升级匹配版本后再继续。
+- OpenAPI Snapshot 可动态刷新，但语义命令合同不会因刷新而被静默改写。
+- Data 合同由 Deployment 的 `data_contract=auto|ontology-v1|bucket-v1` 决定；`auto` 依次采用精确 OpenAPI、同一上下文缓存和有界只读探测。只有 Ontology 路由明确返回 404 时才探测旧 Bucket 路由。
+- 输出中的 `dataContractVariant` 和 `dataScope` 是当前请求的合同/作用域真相。认证、授权、网络、5xx 或响应不兼容不得触发合同切换，已发送写操作不得换合同重放。
+- Data 语义命令应显式传 `--perspective kernel|studio`；以输出中的 `requestedPerspective`、`effectivePerspective`、`perspectiveSource` 和 Perspective-aware `contextFingerprint` 判断视角。`legacy-unverified` 不能作为实际视角真相；不得根据 Profile 名称或请求参数猜测。
+- Data 输出中的 `teamMode=none|filter|context` 表示 CLI 是否施加 Team；只有存在 `effectiveTeamId` 时才能报告具体筛选/上下文 Team。Kernel 全局读取必须为 `teamMode=none`；可选 `resourceLocator.kind=ontology-resource-team`、`source=explicit-flag` 只表示 Ontology 数据资源定位，不改变 Team 模式。CLI 不从 owner Team 自动推导 locator。
+- 出现 Binding 漂移时按受控降级流程处理，不猜测 operationId。
+- Execution 列表可能适配 `legacy-list-v1` 或 `db-search-summary-v1`；以输出的 `contractVariant` 为诊断依据，只消费稳定字段。
+- Agent Work 优先使用部署 OpenAPI 的精确 method/path；OpenAPI 不可用时可使用 `agent-work-v1`、`agent-work-list-v1`、`agent-work-collection-v1` 等内置适配器。必须同时检查 `schemaSource`、`schemaFresh` 和 `adapter`，未知响应不得原样透传或猜字段。
+- Agent Work 固定为 Kernel Surface 和 `teamMode=none`。它与 Data Perspective 路由无关，权限不足不得切换 Studio，也不得把 Session `currentTeamId` 注入请求。
+- 不同部署可能不返回列表条目的 Team、Workflow 版本等可选字段。字段缺失时不得根据请求上下文或相似字段推断、补造。
+- `OPENAPI_UNAVAILABLE` 表示无法完成受控 Raw API 降级；停止降级并报告恢复建议，不得复用已过期 Evidence 或改为直接 HTTP。
+- Tool/Workflow/Plugin 的 capability 清单不是平台 OpenAPI；不要交给 `api call` 或 Operation Resolver。
+- Asset 媒体允许由 CLI 匿名读取公开 HTTPS 对象；匿名访问明确返回 401/403/404 时，必须由 Server `/api/medias/s3/presign-v2` 生成短期签名后重试。CLI 不持有存储签名密钥、不自行签名，也不得用普通 HTTP 或 Raw API 绕过失败。
+- View Feature 附件遵守相同边界：Feature Value 必须携带 View Scope 读取，附件 URL 只允许在 CLI 内存中用于公开匿名下载或 Server 预签名，不得写入聊天、Cursor、日志或结构化输出。
+
+Node.js 包要求 Node.js 22 或更高版本。独立分发包自带 Node.js，不依赖系统 Node.js。

package/skills/monkeys/references/data-governance.md

@@ -0,0 +1,24 @@
+# Data 初步治理
+
+## Ontology
+
+- `data ontology list` 用于发现可见、可创建或全部 Ontology；列表可见性不代表管理权限。
+- `data ontology get/create/update` 只使用声明了 Kernel Surface 的 Profile，并显式传 `--perspective kernel`。现有 Server 的 `get` 仍要求 `--team` 作为资源定位条件，但不得把它描述成 Kernel 查询作用域；`create/update` 按命令 Help 显式传目标/归属 `--team`。这些命令不得降级到 Studio。
+- Workspace Profile 被拒绝时不要自动换凭据或改走 Raw API。
+- Create/Update 前展示目标/归属 Team、Ontology ID、`dataContractVariant` 和字段级变更；Get 必须说明 Team 只是当前接口的定位参数，不得把 Session 当前 Team 描述成 Kernel 资源作用域。以服务端授权结果为准。
+- 使用 `data asset import-jsonl` 做服务端原生批量导入前，展示目标 Ontology、目标/归属 Team、导入模式、Asset/Tag/功能列开关与可选 Container View。保存返回的 `logId` 并以状态查询和目标数据读取共同验收。
+- 外部生成清单补充现有 Asset 时使用 `data asset feature-backfill`，必须提供包含稳定来源 ID 与目标 `assetId` 的映射 JSONL。需要保护更高质量来源时同时传 `--priority-file`；CLI 会用同一映射把优先来源解析为受保护目标 Asset，因此其他来源别名也不能覆盖该目标。先用完全相同的文件、Key、列名、优先源和样本筛选运行 `--dry-run`；未知优先来源、缺失映射、重复来源、重复未保护目标、非法图片/文本或缺失样本时停止。`data asset enrich-jsonl` 仅作为已弃用兼容入口保留；若结果含 `deprecation`，必须向聊天用户说明替代命令。
+- 首版没有 Ontology Delete。
+
+`data bucket list/get/create/update` 是旧入口，必须把输出中的弃用信息报告给用户。它可以委托到 Ontology 合同，但不得被理解为平台仍以 Bucket 为主模型。
+
+## Container 生命周期
+
+- `data container move`：改变现有 Membership/归属，先显示来源 View、目标 View、Asset ID。
+- `data container copy`：创建独立 Asset，保存返回的新 Asset ID。
+- `data container remove`：只把 Membership 移入 Trash，不删除 Asset 本体。
+- `data container trash list/restore`：先列出精确回收项，再做有界恢复；部分失败逐项报告。
+- `data view convert-to-container`：将普通 Filter View 的当前筛选结果快照转换为 Container View。Kernel Data 界面将它称为“转化为增强视图”；转换后会清除筛选逻辑，且无法撤销。它是非幂等后台治理任务，只有用户明确要求固化动态筛选结果时才能执行。
+- 转换前展示 Profile、Perspective、Team 模式、View ID、Ontology ID、当前筛选摘要和不可逆影响，并取得对该精确 View 的确认。筛选失败、返回为空、API 漂移或权限不足时不得把转换当作兜底。
+
+禁止通过 Raw API 把 Remove 替换成永久删除，禁止 Purge 和大范围清空。

package/skills/monkeys/references/data-perspective.md

@@ -0,0 +1,45 @@
+# Data 视角路由
+
+CLI 只提供确定性的 `--perspective kernel|studio` 断言和固定语义命令；路由策略由本 Skill 执行。现有 Server 的统一 Data 接口按当前 Session 是否具有 Kernel Scope 分流，CLI 不发送自定义视角 Header，也不能把同一个 Kernel Session 强制降权为 Studio。不得使用 `auto`，不得直接构造 `x-monkeys-data-perspective` Header。
+
+Team 与 Data Perspective 分开处理：Kernel 是租户内管理视角，Kernel 全局读取默认不传 `--team`；只有用户明确要求 Team 筛选时才传。Field、View、Feature Value、Advanced Asset Search 和 Asset Export 等需要下游数据资源 Team 时，使用用户或部署所有者已确认的 `--resource-team`；CLI 通过 `resourceLocator.source=explicit-flag` 报告，它不会改变 `teamMode=none`，不得描述成 Kernel 查询作用域。Ontology owner Team 与 data resource Team 可以不同，CLI 不会自动推导。Studio 的 Team 表示前台工作空间上下文。Session 的 `currentTeamId` 只是当前登录状态，不能据此宣称 Kernel 查询属于该 Team。
+
+## 决策顺序
+
+1. 用户明确要求 Studio/前台视角：不得先尝试 Kernel。先用 `auth status` 确认 Session：
+   - 从用户明确输入或 `session.currentTeamId` 确认 Studio Team；使用 Session Team 时必须说明结果受该 Team 与前台权限限制。
+   - 固定 Studio 入口（例如 `data ontology list --scope visible|creatable`）可直接使用 `--perspective studio`。
+   - 其他统一 Data 命令只有在 `session.surfaces.kernel=false` 时才能使用 `--perspective studio`。
+   - 若当前 Session 具有 Kernel Scope，必须告诉用户现有 Server 无法将该 Session 强制切到 Studio，并要求用户选择无 Kernel 权限的账户/Profile；不得假装已经切换。
+2. 用户明确要求 Kernel/后台/管理视角：使用 `--perspective kernel`；全局读取不传 `--team`，用户明确要求某 Team 时才把 `--team` 作为筛选条件；命令需要资源定位时传已确认的 `--resource-team`，未知时先在聊天中说明并请求，不得猜测；权限不足时报告错误，不得降级。
+3. 用户未指定视角：每个任务最多运行一次 `monkeys auth status --profile <Profile> --output json` 检查能力。
+   - `session.surfaces.kernel=true`：使用 `--perspective kernel`；全局读取默认不传 `--team`。
+   - 当前身份没有 Kernel Surface，但命令有 Studio 等价能力：必须先在聊天中明确告诉用户“当前账户没有 Kernel 管理权限，本次将使用 Studio 视角；结果受前台可见性和权限限制。”，再使用 `--perspective studio`。
+   - 当前身份没有 Kernel Surface，且命令没有 Studio 等价能力：停止并报告需要 Kernel 权限。
+
+最终答复必须引用 CLI 返回的 `effectivePerspective` 与 `teamMode`；存在 `effectiveTeamId` 时同时报告。存在 `resourceLocator` 时说明该 Team 仅用于 Ontology 子资源定位、没有把 Kernel 全局结果收窄为 Team 筛选。若 CLI 只返回 `perspectiveSource=legacy-unverified`，必须明确说明实际视角未经确认。使用 Studio 时必须说明结果受前台 Team、可见性与权限过滤；不得把 Studio 空结果解释为 Kernel 中也不存在。
+
+## 能力边界
+
+- Session 路由、Kernel 与 Studio 均有实现：View、Asset、Tag、Tag Group、Field List/Ensure、Feature Value。实际分支由 Session Kernel Scope 决定。
+- 固定 Studio 语义：`data ontology list --scope visible|creatable`。
+- 固定 Kernel 语义：`data ontology list --scope all`、`data ontology get/create/update/import`、`data asset import-jsonl` 及其 `status/cancel`、`data field get/update` 和其他命令明确标记的 Kernel 专有治理操作。
+- Skill 默认发现 Ontology 时，Kernel 路径使用 `data ontology list --scope all --perspective kernel` 且不传 Team；Studio 路径使用 `data ontology list --scope visible --perspective studio --team <Team ID>`。
+- Kernel Field List/Get、View Tree/Rows、Feature Value、Feature 附件、Advanced Asset Search 和 Asset Export 使用独立 `--resource-team`，不手工补 `--team`。`DATA_RESOURCE_TEAM_REQUIRED`、`DATA_TEAM_ROLE_CONFLICT` 或 `DATA_RESOURCE_TEAM_NOT_APPLICABLE` 时停止并在聊天中报告；不尝试 owner Team、Team `0`、Session Team、Raw API 或空结果重试。
+
+## 受控降级
+
+优先在业务命令前通过 `auth status` 选择视角，避免先发一次 Kernel 业务请求。只有以下条件全部满足，Skill 才能把一次失败的 Kernel 尝试改为 Studio：
+
+- 用户没有明确要求 Kernel；
+- 错误为 `DATA_KERNEL_PERMISSION_REQUIRED`；
+- `safeDetails.requestState=not_sent`；
+- 同一语义命令具有 Studio 等价能力；
+- 保持同一 Profile、Deployment、Tenant、Ontology 和精确目标；Kernel 全局查询不得凭 Session Team 补造筛选，切换 Studio 前必须确认 Team 并明确告知作用域收窄；
+- 执行 Studio 命令前已在聊天中告知用户。
+
+每个任务最多发生一次 Perspective 降级。空结果、404、认证过期、网络错误、5xx、合同或响应不兼容、`sent`、`result_unknown` 都不得触发 Perspective 降级。Perspective 降级与语义命令到 Raw API 的受控降级是两套独立机制，不得混用 `fallbackEligible`。
+
+`DATA_STUDIO_SESSION_REQUIRED` 表示当前 Kernel Session 会被统一接口路由到 Kernel，无法满足明确的 Studio 要求。停止并要求无 Kernel Scope 的账户/Profile，或改用固定 Studio 入口；不得改走 Raw API 伪造成功。
+
+`DATA_PERSPECTIVE_SESSION_INCOMPATIBLE` 表示 CLI 无法从认证 Session 确认实际能力。停止并报告认证合同问题，不得根据 Profile 名称猜测视角。

package/skills/monkeys/references/data-read.md

@@ -0,0 +1,34 @@
+# Data 读取
+
+## 选择命令
+
+- Ontology：`data ontology list`
+- Container/View：`data view tree`
+- View 完整行表：`data view rows`
+- Asset：`data asset list/search/get/sample`
+- Asset 媒体：`data asset media download`
+- View Feature 附件：`data asset attachment download`
+- Field：`data field list/get`
+- Feature Value：`data value get`
+- Tag/Tag Group：对应的 `list/get`
+
+## 流程
+
+1. 先按 Data 视角路由选择 `data ontology list --scope all --perspective kernel` 或 `data ontology list --scope visible --perspective studio --team <Team ID>`，解析明确的 Ontology。
+2. Kernel 全局读取默认不传 `--team`；只有用户明确要求某 Team 且命令支持筛选时才传。Field、View、Feature Value、Feature 附件和 Advanced Asset Search 需要后端资源 Team 时传已确认的 `--resource-team <数据 Team>`；不得从 Ontology owner `teamId`、Session 或空结果猜测。Studio 后续命令同时传明确的 `--team`、`--ontology <Ontology ID>` 和同一 `--perspective`，不传 `--resource-team`。
+3. 检查输出中的 `effectivePerspective`、`teamMode`、可选的 `effectiveTeamId` 和 `resourceLocator`；`teamMode=none` 表示 CLI 未施加 Team 上下文/筛选。`resourceLocator.source=explicit-flag` 和 `resourceLocator.teamId` 只说明后端分区定位，不得补造用户筛选。CLI 返回 `DATA_RESOURCE_TEAM_REQUIRED` 时在聊天中请求已确认的数据资源 Team，不得尝试 `0`。
+4. 用户要求“列出/查看某个 View 的数据”时，Kernel 默认使用 `monkeys data view rows --ontology <Ontology ID> --view <View ID> --resource-team <数据 Team> --limit 20 --perspective kernel --profile <Profile> --output json`；Studio 改用 `--team` 且不传 `--resource-team`。不要要求用户额外指定“完整列”，也不要先用紧凑 `data asset list` 代替。
+5. View 类型为 `filter` 且已经配置 Tag/Field 规则时，继续使用 `data view rows`，由 CLI 按当前部署合同解析 `allOf`、`anyOf`、`noneOf` 与启用的字段规则。临时按 Ontology 全局 Feature 的结构化值筛选时，读取[Ontology Feature 结构化检索](ontology-feature-search.md)，使用 `data asset search --expression-json/--expression-file`；其他临时条件仍以命令 Help 为准。筛选失败或结果为空时先核对上下文、View 类型和规则，禁止通过 `data view convert-to-container` 兜底。
+6. 依据返回的有序 `columns` 和 `rows` 在聊天中展示完整 Markdown 表格。列较多时按列分成多个表格，每个表都保留 Asset ID 和名称用于关联；不得静默省略列。附件单元格只显示“可下载”和数量，不显示 URL。
+7. 只有用户明确要求简略列表、资源元数据或低上下文投影时，才使用 `data asset list --view <View ID>`。默认单页有界；只有用户确实需要时扩大范围。
+8. 抽样使用 `data asset sample` 的有界样本，不自行无限翻页后随机。
+9. 只复用同一 Context、Data Perspective、Team 模式、Data 合同、Ontology、View 和查询生成的 Cursor；游标不匹配时重新查询。
+10. 用户需要读取、查看或保存 Asset 封面图片/媒体时，使用 `monkeys data asset media download <Asset ID> --ontology <Ontology ID> --out <本地路径> --perspective <kernel|studio> --profile <Profile> --output json`。`--source auto` 默认依次选择 `primaryContent.value`、`media`、`thumbnail`；需要特定来源时显式传 `--source`。
+11. 用户需要 View Feature 中的 PDF/文件时，使用 `monkeys data asset attachment download <Asset ID> --ontology <Ontology ID> --view <View ID> --field <Field ID 或唯一精确名称> --out <本地路径> --perspective <kernel|studio> --profile <Profile> --output json`。历史 Field 类型可能是 `img`，仍应按实际 Content-Type/文件内容称为 PDF 或附件，不要误称为图片。
+12. 下载成功后依据 CLI 返回的本地 `path` 展示或处理文件，并向用户报告来源 Field、大小和 SHA-256；不要把二进制正文塞入 JSON 或聊天文本。
+13. 两种下载都由 CLI 内部处理对象地址：公开 HTTPS 对象使用匿名、无身份 Header、无重定向、有界原子下载；对象明确返回 401/403/404 时，CLI 才请求 Server 生成短期签名并重试。CLI 不自行签名，任何规范或签名 URL 都不得进入结构化输出或聊天。网络错误、重定向、异常 Content-Type、超限或签名失败必须直接报告，不得使用普通 HTTP、Raw API 或手工 URL 兜底。
+14. 覆盖本地已有文件前必须得到用户对该精确路径的授权，并同时传 `--overwrite --yes`。默认最大 50 MiB；只有任务确有需要时才提高 `--max-bytes`，不得超过 1 GiB。
+
+参数和筛选条件始终以相应命令的 `--help` 为准。
+
+`visible` 只表示当前身份可以读取，不代表可以创建、更新或治理。`data bucket` 和 `--bucket` 只用于旧脚本/旧部署兼容；新任务不得优先使用。

package/skills/monkeys/references/data-transfer.md

@@ -0,0 +1,74 @@
+# Data 导入导出
+
+## 能力边界
+
+- Ontology 结构：`data ontology export/import`，固定使用版本化 JSON。结构包不包含 Asset 数据、附件二进制、签名 URL 或凭据。
+- Asset 数据：`data asset export/import`，默认 JSONL。只有用户明确要求时才传 `--format csv` 或 `--format xlsx`。
+- Server 原生后台导入：`data asset import-jsonl`，适合平台原生 JSONL 与持久任务进度，不等同于可迁移数据包导入。
+- 已有 Asset 的 Feature 回填：优先使用 `data asset feature-backfill`；它消费显式来源到目标映射，固定不创建 Asset，只回填一个图片列和一个文本列。`data asset enrich-jsonl` 是已弃用兼容入口。
+- 首版 Asset 导入只有 append/create。来源 ID 只用于报告映射，不能宣称保留目标 ID，也不能使用任意业务键 Upsert。
+- Ontology 导入只有 `create|merge`；merge 是非破坏性的，不删除目标端多余资源，不提供 replace。
+
+## Agent 操作流程
+
+1. 明确 Profile、Data Perspective、Ontology、owner Team、data resource Team 和可选 View。Kernel Asset Export 使用 `--resource-team` 定位 View/Field/Value 等读取，不用 owner Team 猜测；Asset Import 等写命令继续用 `--team` 指定目标数据 Team。Ontology 结构迁移只走 Kernel，`--team` 表示 Ontology 所有权/定位 Team，`--resource-team` 表示 View/Field/Tag 等资源 Team。
+2. 首次使用先查看对应命令 `--help`。不要把命令 Envelope 的 `--output json` 当成数据文件格式。
+3. 数据导出未指定 `--format` 时使用 `.jsonl` 输出；如果用户要求 CSV/XLSX，显式传同名格式和扩展名。格式与扩展名冲突时停止，不要改名后猜测重试。
+4. 覆盖本地文件前展示精确绝对路径，并仅在用户授权后同时传 `--overwrite --yes`。
+5. 先导入 Ontology 结构并保存真实 `--report`。包含 Field、Tag、View 引用的 Asset 文件必须把该报告作为 `--ontology-report`；dry-run 报告或部分失败报告不能作为映射依据。结构导入与 Asset 导入必须使用完全相同的 Profile、Credential Context、Perspective 和 data resource Team；Context Fingerprint 不同就停止，不能跨上下文复用报告。
+6. Asset 导入必须先运行同一输入、格式、Mapping、Profile、Perspective、Team、Ontology 和 Ontology report 的 `--dry-run`。向用户报告输入 SHA-256、总行数、计划数量和报告路径。
+7. 用户在看到 dry-run 摘要后明确批准，才以完全相同的参数移除 `--dry-run` 并加入 `--yes`。输入 SHA-256 或 Ontology report 变化时必须重新 dry-run。
+8. 返回目标 ID 映射、成功/失败数量和报告路径。退出码 9、结果未知或中断时明确告诉用户可能已有远端副作用，禁止整文件自动重放或自动删除成功资源。
+
+不要用一个命令根据文件名、行数或服务端能力在 `data asset import`、`data asset import-jsonl` 与 `data asset feature-backfill` 之间静默切换。三者的目标、写入语义、进度与恢复合同不同。
+
+## JSONL 默认
+
+```powershell
+monkeys data asset export --profile <Profile> --perspective kernel --ontology <Ontology ID> --resource-team <数据 Team> --out <file.jsonl> --output json
+
+monkeys data asset import --profile <Profile> --perspective <kernel|studio> --team <数据 Team> --ontology <Ontology ID> --ontology-report <ontology-report.json> --file <file.jsonl> --dry-run --output json
+```
+
+不要因为输入名为 `.csv` 或 `.xlsx` 就省略 `--format`。用户明确选择表格格式时才使用：
+
+```powershell
+monkeys data asset export --profile <Profile> --perspective kernel --ontology <Ontology ID> --resource-team <数据 Team> --format xlsx --out <file.xlsx> --output json
+```
+
+## 第三方表格 Mapping
+
+原生 CSV/XLSX 可直接往返。第三方表格必须提供明确 Mapping JSON，例如：
+
+```json
+{
+  "columns": {
+    "编号": "sourceId",
+    "名称": "asset.displayName",
+    "说明": "values.<Field ID>",
+    "标签": "tagSourceIds",
+    "忽略列": "ignore"
+  }
+}
+```
+
+Mapping 目标只允许 `asset.<字段>`、`values.<精确 Field ID>`、`sourceId`、`tagSourceIds`、`viewSourceIds` 或 `ignore`。自然语言列名不能被 Agent 猜成 Field ID；必须先查询并解析精确目标。原生 CSV/XLSX 的业务 Cell 使用 `json:<JSON>` 类型标记，即使原值是字符串也不要移除该标记；第三方表格需要复杂类型时也可显式使用该格式。
+
+## Ontology 结构迁移
+
+```powershell
+monkeys data ontology export <Ontology ID> --profile <Kernel Profile> --perspective kernel --team <Ontology 所有权/定位 Team> --resource-team <数据资源 Team> --out <ontology.json> --output json
+
+monkeys data ontology import --profile <Kernel Profile> --perspective kernel --team <目标 Ontology 所有权 Team> --resource-team <目标数据资源 Team> --file <ontology.json> --mode create --dry-run --output json
+```
+
+merge 必须显式传 `--target-ontology <目标 ID>`。真实结构导入通过 `--report <ontology-report.json>` 固定资源类型与来源/目标 ID 映射；后续 Asset 导入必须复用该报告。若完整分页无法证明、存在重复稳定键、悬空引用或匹配歧义，必须停止；不得切换 Raw API 绕过结构完整性检查。
+
+Ontology 全局 Asset 导出会遍历 View，默认合并多 View Membership 和可读 Feature Value；同一 Asset 只输出一条记录。若任一 View 分页不完整、Membership 找不到全局 Asset 或不同 View 返回冲突值，整次导出失败，不得改用残缺文件继续迁移。
+
+## 文件与附件边界
+
+- CSV/XLSX 首版最多 50,000 行、500 列，XLSX 输入最大 100 MiB、解压后最大 128 MiB、Shared Strings 最大 64 MiB；超过时改用默认 JSONL。
+- Ontology 映射报告最大 32 MiB。全局 Membership 导出使用磁盘分区；单分区超过 16 MiB 或 100,000 条时显式失败，应缩小到 View 作用域或拆分迁移，不得放宽内存门禁后自动重试。
+- XLSX 只使用 `data` 工作表，任何公式 Cell 都拒绝导入。
+- 本能力不打包图片、PDF 或其他附件二进制。附件仍按 Data 读取 Skill 使用专用下载命令处理。

package/skills/monkeys/references/data-write.md

@@ -0,0 +1,25 @@
+# Data 写入
+
+## 前置检查
+
+1. 明确 `--profile`、`--ontology` 和 `--perspective`，并检查输出中的 `effectivePerspective`、`teamMode` 与 `dataContractVariant`。Studio 写入必须明确 `--team`；Kernel 仅在命令 Help 要求目标/归属 Team 时传 `--team`，不得从 Profile 默认值或 Session 当前 Team 猜测。
+2. 先用读取命令把自然语言名称解析为精确 ID；多匹配时停止并让用户选择。
+3. 回显资源类型、精确 ID 和变化摘要，再执行写命令。
+
+## 能力
+
+- Asset：`create/update/delete`
+- Field：`ensure/update`；首版不提供 Field Delete
+- Feature Value：`set/batch-set`，批量最多 100 项
+- View：`create/update/delete`
+- Tag 与 Tag Group：`create/update/delete`，以及 `tag-group set-tags`
+- 服务端原生 JSONL：`data asset import-jsonl` 创建后台任务，`data asset import-jsonl status` 查询持久进度，`data asset import-jsonl cancel` 终止未完成任务
+- 现有 Asset 特征回填：`data asset feature-backfill` 将外部 JSONL 的一个图片 Key 和一个文本 Key 映射到精确目标 Asset；`data asset enrich-jsonl` 仅保留为已弃用兼容入口
+
+服务端原生 JSONL 导入固定使用 Kernel 视角、显式 Ontology 与目标/归属 Team。执行前先确认文件行数、模式、是否创建 Asset、是否写入 Tag/功能列及可选 Container View；结果必须保存 `logId`。状态为 `COMPLETED` 后仍需通过目标 Ontology 的 Asset 数量或精确源 ID 读取验证。取消只停止后续批次，已完成批次不会回滚。需要可迁移、可逐项报告的数据包时使用 `data asset import`。
+
+`data asset feature-backfill` 固定 `applyAssets=false`、`applyRelations=false`，只允许写一个图片列和一个文本列。执行前必须提供来源 ID 到目标 `assetId` 的映射文件并先运行 `--dry-run`；真实执行时保持输入 SHA-256、映射 SHA-256、筛选条件和列名不变。已有高质量结果需要优先保留时传 `--priority-file`：优先来源必须能通过同一映射解析目标，CLI 按最终目标 Asset 保护，因此其他来源别名也会被排除。预检同时报告 Asset Map 来源/目标/别名数量、选中与完整校验记录数、受保护目标数、`excludedByPriority` 和最终写入数。服务端返回 `logId` 后按同一导入状态命令等待完成，再读取两个 Feature Value 验收。若显式使用旧 `data asset enrich-jsonl`，必须把结构化 `deprecation.replacement` 告诉用户，不得把兼容入口继续推荐给 Agent。
+
+删除命令必须保留 CLI 的显式确认；非交互场景只有在用户已授权同一精确目标时才传 `--yes`。批量写入遇到退出码 9 时逐项报告成功和失败，禁止把整批自动重放。
+
+`--bucket` 是 Command Schema Major 1 内的弃用兼容别名。不要同时传 `--ontology` 和 `--bucket`，不要因合同错误自动换参数重放写操作。

package/skills/monkeys/references/fallback.md

@@ -0,0 +1,32 @@
+# 受控语义到 API 降级
+
+## 何时允许
+
+仅当语义命令结构化错误满足以下全部条件时降级：
+
+- `fallbackEligible` 为 `true`；
+- 错误 `safeDetails.fallbackEvidence` 存在；
+- 保持同一 Profile、Tenant、Team 和 Credential Context；
+- 错误属于无精确 Binding、Binding 歧义或响应合同不兼容，不是认证、授权、输入或确认错误。
+
+## 操作步骤
+
+1. 保存 `semanticAttemptId` 和 `fallbackEvidence`。
+   - Evidence 是签名的不透明值，有效期为 10 分钟；不得解码、编辑、拼接或跨 Credential 复用。
+2. 用 `monkeys api list/describe --profile ... --team ... --output json` 查看同一上下文的 OpenAPI。
+   - 若返回 `OPENAPI_UNAVAILABLE`，立即停止降级并报告错误与恢复建议；不得绕过 CLI 直接发送 HTTP。
+3. 只选择精确 `operationId`，或同时给出精确 Method 与 Path Template；不要模糊猜测相近写接口。
+4. 调用 `monkeys api call ... --fallback-evidence <值> --output json`。
+5. 核对输出中的语义尝试 ID、实际 Operation、Schema Digest 和请求 ID。
+
+## 写操作状态
+
+- `not_sent`：可在用户原授权范围内受控降级。
+- `sent` 或 `result_unknown`：禁止重放；先按资源 ID 或幂等键查询实际状态。
+- `read_failed`：只用于只读降级；不得据此重放写请求。
+
+写操作 Evidence 在 API 请求前即被一次性消费。即使 Raw API 调用失败，也不得再次使用同一 Evidence；先查询目标资源状态，再重新执行语义命令获得新的证据。
+
+不得复用已过期 Evidence。即使原语义命令仍可降级，也必须重新执行语义命令取得当前上下文的新 Evidence；不得在日志、文档或回答中记录 Evidence 原值。
+
+当平台没有对应语义命令时，Raw API 仍是显式专家能力：先用 `api list/describe` 验证 OpenAPI；只读调用可继续，写调用必须获得用户对精确 Operation 和目标的授权。绝不直接拼 HTTP。