docs: agent 创建规范与数据库自动化设计（已确认，待实现）

docs/agent-创建规范与自动化-设计.md

@@ -0,0 +1,216 @@
+# agent 创建规范与数据库自动化（设计）
+
+> **状态**：设计已确认（2026-09-16）· **待实现**
+> **适用**：bk02 上的 OpenClaw（前置阅读：`bk02-openclaw-系统说明.md`）
+> **决策记录**：见 §12
+>
+> ⚠️ 本文不含明文口令。
+
+---
+
+## 1. 目标与范围
+
+**目标**
+
+1. **main agent 在对话中即可创建新 agent**，且新 agent 的配置（`IDENTITY.md`/`SOUL.md`/`AGENTS.md`/`MEMORY.md` 及 `openclaw.json` 的 `name`/`identity.name`）**全部为中文**。
+2. **每个 agent 自动获得专属 MySQL 库**（库名 = `agent_id`）+ **专用账号**（只授权自己的库，不再用 root）。
+3. 新建 agent 的库**次日自动进入每日备份**，无需人工登记。
+
+**范围**
+
+- 新增：`new-agent.sh`（provisioning 脚本）、中文模板一组、`agent-provisioning` skill
+- 改造：既有每日备份脚本 `backup-agent-dbs.sh`（硬编码 → 动态发现）
+- **不修改** OpenClaw 自身（纯配置/文件层扩展）
+
+**明确不做**：见 §9。
+
+---
+
+## 2. 命名与标识规范
+
+| 概念 | 形式 | 示例 |
+|---|---|---|
+| `agent_id` | ASCII slug，正则 `^[a-z][a-z0-9-]{0,23}$` | `reading` |
+| 中文名 | 2–6 个汉字 | `阅读` |
+| MySQL 库 | **= `agent_id`** | `reading` |
+| MySQL 账号 | `agent_<id>` | `agent_reading` |
+| 密码变量 | `DB_PASSWORD_<中文名>`（写入 `~/.openclaw/.env`） | `DB_PASSWORD_阅读` |
+| workspace | `~/.openclaw/workspace-<id>` | `workspace-reading` |
+| agentDir | `~/.openclaw/agents/<id>/agent` | — |
+
+**中文只用于展示层**（`name`、`identity.name`、文档正文、`.env` 变量名后缀）。
+`id` / 库名 / 账号 / 目录名一律 ASCII —— 依据：既有的 `Obsidian` 与 `obsidian`（仅大小写不同）曾导致 `openclaw backup create --verify` 因 *portable path collision* 失败。
+
+---
+
+## 3. 组件与职责
+
+| 组件 | 路径 | 职责 |
+|---|---|---|
+| provisioning 脚本 | `~/.openclaw/scripts/new-agent.sh` | **唯一特权入口**：建库、建账号、授权、写 `.env`、创建 agent、渲染模板、设置中文名、自检 |
+| 中文模板 | `~/.openclaw/scripts/agent-templates/{IDENTITY,SOUL,AGENTS,MEMORY}.md.tpl` | 新建 agent 的文档骨架 |
+| skill | `~/.openclaw/skills/agent-provisioning/SKILL.md` | 中文；定义触发词、参数、约束、输出格式；约束 main **只能调用脚本** |
+| 审计日志 | `~/.openclaw/workspace/db/agent-provision.log` | 脚本每次执行追加一行（时间/参数/结果），供事后对账 |
+| 备份脚本（改造） | `/usr/local/bin/backup-agent-dbs.sh` | 见 §10 |
+
+**设计要点**
+
+- 特权动作（root 建库）只存在于脚本内；main 的 skill 里写死"只允许调用脚本"。
+- skill 与 `~/.openclaw` 同处一个 git 仓库，规范可版本化、可追溯。
+
+---
+
+## 4. 数据流（main 创建 agent）
+
+```
+用户：“新建一个 agent，id 用 reading，中文名 阅读”
+  ↓
+main 读 skills/agent-provisioning/SKILL.md（约束 + 流程）
+  ↓
+main 执行：bash ~/.openclaw/scripts/new-agent.sh reading 阅读
+  ↓
+脚本（幂等，逐步输出）：
+  ① 入参校验：id 正则 / 中文名非空且长度合法
+  ② 冲突检查：库、agent 条目、workspace 目录任一已存在 → 失败退出（见 §6）
+  ③ 生成 32 位随机密码
+  ④ MySQL（root 凭据取自 ~/.openclaw/.env 的 MYSQL_PWD_ROOT）：
+       CREATE DATABASE `<id>` CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
+       CREATE USER 'agent_<id>'@'%' IDENTIFIED BY '<随机密码>';
+       GRANT ALL PRIVILEGES ON `<id>`.* TO 'agent_<id>'@'%';
+  ⑤ 写入 ~/.openclaw/.env：DB_PASSWORD_<中文名>='<随机密码>'
+       （同键则替换，不重复追加；.env 已在 .gitignore）
+  ⑥ openclaw agents add <id> --workspace ~/.openclaw/workspace-<id> --non-interactive
+  ⑦ 渲染中文模板到 workspace-<id>/（覆盖 openclaw 生成的英文骨架）
+  ⑧ openclaw agents set-identity --agent <id> --from-identity
+       （从 IDENTITY.md 读中文名写入配置）
+  ⑨ 自检（§7）并输出汇总：库名 / 账号 / 凭据变量 / workspace / 下一步
+```
+
+**为什么用 `--from-identity`**：中文名先落在 `IDENTITY.md`（人可读），再一条命令同步进 `openclaw.json`，避免两处手工维护不一致。
+
+---
+
+## 5. 中文模板
+
+四件套（全中文，`.tpl` 内用占位符 `{{AGENT_ID}}`、`{{AGENT_NAME}}`）：
+
+- **`IDENTITY.md`** —— 我是谁（含中文名、emoji）
+- **`SOUL.md`** —— 性格与表达风格
+- **`AGENTS.md`** —— 工作规范（**核心是数据库段**）
+- **`MEMORY.md`** —— 长期记忆骨架
+
+`AGENTS.md.tpl` 的数据库段（沿用 `workspace-sql` 已验证的范式）：
+
+```markdown
+## 数据库规范
+- 默认库：`{{AGENT_ID}}` —— 这就是你自己的库
+- 账号：`agent_{{AGENT_ID}}`；密码取环境变量 `DB_PASSWORD_{{AGENT_NAME}}`
+- 连接：mysql -h 127.0.0.1 -u agent_{{AGENT_ID}} -p"${DB_PASSWORD_{{AGENT_NAME}}}"
+- 禁止：使用 root、使用 docker exec、访问其他 agent 的库、跨库写入
+- 破坏性语句（DROP / TRUNCATE / 无条件 DELETE）必须先请示
+```
+
+---
+
+## 6. 幂等、错误处理与安全
+
+| 场景 | 行为 |
+|---|---|
+| id 非法 / 中文名为空 | 立即失败并打印用法 |
+| 库或 agent 或 workspace **已存在** | **默认失败**（不覆盖、不改动）；仅 `--reset-password` 才重置账号密码 |
+| 中途失败 | 已完成的步骤保留；重跑时明确提示"已完成到第 N 步"，不静默改写 |
+| `.env` 写入 | 幂等替换（同键覆盖，避免重复行） |
+| SQL 注入 | id 必须通过白名单正则后才参与拼接 |
+| 凭据 | 脚本**不硬编码**密码，从 `~/.openclaw/.env` 读；生成的密码只写 `.env` |
+
+---
+
+## 7. 验证方式
+
+- `new-agent.sh --dry-run`：打印将执行的 SQL 与文件操作，**不落地**
+- 创建后自动自检：
+  1. 库存在
+  2. **用新账号实连一次 `SELECT 1`**（证明授权真的生效）
+  3. `workspace-<id>/` 四件套齐全
+  4. 输出可直接复制给用户的凭据行
+
+---
+
+## 8. 存量处置（所有 agent）
+
+**范围：全部 12 个 agent 都要有库 + 专用账号**（含 `openclaw`）。
+
+| 分组 | agent | 动作 |
+|---|---|---|
+| 已有库，需改造 | `main` `juaner` `wellness` `tab` `finances` `fitness` `resume` `travel` | 建 `agent_<id>` 账号 + 授权 + 改各自 `AGENTS.md` 数据库段（由 root 直连改为专用账号） |
+| 缺库需新建 | `note`(笔记) `pbs`(PBS备份) | 建库建号 + 补文档 |
+| 特例 | `sql`(SQL) | 保留其**远程 VPS 业务库**定位，另给一个私有库做工作区 |
+| 待纳入 | `openclaw` | 当前不在 `agents.entries`、也不在 `agentToAgent.allow` —— 需先决定是否正式纳入，再建库 |
+
+> 存量改造是**一次性迁移**，建议作为独立步骤执行（含改 `.env` 变量与各 agent 文档），与新建流程分开验证。
+
+---
+
+## 9. 非目标（YAGNI）
+
+- 不做可视化界面 / 批量重建工具
+- 不做库结构版本迁移工具
+- 不去改 skill 机制使其按 agent 隔离 —— OpenClaw 的 `skills.entries` 是**全局开关（52 项，仅 `enabled`）**，无法按 agent 配置；权限隔离由 **MySQL 账号**承担（这也是"专用账号"从建议变为必需的原因）
+
+---
+
+## 10. 每日备份改造
+
+**现状**（已存在，非自建部分）：`crontab 0 3 * * * /usr/local/bin/backup-agent-dbs.sh`
+
+- 逐库 `mysqldump --single-transaction --routines --triggers --events`，**用 root**
+- 备份到各自 workspace 的 `db/`（如 `workspace-resume/db/resume_20260916.sql.gz`），另留一份 `*_latest.sql`
+- 清理 30 天前备份
+- 结束后 `git commit` + **push 到自建 Gitea**
+
+**问题**：库清单是**硬编码的 8 条 `DB_MAP`** ⇒ **新建 agent 不会被备份**。
+
+**改造目标**
+
+1. **动态发现**：备份目标 = `agents.entries` 的 id ∩ `information_schema.schemata`（排除 `mysql`/`information_schema`/`performance_schema`/`sys`），这样 provisioning 建的库**次日自动纳入**
+2. **不硬编码密码**：改为从 `~/.openclaw/.env` 读（而非脚本内明文）
+3. 保留策略（30 天）与 **push 到 Gitea 保持现状**（Gitea 为自建）
+4. PostgreSQL（`openclaw` 库）分支保持不动
+
+---
+
+## 11. 技能强制性 = 档 ①（纯规范，不改环境）
+
+**已明确接受的前提**：不剥夺凭据、不收窄 sudo、不启用 exec 审批。因此 main **技术上仍可能**从 `.env` / 备份脚本取得 root 自行建库 —— 规范能大幅降低概率，但**不能归零**。
+
+在纯规范档下，把约束强化到六点：
+
+1. **写入 main 的「红线」章节**（`workspace/AGENTS.md` 已有该章节）：
+   > 创建 agent 必须且只能执行 `bash ~/.openclaw/scripts/new-agent.sh <id> <中文名>`；
+   > 禁止自行拼 SQL、禁止用 `mysql`/`docker exec` 建库、禁止为建库读取任何 root 凭据。
+2. **SKILL.md 的 `description` 精确化**（skill 触发的唯一依据）：写明触发场景与关键词（"新建 agent""创建 agent""加一个 agent"）。
+3. **让正确路径比绕过更省事**（行为引导）：脚本一条命令完成 9 步；绕过则需自行拼 SQL、处理 `.env`、写四个中文模板 —— 复杂度差本身就是约束。
+4. **脚本内不硬编码密码**（见 §6）。
+5. **脚本自带轻量审计**：每次执行追加一行到 `workspace/db/agent-provision.log`；**不改环境**，但事后可对账 —— 库中多出的账号若不在日志里，即为绕过证据。
+6. **阻断态显式提示**：出现"库已存在但账号缺失"等异常时，输出"请改用 `new-agent.sh`"的明确指引。
+
+---
+
+## 12. 决策记录
+
+| # | 决策点 | 结论 | 日期 |
+|---|---|---|---|
+| 1 | 落地形态 | **方案 B**：脚本 + skill，由 main 调用（否决纯人工脚本、否决把 root 交给 main 自行拼 SQL） | 2026-09-16 |
+| 2 | 目标库与账号 | **本机 docker MySQL**；**每个 agent 专用账号**（停用 root 直连） | 2026-09-16 |
+| 3 | 存量范围 | **所有 agent**（含 `openclaw`）都要有库与账号 | 2026-09-16 |
+| 4 | 中文范围 | 展示层全中文；`id`/库名/账号/目录名保持 ASCII | 2026-09-16 |
+| 5 | 备份 | 改造为动态发现；**保持 push 到自建 Gitea** | 2026-09-16 |
+| 6 | 技能强制性 | **档 ①（纯规范）**：不改凭据、不收窄 sudo、不加 exec 审批 | 2026-09-16 |
+| 7 | 授权模型 | skill 层无法按 agent 隔离（`skills.entries` 全局）⇒ 隔离必须由 MySQL 账号承担 | 2026-09-16 |
+
+---
+
+## 附：实现时需现场确认的两点
+
+1. `openclaw agents add` 生成的骨架文件清单与内容 —— 决定模板是**覆盖**还是**补充**
+2. `set-identity --from-identity` 对 `IDENTITY.md` 格式的具体要求（字段名/解析规则）