完善版「AI 行动系统」Demo 落地方案
在基础版(ai-action-demo.html:数据源→管道→本体→查询→工作流→Copilot→审批→通知→证据)之上,把平台其余全部已实现功能纳入演示:知识库与 RAG、实体抽取、决策证据链、多智能体编排、LLM 网关、评测监控、安全治理、SQL 工作台、Notebook、报表、质量、流事件、实体消解、Marketplace、MLOps、低代码应用,以及 Apollo / Gotham / Swift 三条延伸产品线。
▎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 | 依赖 LLM | LLM 抽实体/关系→人工确认→进 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 | 前端有 bug | markdown/sql/chart 单元格,历史落库(详见 §5.2 边界) | |
Dashboards /foundry/dashboards | MVP 降级 | 图表绑定本体语义查询,表格渲染(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、编排等页面的多通道效果出不来:
2 前置准备(扩展项)
2.1 LLM 网关路由检查(含 entity_extract)
- 登录 admin → 管理后台 → LLM 网关(
/admin/llm-gateway)→ Provider 状态区确认 deepseek available、health 正常、熔断状态 closed。 - 路由规则区确认
entity_extract、nlq、text2sql、analysis、chat等任务类型的路由存在且候选 provider 正确。实体抽取没有规则降级路径:网关未配entity_extract路由时 /entity-extract 抽取直接报错(§3.3)。 - 用「网关试调」
POST /llm/chat选任务类型 entity_extract 试调一次,确认链路通。
cost_limit_cents 单次调用预算 0=不限;/llm/chat 直连端点不经过 PIIGuard 脱敏(内部 LLM 消费默认脱敏,直调不脱敏是已知口径)。2.2 config.yaml 现状与本版相关的项
| 配置节 | 当前实际状态 | 影响 |
|---|---|---|
llm | deepseek 主力(openai 兼容通道亦指向 deepseek-v4-flash),dashscope 承担 embedding | 智能纵深线全部可用 |
feishu.enabled | true(app_id/secret 已配,default_channel: copilot) | 飞书推送/卡片可用;报表 feishu 渠道可试 |
email | username/password/server 均为空 | 邮件通知实际不可用:Reports 的 email 分发、工作流 email 渠道会失败——演示前要么配 SMTP,要么走 internal 渠道并讲"诚实失败"设计 |
foundry.oag.enabled | true(base_url 复用 18081) | Copilot/OAG 动作路可用(基础版已覆盖) |
gotham.graph.mode | "disk"(JSON 落盘 temp/gotham_graph.json) | Gotham 不依赖 neo4j,直接可演示 |
workbuddy.enabled | true(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) |
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)。
操作
- 进 知识库页(
/knowledge)→ 新建目录(名称* + 上级目录 + 描述 →POST /knowledge/directories),建议建「补货口径」目录承载主剧情的业务规则。 - 新建文档:格式 text/markdown/html,填标题/所属目录/标签/内容(如"补货规则:库存低于补货点即创建采购申请,审批人=采购经理")→ 保存。
- 修改内容再保存 → 版本 +1;用「回滚」
POST .../versions/:v/restore演示版本回退。 - 用「知识检索」
POST /knowledge/search(top_k 固定 10)搜"补货规则"验证召回。
怎么验
- 保存响应含
chunk_count>0;检索命中刚建的文档;回滚后内容复原、版本时间线正确。
3.2 知识分层树(/knowledge-tree)
定位:把文档升级为三层结构 document→section→chunk(kdoc_nodes):markdown 按 #/##/### 生成 section;支持 pdf/docx 上传(前端转 base64,创建超时 120s);检索结果带 node_path 标题链与来源标注(新旧双表合并去重)。
操作
- 进
/knowledge-tree→ 上传一份 pdf/docx(或粘贴多级标题 markdown)→ 查看自动生成的分层树。 GET .../outline看文档大纲;用检索验证来源标注(src-tree 分层树 / src-blocks 旧表)。
怎么验
- 树形结构正确;pdf 解析成功(失败时回退纯文本,标注
parser=pdf-degraded——这是诚实降级不是错误);检索结果带标题链。
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 溯源。
操作
- 进 实体抽取页(
/entity-extract)→ 选一份知识库文档(如补货规则文档)→ 点「抽取」→POST /knowledge/documents/:id/extract任务化返回{run, task},前端每 2s 轮询GET /extract_runs(上限约 4 分钟)。 - 实体表逐行确认/拒绝(
POST /entities/:id/confirm|reject)——演示"AI 抽取 + 人工把关"。 - 看 ECharts 力导向关系图(
GET .../graph)。
怎么验
- 实体状态 auto→confirmed;被拒绝实体不进 RAG entity 通道(可在 /rag-test 对比确认前后的检索差异)。
entity_extract 路由则直接报错,无规则降级路径——演示前务必先过 §2.1。其它边界:单 chunk 6000 字符、置信度默认 0.6、实体扫描上限 1000、关系只读不可编辑。3.4 RAG 配置与检索测试(/admin/rag、/rag-test)
定位:RAG 是 NLQ 准确率的底座。配置页调四固定通道(metadata/knowledge/history/fewshot)权重;测试页可视化一次检索的五段上下文。
操作
- RAG 配置(
/admin/rag):调权重(step 5%,保存换算 0-1);合计偏差 >0.5% 弹 confirm 归一化(末位通道吸收漂移)→PUT /rag/channels。演示把 knowledge 通道调高后再问口径类问题。 - 索引重建:
POST /rag/index/rebuild(可带 data_source_id,空=全量;返回 indexed/item_count)。前置链第 ⑤ 步在此执行。 - 检索测试(
/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 返回空)。
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)。
操作
- 进 决策证据链页(
/decision)→ 问"补货规则是什么?当前哪些库存低于补货点?"(前置链铺满时 rag/entity/nlq 三路全命中)。 - 逐步看 5 步状态与耗时;点开引用核对出处(知识库 chunk、实体、查询结果)。
- 历史回放:
GET /decision/answers?limit=20、GET /decision/answers/:id。 - 到
/admin/ai-audit用 trace_id 查决策审计记录——证据链闭环。
怎么验
- 答案带引用列表且可溯源;单步失败降级继续并标注(不是报错中断);markdown 渲染经 DOMPurify 防 XSS。
3.6 会话记忆(/memory-manage)
定位:NLQ 多轮追问的记忆管理。机制:以 user_id 为会话键,仅查询成功才写记忆;最近 6 轮原文 + 更早轮次 LLM 压缩摘要;正则抽取表/指标实体提及;每日 4 点调度清理 30 天前记忆。
操作
- 先在
/chat连续问 3~5 个相关问题(如"各区域销售额"→"华东呢"→"环比上月")。 - 进 记忆管理页(
/memory-manage)→ 会话列表(GET /chat/sessions)→ 点「查看记忆」(GET /chat/sessions/:sid/memory)看原文轮次+摘要+实体提及。 - 回 /chat 用指代词追问,展示多轮上下文生效。
- 点「清空本会话记忆」(DELETE,二次确认,返回
{deleted:N})→ 追问立刻"失忆"。
3.7 多智能体编排(/orchestrate)
定位:多个角色 Agent 协作完成一个任务。策略四种:sequential / parallel / leader_follow / debate。子任务按 required_role(finance/supply_chain/sales/general)匹配角色 Agent。
操作
- 先在 Agent 管理(
/admin/agents)确认各角色 Agent 存在且启用(bootstrap 种子维护,见 §4.6)。 - 进 多智能体编排页(
/orchestrate)→ 选策略(建议先 parallel 再 debate 对比)→ 填任务描述(如"分析当前库存低于补货点的商品,从财务和供应链两个视角给出补货建议")→ 提交POST /orchestrations(同步执行,前端 timeout 600s)。 - 就地查看子任务列表与融合结果;历史分页表可看详情/结果。
怎么验
- 不同策略的子任务编排/融合结果有差异;落 orchestration 历史与 AI 审计。
sub_tasks 手动指定但前端未暴露;partial_complete 状态不支持取消;context 必须合法 JSON;Agent 注册/注销/YAML 导出在 admin 权限(GET /orchestrations/agents/export)。4 AIP 治理与运营纵深
4.1 LLM 网关(/admin/llm-gateway)
定位:所有 LLM 调用的统一收口:Provider 管理、路由规则、预算与熔断、降级链、用量成本。演示"AI 成本与稳定性可治理"。
操作
- Provider 状态:deepseek/qwen/local_rule 的 available/model/cost_per_1k/circuit_state/health。
- 路由规则编辑:「编辑路由」→ 预算开关、user_limit_cents/app_limit_cents、候选
provider_order、降级链fallback_order→PUT /llm/routes/:id落库+热同步(重启不丢)。 - Provider 配置:
PUT /llm/providers/:id——api_key AES-256-GCM 加密落库、不回显,留空=不改。 - 用量概览:
GET /llm/usage(总调用/Tokens/延迟/成功率/成本/降级次数)——跑完智能纵深线后回来看数字。 - 演示熔断降级:把某路由 provider_order 只留一个错误 key 的 provider → 触发熔断 → fallback_order 兜底(如 qwen 或 local_rule)→ 恢复。
4.2 Prompt 管理(/admin/prompts)
定位:Text2SQL/意图识别等 Prompt 模板的版本化管理:改 Prompt 不用发版。
操作
- 模板列表(name/model_family/version/active)→ 新建
POST /prompts/templates或编辑PUT /prompts/templates/:name(保存即新建版本并置 active;编辑不可改名)。 - 版本管理
GET .../versions+POST .../versions/:v/rollback——演示改坏 Prompt 后一键回滚。 - 试算
POST /prompts/compile:填{{var}}变量,Go text/template 本地渲染返回 rendered/estimated_tokens/warnings(不调 LLM,零成本预览)。
4.3 评测管理(/admin/eval)
定位:Text2SQL 质量量化:测试用例库 + 评测运行 + 回归告警。
操作
- 测试用例 Tab:类别 simple_select/join/aggregation/subquery/window,难度 easy/medium/hard,问题*+期望 SQL*;
GET /evaluation/test-cases/export导出 JSON(bootstrap 已种默认评测集)。 - 评测运行:点「运行评测」→
POST /evaluation/runs(timeout 120s)→ 指标:执行准确率 EA / 精确匹配 EM / 语法有效率 SV / 通过用例 / 平均延迟 / Tokens;用例结果可展开比对生成 SQL。 - 历史与回归:
GET /evaluation/reports——EA/EM/SV 较上次下降 >2% 触发regression_alerts告警标红。 - 串联演示:改一处 Prompt(§4.2)→ 跑评测 → 回归告警 → 回滚 Prompt → 再跑恢复。这就是"Prompt 变更安全网"的完整故事。
4.4 监控看板(/admin/monitoring)
定位:查询质量与 LLM 健康度仪表板。
操作
- 概览:查询总数/成功率/平均与 P95 延迟/总 Tokens/LLM 失败率(
GET /monitoring/metrics,聚合 nlq_query_logs 与 LLM 调用日志)——演示前先在 /chat 多问几条攒数据。 - 历史趋势:
GET /monitoring/history?window=1d|7d|30d(柱=查询量,线=延迟/成功率)。 - 反馈统计:
GET /feedback/stats——平均评分/1-5 星分布/类型分布(sql_correct|sql_syntax_error|wrong_result|misunderstood)。配套动作:在 /chat 查询结果页提交一次反馈(POST /feedback),回监控页看数字变化。
4.5 RBAC / 用户 / 安全治理(/admin/roles、/admin/users、/admin/security)
定位:"不同人看到不同数据"的一等治理能力:表/列/行三级权限 + 敏感列脱敏 + AI 护栏。
操作 A:行级权限对比(最有说服力)
/admin/roles→ 角色权限配置弹窗:TABLE_ACCESS / COLUMN_ACCESS / ROW_LEVEL_FILTER 三类勾选 + 行级 SQL 条件(如region = '华东')→ 保存PUT /roles/:id/permissions(body{table, column, row})。/admin/users→ 注册一名普通用户并分配该角色。- 同一查询(如"各区域订单销售额")分别用 admin 与普通用户在 /chat 执行——普通用户只见华东行(RLS 注入),敏感列被脱敏(CLS)。
操作 B:安全治理
/admin/security→ 概览卡(敏感列/RLS/CLS/审计总数/AI 护栏状态,GET /security/overview)。- 敏感列 CRUD:类型 PII/FINANCIAL/HEALTH/CREDENTIAL,脱敏策略 full_mask/partial_mask/hash/tokenize/nullify → 配置 customer.phone=partial_mask → 普通用户查询验证。
- AI 护栏:
PUT /security/guardrails(enabled + max_input_len 默认 4000)→ 在 /chat 输入超长文本验证拦截。
4.6 本体 / 工具 / Agent 管理(/admin/ontology、/admin/tools、/admin/agents)
定位:AIP 侧的语义与工具治理三件套(与 Foundry 本体是两套系统:AIP 侧管"NLQ 怎么理解",Foundry 侧管"业务对象与动作")。
操作
- 本体建模(
/admin/ontology):对象(名称*+基础表*+同义词)/属性(维度|度量 Switch + 聚合 SUM/AVG/COUNT/MAX/MIN)/链接(基数 1:1/1:N/N:1/N:M + 连接条件)三 Tab + 只读本体图。语义:查询命中本体时以对象描述替代原始表结构注入 prompt——本体定义优先于 RAG。演示:给 order 表建对象"销售订单"并配同义词"订单/成交",回 /chat 用口语问验证命中率提升。 - 工具管理(
/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 任务立即受阻 → 启用恢复。 - Agent 管理(
/admin/agents):编排 Agent 治理(name/display_name/role 四角色/capabilities chips/model_id/启用 Switch 即点即存);YAML 导出GET /orchestrations/agents/export。为 §3.7 编排服务。
4.7 运维状态(/ops)
定位:演示开场页——每 10s 轮询五产品 /health(3s 超时,degraded 也算异常的保守口径)+ AIP /license/info(授权到期/tier/shutdown_scheduled)。
- 演示用法:开场先亮 /ops 全绿 → 结尾再回来看"平台健康可观测"。
- 边界:纯前端轮询,进程启停无 API;健康端点含 /health、/health/live、/health/ready、/api/health。
5 Foundry 数据纵深
- 查询标识符白名单: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 才返回数据)、非属主数据集 404;execute_action透传idempotency_key(响应包为{"idempotency_key":…,"result":…},按旧裸结果形状解析的客户端会读空)。 - 数据面 admin-only:数据集/同步/管道等数据面操作统一用 admin 执行(§2.3)。
5.1 SQL 工作台(/foundry/sql)
定位:面向数据工程师的受限只读 SQL 控制台——"自由查询,但闸门是真的"。
操作
- 进 SQL 工作台(
/foundry/sql)→ 输入SELECT product_id, warehouse, stock_level FROM inventory WHERE stock_level < reorder_point→ 点「翻译预览」POST /ontology/sql/translate:回显物理 SQL+绑定参数。 - 点「执行」
POST /ontology/sql/execute:结果表格 + CSV 导出(纯前端)。 - 演示闸门:① 试
DELETE FROM inventory→ 被拒(只读+单语句+白名单);② 用普通用户(配了 RLS 的)执行同 SQL → 结果行被行级过滤;③ 写个无 LIMIT 大查询 → LIMIT 自动钳制(默认 500、上限 5000);④ 配了 Markings(§5.13)的列,无权限者查询得 NULL;⑤ 试SELECT * FROM "users"(平台库真实表)或反引号/派生表内引用表 → 被标识符白名单拒绝。
linkName.prop 语法,跨对象需显式 JOIN;编辑态叠加绿色高亮提示注入的权限条件。5.2 Notebook(/foundry/notebook)
定位:分析笔记本:markdown/sql/chart 三类单元格,单格/全量运行,历史落库(fn_notebook_runs),SQL 复用 Ontology SQL 执行器(同样过 RLS/CLS/LIMIT)。
操作
- 新建笔记本 → 加 markdown 单元格写分析说明 → 加 SQL 单元格查低库存 → 加 chart 单元格做可视化 → 全量运行。
- 宏演示:先在 CodeRepo(§5.9)定义宏
{{macro:low_stock}},在 Notebook Execute 前自动展开(深度≤5)。 - 查看运行历史与耗时。
NotebookPage.vue 的 refreshCells() 调用了 listCells 但 import 缺失——添加/删除单元格、全量运行后会抛 ReferenceError。后端数据已正确变更,仅前端列表/图表/提示受影响;刷新页面即可绕过。演示节奏:每次运行后手动刷新一次。另 markdown 预览为纯文本非富文本。5.3 Dashboards(/foundry/dashboards)
定位:图表绑定本体对象→语义查询取数(RLS/CLS 内生)→仪表盘组装 + user/role 分享。
操作
- 新建仪表盘 → 添加图表(绑定 inventory 对象 + 过滤/聚合)→ 组装 2~3 张图 → 按 user/role 分享给普通用户。
- 用普通用户登录查看共享仪表盘——数据被 RLS/CLS 约束。
5.4 Reports 智能报表(/foundry/reports)
定位:把仪表盘/指标定时变报并主动分发:chart/text/table 三类块 → 生成 markdown+HTML 双形态快照 → email/internal 分发 → cron 调度自动生成。
操作
- 新建报表 → 添加块(chart 绑定对象、text 写结论文案、table 列低库存清单)→ 生成快照(markdown + HTML 双形态)。
- 分发:channel=internal(必现)+ email(当前 SMTP 未配会诚实失败)+ feishu(已配可用,降级标注 partial/degraded)。
- 配 cron 调度 → 到点自动生成新快照;看运行历史。
5.5 Quality 数据质量(/foundry/quality)
定位:四类质量规则(如非空/唯一/范围/自定义 SQL)+ 问题闭环(open→acknowledged→fixed)+ 四因子画像(完整度/唯一度等,SQL 下推,sampled/na 诚实标注)。
操作
- 对 inventory 建规则:
stock_level >= 0(范围)与 inventory_id 唯一。 - 跑数据集画像(
GET /datasets/:id/profile)看四因子分。 - 故意插入一行 stock_level=-5 → 触发规则 → 问题列表出现 issue → acknowledge → 修复数据 → fixed(闭环演示)。
- 联动:同步成功自动触发画像(bridge 已接);管道 run 会执行 scope=pipeline 的 error 级规则并阻断目标对象同步(基础版 §5.2 提过,此处可展开演示)。
5.6 Stream 流事件规则(/foundry/stream)
定位:Foundry 侧的事件驱动引擎(与 AIP event 工作流互补):CDC watcher 绑定 + 条件表达式 + 五类动作(webhook / notification / sync_run / quality_run / writeback)。
操作
- 先确保有 CDC watcher(数据源变更捕获)。
- 建规则:监听 inventory 变更,条件
stock_level < reorder_point→ 动作 notification(站内)+ writeback(如自动写审计备注)。 - 用「测试触发」走真实流水线验证;幂等保证:(rule_id,event_id) 唯一索引,同一事件不会重复触发动作。
- 对照演示:同一库存变更同时被 Foundry Stream 规则(落库侧反应)与 AIP event 工作流(编排侧反应,基础版 §5.5)捕获——两套引擎各司其职。
5.7 Fusion 实体消解(/foundry/fusion)
定位:多源数据"同一个人/同一商品"合并:规则分桶 + 加权打分(exact/prefix/levenshtein)+ union-find 聚类 + 人工确认/拒绝 + survivorship 选主写回(in_place_edit 或 materialize)。
操作
- 准备两个含重复实体的源(如 customers 表导入两次,名称略有差异)。
- 建消解作业:选字段映射与匹配规则 → 运行(异步 run + 1.5s 轮询)→ 看聚类结果与相似度打分。
- 人工确认/拒绝候选合并 → survivorship 规则选主记录 → 写回(in_place_edit 原地改 / materialize 物化新表)。
5.8 Functions 本体函数(/foundry/functions)
定位:声明式注册可复用计算函数(fon_functions):name 正则 + body 语法检查,测试面板即时求值,用户函数互调递归≤5。
操作
- 注册函数如
gap_to_reorder(stock_level, reorder_point) = reorder_point - stock_level。 - 测试面板传入参数即时求值。
- 注册第二个函数调用第一个(演示互调);可在 Metrics/语义层引用函数作为计算口径。
5.9 CodeRepo 代码仓库(/foundry/coderepo)
定位:snippet/template/macro 三类代码资产仓库:文件版本覆盖归档+恢复;宏 {{macro:name}} 在 SQL 工作台/Notebook Execute 前自动展开(深度≤5,未命中原样传)。
操作
- 建 macro:
low_stock=stock_level < reorder_point。 - 在 SQL 工作台写
SELECT * FROM inventory WHERE {{macro:low_stock}}→ 执行前自动展开。 - 用页面内置展开调试端点看展开结果;修改 macro 后版本归档,可恢复旧版。
5.10 Marketplace(/foundry/marketplace)
定位:平台资产商店:六类来源(object/metric/dashboard/app/notebook/fusion)发布为快照商品(fm_items),rid 版本链、重发布 v+1、一键安装(重名自动加 _imported_<ts>)。
操作
- 把 inventory 对象(或某仪表盘/笔记本)发布到 Marketplace → 生成快照商品。
- 修改对象后重新发布 → 版本 v+1。
- 「安装」到另一环境/重装 → 新增
_imported_<ts>副本。 - unlisted 商品安装被拒——治理口径演示。
5.11 MLOps 模型管理(/foundry/mlops)
定位:模型注册/版本/部署/回滚/预测/预测日志全链路;本体集成(预测注册为计算属性、PredictForObject)。
操作
- 注册一个 rule 类型模型(规则数组匹配,如"stock_level < reorder_point → 补货")→ 发布版本 → 部署。
- 对对象行发起预测 → 预测结果可注册为计算属性 → 预测日志可查。
- 回滚演示:发布 v2 → 回滚 v1。
5.12 Apps 低代码应用(/foundry/apps)
定位:应用→页面→组件三层低代码搭建:DataBinding JSON 绑定本体语义查询取数,发布 draft→published。
操作
- 新建应用「库存助手」→ 加页面 → 拖组件:metric_card(库存总量)+ table(低库存清单,DataBinding 绑 inventory 对象)+ text + object_detail。
- 发布 → 与普通用户共享查看。
5.13 Markings 数据打标(/foundry/markings)
定位:密级打标(如内部/敏感/机密)+ 四类目标绑定(表/列/数据集/指标)+ 用户授权矩阵;作为 ApplyCLS 之外第二道列级闸门——未持权查询该列得 NULL(不报错、静默遮蔽)。
操作
- 建密级「内部」→ 绑定 customer.phone 列 → 授权矩阵只给 admin 持权。
- 普通用户在 SQL 工作台/对象查询查 phone → 得 NULL;admin 查 → 正常返回。
/markings/users 依赖 RBAC 注入否则 500。5.14 Governance 数据治理(/foundry/governance)
定位:术语表(可关联本体属性)+ 分类标签(0-3 级打到属性)+ 属性治理汇总 + 保留策略 CRUD/启停。
操作
- 术语表登记"补货点 reorder_point"并关联 inventory.reorder_point 属性——统一业务黑话。
- 给敏感属性打分类标签(等级 0-3)。
- 建保留策略(如日志类数据保留 90 天)并启用。
5.15 API Keys(/foundry/api-keys)
定位:程序化访问凭证:lfk_ 前缀长凭证,SHA256 哈希存储、明文一次性展示、撤销/删除/公开 verify 端点;Bearer lfk_… 可直接过认证中间件。
操作
- 创建 Key → 明文只展示一次(截图保存)→ 用
curl -H "Authorization: Bearer lfk_…"调一个只读端点(如GET /api/v1/ontology/objects)验证。 - 撤销 Key → 再调 → 401(verify 公开端点亦可查状态)。
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 门控
- 进
/apollo/login(独立登录)→ 部署总览确认 seed 的demo-app(v1.0.0,web 依赖 db 验证 DAG 门控)已激活、stable 渠道存在。 - 进
/apollo/deployments→ 发起部署到 spoke-01 → 观察 db 先 ready、web 后放行的分批推进 → 手动 advance 到 synced。
闭环 ②:漂移检测自愈
- 进漂移检测页 → detect → 查看字段级 JSON Patch diff → reconcile 收敛 → has_drift=false 回 synced。
- 可选:告警自愈(health-checks/incidents/healing-policies/healing-history 审批 approve|deny)。
docs/site-v4/apollo.html。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 边)+ 地图要素/轨迹 + 时间轴事件。
闭环 ①:图谱研判
- 进
/gotham工作台浏览玄武网络 → 对"玄武集团"做 1-2 度展开看邻居高亮。 - 最短路径分析:"张远→赵敏"资金链路(图算法接口需 admin)→ 新增节点/边写图(graph/nodes|edges|merge)。
闭环 ②:接入到产出全链
/gotham/ingestion建 file_csv 源并运行(SSE 进度条,可暂停恢复)。/gotham/resolution建解析作业(四层打分,勾enable_ai且后端配了 LLM key 即真走 AI 裁决)+ 人工审核确认合并。/gotham/patterns全量评估(预置 6 条规则)生成告警 → 确认/处置。/gotham/reports生成/发布/导出 PDF/DOCX。
加分项
/gotham/views多视图联动广播(target_count);/gotham/collabWebSocket 实时协同(开双窗口);/gotham/tasks拖拽看板;/gotham/accessABAC 试算留痕(evaluate/traces,PEP 写门);地图 /map/*(热力/轨迹,依赖在线 OSM 瓦片);时间轴 forecast/compare。
target=geo(区域密度)与 target=graph(degree_burst/orphan_burst)评估;图谱 SVG 全量渲染百节点以上卡顿、力导布局不持久化。/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+卫星通信金融结算,星上结算、国密通信。判定:仿真/演示级——链路真实可跑,星座拓扑/账户/清算通道均为模拟,不做投产承诺。
闭环 ①:报文实验室
/swift/messages生成 pacs.008 报文(DRAFT)→ SM3+SM2 国密签名 → 篡改后 verify 拒绝(或 /swift/gac 用 tamper-test)。
闭环 ②:一键 10 步演示(HCC 管控台)
- 进
/swift/hcc点「一键演示」(/demo/run+/demo/status)→ 分步观看:GAC 报文生成 → 国密签名 → 端到端加密(SM2 协商+SM4-GCM 信封)→ 星地链路传输(含断链缓存补发恢复)→ HCC 解密验签解析 → 合规筛查(制裁名单+KYC+LLM 辅助)→ 风控额度 → 结算记账/对账。 - 看支付状态机流转与分步 status/detail/data。
docs/story/cross/value-chain.html。SWIFT_DEMO=1 语义=弱 SECRET_KEY 的演示放行开关(缺省弱值拒绝启动,config.yaml 加载成功路径同样校验,放行时 Warn 留痕)。7 分步验收测试单(扩展)
在基础版 14 项验收(见 ai-action-demo.html §6)之外追加。勾选式 PASS/FAIL;实现程度见 §1.1。
| # | 验收点 | 操作(详见节) | 通过标准 |
|---|---|---|---|
| E1 | 前置链铺满 | §1.2 / §2.1 | LLM 网关路由含 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 不入 |
| E5 | RAG 五段上下文 | §3.4 | /rag-test 返回 channels_used 含 knowledge/entity;latency 可见 |
| E6 | 决策证据链 | §3.5 | 5 步链完成、引用可溯源、trace_id 在 ai-audit 可查 |
| E7 | 会话记忆 | §3.6 | 多轮追问生效;清空后失忆;失败轮次不写记忆 |
| E8 | 多智能体编排 | §3.7 | parallel 与 debate 各出一次融合结果;历史可查 |
| E9 | LLM 网关治理 | §4.1 | 路由热同步;用量数字增长;降级链兜底生效 |
| E10 | Prompt 版本安全网 | §4.2+§4.3 | 改 Prompt→评测回归告警→回滚→恢复(完整闭环) |
| E11 | 监控与反馈 | §4.4 | 概览指标非空;提交反馈后统计变化 |
| E12 | RLS/CLS/脱敏/护栏 | §4.5 | 普通用户行级过滤生效;敏感列脱敏;超长输入被护栏拦截 |
| E13 | SQL 工作台闸门 | §5.1 | 写操作被拒;LIMIT 钳制;无权限列返回 NULL;引用平台库表被白名单拒绝;未配列权限可正常查询(注记放行) |
| E14 | Notebook 运行 | §5.2 | SQL 单元格出结果、历史落库(刷新页面绕过已知前端 bug) |
| E15 | 报表生成分发 | §5.4 | 快照生成(markdown+HTML);internal 分发落通知 |
| E16 | 质量闭环 | §5.5 | 违规→issue→acknowledge→fixed 全链走通 |
| E17 | Stream 规则触发 | §5.6 | 测试触发走真实流水线;同事件不重复触发(幂等) |
| E18 | Fusion 消解 | §5.7 | 聚类+人工确认+写回生效;同项目并发第二次发起 409 |
| E19 | Marketplace 发布安装 | §5.10 | 发布→重发布 v+1→安装出现 _imported 副本 |
| E20 | Markings 双闸门 | §5.13 | 无持权用户查询绑定列得 NULL |
| E21 | API Key 鉴权访问 | §5.15 | Bearer lfk_ 过认证调端点(权限随绑定用户角色);撤销后 401 |
| E22 | Apollo 部署+漂移 | §6.1 | DAG 分批推进到 synced;reconcile 后 has_drift=false;同定义并发触发不重号(冲突 409) |
| E23 | Gotham 图谱全链 | §6.2 | 展开/路径分析出结果;接入→解析→规则→报告四步走通(数据源接口 admin-only,普通角色 403;报告图片按 data:image 白名单渲染) |
| E24 | Swift 国密链路 | §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 同项目第二次运行报 409 | v5 并发互斥(旧"并发覆盖"口径作废):等上一 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.md、swift/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.md、wiki/OVERVIEW.md、wiki/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)