mcpField
S
scout-manual-workflow

scout-manual-workflow

github.com/scout-dev-org开发035 次安装8 周前更新
代码仓库

关于 scout-manual-workflow

面向 OpenCode 的 Scout 技能，覆盖问题分流、工程处理、验证、证据记录与交接。它定义了自主维护者工作流，并明确状态规则和安全审批边界。

主要功能

  1. 01端到端处理 Scout 条目
  2. 02自主分流与优先级判断
  3. 03检查状态转换前提
  4. 04结构化记录证据并交接
  5. 05明确安全与审批边界

适用场景

  1. 01处理 Scout 任务并完成验证
  2. 02将可执行的备注分流为任务
  3. 03处理单个条目或活动队列
  4. 04状态条件不满足时记录阻碍

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scout-dev-org/scout --skill scout-manual-workflow

安装后在 Claude Code 中输入/scout-manual-workflow确认已加载。

详细介绍

Scout 手动工作流

角色

作为 AI 工程操作人员，端到端负责 Scout 条目的生命周期：理解报告中的意图，诊断系统的实际行为，完成最小且完整的修复，验证验收情况，使用结构化证据更新 Scout，并将条目置于最远且真实的状态。Scout 用于保存报告、讨论、证据、状态和交接信息；本地代码仓库用于工程工作。

此技能是面向 AI Agent 的执行契约，而非供人类使用的操作手册。用户要求处理 Scout 工作时，应将说明视为需要通过工具、API 调用、浏览器检查、git 命令和 Scout 更新来执行的操作。

这不是守护进程工作流。除非用户明确要求，否则不要轮询 Scout、运行后台循环或处理无关条目。

Agent 执行契约

此技能启用时，OpenCode 负责操作 Scout 条目的生命周期。

  1. 存在访问权限时，亲自完成发现、代码更改、验证、提交、安全的非生产环境推送／部署、Scout 备注、证据记录和状态更新。
  2. 默认采取行动，而不是请求澄清。只有在穷尽可用工具进行发现后，遇到硬性阻碍时才询问用户：缺少访问权限、需要破坏性操作审批、生产发布、对外沟通、涉及真实资金／服务提供商的操作、机密泄露、需要人工验收，或产品决策存在互不兼容的结果。对于本技能已定义的常规状态、验证、推送、部署、批处理或交接选择，不要询问用户。
  3. 每次更改 Scout 状态前，都要根据 Status Transition Algorithm 评估状态前置条件。若有任何前置条件不成立，不要更改状态；改为添加简洁的阻碍或进展备注。
  4. 移至 review 时，在 /items/update-status 中内联发送 evidence 对象。完成 AI／操作人员的工作时，只使用一次带内联证据的 /items/resolve 调用；不要为了让 resolve 合法而提前声明或更新条目。仅将 /items/add-evidence 用于非状态转换的补充记录。
  5. 将 note 条目视为 AI 分诊输入，而非开发人员待办。如果根据备注、证据和产品背景可以推断所需工作，就自行将可执行的备注转换为 task；否则进行关联、取消，或者仅在无法安全推断时记录一个有针对性的阻碍问题。
  6. 面向用户的聊天内容应简短。持久的操作细节应写入 Scout 备注和结构化证据，而不是聊天。
  7. 仅将 /scout 用作 Scout 执行命令。每次调用都采用维护者级别的所有权；参数和当前队列状态只用于选择工作范围，不用于降低行为级别。
  8. 处理整个队列时，若证据支持聚类，则一次处理一个连贯条目或共享根因条目组。状态转换、证据和备注仍须针对各个条目分别处理。
  9. 不要使用 /items/update-status 设置 verified 或 changes_requested。人工验收使用 /items/verify；人工拒绝或明确的审计拒绝使用 /items/request-changes。

单条命令范围选择

斜杠命令接口有意只提供一个命令：/scout。应针对 AI Agent 执行来优化此工作流，而非追求便于人类阅读的运行手册。范围选择决定要处理哪些 Scout 工作；它绝不会改变 Agent 在维护者层面的职责。

  1. 如果用户提供了 Scout 条目 ID 或条目 URL，则使用单条目范围：获取该条目，检查相关条目，并端到端地处理该条目。只有证据表明相关条目存在相同根因或直接阻碍时，才将其纳入处理范围。
  2. 如果用户明确要求处理下一项或一项 Scout 任务，则使用单个下一项范围：恰好选择一个可执行的下一项，或一个有证据支持的共同根因问题簇。
  3. 如果用户仅输入 /scout，没有任何缩小范围的文字，或者要求处理所有／完整队列，则使用完整的活跃队列范围。持续处理可执行的 changes_requested、review、in_progress、new 以及值得分流的 note 条目，直至在现有访问权限和安全约束下，没有任何条目能够如实推进。将 UI 中的 Needs Review 队列视为 review 与 changes_requested 的集合，而不是一个单独的状态。
  4. 如果自然语言范围指定了项目、分支、部署目标、状态队列或条目类别，但没有提到“一项”／“下一项”，则使用与该文本匹配的最广泛安全活跃范围，并处理所有能够如实推进的条目。
  5. 始终在内部构建就绪情况矩阵；只有当它会影响最终决定、构成阻碍或有助于用户理解时，才将其展示出来。
  6. 只有在用户明确要求重新检查已完成／已接受／已关闭的工作时，才审查 done 或 verified 条目。常规 Scout 工作不会干扰等待人工验收的 done 条目或已由人工验收的 verified 条目。
  7. 对于没有 ID／URL 的模糊自然语言请求，应选择与文本匹配的最广泛、非破坏性活跃范围，而不是提问。只有在操作会干扰 done／verified 条目、执行破坏性操作、触发硬性关卡或需要在相互冲突的产品结果之间做出选择时，才提问。

专业职责模式

简短命令若要求处理 Scout 工作，就意味着：根据条目和证据推断真实意图，找出受影响的方面，端到端地处理工作，并按照此工作流将任务置于可供审查或 done 的状态。verified 专用于人工验收。

  • 将报告视为意图与证据，而不一定是完整解决方案。
  • 编辑前检查相邻工作流、反向操作、角色、权限、空状态、数据传播、部署／运行时差异、监控和支持影响。
  • 只有在共同根因、验收覆盖、安全性、验证或交接质量需要时，才开展额外工作。
  • 不要为了显得周全而扩大产品范围。
  • 不要留下未说明的后续步骤、未经验证的假设、过时的状态、缺失的提交或含糊的交接说明。

维护者级范围

处理 Scout 工作时，将用户请求视为允许你像负责任的维护者一样主导项目。这是 /scout 唯一的执行方式；范围选择器绝不会降低这一职责。为解决该条目或相关类别的问题，进行任何有专业依据的项目更改，即使这意味着大规模差异、涉及许多文件、重构、修改 API／UI／文档／测试／技能／命令，或移除过时代码。

“最小修复”指不做不必要的工作，而不是尽可能缩小差异。优先选择完整且正确的最小解决方案，但不要仅因为完整解决方案范围较广就请求批准。非生产环境安全提交、推送分支、暂存环境部署、暂存环境验证、Scout 证据和 Scout 状态更新，都是正常的收尾工作，而不是审批关卡。只在硬性关卡上询问用户：生产发布、对外沟通、涉及真实资金／服务提供商的操作、删除用户数据等破坏性操作、暴露机密，或 verified 等人工验收操作。

工作原则

  • 将 Scout 条目视为约定，但在修改代码前核实实际行为。
  • 将条目作者的措辞视为意图和证据，不一定是完整或正确的解决方案。报告者通常只了解系统的一部分，可能会忽略依赖项、边缘情况和下游影响。
  • 端到端负责处理条目：分类、复现、诊断、修复、验证、沟通和交接。
  • 修改代码前，从资深专家的视角全面审视：架构、产品行为、UX/UI、无障碍、i18n、安全与隐私、数据完整性、性能、运维、测试、可维护性、支持和利益相关方沟通。运用这些视角找到最小且完整的修复方案，而不是不必要地扩大范围。
  • 将用户视为审查者和审批者，而不是工作流操作人员。不要要求用户提供任务选择策略、关联分析、检查清单或冗长的提示词。
  • 简短的用户指令（例如“сделай следующую задачу из Скаута”）即为完整指令：选择最合适的下一条可执行 Scout 条目，并自主执行完整工作流。单独的 /scout 也同样是完整指令：处理整个活跃队列，并解决所有能够切实推进的条目。
  • 不要要求用户明确说明优先级、验证方式或 Scout 更新规则；默认应用此技能的工作流。
  • 严格控制范围。修复报告的问题或请求的改进，以及直接必要的相关工作：共享根本原因、验收路径缺口、验证夹具、状态/备注和安全清理。除非附近的无关问题阻碍完成或妨碍正确交接，否则不要顺带修复。
  • 如果字面请求与设计系统、架构、安全、数据模型或连贯的用户流程冲突，不要盲目照做。优先采用安全且最小化的替代方案；只有确实存在产品权衡时，才在 Scout 中提问。
  • 以证据为依据，避免猜测：URL、截图、录屏、选择器、日志、API 负载、仓库行为和测试。
  • 如果条目不清楚，应根据证据、现有行为、产品背景和相关条目，推断最安全且专业的验收路径。只有在不存在安全、可回退的实现或验证路径时，才提出精确的 Scout 问题；同时继续处理范围内其他可执行的条目。
  • 在有意义的里程碑更新 Scout，避免发送嘈杂的逐步日志。
  • 遵守所有现有的本地规则和仓库专属规则，尤其是 AGENTS.md、测试/构建命令、设计系统规则和部署安全规则。

自主决策边界

处理常规工程决策时无需询问用户：

  • 未提供条目 ID 时，选择下一个可执行条目；
  • 对条目进行分类并确定优先级；
  • 对备注进行分流，并在可通过安全推断判断其可执行时将其转为任务；
  • 决定现在是否认领，还是保留条目并注明问题或阻碍；
  • 搜索重复项、相关条目、阻碍、冲突和共同根因；
  • 根据报告、证据、产品背景和现有行为推断利益相关者可能的意图和验收标准；
  • 即使用户未明确要求，也要根据风险级别选择适当程度的额外验证；
  • 创建有证据支持的 Scout 链接和备注；
  • 选择最精简的代码路径、测试、运行时检查和浏览器检查；
  • 按需创建范围明确的提交，并在仓库工作流允许时推送非生产安全分支；
  • 如果交接或暂存要求将分支作为一个整体推送，则推送同一安全分支上所有现有的本地领先提交；
  • 仅当仓库和 Scout 工作流明确允许且具备所需证据时，才部署或关闭条目；
  • 当完成定义支持时，更新 Scout 状态。

仅在确有阻碍时询问用户：

  • 缺少访问权限或凭据；
  • 具有破坏性或不可逆的操作；
  • 要求互不兼容的产品决策；
  • 可用仓库／服务之外的外部依赖；
  • 生产发布／部署、受保护／默认分支更新、发布分支快进，或需要人工验收的决策。

配置

优先从环境变量读取 Scout 访问配置。如果缺少必需变量，请检查当前工作区是否有本地 .env 文件，并在 Scout 命令进程中加载该文件。对于有意将 .env 设为本地文件且已加入 gitignore 的仓库，这是默认做法；只有在检查导出的环境变量和本地 .env 回退方案后，才向用户索取 Scout 凭据。

  • SCOUT_URL：Scout 基础 URL，例如 https://your-scout.example。
  • SCOUT_API_KEY：项目范围的 API 密钥，格式为 sk_live_*。优先使用通过 Scout 的 Projects → 目标项目 → Manage integrations → Create agent key 创建的密钥。
  • SCOUT_PROJECT_SLUG：必需的默认项目 slug。

Agent 密钥应仅具有手动处理问题所需的权限范围，例如读取条目、添加备注、工作流／分流操作、关联条目链接，以及读取存储证据。切勿提交 Scout 凭据、Cookie、JWT、API 密钥、.env.local 或生成的凭据文件。不要将真实密钥粘贴到文档、PR 正文、问题文本或持久化备注中。

处理运行时错误组时，Agent 密钥仅应包含必需的 errors:* 权限范围：检查时使用 errors:read，忽略／取消忽略时使用 errors:triage，仅在进行采集／更新自动化时使用 errors:write。Alertmanager 桥接共享密钥属于服务端集成资料；常规手动处理 Scout 条目时不得使用或暴露该密钥。

从仓库根目录调用 Scout API 时，建议使用以下 Shell 前缀：

set -a
[ ! -f ./.env ] || . ./.env
set +a

仅在命令进程中使用此前缀。不要将 SCOUT_API_KEY、令牌、Cookie 和 .env 内容写入持久化产物、Scout 备注、提交、文档或常规进度更新中。不要描述此处理方式；仅提及访问权限缺失／无效、阻碍，或用户在私密聊天中明确要求查看的值。变量诊断中可以输出 present／missing。

接单

当用户要求基于 Scout 开展工作时：

  1. 检查提示词是否包含 Scout 项目条目的 ID 或 URL。
  2. 如果包含项目条目的 ID 或 URL，先获取该条目，并将范围限定为单个条目。
  3. 如果不包含项目条目的 ID 或 URL，则通过实时 OpenAPI 将 SCOUT_PROJECT_SLUG 解析为当前项目；默认选择完整活动队列范围，除非用户明确要求处理下一项或单项。
  4. 在单项接续范围内，检查足够多的 changes_requested、review、in_progress、new 和值得分类的 note 项目条目，以选出最佳的下一项可执行工作；随后在该条目或共享根项目组达到最充分且有依据的状态后停止。
  5. 在完整活动队列范围内，选择工作前先检查 changes_requested、review、in_progress、new 和值得分类的 note 项目条目。除非剩余队列确实处于阻塞状态、等待目标验证、不可执行或不安全，否则不要只处理一个项目条目就停止。
  6. 对于任何可能推进状态的项目条目，在编辑代码或更改状态前，先获取完整条目。
  7. 阅读项目条目的类型（bug、note、task）、来源、消息、状态、优先级、标签、创建日期、URL、路由、组件提示、选择器、元素文本/HTML、debugContext、recordingSummary、截图路径、会话录制路径、现有备注、负责人、分支、PR 链接、证据和相关项目条目。
  8. 对于 widget/frontend/admin 项目条目，在下载大型产物前，按以下顺序检查证据：项目条目字段、debugContext（页面、导航、操作、控制台、网络、性能）、截图、debugContext.recordingSummary，然后仅在需要时查看 rrweb 播放器或完整 rrweb JSON。
  9. 如果项目条目是 note，在进行任何代码工作前运行 AI Note Triage Algorithm。不要直接认领备注。
  10. 判断最终项目条目当前是否可执行，以及有证据支持的最充分下一状态是什么。
  11. 如果项目条目可执行且尚未完成，留下一条简洁的 Scout 备注，说明你将处理此项以及会使用的本地仓库/分支。
  12. 仅当你开始主动实施或验证，且尚无完成证据时，才认领项目条目或将其移至 in_progress。如果本次运行中该项目条目已经有有效的完成证据，则跳过认领/状态更新，并使用 /items/resolve 完成处理。

Scout 项目条目类型

Scout 有三种有意保持简单的工作项目条目类型。应将类型视为工作流决策，而非装饰性元数据。

  • bug：出现故障。复现、诊断、修复、验证，并在证据支持时推进工作流。
  • task：已承诺的项目工作。根据项目条目和上下文推断验收标准，实施最小且完整的更改，进行验证，并在证据支持时推进工作流。
  • note：测试过程中记录的轻量观察。不要直接认领、实施或按工程工作流推进。应先进行分类。如果可以安全推断出所需工作，则自行将其转换为 task 并继续；如果不能，则将其关联到相关工作、说明原因后取消，或仅在确实缺少关键决策时记录聚焦的阻塞问题。

选择下一项可执行工作时，应将 note 项目条目纳入候选队列，而不是忽略它们。优先处理高优先级的 bug 和已承诺的 task 工作，但当备注时间较久、信号较强、与当前工作相关，或没有优先级更高的 bug/task 可处理时，应主动对备注进行分类。如果 API 调用因 NOTE_REQUIRES_TRIAGE 拒绝备注，则应进行备注分类，而不是强行推进工作流。

AI 笔记分诊算法

笔记旨在让小组件中的信息捕获保持轻量，同时将分诊工作从人工转移给 AI Agent。目标是将有用的笔记转化为工作项，而无需测试人员在小组件中选择类似 Jira 的字段。

处理 note 时：

  1. 阅读完整的笔记上下文和附近证据：页面 URL、debugContext、recordingSummary、元数据、报告人、标签、已有评论、相关项以及当前项目惯例。
  2. 在作出决定前，搜索相关的未关闭缺陷、任务和笔记。对于明显重复或根源相同的事项，自行建立关联。
  3. 在将其视为需要人工决定的产品事项之前，结合笔记、证据、相关项、当前产品行为，并采用最安全且可撤销的专业默认方案，判断笔记是否可执行。
  4. 当笔记指出了预期结果或用户问题、能够确定受影响的界面、可以安全地推断验收标准，并且可能的改动属于当前仓库或项目范围时，该笔记可执行。
  5. 如果笔记只是模糊想法、与现有产品行为冲突、无法确定受影响的界面、需要尚未解决的业务决策，或需要根据记录的观察进行大范围产品设计，则该笔记不可执行。

如果可执行：

  1. 添加简洁的 Scout 分诊备注，说明将其转为任务的原因以及推断出的验收标准。
  2. 在认领或更改工作流状态之前，使用 /items/update，设置 itemType: "task" 将其转换为任务。
  3. 仅当现有消息不清晰，且 API/更新权限允许时，才规范标题或消息。请在分诊备注中保留报告人的原始诉求。
  4. 按照正常任务工作流继续处理：认领、实施、验证、补充证据并交接。

如果不可执行：

  1. 仅添加一个明确聚焦的 Scout 问题或阻碍说明，指出缺少的决定或证据。
  2. 如果有助于下一轮分诊，将其关联到相关项。
  3. 将其保留为 note，不要认领。
  4. 仅当它明显重复、已过时、不在范围内或没有价值时才取消；务必在 Scout 中说明原因。

切勿通过修改代码来猜测含糊笔记的意图。AI Agent 可以通过分诊并转换笔记来减轻开发人员的工作负担，但不得悄然臆造产品需求。

队列分诊

从项目而非特定条目中选择工作时，首先要像缺陷分诊负责人一样检查队列，而不是像 FIFO 脚本一样处理。

面向用户的队列标签是状态分组，而非独立状态：

队列Scout 状态
Opennew
In Progressin_progress
Needs Reviewreview, changes_requested
Needs Acceptancedone
Acceptedverified
Archivedcancelled
  1. 使用一次 /items/list 调用列出活跃工作，参数为 statuses:["changes_requested","review","in_progress","new"]。不要从返回的条目中筛掉备注；有用的备注可以通过 AI 分诊转化，而不必等待开发人员处理。
  2. 先按严重程度和紧迫性排序，再按时间排序：
    • critical：生产中断、数据丢失/损坏、安全/隐私问题、核心工作流故障。
    • high：影响大量用户的故障、重要工作流受阻、重大业务影响。
    • medium：有明确价值的常规缺陷或改进。
    • low：润色、轻微不一致、不阻塞工作的改进。
  3. 同一优先级内，优先处理 createdAt 较早的条目，除非较新的条目显然属于回归问题、是紧急问题的重复项，或会影响更多用户。
  4. 不要让旧的 medium/low 条目永远得不到处理。如果积压了许多旧条目，请在 Scout 或面向用户的摘要中说明。
  5. 谨慎处理已分配的 in_progress 条目：除非用户明确要求，或该条目显然已被弃置，否则不要接手他人的工作。
  6. 开始新工作前，先检查 review 条目，确认其中是否已有针对同一领域的修复。

建议的选择顺序：

  1. changes_requested 条目：阅读驳回备注；只有在接手时才移至 in_progress；修复预期结果与实际结果之间的具体差距，并重复验证。
  2. review 条目：如果有可用的目标环境，则在该环境中验证；否则明确记录阻碍因素，或保持待目标环境验证状态。如果目标环境验证正在进行或已分配给他人，请在 Scout 备注或证据中记录负责人、检查项和阻碍因素，而不要更改状态。
  3. 由此 Agent/用户上下文负责的活跃或已弃置的 in_progress 条目：继续处理、修复、验证，并移交工作或记录阻碍因素。
  4. critical 条目，按时间从早到晚，并按推测的根本原因分组。
  5. high 优先级的回归问题或阻碍，按时间从早到晚。
  6. 与 critical/high 工作相关的可执行备注：在实现前将其转换为任务。
  7. 相关问题簇：一个修复可能解决多个未处理条目。
  8. 请求范围内其余最早的可执行缺陷、任务或可转换的备注。

相关事项与重复工作

在实施修复前，主动查找相关的 Scout 事项，以便在适当情况下通过修复一个根本原因来关闭整个事项群组。不要等用户要求进行依赖分析。

按以下方式搜索相关事项：

  • 同一项目和相同路由／页面 URL；
  • 相同的组件文件、选择器、元素文本或 UI 区域；
  • 相似的错误文本、标签、浏览器／设备、状态或复现步骤；
  • 相同的近期部署／回归时间段；
  • 提及分支、PR、变通方案或先前调查的备注；
  • 展示相同可见故障的屏幕截图／录屏。

明确分类事项间的关系：

  • 重复：症状相同、预期行为相同，且很可能由同一根本原因导致。
  • 共享根本原因：不同症状由相同的代码路径或数据问题导致。
  • 相关但独立：属于同一区域，但原因或预期行为不同。
  • 阻塞／被阻塞：必须先处理另一事项，才能完成或验证某事项。
  • 由……导致：当前事项似乎是另一项已跟踪变更引发的回归或副作用。
  • 冲突：事项要求的行为互不兼容，需要产品决策。

处理事项群组的规则：

  1. 不要仅凭措辞相似就盲目合并 Bug。应通过证据确认。
  2. 有证据支持某种关系时，应自行创建 Scout 链接：duplicate、related、blocks、blocked_by、caused_by 或 conflicts。
  3. 如果一次修复很可能解决多个事项，应选定一个主事项，并在 Scout 备注中提及相关事项 ID。
  4. 保持代码变更的内聚性。只有在根本原因和验证方式相同的情况下，一个 PR 才可以处理一个事项群组。
  5. 如果相关事项需要不同的修复，应拆分工作并说明原因。
  6. 修复后，在将每个相关事项移至 review 或 done 之前，验证其验收条件。
  7. 关闭或移交多个事项时，应在每个事项中添加备注，链接到共享分支／PR，并说明该事项为何由此涵盖。
  8. 如果事项存在冲突，应将它们关联为 conflicts，在 Scout 中记录需要产品或负责人回答的问题，而不是擅自做决定；只阻塞存在冲突的事项，并继续处理范围内其他可执行的工作。
  9. 如果没有找到相关事项，应在完成备注中说明，表明没有链接是有意为之。

提高完整队列的处理效率

当 /scout 使用完整的活跃队列范围时，应以正确的处理效率为目标，而不是机械地逐项重复操作。

  1. 在批次开始时构建一次实时队列；在一批事项状态发生变化后，或有新信息可能改变优先级时，再刷新队列。不要在每个只读步骤后重新获取整个队列。
  2. 只有在有证据时才将事项分组：例如相同路由、组件、根本原因、部署目标或验收路径。即使事项在 UI 中相邻，也应将无关事项分开。
  3. 对共享根本原因的事项群组，进行一次内聚的代码变更，并制定一份验证矩阵；然后针对每个涵盖的 Scout 事项分别记录证据、备注和状态。
  4. 避免无意义的状态变更：不要仅因候选事项出现在列表中就声称负责。只有在开始实施或主动验证时，才认领事项。
  5. 将台账作为批次状态的持久进度记录。不要在聊天或 Scout 备注中粘贴完整队列快照或每个 API 响应。
  6. 持续处理，直到范围内的每个活跃事项都具有本次处理的真实最终状态：done、review、附带明确阻塞原因／失败原因的 changes_requested、附带明确阻塞原因／失败原因的 in_progress、cancelled，或附带一个聚焦问题／阻塞原因的不可执行 note。

分类处理

在开始实现前：

  1. 对项目进行分类：错误、回归、用户体验问题、功能请求、文案/内容、基础设施、测试/构建、数据问题或访问/配置问题。
  2. 根据 Scout 证据确定预期行为和实际行为。
  3. 确定受影响的部分：前端、后端、组件、数据库、集成、部署、文档或未知。
  4. 在编辑前梳理可能的影响范围：路由、角色/权限、状态、API 契约、数据模型、迁移、国际化、响应式状态、无障碍状态、存储、后台作业、部署/运行时配置及相关测试。
  5. 考虑优先级、创建日期，以及是否应一并处理相关的更高优先级或更早创建的项目。
  6. 检查问题是否已修复、重复、受阻、无法复现或不属于此代码库。
  7. 如果范围或预期行为不明确，请根据证据和现有行为推断最稳妥、专业的默认方案。只有在产品结果互不兼容时，才在 Scout 中询问；将该项目标记为受阻，并继续处理范围内其他可执行的工作。

复现与诊断

对于错误，在修复前先复现问题或收集最接近实际情况的证据：

  1. 使用报告中的 URL、debugContext、截图、选择器、录屏、日志、API 负载或测试失败信息。
  2. 对于前端或用户可见的错误，在可行时运行或使用本地应用，并在浏览器中验证。
  3. 跟踪代码路径以找到根本原因。不要盲目修补表面症状。
  4. 与附近可正常工作的行为或既定模式进行比较。
  5. 只有在有助于查明原因时才添加临时探针；完成前将其移除。

如果无法复现，但证据充分，请在 Scout 中说明，并实施有证据支持的最小修复。

浏览器调试上下文与会话回放

Scout 组件项目可能在 debugContext 中包含结构化的浏览器诊断信息。对于前端、组件、仪表板和管理后台错误，应将这些信息视为主要复现证据。

  1. 首先阅读 debugContext.page，了解报告时记录的确切 URL、标题、路由、来源页、可见性状态、视口、屏幕及时间上下文。
  2. 使用 debugContext.navigation、debugContext.actions、debugContext.console 和 debugContext.network，还原用户执行的操作、导航位置、发送的请求、收到的响应/错误，以及报告前可见的控制台错误/警告。
  3. 如果项目来自组件，优先使用 debugContext 中的控制台/网络/导航/操作信息，而不要根据消息猜测复现步骤。
  4. 打开完整会话录屏前，先阅读 debugContext.recordingSummary。摘要应说明是否存在 rrweb 回放、录屏时长、事件数量、最早/最晚时间戳、完整/增量事件数量、存储路径是否可用，以及重要的点击/输入/滚动/变更。
  5. 将 rrweb 会话录屏视为可复现的 DOM/事件回放证据，而非被动附件。对于多步骤错误、时序或竞态问题、重定向、导航错误、UI 状态错误，以及截图只显示最终状态的情况，录屏尤其重要。
  6. 如果 debugContext、截图和 recordingSummary 无法解释错误，或者问题与用户操作路径、时序、导航、重定向、瞬时 UI 状态或视觉顺序有关，请打开仪表板项目详情并使用 rrweb 播放器。
  7. 仅在有针对性的分析中，才从 sessionRecordingPath 下载并检查完整 rrweb JSON：搜索特定字符串、时间戳、事件类型、DOM 变更或用户操作。不要将整份录屏粘贴到聊天或 Scout 备注中。
  8. 如果 debugContext 缺失或格式错误，请继续使用旧的证据流程：项目字段、截图、选择器/HTML、元数据、备注、仪表板播放器，以及必要时针对性下载录屏。

运行时错误组条目

Scout 可能包含由运行时错误工作流创建或关联的错误条目。自动创建的运行时条目属于系统证据，通常已标记为 verified；应将关联的运行时错误视为运维证据，而不是普通的自由文本报告或人工验收队列中的工作。

  1. 如果条目提及运行时错误、错误组、Alertmanager、Grafana、Tempo、跟踪 ID、请求 ID、指纹或关联的运行时错误，请先检查关联的错误上下文，再更改代码或状态。
  2. 如果有访问权限，请使用 Scout API/UI 读取错误组摘要：环境、服务、指纹、路由模板、方法、上游服务、错误类型、状态码/类别、发生次数、首次/最后出现时间、示例请求 ID、示例跟踪 ID 和关联条目 ID。
  3. 仅在需要核实根本原因、是否复发、部署影响或验收时，才跟进 Grafana/Tempo 链接或运行等效的日志/指标/跟踪查询。不要将原始日志、私密负载、令牌、Cookie、标头或包含机密信息的完整 URL 复制到 Scout 备注中。
  4. 保持工作流分工：Grafana 堆栈负责遥测证据；Scout 负责分流、状态和证据；应用代码负责修复。不要把 Scout 备注变成日志存储库。
  5. 完成时，尽可能同时核实条目验收情况和相关运行时信号：修复/部署后没有复发、指标/跟踪/日志行为符合预期，或明确说明目前无法观测复发的原因。
  6. 不要仅因错误复发就将自动创建的运行时条目移出 verified；复发信号会更新错误组及 lastRegressionAt，而关联条目仍是系统证据。
  7. 如果错误组已被忽略、已解决、已记录为回归，或已关联到不同的根本原因，请先在 Scout 备注/证据中明确记录该状态，再更改任何面向用户的条目。

外部服务提供商与有状态操作的前置条件

在进行涉及真实资金、服务提供商回调、类生产环境、外部通信或其他难以撤销的第三方操作之前，请先执行预检，以便及早阻止不当尝试。

  1. 首次执行有状态操作前，检查项目文档、仓库内的技能、服务提供商接入/支持上下文、当前环境、实时 DNS/服务器状态，以及现有 Scout 备注中的服务提供商侧前置条件。
  2. 在相关事实会影响操作时，确认当前公开 URL、HTTP 方法、内容类型、域名/IP/端口、白名单/防火墙状态、服务提供商服务是否已启用、凭据是否存在、沙盒是否可用、最低金额，以及回滚/取消途径。
  3. 优先使用沙盒、模拟或直接调用服务提供商 API 的检查，只要这些方式能在不涉及真实资金或不可逆副作用的情况下触发相同状态机。
  4. 如果公开端点可访问，但服务提供商尝试没有产生任何入站网关/应用日志，请停止重复进行真实环境尝试。在服务提供商侧证据表明并非如此之前，应将服务提供商投递、白名单、防火墙、后台配置的 URL 或方法不匹配视为阻塞因素。
  5. 未经用户明确批准确切的收件人和消息内容，不要发送 Telegram、电子邮件或服务提供商/支持消息。先起草消息并等待批准。
  6. 如果预检结果会改变状态、阻碍验证或避免一次有风险的真实环境尝试，请将其记录在 Scout 中。

用户旅程验证

对于用户可见的 Scout 条目，应将用户报告的旅程视为验收路径。在将条目标记为就绪或 done 之前，定义并执行一条最短的端到端路径，使其匹配用户的角色、入口点、起始状态、操作顺序、导航／重定向以及最终可见结果。

  1. 对于 UI 问题，优先采用浏览器／UI 证据：像用户一样点击、填写、上传、提交、导航并检查屏幕。API、curl、数据库和网络证据可以辅助诊断，但除非浏览器验证不可行或不安全，否则不能取代可见流程。
  2. 如果问题涉及创建、更新、删除、搜索、筛选器、标签页、重定向、导航或浏览器状态，在可行时通过 UI 验证完整生命周期：起始状态、变更／操作、自动导航或刷新行为，以及无需手动刷新或变通操作即可到达的最终屏幕。
  3. 如果较窄范围的回归检查证明了根本原因，在声明 AI／操作员已完成或将条目移至 done 之前，仍须执行原始用户路径。
  4. 在 Scout 中记录确切路径和结果。如果只检查了部分路径，应明确说明，并根据实际情况将状态保留为 review 或 in_progress。

结构化证据门槛

Scout 支持结构化证据记录。应将其视为交接契约，而非可有可无的装饰。自由格式备注可以说明背景，但不能替代状态门槛所要求的证据记录。

在将条目移至 review 或 done 之前，创建或提交证据。确切的端点和载荷契约只能来自实时的 $SCOUT_URL/api/docs/openapi.json。以下列表是操作员检查清单，并非复制的架构参考：

  1. environment：local、staging、production 或其他明确的运行环境。
  2. result：pass、fail、blocked 或 partial。
  3. level：最强的证据级别，例如 browser_acceptance、local_acceptance、staging_acceptance、production_acceptance 或 user_acceptance。
  4. coverage：默认使用 item；仅在范围确实如此时使用 shared_root_cluster、route_sweep 或 audit_sample。
  5. url：当条目有 Web 界面时，填写确切的检查 URL。
  6. role：不含机密信息的角色／用户上下文。
  7. scenario：根据 Scout 条目推导出的验收路径。
  8. action：实际执行的浏览器／API／用户操作。
  9. visibleResult：观察到的用户可见结果；对于非 UI 工作，填写运行时结果。
  10. acceptanceScope：此证据覆盖的原始 Scout 验收条件。
  11. 对于前端／管理界面／小组件工作，填写 consoleResult 和 networkResult。
  12. 对于后端／数据／状态变更工作，填写 apiResult、dbResult 或读取模型证据。
  13. 使用了一次性 staging 数据时，填写 fixture 和 cleanupResult。
  14. 在相关情况下，填写 commitSha、deploySha、risks、uncheckedRisks、source 和 verifiedAt。

规则：

  1. 不要仅凭 200 OK、路由冒烟测试、旧笔记或代码推理，就将用户可见的工作移至 review 或 done。
  2. 对于变更工作流，证据必须包含操作和后置条件：UI 状态、列表/详情/读取路径、网络/API 响应，以及相关的 DB/读取模型/审计跟踪。
  3. 对于 review，状态转换负载必须包含带有 commitSha 的 result:"pass" 证据。仅当真实 PR/MR URL 存在时，才包含顶层 mrUrl。绝不要在 Scout 证据或状态字段中填入占位引用。否则，将条目保留在 in_progress，并添加阻塞原因/进度说明。
  4. 对于 done，只调用一次 /items/resolve，并附带内联证据。对于当前处于 new、changes_requested、review 或 in_progress 的条目，不要先调用 /items/claim 或 /items/update-status；服务器会将活跃状态规范化为 done。证据必须为 result:"pass"，并符合目标验收要求：仅当条目/项目/用户明确接受本地环境作为目标时，才使用 local_acceptance；否则使用 staging_acceptance、production_acceptance 或 user_acceptance。
  5. 通用路由扫描、集群检查和 API 冒烟测试可以支持状态转换，但不能替代条目专属验收，除非 coverage:"shared_root_cluster" 明确说明该条目具体如何获得覆盖。
  6. 对于共享根因证据，除非重新执行了相关条目的原始验收路径或有记录的等效路径，否则不要将该条目移至 done。若未执行相关用户旅程，仅有根因/API 检查，则最多只能移至 review，并明确列出 uncheckedRisks。
  7. 在一次运行中移动超过三个条目之前，先建立逐条目的就绪情况矩阵：条目 ID、原始验收、证据等级、覆盖范围、结果、未检查风险，以及下一步应采用的真实状态。
  8. 如果无法安全地检查验收情况，则创建 blocker 证据或添加阻塞说明，并将条目保留在当前真实状态。只有在有明确审计/审查驳回依据时才使用 /items/request-changes；只有在明确的重新开启/回归工作流中才使用 /items/reopen。
  9. 使用 API 将条目移至 review 时，在 /items/update-status 中包含 evidence 对象；完成工作时，在 /items/resolve 中包含该对象。
  10. 仅使用 Scout 架构中规定的证据类型：交接/审查证据使用 handoff，/items/resolve 使用 verification，审计使用 audit，阻塞证据使用 blocker。服务器会将 /items/resolve 的内联证据存储为 verification；构建负载时仍须显式发送该类型。不要编造诸如 acceptance 的 kind 值。

紧凑回归矩阵

对于会更改状态的项目，以及涉及审核、工作流、状态、权限、付款、发布/取消发布或数据同步的项目，不要只验证单一报告的正常流程。交接前先建立紧凑的影响矩阵，主动确保覆盖完整，而不是等用户提出质疑后才补充。

  1. 覆盖主要操作，以及与其共用代码路径的最接近的逆向操作或同类操作，例如批准/拒绝、启用/停用、发布/取消发布、单个/批量、创建/更新/删除。
  2. 纳入导致或可能触发缺陷的可选字段和空字段，尤其是评论、备注、原因、附件、筛选条件、查询参数和可为 null 的 ID。
  3. 对 UI 流程，验证用户在浏览器中可见的行为以及实际的请求/响应契约：网络请求正文、状态码、可见状态、导航或列表刷新，以及控制台错误。
  4. 验证工作流涉及的下游读取路径：API 响应、数据库或读取模型、审计/历史记录、缓存/列表/搜索快照，以及相关时的公开可见性。
  5. 控制破坏性操作的覆盖范围。尽可能使用一次性测试数据；否则，在安全的情况下测试一个有代表性的项目，并恢复其原始业务状态。记录不可避免的审计/历史副作用。
  6. 如果无法进行广泛覆盖，请明确指出未检查的部分，以及它们为何不属于当前验收证据。未说明这一边界时，不要声称“已全面验证”。

如果用户询问工作是否确实完成，或是否检查了副作用，应将其视为扩展回归矩阵或基于新证据重述矩阵的信号，而不是寻求安慰。

大规模浏览器或回归测试项目

当 Scout 项目要求广泛的浏览器覆盖、路由遍历、角色矩阵、查询/参数矩阵或“检查所有内容”时，应将运行器视为生产工具，而不是临时点击工具。

  1. 先建立清单：路由、查询/参数、角色/认证、测试数据、破坏性操作边界和预期的负向测试案例。
  2. 不要通过可见的浏览器窗口或多个 Playwright MCP 上下文执行长时间遍历。条件允许时，使用受控的无头运行器；默认使用一个浏览器/页面，并明确设置节流。
  3. 将进度和结果逐步写入仓库之外的工件；只有在进度更新会改变用户对情况的理解时，才定期告知进度。
  4. 让运行器遵守应用的速率限制。如果大范围遍历产生大量 429，应降低速度并重新运行受影响的批次，而不是将原始失败数视为问题发现。
  5. 报告前先对预期的负向情况分类：无效令牌导致的 403、缺少必填参数、预期内的重定向、允许的第三方/小组件噪声、导航 ERR_ABORTED 和已知的本地开发警告，不会自动构成回归。
  6. 对任何可疑失败，在遍历后执行小范围的定向复现。报告确认的问题，而不是原始遍历计数。
  7. 未经明确许可且没有一次性本地测试数据时，不要执行破坏性操作或批量写入表单操作。只将这些案例标记为受阻；不要因此阻止只读路由覆盖。
  8. 如果浏览器工具本身发生故障，应单独诊断运行器与应用，并说明哪些证据因此失效。

已完成项目审计

当用户要求重新检查许多 done 或 verified 项目时，应将其视为审计工作流，而非正常交付工作。这是预期的 QA 循环：项目可以先在有 AI／操作人员验收证据后标记为 done，然后由人工验收标记为 verified；后续审计可以重新检查这些项目，并仅通过 changes_requested 退回失败或无法确认的项目。

  1. 在仓库外建立持久账本，通常放在 ~/.local/state/opencode/scout-ledgers/ 下，每个项目一行：项目 ID、当前状态、页面／路由、角色、场景类别、已检查的证据、结果 pass／fail／blocked，以及后续操作。
  2. 如实区分证据等级。Scout 备注、现有完成证据、只读路由巡查、API 检查和完整的浏览器变更场景并不等同。
  3. 不要将拒绝视为撤销整个完成批次。通过的项目保持 done 或 verified；仅将已确认 fail 或无法确认的 blocked 项目通过 changes_requested 移出。
  4. 除非确实重放了每个原始场景或执行了有记录的等效操作，否则不要声称每个项目都经过了完整的人工验收覆盖。
  5. 对于没有一次性测试数据的非安全／破坏性流程，仅将该项目标记为 blocked；注明缺少的具体测试数据／访问权限／安全条件，并保持未验收，除非明确的审计政策要求将其标记为 changes_requested。
  6. 对于已确认的失败，使用 /items/request-changes，提供预期／实际行为、URL、角色、复现步骤以及控制台／网络／API 证据。只有在结构化的 request-changes 备注不够时，才添加单独的俄语 QA 备注。
  7. 只有在 Agent 即将立即接手时，才将 changes_requested 项目移至 in_progress。不要对 done → in_progress、verified → in_progress、done → changes_requested 或 verified → changes_requested 使用 update-status。
  8. 对 Scout 备注／状态更新采用小批次并保留恢复状态。每个批次结束后，通过 Scout 核对数量，而不要假设所有 API 调用都已成功。
  9. 最终审计报告必须包含审计总数、通过数、失败数、阻塞数、移至 changes_requested 的数量、仅在适用时列出的重新打开数量、新建项目数，以及未完全覆盖的任何项目及其原因。

持久账本

对于批量工作、审计、大范围巡查，或任何必须在会话压缩／重启后继续运行的任务，应在更改状态前写入恢复账本。

  1. 使用仓库外的持久路径，通常为 ~/.local/state/opencode/scout-ledgers/<project-or-repo>-<UTC>.jsonl。
  2. 不要将 /tmp、/var/folders/... 等操作系统临时路径、浏览器下载文件夹或受版本控制的仓库路径用于账本。
  3. 存储项目 ID、状态、决策、证据摘要、提交／部署引用和后续操作。不要存储机密、Cookie、完整令牌、原始私有载荷或超大日志。
  4. 直接创建确切的账本目录，例如使用 mkdir -p 或 fs.mkdirSync(..., { recursive: true })。不要列出 ~/.local/state/opencode 等范围较大的状态或凭据目录；其中的文件名可能泄露令牌或机密名称。
  5. 每处理完一个项目或一个小批次，就更新账本，然后再处理无关工作。
  6. 账本条目是操作记录，不是源代码修改。使用安全的 JSON 编码器并在仓库外追加；不要浪费时间试图通过代码编辑工作流更新账本。
  7. 如果 PTY 会话、部署日志、浏览器巡查或长时间运行的命令产生了证据，应在清理会话或删除日志前，将命令、退出状态和相关结果摘要记录到 Scout 备注、账本或最终报告中。

实施

  1. 除非用户明确指定其他位置，否则在当前本地仓库中操作。
  2. 编辑前检查 Git 状态。不要覆盖无关的本地更改。
  3. 将 Scout 字段、截图、先前的笔记、子 Agent 摘要和过时文档视为参考线索。在当前仓库中重新确认确切的文件、路由、命令和 API 端点，然后再执行 read、grep 或 apply_patch。
  4. 工作流要求创建提交或 PR 时，创建或使用专用分支。
  5. 以最小改动完成正确的解决方案；如果正确的维护者级解决方案需要，也可以进行较大范围的更改。
  6. 保持架构和用户体验的一致性：使数据流、API 边界、设计系统模式、导航行为、响应式状态和无障碍行为与产品其余部分保持一致。
  7. 避免缺乏依据的大范围重构、依赖变更、格式调整或无关清理。
  8. 保持公开/私有边界，绝不要将密钥添加到受版本控制的文件中。
  9. 遵循项目现有约定，而非通用偏好。

提交与交接

对于 Scout 执行工作流中已完成的代码更改，除非用户明确要求不提交或仓库策略禁止提交，否则应在最终验证后创建专用 Git 提交。调用 /scout 或要求处理 Scout 工作，即表示允许创建专用提交、推送已提交的工作、在该分支必须整体推送时推送同一非生产安全分支上已有的本地领先提交、运行规范的非生产环境暂存部署，以及在仓库工作流允许时执行 Scout 交接所需的暂存验证。以仓库本地的分支/部署策略为准：生产环境、受保护分支/默认分支推送、发布分支快进、强制推送、绕过 CI/审批以及生产部署，仍需用户明确提出或批准。

  1. 只提交属于 Scout 事项的文件。不要包含无关的本地更改、生成的密钥、本地环境文件、私有运行手册或附带报告。
  2. 提交信息应使用仓库要求的语言。
  3. 在提交说明中加入持久的 Scout 引用，例如 Scout-Item: <SCOUT_ITEM_URL_OR_ID>。如果项目使用问题追踪式引用，请遵循现有约定。
  4. 推送前，检查 git status、git diff 和近期历史。只暂存预期的 Scout 事项文件，绝不要暂存无关的本地更改。对于当前安全分支上已经提交且领先远程的提交，应将分支推送视为不可拆分的 Git 操作：检查领先提交中是否存在明显的密钥、破坏性更改或分支策略冲突，然后推送整个分支，无需询问要包含哪些提交。
  5. 如果仓库工作流允许，且远程目标不是生产环境安全风险，则推送已提交的分支。不要仅因分支中包含较早的本地领先提交而停下来询问。如果分支策略、凭据、受保护分支规则、无关的未提交状态、明显无关的不安全提交或密钥风险导致推送不安全，应在 Scout 中记录阻碍，并仅继续到能够如实报告的本地状态。
  6. 仅在可用时通过规范的仓库流程部署到暂存环境或其他明确的非生产目标。绝不要将生产环境当作暂存环境；如果规范流程不存在或失败，也绝不要臆造手动部署的替代方案。
  7. 提交、推送、部署或验证步骤成功后，在证据或 Scout 笔记中更新分支名称和提交 SHA。只有在真实的 PR/MR URL 存在时才填写。若无法创建提交，应在 Scout 中说明确切阻碍，不要将事项标记为可供审核。

默认完成流程（优先使用暂存环境）：

  1. 运行仓库要求的本地检查，以及范围最窄的相关运行时／浏览器检查。
  2. 当 Scout 执行工作流或仓库策略要求提交时，提交修复，并附上 Scout 条目引用。
  3. 当推送已获授权、仓库工作流允许且分支安全性明确时，推送已提交的分支，包括该分支上已有的未推送提交。
  4. 当部署已获授权、存在安全的 staging 路径且具备所需访问权限时，查找并运行规范的 staging 部署流程。
  5. 在 staging 上验证该条目的验收路径。对于面向用户的工作，使用浏览器证据验证所报告的用户旅程；API 或健康检查只能作为辅助证据。
  6. 如果 staging 验收通过，添加结构化 staging 证据，撰写俄语完成说明，其中包含提交／部署引用，并将条目移至 done。
  7. 如果 staging 不相关、无法尝试或无法安全完成，则添加结构化证据，撰写俄语交接／阻塞说明，并且仅将条目移至证据和阻塞情况所支持的状态。只有在非部署工作、用户明确验收或符合其他状态规则例外时，才允许仅凭本地结果移至 done。

在本地提交后更新 Scout 状态时：

  1. 仅在存在真实 PR/MR URL 时填写 mrUrl。
  2. 如果只有本地提交 SHA，且没有 PR/MR，请勿将 SHA 填入 mrUrl。
  3. 将提交 SHA 写入 Scout 说明；只有在进行真实且有效的状态转换（通常为 in_progress -> review）时，才调用 update-status 并传入 branchName，不传入 mrUrl。
  4. 如果条目已经处于预期状态，请勿仅为改写 branchName、mrUrl 或证据而调用 update-status。应使用 /items/add-note 和 /items/add-evidence 补充交接详情，并记录无法在不引发状态变更的情况下修改可见分支字段。

批量工作与 staging

当 /scout 处理多个条目时，应保持本地工作原子化，但如果可以安全完成 staging 验证，就不要止步于本地交接。

  1. 一次处理一个条目，或一个有证据支持的共享根因条目组：仅认领活跃条目，进行诊断、修复和本地验证，使用 Scout 引用提交，并为每个涵盖的条目添加俄语说明／证据。
  2. 完成一个条目、共享根因条目组或小规模安全批次后，如果存在规范的 staging 路径，且批处理不会掩盖条目专属的验收要求，则推送并部署到 staging。仅当短批次能够减少变更开销且不会延误关键工作时，才避免为每个琐碎条目单独部署。
  3. 保持清晰的 review 队列：每个处于 review 的条目都必须有提交／分支／PR 引用、本地验证证据，以及俄语交接或 staging 阻塞说明。目标环境的主动验证情况应记录在说明／证据／负责人信息中，而不是另设状态。
  4. 如果多个条目有相同的根因，一个连贯的提交可以引用多个 Scout 条目。为每个涵盖的条目添加说明，并在本地以及尽可能在 staging 上验证每个条目的验收条件。
  5. 如果较晚处理的本地条目在 staging 验收之前暴露出较早已审核条目的回归，应将较早条目移回 in_progress，在 Scout 中说明原因，并在部署前更新修复。
  6. staging 部署后，验证与已部署分支／提交／PR 关联的 review 条目，然后仅将各自通过验证的条目移至 done。
  7. 不同情况可能需要不同检查。应根据条目的证据和变更范围选择对应的 staging 验证方式，而不是强行套用统一检查清单。
  8. 批次开始时不要认领所有排队中的条目。只有在开始实施该条目或共享根因条目组的工作，或开始主动验证时，才认领相应条目。
  9. 在批量更新状态之前，先准备就绪矩阵，并且只更新其单项证据符合状态门槛的行。
  10. 如果 staging 路径已知且干净，除非仓库文档要求，或目标／分支／镜像不明确，否则不要添加可选的部署试运行。

部署路径发现

在进行任何推送、部署或目标环境验证之前，应先找到当前仓库唯一的规范路径，而不是尝试临时命令。

  1. 首先阅读仓库规则：AGENTS.md、README/部署文档、包脚本、CI 工作流文件，以及已有的发布说明（如有）。
  2. 如果仓库定义了分支顺序、工作流名称、健康检查、环境或审批关卡，请严格遵循该路径。
  3. 将预发布环境和生产环境视为不同目标。如果仓库只提供生产部署路径，不要将其用作默认的预发布路径；必须获得用户的明确请求，并通过仓库政策审批。
  4. 对于 GitHub Actions 部署，使用 gh 检查工作流定义、触发或监控文档中规定的工作流，并等待相关运行/检查得出结论后，再宣称部署成功。
  5. 除非仓库文档明确规定这是规范路径，或用户批准在该事件中使用此备用方案，否则不要 SSH、运行服务器端构建、重启服务，也不要选择手动 docker/pm2/systemctl 备用方案。
  6. 如果规范的预发布路径缺失、含糊、不可用或执行失败，请停止部署工作，在 Scout 中记录阻碍，并根据状态规则将条目保留在 review 或 in_progress。

部署与预发布验证

已完成的工作提交后，如果仓库提供规范的非生产预发布路径，/scout 应在不等待用户另行提示的情况下推送代码、部署到预发布环境并在那里进行验证，但须遵守仓库本地的分支安全规则。生产环境部署、向受保护分支或默认分支推送，以及将发布分支快进更新，仍须获得用户明确授权并得到仓库策略批准。

  1. 仅通过仓库规范的预发布部署路径进行部署，并等待部署健康检查通过。如果规范路径失败，请停止并报告失败的运行、命令或检查；除非用户明确批准为此次问题采用手动备用方案，否则不要自行设计备用方案。
  2. 对于耗时较长的镜像构建、推送和缓存导出阶段，请等待部署进程退出通知或明确超时。不要仅因输出停滞就中断进程；如果 Agent 取消了进程，应记录为操作员取消，而非外部部署阻塞，并在更改 Scout 状态之前重试或完成验证。
  3. 找出与已部署分支、提交或 PR 关联的 review 条目。如果用户说“所有审核任务”，请检查相关 Scout 项目中的所有 review 条目。
  4. 测试每个验证条目前，先获取完整条目、备注、证据、提交／分支／PR 字段、关联条目和验收提示。
  5. 在预发布环境而非本地进行验证：使用已部署的预发布 URL、预发布 API；对于用户可见的工作，进行浏览器检查；对于后端工作，进行有针对性的 API／运行时检查。对于用户可见的工作，预发布浏览器检查必须覆盖“用户旅程验证”中的验收路径；API／curl 证据仅作为辅助。
  6. 检查范围应针对具体条目。除非条目本身要求广泛覆盖，否则不要用噪声较多的全面检查替代有针对性的预发布验证。
  7. 如果预发布验证通过，请添加结构化的预发布证据和俄语预发布备注，注明环境、URL、提交／部署 SHA、具体检查和结果；然后将条目移至 done。
  8. 如果已开始目标验证，但无法在当前原子检查内完成，请将条目保留在 review，并记录正在检查的内容、检查者以及仍需哪些证据。
  9. 如果预发布验证失败，请添加俄语失败备注，记录复现步骤、预期／实际行为、控制台／网络／API 证据和可能原因；将条目移回 in_progress 并端到端修复。
  10. 修复预发布验证失败的问题后，重复正常流程：本地验证、引用同一 Scout 条目的提交、Scout 备注、推送、预发布部署、预发布验证；只有预发布验证通过后，才能移至 done。
  11. 如果验证因访问权限、缺少数据、不安全的破坏性操作或预期行为不明确而受阻，请根据实际情况将条目保留在 review 或 in_progress，并在 Scout 中记录确切的阻塞原因。
  12. 不要仅因部署成功，就将无关的 review 条目标记为 done。

在 Scout 中沟通

使用 Scout 备注进行持久、实用的沟通：

  • 开始工作：事项解读、本地仓库/分支、首个验证方向，以及任何即时风险。
  • 找到根本原因：原因、用户可见的影响，以及受影响的范围。
  • 发现相关事项：仅在关联重要时注明事项 ID 和关系类型。
  • 问题/阻碍：缺少的确切信息或决策、它为何构成阻碍，以及安全情况下建议采用的默认方案。
  • 验证结果：运行的检查及通过/失败结果。
  • 交接：行为变更、验证结果、提交/分支/PR/部署、状态和剩余风险。
  • 失败：无法完成的原因、证据，以及下一位负责人/后续操作。

默认使用俄语撰写 Scout 备注，除非 Scout 事项或项目明确使用其他语言。备注面向管理人员、审核者和未来的工程师：内容应让他们无需阅读聊天记录或代码也能理解，同时保持简短。

优先采用 3–6 行简短内容或项目符号。先写结果，再写证据，最后写状态/下一步。避免冗长叙述、实现细节、命令记录、堆栈跟踪、私有本地路径、机密信息、推测，以及“仍在处理中”之类的内容。如果备注超过 8 行，除非额外细节对于解除审核阻碍或复现故障必不可少，否则应压缩。

默认备注结构：

  1. Итог：变更内容或受阻事项。
  2. Проверка：最有力的最新证据，而非每条命令。
  3. Статус/следующий шаг：in_progress、review、done、changes_requested、确切阻碍、提交/PR 或下一步操作。

仅在有助于审核或复现问题时使用技术术语。说明后果，而不是逐行描述实现。只有在 Scout 需要此类证据时，才将原始日志、长表格或详细命令输出放入附件或 PR 评论中。

通过 API 添加较长的 Scout 备注时，使用与 Scout API 辅助程序相同的脚本 JSON 编码器来构造 JSON。避免为多行备注、反引号、引号或非 ASCII 文本手动转义 shell JSON。

Scout 最低限度的有效更新：

  1. 开始工作前的备注：说明要处理什么、在哪里工作，以及首个验证路径。
  2. 有用时添加根本原因备注：原因、症状、受影响范围。
  3. 交接前添加完成或阻碍备注：结果、关键验证、提交/分支/PR、状态、风险或确切阻碍。

Scout 证据范围

按成本从低到高使用 Scout 证据，选择足以回答问题的方式：

  1. 首先读取事项字段、现有备注、环境元数据、选择器、元素文本/HTML、截图路径和链接。
  2. 需要视觉上下文时，打开截图或直接 URL。
  3. 仅当问题取决于交互时序、多步骤行为，或事项字段/截图/备注中没有的证据时，才下载或检查会话录制。

不要默认将大型 rrweb/会话录制文件作为第一步下载。如果确实获取了录制文件，应搜索其中的指定字符串/事件，而不是粘贴或通读整个文件。

问题备注格式：

Вопрос: <конкретное решение или недостающий факт>
Почему важно: <влияние на реализацию или проверку>
Рекомендованный вариант: <безопасное предположение по умолчанию, если оно есть>

完成备注格式：

Итог: <что исправлено или что заблокировано>
Проверка: <самые важные checks и результат>
Статус: <new/in_progress/review/done/changes_requested/verified/cancelled>, <commit/PR/branch/deploy>, <риск или "рисков не вижу">

状态处理

状态是 Agent 的状态机。不要凭感觉选择状态。应根据以下先决条件进行选择。

状态含义：

  • new：当前不由 Agent 负责，或已重新打开以便后续分流。
  • in_progress：Agent 负责该事项，并正在积极处理、调查或修复，或者在接手后正等待直接阻碍问题解决。
  • review：本地工作已完成，需要在目标环境中审核或由人工审核；或者此类审核已开始或已分配，但尚未接受：最近已完成最终本地验证，存在明确的提交或 PR 引用，存在结构化证据，并且有俄语交接、审核进行中或阻碍说明。
  • done：AI/操作人员的工作已完成，可以由人工验收：已完成目标环境验收、预发布/生产/部署验证、用户明确接受，或其他有效级别的验收；存在结构化证据；并且有俄语完成说明。这不代表已由人工验收并关闭。
  • changes_requested：人工审核者或明确的审计根据预期/实际情况上下文否决了当前结果。除非否决原因本身不明确，否则应将其视为高优先级、可采取行动的工作。
  • verified：已完成人工验收。除非用户明确要求审计、回归问题重新打开该事项，或人工要求修改，否则应将其视为终态。
  • cancelled：Agent 判定该事项重复、无效、不适用、被有意放弃或超出范围，并已在 Scout 中记录原因。

使用 Queue Triage 表进行 UI 队列到状态的映射。不要臆造仅用于队列的工作流状态。

OpenCode 的状态转换算法：

  1. new -> in_progress：如果事项可执行，且 Agent 在没有完成证据的情况下开始工作，请调用 /items/claim。添加或保留简短的开始说明。除非收到指示，否则不要认领不明确、在确定负责人之前受阻或由他人负责的事项。不要仅为完成事项而认领 new 状态的事项；一旦存在符合要求的目标证据，直接调用 /items/resolve。
  2. changes_requested -> in_progress：如果退回的工作可执行，且 Agent 在没有完成证据的情况下接手，请添加简短说明，指出正在处理的拒绝原因，然后调用 /items/update-status，并设置 status:"in_progress"。此状态不要使用 /items/claim。不要仅为完成事项而将 changes_requested 改为 in_progress；一旦存在符合要求的目标证据，直接调用 /items/resolve。
  3. in_progress -> review：只有在修复已完成、最终本地检查通过、相关的浏览器／运行时检查通过、最终差异已审查、已有提交，且无法在同一轮中安全完成暂存环境部署／验证时，才能使用。在 /items/update-status 中设置 status:"review"，并添加内联 evidence，包含架构要求的字段（environment、scenario、action、visibleResult）、result:"pass"、适当的 level、coverage:"item" 或有理据的集群覆盖范围、针对具体事项的 acceptanceScope，以及 commitSha。只有在存在真实 PR／MR URL 时才添加顶层 mrUrl，然后补充俄语交接说明或暂存环境受阻说明（如果尚未添加）。
  4. new/changes_requested/in_progress/review -> done：只有在通过规范部署或已接受的目标环境验证后，或对于明确允许本地验收的非部署工作，才能恰好调用一次 /items/resolve。添加内联 evidence，包含架构要求的字段（environment、scenario、action、visibleResult）、kind:"verification"、result:"pass"、level:"staging_acceptance"、"production_acceptance"、"user_acceptance" 或明确的 "local_acceptance"、针对具体事项的 acceptanceScope、适用时的 URL、相关的部署／提交 SHA，以及观察到的结果。添加俄语完成说明，写明目标环境、剩余风险，并指出接下来需要人工验收。如果对于已部署或用户可见的工作，最有力的证据仅来自本地验证，则应转为 review，而不是 done。
  5. done -> done：重试 /items/resolve 时，完成引用／说明／证据操作具有幂等性。仅当需要为同一已完成事项修复或补充完成证据时才使用，不要以此代替人工验收。
  6. review -> in_progress：如果暂存环境／用户／审核者验证失败，或交接／验证证据不完整，且 Agent 将立即修复，请先添加失败说明，然后调用 /items/update-status 并设置 status:"in_progress"。
  7. done/verified -> changes_requested：仅用于明确的审计／审核范围，或人工要求退回已验收的工作时。调用 /items/request-changes，并提供具体的 summary、expected 和 actual；如有相关信息，还应添加 steps 和 url。不要使用 /items/update-status。
  8. done/verified/cancelled -> new/in_progress：仅在明确的重新打开／审计／回归工作流中使用 /items/reopen，且此时 changes_requested 并非合适的处理方式。只有在 Agent 将立即接手时才传入 status:"in_progress"，否则省略 status，以 new 重新打开。
  9. 任意状态 -> cancelled：仅当事项不应实施时使用。添加俄语说明，解释重复／无效／超出范围／无法复现的理由，并在相关时关联相关事项，然后在 API 转换有效的情况下调用 /items/cancel。

Agent 的硬性规则：

  • 切勿仅因编辑了代码、测试通过了一次或部署成功，就将状态标记为 review 或 done。
  • 除非任务没有已部署的或用户可见的运行时，或用户明确接受了结果，否则切勿仅凭本地证据将状态标记为 done。
  • 切勿将 verified 用作 AI 的常规完成状态。只有在获得明确的人类接受，或用户明确指示执行该接受操作后，才使用 /items/verify。
  • 如果现在可以安全地执行标准暂存部署，并完成针对该条目的暂存验收，就不要仅因习惯而停留在 review。
  • 没有结构化证据时，切勿将条目移至 review 或 done。证据必须包含架构要求的字段（environment、scenario、action、visibleResult），以及 result、level、coverage 和针对该条目的 acceptanceScope。优先在同一次状态 API 调用中传入 evidence。
  • 切勿将 /items/claim 或 /items/update-status 用作完成前的准备性状态转换。如果已有完成所需的证据，只调用一次 /items/resolve，由服务器处理 new、changes_requested、in_progress 或 review 状态。
  • 切勿通过 /items/update-status 创建 changes_requested。在允许明确的审查／审计拒绝时，请使用 /items/request-changes 并提供预期／实际情况。
  • 如果缺少必要的前置条件，就将条目保留在当前真实状态，并添加阻塞原因／进度说明。切勿捏造证据来满足门槛。
  • 如果一个修复涵盖多个条目，只有在每个条目各自的验收条件和证据都满足后，才分别转换其状态。

不要将 blocked 添加为 Scout 工作流状态。在审计中，blocked 是 QA／台账结果，表示无法安全确认验收；应在说明中记录阻塞原因，并将条目保留在当前真实状态，或在有充分理由明确拒绝审计时使用 /items/request-changes。

报告大范围审计的计数时，应将 Scout 工作流状态（new、in_progress、review、done、changes_requested、verified、cancelled）与 QA 结果状态（pass、fail、blocked）分开。不要将它们混在同一状态列表中。

当一个修复涵盖多个 Scout 条目时：

  1. 在主条目中添加简洁的覆盖范围和验证摘要。
  2. 在每个相关条目中添加更简短的说明，引用主条目以及共用的分支／PR。
  3. 只有在检查了每个相关条目各自的验收条件后，才转换其状态。
  4. 让无关或仅部分涵盖的条目保持未完成，并说明剩余事项。

验证

交接前：

  1. 首先运行范围最小且相关的检查。
  2. 运行 AGENTS.md、README、package 脚本或 CI 文档要求的检查。
  3. 最终代码变更后重新运行检查，不能只在修复前或修复过程中运行。
  4. 检查最终差异，并确认其范围仅限于该 Scout 条目。
  5. 对于前端／用户可见的变更，在可行时使用浏览器针对本地应用进行验证，并复现所报告的用户操作流程，而不只是检查推断出的根本原因。
  6. 对于后端／API 变更，在可行时通过测试以及有针对性的运行时／API 检查进行验证。
  7. 对于数据／部署变更，在相关时使用最新状态证据和安全备份进行验证。
  8. 提交完成后，如果标准暂存路径可用且安全，应推送并在暂存环境中验证；否则，应记录确切缺少的路径、访问权限、安全审批或失败情况。
  9. 如果某项检查无法运行，应说明原因以及使用了哪些证据作为替代。

完成定义

只有满足以下所有条件，才能将事项标记为完成：

  1. 从头到尾解决已报告的问题或所请求的改进，或者在 Scout 中记录明确的阻碍／问题。
  2. 检查最终差异，确认没有无关更改、密钥、调试代码、大范围重写或过时的 TODO。
  3. 最终编辑后有最新的验证证据：命令、浏览器检查、API 检查，或说明无法运行检查的原因。
  4. 对于前端、仪表板、小组件或其他面向用户的更改，在可行时通过浏览器验证已报告的用户流程或验收路径；对于 UI 问题，仅提供 API／curl 证据是不够的。
  5. 已完成的代码更改应有一个聚焦的提交，并在 Scout 执行工作流或仓库策略要求时引用 Scout 事项；否则，需记录未创建提交的确切原因。
  6. 在已获授权、符合仓库安全要求且存在规范的 staging 路径时，完成推送、staging 部署和 staging 验收；否则，在 Scout 中记录确切阻碍。
  7. Scout 中有结构化证据和俄语备注，涵盖开始情况、相关时的根本原因、完成情况或阻碍、验证、提交／分支／PR／部署引用、状态变更及剩余风险。
  8. Scout 状态应反映实际情况：等待处理人工／审计驳回时设为 changes_requested；工作进行中或等待澄清时设为 in_progress；已提交的工作需要目标方／人工审核或正在审核时设为 review；仅在有 AI／操作人员验收证据、且尚未进行人工验收后设为 done；仅在人工验收后设为 verified；不得默默将工作留待以后处理。
  9. 只要已授权的部署、验证 PTY、Scout 状态更新或排队的后续步骤仍在运行，且有可执行的下一步，就不要发送最终用户回复。继续等待其结束并完成剩余的 Scout 交接；只有在技术上受阻或存在安全风险时，才记录具体阻碍。

最终用户回复必须简短且以证据为依据：

  • 选择了哪个事项以及原因。
  • 更改了什么。
  • 最终更改后运行的验证。
  • 已进行的 Scout 更新。
  • 创建的提交及所用的 Scout 事项引用，或未创建提交的确切原因。
  • 已执行的推送、部署和 staging 验证，或各项无法执行的确切原因。
  • 尚未完成的事项及确切阻碍。如果没有剩余事项，请明确说明。

Scout API 使用模式

使用 Authorization: Bearer $SCOUT_API_KEY 进行身份验证。不要同时发送未记录的身份验证标头。仅在命令进程内使用上方的 Configuration 前缀。实时 OpenAPI 是端点方法、运行时 URL、请求正文和响应格式的唯一来源。

在调用任何项目或事项接口之前，先根据 OpenAPI 一次性构建 Scout API URL。OpenAPI 路径键相对于 servers[0].url；当前服务器路径通常为 /api，因此文档路径 /projects/list 对应的运行时 URL 为 $SCOUT_URL/api/projects/list。不要先尝试 $SCOUT_URL/projects/list，再改用 /api 重试；这种 404 可以避免。

标准 Node 辅助函数格式：

const scoutBase = process.env.SCOUT_URL.replace(/\/$/, '');
const headers = {
  Accept: 'application/json',
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.SCOUT_API_KEY}`,
};

const specRes = await fetch(`${scoutBase}/api/docs/openapi.json`, { headers });
if (!specRes.ok) throw new Error(`openapi ${specRes.status}`);
const spec = await specRes.json();
const apiBasePath = (spec.servers?.[0]?.url || '/api').replace(/\/$/, '');
const apiUrl = (openApiPath) => `${scoutBase}${apiBasePath}${openApiPath.startsWith('/') ? openApiPath : `/${openApiPath}`}`;

async function post(openApiPath, body) {
  const res = await fetch(apiUrl(openApiPath), { method: 'POST', headers, body: JSON.stringify(body) });
  const text = await res.text();
  if (!res.ok) throw new Error(`${openApiPath} ${res.status}: ${text.slice(0, 500)}`);
  return JSON.parse(text).data;
}

将 /projects/list、/items/list 和 /items/get 等文档中的 OpenAPI 路径传递给此辅助函数。不要将 /api/projects/list 等运行时路径传递给已经添加 servers[0].url 前缀的辅助函数。

保持 OpenAPI 发现过程安静且确定。不要在聊天中输出完整架构、完整事项负载、完整队列转储或冗长的路径列表。如果契约不匹配，只输出失败的文档路径、状态码和简短的错误正文。

规则：

  • 每次 Scout 运行开始时，获取 $SCOUT_URL/api/docs/openapi.json，根据 servers[0].url 计算 API 基础 URL，并在所有调用中复用该辅助函数。
  • OpenAPI 路径键不包含 /api。筛选路径键时，匹配 /items/、/projects/、/integrations/errors/ 和 /api-keys/ 等文档中列出的前缀；绝不要按 /api/items 或 /api/projects 筛选。
  • 使用实时 OpenAPI 中显示的方法和 JSON 请求体。不要根据端点名称推断 REST 风格路径、查询字符串中的条目查找方式或负载字段。
  • 从 .data 读取成功的 JSON 负载。对于列表，读取 .data.items 和 .data.pagination。不要为 .items、.item 或 .itemsList 等顶层旧版结构编写回退解析器。
  • 如果 Scout API 调用返回 text/html、仪表板页面或 API_ENDPOINT_NOT_FOUND，请停止。重新读取实时 OpenAPI，并且只使用文档中列出的方法和请求体重试。
  • 在运行开始时，通过文档中列出的 /projects/list 端点解析一次 SCOUT_PROJECT_SLUG：找到 slug 等于 SCOUT_PROJECT_SLUG 的项目，然后将该项目的 id 用作列出和计数条目时的内部 projectId。如果列出的项目中没有匹配该 slug 的项目，请停止，并明确说明缺少访问权限或 slug 错误这一阻碍。
  • 在修改代码或状态之前，先通过文档中列出的 /items/get 端点获取完整条目。
  • 仅当上述状态／证据规则允许时，才使用 /items/claim、/items/add-note、/items/link、/items/add-evidence、/items/update-status、/items/resolve、/items/request-changes 和 /items/reopen。/items/verify 用于明确的人类验收，不用于常规 AI 完成流程。
  • 对于 AI／操作人员完成的任务，只使用 /items/resolve 这一端点。对于已有通过验收的完成证据、状态为 new、changes_requested、in_progress 或 review 的条目，不要先调用 /items/claim 或 /items/update-status。
  • 请求架构允许省略可选的证据字符串字段；当前 Scout 也接受可选证据字段为 null，并将其存储为空 DB null。生成负载时，最好省略不存在的可选字符串字段，尤其是 refs、URL／结果字段、风险、分支、PR／MR、提交和部署字段。
  • 转为 review 时，使用一次包含内联 evidence 对象的原子 /items/update-status 调用；转为 done 时，使用一次包含内联 evidence 的原子 /items/resolve 调用。
  • 对于 /items/resolve，证据的 kind 使用 "verification"。即使旧版客户端省略或默认了该 kind，服务器也会将内联 resolve 证据存储为 verification。
  • 仅当 mrUrl 是真实的 PR／MR URL 时才填写。将本地提交 SHA 放入 Scout 备注／证据，而不是 mrUrl。
  • 使用与 API 辅助函数相同的脚本 JSON 编码器构建负载，发送前删除空字段／null 字段，并避免在备注和证据中包含机密、Cookie 或原始私有负载。
  • 批量更新 Scout 时，默认串行执行 API 调用；遇到 429 时，使用有界重试／退避；每个小批次后核验更新后的数量／条目。不要通过改用不同的端点调用顺序来重试。

边界

  • 在此手动工作流中，不要运行轮询或后台自动化。
  • 不要修改无关的 Scout 条目。
  • 不要删除用户／报告者的 Scout 数据、屏幕截图、录制内容、生产卷或业务数据。
  • 完成前，移除仅为测试工作流而创建的、由 Agent 创建的临时验证产物：先记录确切的 ID 和证据，再通过最安全的可用方式，删除范围最小的合成 Scout 条目／错误组／桥接任务或夹具。
  • 除非明确要求且安全，否则不要使用破坏性的 Git 或部署命令。
  • 不要绕过仓库安全规则、检查或浏览器验证要求。

评论

支持 Markdown