@earendil-works/pi-agent-core

基于 @earendil-works/pi-ai 构建的有状态智能体，支持工具执行和事件流。

安装

npm install @earendil-works/pi-agent-core

快速开始

本 SDK 提供对 Pi 智能体能力的程序化访问。可用于将 Pi 嵌入其他应用、构建自定义界面，或集成到自动化工作流中。

典型使用场景：

• 构建自定义界面（网页、桌面、移动端）
• 将智能体能力集成到现有应用
• 用智能体推理创建自动化流程
• 构建可生成子智能体的自定义工具
• 以编程方式测试智能体行为

参见 examples/sdk/，获取从极简到全量控制的可运行示例。

快速上手 import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent"; // 设置凭证存储与模型注册器 const authStorage = AuthStorage.create(); const modelRegistry = ModelRegistry.create(authStorage); const { session } = await createAgentSession({ sessionManager: SessionManager.inMemory(), authStorage, modelRegistry, }); // 订阅事件流 session.subscribe((event) => { if (event.

通过两种方式，在 TypeScript 中使用 @earendil-works 的 Pi Agent 框架连接本地运行的 Ollama 模型（以 qwen3.5:9b 为例）。

环境初始化

首先，初始化项目并配置为 ES Modules (ESM) 模式，以支持顶层 await 语法。

npm init -y

在生成的 package.json 中，手动添加 "type": "module"：

AI 的未来不在于将人类现有的经验硬塞给机器，而在于设计出能够利用无限算力进行搜索与学习的“元方法”。

• The Bitter Lesson
  • 里奇·萨顿（Rich Sutton）
  • 2019年3月13日

回顾70年人工智能研究历程，最深刻的一条教训是：依托算力的通用方法，最终效果远超其他路径，且优势极其显著。究其根本，源于摩尔定律——或者更广义地说，单位计算成本持续呈指数级下降。绝大多数人工智能研究开展时，都默认智能体可使用的算力是恒定的（这种情况下，借助人类知识就成了提升性能为数不多的手段之一）。但只要研究周期稍长于普通科研项目，海量算力必然会成为现实。

研究者为追求短期见效的性能提升，往往试图融入自身对领域的人类认知；但从长远来看，真正起决定性作用的，只有对算力的充分利用。这两条路径本不必相互对立，现实中却常常冲突：投入在一方的时间，就无法用于另一方。研究者会在心理上执着于某一种研究思路；而依赖人类知识的方法，往往会让模型变得复杂，反而难以适配依托算力的通用优化路径。

人工智能研究者们屡屡迟来地领悟到这一惨痛教训，回顾其中几个典型案例，颇具启发意义。

在国际象棋领域，1997年击败世界冠军卡斯帕罗夫的算法，依靠的是大规模深度搜索。彼时，多数国际象棋计算机研究者对此倍感沮丧——他们此前一直钻研的，是融入人类对国际象棋特有棋局结构理解的方法。

源码安装

克隆 Reachy Mini Conversation App

git clone https://github.com/wang-junjian/reachy_mini_conversation_app
cd reachy_mini_conversation_app

创建虚拟环境并安装依赖

uv venv --python 3.12
source .venv/bin/activate
uv sync

⚠️ 注意：要完全复现此仓库 uv.lock 文件中的依赖关系，请运行 uv sync --frozen 命令。这将确保 uv 直接从 lock 文件安装依赖项，而无需重新解析或更新任何版本。

安装可选功能

uv sync --extra local_vision         # Local PyTorch/Transformers vision
uv sync --extra yolo_vision          # YOLO face-detection backend for head tracking
uv sync --extra mediapipe_vision     # MediaPipe-based head-tracking
uv sync --extra all_vision           # All vision features

合并额外功能或包含开发依赖项：

项目总览

Kilo Code 是一个功能强大的开源 AI 编码助手，基于 OpenCode 框架开发。项目采用 Monorepo 架构，使用 Turborepo 和 Bun Workspaces 管理多个包。

核心数据

指标	数值
Monorepo 包数量	23
TypeScript 文件数	5800+
支持的 AI 模型	500+
内置工具数量	50+
UI 组件数（kilo-ui）	65+
国际化语言	19 种
开源协议	MIT

核心特性

• 多模型支持：支持 500+ AI 模型，包括 Claude、GPT、Gemini、Grok、Codex、GLM 等
• 多客户端：CLI、VS Code 扩展、Web UI 和桌面应用，满足不同场景
• 丰富的工具集：50+ 内置工具，涵盖文件操作、命令执行、代码搜索
• 插件扩展：支持外部插件和 MCP 服务器，动态加载自定义工具
• 会话管理：完整的会话系统，支持父子会话、上下文压缩、会话恢复
• 浏览器自动化：集成 Playwright，AI agent 可操作网页、截图、表单填充

Monorepo 依赖架构

Kilo Code 采用 Turborepo + Bun Workspaces 分层架构，23 个包协同工作。

架构分层

Pi 是一个模块化的 AI 编码智能体 Monorepo，使用 TypeScript 构建。它提供统一的 LLM 抽象层、通用的智能体运行时、丰富的终端 UI 框架，以及完全可扩展的编码智能体命令行工具。

1. 项目概览

Pi（@earendil-works/pi-mono）是由 Mario Zechner 开发的 AI 编码智能体 Monorepo，设计理念是模块化、可扩展、供应商无关。它将多个 LLM 供应商的复杂性抽象为统一 API，提供强大的智能体运行时和工具执行能力，并附带生产就绪的终端 UI。

核心能力

能力	说明
统一 LLM API	9 种 API 协议和 30+ 供应商品牌的单一接口。只需修改一个字符串即可切换供应商。
智能体运行时	完整的智能体循环，支持并行工具执行、消息注入队列和上下文压缩。
丰富的终端 UI	独立的终端 UI 框架，支持差异化渲染、文本编辑器、图片显示和浮层系统。
扩展系统	80+ 扩展示例、20+ 生命周期钩子。可注册工具、命令、快捷键和供应商。
Web 组件	基于 Lit 的聊天 UI，支持沙箱化 Artifact 渲染（HTML、SVG、PDF、DOCX 等）。
多运行模式	交互式终端、管道友好的打印模式，以及用于 IDE 集成的 JSONL RPC 模式。

包依赖关系图

graph TD
    subgraph "第一层：基础层"
        ai["<b>pi-ai</b><br/>统一 LLM API<br/>30+ 供应商"]
    end
    subgraph "第二层：运行时层"
        agent["<b>pi-agent-core</b><br/>智能体运行时<br/>工具执行"]
    end
    subgraph "第三层：UI 层"
        tui["<b>pi-tui</b><br/>终端 UI 框架<br/>零依赖"]
    end
    subgraph "第四层：应用层"
        coding["<b>pi-coding-agent</b><br/>编码智能体 CLI<br/>扩展与工具"]
        webui["<b>pi-web-ui</b><br/>Web UI 组件<br/>Lit + Tailwind"]
    end

    ai --> agent
    agent --> coding
    tui --> coding
    ai --> webui
    tui --> webui

    style ai fill:#1f6feb,stroke:#388bfd,color:#fff
    style agent fill:#238636,stroke:#3fb950,color:#fff
    style tui fill:#8957e5,stroke:#bc8cff,color:#fff
    style coding fill:#da3633,stroke:#f85149,color:#fff
    style webui fill:#e3b341,stroke:#d29922,color:#fff

图 1: Pi monorepo 包依赖关系图 — 4 层架构，5 个包

部署 Reachy Mini 语音智能体

安装 reachy_mini_conversation_app 到 Reachy Mini

在 MacBook 上运行 Reachy Mini Control，单击 Start 按钮。

在 Applications 页面，单击 Discover apps 后，搜索 reachy_mini_conversation_app。

单击 Install 按钮安装 reachy_mini_conversation_app。

MacBook 上实时模式运行 Speech To Speech

安装 Speech To Speech

uv venv --python 3.12
source .venv/bin/activate
uv pip install speech-to-speech
uv pip install "speech-to-speech[faster-whisper]"

中文

方法

架构

本仓库实现了一个语音到语音的级联管道，包含以下部分：

1. 语音活动检测（VAD）
2. 语音转文本（STT）
3. 语言模型（LM）
4. 文本转语音（TTS）

模块化

该管道提供了一种完全开放且模块化的方法，重点是利用 Hugging Face Hub 上 Transformers 库提供的模型。代码设计易于修改，我们已经支持特定设备和外部库的实现：

VAD

• Silero VAD v5

STT

• 通过 Transformers 🤗 在 Hugging Face Hub 上的任何 Whisper 模型检查点，包括 whisper-large-v3 和 distil-large-v3
• Lightning Whisper MLX
• MLX Audio Whisper - 在 Apple Silicon 上快速推理 Whisper
• Parakeet TDT - 在 Apple Silicon 上实现亚 100 毫秒延迟的实时流式 STT（通过 nano-parakeet 支持 CUDA/CPU，无需 NeMo）
• Paraformer - FunASR

LLM

• 通过 Transformers 🤗 在 Hugging Face Hub 上的任何指令遵循模型
• mlx-lm
• OpenAI API

TTS ChatTTS Pocket TTS - Kyutai Labs 提供的支持语音克隆的流式 TTS Kokoro-

Thariq: Using Claude Code: The Unreasonable Effectiveness of HTML

Markdown 已成为智能体（agent）与我们沟通时占主导地位的文件格式。它简单、可移植，具备一定的富文本能力，且易于编辑。Claude 甚至已经相当擅长在 Markdown 文件中使用 ASCII 绘制图表。

但随着智能体变得越来越强大，我感到 Markdown 已成为一种受限的格式。我发现自己很难阅读超过一百行的 Markdown 文件。我想要更丰富的可视化效果、色彩和图表，并且希望能轻松分享它们。

我也越来越不亲自编辑这些文件，而是将它们用作规格说明、参考文件、头脑风暴输出等。当我确实需要编辑时，我通常会让 Claude 来编辑，这就削弱了 Markdown 最大的一个优势。

我开始更偏爱 HTML 作为输出格式，而不是 Markdown，并且越来越多地看到 Claude Code 团队中的其他人也在使用它。以下就是原因。

（如果你想先看一些示例，可以在这里看到一大堆：https://thariqs.github.io/html-effectiveness ，不过记得回来看更多关于"为什么"的内容。）

为什么选择 HTML？

信息密度

与 Markdown 相比，HTML 能够传达更丰富得多的信息。

Notebook 0 — First Connection & Movement

🎯 目标：连接 Reachy Mini 并执行你的第一条运动指令。

架构概述

Reachy Mini 采用客户端-服务器架构：

graph LR
    subgraph Client
        A[Your Python Script]
    end
    
    subgraph Server
        B[Reachy Daemon]
    end
    
    subgraph Reachy Mini
        C[Robot Hardware or Simulation]
    end
    
    A <--> B
    B --> C

核心概念：

• 守护程序（Daemon）：一个后台服务程序，直接控制机器人的电机、传感器、摄像头和音频。
• Python SDK：你用来发送指令的 reachy_mini 软件包。

为什么采用这种架构？

• 多个客户端可以同时连接（如网页应用、脚本、Jupyter Notebook）。
• 守护程序负责安全地处理底层硬件操作。
• 你可以通过网络远程控制机器人。例如，在与机器人连接的树莓派（Raspberry Pi）上运行守护程序，同时在性能强大的服务器上运行你的 AI 代码。

验证连接

在运行代码之前，请先确认机器人已启动并正常运行。

你应该使用 Reachy Mini Control 来检查机器人是否已连接并准备就绪。Reachy Mini Control 是一款桌面应用程序，可让你管理机器人、运行应用、播放表情以及控制其音响系统。如果尚未下载，请从官方网站下载。

在 Reachy Mini Control 中连接成功后，请确保机器人处于“开启（ON）”状态。

在继续操作前，务必确认机器人已开启！尤其是使用无线版本时，在通电后，机器人代码默认处于关闭状态。

如需排查问题，请参考文档中的“连接与 Reac

• karpathy/llm-wiki.md

使用大语言模型（LLM）构建个人知识库的模式。

这是一份概念文件，设计用于复制粘贴到你自己的 LLM 智能体中（例如 OpenAI Codex、Claude Code、OpenCode / Pi 等）。它的目标是传达高层级的理念，而具体细节将由你的智能体与你协作构建。

核心理念

大多数人与 LLM 和文档打交道的体验看起来像是 RAG：你上传一批文件，LLM 在查询时检索相关片段，然后生成答案。这确实有效，但 LLM 每次都要从零开始重新发现知识，没有任何积累。当你问一个需要综合五份文档的微妙问题时，LLM 必须每次都找到并拼凑相关片段，没有任何东西被沉淀下来。NotebookLM、ChatGPT 文件上传以及大多数 RAG 系统都是这样工作的。

这里的理念不同。与其仅在查询时从原始文档中检索，LLM 增量式地构建并维护一个持久的维基 —— 一个结构化的、相互关联的 Markdown 文件集合，位于你和原始来源之间。当你添加新来源时，LLM 不只是将其索引以备后用。它会阅读来源，提取关键信息，并将其整合到现有维基中 —— 更新实体页面、修订主题摘要、标注新数据与旧主张的矛盾之处、强化或挑战不断演进的综合结论。知识被编译一次，然后保持最新，而不是每次查询都重新推导。

这就是关键区别：维基是一个持久的、复合增长的产物。

1. 开启仓库的 Discussions 功能

默认情况下，GitHub 仓库没有开启讨论（Discussions）功能。

• 进入 wang-junjian.github.io 仓库。
• 点击顶部的 Settings（设置）。
• 在 General 页面向下滚动，找到 Features 区域。
• 勾选 Discussions 选项。

2. 安装并授权 giscus app

为了让 Giscus 有权限向你的仓库写入评论，你需要：

• 访问 github.com/apps/giscus。
• 点击 Install，并选择将其安装到你的 wang-junjian.github.io 仓库上。

3. 配置分类 (Category)

在你的 Discussions 页面中，建议创建一个专门的类别（例如命名为 Announcements 或 Comments），并确保该类别的 Discussion format 设置为 Announcement，这样普通用户就不能直接在 GitHub 页面随意发起讨论，只能通过你的博客留言板生成。

4. 获取配置代码

访问 giscus.app，在“仓库”栏输入 wang-junjian/wang-junjian.github.io，它会自动检测并生成一段配置代码。

5. 博客中评论

Hermes vs. OpenClaw - When to Reach for Which Agent

发布时间：2026-05-07 作者：Brendan O'Leary

上周，有人在 Kilo Discord 里问："我该从 OpenClaw 切换到 Hermes 吗？" 自 Hermes 今年二月发布以来，这个问题我已经见过不下十几次。问得好 —— 两者都是开源的，都能连接你的聊天应用，都能运行工具、记住上下文。单看功能列表，它们几乎一模一样。

但过去两个月同时运行两者之后，我认为功能清单反而让人分心 —— 真正让它们分道扬镳的是设计哲学。

Hermes 是在一个学习型智能体外包裹了一个网关。

OpenClaw 是在一个消息网关内包裹了一个智能体。

这个区别听起来很抽象，但它对你配置和与每个工具交互的方式有着切实的影响。

Hermes：智能体优先

Hermes Agent 来自 Nous Research，于 2026 年 2 月发布。截至本文撰写时，GitHub 星标数约为 13.5 万。其 headline 功能是所谓的"学习循环" —— 智能体会基于自身行为创建并进化自己的技能。

根据其功能文档：

• 自我改进的技能：智能体从经验中生成程序性知识。同一类任务跑上一百次，Hermes 真的会越做越好。
• 五种沙箱后端：本地执行、Docker、SSH、Singularity 和 Modal。你可以自行选择命令执行的隔离程度。
• 子智能体委派：生成拥有独立上下文和终端的子智能体。并行工作流，互不污染上下文。
• 更广泛的浏览器/语音栈：Browserbase、Browser Use、Firecrawl、本地 Chrome，外加 Discord 频道原生语音支持。

KiloClaw 安全

安全架构、租户隔离与面向托管式AI智能体算力的数据保护

2026年2月 v1.0；Andrew Storms 独立安全评估

KiloClaw 是一个托管式计算平台，在每个专用虚拟机中运行每个用户的 AI 智能体实例。每位客户都会获得一个隔离的环境，其 AI 智能体可以在其中执行代码、访问文件系统、浏览网页以及连接到聊天频道（如 Telegram、Discord 和 Slack）。

对于代表客户执行任意代码的 AI 智能体托管式计算这类产品，其安全风险本身就很高。租户隔离的失误可能会将一个客户的秘密、对话和已连接账户暴露给另一个客户。机密管理的失误可能会危及客户托付给该平台的 API 密钥。

本白皮书介绍了 KiloClaw 的安全架构、保护客户数据的控制措施，以及 2026 年 2 月进行的独立安全评估的结果。它面向评估 KiloClaw 是否适合其组织的安全团队、合规官和技术决策者。

评估摘要

一项为期10天的独立安全评估通过威胁建模（采用 PASTA 框架，涵盖13项资产中的30个威胁）、代码审查、60多项对抗性测试以及实时基础设施测试，验证了 KiloClaw 的架构。总体结论是：KiloClaw 的安全架构是健全的，并在多个独立层实施了租户隔离。

KiloClaw 的工作原理

理解安全模型需要先理解其架构。

聊天软件集成 OpenClaw 的方式

聊天软件要集成 OpenClaw，主要有这几类方式（可以组合）： 用 OpenClaw 自带的“Channel 插件”直连（推荐，最省事） Telegram、WhatsApp、Discord、Slack、飞书/Lark、钉钉、Teams、Google Chat、Mattermost、Matrix、IRC、LINE、Signal、iMessage 等。 在 OpenClaw 的初始化或 openclaw channels add 里直接选通道、按向导配置即可。 本质上是：各 IM 的 Bot API / Webhook / Socket Mode / QR 扫码 对接到 OpenClaw 的 Gateway。初始化向导里可以看到支持的通道清单。 通用 HTTP 接口集成（适合任意聊天平台） OpenClaw 的 Gateway 提供了一个 HTTP 端点 /tools/invoke，可以调用单个工具（例如创建会话、发消息、拉取历史等），支持 Bearer 认证和 OpenAI 兼容的 /v1/* 风格接口。 你的聊天软件后端只要能发 HTTP POST，就可以用这个接口和 OpenClaw 交互。

研究编码智能体开源项目的最佳实践

基于 Kilo Code 的架构特征和当前编码智能体领域的生产实践 ，以下是系统研究此类项目的 方法论框架：

阶段 1：宏观定位（Why & Where）

研究维度	关键问题	Kilo Code 的启示
Fork 溯源	上游是谁？核心差异点？社区分裂原因？	Kilo 从 Roo Code 分叉，差异集中在 Cloud 集成和商业化功能
生态位	是「IDE 插件」「CLI 工具」还是「平台」？	Kilo 是「IDE 扩展 + CLI + Cloud」的三位一体
许可策略	是否存在 BSL/SSPL 等限制性条款？	MIT 许可证，无商业限制
模型绑定	是否硬编码单一提供商？	模型中立是核心卖点，避免供应商锁定

阶段 2：架构解构（How）

建议的代码阅读路径（以 Kilo 为例）：

1. 入口层 — src/extension/activate.ts（VS Code 生命周期）、src/extension/api.ts（IPC 外部 API）
2. 核心代理循环 — 查找 Cline/Roo/Kilo 主类，理解 Plan → Act → Verify 的循环
3. 工具调用层 — McpHub 如何集成外部工具（文件系统、终端、浏览器）
4. 上下文管理层 — Memory Bank、Context Mentions、自动索引的实现
5. 模式系统 — Custom Modes 的解析与切换逻辑
6. 差异标记 — 搜索 // kilocode_change 快速定位增量代码

Reachy Mini

2025年12月买的 Reachy Mini 机器人，近5个月终于到手了。

购买链接

介绍

Reachy Mini 是由法国机器人公司 Pollen Robotics 开发的一款开源的桌面级人形机器人，旨在为教育、研究和创意项目提供一个灵活且易于使用的平台。Reachy Mini 是 Reachy 机器人的小型版本，具有相似的功能和设计，但体积更小，更适合在桌面环境中使用。

硬件版本

功能特性	Wireless (无线版)	Lite (轻量版)
价格	$449$	449∣299
电机与机械结构	9 个伺服电机	9 个伺服电机
头部运动	6 自由度 (pitch, roll, yaw, x, y, z)	6 自由度 (pitch, roll, yaw, x, y, z)
身体旋转	±160°	±160°
天线	2 个动力感应天线	2 个动力感应天线
摄像头	广角摄像头	广角摄像头
麦克风	4 麦克风阵列	4 麦克风阵列
扬声器	5W 扬声器	5W 扬声器
板载算力	树莓派 CM 4 (16GB 存储)	-
加速计	内置 IMU	-
Wi-Fi 连接	支持	-
独立模式	支持	需通过 USB 连接控制
供电方式	电池供电 + 电源适配器 (7.3V / 5A)	仅限电源适配器 (7.3V / 5A)

开箱与初体验 Welcome to Reachy Mini!

macOS 图像转为 WebP 格式工具使用说明

本工具是一个专为 macOS 设计的自动化脚本，它能帮助您将选择的图片转换为 WebP 格式。

该工具设计为通过 macOS 的“快速操作”或 Automator 工作流程来调用，从而实现便捷的图像转换操作。

• 作为“快速操作”使用：
  • 设置“快速操作”： 您需要将提供的脚本保存为 Automator 工作流程的“快速操作”。
    • 打开 Automator 应用（在“应用程序” -> “实用工具”中）。
    • 选择 “文件”>“新建”。
    • 选择 “快速操作” 并点击“选取”。
    • 在左侧的库中，搜索并拖动 “运行 Shell 脚本” 到右侧的工作流程区域。
    • 在“运行 Shell 脚本”模块中，将“传递输入”设置为 “作为自变量”。
    • 将本工具的完整代码粘贴到“运行 Shell 脚本”的文本框中。
    • 选择 “文件”>“存储”，为您的快速操作命名，例如“图像转换为 WebP”。
  • 使用方法：
    • 打开 Finder，导航到您要转换的图片所在的文件夹。
    • 选中您希望转换的所有图片（请确保至少选择一张）。
    • 右键点击选中的图片，或者点击 Finder 窗口顶部的“服务”菜单。
    • 在上下文菜单中，找到并点击您刚才创建的“快速操作”名称，例如 “图像转换为 WebP”。
    • 一个对话框会弹出，询问您希望转换为哪种格式。选择您的偏好。
    • 工具将自动处理图片，并将转换后的新图片保存在您选中的图片所在的相同文件夹中。