Posts

欢迎来到我的博客 这是我的第一篇博客！使用 Hugo + PaperMod 主题搭建，部署在 GitHub Pages 上。 关于我 一个热爱技术和分享的开发者。 接下来 我会在这里分享技术文章、学习笔记和各种有趣的内容。

逐行拆解 PI05（Pi 0.5）模型实现，从图像/语言观测到动作序列输出的完整源码分析。覆盖模型初始化、训练前向、推理采样、权重加载、数据预处理及所有工具函数。

逐函数拆解 ZImageControlNetPipeline 的数据流向，从 prompt 输入到最终图像输出的完整 pipeline 分析。

AgentSession — Auto-Retry（自动重试） 文件位置：F:\Pi\packages\coding-agent\src\core\agent-session.ts 依赖的配置类型：F:\Pi\packages\coding-agent\src\core\settings-manager.ts — RetrySettings、getRetrySettings() UI 事件消费：F:\Pi\packages\coding-agent\src\modes/interactive/interactive-mode.ts — auto_retry_start / auto_retry_end 事件处理 编写目的：详细拆解 AgentSession 中 Auto-Retry（自动重试）机制的完整实现，包括 agent-session.ts 中的编排方法、settings-manager.ts 中的配置管理，以及 interactive-mode.ts 中的 UI 消费端。 一、Auto-Retry 概述 Auto-Retry（自动重试）是 AgentSession 中用于自动恢复 LLM 请求失败的机制。当 LLM 提供商返回临时性错误（过载、限流、网络波动）时，Pi 不会直接放弃，而是自动等待一段时间后重试。 设计目标 零干扰恢复：对于临时性的服务端错误，用户无需手动操作，系统自动重试 指数退避：重试间隔逐次翻倍，避免过载时雪上加霜 非重试错误不重试：配额耗尽、上下文溢出等不可恢复错误直接跳过 用户可控：用户可在重试倒计时期间按 Escape 取消，并可配置是否启用 什么错误会被重试 错误类型 重试？ 示例 服务端过载 是 overloaded, service unavailable, 503 限流 是 rate limit, 429, too many requests 网络瞬断 是 connection refused, connection lost, fetch failed 超时 是 timed out, timeout, stream ended before message_stop 服务器内部错误 是 500, 502, 503, 504, server error WebSocket 异常 是 websocket closed, other side closed 配额耗尽 否 quota exceeded, insufficient_quota, available balance 上下文溢出 否 由 Compaction 处理，不是重试的职责 语法/参数错误 否 重试也没用 默认配置 1 2 3 4 5 { enabled: true, // 默认开启 maxRetries: 3, // 最多重试 3 次 baseDelayMs: 2000 // 基础等待 2 秒，逐次翻倍 } 二、AgentSession 中的 Auto-Retry 方法 2.1 _isRetryableError(message) — 判断是否可重试 1 private _isRetryableError(message: AssistantMessage): boolean 位置：agent-session.ts 第 2495 行 ...

AgentSession — Bash Execution（Bash 执行） 文件位置：F:\Pi\packages\coding-agent\src\core\agent-session.ts Bash 结果定义：F:\Pi\packages\coding-agent\src\core\bash-executor.ts — BashResult、executeBashWithOperations() Bash 操作接口：F:\Pi\packages\coding-agent\src\core\tools\bash.ts — BashOperations、createLocalBashOperations() Bash 消息类型：F:\Pi\packages\coding-agent\src\core\messages.ts — BashExecutionMessage UI 消费：F:\Pi\packages\coding-agent\src\modes/interactive/interactive-mode.ts — handleBashCommand()、addMessageToChat() 编写目的：详细拆解 AgentSession 中 Bash Execution（Bash 执行）机制的完整实现，涵盖从用户输入 ! 命令到执行、流式输出、结果持久化的全链路。 一、Bash Execution 概述 Bash Execution 是 AgentSession 中负责执行用户和 LLM 的 bash 命令的模块。Pi 中 bash 执行有三个入口： 用户 !命令 — 用户在交互模式下输入 !ls 直接执行 bash，结果不发给 LLM 用户 !!命令 — 同 ! 但结果也发给 LLM（标记 excludeFromContext: true） LLM 的 bash 工具调用 — Agent 在思考过程中调用 bash 工具 核心消息类型 1 2 3 4 5 6 7 8 9 10 11 export interface BashExecutionMessage { role: "bashExecution"; // 自定义角色 command: string; // 执行的命令 output: string; // 输出内容（可能被截断） exitCode: number | undefined; // 退出码（被取消时为 undefined） cancelled: boolean; // 是否被取消 truncated: boolean; // 输出是否被截断 fullOutputPath?: string; // 完整输出的临时文件路径（截断时） timestamp: number; // 时间戳 excludeFromContext?: boolean; // !! 前缀时不发给 LLM } Bash 执行结果 1 2 3 4 5 6 7 export interface BashResult { output: string; // 合并的 stdout + stderr exitCode: number | undefined; // 退出码 cancelled: boolean; // 是否被取消 truncated: boolean; // 是否被截断 fullOutputPath?: string; // 完整输出文件路径 } 完整执行全景 用户输入 !ls │ ▼ interactive-mode.handleBashCommand() │ ├─ 发送 user_bash 事件 → Extension 可劫持 │ ├─ Extension 返回了完整结果？──是──→ recordBashResult() → 结束 │ ├─ 创建 BashExecutionComponent（UI 组件） │ ├─ isStreaming? │ ├─ 是 → 加入 pendingMessagesContainer（排队） │ └─ 否 → 加入 chatContainer（立即显示） │ └─ 调用 session.executeBash() │ ▼ agent-session.executeBash() │ ├─ 创建 _bashAbortController ├─ 应用 shell 命令前缀（如 alias 支持） ├─ 调用 executeBashWithOperations() │ ├─ 本地执行 → createLocalBashOperations() │ └─ 远程执行 → 自定义 operations（SSH/Docker） │ ├─ recordBashResult() │ ├─ 构建 BashExecutionMessage │ ├─ isStreaming? → 加入 _pendingBashMessages 队列 │ └─ 非 streaming → 立即追加到 agent.state + session │ └─ 返回 BashResult │ ▼ UI 更新 → BashExecutionComponent.setComplete() 二、AgentSession 中的 Bash Execution 方法 2.1 executeBash(command, onChunk?, options?) — 执行 Bash 命令 1 2 3 4 5 async executeBash( command: string, onChunk?: (chunk: string) => void, options?: { excludeFromContext?: boolean; operations?: BashOperations }, ): Promise<BashResult> 位置：agent-session.ts 第 2602 行 ...

AgentSession — Compaction（上下文压缩） 文件位置：.\packages\coding-agent\src\core\agent-session.ts 依赖模块：.\packages\coding-agent\src\core\compaction/ — compaction.ts、utils.ts、branch-summarization.ts 本文拆解 AgentSession 中 Compaction（上下文压缩）机制的完整实现，包括 AgentSession 中的编排方法以及 compaction/ 模块中函数的实现逻辑。在 Agent 的会话机制中，上下文窗口有限和长时间会话的需求之间存在矛盾，而 Compaction 机制正是为了解决这个问题而设计的。 一、Compaction 概述 Compaction（上下文压缩）是 AgentSession 的核心机制之一，用于在长时间会话中压缩历史消息，以维持 LLM 上下文窗口在可管理范围内。Pi 的 Compaction 设计有三个关键特征： LLM 驱动的摘要：不用简单的截断策略，而是调用 LLM 对历史会话生成结构化摘要，保留任务目标、决策、进度等关键信息。Compact 前后的消息列表在语义上保持一致、逻辑上相容，具体的策略由 compaction/branch-summarization.ts 中的 summarizeBranch() 实现。在 agent-session.ts 中， 双模式触发：支持手动触发（/compact 命令）和自动触发（阈值/溢出两种场景） Extension Hook：通过 session_before_compact 扩展事件，允许扩展自定义压缩逻辑或完全接管压缩 Compaction 完整流程 Agent 产生消息 │ ▼ _checkCompaction() ──┬── 检查是否 Overflow ──→ _runAutoCompaction("overflow", willRetry) │ │ │ └── 检查是否超 Threshold ──→ _runAutoCompaction("threshold", false) │ ▼ (用户手动触发) compact() ──→ prepareCompaction() ──→ compact() ──→ sessionManager.appendCompaction() │ │ ▼ ▼ 定位切割点 LLM 生成摘要 计算 tokens 提取文件操作 提取前次摘要 合并为 CompactionResult 二、AgentSession 中的 Compaction 方法 2.1 compact(customInstructions?) — 手动压缩 1 async compact(customInstructions?: string): Promise<CompactionResult> 项目 内容 所在文件 agent-session.ts 返回值 Promise<CompactionResult> — 包含摘要文本、首条保留 entry ID、压缩前 token 数、压缩后估计 token 数、扩展数据 功能 用户或 RPC 模式手动触发压缩的入口。对应 /compact 命令。 执行流程 步骤 1 — 断开 agent 事件并中止当前操作 ...

AgentSession — Model Management（模型管理） 文件位置：F:\Pi\packages\coding-agent\src\core\agent-session.ts 依赖的配置类型：F:\Pi\packages\coding-agent\src\core\settings-manager.ts — defaultThinkingLevel、setDefaultModelAndProvider() 模型注册表：F:\Pi\packages\coding-agent\src\core\model-registry.ts — ModelRegistry AI 兼容层：@earendil-works/pi-ai/compat — clampThinkingLevel()、getSupportedThinkingLevels()、modelsAreEqual() 默认值：F:\Pi\packages\coding-agent\src\core\defaults.ts — DEFAULT_THINKING_LEVEL = "medium" 编写目的：详细拆解 AgentSession 中 Model Management（模型管理）机制的完整实现，涵盖模型选择/切换、thinking level 管理、scoped models 等核心逻辑。 一、Model Management 概述 Model Management 是 AgentSession 中负责管理当前 LLM 模型及相关配置的模块。它包括： 模型选择与切换 — setModel() 直接设置、cycleModel() 循环切换 Thinking Level 管理 — setThinkingLevel()、cycleThinkingLevel()、supportsThinking() Scoped Models — 通过 --models 标志限定的可用模型列表 模型切换事件 — model_select 扩展事件 核心数据结构 1 2 3 4 5 6 7 8 9 10 11 12 // Thinking Level 枚举值 const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high"]; // 默认 Thinking Level const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium"; // cycleModel() 返回类型 export interface ModelCycleResult { model: Model<any>; // 切换后的模型 thinkingLevel: ThinkingLevel; // 切换后的 thinking level isScoped: boolean; // 是否来自 scoped models } 完整流程全景 用户操作 │ ├─ Ctrl+P (cycleModel) │ │ │ ├─ 有 scoped models ──→ _cycleScopedModel() │ │ ├─ 过滤可用的 scoped model │ │ ├─ 计算下一个索引（forward/backward） │ │ ├─ 应用 thinking level（scoped 自带优先） │ │ └─ 更新 agent.state + session + settings │ │ │ └─ 无 scoped models ──→ _cycleAvailableModel() │ ├─ 从 ModelRegistry 获取所有可用模型 │ ├─ 计算下一个索引 │ └─ 更新 agent.state + session + settings │ ├─ /model 命令 (setModel) │ └─ 直接设置模型 + 验证 auth │ └─ Ctrl+T (cycleThinkingLevel) └─ 模型支持 thinking? → 循环下一个 level 状态持久化 每次模型或 thinking level 变更，都会同时写入三处： ...