chore: initial commit
This commit is contained in:
zhaoyilun
227
docs/superpowers/specs/skill-generator-规范.md
Normal file
227
docs/superpowers/specs/skill-generator-规范.md
Normal file
@@ -0,0 +1,227 @@
|
||||
## SGClaw skill 自动生成器提示词（供调用层复用）
|
||||
|
||||
你是“SGClaw 技能打包器”。你的目标：将一段“已完成的 JS 脚本”转换为 SGClaw 可调用的技能包（优先输出 SKILL.toml + SKILL.md），并保证可通过零信任审计与运行时加载。
|
||||
|
||||
### 输入
|
||||
|
||||
你会收到以下信息（可能全部或部分提供）：
|
||||
|
||||
1. `js_script_path`：脚本文件原路径
|
||||
2. `js_script_code`：脚本内容
|
||||
3. `skill_name`（可选）：技能目录名（kebab-case）
|
||||
4. `skill_domain`（可选）：目标站点 host（如 www.zhihu.com）
|
||||
5. `skill_use_case`：一句话任务说明
|
||||
6. `tool_name`（可选）：工具名（默认 derive）
|
||||
7. `tool_description`（可选）
|
||||
8. `arg_spec`（可选）：参数说明映射，例如 `{top_n: "...", body: "..."}`
|
||||
9. `preferred_mode`：compact 或 full（默认 compact）
|
||||
|
||||
### 任务
|
||||
|
||||
严格生成一份 SGClaw 技能包，必须满足：
|
||||
|
||||
#### A. 技能包落盘结构（推荐）
|
||||
|
||||
```
|
||||
skills/
|
||||
<skill_name>/
|
||||
SKILL.toml
|
||||
SKILL.md
|
||||
scripts/
|
||||
<script>.js
|
||||
references/
|
||||
implementation-notes.md
|
||||
assets/
|
||||
notes.md
|
||||
```
|
||||
|
||||
#### B. JS 脚本适配要求
|
||||
|
||||
1. 脚本应保留“输入输出逻辑”，只做打包包装，不改变业务行为。
|
||||
2. 浏览器脚本必须以 `return <payload>` 或抛出错误（throw）结束。
|
||||
3. 禁止脚本直接依赖 expected_domain（runtime 会在 tool 层校验该参数，不会注入给脚本），如需域判断请用 `location`。
|
||||
4. 如果脚本是结构化抽取类，必须返回结构化 artifact（例如：source/sheet_name/columns/rows）。
|
||||
5. 当页面阻断（登录、验证码、反爬）时，抛出明确错误（中文），不要返回空数组当“正常完成”。
|
||||
|
||||
#### C. 生成 SKILL.toml（必须优先）
|
||||
|
||||
- `[skill]` 包含：name、description、version、author、tags
|
||||
- tool 使用：
|
||||
|
||||
```toml
|
||||
[[tools]]
|
||||
name = "<tool_name>"
|
||||
description = "<tool description>"
|
||||
kind = "browser_script"
|
||||
command = "scripts/<script_file>.js"
|
||||
```
|
||||
|
||||
- 如有参数，必须有：
|
||||
|
||||
```toml
|
||||
[tools.args]
|
||||
<arg_name> = "<arg explanation for agent>"
|
||||
```
|
||||
|
||||
- 可选 prompts：仅在 full 场景下使用；若 compact，请保持 concise，但仍可保留关键边界约束（推荐保留）。
|
||||
|
||||
#### D. 生成 SKILL.md
|
||||
|
||||
- frontmatter 至少包含 name/description/version/author/tags
|
||||
- 内容要包含：Use Cases / Workflow / Runtime Contract / Blocked-page Rule / Output Contract / Partial/Fallback 规则
|
||||
- 明确约束：
|
||||
- superrpa_browser（优先）
|
||||
- expected_domain 是裸域名
|
||||
- CSS 选择器
|
||||
- 不用 XPath、不用 jQuery :contains
|
||||
- 结构化产物为主、避免 getText 二次采集
|
||||
|
||||
#### E. 与项目约束兼容
|
||||
|
||||
- 工具名不要包含空格，尽量小写英文/下划线。
|
||||
- 不要引入新的 shell 命令执行逻辑，不要写风险命令字符串。
|
||||
- 避免远程 markdown 链接。
|
||||
- 不得引用本地绝对路径。
|
||||
- 遵守项目安全审计规则（见输出“验收清单”）。
|
||||
|
||||
### 输出格式
|
||||
|
||||
必须输出严格 JSON：
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "...",
|
||||
"target_dir": "skills/<skill_name>",
|
||||
"files": {
|
||||
"SKILL.toml": "...完整内容...",
|
||||
"SKILL.md": "...完整内容...",
|
||||
"scripts/<script>.js": "...脚本内容（可原样或轻微包装后）...",
|
||||
"references/implementation-notes.md": "...",
|
||||
"assets/notes.md": "..."
|
||||
},
|
||||
"metadata": {
|
||||
"skill_contract": {
|
||||
"expected_domain": "xxx",
|
||||
"tool_name": "...",
|
||||
"arguments": ["..."],
|
||||
"artifact_fields": ["source","sheet_name","columns","rows", ...],
|
||||
"failure_modes": ["blocked_page","partial_data","missing_rows"]
|
||||
}
|
||||
},
|
||||
"validation": [
|
||||
"审计项清单通过/待修",
|
||||
"risk_check": [...]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 约束
|
||||
|
||||
- 若无法可靠推断 artifact 结构或参数边界，必须输出 blocking_reason，不允许猜测字段。
|
||||
- output 不能包含 markdown 代码块外文字解释。
|
||||
- 只输出合法可落地内容。
|
||||
|
||||
---
|
||||
|
||||
## SGClaw skill 自动生成器规范文档（可直接存库）
|
||||
|
||||
### 1) 目标
|
||||
|
||||
将一段已有 JS 脚本自动打包为可被 sgclaw/zeroclaw 运行时加载并调用的 skill，重点用于 browser_script 任务。
|
||||
|
||||
### 2) 输入
|
||||
|
||||
- JS 脚本内容（js_script_code 或 js_script_path）
|
||||
- 目标技能名、工具名、业务场景
|
||||
- 目标域名（可选）
|
||||
- 参数说明（可选）
|
||||
|
||||
### 3) 输出
|
||||
|
||||
- skills/<skill_name>/SKILL.toml（必需）
|
||||
- skills/<skill_name>/SKILL.md（必需）
|
||||
- skills/<skill_name>/scripts/<xxx>.js（脚本）
|
||||
- skills/<skill_name>/references/（说明文档）
|
||||
- skills/<skill_name>/assets/（源素材/快照）
|
||||
|
||||
### 4) 文件标准
|
||||
|
||||
#### 4.1 目录与名称
|
||||
|
||||
- skill_name 建议 kebab-case（示例：zhihu-hotlist）
|
||||
- 工具名建议 snake_case 或小写英文下划线（示例：extract_hotlist）
|
||||
- 脚本名可与工具名一致（如 extract_hotlist.js）
|
||||
|
||||
#### 4.2 SKILL.toml 标准（最低）
|
||||
|
||||
- [skill] 必填：name/description/version/author/tags
|
||||
- version 默认 0.1.0
|
||||
- [[tools]] 至少 1 个
|
||||
- kind = browser_script（本需求场景）
|
||||
- command = scripts/<file>.js
|
||||
- [tools.args] 只列出工具参数（不包括 expected_domain）
|
||||
- 可选 prompts 数组（full 模式增强；compact 下可为空）
|
||||
|
||||
#### 4.3 SKILL.md 标准
|
||||
|
||||
建议包含：
|
||||
|
||||
- frontmatter（name/description/version/author/tags）
|
||||
- Use Cases
|
||||
- Runtime Contract
|
||||
- Blocked-Page Rule
|
||||
- Output Contract
|
||||
- Workflow / Partial-Failure Rule
|
||||
- References（指向 references/ 下文档）
|
||||
|
||||
#### 4.4 scripts/<...>.js 标准
|
||||
|
||||
- 输入：args（由 tool args 传入）
|
||||
- 输出：
|
||||
- 正常：return { ... }（建议结构化 artifact）
|
||||
- 失败：throw new Error("...")，错误信息明确（例如“登录/验证码/权限不足”）
|
||||
- 禁止：
|
||||
- 网络请求、shell 相关字符串、危险命令拼接
|
||||
- window/document 之外重度副作用（尽量纯前端提取/点击）
|
||||
- 对阻断页必须显式报错，不可静默返回空结果。
|
||||
|
||||
### 5) 与运行时兼容规则（关键）
|
||||
|
||||
- Skill 扫描优先 SKILL.toml；SKILL.md 作 fallback（但仍建议两者都保留，且 SKILL.md 作为可读性文档）
|
||||
- browser_script tool 调用会自动要求 expected_domain（在 tool 参数侧定义），脚本接收的是 args，不是 expected_domain。
|
||||
- expected_domain 必须是裸域名（如 www.zhihu.com）。
|
||||
- 浏览器操作要偏向 CSS 选择器，不用 XPath 和 :contains(...)。
|
||||
|
||||
### 6) 安全与审计（对应当前校验器）
|
||||
|
||||
- 禁止脚本文件时需开启脚本允许（allow_scripts=true）的配置上下文，否则 package 会被安全审计跳过；
|
||||
- 禁止高风险文本命令片段；
|
||||
- 禁止危险链接/路径越界；
|
||||
- 不要在技能目录中放入异常大文件和异常链接；
|
||||
- markdown 可含本地相对说明链接，不要使用不受控远程 markdown 链接。
|
||||
|
||||
### 7) 生成流程（算法）
|
||||
|
||||
1. 解析脚本目标能力：是否结构化抽取、是否需要参数、是否返回 artifact；
|
||||
2. 推断或生成：
|
||||
- skill_name
|
||||
- tool_name
|
||||
- 参数名及描述（来自脚本读取/调用）
|
||||
- 产物 schema（如有）
|
||||
3. 生成 SKILL.toml + SKILL.md；
|
||||
4. 复制/包入脚本；
|
||||
5. 生成 references/assets 注释材料；
|
||||
6. 输出“校验清单”（通过/待修）。
|
||||
|
||||
### 8) 验收清单（交付前）
|
||||
|
||||
- [ ] 目录和文件存在
|
||||
- [ ] SKILL.toml 能被 toml 解析
|
||||
- [ ] kind="browser_script" + command 指向现有脚本
|
||||
- [ ] expected_domain 在运行时参数上成立（文档明确）
|
||||
- [ ] 脚本可运行并返回可消费 payload
|
||||
- [ ] 阻断/异常场景有显式 error 语句
|
||||
- [ ] 触发规则/边界写进 SKILL.md
|
||||
- [ ] 完全不包含高风险命令文本
|
||||
- [ ] 可被审计脚本通过（或给出逐项修复建议）
|
||||
|
||||
Reference in New Issue
Block a user