ChatLab CLI 只读查询全指南：用 clb 命令让外部 AI Agent 安全分析本地聊天记录

ChatLab 提供了一套独立的clb命令行查询工具，让 Codex、Claude Code、Cursor、HermesAgent 等外部 AI Agent 可以在不打开桌面端或网页界面的前提下，直接对本机已导入的聊天记录进行只读检索与统计分析。本文以 ChatLab 官方的 external-agent 指南为主线，结合仓库内apps/cli/src/query的源码实现，完整讲解clb查询命令的安装、命令体系、三种输出格式、隐私边界与典型实战流程，读完即可让任何支持命令行工具的 Agent 安全、可控地"读懂"你的历史聊天。

适用范围与前置条件

clb查询能力面向的是已经导入 ChatLab 的聊天记录，而不是原始导出文件。因此在开始之前需要满足两个前提：

• Node.js 22.19 或更新版本：CLI 依赖较新的运行时能力，版本不足时无法保证行为正确；
• 聊天记录已导入 ChatLab：即会话数据已经进入本地数据库，查询命令才会命中数据。

安装 CLI 与分析技能只需两条命令：

npm install -g chatlab-cli npx skills add ChatLab/ChatLab --skill chatlab-analyze -g

其中chatlab-analyze技能是给 Agent 使用的"操作手册"，同一个技能文件支持多种语言——用你偏好的语言提问即可，技能会要求 Agent 按对话语言组织回答。

安装说明：chatlab-cli通过 npm 全局安装后提供clb可执行文件；技能文件通过npx skills add安装到 Agent 的技能目录。若 Agent 环境检测不到clb，技能会如实报告能力缺失，安装属于需要授权的一步，Agent 不会自行绕过。

快速上手：让外部 Agent 开始分析

安装完成后，在 Codex、Claude Code、Cursor 或其他外部 Agent 中输入：

chatlab-analyze help me analyze my chat history with Alice

技能会引导 Agent 执行一个受控的只读工作流：先运行clb manifest读取命令契约，再以显式--format agent/json的方式查询聊天记录，全程不会写入任何数据。技能规定的四步工作流如下（完整定义见 skills/chatlab-analyze/SKILL.md）：

1. 准备查询：每个任务先加载一次命令契约（clb manifest），仅在目标会话未知时才列出会话（clb sessions list --format json）；会话、成员、时间范围优先复用对话中已确认的信息，只有候选结果与上下文无法消歧时才向用户提问；
2. 先用专用命令：优先选择能直接回答问题的简单命令——消息文本用--format agent，结构侦察（会话、成员、计数、--no-content搜索）用--format json；
3. 按需加深：首轮结果不足时才追加messages context、stats keywords等命令；meta.hasMore为真时用--cursor <meta.nextCursor>续页，问题得到回答就立即停止，部分覆盖的情况要如实披露而不是把一页当成完整数据集；
4. SQL 仅作回退：没有任何专用命令能回答时才使用只读 SQL，且先用clb schema查看表结构。

chatlab-analyze永远保持只读。如果 Agent 需要导入一份新的聊天导出，应改用独立的chatlab-import技能：它先预览导入内容，再自动创建或增量更新会话，具体流程参见 Import Chat Records Guide。

命令总览：clb 的完整只读查询面

官方指南给出了完整的命令清单，覆盖会话、成员、消息、统计、主题摘要与 SQL 回退：

clb sessions list # List imported sessions clb sessions show # Session details clb members list # Session members clb members history # Member name history clb messages list # List messages in a time window clb messages search <keywords...> # Keyword search (multi-word, context, paging) clb messages context --id <id> # Messages around a specific id clb messages between # Conversation between two members clb stats overview # Session overview clb stats activity # Member activity ranking clb stats time --by day # Time distribution (hour/weekday/day/month) clb stats keywords # High-frequency words (privacy-filtered) clb stats response # Reply speed ranking clb topics list # AI segment summaries clb topics show --id <id> # Original messages of one segment clb sql "<SELECT ...>" # Read-only SQL fallback (strings desensitized) clb schema # Database schema clb manifest # Machine-readable command manifest for agents

这些命令在仓库中的注册实现位于 apps/cli/src/query/commands-messages.ts、apps/cli/src/query/commands-stats.ts 与 apps/cli/src/query/commands-topics-sql.ts，下面按组说明各自的能力与关键默认值。

会话与成员：sessions/members

• sessions list：列出已导入的会话，是 Agent 定位目标的第一步；
• sessions show：查看单个会话详情；
• members list：列出会话成员；
• members history：查看成员昵称变更历史（用于追踪改名成员）。

单会话免选：如果本地只有一个导入会话，--session可以省略，命令自动选中该会话；存在多个会话时，命令会返回候选列表要求消歧（对应错误码 4 的场景，见下文"语义退出码"）。

消息查询：messages

• messages list：在时间窗口内列出消息，默认每页 50 条（上限 500），按最近在前取页、渲染为时间正序；可用--member按发送者过滤；
• messages search <keywords...>：多关键词搜索，默认按 OR 连接（--match any），可用--match all改为 AND；--sort asc|desc控制命中排序（"谁最先说的"用asc），默认desc；--context <n>为每个命中补充前后 n 条上下文，默认 0；每页默认 20 条命中（上限 500）；上下文展开后的总消息数受--max-messages约束（默认 200，上限 2000）；
• messages context --id <id>：围绕指定消息 id 展示上下文，--id支持逗号分隔的多个 id，--window默认 10（上限 100）；传入不存在的 id 会返回MESSAGE_NOT_FOUND；
• messages between：两个成员之间的完整对话，--member必须恰好出现两次（例如--member me --member 小红），默认每页 50 条（上限 500）。

统计：stats

• stats overview：会话概览——总消息数、总成员数、首末消息时间、Top 成员、AI 摘要数；
• stats activity：成员活跃度排名，--top默认 10（上限 100），输出消息数与占比；
• stats time --by <unit>：时间分布，--by必填，支持hour | weekday | day | month四种分桶；
• stats keywords：高频词统计（经过隐私过滤），--top默认 20（上限 100），可用--member限定发送者；
• stats response：回复速度排名（回复间隔中位数），默认统计最近 30 天，--top默认 10（上限 100）。

主题摘要与 SQL 回退：topics/sql/schema/manifest

• topics list：列出 AI 分段摘要，支持--query <kw>按子串过滤摘要，默认返回 20 条（上限 100）；摘要本身是脱敏后的派生文本；
• topics show --id <id>：查看某一段的原始消息，--id来自topics list的段 id，默认返回 200 条（上限 500）；
• sql "<SELECT ...>"：只读 SQL 回退，仅接受 SELECT/WITH 语句，默认最多 100 行（上限 1000），字符串单元格自动脱敏、命中黑名单的行整行剔除；
• schema：输出会话数据库的表结构，供sql语句参考；
• manifest：机器可读的命令清单，由 commander 注册信息自动生成（见 apps/cli/src/query/manifest.ts），一次调用即可替代 N 次--help探测。

三种输出格式与统一的响应协议

所有查询命令都接受--format参数，显式指定有三种取值：

格式的默认选择逻辑在 apps/cli/src/query/runner.ts 中：显式传入--format时以显式值为准；未传时TTY 终端默认text，管道/重定向默认agent——这保证 Agent 通过子进程调用时拿到的是可解析的 JSON。无效格式名会抛出INVALID_ARGUMENT。

输出协议：在agent/json模式下，stdout 恰好只包含一个 JSON 信封，日志一律走 stderr。成功的响应结构如下（示例来自官方文档）：

{ "ok": true, "command": "messages.search", "data": { "text": "returned: 2\n\n--- 2026/6/1 ---\n[#1*] 09:00 Wang: how about a trip on May Day..." }, "meta": { "totalHits": 2, "returnedHits": 2, "hasMore": false, "preprocess": { "desensitized": true }, "apiVersion": 1 } }

失败的响应统一为{ "ok": false, "error": { "code", "message", "hint", "candidates" } }，其中candidates在歧义消解场景携带候选值。信封与错误码的构造逻辑见 apps/cli/src/query/envelope.ts。

语义退出码（Agent 可以据此决定下一步动作）：

映射实现在 apps/cli/src/query/envelope.ts：*_NOT_FOUND→ 3、*_AMBIGUOUS→ 4、SQL_ERROR→ 5、INVALID_ARGUMENT/CURSOR_INVALID/*_DISABLED→ 2，其余内部错误为 1。

常用查询参数详解

时间范围：--since/--until/--last

接受四种取值形态（解析实现见 apps/cli/src/query/parse.ts）：

• 纯日期：2026-06-01
• 日期加时间："2026-06-01 08:30"（引号包裹避免 shell 分词）
• 完整 ISO 8601（含时区偏移或 Z）
• 相对关键词：today、yesterday
• 相对窗口：--last 30d，单位支持h（小时）、d（天）、w（周），例如--last 90d

几个关键语义：

• 仅日期的--until包含整天：例如--until 2026-06-01会覆盖到当天最后一秒；
• --last与--since/--until互斥，同时给出会报INVALID_ARGUMENT；
• 解析后的绝对边界会回显在meta.timeRange中，Agent 可以据此自校验查询窗口。

成员引用：--member

--member接受三种引用形式：

• 成员 id（数字）
• 精确昵称/名称
• me（数据所有者本人）

名称存在歧义时，命令不会擅自猜测，而是返回候选 id 列表供消歧。

分页游标：--cursor

当meta.hasMore为true时，响应会附带meta.nextCursor，把它原样传给--cursor即可取下一页：

clb messages search 报销 --last 90d --limit 20 --format agent # meta.hasMore = true, meta.nextCursor = "..." clb messages search 报销 --last 90d --limit 20 --cursor <meta.nextCursor> --format agent

游标与产生它的查询条件强绑定：实现上会对会话、关键词、匹配模式、排序、时间边界、成员、黑名单等条件计算一个 sha256 指纹（截取 12 位）并编码进游标（apps/cli/src/query/parse.ts）；解码时若指纹不匹配，会抛出CURSOR_INVALID——游标不能跨查询复用。时间范围在分页过程中也会被冻结，避免"最近 n 天"这类相对窗口在翻页期间漂移。

Token 与内容预算

针对消息内容较多的场景，提供四层预算控制：

--full可以关闭单条消息的内容截断。当上下文展开超出--max-messages预算时，命令会优先保留命中消息并给出 warnings（apps/cli/src/query/commands-messages.ts），而不是静默丢数据。

隐私边界：默认脱敏的只读设计

这是clb查询体系最核心的安全设计：所有查询命令默认应用你的 ChatLab 脱敏规则与黑名单，覆盖范围包括：

• stats keywords的高频词词表（先按消息级黑名单过滤，再对词表应用脱敏规则，"过取再剪"保证过滤后 Top-N 不会缺位，见 apps/cli/src/query/commands-stats.ts）；
• topics list的 AI 摘要文本（命中黑名单的摘要整条剔除，剩余摘要再脱敏）；
• sql结果中的字符串单元格（逐单元格脱敏，命中黑名单的行整行丢弃并计入 warnings）。

脱敏规则来自用户的aiPreprocessConfig（存储在~/.chatlab/preferences.json），并在加载时按有效语言环境合并内置规则组（zh-CN / en-US / ja-JP / ko-KR），见 apps/cli/src/query/preprocess-config.ts。这意味着即使本地数据包含敏感信息，Agent 的查询输出也会被脱敏后才离开机器。

--raw逃生舱：默认关闭

• 默认情况下--raw（绕过预处理）是禁用的；
• 只有显式执行clb config set cli.allow_raw true或设置环境变量CHATLAB_CLI_ALLOW_RAW=1后才生效；
• 即便开启，--raw也不能与--format agent组合（见 apps/cli/src/query/messages-output.ts）——它是 json/text 下的调试通道；
• 未开启时使用--raw会返回RAW_DISABLED（退出码 2），提示语会告诉用户如何开启（apps/cli/src/query/context.ts）。

SQL 回退的双重防护

• sql命令本身默认启用，但可通过clb config set cli.allow_sql false关闭；关闭后调用返回SQL_DISABLED；
• 读取message表的content列需要显式--raw：assertSqlPrivacyAllowed会静态分析 SQL 语句，凡是投影包含content列或SELECT *且关联 message 表、而未带--raw的查询都会在执行前被拦截（apps/cli/src/query/commands-topics-sql.ts），这样 SQL 表达式就无法在净化器看到原始内容之前把正文编码出去。

实战示例：从关键词到上下文证据链

官方文档给出了一条典型的实战配方——"谁先提到这件事？看看前后文"：

# 1. 按时间升序搜索，找最早提到 "server migration" 的消息，带前后 3 条上下文 clb messages search "server migration" --sort asc --limit 5 --context 3 --format agent # 2. 从返回文本中取单条消息标记 [#1021*] 中的消息 id，深入查看该条消息前后 10 条 clb messages context --id 1021 --window 10 --format agent

结合技能工作流（skills/chatlab-analyze/SKILL.md），一个完整的"证据查找"会话大致是：

# 每次任务先加载命令契约 clb manifest # 目标会话未知时才列会话 clb sessions list --format json # 用最直接的专用命令作答 clb messages search "server migration" --session <session-id> --format agent clb messages between --member me --member Alice --session <session-id> --last 90d --format agent clb topics list --session <session-id> --last 30d --format agent # 首轮不足时加深：上下文 / 高频词 / 统计 clb messages context --id 1021 --session <session-id> --window 10 --format agent clb stats keywords --session <session-id> --member Alice --last 90d --top 20 --format json # 专用命令无法回答时才回退 SQL clb schema --session <session-id> --format json clb sql "SELECT COUNT(*) AS n FROM message" --session <session-id> --format json

回答规范上，技能要求 Agent：先给答案，并说明查询的会话与时间范围，再区分"观察到的事实"与"主观解读"；用[#1021]、[#1021*]或[#1021-1024]引用证据，但只有单个 id可以传给messages context --id，合并区间是展示性的；关系分析中不过度推测情感意图；只在纠错方向明确时才遵循error.hint。

从源码看查询执行管线

对理解整个系统有帮助的关键实现路径如下：

• 格式与信封：apps/cli/src/query/runner.ts 的resolveFormat决定格式，runQuery统一产出成功/失败信封；apps/cli/src/query/envelope.ts 定义了ok/command/data/meta/error契约与语义退出码，apiVersion常量表示协议版本；
• 查询上下文：apps/cli/src/query/context.ts 的createQueryContext每次查询都会启动运行时、解析目标会话、加载脱敏配置与分词词典目录（nlp），并读取cli.allow_raw/cli.allow_sql开关——这就是"隐私配置随每次查询生效"的实现基础；
• 预处理管线：apps/cli/src/query/messages-output.ts 的buildAgentText把消息送入共享的applyPreprocessingPipeline（清洗、黑名单、去噪、合并、脱敏、token 截断），并生成[#id]标记与meta.preprocess诊断；--verbose可展开更细的管线统计（输入条数、清洗数、黑名单剔除数、去噪数、合并数、命中的脱敏规则数）；
• 时间与游标解析：apps/cli/src/query/parse.ts 覆盖日期关键词、整日边界、--last互斥校验、游标指纹校验与时间快照冻结；
• 命令契约：apps/cli/src/query/manifest.ts 从 commander 注册信息生成机器可读清单，包含命令参数、选项、退出码映射与精心挑选的任务配方示例，避免 Agent 用 N 次--help探测命令面。

与 Import 技能的分工

clb查询命令解决的是"已导入数据的只读分析"；而把新的导出文件变成可查询的会话，属于 chatlab-import 技能的职责——它会先预览导入内容，再自动创建或增量更新会话，避免重复导入。官方文档建议：需要导入时遵循 How to Import 指南，分析时严格停留在只读命令面。二者配合，即构成"导入 → 分析"的完整闭环。

如果你希望进一步对照官方文档原文或深入代码，可以继续阅读 docs/en/ai/external-agent.md（本文对应文档的正式版本）以及apps/cli/src/query目录下的全部源码与配套测试文件。