技能组成规范

文档版本：1.2 状态：与当前后端实现一致（skillpkg、skillfromchat、会话沉淀表、GET /api/v1/skills） 表述：面向产品、运营与对接方，用用户能理解的用语说明「技能是什么、由哪些部分组成、如何进入对话」；实现名放在文末 实现对照。

关联：

• 产品规格.md §3.5（文件优先 Workspace）、§3.6（技能沉淀与治理）
• 智能体调用知识文档的方式.md（技能 vs 知识文档目录）
• 文档驱动意图执行.md（平台内置技能检索与执行）
• help/product-features/skills-and-agents.md（用户侧入口说明）

---

1. 结论先说

Cadau 中的 技能，是供智能体在对话中 按步骤复现一类操作 的 专业操作手册——不是外部业务 API 里的「接口名」，也不是智能体的长期人格（那属于「我的智能体」与 Soul）。

一份规范的技能至少包含：

1. 名称（用户可见标题）
2. 触发说明（description：何时应使用、何时不应使用）
3. 操作正文（步骤、接口要点、排错等 Markdown）

按需可含附属目录 references/（长模板与说明）、scripts/（确定性脚本）、assets/（静态资源）。清单外内容一律不要（思考块、写作过程、已废止路径、聊天原文等）——详见用户侧 技能里该有什么（允许清单） 与下文 §3.5。

会话沉淀技能在数据库中存为 元数据列 + 正文；平台内置与智能体 Workspace 技能在磁盘上可映射为 SKILL.md + 可选附属目录（见 §3）。无论存储形态，逻辑契约统一。

---

2. 与知识文档、智能体的边界

冲突时：对话运行时材料中，技能说明优先于泛化记忆；与 智能体知识库 冲突时，以智能体知识库中的明确覆盖为准（见 智能体调用知识文档的方式.md §5）。

---

3. 逻辑组成（所有来源统一）

3.1 必填：触发说明 + 操作正文

触发说明示例（用户可见文案，非 YAML 原文也可）：

适用：用户上传发票/收据图片并要求识别、入账或汇总。

不适用：纯文字闲聊、与表格或入账无关的问答。

写作要点：

• 适用 行开头写用户可能说的 触发短语（如「识别发票」「导出名单」），再写场景说明。
• 不适用 须写可被用户消息命中的排除场景；运行时若用户消息命中 不适用，该技能 不会 注入本轮对话。
• 忌空泛句如「由会话自动生成」「助力提升效率」——对召回几乎无效。

#### 3.1.1 任务卡（写技能前先填）

无论来源（对话沉淀、技能中心手工编辑、平台内置），建议先在心里或草稿里过一遍 任务卡：

任务卡四句话写不明白时，还不该发布 为技能；先补全对话或拆分更窄的场景。

3.2 推荐正文结构（操作正文）

会话沉淀由模型合成时，正文应优先包含下列小节（无相关内容可省略）：

3.3 渐进式披露（分阶段）

当前实现（v1）：L0+L1；正文过长时在运行时截断，完整版在 技能中心 查看。

3.4 磁盘目录形态（平台 / 智能体 Workspace）

与 Agent Skills 惯例对齐，文件型 技能目录示例（平台内置见 docs/agent-skills/workspace/workspace-ops/）：

skills/{skill-id}/
  SKILL.md          # 必填：YAML 头 + 正文
  references/       # 可选：按需加载的长文档
  scripts/          # 可选：确定性脚本（须沙箱）
  assets/           # 可选：模板、静态资源

SKILL.md 逻辑头字段：

---
name: invoice-ocr-to-sheet
description: |
  适用：用户上传发票/收据并要求识别、入账、汇总。
  不适用：纯文字闲聊或与入账无关的问答。
permissions:
  tools: [http_request]
  secrets: [LARK_APP_TOKEN]
---
# 发票识别入账
…

会话沉淀 不强制落盘为目录；合成结果解析 YAML 头后写入 DB 各列，语义与 SKILL.md 一致。

3.5 允许清单与禁止项（生成 / 更新硬性）

允许：

禁止写入技能包：

• 模型思考块（think / redacted_thinking 等）与写作过程叙述
• 重复 ## 标题；新旧冲突规则并存
• 真实密钥；材料中未出现的 URL/字段/数字
• 空泛触发句；聊天原文 / tool_trace 堆砌
• 已弃用却未删除的脚本或半截模板
• 变更史式长文充当现行步骤（历史留版本表）

用户侧全文：skill-content-rules.md。合成与更新须剥除思考块后再落库（skillpkg.StripThinkLikeBlocks / ParseDocument）。

---

4. 来源与存储

---

5. 进入对话的方式

1. 用户在工作区 消息 中与 我的智能体 对话。
2. 后端用 当前用户消息 对工作区技能做匹配：须名称或「适用」中有连续 3 个汉字（短技能名可用 2 字）与话术重合，避免「检查错误」误召回「检查表 / 数据查询」。再由选择器精选；选择器明确「本轮不用技能」时不再用关键词凑数。
3. 命中至多 3 条，将 触发说明 + 正文（可截断） 拼入运行时材料；前端发送后提示「模型本轮参考了以下工作区技能」。
4. 用户可在 技能中心 查看全文、版本历史，对会话沉淀技能 回滚 发布版。

创建 / 更新沉淀（在消息里说即可，勿调外部 API）：

• 创建：「把刚才的流程 生成技能 / 沉淀技能」
• 更新：「更新技能 xxx」并尽量带上名称

---

6. 合成与校验（会话沉淀）

从对话生成技能时，模型须输出 带 YAML frontmatter 的完整文档；服务端 skillpkg.ParseDocument 解析后：

• name → 覆盖默认推断名（若有效）
• description → 触发说明（须含适用/不适用）
• frontmatter 之后 → body_markdown

若模型不可用，fallback 正文仍保存，但触发说明使用结构化模板句，并鼓励用户事后在技能中心查看、通过对话 更新技能 修订。

功能类型归纳：创建或更新沉淀时，服务端调用大模型根据名称、触发说明与正文生成 2～8 字中文标签（如「天气查询」「接口调用」）；模型不可用或失败时使用规则启发式。用户可在技能详情点击 重新归纳类型 手动刷新（POST /api/v1/skills/conv/{id}/function-type/infer），不新增版本号。

合成正文须含：## 使用说明、## 完成标准、## 失败信号；有 HTTP 时另含 ## 接口与调用。触发说明 适用 行须以用户触发短语开头。

6.1 发布后验收（运营 SOP）

新发布或大改技能后，在 测试工作区 各试一轮（可人工记录，不强制自动化）：

召回异常时：没被想起 → 优先改 触发说明（适用）；被想起但做错 → 改正文步骤与 完成标准 / 失败信号。

---

7. 技能中心界面约定

---

8. 安全与治理

• 正文中 禁止 写入真实密钥；Authorization 等须为占位。
• permissions 声明工具与密钥 名，值走环境变量或工作区密钥管理（后续）。
• 含 scripts/ 的执行须沙箱与审批（产品规格 §3.6.2）。
• 版本变更、回滚写审计事件。

---

9. 实现对照

---

10. 变更记录