dsh-task-dispatch-table 0.0.0 → 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,79 @@
+import z from '@deepseek-ai/schemastery';
+export interface PluginConfig {
+    /** SQLite 状态库绝对路径；空串 = 宿主数据根 storages/dsh-task-dispatch-table/state.db（决策 14）。 */
+    statePath: string;
+    /** tick 周期（毫秒）。 */
+    tickMs: number;
+    /** dispatched 等待 session/created 的宽限期（毫秒）（state-machine §4）。 */
+    dispatchGraceMs: number;
+    /** running 租约时长（毫秒）（state-machine §4，默认 30min）。 */
+    leaseMs: number;
+    /** unknown 只观察不动作的宽限期（毫秒）（state-machine §4，默认 5min）。 */
+    unknownGraceMs: number;
+    /** 任务定义目录（*.json）。相对路径相对宿主进程 cwd 解析。 */
+    tasksDir: string;
+    /** 内嵌任务表 JSON 数组（临时 UI，决策 16 v1 补充）：非空时优先于 tasksDir。 */
+    tasksInline: string;
+    /** 调试快照 JSON（临时调试通道，决策 16 例外）：宿主写入、配置页只读展示，非用户设置。 */
+    debugSnapshot: string;
+    /** 插件级默认 provider（决策 22 漏斗第②层）：与 defaultModel 成对；留空则漏到宿主默认。 */
+    defaultProvider: string;
+    /** 插件级默认 model（决策 22 漏斗第②层）：与 defaultProvider 成对；留空则漏到宿主默认。 */
+    defaultModel: string;
+    /** task_log 保留期（天）：到期行由 tick 内 purgeLog 清除（决策 32）。 */
+    logRetentionDays: number;
+    /**
+     * ⚠️ **执行记录（task_instances + task_events）永久保留，没有保留期字段**——
+     * 历史是用来查的、不该被清（用户 2026-10-08 拍板，原 `historyRetentionDays` 与 `purgeHistory` 一并删除）。
+     */
+    /** 上传临时区保留期（天）：到期文件由 tick 内清道夫删除（默认 7）。 */
+    attachmentTmpRetentionDays: number;
+}
+/**
+ * **系统默认值**（全量，含字符串路径类）—— `Config` schema 与设置页「用户没设时显示什么」的唯一真源。
+ *
+ * 2026-10-08：此前只有 `ConfigDefaults`（7 个计时/保留期字段），字符串字段的默认值只写在 schema 里
+ * （`statePath:''` / `tasksDir:'tasks'` / 两个默认模型 `''`）⇒ 设置页要显示「系统默认值」时拿不到，
+ * 只能在前端另抄一份（必然分叉）。故合并成一份全量对象，schema 的 `.default()` 全部引用它。
+ */
+export declare const CONFIG_DEFAULTS: PluginConfig;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    statePath: z<string, string, "defined">;
+    tickMs: z<number, number, "defined">;
+    dispatchGraceMs: z<number, number, "defined">;
+    leaseMs: z<number, number, "defined">;
+    unknownGraceMs: z<number, number, "defined">;
+    tasksDir: z<string, string, "defined">;
+    tasksInline: z<string, string, "defined">;
+    debugSnapshot: z<string, string, "defined">;
+    defaultProvider: z<string, string, "defined">;
+    defaultModel: z<string, string, "defined">;
+    logRetentionDays: z<number, number, "defined">;
+    attachmentTmpRetentionDays: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    statePath: z<string, string, "defined">;
+    tickMs: z<number, number, "defined">;
+    dispatchGraceMs: z<number, number, "defined">;
+    leaseMs: z<number, number, "defined">;
+    unknownGraceMs: z<number, number, "defined">;
+    tasksDir: z<string, string, "defined">;
+    tasksInline: z<string, string, "defined">;
+    debugSnapshot: z<string, string, "defined">;
+    defaultProvider: z<string, string, "defined">;
+    defaultModel: z<string, string, "defined">;
+    logRetentionDays: z<number, number, "defined">;
+    attachmentTmpRetentionDays: z<number, number, "defined">;
+}>>, "plain">;
+/**
+ * rc.1 volatile 字段的解析结果是**带 get() 的引用**（非纯值）；读取时解包（与参考插件
+ * dsh-task-board 的 readConfigField 同款）。非 volatile 字段原样返回；undefined/null 回落 fallback。
+ * @param field - 配置字段（可能是 Volatile 引用或纯值）。
+ * @param fallback - 字段缺失时的回落值。
+ */
+export declare function readConfigField<T>(field: unknown, fallback: T): T;
+/**
+ * 状态库路径（决策 14）：配置覆盖 > 宿主数据根 storages/dsh-task-dispatch-table/state.db。
+ * 宿主数据根解析复刻 packages/util/home-paths/src/index.ts:87-100：配置路径 > $DSH_HOME > ~/.dsh。
+ * 放 config.ts 而非 index.ts：scheduler/submit 也要用（避免 index 循环导入）。
+ */
+export declare function resolveStatePath(statePath: string): string;

package/dist/config.js

@@ -0,0 +1,80 @@
+// 插件配置：schemastery z schema 一份两用——patch Config 导出 + ctx.settings 命名空间。
+// ⚠️ 升到 @deepseek-ai/schemastery ^3.18.4：rc.1 设置系统（SettingsForms）要求运行时可写字段
+// 标 .volatile()（3.18.2 无此方法）；该版本与 dsh 0.1.7-rc.1 线一致（参考插件即依赖 ^3.18.4）。
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+/**
+ * **系统默认值**（全量，含字符串路径类）—— `Config` schema 与设置页「用户没设时显示什么」的唯一真源。
+ *
+ * 2026-10-08：此前只有 `ConfigDefaults`（7 个计时/保留期字段），字符串字段的默认值只写在 schema 里
+ * （`statePath:''` / `tasksDir:'tasks'` / 两个默认模型 `''`）⇒ 设置页要显示「系统默认值」时拿不到，
+ * 只能在前端另抄一份（必然分叉）。故合并成一份全量对象，schema 的 `.default()` 全部引用它。
+ */
+export const CONFIG_DEFAULTS = {
+    statePath: '',
+    tasksDir: 'tasks',
+    tasksInline: '',
+    debugSnapshot: '',
+    defaultProvider: '',
+    defaultModel: '',
+    tickMs: 60_000,
+    dispatchGraceMs: 60_000,
+    leaseMs: 30 * 60_000,
+    unknownGraceMs: 5 * 60_000,
+    logRetentionDays: 30,
+    attachmentTmpRetentionDays: 7,
+};
+// ⚠️ rc.1（0.1.7-rc.1）约束：宿主插件配置字段**不能标 .volatile()**。
+// 实测根因（set717/lib/index.js:417 + types/index.js:368-380）：configForms 的读写都要求字段
+// volatile，且 describe() 只投影 volatileForm(schema)（即只有 volatile 字段才暴露给客户端）；
+// 但宿主 Loader 会把 volatile 字段的默认按 `{}` 提交进 profile，重装后 z.number()/z.string()
+// 校验失败 → entry 不激活（日志 `$.tickMs expected number but got [object Object]`）。
+// 故宿主插件配置一律为静态字段；运行时数据（快照 / 任务表回写）改走宿主服务
+// `ctx.set('taskDispatchTable', ...)`，客户端经 `ctx.get('remote').taskDispatchTable` 取
+// （参考插件即靠 `ctx.get('remote')` 调宿主服务，不走 configForms）。
+export const Config = z.object({
+    statePath: z.string().default(CONFIG_DEFAULTS.statePath),
+    tickMs: z.number().default(CONFIG_DEFAULTS.tickMs),
+    dispatchGraceMs: z.number().default(CONFIG_DEFAULTS.dispatchGraceMs),
+    leaseMs: z.number().default(CONFIG_DEFAULTS.leaseMs),
+    unknownGraceMs: z.number().default(CONFIG_DEFAULTS.unknownGraceMs),
+    tasksDir: z.string().default(CONFIG_DEFAULTS.tasksDir),
+    tasksInline: z.string().role('textarea').default(CONFIG_DEFAULTS.tasksInline),
+    // 调试快照：运行时数据，不进 Config；宿主经 taskDispatchTable.getSnapshot() 暴露给客户端。
+    debugSnapshot: z.string().default(CONFIG_DEFAULTS.debugSnapshot),
+    // 决策 22 漏斗第②层：留空 = 未配，派发时漏到下一层。解析结果只用于本次派发，不回写本字段。
+    defaultProvider: z.string().default(CONFIG_DEFAULTS.defaultProvider),
+    defaultModel: z.string().default(CONFIG_DEFAULTS.defaultModel),
+    logRetentionDays: z.number().min(1).default(CONFIG_DEFAULTS.logRetentionDays),
+    attachmentTmpRetentionDays: z.number().min(1).default(CONFIG_DEFAULTS.attachmentTmpRetentionDays),
+});
+/**
+ * rc.1 volatile 字段的解析结果是**带 get() 的引用**（非纯值）；读取时解包（与参考插件
+ * dsh-task-board 的 readConfigField 同款）。非 volatile 字段原样返回；undefined/null 回落 fallback。
+ * @param field - 配置字段（可能是 Volatile 引用或纯值）。
+ * @param fallback - 字段缺失时的回落值。
+ */
+export function readConfigField(field, fallback) {
+    if (field === undefined || field === null)
+        return fallback;
+    if (typeof field === 'object' && typeof field.get === 'function') {
+        return field.get();
+    }
+    return field;
+}
+/**
+ * 状态库路径（决策 14）：配置覆盖 > 宿主数据根 storages/dsh-task-dispatch-table/state.db。
+ * 宿主数据根解析复刻 packages/util/home-paths/src/index.ts:87-100：配置路径 > $DSH_HOME > ~/.dsh。
+ * 放 config.ts 而非 index.ts：scheduler/submit 也要用（避免 index 循环导入）。
+ */
+export function resolveStatePath(statePath) {
+    if (statePath.trim().length > 0)
+        return resolve(statePath);
+    const raw = process.env['DSH_HOME'];
+    const selected = raw !== undefined && raw.trim().length > 0 ? raw : join(homedir(), '.dsh');
+    const home = selected === '~' || selected.startsWith('~/')
+        ? join(homedir(), selected.slice(selected.length === 1 ? 1 : 2))
+        : selected;
+    return join(resolve(home), 'storages', 'dsh-task-dispatch-table', 'state.db');
+}

package/dist/deps.d.ts

@@ -0,0 +1,25 @@
+/** 一条已解析的上游依赖：Loop A 判定通过时固化，Loop B 只读不重判。 */
+export interface ResolvedDependency {
+    /** 上游任务 id（depends_on.task 原值）。 */
+    task: string;
+    semantics: 'same_period' | 'latest_success';
+    /** 判定通过那一刻命中的上游实例 id。 */
+    instanceId: string;
+    /** 上游实例的计划时刻（ISO）。 */
+    scheduledAt: string;
+    /** 上游实例的会话 id（无则 null）。 */
+    sessionId: string | null;
+    /** 上游实例快照的工作区 path（产出相对路径的绝对化基准）；上游旧行无快照为 null。 */
+    workspacePath: string | null;
+    /** 上游回执声明并校验过的产出（相对上游工作区；未声明为空数组）。目录以尾斜杠结尾。 */
+    outputs: string[];
+}
+/** 解析 resolvedDeps：字段缺失（旧行）⇒ undefined；任一条形状不对 ⇒ 整组丢弃（不让坏数据进 UI）。 */
+export declare function parseResolvedDeps(raw: unknown): ResolvedDependency[] | undefined;
+/**
+ * 实例快照 JSON → 已解析的上游依赖清单（**客户端便捷入口**）。
+ * 与服务端 `parseInstanceSnapshot` 同一套校验，但**不强求整份快照合法**——
+ * 客户端只想看「接收了什么」，快照里别的字段缺了不该让这一块消失。
+ * 空 / 坏 JSON / 旧行（无 resolvedDeps）⇒ `[]`（调用方按「无上游」渲染，不显示该区）。
+ */
+export declare function resolvedDepsOf(raw: string | null): ResolvedDependency[];

package/dist/deps.js

@@ -0,0 +1,54 @@
+// 依赖快照（决策 43）的中立模块：**零运行时依赖**（不碰 node:* / sqlite），
+// 服务端（store.ts / scheduler.ts）与客户端（会话弹窗「接收」区）共用同一份解析逻辑
+// ——同一机制只解释一次，不允许两处各写一份形状校验。
+//
+// 语义：Loop A 判定通过的**那一刻**把命中的上游实例（id + 产出）冻结进执行记录快照，
+// Loop B（发动 / 重试 / 追问 / 回执裁决）只读，不复判 ⇒ 下游拿到的永远是判定依据那一份。
+/** 解析 resolvedDeps：字段缺失（旧行）⇒ undefined；任一条形状不对 ⇒ 整组丢弃（不让坏数据进 UI）。 */
+export function parseResolvedDeps(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== 'object' || item === null)
+            return undefined;
+        const d = item;
+        if (typeof d.task !== 'string' || typeof d.instanceId !== 'string' || typeof d.scheduledAt !== 'string'
+            || (d.semantics !== 'same_period' && d.semantics !== 'latest_success')
+            || (d.sessionId !== null && typeof d.sessionId !== 'string')
+            || (d.workspacePath !== null && typeof d.workspacePath !== 'string')
+            || !Array.isArray(d.outputs))
+            return undefined;
+        out.push({
+            task: d.task,
+            semantics: d.semantics,
+            instanceId: d.instanceId,
+            scheduledAt: d.scheduledAt,
+            sessionId: d.sessionId ?? null,
+            workspacePath: d.workspacePath ?? null,
+            outputs: d.outputs.filter((x) => typeof x === 'string'),
+        });
+    }
+    return out;
+}
+/**
+ * 实例快照 JSON → 已解析的上游依赖清单（**客户端便捷入口**）。
+ * 与服务端 `parseInstanceSnapshot` 同一套校验，但**不强求整份快照合法**——
+ * 客户端只想看「接收了什么」，快照里别的字段缺了不该让这一块消失。
+ * 空 / 坏 JSON / 旧行（无 resolvedDeps）⇒ `[]`（调用方按「无上游」渲染，不显示该区）。
+ */
+export function resolvedDepsOf(raw) {
+    if (raw === null || raw === '')
+        return [];
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null)
+            return [];
+        return parseResolvedDeps(value.resolvedDeps) ?? [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,133 @@
+import type { HostContext, HostLogger, HostWorkspace, UserFileContent, UserMessage } from './host.js';
+import type { PluginConfig } from './config.js';
+import type { InstanceSnapshot, TaskStore } from './store.js';
+/**
+ * 派发前置条件失败（决策 22 / 决策 23）：scheduler 按具体 reason 收敛实例，而非笼统 dispatch-error。
+ * reason 取值：no-model-route / agent-create-failed / receipt-tool-unavailable / workspace-attach-failed。
+ */
+export declare class DispatchPreconditionError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+/**
+ * 工作区名 → 工作区实体（决策 22：target.workspace 语义是**工作区**，不是工作目录；
+ * 目录由实体 path 派生）。registry 无按 name 查询 API，遍历 list() 比对：
+ * title 精确匹配优先，id 兜底。匹配不到即抛错 ⇒ 任务判失败，绝不落到「未分组」或随便找个目录跑。
+ * （Loop A 落库前的前置检查用；Loop B 发动走 resolveWorkspaceByPath——快照里存的是 path。）
+ */
+export declare function resolveWorkspace(ctx: HostContext, name: string): HostWorkspace;
+/**
+ * 工作区 path → 工作区实体（决策 41：Loop B 发动只读快照的 workspacePath）。
+ * 快照里的 path 是落库时从实体原样取的，精确比对即可；找不到 = 工作区被删/重建，
+ * 行保留走重试判定（失败原因落事件）。
+ */
+export declare function resolveWorkspaceByPath(ctx: HostContext, path: string): HostWorkspace;
+/** 命中漏斗的层级（写进 dispatch 事件，便于排查本次用了哪一层）。 */
+export type ModelSource = 'task' | 'plugin-config' | 'host-default' | 'llm-first';
+export interface ModelResolution {
+    provider: string;
+    model: string;
+    source: ModelSource;
+}
+/**
+ * 模型解析漏斗（决策 22，决策 41 修订第①层来源）：逐层下漏，四层全空返回 undefined
+ * （调用方判失败，走重试判定、行保留）。
+ *
+ * ① 派发快照的 provider/model 提示（= 落库时的任务 target，决策 41：Loop B 不读任务表）
+ * ② 插件配置 defaultProvider/defaultModel
+ * ③ 宿主默认 ctx.get('agentDefaultModel').currentSelection()（= 用户配的 / 上次用的模型）
+ * ④ llm 首个可用：listProviders() 首个能列出模型的 provider + 其首个模型
+ *
+ * ⚠️ 只在落库 / 发动时现算，**绝不回写**任务定义或配置：用户日后换模型要能自动跟上，
+ * 在配置期固化等于自己废掉兜底。
+ */
+export declare function resolveModelRoute(ctx: HostContext, logger: HostLogger, providerHint: string, modelHint: string, config: PluginConfig, hintLabel?: string): Promise<ModelResolution | undefined>;
+/**
+ * 插件→会话的用户消息（决策 19：追问层用，form=notice 走系统通知样式）。
+ * source.kind 用**生产者自有 kind**（0.1.7 v4 格式要求，`kind: 'plugin'` 已废弃被拒）。
+ */
+export declare function userNotice(text: string, summary: string, files?: readonly UserFileContent[]): UserMessage;
+/**
+ * 派发消息拼装（决策 12 模板 + 决策 24 回执工具 + 决策 41 快照化 + 决策 43 依赖冻结段 +
+ * 决策 49 团队段 + **随附文件段（决策 54）** + **执行时间段（U4，2026-10-05）**）：短指令 prompt +
+ * 手册路径 + 执行时间（原定 / 实际派发，给了 times 才注入）+ 上游依赖段 + **随附文件段** +
+ * 团队执行段（仅 agentTeam 且宿主具备时）+ 回执调用说明。
+ * prompt / manual / validStatuses / resolvedDeps / attachments 全部来自派发快照，与任务设置无关。
+ *
+ * 随附文件**两手都给**（2026-10-03 拍板）：
+ * ① **文本路径**——把**绝对路径**逐条写清（「从哪一层开始」就是它），并显式声明「允许读取」，否则
+ *    会与下面的权限指令（「仅工作区」）打架——upload 型附件落在**任务目录**（工作区之外），
+ *    不开口子模型就等于看不见；
+ * ② **官方 file 内容块**——把文件注册进宿主附件库（`ctx.attachments`），模型侧由宿主换成一句
+ *    「只读副本路径」（`projectFilesToText`），**不额外吃 token**；人的那一面则由官方渲染成
+ *    **附件卡**（图标 + 文件名 + 大小，可点开），且 fork 续聊带得走、当时那一份内容被钉住。
+ */
+export declare function buildMessage(snapshot: InstanceSnapshot, workspacePath: string, logicalDate: string, teamMode?: boolean, attachments?: readonly DispatchAttachment[], fileBlocks?: readonly UserFileContent[], 
+/** 执行时间两条（用户 2026-10-05 拍板，U4 收口）：不给 ⇒ 不注入该段（旧调用 / 冒烟旧行为不变）。 */
+times?: {
+    scheduledAt: string;
+    dispatchedAt: string;
+}): UserMessage;
+/**
+ * 派发消息里的随附文件条目（2026-09-30）：ref 已在 Loop B 解析成**绝对路径**。
+ * `path === null` = 来源工作区解析不出 ⇒ 如实标注「工作区相对路径」，**绝不猜**。
+ */
+export interface DispatchAttachment {
+    name: string;
+    kind: 'link' | 'upload';
+    /** link 型的工作区相对路径原文（基准未知时如实展示）。 */
+    ref: string;
+    path: string | null;
+}
+/**
+ * 随附文件 → 官方 `file` 内容块（2026-10-03 拍板「附加文件走 A」）。
+ *
+ * 逐个把文件字节交给宿主附件服务 `ctx.attachments.saveFile`（内容寻址、不可变、
+ * **永不自动删除**），拿回持久引用后拼成 file 块随派发消息发出 ⇒ 官方界面渲染成
+ * **附件卡**（图标 + 文件名 + 大小，可点开）、fork 续聊带得走、当时那份内容被钉住。
+ *
+ * **降级不阻塞**：宿主没挂 `dsh-attachment-local`、文件不在盘上、是目录、超过上限、
+ * 或 saveFile 抛错 ⇒ 该附件**只留文本路径**（2026-10-03 前的行为），派发照常。
+ *
+ * ⚠️ 目录**不能**作为附件：官方附件 = 一段字节，`FileAttachmentRef` 里没有路径
+ * （`dsh-attachment` `lib/types/types.d.ts:34-41`）。
+ */
+export declare function attachmentFileBlocks(ctx: HostContext, attachments: readonly DispatchAttachment[], logger: HostLogger, instanceId: string): Promise<UserFileContent[]>;
+export interface DispatchInput {
+    ctx: HostContext;
+    /** tee logger（显式传参——ctx 不可包装，见 host.ts HostLogger 注释）。 */
+    logger: HostLogger;
+    store: TaskStore;
+    /** 已落库实例：UUID 主键，状态应为 dispatched（决策 41：Loop B 发动）。 */
+    instanceId: string;
+    logicalDate: string;
+    scheduledAt: string;
+    /** 派发快照（决策 41）：prompt / manual / workspacePath / 模型提示 / validStatuses 全在其中。 */
+    snapshot: InstanceSnapshot;
+    /** 已按快照 path 解析的工作区实体（决策 22）：cwd 由它的 path 派生，会话建成后 attach 归组。 */
+    workspace: HostWorkspace;
+    /**
+     * 随附文件（2026-09-30）：ref 已由 Loop B 解析成**绝对路径**，随派发消息注入。
+     * （2026-10-03 起两手都给：文本路径 + 官方 file 内容块，见 {@link attachmentFileBlocks}。）
+     */
+    attachments: readonly DispatchAttachment[];
+    /** 插件配置（决策 22 漏斗第②层取 defaultProvider/defaultModel，发动时现算）。 */
+    config: PluginConfig;
+}
+/** agent handle：ctx.agents.create 的返回（追问时用于再推一轮对话）。 */
+export type AgentHandle = Awaited<ReturnType<HostContext['agents']['create']>>;
+/**
+ * 发动一个已落库实例（决策 41：Loop B 发动；决策 22 顺序 + 决策 23 preset 组装）：
+ * 解析模型漏斗（第①层取快照提示）→ **解析部署默认 preset** → 落 session_id → agents.create
+ * （自建会话并 announce session/created，对账收到时实例必已带 session_id；preset 在 create 的
+ * setup 里 mount，工具/prompt sections/skill 由此挂上）→ **工作区 attachSession 归组**
+ * → 落 dispatch 事件（含本次实测 route、命中层级与 preset）→ send。
+ * 会话改名在 reconciler.onCreated 做——此处拿不到 Session 对象（handle 只有 agent）。
+ * @returns sessionId 与 agent handle——handle 供对账层超时追问（决策 19 第二层）。
+ * @throws DispatchPreconditionError 模型解析不出、会话建不起来（含 preset 挂载失败）、
+ *   或会话建好后无法归组工作区——调用方（Loop B）按重试判定收敛、**行保留**。
+ */
+export declare function dispatchTask(input: DispatchInput): Promise<{
+    sessionId: string;
+    handle: AgentHandle;
+}>;