sophhub 0.4.2 → 0.4.4

package/agents/vip-qa/TOOLS.md

@@ -0,0 +1,41 @@
+# TOOLS.md - 工具备忘（问答 Agent）
+
+## 可用工具
+
+| 工具 | 用途 | 权限 |
+|------|------|------|
+| `read` | 读取知识库文档、图片 | knowledge/ 只读 |
+| `image` | 调用 VLM 识别用户发来的图片 | 只读 |
+| `write` | 写入自己的实例记忆（日志、反馈、画像、摘要等） | 仅限本实例 `memory/` 下允许的文件与根目录 `MEMORY.md`（不得写入 `knowledge/`；具体以 `runtime/agent-binding.json` 的 `allowedWritePatterns` 为准） |
+| `grep` | 搜索知识库文档内容 | knowledge/ 只读 |
+
+## 禁用工具
+
+- `exec` — 已在平台层禁用，无法执行任何 shell 命令
+
+## 工作目录
+
+**路径基目录：** 下文相对路径均以**本问答实例 workspace 根目录**为根（见 `AGENTS.md` 的「路径基目录」）。
+
+- **知识库目录:** `knowledge/`（symlink，指向主 Agent 的知识库，只读）
+- **FAQ 文件:** `knowledge/FAQ.md`（只读）
+- **索引文件:** `knowledge/INDEX.md`（只读）
+- **图片目录:** `knowledge/images/media/`（只读）
+- **短期记忆:** `memory/`（可读写）
+- **会话日志:** `memory/YYYY-MM-DD.md`（可写，按需创建）
+- **画像记忆:** `memory/profile.json`（可写）
+- **偏好备忘:** `memory/preferences.md`（可写）
+- **启动摘要:** `memory/summary.md`（可写；通常由离线脚本生成/更新，但文件仍属于实例记忆区）
+- **长期记忆:** `MEMORY.md`（可写，仅限已确认画像和稳定偏好）
+- **用户反馈:** `memory/feedback-YYYY-MM-DD.md`（可写）
+- **安全日志:** `memory/security-log.md`（可写）
+- **FAQ 建议:** `memory/faq-suggestions.md`（可写）
+
+## 注意事项
+
+- `read` 工具可直接读取 `.md`、`.txt`、`.pdf`、`.xlsx` 和图片文件
+- `grep` 工具可搜索 `knowledge/` 目录下所有 `.md` 文件的内容
+- 不要尝试对 `knowledge/` 目录执行任何写入操作
+- 不要尝试对 `knowledge/` 或系统配置文件执行任何写入操作
+- 写 `MEMORY.md` 时仅允许记录已确认偏好和稳定服务风格，禁止写入知识库事实与安全策略
+- `runtime/agent-binding.json` 属于运行时约束文件，**不要**通过对话尝试修改；若确需调整权限边界，走运维流程

package/agents/vip-qa/USER.md

@@ -0,0 +1,16 @@
+# USER.md - 使用者信息
+
+本助手面向**潜在客户**，通过 API 接口提供问答服务。
+
+## 典型用户
+
+- 询问产品规格
+- 查找解决方案
+- 产品推荐
+
+## 注意事项
+
+- 不同用户的业务熟练度不同，回答时注意判断对方的经验水平
+- 涉及具体系统操作的问题，尽量给出步骤说明
+- 如果用户提到的流程与知识库文档有出入，提醒用户以最新版本文档为准
+- 用户无法直接修改知识库，反馈记录后由管理员处理

package/agents/vip-qa/scripts/setup_links.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# 与 AGENTS.md 一致：VIP 问答实例 workspace 根目录下 knowledge/ 为只读挂载（symlink），
+# 指向 vip-admin workspace（与实例目录同父级）下的共享 knowledge/。
+# 实例内 memory/、MEMORY.md 等仍在本 workspace，不由本脚本链接。
+#
+# 用法：由安装器在 post_install 中调用；需传入本实例 workspace 绝对路径，或设置：
+#   WORKSPACE=/path/to/workspace_<INSTANCE_ID> ./scripts/setup_links.sh
+#   或 OPENCLAW_WORKSPACE=... ./scripts/setup_links.sh
+#   或 ./scripts/setup_links.sh /path/to/workspace_<INSTANCE_ID>
+
+set -euo pipefail
+
+WS="${WORKSPACE:-${OPENCLAW_WORKSPACE:-${1:-}}}"
+if [[ -z "$WS" ]]; then
+  echo "setup_links: set WORKSPACE or OPENCLAW_WORKSPACE, or pass the instance workspace root as the first argument." >&2
+  exit 1
+fi
+
+WS="$(cd "$WS" && pwd)"
+parent="$(dirname "$WS")"
+admin_knowledge="${parent}/knowledge"
+link="${WS}/knowledge"
+
+if [[ ! -d "$admin_knowledge" ]]; then
+  echo "setup_links: admin knowledge directory not found: ${admin_knowledge}" >&2
+  echo "setup_links: install vip-admin first so ${admin_knowledge} exists." >&2
+  exit 1
+fi
+
+mkdir -p "$WS"
+
+if [[ -e "$link" && ! -L "$link" ]]; then
+  echo "setup_links: ${link} exists and is not a symlink; refusing to replace." >&2
+  exit 1
+fi
+
+rm -f "$link"
+ln -sfn "$(cd "$admin_knowledge" && pwd)" "$link"
+echo "setup_links: ${link} -> $(readlink "$link")"

package/package.json

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

package/skills/agent-install/skill.json

@@ -0,0 +1,27 @@
+{
+  "name": "agent-install",
+  "version": "0.1.4",
+  "types": [
+    "store"
+  ],
+  "displayName": "Agent安装",
+  "description": "通用 Agent 安装与升级。",
+  "changelog": [
+    {
+      "changes": [
+        "修复依赖 Agent 使用自定义 openclaw_id 时的安装检测逻辑"
+      ],
+      "date": "2026-04-21",
+      "version": "0.1.4"
+    },
+    {
+      "changes": [
+        "初次提交"
+      ],
+      "date": "2026-04-21",
+      "version": "0.1.3"
+    }
+  ],
+  "createdAt": "2026-04-21",
+  "updatedAt": "2026-04-21"
+}

package/skills/agent-install/src/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: agent-install
+description: 安装或升级通用 OpenClaw Agent（含按 .config.json 自动下载 skill）。Use when the user asks to install an agent, upgrade an agent, download agent config, back up an existing agent, update openclaw.json, or install skills listed with auto_install.
+version: 0.1.0
+---
+
+# Agent Install
+
+安装、升级或重置**单个** OpenClaw Agent。本 skill 只做**顺序编排 + 调用脚本**；细节见脚本与 `AGENT-CONFIG.md`。
+
+**串行**：一次只装一个 Agent，禁止并行。
+
+## 对话约束
+
+勿对用户念内部 **status** 枚举；展示安装状态以 **`user_prompt`** 为主。凡提示已备份，须给出 **`backup_dir` 完整路径**（`backup_agent.py` 输出）。密钥勿在公开渠道展示。
+
+---
+
+## Step 1：选定 Agent 并获取安装包
+
+**A. 解析 `agent_id`**
+
+```bash
+uv run {baseDir}/scripts/list_agents.py
+```
+
+非精确 id 时：
+
+```bash
+uv run {baseDir}/scripts/list_agents.py --query "{user_input}" --limit 5
+```
+
+内部：`EXACT_MATCH` → 继续；`NEEDS_CONFIRMATION` → 展示 `confirmation_message`；`NO_MATCH` → 请用户重述。
+
+**B. 下载并校验**
+
+```bash
+npx -y sophhub@latest agent download {agent_id} --path=/home/node/.openclaw/workspace
+```
+
+```bash
+uv run {baseDir}/scripts/verify_download.py \
+  --agent-id "{agent_id}" \
+  --path "/home/node/.openclaw/workspace"
+```
+
+校验失败则**终止全流程**。成功则带同一 `agent_id` 进入 Step 2。
+
+**输入模版**
+
+```text
+🔹【请提供要安装的 Agent】
+- **agent_id**（例：`ai-cs-qa`）或 **自然语言描述**（例：「智能客服 QA」）；不确定可先模糊查再选。
+
+（需多选一）
+⚠️ <confirmation_message>；可选：<suggested_replies>
+
+（未找到）
+❌ 未找到匹配，请换说法或给精确 agent_id。
+```
+
+**输出模版**
+
+```text
+✅ 已确定目标 Agent：<resolved_agent_id>
+📦 下载与校验：<成功 ✅ / 失败 ❌>；失败则 🛑 终止，不继续。
+```
+
+---
+
+## Step 2：参数、占位替换与安装状态检测
+
+依次执行，中间勿插入无关步骤。
+
+**1）解析安装参数**
+
+```bash
+uv run {baseDir}/scripts/resolve_install_params.py \
+  --agent-id "{agent_id}" \
+  --path "/home/node/.openclaw/workspace"
+```
+
+确认 `openclaw_id`、`workspace`、`agent_name`。`placeholder_catalog` / `placeholders_detail` 见 `AGENT-CONFIG.md`。用户可覆盖默认值。
+
+**2）按需替换 `.md` 中 `token`（有 `placeholders` 时）**
+
+```bash
+uv run {baseDir}/scripts/update_agent_md.py \
+  --agent-id "{agent_id}" \
+  --path "/home/node/.openclaw/workspace" \
+  --replace "{{客服助手}}=客服助手"
+```
+
+**3）检测当前安装状态**
+
+```bash
+uv run {baseDir}/scripts/check_installed.py \
+  --agent-id "{agent_id}" \
+  --source-path "/home/node/.openclaw/workspace" \
+  --openclaw-id "{openclaw_id}" \
+  --workspace "{workspace}" \
+  --name "{agent_name}"
+```
+
+对用户主状态含义（内部仍用 JSON `status` 分支，**勿对用户念枚举**）：
+
+- `DEPENDENCY_MISSING`：缺依赖 Agent → 提示先装依赖，**终止**
+- `UPDATABLE`：可升级 → 后续先备份再覆盖；本地若改过配置需自行同步
+- `SAME_VERSION_REINSTALL`：同版本 → 实为**重置**，须确认并先备份
+- `NOT_INSTALLED`：新装 → 可直接进入 Step 3 的拷贝/写配置
+
+兜底：`CONFIG_ERROR` → **终止**，人工核对 workspace / ID / 版本
+
+说明时优先复述 **`user_prompt`**。
+
+**输入模版**
+
+```text
+🔹【确认或覆盖】openclaw_id / workspace / agent_name（默认见脚本）
+⚠️ 若有占位：按 placeholder_catalog 的 label、description 确认每个 token 的替换文案
+```
+
+**输出模版**
+
+```text
+📌 参数已就绪（表格可列 openclaw_id、workspace、agent_name）
+✏️ 若已跑 update_agent_md：<简述>
+🧭 安装状态：用口语复述 user_prompt；CONFIG_ERROR 时 🛑 暂停
+```
+
+---
+
+## Step 3：写入目标环境（条件备份 → 拷贝 → openclaw）
+
+仅在 Step 2 **不是** `DEPENDENCY_MISSING` / `CONFIG_ERROR` 时继续。
+
+**1）备份（仅 `UPDATABLE` 或 `SAME_VERSION_REINSTALL`）**  
+须先让用户回复「确认更新」或「确认重置」，再执行：
+
+```bash
+uv run {baseDir}/scripts/backup_agent.py \
+  --agent-id "{agent_id}" \
+  --openclaw-id "{current_openclaw_id}" \
+  --workspace "{workspace}" \
+  --status "{status}"
+```
+
+成功后必须把 **`backup_dir` 完整路径**告诉用户。其它 status **不要**调备份。
+
+**2）拷贝文件并更新 `openclaw.json`**
+
+```bash
+uv run {baseDir}/scripts/copy_agent_files.py \
+  --agent-id "{agent_id}" \
+  --path "/home/node/.openclaw/workspace" \
+  --workspace "{workspace}"
+```
+
+```bash
+uv run {baseDir}/scripts/update_openclaw.py \
+  --agent-id "{agent_id}" \
+  --source-path "/home/node/.openclaw/workspace" \
+  --openclaw-id "{openclaw_id}" \
+  --workspace "{workspace}" \
+  --name "{agent_name}"
+```
+
+`NOT_INSTALLED` 无备份，直接 2）。`UPDATABLE` / `SAME_VERSION_REINSTALL` 须已完成 1）。
+
+**输入模版（仅要备份时）**
+
+```text
+🔹 确认更新 → 回复：确认更新
+🔹 确认重置 → 回复：确认重置
+```
+
+**输出模版**
+
+```text
+✅ 已备份（如有）：backup_dir = <完整路径>；copied_md_files 可附
+🛠️ openclaw 已更新：摘要 agent_id、openclaw_id、workspace、version、bot-api、install_state（密钥走安全渠道）
+```
+
+---
+
+## Step 4：Skill（auto_install）与完成表
+
+在 Step 3 成功、`openclaw.json` 已写入后执行。
+
+**Skill**：读 workspace 内 `.config.json` 的 `skills`，对 **`auto_install: true`** 的条目：
+
+```bash
+mkdir -p "{workspace}/skills"
+```
+
+```bash
+npx -y sophhub@latest download {skill_name} -o "{workspace}/skills"
+```
+
+`{workspace}` 为本 Agent 工作目录；多条**依次**下载。必要时加 `--type builtin` / `--type store`。
+
+**输出模版**
+
+```text
+📎 Skill：<列出本次 download 成功的 name>；失败须如实说明
+🎉 **Agent 安装流程结束**
+| 项目 | 内容 |
+|------|------|
+| agent_id | <…> |
+| 结果 | <新装 🆕 / 升级 ⬆️ / 重置 🔄> |
+| workspace | <路径> |
+| 备份目录 | <backup_dir 或「本次无备份」> |
+| skills | <已下载 name 列表或「未在本流程下载」> |
+| bot-api | <仅安全渠道> |
+🔐 密钥勿截图发群、勿写入公开工单。
+```
+
+---
+
+## 错误与中止
+
+同版须先确认再备份；本地版本更高勿强退；无 `openclaw.json` 先初始化；`CONFIG_ERROR` 等见 Step 2。
+
+**输出模版**
+
+```text
+❌ 流程中止：<步骤简述> — <原因> — <建议>
+```
+
+---
+
+## Forbidden
+
+- 不要直接手改 `openclaw.json`
+- 不要在未确认时覆盖同名 Agent；未确认参数前不要跑 `check_installed`
+- 不要并行多 Agent；不要删其它 Agent 配置
+- 勿把「下载成功」当成「已安装完成」
+- 勿在本 skill 展开脚本实现细节

package/skills/agent-install/src/pyproject.toml

@@ -0,0 +1,6 @@
+[project]
+name = "agent-install"
+version = "0.1.4"
+description = "通用 Agent 安装与升级"
+requires-python = ">=3.10"
+dependencies = []

package/skills/agent-install/src/scripts/backup_agent.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common import (
+    default_openclaw_config_path,
+    find_agent_entry,
+    load_openclaw_config,
+    resolve_existing_agent_entry,
+)
+
+ALLOWED_BACKUP_STATUSES = {"UPDATABLE", "SAME_VERSION_REINSTALL"}
+
+
+def backup_md_files(workspace_path: Path, backup_dir: Path) -> list[str]:
+    copied_files: list[str] = []
+    if not workspace_path.is_dir():
+        return copied_files
+
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    for file_path in sorted(workspace_path.iterdir()):
+        if file_path.is_file() and file_path.suffix == ".md":
+            shutil.copy2(file_path, backup_dir / file_path.name)
+            copied_files.append(file_path.name)
+    return copied_files
+
+
+def backup_agent(
+    agent_id: str,
+    status: str,
+    config_path: Path,
+    backup_root: Path,
+    *,
+    openclaw_id: str | None = None,
+    workspace: str | None = None,
+) -> dict[str, object]:
+    if status not in ALLOWED_BACKUP_STATUSES:
+        raise ValueError(
+            "当前状态不允许执行备份。"
+            f"仅当状态为 {', '.join(sorted(ALLOWED_BACKUP_STATUSES))} 时才能备份，当前状态: {status}"
+        )
+
+    openclaw = load_openclaw_config(config_path)
+    agent_entry = None
+    if isinstance(openclaw_id, str) and openclaw_id.strip():
+        agent_entry = find_agent_entry(openclaw, openclaw_id.strip())
+    if agent_entry is None and isinstance(workspace, str) and workspace.strip():
+        agent_entry = resolve_existing_agent_entry(config_path, openclaw, agent_id, workspace.strip())
+    if agent_entry is None:
+        agent_entry = find_agent_entry(openclaw, agent_id)
+    if agent_entry is None:
+        raise ValueError(f"openclaw.json 中不存在 Agent: {agent_id}")
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup_dir = backup_root / agent_id / timestamp
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    workspace_backed_up = False
+    workspace_path = agent_entry.get("workspace")
+    copied_md_files: list[str] = []
+    if isinstance(workspace_path, str) and Path(workspace_path).exists():
+        copied_md_files = backup_md_files(Path(workspace_path), backup_dir)
+        workspace_backed_up = bool(copied_md_files)
+
+    return {
+        "agent_id": agent_id,
+        "openclaw_id": agent_entry.get("id"),
+        "status": status,
+        "backup_dir": str(backup_dir),
+        "workspace_backed_up": workspace_backed_up,
+        "workspace": workspace_path,
+        "copied_md_files": copied_md_files,
+        "message": "Agent 配置备份完成，已备份 workspace 下的 .md 文件。",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="备份已安装 Agent")
+    parser.add_argument("--agent-id", required=True, help="Agent ID")
+    parser.add_argument("--openclaw-id", help="当前 openclaw 条目 id（check_installed / openclaw 解析结果）")
+    parser.add_argument("--workspace", help="当前 workspace（流程确认结果）")
+    parser.add_argument(
+        "--status",
+        required=True,
+        help="check_installed 状态，仅允许 UPDATABLE 或 SAME_VERSION_REINSTALL",
+    )
+    parser.add_argument(
+        "--config",
+        default=str(default_openclaw_config_path()),
+        help="openclaw.json 路径",
+    )
+    parser.add_argument(
+        "--backup-root",
+        default=os.path.expanduser("~/.openclaw/backups"),
+        help="备份根目录",
+    )
+    args = parser.parse_args()
+
+    result = backup_agent(
+        args.agent_id,
+        args.status,
+        Path(args.config).expanduser().resolve(),
+        Path(args.backup_root).expanduser().resolve(),
+        openclaw_id=args.openclaw_id,
+        workspace=args.workspace,
+    )
+    json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())