Files

T

hoelee fd62775fcd 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

2026-08-24 22:05:59 +08:00

2.1 KiB

Raw Permalink Blame History

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

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

开工四步

读本文件（30 秒）
读 docs/PROJECT_STATE.md（当前进度 + 下一步，≤150 行）
凭据/地址 → 只看 SECRETS.md（唯一凭据文件；外发给别人 = 删它即可）
连不上系统？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` 结案区

铁律（违反必返工）

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

项目一句话

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

外发 SOP

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

2.1 KiB Raw Permalink Blame History Unescape Escape