@inf-monkeys-tech/monkeys-cli 0.12.12 → 0.12.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inf-monkeys-tech/monkeys-cli",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "packageManager": "bun@1.3.14",
   "description": "Monkeys command-line client for AI agents, automation, and interactive use",
   "type": "module",
@@ -48,6 +48,15 @@
     "commands": "./dist/commands",
     "topicSeparator": " ",
     "topics": {
+      "user": {
+        "description": "Manage Kernel platform users and their direct group memberships"
+      },
+      "group": {
+        "description": "Manage Kernel permission groups, direct members, and permission sets"
+      },
+      "permission": {
+        "description": "Discover the Kernel permission catalog"
+      },
       "dev-agent": {
         "description": "Manage Dev Agent Work"
       },
@@ -134,5 +143,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "monkeysReleaseCommit": "8656177d047df3ae76d2635ab62694d2e3772d22"
+  "monkeysReleaseCommit": "f3bb1c9de08289ab9bdc646641d9e7deed5f5f9b"
 }

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

@@ -8,12 +8,12 @@ Data 查询视角由 CLI 根据经过认证的 Session 能力统一解析，Skil
 2. 用户明确要求 Kernel/后台/管理视角：传 `--perspective kernel`，直接查 Kernel。权限不足时报告 `DATA_KERNEL_PERMISSION_REQUIRED`，不得降级到 Studio。
 3. 用户未指定视角：省略 `--perspective`。
    - Session 有 Studio 权限时先查 Studio。
-   - Studio 返回确定性的空集合，或精确 GET 资源返回 404，并且 Session 同时有 Kernel 权限时，CLI 最多自动升级一次到 Kernel。
+   - 只有受支持的精确 GET 资源返回 404，且 Session 同时有 Kernel 权限时，CLI 才最多自动升级一次到 Kernel；空集合不会升级。
    - Session 只有 Kernel 权限时直接查 Kernel。
    - 401/403、认证过期、网络错误、5xx、合同/响应不兼容、校验失败及其他不确定错误均不得触发升级。
 4. 写操作不会因失败或结果形态自动重放到另一个视角。治理命令和 `visible|creatable|all` 等固定语义入口仍受命令自身声明的可用视角约束；不支持所选视角时报告 `DATA_PERSPECTIVE_UNAVAILABLE`，不得换用 Raw API 伪造等价能力。
 
-这套合同与 Lark CLI 的身份解析原则一致：显式选择优先于默认选择，命令声明支持的身份范围，最终解析结果进入结构化输出；Monkeys 额外只为确定性的只读空结果提供 Studio 到 Kernel 的一次升级。
+这套合同与 Lark CLI 的身份解析原则一致：显式选择优先于默认选择，命令声明支持的身份范围，最终解析结果进入结构化输出；Monkeys 仅为受支持的精确 GET 404 提供一次 Studio 到 Kernel 的升级，不对搜索或聚合结果自动扩大范围。
 
 ## 输出与审计
 
@@ -23,10 +23,10 @@ Data 查询视角由 CLI 根据经过认证的 Session 能力统一解析，Skil
 - `effectivePerspective`：实际返回结果的视角；
 - `perspectiveSource`：`explicit`、`fixed-route` 或 `studio-first`；
 - `perspectiveResolution.attempts`：按顺序记录 `studio|kernel` 和 `success|empty|not_found`；
-- `perspectiveResolution.fallbackReason`：只有实际升级时才出现，为 `studio_empty` 或 `studio_not_found`；
+- `perspectiveResolution.fallbackReason`：只有实际升级时才出现，为 `studio_not_found`；
 - `teamMode`、可选的 `effectiveTeamId` 与 `resourceLocator`。
 
-使用 Studio 返回结果时，说明结果受前台 Team、可见性与权限过滤。发生自动升级时，明确说明 Studio 的确定性空结果/精确资源不存在，以及最终数据来自 Kernel。没有 `fallbackReason` 时，不得宣称发生过升级。
+使用 Studio 返回结果时，说明结果受前台 Team、可见性与权限过滤。发生自动升级时，明确说明 Studio 的精确资源不存在，以及最终数据来自 Kernel。没有 `fallbackReason` 时，不得宣称发生过升级。
 
 ## Team 与资源定位
 
@@ -45,6 +45,6 @@ Team `0` 的 Ontology 可以作为共享 Schema 被其他 Team 复用，因此 `
 ## 能力边界
 
 - 双视角查询：View、Asset、Tag、Tag Group、Field List/Get、Feature Value 等统一 Data 读取。
-- 固定 Studio 语义：`data ontology list --scope visible|creatable`。
+- 固定 Studio 语义：`data ontology list --scope visible|creatable`、`data asset aggregate`；后者还要求部署公开稳定的聚合 Operation，不因缺少绑定或 HTTP 错误改查 Kernel。
 - 固定 Kernel 语义：`data ontology list --scope all`、`data ontology get/create/update/import`、`data asset import-jsonl` 及其 `status/cancel`，以及其他命令明确标记的 Kernel 专有治理操作。
 - `pageInfo.nextPageToken` 会绑定查询上下文并记录实际视角；Studio 首次升级到 Kernel 后，下一页直接延续 Kernel，不重新把 Kernel 的服务端游标发给 Studio。

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

@@ -6,6 +6,7 @@
 - Container/View：`data view tree`
 - View 完整行表：`data view rows`
 - Asset：`data asset list/search/get/sample`
+- 服务端通用统计：`data asset aggregate`，只支持已发布该 Operation 的 Studio Ontology/View 合同；详见[字段投影与聚合](ontology-feature-search.md)。
 - Asset 媒体：`data asset media download`
 - View Feature 附件：`data asset attachment download`
 - Field：`data field list/get`
@@ -16,7 +17,7 @@
 
 1. 用户明确要求 Kernel 时用 `data ontology list --scope all --perspective kernel`；明确要求 Studio 时用 `data ontology list --scope visible --perspective studio --team <Team ID>`。`visible|creatable|all` 是固定语义入口，不在它们之间自动改写。目标 Ontology 已知、用户未指定视角时，后续双视角查询省略 `--perspective`，由 CLI 执行 Studio-first。
 2. Kernel 全局读取默认不传 `--team`；只有用户明确要求某 Team 且命令支持筛选时才传。Field、View、Feature Value、Feature 附件和 Advanced Asset Search 需要后端资源 Team 时传已确认的 `--resource-team <数据 Team>`；不得从 Ontology owner `teamId`、Session 或空结果猜测。已确认目标位于共享/系统数据分区时，直接分区查询传 `--team 0`，子资源定位传 `--resource-team 0`。明确 Studio 时传 `--team` 且不传 `--resource-team`；自动模式可携带已确认的 `--resource-team` 供 Kernel 升级后定位，Studio 尝试不会把它当作 Team 上下文。
-3. 检查输出中的 `requestedPerspective`、`effectivePerspective`、`perspectiveResolution`、`teamMode`、可选的 `effectiveTeamId` 和 `resourceLocator`。`teamMode=none` 表示 CLI 未施加 Team 上下文/筛选；`resourceLocator` 只说明后端分区定位。`perspectiveResolution.fallbackReason` 为 `studio_empty|studio_not_found` 时，说明 Studio 已确定为空/不存在且最终结果来自 Kernel；其他错误不得由 Skill 手工换视角重试。CLI 返回 `DATA_RESOURCE_TEAM_REQUIRED` 时请求已确认的数据资源 Team；不得把 `0` 当默认兜底。
+3. 检查输出中的 `requestedPerspective`、`effectivePerspective`、`perspectiveResolution`、`teamMode`、可选的 `effectiveTeamId` 和 `resourceLocator`。`teamMode=none` 表示 CLI 未施加 Team 上下文/筛选；`resourceLocator` 只说明后端分区定位。`perspectiveResolution.fallbackReason=studio_not_found` 时，说明受支持的 Studio 精确 GET 资源返回 404 且最终结果来自 Kernel；空集合不会升级，其他错误不得由 Skill 手工换视角重试。CLI 返回 `DATA_RESOURCE_TEAM_REQUIRED` 时请求已确认的数据资源 Team；不得把 `0` 当默认兜底。
 4. 用户要求“列出/查看某个 View 的数据”且未指定视角时，使用 `monkeys data view rows --ontology <Ontology ID> --view <View ID> --resource-team <已确认的数据 Team> --page-size 20 --subscription <Subscription> --output json`；CLI 会把复合查询整体固定在一个视角，必要时从头用 Kernel 重查，避免混合两侧数据。明确 Studio 时改用 `--team` 且不传 `--resource-team`；明确 Kernel 时补 `--perspective kernel`。不要要求用户额外指定“完整列”，也不要先用紧凑 `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。

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

@@ -65,11 +65,57 @@ CLI 只校验 expression 公共结构和 JSON 标量形状。Feature 的真实
 - 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
+- 任意关系遍历、多维 facet、exists 或 null predicate；标量 sort/select 与单维 aggregate 见下文，不能据此推断其他能力已经存在。
 - Feature 与 `current_and_shared` 跨 Team 查询
 
 不要把固定字段 `relation` expression 与 Relation 类型 Feature 混淆；后者当前不支持。
 
+## 最小字段投影与排序
+
+部署支持语义 `sort/select` 时，通过 `data asset search --filter-file <文件>` 指定 `viewId`、`sort` 和 `select`。普通 Studio 语义查询必须提供已确认的 Ontology 与可读 View；`--team` 只作为认证上下文，不在查询 JSON 中重复添加 `teamId`。自动视角携带的 `--resource-team` 不会注入 Studio advanced-search Body；Kernel 的显式资源定位规则不变。
+
+```json
+{
+  "viewId": "<view-id>",
+  "sort": { "field": { "kind": "feature", "fieldKey": "score" }, "order": "desc", "missing": "last" },
+  "select": [
+    { "field": { "kind": "builtin", "name": "name" }, "alias": "name" },
+    { "field": { "kind": "feature", "fieldKey": "score" }, "alias": "score" }
+  ]
+}
+```
+
+指定字段后，`items` 中每项为 `{ "assetRef": { "id": "...", "teamId": "...", "ontologyId": "..." }, "values": { "name": "...", "score": 0 } }`。身份与别名值分层保留，`null`、`0`、`false` 不代表字段丢失。不要套用普通 Asset 顶层 `id/name` 解析，也不要补拉完整 Asset。`select` 不与 `--compact` 同用；CLI 在请求前明确拒绝，防止丢失已选择的值。
+
+沿用统一 `--page-size/--page-token/--page-all/--page-limit`。变更 View、条件、select、排序、缺失值策略或 Context 后，必须从第一页开始。
+
+## 服务端通用聚合
+
+先查看 `monkeys schema data asset aggregate`。该命令只支持 `ontology-v1` 和 Studio，并要求 `--ontology`、`--view` 与 `--input-file` 或 `--input-json`。不要传 `--bucket`、`--resource-team`、输入 `teamId` 或 `timeoutMs`，也不要把 search 的 `filterConfigV2` 包装复制进聚合输入。
+
+```bash
+monkeys data asset aggregate --ontology <ontology-id> --view <view-id> --input-file aggregate.json --subscription <Subscription> --output json
+```
+
+`aggregate.json` 使用现有通用合同，例如：
+
+```json
+{
+  "expression": { "op": "feature", "fieldKey": "active", "cmp": "eq", "value": true },
+  "metrics": [
+    { "op": "count", "alias": "records" },
+    { "op": "value_count", "field": { "kind": "feature", "fieldKey": "score" }, "alias": "present" },
+    { "op": "sum", "field": { "kind": "feature", "fieldKey": "score" }, "alias": "scoreSum" }
+  ]
+}
+```
+
+- 可选一个 `groupBy`，字段使用 `builtin`、标量 `feature.fieldKey` 或 `tag_group.tagGroupId`；多个指标仍有上限。支持 `count/value_count/distinct_count/sum/avg/min/max`，实际字段类型和权限由服务端判定。`count` 不带字段，所有指标及分组 alias 必须唯一。
+- CLI 只调用已公开、稳定、只读且支持 Studio 的 `data.asset.aggregate`；不会猜地址、不以旧内置路由替代、不下载全量 Asset 后本地统计。找不到或不兼容时，停止并确认 Server 部署和 OpenAPI，不能靠刷新 CLI 把未部署的 Operation 变出来。
+- 结果仍为 `items/pageInfo`。`aggregatePages` 保留每一服务端页的 `scanned/exact/truncated/pageInfo` 及 `itemOffset`；多页不累加扫描量，也不把分页分组再算成一个虚假的总计。单次只返回一页时还提供顶层 `scanned/exact/truncated`。
+- `exact` 是服务端指标精确度声明，不等于已经读完全部组。必须同时检查 `pageInfo.hasMore` 与 `truncated`；任何缺页或截断都不能称为完整统计。近似 `distinct_count` 也不得说成精确去重数。`accuracy` 不是请求参数。
+- 默认单页；确有需要时才用有界 `--page-all --page-limit`。分页令牌绑定指标、分组、排序、筛选、Ontology/View 和 Context。服务端按指标排名不支持续页时，不得自行分页或改为本地全量排序。
+
 ## 错误处理
 
 - `DATA_SEARCH_EXPRESSION_INVALID`：请求未发送。修正节点路径、op、fieldKey、cmp、value 或表达式上限。

package/skills/monkeys-shared/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: monkeys-shared
-description: 通过 monkeys CLI 选择多租户或私有化部署的 Subscription、Context、Team 与 Identity，并遵循统一的输出、风险、错误、安全和 CLI/Skill 版本规则。用户询问 Monkeys 平台能力、订阅上下文、命令参数、结构化错误、版本兼容或其他 monkeys-* Skill 需要公共规则时使用。
+description: 通过 monkeys CLI 选择 Subscription、Context、Team 与 Identity，管理 Kernel 平台用户的直接组成员和自定义权限组，并遵循公共输出、安全、错误和版本规则。用户询问平台能力、用户/权限组管理、订阅上下文或其他 monkeys-* Skill 需要公共规则时使用。
 ---
 
 # Monkeys Shared
@@ -19,6 +19,7 @@ description: 通过 monkeys CLI 选择多租户或私有化部署的 Subscriptio
 ## 按需读取
 
 - 平台领域与命令入口：[平台能力地图](references/platform-overview.md)
+- 平台账号、用户组、权限组与批量成员治理：[用户与权限组](references/identity-governance.md)
 - Secret、确认、批处理与结构化错误：[安全与错误](references/safety-errors.md)
 - 所有列表、搜索和行读取命令的统一续页规则：[分页](references/pagination.md)
 - CLI/Skills 同版本合同：[兼容性](references/compatibility.md)

package/skills/monkeys-shared/references/identity-governance.md

@@ -0,0 +1,47 @@
+# 平台用户与权限组
+
+这是 Kernel 全局管理，不是 Studio 分享目标 `identity list/get`，也不是 Data Tag Group。先按 monkeys-shared 公共流程核对版本、Subscription 与实际身份，再读 `monkeys schema <命令>`。全部命令要求显式 `--subscription`，不接收也不继承 Team。
+
+## 发现和边界
+
+- `user list/get` 查平台账号的安全投影，不提供创建/删除账号、改密码/API Key 或禁用状态写入。
+- `group list/get` 查权限组；`permission list` 查现有权限定义，不创建/删除权限定义。
+- `user group list <user-id>` 的分页 `items` 带 `source=direct|mapped`，`direct/mapped` 是当前页的分组投影。同一组可能有两种来源。
+- `group member list <group-id>` 仅查直接成员；`group permission list <group-id>` 查配置权限。列表均遵守标准分页，完整读取要检查 `hasMore=false`。
+- `super_admin` 成员受保护。`member/platform_admin` 等系统组定义/权限不能修改，但服务端允许的直接成员可增删。`platform_admin` 被移除后，业务组和组织映射不会被一并清空。
+- 自定义组支持 `group create/update/delete`，输入走 `--input-file` 或 `--input-json`。删除须无直接成员，且无法恢复原 ID。
+- 写操作必须先预览，并只在用户批准已展示的精确目标后使用 `--yes`。CLI 校验不是服务端授权承诺。
+
+## 单个成员变更
+
+`--ids` 可重复：在 `user group add/remove` 中表示组 ID；在 `group member add/remove` 中表示用户 ID。`--ids-file` 是严格 JSON 字符串数组。不得按名字猜 ID，空数组不表示全选。
+
+```bash
+monkeys group member remove <group-id> --subscription <subscription> --ids <user-id> --dry-run
+monkeys group member remove <group-id> --subscription <subscription> --ids <user-id> --yes
+```
+
+## 全体成员或其他批量变更
+
+```bash
+monkeys group member remove <group-id> --subscription <subscription> --all-members --dry-run --plan-out removal-plan.json --page-size 100 --page-limit 100
+monkeys group member remove <group-id> --subscription <subscription> --plan-file removal-plan.json --yes
+```
+
+第一条只完整枚举直接成员并冻结名单，不执行修改。第二条必须基于用户审核的文件；之后新增成员不自动进入范围。普通多 ID 写入也必须先 `--dry-run --plan-out`，再用 `--plan-file --yes`，不能跳过预览直接全量执行。
+
+清单绑定命令、目标、实际操作者、Subscription、部署/租户、合同 digest 与相关成员前态；发生变化会拒绝执行。每批最多 200 个增量，逐批重新检查、写入和读回，整个作业不是一个事务。分页不完整、重复 ID/token、总量证据不一致都必须停止。
+
+如果范围包含操作者自己，CLI 要求能证明保留独立受保护 super_admin 权限；失败时换用已有且合适的授权操作者。不得偷偷排除自己、授予备用管理员权限或修改清单绕过检查。
+
+## 整组权限替换
+
+`group permission set <group-id> --input-file permissions.json --dry-run` 只预览。文件必须显式为 `{"permissionIds":[...]}`，缺字段/null/未知 ID 都报错，`{"permissionIds":[]}` 才是有意清空。该操作是整组替换，不是增量追加；服务端仍是后写覆盖，预检/读回不等于原子版本检查。
+
+## 报告和失败处理
+
+- 默认在当前目录 `.monkeys-identity/` 保存前态、批次写前记录、已核验回执和最终报告；`--plan-out/--report/--snapshot` 指定文件绝不覆盖。文件含账号/组标识和权限配置，不含凭据；应保存在受访问控制的目录，不提交到仓库或随意分享。
+- 批量结果分别为 `completed/skipped/failed/unknown/pending`。退出码 9 表示执行或核验未完整完成，不是“全部没改”。
+- `inverse` 只包含确认完成的变化，供另一次获授权的恢复使用；不得自动反向执行，也不得用旧计划继续重放。
+- `unknown`、超时、无效响应、授权丢失或读回失败后，只读核对精确目标。保存 `snapshot/reports/failureReport/requestId`；不能用 Raw API、HTTP、UI 或数据库绕过新命令的兼容/安全门禁。
+- `IDENTITY_OPERATION_UNAVAILABLE` 表示部署尚未公开兼容接口或合同已漂移。报告发布/部署限制；获授权更新后 `--refresh` 再预检。安装 CLI、部署 Server、执行用户数据清理是三个独立步骤。

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

@@ -15,6 +15,8 @@
 
 ## 覆盖边界
 
+- 平台用户/权限组管理使用 `user`、`group`、`permission`，先读 [用户与权限组](identity-governance.md)。这些命令固定 Kernel 全局；旧 `identity` 分享目标发现保持独立。
+
 - 语义命令覆盖的是 Agent 高频、可建立安全合同的能力，不等于 Kernel/Studio 界面中的全部导航模块。
 - Applications、Models、Identity、Billing 等领域若没有对应语义命令，先用 `monkeys --help` 与领域 Help 确认；不要因为界面存在入口就臆造 CLI 命令。
 - 只有满足受控降级条件时，才通过 CLI 的 `api list/describe/call` 使用 Server OpenAPI。仍然不得直接发送 HTTP。