Cf Todoist Daily Agent

Todoist每日代理

Cloudflare Worker+Next.js 16参考实现，该实现计划与Workers AI一起度过一个专注的一天，将中间事件流式传输到浏览器，并通过官方的模型上下文协议（MCP）可流式HTTP端点将生成的任务同步到Todoist中。该项目在Apache 2.0许可证下分发（请参阅 许可证).

架构概述

• 前端：React 19应用路由器页面(src/app/page.tsx)它捕获单个自然语言提示，从中流式传输NDJSON事件 /plan，并可选择录制流过的简短语音备忘 /api/transcribe.
• 规划管道: /plan （记录于 openapi/plan.yaml)验证请求，运行意图分类+特定场景规划 @cf/openai/gpt-oss-120b / @cf/openai/gpt-oss-20b，动态发现Todoist项目/标签，并将每个阶段作为换行符分隔的JSON进行流式传输。详细信息在 docs/PLAN_PIPELINE.md.
• Todoist MCP集成：用途 StreamableHTTPClientTransport 要连接到 https://ai.todoist.net/mcp，列出所有可用的元数据/工具（传统或官方），并调用 add-task(s) 两者都 projectId 和 project_id 字段加上标准化优先级(p1…p4).
• 语音转录: /api/transcribe 将base64 WebM/Opus音频代理到 @cf/openai/whisper-large-v3-turbo执行8 MB限制，以便前端可以覆盖提示并立即提交 /plan.

特性

• 意识到意图的规划: single_reminder, multi_step_plan, recipe_plan，以及 general_plan 模板强制执行任务计数、依赖关系和音调。
• 元数据驱动的提示：通过MCP获取的Todoist项目/标签被注入到AI提示符中，并通过 debug.metadata 事件，以尽量减少“收件箱”回退。
• 优先级标准化：自然语言提示，如 P0, P1，或“高优先级”映射到Todoist REST优先级编号(4 = P1, 1 = P4).批量工具自动转换为 p1…p4 串。
• 流媒体用户体验: /plan 回复与 application/x-ndjson 事件(status, ai.plan, todoist.task, final, error)因此UI可以立即显示进度和失败。
• 语音优先流：浏览器媒体记录器→ /api/transcribe → 一键提示提交，当权限或大小限制失败时，可以优雅地回退。

先决条件

• Node.js 20+
• pnpm 9+
• 牧马人CLI 4.45+
• 启用Workers AI的Cloudflare帐户
• Todoist账户+API代币获准用于MCP测试版(https://ai.todoist.net/mcp)

配置

填充 .dev.vars 对于本地运行，然后通过在Cloudflare中设置相同的名称 wrangler secret put.

本地开发

pnpm install
pnpm dev          # Next.js dev server (no Worker bindings)
pnpm lint         # ESLint flat config for Next.js 16 + TS strict
pnpm preview      # Build via OpenNext + Wrangler preview
wrangler dev      # Run the Worker locally at http://127.0.0.1:8787

流媒体请求示例：

curl -u "$BASIC_AUTH_USER:$BASIC_AUTH_PASS" \
     -N -H "Content-Type: application/json" \
     -H "Origin: $FRONTEND_ORIGIN" \
     -d '{"prompt":"Plan a mindful evening"}' \
     http://127.0.0.1:8787/plan

生成的类型

cloudflare-env.d.ts 由以下人员生产 wrangler types 从 wrangler.jsonc 并且是故意的 未承诺.打包脚本连线 pnpm cf-typegen 进入每个共同的入口点，这很正常 pnpm install 后面跟着任何 pnpm dev, pnpm lint, pnpm build, pnpm preview，或 pnpm run deploy 为您实现文件：

如果你绕过脚本——例如 pnpm install --ignore-scripts 在CI映像或跳过的Docker构建中 devDependencies （所以 wrangler 缺席）-- cloudflare-env.d.ts 将丢失和 pnpm exec tsc --noEmit （没有包装）将表面精确 Property '' does not exist on type 'CloudflareEnv' 错误。跑 pnpm cf-typegen 一次修复。不透明 TS2688: Cannot find type definition file 已退役，因此缺失类型的故障现在可以采取行动。

对于Docker --prod 图像，要么保留 wrangler 在构建期间可用（因此 postinstall 成功）或通过 pnpm install --ignore-scripts 然后跑 pnpm cf-typegen 明确地处于一个阶段 wrangler.

部署

pnpm run deploy   # Builds with opennextjs-cloudflare and runs `wrangler deploy`

脚本生成 .open-next/worker.js，上传静态资产，并发布到 wrangler.jsonc的工人姓名。

可观察性和调试

1. 禁用净化功能以捕获Todoist有效载荷的尾日志：

   LOG_FILE=$(mktemp -t wrangler-tail).log
   WRANGLER_LOG_SANITIZE=false npx wrangler tail cf-todoist-daily-agent --format json > "$LOG_FILE" 2>&1 &

1. 触发 /plan 当尾巴在奔跑时。寻找：

- [todoist.tools] –发现MCP工具。 - [todoist.debug.metadata] –前几个项目/标签（确认元数据范围）。 - [todoist.debug.call-args] –准确 add-task(s) 有效载荷（检查 project_id, priority, due*).

1. 对照Todoist活动日志，确认任务是否落在预期项目和优先级中。

API摘要

• OPTIONS /plan –CORS飞行前（204）。
• POST /plan –主计划器端点返回 application/x-ndjson （参见 openapi/plan.yaml).
• POST /transcribe –语音助手，返回 { text, language } 或错误有效载荷。

OpenAPI模式定义了用于自动化和客户端生成的请求/响应体。

测试与验证

• pnpm lint
• pnpm preview
• wrangler dev --local 然后是示例curl（如上所述），以验证NDJSON流和Todoist MCP连接。

许可证

根据 Apache许可证，版本2.0.