Merge branch 'master' into style/better-error-report

2026-09-07 15:17:10 +08:00
parent 336cb17d94 60fbee2353
commit 4d264dd2b0
139 changed files with 13058 additions and 1735 deletions
@@ -0,0 +1,17 @@
+# AGC 后台模型别名与对话选择
+
+## 契约
+
+- 后台 owner 在“AGC 模型”维护列表；每项包含稳定 `id`、必填 `alias`、服务端 `modelId`、`enabled`。默认项必须启用。标识唯一，别名唯一，列表最多 32 项。
+- 配置保存到私有 `agc_model_catalog` 单例表，使用 revision 乐观锁，重启及多 api-server 实例共享同一事实。缺少配置时使用初始目录，高质量对应 `gpt-6-astra`，快速对应 `gpt-5.6-luna`。
+- `GET/PUT /admin/api/agc-models` 仅 owner 可用，返回完整配置；PUT 携带上次读取的 revision，冲突拒绝覆盖。
+- `GET /api/llm/models` 返回启用项的 `id/displayName` 和 `defaultModelId`，不返回实际模型名、Router 目录、凭据或能力原始数据。
+- AGC Responses 请求的 `model` 是稳定目录标识。服务端按当前目录映射实际模型名；未知、停用项拒绝，不回退其它模型。旧客户端无 AGC 标记时使用后台默认项。
+- 输入框右下角选择模型，只显示别名；选择保存到客户端配置 `selectedModelId`，从下一次请求生效。加载失败或选项停用时禁用提交并允许刷新，不显示实际 ID 作为兜底文案。
+- 设置页恢复到布局改版前的官方代理版本，不包含模型管理或模型选择，保留配置安全清理和官方代理锁定。
+
+## 验收
+
+- 目录领域校验、未知/停用模型拒绝、客户端响应不包含实际模型名。
+- 后台鉴权、持久化 revision 冲突处理；客户端选择保存后重新读取，设置保存不覆盖选择。
+- AGC/admin-web 类型检查与定向测试、编码检查、Rust 定向检查、schema 一致性与 diff 检查。
@@ -1617,6 +1617,7 @@ V1.51 在不替换现有 Provider、Runner 和 Runtime 事实源的前提下增
 ### 配置与验收

 - `check_game_creator_llm_config` 在 CLI 模式只检查固定 Codex 可执行文件可启动并返回受支持版本，不要求 LLM API Key；Provider 模式保持既有检查。配置 UI 显示全局模式，始终保留旧 LLM/逐 Agent/MCP/Editor 配置；切换模式不清空任何旧值。
+- Tauri 配置页触发的 `check_game_creator_llm_config` 必须通过阻塞线程池执行 Codex CLI / app-server 探测，不能在窗口线程同步等待；配置文件读写不得因诊断探测阻塞整个 GameAgent 窗口。
 - fake Codex fixture 必须覆盖 argv/stdin、structured calls、final text、非零退出、挂起取消、损坏/超限 JSONL、无 shell/MCP 参数和并发节点；真实 smoke 只复用用户已有 Codex 登录态。旧 Provider smoke 继续作为回退模式门禁，不能被新 CLI smoke 替代。

 ## V1.52 Codex app-server 长期节点 Agent 模式
@@ -217,7 +217,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.147.0` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
 - Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。
 - CLI 安全边界：CLI 固定使用 argv 启动，禁止 shell 拼接；工作目录使用本次请求专用的空临时目录，不把游戏项目绝对路径写入 prompt、stdout、stderr 或持久记录。调用固定使用 ephemeral、忽略用户配置和 exec rules、read-only sandbox、never approval，并关闭 Codex shell tool；只继承 CLI 运行和认证所需的最小环境，显式移除宿主 `CODEX_API_KEY`。用户级 Codex 登录态继续由本机 Codex 自己读取，API Key、auth 文件、Cookie、Token、`CODEX_HOME` 私有内容不得复制到项目配置、Runtime sidecar、Agent DB、conversation 或日志；stdout / stderr 无换行时也受硬上限约束，stderr 诊断只记录固定分类、字节数和 SHA-256。
- 协议边界：Runtime 把既有 `LlmRunRequest` 的消息和当前函数目录编码为有界 prompt，并从同一函数 JSON Schema 生成 Codex structured-output schema。CLI 输出转换为现有 `LlmRunResponse / LlmToolCall` 后，继续经过 native tool / MCP 参数校验、动作上限、权限、pending、receipt、验证与格式修复链；最终回复仍走现有脱敏和唯一提交路径，不新增平行响应协议。
+- 协议边界：Runtime 把既有 `LlmRunRequest` 的消息和当前函数目录编码为有界 prompt，并从同一函数 JSON Schema 生成 Codex structured-output schema。CLI 输出转换为现有 `LlmRunResponse / LlmToolCall` 后，继续经过 native tool / MCP 参数校验、动作上限、权限、pending、receipt、验证与格式修复链；最终回复仍走唯一提交路径，不新增平行响应协议。
 - 取消与恢复：Codex 子进程绑定当前 Provider request lifecycle，取消、暂停、Runner draining 或 GUI owner 丢失时终止并回收当前进程；started 后没有可信终态仍沿现有 Provider reconciliation 处理。`agentMode`、CLI 可执行身份和影响输出的 Codex 参数进入 `providerConfigFingerprint`，模式切换不得消费另一模式遗留的 retry/handoff。
 - 可用性与兼容：`check_game_creator_llm_config` 在 `codex_cli` 模式检查 Codex 可执行文件和版本，不再要求 HTTP API Key；在 `provider` 模式保持原有 API Key、base URL、model 和逐 Agent override 校验。设置面板始终保留旧 Provider 配置，模式切回后不得丢失既有密钥或逐 Agent设置。配置向导若写入 HTTP Provider 凭据，必须显式把模式切到 `provider`。
 - 验收：覆盖缺省模式、显式 Provider 回退、配置 round-trip、CLI 缺失/非零退出/损坏 JSONL/超限输出、structured tool calls、普通最终回复、进程取消、模式指纹漂移和旧 Provider 回归；同时执行 AGC 定向 Rust 测试、前端配置测试与 typecheck、配置门禁、编码检查和 `git diff --check`。
@@ -1198,8 +1198,8 @@ game-project/

 - 普通项目对话只由一个 project-bound Codex app-server thread 执行。客户端系统提示词只放最小工程合同、当前游戏源码有界快照、项目 prompts 和审核 Skill 索引；不再批量读取项目 `.codex/.agents` Skill 正文，也不恢复 Supervisor、专业 Agent 或 harness。
 - 首页恢复“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。该选择与设置页的 Agent Runtime 模式无关；每次首页提交仍只自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 仅作为受限结构化首轮上下文传给同一 Codex thread，不拼接“初始意图”文案、不产生首页对话、不切换 Provider 或恢复旧 Runtime 编排。
- `agc-skill-pack.v1` 只包含项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影五项 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync`，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文与 references 均由 Codex 原生 Skill 机制按意图和声明的相对路径按需读取。
- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP；2026-08-31 起还会在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置，但不读取用户全局 Codex MCP、不开启完整 Plugin Runtime。`agc_tools` 工具固定为标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景和 desktop/mobile 浏览器试玩。内置 MCP 进程只做协议；真实浏览器与付费 External v1 调用通过随机 loopback 地址回到客户端主进程，因此不复制 GUI 登录态、开发者 Key、项目路径、revision、operation 或幂等键到模型上下文。内置与用户启用的第三方 MCP 工具都沿用 DirectProject 自动批准方式，但付费资源工具仍由客户端绑定稳定回合身份、限制单回合请求数、串行执行并优先恢复匹配账本；Codex 原生 webSearch、任意原生命令网络、多 Agent 和完整插件能力继续关闭。
+- `agc-skill-pack.v1` 只包含项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影五项 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync`，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文由 Codex 原生 Skill 机制按意图加载，一层引用只能经 `agc_read_skill_resource` 读取清单内 Markdown。引用路径按平台无关规则拒绝反斜杠、盘符、UNC、绝对路径和 `..`，不能依赖当前宿主的 `std::path` 语义判断其它平台路径。
+- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP；2026-08-31 起还会在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置，但不读取用户全局 Codex MCP、不开启完整 Plugin Runtime。内置工具固定为审核引用读取、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`。内置 MCP 进程只做协议；真实浏览器、付费 External v1 调用与受控搜索通过随机 loopback 地址回到客户端主进程，因此不复制 GUI 登录态、开发者 Key、项目路径、revision、operation 或幂等键到模型上下文。内置与用户启用的第三方 MCP 工具都沿用 DirectProject 自动批准方式，但付费资源工具仍由客户端绑定稳定回合身份、限制单回合请求数、串行执行并优先恢复匹配账本；通用 shell、Codex 原生 webSearch、任意原生命令网络、多 Agent 和完整插件能力继续关闭。`llm.webSearchEnabled` 只控制 DirectProject 的 AGC 受控搜索工具暴露与执行，Codex 原生 `web_search` 始终保持 disabled；Provider、ToolHost、DirectHome 不纳入本次联网主链路。
 - 陶泥儿生成继续复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端优先使用当前 AGC 登录会话及账号路由，只有受控的 ExternalDeveloper 发布模式才在客户端内部使用按服务器 origin 隔离的私有 Key。用户和模型都不需要提供或配置 API Key；凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
 - 自定义 LLM API Key 路由只在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理不注入 Key，只要求请求自带 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，防止隔离 app-server 把 API Provider 误判为余额 0；旧 ToolHost 保持原 Provider 行为。

@@ -1274,3 +1274,11 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
 - `autonomous-game-build` 运行档位采用自主并行编排：manifest `dependencies` 仅作为上下文提示，不参与 ready 判定；代码、设计、美术、音频和发布 child 可以按调度器可用性并行启动。child 不要求固定 task ID、owner、parent-child lineage、run ID 或回执顺序，完成投影按同一项目事实幂等收束。
 - 该档位不把最终验收条件提前成启动条件，也不把平台画布、preview、static smoke、发布包或其它平台产物检查作为 child 或根 Supervisor 的完成门。缺少平台产物不会把已完成任务重置为 `Pending`；根 run 只等待任务图进入终态并交回结果。
 - 代码可先按约定的项目路径落地并完成自己的工作；后续任务状态变化只负责唤醒同一根 run 继续收束，不因 `art-polish`、`art-asset-plan` 等非代码任务失败而阻塞代码启动。平台产物和可玩性检查若需要，属于后续独立验收，不是本档位的运行前置条件。
+
+## 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、回环 / 私网 / 本地域名，返回有界标题、摘要和结果链接，并以“不可信网页内容”标签回传。
+- Codex 原生 `web_search` 在 app-server 启动参数中始终保持 `web_search=\"disabled\"`。`llm.webSearchEnabled` 在 `DirectProject` 仅表示受控工具开关，不得被状态文案解释为 Codex 原生联网；工具桥关闭时即使收到旧调用也失败关闭。原生命令网络、任意外部 MCP、工具参数透传、网页内容改写系统规则 / 身份 / 权限 / 协议均继续禁止。
+- 配置文件新增 `schemaVersion: \"game-creator-config.v2\"`。新默认配置开启 `stream` 与受控联网；无版本旧配置在启动时补写 v2，旧 `codex_app_server` 路由仅在省略 `webSearchEnabled` 时按历史默认补为开启，显式 `false` 保留；Provider / Anthropic 路由未提供搜索覆盖时保持关闭，避免继承 DirectProject 默认。主配置按完整配置迁移；本地覆盖只补 schema 版本，不凭不完整 overlay 推断或写入 `agentMode` / 搜索布尔值。
+- `/llm-status`、开发单 Agent 状态和项目 Agent 状态卡对 Codex 模式显示“流式开启 / 关闭”“受控联网开启 / 关闭”“Codex 原生 web_search 关闭”，不显示 API Key、URL、请求头、绝对路径或 Provider 原始错误正文。
+- BDD 验收场景与测试映射：DirectProject 默认工具目录包含 `agc_web_search` 且原生搜索仍 disabled；未审核字段、越界数量和非公开 URL 在桥接端失败关闭；旧无版本配置迁移为 v2 且按路由得到正确默认；状态卡显示三态安全摘要。对应 Rust `configuration`、`direct_tools_mcp`、`direct_tool_bridge`、`codex_app_server` 定向测试及前端状态格式化 / AppSurface 测试。
@@ -291,7 +291,7 @@ chat_with_game_creator_direct_codex

 `direct_game_creator_codex_chat_at_with_optional_observer` 增加可选 `audit: Option<&mut DirectCodexTurnAudit>`，再传到 `run_turn_with_direct_observer`。仅 `workspace_mode == DirectProject` 且 `audit` 为 Some 时抽取。

-`run_direct_game_creator_turn_inner` 的 UI observer 保持只处理 `AccumulatedText` / `Activity`。
+`run_direct_game_creator_turn_inner` 的 UI observer 把 `AccumulatedText`（仅开启流式时）映射为 `streaming`，`IntermediateText` 与 `Activity` 一律映射为 `running`，只向前端暴露安全活动词与可见正文，不携带原始 item JSON。

 回合失败（生成失败、浏览器试玩失败、回复落盘失败）：只要 `start` 过就 `finish(false)`，保留已观察到的 item。Codex 尚未启动则 `itemCount=0`。

@@ -0,0 +1,35 @@
+# LLM 累计额度结算
+
+## 目标与边界
+
+使用 New API `GET /api/user/{id}` 的 `used_quota` 累计值结算，不按 token 估价，不依赖单次响应 cost，不建立本地 WAL、余数 Map 或延迟队列。模型调用前同步并检查余额，成功响应后再同步；失败、断流或进程退出留下的消耗由下一次调用前同步补结算。不承诺无后续调用的闲置账号立即结清。
+
+## 单位与算法
+
+Router `GET /api/status` 的 `data.quota_per_unit` 已实测为 500000，即每美元 500000 quota。美元数值直接乘 10 转泥点，不使用 USDExchangeRate。每泥点对应 50000 quota，采用整数运算。查询时验证单位不变，异常时拒绝结算，不静默改价。
+
+```text
+pending = max(observed_used_quota - settled_quota, 0)
+charged_points = min(pending / 50000, spendable_points)
+next_settled_quota = settled_quota + charged_points * 50000
+```
+
+`settled_quota` 只推进实际扣费对应的部分。查询失败、钱包被冻结、扣款失败时不推进。重复或乱序快照不回退游标；Router 重置累计值需人工核对，不自动清零本地记录。
+
+## 持久化与事务
+
+新增私有表 `llm_router_billing_checkpoint`，主键沿用已认证用户的 `llm_router_account.account_key`，保存 `router_user_id`、`settled_quota` 和更新时间。账号 owner/route 来自现有本地映射，不信任客户端提交的 Router ID；同一映射更换 Router ID 时拒绝结算，需明确迁移。
+
+首次同步在模型请求之前执行：若没有 checkpoint，以当前累计额度完整建立基线，不扣历史，不抹零。现有账号与首次接入账号均在使用前建立基线。
+
+只有服务身份可以调用结算 procedure。事务内先检查人工冻结与退款欠款限制（包括尚不足一整点与首次初始化），再读取 checkpoint，计算可扣金额，更新钱包和流水，最后推进 checkpoint；三者同一事务提交。返回的剩余可消费余额扣除了退款占用与本次消费，模型调用前据此拒绝零可用余额。并发、重复快照和响应丢失后重试不能重复扣费。流水 ID 由账号与已结算额度区间构成，而非单次请求 ID。
+
+新增流水来源 `llm_router_consume`，显示“LLM 调用消耗”，保持免费/会员/永久泥点消耗顺序、退款冻结和消费统计。历史资产来源流水不改写；旧资产生成扣费/退款协议不变。
+
+## 验收
+
+- 首次基线、234 余量跨次保留、重复/乱序快照、余额不足、零余额、整数溢出均有定向测试。
+- Router 查询验证业务 success、用户 ID、非负整数 used_quota、quota_per_unit；错误不打印凭据或原始用户数据。
+- 模型请求前基线失败关闭；成功模型响应不因后置同步故障变为失败，下一次可重试。
+- schema 同步 migration、表目录、生成绑定，运行定向 Rust 测试、schema guard、编码检查、diff check。
+- 本次不部署、不迁移历史钱包流水、不修改外部 OpenAPI。