integrate-todo-list

集成待办事项列表

添加 TodoWrite 工具和面板，让应用内的 Atlas Agent 能展示任务进度。

如果应用使用 Atlas / EOS 侧边栏（integrate-fusion-agent），请跳过。前置条件：来自 integrate-atlas-chat 的 useAtlasChat、src/atlas-agent/ 和 @sinclair/typebox。

---

步骤 1 — 阅读应用

开始编写前，先阅读：

• package.json — 确认已安装 @tabler/icons-react；如果没有，请使用应用的包管理器安装
• src/App.tsx — 找出添加 TodoProvider 的位置
• 调用 useAtlasChat 的文件（通常是 src/chat/useChatViewModel.ts 或 src/App.tsx）— 在这里接入工具
• 渲染消息的聊天视图组件 — 在这里添加 TodoPanel 和 TodoToolResultCard

---

步骤 2 — 创建 src/todo/ 模块

从项目根目录运行 find . -path "*/.agents/skills/integrate-todo-list/code" -type d，找到技能目录。

读取 <skill-dir>/code/ 中的每个文件，并使用相同的文件名将其写入 src/todo/：

文件	用途
types.ts	TodoItem 和 TodoList 类型
TodoContext.tsx	React 上下文 + TodoProvider
useTodoList.ts	读取/写入待办事项列表的 Hook
todoWriteTool.ts	createTodoWriteTool 工厂 — AtlasTool，包含完整的 CDF 任务分解指导
useTodoWriteTool.ts	使用当前状态访问权限记忆该工具的 Hook
TodoPanel.tsx	卡片 UI：进度条 + 任务行
TodoItemRow.tsx	包含动画状态图标的单行
TodoToolResultCard.tsx	用于展示工具调用的精简摘要卡片

所有文件均使用相对导入（./types、./TodoContext 等），无需修改。

---

步骤 3 — 使用 TodoProvider 包裹应用

在 src/App.tsx（或根组件）中，使用 <TodoProvider> 包裹现有组件树：

import { TodoProvider } from './todo/TodoContext'; // adjust path to match app conventions

function App() {
  return (
    <TodoProvider>
      {/* existing children */}
    </TodoProvider>
  );
}

---

步骤 4 — 将工具接入 useAtlasChat

在调用 useAtlasChat 的文件中，添加以下内容。根据应用的惯例调整导入路径。

import { useRef, useCallback } from 'react';
import { useTodoList } from './todo/useTodoList';
import { useTodoWriteTool } from './todo/useTodoWriteTool';

// Inside the hook/component:
const { todos, setTodos } = useTodoList();
const todoWriteTool = useTodoWriteTool();

// Keep a ref so getAppContext always reads fresh state without re-creating the callback.
const todosRef = useRef(todos);
todosRef.current = todos;

const getAppContext = useCallback(() => {
  const t = todosRef.current;
  if (t.length === 0) return undefined;
  const lines = t.map((item, i) => `${i + 1}. [${item.status}] ${item.content}`);
  return `Current todo list:\n${lines.join('\n')}`;
}, []);

// Add to useAtlasChat options:
const { messages, send, isStreaming, progress, error, reset, abort } = useAtlasChat({
  client: isLoading ? null : sdk,
  agentExternalId: AGENT_EXTERNAL_ID,
  tools: [todoWriteTool],   // add alongside any existing tools
  getAppContext,
});

// In the reset handler, clear the todo list:
const handleReset = useCallback(() => {
  reset();
  setTodos([]);
}, [reset, setTodos]);

// Expose todos in the return value so the view can render TodoPanel:
return { ..., todos };

---

步骤 5 — 在聊天视图中渲染 TodoPanel

在渲染聊天输入区域的组件中，在输入框上方添加 <TodoPanel>：

import { TodoPanel } from './todo/TodoPanel'; // adjust path

// In the render:
<TodoPanel todos={todos} />
<YourChatInput ... />

待办事项列表为空时，TodoPanel 会返回 null，因此始终渲染它也没有问题。

---

步骤 6 — 为工具调用步骤渲染 TodoToolResultCard

在渲染每条消息的工具调用的组件中（通常是步骤折叠面板或类似组件），根据工具名称进行分支处理：

import { TodoToolResultCard } from './todo/TodoToolResultCard'; // adjust path

{toolCalls.map((tc, i) =>
  tc.name === 'TodoWrite' ? (
    <TodoToolResultCard key={i} toolCall={tc} />
  ) : (
    <YourDefaultToolCallCard key={i} toolCall={tc} />
  )
)}

---

步骤 7 — 验证

运行应用的类型检查命令（通常为 pnpm tsc --noEmit），并确认没有错误。 如果项目包含测试，请运行测试以确认没有引入回归问题。

---

完成

现在，Agent 可以使用 TodoWrite 创建和跟踪任务。它将：

• 开始多步骤任务后立即显示任务面板
• 实时更新任务状态（pending → in_progress → completed）
• 所有任务完成后自动清空列表
• 通过 getAppContext 将当前任务列表注入每条提示词，让 Agent 知道进度停在哪里