Deepseek on OHTLY Blog

为 Pi Coding Agent 编写自定义工具

Tue, 14 Jul 2026 10:30:00 +0800

背景链接到标题

Pi Coding Agent 的扩展机制允许向 AgentSession 注册自定义 Tool，LLM 在对话中可以直接调用这些工具。扩展是 ESM 模块，通过 pi.registerTool() 注册，自动加载到当前 Session。

注册 Tool 链接到标题

Extension 文件导出一个默认函数，接收 pi: ExtensionAPI 作为参数：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerTool({ /* ... */ });
}

pi.registerTool() 接收一个对象，关键字段如下：

字段	类型	说明
`name`	`string`	工具唯一标识，LLM 据此调用
`label`	`string`	显示名称，UI 中展示
`description`	`string`	工具描述，LLM 据此判断何时调用
`promptSnippet`	`string`	简短提示，注入系统提示词
`promptGuidelines`	`string[]`	调用 guideline，LLM 参考
`parameters`	`TypeBox Schema`	参数 Schema，LLM 据此生成参数
`execute`	`function`	工具执行函数

TypeBox Schema 链接到标题

parameters 用 TypeBox 定义：

Pi Web 配置 DeepSeek 与自定义工具

Mon, 13 Jul 2026 09:44:05 +0800

背景链接到标题

Pi Coding Agent 是一个开源的 AI 编程助手，69K+ Stars，MIT 协议。它的架构分三层：

@earendil-works/pi-ai — 统一多 Provider LLM API
@earendil-works/pi-agent-core — Agent 运行时（Tool calling、状态管理）
@earendil-works/pi-coding-agent — CLI + SDK

Pi Web 是社区开发的 Web UI，1.1K Stars。它通过 Pi SDK 直接创建 AgentSession，通过 SSE 推送流式事件到浏览器，不跑 CLI 子进程。

同类项目还有 jmfederico/pi-web（支持远程 Machine/Fleet）和 pi-gui（Electron 桌面版）。

部署链接到标题

环境要求：Node.js 22+。

git clone https://github.com/agegr/pi-web.git
cd pi-web
npm install
npm run dev

默认运行在 http://localhost:30141。

配置 DeepSeek 模型链接到标题

Pi Coding Agent 内置了 DeepSeek Provider，模型定义在 deepseek.models.ts，包含 deepseek-v4-flash 和 deepseek-v4-pro。

四种 PageIndex 检索方案的 Token 消耗对比

Thu, 09 Jul 2026 15:21:34 +0800

背景链接到标题

PageIndex 是一个无向量（vectorless）、基于推理（reasoning-based）的 RAG 框架。核心思路是将文档解析为树状索引，让 LLM 通过推理来导航定位内容，而不是靠向量相似度搜索。

这次实验的数据源是一本人教版《物理必修第二册》扫描版 PDF。因为纯扫描件没有文字层，先用 MinerU（vlm-engine）OCR 提取了结构化文本，再插入  标记以使页码可追溯。最后用 PageIndex 对这份带页码的 markdown 建立树索引。

基于同一份数据，实现了四种检索方案，对比它们的实现差异和 Token 消耗。

四种方案的设计差异链接到标题

方案 A：简单查询链接到标题

两步走，两次独立 LLM 调用：

LLM #1 看树结构 → 返回行号范围
LLM #2 取内容 → 回答

没有验证步骤，LLM 一次定生死。

方案 B：手写 Agent 循环链接到标题

三步走，三次独立 LLM 调用：

LLM #1 identify_ranges → 返回候选行号列表
LLM #2 evaluate → 判断内容是否包含答案
LLM #3 final_answer → 基于内容给出最终回答

写了 for 循环遍历候选清单，显式 evaluate 确认命中后才回答。

DeepSeek V4 DSML 标记导致 Codex 任务中止

Fri, 26 Jun 2026 11:24:38 +0800

问题现象链接到标题

Codex 通过 Moon Bridge 使用 DeepSeek V4 Flash 时，任务执行中途突然终止。终端输出类似：

<｜｜DSML｜｜tool_calls> <｜｜DSML｜｜invoke name="exec_command"> <｜｜DSML｜｜parameter name="cmd" string="true">

然后任务就卡住不动了。

问题分析链接到标题

Moon Bridge 架构链接到标题

Moon Bridge 是一个 Go 编写的协议转换与模型路由代理，对外暴露 OpenAI Responses API（/v1/responses），对内支持 Anthropic Messages、Google Gemini、OpenAI Chat Completions 等多种上游协议。

当 Codex 发起请求时，Moon Bridge 负责把 OpenAI Responses 格式的请求转换为上游 Provider 需要的格式。

根因：DeepSeek V4 DSML 链接到标题

DeepSeek V4 在工具调用场景下，会将 DSML（DeepSeek Markup Language）标记直接输出到 content 字段，而不是作为结构化的 tool_calls 返回。这违反了 OpenAI API 契约——工具调用应该只在 tool_calls 字段中传递。

Codex CLI 用 DeepSeek 的协议转换方案

Wed, 24 Jun 2026 14:35:40 +0800

Codex CLI 是 OpenAI 出品的终端编码 agent。2026 年 2 月起，Codex 只支持 OpenAI Responses API（/v1/responses），不再兼容 Chat Completions（/v1/chat/completions）。DeepSeek 官方 API 只提供 Chat Completions 接口，两者协议不互通。

需要一个协议转换层。

方案对比链接到标题

方案	原理	评价
Chutes	云端 Responses→Chat 翻译	依赖第三方云服务
LiteLLM	全能 AI 网关	功能太多，对 Codex 场景大材小用
open-codex fork	用 Chat API 重写	已停更
Moon Bridge	本地 Go 代理，协议转换 + 路由	DeepSeek 官方推荐，轻量专注

Moon Bridge 是 Go 写的协议转换代理，对外暴露 POST /v1/responses，对内将请求转为 Anthropic Messages API 格式发给 DeepSeek（DeepSeek 兼容 Anthropic 协议）。支持多 Provider 路由、请求跟踪、Web Console 管理。

排查 OpenClaw memory_search 工具被禁用的问题

Mon, 15 Jun 2026 18:32:05 +0800

背景链接到标题

OpenClaw 部署在 server-a 上的实例（版本 2026.6.5），用户反馈 “Memory search 暂时不可用”。另一个实例 server-b 上相同配置却工作正常。

排查目标：找到差异，修复问题。

排查过程链接到标题

阶段 1：对比配置差异链接到标题

先对比两边的 memorySearch 配置：

实例	provider	状态
server-b（正常）	`ollama-ollama-host`	✅
server-a（异常）	`ollama` + `remote.baseUrl`	❌

配置都指向同一台 Ollama 服务器，模型都是 bge-m3。尝试了三种修改：

将 provider 改为 ollama-ollama-host → 插件不加载（该实例无本地 Ollama）
将 provider 改为 openai-compatible → 插件同样不加载
恢复原配置 → 插件正常加载

结论：provider 名不是根本原因，ollama 插件本身加载正常。

阶段 2：分析日志链接到标题

日志中发现了关键线索：

openclaw 6.6 修复 DeepSeek 定时 Wiki 编译问题

Sun, 14 Jun 2026 13:29:16 +0800

背景链接到标题

我在一台个人服务器上运行 OpenClaw，并使用 Memory Wiki 功能把本地知识库编译成可检索的结构化内容。这个编译动作原本由一个每天定时执行的 cron job 完成，任务内容很简单：触发 /wiki-compile。

这类任务长期运行正常。后来默认模型切换到 DeepSeek 后，定时任务开始失败，表面错误是：

LLM request failed.

一开始这个错误很容易被误判成 DeepSeek 接口不稳定。但后续排查发现，问题并不是 DeepSeek 全局不可用，也不是 Wiki 编译工具本身坏了，而是 OpenClaw 旧版本中 cron isolated agent 运行路径的 timeout 传递问题。

OpenCode 换用 DeepSeek V4 后的代理与搜索配置

Tue, 09 Jun 2026 21:14:32 +0800

最近把 OpenCode 的主力模型从 MiniMax 换成了 DeepSeek V4，顺便整理了下 webfetch 代理和 websearch 工具的配置。

Deepseek on OHTLY Blog

为 Pi Coding Agent 编写自定义工具

背景 链接到标题

注册 Tool 链接到标题

TypeBox Schema 链接到标题

Pi Web 配置 DeepSeek 与自定义工具

背景 链接到标题

部署 链接到标题

配置 DeepSeek 模型 链接到标题

四种 PageIndex 检索方案的 Token 消耗对比

背景 链接到标题

四种方案的设计差异 链接到标题

方案 A：简单查询 链接到标题

方案 B：手写 Agent 循环 链接到标题

DeepSeek V4 DSML 标记导致 Codex 任务中止

问题现象 链接到标题

问题分析 链接到标题

Moon Bridge 架构 链接到标题

根因：DeepSeek V4 DSML 链接到标题

Codex CLI 用 DeepSeek 的协议转换方案

方案对比 链接到标题

排查 OpenClaw memory_search 工具被禁用的问题

背景 链接到标题

排查过程 链接到标题

阶段 1：对比配置差异 链接到标题

阶段 2：分析日志 链接到标题

openclaw 6.6 修复 DeepSeek 定时 Wiki 编译问题

背景 链接到标题

OpenCode 换用 DeepSeek V4 后的代理与搜索配置

背景链接到标题

背景链接到标题

部署链接到标题

配置 DeepSeek 模型链接到标题

背景链接到标题

四种方案的设计差异链接到标题

方案 A：简单查询链接到标题

方案 B：手写 Agent 循环链接到标题

问题现象链接到标题

问题分析链接到标题

Moon Bridge 架构链接到标题

方案对比链接到标题

背景链接到标题

排查过程链接到标题

阶段 1：对比配置差异链接到标题

阶段 2：分析日志链接到标题

背景链接到标题