一、项目整体架构

1.1 项目概述

Hermes Agent（v0.10.0）是Nous Research开发的全栈自改进AI Agent系统。它是一个Python后端 + TypeScript前端的混合项目，通过插件式网关架构将20+消息平台与15+ LLM Provider连接，提供70+内置工具、76个技能包、可插拔上下文引擎和记忆系统，支持ACP协议编辑器集成、MCP桥接和RL训练。

指标	数值
项目版本	v0.10.0
主要语言	Python 3.11+ (后端) + TypeScript (前端TUI/Web)
Python源文件	24,930
TypeScript源文件	17,925
内置工具	70+
技能包(SKILL.md)	76
消息平台适配器	20+
LLM Provider	15+
执行环境	7种 (Local/Docker/SSH/Modal/Daytona/Singularity/SWE)
CLI子命令	30+
CLI主文件	cli.py (469KB!)

1.2 架构模式：六层+插件式全栈Agent架构

Hermes Agent 采用六层+插件式+多前端架构模式：

层级	名称	核心组件	职责
L1	用户界面层	CLI、Gateway、TUI(Ink)、Web UI(React)、ACP Server、Cron、Batch Runner、RL CLI、MCP Server	用户交互入口(9个)
L2	平台适配层	20+ Platform Adapters (Telegram/Discord/WhatsApp/Slack/Feishu/WeCom/Signal/Matrix/Email/DingTalk/QQBot/Webhook/HA/BlueBubbles/Mattermost/API Server…)	消息平台双向适配
L3	Agent核心层	AIAgent + agent/ 子包 (PromptBuilder/ContextEngine/MemoryManager/CredentialPool/SmartModelRouting/ModelMetadata/…)	Agent循环、提示构建、上下文管理
L4	LLM Provider层	15+ Provider Adapters (Anthropic/OpenAI/Google/Bedrock/OpenRouter/DeepSeek/Groq/Ollama/xAI/Copilot ACP/…)	多模型流式调用
L5	工具执行层	Tool Registry (70+ tools) + Toolset Distributions + 7 Execution Environments	工具调度与沙箱执行
L6	基础设施层	Session Store (JSONL)、Hook System (7 events)、Config (YAML)、Auth Store、Security (Tirith/Path)	持久化与安全保障

跨切关注点：

• Skills (76)：按领域分27类（autonomous-ai-agents/creative/devops/mlops/research/…）
• Plugins：Context Engine + Memory Provider，config-driven选择，限1外部Provider
• MCP Bridge：9-tool bridge surface暴露给Cursor/Claude Code等MCP客户端
• Proactive Agent：主动式Agent子目录

1.3 整体运行流程

用户消息 → Platform Adapter (L2)
  → GatewayRunner (L2) [会话解析/路由/Agent缓存]
  → HookRegistry.emit("agent:start") (L6)
  → AIAgent.agent_loop() (L3)
    → PromptBuilder.build() [identity + skills + tools + memory + context]
    → SmartModelRouting → CredentialPool.get() → Provider.stream() (L4)
    → toolCall检测 → ToolRegistry.dispatch() → handler() (L5)
    → _should_parallelize_tool_batch() 并行工具优化
    → ContextEngine.should_compress() → compress() (L3)
    → MemoryManager.sync_all() (L3)
  → DeliveryRouter.route() → PlatformAdapter.send() (L2)
  → SessionManager.persist() → JSONL (L6)
  → HookRegistry.emit("agent:end") (L6)

核心循环：agent_loop() → build_prompt → LLM stream → toolCall检测 → dispatch → result回注 → compression检查 → memory同步 → 重复直到终止或IterationBudget耗尽。

---

二、子模块详细分析

2.1 Agent Core — Agent核心

核心作用：Hermes Agent的"大脑"，驱动LLM调用循环、系统提示构建、上下文压缩、记忆编排、模型选择和凭证故障转移。

关键模块：

模块	文件	核心作用	关键函数/类
AIAgent编排器	run_agent.py	主编排器(原3600行，已拆分30+模块)	AIAgent.__init__(), agent_loop(), _build_system_prompt(), _handle_tool_call(), _compress_context(), _should_parallelize_tool_batch(), switch_model(), _persist_session()
迭代预算	run_agent.py	最大迭代跟踪	IterationBudget, consume(), refund()
代理清洗	run_agent.py	UTF-16代理对清洗	_sanitize_messages_surrogates(), _sanitize_structure_surrogates()
提示构建器	agent/prompt_builder.py	系统提示组装	build_skills_system_prompt(), build_context_files_prompt(), _CONTEXT_THREAT_PATTERNS (11种注入检测)
技能工具	agent/skill_utils.py	技能前置解析	parse_frontmatter(), skill_matches_platform(), iter_skill_index_files()
标题生成	agent/title_generator.py	自动生成对话标题	generate_title()
上下文引擎	agent/context_engine.py	可插拔压缩接口(ABC)	ContextEngine, should_compress(), compress(), on_session_start/end()
内置压缩器	agent/context_compressor.py	Token压缩+摘要	ContextCompressor, 默认实现
记忆管理	agent/memory_manager.py	Builtin + 1外部Provider编排	MemoryManager, prefetch_all(), sync_all(), build_system_prompt(), build_memory_context_block()
记忆提供者	agent/memory_provider.py	记忆后端接口(ABC)	MemoryProvider, store(), retrieve(), search()
上下文引用	agent/context_references.py	交叉引用解析	ContextReferences
智能路由	agent/smart_model_routing.py	便宜/强力模型自动路由	should_use_strong_model(), 30+复杂度关键词匹配
模型元数据	agent/model_metadata.py	模型能力/定价/窗口	fetch_model_metadata(), estimate_tokens_rough(), parse_context_limit_from_error()
models.dev集成	agent/models_dev.py	4000+模型注册表	get_model_info(), get_providers(), 离线优先缓存(1h TTL)
凭证池	agent/credential_pool.py	多密钥故障转移	CredentialPool, rotate_on_error(), cooldown机制
速率限制	agent/rate_limit_tracker.py	每Provider限流追踪	RateLimitTracker
重试工具	agent/retry_utils.py	指数退避+抖动	jittered_backoff()
错误分类	agent/error_classifier.py	错误分类	classify_api_error(), FailoverReason枚举
提示缓存	agent/prompt_caching.py	Anthropic cache_control	apply_anthropic_cache_control()
轨迹记录	agent/trajectory.py	ShareGPT格式对话日志	save_trajectory(), convert_scratchpad_to_think()
使用定价	agent/usage_pricing.py	Token使用与成本计算	estimate_usage_cost(), CanonicalUsage, normalize_usage()
显示	agent/display.py	终端输出格式化	KawaiiSpinner, build_tool_preview(), streaming display
Skill命令	agent/skill_commands.py	技能CLI命令	install_skill(), list_skills()
子目录提示	agent/subdirectory_hints.py	目录上下文提示	SubdirectoryHintTracker
脱敏	agent/redact.py	PII脱敏	redact_sensitive()
洞察	agent/insights.py	Agent分析洞察	Agent运行分析

---

2.2 Gateway & Platforms — 网关与平台适配

核心作用：连接20+消息平台的适配层，处理消息收发、会话管理、投递路由、流式回复和生命周期钩子。

关键模块：

模块	文件	核心作用	关键函数/类
网关运行器	gateway/run.py	启停所有平台适配器	GatewayRunner, start_gateway(), _enforce_agent_cache_cap(max=128), _session_expiry_watcher(TTL=1h), _handle_inbound()
网关配置	gateway/config.py	平台配置管理	GatewayConfig, Platform枚举, _coerce_bool(), _normalize_unauthorized_dm_behavior()
会话管理	gateway/session.py	会话上下文+重置策略+PII脱敏	SessionContext, reset policy, _hash_sender_id() → user_lt;12hexgt;
会话上下文	gateway/session_context.py	线程/对话绑定	SessionSource, thread binding
投递路由	gateway/delivery.py	消息路由到平台/频道	DeliveryTarget, parse(), MAX_PLATFORM_OUTPUT=4000
Hook系统	gateway/hooks.py	事件驱动的生命周期钩子	HookRegistry, emit(), discover_and_load()
内置Hook	gateway/builtin_hooks/boot_md.py	注入boot.md	handle()
流消费者	gateway/stream_consumer.py	流式回复分块	consume_stream()
配对	gateway/pairing.py	设备/频道配对	pair()
重启	gateway/restart.py	优雅重启	restart()
镜像	gateway/mirror.py	消息镜像/广播	mirror_message()
状态	gateway/status.py	网关运行状态	get_status()
贴纸缓存	gateway/sticker_cache.py	贴纸/Emoji缓存	StickerCache
频道目录	gateway/channel_directory.py	频道配置目录	resolve_channel_dir()
显示配置	gateway/display_config.py	UI显示格式	DisplayConfig

平台适配器（20+）：

平台	文件	关键特性
Telegram	telegram.py	python-telegram-bot, BotCommands, Topics, UTF-16长度计算, 媒体
Discord	discord.py	discord.py, Slash commands, Threads, 机器人
WhatsApp	whatsapp.py	Baileys桥接, 媒体处理
Slack	slack.py	slack-bolt, SocketMode, Blocks
飞书	feishu.py / feishu_comment.py	事件订阅, 卡片消息, 评论管理(feishu_comment_rules.py)
企微	wecom.py / wecom_callback.py / wecom_crypto.py	回调模式, 加解密, 消息模板
Signal	signal.py	signal-cli, 群组
Matrix	matrix.py	matrix-nio, 房间管理
钉钉	dingtalk.py	机器人回调
Email	email.py	SMTP/IMAP
SMS	sms.py	SMS网关
Webhook	webhook.py	通用Webhook
QQBot	qqbot/	QQ机器人
HA	homeassistant.py	智能家居控制
蓝泡泡	bluebubbles.py	iMessage桥接
Mattermost	mattermost.py	开源Slack替代
API Server	api_server.py	HTTP API端点
微信	weixin.py	微信公众号
基类	base.py	BasePlatform ABC + UTF-16工具函数

---

2.3 Tool Registry & Toolset — 工具注册与工具集

核心作用：70+工具的中央注册表+工具集别名系统。每个工具模块通过registry.register()声明schema、handler和toolset，AIAgent通过注册表查询和调度。工具集系统支持组合和分发级别管理。

关键模块：

模块	文件	核心作用	关键函数/类
工具注册表	tools/registry.py	中央register()+dispatch()+query()	ToolRegistry, register(), dispatch(), discover_builtin_tools()
模型工具	model_tools.py	从注册表构建LLM工具列表(薄编排层)	get_tool_definitions(), handle_function_call(), get_toolset_for_tool()
工具集	toolsets.py	工具集别名系统: research/full_stack/hermes等	resolve_toolset(), get_all_toolsets(), _HERMES_CORE_TOOLS
工具集分发	toolset_distributions.py	分发级别工具集管理	Distribution-level toolset resolution
结果存储	tools/tool_result_storage.py	工具结果持久化+回合预算	maybe_persist_tool_result(), enforce_turn_budget()
终端工具	tools/terminal_tool.py	Bash/shell执行, PTY, 进程管理	exec_command(), process lifecycle, environment factory
文件工具	tools/file_tools.py / file_operations.py	读/写/编辑/搜索	read_file(), write_file(), patch(), search_files()
浏览器工具	tools/browser_tool.py	Web自动化	browse(), Camofox/BrowserUse/Firecrawl多Provider
Web工具	tools/web_tools.py	Web抓取+URL安全	fetch_url(), check_url_safety()
代码执行	tools/code_execution_tool.py	沙箱代码执行	execute_code()
进程注册	tools/process_registry.py	后台进程管理	process tracking
中断	tools/interrupt.py	工具执行中断	set_interrupt()
审批	tools/approval.py	执行审批(白名单+人工)	request_approval(), is_auto_approved()
MCP工具	tools/mcp_tool.py	MCP服务器/客户端集成	call_mcp_server(), stdio/HTTP
飞书文档	tools/feishu_doc_tool.py	飞书文档操作	read_doc(), write_doc(), create_doc()
飞书云盘	tools/feishu_drive_tool.py	飞书云盘操作	list_files(), upload_file()
智能家居	tools/homeassistant_tool.py	HA API控制	call_service(), get_state()
消息发送	tools/send_message_tool.py	跨通道消息投递	send_to_channel()
图像生成	tools/image_generation_tool.py	AI图像生成	generate_image(), 多Provider
委托工具	tools/delegate_tool.py	子Agent委托/混合Agent	delegate_task()
混合Agent	tools/mixture_of_agents_tool.py	多Agent混合推理	MoA implementation
技能工具	tools/skills_tool.py / skill_manager_tool.py	技能安装/列表/执行	install_skill(), execute_skill()
技能Hub	tools/skills_hub.py	ClawHub技能市场	search_skills(), publish_skill()
技能同步	tools/skills_sync.py	技能同步更新	sync_skills()
技能守卫	tools/skills_guard.py	技能安全守卫	Validation
记忆工具	tools/ todo_tool.py	记忆搜索/存储/召回	search_memory(), store_memory()
Todo工具	tools/todo_tool.py	Todo/任务跟踪	add_todo(), list_todos()
会话搜索	tools/session_search_tool.py	历史会话搜索	search_sessions()
视觉	tools/vision_tools.py	图像分析	analyze_image()
语音转文字	tools/transcription_tools.py	音频转文字	transcribe_audio()
文字转语音	tools/tts_tool.py / neutts_synth.py	TTS合成	synthesize_speech(), NeuTTS
Cron工具	tools/cronjob_tools.py	Cron CRUD	add_job(), list_jobs(), remove_job()
检查点	tools/checkpoint_manager.py	检查点保存/恢复	save_checkpoint(), restore_checkpoint()
预算	tools/budget_config.py	Token/成本预算	check_budget()
路径安全	tools/path_security.py	路径验证	validate_path()
Tirith安全	tools/tirith_security.py	安全策略执行	enforce_policy()
URL安全	tools/url_safety.py	URL安全检查	check_url()
网站策略	tools/website_policy.py	网站访问策略	check_policy()
RL训练	tools/rl_training_tool.py	RL训练环境工具	RL integration
调试	tools/debug_helpers.py	调试自省	Debug introspection
管理网关	tools/managed_tool_gateway.py	管理工具网关	Tool gateway management

---

2.4 LLM Provider Adapters — LLM Provider适配器

核心作用：15+ LLM Provider的适配层，统一stream/complete接口，支持多密钥故障转移、OAuth认证和Anthropic缓存优化。

关键模块：

模块	文件	核心作用	关键函数/类
Anthropic	agent/anthropic_adapter.py	Messages API, tool_use, streaming	stream(), complete(), cache_control
Bedrock	agent/bedrock_adapter.py	AWS Bedrock, converse-stream	stream(), IAM认证
Google Code Assist	agent/google_code_assist.py	Gemini Code Assist API	stream()
Gemini CloudCode	agent/gemini_cloudcode_adapter.py	Gemini CloudCode + OAuth	stream(), OAuth flow
OpenAI兼容	内置于run_agent.py	GPT-4/5, Codex, Responses API	stream/complete, _model_requires_responses_api()
OpenRouter	tools/openrouter_client.py	多模型路由	stream()
DeepSeek	OpenAI兼容	V3/R1, 推理模式	stream()
Groq	OpenAI兼容	LPU推理, 超低延迟	stream()
xAI	tools/xai_http.py	Grok模型	stream()
Ollama	OpenAI兼容	本地模型	stream(), query_ollama_num_ctx()
vLLM/SGLang	OpenAI兼容	自托管推理	stream()
Copilot ACP	agent/copilot_acp_client.py	GitHub Copilot via ACP	ACP协议
辅助客户端	agent/auxiliary_client.py	非标准API降级	stream()
凭证池	agent/credential_pool.py	多密钥池: 429/认证错误时轮换	rotate_on_error(), cooldown
Google OAuth	agent/google_oauth.py	Google OAuth2流程	authorize(), token refresh
Nous限流	agent/nous_rate_guard.py	Nous Provider限流守卫	check_rate()
错误分类	agent/error_classifier.py	可重试/致命/认证错误分类	classify_api_error(), FailoverReason

---

2.5 Config, Session & Hook — 配置/会话/钩子

核心作用：配置管理、会话生命周期和事件钩子系统——Agent运行的基础设施层。

关键模块：

模块	文件	核心作用	关键函数/类
主配置	config.yaml	中央配置：agents/models/channels/tools/cron/skills	YAML格式，热重载
CLI配置模板	cli-config.yaml.example	CLI专用配置模板(45KB!)	完整配置参考
CLI配置加载	hermes_cli/config.py	加载/保存/验证	load_config(), save_config()
网关配置	gateway/config.py	GatewayConfig, Platform枚举	每平台配置, _coerce_bool()
环境加载	hermes_cli/env_loader.py	.env文件加载	环境变量优先级: ~/.hermes/.env → project/.env → shell
会话管理	gateway/session.py	SessionContext: 来源追踪, 重置策略	SessionContext, PII脱敏
会话上下文	gateway/session_context.py	线程/对话绑定	SessionSource
JSONL存储	(内嵌)	每会话对话转录	追加写入
重置策略	(session.py内)	never / on_new_message / timeout	evaluate_reset_policy()
Hook注册表	gateway/hooks.py	发现/加载/触发事件钩子	HookRegistry, emit()
Hook目录	~/.hermes/hooks/	用户钩子: HOOK.yaml + handler.py	约定式发现
生命周期事件	hooks.py	7个事件: gateway:startup, session:start/end, agent:start/end/step, command:*	fire()
内置Hook	builtin_hooks/boot_md.py	注入boot.md	handle()
认证	hermes_cli/auth.py	API密钥存储, OAuth流程	load_auth(), save_auth()
认证命令	hermes_cli/auth_commands.py	认证CLI子命令	Login/logout/refresh
Copilot认证	hermes_cli/copilot_auth.py	GitHub Copilot认证	Token management
钉钉认证	hermes_cli/dingtalk_auth.py	钉钉机器人认证	Callback URL setup
配对	gateway/pairing.py	设备/频道配对协议	pair()
重启	gateway/restart.py	优雅重启+会话保持	restart()
状态	gateway/status.py	网关运行状态	get_status()

---

2.6 CLI & Commands — 命令行接口

核心作用：基于prompt_toolkit的交互式CLI（469KB主文件！），30+子命令覆盖chat/gateway/setup/doctor/models/cron/skills等。支持多Skin、Git Worktree、文件拖放、语音模式等高级特性。

关键模块：

模块	文件	核心作用	关键函数/类
主CLI	cli.py (HermesCLI)	469KB交互式CLI！prompt_toolkit TUI	HermesCLI.__init__(), _build_status_bar_text(), Git Worktree管理, 文件拖放, 语音模式
CLI控制台	cli.py (ChatConsole)	统一输出接口	ChatConsole.print()
主入口	hermes_cli/main.py	argparse根, 子命令分发	hermes chat/gateway/setup/doctor/...
命令注册	hermes_cli/commands.py	CommandDef注册表, 自动补全	COMMAND_REGISTRY, resolve_command()
回调	hermes_cli/callbacks.py	prompt_toolkit回调, 键绑定	Key bindings
Claw集成	hermes_cli/claw.py	ClawHub技能市场	claw_hub()
模型命令	hermes_cli/models.py / providers.py	模型/Provider列表、配置、切换	list_models(), switch_provider()
模型切换	hermes_cli/model_switch.py	交互式模型选择UI	Model picker
模型规范化	hermes_cli/model_normalize.py	模型ID别名归一化	normalize_model_id()
Codex模型	hermes_cli/codex_models.py	Codex专用模型配置	Codex model mapping
Nous订阅	hermes_cli/nous_subscription.py	Nous订阅管理	Subscription status
配置	hermes_cli/config.py	配置文件操作	load_config(), save_config()
设置向导	hermes_cli/setup.py	交互式设置向导	run_setup()
Doctor	hermes_cli/doctor.py	配置+依赖健康检查	run_doctor()
状态	hermes_cli/status.py	系统概览	show_status()
Cron	hermes_cli/cron.py	Cron任务管理	list_cron()
插件	hermes_cli/plugins.py / plugins_cmd.py	插件管理	install_plugin()
技能	hermes_cli/skills_config.py / skills_hub.py / skills_sync.py	技能安装/列表/更新/同步	install_skill(), sync_skills()
记忆	hermes_cli/memory_setup.py	记忆Provider配置	setup_memory()
MCP配置	hermes_cli/mcp_config.py	MCP服务器配置	configure_mcp()
网关	hermes_cli/gateway.py / platforms.py	平台+网关配置	configure_gateway()
认证	hermes_cli/auth.py / auth_commands.py	API密钥/OAuth管理	login(), logout()
配对	hermes_cli/pairing.py	设备配对	pair_device()
备份	hermes_cli/backup.py	配置备份	backup_config()
日志	hermes_cli/logs.py	日志查看	show_logs()
调试	hermes_cli/debug.py / dump.py	调试+转储	dump_state()
视觉	hermes_cli/banner.py / colors.py / tips.py	CLI视觉定制(多Skin)	_accent_hex(), _SkinAwareAnsi
剪贴板	hermes_cli/clipboard.py	剪贴板集成	paste_from_clipboard()
Web服务器	hermes_cli/web_server.py	本地Web服务(浏览器认证)	start_web_server()
Curses UI	hermes_cli/curses_ui.py	Curses UI降级方案	Fallback UI
Profiles	hermes_cli/profiles.py	Agent配置文件管理	switch_profile()
运行时Provider	hermes_cli/runtime_provider.py	运行时Provider解析	resolve_provider()
补全	hermes_cli/completion.py	Shell补全生成	generate_completion()
默认灵魂	hermes_cli/default_soul.py	默认SOUL.md	Default personality
CLI输出	hermes_cli/cli_output.py	结构化CLI输出	Formatted output
卸载	hermes_cli/uninstall.py	卸载清理	uninstall()
RL CLI	rl_cli.py	RL训练专用CLI	Extended timeout, RL-focused prompts
批处理	batch_runner.py	批量提示处理+检查点	BatchRunner, _process_single_prompt(), checkpoint
轨迹压缩	trajectory_compressor.py	后处理压缩轨迹	保护首尾轮次, 仅压缩中间

---

2.7 Environments, Plugins, ACP & Frontend — 环境/插件/ACP/前端

核心作用：执行环境（7种沙箱）、插件系统（上下文引擎/记忆）、ACP协议适配器（编辑器集成）、MCP桥接和前端UI。

关键模块：

模块	文件	核心作用	关键函数/类
环境基类	tools/environments/base.py	抽象执行环境接口(ABC)	BaseEnvironment, exec(), isolate(), cleanup()
本地环境	tools/environments/local.py	本地进程执行(默认)	LocalEnvironment
Docker环境	tools/environments/docker.py	Docker容器沙箱	DockerEnvironment, container lifecycle
SSH环境	tools/environments/ssh.py	远程SSH执行	SSHEnvironment
Modal环境	tools/environments/modal.py / managed_modal.py	Modal云执行	ModalEnvironment, managed variant
Daytona环境	tools/environments/daytona.py	Daytona沙箱IDE	DaytonaEnvironment
Singularity环境	tools/environments/singularity.py	Singularity容器	SingularityEnvironment
文件同步	tools/environments/file_sync.py	环境间文件同步	sync_files()
SWE环境	tools/environments/hermes_swe_env/	SWE-bench评估环境	Benchmark execution
Web研究环境	tools/environments/web_research_env.py	Web研究专用环境	Research agent
Agentic OPD环境	tools/environments/agentic_opd_env.py	Agentic OPD环境	OPD evaluation
上下文引擎插件	plugins/context_engine/	可插拔上下文引擎(LCM等)	register(), config-driven选择
记忆插件	plugins/memory/	外部记忆Provider(Honcho等)	MemoryProvider子类
插件生命周期	(约定)	实例化→on_session_start→per-turn→on_session_end	config.yaml: context.engine, memory.provider
ACP服务端	acp_adapter/server.py	ACP协议服务端(编辑器集成)	HermesACPAgent(acp.Agent), initialize(), prompt(), newSession()
ACP会话	acp_adapter/session.py	ACP会话管理	Session create/resume/fork/list
ACP工具	acp_adapter/tools.py	ACP工具Schema暴露	listTools()
ACP认证	acp_adapter/auth.py	ACP认证	authenticate()
ACP权限	acp_adapter/permissions.py	权限范围执行	checkPermission()
ACP事件	acp_adapter/events.py	ACP事件流	Event streaming
ACP入口	acp_adapter/main.py / entry.py	ACP入口点	hermes acp
ACP注册	acp_registry/	会话+能力注册	Session registry
MCP服务	mcp_serve.py	MCP stdio服务器	9-tool bridge: conversations_list/get, messages_read/send, events_poll/wait, permissions_list_open/respond, channels_list
Cron调度器	cron/scheduler.py	tick()每60s, 文件锁	tick(), run_due_jobs(), fcntl/Windows msvcrt
Cron任务	cron/jobs.py	任务定义, cron表达式	Job, is_due()
Web UI	web/ (React+Vite+shadcn)	配置/状态/日志/会话/分析页面	ConfigPage, StatusPage, LogsPage, SessionsPage, AnalyticsPage
Web组件	web/src/components/	AutoField, OAuthLoginModal, Markdown, ThemeSwitcher	i18n, theming, plugin registry
TUI	ui-tui/ (Ink/React for CLI)	终端TUI: gatewayClient, slash命令, 主题	entry.tsx, gatewayClient.ts, slash/registry.ts
TUI包	ui-tui/packages/hermes-ink	Hermes Ink组件库	React Ink components

---

三、模块调用关系与数据流

3.1 核心依赖关系

CLI/TUI/WebUI (L1) → Gateway/Platforms (L2) → AIAgent (L3) → Providers (L4) → Tools/Envs (L5)
                                         ↕                    ↕
                                   Config/Session         CredentialPool
                                         ↕                    ↕
                                   Hooks/Auth              ModelCatalog

调用方	被调用方	方式
CLI (cli.py)	AIAgent (run_agent.py)	函数调用
Gateway (run.py)	AIAgent	函数调用, Agent缓存
Platform Adapter	GatewayRunner	回调注册
AIAgent	Provider Adapter	stream() / complete()
AIAgent	ToolRegistry	dispatch() → handler()
AIAgent	PromptBuilder	build_system_prompt()
AIAgent	MemoryManager	prefetch_all() / sync_all()
AIAgent	ContextEngine	should_compress() / compress()
AIAgent	CredentialPool	get_credential() / rotate()
GatewayRunner	SessionManager	load_session() / save_session()
GatewayRunner	HookRegistry	emit()
Cron Scheduler	AIAgent	代理运行任务
ACP Server	AIAgent	编辑器集成调用
MCP Server	Gateway/Session	MCP协议桥接
Batch Runner	AIAgent	批量运行+检查点
TUI (Ink)	Gateway API	WebSocket/HTTP
Web UI (React)	Gateway API	HTTP API

3.2 核心请求链路

链路1：Telegram消息处理

TelegramAdapter.on_message()
  → GatewayRunner._handle_inbound()
    → SessionManager.resolve_session() [重置策略检查]
    → HookRegistry.emit("session:start") / ("agent:start")
    → AIAgent.agent_loop()
      → PromptBuilder.build() [identity + skills + tools + memory + context]
      → CredentialPool.get() → Provider.stream()
      → _should_parallelize_tool_batch() [并行优化]
      → toolCall → ToolRegistry.dispatch() → handler()
      → ContextEngine.should_compress() → compress()
      → MemoryManager.sync_all()
      → estimate_usage_cost()
    → DeliveryRouter.route() → TelegramAdapter.send()
    → SessionManager.persist() → JSONL
    → HookRegistry.emit("agent:end")

链路2：CLI交互模式

hermes chat
  → cli.py → HermesCLI.__init__() [prompt_toolkit TUI]
  → AIAgent.agent_loop()
  → (同链路1的Agent流程)
  → ChatConsole.print() / KawaiiSpinner [终端输出]
  → _build_status_bar_text() [上下文进度条]

链路3：ACP编辑器集成

Editor (Cursor/Claude Code)
  → ACP协议
  → acp_adapter/server.py (HermesACPAgent)
    → initialize() / new_session()
    → AIAgent.agent_loop() (编辑器专用配置)
    → ACP事件流回推
    → fork_session() / resume_session()

链路4：MCP客户端调用

MCP Client (Claude Code / Cursor)
  → stdio MCP协议
  → mcp_serve.py
    → conversations_list / messages_read
    → Gateway SessionManager查询
    → messages_send
    → DeliveryRouter → PlatformAdapter.send()
    → permissions_list_open / permissions_respond
    → Approval flow交互

链路5：Cron定时任务

CronScheduler.tick() [每60s, 文件锁]
  → 检查到期任务
  → AIAgent.agent_loop() (cron专用配置)
  → DeliveryRouter.route() → PlatformAdapter.send()

链路6：Batch Runner

batch_runner.py (BatchRunner)
  → 加载数据集 + 创建批次
  → _process_single_prompt() per worker
  → AIAgent.agent_loop()
  → 检查点保存/恢复
  → 轨迹保存 + 压缩(trajectory_compressor.py)

3.3 关键数据传递

数据	来源	目标	方式
InboundMessage	PlatformAdapter	GatewayRunner	回调参数
SessionContext	SessionManager	AIAgent	对象传递
SystemPrompt	PromptBuilder	LLM Provider	函数返回(list[dict])
ToolCall	LLM响应	ToolRegistry	content block解析
ToolResult	ToolHandler	AIAgent上下文	消息追加
Credential	CredentialPool	Provider	pool.get()
MemoryContext	MemoryManager	PromptBuilder	prefetch结果
DeliveryTarget	DeliveryRouter	PlatformAdapter	路由解析
HookEvent	HookRegistry	HookHandler	emit()分发
ACPRequest	ACP Client	HermesACPAgent	ACP协议
MCPRequest	MCP Client	mcp_serve.py	stdio JSON-RPC

3.4 状态管理

会话状态：SessionManager维护每会话JSONL文件：

• 对话历史与重置策略
• PII脱敏(哈希sender/chat ID)
• 线程绑定与来源追踪
• Agent缓存(LRU max=128 + idle TTL=1h)
• SQLite状态数据库(state.db)

配置状态：

• config.yaml中央配置，支持include和环境变量替换
• cli-config.yaml.example完整参考(45KB)
• 热重载(无需重启)
• 备份轮换

认证状态：

• CredentialPool多密钥池：429/认证错误时轮换
• cooldown机制防止频繁切换
• API Key / OAuth双模式
• Provider级独立状态存储

安全状态：

• Exec审批(白名单allowlist + 人工审批)
• 路径安全验证(traversal prevention)
• Tirith策略执行
• URL安全检查 + 网站访问策略
• Prompt注入检测(11种威胁模式)

---

四、架构特点总结

4.1 设计优势

1. 从3600行单文件到模块化：AIAgent从单文件拆分为30+独立模块，可维护性大幅提升
2. 可插拔上下文引擎：ContextEngine接口允许替换压缩策略(LCM等)，config-driven选择
3. 可插拔记忆系统：MemoryManager编排Builtin + 1外部Provider，防止工具Schema膨胀和冲突
4. 多密钥故障转移：CredentialPool + cooldown + 轮换，429/认证错误自动切换
5. 智能模型路由：30+复杂度关键词分析自动选择便宜/强力模型
6. 注入威胁检测：PromptBuilder扫描上下文文件中的11种prompt injection模式
7. 7种执行环境：Local/Docker/SSH/Modal/Daytona/Singularity/SWE可切换沙箱
8. ACP协议集成：编辑器(Cursor/Claude Code等)直接调用Agent能力
9. MCP桥接：9-tool bridge surface暴露对话/消息/权限给MCP客户端
10. 并行工具优化：_should_parallelize_tool_batch()自动检测可并行工具调用
11. UTF-16安全：Telegram等平台的UTF-16长度精确计算和代理对清洗
12. 469KB CLI：功能极其丰富的交互式CLI，支持多Skin/Worktree/拖放/语音

4.2 架构模式

模式	应用位置
插件式	上下文引擎、记忆Provider、平台适配器、工具、技能
分层架构	L1-L6六层单向依赖
网关模式	GatewayRunner中心路由
观察者模式	Hook系统(7个生命周期事件)
策略模式	重置策略、审批策略、路由策略
注册表模式	ToolRegistry, CommandRegistry, HookRegistry, SkillRegistry
适配器模式	Provider/Platform/Environment适配器
对象池模式	CredentialPool, AgentCache
前端组合	React组件(Ink TUI + Web UI) + Plugin系统
桥接模式	MCP Bridge (9-tool surface)

4.3 规模指标

指标	数值
Python源文件	24,930
TypeScript源文件	17,925
工具数	70+
平台适配器	20+
技能包	76 (27类)
LLM Provider	15+
执行环境	7种
CLI子命令	30+
Hook事件	7
CLI主文件大小	469KB
CLI配置模板	45KB