数据截至 (上游 commit 38006dda2d96)
Agent 与模型:ReActAgent 之上的组装、prompt、provider
30 秒导读: 本章讲 QwenPaw 里"那个真正会思考、会调工具的 agent"到底是怎么拼出来的。核心一句话:
QwenPawAgent本体什么都不自己造——模型、系统 prompt、工具包、中间件全部由外部的AgentBuilder组装好、从构造函数塞进来;agent 类只负责在 agentscope 2.0 的ReActAgent之上,叠加几层 QwenPaw 特有的行为(coding mode、多模态降级、文本-only 自动续跑、上下文压缩接管)。往下是"模型接入层":一个统一的Provider抽象把 OpenAI/Anthropic/DashScope/Gemini 等各家 API 收成同一种ChatModelBase,再套上重试、限流、token 计量三层包装。
本章聚焦"agent 本体 + 模型接入"。上一层的运行时编排(谁在什么时候调 AgentBuilder)见 01-request-lifecycle.md;有哪些工具、skill→tool 的机制见 03-skills.md 与 04-channels-drivers-mcp.md;工具守卫与沙箱见 05-security.md。
1. 这是什么(零基础也能懂)
一句话定义
QwenPawAgent 是 QwenPaw 的主 agent 类:它继承 agentscope 2.0 的 Agent(即 ReAct 循环:推理 → 调工具 → 看结果 → 再推理),然后在外面包一圈"生产环境要的脏活"——模型不支持图片时怎么办、模型只回了一段文字没干活时要不要催它继续、上下文太长怎么压。
它解决什么问题
假设你要把"一个通用 LLM"变成"一个能在真实终端里连续干活好几十轮、还不崩"的助手。裸的 ReAct 循环干不了这些:
| 现实里会出的岔子 | QwenPawAgent 怎么兜 |
|---|---|
| 用户塞了张图,但当前模型是纯文本模型 | 调模型前先剥掉图片块,失败了再学一次"这模型拒收媒体" |
| 模型只回了句"好的我来规划一下"就停了,没调工具 | 注入一条 system-hint,让外层循环再转一轮(自动续跑) |
| 聊了几十轮,上下文超了模型窗口 | 交给上下文管理器压缩 / 把 老消息卸到磁盘 |
| 切换到另一个供应商,第一次调用必失败 | 用进程级"能力缓存"记住这个模型的怪癖 |
它的设计原则:自己不造零件
这是理解整章的钥匙。看构造函数签名(agents/react_agent.py:53 QwenPawAgent.__init__),几乎所有东西都是关键字入参:
# 示意,非源码 —— 说明"依赖全从外部注入"这个设计
agent = QwenPawAgent(
name=..., # 谁
model=..., # 已经包好重试/限流/计量的 ChatModelBase
system_prompt=..., # 已经拼好的整段文字
toolkit=..., # 已经装满工具的 Toolkit
react_config=..., # max_iters 等
middlewares=[...], # 洋葱圈中间件
... # offloader / context_manager / memory_manager / governor
)
模块 docstring 把话说死了:"Agent construction is fully delegated to AgentBuilder"(agents/react_agent.py:1-10)。谁来造这些零件?下一节的 AgentBuilder。
2. 顶层全景(它大概怎么转)
两个主角:装配工 vs 产品
QwenPaw 把"造 agent"和"agent 本体"拆成两个东西:
AgentBuilder(runtime/builder.py:23)——每次请求都跑一遍的装配工。它去各个注册表取零件、拼成一个完整 agent。QwenPawAgent(agents/react_agent.py:40)——被装出来的产品,只管跑 ReAct 循环 + 叠加行为。
一次装配的数据流
下图从上到下是 AgentBuilder.build()(runtime/builder.py:92)的真实顺序,命中即用:
AgentBuilder.build(ctx)
│
┌─────────────────────────┼─────────────────────────┐
▼ ▼ ▼
① 模型 + formatter ② 系统 prompt ③ 工具包 Toolkit
build_model() build_prompt() build_toolkit()
│ │ │
create_model_and_ PromptManager local_workspace
formatter() .build_sync() .list_tools()
│ (9 个 contributor + coding tools
Provider.get_chat_ 按 priority 拼) + driver/MCP tools
model_instance() + memory tools
│
套 3 层包装:
TokenRecording →
Retry → (router?)
│
└──────────────┬───────────────┬─────────────┘
▼
④ 中间件 middlewares（洋葱圈）
ToolCoordinator / Memory / ToolResultPruning / Langfuse
│
▼
QwenPawAgent(name, model, system_prompt,
toolkit, middlewares, ...) ← 全部注入
│
▼
agent.load_state_dict() ← 恢复历史会话
部件一句话职责
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
AgentBuilder | 每请求装配一个 agent | runtime/builder.py:23 |
QwenPawAgent | ReAct 循环 + QwenPaw 行为叠加 | agents/react_agent.py:40 |
create_model_and_formatter | 建模型实例 + 套三层包装 | agents/model_factory.py:1409 |
Provider | 各家 API 的统一抽象 | providers/provider.py:396 |
ProviderManager | 管所有 provider,给出"当前活跃模型" | providers/provider_manager.py:81 |
PromptManager + contributors | 把 prompt 拆成 9 个片段按序拼 | runtime/prompt_contributors.py:302 |
TokenRecordingModelWrapper | 记 token 用量(计费/统计) | token_usage/model_wrapper.py:15 |
RetryChatModel | 重试 + 限流 | providers/retry_chat_model.py:290 |
QwenPawOffloader | 把压缩掉的历史/工具结果落盘 | agents/offloader.py:29 |
3. 核心原理(逐个机制,由浅入深)
3.1 系统 prompt 是怎么拼出来的
要解决的小问题: 一段系统 prompt 不是一坨死文本——它要拼进用户工作目录里的 AGENTS.md、身份、记忆、多模态提示、coding mode 说明、环境信息……而且每样都可能"有就加、没有就跳过"。
思路: 把 prompt 切成一堆独立"贡献者"(contributor),每个只管自己那一小块,PromptManager 按 priority 从小到大排好、跳过空的、用双换行拼起来(runtime/prompt_manager.py:80 排序,:113 build_sync)。
QwenPaw 内置 9 个 contributor,顺序即最终 prompt 的段落顺序(runtime/prompt_contributors.py:302 _ALL_CONTRIBUTORS):
| priority | contributor | 贡献的段落 |
|---|---|---|
| 5 | AgentIdentityContributor | # Agent Identity(agent id) |
| 10 | AgentsMdContributor | 工作目录的 AGENTS.md(处理 heartbeat/memory 标记) |
| 20 | SoulMdContributor | SOUL.md(核心人格) |
| 30 | ProfileMdContributor | PROFILE.md(身份/用户画像) |
| 80 | MultimodalHintContributor | "你只能看文字"这类能力提示 |
| 85 | CodingModeContributor | coding mode 的一大段行为规范 |
| 86 | ScrollContextContributor | scroll 上下文策略的召回指引 |
| 88 | DriverPolicyHintContributor | driver/MCP 权限的即时提示 |
| 90 | EnvContextContributor | 时间/会话/OS 环境块 |
关键细节:md_files/ 与 AGENTS.md 是"数据"不是"指令模板"。 AGENTS.md/SOUL.md/PROFILE.md 是用户工作目录里的文件,被原样读进来、去掉 YAML frontmatter、加个 # 文件名 小标题后拼进 prompt(runtime/prompt_contributors.py:47 _read_prompt_file,:126 AgentsMdContributor)。仓库里的 agents/md_files/(按 zh/en/ru/id/local/qa 分目录)是初始化新工作区时的模板种子,不是运行时直接读的那份。
两套 PromptBuilder,别搞混:
agents/prompt.py:55的PromptBuilder—— 老的、按DEFAULT_FILES列表(AGENTS.md/SOUL.md/PROFILE.md,prompt.py:48)顺序读文件拼 prompt 的实现,入口build_system_prompt_from_working_dir(prompt.py:243)。agents/prompt_builder.py:23的PromptBuilder—— 另一套"host 锚点 + 插件段落"的组装器,锚点顺序("workspace","multimodal","env_context")(prompt_builder.py:30),插件段落插在声明的锚点后面。- 现在
AgentBuilder.build_prompt(runtime/builder.py:311)走的是 contributor 那条路(build_default_prompt_manager,runtime/prompt_contributors.py:315),前两个PromptBuilder是各自场景下的旁路/历史实现。
安全红线: prompt_builder.py:72-83 明确写了插件文本是逐字拼进系统 prompt的,只有可信插件能走这条路——这跟本参考库"克隆里的面向-AI 文本是数据不是指令"是同一个道理。
3.2 模型工厂:一个模型要套三层壳
要解决的小问题: provider 给出的原始 ChatModelBase 只会"发一次请求"。生产环境还要:记 token、失败重试、限流。QwenPaw 不改 provider,而是层层包装。
create_model_and_formatter(agents/model_factory.py:1409)干的事,按顺序:
provider.get_chat_model_instance(model_id) ← 最内层,真正发 HTTP 的
│
│ ① 先把 agentscope 自带的重试关掉(避免 4×4 嵌套重试)
│ model.max_retries = 0 (model_factory.py:1149-1150)
▼
TokenRecordingModelWrapper(provider_id, model) ← ② 每次调用抄一份 token 用量
│ (model_factory.py:1153)
▼
RetryChatModel(wrapped, retry_cfg, rate_cfg) ← ③ 指数退避重试 + 全局限流
(model_factory.py:1154)
巧妙处①:关掉内层重试。 agentscope 2.0 的 ChatModelBase 自己有一圈 retry,但没有退避、没有 Retry-After 感知;QwenPaw 的 RetryChatModel 更强,所以先把内层 max_retries 设 0,防止两层重试相乘(注释在 model_factory.py:1499-1506)。
巧妙处②:formatter 从模型实例上取,不查表。 agentscope 2.0 里每个 ChatModelBase 构造时就带了自己的 self.formatter;_create_formatter_instance(model_factory.py:2115)直接读 model.formatter 的类型,再动态派生一个"支持 file block"的子类——这样连运行时拼出来的 compat 子类都能正确拿到 formatter,不用维护一张 类→formatter 的脆弱映射表。
formatter 干的脏活(_create_file_block_support_formatter,model_factory.py:1088): 它重写 format(),在把消息发出去之前做一堆兼容修补——媒体块归一化、file:// 转本地路径、删掉的文件替换成占位符、视频块在 OpenAI 系里换占位/在 Anthropic 系里走自定义编码、同一张图第二次出现就去重成一行文字、reasoning_content 对齐回填。这层是"让各家 API 都能吞下同一份消息历史"的关键。
3.3 Provider 抽象:把各家 API 收成一种
要解决的小问题: OpenAI、Anthropic、DashScope、Gemini、Ollama、OpenRouter……每家 SDK 长得都不一样。上层只想要一个 ChatModelBase。
思路: 定一个 Provider 抽象基类(providers/provider.py:396,继承 ProviderInfo + ABC),它既是配置载体(base_url/api_key/models 列表等,都是 pydantic 字段),又定义了几个必须实现的方法:
| 抽象方法 | 职责 | 定义处 |
|---|---|---|
check_connection | 探活 | provider.py:400 |
fetch_models | 拉取可用模型列表 | provider.py:404 |
check_model_connection | 单模型可用性 | provider.py:415 |
get_chat_model_instance | 造出真正的 ChatModelBase | provider.py:749 |
get_chat_model_instance 是核心——每个 provider 自己知道该 new 哪个 agentscope 模型类、怎么塞 credential。以 DashScope 为例(providers/dashscope_provider.py:51):它继承 OpenAIProvider(因为 DashScope 的 compatible-mode 说 OpenAI 协议),只重写这一个方法,去 new agentscope 原生的 DashScopeChatModel,并用一个运行时拼出来的 _DashScopeChatModelCompat 子类(dashscope_provider.py:147)往每次 _call_api 里注入自定义追踪头、并处理"用户没显式开 thinking 时别把 enable_thinking 发出去"的怪癖。
generate_kwargs 的合并规则(容易踩): provider 级参数是底,模型级参数覆盖在上,嵌套 dict 深合并;max_tokens 若没显式给就注入模型自己的(provider.py:623 get_effective_generate_kwargs)。返回的永远是新 dict,调用方改不脏 provider 状态。
"当前活跃模型"从哪来: ProviderManager.get_active_chat_model(providers/provider_manager.py:951)= 取活跃模型槽(get_active_model,:193)→ 找到对应 provider → 调它的 get_chat_model_instance。这就是工厂拿到"最内层模型"的入口。
3.4 模型路由:按 local/cloud 选槽(目前是脚手架)
要解决的小问题: 想让 agent 在"本地小模型"和"云端大模型"之间自动选。
实现: RoutingChatModel(agents/routing_chat_model.py:64)本身也是个 ChatModelBase,内部持有 local_endpoint 和 cloud_endpoint 两个 RoutingEndpoint(:55),__call__ 时先让 RoutingPolicy.decide(:34)选一条路,再把请求委托给对应 endpoint 的模型。
当前策略非常朴素: decide 把 text/channel/tools_available 参数直接 del 丢掉(routing_chat_model.py:41),只看配置里的 mode 是 local_first 还是 cloud_first 返回固定路由——还没有"按内容复杂度/成本"的真实路由逻辑。
诚实说明: 在本 commit 里,RoutingChatModel / RoutingEndpoint 没有被任何地方实例化——全仓搜索只有它自己的定义文件和 AgentsLLMRoutingConfig 配置项引用它(migration.py / routers/config.py / config.py)。也就是说,路由是已搭好骨架、配置项也在、但运行时装配路径尚未接线的能力。AgentBuilder.build_model(runtime/builder.py:355)走的是单模型的 create_model_and_formatter,不经过 router。(inferred:属"预留能力",非已启用主路径。)
3.5 多模态容错:两道防线
要解决的小问题: 用户可能塞图片/音视频,但当前模型不一定吃。硬发过去就是一个 400。
QwenPaw 在 QwenPawAgent._reasoning(agents/react_agent.py:405)里设了两道防线:
一次 _reasoning
│
┌───────────────────┴───────────────────┐
▼ 主动防线 ▼ 被动防线
调模型前先查: 真发出去 400 了?
模型支持多模态吗? →失败→ 是媒体相关错误吗?
或缓存里学过"拒收媒体"? │(react_agent.py:549
│是 │ _is_bad_request_or_media_error)
▼ ▼是
剥掉媒体块再发 往能力缓存写 rejects_media=True,
(或让 formatter 剥) 剥掉媒体,重试一次
关键细节:400 不能一律当"拒收媒体"。 _is_bad_request_or_media_error(react_agent.py:567)特意收紧:内容安全拒绝、请求过大、超上下文长度这些 400 都否决掉——因为把它们误判成"模型不支持媒体"会污染能力缓存,导致后续请求默默丢掉用户的图(注释 :558-566)。只有错误信息里真出现 image/audio/video/vision/multimodal 才算数。
学到的怪癖存哪: ModelCapabilityCache(providers/model_capability_cache.py:24)——进程级、不落盘、线程安全,key 是 provider:model。它只在"确认失败→恢复"之后才写(learn,:53),很保守。已知能力键:rejects_media、needs_reasoning_content。另有一份 capability_baseline.py(:12 ExpectedCapability/ProbeSource)记录"官方文档声称的多模态能力"以及探测结果与文档不符时的 DiscrepancyLog。
3.6 文本-only 自动续跑
要解决的小问题: 模型有时只回一句"好的,我来规划一下"就停了,既没调工具也没真干活。用户得再敲一句"继续"。
思路: _reasoning 拿到最终消息后,若判定该续跑(_should_auto_continue,react_agent.py:518:配置开了、这轮没有 tool_call、tool_choice != none、还没到 max_iters),就往上下文塞一条 user 角色的 system-hint(react_agent.py:480-507),然后直接 return——让 agentscope 的外层 ReAct 循环自然再转一轮。hint 内容按语言分中英两版(_AUTO_CONTINUE_HINT_ZH/EN,:328/339),还会把上一轮助手回复的尾部若干字符附进去当上下文(_auto_continue_tail_context,:355)。
妙在: 它不自己写 while 循环重试,而是"喂一条消息 + return",借力框架已有的外层循环(注释 react_agent.py:370-371)。
3.7 Token:计量 vs 估算,两件不同的事
初学者最容易混。QwenPaw 里"token"有两条完全独立的线:
| 计量(billing/统计) | 估算(触发压缩) | |
|---|---|---|
| 目的 | 记"这次真花了多少 token" | 判"上下文快满了没" |
| 数据来源 | 模型响应里的真实 usage 字段 | 字符数 / 除数 的近似 |
| 谁干的 | TokenRecordingModelWrapper | EstimatedTokenCounter / model.count_tokens |
| 落哪 | 磁盘 JSON(按日/provider/model 聚合) | 只用于当下判断,不落盘 |
计量线: TokenRecordingModelWrapper._record_usage(token_usage/model_wrapper.py:35)从 ChatResponse.usage 抄出 input_tokens/output_tokens,enqueue 一个 _UsageEvent 到 TokenUsageManager(token_usage/manager.py:96)。这是同步 fire-and-forget(注释说 ~100ns,不 await),再由 TokenUsageBuffer(token_usage/buffer.py:29)异步批量刷盘。查询走 get_summary/get_details(manager.py:177/265),按日期区间聚合出 by_model/by_date。另外它还把最近一次用量按 session 存进内存(_store_usage,model_wrapper.py:87),供每轮回显。
顺带一个 vLLM 兼容小坑:
model_wrapper.py:121把tool_choice="auto"改成None——因为没开--enable-auto-tool-choice的 vLLM 会因为auto直接拒请求,置空后既绕过检查又保留 tools。
估算线: 运行时判断"要不要压缩上下文"时,agentscope 侧调 agent.model.count_tokens(**kwargs)(如 agents/middlewares.py:250、scroll 的 manager.py:156)。QwenPaw 自己的 EstimatedTokenCounter(agents/utils/estimate_token_counter.py:8)则是纯字符估算:len(text.encode("utf-8")) / divisor,除数可配(中文用 2-3、英文 4-5,:16-26)。每轮结束还会 snapshot_context_usage_for_state(token_usage/turn_usage.py:24)估一份上下文占用写进消息 metadata(TURN_USAGE_META_KEY,:14),给 UI 显示"上下文用了百分之多少"。
关于 tokenizer/ 目录: 仓库带了一份 Qwen 本地 tokenizer 词表(src/qwenpaw/tokenizer/ 下 tokenizer.json/vocab.json/merges.txt/tokenizer_config.json)。但在本 commit 的 src/ Python 代码里没找到直接加载这份词表做计数的路径——运行时的上下文估算走的是上面的字符估算 + model.count_tokens。这份词表更像是打包进去的数据资产(供 agentscope 的 Qwen/DashScope 计数或离线用途)。(inferred:未见直接 loader,故不能断言其运行时用途。)
3.8 上下文管理:压缩、卸载、pruning
长会话必然撑爆窗口。QwenPaw 有三个协作的机制:
① 压缩接管(compress_context,agents/react_agent.py:137)。 若注入了 context_manager(scroll 策略),压缩完全交给它;否则回落到 agentscope 原生压缩,且受 context_compact_config.enabled 开关控制。_save_to_context(:157)在每次写上下文后再通知 context_manager 把这些块"写穿"到它的存储。
② 卸载到磁盘(QwenPawOffloader,agents/offloader.py:29)。 它实现 agentscope 的 Offloader 协议,原生 compress_context 触发时自动把被驱逐的消息按日期追加到 {dialog_path}/{YYYY-MM-DD}.jsonl(offload_context,:46),把被截断的工具结果单独写成 {uuid}.txt(offload_tool_result,:105)。close() 时按保留天数清过期文件(cleanup_expired,:138)。
③ 工具结果分级截断(ToolResultPruningMiddleware,agents/middlewares.py:406)。 中间件形态,在 on_acting(:443,工具执行后)扫描上下文里所有 tool_result 块:最近 N 条用大阈值、更老的用小阈值,某些工具名/文件扩展名豁免走大阈值(:485 起)。截断前先把完整输出存成文件,保证可恢复(_truncate_tool_result,:597)。
3.9 coding / mission 两种 mode 怎么影响 agent
mode 是"往 prompt 里塞一段人格 + 往工具包里塞几个工具",不是换一个 agent 类。
Coding Mode:
- 人格:
_CODING_SYSTEM_PROMPT_TEMPLATE(modes/coding/mixin.py:27)是一大段行为规范——怎么建*_TODO.md追踪任务、代码引用用path:line形式、优先用lsp/ast_search、文件操作必须用绝对路径、shell 命令要显式传cwd。它由CodingModeContributor(runtime/prompt_contributors.py:202,priority 85)在 coding mode 开启时拼进 prompt。 - 工具:
collect_coding_tools(modes/coding/mixin.py:271)按项目目录探测可用的 LSP 语言、检查ast-grepCLI 在不在,分别加lsp/ast_search工具,都用PolicyGuardedTool包过守卫。 QwenPawAgent继承了CodingModeMixin(react_agent.py:40的 MRO),但实际装配走的是AgentBuilder._collect_coding_mode_tools(runtime/builder.py:530)那条独立函数路径——mixin 上同名方法是历史留存。
Mission Mode: 概念上同构——MissionPromptContributor(modes/mission/contributor.py:20,priority 25)在 mission 激活且有 mission state 时,调 build_mission_system_prompt 拼进一段任务指引。它委托给 agents/mission/prompts.py。
两种 mode 的共同点:都不碰 agent 的核心循环,只在"prompt 片段"和"工具集合"两个可插拔点上加料。
4. 生命周期:reply 与 close
一次回复(_reply)
QwenPawAgent._reply(agents/react_agent.py:679)只在原生 reply 前多做一件事:_inject_pending_hints(:615)——从 ToolCoordinator 弹出后台工具攒下的提示消息,append 进上下文,再走 super()._reply()。真正的推理循环在 agentscope 的 Agent 里,QwenPaw 通过重写 _reasoning(3.5/3.6 讲的两道防线 + 自动续跑)介入其中的每一步推理。
构造时还做了两件设置:把 agentscope 自带权限引擎设为 BYPASS(react_agent.py:128-130,因为 QwenPaw 用自己的 PolicyGuardedTool.check_permissions),以及注册每工具的默认超时到 ToolCoordinator(_register_tool_call_hooks,:633,如 shell 60s、子 agent 300s、browser 内部 3600s)。
关闭(close)
close(react_agent.py:238)按序释放:停 governor → 应用历史保留窗口并释放 scroll 的 sqlite 连接(否则长期运行的服务器会累积 fd)→ 清过期的工具结果文件。
会话持久化
state_dict/load_state_dict(react_agent.py:165/178)把 agent 状态序列化/恢复。load_state_dict 还兼容 1.x 旧格式:检测到 {"memory": {...}} 结构就现场迁移成 2.0 的 AgentState(:213-227),让老会话能平滑升级。
5. 巧妙之处(可借鉴的技术)
-
依赖全外注,agent 零自造。 测试时 mock 任一零件都无摩擦,装配逻辑集中在一个
AgentBuilder里,agent 类保持纯粹(runtime/builder.py:92vsagents/react_agent.py:53)。 -
formatter 从实例类型派生,不查表。
_create_formatter_instance(model_factory.py:2115)读model.formatter的类型再动态建子类,连运行时拼的 compat 子类都自动适配,免维护脆弱映射。 -
关掉内层重试再套自己的。 显式
model.max_retries = 0(model_factory.py:1505),避免两层重试相乘造成 4×4 次无谓请求。 -
400 分诊,拒绝污染能力缓存。
_is_bad_request_or_media_error(react_agent.py:567)把"过大/超长/内容安全"从"媒体不支持"里摘出去,防止误学导致后续默默丢图。 -
自动续跑借力外层循环。 不写手动 while,只塞一条 hint 消息就 return,让框架的 ReAct 循环自然再转(
react_agent.py:479-507)。 -
prompt = 9 个可插 拔 contributor。 加一段 prompt = 加一个 contributor + 定 priority,mode/scroll/driver 都靠这个点接入(
runtime/prompt_contributors.py:302)。
6. 边界与局限
- LLM 路由未接线。
RoutingChatModel定义完整、配置项也在,但本 commit 无实例化路径,AgentBuilder.build_model走单模型工厂;且现有RoutingPolicy.decide只看mode配置、丢弃全部内容信号(routing_chat_model.py:41)。 - 能力缓存不落盘。
ModelCapabilityCache是进程级的(model_capability_cache.py:41),进程重启后"学过的怪癖"清零,同一模型首次调用可能再失败一次。 - token 计量依赖 provider 回传 usage。 若某 provider 的
ChatResponse.usage缺失或为 0,_record_usage直接跳过(model_wrapper.py:48),这次调用不计入统计。 - 本地 Qwen tokenizer 词表运行时用途不明。
src/qwenpaw/tokenizer/有词表文件,但src/里没见到直接加载它做计数的代码;上下文估算走字符近似(estimate_token_counter.py:40)。 - coding mode 的 mixin 与装配双路径并存。
CodingModeMixin在 agent 上,但真正注册工具走AgentBuilder的独立函数,mixin 同名方法属历史留存,读代码时容易误以为 mixin 在起作用。
7. 横向对比
同 ai-agent-reference 货架里,"agent 本体如何在一个第三方 ReAct 框架之上叠加生产行为"是共性关切。QwenPaw 的取舍有两个鲜明特征:
- 薄 agent + 厚装配工。 不少同类项目把模型选择、prompt 拼装、工具注册都写进 agent 类;QwenPaw 反其道,agent 只叠加行为,全部构造外移到
AgentBuilder。 - 包装而非改造 provider。 重试/限流/计量三层都是
ChatModelBase装饰器(model_factory.py:2074-2090),不动 agentscope 原生模型,升级上游时冲突面小。
具体对比表见货架总库 doc 的"agent 组装与模型接入"一节。
8. 代码地图(导航索引)
用符号名 grep 比行号抗漂移。
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| Agent 本体 | src/qwenpaw/agents/react_agent.py | QwenPawAgent |
| 推理拦截(媒体/续跑) | src/qwenpaw/agents/react_agent.py | _reasoning, _should_auto_continue |
| 400 分诊 | src/qwenpaw/agents/react_agent.py | _is_bad_request_or_media_error |
| 生命周期 | src/qwenpaw/agents/react_agent.py | _reply, close, state_dict, load_state_dict |
| 装配工 | src/qwenpaw/runtime/builder.py | AgentBuilder.build, build_model, build_prompt |
| 模型工厂 + 三层包装 | src/qwenpaw/agents/model_factory.py | create_model_and_formatter, _create_formatter_instance |
| formatter 兼容层 | src/qwenpaw/agents/model_factory.py | _create_file_block_support_formatter |
| Provider 抽象 | src/qwenpaw/providers/provider.py | Provider, ModelInfo, get_chat_model_instance |
| Provider 管理器 | src/qwenpaw/providers/provider_manager.py | ProviderManager.get_active_chat_model, get_active_model |
| DashScope provider 实例化 | src/qwenpaw/providers/dashscope_provider.py | DashScopeProvider.get_chat_model_instance, _DashScopeChatModelCompat |
| 模型路由(脚手架) | src/qwenpaw/agents/routing_chat_model.py | RoutingChatModel, RoutingPolicy |
| 重试 + 限流 | src/qwenpaw/providers/retry_chat_model.py | RetryChatModel, RetryConfig, RateLimitConfig |
| 能力缓存 | src/qwenpaw/providers/model_capability_cache.py | ModelCapabilityCache |
| 能力基线/探测 | src/qwenpaw/providers/capability_baseline.py | ExpectedCapability, ProbeSource |
| prompt 组装(现主路径) | src/qwenpaw/runtime/prompt_contributors.py | _ALL_CONTRIBUTORS, build_default_prompt_manager |
| prompt 排序器 | src/qwenpaw/runtime/prompt_manager.py | PromptManager.build_sync |
| 工作目录 prompt(旁路) | src/qwenpaw/agents/prompt.py | build_system_prompt_from_working_dir, PromptBuilder |
| host 锚点 prompt(旁路) | src/qwenpaw/agents/prompt_builder.py | PromptBuilder, HOST_ANCHORS |
| 模板种子 | src/qwenpaw/agents/templates.py | build_agent_template |
| token 计量 | src/qwenpaw/token_usage/model_wrapper.py | TokenRecordingModelWrapper._record_usage |
| token 聚合/查询 | src/qwenpaw/token_usage/manager.py | TokenUsageManager, get_summary |
| token 缓冲落盘 | src/qwenpaw/token_usage/buffer.py | TokenUsageBuffer, _UsageEvent |
| 每轮上下文估算 | src/qwenpaw/token_usage/turn_usage.py | snapshot_context_usage_for_state |
| 字符估算器 | src/qwenpaw/agents/utils/estimate_token_counter.py | EstimatedTokenCounter |
| 上下文卸载 | src/qwenpaw/agents/offloader.py | QwenPawOffloader |
| 工具结果分级截断 | src/qwenpaw/agents/middlewares.py | ToolResultPruningMiddleware, MemoryMiddleware |
| Coding Mode | src/qwenpaw/modes/coding/mixin.py | CodingModeMixin, _CODING_SYSTEM_PROMPT_TEMPLATE, collect_coding_tools |
| Mission Mode | src/qwenpaw/modes/mission/contributor.py | MissionPromptContributor |