Qoder Sync - Qoder 缓存数据库采集工具

一个用于采集和分析 Qoder 缓存数据库的 VS Code 插件，支持导出 JSON 和同步到公司数据库。

📑 目录

功能
安装
使用方法
- 快速开始
- 命令列表
VS Code 配置项
开发与打包
更新日志
常见问题
许可证

功能

🎯 核心功能

1. 数据采集

✅ 会话采集: 查询 chat_session 表中的所有会话信息
✅ 文件版本采集: 查询 chat_working_space_file 表中的所有文件版本
✅ 增量采集: 记录上次统计的结束时间,下次只采集新数据,避免重复
✅ 分批采集: 每批最多采集 50 条变更,分批发送,避免数据过大
✅ 版本对比: 对比同一文件不同版本的内容变更,识别新增和修改的代码行
✅ 状态识别: 根据 status 字段判断版本是否被接受(ACCEPTED/APPLIED/REJECTED 等)

2. 对话记录采集

✅ 双模式支持:
- 编辑器用户(editor): 从 state.vscdb 采集对话记录
- 插件用户(plugin): 从缓存目录和 chat_message 表采集对话记录
✅ 状态自动计算: 根据代码变更自动推断对话记录状态(ACCEPTED/PARTACCEPTED/REJECTED)
✅ 时间范围过滤: 只采集指定时间范围内的对话记录

3. 数据输出

✅ JSON 导出: 导出完整的 JSON 数据文件,包含会话、代码变更、对话记录
✅ API 同步: 自动调用后端 API 同步数据到公司数据库
✅ 分片上传: 数据过大时自动分片上传,避免请求失败
✅ 数据查看器: 内置 HTML 查看器,方便浏览采集数据

🔄 自动化功能

4. 定时任务

✅ 自动采集任务:
- 首次采集 7 天数据
- 之后每 30 分钟增量采集
- Cron 表达式可配置(默认 */30 * * * *)
✅ 持久化任务: 关闭/重启 VS Code 后自动恢复自动任务
✅ 启停控制: 手动启动/停止自动任务
✅ 间隔控制: 可设置最小执行间隔,避免频繁执行

5. 文件同步（规则/技能/智能体）

✅ 规则同步: 自动同步 .qoder/rules 文件夹下的规则文件
✅ 技能同步: 自动同步 .qoder/skills 文件夹下的技能文件
✅ 智能体同步: 自动同步 .qoder/agents 文件夹下的智能体文件
✅ 综合同步: 一键同步规则+技能+智能体，支持独立定时任务（默认每小时）
✅ 增量同步: 对比本地和远程文件,只同步有变化的文件
✅ 文件管理: 支持新增、更新、删除操作
✅ 定时同步: 单项与综合同步默认均为每小时执行一次(Cron: 0 * * * *)
✅ 版本控制: 通过 manifest.json 记录文件版本和时间戳
✅ 配置向导: 首次使用自动引导配置,包含数据授权、用户信息、数据库配置等
✅ 用户授权: 首次使用需同意数据采集,保护用户隐私
✅ 用户信息强制校验: 采集前必须配置用户类型和用户名（用户名仅校验非空）
✅ 数据库路径选择器: 支持自动检测或手动选择 .db 文件
✅ 连接测试: 支持数据库连接测试和 API 连接测试
✅ 日志导出: 导出完整日志,方便排查问题

6. DevOps 认证与 Token 管理

✅ 自动登录: 首次使用配置向导时自动完成 DevOps 登录
✅ Token 自动刷新: Token 失效或为空时自动重新登录
✅ 手动重新登录: 登录失败时弹出输入框引导重新输入凭证
✅ 凭证加密存储: 密码使用 AES 加密后存储
✅ 清除凭证: 支持手动清除 DevOps 凭证重新登录

7. 跨平台支持

✅ Windows: 自动检测 %APPDATA%\Qoder\SharedClientCache\cache\db\local.db
✅ macOS: 自动检测 ~/Library/Application Support/Qoder/SharedClientCache/cache/db/local.db
✅ Linux: 自动检测 ~/.config/Qoder/SharedClientCache/cache/db/local.db

📊 统计与监控

✅ 运行次数统计: 记录累计运行次数
✅ 状态查看: 查看自动任务状态、运行次数、首次采集状态等
✅ 状态重置: 支持重置采集状态(保留或删除 output.json)
✅ 详细日志: 所有操作都有详细日志输出到"Qoder Sync"通道
✅ 日志输出优化: 接口成功/失败等提示信息统一输出到日志通道，不再弹窗干扰

安装

npm install

使用方法

快速开始

方式一: 配置向导(首次使用推荐)

在 VS Code 中按 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS),输入:

Qoder: zk-tool-配置向导

配置向导将引导您完成:

📋 数据采集授权(首次使用必须先同意授权)
👤 用户信息配置(用户类型和用户名,采集前必须设置)
🔐 DevOps 登录(输入用户名密码自动获取 Token)
📁 数据库路径配置(自动检测或手动选择)
🔍 数据库连接测试
🔍 API 连接测试
🚀 自动采集任务启动

命令列表

在 VS Code 命令面板(Ctrl+Shift+P 或 Cmd+Shift+P)中可使用以下命令:

数据采集命令

命令	说明
`Qoder: zk-collect-立即采集`	立即执行一次数据采集
`Qoder: zk-collect-启动自动采集`	启动定时自动采集任务
`Qoder: zk-collect-停止自动采集`	停止自动采集任务
`Qoder: zk-collect-查看采集状态`	查看当前采集任务状态和统计信息
`Qoder: zk-collect-重置采集状态`	重置采集进度(可选保留或删除 output.json)

规则同步命令

命令	说明
`Qoder: zk-rules-启动自动同步`	启动 .qoder/rules 文件夹自动同步
`Qoder: zk-rules-停止自动同步`	停止规则文件自动同步
`Qoder: zk-rules-查看同步状态`	查看规则文件同步状态
`Qoder: zk-rules-立即同步`	立即执行一次规则文件同步

技能同步命令

命令	说明
`Qoder: zk-skills-启动自动同步`	启动 .qoder/skills 文件夹自动同步
`Qoder: zk-skills-停止自动同步`	停止技能文件自动同步
`Qoder: zk-skills-查看同步状态`	查看技能文件同步状态
`Qoder: zk-skills-立即同步`	立即执行一次技能文件同步

智能体同步命令

命令	说明
`Qoder: zk-agents-启动自动同步`	启动 .qoder/agents 文件夹自动同步
`Qoder: zk-agents-停止自动同步`	停止智能体文件自动同步
`Qoder: zk-agents-查看同步状态`	查看智能体文件同步状态
`Qoder: zk-agents-立即同步`	立即执行一次智能体文件同步

综合同步命令（规则+技能+智能体）

命令	说明
`Qoder: zk-sync-启动自动同步`	启动综合自动同步（规则+技能+智能体，默认每小时）
`Qoder: zk-sync-停止自动同步`	停止综合自动同步
`Qoder: zk-sync-查看同步状态`	查看综合同步状态
`Qoder: zk-sync-立即同步所有（规则+技能+智能体）`	立即执行一次综合同步

辅助命令

命令	说明
`Qoder: zk-tool-选择数据库文件`	手动选择 .db 数据库文件
`Qoder: zk-tool-测试数据库连接`	测试数据库连接并显示统计信息
`Qoder: zk-tool-测试API连接`	测试后端 API 连接
`Qoder: zk-tool-导出日志`	导出完整日志文件
`Qoder: zk-tool-配置向导`	启动首次配置向导
`Qoder: zk-tool-清除DevOps凭证`	清除 DevOps 登录凭证和 Token

2. 选择数据库文件(可选)

如果自动检测的数据库路径不正确,可以手动选择:

Qoder: zk-tool-选择数据库文件

支持的文件格式：.db, .sqlite, .sqlite3

3. 运行采集脚本

在 VS Code 中按 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS)，输入：

Qoder: zk-collect-立即采集

或点击命令面板中的 Qoder: zk-collect-立即采集 命令。

4. 启动自动任务（推荐）

首次运行会采集最近 7 天的数据，之后每 30 分钟自动增量采集：

Qoder: zk-collect-启动自动采集

注意：自动任务会在后台持续运行，停止自动任务可点击 Qoder: zk-collect-停止自动采集。

✨ 持久化特性：一旦启动自动采集，任务状态会被保存。无论是关闭 VS Code 还是重启电脑，下次打开 VS Code 时自动采集任务会自动恢复运行，无需手动重新启动。

5. 停止自动任务

Qoder: zk-collect-停止自动采集

6. 查看运行状态

Qoder: zk-collect-查看采集状态

============================================================ 📊 自动任务状态

自动任务：✅ 已启用运行次数：15 首次采集：已完成上次运行：2026-03-17 10:30:00 基准时间：2026-03-17 10:25:00


### 7. 重置采集状态（重新采集所有数据）

Qoder: zk-collect-重置采集状态


**使用场景：**
- 🔄 想要重新初始化采集所有数据
- 🔄 之前的采集数据有问题，需要重新采集
- 🔄 更换了数据库或 API 地址，需要重新同步

**重置选项：**
执行命令后会弹出选择框：

| 选项 | 说明 |
|------|------|
| **仅重置状态（保留 output.json）** | 只清除采集进度记录，保留已导出的 JSON 文件 |
| **完全重置（删除 output.json）** | 清除采集进度记录 + 删除 JSON 文件，彻底重新开始 |
| **取消** | 取消操作 |

**重置后的行为：**
- 下次执行采集时，会像首次运行一样重新采集所有数据
- 如果是自动任务，会重新执行"首次采集模式"（采集最近 7 天数据）

### 8. 测试数据库连接

Qoder: zk-tool-测试数据库连接


显示当前数据库文件的信息和统计数据。

Qoder: zk-tool-导出日志


将采集日志导出为文本文件，方便排查问题。

## 输出数据格式

### JSON 文件结构（公司数据库格式）

```json
[
  {
    "session": {
      "sessionId": "9d275ae4-7805-4d53-a4cb-252833eb26cb",
      "userId": "user_123",
      "userName": "张三",
      "sessionTitle": "检查并记忆规则配置",
      "projectId": "D:\\project\\ai_dev_platform",
      "projectName": "ai_dev_platform",
      "sessionType": "assistant",
      "model": "agent",
      "codingTool": "Qoder",
      "createTime": "2026-03-16 10:00:00",
      "updateTime": "2026-03-16 12:00:00"
    },
    "codingChanges": [
      {
        "id": "cd04334a-f32b-4293-9227-35979c2e8977",
        "sessionId": "9d275ae4-7805-4d53-a4cb-252833eb26cb",
        "fileId": "d:\\project\\session-data.html",
        "content": "新增的代码内容...",
        "status": "APPLIED",
        "operationMode": "MODIFIED",
        "version": "1"
      }
    ],
    "dialogueRecords": [
      {
        "id": "对话记录ID",
        "sessionId": "9d275ae4-7805-4d53-a4cb-252833eb26cb",
        "question": "用户提问内容",
        "context": "",
        "status": "ACCEPTED",
        "createTime": "2026-03-16 10:05:00",
        "updateTime": "2026-03-16 10:05:00"
      }
    ]
  }
]

字段说明

session 对象

字段	说明
`sessionId`	会话唯一标识
`userId`	用户 ID
`userName`	用户名（优先使用配置的用户名，未配置时使用数据库原始值）
`sessionTitle`	会话标题
`projectId`	项目 ID（路径）
`projectName`	项目名称
`sessionType`	会话类型
`model`	模型模式
`codingTool`	编码工具（固定为 Qoder）
`createTime`	创建时间
`updateTime`	更新时间

codingChanges 数组

字段	说明
`id`	变更记录唯一标识（UUID）
`sessionId`	关联的会话 ID
`fileId`	文件路径
`content`	新增的代码内容（变更行的集合）
`status`	状态（APPLIED/ACCEPTED/REJECTED 等）
`operationMode`	操作模式（MODIFIED/ADDED/REJECTED）
`version`	版本号

dialogueRecords 数组

字段	说明
`id`	对话记录唯一标识
`sessionId`	关联的会话 ID
`question`	用户提问内容
`context`	对话上下文（预留字段，当前为空）
`status`	状态（自动计算：ACCEPTED/REJECTED/PARTACCEPTED）
`createTime`	创建时间
`updateTime`	更新时间

增量统计原理

工具会在项目目录下生成 .last_sync_state.json 文件，记录：

lastEndTime: 上次统计的会话结束时间戳
lastRunTime: 上次运行时间
isFirstRun: 是否为首次运行标记
runCount: 累计运行次数
autoTaskEnabled: 自动任务启用状态

首次采集模式

第一次运行时，工具只统计最近 initialDays 天（默认 7 天）的数据：

时间范围：当前时间往前推 7 天
跳过 7 天之前的所有会话
采集完成后标记 isFirstRun: false

增量采集模式（分批采集）

首次采集完成后，后续运行根据 lastEndTime 进行智能增量统计：

核心逻辑：

采集时间范围：从 lastEndTime 到当前运行时间
版本过滤：只采集 gmt_modified 字段在采集范围内的版本记录
分批采集：每批最多采集 50 条变更，采集满后发送 API
状态更新：API 成功后才更新同步状态和 output.json，失败则不更新（避免漏数据）
循环采集：一批成功后继续采集下一批，直到覆盖到运行时间

时间更新规则：

最后一批：更新 lastEndTime 为运行时间（当前时间）
中间批次：更新 lastEndTime 为本批最后一个版本的 gmt_modified 时间

数据落地规则：

API 成功 → 更新 output.json + 更新 .last_sync_state.json
API 失败 → 不更新 output.json（保持上次成功数据） + 不更新 .last_sync_state.json

示例流程：

运行时间：2026-03-27 10:00:00
上次结束时间：2026-03-27 08:00:00

第 1 批：采集 08:00:00 → 10:00:00 的数据，最多 50 条变更
       → API 成功 → 更新 lastEndTime = 第 1 批最后版本时间 (08:45:00)

第 2 批：采集 08:45:00 → 10:00:00 的数据，最多 50 条变更
       → API 成功 → 更新 lastEndTime = 第 2 批最后版本时间 (09:30:00)

第 3 批：采集 09:30:00 → 10:00:00 的数据，最多 50 条变更
       → API 成功 → 更新 lastEndTime = 运行时间 (10:00:00)（最后一批）

✅ 采集完成

失败处理：

如果某一批 API 发送失败，则 lastEndTime 不会更新
下次执行时会重新采集该批次数据
确保数据不会丢失

这样可以：

✅ 避免一次性采集大量数据导致超时
✅ 每批数据及时同步，降低风险
✅ API 失败时不更新状态，保证数据完整性
✅ 循环采集直到覆盖所有数据

自动任务说明

启动自动任务

在 VS Code 命令面板中执行：

Qoder: zk-collect-启动自动采集

启动后：

立即执行首次采集：采集最近 7 天的数据
定时执行：之后每 30 分钟自动执行一次增量采集
后台运行：任务会持续运行，直到手动停止
✨ 持久化：自动任务状态会被保存，关闭 VS Code 或重启电脑后，下次启动时会自动恢复运行

自动恢复

当自动采集任务已启用时：

关闭 VS Code 后重新打开 → 自动恢复运行
重启电脑后打开 VS Code → 自动恢复运行
插件激活时会自动检测并恢复上次启用的自动任务

注意：自动恢复时不会重复请求用户授权（因为之前已经同意过）

停止自动任务

Qoder: zk-collect-停止自动采集

查看状态

Qoder: zk-collect-查看采集状态

显示信息：

自动任务启用状态
累计运行次数
首次采集是否完成
上次运行时间
增量统计基准时间

对话记录采集

用户类型区分

插件支持两种用户类型的对话记录采集，数据源和采集方式不同：

特性	编辑器用户 (editor)	插件用户 (plugin)
数据源	`state.vscdb` 数据库	`.qoder/cache/projects` 目录下的 txt 文件
数据库路径	`Qoder/User/globalStorage/state.vscdb`	不需要额外数据库
查询方式	`SELECT key, value FROM ItemTable WHERE key LIKE '%lingma%'`	读取 txt 文件并解析
时间来源	`state.vscdb` 中的 timestamp 字段	`chat_message` 表中的 `gmt_create` 字段
关联方式	直接从 value JSON 中提取 sessionId	通过 `chat_message` 表关联 requestId 和 sessionId

编辑器用户采集流程

Step 1: 打开 state.vscdb 数据库
  ↓
Step 2: 查询 ItemTable 表
  SQL: SELECT key, value FROM ItemTable WHERE key LIKE '%lingma%'
  ↓
Step 3: 解析 value 字段（JSON 格式）
  - 提取 id、sessionId、question、timestamp 等字段
  ↓
Step 4: 过滤和排序
  - 只保留目标 sessionId 的记录
  - 按 sessionId + timestamp 升序排序
  ↓
Step 5: 输出 dialogueRecords 数组

数据库路径（跨平台）：

Windows: C:\Users\{用户名}\AppData\Roaming\Qoder\User\globalStorage\state.vscdb
macOS: /Users/{用户名}/Library/Application Support/Qoder/User/globalStorage/state.vscdb
Linux: /home/{用户名}/.config/Qoder/User/globalStorage/state.vscdb

插件用户采集流程

Step 1: 查询 chat_message 表（带时间范围过滤）
  SQL: SELECT request_id, session_id, gmt_create
       FROM chat_message
       WHERE session_id IN (?, ?, ...)
         AND gmt_create IS NOT NULL
       ORDER BY gmt_create ASC
  ↓
Step 2: 扫描缓存目录
  路径：C:\Users\{用户名}\.qoder\cache\projects
  递归查找所有 .txt 文件
  ↓
Step 3: 按需读取 txt 文件（提前终止优化）
  - 从 txt 文件提取 requestId 和 <user_query> 标签内容
  - 匹配到所有 request_id 后立即停止读取
  ↓
Step 4: 构建输出数据
  - 按 sessionId + createTime 排序
  - 输出格式与编辑器用户一致

性能优化：

✅ 先查数据库获取 request_id 列表，再按需读取 txt 文件
✅ 匹配到所有 request_id 后立即停止读取，避免解析无用文件
✅ 完全遵循主程序的时间范围规则（首次 7 天，之后增量采集）

txt 文件格式要求：

requestId: 726c47c1-0781-4fd5-bd51-dd674241c0e9
timestamp: 1712340000000
...

<user_query>
请帮我优化这个函数的性能
</user_query>

<response>
...
</response>

对话记录状态自动计算

在输出数据时，插件会根据 codingChanges（代码变更）的状态自动推断 dialogueRecords（对话记录）的状态。

核心规则：

状态	说明
`ACCEPTED`	对应时段内所有代码变更都不是 `REJECTED`，或没有代码变更（默认值）
`REJECTED`	对应时段内所有代码变更都是 `REJECTED`
`PARTACCEPTED`	对应时段内部分代码变更是 `REJECTED`

时间范围映射逻辑：

对话记录按时间顺序与代码变更进行匹配：

对话记录 1 (时间: T1)
  ↓
查找代码变更: createTime >= T1 且 < T2 (T2 是对话记录 2 的时间)
  ↓
计算状态 → 更新对话记录 1 的 status

对话记录 2 (时间: T2)
  ↓
查找代码变更: createTime >= T2 且 < T3
  ↓
计算状态 → 更新对话记录 2 的 status

...

最后一条对话记录 (时间: Tn)
  ↓
查找代码变更: createTime >= Tn (所有剩余的代码变更)
  ↓
计算状态 → 更新最后一条对话记录的 status

示例：

{
  "dialogueRecords": [
    { "id": "1", "question": "如何创建函数？", "createTime": "10:00:00" },
    { "id": "2", "question": "如何添加注释？", "createTime": "10:10:00" },
    { "id": "3", "question": "如何测试？", "createTime": "10:20:00" }
  ],
  "codingChanges": [
    { "id": "c1", "createTime": "10:02:00", "status": "ACCEPTED" },
    { "id": "c2", "createTime": "10:05:00", "status": "ACCEPTED" },
    { "id": "c3", "createTime": "10:12:00", "status": "REJECTED" },
    { "id": "c4", "createTime": "10:15:00", "status": "ACCEPTED" },
    { "id": "c5", "createTime": "10:25:00", "status": "REJECTED" }
  ]
}

计算结果：

对话记录	时间范围	对应代码变更	状态	原因
对话 1	10:00-10:10	c1, c2	`ACCEPTED`	全部非 REJECTED
对话 2	10:10-10:20	c3, c4	`PARTACCEPTED`	部分 REJECTED
对话 3	10:20 之后	c5	`REJECTED`	全部 REJECTED

注意事项：

函数内部会自动对 dialogueRecords 和 codingChanges 按 createTime 进行升序排序
使用浅拷贝排序（[...array].sort()），不会修改原始数组
时间格式必须是可解析的（ISO 格式或 YYYY-MM-DD HH:mm:ss）

文件版本对比说明

工具只对比相同版本号的相邻文件变更：

✅ 版本 0 → 版本 0（同一版本的不同状态）
✅ 版本 1 → 版本 1（同一版本的不同状态）
❌ 版本 0 → 版本 1（跳过，不同版本）

原因：同一版本号的不同记录代表该版本的不同处理状态（如 ACCEPTED、APPLIED），对比相同版本号的相邻记录可以查看文件内容在该版本下的变化。

差异输出格式

文件差异不显示具体行号，而是将变更整理成代码集合（只包含新增内容）：

{
  "type": "modified",
  "description": "文件内容已修改",
  "diffCount": 10,
  "oldHash": "abc123...",
  "newHash": "def456...",
  "changes": {
    "added": [
      "新代码行 1",
      "新代码行 2",
      "新代码行 3"
    ]
  }
}

优点：

简洁明了，直接看到新增的代码内容
不包含删除内容，聚焦于最终结果
文件大小更小，便于传输和存储

数据库路径

默认读取以下路径的数据库文件：

Windows

C:\Users\{用户名}\AppData\Roaming\Qoder\SharedClientCache\cache\db\local.db

macOS

/Users/{用户名}/Library/Application Support/Qoder/SharedClientCache/cache/db/local.db

Linux

/home/{用户名}/.config/Qoder/SharedClientCache/cache/db/local.db

文件缓存路径

文件内容存储在：

Windows

C:\Users\{用户名}\AppData\Roaming\Qoder\SharedClientCache\cache\workingSpace\

macOS

/Users/{用户名}/Library/Application Support/Qoder/SharedClientCache/cache/workingSpace/

Linux

/home/{用户名}/.config/Qoder/SharedClientCache/cache/workingSpace/

技术栈

Node.js
sqlite3: SQLite 数据库驱动
fs/path: 文件系统操作
http/https: API 请求
os: 跨平台路径检测
node-cron: 定时任务
crypto: 文件哈希计算

架构说明

模块结构

qoder-sync/
├── extension.js           # 主入口文件（插件激活/停用，协调各模块）
├── collector.js           # 数据采集核心模块（分批采集、API 发送、状态保存）
├── dialogue-collector.js  # 编辑器用户对话记录采集模块（state.vscdb）
├── plugin-dialogue-collector.js  # 插件用户对话记录采集模块（txt 文件）
├── commands.js            # 命令注册模块（所有 VS Code 命令）
├── config-loader.js       # 配置加载器（加载和合并配置）
├── task-manager.js        # 定时任务管理模块（自动采集、规则同步）
├── rules-sync.js          # 规则文件同步模块
├── skills-sync.js         # 技能文件同步模块
├── agents-sync.js         # 智能体文件同步模块
├── http-client.js         # 统一 HTTP 客户端（Token 认证、自动重登录）
├── devops-auth.js         # DevOps 认证模块（登录、Token 管理）
├── crypto-utils.js        # 加密工具模块（AES 加密密码）
├── rules-skills-common.js # 规则/技能/智能体同步公共配置和工具
├── utils.js               # 工具函数模块（时间解析、文件对比等）
├── viewer.js              # 数据查看器和日志导出模块
├── viewer.html            # 数据查看器 HTML 页面

模块职责

模块	职责
`extension.js`	插件激活/停用，协调各模块工作
`collector.js`	核心采集逻辑：查询数据库、分批采集、发送 API、导出 JSON
`dialogue-collector.js`	编辑器用户对话采集：从 `state.vscdb` 提取对话记录
`plugin-dialogue-collector.js`	插件用户对话采集：从缓存目录 txt 文件提取对话记录
`commands.js`	注册所有 VS Code 命令及其处理逻辑
`config-loader.js`	加载和合并用户配置
`task-manager.js`	管理定时任务：启动、停止、恢复自动任务
`rules-sync.js`	规则文件同步：对比本地和远程文件，下载/删除/更新
`skills-sync.js`	技能文件同步：对比本地和远程文件，下载/删除/更新
`agents-sync.js`	智能体文件同步：对比本地和远程文件，下载/删除/更新
`http-client.js`	统一 HTTP 客户端：Token 认证、Token 失效自动重登录、调试日志
`devops-auth.js`	DevOps 认证：登录、Token 获取/保存/清除
`crypto-utils.js`	加密工具：AES 加密/解密密码
`rules-skills-common.js`	公共配置和工具：API 地址、文件下载、manifest 管理
`utils.js`	工具函数：时间格式化、文件内容对比、同步状态管理
`viewer.js`	数据查看器和日志导出：打开 HTML 查看器、导出日志文件

依赖注入

模块之间通过回调函数和参数传递依赖，避免全局变量：

// 示例：collector.js 通过参数接收依赖
runBatchLoop(
    db, startTime, endTime, isFirstRun, initialStartTime,
    config,
    sendToApi,           // 注入 API 发送函数
    exportToJson,        // 注入导出函数
    loadSyncState,       // 注入状态加载函数
    saveSyncState,       // 注入状态保存函数
    log,                 // 注入日志函数
    configUserName,      // 配置的用户名
    stateDb,             // state 数据库连接（编辑器用户专用）
    userType             // 用户类型（editor/plugin）
)

文件同步功能（规则/技能/智能体）

功能说明

自动同步工作区中 .qoder 文件夹下的规则文件（rules）、技能文件（skills）和智能体文件（agents），确保本地文件与远程 API 保持一致。

使用方法

配置 API 地址

当前 API 基础域名默认为 https://devops.ctjsoft.com，后续将支持通过配置文件自定义。
启动自动同步

规则同步：
```
Qoder: zk-rules-启动自动同步
```
技能同步：
```
Qoder: zk-skills-启动自动同步
```
智能体同步：
```
Qoder: zk-agents-启动自动同步
```
启动后：
- 立即执行首次同步
- 之后每小时自动执行一次（可配置 Cron 表达式）
- 关闭/重启 VS Code 后自动恢复运行

手动同步

单项同步：

Qoder: zk-rules-立即同步
Qoder: zk-skills-立即同步
Qoder: zk-agents-立即同步

综合同步（一次性同步规则+技能+智能体）：

Qoder: zk-sync-立即同步所有（规则+技能+智能体）

综合自动同步

综合同步将规则、技能、智能体三项同步合并为一个定时任务，只需启动一次即可自动同步所有文件：
```
Qoder: zk-sync-启动自动同步
```
启动后：
- 立即执行首次综合同步
- 之后每小时自动执行一次（可通过 qoder-sync.allSync.cronExpression 配置）
- 关闭/重启 VS Code 后自动恢复运行
查看状态：
```
Qoder: zk-sync-查看同步状态
```
停止：
```
Qoder: zk-sync-停止自动同步
```

同步逻辑

检测工作区：检查当前打开的项目中是否存在 .qoder 文件夹（包含 rules、skills、agents 子目录）
获取本地文件列表：递归读取 .qoder/rules、.qoder/skills、.qoder/agents 下所有文件
请求远程文件列表：调用 API 获取远程文件名列表
对比文件：
- 远程有、本地没有 → 下载新增文件
- 本地有、远程没有 → 删除本地文件
- 两边都有 → 对比内容，不一致则更新
更新状态：保存同步时间和文件列表到对应的 manifest.json

API 格式要求

获取文件列表接口

GET /api/qoder/rules
响应：
{
  "success": true,
  "data": {
    "files": [
      "agents/my-agent.md",
      "rules/coding-standards.md",
      "skills/data-analysis.md"
    ]
  }
}

下载单个文件接口

GET /api/qoder/rules/{fileName}
响应：文件内容（纯文本）

注意事项

必须有打开的工作区且包含 .qoder 文件夹
同步过程会修改 .qoder 文件夹内容，请确保有写入权限
规则、技能、智能体同步共用相同的 API 基础域名和认证机制（DevOps Token）
综合同步与单项同步可独立运行，互不影响
所有接口成功/失败提示信息统一输出到"Qoder Sync"日志通道，不再弹出通知窗口

VS Code 配置项

可通过 VS Code 设置（Ctrl+,）搜索 qoder-sync 查看和修改以下配置：

配置项	默认值	说明
`qoder-sync.userType`	`""`	用户类型：`editor`（编辑器用户）或 `plugin`（插件用户）
`qoder-sync.userName`	`""`	DevOps 用户名（姓名全拼）
`qoder-sync.devopsPassword`	`""`	DevOps 登录密码（AES 加密后存储）
`qoder-sync.dbPath`	`""`	Qoder 数据库路径（留空则自动检测）
`qoder-sync.dataConsent`	`false`	是否同意插件采集本地数据
`qoder-sync.api.enabled`	`false`	是否启用 API 同步
`qoder-sync.api.requestEnabled`	`true`	是否请求后端 API
`qoder-sync.export.outputFile`	`"output.json"`	JSON 输出文件名
`qoder-sync.schedule.minIntervalMinutes`	`30`	最小执行间隔（分钟），0 表示不限制
`qoder-sync.schedule.initialDays`	`7`	首次采集的天数范围
`qoder-sync.schedule.autoTask.cronExpression`	`"/30 * * *`	自动采集 Cron 表达式
`qoder-sync.rulesSync.cronExpression`	`"0 * * * *`	规则文件同步 Cron 表达式
`qoder-sync.skillsSync.cronExpression`	`"0 * * * *`	技能文件同步 Cron 表达式
`qoder-sync.agentsSync.cronExpression`	`"0 * * * *`	智能体文件同步 Cron 表达式
`qoder-sync.allSync.cronExpression`	`"0 * * * *"`	综合同步 Cron 表达式（默认每小时）
`qoder-sync.allSync.enabled`	`false`	是否启用综合同步
`qoder-sync.rulesSync.enabled`	`false`	是否启用规则文件自动同步
`qoder-sync.skillsSync.enabled`	`false`	是否启用技能文件自动同步
`qoder-sync.agentsSync.enabled`	`false`	是否启用智能体文件自动同步
`qoder-sync.devopsToken`	`""`	DevOps 认证 Token（自动管理，无需手动配置）
`qoder-sync.devopsTokenExpiry`	`0`	DevOps Token 过期时间戳（自动管理）
`qoder-sync.hasShownWizard`	`false`	是否已显示过配置向导（自动管理）

常见问题

数据采集相关

Q: 为什么采集的数据为空?

A: 请检查:

Qoder 数据库文件是否存在
数据库中是否有 chat_session 和 chat_working_space_file 表
是否有实际的会话数据
用户类型和用户名是否已正确配置
是否已同意数据采集授权

Q: 如何修改采集频率?

A: 采集频率由系统自动管理,无需手动配置。

Q: API 同步失败怎么办?

A: 检查:

网络连接是否正常
后端服务是否运行
DevOps 用户名和密码是否已正确配置
Token 是否已过期（插件会自动重新登录，如失败会弹出输入框）
查看输出通道的详细错误信息
使用 Qoder: zk-tool-测试API连接 命令测试连接
如持续失败，可尝试 Qoder: zk-tool-清除DevOps凭证 后重新配置

Q: 如何查看详细的采集日志?

A: 在 VS Code 中点击底部状态栏的"输出"面板,选择"Qoder Sync"通道。或使用 Qoder: zk-tool-导出日志 命令导出日志文件。

Q: 如何在另一台电脑上使用?

在新电脑上安装 Qoder 插件和 Qoder Sync 插件
如果数据库路径不同,使用 Qoder: zk-tool-选择数据库文件 手动选择
系统会自动完成配置

Q: sqlite3 模块未编译怎么办?

A: 插件激活时会检查 sqlite3 模块是否可用。如果未编译,会弹出错误提示。请在终端执行:

cd ~/.qoder/extensions/qoder-sync.qoder-sync-1.0.0
npm install sqlite3

Q: 对话记录没有采集到?

A: 检查:

用户类型是否设置为 editor 或 plugin
编辑器用户:state.vscdb 文件是否存在,数据库中是否有包含 lingma 的记录
插件用户:缓存目录是否有 txt 文件,chat_message 表是否有对应记录

规则/技能同步相关

Q: 文件同步失败怎么办?

A: 检查:

是否打开了工作区且包含 .qoder 文件夹
网络连接是否正常
DevOps Token 是否有效（查看输出通道是否有自动重新登录的日志）
.qoder/rules、.qoder/skills、.qoder/agents 文件夹是否有写入权限
查看输出通道的详细错误信息

Q: Token 失效或自动登录失败怎么办?

插件会在 Token 失效或为空时自动尝试重新登录
如果自动登录失败，会弹出输入框要求重新输入用户名和密码
也可手动执行 Qoder: zk-tool-清除DevOps凭证 清除 Token，下次操作时会重新弹出登录框

Q: 如何手动触发同步?

A: 使用以下命令:

Qoder: zk-rules-立即同步
Qoder: zk-skills-立即同步
Qoder: zk-agents-立即同步

开发与打包

版本升级指南

插件版本号定义在 package.json 文件的 version 字段中。每次发布新版本前,需要更新版本号。

方案 1: 使用 npm 命令自动升级(推荐)

# 升级修订号 (1.0.0 → 1.0.1) - 用于 bug 修复
npm version patch

# 升级次版本号 (1.0.0 → 1.1.0) - 用于新增功能
npm version minor

# 升级主版本号 (1.0.0 → 2.0.0) - 用于重大变更
npm version major

# 指定具体版本号
npm version 1.2.3

执行后会自动更新 package.json 中的版本号,并创建对应的 git tag。

方案 2: 手动修改版本号

直接编辑 package.json 文件,修改第 6 行的 version 字段:

{
  "name": "qoder-sync",
  "version": "1.0.1",  // 修改此处
  ...
}

版本号规范(语义化版本 SemVer)

版本号格式: 主版本号.次版本号.修订号 (Major.Minor.Patch)

主版本号(Major): 不兼容的 API 重大变更
次版本号(Minor): 向下兼容的功能性新增
修订号(Patch): 向下兼容的问题修正

示例:

1.0.0 → 1.0.1: 修复 bug
1.0.0 → 1.1.0: 新增功能
1.0.0 → 2.0.0: 重大变更或不兼容更新

打包插件

版本升级后,使用以下命令打包插件:

# 使用 vsce 打包(自动生成包含版本号的 .vsix 文件)
vsce package

打包成功后会生成文件: qoder-sync-<版本号>.vsix

示例:

版本 1.0.0 → 生成 qoder-sync-1.0.0.vsix
版本 1.0.1 → 生成 qoder-sync-1.0.1.vsix
版本 1.1.0 → 生成 qoder-sync-1.1.0.vsix

⚠️ 打包注意事项：

VSIX 打包不支持中文文件名（中文会被转为 ?，导致 Item has already been added 重复 key 错误）。本项目的 .vscodeignore 已排除以下可能包含中文文件名的目录：

.qoder/**          # 开发者本地规则/技能/智能体文件
.lingma/**         # 其他编辑器配置
openspec/**        # OpenSpec 开发规范文件
node_modules/**    # 依赖包
*.vsix             # 已打包的 vsix 文件

如果本地还有其他中文文件需要排除，请同步补充到 .vscodeignore 中。

完整发布流程

更新版本号:
```
npm version patch  # 或 minor/major
```
更新更新日志: 在 README.md 的"更新日志"章节添加新版本说明
打包插件:
```
vsce package
```

安装测试:

code --install-extension qoder-sync-<新版本号>.vsix

发布(可选):
```
vsce publish
```

更新日志

1.0.0 (2025-03-30)

🎉 初始版本发布
✅ 支持完整的数据采集功能(会话、文件版本)
✅ 支持增量采集和自动定时任务
✅ 支持后端 API 同步
✅ 跨平台支持(Windows/macOS/Linux)

1.1.0 (2026-05-18)

✨ 新增配置向导: 首次使用自动引导配置,提升用户体验
✨ 新增数据库路径选择器: 支持手动选择 .db 文件
✨ 新增日志导出功能: 方便排查问题
✨ 新增数据库连接测试功能: 测试连接并显示统计信息
✨ 新增 API 连接测试功能: 验证后端 API 可用性
✨ 新增用户信息强制校验: 采集前必须配置用户类型和用户名
✨ 新增对话记录采集功能:
- 支持编辑器用户(editor)模式
- 支持插件用户(plugin)模式
✨ 新增对话状态自动计算: 根据代码变更推断对话记录状态
✨ 新增规则文件同步功能: 自动同步 .qoder/rules 文件夹，支持增量同步和版本控制
✨ 新增技能文件同步功能: 自动同步 .qoder/skills 文件夹，支持增量同步和版本控制
✨ 新增智能体文件同步功能: 自动同步 .qoder/agents 文件夹，支持增量同步和版本控制
✨ 新增综合同步功能: 一键同步规则+技能+智能体，独立定时任务（默认每小时），支持查看状态与自动恢复
✨ 新增 DevOps 认证集成:
- 自动登录获取 Token
- Token 失效/为空时自动重新登录
- 登录失败弹出输入框引导重新输入凭证
- 密码 AES 加密存储
- 支持手动清除凭证
✨ 新增持久化任务: 关闭/重启 VS Code 后自动恢复自动任务
🔧 统一 HTTP 客户端: 采集、规则、技能、智能体共用 http-client，统一处理 Token 认证
🔧 API 基础域名配置化: 默认域名写在配置文件中，后续支持用户自定义
🔧 用户名校验放宽: 用户名仅校验非空，不再限制字符格式
🔧 日志输出优化: 接口成功/失败等提示信息统一输出到“Qoder Sync”日志通道，不再弹窗干扰
🔧 完善 .vscodeignore: 排除 .qoder/、.lingma/、openspec/ 等目录，避免中文文件名导致打包冲突
🐛 优化首次使用体验
🏗️ 代码模块化拆分,提升可维护性
📝 完善文档和配置说明

许可证

ISC

ZK Qoder Sync

zk-qoder-sync

Qoder Sync - Qoder 缓存数据库采集工具

📑 目录

功能

🎯 核心功能

1. 数据采集

2. 对话记录采集

3. 数据输出

🔄 自动化功能

4. 定时任务

5. 文件同步（规则/技能/智能体）

6. DevOps 认证与 Token 管理

7. 跨平台支持

📊 统计与监控

安装

使用方法

快速开始

方式一: 配置向导(首次使用推荐)

命令列表

数据采集命令

规则同步命令

技能同步命令

智能体同步命令

综合同步命令（规则+技能+智能体）

辅助命令

2. 选择数据库文件(可选)

3. 运行采集脚本

4. 启动自动任务（推荐）

5. 停止自动任务

6. 查看运行状态

============================================================ 📊 自动任务状态

自动任务：✅ 已启用 运行次数：15 首次采集：已完成 上次运行：2026-03-17 10:30:00 基准时间：2026-03-17 10:25:00

字段说明

session 对象

codingChanges 数组

dialogueRecords 数组

增量统计原理

首次采集模式

增量采集模式（分批采集）

自动任务说明

启动自动任务

自动恢复

停止自动任务

查看状态

对话记录采集

用户类型区分

编辑器用户采集流程

插件用户采集流程

对话记录状态自动计算

文件版本对比说明

差异输出格式

数据库路径

Windows

macOS

Linux

文件缓存路径

Windows

macOS

Linux

技术栈

架构说明

模块结构

模块职责

依赖注入

文件同步功能（规则/技能/智能体）

功能说明

使用方法

同步逻辑

API 格式要求

注意事项

VS Code 配置项

常见问题

数据采集相关

Q: 为什么采集的数据为空?

Q: 如何修改采集频率?

Q: API 同步失败怎么办?

Q: 如何查看详细的采集日志?

Q: 如何在另一台电脑上使用?

Q: sqlite3 模块未编译怎么办?

自动任务：✅ 已启用运行次数：15 首次采集：已完成上次运行：2026-03-17 10:30:00 基准时间：2026-03-17 10:25:00