AI 待办的技术架构围绕一个目标设计：为人类和 AI Agent 提供同一套稳定的个人事务数据能力。

小程序、CLI 和 Agent Skill 都围绕后端服务工作，避免多端逻辑分裂。REST API 当前不作为公开接入方式，现阶段优先开放 CLI。

总体架构

apps/
  api/              # 后端 API 服务
  cli/              # 命令行工具
  miniapp/          # 微信小程序
  ios/              # 预留 iOS 原生 App
  android/          # 预留 Android 原生 App
  harmony/          # 预留 HarmonyOS 原生 App
packages/
  shared/           # 共享类型
  api-client/       # API 客户端
  agent-protocol/   # Agent 工具协议

后端

后端采用 Python + FastAPI + PostgreSQL + Alembic。

核心能力：

• 用户隔离；
• 软删除；
• 审计日志；
• 幂等操作；
• 限流防护；
• 内部 API；
• JSON 字段使用 camelCase。

认证体系

AI 待办区分人类入口和 Agent 入口：

• 小程序：微信登录 + 会话 Token；
• CLI / Agent：Personal Access Token（PAT）；
• 权限隔离：所有数据按 user_id 强隔离。

这种设计可以让用户在小程序里管理自己的访问令牌，也方便随时撤销 Agent 权限。

CLI 设计

CLI 是 Agent 接入的首选方式。

设计要求：

• 所有命令支持 --json；
• 错误输出可被 Agent 稳定解析；
• 时间字段统一使用 ISO 8601；
• 写操作支持幂等能力；
• 命令语义与后端资源保持一致。

小程序设计

微信小程序承担人类用户的日常交互入口。

它需要覆盖：

• 今日事项；
• 提醒事项；
• 日历事项；
• 联系人管理；
• CLI / Agent 访问令牌管理；
• 微信订阅消息提醒。

小程序不内置 AI 能力，也不负责自然语言解析。它只提供确定、可控、轻量的图形化操作体验。

数据边界

AI 待办保持数据模型克制：

• 不做团队项目管理；
• 不做复杂审批流；
• 不做文档协作；
• 不做企业 IM；
• 不在服务端保存大模型推理上下文。

它只保存待办小程序所需的提醒、日历、联系人以及必要的审计数据。

开发文档

更多技术细节建议在 AI 待办仓库中继续补齐：

• docs/api-design.md：API 设计文档；
• docs/developer-guide.md：开发者指南；
• docs/deploy.md：部署文档。