@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

login 会先通过 /api/v1/me 验证凭据，成功后再原子写入配置；配置目录和文件权限分别为 0700、0600。

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

Decidex 渐进披露三步走

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

# 2. 列出该本体下的问题场景（默认只返回 stableId/name/description）
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
guanonto risk-types expand --network ont_xxx <riskStableId>

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

完整命令

Discovery

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

场景（concept-groups）

# concept-groups 形态：--network 指定本体（容器 friendly）
guanonto concept-groups list   --network <ontId>
guanonto concept-groups list   --network <ontId> --view full
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

完整场景展开不传 --version 时读取当前可编辑本体；传数字编号时按不可变快照解析。--view risk 只查当前本体，不能与 --version 同用。 --view risk 返回轻量风险候选索引：risks[] 内含 stableId/name/description/severity/source/matchedObjectStableIds。source=related 只表示与场景成员对象有交集；需要调查时再调用 risk-types expand。不返回对象属性、引用指标和缓解行动。

concept-groups list 默认只返回 stableId/name/description；管理端需要成员列表时使用 --view full。

关系路径（仅查本体定义）

guanonto graph paths --network <ontId> --from <objectStableId> --to <objectStableId> --max-hops 3
guanonto graph paths --network <ontId> --from <objectStableId> --to <objectStableId> --mapped-only

从当前可编辑本体返回最多 20 条、最多三跳的对象关系路径。每一步包含方向、基数、连接属性和已绑定字段；status=unmapped 表示还不能据此连接实例。此命令不读取 BI 实例数据，也不能用空路径证明业务实例不存在。

完整 expand 结果（当前态 / 历史快照一致，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>

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

# 导出：默认 latest=当前可编辑态；数字编号或快照 ID 导出不可变历史版本
guanonto export <ontId> [--version <number|id|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，但 apply 仍单独检查 write scope、创建权限、并发状态和持久化结果。
• dry-run 命中 conflicts 时服务端返回 200，CLI 以非 0 退出，便于 agent 自我修正。
• read PAT 可以执行 create-new dry-run；replace dry-run 还要求目标本体命中 PAT 白名单。
• apply 必须使用 write PAT 或 svc-key；svc-key 写操作还需 GUANONTO_NAMESPACE + GUANONTO_ACTOR_REF。
• --ontology 或文件内 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。

版本对齐

• 0.5.0（2026-09-28，不兼容）：移除 lookup / search（ADR 0026）、scenarios（改用 concept-groups --network）、object-types get（改用 show）、import --target（改用 --ontology）
• @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 · 公司内部使用。