Add label master skill
This commit is contained in:
wuyang6
@@ -271,18 +271,76 @@ output/ 最终交付文件
|
||||
skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
Skill 是可以独立维护、独立安装、被 Agent 读取和执行的能力包。它不只是 prompt，也不只是脚本，而是某类任务的“能力入口”：可以包含流程、知识、脚本、配置和模板，但必须清楚说明边界。
|
||||
|
||||
#### 适合做成 Skill 的内容
|
||||
|
||||
当前项目里的 Skill 大致分为四类：
|
||||
|
||||
| 类型 | 代表 | 适合承载 |
|
||||
|------|------|----------|
|
||||
| 流程编排型 | `product-data`、`online-mining`、`eval-repair` | 分阶段流程、review 门禁、工具调用顺序、产物规范 |
|
||||
| 工具封装型 | `elk-fetch`、`data-factory-sql` | 外部系统调用脚本、CLI 参数、依赖说明、返回格式 |
|
||||
| 知识增强型 | `model-iteration/knowledge/*`，后续标签知识 Skill | 标签定义、边界规则、案例、决策依据 |
|
||||
| 混合工程型 | `model-iteration` | 复杂工程闭环：流程 + 知识 + 脚本 + 配置 |
|
||||
|
||||
判断一件事放在哪里：
|
||||
|
||||
- **Skill**：告诉 Agent 怎么做、什么时候停、读哪些知识、如何组织流程。
|
||||
- **Knowledge / references**：放大段业务知识、规则、案例和字段说明。
|
||||
- **Scripts**：放可重复、确定性、容易写错的执行逻辑。
|
||||
- **Tools**：放平台级、强约束、需要长期稳定维护的能力，例如 records 转换、校验、线上 parquet 检索。
|
||||
|
||||
#### 推荐目录结构
|
||||
|
||||
```text
|
||||
skills/<skill-name>/
|
||||
SKILL.md 必须，Agent 触发和执行该能力的入口
|
||||
README.md 可选，给维护者看的说明
|
||||
scripts/ 可选，确定性脚本或 CLI
|
||||
knowledge/ 可选，业务知识、标签规则、案例
|
||||
references/ 可选，长文档、字段说明、API 说明
|
||||
assets/ 可选，模板、静态资源
|
||||
config.yaml 可选，默认参数
|
||||
```
|
||||
|
||||
不建议提交：
|
||||
|
||||
- `__pycache__/`
|
||||
- `.venv/`
|
||||
- 临时运行结果
|
||||
- 用户私有 token、key、cookie
|
||||
- 大体积产物或线上原始数据
|
||||
|
||||
#### SKILL.md frontmatter
|
||||
|
||||
`SKILL.md` frontmatter 至少包含：
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: product-data
|
||||
description: 简短说明这个 skill 做什么。
|
||||
when_to_use: 说明什么场景应该触发。
|
||||
name: skill-name
|
||||
description: 简短说明这个 skill 做什么，尽量覆盖触发关键词。
|
||||
when_to_use: 说明什么场景应该触发，包含用户常见说法。
|
||||
aliases: optional-alias
|
||||
allowed_tools: read_file, write_file, python_exec
|
||||
---
|
||||
```
|
||||
|
||||
字段约定：
|
||||
|
||||
- `name`：短横线命名，稳定、可读，例如 `online-mining`、`data-factory-sql`。
|
||||
- `description`：面向模型召回，说明能力范围和典型触发词。
|
||||
- `when_to_use`：面向模型决策，说明什么场景应该使用。
|
||||
- `aliases`：兼容旧名字、团队口头叫法。
|
||||
- `allowed_tools`：列出该 Skill 合理使用的工具，避免能力越界。
|
||||
|
||||
命名建议：
|
||||
|
||||
- 用“能力名”而不是项目临时代号，例如 `model-iteration` 优于 `zk-model`。
|
||||
- 工具封装型可以用系统名，例如 `elk-fetch`、`data-factory-sql`。
|
||||
- 知识型可以用知识域名，例如 `label-master`。
|
||||
- 不要用过泛的名字，例如 `helper`、`tools`、`data`。
|
||||
|
||||
维护规则：
|
||||
|
||||
- 用中文写主要流程说明，方便团队后续维护。
|
||||
@@ -291,6 +349,110 @@ allowed_tools: read_file, write_file, python_exec
|
||||
- Skill 如果依赖脚本，脚本放在该 Skill 目录下，并通过 `python_exec` 调用。
|
||||
- 新增业务 Skill 后，可以在 Web UI Skill 列表中按会话启用或关闭。
|
||||
|
||||
#### SKILL.md 内容结构
|
||||
|
||||
推荐顺序：
|
||||
|
||||
```text
|
||||
1. 这个 Skill 解决什么问题
|
||||
2. 输入假设
|
||||
3. 必要工作流
|
||||
4. 需要用户 review 的门禁
|
||||
5. 输出目录和产物约束
|
||||
6. 可用脚本或知识文件
|
||||
7. 常见错误和禁止事项
|
||||
```
|
||||
|
||||
如果 `SKILL.md` 超过几百行，优先拆分：
|
||||
|
||||
- 长业务规则放 `knowledge/`
|
||||
- 长 API/字段说明放 `references/`
|
||||
- 可执行逻辑放 `scripts/`
|
||||
- `SKILL.md` 只保留导航、流程和关键门禁
|
||||
|
||||
#### 脚本型 Skill 约定
|
||||
|
||||
脚本型 Skill 典型如 `elk-fetch`、`data-factory-sql`、`model-iteration`。
|
||||
|
||||
约定：
|
||||
|
||||
- Python 脚本优先放在 `scripts/`，少量历史 Skill 可保留根目录脚本，但新 Skill 优先使用 `scripts/`。
|
||||
- Agent 调用脚本优先使用 `python_exec`，不要让模型直接 `bash python xxx.py`。
|
||||
- 依赖缺失时使用 `python_package` 安装到账号级 Python 环境。
|
||||
- 脚本参数要稳定，输出尽量给 JSON 或结构化摘要，方便 Agent 继续分析。
|
||||
- 不要在脚本里硬编码 API key、token、个人路径。优先读取环境变量或用户 home 下配置。
|
||||
- 长耗时脚本必须考虑超时、分页、采样或断点，不要默认全量扫描。
|
||||
|
||||
脚本调用示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"script_path": "skills/example/scripts/run_task.py",
|
||||
"args": ["--input", "xxx"],
|
||||
"timeout_seconds": 120,
|
||||
"max_output_chars": 20000
|
||||
}
|
||||
```
|
||||
|
||||
#### 知识型 Skill 约定
|
||||
|
||||
知识型 Skill 适合承载标签体系、业务规则、字段定义、案例库。
|
||||
|
||||
约定：
|
||||
|
||||
- `SKILL.md` 只写“什么时候读哪些知识文件”。
|
||||
- `knowledge/` 下按主题拆文件，文件名语义化。
|
||||
- 每个知识文件开头写清楚适用范围。
|
||||
- 不要把所有知识一次性塞进 `SKILL.md`。
|
||||
- 面向标签、路由、复杂度等判断时，鼓励输出“候选、依据、排除项、不确定点”，不要过早封装成黑盒单步分类。
|
||||
|
||||
例如后续中控标签知识可以先设计为：
|
||||
|
||||
```text
|
||||
skills/label-master/
|
||||
SKILL.md
|
||||
knowledge/
|
||||
agents.md
|
||||
functions.md
|
||||
complex_rules.md
|
||||
boundary_cases.md
|
||||
examples.md
|
||||
scripts/
|
||||
build_index.py
|
||||
```
|
||||
|
||||
#### 外部 Skill 仓库安装约定
|
||||
|
||||
允许同事把能力打包为独立 git 仓库维护，再安装到本项目：
|
||||
|
||||
```text
|
||||
skills/<skill-name>/
|
||||
```
|
||||
|
||||
安装或迁移时需要检查：
|
||||
|
||||
- 是否有合法 `SKILL.md` frontmatter。
|
||||
- skill 名是否符合项目命名风格。
|
||||
- 是否包含不该提交的缓存、运行产物、私钥、token。
|
||||
- 脚本是否能通过 `python_exec` 调用。
|
||||
- 依赖是否写清楚，缺包时能通过 `python_package` 安装。
|
||||
- 输出目录是否遵守当前会话 `output/` / `scratchpad/` 公约。
|
||||
- 高风险动作是否有用户确认门禁。
|
||||
|
||||
外部仓库可以保留自己的 README，但真正影响 Agent 行为的是 `SKILL.md`。
|
||||
|
||||
#### 高风险动作门禁
|
||||
|
||||
Skill 中只要涉及下面动作，必须先展示计划并等待用户确认：
|
||||
|
||||
- 批量修改训练数据或标签定义。
|
||||
- 提交训练、部署模型、启动 CML job。
|
||||
- 写入外部路径或覆盖已有产物。
|
||||
- 推送 git、改远端配置。
|
||||
- 导出包含敏感线上字段的数据。
|
||||
|
||||
用户明确说“开始评测”“查一下”“分析一下”时，可以执行只读分析；不要自动升级成训练、部署或批量改数据。
|
||||
|
||||
### Tool 公约
|
||||
|
||||
工具是稳定执行边界。
|
||||
|
||||
Reference in New Issue
Block a user