hyacinth-ai 0.9.6

package/dist/world-engine/sim.js

@@ -0,0 +1,120 @@
+// ============================================================
+// world-engine / sim — 框架维护的动态对象行为
+// ============================================================
+//
+// 有一类对象不由 LLM 逐帧管理，而由框架（Ticker）按世界时间+环境自动演化：
+//   雪   —— 受温度影响融化，化尽即消失（暖天化得快，严寒缓慢升华）
+//   植物 —— 随时间生长到成熟；采摘后：一茬生消失，多茬生重新生长
+//   计时 —— 如"正在运行的面包机"，进度到 100% 变为"完成"
+//
+// 扩展只需在 BEHAVIORS 里加一个 kind → 一套规则。LLM 负责"造出来"，框架负责"养着"。
+// ============================================================
+function num(v, def) {
+    return typeof v === 'number' && !isNaN(v) ? v : def;
+}
+const snow = {
+    init(s) {
+        if (typeof s.amount !== 'number')
+            s.amount = 100;
+        s.phase = '积雪';
+    },
+    tick(s, ambient, h) {
+        const temp = num(ambient.temperature, 0);
+        if (temp > 0) {
+            // 越暖化得越快
+            s.amount -= temp * h * num(s.params?.meltFactor, 0.8);
+            s.phase = '融化中';
+        }
+        else {
+            // 严寒时缓慢升华
+            s.amount -= h * num(s.params?.sublimeFactor, 0.05);
+            s.phase = '积雪';
+        }
+        if (s.amount <= 0) {
+            s.amount = 0;
+            return false; // 化尽/蒸发 → 移除
+        }
+        return true;
+    },
+};
+const plant = {
+    init(s) {
+        if (typeof s.amount !== 'number')
+            s.amount = 0;
+        s.phase = s.amount >= 100 ? '成熟' : '生长中';
+    },
+    tick(s, _ambient, h) {
+        const rate = num(s.params?.growthRate, 100 / 24); // 默认 24 世界小时成熟
+        if (s.amount < 100)
+            s.amount = Math.min(100, s.amount + rate * h);
+        s.phase = s.amount >= 100 ? '成熟' : s.amount <= 0 ? '幼苗' : '生长中';
+        return true; // 植物不会自己消失，靠采摘处理
+    },
+};
+const timer = {
+    init(s) {
+        if (typeof s.amount !== 'number')
+            s.amount = 0;
+        s.phase = '进行中';
+    },
+    tick(s, _ambient, h) {
+        const durH = num(s.params?.durationHours, 0.1);
+        if (s.amount < 100)
+            s.amount = Math.min(100, s.amount + (100 / durH) * h);
+        s.phase = s.amount >= 100 ? '完成' : '进行中';
+        return true; // 完成后保留，等 LLM 处理（如"取出面包"）
+    },
+};
+const BEHAVIORS = { snow, plant, timer };
+/** 内置动态对象类型 */
+export function listSimKinds() {
+    return Object.keys(BEHAVIORS);
+}
+// ── 声明式自定义类型的通用解释器 ──────────────────────────
+/** 按 amount 匹配阶段标签（阈值从高到低） */
+function phaseFor(spec, amount) {
+    if (!spec.phases?.length)
+        return undefined;
+    const sorted = [...spec.phases].sort((a, b) => b.atOrAbove - a.atOrAbove);
+    return sorted.find(p => amount >= p.atOrAbove)?.label;
+}
+function initCustom(sim, spec) {
+    const max = num(spec.max, 100);
+    sim.amount = num(spec.start, spec.ratePerHour < 0 ? max : 0);
+    sim.phase = phaseFor(spec, sim.amount);
+}
+function tickCustom(sim, ambient, h, spec) {
+    const max = num(spec.max, 100);
+    const rate = spec.ratePerHour + num(spec.tempFactor, 0) * num(ambient.temperature, 0);
+    sim.amount = Math.min(max, Math.max(0, sim.amount + rate * h));
+    sim.phase = phaseFor(spec, sim.amount) ?? sim.phase;
+    if (spec.removeAtOrBelow != null && sim.amount <= spec.removeAtOrBelow)
+        return false;
+    return true;
+}
+/** 生成时初始化。内置 kind 用内置规则；自定义 kind 用声明式规则；都没有则给默认量。 */
+export function initSim(sim, customKinds = {}) {
+    const b = BEHAVIORS[sim.kind];
+    if (b) {
+        b.init(sim);
+        return;
+    }
+    const spec = customKinds[sim.kind];
+    if (spec) {
+        initCustom(sim, spec);
+        return;
+    }
+    if (typeof sim.amount !== 'number')
+        sim.amount = 100;
+}
+/** 演化一个动态对象；返回 false 表示应移除。未知 kind 不处理也不删。 */
+export function evolveSim(sim, ambient, worldHours, customKinds = {}) {
+    const b = BEHAVIORS[sim.kind];
+    if (b)
+        return b.tick(sim, ambient, worldHours);
+    const spec = customKinds[sim.kind];
+    if (spec)
+        return tickCustom(sim, ambient, worldHours, spec);
+    return true;
+}
+//# sourceMappingURL=sim.js.map

package/dist/world-engine/store.d.ts

@@ -0,0 +1,110 @@
+import type { World, WorldLocation, WorldNpc, KindSpec, EnvironmentSnapshot, CharacterInfo } from './types.js';
+export declare class WorldStore {
+    private readonly worldsDir;
+    private readonly characterName;
+    /** 内存中的当前世界快照（读的唯一来源） */
+    private world;
+    /** 写队列：保证持久化顺序执行 */
+    private writeQueue;
+    /**
+     * @param characterName 陪伴角色名（如"柔柔"）——一个角色 = 一个世界。
+     *   world.json 落在 ~/.agent/companion/<name>/world.json
+     */
+    constructor(characterName: string);
+    private worldDir;
+    private worldFilePath;
+    /**
+     * 加载活动世界到内存。若不存在则创建一个空世界并设为活动。
+     * @returns 当前内存中的世界
+     */
+    /** @returns true 表示本次是新建的空世界（供调用方决定是否注入预设） */
+    loadOrCreate(defaultName: string, now: Date): Promise<boolean>;
+    private readWorldFile;
+    /** 列出所有世界 id */
+    listWorlds(): Promise<string[]>;
+    getWorld(): World | null;
+    /** 场景地点 = 陪伴角色所在地（narrate 服务于她）；未设则回落用户地点 */
+    private sceneLocation;
+    /** 世界是否已"长出"可注入的内容（有场景地点且该地点存在） */
+    hasContent(): boolean;
+    /**
+     * 组装当前地点的环境快照。
+     * 临近可见地点只带一层摘要（desc），绝不展开其 visible——防无限递归。
+     * @param mainCharacters 始终视为"在场"的角色名（主角/陪伴），用于筛选相关社会关系。
+     */
+    readEnvironment(mainCharacters?: string[]): EnvironmentSnapshot | null;
+    /**
+     * 当前在某地点的 NPC，带主标识 id。
+     * 【未来·用户↔NPC 交互】曾有"pin 优先于日常 location"的逻辑（剧情把 NPC 钉在某地），
+     * 因触发者已移除而清理；将来重做 NPC 交互时可在此恢复 pin 优先判断。
+     */
+    npcsAt(locationId: string): Array<WorldNpc & {
+        id: string;
+    }>;
+    /** WorldTicker：更新环境 */
+    setAmbient(patch: Partial<World['ambient']>): Promise<void>;
+    /** WorldTicker：放置 NPC 到某地点（跳过被 pin 的调用方自行判断） */
+    placeNpc(npcId: string, location: string): Promise<void>;
+    /** WorldAgent：创建/更新地点（对话中"长出来"） */
+    upsertLocation(id: string, patch: Partial<WorldLocation>): Promise<void>;
+    /** WorldAgent：创建 NPC，或后续丰富其信息（世界从对话中逐渐长细节） */
+    upsertNpc(id: string, patch: Partial<WorldNpc>): Promise<void>;
+    /** WorldAgent：声明一个自定义动态类型（框架据此演化该类对象） */
+    defineKind(spec: KindSpec): Promise<void>;
+    /** WorldAgent：生成一个框架维护的动态对象（雪/植物/计时器等） */
+    spawnSimObject(id: string, kind: string, location: string, desc?: string, params?: Record<string, unknown>): Promise<void>;
+    /** WorldAgent：移除动态对象 */
+    removeSimObject(id: string): Promise<void>;
+    /** WorldAgent：设置物品的相对位置（object 在 anchor 的 relation 处），记在主角当前地点 */
+    placeObject(object: string, relation: string, anchor: string): Promise<void>;
+    /**
+     * WorldAgent：把物体搬到另一个地点（静物或动态对象都适用）。
+     * 静物：从原地点的 objects 移除、加到目标地点；动态对象：改其 location。
+     * 搬动会清掉该物品在原地的相对位置（它不再在原来的柜子上了）。
+     */
+    moveObject(object: string, to: string): Promise<void>;
+    /** WorldAgent：物体被消耗/用掉/毁坏而消失（静物或动态对象） */
+    removeObject(object: string): Promise<void>;
+    /**
+     * WorldAgent：采摘植物类动态对象。
+     * 多茬生 → 成熟度归零重新生长；一茬生 → 直接消失。
+     */
+    harvestSim(id: string): Promise<void>;
+    /** Ticker 演化时用（在 batch 内直接改 world.simObjects，此处无需单独方法） */
+    private static readonly SYMMETRIC;
+    /** WorldAgent：创建/更新一条社会关系。对称关系全自动归一化——若同对已存在任一方向的条目则原地更新，保证一对人永远只保留一条。 */
+    setRelationship(from: string, to: string, type: string, note?: string): Promise<void>;
+    /** WorldAgent：删除误建的重复角色条目（如把同一人的别名当成了独立角色）。 */
+    removeCharacter(name: string): Promise<void>;
+    /** WorldAgent：创建/更新主角或陪伴角色的动态身份信息（种族/别名/留痕）。
+     *   以规范名（如 天角兽）为键；只增补、不覆盖已有配置——旁路补学到的种族/别名/来由。 */
+    setCharacter(name: string, info: CharacterInfo): Promise<void>;
+    /** WorldAgent：删除一条社会关系（建错的、或已结束的） */
+    removeRelationship(from: string, to: string): Promise<void>;
+    /** WorldAgent：删除误建的 NPC（如把主角/陪伴角色错建成了 NPC） */
+    removeNpc(id: string): Promise<void>;
+    /** WorldAgent：移动用户/主角当前地点（用户单独行动时） */
+    moveUser(location: string): Promise<void>;
+    /** WorldAgent：移动陪伴角色当前地点（她单独行动时；narrate 的场景以此为准） */
+    moveCompanion(location: string): Promise<void>;
+    /** WorldAgent：两人一起移动（最常见）——同时更新用户与陪伴角色地点 */
+    moveBoth(location: string): Promise<void>;
+    /** WorldAgent：设置/清除对环境的临时变更 */
+    setSceneOverride(key: string, value: string | null): Promise<void>;
+    /** WorldAgent：追加事件（自动截断） */
+    addEvent(event: string): Promise<void>;
+    save(label: string): Promise<string>;
+    /**
+     * 批量修改：多处变更合并为一次持久化（供 WorldTicker 每次心跳使用）。
+     * 注意：绕过按方法的所有权约束，仅供受信任的内部模块调用。
+     */
+    batch(fn: (w: World) => void): Promise<void>;
+    private mutate;
+    /** 串行持久化当前内存世界 */
+    private persist;
+    /** 写临时文件再 rename，保证磁盘上永远是完整文件 */
+    private atomicWrite;
+    /** 等待所有挂起的写完成（stop 时调用，确保落盘） */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map