foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/skills/archive.py

@@ -0,0 +1,111 @@
+"""技能包归档读取:zip / tar.gz 统一「按名读」,不落盘、不 extractall。
+
+`markdown_skill.extract_skill_package` 只认 zip,而 ClawHub 发 zip、GitHub 发 tar.gz。
+两者共用同一套规则:拒路径穿越、限解压总量(防 zip bomb)、挑**最浅**的 SKILL.md
+(GitHub 仓库里它常埋在 `skills/<name>/` 多级子目录下)。
+"""
+from __future__ import annotations
+
+import io
+import json
+import tarfile
+import zipfile
+
+MAX_TOTAL = 8 * 1024 * 1024
+
+_CODE_EXT = (".py", ".sh", ".bash", ".ps1", ".js", ".mjs", ".cjs", ".ts",
+             ".rb", ".pl", ".bat", ".cmd", ".exe")
+
+
+class PackageError(ValueError):
+    """包不可用:格式坏 / 缺 SKILL.md / 超体积。"""
+
+
+def safe_name(name: str) -> bool:
+    """拒绝对路径、盘符与 `..` 段。按名读虽不落盘,但脏名字会流进日志与提示词。"""
+    n = (name or "").replace("\\", "/")
+    while n.startswith("./"):
+        n = n[2:]
+    if not n or n.startswith("/") or ".." in n.split("/"):
+        return False
+    return not (len(n) > 1 and n[1] == ":")
+
+
+def _shallowest(names: list[str], base: str, subpath: str = "") -> str | None:
+    """挑最浅的同名文件(全小写比较)。subpath 非空时只在其下找。"""
+    want = f"/{subpath.strip('/')}/" if subpath.strip("/") else ""
+    cands = [
+        n for n in names
+        if safe_name(n)
+        and n.rsplit("/", 1)[-1].lower() == base
+        and (not want or want in f"/{n}")
+    ]
+    if not cands:
+        return None
+    return min(cands, key=lambda n: (n.count("/"), len(n)))
+
+
+def pick_skill_md(names: list[str], subpath: str = "") -> str | None:
+    """挑最浅的 SKILL.md:ClawHub 在根,GitHub 仓库常在 skills/<name>/ 下。"""
+    return _shallowest(names, "skill.md", subpath)
+
+
+def has_code(files: list[str]) -> bool:
+    """包内是否带可执行脚本 / 独立的 scripts/ 目录。"""
+    for n in files:
+        low = n.lower()
+        if low.endswith(_CODE_EXT) or "/scripts/" in f"/{low}":
+            return True
+    return False
+
+
+def read_package(data: bytes, subpath: str = "", max_total: int = MAX_TOTAL) -> dict:
+    """解一个技能包,返回 {files, skill_md, meta}。"""
+    if not data:
+        raise PackageError("空包")
+    if data[:2] == b"PK":
+        names, read = _open_zip(data, max_total)
+    else:
+        names, read = _open_tar(data, max_total)
+    md = pick_skill_md(names, subpath)
+    if md is None:
+        where = f"(子路径 {subpath} 下)" if subpath else ""
+        raise PackageError(f"包内未找到 SKILL.md{where}")
+    meta: dict = {}
+    meta_name = _shallowest(names, "_meta.json")
+    if meta_name:
+        try:
+            meta = json.loads(read(meta_name).decode("utf-8", "replace")) or {}
+        except Exception:
+            meta = {}
+    return {"files": names, "skill_md": read(md).decode("utf-8", "replace"), "meta": meta}
+
+
+def _open_zip(data: bytes, max_total: int):
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(data))
+    except Exception as e:
+        raise PackageError(f"zip 解析失败: {e}") from None
+    infos = [i for i in zf.infolist() if not i.is_dir()]
+    total = sum(i.file_size for i in infos)
+    if total > max_total:
+        raise PackageError(f"解压体积超上限({total} > {max_total})")
+    return [i.filename for i in infos], zf.read
+
+
+def _open_tar(data: bytes, max_total: int):
+    try:
+        tf = tarfile.open(fileobj=io.BytesIO(data), mode="r:*")
+        members = [m for m in tf.getmembers() if m.isfile()]
+    except Exception as e:
+        raise PackageError(f"既不是 zip 也不是 tar 包: {e}") from None
+    total = sum(m.size for m in members)
+    if total > max_total:
+        raise PackageError(f"解压体积超上限({total} > {max_total})")
+    by_name = {m.name: m for m in members}
+
+    def read(name: str) -> bytes:
+        fp = tf.extractfile(by_name[name])
+        return fp.read() if fp else b""
+
+    return [m.name for m in members], read

package/python/foxclaw/skills/fetch.py

@@ -0,0 +1,226 @@
+"""技能来源解析与下载:ClawHub / GitHub / http(s) 包地址 / 本地路径。
+
+`foxclaw skills install <ref>` 的统一入口。ref 形式:
+
+    @owner/slug                    ClawHub 作用域包(与 `openclaw skills install` 同源)
+    owner/slug                     同上,省略 @
+    github:owner/repo[/sub][@ref]  GitHub 仓库里的 SKILL.md(默认 HEAD)
+    https://...zip|tar.gz|.md      直接给包地址
+    ./skill.zip | ./SKILL.md       本地包 / 文件 / 目录
+
+安全口径:ClawHub 在**下载前**先查 moderation,`isMalwareBlocked` 直接拒绝;
+`isSuspicious` 只作告警交给调用方确认。包内带可执行脚本时标 `has_code` ——
+foxclaw 的 SKILL.md 是纯提示词,不执行包内代码,这点必须让调用方说清楚。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .archive import PackageError, has_code, read_package
+
+DEFAULT_REGISTRY = "https://clawhub.ai"
+MAX_BYTES = 10 * 1024 * 1024
+UA = "foxclaw-skills/1 (+https://github.com/snowfoxHQ/FoxClaw)"
+_ARCHIVE_EXT = (".zip", ".tar.gz", ".tgz", ".tar")
+_LOCAL_ID = re.compile(r"^@?([A-Za-z0-9][\w.-]*)/([\w.-]+)$")
+
+
+class HttpError(PackageError):
+    """远端返回非 2xx。status 保留下来供调用方区分 404(不存在)与其他错误。"""
+
+    def __init__(self, status: int, url: str, detail: str):
+        self.status = status
+        super().__init__(f"{url} 返回 {status}: {detail or '(无响应体)'}")
+
+
+class MalwareBlocked(PackageError):
+    """来源方已判定为恶意,任何 --yes 都不放行。"""
+
+
+@dataclass
+class SkillPackage:
+    skill_md: str
+    source: str
+    origin: str
+    files: list = field(default_factory=list)
+    meta: dict = field(default_factory=dict)
+    version: str = ""
+    moderation: dict = field(default_factory=dict)
+
+    @property
+    def has_code(self) -> bool:
+        return has_code(self.files)
+
+    @property
+    def suspicious(self) -> bool:
+        return bool(self.moderation.get("isSuspicious"))
+
+
+def registry() -> str:
+    """ClawHub 地址。内网镜像走 FOXCLAW_CLAWHUB_REGISTRY,别改代码。"""
+    return (os.environ.get("FOXCLAW_CLAWHUB_REGISTRY", "").strip()
+            or DEFAULT_REGISTRY).rstrip("/")
+
+
+def _http_get(url: str, timeout: float = 25.0,
+              max_bytes: int = MAX_BYTES) -> tuple[bytes, str]:
+    """GET 一个 URL,返回 (bytes, content-type)。超限/4xx 都抛 PackageError。"""
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            ctype = (resp.headers.get("Content-Type") or "").split(";")[0].lower()
+            chunks, total = [], 0
+            while True:
+                buf = resp.read(65536)
+                if not buf:
+                    break
+                total += len(buf)
+                if total > max_bytes:
+                    raise PackageError(f"下载超过上限({max_bytes} 字节): {url}")
+                chunks.append(buf)
+            return b"".join(chunks), ctype
+    except urllib.error.HTTPError as e:
+        detail = e.read(300).decode("utf-8", "replace").strip()
+        raise HttpError(e.code, url, detail) from None
+    except urllib.error.URLError as e:
+        raise PackageError(f"下载失败 {url}: {e.reason}") from None
+
+
+def _json_get(url: str, timeout: float = 25.0) -> dict:
+    raw, _ = _http_get(url, timeout)
+    try:
+        got = json.loads(raw.decode("utf-8", "replace"))
+    except Exception:
+        raise PackageError(f"{url} 返回的不是 JSON") from None
+    return got if isinstance(got, dict) else {}
+
+
+def fetch(ref: str, timeout: float = 25.0) -> SkillPackage:
+    """把一个 ref 解析成 SkillPackage(已下载并解出 SKILL.md)。"""
+    r = (ref or "").strip()
+    if not r:
+        raise PackageError("缺少 skill 来源")
+    low = r.lower()
+    if low.startswith(("http://", "https://")):
+        return _from_url(r, timeout)
+    if low.startswith("github:"):
+        return _from_github(r[len("github:"):], timeout)
+    local = Path(os.path.expanduser(r))
+    if local.exists():
+        return _from_local(local)
+    m = _LOCAL_ID.match(r)
+    if m:
+        return _from_clawhub(m.group(1), m.group(2), timeout)
+    raise PackageError(
+        "无法识别的来源。支持:@owner/slug(ClawHub)、github:owner/repo[/子路径][@ref]、"
+        "http(s):// 包地址、本地 .zip/.tar.gz/SKILL.md/目录")
+
+
+def _from_clawhub(owner: str, slug: str, timeout: float) -> SkillPackage:
+    """ClawHub:先查详情(拿版本 + 审核状态),再下载 zip。
+
+    先查详情而不是直接下载,是为了在落盘前拦住 `isMalwareBlocked` —— openclaw 自己
+    也把 moderation 摆在安装前的核验位置,我们不能比它更松。
+    """
+    base = registry()
+    q_slug = urllib.parse.quote(slug, safe="")
+    q_owner = urllib.parse.quote(owner, safe="")
+    try:
+        detail = _json_get(f"{base}/api/v1/skills/{q_slug}?ownerHandle={q_owner}", timeout)
+    except HttpError as e:
+        if e.status == 404:
+            raise PackageError(f"ClawHub 上找不到 @{owner}/{slug}") from None
+        raise
+    mod = detail.get("moderation") or {}
+    if mod.get("isMalwareBlocked"):
+        reason = mod.get("summary") or "来源方未给说明"
+        raise MalwareBlocked(f"@{owner}/{slug} 已被 ClawHub 判为恶意并拦截:{reason}")
+    version = str((detail.get("latestVersion") or {}).get("version") or "")
+    data, ctype = _http_get(
+        f"{base}/api/v1/download?slug={q_slug}&ownerHandle={q_owner}", timeout)
+    if data[:1] == b"{" or "json" in ctype:
+        try:
+            handoff = json.loads(data.decode("utf-8", "replace")) or {}
+        except Exception:
+            handoff = {}
+        archive = str(handoff.get("archiveUrl") or "")
+        if not archive:
+            raise PackageError(f"@{owner}/{slug} 无托管版本,且返回里没有可下载地址")
+        data, _ = _http_get(archive, timeout)
+    pkg = read_package(data)
+    return SkillPackage(
+        skill_md=pkg["skill_md"], source="clawhub",
+        origin=f"@{owner}/{slug}" + (f"@{version}" if version else ""),
+        files=pkg["files"], meta=pkg["meta"], version=version, moderation=mod)
+
+
+def _from_github(spec: str, timeout: float) -> SkillPackage:
+    """github:owner/repo[/子路径][@ref] → codeload 的 tar.gz(不占 GitHub API 配额)。"""
+    body, _, ref = spec.partition("@")
+    parts = [p for p in body.split("/") if p]
+    if len(parts) < 2:
+        raise PackageError("github: 形式应为 github:owner/repo[/子路径][@ref]")
+    owner, repo = parts[0], parts[1]
+    sub = "/".join(parts[2:])
+    url = f"https://codeload.github.com/{owner}/{repo}/tar.gz/{ref or 'HEAD'}"
+    data, _ = _http_get(url, timeout)
+    pkg = read_package(data, subpath=sub)
+    origin = f"github:{owner}/{repo}" + (f"/{sub}" if sub else "") + (f"@{ref}" if ref else "")
+    return SkillPackage(skill_md=pkg["skill_md"], source="github", origin=origin,
+                        files=pkg["files"], meta=pkg["meta"])
+
+
+def _from_url(url: str, timeout: float) -> SkillPackage:
+    """直链:归档当包解,markdown/纯文本当单文件 SKILL.md。"""
+    data, ctype = _http_get(url, timeout)
+    path = urllib.parse.urlparse(url).path.lower()
+    name = path.rsplit("/", 1)[-1] or "SKILL.md"
+    textish = path.endswith((".md", ".markdown")) or ctype in ("text/markdown", "text/plain")
+    is_archive = data[:2] == b"PK" or data[:2] == b"\x1f\x8b" or path.endswith(_ARCHIVE_EXT)
+    if textish and not is_archive:
+        text = data.decode("utf-8", "replace")
+        return SkillPackage(skill_md=text, source="url", origin=url, files=[name])
+    pkg = read_package(data)
+    return SkillPackage(skill_md=pkg["skill_md"], source="url", origin=url,
+                        files=pkg["files"], meta=pkg["meta"])
+
+
+def _from_local(path: Path) -> SkillPackage:
+    """本地:目录(找 SKILL.md)、单 .md、或 .zip/.tar.gz 包。"""
+    origin = str(path)
+    if path.is_dir():
+        direct = path / "SKILL.md"
+        if direct.is_file():
+            text = direct.read_text(encoding="utf-8", errors="replace")
+            meta = _read_meta(path / "_meta.json")
+        else:
+            cands = sorted(path.glob("*/SKILL.md")) + sorted(path.glob("*/*/SKILL.md"))
+            if len(cands) != 1:
+                raise PackageError(
+                    f"{path} 里没找到唯一的 SKILL.md(直接放 SKILL.md,或只有一个子目录带它)")
+            text = cands[0].read_text(encoding="utf-8", errors="replace")
+            meta = _read_meta(cands[0].parent / "_meta.json")
+        files = [p.relative_to(path).as_posix() for p in path.rglob("*") if p.is_file()]
+        return SkillPackage(skill_md=text, source="local", origin=origin,
+                            files=files, meta=meta)
+    if path.suffix.lower() in (".md", ".markdown"):
+        return SkillPackage(skill_md=path.read_text(encoding="utf-8", errors="replace"),
+                            source="local", origin=origin, files=[path.name])
+    pkg = read_package(path.read_bytes())
+    return SkillPackage(skill_md=pkg["skill_md"], source="local", origin=origin,
+                        files=pkg["files"], meta=pkg["meta"])
+
+
+def _read_meta(p: Path) -> dict:
+    try:
+        got = json.loads(p.read_text(encoding="utf-8"))
+        return got if isinstance(got, dict) else {}
+    except Exception:
+        return {}

package/python/foxclaw/skills/hooks_spec.py

@@ -13,60 +13,56 @@ Foxclaw — 标准生命周期钩子点 (Lifecycle Hooks Specification)
 """
 from __future__ import annotations
 
+from typing import Literal, cast
+
 
-# ── 标准钩子点(生命周期顺序)──────────────────────────────
 class Hooks:
     """标准钩子点常量。用 Hooks.BEFORE_TOOL_CALL 而非裸字符串,避免拼写错误。"""
 
-    # 会话级
-    SESSION_START = "session_start"     # 一次任务开始
-    AGENT_START = "agent_start"         # Agent 开始处理(分诊后)
-    AGENT_END = "agent_end"             # Agent 处理完成
-    SESSION_END = "session_end"         # 一次任务结束
+    SESSION_START = "session_start"
+    AGENT_START = "agent_start"
+    AGENT_END = "agent_end"
+    SESSION_END = "session_end"
 
-    # 工具/skill 级
-    BEFORE_TOOL_CALL = "before_tool_call"   # 调用前(可阻断/可改参数)
-    AFTER_TOOL_CALL = "after_tool_call"     # 调用成功后
-    ON_ERROR = "on_error"                   # 调用失败
-    ON_LOOP = "on_loop"                     # 检测到死循环
+    BEFORE_TOOL_CALL = "before_tool_call"
+    AFTER_TOOL_CALL = "after_tool_call"
+    ON_ERROR = "on_error"
+    ON_LOOP = "on_loop"
 
-    # 消息级
-    BEFORE_MESSAGE_WRITE = "before_message_write"   # 写入/发送消息前(可改写)
+    BEFORE_MESSAGE_WRITE = "before_message_write"
 
 
-# 所有标准钩子点(供校验)
 ALL_HOOKS = frozenset({
     Hooks.SESSION_START, Hooks.AGENT_START, Hooks.AGENT_END, Hooks.SESSION_END,
     Hooks.BEFORE_TOOL_CALL, Hooks.AFTER_TOOL_CALL, Hooks.ON_ERROR, Hooks.ON_LOOP,
     Hooks.BEFORE_MESSAGE_WRITE,
 })
 
-# 拥有阻断权的钩子(只有这些返回 {block:True} 才生效)
 BLOCKING_HOOKS = frozenset({Hooks.BEFORE_TOOL_CALL})
 
-# 可注入 additionalContext 的钩子(E2:非阻断,但其返回的 additional_context 会被并入推理上下文)。
-# agent_start = 一次 Agent 任务的推理开始点,对应范式 pre_reasoning —— 推理前注入上下文的落点。
 CONTEXT_HOOKS = frozenset({Hooks.AGENT_START})
 
-# 工具级钩子(按 skill_id 做 matcher 过滤)
 TOOL_SCOPED_HOOKS = frozenset({
     Hooks.BEFORE_TOOL_CALL, Hooks.AFTER_TOOL_CALL, Hooks.ON_ERROR, Hooks.ON_LOOP,
 })
 
-# 向后兼容 + 语义别名 → 标准名
 ALIAS = {
     "pre_skill": Hooks.BEFORE_TOOL_CALL,
     "post_skill": Hooks.AFTER_TOOL_CALL,
-    # E2:推理层/会话层语义名(对齐范式 pre_reasoning / Stop),规整到已有的会话级钩子点——
-    # 顺带**复活**此前定义却从未被 fire 的 agent_start / agent_end 孤儿钩子。
-    "pre_reasoning": Hooks.AGENT_START,   # 一次 Agent 任务推理开始前(可注入 additionalContext)
-    "task_complete": Hooks.AGENT_END,     # 一次 Agent 任务结束后(只读观测/上报,对应范式 Stop)
+    "pre_reasoning": Hooks.AGENT_START,
+    "task_complete": Hooks.AGENT_END,
 }
 
 
-def normalize_hook(event: str) -> str:
+HookEvent = Literal["before_tool_call", "after_tool_call", "on_error", "on_loop",
+                    "session_start", "agent_start", "agent_end", "session_end",
+                    "before_message_write",
+                    "pre_skill", "post_skill", "pre_reasoning", "task_complete"]
+
+
+def normalize_hook(event: str) -> HookEvent:
     """把旧钩子名规整为标准名;已是标准名则原样返回。"""
-    return ALIAS.get(event, event)
+    return cast(HookEvent, ALIAS.get(event, event))
 
 
 def is_valid_hook(event: str) -> bool:

package/python/foxclaw/skills/install_cmd.py

@@ -0,0 +1,216 @@
+"""`foxclaw skills install|list|remove` 的实现。
+
+为什么不放在 cli.py:那里只该有参数解析与分发(体积门 15KB,且它已承载 serve/config)。
+装技能的真正复杂度在「服务在跑没跑」这一个分叉上:
+
+* **在跑** → 必须打 /api/ahs/md-skills。直接改 markdown_skills.json 会被运行中的
+  注册表下一次 `save()` 用内存快照整份覆盖,用户的安装无声消失(极难查)。
+* **没跑** → 直接写同一个 JSON,格式与 MarkdownStore 完全一致,下次启动即加载。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, cast
+
+
+def _data_dir() -> Path:
+    """与 `foxclaw serve` 同源:FOXCLAW_DATA_DIR,否则 cwd 下的 foxclaw_data。"""
+    raw = os.environ.get("FOXCLAW_DATA_DIR", "").strip()
+    return Path(raw or "./foxclaw_data").resolve()
+
+
+def _api_base() -> str:
+    """本地服务地址:FOXCLAW_API 可覆盖,否则回环 + FOXCLAW_PORT。"""
+    raw = os.environ.get("FOXCLAW_API", "").strip()
+    if raw:
+        return raw.rstrip("/")
+    port = os.environ.get("FOXCLAW_PORT", "").strip() or "8000"
+    return f"http://127.0.0.1:{port}"
+
+
+def _api_alive(base: str) -> bool:
+    try:
+        with urllib.request.urlopen(f"{base}/api/system/info", timeout=0.8) as r:
+            return 200 <= r.status < 300
+    except Exception:
+        return False
+
+
+def _api_json(base: str, method: str, path: str, payload: dict | None = None) -> dict:
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8") if payload is not None else None
+    headers = {"Content-Type": "application/json"}
+    key = os.environ.get("FOXCLAW_API_KEY", "").strip()
+    if key:
+        headers["X-API-Key"] = key
+    req = urllib.request.Request(f"{base}{path}", data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as r:
+            return json.loads(r.read().decode("utf-8", "replace") or "{}")
+    except urllib.error.HTTPError as e:
+        detail = e.read(400).decode("utf-8", "replace").strip()
+        raise RuntimeError(f"{method} {path} → {e.code}: {detail}") from None
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"连不上服务: {e.reason}") from None
+
+
+def _confirm() -> bool:
+    """非 TTY(管道/CI)一律不认,必须显式 --yes。"""
+    if not sys.stdin.isatty():
+        return False
+    try:
+        ans = input("安装后它会注入你 AI 的提示词、影响其行为。继续?[y/N] ")
+    except (EOFError, KeyboardInterrupt):
+        return False
+    return ans.strip().lower() in ("y", "yes")
+
+
+def _persist(skill, text: str) -> tuple[bool, str, bool]:
+    """落地一个指令技能。返回 (是否新建, 位置说明, 是否已热加载)。"""
+    base = _api_base()
+    if _api_alive(base):
+        got = _api_json(base, "POST", "/api/ahs/md-skills",
+                        {"content": text, "id": skill.id, "acknowledged": True})
+        return bool(got.get("created")), base, True
+    from .markdown_skill import MarkdownSkillRegistry
+    from .markdown_store import MarkdownStore
+
+    reg = MarkdownSkillRegistry()
+    store = MarkdownStore(_data_dir())
+    store.load(reg)
+    created = reg.get(skill.id) is None
+    reg.register(skill)
+    store.save(reg)
+    return created, str(_data_dir() / "markdown_skills.json"), False
+
+
+def install(args) -> int:
+    from .fetch import MalwareBlocked, PackageError, fetch
+    from .markdown_skill import parse_skill_md
+
+    try:
+        pkg = fetch(args.ref)
+    except MalwareBlocked as e:
+        print(f"拒绝安装:{e}", file=sys.stderr)
+        return 3
+    except PackageError as e:
+        print(f"获取失败:{e}", file=sys.stderr)
+        return 2
+    want_id = (args.id or "").strip() or str(pkg.meta.get("slug") or "")
+    try:
+        skill = parse_skill_md(pkg.skill_md, id=want_id or None)
+    except ValueError as e:
+        print(f"SKILL.md 解析失败:{e}", file=sys.stderr)
+        return 2
+    if pkg.version and not skill.version:
+        skill.version = pkg.version
+    if not args.json:
+        ver = f" v{skill.version}" if skill.version else ""
+        print(f"来源   {pkg.source} · {pkg.origin}")
+        print(f"技能   {skill.name}(id={skill.id}){ver}")
+        print(f"描述   {skill.description[:100]}")
+        if pkg.has_code:
+            print("注意   包内带可执行脚本。foxclaw 只注入 SKILL.md、不运行这些脚本;"
+                  "若正文要求 agent 去跑它们,该技能不会按预期工作。")
+        if pkg.suspicious:
+            print("警告   ClawHub 标记该技能可疑,请先读正文再决定。")
+    if not args.yes and not _confirm():
+        print("已取消:未确认。确认后加 --yes(或在本机终端里交互确认)。")
+        return 1
+    try:
+        created, where, hot = _persist(skill, pkg.skill_md)
+    except RuntimeError as e:
+        print(f"写入失败:{e}", file=sys.stderr)
+        return 4
+    if args.json:
+        print(json.dumps({"ok": True, "created": created, "skill": skill.to_meta(),
+                          "source": pkg.source, "origin": pkg.origin,
+                          "has_code": pkg.has_code, "where": where,
+                          "hot_loaded": hot}, ensure_ascii=False))
+        return 0
+    print(f"{'已安装' if created else '已更新'}「{skill.name}」→ {where}")
+    if not hot:
+        print("提示:服务若正在运行,重启一次才会加载;不想重启就先起服务再装。")
+    return 0
+
+
+def list_skills(args) -> int:
+    base = _api_base()
+    hot = _api_alive(base)
+    try:
+        if hot:
+            rows = _api_json(base, "GET", "/api/ahs/md-skills").get("skills") or []
+        else:
+            from .markdown_skill import MarkdownSkillRegistry
+            from .markdown_store import MarkdownStore
+
+            reg = MarkdownSkillRegistry()
+            MarkdownStore(_data_dir()).load(reg)
+            rows = reg.catalog()
+    except RuntimeError as e:
+        print(f"读取失败:{e}", file=sys.stderr)
+        return 4
+    if args.json:
+        print(json.dumps({"source": "api" if hot else "file", "skills": rows},
+                         ensure_ascii=False))
+        return 0
+    if not rows:
+        print("还没有安装指令技能。`foxclaw skills install @owner/slug` 装一个。")
+        return 0
+    for s in rows:
+        ver = f" v{s.get('version')}" if s.get("version") else ""
+        off = "" if s.get("enabled", True) else " [已停用]"
+        blocked = " [被封杀]" if s.get("blocked") else ""
+        print(f"{str(s.get('id', '')).ljust(26)} {str(s.get('source', '?')):8}{ver}{off}{blocked}")
+        print(f"  {str(s.get('description', ''))[:90]}")
+    return 0
+
+
+def remove(args) -> int:
+    sid = (args.id or "").strip()
+    if not sid:
+        print("要卸载哪个?`foxclaw skills list` 看 id。", file=sys.stderr)
+        return 2
+    base = _api_base()
+    if _api_alive(base):
+        try:
+            _api_json(base, "DELETE", f"/api/ahs/md-skills/{urllib.parse.quote(sid, safe='')}")
+        except RuntimeError as e:
+            print(f"卸载失败:{e}", file=sys.stderr)
+            return 4
+        print(f"已卸载 {sid}(服务已热更新)")
+        return 0
+    from .markdown_skill import MarkdownSkillRegistry
+    from .markdown_store import MarkdownStore
+
+    reg = MarkdownSkillRegistry()
+    store = MarkdownStore(_data_dir())
+    store.load(reg)
+    if not reg.unregister(sid):
+        print(f"没找到 id={sid} 的指令技能(`foxclaw skills list` 看现有)", file=sys.stderr)
+        return 1
+    store.save(reg)
+    print(f"已卸载 {sid} → {_data_dir() / 'markdown_skills.json'}")
+    return 0
+
+
+def run(args) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            cast(Any, stream).reconfigure(errors="replace")
+        except Exception:
+            pass
+    action = getattr(args, "skills_action", None)
+    if action == "install":
+        return install(args)
+    if action == "list":
+        return list_skills(args)
+    if action == "remove":
+        return remove(args)
+    print("用法:`foxclaw skills install <ref>` / `list` / `remove <id>`")
+    return 2