附录C:源码结构总览

个人公众号

源码根目录:src/qwenpaw/


顶层文件

文件说明
__init__.py包入口,导出版本等基本信息
__main__.py入口点,支持 python -m qwenpaw 运行
__version__.py版本号定义
constant.py全局常量:路径、默认值、环境变量加载与解析
exceptions.py自定义异常类与 LLM API 异常转换器

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
src/qwenpaw/
├── agent_stats/ # Agent 统计信息收集
├── agents/ # Agent 核心:ReAct 循环、技能、提示词、工具
│ ├── acp/ # ACP(Agent Communication Protocol)服务端
│ ├── hooks/ # Agent 生命周期钩子
│ ├── md_files/ # 内置 Markdown 模板文件(zh/en/ru)
│ ├── memory/ # 记忆管理与向量搜索
│ │ └── proactive/ # 主动记忆检索
│ ├── mission/ # Mission 模式(自治迭代任务)
│ ├── skills/ # 内置技能目录(多语言版本)
│ ├── skills_hub/ # 技能池(Skill Pool)管理
│ ├── tools/ # 内置工具实现
│ └── utils/ # Agent 相关工具函数
├── app/ # FastAPI 应用层
│ ├── approvals/ # 工具防护审批机制
│ ├── channels/ # 频道实现(各通信平台)
│ │ ├── console/ # 控制台频道
│ │ ├── dingtalk/ # 钉钉频道
│ │ ├── discord_/ # Discord 频道
│ │ ├── feishu/ # 飞书/Lark 频道
│ │ ├── imessage/ # iMessage 频道
│ │ ├── matrix/ # Matrix 频道
│ │ ├── mattermost/ # Mattermost 频道
│ │ ├── mqtt/ # MQTT 频道
│ │ ├── onebot/ # OneBot v11 频道
│ │ ├── qq/ # QQ 频道
│ │ ├── telegram/ # Telegram 频道
│ │ ├── voice/ # Twilio 语音频道
│ │ ├── wecom/ # 企业微信频道
│ │ ├── weixin/ # 微信(iLink)频道
│ │ └── xiaoyi/ # 小艺(华为 A2A)频道
│ ├── crons/ # Cron 定时任务引擎
│ │ └── repo/ # Cron 任务持久化仓库
│ ├── mcp/ # MCP(Model Context Protocol)客户端管理
│ ├── routers/ # FastAPI 路由(REST API 端点)
│ ├── runner/ # Agent 运行器(会话管理、守护命令)
│ │ ├── control_commands/ # 运行时控制命令
│ │ └── repo/ # 会话存储仓库
│ └── workspace/ # 工作空间管理
├── backup/ # 备份与恢复
│ ├── _ops/ # 备份/恢复操作
│ └── _utils/ # 安全文件交换工具
├── cli/ # 命令行接口(Click 框架)
├── config/ # 配置系统(Pydantic 模型、加载/保存)
├── envs/ # 环境变量持久化(加密存储)
├── local_models/ # 本地模型管理(下载、llama.cpp 集成)
├── plugins/ # 插件系统(加载、运行、注册表)
├── providers/ # LLM Provider 实现
├── security/ # 安全子系统
│ ├── secret_store.py # 加密密钥存储
│ ├── skill_scanner/ # 技能安全扫描
│ │ ├── analyzers/ # 代码分析器
│ │ ├── data/ # 扫描规则数据
│ │ └── rules/ # 扫描规则与签名
│ └── tool_guard/ # 工具防护
│ ├── guardians/ # 各类工具守护者
│ └── rules/ # 防护规则
├── token_usage/ # Token 用量追踪
├── tokenizer/ # 分词器(Token 计数)
├── tunnel/ # 隧道(Cloudflare Tunnel 集成)
└── utils/ # 通用工具(日志、遥测、系统信息)

关键模块导出

qwenpaw.config

导出说明
Config根配置模型(config.json 完整结构)
ChannelConfig频道配置集合
AgentsConfigAgent 管理配置
AgentsRunningConfigAgent 运行时参数
SecurityConfig安全配置(工具防护、文件防护、技能扫描)
ToolGuardConfig工具防护配置
ACPConfigACP 协议配置
load_config加载配置文件
save_config保存配置文件
get_available_channels获取可用频道列表

qwenpaw.envs

导出说明
load_envsenvs.json 加载环境变量(自动解密)
save_envs保存环境变量到 envs.json(自动加密)
set_env_var设置单个环境变量
delete_env_var删除单个环境变量
load_envs_into_environ启动时注入环境变量到 os.environ

qwenpaw.exceptions

导出说明
ProviderErrorProvider 错误(PROVIDER_ERROR
ModelFormatterError模型消息格式化错误(MODEL_FORMATTER_ERROR
SystemCommandException系统命令执行错误(SYSTEM_COMMAND_ERROR
ChannelError频道通信错误
AgentStateErrorAgent 状态与会话错误(AGENT_STATE_ERROR
SkillsError技能管理错误(SKILLS_ERROR
convert_model_exceptionLLM API 异常自动转换器

内置 Provider

Provider ID模块文件说明
openaiproviders/openai_provider.pyOpenAI 及兼容 API
anthropicproviders/anthropic_provider.pyAnthropic Claude
geminiproviders/gemini_provider.pyGoogle Gemini
ollamaproviders/ollama_provider.pyOllama 本地推理
lmstudioproviders/lmstudio_provider.pyLM Studio 本地推理
openrouterproviders/openrouter_provider.pyOpenRouter 聚合
qwenpaw-localproviders/provider.py + local_models/内置 llama.cpp 本地推理