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

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

@@ -0,0 +1,29 @@
+/**
+ * dsh-workflow-lite — 两版图之间改了什么。
+ *
+ * 实例视图里改图时，底部的「已改 x 处」按它数；保存时插件按它写给模型的通知。
+ * 按对象比：步骤、资源、输入按 id；连线先按 id，对不上再按两端认（改条件会换 id）。
+ * 挪卡片合成一处「布局」：不进计划，也不用告诉模型。
+ *
+ * 纯函数，不碰磁盘。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/graphDiff
+ */
+import type { WorkflowDocument } from './types.ts';
+export type ChangeObject = 'step' | 'resource' | 'input' | 'edge' | 'layout';
+export interface GraphChange {
+    object: ChangeObject;
+    kind: 'added' | 'removed' | 'changed';
+    /** 节点 id 或连线 id（删掉的是原来的 id，其余是现在的）；布局是空串。 */
+    id: string;
+    /** 改了的连线原来的 id（改条件会换 id）。 */
+    was?: string;
+    /** 改了哪些字段（`changed` 才有）；布局是挪动了的节点 id。 */
+    fields: string[];
+}
+/** 这处改动会不会让计划变样（要不要告诉模型）。 */
+export declare function affectsPlan(change: GraphChange): boolean;
+/** `base` → `next` 改了什么：节点按图里的顺序在前（删掉的排在最前），连线其次，布局最后。 */
+export declare function graphChanges(base: WorkflowDocument, next: WorkflowDocument): GraphChange[];
+/** 一处改动写成一行（不带前面的「- 」），比如「步骤 review（审查）：改了提示词、名称」。 */
+export declare function describeGraphChange(change: GraphChange, base: WorkflowDocument, next: WorkflowDocument): string;

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

@@ -0,0 +1,46 @@
+/**
+ * dsh-workflow-lite — 输入节点：执行前问用户的问题，与用户的回答。
+ *
+ * 一个输入节点 = 一个问题。连到哪些步骤（输入 → 步骤），回答就交给哪些步骤；一条都没连 = 交给整个工作流。
+ * 用户点「执行」时按画布上从上到下、从左到右的顺序把问题摆出来填；编译时问题与回答进计划，
+ * 占位与说明只给填写的人看。
+ *
+ * 编译器、校验、画布、工具、实例都从这里取解释。纯函数，不碰磁盘、不 import DSH 包。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/inputs
+ */
+import type { InputAnswer, InputData, InputKind, InputNode, WorkflowDocument } from './types.ts';
+/** 交互方式（缺省 = 单行文字）。 */
+export declare function inputKind(data: InputData): InputKind;
+/** 要从选项里选的两种。 */
+export declare function isChoiceKind(kind: InputKind): boolean;
+/** 图里的输入节点，按画布上的阅读顺序：从上到下、同一行从左到右，再按 id。 */
+export declare function orderedInputs(document: WorkflowDocument): InputNode[];
+/** 回答交给哪些步骤（按 id 码位序）；空 = 交给整个工作流。 */
+export declare function inputReaders(document: WorkflowDocument, inputId: string): string[];
+/** 一个步骤用到的输入节点（按阅读顺序）。 */
+export declare function stepInputs(document: WorkflowDocument, stepId: string): InputNode[];
+/**
+ * 一份回答按题型取形（见 `readAnswer`）。单选 / 多选只留选项里有的那些；文字题原样。
+ * @returns 没有有效回答时 `undefined`。
+ */
+export declare function normalizeAnswer(data: InputData, raw: unknown): InputAnswer | undefined;
+/** 实际用的回答：用户给的；没给就用默认值（默认值同样按题型取形）。 */
+export declare function effectiveAnswer(input: InputNode, answers: Readonly<Record<string, InputAnswer>>): InputAnswer | undefined;
+export interface AnswerCheck {
+    /** 规范化后的回答（输入 id → 回答；已经补上默认值，没回答的不在里面）。 */
+    answers: Record<string, InputAnswer>;
+    /** 填得不对的：选了不在选项里的、对不上任何输入节点的。 */
+    errors: string[];
+    /** 必填却还空着的输入节点。 */
+    missing: InputNode[];
+}
+/**
+ * 核对一份回答（来自「执行」对话框或工具的 `answers`）：补上默认值、挑出填错的与漏填的。
+ * @param raw - 输入 id → 回答；不是对象当没回答。
+ */
+export declare function checkAnswers(document: WorkflowDocument, raw: unknown): AnswerCheck;
+/** 两份回答是否相同（实例复用时比）。 */
+export declare function sameAnswers(a: Readonly<Record<string, InputAnswer>>, b: Readonly<Record<string, InputAnswer>>): boolean;
+/** 一个问题的写法提示（给模型问用户时看）：「单选：A / B，默认 A」这类。 */
+export declare function describeInput(data: InputData): string;

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

@@ -0,0 +1,77 @@
+/**
+ * dsh-workflow-lite — 字面约束与默认值。
+ *
+ * 这里放**格式契约里写死的字面量**（字符集、长度上限、键序之外的那些数）。
+ * 随部署变化的取值**不在这里**——那些一律是 Config 字段（见 `shared/config.ts`）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/limits
+ */
+/** 工具名（唯一工具）。 */
+export declare const TOOL_NAME = "workflow_lite";
+/** 派发目录名。写死、不做配置键；启动时**不**创建，编译时才建。 */
+export declare const DISPATCH_DIR = ".dispatch";
+/** 图目录名（`dataDir` 下的固定子目录）。 */
+export declare const WORKFLOWS_DIR = "workflows";
+/** 模板目录名。 */
+export declare const TEMPLATES_DIR = "templates";
+/** 工作流版本目录名：`versions/<图名>/<序号>.json`（不在 `workflows/` 下——那里的子目录算旧结构）。 */
+export declare const VERSIONS_DIR = "versions";
+/** 一个工作流最多留几个版本（到了就先删掉旧的再存）。 */
+export declare const MAX_VERSIONS = 100;
+/** 版本说明的长度上限（码点）。 */
+export declare const MAX_VERSION_NOTE_CODEPOINTS = 500;
+/** 自动布局 / 归一化后的坐标小数位。 */
+export declare const COORD_DECIMALS = 2;
+/** 名字长度上限（码点）。适用于图名 / 模板名 / `node.id`。 */
+export declare const MAX_NAME_CODEPOINTS = 64;
+/**
+ * `when` 值长度上限（码点）。
+ *
+ * 这是软编排：条件可以是一句、一段自然语言（"测试全绿且没有新增警告"），由执行者自己判断。
+ * 上限只防病态输入。
+ */
+export declare const MAX_WHEN_CODEPOINTS = 2000;
+/**
+ * 判定词（走 `VERDICT: <值>` 约定的那种）的长度上限。短标识（pass / fail / retry）是判定词，
+ * 其余的是自然语言条件——编译器对两者的写法不同，见 `isVerdictWhen`。
+ */
+export declare const MAX_VERDICT_CODEPOINTS = 32;
+/** 一个节点的描述 / 一条产出规则的长度上限（码点）——同样只防病态输入。 */
+export declare const MAX_TEXT_CODEPOINTS = 2000;
+/** 工作流设置里「产出根目录」的长度上限（码点）。 */
+export declare const MAX_ROOT_CODEPOINTS = 1024;
+/** `label` 长度上限（码点）——只防病态输入，不参与任何判定。 */
+export declare const MAX_LABEL_CODEPOINTS = 200;
+/** 一个资源最多放几项。 */
+export declare const MAX_RESOURCE_ITEMS = 50;
+/** 资源里一条路径 / 网址的长度上限（码点）。 */
+export declare const MAX_VALUE_CODEPOINTS = 2048;
+/** 资源里一段自定义提示词的长度上限（码点）——它本身就是一段提示词，给得宽一些。 */
+export declare const MAX_RESOURCE_TEXT_CODEPOINTS = 20000;
+/** 一个选择题最多几个选项（再多就不是执行前顺手点一下的事了）。 */
+export declare const MAX_OPTIONS = 30;
+/**
+ * Windows 文件名非法字符。`node.id` / 图名 / 模板名共用这一套（它们都要落成文件名）。
+ * 注意：`|` 也在这里——它同时会打断计划里的 markdown 表格，`label` 另有单列规则。
+ */
+export declare const ILLEGAL_NAME_CHARS: RegExp;
+/** 控制字符（含 DEL）。**这里就是要匹配它们**——它们是名字里必须被拒的字符类。 */
+export declare const CONTROL_CHARS: RegExp;
+/** Windows 保留名（**大小写不敏感**）；带扩展名的形式也算，如 `con.json`。 */
+export declare const WINDOWS_RESERVED: Set<string>;
+/** 原子写的临时文件前缀——以 `.` 开头，一切扫描天然忽略。 */
+export declare const TMP_PREFIX = ".tmp-";
+/** 预置的分支判定值（自由文本 `when` 也允许，只是无法推断穷尽性）。 */
+export declare const WELL_KNOWN_WHEN: readonly ["pass", "fail"];
+/** `VERDICT` 约定的固定形态：`VERDICT: <值>`（顶格、大写、半角冒号 + 一个空格）。 */
+export declare const VERDICT_PREFIX = "VERDICT: ";
+/** 派发计划的段标记（字节稳定的前缀契约）。 */
+export declare const PLAN_SECTIONS: {
+    readonly protocol: "## 你拿到的是什么";
+    readonly facts: "## 图的事实";
+    readonly discipline: "## 分发纪律";
+    readonly contract: "## 交付契约";
+    readonly dynamic: "## 本次执行";
+    readonly notes: "## 图的注意事项";
+    readonly runState: "## 运行状态";
+};

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

@@ -0,0 +1,122 @@
+/**
+ * dsh-workflow-lite — 图 JSON 的读入规范化与 canonical 写出。
+ *
+ * 两条硬规则都在这里兑现：
+ * 1. **白名单写出**：只写契约里的键，React Flow 的运行时字段（`measured` /
+ *    `selected` / `dragging` / `width` / `height` / `computedPosition` …）与一切
+ *    未知字段**一律丢弃**并报警告——它们每次渲染都在变，持久化就是永不停止的假 diff。
+ * 2. **canonical writer**：2 空格缩进 / LF / 末尾恰好一个换行 / 固定键序 / 坐标归一化 /
+ *    数组顺序永不重排。往返测试与"同图两次编译逐字节相同"的期望值都来自它。
+ *
+ * 纯函数，不碰磁盘、不 import DSH 包。
+ * @module @xiaoso/dsh-workflow-lite/shared/model
+ */
+import { type EdgeData, type Handoff, type InputAnswer, type InputData, type InputNode, type NodeData, type OutputSpec, type ResourceData, type ResourceItem, type ResourceNode, type StepNode, type ValidationProblem, type WorkflowDocument, type WorkflowEdge, type WorkflowNode, type WorkflowSettings } from './types.ts';
+/** 坐标归一化：`round(v * 100) / 100`（2 位小数）。 */
+export declare function normalizeCoord(value: number): number;
+/**
+ * 大小写不敏感的 id 键——图内唯一性按它判定（`Scan` 与 `scan` 是同一个身份，
+ * 因为它们会撞同一个载荷文件名）。
+ */
+export declare function idKey(id: string): string;
+/** 边 id 的构造式：`<source>-><target>`，带 `when` 时追加 `#<when>`。构造上天然唯一。 */
+export declare function makeEdgeId(source: string, target: string, when?: string): string;
+/** 一个节点在计划里的规范标识：`label（id）`，`label` 缺省时只写 `id`。 */
+export declare function displayName(id: string, label?: string): string;
+export interface ParseOutcome {
+    /** 结构可用时是规范化后的文档；保存级破损时是 `null`。 */
+    document: WorkflowDocument | null;
+    problems: ValidationProblem[];
+}
+/**
+ * 从原始对象里挑出 `data` 的已知键（图里的节点与节点模板共用这一份）。
+ * 产出数组里认不出的元素（不是对象、没有字符串 `path`）直接略过。
+ */
+export declare function readNodeData(raw: unknown): NodeData;
+/**
+ * 产出的规范写法：空数组 = 未声明；只有一个产出且没有规则 = 写成字符串（老写法，文件保持不变）；
+ * 规则是空白的当没写。其余原样（数组顺序永不重排）。
+ */
+export declare function canonicalOutput(output: NodeData['output']): NodeData['output'];
+/** 把任意写法的产出摊成一张清单（`false` 与未声明都是空清单）。 */
+export declare function outputSpecs(output: NodeData['output']): OutputSpec[];
+/** 两份 `data` 内容是否相同（产出按规范写法比，数组逐项比）。 */
+export declare function sameNodeData(a: NodeData, b: NodeData): boolean;
+/** 深拷一份输入节点的 `data`（选项与多选默认值不和原件共用）。 */
+export declare function cloneInputData(data: InputData): InputData;
+/** 深拷一份 `data`（产出数组不和原件共用）。 */
+export declare function cloneNodeData(data: NodeData): NodeData;
+/**
+ * 从原始对象里挑出工作流设置的已知键。根目录存规范化后的写法；认不出的执行方式、复用方式当缺省（`auto`）。
+ * 全是缺省值时返回 `undefined`（文件里不写这个键）。
+ */
+export declare function readSettings(raw: unknown): WorkflowSettings | undefined;
+/** 冲突清单里代表「工作流设置」的那一项（设置没有 id，用这个固定键）。 */
+export declare const SETTINGS_CONFLICT_ID = "settings";
+/** 两份设置是否相同（缺省与缺省相等）。 */
+export declare function sameSettings(a: WorkflowSettings | undefined, b: WorkflowSettings | undefined): boolean;
+/** 交接：`false` 原样；对象只认字符串 `note`（空白说明 = 缺省）；其余值当没写（= 交执行结果）。 */
+export declare function readHandoff(raw: unknown): Handoff | false | undefined;
+/** 交接的规范写法：空白说明 = 缺省（交执行结果、不附说明）。 */
+export declare function canonicalHandoff(handoff: Handoff | false | undefined): Handoff | false | undefined;
+/** 两份交接是否相同（按规范写法比；缺省与缺省相等）。 */
+export declare function sameHandoff(a: Handoff | false | undefined, b: Handoff | false | undefined): boolean;
+/** 两条边的 `data` 内容是否相同（条件、标签、交接、写入方式）。 */
+export declare function sameEdgeData(a: EdgeData | undefined, b: EdgeData | undefined): boolean;
+export declare function isStep(node: WorkflowNode): node is StepNode;
+export declare function isInput(node: WorkflowNode): node is InputNode;
+export declare function isResource(node: WorkflowNode): node is ResourceNode;
+/**
+ * 资源节点 `data` 的已知键：名字与描述空白就当没写；内容里认不出的项（不是对象、种类不认识、
+ * 没有字符串 `value`）直接略过；自定义不带 `note`。
+ */
+export declare function readResourceData(raw: unknown): ResourceData;
+/** 资源节点 `data` 的规范写法（读入的规范化 + 固定键序），写盘与比较都用它。 */
+export declare function canonicalResource(data: ResourceData): ResourceData;
+/** 深拷一份资源节点的 `data`（内容数组与每一项都不和原件共用）。 */
+export declare function cloneResourceData(data: ResourceData): ResourceData;
+/**
+ * 输入节点 `data` 的已知键，顺手规范化：选项去空、去重；不认识的交互方式当单行文字；
+ * 默认值按交互方式取形（文字题 / 单选是一段文字，多选是若干选项）。没有字符串 `question` 时给空串（编译级）。
+ */
+export declare function readInputData(raw: unknown): InputData;
+/**
+ * 一份回答按交互方式取形：文字题与单选是一段文字（空白 = 没回答），多选是去空、去重后的若干项
+ * （一项都没有 = 没回答）。形状对不上（比如多选给了一段文字）时也尽量接住。
+ */
+export declare function readAnswer(kind: InputData['kind'] | 'text', raw: unknown): InputAnswer | undefined;
+/** 输入节点 `data` 的规范写法（读入的规范化 + 固定键序），写盘与比较都用它。 */
+export declare function canonicalInput(data: InputData): InputData;
+/** 两个节点的内容是否相同（类型 + `data`；坐标不算）。 */
+export declare function sameNodeContent(a: WorkflowNode, b: WorkflowNode): boolean;
+/** 一项内容的简称：文件与文件夹取最后一段，网址取主机名，skill 取名字，自定义取 `custom`。 */
+export declare function itemShortName(item: ResourceItem): string;
+/**
+ * 给资源起一个节点 id：按名字（没有就按第一项的简称，文件不带扩展名）换掉文件名里不许出现的字符，前面加 `res-`；
+ * 撞名（大小写不敏感）就加 `-2`、`-3`…
+ */
+export declare function resourceIdFor(data: ResourceData, taken: (id: string) => boolean): string;
+/**
+ * 把 `JSON.parse` 的结果规范化成我们的文档形状。
+ *
+ * 保存级破损（顶层不是对象 / `nodes` 或 `edges` 不是数组 / 元素不是对象 /
+ * 缺 `id` / 缺 `source` / `target` / 坐标非法）→ `document: null` + 保存级问题。
+ * 其余问题（未知字段、未知 `type`、`position` 缺失、悬空 edge…）在**保留文档**的前提下
+ * 逐条报出，交给上层按级别处置。
+ */
+export declare function normalizeDocument(input: unknown): ParseOutcome;
+/** `JSON.parse` + {@link normalizeDocument}。解析失败就是保存级。 */
+export declare function readDocument(text: string): ParseOutcome;
+/**
+ * Canonical 写出。**同一份文档两次写出必得逐字节相同的文本**，而不同文档的差异
+ * 被限制在改动的那一个块里（2 空格缩进的每节点／每边一个多行块）。
+ */
+export declare function writeDocument(document: WorkflowDocument): string;
+/** 深拷贝一份文档（工具做读-改-写时用，避免就地改调用方的对象）。 */
+export declare function cloneDocument(document: WorkflowDocument): WorkflowDocument;
+/** 按 `id` 找节点。 */
+export declare function findNode(document: WorkflowDocument, id: string): WorkflowNode | undefined;
+/** 一个节点的入边（**含回边**）。 */
+export declare function incomingEdges(document: WorkflowDocument, id: string): WorkflowEdge[];
+/** 一个节点的出边。 */
+export declare function outgoingEdges(document: WorkflowDocument, id: string): WorkflowEdge[];

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

@@ -0,0 +1,59 @@
+/**
+ * dsh-workflow-lite — 命名约束。
+ *
+ * 图名、模板名与 `node.id` **共用同一套文件名约束**（这三样都要落成文件名：
+ * `workflows/<图名>.json`、`templates/**\/<名>.json`、`.dispatch/<图名>/<planId>/<id>.md`）。
+ * `label` **不在**这套里——它不是文件名，只受"不得含换行或 `|`"一条。
+ *
+ * 写成**禁止集**而不是允许集：规则是"不许有什么"，所以中文名天然可用（`修复认证` 合法）。
+ *
+ * 纯函数，不碰磁盘、不 import DSH 包。
+ * @module @xiaoso/dsh-workflow-lite/shared/naming
+ */
+import type { ValidationCode } from './types.ts';
+/** 一条命名/取值问题：`code` 给机器，`message` 给人。 */
+export interface NameProblem {
+    code: ValidationCode;
+    message: string;
+}
+/** 码点数（不是 UTF-16 长度——emoji 与增补平面字符按 1 个数）。 */
+export declare function codepointLength(value: string): number;
+/**
+ * 归一：trim 尾部空白与尾随 `.`（Windows 会静默吞掉尾点），再统一 NFC。
+ * **比较与落盘都走这一步。**
+ */
+export declare function normalizeName(raw: string): string;
+/** 只做归一，不做校验——给"用户输入 → 待校验名字"这一步用。 */
+export declare function normalizeWhen(raw: string): string;
+/**
+ * 校验一个名字（图名 / 模板名 / `node.id`）。
+ * @returns `null` = 合法；否则是一条问题。
+ */
+export declare function checkName(raw: string): NameProblem | null;
+/**
+ * 校验 `when` 的值（条件出边的判据）。
+ *
+ * 两种都合法：短的判定词（`pass` / `fail` / `retry`，走 `VERDICT:` 约定），或者一句自然语言条件
+ * （"测试全绿且没有新增警告"）。只拦三样：空串（要无条件边就整条不写 `when`）、换行与控制字符
+ * （条件要能写进计划里的一句话）、超长。
+ */
+export declare function checkWhen(raw: string): NameProblem | null;
+/**
+ * 这个条件是不是判定词：一个短的英文标识（≤ {@link MAX_VERDICT_CODEPOINTS} 个字符，只含字母、
+ * 数字、`-`、`_`），如 `pass` / `fail` / `needs-review`。
+ *
+ * 判定词由上游在回复末行写 `VERDICT: <值>` 来选路；其余（包括"用户确认了方案"这类中文短句）
+ * 都按自然语言条件处理：由执行者读了上游产出之后自己判断成立与否——计划里两种的写法不同。
+ */
+export declare function isVerdictWhen(value: string): boolean;
+/** 校验节点描述 / 产出规则这类自由文本：只防病态长度。 */
+export declare function checkText(raw: string, what: string): NameProblem | null;
+/** 校验 `label`：只禁换行与竖线 `|`（它们会打断计划里的 markdown 表格）。 */
+export declare function checkLabel(raw: string): NameProblem | null;
+/**
+ * 校验 `output`：相对工作区根的路径，允许子路径，**禁止绝对路径与 `..`**。
+ * `false`（显式不产出）与缺省都合法，由调用方先分流。
+ */
+export declare function checkOutput(raw: string): NameProblem | null;
+/** 大小写不敏感的撞名比较（Windows 落盘不区分大小写，而这三样都是文件名）。 */
+export declare function sameName(a: string, b: string): boolean;

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

@@ -0,0 +1,49 @@
+/**
+ * dsh-workflow-lite — 产出路径：根目录的规范化，与「根目录 + 产出文件名」的拼接。
+ *
+ * 这件事**只在这里做**：编译器、校验、画布预览都调这几个函数，不各写一份字符串拼接。
+ * 规范化交给 `pathe`（Node `path` 的跨平台版本，浏览器里也能跑）：
+ * - 分隔符统一成 `/`（Windows 的 `D:\out` → `D:/out`，执行者的文件工具两种都认）；
+ * - 折叠重复的 `/`、`./`、`a/..`；盘符大写；UNC `\\srv\share` → `//srv/share`；
+ * - 拼接时不管根目录有没有尾斜杠、产出名是不是 `./` 开头，结果都只有一个分隔符。
+ *
+ * 纯函数，不碰磁盘、不 import DSH 包。
+ * @module @xiaoso/dsh-workflow-lite/shared/outputPaths
+ */
+import { type NameProblem } from './naming.ts';
+/**
+ * 根目录的规范写法：去首尾空白、`pathe.normalize`、去掉尾斜杠（`/`、`C:/`、`//srv/share` 这类根本身除外）。
+ * 空串与 `.` 都表示"工作区根"，返回 `undefined`（拼接时不加前缀）。
+ */
+export declare function normalizeRoot(raw: string | undefined): string | undefined;
+/** 根目录里的这个记号建实例时换成实例 id（每次执行的产出各放各的）。 */
+export declare const INSTANCE_TOKEN = "{instance}";
+/** 没配产出根目录时用它：和状态文件放在一起，每个实例一个 `out`。 */
+export declare const DEFAULT_OUTPUT_ROOT = ".workflow-lite/runs/{instance}/out";
+/** 写 `.` = 明确要写在工作区根目录（和"没配"区分开：没配是 {@link DEFAULT_OUTPUT_ROOT}）。 */
+export declare const WORKSPACE_ROOT = ".";
+/** 一张图实际用的产出根目录（还没换实例 id）：没配就是默认值。 */
+export declare function rootOf(settings: {
+    outputRoot?: string;
+} | undefined): string;
+/** 把根目录里的 {@link INSTANCE_TOKEN} 换成 `instance`，再规范化；结果是工作区根时回 `.`。 */
+export declare function bindRoot(root: string, instance: string): string;
+/** 根目录是不是绝对路径（`/x`、`C:/x`、`//srv/share`；`C:` 这种盘符相对写法规范化后也算）。 */
+export declare function isAbsoluteRoot(root: string): boolean;
+/**
+ * 一个产出文件最终写到哪：`根目录 + 产出路径`，规范化。没配根目录就是规范化后的产出路径本身
+ * （相对工作区）。产出路径本身是绝对路径时原样用（规范化），不拼根目录。
+ */
+export declare function resolveOutputPath(root: string | undefined, path: string): string;
+/**
+ * 资源里一个文件 / 文件夹实际在哪：绝对路径原样用；相对路径在有步骤写这个资源时放在产出根目录下
+ * （它是这次执行的产出），只被读时相对工作区（它是现成的东西）。
+ */
+export declare function resolveItemPath(root: string | undefined, path: string, written: boolean): string;
+/**
+ * 一个产出文件的身份：规范化后的相对路径（`./a.md` 与 `a.md` 是同一份）。
+ * 交接引用产出、统计「谁在用这份文件」都按它比较。
+ */
+export declare function outputKey(path: string): string;
+/** 根目录合不合法：只拦控制字符、`~`（不会被展开）与超长；相对、绝对、`..` 都允许。 */
+export declare function checkOutputRoot(raw: string): NameProblem | null;

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

@@ -0,0 +1,98 @@
+/**
+ * dsh-workflow-lite — 资源节点与交接：图上"传了什么"的唯一解释。
+ *
+ * 两种东西在步骤之间传，性质不同，所以分开表达：
+ * - **资源**是独立的东西，不依赖某一次运行——画成**资源节点**，一个资源里可以放好几项（文件、文件夹、
+ *   网址、Skill、自定义）。步骤 → 资源 = 写它（写的是其中的文件与文件夹：产出，或在原文件上更新）；
+ *   资源 → 步骤 = 读它。几个步骤连到同一个资源，它就是几步之间共用的一份；一条线都没连的资源交给
+ *   整个工作流。
+ * - **执行结果**是某一次运行的回复——沿**步骤 → 步骤**的线交给下游（缺省就交；可以附一段交接说明，
+ *   也可以设成"只管先后"）。
+ *
+ * 编译器、校验、画布、工具都从这里取解释。纯函数，不碰磁盘、不 import DSH 包。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/resources
+ */
+import { type Handoff, type OutputSpec, type ResourceData, type ResourceItem, type ResourceNode, type StepNode, type WorkflowDocument, type WorkflowEdge, type WorkflowNode } from './types.ts';
+/**
+ * - `flow`：步骤 → 步骤（先后，带条件与交接）；
+ * - `write`：步骤 → 资源；`read`：资源 → 步骤；
+ * - `ask`：输入 → 步骤（把用户的回答交给它）；
+ * - `invalid`：资源 → 资源、连进输入节点、输入连到资源（保存级）；`dangling`：端点不存在。
+ */
+export type EdgeKind = 'flow' | 'write' | 'read' | 'ask' | 'invalid' | 'dangling';
+/** 按 `idKey` 查节点（同 id 重复时取第一个）。 */
+export declare function nodeIndex(document: WorkflowDocument): Map<string, WorkflowNode>;
+export declare function edgeKind(nodes: ReadonlyMap<string, WorkflowNode>, edge: WorkflowEdge): EdgeKind;
+/** 只留步骤 → 步骤的线（执行次序、环、批次只看它们）。 */
+export declare function flowEdges(document: WorkflowDocument): WorkflowEdge[];
+/** 这一项步骤能不能写（文件、文件夹）。 */
+export declare function isWritable(item: ResourceItem): boolean;
+/** 资源的称呼：名字；没有名字就用第一项的简称；什么都没有就是 id。 */
+export declare function resourceTitle(resource: ResourceNode): string;
+export interface ResourceInfo {
+    resource: ResourceNode;
+    /** 写它的步骤（文件中的顺序）；`update` = 在原文件上更新。 */
+    writers: {
+        id: string;
+        update: boolean;
+    }[];
+    /** 读它的步骤。 */
+    readers: string[];
+}
+/** 一个资源有没有连任何步骤：一条线都没有就交给整个工作流。 */
+export declare function isShared(info: ResourceInfo): boolean;
+/** 资源节点 id（规范大小写）→ 写它、读它的步骤。 */
+export declare function resourceGraph(document: WorkflowDocument): Map<string, ResourceInfo>;
+/** 一个步骤和它连着的资源（不含交给整个工作流的那些）。 */
+export interface StepResources {
+    writes: {
+        resource: ResourceNode;
+        update: boolean;
+        edge: WorkflowEdge;
+    }[];
+    reads: {
+        resource: ResourceNode;
+        edge: WorkflowEdge;
+    }[];
+}
+export declare function stepResources(document: WorkflowDocument, stepId: string): StepResources;
+/** 交给整个工作流的资源（一条线都没连的那些），按文件中的顺序。 */
+export declare function sharedResources(document: WorkflowDocument): ResourceNode[];
+/** 某个步骤与某个资源的关系（画布高亮用）；没关系是 `null`。 */
+export type ResourceRole = 'producer' | 'updater' | 'reader';
+export declare function roleOf(info: ResourceInfo | undefined, stepId: string): ResourceRole | null;
+/** 一个步骤写的资源里的文件，摊成产出清单（存成步骤模板时用）。 */
+export declare function outputsOf(document: WorkflowDocument, stepId: string): OutputSpec[];
+/** 一个产出文件对应的资源内容：一个文件项，生成规则写进它的说明。 */
+export declare function outputResource(spec: OutputSpec): ResourceData;
+/** 按路径（规范化后）找放着这个文件的资源；有好几个时优先只放了它一项的。 */
+export declare function resourceByPath(document: WorkflowDocument, path: string): ResourceNode | undefined;
+/** 新资源节点（`(0,0)` = 还没摆过，由布局补位）。 */
+export declare function newResourceNode(document: WorkflowDocument, data: ResourceData, position?: {
+    x: number;
+    y: number;
+}): ResourceNode;
+/**
+ * 让一个步骤恰好写这些文件（工具的 `write_node` 与模板展开用）：
+ * 路径已有资源就连上它（文件项没写过说明就补上），没有就新建一个只放这个文件的资源；
+ * 不在清单里的写入线去掉，去掉之后什么都不连的资源一并删掉。**就地改** `document`。
+ * @param positionOf - 新资源节点的坐标（第几个新资源 → 坐标）；缺省 `(0,0)`。
+ * @returns 新建的资源节点 id。
+ */
+export declare function setStepOutputs(document: WorkflowDocument, stepId: string, specs: readonly OutputSpec[], positionOf?: (index: number) => {
+    x: number;
+    y: number;
+}): string[];
+/** 把模板里的产出清单（`data.output`）挑出来，剩下的是步骤自己的 `data`。 */
+export declare function splitOutputs(data: StepNode['data']): {
+    data: StepNode['data'];
+    outputs: OutputSpec[];
+};
+/** 一条步骤间的线实际交了什么。 */
+export interface ResolvedHandoff {
+    /** 交不交上游的执行结果。 */
+    result: boolean;
+    note?: string;
+}
+export declare function resolveHandoff(handoff: Handoff | false | undefined): ResolvedHandoff;

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

@@ -0,0 +1,54 @@
+/**
+ * dsh-workflow-lite — 运行到哪了：按图、判定和流水推出**最后执行**的步骤与**接下来**该做的步骤。
+ *
+ * 只看各步骤的状态会漂：循环里每个步骤都做过一轮、都是 `done`，"第一个没完成的步骤"会跳到环外。
+ * 这里改看流水（只追加，下标就是先后）：
+ * - 一个步骤做完之后，它该交给的下游（无条件线、条件等于它这一轮判定的线）在那之后还没有动静，
+ *   它就是**最后执行**的步骤之一，那些下游就是**接下来**的步骤（回边 = 循环回去，再做一轮）；
+ * - 失败的步骤一直算最后执行（等重做或叫停）；
+ * - 都接上了（下游在跑，或走到了头）时，最后执行 = 最近做完的那一步（同一次调用写下的几步一起算）。
+ *
+ * 另外两种「接下来」：从没开始过的入口步骤，和被改回 `pending` 的步骤（它前面的都完成了才轮到）。
+ *
+ * 用户也可以**指定**下一步（状态里的 `next`，流水里记一条 `next` 事件）：
+ * - 指定还在时，「接下来」就是指定的这几步；
+ * - 指定那一刻之前做完的步骤，交接都算已经了结——模型做完指定的步骤后，不会再绕回指定之前没接上的下游。
+ * 画布上的「最后执行 / 下一步」标记与工具回给模型的进度都用它。
+ *
+ * @module @xiaoso/dsh-workflow-lite/shared/runCursor
+ */
+import { type GraphAnalysis } from './graph.ts';
+import type { NodeStatus, RunState } from './runState.ts';
+import type { WorkflowDocument } from './types.ts';
+/** 最后执行的一步。 */
+export interface CursorStep {
+    node: string;
+    status: NodeStatus;
+    round?: number;
+    verdict?: string;
+    /** 结束时刻。 */
+    at?: string;
+}
+/** 接下来的一步。 */
+export interface NextStep {
+    node: string;
+    /** 做的话是第几轮。 */
+    round: number;
+    /**
+     * `flow` = 上游交过来；`start` = 入口步骤还没开始；`reset` = 被改回 pending，要重做；
+     * `pinned` = 用户指定。
+     */
+    reason: 'flow' | 'start' | 'reset' | 'pinned';
+    /** 谁交过来的（`flow` 才有）。 */
+    from?: string;
+    /** 沿回边过来：循环回到这一步。 */
+    loop?: true;
+}
+export interface RunCursor {
+    /** 按做完的先后。 */
+    last: CursorStep[];
+    running: string[];
+    waiting: string[];
+    next: NextStep[];
+}
+export declare function runCursor(document: WorkflowDocument, state: RunState, analysis?: GraphAnalysis): RunCursor;