属性

const world = await storvia.world.get();
// { time: "晚上 21:00", location: "秦照野的直播间" }

await storvia.world.update({
    time: "深夜 23:30",
    location: "回到家中",
});

const player = await storvia.player.get();
// { name: "小明", gender: "male", description: "冒险者", avatar: "https://..." }

await storvia.player.update({
    name: "小明",
    gender: "male",
    description: "22岁的新晋制作人",
    avatar: "https://example.com/player.png", // 可选
});

import { extractFieldValue } from "@storvia/sdk";

// 获取全部分组
const allState = await storvia.player.state.get();
// {
//   "经济": {
//     "花园币": { value: 500, type: "number", min: 0, max: 99999 },
//     "等级": { value: 3, type: "number", min: 1, max: 100 }
//   },
//   "数据": {
//     "粉丝": { value: 120, type: "number" }
//   }
// }

// 提取原始值
const coins = extractFieldValue(allState["经济"]["花园币"]); // 500

// 获取特定分组
const economy = await storvia.player.state.get("经济");

await storvia.player.state.update("经济", {
    花园币: 450, // 扣了 50 币，系统自动钳位到 [0, 99999]
    经验: 180, // 加了 30 经验
});

await storvia.player.state.remove("状态", ["中毒", "灼烧"]);

await storvia.player.state.removeGroup("临时增益");

const chars = await storvia.characters.list();
// [{
//   name: "秦照野",                    // 角色名
//   avatar: "https://...",             // 头像
//   description: "",                   // 预设角色固定为空字符串（作者人设仅 AI 可见）；自建角色为用户撰写
//   introduction: "对外介绍文本",      // 仅预设角色有意义，作者资产，SDK 只读
//   visibleAtStart: true,              // 开局是否出场，仅预设角色有意义，作者资产，SDK 只读
//   userDescription: "对我温柔一些",    // 用户补充人设
//   gender: "male",                   // "male" | "female" | "other"；老数据可能没有
//   isPreset: true                    // 是否为作者预设角色
// }, ...]

const char = await storvia.characters.get("秦照野");
// { name, avatar, description, introduction, visibleAtStart, userDescription, gender, isPreset }

await storvia.characters.add({
    name: "新角色",
    description: "一个神秘的路人",
    gender: "other", // 必填
    avatar: "img/stranger.png", // 可选
});

// 为预设角色添加用户补充人设
await storvia.characters.update("秦照野", { userDescription: "对我温柔一些" });

// 非预设角色可改 description
await storvia.characters.update("路人甲", { description: "神秘的陌生人" });

// 改头像
await storvia.characters.update("秦照野", { avatar: "img/new-avatar.png" });

// 改性别
await storvia.characters.update("秦照野", { gender: "male" });

await storvia.characters.remove("新角色");

await storvia.characters.merge("维克多", "老维");
// 「维克多」消失，它的数据全部并进「老维」

const detail = await storvia.characters.detail("秦照野");
// {
//   name: "秦照野",
//   avatar: "https://...",
//   description: "",                    // 预设角色固定为空；自建角色为用户撰写
//   introduction: "对外介绍文本",        // 仅预设角色有意义，只读
//   visibleAtStart: true,                // 仅预设角色有意义，只读
//   userDescription: "用户补充",
//   gender: "male",
//   isPreset: true,
//   state: {
//     "档案": {
//       "心情": { value: "happy", type: "text" },
//       "好感度": { value: 45, type: "number", min: 0, max: 100 }
//     }
//   }
// }

// 获取全部分组
const all = await storvia.characters.state.get("秦照野");
// {
//   "档案": {
//     "心情": { value: "happy", type: "text" },
//     "好感度": { value: 45, type: "number", min: 0, max: 100 }
//   },
//   "身份": {
//     "粉丝牌": { value: "真爱粉", type: "text" }
//   }
// }

// 获取单个分组
const profile = await storvia.characters.state.get("秦照野", "档案");

await storvia.characters.state.update("秦照野", "档案", {
    心情: "happy",
    好感度: 50, // 自动钳位到 [0, 100]
});

await storvia.characters.state.remove("秦照野", "状态", ["中毒"]);

await storvia.characters.state.removeGroup("秦照野", "临时增益");

// 让某个角色 变得重要
await storvia.characters.setPriority("路人甲", 80);

// 让 角色退居二线（下次触发上限裁剪时会被优先移除）
await storvia.characters.setPriority("过客", 10);

const rels = await storvia.relationships.list();
// [
//   { from: "玩家", to: "秦照野", "好感度": 45, "关系阶段": "朋友" },
//   { from: "玩家", to: "宋亦", "好感度": 30, "关系阶段": "认识" },
// ]

const rel = await storvia.relationships.get("玩家", "秦照野");
// { from: "玩家", to: "秦照野", "好感度": 45, "关系阶段": "朋友" }

await storvia.relationships.add({
    from: "玩家",
    to: "新角色",
    好感度: 0,
    关系阶段: "陌生",
});

await storvia.relationships.update("玩家", "秦照野", {
    好感度: 50,
    关系阶段: "朋友",
});

await storvia.relationships.remove("玩家", "新角色");

// 全部
const all = await storvia.inventory.list();
// {
//   "礼物": { "玫瑰花": { count: 3, desc: "送给主播的礼物", iconUrl: "https://.../rose.png" } },
//   "装备": {},               // 空分组也会保留
//   "仓库": { "宝箱": { count: 1, iconUrl: "https://.../chest.png" } }
// }

// 单个分组
const gifts = await storvia.inventory.list("礼物");
// { "玫瑰花": { count: 3, desc: "...", iconUrl: "https://.../rose.png" } }

await storvia.inventory.add({
    group: "礼物",
    name: "玫瑰花",
    count: 5,
    desc: "送给主播的礼物",
    iconUrl: "https://example.com/rose.png", // 可选
});

// 同时更新多个字段
await storvia.inventory.update({
    group: "礼物",
    name: "玫瑰花",
    count: 10,
    desc: "新描述",
    iconUrl: "https://example.com/rose-v2.png",
});

await storvia.inventory.remove({ group: "礼物", name: "玫瑰花" });

await storvia.inventory.removeBatch([
    { group: "礼物", name: "玫瑰花" },
    { group: "装备", name: "生锈的铁剑" },
]);

// 把随身的药水移到仓库
await storvia.inventory.move({
    fromGroup: "随身",
    toGroup: "仓库",
    name: "生命药水",
});

await storvia.inventory.ensureGroup("临时物品栏");

await storvia.inventory.removeGroup("临时物品栏"); // 仅空分组
await storvia.inventory.removeGroup("临时物品栏", { cascade: true }); // 强制删除

// 获取全部
const all = await storvia.custom.get();
// { chapter: 3, bgm: "rain", endings: { he: false, be: true } }

// 获取单个字段
const chapter = await storvia.custom.get("chapter");
// 3

// 更新平铺字段：推进到第 4 章
await storvia.custom.set({ chapter: 4 });

// 更新分组内的字段（只改 he，be 保持不变）
await storvia.custom.set({ endings: { he: true } });

// 写入并同时开启 AI 追踪
await storvia.custom.set({ chapter: 4 }, { inject: true });

await storvia.custom.setInject("chapter", true); // 开启注入
await storvia.custom.setInject("endings", false); // 整组关闭注入

const injectMap = storvia.custom.getInject();
// { chapter: true, endings: false } —— 仅含本会话显式设置过的 key

// 删除平铺字段
await storvia.custom.delete("bgm");

// 删除整个分组
await storvia.custom.delete("endings");

await storvia.custom.setGroupField("endings", "se", true);

await storvia.custom.deleteGroupField("endings", "be");

const snapshot = await storvia.state.get();

{
  current: PublicCurrentState,           // 当前活跃模块的合并快照
  previous: PublicCurrentState | null,    // 上一轮的 current（用于 before/after 对比）
  dormant: {                              // 因角色数量超出上限被移入休眠区的数据
    characters: Record<string, CharacterState>,
    relationships: Array<Record<string, unknown>>,
  }
}

{
  "current": {
    "world": {
      "time": "晚上 22:00",
      "date": "2024年3月15日",
      "location": "秦照野的直播间",
      "region": "江南水乡",
      "weather": "小雨"
    },
    "player": {
      "attributes": {
        "基础": {
          "等级": { "value": 5, "type": "number", "min": 1, "max": 100 },
          "经验": { "value": 180, "type": "number", "min": 0, "max": 9999 }
        },
        "经济": {
          "花园币": { "value": 450, "type": "number", "min": 0, "max": 99999 }
        }
      }
    },
    "characters": {
      "秦照野": {
        "isPreset": true,
        "priority": 100,
        "avatar": "https://cdn.storvia.com/avatars/qzy.png",
        "gender": "male",
        "attributes": {
          "档案": {
            "好感度": { "value": 50, "type": "number", "min": 0, "max": 100 },
            "心情": { "value": "开心", "type": "text" }
          }
        }
      },
      "路人甲": {
        "isPreset": false,
        "priority": 60,
        "gender": "other",
        "attributes": {
          "档案": {
            "好感度": { "value": 0, "type": "number", "min": 0, "max": 100 }
          }
        }
      }
    },
    "inventory": {
      "礼物": {
        "玫瑰花": { "count": 3, "desc": "送给主播的礼物", "icon_url": "https://cdn.storvia.com/items/rose.png" }
      },
      "装备": {}
    },
    "relationships": [
      { "from": "玩家", "to": "秦照野", "好感度": 50, "关系阶段": "朋友" }
    ]
  },
  "previous": {
    "world": { "time": "晚上 21:00", "...": "..." },
    "player": { "...": "..." },
    "characters": { "...": "..." },
    "inventory": { "...": "..." },
    "relationships": []
  },
  "dormant": {
    "characters": {
      "过客": {
        "isPreset": false,
        "priority": 10,
        "attributes": { "档案": { "好感度": { "value": 5, "type": "number" } } }
      }
    },
    "relationships": []
  }
}

const save = await storvia.save.get();
// {} 或上次写入的对象

// 典型存档场景
await storvia.save.set({
    chapter: 3,
    cursor: { x: 120, y: 340 },
    flags: { metAlice: true, doorUnlocked: false },
    inventory: [
        { id: "key_red", count: 1 },
        { id: "potion", count: 5 },
    ],
    history: ["scene_intro", "scene_market"],
    meta: { savedAt: Date.now(), version: 2 },
});

// 增量更新：先读再改
const cur = await storvia.save.get();
cur.flags.doorUnlocked = true;
await storvia.save.set(cur);

interface AISummary {
    content: string; // 永久记忆内容
    updated_at: string; // ISO 时间戳，最近一次写入时间
}

const m = await storvia.memory.get();
// null 或：
// { content: "主角是龙族最后的后裔，这个身份必须对王国保密。", updated_at: "2026-05-06T10:00:00.000Z" }

const updated = await storvia.memory.update("主角是龙族最后的后裔，这个身份必须对王国保密。");
// { content: "主角是龙族最后的后裔，这个身份必须对王国保密。", updated_at: "..." }

interface ExtendWorldRuleEntry {
    id: string; // 条目 id，新建时可自行生成（如 crypto.randomUUID()）
    keys: string[]; // 关键词，任一命中即触发；常驻模式忽略
    content: string; // 注入的设定
    title?: string; // 条目名，只给玩家看（≤50 字）
    constant?: boolean; // true = 常驻；缺省 false = 关键词触发（0.10.7 起）
    enabled?: boolean; // 缺省 true；false 时不注入也不扫关键词（0.10.7 起）
    widget?: boolean; // 小手机生效：true 时在小组件生成里也注入；缺省 false（0.10.7 起）
}

interface PresetWorldbookView {
    id: string; // 作者写的预设 id，开关时用它
    title: string; // 标题（≤50 字）
    description: string; // 简介，告诉玩家这条是干什么的、什么时候开
    enabled: boolean; // 当前是否开启
    constant: boolean; // true = 常驻，false = 关键词触发（0.10.7 起）
}

interface Worldbook {
    content: string; // 基础
    contentWidget: boolean; // 小手机生效：true 时基础在小组件生成里也注入（0.10.7 起）
    entries: ExtendWorldRuleEntry[]; // 高级条目
    presets: PresetWorldbookView[]; // 预设世界书清单（只读，不含正文）
    updated_at: string | null; // ISO 时间戳，从未写入过为 null
}

const wb = await storvia.memory.worldbook.get();
// null 或：
// {
//   content: "主角绝不会背叛王国；所有对话使用第二人称。",
//   contentWidget: false,
//   entries: [
//     { id: "…", keys: ["霜牙", "佩剑"], content: "主角的佩剑名为「霜牙」，祖传之物，遇血泛蓝光。", title: "佩剑", constant: false, enabled: true },
//     { id: "…", keys: [], content: "王国正处于持续三年的旱灾之中。", title: "旱灾", constant: true, enabled: false, widget: true },
//   ],
//   presets: [{ id: "ap-1", title: "雨夜模式", description: "整段剧情改在雨夜发生", enabled: false, constant: true }],
//   updated_at: "2026-09-18T10:00:00.000Z"
// }

// 只改基础
await storvia.memory.worldbook.update("主角绝不会背叛王国；所有对话使用第二人称。");

// 只改高级条目（基础不受影响）
await storvia.memory.worldbook.update({
    entries: [
        { id: crypto.randomUUID(), keys: ["霜牙", "佩剑"], content: "主角的佩剑名为「霜牙」，祖传之物，遇血泛蓝光。" },
        { id: crypto.randomUUID(), title: "旱灾", constant: true, keys: [], content: "王国正处于持续三年的旱灾之中。", widget: true },
        { id: crypto.randomUUID(), keys: ["芝麻"], content: "店里的黑猫叫芝麻，只让店主摸。", enabled: false },
    ],
});

// 开启某条预设世界书（id 从 get() 的 presets 里拿；不在清单里的 id 会被忽略）
await storvia.memory.worldbook.update({ enabledPresets: ["ap-1"] });

// 几块一起改
await storvia.memory.worldbook.update({ content: "…", entries: [], enabledPresets: [] });

interface AssetItem {
    id: number;
    name: string;
    url: string;
    assetType: "avatar" | "icon";
    category: string;
}

// 获取所有头像素材
const avatars = await storvia.getAssets("avatar");
// [
//   { id: 1, name: "骑士", url: "https://...", assetType: "avatar", category: "奇幻" },
//   { id: 2, name: "法师", url: "https://...", assetType: "avatar", category: "奇幻" },
//   ...
// ]

// 按分类获取物品图标
const weapons = await storvia.getAssets("icon", "武器");

// 用获取到的素材设置角色头像
const avatar = avatars[0];
await storvia.characters.update("骑士", { avatar: avatar.url });