sophhub 0.4.30 → 0.4.32

package/package.json

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

package/skills/restore-state/skill.json

@@ -0,0 +1,16 @@
+{
+  "name": "restore-state",
+  "version": "1.0.0",
+  "types": ["store"],
+  "displayName": "状态恢复",
+  "description": "从 ZIP 备份文件恢复 SophClaw 完整状态。当用户要求恢复数据、还原备份、恢复账号或上传了备份 ZIP 文件时触发。支持恢复 agent 配置、会话历史、workspace 文件、语义记忆等全部状态。",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-05-27",
+      "changes": ["从 moltbot 迁移：ZIP 备份解析、openclaw.json 合并、会话恢复、workspace 恢复"]
+    }
+  ],
+  "createdAt": "2026-05-27",
+  "updatedAt": "2026-05-27"
+}

package/skills/restore-state/src/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: restore-state
+description: 从 ZIP 备份文件恢复 SophClaw 完整状态。当用户说要"恢复数据"、"还原备份"、"恢复我的账号"、"restore"并上传了 ZIP 文件时触发。支持恢复 agent 配置、会话历史、workspace 文件、语义记忆等全部状态。
+---
+
+# Restore State
+
+从用户上传的 ZIP 备份文件恢复 SophClaw 完整状态到当前空白容器。
+
+## 前置检查
+
+在开始恢复之前，先确认以下几点：
+
+1. 用户已通过聊天上传了一个 `.zip` 文件（从 SophClaw 前端下载的备份包）
+2. 当前容器是空白状态（新创建的容器，不包含用户之前的数据）
+3. 如果当前容器已有重要数据，警告用户会被部分覆盖
+
+向用户简短确认：
+
+- "我将用你上传的备份文件恢复你的 SophClaw 状态，包括 agent 配置、会话历史和 workspace 文件。当前容器的某些数据会被覆盖。确认继续吗？"
+
+用户确认后继续。
+
+## 定位上传的 ZIP 文件
+
+用户通过 SophClaw Web UI 上传的文件会被保存在 `~/.openclaw/media/inbound/` 目录下，文件名格式为 `<原始名称>---<uuid>.zip`。
+
+**第一步：查找最新上传的 ZIP 文件**
+
+```bash
+ls -lt ~/.openclaw/media/inbound/*.zip 2>/dev/null | head -5
+```
+
+如果用户刚上传了一个恢复用的 ZIP，最新的文件就是它（文件名包含恢复相关的关键词如 `restore`、`backup`、`openclaw` 等）。
+
+如果找到明确的文件，直接使用它的完整路径。如果有多个 ZIP，选择最新的那个。
+
+**第二步：如果 media/inbound 目录没有 ZIP**
+
+可能用户是通过其他方式提供的文件路径。请用户确认文件位置，然后用 `ls` 验证。
+
+## 执行恢复
+
+找到 ZIP 文件路径后，运行：
+
+```bash
+python3 skills/restore-state/src/scripts/restore.py "<找到的zip文件完整路径>"
+```
+
+也可以不加参数直接运行，脚本会自动搜索 `~/.openclaw/media/inbound/` 中最新的 ZIP：
+
+```bash
+python3 skills/restore-state/src/scripts/restore.py
+```
+
+## 解释恢复结果
+
+脚本会输出恢复摘要，包括：
+- 恢复了哪些 agent（main、assistant、beauty、vip-qa 等）
+- 恢复了多少条会话记录
+- 恢复了哪些 workspace
+- 是否有跳过的文件及原因
+
+向用户报告摘要。
+
+## 下一步提示
+
+提醒用户：
+
+- "由于更新了配置，SophClaw 会自动重新加载。等待约 10 秒后刷新前端页面即可看到恢复的会话和 agent。"
+
+## 异常处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| ZIP 文件路径不存在 | 用 `ls ~/.openclaw/media/inbound/` 查看可用文件，选最新的 ZIP |
+| ZIP 文件格式损坏 | 请用户重新下载备份文件后再试 |
+| 未找到任何 ZIP 文件 | 请用户重新上传备份文件到聊天中 |
+| Python 或依赖缺失 | 运行 `which python3` 确认解释器存在 |
+| 权限被拒绝写入 ~/.openclaw | 检查当前用户和目录权限 |
+| openclaw.json 解析失败 | 检查备份文件是否完整，尝试用 `python3 -m json.tool` 验证 JSON |
+| Gateway 重载失败 | 手动运行 `openclaw daemon restart` |

package/skills/restore-state/src/scripts/restore.py

@@ -0,0 +1,396 @@
+#!/usr/bin/env python3
+"""SophClaw state restore tool.
+
+Extracts a SophClaw backup ZIP and merges its contents into the current
+state directory (~/.openclaw by default).
+
+Usage:
+    python3 restore.py [backup.zip]
+
+If no path is given, auto-discovers the latest ZIP in ~/.openclaw/media/inbound/.
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+
+def resolve_state_dir() -> Path:
+    """Resolve the SophClaw state directory, same logic as SophClaw's resolveStateDir."""
+    env_override = os.environ.get("OPENCLAW_STATE_DIR")
+    if env_override:
+        return Path(env_override).expanduser().resolve()
+
+    home = Path.home()
+    candidates = [
+        home / ".openclaw",
+        home / ".clawdbot",
+        home / ".moltbot",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    return home / ".openclaw"
+
+
+def auto_discover_zip(state_dir: Path) -> Path | None:
+    """Find the most recent ZIP file in the media/inbound directory."""
+    inbound = state_dir / "media" / "inbound"
+    if not inbound.is_dir():
+        return None
+
+    zip_files = sorted(
+        inbound.glob("*.zip"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    if not zip_files:
+        return None
+    return zip_files[0]
+
+
+# Config keys to RESTORE from the backup (user-created content and preferences).
+RESTORE_BACKUP_KEYS = {
+    "agents",
+    "models",
+    "skills",
+    "tools",
+    "commands",
+    "messages",
+    "session",
+    "identity",
+    "cron",
+}
+
+
+def deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge overlay into base. overlay values win on conflict."""
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def merge_openclaw_json(backup_path: Path, state_dir: Path) -> dict:
+    """Merge backup openclaw.json with the current one.
+
+    Backup values take precedence for user-config keys (agents, models, etc.).
+    Container runtime keys (gateway, channels, plugins) are kept from current.
+    """
+    current_path = state_dir / "openclaw.json"
+    if not current_path.exists():
+        with open(backup_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    with open(current_path, "r", encoding="utf-8") as f:
+        current = json.load(f)
+    with open(backup_path, "r", encoding="utf-8") as f:
+        backup = json.load(f)
+
+    merged = dict(current)
+
+    for key in RESTORE_BACKUP_KEYS:
+        if key in backup:
+            if key in merged and isinstance(merged[key], dict) and isinstance(backup[key], dict):
+                merged[key] = deep_merge(merged[key], backup[key])
+            else:
+                merged[key] = backup[key]
+
+    return merged
+
+
+def merge_sessions_json(backup_path: Path, current_path: Path) -> tuple[int, int]:
+    """Merge backup sessions.json into the current one.
+
+    Backup entries win on session ID conflict.
+    Returns (backup_session_count, merged_total_count).
+    """
+    current_sessions: dict = {}
+    if current_path.exists():
+        with open(current_path, "r", encoding="utf-8") as f:
+            current_sessions = json.load(f)
+
+    with open(backup_path, "r", encoding="utf-8") as f:
+        backup_sessions = json.load(f)
+
+    merged = dict(current_sessions)
+    for session_id, entry in backup_sessions.items():
+        merged[session_id] = entry
+
+    current_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(current_path, "w", encoding="utf-8") as f:
+        json.dump(merged, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+
+    return len(backup_sessions), len(merged)
+
+
+def copy_file(src: Path, dst: Path) -> bool:
+    """Copy a file from src to dst, creating parent dirs as needed."""
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+        return True
+    except OSError as e:
+        print(f"  [WARN] Failed to copy {src} -> {dst}: {e}", file=sys.stderr)
+        return False
+
+
+def copy_directory(src: Path, dst: Path) -> tuple[int, int]:
+    """Recursively copy directory contents from src to dst."""
+    copied = 0
+    skipped = 0
+    dst.mkdir(parents=True, exist_ok=True)
+    for item in src.rglob("*"):
+        rel = item.relative_to(src)
+        target = dst / rel
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        if copy_file(item, target):
+            copied += 1
+        else:
+            skipped += 1
+    return copied, skipped
+
+
+def resolve_backup_path(args: list[str], state_dir: Path) -> tuple[Path, str]:
+    """Resolve the backup ZIP path from CLI args or auto-discovery.
+
+    Returns (path, source_description).
+    """
+    if len(args) >= 2:
+        user_path = Path(args[1]).resolve()
+        if not user_path.exists():
+            print(f"Error: backup file not found: {user_path}", file=sys.stderr)
+            sys.exit(1)
+        if not zipfile.is_zipfile(user_path):
+            print(f"Error: not a valid ZIP file: {user_path}", file=sys.stderr)
+            sys.exit(1)
+        return user_path, "user-specified"
+
+    # Auto-discover from media/inbound
+    discovered = auto_discover_zip(state_dir)
+    if discovered is None:
+        print(
+            "Error: no backup ZIP path provided and no ZIP files found in "
+            f"{state_dir / 'media' / 'inbound'}",
+            file=sys.stderr,
+        )
+        print(
+            "Usage: python3 restore.py <backup.zip>\n"
+            "       or upload a ZIP via SophClaw chat and run without arguments.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return discovered, "auto-discovered"
+
+
+def main():
+    state_dir = resolve_state_dir()
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    zip_path, source = resolve_backup_path(sys.argv, state_dir)
+
+    print(f"State directory: {state_dir}")
+    print(f"Backup ZIP ({source}): {zip_path}")
+    print(f"  Size: {zip_path.stat().st_size / 1024:.1f} KB")
+    print()
+
+    summary = {
+        "agents_restored": [],
+        "sessions_total": 0,
+        "sessions_merged": 0,
+        "files_copied": 0,
+        "files_skipped": 0,
+        "workspaces_restored": [],
+    }
+
+    with tempfile.TemporaryDirectory(prefix="sophclaw-restore-") as tmpdir:
+        tmp = Path(tmpdir)
+        print("Extracting ZIP...")
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(tmp)
+
+        top_items = list(tmp.iterdir())
+        print(f"  Extracted {len(top_items)} top-level items")
+
+        # === 1. openclaw.json ===
+        backup_config = tmp / "openclaw.json"
+        if backup_config.exists():
+            print("\n--- Config ---")
+            print("  Merging openclaw.json...")
+            merged = merge_openclaw_json(backup_config, state_dir)
+
+            config_target = state_dir / "openclaw.json"
+            with open(config_target, "w", encoding="utf-8") as f:
+                json.dump(merged, f, ensure_ascii=False, indent=2)
+                f.write("\n")
+            print(f"  Written: {config_target}")
+
+            agents_list = merged.get("agents", {}).get("list", [])
+            for agent in agents_list:
+                summary["agents_restored"].append(agent.get("id", "unknown"))
+            print(f"  Agents restored: {', '.join(summary['agents_restored']) or 'none'}")
+        else:
+            print("  [WARN] No openclaw.json found in backup")
+
+        # === 2. Agents (sessions, models, runtime-stats) ===
+        backup_agents = tmp / "agents"
+        if backup_agents.is_dir():
+            print("\n--- Agents ---")
+            current_agents = state_dir / "agents"
+
+            for agent_dir in sorted(backup_agents.iterdir()):
+                if not agent_dir.is_dir():
+                    continue
+                agent_name = agent_dir.name
+
+                # Merge sessions.json
+                backup_sessions_json = agent_dir / "sessions" / "sessions.json"
+                current_sessions_json = current_agents / agent_name / "sessions" / "sessions.json"
+                if backup_sessions_json.exists():
+                    backup_count, merged_count = merge_sessions_json(
+                        backup_sessions_json, current_sessions_json
+                    )
+                    summary["sessions_merged"] += backup_count
+                    summary["sessions_total"] += merged_count
+                    print(
+                        f"  [{agent_name}] sessions: {backup_count} from backup, "
+                        f"{merged_count} total after merge"
+                    )
+
+                # Copy session transcript .jsonl files
+                backup_sessions_dir = agent_dir / "sessions"
+                if backup_sessions_dir.is_dir():
+                    jsonl_count = 0
+                    for session_file in backup_sessions_dir.iterdir():
+                        if session_file.suffix == ".jsonl" and session_file.name != "sessions.json":
+                            target = current_agents / agent_name / "sessions" / session_file.name
+                            if copy_file(session_file, target):
+                                jsonl_count += 1
+                    if jsonl_count > 0:
+                        print(f"  [{agent_name}] transcripts: {jsonl_count} files copied")
+
+                # Copy non-session agent files (models.json, runtime-stats, etc.)
+                for item in agent_dir.rglob("*"):
+                    if item.is_dir():
+                        continue
+                    rel = item.relative_to(agent_dir)
+                    if rel.parts[0] == "sessions":
+                        continue
+                    target = current_agents / agent_name / rel
+                    if copy_file(item, target):
+                        summary["files_copied"] += 1
+        else:
+            print("\n  [INFO] No agents directory in backup")
+
+        # === 3. Workspace directories ===
+        print("\n--- Workspaces ---")
+        for item in sorted(tmp.iterdir()):
+            if not item.is_dir():
+                continue
+            if item.name.startswith("workspace"):
+                ws_name = item.name
+                current_ws = state_dir / ws_name
+                copied, skipped = copy_directory(item, current_ws)
+                summary["files_copied"] += copied
+                summary["files_skipped"] += skipped
+                summary["workspaces_restored"].append(ws_name)
+                print(f"  [{ws_name}] {copied} files, {skipped} skipped")
+
+        # === 4. Memory SQLite files ===
+        backup_memory = tmp / "memory"
+        if backup_memory.is_dir():
+            print("\n--- Memory ---")
+            current_memory = state_dir / "memory"
+            for db_file in sorted(backup_memory.iterdir()):
+                if db_file.suffix == ".sqlite":
+                    target = current_memory / db_file.name
+                    if copy_file(db_file, target):
+                        summary["files_copied"] += 1
+                        print(f"  [{db_file.name}] restored")
+
+        # === 5. Loose files (identity, canvas, logs, media, config backups, etc.) ===
+        LOOSE_PATTERNS = [
+            "identity",
+            "canvas",
+            "logs",
+            "media",
+            "openclaw.json.bak",
+            "openclaw.json.bak.1",
+            "openclaw.json.bak.2",
+            "openclaw.json.bak.3",
+            "openclaw.json.bak.4",
+            "openclaw.json.last-good",
+            "jwt.json",
+            "update-check.json",
+        ]
+
+        print("\n--- Other Files ---")
+        for pattern in LOOSE_PATTERNS:
+            src = tmp / pattern
+            if src.exists():
+                dst = state_dir / pattern
+                if src.is_dir():
+                    copied, skipped = copy_directory(src, dst)
+                    summary["files_copied"] += copied
+                    summary["files_skipped"] += skipped
+                    print(f"  [{pattern}/] {copied} files")
+                else:
+                    if copy_file(src, dst):
+                        summary["files_copied"] += 1
+                        print(f"  [{pattern}] copied")
+
+        # Handle any remaining items not explicitly covered
+        handled = set(LOOSE_PATTERNS) | {"agents", "memory", "openclaw.json"}
+        for ws_name in summary["workspaces_restored"]:
+            handled.add(ws_name)
+
+        for item in sorted(tmp.iterdir()):
+            if item.name in handled:
+                continue
+            dst = state_dir / item.name
+            if item.is_dir():
+                copied, skipped = copy_directory(item, dst)
+                summary["files_copied"] += copied
+                summary["files_skipped"] += skipped
+                if copied > 0:
+                    print(f"  [{item.name}/] {copied} files")
+            else:
+                if copy_file(item, dst):
+                    summary["files_copied"] += 1
+                    print(f"  [{item.name}] copied")
+
+    # === Summary ===
+    print()
+    print("=" * 50)
+    print("Restore Complete")
+    print("=" * 50)
+    print(f"  Agents:      {', '.join(summary['agents_restored']) or 'none'}")
+    print(f"  Sessions:    {summary['sessions_merged']} from backup ({summary['sessions_total']} total)")
+    print(f"  Workspaces:  {', '.join(summary['workspaces_restored']) or 'none'}")
+    print(f"  Files:       {summary['files_copied']} copied, {summary['files_skipped']} skipped")
+    print()
+
+    # Touch config to trigger chokidar-based hot reload
+    config_target = state_dir / "openclaw.json"
+    if config_target.exists():
+        os.utime(config_target, None)
+        print("Config updated. SophClaw will auto-reload within a few seconds.")
+        print("Refresh your browser page to see the restored state.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/sophclaw-skill-creator/skill.json

@@ -1,10 +1,21 @@
 {
   "name": "sophclaw-skill-creator",
-  "version": "1.0.0",
-  "types": ["store"],
+  "version": "1.1.0",
+  "types": ["private"],
   "displayName": "Skill 创建向导",
-  "description": "在 SophClaw 仓库中交互式创建符合规范的 Skill，三步流程：需求对齐→方案对齐→生成代码",
+  "description": "在 SophClaw 仓库中创建/修改 Skill 或为已有 Skill 补全 design.md。两条路径：路径 A（创建/修改）三步流程：需求对齐→方案对齐→生成代码；路径 B（补全 design.md）五步流程：确定目标→阅读代码→逆向整理→逐节确认→写入文档",
   "changelog": [
+    {
+      "version": "1.1.0",
+      "date": "2026-05-28",
+      "changes": [
+        "新增路径 B：为已有 skill 补全 design.md（五步流程：确定目标→阅读代码→逆向整理→逐节确认→写入文档）",
+        "SKILL.md 拆分为入口+分流，路径 A/B 详细步骤拆分到 references/path-a-create.md 和 references/path-b-backfill.md",
+        "新增 <skills_dir> 自动定位机制，支持 workspace root 为 sophclaw-skills/ 或上级目录",
+        "路径 A 新增复用检查步骤：遍历已有 skill 发现可复用代码",
+        "generate.py 新增 --output-dir 参数，支持指定输出目录"
+      ]
+    },
     {
       "version": "1.0.0",
       "date": "2026-05-25",
@@ -14,5 +25,5 @@
     }
   ],
   "createdAt": "2026-05-25",
-  "updatedAt": "2026-05-25"
+  "updatedAt": "2026-05-28"
 }

package/skills/sophclaw-skill-creator/src/SKILL.md

@@ -1,205 +1,41 @@
 ---
 name: sophclaw-skill-creator
-description: 在 SophClaw 仓库中创建新 skill。当用户说"创建skill""新建skill""开发一个skill""帮我做一个skill"时使用。三步流程：需求对齐→方案对齐→生成代码。
+description: 在 SophClaw 仓库中创建新 skill / 修改已有 skill / 为已有 skill 补全 design.md。当用户说"创建skill""新建skill""开发一个skill""帮我做一个skill""修改skill""补充design.md""补全设计文档"时使用。
 ---
 
 # SophClaw Skill Creator
 
-在 SophClaw 仓库中交互式创建符合规范的 skill。
+在 SophClaw 仓库中交互式创建或维护 skill。
 
-## 流程
+## 定位 skills 目录
 
-```dot
-digraph skill_create {
-    rankdir=TB;
-
-    start [label="用户请求创建 skill", shape=oval];
-    step1 [label="第一步：需求对齐\n自适应提问，明确需求", shape=box];
-    spec1 [label="产出 design.md「需求说明」", shape=box];
-    user_ok1 [label="用户确认？", shape=diamond];
-    step2 [label="第二步：方案对齐\n设计结构 + 打磨 description", shape=box];
-    spec2 [label="产出 design.md「方案设计」+「测试用例」", shape=box];
-    user_ok2 [label="用户确认？", shape=diamond];
-    step3 [label="第三步：生成代码\ngenerate.py 生成骨架", shape=box];
-    edit [label="用户编辑 SKILL.md", shape=box];
-    validate [label="validate.py 校验", shape=box];
-    check [label="有 ERROR？", shape=diamond];
-    done [label="完成 ✅", shape=oval];
-
-    start -> step1;
-    step1 -> spec1;
-    spec1 -> user_ok1;
-    user_ok1 -> step1 [label="否，修改"];
-    user_ok1 -> step2 [label="是"];
-    step2 -> spec2;
-    spec2 -> user_ok2;
-    user_ok2 -> step2 [label="否，修改"];
-    user_ok2 -> step3 [label="是"];
-    step3 -> edit;
-    edit -> validate;
-    validate -> check;
-    check -> edit [label="是，修复"];
-    check -> done [label="否"];
-}
-```
-
-## 第一步：需求对齐
-
-自适应提问，帮用户把 skill 想清楚。每次只问一个问题，多问"为什么"。至少覆盖：
-
-1. **功能**：这个 skill 做什么？输入是什么？输出是什么？
-2. **触发场景**：用户会怎么说话来触发它？（这是 description 的核心素材）
-3. **上线平台**：确定 type，按以下决策树选择：
-
-```dot
-digraph type_select {
-    rankdir=TB;
-
-    q1 [label="用户能自己安装？", shape=diamond];
-    q2 [label="默认所有用户可见？", shape=diamond];
-    q3 [label="已确定长期维护？", shape=diamond];
-
-    store [label="store\n商店可安装\n需中文 displayName/description", shape=box];
-    builtin [label="builtin\n系统内置，默认可用", shape=box];
-    private [label="private\n内部使用，CLI 不可见", shape=box];
-    tmp [label="tmp\n临时/未分类，CLI 不可见", shape=box];
-
-    q1 -> q2 [label="否"];
-    q1 -> store [label="是"];
-    q2 -> builtin [label="是"];
-    q2 -> q3 [label="否"];
-    q3 -> private [label="是"];
-    q3 -> tmp [label="否/不确定"];
-}
-```
-
-- `store`：**必须**有中文 displayName 和 description
-- `private` / `tmp`：CLI list/download 不可见
-4. **是否需要脚本**：涉及 API 调用？复杂数据处理？还是纯指令型的 SKILL.md 就够？
-5. **是否需要 references/assets**：有大量参考文档？有模板文件？
-
-确认需求后，产出 `design.md` 的「需求说明」部分，格式：
-
-```markdown
-# <skill-name> 设计文档
-
-## 一、需求说明
-- 功能描述
-- 触发场景（用户怎么说话会触发）
-- 输入/输出约定
-- 上线平台及 type 选择理由
-```
-
-用户确认后进入下一步。
-
-## 第二步：方案对齐
-
-基于需求，设计 skill 结构。重点：
-
-### 目录结构设计
-
-讨论并确定需要哪些资源目录（scripts/references/assets），产出目录树。
-
-### description 打磨（核心）
-
-这是最容易出问题的地方。**description 是 LLM 匹配 skill 的唯一依据**，必须包含功能+触发场景。
-
-**公式**：`功能 + 触发场景 = 好的 description`
-
-正例：
-```yaml
-description: 压缩 PNG/JPEG 图片。当用户要求压缩图片、减小图片体积、优化图片大小时使用。
-```
-
-反例：
-```yaml
-# ❌ 太长，没有触发场景
-description: 这是一个功能强大的图片处理工具，支持多种格式的压缩、旋转、裁剪、滤镜等操作
-
-# ❌ 只写了功能，没写何时触发
-description: 图片压缩工具
-
-# ❌ 写了实现细节
-description: 使用 Pillow 库对图片进行有损压缩，支持调整质量和尺寸
-```
-
-**与用户协作打磨**：如果用户给的 description 太长或缺少触发场景，指出问题并帮助精简。
-
-### 方案产出
-
-在 `design.md` 中追加「方案设计」和「测试用例」：
-
-```markdown
-## 二、方案设计
-- 目录结构
-- 是否需要脚本及理由
-- SKILL.md 关键设计决策
-- 注意事项
-
-## 三、测试用例
-| 编号 | 测试场景 | 触发语句 | 预期匹配 | 预期行为 | 预期输出 |
-```
-
-测试用例至少覆盖：正常场景、不触发场景、边界场景。
-
-用户确认后进入下一步。
-
-## 第三步：生成代码
-
-### 生成骨架
+触发后，先确定 sophclaw-skills 仓库的 skills 目录位置：
 
 ```bash
-uv run {baseDir}/scripts/generate.py \
-  --name <skill-name> \
-  --type <builtin|store|private|tmp> \
-  --display-name <中文名称> \
-  --skill-description <中文描述> \
-  --resources scripts,references,assets
+# 检查常见路径
+ls skills/ 2>/dev/null && echo "FOUND:skills/" || echo "NOT_FOUND:skills/"
+ls sophclaw-skills/skills/ 2>/dev/null && echo "FOUND:sophclaw-skills/skills/" || echo "NOT_FOUND:sophclaw-skills/skills/"
 ```
 
-- `--display-name` 和 `--skill-description`：store 类型必填
-- `--resources`：可选，逗号分隔，按需创建
+- 如果 `skills/` 存在且有 skill.json 文件 → 说明用户直接打开了 `sophclaw-skills/` 作为 workspace root
+- 如果 `sophclaw-skills/skills/` 存在 → 说明用户打开了上一级目录
+- 都不存在 → 请用户提供 skills 目录的绝对路径，赋给 `<skills_dir>`
 
-### 用户编辑
+后续所有操作中，用 `<skills_dir>` 指代这个路径。以下路径中的 `<skills_dir>` 均需替换为实际路径。
 
-生成后提醒用户编辑 `src/SKILL.md` 填充具体内容。编辑注意事项：
-- description 已在第二步打磨好，直接填入 frontmatter
-- 路径用 `{baseDir}/scripts/xxx.py`（不含 `src/`）
-- 命令示范用 `uv run`，不用 `python`
-- 不提及其他 skill
-- 不写实现细节
+## 路径选择
 
-### 校验
+触发后先判断用户意图，分流到对应路径：
 
-```bash
-uv run {baseDir}/scripts/validate.py skills/<skill-name>
-```
-
-```dot
-digraph validate_loop {
-    rankdir=TB;
-
-    run [label="运行 validate.py", shape=box];
-    has_err [label="有 ERROR？", shape=diamond];
-    has_warn [label="有 WARNING？", shape=diamond];
-    fix_err [label="修复 ERROR（必须）", shape=box];
-    review [label="审视 WARNING\n决定是否修改", shape=box];
-    done [label="通过 ✅", shape=oval];
-
-    run -> has_err;
-    has_err -> fix_err [label="是"];
-    fix_err -> run [label="重新校验"];
-    has_err -> has_warn [label="否"];
-    has_warn -> review [label="是"];
-    review -> run [label="修改后重新校验"];
-    has_warn -> done [label="否"];
-}
-```
+| 用户意图 | 关键词 | 走哪条路径 |
+|---------|--------|-----------|
+| 创建新 skill / 修改已有 skill | "创建skill""新建skill""开发skill""修改skill" | 路径 A |
+| 为已有 skill 补全 design.md | "补充design.md""补全设计文档" | 路径 B |
 
-- **ERROR**：结构问题，必须修复（skill.json 缺失、name 不一致、store 缺少中文名等）
-- **WARNING**：内容建议，建议审视修改（description 偏长、路径含 src/、用了 python 而非 uv run 等）
+- **路径 A（创建/修改 skill）**：需求对齐 → 方案对齐 → 生成代码。详见 [references/path-a-create.md](references/path-a-create.md)
+- **路径 B（补全 design.md）**：阅读代码 → 逆向整理 → 逐节确认 → 写入文档。详见 [references/path-b-backfill.md](references/path-b-backfill.md)
 
-STATUS=succeeded 当且仅当无 ERROR。
+确定路径后，**只读取对应路径的 reference 文件**，不要把另一条路径加载到上下文。
 
 ## 关键规范速查
 

package/skills/sophclaw-skill-creator/src/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
 name = "sophclaw-skill-creator"
-version = "1.0.0"
+version = "1.1.0"
 description = "Interactive skill creation wizard for SophClaw repository"
 requires-python = ">=3.8"

package/skills/sophclaw-skill-creator/src/references/path-a-create.md

@@ -0,0 +1,208 @@
+# SophClaw Skill Creator — 路径 A：创建新 skill / 修改已有 skill
+
+适用于 skill 不存在或需要改动 skill 本身（代码、配置、SKILL.md）。
+
+三步流程：需求对齐 → 方案对齐 → 生成代码。
+
+```dot
+digraph skill_create {
+    rankdir=TB;
+
+    start [label="用户请求创建/修改 skill", shape=oval];
+    step1 [label="第一步：需求对齐\n自适应提问，明确需求", shape=box];
+    spec1 [label="产出 design.md「需求说明」", shape=box];
+    user_ok1 [label="用户确认？", shape=diamond];
+    step2 [label="第二步：方案对齐\n设计结构 + 打磨 description", shape=box];
+    spec2 [label="产出 design.md「方案设计」+「测试用例」", shape=box];
+    user_ok2 [label="用户确认？", shape=diamond];
+    step3 [label="第三步：生成代码\ngenerate.py 生成骨架", shape=box];
+    edit [label="用户编辑 SKILL.md", shape=box];
+    validate [label="validate.py 校验", shape=box];
+    check [label="有 ERROR？", shape=diamond];
+    done [label="完成 ✅", shape=oval];
+
+    start -> step1;
+    step1 -> spec1;
+    spec1 -> user_ok1;
+    user_ok1 -> step1 [label="否，修改"];
+    user_ok1 -> step2 [label="是"];
+    step2 -> spec2;
+    spec2 -> user_ok2;
+    user_ok2 -> step2 [label="否，修改"];
+    user_ok2 -> step3 [label="是"];
+    step3 -> edit;
+    edit -> validate;
+    validate -> check;
+    check -> edit [label="是，修复"];
+    check -> done [label="否"];
+}
+```
+
+## 第一步：需求对齐
+
+自适应提问，帮用户把 skill 想清楚。每次只问一个问题，多问"为什么"。至少覆盖：
+
+1. **功能**：这个 skill 做什么？输入是什么？输出是什么？
+2. **触发场景**：用户会怎么说话来触发它？（这是 description 的核心素材）
+3. **上线平台**：确定 type，按以下决策树选择：
+
+```dot
+digraph type_select {
+    rankdir=TB;
+
+    q1 [label="用户能自己安装？", shape=diamond];
+    q2 [label="默认所有用户可见？", shape=diamond];
+    q3 [label="已确定长期维护？", shape=diamond];
+
+    store [label="store\n商店可安装\n需中文 displayName/description", shape=box];
+    builtin [label="builtin\n系统内置，默认可用", shape=box];
+    private [label="private\n内部使用，CLI 不可见", shape=box];
+    tmp [label="tmp\n临时/未分类，CLI 不可见", shape=box];
+
+    q1 -> q2 [label="否"];
+    q1 -> store [label="是"];
+    q2 -> builtin [label="是"];
+    q2 -> q3 [label="否"];
+    q3 -> private [label="是"];
+    q3 -> tmp [label="否/不确定"];
+}
+```
+
+- `store`：**必须**有中文 displayName 和 description
+- `private` / `tmp`：CLI list/download 不可见
+4. **是否需要脚本**：涉及 API 调用？复杂数据处理？还是纯指令型的 SKILL.md 就够？
+5. **是否需要 references/assets**：有大量参考文档？有模板文件？
+
+确认需求后，产出 `design.md` 的「需求说明」部分，格式：
+
+```markdown
+# <skill-name> 设计文档
+
+## 一、需求说明
+- 功能描述
+- 触发场景（用户怎么说话会触发）
+- 输入/输出约定
+- 上线平台及 type 选择理由
+```
+
+用户确认后进入下一步。
+
+## 第二步：方案对齐
+
+基于需求，设计 skill 结构。重点：
+
+### 复用检查（先做，避免重复造轮子）
+
+在讨论具体方案之前，先检查已有 skill 是否有可复用的代码或模式：
+
+1. **完整读取已有 skill**：遍历 `<skills_dir>/` 下所有子目录，读取每个 skill 的全部文件（skill.json、SKILL.md、scripts/ 下的脚本）
+2. **判断复用价值**：根据第一步确认的需求，找出哪些 skill 的代码或设计模式可以复用（如 API 调用封装、输出格式、错误处理、目录结构等）
+3. **向用户呈现**：列出可复用的 skill 及具体复用点，问用户是否采纳
+
+> **为什么先做复用检查？** 仓库里已有数十个 skill，很多基础能力已有成熟的实现。直接复用可以减少代码量、保持风格一致、避免引入新的 bug 模式。
+
+### 目录结构设计
+
+讨论并确定需要哪些资源目录（scripts/references/assets），产出目录树。
+
+### description 打磨（核心）
+
+这是最容易出问题的地方。**description 是 LLM 匹配 skill 的唯一依据**，必须包含功能+触发场景。
+
+**公式**：`功能 + 触发场景 = 好的 description`
+
+正例：
+```yaml
+description: 压缩 PNG/JPEG 图片。当用户要求压缩图片、减小图片体积、优化图片大小时使用。
+```
+
+反例：
+```yaml
+# ❌ 太长，没有触发场景
+description: 这是一个功能强大的图片处理工具，支持多种格式的压缩、旋转、裁剪、滤镜等操作
+
+# ❌ 只写了功能，没写何时触发
+description: 图片压缩工具
+
+# ❌ 写了实现细节
+description: 使用 Pillow 库对图片进行有损压缩，支持调整质量和尺寸
+```
+
+**与用户协作打磨**：如果用户给的 description 太长或缺少触发场景，指出问题并帮助精简。
+
+### 方案产出
+
+在 `design.md` 中追加「方案设计」和「测试用例」：
+
+```markdown
+## 二、方案设计
+- 目录结构
+- 是否需要脚本及理由
+- SKILL.md 关键设计决策
+- 注意事项
+
+## 三、测试用例
+| 编号 | 测试场景 | 触发语句 | 预期匹配 | 预期行为 | 预期输出 |
+```
+
+测试用例至少覆盖：正常场景、不触发场景、边界场景。
+
+用户确认后进入下一步。
+
+## 第三步：生成代码
+
+### 生成骨架
+
+```bash
+uv run {baseDir}/scripts/generate.py \
+  --name <skill-name> \
+  --type <builtin|store|private|tmp> \
+  --display-name <中文名称> \
+  --skill-description <中文描述> \
+  --resources scripts,references,assets \
+  --output-dir <skills_dir>
+```
+
+- `--display-name` 和 `--skill-description`：store 类型必填
+- `--resources`：可选，逗号分隔，按需创建
+
+### 用户编辑
+
+生成后提醒用户编辑 `src/SKILL.md` 填充具体内容。编辑注意事项：
+- description 已在第二步打磨好，直接填入 frontmatter
+- 路径用 `{baseDir}/scripts/xxx.py`（不含 `src/`）
+- 命令示范用 `uv run`，不用 `python`
+- 不提及其他 skill
+- 不写实现细节
+
+### 校验
+
+```bash
+uv run {baseDir}/scripts/validate.py <skills_dir>/<skill-name>
+```
+
+```dot
+digraph validate_loop {
+    rankdir=TB;
+
+    run [label="运行 validate.py", shape=box];
+    has_err [label="有 ERROR？", shape=diamond];
+    has_warn [label="有 WARNING？", shape=diamond];
+    fix_err [label="修复 ERROR（必须）", shape=box];
+    review [label="审视 WARNING\n决定是否修改", shape=box];
+    done [label="通过 ✅", shape=oval];
+
+    run -> has_err;
+    has_err -> fix_err [label="是"];
+    fix_err -> run [label="重新校验"];
+    has_err -> has_warn [label="否"];
+    has_warn -> review [label="是"];
+    review -> run [label="修改后重新校验"];
+    has_warn -> done [label="否"];
+}
+```
+
+- **ERROR**：结构问题，必须修复（skill.json 缺失、name 不一致、store 缺少中文名等）
+- **WARNING**：内容建议，建议审视修改（description 偏长、路径含 src/、用了 python 而非 uv run 等）
+
+STATUS=succeeded 当且仅当无 ERROR。

package/skills/sophclaw-skill-creator/src/references/path-b-backfill.md

@@ -0,0 +1,111 @@
+# SophClaw Skill Creator — 路径 B：补全 design.md
+
+从已有代码逆向分析，为缺少 `design.md` 的 skill 补全设计文档。
+
+流程：逆向分析 → 对齐确认 → 生成文档。
+
+```dot
+digraph design_backfill {
+    rankdir=TB;
+
+    start [label="用户要求补全 design.md", shape=oval];
+    identify [label="第一步：确定目标 skill\n确认 skill 名称", shape=box];
+    read [label="第二步：阅读已有代码\nskill.json + SKILL.md + 脚本 + 资源", shape=box];
+    draft [label="第三步：逆向整理\n从代码中还原需求和方案", shape=box];
+    discuss [label="第四步：逐节确认\n与用户对齐理解", shape=box];
+    write [label="第五步：写入 design.md", shape=box];
+    done [label="完成 ✅", shape=oval];
+
+    start -> identify;
+    identify -> read;
+    read -> draft;
+    draft -> discuss;
+    discuss -> draft [label="用户纠正/补充"];
+    discuss -> write [label="用户确认"];
+    write -> done;
+}
+```
+
+## 第一步：确定目标 skill
+
+用户可能说"给 restore-state 补一个 design.md"、"补充 XXX 的设计文档"。先确认：
+
+1. skill 名称是什么？
+2. 确认路径 `<skills_dir>/<name>/` 存在（用 `ls <skills_dir>/<name>/` 验证）
+3. 确认 `design.md` 确实不存在（不覆盖已有文件）
+
+## 第二步：阅读已有代码
+
+完整读取目标 skill 的以下文件：
+
+| 文件 | 获取什么信息 |
+|------|-------------|
+| `<skills_dir>/<name>/skill.json` | name、version、types、displayName、description、changelog |
+| `<skills_dir>/<name>/src/SKILL.md` | 触发描述、前置检查、用法、输出格式、异常处理 |
+| `<skills_dir>/<name>/src/scripts/*.py` | 核心逻辑、关键设计决策、配置常量 |
+| `<skills_dir>/<name>/src/pyproject.toml` | 依赖、Python 版本要求 |
+| `<skills_dir>/<name>/src/references/*` | 参考文档 |
+| `<skills_dir>/<name>/src/assets/*` | 模板/资源文件 |
+
+**这一步不问用户任何问题**，全靠阅读代码收集信息。
+
+## 第三步：逆向整理
+
+从代码中还原设计文档所需的内容：
+
+**还原需求说明**（从 skill.json + SKILL.md）：
+- 功能描述 ← SKILL.md 的功能说明
+- 触发场景 ← SKILL.md 的 description + 触发条件描述
+- 输入/输出约定 ← SKILL.md 的输入输出描述 + 脚本的 exit code 逻辑
+
+**还原方案设计**（从脚本代码 + 目录结构）：
+- 目录结构 ← `ls` 查看实际文件树
+- 是否需要脚本及理由 ← 存在 `src/scripts/` 则"需要"
+- SKILL.md 关键设计决策 ← 代码中的硬编码常量、特殊处理逻辑、注释说明
+- 注意事项 ← SKILL.md 的异常处理表 + 脚本的错误分支
+
+**还原测试用例**（从 SKILL.md 的异常处理表 + 脚本边界逻辑）：
+- 正常场景 ← SKILL.md 的用法示例
+- 异常场景 ← SKILL.md 的异常处理表 + 脚本中的错误处理分支
+- 不触发场景 ← 从 description 反推边界（相近但不应触发的场景，如"备份数据"对 restore-state）
+
+## 第四步：逐节确认
+
+将整理好的内容分节呈现给用户，每节确认后再继续下一节：
+
+1. 先呈现「需求说明」，问："功能描述和触发场景我整理得对吗？有没有遗漏或需要补充的？"
+2. 再呈现「方案设计」，问："架构和关键设计决策我理解得对吗？"
+3. 最后呈现「测试用例」，问："测试用例是否完整？是否需要增删？"
+
+**与路径A的共同点**：都需要与用户对齐，确保理解正确。
+**与路径A的不同点**：这里是先基于代码给出初步判断再确认，而非从零开始提问。
+
+## 第五步：写入 design.md
+
+用户逐节确认后，写入 `<skills_dir>/<name>/design.md`。
+
+**格式严格遵循** [references/skill-notes.md](references/skill-notes.md) **§十「design.md 规范」**：
+
+```markdown
+# <skill-name> 设计文档
+
+## 一、需求说明
+- 功能描述
+- 触发场景（用户怎么说话会触发）
+- 输入/输出约定
+- 上线平台及 type 选择理由
+
+## 二、方案设计
+- 目录结构
+- 是否需要脚本及理由
+- SKILL.md 关键设计决策
+- 注意事项
+
+## 三、测试用例
+| 编号 | 测试场景 | 触发语句 | 预期匹配 | 预期行为 | 预期输出 |
+```
+
+**补充说明**（在规范结构基础上可酌情扩充）：
+- 「需求说明」可追加"核心能力""不触发场景"小节，帮助完善边界描述
+- 「方案设计」可追加"架构""职责划分"小节，补充架构图和组件分工表
+- 以上为可选扩充，规范中的 4 个要点和表头必须保留

package/skills/sophclaw-skill-creator/src/scripts/generate.py

@@ -127,12 +127,13 @@ def parse_resources(raw_resources):
     return deduped, ""
 
 
-def generate_skill(skill_name, skill_type, display_name, skill_description, resources):
+def generate_skill(skill_name, skill_type, display_name, skill_description, resources, output_dir=None):
     """Create the full skill directory structure."""
     today = date.today().isoformat()
     skill_title = title_case_skill_name(skill_name)
 
-    skill_dir = Path.cwd() / "skills" / skill_name
+    base = Path(output_dir) if output_dir else Path.cwd() / "skills"
+    skill_dir = base / skill_name
     src_dir = skill_dir / "src"
 
     # Check for existing directory
@@ -209,6 +210,7 @@ def main():
     parser.add_argument("--display-name", default="", help="Chinese display name (required for store)")
     parser.add_argument("--skill-description", default="", help="Chinese description (required for store)")
     parser.add_argument("--resources", default="", help="Comma-separated: scripts,references,assets")
+    parser.add_argument("--output-dir", default="", help="Output directory for the skill (defaults to ./skills/)")
     args = parser.parse_args()
 
     # Validate name
@@ -252,6 +254,7 @@ def main():
         display_name=args.display_name.strip(),
         skill_description=args.skill_description.strip(),
         resources=resources,
+        output_dir=args.output_dir.strip() or None,
     )
 
     if not success: