<span id="旧式样例复制协议"></span>

# Legacy sample copy protocol

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

`POST /workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize`. Uses a regular product identity and regular service boundary. The handler reads the ID from the path, not business request fields. The legacy frontend helper sends `{}`; current home file cards use read-only resolution and do not call this POST.

<span id="可用-id"></span>

## Available IDs

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

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

:::::
:::::{tab-item} Parameters

`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`. These legacy SampleIDs are not interchangeable with the three file GuideIDs.

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

<span id="写入与失败清理"></span>

## Writes and failure cleanup

Validate SampleID, sequentially open packaged assets from the configured directory, read file information and localized display names for the request language, and upload unreferenced files through Catalog. Success includes new files and `moi://files/{id}` URIs. There is no idempotency key; repeated POST does not imply reusing existing references.

On failure, delete each file recorded as successfully uploaded. Cleanup uses an independent timeout context detached from request cancellation. File-close failures also trigger cleanup; deletion failures are combined with the original error. This is not an atomic database transaction and does not guarantee removal of every partial write. If an upload returns both an ID and an error, persistence and underlying recovery require checking the complete upload lifecycle; this alone does not establish a production leak.

<span id="成功字段"></span>

## Success fields

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Fields

The string `code: "OK"` envelope contains this `data`:

| Field | Type | Description |
| --- | --- | --- |
| `sample_id` | string | Legacy sample ID |
| `files` | array (array) | New files generated in definition order |
| `files[].file_key` | string | Legacy logical file key |
| `files[].id` | string | Uploaded file ID |
| `files[].uri` | string | `moi://files/{id}` |
| `files[].name` | string | Display name from the upload result |
| `files[].size` | integer | File size in bytes |
| `files[].type` | string | Content type in the sample definition |
| `files[].md5` | string | Optional content MD5 |

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

<span id="错误与复测"></span>

## Errors and retesting

Unknown SampleID maps to 404/ErrObjectNotFound, missing packaged assets to **500/ErrSampleAssetMissing**, and other failures to 500/ErrServer. GET uses 404 for missing samples; do not copy its error table to the legacy POST. POST has no separate mapping for authorization denial or PDP unavailability.

Record file IDs before and after the operation and retain every cleanup result. Do not delete files of unknown provenance.
