封存與預設

跑通完整本機範例

按快速開始啟動後端。把下面的內容存為儲存庫根目錄的 docs-first-room.mjs。每次執行會建立一個教學房間，新增一個角色和一個數值變數，產生實際封存，並把讀取到的快照保存在本機。它不會呼叫模型。

import { writeFile } from 'node:fs/promises';
const base = process.env.TEA_API || 'http://127.0.0.1:4318';
async function api(path, body) {
  const response = await fetch(base + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}
const { room } = await api('/api/rooms', { name: 'Docs tea room', description: 'A local tutorial room' });
const prefix = `/api/rooms/${encodeURIComponent(room.id)}`;
await api(`${prefix}/characters`, { name: 'Guide', personality: 'Patient and precise', background: 'Hosts the tea room', speaking_style: 'Short sentences', description: 'Tutorial character' });
await api(`${prefix}/variables/set`, { name: 'danger', value: 0 });
const { archive } = await api(`${prefix}/archives`, { title: 'First local archive' });
const snapshot = await api(`${prefix}/archives/${encodeURIComponent(archive.id)}`);
await writeFile('docs-room-archive.json', JSON.stringify(snapshot, null, 2));
console.log(JSON.stringify({ roomId: room.id, archiveId: archive.id, characters: snapshot.room.characters.length, variables: snapshot.room_variables, saved: 'docs-room-archive.json' }, null, 2));

然後執行：

node docs-first-room.mjs
node scripts/export-room-template.mjs docs-room-archive.json docs-room-template

一切順利的話，docs-room-archive.json 包含剛建立的房間和變數，docs-room-template/template.json 包含 schema_version: 1、一個房間、Guide 角色以及值為 0 的 danger。ID 和時間戳記每次都不同。API 回傳非 2xx 時指令稿會停止——不要拿上次留下的檔案當這次執行成功的依據。

保留與省略的內容

封存是包含對話記錄的快照。匯出指令稿則保留可重用的初始設定：角色、房間/全域變數、情勢欄、世界資訊和行為規則，但會省略訊息歷史。不過，描述、角色文字和世界資訊仍然可能含有個人資訊，分享預設之前也要檢查這些欄位。

封存會記錄 variable_displays，但目前版本的 export-room-template.mjs 沒有把它複製到匯出的預設裡。如果你需要原始的 HUD 標籤和數值範圍，保留封存檔案，在編寫預設時再手動補上對應定義。不要把這個匯出當成可以完整往返還原的備份。

使用儲存庫範例作為參考

公開原始碼裡的 examples/templates/agent-room-basic/template.json 展示了角色、danger 變數、顯示設定、世界資訊和條件行為規則。其中條件範例在 danger ≥ 8 時啟動。本指南沒有宣稱存在一鍵匯入或匯出按鈕——經過驗證的匯出方式就是上面的命令。為新工作台準備設定時，可以參考原始碼裡的 template-authoring 說明。