authoring-signals-scouts

编写 Signals scout

scout 是一种按计划运行的 Agent，会按自己的间隔自动唤醒，查看一个 PostHog 项目，判断真正值得呈现的内容，并将其作为发现发送到 Signals 收件箱；也可以在没有发现时结束运行，这同样是一种有效结果。PostHog 提供了一组标准 scout（一个跨产品通用 scout，以及针对各个产品界面的专用 scout）。本技能可帮助你和你的 Agent 针对特定项目调整这些标准 scout，或从头编写新的 scout，以覆盖这组 scout 尚未涵盖的用例。

scout 本质上是一个名称以 signals-scout- 开头的 LLMSkill。运行框架会通过对项目的技能进行 signals-scout-* glob 匹配来发现 scout，将技能正文原样加载为 Agent 的系统提示词，并按需逐步读取其中包含的参考文件。signals-scout- 名称前缀至关重要：名称不同的技能永远不会作为 scout 运行。

动笔之前

不要凭空编写 scout。先了解目标项目——scout 的效果取决于它与所监测数据的匹配程度。

1. 了解项目。 posthog:signals-scout-project-profile-get 会返回 scout 冷启动时使用的确定性快照：正在使用的产品、包含触达量／突发量指标的热门事件、集成，以及现有收件箱计数。如果 scout 要监测某个特定事件，请确认该事件存在，并通过 posthog:read-data-schema 检查其结构。如果项目没有采集某个事件，那么针对该事件的 scout 一开始就没有用。
2. 查看已有的 scout。 posthog:signals-scout-config-list 会列出项目上的所有现有 scout，包括其运行计划、enabled 和 emit 执行策略，以及每个 scout 的 description（从技能的 frontmatter 中提取），让你无需加载正文就能判断 scout 监测的内容。不要重复覆盖标准 scout 已涵盖的产品界面——应调整现有 scout。
3. 阅读最接近的标准 scout。 它既是你的模板，也是参考范例。使用 posthog:llma-skill-get {"skill_name": "signals-scout-<x>"}（每团队一条记录）获取它，或在代码库中读取 products/signals/skills/signals-scout-*/。通用 scout（signals-scout-general）是宽泛场景的模板；如果你的范围比较具体，请选择最接近你所关注产品界面的专用 scout——使用 posthog:llma-skill-list {"search": "signals-scout"} 列出当前启用的 scout（大多数产品界面都有专用 scout：错误跟踪、日志、AI 可观测性、实验、功能标志、会话回放、Web 分析、调查等）。
4. 浏览收件箱。 posthog:inbox-reports-list 会显示实际收到的发现——据此调整，让你的 scout 提供有效信号，而不是制造噪声。

选择路径

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

构建内容

情况	方案
某个标准 scout 很接近需求，但范围过广／噪声太多／缺少适用于此项目的排除条件	调整它——缩小范围、添加排除条件、重新调整阈值。
你想监测某个标准 scout 未覆盖的产品界面（自定义事件、特定产品漏斗）	从头编写新 scout——复制最接近的标准 scout 作为脚手架，替换领域判别逻辑和探索模式。
你只想更改 scout 的运行时间／条件	无需编写——只需调整配置（参见运行策略）。

位置

路径	机制	适用场景
按团队配置（常见用户路径）	通过 posthog:llma-skill-create / -update / -file-create，在项目的技能存储中创建或编辑 signals-scout-* LLMSkill 行，然后立即通过 posthog:signals-scout-config-create 注册其配置。	为单个项目自定义。下一个周期中，执行框架会将该行纳入匹配范围；规范同步不会改动你编辑过的（“已分化”）行。
规范配置（PostHog 贡献者）	编辑 products/signals/skills/signals-scout-*/ 下的磁盘文件，运行 lint/build，然后发起 PR。	为_所有_已加入的项目改进 scout。lazy_seed 会在下一个周期中将其同步到所有已加入的团队。

原地修改的权衡：编辑团队的规范 scout 行会将其标记为 已分化——你将不再收到该 scout 的上游改进。如果你只需要_额外_的行为， 建议编写一个名称不同的新 scout （signals-scout-<your-scope>），并保留规范 scout 不变。

有关技能存储调用、构建/lint 命令以及播种机制的 具体说明，请参阅 references/lifecycle-and-testing.md。

编写 scout

首先选择类型。references/scout-patterns.md 是一本参考架构手册，介绍了 scout 常见的模式——异常监控、监控列表探索／利用、跨产品关联、推荐／缺口、数据仓库支持的数据源、自定义单事件、开放文本主题、外部工具／代码——每种模式都对应一个规范 scout，可复制用作脚手架。它还强调了一个关键点：scout 可以监控 PostHog 摄取到数据仓库的任何来源，而不只是分析事件（Slack 频道同步、计费系统、CRM、支持收件箱），还可以监控从沙盒可访问的外部系统。找到最接近的模式，然后编写主体内容。

遵循 references/scout-anatomy.md——其中包含 frontmatter 架构、规范的主体结构（快速收尾 → 定位 → 领域判别 → 探索模式 → 保存记忆 → 决策 → 排除条件 → 收尾）、精简主体规则，以及可直接复制的 specialist 和 generalist 骨架模板。

整个 scout 集群都会参考以下两份工艺文档——优秀 scout 的决策和记忆部分都以此为基础，因此编写这些部分前请先阅读：

• references/emit-contract.md——emit-signal 的参数、置信度标准、严重性、去重键、finding_id、描述文本规范，以及一个完整示例。这份文档说明 scout 如何判断_哪些发现达到标准_，以及_如何撰写发现_。
• references/dedupe-and-memory.md——四状态分类器（全新／重大更新／已覆盖／已处理或噪声）、scratchpad 键前缀词汇，以及跨项目的噪声模式。这份文档说明 scout 如何避免重复发出信号，并在多次运行中积累经验。

任何 scout 最重要的设计决策，都是它的信号与噪声判别器——一种成本低廉的特征分析，用于区分“值得调查”和“基线情况”。错误跟踪看的是 count 与 distinct_users 的比值；CSP 看的是覆盖范围，而非原始计数。你的新 scout 也需要自己的判别器。请在主体靠前的位置明确命名，让每次运行都以此为准。

运行方式（配置）

scout 的运行计划和发出行为保存在其 SignalScoutConfig 中，与技能主体分开。对于全新 scout，创建技能后立即使用 posthog:signals-scout-config-create {"skill_name": "signals-scout-<scope>", ...} 注册配置，并在同一次调用中设置以下任意字段——包括在 scout 首次运行前将其设为禁用或试运行。（这是 upsert：如果协调器已自动注册该行，你的字段会应用到该行。）否则，协调器会在下一次调度时（最多约 30 分钟后）自动注册每小时启用的默认配置。对于现有 scout，使用 posthog:signals-scout-config-update 调整配置（通过 -config-list 查找 id）：

• run_interval_minutes — 10 到 43200。默认值为 60（每小时）。如果 scout 产生过多消息或成本过高，可增大此值来降低运行频率。
• enabled — false 会完全暂停 scout（协调器会跳过它）。
• emit — 默认值为 true：scout 会将发现直接写入收件箱。标准做法是创建 scout 并让它发出信号——查看实际写入收件箱的内容，是最快的校准方式。只有在需要格外谨慎时才设为 emit=false（试运行）：scout 仍会运行并记录其推理过程，但不会向收件箱写入任何内容。对于预计消息过多、成本较高或影响重大的 scout，可考虑试运行；对于大多数 scout，直接发出信号并观察收件箱，才是更好的迭代方式。

测试循环

作为用户，你无法强制同步运行——scout 会按计划触发。标准循环是发出 + 检查：上线 scout，让它发出结果，然后根据实际产出进行校准。

1. 上线 scout（默认 emit=true），并设置较短的 run_interval_minutes，让它尽快触发——在创建时通过 posthog:signals-scout-config-create {"skill_name": ..., "run_interval_minutes": 10} 设置，就在 llma-skill-create 之后，而不是等协调器自动注册每小时运行的默认设置。
2. 触发一次后，查看它的执行结果：posthog:inbox-reports-list（它实际发出的发现）、posthog:signals-scout-runs-list（运行摘要）、-runs-retrieve（某次运行的完整推理）以及 -scratchpad-search（它写入的持久记忆）。
3. 优化正文——收紧判别条件，为误报的情况添加排除条件，并调整发出校准。
4. 确认结果符合预期后，将运行间隔恢复为可持续的频率（每小时或更长）。

想格外谨慎吗？ 先设置 emit=false 进行试运行——通过 -config-create 创建配置并设置 emit=false，确保 scout 首次运行时不会实际发出结果；它会运行并记录本来会发出的内容（可通过 -runs-list / -runs-retrieve 查看），但不会写入收件箱。检查并优化后，再将其切换为 emit=true。如果你预计 scout 会频繁发出结果、成本高或事关重大，这样做很值得；否则，直接发出并查看收件箱，是更快校准 scout 的方式。

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

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

v1 scout 的质量标准

• 在靠前位置明确说明一个简洁的信号与噪声判别条件。
• 设置快速收尾机制，让安静的运行成本较低（当监控对象处于基线状态或不存在时，不要为深入探索付费）。
• 提供 2–4 个具体的探索模式，并列出要运行的实际查询或工具——它们是起点，而不是僵化的检查清单。
• 排除条件应列出该项目已知的噪声（单用户特例、开发环境中的突发情况、允许列表中的实体）。
• 设置 Decide 部分，根据发出约定进行校准（置信度 ≥ 0.65 时发出；低于此值时写入记忆）。
• 提供 Save-memory 指南，使用 scratchpad 前缀，让 scout 每次运行都能变得更聪明。
• 保持正文精简（将深入内容放入 references/）——每一行都是每次运行都会重复产生的 token 成本。