chore: agent entrypoint + centralized secrets + slimmer handoff doc

- AGENTS.md: AI session entrypoint (task routing table + iron rules)
- SECRETS.md: single credentials file; distributing the project to
  others = delete this one file
- PROJECT_STATE.md: 190 -> 70 lines, credential quick-ref block removed
  (points to SECRETS.md), incident postmortems kept, pitfall details
  delegated to skill/API_INTEGRATION

AGENTS.md

@@ -0,0 +1,34 @@
+# 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` 这一个文件即可**，其余内容均可公开。