pChronicle 命令行设计与使用指南¶

本文介绍 pchronicle 的公共命令行。当前安装版本的 pchronicle --help 是该版本可用参数的准确信息来源。

pchronicle 用于浏览、查询、交换和服务 Agent Run Dataset。它既适合人在终端中探索，也适合 shell、CI 和 Agent 发起受资源上限保护的只读分析。

按任务查找命令¶

先体验产品： pchronicle onboard query 使用临时示例数据，不需要 Dataset 路径。
检查 Dataset： 先用 list/ls 和 stats overview，再编写 SQL。
定位 Run 或文本： 使用 find --run-id、--session-id 或 --match。
提出可复现问题： 使用 query --sql 或 query --file，并显式设置输出与资源上限。
提供历史服务： 先完成只读查询，再阅读服务指南使用 serve。

第一次使用可以复制：

pchronicle onboard query
pchronicle list ./trajectory-data
pchronicle query ./trajectory-data --sql 'SELECT COUNT(*) FROM dataset.runs'

后两条命令要求你已有 Dataset；如果还没有数据，完成 onboard query 后继续阅读Dataset 入门。

如果你第一次使用 pChronicle，可以从这里开始：

pchronicle onboard

1. Intro¶

pChronicle¶

pchronicle 围绕 Dataset 提供一组组合式命令。读取命令可以浏览、定位和分析 Run；交换命令负责导入和导出；agent 与 serve 分别提供交互分析和本地服务入口。

Dataset¶

Dataset 就是 path。 pChronicle 打开这条 path 作为轨迹存储。它可以写成：

本地目录或文件（./local/path）；
对象存储中的 URI 前缀（s3://bucket/prefix）；
解析到上述位置的 dataset pin（@name）。

Dataset 内部可以保存一种或多种受支持的运行数据格式。pChronicle 负责发现和规范化这些数据；用户只需要向命令提供 Dataset，不需要先理解内部文件、分片、投影或版本布局。

每条读取命令都会使用一个内部一致的数据视图。命令开始后底层数据发生变化，不会改变该命令已经产生的结果。

@NAME 明确表示一个 dataset pin。裸字符串始终按路径或 URI 解释：

prod 本地相对路径 ./prod
@prod 名为 prod 的 Dataset pin

这种区分可以避免同名目录出现或消失时，命令突然解析到不同位置。

命令总览¶

pchronicle
├── onboard [SECTION] [DATASET]
├── dataset|ds pin|unpin|list|show|set|rename
├── list|ls [DATASET]
├── stats [DATASET]
├── stats overview|agents|models|tools [DATASET]
├── find [DATASET]
├── query [DATASET]
├── import --from SOURCE --to DATASET
├── sync --from DIRECTORY [--mirror DIRECTORY] [--to DIRECTORY]
├── export --from DATASET --to TARGET
├── agent codex|claude [DATASET]
└── serve DATASET...

2. Commands¶

每节依次给出命令原型、一到两个代表性例子和必要说明。方括号表示可选参数，竖线表示互斥选择。

公共参数¶

pchronicle [-c FILE] [--log-level LEVEL] <COMMAND> ...

参数	默认值	用途
`-c, --config FILE`	平台配置目录	使用另一份用户配置文件
`--log-level error\|warn\|info\|debug`	`info`	控制 stderr 诊断详细度；`serve` 同时用它过滤 Warehouse tracing（`pchronicle.serve`）
`-h, --help`	—	查看当前层级帮助
`-V, --version`	—	查看版本

更多细节随各命令说明给出；任何层级都可以使用 --help 查看本机版本的准确语法。

2.1 `onboard`¶

pchronicle onboard [SECTION] [DATASET] [--no-pause]

pchronicle onboard
pchronicle onboard query @prod

通过内建示例或自己的 Dataset 体验 pChronicle 工作流。SECTION 可以是 basics、all、concepts、 inspect、analyze、query、formats、find、exchange 或 serve，默认为 basics：列表、汇总和一个 SQL 问题。all 保留完整进阶课程。交互式终端会在章节之间暂停；pipe、重定向或 --no-pause 输出连续 Markdown。完整引导还会演示统一的 FTS/JSONB find 表达式、Storyline Lance 导入导出以及只读 Web/API 边界；使用 pchronicle onboard find DATASET 可以直接查看检索语法。

2.2 `dataset`（pin）¶

pchronicle dataset pin|unpin|list|show|set|rename …

pchronicle dataset pin default ./trajectory-data
pchronicle dataset show default
pchronicle dataset pin local ./trajectory-data
pchronicle dataset pin prod s3://bucket/evals
pchronicle dataset pin secure s3://bucket/evals --ak "$AWS_ACCESS_KEY_ID" --sk "$AWS_SECRET_ACCESS_KEY"
pchronicle dataset pin minio s3://bucket/evals --endpoint http://127.0.0.1:9000 --region us-west-2 --ak 123 --sk 123
pchronicle dataset pin regional s3://bucket/evals --region us-west-2
pchronicle dataset pin team catalog://127.0.0.1:8081 --ak USER_AK --sk USER_SK
pchronicle dataset set prod s3://new-bucket/evals
pchronicle dataset list
pchronicle stats @prod

default 是保留 pin：省略 Dataset 参数时使用，必须是本地目录。其他 pin 只改用户配置，不移动或删除 Dataset。名称使用小写字母、数字、点、下划线和连字符，并以小写字母开头；codex/claude/claude-code 保留。用户配置（-c / PCHRONICLE_CONFIG）使用 [pins.<name>]：

[pins.default]
uri = "/abs/path/to/warehouse"

[pins.prod]
uri = "s3://bucket/evals"
endpoint = "http://127.0.0.1:9000"
region = "us-west-2"
access_key = "..."
secret_key = "..."

旧键（如 default_warehouse、aliases）会被拒绝。dataset list 还会显示内置 @codex / @claude / @claude-code。 S3 凭证用 --ak/--sk 写在同一 pin 表中，不会被 dataset list / dataset show 打印。 catalog://127.0.0.1:PORT pin 是 Directory locator：@team/prod 换票打开 path， @team 列出可访问 Datasets。详见 RFC-0013。

2.3 `list`¶

pchronicle list [DATASET] [--sources] [--physical] [--format auto|table|json] [--errors report|strict]
 [--max-files N] [--max-entries N]

pchronicle list
pchronicle list @prod --sources --physical --format json --errors strict
pchronicle list @prod --sources --format json

list（ls）列出当前路径的一层 children，体验对齐 shell ls。若某一子目录是 Dataset （含 chronicle.manifest 或其它叶子标记），同时显示类型和轨迹数。--sources 会打开该路径并打印 Snapshot 成员（query 会合成的虚拟 dataset）。--physical 增加大小、修改时间和存储版本信息。还可以用 --max-files 和 --max-entries 限制发现范围。 --errors report 会报告坏数据项并继续；strict 遇到第一个坏数据项即失败。

2.4 `stats`¶

pchronicle stats [DATASET] [--format auto|table|json] [--errors report|strict] [--timeout 30s]
 [--max-files N] [--max-entries N]

pchronicle stats
pchronicle stats @prod --errors strict --timeout 2m

结果包含 Dataset 的 ready、degraded 或 error 状态，各类数据计数、counts_complete，以及 canonical Event Store 的 Storyline projection 状态。还可以用 --max-files 和 --max-entries 限制检查范围。stats 不会创建、同步或修复 projection。

报告型子命令（原 analysis）挂在同一入口下：

pchronicle stats <overview|agents|models|tools> [DATASET]
 [--format auto|table|jsonl|csv|tsv]
 [--limit 100] [--max-output-bytes 8MiB] [--timeout 30s]

pchronicle stats overview
pchronicle stats tools @prod --format csv --limit 20

报告	内容
`overview`	数据可用性，以及 Run、Step、Agent、Model、tool call 总览
`agents`	按 Agent identity 和 version 聚合
`models`	区分 Run 声明的 model 和实际观察到的 Step model
`tools`	按 normalized function name 聚合，并报告 duration coverage

内建报告用于常见、稳定的统计。需要任意筛选、join 或聚合时使用 query。

2.5 `find`¶

pchronicle find [DATASET]
 (--run-id ID|--document-id ID|--session-id ID|--match EXPRESSION)
 [--source PATH] [--step-id N] [--match EXPRESSION ...]
 [--format auto|table|json] [--max-results N]

pchronicle find @prod --session-id session-42
pchronicle find ./dataset \
 --source nested/source.json \
 --session-id session-42 --step-id 7
pchronicle find ./dataset \
 --match "timeout" --match "retry" --format json
pchronicle find ./dataset \
 --match '$.tags=important' --match '$.priority=2' --format json

外部 ID 不保证在整个 Dataset 内唯一。没有 --source 时，同一个 ID 可以返回多个候选；结果中的 source_path 可以供下一次查询消除歧义。--match 是统一检索表达式：普通关键词搜索 Storyline Step 内容并使用 FTS/Jieba 索引，#system(prompt) 等形式可以限定字段，AND、OR、NOT 用于组合条件；$.path=value（或 #json("$.path")=value）按 JSONPath 对 JSONB 列做精确值匹配。仅 JSON 表达式当前搜索 Run 级 JSONB，和文本混合时搜索 Step 级 JSONB。可以重复 --match 要求所有表达式同时满足；显式使用 #json.metrics(...) 时即使没有文本条件也会检索 Step 级 JSONB。CLI 与 Web 共用该表达式、报告的 search.scope 和 snapshot_id；Web UI 可以对返回字段做高亮和截取，不改变命中集合。使用 --format 和 --max-results 控制结果形式和数量。每条结果还包含有界的 preview 摘要，便于在继续查询前判断候选是否正确。 JSON 输出还会报告 search.mode（fts、json、fts+json 或 identity）、search.scope（steps 或 runs）以及 FTS 可用性和分词器元数据。当前语法见 Query Model。 RFC-0012 是已接受的决策记录；与已安装 CLI 不一致时以 CLI 为准。

2.6 `query`¶

pchronicle query [DATASET|--mount NAME=DATASET ...] (--sql SQL|--file FILE_OR_STDIN)
 [--format auto|table|jsonl|csv] [--output PATH_OR_STDOUT]
 [--max-output-rows N] [--max-output-bytes BYTES] [--timeout 30s]

pchronicle query ./dataset \
 --sql 'SELECT COUNT(*) AS runs FROM dataset.runs'
pchronicle query \
 --mount live=./live \
 --mount archive=@archive \
 --sql 'SELECT * FROM live.runs
 UNION ALL
 SELECT * FROM archive.runs'

--file 从文件读取 SQL，--file - 从 stdin 读取；--format、--output、输出上限和 --timeout 控制执行结果。一条命令只接受一条只读 statement，DDL、DML、COPY 和多语句会被拒绝。使用 --mount 后没有隐式 dataset schema，SQL 必须使用 mount 名。

2.7 `import`¶

pchronicle import -f|--from SOURCE -t|--to NEW_DATASET
 [-i|--input-format FORMAT] [-o|--output-format preserve|storyline|compact-jsonl]
 [--replace] [--append] [--on-duplicate suffix|skip] [--yes]
 [--resume] [--wal-dir DIR] [--reset]
 [--column NAME=JSON_PATH]... [--max-input-bytes BYTES]

pchronicle import \
 -f input.json -t ./imported -i atif
pchronicle import \
 -f ./corpus \
 -t s3://bucket/normalized \
 -o storyline
pchronicle import \
 -f more.json -t ./normalized --append --on-duplicate skip
pchronicle import \
 -f rebuilt.json -t ./normalized --replace --yes
pchronicle import \
 -f s3://bucket/corpus -t s3://bucket/out -o storyline --resume
pchronicle import \
 -f ./jsonl-root -t ./records.lance \
 -o compact-jsonl \
 --column id=$.event.id --column timestamp=$.event.time \
 --column model=$.payload.model

长参数分别是 --from、--to、--input-format 和 --output-format。短 option 始终只有一个字符，因此格式参数使用 -i 和 -o，而不是 -if 和 -of。文件和目录默认自动识别输入格式；stdin 必须显式指定 -i。preserve 保留文件边界和相对路径，storyline 合并为 normalized Store；对象存储目标必须使用 storyline。

长时间 Storyline import 会在 ./.pchronicle-import-wal/<job_id>/ 写入本地 checkpoint WAL （job.json、done.jsonl、failed.jsonl）。同一 --from/--to 指纹下使用 --resume 可跳过已标记 done/failed 的源；--wal-dir 覆盖 WAL 根目录；--reset 会先删除该 job 的 WAL。 decode 与可跳过的 commit 失败会写入 WAL 与 import.log，进程继续处理其余源。

Format	Import	Export
`atif`	是	是
`actf`	是	是
`openai-messages`	是	是
`storyline`	是	是
`codex`	是	否
`claude-code`	是	否
`compact-jsonl`	是	是

Codex 和 Claude Code session 是 decode-only 输入格式。默认创建要求目标不存在。--append 要求目标是已有 Storyline Dataset；重复 document_id 默认增加 #N 后缀，也可用 --on-duplicate skip 跳过。--replace 会先将完整导入写入临时路径，再将旧本地 Dataset rename 到备份路径、将新 Dataset rename 到正式路径，确认新路径发布后才删除备份；因此必须交互确认或传入 --yes。对象存储 Dataset 的 replace 会先清空目标前缀再写入（非原子）。

Compact JSONL 是记录存储，不会转换或推断轨迹语义。指定 --input-format compact-jsonl 或 --output-format compact-jsonl 均会选择该格式。输入必须是本地 .json、.jsonl 或 .ndjson 文件或目录树；JSON object 和 array 都会被接受，每个 JSON 文档会成为一条 record，数组会完整保留。缺失或无效的 id 和 timestamp 会获得稳定的 source_filename#line_number 值，默认路径分别为 $.id 和 $.timestamp。--column id=PATH 与 --column timestamp=PATH 用于覆盖默认路径，其他 --column NAME=PATH 会增加 nullable JSONB 投影列。Compact import 支持本地 create 和经确认的 replace，不支持 stdin、对象存储目标或 append。

2.8 `sync`¶

pchronicle sync --from DIRECTORY
 [--mirror DIRECTORY] [--to DIRECTORY]
 [--input-format FORMAT] [--suggested-format FORMAT]
 [--column NAME=JSON_PATH]...
 [--interval DURATION] [--once]

sync 是常驻轮询器：监听源目录下的 .json、.jsonl 和 .ndjson，将变更合并到 pending 池，并按 --interval 做整树 snapshot 重建。--mirror 与 --to 至少提供一个，也可同时提供：

--mirror：把源树按 Compact JSONL 规则写入 Compact Lance Dataset（record-level；可用 --column）。每个成功批次原子替换该目标。
--to：把源轨迹转换为 Storyline Lance Dataset（可用 --input-format / --suggested-format）。

一个批次内启用的目标全部成功后才清理 pending；失败会保留变更并指数退避重试。--once 只执行一次初始批次后退出。本地目标必须位于源目录之外。

若 --input-format compact-jsonl，只能配合 --mirror（不能与 --to 同用）：每个成功批次重新扫描整个目录，并原子替换 --mirror 指向的 Compact Lance 快照。

2.9 `drop`¶

pchronicle drop DATASET [--yes]

drop 永久删除本地 Dataset 目录或对象存储前缀。默认要求交互确认，--yes 可跳过确认；命令会拒绝删除文件系统根目录或整个对象存储 bucket。

2.10 `export`¶

pchronicle export -f|--from DATASET -t|--to TARGET -o|--output-format FORMAT
 [--source PATH] [--run-id ID|--document-id ID|--session-id ID] [--where EXPRESSION]
 [--strict] [--overwrite] [--max-trajectories N] [--max-output-bytes BYTES] [--timeout 30s]

pchronicle export \
 -f ./imported -t restored.json -o atif
pchronicle export \
 -f ./imported \
 -t - -o actf --session-id session-42 --strict

长参数分别是 --from、--to 和 --output-format。过滤条件包括 --source、--run-id、 --document-id、--session-id 和 --where；--to - 直接写 stdout。--strict 要求转换保留原始 exchange document，失败时不产生部分输出。文件和对象存储输出默认 create-only，只有显式 --overwrite 才允许原子替换。

导出 Compact JSONL 时使用 --output-format compact-jsonl，目标必须是本地目录，且不支持 --source、ID 过滤或 --where，以保持原始 JSONL 文件的目录边界与字节内容。

2.11 `agent`¶

pchronicle agent <codex|claude> [DATASET]
 [--ask QUESTION|--ask-file FILE_OR_STDIN] [--no-overview] [--dry-run]

pchronicle agent codex ./dataset
pchronicle agent claude @prod --ask '比较模型延迟'

默认先执行有界 status 和紧凑的 stats overview，再进入提问；--no-overview 只跳过 overview。问题也可以通过 --ask-file 从文件或 stdin 读取，--dry-run 用于预览启动内容。 Agent 注入是行为引导，不是 filesystem、network 或 tool permission 沙箱。

2.12 `serve`¶

pchronicle serve ./trajectory-data
pchronicle serve --listen 127.0.0.1:8080 train=./train eval=./eval
pchronicle serve --catalog-config catalog.toml --listen 127.0.0.1:8081

监听地址只允许 loopback。命名挂载提供稳定的 SQL 别名。 --open 打开 Web UI，--home-link TEXT=PATH 增加同源导航链接。 --catalog-config 启用 Directory 和数据操作认证，不能与位置参数挂载同时使用。通过 pchronicle serve catalog 配置 Dataset 和用户授权，存储凭证按后端与 worker 隔离。启动就绪 JSON 包含 warehouse_endpoint。

刷新先构建新 Snapshot 再切换读者，失败时保留旧视图。数据写入使用 CLI import。日志写入 stderr，--log-level 控制详细程度。失败 API 响应包含 code、message 和 request_id，内部错误细节保留在服务日志。

Catalog 管理¶

Directory ACL 文件包含用户、datasets（libraries）和 grants。配置文件不存在时，管理命令会自动创建。

pchronicle serve catalog issue --catalog-config FILE NAME
pchronicle serve catalog grant --catalog-config FILE NAME DATASET...
pchronicle serve catalog revoke --catalog-config FILE NAME DATASET...
pchronicle serve catalog dataset add --catalog-config FILE NAME --uri URI
 [--endpoint URL] [--region REGION] [--access-key KEY] [--secret-key KEY]
pchronicle serve catalog dataset remove --catalog-config FILE NAME...
pchronicle serve catalog dataset list --catalog-config FILE

issue 生成用户 AK/SK 并只显示一次 secret；dataset add 只登记 URI 与可选后端存储凭据，不创建或删除对象存储数据；grant/revoke 增减该用户可打开的 library 名称（v1 是库成员关系，不是细粒度 --permission 标志）。

公共输出与退出状态¶

stdout 只包含命令结果、导出内容或 readiness JSON；stderr 包含 Dataset 版本 metadata、warning、进度和错误。--log-level error 可以关闭成功诊断，但不会改变 stdout 或退出码。

auto 在 TTY 中为 dataset list、list/ls、stats、find 选择 table，为 query、stats reports 选择 table；相同命令在 pipe 中分别选择 JSON 和 JSONL。脚本中建议显式指定格式。

Exit code	含义
0	命令按所选 error policy 完成
1	未分类内部错误
2	参数、输入或操作不合法
3	配置、Dataset、数据项或实体不存在
4	create-only 目标或身份冲突
5	行数、字节数、文件数或队列资源超限
6	timeout 或外部依赖暂时不可用

错误第一行带稳定 code，例如 error[invalid_request]: --timeout must be greater than zero。 --log-level debug 会增加脱敏后的原因链。颜色根据 TTY 和 NO_COLOR 自动决定，机器格式不含 ANSI。

3. Examples¶

从本地文件开始¶

pchronicle dataset pin local ./trajectory-data
pchronicle dataset pin default @local

pchronicle import \
 -f ./training.json \
 -t ./trajectory-data/training \
 -i openai-messages

pchronicle list
pchronicle stats
pchronicle stats overview

比较线上和归档 Dataset¶

pchronicle dataset pin live s3://bucket/live
pchronicle dataset pin archive s3://bucket/archive

pchronicle query \
 --mount live=@live \
 --mount archive=@archive \
 --sql 'SELECT model_name, COUNT(*) AS steps
 FROM (
 SELECT model_name FROM live.steps
 UNION ALL
 SELECT model_name FROM archive.steps
 )
 GROUP BY model_name
 ORDER BY steps DESC'

找到并严格导出一条 Run¶

pchronicle find @prod --session-id session-42 --format json

pchronicle export \
 -f @prod \
 -t session-42.actf.json \
 -o actf \
 --source nested/source.json \
 --session-id session-42 \
 --strict

在 CI 中使用¶

pchronicle \
 -c ./ci-config.toml \
 --log-level error \
 status ./fixtures \
 --format json > status.json

pchronicle \
 -c ./ci-config.toml \
 --log-level error \
 query ./fixtures \
 --file checks.sql \
 --format jsonl > checks.jsonl

定位后再写 SQL 见发现并查询，交换见导入与导出，只读服务见本地服务 Dataset。 Snapshot 构造见 Snapshot 设计。

请求执行诊断¶

Requests 标签页展示当前浏览器标签页会话中的近期 API 请求的 request ID、HTTP 结果、执行阶段和耗时。左下角 Local / profile 上方的状态提示可打开该页。选择请求或输入 request ID，即可在请求尚未结束时查看进度。Worker 排队、启动和执行分别计时；目录浏览与 Runs 查询报告各自的执行阶段。pending 表示尚未开始，skipped 表示未使用该阶段。阶段描述应用操作，并非逐条 DNS、TCP 或 S3 请求。目录返回 200 但仍在后台刷新时，会显示相应提示。

GET /api/requests/{request_id}（也支持 /api/v1）返回实时快照： request_id、method、path、state、elapsed_ms、status、error、note、 phases（name、state、elapsed_ms），以及可选的嵌套 worker 快照。该接口由前置服务直接处理，不等待业务 worker。

追踪需要显式开启：原请求和诊断查询必须携带同一个随机生成的 32 位十六进制 x-pchronicle-observer 请求头；原请求可通过 x-request-id 指定 ID，以便完成前查询。 UI 自动生成这两个请求头。Observer token 是私有查询凭证，不替代 catalog 身份认证，其他 token 无法访问该记录。服务端最多保留 512 条记录、最长 10 分钟，仅保存在内存中，重启即清空。记录不存在、过期或无权访问时均返回 404。UI 保留最近 40 条，每秒查询未完成请求；诊断连接失败会单独提示，可手动重试。记录不包含查询参数、请求体或凭据；内部错误详情仍需通过 request ID 在服务端日志中定位。