AI-Secretary/AGENTS.md

AGENTS.md

本文件是给 AI 和开发者看的后端协作导航。开发任何后端功能前，先按本文件判断要读哪些 spec、contract、plan 和 checklist。

项目一句话

第一版要做一个公司内部 AI 协作最小闭环：

老板一句话
-> AI 草稿
-> 人工确认
-> 创建事项或定时提醒
-> 飞书通知
-> 接收人反馈
-> 页面看到结果和失败记录

这不是完整任务系统、完整 AI 工作台、完整看板，也不是全自动 Agent。

当前技术栈

层级	约定
后端	Python Django + Django REST Framework
ORM	Django ORM + Django Migrations
数据库	PostgreSQL 18.x，作为唯一数据源；业务表、AI 对话记忆、上下文快照和日志都落同一套 PostgreSQL
AI 对话记忆	PostgreSQL 表 + jsonb，用于老板秘书会话、对话消息、BotContext 快照、模型请求/响应和 Agent 决策快照；AI 记忆表不能替代正式业务表
Agent 编排	第一版不引入 LangChain / LangGraph，先用 Django service 层实现轻量 AiSecretaryAgent
定时任务	Django management command + 独立 scheduler 进程
后台管理	Django Admin
AI 接入	阿里百炼 API，后端封装薄 ai_client
飞书	飞书身份登录、机器人私聊、个人消息、交互卡片和回调
部署	Docker Compose + Nginx + Gunicorn

渐进式阅读规则

普通任务只读：

1. AGENTS.md
2. 当前相关 docs/specs/*.md
3. 当前 active plan

涉及接口时再读：

1. docs/contracts/API接口约定.md

涉及数据库或字段时再读：

1. docs/contracts/数据对象约定.md

涉及老板 AI 秘书、Agent、意图识别、上下文和草稿生成时先读：

1. docs/specs/01_老板AI秘书与AI草稿.md
2. docs/contracts/数据对象约定.md
3. docs/contracts/API接口约定.md

涉及 AI 对话记忆、上下文恢复、多账号会话或 PostgreSQL jsonb 上下文表时再读：

1. docs/specs/01_老板AI秘书与AI草稿.md
2. docs/contracts/数据对象约定.md

只处理任务、提醒、通知等业务状态时，以 PostgreSQL 正式业务表为准，不要把 AI 记忆表当业务事实源。

涉及状态流转时再读：

1. docs/contracts/状态流转约定.md

涉及飞书时再读：

1. docs/specs/03_飞书通知与反馈.md
2. docs/contracts/API接口约定.md

涉及 Review 或提交前检查时再读：

1. docs/checklists/AI生成代码检查清单.md
2. docs/checklists/后端Review清单.md

不要每次全量读取所有 docs，避免上下文过大、重点变散。

事实源优先级

1. docs/contracts/ 是字段、接口、状态、错误码和全局约定的唯一事实源。
2. docs/specs/ 说明业务边界和模块目标，不复制完整字段表。
3. docs/plans/active/ 是当前施工依据，不用于偷偷改变业务边界。
4. docs/checklists/ 和测试是 Review 闸门。

如果 spec 和 contract 冲突，以 contract 为准，并提出文档修正建议。

PostgreSQL 是唯一事实源，保存用户、人员映射、AI 草稿、任务、提醒、通知、反馈、失败记录、操作日志、AI 对话消息和 BotContext 快照。

AI 对话记忆也保存在 PostgreSQL 中，第一阶段使用 secretary_conversations、secretary_messages、bot_contexts 等表；bot_context_snapshot、extracted_facts、模型请求/响应摘要等结构化弹性字段使用 jsonb。

PostgreSQL 中的 AI 记忆表只能辅助 AI 理解、追问、恢复会话和生成草稿，不能直接作为创建任务、提醒或通知的最终依据。

生成代码禁止事项

1. 不允许 AI 未经人工确认直接创建事项、提醒或发送通知。
2. 不允许普通员工给别人创建事项或提醒。
3. 不允许绕过后端权限校验，只靠前端隐藏按钮。
4. 不允许自动操作交易系统、公司历史数据库、后台管理系统或其他外部业务系统。
5. 不允许把 API Key、App Secret、飞书 token、完整手机号、完整邮箱写进代码或普通日志。
6. 不允许把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
7. 不允许把第一版明确不做的功能混入主线。
8. 不允许只写 AI 记忆表就认为任务、提醒或通知已经创建成功。
9. 不允许 AI 根据 PostgreSQL AI 记忆表绕过正式业务表中的权限、草稿确认和业务状态校验。
10. 不允许把老板 AI 秘书写成普通聊天接口；必须经过 AiSecretaryAgent 的意图识别、上下文读取、JSON 校验、草稿/追问/降级流程。

AI 写代码推荐流程

人确定任务
-> AI 读 AGENTS.md
-> AI 读对应 spec
-> AI 检查 docs/plans/active/ 是否已有当前 plan
-> 没有 plan：读必要 contracts，生成 plan 给人确认
-> 已有 plan：只按当前 plan 执行
-> AI 读 checklists
-> AI 按 plan 写代码
-> AI 自测
-> 泽源跑测试
-> 乔大卫 / 田宇 Review 关键代码
-> 王一多验收闭环

active plan 是当前施工依据。除非发现 plan 明确不符合 spec/contracts，否则不要重新生成新 plan。

第一版不做

AI 工作台、技能市场、文件上传、多模态处理、会议纪要、日报、文档摘要、复杂反馈看板、复杂 BI、成本驾驶舱、完整工作流、完整项目管理、多级子任务、甘特图、复杂审批流、复杂组织架构、cron 表达式、日历系统、自动操作交易系统、自动操作历史数据库、自动读取员工本地文件、手机端网页完整适配、把飞书机器人开放为程经理或普通员工通用派活入口。