From 7067c3f1c8b277e2c19baff57119cca44663c305 Mon Sep 17 00:00:00 2001 From: digua Date: Tue, 14 Jul 2026 18:34:59 +0800 Subject: [PATCH] feat(skills): add localized import and analysis workflows --- docs/cn/usage/cli-query.md | 8 +- docs/cn/usage/how-to-import.md | 66 ++++++++-- docs/en/usage/cli-query.md | 2 + docs/en/usage/how-to-import.md | 68 +++++++++-- docs/tw/usage/how-to-import.md | 66 ++++++++-- skills/chatlab-analyze-cn/SKILL.md | 77 ++++++++++++ skills/chatlab-analyze-cn/agents/openai.yaml | 4 + skills/chatlab-analyze/SKILL.md | 119 ++++++------------- skills/chatlab-analyze/agents/openai.yaml | 4 + skills/chatlab-import-cn/SKILL.md | 67 +++++++++++ skills/chatlab-import-cn/agents/openai.yaml | 4 + skills/chatlab-import/SKILL.md | 66 ++++++++++ skills/chatlab-import/agents/openai.yaml | 4 + 13 files changed, 445 insertions(+), 110 deletions(-) create mode 100644 skills/chatlab-analyze-cn/SKILL.md create mode 100644 skills/chatlab-analyze-cn/agents/openai.yaml create mode 100644 skills/chatlab-analyze/agents/openai.yaml create mode 100644 skills/chatlab-import-cn/SKILL.md create mode 100644 skills/chatlab-import-cn/agents/openai.yaml create mode 100644 skills/chatlab-import/SKILL.md create mode 100644 skills/chatlab-import/agents/openai.yaml diff --git a/docs/cn/usage/cli-query.md b/docs/cn/usage/cli-query.md index 63b486db..b94ce463 100644 --- a/docs/cn/usage/cli-query.md +++ b/docs/cn/usage/cli-query.md @@ -79,20 +79,22 @@ agent/json 模式下 stdout 只包含一个 JSON 响应信封，日志一律走 ## 给 Agent 的使用指南 -推荐通过通用 Agent Skills CLI 安装官方 `chatlab-analyze` 技能： +推荐通过通用 Agent Skills CLI 安装官方中文 `chatlab-analyze-cn` 技能： ```bash -npx skills add ChatLab/ChatLab --skill chatlab-analyze -g +npx skills add ChatLab/ChatLab --skill chatlab-analyze-cn -g ``` 安装后，可以在 Codex、Claude Code、Cursor 等外部 Agent 中直接说： ```text -chatlab-analyze 帮我分析我和小红的聊天记录 +chatlab-analyze-cn 帮我分析我和小红的聊天记录 ``` 这个技能会引导 Agent 先执行 `chatlab manifest` 获取机读命令清单，再用安全的 `--format agent/json` 查询聊天记录。 +`chatlab-analyze-cn` 始终只读。如果你希望 Agent 导入新的聊天导出文件，请改用独立的 `chatlab-import-cn` Skill；它会先预览导入计划，再自动新建或增量导入，详见[导入聊天记录指南](./how-to-import.md)。 + 典型配方——"谁最早提到某个问题？查看现场"： ```bash diff --git a/docs/cn/usage/how-to-import.md b/docs/cn/usage/how-to-import.md index 6b3fdbc8..e716d162 100644 --- a/docs/cn/usage/how-to-import.md +++ b/docs/cn/usage/how-to-import.md @@ -4,15 +4,67 @@ outline: deep # 导入聊天记录指南 -完成导出后，您只需在 ChatLab 的首页： +ChatLab 支持多种方式导入聊天记录。 -1. 将导出的**数据文件**直接拖入上传区域。 -2. 等待 ChatLab 解析完成即可。 +## 桌面端：在首页拖入文件 -## BUG 排查 +这是最简单的导入方式： -如果导入失败，可以通过日志快速排查问题： +1. 将聊天平台导出的**数据文件**拖入首页上传区域。 +2. 等待解析和导入完成。 -软件左下角「设置」 > 「基础设置」 > 「日志文件」，打开该目录，该目录下有个「import」目录，就是所有导入的日志记录了。 +首页同时支持增量导入，如果新文件与已导入会话能匹配，ChatLab 会增量补充新的消息。 -如果您看不懂，可以通过 Github issue 提交问题。 +## Agent：使用 AI Skill 导入 + +适合已经使用 Codex、Claude Code 等各类 AI Agent，希望让 Agent 代为执行导入的用户。 + +需要 Node.js 20 或更高版本。安装 ChatLab CLI 和中文 Skill： + +```bash +npm install -g chatlab-cli +npx skills add ChatLab/ChatLab --skill chatlab-import-cn -g +``` + +然后直接告诉 Agent： + +```text +chatlab-import-cn 帮我把 /absolute/path/to/chat-export.json 导入 ChatLab +``` + +Agent 会先在后台预览，预览成功后自动新建或增量导入，无需再次确认。 + +## 终端：使用命令行导入 + +安装 ChatLab CLI： + +```bash +npm install -g chatlab-cli +``` + +最简单的用法是直接导入一个文件： + +```bash +chatlab import "/absolute/path/to/chat-export.json" +``` + +### 指定已有会话 + +需要明确追加到某个会话时，使用 `--session-id`： + +```bash +chatlab import "/absolute/path/to/chat-export.json" --session-id +``` + +## 自动化：使用 API 或自动同步 + +这是适合长期集成的进阶方式。首页的「API 导入」提供两个方向： + +- **自动同步（Pull）**：ChatLab 定时从已配置的数据源拉取新增聊天记录，详见 [Pull 远程数据源协议](/cn/standard/chatlab-pull)。 +- **API 推送（Push）**：第三方工具、插件或脚本通过 ChatLab 本地 API 主动写入聊天记录，详见 [Push 导入协议](/cn/standard/chatlab-import)。 + +## 导入失败怎么办 + +在 ChatLab 左下角打开「设置」→「存储管理」→「日志文件」，然后查看其中的 `import` 目录。 + +命令行模式还可以根据 JSON 中的 `error.code` 和 `error.hint` 排查文件路径、格式、并发导入或会话 ID 问题。如果仍无法解决，可以携带脱敏后的错误信息提交 GitHub Issue。 diff --git a/docs/en/usage/cli-query.md b/docs/en/usage/cli-query.md index ded77eaa..69621d5b 100644 --- a/docs/en/usage/cli-query.md +++ b/docs/en/usage/cli-query.md @@ -93,6 +93,8 @@ chatlab-analyze help me analyze my chat history with Alice The skill tells the agent to run `chatlab manifest` first, then query chat records safely with explicit `--format agent/json` commands. +`chatlab-analyze` always remains read-only. To let an agent import a new chat export, use the separate `chatlab-import` skill; it previews the import, then automatically creates or incrementally updates a session. See the [Import Chat Records Guide](./how-to-import.md). + A typical recipe — "who mentioned this first? inspect the surrounding context": ```bash diff --git a/docs/en/usage/how-to-import.md b/docs/en/usage/how-to-import.md index be10f93b..a6c25601 100644 --- a/docs/en/usage/how-to-import.md +++ b/docs/en/usage/how-to-import.md @@ -2,17 +2,69 @@ outline: deep --- -# Import Chat Records Guide +# Import Chat Records -After completing the export, you simply need to: +ChatLab supports several ways to import chat records. -1. Drag the exported **data file** directly into the upload area on ChatLab's homepage. -2. Wait for ChatLab to finish parsing. +## Desktop: Drag a file into ChatLab -## Bug Troubleshooting +This is the simplest import path: -If the import fails, you can quickly troubleshoot the issue through logs: +1. Drag the chat platform's exported **data file** into the upload area on the homepage. +2. Wait for parsing and import to finish. -Go to "Settings" in the bottom left corner > "Basic Settings" > "Log Files", and open that directory. Inside, there's an "import" folder containing all import log records. +The homepage also supports incremental imports. When a new file matches an imported session, ChatLab adds the new messages. -If you can't understand the logs, you can submit an issue on GitHub. +## Agent: Import with an AI Skill + +Use this when you already work with Codex, Claude Code, or another AI agent and want the agent to handle the import for you. + +Node.js 20 or newer is required. Install ChatLab CLI and the English skill: + +```bash +npm install -g chatlab-cli +npx skills add ChatLab/ChatLab --skill chatlab-import -g +``` + +Then ask the agent: + +```text +chatlab-import import /absolute/path/to/chat-export.json into ChatLab +``` + +The agent previews the import in the background, then automatically creates or incrementally updates a session without asking for another confirmation. + +## Terminal: Import from the command line + +Install ChatLab CLI: + +```bash +npm install -g chatlab-cli +``` + +The simplest command imports one file directly: + +```bash +chatlab import "/absolute/path/to/chat-export.json" +``` + +### Target an existing session + +To append to a specific session, use `--session-id`: + +```bash +chatlab import "/absolute/path/to/chat-export.json" --session-id +``` + +## Automation: Use an API or automatic sync + +These advanced options are intended for ongoing integrations. The **API Import** section on the homepage provides two directions: + +- **Automatic Sync (Pull):** ChatLab periodically fetches new chat records from a configured data source. See the [Pull Remote Data Source Protocol](/standard/chatlab-pull). +- **API Push (Push):** a third-party tool, plugin, or script writes records through ChatLab's local API. See the [Push Import Protocol](/standard/chatlab-import). + +## If an import fails + +Open **Settings** → **Storage** → **Log Files** in ChatLab, then inspect the `import` directory. + +In command-line mode, the JSON `error.code` and `error.hint` fields can identify path, format, concurrent-import, or session-ID problems. If the issue remains, submit a GitHub Issue with desensitized error details. diff --git a/docs/tw/usage/how-to-import.md b/docs/tw/usage/how-to-import.md index 17674a63..41a473a3 100644 --- a/docs/tw/usage/how-to-import.md +++ b/docs/tw/usage/how-to-import.md @@ -4,15 +4,67 @@ outline: deep # 匯入聊天記錄指南 -完成匯出後，您只需在 ChatLab 的首頁： +ChatLab 支援多種方式匯入聊天記錄。 -1. 將匯出的**資料檔案**直接拖入上傳區域。 -2. 等待 ChatLab 解析完成即可。 +## 桌面端：在首頁拖入檔案 -## BUG 排查 +這是最簡單的匯入方式： -如果匯入失敗，可以透過日誌快速排查問題： +1. 將聊天平台匯出的**資料檔案**拖入首頁上傳區域。 +2. 等待解析和匯入完成。 -軟體左下角「設定」 > 「基礎設定」 > 「日誌檔案」，開啟該目錄，該目錄下有個「import」目錄，就是所有匯入的日誌記錄了。 +首頁同時支援增量匯入，如果新檔案與已匯入工作階段能配對，ChatLab 會增量補充新的訊息。 -如果您看不懂，可以透過 Github issue 提交問題。 +## Agent：使用 AI Skill 匯入 + +適合已經使用 Codex、Claude Code 等各類 AI Agent，希望讓 Agent 代為執行匯入的使用者。 + +需要 Node.js 20 或更高版本。安裝 ChatLab CLI 和中文 Skill： + +```bash +npm install -g chatlab-cli +npx skills add ChatLab/ChatLab --skill chatlab-import-cn -g +``` + +然後直接告訴 Agent： + +```text +chatlab-import-cn 幫我把 /absolute/path/to/chat-export.json 匯入 ChatLab +``` + +Agent 會先在背景預覽，預覽成功後自動建立或增量匯入，無需再次確認。 + +## 終端機：使用命令列匯入 + +安裝 ChatLab CLI： + +```bash +npm install -g chatlab-cli +``` + +最簡單的用法是直接匯入一個檔案： + +```bash +chatlab import "/absolute/path/to/chat-export.json" +``` + +### 指定現有工作階段 + +需要明確追加到某個工作階段時，使用 `--session-id`： + +```bash +chatlab import "/absolute/path/to/chat-export.json" --session-id +``` + +## 自動化：使用 API 或自動同步 + +這是適合長期整合的進階方式。首頁的「API 匯入」提供兩個方向： + +- **自動同步（Pull）**：ChatLab 定時從已設定的資料來源拉取新增聊天記錄，詳見 [Pull 遠端資料來源協議（簡體中文）](/cn/standard/chatlab-pull)。 +- **API 推送（Push）**：第三方工具、外掛程式或腳本透過 ChatLab 本機 API 主動寫入聊天記錄，詳見 [Push 匯入協議（簡體中文）](/cn/standard/chatlab-import)。 + +## 匯入失敗怎麼辦 + +在 ChatLab 左下角開啟「設定」→「儲存管理」→「日誌檔案」，然後查看其中的 `import` 目錄。 + +命令列模式還可以根據 JSON 中的 `error.code` 和 `error.hint` 排查檔案路徑、格式、並行匯入或工作階段 ID 問題。如果仍無法解決，可以攜帶脫敏後的錯誤資訊提交 GitHub Issue。 diff --git a/skills/chatlab-analyze-cn/SKILL.md b/skills/chatlab-analyze-cn/SKILL.md new file mode 100644 index 00000000..8bf2a8bb --- /dev/null +++ b/skills/chatlab-analyze-cn/SKILL.md @@ -0,0 +1,77 @@ +--- +name: chatlab-analyze-cn +description: 通过 chatlab CLI 分析本地 ChatLab 聊天记录。当用户要求外部 Agent 检查对话、查找证据、总结话题、比较成员，或基于已导入的 ChatLab 数据分析指定人物或群组关系时使用。 +--- + +# ChatLab 聊天分析 + +通过只读 `chatlab` CLI 查询和分析已经导入 ChatLab 的聊天记录。 + +## 适用场景 + +- 查找某段对话，或确认谁最先提到某件事。 +- 总结近期话题，或分析与某个人的聊天关系。 +- 比较成员活跃度、关键词或回复规律。 + +如果要导入新的聊天导出文件，请使用 `chatlab-import-cn`。 + +安装命令： + +```bash +npx skills add ChatLab/ChatLab --skill chatlab-analyze-cn -g +``` + +## 工作流程 + +### 1. 准备查询 + +检查 CLI、读取当前命令契约并列出会话： + +```bash +chatlab --help +chatlab manifest +chatlab sessions list --format json +``` + +只有一个相关会话时直接使用；多个会话或成员都可能匹配时，让用户从返回的候选项中选择。 + +### 2. 从专用命令开始 + +先使用能直接回答问题的最简单命令： + +```bash +chatlab messages search "" --session --format agent +chatlab messages between --member me --member --session --last 90d --format agent +chatlab topics list --session --last 30d --format agent +``` + +读取消息文本时使用 `--format agent`；侦察会话、成员、数量和 `--no-content` 搜索等结构时使用 `--format json`。 + +### 3. 补充上下文或统计 + +只有第一步结果不足时再深入： + +```bash +chatlab messages context --id 1021 --session --window 10 --format agent +chatlab stats keywords --session --member --last 90d --top 20 --format json +``` + +当 `meta.hasMore` 为 true 时，保持相同查询条件并使用 `--cursor ` 继续。通过数量和 Token 参数只获取回答问题所需的上下文。 + +### 4. 最后才使用 SQL + +只有专用命令无法回答时，才使用只读 SQL： + +```bash +chatlab schema --session --format json +chatlab sql "SELECT COUNT(*) AS n FROM message" --session --format json +``` + +## 隐私与回答 + +- 绝不使用 `--raw`、修改 ChatLab 数据、导入文件、更改配置或启动长期运行的服务。 +- 绝不泄露完整聊天记录。ChatLab 的安全输出会应用用户配置的隐私预处理。 +- 使用 `[#1021]`、`[#1021*]` 或 `[#1021-1024]` 等可用标记引用消息证据。 +- 先直接回答，说明实际查询的会话和时间范围，再区分观察到的事实与解释。 +- 分析关系时不要过度推断情绪意图。仅在修正方式明确时遵循 `error.hint`。 +- 优先使用用户当前使用的中文变体回答，命令、参数、JSON 字段和证据标记保持原样。 diff --git a/skills/chatlab-analyze-cn/agents/openai.yaml b/skills/chatlab-analyze-cn/agents/openai.yaml new file mode 100644 index 00000000..cce7b004 --- /dev/null +++ b/skills/chatlab-analyze-cn/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: 'ChatLab 聊天分析' + short_description: '通过 ChatLab CLI 安全查询并分析本地聊天记录' + default_prompt: '使用 $chatlab-analyze-cn 分析我在 ChatLab 中的本地聊天记录。' diff --git a/skills/chatlab-analyze/SKILL.md b/skills/chatlab-analyze/SKILL.md index cc01eb8f..4d56c54d 100644 --- a/skills/chatlab-analyze/SKILL.md +++ b/skills/chatlab-analyze/SKILL.md @@ -5,13 +5,15 @@ description: Analyze local ChatLab chat records through the chatlab CLI. Use whe # ChatLab Analyze -Use this skill when the user asks you to analyze local ChatLab chat records, especially when they explicitly write `chatlab-analyze`, ask about a person or group in their chat history, or want evidence from imported conversations. +Query and analyze records already imported into ChatLab through the read-only `chatlab` CLI. -Example user request: +## Good Fit -```text -chatlab-analyze 帮我分析我和小红的聊天记录 -``` +- Find conversations or determine who mentioned something first. +- Summarize recent topics or inspect a named relationship. +- Compare member activity, keywords, or response patterns. + +For importing a new chat export, use `chatlab-import` instead. Install this skill with: @@ -19,109 +21,56 @@ Install this skill with: npx skills add ChatLab/ChatLab --skill chatlab-analyze -g ``` -## What ChatLab Provides +## Workflow -`chatlab` is a local CLI for querying chat records imported into ChatLab. Treat it as the source of truth for sessions, members, messages, statistics, topics, and read-only SQL fallback. +### 1. Prepare the Query -The CLI is read-only for this skill. Do not modify ChatLab data, import files, change config, or start long-running services unless the user explicitly asks. - -## First Steps - -1. Check that the CLI is available: +Check the CLI, load its current command contract, and list sessions: ```bash chatlab --help -``` - -2. Load the command contract before deeper work: - -```bash chatlab manifest -``` - -3. List sessions. If exactly one session is relevant, use it. If multiple sessions may match the user's wording, ask a short clarification or show the likely candidates. - -```bash chatlab sessions list --format json ``` -## Privacy Rules +Use the only relevant session. If multiple sessions or members match the request, ask the user to choose from the returned candidates. -- Always pass `--format` explicitly. -- Use `--format agent` when reading message bodies. -- Use `--format json` for structural scouting such as session lists, member lists, counts, fields, and `--no-content` searches. -- Do not use `--raw`. ChatLab disables raw output by default because the safe path applies the user's desensitization and blacklist rules. -- Do not reveal full chat dumps. Retrieve only the context needed for the user's question. -- Cite evidence with ChatLab message markers such as `[#1021]`, `[#1021*]`, or merged ranges like `[#1021-1024]` when available. +### 2. Start with a Dedicated Command -## Common Workflows - -### Analyze a One-To-One Relationship - -Use this when the user asks about themselves and another person, for example "我和小红". +Use the simplest command that directly answers the question: ```bash -chatlab members list --session --format json +chatlab messages search "" --session --format agent chatlab messages between --member me --member --session --last 90d --format agent -chatlab stats keywords --session --member me --last 90d --top 20 --format json +chatlab topics list --session --last 30d --format agent +``` + +Use `--format agent` for message text and `--format json` for structural scouting such as sessions, members, counts, and `--no-content` searches. + +### 3. Add Context or Statistics + +Only deepen the query when the first result is insufficient: + +```bash +chatlab messages context --id 1021 --session --window 10 --format agent chatlab stats keywords --session --member --last 90d --top 20 --format json ``` -Then answer with patterns, concrete examples, and limits. If the retrieved time range is narrow, say so and offer the next query you would run. +When `meta.hasMore` is true, continue with `--cursor ` and the same query conditions. Use limits and token controls to retrieve only the context needed. -### Find Who Mentioned Something First +### 4. Use SQL Only as a Fallback -```bash -chatlab messages search "" --session --sort asc --limit 5 --context 3 --format agent -chatlab messages context --id 1021 --session --window 10 --format agent -``` - -Use the earliest hit and its surrounding context as evidence. The `[#1021*]` marker identifies the matching message. - -### Summarize Recent Topics - -```bash -chatlab topics list --session --last 30d --format agent -chatlab stats keywords --session --last 30d --top 20 --format json -chatlab messages list --session --last 7d --limit 80 --max-tokens 3000 --format agent -``` - -Prefer topic summaries first. Use keywords and recent messages to verify or fill gaps. - -### Scout Before Pulling Message Bodies - -Use JSON scouting before retrieving many message bodies. - -```bash -chatlab messages search "" --session --since 2026-01-01 --no-content --limit 100 --format json -chatlab messages search "" --session --cursor --format agent -``` - -When `meta.hasMore` is true, continue with `--cursor ` using the same query conditions. - -### Read-Only SQL Fallback - -Only use SQL when dedicated commands cannot answer the question. +Use read-only SQL only when no dedicated command can answer the question: ```bash chatlab schema --session --format json chatlab sql "SELECT COUNT(*) AS n FROM message" --session --format json ``` -SQL output still goes through ChatLab's privacy preprocessing for string values. +## Privacy and Answers -## Answering Style - -- Start with the direct answer, then give evidence and caveats. -- Name the session and time range you actually queried. -- Separate observed facts from interpretation. -- For relationship analysis, avoid overclaiming emotional intent. Use language like "从这些记录看..." and ground claims in message evidence. -- If member names are ambiguous, stop and ask the user to choose from the candidate ids. -- If ChatLab returns an error envelope, follow `error.hint` and retry only when the correction is clear. - -## Useful Command Hints - -- Time supports ISO dates, `today`, `yesterday`, and `--last 30d`. -- Members can be ids, exact display names, aliases, or `me`. -- Pagination uses `meta.hasMore` and `meta.nextCursor`. -- Token controls: `--limit`, `--max-messages`, `--max-tokens`, and `--max-chars`. +- Never use `--raw`, modify ChatLab data, import files, change config, or start long-running services. +- Never reveal full chat dumps. ChatLab's safe output applies the user's privacy preprocessing. +- Cite available message evidence with markers such as `[#1021]`, `[#1021*]`, or `[#1021-1024]`. +- Start with the answer, name the queried session and time range, then separate observed facts from interpretation. +- Avoid overclaiming emotional intent in relationship analysis. Follow `error.hint` only when the correction is clear. diff --git a/skills/chatlab-analyze/agents/openai.yaml b/skills/chatlab-analyze/agents/openai.yaml new file mode 100644 index 00000000..1bd7f9f3 --- /dev/null +++ b/skills/chatlab-analyze/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: 'ChatLab Analyze' + short_description: 'Safely query and analyze local chats with ChatLab CLI' + default_prompt: 'Use $chatlab-analyze to analyze my local ChatLab chat records.' diff --git a/skills/chatlab-import-cn/SKILL.md b/skills/chatlab-import-cn/SKILL.md new file mode 100644 index 00000000..ecc8fdbc --- /dev/null +++ b/skills/chatlab-import-cn/SKILL.md @@ -0,0 +1,67 @@ +--- +name: chatlab-import-cn +description: 通过 chatlab CLI 安全预览并将本地聊天导出文件导入 ChatLab。当用户要求外部 Agent 从本地 QQ、微信、Telegram、WhatsApp、LINE、Discord、Instagram、Google Chat、ChatLab JSON/JSONL 或其他受支持的聊天导出文件执行首次导入、重新导入或增量更新时使用。 +--- + +# ChatLab 聊天导入 + +通过 `chatlab` CLI 导入本地聊天导出文件。始终先预览准确的写入计划。将用户明确提出的导入请求视为授权，预览成功后继续执行，不再请求二次确认。 + +## 适用场景 + +- 首次导入本地聊天导出文件。 +- 重新导入更新后的文件，只补充新增消息。 +- 让外部 Agent 安全处理格式识别和会话匹配。 + +如果只需分析 ChatLab 中已有的聊天记录，请使用 `chatlab-analyze-cn`。 + +安装命令： + +```bash +npx skills add ChatLab/ChatLab --skill chatlab-import-cn -g +``` + +## 工作流程 + +1. 检查 CLI，并确认唯一、准确的文件路径： + +```bash +chatlab --help +``` + +如果 CLI 未安装，告诉用户运行 `npm install -g chatlab-cli`。未经批准不要自行安装软件。存在多个候选文件时不要猜测，每条命令中的路径都要加引号。 + +2. 只读预览导入计划： + +```bash +chatlab import "/absolute/path/to/chat-export.json" --dry-run --json +``` + +如果用户选择了已有会话，在预览和正式导入中都加入 `--session-id `。 + +3. 只总结新建或更新模式、目标会话 ID、扫描消息数、新增消息数、重复消息数，以及匹配方式或新建原因。不要引用消息正文。 + +4. 根据预览结果决定下一步： + +- 用户只要求预览或检查时，到此停止，不写入数据。 +- `importMode` 为 `incremental` 且 `newMessageCount` 为 `0` 时，告诉用户会话已经是最新状态，然后停止。 +- `importMode` 为 `incremental` 且存在新增消息时，无需再次确认，自动继续。 +- `importMode` 为 `created` 时，自动继续。如果 `createReason` 为 `ambiguous`，通过新建会话保护已有会话，并在最终结果中说明原因。 +- 结果不足以确定安全操作时，停止并说明缺少的信息。 + +5. 根据上一步可以写入时，使用相同文件、目标和格式移除 `--dry-run`： + +```bash +chatlab import "/absolute/path/to/chat-export.json" --json +``` + +根据最终 JSON 信封报告结果会话 ID、导入模式、新增消息数和重复消息数。 + +## 安全边界 + +- 绝不跳过预览、直接编辑 ChatLab 数据库、删除或合并会话。 +- 绝不泄露完整聊天导出文件或消息正文。 +- 绝不编造文件路径、解析格式或会话 ID。 +- 仅在修正方式明确时遵循 `error.hint`。 +- `FILE_NOT_FOUND` 要求正确路径；`UNRECOGNIZED_FORMAT` 查看 `chatlab formats`；`IMPORT_IN_PROGRESS` 稍后重试；`INVALID_SESSION_ID` 要求有效 ID。 +- 优先使用用户当前使用的中文变体回答，命令、参数、JSON 字段和错误码保持原样。 diff --git a/skills/chatlab-import-cn/agents/openai.yaml b/skills/chatlab-import-cn/agents/openai.yaml new file mode 100644 index 00000000..60b92473 --- /dev/null +++ b/skills/chatlab-import-cn/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: 'ChatLab 聊天导入' + short_description: '通过 ChatLab CLI 安全预览并导入本地聊天记录' + default_prompt: '使用 $chatlab-import-cn 安全预览并将这个聊天导出文件导入 ChatLab。' diff --git a/skills/chatlab-import/SKILL.md b/skills/chatlab-import/SKILL.md new file mode 100644 index 00000000..f3778f6f --- /dev/null +++ b/skills/chatlab-import/SKILL.md @@ -0,0 +1,66 @@ +--- +name: chatlab-import +description: Safely preview and import local chat export files into ChatLab through the chatlab CLI. Use when a user asks an external agent to import, re-import, or incrementally update ChatLab from a local QQ, WeChat, Telegram, WhatsApp, LINE, Discord, Instagram, Google Chat, ChatLab JSON/JSONL, or other supported chat export. +--- + +# ChatLab Import + +Import local chat exports through the `chatlab` CLI. Always preview the exact write. Treat an explicit request to import as authorization to continue after a successful preview; do not ask for a second confirmation. + +## Good Fit + +- Import a local chat export for the first time. +- Re-import a newer export and add only new messages. +- Let an external agent handle file detection and session matching safely. + +For read-only analysis of records already in ChatLab, use `chatlab-analyze` instead. + +Install this skill with: + +```bash +npx skills add ChatLab/ChatLab --skill chatlab-import -g +``` + +## Workflow + +1. Check the CLI and resolve one exact file path: + +```bash +chatlab --help +``` + +If the CLI is missing, tell the user to install it with `npm install -g chatlab-cli`. Do not install software without approval. Do not guess between multiple files, and quote the path in every command. + +2. Preview the import without writing: + +```bash +chatlab import "/absolute/path/to/chat-export.json" --dry-run --json +``` + +If the user selected an existing session, include `--session-id ` in both preview and import. + +3. Summarize only the plan: create or update mode, target session ID, scanned messages, new messages, duplicates, and match method or create reason. Never quote message bodies. + +4. Decide from the preview: + +- If the user asked only to preview or inspect, stop without writing. +- If `importMode` is `incremental` and `newMessageCount` is `0`, report that the session is already up to date and stop. +- If `importMode` is `incremental` and there are new messages, continue automatically without another confirmation. +- If `importMode` is `created`, continue automatically. When `createReason` is `ambiguous`, preserve existing sessions by creating a new one and explain this choice in the final result. +- If the result does not identify a safe action, stop and explain what is missing. + +5. When the decision permits writing, run the same command without `--dry-run`, keeping the file, target, and format unchanged: + +```bash +chatlab import "/absolute/path/to/chat-export.json" --json +``` + +Report the resulting session ID, import mode, new-message count, and duplicate count from the final JSON envelope. + +## Guardrails + +- Never skip the preview, edit ChatLab databases directly, or delete or merge sessions. +- Never reveal a full chat export or message bodies. +- Never invent a file path, parser format, or session ID. +- Follow `error.hint` only when the correction is unambiguous. +- For `FILE_NOT_FOUND`, request the correct path. For `UNRECOGNIZED_FORMAT`, inspect `chatlab formats`. For `IMPORT_IN_PROGRESS`, retry later. For `INVALID_SESSION_ID`, request a valid ID. diff --git a/skills/chatlab-import/agents/openai.yaml b/skills/chatlab-import/agents/openai.yaml new file mode 100644 index 00000000..0b5309f7 --- /dev/null +++ b/skills/chatlab-import/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: 'ChatLab Import' + short_description: 'Preview and import chat exports with ChatLab CLI' + default_prompt: 'Use $chatlab-import to safely preview and import this chat export into ChatLab.'