Skill、Reference 与 Script 的本质解耦与 RAG 局限
在构建基于大模型(LLM Agent / Agentic Workflow)的企业级知识库时,必须区分程序性知识(Know-how)与陈述性知识(Know-what / Know-why)。传统 RAG 或将所有业务塞入“单一超级 Skill”会导致控制流交错、意图路由失效与上下文污染。本中台采用“以 Skill 为调度骨架、以 Reference 为上下文字典、以 Script 为物理内核”的异构拓扑解耦模式。
三层架构职责定位表
| 维度 | Skill (程序性技能 / SOP) | Reference (静态规约 / 语境) | Script (确定性内核) |
|---|---|---|---|
| 知识类型 | 程序性知识 (Know-how) | 陈述性知识 (Know-what / why) | 确定性计算 (Exact Logic) |
| 核心载体 | 动态控制流、有向状态机、准入断言 | 字典表、阈值矩阵、合规清单、金样/反模式 | Python/Shell 脚本、正则、哈希校验、AST 算子 |
| 动作属性 | 具备 副作用 (Side-effects),可编排 API | 只读 (Read-Only),无状态,提示词补丁 | 纯函数、幂等计算、无模型概率干扰 |
| 执行逻辑 | 明确入口、RFC 2119 步骤、失败重试与回退 | 仅在特定分支被懒加载注入 | 物理沙箱执行,仅将 stdout/stderr 回填 |
传统 RAG 的三大结构性缺陷
切块+向量召回- ✖ 执行时序拓扑断裂: 按固定 Token 盲目切块,破坏长 SOP 流程严密性,导致 Agent 遗漏前置系统权限校验断言(Preconditions),引发越权或逆向执行。
- ✖ 统计概率推理侵蚀确定性逻辑: 在提示词内依靠 LLM 硬算税率、风控比对或浮点数计算,极易诱发数值幻觉与外部 API 脏写。
- ✖ 注意力稀释与全局上下文污染: 全量堆叠系统手册导致“中间失落(Lost in the Middle)”,段落中间的核心反模式约束(Anti-patterns)被概率性忽略。
单一“超级 Skill”模式的物理崩溃
全量挂载陷阱- ✖ 意图发现与路由彻底失效: 依赖 Frontmatter 路由。单一 Skill 描述必须涵盖全业务,模糊度极高导致 Level 1 路由命中率暴跌。
- ✖ 控制流交错与注意力污染: 财务与运维逻辑交织在一起,触发模型跨业务借用逻辑(如执行财务核销时错用了运维回退策略)。
- ✖ 拓扑冲突与并发锁瘫痪: “账户注销”与“资金划转”必须互斥,单一 Skill 缺少图实体,无法做亚毫秒级冲突排查(`CONFLICTS_WITH`)。
渐进式披露机制与 Canvas 交互式拓扑子图模拟器
本章节展示了三级渐进式披露(Progressive Disclosure)机制与异构动作-状态图谱拓扑。用户可以在下方的 Canvas 动态拓扑子图模拟器 中点击不同节点(Skill、Reference、ScriptTool、StateArtifact),查看节点属性以及在线调度的 1-hop 依赖边高亮与上下文注入流。
拓扑子图交互模拟器 (Subgraph Visualizer)
点击节点可激活该节点的 1-hop 依赖图谱并实时查看其上下文注入载荷 (Payload)
invoice-audit
财务发票核销与合规审计
- REQUIRES_REF ➔ tax_table_2026
- INVOKES ➔ calc_tax_deductions
- PRODUCES ➔ Invoice[AUDITED]
三级渐进式披露分级与数学开销模型
载体为 SKILL.md 顶部的 YAML Frontmatter。控制在 50~100 Tokens,仅包含 name 与 description,防止描述过长污染意图路由。
意图匹配后载入 SKILL.md Markdown 正文。预算 < 5,000 Tokens,定义 RFC 2119 规范步骤、准入断言与异常回退。
涉及特定规则表或强计算时,懒加载 references/* 字典或运行 scripts/*,仅将脚本 stdout 回填,防止只读明细塞满上下文。
该数学机制确保企业技能从 10 扩展至 1000 时,常驻底噪仅呈极低斜率线性增长(N × 80 Tokens),降低 60%~95% 的 Token 成本。
技能拆分 4 大黄金法则与交互式代码检查器
本章节提供了将企业 SOP 解构为程序性资产时的 4 大黄金拆分法则,并附带了交互式代码查看器,用户可以在左侧切换 Level 1 Frontmatter、Level 2 SKILL.md、Level 3 Reference/Script,查看符合规范的标准代码与结构。
单一业务目标收敛性
一个 Skill 必须且仅对应一个可判定是否完成的业务目标。将 create-purchase-order 与 approve-purchase-order 拆为独立 Skill。
独立副作用与 API 绑定
若某段逻辑需调用物理脚本或写 API 且有准入断言,独立为 Skill;若仅为只读对照表(如《2026年税率表》),归入 Reference。
状态机自治与失败回退
具备独立失败模式(Failure Modes)与回退路径的流程必须独立(如服务器部署失败自动退滚与报警),以便被主流程作为子技能调用。
5,000 Token 预算断言
单个 Skill 的 SKILL.md 正文严格控制在 5,000 Tokens 以内。超长说明粒度过粗,必须拆分为微技能并通过图谱编排。
--- name: invoice-audit description: 财务发票核销与合规审计技能。当用户发起增值税发票报销、跨国凭证核销或进行进项税抵扣计算时触发。 timeout_seconds: 120 allowed_tools: - python_sandbox - erp_api_client ---
从非结构化文件到可计算图谱的五步工程流水线
本章节系统化拆解了将企业沉淀的制度规范转换为图谱化技能库的五个标准阶段:高保真解析、动静编译、静态 Lint 门禁、双轨制图谱抽取以及图存储与闭环演进。下方提供了详细的阶段评估与全量开源选型对比矩阵。
开源技术选型评估矩阵 (8 大核心组件)
点击标签按阶段过滤开源组件,点击组件查看工程考量
| 工具名称 & GitHub | 对应阶段 | 底层技术架构 / OCR 底座 | 核心工程优势 | 局限性与权衡 (Trade-offs) | 开源协议 |
|---|---|---|---|---|---|
|
docling-project/docling
IBM Research
|
阶段 1 | TableFormer + Granite-Docling VLM; 原生数字文档免 OCR | 结构化语义保持极佳,导出带层级树的 DoclingDocument;纯 CPU 高并发支持 | 模糊倾斜扫描件字符识别率略逊于专用 OCR 引擎 | Apache-2.0 |
|
opendatalab/MinerU
上海 AI 实验室
|
阶段 1 | PaddleOCR + 专用高精度版面分析网 + MinerU2.5 VLM | 极端复杂 CJK 中文排版、跨页嵌套表格识别率领先 (Layout mAP 97.5) | 依赖 GPU 算力环境,单机吞吐延迟较高;Office 泛化较弱 | AGPL-3.0 |
|
datalab-to/marker
|
阶段 1 | Surya OCR 套件 + 多语言版面分析 + LLM 修复(可选) | 批量离线吞吐量极高(25 pages/s on H100),代码块与格式规整 | 开启 LLM 修复时成本与延时激增;跨页表格拆解稍弱 | GPL-3.0 |
|
strands-agents/agent-sop
|
阶段 2 | RFC 2119 规范约束生成 + 参数化槽位提取 | 生成的 SOP 具备强控制力,严格杜绝跳步;原生集成步骤执行证明 | 需要自定义 Prompt 适配特定行业名词体系 | MIT |
|
agentskills (Skill-Creator)
|
阶段 2 | 官方规范脚手架(init_skill.py / quick_validate.py) | 标准化目录骨架,强制执行三级渐进披露与 5000 Token 预算断言 | 仅提供 CLI 与规则校验,缺少 GUI 编排画布 | MIT |
|
run-llama/llama_index
PropertyGraphIndex
|
阶段 4 | SchemaLLMPathExtractor + AST 结合双轨制抽取 | 首选提取框架;强类型模式约束,完美对接 Kùzu / Neo4j 接口 | 框架抽象层较厚,需重写提示词管道屏蔽默认三元组模式 | MIT |
|
kuzudb/kuzu
|
阶段 5 | C++20 嵌入式 GDBMS + 因子化计算 (Factorization) | 嵌入式首选;消除多跳中间笛卡尔积;标准 OpenCypher 支持;零运维 | 适合单节点高并发,超大规模分布式切片需搭配独立图集群 | MIT |
|
HKUDS/OpenSpace
|
阶段 5 | SkillOps 生命周期监控与真实运行证据 (Evidence) 捕获引擎 | 自动捕获失败证据,衍生 FIX 补丁与边缘子技能;在线 A/B 灰度 | 需部署运行时 Log Hook 收集调用链路 | Apache-2.0 |
文档解析引擎多维度对比 Radar (Stage 1)
针对企业 PDF/扫描件的综合工程表现评级
双轨制图谱自动化抽取架构 (Stage 4)
采用物理层与语义层并行构建的“双轨机制”,兼顾零成本吞吐与高阶状态机语义捕获:
利用 Python AST 正则扫描 SKILL.md 的 YAML Frontmatter 与 Markdown 相对路径,秒级抽离 REQUIRES_REF (规则引用) 与 INVOKES (脚本调用) 边。
配置 LlamaIndex PropertyGraphIndex + 自定义 Schema Injector,提取 SOP 步骤消耗与产出的业务实体状态,构建 TRANSFORMS 与 PRODUCES 状态迁移边。
有向异构动作-状态图谱本体 (Ontology Schema)
为防止图谱抽取过程中产生实体标签膨胀与语义发散,本中台强制对节点(Node)与关系边(Edge)实施强类型本体约束。下方展示了完整的节点/关系属性定义以及在 Kùzu 图数据库中的 OpenCypher 数据定义语言(DDL)代码。
节点 (Node Table) 本体定义
属性: name, description, timeout_seconds, allowed_tools
属性: category (ThresholdTable/AntiPattern/etc), content_digest, token_cost
属性: runtime (python3.11/bash), idempotent (BOOLEAN)
属性: entity_type, status_code, schema_definition (JSON Schema)
关系边 (Rel Table) 本体定义
属性: load_condition (ALWAYS / LAZY)
属性: step_order (INT64), on_failure (ABORT/RETRY/FALLBACK)
属性: precondition_assert, transition_action (CREATE/UPDATE)
属性: reason (锁表/状态竞争,调度器禁止并发调用)
// ==========================================
// KùzuDB 图数据库 Schema 固化 DDL
// ==========================================
// 1. 创建节点表 (Node Tables)
CREATE NODE TABLE Skill (
id STRING PRIMARY KEY,
name STRING,
description STRING,
timeout_seconds INT64,
allowed_tools STRING
);
CREATE NODE TABLE Reference (
id STRING PRIMARY KEY,
category STRING,
content_digest STRING,
token_cost INT64
);
CREATE NODE TABLE ScriptTool (
id STRING PRIMARY KEY,
runtime STRING,
idempotent BOOLEAN
);
CREATE NODE TABLE StateArtifact (
id STRING PRIMARY KEY,
entity_type STRING,
status_code STRING,
schema_definition STRING
);
// 2. 创建关系表 (Relationship Tables)
CREATE REL TABLE REQUIRES_REF (
FROM Skill TO Reference,
load_condition STRING
);
CREATE REL TABLE INVOKES (
FROM Skill TO ScriptTool,
step_order INT64,
on_failure STRING
);
CREATE REL TABLE CONSUMES (
FROM StateArtifact TO Skill,
precondition_assert STRING
);
CREATE REL TABLE PRODUCES (
FROM Skill TO StateArtifact,
transition_action STRING
);
CREATE REL TABLE DEPENDS_ON (
FROM Skill TO Skill,
dependency_type STRING
);
CREATE REL TABLE CONFLICTS_WITH (
FROM Skill TO Skill,
reason STRING
);
四大核心子系统、路线图与 Token 算力沙盒
本章节涵盖了平台四大核心子系统(编译工作台、契约门禁、图谱索引、SkillOps 监控中台)、12 周落地里程碑以及交互式 Token 预算节省模拟器。
文档接入与 SOP 编译工作台
提供多源文档批量上传、Docling 解析与可视化解构。挂载 strands-agents/agent-sop 重写流水线,一键提炼符合 RFC 2119 规范的 SKILL.md 与参考表单。
契约门禁与静态治理套件
版本化准入审查服务。内置扩展版 quick_validate.py 门禁,核验 Frontmatter 格式、相对引用拓扑与 Token 预算,挂载 Git Pre-commit 与 CI/CD Guardrails。
拓扑抽取与图谱索引引擎
基于 AST 抽离物理边,结合 LlamaIndex PropertyGraphIndex 抽取状态转移。自动将节点与边编译写入 Kùzu 图数据库,暴露亚毫秒级 Cypher 查询接口。
运行时拓扑调度与 SkillOps 监控中台
解析意图并在图谱中进行路径预演,抽取 1-hop 子图注入模型。集成 HKUDS/OpenSpace 内核,全量采集成功率、重试与回退事件,驱动自适应补丁演进。
演算参数调节
上下文 Token 占用演算对比 (Live Benchmark)
随着技能总数增长,全量注入与三级渐进式披露的开销差距
三阶段 12 周落地实施路线图 (Implementation Roadmap)
Phase 1: 资产解析与规范化骨架构建 (Pioneer Phase)
第 1 至 4 周跑通企业文件向标准化技能包转换,建立统一 GitOps 知识仓库,挂载静态门禁。
SKILL.md 静态门禁一次性通过率达 100%。
Phase 2: 自动化图谱抽取与调度接入 (Graphing Phase)
第 5 至 8 周建立有向异构动作-状态图谱,实现多技能间的拓扑依赖导航与 1-hop 上下文精准注入。
Phase 3: 生产闭环治理与自演化运营 (SkillOps Phase)
第 9 至 12 周承载高风险生产流量,挂载 HKUDS/OpenSpace,收集证据并开启自适应补丁衍生与灰度更新。