首页/参考/CLI 参考

CLI 参考

两个命令：trove（交互与运维）和 trove-cli（一次性提问）。这一页列出全部子命令与 REPL 斜杠命令。

两个入口

命令	用途
trove	REPL / serve / mcp / admin / job / schedule / maintenance / validate / extensions / preset
trove-cli	一次性提问，配合 `--print` 输出 JSON

pyproject.toml:93 trove main.py:971 main_repl

flowchart LR
    T["trove
常驻与运维"]:::entry --> T1["REPL（默认）"]:::entry
    T --> T2["serve · mcp"]:::entry
    T --> T3["admin · job · schedule
maintenance"]:::entry
    T --> T4["validate · extensions · preset
干跑校验与扩展资产"]:::entry
    TC["trove-cli
一次性"]:::entry --> C1["提问：--print 输出 JSON"]:::entry
    TC --> C2["index：kb / schema / sync
只属于 trove-cli，trove index 不认"]:::entry

    classDef entry fill:#71717a14,stroke:#71717a59,stroke-width:1px;

图 1 · 两个入口的分工：trove 是常驻与运维（干跑校验 validate、扩展资产与包 extensions、预设 preset 都挂在这一侧），trove-cli 是一次性提问与索引。要留意 index 只挂在后者上——trove index … 不认这个名字。上面这段以源码显示：图渲染库没加载起来（离线、CDN 被拦或浏览器禁用了 JavaScript 时会这样）。这段 Mermaid 文本本身就说明了上面那些框与连线。

trove-cli

参数	说明
--datasource / -d	数据源名或 URL
--config / -f	指定配置文件
--model / -m	覆盖模型（优先级最高）
--print / -p	一次性输出 JSON 后退出
--workflow / -w	`reflection` / `fixed` / `empty`

echo "哪个地区的平均贷款金额最高?" | uv run trove-cli --datasource demo --print

三个 workflow 分别是什么

reflection 是默认的完整图；fixed 直通不反思（用于对照实验）； empty 是调试用的空转。排查「是不是反思环节引入的问题」时，切到 fixed 跑一遍是很有用的手段。

trove 的子命令

子命令	作用
serve	启动 HTTP 服务
mcp	启动 MCP 服务（见 MCP 集成）
admin	用户与授权管理
job	定时任务增删查
schedule	调度器（`--once` / `--daemon`）
maintenance	会话维护：`run` / `status`
validate	扩展面干跑校验：KB lint / 决策规则编译 / 技能挂点；`--run` 装前试跑、`--impact` 影响面回放、`--packs` 反作弊——零 LLM，退出码即结论（见下文）
extensions	扩展资产：`list` / `show` / `plan`（信封，能力从引用推导）；`export` / `import`（资产包，导入全落 pending）
preset	预设包（接入模板）：`list` / `show` / `apply`——套用只落 pending 草稿
index	索引：`kb` / `schema` / `sync`——只属于 `trove-cli` 入口，`trove index …` 不认它

main.py:683 sys.argv schedule_cmds.py:197 --daemon maintenance_cmds.py:22 run

serve

trove serve [--host 127.0.0.1] [--port 8000]

main.py:752 --host main.py:753 --port

job / schedule

trove job add | list | cancel
trove schedule --once        # 跑一轮到期任务后退出
trove schedule --daemon      # 常驻循环

schedule_cmds.py:92 add schedule_cmds.py:196 --once

daemon 与 serve 内置调度二选一

trove serve 自带调度 tick。再起一个 schedule --daemon 会让任务跑两遍。详见运维管理 · 定时任务。

admin

trove admin create-user | reset-password | list-users
            disable-user | enable-user | grant | revoke | facts

admin_cmds.py:172 create-user

validate

trove validate                     # 全量干跑：KB / 决策规则 / 技能挂点
trove validate --datasource demo   # 只体检一个数据源
trove validate --json | jq .       # 机器可读（CI 消费）
trove validate --strict            # 警告也算失败
trove validate --live              # 连真源：枚举缺口 + 真方言编译 + 声明验证（键/基数/fan-out 前提）
trove validate --run               # 装前试跑：语料对已确认资产做装/不装双态消融
trove validate --impact <包|目录>   # 影响面回放：候选资产装上前后判定差分（与 --run 互斥）
trove validate --packs             # 反作弊：KB 示例 SQL vs 本地 gold 集（gold.sql）

退出码即结论：0 干净 · 1 硬错误（--strict 下警告也算；试跑/回放里为有拦截变更或断言失败）· 2 用法错误——以及在 --run/--impact 下「这次没验成」（语料缺失 / 判定执行出错 / 一条判定都没跑过 / 候选集读不出）。试跑与回放绝不静默返回 0。全部零 LLM； --json 顶层 metrics 可直接喂回归门 scripts/eval_gate.py。机制详解见扩展与治理 · 干跑校验。

main.py:996 validate validate_cmds.py:92 main_validate

extensions

trove extensions list [--kind skill|decision|preset]   # 资产总表（信封）
trove extensions show <名称> [--kind ...]              # 单个信封：挂点 / 能力 / 来源 / unresolved
trove extensions plan [--json]                         # 运行时装配清单 + 与信封对账（漂移 → 退出码 1）
trove extensions export <名称> <目录> [--origin ...]    # 打包组织资产（原样 + sha256 + 来源）
trove extensions import <目录> [--force]               # 校验并导入——全部落 pending

「信封」是资产的编译产物：能力从引用闭包推导（不是作者声明），推导不出的引用响亮进 unresolved。导入是包级校验（缺文件 / 被篡改 / 版本过新一条都不落）+ 逐条落 pending——已生效的决策规则永不被覆盖，--force 也不行；条目级拒载时退出码 1（静默的成功码会让 CI 把「部分没导进去」当成「全导进去了」）。

main.py:1008 extensions extensions_cmds.py:188 main_extensions

preset

trove preset list              # 内置 + 组织预设
trove preset show <名称>       # 逐段摘要 + 原文
trove preset apply <名称>      # 套用（只落 pending 草稿，确认后才生效）

main.py:1002 preset preset_cmds.py:66 main_preset

REPL 斜杠命令

会话

命令	作用
/help	列出全部命令
/exit	退出
/clear	清空当前会话上下文
/compact	压缩上下文（会触发偏好抽取）
/tasks	查看后台任务

session_cmds.py:53 help session_cmds.py:73 compact

系统

命令	作用
/model	切换模型
/datasource	切换数据源
/init	初始化
/validate [--live] [--run [--episodes]] [--impact <包\|目录>]	扩展面干跑校验（REPL 无退出码——结论落在输出末尾的「退出码 N」一行）
/extensions	扩展资产信封：`list` / `show`
/preset	预设包：`list` / `apply`（套用只落 pending 草稿）

system_cmds.py:55 model system_cmds.py:61 datasource validate_cmds.py:193 validate extensions_cmds.py:292 extensions preset_cmds.py:187 preset

知识库

/kb init              # 起草 schema 注释 + 确定性词表/模板
/kb list              # 看现有条目
/kb reload            # 改完 YAML 后重载
/kb migrate           # 迁移到 OSSIE 语义模型格式
/kb lessons           # 查看教训
/kb learn [--yes]     # 从上一轮沉淀一条示例

kb_cmds.py:329 kb

元数据与轨迹

命令	作用
/tables	列出表
/table_schema	看某表结构
/schemas	列出 schema
/databases	列出数据库
/facts	查看已确认的用户事实
/trace [list]	回放最近一轮的完整轨迹

metadata_cmds.py:82 tables facts_cmds.py:57 facts trace_cmds.py:186 trace

附带脚本

仓库的 scripts/ 下有一批运维与评测脚本。分两类：

零成本（随时可跑）

脚本	作用
lint_kb.py	KB 静态检查（+ 可选活库枚举比对）
check_kb_anti_cheat.py	检查模板是否抄了 gold SQL
check_drift.py	数据漂移门禁
check_page_anchors.py	本文档站的锚点与死链校验
eval_gate.py	回归门（纯文件对比）
eval_retrieval.py 等	检索评测
tune_rrf.py	RRF 参数网格调优

会花钱（按需）

脚本	作用
eval_bird.py	端到端 EX 评测——不要随手跑
distill_lessons.py	从失败中蒸馏教训（调 LLM）
distill_history.py	从历史（episode / 审计 / lineage）蒸馏三类待审资产；判定与抽取零 LLM，仅教训提炼一步调（走起草模型档）；`--dry-run` 零写入

数据准备（一次性）

脚本	作用
init_postgres_demo.py	BIRD 金融 demo 灌入 PostgreSQL（幂等）
import_sqlite_to_mysql.py	BIRD SQLite 导入 MySQL
import_bird_descriptions.py	BIRD 官方描述导入 schema_notes
probe_enums.py	探测枚举值写入 schema_notes

继续读

想了解	去哪
HTTP 接口	API 参考
MCP 三种传输	MCP 集成
命令背后的配置	配置参考
定时任务的行为细节	运维管理

本页源码锚点的基准提交：anchor-base: 211ae86 GitHub 仓库文档首页