# @amaster\.ai/pi-channels 中文文档 规范地址：https://npmcn.com/package/%40amaster.ai/pi-channels/ 版本：0\.1\.37 npm 元数据更新时间：2026-11-09T02:51:18.228Z 中文译文更新时间：2026-11-09T07:14:50.837Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/pi-channels 原文对照：https://npmcn.com/package/%40amaster.ai/pi-channels/?lang=original 项目主页：https://github.com/TGYD-helige/pi#readme 源码仓库：https://github.com/TGYD-helige/pi ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.1 MB，56 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：4 个 - peer 依赖：typebox \*，@earendil-works/pi-coding-agent \>=0\.79\.1 - 首次发布：2026-05-19T10:27:52.712Z - 最新版本发布：2026-11-09T02:51:18.060Z - 近 30 天下载量：4289（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：128（近 12 个月 128 个） ## 中文简介 包括Feishu, DingTalk, WeCom, 以及webhooks在内的本地通讯频道的 Pi扩展. ## 安装 ```sh npm install @amaster.ai/pi-channels ``` 也可以使用：`pnpm add @amaster.ai/pi-channels`、`yarn add @amaster.ai/pi-channels`、`bun add @amaster.ai/pi-channels` ## README # @amaster.ai/pi频道 ![pi-channels preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-channels/preview.png) 本地信件通道的 Pi 扩展名 . 此软件包遵循与开源软件相同的扩展形状 `@e9n/pi-channels` 软件包: 它登记一个 `notify` 工具、频道事件、路由别名,以及可选的聊天桥,将收到的频道消息转换成 pi 提示. 这不取决于 `@e9n/pi-channels` 在运行时间。 该软件包作为独立扩展源软件包发布 `@mariozechner/*` 等同命名空间和Slack/电话依赖。 此软件包在锁定此 repo 时保留相同的频道合同 `@earendil-works/*` API地表和本土的Feishu/DingTalk/WeCom适配器. ## 配置 拿着 `pi-channels` 节 `~/.pi/agent/settings.json`,则配置代理目录中的 `settings.json`,或项目/祖先 `.pi/settings.json`。只有在项目信任被接受后才能阅读项目-当地文件. `${ENV_VAR}` 插入只在用户和代理设置中支持,而不是在项目本地文件中支持. 实例中记录的直接证书环境变量仍然超过已装入的适配器值. ## 频道 - `feishu` - 由官员支持的本地Feishu/Lark应用程序信息 `@larksuiteoapi/node-sdk`。支持即将发布的 Markdown 富文本后退 , 默认情况下的 WebSocket 事件, HTTP 事件回调作为后退 , 以及正在发送的文本、 帖子和图像信息 。 这两个事件模式都从独立的图像信息和丰富的文本帖子下载图像到临时文件并传递到皮桥作为图像输入. 如果图像下载失败,文本和已成功下载的图像仍以注释方式发送,请发送者再发送缺失的图像. 下载失败和不支持的訊息類型在不需要DEBUG的情况下会生成已消毒的错误诊断;必须允许Feishu app下载訊息资源. - `wecom` - 由官方支持的本地WeCom智能机器人信息 `@wecom/aibot-node-sdk`。支持 WebSocket 长连接事件并活跃 Markdown 以 Bot ID / 秘密证书来推. - `dingtalk` - 由官方支持的本地DingTalk应用机器人信息 `dingtalk-stream` SDK(英语:SDK). 支持 Stream 模式收到的bot 消息, 回复 消息通过 `sessionWebhook`,并且活动组文本将推动通过 丁言开口API. - `webhook` - 通用的HTTP请求. ## 示例 这个 `${...}` 下面的占位符假设此部分存储在用户或代理设置中. 对于被信任的项目设置,使用相应的直接证书环境变量或字面上的非秘密值. ```json { "pi-channels": { "adapters": { "feishu": { "type": "feishu", "appId": "${FEISHU_APP_ID}", "appSecret": "${FEISHU_APP_SECRET}", "eventMode": "websocket", "respondToMentionsOnly": true }, "wecom": { "type": "wecom", "botId": "${WECOM_BOT_ID}", "secret": "${WECOM_BOT_SECRET}", "eventMode": "websocket", "respondToMentionsOnly": true, "timeoutMs": 15000 }, "dingtalk": { "type": "dingtalk", "clientId": "${DINGTALK_CLIENT_ID}", "clientSecret": "${DINGTALK_CLIENT_SECRET}", "eventMode": "stream", "respondToMentionsOnly": true } }, "routes": { "ops": { "adapter": "feishu", "recipient": "oc_xxx" } }, "bridge": { "enabled": true } } } ``` ### 桥梁扩展 该桥在可用时使用已安装的Pi套件CLI. 如果缺少 CLI( 例如, 使用独立的 Scoop 安装), 它会解决 `pi.exe` 从 `PATH` 在窗口上或 `pi` 在其它平台上。 设定 `bridge.piBin` 或者说 `PI_CHANNELS_PI_BIN` 到绝对路径或可执行名称 `PATH` 要覆盖; 拒绝工作空间内的二进制. 桥对每个来自儿童 Pi 进程的信件进行回答 `--offline --no-extensions`,所以安装的扩展从不隐含地加载( 包含频道扩展本身,使孩子无法打开第二个 串流连接). 列出儿童会话可能装入的扩展源 `bridge.extensions`; 每个条目作为可重复的 `-e `,使用 相同的路径 / npm / git 源 `pi --extension` 接受: ```json { "pi-channels": { "bridge": { "enabled": true, "extensions": ["npm:@example/pi-memory", "./local-extension.ts"] } } } ``` 空白、复制和类似旗帜的条目被忽略。 因为孩子跑 离线, `npm:` 编号 : `git:` 条目是从用户镜像安装处装入的 ——先安装软件包(`pi install npm:@example/pi-memory`, (中文(简体) ), 或条目被跳过。 打开密钥, 使儿童会话没有扩展 . ### 桥桥命令 与 `bridge.commands` 启用(默认),聊天可以控制自己与这些信件的对话: - `/status` - 桥梁活动计数器. - `/abort` ——停止当前运行的此聊天提示. - `/new` —— 启动一个干净的对话: 中止运行的提示, 丢弃已队列的信件( 其临时附件已被清理), 删除持续会话文件 `.pi/channel-sessions/-.jsonl`,因此下一条信息不会恢复旧历史. 共享相同持续对话的信件也共享一个队列 。 包括主要聊天内容及其线索: `/abort` 财务报告和审定财务报表 `/new` 应用到共享的对话中,而回复仍然流向原始聊天或线索. `/new` 等待被中止的子进程在删除文件前退出,因为皮在保存整个会话文件时会重写. 新提示等待所有重叠的重排完成 。 桥倒向本地 Pi - 代理 API 的镜像 `bridge.persistSessions` 未被删除 `/new`。 。 。 . ### 飞翔模式 WebSocket是默认和推荐模式,因为它不需要公开回调 URL : ```json { "type": "feishu", "appId": "${FEISHU_APP_ID}", "appSecret": "${FEISHU_APP_SECRET}", "eventMode": "websocket", "respondToMentionsOnly": true, "allowedChatIds": ["oc_xxx"] } ``` 当部署已经暴露出 Feishu 事件 URL 时使用 HTTP 回调模式 。 SDK处理挑战响应,符号验证,以及加密事件有效载荷. `encryptKey` 在HTTP模式中需要,因为它用于验证普通事件签名; `verificationToken` 光靠自己是不够的: ```json { "type": "feishu", "appId": "${FEISHU_APP_ID}", "appSecret": "${FEISHU_APP_SECRET}", "eventMode": "http", "verificationToken": "${FEISHU_VERIFICATION_TOKEN}", "encryptKey": "${FEISHU_ENCRYPT_KEY}", "botOpenId": "ou_xxx", "incoming": { "port": 8787, "path": "/feishu/events" } } ``` 外出 Markdown 使用丰富文本 `post` 信件为 `md` 默认元素( e)`"renderMode": "markdown"`直接发送和答复。 标记下表对本地渲染没有变化;每个有栅栏的代码块以单独的段落发送,因此后行道被保留. 普通信息仍为逐字记录 `text`。这跟随 [Hermes Feishu 适配器的后/md方法](https://github.com/NousResearch/hermes-agent/blob/ecac27c0af86064c40eeb8097cc20377cf2eee12/plugins/platforms/feishu/adapter.py)。如果Feishu拒绝一个带有非零业务代码(包括明确的HTTP 4xx拒绝)的帖子,适配器日志 `feishu-render-fallback` ,并重试一次,作为可读的纯文本;只有这样,表格才会被扩展成以列标题为标签的记录。 被拒绝的文本发送被报告为错误;模棱两可的传输或HTTP 5xx故障没有被重审,因为交付可能已经成功. 每次发送尝试前都会检查取消; SDK 不显示飞行中请求取消选项 。 设定 `"renderMode": "text"` 保留所有信件的逐字记录. 设定 `"eventMode": "off"` 仅用于外出用途. ### 叮当聊天模式 创建 DingTalk 内部应用程序,加入bot能力,选择Stream模式并发布. 将客户端ID和客户端秘密复制到适配器配置 : ```json { "type": "dingtalk", "clientId": "${DINGTALK_CLIENT_ID}", "clientSecret": "${DINGTALK_CLIENT_SECRET}", "robotCode": "${DINGTALK_ROBOT_CODE}", "eventMode": "stream", "respondToMentionsOnly": true, "allowedConversationIds": ["cid_xxx"] } ``` 收到的答复使用每个消息 `sessionWebhook` 当可用时。 活动路由发送使用 DingTalk 的分组消息 OpenAPI 与路由接收者作为对话/打开连接 爱德. `robotCode` 默认为 `clientId` 当省略时. 设定 `"eventMode": "off"` 当机器人只发出消息时. ### WeCom 模式 在 WeCom 管理控制台中创建智能机器人,选择API模式,并选择长连接选项. 将Bot ID 和 secret 复制到适配器配置 : ```json { "type": "wecom", "botId": "${WECOM_BOT_ID}", "secret": "${WECOM_BOT_SECRET}", "eventMode": "websocket", "allowedChatIds": ["wr_xxx"] } ``` 设定 `"eventMode": "off"` 当机器人只发出消息时. ## 工具 ```text notify(action: "send", adapter: "ops", text: "hello") notify(action: "list") notify(action: "test", adapter: "ops") ``` 对于费修,收件人默认为 `chat_id`。在接收器上覆盖接收id类型的前缀 : ```text chat_id:oc_xxx open_id:ou_xxx user_id:abc123 email:name@example.com ``` 对于 WeCom 智能bots,接收者是Bot API 所使用的对话ID. 在一组中, 向机器人发送一个消息并使用路径抓取来填充组 `chatid`; 对于一对一的推力,使用目标用户的用法: ```text wr_xxx zhangsan ``` 智能机器人适配器使用WebSocket Bot API,因此长接模式不需要公共回调URL. 对于 DingTalk app bots, 发送一个消息给bot, 并使用路径抓取来填充分组对话 id: ```text cid_xxx ``` ## 活动 - `channel:send` - `channel:receive` - `channel:register` - `channel:remove` - `channel:list` ## 图标 ```text /channel list /channel reload /channel bridge on /channel bridge off /channel bridge status ``` ## 常见问题 ### @amaster\.ai/pi-channels 是什么？ 包括Feishu, DingTalk, WeCom, 以及webhooks在内的本地通讯频道的 Pi扩展\. ### 如何安装 @amaster\.ai/pi-channels？ 在项目目录运行 npm install @amaster\.ai/pi-channels，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-coding-agent（\>=0\.79\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @amaster\.ai/pi-channels 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @amaster\.ai/pi-channels 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @amaster\.ai/pi-channels 可以商用吗？ @amaster\.ai/pi-channels 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @amaster\.ai/pi-channels 的下载量有多少？ 根据 npm 官方下载统计，@amaster\.ai/pi-channels 在 2026/10/06 – 2026/11/04 这 30 天内被下载 4,289 次，日均约 143 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amaster\.ai/pi-channels 还在维护吗？ 最新版本 0\.1\.37 发布于 2026/11/09（今天）；至今共发布 128 个版本，其中过去 12 个月发布了 128 个；首次发布于 2026/05/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。