<span id="任务内知识检索"></span>
<span id="任务内知识检索与引用"></span>

# In-Task Knowledge Retrieval

Inside a managed agent task execution environment, use the task-runtime `semantic-model` subcommands to search bound knowledge sources, paginate full evidence passages, locate text inside parsed Markdown documents, and submit answer citations. For the underlying HTTP API contracts and authorization rules, see [Search and cite knowledge within a task](../../api/ai-studio/agents/runtime-knowledge.md).

<span id="使用任务注入连接包"></span>
<span id="使用当前任务连接"></span>

## Use the injected task connection bundle

When an agent execution sandbox spawns child processes, it injects `MOI_RUNTIME_AUTHORIZATION` (`Bearer <token>`), `MOI_ENDPOINT`, `MOI_API_KEY`, and `MOI_WORKSPACE_ID` as an atomic bundle. When `MOI_RUNTIME_AUTHORIZATION` is present, `moi-cli` binds that short-lived task proof automatically and disables interactive prompts:

- Run the `moi-cli semantic-model ...` commands below directly while preserving the injected environment variables.
- Passing an explicit `-endpoint` or `-api-key` that differs from the injected bundle fails immediately with `CLI_RUNTIME_CONNECTION_CONFLICT` so task proofs are never sent to another endpoint.
- Standalone workspace management PATs do not carry task execution context and cannot replace short-lived task authorization.

<span id="检索、分页读取证据与提交引用"></span>

## Search, paginate evidence, and submit citations

Task-scoped knowledge retrieval follows a three-step loop: search candidate passages, paginate full evidence text, and submit verified citations.

<span id="检索并保存完整结果"></span>

### 1. Search candidate passages and save the result file

Set your query keywords and pass a non-existent local file path to `--output`:

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

Standard output prints a summary containing `path` (full JSON result) and `reading_path` (formatted passage text indexed by `PASSAGE` numbers). Inspect `reading_path` to choose the passage indices that answer the user question.

<span id="读取选中的证据"></span>

### 2. Paginate full evidence by passage index

Point `--from` at the saved search file and specify the selected passage `--index` (`0` in the example below):

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

`moi-cli` extracts artifact, file, and segment identifiers directly from `--from`. Inspect `output.content` and `output.has_more`; while `output.has_more` is `true`, pass the newly written evidence file to `--from` and save each subsequent page to a new output path until `has_more` is `false`:

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

If `search.json` already contains an untruncated full passage that you have read completely, you can pass `--local-read` to register that full local read.

<span id="提交引用选择"></span>

### 3. Submit citations and verify `accepted`

After reading the full supporting passages, submit the selected indices before composing the final answer:

```bash
# Submit passage index 0 from a single result file (repeat --from <file> --indices <list> across multiple files)
moi-cli semantic-model cite --from ./search.json --indices 0

# Submit an explicit empty citation set when no retrieved evidence supports the factual claim
moi-cli semantic-model cite --json '{"sources":[]}'
```

Verify `output.accepted` (and inspect the full JSON at `path` if the summary reports unaccepted items):

- When `accepted` is `true`, the server has verified the required evidence reads and recorded your citations.
- When `accepted` is `false`, fulfill any missing `read-evidence` requirements reported in the response and re-submit `cite`.

<span id="发现来源文件、定位解析原文与查询表"></span>
<span id="查找文件和-markdown-原文"></span>

## Discover source files, search parsed Markdown, and query tables

Beyond keyword passage search, runtime commands support source discovery, parsed Markdown navigation, image search, and authorized structured table queries:

| Subcommand and key flags | Description |
| --- | --- |
| `semantic-model find-files --query <kw> --output <path>` | Search bound source filenames; pass matching entries via `--from` and `--index` into subsequent search or passage calls (file listings themselves are not citable evidence). |
| `semantic-model read-source --source-name <exact-name> --output <path>` | Sequentially read a uniquely named source and inspect coverage metadata. |
| `semantic-model list-passages --from <file> --index <n> --output <path>` | Paginate passages within a single source using returned source cursors. |
| `semantic-model search-document --from <file> --index <n> --query <kw> --output <path>` | Search inside a parsed Markdown document using Markdown locator metadata attached to the evidence item. |
| `semantic-model read-document --from <file> --index <n> --output <path>` | Read pages of a parsed Markdown document and follow continuation cursors. |
| `semantic-model search-images --query <kw> --output <path>` | Retrieve image evidence items and page bounding/location metadata. |
| `semantic-model describe-tables` / `semantic-model query --json-file <query.json> --output <path>` | Inspect structured tables authorized for the current task, then execute a table query and check row counts, truncation flags, and provenance. |

Search inside a parsed Markdown document from an earlier search hit:

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

<span id="限制和注意事项"></span>

## Limitations and notes

- Every `--output` flag requires a destination path that does not exist yet; choose a new filename for each pagination step or follow-up query.
- `search-document` and `read-document` require parsed Markdown locator metadata on the referenced evidence item; when absent, continue reading passages with `read-evidence` or `list-passages`.
- Local file creation alone does not confirm accepted citations; always check the process exit status, API error fields, and `accepted` in the `cite` output JSON.
