hoelee
fd62775fcd
- 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
35 lines
2.1 KiB
Markdown
35 lines
2.1 KiB
Markdown
# 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` 这一个文件即可**，其余内容均可公开。
|