sophhub 0.4.6 → 0.4.8

package/agents/vip-qa/TOOLS.md

@@ -6,7 +6,7 @@
 |------|------|------|
 | `read` | 读取知识库文档、图片 | knowledge/ 只读 |
 | `image` | 调用 VLM 识别用户发来的图片 | 只读 |
-| `write` | 写入自己的实例记忆（日志、反馈、画像、摘要等） | 仅限本实例 `memory/` 下允许的文件与根目录 `MEMORY.md`（不得写入 `knowledge/`；具体以 `runtime/agent-binding.json` 的 `allowedWritePatterns` 为准） |
+| `write` | 写入自己的实例记忆（日志、反馈、画像、摘要等） | 仅限本实例 `memory/` 下允许的文件与根目录 `MEMORY.md`；不得写入 `knowledge/` |
 | `grep` | 搜索知识库文档内容 | knowledge/ 只读 |
 
 ## 禁用工具
@@ -29,7 +29,7 @@
 - **长期记忆:** `MEMORY.md`（可写，仅限已确认画像和稳定偏好）
 - **用户反馈:** `memory/feedback-YYYY-MM-DD.md`（可写）
 - **安全日志:** `memory/security-log.md`（可写）
-- **FAQ 建议:** `memory/faq-suggestions.md`（可写）
+- **FAQ 建议:** `memory/faq-suggestions.md`（可写；由本 Agent 按 `AGENTS.md` 3.2 维护，非用户手填）
 
 ## 注意事项
 
@@ -38,4 +38,4 @@
 - 不要尝试对 `knowledge/` 目录执行任何写入操作
 - 不要尝试对 `knowledge/` 或系统配置文件执行任何写入操作
 - 写 `MEMORY.md` 时仅允许记录已确认偏好和稳定服务风格，禁止写入知识库事实与安全策略
-- `runtime/agent-binding.json` 属于运行时约束文件，**不要**通过对话尝试修改；若确需调整权限边界，走运维流程
+- 若运行环境对可写路径另有平台层限制，以实际策略为准；**不要**通过对话尝试扩大写权限；确需改边界走运维

package/agents/vip-qa/USER.md

@@ -1,6 +1,6 @@
 # USER.md - 使用者信息
 
-本助手面向**潜在客户**，通过 API 接口提供问答服务。
+本助手以**{{vip客服}}**这一对外身份，面向**潜在客户**通过 API 接口提供问答服务（安装/部署时与 bot 展示名、IDENTITY 中的 Name 一致）。
 
 ## 典型用户
 
@@ -13,4 +13,4 @@
 - 不同用户的业务熟练度不同，回答时注意判断对方的经验水平
 - 涉及具体系统操作的问题，尽量给出步骤说明
 - 如果用户提到的流程与知识库文档有出入，提醒用户以最新版本文档为准
-- 用户无法直接修改知识库，反馈记录后由管理员处理
+- 用户无法直接修改知识库，反馈记录后由 **{{vip客服管理员}}** 侧处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "SophHub CLI - Manage and download AI Agent skills",
   "type": "module",
   "bin": {

package/skills/bot-api-status/skill.json

@@ -1,12 +1,20 @@
 {
   "name": "bot-api-status",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "types": [
     "store"
   ],
   "displayName": "BOT-API",
   "description": "查看当前 Agent 的 bot api 状态，同时也支持开启、关闭、重置密钥",
   "changelog": [
+    {
+      "changes": [
+        "非 --json 输出补充 Agent 名字与 source_agent_id，与 SKILL 输出模板一致",
+        "修正 SKILL 页眉为合法 YAML frontmatter"
+      ],
+      "date": "2026-04-28",
+      "version": "1.0.3"
+    },
     {
       "changes": [
         "修正 SKILL 中 bot-api 链接路径说明（account_id 占位，与脚本一致）",
@@ -32,5 +40,5 @@
     }
   ],
   "createdAt": "2026-04-22",
-  "updatedAt": "2026-04-22"
+  "updatedAt": "2026-04-28"
 }

package/skills/bot-api-status/src/SKILL.md

@@ -45,6 +45,9 @@ uv run {baseDir}/scripts/secret.py reset --json
 ```text
 📋 🤖 bot-api 状态：<🟢 开启 / ⚪ 关闭>
 
+📛 Agent 名字：<display_name>
+🆔 Agent ID：<source_agent_id>
+
 🔗 非流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat
 🔗 流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat-stream
 🔑 密钥：<api_secret 或 📭 暂无>
@@ -55,6 +58,9 @@ uv run {baseDir}/scripts/secret.py reset --json
 ```text
 ✨ 🤖 bot-api 已创建
 
+📛 Agent 名字：<display_name>
+🆔 Agent ID：<source_agent_id>
+
 🔗 非流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat
 🔗 流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat-stream
 🔑 密钥：<api_secret>
@@ -75,9 +81,12 @@ uv run {baseDir}/scripts/secret.py reset --json
 ```text
 🔄 🤖 bot-api 密钥已更新
 
-🔑 新密钥：<new_secret>
+📛 Agent 名字：<display_name>
+🆔 Agent ID：<source_agent_id>
+
 🔗 非流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat
 🔗 流式链接：{{BASEURL}}/bot-api/v2/<account_id>/chat-stream
+🔑 新密钥：<new_secret>
 
 🔒 请妥善保管，勿对外转发或截图。
 ```
@@ -87,3 +96,4 @@ uv run {baseDir}/scripts/secret.py reset --json
 ```text
 ⚠️ 获取BASEURL失败，刷新页面或者重新登录后重试。
 ```
+

package/skills/bot-api-status/src/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
 name = "bot-api-status"
-version = "1.0.2"
+version = "1.0.3"
 description = "Manage bot-api lifecycle and secret for the current Agent"
 requires-python = ">=3.10"

package/skills/bot-api-status/src/scripts/secret.py

@@ -365,6 +365,17 @@ def _fmt_url(value: object) -> str:
     return "📭 暂无"
 
 
+def _fmt_identity(value: object) -> str:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return "📭 暂无"
+
+
+def _print_agent_identity(display_name: object, source_agent_id: object) -> None:
+    print(f"📛 名字：{_fmt_identity(display_name)}")
+    print(f"🆔 source_agent_id：{_fmt_identity(source_agent_id)}")
+
+
 def _print_link_block(url: str, stream_url: str, baseurl_note: str) -> None:
     if url != "📭 暂无":
         print(f"🔗 非流式链接：{url}")
@@ -384,6 +395,8 @@ def print_human_response(command: str, payload: dict[str, Any]) -> int:
         state = "🟢 开启" if enabled else "⚪ 关闭"
         print(f"📋 🤖 bot-api 状态：{state}")
         print()
+        _print_agent_identity(payload.get("display_name"), payload.get("source_agent_id"))
+        print()
         _print_link_block(url, stream_url, "")
         print(f"🔑 密钥：{secret}")
         return 0
@@ -393,6 +406,8 @@ def print_human_response(command: str, payload: dict[str, Any]) -> int:
         prefix = "📝" if action == "updated" else "✨"
         print(f"{prefix} 🤖 bot-api {title}")
         print()
+        _print_agent_identity(payload.get("display_name"), payload.get("source_agent_id"))
+        print()
         _print_link_block(url, stream_url, "")
         print(f"🔑 密钥：{secret}")
         print()
@@ -411,9 +426,10 @@ def print_human_response(command: str, payload: dict[str, Any]) -> int:
             return 1
         print("🔄 🤖 bot-api 密钥已更新")
         print()
-        print(f"🔑 新密钥：{secret}")
+        _print_agent_identity(payload.get("display_name"), payload.get("source_agent_id"))
         print()
         _print_link_block(url, stream_url, "")
+        print(f"🔑 新密钥：{secret}")
         print()
         print("🔒 请妥善保管，勿对外转发或截图。")
         return 0

package/skills/claw-agent-get-send/skill.json

@@ -0,0 +1,21 @@
+{
+  "name": "claw-agent-get-send",
+  "version": "1.0.0",
+  "types": ["store"],
+  "displayName": "Claw Agent Get/Send",
+  "description": "Appia claw.agent.groups.get / claw.agent.message.send：脚本封装 + HTTP/curl 参考（JWT、msg/md 负载、错误码）",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-04-28",
+      "changes": [
+        "groups / verify-target / send 分片子命令",
+        "reference-http.md：合并 claw.agent.groups.get / message.send curl 文档",
+        "skill 标识 claw-agent-get-send（原 appia-claw）",
+        "send-md 命令支持 Markdown AST 发送"
+      ]
+    }
+  ],
+  "createdAt": "2026-04-28",
+  "updatedAt": "2026-04-28"
+}

package/skills/claw-agent-get-send/src/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: claw-agent-get-send
+description: >-
+  Call Appia Claw HTTP APIs (agent.groups.get, agent.message.send) using env vars or curl.
+  Use when querying bot group memberships, verifying rid+group name, sending plaintext or Markdown AST to Appia rooms,
+  or when the user needs JWT auth rules, curl examples, or md payload shape for agent.message.send.
+---
+
+# Claw Agent（groups.get / message.send）
+
+使用 **环境变量** 鉴权，**不向仓库提交** JWT、`APP_AGENT_ID` 等明文。
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `APPIA_BASE_URL` | 是 | 根地址，例如 `https://sophgo.appia.cn` |
+| `CLAW_JWT` | 是 | `Authorization: Bearer` 的值 |
+| `APP_AGENT_ID` | 是 | SophClaw 机器人 Agent ID（与 `AGENT_ID` 二选一） |
+| `TARGET_RID` | send / verify | 目标群 `rid` |
+| `TARGET_GROUP_NAME` | verify | 群展示名，`verify-target` 双因子校验用 |
+| `TARGET_GROUP_MATCH` | 否 | `exact`（默认）或 `contains` |
+
+| 可选 | 说明 |
+|------|------|
+| `APPIA_MSG_CHUNK_SIZE` | 单条 `msg` 最大字符数，超出则拆分多次发送（默认 3500） |
+
+## 用法
+
+`{baseDir}` 为与本 `SKILL.md` 同级的安装根（通常含 `scripts/`）。
+
+### 查询群列表
+
+```bash
+uv run {baseDir}/scripts/appia_claw.py groups --json
+```
+
+### 校验目标群
+
+```bash
+uv run {baseDir}/scripts/appia_claw.py verify-target
+```
+
+### 发送纯文本（支持分段）
+
+```bash
+uv run {baseDir}/scripts/appia_claw.py send --file /tmp/brief.txt
+uv run {baseDir}/scripts/appia_claw.py send --text "hello" --rid <rid>
+```
+
+### 发送 Markdown AST
+
+```bash
+# 从 JSON 字符串
+uv run {baseDir}/scripts/appia_claw.py send-md --md-json '[{"type":"PARAGRAPH","value":[{"type":"PLAIN_TEXT","value":"**粗体** 文本"}]}]'
+
+# 从 JSON 文件
+uv run {baseDir}/scripts/appia_claw.py send-md --md-file /tmp/md.json
+
+# 纯文本自动转 md 结构
+uv run {baseDir}/scripts/appia_claw.py send-md --text "简单文本"
+```
+
+## 说明
+
+- `send` 命令使用 **`msg` 纯文本**；极长正文按 `APPIA_MSG_CHUNK_SIZE` **分多条**发送。
+- `send-md` 命令使用 **`md` Markdown AST** 结构，支持 Rocket.Chat 富文本格式。
+- 请避免与业务侧「同 Sender 并发冲突」同时使用（串行调用本脚本即可）。
+
+## HTTP / curl 参考
+
+仓库根目录的 `claw.agent.groups.get.curl.md` 与 `claw.agent.message.send.curl.md` 已并入本 skill 的 [reference-http.md](reference-http.md)（鉴权说明、完整 curl、`md` 示例、常见错误码）。需要手写请求或排查 401 / 参数错误时优先读该文件。

package/skills/claw-agent-get-send/src/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "claw-agent-get-send"
+version = "1.0.0"
+description = "Appia Claw groups.get / message.send helper"
+requires-python = ">=3.10"

package/skills/claw-agent-get-send/src/reference-http.md

@@ -0,0 +1,149 @@
+# Claw HTTP API（curl 参考）
+
+与仓库根目录 `claw.agent.groups.get.curl.md`、`claw.agent.message.send.curl.md` 同源；集成在 skill 内便于离线查阅。
+
+---
+
+## `GET /api/v1/claw/agent.groups.get`
+
+用于按 `agentId` 查询该机器人所在的所有群聊，返回 `rid` 和群名称。
+
+### 鉴权方式
+
+与 `mcpToDos` 一致：
+
+- `authRequired: false`
+- 通过请求头 `Authorization: Bearer <JWT>` 校验
+- 校验规则受以下设置控制：
+  - `Appia_Antagent_JWT_Enable`
+  - `APPIA_JWT_SECRET`
+
+### 请求示例
+
+```bash
+curl -sS -G 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.groups.get' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  --data-urlencode 'agentId=AGENT_BOT_USER_ID'
+```
+
+### 参数
+
+- `agentId`（query，必填）：OpenClaw 侧 Agent ID（会映射到机器人用户）
+
+### 成功返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "agentId": "AGENT_BOT_USER_ID",
+    "groups": [
+      {
+        "rid": "ROOM_ID_1",
+        "name": "群聊A"
+      },
+      {
+        "rid": "ROOM_ID_2",
+        "name": "群聊B"
+      }
+    ],
+    "total": 2
+  }
+}
+```
+
+### 常见失败
+
+- `{"success":false,"message":"401"}`：JWT 无效或过期
+- `{"success":false,"message":"agentId is required"}`：缺少 `agentId`
+- `{"success":false,"message":"agent not found by agentId"}`：找不到对应 agentId 的机器人
+
+---
+
+## `POST /api/v1/claw/agent.message.send`
+
+用于根据 `rid + agentId` 向指定群聊发送消息。
+
+接口会校验：
+
+1. `rid` 对应房间存在
+2. `agentId` 对应用户存在、为 bot、且 active
+3. 该 `agentId` 确实在该 `rid` 的订阅列表里
+
+满足后，走后端正常发消息逻辑（`executeSendMessage`）。
+
+### 鉴权方式
+
+与 `mcpToDos` 一致：
+
+- `authRequired: false`
+- 通过请求头 `Authorization: Bearer <JWT>` 校验
+- 校验规则受以下设置控制：
+  - `Appia_Antagent_JWT_Enable`
+  - `APPIA_JWT_SECRET`
+
+### 请求示例
+
+#### 示例一：发送纯文本
+
+```bash
+curl -sS -X POST 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.message.send' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  -d '{
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "AGENT_BOT_USER_ID",
+    "msg": "这是一条由 Claw 机器人发送的消息"
+  }'
+```
+
+#### 示例二：发送 Markdown（`md`）
+
+```bash
+curl -sS -X POST 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.message.send' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  -d '{
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "OPENCLAW_AGENT_ID",
+    "md": [
+      {
+        "type": "PARAGRAPH",
+        "value": [
+          { "type": "PLAIN_TEXT", "value": "这是一条 *Markdown* 消息" }
+        ]
+      }
+    ]
+  }'
+```
+
+### 参数
+
+- `rid`（body，必填）：目标群聊房间 ID
+- `agentId`（body，必填）：OpenClaw 侧 Agent ID（会映射到机器人用户）
+- `msg`（body，可选）：消息文本
+- `md`（body，可选）：Markdown AST（Rocket.Chat `md` 结构）
+- 约束：`msg` 和 `md` 至少提供一个
+
+### 成功返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "AGENT_BOT_USER_ID",
+    "status": "sent"
+  }
+}
+```
+
+### 常见失败
+
+- `{"success":false,"message":"401"}`：JWT 无效或过期
+- `{"success":false,"message":"rid and agentId are required, and either msg or md must be provided"}`：参数缺失
+- `{"success":false,"message":"room not found"}`：房间不存在
+- `{"success":false,"message":"agent not found by agentId"}`：找不到对应 agentId 的机器人
+- `{"success":false,"message":"agent must be a bot user"}`：agent 不是 bot
+- `{"success":false,"message":"agent is inactive"}`：机器人未激活
+- `{"success":false,"message":"agent is not in this room"}`：机器人不在该群里