@william2000/dsh-nova-ui-task-board 0.1.0

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

@@ -0,0 +1,446 @@
+/**
+ * Task board authoritative data model（DSH-REQ-001 §9）。
+ *
+ * T002 落地完整的 Host 侧数据模型：
+ * - 账本文档（§9.1）：`LedgerDocument`，`schemaVersion: 2`、单调递增 `revision`、
+ *   `tasks`、`scheduler`（timeZone/ledgerId/lastTickAt/error/importedSources）、
+ *   `recentRequests`（最近 256 条幂等缓存）；
+ * - 任务（§9.2）：`TaskRecord` 全字段。`tags/project/order/parentId` 本期落位
+ *   （默认值/归一化），对应能力分别由 T008/T009/T012 启用；`source` 字段随
+ *   对话流转（P3）提前启用；
+ * - 执行记录（§9.3）：`ExecutionRecord`；
+ * - 执行安排（§9.4）：`ScheduleRule` 判别联合（cron | one-shot）；cron 的到期
+ *   计算与 one-shot 的触发消费属 T006/T007，本层只做结构解析与归一化。
+ *
+ * T010 补齐「自动化收集 + 上下文闭环」（P3，§9.5/§14）：
+ * - 评论（comments）：`TaskComment`（author/body/type/createdAt）挂在任务行；
+ * - 上下文快照（context_snapshot）：`ContextSnapshot`
+ *   （goal/keyDecisions/filePaths/lastAiSummary/latestUserFeedback/relatedLinks/
+ *   updatedAt），每次执行后由 Host 更新，后续调用只注入摘要 + 必要片段（B5）；
+ * - 产物（artifacts）：`Artifact`（type/title/url/contentRef），会话 transcript
+ *   即默认产物（执行结算成功时自动记录）；
+ * - 自动化规则（automation_rules）：`AutomationRule` 集合挂在账本文档
+ *   （trigger=5 段 cron / source=github_issue|bookmark_collector / config /
+ *   filter.labels / enabled），GitHub Webhook 与收藏收集 cron 共用；
+ * - 来源元数据：`TaskRecord.metadata`（Record<string,string>），GitHub Issue
+ *   的来源链接 / 书签 URL 等写入此处（§14.1/14.2，供去重与追溯）。
+ *
+ * 解析/归一化是纯函数（无 fs、无运行时依赖），保证模型可脱离宿主单测；
+ * 行级损坏「修复或丢弃 schedule、绝不丢整行」，账本级损坏抛
+ * `LedgerSchemaError` 由 HostLedger 走隔离路径（见 host-ledger.ts）。
+ */
+/** 账本 schema 版本（不兼容时走损坏隔离路径，见 §9.1）。 */
+export declare const LEDGER_SCHEMA_VERSION: 2;
+/** 幂等缓存保留条数（§11.3：最近 256 条）。 */
+export declare const MAX_REQUEST_CACHE = 256;
+/** 任务生命周期状态，与看板列一一对应（§10.1）；`proposed` 为对话流转候选（D7/P3.1）。 */
+export declare const TASK_STATUSES: readonly ["proposed", "backlog", "todo", "running", "done", "failed"];
+/** 任务生命周期状态。 */
+export type TaskStatus = typeof TASK_STATUSES[number];
+/** 任务来源（§9.2，v1.0 字段，P3 随对话流转启用）。 */
+export declare const TASK_SOURCES: readonly ["manual", "conversation", "github_issue", "bookmark_collector", "feishu", "requirement", "other"];
+/** 任务来源。 */
+export type TaskSource = typeof TASK_SOURCES[number];
+/** 执行会话钉住的权限预设 id（`/permission <id>`，§9.2）。 */
+export declare const TASK_PERMISSIONS: readonly ["read-only", "workspace-write", "danger-full-access"];
+/** 执行会话钉住的权限预设 id。 */
+export type TaskPermission = typeof TASK_PERMISSIONS[number];
+/** 执行结果（§9.3）。 */
+export declare const EXECUTION_RESULTS: readonly ["succeeded", "failed", "cancelled"];
+/** 执行结果。 */
+export type ExecutionResult = typeof EXECUTION_RESULTS[number];
+/** 评论类型（§9.5 comments：user_feedback/ai_log/system_event）。 */
+export declare const COMMENT_TYPES: readonly ["user_feedback", "ai_log", "system_event"];
+/** 评论类型。 */
+export type CommentType = typeof COMMENT_TYPES[number];
+/** 产物类型（§9.5 artifacts；会话 transcript 即默认产物 `session`）。 */
+export declare const ARTIFACT_TYPES: readonly ["session", "link", "file", "other"];
+/** 产物类型。 */
+export type ArtifactType = typeof ARTIFACT_TYPES[number];
+/** 自动化收集来源（§14.1/14.2 automation_rules.source）。 */
+export declare const AUTOMATION_SOURCES: readonly ["github_issue", "bookmark_collector"];
+/** 自动化收集来源。 */
+export type AutomationSource = typeof AUTOMATION_SOURCES[number];
+/** 单次执行尝试（§9.3）：自己的 id、承载会话（创建后回填）、起止与结算结果。 */
+export interface ExecutionRecord {
+    /** 执行尝试 id（uuid）。 */
+    id: string;
+    /** 承载本次执行的 DSH 会话 id；会话创建后回填，运行中/启动前缺省。 */
+    sessionId?: string;
+    /** 开始时间（ms epoch）。 */
+    startedAt: number;
+    /** 结算时间（ms epoch）；运行中缺省。 */
+    endedAt?: number;
+    /** 结算结果；运行中缺省。 */
+    result?: ExecutionResult;
+    /** 失败/取消原因。 */
+    error?: string;
+}
+/** 任务评论（§9.5 comments：author/body/type/createdAt，P3/T010 落地）。 */
+export interface TaskComment {
+    /** 评论 id（uuid）。 */
+    id: string;
+    /** 作者（缺省 'user'；'system' 为 Host 侧系统事件）。 */
+    author: string;
+    /** 正文（已清洗：控制字符剥离、长度封顶）。 */
+    body: string;
+    /** 评论类型（§9.5）。 */
+    type: CommentType;
+    /** 创建时间（ms epoch）。 */
+    createdAt: number;
+}
+/** 产物记录（§9.5 artifacts：type/title/url/content_ref；会话 transcript 即默认产物）。 */
+export interface Artifact {
+    /** 产物 id（uuid）。 */
+    id: string;
+    /** 产物类型（session/link/file/other）。 */
+    type: ArtifactType;
+    /** 展示标题。 */
+    title: string;
+    /** 外链（link 类）。 */
+    url?: string;
+    /** 内容引用（如会话 id / 文件相对路径）。 */
+    contentRef?: string;
+    /** 记录时间（ms epoch）。 */
+    createdAt: number;
+}
+/**
+ * 上下文快照（§9.5 context_snapshot，P3/T010 落地）。
+ * 每次执行后由 Host 更新（lastAiSummary 来自会话最近一条 assistant 消息的
+ * 文本摘取、latestUserFeedback 来自最近一条 user_feedback 评论、relatedLinks
+ * 来自来源 metadata.url）；goal/keyDecisions/filePaths 由用户/后续任务维护。
+ * 后续调用只注入摘要 + 必要片段（见 core/context.ts 的 composeInjectionContext，
+ * B5 调研决定 Host 侧摘取 + 固定 token 预算）。
+ */
+export interface ContextSnapshot {
+    /** 任务目标（可空；初始可由任务标题/描述派生）。 */
+    goal?: string;
+    /** 关键决策记录（P3 起，供跨会话续接）。 */
+    keyDecisions: string[];
+    /** 涉及文件路径（供续接定位）。 */
+    filePaths: string[];
+    /** 最近一次 AI 执行摘要（Host 执行结算时摘取，长度受 B5 预算约束）。 */
+    lastAiSummary?: string;
+    /** 最近一条用户反馈（评论 type=user_feedback 的最新正文）。 */
+    latestUserFeedback?: string;
+    /** 相关链接（来源 metadata.url 等）。 */
+    relatedLinks: string[];
+    /** 快照更新时间（ms epoch）。 */
+    updatedAt: number;
+}
+/**
+ * 自动化收集规则（§9.5 automation_rules / §14.1-14.3，P3/T010 落地）。
+ * 挂在账本文档级（非任务行）：一条规则定义一个外部来源的定时收集行为。
+ * - trigger：5 段 cron（收藏收集默认每周日 00:00；GitHub 也可配置轮询兜底）；
+ *   `nextRunAt`/`lastTriggeredAt` 为 Host 独占字段（tick 扫描与收集后维护，
+ *   浏览器不可写），与任务 schedule 的 cron 分支同语义（错过跳过不补跑）；
+ * - source：`github_issue`（GitHub Webhook 推送 + 可选 API 轮询）或
+ *   `bookmark_collector`（本地收藏收件箱文件，见 host-automation.ts）；
+ * - config：来源级配置（github_issue：`repo`；bookmark_collector：`filePath`）；
+ * - filter.labels：GitHub 标签过滤（非空时 Issue 必须命中至少一个标签才收集，
+ *   §14.1「如仅 bug/enhancement 标签」）。
+ */
+export interface AutomationRule {
+    /** 规则 id（uuid，浏览器创建时生成）。 */
+    id: string;
+    /** 是否武装（false = 不参与 tick 扫描与 Webhook 过滤）。 */
+    enabled: boolean;
+    /** 收集来源。 */
+    source: AutomationSource;
+    /** 触发：5 段 cron + Host 独占的到期/最近触发时间戳。 */
+    trigger: {
+        kind: 'cron';
+        cron: string;
+        nextRunAt?: number;
+        lastTriggeredAt?: number;
+    };
+    /** 来源级配置（均为字符串值）。 */
+    config: Record<string, string>;
+    /** 过滤器（GitHub 标签；空数组 = 全部接受）。 */
+    filter: {
+        labels: string[];
+    };
+    /** 创建时间（ms epoch）。 */
+    createdAt: number;
+    /** 最后变更时间（ms epoch）。 */
+    updatedAt: number;
+}
+/**
+ * 执行安排（§9.4 判别联合）：一个任务同时只持有一个执行安排，cron 周期定时
+ * 或一次性计划（one-shot）二选一。判别联合延续协议层的严格校验风格。
+ */
+export type ScheduleRule = {
+    kind: 'cron';
+    /** 是否武装。 */
+    enabled: boolean;
+    /** 5 段 cron（分 时 日 月 周），Host 本地时区。 */
+    cron: string;
+    /** 下次到期点（ms epoch，Host 调度器维护，浏览器不可写）。 */
+    nextRunAt?: number;
+    /** 最近触发点（ms epoch）。 */
+    lastTriggeredAt?: number;
+} | {
+    kind: 'one-shot';
+    /** 计划执行时刻（ms epoch，Host 本地时区）。 */
+    runAt: number;
+    /** 触发/消费标记（ms epoch）：到点触发执行时写入，防止重启后重复触发。 */
+    firedAt?: number;
+};
+/** 看板上的一个任务（§9.2）。 */
+export interface TaskRecord {
+    /** 稳定任务 id（uuid），全局唯一。 */
+    id: string;
+    /** 显示标题（非空，创建时校验）。 */
+    title: string;
+    /** 长描述，展示于详情页（可空）。 */
+    description: string;
+    /** 执行时发送给 agent 的 Prompt；空则回退用标题。 */
+    prompt: string;
+    /** 当前状态（列）。 */
+    status: TaskStatus;
+    /** 任务来源（P3 随对话流转启用；`requirement` 为需求拆分产物）。 */
+    source?: TaskSource;
+    /** 创建时间（ms epoch）。 */
+    createdAt: number;
+    /** 最后变更时间（ms epoch）。 */
+    updatedAt: number;
+    /** 全部执行记录，最近的在最后。 */
+    executions: ExecutionRecord[];
+    /** 可选执行安排（cron 或 one-shot，二选一，见 §9.4）。 */
+    schedule?: ScheduleRule;
+    /** 钉住的工作区（空 = 执行时用最近工作区）。 */
+    workspaceId?: string;
+    /** 钉住的 agent 预设 id（空 = 部署默认）。 */
+    mode?: string;
+    /** 钉住的权限预设（空 = 会话默认）。 */
+    permission?: TaskPermission;
+    /** 归档标记（ms epoch）；归档任务离开主看板、只读，定时被解除。 */
+    archivedAt?: number;
+    /** 标签数组（模块/优先级/技术栈等），默认 []（D9，P2.6 起启用）。 */
+    tags: string[];
+    /** 所属项目名（D9，P2.6 起启用）。 */
+    project?: string;
+    /** 父任务 id（需求拆分子任务指向父需求任务，D8，P3.2 起启用）。 */
+    parentId?: string;
+    /**
+     * 列内排序键：同列内唯一（不要求连续，Host 在 reorder/move 时重算，D10，
+     * P2.7 起启用）；新任务追加到所在列末尾。
+     */
+    order: number;
+    /** 来源元数据（T010，§14.1/14.2）：GitHub Issue 链接 / 书签 URL 等；去重与追溯用。 */
+    metadata?: Record<string, string>;
+    /** 评论（T010，§9.5 comments；默认 []）。 */
+    comments: TaskComment[];
+    /** 产物记录（T010，§9.5 artifacts；默认 []）。 */
+    artifacts: Artifact[];
+    /** 上下文快照（T010，§9.5 context_snapshot；每次执行后更新）。 */
+    contextSnapshot?: ContextSnapshot;
+}
+/**
+ * 新建任务的输入（§11.2 `create` / §12.4 新建表单）。
+ * T003 基线不含执行安排（cron/one-shot 属 T006/T007）；T008 扩展 project/tags
+ * （§9.2，新建表单可选填项目与标签，缺省不落字段/[]）。
+ */
+export interface NewTaskInput {
+    /** 显示标题（非空，trim 后校验）。 */
+    title: string;
+    /** 长描述（可空）。 */
+    description: string;
+    /** 执行时发送给 agent 的 Prompt；空则回退用标题。 */
+    prompt: string;
+    /** 钉住的工作区（空/缺省 = 执行时用最近工作区）。 */
+    workspaceId?: string;
+    /** 钉住的 agent 预设 id（空/缺省 = 部署默认）。 */
+    mode?: string;
+    /** 钉住的权限预设（缺省 = 会话默认）。 */
+    permission?: TaskPermission;
+    /** 所属项目名（T008，可空；trim 后落字段）。 */
+    project?: string;
+    /** 任意标签（T008，缺省 []；按 normalizeTags 规范化落账）。 */
+    tags?: string[];
+}
+/**
+ * 任务可编辑字段补丁（§11.2 `update`）。浏览器不可写 Host/runner 独占字段：
+ * `schedule.*`、`executions[].result/endedAt`、`archivedAt`、`status` 等一律
+ * 不在补丁面内（协议层 exact keys 拒绝）。T008 扩展 project/tags（§9.2：
+ * 项目单选可清除、标签数组整体替换，空数组 = 清空）。
+ */
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission' | 'project' | 'tags'>>;
+/**
+ * 对话流转候选的输入（§11.2 `propose`，T011/P3.1）：沿用 NewTaskInput 全部
+ * 字段，另加来源会话/消息引用（写入 metadata，供跳回对话追溯，§9.2/§14.4）。
+ * 标题/描述/prompt 的清洗（长度/字符/控制字符）由状态机落账层完成
+ * （transitions.applyProposeTask，§16.7）。
+ */
+export interface ProposeTaskInput extends NewTaskInput {
+    /** 来源会话 id（Agent 标记提取 / 手动「转为任务」时写入）。 */
+    sourceConversationId?: string;
+    /** 来源消息 id（可跳回对话中具体消息；缺省时以 seq 字符串代替）。 */
+    sourceMessageId?: string;
+}
+/**
+ * 批量候选条目（§11.2 `propose-batch` / §14.5，T012/P3.2）：ProposeTaskInput
+ * 扩展 `parentId`（父需求任务 id）。校验与落账见 transitions.applyProposeBatch：
+ * parentId 必须指向账本内已存在且非自身的任务（禁止环引用，§16.8），创建后
+ * 不可改（update 补丁面不含 parentId）。
+ */
+export interface BatchProposeItem extends ProposeTaskInput {
+    /** 父需求任务 id（需求拆分子任务指向父任务，D8）。 */
+    parentId?: string;
+}
+/**
+ * 需求拆分请求（§11.2 `start-split` / §12.9 / §14.5，T012/P3.2）：用户提交一份
+ * 需求文档（粘贴文本或工作区文件路径），Host 启动独立拆分会话（复用执行通道，
+ * B8）驱动 agent 按 §14.5 方法论拆分，结算后经父需求任务 propose +
+ * propose-batch 落账（全部 proposed，人工确认闸门复用 T011）。
+ *
+ * - `text` 与 `filePath` 至少提供其一（需求来源）；两者都提供时 text 优先内联、
+ *   filePath 作为来源说明写入父任务描述；
+ * - `parentTaskId`：递归拆分入口（§12.9）——对任一任务（含子任务）再发起拆分
+ *   时，新建的父需求任务「需求：<标题>」以该任务为父（parentId），子任务再指向
+ *   新父任务，形成树状层级。
+ */
+export interface SplitRequestInput {
+    /** 需求标题（父任务「需求：<标题>」与拆分会话标题）。 */
+    title: string;
+    /** 粘贴的需求原文（与 filePath 至少其一）。 */
+    text?: string;
+    /** 工作区内文件相对路径（与 text 至少其一；agent 自行读取文件）。 */
+    filePath?: string;
+    /** 需求所属项目（父任务与子任务自动带，§14.5 子任务产出结构）。 */
+    project?: string;
+    /** 默认标签（父任务与子任务自动带；agent 可再细化，见 core/split.ts）。 */
+    tags?: string[];
+    /** 递归拆分：新父需求任务挂到该任务下（§12.9/§14.5）。 */
+    parentTaskId?: string;
+}
+/** 来源会话引用写入 metadata 的键（§9.2/§14.4：可跳回对话）。 */
+export declare const SOURCE_CONVERSATION_META_KEY = "sourceConversationId";
+/** 来源消息引用写入 metadata 的键（§9.2/§14.4：可跳回消息）。 */
+export declare const SOURCE_MESSAGE_META_KEY = "sourceMessageId";
+/** 账本 scheduler 对外快照（不含内部字段 importedSources，见 §11.1 events）。 */
+export interface SchedulerSnapshot {
+    /** Host 本地时区。 */
+    timeZone: string;
+    /** 账本代数（迁移/导入判定）。 */
+    ledgerId?: string;
+    /** 最近 cron tick（ms epoch）。 */
+    lastTickAt?: number;
+    /** 可见的调度/恢复错误。 */
+    error?: string;
+}
+/** 账本内持久化的 scheduler（含内部字段，仅在文档层可见）。 */
+export interface LedgerScheduler extends SchedulerSnapshot {
+    /** 已导入的 v1 来源（§9.1）；导入 marker 只在 Host 确认（原子落账）后写入。 */
+    importedSources?: string[];
+}
+/** 幂等缓存条目（§11.3）。 */
+export interface RecentRequest {
+    requestId: string;
+    fingerprint: string;
+}
+/** 账本文档（§9.1）。 */
+export interface LedgerDocument {
+    schemaVersion: typeof LEDGER_SCHEMA_VERSION;
+    /** 单调递增的版本号；每次原子落账 +1。 */
+    revision: number;
+    /** 全部任务（含归档）。 */
+    tasks: TaskRecord[];
+    scheduler: LedgerScheduler;
+    /** 最近 256 条幂等缓存，随账本原子持久化。 */
+    recentRequests: RecentRequest[];
+    /** 自动化收集规则（T010，§9.5 automation_rules）。 */
+    automationRules: AutomationRule[];
+}
+/** Host 内部状态快照（revision + tasks 深拷贝 + scheduler + automationRules，不含 power——power 属协议层）。 */
+export interface LedgerState {
+    revision: number;
+    tasks: TaskRecord[];
+    scheduler: SchedulerSnapshot;
+    automationRules: AutomationRule[];
+}
+/** 账本级损坏（schema 不兼容/不可解析），由 HostLedger 走隔离路径。 */
+export declare class LedgerSchemaError extends Error {
+    constructor(message: string);
+}
+/** 有限数字守卫。 */
+export declare function isFiniteNumber(value: unknown): value is number;
+/** 非空字符串（trim 后）守卫，空串/空白清除钉住字段（对齐参考实现 normalizeTargetId）。 */
+export declare function normalizeOptionalString(value: unknown): string | undefined;
+/** 是否为已知任务状态。 */
+export declare function isTaskStatus(value: unknown): value is TaskStatus;
+/** 是否为已知任务来源。 */
+export declare function isTaskSource(value: unknown): value is TaskSource;
+/** 是否为已知权限预设。 */
+export declare function isTaskPermission(value: unknown): value is TaskPermission;
+/** 是否为已知执行结果。 */
+export declare function isExecutionResult(value: unknown): value is ExecutionResult;
+/** 是否为已知评论类型。 */
+export declare function isCommentType(value: unknown): value is CommentType;
+/** 是否为已知产物类型。 */
+export declare function isArtifactType(value: unknown): value is ArtifactType;
+/** 是否为已知自动化收集来源。 */
+export declare function isAutomationSource(value: unknown): value is AutomationSource;
+export declare function isPlausibleCron(cron: unknown): cron is string;
+/**
+ * 归一化一条持久化的执行安排（§9.4 判别联合）：
+ * - `kind: 'one-shot'` → one-shot 分支；`runAt` 非有限数则整条丢弃；
+ * - `kind: 'cron'` 或缺省 kind（v1/v2 旧形状）→ cron 分支；cron 形状非法则整条
+ *   丢弃（「修复或丢弃 schedule、绝不丢整行」——坏 schedule 不拖垮任务行）；
+ * - 其他 kind → 丢弃。
+ */
+export declare function normalizeSchedule(value: unknown): ScheduleRule | undefined;
+/** 归一化一条执行记录（§9.3）；结构非法返回 undefined。 */
+export declare function normalizeExecution(value: unknown): ExecutionRecord | undefined;
+/**
+ * 归一化标签数组（§9.2 默认 []）：仅保留字符串元素，逐项 trim、丢弃空白项、
+ * 按首次出现顺序去重；缺省/非法 → []。标签是展示/过滤维度的原始字符串，
+ * 大小写敏感（`API` 与 `api` 是两个标签），去重不折叠大小写。
+ */
+export declare function normalizeTags(value: unknown): string[];
+/** 归一化来源元数据（§14.1/14.2）：仅保留字符串键值对；缺省/非法 → undefined。 */
+export declare function normalizeMetadata(value: unknown): Record<string, string> | undefined;
+/** 归一化一条评论（§9.5）；结构非法返回 undefined。 */
+export declare function normalizeComment(value: unknown): TaskComment | undefined;
+/** 归一化评论集合（§9.5 comments，默认 []）；非法条目丢弃。 */
+export declare function normalizeComments(value: unknown): TaskComment[];
+/** 归一化一条产物（§9.5 artifacts）；结构非法返回 undefined。 */
+export declare function normalizeArtifact(value: unknown): Artifact | undefined;
+/** 归一化产物集合（§9.5 artifacts，默认 []）；非法条目丢弃。 */
+export declare function normalizeArtifacts(value: unknown): Artifact[];
+/** 归一化上下文快照（§9.5 context_snapshot）；结构非法返回 undefined。 */
+export declare function normalizeContextSnapshot(value: unknown): ContextSnapshot | undefined;
+/** 归一化一条自动化规则（§9.5 automation_rules）；结构非法返回 undefined。 */
+export declare function normalizeAutomationRule(value: unknown): AutomationRule | undefined;
+/** 归一化自动化规则集合（§9.5 automation_rules，默认 []）；非法条目丢弃。 */
+export declare function normalizeAutomationRules(value: unknown): AutomationRule[];
+/**
+ * 归一化一条任务行（§9.2）。
+ *
+ * 结构非法（id/title/description/prompt/createdAt/updatedAt/executions 任一不
+ * 符合）→ 返回 undefined（整行丢弃，HostLedger 记入 scheduler.error）；
+ * 语义非法 → 就地修复：
+ * - 未知状态 → `todo`（未来版本的未知状态落入待办而非丢行，对齐参考实现）；
+ * - 未知 source/permission → undefined；空白 workspaceId/mode/project/parentId
+ *   → undefined；archivedAt 非有限数 → undefined；
+ * - tags 非字符串数组 → []；order 非有限数 → 0（T009 重算列内唯一）；
+ * - schedule 交给 normalizeSchedule（修复或丢弃，不丢行）。
+ */
+export declare function normalizeTask(value: unknown): TaskRecord | undefined;
+/** Host 本地时区（§9.1 scheduler.timeZone）。 */
+export declare function hostTimeZone(): string;
+/**
+ * 空账本文档（新账本/损坏隔离后的重建起点）。
+ * @param error - 首次持久化即可见的错误（如损坏隔离说明）。
+ */
+export declare function emptyLedgerDocument(error?: string): LedgerDocument;
+/**
+ * 解析并归一化账本文档（§9.1）。
+ *
+ * 账本级损坏（非 JSON、根非对象、schemaVersion ≠ 2、tasks 非数组）抛
+ * `LedgerSchemaError`，由 HostLedger 隔离原文件（`corrupt-*` 保留原字节）后
+ * 以空账本重建。行级损坏（非法任务行、非法执行记录行）丢弃该行并记入
+ * `scheduler.error`；`revision` 非负安全整数 → 0；`recentRequests` 仅保留
+ * 合法条目并截断到最近 256 条。
+ */
+export declare function parseLedgerDocument(raw: string): LedgerDocument;

package/lib/types/core/recovery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 加载时恢复（DSH-REQ-001 §17 可恢复性 / §19-7）。
+ *
+ * Host 崩溃后重启：账本里可能残留 `running` 状态的任务——若其最后一次执行
+ * 从未拿到 sessionId（会话还没创建出来进程就死了），该执行永远无法被 runner
+ * 结算，必须在此标记 cancelled，否则看板会卡死在幽灵 running 态；若执行已带
+ * sessionId，说明会话已真实创建，由 T005 重启后按 sessionId 继续结算，这里不动。
+ *
+ * 本模块是 T002 的窄恢复逻辑（账本加载职责）；T003 的通用 settle 状态机可
+ * 吸收/复用同样的语义。
+ */
+import type { TaskRecord } from './model.ts';
+/** 无 sessionId 的中断执行被标记 cancelled 的原因文案。 */
+export declare const INTERRUPTED_START_REASON = "host restarted before the execution session was recorded";
+export interface RecoveryResult {
+    tasks: TaskRecord[];
+    changed: boolean;
+}
+/**
+ * 结算中断执行：running 任务 + 最后一条执行 open 且无 sessionId → 置
+ * cancelled（endedAt = now，记原因，bump updatedAt），状态按 §10.2
+ * `running → settle(cancelled) → todo` 回落待办，避免卡死幽灵 running 态。
+ * 其余任务原样保留。
+ */
+export declare function settleInterruptedStarts(tasks: readonly TaskRecord[], now: number): RecoveryResult;

package/lib/types/core/split.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 需求拆分核心（T012/P3.2，DSH-REQ-001 §12.9/§14.5 + 附录 B8 调研定案）。
+ *
+ * B8 结论（2026-08-23）：
+ * - **拆分执行通道**：`start-split` action 提交需求（粘贴文本/工作区文件路径）
+ *   后，Host 复用 T005 执行通道（runner.launch）启动**独立拆分会话**
+ *   （标题「需求拆分：<标题>」），按 §14.5 方法论（粒度启发式 + 拆后自检）驱动
+ *   agent 拆分；会话结束时 Host 读取 transcript，解析结构化标记，经父需求任务
+ *   propose + `propose-batch` 原子落账（全部 proposed，人工确认闸门复用 T011）。
+ *   会话不复用当前对话（不污染聊天记录）；成本 = 每次拆分一个独立会话（额度
+ *   成本随会话数量线性，递归拆分同理）；会话标题可辨识、候选 metadata 携带
+ *   拆分会话引用（可跳回追溯，§15）。
+ * - **输出契约**：agent 逐条输出单行标记 `⟦task-board:split⟧ 标题 | 描述 | prompt`
+ *   （与 T011 的 `⟦task-board:propose⟧` 同格式契约，按 `|` 分段），最后一行
+ *   `⟦task-board:coverage⟧ 覆盖矩阵`。解析为纯函数（本文件），可脱离宿主单测。
+ * - **粒度启发式**（§14.5）：单一职责、会话边界、单次 3~15 个（超限递归）；
+ *   拆后自检：覆盖完备 / 无重叠 / 可验收 / 依赖明确；拆分维度：功能模块 /
+ *   架构分层 / 交付顺序 / 验收逐条 / 混合。以上全部内嵌于指令模板
+ *   （composeSplitInstruction），由拆分会话的系统 Prompt 承载。
+ * - **父需求任务**（§14.5）：不引入独立「需求实体」——拆分结算时创建父任务
+ *   「需求：<标题>」（proposed、source=requirement），描述承载需求原文/来源与
+ *   覆盖矩阵（P3 产物表落地前存描述）；子任务 parentId 指向该父任务；
+ *   递归拆分（§12.9）时新父任务以原任务为父（parentId），形成树状层级。
+ */
+import type { SplitRequestInput } from './model.ts';
+/** 子任务单行标记（agent 输出契约，与 T011 的 propose 标记同格式）。 */
+export declare const SPLIT_MARKER = "\u27E6task-board:split\u27E7";
+/** 覆盖矩阵单行标记（agent 输出契约；其后内容 = 覆盖矩阵文本）。 */
+export declare const COVERAGE_MARKER = "\u27E6task-board:coverage\u27E7";
+/** 单次拆分的建议数量界下限（§14.5：少于 3 个提示合并）。 */
+export declare const SPLIT_BATCH_MIN = 3;
+/** 单次拆分的建议数量界上限（§14.5：多于 15 个提示递归拆分）。 */
+export declare const SPLIT_BATCH_MAX = 15;
+/** 父需求任务描述的长度封顶（§16.7 清洗：需求原文 + 覆盖矩阵整体封顶）。 */
+export declare const REQUIREMENT_DESCRIPTION_LIMIT = 40000;
+/** 拆分会话（独立执行会话）标题前缀：`需求拆分：<标题>`。 */
+export declare const SPLIT_SESSION_TITLE_PREFIX = "\u9700\u6C42\u62C6\u5206\uFF1A";
+/** 父需求任务标题前缀：`需求：<标题>`（§14.5 父需求任务）。 */
+export declare const REQUIREMENT_PARENT_TITLE_PREFIX = "\u9700\u6C42\uFF1A";
+/** 解析出的一条子任务标记内容（标题必填；描述/prompt 可空）。 */
+export interface SplitMarkerContent {
+    title: string;
+    description: string;
+    prompt: string;
+}
+/** 解析出的整批拆分结果：子任务条目 + 可选的覆盖矩阵文本。 */
+export interface SplitParseResult {
+    items: SplitMarkerContent[];
+    coverage?: string;
+}
+/**
+ * 解析 transcript 中的拆分标记（纯函数，可脱离宿主单测）：
+ * - 逐行扫描 `⟦task-board:split⟧`，每行一条子任务；行内按 `|` 分段（首段 =
+ *   标题，空则丢弃该条；次段 = 描述；其余拼接为 prompt）——与 T011
+ *   parseProposeMarkers 同契约；
+ * - 扫描 `⟦task-board:coverage⟧`，该行标记之后的内容 = 覆盖矩阵文本（首条
+ *   为准）；无标记 → 无覆盖矩阵；
+ * - 其余文本（说明性内容）忽略。
+ */
+export declare function parseSplitMarkers(text: string): SplitParseResult;
+/**
+ * 需求拆分指令模板（B8：粒度启发式 + 覆盖自检 + 输出 schema，§14.5）。
+ * 作为拆分会话（独立执行会话）的首条 Prompt 发送：内嵌需求标题与需求原文
+ * （text 优先；filePath 时指示 agent 先读文件），随后是拆分方法论与输出契约。
+ * @param input - 拆分请求（title 必填；text/filePath 至少其一）。
+ */
+export declare function composeSplitInstruction(input: SplitRequestInput): string;
+/**
+ * 构造父需求任务的描述（§14.5：承载需求原文与覆盖矩阵，P3 产物表落地前存
+ * 描述）：按「需求原文（text）/ 需求来源（filePath）/ 覆盖矩阵」三段拼接。
+ * 纯函数；长度封顶与清洗由调用方落账时经 sanitizeCollectedText 完成。
+ */
+export declare function buildRequirementDescription(input: {
+    text?: string;
+    filePath?: string;
+    coverage?: string;
+}): string;
+/** 父需求任务标题（§14.5：`需求：<标题>`），清洗后返回；空输入返回空串。 */
+export declare function requirementParentTitle(title: string): string;
+/** 拆分会话标题（`需求拆分：<标题>`），清洗后返回；空输入返回空串。 */
+export declare function splitSessionTitle(title: string): string;