【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载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准备查询每个任务先加载一次命令契约clb manifest仅在目标会话未知时才列出会话clb sessions list --format json会话、成员、时间范围优先复用对话中已确认的信息只有候选结果与上下文无法消歧时才向用户提问先用专用命令优先选择能直接回答问题的简单命令——消息文本用--format agent结构侦察会话、成员、计数、--no-content搜索用--format json按需加深首轮结果不足时才追加messages context、stats keywords等命令meta.hasMore为真时用--cursor meta.nextCursor续页问题得到回答就立即停止部分覆盖的情况要如实披露而不是把一页当成完整数据集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/memberssessions list列出已导入的会话是 Agent 定位目标的第一步sessions show查看单个会话详情members list列出会话成员members history查看成员昵称变更历史用于追踪改名成员。单会话免选如果本地只有一个导入会话--session可以省略命令自动选中该会话存在多个会话时命令会返回候选列表要求消歧对应错误码 4 的场景见下文语义退出码。消息查询messagesmessages 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上限 2000messages context --id id围绕指定消息 id 展示上下文--id支持逗号分隔的多个 id--window默认 10上限 100传入不存在的 id 会返回MESSAGE_NOT_FOUNDmessages between两个成员之间的完整对话--member必须恰好出现两次例如--member me --member 小红默认每页 50 条上限 500。统计statsstats 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/manifesttopics list列出 AI 分段摘要支持--query kw按子串过滤摘要默认返回 20 条上限 100摘要本身是脱敏后的派生文本topics show --id id查看某一段的原始消息--id来自topics list的段 id默认返回 200 条上限 500sql SELECT ...只读 SQL 回退仅接受 SELECT/WITH 语句默认最多 100 行上限 1000字符串单元格自动脱敏、命中黑名单的行整行剔除schema输出会话数据库的表结构供sql语句参考manifest机器可读的命令清单由 commander 注册信息自动生成见 apps/cli/src/query/manifest.ts一次调用即可替代 N 次--help探测。三种输出格式与统一的响应协议所有查询命令都接受--format参数显式指定有三种取值格式适用对象内容形态agentAI Agent推荐JSON 信封body 为紧凑文本经完整预处理管线生成清洗、黑名单、去噪、连续消息合并、脱敏、token 感知截断单条消息用[#id]/[#id*]标记合并区间如[#a-b]仅作展示json程序化解析结构化消息条目应用隐私步骤清洗、黑名单、脱敏但不合并、不去噪适合配合--no-content/--fields做结构侦察text人类阅读终端TTY下的默认格式输出可读文本格式的默认选择逻辑在 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 可以据此决定下一步动作退出码含义0成功2无效参数或能力被禁用含无效游标、--raw未开启等3资源不存在会话/成员/消息/分段4引用有歧义错误体携带candidates5SQL 错误映射实现在 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 与内容预算针对消息内容较多的场景提供四层预算控制参数作用默认值上限--limit主要对象数量命中/消息/行各命令不同搜索 20、列表 50、SQL 100 等各命令不同500/1000 等--max-messages上下文展开后的总消息数上限2002000--max-tokensagent 文本的 token 预算400032000--max-chars单条消息内容的字符截断按命令搜索默认 12010000--full可以关闭单条消息的内容截断。当上下文展开超出--max-messages预算时命令会优先保留命中消息并给出 warningsapps/cli/src/query/commands-messages.ts而不是静默丢数据。隐私边界默认脱敏的只读设计这是clb查询体系最核心的安全设计所有查询命令默认应用你的 ChatLab 脱敏规则与黑名单覆盖范围包括stats keywords的高频词词表先按消息级黑名单过滤再对词表应用脱敏规则过取再剪保证过滤后 Top-N 不会缺位见 apps/cli/src/query/commands-stats.tstopics 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_RAW1后才生效即便开启--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列需要显式--rawassertSqlPrivacyAllowed会静态分析 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目录下的全部源码与配套测试文件。赞分享【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载相关推荐用外部 AI Agent 安全分析本地聊天记录ChatLab clb 只读查询 CLI 全指南用外部 AI Agent 安全分析本地聊天记录ChatLab clb 只读查询 CLI 全指南 ChatLab 提供了一条专为 AI Agent如 CodeChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录ChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录 ChatLab 提供一套面向 AI Agent 与命令行用户设计数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能本地部署ChatLab chatlab-analyze 技能实战用只读 clb CLI 让 AI Agent 查询与分析本地聊天记录ChatLab chatlab analyze 技能实战用只读 clb CLI 让 AI Agent 查询与分析本地聊天记录 ChatLab 是一个本地优先的上一篇pi-subagents 代理管理生命周期管理与资源调度的完整指南下一篇react-pdf 实现 PDF/A 归档输出深入解析 Document 的 conformance prop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ChatLab CLI 只读查询全指南：用 clb 命令让外部 AI Agent 安全分析本地聊天记录
【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载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准备查询每个任务先加载一次命令契约clb manifest仅在目标会话未知时才列出会话clb sessions list --format json会话、成员、时间范围优先复用对话中已确认的信息只有候选结果与上下文无法消歧时才向用户提问先用专用命令优先选择能直接回答问题的简单命令——消息文本用--format agent结构侦察会话、成员、计数、--no-content搜索用--format json按需加深首轮结果不足时才追加messages context、stats keywords等命令meta.hasMore为真时用--cursor meta.nextCursor续页问题得到回答就立即停止部分覆盖的情况要如实披露而不是把一页当成完整数据集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/memberssessions list列出已导入的会话是 Agent 定位目标的第一步sessions show查看单个会话详情members list列出会话成员members history查看成员昵称变更历史用于追踪改名成员。单会话免选如果本地只有一个导入会话--session可以省略命令自动选中该会话存在多个会话时命令会返回候选列表要求消歧对应错误码 4 的场景见下文语义退出码。消息查询messagesmessages 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上限 2000messages context --id id围绕指定消息 id 展示上下文--id支持逗号分隔的多个 id--window默认 10上限 100传入不存在的 id 会返回MESSAGE_NOT_FOUNDmessages between两个成员之间的完整对话--member必须恰好出现两次例如--member me --member 小红默认每页 50 条上限 500。统计statsstats 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/manifesttopics list列出 AI 分段摘要支持--query kw按子串过滤摘要默认返回 20 条上限 100摘要本身是脱敏后的派生文本topics show --id id查看某一段的原始消息--id来自topics list的段 id默认返回 200 条上限 500sql SELECT ...只读 SQL 回退仅接受 SELECT/WITH 语句默认最多 100 行上限 1000字符串单元格自动脱敏、命中黑名单的行整行剔除schema输出会话数据库的表结构供sql语句参考manifest机器可读的命令清单由 commander 注册信息自动生成见 apps/cli/src/query/manifest.ts一次调用即可替代 N 次--help探测。三种输出格式与统一的响应协议所有查询命令都接受--format参数显式指定有三种取值格式适用对象内容形态agentAI Agent推荐JSON 信封body 为紧凑文本经完整预处理管线生成清洗、黑名单、去噪、连续消息合并、脱敏、token 感知截断单条消息用[#id]/[#id*]标记合并区间如[#a-b]仅作展示json程序化解析结构化消息条目应用隐私步骤清洗、黑名单、脱敏但不合并、不去噪适合配合--no-content/--fields做结构侦察text人类阅读终端TTY下的默认格式输出可读文本格式的默认选择逻辑在 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 可以据此决定下一步动作退出码含义0成功2无效参数或能力被禁用含无效游标、--raw未开启等3资源不存在会话/成员/消息/分段4引用有歧义错误体携带candidates5SQL 错误映射实现在 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 与内容预算针对消息内容较多的场景提供四层预算控制参数作用默认值上限--limit主要对象数量命中/消息/行各命令不同搜索 20、列表 50、SQL 100 等各命令不同500/1000 等--max-messages上下文展开后的总消息数上限2002000--max-tokensagent 文本的 token 预算400032000--max-chars单条消息内容的字符截断按命令搜索默认 12010000--full可以关闭单条消息的内容截断。当上下文展开超出--max-messages预算时命令会优先保留命中消息并给出 warningsapps/cli/src/query/commands-messages.ts而不是静默丢数据。隐私边界默认脱敏的只读设计这是clb查询体系最核心的安全设计所有查询命令默认应用你的 ChatLab 脱敏规则与黑名单覆盖范围包括stats keywords的高频词词表先按消息级黑名单过滤再对词表应用脱敏规则过取再剪保证过滤后 Top-N 不会缺位见 apps/cli/src/query/commands-stats.tstopics 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_RAW1后才生效即便开启--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列需要显式--rawassertSqlPrivacyAllowed会静态分析 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目录下的全部源码与配套测试文件。赞分享【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载相关推荐用外部 AI Agent 安全分析本地聊天记录ChatLab clb 只读查询 CLI 全指南用外部 AI Agent 安全分析本地聊天记录ChatLab clb 只读查询 CLI 全指南 ChatLab 提供了一条专为 AI Agent如 CodeChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录ChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录 ChatLab 提供一套面向 AI Agent 与命令行用户设计数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能本地部署ChatLab chatlab-analyze 技能实战用只读 clb CLI 让 AI Agent 查询与分析本地聊天记录ChatLab chatlab analyze 技能实战用只读 clb CLI 让 AI Agent 查询与分析本地聊天记录 ChatLab 是一个本地优先的上一篇pi-subagents 代理管理生命周期管理与资源调度的完整指南下一篇react-pdf 实现 PDF/A 归档输出深入解析 Document 的 conformance prop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考