meticulous-use-session-data

使用此工作流从 Meticulous 获取结构化的会话数据——覆盖你代码变更的已录制用户流程和网络模拟。

开始之前，运行 meticulous-cli-update 技能以确保 Meticulous CLI 是最新的——除非它已经在此对话中运行过，否则请执行此步骤。

步骤 1 — 查找相关会话并下载其数据

在 git 仓库的根目录下运行以下命令：

meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

这将：

1. 识别哪些录制的会话执行了当前分支上修改的代码路径。
2. 将会话数据作为结构化的目录树下载到 .meticulous/sessions/。

选项：

选项	类型	默认值	描述
--format	multi-file	—	设置为 multi-file 以将每个相关会话的数据下载为结构化的目录树
--minimum-times-to-cover-each-line	number	—	至少选择这么多会话以覆盖每个编辑的行，当有更多候选时选择最多样化的子集
--include-superfluous-sessions	boolean	false	也包括那些确实测试了一些更改但相对于 --minimum-times-to-cover-each-line 是多余的会话
--outputDir	string	.meticulous/sessions	多文件格式的输出目录
--showMaybeRelevant	boolean	false	也显示可能受影响的会话
--startingPointSha	string	—	仅考虑自此提交 SHA 以来的更改

步骤 2 — 理解输出结构

下载的数据组织如下：

.meticulous/sessions/
  manifest.json                       # 所有会话的列表，包含摘要元数据
  sessions/
    <sanitized-session-id>/           # 会话 ID 中的特殊字符被替换以确保文件系统安全
      summary.json                    # 会话概览：URL、视口、持续时间、事件数
      user-events.json                # 用户交互序列（点击、输入、导航）
      network-requests/
        summary.json                  # 所有网络请求：方法、URL、状态（无请求体）
        <order>.json                  # 单个请求/响应对（含请求体）
      storage/
        cookies.json                  # 初始 cookie 状态
        local-storage.json            # 初始 localStorage 状态
        session-storage.json          # 初始 sessionStorage（如果存在）
        indexed-db.json               # 初始 IndexedDB（如果存在）
      url-history.json                # 页面导航历史，带时间戳
      context.json                    # 功能标志、用户 ID、自定义上下文（如果存在）
      websockets/                     # WebSocket 数据（如果存在）
        summary.json                  # WebSocket 连接概览
        <connection-id>.json          # 每个连接的事件

步骤 3 — 浏览数据

1. 从 manifest.json 开始 查看所有可用的会话。每个条目包括会话 ID、起始 URL、事件数、持续时间和网络请求数。选择与你的任务相关的会话。

2. 读取会话目录中的 summary.json 以快速了解该会话——起始 URL、视口大小、总持续时间和事件数。

3. 读取 user-events.json 以了解用户流程。每个事件包含：

   • type：交互类型（例如 click、input、scroll）
   • selector：目标元素的 CSS 选择器
   • timestampMs：事件发生的时间戳
   • coordinates：点击位置（如果适用）

4. 浏览 network-requests/summary.json 以查看会话期间的所有 API 调用。每个条目显示 HTTP 方法、URL、状态码、内容类型和响应时间——不包含响应体，因此可以快速浏览。

5. 读取单个 network-requests/<order>.json 文件 以获取特定 API 调用的完整请求/响应数据。在编写测试时将这些用作模拟数据。摘要中的 order 字段对应文件名。

6. 检查 storage/ 文件 如果你需要了解初始应用状态（cookies、localStorage 等）。

步骤 4 — 使用数据进行测试

常见用例：

理解用户流程

读取 user-events.json 以查看用户交互的确切顺序。这告诉你用户点击、输入和导航了什么，有助于理解你的代码变更需要支持什么。

创建网络模拟

使用网络请求文件为你的测试创建模拟响应：

1. 读取 network-requests/summary.json 以找到相关的 API 端点。
2. 读取单个 network-requests/<order>.json 文件以获取完整的请求/响应对。
3. 使用 response.content.text 字段作为测试中的模拟响应数据。

验证覆盖率

将用户事件和网络请求与你的代码变更进行交叉引用，以验证会话覆盖了你修改的代码路径。

替代方案：下载特定会话

如果你已经知道需要的会话 ID，可以直接下载它们：

meticulous download session --sessionId=<id> --format=multi-file

默认写入 .meticulous/sessions/。使用 --outputDir 更改输出位置。

MCP 工具：get_session_data 直接返回相同的结构化会话数据（而不是写入磁盘），适用于连接到 Meticulous MCP 服务器 的客户端。

最后一步 — 向 Meticulous 提交反馈

使用完会话数据后，向 Meticulous 团队提交一条简短的反馈：会话数据是否覆盖了你需要的流程，缺少哪些信息或哪些信息会使任务更轻松？

meticulous agent submit-feedback --message="<一两句话>" --outcome=<helped|neutral|hindered> --skill=meticulous-use-session-data

MCP 工具：submit_feedback。