Merge branch 'master' into codex/agc-client-mcp-facade
This commit is contained in:
@@ -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 并保持一致。
|
||||
|
||||
@@ -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、失败退款或余额结算语义。
|
||||
|
||||
## 外部服务与资产
|
||||
|
||||
|
||||
Reference in New Issue
Block a user