Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.
TypeScript agent-skillscodex-clideskop-appdubbingimage-generationlocalizationskillsttsvideo-editingvideo-generationvideo-transcriptionvideo-translation
chore: stop tracking local specifications
Leggett0eef011c3e84
diff --git a/.gitignore b/.gitignoreindex 6cacdf54..cae54530 100644--- a/.gitignore+++ b/.gitignore@@ -13,6 +13,7 @@ coverage/test-results/.superpowers//docs/superpowers/+/docs/specs/codex-main/open-design-main/.gstack/diff --git a/docs/specs/2026-07-14-scheduled-task-dedicated-thread-design.md b/docs/specs/2026-07-14-scheduled-task-dedicated-thread-design.mddeleted file mode 100644index c2c0fd7c..00000000--- a/docs/specs/2026-07-14-scheduled-task-dedicated-thread-design.md+++ /dev/null@@ -1,1982 +0,0 @@-# OpenCreator 定时任务专属会话重构规格--## 0. 文档信息--| 项目 | 内容 |-|---|---|-| 文档状态 | 已实施;真实原生 Desktop Host 验收阻塞 |-| 版本 | 1.1 |-| 创建日期 | 2026-07-14 |-| 最近更新 | 2026-07-15 |-| 适用范围 | OpenCreator Web、Local Runtime Daemon、Protocol、Scheduler、Thread、Run、通知 |-| 规格优先级 | 本文档覆盖并替代 `docs/2026-07-03-codex-native-agent-runtime-design.md` 中 Scheduler 的旧会话模型 |-| 执行计划 | `docs/plans/2026-07-14-scheduled-task-dedicated-thread-design-plan.md` |-| 发布运行手册 | `docs/operations/2026-07-15-scheduled-task-dedicated-thread-release-runbook.md` |-| 最终验收报告 | `docs/test-reports/2026-07-15-scheduled-task-dedicated-thread-final-acceptance.md` |--本文是可直接实施的产品和技术规格。后续开发应按本文的 P0、P1、P2 顺序执行。实现过程中如需改变数据模型、接口或关键交互,必须先更新本文,再修改代码。--### 0.1 实施结果--- P0、P1 和 P2 的 24 个实现批次为 `PASS`。-- 全仓测试、类型检查、构建、14 个桌面/移动 Playwright、100 任务性能门禁、旧库升级- 与回滚演练、真实 Codex 14/14 smoke 均通过。-- 最终批次 P2-B7 为 `BLOCKED_ENV`,总体状态为 `PARTIAL`。-- 仓库没有真实原生 Desktop Host,页面关闭后的系统通知展示和点击深链无法在当前环境- 实机验收。outbox、Bridge 契约和 harness 已通过,但不替代 Host 实机证据。-- 下文未勾选项保留为原始验收清单;实际执行证据以最终验收报告为准。--## 1. 一句话定义--**定时任务不是独立的提醒系统,而是一个带定时触发器的 OpenCreator 长期会话。**--一个定时任务必须对应一个专属 OpenCreator 会话。同一个定时任务的每次自动执行、立即执行、审批、失败和结果,都进入同一个会话。定时系统只决定何时向该会话发起下一次 Agent 执行,实际能力继续由 OpenCreator 的普通 Run 和 Codex CLI 提供。--## 2. 已确认需求--1. 用户可以用自然语言让 AI 创建定时任务,也可以手动创建。-2. 每个定时任务创建一个专属会话。-3. 同一个定时任务始终复用同一个 OpenCreator 会话。-4. 同一个 OpenCreator 会话底层优先复用同一个 Codex thread。-5. 每次触发的任务输入、执行过程、审批和最终结果都追加到该专属会话。-6. 左侧最底部增加“任务”区域,展示定时任务对应的专属会话。-7. “任务”不是旧的技术 Run 中心,不向普通用户展示底层 Run 列表。-8. “已安排”负责创建、编辑、暂停、恢复、立即运行和删除。-9. “任务”负责查看执行历史、最新结果以及继续和 AI 对话。-10. 通知点击后直接进入任务专属会话,并定位到最新一次执行。-11. 喝水提醒、每日工作总结、定时生成文稿、读取项目、生成文件等都走同一套执行机制。-12. 原则上 OpenCreator 普通会话可以完成的任务,定时任务也可以完成。-13. OpenCreator 自己存储和调度任务,Codex CLI 只作为 Agent 执行引擎。--## 3. 目标与成功标准--### 3.1 产品目标--1. 普通用户不需要理解 cron、Run、Codex session、source id 等技术概念。-2. 用户看到的是一个长期任务,以及这个任务持续产生的对话和结果。-3. 用户可以在任务会话中继续提出要求,例如“以后控制在 300 字以内”或“改到晚上 8 点执行”。-4. 用户离开任务会话后,任务继续执行;再次进入时立即看到当前运行状态和最新结果。-5. 不同任务互不污染上下文,同一个任务保留连续上下文。--### 3.2 技术成功标准--1. 每条未删除的 `schedule` 都有唯一的 `thread_id`。-2. 每次 Schedule Run 都同时写入 `runs.source_id` 和 `runs.thread_id`。-3. 同一 Schedule 的所有新 Run 的 `thread_id` 相同。-4. 同一任务会话内禁止并行写入,任务触发必须串行。-5. 定时触发、立即执行和用户在会话中发消息都使用同一个 `RunManager`。-6. Schedule Run 可以使用对应会话的项目、Profile、模型、推理强度、权限、Skills 和 MCP。-7. 服务重启后可以恢复 Schedule 和 Thread 的绑定,不创建重复会话。-8. 点击成功、失败或待审批通知,都能进入正确的任务会话。-9. 旧版没有 `thread_id` 的 Schedule 可以自动补齐专属会话。-10. 旧版孤立的 Schedule Codex session 不会重新出现在普通会话列表中。--## 4. 非目标--本轮重构不包含以下能力:--1. 不把调度迁移到 Codex 官方“已安排”产品。-2. 不实现云端调度服务。-3. 不实现多人共享任务。-4. 不实现跨设备同步。-5. 不允许定时任务绕过既有 Sandbox、审批和 Profile 约束。-6. 不承诺浏览器页面完全关闭时仍能展示浏览器系统通知;原生后台通知属于 P2。-7. 不重写 Codex Agent loop、Skills runtime 或 MCP runtime。-8. 不把旧技术 TaskCenter 重新作为普通用户菜单展示。--## 5. 当前实现与问题--### 5.1 当前数据模型--当前 `schedules` 表保存:--- `name`-- `cron`-- `timezone`-- `prompt`-- `profile`-- `cwd`-- `model`-- `reasoning`-- `sandbox`-- `timeout_ms`-- `concurrency_policy`-- `next_run_at`-- `last_run_id`-- `last_status`--当前缺少:--- `thread_id`-- 任务专属会话类型-- Agent 创建任务时的结构化工具入口-- 通知到任务会话的稳定深链接--### 5.2 当前触发流程--```text-Schedule 到期- -> SchedulerService.handleTrigger()- -> RunManager.startRun()- -> 不传 threadId- -> 创建独立 Run- -> Codex 创建独立 session- -> 完成后通知跳到“已安排”-```--这导致:--1. 每次执行可能产生新的 Codex session。-2. 同一任务没有连续上下文。-3. 任务结果无法自然沉淀到一个可继续对话的页面。-4. 通知只能打开“已安排”或诊断信息。-5. 旧逻辑为了隐藏重复会话,会归档所有 `created_by='schedule'` 的会话。-6. 自然语言创建器目前是提醒语句正则解析,不是真正的 Agent 创建。--### 5.3 必须移除的错误假设--以下假设不再成立:--1. Schedule Run 是独立 Run。-2. Schedule 产生的 Codex session 都应该隐藏。-3. 通知的目标页面是“已安排”。-4. 定时任务只用于提醒。-5. `parallel` 可以用于同一个任务会话。--## 6. 核心设计决策--### 6.1 OpenCreator 持有调度状态--定时任务继续保存在 OpenCreator SQLite 中,由 OpenCreator Daemon 计算下次执行时间并触发。--Codex CLI 的职责只有:--1. 接收本次任务输入。-2. 恢复或创建 Codex thread。-3. 使用工具完成任务。-4. 返回事件和最终结果。--### 6.2 Schedule 与 Thread 一对一--关系定义:--```text-Schedule 1 ---- 1 Thread-Schedule 1 ---- N Run-Thread 1 ---- N Run-Run N ---- 1 Schedule-Run N ---- 1 Thread-```--约束:--1. 一个未删除 Schedule 必须绑定一个 Thread。-2. 一个 Thread 最多绑定一个未删除 Schedule。-3. Schedule Run 的 `source_id` 必须等于 Schedule ID。-4. Schedule Run 的 `thread_id` 必须等于 Schedule 的 `thread_id`。--### 6.3 OpenCreator Thread 与 Codex Thread 分层--OpenCreator 的任务会话 ID 是稳定的产品身份。--Codex thread ID 是可更换的执行身份:--```text-稳定的 OpenCreator thread_id- -> 当前 codex_thread_id- -> 必要时因恢复失败、上下文轮换而切换-```--即使未来底层 Codex thread 因上下文过长需要轮换,用户看到的 OpenCreator 任务会话仍然不变。--### 6.4 “已安排”和“任务”同时保留--两者职责不同:--| 入口 | 用户目标 | 主要内容 |-|---|---|---|-| 已安排 | 管理什么时候执行 | 创建、编辑、暂停、恢复、立即运行、删除 |-| 任务 | 查看执行了什么 | 任务会话、运行状态、历史结果、继续对话 |--“任务”不复用旧的技术 TaskCenter 页面。旧 TaskCenter 可以继续作为内部诊断组件,但不出现在普通用户导航中。--### 6.5 同一任务只允许串行执行--同一个 Thread 不能同时被两个 Codex Run 写入。--新任务只支持:--- `queue`:默认。当前运行结束后补执行一次,重复触发合并为一个待执行状态。-- `skip`:如果当前任务会话正在运行,本次触发跳过。--不再允许新建 `parallel` Schedule。旧数据中的 `parallel` 在迁移时转换为 `queue`。--### 6.6 Schedule 配置是任务执行配置的真相源--Schedule 保存时间和任务内容,同时绑定的 Thread 保存执行上下文。--以下字段必须保持同步:--| Schedule | Thread |-|---|---|-| `name` | `title` |-| `cwd` | `cwd` |-| `canonical_cwd` | `canonical_cwd` |-| `profile` | `profile` |-| `model` | `model` |-| `reasoning` | `reasoning` |-| `sandbox` | `sandbox` |--时间、启停、Prompt、超时和并发策略只属于 Schedule。--所有配置更新通过 Schedule 协调服务完成,不能只更新一侧。--## 7. 信息架构和页面设计--### 7.1 左侧导航--建议结构:--```text-新对话-搜索-已安排-插件--项目- 项目 A- 普通会话 1- 普通会话 2--任务- 喝水提醒 下次 10:30- 每日工作总结 正在运行- 每日生成 100 字文稿 失败--设置-```--规则:--1. “任务”固定在左侧靠下位置。-2. 任务会话不再混入项目普通会话列表。-3. 每个任务行显示名称、状态图标和未读标记。-4. 正在运行时显示旋转状态。-5. 等待审批时显示醒目的审批状态。-6. 失败时显示失败状态,但不直接展开技术错误。-7. 已暂停任务仍显示,标记“已暂停”。-8. 已删除任务不显示,其会话进入归档。-9. 点击任务立即清空旧会话内容并显示加载状态,避免短暂显示上一个会话。--### 7.2 “已安排”页面--列表行至少包含:--- 任务名称-- 任务内容摘要-- 友好执行频率-- 下次执行时间-- 当前状态-- 最近结果状态-- 打开任务会话-- 立即执行-- 暂停或恢复-- 编辑-- 删除--任务名称或“打开会话”按钮进入专属任务会话。--“查看上次运行”不再默认打开诊断抽屉,而是进入任务会话并定位到对应 Run。诊断信息保留为二级操作。--### 7.3 任务会话头部--任务会话顶部显示一个紧凑任务栏:--- 任务名称-- 已启用或已暂停-- 下次执行时间-- 正在运行、等待审批或失败状态-- 立即执行按钮-- 暂停或恢复按钮-- 编辑按钮--不得使用大面积卡片或教学说明占用对话空间。--### 7.4 手动创建--手动表单保留普通用户需要的字段:--1. 任务名称-2. OpenCreator 要做什么-3. 执行频率-4. 项目-5. 是否启用--高级设置折叠展示:--- 时区-- Profile-- 模型-- 推理强度-- 权限-- 超时-- 冲突策略--提交成功后:--1. 创建 Schedule。-2. 创建专属 Thread。-3. 返回 `threadId`。-4. 前端自动进入任务会话。-5. 左侧“任务”立即出现新任务。--### 7.5 使用 OpenCreator 创建--用户点击“使用 OpenCreator 创建”后:--1. 创建一个 `schedule_draft` 会话。-2. 自动进入该会话。-3. 用户用自然语言描述任务。-4. Agent 判断信息是否完整。-5. 信息不足时,Agent 只追问缺少的信息。-6. 信息完整时,Agent 调用 OpenCreator Schedule Tool 创建任务。-7. 创建成功后,当前草稿会话转换为 `schedule_task` 会话。-8. 当前页面不跳走,直接显示创建结果和任务状态栏。-9. 任务出现在左侧“任务”和“已安排”页面。--这条流程必须删除当前基于标题和正则表达式的特殊提交逻辑。--## 8. 完整用户流程--### 8.1 AI 创建任务--示例:--```text-用户:每天晚上 6 点总结今天项目里的工作,控制在 300 字以内。-Agent:调用 schedule_create-OpenCreator:创建 Schedule + 绑定当前 draft Thread-Agent:已创建“每日工作总结”,下次将在今天 18:00 执行。-```--如果缺少时间:--```text-用户:每天帮我生成一篇 100 字文稿。-Agent:你希望每天几点生成?-```--如果缺少项目:--```text-Agent:这项任务要在哪个项目中执行?-```--Agent 不应让用户填写 cron。--### 8.2 手动创建任务--```text-用户打开已安排- -> 创建- -> 手动设置- -> 填写内容和时间- -> 提交- -> 后端原子创建 Schedule 和 Thread- -> 前端进入 Thread-```--### 8.3 到时自动执行--```text-Scheduler 发现到期- -> 查询 Schedule.thread_id- -> 检查 Thread 是否有活动 Run- -> 根据 queue 或 skip 决定- -> RunManager.startRun({ threadId, createdBy: "schedule", sourceId })- -> 首次执行创建 Codex thread- -> 后续执行 resume 同一 Codex thread- -> 事件进入同一 OpenCreator Thread- -> 结果完成- -> 更新 Schedule.last_*- -> 发送通知-```--### 8.4 喝水提醒--任务 Prompt:--```text-提醒我喝水-```--到时后 Agent 在任务会话中产生简短结果:--```text-该喝水了。-```--该文本同时作为通知正文。它不是特殊提醒代码路径,只是普通 Agent 任务的简短结果。--### 8.5 每日生成文稿--任务 Prompt:--```text-生成一篇 100 字左右的产品文稿,保存到 docs/daily 下,并告诉我文件路径。-```--到时后:--1. Agent 读取同一个项目。-2. 使用相同 Skills、MCP、文件和 Shell 能力。-3. 生成文件。-4. 在任务会话中返回文件链接。-5. 用户点击链接直接预览。--### 8.6 用户进入正在运行的任务--1. 左侧任务显示旋转状态。-2. 用户点击后立即显示该任务的加载状态。-3. 历史加载完成后显示当前 Run 的流式事件。-4. 用户可以等待、打断并继续或发送排队消息。-5. 切换走再回来时,必须恢复当前 Run 和实时事件订阅。--### 8.7 修改任务--页面修改:--```text-任务会话头部 -> 编辑 -> 保存-```--对话修改:--```text-用户:以后改成晚上 8 点执行,控制在 200 字以内。-Agent:调用 schedule_update-OpenCreator:原子更新 Schedule 和 Thread 配置-Agent:已更新,下次将在今天 20:00 执行。-```--如果任务正在运行,涉及项目、Profile、模型、权限的配置更新返回 `SCHEDULE_HAS_ACTIVE_RUN`。只修改时间、名称或 Prompt 可以在当前 Run 完成后生效。--### 8.8 暂停和恢复--暂停:--1. `enabled=false`-2. `next_run_at=null`-3. 专属 Thread 保留-4. 左侧任务继续显示“已暂停”-5. 用户仍可进入会话和手动发送消息--恢复:--1. 重新计算 `next_run_at`-2. 不补执行暂停期间错过的任务-3. 继续使用原 Thread--### 8.9 立即执行--1. 点击后立即进入或保持在任务会话。-2. 创建 Schedule Run,并携带固定 `threadId`。-3. 如果当前 Thread 正在运行:- - `queue`:合并为一个待执行触发。- - `skip`:明确提示本次已跳过。-4. 前端不能只显示无限转圈,必须展示“正在运行”“已排队”或“已跳过”。--### 8.10 删除任务--删除采用软删除:--1. Schedule 设置 `deleted_at`。-2. Schedule 禁用并清空 `next_run_at`。-3. 绑定 Thread 归档。-4. 历史 Run 和诊断数据保留。-5. 左侧“任务”和“已安排”不再显示。--如果存在活动 Run,删除返回 `SCHEDULE_HAS_ACTIVE_RUN`。用户需要先取消或等待完成。--## 9. 目标架构--```text-┌────────────────────────────────────────────────────────────┐-│ OpenCreator Web │-│ 已安排管理 | 左侧任务 | 任务会话 | 通知跳转 | 审批 │-└───────────────────────────┬────────────────────────────────┘- │ HTTP + SSE- ▼-┌────────────────────────────────────────────────────────────┐-│ OpenCreator Runtime Daemon │-│ │-│ ScheduleCoordinator │-│ ├─ ScheduleRepository │-│ ├─ ThreadManager │-│ ├─ ScheduleThreadRepair │-│ └─ SQLite transaction │-│ │-│ SchedulerService │-│ ├─ cron / next_run_at │-│ ├─ queue / skip │-│ └─ RunManager.startRun(threadId) │-│ │-│ Agent Schedule Tools │-│ ├─ create │-│ ├─ update │-│ ├─ pause / resume │-│ └─ run_now │-└───────────────────────────┬────────────────────────────────┘- │ spawn / resume- ▼-┌────────────────────────────────────────────────────────────┐-│ Codex CLI │-│ Agent loop | Skills | MCP | Shell | Files | Web | Tools │-└────────────────────────────────────────────────────────────┘-```--## 10. 数据模型--### 10.1 `schedules` 新字段--```sql-ALTER TABLE schedules ADD COLUMN thread_id TEXT;--CREATE UNIQUE INDEX IF NOT EXISTS idx_schedules_thread_id- ON schedules(thread_id)- WHERE thread_id IS NOT NULL AND deleted_at IS NULL;-```--运行期约束:--1. 新 Schedule 创建完成后 `thread_id` 不允许为空。-2. 更新 Schedule 不允许替换 `thread_id`。-3. 删除只归档绑定 Thread,不清空 `thread_id`。-4. 旧数据迁移期间允许短暂为空。--### 10.2 `threads` 新字段--```sql-ALTER TABLE threads- ADD COLUMN purpose TEXT NOT NULL DEFAULT 'conversation';-```--允许值:--```ts-type ThreadPurpose =- | 'conversation'- | 'schedule_draft'- | 'schedule_task';-```--含义:--| purpose | 含义 |-|---|---|-| `conversation` | 普通用户会话 |-| `schedule_draft` | 使用 OpenCreator 创建任务的草稿会话 |-| `schedule_task` | 已绑定 Schedule 的任务会话 |--### 10.3 现有表的复用--`runs` 不增加新的关系字段,继续使用:--- `thread_id`-- `codex_thread_id`-- `created_by`-- `source_id`--Schedule Run 必须满足:--```text-created_by = "schedule"-source_id = schedules.id-thread_id = schedules.thread_id-```--`schedule_operations` 继续记录:--- 创建-- 更新-- 删除-- 立即执行-- 定时触发-- 跳过-- 排队-- 执行失败--P2 增加审计字段:--```sql-ALTER TABLE schedule_operations ADD COLUMN actor_type TEXT;-ALTER TABLE schedule_operations ADD COLUMN actor_run_id TEXT;-```--`actor_type` 允许:--- `user`-- `agent`-- `timer`-- `migration`--### 10.4 Protocol 类型--```ts-export type ThreadPurpose =- | 'conversation'- | 'schedule_draft'- | 'schedule_task';--export type ThreadResponse = {- // 现有字段- purpose: ThreadPurpose;- scheduleId?: string;-};--export type ScheduleResponse = {- // 现有字段- threadId: string;-};-```--`CreateScheduleRequest` 不允许普通客户端指定任意 `threadId`。绑定已有草稿 Thread 只通过受保护的 Agent Tool 内部接口完成。--## 11. 服务职责--### 11.1 `ScheduleCoordinator`--新增协调层,负责跨 Schedule 和 Thread 的原子操作。--建议文件:--```text-apps/daemon/src/scheduler/coordinator.ts-```--接口:--```ts-type ScheduleCoordinator = {- createManual(input: CreateScheduleRequest): ScheduleResponse;- createFromAgent(input: AgentCreateScheduleInput): ScheduleResponse;- update(id: string, input: UpdateScheduleRequest): ScheduleResponse;- delete(id: string): void;- ensureBindings(): ScheduleBindingRepairResult;-};-```--职责:--1. 创建 Schedule 时创建或绑定 Thread。-2. 在一个 SQLite transaction 内写入两张表。-3. 更新 Schedule 配置时同步 Thread 配置。-4. 删除 Schedule 时归档 Thread。-5. 启动时修复缺少 Thread 的旧数据。-6. 验证 Thread purpose 和 Schedule 关系。--### 11.2 `SchedulerService`--SchedulerService 只负责:--1. 计算下一次执行时间。-2. 检查到期任务。-3. 根据并发策略决定 queue 或 skip。-4. 创建 Schedule Run。-5. 更新最后运行状态。--不再负责 Schedule 和 Thread 的创建事务。--触发调用必须变为:--```ts-runManager.startRun({- threadId: schedule.threadId,- prompt: schedule.prompt,- executionPrompt: createScheduleExecutionPrompt(schedule, ranAt),- createdBy: 'schedule',- sourceId: schedule.id,- timeoutMs: schedule.timeoutMs ?? undefined-});-```--当传入 `threadId` 后,不再重复传入 `cwd/profile/model/reasoning/sandbox`,由 RunManager 从 Thread 固定配置读取。--### 11.3 `ThreadManager`--需要增加内部能力:--```ts-createThread({- purpose,- title,- cwd,- workspaceMode: 'external',- profile,- model,- reasoning,- sandbox-});--updateScheduleThread(threadId, {- title,- cwd,- canonicalCwd,- profile,- model,- reasoning,- sandbox-});--setPurpose(threadId, 'schedule_task');-```--普通 `PATCH /threads/:id` 不允许绕过 ScheduleCoordinator 修改 `schedule_task` 的执行配置。--### 11.4 `RunManager`--继续承担:--1. 同一 Thread 串行队列。-2. Codex thread 创建和恢复。-3. SSE 事件。-4. 取消、打断和继续。-5. 审批。-6. 失败恢复。--Schedule Run 不增加第二套执行逻辑。--## 12. Agent 创建和管理任务--### 12.1 设计原则--当前 `schedule-natural-language.ts` 是本地正则解析器,只能识别“提醒我”类语句。目标实现必须让 Agent 理解任务并调用结构化工具。--Agent 不直接写 SQLite,不直接调用公开 Bearer Token,也不执行拼接 SQL。--### 12.2 内置 Schedule MCP Tool--新增 OpenCreator 内置 MCP 工具服务,只在 OpenCreator 启动的 Codex Run 中注入,不修改用户全局 Codex 配置。--建议目录:--```text-apps/daemon/src/agent-tools/- capability-token.ts- internal-routes.ts- schedule-tools.ts- stdio-server.ts-```--工具:--```text-opencreator_schedule_create-opencreator_schedule_update-opencreator_schedule_pause-opencreator_schedule_resume-opencreator_schedule_run_now-opencreator_schedule_get-```--删除任务不在第一批 Agent Tool 中开放,先通过 UI 明确确认。--### 12.3 工具注入方式--1. Daemon 为每个用户发起的 Run 创建短期能力令牌。-2. 令牌只允许访问 Schedule Tool 内部接口。-3. 令牌绑定 `runId` 和 `threadId`,Run 终止后失效。-4. Codex 子进程通过临时 MCP 配置启动 `stdio-server.ts`。-5. MCP 子进程使用短期令牌访问 Daemon 的内部 Schedule Tool 路由。-6. 令牌不得写入 Prompt、事件、诊断导出或普通日志。-7. `createdBy='schedule'` 的自动执行 Run 不注入任务修改工具,避免任务自行修改或重复创建 Schedule。-8. 用户在任务会话中主动发送的普通 Run 可以使用更新、暂停、恢复和立即执行工具。--### 12.4 创建工具输入--```ts-type AgentCreateScheduleInput = {- name: string;- task: string;- timing:- | {- type: 'interval';- everyMinutes: number;- startTime?: string;- endTime?: string;- }- | {- type: 'daily';- time: string;- weekdaysOnly?: boolean;- }- | {- type: 'weekly';- weekdays: number[];- time: string;- }- | {- type: 'cron';- expression: string;- };- timezone?: string;- enabled?: boolean;- concurrencyPolicy?: 'queue' | 'skip';-};-```--规则:--1. Tool 不接受任意 `threadId`。-2. 如果当前 Thread 是 `schedule_draft`,绑定当前 Thread。-3. 如果当前 Thread 是普通会话,创建新的 `schedule_task` Thread。-4. `schedule_draft` 使用 OpenCreator 管理的独立工作区,默认 Profile 为 `default`、- Sandbox 为 `danger-full-access`,不继承创建前选中的项目。-5. Agent 创建工具不接受任意 `cwd`;需要绑定代码仓库或业务目录的任务,应从对应项目- 的普通会话发起,或使用“手动设置”。普通会话发起时,项目、Profile、模型和权限继承- 当前 Thread。-6. 服务端转换 timing 为 cron 并执行最终校验。-7. Tool 返回 `scheduleId`、`threadId`、名称和下次执行时间。--### 12.5 更新工具输入--```ts-type AgentUpdateScheduleInput = {- scheduleId?: string;- name?: string;- task?: string;- timing?: AgentCreateScheduleInput['timing'];- timezone?: string;- enabled?: boolean;-};-```--在 `schedule_task` Thread 中,`scheduleId` 可以省略,由 Thread 绑定关系确定。--普通会话中如未指定任务且存在多个候选,Tool 返回候选列表,Agent 必须询问用户,不能猜测。--## 13. 执行 Prompt 设计--### 13.1 原则--1. 不根据“喝水”“总结”“文稿”等关键词进入不同执行器。-2. Schedule Prompt 始终是普通 Agent 任务。-3. 执行包装只负责说明当前是一次已经到时的执行。-4. 包装内容不能在用户时间线中原样显示。--### 13.2 建议执行包装--```text-这是 OpenCreator 已经触发的一次计划任务执行。--执行规则:-1. 立即完成本次任务,不要重新创建或修改计划任务。-2. 不要询问执行时间,也不要只解释如何完成。-3. 可以使用当前会话可用的文件、Shell、Skills 和 MCP。-4. 如果需要用户审批,正常发起审批并等待。-5. 完成后直接给出本次结果;如果生成了文件,给出可点击的文件路径。--任务名称:{schedule.name}-本次触发时间:{ranAt}-任务内容:-{schedule.prompt}-```--### 13.3 时间线展示--用户时间线展示:--```text-定时执行 · 2026-07-14 18:00-每日总结项目进展,控制在 300 字以内-```--不得把内部执行规则显示成用户消息。--实现方式:--1. Run 保存原始 `prompt` 作为公开输入。-2. `executionPrompt` 只进入 Codex。-3. 历史解析器识别 Schedule Run,根据 Run 元数据替换内部包装的展示文本。-4. Run 详情仍可在诊断信息中显示脱敏后的执行模式,但不展示完整内部 Prompt。--## 14. 并发、排队和中断--### 14.1 活动状态判断--并发判断必须基于 Thread,而不是只检查相同 `source_id` 的 Schedule Run。--原因:--1. 用户可能正在任务会话中主动发送消息。-2. 定时触发不能与用户 Run 同时写入同一会话。-3. 立即执行和自动执行也不能并行。--使用:--```ts-runManager.hasActiveRunForThread(schedule.threadId)-```--### 14.2 `queue`--1. 当前 Thread 有活动或排队 Run 时,设置 `pending_trigger=1`。-2. 多次触发只保留一个 pending trigger。-3. Thread 空闲后创建一次新 Run。-4. 创建 Run 后清空 pending trigger。-5. 页面显示“等待运行”。--### 14.3 `skip`--1. 当前 Thread 有活动或排队 Run 时不创建 Run。-2. 写入 `skip_concurrency` 操作记录。-3. 页面显示“上次已跳过”。--### 14.4 用户打断--任务会话复用现有 `interrupt_and_enqueue`:--1. 用户点击停止或发送“打断并继续”。-2. 当前 Run 取消。-3. 用户新消息作为同一 Thread 的下一个 Run。-4. Schedule 的 pending trigger 继续保留,用户 Run 完成后再执行。--## 15. 审批和无人值守边界--任务页通过“使用 OpenCreator 创建”生成的任务以无人值守执行为默认目标,使用-`danger-full-access`,不进入审批流程。其他入口创建的任务继续遵循其绑定 Thread 的-Sandbox 和审批策略。--规则:--1. `danger-full-access` 映射为 Codex app-server- `approvalPolicy='never'`,并在 `thread/start`、`thread/resume` 和 `turn/start`- 三处保持一致。-2. 完全访问模式不创建 OpenCreator Approval 记录、不展示审批卡,也不进入- `waiting_approval`。-3. 如果 app-server 在 `never` 模式下仍发送 command、file、permissions 或- MCP tool elicitation 审批请求,runner 直接返回批准结果,避免无人值守 Run- 因等待用户操作触发 inactivity timeout。-4. `read-only` 和 `workspace-write` 继续使用 `approvalPolicy='on-request'`,保留- 现有审批卡、通知、批准、拒绝、过期和 queue/skip 处理。-5. 普通 MCP form elicitation 不属于工具审批;当前版本返回 `cancel`,不伪造表单输入。--## 16. 通知设计--### 16.1 通知内容--成功:--```text-标题:每日工作总结-正文:已完成今天的工作总结,共 286 字。-```--提醒:--```text-标题:喝水提醒-正文:该喝水了。-```--失败:--```text-标题:每日工作总结执行失败-正文:项目目录不存在,点击查看详情。-```--等待审批:--```text-标题:每日工作总结等待审批-正文:需要允许执行文件写入操作。-```--### 16.2 通知目标--```ts-type HostNotification = {- title: string;- body: string;- threadId: string;- runId: string;-};-```--不再为 Schedule 通知使用:--```ts-target: 'schedules'-```--点击流程:--```text-打开 #/thread/{threadId}- -> 立即显示加载状态- -> 加载 Thread 历史- -> 恢复 Run- -> 定位 runId 对应的最新执行-```--### 16.3 结果摘要--通知正文优先使用:--1. 最后一条 `assistant_message` 的前 120 个字符。-2. 如果没有最终消息,使用任务状态摘要。-3. 不使用内部执行 Prompt。-4. 不在通知中展示敏感诊断信息。--### 16.4 浏览器限制--P0 和 P1 中,浏览器通知依赖页面仍在运行。--P2 增加 Host 后台通知:--1. Daemon 产生通知事件。-2. Desktop Host 或系统适配器订阅。-3. 页面关闭时仍能显示。-4. 点击后启动或聚焦 OpenCreator 并打开任务会话。--## 17. 会话列表、搜索和历史--### 17.1 普通会话与任务会话分组--前端按 `ThreadResponse.purpose` 分组:--- `conversation`:项目普通会话区域。-- 未完成的 `schedule_draft` 和正式 `schedule_task`:左侧“任务”区域。-- “使用 OpenCreator 创建”生成的 `schedule_draft` 使用 `workspaceMode='managed'`,不携带- 当前项目 `cwd`,默认 Profile 为 `default`、Sandbox 为 `danger-full-access`。-- 新建 managed Thread 必须持久化绝对工作区路径;兼容历史相对 `cwd` 时,Run 执行必须- 使用 Thread 的绝对 `canonicalCwd`,避免 Codex app-server 二次相对解析导致 MCP- 启动目录不存在。-- 任务草稿和正式任务的 Composer 不显示普通项目选择器;需要项目目录时,从对应项目- 普通会话发起任务创建,或使用“手动设置”。项目只是任务执行配置,不是任务侧栏归属。--### 17.2 Codex session 索引--旧逻辑会把所有 Schedule 创建的 Codex session 标记为 `kind='schedule'` 并隐藏。新逻辑必须改为:--1. 只有 `runs.created_by='schedule' AND runs.thread_id IS NULL` 的旧孤立 session 标记为 legacy schedule。-2. 有 OpenCreator `thread_id` 的 Schedule session 保持可索引和可搜索。-3. 不再归档绑定 Schedule 的 OpenCreator Thread。-4. 搜索结果可以返回任务会话,并标注“任务”。--### 17.3 历史加载--任务会话使用现有懒加载规则:--1. 刷新页面只加载可见会话列表。-2. 不预加载所有任务历史。-3. 点击任务后才加载对应历史。-4. 切换任务时立即清空旧时间线并显示加载状态。-5. 正在运行时恢复 SSE,不依赖历史加载完成后才订阅。--## 18. 启动修复和旧数据迁移--### 18.1 Schema 迁移--在 `migrate()` 中使用现有 `ensureColumn()` 风格:--1. 增加 `schedules.thread_id`。-2. 增加 `threads.purpose`。-3. 创建唯一部分索引。-4. 将旧 `parallel` 转换为 `queue`。--### 18.2 数据回填--Schema 迁移完成后、Scheduler 启动前执行:--```ts-scheduleCoordinator.ensureBindings();-```--对每条 `deleted_at IS NULL AND thread_id IS NULL` 的 Schedule:--1. 根据 Schedule 配置创建 `workspaceMode='external'` 的 Thread。-2. Thread title 使用 Schedule name。-3. Thread purpose 设置为 `schedule_task`。-4. Schedule 写入 Thread ID。-5. 写入 `schedule_operations.operation='binding_repair'`。-6. 每条 Schedule 单独 transaction,单条失败不阻塞其他 Schedule。-7. 修复失败的 Schedule 自动禁用,并记录错误。--需要扩展操作类型:--```ts-type ScheduleOperationType =- | ...现有类型- | 'binding_repair'- | 'binding_repair_failed';-```--### 18.3 旧 Run--旧版 Run 没有 `thread_id`,不尝试伪造到新会话中,因为底层 Codex session 不同,强行合并会产生错误上下文。--处理方式:--1. 旧 Run 和诊断继续保留。-2. 新专属会话从迁移后的第一次执行开始形成连续历史。-3. “已安排”的高级运行记录中可以查看旧 Run。-4. 旧 Codex session 继续隐藏,避免重复会话。--### 18.4 启动顺序--```text-打开数据库- -> migrate schema- -> 构建 ThreadManager- -> 构建 ScheduleCoordinator- -> ensureBindings- -> 修复 Codex session 分类- -> 构建 SchedulerService- -> 注册 API- -> Scheduler.start()-```--Scheduler 不得在绑定修复之前启动。--## 19. API 设计--### 19.1 创建 Schedule--```http-POST /schedules-```--响应增加:--```json-{- "id": "sch_xxx",- "threadId": "thread_xxx",- "name": "每日工作总结"-}-```--服务端必须完成 Schedule + Thread 创建后才返回 `201`。--### 19.2 获取和列表--```http-GET /schedules-GET /schedules/:id-```--每条记录必须包含 `threadId`。--### 19.3 更新--```http-PATCH /schedules/:id-```--更新 Schedule 和 Thread 配置必须处于同一 transaction。--可能错误:--| HTTP | code | 场景 |-|---|---|---|-| 404 | `SCHEDULE_NOT_FOUND` | Schedule 不存在 |-| 409 | `SCHEDULE_HAS_ACTIVE_RUN` | 活动 Run 阻止配置变更 |-| 409 | `SCHEDULE_THREAD_MISSING` | 绑定损坏且自动修复失败 |-| 409 | `SCHEDULE_THREAD_ARCHIVED` | Thread 被异常归档 |-| 422 | `SCHEDULE_INVALID` | 时间或配置无效 |--### 19.4 立即执行--```http-POST /schedules/:id/run-now-```--成功创建 Run:--```json-{- "run": {- "id": "run_xxx",- "threadId": "thread_xxx",- "status": "running"- },- "schedule": {- "id": "sch_xxx",- "threadId": "thread_xxx"- },- "skipped": false,- "queued": false-}-```--### 19.5 Thread API--`POST /threads` 增加内部可用字段:--```ts-purpose?: 'conversation' | 'schedule_draft';-```--普通调用默认 `conversation`。--`ThreadResponse` 增加:--```ts-purpose: ThreadPurpose;-scheduleId?: string;-```--## 20. 错误处理--### 20.1 绑定损坏--发现 Schedule 有 `thread_id`,但 Thread 不存在:--1. 不直接创建 Run。-2. 尝试一次自动修复。-3. 修复成功后继续。-4. 修复失败则禁用 Schedule。-5. 写入错误操作记录。-6. 页面显示“任务会话需要修复”。--### 20.2 项目目录不存在--1. 本次 Run 失败。-2. Schedule 保持启用。-3. 通知用户。-4. 页面提供“编辑项目”操作。-5. 连续三次相同错误后显示建议暂停,但不自动删除。--### 20.3 Codex resume 失败--1. RunManager 按现有恢复策略尝试。-2. 如果 Codex thread 无法恢复,使用 OpenCreator 对话摘要重新建立 Codex thread。-3. 更新 `threads.codex_thread_id`。-4. OpenCreator `thread_id` 不变。-5. 在会话中显示一次非阻断诊断:“执行上下文已重新连接”。--### 20.4 Daemon 重启--1. 运行中的 Run 按现有 orphan 规则收敛为失败。-2. Schedule 绑定不变。-3. pending trigger 保留。-4. 重启后根据 misfire 规则处理错过时间。-5. 不创建新的任务 Thread。--## 21. 安全边界--1. Schedule Run 继承 Thread 的 Sandbox,不提升权限。-2. Schedule Tool 使用短期、按 Run 绑定的能力令牌。-3. 自动执行 Run 不拥有修改 Schedule 的工具。-4. Schedule Tool 输入全部经过 Daemon 校验。-5. Tool 不能传入任意 `threadId`。-6. Tool 不能访问其他 Daemon 实例。-7. 通知正文必须经过脱敏。-8. Prompt 和结果中的密钥不得进入通知。-9. 删除仍需 UI 确认。-10. 任务审批不能自动通过。--## 22. 可观测性--每次触发至少记录:--- `schedule_id`-- `thread_id`-- `run_id`-- `trigger_type`-- `scheduled_at`-- `started_at`-- `ended_at`-- `status`-- `queue_reason`-- `error_code`--建议诊断事件:--```text-SCHEDULE_TRIGGERED-SCHEDULE_TRIGGER_QUEUED-SCHEDULE_TRIGGER_SKIPPED-SCHEDULE_THREAD_REPAIRED-SCHEDULE_THREAD_REPAIR_FAILED-SCHEDULE_RUN_STARTED-SCHEDULE_RUN_COMPLETED-SCHEDULE_RUN_WAITING_APPROVAL-```--不得把完整 Prompt、能力令牌或未脱敏结果写入普通日志。--## 23. 测试策略--### 23.1 单元测试--Daemon:--- ScheduleRepository 保存和读取 `thread_id`-- ThreadRepository 保存 `purpose`-- ScheduleCoordinator 原子创建-- ScheduleCoordinator 更新同步-- ScheduleCoordinator 删除归档-- ensureBindings 回填-- Scheduler 传入固定 `threadId`-- queue 和 skip 基于 Thread 活动状态-- legacy session 分类-- Schedule Tool 输入校验和权限--Web:--- 左侧任务分组-- 运行状态旋转-- 点击任务立即显示加载状态-- “已安排”打开任务会话-- 通知跳到 thread + run-- AI 创建草稿会话-- 创建成功后 draft 转 task-- 页面不显示 cron--### 23.2 集成测试--1. 手动创建 Schedule 后同时存在 Thread。-2. 连续两次 `run-now` 使用同一 `threadId`。-3. 第二次 Run 使用同一 Codex thread 或正确恢复。-4. 正在执行时触发 queue,只补执行一次。-5. Schedule 更新同步 Thread。-6. 删除 Schedule 后 Thread 归档。-7. 服务重启后不重复创建 Thread。-8. Agent Tool 创建任务并绑定 draft Thread。-9. Schedule Run 无权调用 Schedule mutation tools。-10. 通知包含正确 `threadId` 和 `runId`。--### 23.3 浏览器端到端测试--使用 Playwright 验证:--1. 创建一个每分钟任务。-2. 左侧“任务”立即出现。-3. 点击立即执行。-4. 任务行显示正在运行。-5. 切换到普通会话,再切回任务。-6. 不显示上一个会话内容。-7. 任务完成后结果出现在同一会话。-8. 再次立即执行,结果追加到同一会话。-9. 点击通知模拟事件,进入正确任务。-10. 桌面和移动视口都能滚动、审批和查看结果。--### 23.4 必跑命令--```bash-pnpm --filter @opencreator/protocol typecheck-pnpm --filter @opencreator/daemon test-pnpm --filter @opencreator/daemon typecheck-pnpm --filter @opencreator/web test-pnpm --filter @opencreator/web typecheck-pnpm build-```--## 24. 分阶段实施计划--所有批次必须:--1. 先补测试,再修改实现。-2. 每批完成后运行该批相关测试和 typecheck。-3. 每批单独提交一次 Git。-4. 不等待中间人工验收,按顺序继续。-5. P0、P1、P2 全部完成后统一验收。--## 25. P0:专属会话执行闭环--P0 目标:从手动创建到定时执行,Schedule 必须稳定复用专属 Thread。--### P0-1:Schema 和 Protocol--**修改内容**--- 为 `schedules` 增加 `thread_id`-- 为 `threads` 增加 `purpose`-- 增加唯一索引-- 扩展 Protocol 类型--**可能修改文件**--- `apps/daemon/src/storage/migrations.ts`-- `packages/protocol/src/api.ts`-- `apps/daemon/src/threads/types.ts`-- `apps/daemon/src/scheduler/types.ts`-- 对应测试文件--**验收**--- [ ] 旧数据库可以无损升级-- [ ] 新数据库字段存在-- [ ] `ScheduleResponse.threadId` 为必填-- [ ] `ThreadResponse.purpose` 为必填-- [ ] 旧 `parallel` 已转换为 `queue`--**验证**--```bash-pnpm --filter @opencreator/protocol typecheck-pnpm --filter @opencreator/daemon test -- scheduler-repository thread-manager-```--### P0-2:Thread purpose 和任务 Thread 查询--**修改内容**--- ThreadManager 支持创建 `schedule_draft` 和 `schedule_task`-- Thread 查询返回 `scheduleId`-- 普通线程配置接口拒绝直接修改 Schedule Thread--**可能修改文件**--- `apps/daemon/src/threads/manager.ts`-- `apps/daemon/src/threads/types.ts`-- `apps/daemon/src/storage/repositories.ts`-- `apps/daemon/src/api/routes.threads.ts`-- `apps/daemon/test/unit/thread-manager.test.ts`--**验收**--- [ ] 默认 Thread purpose 为 `conversation`-- [ ] Schedule Thread 可以被单独识别-- [ ] `scheduleId` 通过绑定关系返回-- [ ] Schedule Thread 不会被普通配置更新破坏--### P0-3:ScheduleCoordinator 创建事务--**修改内容**--- 新增 ScheduleCoordinator-- 手动创建时同时创建外部项目 Thread-- Schedule 和 Thread 在一个 transaction 内提交--**可能修改文件**--- `apps/daemon/src/scheduler/coordinator.ts`-- `apps/daemon/src/scheduler/repository.ts`-- `apps/daemon/src/threads/manager.ts`-- `apps/daemon/src/api/server.ts`-- `apps/daemon/test/unit/scheduler-coordinator.test.ts`--**验收**--- [ ] 创建 Schedule 返回 `threadId`-- [ ] Thread title 与 Schedule name 一致-- [ ] Thread 执行配置与 Schedule 一致-- [ ] 任一写入失败时数据库不留下半成品--### P0-4:Schedule 更新和删除事务--**修改内容**--- Schedule 配置更新同步 Thread-- 删除 Schedule 归档 Thread-- 活动 Run 阻止危险配置变更和删除--**可能修改文件**--- `apps/daemon/src/scheduler/coordinator.ts`-- `apps/daemon/src/scheduler/service.ts`-- `apps/daemon/src/storage/repositories.ts`-- `apps/daemon/src/api/routes.schedules.ts`-- `apps/daemon/test/unit/scheduler-coordinator.test.ts`--**验收**--- [ ] 修改名称同步 Thread title-- [ ] 修改项目和权限同步 Thread-- [ ] 删除后 Thread 归档-- [ ] 活动 Run 时返回明确 409--### P0-5:Scheduler 使用固定 Thread--**修改内容**--- `startRun()` 传入 `schedule.threadId`-- 不再重复传执行配置-- 并发判断改为 Thread 级别-- 新任务只允许 queue 或 skip--**可能修改文件**--- `apps/daemon/src/scheduler/service.ts`-- `apps/daemon/src/scheduler/validator.ts`-- `apps/daemon/src/runs/manager.ts`-- `apps/daemon/test/unit/scheduler-service.test.ts`-- `apps/daemon/test/unit/scheduler-validator.test.ts`--**验收**--- [ ] 同一 Schedule 连续 Run 的 `threadId` 相同-- [ ] 第一次运行创建 Codex thread-- [ ] 后续运行恢复 Codex thread-- [ ] 用户 Run 活动时 Schedule 不并行执行-- [ ] queue 重复触发只合并一次--### P0-6:旧 Schedule 绑定修复--**修改内容**--- 增加 `ensureBindings()`-- 启动时回填旧 Schedule-- 失败任务自动禁用并记录--**可能修改文件**--- `apps/daemon/src/scheduler/coordinator.ts`-- `apps/daemon/src/api/server.ts`-- `apps/daemon/src/scheduler/repository.ts`-- `apps/daemon/src/scheduler/types.ts`-- `apps/daemon/test/unit/scheduler-binding-repair.test.ts`--**验收**--- [ ] 每条旧 Schedule 只创建一个 Thread-- [ ] 重复启动不重复创建-- [ ] 单条失败不阻塞其他修复-- [ ] Scheduler 在修复后启动--### P0-7:修正旧 Schedule session 隐藏逻辑--**修改内容**--- 只隐藏没有 OpenCreator Thread 的旧孤立 Schedule session-- 不再归档新任务 Thread-- 新任务会话可以搜索--**可能修改文件**--- `apps/daemon/src/codex/sessions/index-repository.ts`-- `apps/daemon/src/storage/repositories.ts`-- `apps/daemon/src/api/server.ts`-- 对应索引和服务器测试--**验收**--- [ ] 新 Schedule Thread 保持 active-- [ ] 旧孤立 session 不进入普通列表-- [ ] 新任务历史可以正常加载和搜索--### P0 检查点--- [ ] 所有 Daemon 单元和集成测试通过-- [ ] 手动创建任务返回专属 Thread-- [ ] 连续立即执行两次进入同一会话-- [ ] 重启后绑定不变-- [ ] 数据库无重复绑定--## 26. P1:完整用户交互--P1 目标:用户可以从“已安排”、左侧“任务”和自然语言完整使用专属任务会话。--### P1-1:前端数据模型和服务--**修改内容**--- 接入 `ScheduleResponse.threadId`-- 接入 `ThreadResponse.purpose`-- 增加任务 Thread 选择器--**可能修改文件**--- `apps/web/src/services/schedule-service.ts`-- `apps/web/src/services/thread-service.ts`-- `apps/web/src/features/projects/project-model.ts`-- `apps/web/src/app/AppController.tsx`-- 对应测试--**验收**--- [ ] 普通会话和任务会话可以稳定分组-- [ ] 缺少 Thread 的异常状态有明确提示--### P1-2:左侧“任务”区域--**修改内容**--- 在侧栏底部增加任务区域-- 显示运行、排队、审批、失败、暂停和未读状态-- 点击时立即进入加载态--**可能修改文件**--- `apps/web/src/features/shell/OpenCreatorSidebar.tsx`-- `apps/web/src/features/shell/opencreator-sidebar.css`-- `apps/web/src/app/AppController.tsx`-- 对应组件测试--**验收**--- [ ] Schedule Thread 不出现在项目普通会话中-- [ ] 正在运行显示旋转图标-- [ ] 点击其他任务不残留上一个会话内容-- [ ] 已暂停任务仍可进入--### P1-3:“已安排”打开任务会话--**修改内容**--- 创建后自动进入 `threadId`-- 任务标题打开专属会话-- 立即执行后进入或保持任务会话-- 诊断信息降为二级入口--**可能修改文件**--- `apps/web/src/features/schedules/SchedulesView.tsx`-- `apps/web/src/features/schedules/ScheduleEditor.tsx`-- `apps/web/src/app/AppController.tsx`-- `apps/web/src/features/schedules/SchedulesView.test.tsx`--**验收**--- [ ] 手动创建后进入专属会话-- [ ] “查看上次运行”定位到同一任务会话-- [ ] 立即执行不会无限转圈--### P1-4:任务会话头部--**修改内容**--- 增加紧凑任务状态栏-- 支持立即执行、暂停、恢复和编辑--**可能修改文件**--- `apps/web/src/features/conversation/ConversationPage.tsx`-- `apps/web/src/features/schedules/ScheduleThreadHeader.tsx`-- 对应 CSS-- `apps/web/src/app/AppController.tsx`-- 对应测试--**验收**--- [ ] 不离开会话即可管理任务-- [ ] 状态变化后及时刷新-- [ ] 移动端不遮挡对话和审批--### P1-5:内置 Schedule Tool 能力令牌--**修改内容**--- 实现短期能力令牌-- 实现内部 Agent Tool 路由-- Run 完成后令牌失效--**可能修改文件**--- `apps/daemon/src/agent-tools/capability-token.ts`-- `apps/daemon/src/agent-tools/internal-routes.ts`-- `apps/daemon/src/api/server.ts`-- 对应安全测试--**验收**--- [ ] 无令牌不能调用-- [ ] 令牌不能跨 Run 或 Thread 使用-- [ ] 令牌不进入日志--### P1-6:Schedule MCP 工具--**修改内容**--- 实现 create、update、pause、resume、run-now、get-- 增加 timing 到 cron 的服务端转换-- 自动执行 Run 不注入修改工具--**可能修改文件**--- `apps/daemon/src/agent-tools/schedule-tools.ts`-- `apps/daemon/src/agent-tools/stdio-server.ts`-- `apps/daemon/src/runs/manager.ts`-- `apps/daemon/src/scheduler/coordinator.ts`-- 对应工具测试--**验收**--- [ ] Agent 能创建通用任务,不限提醒-- [ ] Agent 能在任务会话中修改时间和任务内容-- [ ] 自动执行不能修改自身 Schedule-- [ ] 不修改全局 Codex 配置--### P1-7:替换正则创建流程--**修改内容**--- “使用 OpenCreator 创建”创建 `schedule_draft`-- 用户消息走普通 Agent Run-- 删除标题匹配和正则拦截-- Tool 成功后转换为 `schedule_task`--**可能修改文件**--- `apps/web/src/app/AppController.tsx`-- `apps/web/src/features/schedules/schedule-natural-language.ts`-- `apps/web/src/features/schedules/schedule-natural-language.test.ts`-- `apps/web/src/features/schedules/SchedulesView.tsx`-- 相关 App 测试--**验收**--- [ ] “每天生成 100 字文稿”可以创建-- [ ] 缺少时间时 Agent 会追问-- [ ] 创建后当前会话成为任务会话-- [ ] 不再依赖“提醒我”关键词--### P1-8:通知深链接和结果摘要--**修改内容**--- Schedule 通知携带 `threadId` 和 `runId`-- 点击进入任务会话-- 通知正文使用最终结果摘要--**可能修改文件**--- `apps/web/src/features/tasks/task-monitor.ts`-- `apps/web/src/host/bridge.ts`-- `apps/web/src/host/browser-bridge.ts`-- `apps/web/src/app/AppController.tsx`-- 对应测试--**验收**--- [ ] 成功通知显示结果摘要-- [ ] 失败和审批通知进入正确会话-- [ ] 不再跳转到“已安排”--### P1-9:时间线公开输入--**修改内容**--- Schedule Run 展示友好的触发消息-- 隐藏内部执行包装-- 文件链接继续可点击预览--**可能修改文件**--- `apps/daemon/src/scheduler/service.ts`-- `apps/daemon/src/codex/sessions/parser.ts`-- `apps/web/src/features/conversation/*`-- 对应历史和时间线测试--**验收**--- [ ] 用户只看到任务内容和触发时间-- [ ] 不显示内部调度指令-- [ ] HTML 等生成文件可以直接打开预览--### P1 检查点--- [ ] AI 和手动两种方式都能创建任务-- [ ] 左侧任务列表、已安排和会话状态一致-- [ ] 通知可以准确打开任务会话-- [ ] 喝水提醒和生成文稿使用同一执行路径-- [ ] 用户可以在任务会话中修改任务--## 27. P2:长期运行和发布质量--P2 目标:让任务适合长期运行、后台通知和故障恢复。--### P2-1:等待审批和失败体验--**修改内容**--- 任务行显示待审批-- 通知定位审批卡片-- 连续失败展示建议操作--**验收**--- [ ] 无人值守任务不会自动批准-- [ ] 审批恢复后继续同一 Run-- [ ] 错误不只显示技术代码--### P2-2:长期上下文轮换--**修改内容**--- 使用已有会话摘要-- Codex resume 失败或上下文过长时重建 Codex thread-- OpenCreator thread 不变--**验收**--- [ ] 长期任务不会因单个 Codex thread 失效而永久中断-- [ ] 用户历史和任务入口不变化-- [ ] 新 Codex thread 获得必要摘要--### P2-3:后台通知适配--**修改内容**--- Daemon 发出持久通知事件-- Desktop Host 或系统适配器展示通知-- 页面关闭后仍可提醒--**验收**--- [ ] 浏览器页面关闭时,受支持 Host 仍能通知-- [ ] 点击后打开正确任务会话--### P2-4:操作审计和诊断--**修改内容**--- 增加 actor 字段-- 增加 Schedule 诊断事件-- 导出时脱敏--**验收**--- [ ] 可以区分用户、Agent、Timer 和 Migration 操作-- [ ] 可以追踪一次 Trigger 到 Run 和 Thread--### P2-5:完整 E2E 和性能检查--**修改内容**--- 增加两次连续执行 E2E-- 增加切换会话和刷新恢复 E2E-- 检查任务数量较多时的列表性能--**验收**--- [x] 100 个任务时侧栏不预加载全部历史-- [x] 页面刷新只加载任务摘要-- [x] 点击后按需加载会话-- [x] 不出现主线程长时间卡死--### P2 检查点--- [x] 完整自动化测试通过-- [ ] 手动验收矩阵通过-- [x] 升级旧数据库通过-- [x] 回滚演练通过-- [x] 文档和 API 文档更新完成--## 28. 手动验收矩阵--| 场景 | 操作 | 预期 |-|---|---|---|-| AI 创建提醒 | “每 30 分钟提醒我喝水” | 创建任务会话,按时产生简短提醒 |-| AI 创建内容任务 | “每天 9 点生成 100 字文稿” | 无需项目时使用独立任务工作区;需要目录时从项目会话发起或手动设置,生成内容进入同一会话 |-| 手动创建 | 表单提交 | 自动进入专属会话 |-| 连续立即执行 | 连点两次 | 第二次排队或跳过,不并行 |-| 自动执行两次 | 等待两个周期 | 两次结果在同一会话 |-| 切换会话 | 运行时切走再回来 | 不丢输入,不显示旧会话内容 |-| 页面刷新 | 任务运行中刷新 | 会话恢复,Run 状态继续显示 |-| 审批 | 定时任务请求写文件 | 通知并进入审批,不自动批准 |-| 暂停 | 点击暂停 | 不再自动触发,会话仍可进入 |-| 修改 | 在会话说“改成 20:00” | Schedule 更新,下次时间变化 |-| 删除 | 删除无活动任务 | Schedule 隐藏,Thread 归档 |-| 旧数据升级 | 使用现有数据库启动 | 每个旧 Schedule 补一个 Thread,不重复 |-| 通知 | 点击完成通知 | 进入正确 Thread 并定位最新 Run |-| 文件结果 | 生成 HTML | 会话中链接可点击并以预览方式打开 |--## 29. 发布和回滚--### 29.1 发布前--1. 备份本地 SQLite。-2. 记录旧 Schedule 数量。-3. 运行 Schema 迁移。-4. 运行绑定修复。-5. 对比 Schedule 数量和新增 Thread 数量。-6. Scheduler 最后启动。--### 29.2 灰度检查--启动后检查:--```sql-SELECT COUNT(*) FROM schedules-WHERE deleted_at IS NULL AND thread_id IS NULL;-```--结果必须为 `0`。--检查重复绑定:--```sql-SELECT thread_id, COUNT(*)-FROM schedules-WHERE deleted_at IS NULL-GROUP BY thread_id-HAVING COUNT(*) > 1;-```--结果必须为空。--### 29.3 回滚--回滚代码时:--1. 不删除新字段。-2. 停止新版 Scheduler。-3. 回滚应用代码。-4. 旧代码可以忽略新增字段。-5. 已创建的任务 Thread 保留。-6. 不反向删除或合并 Codex session。--数据库迁移只增列和增索引,不执行破坏性降级。--## 30. 风险与缓解--| 风险 | 影响 | 缓解 |-|---|---|---|-| 旧隐藏逻辑归档新任务 Thread | 用户看不到任务会话 | P0 优先修正 session 分类和归档条件 |-| 同一 Thread 并行写入 | 历史错乱、恢复失败 | 禁止 parallel,基于 Thread 判断活动状态 |-| Schedule 和 Thread 配置不一致 | 执行项目或权限错误 | 使用 ScheduleCoordinator transaction |-| Agent Tool 泄露 Daemon Token | 本地权限扩大 | 使用短期作用域令牌,不传完整 Token |-| Agent 创建错误时间 | 任务执行时间错误 | 结构化 timing、服务端校验、回复下次执行时间 |-| 页面关闭后无通知 | 用户错过提醒 | P2 后台 Host 通知,P1 明确浏览器限制 |-| Codex thread 过长 | 长期任务失败 | P2 摘要和底层 thread 轮换 |-| 迁移创建重复 Thread | 任务列表重复 | 唯一索引、逐条 transaction、幂等 repair |-| 正则创建逻辑残留 | 通用任务仍无法创建 | P1 删除特殊提交分支和标题判断 |--## 31. 实施边界--### 必须始终做到--1. Schedule 新建和 Thread 绑定必须原子化。-2. 每个实现批次必须有测试。-3. Schedule Run 必须使用固定 `threadId`。-4. 同一任务会话必须串行。-5. 通知必须携带 Thread 和 Run。-6. 所有用户文案使用普通用户可理解的语言。--### 修改前必须更新本文--1. 改成一对多 Schedule 与 Thread 关系。-2. 恢复 `parallel`。-3. 让 Codex 官方调度替代 OpenCreator Scheduler。-4. 允许自动审批。-5. 改变删除和历史保留策略。--### 禁止--1. 重新用标题字符串识别 Schedule Thread。-2. 继续用正则表达式冒充 AI 创建任务。-3. 为提醒、总结、文稿分别建立独立执行器。-4. Schedule Run 不传 `threadId`。-5. 通知只跳到“已安排”。-6. 为了隐藏旧孤立 session 而归档所有 Schedule Thread。--## 32. 最终完成定义--只有同时满足以下条件,整个任务才算完成:--1. AI 创建和手动创建都可用。-2. 每个 Schedule 有且只有一个专属 Thread。-3. 同一 Schedule 多次运行始终进入同一 Thread。-4. 定时任务使用 OpenCreator 普通 Agent 的完整执行能力。-5. 左侧“任务”正确展示长期任务会话。-6. “已安排”与任务会话职责清晰且可以互相跳转。-7. 通知点击进入任务会话。-8. 正在运行、排队、审批、失败、暂停状态一致。-9. 旧数据升级不丢 Schedule,不生成重复 Thread。-10. 页面刷新和会话切换不丢运行状态。-11. P0、P1、P2 的自动化测试和手动验收矩阵全部通过。diff --git a/docs/specs/2026-07-15-opencreator-desktop-app-host-design.md b/docs/specs/2026-07-15-opencreator-desktop-app-host-design.mddeleted file mode 100644index b53caba4..00000000--- a/docs/specs/2026-07-15-opencreator-desktop-app-host-design.md+++ /dev/null@@ -1,1968 +0,0 @@-# OpenCreator 桌面版 App 宿主与 Codex 启动门禁规格--## 0. 文档信息--| 项目 | 内容 |-|---|---|-| 文档状态 | 整改后实施完成,本机发布候选通过,外部环境验收部分阻塞 |-| 版本 | 1.4 |-| 创建日期 | 2026-07-15 |-| 最近整改验收 | 2026-07-16 |-| 适用范围 | OpenCreator Desktop Host、Local Runtime Daemon、Web UI、Protocol、通知、打包与发布 |-| 技术路线 | Electron 薄宿主 + 现有 React Web UI + 独立 OpenCreator Daemon |-| 首要平台 | macOS;架构保持 Windows 可移植 |-| 规格优先级 | 本文档覆盖现有文档中尚未实现的原生 Desktop Host 部分 |--本文是 OpenCreator 桌面版第一阶段的产品、架构和实施规格。P0、P1 和 P2 的仓库内实现已经完成;macOS arm64 离线 fresh package、Fuses、ASAR、packaged E2E、真实 Codex hello 和本地 OSV 验收已通过。签名、公证、真实版本升级、GitHub Actions 发布矩阵和 Windows 实机项目因当前环境缺失保留为 `BLOCKED_ENV` 或 `NOT_RUN`。--如实现过程中需要改变以下原则,必须先更新本文档:--1. OpenCreator 依赖用户本机已经安装并可用的 Codex CLI。-2. OpenCreator 不内置 Codex CLI,不管理 Codex 登录。-3. Codex 是否可用只通过一次真实最小模型调用判断。-4. 只有真实调用成功后,才加载 OpenCreator 主 Dashboard 。-5. 页面刷新、切换项目和从托盘重新打开窗口不能重复执行启动探测。-6. 启动探测不得加载 OpenCreator Skills、Skill Market 或 MCP 页面数据。--## 1. 一句话定义--**OpenCreator Desktop 是本机 Codex CLI 的桌面 Agent Dashboard,由 Electron 托管现有 Web UI 和 OpenCreator Daemon,并在冷启动时通过一次真实 Codex `hello` 调用确认 Codex CLI 基础模型调用可用。**--## 2. 已确认决策--### 2.1 产品决策--1. OpenCreator 不是 Codex 安装器。-2. OpenCreator 不提供 Codex 登录页面。-3. 用户应当在安装 OpenCreator 前,自行完成 Codex CLI 的安装和本机配置。-4. OpenCreator 启动后先显示轻量环境检查界面,不立即加载主 Dashboard 。-5. Codex CLI 能完成一次真实最小请求并返回有效 assistant 消息,才视为可用。-6. 探测失败时只进入诊断界面,不允许跳过后进入主 Dashboard 。-7. 探测失败不推断为“未登录”,也不调用 `codex login status`。-8. 探测成功后,现有项目、会话、任务、插件、Skills、MCP 和设置功能保持不变。--### 2.2 技术决策--1. 桌面宿主采用 Electron。-2. 不重写 `apps/web`,桌面版直接承载现有 React Web UI。-3. 不把 Daemon 逻辑合并进 Renderer 或 Electron Main。-4. OpenCreator Daemon 作为 Electron 管理的独立 Utility Process 运行。-5. Electron Main 负责 Codex 路径解析、Daemon 生命周期、窗口、托盘、通知、深链接和更新。-6. Renderer 不允许直接访问 Node.js、Electron、文件系统或 Shell。-7. Desktop Host 通过现有 `HostBridge` 方向向 Web UI 暴露有限原生能力。-8. Daemon 继续只监听 `127.0.0.1` 的随机端口,并使用每次启动生成的临时 token。-9. Web 开发服务器继续固定使用 `127.0.0.1:9000`;该端口只用于开发环境,不用于生产 Daemon。-10. 生产 Renderer 不直接获得 Daemon token;`opencreator-app://app/.opencreator/runtime/*` 由 Electron Main 代理并注入鉴权。-11. Desktop 使用标准 `CODEX_HOME` 向 Daemon 传递用户 Codex Home;Probe 运行时由 Daemon 创建一次性净化 `CODEX_HOME`,普通任务仍使用用户真实 Codex Home。-12. Daemon 异常重启且 Codex 环境未变化时复用本次 Desktop 生命周期内的 Probe 成功结果,不重复产生模型调用。-13. Probe 的临时 `CODEX_HOME` 解析用户基础 `config.toml` 后只写入 model、选中 provider、认证路由和模型目录等调用必需配置,并复制 `auth.json` 与模型目录文件;Skills、Plugins、MCP、Hooks、项目授权、通知及其他扩展状态不进入 Probe Home。启动 Probe 没有显式 Profile,因此不推断或加载 `<name>.config.toml`。--### 2.3 Codex 可用性决策--以下项目不是独立启动门禁:--1. Codex 登录状态。-2. Codex 版本是否位于预设白名单。-3. `CODEX_HOME` 中是否存在某个特定认证文件。-4. `codex doctor` 的单项诊断结果。-5. MCP 是否可用。-6. Skills 是否可用。-7. Skill Market 是否可访问。--唯一硬门禁是:--```text-OpenCreator Daemon- -> 使用目标 Codex CLI 和目标 CODEX_HOME- -> 发起一次临时、只读、无工具的最小请求- -> 收到至少一条非空 assistant 消息-```--## 3. 当前实现基线--### 3.1 已完成模块--当前仓库已经具备:--1. `apps/desktop`- - Electron Main、sandboxed Preload、Bootstrap 页面和共享 IPC 类型。- - 单实例、窗口、托盘、通知、深链接、诊断导出、数据迁移和更新框架。- - Codex 路径解析、登录 Shell 环境恢复、Windows `where.exe` 与 `.cmd/.bat/.exe` 支持。- - Daemon Utility Process 托管、一次自动恢复、二次崩溃熔断和进程树回收。- - `opencreator-app://` 本地资源协议以及 JSON、二进制和 SSE Runtime 代理。-2. `apps/daemon`- - 冷启动真实 Codex Probe、结构化 Bootstrap 协议和 Runtime 互斥锁。- - 临时净化 Probe Home、低推理等级、无工具、只读和扩展能力禁用。- - 现有 Thread、Run、Scheduler、Skills、MCP、附件、搜索、记忆、通知和诊断能力保持复用。-3. `apps/web`- - Desktop HostBridge、连接更新、同源 Runtime 代理和桌面设置入口。- - Browser 模式继续固定使用 `127.0.0.1:9000`,页面刷新不触发 Probe。-4. 打包与发布- - Electron Builder、独立 Daemon 生产部署、Electron ABI 原生模块重建、阶段超时和包内容校验。- - Electron Fuses 关闭 RunAsNode、NODE_OPTIONS 和 Node CLI Inspector,启用 Cookie 加密、ASAR 完整性和 OnlyLoadAppFromAsar。- - macOS arm64 unsigned/ad-hoc `.app` 已通过全离线 fresh package、构建清单、正式包校验和 6 项 packaged E2E。- - 自动更新源固定为 GitHub Releases `wulien/opencreator-agent`,生产运行时不依赖环境变量。- - macOS x64、arm64 和 Windows x64 CI 发布矩阵、OSV、签名参数和更新元数据流程已配置。-5. 自动化- - Desktop 48 项单元测试和 6 项 packaged E2E。- - Web 532 项单元/组件测试。- - Daemon 663 项通过,23 项条件型用例显式跳过并单独记录。- - 本机 Codex CLI 0.144.4 真实冷启动 hello Smoke。- - OSV Scanner 2.3.8 发布源码扫描和 actionlint 1.7.7 工作流静态检查。--### 3.2 剩余环境验收--以下项目不是代码缺口,当前因外部发布环境不足标记为 `BLOCKED_ENV`:--1. macOS Developer ID 正式签名。-2. Apple 公证、stapling 和 Gatekeeper 正式包验证。-3. 从上一正式版本通过真实更新服务升级。-4. macOS 通知中心点击的发布包人工验收。-5. Windows x64 构建机上的安装、托盘、通知、协议和进程树实机验收。-6. Windows Authenticode 正式签名。--### 3.3 复用边界--桌面版继续复用且不重写:--1. Web 主 Dashboard 和现有业务页面。-2. Daemon 的 Thread、Run、Scheduler、Skills 和 MCP 服务。-3. Daemon 的 bearer token 鉴权;生产 Renderer 只能通过 Main 同源代理访问。-4. 通知 outbox 数据模型和确认语义。-5. 现有 Thread、Run、Approval 深链接格式。-6. `OPENCREATOR_CODEX_BIN`、`CODEX_HOME`、`OPENCREATOR_DATA_DIR` 和 `OPENCREATOR_DEFAULT_CWD` 环境入口。--## 4. 目标与成功标准--### 4.1 产品目标--1. 用户点击 OpenCreator 后立即看到启动检查界面。-2. OpenCreator 自动找到用户在终端中实际使用的 Codex CLI。-3. OpenCreator 通过真实 Codex 请求判断环境是否可用。-4. 探测成功后自动进入现有主 Dashboard 。-5. 探测失败时提供明确、可操作且不误判登录状态的诊断。-6. 用户刷新页面时不会再次等待 Codex 探测。-7. 用户关闭主窗口后,正在执行的任务和计划任务可以继续运行。-8. 系统通知可以打开正确的 Thread、Run 或 Approval。-9. 应用重新打开时复用正在运行的 Daemon。-10. 应用真正退出时可以有序关闭 Daemon。--### 4.2 技术成功标准--1. Electron Main、Preload、Renderer 和 Daemon 进程边界明确。-2. `nodeIntegration=false`、`contextIsolation=true`、`sandbox=true`。-3. Renderer 只能通过固定 IPC 白名单访问原生能力。-4. Daemon 只监听 `127.0.0.1`,端口由系统分配。-5. Daemon token 不写入磁盘和日志。-6. Desktop Host 能从 Daemon stdout 可靠获取连接配置。-7. 冷启动时最多执行一次自动 Codex 探测。-8. 自动探测失败后不自动循环重试。-9. 探测使用临时会话,不进入 OpenCreator Thread、Run 或通知历史。-10. 探测不启动 OpenCreator Scheduler,直到探测成功。-11. 探测不调用 `codex login status` 或 `codex doctor`。-12. 探测不调用 MCP 管理 API、Skills 扫描或 Skill Market。-13. 页面刷新不会重启 Daemon,也不会再次调用 Codex。-14. Daemon 崩溃后 Host 能展示故障状态并执行受控重启。-15. `better-sqlite3` 能在打包后的 Utility Process 中正常加载。-16. 生产 Renderer 无法读取或持久化 Daemon token。-17. Desktop 首次启动可以安全导入现有 `.runtime` 数据,失败时不破坏源数据。--### 4.3 性能目标--1. 点击应用后 500ms 内显示启动检查窗口。-2. 本机 Codex 路径解析目标耗时不超过 2 秒,硬超时 5 秒。-3. Codex 真实探测硬超时 45 秒。-4. 探测成功后 1.5 秒内开始显示 OpenCreator 主 Dashboard;Capability 完整扫描不能阻塞该目标。-5. 主 Dashboard 刷新不执行 Codex 探测,目标恢复时间不超过 2 秒。-6. 从托盘重新打开窗口不执行 Codex 探测,目标显示时间不超过 500ms。--## 5. 非目标--第一阶段不做:--1. 内置或自动下载 Codex CLI。-2. OpenCreator 内部的 Codex 登录、退出或账号切换。-3. API Key、ChatGPT 账号或访问令牌管理。-4. Codex 版本自动更新。-5. 独立于 `$CODEX_HOME` 的第二套 Codex 配置。-6. 启动时加载全部 MCP。-7. 启动时扫描全部 Skills。-8. 启动时加载 Skill Market。-9. 多个主窗口。-10. 内置终端、Git 面板或 IDE 级编辑器。-11. 云同步、多人协作和团队账号。-12. 将 Daemon 安装为独立系统服务。-13. 移动端桌面伴侣。--## 6. 总体架构--```text-┌────────────────────────────────────────────┐-│ OpenCreator Desktop Host / Electron Main │-│ │-│ Codex Resolver Bootstrap Controller │-│ Daemon Manager Window Manager │-│ Tray Manager Notification Manager │-│ Deep Link Manager Update Manager │-└───────────────────────┬────────────────────┘- │ Utility Process- ▼-┌────────────────────────────────────────────┐-│ OpenCreator Daemon │-│ │-│ Codex Probe Runtime API │-│ Thread / Run Scheduler │-│ Skills / MCP SQLite / Notifications │-└───────────────────────┬────────────────────┘- │ child process- ▼-┌────────────────────────────────────────────┐-│ 用户本机 Codex CLI │-│ 用户本机 CODEX_HOME │-└────────────────────────────────────────────┘--Electron Renderer- -> 只加载本地打包的现有 apps/web- -> 通过 Preload Bridge 获取连接配置和原生能力- -> 通过 HTTP/SSE 访问 127.0.0.1 Daemon-```--### 6.1 Electron Main 职责--1. 保证单实例。-2. 创建启动检查窗口和主 Dashboard 窗口。-3. 解析 Codex CLI 路径和 Shell 环境。-4. 启动、监控、重启和关闭 Daemon。-5. 解析 Daemon stdout 启动协议。-6. 保存 Desktop 专属设置。-7. 管理托盘、系统通知和外部深链接。-8. 管理自动更新。-9. 记录 Desktop Host 日志。--Electron Main 不负责:--1. Thread、Run 或 Schedule 数据。-2. Codex 会话协议。-3. Skills 或 MCP 业务逻辑。-4. React 页面状态。-5. 直接访问 OpenCreator SQLite。--### 6.2 Preload 职责--1. 通过 `contextBridge` 暴露固定 API。-2. 对 Renderer 输入做基础类型校验。-3. 将 IPC 结果映射为 `HostBridge`。-4. 不暴露 `ipcRenderer`、Shell 或任意文件读取能力。--### 6.3 Renderer 职责--1. 运行现有 `apps/web`。-2. 从 Desktop Host 获取 Daemon 连接配置。-3. 使用现有 RuntimeClient 调用 Daemon。-4. 处理 Host 发出的连接更新和深链接导航事件。-5. 不参与冷启动 Codex 探测。--### 6.4 Daemon 职责--1. 使用 Host 指定的 `OPENCREATOR_CODEX_BIN` 和标准 `CODEX_HOME`。-2. 在 Desktop 模式下先完成真实 Codex 探测。-3. 探测成功后再启动完整 Runtime 和 Scheduler。-4. 继续承载所有现有业务能力。-5. 输出结构化启动状态和最终连接配置。--## 7. 桌面应用产品形态--### 7.1 窗口模型--第一版只使用一个主 BrowserWindow:--1. 启动时加载 Desktop 自带的轻量 Bootstrap 页面。-2. 探测成功后,同一个窗口切换到打包后的 `apps/web`。-3. 不创建登录窗口。-4. 不创建独立设置窗口。-5. 不创建独立审批窗口。-6. 通知点击后复用并聚焦主窗口。--使用同一个窗口的原因:--1. 避免 Splash 窗口和主窗口切换闪烁。-2. 避免两个窗口之间同步尺寸和焦点。-3. 启动失败时可以直接保留诊断界面。-4. 主 Dashboard 加载前不会挂载现有 Web App。--### 7.2 启动检查页面--正常状态依次展示:--1. `正在查找本机 Codex`-2. `正在启动本地运行服务`-3. `正在验证 Codex 是否可用`-4. `正在打开 OpenCreator`--页面要求:--1. 只展示当前阶段,不展示 Skills、MCP 或项目加载状态。-2. 3 秒内完成时保持简洁,不展示技术细节。-3. 超过 3 秒后显示当前阶段和已等待时间。-4. 不显示“正在登录”。-5. 不显示账号头像、验证码、API Key 输入框。-6. 不提供跳过按钮。--### 7.3 启动失败页面--失败页面统一使用:--```text-Codex CLI 暂时无法完成调用--OpenCreator 已尝试通过本机 Codex 发送一条测试消息,-但没有收到有效响应。-```--主要动作:--1. `重新检测`-2. `选择 Codex 路径`-3. `查看诊断`-4. `退出 OpenCreator`--诊断信息:--1. Codex 实际路径。-2. `CODEX_HOME`。-3. 探测阶段。-4. 调用耗时。-5. 退出码或终止信号。-6. 脱敏后的 stderr 摘要。-7. Desktop Host 日志目录。--禁止出现:--1. `尚未登录`-2. `登录已过期`-3. `请在 OpenCreator 中登录`-4. 未经 Codex 明确返回的认证原因推断--## 8. Codex 路径与环境解析--### 8.1 解析原则--GUI 应用不能假设能继承用户终端中的完整 `PATH`。Desktop Host 必须解析并保存实际 Codex 路径,同时将匹配的环境传给 Daemon。--解析优先级:--1. 用户手动选择并且上次探测成功的 Codex 路径。-2. Desktop 设置中保存的上次成功路径。-3. 当前 Electron 进程环境中的 `PATH`。-4. 用户登录 Shell 环境中的 `PATH`。-5. macOS 常见本地可执行目录。-6. 找不到时进入路径选择状态。--macOS 常见目录只作为候选来源,不作为可用性证明:--```text-/opt/homebrew/bin-/usr/local/bin-~/.local/bin-~/.local/node-current/bin-~/.npm-global/bin-```--### 8.2 Shell 环境恢复--Desktop Host 可以通过用户默认 Shell 获取登录环境,但必须满足:--1. 命令内容固定,不拼接用户输入。-2. 使用 5 秒硬超时。-3. 限制输出大小。-4. 忽略 Shell 初始化脚本产生的额外文本。-5. 失败后继续使用现有环境和常见路径,不导致 Main 进程退出。-6. 不使用 `shell: true` 执行动态命令。--### 8.3 路径持久化--Desktop 设置只保存:--```ts-type DesktopRuntimeSettings = {- codexBin?: string;- closeBehavior: 'hide' | 'quit';-};-```--规则:--1. 只在真实探测成功后将候选路径标记为“上次成功路径”。-2. 手动选择但探测失败的路径可以保留为当前候选,但不能覆盖成功路径。-3. 不保存 token。-4. 不复制 Codex 配置。-5. 不保存 Codex 登录状态。--### 8.4 传递给 Daemon 的环境--Desktop Host 至少传递:--```text-OPENCREATOR_CODEX_BIN=<absolute path>-CODEX_HOME=<resolved CODEX_HOME>-OPENCREATOR_DATA_DIR=<app userData>/daemon-OPENCREATOR_DEFAULT_CWD=<user home or configured workspace>-OPENCREATOR_REQUIRE_CODEX_PROBE=1-OPENCREATOR_CODEX_PROBE_VERIFIED=0-HOME=<user home>-PATH=<resolved shell path>-SHELL=<user shell>-```--Daemon 及其 Codex 子进程必须使用同一组环境,避免探测和真实 Run 使用不同 Codex。--## 9. 冷启动门禁--### 9.1 触发时机--自动探测只在以下情况触发:--1. Desktop Host 冷启动并创建新的 Daemon。-2. 用户选择新的 Codex 路径。-3. 用户改变 `CODEX_HOME`。-4. 用户在失败页面点击 `重新检测`。--以下操作不能触发:--1. Renderer 刷新。-2. 前端路由切换。-3. 打开插件页面。-4. 打开设置页面。-5. 切换项目或会话。-6. 隐藏窗口后从托盘重新打开。-7. 系统通知点击。-8. Daemon 在同一 Desktop 生命周期中异常退出,且 Codex 路径、`CODEX_HOME` 和关键环境指纹未变化。--### 9.2 启动状态机--```text-IDLE- -> RESOLVING_CODEX- -> STARTING_DAEMON- -> PROBING_CODEX- -> STARTING_RUNTIME- -> READY--任意非 READY 阶段- -> FAILED--FAILED- -> RETRYING- -> RESOLVING_CODEX-```--状态类型:--```ts-type DesktopBootstrapPhase =- | 'idle'- | 'resolving_codex'- | 'starting_daemon'- | 'probing_codex'- | 'starting_runtime'- | 'ready'- | 'failed';--type DesktopBootstrapState = {- phase: DesktopBootstrapPhase;- startedAt: string;- updatedAt: string;- attempt: number;- codexBin?: string;- codexHome?: string;- durationMs?: number;- error?: DesktopBootstrapError;-};-```--### 9.3 Daemon Bootstrap 模式--当 `OPENCREATOR_REQUIRE_CODEX_PROBE=1` 时,Daemon 启动顺序必须改为:--```text-读取环境- -> 输出 probing_codex 状态- -> 执行真实 Codex Probe- -> Probe 成功- -> 读取缓存或收集启动必需的 capability 信息- -> buildServer()- -> 启动 Scheduler- -> listen(127.0.0.1, 0)- -> 输出 address + token-```--Probe 失败时:--1. 不调用 `buildServer()`。-2. 不打开 SQLite。-3. 不启动 Scheduler。-4. 不扫描 Skills。-5. 不创建 MCP Manager。-6. 输出结构化失败事件。-7. 以非零退出码结束 Daemon。--普通 Web 开发模式不设置 `OPENCREATOR_REQUIRE_CODEX_PROBE`,避免每次开发启动都产生真实模型调用。--### 9.4 Daemon stdout 协议--Bootstrap 进度行:--```json-{- "type": "opencreator_daemon_bootstrap",- "phase": "probing_codex",- "at": "2026-07-15T00:00:00.000Z"-}-```--探测成功:--```json-{- "type": "opencreator_daemon_bootstrap",- "phase": "probe_succeeded",- "durationMs": 1840,- "responseReceived": true-}-```--探测失败:--```json-{- "type": "opencreator_daemon_bootstrap_error",- "code": "CODEX_PROBE_TIMEOUT",- "message": "Codex CLI did not return an assistant message before timeout",- "durationMs": 45000,- "details": {- "exitCode": null,- "signal": "SIGTERM"- }-}-```--最终就绪行继续兼容现有协议:--```json-{- "address": "http://127.0.0.1:60855",- "token": "runtime-token"-}-```--规则:--1. 最终连接行的 `address` 和 `token` 字段不能改名。-2. token 只能通过父子进程管道传递。-3. 日志模块必须识别并删除 token 后再落盘。-4. Desktop Host 忽略未知 Bootstrap 事件,保证向后兼容。--## 10. Codex Probe 设计--### 10.1 Probe 服务--新增独立的 `CodexProbeService`:--```ts-type CodexProbeInput = {- codexBin: string;- codexHome: string;- cwd: string;- timeoutMs: number;- env?: Record<string, string>;-};--type CodexProbeResult = {- ready: boolean;- responseReceived: boolean;- markerMatched: boolean;- durationMs: number;- exitCode: number | null;- signal: NodeJS.Signals | null;- terminationReason: string;- stderrSummary?: string;-};-```--Probe 服务必须:--1. 复用 `startCodexExec()` 的进程托管、超时和强制终止能力。-2. 使用独立 Probe argv builder。-3. 解析 Codex JSONL 中的 assistant message。-4. 不使用 `RunManager`。-5. 不写 OpenCreator SQLite。-6. 不创建 OpenCreator Thread 或 Run。-7. 不生成通知。-8. 不调用 Scheduler。-9. 对 stderr 做脱敏和长度限制。--### 10.2 Probe 请求--每次探测生成随机 challenge:--```text-OPENCREATOR_READY_<random nonce>-```--Prompt:--```text-This is a OpenCreator startup availability probe.-Do not call tools and do not modify files.-Reply briefly to this hello message.-If possible, include this marker: OPENCREATOR_READY_<nonce>-```--成功标准:--1. Codex 进程正常完成。-2. JSONL 中至少出现一条非空 `agent_message`。--`markerMatched` 只作为诊断字段,不作为硬门禁。只要收到真实 assistant 消息,就证明 Codex CLI 基础模型调用能够完成;它不证明后续 `app-server` transport、MCP 或 Skills 一定可用。--### 10.3 Probe argv--目标命令语义:--```text-CODEX_HOME=<temporary sanitized probe home>-codex exec- --json- --ephemeral- --skip-git-repo-check- --ignore-rules- --sandbox read-only- -c approval_policy="never"- -c model_reasoning_effort="low"- -c model_verbosity="low"- -c mcp_servers={}- -c plugins={}- -c web_search="disabled"- -c notify=[]- -c check_for_update_on_startup=false- --disable hooks- --disable plugins- --disable apps- --disable multi_agent- --disable browser_use- --disable computer_use- --disable in_app_browser- --disable image_generation- --disable tool_suggest- --disable shell_tool- --disable unified_exec- --disable shell_snapshot- -C <empty probe directory>- --output-last-message <temporary result file>-```--要求:--1. Prompt 通过 stdin 传入,不拼入 Shell 命令。-2. 输入源是用户真实 `CODEX_HOME`,但 Codex Probe 子进程只使用一次性临时 Home。-3. 临时 Home 不复制整份 `config.toml`;Daemon 使用 TOML 解析器读取基础配置,只写入 model、选中 provider、认证路由、模型目录和请求兼容字段,并复制 `auth.json` 与模型目录文件,因此保留真实调用链但不继承无关启动行为。Codex `0.134.0+` 的 Profile 只能由 `--profile <name>` 显式选择,启动 Probe 不带该参数,所以不得读取旧式顶层 `profile`、内联 `[profiles.*]` 或任意 `<name>.config.toml`。-4. 使用空 Probe 工作目录,避免加载项目 `AGENTS.md`。-5. 使用 `--ephemeral`,避免持久化 Codex session。-6. 使用 `read-only`,禁止文件修改。-7. 不复制 Skills、Plugins、MCP OAuth 凭据、Rules、Hooks 和项目状态。-8. 通过配置覆盖清空 MCP、Plugins 和通知,关闭启动更新检查,并显式禁用 Hooks、Apps、浏览器、Computer Use、图片生成、工具建议、Shell 和 Exec 等扩展能力。-9. 推理等级和输出详细度固定为 `low`,减少启动门禁的耗时与成本。-10. 不传图片、Skills、附件或项目目录。-11. 不调用 `codex login status`。-12. 不调用 `codex doctor`。-13. Probe 结果记录 `homePreparationMs`、`firstEventMs`、`responseReceivedMs` 和 `processExitMs`,避免把配置准备、CLI 初始化、模型响应和进程退出笼统归为“hello 耗时”。--如果目标 Codex CLI 不接受 Probe 必需参数,则 Probe 失败并展示真实错误;不根据版本号提前推断。临时 Home 的设计保证自定义 provider 和 model 与真实运行环境一致,同时不让用户 Skills、Plugins 或 MCP 参与启动门禁。--Probe 成功信号优先级:--1. `--output-last-message` 文件存在且包含非空 assistant 文本。-2. JSONL `agent_message` 作为兼容成功信号。-3. JSONL 事件只用于诊断,不把具体事件 schema 当作长期稳定协议。--### 10.4 Probe 工作目录和临时 Home--工作目录位于:--```text-<app userData>/probe-```--临时 Home 位于操作系统临时目录:--```text-<os temp>/opencreator-codex-probe-<random>/-```--规则:--1. 工作目录由 Daemon 创建。-2. 工作目录中不能包含项目文件、`AGENTS.md` 或用户内容。-3. 每次启动前清理 OpenCreator 自己生成的临时 Probe 文件。-4. Probe 不允许访问用户项目 cwd。-5. 临时 Home 权限为 `0700`,复制的文件权限为 `0600`。-6. Probe 完成、失败或超时后都必须删除临时 Home 和输出文件。-7. 不把临时 Home 用于正常 Thread、Run、Scheduler、Skills 或 MCP。-8. `model_catalog_json` 指向的文件必须复制到临时 Home 并重写路径,不能借最小配置重新访问用户原始目录。--### 10.5 超时和重试--1. 总超时:45 秒。-2. Spawn 首次活动超时:5 秒。-3. 进程终止宽限:2 秒。-4. 自动探测只执行一次。-5. 失败后不自动重试,避免重复模型调用。-6. 用户点击 `重新检测` 后执行新 attempt。-7. 新 attempt 开始前必须终止并回收旧 Daemon。-8. 同一 attempt 内禁止并发 Probe。--### 10.6 Probe 错误码--```ts-type CodexProbeErrorCode =- | 'CODEX_NOT_FOUND'- | 'CODEX_PATH_INVALID'- | 'CODEX_PROBE_SPAWN_FAILED'- | 'CODEX_PROBE_SPAWN_TIMEOUT'- | 'CODEX_PROBE_TIMEOUT'- | 'CODEX_PROBE_EXIT_NON_ZERO'- | 'CODEX_PROBE_INVALID_OUTPUT'- | 'CODEX_PROBE_NO_RESPONSE'- | 'DAEMON_START_FAILED'- | 'DAEMON_EXITED_BEFORE_READY';-```--禁止定义:--```text-CODEX_NOT_LOGGED_IN-CODEX_LOGIN_EXPIRED-CODEX_AUTH_REQUIRED-```--除非未来 Codex CLI 提供稳定、明确且本产品决定使用的结构化错误协议,否则 OpenCreator 不推断认证状态。--## 11. Daemon 生命周期--### 11.1 启动--Desktop Host:--1. 解析 Codex 路径和环境。-2. 使用 Electron Utility Process 启动打包后的 Daemon 入口。-3. 订阅 stdout、stderr 和 exit。-4. 解析 Bootstrap 状态。-5. 收到最终 `address + token` 后保存内存连接配置。-6. 将 Bootstrap 状态切换为 `ready`。-7. 通知 Window Manager 加载主 Dashboard 。--### 11.2 正常退出--用户选择 `退出 OpenCreator` 时:--1. 停止通知 outbox 消费。-2. 停止接受新的深链接导航。-3. 通过 Utility Process `postMessage({ type: 'shutdown' })` 请求 Daemon 优雅关闭。-4. 最多等待 5 秒。-5. Daemon 收到消息后调用 `server.close()`,停止 Scheduler 并回收 Codex 子进程。-6. 超时后调用 `UtilityProcess.kill()`。-7. 再等待 2 秒后使用平台级进程终止兜底,并清理已知 Codex 子进程。-8. 清理内存 token。-9. 退出 Electron。--### 11.3 窗口关闭--默认行为:--1. 点击关闭按钮只隐藏主窗口。-2. Daemon 和 Scheduler 继续运行。-3. 托盘继续显示。-4. 系统通知继续消费。--设置允许切换为:--```text-关闭窗口时退出 OpenCreator-```--### 11.4 Daemon 异常退出--规则:--1. Host 记录退出码和信号。-2. 主窗口仍存在时显示运行服务中断状态。-3. 第一次异常退出允许自动重启一次。-4. Codex 环境指纹未变化且本次 Desktop 生命周期已有成功 Probe 时,自动重启不重复 Probe。-5. 第二次连续失败停止自动重启,进入诊断状态。-6. 不允许无限重启循环。-7. 恢复成功后通过 Host 事件更新 Web UI 连接配置。--连续失败计数在以下情况清零:--1. Daemon 稳定运行超过 5 分钟。-2. 用户手动点击重新检测并成功。--## 12. Renderer 与 Host Bridge--### 12.1 Desktop Bridge--新增 Desktop Bridge 实现,并保持现有 `HostBridge` 兼容:--```ts-type DesktopHostBridge = HostBridge & {- kind: 'desktop';- subscribeConnectionConfig?(- listener: (connection: ConnectionConfig | null) => void- ): () => void;- restartRuntime?(): Promise<HostBridgeResult>;-};-```--现有方法继续支持:--1. `readConnectionConfig()`;Desktop 只返回同源 Runtime 代理地址,不返回真实 token。-2. `openExternal()`-3. `revealPath()`-4. `notify()`-5. `configureBackgroundNotifications()`--### 12.2 连接配置--规则:--1. 主 Dashboard 首次加载时,`readConnectionConfig()` 必须立即返回当前 Daemon 配置。-2. Renderer 刷新只重新读取内存配置。-3. Renderer 不负责启动 Daemon。-4. Renderer 不负责执行 Codex Probe。-5. Daemon 重启后由 Main 更新代理目标,并通过订阅事件下发新的代理连接状态。-6. Browser Bridge 行为保持不变。--### 12.3 内部页面协议--生产环境不直接使用 `file://` 加载主 Dashboard 。Desktop Host 注册安全的内部 scheme:--```text-opencreator-app://app/-```--外部深链接使用:--```text-opencreator://-```--两者不能混用:--1. `opencreator-app://` 只服务打包后的本地静态资源。-2. `opencreator://` 只接收系统外部唤起。-3. Daemon CORS 只增加对精确内部 origin 的允许。-4. 不允许任意自定义 scheme origin 访问 Daemon。-5. `opencreator-app://app/.opencreator/runtime/*` 由 Main 使用 Node 24 标准 `fetch` 转发到 Daemon,并在最终同源断言后注入 Authorization。请求使用 `redirect: 'manual'`;Electron `net.fetch` 因在 `protocol.handle` 内出现过无法稳定收敛的挂起,不再用于该链路。-6. Runtime 代理必须支持 JSON、二进制上传下载和流式 SSE。-7. 内部 scheme 必须在 `app.ready` 前通过 `registerSchemesAsPrivileged` 注册为 `standard`、`secure` 且支持 Fetch API。--### 12.4 IPC 安全--BrowserWindow 固定配置:--```ts-{- webPreferences: {- nodeIntegration: false,- contextIsolation: true,- sandbox: true,- preload: '<absolute preload path>'- }-}-```--必须满足:--1. 不暴露 `require`。-2. 不暴露完整 `ipcRenderer`。-3. 不允许 Renderer 传入任意命令。-4. 不允许 Renderer 传入任意 Shell 参数。-5. `openExternal` 只允许 `https:` 和明确允许的协议。-6. `revealPath` 由 Main 校验路径存在性。-7. 所有 IPC channel 在共享类型文件中静态定义。-8. 所有监听函数返回取消订阅方法。-9. 窗口销毁时释放全部 listener。-10. IPC handler 必须校验 sender frame URL 属于 `opencreator-app://app` 或受控开发 origin。-11. 禁止未受控导航,并通过 `setWindowOpenHandler` 拒绝 Renderer 创建窗口。-12. Preload 构建为单文件 CommonJS,兼容 sandboxed preload 环境。--## 13. 主窗口、托盘和系统集成--### 13.1 主窗口--1. 保存上次窗口尺寸和位置。-2. 恢复时校验窗口仍位于当前显示器可见范围。-3. 最小尺寸必须保证现有桌面 Dashboard 不重叠。-4. 启动阶段和主 Dashboard 阶段复用同一 BrowserWindow。-5. 主 Dashboard 加载失败时显示本地错误页,不能加载远程页面。-6. 外部链接统一交给系统浏览器。--### 13.2 系统托盘--托盘菜单:--1. 打开 OpenCreator。-2. 新建任务。-3. 查看运行中任务。-4. 退出 OpenCreator。--托盘本身不能直接读取 SQLite,所有状态通过 Daemon API 获取。--### 13.3 系统通知--Desktop Host 复用现有 outbox 语义:--1. 轮询或订阅待展示通知。-2. 成功交给系统通知中心后确认。-3. 展示失败不确认,下次重试。-4. 通知点击后打开并聚焦主窗口。-5. 跳转到目标 Thread。-6. 可选定位 Run 和 Approval。-7. Renderer 关闭或刷新不影响通知消费。--### 13.4 深链接--支持:--```text-opencreator://thread/<threadId>-opencreator://thread/<threadId>?runId=<runId>-opencreator://thread/<threadId>?runId=<runId>&approvalId=<approvalId>-opencreator://new-opencreator://tasks-```--规则:--1. 只允许已知 route。-2. 所有 ID 都要 URL decode 后再做格式校验。-3. 应用未启动时缓存深链接,Probe 成功后再导航。-4. Probe 失败时保留待处理深链接。-5. 多次点击同一通知不创建新窗口。-6. Windows 第二实例参数和 macOS `open-url` 统一映射到同一解析器。--## 14. 本地数据与日志--### 14.1 数据目录--```text-<Electron userData>/-├── desktop-settings.json-├── window-state.json-├── logs/-│ ├── desktop-main.log-│ └── daemon.log-├── probe/-└── daemon/- ├── app.sqlite- ├── runs/- ├── workspaces/- └── attachments/-```--Codex 数据继续位于用户真实 `$CODEX_HOME`,不复制到 OpenCreator `userData`。只有启动 Probe 会在操作系统临时目录复制最小配置子集,并在 Probe 结束后删除。--### 14.2 首次数据导入--当 Desktop 数据目录为空时允许导入现有 OpenCreator `.runtime`:--1. 导入必须由明确的源目录触发,不能遍历磁盘猜测多个候选。-2. 导入前创建目标目录备份点并校验源 `app.sqlite`。-3. 不能复制正在被其他 OpenCreator Daemon 使用的 SQLite。-4. 使用临时目录完成复制和校验后再原子切换。-5. 失败时删除未完成目标,源数据保持不变。-6. Desktop 和 Web 开发 Daemon 不能长期共享同一数据目录,避免重复 Scheduler。-7. 迁移 Web origin 下的 localStorage 不作为自动能力;需要将长期偏好迁移到 Desktop 设置或由用户重新配置。--### 14.3 日志规则--1. token 永不落盘。-2. Authorization header 永不落盘。-3. Probe prompt 只记录固定模板,不记录随机完整 challenge。-4. Probe assistant 原始回复默认不落盘。-5. stderr 最多保留脱敏后的末尾 8KB。-6. Desktop 日志按大小轮转。-7. 日志目录可以从诊断页面打开。-8. 用户项目内容不写入 Desktop Main 日志。--## 15. 打包与发布--### 15.1 构建结构--新增:--```text-apps/desktop-├── package.json-├── tsconfig.json-├── electron-builder.yml-├── src/-│ ├── main/-│ │ ├── main.ts-│ │ ├── bootstrap-controller.ts-│ │ ├── codex-resolver.ts-│ │ ├── daemon-manager.ts-│ │ ├── window-manager.ts-│ │ ├── tray-manager.ts-│ │ ├── notification-manager.ts-│ │ ├── deep-link-manager.ts-│ │ ├── settings-store.ts-│ │ ├── protocol-handler.ts-│ │ └── updater.ts-│ ├── preload/-│ │ └── index.ts-│ ├── bootstrap/-│ │ ├── index.html-│ │ ├── main.tsx-│ │ └── BootstrapView.tsx-│ └── shared/-│ ├── ipc.ts-│ └── types.ts-└── resources/- ├── icons/- └── entitlements.mac.plist-```--### 15.2 Daemon 打包--1. Daemon TypeScript 编译为生产 JavaScript。-2. Electron Main 不直接 import Daemon 业务模块。-3. Daemon 通过 Utility Process 加载独立入口。-4. `better-sqlite3` 针对 Electron 使用的 Node ABI 重建。-5. `.node` 原生文件放入 `asarUnpack`。-6. 打包后不依赖用户安装 Node.js。-7. 打包后仍依赖用户安装 Codex CLI。-8. Bootstrap Probe 成功前不静态加载 `better-sqlite3` 所在的完整 Server 模块图。--### 15.3 平台顺序--P0:--1. macOS Apple Silicon 开发包。-2. macOS Intel 构建结构保持可用。--P1:--1. macOS 托盘、通知和深链接。-2. 故障恢复和诊断。--P2:--1. macOS 签名、公证和自动更新。-2. Windows x64 安装包。-3. Windows Codex 路径解析。-4. Windows 深链接和托盘实机验收。--## 16. 实施任务--以下任务按依赖顺序执行。每个批次完成后必须保持全仓可构建、可测试。--### 16.1 实施与验收状态回填--状态说明:--- `DONE`:代码与仓库内自动化已完成。-- `PASS`:当前环境已执行并通过。-- `BLOCKED_ENV`:实现已完成,但需要当前环境没有的证书、发布服务或目标平台实机。--| 任务 | 实施状态 | 自动化/实机状态 | 说明 |-|---|---|---|---|-| P0-A0 Desktop 打包技术尖峰 | DONE | PASS | unsigned macOS arm64 `.app` 已生成;Utility Process、Runtime 代理、原生 SQLite 和进程回收已通过 |-| P0-B1 Electron 工程骨架 | DONE | PASS | 单实例、安全 BrowserWindow、固定 `9000` 开发端口和构建脚本已完成 |-| P0-B2 Codex 路径解析 | DONE | PASS | 登录 Shell、保存路径、手动路径和 Windows `where.exe`/常见目录已覆盖 |-| P0-B3 Daemon Codex Probe | DONE | PASS | 临时净化 Home、真实 assistant 响应判定、45 秒超时和进程回收已覆盖 |-| P0-B4 Daemon Bootstrap | DONE | PASS | Probe 在 Runtime/SQLite/Scheduler 前执行,最终连接协议保持兼容 |-| P0-B5 Desktop DaemonManager | DONE | PASS | Utility Process、内存 token、优雅退出、强制回收和单次恢复已覆盖 |-| P0-B6 Bootstrap 页面 | DONE | PASS | 成功进入 Dashboard,失败停留诊断页,不提供登录或跳过入口 |-| P0-B7 内部协议与 Bridge | DONE | PASS | `opencreator-app://`、固定 IPC 白名单、严格 loopback 同源、10 MiB 上限和 JSON/二进制/SSE 代理已通过 |-| P0-B8 Dashboard 刷新与恢复 | DONE | PASS | 刷新五次 Probe 计数保持 1,Daemon 恢复后连接可更新 |-| P1-B1 窗口与托盘 | DONE | PASS | 默认隐藏、全局关闭行为设置、托盘恢复和有序退出已实现 |-| P1-B2 原生通知 | DONE | PASS(自动化) | outbox、确认语义、去重和点击路由已覆盖;发布包通知中心人工点击为 `BLOCKED_ENV` |-| P1-B3 单实例与深链接 | DONE | PASS | 第二实例、启动前缓存和 `opencreator://` 路由已覆盖 |-| P1-B4 文件与外部应用 | DONE | PASS | 路径定位、外部协议白名单和错误映射已实现 |-| P1-B5 故障恢复与诊断 | DONE | PASS | 首次崩溃恢复、二次熔断、手动重试和脱敏诊断已覆盖 |-| P2-B1 生产打包加固 | DONE | PASS / BLOCKED_ENV | 离线部署、Electron ABI 重建、构建清单、Fuses、ASAR、包内容检查和 6 项 packaged E2E 已通过;无 Node.js 独立干净机验收待外部环境 |-| P2-B2 macOS 发布 | DONE | PASS / BLOCKED_ENV | GitHub Releases 更新状态机、macOS arm64 ad-hoc 包和恢复测试已通过;Developer ID、公证、上一正式版本真实升级仍阻塞 |-| P2-B3 Windows 适配 | DONE | BLOCKED_ENV | 路径、脚本入口、进程树、NSIS 和 CI 已实现;缺少 Windows x64 构建机与实机验收 |-| P2-B4 最终验收 | DONE | PASS / BLOCKED_ENV | 全仓自动化、离线 fresh package、OSV、actionlint 与本机真实 Codex 已通过;外部环境项逐项保留为 `BLOCKED_ENV` 或 `NOT_RUN` |--原任务清单保留作为实现范围和验收定义;最终状态以本节和 `docs/test-reports/opencreator-desktop-final-acceptance.md` 为准。--### P0-A0:完成 Desktop 打包技术尖峰--**目标:** 在业务功能展开前验证 Electron、Utility Process、原生模块和外部 Codex 的打包链。--**实现内容:**--1. 生成 unsigned macOS `.app`。-2. 从 Utility Process 启动编译后的 Daemon。-3. 验证 `better-sqlite3` 打开数据库。-4. 验证外部 Codex CLI 路径和环境传递。-5. 验证内部 scheme、Runtime 代理、SSE 和二进制请求。-6. 验证打包环境默认 cwd 和 macOS TCC 目录行为。--**验收标准:**--- [x] `.app` 不依赖用户 Node.js。-- [x] Utility Process 可以启动和关闭 Daemon。-- [x] 原生模块不存在 ABI 加载错误。-- [x] 强制关闭后没有残留 Codex 子进程。-- [x] 打包问题在后续 P0 功能实现前暴露。--**依赖:** 无。--**规模:** M。--### P0-B1:建立 Electron Desktop 工程骨架--**目标:** 新增可启动的安全 Electron Host,并能在开发环境加载固定 `9000` 端口的现有 Web UI。--**主要文件:**--- `apps/desktop/package.json`-- `apps/desktop/tsconfig.json`-- `apps/desktop/src/main/main.ts`-- `apps/desktop/src/preload/index.ts`-- `apps/desktop/src/shared/ipc.ts`-- `package.json`-- `pnpm-lock.yaml`--**实现内容:**--1. 将 `apps/desktop` 接入 pnpm workspace。-2. 配置 Electron Main、Preload 和 Bootstrap 构建。-3. 创建单实例锁。-4. 使用安全 BrowserWindow 配置。-5. 开发环境加载 `http://127.0.0.1:9000`。-6. 生产环境暂时加载占位 Bootstrap 页面。-7. 增加 `desktop:dev`、`desktop:build` 和 `desktop:test` 脚本。--**验收标准:**--- [x] `pnpm --filter @opencreator/desktop typecheck` 通过。-- [x] Electron 启动后只有一个主窗口。-- [x] 第二次启动不会创建第二个主实例。-- [x] Renderer 中不存在 `window.require`。-- [x] `nodeIntegration=false`、`contextIsolation=true`、`sandbox=true` 有自动化断言。-- [x] 开发模式始终连接 `127.0.0.1:9000`。--**验证:**--```bash-pnpm --filter @opencreator/desktop typecheck-pnpm --filter @opencreator/desktop test-pnpm desktop:dev-```--**依赖:** 无。--**规模:** M。--### P0-B2:实现 Desktop 设置和 Codex 路径解析--**目标:** 在 GUI 环境中找到用户终端实际使用的 Codex,并保存上次成功路径。--**主要文件:**--- `apps/desktop/src/main/codex-resolver.ts`-- `apps/desktop/src/main/settings-store.ts`-- `apps/desktop/src/shared/types.ts`-- `apps/desktop/test/codex-resolver.test.ts`--**实现内容:**--1. 实现路径候选优先级。-2. 实现登录 Shell 环境恢复。-3. 实现超时、输出限制和路径规范化。-4. 实现手动选择可执行文件。-5. 保存候选路径和上次成功路径。-6. 将完整解析环境传给 DaemonManager。--**验收标准:**--- [x] 能解析当前机器上的 `~/.local/node-current/bin/codex` 类路径。-- [x] Electron 原始 `PATH` 不含 Codex 时,仍能从登录 Shell 找到。-- [x] Shell 环境读取超过 5 秒会终止。-- [x] 无效保存路径不会阻断后续候选搜索。-- [x] 未经真实 Probe 成功的路径不会覆盖成功路径。-- [x] 测试不调用真实模型。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- codex-resolver-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** P0-B1。--**规模:** M。--### P0-B3:实现 Daemon Codex Probe 服务--**目标:** 在 Daemon 中通过真实 `codex exec --ephemeral` 请求判断 Codex 是否能返回 assistant 消息。--**主要文件:**--- `apps/daemon/src/codex/probe.ts`-- `apps/daemon/src/codex/probe-argv.ts`-- `apps/daemon/src/codex/runner.ts`-- `apps/daemon/test/unit/codex-probe.test.ts`-- `apps/daemon/test/unit/codex-probe-argv.test.ts`--**实现内容:**--1. 新增 `CodexProbeService`。-2. 生成固定模板和随机 marker。-3. 构建临时、只读的 Probe argv,并使用净化临时 `CODEX_HOME` 隔离 Skills、Plugins 和 MCP 状态。-4. 复用 `startCodexExec()`。-5. 优先读取 `--output-last-message`,并兼容解析 JSONL `agent_message`。-6. 按成功、超时、退出非零、无响应和非法输出映射结果。-7. 对 stderr 脱敏并截断。-8. 使用 fake Codex executable 完成单元测试。--**验收标准:**--- [x] 收到任意非空 assistant 消息即成功。-- [x] marker 未匹配但有 assistant 消息仍成功。-- [x] `--ephemeral`、`read-only` 和空 cwd 被传入。-- [x] 临时 Home 不复制 Skills、Plugins 和 MCP OAuth 凭据,argv 同时明确清空 MCP 与 Plugins。-- [x] 不调用 `login status`。-- [x] 不调用 `doctor`。-- [x] 不创建 OpenCreator Thread、Run、通知或 SQLite 文件。-- [x] 超时后进程被完整回收。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- codex-probe-pnpm --filter @opencreator/daemon typecheck-```--**依赖:** 无,可与 P0-B1 并行。--**规模:** M。--### P0-B4:接入 Daemon Bootstrap 协议--**目标:** Desktop 模式下先 Probe,成功后再构建完整 Runtime。--**主要文件:**--- `apps/daemon/src/main.ts`-- `apps/daemon/src/startup.ts`-- `apps/daemon/src/api/server.ts`-- `apps/daemon/test/unit/startup.test.ts`-- `apps/daemon/test/integration/desktop-bootstrap.test.ts`--**实现内容:**--1. 解析 `OPENCREATOR_REQUIRE_CODEX_PROBE`。-2. 在 `buildServer()` 前执行 Probe。-3. 输出结构化 Bootstrap 事件。-4. Probe 失败时输出结构化错误并退出。-5. Probe 成功后读取 capability 缓存;缓存缺失时只同步检测启动必需项,完整检测异步执行。-6. 保持最终 `{ address, token }` 协议兼容。-7. 普通 Web 开发模式保持原启动行为。--**验收标准:**--- [x] Probe 失败时不会调用 `buildServer()`。-- [x] Probe 失败时不会创建 `app.sqlite`。-- [x] Probe 失败时 Scheduler 不启动。-- [x] Probe 成功时最终输出连接配置。-- [x] 最终连接行 token 不进入日志快照。-- [x] 未设置 Desktop Probe 环境变量时不产生真实模型调用。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- desktop-bootstrap-pnpm --filter @opencreator/daemon test -- startup-pnpm --filter @opencreator/daemon typecheck-```--**依赖:** P0-B3。--**规模:** M。--### P0-B5:实现 Desktop DaemonManager--**目标:** Electron Main 能启动、监控和关闭打包后的 Daemon Utility Process。--**主要文件:**--- `apps/desktop/src/main/daemon-manager.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/src/shared/types.ts`-- `apps/desktop/test/daemon-manager.test.ts`--**实现内容:**--1. 使用 Utility Process 启动 Daemon。-2. 传入 Codex、数据目录和 Probe 环境。-3. 解析多行 JSON stdout。-4. 将进度、失败和连接配置转换为 Bootstrap 状态。-5. 保存 token 到 Main 进程内存。-6. 实现优雅退出和强制终止。-7. 实现单 attempt 去重。-8. 实现最多一次异常自动重启。--**验收标准:**--- [x] 同一 attempt 只启动一个 Daemon。-- [x] 未收到最终连接行前不产生可用连接配置。-- [x] stdout 非 JSON 噪声不会导致 Main 崩溃。-- [x] token 不进入 Desktop 日志。-- [x] Daemon 超时和提前退出能映射到稳定错误码。-- [x] 退出 OpenCreator 后没有残留 Daemon 进程。-- [x] 正常退出通过 `postMessage` 触发 `server.close()`。-- [x] 同一环境下异常重启不会重复 Probe。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- daemon-manager-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** P0-B2、P0-B4。--**规模:** M。--### P0-B6:实现 Bootstrap 页面和主窗口切换--**目标:** 用户先看到环境检查,Probe 成功后同窗口进入 OpenCreator 主 Dashboard 。--**主要文件:**--- `apps/desktop/src/bootstrap/index.html`-- `apps/desktop/src/bootstrap/main.tsx`-- `apps/desktop/src/bootstrap/BootstrapView.tsx`-- `apps/desktop/src/main/window-manager.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/test/bootstrap-view.test.tsx`--**实现内容:**--1. 创建 Bootstrap UI。-2. 将 Bootstrap 状态通过 IPC 推送到页面。-3. 实现正常阶段、慢等待和失败状态。-4. 实现重新检测、选择路径、查看日志和退出。-5. Probe 成功后切换到 Web UI。-6. 保持 BrowserWindow 不销毁。--**验收标准:**--- [x] 主 Dashboard 不会在 Probe 成功前挂载。-- [x] 页面不出现登录、API Key 或账号输入。-- [x] 页面不出现 Skills 或 MCP 加载状态。-- [x] 失败页面没有跳过按钮。-- [x] 重新检测不会并发启动多个 Daemon。-- [x] 成功后窗口只切换内容,不创建第二个窗口。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- bootstrap-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** P0-B5。--**规模:** M。--### P0-B7:实现生产内部协议和 Desktop Preload Bridge--**目标:** 安全加载打包后的 Web UI,并接入现有 HostBridge。--**主要文件:**--- `apps/desktop/src/main/protocol-handler.ts`-- `apps/desktop/src/preload/index.ts`-- `apps/desktop/src/shared/ipc.ts`-- `apps/web/src/host/bridge.ts`-- `apps/web/src/host/desktop-bridge.ts`-- `apps/web/src/main.tsx`-- `apps/daemon/src/api/server.ts`--**实现内容:**--1. 在 `app.ready` 前注册 `opencreator-app` privileged scheme。-2. 安全映射 `apps/web/dist` 静态资源。-3. Daemon CORS 允许精确内部 origin。-4. Preload 暴露固定 Desktop API。-5. Web 启动时根据 Preload 能力选择 Desktop Bridge。-6. 实现同源 Runtime 代理、连接状态读取和连接更新订阅,真实 token 不进入 Renderer。-7. 保持 Browser Bridge 和 `9000` 开发模式不变。--**验收标准:**--- [x] 生产包不使用远程 URL 加载 UI。-- [x] 内部协议不能读取 `apps/web/dist` 外的文件。-- [x] Renderer 无法访问任意 IPC channel。-- [x] Desktop Bridge 能立即读到连接配置。-- [x] Renderer 无法读取真实 Daemon token。-- [x] Runtime 代理支持 SSE、JSON 和二进制请求。-- [x] Browser Bridge 全部测试继续通过。-- [x] Daemon 只允许精确 Desktop origin 和既有本地 Web origin。--**验证:**--```bash-pnpm --filter @opencreator/web test -- browser-bridge-pnpm --filter @opencreator/desktop test -- protocol-handler-pnpm --filter @opencreator/web typecheck-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** P0-B1、P0-B5、P0-B6。--**规模:** L,实施时应先完成内部协议,再完成 Bridge。--### P0-B8:完成主 Dashboard 连接与刷新行为--**目标:** 主 Dashboard 复用 Daemon 连接,刷新时不重启或重新 Probe。--**主要文件:**--- `apps/web/src/app/AppController.tsx`-- `apps/web/src/host/bridge.ts`-- `apps/web/src/host/desktop-bridge.ts`-- `apps/web/src/services/connection-service.ts`-- `apps/web/src/app/App.test.tsx`-- `apps/desktop/test/electron-refresh.e2e.ts`--**实现内容:**--1. 支持 Desktop Host 推送新的连接配置。-2. 连接更新后重建 RuntimeClient 和 SSE。-3. Renderer 刷新时只读取现有连接。-4. Daemon 重启期间展示连接恢复状态。-5. 恢复后重新订阅当前 Run。-6. 不触发 Skills、MCP 的全局阻塞加载。--**验收标准:**--- [x] 冷启动成功后主 Dashboard 正常加载。-- [x] 连续刷新 5 次只发生一次 Codex Probe。-- [x] 刷新不重启 Daemon PID。-- [x] 刷新后当前 Thread 路由保持。-- [x] Daemon 连接更新后 Web 能恢复 API 调用。-- [x] 插件页面加载失败不影响主 Dashboard 启动。--**验证:**--```bash-pnpm --filter @opencreator/web test-pnpm --filter @opencreator/desktop test -- electron-refresh-pnpm --filter @opencreator/web typecheck-```--**依赖:** P0-B7。--**规模:** M。--### P0 检查点:桌面版最小可运行闭环--- [x] macOS 上可以启动 Electron。-- [x] 能找到本机 Codex。-- [x] 能通过真实 hello Probe。-- [x] Probe 成功后进入现有 OpenCreator 主 Dashboard 。-- [x] Probe 失败时停留在诊断页面。-- [x] 刷新不重复 Probe。-- [x] Daemon token 不落盘。-- [x] 全仓测试、类型检查和构建通过。--### P1-B1:实现窗口生命周期和系统托盘--**目标:** 关闭窗口后任务继续执行,用户可以从托盘恢复或真正退出。--**主要文件:**--- `apps/desktop/src/main/window-manager.ts`-- `apps/desktop/src/main/tray-manager.ts`-- `apps/desktop/src/main/settings-store.ts`-- `apps/desktop/test/tray-manager.test.ts`--**实现内容:**--1. 默认关闭窗口时隐藏。-2. 保存和恢复窗口状态。-3. 创建托盘菜单。-4. 实现打开、新建任务、任务页和退出。-5. 支持设置切换为关闭即退出。--**验收标准:**--- [x] 关闭窗口后 Daemon PID 不变。-- [x] 关闭窗口后正在运行的 Run 不被取消。-- [x] 托盘点击可以恢复同一窗口。-- [x] 托盘退出可以有序关闭 Daemon。-- [x] 窗口位置在显示器变化后仍可见。--**依赖:** P0 检查点。--**规模:** M。--### P1-B2:实现原生通知 outbox 消费--**目标:** 页面隐藏或刷新时,Desktop Host 仍能展示系统通知。--**主要文件:**--- `apps/desktop/src/main/notification-manager.ts`-- `apps/desktop/src/main/daemon-client.ts`-- `apps/harness/src/notification-host.ts`-- `apps/desktop/test/notification-manager.test.ts`--**实现内容:**--1. 按现有 outbox 协议拉取通知。-2. 展示成功后确认。-3. 展示失败时保留 cursor。-4. 去除 Renderer 和 Main 的重复通知。-5. 点击通知进入统一深链接解析器。-6. Daemon 重启后恢复 cursor。--**验收标准:**--- [x] 窗口隐藏时通知仍能展示。-- [x] 同一通知只展示一次。-- [x] 未成功展示的通知不会被确认。-- [x] 通知点击打开正确 Thread、Run 和 Approval。-- [x] Renderer 刷新不会造成重复通知。--**依赖:** P1-B1。--**规模:** M。--### P1-B3:实现单实例和外部深链接--**目标:** 系统通知和外部协议始终聚焦现有实例并导航到正确页面。--**主要文件:**--- `apps/desktop/src/main/deep-link-manager.ts`-- `apps/desktop/src/main/main.ts`-- `apps/desktop/src/main/window-manager.ts`-- `apps/web/src/app/routes.ts`-- `apps/desktop/test/deep-link-manager.test.ts`--**实现内容:**--1. 注册 `opencreator://`。-2. 统一 macOS 和 Windows 参数解析接口。-3. 校验允许 route 和 ID。-4. 启动未就绪时缓存导航。-5. 就绪后通过 IPC 导航。-6. 第二实例只传递参数并退出。--**验收标准:**--- [x] 深链接不会创建第二个主窗口。-- [x] 未完成 Probe 时点击通知不会绕过门禁。-- [x] Probe 成功后自动处理缓存导航。-- [x] 非法 scheme 和 route 被拒绝。-- [x] Thread、Run、Approval 特殊字符能正确编码和解码。--**依赖:** P0-B7、P1-B2。--**规模:** M。--### P1-B4:实现文件和外部应用集成--**目标:** 完成现有 HostBridge 的原生文件定位和外部链接能力。--**主要文件:**--- `apps/desktop/src/main/native-actions.ts`-- `apps/desktop/src/preload/index.ts`-- `apps/web/src/host/desktop-bridge.ts`-- `apps/desktop/test/native-actions.test.ts`--**实现内容:**--1. 实现 `revealPath`。-2. 实现 `openExternal` 协议白名单。-3. 路径不存在时返回稳定错误。-4. 拒绝 Renderer 请求执行任意命令。--**验收标准:**--- [x] 文件和目录能在 Finder 中正确定位。-- [x] 不存在路径返回 `FAILED`,不导致 Main 崩溃。-- [x] `javascript:`、`file:` 和未知协议被拒绝。-- [x] `https:` 链接交给默认浏览器。--**依赖:** P0-B7。--**规模:** S。--### P1-B5:实现故障恢复和诊断导出--**目标:** Daemon 或 Codex Probe 失败后,用户能恢复并获得脱敏诊断。--**主要文件:**--- `apps/desktop/src/main/daemon-manager.ts`-- `apps/desktop/src/main/diagnostics.ts`-- `apps/desktop/src/bootstrap/BootstrapView.tsx`-- `apps/desktop/test/recovery.e2e.ts`--**实现内容:**--1. 实现一次自动重启和熔断。-2. 实现手动重新检测。-3. 实现日志目录打开。-4. 实现脱敏诊断 JSON 导出。-5. 记录 Codex 路径、阶段、耗时、退出码和信号。-6. 不记录 token、认证内容和 assistant 原文。--**验收标准:**--- [x] Daemon 首次崩溃后自动恢复。-- [x] 连续失败后停止重启循环。-- [x] 手动重新检测可以恢复。-- [x] 诊断文件不包含 daemon token。-- [x] 诊断文案不推断登录状态。--**依赖:** P0-B5、P0-B6、P0-B8。--**规模:** M。--### P1 检查点:完整原生桌面体验--- [x] 关闭窗口后后台任务继续。-- [x] 系统通知在页面隐藏时可用。-- [x] 通知点击进入正确页面。-- [x] 单实例和深链接可用。-- [x] 文件定位和外部链接可用。-- [x] Daemon 崩溃恢复和诊断可用。--### P2-B1:完成生产打包加固和原生依赖复验--**目标:** 生成不依赖用户 Node.js 的 macOS 安装包。--**主要文件:**--- `apps/desktop/electron-builder.yml`-- `apps/desktop/package.json`-- `apps/desktop/resources/entitlements.mac.plist`-- `scripts/verify-desktop-package.mjs`-- `package.json`--**实现内容:**--1. 配置 Electron Builder。-2. 打包 Web、Desktop 和 Daemon 产物。-3. 重建并 unpack `better-sqlite3`。-4. 校验资源路径和内部 scheme。-5. 校验安装包内不包含开发依赖和源码映射。-6. 增加安装包烟测脚本。--**验收标准:**--- [ ] `BLOCKED_ENV`:未安装 Node.js 的独立干净用户环境启动验收;包内运行时和原生模块自动化已通过。-- [x] 已安装 Codex CLI 时 Probe 可以成功。-- [x] `better-sqlite3` 正常打开数据库。-- [x] 打包后 Web 静态资源完整。-- [x] Daemon 和 Renderer 不从开发目录读取文件。--**依赖:** P0-A0、P1 检查点。--**规模:** L,实施时拆成打包和原生模块两个提交。--### P2-B2:完成 macOS 签名、公证和自动更新--**目标:** 交付可正常安装和升级的 macOS 正式包。--**主要文件:**--- `apps/desktop/electron-builder.yml`-- `apps/desktop/src/main/updater.ts`-- `apps/desktop/resources/entitlements.mac.plist`-- `.github/workflows/desktop-release.yml` 或现有 CI 等价文件-- `docs/operations/opencreator-desktop-release-runbook.md`--**实现内容:**--1. 配置 Developer ID 签名。-2. 配置 Hardened Runtime 和 entitlements。-3. 配置 notarization。-4. 配置更新元数据和增量更新。-5. 更新下载完成后提示用户重启。-6. 更新期间不强制终止正在运行的任务。--**验收标准:**--- [ ] `BLOCKED_ENV`:Gatekeeper 正式包验证,需要 Developer ID 签名和公证产物。-- [ ] `BLOCKED_ENV`:公证与 stapling 验证,需要 Apple 公证凭据。-- [ ] `BLOCKED_ENV`:从上一正式版本真实升级并验证数据库和设置保留,需要上一版本和更新服务。-- [x] 有运行中任务时不会静默强制重启。-- [x] 更新失败不影响当前版本继续使用。--**依赖:** P2-B1。--**规模:** M。--### P2-B3:补齐 Windows 适配--**目标:** 在不改变产品模型的前提下支持 Windows x64。--**主要文件:**--- `apps/desktop/src/main/codex-resolver.ts`-- `apps/desktop/src/main/deep-link-manager.ts`-- `apps/desktop/electron-builder.yml`-- `apps/desktop/test/windows-paths.test.ts`-- `docs/operations/opencreator-desktop-windows-release.md`--**实现内容:**--1. 支持 `where.exe codex` 和常见 npm 路径。-2. 支持 `.cmd`、`.exe` 可执行入口。-3. 支持 Windows 单实例参数和协议注册。-4. 支持托盘和通知。-5. 构建 NSIS 安装包。--**验收标准:**--- [ ] `BLOCKED_ENV`:Windows 终端与 Desktop Codex 路径一致性实机验证。-- [ ] `BLOCKED_ENV`:Windows 真实 Probe 与 Dashboard 启动实机验证。-- [ ] `BLOCKED_ENV`:Windows 关闭窗口后后台任务实机验证。-- [ ] `BLOCKED_ENV`:Windows 深链接、托盘和通知点击实机验证。-- [ ] `BLOCKED_ENV`:Windows 安装、覆盖升级和卸载数据保留验证。--**依赖:** P2-B1。--**规模:** L,应作为独立平台里程碑。--### P2-B4:最终真实环境验收--**目标:** 对真实 Codex、真实桌面宿主和发布包执行端到端验收。--**主要文件:**--- `docs/test-reports/opencreator-desktop-final-acceptance.md`-- `docs/operations/opencreator-desktop-release-runbook.md`-- `apps/desktop/e2e/`--**验收场景:**--1. Codex 可用,冷启动 Probe 成功。-2. Codex 路径不在 Electron 原始 `PATH` 中,仍能解析成功。-3. Codex 返回非 marker assistant 消息,仍视为成功。-4. Codex 进程超时,进入诊断页面。-5. Codex 退出非零,进入诊断页面。-6. Probe 成功后刷新五次,不产生新 Probe。-7. 从托盘打开五次,不产生新 Probe。-8. Daemon 崩溃一次,自动恢复。-9. Daemon 连续崩溃,停止循环重启。-10. 窗口关闭后计划任务继续执行并发送通知。-11. 通知点击进入正确 Thread、Run 和 Approval。-12. 打包环境中 `better-sqlite3` 正常。-13. 更新后数据保留。-14. 日志和诊断中不存在 token。--**验收标准:**--- [x] 自动化测试全部通过。-- [x] 真实 Codex 冷启动通过。-- [x] macOS 安装包实机通过。-- [ ] `BLOCKED_ENV`:发布包后台通知中心点击实机通过;深链接自动化已通过。-- [x] 所有失败项有明确状态:`PASS`、`FAIL` 或 `BLOCKED_ENV`。--**依赖:** P2-B2;Windows 验收依赖 P2-B3。--**规模:** M。--## 17. 依赖关系--```text-P0-A0 打包技术尖峰- -> P0-B1 Desktop 骨架--P0-B1 Desktop 骨架- ├── P0-B2 Codex 解析- └── P0-B7 内部协议与 Bridge--P0-B3 Codex Probe- -> P0-B4 Daemon Bootstrap- -> P0-B5 DaemonManager--P0-B2 + P0-B5- -> P0-B6 Bootstrap UI- -> P0-B7 Desktop Bridge- -> P0-B8 主 Dashboard 刷新与恢复--P0 检查点- -> P1-B1 托盘- -> P1-B2 通知- -> P1-B3 深链接--P0-B7- -> P1-B4 文件与外部应用--P0-B5 + P0-B6 + P0-B8- -> P1-B5 故障恢复--P1 检查点- -> P2-B1 生产打包- ├── P2-B2 macOS 发布- └── P2-B3 Windows--P2-B2- -> P2-B4 最终验收-```--## 18. 测试策略--### 18.1 单元测试--必须覆盖:--1. Codex 路径候选和优先级。-2. Shell 环境解析和超时。-3. Probe argv。-4. JSONL assistant 消息解析。-5. Probe 超时和进程回收。-6. Daemon stdout 协议解析。-7. token 日志脱敏。-8. 深链接解析。-9. IPC 参数校验。-10. 通知 cursor 和确认语义。--### 18.2 集成测试--使用 fake Codex executable 覆盖:--1. 正常返回 assistant JSONL。-2. 返回非 marker 消息。-3. 无输出退出 0。-4. 输出非法 JSON。-5. 退出非零。-6. 永不退出。-7. stderr 包含模拟 secret。-8. 验证传入的 argv、cwd 和环境。-9. 验证没有 `login status` 和 `doctor`。-10. 验证没有 MCP 子进程。--### 18.3 Electron E2E--使用 Playwright Electron 能力覆盖:--1. Bootstrap 成功进入主 Dashboard 。-2. Bootstrap 失败停留诊断页面。-3. 重新检测。-4. 选择 Codex 路径。-5. Renderer 刷新不 Probe。-6. 关闭到托盘。-7. 通知点击。-8. 深链接。-9. Daemon 崩溃恢复。-10. 安全配置和 IPC 暴露面。--### 18.4 真实 Codex 验收--真实 Codex 测试只在明确的 smoke 或发布验收中运行,不能混入普通单元测试。--至少记录:--1. Codex 路径。-2. Codex 版本,仅作诊断。-3. Probe 耗时。-4. 是否收到 assistant 消息。-5. 是否持久化了新 Codex session。-6. 是否产生 MCP 子进程。-7. Renderer 刷新前后 Probe 次数。--## 19. 发布门禁--### 19.1 P0 发布门禁--1. 冷启动真实 Probe 成功。-2. Probe 失败不加载主 Dashboard 。-3. 页面刷新不 Probe。-4. Desktop 安全配置通过。-5. Daemon 可完整退出。--### 19.2 P1 发布门禁--1. 关闭窗口后任务继续。-2. 原生通知可用。-3. 深链接可用。-4. Daemon 崩溃恢复可用。-5. 日志脱敏通过。--### 19.3 P2 发布门禁--1. 签名和公证通过。-2. 干净机器安装通过。-3. 原生依赖加载通过。-4. 自动更新通过。-5. 最终验收报告无未解释的 `FAIL`。--## 20. 风险与缓解--| 风险 | 影响 | 缓解 |-|---|---|---|-| GUI 环境找不到终端中的 Codex | 无法启动 | 恢复登录 Shell PATH、保存成功绝对路径、支持手动选择 |-| Codex Probe 产生启动延迟 | 用户等待 | 立即显示 Bootstrap、45 秒硬超时、不自动重复调用,固定低推理等级,并用最小配置隔离项目授权、市场、Hooks、通知和更新检查等无关初始化 |-| Probe 每次产生真实模型调用 | 有少量调用成本 | 只在冷启动、环境变化或用户手动重试时执行;刷新、托盘恢复和同环境 Daemon 自动恢复不执行 |-| 全局 MCP、Skills 或 Plugins 拖慢 Probe | 启动长时间卡住 | 使用临时净化 Home,只生成 provider/model/auth 必需配置并复制实际引用文件,在 argv 中清空和禁用扩展能力 |-| 忽略用户配置导致自定义 provider 失效 | Probe 误报 401 或不可用 | 结构化提取 model、选中 provider、认证路由和模型目录,复制 `auth.json`,不使用 `--ignore-user-config` |-| Probe 污染 Codex 历史 | 产生无意义会话 | 使用 `--ephemeral`,发布验收检查 session 目录 |-| Electron Main 泄漏 Daemon token | 本地 API 风险 | token 只保留在 Main,Renderer 通过同源 Runtime 代理访问 |-| `better-sqlite3` ABI 不匹配 | 打包后 Daemon 无法启动 | Electron ABI 重建、`asarUnpack`、安装包 smoke |-| Daemon 无限崩溃重启 | 资源消耗和糟糕体验 | 最多自动重启一次,连续失败熔断 |-| Renderer XSS 获取本地 token | 本地数据风险 | 只加载本地资源、CSP、sandbox、严格 IPC、禁止远程导航 |-| Desktop 首次启动看不到 Web 数据 | 用户数据割裂 | 首次导入、SQLite 校验、临时目录复制和原子切换 |-| 打包 cwd 指向应用资源目录 | 任务目录错误或不可写 | 显式传递 `OPENCREATOR_DEFAULT_CWD` |-| 自动更新中断任务 | 用户任务丢失 | 只提示安装,用户确认退出后更新 |--## 21. 明确禁止的实现--1. 在 Renderer 中使用 `child_process` 启动 Codex。-2. 在 Renderer 中执行 `codex login`。-3. 使用 `codex login status` 作为启动门禁。-4. 使用认证文件存在性作为启动门禁。-5. 只运行 `codex --version` 就判定环境可用。-6. Probe 成功前加载主 Dashboard 。-7. 页面刷新时重新 Probe。-8. Probe 过程中扫描 Skills 或请求 Skill Market。-9. Probe 过程中启动 MCP server。-10. 将 token 写入 localStorage、配置文件或日志。-11. Electron Main 直接访问 OpenCreator SQLite。-12. 使用 `nodeIntegration=true`。-13. 向 Renderer 暴露完整 `ipcRenderer`。-14. 使用用户系统 Node.js 运行打包后的 Daemon。-15. Daemon Probe 失败后仍启动 Scheduler。-16. 仅通过 `mcp_servers={}` 假定已经隔离用户 MCP,而不同时使用净化临时 Home 和扩展禁用参数。-17. 将用户全局 Codex Home 通过 `OPENCREATOR_CODEX_HOME` 伪装成隔离可写目录。-18. 把真实 Daemon token 暴露给生产 Renderer。--## 22. 最终验收定义--桌面版第一阶段只有同时满足以下条件才算完成:--1. 用户本机已经安装且可调用 Codex CLI。-2. 启动 OpenCreator 后先出现环境检查页面。-3. OpenCreator 通过 Daemon 向 Codex 发送一次临时 hello 请求。-4. Codex 返回非空 assistant 消息。-5. OpenCreator 随后加载现有主 Dashboard 。-6. 刷新主 Dashboard 不会再次调用 Codex。-7. 关闭窗口后 Daemon 和计划任务可以继续运行。-8. 系统通知可以唤起正确会话。-9. 真正退出时 Daemon 被完整关闭。-10. 安装包不依赖用户 Node.js,不内置 Codex CLI,也不提供 Codex 登录。diff --git a/docs/specs/2026-07-16-opencreator-desktop-remediation-plan.md b/docs/specs/2026-07-16-opencreator-desktop-remediation-plan.mddeleted file mode 100644index 7f1c619e..00000000--- a/docs/specs/2026-07-16-opencreator-desktop-remediation-plan.md+++ /dev/null@@ -1,1237 +0,0 @@-# OpenCreator Desktop 全面审查整改规格与实施计划--## 0. 文档信息--| 项目 | 内容 |-|---|---|-| 文档状态 | 整改实施与本机发布候选验收完成,外部平台项部分阻塞 |-| 版本 | 1.3 |-| 创建日期 | 2026-07-16 |-| 最近实施验收 | 2026-07-16 |-| 上游规格 | `docs/specs/2026-07-15-opencreator-desktop-app-host-design.md` |-| 审查报告 | `docs/test-reports/opencreator-desktop-final-acceptance.md` |-| 适用范围 | Electron Main、Preload、Bootstrap、Daemon、Runtime 代理、通知、迁移、日志、更新、打包和验收 |-| 实施约束 | 当前分支、当前工作区实施;禁止使用 Git Worktree;不得回退用户现有修改 |--本文用于修复 2026-07-16 全面复审中发现的安全、可靠性、性能和验收证据问题。用户已确认按本文直接执行;当前实现、测试、离线打包和 macOS arm64 发布候选验收已完成,Windows CI/实机、正式签名、公证和真实升级继续按实际状态保留为 `BLOCKED_ENV`。--### 0.1 实施结果总览--| 阶段 | 状态 | 证据摘要 |-|---|---|---|-| Phase A:P0 安全边界 | DONE | Runtime 严格同源、Renderer Token 隔离、Probe 工具禁用、结构化超时与回收测试通过 |-| Phase B:P0 启动与恢复 | DONE | Bootstrap 优先展示、Worker 迁移、Resolver、Capability、静态资源和 Renderer Ready 已实现并通过自动化 |-| Phase C:P1 可靠性与性能 | DONE | 通知确认语义、窗口写入合并、异步日志、诊断脱敏、有界输出、CORS 和深链接测试通过 |-| Phase D:P2 发布工程 | DONE / BLOCKED_ENV | 更新、Fuses、离线打包、构建清单、macOS packaged E2E、真实 Codex 和本地 OSV 已通过;Windows 与正式发布凭据待外部环境 |--本文后续任务级验收清单保留原始验收定义。最终状态和本轮命令证据以本节及 `docs/test-reports/opencreator-desktop-final-acceptance.md` 为准;未实际运行的平台项不得因代码已实现而视为 `PASS`。--## 1. 实施前复审结论--1. 原方案总体方向正确,但低估了开发代理、 Dashboard 空白页、通知重试、迁移 ABI、更新失败恢复和打包产物串用的复杂度。-2. Migration Worker 不再加载 `better-sqlite3`,统一使用 Electron 43 内置 Node 24 的 `node:sqlite`,避免新增运行时依赖和 Electron ABI 风险。-3. Capability 不新增独立 Store 服务,改为全进程共享同一个 Capability State 对象,并原地更新可热更新字段,降低改动面。-4. Dashboard 是否可用不能只依赖 `loadURL()` 成功,必须增加 Renderer 就绪握手,否则脚本缺失或首屏异常仍可能表现为空白页。-5. 通知不能固定拉取第一页,也不能展示后立即推进永久 cursor;必须使用循环扫描游标、展示待确认集合和系统通知稳定 ID。-6. 更新安装前不能提前销毁托盘;安装准备失败时必须恢复当前版本的 Runtime 和通知能力。-7. 500ms 启动目标保留为参考机性能目标,CI 使用独立硬门槛和相对回归门槛,避免不同机器性能差异造成假失败。-8. `pnpm audit` 的旧审计端点在 2026-07-16 返回 HTTP 410,发布门禁改用官方 OSV-Scanner 工作流,不把 registry 错误当成安全通过。-9. 每个任务主要控制在约 5 个文件;确实跨越启动协议或打包链路的任务标记为 `L`,并在检查点统一验证。-10. 完成本文全部任务后,才能重新声明 Desktop P0、P1、P2 已完成。--## 2. 目标与不变原则--### 2.1 整改目标--1. 修复 Runtime 代理跨 origin 后仍可能注入 Daemon Token 的严重漏洞。-2. 让 Codex Probe 技术上关闭 Shell、Exec 和其他非必要工具。-3. 修正 Probe、Daemon Host 和进程回收之间的超时预算与错误传播。-4. 保证 Bootstrap 先显示,再执行迁移、登录 Shell 读取和其他慢操作。-5. 保证 Dashboard 加载失败后有本地恢复界面,并且恢复不重复 Probe。-6. 修正系统通知展示失败仍被确认、失败项阻塞后续通知和 ACK 失败重复展示的问题。-7. 移除 Electron Main 高频同步磁盘 I/O、同步 Windows 进程回收和无界子进程输出。-8. 让 Capability 检测、自动更新、打包和跨平台验收符合真实运行状态。--### 2.2 保持不变的产品原则--1. OpenCreator 依赖用户本机 Codex CLI,不内置 Codex。-2. OpenCreator 不提供 Codex 登录页,不调用 `codex login status` 作为门禁。-3. 冷启动只通过一次真实最小 Codex 请求判断基础模型调用是否可用。-4. Probe 成功前不加载主 Dashboard 。-5. 页面刷新、项目切换、托盘恢复和 Daemon 自动恢复不重复 Probe。-6. Probe 不加载 OpenCreator Skills、Skill Market 或用户 MCP。-7. 生产 Renderer 和 Vite 同源代理页面都不获得 Daemon Token。-8. Daemon 继续监听 `127.0.0.1` 随机端口。-9. Web 开发服务器固定在 `127.0.0.1:9000`,并保持 `strictPort=true`。-10. 不新增登录、账号、API Key 或 Token 管理功能。--## 3. 整改前审查状态--下表记录 2026-07-16 实施前的审查基线,用于说明整改来源,不代表当前实现状态。整改后的结果以第 0.1 节和最终验收报告为准。--| 任务 | 当前结论 | 原因 |-|---|---|---|-| P0-B2 Codex 路径解析 | PARTIAL | 有效保存路径仍被登录 Shell 阻塞,2 秒目标不稳定 |-| P0-B3 Daemon Codex Probe | FAIL | Shell/Exec 工具未技术禁用,超时测试不足 |-| P0-B4 Daemon Bootstrap | PARTIAL | 完整 Capability 扫描阻塞 Runtime listen |-| P0-B5 Desktop DaemonManager | PARTIAL | Host 超时与 Probe 超时相同,错误码通过字符串拆分 |-| P0-B7 内部协议与 Bridge | FAIL | Runtime 代理存在跨 origin Token 泄漏风险 |-| P1-B1 窗口与托盘 | PARTIAL | 高频同步写窗口配置,Windows 进程回收会阻塞 Main |-| P1-B2 原生通知 | FAIL | 未等待系统通知成功展示就确认 outbox |-| P1-B3 深链接 | PARTIAL | 非法编码会被过滤后继续匹配,ID 校验不完整 |-| P1-B5 故障恢复与诊断 | PARTIAL | Dashboard 缺少 Renderer 就绪握手、本地错误页和最终脱敏 |-| P2-B1 生产打包 | PARTIAL | fresh package 容易受外部下载和旧产物选择影响 |-| P2-B2 自动更新 | PARTIAL/BLOCKED_ENV | 更新源依赖运行时环境变量,安装失败恢复和有序退出未验证 |-| P2-B3 Windows | BLOCKED_ENV | 代码路径存在,实机和完整自动化不足 |--只有对应任务的实现、自动化和要求的实机验收全部满足后,才能重新标记为 `DONE` 或 `PASS`。--## 4. 架构决策--### 4.1 Runtime 代理采用严格同源模型--1. Runtime 路由只匹配:- - `/.opencreator/runtime`- - `/.opencreator/runtime/...`-2. `/.opencreator/runtimeevil` 等前缀碰撞不得进入代理。-3. Daemon 地址只接受 `http://127.0.0.1:<有效端口>`,拒绝凭据、路径、查询、片段、`localhost` 和任意其他主机。-4. Runtime 子路径在原始值和解码值两个层面拒绝:- - `//`、`\\` 和混合网络路径。- - 反斜杠。- - 控制字符和空字节。- - 非法百分号编码。-5. 构建目标 URL 后必须再次断言 `target.origin === daemon.origin`。-6. Daemon Token 只能在最终断言通过后注入。-7. Electron Main 使用 Node 24 标准 `fetch` 并设置 `redirect: 'manual'`,不得自动跟随跨 origin 重定向。`net.fetch` 在 `protocol.handle` 内出现过无法稳定收敛的挂起,不再用于 Runtime 上游请求。-8. 请求体最多在 Main 中保留 10 MiB;先检查可信 `Content-Length`,再使用有界流读取,超过限制返回 `413`。-9. 缺失静态资源只对主文档导航执行 SPA fallback,缺失 JS、CSS、图片和 WASM 必须返回 `404`。--### 4.2 Vite 同源代理不向浏览器暴露 Token--1. `/.opencreator/runtime-config` 只返回 `{ baseUrl: '/.opencreator/runtime' }`。-2. Browser Bridge 接受同源配置中不存在 Token,但本地存储的直接 Daemon 配置仍要求 Token。-3. Vite 代理在服务端校验目标 origin 后注入 Token,并删除浏览器传入的 Authorization、Origin、Referer、Host 和 Connection。-4. Vite 代理应用与生产代理相同的网络路径和重定向限制。-5. Vite Daemon 启动 stdout/stderr 使用有界缓冲,解析出连接信息后不再无限累积。--### 4.3 Probe 使用技术工具隔离--在现有禁用项基础上增加:--```text---disable shell_tool---disable unified_exec---disable shell_snapshot-```--规则:--1. 固定 Prompt 继续要求不调用工具,但 Prompt 只作为语义约束。-2. 工具禁用参数才是安全边界。-3. 保留真实用户 provider、model、认证和必要环境变量。-4. 不使用 `--ignore-user-config`,避免破坏自定义 provider 和 model。-5. 如果目标 Codex 不支持必需禁用项,Probe 直接失败并显示真实参数错误,不降级为有工具 Probe。-6. Probe JSONL 出现 `command_execution`、`file_change`、MCP、Web Search、Computer Use、图片生成或其他工具调用事件时,返回 `CODEX_PROBE_TOOL_USED`。-7. `error`、`reasoning` 和 `agent_message` 等非工具事件不应误判。-8. 本机 Codex `0.144.4` 已通过真实 hello Smoke 并确认支持三个新增禁用项;其他版本仍以真实 Probe 结果为准。--### 4.4 超时预算分层并使用结构化错误--| 阶段 | 预算 |-|---|---:|-| Probe 总执行时间 | 45 秒 |-| Probe Spawn 首次活动 | 5 秒 |-| Probe SIGTERM 宽限 | 2 秒 |-| Probe 强杀后最终收敛 | 1 秒 |-| Daemon Runtime 启动余量 | 10 秒 |-| Desktop Host 总启动超时 | 60 秒 |-| Notification Runtime 请求 | 10 秒 |-| Notification `show/failed` 等待 | 3 秒 |--要求:--1. Probe 自己产生的结构化错误优先于 Host 通用超时。-2. Desktop 使用 `DaemonStartError` 等结构化错误,不再从 `"CODE: message"` 字符串拆分。-3. 超时测试允许注入缩短预算,不等待真实 45 秒。-4. Windows `taskkill.exe` 使用异步子进程并等待结果,不得在 Electron Main 中 `spawnSync`。-5. 强杀后仍未收到 close 时,Promise 必须按最终预算收敛,同时记录残留进程诊断。--### 4.5 Probe 冷启动性能修正--真实分段测试确认,旧实现的 `13.255s` 不是 hello 模型响应时间,而是整份用户 `config.toml` 引入项目授权、插件市场、Hooks、通知和更新检查等无关初始化后的完整 Codex 子进程生命周期。整改规则如下:--1. Probe Home 解析用户基础配置后只写入 model、选中 provider、认证路由、模型目录和请求兼容字段;启动 Probe 没有显式 Profile,不读取旧式顶层 `profile`、内联 `[profiles.*]` 或 `<name>.config.toml`。-2. 保留 `auth.json`、自定义 provider 完整表和 `model_catalog_json`;模型目录文件复制到临时 Home 后重写路径。-3. 不复制 `projects`、`plugins`、`marketplaces`、`hooks`、`features`、`mcp_servers`、`tui`、`desktop`、`notify` 等无关配置。-4. argv 额外覆盖 `notify=[]` 和 `check_for_update_on_startup=false`,防止未来白名单变化时重新引入这两项启动行为。-5. 成功和失败结果都记录 `homePreparationMs`、`firstEventMs`、`responseReceivedMs`、`processExitMs`。-6. 2026-07-16 macOS arm64 最终正式包真实 Smoke 为 `3048ms`:配置准备 `4ms`、首事件 `134ms`、回复 `2407ms`、退出 `3048ms`;刷新五次未重复 Probe。此前两个正式包样本分别为 `3052ms` 和 `4388ms`,差异来自真实 provider 响应波动,本地配置初始化和首事件保持稳定。--### 4.6 Bootstrap 先显示,迁移在 Worker 中执行--新的冷启动顺序:--```text-app.whenReady()- -> 初始化最小 Logger 和 Settings- -> 注册本地协议和 IPC- -> 创建 BrowserWindow- -> 加载并显示 Bootstrap- -> 并行预取登录 Shell 环境- -> 如需要,在 Worker 中迁移 Runtime 数据- -> 解析 Codex 路径- -> 启动 Daemon 和 Probe- -> Runtime listen- -> 加载 Dashboard 并等待 Renderer Ready-```--迁移规则:--1. Worker 文件位于 `apps/desktop/src/main/workers/`,自动进入现有 Main 编译和 `dist/main/**` 打包范围。-2. SQLite 校验使用 Electron 内置 `node:sqlite`,不加载 Daemon 的 `better-sqlite3`。-3. source、temporary、target 必须在规范化和 realpath 后不存在父子递归关系。-4. 拒绝符号链接、设备文件和其他特殊文件,避免迁移结果依赖源目录外部内容。-5. 正确判断源 Runtime 锁:只有 `ESRCH` 表示进程不存在,`EPERM` 等错误仍视为可能在用。-6. 以只读方式打开源 SQLite 并执行 `PRAGMA quick_check`。-7. 复制到 target 同级临时目录,再对复制后的 SQLite 执行 `PRAGMA quick_check`。-8. target 非空时保持现有 `TARGET_EXISTS` 行为;target 不存在或为空时使用同文件系统 rename 切换。-9. 失败时删除临时目录并恢复空 target 目录,源目录保持不变。-10. 当前版本只提供阶段状态和取消退出,不实现逐文件百分比进度,避免为一次性迁移引入额外协议。--### 4.7 Codex 路径和 Shell 环境分层解析--1. 立即检查手动路径、成功保存路径、普通保存路径和进程 `PATH`。-2. 登录 Shell 环境读取与 Bootstrap 展示、迁移并行执行。-3. 已找到有效快速候选时,登录 Shell 最多等待 2 秒,以补充 provider 所需环境;超时后使用进程环境并终止 Shell 进程组。-4. 没有快速候选时,允许登录 Shell 使用完整 5 秒硬超时。-5. Windows 继续使用 `where.exe` 和 `.cmd/.bat/.exe` 规则,不启动登录 Shell。-6. 所有超时子进程必须完成进程树回收。--### 4.8 Capability 使用单一共享状态对象--1. 命中有效指纹缓存时立即使用缓存,不重复阻塞启动。-2. 无缓存时,启动必需检测只包含:- - `codex --version`- - `codex exec --help`- - `codex exec resume --help`- - `codex app-server --help`-3. 四项并行执行,总等待上限 500ms;超时后使用保守矩阵启动 Runtime。-4. Runtime listen 后异步执行完整 Capability 扫描并原子写缓存。-5. 不新增重量级 Capability Store 类;`buildServer`、MCP Manager、Run Routes 和 Codex Status 共享同一个对象引用。-6. 完整扫描完成后原地更新允许热更新的字段,使 `/codex/status`、MCP 校验和图片能力读取新值。-7. `runtimeTransport`、resume transport 等不能安全热切换的决策在本次生命周期固定,下次启动使用新缓存。-8. 后台收集器支持取消,Daemon 关闭时回收仍在运行的 Codex help 子进程。--### 4.9 通知采用循环扫描和展示成功后确认--1. `NotificationManager.show()` 返回 `Promise<'shown' | 'failed' | 'unsupported'>`。-2. Electron `show` 事件表示成功;`failed`、构造异常、3 秒超时表示失败。-3. Notification 的 `id` 使用 outbox ID,相同通知重试时由系统更新同一个通知。-4. 保留 Notification 对象引用,直到 `show`、`failed`、`close` 或超时。-5. 维护 `shownAwaitingAck` 集合;ACK 失败时不重复展示,只重试 ACK。-6. 使用循环 `scanCursor`:- - 每轮读取一页未确认通知。- - 无论单项成功或失败都推进本轮 cursor。- - 到达空页后重置为 `0`,下一轮重试失败项。-7. 单项失败使用有界退避,不能阻塞同页和后续页通知。-8. Runtime 请求使用 AbortController,10 秒超时后释放消费锁。-9. `stop()` 终止当前请求并清理待处理 Notification。-10. 崩溃发生在系统展示成功但 ACK 前时仍属于至少一次语义;稳定 ID用于降低重复,不宣称跨崩溃严格 exactly-once。--### 4.10 Main I/O 和子进程内存必须有界--1. 窗口位置保存使用 300ms debounce,隐藏、关闭和退出前 flush。-2. Desktop Logger 使用串行异步队列;退出前显式 flush。-3. 高频 Daemon stderr 按固定窗口合并和限频。-4. 日志轮转在 macOS 和 Windows 上都能替换旧备份。-5. Desktop 和 Daemon 使用同等级脱敏规则。-6. 诊断导出前执行最终递归脱敏,并使用异步写文件。-7. Codex Runner stdout 仅保留最近 10,000 行或 4 MiB,stderr 仅保留最近 1 MiB。-8. App Server stderr 仅保留最近 1 MiB。-9. Codex Runner、App Server 和 Desktop Daemon 的未换行 frame 均设置上限,超限丢弃当前 frame 并记录截断。-10. 超限只影响诊断快照,不影响后续实时事件和最终 assistant/terminal 事件处理。--### 4.11 Dashboard 使用 Renderer Ready 握手--1. `loadURL()` 成功只表示主文档完成,不表示 React Dashboard 可用。-2. Web Renderer 首次挂载后通过 Preload 发送 `workspaceReady`。-3. Main 在加载 Dashboard 后等待固定握手超时;超时、主 frame 加载失败或 Renderer 崩溃都进入 `workspace_failed`。-4. 错误页只加载本地 Bootstrap 资源,提供:- - 重新加载 Dashboard 。- - 重启 Runtime。- - 导出诊断。- - 退出。-5. 重新加载 Dashboard 不重启 Daemon,不重复 Probe。-6. 重启 Runtime 复用已验证 Codex 指纹,不重复 Probe。-7. 错误页不得加载远程资源。--### 4.12 更新、打包和发布安全模型--1. 正式更新源固定为 GitHub Releases `wulien/opencreator-agent`,由 Electron Builder 生成 packaged update 配置。-2. 生产运行时不依赖 `OPENCREATOR_UPDATE_URL`;测试使用注入的 fake updater,必要的开发覆盖不得进入正式包。-3. Updater 使用显式状态机:--```text-idle -> checking -> available -> downloading -> downloaded- -> preparing_install -> installing- -> error-```--4. `checkForUpdates()` 和 `downloadUpdate()` Promise 必须捕获;`quitAndInstall()` 按同步调用捕获异常,并监听 updater `error` 事件。-5. 安装准备顺序:- - 阻止新的更新操作。- - 停止通知轮询。- - flush 窗口状态和日志。- - 有序停止 Daemon。- - 设置 `allowQuit`。- - 调用 `quitAndInstall()`。-6. 托盘在安装器真正接管前保持存在;准备失败时恢复 Runtime 和通知。-7. 正式包启用 Electron Fuses,至少关闭 RunAsNode、Node CLI inspect 和 NODE_OPTIONS,并启用 ASAR 完整性相关保护。-8. fresh package 必须生成构建清单,绑定 commit、dirty 状态、平台、架构、时间和包根目录。-9. verify 与 E2E 必须通过显式 package root 使用同一产物。-10. 依赖安全扫描使用官方 OSV-Scanner 工作流;任何例外必须记录 advisory、原因、负责人和到期时间。--## 5. 性能与可靠性预算--性能指标分为参考机目标和 CI 硬门槛。参考机数据每项至少运行 10 次,记录中位数和 P95;CI 同时检查绝对硬门槛和相对基线回归。--| 场景 | 参考机目标 | CI/可靠性硬门槛 |-|---|---:|---:|-| 应用入口到 Bootstrap `did-finish-load` | P95 不超过 500ms | 不超过 1000ms,且相对基线回归不超过 25% |-| 有效保存路径的 Codex 解析 | P95 不超过 2.2 秒 | 不超过 2.5 秒 |-| 无快速候选的登录 Shell 解析 | 不超过 5 秒 | 不超过 5.5 秒 |-| Probe 正常成功 | P95 不超过 8 秒 | 总执行硬超时 45 秒 |-| Probe 配置准备 | P95 不超过 50ms | 不超过 250ms |-| Probe 首个 JSON 事件 | P95 不超过 1 秒 | 由总超时兜底 |-| Desktop Host 总启动 | 60 秒 | 必须晚于 Probe 结构化错误 |-| Probe 成功到 Renderer Ready | P95 不超过 1.5 秒 | 不超过 3 秒 |-| 托盘恢复窗口 | P95 不超过 500ms | 不超过 1 秒 |-| 页面刷新恢复连接 | 不超过 2 秒 | Probe 计数不增加 |-| 窗口连续移动 5 秒 | 无同频磁盘写入 | 写入次数符合 300ms debounce |-| Runtime 代理请求体 | 最大 10 MiB | 超限返回 `413` |-| Notification Runtime 请求 | 10 秒 | 超时后释放消费锁 |-| Codex 输出内存快照 | 符合 4.9 节 | 不随总输出线性增长 |--性能测试必须记录 Main 内部时间戳,不能只使用 Playwright 进程启动耗时替代应用内部指标。--## 6. 实施任务--所有任务默认使用测试驱动方式:先增加可复现失败测试,再修改实现,最后运行任务级和检查点级验证。--### Phase A:P0 安全边界--#### Task A1:固定生产 Runtime 代理 origin 和请求体上限--**实现内容:**--1. 提取可测试的 Daemon origin、Runtime 路径和目标 URL 校验函数。-2. 使用精确前缀,拒绝网络路径、反斜杠、非法编码和非 `127.0.0.1` Daemon。-3. 只在最终同源断言后注入 Token,使用手动重定向。-4. 使用有界流读取请求体,超过 10 MiB 返回 `413`。--**验收标准:**--- [ ] `//attacker.example`、`\\attacker.example`、混合编码和前缀碰撞全部被拒绝。-- [ ] 攻击服务器未收到请求和 Authorization Header。-- [ ] JSON、二进制和 SSE 正常代理继续通过。-- [ ] 超限请求不会完整进入 Main 内存。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- runtime-proxy-pnpm --filter @opencreator/desktop e2e:package --grep "Runtime 代理"-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** 无。--**主要文件:**--- `apps/desktop/src/main/protocol-handler.ts`-- `apps/desktop/test/runtime-proxy.test.ts`-- `apps/desktop/e2e/desktop.spec.ts`-- `apps/desktop/test/protocol-path.test.ts`--**规模:** M。--#### Task A2:收紧 Vite 同源代理并移除浏览器 Token--**实现内容:**--1. 新增可测试的开发代理目标解析模块。-2. `runtime-config` 只返回同源 base URL。-3. Vite 服务端校验目标后注入 Token,并清理敏感请求头。-4. 限制开发 Daemon 启动输出缓冲。--**验收标准:**--- [ ] 浏览器无法从 `runtime-config` 获得 Token。-- [ ] Browser Bridge 可使用无 Token 的同源配置。-- [ ] 直接 Daemon 的本地存储配置仍要求 Token。-- [ ] 开发代理不能通过网络路径向其他 origin 发请求。--**验证:**--```bash-pnpm --filter @opencreator/web test -- dev-proxy-target browser-bridge-pnpm --filter @opencreator/web typecheck-pnpm --filter @opencreator/web build-```--**依赖:** 无。--**主要文件:**--- `apps/web/vite.config.ts`-- `apps/web/src/runtime/dev-proxy-target.ts`-- `apps/web/src/runtime/dev-proxy-target.test.ts`-- `apps/web/src/host/browser-bridge.ts`-- `apps/web/src/host/browser-bridge.test.ts`--**规模:** M。--#### Task A3:关闭 Probe Shell 和 Exec 工具--**实现内容:**--1. 增加 Shell、Unified Exec 和 Shell Snapshot 禁用参数。-2. Probe 解析 JSONL 并识别工具调用事件。-3. 工具事件返回稳定隔离错误。-4. 扩展 fake Codex 和 gated real smoke。--**验收标准:**--- [ ] argv 包含全部必需工具禁用项。-- [ ] fake Codex 模拟工具调用时 Probe 失败。-- [ ] 正常 assistant 响应仍成功。-- [ ] 真实 Smoke 的 JSONL 不包含工具调用事件。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- codex-probe-OPENCREATOR_RUN_REAL_CODEX_SMOKE=1 pnpm --filter @opencreator/desktop e2e:real-codex-```--**依赖:** 无。--**主要文件:**--- `apps/daemon/src/codex/probe-argv.ts`-- `apps/daemon/src/codex/probe.ts`-- `apps/daemon/test/unit/codex-probe-argv.test.ts`-- `apps/daemon/test/unit/codex-probe.test.ts`-- `apps/desktop/e2e/fixtures/fake-codex.mjs`--**规模:** M。--#### Task A4:重构 Probe、Host 超时和进程回收协议--**实现内容:**--1. 将 Probe、回收和 Host 预算定义为具名常量。-2. Host 默认超时调整为 60 秒。-3. 使用结构化错误传递 Probe 错误码。-4. Windows 进程树回收改为异步,并限制 Daemon 输出 frame。--**验收标准:**--- [ ] Probe 超时后输出 `CODEX_PROBE_TIMEOUT`,Host 不抢先失败。-- [ ] 工具调用输出 `CODEX_PROBE_TOOL_USED`。-- [ ] 超时后不存在可确认的残留 Codex 进程。-- [ ] Windows `taskkill` 不同步阻塞 Main。-- [ ] 普通 Daemon 启动超时仍映射为 `DAEMON_START_FAILED`。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- codex-probe codex-process-pnpm --filter @opencreator/desktop test -- daemon-manager-pnpm --filter @opencreator/desktop e2e:package --grep "Probe"-```--**依赖:** A3。--**主要文件:**--- `apps/daemon/src/main.ts`-- `apps/daemon/src/codex/probe.ts`-- `apps/desktop/src/main/daemon-manager.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/test/daemon-manager.test.ts`--**规模:** L。--### Checkpoint A:安全门禁--- [x] A1 至 A4 新增测试先失败后通过。-- [x] 生产和开发 Renderer 都无法获得或外带 Daemon Token。-- [x] Probe 技术上没有 Shell/Exec 工具。-- [x] Probe 错误在 Host 超时前稳定传递。-- [x] `pnpm test`、`pnpm typecheck` 通过。--### Phase B:P0 启动性能和恢复--#### Task B1:调整冷启动顺序并建立启动指标--**实现内容:**--1. 在迁移和 Shell 等待前加载 Bootstrap。-2. 增加 `migrating_data` 和 `workspace_failed` 状态。-3. 记录应用入口、窗口创建、DOM Ready 和 did-finish-load 时间戳。-4. 增加启动性能 E2E。--**验收标准:**--- [ ] 无迁移场景先显示 Bootstrap。-- [ ] Bootstrap 不展示 Skills、MCP 或登录状态。-- [ ] 参考机和 CI 指标按第 5 节分别判断。-- [ ] 指标来自 Main 内部时间戳。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- bootstrap-pnpm --filter @opencreator/desktop e2e:package --grep "启动性能"-```--**依赖:** Checkpoint A。--**主要文件:**--- `apps/desktop/src/main/main.ts`-- `apps/desktop/src/main/window-manager.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/src/bootstrap/main.ts`-- `apps/desktop/src/shared/types.ts`-- `apps/desktop/e2e/startup-performance.spec.ts`--**规模:** L。--#### Task B2:将 Runtime 数据迁移移出 Main--**实现内容:**--1. 新增 Main Worker 和消息协议。-2. 使用 `node:sqlite` 执行迁移前后 `quick_check`。-3. 增加路径关系、符号链接、锁和切换失败处理。-4. 应用退出时终止仍在运行的迁移 Worker。--**验收标准:**--- [ ] 20 MiB/5000 文件迁移期间 Main 仍可响应窗口事件。-- [ ] source 与 target 父子关系、符号链接和 SQLite 损坏均被拒绝。-- [ ] 迁移失败后源目录保持不变。-- [ ] packaged Worker 可加载 `node:sqlite`。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- data-migration-pnpm --filter @opencreator/desktop e2e:package --grep "数据迁移"-pnpm --filter @opencreator/desktop package-```--**依赖:** B1。--**主要文件:**--- `apps/desktop/src/main/data-migration.ts`-- `apps/desktop/src/main/workers/data-migration-worker.ts`-- `apps/desktop/test/data-migration.test.ts`-- `apps/desktop/e2e/desktop.spec.ts`--**规模:** L。--#### Task B3:实现 Codex 路径快速候选--**实现内容:**--1. 先验证 selected、successful、saved 和进程 PATH。-2. 登录 Shell 读取与其他启动工作并行。-3. 快速候选使用 2 秒环境合并预算,无候选使用 5 秒预算。-4. 完整回收慢 Shell 进程组。--**验收标准:**--- [ ] 有效保存路径配合慢 Shell 时不超过 2.5 秒硬门槛。-- [ ] 进程 PATH 无 Codex 时仍能通过登录 Shell 找到。-- [ ] Shell 超时没有残留进程。-- [ ] Windows `where.exe` 和 `.cmd/.bat/.exe` 行为不回归。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- codex-resolver-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** B1。--**主要文件:**--- `apps/desktop/src/main/codex-resolver.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/test/codex-resolver.test.ts`-- `apps/desktop/src/shared/types.ts`--**规模:** M。--#### Task B4:拆分启动 Capability 和完整 Capability--**实现内容:**--1. 增加启动必需 Capability 收集器和 500ms 总预算。-2. Runtime listen 后异步收集完整矩阵。-3. 共享同一 Capability State 引用并原地更新。-4. 使用异步原子方式写入指纹缓存。--**验收标准:**--- [ ] 冷缓存完整扫描不阻塞 Runtime listen。-- [ ] 慢 Codex help 在 500ms 后保守启动。-- [ ] 完整矩阵完成后 `/codex/status` 和可热更新校验读取新值。-- [ ] transport 本次生命周期不热切换。-- [ ] 下一次启动命中完整缓存。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- codex-capabilities startup-pnpm --filter @opencreator/daemon typecheck-```--**依赖:** A4。--**主要文件:**--- `apps/daemon/src/codex/capabilities.ts`-- `apps/daemon/src/main.ts`-- `apps/daemon/src/api/server.ts`-- `apps/daemon/test/unit/codex-capabilities.test.ts`-- `apps/daemon/test/unit/startup.test.ts`--**规模:** L。--#### Task B5:异步加载本地静态资源并收紧 SPA fallback--**实现内容:**--1. 静态资源改用异步 `stat/readFile`。-2. 只对主文档或无扩展路由执行 SPA fallback。-3. 缺失资源返回真实 `404` 和正确 MIME。-4. 保持现有 CSP 和静态路径逃逸防护。--**验收标准:**--- [ ] Dashboard 加载大量静态资源时不连续阻塞 Main。-- [ ] 缺失 JS/CSS 不再返回 `index.html`。-- [ ] 合法 hash 路由刷新仍进入 Dashboard 。-- [ ] 路径逃逸测试继续通过。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- protocol-path static-response-pnpm --filter @opencreator/desktop e2e:package --grep "静态资源"-```--**依赖:** A1。--**主要文件:**--- `apps/desktop/src/main/protocol-handler.ts`-- `apps/desktop/test/protocol-path.test.ts`-- `apps/desktop/test/static-response.test.ts`-- `apps/desktop/e2e/desktop.spec.ts`--**规模:** M。--#### Task B6:增加 Renderer Ready 握手--**实现内容:**--1. 新增 `workspaceReady` IPC。-2. Preload 暴露只写就绪信号,不暴露额外主进程能力。-3. Web 首次挂载后发送就绪信号。-4. Main 对 main-frame load、Renderer crash 和握手超时统一处理。--**验收标准:**--- [ ] 正常 Dashboard 在超时前完成握手。-- [ ] 缺失 bundle、Renderer 异常和未握手都进入失败状态。-- [ ] 非受信页面无法发送就绪 IPC。-- [ ] 重复就绪信号幂等。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- workspace-ready-pnpm --filter @opencreator/web test -- desktop-bridge-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** B1、B5。--**主要文件:**--- `apps/desktop/src/shared/ipc.ts`-- `apps/desktop/src/shared/types.ts`-- `apps/desktop/src/preload/index.ts`-- `apps/desktop/src/main/main.ts`-- `apps/web/src/main.tsx`--**规模:** M。--#### Task B7:增加 Dashboard 本地错误页和无 Probe 恢复--**实现内容:**--1. 在本地 Bootstrap 中增加 Dashboard 失败视图。-2. 增加仅重载 Renderer 的 IPC。-3. 复用现有无 Probe Runtime 重启。-4. 增加 packaged E2E 故障注入。--**验收标准:**--- [ ] Dashboard 资源缺失或握手超时时显示本地错误页。-- [ ] “重新加载 Dashboard”不改变 Daemon PID 和 Probe 计数。-- [ ] “重启 Runtime”不重复 Probe。-- [ ] 错误页可以导出诊断和退出。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- workspace-load-pnpm --filter @opencreator/desktop e2e:package --grep "Dashboard 加载失败"-```--**依赖:** B6、B4。--**主要文件:**--- `apps/desktop/src/main/window-manager.ts`-- `apps/desktop/src/main/bootstrap-controller.ts`-- `apps/desktop/src/bootstrap/main.ts`-- `apps/desktop/src/bootstrap/style.css`-- `apps/desktop/e2e/desktop.spec.ts`--**规模:** M。--### Checkpoint B:P0 主闭环--- [x] Bootstrap 性能符合参考机目标和 CI 门槛。-- [x] 首次迁移不阻塞 Main。-- [x] Probe 成功后在预算内完成 Renderer Ready。-- [x] 刷新五次 Probe 计数保持 1。-- [x] Dashboard 加载失败可恢复且不重复 Probe。-- [x] P0 打包 E2E 全部通过。--### Phase C:P1 可靠性、性能和诊断--#### Task C1:修正通知展示、扫描和确认语义--**实现内容:**--1. 注入 Notification 和 fetch 依赖,`show()` 返回展示结果。-2. 使用 outbox ID 作为系统 Notification ID。-3. 增加循环 scan cursor、`shownAwaitingAck` 和失败退避。-4. 增加请求超时和 stop 中止。--**验收标准:**--- [ ] `failed` 通知不被确认。-- [ ] ACK 失败不导致同一进程内重复展示。-- [ ] 长期失败项不阻塞后续通知。-- [ ] Runtime 请求挂起 10 秒后下一轮可以继续。-- [ ] 点击仍能打开 Thread、Run 和 Approval。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- notification-manager-pnpm --filter @opencreator/daemon test -- notification-```--**依赖:** Checkpoint B。--**主要文件:**--- `apps/desktop/src/main/notification-manager.ts`-- `apps/desktop/test/notification-manager.test.ts`-- `apps/desktop/e2e/desktop.spec.ts`--**规模:** L。--#### Task C2:窗口状态防抖和退出 flush--**实现内容:**--1. resize/move 使用 300ms debounce。-2. hide、close、before-quit 前 flush。-3. 最大化、恢复和显示器变化保持可见。-4. SettingsStore 支持可测试持久化适配器。--**验收标准:**--- [ ] 连续移动 5 秒不会产生同频磁盘写入。-- [ ] 退出前最后位置一定落盘。-- [ ] 最大化时保存正常窗口位置。-- [ ] 配置损坏时使用默认值且 Main 不崩溃。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- window-manager settings-store-```--**依赖:** Checkpoint B。--**主要文件:**--- `apps/desktop/src/main/window-manager.ts`-- `apps/desktop/src/main/settings-store.ts`-- `apps/desktop/test/window-manager.test.ts`-- `apps/desktop/test/settings-store.test.ts`--**规模:** M。--#### Task C3:统一 Desktop 脱敏和异步日志--**实现内容:**--1. 提取 Desktop redaction 模块,对齐 Daemon 规则。-2. Logger 使用串行异步队列、限频和可等待 flush。-3. Windows 轮转前安全替换旧 `.1`。-4. Daemon stderr 使用合并日志。--**验收标准:**--- [ ] JSON Token、环境变量、Bearer、`sk-*` 和 `occap_*` 均不落盘。-- [ ] 高频 stderr 不阻塞 Main。-- [ ] 日志轮转目标已存在时仍成功。-- [ ] graceful quit 等待日志 flush。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- logger redaction-```--**依赖:** Checkpoint B。--**主要文件:**--- `apps/desktop/src/main/logger.ts`-- `apps/desktop/src/main/redaction.ts`-- `apps/desktop/src/main/daemon-manager.ts`-- `apps/desktop/src/main/main.ts`-- `apps/desktop/test/logger.test.ts`--**规模:** L。--#### Task C4:诊断导出最终递归脱敏--**实现内容:**--1. 诊断 payload 在写入前递归脱敏。-2. 文件写入改为异步。-3. 增加嵌套对象、数组和混合字符串测试。--**验收标准:**--- [ ] 诊断导出不包含测试注入的任何 secret。-- [ ] Prompt、Token、路径中的非敏感信息按规则保留。-- [ ] 用户取消导出不写文件。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- diagnostics-```--**依赖:** C3。--**主要文件:**--- `apps/desktop/src/main/diagnostics.ts`-- `apps/desktop/src/main/redaction.ts`-- `apps/desktop/test/diagnostics.test.ts`--**规模:** S。--#### Task C5:限制 Codex 子进程内存和 frame--**实现内容:**--1. 新增通用有界文本、行和 frame buffer。-2. Runner stdout/stderr 改用有界缓冲。-3. App Server stderr 和未换行 stdout frame 增加上限。-4. 保持实时事件回调和最终事件识别。--**验收标准:**--- [ ] 超大 stdout/stderr 不造成线性内存增长。-- [ ] 无换行超大 frame 不造成线性内存增长。-- [ ] 最后的 assistant 和 terminal 事件仍能识别。-- [ ] 截断信息进入诊断元数据。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- bounded-buffer codex-runner codex-app-server-```--**依赖:** A3。--**主要文件:**--- `apps/daemon/src/codex/runner.ts`-- `apps/daemon/src/codex/app-server-runner.ts`-- `apps/daemon/src/codex/bounded-buffer.ts`-- `apps/daemon/test/unit/bounded-buffer.test.ts`-- `apps/daemon/test/integration/codex-runner.test.ts`--**规模:** L。--#### Task C6:收紧 CORS 和深链接输入--**实现内容:**--1. 默认只允许 `http://127.0.0.1:9000`。-2. Harness 和测试额外 origin 使用显式配置。-3. 深链接任一 path 或 query 编码失败时整体拒绝。-4. 拒绝控制字符、替换字符、空 ID 和超长 UTF-8 ID。--**验收标准:**--- [ ] 任意 localhost 高位端口默认不再获得 CORS Header。-- [ ] 固定 9000 origin 正常工作。-- [ ] 非法编码不能通过过滤后变成合法路由。-- [ ] 中文、空格和编码斜杠等合法 ID 继续工作。--**验证:**--```bash-pnpm --filter @opencreator/daemon test -- cors-pnpm --filter @opencreator/desktop test -- deep-link-```--**依赖:** A1、A2。--**主要文件:**--- `apps/daemon/src/api/server.ts`-- `apps/daemon/test/integration/api.test.ts`-- `apps/desktop/src/main/deep-link-manager.ts`-- `apps/desktop/test/deep-link-manager.test.ts`--**规模:** M。--### Checkpoint C:P1 完整体验--- [x] 通知成功、失败、超时、ACK 失败、循环扫描和点击均有自动化。-- [x] 窗口拖动没有同步写放大。-- [x] 日志和诊断脱敏测试通过。-- [x] Codex 输出和 frame 内存有明确上限。-- [x] CORS 和深链接边界测试通过。-- [x] 全仓测试、类型检查和构建通过。--### Phase D:P2 发布工程--#### Task D1:重构更新状态机和有序安装--**实现内容:**--1. Updater、Dialog 和安装协调器使用依赖注入。-2. 捕获 check、download、dialog 和 quitAndInstall 错误。-3. 安装前 flush 状态并停止 Daemon,托盘保持到安装器接管。-4. 准备失败时恢复 Runtime 和通知。-5. 正式更新源改为 GitHub Releases 配置。--**验收标准:**--- [x] 下载失败不产生未处理 Promise rejection。-- [x] 用户拒绝安装时当前任务不受影响。-- [x] 用户确认安装后 Daemon 先停止,安装器后启动。-- [x] 安装准备失败后当前版本继续可用。-- [x] dispose 后不残留 updater listener。--**验证:**--```bash-pnpm --filter @opencreator/desktop test -- updater-pnpm --filter @opencreator/desktop typecheck-```--**依赖:** Checkpoint C。--**主要文件:**--- `apps/desktop/src/main/updater.ts`-- `apps/desktop/src/main/main.ts`-- `apps/desktop/test/updater.test.ts`-- `apps/desktop/electron-builder.yml`-- `docs/operations/opencreator-desktop-release-runbook.md`--**规模:** L。--#### Task D2:启用 Electron Fuses 和正式包安全约束--**实现内容:**--1. 关闭 RunAsNode、Node CLI inspect 和 NODE_OPTIONS。-2. 启用 ASAR 完整性和只从 ASAR 加载应用代码。-3. 修改原生 SQLite 验证方式,不再依赖 packaged executable 的 `-e`。-4. verify 检查正式 Fuse 状态。--**验收标准:**--- [x] `ELECTRON_RUN_AS_NODE=1 OpenCreator -e ...` 不再执行任意 Node 代码。-- [x] packaged Daemon 仍能通过 Utility Process 加载 `better-sqlite3`。-- [x] app.asar 完整性和加载范围符合配置。-- [x] macOS arm64 打包 E2E 不回归。-- [ ] Windows 打包 E2E 待 Windows x64 CI 实际执行。--**验证:**--```bash-pnpm --filter @opencreator/desktop package-pnpm --filter @opencreator/desktop verify:package-pnpm --filter @opencreator/desktop e2e:package-```--**依赖:** D1。--**主要文件:**--- `apps/desktop/electron-builder.yml`-- `apps/desktop/scripts/verify-package.mjs`-- `apps/desktop/package.json`-- `apps/desktop/e2e/desktop.spec.ts`-- `docs/operations/opencreator-desktop-release-runbook.md`--**规模:** L。--#### Task D3:提高打包可重复性和依赖安全检查--**实现内容:**--1. 打包步骤增加阶段日志和子步骤超时。-2. `pnpm deploy` 强制锁文件,增加缓存完整时的 offline 路径。-3. Electron headers 和下载缓存路径显式配置。-4. 生成构建清单,并让 verify/E2E 接受同一个显式 package root。-5. CI 接入官方 OSV-Scanner `v2.3.8` 可复用工作流。--**验收标准:**--- [x] fresh package 清单记录 commit、dirty、时间、平台、架构和包根目录。-- [x] 依赖缓存完整时可以 offline 完成 Daemon prepare。-- [x] 打包卡住时在明确超时内失败。-- [x] verify 和 E2E 使用同一次构建产物。-- [x] OSV 2.3.8 对当前发布源码快照扫描无已知漏洞;CI 工作流仍需在 GitHub Actions 实际运行。--**验证:**--```bash-pnpm --filter @opencreator/desktop package-pnpm --filter @opencreator/desktop verify:package-OPENCREATOR_DESKTOP_PACKAGE_ROOT="<当前构建清单中的包根目录>" pnpm --filter @opencreator/desktop e2e:package-osv-scanner scan source --recursive .-```--**依赖:** D2。--**主要文件:**--- `apps/desktop/scripts/prepare-daemon.mjs`-- `apps/desktop/scripts/package-release.mjs`-- `apps/desktop/scripts/verify-package.mjs`-- `apps/desktop/e2e/desktop.spec.ts`-- `apps/desktop/package.json`-- `.github/workflows/desktop-release.yml`--**规模:** L。--#### Task D4:补齐 Windows 自动化和实机清单--**实现内容:**--1. Windows CI 执行 `.cmd/.bat/.exe`、`where.exe`、异步进程树和打包 E2E。-2. 增加 Windows 日志轮转、深链接参数、通知失败和更新退出测试。-3. 实机记录安装、覆盖升级、托盘、通知、协议和卸载数据保留。--**验收标准:**--- [ ] Windows x64 CI 生成并验证 NSIS 包。-- [ ] Windows E2E 使用构建清单指定产物。-- [ ] 正常退出、Probe 超时和 Daemon 异常后无残留进程树。-- [ ] 未签名和已签名结果在报告中明确区分。--**验证:**--```powershell-pnpm test-pnpm typecheck-pnpm desktop:release-$env:OPENCREATOR_DESKTOP_PACKAGE_ROOT = "<win-unpacked>"-pnpm --filter @opencreator/desktop e2e:package-```--**依赖:** D3。--**主要文件:**--- `.github/workflows/desktop-release.yml`-- `apps/desktop/e2e/desktop.spec.ts`-- `apps/daemon/test/unit/codex-process.test.ts`-- `docs/operations/opencreator-desktop-windows-release.md`--**规模:** L。--#### Task D5:重新执行最终验收并修订状态--**实现内容:**--1. 重新运行全仓测试、类型检查、构建、fresh package 和 Desktop E2E。-2. 运行真实 Codex Smoke。-3. 记录性能、Fuses、OSV 和跨平台结果。-4. 更新上游规格、发布手册和最终验收报告。--**验收标准:**--- [x] 每个 `PASS` 都有可定位的自动化或实机证据。-- [x] 未运行、跳过和环境缺失不能写成 `PASS`。-- [x] Critical、High 问题全部关闭。-- [x] P0、P1、P2 状态与任务实际结果一致。--**验证:**--```bash-pnpm test-pnpm typecheck-pnpm build-pnpm --filter @opencreator/desktop package-pnpm --filter @opencreator/desktop verify:package-pnpm --filter @opencreator/desktop e2e:package-OPENCREATOR_RUN_REAL_CODEX_SMOKE=1 pnpm --filter @opencreator/desktop e2e:real-codex-```--**依赖:** D1、D2、D3、D4。--**主要文件:**--- `docs/specs/2026-07-15-opencreator-desktop-app-host-design.md`-- `docs/test-reports/opencreator-desktop-final-acceptance.md`-- `docs/operations/opencreator-desktop-release-runbook.md`-- `docs/operations/opencreator-desktop-windows-release.md`--**规模:** M。--### Checkpoint D:发布候选--- [x] macOS fresh package、verify、E2E 和真实 Codex Smoke 使用同一份源码和产物。-- [ ] Windows 自动化通过,实机项按真实状态记录。-- [x] Electron Fuses 验证通过。-- [x] OSV 依赖安全扫描完成。-- [x] 性能预算有可复现报告。-- [x] 上游规格不再包含无证据的完成标记。--## 7. 测试矩阵--| 领域 | 单元测试 | 集成测试 | 打包 E2E | 实机 |-|---|---|---|---|---|-| 生产 Runtime origin 固定 | 必须 | 攻击服务必须 | 必须 | 不要求 |-| Vite Token 隔离 | 必须 | Vite 中间件必须 | 开发 Smoke | 不要求 |-| Probe 工具隔离 | 必须 | fake Codex | 真实 Smoke | 发布前一次 |-| 超时和进程回收 | 必须 | 必须 | 必须 | Windows 必须 |-| 数据迁移 | 必须 | Worker 集成 | 必须 | 大目录人工复验 |-| Codex Resolver | 必须 | 不要求 | 必须 | macOS/Windows |-| Capability 异步刷新 | 必须 | 必须 | 必须 | 不要求 |-| 静态资源和 Renderer Ready | 必须 | 必须 | 必须 | 不要求 |-| Notification show/failed/ACK | 必须 | Daemon outbox | fake/受控 | macOS/Windows |-| Window 和 Settings | 必须 | 不要求 | 必须 | macOS/Windows |-| Logger 和 Diagnostics | 必须 | 必须 | 必须 | 不要求 |-| 有界子进程输出 | 必须 | 大输出必须 | 不要求 | 不要求 |-| Updater | fake 必须 | 本地更新服务 | 必须 | 正式服务 |-| Electron Fuses | 脚本验证 | verify script | 必须 | 正式包 |-| 打包和原生 SQLite | 不适用 | verify script | 必须 | 干净机 |-| 依赖安全 | 不适用 | OSV CI | 发布门禁 | 不要求 |--## 8. 实施边界--### 必须执行--1. 每个任务先增加失败测试。-2. 每完成 2 至 3 个任务运行任务级测试,每个 Phase 结束运行完整 Checkpoint。-3. 保持 Browser 模式和固定 `9000` 端口不回归。-4. 保持用户已有未提交修改,不回退无关文件。-5. 所有文档和用户界面文案继续使用中文。-6. 所有新日志默认脱敏。-7. 不得用旧 package、旧报告或跳过项证明当前源码已通过。--### 实施前需要再次确认--1. 新增运行时第三方依赖。-2. 修改 SQLite schema。-3. 改变 Probe 45 秒产品超时。-4. 放弃对自定义 Codex provider 或 model 的兼容。-5. 改变“Probe 失败不能跳过”的产品原则。-6. 正式更新源不再使用 `wulien/opencreator-agent` GitHub Releases。-7. 因兼容原因不能启用计划中的 Electron Fuses。--### 禁止执行--1. 禁止向 Renderer 暴露 Daemon Token 简化代理。-2. 禁止在 Probe 失败后自动重复真实模型调用。-3. 禁止恢复启动时 Skills、MCP 或 Skill Market 全量加载。-4. 禁止通过放宽 CSP、IPC sender 校验或 CORS 解决兼容问题。-5. 禁止未运行测试就回填 `PASS`。-6. 禁止创建 Git Worktree。--## 9. 风险和缓解--| 风险 | 影响 | 缓解措施 |-|---|---|---|-| 旧 Codex 不认识工具禁用参数 | Probe 失败 | 展示真实参数错误,不降级为有工具 Probe;记录最低兼容范围 |-| Capability 原地更新误改固定 transport | 运行中 transport 不一致 | 明确区分热更新字段和生命周期固定决策,并增加测试 |-| `node:sqlite` Worker 行为跨平台差异 | 迁移失败 | packaged Worker smoke、只读 quick_check、失败保留源数据 |-| Worker 复制符号链接或特殊文件 | 数据越界或不可移植 | lstat 遍历并拒绝符号链接和特殊文件 |-| Renderer 页面加载成功但 React 未挂载 | 长时间空白 | Renderer Ready 握手和超时错误页 |-| Notification 事件平台差异 | 误确认或重复 | fake 单测、稳定 ID、循环扫描和双平台实机验收 |-| 更新安装准备失败 | Runtime 已停但应用未退出 | 托盘保留、状态回滚、无 Probe 恢复 Runtime |-| Electron Fuses 影响原有原生烟测 | verify 失败 | 改用 Utility Process/E2E 验证,不依赖 RunAsNode |-| 500ms 指标受 CI 抖动影响 | 假失败 | 参考机 P95、CI 绝对门槛和相对回归三者分离 |-| OSV 服务或网络不可用 | 无安全证据 | 发布任务失败并标记 BLOCKED_ENV,不能降级为 PASS |-| 打包依赖外部下载 | CI 长时间挂起 | 缓存、offline 路径、阶段超时和构建清单 |--## 10. 实施顺序--```text-A1 -> A2 -> A3 -> A4- -> Checkpoint A- -> B1 -> B2 -> B3 -> B4 -> B5 -> B6 -> B7- -> Checkpoint B- -> C1 -> C2 -> C3 -> C4 -> C5 -> C6- -> Checkpoint C- -> D1 -> D2 -> D3 -> D4 -> D5- -> Checkpoint D-```--允许在同一 Phase 内并行准备互不修改同一文件的测试,但合并和验证仍按上述顺序执行。--## 11. 方案确认门--开始实施前必须满足:--- [x] 用户确认本文的整改范围和优先级。-- [x] 用户确认旧 Codex 不支持必需禁用项时直接 Probe 失败,不降级为有工具模式。-- [x] 用户确认迁移 Worker 使用内置 `node:sqlite`,不新增运行时 SQLite 依赖。-- [x] 用户确认正式自动更新源使用 GitHub Releases `wulien/opencreator-agent`。-- [x] 用户确认正式包启用 Electron Fuses,并移除 RunAsNode 验证方式。-- [x] 用户确认性能采用“参考机目标 + CI 硬门槛 + 相对回归”三层标准。-- [x] 用户确认 P0 安全与启动整改完成前不继续维持“全部完成”的状态。-- [x] 实施者已确认每个任务都有验收、验证、依赖和文件范围。--本文已完成技术复审、用户确认、Task A1 至 D5 的仓库内实施和本机验收。未完成项仅限 Windows CI/实机、正式签名、公证、Gatekeeper、真实升级和正式通知点击,均已在最终验收报告中按 `BLOCKED_ENV` 或 `NOT_RUN` 记录。diff --git "a/docs/specs/OpenCreator-Codex-AppServer\345\205\274\345\256\271\344\270\216\347\234\237\345\256\236Agent\346\226\271\346\241\210-2026-08-21.md" "b/docs/specs/OpenCreator-Codex-AppServer\345\205\274\345\256\271\344\270\216\347\234\237\345\256\236Agent\346\226\271\346\241\210-2026-08-21.md"deleted file mode 100644index 2e23b235..00000000--- "a/docs/specs/OpenCreator-Codex-AppServer\345\205\274\345\256\271\344\270\216\347\234\237\345\256\236Agent\346\226\271\346\241\210-2026-08-21.md"+++ /dev/null@@ -1,839 +0,0 @@-# OpenCreator Codex App Server 兼容与真实 Agent 方案--> 日期:2026-08-21-> 版本:V3-> 状态:已批准-> 方案类型:复杂方案-> 目标 Codex 版本:`0.149.0`-> 关联方案:`docs/specs/OpenCreator模板化创作架构方案-2026-08-20.md`-> V1 Reviewer 原始结论:`BLOCKED`,原因是缺少用户需求原文、确认上下文和可枚举审核影响清单,未进入技术审核-> V2 Reviewer 原始结论:`REVISE`,提出 4 个 Major,无产品未决问题-> 流程结论:`PASS`,4 个 Major 已在 V3 按关闭条件修订-> 用户批准:2026-08-21,批准原话:`没问题,继续`--## 1. 文档目的--本方案解决四个已经明确的问题:--1. OpenCreator 升级并内置最新稳定 Codex,交互式 Agent 统一使用 `codex app-server`,不再把 `codex exec` 当作主链路。-2. 内置 Codex 与用户机器上已经安装的 Codex 完全隔离,不修改用户 PATH、全局配置、Skills 或凭据。-3. OpenCreator 右侧 Agent 接入真实 Codex Thread、Turn、Item 和工具调用,删除生产环境的 Demo、规则回答与假结果兜底。-4. 将容易误解的“OpenCreator MCP”重新定义为 Creator Tool Server:它是 OpenCreator 业务工具服务,MCP 只是 Codex 使用它的一种传输协议。--本方案继承上一份模板化创作方案中的产品定位、Creator Job、TemplateDefinition、Artifact、Activity 和 Stage 设计;当两份文档在 Codex Runtime、Agent 持久化、Creator Tool 或 KrillinAI 运行方式上冲突时,以本方案为准。--## 2. 用户需求原文与设计来源--以下原文按本轮方案形成顺序记录,用于让独立 Reviewer 判断是否发生需求漂移:--1. `其他的没问题,我就觉得skills的描述那一节我没看明白,模版和skills的关系到底是什么,skills是每次作为上下文全部传到底层的codex,还是写入到codex的skills里面,这个要讲清楚。还有就是Krillinai是一个golang服务,是每次都用cli调用,还是作为一个常驻的服务启动,让执行更快呢,这个也要考虑下。你还是画一个全局的架构图来讲解吧,每个部分都要想清楚`-2. `稳定 Skill 安装一次 -- 在什么时机安装呢,正常来说,用户肯定不会显示去处理,可能也看不懂什么是skill,其他方案没问题了`-3. `功能可以分不同阶段,P0确实可以先从最小的开始验证,但是其他阶段的方案也要一起出出来,方便后续指导开发,没问题,继续吧`-4. `codex昨天有重大更新,OpenCreator底层用的就是codex的cli,你再分析下最新的codex开源代码,我看是有app-server和sdk一整套的harness开源,分析下对OpenCreator的影响`-5. `1. 目前OpenCreator全部依赖的就是codex cli,这次codex更新的app-server,sdk等继续放弃不用,还是只用codex cli吗`-6. `2. OpenCreator MCP 这一层很容易让人误解,这不应该是Codex runtime封装层吗`-7. `3. 把Codex当做安装包安装进OpenCreator,如果机器本身就有Codex了,会不会冲突`-8. `1. 需要升级Codex到最新版本,按照最新的开源代码架构设计OpenCreator的兼容方案,我理解是不是统一用Codex cli的app server`-9. `2. OpenCreator支持将Codex打包进去,就是你讲的方案,和本机已安装的Codex不冲突。`-10. `3. 让OpenCreator的Agent能真正运行起来,不要再运行demo了,也不存在兜底用demo的mock数据,这是一个完整的功能。`-11. `4. Creator Tool Server就按你的建议去设计。`-12. `给出完整的设计方案,使用 $zhiyu-brainstorm 去完成`--四段设计分别在完整内容展示后由用户确认:--| 顺序 | 展示内容 | 紧随其后的用户确认 |-| --- | --- | --- |-| D-1 | 总体边界与技术选型 | `没问题,继续` |-| D-2 | Codex Runtime 打包、版本和兼容 | `没问题,继续` |-| D-3 | 真实 Agent 与 Creator Tool Server | `没问题,继续` |-| D-4 | 迁移、异常、测试与验收 | `没问题,继续` |--## 3. 独立审核包--### 3.1 审核类型--V1 因审核输入不完整得到 `BLOCKED`,没有产生技术结论;V2 补齐审核基线后完成技术审核,原始结论为 `REVISE`;V3 按四个 Major 的关闭条件完成修订,并保留全部原始结论。--### 3.2 直接影响清单--| 范围 | 当前直接证据 |-| --- | --- |-| Codex Host 与事件 | `apps/daemon/src/codex/app-server-host-2026-07-28.ts`、`apps/daemon/src/runs/persistent-app-server-executor-2026-07-28.ts`、`apps/daemon/src/codex/app-server-runner.ts` |-| Creator Agent | `apps/daemon/src/creator/agent/codex-adapter.ts`、`apps/daemon/src/creator/agent/agent-service.ts`、`apps/daemon/src/api/routes.creator.ts` |-| Creator 状态与调度 | `apps/daemon/src/creator/service.ts`、`repository.ts`、`stage-runner.ts`、`apps/daemon/src/storage/migrations.ts`、`packages/protocol/src/creator.ts` |-| Creator Tool | `apps/daemon/src/agent-tools/creator-tools.ts`、`mcp-routes.ts`、`internal-routes.ts`、`capability-token.ts` |-| Web 双侧交互 | `VideoTranslationWorkspace.tsx`、`VideoTranslationAgentPanel.tsx`、`CreatorAgentPanel.tsx`、`creator-session-store.tsx`、`creator-sse.ts` |-| Desktop Runtime 打包 | `apps/desktop/src/main/codex-resolver.ts`、`daemon-manager.ts`、`bootstrap-controller.ts`、`electron-builder.yml`、`scripts/package-release.mjs`、`scripts/verify-package.mjs` |-| KrillinAI | `KrillinAI/internal/cli/commands.go`、`internal/router/router.go`、`internal/service/subtitle_service.go`、`internal/pipeline/manifest.go`、`apps/daemon/src/creator/krillin/*` |-| 最新 Codex 协议 | `codex/codex-rs/app-server/README.md`、`codex/codex-rs/app-server-protocol/schema/typescript/v2/*`、稳定标签 `rust-v0.149.0` |-| 直接测试 | `apps/daemon/test/unit/creator-*.test.ts`、`apps/daemon/test/integration/creator-api.test.ts`、`apps/desktop/test/codex-resolver.test.ts`、`creator-runtime-package.test.mjs`、`apps/desktop/e2e/creator-packaged-app.spec.ts`、`apps/web/e2e/web-desktop-parity.spec.ts` |--关键协议核验命令:--```powershell-git -C codex show rust-v0.149.0:codex-rs/app-server/README.md-git -C codex show rust-v0.149.0:codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts-git -C codex show rust-v0.149.0:codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts-git -C codex show rust-v0.149.0:codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts-```--### 3.3 审核排除项--1. 不审核内容发布、平台上传、审批发布和发布数据分析。-2. 不审核多人实时协作、CRDT、组织权限和云端多租户部署。-3. 不要求本方案阶段实现 Claude Code Adapter,只审核替换边界是否成立。-4. 不把 P3 功能尚未实现视为当前代码缺陷,但审核其方案是否可继续指导开发。-5. 不审核与 Creator、Codex Runtime、安装包和 KrillinAI 无直接关系的旧功能。--## 4. 用户确认记录--| 设计部分 | 已确认决定 | 用户确认原话 |-| --- | --- | --- |-| D-1 总体边界与技术选型 | 内置 Codex CLI;交互式 Agent 统一使用 app-server;Creator Core 是业务状态源;Creator Tool Server 是业务工具层;生产环境禁止 Demo 兜底。 | `没问题,继续` |-| D-2 Codex Runtime 打包、版本和兼容 | 固定 Codex `0.149.0`;使用绝对路径和隔离 `CODEX_HOME`;默认不读取本机 Codex;按 scope 管理常驻 Host;升级可回滚。 | `没问题,继续` |-| D-3 真实 Agent 与 Creator Tool Server | Agent 由 Creator 状态、Activity 和 Codex 对话共同组成;REST 与 Agent Tool 共用 Command Dispatcher;模板、上下文和 Skill 分层;历史持久化恢复。 | `没问题,继续` |-| D-4 迁移、异常、测试与验收 | 按 Runtime、同步、真实视频流程、模板扩展分阶段实施;失败不得伪造成成功;必须完成真实安装包和恢复测试。 | `没问题,继续` |--## 5. 事实基线--### 5.1 Codex--1. 本地 Codex 源码位于 `codex/`,当前检出的提交为 `d8ec270183ffb341fb0211c5ee8335419ea67cc7`。-2. 2026-08-21 可采用的最新稳定版本为 `0.149.0`;`0.150.0-alpha` 和源码 `main` 不进入正式安装包。-3. 稳定标签 `rust-v0.149.0` 对应提交 `758ef40f50c1a458425c7cfbf1eb12cbc07af0b0`;协议生成和兼容测试必须基于该标签,而不是当前 `main`。-4. app-server 已提供稳定的 JSON-RPC 主链路,包括:- - `initialize`- - `account/read` 与登录流程- - `model/list`- - `skills/list`、`skills/extraRoots/set`- - `thread/start`、`thread/resume`、`thread/read`- - `turn/start`、`turn/steer`、`turn/interrupt`- - Thread、Turn、Item、审批和工具调用通知-5. 仓库中普通 Agent 已存在较早的 app-server Host 和持久执行器实现,但 Creator Agent 仍按 Turn 临时启动 app-server,且历史主要保存在内存中。--### 5.2 OpenCreator--1. `apps/daemon/src/creator/agent/codex-adapter.ts` 仍是 Creator Agent 的临时适配实现。-2. `apps/daemon/src/creator/agent/agent-service.ts` 使用进程内 `Map` 保存消息和运行状态,Daemon 重启后无法恢复。-3. `VideoTranslationAgentPanel` 仍包含本地消息、字符串意图识别、固定回答或演示结果路径。-4. Creator Tool 已能调用 CreatorService,但 REST、工具调用和 Stage 调度之间仍存在行为分叉风险。-5. Desktop 当前优先发现本机 Codex,安装包尚未形成固定版本、哈希、Schema 和隔离 Home 的完整合同。--### 5.3 KrillinAI--1. KrillinAI 是媒体能力提供方,OpenCreator 是业务编排与状态所有者。-2. 当前 KrillinAI CLI 能力比既有 HTTP Server 完整;既有 Server 的内存任务、全局配置和恢复能力不足以直接作为正式 OpenCreator 服务合同。-3. 正式目标是补齐并托管一个本地常驻 KrillinAI 服务;在该合同完成前,CLI 只能作为真实阶段执行的迁移适配器,不能返回 Demo 结果。--## 6. 目标与非目标--### 6.1 目标--1. Agent 可以连续对话、调用 Creator Tool、接收流式事件、处理中断和审批,并在重启后恢复。-2. 工作台和 Agent 是同一个 Creator Job 的两个入口,双方读取同一状态源,而不是互相复制两套状态。-3. 工作台操作会立即在 Agent 区域形成状态变化或 Activity,但不会因此自动消耗一次 Codex Turn。-4. Agent 通过 Creator Tool 修改 Job 后,工作台通过同一 Creator 事件通道立即更新。-5. 视频下载、字幕、翻译、TTS 和渲染返回真实任务、进度、错误和 Artifact。-6. Codex、Creator Tool Server、KrillinAI 和 AI Provider 的边界清晰,可独立升级和诊断。--### 6.2 非目标--1. 不建设另一套通用 Agent Harness;Codex app-server 已经承担 Agent loop。-2. 不让 Codex Thread、Skill、聊天消息或 KrillinAI Task 成为 Creator Job 的业务状态源。-3. 不在 P0 引入消息队列、事件溯源、CRDT、微服务集群或多用户协同协议。-4. 不默认复用用户全局 Codex 配置、MCP、Skills、凭据或本机未知版本二进制。-5. 不把 Codex 登录凭据转换成 KrillinAI 所需的 OpenAI-compatible API Key。-6. 不保留生产 Demo Agent、规则 Agent、固定回复或假 Artifact 作为“容错”。--## 7. 核心原则--1. **一个业务状态源**:Creator Core 是 Job、revision、Stage、Artifact 和 Activity 的唯一权威。-2. **一个交互式 Agent 主链路**:所有 OpenCreator 交互式 Agent 使用 app-server;`codex exec` 只保留给独立、非交互、无需恢复的后台任务或兼容工具。-3. **一个业务命令入口**:工作台 REST Action 和 Agent Tool Action 最终都进入 Creator Command Dispatcher。-4. **状态共享,不做双向复制**:工作台和 Agent 订阅同一个 Snapshot 与事件流,不设计两边互相通知和合并。-5. **模板高于 Runtime**:模板属于 OpenCreator;Skill 只描述某个 Runtime 可复用的操作知识。-6. **真实失败优于假成功**:Runtime、Provider 或媒体服务不可用时明确失败,不降级为 Demo 数据。-7. **版本固定、协议生成、升级可退**:安装包绑定 Codex 版本、二进制哈希和生成 Schema。--## 8. 全局架构--下面的图只表达“谁拥有状态、谁负责执行”,箭头不代表复制数据:--```text-┌──────────────────────────── OpenCreator UI ────────────────────────────┐-│ │-│ 左侧工作台 右侧 Agent │-│ 编辑参数、字幕、产物 状态摘要 + Activity + Codex 对话 │-│ │ │ │-│ └────────── 共同订阅 Creator Snapshot / Events ──────────────┘-└───────────────────────────────────┬────────────────────────────────────┘- │ HTTP + SSE-┌──────────────────────── OpenCreator Daemon ────────────────────────────┐-│ │ │-│ Creator API ───────┐ │ ┌─ Agent API │-│ ▼ ▼ ▼ │-│ Creator Command Dispatcher │-│ │ │-│ ▼ │-│ Creator Core:Job / revision / Stage / Artifact / Activity / Template│-│ │ │ │-│ │ └──── Stage Runner ─── Krillin Host │-│ │ │ │-│ │ ▼ │-│ │ KrillinAI 常驻服务 │-│ │ │-│ └──── Agent Context Projection │-│ │ │-│ ▼ │-│ Codex Runtime Adapter │-│ │ JSON-RPC │-│ ▼ │-│ 内置 codex app-server Host │-│ │ MCP / Tool Call │-│ ▼ │-│ Creator Tool Server │-│ │ │-│ └──── 回到 Creator Command Dispatcher │-└────────────────────────────────────────────────────────────────────────┘-```--这个结构中没有“工作台状态”和“Agent 状态”两套业务数据。右侧 Agent 只是把三类数据组合展示:--1. Creator Job 当前快照。-2. Creator Activity 时间线。-3. Codex Thread/Turn/Item 对话记录。--## 9. 模块职责--| 模块 | 唯一职责 | 明确不负责 |-| --- | --- | --- |-| Desktop Bootstrap | 定位应用资源、启动 Daemon、展示启动诊断 | 不实现 Creator 业务 |-| Codex Runtime Manager | 校验、启动、复用、回收和升级内置 Codex Host | 不保存 Creator Job |-| Codex AppServer Host | 维护一个 app-server 子进程和 JSON-RPC 连接 | 不解释模板或直接调用 KrillinAI |-| Codex Runtime Adapter | 将 OpenCreator AgentContract 映射到 app-server 方法和事件 | 不持有业务状态 |-| Agent Service | 管理 Creator Job 与 Codex Thread 的映射、Turn 和展示历史 | 不伪造回答 |-| Creator Core | 持有模板、Job、revision、Stage、Artifact、Activity | 不执行 Codex Agent loop |-| Creator Command Dispatcher | 统一校验并提交 Creator Action | 不区分调用来自 UI 还是 Agent |-| Creator Tool Server | 向 Runtime 暴露稳定的业务工具 | 不等同于 Codex Runtime 封装层 |-| Stage Runner | 将 Creator Stage 映射到媒体执行器并登记结果 | 不允许 Agent 绕过 Creator Core |-| Krillin Runtime Host | 托管 KrillinAI 服务进程、健康检查和重启 | 不决定模板流程 |-| Provider Config Store | 保存文本、ASR、TTS、图片、视频和代理配置 | 不把密钥写入 Agent 上下文 |--## 10. Codex Runtime 设计--### 10.1 打包目录--建议安装包结构:--```text-resources/- runtime/- codex/- manifest.json- schema/- app-server.schema.json- app-server.types.ts- win32-x64/codex.exe- darwin-arm64/codex- linux-x64/codex- opencreator-skills/- opencreator-runtime/SKILL.md-```--`manifest.json` 至少包含:--```ts-type BundledCodexManifest = {- version: '0.149.0';- protocolSchemaVersion: string;- platform: string;- arch: string;- sha256: string;- sourceCommit: string;- builtAt: string;-};-```--正式构建只打包当前平台对应二进制,不在用户机器上执行全局安装。--### 10.2 隔离规则--1. 通过安装包绝对路径启动,例如 `<resources>/runtime/codex/win32-x64/codex.exe app-server`。-2. 设置独立 `CODEX_HOME=<OpenCreatorUserData>/runtime/codex/home`。-3. 不修改 PATH,不调用 `npm install -g`,不覆盖用户全局 Codex。-4. 默认不复制 `~/.codex/config.toml`、凭据、MCP 或 Skills。-5. 本机 Codex 继续由用户在终端独立使用,两者进程、Home 和升级互不影响。-6. 内置 Runtime 失败时不搜索 PATH 兜底。-7. 外部 Codex 只能在高级设置中显式启用,并在启用前完成版本和协议检查。--### 10.3 启动检查--Runtime Manager 按顺序执行:--1. 校验 manifest、平台、架构和二进制 SHA-256。-2. 读取 `codex --version`,必须与兼容矩阵匹配。-3. 启动 `codex app-server` 并完成 `initialize`。-4. 调用 `model/list`、`skills/list`、`account/read`。-5. 调用 `skills/extraRoots/set` 加载应用内置 Skill 根目录。-6. 将结果写入 Runtime Readiness,不把未登录误报成二进制损坏。--### 10.4 Host 范围与生命周期--Runtime Manager 维护两种 scope:--```text-project:<projectId> 普通项目 Agent-creator-job:<creatorJobId> 创作工作台 Agent-```--规则如下:--1. 同一 scope 复用一个 Host,避免每次 Turn 重启 app-server。-2. Host 可以恢复多个 Thread,但同一 Host 同时只允许一个活动 Turn;Runtime Manager 对同 scope 的 Turn 串行排队。Creator Job 默认映射一个主 Thread。-3. Host 启动时通过现有 Capability Token Store 的 `issueProcess` 创建一个固定 Process Capability Lease,并把进程 Token 注入 Creator MCP Server 环境。Token 不随 Turn 替换。-4. 每个 Turn 调用 `turn/start` 前,使用 `activate` 将该 Lease 临时绑定到 `runId`、`threadId`、`creatorJobId` 和最小 scopes;Turn 进入任一终态后立即 `deactivate`。-5. 未激活、已停用、过期、Job 不匹配或 scope 超出的 Creator Tool 请求必须被拒绝。Host 关闭或 Daemon 重启时 `revoke` 旧 Lease,并为新进程生成新 Token。-6. Turn 运行期间 Host 不得被空闲回收。-7. 空闲 Host 超过阈值后优雅关闭;上限到达时只回收最久未使用且没有活动 Turn 的 Host。-8. Host 崩溃后自动重启一次,并对已持久化的 Codex Thread 执行恢复对账;未确认完成的 Turn 不自动重新提交。-9. MCP URL、命令、工具集合或启动配置发生变化时必须重启 Host。`config/mcpServer/reload` 只用于实际写入隔离 `config.toml` 的配置变化,不用于刷新启动参数或进程环境。--### 10.5 版本和 Schema--1. 每个 OpenCreator 版本只声明一个默认 Codex 版本和一组经过测试的兼容版本。-2. TypeScript 协议类型从固定 Codex 源码生成并提交,不手写宽泛 `any` 协议。-3. app-server 未知通知可以记录并忽略;已使用字段缺失、类型不兼容或关键方法缺失必须使 Readiness 失败。-4. Codex 升级随 OpenCreator 发布,先写入新版本目录,校验成功后原子切换 active manifest。-5. 保留上一个已验证版本;新版本启动检查失败时回滚并记录诊断。--## 11. 真实 Agent 设计--### 11.1 Runtime Adapter--OpenCreator 内部只依赖以下接口:--```ts-interface AgentRuntimeAdapter {- startOrResumeThread(input: StartThreadInput): Promise<RuntimeThread>;- startTurn(input: StartTurnInput): Promise<RuntimeTurn>;- steerTurn(input: SteerTurnInput): Promise<void>;- interruptTurn(input: InterruptTurnInput): Promise<void>;- subscribeEvents(scopeId: string, listener: AgentEventListener): Unsubscribe;- readHistory(threadId: string): Promise<RuntimeHistory>;- closeScope(scopeId: string): Promise<void>;-}-```--CodexAdapter 分别映射到 `thread/start|resume|read`、`turn/start|steer|interrupt` 和 app-server 通知。未来 Claude Code Adapter 可以实现同一个接口,无需修改 Creator Core、模板和工作台。--### 11.2 持久化模型--新增或补齐:--```text-creator_agent_sessions- id, creator_job_id, runtime, runtime_thread_id,- host_scope, process_generation, status, last_turn_id,- created_at, updated_at--creator_agent_turns- id, session_id, runtime_turn_id, client_message_id,- status, input_summary, error_code, started_at, finished_at--creator_agent_items- id, turn_id, runtime_item_id, seq, kind,- payload_json, created_at, completed_at--creator_agent_events- id, session_id, turn_id, seq, type,- payload_json, created_at--creator_agent_approvals- id, session_id, turn_id, runtime_request_id,- process_generation, status, payload_json,- created_at, resolved_at--creator_command_receipts- id, job_id, idempotency_key, request_hash,- status, receipt_json, error_json, stage_run_id,- created_at, completed_at-```--Creator Agent 的 `Map` 只能作为活动连接缓存,不能再承担历史真相源。--约束:--1. `creator_agent_items` 对 `(turn_id, runtime_item_id)` 建唯一约束;事件使用可重放序号或稳定事件键去重。-2. `creator_command_receipts` 对 `(job_id, idempotency_key)` 建唯一约束。-3. approval 保存 app-server 请求 ID 和 `process_generation`;请求只能回写给仍存活且 generation 相同的 Host。--### 11.3 消息执行流程--```text-1. 用户在右侧 Agent 输入消息。-2. Web 先 flush 当前工作台草稿,确保 Creator revision 已提交。-3. Agent Service 读取最新 Job 并生成 Context Projection。-4. Adapter 通过 `thread/start` 或 `thread/resume` 启动/恢复 Creator Job 对应 Codex Thread,并在该 Thread 设置强制 `developerInstructions`。-5. Adapter 调用 `turn/start`,只在用户输入中传入本轮消息和动态 Creator Context Projection;`TurnStartParams` 不承载 `developerInstructions`。-6. app-server 流式返回 Turn、Item、工具、审批和文本事件。-7. Agent Event Normalizer 持久化事件,并通过现有 Creator SSE 通道推送给 Web。-8. Creator Tool Call 进入 Creator Command Dispatcher;成功后产生新 revision 和 Activity。-9. 工作台与 Agent 同时收到新的 Creator Snapshot/Events。-10. turn/completed 后保存最终状态;失败或取消同样保存终态和结构化错误。-```--### 11.4 事件归一化--UI 不直接依赖 Codex 原始 JSON-RPC。Daemon 将其转换为稳定事件:--```ts-type OpenCreatorAgentEvent =- | { type: 'turn.started'; turnId: string }- | { type: 'message.delta'; itemId: string; text: string }- | { type: 'message.completed'; itemId: string; text: string }- | { type: 'tool.started'; itemId: string; name: string; input: unknown }- | { type: 'tool.completed'; itemId: string; output: unknown; isError: boolean }- | { type: 'approval.required'; requestId: string; action: unknown }- | { type: 'usage.updated'; usage: unknown }- | { type: 'turn.completed'; turnId: string }- | { type: 'turn.failed'; turnId: string; code: string; message: string }- | { type: 'turn.canceled'; turnId: string };-```--原始事件可以作为脱敏诊断记录保留,但不得成为 Web 协议。--### 11.5 重启对账与审批恢复--页面刷新和进程崩溃采用不同语义:--1. **仅页面刷新**:Daemon 和 app-server 仍存活。Web 从 SQLite/SSE replay 恢复对话,并从审批 API 读取当前 generation 的 pending approval;用户仍可对原 JSON-RPC 请求作答。-2. **Daemon 或 app-server 重启**:旧 JSON-RPC 连接和 approval request ID 已失效。所有旧 generation 的 pending approval 标记为 `expired`,禁止向旧 request ID 回写。-3. 新 Host 启动后先调用 `thread/read({ includeTurns: true })`,用稳定 Thread/Turn/Item ID 与本地数据库对账并幂等补齐已完成事件,再调用 `thread/resume` 恢复后续对话。-4. 若远端历史表明 Turn 已完成或失败,本地补齐对应终态;若本地仍为 `running` 或 `waiting_approval` 且无法从存活 Host 证明仍在运行,则转为 `interrupted`。-5. 只有同一存活 Host 明确报告活动 Turn 时才重新订阅该 Turn;进程死亡后不尝试恢复旧审批或自动重放旧 Turn。-6. 用户可以基于已恢复 Thread 发起一个新 Turn 继续,但该动作必须是显式提交,并使用新的 `clientUserMessageId` 和命令幂等键。--专项验收必须覆盖:页面刷新后继续审批、Daemon 重启、app-server 在审批中崩溃、重复 Item/Event 回放,以及不存在永久 `waiting_approval` 或 `running`。--### 11.6 快捷动作--右侧快捷入口必须区分两类:--1. **确定性 Creator Action**:例如“重新生成字幕”“切换竖屏”“撤销上次字幕修改”。直接执行 Dispatcher,可在 Activity 中显示“由用户从 Agent 面板触发”,但不伪装成 Codex 回答。-2. **真实 Agent Turn**:例如“把字幕改得更口语化”“根据当前视频给三种封面方向”。必须启动真实 Turn,并展示真实工具调用和结果。--## 12. 工作台与 Agent 的共享状态--### 12.1 同步模型--不采用“左侧通知右侧、右侧再通知左侧”的双向消息复制。两侧共享以下服务端数据:--```text-Creator Snapshot = Job + revision + current Stage + Artifact 摘要-Creator Activity = 已提交的语义操作记录-Agent Conversation = Codex Thread/Turn/Item-```--前端 CreatorSessionStore 是这些数据在当前页面的缓存和草稿层,Creator Core 才是持久权威。--### 12.2 工作台操作规则--| 操作 | Creator 状态 | Agent 区域表现 | 是否启动 Codex |-| --- | --- | --- | --- |-| 输入字幕文字 | 实时更新本地草稿,短 debounce 提交 | 状态摘要更新;聚合后产生一次 Activity | 否 |-| 修改语言、比例或音色 | 提交 Action 和新 revision | 显示一条结构化 Activity | 否 |-| 启动翻译或渲染 | 创建 StageRun | 显示任务开始与进度 | 否 |-| 选择 Artifact | 更新当前关注项 | Agent Context 的当前选择变化 | 否 |-| 向 Agent 提问 | flush 草稿并启动 Turn | 显示真实 Codex 对话 | 是 |--Activity 必须按 `actionId` 去重。类似“左侧工作台设置已同步”的重复提示属于同一操作被多次消费,最终实现必须通过服务端事件 ID 和前端已应用序号消除。--### 12.3 revision 冲突--所有修改携带 `expectedRevision`:--1. revision 匹配:原子提交并返回新 revision。-2. 首次冲突:Agent 重新读取 Creator Context,并最多重试一次。-3. 第二次冲突:停止自动写入,Turn 进入 `needs_user_resolution`,展示冲突字段和最新值。-4. UI 冲突:保留用户草稿,提示刷新后的差异,不直接覆盖。--## 13. Creator Tool Server--### 13.1 定位--Creator Tool Server 是 OpenCreator Daemon 内的业务工具入口。它可以通过 MCP 暴露给 Codex,也可以通过未来 Runtime 的原生 Tool API 暴露;因此模块名、日志和文档不再使用容易误解的“OpenCreator MCP 层”。--关系如下:--```text-Codex Runtime Adapter ─ MCP ─┐-Claude Runtime Adapter ─ Tool API ─┼─ Creator Tool Server ─ Dispatcher-内部自动化任务 ─ Native Call ─────┘-```--Codex `0.149.0` 的 P0 稳定接入沿用现有 Host 的做法:Runtime Manager 在启动隔离 app-server 时通过 Codex 配置覆盖注入唯一的 Creator MCP Server,Creator Tool Server 使用 Daemon 本地受保护路由。不使用仍标记为 experimental 的 `dynamicTools` 作为正式主链路,也不修改用户全局 `config.toml`。--认证采用 Process Capability Lease:Host 环境中只有固定进程 Token,真正的 Job、Thread、Turn 和 scopes 在每个 Turn 开始前由 Daemon 激活,结束后停用。MCP 启动配置改变时重启 Host;`config/mcpServer/reload` 不能用于替换命令行覆盖或环境变量。--### 13.2 P0 工具--```ts-creator_get_context({ jobId, projection?, sinceRevision? })-creator_get_artifact({ jobId, artifactId, format?, range? })-creator_apply_action({ jobId, expectedRevision, action, idempotencyKey })-```--设计约束:--1. `creator_get_context` 默认返回摘要,不返回完整字幕、媒体二进制和全部历史。-2. `creator_get_artifact` 按需读取大内容,并限制路径只能位于当前 Creator Job 授权目录。-3. `creator_apply_action` 只接受 TemplateDefinition 声明的 Action Schema。-4. Tool Server 不提供 `run_shell`、任意文件路径或直接 KrillinAI 调用。-5. 每次调用绑定 `creatorJobId`、Thread、Turn 和 capability token。-6. 写操作要求 `expectedRevision` 和 `idempotencyKey`。--### 13.3 Command Dispatcher--REST 与 Tool 必须共用:--```ts-dispatchCreatorCommand({- jobId,- actor,- expectedRevision,- idempotencyKey,- action,-}): Promise<CreatorActionReceipt>-```--Dispatcher 统一完成:--1. Action Schema 和权限校验。-2. revision 与幂等检查。-3. Job 状态修改。-4. 下游 Artifact stale 传播。-5. Activity 写入。-6. StageRun 创建与真实调度。-7. Creator Snapshot/Event 发布。--现有 `run-stage` 只修改状态而未可靠启动 Stage 的分叉必须消失;状态变更和调度意图在同一个数据库事务中提交,再由可恢复的 Stage 调度器领取执行。--幂等语义固定如下:--1. Dispatcher 开启数据库事务后先按 `(job_id, idempotency_key)` 查询 `creator_command_receipts`。-2. 同键、同 `request_hash` 且已完成:直接重放原 `receipt_json` 或原结构化错误,不再次修改 revision、创建 Activity 或 StageRun。-3. 同键、不同 `request_hash`:拒绝并返回 `creator_idempotency_key_reused`。-4. 新命令通过校验后,在同一事务内提交 revision、Activity、StageRun/调度意图和 committed receipt;响应丢失不影响后续重放。-5. revision 冲突等确定性拒绝可以保存 rejected receipt;Agent 重新读取后使用新的 idempotencyKey 提交新尝试。-6. 事务提交前的进程或数据库失败不留下可见 receipt,调用方可以用原键重试。--测试必须覆盖并发相同请求、同键不同载荷、响应丢失后重试和 Daemon 重启后重试,并证明只产生一次 Activity、StageRun 和 Artifact 执行链。--## 14. 模板、上下文与 Skills--### 14.1 三者关系--```text-TemplateDefinition:OpenCreator 业务生产合同- 决定阶段、输入、Action、依赖、产物和 UI Schema--Agent Context Projection:某一时刻从 Creator Job 派生的动态事实- 告诉 Agent 当前任务、revision、选择、最近变化和允许动作--Runtime Skill:面向某个 Agent Runtime 的稳定操作知识- 告诉模型如何理解 OpenCreator 工具、错误和操作习惯-```--模板不是 Skill,模板也不需要每次完整塞给 Codex。--### 14.2 每次 Turn 传什么--每次 Turn 只传:--1. Job ID、template ID/version 和当前 revision。-2. 当前阶段、选择项和用户正在看的 Artifact。-3. 最近有限条 Activity。-4. 当前可执行 Action 的名称和简要约束。-5. 与当前问题直接相关的小型数据摘要。-6. 必要时提示 Agent 使用 `creator_get_context` 或 `creator_get_artifact` 获取更多内容。--完整字幕、全部模板 Schema、所有历史版本和媒体数据不进入基础 Prompt。--### 14.3 强制规则放在哪里--以下内容在 `thread/start` 或 `thread/resume` 时通过 app-server `developerInstructions` 注入,而不是依赖 Skill 是否被模型触发:--1. 修改 Creator Job 必须使用 Creator Tool。-2. 不得通过文件编辑绕过 revision。-3. 工具失败不得宣称任务成功。-4. revision 冲突处理规则。-5. 当前 Job 和允许访问的目录范围。--### 14.4 Skill 的安装与加载时机--用户不参与 Skill 安装:--1. OpenCreator 构建时将稳定 Skills 打入安装包资源目录。-2. Daemon 首次初始化内置 Runtime 时校验 manifest 和 Skill 版本。-3. 每个 app-server Host 启动后调用 `skills/extraRoots/set`,以只读额外根目录加载这些 Skills。-4. OpenCreator 升级时随安装包原子更新;不复制到用户全局 `CODEX_HOME/skills`。-5. `skills/list` 启动检查确认 Skill 可见;不可见时给出 Runtime 诊断,但模板和业务状态仍不迁移进 Skill。--因此,Skill 不是“每轮把全部内容作为 Prompt 发送”,也不是要求用户手动安装到自己的 Codex。它是 OpenCreator 内置 Runtime 的版本化资源,并由 app-server 原生发现。--### 14.5 替换 Claude Code--替换 Runtime 时:--1. Creator Core、TemplateDefinition、Context Projection 和 Creator Tool Contract 保持不变。-2. 新增 ClaudeRuntimeAdapter,将 Thread、Turn、事件、审批和工具映射到同一 AgentRuntimeAdapter。-3. 将 `opencreator-runtime` 的稳定知识转换为 Claude 可加载的项目指令或 Skill 形式。-4. 强制规则仍由 Adapter 作为 developer/system 指令注入,不能只依赖可选 Skill。--## 15. KrillinAI 与多模态 Provider--### 15.1 正式运行方式--正式目标是常驻服务,而不是每个动作都让 Agent 调 CLI:--```text-Creator Stage Runner- │ local RPC- ▼-Krillin Runtime Host- │ 启动、健康、重启、日志- ▼-KrillinAI OpenCreator Service- ├─ download / probe- ├─ subtitle / ASR / translation- ├─ TTS- ├─ horizontal / vertical render- └─ task status / cancel / result-```--需要在 KrillinAI 补齐的最小服务合同:--```text-GET /v1/health-GET /v1/capabilities-POST /v1/tasks-GET /v1/tasks/:id-POST /v1/tasks/:id/cancel-GET /v1/tasks/:id/events-```--任务请求只携带 `jobId`、`stageId`、阶段类型、Artifact ID、非敏感参数和幂等键;不得接受客户端提供的任意绝对工作目录。服务根据 Host 授予的 Creator Jobs 根目录自行解析真实路径。服务返回结构化 task ID、状态、事件和 Manifest;任务状态至少持久化到对应 Job 目录,不能只在内存中保存。--### 15.2 本地服务安全边界--1. Krillin Runtime Host 让操作系统分配随机 loopback 端口,仅绑定 `127.0.0.1`;命名管道或 Unix Domain Socket 可作为后续平台优化,但 P0 不同时维护两套协议。-2. 每次服务进程启动生成至少 256 bit 的随机进程 Token,通过受控环境变量传入,不放在 argv、URL、日志或配置文件中。-3. 所有 `/v1/*` 请求都必须携带 Bearer Token;无 Token、错误 Token 或旧进程 Token统一拒绝。`/v1/health` 也不匿名暴露内部配置。-4. Host 只授予 `<OpenCreatorUserData>/creator/jobs` 作为数据根。服务通过 `jobId` 和 Artifact ID 解析路径,对 canonical path、父目录和符号链接逐级校验,禁止跨 Job 和根目录逃逸。-5. OpenCreator service mode 不挂载旧 `/api/config`、`/api/file`、静态 UI 和任意路径下载接口。-6. Provider 凭据由 Host 从 Keyring 读取后,经认证本地请求作为任务期内存配置传入;服务不持久化、不回显,并在任务结束或进程退出时释放。-7. 请求、事件、Manifest 和日志执行统一脱敏;API Key、Authorization、代理凭据和完整 Provider 配置不得进入任务目录、诊断包或崩溃日志。-8. 服务重启时轮换 Token;旧任务恢复只依赖持久 task metadata 和幂等键,不依赖旧 Token。--集成测试必须覆盖无 Token、错误/旧 Token、任意路径输入、`..` 逃逸、符号链接逃逸、跨 Job 访问、旧路由不可用、日志泄漏和崩溃后凭据清理。--### 15.3 为什么采用常驻服务--1. 避免每次执行重新发现依赖、初始化本地 ASR 和建立重复的管理通道。-2. 统一取消、进度、日志、并发和恢复语义。-3. Stage Runner 不需要解析不同 CLI 命令的 stdout 文案。-4. OpenCreator 可以明确展示服务 readiness 和能力矩阵。--迁移期允许 Krillin Service 内部调用现有 CLI command handler 复用能力,但 OpenCreator 只依赖服务合同。若某阶段尚未进入服务,Stage Runner 可以使用显式的真实 CLI Adapter;该 Adapter 必须返回真实结果和错误,并在服务版本完成后删除,不能成为长期双主链路。--### 15.4 配置所有权--OpenCreator 统一保存以下逻辑能力配置:--```text-agent_runtime Codex 登录、模型和推理设置-text_generation 字幕翻译、摘要、改写所用 Provider-asr 云端转录或本地 Whisper-tts 配音 Provider-image_generation 封面与图片 Provider-video_generation 后续生视频 Provider-proxy 下载和外部服务代理-```--规则:--1. Codex 登录只服务交互式 Agent,不自动变成 KrillinAI 的 OpenAI API Key。-2. 小规模交互式文本修改可以由 Codex Agent 完成;批量字幕翻译作为可重试 Stage 时使用 `text_generation` Provider。-3. 转录按配置能力选择:配置云端 ASR 时使用云端;未配置且本地 Whisper 可用时使用本地;两者都不可用才报缺少转录能力。-4. Provider Config Store 使用系统 Keyring;传给 KrillinAI 时使用进程内请求或临时受限配置,不写入 Creator Job、Agent Prompt 和普通日志。-5. 启动 Stage 前执行 capability preflight,并明确指出缺失的是 ASR、翻译、TTS、下载还是渲染能力。--## 16. 失败和恢复--| 场景 | 处理 |-| --- | --- |-| Codex 文件缺失或哈希错误 | Runtime Readiness 失败,禁止 Agent 启动,提示修复安装 |-| app-server 初始化失败 | 自动重启一次;仍失败则记录 `CODEX_APP_SERVER_UNAVAILABLE` |-| app-server 在 Turn 中崩溃 | 恢复 Thread;未确认 Turn 不自动重放 |-| 用户取消 Turn | 调用 `turn/interrupt`,持久化 canceled 终态 |-| 页面刷新且原 Host 存活 | Turn 保持 waiting_approval,UI 可继续响应当前 generation 的审批 |-| Daemon/app-server 在审批中崩溃 | 旧审批标记 expired,无法确认的 Turn 标记 interrupted,不回写旧 request ID |-| Creator revision 首次冲突 | 重新读取后最多重试一次 |-| Creator revision 再次冲突 | 进入 `needs_user_resolution` |-| Creator Tool 失败 | Tool Item 保存结构化错误,Agent 不得宣称成功 |-| KrillinAI 服务崩溃 | Host 重启;执行中 Stage 标记 interrupted,按幂等键恢复或由用户重试 |-| Provider 配置缺失 | Stage 启动前失败,指出具体能力,不生成假任务 |-| 网络或模型失败 | 保存 retryable 与 provider error,保留已有 Artifact |-| 上游内容变化 | 保留旧 Artifact,并将受影响下游标记 stale |--终态必须明确:`completed`、`failed`、`canceled`、`interrupted` 或 `needs_user_resolution`,不得永久停留在无解释的 `running`。--## 17. 数据与历史迁移--1. 为 Agent Session、Turn、Item 和 Event 增加带版本号的 SQLite migration。-2. 旧 Demo 会话标记为 `legacy_demo`,不写入 Codex Thread,也不显示成真实模型回答。-3. 现有 Creator Job 可迁移输入、配置和可验证 Artifact;无法证明来源的演示 Artifact 标记为 demo,不能成为正式 Stage 依赖。-4. 升级前创建数据库备份;失败时回滚 Schema 和 active runtime manifest。-5. 首次启动新版本时执行 Codex、Creator Tool 和 KrillinAI readiness 检查,但登录缺失只影响 Agent,不应破坏已有 Creator 数据浏览。--## 18. 分阶段实施--### P0:Codex Runtime 基础闭环--1. 打包 Codex `0.149.0`、manifest、哈希和生成 Schema。-2. 实现隔离 `CODEX_HOME`、Runtime Readiness、应用内登录和模型列表。-3. 将普通 Agent 与 Creator Agent 都接入共享的常驻 app-server Host 管理。-4. 持久化 Thread、Turn、Item 和归一化事件。-5. 删除生产规则回答、固定回复和 mock 结果。--验收:连续真实对话、流式输出、中断、刷新恢复和 Daemon 重启恢复全部可用。--### P1:Creator Agent 与共享状态--1. 完成 Creator Command Dispatcher。-2. 工作台 REST 与 Agent Tool 使用同一 Action 合同。-3. Agent 面板统一展示 Creator Snapshot、Activity 和真实 Codex 对话。-4. 完成 Activity 去重、revision 冲突和 Artifact stale。-5. 删除 `VideoTranslationAgentPanel` 的本地历史与字符串意图识别。--验收:从任一侧修改任务,另一侧实时看到同一结果;工作台操作不自动启动 Codex。--### P2:Creator Tool Server 与真实视频流程--1. 上线三个 P0 Creator Tool。-2. 补齐 KrillinAI 常驻服务合同与 Runtime Host。-3. 打通真实下载、字幕、转录、翻译、TTS、横屏和竖屏渲染。-4. 完成统一 Provider 配置桥接和 capability preflight。-5. 修复 `run-stage` 状态与调度分叉。--验收:输入真实 YouTube/Bilibili/本地素材,产生可验证的真实任务、字幕、媒体和 Artifact。--### P3:模板与多模态扩展--1. 完成 Template Context Projection 和 Action Schema 自动暴露。-2. 增加封面、生图和后续生视频 Provider。-3. 增加模板版本迁移、能力声明和兼容检查。-4. 实现外部 Codex 高级模式及兼容矩阵。-5. 为 Claude Code 等 Runtime 验证 Adapter 可替换性。--验收:新增模板无需修改 Agent 基础协议;更换 Runtime 不修改 Creator Core。--## 19. 测试策略--### 19.1 协议与单元测试--1. Codex `0.149.0` Schema 生成快照与关键方法解析。-2. Runtime manifest、哈希、版本、平台和回滚。-3. Host 复用、空闲回收、活动 Turn 保护和崩溃恢复。-4. Event Normalizer 对 Thread、Turn、Item、审批、工具和未知通知的映射。-5. Dispatcher 的 revision、幂等、Activity、stale 和调度事务。-6. Context Projection 不泄露密钥、不携带不必要大数据。-7. Process Capability Lease 的 activate/deactivate/revoke、Job/Thread/Turn 绑定和非活动请求拒绝。-8. Command Receipt 的同键同载荷重放、同键不同载荷拒绝和唯一约束。--### 19.2 集成测试--1. 真实 `codex app-server` initialize、account、model、skill、Thread 和 Turn。-2. Creator Tool Server 经 MCP 调用 Dispatcher,并验证同一 Host 连续两个 Turn 分别激活正确的 Job/Run/scopes,旧绑定和非活动请求均被拒绝。-3. SQLite 重启恢复 Agent 历史和 Creator Job 映射,并覆盖 `thread/read(includeTurns:true)` 对账、重复事件回放和旧 generation 审批失效。-4. 并发重复命令、响应丢失和 Daemon 重启后重试只创建一次 Activity、StageRun 和执行链。-5. KrillinAI health、task、events、cancel、重启和结果校验。-6. KrillinAI 本地服务覆盖无 Token、错误/旧 Token、路径与符号链接逃逸、跨 Job 访问、旧路由不可用、日志脱敏和崩溃清理。-7. 云端 ASR、本地 Whisper 和无转录能力三种路径。--测试夹具可以使用 fake app-server 或 fake provider 验证异常,但生产构建不得引用这些入口。--### 19.3 端到端与安装包测试--1. 无本机 Codex时,内置 Runtime 正常工作。-2. 本机已有其他 Codex 版本时,两者 Home、PATH、配置和进程互不影响。-3. 未登录、登录、退出和令牌过期状态正确。-4. 视频翻译从链接输入到真实 Artifact 完成。-5. 工作台修改后 Agent Activity 只出现一次。-6. Agent 修改字幕后工作台立即更新。-7. 页面刷新、Daemon 重启、app-server 崩溃和 KrillinAI 重启后状态可解释并可恢复。-8. Web 与 Desktop 使用同一 Web 构建和 Daemon API,完成相同内容视口截图与行为对比。-9. 安装包校验内置 Codex、KrillinAI、yt-dlp nightly、FFmpeg、Schema 和 manifest。-10. 页面刷新时可继续存活审批;Daemon/app-server 在审批中崩溃时旧审批失效且 Turn 进入 interrupted,不存在永久 waiting_approval/running。--## 20. 发布门禁与最终验收--以下条件必须全部满足,才能声明真实 Agent 改造完成:--1. Agent 的回答来自真实 Codex Turn,不存在生产 mock 或规则兜底。-2. Creator Agent 不再为每个 Turn 临时启动一个 app-server。-3. 工作台和 Agent 共享同一 Creator Job、revision、Activity 和 Artifact。-4. 工作台操作会立即在 Agent 区域形成一条可理解且不重复的状态体现。-5. Agent 执行 Creator Action 后,工作台立即展示真实变化。-6. 刷新和重启后能够恢复 Creator 状态和 Codex 对话。-7. 视频翻译产生真实 KrillinAI Task 和文件,失败时保留真实错误。-8. 转录正确执行云端 ASR、本地 Whisper 或明确失败的能力选择逻辑。-9. 内置 Codex 不修改或依赖用户本机 Codex 环境。-10. Codex、Creator Tool Server 和 KrillinAI 均有明确 readiness 与诊断。-11. Web 与 Desktop 通过同源构建、行为测试和实际安装包测试。-12. 任一 Runtime、Tool 或 Provider 失败都不会显示 Demo 成功结果。-13. 同一常驻 Host 的工具权限严格绑定当前活动 Turn,旧 Turn 和非活动请求无法访问 Creator Tool。-14. 相同幂等命令在并发、丢响应和重启重试后只执行一次。-15. KrillinAI 服务仅接受认证的 loopback 请求,不能访问授权 Creator Jobs 根以外的路径或泄露 Provider 凭据。--## 21. 关键风险--| 风险 | 影响 | 控制措施 |-| --- | --- | --- |-| Codex app-server 协议仍快速演进 | 升级可能破坏类型或事件解析 | 固定版本、生成 Schema、兼容矩阵、未知事件容忍、回滚 |-| Tool 重放导致重复 Stage | 重复计费或覆盖 Artifact | idempotencyKey、调度事务、Turn 不自动重放 |-| Context Projection 过少或过多 | Agent 判断不足或 Token 浪费 | 默认摘要、按需工具读取、上下文体积测试 |-| KrillinAI 常驻服务改造范围扩大 | P2 工期增加 | 复用现有 command handler;先建立最小 task 合同 |-| 双侧同步出现重复 Activity | 用户误以为执行了两次 | 服务端 actionId/seq、前端幂等消费、专项 E2E |-| Provider 配置与 Codex 登录混淆 | 已配置仍提示缺失,或错误复用凭据 | 分能力 readiness、独立配置域、执行前能力解释 |--## 22. 已排除方案--1. 继续只使用 `codex exec --json` 承担交互式 Agent。-2. 直接采用当前 TypeScript SDK 作为主集成层;它目前主要封装 exec,不能替代 app-server 完整控制面。-3. 每个 Creator Turn 启动和销毁一次 app-server。-4. 默认发现并使用 PATH 中任意 Codex。-5. 把完整模板和全部 Job 内容每轮塞入 Prompt。-6. 为每个模板生成一份 Skill,并让 Skill 保存业务流程状态。-7. Agent 直接调用 KrillinAI CLI 或 HTTP 接口。-8. 工作台和 Agent 各维护一份状态,再通过相互通知合并。-9. Runtime 失败后回退到规则回答或 Demo Artifact。--## 23. Reviewer 修订记录--V2 独立审核原始结论为 `REVISE`,无未决产品问题。关闭情况如下:--| Reviewer 问题 | V3 修订 | 关闭证据 |-| --- | --- | --- |-| R-01 Host MCP Token 无法按 Turn 换绑 | 固定 Process Capability Lease;Turn 前 activate、终态 deactivate;同 Host 串行 Turn;配置变化重启 Host | 10.4、13.1、19.1-19.2、最终验收 13 |-| R-02 Thread resume 不能恢复死亡连接上的审批 | 增加 approval/process generation;页面刷新与进程崩溃分流;`thread/read` 对账;旧审批 expired,未知 Turn interrupted | 11.2、11.5、16、19.2-19.3 |-| R-03 idempotencyKey 没有持久权威 | 增加 `creator_command_receipts`、唯一约束、request hash、事务内收据和结果重放语义 | 11.2、13.3、19.1-19.2、最终验收 14 |-| R-04 KrillinAI 常驻服务缺少安全边界 | 随机 loopback 端口、进程 Token、授权根解析、符号链接检查、旧路由禁用、凭据内存化和脱敏 | 15.1-15.2、19.2、最终验收 15 |--流程结论为 `PASS`:四项 Major 均已转化为唯一技术合同和可执行测试,不需要用户新增产品决策。Reviewer 未运行测试、构建或服务;这是方案审核结论,不代表代码已经实现或验收通过。--## 24. 方案结论--OpenCreator 不需要再建设一个新的 Agent Harness,也不应继续把 Codex CLI 当成一次性命令执行器。最简单且完整的方案是:内置并隔离固定版本 Codex CLI,由 Runtime Manager 常驻管理 `codex app-server`;Creator Core 继续拥有全部创作业务状态;Creator Tool Server 通过统一 Dispatcher 把真实 Agent 操作连接到同一 Creator Job;KrillinAI 作为被托管的常驻媒体服务执行真实 Stage。--该方案的关键不是增加更多同步机制,而是删除重复状态源和假执行路径。工作台、Activity 与 Codex 对话各自表达不同信息,但共同围绕唯一 Creator Job 运行。diff --git "a/docs/specs/OpenCreator\346\250\241\346\235\277\345\214\226\345\210\233\344\275\234\346\236\266\346\236\204\346\226\271\346\241\210-2026-08-20.md" "b/docs/specs/OpenCreator\346\250\241\346\235\277\345\214\226\345\210\233\344\275\234\346\236\266\346\236\204\346\226\271\346\241\210-2026-08-20.md"deleted file mode 100644index b96cff7e..00000000--- "a/docs/specs/OpenCreator\346\250\241\346\235\277\345\214\226\345\210\233\344\275\234\346\236\266\346\236\204\346\226\271\346\241\210-2026-08-20.md"+++ /dev/null@@ -1,568 +0,0 @@-# OpenCreator 模板化创作架构方案--> 状态:草案-> 体量判断:复杂方案。该交付同时涉及前端共享状态、Daemon 持久化、Agent Runtime 抽象、Skill 生命周期、外部 KrillinAI 进程、凭证配置、媒体产物和多阶段产品演进;各部分共同约束同一个创作任务,不能独立验收,因此保持一份内聚方案。-> 设计确认:已完成(D-1 至 D-4)-> Reviewer 原始结论:REVISE-> 流程结论:PASS-> 用户批准:已批准(2026-08-20),批准原话:`没问题,继续`--## 背景、目标与非目标--OpenCreator 当前已经具备成熟的 Codex Runtime、Daemon、Web/Desktop 共用前端、任务事件和 AI 服务配置基础,但上层创作功能仍处于 Demo 阶段。视频翻译、视频下载、封面、自动剪辑和火柴人视频目前主要表现为硬编码工作区、React 本地状态和关键词回调,尚未形成可持久化、可恢复、可扩展的创作产品。--### 目标--1. 将 OpenCreator 定位为面向个人创作者和小型内容团队的 AI 内容创作工作台,责任终点为内容成品预览与导出,不处理发布。-2. 让工作台和 Agent 面板成为同一个创作任务的两个平等操作入口,双方共享状态、当前关注、创作动态和版本结果。-3. 建立最小且可执行的模板、任务、阶段和产物契约,以视频翻译作为 P0 真实闭环,并同时定义下载、封面、自动剪辑和火柴人视频的后续方案。-4. 保持 OpenCreator 核心与 Codex 解耦:模板和业务状态属于 OpenCreator,Skill 属于 Agent Runtime 适配层,Codex/Claude Code 可通过适配器替换。-5. 将 KrillinAI 定位为媒体阶段执行器,由 OpenCreator 负责任务编排、进程生命周期、配置注入、结果校验和失败恢复。--### 非目标--1. 内容上传、定时发布、发布审批、平台状态跟踪和发布数据分析。-2. Premiere/剪映式完整非线性编辑器。-3. 用户可视化拖拽节点的通用工作流平台或用户自定义模板编辑器。-4. P0 多人实时协作、组织权限和审批流。-5. 以 Skill、聊天记录或 KrillinAI Manifest 作为创作任务的唯一状态源。-6. P0 同时实现全部五类功能的真实执行闭环。--## 用户需求原文--1. `底层使用codex的运行时确实很成熟了,我需要你重点关注的是上层opencreator交互的设计,里面涉及多个功能:视频翻译,封面等,这些是由模版化的方式运行,这里需要你认真分析出来,现在实现的是demo层面,需要给出实际的需求分析。`-2. `视频的下载、翻译等都是用这个工具[email protected]:krillinai/KrillinAI.git,你可以拉取到当前目录看下有什么能力,然后再结合上面的分析来一起设计方案。`-3. `$zhiyu-brainstorm 你分不同段落来梳理需求和方案,我跟你一起来完成,让我可以消化,一次太多,我消化不过来,从产品需求定位开始,再到方案设计,一步步来,但也不要拆分的过细,整个过程控制在10~20次交互之内吧,开始`-4. `经过少量关键审核,得到可直接发布的多平台内容包 -- 这里有误差,OpenCreator暂时不处理发布,只做内容创作,所以不需要再增加审核发布环节`-5. `这里有一个很关键的点你没提到,就是工作台的信息和Agent区域的互动,这是这个产品的核心灵魂,也就是说,用户可以在工作台进行创作,也可以在Agent区域进行创作,但二者的状态是同步的。`-6. `现在开始进入方案设计了,要求就是,方案能简单就简单,要满足奥卡姆剃刀原理,另外就是方案一定要具备可执行性。`-7. `最难的就是Creator Core这一层了,这是最核心的部分,如何做好状态同步,以及Agent上下文的处理,包括模版的设计。我理解下:这里的模版流程什么的,让Agent能识别,是不是需要做成skills,因为底层是codex,只能靠skills串联,还是说每次把全部上下文全丢给Agent处理呢,这个要评估下。`-8. `用户在任何一边的操作,都要实时相互同步,也就是在工作台只要有操作,就要在Agent侧有体现,这个体现不一定是要Agent执行,而是要有一定的提示。`-9. `模版是更上层的,skills是codex底层的东西,所以我说为什么要把整个模版上下文全部都给Agent,是因为,OpenCreator是一个上层Agent,codex是底层执行的,那skills到底应该是属于谁的呢,如果底层换了Claude code的话,能适配吗?`-10. `稳定 Skill 安装一次 -- 在什么时机安装呢,正常来说,用户肯定不会显示去处理,可能也看不懂什么是skill。`-11. `功能可以分不同阶段,P0确实可以先从最小的开始验证,但是其他阶段的方案也要一起出出来,方便后续指导开发。`--## 事实基线与假设--### 事实基线--| 证据 | 已确认事实 |-| --- | --- |-| `apps/web/src/features/conversation/CreatorWorkbench.tsx`、`creator-workspace.ts` | 当前五个创作入口映射到硬编码工作区,没有统一模板协议。 |-| `CreatorToolShell.tsx` | 通用 Agent 消息保存在组件 `useState`,通过本地 `onCommand` 回调返回 Demo 文本。 |-| `VideoTranslationWorkspace.tsx`、`VideoTranslationAgentPanel.tsx` | 视频翻译 Demo 已支持 Agent 修改左侧状态、撤销、控件高亮和派生 `contextSummary`;工作台操作尚未形成持久化创作动态。 |-| `apps/daemon/src/storage/*`、`packages/protocol/src/events.ts` | Daemon 已有 SQLite、任务状态和 SSE/事件基础,可以承载 CreatorService,无需新增独立服务。 |-| `apps/daemon/src/codex/app-server-runner.ts` | 当前 Codex Runtime 可传入 Prompt、恢复 Thread、注入 MCP/内置工具和处理取消,不是只能依赖 Skills。 |-| `apps/daemon/src/codex/skills/scanner.ts` | Codex Skill 从应用指定 `CODEX_HOME/skills/<id>/SKILL.md` 扫描,可使用应用隔离 Codex Home。 |-| `apps/daemon/src/creator-services/config-store.ts` | 文本、ASR、TTS、图片、视频和代理配置已通过系统 Keyring 安全保存。 |-| `KrillinAI/internal/cli/commands.go` | KrillinAI 真实 CLI 支持 `subtitle`、`tts`、`render-horizontal`、`render-vertical`、`cover` 和 `voices`;`pipeline/status` 未形成可靠执行能力。 |-| `KrillinAI/internal/router/router.go`、`internal/service/subtitle_service.go` | KrillinAI HTTP Server 主要提供旧版字幕综合任务,任务状态保存在内存,全局配置和取消/恢复能力不满足正式集成。 |-| `KrillinAI/internal/pipeline/manifest.go` | Manifest 可作为执行结果证据之一,但没有 OpenCreator 所需的版本、审核、stale、实时进度和血缘语义。 |-| KrillinAI 提交 `a9f4ec2` | 本方案能力判断基于 2026-08-19 拉取的该版本。 |-| `AGENTS.md` | Web 是唯一前端实现,Desktop 必须复用同一 Web 构建、Daemon API、状态和通用业务逻辑。 |--### 假设--1. P0 是本机单用户创作软件,不设计 CRDT 和多人并发编辑。-2. OpenCreator 可以随安装包携带平台对应的 KrillinAI、FFmpeg 和必要媒体依赖。-3. P0 仅正式实现 CodexAgentAdapter,但所有 OpenCreator 业务契约保持运行时无关。-4. P0 可以接受 KrillinAI 的真实阶段级进度;细粒度百分比在 KrillinAI 提供 JSONL 事件后实现。-5. 视频翻译 P0 只承诺 YouTube、Bilibili 和本地媒体输入。--## 设计确认记录--| 设计部分 | 核心决定 | 用户确认原话 |-| --- | --- | --- |-| D-1 产品定位与目标边界 | OpenCreator 只做内容创作、预览和导出;创作确认不是发布审批;P0 面向个人创作者和小型团队。 | `没问题,继续` |-| D-2 模板化产品结构与双向创作交互 | 模板是可版本化生产契约;工作台与 Agent 是统一创作状态之上的两个平等入口;视频下载是基础能力,封面可独立也可嵌入模板。 | `没问题,继续` |-| D-3 系统架构与运行边界 | 采用共享 CreatorSession、薄 CreatorService、运行时无关 Agent Action API;模板不等同于 Skill;基础 Skill 由 Daemon 自动安装到隔离 Runtime Home;KrillinAI P0 按阶段调用 CLI。 | `没问题,继续` |-| D-4 实施范围与验收 | P0 以最小视频翻译闭环验证架构,P1/P2 方案同时写入本方案供后续开发使用。 | `功能可以分不同阶段,P0确实可以先从最小的开始验证,但是其他阶段的方案也要一起出出来,方便后续指导开发,没问题,继续吧` |--## 需求与业务规则--| ID | 类型 | 优先级 | 描述 |-| --- | --- | --- | --- |-| FR-1 | 功能需求 | P0 | OpenCreator 从素材或创作意图开始,完成模板化内容创作、预览和导出,不包含发布流程。 |-| FR-2 | 功能需求 | P0 | 每次模板运行创建可持久化 CreatorJob,并保存模板版本、阶段、产物版本、创作动态和失败记录。 |-| FR-3 | 功能需求 | P0 | 工作台和 Agent 面板实时展示同一 CreatorSession;任一侧的有效操作都必须在另一侧的状态或创作动态中体现。 |-| FR-4 | 功能需求 | P0 | Agent 面板必须同时提供当前创作状态、创作动态和模型对话,并允许 Agent 通过运行时无关的 Creator Action 修改任务。 |-| FR-5 | 功能需求 | P0 | 视频翻译支持 YouTube、Bilibili、本地媒体、字幕生成与编辑、可选 TTS、横竖屏渲染、版本保留、预览和导出。 |-| FR-6 | 功能需求 | P0 | OpenCreator 提供统一 AI 服务配置并映射给 KrillinAI;Agent Runtime 认证与生产模型凭证分开管理。 |-| FR-7 | 功能需求 | P1 | 视频下载形成可独立使用且可被其他模板复用的 `probe/download` 基础能力;封面支持独立和嵌入式多方案创作。 |-| FR-8 | 功能需求 | P2 | 自动剪辑和火柴人视频复用统一 CreatorSession、模板、Agent Action 和 StageRunner,并通过独立执行器补齐核心生成能力。 |-| BR-1 | 业务规则 | P0 | TemplateDefinition 是模板业务规则的唯一权威位置;Skill 不得保存阶段状态、产物依赖或 UI 规则。 |-| BR-2 | 业务规则 | P0 | 单纯工作台操作只更新共享状态和创作动态,不得启动 Codex Run 或消耗模型 Token。 |-| BR-3 | 业务规则 | P0 | 高频文字输入实时更新共享草稿,但只在失焦、保存或聚合阈值到达时产生语义创作动态。 |-| BR-4 | 业务规则 | P0 | 所有持久化修改携带 `expectedRevision`;旧 revision 不得覆盖新状态。 |-| BR-5 | 业务规则 | P0 | 上游内容变化后保留旧产物版本,并将受影响的下游产物标记为 `stale`,不得静默复用。 |-| BR-6 | 业务规则 | P0 | KrillinAI P0 采用每个 StageRun 一个 CLI 进程;是否引入常驻 Worker 必须由真实预热和吞吐数据决定。 |-| BR-7 | 业务规则 | P0 | 执行成功必须同时通过进程结果、Manifest/JSON 解析和媒体文件校验,不能制造假进度或假成功。 |-| BR-8 | 业务规则 | P0 | `opencreator-runtime` Skill 由 Daemon 自动同步到应用隔离 Runtime Home,用户无需理解、安装或配置 Skill。 |-| NFR-1 | 一致性约束 | P0 | Web/Desktop 使用同一 React 前端、Protocol、Daemon CreatorService、模板和 Agent Action 实现。 |-| NFR-2 | 恢复约束 | P0 | 页面刷新和 Daemon 重启后可恢复 Job、阶段、产物和创作动态;中断中的外部进程标记为 `interrupted` 并允许重试。 |-| NFR-3 | 安全约束 | P0 | API Key 不进入 React 持久状态、CreatorJob、聊天上下文、普通日志、诊断包或导出产物。 |-| NFR-4 | 交互约束 | P0 | 同一页面内的工作台变化同步更新 Agent 状态视图,不依赖网络轮询或模型调用。 |-| NFR-5 | 可替换性约束 | P0 | TemplateDefinition、CreatorSession 和 Creator Action 不引用 Codex 专属类型;Codex/Claude 差异只存在于 AgentRuntimeAdapter。 |-| NFR-6 | 打包约束 | P0 | 正式安装包固定并记录 KrillinAI 及媒体依赖版本,运行时不克隆仓库或下载不受控可执行文件。 |--## 方案比较与推荐--### Creator 状态方案--| 方案 | 影响 | 结论 |-| --- | --- | --- |-| React 本地状态 + Agent 回调 | 延续 Demo,无法持久化、恢复或跨模板复用。 | 排除 |-| 通用工作流引擎 + 事件溯源 | 扩展性高,但需要 DSL、事件重放和复杂迁移,超出当前需求。 | 排除 |-| 前端共享 SessionStore + Daemon 薄 CreatorService | 同时满足实时展示、持久化、版本冲突和最小实现。 | 采用 |--### Agent 上下文方案--| 方案 | 影响 | 结论 |-| --- | --- | --- |-| 每轮传入完整模板、字幕、历史和日志 | Token 成本高,容易使用过期状态。 | 排除 |-| 每个模板复制为 Codex Skill | 模板业务规则与 Skill 漂移,绑定 Codex。 | 排除 |-| 稳定 Runtime Skill + 最小动态上下文 + 按需工具读取 | 稳定规则安装一次,业务状态实时读取,支持运行时替换。 | 采用 |--### KrillinAI 运行方案--| 方案 | 影响 | 结论 |-| --- | --- | --- |-| 复用现有 HTTP Server | 只覆盖旧字幕任务,状态在内存,配置与取消边界不足。 | 排除 |-| 每 StageRun 启动 CLI | 隔离、取消、重试、配置映射和打包边界清晰。 | P0 采用 |-| 新建常驻 Worker | 可复用本地大模型预热,但增加协议、健康、并发和恢复复杂度。 | 有性能证据后采用 |--## 关键设计决策--| DEC ID | 决策 | 理由 | 约束范围 |-| --- | --- | --- | --- |-| DEC-1 | CreatorSessionStore 是同一前端实例中工作台和 Agent 面板的共享展示状态;CreatorService 是持久业务状态的唯一权威。 | 同时满足即时交互和重启恢复,避免两侧互发业务通知。 | Web、Desktop、Daemon |-| DEC-2 | Agent 面板固定由状态摘要、创作动态和模型对话三部分组成。 | 工作台操作可以在 Agent 区域体现,而无需伪造 Agent 消息或调用模型。 | 所有模板 UI |-| DEC-3 | CreatorService 直接作为现有 Daemon 内模块实现,不新增微服务、消息队列、CRDT 或事件溯源。 | 符合单机产品和奥卡姆剃刀原则。 | Daemon、SQLite |-| DEC-4 | TemplateDefinition 以静态 TypeScript 定义和 Schema 校验实现,P0 不提供 YAML、数据库或可视化模板编辑器。 | 保持类型安全和可执行性,避免过早建设通用平台。 | TemplateRegistry、UI、StageRunner |-| DEC-5 | OpenCreator 核心使用运行时无关 AgentContract 和 Creator Action API;MCP/Native Tools 只是 AgentRuntimeAdapter 的传输实现。 | 支持 Codex 与 Claude Code 替换,避免产品绑定 MCP 或 Skill。 | Agent 集成 |-| DEC-6 | 稳定 Agent 行为规则作为 `opencreator-runtime` Skill 安装到应用隔离 Runtime Home;模板定义不写入 Skill。 | 不污染用户全局环境,避免业务规则双写。 | Runtime Bootstrap、打包 |-| DEC-7 | 每轮只提供 Job、模板、revision、阶段、当前选中项、最近变化和允许动作;大产物按需读取。 | 控制 Token,保证 Agent 使用最新状态。 | AgentContextBuilder |-| DEC-8 | KrillinAI P0 作为固定版本 CLI Sidecar,每个 StageRun 独立进程和工作目录。 | 当前 CLI 能力比 HTTP Server 完整,进程隔离和恢复语义清晰。 | StageRunner、打包 |-| DEC-9 | Codex 用于交互式理解和文本修改,批量 ASR、翻译、TTS、生图和视频阶段使用 CreatorServicesConfig 指定的生产服务。 | Codex 认证不能安全、稳定地冒充外部 API;生产阶段需要可重试、可计量和结构化结果。 | Agent、KrillinAI、配置 |-| DEC-10 | P0 只完成视频翻译真实闭环,但 P1/P2 必须复用同一领域契约,不允许再创建独立 React 状态流程。 | 用一个垂直切片验证架构,同时约束后续演进。 | 产品路线、所有模板 |-| DEC-11 | P1 视频下载由 OpenCreator Daemon 的 DownloadExecutor 直接封装打包固定版本的 yt-dlp,不等待 KrillinAI 新增下载命令。 | 下载是多个模板共用的输入能力,OpenCreator 需要直接掌握 probe、格式选择、进度和 Artifact 登记。 | P1 下载、打包、StageRunner |-| DEC-12 | P1 封面由 OpenCreator ImageExecutor 负责,使用 CreatorServicesConfig.image 调用 OpenAI-compatible 生成/编辑接口;多候选和比例由模板编排,KrillinAI `cover` 只作为兼容执行器而非首选所有者。 | 避免单图 CLI 限制,并固定参考图、多候选和多比例的扩展位置。 | P1 封面、图片配置、Artifact |--## 详细设计--### 全局架构--```mermaid-flowchart TB- subgraph UI[OpenCreator 界面]- W[工作台]- AP[Agent 面板:状态、动态、对话]- STORE[CreatorSessionStore]- W <--> STORE- AP <--> STORE- end-- subgraph CORE[OpenCreator Daemon]- CS[CreatorService]- TR[TemplateRegistry]- ACTION[Creator Action API]- RUNNER[StageRunner]- DB[(SQLite)]- FILES[(项目产物目录)]- CFG[CreatorServicesConfig / Keyring]- CS <--> TR- CS <--> DB- CS <--> FILES- ACTION --> CS- CS --> RUNNER- CFG --> RUNNER- end-- STORE <--> CS-- subgraph AGENT[Agent Runtime]- CONTEXT[AgentContextBuilder]- ADAPTER[AgentRuntimeAdapter]- RUNTIME[Codex / Claude Code]- SKILL[Runtime Skill]- CONTEXT --> ADAPTER- ADAPTER <--> RUNTIME- SKILL --> RUNTIME- end-- AP -->|用户发送消息| CONTEXT- CS --> CONTEXT- RUNTIME -->|工具调用| ADAPTER- ADAPTER --> ACTION-- subgraph EXEC[执行器]- KRILLIN[KrillinAI CLI Sidecar]- OTHER[其他执行器]- end- RUNNER --> KRILLIN- RUNNER --> OTHER-```--### CreatorSessionStore 与创作动态--1. Store 同时保存已确认 Session 快照和当前页面未提交草稿;工作台输入立即更新 Store,因此 Agent 状态区同步显示。-2. 普通文本输入按短 debounce 写入 CreatorService;执行、生成版本、删除或覆盖等重要动作等待 Daemon 确认。-3. 用户发送 Agent 消息前必须 flush 当前草稿,再构造 AgentContext,避免模型读取旧值。-4. CreatorService 对成功的语义操作返回 `CreatorActionReceipt`,至少包含 `actor`、`summary`、`affectedArtifacts`、`newRevision` 和时间。-5. 状态摘要实时派生;Activity 只记录语义变化。逐字符输入、鼠标移动和普通预览时间变化不得形成永久 Activity。-6. Agent 修改结果通过同一 Store 展示,并对相关控件或内容进行短时高亮;撤销仍通过 Creator Action 创建新 revision,不直接回滚前端状态。--### 最小数据模型--```text-creator_jobs- id, project_id, template_id, template_version,- status, revision, state_json, created_at, updated_at--creator_stage_runs- id, job_id, stage_id, executor, status,- progress_json, error_code, error_message,- started_at, finished_at--creator_artifacts- id, job_id, kind, version, status, path,- source_artifact_ids_json, metadata_json, created_at--creator_activities- id, job_id, revision, actor, action,- summary, details_json, created_at-```--`state_json` 由 TemplateDefinition 对应的 Schema 校验;列表和恢复所需字段保留为独立列。媒体文件不写入 SQLite。--### 状态语义--Job 状态:--```text-draft → running → needs_input → running → completed- ↘ failed / canceled-```--Daemon 重启时尚未结束的 StageRun 变为 `interrupted`,Job 根据是否可重试进入 `needs_input` 或保留 `failed` 原因。--Artifact 状态:--```text-draft | technical_preview | completed | stale-```--`completed` 只表示模板预期创作和技术校验完成,不代表发布或平台审核。--### TemplateDefinition--```ts-type CreatorTemplate = {- id: string;- version: number;- renderer: string;- inputSchema: unknown;- stages: Array<{- id: string;- executor: string;- dependsOn?: string[];- optional?: boolean;- allowedJobStatuses: string[];- inputArtifacts: Array<{- kind: string;- selector: "latest-completed" | "explicit-version";- optional?: boolean;- }>;- outputArtifacts: Array<{- kind: string;- status: "technical_preview" | "completed";- }>;- }>;- actions: Array<{- id: string;- inputSchema: unknown;- allowedStages: string[];- invalidates?: Array<{- sourceArtifactKind: string;- propagateThroughStageGraph: boolean;- }>;- }>;- outputs: Array<{ kind: string; required: boolean }>;- agentGuidance: string;-};-```--P0 模板以静态 TypeScript 对象注册,不实现通用 DSL。`agentGuidance` 只提供当前模板的简短创作语义,不能重复阶段和失效规则。CreatorService 只依据 `inputArtifacts/outputArtifacts` 构建产物依赖边,并从动作声明的源产物开始沿阶段图传播 `stale`;执行器不得自行定义另一套失效规则。--视频翻译的最小依赖实例:--```text-source_video- └─ subtitle stage- ├─ source_subtitle- └─ target_subtitle- ├─ tts stage → dubbed_audio- ├─ render-horizontal stage → horizontal_video- └─ render-vertical stage → vertical_video--render-horizontal / render-vertical 还读取 source_video,-启用配音时读取 dubbed_audio,未启用时该输入为 optional。-```--`edit-subtitle` 声明从 `target_subtitle` 开始传播失效,因此只将依赖该字幕版本的配音和横竖屏视频标记为 `stale`,源视频和源字幕保持有效。StageRunner 启动前必须解析每个必需输入的具体 Artifact 版本;缺少输入或输入不是 `completed` 时不启动执行器。--### Agent、Skill 与上下文--1. OpenCreator 安装包携带只读 `opencreator-runtime` Skill 和版本清单。-2. Daemon 启动时由 AgentRuntimeBootstrap 将其原子同步到应用专属隔离 Codex Home;不存在时安装,版本或哈希不一致时替换,初始化失败时禁用 Agent 但不影响工作台。-3. 创建 Codex Thread 的首轮 Prompt 由 CodexAgentAdapter 增加固定前缀 `$opencreator-runtime`,明确要求先加载该 Skill 并调用 `creator_get_context`;后续恢复同一 Thread。为抵抗会话压缩,后续每轮只重复 Skill 标识和契约版本,不拼接整份 `SKILL.md`。-4. 每轮动态上下文只包含 `jobId/templateId/templateVersion/revision/currentStage/selection/recentChanges/allowedActions`。-5. 字幕、脚本、分镜和历史版本由 Agent 通过范围读取工具获取。-6. AgentRuntimeAdapter 接口保持运行时无关,CodexAdapter 可用 MCP 或原生 Tools,ClaudeAdapter 可映射到其工具协议或兼容 MCP。-7. P0 不为每个模板创建 Skill。后续专业 Skill 只能补充非确定性的创作方法,不能成为业务规则权威位置。--运行时无关适配契约为:--```ts-type StableAgentGuide = {- id: "opencreator-runtime";- version: number;- contentHash: string;- instructions: string;-};--interface AgentRuntimeAdapter {- ensureStableGuide(guide: StableAgentGuide): Promise<{- status: "ready" | "failed";- runtimeLocation?: string;- errorCode?: string;- }>;-- startThread(input: {- guideId: string;- guideVersion: number;- toolSchemas: unknown[];- bootstrapContext: AgentContextEnvelope;- }): Promise<{ threadId: string }>;-- runTurn(input: {- threadId: string;- guideId: string;- guideVersion: number;- context: AgentContextEnvelope;- userMessage: string;- }): Promise<AgentTurnResult>;-}-```--CodexAdapter 通过隔离 `CODEX_HOME/skills` 和首轮 `$opencreator-runtime` 激活稳定指导;不支持 Skill 文件的运行时必须在 `ensureStableGuide` 中通过其开发者指令机制注入同一 `StableAgentGuide.instructions`。任何适配器无法确认稳定指导和 Creator Action 工具同时可用时,返回 `failed` 并禁用 Agent,不能继续无约束运行。--### Creator Action API--P0 保持最小工具面:--```text-creator_get_context(jobId)-creator_get_artifact(jobId, artifactId, range?)-creator_apply_action(jobId, action, expectedRevision, input)-```--`creator_apply_action` 由当前 TemplateDefinition 校验动作、阶段和输入;成功后在一个事务中更新 Job、Artifact 和 Activity,并返回新 revision。长任务动作创建 StageRun 并交给 StageRunner。--### AI 服务配置--1. 复用现有 CreatorServicesConfig 和系统 Keyring,不新建第二套多模态配置中心。-2. Agent Runtime 认证与生产服务配置分开:Codex/Claude 负责对话和交互式内容修改;KrillinAI/执行器使用文本、ASR、TTS、图片和视频配置。-3. P0 固定使用“独立启动目录 + 绝对 `--workdir`”配置桥接,不在实现阶段保留 `--config`/环境变量二选一。KrillinAIAdapter 为每个进程创建应用私有临时启动目录 `<app-data>/runtime/krillin-launch/<run-id>`,在其中写入 `config/config.toml` 和打包内置的默认字幕样式;CLI 的 `cwd` 指向该启动目录,`--workdir` 指向不含密钥的 Job StageRun 产物目录绝对路径。-4. 缺少必需配置时,StageRun 不启动,Job 进入 `needs_input` 并提供对应设置入口。--P0 字段映射的唯一权威表:--| OpenCreator CreatorServicesConfig | KrillinAI TOML |-| --- | --- |-| `proxy` | `app.proxy` |-| `llm.baseUrl/apiKey/model/jsonMode` | `llm.base_url/api_key/model/json` |-| `transcription.provider/enableGpuAcceleration` | `transcribe.provider/enable_gpu_acceleration` |-| `transcription.openai.*` | `transcribe.openai.*` |-| `transcription.fasterWhisper.model` | `transcribe.fasterwhisper.model` |-| `transcription.whisperKit.model` | `transcribe.whisperkit.model` |-| `transcription.whisperCpp.model` | `transcribe.whispercpp.model` |-| `transcription.aliyun.oss.*` | `transcribe.aliyun.oss.*` |-| `transcription.aliyun.speech.*` | `transcribe.aliyun.speech.*` |-| `tts.provider` | `tts.provider` |-| `tts.openai.*` | `tts.openai.*` |-| `tts.minimax.*` | `tts.minimax.*` |-| `tts.aliyun.oss.*` | `tts.aliyun.oss.*` |-| `tts.aliyun.speech.*` | `tts.aliyun.speech.*` |-| `image.provider/image.openai.*` | `image.provider/image.openai.*` |--KrillinAI 的非密钥运行参数使用 OpenCreator 打包时固定并版本化的基线配置,不开放为 P0 用户设置。POSIX 启动目录和配置文件权限分别为 `0700/0600`;Windows 在应用 LocalAppData 下创建目录并移除普通用户组继承,仅保留当前用户和 SYSTEM 访问。进程结束后在 `finally` 删除整个启动目录;Daemon 每次启动先清理没有对应活动子进程的遗留 `krillin-launch` 目录。启动目录不得被 Workspace 文件 API、诊断打包或产物扫描访问。--### KrillinAIAdapter 与进程模型--1. 正式安装包携带固定版本 KrillinAI CLI,运行时不克隆仓库。-2. `subtitle`、`tts`、横屏渲染、竖屏渲染和 `cover` 分别对应独立 StageRun;OpenCreator 不依赖 KrillinAI `pipeline/status`。-3. 每个 StageRun 使用独立工作目录、超时、取消令牌和进程树终止;最终 JSON、Manifest、stderr 和退出码统一归一化。-4. 字幕文件需解析验证;音视频需用 ffprobe 校验流、时长、分辨率和非空;封面需校验图片格式与尺寸。-5. P0 不使用现有 KrillinAI HTTP Server。若本地大模型预热经基准测试证明是常见流程的显著瓶颈,再设计由 Daemon 管理的私有 Worker,不直接复用旧 Server。--### 各阶段模板方案--#### P0 视频翻译--```text-素材输入-→ subtitle(下载/字幕获取/ASR/翻译)-→ 字幕编辑-→ 可选 tts-→ 可选横屏/竖屏 render-→ 预览-→ 导出-```--工作台提供字幕对照编辑、配音参数、横竖屏设置、版本预览和导出;Agent 可修改同一字幕与参数,并通过 Creator Action 启动阶段。--P0 真实边界验收矩阵必须全部通过,不能用单个媒体样例替代:--| 用例 | 输入 | 字幕编辑 | TTS | 输出 | 独立预期 |-| --- | --- | --- | --- | --- | --- |-| VT-1 | YouTube 公开短视频 | 修改并保存至少一条目标字幕 | 关闭 | 字幕文件 | 平台字幕可用时优先使用,不可用时按配置回退 ASR;保存后版本递增 |-| VT-2 | Bilibili 公开短视频 | 修改并保存字幕 | 开启 | 横屏视频 | 生成有效配音和横屏视频,字幕修改后的旧音频/视频为 `stale` |-| VT-3 | 本地 MP4 | 修改并保存字幕 | 开启 | 竖屏视频 | 生成有效配音和竖屏视频,分辨率与音视频流校验通过 |-| VT-4 | 本地 MP4 | 不修改 | 关闭 | 横屏视频 | 生成无目标语言配音的横屏字幕视频 |-| VT-5 | 不支持的平台 URL | 不适用 | 不适用 | 不适用 | 在执行下载前返回 `unsupported_source`,不创建假 StageRun 成功记录 |-| VT-6 | 支持输入但缺少所选 TTS 配置 | 不适用 | 开启 | 任一视频 | StageRun 不启动,Job 进入 `needs_input` 并定位到 TTS 设置 |--#### P1 视频下载--视频下载定位为基础能力和可独立工具,由 OpenCreator Daemon 的 `DownloadExecutor` 封装安装包内固定版本 yt-dlp:--```text-probe(url) → 平台、标题、时长、可用格式-download(url, format) → 本地媒体 Artifact-```--`probe` 输入 URL,输出标准化媒体元数据和可选格式;`download` 输入 probe 结果中的格式 ID,输出 `source_video` 或 `source_audio` Artifact,并持续产生真实下载进度。无支持平台、登录限制、版权/地区限制、格式消失和磁盘不足使用独立错误码。下载 Artifact 可直接作为视频翻译和自动剪辑输入,避免重复下载。KrillinAI 内部若仍需下载,只允许在没有预下载 Artifact 的兼容路径中使用。--#### P1 封面创作--```text-视频/图片/文字输入-→ 提取主题和关键帧-→ 形成创意简报-→ 多候选生成-→ 用户/Agent 调整-→ 比例适配-→ 导出-```--执行所有权固定在 OpenCreator `ImageExecutor`。其输入为 Prompt、比例、候选数量和可选参考图 Artifact,输出为逐张版本化 `cover_image` Artifact;OpenAI-compatible ProviderAdapter 分别实现图片生成和参考图编辑调用。模板通过多次独立请求生成候选,单张失败不覆盖其他成功候选,并以 `partial_success` 暴露失败项。Provider 不支持参考图编辑时返回 `unsupported_capability` 并要求用户更换服务,不能静默忽略参考图。KrillinAI 当前单 Prompt 单图 `cover` 只作为无参考图场景的兼容 Adapter。封面模板可独立使用,也可作为其他模板的可选阶段。--#### P2 自动剪辑--```text-字幕/转录-→ 高光片段分析-→ 候选片段工作台-→ 时间线和画幅调整-→ 字幕/配音/包装-→ 导出短视频-```--KrillinAI 复用字幕、TTS 和部分渲染;高光评分、裁切、重构和时间线由独立 ClipExecutor 负责。--#### P2 火柴人视频--```text-主题或脚本-→ 脚本版本-→ 角色与视觉风格-→ 分镜-→ 画面资产-→ TTS-→ 时间线合成-→ 预览和导出-```--KrillinAI 复用 TTS 和字幕;脚本、分镜、图像/动画资产和时间线合成由独立执行器负责。每个脚本段、分镜和资产仍作为 Artifact 管理。--## 异常、兼容、迁移与回滚--1. 当前 Demo 没有需要迁移的正式 CreatorJob;上线新模型后可保留旧 Demo 入口一段受控开发期,但不得把 React 本地状态转换成正式任务。-2. Agent Runtime 初始化失败时工作台继续可用,Agent 面板明确显示不可用原因;不使用无 Skill/无工具约束的静默降级。-3. CreatorAction 版本冲突返回可识别错误和最新 revision;Agent 重新读取,工作台保留用户最新修改。-4. KrillinAI 阶段失败保留工作目录和诊断引用,但日志脱敏;用户可重试当前阶段或修改配置,不删除已完成产物。-5. 新模板版本只影响新 Job;旧 Job 固定使用创建时版本。需要修订旧 Job 时显式创建升级副本,不就地改变行为。-6. 软件升级时 Runtime Skill 使用临时目录、哈希校验和原子替换;替换失败保留上一有效版本。-7. 若常驻 Worker 后续验证失败,可回滚为 P0 CLI 模式,CreatorService、StageRun 和 Artifact 协议不变化。--## 验收标准--| AC ID | 关联需求 | 前置条件 | 操作 | 可观察结果 | 验证层级 |-| --- | --- | --- | --- | --- | --- |-| AC-1 | FR-1 | 已创建任一创作任务 | 完成模板流程并导出 | 可获得内容成品;产品中不存在发布审批、账号上传或发布状态步骤 | 产品 E2E |-| AC-2 | FR-2、NFR-2 | Job 已有阶段、产物和 Activity | 刷新页面并重启 Daemon | Job、版本、产物、动态恢复;运行中阶段变为 `interrupted` 并可重试 | API + E2E |-| AC-3 | FR-3、FR-4、NFR-4 | 视频翻译工作台与 Agent 面板同时打开 | 在工作台切换语言、配音并编辑字幕 | Agent 状态立即更新,语义变化形成聚合 Activity,且没有创建 Codex Run | 前端集成测试 |-| AC-4 | FR-3、FR-4 | Agent 已绑定同一 Job | 让 Agent 修改字幕和输出设置 | 工作台显示修改、相关位置高亮、Activity 标记 actor=agent,并可撤销 | Agent 集成 E2E |-| AC-5 | BR-4 | Agent 获取 revision 后,工作台先产生新修改 | Agent 使用旧 revision 提交 | 返回版本冲突,工作台新修改不被覆盖,Agent 可刷新后继续 | Service 单元 + 集成 |-| AC-6 | BR-5 | 已有字幕、配音和渲染产物 | 修改字幕并保存 | 旧产物仍可查看,配音和视频标记 `stale`,重新生成创建新版本 | Service + E2E |-| AC-7 | FR-5 | 准备 VT-1 至 VT-6 的输入和对应生产服务配置 | 逐项执行视频翻译真实边界矩阵 | 每项得到表中独立预期;三类输入、字幕编辑、TTS 开关、横屏、竖屏和失败路径全部通过 | 参数化真实边界 E2E |-| AC-8 | FR-6、NFR-3 | Keyring 分别处于配置完整、缺必需字段、进程启动失败和进程崩溃四种条件 | 启动 KrillinAI 阶段并检查启动目录、数据库、日志、上下文、诊断包和导出包 | 字段按唯一映射生成;密钥仅短暂存在于受限启动目录;所有结束路径删除目录,Daemon 重启清理崩溃残留;其他位置无明文 | 安全集成测试 |-| AC-9 | BR-8 | 新安装、Skill 升级、Skill 损坏和写入失败四种条件 | 启动 Daemon | Skill 自动安装/升级/修复到隔离 Runtime Home,不改用户全局 Codex Home;无法就绪时 Agent 禁用且工作台可用 | Bootstrap 集成测试 |-| AC-10 | BR-6、BR-7、NFR-6 | 打包版本已包含 KrillinAI 和依赖 | 启动、取消、失败并重试一个真实阶段 | 进程树无残留,StageRun 状态准确,失败不产生假 Artifact,重试不覆盖旧结果 | 打包 App E2E |-| AC-11 | FR-7、DEC-11、DEC-12 | 打包 yt-dlp、DownloadExecutor 和 ImageExecutor 已实现,图片 Provider 支持生成与参考图编辑 | probe/download 素材,并以 Prompt、参考图和多比例生成多候选封面 | 下载 Artifact 可被翻译模板直接复用;候选逐张形成 Artifact,可比较、调整、部分失败、版本化和导出;不支持参考图时明确返回 `unsupported_capability` | P1 产品 E2E |-| AC-12 | FR-8 | P2 执行器实现 | 分别运行自动剪辑和火柴人模板 | 两者复用统一 Job/StageRun/Artifact/Activity/Agent Action,不出现独立本地状态业务链 | P2 架构 + 产品 E2E |-| AC-13 | NFR-1 | 同一 Daemon 数据、项目和内容视口 | 分别在 Web 与实际 Desktop App 执行相同创作操作 | 通用界面、状态、Runtime API、持久化结果和导出结果一致 | Web/Desktop 一致性 E2E |-| AC-14 | DEC-5、DEC-6、DEC-7、NFR-5 | 已安装稳定指导,准备真实 Codex 和一个不支持 Skill 文件的 Fake AgentRuntimeAdapter | 创建 Thread 并执行要求读取状态后修改内容的受控任务 | 真实 Codex 能发现并激活 `opencreator-runtime`、先读取 Context 再调用 Creator Action;Fake Adapter 通过等价稳定指导完成同一契约;激活失败时 Agent 被禁用 | Runtime 契约 + 真实 Codex 冒烟 |--## 测试策略--1. TemplateDefinition、Action Schema、阶段输入输出依赖图、失效传播、revision 和状态转换使用单元测试;视频翻译实例必须证明修改 `target_subtitle` 只传播到依赖它的 `dubbed_audio` 与横竖屏视频。-2. CreatorService 使用临时 SQLite 和文件目录验证事务、恢复、版本冲突、Activity 聚合和 stale 血缘。-3. CreatorSessionStore 使用 Fake CreatorService 验证工作台与 Agent 面板同源渲染,重点断言普通工作台操作不会创建 Agent Run。-4. AgentRuntimeAdapter 使用 Fake Runtime 验证最小上下文、按需读取、工具调用、冲突恢复和非 Skill 运行时的稳定指导注入;使用真实 Codex 验证 Skill 发现、首轮激活、Context 读取和 Creator Action 调用。-5. KrillinAIAdapter 使用伪进程覆盖退出码、超时、取消、JSON/Manifest 异常、配置目录清理和脱敏;真实 KrillinAI/FFmpeg 必须完成 VT-1 至 VT-6 矩阵,不允许用单个短媒体替代。-6. 正式交付前使用实际打包 App 验证 Sidecar 路径、依赖预检、进程终止、Web 资源一致性、Keyring 和导出。-7. P1/P2 每个模板必须在统一 Fake CreatorService 契约测试之外增加自身专用工作台与真实执行器测试。--## 分阶段交付边界--| 阶段 | 交付边界 | 完成条件 |-| --- | --- | --- |-| P0-A 共享创作骨架 | CreatorSessionStore、Agent 三层面板、TemplateRegistry、CreatorService、Action API | Fake 执行器下双向同步、恢复、冲突和 Activity 通过 |-| P0-B Agent 与 KrillinAI | Runtime Bootstrap、CodexAdapter、KrillinAIAdapter、配置桥接、媒体校验 | 真实短媒体阶段可执行、取消、失败和重试 |-| P0-C 视频翻译 | 完整翻译、字幕编辑、TTS、横竖屏、版本、预览、导出 | AC-1 至 AC-10、AC-13、AC-14 及 VT-1 至 VT-6 全部通过 |-| P1 | 独立下载能力和封面创作 | AC-11 通过,且复用 P0 领域契约 |-| P2 | 自动剪辑和火柴人视频 | AC-12 通过,核心生成由专用执行器完成 |--## 风险与未决问题--| 风险 | 处理 |-| --- | --- |-| Activity 信息过多 | 只记录语义操作,文本输入按对象和时间窗口聚合。 |-| Agent 与工作台并发修改 | expectedRevision 冲突保护,禁止静默覆盖。 |-| TemplateDefinition 与 Skill 漂移 | 业务规则只存在 TemplateDefinition;Skill 只保存稳定工具使用规则。 |-| KrillinAI CLI 缺少细粒度进度 | P0 展示真实阶段,JSONL 进度列为 KrillinAI 后续改造。 |-| 本地 ASR 模型重复预热 | 记录启动和预热指标;只有数据证明收益后引入受管 Worker。 |-| KrillinAI Windows 文件句柄和取消不完整 | 将进程树终止、临时目录释放和 CLI 测试失败纳入 P0 阻断项。 |-| 打包依赖跨平台差异 | 每个平台固定依赖清单并执行实际打包 App E2E。 |--当前没有需要用户在设计阶段决定的未决问题。Claude Code 的实际适配和常驻重模型 Worker 是否实现,分别由 P1 需求和真实性能数据触发,不影响 P0 契约。--## 独立审核记录--### Reviewer 原始结论--`REVISE`--### 问题处理--| 问题 ID | 严重程度 | Reviewer 关闭条件 | 处理决定 | 修改位置 | 关闭证据 | 遗留风险 |-| --- | --- | --- | --- | --- | --- | --- |-| R-01 | Major | 模板补齐阶段输入输出、前置状态和可解析失效图,并给出视频翻译实例与测试 | 采纳并关闭 | `TemplateDefinition`、视频翻译依赖实例、测试策略 | 阶段契约新增 `allowedJobStatuses/inputArtifacts/outputArtifacts`;失效仅沿该图传播;测试明确验证字幕到配音/渲染链 | 无 |-| R-02 | Major | 定义稳定指导激活契约、Codex 激活序列和非 Codex 等价机制,并增加真实/Fake 验收 | 采纳并关闭 | `Agent、Skill 与上下文`、AC-14 | 新增 AgentRuntimeAdapter 签名、首轮 `$opencreator-runtime` 激活、非 Skill 适配器注入和失败禁用;AC-14 覆盖真实 Codex 与 Fake Adapter | Claude Code 正式实现仍属后续交付,但不改变契约 |-| R-03 | Major | 固定 P0 配置机制、字段映射、cwd/workdir、安全权限与残留清理,并扩充安全 AC | 采纳并关闭 | `AI 服务配置`、AC-8 | 固定独立启动目录方案,列出完整字段映射、POSIX/Windows 权限、finally 清理和启动清扫;AC-8 覆盖缺配置、启动失败和崩溃 | KrillinAI 后续可增加 `--config`,但不影响 P0 机制 |-| R-04 | Major | 固定 P1 下载和封面的执行器所有权、接口、失败语义和验收 | 采纳并关闭 | DEC-11、DEC-12、P1 详细设计、AC-11 | 下载固定为 DownloadExecutor + yt-dlp;封面固定为 ImageExecutor + OpenAI-compatible Provider,明确输入输出和错误 | 图片 Provider 能力差异通过 `unsupported_capability` 显式处理 |-| R-05 | Major | P0 真实边界验收覆盖三类输入、字幕编辑、TTS 开关、横竖屏和失败路径 | 采纳并关闭 | VT-1 至 VT-6、AC-7、测试策略、P0-C 完成条件 | 参数化矩阵成为 P0 阻断条件,单个媒体样例不能替代 | 平台外部网络波动需在测试环境固定可用样例 |--全部 Major 已按 Reviewer 的可验证关闭条件修订,流程结论记为 `PASS`。Reviewer 原始结论保持为 `REVISE`,本版本不启动第二次 Reviewer。diff --git "a/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221-auto-video\350\241\214\344\270\272\347\255\211\344\273\267\345\220\210\345\220\214-2026-09-03.md" "b/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221-auto-video\350\241\214\344\270\272\347\255\211\344\273\267\345\220\210\345\220\214-2026-09-03.md"deleted file mode 100644index 8c802ed5..00000000--- "a/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221-auto-video\350\241\214\344\270\272\347\255\211\344\273\267\345\220\210\345\220\214-2026-09-03.md"+++ /dev/null@@ -1,124 +0,0 @@-# OpenCreator 火柴人视频与 auto-video 行为等价合同--> 状态:实施基线-> 参考实现:`auto-video@c85da4a2d86ec761baa0e697ed10d62982ff401b`-> 目标实现:`stickman-video@2`,TypeScript + CreatorJob + KrillinAI + Remotion--## 1. 等价边界--本合同约束生产行为,不要求复用 Python 代码,也不承诺模型输出逐像素一致。只有下列各项同时成立,才可称为与参考实现行为等价:--- 阶段先后关系、输入工件和输出工件一致。-- 来源先拆成有原文引用的 Claim,所有 Claim 必须明确保留或舍弃,不能静默遗漏。-- 脚本由一次 LLM 调用同时生成旁白、画面意图和生图描述;每段引用保留 Claim 及其原始来源片段。-- 角色参考图片以真实文件和 SHA-256 进入每次镜头生图请求。-- 旁白先按段生成,再以真实媒体时长建立分镜、字幕和时间线。-- 固定角色、品牌和 BGM 先物化并锁定风格合同,才允许全量镜头产生新的计费请求。-- 视觉、时间线、媒体和交付质量门真实执行;失败不得生成成功工件。-- 上游变化使所有依赖工件变为 `stale`,恢复时只复用指纹完全一致的成功工件。-- 占位资产、Fake Provider 和未验证媒体只能得到 `technical-draft`,不能得到 `publishable`。--## 2. 生产执行图--```text-文本或 URL 来源- -> source-brief- -> content-plan- -> script(一次生成旁白 + 画面意图 + 生图描述,并完成结构校验)- -> [唯一人工门:approve-script]- -> locked-script(审核稿锁定为新的不可变工件)- -> tts(逐旁白单元)- -> audio-timing(ffprobe 累计真实 TTS 时长)- -> storyboard(基于真实时间)- -> prompt-pack- -> character-reference(真实文件)- -> style-assets(物化角色、品牌、BGM)- -> style-calibration(自动合同锁)- -> images(全量镜头)- -> visual-validation- -> timeline + narration-srt- -> render-clean- -> media-validation- -> cover / bilingual-subtitles / publish-copy- -> bilingual-render- -> package-validation-```--工作台仍显示四个业务步骤;这些步骤是上述生产阶段的产品分组,不是第二套状态机。`CreatorCollaborationPanel` 是唯一 Agent、进度、Activity 和错误展示面。--## 3. 阶段与工件合同--| 阶段 | 必需输入 | 必需输出 | 硬性质量门 |-| --- | --- | --- | --- |-| `ingest-text` / `acquire-source` / `source-transcript` | 用户文本或 URL | `source_text` 或 `source_video` + `source_subtitle` | 输入非空;URL 媒体和字幕可读取 |-| `source-brief` | 来源文本 | `source_brief` | 每个来源片段进入至少一个 Claim;Claim 只能引用真实来源片段 |-| `content-plan` | `source_brief` | `content_plan` | 所有 Claim 必须且只能进入保留或舍弃集合;章节覆盖全部保留 Claim |-| `script` | `content_plan` + `source_brief` | `script_manifest` | 同一 Prompt 同时生成旁白、画面意图、生图描述;每段绑定 `claimIds` 和 `sourceSpanIds`;覆盖全部保留 Claim;满足总旁白预算;失败时携带整稿和校验原因重新生成整稿 |-| `approve-script` | 待审核 `script_manifest` | 新的已锁定 `script_manifest` | 审核状态为 approved、`contentLocked=true`;旧审核稿变为 stale;TTS 只能读取当前锁定稿 |-| `tts` | 已审核脚本中的单段旁白 | 每段一个 `narration_audio` | 真实非空音频;ffprobe 得到正时长;scope 与 segment 一致 |-| `audio-timing` | 全部段音频 | `audio_timing` | 每段 start/end/duration 来自 ffprobe;连续且总时长一致;30 秒任务真实总时长必须为 27–33 秒 |-| `storyboard` | `script_manifest` + `audio_timing` | `shot_spec` | 镜头时间必须引用真实 timing,不得按脚本估时比例分配 |-| `prompt-pack` | `shot_spec` | `image_prompt_pack` | 最终 Prompt 由画面意图、角色、风格、构图约束共同生成 |-| `character-reference` | `selectedPresetId` | `character_reference` | `path`、`sha256`、MIME、尺寸均存在;哈希与预设资源一致 |-| `style-assets` | `selectedPresetId` + 固定资源包 | `character_reference` + `style_contract` | 角色 `path`、`sha256`、MIME、尺寸均存在;哈希与预设资源一致 |-| `style-calibration` | `style_contract` | `style_calibration` | 自动合同锁必须证明风格、16:9 和角色引用完整 |-| `images` | 已校准 Prompt Pack + 角色参考图 | 每镜头一个 `shot_image` | 每个请求携带同一参考图字节;只复用相同指纹结果 |-| `visual-validation` | 全部镜头图 | `visual_validation` | 可解码、16:9、非空白、OCR 无字幕、哈希不重复;全部通过才成功 |-| `timeline` | `audio_timing` + 镜头图 + 音频 | `timeline_manifest` + `narration_subtitle` | 画面轨、旁白轨、字幕轨边界一致;SRT 机械导出自真实 timing |-| `render-clean` / `media-validation` | Timeline | `clean_video` + `media_validation` | Remotion 成功;ffprobe 和抽帧检查通过 |-| 交付阶段 | 已验证纯净视频 | 固定五项结果 + `delivery_manifest` | 文件存在、非空、哈希匹配、可探测;manifest 决定可发布性 |--## 4. Provider 请求合同--当 OpenAI 图像配置指向 RightCodes 兼容端点时,镜头图请求固定为:--```json-{- "model": "gpt-image-2",- "prompt": "<最终镜头 Prompt>",- "size": "1024x576",- "n": 1,- "quality": "auto",- "response_format": "b64_json",- "async": true,- "image": ["data:image/<type>;base64,<所选角色原始字节>"]-}-```--提交地址只能是 `/images/generations`,不能因有参考图而切换为 `/images/edits` multipart。异步响应必须保存 `task_id` 并查询原任务;远端是否接收未知时进入 `needs_input`,普通重试不得再次计费。--## 5. 审核、失败与失效矩阵--| 事件 | 当前工件 | 必须失效 | 不得发生 |-| --- | --- | --- | --- |-| 修改脚本 | 新 `script_manifest` | 旧锁定脚本、TTS、timing、分镜、Prompt、样图、全量图、Timeline、视频和交付 | 复用旧音频或旧时间线 |-| 修改单镜头画面描述 | 新 `shot_spec` | 对应 Prompt、样图/镜头图及全部聚合下游 | 删除无关镜头的当前图片 |-| 更换角色 | 新 `character_reference` | 全部样图、全量图、视觉校验、Timeline、视频和交付 | 只改 Prompt 文本而继续使用旧图 |-| 更换音色/TTS 模型 | 新分段音频 | timing、分镜节奏、Timeline、字幕、视频和交付 | 按旧估时拼接新音频 |-| 单镜头候选尺寸或内容校验失败 | 失败证据 | 当前候选不得晋级;按固定重试上限处理 | 把失败候选写成成功图片或继续下一镜头 |-| 任一真实依赖失败 | `failed` / `needs_input` | 下游保持缺失或 stale | 写入成功工件、显示 100% 成功、产出 publishable |--正常流程只保留脚本人工审核。样图自动校准成功后继续;自动检查无法证明可用时阻塞并给出可操作原因,不新增常态人工审核步骤。--旁白中的人物、事件和关系由脚本 Prompt 基于保留 Claim 与原始来源片段生成。Runtime 不通过制作词黑名单删词、替换句子或局部修补旁白,避免为了命中规则破坏语义;结构、引用闭环和预算不合格时,必须把完整失败原因交回模型并重新生成整稿。图片中禁止可见文字属于生图质量约束,只检查 `imagePrompt`,不参与改写旁白。--## 6. 进度与完成判定--- 同一时刻协作面板只展示一个当前业务进度。内部 scoped StageRun 可并行,但由 Adapter 聚合为单条标准进度。-- 标准进度只含 `phase`、`percent`、`message`、`completed`、`failed`、`total`,通用 Panel 不读取执行器私有字段。-- 等待执行的后续阶段不显示独立进度条;完成的内部阶段进入 Activity,不重复显示多条 100%。-- Fake Daemon、1x1 图片、伪 MP3、手填 duration 和跳过的真实 E2E 不能作为发布能力通过证据。-- `publishable` 只能由真实角色图、真实生图、真实 TTS、真实 timing/SRT、真实 Timeline、Remotion final、ffprobe、抽帧和包校验共同证明。--## 7. 验收最小样例--正式验收固定使用:短文本、`student` 非默认角色、3 个镜头、已配置的真实音色和真实图像服务。验收必须证明:--1. 每次生图请求中的参考图 SHA-256 与 `student.png` 一致。-2. 所有生成图为 16:9;单镜头候选按固定上限重试,耗尽后不得继续下一镜头。-3. 脚本一次生成旁白、画面意图和生图描述;每段引用有效的保留 Claim 和来源片段,且全部保留 Claim 都被覆盖。-4. TTS 恰好按脚本段数生成;每段时长来自 ffprobe,30 秒任务的真实总时长必须为 27–33 秒。-5. Storyboard 在 `audio_timing` 成功前没有 StageRun。-6. Timeline 三轨边界和 SRT cue 与真实 timing 一致。-7. 页面只显示一个当前进度,失败原因与 Daemon 事实一致。-8. 五项交付都通过实际文件、哈希、ffprobe/抽帧和 manifest 校验;否则状态保持 `BLOCKED`。diff --git "a/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221\347\224\237\344\272\247\344\273\273\345\212\241\351\207\215\346\236\204-\346\226\271\346\241\210-2026-08-31.md" "b/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221\347\224\237\344\272\247\344\273\273\345\212\241\351\207\215\346\236\204-\346\226\271\346\241\210-2026-08-31.md"deleted file mode 100644index 8ec3dd18..00000000--- "a/docs/specs/OpenCreator\347\201\253\346\237\264\344\272\272\350\247\206\351\242\221\347\224\237\344\272\247\344\273\273\345\212\241\351\207\215\346\236\204-\346\226\271\346\241\210-2026-08-31.md"+++ /dev/null@@ -1,264 +0,0 @@-# OpenCreator 火柴人视频生产任务重构方案--> 状态:草案-> 体量判断:复杂。该交付同时涉及 Creator 模板与状态、持久化数据清理、镜头级并发与幂等、外部付费 Provider、KrillinAI、Remotion、Web/Desktop 共用界面和正式打包门禁;各部分共同约束同一个可发布任务,无法独立批准或验收,因此保持一份内聚方案。-> 设计确认:已完成(D-1 至 D-3)-> Reviewer 原始结论:REVISE-> 流程结论:PASS-> 用户批准:已批准(2026-08-31)--## 背景、目标与非目标--### 目标--在 `feat-stick-video` 分支中删除现有火柴人 Demo 的业务实现,以 auto-video 当前真实生产链路为基线,重新实现唯一的 `stickman-video` Creator 任务。新任务必须使用 OpenCreator 已落地于视频翻译、图像生成等功能的 CreatorJob、StageRun、Artifact、CreatorAction、Revision、ResultSnapshot 和 Agent 协作架构,并由 OpenCreator、KrillinAI 与 Remotion 按明确边界共同完成五项交付物。--### 非目标--- 不保留旧火柴人模板、执行器、页面状态或兼容入口。-- 不迁移或恢复旧火柴人 Demo Job。-- P0 不恢复 auto-video 旧设计文档中的十三项多平台交付合同。-- 不把脚本审核、分镜审核、交付包等火柴人产品语义放入 KrillinAI。-- 不把 auto-video 的 Python 实现、解释器或依赖放入 OpenCreator 源码运行链路或火柴人 Runtime;既有 Creator Runtime 中受 Manifest、版本和哈希约束的便携 Python `yt-dlp` 保持原有媒体获取职责,不扩展为火柴人业务实现。-- 不借本任务重构视频翻译、图像生成及其他 Creator 模板。--## 用户需求原文--1. `auto-video是自动生成视频的项目,我现在希望把当前这个功能合并到opencreator里面,就像Krillinai提供视频下载、字幕生成等能力一样,需要给出技术方案分析,因为auto-video是Python实现的,opencreator不太适合引入更多语言,有两种选择:1. 用OpenCreator的ts重构 2. 放到Krillinai里面重构,或者你有没有更好的方案,评估一下`-2. `你推荐的方案整体没问题,需要修正下,auto-video是对应 火柴人生成,目前OpenCreator的 火柴人生成,还是之前的demo,并没有按照 视频翻译、图像生成等这些按照新的架构设计出来的任务,所以需要你重新评估下`-3. `$zhiyu-brainstorm 1. 从OpenCreator拉取一个新的分支 feat-stick-video开发。2. 不要留兼容模式,stickman-video就只有一个版本,可以使用现有demo的功能交互设计,但底层只有一套`-4. D-1 确认:`没问题,继续`-5. D-2 确认:`没问题,继续`-6. D-3 确认:`没问题,继续`--## 事实基线与假设--| 证据 | 已确认事实 | 对设计的影响 |-| --- | --- | --- |-| `apps/web/src/features/dashboard/StickmanVideoWorkspace.tsx` 的 `storyboardShots`、`resultVersions`、`generateStoryboard`、`generateVideo` | 现有火柴人页面以硬编码分镜和 React 本地结果为主,调用后端后会立即标记结果就绪 | 现有业务状态和结果逻辑必须删除,只允许复用交互与视觉设计 |-| `apps/daemon/src/creator/templates/stickman-video.ts`、`creator/stickman/executor.ts` | 现有模板只有简化的 script、storyboard、narration、render 四阶段,未形成真实审核、版本和完整交付闭环 | 直接替换模板和执行器,不以现有实现为增量基座 |-| `creator-session-store.tsx`、`creator/service.ts`、`creator/stage-runner.ts`、`creator/result-snapshots.ts` | OpenCreator 已具备持久 CreatorJob、Revision、StageRun、Artifact、stale 血缘、事件同步和结果快照 | 新任务复用 Creator 通用领域模型,不迁移 auto-video 的 SQLite 与 Runner |-| `video-translation.ts`、`video-translation-actions.ts` | 视频翻译已经形成模板、工作流推进、配置门、reconcile/recover 和 KrillinAI 执行边界 | 火柴人任务按同一新架构建立专属 Workflow Controller |-| `packages/protocol/src/krillin-opencreator.ts`、KrillinAI `internal/opencreatorapi` | KrillinAI 暴露下载、字幕、TTS、横竖屏渲染等媒体能力,并具有任务、事件、Manifest 和幂等字段 | 只复用通用媒体原子能力,不向 KrillinAI 下沉火柴人产品状态 |-| auto-video `application/factory.py`、`stages/*`、Remotion 模板 | auto-video 的 Python 主要承担编排、合同和工件处理,字幕已调用 KrillinAI,Remotion 模板本身是 TypeScript | Python 作为行为参考和黄金基线,不作为最终 Runtime |-| 当前 Git 状态 | 已从最新 `origin/main` 创建本地 `feat-stick-video`,未跟踪的 `auto-video/` 目录保持不变 | 后续方案、Plan 和实现均以该分支为工作分支;首次有效提交后再推送远端 |--假设:P0 输入为有效的 YouTube 公共链接;当前 auto-video 实际五项交付合同是本轮功能基线;旧火柴人 Demo 数据不具有需要保留的生产价值。不存在未决问题。--## 设计确认记录--| 设计部分 | 核心决定 | 用户确认原话 |-| --- | --- | --- |-| D-1 产品范围与替换策略 | 直接重做唯一 `stickman-video`;清理旧 Demo Job;P0 交付纯净视频、封面、发布文案、双语视频和双语 SRT;不新增 Python 火柴人实现或 Runtime | `没问题,继续` |-| D-2 技术架构与任务数据流 | OpenCreator TS 编排,KrillinAI 承担媒体原子能力,Remotion 使用 Node Worker;页面、Agent、版本和进度全部由 CreatorJob、StageRun 和 Artifact 驱动 | `没问题,继续` |-| D-3 失败恢复、测试与交付门禁 | 定义中断恢复、付费请求安全、镜头级幂等、旧数据清理、Web/Desktop 一致性和实际打包 App 门禁 | `没问题,继续` |--## 需求与业务规则--| ID | 类型 | 优先级 | 描述 |-| --- | --- | --- | --- |-| FR-1 | 功能需求 | P0 | 产品中只存在一套可真实运行的 `stickman-video` 工作台、模板、工作流和执行实现;页面可以沿用 Demo 的交互设计,但所有完成状态来自持久任务数据。 |-| FR-2 | 功能需求 | P0 | 用户输入有效 YouTube 链接并完成脚本、分镜审核后,任务自动完成内容理解、图片、配音、时间线、纯净成片、字幕、封面、发布文案和交付校验。 |-| FR-3 | 功能需求 | P0 | 用户和 Agent 可以编辑脚本、审核分镜、重生成单镜头并查看历史结果;修改只使受影响 Artifact 及其下游结果失效。 |-| FR-4 | 功能需求 | P0 | CreatorJob 是工作台与 Agent 的共享权威状态;刷新页面、重启 Daemon 或恢复外部任务后,阶段、审核、进度、版本和结果保持一致。 |-| BR-1 | 业务规则 | P0 | 不保留兼容模式;TemplateRegistry 只注册当前生产定义 `stickman-video@2`,不注册旧 `@1`;旧 Demo Job 及其关联数据通过一次性迁移定向删除。 |-| BR-2 | 业务规则 | P0 | OpenCreator 负责产品编排、审核、状态、血缘和交付;KrillinAI 只负责通用媒体能力;Remotion 只负责按照已登记时间线渲染。 |-| BR-3 | 业务规则 | P0 | 前端不得维护独立结果版本或自行宣布成功;所有可展示结果来自 `completed` 或历史 `stale` Artifact 及 ResultSnapshot。 |-| BR-4 | 业务规则 | P0 | 具有计费副作用的 Provider 在远端接受状态未知时不得自动再次提交;单镜头成功结果必须在其他镜头失败或重试时保留。 |-| BR-5 | 业务规则 | P0 | P0 最终交付固定为纯净视频、YouTube 封面、YouTube 发布文案、双语视频和双语 SRT 五项文件,并由 Delivery Manifest 逐项验真。 |-| NFR-1 | 非功能需求 | P0 | 火柴人源码、Daemon、Stickman Runtime 和 `app.asar` 不包含 Python 实现或 Runtime;既有 Creator Runtime 的便携 Python `yt-dlp` 只能用于统一媒体获取,必须由独立 Manifest 固定版本、文件集和哈希。Remotion、Chromium、字体、素材和 KrillinAI 依赖同样必须固定版本并记录哈希。 |-| NFR-2 | 非功能需求 | P0 | Web 与实际 Desktop App 在相同内容视口、Job 和设置下具有相同通用界面、动作、Runtime 请求、持久化结果和交付结果。 |-| NFR-3 | 非功能需求 | P0 | Desktop 正式打包必须从当前工作区重新构建 Web,记录 commit、dirty 状态、Web 构建标识或哈希、平台、架构和构建时间,并逐文件比较 `apps/web/dist` 与 App 内嵌 Web 目录的文件列表和内容哈希。 |--需求追踪:FR-1 由 AC-1、AC-7 验证;FR-2 由 AC-2 验证;FR-3 由 AC-3、AC-6 验证;FR-4 由 AC-5、AC-6、AC-10 验证;BR-1 由 AC-1、AC-7 验证;BR-2 由 AC-2、AC-9 验证;BR-3 由 AC-1、AC-5 验证;BR-4 由 AC-3、AC-4 验证;BR-5 由 AC-2 验证;NFR-1 由 AC-9 验证;NFR-2 由 AC-8 验证;NFR-3 由 AC-9 验证。--## 方案比较与推荐--| 方案 | 状态与调用方影响 | 失败与维护成本 | 结论 |-| --- | --- | --- | --- |-| OpenCreator 全量 TS 重写 | 产品状态自然落入 Creator 架构,但会在 TS 中重复下载、ASR、TTS、字幕和媒体渲染能力 | 媒体实现和跨平台依赖维护面过大 | 不采用 |-| 整条火柴人流水线放入 KrillinAI | OpenCreator 只能把高层流程视作黑盒,或被迫与 KrillinAI 双写阶段、审核和版本 | Go Runtime 被产品语义污染,Agent 与 UI 的逐镜修改、stale 血缘和恢复复杂 | 不采用 |-| Python Sidecar | 最快复用 auto-video,但新增解释器、依赖、跨平台环境和另一套状态账本 | 与“不引入更多语言”和正式打包约束冲突 | 只作为测试基线,不进入产品 |-| OpenCreator Creator 编排 + 专用 TS Executor + KrillinAI + Remotion Worker | CreatorJob 保持唯一状态源,媒体能力通过现有 Runtime 边界复用,Remotion 使用原生 Node 生态 | 需要补充镜头级 StageRun 和 Provider 请求安全,但边界可测试、可恢复 | 推荐 |--## 关键设计决策--| DEC ID | 决策 | 理由 | 约束范围 |-| --- | --- | --- | --- |-| DEC-1 | 保留模板 ID `stickman-video`,当前 Registry 只注册单一 `version: 2` 生产定义并删除旧 `@1` 定义;旧数据定向删除,不保留 Legacy 模块或并行注册版本 | 仍满足“只有一个版本”,同时让旧代码的 Registry 无法识别或运行新 `@2` Job,避免代码回滚后用 Demo 语义打开生产数据 | TemplateRegistry、数据库迁移、Web 路由、结果打开逻辑、回滚 |-| DEC-2 | CreatorService 是业务状态唯一权威;OpenCreator TS 承担内容、审核、时间线和交付,KrillinAI 承担通用媒体能力,Remotion 在隔离 Node Worker 中渲染 | 复用新 Creator 架构和既有媒体 Runtime,同时保持产品语义在 OpenCreator | Daemon、Krillin 协议、渲染、UI、Agent |-| DEC-3 | 审核使用 `needs_input` 和显式 CreatorAction;大内容存为 Artifact,Job State 只保存设置、选择和审核状态;结果版本由 ResultSnapshot 派生 | 避免假 Stage、前端双状态和大对象状态漂移,支持重启恢复与 Agent 协作 | Template、Workflow Controller、CreatorSession、Artifact |-| DEC-4 | 为昂贵的动态项目执行引入 `scopeKey` 与 `inputFingerprint`;Provider 请求在提交前持久化请求身份,在远端状态未知时阻止自动重试 | 支持单镜头重生成、部分成功、精确 stale 和计费安全 | StageRun、ImageExecutor、Provider Ledger、恢复逻辑 |-| DEC-5 | P0 固定五项交付合同;Remotion、Chromium、字体、角色素材和 KrillinAI 进入正式资源 Manifest 与实际打包 App 校验 | 防止目标漂移、运行时安装和不可复现资源;满足 Desktop 发布门禁 | Delivery、资源打包、Desktop E2E、发布 |--## 详细设计--### 模块边界--直接替换现有 `templates/stickman-video.ts`、`creator/stickman/*` 和 `StickmanVideoWorkspace.tsx` 的业务实现,不创建 Legacy 目录。新增 `stickman-video-actions.ts` 作为模板专属 Workflow Controller;它与视频翻译工作流保持同一调用模式,负责自动推进、配置门、审核门、幂等排队、`reconcile` 和 `recover`。--执行所有权固定如下:--| 能力 | 执行者 | 主要输入 | 主要输出 |-| --- | --- | --- | --- |-| 来源获取 | OpenCreator DownloadExecutor | YouTube URL | `source_video` |-| 来源转录 | KrillinAI subtitle | `source_video` | `source_subtitle` |-| 摘要、计划、脚本、分镜规格 | TS LLM Executor | 上游文本 Artifact、用户创作设置 | `source_brief`、`content_plan`、`script_manifest`、`shot_spec` |-| 分镜图片、封面候选 | OpenCreator ImageExecutor | `shot_spec`、`character_reference`、Prompt、Provider 设置 | `shot_image`、`cover_image` |-| 配音 | KrillinAI tts | 已批准脚本或字幕 | `narration_audio` |-| 图片和媒体技术校验 | TS + `sharp`、按需 Tesseract、FFprobe | 图片、音视频 Artifact | 校验元数据或失败 |-| 时间线 | TS Timeline Executor | 已批准镜头、图片、音频 | `timeline_manifest` |-| 纯净视频 | Remotion Node Worker | `timeline_manifest` 和受信 Artifact | `clean_video` |-| 双语字幕与视频 | KrillinAI subtitle/render-horizontal | `clean_video`、语言和字幕设置 | `bilingual_subtitle`、`bilingual_video` |-| 发布和交付 | TS Delivery Executor | 结果 Artifact、脚本、内容计划 | `publish_copy`、`delivery_manifest` 和五项交付文件 |--KrillinAI 协议不得增加火柴人产品级 Stage。若现有媒体能力缺失,只允许增加可被其他模板复用的通用媒体能力,并同步 TS 类型、JSON Schema、Go DTO 和合同测试。--### 阶段与审核数据流--执行 DAG 为:--```text-acquire-source-→ source-transcript-→ source-brief-→ content-plan-→ script-→ [approve-script]-→ storyboard-→ [approve-storyboard]-→ images ─────┐-→ narration ──┤- ▼- visual-validation- ↓- timeline- ↓- render-clean- ↙ ↓ ↘- cover subtitles publish-copy- ↓- bilingual-render- ↘ ↓ ↙- package-validation-```--`approve-script` 和 `approve-storyboard` 是 Action,不注册无执行内容的假 Stage。对应上游 Stage 成功后,Workflow Controller 将 Job 切换为 `needs_input` 并持久化审核对象、来源 Artifact 和 revision;只有针对当前 revision 与当前 Artifact 的批准才能继续。--CreatorAction 至少包括:`update-settings`、`approve-script`、`edit-shot`、`approve-storyboard`、`regenerate-shot`、`approve-visuals`、`run-stage`、`commit-version`、`retry-stage`、`resolve-provider-request` 和 `undo-action`。每个 Action 使用显式 Zod Schema,不使用无边界通用 Record 代替业务合同。--### Job State、Artifact 与结果版本--Job State 只保存来源 URL、角色/参考图选择、创作偏好、语言与配音设置、BGM 设置、当前 UI 步骤、审核状态、当前结果选择和必要的 Artifact ID。脚本、分镜、时间线、字幕、媒体和发布文本都存为 Artifact。--核心 Artifact 包括:`source_video`、`source_subtitle`、`source_brief`、`content_plan`、`script_manifest`、`shot_spec`、`character_reference`、`shot_image`、`narration_audio`、`timeline_manifest`、`clean_video`、`bilingual_subtitle`、`bilingual_video`、`cover_image`、`publish_copy` 和 `delivery_manifest`。--每个 Artifact 必须保存版本、SHA-256、来源 Artifact ID、作用域、模板与模型配置快照,以及媒体适用的 MIME、尺寸、时长等技术证据。ResultSnapshot 只从已登记 Artifact 生成,允许历史结果继续查看;上游变化后旧结果保留为 `stale`,不得作为新运行输入静默复用。--### 镜头级执行与失效--CreatorStageRun 增加可选 `scopeKey` 和 `inputFingerprint`。图片阶段按镜头创建独立 StageRun,例如 `stageId=images`、`scopeKey=shot-07`,指纹覆盖镜头 Prompt、角色参考、风格、模型和所有直接输入 Artifact 哈希。同一 `stageId + scopeKey + inputFingerprint` 只能存在一个活动执行。--修改 `shot-07` 只使该镜头图片以及依赖它的视觉校验、时间线、视频和交付结果失效;其他镜头图片保持 `completed`。Workflow Controller 在进入聚合阶段前校验已批准 Storyboard 中每个 shot 都有匹配当前指纹的成功 Artifact。--### Provider 请求安全--对计费 Provider 持久化请求账本,最少包含 provider、stageRunId、scopeKey、requestKey、requestHash、remoteTaskId、billingSideEffect、status 和 resultArtifactId。流程必须先登记稳定请求身份,再提交远端,再登记 Remote ID,最后登记结果 Artifact。--恢复时优先按 Remote ID 查询;没有 Remote ID 时只有 Provider 明确支持 requestKey 查询才可自动恢复。无法判断远端是否已接受的请求进入 `needs_input`,不得默认再次提交。已经成功的其他镜头 Artifact 不因单项失败而删除或覆盖。--未知计费请求只能通过 `resolve-provider-request` 处置,其 Zod 合同固定为请求账本 ID、当前 revision 和以下一种决策:--| 决策 | 行为 |-| --- | --- |-| `query` | 仅当 Provider 声明支持 Remote ID 或 requestKey 查询时继续查询原请求;不创建新计费请求 |-| `confirm-resubmit` | 只允许用户角色提交,并要求 `acceptDuplicateBilling: true`;原账本标记为 `abandoned_unknown`,新请求使用新的 generation、requestKey 并记录 `resubmissionOf` |-| `cancel-scope` | 将未知请求和对应镜头执行标记为已取消,不生成假 Artifact;必需镜头仍阻止聚合,用户需编辑或移除该镜头后继续 |--普通 `retry-stage` 必须拒绝存在 `unknown_remote_acceptance` 的计费请求。每次处置写入 Creator Activity,记录 actor、账本 ID、决策和 revision,但不得记录凭证;Agent 可以建议处置,不能代替用户执行 `confirm-resubmit`。--### 前端和 Agent--现有 Demo 的步骤布局、角色选择视觉、分镜弹窗、配音设置、结果页和版本菜单可以继续使用,但所有数据改由 CreatorSession 提供。表单通过 `updateDraft` 持久化,执行通过 CreatorAction 发起,进度由 StageRun 事件驱动,分镜由 `shot_spec` 与 `shot_image` 渲染,结果菜单由 ResultSnapshot 派生。--删除前端的硬编码 `storyboardShots`、本地 `resultVersions`、`storyboardReady`、`videoReady` 和调用后立即成功的逻辑。工作台和 Agent 对同一 Job 使用 `expectedRevision`;冲突时拒绝旧 revision,重新加载后再提交,不覆盖另一入口的较新修改。--火柴人必须复用唯一 `CreatorCollaborationPanel`,不得创建独立 Agent Panel。`creator-panel-adapters.ts` 新增 `stickmanVideoPanelAdapter` 并由 `creatorPanelAdapterFor('stickman-video')` 选择;Adapter 负责全部 P0 Stage 和 Phase 的中英文文案、`approve-script`、`edit-shot`、`approve-storyboard`、`regenerate-shot`、`approve-visuals`、`resolve-provider-request` 等 Activity 语义、无意义草稿 Activity 过滤,以及连续同阶段/同镜头更新的合并去重。--镜头级进度只读取 CreatorStageRun 的标准字段 `phase/percent/message/completed/failed/total/scopeKey`,不得读取执行器私有 Payload。协作面板必须展示真实镜头完成数、失败数和总数,并把脚本审核、分镜审核、渲染、字幕和交付映射为可识别阶段。--### Remotion Worker--Remotion 使用固定版本 `@remotion/bundler` 与 `@remotion/renderer`,由 Daemon 启动隔离 Node 子进程。Worker 只接收受信时间线、Artifact 路径和当前 Stage 工作目录;崩溃只使当前 StageRun 失败。运行时不得执行 `npm install` 或下载不受控 Chromium。--模板、Chromium、字体、角色和固定素材进入 Desktop 资源 Manifest,逐文件记录版本和 SHA-256。输出必须位于当前 Stage 工作目录,完成技术校验后才能登记 `clean_video` Artifact。--## 异常、兼容、迁移与回滚--### 状态和恢复--StageRun 使用 `queued/running/succeeded/failed/interrupted`;配置、审核或远端未知状态通过 Job `needs_input` 表达。Daemon 重启时未结束 StageRun 转为 `interrupted`,Workflow Controller 依据已完成 Artifact、输入指纹、请求账本和父 StageRun 幂等键恢复。成功且指纹未变化的阶段不重跑;Stage 成功但后续排队中断时由 `reconcile` 补排。--用户取消时终止 Remotion、FFmpeg、KrillinAI 和其他子进程树;未通过最终校验的临时文件不登记 Artifact。日志和进度不得输出 API Key、Token、完整 Provider 请求或其他凭证。--### Demo 数据迁移--一次性数据库迁移在事务内定向识别 `template_id='stickman-video' AND template_version=1` 的旧 Job,删除其 StageRun、Artifact、Activity、Agent 关联记录和 Job,并写入迁移标记。事务提交后,只允许在经过根目录约束和路径越界检查后删除这些 Job 的 Creator 文件目录。其他模板数据、`stickman-video@2` Job 和项目文件不得修改。--不提供旧 Demo 数据恢复、Legacy 页面或旧执行器。旧 Demo 主要结果原本是前端内存状态,设计不建立无事实依据的兼容层。--### 发布和回滚--开发只在 `feat-stick-video` 进行,首次有效提交后推送远端。合并前同步最新 `origin/main`,解决 Creator 架构相关冲突并重新执行直接受影响门禁。所有门禁通过前不合并主分支。--发布前可以通过不合并或回滚分支提交撤回功能;数据库清理一旦在用户环境执行,代码回滚不会恢复旧 Demo Job。该不可逆性是用户已确认“不保留兼容模式”的直接结果,发布说明必须明确。新生产任务固定为 `stickman-video@2`,旧代码只注册 `@1`,因此必须以 `Unknown creator template: stickman-video@2` 拒绝打开、修改或运行新任务,不能回退到 latest 或按模板 ID 猜测解释。--## 验收标准--| AC ID | 关联需求 | 前置条件 | 操作 | 可观察结果 | 验证层级 |-| --- | --- | --- | --- | --- | --- |-| AC-1 | FR-1、BR-1、BR-3 | 使用新代码、旧代码 Registry 和清洁测试库 | 枚举模板、创建新任务、打开火柴人页面,并尝试用旧 Registry 加载新 Job | 新 Registry 只枚举 `stickman-video@2`;无硬编码分镜、本地结果版本或旧执行器;旧 Registry 明确拒绝加载、修改和运行 `@2` Job | 静态检查 + 单元测试 |-| AC-2 | FR-2、BR-2、BR-5 | 配置真实生产 Provider、KrillinAI 和固定短 YouTube 输入 | 完成脚本与分镜审核并等待流水线结束 | 产生可播放纯净视频、1280x720 封面、发布文案、可播放双语视频和合法双语 SRT;Delivery Manifest 的路径、哈希和技术参数全部匹配 | 真实流水线 E2E |-| AC-3 | FR-3、BR-4 | 已完成含多个镜头的结果版本 | 修改一个镜头并重生成 | 只产生该镜头的新 StageRun/Artifact,其他镜头保持有效;时间线、视频和交付被精确标记 stale 后生成新版本 | Service 集成测试 |-| AC-4 | BR-4 | Fake Provider 支持故障注入和可配置查询能力 | 在远端接受请求后、Remote ID 持久化前模拟崩溃;分别执行查询、普通重试、用户确认重提交和取消作用域 | 可查询时恢复原任务;不可查询时普通 `retry-stage` 被拒绝;只有用户提交 `acceptDuplicateBilling: true` 才创建新 generation;取消不产生假 Artifact 且保留审计 Activity | Provider 故障注入测试 |-| AC-5 | FR-4、BR-3 | 流水线分别处于运行、审核和完成状态 | 刷新页面并重启 Daemon | Job、阶段、进度、审核对象、ResultSnapshot 和可打开 Artifact 完整恢复;中断阶段可安全继续 | API + 浏览器 E2E |-| AC-6 | FR-3、FR-4 | 工作台和 Agent 同时打开同一 Job | 工作台先修改,Agent 再使用旧 revision 提交;随后 Agent 刷新并修改镜头 | 旧 revision 返回可识别冲突且不覆盖新数据;刷新后双方看到相同 Job 和 Artifact | Service + Agent 集成测试 |-| AC-7 | FR-1、BR-1 | 数据库含旧 `stickman-video@1` Demo Job、新 `@2` Job 和其他模板 Job | 执行升级迁移 | 仅旧 `@1` Job 及关联数据被定向删除,新 `@2` 和其他 Creator Job、Artifact、文件保持不变;重复迁移无副作用 | 数据迁移测试 |-| AC-8 | NFR-2 | 同一 Fake Daemon、Job、偏好和内容视口,以及实际 Desktop App | 执行项目规定的完整 Web/Desktop 一致性套件,并在两端完成审核、单镜头重生成、协作面板查看和结果查看 | 首页、项目选择、设置、输入区、文件工作区及火柴人通用文案、按钮、状态、关键尺寸、CreatorAction、Runtime API、持久化和交付结果一致;Desktop 原生入口仍按 capability 工作 | Web/Desktop 一致性 E2E + 实际 App E2E |-| AC-9 | BR-2、NFR-1、NFR-3 | 当前工作区准备正式 Desktop 打包,允许工作区 dirty 状态被如实记录 | 运行正式打包链路、资源合同校验和实际 App 火柴人 E2E | 打包前重新构建当前 `apps/web/dist`;构建清单记录 commit、dirty、Web 构建标识或哈希、平台、架构和时间;App 内嵌 Web 与本次 dist 的完整文件列表和逐文件哈希完全一致;Remotion、Chromium、字体、素材和 KrillinAI Manifest 有效;Daemon、Stickman Runtime 和 `app.asar` 无 Python Runtime,Creator Runtime 仅允许受独立 Manifest/哈希合同约束的便携 Python `yt-dlp`;任一不一致均阻止交付 | 构建清单 + 完整哈希比较报告 + 打包合同 + 实际 App E2E |-| AC-10 | FR-4 | Job 含工作台、Agent、镜头进度和各类火柴人 Activity | 在唯一 CreatorCollaborationPanel 中执行设置修改、审核、镜头重生成、失败重试和 Provider 处置 | `stickmanVideoPanelAdapter` 提供全部 P0 Stage/Phase 文案,过滤无意义 Activity,合并连续同阶段/同镜头更新,展示标准字段产生的真实 completed/failed/total;未创建独立 Panel,也未读取执行器私有字段 | Adapter 单元测试 + Panel 组件测试 |--## 测试策略--- 单元层验证 Zod Action/Artifact 合同、时间线、指纹、作用域、血缘失效、Delivery Manifest 和路径约束。-- Service 集成层使用临时 SQLite 和文件目录验证 revision、审核门、镜头级 StageRun、部分成功、恢复、取消、迁移和 ResultSnapshot。-- Provider 层使用 Fake LLM、Fake Image Provider、Fake KrillinAI 验证幂等、未知提交状态、超时、Remote ID 恢复、配置缺失和错误映射;真实 Provider 测试只使用受控短输入并避免无界计费。-- 前端层验证页面只消费 CreatorSession、StageRun 和 Artifact,运行中不提前显示成功,刷新和冲突后能够恢复;不以硬编码媒体或本地版本冒充结果。-- 协作层验证 `stickmanVideoPanelAdapter` 的 Stage/Phase 文案、Action Activity、过滤去重、镜头级真实进度和唯一 `CreatorCollaborationPanel` 选择逻辑。-- 真实边界使用一条固定短视频验证 KrillinAI、Remotion、字幕、双语烧录和五项交付合同。-- 发布层执行项目完整 Web/Desktop 一致性套件、当前工作区 Web 新鲜构建、构建清单字段校验、`apps/web/dist` 与 App 内嵌资源的完整文件列表和逐文件哈希比较、实际打包 App E2E、Creator Runtime 与 Remotion 资源校验,以及安装包 Python Runtime 扫描。--## 风险与未决问题--| 风险 | 处理 |-| --- | --- |-| Remotion Chromium 和字体增大安装包并存在跨平台差异 | 固定版本和资源哈希,逐平台运行实际打包 App;未通过平台不得发布 |-| 图片 Provider 缺少服务端幂等查询 | 正式流水线阻止未知状态自动重试,通过 `needs_input` 显式处理 |-| 镜头级 StageRun 扩展影响共享 Creator 核心 | 字段设计为可选,只改变火柴人及明确使用 scope 的执行路径;共享回归由 Creator Service 定向测试覆盖 |-| 旧 Demo 数据清理不可逆 | 定向事务、路径守卫和迁移测试;发布说明明确不兼容决定 |-| auto-video 当前测试没有完整真实整链覆盖 | 使用黄金输入输出和新 Fake/真实 E2E 建立新的可执行证据,不把旧单元测试通过视为迁移完成 |--未决问题:无。--## 独立审核记录--Reviewer 原始结论:`REVISE`。--| 问题 ID | 严重程度 | 处理决定 | 修改位置 | 关闭证据或不采纳理由 | 遗留风险 |-| --- | --- | --- | --- | --- | --- |-| R-01 | Major | 采纳。当前唯一注册模板改为 `stickman-video@2`,删除 `@1` 注册;旧数据只清理 `@1`;旧代码必须拒绝 `@2` | BR-1、DEC-1、Demo 数据迁移、发布和回滚、AC-1、AC-7 | 关闭条件要求统一身份隔离并证明旧 Registry 无法操作新 Job;AC-1 明确用旧 Registry 验证拒绝,AC-7 验证版本定向迁移 | 数值版本由 1 改为 2,但 Registry 中仍只有一个当前版本,符合用户“只有一个版本”要求 |-| R-02 | Major | 采纳。增加 `resolve-provider-request` 及 query、confirm-resubmit、cancel-scope 三种决策;普通重试拒绝未知计费状态 | CreatorAction、Provider 请求安全、AC-4 | 关闭条件要求状态转换、Action、审计和三类恢复路径;对应合同与 AC-4 已逐项补齐 | 用户确认重提交仍可能产生重复计费,但必须明确勾选并有 Activity 审计 |-| R-03 | Major | 采纳。复用唯一协作面板并新增火柴人语义 Adapter,覆盖 Stage/Phase、Activity、去重和标准镜头进度 | 前端和 Agent、AC-10、测试策略 | 关闭条件要求 Adapter 责任和测试;AC-10 同时验证 Adapter、Activity、进度和无独立 Panel | 多阶段文案需要在实现时保持中英文同步,由 Adapter 测试约束 |-| R-04 | Major | 采纳。补充新鲜 Web 构建、完整构建清单、dist 与 App 内嵌目录的文件列表和逐文件哈希门禁 | NFR-3、AC-8、AC-9、测试策略 | 关闭条件要求完整一致性套件和可判定打包证据;AC-8/AC-9 已列出全部项目门禁和失败语义 | 实际打包成本较高,但属于发布前强制门禁,不能降级 |--全部 Major 均已按 Reviewer 的可验证关闭条件修订,流程结论记录为 `PASS`;Reviewer 原始结论保持 `REVISE`,本版本不启动第二次 Reviewer。diff --git "a/docs/specs/OpenCreator\347\273\237\344\270\200AI\346\234\215\345\212\241\344\276\233\345\272\224\345\225\206\344\270\216\351\205\215\347\275\256\344\275\223\351\252\214\346\226\271\346\241\210-2026-09-14.md" "b/docs/specs/OpenCreator\347\273\237\344\270\200AI\346\234\215\345\212\241\344\276\233\345\272\224\345\225\206\344\270\216\351\205\215\347\275\256\344\275\223\351\252\214\346\226\271\346\241\210-2026-09-14.md"deleted file mode 100644index 56c58a65..00000000--- "a/docs/specs/OpenCreator\347\273\237\344\270\200AI\346\234\215\345\212\241\344\276\233\345\272\224\345\225\206\344\270\216\351\205\215\347\275\256\344\275\223\351\252\214\346\226\271\346\241\210-2026-09-14.md"+++ /dev/null@@ -1,135 +0,0 @@-# OpenCreator 统一 AI 服务供应商与配置体验方案--> 状态:已批准(2026-09-14)-> 体量判断:复杂。范围跨协议、Daemon、Web 设置页、Creator Runtime、模板参数与 Desktop 一致性,但各服务共享同一配置边界,因此保持一份内聚方案。-> 设计确认:已完成(D-1 至 D-4)-> Reviewer 原始结论:未执行(当前会话未提供 `zhiyu-reviewer` Agent 调用能力)-> 流程结论:PASS(用户知情批准)-> 用户批准:已批准(2026-09-14,用户知情接受未独立审核风险)--## 背景、目标与非目标--目标是梳理当前 AI 能力和 API 支持范围,建立统一的供应商目录、默认 Base URL、默认模型和能力声明,并让用户通过“选择供应商 -> 选择模型 -> 填写认证信息”完成配置。Web 与 Desktop 使用同一套 Web 页面、Daemon API 和持久化结果。--非目标:本轮不代理或购买第三方 API;不把非兼容服务强行抽象成 OpenAI-compatible;不替换 CreatorCollaborationPanel;不把实时联网模型市场作为首版依赖;未具备稳定公开 API 的服务不标记为已支持。--## 用户需求原文--> 比如,LLM目前支持了openai协议,但是配置不友好,可以让用户选择比如:deepseek、openai、minimax,然后自动就把base_url配好了->-> 图片生成的支持,要加入极梦、可灵、nanobanana等等主流生图->-> 视频生成,tts也一样,主流的都梳理一下,增加支持->-> 配置的交互要优化,就想第1点提到的那样,要很方便的能配置,模型做到下拉可选。--## 事实基线与假设--| 证据 | 已确认事实 |-|---|---|-| `packages/protocol/src/creator-services.ts` | 统一配置已有 LLM、转写、TTS、图片、视频结构;LLM 仍是 OpenAI-compatible 配置。 |-| `packages/protocol/src/media-generation.ts` | 图片 provider 为 OpenAI、即梦、可灵、Gemini;视频 provider 为 Seedance、可灵、Veo,并已有部分模型目录。 |-| `apps/daemon/src/creator-services/config-store.ts` | 配置使用 Zod 校验,凭据分离存储并支持脱敏、旧配置归一化。 |-| `apps/daemon/src/image-generation/provider.ts`、`video-generation/service.ts` | 图片和视频已有专用请求/轮询逻辑,但能力和 provider 仍分散。 |-| `apps/web/src/features/settings/CreatorServicesSettingsView.tsx` | 设置页已按服务分区,部分 provider 有字段和模型建议,但存在硬编码和 LLM 体验不一致。 |-| `apps/web/e2e/web-desktop-parity.spec.ts`、`apps/desktop/e2e/desktop.spec.ts` | 项目已有 Web/Desktop parity 与实际打包 App E2E 门禁。 |--假设:首批 API 以公开、可授权、能够使用现有 Daemon 资产和任务模型验证的服务为准;其余服务进入规划目录,不作为已支持能力。--## 设计确认记录--| 设计部分 | 核心决定 | 用户确认原话 |-|---|---|---|-| D-1 目标与总体范围 | 采用统一 AI 服务供应商与配置体验方案;首批实现可验证 provider,其余进入规划清单。 | “没问题,继续” |-| D-2 供应商目录与适配分层 | 使用 Provider Catalog + 能力声明 + 专用 adapter;首批覆盖 LLM OpenAI/DeepSeek/MiniMax/Custom,图片 OpenAI/即梦/可灵/Gemini,视频 Seedance/可灵并核验 Veo,TTS OpenAI/MiniMax/阿里云/Edge TTS。 | “没问题,继续” |-| D-3 配置交互与兼容 | 供应商先选、模型下拉加自定义、自动填充地址和默认模型;保留旧配置、密钥和自定义地址;错误按配置、能力、上游和网络分类。 | “没问题,继续” |-| D-4 验收与交付 | 分配置体验、真实适配、Web/Desktop 一致性三阶段交付;不以未验证的供应商宣称已支持。 | “没问题,继续” |--## 需求与业务规则--| ID | 类型 | 优先级 | 描述 |-|---|---|---:|---|-| FR-1 | 功能 | P0 | LLM 支持 OpenAI、DeepSeek、MiniMax 和 Custom OpenAI-compatible 的明确选择。 |-| FR-2 | 功能 | P0 | 图片、视频、TTS provider 通过统一配置体验展示已支持能力,并清晰区分规划项。 |-| FR-3 | 功能 | P0 | Provider 选择自动填充 Base URL、推荐模型和认证字段。 |-| FR-4 | 功能 | P0 | 模型支持下拉选择和自定义模型,未知旧模型可正确回显。 |-| FR-5 | 功能 | P0 | 配置密钥继续安全存储、脱敏,并在 provider 切换和保存时保留已有密钥。 |-| FR-6 | 功能 | P1 | Provider 能力声明控制参考图、图生视频、声音列表等字段和入口。 |-| FR-7 | 功能 | P1 | TTS 声音按 provider/model 提供,支持内置声音、自定义 ID 和试听错误反馈。 |-| BR-1 | 规则 | P0 | 配置保存成功不等于上游连接成功;连接测试为用户主动操作。 |-| BR-2 | 规则 | P0 | 不可用或规划中的 provider 不得显示为点击后无效的可用入口。 |-| BR-3 | 规则 | P0 | 非 OpenAI-compatible provider 使用专用 adapter,不改变通用 Runtime 进度契约。 |-| BR-4 | 规则 | P0 | 旧配置读写归一化时保留用户地址、模型和凭据,不静默重置。 |-| NFR-1 | 约束 | P0 | Web/Desktop 共用页面、Catalog、Daemon API 和持久化结果,并在相同内容视口下验证一致。 |--## 方案比较与推荐--推荐 Provider Catalog + 能力声明 + 专用 adapter。Catalog 负责显示名、官方地址、默认模型、模型列表、认证方式、能力和文档链接;adapter 负责真实请求、异步任务、响应转换和错误映射。--仅在设置页中继续硬编码 provider 会导致 Web 与 Daemon 的支持范围漂移,排除。仅统一为 OpenAI-compatible 会无法表达可灵、视频任务和云厂商专用鉴权,排除。Catalog 不负责发请求,避免把产品元数据和上游协议耦合。--## 关键设计决策--| DEC ID | 决策 | 理由 | 约束范围 |-|---|---|---|---|-| DEC-1 | 共享包提供 Provider Catalog 和能力声明;Daemon adapter 负责上游协议。 | 统一 Web/Daemon 配置认知,同时保留专用协议差异。 | protocol、web、daemon |-| DEC-2 | Provider 切换自动填充默认值,但允许修改 Base URL、模型和自定义网关。 | 兼顾易用性、代理、中转和新模型。 | 配置 UI、schema、兼容 |-| DEC-3 | 模型选择为“推荐/可选列表 + 自定义模型”。 | 不阻塞未收录模型和旧配置。 | 所有生成与文本服务 |-| DEC-4 | 能力不足时隐藏或禁用对应入口,并提供明确原因。 | 防止伪一致和点击无效。 | 图片、视频、TTS、Desktop parity |-| DEC-5 | 统一外部进度使用 `phase`、`percent`、`message`、`completed`、`failed` 等字段。 | 通用 Panel 不依赖供应商私有事件。 | Creator Runtime、Panel |-| DEC-6 | 首批范围与规划范围分离;真实 API 未验证不得标记 supported。 | 控制交付风险和支持口径。 | Catalog、文档、验收 |--## 首批支持范围--- LLM:OpenAI、DeepSeek、MiniMax、Custom OpenAI-compatible。-- 图片:OpenAI、即梦、可灵、Gemini/Nano Banana;核对各自参考图和尺寸能力。-- 视频:Seedance、可灵;核验并补全 Veo 的创建、轮询和下载。-- TTS:OpenAI、MiniMax、阿里云、Edge TTS。-- 转写:保留 OpenAI、阿里云、Faster Whisper、WhisperKit、whisper.cpp,统一展示能力和配置。--规划目录可包含智谱、通义、Moonshot、OpenRouter、Runway、Luma、Pika、海螺、ElevenLabs、Azure Speech、火山引擎、腾讯云、Fish Speech、CosyVoice 等,但规划项不进入首批可用选择和完成统计。--## 详细设计--Catalog 条目至少包含 `id`、服务类型、显示名称、协议类型、默认 Base URL、模型条目、认证字段、能力标签、文档链接和 `supported/planned` 状态。模型条目包含 ID、显示名称、推荐标记和能力限制。--配置页采用“服务分区 -> provider 选择 -> model 选择 -> provider 字段”的顺序。API Key 只显示已配置状态;空值提交不得覆盖已存密钥。Provider 切换只影响当前表单默认值,不删除其他 provider 配置。--图片能力声明参考图数量、尺寸、输出格式和 URL/Base64 形式;视频能力声明文生/图生、时长、尺寸、进度可靠性和异步结果;TTS 能力声明声音目录来源、模型关联和试听能力。Daemon 负责将临时上游 URL 下载为本地资产,处理 URL 过期。--连接错误映射为配置缺失、认证失败、模型不存在、能力不支持、限流/配额、网络/代理/地区不可达和响应格式不兼容。异步视频若无可信进度,返回未知进度而不伪造百分比。--## 异常、兼容、迁移与回滚--保留现有配置文件和凭据文件,不新增数据库迁移。旧 provider ID 和旧 OpenAI-compatible 结构在读取时转换为当前结构;用户自定义地址、模型、密钥优先保留;未知模型回显为自定义模型。解析失败阻止保存并报告错误,不自动恢复默认。--每个 provider adapter 可独立关闭或从 Catalog 标记为 unavailable;已有配置仍可读取。若新 Catalog 或 adapter 发布后出现问题,可通过回退 provider 状态和保留旧配置结构恢复,不需要删除用户数据。--## 验收标准--| AC ID | 关联需求 | 前置条件 | 操作 | 可观察结果 | 验证层级 |-|---|---|---|---|---|---|-| AC-1 | FR-1, FR-3 | 打开模型设置 | 选择 OpenAI、DeepSeek、MiniMax | 地址、推荐模型和认证字段自动变化且可保存 | Web 组件 + Daemon |-| AC-2 | FR-2, FR-6 | 打开图片/视频/TTS 设置 | 切换不同 provider | 只显示真实支持字段,规划项不作为可用入口 | Web 组件 |-| AC-3 | FR-4 | provider 有模型目录 | 选择模型、自定义模型并重新打开 | 下拉选择和自定义值均能保存回显 | Web 组件 + Daemon |-| AC-4 | FR-5, BR-4 | 已存在旧配置和密钥 | 切换 provider、提交空 Key、重新读取 | 地址、模型和密钥均不丢失,密钥不明文回显 | Daemon 单元/集成 |-| AC-5 | FR-7 | TTS provider 可用 | 选择模型、声音并试听 | 声音列表按 provider/model 返回,错误信息可区分 | Daemon 集成 + Web |-| AC-6 | BR-3, DEC-5 | 使用 fake upstream | 执行图片、视频和 TTS 请求 | adapter 请求正确,Runtime 输出统一契约 | Daemon 集成 |-| AC-7 | NFR-1 | 同一 Fake Daemon、相同视口 | Browser/Desktop 执行配置读取和保存 | DOM、文案、关键尺寸、Runtime 请求和持久化结果一致 | parity E2E |-| AC-8 | NFR-1 | 当前 Web 构建和 Desktop 打包 | 启动实际 App 并检查资源 | App 加载本次 Web 产物,Preload、代理和配置流程可用,资源哈希一致 | Desktop E2E/打包校验 |--## 测试策略--协议层覆盖 Catalog 类型、provider/model 目录和能力声明;Daemon 覆盖 schema、旧配置归一化、凭据保留、每个 adapter 的请求/响应/错误和异步轮询;Web 覆盖切换、默认值、下拉、自定义模型、脱敏和字段可见性;parity E2E 覆盖 Browser/Desktop 相同配置流程;实际打包 App 覆盖嵌入资源、Preload、Runtime 代理和配置持久化。CI 使用 fake upstream,不依赖真实计费凭据;真实服务只做显式手动 smoke test。--## 风险与未决问题--未决问题是各规划供应商的公开 API、地区可用性和模型目录变化;不影响首批方案,但在进入 supported 前必须取得可验证的接口证据。Nano Banana 的产品名称与 Gemini API 模型 ID 需要在适配核验时明确映射,避免只按营销名称展示。--## 独立审核记录--Reviewer 原始结论:未执行。当前会话未提供 `zhiyu-reviewer` Agent 调用能力;用户已知悉该风险并明确批准进入 Plan。--| 问题 ID | 严重程度 | 处理决定 | 修改位置 | 关闭证据或不采纳理由 | 遗留风险 |-|---|---|---|---|---|---|-| REVIEWER-UNAVAILABLE | 流程异常 | 用户知情接受 | 独立审核记录、本文件头部 | 当前工具集中没有 `zhiyu-reviewer` 调用能力,无法伪造审核结论 | 方案未经过独立审核,Plan 和实现仍应重点复核 provider API、地区限制及 Web/Desktop 门禁 |diff --git "a/docs/specs/opencreator-app-server\345\270\270\351\251\273\345\214\226\346\226\271\346\241\210-2026-07-28.md" "b/docs/specs/opencreator-app-server\345\270\270\351\251\273\345\214\226\346\226\271\346\241\210-2026-07-28.md"deleted file mode 100644index a207a91c..00000000--- "a/docs/specs/opencreator-app-server\345\270\270\351\251\273\345\214\226\346\226\271\346\241\210-2026-07-28.md"+++ /dev/null@@ -1,233 +0,0 @@-# OpenCreator app-server 常驻化方案--> 状态:已批准-> 体量判断:标准方案。该改动跨越运行管理、Codex app-server 生命周期和日程工具权限,但保持单一交付目标,不拆分为独立方案。-> 设计确认:已完成(D-1 至 D-3)-> Reviewer 原始结论:BLOCKED-> 流程结论:PASS(用户知情批准)-> 用户批准:已批准(2026-07-28)--## 背景、目标与非目标--OpenCreator 当前为每次对话运行单独启动 `codex app-server --stdio`,重复执行进程启动、`initialize` 和固定 MCP 初始化。会话查询已有独立的常驻 app-server 客户端,但对话执行仍走一次性进程。--本方案的目标是让用户主动发起的对话复用一个由 OpenCreator Daemon 管理的常驻 app-server,消除热路径中的重复初始化,同时保持现有会话、审批、取消、日程工具和 Web/Desktop 行为。--非目标:--- 不实现多 app-server 进程池或多 turn 并发。-- 不将后台定时任务改造成常驻执行。-- 不实现崩溃后的 turn 自动恢复或自动重放。-- 不合并现有会话查询客户端与执行客户端。-- 不接入 `codex app-server daemon/proxy`、系统服务或全局 socket。-- 不建设新的监控页面或性能平台。-- 不进行与常驻执行无关的 Runtime 重构。--## 用户需求原文--1. “我一直有个感觉,用codex cli的速度和Chatgpt app相比,响应有些慢,有这种可能吗”-2. “我说错了,是用opencreator的速度”-3. “把app-server做成常驻的,这个方案我觉得可以。给出优化方案”-4. “$zhiyu-brainstorm 方案还是挺复杂的,根据你的建议方案,重新做需求和方案分析”-5. D-1 确认:“没问题,继续”-6. D-2 确认:“没问题,继续”-7. D-3 确认:“没问题,继续”--## 事实基线与假设--| 项目 | 已确认事实 |-|---|---|-| 对话执行 | `apps/daemon/src/codex/app-server-runner.ts` 每次运行都会启动、初始化并在 turn 完成后关闭 app-server。 |-| 会话查询 | `apps/daemon/src/codex/app-server-client.ts` 已实现按需启动、进程失效后重建的常驻请求客户端,但不处理 turn 通知、审批和运行结果。 |-| 运行参数 | `cwd`、`model`、`sandbox`、`reasoning` 和 `approvalPolicy` 可通过 `thread/start`、`thread/resume`、`turn/start` 按运行传入。 |-| 进程参数 | `profile` 和通过命令行注入的 MCP 配置在 app-server 启动时确定。 |-| 日程权限 | `opencreator_schedule` 当前使用绑定 `runId`、`threadId`、`createdBy` 和 scopes 的短期令牌;运行终止后撤销。 |-| 调度边界 | 自动定时任务不能获得日程修改权限,只能保留现有允许范围。 |-| 前端边界 | Web 与 Desktop 通过同一 Daemon/Runtime 链路执行对话,不应分别实现常驻逻辑。 |--假设:--- OpenCreator 发版绑定的 Codex 版本继续支持当前已使用的 app-server 协议。-- 第一版允许不同手动运行在 Daemon 内串行进入常驻执行器。-- 交互式进程凭证只在本机 Daemon 和其 app-server 子进程之间使用,并在进程退出时撤销。--## 设计确认记录--| 设计部分 | 核心决定 | 用户确认原话 |-|---|---|---|-| D-1 需求边界与简化原则 | 只常驻用户交互链路;后台定时任务维持一次性进程;不引入进程池、并发或自动恢复。 | “没问题,继续” |-| D-2 最小架构与运行流程 | 使用一个串行常驻执行器;profile 改变时重启;交互式 MCP 通过进程凭证映射当前活动 run。 | “没问题,继续” |-| D-3 异常处理、测试与验收 | 当前 run 明确失败、下一轮重建;不自动重放;通过 Fake app-server 和真实 Codex 验证复用与权限。 | “没问题,继续” |--## 需求与业务规则--| ID | 类型 | 优先级 | 描述 |-|---|---|---|---|-| FR-1 | 功能需求 | P0 | 用户主动发起的同 profile 对话必须复用同一个常驻执行 app-server,Daemon 退出前不因单个 turn 完成而关闭。 |-| FR-2 | 功能需求 | P0 | 切换项目、目录、模型、沙箱或推理等级时必须按运行传入正确参数;只有 profile 改变才受控重启常驻进程。 |-| FR-3 | 功能需求 | P0 | 会话新建与续接、事件输出、请求批准、完全访问权限和取消行为必须保持现有外部语义。 |-| FR-4 | 功能需求 | P0 | 用户对话必须保留现有日程工具能力;后台定时任务继续使用一次性 app-server 和现有受限令牌。 |-| FR-5 | 功能需求 | P0 | 常驻进程异常时只使当前 run 失败;下一次手动运行必须能够自动启动新进程。 |-| BR-1 | 业务规则 | P0 | 第一版常驻执行器同一时间只能有一个活动 turn,后续运行必须排队,因此事件和审批只能归属当前活动 run。 |-| BR-2 | 业务规则 | P0 | 已发送的 `turn/start` 不得自动重放;profile 切换和进程替换只能在当前 turn 终止后发生。 |-| NFR-1 | 非功能需求 | P0 | 常驻化不得扩大后台任务权限,不得产生 Web/Desktop 分叉,不得在 Daemon 退出后残留 Codex 子进程。 |-| NFR-2 | 非功能需求 | P1 | 日志必须能够证明进程启动、初始化、复用、重启和退出原因,并记录关键运行时间点。 |--## 方案比较与推荐--| 方案 | 优点 | 缺点 | 结论 |-|---|---|---|---|-| 一个交互式常驻进程,后台任务保留单次进程 | 直接优化用户等待;权限边界清晰;复用现有 runner 行为;改动可控 | 同一时刻只能串行执行;保留两种生命周期 | 推荐 |-| 所有运行共用常驻进程并支持并发 | 进程数量最少;理论吞吐更高 | 必须新增完整事件路由、并发控制和动态权限上下文,失败模式复杂 | 第一版排除 |-| 保持每轮一次性进程 | 无架构改动 | 无法消除重复启动和 MCP 初始化,不能达成目标 | 排除 |--## 关键设计决策--| DEC ID | 决策 | 理由 | 约束范围 |-|---|---|---|---|-| DEC-1 | 用户手动运行使用一个常驻执行器;后台定时任务继续使用现有一次性 runner。 | 将性能收益集中在用户感知链路,同时保持后台任务权限和失败边界。 | RunManager、Daemon 生命周期、调度执行 |-| DEC-2 | 第一版只允许一个活动 turn,以 `activeRun` 直接承接通知、审批、日志和结果。 | 避免引入 run/thread/turn 全局路由表和并发串线风险。 | 常驻执行器、运行队列、审批 |-| DEC-3 | 交互式 app-server 使用进程级凭证,Daemon 将该凭证映射到当前活动 run;无活动 run 时拒绝 MCP 请求。 | app-server 环境变量在启动时固定,无法继续使用每轮短期环境变量令牌;串行执行使活动上下文无歧义。 | capability token、内部 MCP 路由 |-| DEC-4 | `cwd/model/sandbox/reasoning/approvalPolicy` 按运行传入;profile 改变时在空闲状态重启常驻进程。 | 这些运行参数已有协议支持,只有 profile 属于当前进程启动参数。 | app-server 启动、thread/turn 请求 |-| DEC-5 | 进程异常不自动重放 turn;当前 run 终止,下一次请求重建进程。 | 防止重复生成、重复文件修改和重复日程操作。 | 取消、超时、崩溃恢复、回退 |--## 详细设计--### 常驻执行器--Daemon 持有一个 `PersistentAppServerRunner` 实例。该实例至少维护:--- 当前子进程和初始化状态。-- 当前 profile。-- 当前活动 run 的回调和运行上下文。-- 当前 thread ID、turn ID 和取消状态。-- 串行化入口,保证任何时刻最多一个活动 turn。--执行器按需启动,不要求 Daemon 启动时阻塞等待 Codex。第一次手动运行负责启动和 `initialize`;后续同 profile 运行直接复用。--现有会话查询 `app-server-client` 保持独立,第一版不承担 turn 通知或审批。--### 手动运行数据流--1. RunManager 将手动运行提交给常驻执行器。-2. 执行器等待前一轮结束。-3. 执行器检查进程状态和 profile。-4. 无进程时启动并初始化;profile 不同时关闭旧进程后启动新进程。-5. 执行器登记 `activeRun` 和对应的交互式能力上下文。-6. 根据续接模式发送 `thread/start` 或 `thread/resume`。-7. 发送 `turn/start`,并将通知、审批、stderr 和日志交给当前 run 的现有回调。-8. 收到 `turn/completed` 后解析结果并清除活动运行上下文,但保留进程。--切换 OpenCreator 项目只改变请求中的 `cwd`,不改变 app-server 进程。--### 后台任务数据流--由 schedule 创建的运行继续调用现有一次性 `startCodexAppServer`:--- 每轮签发绑定 run/thread 的受限令牌。-- 每轮注入独立 MCP 配置和环境变量。-- turn 结束后关闭进程并撤销令牌。--后台路径不接入交互式进程凭证,也不共享交互式 `activeRun`。--### 交互式能力凭证--常驻 app-server 启动时,Daemon 创建一个仅属于该进程实例的不可预测凭证,并在 MCP 配置中引用该凭证。--Daemon 维护:--```text-processCredential -> {- appServerInstanceId,- activeRunId,- activeThreadId,- createdBy: "api",- allowedScopes-}-```--每轮开始时写入活动 run/thread,结束时清空。内部 MCP 路由收到请求后:--1. 校验进程凭证有效且未撤销。-2. 确认当前存在活动交互式 run。-3. 校验请求 scope 属于交互式允许范围。-4. 使用当前活动 run/thread 构造现有审计 actor。-5. 执行操作。--凭证在 app-server 退出、profile 切换、Daemon 关闭或执行器被强制重置时撤销。无活动 run、旧凭证或后台运行尝试使用交互式凭证时必须拒绝。--### 取消和超时--- 已获得 thread ID 和 turn ID 时,取消发送 `turn/interrupt`。-- interrupt 成功后当前 run 按现有取消语义终止,app-server 可继续复用。-- app-server 无响应、interrupt 失败或协议状态不可判定时,终止进程并使当前 run 失败或取消。-- 进程终止后清除 `activeRun`、初始化状态和进程凭证。-- 下一次手动运行重新启动,不重放前一轮请求。--### 关闭和回退--Daemon 关闭时停止接收新运行,处理当前运行终止,然后关闭常驻 app-server 并撤销进程凭证。--现有一次性 runner 继续存在,可用于后台任务,并作为交互常驻化的紧急回退路径。回退不得改变会话、项目或前端接口。--## 异常、兼容、迁移与回滚--该改动不迁移数据库或持久化会话。常驻状态全部属于 Daemon 内存状态,Daemon 重启后重新创建即可。--| 异常 | 对当前 run 的处理 | 后续处理 |-|---|---|---|-| 启动或 initialize 失败 | 失败 | 清空状态;下一轮重新启动 |-| turn 中进程退出 | 失败 | 撤销凭证;下一轮重新启动 |-| interrupt 成功 | 取消 | 保留进程 |-| interrupt 超时或失败 | 取消或失败 | 强制关闭进程;下一轮重建 |-| profile 改变 | 等待当前 turn 结束 | 关闭旧进程并启动新进程 |-| MCP 无活动 run | 拒绝操作 | 不影响进程 |-| 进程凭证失效 | 当前工具调用失败 | 关闭对应进程;下一轮重建 |--由于 OpenCreator 发版绑定 Codex 版本,本方案不提供旧 Codex 协议兼容层。若发布后出现常驻执行问题,可以将手动运行临时切回现有一次性 runner;不得通过自动重放当前 turn 进行回滚。--## 验收标准--| AC ID | 关联需求 | 前置条件 | 操作 | 可观察结果 | 验证层级 |-|---|---|---|---|---|---|-| AC-1 | FR-1、FR-2、NFR-2 | 同一 Daemon、同一 profile | 在同一项目连续运行三轮,再切换项目运行一轮 | 四轮使用同一执行 PID;只出现一次 initialize;每轮 cwd 正确 | 单元、集成、真实 Codex |-| AC-2 | FR-2、BR-2 | 常驻进程空闲 | 切换到不同 profile 后运行 | 旧进程关闭,新进程只启动并初始化一次,没有进程重叠 | 单元、集成 |-| AC-3 | BR-1 | 同时提交两个手动运行 | 观察通知、审批和完成顺序 | 第二轮在第一轮终止后开始;事件和审批不串线 | 单元、集成 |-| AC-4 | FR-3、NFR-1 | Web 与 Desktop 使用同一 Fake Daemon 和真实 Daemon | 验证新会话、续接、两档权限、审批和取消 | 两端调用相同 Runtime API,外部行为与改造前一致 | 集成、Web/Desktop 门禁、App E2E |-| AC-5 | FR-4、NFR-1 | 分别存在手动 run 和后台任务 run | 手动读取/修改日程,并触发后台任务 | 手动功能可用;后台任务仍无法获得修改权限;两类进程和凭证相互隔离 | 单元、集成、真实 Codex |-| AC-6 | FR-5、BR-2 | turn 执行中模拟 app-server 崩溃 | 等待当前 run 终止,再提交下一轮 | 当前 run 明确失败且没有重复 turn;下一轮使用新 PID 成功运行 | 单元、集成 |-| AC-7 | NFR-1、NFR-2 | 常驻进程已运行 | 关闭 Daemon | app-server 退出、凭证撤销、无残留子进程;日志记录退出原因 | 集成、真实进程 |--## 测试策略--单元测试使用 Fake app-server 精确断言 spawn 次数、`initialize` 次数、请求顺序、PID 复用、profile 重启、串行队列、取消和崩溃行为。能力测试覆盖活动 run 映射、scope 校验、旧凭证撤销及无活动 run 拒绝。--集成测试通过 RunManager 验证手动运行选择常驻路径、后台任务选择一次性路径,并覆盖会话续接、审批、日志、日程工具和 Daemon 关闭。--真实边界验证使用发版绑定的 Codex,完成连续三轮、跨项目一轮、取消、审批、手动日程操作和后台任务。性能门禁以可重复的结构事实为准:--- 热路径不重新 spawn。-- 热路径不重新 initialize。-- profile 不变时不重新初始化固定 MCP。-- 记录改造前后 `submit -> turn/start`、`submit -> turn/started`、`submit -> first model event`,但不以受网络和模型波动影响的首字绝对时间作为唯一发布条件。--## 风险与未决问题--| 风险 | 处理 |-|---|---|-| 交互式进程凭证比运行级令牌存活更久 | 凭证只绑定单个子进程;每轮通过活动上下文恢复 run/thread 归属;进程退出立即撤销;无活动 run 时拒绝。 |-| 串行执行可能限制多会话并发 | 第一版保持简单和事件隔离;只有出现明确并发需求与数据后再设计路由。 |-| app-server 内部状态长期运行后可能异常 | 进程退出和协议错误会清空状态;下一轮自动重建;真实连续运行纳入验收。 |-| 保留常驻与一次性两条路径增加测试面 | 两条路径按 `createdBy` 明确分工,一次性路径不修改核心语义。 |--当前没有阻止方案实施的未决产品问题。--## 独立审核记录--> Reviewer 原始结论:BLOCKED->-> 审核异常:兼容 Reviewer 已到达 completed 终态,但其运行环境没有本地文件读取或 CodeGraph 工具。在遵守只读且不启动子进程的约束下,Reviewer 无法读取方案正文和直接代码证据,因此没有完成实质性独立审核。--| 问题 ID | 严重程度 | 处理决定 | 修改位置 | 关闭证据或不采纳理由 | 遗留风险 |-|---|---|---|---|---|---|-| REV-BLOCK-001 | Blocker | 用户知情接受;不伪造为已关闭 | 本节及文档头部 | Reviewer 的关闭条件是获得方案、`AGENTS.md` 和直接证据文件的只读访问;本次唯一 Reviewer 已完成且不可对同一版本重复启动。用户在风险披露后回复“没问题,继续”,批准进入 Plan | D/FR/BR/NFR/DEC/AC 未获得独立 Reviewer 的逐项代码事实核对;权限凭证和失败语义必须在 Plan、实现和验收中重点验证 |diff --git "a/docs/specs/opencreator-\347\213\254\347\253\213\351\241\271\347\233\256\344\270\216codex\344\274\232\350\257\235\346\230\240\345\260\204-\346\226\271\346\241\210-2026-07-21.md" "b/docs/specs/opencreator-\347\213\254\347\253\213\351\241\271\347\233\256\344\270\216codex\344\274\232\350\257\235\346\230\240\345\260\204-\346\226\271\346\241\210-2026-07-21.md"deleted file mode 100644index 662e566a..00000000--- "a/docs/specs/opencreator-\347\213\254\347\253\213\351\241\271\347\233\256\344\270\216codex\344\274\232\350\257\235\346\230\240\345\260\204-\346\226\271\346\241\210-2026-07-21.md"+++ /dev/null@@ -1,289 +0,0 @@-# OpenCreator 独立项目与 Codex 会话映射方案--> 状态:已批准-> 设计确认:已完成(D-1 至 D-3)-> Reviewer 原始结论:BLOCKED-> 流程结论:PASS(用户知情批准)-> 用户批准:已批准(2026-07-21)--## 背景、目标与非目标--### 背景--当前 OpenCreator 的项目保存在 Web `localStorage`,普通会话从 Codex-app-server 的 `thread/list` 导入后,再按 `cwd` 与项目路径是否相等进行前端分组。-这同时混淆了三个不同概念:--1. OpenCreator 主动创建并管理的项目。-2. OpenCreator 主动创建的 RuntimeThread。-3. Codex CLI、Desktop、IDE 或其他入口产生的任意历史会话。--现有“本机目录”回退虽然避免了临时目录被自动创建为项目,却会把所有未匹配会话-集中到 `~`,既丢失项目所有权,也可能让新会话在用户主目录运行。--### 目标--1. OpenCreator 项目与 Codex 项目彻底分离,双方不建立同步关系。-2. OpenCreator 只展示和管理自己创建或用户明确认领的普通会话。-3. OpenCreator 持久化项目与 RuntimeThread 的所有权关系,以及 RuntimeThread 与- `codexThreadId` 的绑定。-4. Codex app-server 继续负责会话执行、恢复、正文历史和搜索来源。-5. 删除 `cwd` 运行期推断和“本机目录”默认项目,消除项目丢失与历史会话污染。-6. 升级时保留既有 OpenCreator 项目和自建会话,并提供待归属会话恢复入口。--### 非目标--1. 不读取、修改或同步 Codex Desktop 的项目状态文件。-2. 本期不提供任意 Codex 历史会话的主动导入功能。-3. 不把一个会话同时分配给多个项目。-4. 不重构 `schedule_draft`、`schedule_task` 的现有生命周期。-5. 不删除本机代码目录或底层 Codex 会话文件。--## 用户需求原文--1. “那就直接来个彻底的,opencreator的项目和codex的项目彻底分离,二者不需要有关系,- opencreator维护自己创建的项目的会话,问题是会话是从codex cli读取的,由opencreator维护- 一套映射逻辑,有没有问题? $zhiyu-brainstorm 分析这个需求”-2. D-1 确认:“没问题,继续”-3. D-2 确认:“没问题,继续”-4. D-3 确认:“没问题,继续”--## 事实基线与假设--| 证据 | 已确认事实 |-|---|---|-| `apps/web/src/features/projects/project-model.ts` | 项目由 Web 模型定义并持久化到 `opencreator.projects.v1` |-| `apps/web/src/app/AppController.tsx` | `projectIdForThread` 通过 `cwd` 匹配项目,未匹配时归入 `local-home` |-| `apps/daemon/src/codex/sessions/app-server-provider.ts` | Codex 会话通过 `thread/list`、`thread/turns/list` 和 `thread/search` 读取 |-| `apps/daemon/src/threads/manager.ts` | Daemon 已持久化 RuntimeThread 与 `codexThreadId` 的绑定 |-| `apps/daemon/src/api/routes.threads.ts` | 普通会话列表会合并并导入最近 Codex 会话 |-| `apps/daemon/src/storage/migrations.ts` | SQLite 已有 `threads`,目前没有 `projects`、`project_id` 或会话来源字段 |-| `apps/daemon/src/codex/app-server-runner.ts` | `thread/start` 和 `thread/resume` 都接收 OpenCreator 提供的 `cwd` |--假设:--1. 一个普通 RuntimeThread 在任意时刻最多属于一个 OpenCreator 项目。-2. 项目目录是普通会话的执行与文件访问边界,但不是会话所有权标识。-3. 旧 `thread_codex_*` ID 只由现有 Codex 自动导入逻辑生成,可用于一次性来源迁移。-4. Desktop 与 Web 使用同一个 Daemon 数据目录,SQLite 适合作为项目事实源。--## 设计确认记录--| 设计部分 | 核心决定 | 用户确认原话 |-|---|---|---|-| D-1 目标与产品边界 | 项目完全独立;移除“本机目录”;只展示 OpenCreator 拥有的会话;未知 Codex 会话不自动导入 | “没问题,继续” |-| D-2 数据模型与映射 | 项目进入 Daemon SQLite;Thread 直接保存 `projectId` 和来源;首次运行后绑定唯一 `codexThreadId` | “没问题,继续” |-| D-3 迁移与验收 | 幂等迁移旧项目;本机目录自建会话进入待归属区;Codex 不可用时保留本地索引 | “没问题,继续” |--## 需求与业务规则--| ID | 类型 | 优先级 | 描述 |-|---|---|---|---|-| FR-1 | 功能 | P0 | 用户可以在 OpenCreator 中创建、查看、修改、归档和恢复独立项目 |-| FR-2 | 功能 | P0 | 新建普通会话必须指定活跃 `projectId`,Daemon 持久化项目归属 |-| FR-3 | 功能 | P0 | RuntimeThread 首次运行后绑定唯一 `codexThreadId`,后续从 Codex 读取和恢复历史 |-| FR-4 | 功能 | P0 | 侧边栏、搜索和导航只展示 OpenCreator 项目会话及现有调度会话 |-| FR-5 | 功能 | P0 | 升级后可查看并认领无法自动归属的 OpenCreator 自建会话 |-| FR-6 | 功能 | P1 | 用户可以显式更换项目目录,并让该项目既有普通会话使用新目录 |-| BR-1 | 规则 | P0 | OpenCreator 不读取、不修改、不同步 Codex 项目配置 |-| BR-2 | 规则 | P0 | 运行期禁止根据 `cwd`、标题或时间推断项目归属 |-| BR-3 | 规则 | P0 | 未知 Codex 会话不得因列表、搜索、深链接或刷新而自动导入 |-| BR-4 | 规则 | P0 | 归档项目不删除目录、Codex 会话或 Thread 映射 |-| BR-5 | 规则 | P1 | 调度会话继续由 `purpose` 和调度系统管理 |-| BR-6 | 规则 | P0 | 不再创建“本机目录”,没有项目时禁止新建普通会话 |-| NFR-1 | 约束 | P0 | Codex 不可用时,项目和会话索引仍可从 SQLite 加载 |-| NFR-2 | 约束 | P0 | 项目迁移和 `codexThreadId` 绑定必须幂等、唯一且可恢复 |-| NFR-3 | 约束 | P0 | 升级不得静默删除旧项目、自建会话或原始 localStorage 备份 |--## 方案比较与推荐--### 方案 A:`threads.project_id` 直接外键,推荐--项目保存在 Daemon SQLite,普通 Thread 直接保存 `project_id`。一对多关系明确,-创建、查询、归档和搜索都可以通过单次连接或索引完成。--优点:数据模型简单、数据库可维护完整性、查询和迁移成本低。--### 方案 B:独立 `project_threads` 映射表--可表达多对多关系,但当前没有一个会话属于多个项目的需求。它会增加事务、唯一约束、-归档和查询复杂度,没有带来实际能力。--### 方案 C:继续按 `cwd` 推断--无法区分显式项目和任意历史目录,遇到临时路径、符号链接、目录移动和同路径外部会话时-都会产生错误归属,因此排除。--## 关键设计决策--| DEC ID | 决策 | 理由 | 约束范围 |-|---|---|---|---|-| DEC-1 | Daemon SQLite 是项目事实源 | 项目需要与 Thread、运行和迁移保持事务一致 | 项目 API、Web 状态 |-| DEC-2 | Thread 直接保存 `project_id` 和 `origin` | 明确所有权并区分自建与历史自动发现会话 | 普通 Thread、迁移 |-| DEC-3 | 采用先创建 RuntimeThread、首次运行后绑定 Codex 的两阶段流程 | Codex ID 只能在 `thread/start` 后获得 | 创建、运行、故障恢复 |-| DEC-4 | OpenCreator 保存索引和所有权,Codex 保存会话正文 | 离线可见且不复制完整会话真相 | 列表、历史、恢复 |-| DEC-5 | 路径匹配只允许出现在一次性迁移中 | 保留旧数据但杜绝运行期启发式 | 升级迁移 |-| DEC-6 | 显式更换项目目录时更新该项目普通 Thread 的执行目录 | Codex resume 支持由 OpenCreator提供新 `cwd` | 项目目录修复 |-| DEC-7 | Codex 搜索结果必须在 Daemon 与映射求交集 | 防止 Web 绕过所有权边界 | 搜索、深链接 |--## 详细设计--### 项目数据--新增 `projects` 表:--```text-id, name, cwd, canonical_cwd, profile, model, reasoning, sandbox,-status, created_at, updated_at, archived_at-```--新项目使用 OpenCreator 生成的稳定 ID。新建时展开 `~`、校验目录并执行 `realpath`。-同一个 `canonical_cwd` 只能有一个活跃项目。迁移产生的缺失目录项目允许-`canonical_cwd` 为空,并在修复目录前禁止运行。--新增项目 API:--```text-GET /projects-POST /projects-PATCH /projects/:id-POST /projects/:id/archive-POST /projects/:id/restore-POST /projects/:id/replace-directory-```--Desktop 目录选择器只返回路径,项目创建和校验全部由 Daemon 完成。--### Thread 所有权--`threads` 新增:--```text-project_id TEXT NULL-origin TEXT NOT NULL -- opencreator_created | codex_discovered-```--普通项目会话必须满足:--```text-purpose = conversation-origin = opencreator_created-project_id IS NOT NULL-```--`codex_thread_id` 增加非空唯一索引。`ThreadResponse` 返回 `projectId` 和 `origin`。-普通 `POST /threads` 必须传 `projectId`,Daemon 从项目读取 `cwd`,不接受 Web-覆盖项目目录。Composer 明确配置可覆盖项目默认值,Thread 创建后保存配置快照。--### 创建与绑定--1. Daemon 校验项目活跃且目录可用。-2. 创建带 `projectId`、`origin=opencreator_created` 的 RuntimeThread。-3. 首次发送消息调用 Codex `thread/start`。-4. Codex 返回 ID 后,在唯一约束保护下写入 `codex_thread_id`。-5. 后续历史使用 `thread/turns/list`,运行使用 `thread/resume`。--若绑定写入失败,Run 保留返回的 Codex ID,Thread 保持未绑定并记录错误。启动恢复只在-Thread 未绑定、Run 唯一指向该 Thread、Codex ID 未被占用时自动修复,否则停止并报告。--### 列表、搜索与导航--普通 `/threads` 列表只查询本地 `origin=opencreator_created` 且已有项目归属的记录,不再-调用 `listRecentCodexThreads` 导入任意会话。项目侧边栏直接使用服务端 `projectId`-分组,删除 `projectIdForThread(cwd)`。--搜索仍以 Codex app-server 为正文来源,但 Daemon 必须用已映射 `codexThreadId`-过滤结果;过滤后不足请求数量时继续读取 Codex 搜索分页。未知结果不返回 Web。-打开搜索结果或深链接只能访问已存在的 OpenCreator RuntimeThread。--### 项目目录更换--普通改名或默认配置修改不改变既有 Thread。显式更换目录时校验新路径,并在不存在-运行中任务的前提下,事务性更新项目及其全部普通 Thread 的 `cwd/canonical_cwd`。-`projectId` 和 `codexThreadId` 不变。--## 兼容、迁移与回滚--新增幂等迁移接口 `POST /projects/migrations/local-storage-v1`。Web 传入旧-`opencreator.projects.v1`,Daemon 在事务中创建项目、合并规范路径重复项,并仅将-`opencreator_created` 历史普通会话按完整规范路径归属。旧 `local-home` 不创建项目;-其自建会话进入待归属区。`codex_discovered` 始终隐藏。--迁移状态保存在 Daemon,重复调用返回既有映射。旧 localStorage 至少保留一个版本,-新版迁移成功后停止把它作为事实源。回滚旧版本时仍可读取原数据。--项目归档或目录更换遇到活跃运行返回 `409`。项目目录缺失时项目保留并标记不可用。-Codex 不可用或已映射 Codex 会话不存在时,不清空本地项目、Thread 或绑定。--## 验收标准--| AC ID | 关联需求 | 前置条件 | 操作 | 可观察结果 | 验证层级 |-|---|---|---|---|---|---|-| AC-1 | FR-1, BR-6 | 全新数据目录 | 启动、添加项目、重启 | 无“本机目录”,项目持久存在 | Desktop E2E |-| AC-2 | FR-4, BR-2, BR-3 | Codex 存在相同及不同 cwd 历史会话 | 刷新列表和搜索 | 未映射会话均不出现 | Daemon 集成 |-| AC-3 | FR-2, FR-3, NFR-2 | 已有活跃项目 | 新建会话并完成首次运行 | 创建时有 projectId,运行后绑定唯一 Codex ID | API 集成 |-| AC-4 | FR-3, NFR-1 | 已完成一次会话 | 重启并打开会话 | 按 projectId 展示并从 Codex 读取原历史 | Desktop E2E |-| AC-5 | FR-6, BR-2 | 项目无活跃运行 | 改名并显式更换目录 | 归属不变,既有会话使用新目录 | Daemon 集成 |-| AC-6 | FR-5, NFR-3 | 存在旧项目、自建会话和外部 Codex 会话 | 执行升级迁移 | 项目保留,本机会话待归属,外部会话隐藏 | 迁移测试 |-| AC-7 | NFR-1, BR-4 | 已有项目和绑定会话 | 停止 Codex 后启动 OpenCreator | 索引仍显示,历史不可用但映射不丢失 | Desktop E2E |-| AC-8 | FR-4, BR-3 | 存在未知 Codex 搜索结果和深链接 | 搜索或直接导航 | 不创建 RuntimeThread、不导入未知会话 | Web/API 集成 |--## 测试策略--Daemon 单元测试覆盖项目仓储、路径规范化、重复路径、归档恢复、Thread 所有权、-Codex ID 唯一绑定、绑定恢复和迁移幂等性。--Daemon 集成测试覆盖项目 API、普通 Thread 必须携带项目、列表不再自动导入、-搜索映射过滤、目录更换、活跃运行冲突和 Codex 不可用降级。--Web 测试覆盖空项目状态、服务端项目 CRUD、按 `projectId` 分组、待归属认领、-搜索导航隔离以及删除“本机目录”和 `cwd` 推断。--Desktop E2E 使用临时数据目录完成创建、首次运行、重启恢复、注入外部 Codex 会话、-Codex 下线和恢复的完整链路。--## 风险与未决问题--1. 旧项目 localStorage 只能由 Web 主动提交,迁移必须等待 Daemon 连接成功后执行。-2. 一次性通过 `thread_codex_*` 分类旧自动导入会话依赖现有稳定 ID 生成规则,需要测试锁定。-3. 搜索结果过滤可能需要读取多个 Codex 分页,必须保留游标和加载状态,避免结果提前截断。-4. 当前没有阻塞设计或实现的未决问题。--## 独立审核记录--> Reviewer 原始结论:BLOCKED-> 审核角色:`zhiyu-reviewer` 未注册,按兼容规则使用一次默认独立 Reviewer--### Reviewer 原始输出--```text-## 审核结论-BLOCKED--## 审核问题-### R-1 审核对象无法读取-- 严重程度:Blocker-- 证据:方案路径未提供正文;Reviewer 会话未暴露可用的 CodeGraph 或文件读取资源。- 审核约束同时禁止通过命令或子进程读取文件。-- 影响:无法核验方案契约,也无法对迁移幂等性、数据保留、未知会话隔离、- Codex ID 绑定、失败恢复及直接调用方兼容性作出有证据的结论。- 此处是审核阻塞,不代表方案本身已有 Blocker。-- 建议:向 Reviewer 暴露只读 CodeGraph/文件读取工具,或提供方案正文以及直接影响- 代码和测试片段。-- 关闭条件:能够只读访问方案全文,并定向读取直接影响证据及其一层调用关系后,- 重新完成一次独立审核。--## 契约追踪检查-审核包声明了必须保持一致的契约组合,但缺少各契约正文,无法验证需求、决策和 AC-是否形成闭环,也无法确认是否遗漏直接调用方。--## 审核范围说明-Reviewer 遵守了只读和排除项。审核被阻塞所缺失的外部事实是方案全文、直接影响-代码/测试内容及其一层调用关系。-```--### 问题处理记录--| 问题 ID | 严重程度 | 处理决定 | 修改位置 | 关闭证据或不采纳理由 | 遗留风险 |-|---|---|---|---|---|---|-| R-1 | Blocker | 用户知情接受审核缺失风险,不修改方案契约 | 本节及文档头部 | Reviewer 已明确说明这不代表方案本身存在 Blocker;用户在看到审核状态和遗留风险后批准继续,原话:“没问题,方案我审过了,可以继续了” | 本方案未获得有效独立 Reviewer 审核,实施计划和开发验证需重点检查契约、迁移与兼容问题 |