ce-product-pulse

Product Pulse

ce-product-pulse 会查询指定时间窗口内的产品数据源，生成一份涵盖使用情况、系统性能、错误异常与后续跟进项的单页精简报告。报告将保存至 <root>/pulse-reports/，关键要点会在对话中直接呈现。

本 Skill 不会修改产品本身、数据库或任何外部系统。它唯一的写操作是：将脉搏配置追加保存到 .compound-engineering/config.local.yaml（CE 统一的本地配置文件，已加入 gitignore，仅限本机有效），以及生成报告文件（<root>/pulse-reports/...）。所有 MCP 及其他数据源工具均以只读方式调用；若某工具提供了写入模式，请勿使用。

交互方式

默认使用宿主平台的阻塞式提问工具：在 Claude Code 中使用 AskUserQuestion（若未加载该 Schema，先调用 ToolSearch 并传入 select:AskUserQuestion），在 Codex 中使用 request_user_input，在 Antigravity CLI（agy）中使用 ask_question，在 Pi 中使用 ask_user（需安装 pi-ask-user 插件）。仅当宿主环境没有阻塞式工具或工具调用报错（例如 Codex 的编辑模式下）时，才降级使用对话框中的编号选项——绝对不要因为需要加载 Schema 就放弃调用。严禁静默跳过提问。

每次只提一个问题。多选框仅限首次运行配置时使用。

回溯窗口（Lookback Window）

回溯窗口是指调用本 Skill 时传入的时间范围（如 24h、7d）——存在于当前 Prompt 或上下文中，无论是由用户直接指定还是由上游 Skill 传递。

将参数解析为时间窗口。常见格式如下：

• 24h、48h、72h - 回溯小时数
• 7d、30d - 回溯天数
• 1h - 短时间窗口（非常适合上线发布期间使用）

若参数为空，默认读取配置中的 pulse_lookback_default（在 Phase 0 中解析）；若该配置亦未设置，则退回硬编码默认值 24h。若参数无法解析，提示用户进行澄清。

在时间窗口的上限增加 15 分钟的延迟缓冲。许多分析与链路追踪工具存在数据写入延迟，直接查询到 now 会导致最新事件统计不足。例如，对于 24h 窗口，实际查询范围应为 [now - 24h - 15m, now - 15m]。

产物根目录（Artifact Root）

本 Skill 会将脉搏报告写入 <root>/pulse-reports/ 目录下。请在首次拼接 <root>/ 路径时（按下方规则）解析 <root>，切勿过早解析。无论写入 <root>/... 还是读取 <root>/solutions/，都算作拼接 <root>/ 路径，均会触发解析；只有完全不触碰任何 <root>/ 路径的运行（如纯草稿或无仓库流程）才可以跳过。

<!-- ce-docs-root:start -->
在拼接任何产物路径前，必须先解析 CE 产物根目录 <root>。

• 读取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，若为空则再读取 config.yaml；以第一个非空值为准（其中 <repo-root> 通过 git rev-parse --show-toplevel 获取）。若均未设置，则 <root> 默认为 docs，与之前完全一致。
• 校验已设置的值：必须是相对于仓库的相对路径，且其实际路径（解析软链接后）必须保留在仓库内部，既不能是仓库根目录，也不能在 .git/ 之下。校验失败则直接抛错终止并指出 docs_root 及其具体值——绝不静默退回 docs。
• 使用 <root> 作为唯一的产物存放位置：若不存在则创建之；将各个路径拼接为 <root>/<subdir>（带本 Skill 自身的子目录），且不得同时读取 docs。
  <!-- ce-docs-root:end -->

核心原则

1. 以创始人视角阅读。 不硬编码任何阈值。默认不对数据定性为“好”或“坏”——直接呈现场景与数据，由读者自行判断。
2. 控制在单页内。 终端输出目标为 30-40 行。报告若偏长，务必裁剪。
3. 已保存的报告中严禁包含 PII（个人身份信息）。 落盘的报告中不得包含用户邮箱、账号 ID 或消息文本内容。
4. 安全处并发，关键处串行。 分析与链路追踪查询采用并发执行；数据库查询采用串行执行，避免造成数据库负载压力。
5. 通过历史报告保持记忆。 每次运行都会写入 <root>/pulse-reports/，以便将历史脉搏作为时间线进行浏览。
6. 仅限只读数据库访问。 若将数据库用作数据源，连接必须是只读的。配置访谈阶段会拒绝接受读写权限凭证。数据库访问是可选的——许多产品仅靠分析和链路追踪即可完成脉搏报告。
7. 优先基于战略文档进行初始化。 若存在 STRATEGY.md，访谈阶段会在提问前先读取该文档，并将产品名称与核心指标提取出来作为初始种子。数据源配置的目标，就是接入能真实测量这些指标所需的各种连接。

执行流程

Phase 0：按配置状态路由

读取配置。 运行时先通过 Shell 工具执行 git rev-parse --show-toplevel 解析出 <repo-root>。然后使用原生文件读取工具（如 Claude Code 中的 Read，Codex 中的 read_file）读取 <repo-root>/.compound-engineering/config.local.yaml。若无法解析根目录或文件不存在，视作首次运行；否则提取下方“配置字段”列出的 pulse_* 属性值。

配置字段：

• pulse_product_name -- 字符串，用于报告标题。路由必需项：若未设置，说明 Skill 未配置。
• pulse_lookback_default -- 1h、24h、7d、30d 之一（默认：24h）
• pulse_primary_event -- 字符串，核心参与/互动事件名称
• pulse_value_event -- 字符串，价值实现事件名称
• pulse_completion_events -- 逗号分隔字符串，包含 0-3 个完成事件名称
• pulse_quality_scoring -- true 或默认 false（仅限 AI 产品）
• pulse_quality_dimension -- 字符串，当 pulse_quality_scoring 为 true 时按 1-5 分打分；否则忽略
• pulse_analytics_source -- 字符串，标识分析服务提供商（例如 posthog、mixpanel、custom）
• pulse_tracing_source -- 字符串，标识链路追踪提供商（例如 sentry、datadog、custom）
• pulse_payments_source -- 字符串，标识支付服务提供商（例如 stripe、custom）；若不用则省略
• pulse_db_enabled -- true 或默认 false；为 true 时只读数据库访问将纳入脉搏统计
• pulse_metric_sources -- 逗号分隔的 metric=source 键值对，用于覆盖战略文档中各指标的数据源（例如 retention_d7=posthog,nps=delighted）。未在其中列出的战略指标将回退至 pulse_analytics_source，并带有 (default source) 标记展示，以保持显性路由。
• pulse_pending_metrics -- 逗号分隔的战略文档指标名称字符串，表示等待埋点中；在埋点完成前，各脉搏报告中会渲染为 no data
• pulse_excluded_metrics -- 逗号分隔的战略文档指标名称字符串，表示故意在脉搏中排除的指标；该指标仍保留在 STRATEGY.md 中，但不会呈现在脉搏报告中

路由逻辑：

• pulse_product_name 未设置（或配置文件缺失） -> 首次运行。进入 Phase 1（访谈），然后进入 Phase 2。
• pulse_product_name 已设置 -> 直接跳至 Phase 2。

如果传入参数为 setup、reconfigure 或 edit config，无论配置状态如何，均直接进入 Phase 1。

Phase 1：首次运行访谈

1.0 从战略文档预填（若存在）

在抛出任何问题前，先使用原生文件读取工具读取 STRATEGY.md。若文件存在，从中提取：

• 从 YAML frontmatter 的 name 字段中提取产品名称；若无 frontmatter，则降级从 H1 标题中提取（去除结尾的 Strategy 后缀，如 # Spiral Strategy -> Spiral）
• 从 ## Key metrics 章节中提取核心指标列表（每行一个）

开启访谈时先展示提取出的内容：告知已找到战略文档，显示预填的产品名称以及将带入事件/数据配置的核心指标列表，并邀请用户在继续前进行确认或修正。

若 STRATEGY.md 不存在，在对话中明确说明：未找到战略文档，将从头开始配置，并提示用户后续若先运行 ce-strategy 也可以为脉搏报告补充初始种子。

1.1 访谈流程

读取 references/interview.md。此步骤为必选——推翻/追问规则、反模式示例以及指标到数据源的映射逻辑均包含在该文件中。

按以下顺序开展访谈：

1. 产品名称（确认或修改预填值）
2. 核心互动事件
3. 价值实现事件
4. 转化/完成事件（0-3 个）
5. 质量评分（按需开启，仅限 AI 产品）
6. 数据源 - 为商定的每个指标和事件接入连接。引导优先使用 MCP。拒绝读写数据库权限。数据库完全可选。
7. 系统性能 - 针对顶部错误与延迟给出一套简短推荐配置。用户在此处很少有强烈偏好；展示默认项并接受即可。
8. 默认回溯窗口

对每个章节均应用 references/interview.md 中的追问推翻规则。根据 references/interview.md “通用规则”中阐明的 SMART 标准（具体、可衡量、可行动、相关性、时效性）来评估用户提出的每个指标、事件和信号——推翻任何含糊、虚荣或不可行动的提案。

如果用户试图提供具有读写权限的数据库凭证，必须拒绝，并提供 references/interview.md 第 6 节中记录的替代方案。

将收集到的配置作为扁平的 pulse_* 属性写入 <repo-root>/.compound-engineering/config.local.yaml，格式遵从 references/interview.md 中“配置文件格式”的 Schema。通过 git rev-parse --show-toplevel 解析仓库根目录。写入逻辑：(1) 若文件或目录不存在，创建 .compound-engineering/ 并写入该 YAML 文件；(2) 若文件已存在，将新键合并至现有 YAML 中，保留所有非 pulse 属性（如 plan_*）不受影响。若 .compound-engineering/config.local.yaml 尚未被仓库的 .gitignore 覆盖，提示用户在写入前添加该条目。在对话中向用户展示最终生成的 pulse 配置块，并提供一轮修改机会。

配置写入完成后，运行 references/interview.md 第 9 节中的定时任务调度建议：询问是否配置定时运行，以便用户定期接收脉搏报告，而无需每次手动运行。接受“是/否/稍后”。若选择“是”，交由当前宿主提供的调度原语处理——如果已安装插件内置的 schedule Skill，则直接调用；否则提示调度属于平台特定功能（如 cron、GitHub Actions、宿主自带自动化），并输出一份简短提示说明需要运行什么命令。切勿直接在行内进行调度。随后进入 Phase 2。

Phase 2：运行脉搏分析

若刚刚执行了 Phase 1（首次运行，或传入了 setup/reconfigure 参数），使用原生文件读取工具重新读取仓库根目录下的 .compound-engineering/config.local.yaml，以便获取 Phase 1 审查环节中确认的修改。否则，直接使用 Phase 0 中提取的 pulse_* 值。对任何未设置的配置项应用硬编码默认值（见 Phase 0“配置字段”）。

2.1 分发查询

在时间窗口内并发运行以下查询（使用不同工具，无共享负载）：

• 产品分析查询（核心事件数、价值实现数、完成数、转化率）
• 应用链路追踪查询（按分类统计的错误数、延迟分布、Top 错误特征）
• 支付查询（若已配置：新客户数、流失率、营收增量）

在并发查询完成后，串行运行以下查询：

• 只读数据库查询。逐个执行。仅运行紧凑、带限定条件的查询。严禁在大表上执行全表扫描。若某一 DB 查询代价高昂，跳过该查询并备注“DB 查询已跳过（预估成本过高）”。

2.2 可选：质量评分抽样

若 pulse_quality_scoring 为 true（仅限 AI 产品），从窗口内抽取最多 10 个会话/对话样本，并在 pulse_quality_dimension 记录的维度上按 1-5 分打分。

评分纪律： 默认为 4 分