# ceulen 中文文档

规范地址：https://npmcn.com/package/ceulen/

版本：0\.26\.0
npm 元数据更新时间：2026-11-03T07:06:30.132Z
中文译文更新时间：2026-11-03T07:37:39.910Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/ceulen
原文对照：https://npmcn.com/package/ceulen/?lang=original
项目主页：https://github.com/ceulen-dev/ceulen#readme
源码仓库：https://github.com/ceulen-dev/ceulen

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.9 MB，571 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：4 个
- peer 依赖：typebox \*，@earendil-works/pi-tui \>=0\.99\.1 \<1\.6\.0，@earendil-works/pi-coding-agent \>=0\.99\.1 \<1\.6\.0
- 首次发布：2026-09-28T14:51:40.790Z
- 最新版本发布：2026-11-03T07:06:29.915Z
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Ceulen - Pi编码代理，完全打扮：一个包扩展携带完整的工具包与一个/ Ceulen配置命令。

## 安装

```sh
npm install ceulen
```

也可以使用：`pnpm add ceulen`、`yarn add ceulen`、`bun add ceulen`

## README

# Ceulen

**Pi编码特工，全副武装。**

一个扩展包 [π](https://github.com/earendil-works/pi) 变成一个装备齐全的编码代理：路由器提供者、第二模型审查器、长期记忆、具有多会话repo安全性的子代理委托、使用显示、主题和中央设置面板——一个安装、一个命令界面，大多数模块都可以单独切换。

以将π计算为35位数字的鲁道夫·范·克伦的名字命名，他们被刻在了他的墓碑上。

## 安装

```sh
pi install npm:ceulen
```

添加 `-l` 安装到当前项目而不是您的用户范围。更新与 `pi update --extensions`． 然后在项目中启动Pi -模块自动加载。

## 快速启动

```sh
/config                  # one panel for pi core + every ceulen module
/ceulen                  # which modules are active
```

大多数模块都是开箱即用的。两个需要证件；一个是可选配置的：

-   **路由器** ——设置 `router.baseUrl` (通过 `/config` →供应商，或 `ROUTER_BASE_URL` env),然后 `/login router`.
-   **munin** -设置项目+ API密钥via `/config` →内存(保存到 `<repo>/.pi/settings.json`）。
-   **网络** -可选：设置搜索/提取后端通过 `/config` →工具→网络（SearXNG/Brave/Firecrawl/Crawl4AI）。仅配置一个后端即可工作； `web_status` 报告什么是准备好的。

## 模块

### 路由器-任何与openai兼容的路由器作为Pi提供商

使用9router、OmniRoute、yardmaster或任何openai兼容的端点作为普通的Pi提供商：模型出现在 `/model`，聊天通过 `/v1/chat/completions`.

-   配置: `/config` 提供者（基本URL +思维层次；保存重新注册和刷新）
-   身份验证: `/login router` 或者 `ROUTER_API_KEY` env
-   命令: `/router-status`， `/router-model`

如果路由器服务于系统一决策模型（码长） `GET /v1/systemone/models`)，它们被列为分类器模型 `classify` 工具-永远不要混进聊天选择器。

### 分类器——用于输入答案的决策模型（Jev）

这个 `classify` 工具询问System One决策模型类型的问题（是-概率，有信心的多项选择，得分位置），并得到校准的答案，而不是散文-对于在脚本和代码模型中路由，验证和控制决策非常有用。

它还审计bash命令(可逆的？服务于任务？ `~/.pi/agent/classifier.log`． 这是 **只观察** -它从不阻止或批准任何事情。

-   配置: `/config` →模型→分类器（Jev）
-   需要配置路由器模块

### 顾问，你的第二只眼睛

在实际工作的每个回合之后，一个单独的审稿人模型读取成绩单并可能提出 **一个** 注意: `nit` (考虑), `concern` （地址或证明）， `blocker` （先修复）——或者保持沉默。重删/限速保护使其保持安静；审稿人从不使用你的主要模型。

-   工具: `advisor` -根据需要咨询审稿人
-   配置: `/config` →模型→顾问（审查模型，回退链，手表旋钮-适用于现场）
-   命令: `/advisor [model[, model…]|models|on|off|status]`
-   关闭它：清除Primary模型行

### 用法-页脚中的订阅用法

包含提供商使用情况的状态页脚：5小时/每周/每月窗口、积分和生成率指示器。 `/usage` 的细节, `/context` 用于上下文窗口分解。支持openai-codex， opencode-go, z.ai， Command Code和router/yardmaster（需要具有使用权限的密钥）。

### Composer——一个合适的输入编辑器

选择输入编辑器的外观 `/config` →外观→作曲家形状：状态带（默认），圆形框，克劳德代码，Pi，无边界，和更多-与实时预览，而你浏览。显示状态的形状显示模型、目录、git分支+工作树状态、生成速率和上下文使用情况。总是在。

### 长期记忆

`munin_search` / `munin_get` / `munin_store` / `munin_list` / `munin_recent` / `munin_share` / `munin_delete` / `munin_capabilities`，再加上一个内存协议，该协议教导代理何时进行搜索以及哪些内容值得存储。 `/munin-status` 显示每个配置字段的来源（而不是键本身）。

-   配置: `/config` →记忆→ **项目级** （`<repo>/.pi/settings.json`;添加到 `.gitignore`）. 仅在项目受信任时读取； `MUNIN_*` 嫉妒者凌驾于此。

### Ponytail - lazy-senior-dev模式

`/ponytail off|lite|full|ultra` 切换一个过度工程的原则：最简单的解决方案，stdlib优先，没有推测性的抽象。还船 `/ponytail-review`， `/ponytail-audit`， `/ponytail-debt`， `/ponytail-gain` 技能。禁用与 `stop ponytail`.

### 子代理-委托工作，安全

一个 `subagent` 工具爱好者工作到专门代理- `scout` (侦察), `tester`， `worker`， `planner`， `reviewer` -在三种模式：单一，并行（最多8个任务），或链式管道。后台任务报告活跃度(`operation:"status"/"wait"/"cancel"`）; 当Pi在herdr中运行时，任务可以委托给可见的交互式窗格。模型层和思维努力由分类器模块路由到每个任务； `/subagent` 管理的角色, `/agent` 检查线程。

多会话的安全（孤立的孩子永远不会殴打你或彼此）：

-   **Worktree沙箱** - - - - - - `sandbox:"worktree"` 在你的工作树的一个写时复制的克隆中运行子进程 `clonefile` -接近零的时间和磁盘；携带您未提交的更改， `node_modules`, `.env` （免费），返回到其他地方的分离git工作树。孩子的变化会像补丁一样回来； `merge:"3way"` 将其应用于有冲突的结帐 **报告过的，从来没有默默地解决过**.
-   **基线携带** 在工作树回退中，父级的未提交状态被组成为纯读(`git diff`/`--no-index`)，然后播种到沙箱中，这样孩子们就不会去做一棵陈旧的树，补丁也会干净地合并。
-   **`.worktreeinclude`** - gitignore风格的文件列表复制到新的工作树（env文件，configs）。
-   **回购锁+ GC** -每个repo序列化父变量git操作 `index.lock` 平行子节点之间的赛跑)；在会话开始时扫描崩溃运行的沙盒。 `/subagent worktrees [clean]` 列出或强制清除。
-   **写新鲜保护** （修理模块）- a `write` 对于自上次读取以来另一个会话更改的文件，它会出现重读优先错误而不是失败。
-   **冲突的页脚** （修复模块）-完整文件读取表面未解决 `<<<<<<<` 自动冲突标记。

配置: `/config` →任务→子代理（模型池、路由、超时）。

### 修理-工具召唤硬化

将内置的读/写/编辑/grep/find/ls/bash分别包装一次：模式参数修复，编辑不匹配的容错重试 `apply_patch` 升级，破坏性-bash +猜测路径保护，以及读取路径后缀- `file.ts:50`， `:50-200`， `:50+150`， `:-60` （尾），逗号连接的范围， `:raw`, `:conflicts` （列出合并冲突块）。寄存器 `apply_patch` （法典风格的V4D差异）和 `str_replace_editor` 作为独立的工具。配置: `/config` →工具→维修。

### 转向-模型-家庭指导

与提供者无关的deepseek/glm家族检测，包括第一工具提示、推理剥离、错误分类+恢复提示，以及用于deepseek最小模式的ds-anchor两阶段引导。 `/steering` 显示状态。

### zai - Z.AI提供商（GLM）

注册一个 `zai-anthropic` 通过Z.ai的Anthropic端点服务GLM的提供商：显式提示缓存； `speed:"fast"` 服务层，基于努力的推理，跨进程速率限制节流，以及可选的ZCode请求签名。 `/zai` =状态;配置在 `/config` →提供者。

### 用户界面—防止用户界面混乱

`/ux off|lite|strict` 为任何UI工作注入UI设计方法（游戏邦注：只有令牌，完整的交互状态，没有ai溢出）； `strict` 块切换直到确定 `ux_audit` 工具通过（APCA对比、令牌和状态门—不需要模型）。船的 `ux-*` 技能。禁用与 `stop ux`.

### Plan—只读规划模式

`/plan` (或 `--plan`， `ctrl+alt+p`)切换为只读规划模式：研究工具和只读bash运行不受影响，文件mutators硬块，未知命令优先询问。代理通过生成一个可审查的计划 `write_plan` 并且可以解决歧义 `ask_user_question`； `/plan-approve current|new` 在此会话或新的会话中执行它。计划落地 `.pi/plans/` 默认情况下- **拯救计划** 在 `/config` →任务→计划模式决定哪个命中磁盘(`all` 草稿, `approved` 只有最后敲定的， `none` conversation-only)。只计划模型/思考和 `/plan-auto` 自主审批也是配置行。

### Web统一的Web工具

`web_search` （自适应搜索→勇敢→火龙）， `web_extract`， `web_map`， `web_crawl`， `web_screenshot`， `web_pdf`， `web_interact` （真正的无头chrome点击/键入/评估验证UI行为）， `web_research` （双子座网+深度研究）， `web_image`， `web_chat`， `web_status`． 只有当web工具处于活动状态时才会注入后端路由指导。

-   配置: `/config` →工具→ **网络** - 16行提供程序（端点、密钥、超时、Gemini cookie、图像/聊天提供程序）。写给全球的 `web` 设置部分和读取每个工具调用，所以保存应用没有 `/reload`； `BRAVE_API_KEY`， `SEARXNG_BASE_URL`， `FIRECRAWL_*`， `CRAWL4AI_*`， `GEMINI_WEB_*`， `ZAI_API_KEY`， `WEB_IMAGE_*`， `WEB_CHAT_*` 嫉妒者仍然是赢家。秘密是被掩盖的。冷工具负载需求通过 `tool_search`.
-   静态提取使用厂商提供的可读性/关闭（无需额外安装）； `jsdom` 和 `gemini-reverse` 是模块仅有的运行时依赖项。

### a2a - Agent2Agent协议

与远程代理（Hermes， ADK, LangChain, CrewAI，任何A2A对等体）交谈：7个出站工具(`a2a_call` 使用异步调度， `a2a_status`， `a2a_discover`， `a2a_list`， `a2a_history`， `a2a_orchestrate` 扇出, `a2a_peers`)和一个可选择的入站服务器，用于服务隔离的子会话。发现跨越本地注册中心、mDNS和a2a交换机网关。 `/a2a-help` 对一切;配置在 `/config` →任务→A2A。

### 待办事项分阶段任务板

一个 `todo` 工具跟踪一个有序的阶段列表 `blockedBy` 边缘，自动启动和实时TUI HUD； `/todo` 打印电路板。遵循批处理合同（将其与实际工作一起调用，而不是单独调用）。

### 规则-粘性规则+规则手册

`<dir>/.pi/RULES.md` 文件（走到repo根目录，加上一个用户级文件）将粘性规则注入每个请求； `## name` 带a的部分 `description:` Line变成了一个按需服务的规则手册 `rule_get` 工具。无需编辑即可应用 `/reload`； `/rules` =状态。

### gh - GitHub（只读）

一个 `github` 工具 `gh` CLI: `repo_view`， `file_read`， `pr_view`， `pr_diff`， issue/PR/code/commit/repo搜索与日期限定符，和 `run_watch` for Actions运行时带有失败的作业日志尾部。零npm深度；无法打开 `gh` 不在。变化的流留在bash中 `gh` -使工具在计划模式下保持自动允许。

### 附件-将文件粘贴到提示符中

将文件路径（或大文本）粘贴到 `[[attach:name]]` 带有托盘小部件的令牌；在提交时，它们成为真实的图像部件、路径芯片或内联文件块。 `alt+shift+v` 粘贴剪贴板文件引用。配置: `/config` →文件→附件。

### 定时作业

这个 `cron` 工具+ `/cron` 中管理循环提示 `<agentDir>/cron/jobs.json` （vi -cron时间表，手卷匹配器-零深度）。随着后续事件的发生，乔布斯开始开火；固定的作业在它们自己的Pi进程中无头运行。 `/cron test` 预览五次；配置在 `/config` →任务→Cron

### Permission -配置驱动的工具权限

可选 `permission` 设置部分：使用通配符允许/请求/拒绝每个工具的规则 `external_directory` 拒绝边界，并对重复的相同呼叫设置了一个末日循环保护。没有章节=没有观点。无头问失败关； `--yolo`/`--auto` auto-approve。

### Serena / FFF / RTK -代码导航和搜索（捆绑工具）

-   **瑟瑞娜** -语义代码工具（查找符号，引用，重命名，诊断）通过一个持久的语言服务器工作器
-   **fff** -快速模糊文件/内容搜索(`ffgrep`， `fffind`)提供内置的grep/find经验和 `@`提到完成
-   **rtk** -通过RTK重写shell命令，只在RTK支持的地方（git, ls, rg, test runner）；链、重定向和内联脚本通过字节相同的(`/rtk status`， `/config` →Shell→RTK； `RTK_DISABLED=1` 绕过)

### 配置-设置面板

`/config` 打开一个全屏面板覆盖 **PI核心设置和每个ceulen模块**，以标签形式组织（外观·模型·交互·内存·上下文·Shell·任务·提供程序·插件）。

-   主题和作曲家的变化预览现场，而你浏览；PI内置工具切换立即应用
-   模块开/关开关和pi-core行生效 `/reload`
-   键入任何文本来模糊搜索每个标签； `Esc` 保存和关闭
-   非tui上下文获得文本摘要： `/config show`

## 主题

104个主题随附在包中-在Pi's中选择它们 `/theme` 选择器或 `/config` （外观→主题；现场预览）。包括Ayu/Catppuccin端口和100个主题的oh-my-pi集合。

## 关闭模块

```json
{ "ceulen": { "disabled": ["munin", "ponytail"] } }
```

在 `~/.pi/agent/settings.json` 或者是一个可信的项目 `.pi/settings.json` -一个只有设置的逃生舱口为损坏的模块（没有UI）。 `/ceulen` 列出活动的内容。被禁用的模块不注册任何东西。

核心集-路由器，用法，用户体验，分类器，编写器，顾问，和 `/config` 面板本身-总是打开并且永远不会出现在终止开关列表中。

**工具加载**：大多数工具注册 _递延_ -不声明给模型，根据需要加载 `tool_search` （圆周率为你激活它）。声明每个请求：hot core （subagent, herdr, todo, write\_plan, ask\_user\_question, apply\_patch, str\_replace\_editor, web\_search/extract/screen / interaction, ffgrep/fffind, advisor, classification, think）加四个工具在2026-10-08中推广使用reeval - `munin_search`， `munin_get`， `github`， `ux_audit`． 所有其他内容都只能通过发现才能获得，无论玩家运送多少工具，固定代币的成本都很低。

## 许可证

麻省理工学院

## 常见问题

### ceulen 是什么？

Ceulen - Pi编码代理，完全打扮：一个包扩展携带完整的工具包与一个/ Ceulen配置命令。

### 如何安装 ceulen？

在项目目录运行 npm install ceulen，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-tui（\>=0\.99\.1 \<1\.6\.0）、@earendil-works/pi-coding-agent（\>=0\.99\.1 \<1\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### ceulen 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ceulen 是否存在。

### ceulen 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### ceulen 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### ceulen 可以商用吗？

ceulen 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### ceulen 还在维护吗？

最新版本 0\.26\.0 发布于 2026/11/03（今天）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/09/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。