TaskToAgent · 本地任务看板

简体中文 | English

人和 agent 写在同一块本地看板上：任务分七列流转，谁认领、做到哪一步、卡在哪里，一眼看清。

它是什么

一个本地优先的任务看板，用 t2a 命令行快速增删改查，配合网页看板可视化操作，两端读写同一份 SQLite 数据库。零外部依赖，不联网、不登录，数据全在你自己机器上。设计目标是让 AI agent 也能用同一套机制接任务：认领、续租、写日志、交付产出，全部有结构化的接口。

Related MCP server: AgentTasker

特性

• 零外部依赖 —— 只用 Node 内置模块，无需 npm install 即可启动，构建产物已随仓库提交。

• 本地存储 —— 数据落在本地 SQLite 文件（默认 ~/.t2a/t2a.db），不联网、不依赖任何云服务。

• 中英双语界面 —— 设置菜单里一键切换，偏好记在浏览器本地；首次打开按浏览器语言自动选择。

• 双端互通 —— 命令行与网页看板读写同一份数据库，任一边改动，另一边立即可见。

• 七列看板 —— 灵感区 → 待办 → 进行中 → 阻塞 → 待验收 → 已完成 → 存档，面板内可直接添加、拖动。

• 原子认领 —— task next 用单条 UPDATE ... WHERE 完成认领，多个 agent 同时抢也不会拿到同一条任务。

• 租约心跳 —— 认领默认带 30 分钟租约，长任务定期 heartbeat 续租；到期自动回收回待办并留下系统日志。

• 依赖编排 —— 支持任务依赖 DAG（等 A 完成才能做 B），加边时自动检测环，ready 只列出可开工任务。

• 结构化输出 —— 所有命令支持 --json，统一返回 {"ok":true,"data":...}；语义化退出码让 agent 不解析文本即可分支。

• MCP server —— t2a mcp 以 stdio JSON-RPC 暴露 22 个工具，支持 MCP 的 agent 可直接调用，不用拼命令。

• 审计与备份 —— 所有写操作记入 events 审计流水，t2a db backup 做自包含快照。

快速开始

环境要求

存储用 Node 内置的 node:sqlite，要求 Node.js >= 22.13（22.12 实测报 ERR_UNKNOWN_BUILTIN_MODULE）。跑不起来先自检：

node bin/t2a doctor

本地使用

# 网页看板（默认 http://127.0.0.1:3979）
npm run web

# 命令行
node bin/t2a help

界面说明

顶栏右侧一排图标，从左到右依次是搜索、新建任务、设置。设置菜单把偏好收在一处：

界面语言的选择存在浏览器本地（t2a-lang），只影响这一台设备；命令行输出仍是中文。

命令行速查

看板与任务

agent 联动

审计与维护

状态与退出码

看板七个列对应一个 status 值：

退出码是给 agent 用的，不必解析文本即可分支：

常见 code：NO_TASK CONFLICT DEP_NOT_READY NOT_FOUND USAGE CONFIRM_REQUIRED INVALID_DEP EXISTS。

环境变量

TASKCLI_* 是历史名称（项目原名 taskcli），仍被识别但优先级低于 T2A_*，老脚本无需修改。

agent 接入

支持 MCP 的客户端直接配 server，不用拼 shell：

node bin/t2a mcp --print-config

协议 2024-11-05，stdio JSON-RPC，暴露 22 个工具：project_list/add、task_list/show/search/add/update、task_next/claim/heartbeat/release/done/fail、task_log/logs、task_deps/dep_add/dep_rm、task_ready、task_assign、task_report、events。完整约定见 AGENT.md。

不支持 MCP 也可以用 CLI，一次标准循环：

export T2A_AGENT=codebuddy
t2a task next --json            # 取任务（自动认领 + 置为进行中）
t2a task log 12 "定位到问题在 src/db.js:88"
t2a task heartbeat 12 --lease 30m
t2a task done 12 --result "已修复并补测试"

agent 身份由服务端配置决定，不采信 agent 自报的名字；填错了会自动纠正：

t2a config set agent workbuddy
t2a config alias codebuddy workbuddy

数据与隐私

数据只存在本机，不上传任何地方，页面也没有第三方统计。存储位置与作用：

.db 文件已列入 .gitignore，不会被误提交。给每个 agent 单独开一个库即可隔离：T2A_DB=/path/to/agent.db t2a task list。

网页服务默认只监听 127.0.0.1。确需局域网访问时用 T2A_HOST=0.0.0.0 npm run web，注意没有任何鉴权，仅在可信网络里这么做。

目录结构

TaskToAgent/
├── bin/t2a            # CLI 入口（可执行）
├── src/
│   ├── brand.js       # 品牌与路径解析（T2A_* 优先、TASKCLI_* 兼容）
│   ├── config.js      # 默认 agent 身份 + 错误名自动纠正
│   ├── db.js          # 建表 + 认领/租约/依赖等协作原语（node:sqlite）
│   ├── report.js      # 任务与项目报告、产物汇总
│   ├── agent-guide.js # 内置 agent 上手指南
│   ├── sqlite-guard.js# Node 版本前置检查（给友好报错而非模块堆栈）
│   ├── cli.js         # CLI 全部命令逻辑
│   └── mcp.js         # MCP server（stdio JSON-RPC，零依赖）
├── AGENT.md           # agent 接入约定（MCP 配置 / 标准循环 / 规矩）
├── web/
│   ├── server.js      # 零依赖 http 服务：REST API + 托管前端
│   ├── dist/          # 前端构建产物（已提交，开箱即用）
│   └── ui/            # 前端源码（Vite + React + Arco Design）
│       └── src/i18n.jsx  # 中英双语文案字典与语言切换
├── docs/              # README 配图
└── package.json

开发说明

改后端直接改 src/ 下对应文件，无需构建。改前端需要重新构建并提交产物：

cd web/ui && npm install && npm run build

前端产物落在 web/dist，已提交到仓库，所以别人 clone 下来直接 npm run web 就能用，不必装前端依赖。

浏览器支持

网页看板是构建后的现代浏览器应用，需要支持 fetch 与 CSS Grid 的版本（Chrome / Edge / Firefox / Safari 近两年版本均可）。命令行与 MCP 不依赖浏览器。界面是响应式布局，窄屏下七列可横向滚动。

许可

MIT © 2026 isnotry