@ilikexiaoni/pi-task-list 0.4.0

package/extensions/task-list.ts

@@ -0,0 +1,527 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Text, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+  TASK_PRIORITIES,
+  TASK_STATUSES,
+  applyTaskAction,
+  cloneState,
+  filterTasks,
+  isTaskReady,
+  normalizeState,
+  priorityLabel,
+  statusLabel,
+  summarizeState,
+  type Task,
+  type TaskAction,
+  type TaskCommand,
+  type TaskPriority,
+  type TaskState,
+  type TaskStatus,
+} from "../lib/task-list-core.ts";
+
+const TOOL_NAME = "task_list";
+const WIDGET_KEY = "task-list-widget";
+const STATUS_KEY = "task-list-status";
+
+interface TaskListDetails {
+  action: TaskAction;
+  state: TaskState;
+  changedIds: number[];
+  visibleTasks: Task[];
+  selectedTask?: Task;
+  message: string;
+}
+
+const TaskListParams = Type.Object({
+  action: StringEnum(["create", "update", "list", "get", "clear"] as const),
+  id: Type.Optional(Type.Number({ minimum: 1, description: "目标任务 ID" })),
+  subject: Type.Optional(Type.String({ description: "任务标题；create 必填" })),
+  description: Type.Optional(Type.String({ description: "任务背景和范围" })),
+  activeForm: Type.Optional(Type.String({ description: "进行中时显示的动作短语" })),
+  acceptanceCriteria: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "可验收的完成条件" })),
+  evidence: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "已取得的证据；可替换现有证据" })),
+  addEvidence: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "追加证据" })),
+  status: Type.Optional(StringEnum(TASK_STATUSES)),
+  priority: Type.Optional(StringEnum(TASK_PRIORITIES)),
+  blockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50, description: "硬依赖任务 ID" })),
+  addBlockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50 })),
+  removeBlockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50 })),
+  blockReason: Type.Optional(Type.String({ description: "阻塞原因；空字符串可清除" })),
+  tags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
+  addTags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
+  removeTags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
+  owner: Type.Optional(Type.String({ description: "负责人或执行单元" })),
+  completionNote: Type.Optional(Type.String({ description: "完成结论或验收说明" })),
+  note: Type.Optional(Type.String({ description: "追加一条进度记录" })),
+  query: Type.Optional(Type.String({ description: "list 的标题、描述、标签搜索词" })),
+  includeCancelled: Type.Optional(Type.Boolean()),
+  scope: Type.Optional(StringEnum(["finished", "all"] as const)),
+  confirm: Type.Optional(Type.Boolean({ description: "clear 的显式确认" })),
+});
+
+function compact(value: string, max = 76): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, Math.max(1, max - 3))}...` : text;
+}
+
+function priorityToken(priority: TaskPriority): string {
+  return priority === "high" ? "H" : priority === "medium" ? "M" : "L";
+}
+
+function taskStateSummary(state: TaskState): string {
+  const summary = summarizeState(state);
+  return `${summary.completed}/${summary.total} 已完成 | ${summary.active} 进行中 | ${summary.blocked} 阻塞 | ${summary.ready} 可开始${summary.cancelled ? ` | ${summary.cancelled} 已取消` : ""}`;
+}
+
+function taskLine(task: Task, state: TaskState, detailed = false): string[] {
+  const lines = [`#${task.id} [${statusLabel(task.status)}] [${priorityLabel(task.priority)}] ${task.subject}`];
+  if (detailed && task.activeForm && task.activeForm !== task.subject) lines.push(`  当前动作：${task.activeForm}`);
+  if (detailed && task.description) lines.push(`  说明：${task.description}`);
+  if (task.acceptanceCriteria.length > 0) {
+    lines.push(`  完成条件：${task.acceptanceCriteria.length} 项，证据 ${task.evidence.length} 项`);
+    if (detailed) task.acceptanceCriteria.forEach((item, index) => lines.push(`    ${index + 1}. ${item}`));
+  }
+  if (task.evidence.length > 0 && detailed) task.evidence.forEach((item) => lines.push(`  证据：${item}`));
+  if (task.blockedBy.length > 0) lines.push(`  依赖：${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
+  if (task.status === "blocked" && task.blockReason) lines.push(`  阻塞原因：${task.blockReason}`);
+  if (task.owner) lines.push(`  负责人：${task.owner}`);
+  if (task.tags.length > 0) lines.push(`  标签：${task.tags.join(", ")}`);
+  if (task.completionNote && task.status === "completed") lines.push(`  完成说明：${task.completionNote}`);
+  if (detailed && task.notes.length > 0) {
+    for (const note of task.notes.slice(-3)) lines.push(`  记录${note.at ? ` [${note.at}]` : ""}：${note.text}`);
+  }
+  if (!detailed && task.status === "pending" && !isTaskReady(state, task)) lines.push("  等待依赖完成");
+  return lines;
+}
+
+function formatForModel(result: Pick<ApplyResultLike, "action" | "message" | "visibleTasks" | "selectedTask" | "state">): string {
+  const lines = [result.message, taskStateSummary(result.state)];
+  const tasks = result.action === "get" && result.selectedTask ? [result.selectedTask] : result.visibleTasks;
+  if (tasks.length === 0) {
+    lines.push("（没有符合条件的任务）");
+  } else {
+    const display = result.action === "list" ? tasks.slice(0, 50) : tasks.slice(0, 5);
+    for (const task of display) lines.push(...taskLine(task, result.state, result.action === "get"));
+    if (display.length < tasks.length) lines.push(`... 还有 ${tasks.length - display.length} 个任务，请使用 list 的 query/status 分批查看`);
+  }
+  return lines.join("\n");
+}
+
+interface ApplyResultLike {
+  action: TaskAction;
+  message: string;
+  visibleTasks: Task[];
+  selectedTask?: Task;
+  state: TaskState;
+}
+
+interface CompactWidgetTask {
+  id: number;
+  priority: TaskPriority;
+  subject: string;
+  activeForm: string;
+  blockReason: string;
+}
+
+interface CompactWidgetModel {
+  summary: ReturnType<typeof summarizeState>;
+  active?: CompactWidgetTask;
+  blocked?: CompactWidgetTask;
+  ready?: CompactWidgetTask;
+  recent?: CompactWidgetTask;
+  activeCount: number;
+  blockedCount: number;
+  readyCount: number;
+}
+
+function compactWidgetTask(task: Task | undefined): CompactWidgetTask | undefined {
+  if (!task) return undefined;
+  return {
+    id: task.id,
+    priority: task.priority,
+    subject: compact(task.subject),
+    activeForm: compact(task.activeForm || task.subject),
+    blockReason: compact(task.blockReason, 60),
+  };
+}
+
+function preferredWidgetTask(current: Task | undefined, candidate: Task): Task {
+  if (!current) return candidate;
+  const rank: Record<TaskPriority, number> = { high: 0, medium: 1, low: 2 };
+  return rank[candidate.priority] < rank[current.priority] || (candidate.priority === current.priority && candidate.id < current.id)
+    ? candidate
+    : current;
+}
+
+function compactWidgetModel(state: TaskState): CompactWidgetModel {
+  const summary = summarizeState(state);
+  const statusById = new Map(state.tasks.map((task) => [task.id, task.status]));
+  let active: Task | undefined;
+  let blocked: Task | undefined;
+  let ready: Task | undefined;
+  let recent: Task | undefined;
+
+  for (const task of state.tasks) {
+    if (task.status === "in_progress") active = preferredWidgetTask(active, task);
+    if (task.status === "blocked") blocked = preferredWidgetTask(blocked, task);
+    if (task.status === "pending") {
+      const dependenciesResolved = task.blockedBy.every((id) => {
+        const status = statusById.get(id);
+        return status === undefined || status === "completed" || status === "cancelled";
+      });
+      if (dependenciesResolved) ready = preferredWidgetTask(ready, task);
+    }
+    if (
+      task.status === "completed" &&
+      (!recent || task.updatedAt > recent.updatedAt || (task.updatedAt === recent.updatedAt && task.id > recent.id))
+    ) {
+      recent = task;
+    }
+  }
+
+  return {
+    summary,
+    active: compactWidgetTask(active),
+    blocked: compactWidgetTask(blocked),
+    ready: compactWidgetTask(ready),
+    recent: compactWidgetTask(recent),
+    activeCount: summary.active,
+    blockedCount: summary.blocked,
+    readyCount: summary.ready,
+  };
+}
+
+function extraCount(count: number): string {
+  return count > 1 ? `  +${count - 1}` : "";
+}
+
+function compactWidgetLines(model: CompactWidgetModel, theme: Theme, width: number): string[] {
+  const { summary } = model;
+  const percent = summary.total === 0 ? 0 : Math.round((summary.completed / summary.total) * 100);
+  const barWidth = width >= 88 ? 12 : width >= 60 ? 8 : 5;
+  const filled = summary.total === 0 ? 0 : Math.round((summary.completed / summary.total) * barWidth);
+  const barColor = percent === 100 ? "success" : "accent";
+  const bar = theme.fg(barColor, "━".repeat(filled)) + theme.fg("borderMuted", "─".repeat(barWidth - filled));
+  const counts = width >= 66 ? `进行中 ${summary.active}  阻塞 ${summary.blocked}` : `A${summary.active} B${summary.blocked}`;
+  const header = `${theme.fg("borderMuted", "┌─")} ${theme.bold(theme.fg("accent", "TASKS"))}  ${theme.fg("text", `${summary.completed}/${summary.total}`)}  ${bar} ${theme.fg("muted", `${percent}%`)}  ${summary.blocked > 0 ? theme.fg("error", counts) : theme.fg("muted", counts)}`;
+
+  const activeBody = model.active
+    ? `${theme.fg("accent", `#${model.active.id}`)} ${theme.fg("muted", `[${priorityToken(model.active.priority)}]`)} ${theme.fg("text", model.active.activeForm)}${theme.fg("muted", extraCount(model.activeCount))}`
+    : theme.fg("muted", "暂无进行中任务");
+
+  const focusBody = model.blocked
+    ? `${theme.fg("error", `#${model.blocked.id}`)} ${theme.fg("text", model.blocked.subject)}${model.blocked.blockReason ? theme.fg("muted", ` · ${model.blocked.blockReason}`) : ""}${theme.fg("muted", extraCount(model.blockedCount))}`
+    : model.ready
+      ? `${theme.fg("accent", `#${model.ready.id}`)} ${theme.fg("muted", `[${priorityToken(model.ready.priority)}]`)} ${theme.fg("text", model.ready.subject)}${theme.fg("muted", extraCount(model.readyCount))}`
+      : theme.fg("muted", "暂无可开始任务");
+
+  const recentBody = model.recent
+    ? `${theme.fg("success", `#${model.recent.id}`)} ${theme.fg("muted", model.recent.subject)}${summary.completed > 1 ? theme.fg("muted", ` · 另 ${summary.completed - 1} 项已完成`) : ""}`
+    : theme.fg("muted", "尚无已完成任务");
+
+  const focusLabel = model.blocked ? theme.fg("error", "! 阻塞  ") : theme.fg("accent", "○ 下一步");
+  const lines = [
+    header,
+    `${theme.fg("borderMuted", "│")} ${theme.fg("accent", "▶ 当前  ")} ${activeBody}`,
+    `${theme.fg("borderMuted", "│")} ${focusLabel} ${focusBody}`,
+    `${theme.fg("borderMuted", "│")} ${theme.fg("success", "✓ 最近  ")} ${recentBody}`,
+    `${theme.fg("borderMuted", "└─")} ${theme.fg("accent", "/tasks")} ${theme.fg("muted", "完整清单 · 验收条件 · 证据")}`,
+  ];
+
+  return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+}
+
+class CompactTaskWidget {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  constructor(
+    private model: CompactWidgetModel,
+    private fingerprint: string,
+    private readonly theme: Theme,
+    private readonly tui: TUI,
+  ) {}
+
+  update(model: CompactWidgetModel, fingerprint: string): boolean {
+    this.model = model;
+    if (fingerprint === this.fingerprint) return false;
+    this.fingerprint = fingerprint;
+    this.invalidate();
+    this.tui.requestRender();
+    return true;
+  }
+
+  render(width: number): string[] {
+    if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+    this.cachedWidth = width;
+    this.cachedLines = compactWidgetLines(this.model, this.theme, width);
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+
+function hasPersistedState(value: unknown): value is { state?: unknown; tasks?: unknown[] } {
+  return typeof value === "object" && value !== null && ("state" in value || "tasks" in value);
+}
+
+function restoreState(ctx: ExtensionContext): TaskState {
+  let restored: TaskState | undefined;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "custom" && entry.customType === "task-list-state" && hasPersistedState(entry.data)) {
+      restored = normalizeState(entry.data.state ?? entry.data);
+      continue;
+    }
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (message.role !== "toolResult" || message.toolName !== TOOL_NAME) continue;
+    const details = message.details as Partial<TaskListDetails> | undefined;
+    if (details?.state) restored = normalizeState(details.state);
+  }
+  return restored ?? normalizeState(undefined);
+}
+
+function statusColor(theme: Theme, status: TaskStatus, text: string): string {
+  switch (status) {
+    case "completed":
+      return theme.fg("success", text);
+    case "blocked":
+      return theme.fg("error", text);
+    case "in_progress":
+      return theme.fg("accent", text);
+    case "cancelled":
+      return theme.fg("dim", text);
+    default:
+      return theme.fg("text", text);
+  }
+}
+
+class TaskListComponent {
+  private readonly state: TaskState;
+  private readonly theme: Theme;
+  private readonly title: string;
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  private readonly onClose: () => void;
+
+  constructor(state: TaskState, theme: Theme, title: string, onClose: () => void) {
+    this.state = state;
+    this.theme = theme;
+    this.title = title;
+    this.onClose = onClose;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.onClose();
+  }
+
+  render(width: number): string[] {
+    if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+    const lines: string[] = [];
+    const summary = summarizeState(this.state);
+    const header = this.theme.fg("borderMuted", "─".repeat(3)) + this.theme.fg("accent", ` ${this.title} `) + this.theme.fg("borderMuted", "─".repeat(Math.max(0, width - 12)));
+    lines.push("");
+    lines.push(truncateToWidth(header, width));
+    lines.push(truncateToWidth(`  ${taskStateSummary(this.state)}`, width));
+    lines.push("");
+
+    const tasks = filterTasks(this.state, { includeCancelled: true });
+    if (tasks.length === 0) {
+      lines.push(truncateToWidth(`  ${this.theme.fg("dim", "当前没有任务")}`, width));
+    } else {
+      for (const task of tasks) {
+        const mark = task.status === "completed" ? "[x]" : task.status === "cancelled" ? "[-]" : task.status === "blocked" ? "[!]" : task.status === "in_progress" ? "[>]" : "[ ]";
+        lines.push(truncateToWidth(`  ${statusColor(this.theme, task.status, mark)} ${this.theme.fg("accent", `#${task.id}`)} [${priorityLabel(task.priority)}] ${task.subject}`, width));
+        if (task.status === "in_progress") lines.push(truncateToWidth(`      动作：${task.activeForm}`, width));
+        if (task.description) lines.push(truncateToWidth(`      说明：${task.description}`, width));
+        if (task.acceptanceCriteria.length > 0) {
+          lines.push(truncateToWidth(`      完成条件：${task.evidence.length}/${task.acceptanceCriteria.length} 项已有证据`, width));
+          for (const criterion of task.acceptanceCriteria) {
+            lines.push(truncateToWidth(`        - ${criterion}`, width));
+          }
+        }
+        if (task.evidence.length > 0) {
+          lines.push(truncateToWidth("      证据：", width));
+          for (const evidence of task.evidence) lines.push(truncateToWidth(`        - ${evidence}`, width));
+        }
+        if (task.blockedBy.length > 0) lines.push(truncateToWidth(`      依赖：${task.blockedBy.map((id) => `#${id}`).join(", ")}`, width));
+        if (task.status === "blocked" && task.blockReason) lines.push(truncateToWidth(`      阻塞：${task.blockReason}`, width));
+        if (task.notes.length > 0) lines.push(truncateToWidth(`      最近记录：${task.notes.at(-1)?.text ?? ""}`, width));
+        if (task.status === "completed" && task.completionNote) lines.push(truncateToWidth(`      完成说明：${task.completionNote}`, width));
+      }
+    }
+    lines.push("");
+    lines.push(truncateToWidth(`  ${this.theme.fg("dim", "按 Escape 关闭")}`, width));
+    lines.push("");
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+
+function commandFilter(state: TaskState, args: string): { state: TaskState; title: string } {
+  const filter = args.trim();
+  if (!filter || filter.toLowerCase() === "all") return { state: cloneState(state), title: "Tasks" };
+  const lower = filter.toLowerCase();
+  if (/^#?\d+$/.test(lower)) {
+    const id = Number(lower.replace(/^#/, ""));
+    return { state: { ...cloneState(state), tasks: state.tasks.filter((task) => task.id === id) }, title: `Task #${id}` };
+  }
+  const statusMap: Record<string, TaskStatus> = {
+    active: "in_progress",
+    in_progress: "in_progress",
+    blocked: "blocked",
+    pending: "pending",
+    completed: "completed",
+    done: "completed",
+    cancelled: "cancelled",
+  };
+  if (statusMap[lower]) {
+    return { state: { ...cloneState(state), tasks: filterTasks(state, { status: statusMap[lower], includeCancelled: true }) }, title: `Tasks: ${statusLabel(statusMap[lower])}` };
+  }
+  return { state: { ...cloneState(state), tasks: filterTasks(state, { query: filter, includeCancelled: true }) }, title: `Tasks: ${filter}` };
+}
+
+export default function taskListExtension(pi: ExtensionAPI) {
+  let state = normalizeState(undefined);
+  let compactWidget: CompactTaskWidget | undefined;
+  let rpcWidgetFingerprint: string | undefined;
+  let lastStatusText: string | undefined;
+
+  const refreshUi = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI) return;
+
+    const model = compactWidgetModel(state);
+    const fingerprint = JSON.stringify(model);
+    if (ctx.mode === "tui") {
+      if (compactWidget) {
+        compactWidget.update(model, fingerprint);
+      } else {
+        ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+          compactWidget = new CompactTaskWidget(model, fingerprint, theme, tui);
+          return compactWidget;
+        });
+      }
+    } else if (rpcWidgetFingerprint !== fingerprint) {
+      ctx.ui.setWidget(WIDGET_KEY, compactWidgetLines(model, ctx.ui.theme, 96));
+      rpcWidgetFingerprint = fingerprint;
+    }
+
+    const currentText = model.active ? `#${model.active.id} ${compact(model.active.activeForm, 38)}` : "无进行中任务";
+    const statusText = `Tasks ${model.summary.completed}/${model.summary.total} · ${currentText} · 阻塞 ${model.summary.blocked}`;
+    if (statusText !== lastStatusText) {
+      ctx.ui.setStatus(STATUS_KEY, statusText);
+      lastStatusText = statusText;
+    }
+  };
+
+  const clearUi = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setWidget(WIDGET_KEY, undefined);
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+    compactWidget = undefined;
+    rpcWidgetFingerprint = undefined;
+    lastStatusText = undefined;
+  };
+
+  const restoreAndRefresh = (ctx: ExtensionContext) => {
+    state = restoreState(ctx);
+    refreshUi(ctx);
+  };
+
+  pi.on("session_start", async (_event, ctx) => restoreAndRefresh(ctx));
+  pi.on("session_tree", async (_event, ctx) => restoreAndRefresh(ctx));
+  pi.on("session_shutdown", async (_event, ctx) => clearUi(ctx));
+  pi.on("session_compact", async () => {
+    pi.appendEntry("task-list-state", { state: cloneState(state) });
+  });
+
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: "Task List",
+    description: "Manage a structured task list with incremental updates, acceptance criteria, evidence, dependencies, blockers, priorities, notes, and branch-aware session state.",
+    promptSnippet: "Manage the structured task list with dependencies, evidence, and visible progress",
+    promptGuidelines: [
+      "Use task_list for multi-step work instead of maintaining an unstructured plan in prose.",
+      "Create atomic tasks with a clear subject and acceptanceCriteria that can be checked independently.",
+      "Use task_list update to mark work in_progress before starting; each acceptance criterion needs an evidence entry before completion.",
+      "Use task_list update with note to record a meaningful milestone, blocker, or next action; do not hide a blocker in a completed task.",
+      "Use blockedBy for hard task dependencies; dependency blockers are managed automatically, while manual blockers require an explicit blockReason and explicit release.",
+      "After changing task state, explain to the user what completed, what is current, and what happens next.",
+    ],
+    parameters: TaskListParams,
+    executionMode: "sequential",
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (signal?.aborted) throw new Error("Task list operation cancelled");
+      const result = applyTaskAction(state, params as TaskCommand);
+      state = result.state;
+      if (result.mutated) {
+        pi.appendEntry("task-list-state", { state: cloneState(state) });
+      }
+      refreshUi(ctx);
+
+      const details: TaskListDetails = {
+        action: result.action,
+        state: cloneState(state),
+        changedIds: [...result.changedIds],
+        visibleTasks: result.visibleTasks.map((task) => ({ ...task, acceptanceCriteria: [...task.acceptanceCriteria], evidence: [...task.evidence], blockedBy: [...task.blockedBy], tags: [...task.tags], notes: task.notes.map((note) => ({ ...note })) })),
+        selectedTask: result.selectedTask,
+        message: result.message,
+      };
+
+      return {
+        content: [{ type: "text", text: formatForModel(result) }],
+        details,
+      };
+    },
+
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("task_list ")) + theme.fg("muted", args.action);
+      if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
+      if (args.subject) text += ` ${theme.fg("dim", `"${compact(args.subject, 64)}"`)}`;
+      if (args.status) text += ` ${theme.fg("muted", `[${args.status}]`)}`;
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, context) {
+      const details = result.details as TaskListDetails | undefined;
+      const fallback = result.content.find((part) => part.type === "text");
+      if (!details) return new Text(theme.fg(context.isError ? "error" : "muted", fallback?.type === "text" ? fallback.text : ""), 0, 0);
+
+      const lines = [theme.fg(context.isError ? "error" : "success", details.message), theme.fg("muted", taskStateSummary(details.state))];
+      const tasks = details.action === "get" && details.selectedTask ? [details.selectedTask] : details.visibleTasks;
+      const display = expanded ? tasks.slice(0, 20) : tasks.slice(0, 4);
+      for (const task of display) {
+        const mark = task.status === "completed" ? "✓" : task.status === "blocked" ? "!" : task.status === "in_progress" ? ">" : task.status === "cancelled" ? "-" : "○";
+        lines.push(`${statusColor(theme, task.status, mark)} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(task.status === "completed" ? "dim" : "text", task.subject)} ${theme.fg("dim", `[${priorityLabel(task.priority)}]`)}`);
+        if (expanded && task.status === "blocked" && task.blockReason) lines.push(`  ${theme.fg("error", task.blockReason)}`);
+        if (expanded && task.acceptanceCriteria.length > 0) lines.push(`  ${theme.fg("muted", `完成条件证据：${task.evidence.length}/${task.acceptanceCriteria.length}`)}`);
+      }
+      if (display.length < tasks.length) lines.push(theme.fg("dim", `... 还有 ${tasks.length - display.length} 个任务`));
+      return new Text(lines.join("\n"), 0, 0);
+    },
+  });
+
+  pi.registerCommand("tasks", {
+    description: "查看当前分支的完整任务清单；可按 all、active、blocked、pending、done、ID 或关键词筛选",
+    handler: async (args, ctx) => {
+      const selected = commandFilter(state, args);
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify(formatForModel({ action: "list", message: selected.title, visibleTasks: selected.state.tasks, state: selected.state }), "info");
+        return;
+      }
+      await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => new TaskListComponent(selected.state, theme, selected.title, () => done()));
+    },
+  });
+}