技术栈梳理¶

最后更新：2026-05-05

1. 核心技术选型¶

层级	技术	版本要求	选择理由
语言	Python	>=3.10	生态丰富、AI/ML首选
Web框架	FastAPI	>=0.115	原生async，WebSocket支持好
WebSocket	websockets	>=14	高性能异步WebSocket
HTTP客户端	httpx	>=0.28	原生async，HTTP/2支持
CLI框架	Typer + Rich	>=0.15	类型安全 + 丰富输出
UI (Web)	Next.js	15.x	React框架，SSR/SSG支持
UI (Desktop)	Tauri	2.x	轻量级跨平台桌面应用
UI (Mobile)	Expo React Native	-	跨平台移动应用
配置格式	JSON5	>=0.10	支持注释，兼容JSON
类型系统	Pydantic v2	>=2.10	验证 + 序列化
向量引擎	LanceDB	-	零配置，嵌入式
流式协议	WebSocket v3	-	JSON帧协议
日志	stdlib logging	-	无额外依赖

2. LLM Provider 适配¶

Provider	类型	支持模型	状态
OpenAI	云端	GPT-4o, GPT-4o-mini, o1, o3-mini	✅ 完成
Anthropic	云端	Claude Opus, Sonnet, Haiku	✅ 完成
Google	云端	Gemini 2.0 Flash, Gemini Pro	✅ 完成
Ollama	本地	Llama, Mistral, Qwen, etc.	✅ 完成
OpenAI兼容	混合	OpenRouter, Groq, Together, Fireworks, etc.	✅ 完成
中国提供商	云端	DeepSeek, Moonshot, Zhipu, Qwen, Volcengine, MiniMax, Qianfan	✅ 完成

3. 消息平台通道¶

3.1 即时通讯（8个）¶

平台	协议	状态
Telegram	Bot API (aiogram)	✅
Discord	Bot (discord.py)	✅
Slack	Bot/App (slack-bolt)	✅
WhatsApp	Business API (neonize)	✅
Signal	signal-cli JSON-RPC	✅
Matrix	matrix-nio	✅
IRC	Native TCP/TLS	✅
LINE	Messaging API	✅

3.2 国内平台（5个）¶

平台	状态
钉钉 DingTalk	✅
飞书 Feishu	✅
QQ	✅
Zalo	✅
ZaloUser	✅

3.3 企业平台（5个）¶

平台	状态
Microsoft Teams	✅
Google Chat	✅
Mattermost	✅
Nextcloud Talk	✅
Synology Chat	✅

3.4 其他（9个）¶

平台	状态
Twitch	✅
Nostr	✅
Tlon / Urbit	✅
iMessage	✅ (macOS)
BlueBubbles	✅
Voice Call (Twilio)	✅
Web (内置)	✅

通道总数：27

4. 存储与数据库¶

存储	技术	用途
会话存储	JSONL (文件)	无需数据库，便于调试
记忆-全文	SQLite FTS5 (aiosqlite)	关键词搜索
记忆-向量	LanceDB	语义搜索
配置存储	JSON5文件	用户配置
凭证存储	JSON文件	API密钥管理

5. 开发工具链¶

工具	用途
Ruff	代码检查 + 格式化
pytest	单元测试
pytest-asyncio	异步测试
pytest-cov	测试覆盖率
mypy	类型检查
Playwright	E2E测试
pre-commit	Git钩子

6. 构建与发布¶

6.1 Python 包¶

平台	命令	产物
PyPI	`hatch build`	sdist + wheel
Docker	`docker build`	Container image

6.2 Web 客户端 (Next.js)¶

平台	命令	产物
静态导出	`pnpm build`	静态文件
开发	`pnpm dev`	开发服务器

6.3 桌面客户端 (Tauri)¶

平台	命令	产物
Linux	`pnpm tauri build`	可执行文件 + deb/rpm
macOS	`pnpm tauri build`	.app + .dmg
Windows	`pnpm tauri build`	.exe + .msi

6.4 移动客户端 (Expo)¶

平台	命令	产物
Android	`eas build --platform android`	.apk/.aab
iOS	`eas build --platform ios`	.ipa

7. 设计决策记录¶

决策	选择	理由
Web 框架	FastAPI	原生 async，WebSocket 支持好
CLI 框架	Typer + Rich	类型安全 + 丰富输出
配置格式	JSON5	支持注释，兼容 JSON
会话存储	JSONL (文件)	无需数据库，便于调试
向量引擎	LanceDB	零配置，嵌入式
UI 客户端	TypeScript	跨平台（Web/Tauri/Expo）统一技术栈
LLM 流式	统一 chunk 格式	屏蔽 Provider 差异
进程管理	asyncio subprocess	与 async 架构一致
日志	stdlib logging	无额外依赖
类型系统	Pydantic v2	验证 + 序列化
包管理	Hatch	现代 Python 打包工具
Monorepo	Turborepo + pnpm	TypeScript 多包管理

8. 依赖关系¶

┌─────────────────────────────────────────────────────────┐
│                     CLI (Typer)                          │
│                         │                                │
│              TypeScript 客户端                           │
│              (Web/Desktop/Mobile)                       │
│                         │                                │
│         ┌───────────────┼───────────────┐               │
│         │               │               │               │
│    Channels        Gateway         MCP Client           │
│         │               │               │               │
│         └───────────────┼───────────────┘               │
│                         │                                │
│                  Agent Runtime                          │
│                         │                                │
│         ┌───────┬───────┼───────┬───────┐               │
│         │       │       │       │       │               │
│      Tools  Memory  Skills  SubAgent  Security          │
│         │       │       │       │       │               │
│         └───────┴───────┴───────┴───────┘               │
│                         │                                │
│                  LLM Providers                          │
│         (OpenAI / Anthropic / Gemini / Ollama)          │
└─────────────────────────────────────────────────────────┘

9. 版本兼容性¶

组件	最低版本	推荐版本
Python	3.10	3.11+
Node.js	18	20+
pnpm	8	9+
TypeScript	5.0	5.3+

10. 扩展机制¶

机制	用途	实现方式
entry_points	第三方插件	Python包发现机制
SKILL.md	Agent能力注入	系统提示注入
HOOK.md	事件钩子	生命周期回调
MCP	外部工具服务器	stdio/HTTP协议
ChannelPlugin	消息通道插件	抽象基类继承