# AGENTS.md

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

## 项目一句话

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

```text
老板一句话
-> 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/contracts/安全权限日志约定.md`

涉及飞书时再读：

1. `docs/specs/03_飞书通知与反馈.md`
2. `docs/contracts/API接口约定.md`
3. `docs/contracts/安全权限日志约定.md`

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

1. `docs/checklists/AI生成代码检查清单.md`
2. `docs/checklists/后端Review清单.md`
3. 本次新增或修改的 tests

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

## 事实源优先级

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

如果 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、OAuth code/state、回调验签密钥、一次性操作 token、完整手机号、完整邮箱写进代码或普通日志。
6. 不允许把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
7. 不允许把第一版明确不做的功能混入主线。
8. 不允许只写 AI 记忆表就认为任务、提醒或通知已经创建成功。
9. 不允许 AI 根据 PostgreSQL AI 记忆表绕过正式业务表中的权限、草稿确认和业务状态校验。
10. 不允许把老板 AI 秘书写成普通聊天接口；必须经过 `AiSecretaryAgent` 的意图识别、上下文读取、JSON 校验、草稿/追问/降级流程。

## AI 写代码推荐流程

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

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

## 第一版不做

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