integrate-todo-list

集成待办事项列表

为此 Dune 应用添加结构化任务跟踪功能。Agent 在处理多步骤查询时会使用 TodoWrite 工具创建并更新任务列表，让用户实时了解 Agent 正在做什么以及原因。

**前置条件：**必须已设置 integrate-atlas-chat；useAtlasChat 必须已接入，并且必须已安装 @cognite/dune-industrial-components、@sinclair/typebox、ajv 和 ajv-formats。

---

步骤 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 context + TodoProvider
useTodoList.ts	用于读取和写入待办事项列表的 Hook
todoWriteTool.ts	createTodoWriteTool 工厂 — 带有完整 CDF 任务分解指导的 AtlasTool
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 将当前任务列表注入每条提示词，使其了解任务进度