ce-product-pulse

产品脉搏

ce-product-pulse 会查询产品在给定时间窗口内的数据源，并生成一份简洁的单页报告，涵盖使用情况、性能、错误和后续跟进事项。报告会保存到 <root>/pulse-reports/，并在聊天中展示要点。

完成标准： <root>/pulse-reports/YYYY-MM-DD_HH-MM.md 中存在一份 30-40 行的报告，报告标题和最重要的后续跟进事项已在聊天中展示，且已到达第 3 阶段（安排）。

边界

• 全程只读。 此技能不会更改产品、数据库或任何外部系统。它唯一的写入操作是将脉搏设置追加到 .compound-engineering/config.local.yaml（访谈和选择退出的写入仍保留在本地覆盖文件中），以及写入报告文件。MCP 和其他数据源工具均以只读方式调用；如果工具提供写入模式，请勿使用。数据库数据源必须使用只读连接——访谈会拒绝读写凭据；数据库访问是可选的，因为许多产品仅凭分析和追踪数据就能完成脉搏报告。
• 保存的报告中不得包含个人身份信息（PII）。 写入磁盘的文件中不得包含用户邮箱、账户 ID 或消息内容。
• 像创始人一样阅读。 不设置硬编码阈值，不默认标记“好”或“坏”，也不触发告警：呈现数据，由读者自行判断。
• 单页。 目标为 30-40 行。如果某个部分内容较少，就保持简短；如果报告篇幅过长，就删减。
• 不是发布日志，也不是仪表板的替代品。 已发布的工作记录在问题跟踪系统和提交历史中。深入调查仍需使用原生工具；此报告汇总为单页概览，并保存每次运行的结果，以便将过往脉搏报告作为时间线浏览。

交互方式

默认使用当前工具列表中已有的宿主阻塞式提问工具（按能力匹配，而非按特定宿主的名称）。工具出现在当前列表中，就证明它存在；切勿调用面向用户的提问工具来确认其是否存在。如果列表中有匹配的工具但尚未加载，请使用宿主的工具发现原语加载该能力——不要搜索其他宿主的工具名称。只有在列表中没有此类工具，或实际提问调用报错时，才在宿主面向用户的聊天界面上提供编号选项作为后备方案。切勿默默跳过提问。

一次只问一个问题。仅在首次运行配置时使用多选。

回溯窗口

回溯窗口是调用此技能时指定的时间范围（例如 24h、7d）——无论是用户直接提供，还是由调用技能传入，都会出现在当前提示或对话中。

常见形式包括过去若干小时（24h、48h、72h）、过去若干天（7d、30d），以及用于发布的 1h。

如果参数为空，则使用配置中的 pulse_lookback_default（在第 0 阶段“按配置状态路由”中解析）；如果该项也未设置，则回退到硬编码默认值 24h。如果无法解析参数，请用户澄清。

在窗口上界应用向前回溯 15 分钟的缓冲区。许多分析和追踪工具存在数据摄取延迟；如果查询截至当前时间，最近的事件数量会被低估。对于 24h 窗口，查询 [now - 24h - 15m, now - 15m]。

构件根目录

此技能会在 <root>/pulse-reports/ 下编写 pulse 报告。首次需要拼接 <root>/ 路径时（按照下方代码块的说明）解析 <root>，在此之前不要解析。写入 <root>/... 和读取 <root>/solutions/ 都算是拼接 <root>/ 路径，因此任一操作都会触发解析；只有完全不涉及任何 <root>/ 路径的运行——仅使用临时目录或不涉及仓库的流程——才跳过解析。

在拼接任何构件路径之前，先解析 CE 构件根目录 <root>。

• 读取 <repo-root>/.compound-engineering/config.yaml 中的 docs_root，且仅从该文件读取（<repo-root> = git rev-parse --show-toplevel）。不要从 config.local.yaml 读取。未设置时，<root> 为 docs，与之前完全相同。
• 验证已设置的值：它必须是相对于仓库的目录，且其真实路径（解析符号链接后）必须位于仓库内，既不能是仓库根目录，也不能位于 .git/ 下。否则停止并报错，错误中须指出 docs_root 和该值——绝不要回退到 docs。
• 使用 <root> 作为唯一构件位置：如果不存在则创建它；将每个路径拼接为 <root>/<subdir>，其中 <subdir> 使用此技能自己的子目录；也绝不要读取 docs。

阶段 0：根据配置状态进行路由

从两个仓库文件中解析普通 CE yaml 键。

• 读取 <repo-root>/.compound-engineering/config.local.yaml，然后读取 config.yaml（<repo-root> = git rev-parse --show-toplevel）。跳过不存在的文件。Gitignore 不影响解析。
• 优先采用第一个生效的（未注释）值。对于标量，空值视为未设置；无效值会继续检查下一层，然后使用技能默认值。对于列表和映射，键一旦存在——包括空列表或空映射——就会整体替换该键。
• 不要对 docs_root 使用此规则——该键仅从 config.yaml 读取。

使用 git rev-parse --show-toplevel 解析 <repo-root>，然后按上述普通键规则处理 pulse_* 键。每当需要解读 pulse_* 值时，都要读取 references/config.md——它仅定义键模式：每个键、允许的值及其默认值；未设置或无效的值应采用文档规定的默认值，而不是自行推测。

**路由：**每次运行都要经过阶段 2（运行 pulse），然后进入阶段 3（调度）。如果级联解析后 pulse_product_name 未设置（按上述普通键规则），无法解析仓库根目录，或参数为 setup、reconfigure 或 edit config，则先运行阶段 1（首次运行访谈）。否则，从阶段 2（运行 pulse）开始。

阶段 1：首次运行访谈

首先读取 references/setup.md；此读取为必需步骤。该文件定义了策略文档的预置方式、访谈顺序及质疑标准、拒绝使用可读写数据库的规则、如何在不影响其他键的情况下将配置写入 config.local.yaml，以及一次性的调度邀请。具体问题来自 references/interview.md，该文件将其列为自身必需的读取内容。

阶段 2：运行 pulse

如果已运行阶段 1（首次运行访谈），则在任何查询之前，使用原生文件读取工具，从仓库根目录重新应用普通键规则（先本地文件，再已跟踪文件），以获取阶段 1 审核步骤中接受的修改。否则，使用阶段 0（根据配置状态进行路由）中已提取的 pulse_* 值，并对所有未设置的值应用 references/config.md 中的默认值。

然后在分派任何查询之前读取 references/run.md；此读取为必需步骤。该文件定义哪些查询并行运行、哪些串行运行、决定是否执行数据库操作的 pulse_db_enabled 检查、可选的质量抽样及其评分规则、报告的四个部分，以及报告的写入位置。

阶段 3：调度

设置时提供一次定期运行选项（references/setup.md）。之后运行时，轻描淡写地再次提及：如果参数是调度关键词（daily、hourly、weekly），请说明本次运行为临时运行，并指向该框架的调度原语；如果没有记录调度安排，且这是第三次或之后的运行，则提及一次可用调度功能。不要每次运行都提醒，也绝不要自动安排调度——任何移交给调度原语的操作都需要明确确认。