@inf-monkeys-tech/monkeys-cli 0.10.0

package/skills/monkeys/references/ontology-feature-search.md

@@ -0,0 +1,81 @@
+# Ontology Feature 结构化检索
+
+本能力按 Ontology 全局 Feature Column 的结构化值确定性筛选 Asset。它不是语义、向量、description、模糊或全文搜索。
+
+## 使用前提
+
+- 使用 `data asset search`，不要新造命令、直接 HTTP 或直连 Data Server。
+- Feature 身份必须来自 `data field list` 返回的 `config.fieldKey`。
+- 不使用列的展示名、`id`、raw Column ID 或任何 `feature_*` ES path。
+- 当前只支持 Ontology-global Feature；带 `scopeContainerViewId` 的 View/container scoped Feature 不可用于本查询。
+- 写入通过 outbox/indexer 异步进入搜索索引，秒级写后不可见是允许的最终一致性行为。
+
+## Agent 执行流程
+
+1. 按[Data 视角路由](data-perspective.md)确定 `--perspective`。内部开发默认 Kernel；Kernel 全局查询默认不传 `--team`，用户明确要求 Team 筛选时才传。用户明确要求 Studio 时使用 Studio 和明确 Team。
+2. 查询目标 Ontology 的 Feature Column：
+
+   ```bash
+   monkeys data field list --profile <Profile> --perspective kernel --ontology <Ontology ID> --resource-team <数据 Team> --output json
+   ```
+
+   Kernel 下不要添加 `--team`；传已确认的 `--resource-team`。CLI 不会从 Ontology owner Team 自动推导；该 locator 不代表 Feature 查询被收窄到某个 Team。Studio 应改用明确的 `--team` 并移除 `--resource-team`。
+
+3. 从返回项读取 `config.fieldKey`、`type` 和 `scopeContainerViewId`。只选择 `fieldKey` 非空、Ontology-global 且类型受支持的列；多个同名展示列不能按名称猜测。
+4. 使用 `--expression-json` 或复杂条件优先使用 `--expression-file`，并在 Kernel 命令继续传同一 `--resource-team`。不要手工包装 `filterConfigV2.expression`；CLI 会完成适配。
+5. 读取结构化输出的 `items/total/cursor`、Perspective、Team 模式、Ontology 和 Context Fingerprint；只在相同查询条件下复用 Cursor。
+6. 如果查询紧邻本次 Feature Value 写入且首次为空，可以明确说明索引最终一致性，短暂等待后最多做一次有界重试。其他空结果必须按真实空结果报告。
+
+## Expression 合同
+
+Feature leaf：
+
+```json
+{ "op": "feature", "fieldKey": "status", "cmp": "eq", "value": "ready" }
+```
+
+组合条件：
+
+```json
+{
+  "op": "and",
+  "filters": [
+    { "op": "feature", "fieldKey": "status", "cmp": "eq", "value": "ready" },
+    { "op": "feature", "fieldKey": "score", "cmp": "gte", "value": 80 },
+    { "op": "feature", "fieldKey": "active", "cmp": "eq", "value": true }
+  ]
+}
+```
+
+Feature leaf 可以和 `and/or`、固定字段、`tagGroup`、`relation` 组合。单个 expression 参数与 `--filter-json/--filter-file` 可以同时使用，以保留其他高级查询条件；如果 filter 已经声明 `filterConfigV2.expression`，不得再传 `--expression-*`，CLI 会返回 `DATA_SEARCH_EXPRESSION_CONFLICT`。
+
+## 类型和比较符
+
+| Feature 类型                              | 比较符                                          | Value 形状                                   |
+| ----------------------------------------- | ----------------------------------------------- | -------------------------------------------- |
+| `string/text/select/single_select/enum`   | `eq`、`in`                                      | string 或 string array                       |
+| `number/int/integer/float/double/decimal` | `eq`、`in`、`gt`、`gte`、`lt`、`lte`、`between` | finite number 或 number array                |
+| `bool/boolean`                            | `eq`                                            | boolean                                      |
+| `date/datetime/timestamp/time`            | `eq`、`gt`、`gte`、`lt`、`lte`、`between`       | 服务端接受的规范日期时间 string 或范围 array |
+
+CLI 只校验 expression 公共结构和 JSON 标量形状。Feature 的真实类型、比较符匹配、日期规范和列作用域由服务端 Schema 校验；Agent 不根据示例值猜类型。
+
+## 明确不支持
+
+- semantic/vector/description/fuzzy/full-text Feature search
+- JSON/object/relation/image/file Feature 类型
+- View/container scoped Feature
+- Feature sort、aggregation、facet、exists 或 null predicate
+- Feature 与 `current_and_shared` 跨 Team 查询
+
+不要把固定字段 `relation` expression 与 Relation 类型 Feature 混淆；后者当前不支持。
+
+## 错误处理
+
+- `DATA_SEARCH_EXPRESSION_INVALID`：请求未发送。修正节点路径、op、fieldKey、cmp、value 或表达式上限。
+- `DATA_SEARCH_EXPRESSION_CONFLICT`：请求未发送。删除重复的 `filterConfigV2.expression` 或 `--expression-*` 之一。
+- `DATA_RESOURCE_TEAM_REQUIRED`：缺少已确认的数据资源 Team。停止并向用户请求 `--resource-team`；不得尝试 owner Team、`0`、Session Team、Raw API 或在空结果后补 Team 重试。
+- `DATA_TEAM_ROLE_CONFLICT` / `DATA_RESOURCE_TEAM_NOT_APPLICABLE`：`--team` 与 `--resource-team` 角色冲突，或当前不是显式 Kernel Ontology 读取。按 recovery 修正参数，不得改走 Raw API。
+- `HTTP_400`：重新读取 Feature Column，核对 `config.fieldKey`、类型、比较符、全局作用域和不支持边界。不得 Raw API 降级。
+- `HTTP_503`：Feature 搜索依赖的 ES/索引不可用。向用户明确报告服务暂不可用和 `retryable`；不得改为 PG EAV 扫描、Raw API、模糊搜索或其他静默兜底。
+- 空结果：先检查 Perspective、Team、Ontology、权限和真实查询条件；只有紧邻已确认写入时才按最终一致性做一次有界重试。

package/skills/monkeys/references/ontology-model.md

@@ -0,0 +1,43 @@
+# Ontology 领域模型
+
+## 核心对象
+
+- **Ontology**：Data 的规范顶层模型，定义数据作用域、Schema、权限与索引边界；它不是 Tenant 或 Team，也不只是传统意义上的“数据库”。`Bucket` 仅是旧部署兼容名称，新任务优先使用 Ontology。
+- **Asset**：Ontology 中的业务记录。Asset 全局存在，不代表它一定属于某个 View，也不代表 Studio 当前 Team 可见。
+- **Field / Feature Column**：字段或功能列定义；**Feature Value** 是某个 Asset 在相应字段上的值，读取时可能还需要 View Scope。结构化 Feature 检索只接受 Ontology 全局列的稳定 `config.fieldKey`，不能使用展示名、数据库 Column ID 或 ES path。
+- **Tag / Tag Group**：Ontology 内的分类标签及标签组，可参与 Filter View 和 Asset 搜索。
+- **View**：数据的查询、展示或成员组织范围，可以形成树。View 不是另一份独立的数据仓库。
+- **Membership**：Asset 与 Container View 之间的显式成员关系。一个 Asset 可以不属于任何 Container View，也可以属于一个或多个 View。
+
+## View 类型
+
+| 类型         | 含义                                    | 数据关系                               | 典型操作                                                           |
+| ------------ | --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------ |
+| `filter`     | 按 Tag 和字段规则动态查询的普通筛选视图 | 不复制 Asset，也不持有显式 Membership  | 配置筛选后用 `data view rows` 读取；临时条件用 `data asset search` |
+| `container`  | 显式维护 Asset Membership 的容器视图    | 保存成员关系，可移动、复制、移出和恢复 | `data container move/copy/remove/trash`                            |
+| `share_link` | 指向共享目标的快捷入口                  | 不等同于 Filter 或 Container           | 先解析目标和权限，再读取                                           |
+
+## “增强视图”必须消歧
+
+- 在 **Kernel Data** 界面中，“增强视图”对应 `Container View`。
+- 在 Workflow/工作台上下文中也可能出现名为“增强视图”的页面能力，它与 Data Container View 无关。
+- 用户说“增强视图”时，先确认其所在模块、Ontology 和 View；不得仅按中文名称执行转换。
+
+## Filter View 与标签筛选
+
+- 已配置筛选规则的 Filter View 使用 `data view rows --ontology <ID> --view <ID>`；CLI 会按部署合同处理 Tag 的 `allOf`、`anyOf`、`noneOf` 和启用的字段规则。
+- 用户提出临时 Tag/Field 条件而不修改 View 时，使用 `data asset search`。按 Feature Value 精确筛选时先用 `data field list` 读取 `config.fieldKey`，再按[Ontology Feature 结构化检索](ontology-feature-search.md)构造 expression；筛选结构以当前命令 Help 和 Schema 为准。
+- 查询不到数据时，先检查 Perspective、Team、Ontology、View 类型、筛选规则、Tag/Field ID 和权限。不要把“转成增强视图”当作筛选故障的解决方法。
+
+## Filter 转 Container 是高风险治理操作
+
+`data view convert-to-container` 会把 Filter View 当前匹配结果快照为显式 Membership，随后清除筛选逻辑，且无法撤销；它是非幂等的后台治理任务，不是普通查询或筛选命令。
+
+只有用户明确要求把动态筛选视图固化为 Container View 时才能执行。执行前必须展示并确认 Profile、Perspective、Team 模式、Ontology、View、当前筛选摘要和不可逆影响。筛选读取失败、返回为空、API 漂移或权限不足时一律不得自动转换。
+
+## Kernel 与 Studio 可见性
+
+- 内部开发任务默认由 Skill 显式选择 Kernel；Kernel 全局读取没有用户 Team 作用域，显式 `--team` 只用于用户明确筛选。Ontology 子资源需要后端数据资源 Team 时传已确认的 `--resource-team`；owner Team 与 data resource Team 可以不同，Agent 和 CLI 都不得猜测。
+- Studio 结果受当前账户和 Team 可见性限制；用户明确要求 Studio 时必须遵守。
+- Kernel 权限不足且用户未指定视角时，Skill 只有在存在等价 Studio 操作并先在聊天中告知范围收窄后，才可显式降级。
+- 后台能找到 Asset、前台某个 View 找不到，常见原因是 Studio 权限或 Membership/Filter 条件不同，不代表 Asset 不存在。

package/skills/monkeys/references/platform-overview.md

@@ -0,0 +1,29 @@
+# 平台能力地图
+
+本文件随官方 Skill 安装，不依赖本地 Git 仓库。它用于理解平台领域和选择命令；具体命令与参数始终以当前 CLI 的 `--help` 和命令 Schema 为准。
+
+## 当前语义命令覆盖
+
+| 平台领域        | 主要对象与用途                                              | CLI 入口                                   | 深入指南                           |
+| --------------- | ----------------------------------------------------------- | ------------------------------------------ | ---------------------------------- |
+| 上下文与认证    | Deployment、Profile、Tenant、Session、API Key、Team         | `deployment`、`profile`、`auth`、`context` | `authentication.md`                |
+| 自动化执行      | Workflow 定义、Execution 运行记录、输入输出文件             | `workflow`、`execution`、`file`            | `workflow-execution-files.md`      |
+| Agent Work      | Kernel Agent Console 的工作单、分配、对话、审批、运行与验收 | `agent work`                               | `agent-work.md`                    |
+| Data / Ontology | Ontology、View、Asset、Field/Value、Tag、导入导出与治理     | `data`                                     | `ontology-model.md` 及各 Data 指南 |
+| Kernel 配置     | System Config 的发现、读取、窄更新、校验与历史              | `config`                                   | `system-config.md`                 |
+| 通用 API        | 语义命令暂未覆盖或发生兼容漂移时的受控兜底                  | `api list/describe/call`                   | `fallback.md`                      |
+
+## 覆盖边界
+
+- 语义命令覆盖的是 Agent 高频、可建立安全合同的能力，不等于 Kernel/Studio 界面中的全部导航模块。
+- Applications、Models、Identity、Billing 等领域若没有对应语义命令，先用 `monkeys --help` 与领域 Help 确认；不要因为界面存在入口就臆造 CLI 命令。
+- 只有满足受控降级条件时，才通过 CLI 的 `api list/describe/call` 使用 Server OpenAPI。仍然不得直接发送 HTTP。
+- CLI Help 是命令和参数真相；本 Skill 保存稳定领域语义、安全边界和操作路线，不复制易漂移的完整 API 文档。
+
+## 常见概念定位
+
+- “工作流/运行记录”进入 Workflow / Execution，不要与 Agent Work 工作单混淆。
+- “Agent Console/工作单/Spec 审批/验收”进入 Agent Work；它是 Kernel-only，且没有 Team 作用域。
+- “数据仓库、数据集、视图、标签、字段、记录、增强视图”通常进入 Data / Ontology；先读 `ontology-model.md`。
+- “平台设置中的 Key/配置项”进入 Kernel System Config，不是本地 CLI 配置。
+- 同名词可能跨模块复用。必须结合用户所在界面和对象 ID 判断领域，不能只按中文名称猜命令。

package/skills/monkeys/references/safety-errors.md

@@ -0,0 +1,24 @@
+# 安全与错误
+
+## 结构化错误
+
+始终使用 `--output json`，读取 `error.code`、`retryable`、`fallbackEligible`、`recovery` 和 `safeDetails`。按退出码分类：
+
+- 1 输入校验；2 配置；3 认证；4 授权；5 网络；6 API；7 缺少确认；8 兼容性；9 部分成功；10 内部错误。
+
+只有 `retryable=true` 且操作本身安全或带稳定幂等键时才有限重试。退出码 3/4/7 不得通过 Raw API 绕过。
+
+`DATA_RESOURCE_TEAM_REQUIRED` 表示 Kernel Ontology 读取缺少已确认的 data resource Team；`DATA_TEAM_ROLE_CONFLICT` 表示同时传了用户筛选/上下文 `--team` 和资源定位 `--resource-team`；`DATA_RESOURCE_TEAM_NOT_APPLICABLE` 表示把 locator 用在 Studio、legacy perspective 或旧 Bucket。三类错误都发生在请求前。不得硬编码 `0`、使用 owner Team 或 Session Team 猜测、切换 Studio、调用 Raw API或等业务空结果后重试；应向用户报告 Ontology ID、错误和 recovery。
+
+## Secret 与输出
+
+- CLI 和 Agent 都不得索要或接收账户密码；账户认证只在 Deployment 浏览器页面完成。
+- API Key 只从 stdin 或环境变量读取，不把 Secret 写进 CLI 参数、JSON 参数、临时文件、持久环境变量、输出或回答。
+- Keyring 只保存 API Key 或服务端签发的 Session Token；Device Code 和授权 URL 只能用于当前短期授权，不得跨临时 Profile 或 Endpoint 复用。
+- Keyring 不可用时停止登录并明确报告，不得在浏览器授权后静默切换 Store。
+- 不回显服务端响应中的 Token、Cookie、Authorization 或类似字段。
+- 不用 `--header` 覆盖 Authorization、Tenant、Team、Host 等受保护 Header。
+
+## 高风险操作
+
+确认必须绑定精确 Profile、Team、Bucket、资源 ID 和操作。`--yes` 只代表当前精确命令已获授权，不得复用为后续或扩大范围的授权。

package/skills/monkeys/references/system-config.md

@@ -0,0 +1,64 @@
+# System Config
+
+## 上下文与作用域
+
+- 只使用 `expectedSurfaces` 包含 Kernel 的明确 Profile；所有命令显式传 `--profile` 和 `--output json`。
+- System Config 作用域是当前 Deployment/Tenant/Environment。Team 仅是身份上下文；`--team` 不会把配置缩小为 Team 级。
+- 先运行 `config overview`，核对返回的 `deployment`、`tenant`、`configurationScope`、`contextFingerprint` 和 Active Version。
+
+## 发现与只读操作
+
+先发现 Key，再精确读取；禁止猜 Key：
+
+```bash
+monkeys config list --profile <Profile> --prefix <Prefix> --output json
+monkeys config get <Exact.Key> --profile <Profile> --output json
+monkeys config validate --profile <Profile> --output json
+monkeys config history --profile <Profile> --limit 20 --output json
+```
+
+`config list` 只返回 Schema 元数据，不返回全部当前值。`config validate` 只校验当前线上配置，不校验待写入候选值。历史输出是有界摘要，不包含完整版本配置。
+
+## 单 Key 写入
+
+先执行 `--dry-run`，向用户展示精确 Key、脱敏后的 before/after、Active Version 和 `restartRequiredKeys`；获得当前操作授权后才添加 `--yes`：
+
+```bash
+monkeys config set <Exact.Key>=<Value> --profile <Profile> --dry-run --output json
+monkeys config set <Exact.Key>=<Value> --profile <Profile> --yes --output json
+```
+
+复杂值使用 `--value-json '<JSON>'` 或 `--value-json @<File>`。敏感 Key 不得使用 `key=value`、`--value-json` 或 Patch 文件，只能把本次值经 stdin 送入：
+
+```bash
+monkeys config set <Sensitive.Key> --profile <Profile> --value-stdin --yes --output json
+```
+
+不得回显敏感值或 Mask 占位符，不得把 Secret 写入参数、文件或持久环境变量。
+
+## 多 Key 窄更新
+
+`config patch` 只接受 1–50 个精确、非重复、非只读、非敏感 Schema Key：
+
+```json
+{ "patches": [{ "key": "server.example.enabled", "value": true }] }
+```
+
+```bash
+monkeys config patch --profile <Profile> --input @patch.json --dry-run --output json
+monkeys config patch --profile <Profile> --input @patch.json --yes --output json
+```
+
+Patch 只发送列出的 Key，不替换整份配置。CLI 没有服务端 CAS；写后若报告并发基线变化，必须人工复核同 Key 是否被覆盖。
+
+## 导出与故障恢复
+
+```bash
+monkeys config export --profile <Profile> --out config.json --output json
+```
+
+导出会依据当前 Schema 再次脱敏全部敏感 Key，但文件仍按内部配置资料保护。默认拒绝覆盖；确需覆盖时同时使用 `--overwrite --yes`。
+
+若写操作返回 `MUTATION_OUTCOME_UNKNOWN`、`requestState=sent` 或 `result_unknown`，禁止自动重试；运行 `config get <Exact.Key>` 和 `config history` 核查。认证、授权、确认、只读 Key、未知 Key 与输入错误不得通过 Raw API 绕过。
+
+当前语义层不提供 replace、import、rollback、unset/reset 或 Design Token Preview；不得用 Raw API 擅自补做这些高风险能力。

package/skills/monkeys/references/workflow-execution-files.md

@@ -0,0 +1,44 @@
+# Workflow、Execution 与文件
+
+## Workflow
+
+- 先用 `workflow list/get` 解析精确 Workflow ID 和版本。
+- `workflow list` 顶层的 `effectiveTeamId` 表示本次请求使用的 Team；条目中的 `ownerTeamId` 表示资源归属 Team。两者不同不代表 CLI 切换了上下文。
+- 依据 `accessScope` 判断可见性：`team-owned` 是当前 Team 资源，`builtin-cross-team-readonly` 是可跨 Team 读取的内置资源，`cross-team-visible-unknown` 只表示服务端返回了其他 Team 资源，不能据此推断可写。
+- `isBuiltin` 和 `accessScope` 都不能替代服务端授权；跨 Team 可见资源默认只读，写操作必须依赖明确的服务端授权结果。
+- Workflow 提供 `create/import/update/delete` 完整写入语义。所有写命令必须使用明确的 Workspace `--profile`、`--team` 和精确文件或 ID；先运行同一输入的 `--dry-run`，用户确认精确目标后才传 `--yes`。
+- `workflow create --file <definition.json>` 只接受完整 canonical `WorkflowDefinition`，目标 ID 已存在时拒绝覆盖。
+- `workflow import --file <package.json> --mode create` 只接受严格的 `{workflows:[单个定义],pages:[]}`；不支持 page 绑定、upsert 或批量导入。
+- `workflow update <workflowId> --file <definition.json>` 是完整定义的直接修改，不使用 ETag、`If-Match` 或额外并发版本头。路由 ID、Team 和 Creator 必须与当前资源一致；真实写入前 CLI 保存快照，写后回读验证。`revision.recordVersion` 是 Workflow 定义自身字段，不是 CLI 并发令牌。
+- `workflow delete <workflowId>` 只删除一个精确 ID。必须先 dry-run、向用户回显 Profile/Team/ID，再获得 destructive 确认；真实删除前保存快照，删除后确认资源已不可读取。不要把可读的跨 Team 或内置资源视为可删除。
+- Workflow 写操作要求当前部署发布的新鲜 OpenAPI 合同；Binding 缺失、合同过期、写结果未知或写后回读失败时立即停止，禁止 Raw API 降级和自动重放。
+- 用 `workflow run <workflowId> --input-json ... --output json` 异步启动，并保存返回的 Execution ID。
+- 需要安全网络重试时传调用方生成且稳定的 `--idempotency-key`；不要为同一业务操作反复生成新键。
+
+## Execution
+
+- 用 `execution get/list` 查询。
+- `execution list` 的 `contractVariant` 用于标识 CLI 实际适配的服务端列表合同；当前可能为 `legacy-list-v1` 或 `db-search-summary-v1`。Agent 应消费稳定字段，不按具体部署的原始响应猜结构。
+- 顶层 `effectiveTeamId` 表示请求上下文。列表条目缺少 `teamId`、Workflow 版本等可选字段时，保持缺失；禁止用请求 Team、默认值或其他字段补造。
+- 需要终态结果时用 `execution wait <executionId>`，设置有限超时。
+- `execution get/wait` 会把旧 DTO 与 Conductor 详情合同归一为稳定的 `workflowInstanceId`、`workflowId`、`workflowVersion` 和 `status`；`teamId` 等上游未返回的元数据保持缺失。
+- Execution 失败时先读顶层 `reasonForIncompletion`，再检查 `tasks[]` 中非成功状态的 `referenceTaskName`、`taskDefName`、`status`、`retryCount`、`reasonForIncompletion` 与 `outputData.errMsg`。仅复述服务端实际返回的诊断；字段为空时明确说明上游未提供，不推测原因。
+- 需要状态流时用 `execution watch <executionId>`；按 NDJSON 逐行消费，不等待整个输出结束。
+- Ctrl+C 后保留 Execution ID；中断本地等待不等于终止远端执行。
+
+## 后置审查 Job 审计
+
+- 用 `post-review list` 查询当前有效 Team 的后置审查 Job；用 `post-review get <jobId>` 查询一个精确 Job。两者都是只读命令，不提供重试、重放、取消或删除。
+- 列表可按来源或审查 Workflow ID（`--workflow`）、来源 Execution（`--source-execution`）、审查 Execution（`--review-execution`）、重复的 `--status`、重复的 `--policy` 和 Job 创建毫秒时间范围筛选。服务端最大分页为 100。
+- `post-review list/get` 依赖当前部署发布的 `postReview.audit.list/get` OpenAPI Operation；合同不存在或响应不兼容时立即停止，不猜测原始响应，也不降级为通用 `SYSTEM` Execution 查询。
+- 顶层 `effectiveTeamId` 与 `contextFingerprint` 是本次请求的有效上下文。审计结果只包含该 Team 的来源 Job；Job 或 Execution ID 只是关联数据，不能作为跨 Team 授权依据。
+- `reviewExecution.detailAccessible` 仅表示当前 Team 是否能继续读取审查 Execution 详情。为 `false` 时保留状态摘要，不要尝试绕过权限读取详情。
+- Job 在审查 Execution 创建或启动前也可能已经存在，此时 `reviewWorkflowInstanceId` 和 `reviewExecution` 缺失属于正常状态；使用 `status`、`attempts`、`nextRetryAt` 与 `lastError` 判断当前进度。
+- `resultVisibility` 为 `VISIBLE` 或 `REDACTED`；`reason`、`lastError` 与执行摘要均为服务端清洗后的审计字段，不要据此推断或请求未返回的原始配置、输入、输出或凭据。
+
+## 文件
+
+- 上传前运行 `file upload --help`，显式提供本地文件和目标 Key。
+- 下载使用临时文件完成后再替换目标；覆盖现有文件必须明确确认。
+- 使用 CLI 返回的大小和 SHA-256 做审计，不把二进制正文塞入 JSON 输出。
+- `file download` 面向已知存储 Key；Data Asset 只有 URL 时不要把 URL 猜成 Key，改用 `data asset media download`，由 Server 生成短期签名后匿名下载。