回写自动重读与命令切分的口径

- 主规范：四条命令与内容/指纹的切分理由、自动重读的两条采纳规则（hasScript 随时采纳、表单只在用户没在编辑时采纳）、指纹不进对外状态、验收项补「自动重读不覆盖未保存输入」。 - 实施计划与里程碑：命令清单改 4 条、面板改两颗按钮、运行时验收去掉「点刷新」一步、前端 vitest 口径 19 例（新增 15 + 既有 4），并说明刷新撤掉待保存输入那条行为已被取代。
2026-10-05 18:29:11 +08:00
parent aea1fb8f9f
commit 17044f0504
3 changed files with 15 additions and 13 deletions
@@ -8,12 +8,13 @@
 - 表单：`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 回合结束后由用户点「刷新」重读状态、点「导出」由宿主跑脚本。没有构建脚本时，「还没适配」的结论只由注册表读回来之后下（`hasScript` 初值是 `false`，读取中不下结论），提示卡片自带那颗入队按钮，按钮行里就不再重复一颗；失败卡片按变体的 `action` 分派三颗按钮——`adapt` 发首次适配指令（还没适配，修复指令会引用一份还不存在的适配说明）、`repair` 发同一份契约加宿主失败现场、`retry` 只重试，同一时刻只有一张卡片、一个入口。
- 冲突：注册表可被 agent（改文件）与用户（面板编辑）两方写入。宿主读注册表时返回 `contentHash`，保存时带 `baseHash`；宿主重读比对，hash 不同再逐字段 diff，只要有字段真的不同就判冲突，**绝不覆盖**，返回两侧值让前端逐字段选择；纯格式化改动静默吸收。注册表内不存 revision / updatedAt 之类 token。
+- 首次适配：用户点显式按钮 → 前端组装适配指令（正文在 `view/project-development/export/state/xhsMinitoolInstruction.ts`，纯函数 + 契约常量）→ 经 `useDirectProjectChatController` 的 `chat.submit` 入队（该链路自带会话写权限门与 clientTurnId），进的就是同一个项目主 Direct 会话，不另开「直接调 agent」的旁路。不自动跑构建、不自动叫 agent；内容与脚本判据按固定间隔（2 秒，窗口在后台时跳过）自动重读，所以没有刷新按钮——agent 回合结束后用户只需要点「导出」。重读时两条事实分开处理：`hasScript` 是宿主的现算事实，任何时刻都采纳；表单是用户的编辑对象，只有用户手上没有未保存输入（也不在冲突里）时才覆盖，否则只更新 `hasScript`，绝不覆盖正在打的字。没有构建脚本时，「还没适配」的结论只由注册表读回来之后下（`hasScript` 初值是 `false`，读取中不下结论），提示卡片自带那颗入队按钮，按钮行里就不再重复一颗；失败卡片按变体的 `action` 分派三颗按钮——`adapt` 发首次适配指令（还没适配，修复指令会引用一份还不存在的适配说明）、`repair` 发同一份契约加宿主失败现场、`retry` 只重试，同一时刻只有一张卡片、一个入口。
+- 命令切分：`read_xhs_minitool_export` 只返回**内容**（`form` + `hasScript`），自动刷新反复调的就是这一条；**注册表指纹**（写回时的 `baseHash`）由 `read_xhs_minitool_export_hash` 单独给，只在进编辑会话、或重读到的新内容真的被采纳时取一次。两者分开是刻意的：刷新这条高频路径在类型上就动不了写回基线，否则「顺手刷新」会把两次刷新之间的外部改动认成自己的基线、把冲突吞掉。指纹是同步细节，不进前端对外状态（hook 里只在 `baselineRef`），界面也不显示任何同步状态（没有「保存中」「待保存」文案）。`save_xhs_minitool_export_form` 成功后回新的指纹。
+- 冲突：注册表可被 agent（改文件）与用户（面板编辑）两方写入。宿主保存时带 `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 的任何改动。
- 验收：注册表自动建空表单与严格解析拒绝、表单首错、`hasScript` 判定、`contentHash` 冲突与逐字段选择、icon 越界与符号链接拒绝、产物路径；首次适配在真实 vite 项目上由 agent 跑通并产出可人工上传的 zip，二次导出零 agent 调用；变更 skill 脚本后指纹同步。证据与未验证项见[里程碑](../project-memory/plans/【里程碑】导出产物面板与小红书小工具导出-2026-10-05.md)。
- 落地情况：Rust（`export/{mod,registry,draft/xhs_minitool/*}` 三个命令）、前端（`export/{state,tabs/xiaohongshu,generated}`）、skill（`pack.mjs --zip-out`）与 `.export/` 快照同步排除均已实现；定向单测与前端 vitest 通过，**真实 vite 项目上的首轮适配仍是唯一未验证项**。
+- 验收：注册表自动建空表单与严格解析拒绝、表单首错、`hasScript` 判定、内容与指纹两条命令的切分（自动刷新拿不到写回基线）、`contentHash` 冲突与逐字段选择、icon 越界与符号链接拒绝、产物路径；自动重读不覆盖用户未保存的输入、agent 事后加上脚本不用点刷新就能亮起导出按钮；首次适配在真实 vite 项目上由 agent 跑通并产出可人工上传的 zip，二次导出零 agent 调用；变更 skill 脚本后指纹同步。证据与未验证项见[里程碑](../project-memory/plans/【里程碑】导出产物面板与小红书小工具导出-2026-10-05.md)。
+- 落地情况：Rust（`export/{mod,registry,draft/xhs_minitool/*}` 四个命令）、前端（`export/{state,tabs/xiaohongshu,generated}`）、skill（`pack.mjs --zip-out`）与 `.export/` 快照同步排除均已实现；定向单测与前端 vitest 通过，**真实 vite 项目上的首轮适配仍是唯一未验证项**。

 ## 2026-10-02 退役自建 Agent Runtime 与 CLI 执行面