docs: 记录 zsh 引用检查陷阱、agent 权威映射与清理回滚路径

- 系统说明 §10 由 7 行扩至 11 行，新增：引用检查的两个 zsh 陷阱、agent 权威映射只有一处（11 个）、2026-09-16 清理与回滚路径、db-query 技能改走新入口
- 同时提示 workspace/skills 受 gitignore 覆盖不入库、技能改动需重启 gateway 生效

docs/bk02-openclaw-系统说明.md

@@ -318,6 +318,10 @@ grep '^ExecStart' ~/.config/systemd/user/openclaw-gateway.service   # 服务实
 | **skill 重名冲突** | 日志中 `Skill precedence collision`（workspace 覆盖 bundled）属**设计内优先级行为**，非错误 |
 | **skill 必须有 frontmatter** | 新版要求 `SKILL.md` 顶部有 YAML `name` + `description`，否则日志报 `Skipping invalid skill` 并跳过 |
 | **改动后要重启** | 插件变更、skill 变更需 `openclaw gateway restart` 才生效 |
+| **引用检查的两个 zsh 陷阱** | bk02 登录 shell 是 **zsh**，用 ssh 跑 grep 检查引用时：①`--include=*.sh` 等**未加引号的 glob** 会被 zsh 提前展开，无匹配时报 `zsh: no matches found` 并使**整条命令中止、grep 根本没执行**，只见空输出；②`grep ... -- "$pat"` 会让其后的 `--include/--exclude-dir` 被当作**文件名**，过滤条件全部失效。两者叠加足以伪造出「零引用」结论 ⇒ 选项必须加引号（`--include="*.sh"`），且**用一个确定存在的串做对照组**验证 grep 真在工作（2026-09-16 全量清理时两次独立踩中） |
+| **agent 权威映射只有一处** | `openclaw.json` 的 `agents.entries` 是唯一权威（`name` 中文名 + `identity.name`），现存 **11 个**：main=助手 resume=简历 travel=旅行 fitness=健康 finances=理财 juaner=卷儿 sql=SQL note=笔记 pbs=PBS备份 wellness=放松保健 tab=导航页。`scripts/db-conn.sh` 靠 `entries.<id>.name` 反查 `.env` 的 `DB_PASSWORD_<中文名>` ⇒ **改 name 会连带改口令键名**。旧中文名（卷儿记账/理财财务/健身健康/后端开发/简历管理/旅行规划/按摩放松）已于 2026-09-16 清理完毕 |
+| **2026-09-16 清理与回滚路径** | 当日：删 `.env` 6 个零引用旧键（现 11 键）、删空目录 `workspace-attestations/`、`agents/openclaw/` 移出；7 个曾用 id + 2 个陈旧沙箱 + `archived/*` 共 13 项移入 `backups/removed-20260916/`（含 `MANIFEST-taskD.txt` 回滚映射；同盘 `mv` 可瞬时移回）。`.env` 与 `backups/` 都在 `.gitignore` 内、**不受版本管理** ⇒ 该备份目录是这些文件的唯一副本，勿随手删 |
+| **db-query 技能改走新入口** | 本地库一律 `~/.openclaw/scripts/db-conn.sh <agent_id>`（账号 `agent_<id>`，口令经 `MYSQL_PWD` 转发，不进 argv/stdout）；远程 3 个 VPS 主库配置在 `~/.config/clawdbot/db-remote.json`（仅存 `password_env` 键名，无明文）；旧 `db-config.json` 改名 `db-config.json.deprecated-20260916`。本地库输出为 **TSV 无表头**（`mysql -N -B`）。⚠️ 该技能改动**需重启 gateway 才生效**，且 `workspace/skills/**` 受 `.gitignore` 覆盖不入库 |
 
 ---