skillreg 0.1.0__py3-none-any.whl

skillreg/__init__.py

@@ -0,0 +1,8 @@
+"""skillreg — skill registry control plane.
+
+A Python CLI + FastAPI backend that manages a skill registry workspace and
+syncs skills to agent install targets. See ``README.md`` and ``docs/`` for the
+current product docs.
+"""
+
+__version__ = "0.1.0"

skillreg/builtin/skillreg-skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: skillreg-skill
+description: 当用户要注册、导入、转换或同步本地 skill 时使用。用户可能在任意项目里对 agent 说“注册这个 skill”；优先把当前项目或用户给定路径中 agent/用户写好的 SKILL.md 注册到当前 skillreg workspace，而不是要求用户理解产品仓、workspace 仓等实现细节。
+---
+
+# skillreg-skill
+
+当用户想用 `skillreg` 完成 skill 的注册、导入、转换、同步、查看状态或排障时，优先使用这个 skill。
+
+核心心智模型：
+
+- 用户关心的是“把本地已经写好的 skill 放进我的 skill workspace，并同步给 agent 用”。
+- 用户不需要关心当前是在业务项目、skill 源码项目、`skillreg` 产品仓，还是 workspace 仓。
+- agent 要负责识别本地 skill 来源、确认当前 `skillreg` workspace，然后完成注册或给出可执行的下一步。
+
+## 触发场景
+
+- 用户说"用 skillreg 管一下这个 skill"
+- 用户说"注册这个 skill"、"把这个 skill 注册一下"、"把这个目录注册成 skill"
+- 用户要把一个本地目录、zip、git 仓库注册进 workspace
+- 用户要把 `skills/<name>` 转成 `repos/<name>-cli/skill/<name>`
+- 用户要把 workspace 中的 skills 同步到 Claude、Codex、`.agents/skills` 等目标目录
+- 用户反馈 `skillreg` 命令找不到、dashboard 起不来、workspace 不生效、sync 结果不对
+
+## 先做什么
+
+1. 识别要注册的 skill 来源：
+   - 用户给了路径：优先用该路径。
+   - 用户没给路径：从当前工作目录开始找 `SKILL.md`；如果当前目录本身就是 skill 目录，直接使用当前目录。
+   - 如果找不到 `SKILL.md`，先告诉用户需要一个包含 `SKILL.md` 的目录，并说明当前检查过哪里。
+2. 跑 `skillreg config`，确认当前 `workspace_path`、targets 和配置文件位置。
+3. 如果 `workspace_path` 为空，先创建或引导选择 workspace；不要要求用户判断“产品仓/工作区仓”。
+4. 如果命令不存在或环境没装好，读 `references/install.md`。
+5. 如果命令能跑但行为异常（workspace 不对、dashboard/sync 出错），读 `references/troubleshooting.md`。
+
+## 推荐工作流
+
+### 1. 创建或确认 workspace
+
+| 场景 | 操作 |
+|------|------|
+| 新建 workspace | `skillreg workspace create ~/my-skills` |
+| 已有 workspace | 确认它至少包含 `skills/` 目录 |
+| 需要图形操作 | `skillreg dashboard open` |
+
+说明：
+- workspace 切换主要在 dashboard 中完成。
+- CLI 更适合做"确认配置、创建 workspace、启动 dashboard"这几个入口动作。
+
+### 2. 把本地 skill 纳入 workspace
+
+根据用户目标选择入口：
+
+| 目标 | 入口 |
+|------|------|
+| 把当前目录或给定路径里的 skill 注册进 workspace | dashboard 的 import 流程或 `/api/registry/register` |
+| 保留原目录内容并注册进 workspace | dashboard 的 import 流程 |
+| 已有 registry 风格调用面 | `/api/registry/register` |
+| 把 file skill 变成 repo/CLI 骨架 | `/api/registry/convert` |
+
+要点：
+- `register` → 把 skill 放进 `skills/<name>/`
+- `convert` → 把 `skills/<name>` 迁到 `repos/<name>-cli/skill/<name>/`，并生成基础 CLI repo 骨架
+- “注册”默认不是注册当前代码仓库本身，而是注册其中包含 `SKILL.md` 的 skill 目录。
+- 如果用户在任意业务项目里说“注册 skill”，agent 应主动定位该项目中的 `SKILL.md` 或询问具体 skill 目录。
+
+### 3. 同步到 agent 目标目录
+
+1. 在 dashboard 的 Sync 页面配置 targets。
+2. 执行同步，检查状态。
+
+状态含义（不要混淆）：
+
+| 状态 | 含义 |
+|------|------|
+| `synced` | workspace 和 target 一致 |
+| `modified` | target 里有本地改动或差异 |
+| `missing` | 配置里有这个 skill，但目标缺失 |
+| `not-installed` | 该 target 当前还没有安装这个 skill |
+
+## agent 行为约束
+
+- **先验证再行动**：先用 `skillreg config`、dashboard、API 或测试确认能力真的可用。
+- **用户心智优先**：不要把"产品仓 / workspace 仓 / submodule 仓"作为用户必须回答的问题；这些只是 agent 内部判断路径和命令时的实现细节。
+- **任意项目可触发**：用户可能在任何项目里说"注册 skill"。先找本地 `SKILL.md`，再把它注册进 `skillreg config` 指向的 workspace。
+- **优先工具**：如果用户只是要完成一项实际操作，优先直接用 `skillreg` 完成，不要手工复制目录。
+- **排障先诊断**：如果用户是在排障，先给出现状和根因，再决定是否需要改代码或改配置。
+
+## 何时读参考文档
+
+| 问题类型 | 参考文档 |
+|----------|----------|
+| 安装、开发态启动、PATH/venv 问题 | `references/install.md` |
+| dashboard 起不来、workspace 不对、sync 异常、skill 没注入、命令行为不符合预期 | `references/troubleshooting.md` |

skillreg/builtin/skillreg-skill/references/install.md

@@ -0,0 +1,90 @@
+# skillreg 安装与启动
+
+这个文档给 agent 一个稳定起点：当用户要“安装 skillreg”“把 skillreg CLI 跑起来”“确认本地环境能不能用”时，先按这里走。
+
+## 1. 先确认本机入口
+
+无论用户当前在哪个项目里，都先用下面两个命令识别 `skillreg` 是否可用、当前 workspace 指向哪里：
+
+```bash
+pwd
+skillreg config
+```
+
+如果 `skillreg` 命令不存在，再继续看下面的安装方式。
+
+不要要求用户先判断自己是在“产品仓”还是“workspace 仓”。用户通常只是在某个本地项目里想把一个包含 `SKILL.md` 的目录注册进 workspace。
+
+## 2. 面向用户的 CLI 安装
+
+如果目标是给本机装一个可直接调用的 `skillreg`，优先建议：
+
+```bash
+uv tool install skillreg
+```
+
+安装后先确认：
+
+```bash
+skillreg config
+which skillreg
+```
+
+如果项目还没真正发布到公开包源，`uv tool install skillreg` 可能失败。这种情况下要明确告诉用户：
+
+- 当前更可靠的是源码开发态安装
+- 或者从本地仓库执行 `uv pip install -e .`
+
+## 3. 开发态安装
+
+当 agent 正在 `skillreg` 仓库里改代码时，优先用开发态安装：
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+```
+
+安装后可验证：
+
+```bash
+skillreg config
+skillreg dashboard open --no-browser
+```
+
+如果用户是在当前仓库里直接联调，也可以直接起服务：
+
+```bash
+python -m uvicorn skillreg.server:app --host 127.0.0.1 --port 8787
+```
+
+## 4. 初始化最小可用闭环
+
+安装完成后，最小验证顺序：
+
+```bash
+skillreg workspace create ~/my-skills
+skillreg dashboard open --no-browser
+```
+
+然后确认：
+
+- `~/.skillreg/config.json` 已生成
+- `workspace_path` 指向新建 workspace
+- workspace 下至少有 `skills/` 和 `repos/`
+
+## 5. 常用命令
+
+```bash
+skillreg config
+skillreg workspace create <path>
+skillreg dashboard open
+skillreg dashboard open --no-browser
+```
+
+当前 agent 应该把 CLI 看成：
+
+- `config`：确认配置和当前 workspace
+- `workspace create`：创建新的 workspace
+- `dashboard open`：进入主要操作入口
+
+workspace 切换、导入、sync target 管理，目前主要还是通过 dashboard 完成。

skillreg/builtin/skillreg-skill/references/troubleshooting.md

@@ -0,0 +1,143 @@
+# skillreg 排障指南
+
+当用户反馈“装好了但不能用”“workspace 不对”“sync 看起来不可信”“dashboard 起不来”时，按这个顺序排查。
+
+## 1. 先看当前配置
+
+第一步永远先跑：
+
+```bash
+skillreg config
+```
+
+重点看：
+
+- 配置文件是不是 `~/.skillreg/config.json`
+- `workspace_path` 有没有值
+- 指向的路径是不是用户真正想操作的那个 workspace
+
+如果 `workspace_path` 为空或错误，很多问题都会是表象。
+
+## 2. workspace 问题
+
+典型现象：
+
+- skills 列表为空
+- dashboard 里看不到预期 skill
+- sync 用的是错误仓库
+
+检查：
+
+```bash
+ls <workspace>
+ls <workspace>/skills
+```
+
+确认：
+
+- workspace 路径存在
+- 它是目录，不是文件
+- 至少包含 `skills/`
+
+如果用户已经有 workspace，但 CLI 当前没指向它：
+
+- 打开 dashboard
+- 在 header 中切换到正确 workspace
+
+## 3. dashboard 起不来
+
+先区分是“命令起不来”，还是“服务起来了但页面打不开”。
+
+### 命令起不来
+
+优先检查：
+
+```bash
+which skillreg
+skillreg config
+```
+
+如果 `skillreg` 不存在，回到 `install.md` 重新安装。
+
+### 服务起来但网页打不开
+
+可直接用开发命令确认后端是否可起：
+
+```bash
+python -m uvicorn skillreg.server:app --host 127.0.0.1 --port 8787
+```
+
+再检查：
+
+- 端口是否被占用
+- `dashboard/dist` 是否存在
+- 浏览器访问的是不是正确端口
+
+## 4. register / convert 异常
+
+### register 失败
+
+优先检查源目录：
+
+- 是否存在 `SKILL.md`
+- frontmatter 里是否有 `name`
+- `name` 是否满足 `[A-Za-z0-9][A-Za-z0-9_-]*`
+
+常见冲突：
+
+- `skills/<name>` 已存在
+- 没有传 `force=true`
+
+### convert 失败
+
+优先检查：
+
+- `skills/<name>/SKILL.md` 是否存在
+- `repos/<name>-cli` 是否已经存在
+
+语义上要记住：
+
+- `convert` 是迁移，不是复制
+- 成功后原来的 `skills/<name>` 会移入 `repos/<name>-cli/skill/<name>/`
+
+## 5. sync 状态不对
+
+先别急着改代码，先确认状态解释有没有搞错：
+
+- `synced`：一致
+- `modified`：目标侧有差异
+- `missing`：配置/期望存在，但目标缺失
+- `not-installed`：当前 target 还没安装这个 skill
+
+如果用户说“怎么全是 missing / not-installed”，先检查：
+
+- 当前 target 路径是不是对的
+- target 目录是否真的存在
+- workspace 当前选中的 skill 是否在目标里出现
+
+## 6. builtin skill 没注入
+
+`skillreg` 会把 builtin `skillreg-skill` 注入到：
+
+```text
+<workspace>/.skillreg/builtin/skillreg-skill/
+```
+
+如果用户说看不到：
+
+1. 先确认当前 workspace 是对的
+2. 再检查这个目录是否存在
+3. 如果是开发态，确认源码里 `src/skillreg/builtin/skillreg-skill/` 存在
+4. 如果是安装态，确认 wheel 中包含 builtin 目录
+
+## 7. 什么时候该改代码
+
+只有在下面这些都确认之后，再进入代码修复：
+
+- 配置路径正确
+- workspace 正确
+- 输入目录和 skill 元数据合法
+- target 路径和目标状态核对过
+- CLI 安装和 PATH 没问题
+
+也就是说，先排除“环境 / 配置 / 路径 / 术语理解”问题，再动实现。

skillreg/cli.py

@@ -0,0 +1,137 @@
+"""skillreg CLI entry point.
+
+Minimal command set for M1 (issue #02):
+
+- ``skillreg config``           — print config status (auto-creates config).
+- ``skillreg dashboard open``   — start the FastAPI backend + open a browser.
+
+Built with `click`. The entry point ``skillreg = "skillreg.cli:main"`` is
+declared in ``pyproject.toml``.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import webbrowser
+from typing import Optional, Sequence
+
+import click
+import uvicorn
+
+from . import __version__
+from .config import CONFIG_FILE, load_config
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8787
+
+
+def _format_csv(values: Sequence[str]) -> str:
+    return ", ".join(values) if values else "(none)"
+
+
+def _echo_workspace_summary(*, heading: str = "skillreg context") -> None:
+    """Print the current workspace context after user-facing commands."""
+    cfg = load_config()
+    click.echo(heading)
+    click.echo(f"  config file       : {CONFIG_FILE}")
+    click.echo(f"  current workspace : {cfg.workspace_path or '(not configured)'}")
+    click.echo(f"  sync targets      : {_format_csv(cfg.targets)}")
+
+
+@click.group()
+@click.version_option(version=__version__, package_name="skillreg")
+def cli() -> None:
+    """skillreg — skill registry control plane."""
+
+
+@cli.command()
+def config() -> None:
+    """Print skillreg configuration status.
+
+    Auto-creates ``~/.skillreg/config.json`` with the default empty structure
+    on first run.
+    """
+    cfg = load_config()
+    click.echo("skillreg config")
+    click.echo(f"  config file : {CONFIG_FILE}")
+    click.echo(f"  workspace   : {cfg.workspace_path or '(not configured)'}")
+    click.echo(
+        f"  targets     : "
+        f"{', '.join(cfg.targets) if cfg.targets else '(none)'}"
+    )
+    click.echo(
+        f"  agents      : "
+        f"{', '.join(cfg.agents.keys()) if cfg.agents else '(none)'}"
+    )
+
+
+@cli.group()
+def dashboard() -> None:
+    """Manage the skillreg dashboard."""
+
+
+@cli.group()
+def workspace() -> None:
+    """Manage skillreg workspaces."""
+
+
+@workspace.command("create")
+@click.argument("location", type=click.Path())
+def create_workspace(location: str) -> None:
+    """Create a new workspace at LOCATION.
+
+    Initializes a git repo with skills/ and repos/ directories,
+    writes .gitignore and README, and updates the config pointer.
+    """
+    from .services.importer import create_workspace as _create
+
+    try:
+        result = _create(location)
+        click.echo(f"✓ Workspace created at {result['workspace_path']}")
+        click.echo(f"  git init  : {'✓' if result['has_git'] else '✗'}")
+        click.echo(f"  skills/   : {'✓' if result['has_skills_dir'] else '✗'}")
+        click.echo(f"  repos/    : {'✓' if result['has_repos_dir'] else '✗'}")
+        _echo_workspace_summary(heading="skillreg context after workspace create")
+    except ValueError as e:
+        click.echo(f"✗ {e}", err=True)
+        raise SystemExit(1)
+
+
+@dashboard.command("open")
+@click.option("--host", default=DEFAULT_HOST, show_default=True, help="Bind host.")
+@click.option("--port", default=DEFAULT_PORT, show_default=True, type=int, help="Bind port.")
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    default=False,
+    help="Do not open a browser; just start the server.",
+)
+def open_dashboard(host: str, port: int, no_browser: bool) -> None:
+    """Start the FastAPI backend and open the dashboard in a browser."""
+    url = f"http://{host}:{port}"
+    if not no_browser:
+        # Delay browser launch so uvicorn has a moment to bind the socket.
+        threading.Thread(
+            target=lambda: (time.sleep(1.0), webbrowser.open(url)),
+            daemon=True,
+        ).start()
+    click.echo(f"skillreg backend starting at {url}")
+    _echo_workspace_summary(heading="skillreg context for dashboard")
+    click.echo("  press Ctrl+C to stop.")
+    uvicorn.run(
+        "skillreg.server:app",
+        host=host,
+        port=port,
+        log_config=None,
+    )
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point for the ``skillreg`` console script."""
+    cli(args=list(argv) if argv is not None else None, standalone_mode=True)
+    return 0
+
+
+if __name__ == "__main__":
+    main()

skillreg/config.py

@@ -0,0 +1,81 @@
+"""Configuration management for skillreg.
+
+Per PRD §2.3, all skillreg-local state lives in ``~/.skillreg/config.json``:
+
+- ``workspace_path`` — pointer to the workspace repo (skills storage). The
+  workspace itself only holds ``skills/`` + ``repos/``; it no longer carries
+  ``sync-skills.json`` or ``infra/``.
+- ``targets`` — install targets (e.g. ``~/.claude/skills``).
+- ``agents`` — agent conventions map (claude / codebuddy / codex …).
+
+Exclude rules and manifest settings stay code-internal (not in this file).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+# --- locations -------------------------------------------------------------
+
+CONFIG_DIR: Path = Path.home() / ".skillreg"
+CONFIG_FILE: Path = CONFIG_DIR / "config.json"
+
+
+# --- model -----------------------------------------------------------------
+
+
+class SkillregConfig(BaseModel):
+    """Schema for ``~/.skillreg/config.json``."""
+
+    workspace_path: Optional[str] = Field(
+        default=None,
+        description="Absolute path to the workspace repo (skills storage). "
+        "null until the user configures it.",
+    )
+    targets: List[str] = Field(
+        default_factory=list,
+        description="Install targets (agent skill dirs), e.g. ~/.claude/skills.",
+    )
+    agents: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Agent conventions map. Keys are agent names "
+        "(claude / codebuddy / codex …); values are agent-specific convention "
+        "records (structure expanded in later issues).",
+    )
+
+
+def default_config() -> SkillregConfig:
+    """Return a fresh empty config with all expected fields."""
+    return SkillregConfig()
+
+
+# --- I/O -------------------------------------------------------------------
+
+
+def load_config(path: Optional[Path] = None) -> SkillregConfig:
+    """Load config from ``path`` (default: ``~/.skillreg/config.json``).
+
+    If the file does not exist, it is created with the default empty structure
+    and returned. The config directory is created on demand.
+    """
+    if path is None:
+        path = CONFIG_FILE
+    if not path.exists():
+        cfg = default_config()
+        save_config(cfg, path)
+        return cfg
+    data = json.loads(path.read_text(encoding="utf-8"))
+    # Coerce into the schema; unknown keys are dropped, missing keys defaulted.
+    return SkillregConfig.model_validate(data)
+
+
+def save_config(cfg: SkillregConfig, path: Optional[Path] = None) -> None:
+    """Persist ``cfg`` to ``path`` (default: ``~/.skillreg/config.json``)."""
+    if path is None:
+        path = CONFIG_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(cfg.model_dump_json(indent=2), encoding="utf-8")

skillreg/server/__init__.py

@@ -0,0 +1,148 @@
+"""FastAPI backend for skillreg.
+
+Exposes API routes under ``/api`` and (when present) serves the built dashboard
+static files via ``StaticFiles``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+
+from .. import __version__
+
+
+def dashboard_dir() -> Optional[Path]:
+    """Locate the dashboard static directory."""
+    env = os.environ.get("SKILLREG_DASHBOARD_DIR")
+    if env:
+        p = Path(env)
+        if p.is_dir():
+            return p
+    dashboard_root = Path(__file__).resolve().parents[3] / "dashboard"
+    dist = dashboard_root / "dist"
+    if dist.is_dir():
+        return dist
+    if dashboard_root.is_dir():
+        return dashboard_root
+    return None
+
+
+def create_app() -> FastAPI:
+    """Build the FastAPI application with all routes mounted."""
+    app = FastAPI(title="skillreg", version=__version__)
+
+    # Inject self-skill on startup if workspace is configured
+    from ..config import load_config
+    from ..services.self_skill import init_self_skill
+
+    cfg = load_config()
+    if cfg.workspace_path:
+        try:
+            init_self_skill(cfg.workspace_path)
+        except Exception:
+            pass  # Non-fatal: dashboard still works without self-skill
+
+    # Register route modules
+    from .health import router as health_router
+
+    app.include_router(health_router)
+
+    # Skills / registry / sync routes (built progressively)
+    try:
+        from .skills import router as skills_router
+        app.include_router(skills_router)
+    except ImportError:
+        pass
+
+    try:
+        from .sync import router as sync_router
+        app.include_router(sync_router)
+    except ImportError:
+        pass
+
+    try:
+        from .registry import router as registry_router
+        app.include_router(registry_router)
+    except ImportError:
+        pass
+
+    try:
+        from .files import router as files_router
+        app.include_router(files_router)
+    except ImportError:
+        pass
+
+    try:
+        from .git import router as git_router
+        app.include_router(git_router)
+    except ImportError:
+        pass
+
+    try:
+        from .submodules import router as submodules_router
+        app.include_router(submodules_router)
+    except ImportError:
+        pass
+
+    try:
+        from .hooks import router as hooks_router
+        app.include_router(hooks_router)
+    except ImportError:
+        pass
+
+    try:
+        from .import_ import router as import_router
+        app.include_router(import_router)
+    except ImportError:
+        pass
+
+    try:
+        from .compat import router as compat_router
+        app.include_router(compat_router)
+    except ImportError:
+        pass
+
+    try:
+        from .workspace import router as workspace_router
+        app.include_router(workspace_router)
+    except ImportError:
+        pass
+
+    # Dashboard static serving (SPA fallback, after /api routes)
+    _d = dashboard_dir()
+    if _d is not None:
+        index_file = _d / "index.html"
+        if index_file.is_file():
+            @app.get("/assets/{asset_path:path}", include_in_schema=False)
+            def dashboard_assets(asset_path: str):
+                file_path = (_d / "assets" / asset_path).resolve()
+                assets_root = (_d / "assets").resolve()
+                try:
+                    file_path.relative_to(assets_root)
+                except ValueError as exc:
+                    raise HTTPException(404) from exc
+                if not file_path.is_file():
+                    raise HTTPException(404)
+                return FileResponse(file_path)
+
+            @app.get("/{full_path:path}", include_in_schema=False)
+            def dashboard_spa_fallback(full_path: str):
+                request_path = (_d / full_path).resolve()
+                try:
+                    request_path.relative_to(_d.resolve())
+                except ValueError:
+                    return FileResponse(index_file)
+                if full_path and request_path.is_file():
+                    return FileResponse(request_path)
+                return FileResponse(index_file)
+
+    return app
+
+
+# Module-level app for uvicorn (skillreg.server:app)
+app = create_app()