diff --git a/docs/agent-创建规范与自动化-设计.md b/docs/agent-创建规范与自动化-设计.md new file mode 100644 index 0000000..7008788 --- /dev/null +++ b/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_` | `agent_reading` | +| 密码变量 | `DB_PASSWORD_<中文名>`（写入 `~/.openclaw/.env`） | `DB_PASSWORD_阅读` | +| workspace | `~/.openclaw/workspace-` | `workspace-reading` | +| agentDir | `~/.openclaw/agents//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 `` CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; + CREATE USER 'agent_'@'%' IDENTIFIED BY '<随机密码>'; + GRANT ALL PRIVILEGES ON ``.* TO 'agent_'@'%'; + ⑤ 写入 ~/.openclaw/.env：DB_PASSWORD_<中文名>='<随机密码>' + （同键则替换，不重复追加；.env 已在 .gitignore） + ⑥ openclaw agents add --workspace ~/.openclaw/workspace- --non-interactive + ⑦ 渲染中文模板到 workspace-/（覆盖 openclaw 生成的英文骨架） + ⑧ openclaw agents set-identity --agent --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-/` 四件套齐全 + 4. 输出可直接复制给用户的凭据行 + +--- + +## 8. 存量处置（所有 agent） + +**范围：全部 12 个 agent 都要有库 + 专用账号**（含 `openclaw`）。 + +| 分组 | agent | 动作 | +|---|---|---| +| 已有库，需改造 | `main` `juaner` `wellness` `tab` `finances` `fitness` `resume` `travel` | 建 `agent_` 账号 + 授权 + 改各自 `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 <中文名>`； + > 禁止自行拼 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` 格式的具体要求（字段名/解析规则）