# AGENTS.md — AI 会话入口（开工先读这个）

> 本文件是 AI agent 的路由表：新会话从这里开始，按需再往下读，不要一上来通读全部文档。

## 开工四步
1. 读本文件（30 秒）
2. 读 `docs/PROJECT_STATE.md`（当前进度 + 下一步，≤150 行）
3. 凭据/地址 → **只看 `SECRETS.md`**（唯一凭据文件；外发给别人 = 删它即可）
4. 连不上系统？DSM IP 可能漂移了——先探测内网（ping / 试 5244、10380、5678 端口），别死磕旧 IP

## 任务路由表
| 要做的事 | 去哪里 |
|---|---|
| 改 workflow 逻辑 | `n8n/w1..w4-body.js` 或 `n8n/shared/effective-grants.js`，改完跑 `node n8n/gen_w1.js`…重新生成 JSON。**禁止手编 `W*.json`** |
| 查表/字段/link 列 ID | `docs/DATABASE_SCHEMA.md`（ID 不是机密，留在文档里） |
| 查 AList / NocoDB / n8n API 怪癖 | skill `alist-serve-resource` 的 Pitfalls（唯一权威，比本文档全） |
| 理解权限算法 | `n8n/shared/effective-grants.js` 注释 + `docs/PERMISSIONS.md` |
| 理解整体架构 | `docs/ARCHITECTURE.md` |
| 查某次事故结论 | `docs/PROJECT_STATE.md` 结案区 |

## 铁律（违反必返工）
1. **勿手编 `n8n/W*.json`** —— 它们是生成物，源头在 body/shared
2. **验证 n8n 是否真的执行：看 AList/NocoDB 实际状态变化**，别数 executions 表（`SAVE_ON_SUCCESS=none`）
3. **DSM IP 会漂移** —— 连不上先探测（probe_env.py），别死磕旧 IP
4. AList 多目录授权：`base_path="/"` + role scope 绝对路径（设 `/Class` 会双重前缀全 403）
5. expiry 边界是 `<= today`（到期当天即失效）；NocoDB link 查询必须 `(link.Id,eq,N)`
6. 改共享代码后 grep 一遍裸 `(customer,eq,` / `(product,eq,` —— 此 bug 复发过两次

## 项目一句话
NocoDB(业务 SOT) --webhook/schedule--> n8n W1-W4 --> AList(role scopes)。
Customers → CustomerProducts → Products ↔ Resources 决定客户在 AList 能看哪些目录。

## 外发 SOP
把项目给其他人：**删除 `SECRETS.md` 这一个文件即可**，其余内容均可公开。