聊天

storvia.chat.send({
  message: string,       // 必填：用户消息内容
  topic?: string,        // 可选：话题标识，隔离对话历史
  sceneKey?: string,      // 可选：场景 key，引用创作台预设的场景设定
  extract?: { start, end },  // 可选：内容过滤规则，详见「内容过滤」章节
  stream?: boolean,      // 可选：是否流式输出（默认 false）
  onChunk?: (text) => void,         // stream=true 时：收到文本片段的回调
  onDone?: (id, info) => void,      // stream=true 时：生成完成的回调，id 为消息UUID，info.truncated 表示回复是否被截断
  onState?: (delta, full) => void,  // stream=true 时：AI 本轮有属性变更时触发；非流式通过返回值的 delta/full 字段获取
  onThinking?: (status) => void,    // stream=true 时：模型 reasoning 状态变更（'start' = 开始思考，'end' = 开始输出正文），仅支持思考型模型
  onCreatedCharacters?: (names) => void,  // 本轮出现「真·新角色」时触发；非流式通过返回值的 createdNames 字段获取
  onReconnecting?: ({ attempt }) => void, // 仅流式：生成中途断线、SDK 自动重连时触发，attempt 为第几次重连（1 起，最多 10 次）
  onAborted?: ({ id, persisted }) => void, // 仅流式：生成被 cancel() 中断时触发（提供后不再触发 onDone）；persisted:false 表示零内容未入库
})

const reply = await storvia.chat.send({
    message: "你好",
    topic: "dm_npc1",
    sceneKey: "dm_scene",
});

console.log(reply.id); // 消息 UUID
console.log(reply.content); // AI 回复内容

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "干嘛，这么晚找我？",
  "delta": { ... },
  "full": { ... },
  "truncated": false
}

{
    "world": {
        "time": "晚上 22:00",
        "location": "秦照野的直播间"
    },
    "player": {
        "经验": 180
    },
    "characters": [
        {
            "id": "秦照野",
            "op": "update",
            "attrs": { "好感度": 50, "心情": "开心" }
        },
        {
            "id": "路人甲",
            "op": "add",
            "attrs": { "好感度": 0 }
        }
    ],
    "items": [
        { "name": "玫瑰花", "op": "add", "count": 3 },
        { "name": "旧钥匙", "op": "remove" }
    ],
    "relations": [
        {
            "from": "玩家",
            "to": "秦照野",
            "op": "update",
            "好感度": 50,
            "关系阶段": "朋友"
        }
    ],
    "locations": [
        {
            "name": "秘密基地",
            "op": "add",
            "region": "城东",
            "description": "隐蔽的据点"
        }
    ]
}

await storvia.chat.send({
    message: "你好",
    topic: "dm_npc1",
    sceneKey: "dm_scene",
    stream: true,
    onChunk: (text) => {
        // 每收到一个文本片段就会调用
        // text 是增量内容，不是完整内容
        chatBubble.textContent += text;
    },
    onDone: (id) => {
        // 流式输出完成
        console.log("消息ID:", id);
    },
    onState: (delta, full) => {
        // AI 本轮有属性变更时触发（仅在确实改动了世界/玩家/角色等字段时）
        // delta 是本轮的变更内容（增量），full 是合并后的完整快照
        console.log("好感度变了:", delta.characters);
        updateUI(full.current);
    },
});

data: {"type":"start"}

data: {"type":"thinking","status":"start"}
data: {"type":"thinking","status":"end"}

data: {"content":"干"}
data: {"content":"嘛"}

data: {"type":"state_updating","updating":true}
data: {"type":"state_updating","updating":false}

data: {"type":"state","delta":{...},"full":{...}}

data: {"type":"done","id":"550e8400-...","truncated":false}
data: [DONE]

storvia.chat.save({
  role: 'user' | 'assistant',  // 必填：消息角色
  content: string,              // 必填：消息内容
  topic?: string,               // 可选：话题标识
})

{
    id: string;
} // 保存的消息 UUID

// 保存一条用户消息到群聊话题
await storvia.chat.save({
    role: "user",
    content: "大家好！",
    topic: "group_chat",
});

// 也可以保存 AI 消息（比如本地生成的内容）
await storvia.chat.save({
    role: "assistant",
    content: "欢迎回来～",
    topic: "group_chat",
});

storvia.chat.generate({
  topic?: string,        // 可选：话题标识
  sceneKey?: string,      // 可选：场景 key
  extract?: { start, end },  // 可选：内容过滤规则，详见「内容过滤」章节
  stream?: boolean,      // 可选：是否流式（默认 false）
  onChunk?: (text) => void,
  onDone?: (id, info) => void,
  onState?: (delta, full) => void,
  onThinking?: (status) => void,    // 同 send()，仅思考型模型触发
  onCreatedCharacters?: (names) => void,  // 同 send()：本轮出现「真·新角色」时触发
  onReconnecting?: ({ attempt }) => void, // 同 send()：断线自动重连时触发
  onAborted?: ({ id, persisted }) => void, // 同 send()：被 cancel() 中断时触发（提供后不再触发 onDone）
})

// 角色在群聊中回复（AI 能看到 group_chat 的历史，包括之前 save 的消息）
const reply = await storvia.chat.generate({
    topic: "group_chat",
    sceneKey: "group_chat_scene",
});

console.log(reply.content); // "哟，稀客"

storvia.chat.retry({
  topic?: string,        // 可选：重试指定 topic 下的最后一条 AI 消息
  sceneKey?: string,      // 可选：场景 key
  extract?: { start, end },  // 可选：内容过滤规则，详见「内容过滤」章节
  stream?: boolean,      // 可选：是否流式（默认 false）
  onChunk?: (text) => void,
  onDone?: (id, info) => void,
  onState?: (delta, full) => void,
  onThinking?: (status) => void,    // 同 send()，仅思考型模型触发
  onCreatedCharacters?: (names) => void,  // 同 send()：本轮出现「真·新角色」时触发
  onReconnecting?: ({ attempt }) => void, // 同 send()：断线自动重连时触发
  onAborted?: ({ id, persisted }) => void, // 同 send()：被 cancel() 中断时触发（提供后不再触发 onDone）
})

const reply = await storvia.chat.retry({
    topic: "dm_npc1",
    sceneKey: "dm_scene",
});

console.log(reply.content); // 新生成的回复

await storvia.chat.retry({
    topic: "dm_npc1",
    sceneKey: "dm_scene",
    stream: true,
    onChunk: (text) => {
        chatBubble.textContent += text;
    },
    onDone: (id) => {
        console.log("重新生成完成，消息ID:", id);
    },
});

storvia.chat.continue({
  topic?: string,        // 可选：续写该 topic 下最新的 AI 消息；不传 = 续写整个会话里最新的那条 AI 消息
  sceneKey?: string,     // 可选：场景 key；续写场景消息时须带上原样 key，详见「场景设定」章节
  extract?: { start, end },  // 可选：内容过滤规则；续写 extract 模式的消息时须带上原样规则，详见「内容过滤」章节
  onChunk?: (text) => void,             // 收到文本片段的回调（增量，不是完整内容）
  onDone?: (id, info) => void,          // 续写完成的回调；id 为消息 UUID，info.truncated 表示补完后是否仍被截断
  onState?: (delta, full) => void,      // AI 本轮有属性变更时触发；delta 是增量，full 是合并后的完整快照
  onThinking?: (status) => void,        // 模型 reasoning 状态变更（'start' = 开始思考，'end' = 开始输出正文），仅思考型模型
  onReconnecting?: ({ attempt }) => void,   // 生成中途断线、SDK 自动重连时触发；attempt 为第几次重连（1 起，最多 10 次），用于提示「正在重新连接」
  onAborted?: ({ id, persisted }) => void,  // 被停止按钮中断时触发（提供后不再触发 onDone）；persisted:false 表示零内容未入库，需把玩家输入放回输入框
})

// 1. 生成刚结束时：onDone 的第二个参数
await storvia.chat.send({
    message: playerInput,
    stream: true,
    onChunk: (text) => appendToBubble(text),
    onDone: (id, info) => {
        if (info?.truncated) showContinueButton(id); // 没写完 → 给个「继续」按钮
    },
});

// 2. 刷新 / 重进游戏后：chat.messages() 每条消息都带 truncated
const { data } = await storvia.chat.messages({ order: "desc", limit: 20 });
for (const m of data) {
    renderMessage(m);
    if (m.role === "assistant" && m.truncated) showContinueButton(m.uuid);
}

await storvia.chat.continue({
    onChunk: (text) => {
        lastBubble.textContent += text; // 追加到原气泡，不是新建一条
    },
    onDone: (id, info) => {
        hideContinueButton();
        if (info?.truncated) showContinueButton(id); // 补完后又截断了 → 可以再续
    },
});

const result = await storvia.chat.cancel({
  topic?: string,   // 可选：停哪条支线的生成；缺省 = 主线
});
// result: { active: boolean, generationId?: string }

// 发起生成时挂上 onAborted
await storvia.chat.send({
    message: playerInput,
    stream: true,
    onChunk: (text) => appendToBubble(text),
    onDone: (id, info) => resetUI(),
    onAborted: ({ persisted }) => {
        resetUI();
        if (!persisted) {
            inputBox.value = playerInput; // 零内容中断：把玩家的话放回输入框
        }
    },
});

// 停止按钮
stopBtn.onclick = async () => {
    stopBtn.disabled = true;
    const { active } = await storvia.chat.cancel();
    if (!active) {
        // 生成已经跑完了，不会再有 aborted 事件，正常的 done 已经在流里
        stopBtn.disabled = false;
    }
    // active: true → 什么都不用做，等 onAborted 收尾
};

await storvia.chat.send({
    message: "你好",
    topic: "dm_npc1",
    stream: true,
    onChunk: (text) => {
        chatBubble.textContent += text;
    },
    onDone: (id) => {
        hideReconnectingTip();
    },
    onReconnecting: ({ attempt }) => {
        // 每次发起重连前触发，attempt 从 1 递增（最多 10 次）
        showReconnectingTip(`连接中断，正在重新连接… (${attempt}/10)`);
    },
});

storvia.chat.resume({
  topic?: string,
  onChunk?: (text) => void,
  onDone?: (id, info) => void,
  onState?: (delta, full) => void,
  onThinking?: (status) => void,
  onReconnecting?: ({ attempt }) => void,
  onAborted?: ({ id, persisted }) => void,  // SDK 0.9：接管的生成被中断
}): Promise<void>

async function enterConversation(topic) {
    // 1. 先渲染历史消息
    const history = await storvia.chat.messages({ order: "desc", topic });
    renderMessages(history.data);

    // 2. 直接接管在途生成：有就实时续读，没有则静默返回
    //    ⚠️ 气泡要「等第一个 chunk 到了再建」，别无条件先建：
    //    没有在途时 onChunk / onDone 都不会触发，提前建的空气泡会永远留在界面上。
    let bubble = null;
    await storvia.chat.resume({
        topic,
        onChunk: (text) => {
            if (!bubble) bubble = appendStreamingBubble(); // 首个 chunk 到达才建气泡
            bubble.textContent += text;
        },
        onDone: () => {
            if (bubble) markBubbleDone(bubble);
        },
    });
}

storvia.chat.messages({
  order: 'asc' | 'desc',             // 必填：asc=从旧到新（历史展示），desc=从新到旧（聊天框）
  limit?: number,                     // 可选：单次最大返回条数，1-50，默认 20
  topic?: string,                     // 可选：按 topic 过滤，不传则返回全部
  cursor?: {                          // 可选：翻页游标，首次不传
    uuid: string,
    createdAt: string,
  },
})

{
  data: Array<{
    uuid: string,
    role: 'user' | 'assistant',
    content: string,
    topic: string | null,
    status: string,
    model: string | null,
    createdAt: string,
    truncated: boolean,   // SDK 0.9 起：能否免费续写。AI 回复被截断没写完=true；正常写完 / user 消息 / 用户主动停止=false
  }>,
  hasMore: boolean,                    // 是否还有更多消息
  nextCursor: { uuid, createdAt } | null, // 下一页游标；直接传给下次调用的 cursor 字段
}

// 首次加载：最新 20 条
let result = await storvia.chat.messages({
    order: "desc",
    topic: "dm_npc1",
});
renderMessages(result.data);

// 用户向上滚动，加载更旧的消息
if (result.hasMore) {
    result = await storvia.chat.messages({
        order: "desc",
        topic: "dm_npc1",
        cursor: result.nextCursor,
    });
    prependMessages(result.data);
}

// 首次加载：最旧 20 条
let result = await storvia.chat.messages({
    order: "asc",
    topic: "dm_npc1",
});
renderMessages(result.data);

// 用户向下滚动，加载更新的消息
if (result.hasMore) {
    result = await storvia.chat.messages({
        order: "asc",
        topic: "dm_npc1",
        cursor: result.nextCursor,
    });
    appendMessages(result.data);
}

storvia.chat.edit({
  uuid: string;
  content: string;
}): Promise<{
  uuid: string;
  role: string;
  content: string;
  updatedAt: string;
}>;

// 1. 通过 messages() 拿到目标消息的 uuid
const list = await storvia.chat.messages({ order: "desc", limit: 10 });
const target = list.data[0];

// 2. 编辑文本
const updated = await storvia.chat.edit({
    uuid: target.uuid,
    content: "修改后的内容",
});
console.log(updated.content); // "修改后的内容"
console.log(updated.updatedAt); // 新的 ISO 时间戳

storvia.chat.delete({
  uuid: string;
}): Promise<{
  uuid: string;
}>;

// 1. 通过 messages() 拿到目标消息的 uuid
const list = await storvia.chat.messages({ order: "desc", limit: 10 });
const target = list.data[0];

// 2. 删除该消息
const { uuid } = await storvia.chat.delete({ uuid: target.uuid });
console.log("已删除:", uuid);

storvia.chat.rollback({
  uuid: string;
}): Promise<{
  deletedCount: number;
  deletedUuids: string[];
  restoredGameState: { current: unknown; dormant: unknown } | null;
}>;

// 1. 通过 messages() 拿到目标消息的 uuid
const list = await storvia.chat.messages({ order: "asc", limit: 100 });
const checkpoint = list.data[10]; // 想回到第 11 条消息

// 2. 回溯
try {
    const r = await storvia.chat.rollback({ uuid: checkpoint.uuid });
    console.log(`已删除 ${r.deletedCount} 条后续消息`);
    if (r.restoredGameState) {
        console.log("状态已从快照恢复:", r.restoredGameState);
    }
} catch (err) {
    if (err.code === "DAISY_CARD_REQUIRED") {
        showUpgradePrompt("回溯功能仅限雏菊卡会员使用");
    } else if (err.code === "MESSAGE_TOO_OLD") {
        showToast("该消息已超过 30 天，无法回溯");
    } else {
        throw err;
    }
}

// 1. 玩家发消息 → 保存到 group_chat topic
await storvia.chat.save({
    role: "user",
    content: "大家晚上好！",
    topic: "group_chat",
});

// 2. 请求秦照野回复
// AI 能看到 group_chat 历史中的「大家晚上好！」
const reply1 = await storvia.chat.generate({
    topic: "group_chat",
    sceneKey: "group_chat_scene",
});
showMessage("秦照野", reply1.content);

// 3. 请求宋亦回复
// AI 能看到玩家的消息 + 秦照野的回复
const reply2 = await storvia.chat.generate({
    topic: "group_chat",
    sceneKey: "group_chat_scene",
});
showMessage("宋亦", reply2.content);

// 和秦照野的私聊，始终传同一个 topic
await storvia.chat.send({ message: "你好", topic: "dm_qin_zhaoye" });
await storvia.chat.send({ message: "昨天的事情…", topic: "dm_qin_zhaoye" }); // AI 能看到上一条

// ✅ 推荐：固定 topic，首次用 generate，后续重复生成走 retry
const first = await storvia.chat.generate({
    topic: "danmaku",
    sceneKey: "danmaku_scene",
});

// 用户点击"换一条" —— 覆盖上一条，不产生新消息
const next = await storvia.chat.retry({
    topic: "danmaku",
    sceneKey: "danmaku_scene",
});

const reply = await storvia.chat.send({
    message: "你好",
    topic: "dm_npc1",
    sceneKey: "dm_scene", // 引用创作台预设的场景设定
});

await storvia.chat.continue({
    topic: "dm_npc1",
    sceneKey: "dm_scene", // 与被续写消息发送时保持一致
    onChunk: (text) => appendText(text),
});

请严格按以下格式输出，不要有任何额外文字：
<title>标题文本</title>
<summary>一段摘要</summary>
<tags>标签1,标签2,标签3</tags>

const reply = await storvia.chat.send({ message, sceneKey: "card_scene" });
const title = reply.content.match(/<title>([\s\S]*?)<\/title>/)?.[1];
const summary = reply.content.match(/<summary>([\s\S]*?)<\/summary>/)?.[1];
const tags = reply.content.match(/<tags>([\s\S]*?)<\/tags>/)?.[1]?.split(",");

const reply = await storvia.chat.send({
    message: "你好",
    topic: "main",
    extract: { start: "<reply>", end: "</reply>" },
});

// reply.content 包含首尾标记 + 中间内容
// 例如 AI 输出 "让我想想...<reply>干嘛，这么晚找我？</reply>"
// reply.content → "<reply>干嘛，这么晚找我？</reply>"
console.log(reply.content);

try {
    const reply = await storvia.chat.send({
        message: "你好",
        stream: true,
        onChunk: (text) => {
            chatBubble.textContent += text;
        },
        onDone: (id) => {
            console.log("完成:", id);
        },
    });
} catch (err) {
    // err 是 StorviaError，err.code 是机器可读的错误码
    switch (err.code) {
        case "NETWORK_ERROR":
            showError("网络异常，请检查连接");
            break;
        case "REQUEST_TIMEOUT":
            showError("请求超时，请稍后重试");
            break;
        case "MODEL_LOADING_TIMEOUT":
            showError("模型响应超时，请稍后重试");
            break;
        case "STREAM_INACTIVITY":
            showError("连接已中断，请重试");
            break;
        case "STREAM_INTERRUPTED":
            showError("回复已中断，请重试");
            break;
        case "GENERATION_TIMEOUT":
            showError("生成超时，请重试");
            break;
        case "REPETITION_LOOP":
            showError("回复出现重复，请重试或换个说法");
            break;
        case "SAVE_FAILED":
            showError("消息保存失败，本次不扣费，请重试");
            break;
        case "MODEL_REFUSAL":
            showError("模型拒绝响应，换个说法试试");
            break;
        case "CONTENT_FILTERED":
            showError("内容被安全策略拦截，请调整后重试");
            break;
        case "VIOLATION_WORD_DETECTED":
            showError("内容含有违禁词，请修改后重试");
            break;
        case "INSUFFICIENT_CREDITS":
            /* SDK 已自动弹钱包引导，通常无需额外处理 */ break;
        case "RATE_LIMITED":
            showError("操作过于频繁，请稍后再试");
            break;
        default:
            showError("出了点小问题，请稍后重试");
            break;
    }
}

let reply;
try {
    reply = await storvia.chat.send({ message, sceneKey: "card_scene" });
} catch (err) {
    // 第①②类：内容根本没回来 —— 按 code 提示（见上一节）
    showError(mapErrorByCode(err.code));
    return;
}

// 内容已经成功返回（reply.content 一定有值）。开始尝试解析：
const title = reply.content.match(/<title>([\s\S]*?)<\/title>/)?.[1];
const summary = reply.content.match(/<summary>([\s\S]*?)<\/summary>/)?.[1];

if (!title || !summary) {
    // ❗解析失败：不要 return、不要报网络错误
    console.warn("[解析失败] 原始内容:", reply.content);
    // ✅ 1) 把 AI 原文显示出来，让用户至少能读到内容
    renderRawFallback(reply.content);
    // ✅ 2) 给一条准确的提示（不是「网络错误」）
    showWarning("本次回复格式异常，已为你显示原文，可点「重试」重新生成");
    // ✅ 3) 暴露重试入口
    showRetryButton();
    return;
}

// 解析成功，正常渲染卡片
renderCard({ title, summary });

const title = reply.content.match(/<title>([\s\S]*?)<\/title>/)?.[1];
if (!title) {
    showError("网络异常，请检查连接"); // ❌ 内容明明回来了，却误报网络错误
    return; // ❌ AI 已产出的内容被静默丢弃，用户白扣费
}