[v0.2] dev/v0.2 分支 Bug 清单 — 2026-04-29 审计

[Sun-sunshine06]

分支: dev/v0.2 (commit 7bec35b)
审计日期: 2026-04-29
审计环境: Windows 11, Node v24.11.0, pnpm 9.15.0

---

CI 检查总览

检查项	状态	详情
类型检查 (pnpm typecheck)	✅ 通过	10/10 包成功
Lint (pnpm lint)	✅ 通过	Biome 2.4.13, 459 文件, 0 问题
单元测试 (pnpm test)	⚠️ 部分失败	7/10 包通过，3 包因环境问题失败

测试失败详情（非代码缺陷，环境相关）

• @open-codesign/exporters — pdf.test.ts 3/50 测试超时，Puppeteer/Chrome 发现在 Windows 上较慢（5s limit）
• @open-codesign/ui — Vitest forks worker 启动失败（[vitest-pool]: Failed to start forks worker）

通过的包

artifacts (19/19) · templates (8/8) · shared · runtime · providers · desktop · core

---

Bug 清单

Bug #1 [高] 生成任务长时间运行后 terminated 错误

• 严重度: 高（功能缺陷，影响长时间生成任务）
• 现象: 生成任务运行约 12 分钟后，UI 弹出错误 Error invoking remote method 'codesign:v1:generate': CodesignError: terminated
• 复现: 使用 mimo-v2.5-pro 模型生成复杂设计（如落地页），任务超过 12 分钟后触发
• 日志:

  [error] (main:ipc) generate.fail {
    runId: 'moiv5277-9bhpl6',
    ms: 731061,                                    // ≈12.2 分钟
    provider: 'claude-code-imported',
    modelId: 'mimo-v2.5-pro',
    baseUrl: 'https://token-plan-ams.xiaomimimo.com/anthropic',
    message: 'terminated',
    code: 'PROVIDER_ERROR'
  }
  

• 执行数据: 总运行时间 ~12.2 分钟, ~50 agent 轮次, 上下文 20MB → 11MB (修剪后)
• 根因: 代理服务器处理长时间请求后中断连接。terminated 是 Anthropic API 错误响应，表示服务端主动终止
• 影响范围: 所有使用自定义代理服务器且超时较短的场景
• 相关代码: packages/core/src/agent.ts (generateViaAgent)
• 附加: 同一任务中还出现了 aborted 错误（ms: 375699, code: 'PROVIDER_ABORTED'），可能是用户取消或客户端超时
• 建议修复:
  1. 在 agent.ts 中增加代理服务器超时检测和重试逻辑
  2. 增加可配置的生成超时，超时前主动优雅终止
  3. 对 terminated 错误增加重试（resume from last turn）而非直接报错
  4. 增加上下文大小检查，超过阈值时提前警告用户

---

Bug #2 [中] 测试链接（Test Connection）对自定义代理服务器失败

• 严重度: 中（功能缺陷）
• 位置: 设置页面 → Provider 卡片 → 更多操作 → 测试链接
• 现象: 点击"测试链接"弹出错误 toast "连接失败，请检查配置"，但实际生成功能正常
• 原因: 测试探针使用 GET /v1/models，自定义代理服务器未实现该端点
  • 实际使用（POST /v1/messages）正常
  • 测试链接（GET /v1/models）返回 404
• 影响范围: 所有未实现 /v1/models 端点的代理服务器/网关
• 相关代码: apps/desktop/src/main/connection-ipc.ts:219-221 (buildEndpointForWire)
• 建议修复: 增加降级探针：GET /v1/models 404 时，尝试 HEAD /v1/messages 或直接标记"探针不支持"而非报错

---

Bug #3 [中] 设置页存储路径修改后工作区未同步

• 严重度: 中（用户困惑，设置不生效）
• 位置: 设置 → 存储（StorageTab）
• 现象: 用户在设置中修改"数据"存储路径后，期望设计的工作区文件指向新路径，但实际未变化
• 根因: 存储路径（config/logs/data）和设计工作区绑定是两个独立概念：
  • 存储路径：控制全局配置、日志、数据目录（storage-settings.ts），SQLite 数据库始终在 app.getPath('userData')/designs.db
  • 工作区绑定：每个设计独立绑定一个工作区目录（design.workspacePath），通过文件面板的"设置工作区"按钮操作
  • 修改存储路径不会自动更新任何设计的 workspacePath
• 相关代码:
  • apps/desktop/src/main/onboarding/storage.ts — runChooseStorageFolder
  • apps/desktop/src/main/design-workspace.ts — bindWorkspace
  • apps/desktop/src/renderer/src/components/FilesPanel.tsx:74-79
• 建议修复:
  1. 在 StorageTab 中增加提示说明存储路径与工作区绑定的区别
  2. 新建设计时若全局存在默认工作区目录，自动绑定

---

Bug #4 [中] 工作区切换后预览可能出错

• 严重度: 中（功能缺陷）
• 位置: apps/desktop/src/renderer/src/preview/workspace-source.ts → resolveWorkspacePreviewSource
• 现象: 切换工作区后预览区域显示错误 toast "Design is not bound to a workspace"
• 触发条件:
  1. 设计初始无工作区（workspacePath === null）
  2. Agent 生成了 HTML 并设置 previewHtml，其中包含 workspace source reference
  3. 快照持久化时 chat.ts:208 调用 resolveWorkspacePreviewSource → files.read → 异常
  4. 用户随后绑定工作区，但若选择"仅切换"（不复制文件），新工作区目录为空，files.read 找不到引用文件
• 相关代码:
  • apps/desktop/src/renderer/src/preview/workspace-source.ts:50-70
  • apps/desktop/src/renderer/src/store/slices/chat.ts:208-222
• 建议修复:
  1. files:read 增加与 files:list 一致的降级逻辑（workspacePath 为 null 时返回空而非抛异常）
  2. 工作区切换"仅切换"时，若目标目录为空，给出明确警告

---

Bug #5 [低] workspace 未绑定时文件读取错误

• 严重度: 低（list 端点已降级，但 read 端点抛异常污染日志）
• 日志: Error occurred in handler for 'codesign:files:v1:read': CodesignError: Design is not bound to a workspace
• 位置: apps/desktop/src/main/snapshots-ipc.ts:723-724 (codesign:files:v1:read handler)
• 原因: 设计创建后 workspacePath === null，预览或快照持久化时调用 files.read 触发异常
• 对比: 同模块的 codesign:files:v1:list（line 696）已正确降级——workspacePath === null 时返回 [] 而非抛异常
• 触发路径:
  1. chat.ts:208 → resolveWorkspacePreviewSource → files.read → 异常
  2. generation.ts:755 → resolveWorkspacePreviewSource → files.read → 异常（导出时）
• 建议修复: codesign:files:v1:read handler 中 workspacePath 为 null 时返回空内容或特定错误码（对齐 files:list 的降级行为）

---

Bug #6 [低] i18n 翻译键缺失 — settings.providers.noModel

• 严重度: 低（视觉/UX）
• 位置: 设置页面 → Provider 配置区域
• 日志: [warn] [i18n] missing translation key "settings.providers.noModel" in namespace "translation" for locale "en"
• 复现: 打开设置页面，查看已配置的 provider 卡片
• 建议修复: 在 en.json / zh-CN.json 中补充 settings.providers.noModel 翻译键

---

Bug #7 [低] pdf.test.ts 在 Windows 上超时

• 严重度: 低（测试环境问题，非代码缺陷）
• 文件: packages/exporters/src/pdf.test.ts
• 失败数: 3/50 测试
• 原因: Puppeteer/Chrome 发现超时（5s limit），Windows 上浏览器发现较慢
• 建议修复: 增加 Windows CI 的超时配置或跳过条件

---

Bug #8 [低] VitePress v1 与 rolldown-vite 不兼容

• 严重度: 低（不影响桌面端功能）
• 日志: VitePress v1 is not compatible with rolldown-vite. Use VitePress v2 instead.
• 原因: workspace 中 Vite 升级到 v8（rolldown-vite），但 website 包仍用 VitePress v1
• 建议修复: 升级到 VitePress v2 或锁定 Vite 版本

---

Bug #9 [极低] 动态导入优化警告

• 严重度: 极低（构建警告，不影响功能）
• 日志: [INEFFECTIVE_DYNAMIC_IMPORT] Warning ×4
• 涉及文件:
  • packages/providers/src/index.ts (by agent.ts)
  • packages/exporters/src/markdown.ts (by exporters/src/index.ts)
  • packages/core/src/skills/loader.ts (by agent.ts)
  • node_modules/.pnpm/smol-toml@1.6.1 (by codex-config.ts)
• 建议修复: 清理动态导入逻辑或在构建配置中忽略

---

环境注意事项

• 切换到 dev/v0.2 后需要执行 pnpm install 同步依赖（zod 3→4, Biome 1.9→2.4, TS 5.9→6.0）
• 依赖版本已在 pnpm-lock.yaml 中正确锁定，本机首次使用需同步

---

修复优先级排序

优先级	Bug	预估工作量
高	#1 生成 terminated 错误	中-大
中	#2 测试链接对代理服务器失败	中
中	#3 工作区设置不生效	中
中	#4 工作区切换后预览出错	中
低	#5 文件读取降级缺失	小
低	#6 i18n 翻译键缺失	小
低	#7 pdf.test.ts 超时	小
低	#8 VitePress 兼容性	中
极低	#9 动态导入警告	小

[github-actions]

感谢详细审计。我按 issue 里写的 dev/v0.2 commit 7bec35b 对代码做了核对，先给一个初步结论：#1 / #4 / #5 的代码路径能对上；#2 只在 Anthropic wire 上仍可能成立，OpenAI-compatible wire 这条在 #179 后已经有降级探测；#3 更像当前实现语义和提示不够清晰；#6 我没能在该提交的已提交源码里复核出来。

Relevant code:

• packages/core/src/agent.ts:781-840 — agent 路径只对首轮做 withBackoff()，一旦已经产生 assistant/tool side effects 就禁止重试。
• packages/providers/src/retry.ts:97-108 — 当前重试分类只覆盖 429、明确 5xx、TypeError/网络错误码；单独一个 terminated 文本本身不会被当成可重试瞬态错误。
• apps/desktop/src/main/connection-ipc.ts:527-543、apps/desktop/src/main/connection-ipc.ts:546-620 — /models 返回 404 时，openai-chat/openai-responses 会降级 probe 到真实推理端点；anthropic 不会降级。
• apps/desktop/src/main/connection-ipc.test.ts:969-1049、apps/desktop/src/main/connection-ipc.test.ts:1007-1020 — 测试里已经覆盖了 GLM 类 /models 404 -> degrade probe，同时也明确断言 anthropic wire 的 /v1/models 404 不降级。这一点和已关闭的 #179 是相关的。
• apps/desktop/src/main/onboarding/storage.ts:36-55、apps/desktop/src/main/index.ts:48-53、apps/desktop/src/main/design-workspace.ts:113-165、apps/desktop/src/renderer/src/components/FilesPanel.tsx:67-77 — 存储路径（config/logs/data）和 design 的 workspacePath 确实是两套独立状态；修改 storage 不会自动 rebind 设计工作区。
• apps/desktop/src/main/snapshots-ipc.ts:695-725、apps/desktop/src/renderer/src/preview/workspace-source.ts:57-69、apps/desktop/src/renderer/src/store/slices/chat.ts:205-214、apps/desktop/src/renderer/src/store/slices/generation.ts:752-761 — codesign:files:v1:list 在 workspacePath === null 时返回 []，但 codesign:files:v1:read 会直接抛 Design is not bound to a workspace；而快照持久化/导出路径在 HTML 引用了 workspace source 时确实会走 read()。
• packages/i18n/src/locales/en.json:154、packages/i18n/src/locales/zh-CN.json:154 — settings.providers.noModel 这个 key 在该提交里是存在的，所以 #6 我目前不能从已提交源码直接确认。

Need more info:

• #2 里的代理在 Settings 里具体用了哪种 wire：anthropic、openai-chat 还是 openai-responses？如果是 anthropic，那它更像是 #179 的后续场景，而不是同一个 OpenAI-compatible 404 问题。
• #1 如果方便的话，请补一段脱敏后的 terminated 前后日志，尤其是是否带了 HTTP status / stack。当前代码只能确认它会被透传成 provider error，不能从仓库里直接证明“上游主动断开”的具体来源。
• #6 如果还能复现，请贴一下完整 warning 行和当前 locale；因为提交里的 en/zh-CN 词条都已经在。

---

open-codesign Bot

[Sun-sunshine06]

补充信息如下：

#2 wire 类型确认

代理服务器使用的是 anthropic wire。当时的 provider 配置：

• id: claude-code-imported
• wire: anthropic
• baseUrl: https://token-plan-ams.xiaomimimo.com/anthropic
• modelId: mimo-v2.5-pro

这与 bot 分析一致——anthropic wire 的 /v1/models 404 不会降级探测，而 openai-chat/openai-responses 已在 #179 后支持降级。所以 #2 确实是 #179 的后续场景：#179 解决了 OpenAI-compatible 的降级，但 Anthropic wire 仍需单独处理。

#1 terminated 日志补充

terminated 错误来自更早的生成会话，当前日志 (desktop-live.stderr.log) 只保留了最近一次会话。当前会话中记录的是同类型问题的 aborted 变体：

[warn]  (main:ipc) generate.timeout.fired { id: 'mo8gzsfq-c8b2nh', timeoutSec: 1200 }
[error] (main:ipc) [generate] step=send_request.fail {
  generationId: 'mo8gzsfq-c8b2nh',
  provider: 'custom-k2-6-xsy2',
  modelId: 'moonshotai/kimi-k2.6',
  ms: 1200045,                     // ~20 分钟
  stopReason: 'aborted'
}
[error] (main:ipc) generate.fail {
  generationId: 'mo8gzsfq-c8b2nh',
  ms: 1200051,
  provider: 'custom-k2-6-xsy2',
  modelId: 'moonshotai/kimi-k2.6',
  baseUrl: 'https://openrouter.ai/api/v1',
  message: 'Request was aborted',
  code: 'PROVIDER_ERROR'
}
Error occurred in handler for 'codesign:v1:generate': CodesignError: Request was aborted
    at generateViaAgent (.../apps/desktop/out/main/index.js:32516:7)
  code: 'PROVIDER_ERROR'

补充发现：日志中还有一个 MaxListenersExceededWarning 可能与长时间运行相关：

(node:34996) MaxListenersExceededWarning: Possible EventTarget memory leak detected. 
11 abort listeners added to [AbortSignal]. MaxListeners is 10.

当前会话的 provider 使用 openai-responses wire (OpenRouter)，terminated 错误来自之前使用 anthropic wire 的会话。两者的共同特征是长时间运行（>12 分钟 / ~20 分钟）后断开。

结合 bot 的代码分析：

• packages/providers/src/retry.ts:97-108 — 重试分类只覆盖 429、明确 5xx、TypeError/网络错误码；terminated/aborted 不会被当成可重试瞬态错误
• packages/core/src/agent.ts:781-840 — 只对首轮做 withBackoff()，已有 assistant/tool side effects 后禁止重试

这意味着长任务中途断连后直接报错，没有恢复能力。

#6 i18n 确认

可以确认是 真实 bug，且当前日志仍在持续报错。代码中引用了 settings.providers.noModel：

• apps/desktop/src/renderer/src/components/ModelSwitcher.tsx:268 → t('settings.providers.noModel')
• apps/desktop/src/renderer/src/components/settings/primitives.tsx:517 → t('settings.providers.noModel')

但 en.json / zh-CN.json 中 settings.providers 块（line 224-283）没有 noModel 字段。实际的 noModel key 在 sidebar.chat.noModel（line 154），值为 "No model selected"。

当前日志持续报此警告：

[warn] (renderer:console) [i18n] missing translation key "settings.providers.noModel" 
  in namespace "translation" for locale "en"

结论：代码引用了不存在的 i18n 路径。需要在 settings.providers 下新增 noModel key（推荐，因为 ModelSwitcher 和 primitives.tsx 的语义是"未选择模型"而非"sidebar chat"相关），或将代码中的引用改为 sidebar.chat.noModel。

[Sun-sunshine06]

Bug #10 [中] 预览窗口文字在不同窗口大小下显示异常

• 严重度: 中（视觉/UX，影响设计预览质量）

• 位置: 设计预览区域（PreviewPane iframe 内渲染的 HTML）

• 现象: 在不同窗口尺寸下，预览中的文字大小出现异常：

  • 底部标签栏（如"点单"/"历史订单"/"其他"）文字在窗口缩放后明显偏小
  • 商品卡片内的标题、描述、价格等文字尺寸不随窗口等比缩放
  • 部分文字在较小窗口下几乎不可读

• 截图证据:

  

  (截图显示：MIXUE 落地页设计中，底部 tab 文字及商品卡片文字在当前窗口大小下尺寸偏小)

• 可能根因:

  1. 预览 HTML 中使用了固定 px 单位而非 rem/vw/clamp() 等响应式单位
  2. sandbox iframe 的 viewport 元信息（<meta viewport>）未正确传递窗口尺寸
  3. 模型生成的 HTML 未遵循响应式设计规范（packages/core 中 system prompt 缺少相关约束）

• 影响范围: 所有 HTML 预览设计，尤其是包含大量文字内容的落地页/营销页

• 建议修复:

  1. 在 core 的 system prompt 中增加响应式文字约束规则（使用 clamp() 或相对单位）
  2. sandbox renderer 注入 --viewport-width CSS 变量，让生成的 HTML 可基于 iframe 尺寸自适应
  3. 预览区域增加缩放控制（fit-to-window / 100% / 手动缩放）

[Sun-sunshine06]

勘误: 上条 Bug #10 截图链接有误，修正如下。

Bug #10 [中] 预览窗口文字在不同窗口大小下显示异常

• 严重度: 中（视觉/UX，影响设计预览质量）
• 位置: 设计预览区域（PreviewPane iframe 内渲染的 HTML）
• 现象: 在不同窗口尺寸下，预览中的文字大小出现异常：
  • 底部标签栏（如"点单"/"历史订单"/"其他"）文字在窗口缩放后明显偏小
  • 商品卡片内的标题、描述、价格等文字尺寸不随窗口等比缩放
  • 部分文字在较小窗口下几乎不可读
• 复现方式: 生成一个包含底部 tab 栏 + 商品卡片列表的落地页设计（如蜜雪冰城点单页），调整 Electron 窗口大小后观察文字缩放
• 可能根因:
  1. 预览 HTML 中使用了固定 px 单位而非 rem/vw/clamp() 等响应式单位
  2. sandbox iframe 的 viewport 元信息（<meta viewport>）未正确传递窗口尺寸
  3. 模型生成的 HTML 未遵循响应式设计规范（packages/core 中 system prompt 缺少相关约束）
• 影响范围: 所有 HTML 预览设计，尤其是包含大量文字内容的落地页/营销页
• 建议修复:
  1. 在 core 的 system prompt 中增加响应式文字约束规则（使用 clamp() 或相对单位）
  2. sandbox renderer 注入 --viewport-width CSS 变量，让生成的 HTML 可基于 iframe 尺寸自适应
  3. 预览区域增加缩放控制（fit-to-window / 100% / 手动缩放）

[Sun-sunshine06]

Bug #1 — terminated error：已修复 ✅

PR: #263（已合并至 dev/v0.2）

修复内容

当代理服务器（OpenRouter、sub2api 等）在长时间生成任务（12+ 分钟、~50 个 agent turn）中断开 SSE 连接时，pi-ai 内部捕获流错误并将 stopReason 设为 "error"，但 agent.prompt() 正常 resolve —— 导致现有的 withBackoff 重试永远不会触发。

修复方案：在 agent 循环结束后增加 transport-level 重试：

• 检测 stopReason: "error" + 传输层错误消息（terminated、premature close、stream ended、ECONNRESET）
• 剥离失败的 turn（包括中间的 tool-call / toolResult），用干净的对话历史创建新的 agent 实例重试
• 最多重试 2 次

可能的后续问题

• 工具副作用幂等性假设：当前假设 file write 是幂等的（写两次 = 同样的结果）。如果 agent 执行了非幂等操作（如发送网络请求、递增计数器），重放可能产生副作用。目前所有内置工具（text_editor、set_todos 等）都是幂等的，但引入自定义工具时需要注意。
• 长对话历史 replay 成本：如果前 49 个 turn 都成功，第 50 个失败，replay 需要重放完整的对话历史，可能再次触发超时。后续可考虑只 replay 最近 N 个 turn 或做消息压缩。
• 并发写入竞争：如果重试期间 renderer 侧同时写入了文件（如用户手动编辑），replay 可能覆盖这些更改。当前场景下 renderer 为只读预览，暂无此问题。