[Roadmap]: LocalAgentRunner 与业界标准的差距分析与改进方向

[huanghuoguoguo]

背景

根据对 Claude Agent SDK、LangGraph、OpenAI Agents SDK 等业界主流 Agent 框架的分析，LangBot 的 LocalAgentRunner 在健壮性和生产就绪性方面存在差距。

但需注意：LangBot 架构与 standalone agent SDK 不同，某些业界特性在 LangBot 场景下适用性有限。

业界标准特性对比

特性	Claude Agent SDK	LangGraph	LangBot 当前	优先级	状态
Context Engineering	Token budget + 自动压缩	持久化状态	❌ 只有轮次截断	P0	#3 已覆盖
Tool 并行执行	批量并行	并行节点	❌ 顺序执行	P1	#2 已覆盖
Tool 结果截断	max-tool-result-chars	❌	❌ 无限制	P0	#1 已覆盖
Tool 结果持久化	文件引用而非注入	❌	❌ 直接注入	P1	#4 已覆盖
Human-in-the-loop	interrupt + AskUserQuestion	interrupt_after	❌ 缺失	P2	架构不适用
Hooks/Guardrails	18 个生命周期钩子	Middleware 拦截	❌ 缺失	P2	价值有限
Subagents	Agent 工具委托	多节点协调	❌ 缺失	P2	待设计
Credential Vault	OAuth token 管理	❌	❌ 缺失	P2	待设计

架构差异说明

LangBot vs Standalone Agent SDK

Claude Agent SDK / LangGraph 是 standalone agent：

• 直接面对用户，agent loop 是核心
• Hooks 可以拦截整个生命周期

LangBot 是 IM bot platform + agent：

• Platform adapter 层截断消息入（Telegram/飞书/QQ）
• Pipeline 层处理流程（preproc → runner → postproc）
• LocalAgentRunner 只是 Pipeline 的一环
• 大部分"拦截"已在 Pipeline 层实现

因此，某些业界特性在 LangBot 场景下适用性有限或实现困难。

Human-in-the-loop [P2] - 架构不适用

业界实现：

• Claude Agent SDK：AskUserQuestion 工具 + 中断点
• LangGraph：interrupt_after 暂停等待人类输入

LangBot 困难：

• 消息流是异步的，用户在不同 IM 平台
• 无法像 CLI 那样直接暂停等待输入
• 需要考虑平台特性（回复、按钮交互），复杂度高

结论：优先级 P2，后续再考虑，当前架构不适用。

Hooks/Guardrails [P2] - 价值有限

业界 Hooks 场景：

• PreToolUse：验证参数、权限检查
• PostToolUse：结果转换、审计
• PreLLMCall：Token budget 检查
• SessionStart/End：会话初始化

LangBot 现状：

• Pipeline/Platform 层已有权限、日志机制
• Tool 结果截断/持久化：[Feature]: LocalAgentRunner Agent Loop 应增加上下文保护与截断机制 #1、[Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4 已覆盖
• Token budget 检查：[Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3 已覆盖
• 完整 Hooks 系统可能与 Pipeline 层功能重叠

结论：核心功能已被现有 Issue 覆盖，完整 Hooks 系统价值有限，不优先。

详细差距分析（优先项）

1. Context Engineering [P0] ✅ #3 已覆盖

业界实现：

• Token budget 管理：为每次 LLM 调用建立统一预算
• 分层裁剪：旧 tool 结果 → 冗长 RAG → 更早历史轮次
• 按需压缩：接近预算时才触发摘要
• 自动重试：超窗时自动触发更强裁剪

已覆盖 Issue：#3 详细设计了三个阶段的改进方案

2. Tool 并行执行 [P1] ✅ #2 已覆盖

业界实现：

• Claude Agent SDK：批量并行执行
• OpenAI：明确建议 parallel tool calls 应并行处理

LangBot 当前：顺序执行，延迟线性叠加

已覆盖 Issue：#2 已提出 asyncio.gather 并行执行方案

3. Tool 结果截断 [P0] ✅ #1 已覆盖

业界实现：max-tool-result-chars 截断机制

已覆盖 Issue：#1 提出截断方案

4. Tool 结果持久化 [P1] ✅ #4 已覆盖

业界实现：超限时持久化到文件，返回引用而非注入

已覆盖 Issue：#4 提出持久化 + 引用方案

建议的改进路线

第一阶段：基础健壮性 [P0] - 已有 Issue 覆盖

• ✅ [Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3: Context Engineering MVP（token budget、分层裁剪、超限重试）
• ✅ [Feature]: LocalAgentRunner Agent Loop 应增加上下文保护与截断机制 #1: Tool 结果截断
• ✅ [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4: Tool 结果持久化

第二阶段：效率优化 [P1]

• ✅ [Feature]: LocalAgentRunner 应支持并行执行 Tool Calls #2: Tool 并行执行

第三阶段：高级特性 [P2] - 待评估

• Human-in-the-loop：架构不适用，需重新设计
• Hooks 系统：核心功能已覆盖，完整系统价值有限
• Subagents：待设计
• Credential Vault：待设计

参考资源

• Anthropic: Effective context engineering for AI agents
• Claude Agent SDK Overview
• LangGraph Guardrails Example
• LangChain AI Agents Guide 2025

关联 Issue

• ✅ [Feature]: LocalAgentRunner Agent Loop 应增加上下文保护与截断机制 #1: 上下文保护与截断机制
• ✅ [Feature]: LocalAgentRunner 应支持并行执行 Tool Calls #2: Tool 并行执行
• ✅ [Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3: Context-window 感知的上下文管理
• ✅ [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4: Tool 结果持久化

[huanghuoguoguo]

Roadmap status update after the Pi-style local-agent alignment work:

Completed / moved out of roadmap risk:

• [Feature]: LocalAgentRunner Agent Loop 应增加上下文保护与截断机制 #1 is implemented and closed as the MVP context-protection / truncation issue.
• [Feature]: LocalAgentRunner 应支持并行执行 Tool Calls #2 is implemented and closed as same-batch parallel tool execution.
• [Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3 has an MVP implemented: token-style context budget, deterministic old-history summary, per-turn budgeting before every model call, and one context-overflow retry.

Still open / should remain tracked:

• [Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3 advanced work: more precise layered trimming and better Host model/token metadata integration.
• [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4 true tool-result persistence: Host artifact/storage-backed references are still not implemented. Current max-tool-result-chars is only a safe model-facing fallback.
• [Tracking]: Pi-style Local Agent adaptation for LangBot runner #6 Phase 5: LLM summary / checkpoint path should wait for Host state/storage and model usage metadata.

Correction to the old roadmap wording:

• Hooks are no longer purely theoretical. The runner now has internal Pi-style lifecycle hooks, but they are intentionally internal runner extension points, not a public LangBot Hook/Guardrails system.
• We should continue borrowing Pi's middle-layer mechanics, not its CLI/TUI product layer or local filesystem/security assumptions.

Next recommended roadmap slice:

• Design the Host artifact/storage contract for oversized tool results and compaction checkpoints before implementing [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4 / [Tracking]: Pi-style Local Agent adaptation for LangBot runner #6 Phase 5.