人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载本篇指南面向 picoclaw 的维护者与深度贡献者系统讲解当前 Agent 重构工作的目标、工作边界、目录组织方式以及与实现和 GitHub 追踪的关系。读者读完后将掌握本项目重构的核心纪律概念澄清优先、边界收紧优先、语义收敛优先理解pkg/agent/包的文件划分约定agent_*/turn_*/pipeline_*前缀体系并了解 AgentLoop、Turn、Pipeline 三层架构与上下文压缩机制。所有讨论均以 docs/architecture/agent-refactor/ 目录下文档为主体结合仓库源码加以印证。重构的初衷先厘清边界再扩展行为picoclaw 的代码库中已经沉淀了大量真实的 Agent 行为消息循环、工具执行、转向消息、媒体处理、MCP 初始化等但这些行为缺少一个足够显式且稳定的语义边界。重构的初衷很朴素在继续增加任何 Agent 相关行为之前先建立一套更小、更清晰、更稳定的 Agent 模型。代码库已含丰富 Agent 行为 │ ▼ 缺少显式稳定的语义边界 │ ▼ refactor 优先修复边界而非扩功能这也是 docs/architecture/agent-refactor/README.md 反复强调的核心问题本次重构的主问题不是Agent 还能做什么而是现有 Agent 行为可以围绕的最小稳定模型是什么。重构立场维护导向的收敛本次重构是维护主导的收敛性工作maintenance-led consolidation并非邀请并行扩展 Agent 行为。在重构窗口期内与 Agent 相关的工作应收敛到当前重构轨道而不是派生新的语义。落实到具体原则概念澄清优先于功能扩展concept clarification before feature expansion边界收紧优先于抽象增长boundary tightening before abstraction growth语义收敛优先于新行为semantic consolidation before new behavior这些原则与 docs/architecture/README.md 中对架构文档的定位一致该目录收录的是主要运行时机制与子系统设计的内部架构笔记Agent Refactor 目录是其中明确标注的重构工作笔记与检查点。核心规则最小概念原则重构遵循一条硬性规则除非严格必要不要引入新概念。展开来说决策顺序是如果现有概念可以被澄清就复用它如果现有边界可以被显式化先做这一步如果行为可以不用新抽象来表达就不添加新抽象未来灵活性本身不足以作为引入新概念的正当理由。重构的目标不是扩大模型而是降低歧义。这条规则直接约束了同目录下各子文档的产出方式context.md开篇即声明本文件澄清的是既有概念的边界而非引入新概念。当前澄清的工作边界重构当前关注以下 8 个问题它们构成现阶段的工作边界#澄清问题对应实现面1什么是Agentpkg/agent/agent.go 中的AgentLoop结构2什么是AgentLoop消息循环的 Run/Stop/Close 生命周期3AgentLoop的生命周期runAgentLoop、Turn 协调、响应发布4AgentLoop周围的事件表面agent_event.go、runtime event 系统5persona / identity 如何组装Agent 定义与 prompt 组装6capabilities 如何表示tools / skills / MCP 能力语义7上下文边界与压缩如何工作context_budget.go、context_manager.go等8subagent 协调如何工作subturn.go、turn_coord.go这些是当前的工作边界。文档明确要求如果需要调整应当显式调整而不是在代码中隐式漂移。目录定位工作区而非架构文档库状态声明该目录下的文档是工作材料working materials不是最终或不可变的。如果现有笔记不完整、拆分不合理或过于宽泛应当修订。目录应随重构演进而不是假装第一稿就是完整的。建议的文档拆分目录未来可能包含以下主题笔记但只有在有助于澄清当前重构工作时才添加建议文件内容agent-overview.md什么是 Agentagent-loop.mdAgentLoop 契约、生命周期、事件表面persona.mdpersona 与 identity 组装capability.mdtools / skills / MCP 能力语义context.md上下文范围、历史、摘要、压缩subagent.mdsubagent 协调规则同时明确了负面边界该目录不应退化为泛泛的架构转储generic architecture dump不用于——宽泛的推测性架构、当前重构不需要的未来多节点协议设计、与 Agent 收敛无关的并行功能规划、以及在当前概念未澄清前引入新概念。与实现及 GitHub 追踪的关系与实现的关系实现变更不应持续隐式地重新定义 Agent 语义。如果一个 PR 改变或依赖 Agent 语义这些语义应当已经存在于该目录或在关联 issue 中先被澄清。该目录的目的是让实现更窄、更有纪律。与 GitHub 追踪的关系重构的总览 issue 应指向该目录——issue 是协调表面目录是仓库本地的工作表面。文件重命名计划统一pkg/agent/命名重构的一个落地成果是解决了loop_*前缀命名混乱与职责边界不清的问题将pkg/agent/包的文件命名统一化详见 agent-rename-plan.md 与 loop-split.md。12 个文件重命名原文件新文件职责loop.goagent.goAgentLoop 主体 生命周期方法loop_message.goagent_message.go消息处理与路由loop_outbound.goagent_outbound.go响应发布loop_event.goagent_event.go事件系统loop_command.goagent_command.go命令处理loop_steering.goagent_steering.go转向消息处理loop_transcribe.goagent_transcribe.go音频转写loop_media.goagent_media.go媒体处理loop_mcp.goagent_mcp.goMCP 初始化loop_utils.goagent_utils.go工具函数loop_inject.goagent_inject.go依赖注入loop_turn.goturn_coord.goTurn 协调器文件合并2 → 1原文件新文件说明turn.goturn_exec.goturn_state.goTurn 相关类型定义集中命名约定前缀内容示例agent_*AgentLoop 方法文件agent_message.go、agent_event.goturn_*Turn 生命周期相关turn_coord.go、turn_state.gopipeline_*Pipeline 方法pipeline_setup.go、pipeline_llm.gocontext_*上下文管理context_manager.go、context_legacy.gohook_*Hook 系统hook_process.go、hook_mount.go从当前仓库源码看这一约定已完全落地pkg/agent/ 目录下可看到agent.go、agent_message.go、agent_event.go、agent_command.go、agent_steering.go、agent_transcribe.go、agent_media.go、agent_mcp.go、agent_utils.go、agent_inject.go、agent_outbound.go、turn_coord.go、turn_state.go以及pipeline_*.go系列文件与计划中的最终结构一致。三层架构AgentLoop → Turn Coordinator → Pipeline架构分层图重构确立了清晰的三个职责层┌─────────────────────────────────────────────────────────┐ │ AgentLoop (agent.go) │ │ - Message loop Run/Stop/Close │ │ - Dependency injection (agent_inject.go) │ │ - Message routing (agent_message.go) │ │ - Response publishing (agent_outbound.go) │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Turn Coordinator (turn_coord.go) │ │ - runTurn(): main coordinator │ │ - abortTurn(): abort │ │ - askSideQuestion(): side question │ │ - selectCandidates(): model selection │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Pipeline (pipeline_*.go) │ │ - SetupTurn(): initialization │ │ - CallLLM(): LLM call │ │ - ExecuteTools(): tool execution │ │ - Finalize(): finalization │ └─────────────────────────────────────────────────────────┘在源码层面AgentLoop结构pkg/agent/agent.go聚合了消息总线、配置、Agent 注册表、运行时事件系统、Hook 管理器、上下文管理器、fallback 链、频道管理器、媒体存储、转写器、命令注册表、MCP 运行时、steering 队列等依赖并通过workerSem限制并发 Turn 处理、用activeTurnStates防止同会话重复 Turn、以activeReqMu/activeReqCond/activeReqCount替代 WaitGroup 避免并发竞态——这些都是重构后边界收紧的直接体现。文件拆分回顾从 4384 行到 12 个聚焦文件根据 loop-split.md 的记载pkg/agent/loop.go原文件约 4384 行已被拆分为 12 个聚焦源文件。这是一次纯重构无行为变更No Logic Changes所有函数原样搬移保持行为等价。拆分目标包括降低浏览 agent loop 代码时的认知负担、通过解耦关注点支持并行开发、维持全部既有功能与测试、保持每个文件最小化 import。Pipeline 拆分按职责切分 ~1400 行pipeline-restructuring-plan.md 记录了将agent/pipeline.go约 1400 行按职责拆分的计划实际行数如下文件行数职责pipeline.go39Pipeline结构 NewPipeline()依赖容器pipeline_setup.go115SetupTurn()历史组装、消息构建、候选选择pipeline_llm.go519CallLLM()PreLLM hooks、fallback、重试、AfterLLM hookspipeline_execute.go693ExecuteTools()BeforeTool/ApproveTool/AfterTool hooks、媒体发送、steering 处理pipeline_finalize.go78Finalize()会话保存、压缩、状态设置合计1444Turn 协调器与 Pipeline 的关系AgentLoop (agent.go) │ ├── runAgentLoop() ──────────────────┐ │ │ │ ┌───────────────────────────────▼───────────────────────────────┐ │ │ Turn Coordinator (turn_coord.go) │ │ │ │ │ │ runTurn() { │ │ │ exec pipeline.SetupTurn() │ │ │ loop { │ │ │ ctrl pipeline.CallLLM() ──► Pipeline (pipeline_*.go) │ │ │ if ctrl ToolLoop { │ │ │ toolCtrl pipeline.ExecuteTools() │ │ │ } │ │ │ } │ │ │ return pipeline.Finalize() │ │ │ } │ │ └───────────────────────────────────────────────────────────────┘ │ └── Publish response (agent_outbound.go)这段伪代码精确反映了 Turn 的执行形态SetupTurn初始化 → 循环中CallLLM与ExecuteTools交替ToolLoop控制继续执行工具→ 最终Finalize收尾随后由agent_outbound.go发布响应。从源码看pipeline_setup.go、pipeline_llm.go、pipeline_execute.go、pipeline_finalize.go均已存在于 pkg/agent/并有对应的pipeline_streaming.go补充流式处理。上下文边界与压缩context.md 要点重构文档中与实现关系最密切的是 context.md它显式化了 agent loop 中上下文管理的四条边界。上下文窗口的四块区域区域由谁组装是否存会话System promptBuildMessages()静态 动态部分否SummarySetSummary()存储BuildMessages()注入独立于历史会话历史user / assistant / tool 消息是工具定义Provider adapter 在调用时注入否同时MaxTokens输出生成上限也必须从总预算中预留因此历史可用空间为history_budget ContextWindow - system_prompt - summary - tool_definitions - MaxTokensContextWindow 与 MaxTokens 的区分MaxTokensLLM 单次响应可生成的最大 token 数作为max_tokens请求参数发送ContextWindow模型的总输入上下文容量。此前两者被设为相同值导致摘要阈值要么过早触发默认 32K要么在用户调高max_tokens后根本不触发。当前默认未显式配置时ContextWindow MaxTokens * 4。会话历史只存对话消息会话历史仅包含user、assistant可能含ToolCalls、tool三类消息不包含System prompt由BuildMessages在请求时组装和 Summary 内容经SetSummary单独存储、由BuildMessages注入。任何操作会话历史的代码——压缩、边界检测、token 估算——都不能假设其中存在 system 消息。Turn压缩的原子单元Turn是一个完整循环user 消息 → LLM 迭代可能含工具调用→ 最终 assistant 响应。该定义源自 agent loop 设计#1316。会话历史中 Turn 边界由user角色消息标识。Turn 是压缩的原子单元在 Turn 内部切割会孤立工具调用序列——一条含ToolCalls的 assistant 消息与其对应的tool结果被分离。按 Turn 边界压缩从构造上避免了这一问题。对应实现函数parseTurnBoundaries(history)返回每个 Turn 的起始索引findSafeBoundary(history, targetIndex)将目标切割点吸附到最近的 Turn 边界。三条压缩路径按优先级优先级路径触发时机与机制1异步摘要maybeSummarize每条 Turn 完成后运行消息数超阈值或估算历史 token 超过ContextWindow百分比时后台 goroutine 调 LLM 对最旧消息生成摘要经SetSummary存储下一次调用由BuildMessages注入 system prompt切割点用findSafeBoundary保证不拆 Turn2主动预算检查isOverContextBudget每次 LLM 调用前运行使用完整预算公式message_tokens tool_def_tokens MaxTokens ContextWindow超预算则触发forceCompression并重建消息后再调用 LLM避免产生必然以 context-window 错误失败且被计费的调用3应急压缩forceCompression响应式主动检查失效、LLM 仍返回 context-window 错误时运行丢弃最旧约 50% 的 Turn若历史为单个 Turn 且无安全切分点退化为仅保留最近一条 user 消息——作为最后手段打破 Turn 原子性避免上下文超限死循环压缩说明写入会话摘要而非历史消息供下次BuildMessages纳入 system prompt第三条路径是对token 估算低于现实的兜底。Token 估算方式估算采用启发式约每 token 2.5 字符chars * 2 / 5。estimateMessageTokens统计Content按 rune 计数保证多字节正确性、ReasoningContent扩展思考/思维链、ToolCallsID、类型、函数名、参数、ToolCallID工具结果元数据、每条消息的固定开销role 标签、JSON 结构、Media条目每项独立估算后直接加总不走字符启发式因为实际成本取决于分辨率与 provider 特定的图片 token 化。estimateToolDefsTokens统计工具定义开销名称、描述、参数 JSON schema。这些刻意保持启发式主动检查覆盖常见情形响应式路径兜底估算误差。接口边界与数据流上下文预算函数parseTurnBoundaries、findSafeBoundary、estimateMessageTokens、isOverContextBudget是纯函数只接收[]providers.Message与整数参数不依赖AgentLoop或其他运行时结构从源码看这些函数集中在 pkg/agent/context_budget.go而BuildMessages位于 pkg/agent/context.go与文档描述一致。BuildMessages是发往 LLM 的最终消息数组的唯一组装者预算函数只参与压缩决策不构造消息。数据流为budget check -- compression decision -- mutate session -- BuildMessages reads session -- LLM call已知缺口如实记录摘要触发未使用完整预算公式maybeSummarize只用估算历史 token 与ContextWindow百分比比较未计入 system prompt 大小、工具定义开销与MaxTokens预留。主动检查覆盖了关键路径防 400 错误但摘要触发可与同一预算模型对齐以获得更精准的早期压缩。Token 估算为启发式未考虑 provider 特定 token 化、精确的 system prompt 大小另行组装、可变的图片 token 成本。双路径设计主动 响应式用于容忍这种不精确。响应式重试不保留媒体响应式路径压缩后重建上下文时媒体引用传入空值。这是主循环的既有问题非预算系统引入。文档也明确列出不覆盖的内容AGENT.mdfrontmatter 如何配置上下文参数属于 Agent 定义工作、新架构中上下文构建器的组装方式后续工作、压缩事件如何通过事件系统呈现属于事件模型 #1316、subagent 上下文隔离独立轨道。验证结果与测试纪律两个拆分/重命名计划文档都记录了相同的验证结果✅go build ./pkg/agent/...— 通过✅go vet ./pkg/agent/...— 无警告✅go test ./pkg/agent/... -skip TestSeahorse|TestGlobalSkillFileContentChange— 通过关于测试需注意重构文档如实披露有 5 个测试失败TestGlobalSkillFileContentChange与 4 个 Seahorse 测试是重构前已存在的失败与本次重构无关。当前仓库中pkg/agent/下存在大量配套测试如context_budget_test.go、context_test.go、pipeline_streaming_test.go、turn_coord_test.go、turn_state_test.go、agent_mcp_test.go等印证了维持全部既有功能与测试的拆分原则。总结本次 Agent Refactor 的全部决策可以收敛为一句话主问题不是Agent 还能做什么而是现有 Agent 行为可以围绕的最小稳定模型是什么。围绕这一核心重构确立了四条可操作的纪律贡献者可直接引用最小概念原则除非严格必要不引入新概念能澄清就澄清能显式化边界就先显式化文件组织约定pkg/agent/按agent_*AgentLoop 方法、turn_*Turn 生命周期、pipeline_*Pipeline 方法、context_*上下文管理、hook_*Hook 系统划分职责且已落地为最终结构三层架构AgentLoop消息循环→ Turn CoordinatorrunTurn协调→ PipelineSetupTurn/CallLLM/ExecuteTools/Finalize四阶段上下文压缩闭环以 Turn 为原子单元的纯函数预算检查 三条压缩路径异步摘要 / 主动预算 / 应急压缩双保险。当贡献者提交任何改变或依赖 Agent 语义的 PR 时请先确认该语义要么已经记录在 docs/architecture/agent-refactor/ 目录中要么在关联 issue 中被显式澄清——这正是本目录存在的意义让实现更窄、更有纪律。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐Opik Python SDK 重构指南以 Refactor-Helper Agent Skill 落实代码质量清单Opik Python SDK 重构指南以 Refactor Helper Agent Skill 落实代码质量清单 本文以开源仓库 Opikcomet l人工智能LLMOps模型评测可观测性AI AgentAI 应用后端前端Picoclaw Agent 文件重命名计划pkg/agent 目录结构重构实战Picoclaw Agent 文件重命名计划pkg/agent 目录结构重构实战 导读 本文梳理 picoclaw 项目中 pkg/agent/ 包的一次系统人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆Mastra 入门指南理解 Agent 概念并构建你的第一个 AI AgentMastra 入门指南理解 Agent 概念并构建你的第一个 AI Agent 导读 本文是 Mastra 第一个 Agent 课程的开篇核心目标是用最直接人工智能Agent 框架AI AgentRAG后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考