oc-bugfix git:20260922.e951aaaA

Immutable. This exact content never changes and is served at /api/v1/blob/0b1aa3df95259c67.

---
name: oc-bugfix
description: 处理并回写 OpenCreator 飞书 Bug 文档中的问题，依次完成事实排查、详细方案确认、修复、功能测试和原因/方案回写。仅在用户明确要求处理该 Bug 文档或明确调用本 skill 时使用；普通开发修复不自动启用。
---

# OpenCreator Bug Fix

默认问题文档：`https://q1trqz6q9x7.feishu.cn/wiki/D0O5wUHqGiZoXHk9QPqcZjYhnwh`。

遵守仓库根目录 `AGENTS.md`。本流程中的用户确认只授权已说明的修复方案，不自动授权 Git commit、push、发布、添加文档协作者或修改共享权限。

## 飞书工具铁律

- 本项目已验证可用的 Lark CLI 集成是 `lark-mcp mcp`。必须通过 Node MCP SDK 的 `StdioClientTransport` 启动并调用它；不得在交互式 PTY 中向进程直接发送原始 JSON，因为终端回显和控制字符会导致请求挂起或协议失效。
- 使用 OAuth `user_access_token`，调用工具时设置 `useUAT: true`。启动时只开放本次需要的 docx 工具，例如读取使用 `docx.v1.documentBlock.list`，追加内容使用 `docx.v1.documentBlockChildren.create`。
- 不得因为 `whoami` 或 scope 展示中未出现 docx 权限，就直接判断文档不可编辑。编辑能力以实际的受控 API 调用结果为准；先读目标块，再执行最小写入，并回读验证。
- 写入前读取最新问题块及其 children，确认目标文本、目标 block ID、插入位置和已有图片没有变化。若文档内容与排查时记录不一致，停止写入并重新定位，避免覆盖他人修改。
- 写入必须针对原问题块做最小范围追加，并使用稳定、可复用的 `client_token` 防止重试产生重复内容。禁止覆盖原问题、删除原图片或把内容追加到无关位置。
- 写入后立即重新读取目标问题及相邻块；只有新增内容的位置和文本正确、原有内容与图片仍然存在时，才算回写成功。
- 命令、认证参数或本机凭据来源不明确时，先检查已安装包、CLI 帮助和现有安全存储配置。不得凭空猜测命令，也不得通过登出、重新授权、修改协作者或共享权限来试错。

## 进入流程

只有用户明确调用 `$oc-bugfix`，或明确要求读取、处理、修复、测试或回写上述飞书 Bug 文档时才启用。用户只提出普通 Bug、开发或体验优化时，直接按常规开发流程处理，不读取或回写飞书文档。

1. 通过上述 `lark-mcp mcp` CLI 集成，以 OAuth 用户身份解析 Wiki 节点并读取最新正文；不要依赖先前对话中的文档副本。
2. 用户未指定问题时，根据其描述在文档中定位；存在多个合理匹配时，列出候选并请用户选择，不得猜测。
3. 记录问题在文档中的原始描述和相邻上下文，后续回写必须落在该问题下面，不得只追加到文档末尾。
4. 在第一次需要写文档前，通过一次受控的 docx 写入调用确认当前 OAuth 用户身份具有内容更新能力。失败时保留原始错误并排查调用方式、目标块和授权状态，不得仅凭 scope 展示推断权限，也不得修改成员权限来测试。

## 阶段门禁

严格按以下阶段推进，不得合并“排查并顺手修复”，也不得把方案展示视为用户确认。

### 1. 事实排查

在任何代码修改前完成只读调查：复现或获得可靠失败证据，定位相关调用链、状态和数据边界，检查现有测试，并判断影响 Web、Desktop、Daemon、Runtime、持久化或 Creator 共享能力中的哪些部分。

输出一份诊断结论，至少包含：当前行为、期望行为、复现条件、证据、根因、影响范围和仍未证实的假设。根因未查清时继续调查或明确阻塞，禁止修改源码、配置、测试断言或文档来掩盖问题。

### 2. 方案确认

基于已证实根因给出详细优化方案，包含：拟修改文件或模块、关键逻辑、为何能解决根因、兼容性与回归风险、测试计划、文档回写内容。存在合理备选时说明取舍。

明确询问用户是否确认该方案。收到清晰确认前停止，不得编辑代码。用户调整方案后，更新方案并重新确认；确认只覆盖展示过的范围。

### 3. 修复

确认后实施最小充分改动，保留工作区中的用户修改，不做无关重构。若实施中发现根因判断错误、范围显著扩大、需数据迁移或需改变已确认行为，停止修改并带着新证据返回方案确认阶段。

Creator 相关问题在排查和实现前读取 [references/creator-bug-guide.md](references/creator-bug-guide.md)，并遵守共享 `CreatorCollaborationPanel`、Adapter 边界、Runtime 标准进度和 Activity 语义化规则。

### 4. 功能测试

修复后必须执行能覆盖用户报告流程的功能测试，不得只运行 lint、typecheck 或静态检查。先按风险执行最接近的自动化测试；交互问题在自动化无法证明时补充浏览器验证。测试失败时回到排查阶段，不得回写“已修复”。

验证范围遵守根目录风险分级和“Web 快速验证路径”。纯 Web 页面、样式或局部交互 Bug 通过相关定向测试、Web typecheck 和必要的浏览器验证后即可回写完成，不运行 Desktop 打包或 packaged App E2E。只有 Bug 触及 Host Bridge、Preload/IPC、Desktop capability、Daemon 启动与代理、打包资源/脚本，或目标本身是 Desktop 交付、候选验证或发布时，才升级到实际 App 门禁；不能执行的必需项目要明确残余风险。

### 5. 文档回写

只有修复完成且相关功能测试通过后，才在原问题描述正下方追加：

```text
【问题原因】
<面向维护者的具体根因；包含关键模块或数据流，不粘贴大段日志>

【修复方案】
<实际完成的修改、行为变化和关键兼容处理>

【验证结果】
<实际执行的功能测试及结果；未验证项必须明确列出>
```

先通过 `lark-mcp mcp` 和 MCP SDK transport 重新读取最新文档，确认目标问题及邻近内容未被他人改动，再做最小范围更新。不得覆盖原始问题、图片或其他人的记录，不得把计划写成已完成。如果实际 API 返回权限不足，或无法可靠插入到目标位置，保留代码修复结果和原始错误并明确报告回写阻塞；不得改权限、重建文档或声称已经回写。

## 交付

交付时报告根因、实际修复、功能测试、文档回写位置与结果，以及未验证风险。不要自动创建 Git commit。