# 旧式样例复制协议

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

`POST /workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize`。普通产品身份，regular service boundary；handler 从路径读取 ID，不读取请求业务字段。前端旧辅助函数发 `{}`，当前首页文件卡片使用只读解析，不调用此 POST。

## 可用 ID

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

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize
```

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

`builder-expense`、`builder-resume`、`builder-qa`、`doc-report`、`doc-bid`、`doc-meeting`、`data-sales`、`data-retention`、`data-weekly`、`kb-product`、`kb-policy`、`kb-feedback`、`workflow-github`、`workflow-lead`、`workflow-issue`。这些是旧 SampleID，不能与三个文件 GuideID 混用。

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

## 写入与失败清理

先校验 SampleID，再顺序打开配置目录中的打包资源，获取文件信息和请求语言对应的显示名，调用 Catalog 上传无引用文件。成功响应包含新文件及 `moi://files/{id}` URI。没有幂等键，不应把重复 POST 视为复用已有引用。

失败时对已记录为上传成功的文件逐个执行删除，cleanup 使用脱离请求取消的独立超时上下文。关闭文件失败也触发清理；删除失败与原错误合并。这里不是数据库原子事务，不承诺所有部分写入都能清除。当前上传调用若同时返回 ID 和错误，ID 是否已持久化、底层如何恢复需另查完整上传生命周期，暂不判定线上泄漏。

## 成功字段

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sample_id` | string | 旧样例 ID |
| `files` | array（数组） | 按定义顺序生成的新文件 |
| `files[].file_key` | string | 旧逻辑文件键 |
| `files[].id` | string | 上传所得文件 ID |
| `files[].uri` | string | `moi://files/{id}` |
| `files[].name` | string | 上传结果的显示名称 |
| `files[].size` | integer | 文件字节数 |
| `files[].type` | string | 样例定义的内容类型 |
| `files[].md5` | string | 可省略，内容 MD5 |

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

## 错误与复测

未知 SampleID 映射 404/ErrObjectNotFound，缺打包资源映射 **500/ErrSampleAssetMissing**，其他错误映射 500/ErrServer。GET 的样例缺失为 404，不能复制它的错误表给旧 POST。POST 未单列授权拒绝与 PDP 不可用映射。

记录前后文件 ID，保留每个清理结果，不能对来源不明的文件执行删除。
