hyacinth-ai 0.9.6

package/dist/context/section-resolver.js

@@ -0,0 +1,398 @@
+import { loadPrompt, renderPrompt } from '../prompts/loader.js';
+import { loadProjectContext } from './prompt-builder.js';
+import { Retriever } from './retriever.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getGlobalPersonaDir } from '../setup/persona-bootstrap.js';
+/** 查找旁路Agent对指定 section 的注入 */
+function findBypassInjection(sectionName, injections) {
+    if (!injections?.length)
+        return undefined;
+    return injections.find(ij => ij.section === sectionName);
+}
+export async function resolveSection(sec, ctx) {
+    // Router 的 beforeSection 钩子：在正常解析前介入
+    if (ctx.router.beforeSection) {
+        const preempted = await ctx.router.beforeSection(sec, ctx);
+        if (preempted !== undefined) {
+            return preempted || undefined; // null → undefined（跳过此 section）
+        }
+    }
+    // 旁路Agent 注入：replace 模式时替换整个 section 内容
+    const bypassInj = findBypassInjection(sec.name, ctx.bypassInjections);
+    if (bypassInj?.mode === 'replace') {
+        return bypassInj.content;
+    }
+    // 正常解析
+    let resolved;
+    switch (sec.type) {
+        case 'static':
+            resolved = resolveStatic(sec, ctx);
+            break;
+        case 'template':
+            resolved = resolveTemplate(sec, ctx);
+            break;
+        case 'runtime':
+            resolved = await resolveRuntime(sec, ctx);
+            break;
+        case 'retrieval':
+            resolved = await resolveRetrieval(sec, ctx);
+            break;
+        case 'conditional':
+            resolved = resolveConditional(sec, ctx);
+            break;
+        default: resolved = undefined;
+    }
+    // 旁路Agent 注入：append 模式时追加到正常解析结果末尾
+    if (bypassInj?.mode === 'append' && bypassInj.content) {
+        resolved = resolved ? `${resolved}\n\n${bypassInj.content}` : bypassInj.content;
+    }
+    return resolved;
+}
+// --- Static ---
+function resolveStatic(sec, ctx) {
+    const router = ctx?.router;
+    if (sec.name === 'persona_soul') {
+        // precise_mode 保持原有 activeConditions 逻辑
+        if (ctx?.activeConditions?.has('precise_mode'))
+            return undefined;
+        // Router 定义了替代 persona 来源 → 加载替代内容，跳过默认 SOUL
+        // 注：resolve 字段用于 runtime section（异步），static section 只用 source + append。
+        // 如需完全异步接管 persona，应使用 beforeSection 钩子。
+        const personaOverride = router?.sourceOverrides['persona_soul'];
+        if (personaOverride) {
+            try {
+                const effectiveSource = personaOverride.source ?? sec.source;
+                let content = loadPrompt(effectiveSource.replace(/^prompts\//, ''));
+                if (personaOverride.append) {
+                    content = content + '\n\n' + personaOverride.append;
+                }
+                return content;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return buildSoulSection() || undefined;
+    }
+    // Router 指定跳过的 section
+    if (router?.skipSections.includes(sec.name)) {
+        return undefined;
+    }
+    try {
+        return loadPrompt(sec.source.replace(/^prompts\//, ''));
+    }
+    catch {
+        return undefined;
+    }
+}
+// --- Template ---
+function resolveTemplate(sec, ctx) {
+    const vars = {};
+    if (sec.templateVars) {
+        for (const v of sec.templateVars) {
+            if (v === 'cwd')
+                vars.cwd = ctx.cwd;
+            if (v === 'toolNames') {
+                vars.toolNames = ctx.tools.map(t => t.name).join(', ') || '(无)';
+            }
+        }
+    }
+    try {
+        return renderPrompt(loadPrompt(sec.source.replace(/^prompts\//, '')), vars);
+    }
+    catch {
+        return undefined;
+    }
+}
+// --- Runtime ---
+//
+// 运行时 Section 解析器。
+//
+// Zone 布局（详见 manifest-defaults.ts）：
+//   Zone 1 (Anchor)  — 身份/环境/注册表/记忆（稳定，享受前缀缓存）
+//   Zone 2 (Manifest) — 辅助索引区（默认关闭）
+//   Zone 3 (History)  — 摘要/项目上下文/历史消息（持续增长，压缩器管理）
+//   Zone 4 (Context)  — 知识库检索（可独立开关）
+//   Zone 5 (Live)     — Flow 注入/时间戳/用户输入（每轮变化，不缓存）
+//
+// 通用回退规则：runtime:xxx → 查找 ctx.sources.get('xxx')，若存在则取其内容。
+async function resolveRuntime(sec, ctx) {
+    const src = sec.source;
+    if (src === 'runtime:plan') {
+        return ctx.currentPlan ? `[Current Plan]\n${ctx.currentPlan}` : undefined;
+    }
+    if (src === 'runtime:impact') {
+        return ctx.impactInfo ? `[Dependency Impact Analysis]\n${ctx.impactInfo}` : undefined;
+    }
+    if (src === 'runtime:summary') {
+        return ctx.historySummary ? `[Context Summary]\n${ctx.historySummary}` : undefined;
+    }
+    if (src === 'runtime:timestamp') {
+        // 时间戳的条件注入由 Router.beforeSection 控制（如 CompanionRouter 的概率注入）。
+        // 此处无条件生成时间戳文本——如果 beforeSection 返回了 null，此代码不会执行。
+        // # currentDate 是系统元数据标记（非用户输入），模型训练数据中识别为背景信息
+        const [datePart, timePart] = ctx.timestamp.split(' ');
+        const dateSlash = datePart.replace(/-/g, '/');
+        return `# currentDate\nToday is ${dateSlash}, ${timePart}.`;
+    }
+    if (src === 'runtime:userInput') {
+        return ctx.userInput || undefined;
+    }
+    if (src === 'runtime:env') {
+        const envSource = ctx.sources?.get('env-info');
+        if (envSource?.getContent) {
+            const content = await envSource.getContent();
+            return content || undefined;
+        }
+        return undefined;
+    }
+    // Router（或 profile）指定跳过的 runtime source
+    const runtimeKey = src.startsWith('runtime:') ? src.slice('runtime:'.length) : '';
+    const skipSources = ctx.router?.skipRuntimeSources ?? ctx.profile.skipRuntimeSources;
+    if (skipSources.includes(runtimeKey)) {
+        return undefined;
+    }
+    if (src === 'runtime:skills' || src === 'runtime:agents' || src === 'runtime:mcp') {
+        const kind = src.replace('runtime:', '');
+        return buildSourcePartsFromCtx(kind, ctx);
+    }
+    // 会话临时 MCP：仅收集 cacheability === 'live' 的 mcp- 源，用于 Zone 5 热插拔展示
+    if (src === 'runtime:mcp_live') {
+        return buildLiveMcpIndex(ctx);
+    }
+    // 会话临时工具：hot-reload 热添加的工具不进 Zone 2 tool_rules，而在 Zone 5 session_tools 展示
+    if (src === 'runtime:tools_live') {
+        return resolveContextSourceContent('session-tools', ctx);
+    }
+    // MCP 状态变更通知：从 ContextSource 读取并消费，注入后自动清空
+    if (src === 'runtime:mcp_status') {
+        return resolveContextSourceContent('mcp-status', ctx);
+    }
+    // 工具包索引（Zone 2）：所有 bundle 的名称 + 简介
+    if (src === 'runtime:tool_bundles') {
+        return resolveContextSourceContent('tool-bundles', ctx);
+    }
+    // 模式注入（Zone 5）：plan/spec 激活时注入提示词
+    // ── Flow 注入在 Zone 5（flow_injection），由 ContextSource 驱动 ──
+    // runtime:history 由 composer.ts assembleZone() 专门处理（展开为 Message[]）。
+    // 此处的 handler 仅作为防护：如果未来 manifest 将 history section 从 Zone 3 移走，
+    // 或 composer 的硬编码拦截被移除，此处显式返回 undefined 而非静默丢失。
+    // 架构说明见 §0.5 原则③：所有 runtime source 应在 section-resolver 中有显式路由。
+    if (src === 'runtime:history') {
+        return undefined;
+    }
+    // Router（或 profile）指定了替代 memory 来源 → 路由到对应 ContextSource
+    if (src === 'runtime:memory') {
+        const memoryOverride = ctx.router?.sourceOverrides['memory'];
+        const altSourceName = memoryOverride?.source ?? ctx.profile.memorySource;
+        if (altSourceName) {
+            const altSource = ctx.sources?.get(altSourceName);
+            if (altSource?.getContent) {
+                const content = await altSource.getContent();
+                return content || undefined;
+            }
+            return undefined;
+        }
+    }
+    if (src.startsWith('runtime:')) {
+        const key = src.slice('runtime:'.length);
+        const source = ctx.sources?.get(key);
+        if (source?.getContent) {
+            const content = await source.getContent();
+            return content || undefined;
+        }
+    }
+    return undefined;
+}
+// --- Retrieval ---
+async function resolveRetrieval(sec, ctx) {
+    const routerSkipSections = ctx.router?.skipSections ?? ctx.profile.skipSections;
+    if (routerSkipSections.includes(sec.name)) {
+        return undefined;
+    }
+    const src = sec.source;
+    if (src === 'runtime:projectContext') {
+        const projectCtx = await loadProjectContext(ctx.cwd);
+        if (projectCtx) {
+            return `[Project Context from ${projectCtx.source}]\n${projectCtx.content}`;
+        }
+        return undefined;
+    }
+    if (src === 'runtime:pool' || src === 'runtime:git') {
+        if (!ctx.fullHistory || ctx.fullHistory.length === 0)
+            return undefined;
+        const retriever = new Retriever();
+        const result = await retriever.retrieve({
+            pool: ctx.fullHistory,
+            excludeLast: 1,
+            excludeHashes: ctx.zone3Hashes,
+            userInput: ctx.userInput,
+            maxTokens: Math.floor(ctx.maxContextTokens * 0.50),
+            tokenCounter: ctx.tokenCounter,
+            gitManager: ctx.gitManager,
+            cwd: ctx.cwd,
+        });
+        if (src === 'runtime:pool' && result.messages.length > 0) {
+            const lines = ['[Context Pool Results]'];
+            for (const msg of result.messages) {
+                const text = extractTextContent(msg);
+                if (text)
+                    lines.push(`[${msg.role}] ${text}`);
+            }
+            return lines.join('\n');
+        }
+        if (src === 'runtime:git' && result.gitContext && result.gitContext.length > 0) {
+            const lines = ['[Git Context]'];
+            for (const entry of result.gitContext) {
+                const filesStr = entry.files.length > 0
+                    ? ` (涉及: ${entry.files.slice(0, 5).join(', ')}${entry.files.length > 5 ? '...' : ''})`
+                    : '';
+                lines.push(`${entry.hash} ${entry.message}${filesStr}`);
+            }
+            return lines.join('\n');
+        }
+    }
+    return undefined;
+}
+// --- Conditional ---
+function resolveConditional(sec, ctx) {
+    if (sec.condition === 'precise_mode') {
+        if (!ctx.activeConditions?.has('precise_mode'))
+            return undefined;
+        return resolveStatic(sec, ctx);
+    }
+    return undefined;
+}
+// --- Helpers ---
+const PERSONA_SOUL_FILES = ['SOUL', 'IDENTITY', 'USER'];
+export function buildSoulSection() {
+    const parts = [];
+    for (const name of PERSONA_SOUL_FILES) {
+        try {
+            const content = loadPersonaPrompt(name);
+            if (content)
+                parts.push(content);
+        }
+        catch {
+            // skip
+        }
+    }
+    return parts.length > 0 ? parts.join('\n\n---\n\n') : '';
+}
+function loadPersonaPrompt(name) {
+    const fileName = `${name}.md`;
+    const projectPath = path.join(process.cwd(), '.agent', 'prompts', 'persona', fileName);
+    if (fs.existsSync(projectPath)) {
+        return fs.readFileSync(projectPath, 'utf-8');
+    }
+    const globalPath = path.join(getGlobalPersonaDir(), fileName);
+    if (fs.existsSync(globalPath)) {
+        return fs.readFileSync(globalPath, 'utf-8');
+    }
+    return loadPrompt(`persona/${name}`);
+}
+function extractTextContent(message) {
+    const contents = Array.isArray(message.content)
+        ? message.content
+        : [message.content];
+    // Collect text from all blocks — handles [image, text] and [text, image] messages
+    const textParts = contents
+        .filter((c) => c.type === 'text')
+        .map(c => c.text);
+    if (textParts.length > 0)
+        return textParts.join('\n');
+    // Single non-text block — return type marker
+    if (contents.length === 1) {
+        if (contents[0].type === 'image')
+            return `[Image: ${contents[0].source?.media_type ?? 'unknown'}]`;
+        if (contents[0].type === 'tool_use')
+            return `[ToolUse: ${contents[0].name}]`;
+        if (contents[0].type === 'tool_result')
+            return `[ToolResult: ${contents[0].tool_use_id}]`;
+    }
+    return null;
+}
+/** 从指定名称的 ContextSource 读取内容 */
+function resolveContextSourceContent(sourceName, ctx) {
+    if (!ctx.sources)
+        return undefined;
+    const source = ctx.sources.get(sourceName);
+    if (!source?.getContent)
+        return undefined;
+    const content = source.getContent();
+    const text = typeof content === 'string' ? content : '';
+    return text || undefined;
+}
+/**
+ * 收集所有 cacheability === 'live' 的 MCP 源，生成会话临时 MCP 索引。
+ * 用于 Zone 5 session_mcp section — 热插拔 MCP 不进 Zone 2，避免破坏前缀缓存。
+ * 下次启动时这些 MCP 会自动归位到 Zone 2（cacheability 变为 'manifest'）。
+ */
+function buildLiveMcpIndex(ctx) {
+    if (!ctx.sources)
+        return undefined;
+    // 收集匹配的 live MCP 源，按 name 排序保证输出稳定
+    const matchedSources = [];
+    for (const [, source] of ctx.sources) {
+        if (source.cacheability !== 'live')
+            continue;
+        if (!source.name.startsWith('mcp-'))
+            continue;
+        matchedSources.push(source);
+    }
+    matchedSources.sort((a, b) => a.name.localeCompare(b.name));
+    if (matchedSources.length === 0)
+        return undefined;
+    const parts = matchedSources.map((source) => `- ${source.name}: ${source.description ?? '(no description)'}`);
+    return `会话临时 MCP — 本次对话可用\n${parts.join('\n')}`;
+}
+function buildSourcePartsFromCtx(kind, ctx) {
+    if (!ctx.sources)
+        return undefined;
+    const prefix = kind === 'mcp' ? 'mcp-' : `${kind}-`;
+    const parts = [];
+    // 收集匹配的 source，按 name 显式排序以保证输出稳定可预测。
+    // 这确保了即使 Map 插入顺序因热插拔 remove+re-add 而改变，Zone 2 文本字节布局也不变，最大化前缀缓存命中率。
+    const matchedSources = [];
+    for (const [, source] of ctx.sources) {
+        if (source.cacheability !== 'manifest')
+            continue;
+        if (kind !== 'mcp' && !source.name.startsWith(prefix))
+            continue;
+        if (kind === 'mcp' && !source.name.startsWith('mcp-'))
+            continue;
+        matchedSources.push(source);
+    }
+    matchedSources.sort((a, b) => a.name.localeCompare(b.name));
+    for (const source of matchedSources) {
+        switch (source.strategy) {
+            case 'always_inline':
+                parts.push(`- ${source.name}: ${source.description ?? '(no description)'}`);
+                break;
+            case 'index_only':
+                parts.push(`- ${source.name}: ${source.description ?? '(no description)'}`);
+                break;
+            case 'lazy_expand': {
+                const isSelected = kind === 'skill'
+                    ? ctx.selectedSkills?.includes(source.name.replace('skill-', ''))
+                    : kind === 'agent'
+                        ? ctx.selectedAgents?.includes(source.name.replace('agent-', ''))
+                        : false;
+                if (isSelected && source.getContent) {
+                    const content = source.getContent();
+                    const text = typeof content === 'string' ? content : '';
+                    parts.push(`- ${source.name}: ${text}`);
+                }
+                else {
+                    parts.push(`- ${source.name}: ${source.description ?? '(lazy: expand on use)'}`);
+                }
+                break;
+            }
+            case 'phase_bound':
+                break;
+        }
+    }
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+//# sourceMappingURL=section-resolver.js.map

package/dist/context/tokenizer.d.ts

@@ -0,0 +1,23 @@
+import type { Message } from '../types.js';
+export declare class TokenCounter {
+    #private;
+    /**
+     * Count tokens for a plain text string.
+     */
+    countTokens(text: string): number;
+    /**
+     * Count tokens for a single Message object.
+     *
+     * Overhead model:
+     *  - 4 tokens per message for role framing
+     *  - TextContent:       text tokens + 4
+     *  - ToolUseContent:    JSON.stringify(input) tokens + name tokens + 4
+     *  - ToolResultContent: content tokens + 4
+     */
+    countMessageTokens(message: Message): number;
+    /**
+     * Count tokens for an array of messages.
+     */
+    countMessagesTokens(messages: Message[]): number;
+}
+//# sourceMappingURL=tokenizer.d.ts.map

package/dist/context/tokenizer.js

@@ -0,0 +1,78 @@
+import { encodingForModel } from 'js-tiktoken';
+// --- Lazy singleton encoding ---
+let _encoding = null;
+function getEncoding() {
+    if (!_encoding) {
+        _encoding = encodingForModel('gpt-4');
+    }
+    return _encoding;
+}
+// --- TokenCounter ---
+export class TokenCounter {
+    /**
+     * Count tokens for a plain text string.
+     */
+    countTokens(text) {
+        return getEncoding().encode(text).length;
+    }
+    /**
+     * Count tokens for a single Message object.
+     *
+     * Overhead model:
+     *  - 4 tokens per message for role framing
+     *  - TextContent:       text tokens + 4
+     *  - ToolUseContent:    JSON.stringify(input) tokens + name tokens + 4
+     *  - ToolResultContent: content tokens + 4
+     */
+    countMessageTokens(message) {
+        let tokens = 4; // role overhead per message
+        const contents = Array.isArray(message.content)
+            ? message.content
+            : [message.content];
+        for (const part of contents) {
+            tokens += this.#countContentTokens(part);
+        }
+        return tokens;
+    }
+    /**
+     * Count tokens for an array of messages.
+     */
+    countMessagesTokens(messages) {
+        return messages.reduce((sum, msg) => sum + this.countMessageTokens(msg), 0);
+    }
+    #countContentTokens(content) {
+        switch (content.type) {
+            case 'text': {
+                const tc = content;
+                return this.countTokens(tc.text) + 4;
+            }
+            case 'tool_use': {
+                const tuc = content;
+                const inputTokens = this.countTokens(JSON.stringify(tuc.input));
+                const nameTokens = this.countTokens(tuc.name);
+                return inputTokens + nameTokens + 4;
+            }
+            case 'thinking': {
+                const tc = content;
+                return this.countTokens(tc.thinking) + 4;
+            }
+            case 'tool_result': {
+                const trc = content;
+                return this.countTokens(trc.content) + 4;
+            }
+            case 'image': {
+                const img = content;
+                if (img.source.type === 'url')
+                    return 1000; // 远程 URL，保守估算
+                // base64: decoded ≈ data.length * 0.75 bytes, ~1 token per 4 bytes
+                return Math.max(1, Math.ceil(img.source.data.length * 0.75 / 4)) + 4;
+            }
+            default: {
+                // Unknown content type — best-effort: stringify and count
+                const _exhaustive = content;
+                return this.countTokens(JSON.stringify(_exhaustive)) + 4;
+            }
+        }
+    }
+}
+//# sourceMappingURL=tokenizer.js.map

package/dist/dependency/analyzer.d.ts

@@ -0,0 +1,33 @@
+import type { DependencyGraph, ImpactResult } from './types.js';
+import type { GitManager } from '../evolution/git-manager.js';
+export declare class DependencyAnalyzer {
+    private parser;
+    private graph;
+    private fileHashes;
+    private rootDir;
+    private projectKey;
+    private cachePath;
+    /** 分析项目，构建依赖图（优先加载缓存） */
+    analyze(rootDir: string): Promise<DependencyGraph>;
+    /** 全量构建依赖图 */
+    private fullBuild;
+    /** 增量更新：重新解析变更文件，更新依赖图 */
+    incrementalUpdate(changedFiles?: string[], gitManager?: GitManager): Promise<void>;
+    /** 构建正向和反向索引 */
+    private buildIndexes;
+    /** 查询影响面：修改 file 后，哪些文件会受影响 */
+    getImpact(file: string, symbol?: string): ImpactResult;
+    /** 获取依赖图（只读） */
+    getGraph(): Readonly<DependencyGraph> | null;
+    /** 获取 projectKey */
+    getProjectKey(): string;
+    /** 序列化 DependencyGraph 为可存储的 JSON 格式 */
+    private serialize;
+    /** 反序列化 JSON 为 DependencyGraph */
+    private deserialize;
+    /** 从磁盘加载缓存 */
+    private loadCache;
+    /** 保存缓存到磁盘 */
+    private saveCache;
+}
+//# sourceMappingURL=analyzer.d.ts.map