ai-automation-workflow

name	ai-automation-workflow
description	用于腾讯文档任务清单、Bug 分析、多 Agent 静态调查、本地 Markdown 方案文档、截图整理、修正方案回填和已确认方案实施的 AI 自动化工作流。当 Codex 需要从 docs.qq.com 拉取待修改项、整理本地任务/方案文档、派发聚焦子 Agent、复核具体代码/Prefab/资源/配置修复方案，并把方案状态回填到腾讯文档时使用。

AI自动化工作流

概览

这个 Skill 用来跑一套端到端的 AI 辅助任务工作流：

1. 从腾讯文档拉取目标行。
2. 导出本地 Markdown 任务清单和截图目录。
3. 由主 Agent 复核，配合聚焦子 Agent 逐条分析。
4. 产出具体可执行的修正方案。
5. 将 修正方案 和 确认修正方案 回填到腾讯文档。
6. 用户在 修正方案批注 写反馈后，吸收批注、重新分析并更新本地/线上方案。
7. 用户把 确认修正方案 标记为 已确认方案 后，主 Agent 把具体任务分配给实施子 Agent，修复完成并 Review Check 后，把 确认修正方案 更新为 已处理完成，同时把表格 状态 更新为 C待验收 并读回校验。

腾讯文档读写始终配合 read-tencent-docs-opendoc 使用。不要要求用户粘贴 Cookie 或 token；只有用户明确要求写入线上表格时，才使用已有的 TENCENT_DOCS_TOKEN。

每次触发本工作流都必须先查看在线腾讯文档，并重新拉取本轮目标范围的最新表头、状态、方案、批注和截图线索。即使用户提供了上一次导出的本地清单、方案文档、payload 或实施记录，也只能把它们作为历史上下文和任务范围约束；不得跳过在线表读取，也不得直接基于旧本地文件继续分析、回填或实施。

如果腾讯文档 MCP 报缺少 TENCENT_DOCS_TOKEN，不要立即判断为用户没有配置。先排查当前执行环境是否拿不到凭证：

• 当前 Agent 进程环境：[Environment]::GetEnvironmentVariable("TENCENT_DOCS_TOKEN","Process")。
• Windows 用户环境：[Environment]::GetEnvironmentVariable("TENCENT_DOCS_TOKEN","User") 或 HKCU:\Environment。
• 是否在 WSL/非 Windows Node 中运行脚本；非 Windows Node 不能读取 Windows 注册表里的 HKCU 环境变量，需要显式把 token 注入当前进程，或改用 Windows PowerShell/Windows Node 执行腾讯文档脚本。
• 是否是自动化/子 Agent/已启动很久的进程；它可能没有继承后来写入的用户环境变量。此时优先在当前可用进程里重新读取用户环境并临时设置 $env:TENCENT_DOCS_TOKEN，不要让用户重新粘贴 Cookie。

只有确认当前进程、用户环境、注册表和可用 Windows 执行通道都无法取得 token 时，才报告腾讯文档读取被阻塞。

工作流

0. 入口判定

触发本 Skill 后，先判断用户要跑到哪个阶段，不要把它降级成普通表格导出。

• 入口硬规则：每次工作都先读取在线表。先重新读取子表信息、第 1 行表头，并按当前表头拉取本轮目标范围内的最新行数据；再决定进入清单导出、方案分析、批注修订、回填或实施。不得因为本地已有 tasks.md、方案文档、rows.json、回填 payload 或上轮导出结果，就省略这次在线表拉取。
• 如果用户提供了已有本地清单或方案文档，本地文件只用于限定“本轮关注哪些行/哪些问题”和保留历史分析；必须用最新在线表数据刷新这些行的 状态、负责人、修正方案、修正方案批注、确认修正方案、补充说明和截图线索。若线上状态与本地文件冲突，以线上表为准，并在本轮摘要里说明冲突。
• 每轮从腾讯文档开始时，确认修正方案 = 处理中 是最高优先级队列。只要整表存在 处理中 行，就先进入第 6 阶段收尾这些已领取任务：先复核它是否仍有可执行方案，再完成或修复实现、Review Check、验证。复核发现方案错配、缺关键截图/视频/配置 ID、需求意图不清或无法判断改动点时，不要继续占用 处理中；按第 4 阶段把 修正方案 修订为 【信息不足】、追加 Agent 修订留痕，并把 确认修正方案 改为 信息不足 后读回。只有实施通过后才写 确认修正方案 = 已处理完成 与 状态 = C待验收。此时不要先处理未接入空方案、批注修订或新 已确认方案 领取，除非用户明确要求临时切换。
• 用户只说“AI自动化工作流 + 收集/整理/拉取没有修正方案的任务”时，默认至少执行第 1 阶段：按表头定位、筛选目标行、导出本地 Markdown 清单和截图目录，并说明下一步应该进入分析阶段；不要只输出 TSV 或只统计状态。
• 用户说“写方案 / 分析 / 怎么修”时，必须继续执行第 2-3 阶段：逐条静态分析、必要时开子 Agent、本地方案文档落盘。
• 用户说“回填”时，必须执行第 4 阶段：生成 payload、写入目标列、读回校验。
• 用户说“批注 / 用户审核意见 / 更新方案”时，必须执行第 5 阶段。
• 用户说“已确认方案 / 开始修 / 实施”时，必须执行第 6 阶段。
• 如果用户明确说“只导出清单/只要 TSV/不要分析”，才允许停在清单导出；最终回复要标明这是用户要求的简化模式。

1. 拉取行

• 本阶段是每轮必经的在线同步步骤：无论后续是导出、分析、批注修订、回填还是实施，都先从腾讯文档重新拉取本轮目标行。除非在线读取被确认阻塞，否则不要直接复用旧 rows.json 或旧 Markdown 作为当前事实来源。
• 每次先重新读取子表信息和第 1 行表头。用户插入列后，不要假设列位仍然是 H/J/K。
• 按表头文字识别列，尤其是 描述、截图、发起人、日期、类型、内容说明、调整补充说明1、调整补充说明2、优先级、状态、负责人、修正方案、修正方案批注、确认修正方案。
• 只按用户指定范围筛选，例如月份、状态、负责人、发起人或优先级。用户没给足筛选条件时，先读取表头和样例行，再让用户确认产品口径。
• 如果用户说“没有修正方案 / 未写修正方案 / 待出方案 / 待处理”但没有明确指定状态，默认只处理 A未开始。不要把 D已完成 纳入方案产出；B进行中、C待验收 也需要用户明确说要包含才处理。
• D已完成 默认视为已经不需要出修正方案。只有用户明确要求“补历史方案”“复盘已完成项”“已完成也回填方案”时，才允许纳入，并且导出/回填摘要必须明确标出这是用户指定的例外。
• 修正方案 是否有值表示 AI 是否已经接入过这条优化调整项：
  • 收集“未写修正方案 / 未接入 / 待出方案”的任务：筛选 状态 = A未开始 且 修正方案 为空。
  • 收集“已整理方案 / 待审核 / 批注修订 / 回填校验”的任务：筛选 状态 = A未开始 且 修正方案 非空，或使用用户指定的当前任务集合。
  • 不要用 负责人、确认修正方案 或 修正方案批注 替代 修正方案 是否为空来判断 AI 是否接入。
• 如果用户给了已有本地清单或方案文档，例如 <任务清单>.md 或 <方案文档>.md，必须把这个文件视为当前任务集合来源。后续“没有修正方案”“补齐方案”“收集任务包”只能在该文件的任务集合内取交集，不能重新扩大到整张表。
• “没有修正方案”是附加过滤条件，不是完整过滤条件。除非用户明确说“整张表所有没有修正方案的行”，否则必须同时保留当前上下文中的负责人、状态、月份、行号集合等范围。
• 导出前要打印或写入筛选条件摘要，但摘要内容根据用户这次的真实要求来写；例如用户按负责人/状态/月筛，就写这些条件，用户按“已确认方案”筛，就写确认状态条件。不要把某一次任务的话术固定成所有导出的模板。若导出数量和已有清单数量明显不一致，例如从 104 变成 360，必须停止并说明口径冲突，不要继续生成任务包。
• 输出目录默认放在用户当前工作区或用户指定目录。不要把文档产物写进只读分析目标项目或临时目录，除非用户明确要求临时产物放那里。
• 本地输出一个 Markdown 任务清单和一个截图目录。能直接下载的图片 URL 下载到本地；docimg*.docs.qq.com/image/... 这类图片裸开经常被防盗链拦截，下载时要带 Referer: https://docs.qq.com/，Markdown 中引用下载后的本地图片文件，不要继续外链 docimg。
• 腾讯文档页面里同一张 docimg 可能同时出现缩略图和大图 URL。带 ?imageMogr2/thumbnail/... 的是缩略图，只能作为定位线索，禁止作为最终截图写入 Markdown。下载正文截图时必须使用去掉缩略图参数后的原图 URL，或页面预览里带 ?w=...&h=... 的大图 URL。
• 如果已有本地清单中每条任务已经有截图链接，重新导出任务包时必须保留这些截图并挂在对应任务段落下；可以复用原相对路径，也可以复制到新图片目录后改成新相对路径。不能把截图丢掉。
• 截图必须内嵌在 Markdown 正文的对应 bug 段落中，也就是直接写 ![截图1](...)。只把图片下载到目录、只写 manifest、只在 README 说明、或只放文末图集，都算没有完成截图整理。
• 通过 Chrome/opendoc 批量抓到的 docimg 只有在能可靠映射到具体表格行或具体任务时，才允许写到该任务段落。无法映射的图片只能放在诊断 manifest 里，不能放进正文 Unmapped Gallery 冒充任务截图。
• 如果源清单某条有截图，而新任务包对应条目没有截图，导出应视为失败并停止，提示截图映射丢失。
• 如果 sheet.get_cell_data 只返回空格或空字符串，不要断言“没有图片”或“无法下载图片”，只能写“当前读取通道未暴露截图 URL”。需要继续尝试 opendoc 原始数据、已登录 Chrome 页面 DOM/网络请求，或用户导出的文件来提取 docimg*.docs.qq.com/image/... 直链。
• 如果 sheet.get_cell_data 返回空格或空字符串，但用户截图、页面缩略图、导出的 xlsx、批注内容或上下文显示该行有截图，必须把它当成“截图存在但当前通道未暴露 URL”。导出、分析、回填和领取实施前，不要直接写 信息不足；先解决截图映射问题。
• 如果表头定位到的 截图 字段有任何非空值、占位文本、图片标记，或 opendoc/Chrome/导出文件显示该行存在图片，但本轮任务包没有成功下载并内嵌对应截图，必须立刻停止后续分析、派 Agent、回填或实施。先排查为什么图片通道没有拉到：确认目标行切片是否进入 opendoc、Chrome 是否已登录、网络请求是否包含 dop-api/opendoc、docimg 是否被防盗链/缩略图参数拦截、是否需要滚动到目标行或换用用户导出的 .xlsx / .csv。只有截图被可靠下载并映射，或所有规定通道都已尝试且 manifest 明确记录“当前读取通道未暴露截图 URL/图片无法映射”的证据后，才允许继续。
• 截图 列只有“视频在 QQ 群”“见群图片 message_id”这类文字线索时，不等同于腾讯表格内已有可下载图片。若现有通道无法取得该 QQ 视频/图片，且缺少它就无法判断期望表现或具体改动点，应在复核后写 【信息不足】，说明需要补充哪段视频/图片、ID 或复现步骤。
• “没有修正方案”只表示 修正方案 列为空，不等于可以跳过截图、本地 Markdown、后续分析和方案产出。

重复导出优先使用 scripts/export_tencent_bug_rows.mjs。

腾讯文档截图获取流程

腾讯文档表格截图经常不是普通单元格文本，必须按下面顺序获取，避免丢图或错配行：

1. 先用 sheet.get_sheet_info / sheet.get_cell_data 读取子表、表头和普通字段，只把它作为筛选、行号、状态和负责人等文字数据来源；不要用它判断截图是否存在。
   • 只要 截图 列本身有非空内容、空格占位以外的可见值、图片占位，或同一行其他列含图片迹象，就把该行标记为“截图待确认”。若后续没有把图片下载并嵌入该任务正文，导出流程必须失败并转入截图故障排查，不得继续产出方案或回填。
2. 从已登录 Chrome 页面资产或网络资源中找到当前页签对应的 https://docs.qq.com/dop-api/opendoc?... URL。优先使用包含目标 tab、block_start_row、block_end_row、block_start_col、block_end_col 的 opendoc 请求。
3. 用 read-tencent-docs-opendoc 的 protobuf-like 解析逻辑读取 opendoc related_sheet。图片通常在单元格 payload 的 rich JSON / field 17 中表现为 [image] https://docimg*.docs.qq.com/image/...；这一步能拿到图片所在的真实行列。
4. 筛选任务时，如果 描述 单元格只有图片而普通读取显示为空格，opendoc 仍应视为有内容；这类行要纳入任务，并把图片作为该条描述/截图证据。
5. 对每条目标行，收集该行 截图、描述、内容说明、补充说明列中出现的 [image] docimg...，按该行号下载到本地图片目录，命名类似 row088_img1.png。
6. 下载 docimg 时带 Referer: https://docs.qq.com/ 和浏览器 User-Agent。如果 URL 包含 imageMogr2/thumbnail，先去掉 query 使用原图 URL；如果页面给的是 ?w=...&h=... 大图参数，也可以作为备选，但正文优先使用非缩略图文件。
7. 把下载成功的图片用相对路径嵌入该行对应的 Markdown 任务段落：![截图1](images/row088_img1.png)。不要把图片集中追加到文末图库，也不要只写 manifest。
8. 生成 row_image_map.json / manifest.json 记录 rowNumber、列名、原始 URL、实际下载 URL、本地路径、下载状态和映射方法。内部 manifest 可以保留，用户主入口仍是 tasks.md。
9. 如果 opendoc URL 过期或当前切片不包含目标行，重新从 Chrome 当前页面资源里抓最新 opendoc，或滚动/刷新腾讯文档让目标行进入切片后再抓；不要退回“截图不可下载”结论。
10. 如果页面/Chrome/opendoc 通道不稳定，但 MCP 提供 manage.export_file / manage.export_progress，可以导出 xlsx 作为截图兜底通道。导出后解析 xl/workbook.xml、xl/worksheets/_rels/sheetN.xml.rels、xl/drawings/drawingN.xml 和 drawing rels；OOXML 的 from.row / from.col 是 0-based，from.row = 腾讯表格行号 - 1 且 from.col 对应截图列时，即可把 drawing 的 media 图片可靠映射到目标行。提取图片后写入 manifest，mappingMethod 写 xlsx_drawing_anchor。
11. 使用 xlsx 兜底时，必须先验证下载文件是完整 ZIP，能打开并找到 xl/workbook.xml；如果下载被超时截断或 ZIP 中央目录缺失，重新下载，不能拿半截文件继续解析。
12. 交付前核对：tasks.md 中的图片引用数量应等于本轮已映射成功的图片数量；图片文件应存在；正文中不得出现 docimg 外链、thumbnail 链接、Unmapped Gallery 或“另见全量截图 MD”。

数据格式稳定规则

• 数据提取方式可以根据具体情况选择：MCP 表格值、opendoc 原始数据、已登录 Chrome 页面、旧 Markdown 清单、导出的 .xlsx / .csv 都可以作为输入。
• 日期字段统一使用 YYYY-MM-DD 作为规范格式。适用字段包括但不限于 日期、目标验收日期、验收日期、date、targetDate、回填 payload 中的日期值，以及方案/任务 Markdown 中展示的日期。
• read-tencent-docs-opendoc 读取到 Excel 日期序列号时会转换为 YYYY-MM-DD；如果输入是文本日期，只有在能无歧义识别为完整年月日时才规范化为 YYYY-MM-DD。无法确认的值必须保留原文，不要猜测年份、月份或日期。
• 结构化数据中推荐同时保留规范值和原值：date / targetDate 放 YYYY-MM-DD 或 null，dateRaw / targetDateRaw 放来源原文。若来源本身已是规范日期，raw 可与规范值相同。
• 写入腾讯文档日期列时，默认写字符串 YYYY-MM-DD，不要写 YYYY/MM/DD、YYYY年M月D日、M/D 或“今天/明天”。只有用户明确要求保留表格日期序列号、公式或原样文本时，才按用户要求写入，并在回填摘要中说明例外。
• PM备注、方案留痕、批注同步、manifest、归档文件名中的日期也统一用 YYYY-MM-DD；需要时间时使用 YYYY-MM-DD HH:mm，并按当前项目/用户所在时区解释，不要混用相对日期。
• 无论输入方式是什么，落地数据格式必须保持一致，至少输出：
  • 用户阅读的 tasks.md 或方案 Markdown。
  • 结构化 rows.json，保存内部定位信息。
  • 图片目录，例如 <任务清单名>_images/ 或任务包内 screenshots/。
  • 图片 manifest.json，记录每个任务对应的本地图片路径、来源 URL、下载状态、映射证据。
• 除非用户明确要求，不要额外生成给用户阅读的截图索引 Markdown，例如 all_screenshots.md、all_screenshots_full.md、README.md 图库说明。内部诊断可以用 JSON/manifest；用户主入口必须是一个 Markdown。
• 不能把 tasks.md 写成“请另看 all_screenshots/README 才能看到完整截图”。如果用户说“一个 task.md 就够了”，tasks.md 必须包含所有已映射截图正文引用。
• rows.json 中每条任务必须保留内部字段：sourceRowNumber、sourceRowIndex、title、desc、priority、status、owner、submitter、date、dateRaw、targetDate、targetDateRaw、type、details、solution、solutionComment、confirmSolution、images[]。
• 如果表格存在 调整补充说明1、调整补充说明2 或其他补充说明类列，必须写入本地 Markdown 的对应任务段落，并在 rows.json 中保留为 supplements[]。
• images[] 至少包含：localPath、markdownPath、sourceUrl、downloadStatus、mappingMethod。如果图片来自旧清单，mappingMethod 写 source_markdown；来自 Chrome/opendoc 映射，写具体方法。
• 用户阅读的 Markdown 默认不展示表格行号；结构化 JSON 和回填 payload 必须保留行号，供回填和子 Agent 精确定位。若用户明确要求保留行号，则按用户要求展示。
• 用户阅读的 Markdown 也应尽可能展示完整上下文，不要只展示标题和少数字段。默认展示或在有值时展示：描述、截图、发起人、日期、目标验收日期、类型、内容说明、修正方案、修正方案批注、确认修正方案、负责人、优先级、状态、调整补充说明1、调整补充说明2。除非用户明确要求极简清单，否则不要把这些字段只藏在 rows.json。
• 如果某种提取方式拿不到所有字段，仍输出同样字段名，缺失值置空或写 null，不要临时改字段名。

Markdown 插图规则

• 方案文档和任务清单里的截图必须先落到本地图片目录，例如 <工作区>\<任务清单名>_images\bug001_img1.png，再在 Markdown 中引用本地文件。
• 写入 Markdown 文件时，优先使用相对路径，保证文件夹整体移动后仍可查看：

  ![截图1](<任务清单名>_images/bug001_img1.png)
  

• 如果文档不在图片目录的同级目录，按 Markdown 文件所在目录计算相对路径；不要写成 docimg*.docs.qq.com 外链。
• 只有在聊天回复里需要让 Codex Desktop 直接预览本地图片时，才使用绝对路径：

  ![截图1](C:/path/to/workspace/<任务清单名>_images/bug001_img1.png)
  

• Windows 路径写进 Markdown 图片链接时用 /，不要用反斜杠，避免被 Markdown 当成转义。
• 如果图片下载失败但已有原始 URL，在文档里写“截图待下载：”或“当前读取通道未暴露截图 URL”，不要伪造不存在的本地图片路径。
• 如果拿到的是 docimg 缩略图 URL，例如包含 imageMogr2/thumbnail，先把它规范化为同一路径的非缩略图 URL 再下载；manifest 中保留原始 URL 和实际下载 URL，方便追溯。如果无法转换或原图下载失败，不要把缩略图嵌入正文，改写“截图待下载/待映射”。
• 每个任务段落里的截图必须紧跟在该任务元信息或现象后面，格式如下：

  **截图**
  
  ![截图1](<任务清单名>_images/bug001_img1.png)
  

• ![截图1](...) 这一行必须出现在任务正文中，不能只存在于附录、manifest 或截图目录 README。
• 不要把所有图片集中放到文档末尾的 Unmapped Docimg Image Gallery。未映射图片只能进入 manifest/README 作为诊断信息，不能进入任务正文。
• tasks.md 头部不要写“另见全量截图预览 MD”“全量图片目录”来替代正文截图。可以写图片目录位置，但正文条目必须自己包含对应截图。

Markdown 任务展示规则

• 面向用户阅读的 Markdown 任务包和方案文档，标题、导出说明、筛选说明、字段是否展示，都根据用户本次要求生成；不要把某个历史文件的话术硬套到所有任务。
• 默认不要把腾讯表格行号写成标题或字段；不要写 Row 88、行号：88 这类内容。用户明确要求行号时除外。
• 标题使用自然序号和问题标题，例如：

  ## 1. 点击箭头应该就能选中
  

• 需要回填腾讯文档或派发子 Agent 时，行号只保存在内部结构化文件中，例如 rows.json、回填 payload 或调度清单；不要把它混进用户阅读的正文。
• 如果子 Agent 必须按腾讯表格定位，可以在任务包中给它内部映射信息或 rows.json 路径，但最终汇总文档仍不展示行号。
• 截图是格式硬规则，不受导出说明变化影响：只要某条任务有截图，就必须在这条任务正文里内嵌 ![截图N](...)。

交付前质量门

在对用户说“已完成/整理好了/截图补好了”之前，必须检查主 Markdown 本身，而不是只检查图片目录：

• 主 Markdown 不包含 Unmapped Docimg Image Gallery、all_screenshots、all_screenshots_full、另见全量截图、未按行号精确映射图库 这类旁路图库说明。
• 主 Markdown 中的每个 ![截图N](...) 都位于对应任务段落内，而不是文末集中图集。
• 主 Markdown 中的图片路径都是本地相对路径或用户要求的本地绝对路径；不要使用 docimg*.docs.qq.com 外链。
• 主 Markdown 中不得引用 imageMogr2/thumbnail 缩略图；下载目录中也不应把缩略图当最终截图。
• 如果源清单或已映射数据表明某条有截图，而主 Markdown 对应条目缺失 ![截图N](...)，本轮导出失败，不能说完成。
• 如果 截图 字段有值但没有任何本地图片引用，不能进入分析、子 Agent、回填或已确认方案实施阶段；先补跑 opendoc/Chrome/导出文件的截图排查，并把排查结果写入 manifest.json。
• 如果只下载到了大量图片但无法映射到任务，必须如实说“已下载但未映射，不能写入任务正文”，不要把它包装成完成。
• 如果用户要求“一个 task.md 就够了”，不要生成或保留额外用户阅读 Markdown；必要的内部数据放 JSON/manifest。
• 交付前必须运行 scripts/validate_task_markdown.mjs --md <主Markdown>。脚本失败时不能说完成，必须修正文档或如实说明无法把图片可靠映射到任务正文。

2. 分析行

• 主 Agent 负责最终审稿、合并和质量判断。
• 如果用户明确要求“开子 Agent / 多 Agent / 子 Agent 给具体解决方案”，主 Agent 不要抢先替子 Agent 做完整逐条调查。主 Agent 的工作是拆任务、给足上下文、调度、复核、合并；只做必要的轻量核对和质量把关。
• 可以尽可能使用多个子 Agent 并行，但前提是每个任务包都小而明确。多 Agent 的目标是提高并行度，不是把任务合成大包。
• 主 Agent 是唯一负责改最终 Markdown/JSON/payload 的角色。子 Agent 只返回结构化调查结果和建议状态，不直接改主文档、不直接回填腾讯文档，除非用户对某个子 Agent 明确授权。
• 可给方案 / 方案待确认 / 信息不足 这类单条状态应由负责该条的子 Agent 基于证据先判断。主 Agent 只做全局复核和纠偏：发现状态和证据不一致时退回、改为 信息不足 或要求补查；不要替所有条目集中拍脑袋判状态。
• 子 Agent 可以并行，但每个任务包必须明确：工作目录、行号、标题、截图路径、只读约束，以及需要分析代码、Prefab YAML、资源还是配置。
• 派发子 Agent 时必须显式传入本 Skill 路径和子 Agent 规则路径，并要求它先阅读：
  • C:\Users\%USERNAME%\.codex\skills\ai-automation-workflow\SKILL.md
  • C:\Users\%USERNAME%\.codex\skills\ai-automation-workflow\references\subagent-task-rules.md 不能只写“按 ai-automation-workflow 规则”或依赖主 Agent 已加载的上下文。
• 子 Agent 任务包必须按当前任务清单中的具体条目或强相关小组派发。不要先按主 Agent 自己猜的“大类”批量归类，例如把登录、性能、建造、钓鱼、剧情、UI 等几十条混成一个大包。
• 每个子 Agent 的范围应小而明确：优先 1 条；确实强相关时可以 2-5 条；不要一次塞几十条、跨系统条目或“类似问题”。如果需要并行，就开多个窄任务，而不是一个宽任务。
• 禁止把几十条或上百条一次性交给主 Agent 或子 Agent 做“文本复核/状态分类/批量替换”。例如 2-120、121-240 这类范围任务是不合格任务包。
• 大批量清单必须分批推进。每一批建议 5-10 条，且每条都要有独立标题、截图、当前方案/批注和输出位置。上一批质量通过后再开下一批。
• 在一批 5-10 条里，可以同时开多个子 Agent，例如每个子 Agent 负责 1 条，或负责 2-5 条强相关小组。主 Agent 等一批结果回来后统一复核和写文档，再进入下一批。
• 主 Agent 不要先把全量条目批量写成 方案待确认 / 信息不足，再让子 Agent 复核。正确顺序是：子 Agent 按小包逐条调查并给状态，主 Agent 复核后再写入本地文档和回填 payload。
• 子 Agent 不应输出 TSV 替换行来让主 Agent 批量覆盖正文。子 Agent 输出应是逐条结构化分析块：状态、入口、证据、根因/信息不足原因、具体方案或缺失信息。主 Agent 复核后再整合到 Markdown/JSON/payload。
• 主 Agent 不要在子 Agent 尚未返回前宣布“这些足够先出第一版修正方案框架”或类似预设结论。必须等子 Agent 的证据回来，并复核关键文件/入口后再写入方案。
• 每个子 Agent 提示词必须自包含。可以使用完整问题包，也可以使用文档索引包：给出文档路径和这个子 Agent 负责的准确 row/section。
• 每个子 Agent 提示词都必须要求先阅读本 Skill 内的 references/subagent-task-rules.md。同时把 references/subagent-task-template.md 中的必带规范块也贴进任务包，避免子 Agent 没有加载任何上文。
• 子 Agent 必须输出：真实入口、调用链/逻辑判断、根因、具体修改方案、涉及代码/Prefab/资源/配置、缺少的信息。
• 子 Agent 必须同时输出本条建议状态：可给方案、方案待确认 或 信息不足。有具体可执行方案才可建议 方案待确认；方案待确认 的意思是 Agent 已经能确定并写出可执行修正方案，正在等待用户审核确认，不表示 Agent 还没想清楚方案。需求意图不清或无解方案建议 信息不足；意图清楚、已有具体方案但还缺运行态/Prefab 绑定/日志证据时，也可建议 方案待确认，并只写清这些不影响方案成立但需要最终验收确认的点。
• 信息不足 主要用于以下情况：优化调整项的意图不明确；不知道这条到底想改成什么；不知道期望表现是什么；有多个合理修法但拿不定该选哪一个。此时必须返回 信息不足，说明需要补充哪方面的产品/表现意图；不要编造需求、不要硬凑方案。
• 如果按需求描述应该存在某个入口、文件、Prefab、资源、配置或模块，但在目标项目中找不到，也归为 信息不足。这表示需求和项目现状对不上，无法判断怎么改。
• 这种 信息不足 必须写清：查了哪些路径/关键词；没找到什么；需要用户确认真实入口、资源名、配置 ID 或模块名。
• 如果问题意图清楚，但只是静态查证缺少 Unity 运行态、Prefab 实际绑定或日志证据，优先写具体候选入口和 方案待确认，不要轻易归为 信息不足。
• 除非用户明确要求实施，否则子 Agent 只读分析。
• Unity 项目中，允许子 Agent 查代码、CSV/配置、Prefab/Scene YAML、资源名和截图。不要启动 Unity，除非用户明确要求。

派子 Agent 前先阅读 references/subagent-task-template.md。在这个工作流内，references/subagent-task-rules.md 是每个子 Agent 工作前必须阅读的规范页。

3. 写本地方案文档

每条方案要足够具体，能交给工程师直接处理：

• 现象：面向玩家的问题概述和截图引用。
• 影响系统：UI、任务流程、剧情演出、场景表现、资源、配置/文案、云存档、小游戏等。
• 确认入口：具体类/方法、Prefab、YAML 路径、CSV/配置行，或带理由的候选入口。
• 原因分析：Bug 类写根因；设计向、优化向写现状、调整意图和判断依据。
• 修改方案：具体代码、Prefab/UI、资源、配置改动。
• 验收方式：用户要求时写具体复现路径和通过标准。
• 风险：只写真实风险，不写空泛套话。
• 方案待确认：已经有具体可执行方案，等待用户确认；只有存在会影响最终取舍、表现验收或资源绑定的确认点时，才在方案正文里写清这些确认点。

避免“检查一下”这类空话。静态证据不足时，明确写缺少什么信息。

4. 回填腾讯文档

• 回填前必须读取并核对 状态 列。默认只回填当前任务范围内 A未开始 的行；如果 payload 或本地任务包包含 D已完成，必须停止并剔除这些行，除非用户明确要求给已完成项补方案。
• 不要把 D已完成 行写成 方案待确认 或 信息不足。已完成项通常不再需要修正方案审核，强行回填会污染任务板。
• 修正方案：写主 Agent 复核后的本地方案文本。
• 修正方案 单元格不是脚本模板输出，也不是子 Agent 原文直贴。主 Agent 必须逐条整理后再写入，保证每条都按当前问题的具体情况组织成可读的方案文本。
• 回填可以批量写入，但写入内容必须逐条由主 Agent 整理和确认。脚本/MCP 只能负责定位行列、生成 payload、执行写入和读回校验，不能代替主 Agent 判断、改写或批量生成方案。
• 如果本地方案文档格式不符合最终回填口径，主 Agent 要先逐条改正文档内容；不要让脚本把旧格式自动“规范化”成新格式后直接回填。
• 修正方案 正文只写工程师需要阅读的分析和方案，不写 Agent 状态。可以使用下面的阅读结构，但内容和段落要按任务类型取舍。Bug 类通常写原因分析；策划、设计、内容、体验调整类不一定有原因，不要为了格式硬编：

  【原因分析】
  <Bug 类写基于代码、Prefab、资源、配置或截图证据的根因；设计向、优化向、体验调整、内容调整类可写当前表现、调整意图和期望方向；如果本条确实不需要原因段，可以省略。不要硬编 Bug 根因。>
  
  【修改方案】
  <有具体方案时写需要改什么代码/Prefab/UI/资源/配置。>
  
  【信息不足】
  <没有具体方案时，说明缺少什么产品意图、期望表现、真实入口、资源名、配置 ID 或模块名。>
  

• 对已经有具体可执行方案的行，修正方案 正文通常只需要 【原因分析】 和 【修改方案】。确认修正方案 状态列单独写 方案待确认，表示方案已经给出，等待用户确认；不要为了匹配状态而在 修正方案 正文末尾硬加 【待确认】、【方案待确认】 或类似段落。
• 只有确实存在会影响最终取舍的用户决策点，例如两种方案需要选一种、缺少资源命名/配置 ID、需要产品确认具体数值或表现标准时，才在正文追加 【待用户确认】 段，并写具体问题。单纯“等用户确认方案”“需要验收看看效果”“Unity 运行后复核”不要写成正文段落。
• 没有具体方案时，修正方案 正文必须写 【信息不足】 段，确认修正方案 状态列写 信息不足。信息不足 表示当前还不能判断怎么改。
• 【原因分析】 是推荐段落，不是所有任务的强制段落。Bug、异常、缺失、错误表现、回归、配置失效类基本需要写；策划、设计、内容、体验、数值或布局调整类可以省略原因段，或只写现状/调整意图，不要硬编 Bug 根因。
• 写 【原因分析】 时可以写“静态未发现已修支持”“当前链路仍然...”“需求和项目现状不匹配...”，但必须说明证据来源，不要只写结论。
• 【修改方案】 里优先用短项目符号写代码、Prefab/UI、资源、配置，例如 - 代码：...、- Prefab/UI：...；只写和本条相关的项，不要凑满四类。
• 生成 payload 的脚本只负责读取主 Agent 已整理好的文本、定位行列和校验写入；不要让脚本自动编写根因、方案或状态描述。
• 确认修正方案：
  • 只有已经写出具体可执行修正方案，且能说明需要改什么代码、Prefab/UI、资源或配置时，才写 方案待确认。
  • 没有具体解决方案、只是说明不确定/需要用户确认/需要复现/需要看日志，或方案空泛到不能交给工程师修改时，一律写 信息不足。
  • 用户审核后会把有解方案改成 已确认方案。这是实施入口，Agent 不能把未经用户确认的行自行改成 已确认方案。
  • 进入实施时，主 Agent 先把分配出去的目标行从 已确认方案 改成在线表下拉项 处理中，表示 Codex 已接手修复。
  • 子 Agent 完成后，主 Agent 必须 Review Check 修改、验证结果和影响范围；确认没问题后，再把该行 确认修正方案 改成 已处理完成，并同时把表格 状态 改成 C待验收，两列都要读回校验。
  • 关闭 表示这条不再需要 Agent 关注，后续拉取、分析、实施、回填都默认忽略。
• “确认目标”“已修改并确认目标”“已分配给 Agent/实现 Agent”是实施阶段的领取/同步信号，不是完成信号。看到这类反馈时，只能进入或保持 处理中 / 实现观察；不得改成 已处理完成，也不得把表格 状态 转成 C待验收。只有子 Agent 明确完成、主 Agent Review Check 通过，或负责人明确说“已实装/已修完/可验收”时，才进入待验收。
• 修正方案批注：留给用户，不写 Agent 状态。
• 修正方案批注 默认是用户字段，不用于写 方案待确认 / 信息不足 这类 Agent 状态。但如果 Agent 修改了一个已经存在的 修正方案，必须在该行 修正方案批注 末尾追加一条变更留痕，让用户能看出 Agent 改过哪些内容。推荐格式是 [Agent修订：<简短说明>]，也可以使用 [写入改了什么] <简短说明>。
• 后续看到 修正方案批注 中存在 [xxx] 形式的方括号标记，默认视为这条 修正方案 已被 Agent 修订过；重新分析或回填时必须阅读这些标记，不要当成普通用户批注忽略。
• 首次给空白 修正方案 写入方案时，不需要在 修正方案批注 写变更留痕；只有覆盖、修订、重写、补充已有方案时才追加。
• 追加变更留痕时必须保留用户原有批注内容，不要覆盖或清空。若已有批注非空，在末尾追加空行再写 [Agent修订：...]。
• 示例：

  这个是解锁新动物 unlocknew xxx，好像是那个 tween 被错跑了
  
  [Agent修订：将方案从运动会通用点击提示修订为 UnlockNewNPCWindow / Breath 组 tween 已在 Prefab 中但未由控制器播放，需要绑定/播放 breathTween]
  

• 负责人：只有用户明确要求分配时才写。
• 写入前生成本地 payload 并检查目标行列；写入后读回线上区域并报告异常行。
• 如果 payload 生成出现描述匹配警告，或读回校验出现异常行，先停下来解决行映射问题，不要继续写线上单元格。
• 回填优先使用已有脚本和 MCP 包装器，不要为一次性写表临时新建 tencent_doc_*backfill*.mjs 这类脚本：
  • 读取/写入腾讯文档：C:\Users\%USERNAME%\.codex\skills\read-tencent-docs-opendoc\scripts\tencent-docs-mcp.mjs
  • 生成回填 payload：scripts/build_solution_backfill_payload.mjs
  • 读回校验：scripts/verify_tencent_backfill.mjs
• 只有当现有脚本缺少可复用能力，且这项能力会被后续工作流反复使用时，才允许新增脚本；新增脚本必须进 skill 的 scripts/，不能散落在项目临时目录。

回填前阅读 references/tencent-docs-backfill-rules.md。生成和校验 payload 使用 scripts/build_solution_backfill_payload.mjs 与 scripts/verify_tencent_backfill.mjs。

5. 吸收用户批注并修订

第一轮回填后，用户通常会在 修正方案批注 中写审核意见。

• 重新读取表头，扫描目标行中非空的 修正方案批注。
• 批注修订扫描必须先枚举并阅读当前目标范围内所有非空 修正方案批注，再分类处理；不要先用 状态、确认修正方案 或“是否包含 Agent修订”把批注过滤掉。分类时至少记录：行号、标题、当前方案、批注全文、最后一条 Agent 修订留痕后的剩余文本、当前确认状态和表格状态。
• 如果 修正方案批注 已包含 Agent修订 或既有方括号修订留痕，不要简单永久跳过；先判断最新一条用户批注是否已经被最后一条 Agent 修订吸收。若最后一条有效内容是 Agent 修订留痕，且其后没有新的用户意见，默认跳过，不再重复进入批注修订队列，也不要再次派子 Agent 或重复追加留痕。若用户在既有 Agent 修订留痕下面继续追加了新批注、新说明或新的方括号留痕，则视为再次批注，必须重新进入批注修订流程并保留原批注内容。判断时应按文本顺序看最后一条非空段落/最后一个方括号标记之后的内容，而不是只用“是否包含 Agent修订”做过滤。
• 没有 Agent修订 留痕的非空批注，默认就是待处理用户批注。即使当前 确认修正方案 是 信息不足、方案待确认、已确认方案、处理中、已处理完成 或状态不是 A未开始，也必须在本轮报告中列出；是否实施、重开或只记录，由主 Agent 按状态机复核后决定。
• 如果批注提到“截图”“不是有截图吗”“看图”“图里”等截图证据，而当前本地任务包或方案没有对应截图，必须先回到截图获取流程补图；不能只看旧方案文本继续判断。
• 把批注导出成本地 review Markdown，并关联原始行、原方案和当前 确认修正方案。
• 把用户批注当成产品/工程反馈，而不是无需验证的最终结论。必要时重新查代码、配置、Prefab YAML、资源、截图或外部项目资料。
• 批注需要深入调查时，再次使用子 Agent。任务包只给 row、当前方案、用户批注、截图、项目目录和只读约束。
• 如果不逐条粘贴批注，而是让子 Agent 读 review 文档，必须告诉它 review 文档路径和准确负责的 row/section。
• 先更新本地方案文档，再重新生成回填 payload。不要覆盖 修正方案批注，除非用户明确要求清理。
• 重新分类 确认修正方案：修订后方案具体则写 方案待确认；批注暴露出仍缺少关键信息则写 信息不足。

跑这一轮前阅读 references/user-comment-revision-workflow.md。拉取批注使用 scripts/sync_solution_comments.mjs。

6. 实施已确认方案

确认修正方案 在实施阶段按状态机使用：

• 方案待确认：已有可执行方案，等用户审核确认；不实施。
• 信息不足：方案还不够；不实施。
• 已确认方案：用户已确认，可以进入实施队列。
• 处理中：主 Agent 已经领取并分配给自己或子 Agent 处理；不要重复领取。它只能用于仍有可执行方案、正在实施/验证/收尾的行。
• 已处理完成：主 Agent Review Check 通过并已回填完成；写入该值时必须同步把表格 状态 改成 C待验收，表示等待人工验收；后续不再作为 Agent 待实施项关注。
• 关闭：用户关闭或不再处理；后续不再关注。

每轮优先级：如果在线表中已经存在 处理中 行，先处理这些已领取任务。处理中 不是跳过项，而是“需要主 Agent 继续收尾”的最高优先级状态；收尾第一步是复核它是否仍满足可实施条件。只有没有 处理中 时，才去领取新的 已确认方案，再之后才考虑批注修订或空方案分析。

只有 确认修正方案 精确等于 已确认方案 的行可以作为新任务领取并进入实施。处理中 不再作为新任务领取，但必须进入收尾复核：可执行且未完成就继续实施/验证，已完成就回填完成，复核后不可执行就退回 信息不足。方案待确认、信息不足、已处理完成、关闭 不实施。

• 编辑代码前重新读取表头，并导出已确认行。
• 主 Agent 分配具体实施任务前，必须先把这些目标行的 确认修正方案 从 已确认方案 改成在线表下拉项 处理中，并读回确认；如果写入失败，不要启动子 Agent，避免重复领取。
• 每个已确认行的实施任务要绑定当前线上 描述、修正方案、用户 修正方案批注、截图和本地方案文档小节。
• 多个独立行可以开多个子 Agent。每个子 Agent 只拿自己的窄任务包，不能自己挑无关行。
• 如果实施任务包引用“已确认方案导出文档”，必须给文档路径和准确负责的 row/section。
• 子 Agent 只能改本行需要的文件，并报告改动文件、原因、验证和未解决风险。
• 主 Agent 必须 review 所有 diff、解决冲突、跑项目合适的验证，再决定是否可交付或需要再开聚焦调查。
• 修复验证后更新本地记录，并把通过 Review Check 的行从 处理中 改成 已处理完成，同时把表格 状态 从 A未开始 改成 C待验收；两列都必须读回校验。没有通过实现/验证但方案仍明确、正在继续处理的行，可以保留 处理中 并写清阻塞。复核发现当前方案不具体、方案与标题/批注不匹配、缺少关键截图/视频/配置 ID、或需要用户决策才能判断改动点时，必须把 修正方案 修订为 【信息不足】，追加 Agent 修订留痕，把 确认修正方案 改为 信息不足 后读回；不要继续保留 处理中。

派实施子 Agent 前阅读 references/confirmed-implementation-workflow.md。生成已确认实施清单使用 scripts/export_confirmed_fixes.mjs。

脚本

• scripts/export_tencent_bug_rows.mjs：把腾讯文档任务行导出为 Markdown，并下载单元格文本里直接可见的截图 URL；下载 docimg 时带腾讯文档 Referer，遇到 imageMogr2/thumbnail 先规范化为非缩略图 URL，Markdown 写成本地图片引用；嵌入图片需要换 opendoc/Chrome 等通道提取，不要把“当前脚本未下载到”写成“图片不可下载”。
• scripts/normalize_dates.mjs：把日期值或 JSON 里的日期字段规范化为 YYYY-MM-DD。支持 Excel 日期序列号、YYYY-M-D、YYYY/M/D、YYYY.M.D、YYYY年M月D日；不会猜测 6/2、明天、周二 等缺少明确年月日的值。导出和回填脚本需要日期时应复用 scripts/lib/dates.mjs，不要各自手写日期正则。
• scripts/validate_task_markdown.mjs：交付前校验主 Markdown，阻止 Unmapped/Full-Size Screenshot Gallery、all_screenshots 旁路说明、docimg 外链和 thumbnail 缩略图进入最终任务包。
• scripts/sync_solution_comments.mjs：把非空 修正方案批注 导出为本地 review Markdown。
• scripts/export_confirmed_fixes.mjs：导出 确认修正方案 精确等于 已确认方案 的行。
• scripts/build_solution_backfill_payload.mjs：根据本地方案生成 sheet.set_range_value payload。
• scripts/verify_tencent_backfill.mjs：读回线上单元格并报告不匹配项。

安全

• 用户没有明确要求实施时，不要修改目标代码库。
• 不要打印 token、Cookie、DOC_SID、TOK、uid_key 或其他登录材料。
• 不要清空或覆盖目标行/目标字段之外的腾讯文档单元格。
• 腾讯文档写入可能出现追加行为。需要精确替换时，先清目标单元格，再写入并读回。
• 保留原始截图和本地任务清单，除非用户要求重新生成。
• 正常修订流程中不要删除或覆盖 修正方案批注，除非用户明确要求。
• 不能因为某行有具体 修正方案 就实施；实施需要 确认修正方案 == 已确认方案 或用户直接指令。