diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c1227d9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,63 @@
+# AGENTS.md
+
+本仓库（Track 生产流转系统）的工作笔记。仅在验证过之后才写入，避免传谣。
+
+## 架构速览
+
+- `backend/` FastAPI + SQLAlchemy 2.x(async) + Alembic，PostgreSQL。
+- `frontend/` React 19 + Vite + antd + Tailwind。路由见 `src/App.tsx`，
+  管理端菜单见 `src/components/layout/AdminLayout.tsx`（`MENU` 数组）。
+- 登录不走 Track 自己的用户表，而是**只读** MOM(KCGL) 的 `sys_user`：
+  `sys_user.username` 存 `"真实姓名/登录账号"`，`login()` 用
+  `WHERE username LIKE '%/<账号>'` 匹配，`display_name` 由 `/` 拆解得到。
+  MOM 连接配置在 `app/core/mom_database.py`（同步 psycopg2 引擎）。
+
+## 本地起环境（关键，踩过的坑都在这）
+
+1. **本机没有 Postgres 时需要先装**（容器内 `sudo` 可用）：
+   `sudo -n apt-get install -y --fix-missing postgresql postgresql-contrib`
+   然后 `sudo -n pg_ctlcluster 17 main start`。
+   本仓库不使用 pgvector，无需额外扩展。
+2. **数据库端口与生产默认值不同**，必须用环境变量覆盖：
+   - `DATABASE_URL=postgresql+asyncpg://track:track_prod_2026@127.0.0.1:5432/track_production`
+   - `MOM_DB_HOST=127.0.0.1`、`MOM_DB_PORT=5432`
+   - `SECRET_KEY=<≥32 字符>`：`DEBUG=false` 时配置项会**拒绝**默认 SECRET_KEY
+     （见 `app/core/config.py` 的校验），不设会直接 import 失败。
+3. 迁移：`cd backend && python3 -m alembic upgrade head`（没有全局 `alembic` 命令，
+   要用 `python3 -m alembic`）。校验纯 SQL 用 `alembic upgrade head --sql`。
+4. 前端 proxy 指向 Docker 服务名 `backend:8000`。本机跑要么把
+   `127.0.0.1 backend` 写进 `/etc/hosts`，要么直接给
+   `VITE_API_BASE_URL=http://localhost:<port>/api/v1` 绕过 proxy。
+   注意 dev server 由 `basicSsl` 起 HTTPS，跨域需要后端
+   `CORS_ORIGINS` 加上 `https://localhost:1420`。
+
+## 测试的坑（重要）
+
+- **不要用 `starlette.testclient.TestClient` 测异步 SQLAlchemy 应用。**
+  它每个请求新建事件循环，而引擎是模块级单例、池里挂着 asyncpg 连接，
+  跨循环复用会报 `got Future attached to a different loop`，表现为随机 500。
+  正确做法：`httpx.AsyncClient(transport=httpx.ASGITransport(app=app))`
+  并在单个 `asyncio.run()` 里跑完全部请求。生产 uvicorn 单循环无此问题。
+- 仓库目前**没有** pytest 基建，也没有前端测试脚本。
+
+## 已知的待修问题（截至 1.0应用 分支）
+
+- **读接口大面积未鉴权**（已实测，非推测）：无 token 直接 200 的包括
+  `/api/v1/users/`、全部 `/api/v1/dashboard/*`（含
+  `people-history/export` —— 匿名即可批量导出个人工时台账）、
+  `/api/v1/analytics/*`、`/api/v1/screen/*`、`/api/v1/orders/`。
+  写操作和 `/api/v1/tasks`、`/api/v1/products` 是有鉴权的。
+  新增接口请统一用 `app/core/deps.py` 的 `require_admin` / `require_roles`。
+- 「管理员角色」这份规则此前散在 4 处（后端 `task_service`、`products.py` 内联、
+  前端 `constants/task.ts`、`AdminProductsPage` 内联），已因此出过事故。
+  **后端唯一事实来源是 `app/core/roles.py`，前端用 `constants/task.ts::isAdminRole`。**
+  新增判断不要手写 `===` 比较。
+- `task_logs.task_id` 是 NOT NULL 外键，只能挂任务，不是通用审计。通用审计是
+  `audit_logs`（本轮新增，由 `app/core/audit_middleware.py` 自动采集）。
+
+## 约定
+
+- 时间统一北京时间（`app/core/time_utils.py`），库里存 timestamptz。
+- 中文枚举标签尽量由服务端下发（如审计接口的 `module_label`/`action_label`），
+  避免前端再抄一份映射开始漂移。
+- 本仓库的提交信息用中文，说明「为什么」而非「改了什么」。