hyacinth-ai 0.9.6

package/dist/bypass/agents/world-engine/types.d.ts

@@ -0,0 +1,202 @@
+/** 环境 —— WorldTicker 独占写 */
+export interface Ambient {
+    /** 世界内时间（ISO 字符串） */
+    time: string;
+    /** 时段（清晨/上午/下午/晚上…），由 time 推导。世界时间经 timeScale 折算、与现实时钟脱钩，模型无法凭数字判断昼夜，故显式给出 */
+    period: string;
+    weather: string;
+    season: string;
+    temperature: number;
+}
+/** 物品的空间相对位置：object 在 anchor 的 relation 处（如 花瓶 在 柜子 上） */
+export interface ObjectPlacement {
+    object: string;
+    /** 关系：上/里/下/旁边/附近 等 */
+    relation: string;
+    /** 参照物（另一件物品或家具，如"柜子""床"） */
+    anchor: string;
+}
+/** 地点 —— WorldAgent 增长/精修 */
+export interface WorldLocation {
+    desc: string;
+    /** 地点内的物品 */
+    objects: string[];
+    /** 物品的相对摆放（花瓶在柜子上、柜子在床旁），由 WorldAgent 维护 */
+    layout?: ObjectPlacement[];
+    /** 临近可见地点 id（读取时只带一层摘要，不再展开——防无限递归） */
+    visible: string[];
+    /** 可移动到的地点 id */
+    connects: string[];
+    /** 主人（角色名，如"柔柔"）。为空表示公共场所。主人在此地是主人不是客人 */
+    owner?: string;
+}
+/**
+ * NPC —— desc/persona/home/roaming/mobility 由 WorldAgent 创建后只读；
+ * location 由 WorldTicker 概率放置；state 由 WorldAgent 更新。
+ */
+export interface WorldNpc {
+    desc: string;
+    /** 别名/其他称呼（昵称、头衔、全名等），如 徐青 的 aliases=[小青, 蛋糕店老板]。由 WorldAgent 维护 */
+    aliases?: string[];
+    /** 种族/物种（如"兔子""天马"）——属性，非身份；同族不同个体各建各的记录。由 WorldAgent 维护 */
+    race?: string;
+    /** 认知留痕：这个 NPC 的身份是如何被逐渐了解的（初见→得知名字/性格/住处…）。由 WorldAgent 维护 */
+    note?: string;
+    /** 人设，喂给 NPC 回应生成 */
+    persona: string;
+    /** 常驻地点 id（可多个） */
+    home: string[];
+    /** 0..1，离开 home 去邻近地点的概率 */
+    roaming: number;
+    /** anchored=基本不动 / free=会到处逛 */
+    mobility: 'anchored' | 'free';
+    /** 当前实际位置（Ticker 写） */
+    location: string;
+    /** 当前状态描述（Agent 写） */
+    state: string;
+}
+/**
+ * 社会关系（有向边）。可连接任意角色：主角 / 陪伴角色 / NPC。
+ * 语义："to 是 from 的 <type>"。对称关系（朋友/恋人）记一条即可；
+ * 有方向的（宠物：安吉尔是柔柔的宠物 → from=柔柔 to=安吉尔 type=宠物）方向有意义。
+ * 由 observe agent 依对话判断更新——不随时间自动变化。
+ */
+export interface Relationship {
+    from: string;
+    to: string;
+    /** 关系类型：陌生人 / 朋友 / 好友 / 恋人 / 家人 / 宠物 / 主人 / 同事 ... */
+    type: string;
+    /** 可选补充说明（如"刚认识，还有些拘谨"） */
+    note?: string;
+}
+/**
+ * 角色身份的动态补充（旁路随对话逐渐"认识"一个角色时积累的信息）。
+ * 以角色【规范名】为键（个体），与配置身份叠加。由 observe agent 依对话演变。
+ *
+ * 关键：race（种族）是"属性"，不是"身份键"——同种族的不同个体各有各的记录，
+ * 绝不因同族而合并。别名（aliases）只统一"同一个体的多个称呼"，从不跨个体。
+ */
+export interface CharacterInfo {
+    /** 种族/物种（如"天马""独角兽"）。属性，非身份键 */
+    race?: string;
+    /** 旁路学到的其他称呼（名字/昵称/外号/全名）；与配置 aliases 取并集，都指同一个体 */
+    aliases?: string[];
+    /** 认知留痕：这个角色的身份是如何被逐渐了解的（初见只知种族 → 第N轮得知名字 → 后来知道昵称…） */
+    note?: string;
+}
+/**
+ * 声明式自定义动态类型：让 LLM 用受限的规则（而非代码）定义新的动态对象种类，
+ * 框架按规则演化。用于内置 snow/plant/timer 覆盖不了的东西（融化的冰淇淋、燃烧的蜡烛…）。
+ */
+export interface KindSpec {
+    kind: string;
+    desc?: string;
+    /** amount 每"世界小时"的基础变化率（正=增长/积累，负=衰减/消耗） */
+    ratePerHour: number;
+    /** 温度影响：有效速率 += tempFactor × 当前温度（如冰淇淋 tempFactor<0，越热化越快） */
+    tempFactor?: number;
+    /** amount 上限，默认 100 */
+    max?: number;
+    /** amount ≤ 此值则移除该对象（如融化殆尽消失）；不填=不自动移除 */
+    removeAtOrBelow?: number;
+    /** 初始 amount；不填时：衰减型默认满值，增长型默认 0 */
+    start?: number;
+    /** 阶段标签，按 amount 阈值从高到低匹配 */
+    phases?: Array<{
+        atOrAbove: number;
+        label: string;
+    }>;
+}
+/**
+ * 框架维护的动态对象：由 Ticker 按世界时间+环境自动演化（雪/植物/计时器等）。
+ * LLM 负责"造出来"（world_spawn_sim），框架负责演化。见 sim.ts。
+ */
+export interface SimObject {
+    id: string;
+    /** 行为类型：snow / plant / timer / …（决定演化规则） */
+    kind: string;
+    /** 所在地点 id */
+    location: string;
+    desc?: string;
+    /** 通用动态量 0-100：雪量 / 植物成熟度 / 计时进度 */
+    amount: number;
+    /** 当前阶段标签：积雪/融化中；生长中/成熟；进行中/完成 */
+    phase?: string;
+    /** kind 相关参数（如 plant 的 multiHarvest/growthRate、timer 的 durationHours） */
+    params?: Record<string, unknown>;
+}
+/** 动态状态 —— WorldAgent 独占写 */
+export interface WorldState {
+    /** 用户/主角当前所在地点 id */
+    location: string;
+    /** 陪伴角色（如柔柔）当前所在地点 id。narrate 服务于主 LLM，故以此作为"她的场景"；多数时候与 location 相同（在一起） */
+    companionLocation: string;
+    /** 对基础环境的临时变更（如 "灯关了"） */
+    sceneOverrides: Record<string, string>;
+    /** 最近发生的事（有上限，见 WorldStore.MAX_EVENTS） */
+    recentEvents: string[];
+    /** 主角/陪伴角色的动态身份补充（旁路随对话学到的种族/别名/认知留痕），以规范名为键，与配置身份叠加 */
+    characters: Record<string, CharacterInfo>;
+}
+export interface WorldMeta {
+    id: string;
+    name: string;
+    createdAt: string;
+}
+/** 一个完整的世界 */
+export interface World {
+    meta: WorldMeta;
+    ambient: Ambient;
+    locations: Record<string, WorldLocation>;
+    npcs: Record<string, WorldNpc>;
+    /** 社会关系图（有向边），由 observe agent 依对话演变 */
+    relationships: Relationship[];
+    /** 框架维护的动态对象（雪/植物/计时器等） */
+    simObjects: Record<string, SimObject>;
+    /** LLM 声明的自定义动态类型（内置类型之外） */
+    customKinds: Record<string, KindSpec>;
+    state: WorldState;
+}
+/** readEnvironment() 的返回：当前地点的环境快照（供旁白化） */
+export interface EnvironmentSnapshot {
+    /** 场景地点 = 陪伴角色所在地（narrate 服务于她） */
+    location: string;
+    /** 用户/主角当前所在地点（与 location 相同则两人同场） */
+    userLocation: string;
+    /** 用户/主角是否也在此场景（与陪伴角色同地） */
+    userPresent: boolean;
+    desc: string;
+    /** 地点主人（角色名）；为空表示公共场所 */
+    owner?: string;
+    objects: string[];
+    /** 物品相对摆放（花瓶在柜子上…） */
+    layout: ObjectPlacement[];
+    /** 对基础环境的临时变更 */
+    sceneOverrides: Record<string, string>;
+    ambient: Ambient;
+    /** 临近可见地点（单层摘要） */
+    visible: Array<{
+        id: string;
+        desc: string;
+    }>;
+    /** 当前在场的 NPC（含其主标识 id） */
+    npcs: Array<WorldNpc & {
+        id: string;
+    }>;
+    /** 与当前场景相关的社会关系（涉及主角/陪伴/在场 NPC） */
+    relationships: Relationship[];
+    /** 主角/陪伴角色的动态身份补充（种族/别名/留痕），供旁白按规范名叠加渲染 */
+    characters: Record<string, CharacterInfo>;
+    /** 当前地点的动态对象（雪/植物/计时器等） */
+    simObjects: SimObject[];
+    /** 最近事件（截断） */
+    recentEvents: string[];
+}
+/**
+ * 由小时（0-23）推导"时段"标签。世界时间经 timeScale 折算、与现实时钟脱钩，
+ * 模型无法凭 "09:50" 这样的数字判断是上午还是晚上，故显式给出语义标签。
+ */
+export declare function periodOf(hour: number): string;
+/** 创建一个空世界（world 从对话中生长，初始无地点/NPC） */
+export declare function createEmptyWorld(id: string, name: string, now: Date): World;
+//# sourceMappingURL=types.d.ts.map

package/dist/bypass/agents/world-engine/types.js

@@ -0,0 +1,56 @@
+// ============================================================
+// world-engine / types — 世界数据结构
+// ============================================================
+//
+// world.json 的 schema。世界从对话中"长出来"：初始为空，
+// 后置 WorldAgent 根据对话逐渐创建地点/物品/NPC。
+//
+// 写入者所有权（关键约束，由工具层强制）：
+//   ambient          → WorldTicker 独占
+//   locations        → WorldAgent 创建/精修
+//   npcs 静态字段     → WorldAgent 创建后只读（desc/persona/home/roaming/mobility）
+//   npcs.location    → WorldTicker 放置
+//   state.*          → WorldAgent 独占（当前位置 / 场景变更 / 最近事件 / 社会关系等）
+// ============================================================
+/**
+ * 由小时（0-23）推导"时段"标签。世界时间经 timeScale 折算、与现实时钟脱钩，
+ * 模型无法凭 "09:50" 这样的数字判断是上午还是晚上，故显式给出语义标签。
+ */
+export function periodOf(hour) {
+    if (hour < 5)
+        return '凌晨';
+    if (hour < 8)
+        return '清晨';
+    if (hour < 11)
+        return '上午';
+    if (hour < 13)
+        return '中午';
+    if (hour < 17)
+        return '下午';
+    if (hour < 19)
+        return '傍晚';
+    if (hour < 23)
+        return '晚上';
+    return '深夜';
+}
+/** 创建一个空世界（world 从对话中生长，初始无地点/NPC） */
+export function createEmptyWorld(id, name, now) {
+    const iso = now.toISOString();
+    return {
+        meta: { id, name, createdAt: iso },
+        ambient: { time: iso, period: periodOf(now.getHours()), weather: '晴', season: '春', temperature: 20 },
+        locations: {},
+        npcs: {},
+        relationships: [],
+        simObjects: {},
+        customKinds: {},
+        state: {
+            location: '',
+            companionLocation: '',
+            sceneOverrides: {},
+            recentEvents: [],
+            characters: {},
+        },
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/bypass/agents/world-engine.d.ts

@@ -0,0 +1,20 @@
+import type { ModelRouterLike } from '../../world-engine/agent.js';
+import type { BypassAgent, PreTurnContext, PostTurnContext, PreTurnResult } from '../types.js';
+export declare class WorldEngineAgent implements BypassAgent {
+    readonly name = "world-engine";
+    readonly modes: string[];
+    readonly modelChannel = "narration";
+    private engine;
+    private characterName;
+    constructor(characterName: string, modelRouter: ModelRouterLike | null);
+    get enabled(): boolean;
+    /** 设置本轮用户旁白（在 transformUserInput 中调用） */
+    setPendingNarration(text: string): void;
+    /** 直接调用旁白生成（纯旁白轮用，不走 bypassManager.preTurn） */
+    narrate(): Promise<string | undefined>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    preTurn(ctx: PreTurnContext): Promise<PreTurnResult>;
+    postTurn(ctx: PostTurnContext): Promise<void>;
+}
+//# sourceMappingURL=world-engine.d.ts.map

package/dist/bypass/agents/world-engine.js

@@ -0,0 +1,63 @@
+// ============================================================
+// bypass/agents/world-engine — WorldEngine BypassAgent 适配
+// ============================================================
+//
+// 将现有的 WorldEngine 包装为 BypassAgent 接口。
+// 不修改 WorldEngine 内部代码，只做接口适配。
+//
+// 映射：
+//   preTurn  → narrate()    环境 → 旁白，注入 timestamp section
+//   postTurn → observe()    观察对话 → 更新世界状态
+//   start/stop → 现有实现
+// ============================================================
+import { WorldEngine } from '../../world-engine/index.js';
+export class WorldEngineAgent {
+    name = 'world-engine';
+    modes = ['companion'];
+    modelChannel = 'narration';
+    engine;
+    characterName;
+    constructor(characterName, modelRouter) {
+        this.characterName = characterName;
+        this.engine = new WorldEngine(characterName, modelRouter);
+    }
+    // ── 遗留 API（CompanionRouter 仍使用这些方法） ──────────────
+    get enabled() {
+        return this.engine.enabled;
+    }
+    /** 设置本轮用户旁白（在 transformUserInput 中调用） */
+    setPendingNarration(text) {
+        this.engine.setPendingNarration(text);
+    }
+    /** 直接调用旁白生成（纯旁白轮用，不走 bypassManager.preTurn） */
+    async narrate() {
+        return this.engine.narrate();
+    }
+    // ── BypassAgent 接口 ────────────────────────────────────────
+    async start() {
+        await this.engine.start();
+    }
+    async stop() {
+        await this.engine.stop();
+    }
+    async preTurn(ctx) {
+        const narration = await this.engine.narrate();
+        if (!narration) {
+            return { injections: [] };
+        }
+        return {
+            injections: [
+                {
+                    section: 'timestamp',
+                    content: narration,
+                    role: 'assistant',
+                    mode: 'replace',
+                },
+            ],
+        };
+    }
+    async postTurn(ctx) {
+        this.engine.observe(ctx.userInput, ctx.assistantOutput);
+    }
+}
+//# sourceMappingURL=world-engine.js.map

package/dist/bypass/base.d.ts

@@ -0,0 +1,48 @@
+import type { Message, ToolDefinition, StreamEvent } from '../types.js';
+import type { BypassAgent, PreTurnContext, PostTurnContext, PreTurnResult } from './types.js';
+/** 只依赖结构化接口，不耦合具体 provider 实现 */
+export interface ProviderLike {
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+}
+export interface ModelRouterLike {
+    getProvider(role: string): ProviderLike | null;
+}
+export interface BypassAgentConfig {
+    name: string;
+    modes: string[];
+    modelChannel: string;
+    /** 工具定义列表 */
+    tools: ToolDefinition[];
+    /** 工具分发器 */
+    executeTool(name: string, input: Record<string, unknown>): Promise<string>;
+}
+export declare abstract class BypassAgentBase implements BypassAgent {
+    readonly name: string;
+    readonly modes: string[];
+    readonly modelChannel: string;
+    protected tools: ToolDefinition[];
+    protected modelRouter: ModelRouterLike | null;
+    protected readonly _config: BypassAgentConfig;
+    /** BypassManager 引用（由 BypassManager.register 注入） */
+    protected _manager: import('./manager.js').BypassManager | null;
+    constructor(config: BypassAgentConfig);
+    /** 设置模型路由（由 BypassManager 或 factory 注入） */
+    setModelRouter(router: ModelRouterLike | null): void;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract preTurn(ctx: PreTurnContext): Promise<PreTurnResult>;
+    abstract postTurn(ctx: PostTurnContext): Promise<void>;
+    /** 获取当前通道的 Provider */
+    protected getProvider(): ProviderLike | null;
+    /**
+     * 单次 LLM 调用（无工具循环）。
+     * 返回 LLM 生成的纯文本。
+     */
+    protected callLLM(systemPrompt: string, userPrompt: string): Promise<string>;
+    /**
+     * 带工具循环的 LLM 调用。
+     * 底层循环：调 LLM → 执行工具（并行/串行）→ 结果喂回 LLM → 直到无工具调用或达到上限。
+     */
+    protected callLLMWithTools(systemPrompt: string, userPrompt: string, maxIters?: number): Promise<string>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/bypass/base.js

@@ -0,0 +1,126 @@
+// ============================================================
+// bypass/base — BypassAgentBase
+// ============================================================
+//
+// 提供所有旁路Agent的通用能力：
+//   - 模型通道调用
+//   - 工具循环（并行优先，有依赖串行）
+//   - 异常隔离（永不抛给调用方）
+//   - 状态持久化
+//
+// 具体Agent只需提供：
+//   - 系统提示词
+//   - 工具定义和执行函数
+//   - preTurn/postTurn 的提示词构建逻辑
+//   - 内部状态结构与持久化路径
+// ============================================================
+/** 最大工具循环轮数 */
+const MAX_TOOL_ITERS = 5;
+// ── BypassAgentBase ───────────────────────────────────────────
+export class BypassAgentBase {
+    name;
+    modes;
+    modelChannel;
+    tools;
+    modelRouter = null;
+    _config;
+    /** BypassManager 引用（由 BypassManager.register 注入） */
+    _manager = null;
+    constructor(config) {
+        this._config = config;
+        this.name = config.name;
+        this.modes = config.modes;
+        this.modelChannel = config.modelChannel;
+        this.tools = config.tools;
+    }
+    /** 设置模型路由（由 BypassManager 或 factory 注入） */
+    setModelRouter(router) {
+        this.modelRouter = router;
+    }
+    // ── 受保护的 LLM 调用辅助 ──────────────────────────────────
+    /** 获取当前通道的 Provider */
+    getProvider() {
+        return this.modelRouter?.getProvider(this.modelChannel) ?? null;
+    }
+    /**
+     * 单次 LLM 调用（无工具循环）。
+     * 返回 LLM 生成的纯文本。
+     */
+    async callLLM(systemPrompt, userPrompt) {
+        try {
+            const provider = this.getProvider();
+            if (!provider)
+                return '';
+            const messages = [
+                { role: 'system', content: [{ type: 'text', text: systemPrompt }] },
+                { role: 'user', content: [{ type: 'text', text: userPrompt }] },
+            ];
+            let text = '';
+            for await (const ev of provider.createStream(messages)) {
+                if (ev.type === 'TEXT')
+                    text += ev.content;
+            }
+            return text.trim();
+        }
+        catch {
+            return ''; // 旁路失败不影响主流程
+        }
+    }
+    /**
+     * 带工具循环的 LLM 调用。
+     * 底层循环：调 LLM → 执行工具（并行/串行）→ 结果喂回 LLM → 直到无工具调用或达到上限。
+     */
+    async callLLMWithTools(systemPrompt, userPrompt, maxIters = MAX_TOOL_ITERS) {
+        try {
+            const provider = this.getProvider();
+            if (!provider)
+                return '';
+            const messages = [
+                { role: 'system', content: [{ type: 'text', text: systemPrompt }] },
+                { role: 'user', content: [{ type: 'text', text: userPrompt }] },
+            ];
+            const allText = [];
+            for (let i = 0; i < maxIters; i++) {
+                const toolCalls = [];
+                const textParts = [];
+                for await (const ev of provider.createStream(messages, this.tools)) {
+                    if (ev.type === 'TEXT')
+                        textParts.push(ev.content);
+                    else if (ev.type === 'TOOL_USE')
+                        toolCalls.push({ id: ev.id, name: ev.name, input: ev.input });
+                    else if (ev.type === 'STOP')
+                        break;
+                }
+                // 记录本轮文本
+                if (textParts.length)
+                    allText.push(...textParts);
+                // 无工具调用 → 完成
+                if (toolCalls.length === 0)
+                    break;
+                // 添加 assistant 消息（含工具调用）
+                const assistantContent = [];
+                if (textParts.length)
+                    assistantContent.push({ type: 'text', text: textParts.join('') });
+                for (const tc of toolCalls) {
+                    assistantContent.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.input });
+                }
+                messages.push({ role: 'assistant', content: assistantContent });
+                // 并行执行工具（无依赖的并行，有依赖的串行后面再优化）
+                const results = await Promise.all(toolCalls.map(async (tc) => {
+                    const result = await this._config.executeTool(tc.name, tc.input);
+                    return {
+                        type: 'tool_result',
+                        tool_use_id: tc.id,
+                        content: result,
+                    };
+                }));
+                messages.push({ role: 'user', content: results });
+            }
+            return allText.join('').trim();
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/bypass/index.d.ts

@@ -0,0 +1,5 @@
+export type { BypassAgent, PreTurnContext, PostTurnContext, PreTurnResult, Injection, } from './types.js';
+export { BypassAgentBase } from './base.js';
+export type { BypassAgentConfig, ProviderLike, ModelRouterLike } from './base.js';
+export { BypassManager } from './manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/bypass/index.js

@@ -0,0 +1,6 @@
+// ============================================================
+// bypass — 旁路Agent 模块
+// ============================================================
+export { BypassAgentBase } from './base.js';
+export { BypassManager } from './manager.js';
+//# sourceMappingURL=index.js.map

package/dist/bypass/manager.d.ts

@@ -0,0 +1,41 @@
+import type { BypassAgent, PreTurnContext, PostTurnContext, Injection } from './types.js';
+import type { ModelRouterLike } from './base.js';
+export declare class BypassManager {
+    /** 所有已注册的Agent */
+    private registry;
+    /** 当前激活的Agent列表 */
+    private active;
+    /** 模型路由引用（注入后所有Agent共享） */
+    private modelRouter;
+    /** 注入模型路由（factory 初始化后调用） */
+    setModelRouter(router: ModelRouterLike): void;
+    /** 注册一个旁路Agent */
+    register(agent: BypassAgent): void;
+    /** 取消注册 */
+    unregister(name: string): void;
+    /** 根据模式名激活对应的旁路Agent */
+    activateForMode(modeName: string): Promise<void>;
+    /** 手动激活指定Agent（TUI命令用） */
+    activateAgent(name: string): Promise<void>;
+    /** 手动停用指定Agent（TUI命令用） */
+    deactivateAgent(name: string): Promise<void>;
+    /** 停用所有Agent */
+    deactivateAll(): Promise<void>;
+    /** 某Agent是否激活 */
+    isActive(name: string): boolean;
+    /** 获取已注册的Agent（用于直接访问Agent特有方法，如 setPendingNarration） */
+    getAgent(name: string): BypassAgent | undefined;
+    /** 获取激活列表 */
+    getActiveNames(): string[];
+    /** 运行时注入：旁路Agent 在 postTurn 中可调用此方法写入纠正内容 */
+    private _pendingInjections;
+    inject(agentName: string, injection: import('./types.js').Injection): void;
+    /** 消费待注入内容（由 Loop 在 compose 前调用） */
+    consumeInjections(): import('./types.js').Injection[];
+    preTurn(ctx: PreTurnContext): Promise<{
+        transformedInput?: string;
+        injections: Injection[];
+    }>;
+    postTurn(ctx: PostTurnContext): void;
+}
+//# sourceMappingURL=manager.d.ts.map