@dhfpub/clawpool 0.2.1 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "OpenClaw channel plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",

package/skills/clawpool-auth-access/SKILL.md

@@ -17,7 +17,7 @@ Use the bundled scripts and local OpenClaw CLI to bootstrap ClawPool channel acc
 6. `configure-openclaw`
 7. `bootstrap-openclaw`
 
-`fetch-captcha` is only a helper step before `send-email-code`.
+`fetch-captcha` is only a helper step for `reset` and `change_password` email-code sends.
 
 ## Explain ClawPool
 
@@ -49,11 +49,16 @@ If the user wants the main OpenClaw agent to gain ClawPool channel ability quick
 
 ### A. Send registration email code
 
+1. Ask for `email`.
+2. Run `scripts/clawpool_auth.py send-email-code --email ... --scene register`.
+
+### A2. Send reset or change-password email code
+
 1. Ask for `email`.
 2. Run `scripts/clawpool_auth.py fetch-captcha`.
 3. Show `captcha_image_path` to the user if present.
 4. Ask the user to read the captcha text.
-5. Run `scripts/clawpool_auth.py send-email-code --email ... --scene register --captcha-id ... --captcha-value ...`.
+5. Run `scripts/clawpool_auth.py send-email-code --email ... --scene reset --captcha-id ... --captcha-value ...`.
 
 ### B. Register
 
@@ -160,7 +165,7 @@ This action can:
 ## Guardrails
 
 1. Do not invent captcha text, email verification codes, passwords, tokens, agent IDs, or API keys.
-2. Do not call `send-email-code` before obtaining a fresh `captcha_id`.
+2. Do not call `send-email-code` for `reset` or `change_password` before obtaining a fresh `captcha_id`.
 3. Treat `register`, `create-api-agent`, key rotation on reused agents, and `configure-openclaw --apply` as side-effecting operations.
 4. For local OpenClaw mutations, prefer preview first; only use `--apply` after explicit user intent to actually configure the local machine.
 5. Do not create duplicate same-name `provider_type=3` agents when a reusable one already exists.
@@ -176,7 +181,7 @@ This action can:
 ## Error Handling
 
 1. `图形验证码错误或已过期`:
-   fetch a new captcha and retry send-email-code.
+   for `reset` or `change_password`, fetch a new captcha and retry send-email-code.
 2. `该邮箱已被注册`:
    stop registration and switch to login if the user wants.
 3. `邮箱验证码错误或已过期`:

package/skills/clawpool-auth-access/references/api-contract.md

@@ -19,7 +19,7 @@ Helper prerequisite:
 
 | Helper Action | Method | Route | Purpose |
 |---|---|---|---|
-| `fetch-captcha` | `GET` | `/auth/captcha` | Fetch a fresh captcha before `send-email-code` |
+| `fetch-captcha` | `GET` | `/auth/captcha` | Fetch a fresh captcha before `send-email-code` for `reset` or `change_password` |
 
 ### Agent bootstrap action
 
@@ -36,7 +36,16 @@ Helper prerequisite:
 ```json
 {
   "email": "user@example.com",
-  "scene": "register",
+  "scene": "register"
+}
+```
+
+For `reset` and `change_password`, `captcha_id` and `captcha_value` are still required:
+
+```json
+{
+  "email": "user@example.com",
+  "scene": "reset",
   "captcha_id": "captcha-id",
   "captcha_value": "ab12"
 }
@@ -94,7 +103,7 @@ When the same-name `provider_type=3` agent already exists, the skill should:
 
 ### Captcha helper
 
-`fetch-captcha` returns `captcha_id` and `b64s`. The bundled script also returns `captcha_image_path` when image decoding succeeds.
+`fetch-captcha` returns `captcha_id` and `b64s`. The bundled script also returns `captcha_image_path` when image decoding succeeds. This helper is only needed for `reset` and `change_password` email-code sends.
 
 ### `register` / `login`
 
@@ -119,7 +128,7 @@ The bundled script lifts these fields to the top level:
 
 ## Common Errors
 
-1. `图形验证码错误或已过期`
+1. `图形验证码错误或已过期` for `reset` or `change_password`
 2. `邮箱验证码错误或已过期`
 3. `该邮箱已被注册`
 4. `用户不存在或密码错误`

package/skills/clawpool-auth-access/scripts/clawpool_auth.py

@@ -1231,16 +1231,28 @@ def handle_fetch_captcha(args):
 
 
 def handle_send_email_code(args):
+    scene = args.scene.strip()
+    payload = {
+        "email": args.email.strip(),
+        "scene": scene,
+    }
+    captcha_id = (args.captcha_id or "").strip()
+    captcha_value = (args.captcha_value or "").strip()
+    if scene in {"reset", "change_password"}:
+        if not captcha_id or not captcha_value:
+            raise ClawpoolAuthError(
+                "captcha_id and captcha_value are required for reset/change_password"
+            )
+    if captcha_id:
+        payload["captcha_id"] = captcha_id
+    if captcha_value:
+        payload["captcha_value"] = captcha_value
+
     result = request_json(
         "POST",
         "/auth/send-code",
         args.base_url,
-        body={
-            "email": args.email.strip(),
-            "scene": args.scene.strip(),
-            "captcha_id": args.captcha_id.strip(),
-            "captcha_value": args.captcha_value.strip(),
-        },
+        body=payload,
     )
     print_json(
         {
@@ -1409,8 +1421,8 @@ def build_parser():
     send_email_code = subparsers.add_parser("send-email-code", help="Send email verification code")
     send_email_code.add_argument("--email", required=True)
     send_email_code.add_argument("--scene", required=True, choices=["register", "reset", "change_password"])
-    send_email_code.add_argument("--captcha-id", required=True)
-    send_email_code.add_argument("--captcha-value", required=True)
+    send_email_code.add_argument("--captcha-id", default="")
+    send_email_code.add_argument("--captcha-value", default="")
     send_email_code.set_defaults(handler=handle_send_email_code)
 
     register = subparsers.add_parser("register", help="Register by email verification code")

package/skills/message-send/SKILL.md

@@ -128,6 +128,83 @@ target=agent:clawpool-developer:clawpool:direct:e72ce987-2d2e-40ed-bcc9-b336b497
 
 ---
 
+## 会话卡片消息协议
+
+当消息内容是在**提醒用户打开某个群聊**、**打开某个私聊对话**、**引用某个具体对话记录入口**时，如果已经拿到了准确的 `session_id`，不要发送自然语言链接，也不要发送前端内部 JSON；必须发送显式的 `conversation-card` 指令文本，由前端统一解析并渲染为可点击的会话卡片。
+
+### 标准格式
+
+群聊：
+
+```text
+[[conversation-card|session_id=<SESSION_ID>|session_type=group|title=<GROUP_TITLE>]]
+```
+
+私聊：
+
+```text
+[[conversation-card|session_id=<SESSION_ID>|session_type=private|title=<CHAT_TITLE>|peer_id=<PEER_ID>]]
+```
+
+### 字段规则
+
+- `session_id`：必填。必须是准确的目标会话 ID。
+- `session_type`：必填。只能是 `group` 或 `private`。
+- `title`：必填。展示给用户看的群标题或私聊标题。
+- `peer_id`：仅私聊可选。用于补充私聊对象信息，但前端打开行为仍以 `session_id` 为准。
+
+### 编码规则
+
+为了避免标题里出现 `|`、`=`、`]`、空格、换行或其他保留字符导致前端解析失败，`conversation-card` 的字段值应按 URI component 规则编码后再写入指令。
+
+- 推荐：对 `title`、`peer_id`、以及未来可能扩展的文本字段统一做 URI component 编码
+- `session_id` 和 `session_type` 如果本身只包含安全字符，可以直接原样输出
+- 前端会按 URI component 解码后再渲染
+
+示例：
+
+```text
+[[conversation-card|session_id=session-9|session_type=group|title=%E4%BA%A7%E5%93%81%E8%AE%A8%E8%AE%BA%E7%BE%A4%20A]]
+```
+
+### 使用要求
+
+1. 只有在**已知准确 `session_id`** 时，才允许输出 `conversation-card`。
+2. 如果没有 `session_id`，只能发送普通文本说明，不能伪造会话卡片。
+3. 不要输出 `chat://...`、网页链接、或“点这里打开会话”之类的自然语言链接替代方案。
+4. 不要构造前端内部 `biz_card` JSON，也不要尝试发送 Flutter/前端私有协议结构。
+5. `conversation-card` 必须单行发送，不要换行，不要在同一条指令里混入多余说明文字。
+6. 如果字段值包含特殊字符，先做 URI component 编码，再拼进指令文本。
+
+### 示例
+
+示例 1：提醒用户进入群聊
+
+```text
+[[conversation-card|session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901|session_type=group|title=产品群]]
+```
+
+示例 2：提醒用户进入某个私聊
+
+```text
+[[conversation-card|session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512|session_type=private|title=Alice|peer_id=1001]]
+```
+
+### 适用场景
+
+- 给 owner 或其他用户发送“请进入这个对话继续处理”的提醒
+- 发送“这是你要查看的群聊/私聊入口”的通知
+- 发送引用型对话入口，而不是发送完整对话记录内容
+
+### 不适用场景
+
+- 普通文本通知
+- 没有准确 `session_id` 的模糊提醒
+- 需要直接发送完整对话记录内容的场景
+- 仅仅告诉对方“我已经处理完了”，但并不需要跳转到某个具体会话的场景
+
+---
+
 ## 错误处理
 
 常见错误及处理方式：
@@ -145,3 +222,4 @@ target=agent:clawpool-developer:clawpool:direct:e72ce987-2d2e-40ed-bcc9-b336b497
 2. **使用变量**：在代码中使用 `{agentId}`、`{accountId}` 等变量，而不是硬编码
 3. **简洁明了**：私信消息应简洁，突出重点
 4. **适当使用**：不要滥用私信功能，避免打扰 owner
+5. **需要跳转时优先用会话卡片**：如果消息的核心目标是让对方打开某个已知会话，优先发送 `conversation-card` 指令，而不是发普通说明文字