企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• 工具调用
• MCP Clients
• Agent 记忆

本篇指南面向 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 目录是其中明确标注的"重构工作笔记与检查点"。

核心规则：最小概念原则

重构遵循一条硬性规则：

除非严格必要，不要引入新概念。

展开来说，决策顺序是：

1. 如果现有概念可以被澄清，就复用它；
2. 如果现有边界可以被显式化，先做这一步；
3. 如果行为可以不用新抽象来表达，就不添加新抽象；
4. "未来灵活性"本身不足以作为引入新概念的正当理由。

重构的目标不是扩大模型，而是降低歧义。这条规则直接约束了同目录下各子文档的产出方式：context.md开篇即声明"本文件澄清的是既有概念的边界，而非引入新概念"。

当前澄清的工作边界

重构当前关注以下 8 个问题，它们构成现阶段的工作边界：

这些是当前的工作边界。文档明确要求：如果需要调整，应当显式调整，而不是在代码中隐式漂移。

目录定位：工作区而非架构文档库

状态声明

该目录下的文档是工作材料（working materials），不是最终或不可变的。如果现有笔记不完整、拆分不合理或过于宽泛，应当修订。目录应随重构演进，而不是假装第一稿就是完整的。

建议的文档拆分

目录未来可能包含以下主题笔记，但只有在有助于澄清当前重构工作时才添加：

同时明确了负面边界：该目录不应退化为泛泛的架构转储（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 个文件重命名

文件合并（2 → 1）

命名约定

从当前仓库源码看，这一约定已完全落地：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 行）按职责拆分的计划，实际行数如下：

Turn 协调器与 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 中上下文管理的四条边界。

上下文窗口的四块区域

同时MaxTokens（输出生成上限）也必须从总预算中预留，因此历史可用空间为：

history_budget = ContextWindow - system_prompt - summary - tool_definitions - MaxTokens

ContextWindow 与 MaxTokens 的区分

• MaxTokens：LLM 单次响应可生成的最大 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 边界。

三条压缩路径（按优先级）

第三条路径是对"token 估算低于现实"的兜底。

Token 估算方式

估算采用启发式：约每 token 2.5 字符（chars * 2 / 5）。

estimateMessageTokens统计：Content（按 rune 计数保证多字节正确性）、ReasoningContent（扩展思考/思维链）、ToolCalls（ID、类型、函数名、参数）、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 行为可以围绕的最小稳定模型是什么"。

围绕这一核心，重构确立了四条可操作的纪律，贡献者可直接引用：

1. 最小概念原则：除非严格必要，不引入新概念；能澄清就澄清，能显式化边界就先显式化；
2. 文件组织约定：pkg/agent/按agent_*（AgentLoop 方法）、turn_*（Turn 生命周期）、pipeline_*（Pipeline 方法）、context_*（上下文管理）、hook_*（Hook 系统）划分职责，且已落地为最终结构；
3. 三层架构：AgentLoop（消息循环）→ Turn Coordinator（runTurn协调）→ Pipeline（SetupTurn/CallLLM/ExecuteTools/Finalize四阶段）；
4. 上下文压缩闭环：以 Turn 为原子单元的纯函数预算检查 + 三条压缩路径（异步摘要 / 主动预算 / 应急压缩）双保险。

当贡献者提交任何改变或依赖 Agent 语义的 PR 时，请先确认：该语义要么已经记录在 docs/architecture/agent-refactor/ 目录中，要么在关联 issue 中被显式澄清——这正是本目录存在的意义：让实现更窄、更有纪律。

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• 工具调用
• MCP Clients
• Agent 记忆