跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

oc-bugfix

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

krillinai · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add krillinai/OpenCreator --skill oc-bugfix

技能说明


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,并遵守共享 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. 文档回写

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

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

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

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

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

交付

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