hyacinth-ai 0.9.6

package/provider_arch.md

@@ -0,0 +1,179 @@
+# 当前 Agent Provider 层架构
+
+> 基于 `src/provider/` 源码阅读整理，2026-06-15
+
+---
+
+## 一、整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                       上层调用者 (Agent Core)                        │
+│    LLM / Orchestrator / Skills / Sub-agents / 各种 pipeline         │
+└───────────────────────────┬─────────────────────────────────────────┘
+                            │  createStream(messages, tools)
+                            ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      ProviderManager (管理入口)                       │
+│                                                                     │
+│  ┌─────────────────────────────────────────────────────────────┐    │
+│  │                      Provider 实例 (组合)                     │    │
+│  │                                                             │    │
+│  │  ┌─────────────────────────────────────────────────────┐    │    │
+│  │  │            FallbackProviderChain (降级链)             │    │    │
+│  │  │  ┌──────────┐  ┌──────────┐          ┌──────────┐  │    │    │
+│  │  │  │Resilient │  │Resilient │   ...    │Resilient │  │    │    │
+│  │  │  │Provider  │→→│Provider  │→→...→→  │Provider  │  │    │    │
+│  │  │  │(primary) │  │(fallback1)│         │(fallbackN)│  │    │    │
+│  │  │  └────┬─────┘  └────┬─────┘          └────┬─────┘  │    │    │
+│  │  └───────┼─────────────┼─────────────────────┼────────┘    │    │
+│  │          │             │                     │             │    │
+│  │     ┌────▼─────┐  ┌───▼──────┐         ┌─────▼────┐      │    │
+│  │     │Retry + CB│  │Retry + CB│         │Retry + CB│      │    │
+│  │     └────┬─────┘  └───┬──────┘         └─────┬────┘      │    │
+│  │          │             │                     │             │    │
+│  │     ┌────▼─────────────▼─────────────────────▼────────┐    │    │
+│  │     │             具体 Provider 实现 (Adapter)          │    │    │
+│  │     │                                                   │    │    │
+│  │     │  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │    │    │
+│  │     │  │Anthropic │  │ OpenAI   │  │ DeepSeek      │  │    │    │
+│  │     │  │Provider  │  │Provider  │  │ (兼容OpenAI)   │  │    │    │
+│  │     │  ├──────────┤  ├──────────┤  ├───────────────┤  │    │    │
+│  │     │  │Gemini    │  │ Local    │  │ Qwen/Zhipu/   │  │    │    │
+│  │     │  │Provider  │  │Provider  │  │ MiniMax/MiMo  │  │    │    │
+│  │     │  └──────────┘  └──────────┘  │ (兼容Anthropic │  │    │    │
+│  │     │                               │  或 OpenAI)   │  │    │    │
+│  │     │                               └───────────────┘  │    │    │
+│  │     └───────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────┘    │
+│                                                                     │
+│  ModelRouter (子任务路由)           ProviderRouter (注册表路由)      │
+│  ┌────────────────────────┐       ┌────────────────────────────┐   │
+│  │ assessment → main/local│       │  registry: Map<name, Prov> │   │
+│  │ planning  → main/local│       │  route(complexity)         │   │
+│  │ compression→ main/local│       │  setDefault(name)         │   │
+│  └────────────────────────┘       └────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    配置与元数据层                                      │
+│                                                                     │
+│  ProviderConfigLoader     ProviderMeta (baseUrl, model, envKey)     │
+│  LocalConfigLoader        ModelCatalog (ModelInfo, capabilities)    │
+│  ConfigManager            项目/全局 config.json                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、各模块职责
+
+### 2.1 接口层 — `interface.ts`
+
+```
+Provider (interface)
+  ├── createStream(messages, tools?, signal?): AsyncIterable<StreamEvent>
+  ├── getProviderType(): ProviderType
+  ├── getModel(): string
+  ├── getCapabilities?(): ProviderCapabilities  ← toolCalling, streaming, vision, isLocal...
+  ├── setThinking?(enabled, effort?)             ← DeepSeek V4 / Anthropic Extended
+  ├── loadAdapter?(name, path)                   ← LoRA (仅 local)
+  ├── unloadAdapter?(name)
+  └── listAdapters?()
+```
+
+所有 Provider 实现类都实现这个接口。统一的 `createStream` 入口。
+
+### 2.2 弹性层 — `resilient.ts`
+
+**ResilientProvider**: 装饰器模式，包装任意 Provider，添加：
+- **Retry** (重试): 指数退避 (1s→2s→4s→8s, 最多4次)，仅重试可恢复错误 (5xx, 429, 网络错误)
+- **Circuit Breaker** (熔断): 连续 5 次失败 → 断路器打开 → 30s 冷却 → 半开试探 → 恢复或再断开
+- 已 yield 事件后遇到错误不重试（避免流内容重复）
+
+### 2.3 降级链 — `fallback.ts`
+
+**FallbackProviderChain**: 把多个 Provider 串成链。
+- 每个 Provider 独立包裹 ResilientProvider（各自有 retry+CB）
+- 按序尝试 [primary, fallback1, fallback2, ...]
+- 一个失败自动跳到下一个
+- 跨 Provider 时自动清理 `cache_control` 标记（anthropic 独有）
+- 回调通知外部切换事件
+
+### 2.4 管理器 — `manager.ts`
+
+**ProviderManager**:
+- 入口管理者，构造时创建 Provider 实例
+- 自动检测：环境变量 → 自动选择第一个有 API Key 的 provider
+- 显式配置：`createProviderFromConfig(config)` 工厂方法
+- `switchProvider(config)` 运行时热切换，保留弹性层
+- 内置 fallback 链自动发现：主 provider 失败后遍历其他有 key 的 provider
+
+### 2.5 具体 Provider 实现
+
+| Provider | 文件 | 兼容协议 | 特性 |
+|----------|------|---------|------|
+| AnthropicProvider | `anthropic.ts` | Anthropic API | 原生, tool calling, cache_control |
+| OpenAIProvider | `openai.ts` | OpenAI API | 原生, tool calling |
+| DeepSeekProvider | `deepseek.ts` | OpenAI 兼容 | thinking/reasoning |
+| GeminiProvider | `gemini.ts` | Google API | 原生, 大 context |
+| LocalProvider | `local.ts` | OpenAI 兼容 | LoRA adapter, 本地部署 |
+| OpenAICompatibleProvider | `compatible.ts` | OpenAI 兼容 | Groq, xAI, Mistral, OpenRouter, Moonshot |
+| QwenProvider | `qwen.ts` | Anthropic 兼容 | 阿里系 |
+| ZhipuProvider | `zhipu.ts` | OpenAI 兼容 | 智谱 |
+| MiniMaxProvider | `minimax.ts` | Anthropic 兼容 | MiniMax |
+| MiMoProvider | `mimo.ts` | Anthropic 兼容 | 小米 |
+
+### 2.6 路由层
+
+**ModelRouter** (`model-router.ts`): 双通道路由
+- 按角色 (assessment/planning/compression) 路由到 main 或 local provider
+- local 失败自动降级到 main
+
+**ProviderRouter** (`router.ts`): 注册表路由（早期遗留，实际不常使用）
+- 注册/注销/查询 Provider
+- 按复杂度自动路由 (high→在线, low→本地)
+- 支持手动覆盖
+
+### 2.7 配置层
+
+**ProviderConfigLoader** (`config.ts`): 从 `.agent/providers.json` 加载元数据
+- 内置 14+ Provider 的默认配置 (baseUrl, defaultModel, envKey, maxTokens)
+- 首次加载自动生成默认配置文件
+- getProvider(id) 快速查找
+
+**LocalConfigLoader** (`local-config.ts`): 本地 Provider 配置
+
+**ModelCatalog** (`catalog.ts`): 模型能力目录（capabilities, cost, context window）
+
+---
+
+## 三、数据流 (一次 LLM 调用)
+
+```
+Agent Core
+  │ createStream(messages, tools)
+  ▼
+ProviderManager.getProvider()
+  │ ↓ 返回组合好的 Provider 对象
+  ▼
+FallbackProviderChain.createStream()
+  │ 依次尝试链中每个 ResilientProvider
+  ▼
+ResilientProvider.createStream()
+  │ 重试 + 断路器检查
+  │ ↓ 成功后
+  ▼
+AnthropicProvider.createStream()
+  │ HTTP 请求 → Anthropic API
+  │ ↓ 流式返回
+  ▼
+StreamEvent (text, tool_call, thinking, error...)
+  │ 逐层向上 yield
+  ▼
+Agent Core 消费事件
+```
+
+---
+

package/start-webui.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -e
+
+echo ""
+echo "╔══════════════════════════════════════════════╗"
+echo "║       Hyacinth WebUI — One-Click Start      ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Step 1: Install frontend dependencies (if needed)
+if [ ! -d "webui/node_modules" ]; then
+    echo "[1/2] Installing frontend dependencies..."
+    cd webui && npm install && cd ..
+else
+    echo "[1/2] Frontend dependencies OK"
+fi
+
+# Step 2: Build and start
+echo "[2/2] Starting Hyacinth WebUI..."
+echo ""
+
+npx hyacinth serve --webui --webui-port 3100
+
+

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/event-store.ts","./src/index.ts","./src/lifecycle-integration-test.ts","./src/types.ts","./src/agents/builtins.ts","./src/agents/config-loader.ts","./src/agents/delegate-tool.ts","./src/agents/index.ts","./src/agents/registry.ts","./src/channels/auto-detect.ts","./src/channels/index.ts","./src/channels/interface.ts","./src/channels/manager.ts","./src/channels/builtin/http-webhook.ts","./src/channels/builtin/tui-channel.ts","./src/channels/plugins/feishu/feishu-channel.ts","./src/channels/plugins/feishu/feishu-client.ts","./src/channels/plugins/feishu/feishu-config.ts","./src/channels/plugins/feishu/feishu-event.ts","./src/channels/plugins/feishu/feishu-log-suppressor.ts","./src/channels/plugins/feishu/feishu-message-queue.ts","./src/channels/plugins/feishu/feishu-send.ts","./src/channels/plugins/feishu/feishu-session.ts","./src/channels/plugins/feishu/feishu-streaming.ts","./src/channels/plugins/feishu/feishu-transport.ts","./src/channels/plugins/feishu/index.ts","./src/cli/doctor.ts","./src/cli/training.ts","./src/context/cache-stability.test.ts","./src/context/cache-strategy.ts","./src/context/composer.ts","./src/context/compressor.ts","./src/context/context.test.ts","./src/context/index.ts","./src/context/interface.ts","./src/context/manifest-defaults.ts","./src/context/manifest-loader.ts","./src/context/manifest-types.ts","./src/context/prompt-builder.ts","./src/context/retriever.ts","./src/context/section-resolver.ts","./src/context/tokenizer.ts","./src/context/precision/analyzer.ts","./src/context/precision/default.ts","./src/context/precision/index.ts","./src/context/precision/keyword-pool.ts","./src/context/precision/precision.test.ts","./src/context/precision/strategy.ts","./src/context/precision/summary-store.ts","./src/context/precision/types.ts","./src/dependency/analyzer.ts","./src/dependency/data-flow-tracker.ts","./src/dependency/function-parser.ts","./src/dependency/index.ts","./src/dependency/parser.ts","./src/dependency/types.ts","./src/env/env-collector.ts","./src/env/index.ts","./src/evolution/evolver.ts","./src/evolution/git-manager.ts","./src/evolution/index.ts","./src/evolution/prompts.ts","./src/gateway/cli.ts","./src/gateway/factory.ts","./src/gateway/guardian.ts","./src/gateway/index.ts","./src/gateway/server.ts","./src/gateway/tui.ts","./src/hot-reload/agent-watcher.ts","./src/hot-reload/bundle-watcher.ts","./src/hot-reload/command-watcher.ts","./src/hot-reload/config-watcher.ts","./src/hot-reload/index.ts","./src/hot-reload/manager.ts","./src/hot-reload/manifest-watcher.ts","./src/hot-reload/mcp-watcher.ts","./src/hot-reload/model-catalog-watcher.ts","./src/hot-reload/plugin-watcher.ts","./src/hot-reload/prompt-watcher.ts","./src/hot-reload/provider-watcher.ts","./src/hot-reload/skill-watcher.ts","./src/hot-reload/tool-watcher.ts","./src/knowledge/fts5-retriever.ts","./src/knowledge/index.ts","./src/knowledge/indexer.ts","./src/knowledge/query-preprocessor.ts","./src/knowledge/retriever.ts","./src/knowledge/store.ts","./src/knowledge/structured-store.ts","./src/knowledge/structured-tools.ts","./src/knowledge/tools.ts","./src/knowledge/watcher.ts","./src/lifecycle/index.ts","./src/lifecycle/interface.ts","./src/lifecycle/local-model.ts","./src/lifecycle/manager.ts","./src/lifecycle/supervisor.ts","./src/local-model/download-manager.ts","./src/local-model/index.ts","./src/local-model/llamacpp-provider.ts","./src/local-model/model-bridge.ts","./src/local-model/model-registry.ts","./src/local-model/types.ts","./src/logging/index.ts","./src/logging/logger.ts","./src/mcp/bridge.ts","./src/mcp/client.ts","./src/mcp/config.ts","./src/mcp/index.ts","./src/mcp/install-manager.ts","./src/mcp/lifecycle.ts","./src/mcp/process-transport.ts","./src/mcp/side-effect.ts","./src/mcp/system.ts","./src/memory/compression-boundary.ts","./src/memory/conversation.ts","./src/memory/events.ts","./src/memory/index.ts","./src/memory/memory-store.ts","./src/memory/memory.test.ts","./src/memory/session-allowlist.ts","./src/memory/session.ts","./src/memory/stats.ts","./src/memory/summary.ts","./src/modes/bootstrap.mode.test.ts","./src/modes/bootstrap.mode.ts","./src/modes/index.ts","./src/modes/manager.ts","./src/modes/plan.mode.ts","./src/modes/spec.mode.ts","./src/modes/todo.mode.ts","./src/modes/types.ts","./src/modes/utils.ts","./src/multimodal/index.ts","./src/orchestrator/index.ts","./src/orchestrator/loop.ts","./src/orchestrator/plan-store.ts","./src/orchestrator/planner.ts","./src/parser/index.ts","./src/parser/router.ts","./src/plugins/api.ts","./src/plugins/define.ts","./src/plugins/index.ts","./src/plugins/loader.ts","./src/plugins/manager.ts","./src/plugins/plugins.test.ts","./src/plugins/types.ts","./src/prompts/loader.ts","./src/provider/anthropic.ts","./src/provider/catalog.ts","./src/provider/compatible.ts","./src/provider/config.ts","./src/provider/deepseek.ts","./src/provider/fallback.ts","./src/provider/gemini.ts","./src/provider/index.ts","./src/provider/interface.ts","./src/provider/local-config.ts","./src/provider/local.test.ts","./src/provider/local.ts","./src/provider/manager.ts","./src/provider/mimo.ts","./src/provider/minimax.ts","./src/provider/model-catalog-loader.ts","./src/provider/model-router.ts","./src/provider/openai.ts","./src/provider/qwen.ts","./src/provider/resilient.test.ts","./src/provider/resilient.ts","./src/provider/retry.ts","./src/provider/router.ts","./src/provider/zhipu.ts","./src/registry/agent.registry.ts","./src/registry/base.ts","./src/registry/channel.registry.ts","./src/registry/index.ts","./src/registry/mcp.registry.ts","./src/registry/plugin.registry.ts","./src/registry/provider.registry.ts","./src/registry/skill.registry.ts","./src/registry/tool.registry.ts","./src/repair/loop-guard.test.ts","./src/repair/loop-guard.ts","./src/repair/scavenge.ts","./src/repair/storm.ts","./src/runtime/config-center.ts","./src/runtime/config-schema.ts","./src/runtime/defaults.ts","./src/schedule/cron.ts","./src/schedule/index.ts","./src/schedule/persistence.ts","./src/schedule/schedule.test.ts","./src/schedule/scheduler.ts","./src/schedule/types.ts","./src/setup/config.ts","./src/setup/index.ts","./src/setup/model-defaults.ts","./src/setup/persona-bootstrap.test.ts","./src/setup/persona-bootstrap.ts","./src/setup/wizard.ts","./src/skills/index.ts","./src/skills/loader.ts","./src/skills/registry.ts","./src/skills/skill-tool.ts","./src/tools/bash.ts","./src/tools/bootstrap.test.ts","./src/tools/bootstrap.ts","./src/tools/bundle-registry.ts","./src/tools/code-graph.ts","./src/tools/config.ts","./src/tools/edit.ts","./src/tools/executor.ts","./src/tools/filtered-registry.ts","./src/tools/function-context.ts","./src/tools/git-tool.ts","./src/tools/glob.ts","./src/tools/grep.ts","./src/tools/index.ts","./src/tools/injection-filter.ts","./src/tools/insert.ts","./src/tools/interface.ts","./src/tools/mode-tools-compat.ts","./src/tools/mode-tools.ts","./src/tools/multi-edit.ts","./src/tools/path-sandbox.ts","./src/tools/read.ts","./src/tools/registry.ts","./src/tools/restart.ts","./src/tools/result-buffer.ts","./src/tools/runtime-control.ts","./src/tools/tools.test.ts","./src/tools/training.ts","./src/tools/write.ts","./src/tools/python-bridge/bridge.ts","./src/tools/python-bridge/executor.ts","./src/tools/python-bridge/index.ts","./src/tools/python-bridge/parser.ts","./src/training/adapter-bridge.ts","./src/training/adapter.ts","./src/training/aggregator.ts","./src/training/dataset.ts","./src/training/model-store.ts","./src/training/refined-store.ts","./src/training/refiner.ts","./src/training/scheduler.ts","./src/ui/assistant-message.ts","./src/ui/chat-log.ts","./src/ui/command-registry.ts","./src/ui/hyperlink-markdown.ts","./src/ui/markdown-message.ts","./src/ui/osc8-hyperlinks.ts","./src/ui/pi-tui-editor.ts","./src/ui/slash-commands.ts","./src/ui/slash-panel.ts","./src/ui/theme.ts","./src/ui/tool-display.ts","./src/ui/tool-execution.ts","./src/ui/tui-formatters.ts","./src/ui/user-message.ts","./src/update/check.ts","./src/update/config.ts","./src/update/download.ts","./src/update/index.ts","./src/update/install.ts","./src/update/types.ts","./src/utils/misc.ts"],"errors":true,"version":"6.0.3"}