fix: validate platform keys at the gate and stop auto-register

Co-authored-by: Cursor <cursoragent@cursor.com>

references/CLI.md

@@ -29,6 +29,7 @@
 |---|---|
 | `platform list [--domain logistics\|llm\|content]` | 列出平台注册（`--domain` 仅接受这三种；`dev`/`sim` 等平台请省略 `--domain` 查全量或在 JSON 里筛选） |
 | `platform get <platform>` | 获取数据库中的平台详情 |
+| `platform ensure --key <key> --display-name <name> [--url …]` | **登记/更新平台**。`--key` 必须已是小写英文键（如 `douyin`）；`--display-name` **必填**（可中文）。不会从 `add-web` / `pick-web` 自动建平台。 |
 
 ### B. 加密初始化（v2）
 
@@ -223,7 +224,7 @@ ACCOUNT_MANAGER_MASTER_KEY="<base64-44-chars>" python main.py account init-maste
 
 ## 通用说明
 
-- **平台参数**：可为 `scripts/util/platforms.py` 中的英文键、`display_name`、任一 alias（不区分大小写）。详见 [PLATFORMS.md](PLATFORMS.md)。
+- **平台参数**：已注册的英文键、或能唯一对应到一个键的 `display_name`/alias（不区分大小写）。冲突别名（如「公众号」同时对应 `wechat` / `wechat_mp`）会返回 `AMBIGUOUS_PLATFORM`，请改传明确键。未注册的键**不会**自动插入 `platforms` 表。详见 [PLATFORMS.md](PLATFORMS.md)。
 - **数据与路径**：库文件、profile、`master.key` 布局见 [RUNTIME.md](RUNTIME.md)。
 - **机器可读集成**：见 [INTEGRATION.md](INTEGRATION.md)。
 - **错误码**：见 [ERRORS.md](ERRORS.md)。

references/ERRORS.md

@@ -46,7 +46,13 @@
 
 | 前缀 | 含义 |
 |---|---|
-| `ERROR:INVALID_PLATFORM` | 平台名无法识别 |
+| `ERROR:INVALID_PLATFORM` | 平台名为空，或中文/人话名称无法对应到已注册平台 |
+| `ERROR:INVALID_PLATFORM_KEY` | 键格式非法（大写、空格、中文当键等）；展示名不能当键 |
+| `ERROR:PLATFORM_NOT_REGISTERED` | 键格式合法但尚未 `platform ensure`；**已拒绝写入**，不会自动建平台 |
+| `ERROR:AMBIGUOUS_PLATFORM` | 展示名/别名对应多个键（如「公众号」→ `wechat` 与 `wechat_mp`），请改传明确键 |
+| `ERROR:PLATFORM_ALIAS_CONFLICT` | `platform ensure` 的展示名/别名已被其它平台占用 |
+| `ERROR:INVALID_PLATFORM_DISPLAY_NAME` | `platform ensure` 未提供 `--display-name` |
+| `ERROR:PLATFORM_DISABLED` | 平台已禁用 |
 | `ERROR:NO_ACCOUNTS_FOUND` | 列表无结果 |
 | `ERROR:ACCOUNT_NOT_FOUND` | 指定 id 不存在 |
 | `ERROR:ACCOUNT_DISABLED` | 账号状态为 disabled |

references/INTEGRATION.md

@@ -4,6 +4,8 @@
 
 业务 skill **不能自己散落存储账号、密码、API Key、Token**。应通过 account-manager **CLI**（进程隔离）或 **CLI + `service.rpa_helpers` 同进程库**（浏览器自动化）组合获取。
 
+新平台必须先 `platform ensure --key <小写键> --display-name <展示名>` 再引用。`add-web` / `ensure-web` / `pick-web` **不会**根据 `--platform-display-name` 自动插入 `platforms` 行。
+
 ## 两种集成方式
 
 | 方式 | 适用场景 | 调用形态 |
@@ -26,6 +28,7 @@
 | 目的 | 命令 | 成功时 stdout（摘要） |
 |---|---|---|
 | 枚举平台 | `platform list [--domain ...]` | `{"success": true, "data": {"platforms": [...]}}` |
+| 登记平台 | `platform ensure --key <小写键> --display-name <展示名>` | `{"ok": true, "platform_key": "...", "action": "created\|updated"}` |
 | 平台详情 | `platform get <p>` | `{"success": true, "data": {...}}` |
 | 取单条账号 JSON | `account get <id>` | **单行 JSON 对象**（无固定 `success` 字段） |
 | 批量账号 JSON | `account list ...` | **单行 JSON 数组** |

references/PLATFORMS.md

@@ -2,7 +2,12 @@
 
 **权威来源**：`scripts/util/platforms.py` 中的 `PLATFORMS`（当前 **31** 条）。若本文与代码不一致，**以代码为准**。
 
-解析函数：`resolve_platform_key(name)` — 支持英文键、`display_name`、任一 alias（大小写不敏感）。
+解析：
+
+- **引用**（`add-web` / `ensure-web` / `pick-web` / `platform get`）：`resolve_platform_key_dynamic` — 已有键精确匹配；已有键可大小写折叠（`DeepSeek` → `deepseek`）；展示名/别名仅在**唯一**对应一个键时通过。未注册键**拒绝写入**，不会自动 `INSERT`。
+- **登记**（仅 `platform ensure`）：键必须符合 `^[a-z0-9][a-z0-9_-]{1,63}$` 且**本身已是小写**（`HaoKan` 非法）；`--display-name` 必填；别名不得抢其它平台已占用的展示名/别名。
+
+`resolve_platform_key(name)` 仍是内置表的静态别名映射（无 DB、冲突别名后写覆盖），新代码请走动态解析。
 
 ---
 
@@ -99,3 +104,5 @@ CLI `platform list --domain` **仅接受** `logistics | llm | content`（见 `cm
 ## 平台注册到数据库
 
 `seed_platforms(conn)` 在业务流程中随 `init_db()` 触发，将 `PLATFORMS` upsert 进 `platforms` 表（仅覆盖定义字段；**不会**自动清空用户自定义的 `default_auth_strategy`，除非迁移逻辑另行更新——详见 [`SCHEMA.md`](SCHEMA.md)）。
+
+业务 skill 要加新平台：先 `platform ensure --key <小写键> --display-name <展示名> [--url …]`，再 `add-web` / `ensure-web`。不要把中文名或 `HaoKan` 这种大小写混写当成键；也不要指望 `--platform-display-name` 自动建行。

references/README.md

@@ -10,6 +10,7 @@ description: "通用账号 & 凭据 & 登录流程管理器。管理网页/RPA
 
 ## 它能帮你做什么
 
+- **登记自定义平台** — `platform ensure --key douyin --display-name 抖音`；键必须是小写英文，展示名可以是中文。其它技能不能靠 add-web 自动建平台。
 - **添加网页/RPA 账号** — 选平台，给出登录标识（邮箱/手机/用户名），自动创建浏览器 profile 目录。
 - **添加 API Key/Token / 加密密码** — `none` / `env` / `windows_credential` / `local_encrypted`（Fernet 密文入库）。
 - **查看/列出账号** — 按平台、环境、角色等多维度筛选。
@@ -58,4 +59,4 @@ description: "通用账号 & 凭据 & 登录流程管理器。管理网页/RPA
 
 ---
 
-**作者**:深圳匠厂科技有限公司 · **版本**:2.0.23
+**作者**:深圳匠厂科技有限公司 · **版本**:2.0.24