8. 技能体系

Skill System 描述 FlowNex 如何管理、发布、授权、运行和演进可复用 Agent 能力。

Skill 是 FlowNex 从“通用对话”走向“企业专业任务执行”的关键抽象。

8.1 Skill 的定位

Skill 是一类任务的专业执行方法。

它不是简单提示词，也不是单个工具，而是把完成某类任务所需的规则、步骤、上下文、工具、输出格式和经验沉淀为一个可复用能力单元。

Skill 的目标是让 Agent 面对专业任务时具备稳定行为。

例如：

  1. 合同评审 Skill：指导 Agent 识别主体、金额、付款、违约、保密、争议解决等条款风险。
  2. 项目周报 Skill：指导 Agent 按固定结构提取本周进展、风险、阻塞和下周计划。
  3. 数据分析报告 Skill：指导 Agent 读取数据、计算指标、生成图表和输出结论。
  4. 飞书审批 Skill：指导 Agent 调用飞书审批接口并处理审批结果。

Skill 的价值在于：

  1. 降低重复提示词编写成本。
  2. 固化业务最佳实践。
  3. 提升输出格式稳定性。
  4. 限制高风险任务边界。
  5. 支撑能力发布、授权和运营。

8.2 Skill 元数据模型

Skill 元数据保存于 agent-domain-service，核心表为 t_skill 及相关安装、审核、预装记录。

一个 Skill 至少需要包含：

  1. skillId：Skill 主键。
  2. tenantCode：所属租户。
  3. skillCode：稳定业务编码。
  4. skillName：展示名称。
  5. description：能力描述。
  6. categoryId：分类。
  7. enabled：是否启用。
  8. features：运行相关扩展信息。
  9. bizFeatures：业务扩展信息。
  10. authorUserId：作者。
  11. currentVersionId：当前版本。
  12. sourceType：来源类型。

后续建议进一步补齐：

  1. contextMode：SELF_CONTAINED / KNOWLEDGE_BOUND / KNOWLEDGE_REQUIRED。
  2. defaultKnowledgeStrategy：默认知识策略。
  3. executionGuardrails：执行安全边界。
  4. runtimeHintL0：运行时轻量提示。
  5. requiredToolCodes：建议或必需工具。
  6. evaluationStatus：评测状态。

8.3 Skill 生命周期

Skill 生命周期建议采用以下状态机：

stateDiagram-v2
    [*] --> DRAFT
    DRAFT --> PENDING_REVIEW: 提交审核
    PENDING_REVIEW --> PUBLISHED: 审核通过
    PENDING_REVIEW --> REJECTED: 审核拒绝
    REJECTED --> DRAFT: 修改后重新提交
    PUBLISHED --> OFFLINE: 下线
    OFFLINE --> PUBLISHED: 重新上架
    PUBLISHED --> ARCHIVED: 归档

不同阶段的语义：

  1. DRAFT：作者编辑中，不对普通用户可用。
  2. PENDING_REVIEW：等待管理员或审核员确认。
  3. PUBLISHED：已发布，可被授权和安装。
  4. REJECTED：审核未通过，需要修改。
  5. OFFLINE：暂时下线，不允许新任务使用。
  6. ARCHIVED：历史归档，不再进入市场。

运行时只能消费已发布、已授权、已启用的 Skill。

8.4 Skill 市场

Skill 市场是用户发现和安装能力的入口。

Skill 市场应展示：

  1. Skill 名称。
  2. 描述。
  3. 分类。
  4. 作者。
  5. 适用场景。
  6. 所需工具。
  7. 绑定知识。
  8. 安装状态。
  9. 最近使用量。
  10. 成功率或评分。

Skill 市场不只是展示页，也是能力运营入口。

管理员可以通过市场观察：

  1. 哪些 Skill 高频使用。
  2. 哪些 Skill 安装率高但成功率低。
  3. 哪些 Skill 依赖知识过期。
  4. 哪些 Skill 需要补充示例或限制。
  5. 哪些用户创建的 Skill 可以升级为团队 Skill。

8.5 Skill 安装与授权

Skill 可见不等于 Skill 可用。

一个用户能否使用某个 Skill，至少需要满足：

  1. Skill 属于当前租户或平台公共范围。
  2. Skill 已发布。
  3. Skill 已启用。
  4. 用户拥有该 Skill 使用权限。
  5. 用户已安装，或 Skill 被预装给用户所属部门、角色或租户。
  6. 本轮任务允许该 Skill 进入 skillCodes。

推荐授权模型：

  1. 平台 Skill：平台统一维护，可按租户开放。
  2. 企业 Skill：租户管理员维护，对本租户开放。
  3. 团队 Skill：部门或项目团队维护，对指定范围开放。
  4. 个人 Skill：用户个人维护，默认只对自己可用。

8.6 Skill 与 Tool 的关系

Skill 和 Tool 是两种不同抽象。

概念 作用 示例
Skill 描述如何完成一类任务 合同评审、项目周报、行业研究
Tool 执行某个动作 读文件、调用飞书 API、Web 搜索、运行脚本

一个 Skill 可以声明自己建议或依赖哪些 Tool。

例如：

数据分析报告 Skill
  依赖 read_file
  依赖 shell_run
  可选 web_search
  可选 chart_generation

运行时必须检查本轮 Tool 授权。即使 Skill 描述中建议使用某个 Tool，如果本轮 toolCodes 未授权，该 Tool 也不应被注入。

8.7 Skill 与知识库绑定

业务型 Skill 通常需要绑定知识库。

绑定关系用于约束或引导运行时检索范围。

例如：

合同评审 Skill
  REQUIRED: 合同模板知识库
  REQUIRED: 法务风险条款库
  PREFERRED: 历史合同案例库
  FORBIDDEN: 已归档旧制度知识库

第一期建议使用轻量表 t_skill_knowledge_binding 管理绑定。

运行时不直接读取绑定表，而由 control-center 在下发任务前计算 RuntimeKnowledgeAccess。

这样可以保证：

  1. 权限裁剪发生在运行时之前。
  2. runtime 不感知业务权限细节。
  3. 知识范围可以被审计。
  4. Skill 绑定策略可以灰度演进。

8.8 Skill 执行与 runtime 注入

share-harness 在每轮任务中会根据 skillCodes 解析当前可见 Skill。

推荐运行时处理流程：

flowchart TD
    A["收到 RunCreateRequest"] --> B["解析 skill_codes"]
    B --> C["加载可见 Skill 轻量目录"]
    C --> D["Planner / ReAct 判断是否需要 Skill"]
    D --> E["按需加载完整 SKILL.md"]
    E --> F["读取 references / scripts / workflows"]
    F --> G["检查 Tool 授权"]
    G --> H["执行 Skill 指导下的任务"]

Skill 注入应遵守上下文预算。

不建议每轮把所有完整 Skill 文本都塞进模型。更合理的方式是：

  1. 先注入 Skill 轻量摘要。
  2. 命中后再按需读取完整 Skill。
  3. references 和 scripts 只在需要时读取。
  4. 超预算时优先保留当前任务最相关 Skill。

8.8.1 从原子能力到 Skill 的封装模型

业务线接入的原子化 AI 能力通常不应直接暴露给最终用户。更推荐的方式是先注册为 Capability，再按需要包装成 Tool 或 Skill。

封装路径如下：

业务线原子能力
  -> Provider Adapter
  -> Capability Registry
  -> Tool 定义
  -> Skill 方法封装
  -> Agent 能力包

不同封装层的职责不同：

层级 关注点 示例
Capability 能力元数据、Schema、版本、Provider、SLA invoice_ocr_extract
Tool Agent 可调用动作、参数校验、结果裁剪 extract_invoice_fields
Skill 面向任务的方法、步骤、知识依赖、输出格式 差旅报销材料审核 Skill
Agent 能力包 面向业务场景的能力组合 财务报销助手

封装原则：

  1. 原子能力保持小而稳定，不承担复杂业务编排。
  2. Tool 负责动作调用，不写复杂业务说明。
  3. Skill 负责把多个 Tool、知识库和输出要求组织成任务方法。
  4. Agent 能力包负责把一组 Skill、Tool、知识和 AGFS 空间组合成业务场景。
  5. 能力调用结果必须进入 Task Step 和 Trace，便于排障、审计和评估。

例如，合同审核场景可以这样拆分：

合同文本解析 Capability
  -> contract_parse Tool
  -> 合同评审 Skill
  -> 法务助手 Agent 能力包

这样既能复用底层能力，也能保持用户侧的任务表达足够清晰。

8.9 Skill 演进、评测与灰度

Skill 是可演进资产，但不能无审计自动改写。

推荐演进闭环：

任务轨迹
  -> 用户反馈
  -> badcase 识别
  -> 反思抽取
  -> Skill 改进候选
  -> 离线评测
  -> 灰度发布
  -> 正式发布

Skill 改进可以落到不同位置：

  1. 主体规则：长期稳定规则。
  2. 附录：边界条件、示例、反例。
  3. Runtime Reminder：执行时容易遗漏的短提醒。
  4. Eval Case：进入评测集。

发布前必须满足：

  1. 来源可追踪。
  2. 修改可审计。
  3. 评测通过。
  4. 支持灰度。
  5. 支持回滚。