寫入工作區文件（sha256 OCC）

PUT /v1/workspace/files/:name

以原子方式替換工作區 Markdown 文件。必須傳入 expected_sha256，即前一次 GET 返回的值（字符串）；創建全新文件時傳入 null。不匹配會返回 409 並附帶當前 sha，UI 可據此提供覆蓋或重新加載選項。請求體上限為 256 KB；超出時返回 413。

請求體

{ "content": "# SOUL.md - Minara\n...", "expected_sha256": "deadbeef..." }

響應體

{ "ok": true, "data": { "name": "SOUL.md", "sha256": "cafef00d...", "size": 2048, "mtime": 1714493000000 } }

說明

樂觀併發控制：網關會在寫入前比較 expected_sha256 與磁盤上的 sha。未命中返回 409。原子寫入經由 apps/agent/src/workspace/seed.ts::atomicWriteFile，它寫入臨時文件後再原子重命名，並在目標旁寫入單槽 .bak 備份。