企业官网建设流程全解析

rp-engine是一款用 Rust 编写的 YAML 原生 Agent 工作流执行引擎，其中的skill_set 节点通过 **L1/L2/L3 三层渐进式披露（Progressive Disclosure）**机制管理领域知识：只在 system_prompt 中常驻技能"目录"，完整内容与引用资料由 LLM 通过工具调用按需加载，从根本上避免"把全部知识塞进 prompt 导致上下文爆炸"的难题。

一、痛点：把全部知识塞进 prompt 有多痛？

构建代码助手、客服机器人、运维 Agent 时，模型往往需要大量领域知识：团队编码规范、API 设计规范、产品手册节选……最朴素的做法是把它们全部写进 system_prompt。

问题很明显：

• 💸Token 成本高：知识文档动辄上万 token，每次运行都计费；
• 🧠注意力被稀释：prompt 里无关内容越多，模型回答质量反而下降；
• 🔧维护困难：知识一改，就要动工作流提示词。

skill_set 节点给出的答案是：渐进式披露——只在 LLM 需要的时候，才告诉它需要的内容。

二、L1/L2/L3 三层披露机制：按需加载的核心设计

L1 元数据层：常驻 system_prompt 的"技能目录"

每个技能在 system prompt 里只占一行（名称 + 描述），例如：

## Available Skills Use the `load_skill` tool to load full instructions for any skill. - **rust_conventions**: Rust coding conventions and best practices - **api_design**: REST API design guidelines

引擎会自动把这段元数据注入到 system_prompt 的中间层（位于 harness 指令与模板 system_prompt 之间），注入逻辑见 src/nodes/generate.rs。

L2 完整内容层：load_skill 工具按需加载

当 LLM 判断某个问题需要详细规范时，会调用内置工具load_skill("skill_name")，引擎随即返回该技能的完整内容。该工具的参数是全部技能名的枚举，模型不可能"编造"出不存在的技能名。

L3 引用资料层：load_skill_reference 加载关联文件

技能还可以声明一组引用文件路径（references，比如 OpenAPI 规范、完整接口文档）。当 LLM 需要更深的细节时，调用load_skill_reference读取指定文件。出于安全考虑，只有声明在references中的路径才能被读取，未声明路径会被直接拒绝。

三层对比一览：

三、快速上手：在 YAML 中定义 skill_set 节点

最小配置示例：

- id: coding_skills type: skill_set config: skills: - name: rust_conventions description: "Rust coding conventions and best practices" content: | 1. Use snake_case for variables and functions 2. Prefer Result<T, E> over panicking - name: api_design description: "REST API design guidelines" content_file: "skills/api_design.md" references: - "docs/openapi_spec.md"

配置字段说明（完整规范见 docs/FLOW_SPEC.md）：

连接 generate 节点：两步缺一不可

1. 用边（edges）把skill_set节点连到目标generate节点；
2. 在 generate 节点的skill_sets字段中声明 skill_set 节点 ID：

- id: helper type: generate config: skill_sets: ["coding_skills"] # 必须与 skill_set 节点 ID 一致

缺边或缺声明，工作流都会构建失败，问题会提前暴露。

四、运行原理：引擎在背后做了什么

工作流执行时，skill_set 执行器负责：

1. 把content_file读入内存（内联content优先）；
2. 将解析后的技能列表写入执行状态，供下游 generate 节点消费（输出含skills数组与_skill_count）。

随后 generate 节点（见 src/nodes/generate.rs）：

• 把 L1 元数据注入 system_prompt；
• 注册两个内置工具，参数用技能名/引用路径的枚举做约束；
• 在 tool calling 循环中把load_skill/load_skill_reference调用分派给对应处理器，把内容作为工具结果回传给模型。

⚠️ 三个需要注意的细节：

• load_skill与load_skill_reference是保留工具名，在tools中定义同名工具会直接构建报错；
• 技能工具只对支持 function calling 的模型注册，不支持的模型会收到警告并跳过；
• 如果所有技能都没有references，load_skill_reference工具不会注册。

技能的数据结构定义在 src/schema/node.rs。

五、实战示例与调试技巧

项目自带可直接运行的示例 examples/test_skill_set.rs：定义rust_conventions与api_design两个技能，让 helper 节点在回答编码规范问题时自行调用load_skill。

🔍调试技巧：构建引擎时开启capture_actual_prompt(true)，运行后从执行记录的_actual_system_prompt输出中即可验证——L1 元数据是否正确注入、Available Skills里是否列全了技能名，示例代码里已包含对应断言逻辑。

六、最佳实践清单

1. 描述要短而具体——description 是模型决定"要不要加载"的唯一菜单信息，写清楚技能边界；
2. 大文档放文件：正文用content_file，资料用references，保持 YAML 工作流文件精简；
3. 技能名要"为模型而命名"：rust_conventions远胜于skill_1；
4. references 只声明真正需要读的，既是安全边界，也引导模型行为；
5. 与 harness 层搭配使用：harness 约束行为（该做/不该做什么），skill_set 提供知识（怎么做），各司其职。

七、相关资料

• 官方工作流规范（skill_set 章节）：docs/FLOW_SPEC.md
• 渐进式披露层级定义：docs/FLOW_SPEC.md
• skill_set 执行器实现：src/nodes/skill_set.rs
• 技能注入与内置工具注册：src/nodes/generate.rs
• SkillDef 数据结构：src/schema/node.rs
• 可运行示例：examples/test_skill_set.rs
• 项目总览：README.md