draft-closing-report-default/development/SKILL_ACTION_RUNTIME.md

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

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

**产品入口（平级关系、何时挂哪个）**先读 PRODUCT_SURFACES.md；本文管 sync/async、任务中心与编排。

边界：

文档	职责
本文	sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出
../references/ACTIONS.md	actions.json 字段、placements、bind.tables、inputSchema、跨表 Lookup、字段条件显隐 visibleWhen、本地路径 file/directory + 可选 pathRoot、选择摘要「已选择」与映射 readOnly / revealInForm、按钮中文名 label 参考
LOGGING.md	job_context / emit / finish / Run Journal
DATA_PATHS.md	下载/导入等落盘路径

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

---

1. 核心原则

1. 宿主管调度，技能管业务 — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
2. 单业务内核、多入口 — 数据管理、定时任务、Agent、技能详情与直接 CLI 复用同一 domain service；禁止按入口复制业务逻辑。
3. 五职责正交 — placements / bind.tables / executionProfile / entrypoint / domain service 各管一事（见 ACTIONS.md）。可选第六轴 policy（见 references/POLICY.md）：未启用 = L0 与今日一致。可选 hostEffects / steps（见 ACTIONS.md）：数据管理交互前后的 UI/级联编排；省略 = 不额外改 UI（匠厂宿主 ≥2.8.5）。可选 hoverHint（见 ACTIONS.md）：数据管理工具栏悬停；省略 = 不显示，不回退说明或确认黄条。可选 visibleWhen（见 ACTIONS.md）：Action 参数表单字段条件显隐；省略 = 字段始终平铺；勿与 Policy L3 行态 visibleWhen 混淆；勿用其藏映射主键。可选 pathRoot（见 ACTIONS.md）：file/directory 原生选路对话框起始目录（相对技能数据根；省略默认 {skill_data}/input）。可选 bind.labelColumn（见 ACTIONS.md）：选择摘要可读标签列；省略 = 宿主常见列名启发。可选 revealInForm（见 ACTIONS.md）：有「已选择」时仍强制显示某 readOnly 字段；省略 = 映射只读默认不占 form 参数区（仍提交）。可选 cellPresentation（见 references/CELL_PRESENTATION.md）：单元格语义标色；省略 = P0。
4. 长耗时建议 async — 开浏览器、RPA、HTTP 大文件下载等建议 executionProfile: "async"，进任务中心；这是对方法的选择，不限制可以出现在哪些 placement / 入口。
5. Agent：短 CLI / 长 Action — 短查询可用共享 Python bash CLI；长任务 / RPA 禁止 exec + process poll，必须 run_skill_action。
6. 进度走 Journal — emit / video.add_step → Run Journal；UI / Skill Run Card / 任务中心展示；不靠 stdout 流。
7. 显式声明 executionProfile — 心智默认 sync、例外才 async；每个 action 必须写明 sync 或 async；宿主省略时按 sync，新技能仍禁止赌缺省；禁止第三种模糊模式（auto / background / deferred 等）。

---

2. executionProfile：sync vs async

心智（先记住）

1. 默认按 sync 想：多数 Action（诊断、统计、入队、秒级查询）是短调用，当场返回，不进任务中心。
2. 只有特殊情况标 async：开浏览器 / RPA / 长下载 / 需要进度·暂停·停止时，才显式 "executionProfile": "async"，进入任务中心。
3. 匠厂宿主：actions.json 若省略 executionProfile，按 sync 处理（不再把漏写当成进任务中心）。
4. 新技能仍须显式写出 sync 或 async（模板 Schema / POLICY-SKILL-ACTION-002 硬门禁），禁止赌宿主缺省；显式写出也便于人和 AI 阅读。

值	宿主行为	超时	任务中心
sync（或省略时的宿主缺省）	调用方等待 CLI 结束，直接返回结构化结果或结构化错误；不创建后台 Job	默认约 60s（SKILL_ACTION_SYNC_TIMEOUT_MS）	❌ 不进
async（须显式声明）	后台 spawn Job，立即返回 jobId；emit / checkpoint / finish；长任务应支持暂停/停止/取消检查	Job 本身无默认墙钟上限	✅ 进入

直接执行 CLI：终端等待进程结束。宿主经 Action 调用同一 CLI：再按 executionProfile 分流。技能不得自建任务中心。

选择建议（不是 placement 硬限制）

场景	建议
浏览器 / Playwright / RPA 主路径	async + 建议 confirmation
单次可能接近或超过约 60s 的网络/下载/同步	async
health / version / config-path / 纯统计 / 秒级查询	sync
任意 placement（含 toolbar）	允许 sync 或 async；以 manifest 为准

合法：sync|async × toolbar|row|batch|cron|agent|skill-detail。

历史说明：旧文档曾错误地把数据管理按钮入口与异步执行方式绑死。该约束已废止；模板测试与 Schema 不得再建立「入口位置决定 sync/async」一类硬耦合。旧版宿主曾「省略 → async」；当前宿主为「省略 → sync」。新技能仍须显式声明，不得依赖省略行为。

---

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

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

入口（匠厂侧栏 / 界面）	常见 source.kind	技能侧	开发者怎么测
新建任务（对话 Agent）	agent	placements 含 agent；run_skill_action	侧栏「新建任务」→ 对话触发
数据管理 · 顶栏	data-management	toolbar + 必填 bind.tables	侧栏「数据管理」→ 表顶栏按钮
数据管理 · 行级	data-management	row（建议 bind.tables + inputMapping）	操作列和/或行右键（及可选「⋯」）可见并触发（需主键）；技能配什么就显示什么
数据管理 · 批量	data-management	batch	勾选行后点批量按钮
定时任务	cron	placements 含 cron	侧栏「定时任务」→「技能直调」
任务中心	（各入口触发的 Job）	executionProfile: "async"	侧栏「任务中心」查看进度 / 取消；不是 placement
技能详情	skill-detail	placements 含 skill-detail	市场详情安装/四 Tab；详情直调按钮随宿主上线后同等自测

技能 不要 在 Python 里按 source / placement 写业务分叉；宿主读 manifest 分流展示与等待策略。
已声明的入口都要自测，不要只测对话。操作清单见 DEVELOPMENT.md §15 第七步。

---

4. Action 分类与 placements（示例，不是限制）

下表只表示常见组合示例。placements 以 manifest 为准；sync/async 不影响展示入口。

Action 类型	常见 executionProfile	常见 placements	confirmation
运行检查 / 版本 / 配置路径	sync	skill-detail, agent	无
库 / 队列统计	sync	skill-detail, agent	无
外源 → 本地库同步	sync 或 async	可含 toolbar（须 bind.tables）、cron、agent、skill-detail	可选
单行 / 批量数据管理动作	sync 或 async	row / batch（建议 bind.tables；行内常用 inputMapping）	可选
数据导入 / 失败重置	sync 或 async	skill-detail, agent	可选
单条副作用 RPA	async（建议）	agent, skill-detail	建议
批量顺序 RPA（pick）	async（建议）	toolbar, cron, agent	建议

禁忌：

• 高副作用 action 不要默认只挂 toolbar（应有 confirmation）。
• 含 sensitive 参数的 action 不要挂 toolbar / cron（除非有明确安全设计）。
• 不要为了「按钮多」暴露所有 CLI 子命令。
• 不要按入口复制多套采集 / 同步 / 处理实现。

---

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

推荐分层：

scripts/cli/app.py                 # 参数解析 → 调用 task / service
scripts/service/task_service.py    # job_context / emit / checkpoint / finish / 错误转换
scripts/service/<domain>_service.py  # 唯一业务内核
scripts/db/*_repository.py         # 只负责读写与事务
assets/actions.json                # 声明入口、参数、placement、executionProfile、bind

长任务 / RPA 常见拆分（勿把 job_context 塞进纯业务内核）：

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_* / domain service。
2. 批量 顺序、不并发；数量由参数 pickCount / --pick N 传入。
3. pick 循环内：checkpoint() + emit("正在处理 {i}/{total}", progress={...})。
4. 结束：全成功 finish(success)；部分失败 finish(partial)；全失败 finish(failed)。
5. 同一浏览器 Profile / account lease：禁止并发。
6. 兼容旧命令（例如旧 export 需先刷新）必须调用同一 sync / domain 内核，禁止重写采集逻辑。

详见 LOGGING.md §2.5 与 scripts/service/task_service.py 示范。可复用契约样例见 tests/samples/test_action_core_contract.py.sample、tests/samples/test_sync_contract.py.sample。

---

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

有「待处理列表」的技能建议：

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

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

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

默认优先 一次 pick、一条 Job。

---

7. 业务同步与系统导出

能力	方向	负责方
同步 / refresh / collect	外部来源 → 技能本地 SQLite	技能 domain service
导出当前数据表	本地库 → CSV/Excel	宿主数据管理统一导出
特殊业务报告（文件）	多表合并 / 特殊格式 → output/	仅系统导出不足时提供 export-*
HTML 页面报告	写入 {skill_data}/html/*.html	技能生成；宿主扫描预览；重新生成 Action id 固定为 render-html

同步 Action 默认写库、不写导出文件。HTML 报告契约见 ../references/ACTIONS.md「HTML 页面报告」与 DATA_PATHS.md。通用幂等 / 事务 / 空结果保护见 ../references/SCHEMA.md。

---

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

业务技能 SKILL.md / references/ 应明确（Agent 主读，勿只写在本文）：

1. 短查询：共享 Python（PATH 上的 python）跑 CLI；禁止 uv run。
2. 长任务 / RPA / async Action：必须通过宿主 Skill Action（run_skill_action）；禁止 exec + process poll。
3. 单条 vs 批量 action id 与参数（如 url / pickCount）。
4. executionProfile: async → 进度看任务中心 / Skill Run Card；sync → 当场结果。与入口无关。
5. 多入口复用同一业务内核。

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

---

9. Policy

自动检测索引见 POLICY_MATRIX.md：

• POLICY-SKILL-ACTION-001：Runtime 文档存在；schema 含 executionProfile；有 RPA 的业务技能须声明 async agent action。
• POLICY-SKILL-ACTION-002：每个 Action 显式声明 executionProfile（sync/async）。
• POLICY-SKILL-ACTION-003：toolbar Action 必须声明合法 bind.tables。
• POLICY-SKILL-ACTION-004：placements 与 executionProfile 正交（文档/测试不得写死耦合）。
• POLICY-ARCH-CORE-001 / POLICY-DATA-SYNC-001：见矩阵；完整语义多用 sample / code review。

---

10. 与宿主 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 / 任务中心）。

表级 bind.tables 过滤依赖宿主支持；旧宿主忽略绑定时，toolbar Action 可能在技能全部数据表显示——新技能仍须显式绑定，待宿主升级后完整按表过滤生效。