[Meta] v0.2 中仍存在的 8个核心代码缺陷 — 汇总与跟踪

[Sun-sunshine06]

背景

在将 main 分支同步到最新版本（v0.2 @ 4c66392）后，对当前所有 open bug issues 进行了代码级根因分析。以下 issue 的问题根源在 v0.2 代码中仍然存在，在相同场景下会稳定复现。

它们不是环境/配置/第三方 provider 的问题，而是 open-codesign 自身代码层面的缺陷。本 issue 作为汇总跟踪单，链接到各具体 issue，便于集中关注。

---

核心缺陷清单（v0.2 已确认）

1. 导出格式内容/样式严重丢失

• Issue: [Bug]: 导出功能存在多格式内容/样式丢失问题 #284
• 影响: PPTX → 只剩标题+项目符号；Markdown → 丢失表格/布局；HTML → 离线不可用；ZIP → 不收集本地资源；PDF → 无页眉页脚
• 根因: packages/exporters/ 各导出器仅做简单正则提取，未做资源内联/渲染保留
• 状态: 未修复，v0.2 代码与之前完全一致

---

2. DeepSeek V4 Pro reasoning_content 回传失败

• Issue: [Bug]: GENERATION_FAILED (fp: b27a1f89) #260 / [Bug]: GENERATION_FAILED (fp: b27a1f89) #252
• 影响: 使用 DeepSeek V4 Pro 等 reasoning 模型做多轮生成时，在 done/verify 阶段报 400 The reasoning_content in the thinking mode must be passed back to the API
• 根因: agent.ts:674-675 设置 thinkingLevel，但 pi-ai agent 路径在多轮对话中没有将上一轮 model 返回的 reasoning_content 正确回传
• 状态: 未修复，pi-ai 层限制

---

3. 非 reasoning 模型被错误发送 role: developer（Kimi / MiniMax）

• Issue: [Bug]: Kimi-K2.6 and other models incorrectly receives role: developer, causing 422 from Azure AI Foundry #257 / [Bug]: GENERATION_FAILED (fp: ebd4e21f) #234
• 影响: Kimi-K2.6、MiniMax-M2.7 等模型在 openai-chat wire 上收到 developer role，被第三方网关拒绝（422/400）
• 根因: packages/providers/src/index.ts:202-211 的 REASONING_MODEL_ID_PATTERN 包含 (^|/)claude-(?:opus|sonnet)-4 和 ^minimax/minimax-m\d，将这些非 reasoning 模型误判为 reasoning，pi-ai 因此发送 developer role
• 状态: 未修复，模式匹配规则未扩展排除列表

---

4. Agent verify/edit 循环无上限，大量消耗 token

• Issue: [Bug]: Model reasoning in loop burning all tokens #251
• 影响: 简单任务运行 10+ 分钟、消耗 $2+，agent 在 "reasoning → editing → reasoning" 中无限循环
• 根因: agent.ts 没有代码级 max-round 硬上限。verifier 只收集 3s 内 console 错误，若无反馈 agent 无方向自修正。done tool 提示词中 "3 rounds" vs "5 rounds" 冲突
• 状态: 未修复，循环仍可能无限进行

---

5. 未 onboarding 时 UI 暴露 design system 入口导致报错

• Issue: [Bug]: RENDERER_ERROR (fp: 213f47a1) #249
• 影响: 新用户在 onboarding 完成前点击 "Link design system"，弹出 Cannot save a design system before onboarding has completed
• 根因: apps/desktop/src/main/ipc/picker.ts:44 的 setDesignSystem() 有 onboarding 守卫，但 AddMenu.tsx 在 UI 层未做前置检查
• 状态: 未修复，入口仍暴露

---

6. Chat 显示 "design.html delivered" 但 Files 面板为空

• Issue: [Bug]: sidebar chat window showing "design.html delivered" but cannot see in the files app #248
• 影响: Agent 声称已交付文件，但 Files 面板看不到任何文件
• 根因: Agent 写入的是虚拟 FS（不持久化到磁盘），Files 面板读取的是磁盘工作区。当 workspacePath === null 时 useDesignFiles.ts:54-56 返回空数组。chat 的 artifact_delivered 和 Files 是两个独立路径
• 状态: 部分改善（PR feat(workspace): read existing files in bound folders + visible Files panel #271 使绑定工作区后 Files 可读），但未绑定工作区时问题仍在

---

7. 生成失败只显示 CodesignError: terminated，缺乏具体错误信息

• Issue: bug: 生成失败只显示 'CodesignError: terminated'，缺乏具体错误信息 #189
• 影响: 用户看到模糊的 "terminated" 后无法判断是网络中断、代理超时还是服务端断开
• 根因: applyGenerateError 直接透传 err.message，没有对 terminated/aborted/premature close 等做分类映射
• 状态: 有 changesets 规划改进，但 v0.2 代码中未落地

---

8. 测试连接通过但实际生成报 403，诊断提示不准

• Issue: 正常对话时报 403 错误：Error invoking remote method 'codesign:v1:generate' #124
• 影响: Settings 中 Test Connection 显示绿色对勾，但生成时弹出 403 "Your request was blocked"
• 根因: Test Connection 只探测 /models 端点，生成走真实推理请求，两条路径被网关/反代区别对待。diagnostics.ts:61 将 403 归为 keyInvalid，WAF/网关拦截场景没有独立提示
• 状态: 未修复，测试/生成路径不一致，诊断分类不准
• 补充: 用户反馈测试连接显示超时但实际生成可用，进一步印证测试/生成路径行为不一致

---

日志新发现缺陷（v0.2 日志分析）

9. Workspace path 绑定冲突，多个设计无法共享工作区

• Issue: bug: Workspace path binding conflict prevents multiple designs from sharing workspace #286
• 影响: 创建或打开多个引用同一工作区路径的设计时，抛出 Workspace path is already bound to another design，阻断操作
• 根因: 工作区绑定逻辑为排他锁，但未向用户说明原因，也未提供共享或解除绑定的途径
• 日志: main.log 2026-05-04 出现 5 次
• 状态: 未修复

---

10. Windows 文件监视器 EPERM 权限错误

• Issue: bug: EPERM file watcher error on Windows when watching workspace files #287
• 影响: files.watch 在 Windows 上抛出 EPERM: operation not permitted, watch，导致文件变更检测中断
• 根因: 文件监视器未对 Windows 权限受限场景做 graceful degradation（回退到 polling 等）
• 日志: main.log 2026-05-04 出现
• 状态: 未修复

---

11. Scaffold manifest 校验失败 — iphone-frame.source 缺失

• Issue: bug: Scaffold manifest validation fails — 'iphone-frame.source must be a non-empty string' #288
• 影响: 每次启动时 manifest 校验报 manifest.scaffolds.iphone-frame.source must be a non-empty string，iphone-frame 脚手架不可用
• 根因: scaffold manifest 中 iphone-frame 的 source 字段为空或缺失，schema 要求非空字符串
• 日志: main.log 在 4/23、4/24、4/25、5/04 各出现 1 次，共 4 次
• 状态: 未修复

---

12. 自动更新器每次启动都报 404 — Cannot find latest.yml

• Issue: bug: Auto-updater fails with 'Cannot find latest.yml' 404 on every startup #289
• 影响: electron-updater 每次启动检查更新均因 latest.yml 不存在（404）而失败，产生 error 级别日志
• 根因: 实验版/开发版没有发布更新通道，但更新器未做版本类型判断，仍尝试检查
• 日志: main.log 每次启动均出现
• 状态: 未修复

---

修复优先级建议

优先级	Issue	理由
P0	#284	导出是核心用户流程，当前几乎不可用
P0	#257 / #234	阻断多个主流模型（Kimi、MiniMax）的使用
P1	#251	直接影响用户成本（token 燃烧）
P1	#260 / #252	阻断 DeepSeek V4 用户使用
P1	#248	用户看到"已交付"但找不到文件，体验极差
P1	#286	工作区绑定冲突阻断多设计工作流
P2	#189	提升可诊断性，减少 support 成本
P2	#124	测试与生成一致性
P2	#249	新用户 onboarding 体验
P2	#287	Windows 文件监视器稳定性
P2	#288	脚手架 manifest 校验
P2	#289	启动日志噪音，影响可读性

---

如何验证修复

每个 issue 的复现步骤都在其原始 issue 中详细描述。修复后可用以下方式验证：

1. [Bug]: 导出功能存在多格式内容/样式丢失问题 #284: 生成一个带图片/卡片的 HTML → 分别导出 PPTX/Markdown/HTML/ZIP/PDF → 检查内容/样式保留度
2. [Bug]: Kimi-K2.6 and other models incorrectly receives role: developer, causing 422 from Azure AI Foundry #257/[Bug]: GENERATION_FAILED (fp: ebd4e21f) #234: 配置 Kimi-K2.6 或 MiniMax-M2.7 → 发送任意 prompt → 不应再收到 422/400 developer role 错误
3. [Bug]: Model reasoning in loop burning all tokens #251: 发送一个简单 prompt（如"生成一个博客页面"）→ 观察生成时间和 token 消耗，不应超过 3 分钟/$0.5
4. [Bug]: GENERATION_FAILED (fp: b27a1f89) #260/[Bug]: GENERATION_FAILED (fp: b27a1f89) #252: 使用 DeepSeek V4 Pro 做多轮编辑 → done/verify 不应报 reasoning_content 错误
5. [Bug]: sidebar chat window showing "design.html delivered" but cannot see in the files app #248: 不绑定工作区直接生成 → Chat 显示交付后 Files 面板应能看到虚拟 FS 中的文件
6. bug: 生成失败只显示 'CodesignError: terminated'，缺乏具体错误信息 #189: 断开网络/配置错误 baseUrl → 生成失败提示应具体指出"网络中断"/"代理超时"等
7. 正常对话时报 403 错误：Error invoking remote method 'codesign:v1:generate' #124: 配置一个 /models 可访问但生成端点 403 的网关 → Test Connection 应同步失败或给出 403 提示
8. [Bug]: RENDERER_ERROR (fp: 213f47a1) #249: 在未 onboarding 状态下点击 Link design system → 应给出友好引导而非 raw error
9. bug: Workspace path binding conflict prevents multiple designs from sharing workspace #286: 创建两个设计绑定同一工作区路径 → 应允许共享或给出明确解除绑定引导
10. bug: EPERM file watcher error on Windows when watching workspace files #287: 在 Windows 上修改工作区中的文件 → 文件监视器不应报 EPERM，应正常检测变更
11. bug: Scaffold manifest validation fails — 'iphone-frame.source must be a non-empty string' #288: 启动应用 → 日志中不应再出现 iphone-frame.source must be a non-empty string
12. bug: Auto-updater fails with 'Cannot find latest.yml' 404 on every startup #289: 启动应用 → 不应再出现 Cannot find latest.yml 404 错误日志

---

本 issue 仅用于汇总跟踪。具体讨论和修复请移步各子 issue。

[github-actions]

感谢 @Sun-sunshine06 的详细根因分析！这份汇总非常清晰，将散落在多个 issue 中的问题集中呈现，有助于团队优先排序和跟踪。

从代码库当前状态看，您指出的根因位置与代码实际逻辑一致：

• packages/providers/src/index.ts 中 REASONING_MODEL_ID_PATTERN 的正则确实覆盖了部分非 reasoning 模型（如 minimax-m\d），可能导致 developer role 误发（[Bug]: Kimi-K2.6 and other models incorrectly receives role: developer, causing 422 from Azure AI Foundry #257/[Bug]: GENERATION_FAILED (fp: ebd4e21f) #234）
• apps/desktop/src/main/ipc/picker.ts 的 setDesignSystem() 存在 onboarding 守卫，但 UI 入口 AddMenu.tsx 缺少前置检查（[Bug]: RENDERER_ERROR (fp: 213f47a1) #249）
• agent.ts 中未发现硬性的 max-round 上限，done tool 提示词中的轮次描述存在不一致（[Bug]: Model reasoning in loop burning all tokens #251）
• 导出器（packages/exporters/）各模块目前以简单的字符串处理为主，缺少资源内联等渲染保留逻辑（[Bug]: 导出功能存在多格式内容/样式丢失问题 #284）
• applyGenerateError 直接透传 err.message，未对 terminated 等做分类映射（bug: 生成失败只显示 'CodesignError: terminated'，缺乏具体错误信息 #189）
• diagnostics.ts:61 将 403 统一归类为 keyInvalid，未区分 WAF/网关拦截场景（正常对话时报 403 错误：Error invoking remote method 'codesign:v1:generate' #124）

其中部分 issue（如 #248 的虚拟 FS 与磁盘工作区分离问题）在 PR #271 中有阶段性改善，但未绑定工作区时的场景仍需进一步修复。

这份汇总为后续修复提供了很好的 roadmap 和验证标准。建议各子 issue 的维护者参考此分析进行针对性修复。

再次感谢贡献！

---

Open-CoDesign Bot

[Sun-sunshine06]

本轮已按该 meta issue 的清单逐项拆 PR 修复并合并到 main：

• [Bug]: 导出功能存在多格式内容/样式丢失问题 #284 → PR fix(exporters): preserve local assets in exports #290（导出资源/离线保真度改进，issue 保持 open 以承接后续导出保真细节）
• [Bug]: Kimi-K2.6 and other models incorrectly receives role: developer, causing 422 from Azure AI Foundry #257 / [Bug]: GENERATION_FAILED (fp: ebd4e21f) #234 → PR fix(providers): keep Kimi and MiniMax chat models non-reasoning #291
• [Bug]: Model reasoning in loop burning all tokens #251 → PR fix(core): cap done repair loop #292
• [Bug]: GENERATION_FAILED (fp: b27a1f89) #260 / [Bug]: GENERATION_FAILED (fp: b27a1f89) #252 → PR fix(core): retry reasoning content failures #293
• [Bug]: sidebar chat window showing "design.html delivered" but cannot see in the files app #248 → PR fix(desktop): show delivered previews in files panel #294
• bug: Workspace path binding conflict prevents multiple designs from sharing workspace #286 → PR fix(desktop): explain workspace binding conflicts #295
• bug: 生成失败只显示 'CodesignError: terminated'，缺乏具体错误信息 #189 → PR fix(desktop): clarify terminated generation errors #296
• 正常对话时报 403 错误：Error invoking remote method 'codesign:v1:generate' #124 → PR fix(shared): diagnose blocked 403 generation errors #297
• [Bug]: RENDERER_ERROR (fp: 213f47a1) #249 → PR fix(desktop): guard design system linking before onboarding #298
• bug: EPERM file watcher error on Windows when watching workspace files #287 → PR fix(desktop): fall back from denied workspace watches #299
• bug: Scaffold manifest validation fails — 'iphone-frame.source must be a non-empty string' #288 → PR fix(desktop): repair stale scaffold manifests #300
• bug: Auto-updater fails with 'Cannot find latest.yml' 404 on every startup #289 → PR fix(desktop): quiet missing update channel checks #301

每个 PR 都已在 CI、CodeQL、PR review / bot review 无 blocker 或 major 后合并；每次合并后本地 main 已同步远端。各对应 issue 已分别留言，能自动关闭或可确认完成的已关闭。

当前仍保留 #284 open，因为导出功能虽然已有一轮修复，但原 issue 覆盖多个格式的保真度长期验收，适合作为后续导出专项跟踪。这个 meta issue 建议也先保持 open，直到 #284 的剩余验收确认完成。