skill-orchestrator
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
02 资源文件 47
- 脚本bin/design-batch.mjs8.0 KB
- 参考文档manifest.json506 B
- 参考文档package.json384 B
- 脚本runtime/asset-acceptance.mjs6.7 KB
- 脚本runtime/asset-policy.mjs5.5 KB
- 脚本runtime/asset-store.mjs6.3 KB
- 脚本runtime/attempt-root.mjs2.3 KB
- 脚本runtime/batch-request.mjs3.3 KB
- 脚本runtime/batch-runner.mjs34.8 KB
- 脚本runtime/checkpoint-asset-store.mjs3.9 KB
- 脚本runtime/checkpoint.mjs16.2 KB
- 脚本runtime/delivery-index.mjs16.7 KB
- 脚本runtime/discovery.mjs6.9 KB
- 脚本runtime/fingerprint.mjs2.6 KB
- 脚本runtime/guidance.mjs5.0 KB
- 脚本runtime/matcher.mjs10.3 KB
- 脚本runtime/page-linkage.mjs9.6 KB
- 脚本runtime/publish-structure.mjs27.8 KB
- 脚本runtime/research.mjs6.9 KB
- 脚本runtime/result.mjs630 B
- 脚本runtime/runner.mjs25.3 KB
- 脚本runtime/runtime-root.mjs916 B
- 脚本runtime/standard-bindings.mjs7.4 KB
- 参考文档schemas/batch-checkpoint.schema.json4.8 KB
- 脚本scripts/image-edit-adapter.mjs15.3 KB
- 脚本tests/cli/design-batch.test.mjs11.8 KB
- 参考文档tests/fixtures/cli-batch-request.json1.4 KB
- 脚本tests/integration/batch-resume.test.mjs12.3 KB
- 脚本tests/integration/vertical-chain.test.mjs92.7 KB
- 脚本tests/unit/asset-acceptance.test.mjs11.0 KB
- 脚本tests/unit/asset-policy.test.mjs5.4 KB
- 脚本tests/unit/asset-store.test.mjs10.0 KB
- 脚本tests/unit/attempt-root.test.mjs2.4 KB
- 脚本tests/unit/batch-request.test.mjs5.2 KB
- 脚本tests/unit/batch-runner.test.mjs57.1 KB
- 脚本tests/unit/checkpoint-asset-store.test.mjs8.6 KB
- 脚本tests/unit/checkpoint.test.mjs21.1 KB
- 脚本tests/unit/delivery-index.test.mjs1.9 KB
- 脚本tests/unit/discovery.test.mjs3.9 KB
- 脚本tests/unit/fingerprint.test.mjs2.0 KB
- 脚本tests/unit/guidance.test.mjs3.8 KB
- 脚本tests/unit/image-edit-adapter-lifecycle.test.mjs20.8 KB
- 脚本tests/unit/matcher.test.mjs9.8 KB
- 脚本tests/unit/page-linkage.test.mjs10.2 KB
- 脚本tests/unit/publish-structure.test.mjs46.9 KB
- 脚本tests/unit/research.test.mjs4.2 KB
- 脚本tests/unit/standard-bindings.test.mjs7.5 KB
03 SKILL.md 正文
skill-orchestrator
设计 Skill 编排 package(计划工作线 C)。实现 Skill 发现、Capability 匹配、研究信号装配(C3)、 软建议合并(C4)、页面素材回填(C5)与批量生产编排(3B/3C)。
范围约束:不动态安装、不自动升级、不连网络 registry。provider 凭据来自显式环境变量或当前 Codex Agent 登录态,不落入交付物。
用户引导
用户询问“套件能做什么、怎么用、该选哪个 Skill”时,先介绍其用途:将支付宝活动需求转换为可评审、可交接的受控视觉方案,减少素材生成、适配和页面组装的重复工作。仅咨询时不创建请求、不运行批次、不探测图片服务。
按需求推荐入口:首页用 skill-alipay-home,落地页用 skill-alipay-landing,单独生图用 skill-image-generate,已有图片处理用 OpenPhoto;自动生成并回填素材、多页交付、失败恢复或离线联动用本编排器,单页素材链路也可编排。不要把所有独立任务都强制转为批次。
示例:“设计一个首页和两个活动落地页,主题分别为开学季与演唱会,自动生成并回填素材,提供离线联动预览。”从上下文提取页面类型、主题和数量,可选补充受众、品牌要求、文案与参考图。由 Agent 整理结构化请求,仅询问影响执行的缺项;CLI 不直接解析自然语言。需求明确后沿用执行流程,不重复欢迎或介绍。
执行前区分本地测试图片与真实 provider;真实生图可能产生费用,按当前会话授权执行。交付时提供结果返回的 index.html 实际路径,说明成功、失败、待补素材及配置建议的位置。原型和配置不能直接发布,真实资源、生产路由和上线由业务系统负责。详细步骤见使用指南。命令帮助为 npm run batch -- --help,不创建批次。
规划与询问
本 Skill 自行做与本次生成直接相关的短计划,不调用外部通用 brainstorming Skill。用户已明确页面类型、主题和数量时静默执行;仅当表述不明确、要求彼此冲突,或完成任务必须明显扩展范围时再询问用户。
能力
- 扫描显式传入的 Skill 根目录,读取
SKILL.md/manifest.json,以manifest.json为结构化真相源。 - 复用
design-skill-contracts的 JSON Schema 与最小验证器校验SkillManifest,不复制 Schema、不改合同、不安装依赖。 - 支持注入 executor 做 capability 可用性探测。
- 稳定排序输出:
skills/byCapability/unavailable。 - 根据显式指定、Schema、自动执行、确认点、可选优先级和稳定排序选择 capability provider。
- 批量生产:批次请求加载、checkpoint 持久化、断点恢复、失败重试与标准运行时绑定(见下)。
用法
import { discoverSkills } from './runtime/discovery.mjs'
const result = await discoverSkills({
skillRoots: ['path/to/skill-a', 'path/to/skill-b'],
// executor 可选,签名 async ({ root, manifest }) => boolean
executor: async ({ root, manifest }) => true,
})
// result.skills 可用的 Skill 列表(稳定排序)
// result.byCapability capability ID -> Skill ID 列表
// result.unavailable 不可用 Skill(含原因)
// result.duplicates 重复 Skill ID 记录
import { matchCapability } from './runtime/matcher.mjs'
const match = matchCapability({
discovery: result,
capability: 'image.generate',
request: { requireAutomatic: true },
})
未提供 CapabilityManifest 元数据时 priority 默认为 0;提供时数值越大越优先,
同优先级再按 capability version、Skill ID 和规范化路径稳定排序。
研究信号包(C3)与软建议合并(C4)
import { buildResearchPack } from './runtime/research.mjs'
import { aggregateGuidance } from './runtime/guidance.mjs'
buildResearchPack({ brief, searchBinding, catalog, maxQueries = 3 }) 按 brief.researchPolicy
决定行为:
none→skipped,pack 为null;optional且检索缺失/失败/空结果 →warning,pack 为null;required且检索缺失/失败/空结果 →failed,pack 为null;- 成功:归一化
url/title/snippet,生成queries/sources/signals(visual/color/layout/content) 与adoptedElements(经 catalog 过滤),sourceRefs全部引用sources的 URL, 输出通过ResearchPackSchema 校验。searchBinding由调用方注入,本模块不联网。
aggregateGuidance({ brief, researchPack, catalog, guidanceBindings = [] }) 合并多个
binding({ sourceSkill, sourceSkillVersion, run },run 返回 item 数组)的软建议:
- 按 catalog 的 component id / allowedClasses / allowedVariants 做明确 token 过滤;
- 采纳条目
catalogAccepted=true、rejectionReason=null;拒绝条目记rejectedCount与原因; - binding 失败非阻断,记为 warning;输出通过
DesignGuidanceSchema 校验, 含sourceCommit与rejectedCount。
页面素材回填(C5)
runDesign 对首次页面调用返回的 pendingAssetRequests 执行一次有界回填。可选参数
assetPolicy({ default, rules },见 asset-policy.schema.json)、assetStore
(createAssetStore 返回的缓存)、itemFingerprint(缓存键指纹,缺省用 brief.id)。
未传 assetPolicy 时使用默认策略 { default: { source: 'generate', requirement: 'required' }, rules: [] },
保持既有行为。
原始 brief.inputArtifacts 只作参考图候选:仅当其 assetRequestId 精确匹配待补请求的
id 或 usageSlot 时才注入该请求,未绑定输入不会注入任意槽位,也不参与回填或 reuse。
对每个待补请求按 usageSlot 解析策略决策,处理顺序:
- 命中
assetStore缓存(assetKeyFor派生键,仅含 canonical request + policySource,不含密钥); source=reuse:未找到时不调用 generator/adapter;required记失败、optional记 warning;source=generate:无缓存才调用image.generate,成功后写入缓存;required失败记失败、optional失败记 warning 且继续。
参考图 provider 需通过 binding 的 capabilities 声明 asset.reference-images。未声明时 runner
会清空该请求的 referenceImages、记录 warning,并继续以请求的文字约束生成,不会使全部素材失败。
runner 确保每个 request 仅产生一个回填结果,且同一 artifactId 不会被多个请求重复消费;重试耗尽的
required/optional 请求 ID 会在最终页面调用中通过内部 failedAssets 透传,以便原型明确显示“素材生成失败”;页面 Skill
仍会独立校验该合同。
仅当 allowGenerate=true 时逐项调用 image.generate;仅当生成结果的 width、height、MIME 与
strictSizeSatisfied=true 均严格满足请求时才直接回填,否则仅在 allowEdit=true 时调用由组合根
注入的 imageAdapter。收集严格满足请求尺寸与格式的 AssetResult 后,将其合并到
brief.inputArtifacts 并第二次调用同一页面 capability。已有 inputArtifacts 不会被自动编辑。
适配 provider 采用延迟解析:仅当至少一个 generate 请求实际需要适配时才解析并记录
image.crop/image.resize/image.export capability;全 reuse 场景不要求 adapter/provider 能力,
避免无谓失败。image.generate capability 也仅在真正调用 generator(成功或失败)时记录;
brief input 复用、缓存命中、reuse 缺失均不记录。最终状态仅由 required 的失败或剩余必填请求决定;
optional 失败或剩余可选请求不使整体失败,保留默认素材。若全部待补素材均为 optional 且无任何
可回填素材,则不做第二次页面调用,直接使用首次页面包并标记 succeeded。
适配 provider 先由 discovery 中同时声明 image.crop、image.resize、image.export 的 Skill ID
交集确定,再以 preferredSkillId 审计三项 matcher。适配 binding 使用
{ providerId, run(request, { asset, outputRoot }), close?() } 形式:providerId 必须位于该交集;runner 不依赖
具体图片实现。OpenPhoto 组合根 adapter 使用 canvas.resize、object.transform.set 和
document.renderArtifact 完成真实 cover/contain、PNG/JPEG 输出,并回读 artifact 校验尺寸、MIME 与 SHA-256。
createOpenPhotoAdapterBinding({ openphotoRoot, dataRoot, sourceRoot }) 的 sourceRoot 用于解析
相对 AssetResult.path:传入时必须是生成器产物所属目录;未传入时固定为创建 binding 当时的
process.cwd()。绝对路径不受此参数影响;runner 只依赖通用 binding 接口,不硬编码 OpenPhoto。
若 binding 提供可选 close(),runner 会在本次所有待补素材处理完成后调用它;OpenPhoto 的 dataRoot 是一轮
run 内所有素材共享的 data root,复用同一个 daemon,统一由该 close() 回收,避免逐素材重启和遗留进程。
调用 image.generate 时,runner 会传入 { outputRoot, artifactRoot };artifactRoot 是本轮 outputRoot 下的
generated-assets/ 目录,生成 binding 应将本轮临时源素材写入该目录。
同一页面的独立生图请求以固定并发上限 5 执行;单个素材内部的生成重试仍按请求合同串行。OpenPhoto 适配共享同一浏览器/daemon,因此跨素材适配与缓存/checkpoint 写入保持串行。并发完成后的素材和步骤按原请求顺序合并。批次 item 仍按既有顺序执行,联动首页仍等待关联落地页完成。
每个请求都会记录生成、复用、缓存或适配步骤(details 含 request id 与策略 source/requirement);
单项失败仍继续处理其余请求。至少一个请求成功才会第二次调用页面 Skill;全部失败时保留首次页面包
且只调用一次。仅当所有 required 请求均严格回填、第二次页面调用不再返回 required 待补请求且
没有 required 失败步骤时,编排结果为 succeeded;否则为 failed。
批量生产 CLI(3B/3C)
bin/design-batch.mjs 提供批次生产入口,根目录脚本 npm run batch 等价于
node packages/skill-orchestrator/bin/design-batch.mjs。
# 先计算本次统一名称(只读,不创建文件)
npm run batch -- name --output-root ./output --theme-abbr bg4
# 运行新批次
npm run batch -- run --request ./output/20260904-bg4-v1-request.json --output ./output/20260904-bg4-v1 [--screenshot] [--source-commit X]
# 断点恢复(只重跑 pending/interrupted)
npm run batch -- resume --output ./out [--screenshot] [--source-commit X]
# 重试失败项(只重跑 failed)
npm run batch -- retry-failed --output ./out [--screenshot] [--source-commit X]
--source-commit缺省用git rev-parse HEAD(execFile 无 shell),失败抛SOURCE_COMMIT_UNAVAILABLE。- provider 不接受 key CLI 参数。显式
IMAGE_GENERATE_PROVIDER及IMAGE_API_*/FAL_KEY优先;未显式指定时优先继承当前 Codex Agent 的 provider URL 与登录态,图片模型缺省gpt-image-2;Codex 配置不可用时再回退既有 FAL 环境变量。 - 标准绑定
createStandardBatchRuntime把每个 item 映射到runDesign:页面 binding 按deliverableType用designHome/designLanding,image.generate用generateAsset,imageAdapter用createOpenPhotoAdapterBinding(仅当 OpenPhoto 已发布时注入,全 reuse 不需 adapter), 并将 runner 生成的researchPack透传给页面 planner。
目录与产物
Agent 创建新批次前必须先调用 name,并原样使用返回路径。统一 basename 为 YYYYMMDD-<主题缩写>-vN:日期在最前,主题缩写为 2–20 位英文字母/数字,版本从 v1 起;同日同主题扫描输出目录和 -request.json 后自动递增。请求文件固定为 <basename>-request.json,输出目录固定为 <basename>/。既有产物不自动移动或重命名。
每次批次在 --output 目录下生成两层产物:面向使用者的四层交付发布区(终态自动发布)
与保留给恢复/追溯的批次运行目录。
发布区(run/resume/retry-failed 终态自动重建,幂等;只含成功 item):
out/
├─ index.html # 离线统一入口(蓝金响应式设计模板):列出全部成功页面的
│ # 原型/配置/素材/截图入口
├─ assets/<itemId>/ # 该页面原型实际引用的最终素材(改写后的本地引用)
├─ configs/<itemId>.config.json # home-config.json / landing-config.json 发布副本
└─ other/
├─ <itemId>/ # prototype.html(引用改写)、styles/、配置指南、
│ # brief、manifest、package、component usage、
│ # validation report、prototype.png
├─ <itemId>/<landingKey>/ # 联动批次首页 attempt 内的落地页完整离线预览目录
└─ runtime/ # request.json、checkpoint.json、result.json 运行时追溯
- 发布后原型的素材引用改写为
../../assets/<itemId>/...;styles 保留同目录引用; 首页landingPreviewRef改写为../<landingItemId>/prototype.html,发布层内 首页—落地页离线链接可点击。 - 发布层不复制
generated-assets/与openphoto-data/(生成中间图与 daemon 工作目录); 发布后原型的本地src/href均必须存在,缺失依赖、越界或绝对路径引用按BATCH_PUBLISH_INCOMPLETE/BATCH_PUBLISH_INVALID明确抛出(fail fast)。 - 部分失败批次仍发布已成功页面;发布失败会使
runBatch整体抛错, 不会静默报告批次成功但交付入口损坏。
批次运行目录(attempt 恢复与追溯,不进入交付入口):
out/
├─ request.json # 批次请求(不含 provider secret)
├─ checkpoint.json # 当前检查点(原子写,含 checkpoint.previous.json 备份)
├─ result.json # 最终 BatchResult
└─ items/<itemId>/attempts/<0001>/ # 每次 attempt 独立目录
├─ result.json # 该 attempt 的 OrchestrationResult
└─ generated-assets/ # 生图产物
恢复语义
run:输出已存在(request/checkpoint/result 任一)抛BATCH_OUTPUT_EXISTS;空目录允许。resume:加载 request+checkpoint,assertCompatible(batchId/requestFingerprint/sourceCommit/provider), 把running归一化为interrupted并持久化,只重跑pending/interrupted;succeeded永不重跑。retry-failed:只重跑failed;若存在pending/running/interrupted抛BATCH_RETRY_REQUIRES_RESUME。- 每次状态变更都
touch updatedAt+ 原子写 checkpoint;attempt 目录用nextAttempt递增,已存在拒绝覆盖。 - 最终
checkpoint.status与BatchResult.status同名(succeeded/partially_failed/failed)。
退出码
| 码 | 含义 |
|---|---|
| 0 | 批次 succeeded |
| 2 | 请求/schema/用法(BATCH_REQUEST_*、BATCH_USAGE 等) |
| 3 | provider 配置(MISSING_API_KEY、IMAGE_PROVIDER_*、FAL_*、PROBE_*、OPENPHOTO_RELEASE_MISSING) |
| 4 | 批次 partially_failed/failed(命令正常完成但结果非 succeeded) |
| 5 | checkpoint/不兼容/输出已存在/内部(CHECKPOINT_*、BATCH_OUTPUT_EXISTS、BATCH_STATE_* 等) |
stdout 仅单行 JSON:成功 { ok:true, result },错误 { ok:false, code, message }。
安全与脱敏
- provider 身份只保存
id/model/baseUrlFingerprint(SHA256 规范化 host+path),不存完整 URL/API key/secret。 assetKeyFor只含 canonical request + policySource,不含密钥。request.json本身不含 provider 凭据。
契约
- 批次请求/结果复用
design-skill-contracts的batch-design-request.schema.json与batch-design-result.schema.json;素材策略用asset-policy.schema.json。 - 内部检查点用本 package 的
schemas/batch-checkpoint.schema.json(additionalProperties:false, item/asset 状态机、error 结构、provider 脱敏身份)。
稳定错误
- 目录不存在、缺
manifest.json、manifest.json非法 JSON、SkillManifest校验失败、executor 失败, 均被记录到unavailable或duplicates,整体不崩溃。 - 重复 Skill ID:按规范化路径排序保留第一个,其余记录到
duplicates。
测试
npm test
# 等价于 node --test "tests/**/*.test.mjs"
目录结构
packages/skill-orchestrator/
├─ package.json
├─ SKILL.md
├─ bin/
│ └─ design-batch.mjs # 批量生产 CLI(run/resume/retry-failed)
├─ schemas/
│ └─ batch-checkpoint.schema.json # 内部检查点 Schema
├─ runtime/
│ ├─ discovery.mjs # Skill 发现器
│ ├─ matcher.mjs # Capability 匹配器
│ ├─ research.mjs # 研究信号包装配(C3)
│ ├─ guidance.mjs # 软建议合并(C4)
│ ├─ runner.mjs # 页面素材回填 runner(C5)
│ ├─ asset-policy.mjs # 素材策略解析(usageSlot 匹配)
│ ├─ asset-store.mjs # 素材缓存存储(canonicalize/assetKeyFor)
│ ├─ fingerprint.mjs # 指纹与 provider 身份脱敏
│ ├─ checkpoint.mjs # 检查点创建/校验/原子写/恢复
│ ├─ checkpoint-asset-store.mjs # checkpoint 支撑的素材存储
│ ├─ attempt-root.mjs # attempt 目录与序号管理
│ ├─ batch-request.mjs # 批次请求加载与校验
│ ├─ batch-runner.mjs # 批次执行器(状态机/汇总)
│ ├─ publish-structure.mjs # 四层交付发布层(终态自动发布)
│ └─ standard-bindings.mjs # 标准批次运行时绑定
└─ tests/
├─ unit/
│ ├─ discovery.test.mjs
│ ├─ matcher.test.mjs
│ ├─ research.test.mjs
│ ├─ guidance.test.mjs
│ ├─ asset-policy.test.mjs
│ ├─ asset-store.test.mjs
│ ├─ fingerprint.test.mjs
│ ├─ checkpoint.test.mjs
│ ├─ checkpoint-asset-store.test.mjs
│ ├─ attempt-root.test.mjs
│ ├─ batch-request.test.mjs
│ ├─ batch-runner.test.mjs
│ ├─ publish-structure.test.mjs
│ └─ standard-bindings.test.mjs
├─ integration/
│ ├─ vertical-chain.test.mjs
│ └─ batch-resume.test.mjs
├─ cli/
│ └─ design-batch.test.mjs
└─ fixtures/
├─ cli-batch-request.json
└─ skills/ # 发现器测试 fixture
04 同仓库更多 Skills
mock-image-edit
暂无简介
skill-image-generate
暂无简介
skill-alipay-landing
暂无简介
skill-alipay-home
暂无简介
openphoto
Use for deterministic local image editing with OpenPhoto: inspect an image, crop or transform the canvas or an object, adjust image properties, apply supported filters, run automatic background removal/depth/detection/coordinate segmentation/upscale, and return PNG or JPEG artifacts. Ask the user before downloading a missing AI model.