旧式样例复制协议¶
POST /workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize。普通产品身份,regular service boundary;handler 从路径读取 ID,不读取请求业务字段。前端旧辅助函数发 {},当前首页文件卡片使用只读解析,不调用此 POST。
可用 ID¶
POST https://api.moi.matrixorigin.cn/v5/workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize
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 是否已持久化、底层如何恢复需另查完整上传生命周期,暂不判定线上泄漏。
成功字段¶
字符串 code: "OK" 封套的 data 为:
字段 |
类型 |
说明 |
|---|---|---|
|
string |
旧样例 ID |
|
array(数组) |
按定义顺序生成的新文件 |
|
string |
旧逻辑文件键 |
|
string |
上传所得文件 ID |
|
string |
|
|
string |
上传结果的显示名称 |
|
integer |
文件字节数 |
|
string |
样例定义的内容类型 |
|
string |
可省略,内容 MD5 |
错误与复测¶
未知 SampleID 映射 404/ErrObjectNotFound,缺打包资源映射 500/ErrSampleAssetMissing,其他错误映射 500/ErrServer。GET 的样例缺失为 404,不能复制它的错误表给旧 POST。POST 未单列授权拒绝与 PDP 不可用映射。
记录前后文件 ID,保留每个清理结果,不能对来源不明的文件执行删除。