skill-template/development/SKILL_ACTION_RUNTIME.md

Skill Action Runtime（宿主任务中心契约）

本文是匠厂宿主 Skill Action / 任务中心 的技能侧金标准。涉及浏览器 RPA、长耗时任务、数据管理按钮、定时任务或 Agent 直接调用时必读。

边界：

文档	职责
本文	sync/async、任务中心、Agent 禁令、编排范式、队列 pick
../references/ACTIONS.md	actions.json 字段、placements、inputSchema
LOGGING.md	job_context / emit / finish / Run Journal
DATA_PATHS.md	下载/导入等落盘路径

宿主实现细节以匠厂 Host API 为准；技能侧只需保证 manifest 与 CLI 契约稳定。

---

1. 核心原则

1. 宿主管调度，技能管业务 — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
2. 长耗时 = async — 开浏览器、RPA、HTTP 大文件下载等必须 executionProfile: "async"，进任务中心。
3. Agent 禁止 exec 直跑长任务 CLI — 必须 run_skill_action；禁止 exec python main.py run + process poll 干等。
4. 进度走 Journal — emit / video.add_step → Run Journal；UI / Skill Run Card / 任务中心展示；不靠 stdout 流。
5. 显式声明 executionProfile — 宿主省略时默认 async；模板要求每个 action 写明 sync 或 async，避免歧义。

---

2. executionProfile：sync vs async

值	宿主行为	超时	任务中心
sync	内联等待 CLI 结束，把结果直接返回调用方	默认约 30s（SKILL_ACTION_SYNC_TIMEOUT_MS）	❌ 不进
async	后台 spawn Job，立即返回 jobId	Job 本身无默认墙钟上限（可暂停/停止）	✅ 进入
省略	宿主视为 async	同 async	✅

硬规则

场景	必须
浏览器 / Playwright / RPA 主路径	async + 建议 confirmation
单次可能超过 ~20s 的网络/下载	async
health / version / config-path / 纯统计 / 快速导入	sync
数据管理 toolbar	只放 async（宿主前端对 sync 结果会报错）

Agent 路径启发式（宿主行为，技能作者需知）

• 显式写了 executionProfile → 以显式为准。
• 未写时：描述含「统计 / 检查 / 不启动浏览器」等只读语义 → Agent 侧可当 sync；有 confirmation 的副作用 → async。
• 模板要求一律显式写出，不要依赖启发式。

---

3. 三入口如何感知 sync / async

三个入口统一走 POST /api/skill-actions/run，带 source.kind：

入口	source.kind	推荐
Agent	agent	run_skill_action；长任务 async，秒回 jobId
数据管理	data-management	toolbar 按钮触发 async action
定时任务	cron	Cron 配置 async action + pickCount 等参数

技能 不要 在 Python 里为三个入口写三套分支；宿主读 manifest 分流。

---

4. Action 分类与 placements 矩阵

Action 类型	executionProfile	典型 placements	confirmation
运行检查 / 版本 / 配置路径	sync	skill-detail, agent（只读）	无
库 / 队列统计	sync	skill-detail, agent	无
数据导入 / 失败重置	sync	skill-detail, agent	可选
单条副作用 RPA	async	agent, skill-detail	必须
批量顺序 RPA（pick）	async	toolbar, cron, agent	必须

禁忌：

• 高副作用 async action 不要默认只挂 toolbar（应有 confirmation）。
• 含 sensitive 参数的 action 不要挂 toolbar / cron（除非有明确安全设计）。
• 不要为了「按钮多」暴露所有 CLI 子命令。

---

5. 技能内编排范式（单内核 + 多入口）

推荐结构（对齐 create-account / download-video 金标准）：

execute_single_<biz>(...)   # 纯业务：鉴权 + 核心逻辑 + task_log；不含 job_context
cmd_run(...)                # 单条：job_context + execute_single + finish
cmd_run_pick(N, ...)        # 批量：job_context + for-loop execute_single + emit(progress) + finish
cmd_stats()                 # 只读 sync：JSON stdout，无 job_context

要点：

1. job_context 只包编排层（cmd_run / cmd_run_pick），不包 execute_single_*。
2. 批量 顺序、不并发；数量由参数 pickCount / --pick N 传入（不写死 100/200）。
3. pick 循环内：checkpoint() + emit("正在处理 {i}/{total}", progress={...})。
4. 结束：全成功 finish(success)；部分失败 finish(partial)；全失败 finish(failed)。
5. 同一浏览器 Profile / account lease：禁止并发；顺序执行 + lease 即可。

详见 LOGGING.md §2.5 与 scripts/service/task_service.py 示范。

---

6. 队列 + pick（可选，Type B 批量）

有「待处理列表」的技能（账号开通、视频下载、帖子发布等）建议：

能力	约定
队列表	status: pending → processing → success / failed
入库	数据管理 CRUD，或 import-*（相对 {skill_data}/imports/，见 DATA_PATHS.md）
消费	run --pick N，默认仅 pending
重试	reset 或数据管理改 pending；failed 不要自动重试
批次	可选 batch_id，便于筛选与任务中心对照
Manifest	*-run-pick：async，placements 含 toolbar / cron / agent，inputSchema.pickCount

批量有两种合理形态（都是顺序）：

形态	任务中心条数	适用
一次 run-pick 处理 N 条	1 条 Job	同类 RPA、同 Profile、定时消费队列
Agent/UI 触发 N 次单条 run	N 条 Job	每条独立追踪 / 独立重试

默认优先 一次 pick、一条 Job（与 create-account --pick、download --pick 一致）。

---

7. Agent / SKILL.md 契约（复制后必改）

业务技能 SKILL.md 应明确：

1. 副作用任务必须通过宿主 Skill Action（run_skill_action）调用。
2. 禁止对长任务使用 exec + process poll。
3. 单条 vs 批量 action id 与参数（如 url / pickCount）。
4. 长任务进度看任务中心 / Skill Run Card，不等 CLI stdout。

模板源仓库的 SKILL.md 含占位段落；scaffold 后按业务改写。

---

8. Policy

自动检测索引见 POLICY_MATRIX.md：

• POLICY-SKILL-ACTION-001：SKILL_ACTION_RUNTIME.md 存在；schema 含 executionProfile；有 RPA 的业务技能必须声明 async agent action。

---

9. 与宿主 API（参考）

API	用途
GET /api/skill-actions/{skillSlug}	读 manifest
POST /api/skill-actions/run	执行 action（sync inline / async job）
GET /api/skill-actions/jobs	任务中心列表
GET /api/skill-actions/jobs/{jobId}	单 Job 详情 / 事件

Agent 工具（插件）：list_skill_actions → get_skill_action → run_skill_action；正常对话不要轮询 get_skill_action_job（交给 UI / 任务中心）。