authoring-scouts

编写 Signals 侦察器

侦察器是一种按计划定时唤醒的 Agent，它会查看一个 PostHog 项目，判断哪些内容确实值得展示，并将其作为报告写入 Signals 收件箱；如果没有值得展示的内容，则会结束运行，这也是一种有效结果。 PostHog 提供了一组规范侦察器（一个跨产品通用侦察器，以及针对各个产品界面的专用侦察器）。 这项技能可帮助你和你的 Agent 根据特定项目调整这些规范侦察器，或针对这组侦察器未覆盖的用途从头编写新的侦察器。

生成报告的侦察器会通过报告渠道输出：它会在 frontmatter 的 allowed_tools 中列出 emit_report / edit_report，并直接完整编写或编辑收件箱报告，一条侦察结果对应一份报告。 规范侦察器大多采用这种方式运行，所有新编写的报告生成型侦察器也都应如此——编写时请加入 allowed_tools opt-in。 输出为产品界面内容的侦察器（例如工作流页面上的建议）则不包含这两个工具；请参阅具有特定产品输出的侦察器。 输出最终_送达_何处是单独的、针对每个侦察器的配置决策：报告会进入 Signals 收件箱，同一份报告也可以同时发送到 Slack 频道或私信（在 Run posture 下配置 output_destinations）——因此，不要因为用户想在 Slack 中接收结果，就排除某个侦察器。 （历史上存在一种会发出信号的渠道——由管道整合的弱 emit-signal 发现结果——供从未选择加入新机制的侦察器使用，但该渠道已弃用：不要用它编写新的侦察器，应为旧侦察器启用新机制，而不是继续扩展旧渠道。）

侦察器是一个包含 SignalScoutConfig 的 LLMSkill。 运行框架会将正文原样作为 Agent 的系统提示词加载，并按需逐步读取其中捆绑的参考文件。 配置行决定一项技能是否为侦察器。 任何有效的技能名称都可以使用，因此 signals-scout- 前缀是可选的。 该前缀只影响一件事：协调器会对 signals-scout-* 进行 glob 匹配，为尚无配置的技能自动注册配置。 使用其他名称的技能需要在创建技能时一并创建其配置，而 scout-create 正是用于此操作的工具。

写作前的准备工作

不要脱离实际项目，抽象地编写 scout。 先以目标项目为依据——scout 的效果取决于它与所监测数据的契合度。 （scout 工具最近从 signals-scout-* 重命名为 scout-*；如果 scout-* 名称返回未知，服务可能仍以旧版 signals-scout-* 名称提供该工具——请搜索工具目录，并调用返回的名称。）

1. 阅读项目。 posthog:scout-project-profile-get 会返回 scout 冷启动时使用的确定性快照：正在使用的产品、包含覆盖率／突发指标的热门事件、集成，以及现有收件箱计数。 如果 scout 监测的是特定事件，请确认该事件存在，并使用 posthog:read-data-schema 检查其结构。 监测项目未采集的事件，scout 一开始就注定无效。
2. 查看现有运行项。 posthog:scout-config-list 会列出项目上所有现有 scout 及其运行计划、enabled 和 emit 状态，还会列出每个 scout 的 description（取自技能的 frontmatter），以便你无需加载正文就能了解 scout 监测的内容。 不要重复覆盖已有规范 scout 负责的范围——改造现有 scout。
3. 阅读最接近的规范 scout。 它是你的模板和参考格式。 使用 posthog:skill-get {"skill_name": "signals-scout-<x>"}（按团队划分的条目）获取它，或在仓库的 products/signals/skills/signals-scout-*/ 中阅读。 通用 scout（signals-scout-general）是宽泛场景的模板；如果你的范围属于特定领域，请选择最贴近该场景的专用 scout——使用 posthog:skill-list {"search": "signals-scout"} 列出当前可用的 scout（大多数产品场景都有专用 scout：错误追踪、日志、AI 可观测性、实验、功能标志、会话回放、Web 分析、调查等）。
4. 浏览收件箱。 posthog:inbox-reports-list 会显示实际收到的报告——调整你的 scout，让它提供有效信号，而不是制造噪声。

选择路径

这里有两个独立的决策：要构建什么，以及它要放在哪里。

要构建什么

情况	方法
某个规范 scout 已经很接近，但范围太广／噪声太多／缺少适用于此项目的排除条件	改造它——缩小范围、添加排除条件、重新调整阈值。
你想监测规范 scout 都未覆盖的场景（自定义事件、特定产品漏斗）	从头创建 scout——以最接近的规范 scout 为脚手架，替换领域判别条件和探索模式。
你想在应用更改前比较提示词、模型或推理投入	私有试用——保留已保存的 scout，检查其评估标准，并通过下方的测试循环比较不同版本。
你只想更改 scout 的运行_时间_／条件	无需编写——只需调整配置（参见“运行状态”）。
你有针对 scout 的临时反馈、参考信息或短期上下文	无需编写——留下注释（参见“使用注释进行引导”）。

适用场景

路径	机制	适用场景
每个团队（常见用户路径）	通过 posthog:scout-create 创建一个可运行的新 scout；之后通过 posthog:skill-update / -file-create 编辑其提示词或文件，并通过 posthog:scout-config-update 调整其运行时配置。	为单个项目定制。运行框架会在下一次 tick 时纳入该行；规范同步会保留你已编辑（“已分化”）的行。
规范版本（PostHog 贡献者）	编辑 products/signals/skills/signals-scout-*/ 下的文件，运行 lint/build，并提交 PR。	为所有已加入的项目改进 scout。lazy_seed 会在下一次 tick 时将其同步到所有已加入的团队。

就地调整的权衡：编辑适用于你团队的规范 scout 行，会将其标记为已分化——你将不再收到该 scout 的上游改进。 如果你只需要增加一项行为，建议编写一个名称不同的新 scout（signals-scout-<your-scope>），并保留规范版本不变。

参见 references/lifecycle-and-testing.md，了解具体的 skills-store 调用、build/lint 命令，以及播种机制的工作方式。

编写 scout

首先选择类型。 references/scout-patterns.md 是一本指南，介绍 scout 常见的参考架构——异常监测、存活状态／缺失监测、零结果／未满足需求、监视列表探索／利用、跨产品关联、推荐／缺口、由数仓提供数据的来源、自定义单事件、开放文本主题、对抗／滥用集中度、外部工具／代码、状态∩代码交集、自定义问题跟踪器／工作队列、每日摘要／汇总、对预检测流进行分诊、第一人称自用／探测、周期性测量／LLM 评判、维护者／管理者、所有者范围内的手册／队列、触发器到简报的丰富化、调度器／活动、舰队元 scout／审查者——每种类型都对应一个规范 scout，或一个经过验证、可作为脚手架复制的自定义类型。 其中还强调了一个关键点：scout 可以监测 PostHog 摄取到数据仓库的任何来源，而不仅仅是分析事件（例如 Slack 频道同步、计费系统、CRM、支持收件箱），以及沙盒可访问的外部系统、其他 Agent 的输出，乃至 scout 集群本身。 如果某个内置信号来源已涵盖相关范围（GitHub 和 Linear 问题），问题跟踪器模式也会说明该来源的适用边界，以及 scout 从何处开始发挥价值。 scout 不必止步于描述修复方案：维护者／管理者模式说明了持有 write_scopes 的 scout 如何自行维护一组仪表板、告警、数仓视图或扫描器提示词，并通过分级写入机制明确哪些变更会自动应用、哪些会验证并报告，以及哪些会交由人工处理。 找到最接近的模式，然后编写正文。 遵循 references/scout-anatomy.md——其中包含 frontmatter 架构（包括每个生成报告的 scout 都必须选择加入的 allowed_tools 报告渠道；具有特定产品输出的 scout 不需要此项）、规范的正文结构（快速收尾 → 定向 → 领域判别 → 探索模式 → 保存记忆 → 决策 → 排除条件 → 收尾）、精简正文规则，以及适用于专业 scout 和通用 scout 的可直接复制骨架模板。

正文应以功能为先。 正文是一份提示词，运行时每次都会完整读取，并且在 scout 的整个生命周期中都会如此——因此正文只说明 scout 关注什么以及如何做出判断，不写其他内容。以下四类内容不应出现在正文中：

• 不写推出状态。 预览标志、抢先体验门槛、“最近更名”的工具、逐个 scout 迁移的端口。这些内容本月属实，下个月就可能误导读者，而每次运行都无法判断哪种情况适用。写明 scout 当前应遵循的行为；如果某项功能可能不可用，就说明运行时如何判断，而不是何时会推出。
• 不写待办事项。 计划中的工作、尚不存在的字段、有人打算新增的类别。运行无法据此采取行动，只会消耗令牌，并让运行误以为应该等待某项功能。
• 不写仅适用于某个项目的事实。 只在一个项目中存在的指标、仪表板、事件、 ID 或审核者。规范的 scout 会部署到每个项目，因此某个项目中的事实对几乎所有运行都不适用。提及可选产品时，应说明运行如何判断项目是否使用该产品，绝不要假设项目一定在使用。
• 不重复描述框架机制。 报告渠道约定、运行门控和收尾格式都来自框架提示词，每个报告渠道 scout 都会收到。若在正文中重复，内容可能与实际规则不一致，导致运行同时保留同一规则的两个版本。正文只保留 scout 自身领域的描述。

同样四类内容也不应出现在随附参考资料中：运行时也会读取这些资料，因此其中的推出状态或待办事项不能比正文更多。

整支 scout 队伍都会依据两份工艺参考资料进行判断——优秀 scout 的决策和记忆部分都以它们为基础，因此撰写这些部分前请先阅读：

• references/report-contract.md——报告工具（scout-emit-report / scout-edit-report）、报告标准（仅当你愿意全程负责某项发现时才亲自撰写）、suggested_reviewers 路由、通过 report_id 去重的规范（渠道并非幂等——撰写报告前，先通过原生的 inbox-reports-list / inbox-reports-retrieve 对照现有报告），以及已接受的注意事项：后续流水线可能会改写已撰写的标题或摘要。 这决定了你的 scout 如何判断哪些发现达到标准以及如何提交报告。
• references/dedupe-and-memory.md——四态分类器（全新 / 重大更新 / 已涵盖 / 已处理或无关噪声）、暂存记事本的键前缀词汇，以及跨项目噪声模式。 这决定了你的 scout 如何避免重复提交，以及如何从每次运行中学习。
• references/report-checks.md——scout 附加到报告上的后续检查，以便之后衡量“修复是否有效？”，而不是依赖记忆。 这决定了你的 scout 在有人采取行动后，如何跟进某项发现。

报告回顾的是过去；检查则面向未来——它是一项预期及其测试时间，通过 scout-report-check-create 写入报告。 如果你的 scout 发现的问题属于修复效果会在之后的数据中显现的类型，就为它添加检查部分。 正文中应包含三条规则，其余内容见参考资料：

• 每次都先列出报告中已有的检查项（scout-report-check-list）。针对同一主张的待处理检查项会让新增检查变成噪声，而且一份报告最多只能有五个待处理检查项。
• 只要一个数字就能判定主张，且事件或操作序列能够提供该数字，就使用 metric_threshold。 协调器会自行测量，无需运行 scout。
• 如果无法用单个数字判定，或该数字不在事件数据中，就使用 agent——例如日志速率、效果体现在触发的实体而非数量上的修复，以及需要读取堆栈跟踪才能判断的主张。

任何 scout 最重要的设计决策，是它的信号与噪声判别器——一种低成本的画像形状读取方式，用来区分「值得调查」和「基线」。 对于错误跟踪，判别器是 count 与 distinct_users 的比值；对于 CSP，则是覆盖范围，而非原始数量。 你的新 scout 需要有自己的判别器。 请在正文顶部附近明确命名，以便每次运行都以它为依据。

（唯一的例外是：结构化输出通道上的测量型 scout不设门槛——它会对每个抽样项应用一套评分规则，而这套规则取代判别器，成为需要命名、实际试用并校准的设计重点。参见 references/scout-patterns.md 中反复出现的测量型／LLM 评审模式。）

另一个设计考量适用于指标型 scout——它会对一个具名且可复用的度量进行评分、排序或报告。该度量可以是业务指标（MRR、流失风险、使用收入、激活），也可以是每次运行时计算的运营遥测指标，用于监控或报告（每次运行成本、失败率或错误率、延迟、吞吐量）。 如果项目已有该度量的获批指标（metric-list 会显示已有指标），请在正文中注明该指标，并使用 data-catalog-metric-run 运行，以确保 scout 的数值与团队现有的报告口径一致。

运行方式（配置）

scout 的运行计划和输出行为保存在其 SignalScoutConfig 中，与技能正文分开。 对于全新 scout，请在调用 posthog:scout-create 时通过嵌套的 config 对象传入这些设置，包括在 scout 首次运行前将其创建为禁用或试运行模式。 创建 scout 来测试某个想法时，请设置 config.enabled=false，以免定时运行干扰测试。 该端点会原子化地创建技能和配置，始终让 scout 加入报告通道，并在重试相同定义时安全地重新应用配置字段。 具有特定于产品的输出的 scout 必须关闭报告通道，因此请改用 skill-create 和 scout-config-create 创建；参见具有特定于产品的输出的 Scouts。 否则，协调器会在下一个运行周期（最长约 30 分钟）自动注册一个启用的配置，并采用默认的每 24 小时运行一次的计划。 对于现有 scout，请使用 posthog:scout-config-update 调整配置（通过 -config-list 查找 id）：

• run_interval_minutes — 30 到 43200。 默认值为 1440（每 24 小时一次）。 提高此值可降低话多或成本高的 scout 的运行频率。
• run_cron_schedule：五字段 cron 表达式（'30 9 * * *'、'0 9 * * 1-5'），按项目时区计算；每次运行间隔必须至少为 30 分钟。 设置后，它优先于 run_interval_minutes，因此要降低使用 cron 的 scout 的运行频率，必须修改或清除 cron（设为 null 可恢复为滚动间隔）。 新建或编辑的计划以编辑时间为基准，等待下一个时段，而不是补跑已经错过的时段。 当运行需要落在特定的钟点时，可以使用它：例如在站会前生成摘要，或仅在工作日监控。
• 定时运行会在一个时间窗口内开始，而不是精确到某一分钟。 每个 scout 在该窗口内都有固定偏移，因此每次运行的间隔保持不变。 使用 cron 的 scout 会在 cron 时间后的 20 分钟内开始，因此 0 9 * * * scout 每天都会在 9:00 到 9:20 之间的同一分钟开始。 使用间隔的 scout 会在同一个 30 分钟协调器周期内开始，last_run_at 记录的是周期时间，而不是开始时间。 scout 的首次运行、手动运行、工作流运行和报告检查运行会立即开始。 解释或编写计划时，请将时间描述为一个窗口。
• enabled — false 会完全暂停 scout（协调器会跳过它）。
• precheck_query — 默认为 null：定时运行开始前执行的 HogQL SELECT 查询，其中包含 {since}、{now} 和 {interval_minutes} 占位符。 如果查询没有返回行，或返回一行且只有一个值为 false 的结果（例如 count() 为零），则跳过运行，不会创建运行记录或沙盒。任何其他结果都会启动运行，且返回的行会进入运行提示词。查询出错也会启动运行。 只有定时运行会执行此项：手动运行、工作流运行或报告检查运行始终会启动。 如果 scout 大多数周期都无事可做，请设置此项。保存前请使用 posthog:scout-config-precheck-test 测试查询，因为定时检查以 scout 的执行用户身份运行，而试运行以你的身份运行。 规范 scout 可以在 scout-precheck-query frontmatter 中提供默认值。precheck_query 会覆盖该默认值，设为 null 可恢复默认值，而 precheck_disabled: true 会同时关闭两者。 完整步骤、占位符语义，以及如何排查没有运行记录的周期，请参阅 references/scheduled-precheck.md。
• emit — 默认值为 true：scout 会将报告直接写入收件箱。 设置 emit=false（试运行），可查看普通运行的推理过程，而不将报告发布到收件箱。 私有试用会分别捕获报告和记忆；即使源 scout 已暂停或设为 emit=false，也可以使用。
• network_access — 默认值为 trusted：scout 的沙盒只能访问平台的可信域名允许列表（PostHog、GitHub、常见软件包注册表），这足以覆盖 MCP 循环和 gh，但会阻止其他所有访问。 如果 scout 的技能需要读取任意外部网站，例如文档、arxiv.org 上的论文或供应商状态页面，请设为 full。 此设置从 scout 的下次运行起生效，变更会记录在活动日志中。
• auto_pause_exempt — 默认值为 false。 如果没有人互动 scout 的报告（未打开、评分或采取操作——云端 Web 收件箱会记录阅读行为；其他客户端目前还不会），系统会先发出警告，然后自动暂停它（pause_reason=ignored）——每次运行都会消耗一个沙盒 Agent，因此不应让无人使用其输出的 scout 永远运行。仅仅安静的 scout 只会被标记（pause_reason=no_output，此警告不会导致暂停），因为监控型 scout 的任务可能本来就是保持安静。 -config-list 会将警告显示为 status=pending_pause，将暂停显示为 status=paused_by_system；再次设置 enabled=true 会恢复 scout，并开启新的宽限期，之后系统才会再次评估。 如果 watchdog scout 的全部职责就是保持安静，请预先设置 auto_pause_exempt=true，这样它甚至不会被标记为安静。
• write_scopes — 默认值为 ["notebook:write"]：scout 会读取项目，并将发现、记忆和笔记本写入项目。 notebook:write 可访问项目中的每个笔记本，不仅限于 scout 创建的笔记本。对于除了发现和记忆之外不应写入任何内容的 scout，请发送 []（或从列表中移除此项）。与其他权限范围不同，即使运行的作者无法再解析，该权限仍会保留，并使 scout 以另一名项目成员的身份操作。 如果 scout 的职责是维护某项内容，而不只是描述会如何更改，请授予它 dashboard:write、insight:write、annotation:write、alert:write、customer_task:write、llm_skill:write、warehouse_view:write、warehouse_table:write、replay_scanner:write、canvas:write 或 experiment:write。 此类 scout 的正文应遵循 references/scout-patterns.md 中的维护者／管理者模式：精选清单、写入流程（执行并记录、执行并验证后报告、交由人工处理）、每次运行的变更上限，以及列出所有已更改对象的滚动维护报告。 每个权限范围都面向整个项目，并涵盖相应类型的所有对象的更新和删除，不仅限于 scout 创建的对象；因此，只授予 scout 正文实际涉及的权限，并在正文中说明它可以更改什么以及何时可以更改。 llm_skill:write 是需要格外谨慎的权限：自定义 scout 本身也是存储中的技能，因此持有此权限的 scout 可以编辑同级 scout 的正文，甚至编辑自身运行所依据的正文。只有在 scout 的职责确实是维护一组技能时才授予此权限；请在正文中列出这些技能，并说明除非职责就是维护 scout，否则不得修改 scout。 warehouse_view:write 和 warehouse_table:write 是有意分开的：负责维护一组视图的 scout 不需要同时创建表。只有在 scout 同时维护两者时才授予这两个权限。 replay_scanner:write 允许维护扫描器。创建、复制或启用扫描器，以及更改已启用扫描器的目标、采样或模型前，scout 必须设置 credit_limit。它不能清除限制、删除扫描器，也不能启动手动扫描、重试或回填。使用 enabled: false 停止扫描器并保留其观测结果。只有在记录明确的用户判定时才更改共享评分，因为评分会影响扫描器对后续会话的判断。 customer_task:write 涵盖项目中的所有 Customer analytics 任务，包括分配给其他人的任务：创建、更新（状态、截止日期、负责人）、归档和恢复已归档任务，但不包括删除。请在正文中说明 scout 负责哪些人的任务，以及是否可以重新分配任务。 Customer analytics 任务仍受 customer-analytics-customer-tasks 功能标志控制。未启用该功能标志的项目不提供任务工具，授予此权限也不会生效，因此不要在此类项目中授予该权限。 canvas:write 可访问公开空间中的所有画布，以及执行用户创建的所有画布：发布、布局、运行时状态，以及对执行用户自己画布的软删除。scout 运行无法创建画布，因为 scout 任务没有可用于存放画布的空间。请先创建画布，在正文中注明其 id，并遵循 references/scout-patterns.md 中的单画布维护者变体。每个已发布版本都会记录运行任务，因此版本历史会显示由哪次运行发布。 experiment:write 是唯一会改变终端用户所见内容的权限。它可访问项目中的所有实验：创建、编辑、复制、归档、启动、暂停、恢复、结束和重置。启动和暂停会开启或关闭关联的功能标志。scout 不能删除实验、将实验复制到其他项目、迁移旧版实验，也不能打开功能标志清理拉取请求。scout 目前无法持有 feature_flag:write，因此实验启动或其功能标志开启后，scout 也无法发布变体，或更改变体、发布比例或保留组。因此，scout 可以设置草稿和结束实验，而由人员发布实验。请在正文中说明 scout 负责哪些实验，以及无需人员要求即可执行哪些生命周期变更。 只有 scout 运行的执行用户（即其作者）或项目管理员可以设置此字段，授予权限的操作会记录在活动日志中。受限范围的 API 密钥必须自身持有所授予的每项权限范围。 获得授权的 scout 会在运行提示词中获知可更改的对象，并被要求在结束时列出每项变更。授权只是权限上限：执行用户自身的权限仍适用于每个对象；如果写入被拒绝，scout 会报告拒绝情况，而不会重试。 试运行（emit: false）不会持有此授权，因此可以预览 scout，而不会让它更改任何内容。 要审核运行后的写入，请参阅 working-with-scouts 中的“审核 scout 的变更”：变更会记录在 scout 执行用户的活动日志下，并标记为“via MCP”，但记录行不会显示 scout 或运行的名称。 此设置从 scout 的下次运行起生效。
• output_destinations — 默认为无。 将 Slack 添加到现有 scout 时，请先读取 output_destinations，然后发送保留所有键的完整对象。更新会替换整个对象，因此只发送 slack 会移除现有的 webhook 指针。 将 slack 设置为向 Slack 和收件箱发送 scout 发出的每份已呈现报告（ready 或 pending_input）；判定器抑制的报告按设计不会发送到 Slack：指定工作区的 integration_id，再指定 channel（channel_id|#channel-name）或最多五个接收私信的 users（member_id|@display-name），两者不能同时设置。 受限范围的 API 密钥或 OAuth 令牌除了 signal_scout:write 外，还需要 integration:read 和 task:read（或相应的写入权限范围）才能设置 slack；权限范围不足的凭据会收到权限错误。 thread_reports: true 会先以简短的引导消息发布报告，再根据摘要中的章节标签将其余内容拆分为回复，以免长报告被截断；它不会改变发现内容的发布方式。 Slack 投递会将该 scout 的所有输出直接发送过去——没有优先级筛选，也不经过审核者路由——因此适合标准已很严格的 scout，而不适合仍在校准中的话多型 scout。 报告发送到 Slack 的 scout 也不会因报告被忽略而自动暂停，因为系统无法衡量 Slack 中的消费情况。
• display_name：UI 中显示的 scout 名称。留空则使用根据技能名称生成的默认名称；它不会更改固定不变的 skill_name。 这是此处唯一无法通过 scout-create 中嵌套的 config 设置的选项：创建后请使用 -config-update 设置。
• model：固定 scout 运行所用的模型。留空则使用集群默认值，大多数 scout 都应如此；如果 scout 的工作需要更强的模型（长时间研究）或更便宜的模型（频繁、机械化的探测），则设置此项，并在正文中说明原因。 早期访问：未加入 scouts-model-config 预览的项目会拒绝任何非 null 值，并提示“此项目目前无法选择 scout 模型。”因此，只有在该功能标志已开启时才建议固定模型。
• mcp_gateway_server_ids：此 scout 的运行可挂载的 MCP 存储服务器（按 id 指定），从成员已共享给整个团队的连接中选择。 默认值为空，即不挂载任何共享服务器。设计意图是只让团队共享的连接支持 scout 运行，这样无论谁编辑 scout，运行行为都相同；但如果项目尚未启用 MCP gateway 强制策略，启动路径仍可能挂载执行用户的个人连接，因此必要时请在运行记录中检查已挂载的服务器。 请像对待 network_access 一样谨慎处理：它会将第三方工具及共享连接所拥有的访问权限交给 scout，变更会记录在活动日志中，而且正文应说明 scout 使用每台服务器的用途。
• repositories — 默认值为 []：scout 的沙盒不包含代码检出；对于只通过 MCP 读取项目的 scout，这正合适。 对于需要分析代码的 scout，请设置 ["organization/repository", ...]；运行开始前，其沙盒会克隆每个仓库，因此 scout 可以搜索代码树、阅读目录结构，并运行项目自身的构建、类型检查和测试，而不必每次都通过 gh api 获取文件。 每个 scout 最多可设置 10 个仓库，而且每个仓库都必须能通过项目的 GitHub 连接访问——无法访问的名称会在写入时被拒绝，而不会等到运行中途才以克隆失败的形式出现。 无论是否克隆，scout 的 GitHub 访问权限都保持只读，因此列出仓库只会提供可读取的代码树，不会赋予推送、评论或创建拉取请求的能力。scout 的写入权限需要单独选择加入，目前尚不可用。 多仓库 scout 获取的每个代码树都来自对应仓库的默认分支；不支持按仓库选择分支。 每个代码树都包含仓库的完整提交历史，因此技能正文可以直接针对代码树运行 git log、git blame 和 --since，无需先进行非浅克隆。 此设置从 scout 的下次运行起生效，变更会记录在活动日志中。
• tags — 用于对 scout 集群分组的自由格式标签，例如 ["revenue", "on-call"]。每个 scout 最多设置 10 个；标签会规范化为小写 kebab-case（On Call → on-call），并自动去重。 创建时就设置标签：创建后已完成分组的 scout 无需后续编辑，而且桌面应用的 scout 列表可按标签筛选。 优先使用集群中已有的标签（-config-list 会显示每个 scout 的标签），不要创建近似重复的标签——revenue 和 revenue-analytics 会将同一组拆散。 写入会替换整个标签集合，因此请发送完整的目标列表，而不只是新增项。 使用 -config-list 的 tags 参数筛选列表（以逗号分隔，可匹配带有任意一个所列标签的 scout）。
• structured_output_schema — 默认为 null（关闭此通道）。 设置 JSON Schema（draft 2020-12，根节点 "type": "object"）来描述一条结构化记录，scout 就会在报告之外获得第三个输出通道：每次运行都会看到该 Schema，并获知要通过 scout-record-output 提交符合要求的记录（每次运行一条，或每个经过判定的实体一条；记录数量和时机由技能正文决定）。 服务器会根据 Schema 验证记录（每次调用要么全部成功，要么全部失败），并在项目中将其记录为 $scout_structured_output 事件，标量载荷键会展开为 output_<key> 属性——因此，判定／评分型 scout 的数据序列可以直接在洞察中制图，过去的记录也能像其他事件一样查询（按 subject 或 run_id 筛选，按 output_<key> 拆分）。 此通道也需要启用 emit：试运行 scout 无处可写入记录，因此其 scout-record-output 会以安全失败方式拒绝。 如果 scout 的工作是定期进行测量（例如判定每份抽样报告为好／坏／不确定并说明原因、为账户评分、对会话分类），而不是呈现异常，请使用此项；枚举应尽量精简，并添加自由文本原因字段，让数据序列既便于拆分分析，又可供审计。 技能正文应说明采样内容、判定方式，以及每条记录应标记的 subject；记录结构由 Schema 定义。 由于记录是普通事件，任何可使用事件的系统都可以据此采取行动——将工作流或 CDP 目标设置为由 $scout_structured_output 触发，并按你的 skill_name 和某个 output_<key> 值筛选，就能将测量型 scout 变成自动化流程的前端（把判定结果路由到频道、任务或 CRM），无需人工介入。 完整的设计说明——包括评分标准编写、以比率而非分数为导向的记录结构、评分标准版本管理、采样纪律、与报告的衔接、评分成为路由决策后的变化，以及非判定型变体（结构化提取、状态快照、合成遥测）——请参阅 references/scout-patterns.md 中的定期测量／LLM 判定器模式。

通过备注进行引导（无需编写）

有时你不想修改 scout，而是想_告诉它一些事情_。 这就是 scout notes 的用途：团队成员（或代表团队成员行事的 Agent）留给整个 fleet 的简短引导信息，每次运行都会将其与临时记录和运行历史一起作为先前上下文读取。 如果引导内容属于反馈、指引或有时效性的上下文，请使用备注而不是编辑：

• 对输出的反馈：“你一直标记的 staging 流量激增是已知噪声，别再报告了”。
• 指引：“本周深入调查 EU 注册漏斗——我们认为有回归问题”。
• scout 无法自行了解的上下文：“我们周二上线了新的结账流程，请将此后转化率的变化视为预期情况”。

相关工具（读取操作使用公开的 signal_scout:read 作用域；由于 scouts 会原样读取备注，写入或删除备注所需的授权与编辑 scout 技能相同——需要 llm_skill:write 作用域和技能编辑器访问权限）：

• posthog:scout-notes-create {"content": "...", "skill_name": "signals-scout-web-analytics"} — 使用某个 scout 的确切技能名称指定它（通过 scout-config-list 查看名单；该技能必须已存在，因此拼错目标会被拒绝，而不会悄悄导致无人接收），也可以省略 skill_name，创建每个 scout 都能看到的通用备注。 可选设置 expires_at，让限时备注（如“本周密切关注”）自动失效。 skill_name: "pipeline:report-research" 指定报告流水线的研究阶段，而不是任何 scout，用于指导如何研究、评估和分发根据聚类信号构建的报告（“将与计费相关的报告分发给计费团队”）。scout 直接撰写的报告不会经过该阶段，因此相关规则应写入面向所有 scout 的备注（省略 skill_name），或针对单个 scout 的备注。它是唯一的 pipeline:* 受众；其他任何值都会被拒绝。
• posthog:scout-notes-list — 浏览有效备注；传入 skill_name 可查看指定 scout 会读取的内容。 除人工备注外，还会显示由系统生成的备注：驳回或暂缓备注、讨论问题、点赞评分备注，以及报告审核者的添加／移除记录，都会作为备注转发给相关 scout，并标记相应的 origin（report_dismissal、report_discussion、report_feedback、report_reviewer_correction；直接留下的备注标记为 human）。系统生成的备注会在约 30 天后自动过期。 需要注意三点：只有在提问者本身具有备注写入权限时，讨论问题或评分备注才会被转发（需具备技能编辑者权限；对于受限凭据，还需 signal_scout:write 和 llm_skill:write）；只有在操作人员对规范项目具有技能编辑者权限时，审核者变更才会被转发（审核者变更本身仍会记录在报告中）；没有报告读取权限（task:read）的调用者看不到任何源自系统的备注，因为这些备注引用了报告内容。缺少某条系统生成的备注可能是上述任一原因所致。驳回备注仍保留在报告上，讨论问题仍保留在其讨论任务中，但评分备注只以转发给 scout 的备注形式存在（此外还会记录一个分析事件）；因此，未能转发的评分备注就会消失。
• posthog:scout-notes-delete {"id": "..."} — 删除已处理或不再适用的备注。
• posthog:scout-run-now {"id": <config_id>, "note": "..."}：仅引导单次运行。该备注（最多 1,000 个字符）会与长期备注一起由该次运行读取，不会作为备注传递给之后的运行，因此适合用于“现在检查这个”，而不适合写成每次计划运行都会持续读取的备注。之后的运行读取历史记录时，该备注仍会显示在该次运行的元数据（run_note）中，因此应将其写成有日期的单次指示（如“仅限今天：……”），而不是长期政策。此操作需要技能编辑者权限；对于受限凭据，除基本的 signal_scout:write 外，还需具备 llm_skill:write，与长期备注所需的两个权限范围相同（否则会返回 403；移除备注即可无备注运行），并且与任何手动调度一样会消耗一次运行额度。

scout 如何处理备注：每次运行都会在步骤 1 读取备注，并被要求让新备注明显影响调查方向，但备注仅供参考。 备注会引导注意力，但不会降低 scout 的证据标准，也不会强迫它生成报告；因此，即使备注写着“报告 X”，scout 仍会如实调查，而不会自动生成报告。 scout 会在运行摘要中说明闭环情况（它采取了哪些备注指导，以及如何执行），并将吸收的指导纳入其草稿区。

如何在备注和编辑之间选择：对于“当前项目、当前时点”的引导，以及在正式采纳前试行某项建议，备注是合适的工具；一旦引导成为永久政策（如排除条件、阈值或范围变更），就应编辑技能。反复重新留下的备注说明该编辑早该做了——将其升级为技能编辑。 备注的生命周期由人工管理：scout 从不会删除备注，因此请自行删除已处理的备注（或预先设置 expires_at），以保持信息渠道的高信噪比。

工作流触发的运行

工作流中的“Run scout”步骤会在事件触发时启动一次运行，例如出现新的 GitHub issue 或 pull request。 每次运行的提示词都会在 Your run identity 中说明它是如何启动的：triggered_by 的值为 schedule、manual、workflow 或 check（私有试运行时为 experiment）。 工作流运行还会携带 trigger_workflow_id，即触发该运行的工作流 ID。 在正文中根据该值进行分支判断（“如果 triggered_by 是 workflow …… ”），而不要根据是否存在备注来判断。

运行所看到的内容取决于步骤是否有备注：

• 有备注时，执行框架会让备注中提到的主题成为运行的首要任务。 运行会先完整处理该主题，再做其他事情：调查、作出判断、提交报告或记录拒绝该主题的原因，并写入正文要求的记忆。 该次运行可跳过 scout 的例行任务。 如果正文没有说明如何处理工作流触发的运行，该次运行就会跳过例行任务，将其留给定时任务处理。
• 没有备注时，运行会收到提示，说明它由工作流启动，且没有任何内容指明具体事件。 它会像处理定时任务那样执行正文，除非正文说明工作流触发的运行应如何处理。

如果 scout 的默认行为不合适，请在正文中编写工作流触发时的处理说明。 例如：“工作流触发运行时，还要刷新标签缓存”，或“工作流触发运行且没有备注时，只检查最近一小时”。

增量状态需要完整遍历。 跳过例行任务或提前结束的运行必须保持游标、基线和“上次扫描时间”标记不变，并且只写入与所处理主题有关的记忆。 执行框架会向每次带备注的工作流运行说明这一点。 请在正文中列出 scout 自己使用的增量键，因为只有正文知道部分遍历时哪些暂存区条目不得变动。

根据标识符编写步骤备注。 使用 pull request 编号、issue URL 或告警 ID，例如 Issue #{event.properties.issue_number}。 不要粘贴事件中的标题、正文或其他自由文本。 scout 会将备注视为不可信输入，而标识符可以让它使用自己的工具查找相关内容。

测试循环

在真正消耗一次运行前，先亲自试用侦察器。 你——编写侦察器的 Agent——拥有与侦察器运行时相同的 PostHog MCP 工具（execute-sql、read-data-schema、各产品的列表工具、scout-project-profile-get）。 最省钱、最快的迭代方式完全不需要运行侦察器：手动根据实时项目检查侦察器自身的逻辑。 确认监测的事件／实体确实存在，且其结构符合你的假设；运行判别器，检查它在_此_项目的数据中是否真的能将信号与噪声区分开来；然后运行每种探索模式的查询，看看能查出什么。 这个循环免费且即时——根据发现的情况完善正文，重新运行查询，反复迭代，直到侦察器逻辑经得起真实数据的检验。 真正的迭代就在这里发生。

有少数运行时工具无法通过这种方式试用，因此要在首次真实运行中验证。 任何需要 run_id 的工具都只能在运行内部使用，而项目尚未启用的工具，无论谁调用都会失败。 posthog:scout-lighthouse-audit 是需要提前规划的工具：它会在真实的限速浏览器中加载页面并返回实验室指标、浏览器选定的最大内容绘制元素、LCP 时间在各阶段的分布，以及按排名排列的预计节省量——这正是页面性能发现能够指出原因而非猜测原因的依据。 它需要运行的 run_id，仅限允许列表中的公开页面（浏览器不会登录任何账号，因此登录页后面的页面会报告登录屏幕的指标，而非该页面的指标），仅适用于已启用此工具的项目，并且每次运行最多可执行五次审计。调用被拒绝不会产生费用，但页面一旦加载，该次额度就会被消耗，无论结果如何；每条错误消息末尾都会显示本次运行剩余的审计次数，可据此区分调用被拒绝和预算耗尽。 因此：只有在某次运行中成功调用该工具后，才将其视为可用；切勿编写依赖它才能得出发现的正文；并将实验室证据与现场证据分开标注——一次限速冷加载可以解释某项发现，而真实用户的现场百分位数据才能证明确实存在问题。 然后检查首次真实运行的记录，确认调用及其返回内容，就像检查无法手动运行的查询一样。

私下比较不同版本

目前，rubric 和私下试用的 MCP 工具仅供工作人员使用，并且需要启用 scout-trials 功能标志。 当用户想测试现有 scout、尝试一个想法，或比较多种提示词、模型或推理力度时，请使用此流程。 试用会针对项目数据运行实际的 scout，在私下环境中记录其报告和记忆，根据一个已保存的 rubric 对其进行评估，并保存比较报告。 生成、运行 scout 和评估都会消耗模型用量；请根据用户要求的预算选择版本数量和重复次数。

1. 选择来源。 对于现有 scout，通过 posthog:scout-config-list 获取其配置，并使用 posthog:skill-get 读取其指令。 对于新想法，使用 posthog:scout-create 创建完整的 scout，其中包括 config: {"enabled": false} 和任何捆绑的 files。 然后使用配置的 id 调用 posthog:scout-trial-setup，检查准备情况并查看支持的模型和推理力度。
2. 审阅并保存 rubric。 读取 posthog:scout-rubric-get。 如果需要生成，使用 posthog:scout-rubric-generate，然后轮询 posthog:scout-rubric-get，直到生成完成。 审阅建议和捕获的来源，选择能衡量预期任务的标准，并使用当前的 revision、完整的标准列表，以及采用该次生成来源时所需的 adopt_generation_id 调用 posthog:scout-rubric-save。 如果建议质量不佳，请直接编辑标准：启用或停用任意检查、修改其措辞、添加自定义检查，或从已保存列表中移除不需要的自定义检查或生成的检查。保留六项内置默认检查；若不需要，可将其停用；省略 adopt_generation_id 以保留已保存的引用。 单独生成不会保存或采用任何内容；试用开始前，已保存的 rubric 必须采用一个来源。
3. 开始比较。 使用 posthog:scout-trial-start，并提供基线和用户要求的版本。比较提示词更改时，应固定模型和推理力度。 每个候选项都要提供完整的 skill_body；已保存的来源不会更改。 一次比较可容纳 5–10 个提示词；请使用不同的假设，避免无故增加重复次数。
4. 查看结果。 轮询 posthog:scout-trial-report，查看已保存的比较结果，包括标准证据、失败项、适用性和成本。 如果错误允许，可使用 posthog:scout-trial-resume 恢复中断的试用；使用 posthog:scout-trial-list 查找已保存的试用。 在推荐或应用候选项之前，请先阅读其分数背后的证据。

阅读 references/lifecycle-and-testing.md，了解确切的保存和采用规则、请求标识、版本输入及结果解读。 如果设置受阻或工具不可用，请说明限制；普通运行的影响不同，不能替代私下比较。 现有的 posthog:scout-trial-create / posthog:scout-trial-get 组合会运行并读取单个私下的 scout，但不会自动评估；如需完成整个测试流程，请使用 scout-trial-start / scout-trial-report。

应用更改并正常运行

当用户请求中包含应用候选方案时，通过 posthog:skill-update 使用当前的 base_version 更新已保存的技能。 使用 posthog:scout-config-update 根据所请求的发布方式设置预期模型、计划或 enabled=true；Agent 可以通过此现有工具启用或暂停 scout。 此工具无法保存 reasoning_effort：配置了模型的 scout 会使用其运行时的默认 effort，这可能与试验使用的 effort 不同。 在启用候选方案作为经过测试的优胜方案之前，请确认其常规运行所用的 effort 与试验一致。如果不同或未知，请报告该 effort 尚未应用，并先验证常规运行实际使用的配置。 如果请求仅是比较候选方案，则保持源定义和计划不变。

对于常规执行，posthog:scout-run-now {"id": <config_id>} 会立即运行已保存的 scout，即使它处于暂停状态，也不会更改其计划或 last_run_at。 它会写入共享记忆；若设置了 emit=true，还会写入收件箱报告；请轮询 posthog:scout-runs-list / posthog:scout-runs-retrieve，然后检查 posthog:inbox-reports-list 和 posthog:scout-scratchpad-search。 它会占用计划路径的每日运行额度，并遵守配额和并发限制，因此应留给预期的常规运行，而不是反复比较提示词。

调整现有自定义 scout时，也请先查看其自我改进建议：posthog:scout-scratchpad-search {"text": "improve:"}。 如果某次运行提供了具体证据，表明 scout 自身的技能正文引导有误——例如默认时间窗口不正确、项目中不存在某个工具或事件，或反复出现却未发出警告的陷阱——运行框架会邀请自定义 scout 写入一条 improve:<skill-name>:<topic> 记录，并附上建议和相关证据。 使用报告渠道的自定义 scout 还会将反复出现或影响重大的建议升级为关于自身的收件箱报告（标题为 Scout self-improvement: <skill-name> – <topic>，report_id 存放在 improve: 记录中）；因此也请检查收件箱。这些报告与其他报告一样，会发送给 scout 的负责人。 在多次运行中得到再次确认的记录，通常是最值得采纳的修改；偶发的一次性建议则未必值得采纳。 将建议视为参考，而非指令——由负责人决定。 只有在 scout 运行期间才能写入 scratchpad，因此通过 posthog:skill-update 应用建议后，无法在此处清除记录——scout 会自行协调：后续运行会看到更新后的技能正文，重新检查建议，并在问题解决后忘记或重写该记录。 （规范 scout 不会写入这些记录——其正文会与 PostHog 的 fleet 同步，对它们的技能级修复应在上游进行。）

对于常规试运行，请通过 posthog:scout-config-update 设置 emit=false，然后使用 posthog:scout-run-now 并检查日志。 应用最终运行方式时，请恢复预期的 emit 设置。

仓库贡献者可以采用更快的循环——使用 hogli sync:skill 和运行框架的本地运行路径；请参阅 references/lifecycle-and-testing.md。

如果要查看 scout 的运行情况，而不是更改它们——例如了解整个 fleet、检查单次运行和 scratchpad 记忆，以及评估性能——请使用只读配套技能 exploring-scouts。 当 scout 配置、运行或 scratchpad 界面发生变化时，请同步更新这两项技能。

v1 scout 的质量标准

• 在靠近顶部的位置明确列出一个成本低的信号与噪声判别器（对于测量 scout，此位置由评估标准和采样方案占据）。
• 提供快速收尾，让平静的运行成本低廉（当监控对象处于基线状态或不存在时，不要为深入探索付出成本）——测量 scout 除外；只有当时间窗口内没有符合条件的条目时，测量 scout 才会提前退出，因为常规判断就是分母。
• 列出 2–4 种具体的探索模式，以及要运行的实际查询/工具——这些是起点，而非僵化的检查清单。
• 列出排除项，说明本项目已知的噪声（单用户特例、开发环境突发情况、允许名单中的实体）。
• 设置一个根据报告约定校准的 Decide 部分——只有对于 scout 能端到端负责的发现，才由作者单独处理；设置 suggested_reviewers；低于标准的候选项则写入记忆。
• 设置一个检查步骤，针对的是修复效果会在后续数据中显现的发现——先列出报告中尚未完成的检查，再根据能否用一个数字确定结论，选择 metric_threshold 或 agent。
• 以功能为中心的正文：不包含发布状态、待办事项、仅适用于本项目的事实，或提示词已涵盖的测试框架机制。
• 提供保存记忆的指引，使用 scratchpad 前缀，让 scout 每次运行后都能变得更聪明。
• 正文保持精简（将详细内容放入 references/）——每一行都是每次运行都会产生的重复 token 成本。
• 设置简洁的 frontmatter description——用一两句话说明监控对象及其关注的模式。 每个 scout 的 description 都会一并载入调用方的 AI 插件，因此冗长的 description 会浪费 token 预算并被截断；省略全 fleet 通用的套话（报告标准、持久记忆、自包含的同级项）。