# AGENTS.md

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

## 项目一句话

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

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

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

## 当前技术栈

| 层级    | 约定                                          |
| ----- | ------------------------------------------- |
| 后端    | Python Django + Django REST Framework       |
| ORM   | Django ORM + Django Migrations              |
| 数据库   | MySQL 8，使用平台自有应用库                           |
| 定时任务  | 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`

涉及状态流转时再读：

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 为准，并提出文档修正建议。

## 生成代码禁止事项

1. 不允许 AI 未经人工确认直接创建事项、提醒或发送通知。
2. 不允许普通员工给别人创建事项或提醒。
3. 不允许绕过后端权限校验，只靠前端隐藏按钮。
4. 不允许自动操作交易系统、公司历史数据库、后台管理系统或其他外部业务系统。
5. 不允许把 API Key、App Secret、飞书 token、完整手机号、完整邮箱写进代码或普通日志。
6. 不允许把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
7. 不允许把第一版明确不做的功能混入主线。

## AI 写代码推荐流程

```text
人确定任务
-> 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 表达式、日历系统、自动操作交易系统、自动操作历史数据库、自动读取员工本地文件、手机端网页完整适配、把飞书机器人开放为程经理或普通员工通用派活入口。