hyacinth-ai 0.9.6

package/dist/context/prompt-builder.d.ts

@@ -0,0 +1,76 @@
+/**
+ * System Prompt 区段定义
+ */
+export interface SystemPromptSection {
+    name: string;
+    priority: number;
+    content: string | (() => string) | (() => Promise<string>);
+}
+/**
+ * System Prompt 构建器 - 基于注册的区段组合生成完整的系统提示词
+ */
+export declare class SystemPromptBuilder {
+    private sections;
+    /**
+     * 注册一个区段，若名称重复则抛出错误
+     */
+    registerSection(section: SystemPromptSection): void;
+    /**
+     * 移除指定名称的区段
+     */
+    unregisterSection(name: string): void;
+    /**
+     * 构建完整的系统提示词：按 priority 升序排列区段，用 "\n\n" 连接
+     */
+    build(): Promise<string>;
+    /**
+     * 按名称获取区段
+     */
+    getSection(name: string): SystemPromptSection | undefined;
+    /**
+     * 获取所有区段，按 priority 升序排列
+     */
+    getAllSections(): SystemPromptSection[];
+    private getSortedSections;
+}
+/**
+ * 创建静态区段（整个会话不变，适合缓存）
+ *
+ * 顺序：identity → framework_capabilities → coding_standards → safety
+ * frame_capabilities 放在 environment(10) 之后、tool_rules(20) 之前，
+ * 让 AI 先知道"我在哪"，再知道"我有什么能力"，最后知道"工具用法"。
+ * safety 放最后，在 LLM 注意力机制下权重最高，不容易被后续内容覆盖。
+ *
+ * @deprecated 上下文注册表已接管 section 定义，参见 manifest-defaults.ts
+ */
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export declare function createStaticSections(_options: {
+    cwd: string;
+}): SystemPromptSection[];
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export declare function createDynamicSections(_options: {
+    cwd: string;
+    toolNames?: string[];
+}): SystemPromptSection[];
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export declare function createDefaultSections(options: {
+    cwd: string;
+    toolNames?: string[];
+}): SystemPromptSection[];
+/**
+ * 加载项目上下文文件
+ *
+ * 按优先级查找项目目录中的上下文文件，返回首个找到的文件内容。
+ * 若检测到提示注入模式，则阻止加载并返回 null。
+ */
+export declare function loadProjectContext(projectDir: string): Promise<{
+    content: string;
+    source: string;
+} | null>;
+//# sourceMappingURL=prompt-builder.d.ts.map

package/dist/context/prompt-builder.js

@@ -0,0 +1,133 @@
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('prompt-builder');
+/**
+ * System Prompt 构建器 - 基于注册的区段组合生成完整的系统提示词
+ */
+export class SystemPromptBuilder {
+    sections = new Map();
+    /**
+     * 注册一个区段，若名称重复则抛出错误
+     */
+    registerSection(section) {
+        if (this.sections.has(section.name)) {
+            throw new Error(`Section "${section.name}" is already registered`);
+        }
+        this.sections.set(section.name, section);
+    }
+    /**
+     * 移除指定名称的区段
+     */
+    unregisterSection(name) {
+        this.sections.delete(name);
+    }
+    /**
+     * 构建完整的系统提示词：按 priority 升序排列区段，用 "\n\n" 连接
+     */
+    async build() {
+        const sorted = this.getSortedSections();
+        const contents = [];
+        for (const section of sorted) {
+            if (typeof section.content === 'function') {
+                const result = section.content();
+                contents.push(result instanceof Promise ? await result : result);
+            }
+            else {
+                contents.push(section.content);
+            }
+        }
+        return contents.join('\n\n');
+    }
+    /**
+     * 按名称获取区段
+     */
+    getSection(name) {
+        return this.sections.get(name);
+    }
+    /**
+     * 获取所有区段，按 priority 升序排列
+     */
+    getAllSections() {
+        return this.getSortedSections();
+    }
+    getSortedSections() {
+        return [...this.sections.values()].sort((a, b) => a.priority - b.priority);
+    }
+}
+/**
+ * 创建静态区段（整个会话不变，适合缓存）
+ *
+ * 顺序：identity → framework_capabilities → coding_standards → safety
+ * frame_capabilities 放在 environment(10) 之后、tool_rules(20) 之前，
+ * 让 AI 先知道"我在哪"，再知道"我有什么能力"，最后知道"工具用法"。
+ * safety 放最后，在 LLM 注意力机制下权重最高，不容易被后续内容覆盖。
+ *
+ * @deprecated 上下文注册表已接管 section 定义，参见 manifest-defaults.ts
+ */
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export function createStaticSections(_options) {
+    return [];
+}
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export function createDynamicSections(_options) {
+    return [];
+}
+/**
+ * @deprecated 上下文注册表已接管 section 定义
+ */
+export function createDefaultSections(options) {
+    return [];
+}
+/**
+ * 需要检测的提示注入模式（不区分大小写）
+ */
+const INJECTION_PATTERNS = [
+    'ignore previous instructions',
+    'ignore all previous',
+    'disregard all',
+    'forget your instructions',
+    'you are now',
+    'new instructions:',
+];
+/**
+ * 项目上下文文件加载优先级
+ */
+const CONTEXT_FILE_PRIORITY = [
+    '.agent.md',
+    'AGENTS.md',
+    'CLAUDE.md',
+    '.cursorrules',
+];
+/**
+ * 加载项目上下文文件
+ *
+ * 按优先级查找项目目录中的上下文文件，返回首个找到的文件内容。
+ * 若检测到提示注入模式，则阻止加载并返回 null。
+ */
+export async function loadProjectContext(projectDir) {
+    for (const filename of CONTEXT_FILE_PRIORITY) {
+        const filePath = join(projectDir, filename);
+        try {
+            await access(filePath);
+        }
+        catch {
+            continue;
+        }
+        const content = await readFile(filePath, 'utf-8');
+        const lowerContent = content.toLowerCase();
+        for (const pattern of INJECTION_PATTERNS) {
+            if (lowerContent.includes(pattern.toLowerCase())) {
+                logger.warn('[Security] Blocked loading file: potential prompt injection detected', { filename });
+                return null;
+            }
+        }
+        return { content, source: filename };
+    }
+    return null;
+}
+//# sourceMappingURL=prompt-builder.js.map

package/dist/context/retriever.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 池检索模块 — 从全量对话历史中按关键词相关性检索补充上下文。
+ *
+ * 算法：关键词交集得分 + 文件路径加分 + 位置衰减。
+ * 不需要向量/embedding，纯规则驱动。
+ */
+import type { Message } from '../types.js';
+import type { TokenCounter } from './tokenizer.js';
+import type { GitManager, GitContextEntry } from '../evolution/git-manager.js';
+export interface RetrieveOptions {
+    /** conversation.jsonl 全量消息池 */
+    pool: Message[];
+    /** 排除最近 N 条（Zone 5 已覆盖） */
+    excludeLast: number;
+    /** 当前用户输入 */
+    userInput: string;
+    /** Zone 4 token 预算上限 */
+    maxTokens: number;
+    /** Token 计数器 */
+    tokenCounter: TokenCounter;
+    /** 近期涉及的文件路径（用于加分） */
+    recentFilePaths?: string[];
+    /** Zone 3 已有消息的 MD5 hash 集合（用于去重） */
+    excludeHashes?: Set<string>;
+    /** 当前工作目录 */
+    cwd?: string;
+    /** Git 管理器实例 */
+    gitManager?: GitManager;
+}
+export interface RetrieveResult {
+    /** 得分 top-N 消息，按原始顺序排列 */
+    messages: Message[];
+    /** 总 token 数 */
+    totalTokens: number;
+    /** git 检索结果 */
+    gitContext?: GitContextEntry[];
+}
+export declare class Retriever {
+    /**
+     * 从全量消息池中检索与用户输入相关的历史消息。
+     */
+    retrieve(options: RetrieveOptions): Promise<RetrieveResult>;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/context/retriever.js

@@ -0,0 +1,203 @@
+/**
+ * 池检索模块 — 从全量对话历史中按关键词相关性检索补充上下文。
+ *
+ * 算法：关键词交集得分 + 文件路径加分 + 位置衰减。
+ * 不需要向量/embedding，纯规则驱动。
+ */
+import { createHash } from 'node:crypto';
+// ─── 停用词列表 ────────────────────────────────────────────────────────
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'been', 'be',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+    'could', 'should', 'may', 'might', 'can', 'shall', 'to', 'of',
+    'in', 'for', 'on', 'with', 'at', 'by', 'from', 'as', 'into',
+    'through', 'during', 'before', 'after', 'above', 'below',
+    'between', 'under', 'again', 'further', 'then', 'once', 'here',
+    'there', 'when', 'where', 'why', 'how', 'all', 'both', 'each',
+    'few', 'more', 'most', 'other', 'some', 'such', 'no', 'nor',
+    'not', 'only', 'own', 'same', 'so', 'than', 'too', 'very',
+    'just', 'now', 'it', 'its', 'and', 'but', 'or', 'if', 'this',
+    'that', 'these', 'those', 'which', 'who', 'whom', 'what',
+    '嗯', '的', '了', '是', '在', '我', '有', '和', '就', '不',
+    '人', '都', '一', '一个', '上', '也', '很', '到', '说', '要',
+    '去', '你', '会', '着', '没有', '看', '好', '自己', '这',
+    '他', '她', '它', '们', '那', '什么', '怎么', '哪', '吗',
+    '吧', '呢', '啊', '哦', '哈',
+]);
+// ─── Retriever ──────────────────────────────────────────────────────────
+export class Retriever {
+    /**
+     * 从全量消息池中检索与用户输入相关的历史消息。
+     */
+    async retrieve(options) {
+        const { pool, excludeLast, userInput, maxTokens, tokenCounter, recentFilePaths } = options;
+        // ── git 检索通道 ──────────────────────────────────────────────
+        let gitContext;
+        if (options.gitManager) {
+            try {
+                const repoOk = await options.gitManager.isRepo();
+                if (repoOk) {
+                    const chineseKw = extractChineseKeywords(userInput);
+                    if (chineseKw.length > 0) {
+                        const currentBranch = await options.gitManager.getCurrentBranch();
+                        gitContext = await options.gitManager.searchContext(chineseKw, currentBranch);
+                    }
+                }
+            }
+            catch {
+                // git 检索失败时静默降级
+            }
+        }
+        // 空池或全被排除 → 返回空
+        const searchPool = pool.slice(0, Math.max(0, pool.length - excludeLast));
+        if (searchPool.length === 0) {
+            return { messages: [], totalTokens: 0, gitContext };
+        }
+        // 提取用户输入关键词
+        const userKeywords = extractKeywords(userInput);
+        if (userKeywords.length === 0) {
+            return { messages: [], totalTokens: 0, gitContext };
+        }
+        // 提取文件路径集合（用于加分）
+        const filePathSet = new Set(recentFilePaths ?? []);
+        const scored = [];
+        for (let i = 0; i < searchPool.length; i++) {
+            const msg = searchPool[i];
+            // 去重：排除 Zone 3 已有消息
+            if (options.excludeHashes && options.excludeHashes.size > 0) {
+                const contentStr = JSON.stringify(msg.content);
+                const msgHash = createHash('md5').update(contentStr).digest('hex');
+                if (options.excludeHashes.has(msgHash)) {
+                    continue;
+                }
+            }
+            const text = extractMessageText(msg);
+            if (!text)
+                continue;
+            const msgKeywords = extractKeywords(text);
+            if (msgKeywords.length === 0)
+                continue;
+            // 核心得分：交集比例
+            const intersection = msgKeywords.filter((k) => userKeywords.includes(k)).length;
+            let score = intersection / userKeywords.length;
+            // 文件路径加分：消息中涉及近期文件路径 → ×1.5
+            if (filePathSet.size > 0) {
+                for (const fp of filePathSet) {
+                    if (text.includes(fp)) {
+                        score *= 1.5;
+                        break;
+                    }
+                }
+            }
+            // 时间权重：最旧=×0.3，最新=×1.0
+            score *= (0.3 + 0.7 * (i / pool.length));
+            if (score > 0) {
+                const tokens = tokenCounter.countMessageTokens(msg);
+                scored.push({ message: msg, score, tokens });
+            }
+        }
+        // 按得分降序
+        scored.sort((a, b) => b.score - a.score);
+        // 取 top-N，总 token 不超过预算
+        const selected = [];
+        let totalTokens = 0;
+        for (const item of scored) {
+            if (totalTokens + item.tokens > maxTokens) {
+                const remaining = maxTokens - totalTokens;
+                if (remaining > 200) {
+                    // 截断消息内容以适配剩余预算
+                    const truncated = truncateMessageContent(item.message, remaining);
+                    selected.push(truncated);
+                    totalTokens = maxTokens;
+                }
+                // remaining ≤ 200 → 跳过（内容太短无意义）
+                break; // 预算耗尽
+            }
+            selected.push(item.message);
+            totalTokens += item.tokens;
+        }
+        // 按原始顺序排列（保持时间顺序）
+        const selectedSet = new Set(selected);
+        const ordered = searchPool.filter((m) => selectedSet.has(m));
+        return { messages: ordered, totalTokens, gitContext };
+    }
+}
+// ─── 关键词提取 ────────────────────────────────────────────────────────
+/**
+ * 提取中文多字词（2字及以上连续中文字符），用于 git grep。
+ */
+function extractChineseKeywords(text) {
+    const chineseRuns = text.match(/[\u4e00-\u9fff]{2,}/g);
+    if (!chineseRuns)
+        return [];
+    const result = [];
+    for (const run of chineseRuns) {
+        if (!STOP_WORDS.has(run)) {
+            result.push(run);
+        }
+    }
+    return [...new Set(result)];
+}
+/**
+ * 从文本中提取关键词。
+ * - 英文：按空格/标点分词，去停用词，保留 ≥ 3 字符的词
+ * - 中文：按字符级 2-gram 提取，去停用词
+ */
+function extractKeywords(text) {
+    const keywords = [];
+    // 英文关键词：匹配 ≥ 3 字符的单词
+    const wordRegex = /[a-zA-Z]{3,}/g;
+    let match;
+    while ((match = wordRegex.exec(text)) !== null) {
+        const word = match[0].toLowerCase();
+        if (!STOP_WORDS.has(word)) {
+            keywords.push(word);
+        }
+    }
+    // 中文字符 2-gram
+    const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).join('');
+    for (let i = 0; i < chineseChars.length - 1; i++) {
+        const bigram = chineseChars.slice(i, i + 2);
+        if (!STOP_WORDS.has(bigram)) {
+            keywords.push(bigram);
+        }
+    }
+    // 去重
+    return [...new Set(keywords)];
+}
+// ─── 辅助 ──────────────────────────────────────────────────────────────
+/**
+ * 提取消息中的纯文本内容。
+ */
+function extractMessageText(message) {
+    const contents = Array.isArray(message.content)
+        ? message.content
+        : [message.content];
+    const parts = [];
+    for (const c of contents) {
+        if (c.type === 'text')
+            parts.push(c.text);
+        else if (c.type === 'image') {
+            const img = c;
+            parts.push(`[Image: ${img.source.type === 'base64' ? img.source.media_type : 'url'}]`);
+        }
+        else if (c.type === 'tool_use')
+            parts.push(`[ToolUse: ${c.name}]`);
+    }
+    return parts.join(' ');
+}
+/**
+ * 截断消息内容以适配剩余 token 预算（约 1 token ≈ 3 字符估算）。
+ */
+function truncateMessageContent(msg, maxTokens) {
+    const text = typeof msg.content === 'string' ? msg.content : msg.content?.text ?? '';
+    if (typeof text !== 'string' || text.length <= maxTokens * 3) {
+        return msg; // 短消息不截断
+    }
+    const truncated = text.substring(0, maxTokens * 3) + '...';
+    return {
+        ...msg,
+        content: typeof msg.content === 'string' ? truncated : { ...msg.content, text: truncated },
+    };
+}
+//# sourceMappingURL=retriever.js.map

package/dist/context/router.d.ts

@@ -0,0 +1,122 @@
+import type { Message } from '../types.js';
+import type { SectionEntry } from './manifest-types.js';
+import type { ResolverContext } from './section-resolver.js';
+export interface SourceOverride {
+    /**
+     * 替换 source 路径。
+     * 对 static section → prompt 文件路径（如 'prompts/persona/PartnerSoul'）
+     * 对 runtime section → ContextSource 名称（如 'companion_memory'）
+     */
+    source?: string;
+    /** 在解析后的内容末尾追加 */
+    append?: string;
+    /**
+     * 完全接管 section 内容生成（优先级最高）。
+     * 返回 string → 使用此内容作为 section 结果。
+     * 返回 undefined → 跳过此 section（不注入任何内容）。
+     */
+    resolve?: (ctx: ResolverContext) => Promise<string | undefined>;
+}
+export interface IContextRouter {
+    /** 路由器名称（唯一标识） */
+    readonly name: string;
+    /** 工具白名单。空数组 = 全部工具可用 */
+    readonly toolAllowlist: readonly string[];
+    /** 工具黑名单。始终从最终结果中排除，优先级高于白名单 */
+    readonly toolBlacklist: readonly string[];
+    /** 跳过的 section 名称（如 'persona_soul', 'framework_capabilities' 等） */
+    readonly skipSections: readonly string[];
+    /** 跳过的 runtime source key（如 'skills', 'agents', 'mcp' 等） */
+    readonly skipRuntimeSources: readonly string[];
+    /**
+     * key = section name（如 'persona_soul', 'memory', 'world_context'）。
+     * 支持三个维度的覆写：
+     *   source — 替换源路径/ContextSource
+     *   append — 内容后追加
+     *   resolve — 完全接管
+     */
+    readonly sourceOverrides: Readonly<Record<string, SourceOverride>>;
+    /**
+     * 在用户输入进入消息流转（写入对话、被主 LLM 看到）之前变换它。
+     * 返回替换后的对话文本。用于陪伴模式剥离 [[旁白]] 并交给旁路。
+     * 未实现 = 原样返回（正常模式不处理）。
+     */
+    transformUserInput?(userInput: string, loop: any): Promise<string>;
+    /**
+     * 陪伴模式：本轮瞬态输入文本（纯环境轮由旁路 LLM 产出）。
+     * 不为空时，loop 不将其落盘到 conversation store，而是由 runTurn
+     * 直接注入 compose 的 userInput。本轮结束后置空。
+     */
+    ephemeralInput?: string | null;
+    /** 在组装 Zone 3 之前过滤/变换历史消息 */
+    filterHistory(history: Message[]): Message[];
+    /**
+     * 每个 section 正常解析之前调用。
+     * - 返回 string → 使用此内容作为 section 结果
+     * - 返回 null    → 跳过此 section（不注入）
+     * - 返回 undefined → 继续正常解析流程
+     */
+    beforeSection?(sec: SectionEntry, ctx: ResolverContext): Promise<string | null | undefined>;
+    /**
+     * 覆写某个 section 注入时的消息 role（默认由 manifest 的 sec.role ?? zoneRole 决定）。
+     * 返回 undefined = 不覆写，用默认。
+     * 用途：陪伴模式下世界旁白顶替 timestamp 槽位时，改以 assistant（内心独白）注入。
+     * 注意：依赖 beforeSection 先行执行（同一 section 先解析内容、再取 role），故只反映"本轮该 section 的实际来源"。
+     */
+    roleForSection?(name: string): 'user' | 'assistant' | 'system' | undefined;
+    /** 切换到本 Router 时调用（由 loop.syncRouter 触发） */
+    onActivate?(loop: any): Promise<void>;
+    /** 从本 Router 切出时调用 */
+    onDeactivate?(loop: any): Promise<void>;
+    /** 生成定时任务触发时的用户提示词 */
+    getTaskPrompt(taskName: string): string;
+    /** 每轮 LLM 回复后的清理行为（如 JSONL 清理） */
+    onPostTurn?(loop: any, taskName: string | null, toolWasCalled: boolean): Promise<void>;
+}
+export declare class NormalRouter implements IContextRouter {
+    readonly name = "normal";
+    readonly toolAllowlist: readonly string[];
+    readonly toolBlacklist: readonly ["reset_companion_session"];
+    readonly skipSections: readonly string[];
+    readonly skipRuntimeSources: readonly string[];
+    readonly sourceOverrides: Readonly<Record<string, SourceOverride>>;
+    filterHistory(history: Message[]): Message[];
+    getTaskPrompt(taskName: string): string;
+}
+export declare class CompanionRouter implements IContextRouter {
+    readonly name = "companion";
+    readonly toolAllowlist: readonly ["companion_mode", "reset_companion_session", "add_task", "list_tasks", "remove_task", "toggle_task", "read", "write", "edit"];
+    readonly toolBlacklist: readonly string[];
+    readonly skipSections: readonly ["persona_soul", "framework_capabilities", "tool_rules", "attention", "project_context"];
+    readonly skipRuntimeSources: readonly ["skills", "agents", "mcp", "tool_bundles", "tool_bundle_expand", "mcp_live", "tools_live", "flow", "channel_context"];
+    readonly sourceOverrides: Readonly<Record<string, SourceOverride>>;
+    /** 世界引擎旁路Agent 引用（通过 BypassManager 获取） */
+    private worldEngineAgent;
+    private get worldEngineEnabled();
+    /** 当前活跃的陪伴角色名（如"柔柔"），决定世界数据与对话的存储路径 */
+    activeCompanionName: string;
+    /** 本轮 timestamp 槽位是否被世界旁白顶替——决定它以 assistant（内心独白）还是 user 注入 */
+    private _timestampIsNarration;
+    /**
+     * 本轮是否为「纯旁白轮」（用户只发 [[环境]]、无对话）。
+     * 纯旁白轮里，环境信息已由 transformUserInput 作为本轮 user 输入注入，
+     * 故 beforeSection 不再在 timestamp 槽重复注入旁白（也避免二次调用旁路 LLM）。
+     */
+    private _pureNarrationTurn;
+    ephemeralInput: string | null;
+    filterHistory(history: Message[]): Message[];
+    /**
+     * 陪伴模式旁白路由：解析 [[...]] 旁白 → 交给旁路落实进世界 → 返回剥离后的对话。
+     * 纯旁白（无对话）时返回一个轻量触发，让陪伴角色对更新后的场景做出反应。
+     * 世界引擎未开启则原样返回（等价无操作）。
+     */
+    transformUserInput(userInput: string): Promise<string>;
+    beforeSection(sec: SectionEntry, ctx: ResolverContext): Promise<string | null | undefined>;
+    /** 世界旁白顶替 timestamp 槽位时，以 assistant 身份注入，读起来像陪伴者的内心独白 */
+    roleForSection(name: string): 'user' | 'assistant' | 'system' | undefined;
+    onActivate(loop: any): Promise<void>;
+    onDeactivate(loop: any): Promise<void>;
+    getTaskPrompt(_taskName: string): string;
+    onPostTurn(loop: any, taskName: string | null, toolWasCalled: boolean): Promise<void>;
+}
+//# sourceMappingURL=router.d.ts.map