qmd trust：如何审查并批准随仓库提交的 .qmd 配置中的受限字段

qmd trust：如何审查并批准随仓库提交的 .qmd 配置中的受限字段

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd

当你 clone 了一个自带.qmd/index.yml的仓库，并在这个目录树里运行qmd update时，QMD 会自动发现并采用这份项目本地配置——而这份文件里的某些字段可以由仓库作者任意填写，包括一条会在qmd update时执行的 shell 命令。自 2.8.3 版本起，QMD 不再默认信任随 checkout 带来的.qmd配置：受限字段要么在终端里列出并要求你确认，要么在无人值守时被直接跳过。本文的任务就是在这样的仓库里完成一次完整操作：审查受限字段、用qmd trust批准（或撤销）、验证批准状态，以及了解 CI 场景下的替代开关。

qmd 是一个完全本地的文档检索 CLI（全文 BM25 + 向量 + 混合检索），项目本地索引由qmd init创建在.qmd/index.yml（index.yaml也接受）与项目本地index.sqlite中，位置说明见 README.md。

哪些字段受限，哪些不受限

QMD 会自动发现.qmd/index.yml并为目录树内的任何命令采用它，但有三类字段能触达项目之外，默认不会被无人值守地使用（见 README.md 的 "Checked-in.qmdconfig is not trusted by default" 一节及 CHANGELOG.md 2.8.3 的 Security 条目）：

1. collections.<name>.update—— 由qmd update以bash -c在集合自己的目录中执行的 shell 命令，本质上是别人写的脚本；
2. collections.<name>.path解析后指向项目目录之外的路径；
3. models.embed/models.rerank/models.generate中任何不是内置默认值的 URI（任意hf:仓库或本地 GGUF 路径）。

以下情况不受限，无需批准：

• 指向项目内部的集合路径（例如./docs），即使配置未获批也会继续被索引；
• 内置默认模型 URI（缺失的models键与内置默认值等价，qmd init把默认值填进 YAML 也不会使已有批准失效）;
• 你自己~/.config/qmd/*.yml里的任何内容，包括qmd collection update-cmd写入的命令——全局配置永不设限。

一个典型的受限配置长这样（值取自 README 的示例）：

collections: wiki: path: ~/reference/wiki update: "git pull --ff-only"

path指向项目外、update携带 shell 命令，两个字段都命中受限集合。

触发门禁时 QMD 的行为

在终端里运行qmd update（以及qmd embed/qmd pull/qmd query）时，QMD 会先列出受限字段再询问：

This project's config defines update commands: wiki: git pull --ff-only Collection paths outside this project: wiki: ~/reference/wiki Config that came with a checkout is not trusted by default. Trust this project's .qmd config? [y/N]

回答y/yes即记录批准；否则打印 "Skipped. Indexing of this project continues."——受限字段被跳过，项目内部的索引照常进行。

没有终端可询问时（agent、CI、MCP server），QMD 不会失败，而是跳过受限字段并继续索引，输出形如（文档示例）：

Skipping them — no terminal to confirm on. Indexing of this project continues. Approve with 'qmd trust', or set QMD_TRUST_LOCAL_CONFIG=1 for unattended runs.

若某个集合的路径在项目外且配置未获批，qmd update会跳过该集合：

Skipping collection 'wiki' — path ~/reference/wiki is outside this project and this .qmd config is not trusted. Approve with 'qmd trust'.

未获批的自定义模型 URI 则不会被加载或下载；qmd status仍会显示 YAML 里写的值，但实际加载的是内置默认模型。

用 qmd trust 审查并批准

在项目目录内运行：

qmd trust

它会从当前 YAML（而不是 SQLite 同步副本）计算当前受限集合，按上面同样格式列出三类受限项，然后立即把这次批准记录进信任库。批准成功时输出：

✓ Trusted <项目内 .qmd/index.yml 的解析路径> Editing a hook, out-of-project path, or custom model will ask again. Revoke with 'qmd trust revoke'.

几个判断点：

• 如果当前作用域内没有项目本地配置（你在自己~/.config/qmd的场景下运行），提示该配置 "is your own config — it is never gated. Nothing to trust."；
• 如果配置里根本没有更新命令、项目外路径或自定义模型，提示 "Nothing to trust."；
• 批准记录保存在<config dir>/trusted.json，默认即~/.config/qmd/trusted.json；配置目录遵循XDG_CONFIG_HOME与QMD_CONFIG_DIR。每条记录以解析后的配置路径为键，存有一个 SHA-256 摘要和trustedAt时间戳。实现见 src/trust.ts。

批准覆盖的是"你看到的这一组"

摘要（digest）对受限集合做顺序无关的规范化，所以：

• 在 YAML 里调整集合顺序不会使批准失效；
• 但修改任何update命令、新增一个带 hook 的集合、把集合路径改到项目外、或更换自定义模型 URI，都会改变摘要并重新武装门禁——下一次运行会再次询问。CHANGELOG 特别提到：一次改写了命令的git pull同样会触发重新询问。

这意味着批准不是"永久放行这份文件"，而是"放行此刻这组受限值"。

验证批准状态

qmd trust list

没有任何批准时输出No trusted project configs.；有批准时逐条输出<配置路径> (trusted <批准时间>)。

也可以直接查看~/.config/qmd/trusted.json：每条记录包含摘要字段hooks和trustedAt。信任文件损坏时 QMD 会把它当作空信任库而不是"全部可信"，门禁照常生效。

批准生效后，再跑qmd update就不再询问，受限 hook 会在重新索引前执行（README 文档示例）：

$ qmd update [1/3] wiki (**/*.md) Running update command: git pull --ff-only Already up to date. Collection: ~/reference/wiki (**/*.md) Indexed: 0 new, 2 updated, 340 unchanged, 0 removed

这里有一个必须理解的副作用：update命令每次qmd update都会以bash -c在集合自己的path目录（而非你的当前目录）中执行；命令退出码非零时，qmd update打印失败并中止整次运行，排在后面的集合不会被重新索引。所以批准一个 hook 等价于授权在每次更新时执行这段 shell 命令——审查时重点看的就是这一栏。

撤销批准与 CI 无人值守开关

批准后想反悔，在项目内运行：

qmd trust revoke

该命令删除对应配置的信任记录；成功输出✓ Revoked trust for <path>，若本来就没有批准则输出<path> was not trusted.。撤销不影响任何已索引数据，只是让受限字段重新回到"询问/跳过"状态。

CI 或其他必须无人值守、且你明确愿意放行受限字段的场景，用环境变量整体选择信任：

QMD_TRUST_LOCAL_CONFIG=1 qmd update # 信任项目本地配置的全部受限字段 QMD_TRUST_UPDATE_HOOKS=1 qmd update # 较早的开关，只针对 update hooks

两者取真值时门禁直接放行（0、false、off、no、none视为关闭）。这是最宽的放行方式——它绕过审查直接执行仓库作者写的命令，只应在你已确认仓库来源可信的流水线里使用。

另外，qmd collection add/qmd collection update-cmd写入你自己的全局配置时会顺带记录信任，这与qmd trust处理项目本地配置是两回事，不要混淆。

边界与限制

• 门禁只作用于项目本地.qmd/index.yml；你自己~/.config/qmd下的配置永远不受限。
• 未获批不等于不可用：项目内路径的索引、内置模型的工作照旧，被跳过的只有受限字段对应的那部分（外部路径集合、hook、自定义模型）。
• 审批是按"配置文件 × 受限值摘要"记录的：同一仓库换机器后需要重新qmd trust；同一份配置改了命令后也需要重新批准。
• 信任机制与 2.8.3 安全更新一并引入（issue #886、#889），行为细节以 CHANGELOG.md 为准，判定逻辑在 src/trust.ts，CLI 输出文案在 src/cli/qmd.ts。

完成qmd trust→qmd trust list这条链路后，你就完成了一次完整的"审查—批准—验证"：受限字段在批准前只会被跳过或询问，不会在无人知晓时执行；批准范围精确到当前这组值，任何后续改动都会自动把你拉回询问状态。

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd