cckit 0.1.1__tar.gz → 0.2.1__tar.gz

{cckit-0.1.1 → cckit-0.2.1}/.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
 *.py[cod]
 .venv/
+dist/

{cckit-0.1.1 → cckit-0.2.1}/Docs/.gitignore

@@ -1,4 +1,7 @@
 # ignore num-prefix development docs and development README
 [0-9]*.md
 
-README.md
+README.md
+
+# ignore pics
+pics/

{cckit-0.1.1 → cckit-0.2.1}/Docs/05-design-log.md

@@ -385,6 +385,21 @@ skill 报成项目安装。所以刻意分列:`override_scopes` 只给 `remove`
 skill 补。若项目里真有同名项目 kit,该覆盖是写给项目 kit 的(`set_state` 定位顺序先项目后
 全局),不能误归属到全局 kit。
 
+**读回路径的扩展(Web 接入后)**:最初「读回」只补**带项目覆盖**的全局 skill
+(`name in proj_ov`)——因为 CLI 的 `list --project` 语义是"项目里实际有什么"。但 Web
+侧栏要能「看到」全局 skill 才能让用户发起**首次**覆盖;只列出带覆盖的,还没覆盖过的全局
+skill 根本不可见,覆盖无从点起。
+
+故 `list_skills("project")` 改为列出**所有**全局 skill,`SkillState` 带三字段:
+`is_global_skill`(是否全局 skill)、`global_state`(它在全局的当前状态,决策依据)、
+`override`(有无项目覆盖)。有覆盖时 `state`=覆盖态,无覆盖时 `state`=`global_state`
+(跟随全局)。`budget` 相应排除 `is_global_skill` 的 `enabled` 条目——全局 skill 的
+description 在全局作用域已计一次,项目作用域的「跟随全局」条目不能重复计入。
+
+CLI 与 Web 由此共用同一套覆盖语义:CLI 显示「项目覆盖 已关闭」/「跟随全局 已启用」;
+Web 把全局 skill 单独折叠一组、用独立覆盖选择器(不复用四态),只展示当前全局状态下允许的
+选项(全局 `enabled`→跟随/name-only/off;`name-only`→跟随/off;`off`→仅跟随)。
+
 **已知取舍**:这条没有让"全局 skill 在项目里**强制开启**"成为可表达的状态——`enable
 --project` 是清覆盖(跟随全局)。要"全局 off 但本项目 on"属于罕见需求,且 `skillOverrides`
 的项目层覆盖能否压过全局层的 off 尚未验证,不主动提供。

{cckit-0.1.1 → cckit-0.2.1}/Docs/09-state-api.md

@@ -61,16 +61,34 @@ class SkillState:
     env_ok: bool | None             # None = 该 skill 无需 env
     desc_chars: int                 # 用于预算统计
     version: str | None
-
-def list_skills(scope=None) -> list[SkillState]: ...
-def get_state(name, scope) -> str: ...
-def set_state(name, state, scope) -> None: ...        # 带锁 + 原子写
-def budget() -> tuple[int, int]: ...                  # (已用字符, 上限)
+    is_global_skill: bool = False   # project 作用域下,此条目是「全局 skill 的项目覆盖/跟随」
+    global_state: str | None = None # 全局 skill 在全局作用域的状态
+    override: bool = False          # 全局 skill 是否带项目级覆盖(off/name-only)
+
+def list_skills(scope=None, root=None) -> list[SkillState]: ...
+def get_state(name, scope, root=None) -> str: ...
+def set_state(name, state, scope, root=None) -> None: ...   # 带锁 + 原子写
+def budget(scope=None, root=None) -> tuple[int, int]: ...   # (已用字符, 上限)
 ```
 
 `list_skills()` 必须同时列出**非 cckit 管理**的 skill,标记 `managed=False`。
 用户看到的是完整工具箱视图,但只有 cckit 装的能被开关。
 
+### 全局 skill 的项目级覆盖(D-15)
+
+`list_skills(scope="project")` 会把**所有全局 kit 的 skill** 也列出来(标记
+`is_global_skill=True`),供项目里单独覆盖:
+
+- **有项目覆盖**(`override=True`):`state` 是覆盖状态(off/name-only)。
+- **无覆盖、跟随全局**(`override=False`):`state` 等于 `global_state`(全局状态)。
+
+`global_state` 是决策依据:`set_state` 在项目作用域对全局 skill 只允许
+`off`/`name-only`(写项目 `skillOverrides`)、`enabled`(清覆盖=跟随全局),
+不允许 `installed`(项目无 link 可删)。前端据此只展示当前全局状态下允许的覆盖选项。
+
+`budget()` 排除 `is_global_skill` 的 `enabled` 条目——全局 skill 的 description
+在全局作用域已计入一次,项目作用域的「跟随全局」条目不应重复计算。
+
 ## `registry.json` 结构
 
 唯一的持久化存储。只放**观测不出来**的东西。

cckit-0.2.1/Docs/11-web-panel.md

@@ -0,0 +1,182 @@
+# Web 管理面板
+
+配套 v0.2.1 的可选管理面板:平时展示 skill 列表,支持导入（add）、卸载（remove）、
+四态开关切换、诊断（doctor）。**纯增量**——不装 `[web]` 额外依赖时,`cckit` 本体
+与命令行工具完全不变。
+
+## 定位
+
+- 目标是**管理界面**,不是运行界面:`exec` 这类"跑 skill"的能力在网页上不做
+  （服务器上直接跑 `ccb`/Claude Code 即可）。
+- 部署形态是**独立面板 + iframe 融合**:它要和一个外部 dashboard（Vite+React,
+  非本项目维护）一起上 Linux 服务器,通过 `<iframe>` 嵌入对方页面,因此必须
+  独立开发、独立部署、独立端口,不依赖改对方代码。
+
+## 技术方案
+
+| 决策 | 选择 | 理由 |
+|---|---|---|
+| 仓库 | 当前仓库(`web/` + `src/cckit/web/`) | Web 要动状态层(root 推广)与 installer(两阶段),本就是同一件事;版本天然锁步 |
+| 后端 | FastAPI + uvicorn,import `cckit.*` | 状态/安装/诊断逻辑只有一份,Web 不重实现;SSE 流式 |
+| 前端 | Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui | 纯客户端 SPA,无 SSR 需求;shadcn 4.x 用 base-ui 原语 |
+| 图标 | @phosphor-icons/react | shadcn 4.x 默认图标库 |
+| 数据层 | TanStack Query | 缓存 + 失效即"刷新机制" |
+| 提示 | sonner(shadcn 包装) | 四类 toast + 弹窗/toast 分工 |
+| 依赖隔离 | `[web]` 可选 extra | `uv tool install cckit` 仍是 3 依赖纯本体 |
+| 安全 | 后端默认 `127.0.0.1` | Web 能装 kit(跑作者代码)、能改状态,不放开监听 |
+
+## 架构
+
+```
+浏览器 (外部 dashboard 内 iframe)
+   │  http://<server>:<port>/
+   ▼
+FastAPI (src/cckit/web/)  ── 静态托管 web/dist/
+   │  import                    ├── GET/POST /api/* (JSON)
+   │  ┌─ cckit.state            ├── POST /api/add/execute (SSE)
+   │  ├─ cckit.installer        └── POST /api/doctor        (SSE)
+   │  └─ cckit.doctor
+   ▼
+~/.cckit/  store + registry.json + projects.json + envs
+<CC 配置目录>/skills + settings.json   (状态派生源)
+```
+
+**核心原则**:状态读写只走 `cckit.state`,安装只走 `cckit.installer`,诊断只走
+`cckit.doctor`。Web 后端是这些模块的薄前端,零逻辑重实现,杜绝「改两边」——
+改核心逻辑一处,CLI 与 Web 自动同步;唯一要保证的是核心函数**只返回数据、不发声音**
+(不 `print`/`input`),由 CLI/Web 各自渲染。
+
+## 后端 API
+
+| 端点 | 底层调用 | 说明 |
+|---|---|---|
+| `GET /api/scopes` | `state.list_scopes()` | 侧栏作用域(全局 + 历史项目 + 关注项目) |
+| `POST/DELETE /api/scopes` | `projects.add/remove` | 关注/取关项目,add 时建 `.claude` |
+| `GET /api/skills?scope=&root=` | `state.list_skills` + `state.budget` | 列表 + 预算一次返回;skill 带 `is_global_skill`/`global_state`/`override` |
+| `POST /api/skills/{name}/state` | `state.set_state` | 四态切换,返回 `{message}` |
+| `GET /api/kits` | `registry.load()` | kit 头部元信息 |
+| `POST /api/kits/{kit}/remove` | `installer.remove_kit` | 卸载 |
+| `POST /api/add/preview` | `installer.stage_install` | 克隆+校验+计划,存 `preview_id` |
+| `POST /api/add/execute` | `installer.execute_install` | 确认后执行,SSE 进度 |
+| `DELETE /api/add/preview/{id}` | `StagedInstall.cleanup` | 取消时清理临时目录 |
+| `POST /api/doctor` | `doctor.run(fix, on_event)` | SSE 进度 + findings |
+
+错误契约:`CckitError`(含 `InstallError`)统一捕获 → `{error:{message}}` + 400;
+参数校验失败 → 422。前端只读 `message`,不依赖状态码区分。
+
+`preview_id → StagedInstall` 存进程内字典,带 30 分钟过期回收 + 取消清理,避免
+临时 clone 目录堆积。
+
+## 关键改动(相对 v0.1)
+
+### 状态层作用域推广
+
+`list_skills` / `get_state` / `set_state` / `budget` 增加 `root: Path | None` 参数,
+缺省回落 `config.project_root()`(cwd)——CLI 行为不变。`registry._kit_in_scope` /
+`find_skill` 等同步线程 root。这让 Web 侧栏能操作**任意项目作用域**,而非只有 cwd。
+
+### 关注项目清单 `projects.py`
+
+`~/.cckit/projects.json`(声明式存储):记录「用户想持续关注的项目目录」。与
+`registry.json` 分工——registry 存「装了什么」(观测不到),projects 存「想关注什么」
+(用户意图)。`add()` 顺带建 `.claude` 目录使其成为合法项目作用域。
+
+`state.list_scopes()` 返回三源并集(去重):全局 + registry 的
+`known_scopes`/`override_scopes` + 关注清单,每项带 `{path, source, has_skills}`。
+
+### installer 拆两阶段
+
+`install()` 原是一条龙(clone→校验→print→`input()`→执行),混着 I/O。拆为:
+
+- `stage_install(...) -> StagedInstall`:clone → 校验 → lint → 计算计划,不落盘。
+  lint 的 error **不在此中止**(消息进 `lint_msgs`),由调用方决定是否继续。
+- `execute_install(staged, ...) -> Iterator[ProgressEvent]`:移入 store → env →
+  postinstall → registry → link,逐条 yield 进度;异常回滚 store/env/registry。
+
+CLI 的 `install()` 变为薄封装(stage → print 计划 → input 确认 → 迭代打印进度),
+行为与拆分前一致;Web 用 stage/preview + SSE 消费 progress。这是**根治「改两边」**
+的关键:核心函数只返回数据。
+
+### doctor 流式回调
+
+`doctor.run(fix, on_event=None)` 增加可选回调,`_apply_fixes` 重建 env 前后推送
+事件。向后兼容(不传回调行为不变)。
+
+### 全局 skill 项目级覆盖(D-15 读回)
+
+`list_skills(scope="project")` 会把所有全局 kit 的 skill 也列出,`SkillState` 带
+`is_global_skill` / `global_state` / `override` 三个字段(详见
+[09](09-state-api.md))。项目作用域下能「按项目单独覆盖」全局 skill:
+
+- 覆盖 `off` / `name-only`:写项目 `skillOverrides`,不影响全局。
+- `enabled`:清覆盖 = 跟随全局。
+- `installed`(purge)不允许:项目里没有 link 可删。
+
+CLI 与 Web 共用这套语义:CLI `list --project` 显示「项目覆盖 已关闭」或「跟随全局
+已启用」;Web 把全局 skill 单独折叠成一组,用独立的覆盖选择器(不复用四态),只展示
+当前全局状态下允许的选项。
+
+## 前端(`web/`)
+
+```
+src/
+  App.tsx                # 编排:SidebarProvider + AppSidebar + SidebarInset + 弹窗开关
+  lib/api.ts             # 类型 + fetch 封装(SSE 端点返回原生 Response)
+  lib/utils.ts           # cn()
+  hooks/useSSE.ts        # 消费 SSE 流(data: {json} 帧解析)
+  components/
+    AppSidebar / KitList / AddKitDialog / DoctorDialog / AddScopeDialog
+    ui/                  # shadcn 组件(button/dialog/dropdown-menu/tooltip/input/card/
+                         #   badge/progress/separator/popover/sonner/sidebar/sheet/skeleton)
+```
+
+- **布局**:dashboard 式——官方 `Sidebar`(variant=inset)+ 右侧 `SidebarInset`。
+  Sidebar 内:Header(CCKitKit + 版本)、4 个分组(作用域 / 添加关注项目 / Kit 管理 /
+  刷新)、Footer(清单预算,收起时变圆环);右侧顶部 `SidebarTrigger` 收起/展开。
+- **列表**:项目 kit 可收起/展开/卸载(卸载用 Popover + destructive 确认);skill
+  四态选择器(`name-only` 附解释)、`env_ok=False` 警示、`managed=False` 置灰只读;
+  全局 skill 单独折叠一组、无卸载按钮、用覆盖选择器。
+- **添加 Kit**:两阶段弹窗(表单 → 计划确认,lint error 禁用安装 → SSE 日志)。
+- **诊断**:`--fix` 勾选 + SSE 进度 + findings 结果。
+- **刷新三层**:侧栏刷新按钮 + 写操作后 `invalidateQueries` 自动重拉 + 可选轮询。
+  所有开关改动提示「**新会话生效**」(对齐 09 的语义)。
+- **提示框**:后端错误契约统一拦截,`set_state` 的返回串走 error、成功走 success。
+
+## 使用与部署
+
+**普通用户**（前端已随 wheel 打包，一条命令即用）：
+
+```bash
+uv tool install 'cckit[web]'
+cckit web    # 打开 http://127.0.0.1:8000 即用
+```
+
+**开发者**（源码仓库里改前端）：
+
+```bash
+# 开发调试
+uv run cckit web                 # 后端 :8000(不托管前端)
+cd web && npm run dev            # 前端 :5173(vite dev 代理 /api)
+
+# 生产 / 部署
+cd web && npm install && npm run build   # 产出 web/dist/，uv build 时打进 wheel
+uv run cckit web --host 0.0.0.0 --port 8000   # 自动定位前端，缺省也无需 --static-dir
+```
+
+**安全**:`--host` 默认 `127.0.0.1`。上服务器被浏览器访问时用 `--host 0.0.0.0`,
+⚠️ 放开即把「能装 kit(跑作者代码)、能改状态」的能力暴露给网段,只在可信内网用,
+必要时在反向代理层加鉴权。
+
+**iframe 融合**:后端托管前端后,宿主页 `<iframe src="http://<server>:<port>/">`
+即可。同源策略保证宿主页读不到 iframe 内部、也调不了 cckit 接口(无 CORS 问题);
+不设 `frame-ancestors` CSP(Starlette 默认即可嵌)。HTTPS 宿主嵌 `http://<server>`
+需在目标浏览器实测(Safari 较严)。
+
+## 验证
+
+- `uv run pytest -q` 82 项全绿(状态层 root 推广、installer 拆分后 CLI 行为不回归)。
+- `cd web && npm run build` 通过(tsc 类型检查 + vite 打包)。
+- 端到端:装 wheel 到隔离 venv 后 `cckit web` 一键启动,静态页面、`/api/*`、静态资源
+  均可达,非法 API 路径返回 404 而非 index.html。
+- 纯净性:`uv build`(不先跑前端构建)产出的 wheel 不含前端,`[web]` 依赖也不随
+  `uv tool install cckit` 安装;前端产物仅在前端 build 后才由 hatch 钩子打进 wheel。

{cckit-0.1.1 → cckit-0.2.1}/Docs/README.md

@@ -17,6 +17,7 @@
 | [08-installation.md](08-installation.md) | 分发方案与理由 | 打包发布时 |
 | [09-state-api.md](09-state-api.md) | 状态层契约、并发要求、Web 接入 | **实现 list/开关 或 Web 前必读** |
 | [10-kit-authoring.md](10-kit-authoring.md) | 开发手册:把普通 skill 改造成 kit | 发布 kit / 写 kit 时 |
+| [11-web-panel.md](11-web-panel.md) | Web 管理面板:架构、API、部署、iframe | 接入/部署 Web 或改前端时 |
 
 配套:[`schema/cckit.schema.json`](schema/cckit.schema.json)、
 [`examples/video-toolkit/`](examples/video-toolkit/)(参考 kit,应作为测试夹具)、
@@ -53,8 +54,8 @@
 
 ## 当前状态
 
-**v0.1 已实现**:`cckit` 命令行工具与全部 8 个命令(`add` / `list` / `enable` /
-`disable` / `name-only` / `remove` / `doctor` / `exec`),`uv run cckit --help` 可用。
+**v0.2.1 已实现**:`cckit` 命令行工具与全部 9 个命令(`add` / `list` / `enable` /
+`disable` / `name-only` / `remove` / `doctor` / `exec` / `web`),`uv run cckit --help` 可用。（0.2.0因为打包失误，版本号被弃用）
 
 已落地模块(`src/cckit/`):
 
@@ -67,8 +68,10 @@
 - `registry` —— registry.json 原子读写
 - `lint` —— 命名 / description / CRLF / prompt injection / typosquatting
 - `doctor` —— 只读诊断 + 安全修复
+- `projects` —— 关注项目清单 projects.json 原子读写
+- `web` —— Web 管理面板后端(FastAPI,惰性 import,`[web]` 可选依赖)
 
-测试:`tests/` 下 56 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
+测试:`tests/` 下 82 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
 
 ## v0.1 范围
 
@@ -77,10 +80,13 @@
 - 运行时只支持 Python(uv venv)与 Node
 - 依赖文件复用 `requirements.txt` / `package.json`,不自创格式
 - 四态开关、安装计划展示、`list` 报预算、`doctor` 全项检查
-- `cckit.state` 状态层(含文件锁与原子写)。Web 界面本身推迟,但**状态层在 v0.1 就要做对**
-  ——它是 Web 的接入点,事后补会导致两套逻辑
+- `cckit.state` 状态层(含文件锁与原子写)——CLI 与 Web 共用的唯一状态入口
 
-**推迟到 v0.2+**:`cckit.lock` 与 `sync`、`profile`、`update` 的 diff 展示、
+## v0.2 范围
+
+- Web 管理面板(`cckit web`):列表/导入/卸载/四态开关/诊断,iframe 融合(见 [11](11-web-panel.md))
+
+**推迟到 v0.3+**:`cckit.lock` 与 `sync`、`profile`、`update` 的 diff 展示、
 用量统计。
 
 ## 约定

cckit-0.2.1/Docs/pics/architecture.md

@@ -0,0 +1,63 @@
+# cckit 架构图
+
+```mermaid
+flowchart TB
+    subgraph CLI["cckit CLI · 8 个子命令"]
+        Add["add"]
+        List["list"]
+        Switch["enable / disable / name-only"]
+        Remove["remove"]
+        Doctor["doctor"]
+        Exec["exec"]
+    end
+
+    subgraph Core["核心模块 src/cckit/"]
+        Installer["installer · add 全流程"]
+        Manifest["manifest / schema · cckit.yaml 校验"]
+        Lint["lint · 安全检查"]
+        Env["env · 隔离环境"]
+        State["state · 四态派生 + 原子写"]
+        Registry["registry · registry.json 读写"]
+        Link["link · 目录链接"]
+        ExecMod["exec · 脚本执行"]
+        DoctorMod["doctor · 诊断修复"]
+        Config["config · 路径与平台"]
+    end
+
+    subgraph Storage["本地存储 ~/.cckit/"]
+        Store["store / kit / skill / SKILL.md"]
+        Envs["envs / kit__skill__runtime /"]
+        Reg["registry.json"]
+        Usage["usage.jsonl"]
+    end
+
+    subgraph CC["Claude Code 扫描目录"]
+        Global["全局 skills 目录"]
+        Project["项目 .claude/skills 目录"]
+    end
+
+    Add --> Installer
+    List --> State
+    Switch --> State
+    Remove --> Installer
+    Doctor --> DoctorMod
+    Exec --> ExecMod
+
+    Installer --> Manifest
+    Installer --> Lint
+    Installer --> Env
+    Installer --> Registry
+    Installer --> Link
+    Installer --> State
+    Installer --> Config
+
+    Env --> Envs
+    Registry --> Reg
+    State --> Usage
+    State -. 扫描 .-> Reg
+    Link --> Store
+    Link --> Global
+    Link --> Project
+    ExecMod --> Store
+    ExecMod --> Envs
+```

cckit-0.2.1/Docs/pics/directory-layout.md

@@ -0,0 +1,15 @@
+# 目录布局
+
+```mermaid
+flowchart TD
+    Root["~/.cckit/"] --> Store["store / {kit}/"]
+    Root --> Envs["envs / {kit}__{skill}__{runtime}/"]
+    Root --> Reg["registry.json"]
+    Root --> Usage["usage.jsonl"]
+
+    Store --> Skill["{skill} / SKILL.md"]
+    Store --> Yaml["cckit.yaml"]
+
+    Store -. "link（目录链接）" .-> Global["CC 配置目录 / skills / {skill}"]
+    Store -. "link" .-> Project["项目 / .claude / skills / {skill}"]
+```

cckit-0.2.1/Docs/pics/four-state-model.md

@@ -0,0 +1,16 @@
+# 四态模型示意图
+
+```mermaid
+flowchart TD
+    Skill["一个 skill"] --> HasLink{"是否已建立 link？"}
+
+    HasLink -- "否" --> Installed["installed<br/>CC 什么都看不到"]
+
+    HasLink -- "是" --> Override{"skillOverrides 状态？"}
+
+    Override -- "无覆盖" --> Enabled["enabled<br/>名字 + description"]
+
+    Override -- "name-only" --> NameOnly["name-only<br/>只有名字 · 不占预算"]
+
+    Override -- "off" --> Off["off<br/>CC 什么都看不到"]
+```

cckit-0.2.1/Docs/pics/install-flow.md

@@ -0,0 +1,15 @@
+# add 安装流程
+
+```mermaid
+flowchart LR
+    Start["cckit add<br/>git URL / 本地路径"] --> Clone["git clone<br/>锁 commit sha"]
+    Clone --> Validate["manifest 校验<br/>schema + 语义检查"]
+    Validate --> Lint["lint<br/>命名 / description / CRLF<br/>prompt injection / typosquatting"]
+    Lint --> Plan["展示执行计划<br/>等待确认（-y 跳过）"]
+    Plan --> Store["写入 store"]
+    Store --> Env["构建隔离环境<br/>venv / node_modules（uv）"]
+    Env --> Postinstall["运行 postinstall<br/>（限 kit 目录内）"]
+    Postinstall --> Registry["写 registry.json"]
+    Registry --> Link["建立 link<br/>→ CC 扫描目录"]
+    Link --> Done["完成 · enabled"]
+```

cckit-0.2.1/Docs/pics/pain-points-solution.md

@@ -0,0 +1,20 @@
+# 痛点与方案映射
+
+```mermaid
+flowchart TB
+    subgraph Problems["当前痛点"]
+        P1["Skill 数量多<br/>半串行执行 · 自由度有限"]
+        P2["依赖复杂<br/>部署困难"]
+        P3["迭代中舍弃了<br/>有潜力的 Skill"]
+    end
+
+    subgraph Solution["cckit 工具箱管理器"]
+        S1["四态开关<br/>精确控制调度与预算"]
+        S2["隔离环境 + 依赖检查<br/>一键部署"]
+        S3["工具箱化<br/>按需召回复用"]
+    end
+
+    P1 --> S1
+    P2 --> S2
+    P3 --> S3
+```

cckit-0.2.1/Docs/pics/state-transitions.md

@@ -0,0 +1,33 @@
+# 状态迁移图
+
+```mermaid
+stateDiagram-v2
+    direction LR
+
+    [*] --> installed : add
+
+    state "installed<br/>无 link · CC 看不到" as installed
+    state "enabled<br/>link ✓ · 名字 + description" as enabled
+    state "name-only<br/>link ✓ · 只有名字" as nameonly
+    state "off<br/>link ✓ · CC 看不到" as off
+
+    installed --> enabled : enable
+    installed --> nameonly : name-only
+
+    enabled --> off : disable
+    enabled --> nameonly : name-only
+    enabled --> installed : disable --purge
+
+    nameonly --> enabled : enable
+    nameonly --> off : disable
+    nameonly --> installed : disable --purge
+
+    off --> enabled : enable
+    off --> nameonly : name-only
+    off --> installed : disable --purge
+
+    installed --> [*] : remove
+    enabled --> [*] : remove
+    nameonly --> [*] : remove
+    off --> [*] : remove
+```

{cckit-0.1.1 → cckit-0.2.1}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.5
 Name: cckit
-Version: 0.1.1
+Version: 0.2.1
 Summary: Claude Code 的 Skill 工具箱管理器
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: packaging>=24.0
 Requires-Dist: pyyaml>=6.0
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == 'web'
+Requires-Dist: uvicorn>=0.30; extra == 'web'

{cckit-0.1.1 → cckit-0.2.1}/README.md

@@ -2,7 +2,7 @@
 
 # CCKitKit
 
-[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](#) [![版本](https://img.shields.io/badge/version-0.1.1-lightgrey)](#) [![测试](https://img.shields.io/badge/tests-82%20passed-brightgreen)](#)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](#) [![版本](https://img.shields.io/badge/version-0.2.1-lightgrey)](#) [![测试](https://img.shields.io/badge/tests-82%20passed-brightgreen)](#)
 
 </div>
 
@@ -12,7 +12,7 @@
 
 ## 安装
 
-**用户安装：**
+**用户安装（推荐）：**
 
 ```bash
 # 先装 uv
@@ -23,6 +23,8 @@
 uv tool install cckit
 ```
 
+从 Releases 下载安装： 见 [Releases](https://github.com/0Ra1n416/CCKitKit/releases) 。
+
 从源码安装（开发者）：
 
 ```bash
@@ -59,7 +61,49 @@ cckit doctor --fix           # 只修明确安全的项
 cckit exec my-skill scripts/run.py [args...]
 ```
 
-共 **8 个命令**：`add` / `list` / `enable` / `disable` / `name-only` / `remove` / `doctor` / `exec`。完整规格见 [Docs/cli-spec.md](Docs/cli-spec.md)。
+共 **9 个命令**：`add` / `list` / `enable` / `disable` / `name-only` / `remove` / `doctor` / `exec` / `web`。完整规格见 [Docs/cli-spec.md](Docs/cli-spec.md)。
+
+## Web 管理面板
+
+cckit 附带一个可选的管理面板（列表 / 导入 / 卸载 / 状态切换 / 诊断）。它是**纯增量**：不装 `[web]` 额外依赖时，`cckit` 本体与现在完全一样，`uv tool install cckit` 也不会带入任何 web 依赖。
+
+### 启用
+
+**普通用户**（前端已随 wheel 打包，一条命令即用）：
+
+```bash
+uv tool install 'cckit[web]'   # 带后端依赖 + 前端静态产物
+cckit web                       # 前后端一起起，打开 http://127.0.0.1:8000 即用
+```
+
+**开发者**（源码仓库里改前端）：
+
+```bash
+cd web && npm install && npm run build   # 产出 web/dist/，uv build 时打进 wheel
+cckit web                                 # 自动定位前端(包内 static → 源码 web/dist)
+
+# 开发调试：前端单独起 vite dev(自带 /api 代理)
+cckit web                # 后端(不托管前端)
+cd web && npm run dev    # 前端 dev server(:5173)，代理 /api 到 :8000
+```
+
+前端是 Vite + React 19 + Tailwind v4 + shadcn/ui，静态产物由后端托管。
+
+### 功能
+
+- **dashboard 布局**：`Sidebar`（可收起成图标条）+ 右侧内容区。
+- **作用域**：全局 + 装过 kit 的项目 + 手动「关注」的项目（即使暂无 skill 也显示，并自动建 `.claude`；关注项可取消关注）。
+- **kit 列表**：项目 kit 可收起/展开/卸载；每个 skill 带四态开关，`name-only` 附解释。
+- **全局 skill 项目覆盖**：项目作用域下，全局 skill 单独一组，可「跟随全局 / 仅名字 / 关闭」单独覆盖（不复用四态）。
+- **添加 Kit**：填仓库地址或本地路径 → 展示安装计划（依赖 / postinstall / 系统依赖 / 来源+sha）等确认 → 实时日志。
+- **诊断**：勾选 `--fix` 自动修复明确安全的项，下方展示逐项结果。
+- **刷新**：侧栏刷新按钮 + 写操作后自动刷新；所有开关改动提示「新会话生效」。
+
+### 安全与部署
+
+- 后端**默认只绑 `127.0.0.1`**。要作为服务器面板被浏览器访问时，用 `cckit web --host 0.0.0.0`。
+  ⚠️ 放开即把「能装 kit（跑作者代码）、能改 skill 状态」的能力暴露给网段，请只在可信内网使用，必要时在反向代理层加鉴权。
+- 嵌入其他页面用 **iframe**：后端托管前端后，宿主页 `<iframe src="http://<server>:<port>/">` 即可（同源隔离，无 CORS 问题）。
 
 ## 特色
 
@@ -166,11 +210,11 @@ uv run cckit --help     # 直接跑，无需安装
 uv tool install --editable .   # 本机可编辑安装
 ```
 
-代码结构（`src/cckit/`，16 个文件）：
+代码结构（`src/cckit/`，18 个文件，含 `web/` 子包）：
 
 | 模块 | 职责 |
 |---|---|
-| `cli.py` | argparse 分发到 8 个子命令 |
+| `cli.py` | argparse 分发到 9 个子命令 |
 | `installer.py` | `add` 全流程：锁 sha → 校验 → lint → 计划确认 → store/env/postinstall/registry/link |
 | `manifest.py` | `cckit.yaml` 加载 + schema 校验 + 语义检查 |
 | `schema.py` | JSON Schema 加载器（Draft 2020-12） |
@@ -183,3 +227,5 @@ uv tool install --editable .   # 本机可编辑安装
 | `doctor.py` | 只读诊断 + 安全修复 |
 | `config.py` | 路径与平台解析（`CCKIT_HOME` / `CLAUDE_CONFIG_DIR` / 项目根） |
 | `errors.py` | 受检错误 `CckitError` |
+| `projects.py` | 关注项目清单 `projects.json` 原子读写 |
+| `web/` | Web 管理面板后端（FastAPI，惰性 import，`[web]` 可选依赖） |

cckit-0.2.1/hatch_build.py

@@ -0,0 +1,27 @@
+"""hatch 构建钩子:若前端产物 web/dist 存在,把它作为 package data 打进 wheel。
+
+这样「完整构建」(先 `cd web && npm run build` 再 `uv build`)产出的 wheel 自带
+前端,用户 `uv tool install 'cckit[web]'` 后 `cckit web` 一键启动;「纯本体构建」
+(不跑前端构建)则 wheel 不含前端,核心安装保持纯净(见 Docs/11-web-panel.md)。
+
+要点:wheel 是从 sdist 解压目录构建的(uv build),所以 sdist 阶段要把 web/dist
+以**原始路径**带进 sdist,否则 wheel 阶段在解压目录里找不到它。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        dist = Path(self.root) / "web" / "dist"
+        if not (dist / "index.html").is_file():
+            return
+        if self.target_name == "sdist":
+            # sdist 保留原始路径,供 wheel 阶段从解压目录读取
+            build_data.setdefault("force_include", {})[str(dist)] = "web/dist"
+        else:  # wheel
+            # wheel 阶段把解压目录里的 web/dist 放到最终位置 cckit/web/static
+            build_data.setdefault("force_include", {})[str(dist)] = "cckit/web/static"

{cckit-0.1.1 → cckit-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cckit"
-version = "0.1.1"
+version = "0.2.1"
 description = "Claude Code 的 Skill 工具箱管理器"
 requires-python = ">=3.12"
 dependencies = [
@@ -9,6 +9,9 @@ dependencies = [
     "packaging>=24.0",
 ]
 
+[project.optional-dependencies]
+web = ["fastapi>=0.115", "uvicorn>=0.30"]
+
 [project.scripts]
 cckit = "cckit.cli:main"          # 装完后 `cckit` 命令指向这里
 
@@ -19,5 +22,17 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/cckit"]          # 显式声明 src layout
 
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.git",
+  "/.venv",
+  "/.claude",
+  "/dist",
+  "/web/node_modules",
+]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"           # 条件打包前端产物(web/dist 存在才打进 wheel)
+
 [dependency-groups]
 dev = ["pytest>=8"]               # uv sync 默认装上,供 `uv run pytest`

{cckit-0.1.1 → cckit-0.2.1}/src/cckit/__init__.py

@@ -5,4 +5,4 @@
 """
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"