@inf-monkeys-tech/monkeys-cli 0.12.37 → 0.12.39

package/oclif.manifest.json

@@ -5334,6 +5334,16 @@
           "summary": "Old Bucket ID (deprecated; new tasks use --ontology)",
           "type": "option"
         },
+        "incoming": {
+          "allowNo": false,
+          "exclusive": [
+            "keyword",
+            "view"
+          ],
+          "name": "incoming",
+          "summary": "Discover incoming relation columns owned by other Ontologies",
+          "type": "boolean"
+        },
         "jq": {
           "char": "q",
           "hasDynamicHelp": false,
@@ -6957,6 +6967,160 @@
       ],
       "strict": true
     },
+    "data:relation:get": {
+      "aliases": [],
+      "args": {},
+      "description": "Read incoming/outgoing business relations independently of local fields. Bounded multi-hop expansion requires Studio and an explicit Ontology allowlist; it never expands report candidates.",
+      "enableJsonFlag": false,
+      "flags": {
+        "allow-ontology": {
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "name": "allow-ontology",
+          "summary": "Additional Ontology ID allowed for expansion; repeat for each confirmed scope",
+          "type": "option"
+        },
+        "asset-ids-file": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "asset-ids-file",
+          "required": true,
+          "summary": "JSON array of 1-1000 exact root Asset IDs",
+          "type": "option"
+        },
+        "bucket": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "bucket",
+          "summary": "Old Bucket ID (deprecated; new tasks use --ontology)",
+          "type": "option"
+        },
+        "depth": {
+          "default": 1,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "depth",
+          "summary": "Maximum relation hops; default reads direct edges only",
+          "type": "option"
+        },
+        "direction": {
+          "default": "both",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "direction",
+          "options": [
+            "incoming",
+            "outgoing",
+            "both"
+          ],
+          "type": "option"
+        },
+        "field-id": {
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "name": "field-id",
+          "summary": "Optional relation-owner Column IDs filtering the first hop only",
+          "type": "option"
+        },
+        "jq": {
+          "char": "q",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "jq",
+          "summary": "Filter the JSON result with a jq expression",
+          "type": "option"
+        },
+        "max-assets": {
+          "default": 1000,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "max-assets",
+          "type": "option"
+        },
+        "max-edges": {
+          "default": 5000,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "max-edges",
+          "type": "option"
+        },
+        "ontology": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "ontology",
+          "summary": "Ontology ID",
+          "type": "option"
+        },
+        "output": {
+          "default": "json",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "output",
+          "options": [
+            "json",
+            "pretty",
+            "table",
+            "ndjson",
+            "csv",
+            "text"
+          ],
+          "summary": "Output format",
+          "type": "option"
+        },
+        "perspective": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "perspective",
+          "options": [
+            "kernel",
+            "studio"
+          ],
+          "summary": "Use only this Data perspective; when omitted, read queries use Studio first and may fall back to Kernel",
+          "type": "option"
+        },
+        "resource-team": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "resource-team",
+          "summary": "Kernel Ontology data resource location Team; does not represent Team filtering and cannot be used simultaneously with --team",
+          "type": "option"
+        },
+        "subscription": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "subscription",
+          "type": "option"
+        },
+        "team": {
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "team",
+          "type": "option"
+        },
+        "yes": {
+          "allowNo": false,
+          "char": "y",
+          "name": "yes",
+          "summary": "Confirm destructive or privileged operations",
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "data:relation:get",
+      "isESM": true,
+      "pluginAlias": "@inf-monkeys-tech/monkeys-cli",
+      "pluginName": "@inf-monkeys-tech/monkeys-cli",
+      "pluginType": "core",
+      "relativePath": [
+        "dist",
+        "commands",
+        "data",
+        "relation",
+        "get.js"
+      ],
+      "strict": true
+    },
     "data:tag-group:create": {
       "aliases": [],
       "args": {},
@@ -20020,5 +20184,5 @@
       "strict": true
     }
   },
-  "version": "0.12.37"
+  "version": "0.12.39"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inf-monkeys-tech/monkeys-cli",
-  "version": "0.12.37",
+  "version": "0.12.39",
   "packageManager": "bun@1.3.14",
   "description": "Monkeys command-line client for AI agents, automation, and interactive use",
   "type": "module",
@@ -117,7 +117,7 @@
     }
   },
   "dependencies": {
-    "@inf-monkeys-tech/monkeys": "1.1.23",
+    "@inf-monkeys-tech/monkeys": "1.1.38",
     "@oclif/core": "4.13.2",
     "ajv": "8.20.0",
     "csv-parse": "6.1.0",
@@ -150,5 +150,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "monkeysReleaseCommit": "e21b7f47cd65232b4be7956d1596351aa9860960"
+  "monkeysReleaseCommit": "8edded7a47b42036beef3cc8e018718e64cd41b8"
 }

package/skills/monkeys-data/SKILL.md

@@ -19,6 +19,7 @@ description: 通过 monkeys CLI 理解并操作 Ontology、View、Asset、Field/
 
 - 查询、搜索、候选批量字段/关系、媒体与附件（含 Studio View 筛选合同）：[Data 读取](references/data-read.md)
 - 按 Feature Column 结构化值检索：[Ontology Feature 结构化检索](references/ontology-feature-search.md)
+- 跨 Ontology 关联、正向/反向筛选、子查询、关系聚合与有界展开：[Ontology 业务关联](references/ontology-relations.md)
 - 创建和修改资源：[Data 写入](references/data-write.md)
 - Ontology、Container、Trash 与转换：[Data 初步治理](references/data-governance.md)
 - JSONL、CSV、XLSX 与 Ontology 迁移：[Data 导入导出](references/data-transfer.md)

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

@@ -65,10 +65,10 @@ CLI 只校验 expression 公共结构和 JSON 标量形状。Feature 的真实
 - semantic/vector/description/fuzzy/full-text Feature search
 - JSON/object/relation/image/file Feature 类型
 - View/container scoped Feature
-- 任意关系遍历、多维 facet、exists 或 null predicate；标量 sort/select 与单维 aggregate 见下文，不能据此推断其他能力已经存在。
+- 无界关系遍历、exists 或 null predicate；有界业务关联、跨本体子查询及最多两维关联聚合见 [Ontology 业务关联](ontology-relations.md)。
 - Feature 与 `current_and_shared` 跨 Team 查询
 
-不要把固定字段 `relation` expression 与 Relation 类型 Feature 混淆；后者当前不支持。
+不要把用户/团队 `relation` expression 与业务 `featureRelation` / `featureRelationSource` 混淆；业务关系使用专门的身份元组合同，不使用标量 feature 比较。
 
 ## 最小字段投影与排序
 
@@ -110,7 +110,7 @@ monkeys data asset aggregate --ontology <ontology-id> --view <view-id> --input-f
 }
 ```
 
-- 可选一个 `groupBy`，字段使用 `builtin`、标量 `feature.fieldKey` 或 `tag_group.tagGroupId`；多个指标仍有上限。支持 `count/value_count/distinct_count/sum/avg/min/max`，实际字段类型和权限由服务端判定。`count` 不带字段，所有指标及分组 alias 必须唯一。
+- 可选一个 `groupBy` 或最多两个 `groupByDimensions`（互斥），字段使用 `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` 不是请求参数。

package/skills/monkeys-data/references/ontology-relations.md

@@ -0,0 +1,50 @@
+# Ontology 业务关联查询
+
+业务关系连接 `(ontologyId, assetId)`，不能只按 Asset ID 合并。先确定业务候选集合和字段 `config.fieldKey`；关联证据不自动加入报告商品集合。所有命令沿用调用用户、Subscription、明确视角和可读 View，不因空结果或权限失败换身份、切 Kernel、扫 PG 或全库。
+
+## 读取与关系发现
+
+- `data field list --ontology <ID>` 获取出向字段定义；`data field list --ontology <ID> --incoming` 获取其他 ontology 指向当前 ontology 的关系字段，检查完整分页。以实际字段配置确定关系，不按名称猜测。
+- `data asset inspect --ontology <ID> --asset-ids-file ids.json` 批读字段和关系。默认读取全部入向/出向关系，即使当前本体没有关系字段；指定 `--field-id` 时只查所选关系列。省略 View 时不含 View 专属字段。
+- 单独反查或跨本体展开用 `data relation get --ontology <ID> --asset-ids-file ids.json --direction incoming|outgoing|both`。输出 `edges[].source/target/columnId`、`missing`、`boundaries`、`frontier`。缺失记录不等于无关联。只有 `completeWithinRequestedScope=true` 才表示请求范围内批次完整，不表示全图、目标详情或权限已全部验证。
+- 有界展开可加 `--depth 2`（最多3）、重复 `--allow-ontology <确认允许的目标ID>`。多跳只支持 Studio；最多1000节点、5000边，超限报错，不发布部分结果为完整结论。`boundaries` 是未允许继续展开的目标，`frontier` 是深度边界。遇到权限拒绝停止；无循环重复查询。需要详情时将返回节点按 ontology 分组另批 inspect，不跨业务候选范围制作商品卡。
+
+所有示例补充当前已确认的 `--perspective studio --team <Team>`；Kernel 单跳补 `--perspective kernel --resource-team <数据Team>`，不可混用。命令先看当前 schema；旧服务缺接口时报告部署合同缺口，不猜替代接口。
+
+## 关联条件与跨 ontology 子查询
+
+使用 `data asset search --ontology <ID> --filter-file scope.json --expression-file expression.json`。scope.json 保留实际 View 与归属筛选；不能省略原有业务范围。表达式也可与标量、标签通过 and/or 组合。
+
+正向：查使用某块面料的商品（fieldKey 属于商品本体）：
+
+```json
+{"op":"featureRelation","fieldKey":"materials","cmp":"contains_any","value":[{"ontologyId":"materials-ontology","assetId":"material-id"}]}
+```
+
+反向：在面料本体中查被指定商品关联的面料，必须给出关系所属商品本体与可读 View：
+
+```json
+{"op":"featureRelationSource","ontologyId":"products-ontology","viewId":"products-view","fieldKey":"materials","cmp":"contains_any","value":[{"ontologyId":"products-ontology","assetId":"product-id"}]}
+```
+
+根据另一可读 View 的筛选结果选择关联目标（例：在面料本体查询指定品牌商品引用的面料）：
+
+```json
+{"op":"inQuery","query":{"ontologyId":"products-ontology","viewId":"products-view","field":{"kind":"feature_relation_target","fieldKey":"materials"},"expression":{"op":"tagGroup","allOf":["confirmed-brand-tag"]}}}
+```
+
+必须把来源 View 的归属等必要业务条件加入 query.expression；不能仅照抄示例。最多6个 inQuery 叶子，不支持嵌套；服务端限制每叶5000匹配身份、50000来源分组及表达式展开预算。超限缩小真实查询范围或报告缺口，不能静默取前几条。builtin asset_id 投影仅能引用根 ontology。
+
+`relation` 仍只表示 owned-by/shared-with/liked-by/favorited-by 用户或团队关系，不等于业务关联。
+
+## 关联聚合
+
+`data asset aggregate --ontology <ID> --view <View> --input-file query.json` 支持以 `feature_relation_target`（fieldKey）或 `feature_relation_source`（fieldKey、ontologyId、viewId）作为 groupBy 字段；返回键为完整身份元组。支持最多两个 groupByDimensions，与 groupBy 互斥；关系字段不能作为 sum/avg 等数值指标。
+
+```json
+{"groupBy":{"field":{"kind":"feature_relation_target","fieldKey":"materials"},"alias":"material"},"metrics":[{"op":"count","alias":"products"}]}
+```
+
+两维去重统计可使用 rollup `{groupAlias,distinctAlias,alias}`，要求两个不同分组和一个 count 指标、按 key 排序。保留业务筛选，复用实际标签ID。逐页核对 exact/truncated/scanned/pageInfo，不能把分页或截断结果当全量统计。部署必须支持对应合同；校验失败不自动降级到 Raw API。
+
+服务端限制必须保留：当前反向条件可能要求关系所属 View 不附带记录筛选；收到此类 400 不自动改用另一个 View。跨本体子查询仍受各来源与目标的访问控制，403（含 LF_ACCESS_DENIED）表示权限或服务端范围问题，不代表数据为空，也不得通过换身份或 Raw API 绕过。优先使用已验证的直接关系筛选或在既定候选内批读关联证据；不能据此宣称等价全量子查询已完成。