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	multi-file 格式的输出目录
--showMaybeRelevant	boolean	false	另外显示可能受影响的会话
--startingPointSha	string	—	仅考虑自此提交 SHA 以来的变更

第 2 步 — 了解输出结构

下载的数据按以下结构组织：

.meticulous/sessions/
  manifest.json                       # List of all sessions with summary metadata
  sessions/
    <sanitized-session-id>/           # Special characters in session IDs are replaced for filesystem safety
      summary.json                    # Session overview: URL, viewport, duration, event count
      user-events.json                # Sequence of user interactions (clicks, typing, navigation)
      network-requests/
        summary.json                  # All network requests: method, URL, status (no bodies)
        <order>.json                  # Individual request/response pairs (with bodies)
      storage/
        cookies.json                  # Initial cookie state
        local-storage.json            # Initial localStorage state
        session-storage.json          # Initial sessionStorage (if present)
        indexed-db.json               # Initial IndexedDB (if present)
      url-history.json                # Page navigation history with timestamps
      context.json                    # Feature flags, user ID, custom context (if present)
      websockets/                     # WebSocket data (if present)
        summary.json                  # WebSocket connections overview
        <connection-id>.json          # Events for each connection

第 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. 如果需要了解应用的初始状态（Cookie、localStorage 等），请检查 storage/ 中的文件。

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

常见用例：

了解用户流程

阅读 user-events.json，查看用户交互的确切顺序。这会告诉你用户点击、输入和导航了哪些内容，帮助你了解代码更改需要支持什么。

创建网络模拟

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

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

验证覆盖范围

对照用户事件和网络请求，检查代码更改，确认会话覆盖了你修改的代码路径。

替代方案：下载指定会话

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

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

# MCP (returns the same structured data inline instead of writing it to disk)
get_session_data(sessionId="<id>")

CLI 默认将文件写入 .meticulous/sessions/；使用 --outputDir 可更改输出位置。

最后一步 — 向 Meticulous 提交反馈

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

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-use-session-data

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-use-session-data")