@william2000/dsh-nova-ui-task-board 0.3.0 → 0.3.1

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

@@ -1,54 +1,12 @@
-/**
- * 5 段 cron 语法校验（DSH-REQ-001 §9.4 / §11.2 协议严格校验「cron 合法性」）。
- *
- * T003 交付语法层（parseCron + isValidCron，纯函数、无依赖、无 fs）：协议层
- * 用它对 import 载荷里的 schedule.cron 做合法性校验。T006（cron 周期定时调度）
- * 在本模块之上扩展到期计算（nextRunAtMs，§9.4/§13.1：Host 本地时区、DST 正确
- * 处理、错过不补跑由调度 tick 的滚动语义承担），语法面保持一致。
- *
- * 语法（对齐参考实现 core/schedule.ts 的引擎基线）：五个空白分隔字段
- * `分 时 日 月 周`；每字段支持通配星号、步长（星号或区间 + 斜杠 n）、单值、
- * 闭区间 a-b、逗号列表（以上任意混排）。范围：分 0-59、时 0-23、日 1-31、
- * 月 1-12、周 0-7（0 与 7 均表示周日）。非法表达式解析为 null。
- *
- * 与 model.ts `isPlausibleCron` 的分层关系：`isPlausibleCron` 是持久化层的
- * 宽松形状检查（字符集 + 段数，用于行级修复「修复或丢弃 schedule」）；
- * 本模块是协议层的严格语法校验（字段取值范围/区间/步长合法性），二者不互换。
- */
-/** 解析后的各字段匹配集合（不含周字段 7→0 归一化，见 parseCron）。 */
 export interface ParsedCron {
     minutes: ReadonlySet<number>;
     hours: ReadonlySet<number>;
     days: ReadonlySet<number>;
     months: ReadonlySet<number>;
     weekdays: ReadonlySet<number>;
-    /** 日字段是否为字面 `*`（未限制）。 */
     dayWildcard: boolean;
-    /** 周字段是否为字面 `*`（未限制）。 */
     weekdayWildcard: boolean;
 }
-/**
- * 解析一个 5 段 cron 表达式。
- * @returns 各字段匹配集合；表达式非法时返回 null。
- */
 export declare function parseCron(expr: string): ParsedCron | null;
-/** 表达式是否可解析（语法合法）。 */
 export declare function isValidCron(expr: string): boolean;
-/**
- * 计算 `fromMs`（ms epoch）之后的下一个匹配时刻（T006 §9.4/§13.1）。返回匹配
- * 分钟起点的 ms epoch，**严格大于** fromMs；日历约束永不可能满足时返回
- * undefined（如 `0 0 30 2 *`——五年视界包含完整闰周期，合法的 2 月 29 日
- * 计划在任意非闰年仍可达）。
- *
- * 语义（对齐参考实现 core/schedule.ts，T006 验收 3）：
- * - **Host 本地时区**：按 `new Date(y, m, d, h, min)` 墙钟字段遍历候选，不换算
- *   到 UTC——DST 由本地时间语义自然承担；
- * - **日/周 OR 语义**：日字段与周字段字面 `*` 时各自视为未限制（见 parseCron），
- *   二者都受限时用 OR 组合（标准 cron）；
- * - **DST 正确性**：墙钟字段构造 + 最终 `matches` 复检复现旧分钟扫描的 DST
- *   语义——春令时不存在的时间（如 02:30 → 03:30）被 JS 归一化前移，回拨的
- *   重复小时（fall-back）只访问第一次出现；本实现不逐分钟扫描，而是直接从
- *   解析后的字段集合遍历年/月/日/时/分候选，稀疏表达式（如 `0 0 29 2 *`）不会
- *   扫过约 150 万分钟。
- */
 export declare function nextRunAtMs(expr: string, fromMs: number): number | undefined;

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

@@ -1,39 +1,8 @@
-/**
- * v1 数据迁移的纯函数（DSH-REQ-001 §9.5 / §11.2 `import`）。
- *
- * 迁移协议：浏览器首次加载时读取 `dsh.taskBoard.v1`（localStorage），按
- * sourceId（如 `'localStorage:dsh.taskBoard.v1'`）+ requestId 一次性提交 import
- * action；Host 侧由本模块按 id 合并进账本，并把 sourceId 追加到
- * `scheduler.importedSources`（**导入 marker 只在 Host 原子落账确认后写入**）。
- * 浏览器以「import 请求成功返回 + 记住返回快照的 ledgerId」作为确认凭证，确认
- * 后才自行处置 v1 原值——v1 原值保留为只读回退副本（对齐参考实现的
- * `dsh.taskBoard.v2.hostImported` marker 模式）。重复 import 同一 sourceId 为
- * 幂等 no-op（changed: false，不落账不 bump revision）。
- *
- * 合并语义（对齐参考实现）：同 id 任务取 `updatedAt` 较新者为底；执行记录按
- * execution id 合并——已结算记录胜过陈旧未结算记录，平局取较晚者。
- */
 import type { ExecutionRecord, LedgerDocument, TaskRecord } from './model.ts';
-/**
- * 二选一并取更「有信息量」的同 id 执行记录：
- * - 已结算胜过未结算（未结算多为陈旧副本的残留 open 记录）；
- * - 同为已结算/未结算时取较晚者（以 endedAt ?? startedAt 为准）。
- */
 export declare function mergeExecution(a: ExecutionRecord, b: ExecutionRecord): ExecutionRecord;
-/** 按 id 合并两条任务：较新 `updatedAt` 为底，执行记录按 id 合并并按时序排序。 */
 export declare function mergeTask(a: TaskRecord, b: TaskRecord): TaskRecord;
-/** import 落账结果。 */
 export interface ImportResult {
-    /** 是否发生了实际变更（false = sourceId 已导入过，幂等 no-op）。 */
     changed: boolean;
-    /** 可见错误（如被丢弃的非法任务行）。 */
     error?: string;
 }
-/**
- * 将一批 v1 任务按 sourceId 导入账本（就地修改 `doc`）：
- * - `doc.scheduler.importedSources` 已含 sourceId → `{ changed: false }`（跳过）；
- * - 否则逐条 `normalizeTask`（防御性校验：协议层已校验过类型，这里兜底），
- *   非法行丢弃并记入 error；合法行按 id 合并进 `doc.tasks`；
- * - 追加 sourceId 到 importedSources（导入 marker，随下次原子落账持久化）。
- */
 export declare function importIntoLedger(doc: LedgerDocument, sourceId: string, incoming: readonly TaskRecord[]): ImportResult;

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

@@ -1,446 +1,183 @@
-/**
- * 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

@@ -1,25 +1,7 @@
-/**
- * 加载时恢复（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

@@ -1,81 +1,26 @@
-/**
- * 需求拆分核心（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;