技能编排

要解决什么问题

当你手里已经有两个以上「读文件、写文件」的 Agent 技能，它们各自在 venv 里跑得好好的，但没人负责接力：A 产出的 Markdown 还要你手动丢给 B 做 docx。更麻烦的是，若用 import 把技能代码焊在一起，依赖冲突和异常栈会互相污染，排障成本很高。

核心思路与能力

本技能把文件当作中间语言，用 subprocess 在进程隔离下按顺序调用子脚本，而不是 import 子技能模块。每条链路结束会写 orchestration_manifest.json，记录各 stage 状态与输出路径，方便追溯。

• 示范链路 scripts/orchestrate_scan2report.py：Stage A 调用 scan-to-word（OCR→docx + Markdown 报告），Stage B 调用 ai-transformation-consultant 的 md2docx，把 *_OCR报告_*.md 接力成精美 Word。这是「两节点线性编排」的完整范例，可照此套到任意技能对。
• DAG 编排 scripts/orchestrate_dag.py：节点数超过 3、或有分支/汇合时，用 JSON 配置节点与 deps，拓扑排序 + 无依赖节点并发（默认 --max-workers 4），失败默认 skip_downstream（已完成产物保留）。
• 四原则：顺序优先于盲目并行；日志带时间戳；上游失败则整体停、仅下游失败不删上游产物；技能间只认约定文件名，互不感知实现。

跨目录部署时，用 SCAN_TO_WORD_SCRIPT、MD2DOCX_SCRIPT 等环境变量指向子脚本绝对路径，避免技能被挪到 ~/.workbuddy/skills/ 后相对路径失效。

适用边界与注意点

• 两节点线性链路优先用 orchestrate_scan2report.py；复杂图用 orchestrate_dag.py。真要条件分支、重状态机再考虑 LangGraph 等框架。
• Stage B 依赖 python-docx，编排脚本须用已装好子技能依赖的 venv 解释器运行；Windows 下 venv 是 Scripts\python.exe，不是 envs\python.exe。
• --join 仅跑下游，适合上游已在别处跑完、本地只做收尾装配；--self-test 可验证编排逻辑而无需完整 OCR 依赖。
• 与 skill-inventory 衔接时：先治理技能资产清单，再把清单里的路径/environment 喂给编排器，避免「连上了但脚本路径仍是旧的」。