hyacinth-ai 0.9.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 孑遗
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# 🪻 Hyacinth (风信子)
+
+**多 Provider AI Agent** — 可编程、可扩展、可信任的终端智能助手。
+
+> TypeScript 6.0 · Node.js · 37 模块 · 82+ 工具 · 14+ LLM Provider
+
+---
+
+## 特性
+
+### 🤖 多模型支持
+14+ Provider 一键切换 — Anthropic、OpenAI、DeepSeek、Google Gemini、阿里通义千问、智谱 GLM、MiniMax、MiMo、Groq、xAI、Mistral、OpenRouter、Moonshot，以及本地模型（llama.cpp / Ollama）。
+
+### 🛠 工具系统（三层架构）
+| 层 | 来源 | 数量 | 示例 |
+|---|---|---|---|
+| **内置工具** | 启动即注册 | 17+ | `read`、`write`、`bash`、`grep`、`edit`、`glob`、`http_request`、`git` |
+| **运行时控制** | AgentLoop 注入 | 35+ | `switch_provider`、`spawn_sub_agent`、`toggle_tool`、`session` 管理 |
+| **MCP 工具** | 动态桥接 | 动态 | `mcp__chrome-devtools__navigate` 等第三方工具 |
+
+所有工具通过统一注册表管理，支持热插拔、权限白名单、子 Agent 隔离。
+
+### 🔀 多渠道
+| 通道 | 类型 | 状态 |
+|---|---|---|
+| **TUI** | 全屏终端界面 | ✅ 稳定 |
+| **Feishu (飞书)** | 机器人 | ✅ 稳定 |
+| **ClawBot** | 消息通道 | ✅ 可用 |
+| **HTTP Webhook** | Webhook 接入 | ✅ 可用 |
+
+### 🤝 子 Agent 编排
+- 委托式协作：主 Agent 将任务分发给子 Agent
+- 对抗式协作：多 Agent 辩论验证
+- 并行执行：同时处理多个子任务
+- 独立工具白名单、独立上下文、独立 Session
+
+### 🔄 Flow 工作流
+内置 Flow 引擎驱动结构化任务执行：
+- **Todo 模式** — 任务拆解 → 步骤定义 → 逐个执行
+- **Spec 模式** — 需求规格 → 任务清单 → 验收检查
+
+### 🔌 插件 + MCP + Skill
+- **插件系统**：`plugin.json` + `PluginApi`，可注册工具/Skill/MCP Server/渠道
+- **MCP 协议**：桥接第三方工具生态，stdio/SSE 双传输，崩溃自动重连
+- **Skill 系统**：可插拔的提示词模板，按需注入上下文
+
+### 🏗 基础设施
+| 子系统 | 说明 |
+|---|---|
+| **MCP** | 第三方工具桥接，安全沙箱，危险命令黑名单 |
+| **知识库** | SQLite FTS5 全文检索 + CJK bigram 分词 + Tag IDF 语义匹配 |
+| **热重载** | 8 个 Watcher：MCP/Plugin/Prompt/Config/Tool/Skill/Agent/Channel |
+| **调度器** | Interval / Cron / Daily / Fixed-time / Random 五种调度 |
+| **回滚** | 按回合回滚文件更改 (git-driven) |
+| **自修复** | Loop 死循环检测、风暴抑制、会话垃圾清理 |
+| **自更新** | GitHub Release / 本地编译两种更新路径 |
+| **守护进程** | 子进程退出 code 42 时自动拉起 |
+
+### 📦 注册表体系
+所有可扩展点共享同一基类 `GenericRegistry<T>`：
+
+```
+ToolRegistry     → 工具注册
+SkillRegistry    → 技能注册
+AgentRegistry    → 子 Agent 注册
+PluginRegistry   → 插件注册
+ProviderRegistry → Provider 注册
+ChannelRegistry  → 渠道注册
+MachineRegistry  → Flow 注册
+```
+
+## 快速开始
+
+### 安装
+
+```bash
+# 全局安装
+npm install -g hyacinth-ai
+
+# 或直接用 npx
+npx hyacinth-ai
+```
+
+### 首次使用
+
+```bash
+# 运行配置向导
+hyacinth setup
+
+# 启动 TUI 界面
+hyacinth tui
+
+# 直接对话
+hyacinth "帮我检查一下这个目录"
+```
+
+### 配置 API Key
+
+创建 `.env` 文件：
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+DEEPSEEK_API_KEY=sk-...
+GEMINI_API_KEY=...
+```
+
+或通过命令行：
+
+```bash
+hyacinth --set ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## 支持的 Provider
+
+| Provider | 环境变量 | 默认模型 |
+|---|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 |
+| OpenAI | `OPENAI_API_KEY` | gpt-4o |
+| DeepSeek | `DEEPSEEK_API_KEY` | deepseek-V4 |
+| Google Gemini | `GEMINI_API_KEY` | gemini-2.5-flash |
+| 阿里通义千问 (Qwen) | `QWEN_API_KEY` | qwen-plus |
+| 智谱 GLM (Zhipu) | `ZHIPU_API_KEY` | glm-4-plus |
+| MiniMax | `MINIMAX_API_KEY` | minimax-text-01 |
+| MiMo | `MIMO_API_KEY` | mimo |
+| Groq | `GROQ_API_KEY` | llama-3.3-70b-versatile |
+| xAI (Grok) | `XAI_API_KEY` | grok-2 |
+| Mistral | `MISTRAL_API_KEY` | mistral-large-latest |
+| OpenRouter | `OPENROUTER_API_KEY` | auto |
+| Moonshot | `MOONSHOT_API_KEY` | moonshot-v1-8k |
+| Local (llama.cpp) | — | 本地模型路径 |
+
+## CLI 命令
+
+```bash
+hyacinth                        # 交互模式
+hyacinth <prompt>               # 单次执行
+hyacinth --provider deepseek    # 指定 Provider
+hyacinth --tui                  # 全屏 TUI 模式
+hyacinth serve                  # 启动 HTTP API Server
+hyacinth setup                  # 配置向导
+hyacinth doctor                 # 系统诊断
+hyacinth session list           # 会话管理
+hyacinth config get/set         # 配置管理
+hyacinth model switch/list      # 模型管理
+hyacinth skill enable/disable   # Skill 管理
+hyacinth tool enable/disable    # 工具管理
+hyacinth update                 # 自更新
+```
+
+## 项目结构
+
+```
+src/
+├── gateway/          # CLI/TUI/HTTP 入口，Agent 工厂装配
+├── channels/         # 多渠道消息处理（Feishu, Webhook）
+├── orchestrator/     # AgentLoop 主循环，LLM 编排
+├── agents/           # 子 Agent 系统（委托/对抗/并行）
+├── machine/          # 状态机 + Flow 工作流（Todo/Spec/Bootstrap）
+├── provider/         # 14+ LLM Provider 适配层
+├── context/          # 5-Zone 上下文组合器 + 压缩编排器
+├── prompts/          # 提示词模板管理
+├── tools/            # 内置工具 + 运行时控制 + 工具执行器
+├── registry/         # 泛型注册表基类（Tool/Skill/Agent/Plugin...）
+├── mcp/              # MCP 协议集成（Client/Bridge/ServerManager）
+├── knowledge/        # 知识库（FTS5 + Tag 检索）
+├── plugins/          # 插件系统
+├── skills/           # Skill 系统
+├── schedule/         # 调度任务系统
+├── memory/           # 会话/对话持久化（SQLite）
+├── hot-reload/       # 8 个热重载 Watcher
+├── rollback/         # 回合回滚系统
+├── repair/           # 自修复（死循环检测、风暴抑制）
+├── update/           # 自更新
+├── setup/            # 配置管理 + 安装向导
+├── ui/               # 命令注册表
+├── bypass/           # 旁路 Agent
+├── multimodal/       # 多模态（图片处理）
+└── local-model/      # 本地模型管理
+```
+
+## 开发
+
+```bash
+# 依赖安装
+pnpm install
+
+# 编译
+pnpm build
+
+# 开发模式（监听）
+pnpm dev
+
+# 测试
+pnpm test
+
+# Windows 启动
+pnpm start:win
+```
+
+## 许可证
+
+[MIT](./LICENSE)
+
+Copyright © 2026 孑遗

package/commands.json

@@ -0,0 +1,25 @@
+{
+  "commands": [
+    {
+      "name": "model",
+      "description": "模型管理（在线/本地/设置/信息）",
+      "icon": "◆",
+      "category": "model",
+      "executeLocal": true,
+      "children": [
+        {
+          "name": "local",
+          "description": "管理本地模型...",
+          "icon": "💻",
+          "category": "model",
+          "children": [
+            { "name": "start", "description": "启动本地模型服务", "icon": "▶", "category": "model", "args": "<name>", "handler": "localModel.start" },
+            { "name": "stop", "description": "停止本地模型服务", "icon": "■", "category": "model", "args": "<name>", "handler": "localModel.stop" },
+            { "name": "status", "description": "查看本地模型状态", "icon": "ℹ", "category": "model", "handler": "localModel.status" },
+            { "name": "unregister", "description": "注销模型", "icon": "➖", "category": "model", "args": "<name>", "handler": "localModel.unregister" }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/agents/builtins.d.ts

@@ -0,0 +1,8 @@
+import type { AgentDefinition } from '../types.js';
+import type { AgentsConfig } from '../setup/config.js';
+/**
+ * 创建内置子 Agent 定义（fallback 用）
+ * @param config 可选的 Agent 配置覆写，用于覆盖默认的 maxTurns、allowedTools、collaborationMode
+ */
+export declare function createBuiltinAgents(config?: AgentsConfig): AgentDefinition[];
+//# sourceMappingURL=builtins.d.ts.map

package/dist/agents/builtins.js

@@ -0,0 +1,50 @@
+import { loadPrompt } from '../prompts/loader.js';
+/**
+ * 创建内置子 Agent 定义（fallback 用）
+ * @param config 可选的 Agent 配置覆写，用于覆盖默认的 maxTurns、allowedTools、collaborationMode
+ */
+export function createBuiltinAgents(config) {
+    const defaults = [
+        {
+            name: 'code-reviewer',
+            description: '代码审查专家，审查代码质量、可读性和最佳实践',
+            systemPrompt: loadPrompt('agents/code-reviewer'),
+            allowedTools: ['read', 'glob', 'grep'],
+            maxTurns: 10,
+            collaborationMode: 'adversarial',
+            sessionTtlMinutes: 10,
+        },
+        {
+            name: 'security-auditor',
+            description: '安全审计专家，检查代码中的安全漏洞和风险',
+            systemPrompt: loadPrompt('agents/security-auditor'),
+            allowedTools: ['read', 'glob', 'grep'],
+            maxTurns: 10,
+            collaborationMode: 'adversarial',
+            sessionTtlMinutes: 10,
+        },
+        {
+            name: 'test-writer',
+            description: '测试编写专家，为代码编写单元测试和集成测试',
+            systemPrompt: loadPrompt('agents/test-writer'),
+            allowedTools: ['read', 'write', 'glob', 'grep', 'bash'],
+            maxTurns: 15,
+            collaborationMode: 'delegate',
+            sessionTtlMinutes: 10,
+        },
+    ];
+    return defaults.map((agent) => {
+        const override = config?.[agent.name];
+        if (!override)
+            return agent;
+        const merged = { ...agent };
+        if (override.maxTurns !== undefined)
+            merged.maxTurns = override.maxTurns;
+        if (override.allowedTools !== undefined)
+            merged.allowedTools = override.allowedTools;
+        if (override.collaborationMode !== undefined)
+            merged.collaborationMode = override.collaborationMode;
+        return merged;
+    });
+}
+//# sourceMappingURL=builtins.js.map

package/dist/agents/config-loader.d.ts

@@ -0,0 +1,15 @@
+import type { AgentDefinition } from '../types.js';
+import type { AgentsConfig } from '../setup/config.js';
+/**
+ * 加载 Agent 配置
+ *
+ * 加载顺序：
+ * 1. AGENTS_CONFIG_PATH 环境变量（最高优先级）
+ * 2. 项目级 .agent/agents.json
+ * 3. 全局 ~/.agent/agents.json
+ * 4. Fallback: 内置 builtins.ts 定义
+ *
+ * 合并策略：后加载的同名 agent 覆盖先加载的
+ */
+export declare function loadAgentConfigs(cwd: string, configOverride?: AgentsConfig): Promise<AgentDefinition[]>;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/agents/config-loader.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createBuiltinAgents } from './builtins.js';
+import { loadPrompt } from '../prompts/loader.js';
+/**
+ * 加载 Agent 配置
+ *
+ * 加载顺序：
+ * 1. AGENTS_CONFIG_PATH 环境变量（最高优先级）
+ * 2. 项目级 .agent/agents.json
+ * 3. 全局 ~/.agent/agents.json
+ * 4. Fallback: 内置 builtins.ts 定义
+ *
+ * 合并策略：后加载的同名 agent 覆盖先加载的
+ */
+export async function loadAgentConfigs(cwd, configOverride) {
+    // 收集所有 agent 配置（name -> config）
+    const agentMap = new Map();
+    // 1. 加载全局 agents.json
+    const globalPath = path.join(os.homedir(), '.agent', 'agents.json');
+    await loadJsonConfig(globalPath, agentMap);
+    // 2. 加载项目级 agents.json（覆盖全局）
+    const projectPath = path.join(cwd, '.agent', 'agents.json');
+    await loadJsonConfig(projectPath, agentMap);
+    // 3. 环境变量覆盖路径（最高优先级）
+    const envPath = process.env['AGENTS_CONFIG_PATH'];
+    if (envPath) {
+        await loadJsonConfig(envPath, agentMap);
+    }
+    // 4. 如果没有任何配置，fallback 到内置
+    if (agentMap.size === 0) {
+        return createBuiltinAgents(configOverride);
+    }
+    // 5. 将配置转为 AgentDefinition
+    const agents = [];
+    for (const [name, entry] of agentMap) {
+        let systemPrompt;
+        try {
+            systemPrompt = loadPrompt(entry.promptFile);
+        }
+        catch {
+            // 提示词文件不存在，跳过该 agent
+            continue;
+        }
+        // 应用 configOverride（config.json 中的 agents 覆写）
+        const override = configOverride?.[name];
+        agents.push({
+            name,
+            description: entry.description,
+            systemPrompt,
+            allowedTools: override?.allowedTools ?? entry.allowedTools,
+            maxTurns: override?.maxTurns ?? entry.maxTurns,
+            collaborationMode: override?.collaborationMode ?? entry.collaborationMode,
+            modelPreference: entry.modelPreference,
+            sessionTtlMinutes: override?.sessionTtlMinutes ?? entry.sessionTtlMinutes,
+        });
+    }
+    return agents;
+}
+async function loadJsonConfig(filePath, agentMap) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const config = JSON.parse(content);
+        if (Array.isArray(config.agents)) {
+            for (const entry of config.agents) {
+                agentMap.set(entry.name, entry);
+            }
+        }
+    }
+    catch {
+        // 文件不存在或解析失败，忽略
+    }
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/agents/delegate-tool.d.ts

@@ -0,0 +1,109 @@
+import type { Tool } from '../tools/interface.js';
+import type { AgentDefinition } from '../types.js';
+import type { AgentRegistry } from './registry.js';
+import { AgentLoop } from '../orchestrator/loop.js';
+import { ModelRouter } from '../provider/model-router.js';
+import type { Provider } from '../provider/interface.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { DependencyAnalyzer } from '../dependency/analyzer.js';
+/** 子 Agent 进度事件 */
+export interface ProgressEvent {
+    type: 'text' | 'tool_call' | 'tool_result' | 'turn' | 'status';
+    message: string;
+    timestamp: number;
+}
+/** 上下文传递给子 Agent 的参数 */
+export interface SubAgentContext {
+    modelRouter: ModelRouter;
+    toolRegistry: ToolRegistry;
+    sessionDir: string;
+    maxContextTokens: number;
+    dependencyAnalyzer?: DependencyAnalyzer;
+    /** 子 Agent 执行进度回调 */
+    onProgress?: (event: ProgressEvent) => void;
+    /** 文件访问沙箱根目录（设置后子 Agent 的 read/write/edit/grep/glob 被限制在此目录下，bash 被禁用） */
+    sandboxRoot?: string;
+    /** 创建带独立 userId 的 Provider（子Agent 之间 + 与主Agent 的 KVCache 隔离） */
+    createSubProvider(userId: string): Provider;
+}
+/** 注册正在运行的子 Agent loop */
+export declare function registerRunningLoop(instanceId: string, loop: AgentLoop): void;
+/** 注销已完成的子 Agent loop */
+export declare function unregisterRunningLoop(instanceId: string): void;
+/** 中断指定子 Agent */
+export declare function interruptSubAgentLoop(instanceId: string): boolean;
+/** 销毁子 Agent session 目录（清理 conversation/events/stats/meta） */
+export declare function destroySubAgentSession(parentSessionDir: string, instanceId: string): Promise<boolean>;
+/**
+ * 创建（或复用）子 Agent 的 AgentLoop 实例。
+ *
+ * session 按 instanceId 固定目录，多次 delegate 复用同一 session，
+ * 子 Agent 保留完整对话历史，无需每次重新交代背景。
+ *
+ * TTL 机制：若距离上次调用超过 sessionTtlMinutes（默认 10 分钟），
+ * 自动清理旧 session 并重建。
+ */
+export declare function createSubAgentLoop(agentDef: AgentDefinition, task: string, parentContext: SubAgentContext): Promise<{
+    loop: AgentLoop;
+    sessionDir: string;
+    isNew: boolean;
+}>;
+/**
+ * DelegateToAgentTool — 主 Agent 通过此工具委托任务给子 Agent
+ */
+export declare class DelegateToAgentTool implements Tool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            agent_name: {
+                type: "string";
+                description: string;
+            };
+            instance_id: {
+                type: "string";
+                description: string;
+            };
+            task: {
+                type: "string";
+                description: string;
+            };
+            context: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private agentRegistry;
+    private parentContext;
+    constructor(agentRegistry: AgentRegistry, parentContext: SubAgentContext);
+    execute(args: Record<string, unknown>): Promise<string>;
+    /**
+     * 委托模式：单个子 Agent 执行任务
+     */
+    private executeDelegate;
+    /**
+     * 对抗审查模式：两个不同角色的子 Agent 独立审查，综合意见
+     */
+    private executeAdversarial;
+    /**
+     * 并行分工模式：多个子 Agent 并行执行同一任务的不同方面，汇总结果
+     */
+    private executeParallel;
+    /**
+     * 收集子 Agent 的对话摘要
+     */
+    private collectConversationSummary;
+    /**
+     * 收集子 Agent 执行的结构化结果
+     * session 目录按 instanceId 固定，直接读取，无需遍历查找
+     */
+    private collectAgentResult;
+    /**
+     * 收集子 Agent 执行结果
+     */
+    private collectResult;
+}
+//# sourceMappingURL=delegate-tool.d.ts.map