Skill Workflow Pack - 工作流Skill工厂
把别人做好的skill零件，组装成你自己的工作流机器，然后把这台机器打包成一个新skill。出了问题能定位是哪个零件的事。
核心流程：选件 → 接线 → 成包 → 排障
触发场景
用户说了类似这些话时激活本skill：
- "我想把XX和YY串起来用" / "帮我把这几个skill组成一个工作流"
- "我想做个skill，把A→B→C的流程包进去"
- "我自己拼了个工作流跑不通" / "哪个环节断了"
- "帮我把这个工作流打包成skill发skillhub/ClawHub"
- "这几个skill接口对不上" / "输出格式和输入格式不匹配"
- "工作流跑到一半挂了，前面的结果还在吗"
- "怎么优化这个工作流" / "有没有更好的搭配"
核心能力
1. 选件：确定要用哪些现成skill
用户有一个工作需求，想用现有skill组合解决。
你要做的：
- 理解用户的最终目标（不是"我要装什么skill"，而是"我想解决什么工作问题"）
- 拆解目标为能力单元（比如"公众号自动发文" = 写文 + 配图 + 插图 + 合规 + 发布）
- 扫描用户已安装的skill（检查skill目录），看哪些能力已经有了
- 对缺失的能力，推荐候选skill（从skillhub或ClawHub搜索，给出名字、用途、为什么选它）
- 输出组合方案，标注：必选/可选/可替代
输出格式：
你的需求：[一句话复述]
拆解为：[能力1] → [能力2] → [能力3] → ...
推荐组合：
① [能力] → skill-name（必选）- 为什么选它
② [能力] → skill-name（必选）- 说明
③ [能力] → skill-name（可选）- 没有也能跑，但少了XX
④ [能力] → skill-A 或 skill-B（二选一）- 区别是...
你已经有的：[已安装且能复用的skill]
还需要装的：[缺失的，去skillhub或ClawHub搜]
确认这个方案？确认后我帮你接线。
原则：
- 先问清楚用户要什么效果，不要一上来就推荐
- 已装的skill优先复用
- 给替代选项时说明区别（性能/价格/稳定性）
- 用户确认后直接进入"接线"环节
2. 接线：定义数据流契约
确定用哪些skill后，最关键的一步：定义清楚每步之间的输入输出接口。
这是90%的"自己拼的工作流跑不通"的根因——每个skill单独能用，但A的输出格式和B期望的输入格式对不上。
data_flow 定义示例：
data_flow:
- from: "ai-article-writer"
to: "mxai-image-gen"
output: "illust_plan.txt（每行: 描述|标记文本）"
input_expected: "图片描述文本"
transform: "逐行读取，取|前面的描述部分作为生图prompt"
- from: "mxai-image-gen"
to: "article-image-inserter"
output: "图片URL列表"
input_expected: "本地图片文件路径"
transform: "需要先下载URL到本地临时目录"
gap_warning: "生图输出URL但插图要本地路径，中间需要下载步骤"
你作为agent要做的：
1. 读每个skill的SKILL.md/README，理解它的输入输出格式
2. 检查相邻两步的接口是否对得上
3. 对不上的，标注 gap_warning 和 transform（怎么转换）
4. gap太大的（一个输出JSON一个期望CSV），建议换skill或加中间步骤
5. 给每个关键skill配 fallback 降级方案
# 兼容性预检
python scripts/diagnose.py --workflow <name> --precheck
降级链（fallback）：
skills:
- name: "mxai-image-gen"
role: "AI生成配图"
fallback:
- name: "dall-e-wrapper"
note: "质量稍差但稳定"
主skill挂了 → 提示用户切fallback继续，不是整个流程等死。
3. 成包：生成一个可分发的新skill
接线完成后，把整个工作流打包成一个标准skill结构，可以直接安装使用，可以发skillhub。
生成的skill目录结构：
my-workflow-skill/
├── SKILL.md # 工作流的使用说明（agent读这个来执行工作流）
├── workflow.yaml # 工作流定义（skills列表+data_flow+pipeline+fallback）
├── scripts/
│ └── run_check.py # 运行前检查脚本（依赖+配置+接口）
└── README.md # 人读的说明（安装、配置、使用示例）
生成的SKILL.md要包含：
- 工作流做什么（一句话）
- 触发方式（用户说什么话时执行）
- 执行步骤（按pipeline顺序，每步调哪个skill、输入什么、输出什么）
- 断点续跑规则（哪步挂了怎么保存现场、怎么从断点继续）
- 降级规则（哪个skill挂了用什么替代）
- 前置配置（需要什么API Key、环境变量）
你作为agent要做的：
1. 基于 examples/my-workflow.template.yaml 生成 workflow.yaml
2. 基于工作流内容生成 SKILL.md（重点是pipeline执行逻辑和data_flow转换规则）
3. 生成 run_check.py（检查依赖和配置是否就绪）
4. 生成 README.md（安装说明+使用示例）
5. 跑一次 validate + --precheck 确认没问题
6. 打包成zip，告诉用户"你的新skill做好了，可以装到skill目录、发skillhub或发ClawHub"
发布渠道：
- skillhub.cn：用其自有zip格式上传
- ClawHub（国内镜像 cn.clawhub-mirror.com）：zip打包后发布，API无需认证
- 搜索skill: GET https://cn.clawhub-mirror.com/api/v1/search?q=关键词&limit=10
- 浏览热门: GET https://cn.clawhub-mirror.com/api/v1/skills?limit=20&sort=downloads
- 查看详情: GET https://cn.clawhub-mirror.com/api/v1/skills/{slug}
- 选件时可以用这些API帮用户搜索可用的组件skill
# 验证工作流格式
python scripts/workflow_manager.py validate --file workflow.yaml
# 兼容性预检
python scripts/diagnose.py --file workflow.yaml --precheck
打包规则（重要）：
- 用显式文件白名单打zip，不用glob
- 绝不打包：accounts.json、tokens、pycache、.env、任何含密钥的文件
- 配置模板里API Key只留 <YOUR_XXX_HERE> 占位符
- zip内带一级目录（skill-name/...）
4. 排障：逐层诊断定位
用户的工作流skill跑挂了，帮他定位是哪个环节的事。
# 全面诊断
python scripts/diagnose.py --workflow <name>
# 带错误日志
python scripts/diagnose.py --workflow <name> --error-log "报错信息"
# 只查某个skill
python scripts/diagnose.py --workflow <name> --skill <skill-name>
# 查看断点续跑信息
python scripts/workflow_manager.py run-state --workflow <name> --resume
诊断分层（逐层排查）：
第一层 - 安装检查：每个组件skill是否都装好了？
第二层 - 依赖检查：系统工具(ffmpeg/tesseract等)是否存在？
第三层 - 配置检查：必填配置项是否都填了？
第四层 - 数据流检查：相邻skill的输入输出格式是否匹配？（最常见的问题）
第五层 - 运行分析：错误日志定位到具体哪步、哪个skill
第六层 - 历史问题：这个工作流之前跑挂过吗？同样的错？
输出格式：
诊断结果：[工作流名称]
━━━━━━━━━━━━━━━━━━
✅ [skill名] - 正常
✅ [skill名] - 正常
❌ [skill名] - [具体问题]
问题定位：
[大白话说清楚哪里错了]
[如果是接口不匹配："A输出的是XX格式，但B期望的是YY格式"]
修复步骤：
1. [可直接执行的命令或操作]
2. [下一步]
降级选项：
- 或者把 skill-A 换成 skill-B
断点续跑：
# 记录步骤完成
python scripts/workflow_manager.py run-state --workflow <name> --step 2 --status completed --output "result.md"
# 记录步骤失败
python scripts/workflow_manager.py run-state --workflow <name> --step 3 --status failed --error "原因"
# 查询从哪继续
python scripts/workflow_manager.py run-state --workflow <name> --resume
# 工作流跑完清理状态
python scripts/workflow_manager.py run-state --workflow <name> --clear
每步完成就记录，挂了告诉用户"第X步断了，前面结果已保存，修完从第X步继续"。
5. 优化建议
python scripts/diagnose.py --workflow <name> --optimize
建议来源优先级：
1. 运行历史：这个工作流之前哪里挂过？挂了几次？
2. 工作流YAML里的 optimization_rules
3. rules/common-rules.yaml 公共规则库
4. agent自己的推理
原则：
- 某个skill反复出问题（挂2次以上），直接建议换掉
- 建议要具体可执行
- 没匹配到就不硬给，说"当前没问题"
示例工作流模板
本skill附带3个示例（workflows/目录），展示完整的data_flow和fallback怎么写：
| 工作流 | 用途 | 看点 |
|---|---|---|
| meeting-automation | 录音→纪要→待办→提醒 | 完整的data_flow + fallback + 断点续跑 |
| pdf-processing-suite | PDF合并/OCR/提取/压缩 | 按需组合（不是每次跑全部） |
| content-publishing | 大纲→正文→SEO→转换 | 每步需用户确认的交互式流程 |
这些是参考模板，展示格式怎么写。用户实际使用时替换成自己有的skill。
平台兼容
同时支持 QoderWork 和 OpenClaw。脚本自动检测环境。工作流YAML格式通用。
文件结构
skill-workflow-pack/
├── SKILL.md ← 你正在读的文件
├── workflows/ # 示例工作流模板
│ ├── meeting-automation.workflow.yaml
│ ├── pdf-processing-suite.workflow.yaml
│ ├── content-publishing.workflow.yaml
│ └── .state/ # 运行状态（自动生成，不打包）
├── scripts/
│ ├── workflow_manager.py # 解析/验证/配置/状态管理
│ └── diagnose.py # 诊断/预检/优化
├── rules/
│ └── common-rules.yaml # 公共优化规则
├── examples/
│ └── my-workflow.template.yaml # 空白模板
└── README.md
注意事项
- 本skill不修改任何组件skill的代码，只做组装、打包和诊断
- 生成的新skill里，工作流执行靠agent按SKILL.md里的pipeline描述串联
- 打包时绝不包含真实密钥，配置只留占位符
- .state/ 是临时运行数据，打包时排除
