任务内知识检索

在智能体任务的受控执行环境中使用 semantic-model 运行态子命令检索已绑定的知识来源、分页读取完整证据、在解析 Markdown 原文中定位段落,并提交回答所依据的引用集合。对应的服务端 HTTP 契约与权限说明见 任务内知识检索与引用。

使用任务注入连接包

智能体执行沙箱启动子进程时,会成套注入 MOI_RUNTIME_AUTHORIZATION(格式为 Bearer <token>)、MOI_ENDPOINT、MOI_API_KEY 与 MOI_WORKSPACE_ID。moi-cli 检测到 MOI_RUNTIME_AUTHORIZATION 后自动绑定该短期任务授权并关闭终端交互提示:

  • 直接调用下文 moi-cli semantic-model ... 命令,保留沙箱注入的整套环境变量。

  • 运行态模式下传入与注入环境不一致的 -endpoint 或 -api-key 会触发 CLI_RUNTIME_CONNECTION_CONFLICT 并拒绝发送请求,防止短期任务凭证外泄。

  • 用于日常管理知识库的个人访问令牌(PAT)不包含任务执行上下文,无法单独替代短期任务授权。

检索、分页读取证据与提交引用

任务内知识问答遵循“检索候选段落 -> 分页读取完整证据 -> 提交引用并核验接受状态”三步闭环。

1. 检索候选段落并保存输出文件

指定查询关键词与一个尚不存在的本地输出文件路径:

export KNOWLEDGE_QUERY="retention policy"
moi-cli semantic-model search --keywords "$KNOWLEDGE_QUERY" --output ./search.json

命令标准输出返回包含 path(完整 JSON 结果文件)与 reading_path(供按序阅读的格式化文本文件)的摘要。打开 reading_path 浏览各 PASSAGE 编号与上下文预览,挑选支撑当前问题答案的候选段落索引。

2. 按段落索引分页读取完整证据

将 --from 指向检索结果文件,--index 设为选中的段落编号(以下以第 0 段为例):

moi-cli semantic-model read-evidence --from ./search.json --index 0 --output ./evidence-0.json

moi-cli 自动从 --from 文件中提取产物、文件与分段标识。检查返回结果中的 output.content 与 output.has_more;当 output.has_more 为 true 时,将 --from 指向刚刚生成的证据文件并另存新文件名继续读取后续页,直至 has_more 为 false:

moi-cli semantic-model read-evidence --from ./evidence-0.json --index 0 --output ./evidence-1.json

当 search.json 已包含未经截断的完整段落正文且已完整阅读时,也可附加 --local-read 登记该次本地完整读取。

3. 提交引用选择并核对 accepted 状态

证据读取完毕后,在生成最终回答前提交实际采用的证据索引:

# 提交单个检索结果文件中采用的第 0 段(多文件可重复传入 --from <file> --indices <list>)
moi-cli semantic-model cite --from ./search.json --indices 0

# 检索与读取后确认无任何证据能够支撑待回答事实时,显式提交空引用集合
moi-cli semantic-model cite --json '{"sources":[]}'

检查返回结果(及 path 指向的完整 JSON)中的 output.accepted(或顶层摘要 accepted):

  • 若为 true,表明引用已通过服务端读取完整性校验,可据此组织回答。

  • 若为 false,按返回错误或未满足的读取要求补齐 read-evidence 后重新提交 cite。

发现来源文件、定位解析原文与查询表

除通用关键词检索外,运行态还支持按文件查找、解析 Markdown 原文搜索及授权结构化表查询:

子命令与核心参数

作用说明

semantic-model find-files --query <kw> --output <path>

按名称关键词查找已绑定来源清单;后续通过 --from 与 --index 对选中来源发起检索或段落列举(文件清单本身不作为引用证据)。

semantic-model read-source --source-name <exact-name> --output <path>

按唯一匹配的名称顺序读取单个来源内容并检查覆盖范围。

semantic-model list-passages --from <file> --index <n> --output <path>

按页列出来源段落,使用返回游标继续读取同一来源的后续页。

semantic-model search-document --from <file> --index <n> --query <kw> --output <path>

利用当前证据携带的解析 Markdown 定位信息,在解析原文内搜索关键词。

semantic-model read-document --from <file> --index <n> --output <path>

分页读取解析后的 Markdown 原文内容与后续游标。

semantic-model search-images --query <kw> --output <path>

检索知识库中的图片证据及其页面定位信息。

semantic-model describe-tables / semantic-model query --json-file <query.json> --output <path>

先查看当前任务授权访问的结构化表结构,再提交查询请求并核对返回行数、截断标记与来源信息。

在解析 Markdown 原文中定位关键词示例:

moi-cli semantic-model search-document \
  --from ./search.json \
  --index 0 \
  --query "$KNOWLEDGE_QUERY" \
  --output ./matches.json

限制和注意事项

  • 所有运行态子命令的 --output 参数均要求目标文件路径尚不存在,不会覆盖已有文件;每次翻页或追加检索请指定新的输出文件名。

  • search-document 与 read-document 依赖当前证据条目包含解析后的 Markdown 文档定位元数据;若该来源不含解析原文定位信息,请继续使用 read-evidence 或 list-passages 读取段落。

  • 本地输出文件生成并不等同于引用已被服务端接受;脚本或智能体执行器必须同时检查命令退出码、业务错误码及 cite 返回的 accepted 字段。

最后更新于