TodoWindy

把自然语言变成可执行的日程与任务。单机可运行（SQLite），后端 Go + 前端 Vue3 + FullCalendar，支持接入 OpenAI 兼容 LLM。追求“快、稳、可解释”。

特性

• 自然语言 /ingest：一句话生成任务与最小日程建议；可配置时区与“现在”时间
• 单机即可：SQLite（WAL），无需外部依赖；端口占用自动回退 8080→8085→8090→8091→8092
• 简洁 API：/healthz /ingest /tasks /calendar（见下方示例 & api/openapi.yaml）
• 前端直连：web/index.html 使用 Vue3 + FullCalendar（CDN），开箱即用
• LLM 可选：支持 OpenAI 兼容接口（sashabaranov/go-openai），也可用 mock 模式本地演示
• 领域清晰：API 薄、领域厚；planner/scheduler 可扩展，已预留 RRULE 子集（迭代中）

快速开始

依赖

• Go 1.21+
• 可选：OpenAI 兼容 API Key（OPENAI_API_KEY 或 TW_OPENAI_API_KEY）

可在 ~/.zshrc 或项目根 .env 中设置：

OPENAI_API_KEY=sk-...
TW_OPENAI_BASE_URL=https://api.openai.com/v1
TW_OPENAI_MODEL=deepseek-v3.1-terminus
GIN_MODE=release
TW_HTTP_WRITE_TIMEOUT=240s
TW_HTTP_READ_TIMEOUT=60s
TW_HTTP_IDLE_TIMEOUT=90s
TW_LLM_TIMEOUT=120s

运行（本机）

make run          # 自动读取 ~/.zshrc；无空闲 8080 时自动回退端口
# or 指定模型
MODEL=gpt-4o-mini make run
# or 覆盖端口
PORT=8090 make run

启动成功后，直接用浏览器打开 web/index.html，左侧输入自然语言，生成计划并在日历里查看。

若需强制使用 OpenAI 兼容提供方：

make run-openai   # 读取 OPENAI_API_KEY/TW_OPENAI_API_KEY 与 TW_OPENAI_BASE_URL

纯本地演示（不调用外部 LLM）：

make run-mock

Docker

make docker-build
make docker-run     # 读取 .env；映射数据目录 ./data
# 或者 docker compose
make compose-up
make compose-down

目录结构

cmd/server           # 程序入口
internal/api         # HTTP handlers（/healthz /ingest /tasks /calendar /logs）
internal/core        # 领域（planner/scheduler）
internal/infra       # LLM 客户端（openai/mock）
internal/store       # SQLite 迁移与 DAO
internal/pkg/logx    # 环形缓冲日志
web/                 # 前端（Vue3 + FullCalendar）
api/openapi.yaml     # API 契约
docs/                # 文档与 DEVLOG（请在此追加迭代记录）
Makefile             # 开发脚本

API 速览

完整契约见 api/openapi.yaml。

• 健康检查

curl -s http://localhost:8080/healthz

• 自然语言摄入（生成计划 + 建议）

curl -s -X POST http://localhost:8080/ingest \
  -H 'Content-Type: application/json' \
  -d '{"text":"明天上午准备PPT 1小时","timezone":"Asia/Shanghai","now":"2025-01-01T09:00:00+08:00"}'

响应包含 tasks[] 与 suggestions[]（时间选项）。

• 任务 CRUD

# 列表（可按窗口与状态过滤）
curl -s 'http://localhost:8080/tasks?start=2025-01-01T00:00:00Z&end=2025-01-31T23:59:59Z&status=pending'
# 创建
curl -s -X POST http://localhost:8080/tasks -H 'Content-Type: application/json' -d '{"title":"写周报","tags":["工作"],"estimate_minutes":30}'
# 局部更新
curl -s -X PATCH http://localhost:8080/tasks/123 -H 'Content-Type: application/json' -d '{"priority":2}'
# 完成
curl -s -X POST http://localhost:8080/tasks/123/complete

• 日历聚合（按天分组）

curl -s 'http://localhost:8080/calendar?start=2025-01-01T00:00:00Z&end=2025-01-31T23:59:59Z'

配置项（环境变量）

• OPENAI_API_KEY 或 TW_OPENAI_API_KEY
• TW_OPENAI_BASE_URL（如 https://api.openai.com/v1 或代理地址）
• TW_OPENAI_MODEL（如 deepseek-v3.1-terminus）
• GIN_MODE=release（生产）
• TW_HTTP_WRITE_TIMEOUT=240s、TW_HTTP_READ_TIMEOUT=60s、TW_HTTP_IDLE_TIMEOUT=90s
• TW_LLM_TIMEOUT=120s（/ingest 单次调用）
• 运行地址与数据库路径通过 Makefile 设定：TW_ADDR、TW_DB_PATH=data/todowindy.db

开发与测试

make tidy
make test
make build
# 生成 Linux 发行版二进制
make release-linux

开发规范：

• API 契约变更需同步更新 api/openapi.yaml
• 时间统一 RFC3339；内部使用 UTC
• 错误响应统一：{"error":"message"}
• 领域优先：避免在 handler 中堆积复杂逻辑
• 谨慎新增依赖，优先标准库
• 每次迭代请在 docs/DEVLOG.md 追加记录（目标/改动/验证/风险）

路线图

• 后端骨架、SQLite、/tasks、/calendar
• /ingest 打通 + LLM（长耗时已适配）
• Scheduler 最小策略（冲突与建议）
• RRULE 子集展开
• 测试覆盖与性能收尾，打包与发布脚本

参与贡献

欢迎 Issue / PR！

• 分支：feature/*、fix/*、chore/*、docs/*
• 提交信息：type(scope): summary，例 feat(scheduler): 15m grid placement with conflicts
• 本地验证后再提交，并更新 docs/DEVLOG.md

许可证

尚未添加 LICENSE 文件。如计划对外发布，建议增加 MIT 或 Apache-2.0 许可证。

---

本项目的详细“开发总控说明”见 project-doc。