# 读取首页引导的 Catalog 文件引用

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`GET /workspaces/{id}/agent-home-guide/guides/{guide_id}/files`，普通产品身份，无请求体。先经过 regular service boundary，再按目标卷调用受 `volume.read` 约束的 Catalog 文件列表。


## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{id}/agent-home-guide/guides/{guide_id}/files
```

:::::
:::::{tab-item} 参数说明

需要当前工作区的普通产品身份、目标引导ID及相关卷的读取权限，无业务请求体。

:::::
::::::
:::::::


## 引导与文件

| `guide_id` | 逻辑样例键 |
| --- | --- |
| `organize-documents` | `contract_saas_subscription`、`email_contract_approval` |
| `find-information` | `legal_constitution` |
| `automate-repetitive-work` | `email_shipment_exception`、`image_warehouse_receiving` |

`analyze-data` 不属于文件引导 ID；前端走 Catalog 表元数据链。文件解析只读取当前部署语言的不可变样例及工作区挂载卷，逐项核对 file ID 与 volume ID。缺少初始化、挂载或目标文件时失败，不创建文件、不复制文件，也不替换为另一语言资源。

## 响应字段

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 字段说明

字符串 `code: "OK"` 封套的 `data` 为：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `guide_id` | string | 当前引导 ID |
| `language` | string | 部署决定的样例语言 |
| `files` | array（数组） | 以下文件对象，保持引导键顺序 |
| `files[].file_key` | string | 稳定逻辑样例键 |
| `files[].name` | string | Catalog 名称去首尾空白；为空时使用解析出的文件名 |
| `files[].size` | integer | Catalog 文件字节数 |
| `files[].type` | string | 解析所得内容类型；空值回退 application/octet-stream |
| `files[].catalog_file.workspace_id` | string | 当前工作区 |
| `files[].catalog_file.volume_id` | integer | 挂载卷 ID |
| `files[].catalog_file.file_id` | string | 用于后续附件交接的 Catalog 文件 ID |

列表查询固定 page=1、page_size=20，带单个 file ID 过滤和目标卷；这是内部存在性检查，接口本身没有对外分页输入。

:::::
::::::
:::::::

## handler 错误映射

| HTTP | `code` | 条件 |
| --- | --- | --- |
| 404 | `ErrObjectNotFound` | 未知引导 ID |
| 404 | `ErrSampleAssetMissing` | 所需样例不可用 |
| 403 | `ErrForbidden` | 授权拒绝 |
| 503 | `ErrServiceUnavailable` | 授权服务不可用 |
| 500 | `ErrServer` | 其他错误或错误文本本地化失败 |

错误封套包含 `code`、本地化 `msg`、`data: null`。HTTP/封套为源码映射证据，不代表真实请求已测。接口成功只说明这些文件引用在读取时可见，后续任务执行和模型访问仍须验证。
