@guandata/guanonto-cli

guanonto（观远本体平台）的命令行工具。专为 Decidex turn 容器 / Agent runtime 场景设计：env 三元组开箱即用，错误协议对齐 RFC 7807 problem+json，stderr 直接给 Agent 解析。

安装

# 在使用项目 / 容器镜像中加 .npmrc：
echo '@guandata:registry=https://app.mayidata.com/nexus/repository/guandata-web/' >> .npmrc

# 全局装（推荐容器场景）
npm i -g @guandata/guanonto-cli

guanonto --version
guanonto --help

认证：env 优先（Decidex turn 容器）

Decidex turn launcher（PR5b）已经把这三个 env 注入到 codex 沙箱：

| env | 必填 | 示例 | 说明 | |---|---|---|---| | GUANONTO_BASE_URL | ✓ | https://guanonto.guandata.com | guanonto 服务地址（无尾斜杠会被自动剥） | | GUANONTO_PAT | ✓ | guanonto_pat_xxx | 明文 PAT，CLI 透传 Authorization: Bearer <pat> | | GUANONTO_NAMESPACE | △ | org-cmq5xxx | 业务端点必填；/api/v1/me 等少量端点可空 | | GUANONTO_ACTOR_REF | △ | decidex-user-123 | 仅写操作 audit 需要；只读不需要 |

env 模式下不需要 guanonto login。

本地 dev：login（仅本地）

guanonto login \
  --base-url http://127.0.0.1:3003 \
  --token guanonto_pat_xxx \
  --namespace org-default
# → 写 ~/.guanonto/config.json

env 优先级 > 配置文件。env 三元组都在时，config 文件不会被读。

Decidex 渐进披露三步走

# 1. 列出绑定的本体（通常 binding 已经把 networkId 写进 prompt，下面两步直接拿）
guanonto ontologies list

# 2. 列出该本体下的问题场景
guanonto concept-groups list --network ont_xxx

# 3. 命中场景后展开：拿到该场景关联的 object/relation/risk/action，
#    objectTypes[].instanceSources 已内联（remoteResourceId 即数据集 dsId），
#    定位数据集请读这里，不要按名称猜
guanonto concept-groups expand --network ont_xxx <scenarioStableId>

# 只看该场景关联的风险、关联对象、指标与缓解行动（响应更轻）
guanonto concept-groups expand --network ont_xxx <scenarioStableId> --view risk

返回都是 JSON，stdout 一次性吐完。Agent 可以直接 JSON.parse 拿到结构化数据。

完整命令

Discovery

guanonto whoami                    # 当前 PAT 解析后的 caller / namespace / actor / scope / 白名单
guanonto ontologies list           # 当前 namespace 内所有 ontology

场景（concept-groups / scenarios，二者等价）

# concept-groups 形态：--network 指定本体（容器 friendly）
guanonto concept-groups list   --network <ontId>
guanonto concept-groups get    --network <ontId> <scenarioStableIdOrId>
guanonto concept-groups expand --network <ontId> <scenarioStableIdOrId> [--version <n>]
guanonto concept-groups expand --network <ontId> <scenarioStableIdOrId> --view risk

# scenarios 形态：双 positional（兼容 M8 旧 smoke）
guanonto scenarios list   <ontId>
guanonto scenarios get    <ontId> <scenarioStableIdOrId>
guanonto scenarios expand <ontId> <scenarioStableIdOrId> [--version <n>]
guanonto scenarios expand <ontId> <scenarioStableIdOrId> --view risk

--version <n> 不传 = draft；传 = 按 OntologyVersion 快照解析。 --view risk 仅支持 draft，返回轻量风险视图：risks[] 内含显式/关联来源、风险摘要、关联对象、引用指标和缓解行动；风险说明在 risks[].riskType.description/detail；不会返回 objectTypes / relationTypes / instanceSources。

expand 结果（draft / version 一致，ADR 0016）：

• objectTypes[].properties[].metric.subType：object_metric 属性的指标子类型（ATOMIC | COMPOSITE | DERIVED），未命中快照为 null。
• relatedRiskTypes / relatedActionTypes：绑定到成员对象但非显式成员的风险，及缓解这些风险但非显式成员的行动；riskTypes / actionTypes 仍只含显式成员。

单资源查询

guanonto object-types list   --network <ontId>
guanonto object-types show   --network <ontId> <objectTypeId>   # object_metric 属性带 metric.subType

guanonto properties list     --network <ontId> --object-type <otId>
guanonto properties list     <ontId> <objectTypeId>            # 双 positional 兼容形态

guanonto relation-types list --network <ontId>
guanonto risk-types list     --network <ontId>
guanonto risk-types get      --network <ontId> <riskStableIdOrId>   # 普通风险 summary
guanonto risk-types show     --network <ontId> <riskStableIdOrId>   # 风险调查包：对象摘要、引用指标、缓解行动
guanonto risk-types expand   --network <ontId> <riskStableIdOrId>   # show 的同义命令，面向 Agent 渐进检索
guanonto action-types list   --network <ontId>

运行时实例（M5）

guanonto lookup <ontId> <otId> --ids k1,k2,k3
guanonto search <ontId> <otId> --field <fieldStableId> --value <v> [--limit 50]

导入 / 导出（ADR 0011 / 0019，0.2.0 起）

# 导出：--version 默认 latest=当前可编辑态（实时算 checksum）；数字版本号导出不可变快照
guanonto export <ontId> [--version <versionId|latest>] -o customer.bizontology.json

# 导入默认 dry-run：只返回 plan 报告（creates/updates/deletes/skippedSources/conflicts），不写库
# 文件可为完整 .bizontology.json，也可为裸 definition（{schemaVersion,ontology,kinds}），服务端自动识别
guanonto import customer.bizontology.json                                  # create-new dry-run
guanonto import definition.json                                            # 裸 definition create-new dry-run
guanonto import customer.bizontology.json --apply                         # create-new 落库
guanonto import customer.bizontology.json --ontology <ontId> --dry-run    # replace dry-run
guanonto import customer.bizontology.json --ontology <ontId> \
  --source-mappings mappings.json --apply                                 # replace 落库

• 真实校验在服务端（dry-run 与 apply 同一套校验/plan，dry-run 通过 ⟺ apply 成功）。
• dry-run 命中 conflicts 时服务端返回 200，CLI 以非 0 退出，便于 agent 自我修正。
• 写 / 校验需 GUANONTO_NAMESPACE + GUANONTO_ACTOR_REF。
• --ontology（兼容旧 --target）或文件内 targetOntologyId → replace，否则 create-new。

0.1.x 的 pull / push（draft 导出 / 裸 definition 导入）已移除。

通用 flag

• --trace <file>：所有只读命令支持。把 {ts, durationMs, method, path, status, request, response} 追加到 NDJSON 证据链。Agent 可以拿这个文件做"BizOntology 证据" blockquote 渲染。
• --help / -h：根级显示总帮助；<命令> --help 显示命令族 / 子命令帮助（如 guanonto object-types list --help），无需凭据、不触网络。
• --version / -V

错误协议

非 0 退出 + stderr 输出 RFC 7807 application/problem+json：

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "PAT 未授权访问该业务本体",
  "code": "ontology_not_allowed"
}

退出码：

| code | 含义 | |---|---| | 0 | 正常 | | 1 | 业务/网络错误（看 stderr） | | 2 | 用法错误（缺参 / 未配置认证） |

常见 code（继承 @guandata/guanonto-schemas 的 GUANONTO_ERROR_CODES）：

• missing_credentials —— 未配 env、也无 config 文件
• ontology_not_allowed —— PAT 白名单边界（M9.4 / ADR 0009）
• network_error —— fetch 失败（DNS/连接拒绝/超时）
• http_error —— 非 problem+json 的 4xx/5xx
• unknown_command、usage_error

不打回旧 alias / 已下线端点 —— 内部一律走 PR3 之后的 sub-resource API。

版本对齐

• @guandata/guanonto-cli ≥ 0.3.1：支持 risk-types get/show/expand
• @guandata/guanonto-schemas ≥ 0.12.1：导出 ExpandedConceptGroupRiskView，并支持 conceptGroupExpand(..., { view: "risk" })
• @guandata/guanonto-schemas ≥ 0.12.0：导出 RiskInvestigationPackage 与 riskTypeExpand
• guanonto 服务端包含 ADR 0021 /risk-types/:id/expand endpoint

License

UNLICENSED · 公司内部使用。