# @abelxiaoxing/cadence 中文文档 规范地址：https://npmcn.com/package/%40abelxiaoxing/cadence/ 版本：2\.0\.40 npm 元数据更新时间：2026-11-06T15:03:56.240Z 中文译文更新时间：2026-11-06T06:19:29.683Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40abelxiaoxing/cadence 原文对照：https://npmcn.com/package/%40abelxiaoxing/cadence/?lang=original 项目主页：https://github.com/abelxiaoxing/cadence 源码仓库：https://github.com/abelxiaoxing/cadence ## 关键信息（来自 npm 元数据） - 包体积（解压后）：5.9 MB，169 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22\.19\.0 - 运行依赖：2 个 - peer 依赖：typebox \*，@earendil-works/pi-ai ^1\.5\.0，@earendil-works/pi-tui ^1\.5\.0，@earendil-works/pi-coding-agent ^1\.5\.0 - 首次发布：2026-08-15T16:44:38.476Z - 最新版本发布：2026-11-06T15:03:55.811Z - 近 30 天下载量：6985（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：76（近 12 个月 76 个） ## 中文简介 对话驱动的 Pi 工作空间:持久的本地和WebUI工作流程,明确的计划审批,检查和当地交付. ## 安装 ```sh npm install @abelxiaoxing/cadence ``` 也可以使用：`pnpm add @abelxiaoxing/cadence`、`yarn add @abelxiaoxing/cadence`、`bun add @abelxiaoxing/cadence` ## README # Cadence [English](https://npmcn.com/package/%40abelxiaoxing/cadence/README.md) · [简体中文](https://npmcn.com/package/%40abelxiaoxing/cadence/README.zh-CN.md) · [日本語](https://npmcn.com/package/%40abelxiaoxing/cadence/README.ja.md) · [한국어](https://npmcn.com/package/%40abelxiaoxing/cadence/README.ko.md) · [Deutsch](https://npmcn.com/package/%40abelxiaoxing/cadence/README.de.md) · [Français](https://npmcn.com/package/%40abelxiaoxing/cadence/README.fr.md) · [Español](https://npmcn.com/package/%40abelxiaoxing/cadence/README.es.md) · [Português (Brasil)](https://npmcn.com/package/%40abelxiaoxing/cadence/README.pt-BR.md) · [Русский](https://npmcn.com/package/%40abelxiaoxing/cadence/README.ru.md) Cadence 把 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 变成一种持续对话驱动的工程工作方式。 输入一次 `/cadence [目标]`，通过对话对齐计划，再由后台 owner 自动实施、验证和交付；WebUI 支持同样的持续对话流程，不需要 Pi 终端在线。 ## 为什么选择 Cadence - **工作不随窗口结束。** 任务运行在后台服务中：关闭终端、退出 Pi 或离开浏览器标签页只是断开连接，重新打开原生或浏览器对话即可继续观察工作。 - **批准之前不会修改任何文件。** 任务先只读分析并提出一个可读的计划；只有在你确认那个确切计划之后，文件才会被修改。 - **结果可信。** 子代理输出、真实的检查运行和独立 Agent 审查彼此独立：模型的文字或一句“Done”都不算检查通过，失败、取消和未知结果保持相互区分。 - **完整历史。** 新工作流保留脱敏后的子代理记录与实际进程结果；旧任务历史另支持精确搜索及 Markdown/NDJSON 导出。 - **与终端共用一份历史。** 浏览器对话就是项目的 Pi 会话：可以在浏览器里继续终端会话，也可以用 `/resume` 在终端继续浏览器会话，两边都能查看 Pi 的分支。 - **一个链接涵盖一切。** WebUI（桌面和手机，英文与简体中文）还承载普通的 Pi 对话，并可在项目间切换，每个项目都有自己的 owner 和历史。 Cadence 是一个受信任的助手，**不是沙箱**：它的代理在获批的 checkout 或 worktree 中使用宿主工具，所以请只在你能够审阅和恢复的代码上使用它。 ## 安装 你需要带 npm 的 Node `>=22.19.0`，以及已安装并登录到模型提供方的 Pi；Cadence 复用 Pi 的登录和模型设置。 ```sh npm install -g @abelxiaoxing/cadence pi install "$(npm root -g)/@abelxiaoxing/cadence" ``` 可选 WebUI/开机服务使用显式命令 `cadence server install` 注册并启动一个后台服务（Linux 上是 systemd，macOS 上是 LaunchAgent，Windows 上是登录项），并打印一个私有链接 `http://127.0.0.1:17423/?token=…`。 最后一条命令让 Pi 加载同一份副本用于 `/cadence`，因此一次 npm 升级就同时更新两者。 端口和 token 保存在 `~/.pi/agent/cadence/.env`；任何持有 token 的人都可以使用你的工作区，所以请保持链接私密。 ## 使用 ### 在浏览器中 1. 打开一次打印出的链接；浏览器之后会记住你。 如果丢失了链接，`cadence token-link --reveal` 会再次打印它。 2. 用右下角的文件夹按钮明确选择项目。 发送时复用已保存的模型偏好；没有可用偏好时只需选择一次。 3. 输入一次 `/cadence [目标]`，当前对话进入持续 Cadence 模式；之后正常对话，调查项目并澄清影响交付的关键问题。 4. 查看完整计划，点击**按此计划实施**或发送 `按计划实施`。 后台自动实施、诊断故障、调整路线、维护项目知识并验证交付，普通内部问题无需再次确认。 5. 在同一对话查看真实进度和合并结果；子代理的完整上下文从左下角**子代理**面板打开。 刷新、完成目标后仍保持 Cadence；**退出 Cadence**不取消后台工作，**取消工作流 — 请求停止**才请求取消。 ### 在终端中：一次进入，持续对话 在任意已信任项目的 Pi 对话里输入一次 `/cadence <目标>`，之后正常对话即可。 Cadence 自动调查仓库和项目知识，只澄清真正影响结果的问题，并生成包含目标、验收、范围、环境准备和本地交付方式的约定。 确认后输入 `按计划实施`，系统自主实施、诊断、接续部分成果和调整技术路线；没有固定修复轮数或总交付时长配额，真实验证后再交付。 每个获批的 Git 交付创建一个命名任务分支和稳定 worktree，在其中持续实施、恢复和维护项目知识，审查与验证后合回约定中的原分支。 进入模式和只读研究不会创建 Git 资源；不会默认推送、发布或部署。 非 Git 项目可选择直接工作副本交付，不执行提交或合并。 **完成任务后，这个对话仍然保持 Cadence 模式，不需要再次输入 `/cadence`。** 明确输入 `退出 Cadence` 或 `exit cadence` 才退出。 退出、关闭 Pi 或切换对话只脱离观察，不取消已接受的工作；需要取消时直接告诉 Cadence。 日常原生使用可按需启动或复用本地项目 owner，**无需安装系统服务或先进入项目管理器**。 模型偏好记在 `~/.pi/agent/cadence/settings.json`，跨项目复用，不复制 Pi 凭据。 项目知识优先维护在已有工程文档中，`.cadence/project.md` 作为简洁索引；相关内容在工作者启动时按需注入，交付时自动沉淀已验证经验。 隔离 worktree 不会自动复制依赖或凭据，必要的准备命令会列入确认。 详细边界见 [对话模式](https://npmcn.com/package/%40abelxiaoxing/cadence/docs/conversation-mode.md)。 `/cadence-history [运行 ID]` 提供只读诊断、运行详情和已有任务历史，不创建或执行任务，也不启动服务。 见[历史与诊断](https://npmcn.com/package/%40abelxiaoxing/cadence/docs/history.md)。 浏览器批准与所展示的计划、会话和访问身份绑定；登录本身不是执行授权。 ### 更多项目 ```sh cadence project open /absolute/project cadence project open /absolute/new-project --create ``` 每个项目都有自己的 owner、端口和历史，命令会打印其私有链接；WebUI 的文件夹选择器以相同方式打开项目。 打开另一个项目永远不会停止之前项目中的工作。 ### 检查 检查命令在你批准的具体计划中列出，包括基线检查和验收检查。 真实检查结果与自动 Agent 审查保持独立。 ## 管理服务 ```sh cadence server status cadence server restart # 升级或修改 .env / models.json 之后 cadence server upgrade # 识别 Pi/npm/Bun 安装：下载、安装并重启 cadence server stop # 保持注册状态，并在下次启动或登录时再次启动 cadence server uninstall # 在 npm uninstall -g 之前运行 ``` 用 `cadence server upgrade` 或 WebUI 的 Cadence 服务对话框升级：它在 Cadence 继续运行时先下载新版本，新版本无法启动时会装回原版本。 restart、stop 和 uninstall 按顺序停止运行中的工作，而不是留下断开连接的工作。 uninstall 只删除服务定义；项目、历史和 Pi 设置保留。 Linux root 与命名服务、远程 HTTPS 访问和恢复见[服务管理](https://npmcn.com/package/%40abelxiaoxing/cadence/docs/service-management.md)和[远程访问](https://npmcn.com/package/%40abelxiaoxing/cadence/docs/remote-access.md)。 ## 开发 Pi 也可以加载本地 checkout 或打包的 tarball：把其绝对或相对路径加到 Pi 的 `packages`，或试试 `pi -e ./cadence`。 Cadence 要求 Pi 1.5.0 或兼容的 1.x 宿主；开发用的固定版本和已测试运行时不是通用的兼容性承诺。 ```sh bun install bun run verify ``` 工程指导按领域拆分在 [engineering/](https://npmcn.com/package/%40abelxiaoxing/cadence/engineering/) 下；[AGENTS.md](https://npmcn.com/package/%40abelxiaoxing/cadence/AGENTS.md) 中的项目索引说明了哪个文件覆盖哪部分代码。 `verify` 是开发和发布共用的唯一验证入口：只运行快速检查，不需要浏览器。 需要官方 Node 构建和私有临时目录；见[验证](https://npmcn.com/package/%40abelxiaoxing/cadence/engineering/verification.md)。 ## 许可证 Cadence 采用 MIT。 捆绑的适配代码、字体和厂商保留各自许可证；见[复用与分发](https://npmcn.com/package/%40abelxiaoxing/cadence/docs/reuse-and-distribution.md)和[第三方声明](https://npmcn.com/package/%40abelxiaoxing/cadence/THIRD_PARTY_NOTICES.md)。 ## 常见问题 ### @abelxiaoxing/cadence 是什么？ 对话驱动的 Pi 工作空间:持久的本地和WebUI工作流程,明确的计划审批,检查和当地交付\. ### 如何安装 @abelxiaoxing/cadence？ 在项目目录运行 npm install @abelxiaoxing/cadence，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-ai（^1\.5\.0）、@earendil-works/pi-tui（^1\.5\.0）、@earendil-works/pi-coding-agent（^1\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 cadence、cadence-service，可以用 npx cadence 直接运行。 ### @abelxiaoxing/cadence 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/abelxiaoxing\_\_cadence 是否存在。 ### @abelxiaoxing/cadence 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @abelxiaoxing/cadence 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @abelxiaoxing/cadence 可以商用吗？ @abelxiaoxing/cadence 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @abelxiaoxing/cadence 的下载量有多少？ 根据 npm 官方下载统计，@abelxiaoxing/cadence 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,985 次，日均约 233 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @abelxiaoxing/cadence 还在维护吗？ 最新版本 2\.0\.40 发布于 2026/11/06（1 天前）；至今共发布 76 个版本，其中过去 12 个月发布了 76 个；首次发布于 2026/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。