ZY Action Platform · 落地方案 · Full Edition

完善版「AI 行动系统」Demo 落地方案

在基础版(ai-action-demo.html:数据源→管道→本体→查询→工作流→Copilot→审批→通知→证据)之上,把平台其余全部已实现功能纳入演示:知识库与 RAG、实体抽取、决策证据链、多智能体编排、LLM 网关、评测监控、安全治理、SQL 工作台、Notebook、报表、质量、流事件、实体消解、Marketplace、MLOps、低代码应用,以及 Apollo / Gotham / Swift 三条延伸产品线。

适用范围:AIP + Foundry 主线 + 三产品延伸 形态:开发/演示手册 实现程度逐项标注(可演示/部分实现/仿真)

0. 与基础版的关系

项目说明
基础版action/docs/ai-action-demo.html——一条端到端最小闭环(库存补货剧情),本方案不重复其内容:数据源、管道/同步/数据集、本体版本审批、NLQ/语义检索/对象查询、AIP 工作流(cron/webhook/event)、Automation Copilot、Foundry human_task 审批、动作写路径(幂等/乐观锁)、邮件/飞书、审计/血缘/事件回看。演示前请先按基础版 §4-§6 把最小闭环跑通。
本版定位「全功能纵深」演示手册:把基础版之外的已实现功能逐个吃透,并给出推荐串联方式。四条纵深线:① AIP 智能纵深(知识域:知识库→实体抽取→RAG→决策→记忆→编排);② AIP 治理运营纵深(LLM 网关/Prompt/评测/监控/安全/RBAC);③ Foundry 数据纵深(SQL 工作台→Notebook→仪表盘→报表→质量→流事件→消解→函数→Marketplace→MLOps→Apps→打标→治理);④ 产品矩阵延伸(Apollo/Gotham/Swift)。
Demo 时长完整全功能约 2.5~3.5 小时;四条纵深线可独立演示(每条约 30~45 分钟);延伸篇每产品 10~15 分钟。
实现程度口径可演示=后端路由核实+端到端闭环;部分实现=真实但有明确功能边界/降级;仿真=链路真实、业务域为模拟。所有判定均以 2026-09 当前分支代码核实为准(server.go 路由注册逐条比对),与代码不符时以代码为准。
参考依据docs/frontend-intro-v5/markdown/{aip,foundry,gotham,apollo,swift}/(信息截止 v5 Stage 6 · 2026-08-30)、wiki/docs/{aip,foundry}/docs/story/{aip,foundry,cross}/wiki/dev_info.md、各产品 server/server.go 与 seed/demo 代码

1 全景地图与跨模块前置链

1.1 功能全景与实现程度总表

纵深线模块(入口路由)判定一句话能力
AIP 智能纵深 知识库管理 /knowledge可演示目录树+文档 CRUD+版本回滚+检索(保存即切分向量化)
知识分层树 /knowledge-tree可演示document→section→chunk 三层树,pdf/docx 上传,大纲与溯源
实体关系抽取 /entity-extract依赖 LLMLLM 抽实体/关系→人工确认→进 RAG 第五通道 entity
RAG 配置/检索测试 /admin/rag · /rag-test可演示四通道权重配置、索引重建、五段上下文可视化
决策证据链 /decision可演示分解→三路检索→核验→综合→引用,trace 全留痕
会话记忆 /memory-manage可演示会话级记忆查看/清空(最近 6 轮原文+LLM 压缩摘要)
多智能体编排 /orchestrate同步阻塞sequential/parallel/leader_follow/debate 四策略协同
AIP 治理运营 LLM 网关 /admin/llm-gateway可演示Provider/路由规则/预算/熔断/降级链/用量成本
Prompt 管理 /admin/prompts可演示模板版本化+本地试算(不调 LLM)
评测管理 /admin/eval可演示Text2SQL 评测(EA/EM/SV)+回归告警
监控看板 /admin/monitoring可演示查询量/成功率/P95/Tokens/LLM 失败率/反馈统计
RBAC/用户/安全 /admin/roles|users|security可演示表/列/行级权限、敏感列脱敏、AI 护栏
本体/工具/Agent 管理 /admin/ontology|tools|agents可演示AIP 侧本体四件套、工具启停试执行、编排 Agent 治理
Foundry 数据纵深 SQL 工作台 /foundry/sql可演示受限只读 SQL,RLS/CLS 注入+标识符白名单+LIMIT 钳制+翻译预览
Notebook /foundry/notebook前端有 bugmarkdown/sql/chart 单元格,历史落库(详见 §5.2 边界)
Dashboards /foundry/dashboardsMVP 降级图表绑定本体语义查询,表格渲染(ECharts 未接本页)
Reports /foundry/reports可演示块式报表→快照→email/internal 分发+cron 调度
Quality /foundry/quality可演示四类质量规则+问题闭环+四因子画像
Stream /foundry/stream依赖注入CDC 事件规则→webhook/通知/同步/质量/回写五类动作
Fusion /foundry/fusion可演示实体消解:规则打分+聚类+人工确认+主记录写回
Functions /foundry/functions可演示本体函数注册/测试/互调(递归≤5)
CodeRepo /foundry/coderepo可演示snippet/template/macro 仓库+版本+宏展开
Marketplace /foundry/marketplace可演示六类资产发布为快照商品+一键安装
MLOps /foundry/mlops引擎受限模型注册/部署/预测;仅 rule 与 external_api 可推理
Apps /foundry/apps组件受限低代码三层(应用→页面→组件);5/8 组件真实渲染
Markings /foundry/markings可演示密级打标+授权矩阵,CLS 之外第二道列级闸门
Governance /foundry/governance可演示术语表/分类标签/保留策略
API Keys /foundry/api-keys可演示lfk_ 凭证;权限随绑定用户角色继承,scopes 闸门已就绪但不挂载
Apollo/apollo/* 19 页可演示期望状态部署 DAG 门控 + 漂移检测自愈(Poller 演示级)
Gotham/gotham/* 16 页可演示图谱研判/多源接入/实体解析/模式识别/报告(resolution AI 裁决已接线,patterns AI 增强 V2 预留)
Swift/swift/* 4 页仿真国密报文签名验签 + 一键 10 步星地结算演示

1.2 跨模块前置链(决定演示上限)

基础版的环境准备之外,智能纵深线有一条依赖链,必须按顺序先铺好,否则 /rag-test、/decision、编排等页面的多通道效果出不来:

登录 admin → ① 数据源导入元数据(基础版 §5.1) → ② LLM 网关确认 deepseek 路由可用 + entity_extract 路由已种(§4.1 / §2.1) → ③ 建知识库并保存文档(触发切分+向量化,§3.1) → ④ 实体抽取并人工确认(§3.3,硬依赖 entity_extract 路由) → ⑤ 重建 RAG 索引(§3.4,POST /rag/index/rebuild) → ⑥ 之后 /rag-test 五段上下文、/decision 三路检索、NLQ 多通道、/orchestrate 才是"满血"演示
降级是设计行为:embedding/LLM 无 key 时 RAG 走关键词兜底不中断;/decision 单步失败一律降级继续(verify 失败按 support 处理、synthesize 失败降级为证据摘要、某通道未注入则 skipped)。演示话术应把"诚实的降级"当卖点:不静默、不造假。

2 前置准备(扩展项)

2.1 LLM 网关路由检查(含 entity_extract)

  1. 登录 admin → 管理后台 → LLM 网关/admin/llm-gateway)→ Provider 状态区确认 deepseek available、health 正常、熔断状态 closed。
  2. 路由规则区确认 entity_extractnlqtext2sqlanalysischat 等任务类型的路由存在且候选 provider 正确。实体抽取没有规则降级路径:网关未配 entity_extract 路由时 /entity-extract 抽取直接报错(§3.3)。
  3. 用「网关试调」POST /llm/chat 选任务类型 entity_extract 试调一次,确认链路通。
注意:路由规则不可增删只能编辑(UI 限制);cost_limit_cents 单次调用预算 0=不限;/llm/chat 直连端点不经过 PIIGuard 脱敏(内部 LLM 消费默认脱敏,直调不脱敏是已知口径)。

2.2 config.yaml 现状与本版相关的项

配置节当前实际状态影响
llmdeepseek 主力(openai 兼容通道亦指向 deepseek-v4-flash),dashscope 承担 embedding智能纵深线全部可用
feishu.enabledtrue(app_id/secret 已配,default_channel: copilot)飞书推送/卡片可用;报表 feishu 渠道可试
emailusername/password/server 均为空邮件通知实际不可用:Reports 的 email 分发、工作流 email 渠道会失败——演示前要么配 SMTP,要么走 internal 渠道并讲"诚实失败"设计
foundry.oag.enabledtrue(base_url 复用 18081)Copilot/OAG 动作路可用(基础版已覆盖)
gotham.graph.mode"disk"(JSON 落盘 temp/gotham_graph.json)Gotham 不依赖 neo4j,直接可演示
workbuddy.enabledtrue(v5 修复后恢复:出站断线指数退避重连,不再 panic)WorkBuddy 本地 MCP / 云端 Hub 接入可用
secret_key(SECRET_KEY)config.yaml 已配强密钥v5 修复后 SECRET_KEY 缺失/弱值拒绝启动(含 config.yaml 加载成功路径);演示可显式 AIP_DEMO/FOUNDRY_DEMO/GOTHAM_DEMO/SWIFT_DEMO=1 放行(Apollo 无开关,缺密钥回退弱值继续启动)
apollo / swift无独立配置节(各自代码内启动参数)独立后端直接 go run 即可(§6)

2.3 账号与权限矩阵

账号用途要点
admin/admin1主演示账号(各产品各自用户库同名)Markings/图算法等接口 admin 门禁;Foundry 与 AIP token 跨产品互信(username_fallback)
普通用户 1 名RBAC 权限对比、行级过滤演示/admin/users 注册并分配角色;用于验证"看得到的数据不一样"(§4.5)
审批人 1 名基础版 human_task + 本版 Apollo healing 审批基础版 §5.7 已用,本版复用
第二个协同账号Gotham WebSocket 协同/看板联动开两个浏览器窗口演示实时通知(§6.2)
v5 修复后权限口径:admin 密码不再被启动覆盖(bootstrap 改 First-or-Create,已存在即保留既有凭据;忘记密码用 DEFAULT_ADMIN_RESET=1 显式重置并 Warn 留痕)。② Foundry 数据面收敛 admin-only:数据集/同步/管道的创建与数据源访问授权统一要求 admin(普通用户建管道/同步/platform_ds 数据集 403),审计查询/导出、ABAC 策略、/notify/send 亦仅 admin——数据面操作一律用 admin 演示。③ Gotham 数据源接口 admin-only + 口令掩码/ingestion/sources 系列与批次暂停/恢复需 admin(普通角色仅批次列表/进度/融合实体认证可见);数据源口令不再回显(password 恒空,仅 password_set 标记)。

3 AIP 智能纵深(知识域)

3.1 知识库管理(/knowledge)

定位:给 NLQ/RAG/决策链提供"业务口径文档"——目录树管理+文档 CRUD+版本回滚+检索。保存文档即同步完成切分+向量化(返回 chunk_count)。

操作

  1. 知识库页(/knowledge)→ 新建目录(名称* + 上级目录 + 描述 → POST /knowledge/directories),建议建「补货口径」目录承载主剧情的业务规则。
  2. 新建文档:格式 text/markdown/html,填标题/所属目录/标签/内容(如"补货规则:库存低于补货点即创建采购申请,审批人=采购经理")→ 保存。
  3. 修改内容再保存 → 版本 +1;用「回滚」POST .../versions/:v/restore 演示版本回退。
  4. 用「知识检索」POST /knowledge/search(top_k 固定 10)搜"补货规则"验证召回。

怎么验

  • 保存响应含 chunk_count>0;检索命中刚建的文档;回滚后内容复原、版本时间线正确。
边界:标签过滤是客户端过滤(接口无 tag 参数);大文档保存为同步等待(先切分向量化再返回);内容完全未变可能不产生新版本。

3.2 知识分层树(/knowledge-tree)

定位:把文档升级为三层结构 document→section→chunk(kdoc_nodes):markdown 按 #/##/### 生成 section;支持 pdf/docx 上传(前端转 base64,创建超时 120s);检索结果带 node_path 标题链与来源标注(新旧双表合并去重)。

操作

  1. /knowledge-tree → 上传一份 pdf/docx(或粘贴多级标题 markdown)→ 查看自动生成的分层树。
  2. GET .../outline 看文档大纲;用检索验证来源标注(src-tree 分层树 / src-blocks 旧表)。

怎么验

  • 树形结构正确;pdf 解析成功(失败时回退纯文本,标注 parser=pdf-degraded——这是诚实降级不是错误);检索结果带标题链。
设计口径:section/document 级刻意不做 LLM 摘要,仅 chunk 建向量;存量旧文档无树,需编辑内容触发重建。

3.3 实体关系抽取(/entity-extract)

定位:从知识库文档中用 LLM 抽取实体/关系,人工确认后进入 RAG 第五通道 entity(抽取后四通道权重调整为 metadata 0.35/knowledge 0.25/history 0.15/fewshot 0.15 + entity 0.10),按 doc://aip/<docID>?chunk=n 溯源。

操作

  1. 实体抽取页(/entity-extract)→ 选一份知识库文档(如补货规则文档)→ 点「抽取」→ POST /knowledge/documents/:id/extract 任务化返回 {run, task},前端每 2s 轮询 GET /extract_runs(上限约 4 分钟)。
  2. 实体表逐行确认/拒绝POST /entities/:id/confirm|reject)——演示"AI 抽取 + 人工把关"。
  3. 看 ECharts 力导向关系图(GET .../graph)。

怎么验

  • 实体状态 auto→confirmed;被拒绝实体不进 RAG entity 通道(可在 /rag-test 对比确认前后的检索差异)。
硬依赖:LLM 网关未配 entity_extract 路由则直接报错,无规则降级路径——演示前务必先过 §2.1。其它边界:单 chunk 6000 字符、置信度默认 0.6、实体扫描上限 1000、关系只读不可编辑。

3.4 RAG 配置与检索测试(/admin/rag、/rag-test)

定位:RAG 是 NLQ 准确率的底座。配置页调四固定通道(metadata/knowledge/history/fewshot)权重;测试页可视化一次检索的五段上下文。

操作

  1. RAG 配置/admin/rag):调权重(step 5%,保存换算 0-1);合计偏差 >0.5% 弹 confirm 归一化(末位通道吸收漂移)→ PUT /rag/channels。演示把 knowledge 通道调高后再问口径类问题。
  2. 索引重建POST /rag/index/rebuild(可带 data_source_id,空=全量;返回 indexed/item_count)。前置链第 ⑤ 步在此执行。
  3. 检索测试/rag-test):POST /rag/retrieve(question* + 可选数据源 + top_k 1-50 默认 10)→ 看五段上下文 Tab:表结构 Schema / 字段同义词 / 知识上下文 / 历史会话 / Few-shot 示例,以及 channels_used 与 latency_ms。

怎么验

  • 建知识库+抽取实体并重建索引后,/rag-test 的「知识上下文」「实体通道」出现内容;检索带 user 隔离(history/fewshot 按用户过滤,无身份 fail-closed 返回空)。
边界:通道不可增删只有四个;全量重建无进度条;向量引擎 milvus→turbovec→disk 保底(本机走 disk,Milvus 未真机联调);检索空结果多为索引未建——先导元数据/建知识库再重建。

3.5 决策证据链(/decision)

定位:"AI 回答问题,每句话有出处"。三栏页面:提问(问题* + 可选数据源名)→ POST /decision/answer(timeout 300s)同步跑 5 步链:decompose → retrieve(rag/entity/nlq 三路)→ verify → synthesize → cite,每步带状态徽标与 latency_ms;答案 ID 即 trace_id,与 AI 决策审计 ref_id 贯通(落表 ad_answers/ad_citations)。

操作

  1. 决策证据链页(/decision)→ 问"补货规则是什么?当前哪些库存低于补货点?"(前置链铺满时 rag/entity/nlq 三路全命中)。
  2. 逐步看 5 步状态与耗时;点开引用核对出处(知识库 chunk、实体、查询结果)。
  3. 历史回放:GET /decision/answers?limit=20GET /decision/answers/:id
  4. /admin/ai-audit 用 trace_id 查决策审计记录——证据链闭环。

怎么验

  • 答案带引用列表且可溯源;单步失败降级继续并标注(不是报错中断);markdown 渲染经 DOMPurify 防 XSS。
演示建议:先铺满前置链(§1.2)再演示,三路检索全命中效果最佳;只铺数据源也能演示(rag/nlq 两路),讲清楚"某通道 skipped 是依赖未注入的设计行为"。

3.6 会话记忆(/memory-manage)

定位:NLQ 多轮追问的记忆管理。机制:以 user_id 为会话键,仅查询成功才写记忆;最近 6 轮原文 + 更早轮次 LLM 压缩摘要;正则抽取表/指标实体提及;每日 4 点调度清理 30 天前记忆。

操作

  1. 先在 /chat 连续问 3~5 个相关问题(如"各区域销售额"→"华东呢"→"环比上月")。
  2. 记忆管理页(/memory-manage)→ 会话列表(GET /chat/sessions)→ 点「查看记忆」(GET /chat/sessions/:sid/memory)看原文轮次+摘要+实体提及。
  3. 回 /chat 用指代词追问,展示多轮上下文生效。
  4. 点「清空本会话记忆」(DELETE,二次确认,返回 {deleted:N})→ 追问立刻"失忆"。
边界:查询失败轮次不写记忆(空列表属正常);摘要按需压缩,冷启动显示"-";记忆仅会话粒度,无管理员全局视角。

3.7 多智能体编排(/orchestrate)

定位:多个角色 Agent 协作完成一个任务。策略四种:sequential / parallel / leader_follow / debate。子任务按 required_role(finance/supply_chain/sales/general)匹配角色 Agent。

操作

  1. 先在 Agent 管理/admin/agents)确认各角色 Agent 存在且启用(bootstrap 种子维护,见 §4.6)。
  2. 多智能体编排页(/orchestrate)→ 选策略(建议先 parallel 再 debate 对比)→ 填任务描述(如"分析当前库存低于补货点的商品,从财务和供应链两个视角给出补货建议")→ 提交 POST /orchestrations(同步执行,前端 timeout 600s)。
  3. 就地查看子任务列表与融合结果;历史分页表可看详情/结果。

怎么验

  • 不同策略的子任务编排/融合结果有差异;落 orchestration 历史与 AI 审计。
边界:同步阻塞无异步轮询(600s 内出结果,实测长链路 5-6 分钟);后端支持 sub_tasks 手动指定但前端未暴露;partial_complete 状态不支持取消;context 必须合法 JSON;Agent 注册/注销/YAML 导出在 admin 权限(GET /orchestrations/agents/export)。

4 AIP 治理与运营纵深

4.1 LLM 网关(/admin/llm-gateway)

定位:所有 LLM 调用的统一收口:Provider 管理、路由规则、预算与熔断、降级链、用量成本。演示"AI 成本与稳定性可治理"。

操作

  1. Provider 状态:deepseek/qwen/local_rule 的 available/model/cost_per_1k/circuit_state/health。
  2. 路由规则编辑:「编辑路由」→ 预算开关、user_limit_cents/app_limit_cents、候选 provider_order、降级链 fallback_orderPUT /llm/routes/:id 落库+热同步(重启不丢)。
  3. Provider 配置PUT /llm/providers/:id——api_key AES-256-GCM 加密落库、不回显,留空=不改
  4. 用量概览GET /llm/usage(总调用/Tokens/延迟/成功率/成本/降级次数)——跑完智能纵深线后回来看数字。
  5. 演示熔断降级:把某路由 provider_order 只留一个错误 key 的 provider → 触发熔断 → fallback_order 兜底(如 qwen 或 local_rule)→ 恢复。
机制:启动时 SyncFromDB 同步 llm_routes/llm_providers 表;主用 deepseek、备用 qwen、local_rule 规则降级。503=网关 repo 未注入。

4.2 Prompt 管理(/admin/prompts)

定位:Text2SQL/意图识别等 Prompt 模板的版本化管理:改 Prompt 不用发版。

操作

  1. 模板列表(name/model_family/version/active)→ 新建 POST /prompts/templates 或编辑 PUT /prompts/templates/:name保存即新建版本并置 active;编辑不可改名)。
  2. 版本管理 GET .../versions + POST .../versions/:v/rollback——演示改坏 Prompt 后一键回滚。
  3. 试算 POST /prompts/compile:填 {{var}} 变量,Go text/template 本地渲染返回 rendered/estimated_tokens/warnings(不调 LLM,零成本预览)。
边界:版本无限增长无清理;"active"由最近一次保存/回滚决定,无独立开关。

4.3 评测管理(/admin/eval)

定位:Text2SQL 质量量化:测试用例库 + 评测运行 + 回归告警。

操作

  1. 测试用例 Tab:类别 simple_select/join/aggregation/subquery/window,难度 easy/medium/hard,问题*+期望 SQL*;GET /evaluation/test-cases/export 导出 JSON(bootstrap 已种默认评测集)。
  2. 评测运行:点「运行评测」→ POST /evaluation/runs(timeout 120s)→ 指标:执行准确率 EA / 精确匹配 EM / 语法有效率 SV / 通过用例 / 平均延迟 / Tokens;用例结果可展开比对生成 SQL。
  3. 历史与回归GET /evaluation/reports——EA/EM/SV 较上次下降 >2% 触发 regression_alerts 告警标红。
  4. 串联演示:改一处 Prompt(§4.2)→ 跑评测 → 回归告警 → 回滚 Prompt → 再跑恢复。这就是"Prompt 变更安全网"的完整故事。
边界:评测已任务化(15s 内同步返回,超时 202+task_id),但前端未轮询任务接口——超长评测会失败,演示用小评测集即可。

4.4 监控看板(/admin/monitoring)

定位:查询质量与 LLM 健康度仪表板。

操作

  1. 概览:查询总数/成功率/平均与 P95 延迟/总 Tokens/LLM 失败率(GET /monitoring/metrics,聚合 nlq_query_logs 与 LLM 调用日志)——演示前先在 /chat 多问几条攒数据。
  2. 历史趋势GET /monitoring/history?window=1d|7d|30d(柱=查询量,线=延迟/成功率)。
  3. 反馈统计GET /feedback/stats——平均评分/1-5 星分布/类型分布(sql_correct|sql_syntax_error|wrong_result|misunderstood)。配套动作:在 /chat 查询结果页提交一次反馈(POST /feedback),回监控页看数字变化。
空库兜底 0/"-",不会白屏;ts 粒度为日期,近 1 天窗口较粗。

4.5 RBAC / 用户 / 安全治理(/admin/roles、/admin/users、/admin/security)

定位:"不同人看到不同数据"的一等治理能力:表/列/行三级权限 + 敏感列脱敏 + AI 护栏。

操作 A:行级权限对比(最有说服力)

  1. /admin/roles → 角色权限配置弹窗:TABLE_ACCESS / COLUMN_ACCESS / ROW_LEVEL_FILTER 三类勾选 + 行级 SQL 条件(如 region = '华东')→ 保存 PUT /roles/:id/permissions(body {table, column, row})。
  2. /admin/users → 注册一名普通用户并分配该角色。
  3. 同一查询(如"各区域订单销售额")分别用 admin 与普通用户在 /chat 执行——普通用户只见华东行(RLS 注入),敏感列被脱敏(CLS)。

操作 B:安全治理

  1. /admin/security → 概览卡(敏感列/RLS/CLS/审计总数/AI 护栏状态,GET /security/overview)。
  2. 敏感列 CRUD:类型 PII/FINANCIAL/HEALTH/CREDENTIAL,脱敏策略 full_mask/partial_mask/hash/tokenize/nullify → 配置 customer.phone=partial_mask → 普通用户查询验证。
  3. AI 护栏:PUT /security/guardrails(enabled + max_input_len 默认 4000)→ 在 /chat 输入超长文本验证拦截。
边界与教训:权限保存为整体替换(多人并行编辑互相覆盖);权限资源来自数据源元数据导入(未导入弹窗为空);行级条件纯文本无语法校验;脱敏登记后查询必须走 WithMasking 执行器防绕过;PII 护栏曾误伤中文 prompt,现为未配置默认关闭+结构化任务白名单透传。

4.6 本体 / 工具 / Agent 管理(/admin/ontology、/admin/tools、/admin/agents)

定位:AIP 侧的语义与工具治理三件套(与 Foundry 本体是两套系统:AIP 侧管"NLQ 怎么理解",Foundry 侧管"业务对象与动作")。

操作

  1. 本体建模/admin/ontology):对象(名称*+基础表*+同义词)/属性(维度|度量 Switch + 聚合 SUM/AVG/COUNT/MAX/MIN)/链接(基数 1:1/1:N/N:1/N:M + 连接条件)三 Tab + 只读本体图。语义:查询命中本体时以对象描述替代原始表结构注入 prompt——本体定义优先于 RAG。演示:给 order 表建对象"销售订单"并配同义词"订单/成交",回 /chat 用口语问验证命中率提升。
  2. 工具管理/admin/tools):工具列表(builtin/is_dangerous/enabled)+ 详情(参数 JSON Schema)+ 测试执行 POST /tools/:name/execute(参数校验/安全检查/超时/审计/RLS/CLS 全走);启停 PUT /tools/:name/enable。内置 query_data/get_table_schema/nlq_to_sql。演示:禁用 query_data → Agent 任务立即受阻 → 启用恢复。
  3. Agent 管理/admin/agents):编排 Agent 治理(name/display_name/role 四角色/capabilities chips/model_id/启用 Switch 即点即存);YAML 导出 GET /orchestrations/agents/export。为 §3.7 编排服务。
边界:危险工具执行无二次确认;Agent name 创建后不可改、删除为软删;priority/并发数由后端种子维护不可编辑。

4.7 运维状态(/ops)

定位:演示开场页——每 10s 轮询五产品 /health(3s 超时,degraded 也算异常的保守口径)+ AIP /license/info(授权到期/tier/shutdown_scheduled)。

  • 演示用法:开场先亮 /ops 全绿 → 结尾再回来看"平台健康可观测"。
  • 边界:纯前端轮询,进程启停无 API;健康端点含 /health、/health/live、/health/ready、/api/health。

5 Foundry 数据纵深

v5 评审修复后的关键行为口径(本节各页通用,演示前过一遍):
  • 查询标识符白名单:SQL 工作台/对象查询的引用标识符必须命中本体属性白名单,平台库任意表不可读(§5.1)。
  • 列级权限良性放行:未配置 COLUMN_ACCESS 的用户不再被全量拒绝(跳过注入+安全注记放行);显式配置后的拒绝仍 fail-closed(§5.1)。
  • 写路径参数白名单:动作 create/link 传未知参数键 → 422(参数限定 insert_columns 声明集或对象属性名,link 另受 param_schema 限死;非法标识符 400)。
  • 幂等重放如实回传失败:同 idempotency_key 重放 failed run 返回 replayed_failed + 原 error_code(不再"重放也是成功");success/pending 重放仍返回 replayed 的首次结果。
  • Fusion 并发互斥:同项目已有运行中的消解 run 时再次发起 → 409(§5.7,旧文档"并发 run 相互覆盖"口径作废)。
  • Foundry MCP 工具get_dataset 默认关预览(preview 显式 true 才返回数据)、非属主数据集 404execute_action 透传 idempotency_key(响应包为 {"idempotency_key":…,"result":…},按旧裸结果形状解析的客户端会读空)。
  • 数据面 admin-only:数据集/同步/管道等数据面操作统一用 admin 执行(§2.3)。

5.1 SQL 工作台(/foundry/sql)

定位:面向数据工程师的受限只读 SQL 控制台——"自由查询,但闸门是真的"。

操作

  1. SQL 工作台/foundry/sql)→ 输入 SELECT product_id, warehouse, stock_level FROM inventory WHERE stock_level < reorder_point → 点「翻译预览」POST /ontology/sql/translate:回显物理 SQL+绑定参数。
  2. 点「执行」POST /ontology/sql/execute:结果表格 + CSV 导出(纯前端)。
  3. 演示闸门:① 试 DELETE FROM inventory → 被拒(只读+单语句+白名单);② 用普通用户(配了 RLS 的)执行同 SQL → 结果行被行级过滤;③ 写个无 LIMIT 大查询 → LIMIT 自动钳制(默认 500、上限 5000);④ 配了 Markings(§5.13)的列,无权限者查询得 NULL;⑤ 试 SELECT * FROM "users"(平台库真实表)或反引号/派生表内引用表 → 被标识符白名单拒绝。
边界:不支持 linkName.prop 语法,跨对象需显式 JOIN;编辑态叠加绿色高亮提示注入的权限条件。
v5 修复后口径:引用标识符白名单——FROM/JOIN 表引用与 SELECT 列必须命中查询期本体属性白名单(映射物理列),带引号/反引号/schema 前缀等绕过形态一律拒绝,平台库任意表不可读;② CLS 良性放行——用户未配置任何 COLUMN_ACCESS 时跳过列级注入并附安全注记放行(不再误杀全部查询),显式配置了列权限后的拒绝仍 fail-closed。

5.2 Notebook(/foundry/notebook)

定位:分析笔记本:markdown/sql/chart 三类单元格,单格/全量运行,历史落库(fn_notebook_runs),SQL 复用 Ontology SQL 执行器(同样过 RLS/CLS/LIMIT)。

操作

  1. 新建笔记本 → 加 markdown 单元格写分析说明 → 加 SQL 单元格查低库存 → 加 chart 单元格做可视化 → 全量运行。
  2. 宏演示:先在 CodeRepo(§5.9)定义宏 {{macro:low_stock}},在 Notebook Execute 前自动展开(深度≤5)。
  3. 查看运行历史与耗时。
已知前端 bug(演示时规避):NotebookPage.vuerefreshCells() 调用了 listCells 但 import 缺失——添加/删除单元格、全量运行后会抛 ReferenceError后端数据已正确变更,仅前端列表/图表/提示受影响;刷新页面即可绕过。演示节奏:每次运行后手动刷新一次。另 markdown 预览为纯文本非富文本。

5.3 Dashboards(/foundry/dashboards)

定位:图表绑定本体对象→语义查询取数(RLS/CLS 内生)→仪表盘组装 + user/role 分享。

操作

  1. 新建仪表盘 → 添加图表(绑定 inventory 对象 + 过滤/聚合)→ 组装 2~3 张图 → 按 user/role 分享给普通用户。
  2. 用普通用户登录查看共享仪表盘——数据被 RLS/CLS 约束。
MVP 降级(诚实标注):本页图表以表格渲染,bar/line/pie 的 ECharts 视觉渲染未接入本页(chartBuilders 已被 Notebook/报表使用);无编辑入口、无发布切换、无布局拖拽、筛选器 UI 未暴露。演示话术:强调"语义取数+权限内生",图表美化属产品迭代项。

5.4 Reports 智能报表(/foundry/reports)

定位:把仪表盘/指标定时变报并主动分发:chart/text/table 三类块 → 生成 markdown+HTML 双形态快照 → email/internal 分发 → cron 调度自动生成。

操作

  1. 新建报表 → 添加块(chart 绑定对象、text 写结论文案、table 列低库存清单)→ 生成快照(markdown + HTML 双形态)。
  2. 分发:channel=internal(必现)+ email(当前 SMTP 未配会诚实失败)+ feishu(已配可用,降级标注 partial/degraded)。
  3. 配 cron 调度 → 到点自动生成新快照;看运行历史。
边界:无独立"重发历史 run"按钮(API 已备);前端无删除按钮。

5.5 Quality 数据质量(/foundry/quality)

定位:四类质量规则(如非空/唯一/范围/自定义 SQL)+ 问题闭环(open→acknowledged→fixed)+ 四因子画像(完整度/唯一度等,SQL 下推,sampled/na 诚实标注)。

操作

  1. 对 inventory 建规则:stock_level >= 0(范围)与 inventory_id 唯一。
  2. 跑数据集画像(GET /datasets/:id/profile)看四因子分。
  3. 故意插入一行 stock_level=-5 → 触发规则 → 问题列表出现 issue → acknowledge → 修复数据 → fixed(闭环演示)。
  4. 联动:同步成功自动触发画像(bridge 已接);管道 run 会执行 scope=pipeline 的 error 级规则并阻断目标对象同步(基础版 §5.2 提过,此处可展开演示)。
边界:object 作用域画像仅登记不计算;schedule 改动需重启生效。

5.6 Stream 流事件规则(/foundry/stream)

定位:Foundry 侧的事件驱动引擎(与 AIP event 工作流互补):CDC watcher 绑定 + 条件表达式 + 五类动作(webhook / notification / sync_run / quality_run / writeback)。

操作

  1. 先确保有 CDC watcher(数据源变更捕获)。
  2. 建规则:监听 inventory 变更,条件 stock_level < reorder_point → 动作 notification(站内)+ writeback(如自动写审计备注)。
  3. 用「测试触发」走真实流水线验证;幂等保证:(rule_id,event_id) 唯一索引,同一事件不会重复触发动作。
  4. 对照演示:同一库存变更同时被 Foundry Stream 规则(落库侧反应)与 AIP event 工作流(编排侧反应,基础版 §5.5)捕获——两套引擎各司其职。
边界:sync_run/quality_run/writeback 依赖服务注入,未装配时动作记 failed;webhook 动作 SSRF fail-closed;必须先有 CDC watcher。

5.7 Fusion 实体消解(/foundry/fusion)

定位:多源数据"同一个人/同一商品"合并:规则分桶 + 加权打分(exact/prefix/levenshtein)+ union-find 聚类 + 人工确认/拒绝 + survivorship 选主写回(in_place_edit 或 materialize)。

操作

  1. 准备两个含重复实体的源(如 customers 表导入两次,名称略有差异)。
  2. 建消解作业:选字段映射与匹配规则 → 运行(异步 run + 1.5s 轮询)→ 看聚类结果与相似度打分。
  3. 人工确认/拒绝候选合并 → survivorship 规则选主记录 → 写回(in_place_edit 原地改 / materialize 物化新表)。
LLM 复核可选:未注入自动降级纯规则(设计行为,非缺陷)。
v5 修复:同项目并发 run 互斥——已有运行中的消解 run 时再次发起返回 409(进程内互斥 + running 计数兜底),旧文档"并发 run 相互覆盖"口径作废。
已知问题:IngestionSource.Enabled 的 GORM bool default:true 覆写问题未修——显式传 false 可能被存为 true,演示时留意。

5.8 Functions 本体函数(/foundry/functions)

定位:声明式注册可复用计算函数(fon_functions):name 正则 + body 语法检查,测试面板即时求值,用户函数互调递归≤5。

操作

  1. 注册函数如 gap_to_reorder(stock_level, reorder_point) = reorder_point - stock_level
  2. 测试面板传入参数即时求值。
  3. 注册第二个函数调用第一个(演示互调);可在 Metrics/语义层引用函数作为计算口径。
边界:计算属性 Formula 引用函数时 semantic 层降级为 NULL+标注(不报错)。

5.9 CodeRepo 代码仓库(/foundry/coderepo)

定位:snippet/template/macro 三类代码资产仓库:文件版本覆盖归档+恢复;宏 {{macro:name}} 在 SQL 工作台/Notebook Execute 前自动展开(深度≤5,未命中原样传)。

操作

  1. 建 macro:low_stock = stock_level < reorder_point
  2. 在 SQL 工作台写 SELECT * FROM inventory WHERE {{macro:low_stock}} → 执行前自动展开。
  3. 用页面内置展开调试端点看展开结果;修改 macro 后版本归档,可恢复旧版。
刻意不做 git 协议——定位是"平台内轻量代码资产复用"。

5.10 Marketplace(/foundry/marketplace)

定位:平台资产商店:六类来源(object/metric/dashboard/app/notebook/fusion)发布为快照商品(fm_items),rid 版本链、重发布 v+1、一键安装(重名自动加 _imported_<ts>)。

操作

  1. 把 inventory 对象(或某仪表盘/笔记本)发布到 Marketplace → 生成快照商品。
  2. 修改对象后重新发布 → 版本 v+1。
  3. 「安装」到另一环境/重装 → 新增 _imported_<ts> 副本。
  4. unlisted 商品安装被拒——治理口径演示。
边界:安装失败会写 fm_installs 记录但不返回 HTTP 错误,需到安装详情行看失败原因。

5.11 MLOps 模型管理(/foundry/mlops)

定位:模型注册/版本/部署/回滚/预测/预测日志全链路;本体集成(预测注册为计算属性、PredictForObject)。

操作

  1. 注册一个 rule 类型模型(规则数组匹配,如"stock_level < reorder_point → 补货")→ 发布版本 → 部署。
  2. 对对象行发起预测 → 预测结果可注册为计算属性 → 预测日志可查。
  3. 回滚演示:发布 v2 → 回滚 v1。
核心限制(必讲):推理引擎仅 ruleexternal_api(HTTP 转发)可执行;onnx/pmml/pickle/docker_image 可注册但预测报"暂不支持"。部署为记录式(登记端点非真实编排);部署配置用浏览器 prompt 输入 JSON。

5.12 Apps 低代码应用(/foundry/apps)

定位:应用→页面→组件三层低代码搭建:DataBinding JSON 绑定本体语义查询取数,发布 draft→published。

操作

  1. 新建应用「库存助手」→ 加页面 → 拖组件:metric_card(库存总量)+ table(低库存清单,DataBinding 绑 inventory 对象)+ text + object_detail。
  2. 发布 → 与普通用户共享查看。
边界(必讲):8 类组件中仅 table/object_detail/metric_card/button/text 真实渲染;chart/filter_bar/form 为占位提示;button 点击仅 alert"待接线"(后端 action_trigger 已实现但前端未接 UI);发布无独立运行 URL;布局字段不生效。

5.13 Markings 数据打标(/foundry/markings)

定位:密级打标(如内部/敏感/机密)+ 四类目标绑定(表/列/数据集/指标)+ 用户授权矩阵;作为 ApplyCLS 之外第二道列级闸门——未持权查询该列得 NULL(不报错、静默遮蔽)。

操作

  1. 建密级「内部」→ 绑定 customer.phone 列 → 授权矩阵只给 admin 持权。
  2. 普通用户在 SQL 工作台/对象查询查 phone → 得 NULL;admin 查 → 正常返回。
边界:全部接口 admin 门禁(普通用户 403,演示时切换账号);dataset/metric 绑定不校验存在性;/markings/users 依赖 RBAC 注入否则 500。

5.14 Governance 数据治理(/foundry/governance)

定位:术语表(可关联本体属性)+ 分类标签(0-3 级打到属性)+ 属性治理汇总 + 保留策略 CRUD/启停。

操作

  1. 术语表登记"补货点 reorder_point"并关联 inventory.reorder_point 属性——统一业务黑话。
  2. 给敏感属性打分类标签(等级 0-3)。
  3. 建保留策略(如日志类数据保留 90 天)并启用。
边界:保留策略仅元数据管理,到期执行依赖后端调度器(页面无执行展示)。

5.15 API Keys(/foundry/api-keys)

定位:程序化访问凭证:lfk_ 前缀长凭证,SHA256 哈希存储、明文一次性展示、撤销/删除/公开 verify 端点;Bearer lfk_… 可直接过认证中间件。

操作

  1. 创建 Key → 明文只展示一次(截图保存)→ 用 curl -H "Authorization: Bearer lfk_…" 调一个只读端点(如 GET /api/v1/ontology/objects)验证。
  2. 撤销 Key → 再调 → 401(verify 公开端点亦可查状态)。
重要口径(必讲):API Key 的权限随绑定的平台用户角色继承(Key 是绑定用户的能力代理;实测 admin 绑定的 Key 可执行写操作,如 POST /markings → 201);scopes 仅存储/返回、不强制执行——scope 闸门 helper(apiKeyScopeGate())已就绪但默认不挂载,写路径不额外按 scope 限制。因此定位为集成/演示用途的凭证请绑定最小权限账号、勿外泄,也不要宣传成细粒度授权。

6 产品矩阵延伸(P3 / P4 / P5)

主线是 AIP+Foundry;本节给每条延伸产品线 1~2 个最小闭环(10~15 分钟/条),作为"平台全景"收尾演示。各产品独立登录、独立用户库(默认 admin/admin1)、演示数据互不联通。

6.1 Apollo(/apollo,端口 18082,前缀 /apollo-api)——交付运维

定位:供应链规划/交付运维:期望状态(desired state)+ 部署编排 DAG + 漂移检测自愈 + Spoke Agent 拉取。判定:可演示(Agent 为演示级)。

闭环 ①:部署 DAG 门控

  1. /apollo/login(独立登录)→ 部署总览确认 seed 的 demo-app(v1.0.0,web 依赖 db 验证 DAG 门控)已激活、stable 渠道存在。
  2. /apollo/deployments → 发起部署到 spoke-01 → 观察 db 先 ready、web 后放行的分批推进 → 手动 advance 到 synced。

闭环 ②:漂移检测自愈

  1. 进漂移检测页 → detect → 查看字段级 JSON Patch diff → reconcile 收敛 → has_drift=false 回 synced。
  2. 可选:告警自愈(health-checks/incidents/healing-policies/healing-history 审批 approve|deny)。
边界(诚实标注):演示 Poller 只拉取/上报、不真实拉起进程(未挂 ProcManager);Git 仓库为本地目录模拟;v5 前端文档仅 index(正文 19 篇未写),机制介绍可参考 docs/site-v4/apollo.html
v5 修复后口径(三个严格开关缺省=旧行为,未强制):AGENT_AUTH_STRICT=1 才拒绝未登记 Agent 的 pull/report(缺省放行=旧行为);② GITOPS_WEBHOOK_REQUIRE_SECRET=1 时未配 secret 的仓库拒绝 webhook(已配 secret 的仓库无论开关都强制 HMAC 验签,无签/错签 401);③ ALERT_WEBHOOK_STRICT=1 时出站 webhook 连环回地址也拒绝(缺省仅拒私网/链路本地,环回放行)。另两项写路径变化:pipeline (definition_id, run_number) 唯一约束——并发触发同一定义不重号,冲突方 409;git 仓库 webhook_secret/auth_config 只写不回传,编辑时留空=保持不变(不会清掉已登记密钥)。

6.2 Gotham(/gotham,端口 18083,前缀 /gotham-api)——情报分析

定位:对标 Palantir Gotham:图谱构建/分析/时空/多源融合/实体解析/模式识别/报告/ABAC。判定:可演示(resolution AI 裁决已接线,patterns AI 增强 V2 预留)。seed 自带「玄武集团」图谱(10 节点 8 边)+ 地图要素/轨迹 + 时间轴事件。

闭环 ①:图谱研判

  1. /gotham 工作台浏览玄武网络 → 对"玄武集团"做 1-2 度展开看邻居高亮。
  2. 最短路径分析:"张远→赵敏"资金链路(图算法接口需 admin)→ 新增节点/边写图(graph/nodes|edges|merge)。

闭环 ②:接入到产出全链

  1. /gotham/ingestion 建 file_csv 源并运行(SSE 进度条,可暂停恢复)。
  2. /gotham/resolution 建解析作业(四层打分,勾 enable_ai 且后端配了 LLM key 即真走 AI 裁决)+ 人工审核确认合并。
  3. /gotham/patterns 全量评估(预置 6 条规则)生成告警 → 确认/处置。
  4. /gotham/reports 生成/发布/导出 PDF/DOCX。

加分项

  • /gotham/views 多视图联动广播(target_count);/gotham/collab WebSocket 实时协同(开双窗口);/gotham/tasks 拖拽看板;/gotham/access ABAC 试算留痕(evaluate/traces,PEP 写门);地图 /map/*(热力/轨迹,依赖在线 OSM 瓦片);时间轴 forecast/compare。
边界:resolution 的 AI 裁决层已接线(未配 LLM key 时灰区降级,见 Gotham 篇 §5.2);patterns 的 LLM 增强仍 V2 预留,但其 anomaly 已支持 target=geo(区域密度)与 target=graph(degree_burst/orphan_burst)评估;图谱 SVG 全量渲染百节点以上卡顿、力导布局不持久化。
v5 修复后口径:① 数据源接口(/ingestion/sources 系列与批次暂停/恢复)admin-only(普通角色建源/运行 403,批次列表/进度/融合实体保持认证可见);口令掩码——响应 password 恒空、仅 password_set 标记。② reports 图片块走 data:image 白名单:png/jpeg/gif/webp 与纯 base64 放行,svg/bmp/tiff 写入期 422、历史脏数据渲染为占位(报告贴图用 png 截图)。③ WebSocket 协同/看板联动按房间成员校验:非项目成员订阅被静默拒绝(无回执),收不到该项目广播——双窗口演示用同项目成员账号。④ GOTHAM_DEMO=1 仅用于弱 SECRET_KEY 启动放行;文件/数据库导入白名单由 GOTHAM_IMPORT_DIRS/GOTHAM_DB_HOSTS 是否配置决定(配置后强制生效,未配置不启用约束),与 GOTHAM_DEMO 无关。

6.3 Swift(/swift,端口 18084,前缀 /swift-api)——卫星结算(仿真)

定位:SWIFT+卫星通信金融结算,星上结算、国密通信。判定:仿真/演示级——链路真实可跑,星座拓扑/账户/清算通道均为模拟,不做投产承诺

闭环 ①:报文实验室

  1. /swift/messages 生成 pacs.008 报文(DRAFT)→ SM3+SM2 国密签名 → 篡改后 verify 拒绝(或 /swift/gac 用 tamper-test)。

闭环 ②:一键 10 步演示(HCC 管控台)

  1. /swift/hcc 点「一键演示」(/demo/run + /demo/status)→ 分步观看:GAC 报文生成 → 国密签名 → 端到端加密(SM2 协商+SM4-GCM 信封)→ 星地链路传输(含断链缓存补发恢复)→ HCC 解密验签解析 → 合规筛查(制裁名单+KYC+LLM 辅助)→ 风控额度 → 结算记账/对账。
  2. 看支付状态机流转与分步 status/detail/data。
边界:使用独立演示 GAC 客户端与 DemoTopology,不污染正式数据;星座拓扑/链路/余额/外部清算均为模拟。价值链话术:五产品闭环=Foundry(数据)→AIP(智能)→Gotham(决策)→Apollo(交付)→Swift(创新·仿真),详见 docs/story/cross/value-chain.html
v5 修复后口径:HCC 发送方固定 SM2 验签:接收帧必带发送方公钥(明文路径强制验签、信封路径用 GAC 证书固定公钥),错签/无签/篡改一律拒绝,"验签通过即伪造"已根除。② 结算反向冲正:手续费记账失败自动反向冲正本金;冲正再失败显式升级"账目需人工核查"(无静默半结算)。③ SWIFT_DEMO=1 语义=弱 SECRET_KEY 的演示放行开关(缺省弱值拒绝启动,config.yaml 加载成功路径同样校验,放行时 Warn 留痕)。

7 分步验收测试单(扩展)

在基础版 14 项验收(见 ai-action-demo.html §6)之外追加。勾选式 PASS/FAIL;实现程度见 §1.1。

#验收点操作(详见节)通过标准
E1前置链铺满§1.2 / §2.1LLM 网关路由含 entity_extract 且试调通;RAG 索引重建返回 indexed>0
E2知识库建+检索§3.1保存返回 chunk_count>0;search 命中;回滚生效
E3分层树+pdf 上传§3.2三层树生成;pdf 成功或 pdf-degraded 诚实降级
E4实体抽取+人工确认§3.3抽取任务完成;confirm 后实体入 RAG entity 通道;reject 不入
E5RAG 五段上下文§3.4/rag-test 返回 channels_used 含 knowledge/entity;latency 可见
E6决策证据链§3.55 步链完成、引用可溯源、trace_id 在 ai-audit 可查
E7会话记忆§3.6多轮追问生效;清空后失忆;失败轮次不写记忆
E8多智能体编排§3.7parallel 与 debate 各出一次融合结果;历史可查
E9LLM 网关治理§4.1路由热同步;用量数字增长;降级链兜底生效
E10Prompt 版本安全网§4.2+§4.3改 Prompt→评测回归告警→回滚→恢复(完整闭环)
E11监控与反馈§4.4概览指标非空;提交反馈后统计变化
E12RLS/CLS/脱敏/护栏§4.5普通用户行级过滤生效;敏感列脱敏;超长输入被护栏拦截
E13SQL 工作台闸门§5.1写操作被拒;LIMIT 钳制;无权限列返回 NULL;引用平台库表被白名单拒绝;未配列权限可正常查询(注记放行)
E14Notebook 运行§5.2SQL 单元格出结果、历史落库(刷新页面绕过已知前端 bug)
E15报表生成分发§5.4快照生成(markdown+HTML);internal 分发落通知
E16质量闭环§5.5违规→issue→acknowledge→fixed 全链走通
E17Stream 规则触发§5.6测试触发走真实流水线;同事件不重复触发(幂等)
E18Fusion 消解§5.7聚类+人工确认+写回生效;同项目并发第二次发起 409
E19Marketplace 发布安装§5.10发布→重发布 v+1→安装出现 _imported 副本
E20Markings 双闸门§5.13无持权用户查询绑定列得 NULL
E21API Key 鉴权访问§5.15Bearer lfk_ 过认证调端点(权限随绑定用户角色);撤销后 401
E22Apollo 部署+漂移§6.1DAG 分批推进到 synced;reconcile 后 has_drift=false;同定义并发触发不重号(冲突 409)
E23Gotham 图谱全链§6.2展开/路径分析出结果;接入→解析→规则→报告四步走通(数据源接口 admin-only,普通角色 403;报告图片按 data:image 白名单渲染)
E24Swift 国密链路§6.3签名/验签/篡改拒绝(发送方固定公钥验签);一键演示 10 步走完

8 常见坑与应对(本版补充)

症状原因 / 应对
/entity-extract 抽取直接报错LLM 网关未配 entity_extract 路由(无降级路径):先到 /admin/llm-gateway 确认路由并试调(§2.1)。
/rag-test 检索结果为空索引未建或知识库为空:先建知识库/导元数据,再 POST /rag/index/rebuild;另注意检索按用户隔离(无身份 fail-closed 返回空)。
Notebook 添加单元格/全量运行后前端报 ReferenceError已知前端 bug(listCells 未 import):后端数据已正确变更,刷新页面绕过(§5.2)。
评测长时间不返回/失败评测超 15s 任务化返回 202,但前端未轮询任务接口:用小评测集演示。
报表/工作流 email 渠道失败config.yaml 当前 SMTP 未配(email 三项均空)——属诚实失败设计:配 SMTP 或改用 internal/feishu 渠道。
/foundry/markings 接口 403全部 admin 门禁:切 admin 账号演示;/markings/users 依赖 RBAC 注入否则 500。
API Key 能读不能写未必:Key 权限随绑定用户角色继承(admin 绑定的 Key 可写);「写路径拒绝」仅出现在绑定用户无相应角色的场景。要只读就绑定只读账号(§5.15)。
Fusion 数据源启用开关不生效已知 GORM bool default:true 覆写问题(IngestionSource.Enabled 未修):显式确认库内值。
SQL 工作台查询被拒(不在白名单/拒绝执行)v5 修复后引用标识符必须命中本体属性白名单:用对象属性名查询,勿直接引平台库任意表;未配列权限的用户可正常查(良性放行+注记)(§5.1)。
动作执行/重放结果与预期不符create/link 传未知参数键 422(参数限动作声明集合);重放 failed run 返回 replayed_failed+原 error_code(如实回传失败,不再"重放也是成功")(§5 前言)。
Fusion 同项目第二次运行报 409v5 并发互斥(旧"并发覆盖"口径作废):等上一 run 结束后再发起(§5.7)。
Gotham 数据源页 403 / 口令看不到数据源接口 admin-only + 口令掩码(password 恒空、仅 password_set):切 admin 演示(§6.2)。
Gotham 报告图片不显示data:image 白名单:png/jpeg/gif/webp 放行,svg/bmp/tiff 拒绝(渲染为占位)——贴图用 png(§6.2)。
Gotham 协同窗口收不到广播ws 房间按项目成员校验,非成员订阅被静默拒绝:双窗口用同项目成员账号(§6.2)。
重启后 admin 密码"不对了"admin 密码不再被启动覆盖(First-or-Create);忘记密码用 DEFAULT_ADMIN_RESET=1 显式重置(§2.3)。
服务起不来报 SECRET_KEY 弱值v5 修复后弱值/缺失拒绝启动(含 config.yaml 成功路径):配强密钥,或演示显式 AIP_DEMO/FOUNDRY_DEMO/GOTHAM_DEMO/SWIFT_DEMO=1(Apollo 无开关)(§2.2)。
编排长时间执行/超时(决策 300s)同步执行模型:编排前端 timeout 600s(实测长链路 5-6 分钟)、决策 300s——任务描述精简、评测集小、上下文 JSON 合法;LLM 慢时先看 /admin/llm-gateway 用量与熔断状态。
Dashboards/ Apps 图表"不好看"MVP 降级为表格渲染/组件占位——按 §5.3/§5.12 话术讲"语义取数+权限内生",不硬拗视觉效果。
Gotham 大图卡顿SVG 全量渲染百节点以上卡顿:用 seed 小图谱演示;力导布局纯前端不持久化。
角色权限"改了又变回去"权限保存为整体替换(PUT /roles/:id/permissions):单人编辑、或保存前看清全量勾选状态。
Windows 启停/端口同基础版 §8:停进程用 PowerShell Stop-Process;五产品端口 18080~18084;bash 命令带 cd 全路径 && 前缀。

9 相关文档索引

  • 基础版方案(先跑通)action/docs/ai-action-demo.html
  • 前端页面操作手册action/docs/frontend-intro-v5/markdown/aip/(36 篇)、foundry/(30 篇)、gotham/(16 篇)、apollo/index.mdswift/index.md(另有同名 html 版)
  • 业务故事站docs/story/aip/(知识库/实体抽取/意图RAG/LLM网关/安全治理等 17 篇)、docs/story/foundry/(quality/fusion/marketplace/notebook/mlops/stream/markings 等 25 篇)、docs/story/cross/(value-chain、fde-deployment、combined-demo 等)
  • 模块开发文档wiki/docs/aip/wiki/docs/foundry/wiki/docs/gotham/;架构与计划:wiki/upgrade-v5/UPGRADE-PLAN.mdwiki/OVERVIEW.mdwiki/ROADMAP.md
  • 经验与进展wiki/dev_info.md(跨产品通用坑)、wiki/dev_progress.md(注意:止于 v4 里程碑,v5 判定以本文档核实口径为准)、wiki/dev_memory/
  • Apollo 机制参考docs/site-v4/apollo.html(v5 正文文档未写时的兜底)
  • 前端源码web/src/router/index.js(路由全表)、web/vite.config.js(前缀分流 /api→18081、/aip-api→18080、/apollo-api→18082、/gotham-api→18083、/swift-api→18084)