回写未适配入口与失败卡片三向分派

- 主规范：说明未适配结论只在注册表读回来之后下、提示卡片自带入队按钮、失败卡片按 action 分派适配/修/重试，同一时刻只有一张卡片一个入口。 - 实施计划与里程碑：补提交、前端 vitest 口径改为 18 例（新增 14 + 既有 4），并把 14 例覆盖到的内容逐项列出。
2026-10-05 17:54:30 +08:00
parent 9d3018a49c
commit 6dd0dc00cc
3 changed files with 4 additions and 3 deletions
@@ -8,7 +8,7 @@
 - 表单：`name`、`introduction` 各 ≤14 个 Unicode 字符且非空；`iconPath` 必须存在、是项目内普通文件、不是符号链接、扩展名 ∈ {png, jpg, jpeg}、≤5 MiB。上限来自小红书平台上传表单，宿主**硬校验**（不是提示）；不支持的格式先直接拒绝，格式转换工具是后续事项（代码处留 TODO）。表单不是构建输入——zip 规范里没有任何 app 元数据；它的唯一用途是让用户复制粘贴到平台上传页。
 - 注册表：首次打开该目标时由宿主自动创建，**所有字段为空字符串**。注册表不存 status、不存「是否已适配」、不存经验文本；agent 的经验写在它自己拷进项目的脚本注释里。「有没有脚本」永远现场从 npm 包的 `package.json` scripts 读取（`hasScript`），不落盘。
 - 构建契约：项目 npm 包里存在脚本 `build:xhs-minitool`（冒号形式是既有 `command.exec` 白名单 `build:*` 的要求），由宿主负责运行；跑完必须存在 `.export/xhs-minitool.zip`。脚本内部怎么 `vite build`、怎么调 `pack.mjs`、用什么中间目录由 agent 决定并写进脚本；**每次导出都重新构建 zip**，不做「产物已存在」的短路。
- 首次适配：用户点显式按钮 → 前端组装适配指令（正文在 `view/project-development/export/state/xhsMinitoolInstruction.ts`，纯函数 + 契约常量）→ 经 `useDirectProjectChatController` 的 `chat.submit` 入队（该链路自带会话写权限门与 clientTurnId），进的就是同一个项目主 Direct 会话，不另开「直接调 agent」的旁路。不自动跑构建、不自动刷新；agent 回合结束后由用户点「刷新」重读状态、点「导出」由宿主跑脚本；失败卡片上的「让 code agent 修」发的是同一份契约加宿主失败现场。
+- 首次适配：用户点显式按钮 → 前端组装适配指令（正文在 `view/project-development/export/state/xhsMinitoolInstruction.ts`，纯函数 + 契约常量）→ 经 `useDirectProjectChatController` 的 `chat.submit` 入队（该链路自带会话写权限门与 clientTurnId），进的就是同一个项目主 Direct 会话，不另开「直接调 agent」的旁路。不自动跑构建、不自动刷新；agent 回合结束后由用户点「刷新」重读状态、点「导出」由宿主跑脚本。没有构建脚本时，「还没适配」的结论只由注册表读回来之后下（`hasScript` 初值是 `false`，读取中不下结论），提示卡片自带那颗入队按钮，按钮行里就不再重复一颗；失败卡片按变体的 `action` 分派三颗按钮——`adapt` 发首次适配指令（还没适配，修复指令会引用一份还不存在的适配说明）、`repair` 发同一份契约加宿主失败现场、`retry` 只重试，同一时刻只有一张卡片、一个入口。
 - 冲突：注册表可被 agent（改文件）与用户（面板编辑）两方写入。宿主读注册表时返回 `contentHash`，保存时带 `baseHash`；宿主重读比对，hash 不同再逐字段 diff，只要有字段真的不同就判冲突，**绝不覆盖**，返回两侧值让前端逐字段选择；纯格式化改动静默吸收。注册表内不存 revision / updatedAt 之类 token。
 - 权限与副作用：跑脚本复用 `command.exec` 的权限口径（只查 deny，UI 按钮即用户确认），**不新增** `GAME_CREATION_APP_COMMANDS` 条目；导出链路**不拿项目写锁、不推进全局 revision**（`.export/` 不进 manifest、素材、UI State 或客户端投影）。发布包是白名单收集，`.export/` 不会进入。
 - 非目标：平台自动上传（无 API）、PNG/JPG 之外的 icon 格式转换、宿主侧 zip 结构校验、非 vite 项目、第二个导出目标，以及 `GAME_CREATION_APP_COMMANDS` / `shared-contracts` / SpacetimeDB / OpenAPI 的任何改动。