@ilikexiaoni/pi-task-list 0.4.0

package/lib/task-list-core.ts

@@ -0,0 +1,780 @@
+export const TASK_LIST_VERSION = 2 as const;
+
+export const TASK_STATUSES = [
+  "pending",
+  "in_progress",
+  "blocked",
+  "completed",
+  "cancelled",
+] as const;
+
+export const TASK_PRIORITIES = ["high", "medium", "low"] as const;
+
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+export type TaskBlockSource = "" | "dependency" | "manual";
+export type TaskAction = "create" | "update" | "list" | "get" | "clear";
+export type ClearScope = "finished" | "all";
+
+export interface TaskNote {
+  at: string;
+  text: string;
+}
+
+export interface Task {
+  id: number;
+  subject: string;
+  description: string;
+  activeForm: string;
+  acceptanceCriteria: string[];
+  evidence: string[];
+  status: TaskStatus;
+  priority: TaskPriority;
+  blockedBy: number[];
+  blockReason: string;
+  blockSource: TaskBlockSource;
+  tags: string[];
+  owner: string;
+  completionNote: string;
+  notes: TaskNote[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TaskState {
+  version: typeof TASK_LIST_VERSION;
+  revision: number;
+  nextId: number;
+  updatedAt: string;
+  tasks: Task[];
+}
+
+export interface TaskCommand {
+  action: TaskAction;
+  id?: number;
+  subject?: string;
+  description?: string;
+  activeForm?: string;
+  acceptanceCriteria?: string[];
+  evidence?: string[];
+  addEvidence?: string[];
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  blockedBy?: number[];
+  addBlockedBy?: number[];
+  removeBlockedBy?: number[];
+  blockReason?: string;
+  tags?: string[];
+  addTags?: string[];
+  removeTags?: string[];
+  owner?: string;
+  completionNote?: string;
+  note?: string;
+  query?: string;
+  includeCancelled?: boolean;
+  scope?: ClearScope;
+  confirm?: boolean;
+}
+
+export interface ApplyResult {
+  action: TaskAction;
+  state: TaskState;
+  changedIds: number[];
+  visibleTasks: Task[];
+  selectedTask?: Task;
+  message: string;
+  mutated: boolean;
+}
+
+export class TaskListError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "TaskListError";
+    this.code = code;
+  }
+}
+
+const MAX_SUBJECT_LENGTH = 300;
+const MAX_FIELD_LENGTH = 4000;
+const MAX_LIST_ITEMS = 50;
+const MAX_NOTES = 100;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTaskStatus(value: unknown): value is TaskStatus {
+  return typeof value === "string" && (TASK_STATUSES as readonly string[]).includes(value);
+}
+
+function isTaskPriority(value: unknown): value is TaskPriority {
+  return typeof value === "string" && (TASK_PRIORITIES as readonly string[]).includes(value);
+}
+
+function isTaskBlockSource(value: unknown): value is TaskBlockSource {
+  return value === "" || value === "dependency" || value === "manual";
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function boundedText(value: unknown, field: string, max = MAX_FIELD_LENGTH): string {
+  if (typeof value !== "string") {
+    throw new TaskListError("invalid_argument", `${field} 必须是字符串`);
+  }
+  const text = value.trim();
+  if (text.length > max) {
+    throw new TaskListError("invalid_argument", `${field} 不能超过 ${max} 个字符`);
+  }
+  return text;
+}
+
+function requiredText(value: unknown, field: string, max = MAX_FIELD_LENGTH): string {
+  const text = boundedText(value, field, max);
+  if (!text) {
+    throw new TaskListError("invalid_argument", `${field} 不能为空`);
+  }
+  return text;
+}
+
+function stringList(value: unknown, field: string, maxItems = MAX_LIST_ITEMS): string[] {
+  if (!Array.isArray(value)) {
+    throw new TaskListError("invalid_argument", `${field} 必须是字符串数组`);
+  }
+  if (value.length > maxItems) {
+    throw new TaskListError("invalid_argument", `${field} 最多包含 ${maxItems} 项`);
+  }
+  const result: string[] = [];
+  for (const item of value) {
+    const text = requiredText(item, `${field} 项`, MAX_FIELD_LENGTH);
+    if (!result.includes(text)) result.push(text);
+  }
+  return result;
+}
+
+function idList(value: unknown, field: string): number[] {
+  if (!Array.isArray(value)) {
+    throw new TaskListError("invalid_argument", `${field} 必须是数字数组`);
+  }
+  if (value.length > MAX_LIST_ITEMS) {
+    throw new TaskListError("invalid_argument", `${field} 最多包含 ${MAX_LIST_ITEMS} 项`);
+  }
+  const result: number[] = [];
+  for (const item of value) {
+    const id = positiveInteger(item);
+    if (id === undefined) {
+      throw new TaskListError("invalid_argument", `${field} 只能包含正整数任务 ID`);
+    }
+    if (!result.includes(id)) result.push(id);
+  }
+  return result;
+}
+
+function safeStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim().slice(0, MAX_FIELD_LENGTH))
+    .filter(Boolean)
+    .filter((item, index, list) => list.indexOf(item) === index)
+    .slice(0, MAX_LIST_ITEMS);
+}
+
+function safeIdList(value: unknown): number[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map(positiveInteger)
+    .filter((item): item is number => item !== undefined)
+    .filter((item, index, list) => list.indexOf(item) === index)
+    .slice(0, MAX_LIST_ITEMS);
+}
+
+function safeNotes(value: unknown): TaskNote[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter(isRecord)
+    .map((item) => ({
+      at: typeof item.at === "string" ? item.at : "",
+      text: typeof item.text === "string" ? item.text.trim().slice(0, MAX_FIELD_LENGTH) : "",
+    }))
+    .filter((item) => item.text.length > 0)
+    .slice(-MAX_NOTES);
+}
+
+function cloneTask(task: Task): Task {
+  return {
+    ...task,
+    acceptanceCriteria: [...task.acceptanceCriteria],
+    evidence: [...task.evidence],
+    blockedBy: [...task.blockedBy],
+    tags: [...task.tags],
+    notes: task.notes.map((note) => ({ ...note })),
+  };
+}
+
+export function cloneState(state: TaskState): TaskState {
+  return {
+    ...state,
+    tasks: state.tasks.map(cloneTask),
+  };
+}
+
+export function createEmptyState(now = new Date().toISOString()): TaskState {
+  return {
+    version: TASK_LIST_VERSION,
+    revision: 0,
+    nextId: 1,
+    updatedAt: now,
+    tasks: [],
+  };
+}
+
+/** Normalize persisted data defensively so a malformed old session cannot break startup. */
+export function normalizeState(value: unknown): TaskState {
+  if (!isRecord(value)) return createEmptyState();
+
+  const rawTasks = Array.isArray(value.tasks) ? value.tasks : [];
+  const tasks: Task[] = [];
+  const seenIds = new Set<number>();
+  let fallbackId = 1;
+
+  for (const rawTask of rawTasks) {
+    if (!isRecord(rawTask)) continue;
+    const rawId = positiveInteger(rawTask.id);
+    const id = rawId ?? fallbackId;
+    fallbackId = Math.max(fallbackId, id + 1);
+    if (seenIds.has(id)) continue;
+    seenIds.add(id);
+
+    const subject =
+      typeof rawTask.subject === "string" && rawTask.subject.trim()
+        ? rawTask.subject.trim().slice(0, MAX_SUBJECT_LENGTH)
+        : `Task #${id}`;
+    const status = isTaskStatus(rawTask.status) ? rawTask.status : "pending";
+    const priority = isTaskPriority(rawTask.priority) ? rawTask.priority : "medium";
+    const description = typeof rawTask.description === "string" ? rawTask.description.trim().slice(0, MAX_FIELD_LENGTH) : "";
+    const activeForm =
+      typeof rawTask.activeForm === "string" && rawTask.activeForm.trim()
+        ? rawTask.activeForm.trim().slice(0, MAX_SUBJECT_LENGTH)
+        : subject;
+    const blockedBy = safeIdList(rawTask.blockedBy);
+    const blockReason = typeof rawTask.blockReason === "string" ? rawTask.blockReason.trim().slice(0, MAX_FIELD_LENGTH) : "";
+    const inferredBlockSource: TaskBlockSource =
+      status !== "blocked"
+        ? ""
+        : blockedBy.length > 0 && (!blockReason || blockReason.startsWith("等待任务 "))
+          ? "dependency"
+          : "manual";
+    const blockSource = isTaskBlockSource(rawTask.blockSource) ? rawTask.blockSource : inferredBlockSource;
+
+    tasks.push({
+      id,
+      subject,
+      description,
+      activeForm,
+      acceptanceCriteria: safeStringList(rawTask.acceptanceCriteria),
+      evidence: safeStringList(rawTask.evidence),
+      status,
+      priority,
+      blockedBy,
+      blockReason,
+      blockSource: status === "blocked" ? blockSource : "",
+      tags: safeStringList(rawTask.tags),
+      owner: typeof rawTask.owner === "string" ? rawTask.owner.trim().slice(0, 200) : "",
+      completionNote:
+        typeof rawTask.completionNote === "string" ? rawTask.completionNote.trim().slice(0, MAX_FIELD_LENGTH) : "",
+      notes: safeNotes(rawTask.notes),
+      createdAt: typeof rawTask.createdAt === "string" ? rawTask.createdAt : "",
+      updatedAt: typeof rawTask.updatedAt === "string" ? rawTask.updatedAt : "",
+    });
+  }
+
+  const rawNextId = positiveInteger(value.nextId) ?? 1;
+  const rawRevision = typeof value.revision === "number" && Number.isInteger(value.revision) && value.revision >= 0 ? value.revision : 0;
+  const updatedAt = typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString();
+
+  const state: TaskState = {
+    version: TASK_LIST_VERSION,
+    revision: rawRevision,
+    nextId: Math.max(rawNextId, fallbackId, ...tasks.map((task) => task.id + 1)),
+    updatedAt,
+    tasks,
+  };
+  reconcileDependencyBlocks(state, updatedAt, false);
+  return state;
+}
+
+function taskById(state: TaskState, id: number | undefined): Task {
+  const validId = positiveInteger(id);
+  if (validId === undefined) {
+    throw new TaskListError("invalid_argument", "必须提供正整数任务 ID");
+  }
+  const task = state.tasks.find((item) => item.id === validId);
+  if (!task) {
+    throw new TaskListError("not_found", `任务 #${validId} 不存在`);
+  }
+  return task;
+}
+
+function validateReferences(state: TaskState, ids: number[], selfId?: number): void {
+  const known = new Set(state.tasks.map((task) => task.id));
+  for (const id of ids) {
+    if (selfId === id) {
+      throw new TaskListError("dependency_cycle", `任务 #${id} 不能依赖自己`);
+    }
+    if (!known.has(id)) {
+      throw new TaskListError("not_found", `依赖任务 #${id} 不存在`);
+    }
+  }
+}
+
+function validateNoCycle(state: TaskState, taskId: number, dependencies: number[]): void {
+  const graph = new Map(state.tasks.map((task) => [task.id, task.blockedBy]));
+  graph.set(taskId, dependencies);
+
+  const reachesTask = (current: number, visited: Set<number>): boolean => {
+    if (current === taskId) return true;
+    if (visited.has(current)) return false;
+    visited.add(current);
+    for (const dependency of graph.get(current) ?? []) {
+      if (reachesTask(dependency, new Set(visited))) return true;
+    }
+    return false;
+  };
+
+  for (const dependency of dependencies) {
+    if (reachesTask(dependency, new Set())) {
+      throw new TaskListError("dependency_cycle", `任务 #${taskId} 的依赖会形成循环`);
+    }
+  }
+}
+
+function unresolvedDependencies(state: TaskState, task: Task): Task[] {
+  const resolved = new Set(["completed", "cancelled"]);
+  return task.blockedBy
+    .map((id) => state.tasks.find((candidate) => candidate.id === id))
+    .filter((candidate): candidate is Task => candidate !== undefined && !resolved.has(candidate.status));
+}
+
+function dependencyReason(tasks: Task[]): string {
+  return `等待任务 ${tasks.map((task) => `#${task.id}`).join(", ")} 完成`;
+}
+
+function normalizeStatus(value: unknown): TaskStatus {
+  if (!isTaskStatus(value)) {
+    throw new TaskListError("invalid_argument", `status 必须是 ${TASK_STATUSES.join(", ")} 之一`);
+  }
+  return value;
+}
+
+function normalizePriority(value: unknown): TaskPriority {
+  if (!isTaskPriority(value)) {
+    throw new TaskListError("invalid_argument", `priority 必须是 ${TASK_PRIORITIES.join(", ")} 之一`);
+  }
+  return value;
+}
+
+function appendNote(task: Task, text: string, at: string): void {
+  task.notes.push({ at, text });
+  if (task.notes.length > MAX_NOTES) task.notes = task.notes.slice(-MAX_NOTES);
+}
+
+function touch(state: TaskState, now: string): void {
+  state.revision += 1;
+  state.updatedAt = now;
+}
+
+function makeTask(state: TaskState, params: TaskCommand, now: string): Task {
+  const subject = requiredText(params.subject, "subject", MAX_SUBJECT_LENGTH);
+  const requestedStatus = params.status === undefined ? "pending" : normalizeStatus(params.status);
+  const priority = params.priority === undefined ? "medium" : normalizePriority(params.priority);
+  const blockedBy = params.blockedBy === undefined ? [] : idList(params.blockedBy, "blockedBy");
+  validateReferences(state, blockedBy);
+
+  if (requestedStatus === "completed" || requestedStatus === "cancelled") {
+    throw new TaskListError("invalid_transition", "新任务只能从 pending、in_progress 或 blocked 开始");
+  }
+
+  const task: Task = {
+    id: state.nextId++,
+    subject,
+    description: params.description === undefined ? "" : boundedText(params.description, "description"),
+    activeForm:
+      params.activeForm === undefined || !params.activeForm.trim()
+        ? subject
+        : boundedText(params.activeForm, "activeForm", MAX_SUBJECT_LENGTH),
+    acceptanceCriteria: params.acceptanceCriteria === undefined ? [] : stringList(params.acceptanceCriteria, "acceptanceCriteria"),
+    evidence: params.evidence === undefined ? [] : stringList(params.evidence, "evidence"),
+    status: requestedStatus,
+    priority,
+    blockedBy,
+    blockReason: params.blockReason === undefined ? "" : boundedText(params.blockReason, "blockReason"),
+    blockSource: "",
+    tags: params.tags === undefined ? [] : stringList(params.tags, "tags"),
+    owner: params.owner === undefined ? "" : boundedText(params.owner, "owner", 200),
+    completionNote: params.completionNote === undefined ? "" : boundedText(params.completionNote, "completionNote"),
+    notes: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const unresolved = unresolvedDependencies(state, task);
+  if (unresolved.length > 0) {
+    if (requestedStatus === "in_progress") {
+      throw new TaskListError("blocked_dependency", `${dependencyReason(unresolved)}，不能直接开始任务 #${task.id}`);
+    }
+    task.status = "blocked";
+    if (task.blockReason) {
+      task.blockSource = "manual";
+    } else {
+      task.blockReason = dependencyReason(unresolved);
+      task.blockSource = "dependency";
+    }
+    appendNote(task, `自动标记为 blocked：${task.blockReason}`, now);
+  } else if (task.status === "blocked") {
+    if (!task.blockReason) {
+      throw new TaskListError("invalid_argument", "blocked 状态必须提供 blockReason 或未完成的 blockedBy");
+    }
+    task.blockSource = "manual";
+  } else {
+    task.blockReason = "";
+    task.blockSource = "";
+  }
+
+  if (params.note !== undefined) {
+    appendNote(task, requiredText(params.note, "note"), now);
+  }
+
+  return task;
+}
+
+function updateTask(state: TaskState, params: TaskCommand, now: string): { task: Task; changed: boolean } {
+  const current = taskById(state, params.id);
+  const before = cloneTask(current);
+  const candidate = cloneTask(current);
+
+  if (params.subject !== undefined) candidate.subject = requiredText(params.subject, "subject", MAX_SUBJECT_LENGTH);
+  if (params.description !== undefined) candidate.description = boundedText(params.description, "description");
+  if (params.activeForm !== undefined) {
+    const activeForm = boundedText(params.activeForm, "activeForm", MAX_SUBJECT_LENGTH);
+    candidate.activeForm = activeForm || candidate.subject;
+  }
+  if (params.acceptanceCriteria !== undefined) {
+    candidate.acceptanceCriteria = stringList(params.acceptanceCriteria, "acceptanceCriteria");
+  }
+  if (params.evidence !== undefined) candidate.evidence = stringList(params.evidence, "evidence");
+  if (params.addEvidence !== undefined) {
+    for (const item of stringList(params.addEvidence, "addEvidence")) {
+      if (!candidate.evidence.includes(item)) candidate.evidence.push(item);
+    }
+  }
+  if (params.priority !== undefined) candidate.priority = normalizePriority(params.priority);
+  if (params.blockedBy !== undefined) candidate.blockedBy = idList(params.blockedBy, "blockedBy");
+  if (params.addBlockedBy !== undefined) {
+    for (const id of idList(params.addBlockedBy, "addBlockedBy")) {
+      if (!candidate.blockedBy.includes(id)) candidate.blockedBy.push(id);
+    }
+  }
+  if (params.removeBlockedBy !== undefined) {
+    const remove = new Set(idList(params.removeBlockedBy, "removeBlockedBy"));
+    candidate.blockedBy = candidate.blockedBy.filter((id) => !remove.has(id));
+  }
+  if (params.blockReason !== undefined) {
+    candidate.blockReason = boundedText(params.blockReason, "blockReason");
+    candidate.blockSource = candidate.blockReason ? "manual" : "";
+  }
+  if (params.tags !== undefined) candidate.tags = stringList(params.tags, "tags");
+  if (params.addTags !== undefined) {
+    for (const tag of stringList(params.addTags, "addTags")) {
+      if (!candidate.tags.includes(tag)) candidate.tags.push(tag);
+    }
+  }
+  if (params.removeTags !== undefined) {
+    const remove = new Set(stringList(params.removeTags, "removeTags"));
+    candidate.tags = candidate.tags.filter((tag) => !remove.has(tag));
+  }
+  if (params.owner !== undefined) candidate.owner = boundedText(params.owner, "owner", 200);
+  if (params.completionNote !== undefined) candidate.completionNote = boundedText(params.completionNote, "completionNote");
+
+  if (params.status !== undefined) {
+    candidate.status = normalizeStatus(params.status);
+    if (candidate.status !== "blocked") {
+      candidate.blockReason = "";
+      candidate.blockSource = "";
+    }
+  }
+
+  validateReferences(state, candidate.blockedBy, candidate.id);
+  validateNoCycle(state, candidate.id, candidate.blockedBy);
+
+  const unresolved = unresolvedDependencies(state, candidate);
+  if (candidate.status === "in_progress" && unresolved.length > 0) {
+    throw new TaskListError("blocked_dependency", `${dependencyReason(unresolved)}，不能将任务 #${candidate.id} 标记为 in_progress`);
+  }
+  if (candidate.status === "completed") {
+    if (unresolved.length > 0) {
+      throw new TaskListError("blocked_dependency", `${dependencyReason(unresolved)}，不能完成任务 #${candidate.id}`);
+    }
+    if (candidate.evidence.length < candidate.acceptanceCriteria.length) {
+      throw new TaskListError(
+        "evidence_required",
+        `任务 #${candidate.id} 有 ${candidate.acceptanceCriteria.length} 条完成条件，标记 completed 前至少需要同等数量的 evidence（当前 ${candidate.evidence.length} 条）`,
+      );
+    }
+  }
+  if (unresolved.length > 0 && candidate.status === "pending") {
+    candidate.status = "blocked";
+    candidate.blockReason = dependencyReason(unresolved);
+    candidate.blockSource = "dependency";
+  }
+  if (candidate.status === "blocked") {
+    if (candidate.blockSource === "manual" && candidate.blockReason) {
+      // Manual blockers remain until explicitly cleared by the caller.
+    } else if (unresolved.length > 0) {
+      candidate.blockReason = dependencyReason(unresolved);
+      candidate.blockSource = "dependency";
+    } else if (params.status === "blocked") {
+      throw new TaskListError("invalid_argument", "blocked 状态必须提供 blockReason 或未完成的 blockedBy");
+    } else {
+      candidate.status = "pending";
+      candidate.blockReason = "";
+      candidate.blockSource = "";
+      appendNote(candidate, "依赖已完成，自动恢复为 pending", now);
+    }
+  }
+  if (candidate.status !== "blocked") {
+    candidate.blockReason = "";
+    candidate.blockSource = "";
+  }
+
+  if (params.note !== undefined) appendNote(candidate, requiredText(params.note, "note"), now);
+  if (candidate.status !== before.status) {
+    appendNote(candidate, `状态变更：${before.status} -> ${candidate.status}`, now);
+  }
+
+  const changed = JSON.stringify(candidate) !== JSON.stringify(before);
+  if (changed) candidate.updatedAt = now;
+  return { task: candidate, changed };
+}
+
+function reconcileDependencyBlocks(state: TaskState, now: string, recordNotes = true): number[] {
+  const changedIds: number[] = [];
+
+  for (const task of state.tasks) {
+    if (task.status === "completed" || task.status === "cancelled") continue;
+    const before = cloneTask(task);
+    const unresolved = unresolvedDependencies(state, task);
+
+    if (unresolved.length > 0) {
+      if (task.status === "pending" || task.status === "in_progress" || task.blockSource === "dependency") {
+        task.status = "blocked";
+        task.blockReason = dependencyReason(unresolved);
+        task.blockSource = "dependency";
+      }
+    } else if (task.status === "blocked" && task.blockSource === "dependency") {
+      task.status = "pending";
+      task.blockReason = "";
+      task.blockSource = "";
+    }
+
+    if (JSON.stringify(task) === JSON.stringify(before)) continue;
+    if (recordNotes && task.status !== before.status) {
+      const note = task.status === "blocked" ? `依赖未完成，自动标记为 blocked：${task.blockReason}` : "依赖已完成，自动恢复为 pending";
+      appendNote(task, note, now);
+    }
+    task.updatedAt = now;
+    changedIds.push(task.id);
+  }
+
+  return changedIds;
+}
+
+export function filterTasks(state: TaskState, params: Pick<TaskCommand, "status" | "priority" | "query" | "includeCancelled"> = {}): Task[] {
+  const status = params.status === undefined ? undefined : normalizeStatus(params.status);
+  const priority = params.priority === undefined ? undefined : normalizePriority(params.priority);
+  const query = params.query?.trim().toLowerCase();
+
+  return state.tasks
+    .filter((task) => params.includeCancelled === true || task.status !== "cancelled")
+    .filter((task) => status === undefined || task.status === status)
+    .filter((task) => priority === undefined || task.priority === priority)
+    .filter((task) => {
+      if (!query) return true;
+      return [task.subject, task.description, task.owner, ...task.tags].some((value) => value.toLowerCase().includes(query));
+    })
+    .sort(compareTasks)
+    .map(cloneTask);
+}
+
+function compareTasks(left: Task, right: Task): number {
+  const statusRank: Record<TaskStatus, number> = {
+    in_progress: 0,
+    blocked: 1,
+    pending: 2,
+    completed: 3,
+    cancelled: 4,
+  };
+  const priorityRank: Record<TaskPriority, number> = { high: 0, medium: 1, low: 2 };
+  return statusRank[left.status] - statusRank[right.status] || priorityRank[left.priority] - priorityRank[right.priority] || left.id - right.id;
+}
+
+export function isTaskReady(state: TaskState, task: Task): boolean {
+  return task.status === "pending" && unresolvedDependencies(state, task).length === 0;
+}
+
+export function applyTaskAction(current: TaskState, params: TaskCommand, now = new Date().toISOString()): ApplyResult {
+  const state = cloneState(normalizeState(current));
+
+  switch (params.action) {
+    case "create": {
+      const task = makeTask(state, params, now);
+      state.tasks.push(task);
+      touch(state, now);
+      return {
+        action: "create",
+        state,
+        changedIds: [task.id],
+        visibleTasks: [cloneTask(task)],
+        selectedTask: cloneTask(task),
+        message: `已创建任务 #${task.id}：${task.subject}${task.status === "blocked" ? `（blocked：${task.blockReason}）` : ""}`,
+        mutated: true,
+      };
+    }
+
+    case "update": {
+      const result = updateTask(state, params, now);
+      if (!result.changed) {
+        return {
+          action: "update",
+          state,
+          changedIds: [],
+          visibleTasks: [cloneTask(result.task)],
+          selectedTask: cloneTask(result.task),
+          message: `任务 #${result.task.id} 未发生变化`,
+          mutated: false,
+        };
+      }
+      const index = state.tasks.findIndex((task) => task.id === result.task.id);
+      state.tasks[index] = result.task;
+      const dependentChanges = reconcileDependencyBlocks(state, now).filter((id) => id !== result.task.id);
+      const changedIds = [result.task.id, ...dependentChanges];
+      const selectedTask = cloneTask(state.tasks[index]);
+      touch(state, now);
+      return {
+        action: "update",
+        state,
+        changedIds,
+        visibleTasks: state.tasks.filter((task) => changedIds.includes(task.id)).map(cloneTask),
+        selectedTask,
+        message: `已更新任务 #${selectedTask.id}：${selectedTask.subject} [${selectedTask.status}]${dependentChanges.length > 0 ? `；同步更新 ${dependentChanges.length} 个依赖任务` : ""}`,
+        mutated: true,
+      };
+    }
+
+    case "list": {
+      const visibleTasks = filterTasks(state, params);
+      return {
+        action: "list",
+        state,
+        changedIds: [],
+        visibleTasks,
+        message: `当前显示 ${visibleTasks.length} 个任务`,
+        mutated: false,
+      };
+    }
+
+    case "get": {
+      const task = cloneTask(taskById(state, params.id));
+      return {
+        action: "get",
+        state,
+        changedIds: [],
+        visibleTasks: [task],
+        selectedTask: task,
+        message: `任务 #${task.id}：${task.subject}`,
+        mutated: false,
+      };
+    }
+
+    case "clear": {
+      if (params.confirm !== true) {
+        throw new TaskListError("confirmation_required", "clear 是破坏性操作，必须显式提供 confirm=true");
+      }
+      const scope = params.scope ?? "finished";
+      if (scope !== "finished" && scope !== "all") {
+        throw new TaskListError("invalid_argument", "scope 必须是 finished 或 all");
+      }
+      const removed = scope === "all" ? [...state.tasks] : state.tasks.filter((task) => task.status === "completed" || task.status === "cancelled");
+      if (removed.length === 0) {
+        return {
+          action: "clear",
+          state,
+          changedIds: [],
+          visibleTasks: [],
+          message: "没有符合清理范围的任务",
+          mutated: false,
+        };
+      }
+      const removedIds = new Set(removed.map((task) => task.id));
+      state.tasks = scope === "all" ? [] : state.tasks.filter((task) => !removedIds.has(task.id));
+      for (const task of state.tasks) {
+        task.blockedBy = task.blockedBy.filter((id) => !removedIds.has(id));
+      }
+      touch(state, now);
+      return {
+        action: "clear",
+        state,
+        changedIds: removed.map((task) => task.id),
+        visibleTasks: state.tasks.map(cloneTask),
+        message: `已清理 ${removed.length} 个任务（范围：${scope}）`,
+        mutated: true,
+      };
+    }
+
+    default:
+      throw new TaskListError("invalid_argument", `不支持的 action：${String(params.action)}`);
+  }
+}
+
+export function statusLabel(status: TaskStatus): string {
+  return {
+    pending: "待处理",
+    in_progress: "进行中",
+    blocked: "阻塞",
+    completed: "已完成",
+    cancelled: "已取消",
+  }[status];
+}
+
+export function priorityLabel(priority: TaskPriority): string {
+  return { high: "高", medium: "中", low: "低" }[priority];
+}
+
+export function summarizeState(state: TaskState): { total: number; active: number; blocked: number; pending: number; completed: number; cancelled: number; ready: number } {
+  const summary = { total: 0, active: 0, blocked: 0, pending: 0, completed: 0, cancelled: 0, ready: 0 };
+  const statusById = new Map(state.tasks.map((task) => [task.id, task.status]));
+
+  for (const task of state.tasks) {
+    if (task.status === "cancelled") {
+      summary.cancelled++;
+      continue;
+    }
+    summary.total++;
+    if (task.status === "in_progress") summary.active++;
+    if (task.status === "blocked") summary.blocked++;
+    if (task.status === "completed") summary.completed++;
+    if (task.status === "pending") {
+      summary.pending++;
+      const dependenciesResolved = task.blockedBy.every((id) => {
+        const status = statusById.get(id);
+        return status === undefined || status === "completed" || status === "cancelled";
+      });
+      if (dependenciesResolved) summary.ready++;
+    }
+  }
+
+  return summary;
+}