coding-agent@earendil-works/pi-coding-agent

要点Key points

• core/agent-session.ts 是 core/ 里最大的文件（interactive 模式的 interactive-mode.ts 更大）：它持有 Agent、SessionManager、ExtensionRunner 与模型运行时，并负责重试、压缩和排队消息。core/agent-session.ts is the largest file in core/ (only interactive mode's interactive-mode.ts is bigger): it owns the Agent, the SessionManager, the ExtensionRunner and the model runtime, and handles retry, compaction and queued messages.
• rpc-entry.ts 只做一件事：调用 main(["--mode", "rpc", …])，并通过 ./rpc-entry 导出路径对外提供。rpc-entry.ts does one thing: call main(["--mode", "rpc", …]); it is published as the ./rpc-entry export path.
• src/extensions/ 里是随包附带的内置扩展（MCP、codemode、tool-search 等），走的是和用户扩展相同的 API。src/extensions/ holds the bundled built-in extensions (MCP, codemode, tool-search …); they use the same API as user extensions.

工作原理How it works

1. pi → setupCli() → main(argv)：解析参数、决定模式、建会话。pi → setupCli() → main(argv): parse args, pick a mode, build the session.
2. SDK 用户直接调用 createAgentSession() 或 createAgentSessionRuntime()，跳过 CLI。SDK users call createAgentSession() or createAgentSessionRuntime() directly and skip the CLI.
3. 所有模式拿到的都是同一个 AgentSessionRuntime，区别只在输入输出方式。Every mode receives the same AgentSessionRuntime; they differ only in how input and output flow.

要点Key points

• 事件先交给扩展、再交给 UI 监听器（_handleAgentEvent），所以扩展总能先看到并改写。Events reach extensions before UI listeners (_handleAgentEvent), so extensions always see and rewrite first.
• 一次运行结束后由 _handlePostAgentRun() 决定是否再跑一次：可重试错误 → 退避重试；超出上下文或超过阈值 → 压缩；还有排队消息 → continue()。After a run, _handlePostAgentRun() decides whether to go again: retryable error → back off and retry; context overflow or over threshold → compact; queued messages → continue().
• 扩展的 tool_call 处理器出错时，工具调用会被阻止，而不是放行。If an extension's tool_call handler throws, the tool call is blocked rather than allowed.
• turn_end 是边界点：扩展可以在两轮之间往会话里追加条目。turn_end is a boundary: extensions may append entries to the session between turns.

工作原理How it works

1. createAgentSession()（sdk.ts）构造 new Agent({ streamFn, convertToLlm, … })，再把它交给 new AgentSession(…)。createAgentSession() (sdk.ts) builds new Agent({ streamFn, convertToLlm, … }) and passes it to new AgentSession(…).
2. AgentSession 构造时安装其余钩子并 agent.subscribe()。The AgentSession constructor installs the remaining hooks and calls agent.subscribe().
3. prompt(text)：运行中按 streamingBehavior 转成 steer() / followUp()，空闲时开始新一轮。prompt(text): while running it becomes steer() / followUp() per streamingBehavior; when idle it starts a run.
4. 运行结束 → _handlePostAgentRun() → 必要时再次 continue()，直到 agent_settled。Run ends → _handlePostAgentRun() → continue() again if needed, until agent_settled.

要点Key points

• session_before_switch / session_before_fork 返回 { cancel: true } 时，整个替换中止，方法返回 { cancelled: true }。If session_before_switch / session_before_fork returns { cancel: true }, the replacement stops and the method returns { cancelled: true }.
• 旧会话按 abort → session_shutdown → dispose() 的顺序关闭；扩展的 TUI 组件被同步卸下。The old session closes in the order abort → session_shutdown → dispose(); extension TUI widgets are detached synchronously.
• 扩展中捕获的旧 ctx 在替换后失效；需要在替换后继续工作的扩展应使用 withSession 回调里的新 ctx。A captured ctx goes stale after replacement; extensions that must keep working should use the fresh ctx passed to withSession.

工作原理How it works

1. switchSession() / newSession() / fork() 先触发对应的 session_before_* 事件。switchSession() / newSession() / fork() first emit the matching session_before_* event.
2. 打开或新建 SessionManager（fork 时 newSession({ parentSession }) 记录来源）。Open or create a SessionManager (fork records the origin via newSession({ parentSession })).
3. createAgentSessionServices() + createAgentSessionFromServices() 建新会话。createAgentSessionServices() + createAgentSessionFromServices() build the new session.
4. 替换 runtime 内的 session / services / diagnostics，再 rebindSession()。Swap session / services / diagnostics inside the runtime, then rebindSession().

要点Key points

• read 从头截断（truncateHead），bash 从尾截断（truncateTail）——命令最后的输出通常最重要。read truncates from the head (truncateHead), bash from the tail (truncateTail) — the end of a command's output usually matters most.
• *Operations 接口让 SDK 宿主把文件系统和 shell 换成远程、容器或测试实现，而不改工具逻辑。The *Operations interfaces let SDK hosts swap the filesystem and shell for remote, container or test implementations without touching tool logic.
• 扩展用 pi.registerTool() 注册的工具与内置工具并列，可通过 setActiveTools() 开关。Tools registered by extensions via pi.registerTool() sit alongside the built-ins and are toggled with setActiveTools().

工作原理How it works

1. createAllTools(cwd, options) 返回 Record<ToolName, Tool>；createCodingTools() / createReadOnlyTools() 是常用子集。createAllTools(cwd, options) returns Record<ToolName, Tool>; createCodingTools() / createReadOnlyTools() are the common subsets.
2. 工具执行结果 → 截断 → 必要时写临时文件并在结果里给出路径。Tool result → truncation → when needed, the full output goes to a temp file and the result names its path.
3. afterToolCall 再把结果交给扩展的 tool_result 事件。afterToolCall then hands the result to the extensions' tool_result event.

要点Key points

• 文件按 cwd 分目录存放在 ~/.pi/agent/sessions/ 下，文件名带时间戳与 UUIDv7。Files live under ~/.pi/agent/sessions/, one directory per cwd, named with a timestamp and a UUIDv7.
• 写入是惰性的：出现第一条 user 或 assistant 消息之前不落盘，首次写入用 wx 标志，避免并发覆盖。Writes are lazy: nothing hits disk before the first user or assistant message, and the first write uses the wx flag to avoid clobbering.
• 读取时按版本迁移（v1 → v2 → v3），必要时整文件重写，然后从叶子沿 parentId 回溯得到当前上下文。On load, entries migrate by version (v1 → v2 → v3), the file is rewritten if needed, and the current context is rebuilt by walking parentId back from the leaf.

工作原理How it works

1. SessionManager.create() / open() → loadEntriesFromFile()。SessionManager.create() / open() → loadEntriesFromFile().
2. migrateSessionEntries() 原地升级到 CURRENT_SESSION_VERSION。migrateSessionEntries() upgrades in place to CURRENT_SESSION_VERSION.
3. buildSessionContext() 处理压缩条目与分支摘要，产出发给模型的消息列表。buildSessionContext() applies compaction entries and branch summaries to produce the messages sent to the model.

要点Key points

• 第 1 行是 session 头（version 3、id、cwd、可选 parentSession）。Line 1 is the session header (version 3, id, cwd, optional parentSession).
• 11 种条目：message、thinking_level_change、model_change、usage、compaction、branch_summary、custom、custom_message、label、session_info、context_edit。11 entry types: message, thinking_level_change, model_change, usage, compaction, branch_summary, custom, custom_message, label, session_info, context_edit.
• 分支不会改写历史：把 leaf 移回旧条目，下一次追加自然形成兄弟分支。Branching never rewrites history: move the leaf to an older entry and the next append becomes a sibling branch.
• context_edit 只追加，能把某个旧条目从模型上下文中删除（replacement: null）或替换其内容。context_edit is append-only and can drop an earlier entry from model context (replacement: null) or replace its content.

工作原理How it works

1. branchWithSummary() 把 leaf 移到分支点，并追加一个 branch_summary（fromId 指向被放弃的 leaf），记录那条路径做过什么。branchWithSummary() moves the leaf to the branch point and appends a branch_summary (with fromId pointing at the abandoned leaf) describing that path.
2. buildSessionContext() 从 leaf 走到根，应用最新的 compaction 与 context_edit，再转换为 LLM 消息。buildSessionContext() walks from leaf to root, applies the latest compaction and context edits, and converts entries to LLM messages.
3. 文件位于 ~/.pi/agent/sessions/<cwd>/，custom 条目供扩展保存状态但不进入上下文，custom_message 则会进入。Files live under ~/.pi/agent/sessions/<cwd>/; custom entries store extension state outside the context, custom_message entries enter it.

要点Key points

• threshold：contextTokens > contextWindow − reserveTokens（默认 reserveTokens = 16384）。threshold: contextTokens > contextWindow − reserveTokens (default reserveTokens = 16384).
• overflow：provider 返回上下文溢出错误或可恢复的 length 截断；删除失败消息、压缩，并只重试一次。overflow: a context-overflow error or a recoverable length stop; drop the failed message, compact, and retry exactly once.
• findCutPoint() 保留约 keepRecentTokens（默认 20000）的最近内容，并让切点落在轮次边界上。findCutPoint() keeps about keepRecentTokens (default 20000) of recent content and puts the cut on a turn boundary.
• 扩展可在 session_before_compact 中取消压缩，或直接提供自己的压缩结果。Extensions can cancel compaction in session_before_compact or supply their own result.

工作原理How it works

1. 自动检查发生在三处：agent_end 之后、提交新提示之前，以及 prepareNextTurn 中（同一次运行的轮次之间）。Automatic checks run in three places: after agent_end, before a new prompt, and inside prepareNextTurn (between turns of one run).
2. token 数优先取最后一条 assistant 的 usage；出错或 usage 为 0 时按 chars/4 估算。Token counts come from the last assistant usage; on errors or zero usage they are estimated at chars/4.
3. appendCompaction(summary, firstKeptEntryId, tokensBefore, …) 之后，上下文重建为“摘要 + 保留的消息”。After appendCompaction(summary, firstKeptEntryId, tokensBefore, …) the context is rebuilt as summary + kept messages.

要点Key points

• deepMergeSettings(global, project)：项目值覆盖全局值，嵌套对象逐键合并。deepMergeSettings(global, project): project values win, nested objects merge key by key.
• pi 包可以来自 npm:、git: 或本地路径，一个包里可以同时带扩展、技能、提示模板和主题。pi packages come from npm:, git: or local paths; one package can ship extensions, skills, prompt templates and themes together.
• SYSTEM.md 整段替换默认开头，并去掉 tools / rules / docs 分段；APPEND_SYSTEM.md 只追加 <addendum>。两者都是项目优先于全局。SYSTEM.md replaces the default preamble and drops the tools / rules / docs sections; APPEND_SYSTEM.md only adds <addendum>. For both, project beats global.
• 上下文文件（AGENTS.md、CLAUDE.md …）从全局目录和 cwd 的每一级祖先目录收集，放进 <project_context>。Context files (AGENTS.md, CLAUDE.md …) are collected from the global dir and every ancestor of cwd into <project_context>.

工作原理How it works

1. createAgentSessionServices() 创建 SettingsManager、ModelRuntime 与 DefaultResourceLoader，并调用 reload()。createAgentSessionServices() creates the SettingsManager, ModelRuntime and DefaultResourceLoader, and calls reload().
2. reload()：resolveProjectTrust → settingsManager.reload() → packageManager.resolve() → CLI 路径 → loadFinalExtensionSet() → 技能 / 提示 / 主题。reload(): resolveProjectTrust → settingsManager.reload() → packageManager.resolve() → CLI paths → loadFinalExtensionSet() → skills / prompts / themes.
3. buildSystemPromptSections() 组装 preamble、tools、rules、docs、addendum、project_context、skills、cwd 与扩展追加的分段。buildSystemPromptSections() assembles preamble, tools, rules, docs, addendum, project_context, skills, cwd and extension-added sections.