corral

corral：本地编程会话数据接口

corral 扫描本机 ~/.claude/projects/、~/.codex/sessions/、~/.kimi-code/sessions/、~/.cursor/chats/ 和 OpenCode 的 SQLite 数据库（~/.local/share/opencode/opencode.db，只读打开）下的会话历史，为大模型 Agent 提供结构化查询命令。这些命令只读、无副作用：不会拉起新会话、不会自动接续任务、不会修改 任何历史文件。拿到数据之后要做什么（继续任务、汇总给用户、转发给另一个 Agent）由调用方决定。

所有命令输出统一 JSON envelope，写到 stdout：

{"ok": true, "data": {...}, "error": null, "meta": {"version": 1}}

失败时 ok 为 false，data 为 null，error 包含：

• code：程序可判断的错误分类（usage_error / not_found / ambiguous / history_unavailable / not_resumable / internal_error）
• message：人类可读的错误说明
• hint：建议的排查方向
• next_commands：可以直接执行的后续命令列表（绝对入口身份，照抄即可；不要改写成裸 corral，以免命中 PATH 上另一份旧副本）

退出码：0 成功、1 一般失败（含未预料的 internal_error）、2 用法错误（参数不对，含未知 --fields）、3 会话不存在、5 会话标识有歧义。 不要只看 stdout 是否有内容来判断成功，检查退出码或 ok 字段。

安装与探针（CLI 缺失时不要停下问人）

调任何子命令前先确认入口与能力。corral 不在 PATH 上时，按下面可信源装到用户目录后继续原任务（用户要这个能力即已授权用户目录安装；sudo/系统目录/覆盖已装版本仍需显式授权）：

• 可信源：github.com/x0c/corral（corral 包）。安装渠道三选一：pipx install corral、brew install x0c/corral/corral、源码树内 bash cli/scripts/dev-install.sh（editable，供开发）。
• 装完先钉绝对路径并验能力（之后全会话只用该绝对路径；next_commands 给的即是）：

CORRAL_BIN="$(command -v corral)"          # 钉住本会话唯一入口
"$CORRAL_BIN" describe >/dev/null && echo describe-ok
"$CORRAL_BIN" diagnose | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['ok']; print('diagnose-ok', d['data']['version'])"

• diagnose 的 package_file / install_channel / stale_source_warning 告诉你当前跑的是哪份拷贝；源码树里开发却加载了别处副本时会有告警，以告警为准换入口。
• diagnose 的 keepalive_server 报告保活 tmux server 的调度档（priority、interactive_job、clamped）。clamped: true 表示托管助手整体被 macOS 限流（新会话起得慢、同样的活比 Corral 外慢数倍）；只能重启一次 server 解决，见 docs/MAINTAINER_GUIDE.md「Keepalive server scheduling class」。
• 源码树 editable 安装用于维护和开发，不会替代环境准备。跑耗时检查前先用 python3 scripts/dev_env.py check --repo . 确认就绪（未就绪时跑 python3 scripts/dev_env.py prepare --repo .；只诊断用 doctor --repo . --json，命令经 run --repo . -- <cmd> 走 checkout .venv），再按 测试环境指南（python3 scripts/acceptance.py --json，只演练用 --dry-run）做隔离验收；focused acceptance 不代替完整 UI/终端及干净安装门禁。安装/依赖失败应先按环境问题处理，不要误判成会话查询结果为空。