@xiaoso/dsh-workflow-lite 0.0.0-stage → 0.1.0

package/lib/types/host/tool/tool.d.ts

@@ -0,0 +1,432 @@
+/**
+ * dsh-workflow-lite — 唯一的模型可见工具 `workflow_lite`。
+ *
+ * **一个工具 + 一个 action 枚举**：枚举本身就是能力清单，模型看枚举就知道这张图能干什么，
+ * 不必先记住一长串工具名再挑；也避开 DSH 内置的 `workflow` 工具（跑 JS 编排脚本）。
+ *
+ * 返回通道只有三条：
+ * - **被规则拒绝** → 一律 `{ error: { code, message, detail? } }`（`code ∈ {not_found, invalid_args,
+ *   blocked, conflict, io_error}`）——它是**返回**而不是抛，好让模型读到结构化失败。
+ * - **`problems` 只在 `compile` 里出现**，装编译级错误。
+ * - **`warnings` 装警告与提示**，每条带 `level`，任何 action 都能带。
+ *
+ * 定位一律用 `id`；`label` 只用于显示。
+ * @module @xiaoso/dsh-workflow-lite/host/tool/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+import type { ExecutionMode, ReusePolicy } from '../../shared/types.ts';
+import { type Action } from '../../shared/types.ts';
+import type { RunService } from '../runs/service.ts';
+import { type Repository } from '../store/repository.ts';
+/** 工具需要的三个活依赖（`dataDir` / `maxResultBytes` 是活配置，所以取函数而不是值）。 */
+export interface ToolDeps {
+    repository: Repository;
+    dataDir: () => string;
+    maxResultBytes: () => number;
+    /** 工作流实例（运行状态）；不给就当没有这块能力（`runs` / `resume` 报错，编译不建实例）。 */
+    runs?: RunService;
+}
+/**
+ * 注册那唯一的工具。
+ * @param ctx - 插件上下文（`tools` 已就绪）。
+ * @param deps - 仓储与两个活配置。
+ * @returns 注销器。
+ */
+/** 工具的参数面（与下方注册处的 `parameters` 同构；抽成具名接口好让单测直接构造）。 */
+export interface WorkflowLiteArgs {
+    action: Action;
+    workflow?: string;
+    node?: string;
+    content?: string;
+    label?: string;
+    output?: string;
+    outputs?: {
+        path: string;
+        rule?: string;
+    }[];
+    description?: string;
+    no_output?: boolean;
+    from_template?: string;
+    to?: string;
+    source?: string;
+    target?: string;
+    when?: string;
+    goal?: string;
+    full?: boolean;
+    output_root?: string;
+    mode?: ExecutionMode;
+    reuse?: ReusePolicy;
+    set_goal?: boolean;
+    handoff?: 'result' | 'none';
+    handoff_note?: string;
+    update?: boolean;
+    run_state?: boolean;
+    instance?: string;
+    all?: boolean;
+    status?: string;
+    note?: string;
+    nodes?: NodePatchArgs[];
+    log?: string;
+    input?: InputArgs;
+    answers?: AnswerArgs[];
+    resource?: ResourceArgs;
+}
+/** write_resource 的 resource（与参数声明同构）。 */
+export interface ResourceArgs {
+    label?: string;
+    description?: string;
+    items?: {
+        kind: string;
+        value: string;
+        note?: string;
+    }[];
+}
+/** write_node 的 input（与参数声明同构）。 */
+export interface InputArgs {
+    question?: string;
+    kind?: string;
+    options?: string[];
+    default?: string;
+    defaults?: string[];
+    placeholder?: string;
+    hint?: string;
+    required?: boolean;
+}
+/** compile 的 answers 里的一项。 */
+export interface AnswerArgs {
+    id: string;
+    value?: string;
+    values?: string[];
+}
+/** `state` 动作里一个步骤的改动（与参数声明同构）。 */
+export interface NodePatchArgs {
+    id: string;
+    status?: string;
+    summary?: string;
+    outputs?: string[];
+    verdict?: string;
+    error?: string;
+    by?: string;
+}
+/** `execute` 真正用到的那一小块执行上下文（完整 `ToolRunContext` 结构上兼容它）。 */
+export interface ToolExecView {
+    agent?: {
+        session?: {
+            header?: {
+                id?: string;
+                cwd?: string;
+                origin?: string;
+                parentSession?: string;
+            };
+        };
+    };
+}
+/**
+ * 工具的处理体。**抽出来是为了可单测**：单测直接调它，不必造一个 Cordis Context。
+ * @param deps - 仓储与两个活配置。
+ * @returns 处理一个调用并回规范 JSON 值（失败也是返回值，不抛）。
+ */
+export declare function createWorkflowLiteHandler(deps: ToolDeps): (args: WorkflowLiteArgs, exec?: ToolExecView) => Promise<JsonValue>;
+/** 工具的参数声明（隐式开放对象根；`required` 内联写）。导出供测试直接编译成 JSON Schema 校验。 */
+export declare const PARAMETERS: {
+    readonly action: {
+        readonly type: "string";
+        readonly enum: readonly ["list", "read", "compile", "create", "write_node", "set_label", "delete_node", "connect", "disconnect", "rename_workflow", "delete_workflow", "save_as_template", "configure", "write_resource", "runs", "resume", "state"];
+        readonly required: true;
+        readonly description: "要做的动作。";
+    };
+    readonly workflow: {
+        readonly type: "string";
+        readonly description: "图名（不带 .json）。除 list 外都需要。";
+    };
+    readonly node: {
+        readonly type: "string";
+        readonly description: "节点 id（read / write_node / set_label / delete_node / save_as_template）。";
+    };
+    readonly content: {
+        readonly type: "string";
+        readonly description: "write_node：节点提示词正文（允许空串，但空正文是编译级）。";
+    };
+    readonly label: {
+        readonly type: "string";
+        readonly description: "write_node / set_label：显示名。不要求唯一；空串 = 清除（回落显示 id）。";
+    };
+    readonly output: {
+        readonly type: "string";
+        readonly description: "write_node：产出契约（相对工作区根的路径）。";
+    };
+    readonly outputs: {
+        readonly type: "array";
+        readonly description: "write_node：一个或多个产出，每个可带生成规则（规则进派发计划的交付契约）。给了它就整份替换 output。";
+        readonly items: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly path: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "相对工作区根的产出路径。";
+                };
+                readonly rule: {
+                    readonly type: "string";
+                    readonly description: "这份产出该怎么写：结构、必须包含什么、长度上限（进资源说明）。";
+                };
+            };
+        };
+    };
+    readonly description: {
+        readonly type: "string";
+        readonly description: "write_node：一句话说明这一步做什么（给人看，不进计划）；空串 = 清除。";
+    };
+    readonly no_output: {
+        readonly type: "boolean";
+        readonly description: "write_node：true ⇒ 显式声明本节点不产出文件（写 output: false）。";
+    };
+    readonly from_template: {
+        readonly type: "string";
+        readonly description: "write_node：从 templates/nodes/<名>.json 取 data 本体（不复制它的 id 与 position）。";
+    };
+    readonly to: {
+        readonly type: "string";
+        readonly description: "rename_workflow：新图名 / save_as_template：节点模板名（缺省 = 步骤 id）。";
+    };
+    readonly source: {
+        readonly type: "string";
+        readonly description: "connect / disconnect：源节点 id。";
+    };
+    readonly target: {
+        readonly type: "string";
+        readonly description: "connect / disconnect：目标节点 id。";
+    };
+    readonly when: {
+        readonly type: "string";
+        readonly description: "connect / disconnect：条件（缺省 = 无条件边）。短判定词（pass / fail）走 VERDICT 约定；也可以写一句自然语言条件，由执行者判断。";
+    };
+    readonly handoff: {
+        readonly type: "string";
+        readonly enum: readonly ["result", "none"];
+        readonly description: "connect（步骤 → 步骤）：result（缺省）把上游这一次的执行结果交给下游 / none 只管先后。边已存在时只改交接。";
+    };
+    readonly handoff_note: {
+        readonly type: "string";
+        readonly description: "connect（步骤 → 步骤）：交接说明——下游拿到执行结果之后怎么用（进派发计划）；空串 = 清除。";
+    };
+    readonly update: {
+        readonly type: "boolean";
+        readonly description: "connect（步骤 → 资源）：true = 在原文件上更新（先读再改，如修完在问题清单里打钩）；false = 整份写出。缺省：资源还没人写就是整份写出，已经有人写就是更新。";
+    };
+    readonly resource: {
+        readonly type: "object";
+        readonly description: "write_resource：资源的内容（给了 node 就是修改那个资源，给了的字段才改；没给 node 就是新建）。";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly label: {
+                readonly type: "string";
+                readonly description: "名字（计划里称呼它）；空串 = 清除。";
+            };
+            readonly description: {
+                readonly type: "string";
+                readonly description: "一句话描述（给人看，不进计划）；空串 = 清除。";
+            };
+            readonly items: {
+                readonly type: "array";
+                readonly description: "全部内容（整份替换），按顺序。";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly enum: readonly ["file", "folder", "url", "skill", "text"];
+                            readonly required: true;
+                            readonly description: "file 文件 / folder 文件夹（value 是路径：绝对路径原样用；相对路径有步骤写它时在产出根目录下，只被读时相对工作区）/ url 网址 / skill（value 是 skill 名）/ text 自定义（value 是用户自己写的一段提示词，原样交给读它的步骤）。";
+                        };
+                        readonly value: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "路径 / 网址 / skill 名 / 正文。";
+                        };
+                        readonly note: {
+                            readonly type: "string";
+                            readonly description: "这一项怎么用。写入的文件写成规格：结构、长度上限；更新的再写明哪些部分就地改写、记录表每次加一行的格式。text 不用。";
+                        };
+                    };
+                };
+            };
+        };
+    };
+    readonly goal: {
+        readonly type: "string";
+        readonly description: "compile：本次目标（用户说了要做成什么时写，进计划的「本次执行」段）。";
+    };
+    readonly full: {
+        readonly type: "boolean";
+        readonly description: "compile：true = 整卷预览（内联正文，不建实例、不写文件）；建图后自检用它。";
+    };
+    readonly output_root: {
+        readonly type: "string";
+        readonly description: "configure：产出根目录（相对工作区或绝对路径），编译时拼在每个产出文件前面；{instance} 换成实例 id。空串 = 清除（默认 .workflow-lite/runs/{instance}/out），. = 工作区根目录。";
+    };
+    readonly run_state: {
+        readonly type: "boolean";
+        readonly description: "configure：记录运行状态。打开后每个工作流实例都带一份运行状态，执行时按计划末尾「运行状态」段用 state 记进度。";
+    };
+    readonly instance: {
+        readonly type: "string";
+        readonly description: "resume / state：实例 id（缺省 = 本会话当前的实例；用户从画布上执行时会给出）。";
+    };
+    readonly status: {
+        readonly type: "string";
+        readonly enum: readonly ["pending", "running", "waiting", "done", "failed", "cancelled"];
+        readonly description: "state：整体状态。";
+    };
+    readonly note: {
+        readonly type: "string";
+        readonly description: "state：整体的一句说明（waiting 写等什么、failed / cancelled 写原因）；空串 = 清掉。";
+    };
+    readonly nodes: {
+        readonly type: "array";
+        readonly description: "state：要改的步骤，每项一个。改 status 时插件自动补轮次、开始 / 结束时间和流水；done 带 summary、outputs，有条件出边的带 verdict（取它出边的条件值）；failed 带 error。";
+        readonly items: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "步骤 id（大小写与图一致）。";
+                };
+                readonly status: {
+                    readonly type: "string";
+                    readonly enum: readonly ["pending", "running", "waiting", "done", "failed", "skipped"];
+                    readonly description: "步骤状态。";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                    readonly description: "一两句结论（200 字以内）；空串 = 清掉。";
+                };
+                readonly outputs: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "这一轮实际写出的文件路径（照计划里给的路径写）。";
+                };
+                readonly verdict: {
+                    readonly type: "string";
+                    readonly description: "判定：它出边的条件值之一（如 pass / fail）。";
+                };
+                readonly error: {
+                    readonly type: "string";
+                    readonly description: "失败原因。";
+                };
+                readonly by: {
+                    readonly type: "string";
+                    readonly description: "谁做的：self / subagent / 队员名。";
+                };
+            };
+        };
+    };
+    readonly log: {
+        readonly type: "string";
+        readonly description: "state：往流水追加一条说明。";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly description: "write_node：给了它就是新建或修改一个输入节点（执行前问用户的问题；问题与回答进计划，占位与说明只给填写的人看）。";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly question: {
+                readonly type: "string";
+                readonly description: "问题（一行）；新建时必填。";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["text", "textarea", "choice", "multi"];
+                readonly description: "text 一句话（缺省）/ textarea 多行 / choice 单选 / multi 多选。";
+            };
+            readonly options: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "选项（choice / multi）。";
+            };
+            readonly default: {
+                readonly type: "string";
+                readonly description: "默认值（文字题的预填文字、单选的一个选项）。";
+            };
+            readonly defaults: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "多选的默认选项。";
+            };
+            readonly placeholder: {
+                readonly type: "string";
+                readonly description: "输入框里的灰字；空串 = 清除。";
+            };
+            readonly hint: {
+                readonly type: "string";
+                readonly description: "填写时显示的说明；空串 = 清除。";
+            };
+            readonly required: {
+                readonly type: "boolean";
+                readonly description: "必填。";
+            };
+        };
+    };
+    readonly answers: {
+        readonly type: "array";
+        readonly description: "compile：用户对输入节点的回答，每项一个；没给的用默认值。用户在画布上点「执行」时已经填过，不用再给。";
+        readonly items: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "输入节点 id。";
+                };
+                readonly value: {
+                    readonly type: "string";
+                    readonly description: "文字题、单选的回答。";
+                };
+                readonly values: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "多选选中的项。";
+                };
+            };
+        };
+    };
+    readonly all: {
+        readonly type: "boolean";
+        readonly description: "runs：true = 列所有会话的实例（缺省只列本会话的）。";
+    };
+    readonly mode: {
+        readonly type: "string";
+        readonly enum: readonly ["auto", "serial", "subagent", "team"];
+        readonly description: "configure：执行方式。auto 由主 agent 决定 / serial 本人串行 / subagent 主 agent 派子代理 / team 主 agent 当 Agent Team 的 Lead。";
+    };
+    readonly reuse: {
+        readonly type: "string";
+        readonly enum: readonly ["auto", "reuse", "fresh"];
+        readonly description: "configure：复用执行者——同一个步骤再次执行（循环下一轮、重试、中断后继续）交给谁。auto 由主 agent 决定 / reuse 交回上次做它的子代理或队员，带着之前的上下文 / fresh 每次新派，上下文干净。serial 时不起作用。";
+    };
+    readonly set_goal: {
+        readonly type: "boolean";
+        readonly description: "configure：设定目标（缺省开）。开着时计划让主 agent 开始前用 create_goal 把这次执行设成会话目标，做完标记完成；长流程不会做一半就停。";
+    };
+};
+/**
+ * 注册那唯一的工具。
+ * @param ctx - 插件上下文（`tools` 已就绪）。
+ * @param deps - 仓储与两个活配置。
+ * @returns 注销器。
+ */
+export declare function registerWorkflowLiteTool(ctx: Context, deps: ToolDeps): () => void;

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * dsh-workflow-lite — host 半。
+ *
+ * 三件事：把**文件仓储**（单文件 JSON、原子写、写前哈希 + 字段级合并）接到活配置上；
+ * 注册**唯一的模型可见工具** `workflow_lite`（14 个 action，没有档位开关）；把**画布 RPC**
+ * 挂到共享 Connection 的 `/api` 通道上（只在有 web 的 profile 里挂，缺它不影响工具可用）。
+ *
+ * 这个插件**不执行任何节点**：它只管理文件、渲染画布、把图编译成一份派发计划，
+ * 拿到计划的模型自己决定怎么执行。插件不调度，就没有并发/超时/重试/锁/心跳/恢复。
+ * 每次执行都是一个工作流实例：图的快照 + 工作区里的实例目录（任务描述、默认产出）。开了「记录运行状态」
+ * 的图还带一份状态：主 agent 经工具的 `state` 动作记进度，用户在画布上看、改，改动通知回模型。
+ *
+ * @module @xiaoso/dsh-workflow-lite
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { CONFIG_KEYS, Config, type WorkflowLiteSettings } from './host/config.ts';
+/** Host 插件名（也是 profile patch 那行的 id）。 */
+export declare const name = "workflow-lite";
+/** 插件的配置声明——Cordis 从入口模块的命名空间上读它。 */
+export { Config };
+/**
+ * 硬依赖只有 `tools`（工具注册是插件的存在理由）。
+ *
+ * `connection` **刻意不在这里**：画布 RPC 走 `ctx.inject(['connection'])` 的子上下文注册，
+ * 这样在没有 web 服务的 profile 里，插件照样只带工具起来，而不是整个 fiber 停在 pending。
+ */
+export declare const inject: string[];
+/**
+ * Host 插件体。
+ * @param ctx - host 插件上下文。
+ * @param config - 解析后的活配置（`Volatile` 引用，写入时就地更新）。
+ */
+export declare function apply(ctx: Context, config: WorkflowLiteSettings): Promise<void>;
+/** 六个配置键（文档与测试用）。`dataDir` 改动需要重启——仓储在装配时定住数据根。 */
+export { CONFIG_KEYS };

package/lib/types/shared/appearance.d.ts

@@ -0,0 +1,49 @@
+/**
+ * dsh-workflow-lite — 步骤卡的图标与颜色：图标库、色板，以及新步骤怎么挑一个不重样的。
+ *
+ * 图标与颜色只是认路的记号，**不进计划**。存在步骤的 `data.icon` / `data.color` 里；没存的老步骤
+ * 按 id 猜（`review`、`review-2` 都是审查的样子，猜不中就是通用的样子）。
+ *
+ * 这里只有名字（host 与 client 都要用：校验、新建步骤时挑一个）；图标的笔画在 `client/ui/stepIcons.ts`。
+ * 纯函数，不碰磁盘、不 import DSH 包。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/appearance
+ */
+import type { NodeData, WorkflowNode } from './types.ts';
+/**
+ * 图标库。顺序就是新步骤挑图标的顺序：先挑通用的那些，内置步骤的六个放在最后
+ * （它们代表固定的意思，空白步骤别一上来就撞上）。
+ */
+export declare const STEP_ICONS: readonly ["idea", "target", "terminal", "bug", "test", "database", "chart", "globe", "chat", "mail", "rocket", "gear", "layers", "book", "checklist", "clipboard", "brush", "image", "translate", "branch", "package", "cloud", "lock", "flag", "sparkle", "scan", "plan", "implement", "review", "fix", "report", "blank"];
+export type StepIcon = (typeof STEP_ICONS)[number];
+/** 色板。顺序就是新步骤挑颜色的顺序；中性的石板灰放最后。 */
+export declare const STEP_COLORS: readonly ["blue", "green", "amber", "coral", "teal", "pink", "olive", "violet", "slate"];
+export type StepColor = (typeof STEP_COLORS)[number];
+export interface Appearance {
+    icon: StepIcon;
+    color: StepColor;
+}
+export declare function isStepIcon(value: unknown): value is StepIcon;
+export declare function isStepColor(value: unknown): value is StepColor;
+/** 按 id 猜样子：`review`、`review-2` 都算审查；猜不中是通用的样子。 */
+export declare function guessAppearance(id: string): Appearance;
+/** 一个步骤卡的样子：存了就用存的，没存（或存的不认识）就按 id 猜。 */
+export declare function appearanceOf(id: string, data: Pick<NodeData, 'icon' | 'color'>): Appearance;
+/**
+ * 给新步骤挑样子：给了的（来自模板 / 内置步骤）照用，缺的那一半挑图里用得最少的——
+ * 尽量不和已有的步骤重样。
+ */
+export declare function pickAppearance(nodes: readonly WorkflowNode[], preferred?: Pick<NodeData, 'icon' | 'color'>, 
+/** 新步骤的 id：是内置步骤的名字（`review`、`review-2`）就照内置步骤的样子。 */
+id?: string): Appearance;
+/**
+ * 给新的「我的步骤」挑样子：避开内置步骤和已有的我的步骤用过的——步骤库里一眼扫过去尽量不重样。
+ * 没存样子的老模板在库里显示的是书签，不算占用。
+ */
+export declare function pickTemplateAppearance(templates: readonly {
+    name: string;
+    icon?: string;
+    color?: string;
+}[]): Appearance;
+/** 内置步骤的样子（步骤库、示例流程用）。 */
+export declare function presetAppearance(id: string): Appearance;

package/lib/types/shared/compile.d.ts

@@ -0,0 +1,71 @@
+/**
+ * dsh-workflow-lite — 派发计划编译器（产品核心）。
+ *
+ * **纯函数**：不碰磁盘、不看时钟、不用随机数——同一份 `PlanFacts` + 同一份 `GraphAnalysis`
+ * + 同一份可选入参 ⇒ **逐字节相同**的输出。物化载荷是 I/O，不在这里。
+ *
+ * 只有一份段结构，两个视图共用：
+ * - **派发版** {@link buildPlan}：② 段的「任务描述路径」给出绝对路径，**正文一个字都不进计划**。
+ * - **整卷版** {@link buildFullText}：同一份段结构，把路径引用换成**逐节点内联正文**。
+ *
+ * 派发版里路径指向的那些文件由 {@link buildTaskTexts} 给出正文：提示词原文，末尾附上这一步读写的资源。
+ *
+ * 段序**稳定在前、易变在后**：①②③④⑥ 只依赖图 JSON 与路径映射，⑤ 每次都变。
+ *
+ * 全篇的序一律是 `id` 的**码位序**（{@link byId}）：清单表行序、批次内序、前置列、补注序。
+ * 计划里的节点引用：② 段清单表**首列**写 `label（id）`（{@link displayName}），
+ * 其余位置一律写 `id`——`id` 唯一，且与载荷文件名一致。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/compile
+ */
+import { type GraphAnalysis } from './graph.ts';
+import type { PlanFacts, PlanId, PlanResult, ValidationProblem, WorkflowDocument } from './types.ts';
+/**
+ * 「运行状态」段（工作流开了「记录运行状态」时才有）：用 `state` 动作记进度、谁记、什么时候记、
+ * 怎么接着跑。字段全表与例子在 skill `workflow-run-state`，这里只放执行时离不开的规矩。
+ */
+export declare function runStateLines(section: RunStateSection): string[];
+/**
+ * {@link buildPlan} / {@link buildFullText} 的**可选**入参（必填签名不变）。
+ *
+ * ⑥ 段「图的注意事项」逐字取自校验结论（`shared/validate.ts`），所以警告与提示必须由调用方带进来；
+ * 这里收**该图的全部** `ValidationProblem`——`warning` / `hint` 进 ⑥ 段，
+ * `compile` 级与内部判定合并后决定"是否拒绝出计划"（`plan` 为空串）。
+ */
+export interface PlanOptions {
+    /** 该图本次校验出的全部问题。 */
+    problems?: readonly ValidationProblem[];
+    /** 这次执行要记运行状态：计划末尾追加「运行状态」段（见 {@link runStateLines}）。 */
+    runState?: RunStateSection;
+}
+/** 「运行状态」段要的东西（host 建好实例后给；预览时实例 id 是 `{instance}`）。 */
+export interface RunStateSection {
+    /** 实例 id：模型调用 `state` / `resume` 时带上它。 */
+    instance: string;
+}
+/**
+ * 派发版：图 + 入参 → 派发计划文本。**纯函数，不碰磁盘。**
+ *
+ * 有**编译级**问题时返回 `plan: ''`（绝不返回一份残缺计划），`problems` 里是：
+ * 内部判定的 `no_nodes` / `prompt_empty`，加上 `options.problems` 里编译级的那些。
+ */
+export declare function buildPlan(facts: PlanFacts, analysis: GraphAnalysis, options?: PlanOptions): PlanResult;
+/**
+ * 整卷版：**同一份段结构**，但把"路径引用"换成"内联正文"（给人和存档）。
+ *
+ * ② 段清单表不再有「任务描述路径」列（路径是本机私有的、带不走），
+ * 段尾追加 `### 节点正文`，逐节点内联 `data.prompt` 原文。
+ * 有编译级问题时返回空串（与派发版的失败姿态一致——不替它编内容、也不给空正文放行）。
+ */
+export declare function buildFullText(facts: PlanFacts, analysis: GraphAnalysis, options?: PlanOptions): string;
+/**
+ * 各步骤的任务描述（`id` → 正文）：提示词原文，末尾附上这一步读写的资源（路径已拼好、说明原样）、
+ * 写文件的规矩和判定行要求。执行者只读这一份就知道写哪、怎么写，不靠编排者转述——
+ * 转述几轮之后，同一份文件每轮的写法都不一样。没什么可附的步骤就是提示词原文。
+ */
+export declare function buildTaskTexts(facts: PlanFacts, analysis: GraphAnalysis): Map<string, string>;
+/**
+ * 内容寻址：`planId` = **图内容哈希**前 8 位（canonical writer 的字节 ⇒ 同内容必得同 `planId`
+ * ⇒ 同目录幂等覆盖；异内容换目录，先前发出的计划不会被打穿）。
+ */
+export declare function planIdOf(document: WorkflowDocument): PlanId;

package/lib/types/shared/graph.d.ts

@@ -0,0 +1,54 @@
+/**
+ * dsh-workflow-lite — 图的语义分析：环、回边、执行批次、出边形态。
+ *
+ * 允许成环之后，编译器最要紧的四件事都在这里一次算清：
+ * - **环 = 强连通分量**（SCC）。一个 SCC 就是一个循环体。
+ * - **回边**＝在 SCC 内做一次 DFS，**指向当前 DFS 栈上祖先**的那条边（自环也算）。
+ *   起点取该 SCC 的**入口节点**——被环外入边指向的那个；没有环外入边时按语义挑最像起点的
+ *   （第一轮就跑得起来、是被条件线跳回来的），并列再取 `id` 最小者（见 `loopStart`）。
+ *   一个 SCC **至少**有一条回边；简单环恰好一条，多环交叠的 SCC 可以有多条。
+ * - **回边不计入汇合与批次推导**（它不是"要等它"，而是"再触发一次"）。前向边照常计入前置。
+ * - **执行批次**＝在"去掉回边之后的 DAG"上做最长路径分层。
+ *
+ * 全篇的序一律是 **`id` 的码位序**（不是 `localeCompare`，也不是文件里的数组序）。
+ *
+ * 纯函数，不碰磁盘、不 import DSH 包。
+ * @module @xiaoso/dsh-workflow-lite/shared/graph
+ */
+import type { CycleGroup, EdgeShape, ExecutionBatch, WorkflowDocument, WorkflowEdge } from './types.ts';
+/** 按**码位序**比较两个字符串（`localeCompare` 会随 locale 变，不能用）。 */
+export declare function compareByCodepoint(a: string, b: string): number;
+/** 排序助手：按 `id` 码位序升序。 */
+export declare function byId(a: string, b: string): number;
+export interface GraphAnalysis {
+    /** 全部**步骤** id，按 `id` 码位序（文件节点不在其中）。 */
+    nodeIds: string[];
+    /** 边 id → 边。 */
+    edgesById: Map<string, WorkflowEdge>;
+    /** 节点 id → 出边形态。 */
+    shapes: Map<string, EdgeShape>;
+    /** 回边 id 集合。 */
+    backEdges: Set<string>;
+    /** 循环体（SCC）列表，按入口 id 码位序。 */
+    cycles: CycleGroup[];
+    /** 执行批次，按批次序。 */
+    batches: ExecutionBatch[];
+    /** 节点 id → 前置 id（**含回边**），按 `id` 码位序。 */
+    predecessors: Map<string, string[]>;
+    /** 节点 id → 后继 id，按 `id` 码位序。 */
+    successors: Map<string, string[]>;
+    /** 图内是否有边指向不存在的节点（悬空 edge ⇒ 保存级）。 */
+    danglingEdges: WorkflowEdge[];
+}
+/** 判形态：单条 = 顺序；全无条件 = 并行扇出；全有条件 = 状态分支；混用 = 歧义。 */
+export declare function classifyShape(outgoing: readonly WorkflowEdge[]): EdgeShape;
+/** 一条边的条件值；缺省与空串都当"无条件"。 */
+export declare function edgeWhen(edge: WorkflowEdge): string | undefined;
+/**
+ * 分析整张图。对**悬空 edge**（端点不存在）不抛错——它由校验层判保存级，
+ * 这里把这类边收进 `danglingEdges` 并从拓扑计算里排除，好让上层能同时报出
+ * "图坏了"与"坏在哪"，而不是在分析阶段就崩掉。
+ */
+export declare function analyzeGraph(document: WorkflowDocument): GraphAnalysis;
+/** 一个循环体是否**没有出口**（环上没有任何指向环外的条件边）——警告级。 */
+export declare function cycleHasNoExit(cycle: CycleGroup): boolean;