Skip to content

zjs105910/workbuddy-market / bundled/github-project-manager/skills/github-project-manager

github-project-manager

Verified

管理从 GitHub 下载到本机的开源项目与技能包:列出、扫描发现、安装前预检、检查更新、一键更新、移除、回滚、数据完整性校验与环境诊断。带 O_EXCL 原子锁 + 心跳租约、事务级失败回滚、InstallPlan 状态收敛、单次遍历的磁盘预检、批量更新复用远程信息(消灭 N+1 请求)、ZIP 预扫描与压缩炸弹/设备名双重防护、skill 冲突阻断、内容指纹校验、硬链接与 rename 两种备份介质。触发方式:/ghpm、『GitHub 项目管理』『检查插件更新』『更新开源项目』『我装了哪些 GitHub 项目』『这个插件有新版吗』『卸载插件』『这个仓库能装吗』『ghpm doctor』『ghpm verify』『文件丢了/装坏了』。

scripts/ghpm/commands/basic.py

View on GitHub
# -*- coding: utf-8 -*-
"""基础命令:list / unlock / rollback / doctor。"""
from __future__ import annotations

import json
import os
import shutil
import sys
import time
from pathlib import Path

from .. import config
from ..errors import E_LOCKED, E_UNSAFE_PATH, E_WRITE, UnsafePathError
from ..lock import (acquire_lock, lock_heartbeat_age, pid_alive, read_lock,
                    release_lock)
from ..pathguard import validate_managed_path
from ..registry import load, migrate_registry
from ..remote import _http_code
from ..transaction import restore_backup
from ..util import (disk_free_bytes, emit, fmt_ts, format_bytes, path_size_bytes, run)


def cmd_list(args):
    data = load()
    ps = data["projects"]
    if args.json:
        print(json.dumps(data, ensure_ascii=False))
        return
    if not ps:
        print("清单为空。用 `ghpm add <repo>` 添加,或 `ghpm scan` 自动发现。")
        return
    print("共 %d 个受管项目\n" % len(ps))
    for p in ps:
        print("  %-24s %-38s %s" % (p.get("name", "?"), p.get("repo", "?"),
                                    p.get("sha_short", "-")))
        if p.get("desc"):
            print("      %s" % p["desc"])
        if p.get("skill_names"):
            print("      skills: %s" % ", ".join(p["skill_names"]))
        print("      安装 %s  版本更新 %s  最近检查 %s"
              % (fmt_ts(p.get("installed_at")), fmt_ts(p.get("updated_at")),
                 fmt_ts(p.get("checked_at"))))
        print()


# ---------- unlock ----------

def cmd_unlock(args):
    """清锁。v2 是无条件 unlink —— 那会绕过 token 锁,把正在写盘的进程的锁
    直接抹掉,让第二个进程并发写 skills。这里改成先确认持有者是否还活着。

    v4 起判定多了一层租约:连进程都查不出来(tasklist 缺失 / 无权限)时,
    心跳还新的锁同样拒绝清除 —— 拿不准就不要动。
    """
    from ..lock import _lock_path, lock_is_stale
    force = bool(getattr(args, "force", False))
    lock = _lock_path()
    if not lock.exists():
        print("当前没有锁")
        return
    st = read_lock()
    if not st:
        try:
            lock.unlink()
            print("锁文件内容无法解析(不是有效锁),已清除")
        except Exception as e:
            print("删除锁文件失败:%s" % e)
        return

    pid = st.get("pid")
    alive = pid_alive(pid)
    hb = lock_heartbeat_age(st, None)
    if alive is True and not force:
        emit("failed", "锁仍被占用,拒绝清除", percent=100, code=E_LOCKED,
             detail="持有者 pid=%s(%s,开始于 %s)" % (pid, st.get("op", "?"), st.get("at", "?")),
             hint="该进程正在写 skills 目录,强删会导致并发写入。等它结束再试;"
                  "确认它已僵死且不会恢复时用 `ghpm unlock --force`。")
        raise RuntimeError("%s 锁仍被进程 %s 持有,未清除" % (E_LOCKED, pid))
    if alive is None and not lock_is_stale(st, None) and not force:
        emit("failed", "无法确认锁的持有者是否还活着,拒绝清除", percent=100, code=E_LOCKED,
             detail="pid=%s(%.0f 秒前还有心跳)" % (pid, hb),
             hint="进程查询不可用(缺 tasklist / 无权限),而心跳仍在租约内。"
                  "确认没有 ghpm 在跑就用 `ghpm unlock --force`。")
        raise RuntimeError("%s 锁的持有者状态未知,未清除" % E_LOCKED)

    if alive is not False and force:
        print("  [警告] 持有者可能仍在运行,按 --force 强行清锁,可能造成并发写入。",
              file=sys.stderr)
    if pid == os.getpid():
        release_lock(st.get("token"))
    else:
        try:
            lock.unlink()
        except Exception as e:
            print("删除锁文件失败:%s" % e)
            print("无妨 —— 锁的持有者进程结束后会被自动判定为陈旧锁。")
            return
    print("锁已清除")


# ---------- rollback ----------

def cmd_rollback(args):
    """把某次备份恢复到原位,并逐项报告失败。

    v3.1 这里直接 restore_backup,没拿写锁 —— 于是 install 正在写 skills/foo 时,
    另一个进程可以同时把 foo 覆盖回旧版,两边都以为自己是最后一次写入。
    回滚同样是写操作,必须和 install/update/remove/scan 互斥。
    """
    bd = Path(args.backup)
    if not bd.exists():
        emit("failed", "备份目录不存在", percent=100, code="E_NOT_FOUND", detail=str(bd))
        print("备份目录不存在:%s" % bd, file=sys.stderr)
        return
    # 备份目录本身也要在 WB 内,否则 restore_backup 里的 strict 校验会全量拒绝,
    # 结果就是「什么都没恢复」——先在这里给出明确原因。
    try:
        bd = validate_managed_path(bd, config.WB, "备份目录")
    except UnsafePathError as e:
        emit("failed", "备份路径越界", percent=100, code=E_UNSAFE_PATH, detail=str(e),
             hint="回滚只允许操作 %s 之内的备份目录。" % config.WB)
        raise

    with _RollbackLock(bd):
        result = restore_backup(bd)
        restored = result["restored"]
        failed = result["failed"]
        if restored:
            print("已恢复 %d 项:" % len(restored))
            for r in restored:
                print("  " + r)
        if result.get("skipped"):
            print("有 %d 项因路径越界被跳过(清单可能被手工改坏):"
                  % len(result["skipped"]), file=sys.stderr)
            for item in result["skipped"]:
                print("  %s: %s" % (item.get("path", "?"), item.get("error", "?")),
                      file=sys.stderr)
        if failed:
            print("有 %d 项恢复失败,备份已保留:" % len(failed), file=sys.stderr)
            for item in failed:
                print("  %s: %s" % (item.get("path", "?"), item.get("error", "未知错误")),
                      file=sys.stderr)
            emit("failed", "回滚不完整", percent=100, code=E_WRITE, backup=str(bd),
                 data={"rollback": result})
            raise RuntimeError("%s 回滚不完整" % E_WRITE)
        if not restored:
            print("没有可恢复的内容:%s" % bd)
            emit("done", "没有可恢复的内容", percent=100, ok=True,
                 backup=str(bd), data={"rollback": result})
            return
        emit("done", "回滚完成 · %d 项" % len(restored), percent=100, ok=True,
             data={"rollback": result})


class _RollbackLock:
    """回滚的写锁。单独写一个小上下文,是为了让「拿不到锁」也能 emit E_LOCKED
    (LockSession 也会抛,但这里的提示文案是回滚专属的)。"""

    def __init__(self, bd: Path):
        self.bd = bd
        self.holder: dict = {}

    def __enter__(self):
        self.lock, self.holder = acquire_lock("rollback %s" % self.bd.name)
        if not self.lock:
            emit("failed", "有另一个任务正在修改,请稍后再试", percent=100, code=E_LOCKED,
                 detail="占用者:%s" % self.holder.get("op", "?"),
                 hint="回滚会写 skills 目录,必须等写任务结束。")
            raise RuntimeError("%s %s 当前无法回滚" % (E_LOCKED, self.bd.name))
        return self

    def __exit__(self, *exc):
        release_lock(self.holder.get("token"))


# ---------- doctor ----------

def _doctor_item(name: str, status: str, detail: str, hint: str = "") -> dict:
    item = {"name": name, "status": status, "detail": detail}
    if hint:
        item["hint"] = hint
    return item


def _doctor_api() -> dict:
    """短超时探测 GitHub API,并返回额度信息。"""
    cmd = ["curl", "-sSL", "--max-time", "10", "-w", "\n__HTTP__%{http_code}",
           "-H", "Accept: application/vnd.github+json"]
    if config.GH_TOKEN:
        cmd += ["-H", "Authorization: Bearer %s" % config.GH_TOKEN]
    cmd.append("https://api.github.com/rate_limit")
    r = run(cmd)
    code = _http_code(r.stdout)
    body = r.stdout.rsplit("__HTTP__", 1)[0] if "__HTTP__" in (r.stdout or "") else r.stdout
    if r.returncode != 0:
        raise RuntimeError(r.stderr.strip()[:160] or "curl 请求失败")
    if not code.isdigit() or int(code) >= 400:
        raise RuntimeError("HTTP %s" % (code or "?"))
    data = json.loads(body)
    core = (data.get("resources") or {}).get("core") or data.get("rate") or {}
    return {"remaining": core.get("remaining"), "limit": core.get("limit")}


def cmd_doctor(args):
    """只读诊断运行环境、网络、清单、锁、缓存、备份与磁盘。"""
    checks = []
    py_ok = sys.version_info >= (3, 10)
    checks.append(_doctor_item("Python", "OK" if py_ok else "FAIL",
                               "%d.%d.%d" % sys.version_info[:3],
                               "需要 Python 3.10+" if not py_ok else ""))

    curl = shutil.which("curl")
    if curl:
        try:
            r = run([curl, "--version"])
            version = (r.stdout or "").splitlines()[0] if r.returncode == 0 else curl
            checks.append(_doctor_item("curl", "OK", version))
        except Exception as e:
            checks.append(_doctor_item("curl", "FAIL", str(e)[:160]))
    else:
        checks.append(_doctor_item("curl", "FAIL", "PATH 中未找到 curl",
                                   "安装 curl 并确保命令可用"))

    checks.append(_doctor_item("GITHUB_TOKEN", "OK" if config.GH_TOKEN else "WARN",
                               "已配置" if config.GH_TOKEN else "未配置(GitHub API 仅 60 次/小时)",
                               "频繁检查时建议配置 GITHUB_TOKEN" if not config.GH_TOKEN else ""))

    if getattr(args, "no_network", False):
        checks.append(_doctor_item("GitHub API", "SKIP", "按 --no-network 跳过"))
    elif not curl:
        checks.append(_doctor_item("GitHub API", "FAIL", "无法探测:curl 不可用"))
    else:
        try:
            rate = _doctor_api()
            detail = "连接正常"
            if rate.get("remaining") is not None:
                detail += ",额度 %s/%s" % (rate["remaining"], rate.get("limit", "?"))
            checks.append(_doctor_item("GitHub API", "OK", detail))
        except Exception as e:
            checks.append(_doctor_item("GitHub API", "FAIL", str(e)[:160],
                                       "检查网络、代理或 token 后重试"))

    anchor = config.WB
    while not anchor.exists() and anchor.parent != anchor:
        anchor = anchor.parent
    writable = os.access(anchor, os.W_OK)
    checks.append(_doctor_item("WorkBuddy 目录", "OK" if writable else "FAIL",
                               "%s(%s)" % (config.WB, "可写" if writable else "不可写")))

    if not config.REGISTRY.exists():
        checks.append(_doctor_item("Registry", "OK", "尚未创建,将在首次安装时生成 schema v%d"
                                   % config.REGISTRY_SCHEMA_VERSION))
    else:
        try:
            raw = json.loads(config.REGISTRY.read_text(encoding="utf-8"))
            version = raw.get("schema_version", 1) if isinstance(raw, dict) else "?"
            migrated = migrate_registry(raw)
            status = "OK" if version == config.REGISTRY_SCHEMA_VERSION else "WARN"
            checks.append(_doctor_item("Registry", status,
                                       "schema v%s,%d 个项目(当前目标 v%d)"
                                       % (version, len(migrated.get("projects", [])),
                                          config.REGISTRY_SCHEMA_VERSION),
                                       "下次成功写入清单时会自动迁移到当前版本"
                                       if status == "WARN" else ""))
        except Exception as e:
            checks.append(_doctor_item("Registry", "FAIL", str(e)[:160],
                                       "先备份损坏文件,再运行任一写命令触发留档恢复"))

    lock = config.LOCK
    if not lock.exists():
        checks.append(_doctor_item("写锁", "OK", "当前无锁"))
    else:
        st = read_lock()
        mtime = None
        try:
            mtime = lock.stat().st_mtime
        except OSError:
            pass
        hb = lock_heartbeat_age(st, mtime) if st else float("inf")
        hb_txt = ("心跳 %.0fs 前" % hb) if hb != float("inf") else "无心跳记录"
        if not st:
            checks.append(_doctor_item("写锁", "WARN", "锁文件损坏(%s)" % hb_txt,
                                       "确认没有 ghpm 任务后运行 `ghpm unlock`"))
        elif pid_alive(st.get("pid")) is True:
            checks.append(_doctor_item("写锁", "WARN",
                                       "pid=%s 正在执行 %s(%s)"
                                       % (st.get("pid"), st.get("op", "?"), hb_txt)))
        else:
            checks.append(_doctor_item("写锁", "WARN",
                                       "发现陈旧锁 pid=%s(%s)" % (st.get("pid", "?"), hb_txt),
                                       "运行 `ghpm unlock` 清理"))

    cache_files = list(config.CACHE.glob("repo-*.json")) if config.CACHE.is_dir() else []
    cache_size = sum(path_size_bytes(p) for p in cache_files)
    cache_status = "WARN" if len(cache_files) > config.CACHE_MAX_FILES else "OK"
    checks.append(_doctor_item("缓存", cache_status,
                               "%d 个文件,%s" % (len(cache_files), format_bytes(cache_size))))

    skill_count = 0
    if config.SKILLS.is_dir():
        skill_count = sum(1 for p in config.SKILLS.iterdir()
                          if p.is_dir() and (p / "SKILL.md").is_file())
    checks.append(_doctor_item("Skills 目录", "OK",
                               "%s,%d 个标准 skill" % (config.SKILLS, skill_count)))

    backups = [p for p in config.WB.glob(".ghpm-backup-*")
               if p.is_dir()] if config.WB.is_dir() else []
    old_cutoff = time.time() - 7 * 24 * 3600
    old_backups = [p for p in backups if p.stat().st_mtime < old_cutoff]
    if old_backups:
        checks.append(_doctor_item("事务备份", "WARN", "%d 个备份,其中 %d 个超过 7 天"
                                   % (len(backups), len(old_backups)),
                                   "确认无需回滚后再手动处理旧备份"))
    else:
        checks.append(_doctor_item("事务备份", "OK",
                                   "%d 个(无超过 7 天的旧备份)" % len(backups)))

    try:
        free = disk_free_bytes(config.WB)
        min_free = int(float(os.environ.get("GHPM_DOCTOR_MIN_FREE_MB", "1024")) * config.MIB)
        status = "OK" if free >= min_free else "WARN"
        checks.append(_doctor_item("磁盘空间", status, "可用 %s" % format_bytes(free),
                                   "建议至少保留 %s" % format_bytes(min_free)
                                   if status == "WARN" else ""))
    except Exception as e:
        checks.append(_doctor_item("磁盘空间", "FAIL", str(e)[:160]))

    summary = {s: sum(1 for x in checks if x["status"] == s)
               for s in ("OK", "WARN", "FAIL", "SKIP")}
    payload = {"ok": summary["FAIL"] == 0, "checks": checks, "summary": summary,
               "schema_version": config.REGISTRY_SCHEMA_VERSION,
               "backup_mode": config.backup_mode()}
    if getattr(args, "json", False):
        print(json.dumps(payload, ensure_ascii=False))
        return

    print("GHPM Doctor\n")
    for item in checks:
        print("[%s] %-14s %s" % (item["status"], item["name"], item["detail"]))
        if item.get("hint"):
            print("       建议:%s" % item["hint"])
    print("\n汇总:%d OK,%d WARN,%d FAIL,%d SKIP(备份介质 %s)"
          % (summary["OK"], summary["WARN"], summary["FAIL"], summary["SKIP"],
             config.backup_mode()))
    print("数据完整性请用 `ghpm verify`(doctor 只看运行环境能不能用)。")
    emit("done", "诊断完成", percent=100, ok=payload["ok"], data=payload)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall