落日画斜阳

07 — 分布式与可观测性 (chord, server, client, telemetry)问题当 Agent 需要以 client-server 模式运行（例如远程会话、多 worker 并行）时，需要： 一个服务组合运行时来管理多个服务及其依赖 一个 client-server 协议实现来传输消息 一个可观测性系统来追踪跨进程的请求 Pi 将这些放在 chord、server、client、telemetry 四个包中。这些目前是实验性的（受 PI_EXPERIMENTAL=1 环境变量控制），但设计成熟。 第一部分：chord — 应用组合运行时packages/chord/src/ 核心概念 概念 说明 Facet 一个模块，声明它提供和消费的服务 Service 类型化的服务契约（singleton 或 keyed 模式） ReplicatedState 可变复制状态，跨进程同步 FacetHost 管理一组 facet 的激活、热重载 Facet 模型packages/chord/src/facets/host.ts（~32K） 一个...

06 — 终端 UI (pi-tui)问题在终端中渲染一个交互式 Agent 界面面临几个挑战： 终端是顺序输出的设备，如何实现”局部更新”（只刷新变化的部分）？ 如何处理复杂的键盘输入（组合键、修饰键、按键释放）？ 如何渲染 Markdown、代码高亮、diff、图片？ 如何让 UI 组件可组合且高效？ pi-tui 是一个独立的终端 UI 库，解决了这些问题。 渲染架构差分渲染pi-tui 的核心渲染策略是差分渲染（differential rendering）： 12345678910Frame N (当前屏幕) Frame N+1 (新屏幕)┌──────────────┐ ┌──────────────┐│ Hello World │ │ Hello Pi ││ > _ │ │ > typing_ │└──────────────┘ └──────────────┘ │ ...

04 — 会话持久化 (pi-protocol 与 session-backends)问题Agent 的对话状态（消息、工具结果、用量统计）需要持久化，以支持： 进程重启后恢复对话 创建会话分支（fork） 导航到历史中的某一点 同时，Agent 可能以 client-server 模式运行，需要一个传输中立的协议来在进程间通信。 Pi 将这两个关注点分别放在 pi-protocol（协议层）和 pi-session-backends（存储层）。 第一部分：pi-protocol — 传输中立协议packages/protocol/src/ 协议概述一个二进制 RPC 协议，用于远程 pi 会话。客户端发送 hello + 请求/取消；服务端回复 hello + 响应 + 服务更新 + 附件通知。 协议版本：PROTOCOL_VERSION = 8（protocol.ts:5） 消息类型packages/protocol/src/protocol.ts 客户端消息（ClientMessage，line 63）： 消息 说明 ClientHello { t...

05 — 编码 Agent (pi-coding-agent)问题pi-agent-core 提供了 Agent 运行时，但它不知道什么是”文件”、什么是”bash 命令”、什么是”系统提示”。它只是一个通用的 agent loop。 pi-coding-agent 的任务是：在 agent-core 之上组装一个可用的编码助手产品——定义具体工具、构建系统提示、管理会话、支持扩展、提供终端 UI。 启动流程packages/coding-agent/src/main.ts（~982 行） 1234567891011121314151617181920212223用户执行 `pi "帮我读一下 README"` │ ▼cli.ts (7行) └─ setupCli() → main(process.argv.slice(2)) │ ▼main.ts ├─ parseArgs() // 解析 CLI 参数 (args.ts) ├─ 运行一次性迁移 /...

03 — Agent 运行时核心 (pi-agent-core) 这是最核心的文档。理解了这一篇，你就理解了 Agent 的本质。 问题一个 Agent 需要持续地与 LLM 交互：发送上下文 → 接收响应 → 执行工具 → 将工具结果加入上下文 → 再次发送。这个循环何时继续、何时停止？工具调用如何执行？如果 LLM 返回错误怎么办？如果用户想在 Agent 工作时插入新指令怎么办？ pi-agent-core 提供了两套实现来回答这些问题： 经典 Agent（agent.ts + agent-loop.ts）— 简单的 while 循环，适合理解概念 AgentHarness（harness/ 目录）— 生产级状态机，支持崩溃恢复、多 lane、compaction 第一层：经典 AgentAgent 类packages/agent/src/agent.ts Agent 类持有 AgentState： 1234567891011interface AgentState { systemPrompt: string; model: Model<any&...

02 — LLM 抽象层 (pi-ai)问题OpenAI、Anthropic、Google 等 LLM 供应商的 API 各不相同：消息格式不同、流式事件不同、工具调用格式不同、认证方式不同。如果 Agent 代码直接调用某个 provider 的 SDK，切换 provider 需要大面积改码。 pi-ai 的任务是提供一个统一抽象层，让上层 Agent 代码只面对一套接口，无需关心底层是哪个 provider。 核心类型Api 与 Providerpackages/ai/src/types.ts:17-29 定义了已知的 API 类型： 123456789101112export type KnownApi = | "openai-completions" | "openai-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "g...

01 — 整体架构与包依赖问题一个生产级 Agent 系统涉及 LLM 调用、工具执行、状态管理、会话持久化、终端渲染、多进程协作等多个关注点。如果把它们全部塞进一个包，代码会迅速变成无法维护的巨型模块。 Pi 的解法是 严格分层：每一层只依赖下一层，职责边界清晰。 11 个包的职责 包名 npm 包 职责 层级 telemetry pi-telemetry 厂商中立的遥测契约（span、属性、schema 类型推断） 基础设施 ai pi-ai 多 provider LLM 统一接口、模型管理、认证 LLM 层 agent pi-agent-core Agent 运行时：主循环、工具调用、状态机、compaction 运行时层 protocol pi-protocol 传输中立的二进制 RPC 协议（CBOR + 长度前缀帧） 通信层 session-backends pi-session-backend-sqlite-node SQLite 会话持久化实现 存储层 coding-agent pi-coding-agent 交互式编码 Agent ...

Pi Agent Harness 项目解构 — 导读与学习路线项目定位Pi（v0.85.1）是 earendil-works 开发的 Agent harness（Agent 运行时框架）。它不是一个简单的 LLM 封装库，而是一套从 LLM provider 抽象、Agent 运行时、会话持久化、到交互式终端 UI 的完整工程实现。 学习这个项目的价值在于：你可以看到一个 生产级 Agent 如何解决以下工程问题—— 如何统一 10+ 个 LLM provider（OpenAI、Anthropic、Google 等）的接口差异 如何实现一个可恢复、可中断的 Agent 主循环 如何在工具调用过程中保证状态一致性（即使进程崩溃也能恢复） 如何在上下文窗口接近满时自动压缩对话 如何设计一个可扩展的工具系统和插件系统 如何实现终端差分渲染 前置知识 领域 要求 说明 TypeScript 中级 需理解泛型、类型推断、TypeBox schema LLM API 基础 了解 chat completion、streaming、tool calling 概念 Node...

一、Talon 是什么？Talon 是一个用 Rust 编写的本地优先混合检索与 MCP（模型上下文协议）服务器。它专门为 Obsidian 知识库设计，能够索引你的笔记库，并通过混合搜索（BM25 + 语义向量 + 重排序）以及知识图谱（基于双向链接）提供智能检索服务。 核心能力： 混合检索：结合关键词匹配（BM25）和语义向量检索，再通过重排序模型优化结果 知识图谱排名：利用 Obsidian 的双向链接、反向链接、标签等作为排名信号 MCP 服务器：提供 talon_search、talon_read、talon_related 三个工具，供任何支持 MCP 的 AI Agent（Claude Desktop、Cursor、Codex 等）调用 Recall Hook：可在每次 Agent 对话时自动检索相关笔记并注入上下文 二、前置准备2.1 安装 Node.js（Windows 11）Talon 可以通过 npm 安装，因此需要 Node.js。 访问 Node.js 官网 下载 LTS 版本（推荐 22.0.0 或更高） 运行安装程序，按默认选项完成安装 安装...