# 任务内知识检索

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

## 使用任务注入连接包

智能体执行沙箱启动子进程时，会成套注入 `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. 检索候选段落并保存输出文件

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

```bash
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` 段为例）：

```bash
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`：

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

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

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

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

```bash
# 提交单个检索结果文件中采用的第 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 原文中定位关键词示例：

```bash
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` 字段。
