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

package/lib/types/client/ui/WorkflowSwitcher.d.ts

@@ -0,0 +1,20 @@
+/**
+ * dsh-workflow-lite — 顶栏左边的工作流名字与它的下拉：切换、改名、删除、新建。
+ *
+ * 改名和删除挂在列表的每一行上（见 {@link WorkflowRow}），哪张都能直接改，不用先切过去；
+ * 底下只留跟「正开着的这张」有关的「从磁盘重新加载」和「新建」。
+ * 双击顶栏上的名字、或刚新建好时，名字就地变成输入框改正开着的这张。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/WorkflowSwitcher
+ */
+import type { Runs } from '../app/useRuns.ts';
+import type { Workflow } from '../app/useWorkflow.ts';
+import type { T } from '../i18n.ts';
+export interface WorkflowSwitcherProps {
+    t: T;
+    wf: Workflow;
+    /** 本会话的工作流实例（下拉里「本会话的实例」那一段）。 */
+    runs: Runs;
+    onOpenRun(id: string): void;
+}
+export declare function WorkflowSwitcher(props: WorkflowSwitcherProps): React.JSX.Element;

package/lib/types/client/ui/WorkflowView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * dsh-workflow-lite — 工作流视图（会话页的一个 tab）：把发动机、画布与各块面板接起来。
+ *
+ * 版式：画布铺满，顶栏、步骤库、属性面板、缩放条浮在上面。属性面板只在选中东西时出现。
+ * 键盘：快捷键挂在视图根上——视图内任何地方拿到焦点都能冒上来，又出不了这个视图
+ * （挂 window 会隔着整页抢宿主的按键）。输入框里一律让开。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/WorkflowView
+ */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { Desktop } from '../app/desktop.ts';
+import { type SessionBridge } from '../app/sessions.ts';
+import type { NS } from '../i18n.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+/** 客户端入口注入的业务面。 */
+export interface WorkflowViewInjected {
+    rpc: WorkflowLiteRpc;
+    /** 这个 tab 所在的会话。 */
+    sessionId?: string;
+    /** 会话列表与发消息（「执行」用）；宿主缺相应服务时不给。 */
+    sessions?: SessionBridge;
+    /** 用系统程序打开文件；宿主没有桌面能力时不给。 */
+    desktop?: Desktop;
+}
+/** 槽位给这个组件的完整 props。 */
+export type WorkflowViewProps = PropsRuntime<'conversation.view'> & PropsLocale<typeof NS> & WorkflowViewInjected;
+export declare function WorkflowView(props: WorkflowViewProps): React.JSX.Element;

package/lib/types/client/ui/lines.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 八种线的颜色：画布上的线、箭头、光带、线上的牌子，面板里的标签和图例都从这里取，
+ * 永远是同一个色。色值在 shell.module.css 的 `--wl-flow-*` / `--wl-io-*`。
+ * 输入 → 步骤（交回答）用一档中性的墨色：色环上七个色都占满了，再加一个彩色总会和某一个撞；
+ * 它另有第二重记号——点线、输入卡。
+ */
+/** 步骤之间的线按条件分四种：总是 / 通过 / 未通过 / 自定义条件。 */
+export type WhenKind = 'always' | 'pass' | 'fail' | 'custom';
+/** 连着文件或输入的线：整份写出 / 在原文件上更新 / 读取 / 交回答（输入 → 步骤）。 */
+export type Access = 'produce' | 'update' | 'read' | 'ask';
+export declare function whenKind(when: string | undefined): WhenKind;
+export declare const WHEN_COLOR: Record<WhenKind, string>;
+export declare const ACCESS_COLOR: Record<Access, string>;

package/lib/types/client/ui/primitives.d.ts

@@ -0,0 +1,119 @@
+/**
+ * dsh-workflow-lite — 小件：类名拼接、点外面关闭、分段选择、浮层。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/primitives
+ */
+import { type RefObject } from 'react';
+/** 拼类名，跳过假值。 */
+export declare function cx(...names: (string | false | null | undefined)[]): string;
+/**
+ * 在 `ref` 之外按下指针就关掉。
+ *
+ * 监听挂在 `document` 的**捕获**阶段：React Flow 会在自己的按下处理里拦截冒泡，
+ * 冒泡阶段的监听收不到"点在画布上"这一下。
+ */
+export declare function useDismiss(open: boolean, ref: RefObject<HTMLElement | null>, onClose: () => void): void;
+/**
+ * 触发器 + 浮层。浮层不走 portal：留在视图根的子树里，设计令牌照常继承。
+ * `Esc` 在这里消化掉（不再冒到视图根去取消画布上的选中）。
+ *
+ * `hold`：浮层里正有一件事没做完（行内改名、挂在某一行上的确认卡）——点外面先只结束那件事，
+ * 浮层留着，再点一下才收。浮层本身可聚焦（不进 Tab 序）：里面的按钮跟着一行被删掉时焦点有处可去，
+ * Esc 照样能收起。
+ */
+export declare function Popover(props: {
+    open: boolean;
+    onClose: () => void;
+    trigger: React.ReactNode;
+    children: React.ReactNode;
+    align?: 'start' | 'end';
+    up?: boolean;
+    className?: string;
+    label: string;
+    hold?: boolean;
+}): React.JSX.Element;
+/** 分段选择（单选）。选中格下面那块滑块靠 `transform` 滑过去。 */
+export declare function Segmented<V extends string>(props: {
+    label: string;
+    value: V;
+    /** `color`：选项前的小色点（比如条件的四种线色），和画布上对应的东西同色。 */
+    options: readonly {
+        value: V;
+        label: string;
+        color?: string;
+    }[];
+    onChange: (value: V) => void;
+    disabled?: boolean;
+    /** 每格的 `data-testid` 是 `${testId}-${value}`。 */
+    testId?: string;
+}): React.JSX.Element;
+export declare const ModalHostProvider: import("react").Provider<HTMLElement | null>;
+/**
+ * 模态框：遮罩 + 居中的一张卡。
+ *
+ * - 键盘事件一律在这里截住：React 的合成事件会顺着组件树（而不是 DOM 树）冒泡，不截的话
+ *   在模态框里按 Delete / Esc 会冒到视图根，删掉画布上选中的步骤。
+ * - Esc 与点遮罩都走 `onDismiss`；调用方据此决定"有没写完的改动时不关"。
+ * - 只有按下与松开都落在遮罩上才算点遮罩：在输入框里拖选文字、松手落在外面，不该把框关掉。
+ * - Tab 在框内循环；关掉后焦点还给打开它的那个按钮。
+ */
+export declare function Modal(props: {
+    label: string;
+    onDismiss(): void;
+    children: React.ReactNode;
+    className?: string;
+    testId?: string;
+}): React.JSX.Element;
+export type FloatState = 'off' | 'hover' | 'pinned';
+/**
+ * 悬停浮层的状态与摆位（「?」说明、画布连线上的交接卡片共用）。
+ *
+ * - 浮层挂到视图根（和模态框同一个挂载点）：不被滚动区裁掉，也不会把滚动区撑出滚动条；
+ *   画布缩放时字号也不跟着变小。
+ * - 鼠标可以从触发器移进浮层：离开触发器后稍等一下再收，进了浮层就不收；浮层接住指针，
+ *   里面的文字能选中复制，点击不会穿透到后面。
+ * - 在触发器与浮层之外按下指针、滚动、滚轮缩放画布都收起；Esc 只收浮层。
+ * - 先按"触发器正下方、左边对齐"放（`align: 'end'` 右边对齐；`'auto'` 触发器在视图右半边就右对齐），
+ *   量出高度后下面放不下就翻到上方，左右夹在视图里。
+ */
+export declare function useFloat<A extends HTMLElement>(options: {
+    openMs: number;
+    closeMs: number;
+    width: number;
+    align?: 'start' | 'end' | 'auto';
+    /** 与触发器的间距，缺省 6。 */
+    gap?: number;
+}): {
+    state: FloatState;
+    setState: (next: FloatState | ((current: FloatState) => FloatState)) => void;
+    anchorRef: RefObject<A>;
+    panelRef: RefObject<HTMLDivElement>;
+    /** 取消还没生效的悬停开 / 关。 */
+    cancel: () => void;
+    /** 悬停触发：挂到触发器上。 */
+    hoverProps: {
+        onPointerEnter: () => void;
+        onPointerLeave: () => void;
+    };
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    /** 把浮层内容包一层定位壳，挂到视图根。 */
+    render: (props: {
+        className: string;
+        testId?: string | undefined;
+        label?: string;
+        /** 默认 `tooltip`；二次确认这类要操作的浮层用 `alertdialog`。 */
+        role?: 'tooltip' | 'alertdialog';
+        children: React.ReactNode;
+    }) => React.ReactNode;
+};
+/**
+ * 「?」说明：平时只占一个小图标，悬停 / 聚焦 / 点击时浮出一段说明（浮层行为见 {@link useFloat}）。
+ * 点「?」钉住（触屏也能用），点别处或按 Esc 收起。
+ */
+export declare function HelpTip(props: {
+    label: string;
+    children: React.ReactNode;
+    testId?: string;
+}): React.JSX.Element;
+/** 把一段文字写进剪贴板；环境不允许就安静地失败。 */
+export declare function copyText(text: string): Promise<boolean>;

package/lib/types/client/ui/resourceUi.d.ts

@@ -0,0 +1,49 @@
+/**
+ * dsh-workflow-lite — 资源在界面上的样子：每种内容的图标与名字、一项内容的简短写法、起名与查重。
+ *
+ * 画布的资源卡、属性面板、实例视图都从这里取，同一种内容到哪儿都是同一个图标、同一种写法。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/resourceUi
+ */
+import type { ResourceItem, ResourceKind, WorkflowDocument, WorkflowNode } from '../../shared/types.ts';
+import type { HostSkillEntry } from '../../shared/wire.ts';
+import type { LocaleKey } from '../i18n.ts';
+import type { IconName } from './Icon.tsx';
+/** 呈现顺序 = 「添加」菜单里的顺序。 */
+export declare const KIND_ORDER: readonly ResourceKind[];
+export declare const KIND_ICON: Record<ResourceKind, IconName>;
+export declare const KIND_LABEL: Record<ResourceKind, LocaleKey>;
+/**
+ * 卡片上一项的写法：文件与文件夹取最后一段，网址去掉协议，自定义取第一行
+ * （自定义文字常是 Markdown：去掉行首的标题 `#`、列表 `-`、引用 `>` 记号）。
+ */
+export declare function itemText(item: ResourceItem): string;
+/** 面板清单里一项的名字：网址只取主机名（整条网址放在下面一行），其余同 {@link itemText}。 */
+export declare function itemName(item: ResourceItem): string;
+/**
+ * 面板清单里一项的位置（名字下面那一行）：文件与文件夹是路径（相对路径有步骤写它时换成产出根目录下的
+ * 实际位置），网址是整条网址；Skill 与自定义没有位置（空串，界面上写种类）。
+ */
+export declare function itemLocation(item: ResourceItem, root: string | undefined, written: boolean): {
+    text: string;
+    mono: boolean;
+};
+/** 往资源里加几项：空值照加（等着填），和已有的重复的跳过，满了就停。 */
+export declare function addItems(items: readonly ResourceItem[], fresh: readonly ResourceItem[], max: number): ResourceItem[];
+/** 筛选 skill：名字或说明里有这几个字（不分大小写）。 */
+export declare function filterSkills(skills: readonly HostSkillEntry[], filter: string): readonly HostSkillEntry[];
+/** skill 从哪来，给人看的两种说法（清单里的小签、预览里的全称）；不认识的来源原样给。 */
+export declare function skillSource(source: string, t: (key: LocaleKey) => string): {
+    short: string;
+    full: string;
+};
+/** 节点的显示名：步骤取名称，资源取名字（没有就第一项），输入取问题。 */
+export declare function stepName(node: WorkflowNode | undefined, fallback: string): string;
+/** 路径的最后一段（卡片标题里放不下整条路径）。 */
+export declare function baseName(path: string): string;
+/** 图里没被资源占用的文件路径：`x.md` 被占了就 `x-2.md`、`x-3.md`… */
+export declare function freeFilePath(doc: WorkflowDocument, want: string): string;
+/** 同一个资源里两项是不是重复（种类相同、值规范化后相同）。 */
+export declare function sameItem(a: ResourceItem, b: ResourceItem): boolean;
+/** 是不是同一个节点。 */
+export declare function sameId(a: string, b: string): boolean;

package/lib/types/client/ui/stepIcons.d.ts

@@ -0,0 +1,10 @@
+/**
+ * dsh-workflow-lite — 步骤卡的图标库：每个图标的笔画（24 栅格、描边，和 `Icon.tsx` 同一套画法）。
+ *
+ * 名字清单在 `shared/appearance.ts`（host 也要用它校验、给新步骤挑样子）；这里用
+ * `Record<StepIcon, string>` 对齐，清单里加了名字却忘了画，类型检查就过不去。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/stepIcons
+ */
+import type { StepIcon } from '../../shared/appearance.ts';
+export declare const STEP_ICON_PATHS: Record<StepIcon, string>;

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

@@ -0,0 +1,17 @@
+/**
+ * dsh-workflow-lite — 按需 skill `workflow-authoring`：怎么设计一张工作流图。
+ *
+ * 工具描述只列能力（有哪些 action、参数是什么）；步骤怎么拆、产物怎么传、资源说明怎么写、
+ * 建完怎么自检，都放在这里，模型要建图、改图时才读（目录里只常驻一句摘要）。
+ * 内容来自真实使用里反复出现的问题：步骤拆得太碎、中间产物没接给下游、提示词说要改的文件图里没连、
+ * 循环跑几轮后台账和状态文档越写越长、每轮写法都不一样、自检时反复编译留下一堆实例。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/authoringSkill
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const AUTHORING_SKILL = "workflow-authoring";
+/**
+ * 注册 skill；`skills` 服务不在时由调用方跳过。
+ * @returns 注销器。
+ */
+export declare function registerAuthoringSkill(ctx: Context): () => void;

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

@@ -0,0 +1,54 @@
+/**
+ * dsh-workflow-lite — 配置面。
+ *
+ * 六个键，默认值全部写在 schema 里（**不硬编码在代码里**）。字段类型是
+ * `Volatile`：设置表单投影的正是这些字段，写入落进当前 profile 的 Cordis patch，
+ * 运行中的插件读的是**活引用**——一次配置写入就地更新它，不重挂插件。
+ *
+ * 部署相关的取值一律走这里：`dataDir`（数据根）、`maxNodes`、`maxResultBytes`
+ * （单次返回字节上限）、`saveDebounceMs`、`routePrefix`、`installSkill`。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/config
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** 设置命名空间——同一个 kebab-case 串也是 locale 的 NS。 */
+export declare const WORKFLOW_LITE_SETTINGS_NS = "workflow-lite";
+/** 插件在 profile 里的那一行的 id（`cordis.patch.yml` 的 `insert.id`）。 */
+export declare const WORKFLOW_LITE_ROW_ID = "workflow-lite";
+/** 解析后的活配置。 */
+export interface WorkflowLiteSettings {
+    /** 数据根目录。`workflows/`、`templates/` 与 `.dispatch/` 都在它下面。 */
+    dataDir: Volatile<string>;
+    /** 画布改动落盘的防抖毫秒数。**拖动过程中不写盘，指针停稳后才写一次。** */
+    saveDebounceMs: Volatile<number>;
+    /** 单图节点数上限。超出：落盘允许、自动布局不跑、**编译挡住**。 */
+    maxNodes: Volatile<number>;
+    /** 单次工具 / RPC 返回的字节上限。超限**报错而不截断**。 */
+    maxResultBytes: Volatile<number>;
+    /** 画布 ↔ host 的同源路由前缀。插件不自开端口。 */
+    routePrefix: Volatile<string>;
+    /** 是否随插件注册按需 skill `workflow-authoring`（设计图）与 `workflow-run-state`（运行状态）。 */
+    installSkill: Volatile<boolean>;
+}
+/**
+ * 运行期 schema。字段一律 `volatile()`（只有这类字段设置表单才能编辑），
+ * 并且都带**约束**——配错了要响亮失败，不要静默取一个坏值。
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    dataDir: z<string, string, "volatile-defined">;
+    saveDebounceMs: z<number, number, "volatile-defined">;
+    maxNodes: z<number, number, "volatile-defined">;
+    maxResultBytes: z<number, number, "volatile-defined">;
+    routePrefix: z<string, string, "volatile-defined">;
+    installSkill: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    dataDir: z<string, string, "volatile-defined">;
+    saveDebounceMs: z<number, number, "volatile-defined">;
+    maxNodes: z<number, number, "volatile-defined">;
+    maxResultBytes: z<number, number, "volatile-defined">;
+    routePrefix: z<string, string, "volatile-defined">;
+    installSkill: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** 六个键的名字（测试与文档用，避免两处各写一遍）。 */
+export declare const CONFIG_KEYS: readonly ["dataDir", "saveDebounceMs", "maxNodes", "maxResultBytes", "routePrefix", "installSkill"];

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

@@ -0,0 +1,69 @@
+/**
+ * dsh-workflow-lite — 主机上的东西：资源节点「选文件 / 选文件夹 / 选 Skill」时列给画布看。
+ *
+ * - {@link listHostDir}：列一个目录里有什么（只给名字和是不是目录，**不读内容**），外加几个可以跳去的根；
+ * - {@link listSkills}：会话里的 agent 能用的 skill（只列模型能用的）；{@link readSkill}：读一个的全文。
+ *
+ * 只读。画布那头是本机用户自己在选路径，选中的路径原样进图，执行时由模型自己去读。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/hostFs
+ */
+import type { HostListResponse, HostSkillResponse, HostSkillsResponse } from '../shared/wire.ts';
+import type { Outcome } from './store/repository.ts';
+/**
+ * 列一个目录。`path` 缺省 = `cwd`（会话的工作区），再缺省 = 用户主目录；相对路径按 `cwd` 解析。
+ */
+export declare function listHostDir(request: {
+    path?: string;
+    cwd?: string;
+}): Promise<Outcome<HostListResponse>>;
+/** 一条 skill 的摘要（`ctx.skills.list()` 给的那几样）。 */
+interface SkillSummaryLike {
+    name: string;
+    description: string;
+    source: string;
+    /** SKILL.md 的绝对路径；插件运行时注册的 skill 没有。 */
+    path?: string;
+    whenToUse?: string;
+    invocation: {
+        modelInvocable: boolean;
+    };
+}
+/** 读 skill 时的作用域与工作区（`scope` 是 DSH 的不透明作用域键）。 */
+interface SkillLookup {
+    cwd?: string;
+    scope?: object;
+}
+/** `ctx.skills` 用到的那一点（只借形状，不 import 运行时）。 */
+export interface SkillLister {
+    list(options: SkillLookup): Promise<readonly SkillSummaryLike[]>;
+    get(name: string, options: SkillLookup): Promise<(SkillSummaryLike & {
+        content: string;
+    }) | undefined>;
+}
+/**
+ * 以谁的眼光看 skill：DSH 的本地 skill（项目的 `.dsh/skills`、`~/.agents/skills`…）是挂在
+ * **agent 预设**底下的，只有带上那个预设的作用域才读得到；不带作用域只剩全局那一层（内置的、
+ * 插件注册的）。读完调 `release` 还回作用域。
+ */
+export interface SkillView {
+    skills: SkillLister;
+    scope?: object;
+    release?: () => Promise<void>;
+}
+/** 给一个会话（可以不给）找出看 skill 的视角；没装 skill 服务回 `undefined`。 */
+export type SkillViewer = (session: string | undefined) => Promise<SkillView | undefined>;
+/**
+ * 会话里的 agent 能用的 skill（只列模型能用的，执行时是模型去加载它们）；没装 skill 服务就是空的。
+ */
+export declare function listSkills(viewer: SkillViewer | undefined, request: {
+    cwd?: string;
+    session?: string;
+}): Promise<HostSkillsResponse>;
+/** 读一个 skill 的全文（SKILL.md 去掉头部元数据后的正文），给画布预览。 */
+export declare function readSkill(viewer: SkillViewer | undefined, request: {
+    name: string;
+    cwd?: string;
+    session?: string;
+}): Promise<Outcome<HostSkillResponse>>;
+export {};

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

@@ -0,0 +1,68 @@
+/**
+ * dsh-workflow-lite — 编译编排。
+ *
+ * 纯函数编译器（`shared/compile.ts`）不认识磁盘；这一层负责**把它需要的东西凑齐**：
+ * 图（从仓储读，或实例的快照）、任务描述的路径、以及该图的校验结论（进 ⑥ 段）。
+ *
+ * 计划永远对着一个**工作流实例**出：
+ * - 给了实例（`options.instance`）：任务描述写进实例目录的 `tasks/`，产出根目录里的 `{instance}`
+ *   换成实例 id，开了「记录运行状态」就带上「运行状态」段——这就是模型拿到的那份；
+ * - 没给（画布预览、整卷版）：同一份计划，只是实例 id 还没有，路径与段落里留着 `{instance}`，
+ *   不写任何文件。预览与执行时拿到的内容逐段对得上。
+ *
+ * 失败姿态：有编译级问题时 `plan` 为空串、`problems` 必填，
+ * **绝不返回一份残缺计划**；写任务描述失败 ⇒ `io_error`（图本身没坏，不该是 `invalid_args`）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/plan
+ */
+import type { InputAnswer, PlanId, ToolWarning, ValidationProblem, WorkflowDocument } from '../shared/types.ts';
+import { type Outcome, type Repository } from './store/repository.ts';
+/** 计划对着的实例。 */
+export interface PlanInstance {
+    id: string;
+    /** 实例目录（任务描述 `tasks/`、状态 `state.yaml`、默认产出 `out/` 都在这里）。 */
+    dir: string;
+    /** 记运行状态：计划末尾带「运行状态」段。 */
+    tracked: boolean;
+}
+/** 编译入参。 */
+export interface CompileOptions {
+    /** `true` = 整卷版（内联正文，给人读）；缺省 = 派发版。 */
+    full?: boolean;
+    goal?: string;
+    /** 实例：给了就按它出计划、把任务描述写进实例目录；不给是预览（留 `{instance}`，不写文件）。 */
+    instance?: PlanInstance;
+    /**
+     * 用户对输入节点的回答。不给 = 预览（回答处写「执行时填写」）；给了 = 真的要执行
+     * （没回答的用默认值，必填的还空着就是编译级）。
+     */
+    answers?: Readonly<Record<string, InputAnswer>>;
+}
+export interface CompileBundle {
+    /** 内容哈希前 8 位（实例的快照把实例 id 定进了产出根目录，所以每个实例各不相同）。 */
+    planId: PlanId;
+    /** 派发计划（或整卷版）文本；有编译级问题时为空串。 */
+    plan: string;
+    /** **只装编译级问题**（阻塞编译的那几条）。 */
+    problems: ValidationProblem[];
+    /** 警告与提示（非阻塞），含该图读入阶段报出的那些。 */
+    warnings: ToolWarning[];
+    /** 任务描述路径（步骤 id → 绝对路径）；预览时路径里是 `{instance}`。 */
+    payloadPaths: Record<string, string>;
+}
+/**
+ * 编译一张图（仓储里的模板）。
+ *
+ * - 保存级问题 ⇒ `blocked`（图都加载不了，谈不上编译）；图不存在 ⇒ `not_found`。
+ * - 编译级问题 ⇒ 成功返回但 `plan` 为空串、`problems` 非空，**且不写文件**。
+ */
+export declare function compileWorkflow(repository: Repository, dataDir: string, name: string, options?: CompileOptions, 
+/** 执行者的工作区根；由调用方从会话取（工具从 `exec` 取，RPC 从前端给）。 */
+cwd?: string): Promise<Outcome<CompileBundle>>;
+/**
+ * 编译一份已经读进来的图（工作流实例的快照走这里：它不在 `workflows/` 里）。
+ * @param problems - 该图的校验结论（进 ⑥ 段与 `warnings`）。
+ */
+export declare function compileDocument(dataDir: string, name: string, document: WorkflowDocument, problems: readonly ValidationProblem[], options?: CompileOptions, cwd?: string): Promise<Outcome<CompileBundle>>;
+/** 该图的警告与提示（画布校验面板用）。 */
+export declare function nonBlockingProblems(problems: readonly ValidationProblem[]): ValidationProblem[];

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

@@ -0,0 +1,57 @@
+/**
+ * dsh-workflow-lite — 工作流中心「设置」页的后端：经 DSH 的设置服务（`ctx.settings`）读写本插件自己那一行配置。
+ *
+ * - 只露 {@link PLUGIN_CONFIG_KEYS} 那几项；`routePrefix` 这类接线细节不给人改。
+ * - 写入走设置服务的路径编辑（`mutate`）：它按完整 Config 校验、落进当前 profile 的 patch、
+ *   就地更新运行中的活配置；带修订号，别人先改过就拒绝，不悄悄覆盖。
+ * - 设置服务不在（精简的 profile）时只读：页面照样显示现值，告诉人这里改不了。
+ *
+ * 本插件在 profile 里那一行的 id 通常就是 `workflow-lite`（`cordis.patch.yml` 里写的）；
+ * 有人手动换了 id 时，退回去找「字段正好是这几项」的那一行。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/pluginConfig
+ */
+import { type PluginConfigValues, type PluginConfigView } from '../shared/wire.ts';
+/** 用到的那一小截设置服务（`@deepseek-ai/dsh-settings` 的 `SettingsForms`）。 */
+export interface SettingsPort {
+    readonly writable: boolean;
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): readonly SettingsRow[];
+    mutate(ns: string, ops: readonly ({
+        op: 'set';
+        path: readonly string[];
+        value: unknown;
+    } | {
+        op: 'unset';
+        path: readonly string[];
+    })[], expectedRevision?: number): Promise<void>;
+}
+export interface SettingsRow {
+    ns: string;
+    revision: number;
+    value: unknown;
+    base?: unknown;
+    user?: unknown;
+}
+type Outcome<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** 设置服务不在时页面要的现值（从活配置读）。 */
+export type LiveValues = () => PluginConfigValues;
+export declare function readPluginConfig(port: SettingsPort | undefined, live: LiveValues): PluginConfigView;
+export declare function writePluginConfig(port: SettingsPort | undefined, live: LiveValues, 
+/** 线上来的原样（键名、值都还没核对过）。 */
+write: {
+    revision: number;
+    set?: Record<string, unknown>;
+    reset?: readonly string[];
+}): Promise<Outcome<PluginConfigView>>;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * dsh-workflow-lite — 画布的后端路由。
+ *
+ * 一个 endpoint 一条精确 Fetch 路由，挂在共享 Connection 的 `/api` 通道上
+ * （与生态里其它插件同一条路）。载波负责 Host/Origin + 浏览器会话策略，
+ * 我们只解码标准 `client-request` 信封、分派、再按标准 `server-response` 回。
+ *
+ * 注册走 `ctx.inject(['connection'])` 的子上下文——这样**插件在没有 web 的 profile 里
+ * 也能只带工具起来**（RPC 是画布专用，缺它不该让整个插件停摆）。
+ *
+ * 入参一律**从原始记录里逐字段读**（不做类型断言）；图文档走 `normalizeDocument`
+ * 做形状归一，坏形状在这里就被挡成 `invalid_args`，不会渗进仓储。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/rpc
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SkillViewer } from './hostFs.ts';
+import { type LiveValues, type SettingsPort } from './pluginConfig.ts';
+import type { RunService } from './runs/service.ts';
+import { type Repository } from './store/repository.ts';
+/** 路由需要的活依赖。 */
+export interface RpcDeps {
+    repository: Repository;
+    dataDir: () => string;
+    /** 画布要用的两个活配置值（`graph/list` 一并回给它，见 `GraphListResponse`）。 */
+    limits: () => {
+        maxNodes: number;
+        saveDebounceMs: number;
+    };
+    /** 工作流实例（`run/*`）。 */
+    runs: RunService;
+    /** 看 DSH 的 skill（选 Skill、预览 SKILL.md 用）；没给就当没装 skill 服务。 */
+    skills?: SkillViewer;
+    /** 「设置」页：DSH 的设置服务（不在时回 `undefined`，页面只读）与活配置的现值。 */
+    config: {
+        port: () => SettingsPort | undefined;
+        live: LiveValues;
+    };
+}
+/**
+ * 注册全部画布路由。
+ * @param ctx - **已绑定 `connection`** 的子上下文。
+ * @param deps - 仓储与数据根。
+ */
+export declare function registerWorkflowLiteRpc(ctx: Context, deps: RpcDeps): void;

package/lib/types/host/runs/files.d.ts

@@ -0,0 +1,37 @@
+/**
+ * dsh-workflow-lite — 实例里的文件：给画布看一眼（资源面板与查看框）。
+ *
+ * 只读、只认这个实例名下的文件：要么是快照里某个资源的文件项，要么是落在实例工作区里的相对路径
+ * （模型在状态文件 `outputs` 里写的那些）。随手传进来的工作区外路径一律拒绝——这条路由不是通用的读文件口子。
+ *
+ * 读多少：小文本整份回去（`RUN_FILE_TEXT_MAX`），大了只回元信息让前端说"太大了"；
+ * 前 8 KB 里有 NUL 字节就当二进制。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/runs/files
+ */
+import type { InstanceRecord } from '../../shared/runState.ts';
+import type { WorkflowDocument } from '../../shared/types.ts';
+import { type RunFileResponse } from '../../shared/wire.ts';
+import type { Outcome } from '../store/repository.ts';
+/** 要看哪份：快照里某个资源的第几项，或实例工作区里的相对路径。 */
+export type RunFileTarget = {
+    node: string;
+    item: number;
+} | {
+    path: string;
+};
+/**
+ * 快照里一个资源的第几项实际在哪（还没拼工作区）；不是文件 / 文件夹就是 `null`。
+ * 相对路径：有步骤写这个资源时在产出根目录下，只被读时相对工作区。
+ */
+export declare function itemLocation(document: WorkflowDocument, node: string, item: number): string | null;
+/**
+ * 把目标解析成绝对路径与给人看的相对路径；越界或找不到就是错误。
+ * @param underRoot - 相对路径按产出根目录解析（模型报告产出时可能是相对根目录写的）。
+ */
+export declare function resolveRunFile(record: InstanceRecord, document: WorkflowDocument, target: RunFileTarget, underRoot?: boolean): Outcome<{
+    full: string;
+    display: string;
+}>;
+/** 读一份文件给画布：小文本带正文，其余（含文件夹）只有元信息。 */
+export declare function readRunFile(full: string, display: string): Promise<RunFileResponse>;

package/lib/types/host/runs/notice.d.ts

@@ -0,0 +1,21 @@
+/**
+ * dsh-workflow-lite — 把"用户修改了运行状态"送进会话。
+ *
+ * 和 `dsh-task-runner` 的后台任务完成通知同一套机制：一条 `form: 'notice'` 的用户角色消息，
+ * 对话里显示成一行摘要，展开就是完整的注入内容（用户看得到模型收到了什么）。
+ * 用 `steer` 投递：会话空闲就开一轮，正在跑就在下一步接上。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/runs/notice
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { Notify } from './service.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'workflow-lite': {
+            kind: 'workflow-lite';
+        } & ContextFormed;
+    }
+}
+/** 造一个投递函数：会话的 agent 不在运行时回 `false`（调用方把通知暂存起来）。 */
+export declare function createNotify(ctx: Context): Notify;