Merge branch 'master' into feat/agc-codex-native-tool-call-info
This commit is contained in:
@@ -3372,8 +3372,14 @@
|
||||
},
|
||||
"sliceLayout": {
|
||||
"type": "string",
|
||||
"enum": ["grid-2x2"],
|
||||
"description": "可选固定图集切片合同。省略时沿用全图 alpha 连通域自动拆分；传 grid-2x2 时服务端要求生成四个固定象限，并按左上、右上、左下、右下各持久化一个独立切片。该模式适用于需要恰好四类核心运行时素材的游戏，不会猜测等分裁切。"
|
||||
"deprecated": true,
|
||||
"description": "历史兼容字段，新的调用请使用 sliceCount。"
|
||||
},
|
||||
"sliceCount": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"description": "可选的目标切片数量；省略时按图像内容自动识别。"
|
||||
},
|
||||
"screenColor": {
|
||||
"type": ["string", "null"],
|
||||
@@ -3597,15 +3603,21 @@
|
||||
},
|
||||
"iconImageSrcs": {
|
||||
"type": "array",
|
||||
"description": "默认模式识别图集中全部有效 alpha 连通域并持久化的独立素材，按视觉阅读顺序命名为“素材 N”；数量由图集内容决定，不由 iconDescriptions 数量决定。sliceLayout=grid-2x2 时固定返回左上、右上、左下、右下四个格子的切片，各格内的零散视觉细节不会被拆成额外素材。",
|
||||
"description": "识别图集中有效 alpha 连通域并持久化的独立素材，按视觉阅读顺序命名为“素材 N”；可通过 sliceCount 指定目标数量。",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
|
||||
}
|
||||
},
|
||||
"sliceLayout": {
|
||||
"type": "string",
|
||||
"enum": ["grid-2x2"],
|
||||
"description": "仅当请求使用固定切片合同且主图完成透明化、切片持久化后返回。调用方可将该字段与 iconImageSrcs=4 共同作为固定四类素材的来源证明。"
|
||||
"deprecated": true,
|
||||
"description": "历史兼容字段。"
|
||||
},
|
||||
"sliceCount": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 100,
|
||||
"description": "实际生成的切片数量。"
|
||||
},
|
||||
"sliceWarning": {
|
||||
"anyOf": [
|
||||
|
||||
@@ -185,7 +185,7 @@ completed -> starting(nextSlice)
|
||||
idle -> focused(document|art|audio|version) -> idle
|
||||
```
|
||||
|
||||
- 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。
|
||||
- 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。聊天侧 `/read` 回执中的文件正文必须作为代码块渲染为 `<pre><code>`，以便用户审阅源码字面量但不执行其中的 HTML；Markdown 渲染使用 `react-markdown` 的 `skipHtml`，依赖库对代码 span / fenced code 的文本转义；不得在整段 Markdown 上预转义 HTML，否则会把代码中的 `<tag>` 双重转义为字面量 `<tag>`。
|
||||
- 美术：PNG、JPEG、WEBP、GIF、SVG、AVIF、BMP、MP4、WebM、MOV 只在资源卡本体中按既有受控读取、文件签名与解码门禁展示；中央详情不重复加载或放大图片 / 视频本体。SVG 继续拒绝脚本、事件处理器、外部资源引用和实体声明。
|
||||
- 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
|
||||
- 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。资源替换仍留给后续切片。
|
||||
|
||||
@@ -1507,6 +1507,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 背景：主站与图片画板的泥点余额入口、余额明细和充值弹窗存在不同实现，旧充值口径仍展示六档泥点、首充双倍和会员购买 / 升级入口，容易让展示、商品资格与后端余额真相发生漂移。
|
||||
- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。钱包明细每次展开都重新读取充值中心 BFF，打开期间实时总额变化时继续补读；图片画板的生成扣费或退款完成后同时刷新总额与充值中心拆分。充值中心读请求必须使用 revision 门禁，支付创建、到账确认等权威响应写入时使旧读失效，避免旧响应覆盖新的每日免费 / 不限时明细。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
|
||||
- 2026-07-17 追加：主站、图片画板与 AI 游戏创作独立 App 的泥点账单统一复用 `packages/shared/src/components/PlatformProfileWalletLedgerModal`。共享组件只依赖 `ProfileWalletLedgerResponse`，承接来源 label、金额正负号、UTC 日期、余额兜底和 loading / empty / error 展示；`/api/profile/wallet-ledger` 请求、鉴权、打开状态与重试生命周期继续由各宿主持有，不把账户事实或后端副作用下沉到共享 UI。
|
||||
- 2026-09-07 追加：资产扣费在既有钱包流水 metadata 中记录服务端确定的 `assetKind`，`GET /api/profile/wallet-ledger` 只把白名单类型映射为可选用户文案 `reason`，不暴露原始 metadata、资源 ID、任务 ID 或未知内部枚举。共享账单组件优先展示非空 `reason`；历史、未知和空 metadata 继续按 `sourceType` 回退为“资产操作消耗”，不得由客户端猜测业务类型。
|
||||
- 影响范围：`profile_recharge_product_config` 默认商品、充值中心 read model、共享前后端契约、主站与图片画板泥点资产入口、充值弹窗、后台充值商品默认值。
|
||||
- 验证方式：充值与统一入口定向前端测试、`npm run typecheck`、充值商品定向 Rust 测试、`cargo check -p spacetime-module -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
@@ -51,9 +51,11 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
|
||||
|
||||
## AGC DirectProject 与 UI workflow
|
||||
|
||||
- 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建，已有单 HTML/Godot 不自动迁移。
|
||||
|
||||
- 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。
|
||||
- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP，并在启动时额外读取客户端扩展仓库中已启用的第三方 MCP 独立项。第三方 STDIO/HTTP 配置只写入本次隔离 `CODEX_HOME`，单项非 required，启停、重命名和内容指纹进入 app-server pool identity；完整 Plugin Runtime、hooks/apps 和单文件脚本手动指定入口仍关闭。Skill 正文与 references 由 Codex 原生按需读取；`agc_tools` 负责标准美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`；付费资源调用仍由客户端绑定回合、幂等账本、请求上限和投影权威。
|
||||
- DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在真实 `game/` cwd 与 `workspaceWrite(writableRoots=[game])` 内可用；原生命令网络保持关闭。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。
|
||||
- DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在用户项目 cwd 与 `workspaceWrite(writableRoots=[project])` 内可用；原生命令允许联网以支持 npm 安装，npm 缓存位于项目内 `.npm-cache/`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。
|
||||
- `ui-prototype`（设计图片）与 UI 编辑器 `UI` JSON 是不同资源。白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`，由 provider-backed 识别、合并和组件绑定持久化 State/revision，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 投影到 manifest。Provider 缺失、请求失败、工具缺失、结果不匹配或仍有待审节点时保留真实阶段并返回 blocker，不得用 deterministic seed 伪造完成。
|
||||
- UI workflow 的资源桥接与 Runtime 边界以 `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 和 AGC 实施计划的 2026-08-24 覆盖段为准；只生成图片、登记空 JSON 或进入普通图片画布都不构成 workflow 完成。
|
||||
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# AI 游戏创作智能体 App 实施计划
|
||||
|
||||
## 2026-09-08 Web 游戏 npm 与 Phaser 4 产物合同
|
||||
|
||||
新建 Web 游戏使用 npm 工程：默认 `game/package.json` 声明 Phaser 4.2.1 和 Vite 构建工具，源码使用 `import Phaser from 'phaser'`，`package-lock.json` 由 npm 维护。默认脚手架文件位于 `game/`，包含 `index.html`、`game.js`、`style.css`、`vite.config.js` 和 npm 配置/锁文件；已有根目录 npm 工程沿用原根，可按需求拆分模块并添加任意其它 npm 依赖，不设置包名白名单。客户端不手工分发 Phaser bundle，不用 import map 模拟 package 导入。
|
||||
|
||||
Agent 在包含 `package.json` 的目录执行 `npm ci`（依赖变更使用 `npm install`）和 `npm run build`；默认可从工作区根执行 `npm --prefix game ci` 与 `npm --prefix game run build`。DirectProject 保持 workspace-write 目录边界并开放网络，以支持 npm 依赖解析和安装；凭据仍由客户端代理持有，不进入项目或原生命令环境。其它执行模式维持现有权限。新游戏完成后执行 `npm run build` 并用真实浏览器试玩；依赖安装与构建失败必须反馈真实错误，不能回退成未解析裸模块导入的静态页面。
|
||||
|
||||
npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.html`，静态 smoke 校验构建入口及本地文件引用，实际可玩性由浏览器验证。预览服务与导出读取该构建目录，所有运行素材必须由构建纳入 dist；npm 预览不回退读取源码或项目素材目录，保证试玩与导出一致。源码投影包含 package、锁文件、配置和真实游戏源码，排除 `node_modules/`、`dist/`、控制文件与凭据；npm 试玩包将 dist 文件映射到 `game/` 并附带发布说明，不包含源码依赖安装目录。现有单 HTML 项目不自动迁移，Godot 项目保持原合同。旧 JSON Generator 仅接受已初始化的单 HTML 项目，npm 项目或新建请求在调用 LLM 前明确拒绝并引导使用 DirectProject，避免静态草案伪装为 npm 构建产物。本节覆盖下文仅适用于旧单 HTML 产物的 Canvas API、手写动画循环和禁止外部本地脚本要求。
|
||||
|
||||
## 2026-09-02 项目名称显示与自动提炼
|
||||
|
||||
- `.agent/manifest.json` 的 `name` 仍是本地项目显示名唯一事实源；项目组页行尾更多菜单提供行内重命名，保存必须走 Tauri 受控命令、项目写锁、manifest 写锁与既有 ACL/权限校验。重命名只更新 manifest，不改变项目目录、`projectId`、项目类型、任务、资源、版本或远端同步状态；保存成功后当前项目上下文、窗口标题和最近项目检查结果必须回读新 manifest 并保持一致。
|
||||
@@ -58,6 +66,10 @@ Runtime 确认卡与普通聊天确认卡必须共用“信息区 + 固定操作
|
||||
|
||||
## 2026-08-19 UI Editor 节点右键菜单
|
||||
|
||||
## 2026-09-05 UI Editor 节点树快捷删除
|
||||
|
||||
左侧 `UI Tree` 每个可删除节点行在右侧提供桌面端快捷删除按钮，眼睛与删除按钮组成固定宽度的右侧动作列；整棵树保留横向滚动，深层节点的缩进、完整名称和组件数随树内容一起滚动，不使用省略号截断。沿用右键菜单的页面根节点禁删规则。快捷删除与右键删除共用页面级 `requestDelete` 入口：叶子节点直接调用现有删除命令；包含后代节点时先打开模态确认，正文显示节点名称及将同时删除的后代节点数量，按钮为“取消 / 删除”。确认期间使用现有 `ThemedModal` 的模态行为，取消或完成后关闭弹窗。底层 `deleteNode` 命令继续保持无确认，以兼容键盘 `Delete` 及已有状态测试；锁定态下快捷按钮和右键删除均不可执行。
|
||||
|
||||
## 2026-08-20 UI Editor 最终预览互斥子节点
|
||||
|
||||
最终预览中，选中一个 `Exclusive` 父节点时，它的子节点切换条必须在该父节点自身的预览坐标空间内、紧贴节点上方悬浮；不得固定在预览容器左上角，也不得另行按屏幕坐标换算。点击 tab 必须显式选中对应子节点，不能按通用“切换可见性”语义把当前分支隐藏。`Exclusive` 父节点首次加载且尚未发生可见性操作时，必须默认且仅显示第一个直接子节点；用户手动隐藏全部直接子节点后必须保持全部隐藏，不得再次回退显示第一个子节点；空容器不显示子节点。切换条始终按内容宽度展开并允许溢出节点边界，不设最大宽度或内部滚动区域。从 `Exclusive` 切回 `Stack` 时必须清除全部直接子节点因互斥选择产生的隐藏状态并立即显示所有子节点，后代节点自身的独立隐藏状态保持不变。切换条仅改变现有子节点可见性状态，不能触发参考图重读、视口重新适配或预览树的异步重建。
|
||||
@@ -234,6 +246,13 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
|
||||
- 旧配置迁移：既有 AppData 若没有 `agentMode`，只有全局和逐 Agent 路由均为 `openai_responses` 时迁移到 `codex_app_server`；存在 `openai_chat / anthropic` 时显式保留 `provider`，避免打开项目自动恢复时把所有节点批量写成 `invalid-config`。用户确认端点支持 Responses 后，可在设置中显式切换并保留原 model/base URL/API Key。
|
||||
- 验收：fake JSON-RPC fixture、三态 UI/config、配置指纹、unknown-terminal 零重放、旧两种模式回归和显式 ignored 真实 smoke 全部通过后，才可视为模式切换完成。
|
||||
|
||||
### 2026-09-03 AGC 客户端能力以 MCP 暴露
|
||||
|
||||
- MCP 暴露是客户端能力层，不替换 `codex_app_server / codex_cli / provider` 或客户端对话。客户端对话入口继续驱动 Codex app-server；app-server 通过客户端随附的 stdio MCP 子进程调用审核后的客户端能力。客户端不再替 Codex 做业务语义门禁、意图判断和完成判定。
|
||||
- MCP 会话在客户端握手时绑定当前账号、项目和实例，工具参数不得携带 `projectPath`、Token、Cookie、objectKey 或内部 URL。仅暴露稳定业务白名单与 `resources/list/read`，所有文件、资源、画布、预览和 operation 副作用继续复用客户端权限、锁、计费、幂等账本、manifest/revision 与恢复机制。
|
||||
- 客户端对话继续写入现有 conversation projection；外部 Host 如需旁路保存返回文本，可显式调用 `conversation.record_codex_response`。客户端将有界、脱敏正文、SHA-256、安全摘要和状态追加到项目级 journal，UI 只展示记录，不从文本推断业务状态或触发副作用。
|
||||
- MCP 子进程只由当前客户端为绑定项目启动，并在该项目工作目录内运行；客户端回合结束或客户端退出后子进程随 Codex app-server 一并回收。账号和项目权限仍由客户端业务桥接层校验，未知副作用保持 `needs-reconciliation`，只能通过 operation 查询恢复。稳定验收覆盖客户端对话驱动的 MCP 工具调用、Skill 指导资源、跨项目/账号拒绝以及旧 Provider/Codex 回归。
|
||||
|
||||
### 2026-08-10 Supervisor 边做边聊与条件中断
|
||||
|
||||
- 根 Project Supervisor 的运行中消息继续进入当前 `taskId / sessionId / runId`，先持久显示“正在判断、当前任务继续”，再由独立 LLM 生成非终态语义回复并给出 `interruptCurrentProvider`。过程回复不能调用终态 `respond_to_user`，不能把制作 Run、Goal 或 task 提前完成。
|
||||
@@ -870,7 +889,7 @@ game-project/
|
||||
- 聊天输入 `/status` 会读取 `.agent/manifest.json` 并在聊天里汇总项目目录、任务状态、资产数量、预览状态和最近命令，不向普通用户暴露任务或文件面板。
|
||||
- 聊天输入 `/files` 会通过 `file.list` 只读列出本地项目内的文件摘要；主窗口最近项目文件可一键读取，也可一键填入 `/read` 或 `/asset-register` 草稿，但资产登记仍必须走聊天确认；`/checkpoints` 复用 `file.list` / `file.read` 只读列出最近 checkpoint id、文件数、大小和可复制的 `/diff` / `/restore` 命令，主窗口最近 checkpoint 列表也可填入对应草稿；普通用户仍不暴露文件读写面板。
|
||||
- 聊天输入 `/assets` 会读取 `.agent/manifest.json` 并在聊天里列出本地项目资产路径、类型和来源，资产列表消息和主窗口最近项目资产入口都可一键填入对应资产的 `/read` 草稿；聊天输入 `/art` 只使用当前已加载 manifest 盘点美术素材，并提供首版美术生成或读取美术清单草稿，不直接读取文件、不触发平台生成或画板同步；聊天输入 `/audio` 只使用当前已加载 manifest 盘点音频素材，并提供登记音效或读取音频清单草稿，不直接读取文件、不触发资产写入；`/asset-register 路径 [kind] [mediaType]` 可确认后登记项目内已有资产；主窗口音效快捷入口只填入 `/asset-register assets/audio/sfx.wav audio audio/wav` 草稿，不直接写 manifest；普通用户仍不暴露资产面板。
|
||||
- 聊天输入 `/read 本地相对路径` 会通过 `file.read` 只读返回项目内文本文件内容并在聊天中截断长文本；普通用户仍不暴露文件写入或删除能力。
|
||||
- 聊天输入 `/read 本地相对路径` 会通过 `file.read` 只读返回项目内文本文件内容并在聊天中截断长文本；聊天回执中的正文必须包装为安全的 `<pre><code>` 代码块，保留源码字面量但不得执行 HTML；普通用户仍不暴露文件写入或删除能力。
|
||||
- 主窗口常用生成产物入口只把 `game/index.html`、`game/game_design.md`、`game/balance.json`、`assets/manifest.art.json`、`assets/manifest.audio.json` 和 `exports/README.md` 的 `/read` 草稿填入聊天输入框；聊天输入 `/artifacts` 只列出这组固定读取命令并提供首个 `/read` 草稿，聊天输入 `/run-artifacts` 只列出最近 run trace 里的产物读取命令并提供首个 `/read` 草稿，聊天输入 `/run-files` 只列出 `.agent/output.jsonl`、`.agent/activity.jsonl` 和 `.agent/context.bundle.json` 的读取命令并提供首个 `/read` 草稿；读取仍由聊天侧 `file.read` 权限流执行。
|
||||
- 聊天输入 `/logs` 只列出 `.agent/logs/command.log`、`.agent/logs/preview.log` 和 `.agent/logs/agent.log` 对应的 `/read ...` 草稿 / 命令，并提供首个 `/read` 草稿；该命令不直接读取日志，不新增普通用户日志面板，实际读取仍由聊天侧 `file.read` 权限流执行。
|
||||
- 聊天输入 `/tasks` 会读取 `.agent/manifest.json` 并在聊天里列出专业组、角色、任务状态、产物交接和下一步可执行任务；普通用户仍不暴露任务面板。
|
||||
@@ -1063,7 +1082,7 @@ game-project/
|
||||
- 内部 owner 验证只接受 GUI / CLI 完整 16 任务 DAG 中 `agent-ready-task-scheduler` 启动的确定性直接 child、当前活跃根和完整 project/source/profile/Agent/run/parent/root/binding 身份。错误 source、delegated run、历史或终态根、非当前活跃根、跨 Agent/run 凭证均失败关闭；再次 mutation 使旧凭证失效，相同身份恢复可按当前事实确定性重验。本阶段不扩到后置 `publish-package`。`code-prototype` 与 `preview-readiness` 继续执行真实 `game.static_smoke`，`preview-playtest` 继续独立执行浏览器验收；任何 owner 文件凭证都不能替代可玩证据。
|
||||
- `design-foundation` 的 2026-07-26 职责隔离继续有效：项目文件仍只允许 `memory/project.md`、`game/game_design.md` 和配置 Key 时的固定 `assets/ui-prototype.png`，禁止修改 `game/index.html`、调用 smoke / preview / process 或恢复整项目。未配置 External Editor API Key 时 `art-director` 保持只读协调；配置 Key 时它是条件 Canvas owner，必须生成并登记 `assets/art-spec.png`，成功 `canvas.asset_generate` 为本人当前 revision 形成普通验证凭证，不能被只读分类吞掉。配置 Key 时 UI 原型、透明图集、Canvas 登记和视觉门仍按既有合同执行，内部 owner 文件验证不替代图片证据。
|
||||
- `canvas.asset_generate.replaceExisting` 默认并必须保持 `false`；只有静态专业 Agent 的 `delegated-*` 唯一 repair run 才能申请 `true`。Runtime 要求当前 delivery 带 `repairOfDelegationId`，原 delivery 已被同一父 Agent / 父 run 认领，原始与返工合同的目标 Agent 和精确 `expectedArtifacts` 路径一致；普通 run、未声明路径、错误 Agent、未认领原交付或缺失原图都失败关闭。图片生成仍服从 `art-director` / `design-foundation` / `art-asset-plan` 的固定输出路径、比例、尺寸、kind 和 label，禁止先删除正式图片；请求前记录旧文件 SHA-256，外部生成返回后在项目写锁内复核，旧图在网络请求期间变化即拒绝覆盖。授权替换先写私有临时文件，再以备份 / rename 切换；落盘或 manifest 登记失败时恢复旧图，不把新旧文件并存状态当作成功。
|
||||
- 在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 用当前调用模式的图片生成 `kind=spec` 生成 `assets/art-spec.png` 并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的稳定资源 ID 作为视觉规范参考，用同模式图片生成 `kind=ui-design` 生成 `assets/ui-prototype.png`；`art-asset-plan` 以同一 resource ID 调用同模式图标 spritesheet 生成，产出透明 `assets/art-spritesheet.png`。普通模式使用内部 `/api/editor/*`，standalone/高级模式使用对应 `/api/external/v1/*`；业务请求、依赖和验收完全一致。规范图缺失、未登记或缺少稳定资源 ID 时，下游任务不得退回普通生图。图集 warning、透明像素与切片门禁保持不变。
|
||||
- 视觉 Agent 只负责指导 Codex 选择合适的图片/编辑/图集工具并提供项目上下文，不再固定图片数量、文件槽位、素材类别或 spritesheet 布局；请求可按玩法需要生成单图、多图或任意切片布局。普通模式使用内部 `/api/editor/*`，standalone/高级模式使用对应 `/api/external/v1/*`；权限、计费、幂等、资源登记和安全校验保持不变。
|
||||
- 旧项目已有同路径派生图但缺少上述 provenance 时，一律标记为 legacy，不得只因文件、kind 或通用视觉检查存在就完成。原位替换仍走显式 repair：`design-foundation` 与 `art-asset-plan` 先在同一 Supervisor 批次分别建立 owner 精确原合同并交付 `needs-repair`，父 run 认领后再在同一批次分别发起各自唯一 repair；两个 repair 合称一个显式视觉返工阶段。`art-director` 不得跨 owner 声明或替换 UI / spritesheet，Runtime 在委派落盘前就拒绝这类合同，不再等到生图阶段才失败。
|
||||
- 2026-07-27 新起的“16 任务正式产物 + 两张真实画布图片 + current revision 静态 / 双视口浏览器 / PNG 证据 + 受限 repair 替换”独立外部 Provider 验收，使用 `npm run agc:test:chat -- --timeout-minutes 75`，约 `59m50s` 后以退出码 `0` 完整 **PASS**。同一轮真实生成并登记 `assets/ui-prototype.png`（`2829418` bytes）与 `assets/art-spritesheet.png`（`1361906` bytes），固定 `16` 个 manifest task 均为当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物、两张 PNG、当前 revision 的 `game.static_smoke`、desktop / mobile `lane-defense-v1` playtest、浏览器报告与截图全部通过。`turn.report=settled` 且唯一 assistant，busy / pending / running / confirmation / user-input / reconciliation 均为 `0`；隔离 Runner、一次性项目和隔离 AppData 已自动清理。此前失败轮继续独立保留，不与本轮拼接；未来合同变化仍须新起完整轮次复验。
|
||||
- 2026-07-27 补充 tool-plan 成功响应交接的内容边界：Provider 的自然语言计划叙述，以及结构化 arguments 中 `body / code / content / css / html / newText / oldText / patch / script / text` 等源码内容字段，只检查真实密钥 token 形状、凭据头标记和不安全控制字符；仅仅提及 `.env` 或 `game-creator.config` 不能阻断已经计费的安全响应。结构化输入中的敏感 JSON key、非内容字段中的配置痕迹或绝对路径、真实 token、容量、thinking、身份、顺序和账本完整性门禁仍失败关闭。成功 handoff 失败进入 reconciliation 时，Runtime 额外只持久化受控 `failureKind`、脱敏错误 SHA-256 和字符数，不保存 Provider 正文、function arguments、密钥或绝对路径。定向回归覆盖叙述/源码字段放行、`.env.local` 路径和真实 token 拒绝、全部 tool-plan handoff 回归及诊断零正文。
|
||||
@@ -1275,6 +1294,15 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
|
||||
- 该档位不把最终验收条件提前成启动条件，也不把平台画布、preview、static smoke、发布包或其它平台产物检查作为 child 或根 Supervisor 的完成门。缺少平台产物不会把已完成任务重置为 `Pending`；根 run 只等待任务图进入终态并交回结果。
|
||||
- 代码可先按约定的项目路径落地并完成自己的工作；后续任务状态变化只负责唤醒同一根 run 继续收束，不因 `art-polish`、`art-asset-plan` 等非代码任务失败而阻塞代码启动。平台产物和可玩性检查若需要，属于后续独立验收，不是本档位的运行前置条件。
|
||||
|
||||
## 2026-09-04 AGC 项目聊天 Markdown 与流式回复渲染
|
||||
|
||||
- 项目开发工作台的 `ProjectWorkspaceChatPane`、`ProjectSupervisorView` 与 `SupervisorChatOnlyView` 继续共享 `ChatMessage` / `visibleMessages` 数据结构；聊天 Markdown 只作为前端表现层能力，不新增消息字段、持久化格式、后端 DTO 或事件协议。
|
||||
- 三个视图统一复用 `apps/ai-game-creator-shell/src/components/ChatMarkdownMessage`。assistant 历史消息和流式临时回复使用 `react-markdown + remark-gfm` 渲染；用户消息与命令草稿保持纯文本。调用方仍先执行现有的 `projectSupervisorVisibleConversationText` 安全文案归一化，再交给展示组件。
|
||||
- 流式回复以事件中的 `accumulatedText` 作为当前完整草稿：每次更新替换上一版临时正文，不在渲染层自行拼接 `deltaText`。既有 `runId` / sequence 去重、最终 assistant 持久化和历史回放语义保持不变。
|
||||
- Markdown 禁止原始 HTML；链接和图片只显示普通文本，不产生可点击或可加载的外部资源。后续若开放安全外链，必须另行评估协议白名单、窗口策略和审计边界，并保留实现 TODO。
|
||||
- Markdown 元素样式使用 Tailwind 内联 class，限定在聊天消息组件内部，不改全局 `.message`、资源文档预览或启动器全局 Agent 聊天。组件异常按单条消息回退纯文本，不能使整个聊天面板崩溃。
|
||||
- 流式更新沿用“仅在用户接近底部时跟随”的滚动语义；用户主动查看历史时不得被实时 Markdown 高度变化强制拉回底部。实现验收需覆盖 GFM、未闭合 Markdown 中间态、HTML/链接/图片安全、三视图一致性、流式去重、历史回放和桌面/移动视口。
|
||||
|
||||
## 2026-08-29 DirectProject 受控联网搜索闭环
|
||||
|
||||
- 本次正式产品范围只包含 `DirectProject` 单 Codex Agent；`Provider`、`ToolHost`、`DirectHome` 不新增联网工具桥，也不纳入本次联网路由覆盖。受控联网唯一实现为 `agc_tools.agc_web_search`：Codex app-server 通过审核的 STDIO MCP 工具目录发起调用，客户端 loopback 工具桥执行固定 Bing RSS HTTPS 请求，过滤非 HTTPS、凭据 URL、回环 / 私网 / 本地域名，返回有界标题、摘要和结果链接，并以“不可信网页内容”标签回传。
|
||||
|
||||
@@ -14,6 +14,10 @@
|
||||
|
||||
## 3. 已确定的产品边界
|
||||
|
||||
### 3.0 客户端能力 MCP 暴露边界（2026-09-03）
|
||||
|
||||
客户端仍由现有对话入口启动并驱动 Codex；MCP 只是把客户端已审核的项目、文件、资源、画布、生成和预览能力暴露给该 Codex 或其它 Host。客户端只负责账号、项目路径、权限、计费、幂等、锁和恢复等自身安全，不替 Codex 做高层意图/完成门禁。审核 Skill 的索引和正文可作为只读 MCP resource 提供，第三方扩展不得获得客户端会话凭据、内部路径或 bridge token；该能力与公网 `/api/external/v1/mcp` 保持独立。
|
||||
|
||||
### 3.1 客户端安装、运行时注入
|
||||
|
||||
- 扩展内容保存在 AGC 客户端的扩展仓库。
|
||||
|
||||
@@ -89,6 +89,10 @@ Codex app-server 协议里，`commandExecution.commandActions` 已分类为 `Rea
|
||||
|
||||
不升级 `GAME_CREATOR_AGENT_DB_SCHEMA_VERSION`；新 `recordType` 走 Ordinary 追加。`updatedAt` / `schemaVersion` 仍由 `serialize_agent_db_record` 写入。
|
||||
|
||||
### 2026-09-03 客户端对话与 MCP 能力边界
|
||||
|
||||
客户端对话仍由现有 Codex app-server 链路完成；MCP 只暴露客户端自身业务能力和审核 Skill 指导。客户端安全门禁限于账号、项目路径、权限、计费、幂等、锁、revision 与恢复，不根据 Codex 自然语言替代 Codex 决定业务动作。外部 Host 返回如需旁路归档，可使用显式记录工具，但不替代现有 conversation projection，也不触发资源、状态或完成判定。
|
||||
|
||||
jsonl 每条自带 `recordedAtMs`（`unix_millis`）。同一 `clientTurnId` 若再次进入（当前 GUI 运行中互斥，结束后理论上可再来）：只追加，不截断；后一次 `turn_start` 视为新 attempt。读摘要时按文件内最后一次 `turn_start` 到对应 `turn_end` 计算 `offeredRead`。`agent.db` 每次 `turn_end` 再追加一条摘要，分析取该 `clientTurnId` 最后一条。
|
||||
|
||||
## 5. 记录合同
|
||||
|
||||
@@ -76,6 +76,7 @@
|
||||
### 失败生成任务归档与任务侧栏
|
||||
|
||||
- 用户界面的“删除失败任务”语义是归档，不物理销毁私有 generation ledger。只有平台明确失败的 `failed` 任务可归档；`reconciliation-required`、已受理、运行中和结果未知任务不得移出恢复队列。
|
||||
- 已受理 operation 在重试时若请求快照发生变化，客户端可先对原 operation 执行一次只读状态查询；仅当平台明确返回 `failed` 时才自动收口旧账本并允许新提交，排队、运行中、完成或未知状态继续保持原幂等身份并阻断替代请求。
|
||||
- 归档命令校验 project、draft、generation 与 expected draft revision，先把私有 ledger 写入可重放的 `archiving/archivedAt`，再从 `draft.generations` 移除公开投影并推进一次 revision；草稿删除成功并回读后才发布 `archived`。`archiving` 以及历史上已写 `archived` 但仍残留公开记录的状态都必须在恢复阶段幂等收敛，且不依赖图片生成服务凭证。
|
||||
- 失败占位和右上角任务项复用同一个归档动作，成功后两处同时消失，其它任务、图层和候选不受影响。
|
||||
- 任务侧栏折叠只属于当前会话 UI 状态，不写入 draft 或 manifest。视觉和交互复用现役美术画布：右上角独立“任务列表”图标按钮、20rem 白色模糊卡、总数徽标、`排队/生成中` 与 `已完成` 双 Tab、状态圆形图标、阶段进度和时间信息；折叠后只保留图标按钮，不显示摘要卡。用户显式新建 generation 时自动展开并切回活动 Tab，普通进度更新不得推翻用户已有折叠选择。Game Agent 的失败归档作为任务行扩展保留。
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# UI 编辑器工作流完成通知弹窗
|
||||
|
||||
## 目标
|
||||
|
||||
UI 编辑器的“分析参考图”“识别界面结构”“绑定视觉素材”三个工作流动作在每次运行结束后，用独立的阻塞通知弹窗明确反馈结果，避免仅依赖卡片内一行状态文本而被忽略。
|
||||
|
||||
## 交互约定
|
||||
|
||||
- 三个动作的每次运行在终态（成功或失败）时自动弹出一次通知。
|
||||
- 弹窗打开期间遮挡并阻塞工作台底层交互；关闭后恢复当前步骤，不自动切换步骤、不自动重跑。
|
||||
- 使用现有 `ThemedModal` 的普通关闭行为（遮罩、Esc 和关闭按钮均可关闭）。
|
||||
- 弹窗仅承载通知，不提供“继续”“重试”或其他业务操作。
|
||||
- 关闭弹窗后，工作流卡片继续显示同一条结果状态；重新运行产生新的终态时再次通知。
|
||||
- 绑定动作包含多个批次时，只在最终批次结束后通知一次。
|
||||
|
||||
## 文案
|
||||
|
||||
弹窗标题由步骤名和结果态组成，例如“识别界面结构完成”或“绑定视觉素材失败”。正文复用卡片状态文本，并逐条扩展结果信息，统一以“请检查”收尾。
|
||||
|
||||
成功状态的基线文案：
|
||||
|
||||
- 分析参考图：保留已应用的语义建议数量；若现有状态可可靠取得问题/待确认数量，则一并展示。
|
||||
- 识别界面结构：保留替换的界面树数量，并展示识别结果中的待检查/必须修复数量（若可取得）。
|
||||
- 绑定视觉素材：保留现有 `B/B` 批次计数，改为用户可读的绑定结果。
|
||||
|
||||
失败状态保留实际错误文本，仅在弹窗标题中补充步骤和失败上下文，正文同样以“请检查”收尾。
|
||||
|
||||
## 实现边界
|
||||
|
||||
- 新增独立的工作流通知弹窗组件文件，组件只负责展示和关闭，不包含工作流领域规则或后端副作用。
|
||||
- 在 UI 编辑器页面/会话投影中维护临时通知状态，并在三个异步动作的成功与失败终态写入。
|
||||
- 不新增后端字段或公开契约；数量只能使用当前前端已有且可靠的数据。
|
||||
|
||||
## 验收
|
||||
|
||||
1. 三个动作成功和失败终态各弹出一次通知；绑定批次只弹最终一次。
|
||||
2. 弹窗打开时底层工作台不可操作，且无继续/重试等业务按钮。
|
||||
3. 弹窗可通过标准关闭方式退出；关闭后卡片状态仍可见。
|
||||
4. 每条成功文案保留原有数量信息并增加可用的检查数量，所有文案包含“请检查”。
|
||||
5. 重新运行后新的终态会再次弹出通知。
|
||||
@@ -48,13 +48,19 @@ UI 编辑器支持撤销最近一次或多次作品编辑，并支持重做被
|
||||
|
||||
- 桌面端页面工具栏提供撤销和重做按钮。
|
||||
- 非文本编辑目标聚焦编辑器时支持 `Cmd/Ctrl+Z` 撤销、`Cmd/Ctrl+Shift+Z` 和 `Ctrl+Y` 重做。
|
||||
- `input`、`textarea`、`select`、`contenteditable` 以及按钮/链接等控件交给浏览器原生行为，不拦截文本撤销。
|
||||
- `input`、`textarea`、`select`、`contenteditable` 等文本编辑控件交给浏览器原生行为，不拦截文本撤销；按钮/链接等非文本控件仍允许编辑器撤销/重做快捷键生效。
|
||||
- UI Editor 页面内选中节点后，支持不带修饰键的 `Delete` 删除节点及其子节点；快捷键复用 Inspector、树面板和右键菜单共用的 `deleteNode` 命令，因此沿用根节点/锁定禁删、单条历史记录、dirty 标记和后续保存语义。
|
||||
- `Delete` / `Backspace` 在 `input`、`textarea`、`select`、`contenteditable`、按钮和链接等交互控件聚焦时交给浏览器原生行为；无选中、根节点、锁定或目标不存在时不执行删除。长按重复事件不重复删除，成功处理后阻止默认行为和事件冒泡。
|
||||
- `Delete` / `Backspace` 在打开的对话框（`role="dialog"` 或 `aria-modal="true"`）内聚焦时交给对话框处理，不删除对话框背后的节点。
|
||||
- `Cmd/Ctrl+Z`、`Cmd/Ctrl+Shift+Z` 和 `Ctrl+Y` 在打开的对话框（`role="dialog"` 或 `aria-modal="true"`）内聚焦时暂停编辑器级撤销/重做，由对话框或浏览器原生行为处理。
|
||||
- 无可撤销或重做记录时按钮禁用，并提供可访问名称。
|
||||
|
||||
## 脏状态与选择
|
||||
|
||||
撤销和重做恢复的 State 继续参与现有 dirty 判定、保存和后端持久化。历史快照不包含当前设计图、节点选择、隐藏集合或视口；恢复后若当前选择已不存在，页面清理无效选择并保持安全空态。
|
||||
|
||||
删除节点后，若当前选中节点是被删除节点或其任意后代，页面将选区清空为 `null`；删除成功不强制抢占焦点。该选择清理属于 UI 临时状态，不写入撤销历史。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. 单次字段编辑可撤销和重做。
|
||||
@@ -67,3 +73,4 @@ UI 编辑器支持撤销最近一次或多次作品编辑，并支持重做被
|
||||
8. 工具栏按钮、禁用态和桌面快捷键可用，文本控件保留原生撤销。
|
||||
9. no-op、锁定、校验失败和不存在目标不进入历史。
|
||||
10. 颜色选择器和九宫格边界拖动不会按每个 pointer move 写入 State。
|
||||
11. `Delete` / `Backspace` 仅在非交互控件聚焦且存在可删除选中节点时生效；删除整棵子树、可撤销、长按只处理一次，并清理被删除子树内的无效选区。
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# 预览画布缩放滑杆
|
||||
|
||||
## 交付目标
|
||||
|
||||
将 UI 编辑器预览区现有的缩放按钮替换为桌面端可拖动滑杆，同时保留快速缩小、放大和适配画布操作。
|
||||
|
||||
## 交互约定
|
||||
|
||||
- 滑杆选择范围为 25%–200%，步进 5%；快捷加减继续使用核心视口的现有缩放边界。
|
||||
- 滑杆位于预览区右下角固定工具栏；不提供移动端或窄窗口 fallback。
|
||||
- 保留 `−` 与 `+` 按钮。点击轨道可跳转，拖动滑块实时更新画布和百分比。
|
||||
- 缩放以视口中心为中心，继续支持 Ctrl/Cmd + 滚轮缩放。
|
||||
- 滑杆支持方向键、Home、End；百分比文本可点击编辑并在失焦时限制到有效范围。
|
||||
- 百分比文本使用数字输入框呈现；输入提交后同步视口缩放，适配画布保持独立按钮，点击百分比不会触发适配。
|
||||
- 缩放滑杆获得焦点时，Delete/Backspace 不触发 UI 节点快捷删除；缩放按钮鼠标点击不改变快捷键焦点。
|
||||
- Windows/Linux 使用 `Ctrl`，macOS 使用 `Cmd`；`+`、`=` 与 `NumpadAdd` 放大，`-` 与 `NumpadSubtract` 缩小，允许按键重复时连续缩放。
|
||||
- 快捷键直接复用现有 `+`/`−` 按钮动作：以视口中心为锚点，按 `×1.16`/`×0.86` 改变缩放。
|
||||
- 鼠标悬停在预览画布上，或预览画布已获得键盘焦点时，快捷键生效。预览画布需提供可聚焦语义与无障碍名称。
|
||||
- 事件来自输入框、文本编辑区、按钮、链接、缩放工具栏或其他可操作控件时不拦截；不向 iframe 子文档注入监听。
|
||||
- 仅在存在可缩放视口且确认命中快捷键时调用 `preventDefault()` 与 `stopPropagation()`，防止浏览器页面同时缩放。
|
||||
- 保留现有 `Ctrl/Cmd+0` 适配画布与 `Ctrl/Cmd+1` 恢复 100% 行为，不增加其他重置快捷键。缩放仍是当前预览实例的临时 UI 状态。
|
||||
- 保留快捷键与缩放焦点边界的组件级回归测试，不扩展端到端测试。
|
||||
|
||||
## 验收
|
||||
|
||||
桌面端可通过按钮、轨道点击、拖动和键盘改变缩放；百分比与画布同步，边界不会越界。组件级测试覆盖平台修饰键、主键盘与小键盘变体、按键重复、悬停/焦点作用域、可编辑与可操作目标放行、无内容放行、浏览器默认行为拦截和现有 `0`/`1` 回归；另运行前端定向类型检查、编码检查和 `git diff --check`。
|
||||
@@ -251,6 +251,7 @@ npm run check:server-rs-ddd
|
||||
10. 已有静态图片的 `POST /api/editor/images/pixel-art-snaps` 是免费 inline 派生操作，不调用外部 provider、不创建 `external_generation_job`、不读写泥点 ledger，也不进入任务侧栏。免费不放宽 owner、稳定引用、输入上限、持久化或处理阶段零持久化门禁。
|
||||
11. 主站编辑器生成队列使用同一次前端请求稳定复用的 `x-request-id`，按 namespace + owner + job kind + request id 生成唯一 `dedupe_key`；首次请求已入队但响应丢失时，重试必须返回原任务。同一幂等键携带不同 payload 返回 `409`，不得创建第二个任务或串到旧结果。外部 v1 的 `Idempotency-Key` 使用独立 namespace，不能与主站请求标识碰撞。幂等 payload 比较只对本次已迁移 sanitizer 的图片生成、图片修改、去背景、图标图集和 UI 提取任务，兼容“升级前旧任务仍含客户端 `generationInputs.references`、当前请求已删除该字段”的单向形状；当前请求仍含 references，或 job kind 属于音频 / 视频 / 角色动作等未迁移任务时必须完整比较，其余请求字段始终完全一致。
|
||||
12. `generationInputs.references` 是最终资产的服务端权威行引用，不接受客户端自报 provenance。图片生成类请求入队、完美像素及直接创建资源 / 素材时删除客户端 references；worker 和 inline 路径按本次真实参考图、当前 owner 的项目资源 / 素材记录重建 `refType/refId` 后再持久化。仅能证明 owned objectKey、但找不到对应资源或素材行时可以参与生成，不得制造虚假行引用；`title/label` 只作为展示快照，不提升为资源身份。完美像素为兼容升级前的未知结果重放，可继续用旧版 canonical 客户端输入计算 operation fingerprint；新操作持久化元数据只能使用服务端重建值。owner-scoped 项目快照发现同一 operation 的稳定 result `resourceId` 时，HTTP 路径必须在来源解析、OSS 下载、规整、preflight 和 PUT 前直接返回 `409`，携带 `operationResultAlreadyExists=true` 与 `resultResourceId`，客户端仅以 GET-only 项目对账判定权威结果，不复用既存 metadata 作 exact compare-and-return。
|
||||
13. 资产操作扣费必须在既有 `profile_wallet_ledger.metadata_json` 中记录服务端确定的 `assetKind`；外部生成任务继续同时记录 `externalGenerationJobId` 与 `externalGenerationClaimAttempt`。公开 `GET /api/profile/wallet-ledger` 不返回原始 metadata、资源 ID 或任务 ID，只为 `asset_operation_consume` 下发可选的用户可见 `reason`：图片、图标图集、美术规范、UI 设计和发布素材等图片生成统一显示“生成美术素材”，图片修改显示“编辑美术素材”，UI 素材提取显示“提取美术素材”，角色动画、视频、音效和背景音乐分别显示对应生成原因。未知、空值和未携带新 metadata 的历史流水不猜测业务含义，不下发 `reason`，共享前端继续回退到来源类型文案“资产操作消耗”。该展示投影不得改变定价、扣费顺序、幂等 ledger、失败退款或余额结算语义。
|
||||
|
||||
## 外部服务与资产
|
||||
|
||||
|
||||
@@ -62,7 +62,7 @@ Linux 本机多用户并发开发时，`npm run dev`、`npm run dev:*` 单模块
|
||||
|
||||
后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
|
||||
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
|
||||
|
||||
Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user