嵌入式命令行
drsg 是命令行界面。它直接打开数据库，属于嵌入式访问，而不是连到某个正在运行的
服务，因此适合本地脚本化、批量导入、检视、备份与运维。每次调用都接受一个全局的
--db <路径>（默认 graph.drsg）；多数命令还接受一个 --plane（默认 startup）。
由于它在进程内打开数据库，drsg 无法操作一个已经被 drsg serve（或另一个 drsg）
打开的数据库：数据库会取得一把排他锁，第二次打开会直接报错，而不会把数据库弄坏。并发
访问请改用面向该服务的 SDK 或 RPC 接口，命令行只用于离线操作。
命令参考
| 命令 | 用途 |
|---|---|
init [--dir] [--rebuild] | 为智能体引导本仓库：图化、以分离方式拉起 serve watch、写出 .mcp.json（见第 10 章）。在不含 digest 特性的 --no-default-features 构建中，它退化为创建一个空数据库——多数命令也会在首次使用时创建 |
plane list | create | drop | show | 平面生命周期 |
import <文件> --plane | 加载 JSONL 节点/边 |
export --plane | 将一个平面导出为 JSONL |
get <节点> --plane | 按 id 或 @外部键 获取一个节点 |
query <计划> --plane | 运行一个序列化的逻辑计划（JSON，或 -） |
cypher <查询> --plane | 运行一条 openCypher 子集语句（或 -） |
catalog [--plane] | 打印软 schema（单个平面或整个数据库） |
algo <名称> --plane | 运行一个图算法 |
hybrid <查询> --plane | 融合的向量 + 关键词 + 图邻近度检索 |
index ensure | keyword | 声明一个向量或关键词索引 |
ask <问题> --plane | 自然语言查询 |
digest <文件|目录|url> --plane [--mode] | 导入一篇文档、一个代码仓库，或一个页面及其链接 |
search <查询> --plane | 语义查找：嵌入查询文本，返回最近的节点 |
context | describe | trace | impact | fathom <名称> --plane | 已图化代码平面上的智能体动词 |
impact <名称> --plane [--depth] [--across [attached|all]] | --across 把半径扩到本仓库之外：本平面所附着的那些平面，或本实例持有的每一个平面 |
snippet <名称 | path:start-end> --plane | 一个符号的源码文本，或被解析树中任一文件的某个行区间 |
grep <模式> --plane [--regex] [--path] [--all-files] | 在该树上做文本检索，被 ignore 的文件除非指定 --all-files 否则不在范围内；每个命中都标出所在的符号 |
traverse <键> --plane [--edge-type] | 一跳（或数跳）之外的邻居 |
history --plane [--limit] | 平面背后的代码仓库：HEAD、分支与标签指向、变基、最新的提交 |
deployed [<目标>] --plane [--ops] [--history] | 某个运行中的东西是由哪次提交构建的，以及哪些东西在跑某次提交：通过镜像标签所携带的修订号，把运维平面连到它旁边的历史平面 |
recall <名称> --at <修订> --plane [--vs <修订>] [--pattern] | 某个修订版本时的代码：文件、行区间、目录或符号；在那棵树上检索；或相对更早修订版本的差异 |
wire <路径 | 名称> --plane [--verb] | 什么在提供某个 HTTP 路径、什么在请求它；跨平面内的每种语言，也跨它所附着的平面 |
attach <名称> --plane [--url] [--as] [--both] | 记录本平面可以询问的平面：本实例上的，或由另一个 drsg 提供服务的 |
detach <名称> --plane | 移除一条附着（名称不存在时只做报告，不算错误） |
attachments --plane [--probe] | 本平面附着了什么；--probe 会逐个询问远端的附着现在是否应答 |
mount <路径> [--as] [--url] | 立即在一个正在运行的 drsg 上提供另一个数据库的平面——这三个动词说的是它的 RPC，而不是打开某个文件，因为存储的锁在服务器手里 |
unmount <名称> [--url] | 停止提供某个挂载，并释放其存储的锁——若有折叠仍在进行中并持有它，会如实说明（名称不存在时如实报告，而不是报错） |
mounts [--url] | 那台服务器提供了什么：每个挂载及其目录与平面，以及每个平面所记录的树 |
queries [<id>] [--limit] | 已经运行过的 Cypher 查询；cypher --history <id> 可再跑一次 |
vectorize --plane | 为一个平面的节点生成向量嵌入，以供相似度检索 |
plugin install | list | remove | 管理预处理插件（沙箱化的 wasm 解析器） |
snapshot <out> / restore <in> | 整库备份与恢复 |
stats / check | 汇总计数 / 完整性扫描 |
serve [--addr] | 运行 Web 仪表盘 + JSON-RPC 接口 + MCP 端点 |
serve watch [--dir] | 对外服务，并让代码平面随每次提交保持同步 |
update [--bin] [--dir] | 若有更新的发行版，就把本二进制替换掉 |
被导入的文件可以是 Markdown 或纯文本，也可以是 Word、PowerPoint、Excel、 OpenDocument、RTF、EPUB、CSV 与 PDF；后一类会先转换为 Markdown，让模型读到的是标题、 表格与列表，而不是一堆散乱的字符。格式依据文件内容判断，扩展名写错也不影响。目录会 被逐文件遍历、分发：源码经已安装的解析器插件变成事实，文档则作为散文交给模型。
全局选项为 --db <路径> 与 --config <路径>（配置文件，见
第 2 章）。
平面
$ drsg --db graph.drsg plane create social
$ drsg --db graph.drsg plane list
$ drsg --db graph.drsg plane show social
$ drsg --db graph.drsg plane drop social
数据进出
导入与导出都用 JSONL：每行一个节点或边，一个平面因此可以经由文件系统往返，也便于跟 其它工具集成：
$ drsg --db graph.drsg import nodes.jsonl --plane social
$ drsg --db graph.drsg export --plane social > social.jsonl
$ drsg --db graph.drsg get @ada --plane social
节点的 external_key 是它在平面内的身份标识，因此 --on-conflict 决定了当导入的键
已经存在时的处理方式：
| 策略 | 效果 |
|---|---|
error（默认） | 不导入任何内容，并列出发生冲突的键 |
skip | 保留已有节点，丢弃传入的那一行 |
update | 覆盖已有节点的属性；若该行带有 labels，一并覆盖标签 |
$ drsg --db graph.drsg import nodes.jsonl --on-conflict update
imported 0 nodes, 0 edges, 2 existing updated
在 skip 与 update 下，文件中的边仍会解析到平面中已存在的节点，因此关系可以挂载到
既有数据上。边本身不带键，所以总是追加写入。这一策略约束的是节点身份，而不是边的
去重。没有 external_key 的行不可能发生冲突，始终会被插入。
查询
一条语句既可以是 openCypher 子集，也可以是一个序列化的计划；两者均接受 - 以从标准
输入读取。--param 将一个 $name 占位符绑定到一个 JSON 值：
$ drsg --db graph.drsg cypher --plane social \
'MATCH (p:Person) WHERE p.age >= $min RETURN p' --param min=18
$ drsg --db graph.drsg query - --plane social < plan.json
$ drsg --db graph.drsg catalog --plane social
每一条成功执行的查询都会被记录下来——无论它来自 CLI、仪表盘，还是通过 MCP 发起的
智能体。queries 按时间倒序列出已执行的查询，每行包含 id、时间、平面以及折叠为单行
的查询文本；带上 id 则单独打印该条查询的原文。cypher --history 会重新执行一条已
记录的查询，并默认使用它当初所针对的平面，除非 --plane 另有指定：
$ drsg --db graph.drsg queries --limit 5
4 2026-09-05 08:14:02Z social MATCH (p:Person) WHERE p.age >= $min RETURN p
3 2026-09-05 08:11:47Z social MATCH (p:Person) RETURN count(*) AS people
$ drsg --db graph.drsg queries 3 > last.cypher
$ drsg --db graph.drsg cypher --history 3
历史记录有容量上限——默认为两百条——新记录到来时最旧的一条会被清除。重新执行最近
一条已记录的查询只会更新它的时间戳，而不会再添加一份副本。请注意 drsg history
是另一条命令：它列出的是某个仓库的提交历史。
图算法
$ drsg --db graph.drsg algo pagerank --plane social --top 10
$ drsg --db graph.drsg algo components --plane social
$ drsg --db graph.drsg algo shortest-path --plane social --src 1 --dst 42
$ drsg --db graph.drsg algo louvain --plane social
检索与导入
声明索引、运行融合检索、以自然语言提问，并导入文档（第 3 章）。 由 LLM 支撑的命令从环境读取提供方密钥：
$ drsg --db graph.drsg index ensure Doc embedding --plane social
$ drsg --db graph.drsg index keyword Doc body --plane social --lang english
$ drsg --db graph.drsg hybrid "how does time-travel work" \
--plane social --label Doc --vector embedding --keyword body --graph-hops 1
$ drsg --db graph.drsg ask "which companies does Ada work for?" \
--plane social --chat deepseek --embed qwen
$ drsg --db graph.drsg digest notes.md --plane social --apply
$ drsg --db graph.drsg digest paper.md --plane papers --mode super --apply
$ drsg --db graph.drsg digest https://example.com/paper --plane papers \\
--topic "attention mechanism" --pages 6 --apply
以 http(s):// 开头的参数会被抓取，而不是从磁盘读取：页面会被转换为 Markdown，并在
--pages/--depth 范围内沿链接继续抓取，只保留与页面自身主题（以及给出的
--topic，如果有）相关的内容（第 3 章）。协议头是
必需的：裸的 example.com 也可能是一个合法的文件名，与其去猜使用者的本意，不如
要求写明。命令会打印保留了什么、丢弃了什么，但不提供交互式挑选，那是仪表盘页面
列表要做的事。
--mode 决定抽取结果会被清理到何种程度：coarse 归一标签与边类型的词表，fine
（默认）在此之上合并指称同一事物的实体，super 再把每个实体连同其全部段落一并
重读，结果最准确，但输入 token 用量约为 15 倍（第 3 章）。
备份与完整性
snapshot 在单一提交序号上写出一个一致的整库快照包；restore 将其重建进一个空
数据库，并保留 id、提交序号与已构建的检索索引（第 11 章）。
stats 与 check 报告计数，并扫描每个平面的可读性：
$ drsg --db graph.drsg snapshot backup.drsgsnap
$ drsg --db fresh.drsg restore backup.drsgsnap
$ drsg --db graph.drsg stats
$ drsg --db graph.drsg check
check 还会指出仍为旧格式、其数据块没有校验和的存储段。压缩会重写它所合并的段，
因此写入频繁的库会自行升级；而稳定在压缩阈值以下的库则会一直保留未校验的块——这些
块中的损坏会被当作数据读出，而不是报错。upgrade 逐条重写这些段，不回收任何版本，
库中内容保持原样：
$ drsg --db graph.drsg upgrade
upgraded 2 storage runs to the checksummed format
提供服务
serve 是嵌入式模型的例外：它打开数据库，随后将其通过网络暴露给仪表盘、各 SDK 与
MCP 服务。
$ DRSG_TOKEN=please-change-me drsg --db graph.drsg serve --addr 0.0.0.0:7700