@guandata/guanwf 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guanwf 0.1.7 - 2026-07-08
+
+- 工作流离线开发能力增强，支持文件夹、实例、权限、告警和调度相关命令。
+- 新增工作流依赖分析、执行计划和依赖校验能力，便于把一批作业编排为统一调度主工作流。
+- 数据流保存和合并能力增强，补充子工作流、事件调度和恢复场景支持。
+
 ## @guandata/guanwf 0.1.6 - 2026-06-24
 
 - `install-skill` 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

package/LICENSE

@@ -0,0 +1,133 @@
+Guandata Developer Tools Free Evaluation License
+
+Copyright (c) Hangzhou Guandata Co., Ltd.
+
+This software and its related source code, documentation, examples, packages,
+configuration files, command-line tools, MCP servers, SDKs, plugins, and tool
+integrations are proprietary software of Hangzhou Guandata Co., Ltd. or its
+licensors.
+
+This license applies to Guandata developer tools, including but not limited to
+Guandata CLI, Guandata MCP Server, related npm packages, source code,
+documentation, examples, configuration files, and tool integrations.
+
+1. Free Personal Evaluation Use
+
+Hangzhou Guandata Co., Ltd. grants you a limited, non-exclusive,
+non-transferable, revocable license to use this software free of charge solely
+for personal learning, local testing, technical evaluation, and non-production
+experiments.
+
+This free license does not permit enterprise, commercial, production, internal
+business, team, organizational, hosted, customer-facing, or revenue-generating
+use.
+
+2. Enterprise and Commercial Use
+
+Any use by or for a company, organization, institution, government entity, team,
+client, or other non-individual entity requires a separate commercial license
+from Hangzhou Guandata Co., Ltd.
+
+Enterprise or commercial use includes, but is not limited to:
+
+- use in production, staging, shared, or hosted environments;
+- use for internal business operations or automated business workflows;
+- use by employees, contractors, consultants, service providers, or
+  representatives on behalf of an organization;
+- integration into commercial products, services, platforms, workflows, AI
+  agents, MCP clients, or customer deliverables;
+- connection to, access to, processing of, exposure of, or operation on
+  enterprise data, business systems, customer data, or production data;
+- redistribution, hosting, resale, sublicensing, or provision of this software
+  as part of a paid or unpaid service.
+
+To obtain an enterprise or commercial license, please contact Hangzhou Guandata
+Co., Ltd. through its official sales, support, or business channels.
+
+3. MCP Server and Agent Integration
+
+For Guandata MCP Server or any MCP-compatible tool integration, the free license
+is limited to local personal testing, learning, and non-production evaluation.
+
+The free license does not permit use of the MCP Server in enterprise agent
+platforms, production AI applications, shared team environments,
+customer-facing systems, hosted services, automated business workflows, or
+integrations that access, process, expose, or operate on enterprise data.
+
+Any organizational, commercial, hosted, production, or data-connected use of the
+MCP Server requires a separate commercial license from Hangzhou Guandata Co., Ltd.
+
+4. Restrictions
+
+Unless expressly permitted by this license, reasonably necessary to install and
+use the software as allowed by this license, or expressly permitted by a
+separate written agreement with Hangzhou Guandata Co., Ltd., you may not:
+
+- copy, distribute, sublicense, sell, lease, host, or provide this software to
+  third parties;
+- modify, adapt, translate, create derivative works of, or otherwise alter this
+  software;
+- reverse engineer, decompile, disassemble, or attempt to derive the source
+  code, structure, sequence, organization, or underlying ideas of this software,
+  except to the extent such restriction is prohibited by applicable law;
+- remove or alter copyright, trademark, license, or proprietary notices;
+- use Guandata names, logos, trademarks, product names, or brand assets without
+  permission;
+- use this software in violation of applicable laws, regulations, or third-party
+  rights;
+- circumvent license, access control, usage limitation, telemetry, audit, or
+  security mechanisms, if any.
+
+5. Ownership
+
+Hangzhou Guandata Co., Ltd. and its licensors retain all rights, title, and
+interest in and to this software. No rights are granted except as expressly
+stated in this license.
+
+6. Third-Party Components
+
+Third-party open source components, if any, are licensed under their respective
+licenses. This license applies only to software owned by Hangzhou Guandata Co., Ltd.
+and does not modify any third-party license terms.
+
+7. No Warranty
+
+This software is provided "as is" and "as available", without warranties of any
+kind, whether express, implied, statutory, or otherwise, including but not
+limited to warranties of merchantability, fitness for a particular purpose,
+accuracy, availability, security, and non-infringement.
+
+8. Limitation of Liability
+
+To the maximum extent permitted by applicable law, Hangzhou Guandata Co., Ltd.
+shall not be liable for any indirect, incidental, special, consequential,
+exemplary, or punitive damages, or for any loss of profits, revenue, data,
+goodwill, business opportunity, or business interruption arising from or related
+to this software, even if Hangzhou Guandata Co., Ltd. has been advised of the
+possibility of such damages.
+
+9. Termination
+
+Your rights under this license terminate automatically if you violate any term of
+this license. Upon termination, you must stop using the software and delete all
+copies in your possession or control.
+
+10. Governing Law and Dispute Resolution
+
+This license shall be governed by the laws of the People's Republic of China,
+without regard to its conflict of laws principles.
+
+Any dispute arising from or related to this license or the software shall be
+submitted to the competent court with jurisdiction in Hangzhou, Zhejiang
+Province, China, unless otherwise required by applicable law.
+
+11. Contact
+
+For enterprise licensing, commercial authorization, partnership, procurement, or
+other questions, please contact Hangzhou Guandata Co., Ltd. through its official
+website or official business channels.
+
+12. Language
+
+If this license is provided in multiple languages, the English version controls
+unless Hangzhou Guandata Co., Ltd. expressly states otherwise in writing.

package/LICENSE.zh-CN

@@ -0,0 +1,82 @@
+观远开发者工具免费评估许可协议
+
+版权所有 (c) 杭州观远数据有限公司。
+
+本软件及其相关源代码、文档、示例、软件包、配置文件、命令行工具、MCP Server、SDK、插件和工具集成，属于杭州观远数据有限公司或其授权方的专有软件。
+
+本协议适用于观远开发者工具，包括但不限于观远 CLI、观远 MCP Server、相关 npm 包、源代码、文档、示例、配置文件和工具集成。
+
+1. 免费个人评估使用
+
+杭州观远数据有限公司授予你一项有限的、非独占的、不可转让的、可撤销的许可，允许你免费使用本软件，但仅限于个人学习、本地测试、技术评估和非生产环境实验。
+
+本免费许可不允许企业使用、商业使用、生产环境使用、内部业务使用、团队使用、组织使用、托管使用、面向客户的使用，或任何直接或间接产生商业收益的使用。
+
+2. 企业及商业使用
+
+任何由公司、组织、机构、政府单位、团队、客户或其他非个人主体进行的使用，或代表上述主体进行的使用，均需事先取得杭州观远数据有限公司的单独商业授权。
+
+企业或商业使用包括但不限于：
+
+- 在生产环境、预发布环境、共享环境或托管环境中使用；
+- 用于内部业务运营或自动化业务流程；
+- 由员工、承包商、顾问、服务商或代理人代表组织使用；
+- 集成到商业产品、服务、平台、工作流、AI 智能体、MCP 客户端或客户交付物中；
+- 连接、访问、处理、暴露或操作企业数据、业务系统、客户数据或生产数据；
+- 对本软件进行分发、托管、转售、再许可，或作为任何付费或免费的服务的一部分提供。
+
+如需企业或商业授权，请通过观远官方销售、支持或商务渠道联系杭州观远数据有限公司。
+
+3. MCP Server 与智能体集成
+
+对于观远 MCP Server 或任何兼容 MCP 的工具集成，免费许可仅限于个人本地测试、学习和非生产环境评估。
+
+免费许可不允许将 MCP Server 用于企业级智能体平台、生产环境 AI 应用、团队共享环境、面向客户的系统、托管服务、自动化业务流程，或任何访问、处理、暴露、操作企业数据的集成场景。
+
+任何组织用途、商业用途、托管用途、生产用途，或涉及企业数据连接的 MCP Server 使用，均需取得杭州观远数据有限公司的单独商业授权。
+
+4. 限制
+
+除非本协议明确允许、为按照本协议安装和使用本软件所合理必需，或杭州观远数据有限公司通过单独书面协议明确允许，你不得：
+
+- 复制、分发、再许可、销售、出租、托管本软件，或向第三方提供本软件；
+- 修改、改编、翻译本软件，创作本软件的衍生作品，或以其他方式变更本软件；
+- 对本软件进行反向工程、反编译、反汇编，或试图获取本软件的源代码、结构、顺序、组织方式或底层思想，但适用法律禁止限制的情形除外；
+- 删除或修改版权、商标、许可或专有权利声明；
+- 未经许可使用杭州观远数据有限公司或观远品牌的名称、标识、商标、产品名称或品牌资产；
+- 以违反适用法律法规或第三方权利的方式使用本软件；
+- 绕过任何许可、访问控制、使用限制、遥测、审计或安全机制。
+
+5. 权利归属
+
+本软件的所有权利、所有权和利益均归杭州观远数据有限公司及其授权方所有。除本协议明确授予的权利外，不授予任何其他权利。
+
+6. 第三方组件
+
+本软件中如包含第三方开源组件，该等组件适用其各自的许可协议。本协议仅适用于杭州观远数据有限公司拥有权利的软件部分，并不修改任何第三方许可条款。
+
+7. 无担保
+
+本软件按“现状”和“现有”基础提供，不作任何明示、默示、法定或其他形式的担保，包括但不限于适销性、特定用途适用性、准确性、可用性、安全性和不侵权担保。
+
+8. 责任限制
+
+在适用法律允许的最大范围内，杭州观远数据有限公司不对因本软件引起或与本软件相关的任何间接、附带、特殊、后果性、惩罚性或惩戒性损害承担责任，也不对利润、收入、数据、商誉、商业机会损失或业务中断承担责任，即使杭州观远数据有限公司已被告知可能发生该等损害。
+
+9. 终止
+
+如果你违反本协议的任何条款，你在本协议项下的权利将自动终止。终止后，你必须停止使用本软件，并删除你持有或控制的所有副本。
+
+10. 适用法律与争议解决
+
+本协议适用中华人民共和国法律，但不包括其冲突法规则。
+
+因本协议或本软件引起或与之相关的任何争议，应提交中国浙江省杭州市有管辖权的人民法院解决，除非适用法律另有强制性规定。
+
+11. 联系方式
+
+如需企业授权、商业许可、合作、采购或有其他问题，请通过观远官方网站或官方商务渠道联系杭州观远数据有限公司。
+
+12. 语言
+
+如本协议提供多个语言版本，除非杭州观远数据有限公司另有明确书面说明，以英文版本为准。

package/README.md

@@ -33,6 +33,12 @@ guanwf install-skill
 
 ## 版本更新
 
+### @guandata/guanwf 0.1.7
+
+- 工作流离线开发能力增强，支持文件夹、实例、权限、告警和调度相关命令。
+- 新增工作流依赖分析、执行计划和依赖校验能力，便于把一批作业编排为统一调度主工作流。
+- 数据流保存和合并能力增强，补充子工作流、事件调度和恢复场景支持。
+
 ### @guandata/guanwf 0.1.6
 
 - `install-skill` 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanwf",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "观远工作流数据流编辑工具 - 创建、编辑、导出、预览、保存数据流",
   "bin": {
     "guanwf": "bin/run.js"
@@ -16,6 +16,8 @@
     "binaries/",
     "skills/",
     "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.zh-CN",
     "README.md"
   ],
   "keywords": [
@@ -25,7 +27,7 @@
     "cli",
     "agent-skill"
   ],
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "os": [
     "darwin",
     "linux",

package/skills/guanwf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guanwf
-description: 当用户要创建、编辑、保存工作流引擎中的工作流（含数据流节点、Python 节点、参数赋值等多节点 DAG），或需要预览数据流节点、校验/试运行 Python 脚本、运行工作流，或需要查询工作流/数据流列表和详情时使用。数据流是 BI ETL 的扩展，运行在独立的工作流引擎中。适用于用户说"创建一个数据流""创建一个带 Python 节点的工作流""编辑这个工作流""保存数据流""预览数据流节点""运行工作流""验证这个 Python 脚本能不能跑""列出所有数据流""查看这个工作流的定义"等场景。
+description: 当用户要创建、编辑、保存工作流引擎中的工作流（含数据流节点、Python 节点、子工作流编排、参数赋值等多节点 DAG），或需要预览数据流节点、校验/试运行 Python 脚本、运行工作流、配置定时调度、从失败处恢复续跑，或需要查询工作流/数据流列表和详情时使用。也适用于把一批已有作业工作流按依赖串成统一调度的主工作流（编排）：从血缘自动推导依赖生成编排（deps plan）、对账编排依赖与血缘是否一致（deps verify）、配置 cron 调度上下线（schedule）、失败后增量恢复（run --recover）。数据流是 BI ETL 的扩展，运行在独立的工作流引擎中。适用于用户说"创建一个数据流""创建一个带 Python 节点的工作流""编辑这个工作流""保存数据流""预览数据流节点""运行工作流""验证这个 Python 脚本能不能跑""列出所有数据流""查看这个工作流的定义""把这批作业串起来统一调度""按血缘生成调度依赖""给工作流配个每天凌晨的调度""调度先下线""编排里有作业挂了修好后接着跑"等场景。
 compatibility: "Requires Node.js 14+. Install via npm link (local) or npm install -g @guandata/guanwf (from internal Nexus registry). CLI command: guanwf."
 ---
 
@@ -20,6 +20,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - **数据流 (Dataflow / DATAFLOW)**: 嵌入在工作流中的 ETL 流程，actions 结构与 BI ETL 相同
 - **数据库数据流 (DB_DATAFLOW)**: 数据流的变体，支持 SQL 下推
 - **Python 节点 (SECURE_PYTHON)**: 工作流级 Python 任务，沙箱内运行脚本，可读输入数据集并创建输出数据集
+- **子工作流节点 (SUB_PROCESS + PROCESS)**: 引用另一个已存在的工作流作为节点，用于把一批作业编排成统一调度的主工作流
 - **节点依赖**: 节点间用 `After`（成功后）/ `AfterFailure`（失败后）/ `AfterAny`（完成后）声明执行顺序
 
 ## 关键不变式
@@ -83,8 +84,9 @@ guancli auth status  # 检查连接状态
 ### 0. 先分场景
 
 - `只读查询`: 用 `guancli workflow`，不要创建工作目录。
-- `新建工作流`: `guanwf create --name ... --parent-dir ...`（`--type DATAFLOW/DB_DATAFLOW/PYTHON` 控制初始节点骨架），然后编辑 `workflow.go` 和 `nodes/`。
+- `新建工作流`: `guanwf create --name ... --parent-dir ...`（`--type DATAFLOW/DB_DATAFLOW/PYTHON/ORCHESTRATION` 控制初始骨架），然后编辑 `workflow.go` 和 `nodes/`。
 - `编辑已有工作流`: `guanwf edit <workflowId>` 导入整个工作流（数据流节点 → etl.go，Python 节点 → script.py）。
+- `编排一批作业`: `guanwf create --type ORCHESTRATION` + `guanwf deps plan` 从血缘自动生成依赖，见「编排工作流」一节。
 - `修复失败`: 先定位失败发生在 `export`、`preview`、`save` 还是 `run`，只修最小责任源文件。
 
 ### 1. 缺上下文先查，不要猜
@@ -179,10 +181,12 @@ guanwf run --wait --timeout 600 --dir <workdir>  # 自定义超时
 guanwf run --wait --logs --dir <workdir>         # 完成后输出任务日志
 guanwf run --node "<节点名>" --validate --dir <workdir>             # 校验 Python 脚本（不创建输出数据集）
 guanwf run --node "<节点名>" --draft --wait --logs --dir <workdir>  # 单节点真实运行草稿
+guanwf run --recover --wait --dir <workdir>                         # 从最近失败实例的失败节点续跑
 ```
 
 `--node` 按节点显示名只运行指定节点（TASK_ONLY）；`--draft` 运行 save-draft 的草稿版本；
-`--logs` 输出任务实例日志（失败时自动拉取）。
+`--logs` 输出任务实例日志（失败时自动拉取，失败的子工作流节点自动下钻子实例日志）；
+`--recover` 从失败处续跑（见「失败恢复」一节）。
 
 **`--validate` 是验证 Python 脚本的默认方法**：临时草稿中把 `save_outputN` 替换为只打印
 dtypes/head 的 stub，脚本完整执行但不写输出文件，服务端跳过数据集注册（不创建真实数据集），
@@ -198,6 +202,92 @@ guanwf preview <actionId> --dir <workdir>  # 多个数据流节点时按 action
 `preview` 基于 export 的本地定义直接发起预览，无需先 save。Python 节点没有 preview API，
 校验用 `run --node "<节点名>" --validate`。
 
+## 编排工作流（把一批作业统一调度）
+
+场景：已有一批作业工作流（每个作业产出数据集），要按依赖串成一个主工作流统一调度。
+
+用户可能这样下达任务（自然语言 → 执行路径映射）：
+
+| 用户说 | Agent 执行 |
+|---|---|
+| "把 xslh 开头的这批作业串成一个统一调度，每天凌晨 2 点跑" | create ORCHESTRATION → deps plan --search "xslh" → verify → save → schedule set --cron "0 0 2 * * ?" |
+| "这三个作业 A、B、C 编排起来，A 必须在 B 之前" | deps plan --jobs <idA>,<idB>,<idC> + hints.json 里 before:[{first:A,then:B}] |
+| "作业C 是读昨天的快照，别给它连边" | hints.json 里 cross_batch:[{consumer:C,dataset:<dsId>}] |
+| "统一调度里有个作业挂了，帮我修好后接着跑，成功的别重跑" | 下钻日志定位失败作业 → 回作业目录修复+save → 编排目录 run --recover --wait |
+| "调度先别上线/先停掉" | schedule set ... --offline / schedule disable |
+| "看下现在的调度配置" | schedule info |
+
+**依赖的事实源是平台血缘**（作业定义中的输入/输出数据集），不是文档/Excel 的口头描述。
+用 `deps plan` 从血缘自动推导，用 `deps verify` 对账，人工只补血缘表达不了的提示
+（先后顺序 hint、跨批次 CrossBatch、剔除 exclude）。
+
+```bash
+# 1. 建编排工作区（无初始节点）
+guanwf create --name "统一调度" --type ORCHESTRATION --parent-dir <dirId> --dir <workdir>
+
+# 2. 从血缘自动生成 workflow.go（SubWorkflowNode + After 边，每条边注释依据）
+guanwf deps plan --search "<作业名模式>" --yes --dir <workdir>    # 或 --jobs <id1>,<id2>,...
+guanwf deps plan ... --hints hints.json                           # 人工提示（before/cross_batch/exclude）
+
+# 3. 人工微调后对账（ERROR 必须修复；有 ERROR 时 exit 1）
+guanwf export --dir <workdir>
+guanwf deps verify --dir <workdir>
+
+# 4. 保存并运行
+guanwf save --dir <workdir>
+guanwf run --wait --dir <workdir>
+```
+
+```bash
+# 5. 配置定时调度并上线
+guanwf schedule set --cron "0 0 2 * * ?" --dir <workdir>
+```
+
+规则要点：
+
+- 一个数据集只能有一个产出作业（DUP_PRODUCER 是 ERROR）。
+- A 读 B 的产出则编排中必须有 B→A 路径，否则 verify 报 MISSING_EDGE；
+  刻意读上一批（T-1）产物时在 `Workflow.CrossBatch` 中声明，verify 降级为 INFO。
+- 子作业失败 → 主实例失败，下游不执行；失败日志会自动下钻到子实例定位真实报错。
+- **失败恢复**：修复失败作业并 `guanwf save` 后，在编排目录执行
+  `guanwf run --recover --wait`——自底向上恢复失败的子实例和主实例，
+  已成功节点不重跑（job_a/job_b 成功、job_c 失败时只重跑 job_c）。
+- 修改编排结构改 `workflow.go`（`SubWorkflowNode` / `After` / `CrossBatch`），
+  不要去改被引用作业的内容；作业内容问题回作业自己的工作目录修。
+
+`SubWorkflowNode` DSL、hints.json 结构、verify 全部检查项见 `references/WORKFLOW_DSL.md`
+「编排工作流」一节。
+
+## 定时调度
+
+```bash
+guanwf schedule info --dir <workdir>                      # 查看当前调度
+guanwf schedule set --cron "0 0 2 * * ?" --dir <workdir>  # 创建/更新并上线
+guanwf schedule set --cron "0 0 2 * * ?" --offline --dir <workdir>  # 只保存不上线
+guanwf schedule enable --dir <workdir>                    # 上线
+guanwf schedule disable --dir <workdir>                   # 下线
+```
+
+- crontab 是 Quartz 6/7 段表达式（秒 分 时 日 月 周 [年]），如 `0 30 6 * * ?` 每天 06:30。
+- `set` 可选 `--failure-strategy CONTINUE|END`（默认 CONTINUE）、
+  `--warning NONE|SUCCESS|FAILURE|ALL`（默认 FAILURE）、`--start/--end` 生效区间、
+  `--auto-cancel-queued`（上一批未跑完时自动取消堆积实例）。
+- 已有调度时未指定的参数保留现状；事件调度（EVENT_SCHEDULE）不在本命令范围。
+
+## 失败恢复（run --recover）
+
+```bash
+guanwf run --recover --wait --dir <workdir>
+```
+
+找到最近一次 FAILURE 实例，从失败节点处续跑，已成功节点不重跑。适用于长链路编排中
+个别作业失败：先回失败作业的工作目录修复并 `guanwf save`，再回编排目录 `--recover`。
+
+平台语义（已实测）：失败的子工作流节点会复用原子实例，且子实例持有失败时的旧定义快照。
+`--recover` 已处理这一点——自底向上先恢复失败子实例（`update=true` 吸收最新发布定义），
+再恢复父实例。若编排 DAG 结构已变更（加减节点/改依赖），平台会拒绝恢复，此时直接
+`guanwf run` 重跑整链。
+
 ## save 的工作机制
 
 `save` / `save-draft` 不是简单把本地 JSON 上传。内部流程是：
@@ -235,6 +325,11 @@ guanwf preview <actionId> --dir <workdir>  # 多个数据流节点时按 action
 | 查询运行实例 | GET | `/api/offline-dev/process/instance/{id}/select-by-id?domId=<domId>` |
 | 实例任务列表 | GET | `/api/offline-dev/process/instance/{id}/task-list-by-process-id?domId=<domId>` |
 | 任务日志 | GET | `/api/offline-dev/log/detail?taskInstId=<id>&logType=UI&domId=<domId>` |
+| 实例列表分页 | GET | `/api/offline-dev/instance/list-paging?processDefinitionId=<id>&domId=<domId>` |
+| 恢复/停止实例 | POST | `/api/offline-dev/process/{id}/instance/{instId}/execute` |
+| 子实例定位 | GET | `/api/offline-dev/process/instance/{instId}/task/{taskInstId}/select-sub-process?domId=<domId>` |
+| 调度查询 | GET | `/api/offline-dev/process/{id}/schedule/info?domId=<domId>` |
+| 调度创建/更新 | POST | `/api/offline-dev/process/{id}/schedule/create`、`/schedule/{scheduleId}/update` |
 
 实例/日志查询接口要求 `domId` 参数（工作流详情 `select-by-id` 响应中的 `domId` 字段），
 `guanwf run` 内部自动处理。`list-paging` 请求体的搜索字段是 `searchVal`。

package/skills/guanwf/references/WORKFLOW_DSL.md

@@ -62,6 +62,7 @@ func DefineWorkflow() Workflow {
 | `DataflowNode(id, name, DataflowConfig, deps...)` | SUB_PROCESS（数据流） | `nodes/<id>/etl.go` |
 | `DBDataflowNode(id, name, DataflowConfig, deps...)` | SUB_PROCESS（DB 数据流，SQL 下推） | `nodes/<id>/etl.go` |
 | `PythonNode(id, name, PythonConfig, deps...)` | SECURE_PYTHON | `nodes/<id>/script.py`（+ `python.json` 透传） |
+| `SubWorkflowNode(id, name, SubWorkflowConfig, deps...)` | SUB_PROCESS（子工作流） | 无（引用已存在的工作流 ID） |
 | `RawTask(id, deps...)` | 任意（透传） | `nodes/<id>/task.json` |
 
 - `id`：节点目录名，也是 TaskNode 的 id。同一工作流内唯一，建议用 `python_1`、`dataflow_1`
@@ -69,6 +70,7 @@ func DefineWorkflow() Workflow {
 - `name`：节点显示名。**同一工作流内必须唯一**（后端 preTasks 依赖按名字引用）。
 - `RawTask` 不带 name 参数，名称从 `task.json` 的 `name` 字段读取。用于 DSL 未结构化建模的
   节点类型（PARAMETER_ASSIGNMENT、SHELL、HTTP、SWITCH、旧版 PYTHON 等），除依赖外全部透传。
+- `SubWorkflowNode` 用于编排工作流，见下文「编排工作流」一节。
 
 ### 依赖与执行条件
 
@@ -197,6 +199,137 @@ AI 应根据 dtypes/head 检查输出 schema 是否符合预期，确认后用 `
 试运行失败时，根据日志区分：脚本语法/库缺失问题改 `script.py`；输入输出配置问题改
 `workflow.go`；平台/环境错误（如输出数据集注册失败）须排查环境，不要改本地源文件硬绕。
 
+## 编排工作流（子工作流节点）
+
+把一批已存在的作业工作流（每个作业产出数据集）按依赖串成一个主工作流统一调度。
+每个 `SubWorkflowNode` 引用一个已发布的作业工作流；主工作流运行时按依赖顺序触发
+各作业的子实例，任一作业失败则主实例失败（下游不再执行）。
+
+```go
+func DefineWorkflow() Workflow {
+	// id 直接用被引用的工作流 ID，name 用作业名（同一工作流内唯一）
+	a := SubWorkflowNode("<工作流ID_A>", "作业A", SubWorkflowConfig{WorkflowID: "<工作流ID_A>"})
+	// data-dep: 销售明细 (dsId...)   ← 依赖边注释标明依据
+	b := SubWorkflowNode("<工作流ID_B>", "作业B", SubWorkflowConfig{WorkflowID: "<工作流ID_B>"},
+		After(a))
+
+	return Workflow{
+		Name:  "统一调度主流程",
+		Nodes: []*WfNode{a, b},
+		// 跨批次依赖声明：消费方刻意读生产方上一批（T-1）产物，不加执行顺序边
+		CrossBatch: []CrossBatchDep{
+			{Consumer: "作业B", Dataset: "<dsId>", Reason: "读上月快照"},
+		},
+	}
+}
+```
+
+约束（export 校验）：
+
+- `SubWorkflowConfig.WorkflowID` 必填；同一编排中同一个工作流只能被一个节点引用。
+- 不允许引用编排自身（自引用）；嵌套编排如果形成运行时循环，`deps verify` 报 NESTED_CYCLE。
+- `CrossBatch` 声明按 `Consumer`（节点显示名）+ `Dataset`（dsId）匹配，用于把
+  verify 的 MISSING_EDGE 降级为 INFO——表示"读旧数据"是刻意设计而不是漏了依赖边。
+
+### 依赖从哪里来：血缘，不是口头描述
+
+编排的依赖边应来自平台血缘（作业定义中的输入/输出数据集），用 `deps` 子命令自动推导
+和对账，不要凭文档/Excel 手写依赖：
+
+```bash
+# 1) 从血缘自动生成编排草稿（推荐入口）
+guanwf create --name "统一调度" --type ORCHESTRATION --parent-dir <dirId> --dir <workdir>
+guanwf deps plan --search "<作业名模式>" --yes --dir <workdir>   # 按名字搜索作业
+guanwf deps plan --jobs <id1>,<id2>,... --dir <workdir>          # 或显式指定工作流 ID
+guanwf deps plan ... --hints hints.json                          # 附加人工提示
+guanwf deps plan ... --force                                     # 覆盖已有非骨架 workflow.go
+
+# 2) 人工微调 workflow.go 后对账
+guanwf export --dir <workdir>
+guanwf deps verify --dir <workdir>    # ERROR 必须修复；exit 1 表示有 ERROR
+```
+
+`deps plan` 输出的 `workflow.go` 中每条 `After` 边带注释：`data-dep: <数据集>`（血缘推导）
+或 `hint: <原因>`（人工提示）。数据推不出顺序的作业归入"孤岛"层（无依赖边，仍纳入调度）。
+
+hints.json 结构（全部可选）：
+
+```json
+{
+  "before": [
+    {"first": "作业A", "then": "作业B", "reason": "先清洗后汇总"}
+  ],
+  "cross_batch": [
+    {"consumer": "作业C", "dataset": "<dsId>", "reason": "读上一批快照"}
+  ],
+  "exclude": ["废弃作业X"]
+}
+```
+
+- `before`：加一条控制依赖边（血缘推不出来但业务要求先后）。
+- `cross_batch`：声明跨批次读旧数据，plan 不会为它加边，且生成 `CrossBatch` 声明。
+- `exclude`：从编排中剔除某些作业（按名或 ID）。
+- 作业引用支持显示名或工作流 ID；重名时必须用 ID。
+
+### deps verify 检查项
+
+| 级别 | 代码 | 含义 |
+|---|---|---|
+| ERROR | MISSING_EDGE | A 读 B 的产出但编排中没有 B→A 路径（若刻意读旧数据，声明 CrossBatch） |
+| ERROR | DUP_PRODUCER | 同一数据集被多个作业产出（产权冲突，先收敛产出方） |
+| ERROR | REF_NOT_FOUND | 引用的作业工作流不存在（已删除/ID 错误） |
+| ERROR | SELF_REF / NESTED_CYCLE | 自引用 / 嵌套编排成环 |
+| WARN | NAME_MISMATCH | 节点显示名与线上工作流名不一致（edit 后重命名过） |
+| WARN | PENDING_OUTPUT | 作业输出数据集尚未物化（从未成功运行过），血缘对账不完整 |
+| WARN | UNUSED_CROSS | CrossBatch 声明没有匹配到任何血缘（可能写错 Consumer/Dataset） |
+| INFO | CROSS_BATCH | 已声明的跨批次依赖（对账通过） |
+| INFO | CONTROL_DEP | 依赖边没有血缘支撑（纯控制依赖，确认是否刻意） |
+
+血缘提取覆盖：Python 节点（inputDatasets / outputDatasets）、数据流节点（actions 中的
+INPUT_DATASET / OUTPUT_DATASET / INCREMENT_OUTPUT_DATASET）、嵌套子工作流（递归展开）。
+作业定义拉取结果缓存在 `<workdir>/_deps_cache.json`（10 分钟 TTL），`--refresh` 强制重新拉取。
+
+### 编排的运行与失败语义
+
+- `guanwf run --wait --dir <workdir>` 运行主工作流，按边的顺序触发各作业子实例。
+- 子作业失败 → 主实例失败，其 `After` 下游不执行；已成功的作业产出保留。
+- 失败时 `run` 自动拉日志：失败的 SUB_PROCESS 节点 UI 日志为空，会自动下钻到
+  子实例逐任务打印（含 Python traceback 脚本输出），无需手动定位子实例。
+- **推荐修复方式（增量恢复）**：修好失败作业（在作业自己的工作目录里改、save），
+  回编排目录 `guanwf run --recover --wait`——从失败节点续跑，已成功作业不重跑。
+- 整链重跑：`guanwf run --wait`（已成功作业也会重跑；作业输出是 OVERWRITE 时幂等）。
+- 作业节点的重试/超时用 `SubWorkflowConfig` 所在 TaskNode 的通用字段（edit 回读后在
+  task 层，当前 DSL 不展开；需要精细重试策略时在作业工作流内部配）。
+
+### run --recover 的平台语义
+
+`--recover` 找到最近一次 FAILURE 实例并自底向上恢复：
+
+1. 列出失败节点；对失败的 SUB_PROCESS 节点，经 `select-sub-process` 定位失败子实例。
+2. 递归先恢复子实例（`execute` + `START_FAILURE_TASK_PROCESS` + `update=true`，
+   使子实例吸收作业最新发布定义——否则会用失败时的旧定义快照重跑）。
+3. 子实例成功后恢复父实例，父实例吸收子实例成功状态，只重跑未成功节点（秒级）。
+
+限制：只有 FAILURE 状态的最近实例可恢复；若编排 DAG 结构已变更（加减节点/改依赖），
+平台 `checkProcessChange` 会拒绝，此时直接 `guanwf run` 重跑整链。
+不可与 `--node` / `--draft` / `--validate` 同用。
+
+### 编排的定时调度
+
+```bash
+guanwf schedule info --dir <workdir>
+guanwf schedule set --cron "0 0 2 * * ?" --dir <workdir>            # 创建/更新并上线
+guanwf schedule set --cron "0 0 2 * * ?" --offline --dir <workdir>  # 只保存不上线
+guanwf schedule enable / disable --dir <workdir>
+```
+
+- crontab 为 Quartz 表达式（秒 分 时 日 月 周 [年]），服务端校验合法性。
+- `--failure-strategy CONTINUE|END`：某作业失败后，无依赖关系的其他分支是否继续（默认 CONTINUE）。
+- `--warning NONE|SUCCESS|FAILURE|ALL`：告警时机（默认 FAILURE）。
+- `--auto-cancel-queued`：上一批未跑完时自动取消堆积的排队实例（长链路编排建议开启）。
+- 已有调度时未指定的参数保留现状；只调度主工作流，被编排的作业自身不要再配调度
+  （避免同一作业被两条链路并发触发）。
+
 ## 命令闭环
 
 ### 新建工作流
@@ -206,6 +339,7 @@ guanwf create --name "我的工作流" --parent-dir <工作流目录ID> --dir <w
 # 默认生成数据流节点骨架: workflow.go + nodes/dataflow_1/etl.go
 # --type PYTHON 生成 Python 节点骨架: workflow.go + nodes/python_1/script.py
 # --type DB_DATAFLOW 生成数据库数据流骨架
+# --type ORCHESTRATION 生成编排骨架（无初始节点，配合 deps plan 使用）
 
 # 编辑 workflow.go 和节点源文件后：
 guanwf export --dir <workdir>