发现并查询 Dataset¶

当你已有本地路径、对象存储 URI 或 dataset pin，希望先理解其中的 Run 数据再编写报告时，使用这个工作流。

完成后你会得到什么

你会知道 Dataset 包含哪些 Source、有哪些可用 relation，以及如何可复现地回答一个受资源限制的只读问题。

1. 检查 Dataset¶

pchronicle list ./dataset
pchronicle stats ./dataset

list（ls）列出当前路径的一层 children，体验对齐 shell ls。含 chronicle.manifest （或其它 Dataset 标记）的子目录显示为 Dataset，并带类型和轨迹数。ls --sources 会打开该路径并打印 query 会合成的 Snapshot 成员。stats 汇总把该路径打开为 Snapshot 之后的可用性。自动化中使用 JSON 输出：

pchronicle list ./dataset --format json

Dataset 可能包含损坏条目时，显式选择错误策略：

pchronicle list ./dataset --errors report
pchronicle list ./dataset --errors strict

探索陌生数据时使用 report。在自动化任务中，如果不完整 Dataset 应该让任务失败而不是产生部分结果，再切换到 strict。

2. 从内建分析开始¶

pchronicle stats overview ./dataset
pchronicle stats agents ./dataset
pchronicle stats models ./dataset
pchronicle stats tools ./dataset

内建 analysis 覆盖常见汇总；需要自定义筛选、join 或聚合时再进入 SQL。

3. 检查查询 Schema¶

pchronicle query ./dataset --sql "DESCRIBE dataset.steps"

常见关系包括 sources、runs、steps、tool_calls、events 和 trajectories；实际可用关系取决于 Dataset 内容。

4. 提出受资源上限保护的问题¶

pchronicle query ./dataset \
  --sql "SELECT session_id, COUNT(*) AS steps
         FROM dataset.steps
         GROUP BY session_id
         ORDER BY steps DESC"

数据管道使用 --format jsonl|csv 和 --output。Query 只读，并受行数、字节、发现规模与 timeout 上限约束。

5. 先定位，再分析¶

list/ls 列出当前路径。ls --sources 与 query 打开该路径：叶子 Dataset 是一个 source；纯目录会变成由嵌套 Dataset 与 JSON 组成的虚拟 dataset。find 在已 pin 的 Snapshot 内定位。 CLI --match 与 Web q 共用同一表达式、报告的 scope 和 snapshot_id；Web UI 可以对返回字段做高亮，不改变命中集合。

pchronicle find ./dataset --match "timeout" --format json

用返回的 source_path、session 和 step 身份去收窄 SQL。

6. 消除重复外部 ID 的歧义¶

同一个外部 ID 可能出现在多个文件中。先查找候选，需要持久引用时再保留 source_path：

pchronicle find ./dataset --session-id session-42
pchronicle find ./dataset --source nested/source.json \
  --session-id session-42

精确参数见 pchronicle 命令行参考，字段和 join 规则见查询模型。内部发现与版本固定机制属于 Snapshot 设计。