hyacinth-ai 0.9.6

package/dist/cli/doctor.js

@@ -0,0 +1,317 @@
+/**
+ * hyacinth doctor — 系统诊断 + 自动修复
+ *
+ * 检查项：
+ *   1. 运行环境（Node 版本、OS、编码）
+ *   2. 依赖完整性（sharp、chokidar、better-sqlite3）
+ *   3. 原生模块（better-sqlite3 .node 二进制）
+ *   4. Persona 文件（是否仍是模板？显示原始提示词）
+ *   5. 配置文件（~/.agent/config.json）
+ *   6. 知识库状态（kb.sqlite、files/ 目录）
+ *   7. API Key 检测
+ *
+ * --fix 参数自动安装缺失依赖
+ */
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+// ── 原始 Persona 提示词（运行时从文件读取，避免内嵌不同步）─────────
+function loadOriginalPrompts() {
+    const sources = ['src/prompts/persona', 'dist/prompts/persona'];
+    const files = ['SOUL.md', 'IDENTITY.md', 'USER.md'];
+    const result = {};
+    for (const f of files) {
+        for (const dir of sources) {
+            const p = path.join(process.cwd(), dir, f);
+            if (fs.existsSync(p)) {
+                result[f] = fs.readFileSync(p, 'utf-8');
+                break;
+            }
+        }
+    }
+    return result;
+}
+// ── 检查项 ───────────────────────────────────────────────────────────
+function checkNodeEnv() {
+    const v = process.version;
+    const major = parseInt(v.slice(1).split('.')[0]);
+    return {
+        label: 'Node.js 版本',
+        ok: major >= 18,
+        detail: `${v} (需要 >= 18)`,
+        fix: major < 18 ? '升级 Node.js 到 v18 或以上' : undefined,
+    };
+}
+function checkEncoding() {
+    const cp = process.env.CODEPAGE || '';
+    const isUtf8 = cp === '65001' || process.platform !== 'win32';
+    return {
+        label: '终端编码',
+        ok: isUtf8,
+        detail: isUtf8 ? 'UTF-8' : `CP${cp} (推荐 chcp 65001)`,
+    };
+}
+function checkPersona() {
+    const personaDir = path.join(os.homedir(), '.agent', 'prompts', 'persona');
+    const files = ['SOUL.md', 'IDENTITY.md', 'USER.md', 'BOOTSTRAP.md'];
+    const existing = [];
+    const missing = [];
+    for (const f of files) {
+        const p = path.join(personaDir, f);
+        if (fs.existsSync(p))
+            existing.push(f);
+        else
+            missing.push(f);
+    }
+    const hasBootstrap = existing.includes('BOOTSTRAP.md');
+    return {
+        label: 'Persona 文件',
+        ok: existing.length >= 3 && !hasBootstrap,
+        detail: hasBootstrap
+            ? `BOOTSTRAP.md 仍存在 — 需要完成身份初始化（${existing.length}/4 文件存在）`
+            : missing.length > 0
+                ? `缺失: ${missing.join(', ')}`
+                : `完整 (${existing.length}/4 文件，bootstrap 已完成)`,
+        fix: missing.length > 0
+            ? '运行 hyacinth setup 完成初始化'
+            : hasBootstrap
+                ? '启动 TUI 并完成身份对话，或运行 hyacinth setup'
+                : undefined,
+    };
+}
+function checkDeps() {
+    const failures = [];
+    const deps = ['sharp', 'chokidar', 'better-sqlite3'];
+    for (const dep of deps) {
+        try {
+            require.resolve(dep);
+        }
+        catch {
+            failures.push(dep);
+        }
+    }
+    return {
+        label: '核心依赖',
+        ok: failures.length === 0,
+        detail: failures.length > 0 ? `缺失: ${failures.join(', ')}` : '全部就绪',
+        fix: failures.length > 0 ? `pnpm install (缺失: ${failures.join(', ')})` : undefined,
+    };
+}
+function checkNativeModule() {
+    try {
+        const m = require.resolve('better-sqlite3');
+        // 尝试加载验证
+        require(m);
+        return { label: '原生模块 (better-sqlite3)', ok: true, detail: '已加载' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            label: '原生模块 (better-sqlite3)',
+            ok: false,
+            detail: msg.slice(0, 120),
+            fix: 'pnpm rebuild better-sqlite3 或 pnpm approve-builds',
+        };
+    }
+}
+function checkConfig() {
+    const configPath = path.join(os.homedir(), '.agent', 'config.json');
+    if (!fs.existsSync(configPath)) {
+        return {
+            label: '配置文件',
+            ok: false,
+            detail: '~/.agent/config.json 不存在',
+            fix: '运行 hyacinth setup 完成配置',
+        };
+    }
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        JSON.parse(raw);
+        return { label: '配置文件', ok: true, detail: configPath };
+    }
+    catch {
+        return {
+            label: '配置文件',
+            ok: false,
+            detail: 'JSON 解析失败',
+            fix: '检查 ~/.agent/config.json 格式，或删除后重新 setup',
+        };
+    }
+}
+function checkKnowledgeBase() {
+    const kbDir = path.join(os.homedir(), '.agent', 'knowledge');
+    const dbPath = path.join(kbDir, 'kb.sqlite');
+    const filesDir = path.join(kbDir, 'files');
+    const hasDb = fs.existsSync(dbPath);
+    const hasFiles = fs.existsSync(filesDir);
+    if (!hasDb && !hasFiles) {
+        return {
+            label: '知识库',
+            ok: true,
+            detail: '未初始化（首次启动时自动创建）',
+        };
+    }
+    let docCount = 0;
+    if (hasDb) {
+        try {
+            // 尝试读取 SQLite 统计
+            const Database = require('better-sqlite3');
+            const db = new Database(dbPath, { readonly: true });
+            const row = db.prepare('SELECT COUNT(*) as cnt FROM docs').get();
+            docCount = row.cnt;
+            db.close();
+        }
+        catch {
+            // 忽略
+        }
+    }
+    const parts = [];
+    if (hasDb)
+        parts.push(`SQLite: ${docCount} 条`);
+    if (hasFiles) {
+        const fileCount = fs.readdirSync(filesDir).filter(f => !f.startsWith('.')).length;
+        parts.push(`files/: ${fileCount} 个文件`);
+    }
+    return {
+        label: '知识库',
+        ok: true,
+        detail: parts.join(' | '),
+    };
+}
+function checkApiKeys() {
+    const envKeys = [
+        'ANTHROPIC_API_KEY',
+        'OPENAI_API_KEY',
+        'DEEPSEEK_API_KEY',
+        'GEMINI_API_KEY',
+        'MINIMAX_API_KEY',
+        'GROQ_API_KEY',
+    ];
+    const found = [];
+    for (const k of envKeys) {
+        if (process.env[k])
+            found.push(k);
+    }
+    if (found.length > 0) {
+        return {
+            label: 'API Keys (环境变量)',
+            ok: true,
+            detail: `${found.length} 个: ${found.map(k => k.split('_')[0]).join(', ')}`,
+        };
+    }
+    // 检查 config.json
+    const configPath = path.join(os.homedir(), '.agent', 'config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.provider?.apiKey || config.providers) {
+                return { label: 'API Keys', ok: true, detail: '已配置于 config.json' };
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return {
+        label: 'API Keys',
+        ok: false,
+        detail: '未检测到任何 API Key',
+        fix: '运行 hyacinth setup 配置 Provider 和 API Key',
+    };
+}
+export async function runDoctor(opts = {}) {
+    console.log('🔧 hyacinth doctor\n');
+    // ── 显示原始提示词 ────────────────────────────────────────────
+    if (opts.showPrompts) {
+        console.log('═══ 原始 Persona 提示词 ═══\n');
+        for (const [name, content] of Object.entries(loadOriginalPrompts())) {
+            console.log(`── ${name} ──\n`);
+            console.log(content);
+            console.log();
+        }
+        console.log('═══ 提示词结束 ═══\n');
+        return;
+    }
+    // ── 运行诊断 ──────────────────────────────────────────────────
+    const checks = [
+        checkNodeEnv(),
+        checkEncoding(),
+        checkDeps(),
+        checkNativeModule(),
+        checkPersona(),
+        checkConfig(),
+        checkKnowledgeBase(),
+        checkApiKeys(),
+    ];
+    let allOk = true;
+    const needsFix = [];
+    for (const c of checks) {
+        const icon = c.ok ? '✅' : '❌';
+        console.log(`${icon} ${c.label}: ${c.detail}`);
+        if (!c.ok) {
+            allOk = false;
+            if (c.fix)
+                needsFix.push(c.fix);
+        }
+    }
+    console.log();
+    if (allOk) {
+        console.log('✅ 所有检查通过。');
+        return;
+    }
+    console.log('修复建议：');
+    for (const f of needsFix) {
+        console.log(`  → ${f}`);
+    }
+    // ── 自动修复 ──────────────────────────────────────────────────
+    if (opts.fix) {
+        console.log('\n── 自动修复 ──');
+        // 修复 persona 文件
+        const personaDir = path.join(os.homedir(), '.agent', 'prompts', 'persona');
+        const bootstrapPath = path.join(personaDir, 'BOOTSTRAP.md');
+        if (!fs.existsSync(personaDir)) {
+            fs.mkdirSync(personaDir, { recursive: true });
+        }
+        let personaCreated = 0;
+        for (const [name, content] of Object.entries(loadOriginalPrompts())) {
+            const p = path.join(personaDir, name);
+            if (!fs.existsSync(p)) {
+                fs.writeFileSync(p, content, 'utf-8');
+                personaCreated++;
+            }
+        }
+        // 确保 BOOTSTRAP.md 存在（触发 bootstrap 流程）
+        if (!fs.existsSync(bootstrapPath) && personaCreated > 0) {
+            fs.writeFileSync(bootstrapPath, '# Bootstrap\n请与用户对话，了解其偏好后填写 IDENTITY.md 和 USER.md。', 'utf-8');
+        }
+        if (personaCreated > 0) {
+            console.log(`  ✅ 创建了 ${personaCreated} 个 Persona 文件`);
+        }
+        // 修复依赖
+        const depResult = checkDeps();
+        if (!depResult.ok) {
+            console.log('  🔄 安装缺失依赖...');
+            try {
+                execSync('pnpm install', {
+                    cwd: path.join(os.homedir(), '.agent'),
+                    stdio: 'inherit',
+                });
+                console.log('  ✅ 依赖安装完成');
+            }
+            catch {
+                console.log('  ⚠️ 自动安装失败，请手动执行 pnpm install');
+            }
+        }
+        console.log('\n── 再次运行诊断 ──');
+        // Re-run checks after fix
+        const postFix = [checkDeps(), checkPersona(), checkNativeModule()];
+        for (const c of postFix) {
+            const icon = c.ok ? '✅' : '❌';
+            console.log(`${icon} ${c.label}: ${c.detail}`);
+        }
+    }
+    // 显示原始提示词的位置
+    console.log('\n── 提示 ──');
+    console.log('  查看原始 Persona 提示词: hyacinth doctor --prompts');
+    console.log('  重新运行设置向导: hyacinth setup');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/context/cache-strategy.d.ts

@@ -0,0 +1,76 @@
+import type { ProviderType } from '../types.js';
+/** 描述 messages[] 中一条消息在缓存断点中的位置 */
+export interface CacheMarker {
+    /** messages[] 中的全局索引（0-based） */
+    index: number;
+    type: 'ephemeral';
+}
+/** Zone 组装后的结构信息，供策略决定在哪些消息上打点 */
+export interface ZoneInfo {
+    /** Zone 标识（如 "zone1", "zone3"） */
+    key: string;
+    /** 该 Zone 产出的消息数 */
+    msgCount: number;
+}
+export interface ComputeMarkersInput {
+    zones: ZoneInfo[];
+}
+/**
+ * 缓存策略模式（cache mode），区分不同厂商的缓存实现方式。
+ *
+ *   - `none`           — 无缓存支持（本地模型等）
+ *   - `auto-prefix`    — 厂商自动对比请求前缀字节，无需手动干预
+ *   - `manual-markers` — 需在消息上打 cache_control 断点（Anthropic）
+ *   - `pre-create`     — 需预先创建缓存对象，推理时引用 ID（Gemini 显式）
+ */
+export type CacheMode = 'none' | 'auto-prefix' | 'manual-markers' | 'pre-create';
+/**
+ * CacheStrategy — 缓存策略接口。
+ *
+ * 不同厂商对前缀缓存的机制完全不同：
+ *   - Anthropic：manual-markers — 在消息上打 cache_control 标记（最多 4 断点）
+ *   - DeepSeek / OpenAI / 其他：auto-prefix — 自动前缀匹配
+ *   - Gemini：双重 — implicit=auto-prefix (2.5+默认), explicit=pre-create (CachedContent API)
+ *   - local / llamacpp：none — 无缓存
+ *
+ * 新增厂商适配：
+ *   1. 确定其 cacheMode
+ *   2. 如为 manual-markers，实现 computeMarkers()
+ *   3. 调用 registerStrategy(providerType, strategy)
+ */
+export interface CacheStrategy {
+    /** 策略名（用于日志/调试） */
+    readonly name: string;
+    /** 适用的 ProviderType */
+    readonly providerType: ProviderType;
+    /** 缓存模式 */
+    readonly cacheMode: CacheMode;
+    /** 该厂商支持的最大断点数（manual-markers 模式有效） */
+    readonly maxMarkers: number;
+    /** 是否需要在消息上打 cache_control 断点（仅 manual-markers 返回 true） */
+    shouldApplyMarkers(): boolean;
+    /** 根据 Zone 结构计算断点位置（manual-markers 模式调用） */
+    computeMarkers(input: ComputeMarkersInput): CacheMarker[];
+    /**
+     * 返回预创建缓存所需的静态 Zone key 列表（pre-create 模式调用）。
+     *
+     * 对于 Gemini 显式缓存：返回 ['zone1', 'zone2'] 表示应预注册 Z1+Z2 内容。
+     * Provider 读取 zonesToPreCreate 后从消息中提取对应内容，调用 CachedContent API。
+     *
+     * 返回空数组表示不预创建（auto-prefix / manual-markers 模式）。
+     */
+    zonesToPreCreate?(): string[];
+}
+/**
+ * 注册自定义缓存策略（供插件或未来新厂商使用）。
+ *
+ * @example
+ *   registerStrategy('my-provider', new MyProviderCacheStrategy());
+ */
+export declare function registerStrategy(providerType: ProviderType, strategy: CacheStrategy): void;
+/**
+ * 根据 ProviderType 查找对应的缓存策略。
+ * 未注册的 Provider 回退到 AutoPrefixCacheStrategy（零标记 + 自动前缀）。
+ */
+export declare function getCacheStrategy(providerType: ProviderType): CacheStrategy;
+//# sourceMappingURL=cache-strategy.d.ts.map

package/dist/context/cache-strategy.js

@@ -0,0 +1,123 @@
+// ── Built-in strategies ────────────────────────────────────────────
+/**
+ * Anthropic 缓存策略（manual-markers 模式）。
+ *
+ * 4 个 cache_control 断点覆盖所有稳定前缀：
+ *   BP1  → Zone 1 第一条消息（system prompt）
+ *   BP2  → Zone 2 第一条消息（工具规则 + skill/agent/mcp 索引）
+ *   BP3a → Zone 3 第一条消息（项目上下文 + 摘要）
+ *   BP3b → Zone 3 第二条消息（历史首条，若存在）
+ */
+class AnthropicCacheStrategy {
+    name = 'anthropic';
+    providerType = 'anthropic';
+    cacheMode = 'manual-markers';
+    maxMarkers = 4;
+    shouldApplyMarkers() {
+        return true;
+    }
+    computeMarkers(input) {
+        const markers = [];
+        let offset = 0;
+        for (const zone of input.zones) {
+            if (zone.msgCount === 0)
+                continue;
+            switch (zone.key) {
+                case 'zone1':
+                    markers.push({ index: offset, type: 'ephemeral' }); // BP1
+                    break;
+                case 'zone2':
+                    markers.push({ index: offset, type: 'ephemeral' }); // BP2
+                    break;
+                case 'zone3':
+                    markers.push({ index: offset, type: 'ephemeral' }); // BP3a
+                    if (zone.msgCount > 1) {
+                        markers.push({ index: offset + 1, type: 'ephemeral' }); // BP3b
+                    }
+                    break;
+                default:
+                    break;
+            }
+            if (markers.length >= this.maxMarkers) {
+                return markers.slice(0, this.maxMarkers);
+            }
+            offset += zone.msgCount;
+        }
+        return markers;
+    }
+}
+/**
+ * Gemini 缓存策略（双重模式）。
+ *
+ * 隐式缓存（Gemini 2.5+ 默认启用）：
+ *   - 自动匹配请求前缀，最小 token: Flash≥1024 / Pro≥4096
+ *   - 无需手动标记，等价于 auto-prefix
+ *
+ * 显式缓存（CachedContent API，保证命中 + 约 10% 成本）：
+ *   - 预创建缓存对象：POST /v1beta/cachedContents
+ *   - TTL：默认 1h，最长 90 天（7776000s）
+ *   - 仅可修改 TTL，不可修改内容
+ *   - 推理时引用：{ cachedContent: "cachedContents/xxx", contents: [...] }
+ *
+ * 当前走隐式路径（auto-prefix）。
+ * TODO: 实现显式路径 — GeminiProvider 在首次调用时预注册 Z1+Z2 为 CachedContent。
+ */
+class GeminiCacheStrategy {
+    name = 'gemini';
+    providerType = 'gemini';
+    cacheMode = 'auto-prefix';
+    maxMarkers = 0;
+    shouldApplyMarkers() {
+        return false;
+    }
+    computeMarkers(_input) {
+        return [];
+    }
+}
+/**
+ * 自动前缀缓存策略（auto-prefix 模式）。
+ *
+ * 适用于：
+ *   - DeepSeek（AutoPrefixCacheStrategy）
+ *   - OpenAI（自动前缀匹配）
+ *   - Groq / xAI / Mistral / OpenRouter / Moonshot（OpenAI 兼容）
+ *   - local / llamacpp（无缓存，maxMarkers=0）
+ */
+class AutoPrefixCacheStrategy {
+    name = 'auto-prefix';
+    providerType;
+    cacheMode = 'auto-prefix';
+    maxMarkers = 0;
+    constructor(providerType) {
+        this.providerType = providerType;
+    }
+    shouldApplyMarkers() {
+        return false;
+    }
+    computeMarkers(_input) {
+        return [];
+    }
+}
+// ── Registry ───────────────────────────────────────────────────────
+const STRATEGIES = new Map();
+// 注册内置策略
+STRATEGIES.set('anthropic', new AnthropicCacheStrategy());
+STRATEGIES.set('gemini', new GeminiCacheStrategy());
+/**
+ * 注册自定义缓存策略（供插件或未来新厂商使用）。
+ *
+ * @example
+ *   registerStrategy('my-provider', new MyProviderCacheStrategy());
+ */
+export function registerStrategy(providerType, strategy) {
+    STRATEGIES.set(providerType, strategy);
+}
+/**
+ * 根据 ProviderType 查找对应的缓存策略。
+ * 未注册的 Provider 回退到 AutoPrefixCacheStrategy（零标记 + 自动前缀）。
+ */
+export function getCacheStrategy(providerType) {
+    return (STRATEGIES.get(providerType) ??
+        new AutoPrefixCacheStrategy(providerType));
+}
+//# sourceMappingURL=cache-strategy.js.map

package/dist/context/composer.d.ts

@@ -0,0 +1,77 @@
+import type { Message, ToolDefinition } from '../types.js';
+import type { SystemPromptSection } from './prompt-builder.js';
+import type { ComposeOptions, ContextComposer, ContextSource } from './interface.js';
+import type { GitManager } from '../evolution/git-manager.js';
+import type { ContextProfile } from './profiles.js';
+import type { ProviderType } from '../types.js';
+export interface LayeredComposeOptions {
+    sessionDir: string;
+    /** 当前 active Provider 的类型 — 决定缓存策略（断点 vs 自动前缀） */
+    providerType?: ProviderType;
+    maxContextTokens: number;
+    cwd: string;
+    timestamp: string;
+    tools: ToolDefinition[];
+    history: Message[];
+    userInput: string;
+    historySummary?: string;
+    currentPlan?: string;
+    selectedSkills?: string[];
+    selectedAgents?: string[];
+    impactInfo?: string;
+    fullHistory?: Message[];
+    zone3Hashes?: Set<string>;
+    personaDir?: string;
+    gitManager?: GitManager;
+    /** 当前模式 profile — 控制 section 过滤、persona 来源、memory 来源 */
+    profile?: ContextProfile;
+    /** 旁路Agent 注入列表 */
+    bypassInjections?: import('../bypass/types.js').Injection[];
+}
+export type ZoneBreakdown = Record<string, number> & {
+    total: number;
+};
+export interface LayeredContext {
+    messages: Message[];
+    zoneBreakdown: ZoneBreakdown;
+}
+export declare class LayeredContextComposer implements ContextComposer {
+    private promptBuilder;
+    private tokenCounter;
+    private sources;
+    /** 当前激活的条件（如 precise_mode）— 由策略设置 */
+    activeConditions: Set<string>;
+    private persistentSections;
+    private cwd;
+    constructor(maxContextTokens?: number);
+    registerSource(source: ContextSource): void;
+    unregisterSource(name: string): void;
+    getSource(name: string): ContextSource | undefined;
+    registerPromptSection(section: SystemPromptSection): void;
+    clearPersistentSections(): void;
+    compose(options: LayeredComposeOptions): Promise<LayeredContext>;
+    compose(options: ComposeOptions): Promise<Message[]>;
+    composeLegacy(options: ComposeOptions): Promise<Message[]>;
+    private buildResolverContext;
+    private composeCore;
+    private assembleZone;
+    private clearPromptBuilder;
+    private isLayeredOptions;
+    private computeHashes;
+    /**
+     * 按策略计算出的断点位置，在消息的 TextContent 上打 cache_control 标记。
+     *
+     * 仅标记系统角色 (system/user) 的消息，跳过 assistant 角色。
+     * `cache_control` 放在消息的最后一个 TextContent block 上。
+     */
+    /**
+     * 清除所有消息上的 cache_control 标记。
+     *
+     * 历史消息中可能残留之前 Anthropic session 的 cache_control，
+     * 当切换到 DeepSeek/OpenAI 等 auto-prefix Provider 时，必须清除。
+     */
+    private clearMarkers;
+    private applyMarkers;
+    private toLayeredOptions;
+}
+//# sourceMappingURL=composer.d.ts.map