Skip to content

denvey/ai-todos

v0.1.2

独立本地任务、项目、OKR、计划、交付验收与专注工作台

GitHub

Todos · 任务

英文产品名 Todos，中文显示名 任务。插件安装标识仍为 ai-todos@ai-todos-local。当前侧边栏配置使用中文名，工作台页面标题按宿主或浏览器语言显示；官方本地插件显示名配置未确认支持自动语言切换。

可独立运行的 Codex 桌面端任务与专注管理插件。自带本地 MCP 服务、完整 Web 应用和 SQLite 持久化存储，不需要 Xinmo Desktop、心魔 Gateway、OpenClaw 或 NAS。

当前版本：0.1.2。代码、可安装插件包和本地应用均已实现。Codex 内置浏览器路径已实际运行；MCP Apps 资源及 global / thread 入口元数据已实现，用户当前 Codex 客户端已确认原生侧边栏入口和全屏工作台可用，会话面板的宿主渲染尚未确认，详见 宿主支持与验证记录。

界面采用紧凑顶部页签，没有网页左侧栏。嵌入 MCP Apps 时使用宿主提供的颜色、字体、圆角与明暗主题；浏览器里使用系统字体和中性黑白样式。顶部页签属于应用自身，原生 Codex 组件和侧栏入口仍需客户端支持，不能用页面样式替代。

界面使用 React，直接复用心魔的 Radix Select、Popover 和中文 DayPicker；四列看板、折叠卡片、任务详情、OKR 和专注布局从心魔组件适配。数据调用接到本项目服务，运行时不依赖心魔或 Tauri。对话框使用同一版本系列的 Radix Dialog，输入框和时间字段保留 HTML 控件。ext-apps SDK 提供宿主通信与主题接入，这些组件不属于 Codex 原生组件。详见 组件复用范围。

从 GitHub 安装到 Codex

需要支持插件安装的 Codex CLI、Git，以及 Node.js 24+。请确保 Codex 启动环境的 PATH 能找到 node 和 codex。

codex plugin marketplace add denvey/ai-todos
codex plugin add ai-todos@ai-todos-local

仓库附带预构建插件，安装无需运行 npm 或编译。安装后开启新会话，输入“打开 ai-todos 工作台”；用 /hooks 审阅并信任插件 hooks，才能接收兼容模式的 AI 运行事件。历史会话同步无需 hooks。若客户端没有显示 MCP App，使用工具返回的本地浏览器地址。用户当前客户端已确认侧边栏入口可用。

发布包使用 Codex 原生 .codex-plugin/plugin.json。当前 Codex 会跳过通用 Agent Plugins 格式中的 hooks，因此包内不同时放根 plugin.json。若正在执行的会话仍显示未知，在终端运行 codex，通过 /hooks 检查 ai-todos 的 8 个事件是否已启用并信任，再重新打开需要跟踪的会话。工作台没有收到运行事件时会显示提示；历史同步不会覆盖已观察到的运行状态。

已添加同名本地 marketplace 的开发者应先按 codex plugin marketplace --help 管理现有来源，避免来源名称冲突。源码开发和本机打包方法见下文。

快速开始

需要 Node.js 24+（包含内置 SQLite）及 npm。任务、计时和人工审阅可离线运行；同步项目和 AI 完善需要支持 project/list 的 Codex CLI，AI 完善沿用 Codex 已有登录及模型配置，无需给本插件另外填写 API key。

在当前 ai-todos checkout 目录执行：

npm ci
npm run package:plugin
npm run open

npm run open 自动启动本地服务并打开 http://127.0.0.1:16943。也可以前台运行 npm start，或让 Codex 的内置浏览器打开该地址。

默认真实数据存储于 ~/.ai-todos/ai-todos.sqlite。第一次打开是空工作台，无示例数据或模拟后端。服务只监听 127.0.0.1，不对局域网开放。

从源码安装到 Codex

先执行 npm run package:plugin，生成含运行时代码、UI、技能和 hooks 的 plugins/ai-todos/。包内已捆绑依赖，宿主启动时不运行 npm、不访问网络。构建时写入当前机器的 Node 绝对路径；换机器或升级 Node 路径后重新打包。

codex plugin marketplace add /absolute/path/to/ai-todos
codex plugin add ai-todos@ai-todos-local

当前机器已成功执行这两步。若 CLI 不支持安装子命令，在桌面端 Plugins 中选择 ai-todos Local 本地来源安装。部分客户端需要重启后才能发现本地 marketplace；请先保存正在进行的工作。

  1. 安装后开启一个新会话，必要时重启桌面端。
  2. 用 /hooks 审阅并信任 ai-todos 的 hooks。安装插件不会自动信任 hooks；不信任时不会收到 hook 运行事件；官方接口已同步的会话仍可关联。
  3. 在新会话中输入“打开 ai-todos”，调用 ai_todos_open。
  4. 若出现 MCP App，可以使用其完整界面。若宿主不显示自定义入口或 UI，打开工具返回的 browserUrl，或让 Codex 使用内置浏览器打开它。

global 与 thread 元数据使用官方协议声明。没有伪造已注册连接 ID，没有把普通 sidebar section 当作插件应用。当前实现的可靠入口是本地 Web 应用／Codex 内置浏览器。

仅连接 MCP（不安装插件）

codex mcp add ai-todos -- /absolute/path/to/node /absolute/path/to/ai-todos/src/mcp.js

或 Settings → MCP servers → Add server → STDIO，填写同样的 command / args。开启新会话后调用工具。只添加 MCP 不会安装技能和 hooks；要使用可信 AI 会话观察，请安装完整插件。两种连接方式选一种，避免同名工具重复。

使用

工作与排期

  • 首页：展示专注统计、计时控制与今日任务，顶部主导航保留首页、任务、项目、OKR，设置在右侧。复用心魔今日任务与快捷输入栏。Enter 加入今天，⌥/Alt+Enter 存入收件箱；右侧悬停展开收件箱和完整任务入口，键盘与触屏均可用。AI 完善标题、说明与验收标准，可选择保留单项或一次拆成多项；失败保留输入，重试不重复创建。
  • 收件箱：从首页今日任务区进入，独立保存原始想法，不进入任务、逾期和专注列表。支持搜索、待整理／已整理筛选、AI 整理预览、转为任务、加入今天、归档与恢复；转为任务后保留原始想法。AI 整理预览在当前页面会话内保留，刷新后需重新生成。
  • 安排今天：从待办池勾选任务，全部加入／清空未完成，查看今日结束与历史验收任务，填写备注。取消勾选只移出今日。当天原有多个计划显示成员并集，保存保留各计划名称和其他内容；新增成员与今日备注进入按创建时间、ID 排序的首个计划。旧版本保存被拒绝，不覆盖其他页面的新安排。
  • 任务：名称、说明、验收标准、优先级、项目、KR、提醒时间及计划起止时间。排期和提醒使用一体式日期时间选择器，在同一弹层选择日期和时间后点击“确定”；可清除或填入现在，Escape 取消本次选择。标题右侧“AI 完善”根据当前草稿完善标题、说明和验收标准；说明、验收标准右侧“AI 补齐／AI 再优化”只优化对应字段，并参考其他已填写内容。建议先预览，选择“应用优化”后填写到表单，点击保存才写入数据库。
  • 看板：沿用心魔四列分组：未开始（定义中、已就绪、待修改）、进行中（执行中）、需要你处理（待验收）、已完成（已验收）。卡片默认折叠，具体业务状态与 AI 观察状态始终显示；展开可看优先级、项目、排期和版本。完成任务超过五项时提供历史展开，取消任务另列。窄面板按两列排列，组内拖动不改变状态；不能拖拽制造交付或验收。
  • Codex 会话同步：打开工作台时直接读取官方 app-server 会话目录，页面打开期间每 30 秒同步，任务页“刷新”可立即同步。包含未归档主会话，排除子代理和临时草稿；使用会话 ID 去重，同步标题、预览、目录与更新时间。仅隐藏已被任务卡片实际覆盖的会话状态；已验收任务再次运行时仍展示新的会话活动，可按项目目录与文本筛选。卡片支持“打开原会话”；空闲或结束的会话显示“待确定”；未关联业务任务时，可由用户点击“确认完成”或拖到已完成列进行确认，后续运行或目录记录更新时自动清除旧确认。展开区只显示小号 Codex 图标、目录名、时间和确认记录，不展示整段会话预览。确认校验用户实际看到的观察版本，拒绝过期操作；关联业务任务仍走交付验收。活动会话每列先显示 50 个，点击“更多会话”继续加载。运行状态未知的会话放在默认折叠的“其他 Codex 会话”中，不计入未开始任务；展开后同样分批加载。看板列分别显示任务和会话数量。会话卡片不自动创建业务任务或验收记录。运行状态优先使用 codex app-server proxy 连接已有宿主；默认控制 socket 不可用时读取持久化目录，实时状态由可信 hooks 补充。notLoaded 显示未知，Stop／空闲进入需要你处理，不视为验收完成。历史同步不需要模型调用，也不会继续执行会话；本机历史会话预览只保存于本地数据库。
  • 心魔状态迁移：完整保留 6 个交付阶段和 9 个 AI 运行状态的展示与归类规则；定义中的关联任务按规划模式显示“正在规划”，规划本轮结束后进入“需要你处理”，等待确定要求。就绪及后续阶段按执行模式显示。模式从当前任务阶段计算，不写入会话数据。已提交交付显示“待我验收”，尚未人工确定的 AI 结果显示“待确定”。已关联任务的等待、失败、本轮结束和状态未确认参与看板归类，中断后回到可以开始。首页、看板与详情共用状态文案；已完成任务和会话合并显示最近 5 项。具体字段适配与宿主能力见 状态迁移对照。
  • 打开 Codex：卡片与详情页使用同一入口，有关联时直接打开原会话；未关联的定义中、已就绪、待修改任务则新建会话，带入任务说明、验收标准和项目目录。Codex MCP 面板通过 ui/message 请求宿主使用 create_thread，创建方核对宿主返回的 threadId 与已观察会话，使用现有 bind 规则关联原任务，确认关联成功后再打开。任务卡片随后按关联会话的运行状态更新列和状态，不另建业务任务，也不自动开始业务执行。独立浏览器页提供指令，需复制到 Codex 对话发送。详情有未保存更改时，先保存再新建；打开已有会话不要求保存表单。请求发出不代表创建或关联成功，以实际返回与快照为准；宿主必须提供消息和会话创建工具。
  • 时间线／甘特图：与看板共用任务、项目、状态；日／周／月缩放、横向浏览、项目筛选、搜索、拖动移动、两端调整时间。键盘 ← / → 移动一天，Shift + ← / → 调整结束时间；任务详情提供精确日期输入。未排期任务单独展示。
  • 项目：打开应用时同步 Codex 的注册项目，也可在项目页或任务编辑器点击“同步 Codex 项目”。保留项目来源 ID 和工作目录，同一项目的多个目录分别展示，重复同步不会重复创建。名称由 Codex 维护，本地说明和任务关联保留；同步只新增和更新，不自动删除 Codex 中已移除的项目。本地自建项目继续可用。
  • OKR：目标与 KR，起始值、当前值、目标值和可选计量单位（如个、次、%、元）；支持增加或减少目标，任务可关联 KR。添加 KR 与编辑目标位于目标标题右侧。
  • 每日计划：从首页操作区进入，按日期选择已有任务、备注，可查看和编辑不同日期的清单；当天安排显示在首页，直接投影任务状态，不复制任务。
  • 删除：存在引用时拒绝删除。已执行、已关联会话或有计时记录的任务保留审计，使用取消操作。

AI 执行与人工验收

AI 完善使用临时 Codex 会话，只接收草稿和所选项目的名称、说明与目录，不读取项目文件。调用关闭执行、浏览器、插件、hooks 和外部 MCP 工具，使用只读权限与结构化输出；建议不会启动业务任务、绑定会话或改变状态。生成最长等待两分钟，失败时保留输入。草稿发送给 Codex 当前配置的模型服务。

定义需求与验收标准 → 就绪 → 绑定可信会话 → 开始执行
                                          ↓
                            真实交付 + 摘要 + 证据
                                          ↓
                                       待验收
                                 ↙                 ↘
                          人工退回修改          人工验收通过
                               ↓
                         继续执行并重新提交
  • 会话 ID 来自 Codex 官方 thread/list 或可信 hook 的 session_id；绑定前必须已经同步或观察到。一个未取消任务关联一个主会话，一个主会话不重复绑定其他任务。
  • “开始执行”记录业务意图，不会凭空启动 Codex。任务详情可生成执行指令；浏览器中复制到原会话，支持 ui/message 的 MCP App 中可由用户点击发送到当前对话。指令要求核对可信 sessionId；插件不猜测当前宿主会话 ID、不自动创建或路由到其他对话。
  • AI 徽标单独显示 hook 观察到的运行、等待许可、本轮结束、中断、会话结束。运行／等待事件超过 5 分钟未刷新时显示未知，保留最后事件时间；这不是持续遥测。
  • Stop / Interrupt / SessionEnd 只更新观察状态，不提交交付、不验收、不改变任务业务状态。
  • submit 必须有摘要和至少一条真实证据。证据为 HTTP(S) URL 或本地绝对路径；服务不读取、执行、验证证据文件，不允许带账号密码的 URL。
  • 人工验收和退回通过本地审阅页进行，MCP 不暴露验收工具。 审阅页显示验收标准、交付证据和实际版本；需填写审阅人并勾选明确确认。退回必须填写原因。MCP App 的审阅按钮打开同一任务的本地页面。
  • 编辑、排期、推进、提交、绑定、计时和配置均校验实际读取的 revision。审阅使用短时、一次性 ticket 绑定人实际看到的版本；任务变化后拒绝旧确认，不自动提升到最新版。
  • 审阅人名称是本地用户填写的审计标签，不是经过身份提供方认证的身份。任何有本机执行权限的进程仍属于信任边界；此版本不提供多用户、租户或远程权限模型。

首页专注统计与提醒设置

  • 每次只计时一个任务；支持开始、暂停、恢复、结束并记录。
  • 计时状态立即写入 SQLite，按时间戳恢复；面板关闭、重开或服务重启不丢记录。暂停区间不计入投入；结束后保留区间、时长和任务记录。
  • 首页展示选定日期投入、累计投入与记录数；明细可展开按日期、任务和项目查看，跨午夜区间分配到对应日期。统计使用浏览器本地时区，提醒时区可独立配置。
  • 运行中的计时是墙钟时间：关闭 Codex、服务退出、设备休眠期间仍累计，直到显式暂停或结束。需要避免离开时间被计入时，先暂停。
  • 在右侧设置页配置任务提醒、执行中任务跟进间隔、每日复盘时间和时区；提醒保存在提醒记录，支持标记已读。
  • 本地服务每 15 秒检查到期提醒。MCP 启动的服务独立于会话、退出 Codex 后通常继续运行；npm run stop 明确停止。系统重启、关机、休眠或服务被终止期间不调度；再次启动时补发当前到期提醒，每个提醒／跟进时段去重，不补发停机期间每一个历史跟进时段。
  • 系统浏览器通知需要用户授予权限且页面打开；页面关闭时提醒只保存在提醒记录。MCP 面板不保证系统通知。此版本不会唤醒 Codex、主动发消息、后台执行 AI 或安装开机常驻服务。

配置与数据

环境变量默认值用途
AI_TODOS_DATA_DIR~/.ai-todos服务、MCP 和 hooks 共用的数据目录
AI_TODOS_PORT16943回环 HTTP 端口，允许 1024–65535

修改环境变量时，必须让服务、插件 MCP 与 hooks 使用相同值。默认配置无需填写。不要把不同数据目录的服务放在同一个端口；若端口被占用，启动会报告错误而不会连接无凭据的其他服务。

runtime.json 包含仅供本地进程通信的随机凭据，以 0600 保存，不进入前端、工具结果或仓库。前端使用 HttpOnly / SameSite cookie、请求源校验和 CSRF token；仅审阅页可调用人工决定端点。SQLite 使用 WAL、事务和 revision 校验，hooks 与服务可安全并发写入。提醒和历史存储在同一数据库。

npm run stop
# 关闭 Codex 或确保 hooks 暂停写入后备份：
cp ~/.ai-todos/ai-todos.sqlite /your/backup/ai-todos.sqlite

只备份业务数据库，不要把运行凭据或日志提交到仓库。恢复时先停止服务，再替换数据库。卸载插件不会删除 ~/.ai-todos，也不会停止独立本地服务；需要时先运行 npm run stop。

发布与开发

发布仓库中的预构建插件使用 npm run package:plugin -- --portable，以 PATH 中的 node 启动。修改源码后应重新生成并提交 plugins/ai-todos/。

开发与检查

npm ci
npm run build
npm start
npm run package:plugin
npm run check

npm run check 在临时数据库中覆盖 CRUD／关系、幂等创建、revision 冲突、交付与人工审阅、可信会话、Stop、计时重启恢复、提醒去重、真实 STDIO 工具与 UI 资源、HTTP 边界及打包后的入口。不会修改日常数据。

修改服务或 UI 后先停止旧服务、重新构建并启动；页面需要刷新。更新已安装插件后重新打包并刷新本地 marketplace，再开启新会话／重启客户端；重新审阅变化后的 hooks，不绕过信任检查。

src/domain.js           唯一业务规则、SQLite 事务、计时、监督调度
src/server.js           回环 Web 服务与人工审阅端点
src/mcp.js              STDIO MCP 工具、MCP Apps 资源和入口
src/service-client.js   自动启动／连接独立本地服务
src/codex.js            Codex 项目同步与临时任务定义生成
hooks/observe.js        可信宿主事件投影（不读取对话内容）
ui/                    完整工作台，同一界面支持 MCP Apps 与浏览器
scripts/               构建、打包、打开与停止
skills/ai-todos/        AI 工作流约束
.agents/plugins/       本地 marketplace

宿主协议证据、已完成检查和未验证项见 docs/host-support.md。此前复用心魔 Gateway 的调研方案已被独立本地架构替代。ClawMate 仅按需只读参考，未修改或复制其原生桌面实现。