OpenCode Session Toolkit

读取本地 OpenCode SQLite 数据库，跨目录查询或导出会话、消息、片段和项目。

以下所有命令均假设工作目录为此技能目录。如需 Markdown 导出，直接运行捆绑脚本：

bash
./scripts/exportopencodesessions.py --help

使用场景

- 列出最近会话，按目录筛选，或按标题搜索
读取特定会话的消息 JSON
将匹配的会话导出为每个会话一个 Markdown 文件的归档
检查数据库模式和索引（仅在需要时加载 references/schema.md）

工作流程

1. 使用 opencode db path 解析数据库路径。
以只读模式运行所有查询。
仅在需要字段级详细信息时加载 references/schema.md。

1. 解析数据库路径

bash
if ! command -v opencode >/dev/null 2>&1; then
echo opencode 命令未在 PATH 中找到 >&2
exit 1
fi

if ! DB_PATH=$(opencode db path 2>/dev/null); then
echo 通过 opencode db path 解析 OpenCode 数据库路径失败 >&2
exit 1
fi

if [ -z ${DBPATH:-} ] || [ ! -f $DBPATH ]; then
echo 未找到 OpenCode 数据库：$DB_PATH >&2
exit 1
fi

echo 使用数据库：$DB_PATH

列出现有数据库文件（无匹配时不报错）：

bash
find ${XDGDATAHOME:-$HOME/.local/share}/opencode -maxdepth 1 -name *.db -print 2>/dev/null

2. 时间转换与输出格式化

时间转换：所有时间字段均为 Unix 毫秒时间戳。在 SQL 中直接使用 datetime() 进行转换。

bash

在 SQL 中转换（推荐，无需外部命令）

datetime(time_updated/1000, unixepoch, localtime)

Shell 辅助变量用于时间窗口

NOW_MS=$(date +%s000) LAST7D=$((NOWMS - 7864001000)) LAST30D=$((NOWMS - 30864001000))

表格对齐：对于普通字段，将 SQLite 输出通过管道传递给 column -t -s |（| 是 SQLite 的默认分隔符）。对于长 JSON 字段（如 message.data），建议使用 -json 输出。

bash
sqlite3 -readonly $DBPATH SELECT id, title, timeupdated FROM session LIMIT 5; | column -t -s |

3. 常用只读查询

提示：对于不含大 JSON 字段的查询，追加 | column -t -s | 以获得对齐的表格输出。

列出最近 20 个会话（按最近更新时间排序）

bash
sqlite3 -readonly $DB_PATH \
SELECT id, title, directory,
datetime(time_updated/1000,unixepoch,localtime) as updated
FROM session
ORDER BY time_updated DESC
LIMIT 20; | column -t -s |

按目录筛选会话

bash
sqlite3 -readonly $DB_PATH \
SELECT id, title, datetime(time_updated/1000,unixepoch,localtime) as updated
FROM session
WHERE directory LIKE /path/to/project%
ORDER BY time_updated DESC
LIMIT 20; | column -t -s |

按 project_id 筛选会话（最精确的项目关联）

bash
sqlite3 -readonly $DB_PATH \
SELECT s.id, s.title, s.directory,
datetime(s.time_updated/1000,unixepoch,localtime) as updated
FROM session s
WHERE s.project_id = your-project-id
ORDER BY s.time_updated DESC
LIMIT 20; | column -t -s |

project_id 映射到 project.id。使用以下命令列出项目：

bash
sqlite3 -readonly $DB_PATH SELECT id, worktree, name FROM project; | column -t -s |

列出所有目录中的会话（含项目信息）

bash
sqlite3 -readonly $DB_PATH \
SELECT s.id, s.title, s.directory, p.worktree,
datetime(s.time_updated/1000,unixepoch,localtime) as updated
FROM session s
LEFT JOIN project p ON s.project_id = p.id
ORDER BY s.time_updated DESC
LIMIT 50; | column -t -s |

按时间范围筛选

bash

最近 7 天活跃的会话

sqlite3 -readonly $DB_PATH \
SELECT id, title, datetime(time_updated/1000,unixepoch,localtime) as updated
FROM session
WHERE time_updated > $(( $(date +%s000) - 7864001000 ))
ORDER BY time_updated DESC
LIMIT 20; | column -t -s |

今天创建的会话（本地时间）

sqlite3 -readonly $DB_PATH \ SELECT id, title, datetime(time_created/1000,unixepoch,localtime) as created FROM session WHERE date(time_created/1000,unixepoch,localtime) = date(now,localtime) ORDER BY time_created DESC LIMIT 20; | column -t -s |

读取单个会话的消息内容

bash
sqlite3 -readonly -json $DB_PATH \
SELECT m.id, datetime(m.time_created/1000,unixepoch,localtime) as created, m.data
FROM message m
WHERE m.session_id = your-session-id
ORDER BY m.time_created ASC;

从 message.data JSON 中提取字段

bash

提取关键字段，如 role 和 modelID

sqlite3 -readonly $DB_PATH \
SELECT id,
json_extract(data, $.role) as role,
json_extract(data, $.modelID) as model,
datetime(time_created/1000,unixepoch,localtime) as created
FROM message
WHERE session_id = your-session-id
ORDER BY time_created ASC; | column -t -s |

使用 LIKE 搜索消息负载文本

sqlite3 -readonly $DB_PATH \ SELECT id, jsonextract(data, $.role) as role, timecreated FROM message WHERE data LIKE %keyword% ORDER BY time_created DESC LIMIT 20; | column -t -s |

搜索会话标题

bash
sqlite3 -readonly $DB_PATH \
SELECT id, title, directory, datetime(time_updated/1000,unixepoch,localtime) as updated
FROM session
WHERE title LIKE %keyword%
ORDER BY time_updated DESC
LIMIT 20; | column -t -s |

查看会话摘要统计

bash
sqlite3 -readonly $DB_PATH \
SELECT title, summaryadditions, summarydeletions, summary_files,
datetime(time_created/1000,unixepoch,localtime) as created
FROM session
ORDER BY time_updated DESC
LIMIT 20; | column -t -s |

4. 将会话导出为 Markdown

导出脚本将每个会话写入一个 Markdown 文件。默认情况下：

- 文件名 = 会话标题 + 创建时间
时间筛选使用 time_updated，除非传递了 --time-field created
跳过 step-start / step-finish 片段以减少噪音
当 project.name 为空时，项目文件夹名称回退到 worktree 的基本名称，或 global

导出一个项目的会话

bash
./scripts/exportopencodesessions.py \
--project opencode-session-toolkit \
--output-dir ./exports/opencode-session-toolkit

--project 通过子字符串匹配 project_id、project.name、project.worktree 和 session.directory。

导出时间范围内的会话

bash
./scripts/exportopencodesessions.py \
--start 2026-03-01 \
--end 2026-03-24T23:59:59 \
--time-field updated \
--output-dir ./exports/march

接受的时间格式：

- ISO 日期：

opencode-session-toolkitOpenCode会话工具