合并最新master到常用设置修复分支

同步远端master的最新修改
2026-09-09 02:15:42 +00:00
parent 1cf835418e a0e6a83691
commit 5bee48fede
63 changed files with 3311 additions and 1164 deletions
@@ -22,6 +22,7 @@
 - [LLM 累计额度结算](./technical/【技术方案】LLM累计额度结算-2026-09-05.md)：Router 累计额度、首次基线与原子钱包结算。

 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
+- [DirectProject Codex 原始历史与异常恢复](./technical/【技术方案】DirectProject%20Codex原始历史与异常恢复-2026-09-04.md)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
 - [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、OSS 清单格式和下载约定。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
@@ -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>` 双重转义为字面量 `&lt;tag&gt;`。
 - 美术：PNG、JPEG、WEBP、GIF、SVG、AVIF、BMP、MP4、WebM、MOV 只在资源卡本体中按既有受控读取、文件签名与解码门禁展示；中央详情不重复加载或放大图片 / 视频本体。SVG 继续拒绝脚本、事件处理器、外部资源引用和实体声明。
 - 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
 - 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。资源替换仍留给后续切片。
@@ -7961,6 +7961,12 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 新建/恢复 ephemeral Codex thread 时，replay 使用 `contextWindowTokens`、`autoCompactTokenLimit`、本次 `maxOutputTokens` 与 4096 安全余量计算预算，从最新记录向前选择连续完整的 `user` / `assistant` / `tool` 行；超预算旧前缀被省略，单条记录不截断，当前 user request 始终保留。
 - 发生省略时在 prompt 开头加入普通 `system: Earlier conversation history was omitted due to context budget.` 提示；当前请求本身超过硬上下文预算则直接失败。该策略是 Direct 专用滑动窗口，不复用 Runtime Agent 的摘要、tail 或 session compaction 生命周期。

+## 2026-09-07 DirectProject 用户消息由 AGC 预写并过滤 Codex 回显
+
+- `.agent/conversations/project.jsonl` 中的 DirectProject 用户消息由 AGC 在 `turn/start` 前以 `direct-codex:{clientTurnId}:user` 幂等追加；写入失败时禁止发起 Codex turn，失败或中断也保留该 user item。
+- Codex app-server 回显的 `userMessage` / `role=user` item 不是第二个历史来源。AGC 只处理其观察和关联，不再把该 echo 追加到项目历史；Codex 的 assistant、tool 和其它有效 response item 仍按现有 append-only 规则落盘。
+- 本地 AGC user-item 写入必须使用允许 user item 的内部入口，Codex raw item 写入使用过滤入口，避免“过滤回显”反过来阻断预写。相同 `clientTurnId` 只能复用相同规范化 prompt，内容冲突必须失败关闭。
+
 ## 2026-08-31 AGC 错误报告与诊断上传

 - AGC 采用 IDEA 风格的当前进程错误池：按 fingerprint 合并 React / window / Promise / Tauri / Agent 错误，重启后不恢复，不使用 run 或 run_id。
@@ -22,14 +22,15 @@
 AI 游戏创作 / DirectProject / UI workflow：

 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
-2. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
-3. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
-4. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`
-5. `docs/technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md`
-6. `docs/technical/【技术方案】Direct回合行为审计账本-2026-08-31.md`
-7. `docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`
-8. `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`
-9. UI 编辑器、宿主壳和当前测试专题文档
+2. `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`
+3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
+4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
+5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`
+6. `docs/technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md`
+7. `docs/technical/【技术方案】Direct回合行为审计账本-2026-08-31.md`
+8. `docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`
+9. `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`
+10. UI 编辑器、宿主壳和当前测试专题文档

 图片画布 / 媒体生成：

@@ -8,6 +8,8 @@
 - `GET /api/llm/models` 返回启用项的 `id/displayName` 和 `defaultModelId`，不返回实际模型名、Router 目录、凭据或能力原始数据。
 - AGC Responses 请求的 `model` 是稳定目录标识。服务端按当前目录映射实际模型名；未知、停用项拒绝，不回退其它模型。旧客户端无 AGC 标记时使用后台默认项。
 - 输入框右下角选择模型，只显示别名；选择保存到客户端配置 `selectedModelId`，从下一次请求生效。加载失败或选项停用时禁用提交并允许刷新，不显示实际 ID 作为兜底文案。
+- 首页聊天框架的右下角同样提供模型选择入口（与项目对话右侧一致）。首页入口按需加载模型目录（首次展开才请求），选择仅影响后续创建/发送的轮次，不阻塞「开启创作」，因此模型目录不可用时仍可创建项目并使用后台默认项。
+- 项目右侧对话的模型选择器在对话进行中保持可交互：切换模型只写回客户端配置并作用于下一轮，当前回合不受影响；发送按钮仍由 `controlBusy` / `modelReady` 把关。
 - 设置页恢复到布局改版前的官方代理版本，不包含模型管理或模型选择，保留配置安全清理和官方代理锁定。

 ## 验收
@@ -244,7 +244,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创

 - 模式升级：`agentMode` 扩为 `codex_app_server / codex_cli / provider`，新默认为 `codex_app_server`；V1.51 的一次性 `codex exec` 保留为显式兼容模式，HTTP Provider 保留为非 Responses 配置及故障回退模式。
 - 进程与节点：External Runner 按“有效 Agent LLM 凭据/Responses 路由 + `projectId/agentId/sessionId/runId`”隔离长期 `codex app-server --stdio`，即每个权威节点 run 直接持有自己的 Codex CLI 子进程与 ephemeral thread，每次完整权威请求映射 turn。同一节点 turn 串行，节点之间进程级隔离；单节点连接失败不得使其它节点同时失去终态。Codex thread 不写 durable recovery；节点完成、重启、retry、handoff 和 finalization 仍只认 AGC 账本。
- DirectProject replay：Codex thread 仍保持 `ephemeral=true`。`.agent/conversations/project.jsonl` 是聊天唯一、append-only 事实源；每个 GUI turn 在发起 app-server turn 前，先把渲染后的规范化 user prompt 以 `direct-codex:{clientTurnId}:user` 幂等追加，持久化失败则不发起 turn 并公开 failed；LLM 失败 / 中断时保留该 user 记录，重试同一 `clientTurnId` 只复用它。仅当 app-server 连接没有可用的项目 thread（通常是进程重启或 thread 被淘汰）时，AGC 才读取历史，按原顺序渲染为简单 `user:` / `assistant:` / `tool:` 行，再追加本次新 user request，发送给新建 thread；已有 thread 的普通消息仍只发送新 user。为避免持久增长的历史超过模型上下文，replay builder 使用全局 `contextWindowTokens`、`autoCompactTokenLimit`、本次 `maxOutputTokens` 和 4096 安全余量计算输入预算，从最新记录向前选择连续、完整的消息；超预算的旧前缀只在本次 prompt 中省略，不改写 JSONL、不写 summary/sidecar、不拆分单条记录。发生省略时在 prompt 开头加入普通 `system: Earlier conversation history was omitted due to context budget.` 行；当前 user request 始终保留，若其自身超过硬上下文预算则直接失败。这里的简单 role 前缀和普通 assistant partial（末尾 `unexpected interrupt happened here`）仍是产品合同：保持 prompt 形状稳定、避免 envelope breaking change，并让模型明确知道上次输出在断开处结束。app-server 意外中断时，已收到的 partial 文本按普通 `assistant` 消息追加；断开处理和下一次发送都可尝试写入，依赖普通 `messageId` 幂等。项目打开只读取历史，不因 user-only 记录自动重发；Direct 不提供 retry 入口。Runtime Agent 继续使用独立的 runtime/context 恢复链路，不读取 DirectProject 对话作为原生 thread history。
+- DirectProject replay：Codex thread 仍保持 `ephemeral=true`。`.agent/conversations/project.jsonl` 是聊天唯一、append-only 事实源；AGC 是 DirectProject 用户消息的唯一持久化来源：每个 GUI turn 在发起 app-server turn 前，先把渲染后的规范化 user prompt 以 `direct-codex:{clientTurnId}:user` 幂等追加，持久化失败则不发起 turn 并公开 failed；LLM 失败 / 中断时保留该 user 记录，重试同一 `clientTurnId` 只复用它。Codex 回显的 `userMessage` / `role=user` item 只用于事件观察和关联校验，不得再次追加到项目 JSONL，避免把服务端 echo 当作第二条用户消息；本地 user item 写入与 Codex echo 过滤必须区分来源，不能用同一个“忽略 user item”入口阻断 AGC 自己的预写。仅当 app-server 连接没有可用的项目 thread（通常是进程重启或 thread 被淘汰）时，AGC 才读取历史，按原顺序渲染为简单 `user:` / `assistant:` / `tool:` 行，再追加本次新 user request，发送给新建 thread；已有 thread 的普通消息仍只发送新 user。为避免持久增长的历史超过模型上下文，replay builder 使用全局 `contextWindowTokens`、`autoCompactTokenLimit`、本次 `maxOutputTokens` 和 4096 安全余量计算输入预算，从最新记录向前选择连续、完整的消息；超预算的旧前缀只在本次 prompt 中省略，不改写 JSONL、不写 summary/sidecar、不拆分单条记录。发生省略时在 prompt 开头加入普通 `system: Earlier conversation history was omitted due to context budget.` 行；当前 user request 始终保留，若其自身超过硬上下文预算则直接失败。这里的简单 role 前缀和普通 assistant partial（末尾 `unexpected interrupt happened here`）仍是产品合同：保持 prompt 形状稳定、避免 envelope breaking change，并让模型明确知道上次输出在断开处结束。app-server 意外中断时，已收到的 partial 文本按普通 `assistant` 消息追加；断开处理和下一次发送都可尝试写入，依赖普通 `messageId` 幂等。项目打开只读取历史，不因 user-only 记录自动重发；Direct 不提供 retry 入口。Runtime Agent 继续使用独立的 runtime/context 恢复链路，不读取 DirectProject 对话作为原生 thread history。
 - LLM 配置：`apiKind` 始终只接受 `openai_responses`；非空 Key 转换为 app-server model provider，base URL 生效，Key 仅走专用环境变量；空 Key 只桥接用户 Codex `auth.json`，不继承环境 `CODEX_API_KEY`。设置面板在 app-server 模式继续显示并保存 model、effort、stream、全局/逐 Agent Key 与路由配置；`openai_chat / anthropic` 明确提示切 `provider`，不得悄悄忽略。`stream=true` 接入 app-server 文本 delta；`webSearchEnabled=true` 只允许 DirectProject 经客户端审核的 `agc_web_search` 使用，不得启用 Codex 原生 webSearch 或任意网络。
 - 安全与取消：临时 cwd、隔离 `CODEX_HOME` 与 OS HOME、read-only、network off、never approval，并在启动前关闭 web/multi-agent/shell/browser/plugin/image 等原生能力；取消从 turn-start pending 阶段就跟踪且只 interrupt 当前 turn。已发送 turn 后连接断开或终态丢失进入 reconciliation，只关闭当前节点进程且不重放同一 request slot；明确 failed/interrupted 不按 transport 重试。
 - remote-control 认证边界：没有 ChatGPT `auth.json` 的 API Key / provider-proxy app-server 在启动时设置 Codex 内部环境变量 `CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED=1`，让 remote-control 以 `desired_state=Disabled` 启动，避免上游进入 1Hz 认证重试；不再依赖需要 ChatGPT 登录态的 `remoteControl/disable` RPC。只有实际桥接 ChatGPT 登录态的 AuthBridge 保持 remote-control 可用。API Key 子进程同时使用 `RUST_LOG=warn` 收敛剩余预期噪音，不伪造 `auth.json` 或静默继续。
@@ -252,6 +252,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 提前完成。
@@ -888,7 +895,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` 并在聊天里列出专业组、角色、任务状态、产物交接和下一步可执行任务；普通用户仍不暴露任务面板。
@@ -1081,7 +1088,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 回归及诊断零正文。
@@ -1293,6 +1300,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、回环 / 私网 / 本地域名，返回有界标题、摘要和结果链接，并以“不可信网页内容”标签回传。
@@ -0,0 +1,58 @@
+# DirectProject Codex 原始历史与异常恢复
+
+更新时间：`2026-09-07`
+
+## 目标
+
+DirectProject 只使用 `.agent/conversations/project.jsonl` 作为对话历史。历史保存 Codex Responses API 的完整 item，使聊天展示与新线程恢复使用同一份事实来源；两者只是不同读取动作。
+
+本方案只适用于 DirectProject，不改变 DirectHome、Agent session 历史或 `runtime/direct-codex/turns` 审计账本。
+
+## 文件格式
+
+每行采用 Codex CLI rollout 的最小事件外壳，不保存 AGC 自有的顺序号或运行环境字段：
+
+```json
+{"type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"你好"}]}}
+```
+
+`payload` 必须是未经改写的 Responses item。Direct 回合不由浏览器预写用户 message；Codex 返回的 `rawResponseItem/completed.params.item` 原样追加。显式的本地 user/assistant 补写只能通过受权限保护的 `append_direct_project_conversation_message` 命令完成。native 工具、MCP 工具、reasoning、调用参数和调用结果都保留完整内容，不截断、不摘要、不保存 delta/started 事件。
+
+DirectProject 不迁移旧 `{role,content}` 行；实现按新格式工作。
+
+## 正常回合
+
+1. 启动 `ephemeral: true` 线程，并启用 `experimentalRawEvents: true`。
+2. 新线程先把历史 item 数组一次注入；注入成功后执行新的 `turn/start`。本轮用户 item 只接受 Codex 回传的 `rawResponseItem/completed`，不由 AGC 预写。
+3. 收到 `rawResponseItem/completed` 后立即追加其 `params.item` 并 flush。
+4. 正常 `turn/completed: completed` 不生成额外记录。
+
+## 异常回合收尾
+
+AGC 判定本轮不会再产生新事件时收尾：用户中断、turn failed、无响应/idle timeout、硬超时、transport closed、stdout EOF 或 app-server 卡死终止均属于异常终态；正常 completed 不收尾。
+
+`item/agentMessage/delta` 正常带有 `itemId`；若协议异常缺失，AGC 记录 warning 并按当前 turn 生成稳定回退 id。AGC 在内存中按该 id 累计 assistant 文本，不实时写 delta。异常终态时，对仍有累计文本的 item 合成普通 Responses assistant `message` item：
+
+```json
+{"type":"response_item","payload":{"type":"message","role":"assistant","id":"msg_1","content":[{"type":"output_text","text":"已累计文本"}]}}
+```
+
+合成 item 在返回错误、销毁连接或启动恢复线程前追加并 flush。没有文本 delta 的半截工具/MCP 调用不合成，等待完整 `rawResponseItem/completed`。
+
+`rawResponseItem/completed` 缺少 `item`（包括 `null`）时视为反序列化错误；该回合按异常终态收尾，历史中不会写入非法空 item。
+
+Codex 启动时注入的 `host_skills.instructions`、`permissions.instructions` 和 `environments.environment_context` item 不属于项目对话历史；落盘时过滤，读取和线程注入时也过滤。过滤同时识别 role=user 的完整上下文标签包裹文本，即使该 item 没有 `internal_chat_message_metadata_passthrough` 元数据，也不能把它当成用户回合。
+
+## 恢复
+
+创建新的 ephemeral thread 后，读取 `project.jsonl` 中所有 `response_item.payload`，按文件行顺序一次调用 `thread/inject_items`，再执行新的 `turn/start`。Codex 负责上下文窗口管理；注入失败直接失败，AGC 不截断、摘要或改写历史。新 thread 已进入连接池但历史读取或注入失败时，必须先从池中淘汰并取消订阅该 thread，重试只能创建新 thread 并重新注入。
+
+`clientUserMessageId` 仅作为 Codex 用户消息的稳定标识随 `turn/start` 发送，不等价于 turn 级 exactly-once 幂等。断线后的重试仍须由项目侧持久化 turn ledger 或服务端去重合同决定，不能仅凭该字段再次执行。
+
+聊天界面只从 message item 提取 user/assistant 内容；工具 item 不再拼成 `tool: ...` 假文本。
+
+DirectProject 的浏览器层只负责显示和乐观状态，不再调用通用对话写入器；Rust 是该历史文件的唯一写入方。历史读写与回合累计分别位于 `agent/direct_project_history.rs` 和 `agent/direct_project_turn_history.rs`。
+
+## 写入与损坏边界
+
+写入使用 `write_all + flush`。读取时允许丢弃文件末尾一条不完整 JSON 行；中间坏行直接失败。不会对旧格式做迁移或兼容。
@@ -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 的失败归档作为任务行扩展保留。
@@ -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 已退出的证据。