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

package/lib/types/client/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * dsh-workflow-lite — 浏览器半。
+ *
+ * 把工作流视图挂到会话页的 tab 上（`conversation.view` 槽位），并接上共享 Connection 的
+ * `/api` 通道。UI 文案走本插件的 locale 词典（`workflow-lite`）。
+ *
+ * tab 的显示名用 **thunk**：槽位每次读取时重新求值，所以切语言不用重新注册。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** 视图需要的三个客户端服务。 */
+export declare const inject: string[];
+/**
+ * 挂载视图。
+ * @param ctx - 浏览器插件上下文。
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/model/connect.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh-workflow-lite — 拖线连接的规则：从哪个连接点拖出来、能落到哪些连接点上、连上会是什么线。
+ *
+ * 连接点各有分工（「左右走流程，上下走资源」）：
+ * - 步骤左 `in`：入口——接上游步骤（流程）或资源卡（读取）；
+ * - 步骤右 `out`：出口——只连下一个步骤（流程）；
+ * - 步骤底 `file`：出口——只连资源卡（写入）；
+ * - 资源左 `in`：入口——只接步骤的写点（写入）；
+ * - 资源右 `out`：出口——只连步骤（读取）；
+ * - 输入右 `out`：出口——只连步骤（把回答交给它，落点和读资源一样）。输入没有入口。
+ * 步骤上还有几个备用点（上边的写点 `fileUp`、上下边的读点 `read` / `readTop`），挂哪个由画布按位置挑。
+ *
+ * 画布据此在拖线时只露出能连的连接点，并在松手前预告这条线的含义。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/connect
+ */
+import type { WorkflowDocument, WorkflowNode } from '../../shared/types.ts';
+/**
+ * 正在拖的是哪种线（按起点）：
+ * `flow` 步骤右 → 找步骤；`write` 步骤底/上的写点 → 找资源；`read` 资源右 → 找步骤；
+ * `back` 从步骤左边倒着拖 → 找步骤右 / 资源右；`writeBack` 从资源左边倒着拖 → 找步骤的写点；
+ * `readBack` 从步骤的读点倒着拖 → 找资源或输入；`ask` 输入右 → 找步骤。
+ */
+export type DragKind = 'flow' | 'write' | 'read' | 'ask' | 'back' | 'writeBack' | 'readBack';
+/** 拖线起点是哪种卡。 */
+export type CardKind = 'step' | 'resource' | 'input';
+export declare function dragKindOf(from: CardKind, handleId: string | null | undefined): DragKind | null;
+/** React Flow 交过来的连接（已按 source → target 摆正）。 */
+export interface HandleLink {
+    source: string;
+    sourceHandle?: string | null;
+    target: string;
+    targetHandle?: string | null;
+}
+/** 这条拖出来的线能不能连：不连自己、资源不连资源，且两头的连接点分工要对得上。 */
+export declare function linkAllowed(doc: WorkflowDocument, link: HandleLink): boolean;
+/** 连上之后会是什么线：流程 / 产出 / 更新 / 读取 / 交回答；`exists` = 已经连着了，松手什么也不会变。 */
+export interface LinkPreview {
+    kind: 'flow' | 'produce' | 'update' | 'read' | 'ask';
+    source: WorkflowNode;
+    target: WorkflowNode;
+    exists: boolean;
+}
+export declare function previewLink(doc: WorkflowDocument, link: HandleLink): LinkPreview | null;

package/lib/types/client/model/editor.d.ts

@@ -0,0 +1,252 @@
+/**
+ * dsh-workflow-lite — 编辑器状态机（**纯逻辑**，组件只管接线）。
+ *
+ * 事实源是磁盘上的那份 JSON。三个计数讲清"有没有没落盘的改动"：
+ * - `rev`       每次改文档 +1（撤销/重做也算——它们同样需要落盘）；
+ * - `savedRev`  磁盘上已知持有的那一版；
+ * - `savingRev` 在途那笔保存对应的版本。
+ * `rev !== savedRev` 即为脏。保存期间又来的改动不会被误判成已落盘，因为保存成功只把
+ * `savedRev` 推到 `savingRev`，而不是推到最新。
+ *
+ * 节点身份一律按 `idKey`（大小写不敏感）比较；`label` 只用于显示。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/editor
+ */
+import { type Handoff, type InputData, type NodeData, type Point, type ResourceData, type ValidationProblem, type WorkflowDocument, type WorkflowEdge, type WorkflowNode, type WorkflowSettings } from '../../shared/types.ts';
+/** 选中态：步骤、连线，或什么都不选。用一个联合表达，互斥是结构上保证的。 */
+export type Selection = {
+    kind: 'node';
+    id: string;
+} | {
+    kind: 'edge';
+    id: string;
+} | null;
+/** `idle` 没打开任何工作流；`broken` 文件读不了（只读，绝不写盘）。 */
+export type Phase = 'idle' | 'loading' | 'ready' | 'broken';
+export interface EditorState {
+    phase: Phase;
+    name: string | null;
+    doc: WorkflowDocument | null;
+    /** 本地文档所基于的磁盘内容哈希（保存时提交它做写前比对）。 */
+    baseHash: string | null;
+    /** host 给的全部校验问题（四级）。 */
+    problems: ValidationProblem[];
+    /** `broken` 态的说明与原文。 */
+    broken: {
+        message: string;
+        raw: string | null;
+    } | null;
+    selection: Selection;
+    rev: number;
+    savedRev: number;
+    saving: boolean;
+    savingRev: number;
+    saveError: string | null;
+    /** 撤销栈：每个元素是"那次改动之前"的文档。 */
+    past: WorkflowDocument[];
+    future: WorkflowDocument[];
+    /** 当前历史条目的合并键；相同键的连续改动并成一条撤销步。 */
+    mergeKey: string | null;
+    /**
+     * 每压一条新的撤销步 +1（撤销、重做、合并进上一步都不算），换基线也不归零。
+     * 撤销栈到了上限时长度不再变，靠它才看得出"又多了一步"（实例视图把图和状态的撤销排成一条时用）。
+     */
+    historySeq: number;
+    /** 每载入一份新基线 +1：画布据此重新定视口（保存不算，免得每存一次都跳一下）。 */
+    loadSeq: number;
+}
+/** 撤销栈上限。 */
+export declare const HISTORY_LIMIT = 60;
+export declare const initialState: EditorState;
+/** 会改文档的动作。 */
+export type Edit = {
+    type: 'addNode';
+    id: string;
+    /** 步骤的 `data`；带着 `output`（来自模板）时展开成挂在它右下方的资源节点。 */
+    data: NodeData;
+    position: Point;
+    /** 顺手从这个节点连一条线过来（「添加下一步」；从资源拖出来 = 新步骤读这个资源）。 */
+    from?: string;
+}
+/**
+ * 加一个资源节点。给了 `writer` 就连「步骤 → 资源」（写），给了 `reader` 就连「资源 → 步骤」（读）。
+ * 没给坐标时挂在写它（读它）的步骤右下方。`select` = 加完选中它（缺省不动选中）。
+ */
+ | {
+    type: 'addResource';
+    data: ResourceData;
+    position?: Point;
+    writer?: string;
+    reader?: string;
+    select?: boolean;
+}
+/**
+ * 加一个输入节点。给了 `reader` 就连「输入 → 步骤」（把回答交给它）；没给坐标时放在它左边。
+ * 加完选中它（好接着写问题）。
+ */
+ | {
+    type: 'addInput';
+    id: string;
+    data: InputData;
+    position?: Point;
+    reader?: string;
+}
+/** 改输入节点（值为 `undefined` 的键 = 清掉这一项）。`merge` 同 `patchNode`。 */
+ | {
+    type: 'patchInput';
+    id: string;
+    patch: Partial<InputData>;
+    merge?: string;
+}
+/** 一次加进一小片图（示例流程）：算一条撤销步。`settings` 并进工作流设置（同一步）。 */
+ | {
+    type: 'addGraph';
+    settings?: WorkflowSettings;
+    nodes: WorkflowNode[];
+    edges: {
+        source: string;
+        target: string;
+        when?: string;
+        handoff?: Handoff | false;
+        update?: boolean;
+    }[];
+} | {
+    type: 'removeNode';
+    id: string;
+}
+/**
+ * 改坐标。`silent` = 程序自动补位：照样落盘，但不进撤销栈
+ * （`Ctrl+Z` 撤出一个"节点全叠在原点"的版本不是任何人想要的）。
+ */
+ | {
+    type: 'moveNodes';
+    positions: Record<string, Point>;
+    silent?: boolean;
+}
+/**
+ * 改步骤的 `data`。值为 `undefined` 的键表示**清掉这一项**。
+ * `merge` 相同的连续改动并成一条撤销步（连续打字）。
+ */
+ | {
+    type: 'patchNode';
+    id: string;
+    patch: Partial<NodeData>;
+    merge?: string;
+}
+/** 改资源节点：名字 / 描述 / 内容（值为 `undefined` 的键 = 清掉；`items` 整份替换）。 */
+ | {
+    type: 'patchResource';
+    id: string;
+    patch: Partial<ResourceData>;
+    merge?: string;
+} | {
+    type: 'connect';
+    source: string;
+    target: string;
+    when?: string;
+} | {
+    type: 'removeEdge';
+    id: string;
+}
+/** 改条件。`merge` 相同的连续改动并成一条撤销步（在自定义条件里连续打字）。 */
+ | {
+    type: 'setWhen';
+    id: string;
+    when: string | undefined;
+    merge?: string;
+}
+/**
+ * 改交接（步骤 → 步骤）。`undefined` = 交执行结果，`false` = 只管先后，对象 = 交执行结果并附说明。
+ * `merge` 相同的连续改动并成一条撤销步（在交接说明里连续打字）。
+ */
+ | {
+    type: 'setHandoff';
+    id: string;
+    handoff: Handoff | false | undefined;
+    merge?: string;
+}
+/** 改写入方式（步骤 → 资源）：整份写出 / 在原文件上更新。 */
+ | {
+    type: 'setUpdate';
+    id: string;
+    update: boolean;
+}
+/** 视口是视图状态：照样落盘，但不进撤销栈。 */
+/** 换掉整份工作流设置（设置对话框「完成」时一次交出来 = 一条撤销步）。 */
+ | {
+    type: 'setSettings';
+    settings: WorkflowSettings | undefined;
+}
+/** 整张换掉（实例视图撤回某一处改动时用）；选中的东西不在了就放掉。 */
+ | {
+    type: 'replaceDoc';
+    doc: WorkflowDocument;
+};
+export type Action = Edit | {
+    type: 'loading';
+    name: string;
+} | {
+    type: 'loaded';
+    name: string;
+    doc: WorkflowDocument;
+    baseHash: string;
+    problems: ValidationProblem[];
+} | {
+    type: 'broken';
+    name: string;
+    message: string;
+    raw: string | null;
+    problems: ValidationProblem[];
+} | {
+    type: 'closed';
+} | {
+    type: 'renamed';
+    name: string;
+} | {
+    type: 'select';
+    selection: Selection;
+} | {
+    type: 'undo';
+} | {
+    type: 'redo';
+}
+/** 丢掉重做栈（实例视图里别处有了新的一步：撤销排成一条，新的一步之后都不能重做）。 */
+ | {
+    type: 'dropFuture';
+}
+/** 一次交互结束（输入失焦）：断开历史合并。 */
+ | {
+    type: 'seal';
+} | {
+    type: 'saveStarted';
+    rev: number;
+} | {
+    type: 'saveDone';
+    baseHash: string;
+} | {
+    type: 'saveFailed';
+    message: string;
+}
+/**
+ * 回读磁盘后的刷新。带 `doc` = 本地没有在途改动，整份换成磁盘上（合并后）的版本；
+ * `external` = 这份来自外部改动而不是自己的保存，旧历史作废。
+ */
+ | {
+    type: 'refreshed';
+    problems: ValidationProblem[];
+    doc?: WorkflowDocument;
+    baseHash?: string;
+    external?: boolean;
+};
+export declare function isDirty(state: EditorState): boolean;
+export declare function findNode(doc: WorkflowDocument, id: string): WorkflowNode | undefined;
+export declare function findEdge(doc: WorkflowDocument, id: string): WorkflowEdge | undefined;
+/** 一条边的条件值（空串与缺省同义）。 */
+export declare function whenOf(edge: WorkflowEdge): string | undefined;
+/** 新步骤的 id：撞名就加 `-2`、`-3`…（**绝不静默覆盖**）。 */
+export declare function uniqueNodeId(doc: WorkflowDocument, base: string): string;
+/** 这个资源已经有步骤在写（`except` 除外）——再接上来的写入默认是"在原文件上更新"。 */
+export declare function alreadyWritten(doc: WorkflowDocument, resourceId: string, except?: string): boolean;
+/** 图里资源已经用掉的文件路径（规范化、小写后）。 */
+export declare function takenPaths(doc: WorkflowDocument): string[];
+export declare function reduce(state: EditorState, action: Action): EditorState;

package/lib/types/client/model/fileKind.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dsh-workflow-lite — 文件的类型：按扩展名粗分几类，给类型签配色、决定能不能在查看框里看。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/fileKind
+ */
+export type FileKind = 'markdown' | 'text' | 'code' | 'data' | 'image' | 'other';
+/** 路径的最后一段。 */
+export declare function fileBaseName(path: string): string;
+/** 路径去掉最后一段剩下的目录（没有就是空串）。 */
+export declare function fileDirName(path: string): string;
+/** 扩展名，小写、不带点；没有就是空串。 */
+export declare function extensionOf(path: string): string;
+export declare function fileKindOf(path: string): FileKind;
+/** 字节数写成人看的样子：`812 B`、`3.4 KB`、`1.2 MB`。 */
+export declare function formatBytes(bytes: number): string;

package/lib/types/client/model/hostPath.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dsh-workflow-lite — 主机路径拆成面包屑（选择文件 / 文件夹时的路径栏）。
+ *
+ * 只认分隔符已统一成 `/` 的绝对路径（`host/list` 回的就是这种）：
+ * `C:/Users/me` → `C:`、`Users`、`me`；`/home/me` → `/`、`home`、`me`；`//server/share/x` → `//server/share`、`x`。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/hostPath
+ */
+export interface Crumb {
+    /** 显示的名字。 */
+    label: string;
+    /** 点它跳去的绝对路径。 */
+    path: string;
+}
+export declare function crumbs(path: string): Crumb[];

package/lib/types/client/model/htmlPreview.d.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-workflow-lite — 在查看框里渲染 HTML 之前，给页面补细滚动条，颜色跟着页面自己的底色走。
+ *
+ * 框里的页面是独立的源，外面的样式进不去，只能在交给 `srcdoc` 的文字里补。
+ *
+ * 滚动条画在页面上，该看的是**页面的**底色，不是画布的主题：没写背景的页面在框里是白底（画布暗色时也是），
+ * 暗色看板在亮色画布里照样是暗底。所以补一小段脚本，页面加载后读 `<body>` / `<html>` 的背景色，
+ * 深底用浅色滑块、浅底用深色滑块；脚本跑起来之前先用一个两种底色上都看得见的中灰。
+ *
+ * 样式用 `:where()` 把优先级压到零——页面自己写了滚动条样式就用页面的。插在 `<head>` 后
+ * （没有就在 `<html>` / doctype 后），不能插到 doctype 前面，否则页面会掉进怪异模式。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/htmlPreview
+ */
+/** 深底上的滑块、浅底上的滑块、还不知道底色时的滑块。 */
+export declare const THUMB: {
+    readonly onDark: "rgba(255,255,255,.28)";
+    readonly onLight: "rgba(0,0,0,.28)";
+    readonly unknown: "rgba(128,128,128,.45)";
+};
+/** 补进页面的那一段。 */
+export declare const PREVIEW_STYLE: string;
+/** 把 {@link PREVIEW_STYLE} 插进页面。 */
+export declare function withPreviewStyle(html: string): string;

package/lib/types/client/model/hubRuns.d.ts

@@ -0,0 +1,45 @@
+/**
+ * dsh-workflow-lite — 工作流中心「运行实例」页的筛选与分组：按工作区分组、按工作区 / 会话 / 关键字筛。
+ *
+ * 工作区就是实例建立时会话的 `cwd`；路径的大小写、分隔符、末尾斜杠不同也算同一个（Windows）。
+ * 没记下工作区的实例归在一组（键是空串）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/hubRuns
+ */
+import type { InstanceSummary } from '../../shared/runState.ts';
+/** 一个工作区。 */
+export interface HubWorkspace {
+    /** 比较用的键（标准化后的路径；没有工作区是空串）。 */
+    key: string;
+    /** 原样的路径（取这一组里最新那个实例记下的写法）。 */
+    path: string | undefined;
+    /** 显示用的名字：路径最后一段。 */
+    name: string;
+    count: number;
+    /** 是不是本会话所在的工作区。 */
+    here: boolean;
+}
+/** 工作区的比较键。 */
+export declare function workspaceKey(cwd: string | undefined): string;
+/** 路径最后一段（`D:\a\b` → `b`；盘符根 `D:\` → `D:`）。 */
+export declare function workspaceName(path: string): string;
+/** 列表里出现过的工作区：本会话的在最前，其余按最近一次建实例的时间，新的在前。 */
+export declare function workspacesOf(items: readonly InstanceSummary[], hereCwd: string | undefined): HubWorkspace[];
+/** 关键字命中没有：工作流名、会话标题、目标、工作区路径、实例 id，忽略大小写；空白分开的几个词都要命中。 */
+export declare function matchesQuery(item: InstanceSummary, sessionTitle: string | undefined, query: string): boolean;
+export interface HubFilter {
+    /** `'all'` = 全部工作区；否则是 {@link workspaceKey}。 */
+    workspace: string;
+    /** 只看本会话的。 */
+    mine: boolean;
+    query: string;
+}
+/** 按筛选条件挑出实例，再按工作区分组（组的顺序同 {@link workspacesOf}，组内保持原顺序：新的在前）。 */
+export declare function groupRuns(items: readonly InstanceSummary[], options: HubFilter & {
+    session: string | undefined;
+    hereCwd: string | undefined;
+    titleOf: (session: string | undefined) => string | undefined;
+}): {
+    workspace: HubWorkspace;
+    items: InstanceSummary[];
+}[];

package/lib/types/client/model/layout.d.ts

@@ -0,0 +1,83 @@
+/**
+ * dsh-workflow-lite — 自动布局。
+ *
+ * 整图重排交给 ELK（`elkjs` 的 layered 算法）：分层、同层排序（减少交叉）、算坐标都是它做的。
+ * 我们只把自己的版式语法喂给它：
+ * - **列 = 执行批次**：用 ELK 的 interactive 分层，按批次给出横坐标，版面本身就在讲执行次序；
+ * - **资源挂在写它的步骤下面**：一个步骤和它写的资源在 ELK 眼里是一整块（步骤卡 + 下面竖着一串
+ *   资源卡），块的高度随资源卡的高度变，ELK 按真实高度排，谁也压不到谁；资源卡往右缩进，写线从步骤的
+ *   写点竖着落下来、分叉进每张资源卡的左边（见 route.ts），不会穿过任何卡片；
+ * - 没人写、只被读的资源单独成块，放在第一个读它的步骤的前一列；只被后面的步骤在原文件上更新、
+ *   却被前面的步骤读的（共享的状态文档、台账）也一样——它本来就在，是输入；
+ * - 读线只拉相邻一列的（或者读它的步骤没别的线拉着）：跨好几列的读线不参与排版，免得把主线挤歪；
+ * - 流程线的进出口固定在步骤卡（不是整块）的半高处，ELK 才会把一条链摆成一条直线。
+ * - 列距整齐划一；只有相邻两列之间的线上挂着条件牌子 / 交接标记时，把那一处拉开到放得下牌子。
+ *
+ * 补位（只给个别新节点找地方）仍是同步的就近规则：已经摆好的版面一律不动。
+ *
+ * `(0,0)` 是"还没摆过"的哨兵值（host 新建节点时的初始坐标），所以版面原点不落在它上面。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/layout
+ */
+import type { GraphAnalysis } from '../../shared/graph.ts';
+import type { Point, ResourceData, WorkflowDocument, WorkflowNode } from '../../shared/types.ts';
+/** 步骤卡的宽度（CSS 里写死同一个数）与估算高度。 */
+export declare const NODE_W = 216;
+export declare const NODE_H = 96;
+/** 资源卡的宽度（CSS 里写死同一个数）与紧凑时的高度（只有一项、没起名字：一行，像一张文件卡）。 */
+export declare const RES_W = 200;
+export declare const RES_H = 56;
+/** 资源卡上最多列几项，再多折成"还有 N 项"。 */
+export declare const RES_SHOWN = 4;
+/** 资源卡是不是紧凑的一行：没名字、没描述、最多一项。 */
+export declare function isCompactResource(data: ResourceData): boolean;
+/** 资源卡的估算高度（画布量出来之前按它排）。 */
+export declare function resourceHeight(data: ResourceData): number;
+/** 输入卡的宽度（CSS 里写死同一个数）与估算高度：挂在读它的步骤旁边。 */
+export declare const INPUT_W = 180;
+export declare const INPUT_H = 56;
+/** 一张卡的标称尺寸（还没量出来时按它算）。 */
+export declare function cardSize(node: WorkflowNode): {
+    w: number;
+    h: number;
+};
+/**
+ * 资源卡相对写它的步骤：往右缩进 `RES_DX`（左边要让出树干和拐弯），第一张离步骤底边
+ * `RES_DY`，往下每张隔 `RES_GAP`。
+ */
+export declare const RES_DX = 84;
+/** 列距（「添加下一步」也按它往右挪一列）与行距。 */
+export declare const COL_STEP: number;
+export declare const ROW_STEP = 132;
+/**
+ * 一个资源卡该放哪：挂在写它的步骤（没人写就是读它的步骤）下面、往右缩进，被占了就往下找。
+ * @param anchor - 写它 / 读它的步骤的坐标；没有就放在版面左下。
+ */
+export declare function resourceSpot(doc: WorkflowDocument, anchor: Point | undefined, skip?: string, height?: number): Point;
+/**
+ * 一个输入卡该放哪：读它的步骤左边、和步骤上沿对齐，被占了就往下找；没有读它的步骤就放在版面左上方。
+ */
+export declare function inputSpot(doc: WorkflowDocument, reader: Point | undefined, skip?: string): Point;
+/** 这个节点是不是还没摆过。 */
+export declare function isUnplaced(position: Point): boolean;
+/** 量出来的卡片尺寸（画布上已经渲染过的卡）；没有就按估算尺寸。 */
+export type SizeOf = (id: string) => {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * 整图重排：每个节点都重算，同一张图必然摆成同一版式。
+ * @param sizeOf - 卡片的真实尺寸（步骤卡的高度随内容变）；不给就按估算尺寸。
+ */
+export declare function tidy(doc: WorkflowDocument, analysis: GraphAnalysis, sizeOf?: SizeOf): Promise<Record<string, Point>>;
+/** 从 `want` 起往下找一个不压住任何已有卡片的位置。 */
+export declare function freeSpot(occupied: readonly Point[], want: Point): Point;
+/** 「添加下一步」的落点：源步骤的右边一列，被占了就往下找。 */
+export declare function nextTo(doc: WorkflowDocument, source: Point): Point;
+/**
+ * 给**还没摆过**的节点补坐标（已有坐标的一律不动）。
+ *
+ * 全都没摆过 ⇒ 整图重排；只有个别没摆过（模型用工具新加了一步）⇒ 挨着它的上游放，
+ * 不去动用户已经摆好的版面。
+ */
+export declare function placeMissing(doc: WorkflowDocument, analysis: GraphAnalysis): Promise<Record<string, Point>>;

package/lib/types/client/model/library.d.ts

@@ -0,0 +1,109 @@
+/**
+ * dsh-workflow-lite — 步骤库的内容，与「库 → 画布」的拖放载荷。
+ *
+ * 内置步骤是**起点不是规范**：开箱即用的提示词骨架，插进图里之后随便改。没有它们，
+ * 一张新图只能从空白提示词写起。文案全部走 locale 词典（键名在这里，正文在 `i18n.ts`）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/library
+ */
+import type { Handoff, InputData, InputKind, NodeData, WorkflowNode, WorkflowSettings } from '../../shared/types.ts';
+import type { LocaleKey, T } from '../i18n.ts';
+export interface StepPreset {
+    /** 建议的节点 id（撞名由 `uniqueNodeId` 加序号）。 */
+    id: string;
+    labelKey: LocaleKey;
+    descKey: LocaleKey;
+    promptKey: LocaleKey;
+    /** 产出契约；`false` = 显式声明不产出文件。 */
+    output?: string | false;
+    /** 产出文件的生成规则（进计划的「产出要求」）。 */
+    ruleKey?: LocaleKey;
+}
+/** 呈现顺序 = 一条常见主线的顺序。 */
+export declare const PRESETS: readonly StepPreset[];
+/**
+ * 右侧面板正在看步骤库里的哪一项（与画布上的选中互斥）。
+ * `new` = 正在新建一个「我的步骤」，`seed` 是预填的内容（复制内置步骤时带过来）。
+ */
+export type LibraryFocus = {
+    kind: 'preset';
+    id: string;
+} | {
+    kind: 'template';
+    name: string;
+} | {
+    kind: 'new';
+    seed: NodeData;
+    name: string;
+};
+/** 空白步骤的建议 id。 */
+export declare const BLANK_ID = "step";
+/** 输入节点的建议 id。 */
+export declare const INPUT_ID = "ask";
+/**
+ * 输入的四种交互（呈现顺序）与文案。步骤库里只有一个「用户输入」，拖到画布上默认是一句话，
+ * 在属性面板里切换交互方式。
+ */
+export declare const INPUT_KIND_OPTIONS: readonly {
+    kind: InputKind;
+    labelKey: LocaleKey;
+}[];
+/** 交互方式的显示名。 */
+export declare function inputKindLabel(kind: InputKind): LocaleKey;
+/** 新输入节点的 `data`：一句话，带一个起手的问题（空问题挡编译）。 */
+export declare function inputData(t: T): InputData;
+/** 内置步骤实例化成节点的 `data`。 */
+export declare function presetData(preset: StepPreset, t: T): NodeData;
+/**
+ * 示例流程：侦察 → 实现 → 审查，通过去汇总，未通过去修复再回到审查。
+ * 一次把能用的东西都摆出来，比任何说明文字都快：
+ * - 顺序、条件分支（通过 / 未通过）、循环（修完回到审查），线上附交接说明；
+ * - 用户输入：执行前问「这次要做什么」（多行文字、必填，交给侦察与实现）和「审查要多严格」（单选，交给审查）；
+ * - 资源：每一步的产出挂在它右下方；审查报告由修复在原文件上打钩、汇总读它的最终版；
+ *   「项目资料」一张卡放文件夹、文件、网址三项，侦察和实现都读它；
+ *   「团队约定」是一段自定义提示词，一条线都不连 = 交给每一步；
+ * - 设置：打开「记录运行状态」，执行后能在实例里看进度。
+ */
+export declare function starterGraph(t: T): {
+    settings: WorkflowSettings;
+    nodes: WorkflowNode[];
+    edges: {
+        source: string;
+        target: string;
+        when?: string;
+        handoff?: Handoff | false;
+        update?: boolean;
+    }[];
+};
+/** 自定义 MIME，免得跟别处的拖放撞车。 */
+export declare const DND_MIME = "application/x-workflow-lite-step";
+/** 从库里拿出来的东西：空白步骤、内置步骤，或磁盘上的节点模板。 */
+export type StepSource = {
+    kind: 'blank';
+}
+/**
+ * 一张资源卡（不是步骤，但同样从库里拖、从菜单里加）。从步骤的写点 / 「＋」加的是这一步的产出文件；
+ * 别处加的是一张空的资源卡。
+ */
+ | {
+    kind: 'resource';
+}
+/** 一个输入节点（执行前问用户的问题）。 */
+ | {
+    kind: 'input';
+} | {
+    kind: 'preset';
+    id: string;
+} | {
+    kind: 'template';
+    name: string;
+};
+export declare function encodeStepSource(source: StepSource): string;
+/**
+ * 解码。`dataTransfer` 里可能是别的应用拖进来的任意内容，那不是错误而是"不归我们管"：
+ * 任何不认识的输入一律返回 `null`，**永不抛异常**。
+ *
+ * 用 `Map` 查键而不是直接读属性：`JSON.parse('{"__proto__":{"kind":"blank"}}')` 得到的对象
+ * 会顺着原型链读出一个它自己并没有的 `kind`；`Map.get` 只认自有键。
+ */
+export declare function decodeStepSource(raw: string | null | undefined): StepSource | null;

package/lib/types/client/model/nudge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * dsh-workflow-lite — 直角线分道（nudging）：不同颜色的线不叠在同一条道上。
+ *
+ * 每条直角线是各自挑路的（走廊、绕行折线），两条不同种类的线常常挑中同一条缝、同一条走廊，
+ * 叠成一根分不清。这里在挑完路之后统一过一遍（libavoid 的 orthogonal nudging 那一步的简化版）：
+ * - 找出**共线（或挨得不到一个道距）、又有一段重叠**的横段 / 竖段，连成一簇；
+ * - 同一种颜色（`group`）的线可以继续合在一条道上（本来就是一类线，合着反而清爽）；
+ * - 不同颜色的分到相邻的平行道上，道距 `GAP`，在这一簇所在的空当（上下 / 左右最近的卡片之间）里
+ *   尽量居中摆开，空当窄就把道距压小；
+ * - 只挪中间的段：接在连接点上的头尾两段不动，挪一段只是让它两头相邻的段变长 / 变短，线还是直角的；
+ * - 道的先后按线从哪边来、往哪边去排（从上面来的走上面那条道），尽量不因为分道再多出交叉。
+ *
+ * 纯计算，不碰 DOM。
+ * @module @xiaoso/dsh-workflow-lite/client/model/nudge
+ */
+import type { Rect } from './route.ts';
+export interface Track {
+    id: string;
+    /** 颜色类（同一类的线可以合道）。 */
+    group: string;
+    /** 折点（含两头）。 */
+    points: readonly [number, number][];
+}
+/**
+ * 给一组直角线分道。返回挪过的线的新折点（没挪的不在结果里）；传进来的数组不改。
+ * @param boxes - 卡片（道不能摆进卡片里）。
+ */
+export declare function nudge(tracks: readonly Track[], boxes: readonly Rect[]): Map<string, [number, number][]>;
+/** 走廊线上的一块条件牌子：挂在 `y` 这条走廊上，只能在 `from`..`to` 之间挪，原本想放在 `prefer`。 */
+export interface Chip {
+    id: string;
+    y: number;
+    from: number;
+    to: number;
+    prefer: number;
+    width: number;
+}
+/**
+ * 走廊上的条件牌子错开摆：两条线并排走同一段走廊时（比如同一对步骤之间的「通过」和「未通过」），
+ * 牌子原本落在同一个位置、一块压住另一块。按 id 依次摆，叠上了就沿着自己的走廊往两边挪，
+ * 挪到走廊尽头都放不下就留在原处。返回每块牌子中心的 x。
+ */
+export declare function placeChips(chips: readonly Chip[]): Map<string, number>;