ZY Action Platform FDE（数据/本体工程师）使用说明

适用对象：数据工程师 / 本体工程师 / FDE 前沿部署工程师 · 核心产品：P2 LightFoundry（数据源/数据集/同步/本体/指标/管道/质量/SQL 工作台/Notebook/报表/Fusion/流规则/治理/MCP/CLI）、P4 LightGotham（多源接入/实体解析）、P5 LightSwift（部署/授权自检）· v5 对齐 V5 七阶段升级（CHANGELOG v5.0）· 官方文档见 action/wiki/docs/foundry/、gotham/、swift/ 各 md 与 -API.md

1. 工作流总览

登录（admin/admin1，各产品独立 JWT；可用 actionctl login 存凭据）
 ├─ Foundry（18081，网关前缀 /api）
 │   ├─ 1. 数据源接入（自管理数据源页：注册连接 + 导入元数据，任务化）
 │   ├─ 2. 数据集与同步（平台拉数/上传建集 + 全量/增量同步 + 版本发布）
 │   ├─ 3. 质量画像（完整性/唯一性/有效性/时效性四因子加权评分）
 │   ├─ 4. 本体建模（对象/属性/链接/动作 + 标准值类型 13 类 + 本体函数 + OWL/SHACL 导出）
 │   │      └─ 4.1 YAML 导入导出（声明式，随 Apollo bundle 分发）
 │   │      └─ 4.2 版本管理（draft → review → merge + approve/reject + 影响分析）
 │   ├─ 5. 对象化 SQL 工作台（Ontology SQL + 编辑态聚合叠加）
 │   ├─ 6. 指标定义（entity/dimension/measure/metric 四层）
 │   ├─ 7. 管道构建与质量规则（write_mode 目标对象同步 + ValidationRule）
 │   ├─ 8. 血缘追溯（源→管道→本体→指标 四级 + Action 写边 + 报表打点）
 │   ├─ 9. 协作分析（Notebook 代码工作簿 / 块式报表 / Fusion 实体消解 / 流事件规则）
 │   ├─ 10. 治理与安全（术语表/分类/保留策略 + 安全标记 Markings 列级闸门）
 │   ├─ 11. 互操作（MCP Server / 命令行 actionctl / OWL-SHACL 导出）
 │   └─ 12. 生态（组件市场 / 代码仓库 / 统一搜索 Nexus）
 ├─ Gotham（18083，网关前缀 /gotham-api）
 │   ├─ 13. 多源接入（CSV/JSON/database/manual 四类 + Ingest + 行级图谱化导入）
 │   └─ 14. 实体解析作业（L1~L4 四层流水线 + 人工审核）
 └─ Swift（18084）
     └─ 15. 部署与授权自检（WatchPeriodic 周期校验 + 到期优雅关停）

2. 登录与侧边栏

  1. 打开 http://127.0.0.1/（Web 网关 80）或直连 127.0.0.1:18081，登录（admin / admin1）；
  2. 登录后进入 Foundry 本体工作台 /foundry，左侧侧边栏（FDE 高频入口，共 30 项）：
侧边栏入口路由对应能力
本体工作台/foundry对象/属性/链接/动作 CRUD + 版本状态机
版本历史/foundry/versions版本时间线 + review/merge/approve/reject + 影响分析
YAML 导入导出/foundry/yaml声明式导入导出（本体即代码）
Action 测试/foundry/actions写路径执行测试（四模式 + ValidationRule）
指标管理/foundry/metrics指标语义层四层 + 编辑态聚合叠加
管道构建/foundry/pipelinesSQL 步骤管道 + write_mode + cron 调度
数据集/foundry/datasets数据源拉数/上传建集 + 预览/画像/版本发布
数据同步/foundry/sync全量/增量同步目标与运行历史
SQL 工作台/foundry/sql对象化 SQL 翻译与执行 + 编辑态叠加
数据源/foundry/datasourcesFoundry 自管理数据源 CRUD/测试/导入元数据
数据血缘/foundry/lineage四级血缘追溯 + 报表打点
数据质量/foundry/quality质量规则 + 质量画像 Tab
语义检索/foundry/searchSemanticSearch 结构化检索
对象查询/foundry/query对象语义查询（OOL）
数据治理/foundry/governance术语表/分类/保留策略
Notebook 分析/foundry/notebook代码工作簿（markdown/sql/chart 三类块）
智能报表/foundry/reports块式报表 + 定时快照 + 多渠道分发
实体消解/foundry/fusionFusion 重复实体消解 + 人工审核
流事件规则/foundry/stream变更驱动流规则（通知/回调/同步/质量/写回）
函数注册/foundry/functions本体函数（13 内置 + 自定义 + 在线测试）
数据打标/foundry/markings安全标记 + 用户授权矩阵
本体导出/foundry/ontology-exportOWL/TTL/SHACL 标准导出
商品市场/foundry/marketplace组件与应用发布/一键安装
代码仓库/foundry/coderepoSQL 宏与版本化代码仓库
MLOps 模型/foundry/ml模型生命周期（只推理不训练，◐）
演示数据源：aip_demo_warehouse（AIP，18080）/ foundry_demo_warehouse（Foundry，18081）/ 玄武集团网络（Gotham，18083）/ Swift（18084）独立，跨产品语义层未自动打通。

3. Foundry：数据源接入（自管理）

启动时自动创建 foundry_demo_warehouse（SQLite：customers 3 行 / orders 5 行 / products 3 行 / inventory 3 行 + V5 场景表），已导入元数据（幂等 seed，重启重建）。V5 起 Foundry 有独立数据源页 /foundry/datasources（B1-6，不再依赖 AIP 独占 CRUD）：

操作方法/路径
数据源列表GET /api/v1/datasources
注册连接POST /api/v1/datasources（MYSQL/SQLSERVER/POSTGRESQL 默认放行，SQLITE 需显式授权）
连接测试POST /api/v1/datasources/:id/test
导入元数据POST /api/v1/datasources/:id/import-metadata（任务化，15s 快路径兼容 + 202 轮询）

要点：导入前按 table_schema_id 清理旧 columns/tables（防残留误导 RAG/查询）；LLM 可用时自动生成列业务描述与同义词。数据源可作为本体对象的 data_source_id + base_table 底座。

4. Foundry：数据集与全量/增量同步（V5 B1-1 / B1-3）

4.1 数据集（dataset）

入口：/foundry/datasets。API：GET /api/v1/datasets、POST /api/v1/datasets（platform_ds 拉数建集）、POST /api/v1/datasets/upload（CSV/JSON 上传，XLSX 明确报错降级）、GET /api/v1/datasets/:id、GET /api/v1/datasets/:id/preview?limit=（钳制 500）、GET /api/v1/datasets/:id/profile、POST /api/v1/datasets/:id/versions/publish、GET /api/v1/datasets/:id/versions。

curl -s -X POST http://127.0.0.1:18081/api/v1/datasets \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"orders_snapshot","source_type":"platform_ds","source_ref":{"ds_id":"1","query":"SELECT * FROM orders LIMIT 1000"}}'

预期：行表 ds_dataset___foundry_<uuid> 已建、row_count 正确、血缘边 datasource:1 → dataset:<rid> 落库；资源 URI dataset://foundry/<rid> 供统一搜索引用。

4.2 全量/增量同步（sync）

入口：/foundry/sync。API：GET/POST /api/v1/sync/targets、PUT/DELETE /api/v1/sync/targets/:id、POST /api/v1/sync/targets/:id/run（任务化返回 {run, task_id}）、GET /api/v1/sync/targets/:id/runs、GET /api/v1/system/tasks/:id（统一任务进度）。

要点：full = 事务内重写；incremental = watermark 水位线断点续传 + 冲突跳过；成功链自动联动血缘与质量画像（bridge）；schedule 经统一调度器注册。边界：sync source_type=object 未注入 ObjectRowReader（运行时明确报错）；sync_run runner 未注册 taskMgr（重启后 queued 标 failed，可手动重跑）。

5. Foundry：数据质量画像（V5 B1-2）

入口：/foundry/quality 新增「画像」Tab。API：GET/POST /api/v1/quality/profiles（?scope_type=&scope_id= 过滤）、POST /api/v1/quality/profiles/:id/run、GET /api/v1/quality/profiles/:id/scores。

四因子 SQL 下推：completeness（加权 NULL 率）/ uniqueness（DISTINCT pk）/ validity（类型匹配，困难列 sampled 标注）/ freshness（无水位 na）；总分加权，低于阈值经 bridge 写入 pipeline quality issues 闭环。质量规则（null/format/unique/referential）与运行历史见 §9.2。

6. Foundry：本体建模

6.1 创建对象类型

入口：本体工作台 →「创建对象」，接口 POST /api/v1/ontology/objects。字段要点：name（api_name 唯一）/ display_name / data_source_id / base_table / pk_column / properties[]（name/data_type/mapped_column/is_primary_key/ordinal，支持约束/同义词/PII/列级安全）/ actions[]（可选）。对象带稳定标识 rid（object-type:<name>），路由可用 rid 或 api_name 定位。内置演示对象：customer / order / product。预期：创建即生成 v1/merged 版本。

V5 标准值类型（B7-1）：冻结 13 类（text/number/integer/decimal/currency/percentage/date/datetime/bool/enum/json/array<text>/array<number>）；GET /api/v1/ontology/value-types 查目录；POST /api/v1/ontology/value-types/normalize 两段式迁移存量属性（dry-run 返回 diff，confirm 写库；text+enum→enum、number+单位→currency/percentage、precision 0/>0→integer/decimal）。新类型 semantic mapper 按 text/number 降级并标注。

6.2 创建链接

POST /api/v1/ontology/links：object_type_id + name + target_object_type_id + cardinality（1:N 等）+ direction + source_property/target_property；N:N 时带 join_dataset（join_table/source_key/target_key）。内置演示：customer_to_order（1:N）、order_to_product（N:N，join 表 order_items）。

6.3 创建动作（Action 写路径）

动作是本体唯一写入口（POST /api/v1/ontology/actions）。内置示例 update_order_status：

{
  "object_type_id": 2,
  "name": "update_order_status",
  "edit_type": "modify",
  "param_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "number"},
      "status": {"type": "string", "enum": ["shipped","cancelled","pending"]},
      "expected_updated_at": {"type": "string"}
    },
    "required": ["order_id", "status"]
  },
  "write_back_config": {
    "sql_template": "UPDATE orders SET status=:status, updated_at=strftime('%Y-%m-%d %H:%M:%f','now') WHERE order_id=:order_id AND updated_at=:expected_updated_at",
    "data_source_id": 1,
    "optimistic_lock": true,
    "mode": "post"
  },
  "idempotency_key_field": "order_id"
}

v5 要点：四种 edit_type 执行器（create/modify/delete/link）；六步安全流水线（Schema 校验 → 逐动作 RBAC → 记录级写权限 → 属性级写权限三分 → ValidationRules 前置校验（B7-6，失败聚合提示且失败即阻断，规则空时零开销跳过）→ 幂等登记 + 事务）；四执行模式 VALIDATE / RUN / ASYNC / VALIDATE_AND_EXECUTE（默认）；pre/post 回写模式；编辑态独立落盘（ontology_edits）+ 读叠加（行级与聚合 V5 B1-5 均覆盖，聚合回退行级+内存聚合上限 10000，超限 approximate 标注）。

curl -s -X POST http://127.0.0.1:18081/api/v1/ontology/actions/update_order_status/execute \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"object_type_id":2,"params":{"order_id":1,"status":"shipped","expected_updated_at":"<当前 updated_at>"},"idempotency_key":"k-001","mode":"VALIDATE_AND_EXECUTE"}'

预期：正常 → status=success, rows_affected=1；同 key 重放 → status=replayed；expected_updated_at 不匹配 → status=conflict（409 ACTION_CONFLICT）；ValidationRules 不满足 → 聚合返回 message 且写路径阻断。

6.4 YAML 导入导出

入口：/foundry/yaml。导出 GET /api/v1/ontology/objects/:id/export?format=yaml（objectTypes 根节点，含 api_name/rid 引用）；导入 POST /api/v1/ontology/objects/import（application/yaml，两遍扫描解析 link 目标，返回 {total, created, skipped, errors}，单个对象失败不整体回滚）。示例：导出 order → 改名 order_import → 重新导入 → 得到新对象。YAML 制品可随 Apollo bundle 分发（契约④），也可用 actionctl ont export/import（见 §14）。

6.5 版本管理状态机

步骤操作API预期
1创建草稿POST /api/v1/ontology/objects/:id/drafts返回 version_id，状态 draft
2编辑草稿PUT /api/v1/ontology/drafts/:vid仅 draft 可更新
3提交评审POST /api/v1/ontology/drafts/:vid/review状态 → review
4合入POST /api/v1/ontology/drafts/:vid/merge状态 → merged，返回影响分析
5审批POST /api/v1/ontology/objects/:id/versions/:vid/approve|reject审批闭环（门禁 + 自批拦截）
回滚回滚到历史版本POST /api/v1/ontology/objects/:id/rollback（target_version）主表重建为历史快照

v4/v5 增强：聚合真冲突检测——合入时求交 (base, latest] merged diff 与草稿 diff，无真冲突自动合并。

6.6 影响分析

POST /api/v1/ontology/objects/:id/impact 返回对象被引用位置（链接/动作/管道/血缘/指标/编辑）。被引用对象禁止删除。

6.7 本体函数与 OWL/SHACL 导出（V5 B7-2 / B7-5）

本体函数：入口 /foundry/functions。POST /api/v1/ontology/functions 创建（body 为表达式：{{param}} 引用、fn(arg1,arg2) 调用，13 内置函数 len/abs/round/min/max/coalesce/if/ifnull/concat/upper/lower/now/date_trunc + 用户函数，递归深度 ≤5）；POST /api/v1/ontology/functions/:name/test 即时求值。计算属性 Formula 引用 fn_xxx(...) 时 mapper 降级 NULL+标注。

OWL/SHACL 导出：入口 /foundry/ontology-export。GET /api/v1/ontology/objects/:id/export?format=owl|ttl|shacl（单对象 OWL/Turtle 或 SHACL 校验形状；Class/DatatypeProperty 按 DataType→XSD、NodeShape/PropertyShape、minCount/maxCount 由主键/约束推导、enum→sh:in、pattern）；GET /api/v1/ontology/objects/:id/shacl（等价 format=shacl）、GET /api/v1/ontology/export/owl（整库 OWL 一图导出）。

7. Foundry：对象化 SQL 工作台与编辑态聚合叠加（V5 B1-4 / B1-5）

入口：/foundry/sql。API：POST /api/v1/ontology/sql/translate（翻译预览，不执行）、POST /api/v1/ontology/sql/execute（翻译并执行，body {sql, limit}）。

特性：面向业务对象写 SQL（对象名→物理表、属性→MappedColumn）；RLS/CLS 注入（与 semantic 同路径）；LIMIT 补 500 / 钳 5000；编辑态列叠加（行级与聚合一致，LoadEditValues/OverlayAggregate）；解析器安全（单条 SELECT、注释剥离后关键字校验、DML/多语句拒绝）；前端支持对象下拉 / 运行 / 结果表 / 编辑态高亮 / CSV 导出 / 翻译预览。

curl -s -X POST http://127.0.0.1:18081/api/v1/ontology/sql/execute \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT order_id, amount FROM order WHERE amount >= 100 ORDER BY amount DESC","limit":50}'

预期：返回 columns + rows，编辑态修改过的行以最新值返回并附 edited_fields 标注。

8. Foundry：指标定义

四层：entity → dimension / measure → metric；类型支持 simple / ratio / derived / cumulative。入口：指标管理 /foundry/metrics。

操作方法/路径
实体 CRUDGET/POST /api/v1/metrics/entities、GET /api/v1/metrics/entities/:id
维度POST /api/v1/metrics/entities/:id/dimensions（time_grain=day、is_time_dimension=true）
度量POST /api/v1/metrics/entities/:id/measures
指标 CRUDGET/POST /api/v1/metrics、GET/PUT/DELETE /api/v1/metrics/:id
指标查询POST /api/v1/metrics/query
指标目录GET /api/v1/metrics/catalog

内置演示（entity=Sales，挂在 order 对象上）：dimension=created_at(day)；measure gmv=SUM(amount) / count=COUNT(*) / aov=SUM(amount)/COUNT(*)；metric total_gmv（=6470.5）、aov。V5 要点：查询注入属性级只读权限；编辑态聚合叠加（ratio/derived/cumulative 未叠加标注 P2）；指标血缘自动打点；报表块引用 metric 打 RecordMetricToReport 血缘边（B3-5.1 补断点）。

curl -s -X POST http://127.0.0.1:18081/api/v1/metrics/query \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"total_gmv"}'   # 返回 rows=[[6470.5]]

9. Foundry：管道构建与质量规则

9.1 管道构建器

入口：/foundry/pipelines。API：GET/POST /api/v1/pipelines、GET/PUT/DELETE /api/v1/pipelines/:id、POST /api/v1/pipelines/:id/run（任务化）、GET /api/v1/pipelines/:id/runs、POST /api/v1/pipelines/:id/enable|disable、GET /api/v1/scheduler/jobs、GET /api/v1/scheduler/jobs/:name/runs（统一调度器，V5 S0）。创建要点：name / source_connector_id / target_object_type_id / trigger_type=manual / sql_steps[]。

curl -s -X POST http://127.0.0.1:18081/api/v1/pipelines \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"clean_orders_pipe","description":"清洗订单","source_connector_id":1,"target_object_type_id":2,"trigger_type":"manual","sql_steps":[{"name":"clean_orders","sql":"CREATE TABLE IF NOT EXISTS smoke_clean AS SELECT * FROM orders WHERE amount IS NOT NULL","transform_type":"create_table_as"}]}'

预期：运行后 status=success，返回 rows_in/rows_out，自动打点血缘。v5 要点：write_mode 目标对象同步（append / append_only_new / snapshot_replace / snapshot_replace_and_remove）；质量 error 级阻断同步；cron_expr 激活（统一调度器注册）；ValidationRule 六步流水线。边界：单数据源 SQL 步骤。

9.2 数据质量规则与画像

入口：/foundry/quality。API：GET/POST /api/v1/quality/rules、PUT/DELETE /api/v1/quality/rules/:id、GET /api/v1/quality/issues、POST /api/v1/quality/issues/:id/acknowledge|fix；画像（V5）：GET/POST /api/v1/quality/profiles、POST /api/v1/quality/profiles/:id/run、GET /api/v1/quality/profiles/:id/scores。规则四类：非空（null）/ 格式（format）/ 唯一（unique）/ 引用完整性（referential）。

10. Foundry：血缘追溯

入口：/foundry/lineage。链路：源→管道→本体→指标 四级 + Action 写边（对象→动作）+ 报表打点（metric→report，V5 补断点）。

GET /api/v1/lineage?type=object&id=order&direction=downstream&depth=2
GET /api/v1/lineage?type=metric&id=total_gmv&direction=upstream&depth=3

参数：type（source/pipeline/object/metric/report）、id（名称/rid）、direction、depth。返回 nodes+edges，前端图可视化。边界：浓缩版四级模型非逐字段全量；报表血缘断链已补（dashboard 图表绑定 metric 写路径打点）。

11. Foundry：Notebook 与块式报表（V5 B3-1 / B3-2）

11.1 Notebook 代码工作簿

入口：/foundry/notebook。API：GET/POST /api/v1/notebooks、GET/PUT/DELETE /api/v1/notebooks/:id、GET/POST /api/v1/notebooks/:id/cells、PUT/DELETE /api/v1/notebooks/:id/cells/:cid、POST /api/v1/notebooks/:id/cells/:cid/run、POST /api/v1/notebooks/:id/run、GET /api/v1/notebooks/:id/runs?limit=。三类单元格：markdown / sql / chart；sql 块经 OntologySQLService.Execute（复用安全翻译 + RLS/CLS + 编辑态叠加）；chart 块依赖其引用 sql 块结果集（不重算）。

11.2 块式报表

入口：/foundry/reports。API：GET/POST /api/v1/reports、GET/PUT/DELETE /api/v1/reports/:id、POST /api/v1/reports/:id/run、POST /api/v1/reports/:id/dispatch（email 走 mailer / internal 落通知表 / feishu 未配降级）、GET /api/v1/reports/:id/runs?limit=、GET /api/v1/report-runs/:id/snapshot。报表按 blocks（chart/text/table）编排，schedule 经统一调度器（report:<rid>）定时生成快照；块引用 metric 自动打血缘。

12. Foundry：Fusion 实体消解与流规则（V5 B3-3 / B3-4）

12.1 Fusion 实体消解

入口：/foundry/fusion。API：GET/POST /api/v1/fusion/projects、GET/PUT/DELETE /api/v1/fusion/projects/:id、POST /api/v1/fusion/projects/:id/run（异步）、GET /api/v1/fusion/projects/:id/runs、GET /api/v1/fusion/projects/:id/matches?status=、POST /api/v1/fusion/matches/:id/confirm|reject。流程：规则分桶（key_fields 精确 + blocking）→ 桶内两两相似度加权（精确/前缀/编辑距离）→ 阈值外 LLM 复核 → union-find 聚类 → survivorship 选主（in_place_edit 经编辑态写 winner 值 / materialize 写输出 dataset）→ 人工审核闭环。

12.2 流事件规则（stream）

入口：/foundry/stream。API：GET/POST /api/v1/stream/rules、GET/PUT/DELETE /api/v1/stream/rules/:id、POST /api/v1/stream/rules/:id/test、GET /api/v1/stream/rules/:id/deliveries。规则挂 cdc watcher：condition（expression 语法）命中即执行 action_type（webhook 回调 / notification 通知 / sync_run 触发同步 / quality_run 触发巡检 / writeback 经 writepath 五步流水线，不可绕过）。变更捕获由 platform/cdc（V5 B2-3）提供：首轮 snapshot、COUNT+max(watermark) 比对检出 insert/update、EventBus 订阅分发。

13. Foundry：语义检索 / 对象查询 / 数据治理 / 安全标记

13.1 语义检索

POST /api/v1/ontology/semantic-search，body {"query":"order","scopes":["object","metric"]}。返回匹配项（name/display_name/类型/命中原因），对象级可见性注入（供 AIP OAG 使用）。

13.2 对象查询（OOL）

POST /api/v1/objects/:id/query，body {"fields":["order_id","amount"],"filters":[{"field":"amount","op":"gte","value":100}]}。支持 op：eq/gt/gte/lt/lte/ne + 布尔组合 and/or/not；翻译引擎自动参数白名单防注入、link 自动 JOIN、RLS/CLS 注入。限制：单对象遍历式、traverse ≤3 层、禁点号。

13.3 数据治理

入口：/foundry/governance。术语表 GET/POST /api/v1/governance/glossary；分类 GET/POST /api/v1/governance/classifications；保留策略 GET/POST /api/v1/governance/retention-policies（执行属 P2 ○）。

13.4 安全标记（V5 B7-4 Markings）

入口：/foundry/markings。API：GET/POST /api/v1/markings、GET/PUT/DELETE /api/v1/markings/:id、GET/POST /api/v1/markings/:id/bindings、DELETE /api/v1/markings/:id/bindings/:bindingId、GET/POST /api/v1/markings/user-markings、DELETE /api/v1/markings/user-markings/:id。CLS 第二道列级闸门：semantic/query.go 属性级安全块合并 marking 隐藏（任一来源隐藏即隐藏该列，NULL AS col），ApplyCLS 内部零改动。

14. Foundry：MCP 与命令行 actionctl（V5 B7-3 / B7-7）

14.1 MCP Server

foundry.mcp.enabled=false 默认关闭（禁用时路由不注册 → 404，actionctl mcp ping 可判活）。启用后：POST /api/v1/mcp（JSON-RPC：initialize / tools/list / tools/call / ping，Bearer 鉴权）。工具集 5 个：search_objects / query_objects（limit≤200 强制）/ get_metric / execute_action（writepath 五步全走不可绕过，越权 403）/ get_dataset；每次 tools/call 落审计 MCP_TOOL_CALL（敏感参数脱敏）。

14.2 actionctl CLI

构建：cd /f/chatBI/chatBI_dev/action && go build -o actionctl ./cmd/actionctl。7 个子命令（纯 HTTP client，配置三源优先级 flag > env > ~/.actionctl）：

命令说明
actionctl login --base URL --username admin --password admin1登录并保存凭据（~/.actionctl 0600）
actionctl ont export order --format yaml|json|owl|shacl -o order.yaml导出对象定义（YAML/JSON/OWL/SHACL）
actionctl ont import order.yaml导入本体 YAML
actionctl dataset list|get|preview <rid> --limit N数据集操作
actionctl task list|get|cancel <id> --status running异步任务管理（挂 /system/tasks 前缀）
actionctl metric query total_gmv --dims region --filters status=open指标查询（op 恒 eq）
actionctl mcp pingMCP 探活（404 → 未启用，退出码 1）
actionctl login --base http://127.0.0.1:18081 --username admin --password admin1
actionctl ont export order --format yaml -o order.yaml      # 本体即代码，进 Git 评审
actionctl dataset list --format table
actionctl metric query total_gmv --dims region --format table

15. Foundry：组件市场 / 代码仓库 / 统一搜索（V5 B5-1 / B5-2 / B5-3）

15.1 组件市场（Marketplace）

入口：/foundry/marketplace。API：GET /api/v1/marketplace/items?tags=&q=&item_type=&status=、POST /api/v1/marketplace/items（object→ExportObject yaml 信封；metric/dashboard/app/notebook/fusion_project 读库 JSON 组包，跨环境引用全用名称规避 id 漂移）、POST /api/v1/marketplace/items/:id/install、GET /api/v1/marketplace/items/:id/installs。

15.2 代码仓库（CodeRepo）

入口：/foundry/coderepo。API：GET/POST /api/v1/coderepo/repos、GET/POST /api/v1/coderepo/repos/:id/files、GET/PUT/DELETE /api/v1/coderepo/files/:id、GET /api/v1/coderepo/files/:id/revisions、POST /api/v1/coderepo/macros/resolve。SQL 宏（${macro} 引用）在 SqlWorkbench 与 Notebook sql 单元格两处翻译前展开（宏表优先、未命中原样、迭代 maxMacroDepth=5）。

15.3 统一搜索（Nexus）

FoundryLayout 顶栏全局搜索框（防抖 300ms）：GET /api/v1/nexus/search?q=&scopes=&limit=。默认五 scope：objects / metrics / datasets / dashboards / notebooks（docs P0 未注入返回空）；各 scope 并行召回 + RRF 1/(60+rank) 融合、同 URI 跨 scope 累加去重、单 scope 容错；objects 命中含对象级可见性。结果按 URI 映射跳转对应功能页。

16. Gotham：多源接入（CSV/JSON/DB/manual）

入口：Gotham 情报工作台 /gotham「数据接入」区。API：GET/POST /api/v1/ingestion/sources、GET/PUT/DELETE /api/v1/ingestion/sources/:id、POST /api/v1/ingestion/sources/:id/run（任务化，SSE 进度）、GET /api/v1/ingestion/batches?source_id=、GET /api/v1/ingestion/entities；图谱化导入（V5 B4-1）：GET/PUT /api/v1/ingestion/sources/:id/graph-mapping、POST /api/v1/ingestion/sources/:id/map-to-graph、GET /api/v1/ingestion/sources/:id/mapping-suggest。内置演示源：gotham_demo_personnel（manual，5 条记录）。

{
  "name": "smoke_csv_xxx",
  "display_name": "csv 情报源",
  "source_type": "file_csv",
  "connection_config": {"path": "D:/data/entities.csv", "delimiter": ","},
  "mapping_config": {"node_type": "person", "id_field": "entity_id", "label_field": "name", "property_fields": ["org","role","amount"]}
}
  1. 准备 CSV（列与 property_fields 对应），如 smoke_c_001,李四,玄武集团,联络人,50000；
  2. POST /api/v1/ingestion/sources 创建源 → 返回 id；
  3. POST /api/v1/ingestion/sources/:id/run → status=success, imported_records=N（SSE 进度推送）；
  4. GET /api/v1/ingestion/batches?source_id=:id 校验批次（fingerprint 幂等去重）；
  5. GET /api/v1/ingestion/entities 查看融合实体；配好 graph-mapping 后 Ingest 自动追加图谱化步骤（0.6~1.0 进度映射）。

JSON 同理（source_type=file_json）；database 源接连接配置；manual 为预置记录。连接配置秘密字段 AES-256-GCM 加密落库。中文内容建议 UTF-8 文件 + --data-binary @file。

17. Gotham：实体解析作业

四层流水线：L1 确定性（1.0 短路）/ L2 规则 / L3 模糊（Levenshtein/JaroWinkler/Dice/Soundex）/ L4 AI 灰区（0.35~0.85，默认关闭）。三阈值带：≥0.90 自动合并 / 0.70~0.90 待审 / <0.70 拒绝。

# 1) 创建作业
curl -s -X POST http://127.0.0.1:18083/api/v1/resolution/jobs -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"res-persons","description":"人员消解","entity_type":"person","source_ids":[1,2]}'
# 2) 运行
curl -s -X POST http://127.0.0.1:18083/api/v1/resolution/jobs/<JOB_ID>/run
# 3) 轮询直至 completed
curl -s http://127.0.0.1:18083/api/v1/resolution/jobs/<JOB_ID>
接口说明
GET /api/v1/resolution/jobs/:id/statstotal_candidates / matched_pairs / auto_merged / clusters
GET /api/v1/resolution/jobs/:id/clusters实体簇
GET /api/v1/resolution/jobs/:id/pairs候选匹配对（含 Layer + Reason 可解释依据）

待审对可人工确认合并（MergeNode）/ 拒绝 / 拆分，落 EntityMergeLog 审计。预期（冒烟实测）：candidates≥8、matched_pairs≥1、auto_merged≥1（同名"李四"跨源自动合并）。

18. 授权自检（全产品，64ddd5c8 下放）

AIP（18080）/ Foundry（18081）/ Apollo（18082）/ Gotham（18083）/ Swift（18084）自 64ddd5c8 起各产品独立授权自检、自治关停（不再依赖 AIP 级联）：

端点鉴权说明
GET /api/v1/license/infoprotected机器码+有效期仅展示；force=1 强制重校验
PUT /api/v1/license/auth-key内联 admin JWT（共享 SECRET_KEY）写 AUTH_KEY，成功清空授权缓存
POST /api/v1/admin/shutdown公开路由 + 内联 admin JWT触发本产品优雅退出

要点：周期校验 WatchPeriodic（启动立即 + 每 30 分钟，nonce+crypt_data 防重放）；关停语义（授权不满足 → 到点优雅退出本产品、不影响其它产品）；AUTH_KEY 三级兜底（DB system_settings → 环境变量 → config.yaml）；档位：未注册 hard（20min+随机 0~10min）/ 已过期 ≥30 天 hard / 已过期 <30 天或校验失败 grace（6h+随机 0~2h）；/license/info 返回 shutdown_scheduled / shutdown_deadline / shutdown_tier / shutdown_reason，前端到期提醒可见。

19. 未实现边界（如实标注）

能力状态
Foundry MLOps◐ 骨架：rule/external_api 引擎，仅推理不训练；batch-predict/metrics/drift 缺失（P1）
Foundry 三语言 SDK○ 未实现（仅 REST API + OpenAPI 快照）
编辑态读叠加派生指标◐ 行级与聚合已叠加，ratio/derived/cumulative 未叠加（标注 P2）
同步 source_type=object◐ 未注入 ObjectRowReader（运行时明确报错）
XLSX 上传建数据集○ 明确报错降级
管道跨数据源○ 仅单数据源 SQL 步骤
Gotham RLS/CLS（scopeFilter）○ 未实现
Gotham Time-Wheel 时间轮盘○ 未落地（以 timeline 接口实现）
实体解析 AI 增强层◐ 默认关闭（仅相似度算法）
跨产品语义层联动○ 未打通（演示数据独立）
告警推送 / 主动通知○ 漂移/授权事件只落库 + 审计，通知属 V2
MCP 全能力◐ 默认关闭；SSE GET 路由未注册；HTTP 级冒烟测试待补

20. 常见问题

现象处理
创建对象 500 / 语义查询报错确认 data_source_id 指向已注册且已导入元数据的数据源
Action 执行 FORBIDDEN当前用户未授权该动作（admin 角色放行；逐动作授权见《管理员使用说明》）
Action 返回 conflict乐观锁冲突：重新读取最新 updated_at 再提交
Action 返回 ValidationRules 失败看聚合返回的 message 列表，修正入参后再提交
合入报"聚合真冲突"草稿与已合入区间 diff 有交集：看影响分析，重新基于最新版起草稿
数据集上传 XLSX 报错当前仅支持 CSV/JSON，XLSX 明确报错降级，先转 CSV
同步任务重启后 failedsync_run runner 未注册 taskMgr，fs_sync_runs 保留可手动重跑
指标聚合与行级不一致行级与聚合已叠加编辑态（B1-5）；ratio/derived/cumulative 暂不叠加
血缘查不到节点确认 depth/direction；打点有异步延迟；报表节点需块引用 metric
管道输出与目标对象不一致检查质量规则是否 error 级阻断；确认 write_mode 覆盖预期
MCP 调用 404foundry.mcp.enabled=false 默认关闭，改配置启用后重启
授权状态 authorized=falsePUT /api/v1/license/auth-key 写入有效 AUTH_KEY，再 GET /license/info?force=1 强制重校验
CSV 导入中文乱码文件用 UTF-8，终端传参用临时文件方式
实体解析 L4 未参与AI 灰区默认关闭，需管理员配置 LLM 网关