cx-feishu 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComChatX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# cx-feishu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [pi](https://pi.dev) package for sending messages to a Feishu (飞书) group bot from a [ComChatX](https://comchatx.com) box with [pi-channels](https://www.npmjs.com/package/@amaster.ai/pi-channels) (`@amaster.ai/pi-channels`) and its `notify` tool. It sends nothing itself and neither bundles nor lists pi-channels: the seller installs pi-channels beside it.
+
+It is one skill, `cx-feishu`, telling the model what pi-channels' own words miss here: where a bot's address comes from and what overrides it, that a Feishu bot reads only the raw `json` body (`notify`'s default envelope, and its `test` action without `json`, are refused), what keywords, 签名校验 and IP whitelists do to a send, that `Sent` means an HTTP 2xx and Feishu refuses with HTTP 200 and a nonzero `code`, that replies come back to no conversation, and that a listener keeps the box awake.
+
+## A bot
+
+One `webhook` adapter and one route, in the `pi-channels` section of pi's settings:
+
+```json
+{
+  "pi-channels": {
+    "adapters": { "feishu": { "type": "webhook" } },
+    "routes": { "team": { "adapter": "feishu", "recipient": "${FEISHU_HOOK}" } }
+  }
+}
+```
+
+pi-channels expands `${VAR}` in the global and agent-directory settings, not in a project's `.pi/settings.json`; a project's `pi-channels` section replaces the others' key by key — `adapters`, `routes` and `bridge` each — so a section meant to stop another layer's bot carries all three.
+
+## Install
+
+```bash
+pi install -l npm:@amaster.ai/pi-channels@0.1.28
+pi install -l npm:cx-feishu
+```
+
+pi-channels is named at 0.1.28, the version this package is checked against, so pi keeps that version. Run in `/tenant`; without `-l` the install is gone at the box's next start. On ComChatX, a seller installs both from the Plugins page once they are listed.
+
+## Develop
+
+```bash
+npm ci
+npm run typecheck
+npm test               # loads the package with the pinned pi, and sends through pi-channels 0.1.28 to a stub on 127.0.0.1
+```

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "cx-feishu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A pi package that tells the model what pi-channels' notify needs to reach a Feishu group bot from a ComChatX box, and what its answer means.",
+  "license": "MIT",
+  "author": "ComChatX",
+  "comchatx": {
+    "about": "让 cx 通过你的飞书机器人给你发消息。",
+    "description": "cx 会在你的机器人所在的飞书群里发消息，比如某个 listing 丢失 Buy Box 时。在飞书里回复的消息不会传给 cx。\n\n安装后，在它的设置里填写机器人的 Webhook 地址。",
+    "mark": {
+      "line": "megaphone"
+    },
+    "section": "extensions",
+    "order": 40,
+    "builds": [
+      "@amaster.ai/pi-channels"
+    ]
+  },
+  "homepage": "https://github.com/comchatx/cx-feishu#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comchatx/cx-feishu.git"
+  },
+  "bugs": "https://github.com/comchatx/cx-feishu/issues",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "files": [
+    "skills"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "26.2.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "overrides": {
+    "@earendil-works/chord": "1.1.0",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-mcp": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@earendil-works/pi-codemode": "1.1.0",
+    "@earendil-works/pi-agent-core": "1.1.0",
+    "@earendil-works/pi-telemetry": "1.1.0"
+  }
+}

package/skills/cx-feishu/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cx-feishu
+description: "Sending a message to a Feishu (飞书) group bot from a ComChatX box - a report, an alert, a heartbeat's result - with pi-channels (`@amaster.ai/pi-channels`) and its `notify` tool; what pi-channels' own words miss here. Needs @amaster.ai/pi-channels; if no notify tool is offered, it is not installed, and the seller installs it in Plugins once it is listed there, or it is installed with `pi install -l npm:@amaster.ai/pi-channels@0.1.28` run in /tenant (without -l it is gone at the box's next start). cx-feishu itself installs the same way: Plugins once listed, or `pi install -l npm:cx-feishu` in /tenant."
+---
+
+## Where the bot's address comes from
+
+- A bot is a route in pi-channels' settings: `notify action:"list"` shows the routes and hides their addresses. Send to a route by its name as `adapter`.
+- An address the seller gives on the Plugins page works from the box's next open, not in the conversation already open.
+- A `pi-channels` section in `/tenant/.pi/settings.json` replaces the one from Plugins key by key: its `adapters`, `routes` and `bridge` each replace the Plugins ones, and a key it leaves out keeps the Plugins value. A section meant to stop the Plugins bot carries all three.
+- An address the seller says in chat, or one passed as `recipient`, is kept in the conversation's file. A `recipient` passed with a route replaces the route's own address for that send. Use the route and pass no `recipient`.
+
+## What a send needs
+
+- Pass the message as `json`, the body a Feishu bot reads, for example `{"msg_type":"text","content":{"text":"..."}}`. Without `json`, `notify` posts its own envelope (`text`, `source`, `metadata`, `timestamp`), which Feishu takes no text from and refuses.
+- `action:"test"` without `json` posts that envelope: a bot refuses it. Test with a short `json` text.
+- A bot with keywords refuses any message whose text lacks one of them; ask the seller for the bot's keywords and put one in the text. A bot with 签名校验 (signature check) or an IP whitelist refuses every send from here.
+
+## What "Sent" means
+
+- `notify` says `Sent` on any HTTP 2xx and never reads the reply. Feishu refuses with HTTP 200 and a nonzero `code` in the body (a missing keyword is `19024`), so `Sent` does not mean the message was shown. When it matters, ask the seller whether it arrived; if it did not, the cause is one of those above.
+
+## What does not come back
+
+- Replies in the Feishu group reach no conversation here: a webhook bot only receives.
+- pi-channels' `feishu` and `dingtalk` adapters listen for replies unless their `eventMode` is `off`. A listener holds a connection open and keeps the box awake, and awake time is billed; the `webhook` adapter holds nothing open.