OpenCreator Bug Fix

目标

对目标范围内的全部未处理问题串行执行轻量但完整的单问题闭环：

读取目标范围 -> 选择首个未处理问题 -> 验证事实 -> 修复代码 -> 运行验证
-> 回写飞书 -> 回读确认 -> 独立提交 -> 重新读取目标章节
-> 仍有未处理问题则继续 -> 全部完成后最终汇报

固定文档：

https://my.feishu.cn/docx/Ax5VdVsyeojaQlxK9i8cl34Enkd

只在当前 OpenCreator 仓库工作。遵守仓库根目录 AGENTS.md，不创建 worktree，不默认启动 Sub Agent，不覆盖用户已有修改。

选择处理范围

1. 用户指定日期时，只读取该日期章节。
2. 用户明确说“今天”时，使用 Asia/Shanghai 当天的 YYYY.MM.DD 章节；章节不存在时直接报告。
3. 用户未指定日期时，读取“按日期分类”的目录并选择最新日期章节。
4. 默认处理目标章节中的全部未处理问题，按文档顺序串行执行。
5. 不主动扫描历史日期；用户要求“所有未处理问题”时才逐日期扫描。

每次触发必须完成目标范围内的全部未处理问题，不能在首个问题闭环后发送最终汇报或结束任务。每完成一个问题的验证、飞书回写、回读确认和独立提交后，重新局部读取目标章节，使用最新 revision_id 确认剩余问题；仍有未处理问题时立即进入下一个问题。

只有以下情况允许提前停止：

• 目标范围内已经没有未处理问题。
• 当前问题无法复现、信息不足，或必须由用户作出产品决策。
• 飞书认证、写入或回读确认失败。
• 相关测试无法通过，且无法在当前问题范围内继续修复。
• Git 提交失败，或用户已有工作区改动无法与本问题改动可靠隔离。

任一问题阻塞时，默认停止后续处理并明确报告阻塞原因，不得跳过该问题后声称目标范围已经全部完成。只有用户明确允许跳过阻塞项时，才可继续处理后续问题，并在最终汇报中列出所有跳过项。

将一个非空的顶层问题列表项视为一个问题。其嵌套列表、紧随其后的说明段落和图片属于同一问题，直到下一个顶层问题或下一个日期标题。

满足以下任一条件时视为未处理：

• 缺少以“原因分析：”开头的段落。
• 缺少以“修复方法：”开头的段落。
• 用户明确要求重新验证，即使已有分析和修复记录。

忽略空列表项。默认跳过已有完整记录的问题，不重复写入。

飞书前置检查

在修改代码前确认文档闭环能力可用：

1. 按 lark-shared 和 lark-doc 的规则操作，文档身份固定使用 --as user。
2. 执行 lark-cli auth status --json --verify，确认用户身份可用。
3. 使用局部读取，不为省事全文拉取：

lark-cli docs +fetch --as user \
  --doc "https://my.feishu.cn/docx/Ax5VdVsyeojaQlxK9i8cl34Enkd" \
  --scope outline --max-depth 4 --detail with-ids

4. 使用目标日期标题的 block ID 获取章节：

lark-cli docs +fetch --as user \
  --doc "https://my.feishu.cn/docx/Ax5VdVsyeojaQlxK9i8cl34Enkd" \
  --scope section --start-block-id "<日期标题 block ID>" --detail full

5. 文本不足以判断 UI 问题时，只预览该问题关联的图片，不批量下载无关素材。
6. 文档不可写时不要开始代码修改；先解决认证或权限问题。

逐问题执行

一次只处理一个问题。完成提交后必须重新读取目标章节并进入下一个未处理问题，不得因为一个问题已经闭环而结束整次 Skill。

1. 记录基线

• 运行 git status --short --branch。
• 记录处理前已有的改动文件。
• 不执行 git pull、git reset、git checkout -- 或其他会改变用户工作区的操作，除非用户明确要求。
• 如果修复必须修改一个已有未提交改动的文件，先判断能否明确隔离本问题改动；无法隔离时暂停并说明，不得把用户改动带入自动提交。

2. 复述问题

用一小段话说明：

• 实际现象。
• 预期行为。
• 已有截图、复现步骤和缺失信息。

不要直接接受提报人的原因推断。先审查代码、现有测试和当前实际行为再下结论。

3. 分类与验证

将问题归为以下之一：

• 真实缺陷：当前行为明确错误，进入修复。
• 体验或明确优化：需求边界清楚且符合现有产品方向，作为问题修复。
• 已经修复：代码和测试已覆盖，不重复改代码；验证后回写当前根因与实现。
• 无法复现或信息不足：不伪造根因，不写“已修复”，保留为未处理并向用户说明缺失信息。
• 大型或存在产品决策的需求：暂停该问题，请用户确认范围；不要借 Bug 修复偷偷扩张架构。

4. 修复代码

• 优先定位根因，不做只遮挡症状的补丁。
• 修改范围保持聚焦，不做无关重构。
• 有现实回归风险时先补失败测试，再修改实现。
• 涉及 Web/Desktop 通用能力时必须复用 Daemon/API/Service，并执行仓库的一致性门禁。
• 平台原生能力必须通过明确 capability 隔离，不允许显示无效入口。

5. 验证

按影响范围选择最小充分验证：

• Daemon 或数据问题：相关单元/集成测试和类型检查。
• Web 交互问题：组件测试或 App 测试；关键流程运行 Browser E2E。
• Web/Desktop 共用行为：两种 Host Bridge 一致性测试。
• Desktop、Preload、IPC 或打包问题：Desktop 测试；必要时重新打包并运行实际 App E2E。
• 共享基础设施或高风险改动：扩大到全仓测试。

验证失败时继续修复，不得回写为已解决。

回写飞书

仅在代码修复和验证成功后回写。沿用文档现有格式：

<p><b>原因分析：</b>说明具体根因、触发链路和受影响范围。</p>
<p><b>修复方法：</b>说明修改模块、行为变化和验证方式。</p>

写作要求：

• 不写“逻辑有问题”“已经优化”等空泛结论。
• 说明为什么会发生，以及修改后为什么不会再发生。
• 不堆砌文件名；文件和模块只用于解释关键链路。
• 已经修复的问题写明当前实现和验证证据，不创建空提交。
• 无法复现、信息不足或等待产品确认时不写这两段，避免把未解决问题伪装成已处理。

定位规则：

1. 原问题有截图或说明块时，在最后一个证据块之后插入。
2. 没有证据块时，在问题列表项之后插入。
3. 已有其中一个段落时，只补缺失段落。
4. 用户要求重新验证且结论变化时，精准替换已有段落，不新增重复记录。
5. 不移动问题、不删除截图、不覆盖全文、不自动移动到“已处理”章节。

优先使用带 revision_id 的 block_insert_after 或 block_replace。每次写操作后重新局部获取目标章节，确认：

• 两个段落位于正确问题下面。
• 内容没有重复。
• 图片和原始问题仍然存在。
• 文档 revision 已更新。

文档回写或回读验证失败时不要提交 Git，也不要进入下一个问题。

每问题自动提交

一个问题满足以下条件后立即提交：

• 代码修改完成。
• 相关验证通过。
• 飞书原因分析和修复方法已回写。
• 回读确认通过。

提交规则：

1. 只暂存本问题实际修改的代码、测试和必要配置文件。
2. 禁止使用 git add -A、git add . 或把处理前已有改动一并提交。
3. 提交前执行 git diff --cached --check 并检查 git diff --cached --stat。
4. 参考最近提交风格生成提交信息；没有明确风格时使用：

fix: <问题简述>

5. 记录 commit hash，然后处理下一个问题。
6. 默认只提交到当前本地分支，不自动 push；用户明确要求推送时才执行。
7. 已经修复且没有代码变化的问题不创建空 commit。
8. 提交失败时停止后续问题，保留现场并报告错误。

最终汇报

只有目标范围内全部问题完成，或命中允许提前停止的阻塞条件后，才可进行最终汇报。简洁列出：

• 已处理问题及结论。
• 每个问题的验证命令和结果。
• 飞书回写是否确认成功。
• 每个问题对应的 commit hash。
• 未处理问题及阻塞原因。
• 当前分支是否领先远端；不要在未推送时声称已经发布。