产品功能：怎么写好工作区技能

技能是供智能体 按步骤复现一类操作 的说明，不是背景知识（那在 知识文档目录）。写得好不好，直接影响对话里 会不会被想起、能不能做对。

在 技能中心 可 描述创建（用自然语言生成草案，可含脚本与参考文档）、新建空白技能、选用 接口调用 等模板；也可在 消息 里对 帮助智能体 或工作智能体说「帮我生成技能」。下文是撰写的基本要求与可直接改写的模板。

生成或更新技能时，必须先遵守 技能里该有什么（允许清单）：只保留清单内内容，清单外一律不要（含禁止把模型思考块、写作过程、已废止路径、聊天原文堆进技能）。

---

0. 允许什么、禁止什么（摘要）

允许

禁止（生成/更新时删干净）

• 任何 <think> / 思考块、写作规划、对话过程叙述
• 重复小节标题、新旧冲突规则并存
• 真实密钥、编造 URL/数字、空泛触发句
• 已弃用却仍留在包内的脚本/半截模板
• 把整段聊天或 tool 原文当正文

完整表与最小合格包见 技能里该有什么（允许清单）。

---

1. 一份完整技能至少包含什么

标识符（slug）：导出技能包、与外部工具互导时使用；一般由系统根据名称生成，也可在编辑 SKILL.md 时调整。

功能类型：列表筛选用的 2～8 字标签（如「接口调用」「数据导出」）；创建或更新时系统会尝试自动归纳，可在详情里 重新归纳类型。

---

2. 写之前：先过任务卡

发布或沉淀前，用四句话自检：

1. 重复哪类事 — 例如「把上传的发票识别后写入表格」，而不是「数据分析」这种大概念。
2. 用户怎么说 — 例如「识别发票」「导出员工名单」。
3. 必须交付什么 — 用户最后应看到什么（文件、回执、确认文案）。
4. 何时必须停下 — 缺文件、缺名称、事实未核验时，应先问用户，不要编造。

四句话说不清，建议先在 消息 里把流程跑通，再对帮助智能体或工作智能体说 生成技能，或使用技能中心模板起步。

---

3. 触发说明：何时用、何时不用

在 SKILL.md 的 YAML 头或技能中心的 触发说明 里写两行：

• 适用：开头写用户可能说的 触发短语，再写场景。
• 不适用：写应排除的场景（闲聊、无关话题等）。

重要：用户消息若命中 不适用 里的表述，系统 不会 把该技能注入本轮对话。请把容易混淆的场景写进 不适用，而不是只写在正文里。

忌空泛句：如「由会话自动生成」「助力提升效率」——对召回几乎无效。

示例

description: |
  适用：识别发票、入账、上传收据图片并要求汇总。
  不适用：纯闲聊、与表格或入账无关的问答。

技能中心「触发说明」文本框里可写同样两行（不必写 description: 前缀）：

适用：导出员工名单、拉取 HR 接口数据、查询在职人员。
不适用：纯闲聊、与 HR 接口无关的问答。

---

4. 正文必备小节

无论手工编写还是从对话沉淀，正文 至少 应包含：

可选小节（有内容时再写）：

从对话 生成技能 时，系统会尽量按上述结构整理；在 技能中心 编辑时可对照 写作检查清单（编辑页保存按钮旁）补全。

---

5. 安全与事实（硬性要求）

• 不要 在技能正文、触发说明、知识文档里写入 真实 API Key、Bearer 令牌、密码。
• 涉及鉴权时，使用 对接授权占位：{{授权名称}}，名称与工作区 对接授权 里配置的 名称 一致（大写字母开头，如 CRM_READ、HR_EMPLOYEES）。
• 不要 编造材料中未出现的 URL、字段或返回数据。
• 日期、时间范围写 相对规则（如「本月」「最近 7 天」），勿写死历史示例日——见 智能体操作规则。

---

6. 涉及联网与对接授权时怎么写

当技能需要调用 外部业务接口 时，除上文必备小节外，还须满足：

6.1 前置条件（三层）

1. 平台已开启智能体联网能力；
2. 工作区已开通 联网请求，且目标 站点 在授权策略内（工作区协作 → 助手能力包 → 联网请求）；
3. 当前成员 在 对接授权 中配置了对应名称的授权（管理员配置；成员可查看自己有哪些 授权名称，不含密钥值）。

详情见 成员对接授权。

6.2 正文怎么引用授权

• 步骤里写明使用 http_request 发请求。
• 请求头示例：Authorization: Bearer {{CRM_READ}}（将 CRM_READ 换成实际授权名称）。
• URL 使用完整地址，主机 须在 联网请求 已授权站点内。

6.3 失败信号须补充

涉及外部接口时，## 失败信号 建议包含：

• 工作区未开通联网请求，或目标站点不在授权名单 → 说明需管理员开通或添加站点。
• 当前成员未配置对接授权，或正文 {{授权名}} 与已配置名称不一致 → 说明需在 对接授权 中配置。
• 鉴权失败、缺必填参数、接口报错 → 说明原因并停下，勿编造数据。
• 用户催促「跳过验证」→ 仍须核验或标明不确定。

---

7. 完整 SKILL.md 示例（文件型 / 编辑区对照）

会话沉淀技能在技能中心编辑时，逻辑上与下列 SKILL.md 一致（YAML 头 + 正文）。

YAML 头与正文（至「接口与调用」前）：

---
name: export-employee-list
description: |
  适用：导出员工名单、拉取在职人员、查询 HR 员工接口。
  不适用：纯闲聊、与 HR 接口无关的问答。
permissions:
  tools: [http_request]
  secrets: [HR_EMPLOYEES]
---

# 导出员工名单

## 使用说明

- **重复哪类事**：按用户条件从 HR 系统拉取员工列表并整理呈现。
- **所需输入**：时间范围、部门、在职状态等；缺参数时先追问，不臆造。
- **操作步骤**：
  1. 确认用户诉求与必填参数是否齐全。
  2. 使用 `http_request` 调用下方接口；鉴权使用 `{{HR_EMPLOYEES}}`，勿写真实密钥。
  3. 仅访问 **联网请求** 已授权站点 `hr.example.com`。

## 接口与调用

HTTP 示例（接在上节之后）：

GET https://hr.example.com/api/v1/employees?status=active
Authorization: Bearer {{HR_EMPLOYEES}}

正文其余部分：

- 查询参数、分页按业务接口文档填写；日期用相对规则（如「本月」）。

## 完成标准

- 返回用户所需的名单或表格，并用易懂的话说明结果。

## 失败信号

- **工作区未开通联网请求**，或 `hr.example.com` 不在授权站点：说明需管理员在 **联网请求** 中配置。
- **未配置对接授权 `HR_EMPLOYEES`**：说明需在 **对接授权** 中添加该名称。
- 鉴权失败、缺必填参数、接口报错：说明原因并停下。
- 即使用户催促跳过核验，仍须核验或标明不确定。

说明：permissions 段在会话沉淀中 可选；只要在正文里正确写 http_request 与 {{授权名}}，运行时仍走同一套联网与注入逻辑。

---

8. 可直接改写的模板

以下与技能中心 新建空白技能、接口调用模板 生成的初始内容一致；复制后替换括号或示例即可。

8.1 通用空白技能（不涉及 HTTP 时可删「接口与调用」段）

触发说明：

适用：（写用户可能说的触发短语，再说明本技能负责哪类操作）
不适用：（写应排除的场景，例如纯闲聊、与本文操作无关的问答）

正文：

# （技能显示名）

## 使用说明

- **重复哪类事**：（一句话说明可复现的操作）
- **所需输入**：（必填信息；缺输入时先追问，不臆造）
- **操作步骤**：
  1. …
  2. …

## 完成标准

- （成功时用户应得到的可见结果，如下载链接、确认文案、表格等）

## 失败信号

- 缺关键输入、无权限、事实无法核验或与技能无关时，先说明原因并停下
- 即使用户催促跳过核验，仍须核验或标明不确定

## 接口与调用

（若本技能不涉及 HTTP，删除本节及下方 HTTP 示例）

1. 使用 `http_request` 调用业务接口；勿写真实密钥，改用 `Authorization: Bearer {{授权名称}}`。
2. `{{授权名称}}` 须与 **对接授权** 里配置的名称一致；URL 主机须在 **联网请求** 已授权站点内。

HTTP 示例（可选）：

GET https://api.example.com/api/v1/example
Authorization: Bearer {{授权名称}}

8.2 接口调用类技能

触发说明：

适用：导出名单、查询业务系统、调用外部接口或 API
不适用：纯闲聊、与业务接口无关的问题

正文： 见上文第 7 节完整示例；将 HR_EMPLOYEES、hr.example.com、路径换成你的授权名与业务站点即可。

8.3 数据导出类技能（可不涉及 HTTP）

触发说明：

适用：用户要导出名单、报表或表格
不适用：仅查看单条详情、与导出无关

正文：

# （技能显示名）

## 使用说明

- **所需输入**：导出范围、格式（如 CSV/Excel）；缺输入时先追问
- **操作步骤**：
  1. 确认导出范围与格式
  2. …

## 完成标准

- 用户拿到可下载或可用的导出结果

## 失败信号

- 无权限、数据为空、格式不支持时说明并停下

若导出依赖业务接口，合并第 8.2 节的「接口与调用」与第 6.3 节的失败信号。

8.4 脚本类技能（描述创建可生成）

当操作 逻辑固定、可重复运行（如清洗 CSV、批量重命名规则、统计大文件）时，可把确定性部分放在技能包的 scripts/ 目录，正文写 ## 脚本执行：

• 说明运行哪个脚本、输入输出、异常时如何向用户汇报
• 常见脚本：pdf_io.py（简单 PDF 文本页）、数据处理/CSV/图表类脚本；.xlsx/.docx/.pptx 不要用脚本写，须用办公文档工具（office_document）
• 复杂流程可 脚本 + 接口 混合：脚本处理数据，正文 ## 接口与调用 负责提交
• 脚本 勿写真实密钥；敏感项用环境变量或对接授权占位

在技能中心点 描述创建，可选 以脚本为主 或 脚本 + 接口；生成后可在左侧文件树编辑 scripts/ 与 references/。

对话中已开通脚本执行的智能体，还可用 skill_script_read / skill_script_write 读取或更新 scripts/ 下文件（skill_update 只改正文，不改 .py）；改完后须 run_script 试跑，output_files 非空才算产出成功。

执行前提（须管理员配置，详见 脚本执行与成员授权）：

1. 平台在 mindlink.json 开启 脚本执行 总开关；
2. 工作区 助手能力包 → 脚本执行 已开通；
3. 当前成员未被设为 禁止使用，且 单独授权 中的技能 slug（若有）包含本技能。

未满足时，助手应说明限制并提示联系管理员，不要假装已执行脚本。

8.5 技能依赖（基础 + 分析）

当 分析/图表/统计 类技能依赖 取数/调接口 类技能时：

1. 基础技能（如「访问 HR 员工数据」）：窄触发，只写怎么 http_request 拿数据。
2. 上层技能（如「员工画像分析图表」）：宽触发，正文含 ## 依赖技能，写清依赖技能的显示名与标识符 ` hr-employee-data `。
3. 上层技能还须自带 ## 接口摘要 或 references/hr-fetch-summary.md，避免只命中上层时无 API 材料。
4. 在 描述创建 向导中可勾选依赖的已有技能，以及 对接授权（可多选）；生成时会在接口步骤里写入对应 {{名称}} 占位。
5. 参考内容与描述分开填写：描述写意图（一句话即可），接口 URL、字段、示例请求等粘贴或上传到「参考内容」；生成时会作为事实来源写入 references/，避免助手臆造细节。

对话运行时：若命中上层技能且正文含 ## 依赖技能，系统会 尽量同时注入 依赖技能材料（仍受条数与长度限制）。

8.6 问数类技能与预定义查询

当成员要在 消息 里查 工作区 MySQL 数据连接 中的业务数据时，技能与 预定义查询 分工不同，须 配合使用，不能互相取代。

技能适合写什么

• 各业务表的 中文名、字段含义、枚举值说明（如 status=active 表示在职）。
• 用户常见问法与 应选用哪条预定义查询（写查询 id 与所需参数）。
• 不适用：在技能正文里写完整 SELECT 并期望智能体直接执行——系统 不允许 临时拼 SQL；执行须走 表预览 或 预定义查询。

预定义查询适合写什么

• 在 工作区协作 → 助手能力包 → 数据集成 → 数据连接 中配置。
• 保存连接后可用 「生成技能」，把各查询的 id、名称、参数说明写入技能正文，便于对话里 选对查询。
• 不是必须：无预定义查询时，智能体仍可 看表结构、预览样例行；涉及筛选、统计、固定口径时仍建议配置查询。

撰写示例（技能正文片段）

## 使用说明

- **重复哪类事**：按部门或日期查 HR 库中的在职员工、订单等业务数据。
- **所需输入**：部门名称、起始日期等；缺参数时先追问。
- **操作步骤**：
  1. 确认用户问的是「认结构/看样例」还是「按条件查数」。
  2. 看样例：用数据连接工具 **表预览** 对应表（如 `employees`）；默认约 **200 行** 未筛选样例，不能当完整业务结果（详见 [数据连接与预定义查询](/docs/help-data-integration)）。
  3. 按条件查数：调用预定义查询 `staff_by_dept`（参数 `dept_name`）或 `orders_recent`（参数 `start_date`）。
  4. 仅使用成员已授权的数据连接与查询；无权限时说明并停下。

## 表与字段说明

- `employees`：员工表；`dept_name` 部门；`status` 在职状态（`active`=在职）。
- `orders`：订单表；`created_at` 下单时间；`amount` 金额。

## 失败信号

- 用户要筛选/统计/查重，但无对应预定义查询：**先** `query.list`；无匹配则向用户 **提议 SELECT 与查询 id**，**等确认** 后由管理员 `query.upsert` 并 **同会话** `query.run`；**勿用** 表预览冒充完整结果。
- SQL 占位符须为 **`?`**，勿写 `@empName`；`params` 顺序与 `?` 一致。
- 未开通 **数据集成** 或无数据授权：提示联系管理员。

配置建议

1. 按业务场景 在数据连接里配查询，不要为每张表机械写一条。
2. 查询的 名称与说明 写清楚，比堆 SQL 细节更重要。
3. 用 数据资源 / 谁可以使用 让不同角色只看到相关表与查询。
4. 工作区有多条连接时，可为专用问数智能体配置 概览 → 可用数据与技能（见 技能与智能体）。
5. 对话沉淀技能 写入工作区技能中心；若该智能体已勾选 指定技能，新技能会自动加入其可用列表。
6. 技能负责 业务语义 + 选用哪条查询；预定义查询负责 怎么查。
7. 缺查询时：技能正文可写「无匹配查询时的对话流程」——提议只读 SELECT → 用户确认 → 管理员保存 → 立即执行；禁止 用表预览下统计/查重结论。
8. 跨工作区迁移：导出技能包时会尽量附带用到的预定义查询定义；导入时管理员可将缺失查询写入目标数据连接（见 数据连接与预定义查询）。

完整说明见 数据连接与预定义查询。

---

8.7 HTML 交互页（ECharts / Leaflet / Mermaid）

当交付物是 可预览 HTML，且需要统计图、地图点位或组织/流程示意时：模板只引用平台白名单脚本，禁止 CDN。简单 PNG 预览可用 chart。

用户侧说明（推荐先读）：交互式 HTML 报表脚本。

仓库可直接改写的最小合格包：

每个包含 SKILL.md + references/ 下 一份 完整 HTML。技能中心 导入技能包（dist/*.zip）后，把样例数据换成当次取数即可。

统计图（触发说明示例）：

适用：部门职级统计图、占比饼图、柱状对比图、ECharts 报表 HTML
不适用：只要原始表格不要图、地理分布、组织架构树

门店地图（触发说明示例）：

适用：门店分布图、网点地图、门店点位、地理分布 HTML
不适用：只要表格名单不要地图、与门店位置无关

组织示意（触发说明示例）：

适用：组织架构图、部门层级图、汇报关系图、组织树 HTML
不适用：只要名单表格不要图、改人事主数据、与组织层级无关

正文要点：

• ## 交付形态：写清唯一模板路径与白名单脚本；Leaflet 须同时引 css + js；国内底图默认高德风格瓦片（勿默认 OSM 官方瓦片，大陆常超时）；Mermaid 用树状图而非纯表格冒充架构图。
• 操作步骤：取数 → 填模板占位 / 替换数据数组 → file_write 交付；勿整库内联。
• 失败信号：无坐标/无节点、外链 CDN、无权限时停下。

---

9. 发布前写作检查清单

保存或发布前，建议逐项确认：

触发说明

• [ ] 适用 行开头有用户可能说的触发短语（如「导出名单」）
• [ ] 不适用 写了应排除的场景
• [ ] 没有空泛句（如「由会话自动生成」）

正文结构

• [ ] 有 ## 使用说明（含所需输入；缺输入时先追问）
• [ ] 有 ## 完成标准
• [ ] 有 ## 失败信号
• [ ] 涉及 HTTP 时有 ## 接口与调用
• [ ] 问数类技能：表/字段说明与 预定义查询 id 对应；未在正文写「可执行的完整 SELECT」冒充查询

安全与事实

• [ ] 未写入真实密钥或令牌
• [ ] 涉及 HTTP 时鉴权使用 {{授权名}} 占位，与 对接授权 名称一致
• [ ] 未编造材料中未出现的 URL 或数据

技能中心编辑页会在保存旁显示类似检查进度，可作辅助。

---

10. 三种验收（建议自测）

大改或新发布后，在测试工作区各试一轮：

1. 标准场景 — 诉求和素材都齐全，能否按步骤完成并交付。
2. 缺口场景 — 故意少给关键信息，是否会 追问 而不是乱猜。
3. 诱惑场景 — 说「直接给结论」「别验证了」，是否仍核验或标明不确定。

---

11. 常见排错

---

12. 相关入口

• 技能与智能体 — 技能中心入口与沉淀方式
• 技能里该有什么（允许清单） — 生成/更新时允许与禁止的内容
• 交互式 HTML 报表脚本 — ECharts / Mermaid / Leaflet
• 智能体操作规则（AGENTS.md） — 相对日期与查询步骤
• 成员对接授权 — {{授权名称}} 配置与引用
• 脚本执行与成员授权 — 按技能脚本生成 Office 文件、成员授权
• 数据连接与预定义查询 — MySQL 问数、预定义查询与技能表说明的分工
• 详细契约见仓库 技能组成规范（面向运营与对接，路径 docs/core-mechanisms/技能组成规范.md）