CCKitKit v0.3.3

cckit v0.3.3

Claude Code 的 Skill 工具箱管理器 —— 从任意 git 仓库拉取带环境依赖的 Skill，自动配置隔离环境，支持 skill 粒度的开关与干净卸载。

v0.3.3 是一个修复版本，只动卸载路径：从远程仓库装的 kit，在远程更新后重新 cckit add 会被"请先 remove"挡下，而 remove 又删不干净 —— store 里留下一个 .git，新版本于是永远装不上，remove 也说"未安装"了。

如果你正卡在这个状态，见下文「已经在死锁状态里怎么恢复」，一条命令即可。

---

从 Release 产物安装

从 wheel（推荐，最快）：

uv tool install ./cckit-0.3.3-py3-none-any.whl            # 纯命令行
uv tool install './cckit-0.3.3-py3-none-any.whl[web]'    # 带 Web 面板
uv tool install './cckit-0.3.3-py3-none-any.whl[alt]'    # 带非标准仓库导入(--alt)
uv tool install './cckit-0.3.3-py3-none-any.whl[web,alt]' # 面板 + 非标准仓库导入

从源码包（sdist）：

uv tool install ./cckit-0.3.3.tar.gz            # 纯命令行
uv tool install './cckit-0.3.3.tar.gz[web]'    # 带 Web 面板
uv tool install './cckit-0.3.3.tar.gz[alt]'    # 带非标准仓库导入

前置要求：先安装 uv（Windows PowerShell 可 irm https://astral.sh/uv/install.ps1 | iex），uv 会自己拉取所需 Python 版本，无需预装。

--alt 需要额外的 claude-agent-sdk（[alt] extra）；未装该 extra 时 --alt 会提示安装命令并以明确错误结束，不影响其余命令。

修复：remove 留下 .git，重新安装被卡住

现象（用户报告，Windows）：

$ cckit add https://github.com/someone/video-toolkit      # 远程已更新，想装新版
错误: kit 'video-toolkit' 已安装(store 已存在),请先 `cckit remove video-toolkit`

$ cckit remove video-toolkit
已移除 video-toolkit                                      # 看起来成功了

$ cckit add https://github.com/someone/video-toolkit
错误: kit 'video-toolkit' 已安装(store 已存在),请先 `cckit remove video-toolkit`

$ cckit remove video-toolkit
错误: kit 'video-toolkit' 未安装                           # remove 也不认它了

根因是两层叠加，单独任一层都不会致命：

1. 安装时 git clone 出的工作副本是连着 .git 一起被移入 store 的；
2. 删 store 用的是 shutil.rmtree(..., ignore_errors=True)，而 git for Windows 把 .git/objects/** 标成只读，os.unlink 抛 PermissionError 被这个 flag 吞掉 —— 命令报告成功，目录却还在。

实测复现（git init → git clone → shutil.rmtree(clone, ignore_errors=True)）：工作树文件全被删掉，只剩 .git/ 骨架里那批只读对象文件。此时 registry 记录已被清掉，残留再没有任何人能定位 —— 于是 add 说"已安装"、remove 说"未安装"，两头堵死。

修复（四条一起上）：

• 删目录统一走 fsutil.rmtree：失败回调里 os.chmod(path, 0o700) 后重试一次；ignore_errors 只决定"重试仍失败时是否抛出"，不再有"静默跳过只读文件"这条路。
• store 不再带 .git：落盘前剥离（来源与 commit sha 已记进 registry，git 历史对安装/卸载都没用）。--alt 流程一直如此，标准流程现在对齐。
• remove 不再谎报成功：确认真删掉了才报"已移除"；删不掉（文件被占用等）就抛错并保留 registry，让用户排掉占用后重跑一次 —— 而不是留下一个没人知道来历的残留目录。
• 删 store 前按目标路径反查 link（state.links_into）：registry 的 known_scopes 之外的 link 也收掉。悬空 link 同样占住 skill 名，一样会挡住下一次 add。

已经在死锁状态里怎么恢复

不用手动找目录，一条命令：

cckit remove <kit 名>    # 新版本会走"残留兜底"分支：清掉 store + 指向它的 link + <kit>__* env
cckit add <源>           # 重新装，这次 store 里不会再有 .git

registry 里若还留着记录，同一条命令走正常分支，结果一样。
残留目录也可以手动删掉，效果相同。

其他改进

• add 的报错不再误导：store 里已有同名目录时区分两种情况 —— registry 有记录 = 真装过，提示 cckit remove；registry 无记录 = 上次删到一半的残留，明确说是残留并指出目录路径。此前两种情况共用一句"已安装"，正是它把人引向"remove 后还是装不上"的死循环。
• doctor 新增 store 残留检查：store 下有 registry 无记录的目录时报一条 warn，并区分"没有 link 指向它（可清理）"与"仍有 link 指向它（像是 registry.json 丢失，别急着删）"。只报告不自动修 —— registry.json 若被人为删掉，自动清等于清空 store。
• 顺带修掉一处临时目录泄漏：安装取消/中断时，Windows 上 %TEMP%\cckit-clone-* 里同样会因只读 .git 而留下空壳，现在随 fsutil.rmtree 一并清干净。
• 测试从 189 项增至 207 项，其中 18 项是针对本次问题的新增回归（把 fsutil.rmtree 临时换回旧的 shutil.rmtree(ignore_errors=True) 写法，其中 5 项立刻变红）。

CCKitKit v0.3.2

cckit v0.3.2

Claude Code 的 Skill 工具箱管理器 —— 从任意 git 仓库拉取带环境依赖的 Skill，自动配置隔离环境，支持 skill 粒度的开关与干净卸载。

v0.3.2 是一个功能版本：新增 Skill 级用户配置 —— 作者声明"这个 Skill 需要哪些环境变量、哪些文件用户可以改"，用户在 CLI 与 Web 面板里填值，cckit exec 时自动注入。另外还有 Web 面板的管理员通知、同名 Skill 的明确报错，以及 kit-builder 仓库改造准确度的改进。

⚠️ 有一个针对 kit 作者的破坏性变更：manifest 顶层的 env 字段改名为 kit_env，仍写旧名的 kit 会被直接拒绝安装。详见下文。

---

从 Release 产物安装

从 wheel（推荐，最快）：

uv tool install ./cckit-0.3.2-py3-none-any.whl            # 纯命令行
uv tool install './cckit-0.3.2-py3-none-any.whl[web]'    # 带 Web 面板
uv tool install './cckit-0.3.2-py3-none-any.whl[alt]'    # 带非标准仓库导入(--alt)
uv tool install './cckit-0.3.2-py3-none-any.whl[web,alt]' # 面板 + 非标准仓库导入

从源码包（sdist）：

uv tool install ./cckit-0.3.2.tar.gz            # 纯命令行
uv tool install './cckit-0.3.2.tar.gz[web]'    # 带 Web 面板
uv tool install './cckit-0.3.2.tar.gz[alt]'    # 带非标准仓库导入

前置要求：先安装 uv（Windows PowerShell 可 irm https://astral.sh/uv/install.ps1 | iex），uv 会自己拉取所需 Python 版本，无需预装。

--alt 需要额外的 claude-agent-sdk（[alt] extra）；未装该 extra 时 --alt 会提示安装命令并以明确错误结束，不影响其余命令。

新能力：Skill 级用户配置

此前 cckit 只能声明一套 kit 级的环境变量，而且值必须由用户自己在 shell 里 export。Skill 作者只能用散文在 SKILL.md 里写"请先 export XXX"，用户装完看不出缺什么 —— 唯一的发现时机是脚本跑崩那一刻。

现在作者按 skill 粒度声明需要什么，用户直接在 CLI 与面板上填：

kit_env:                        # kit 共用：填一次，整个 kit 生效
  - name: OPENAI_API_KEY
    required: false             # 不填则跳过该步骤，不报错
    description: 用于字幕润色

skills:
  - name: burn-subtitles
    needs: [ffmpeg, python]
    scripts: [scripts/burn.py]
    env:                        # 该 Skill 专属；与 kit_env 同名时以此为准
      - name: FONT_DIR
        required: true          # 不填会让 cckit exec 直接报错中止
        description: 字幕字体所在目录
    conf_files: [config.json]   # 相对 Skill 目录，用户可以改

只声明，不写值 —— manifest 里没有放值的地方。这从根上杜绝了"作者把自己的密钥提交进仓库、随 kit 分发给所有用户"。

配套的 CLI 与面板：

cckit list --envs                            # 各 Skill 需要哪些环境变量（只报已设/未设，不回显明文）
cckit list --confs                           # 各 Skill 有哪些可改的配置文件
cckit env burn-subtitles FONT_DIR D:/fonts   # 填值

• cckit list 在 kit 行打 [env]、skill 行打 [envs] / [conf_files] 标记；有必需变量还没填时，对应行末尾会出现 ⚠ 缺必需变量 FONT_DIR → cckit env 提醒 —— 判定口径与 cckit exec 完全一致，不会出现"列表看着没事、一跑就报错"。
• Web 面板里每个 Skill 行有齿轮入口（环境变量 + 配置文件），kit 卡片头部也有一个（只有环境变量）。点开即可改值、预览和编辑配置文件，改完立即生效。
• 值存在 ~/.cckit/envs.json，不写 Claude Code 的 settings.json —— 那个键里装着用户的核心配置（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等），写坏等于 CC 直接不可用。注入只发生在 cckit exec 拉起脚本的那一刻，优先级为「用户填的 > 进程环境」；声明 required: true 却两处都取不到时会报错中止，不静默跳过。
• 配置文件路径在服务端校验：必须逐字命中声明、且解析后仍落在 Skill 目录内，所以 Web 上的"保存"不会被用来写任意文件。

⚠️ conf_files 里的文件就放在 Skill 目录下，cckit remove 或重装会连同 store 一起删除，用户改过的内容会丢。需要长期保留的数据请让脚本写到用户自己的目录。

新能力：面板管理员通知（--notice）

共享部署时可以在面板顶部挂一条公告，用来通知维护窗口：

cckit web --host 0.0.0.0 --notice "维护通知" ./notice.md

• 控件出现在 Skills 那一行的最右端，两行显示（「管理员通知」+ 你给的标题）；点开以纯文本显示文件内容。
• 不传 --notice 就完全不显示 —— 没有控件、没有额外请求。
• 标题随页面一起下发，首屏就渲染，不会先空一下再冒出来；正文在点开时才读，所以改了通知文件不用重启服务，正文也不会塞进每一次页面响应。
• 文件路径在启动时校验（写错当场报错退出，不用等用户点开才发现）；正文有 256 KiB 上限，非 UTF-8 也能正常显示。

⚠️ 通知内容对所有能访问面板的人都可见（尤其 --host 0.0.0.0 部署时）。不要往通知文件里放密钥。

⚠️ 破坏性变更：顶层 env 改名为 kit_env

为了让"环境变量"这组字段在 kit 级与 Skill 级保持一致的形状，manifest 顶层的 env: 更名为 kit_env:。

受影响的只有写了顶层 env: 的 kit 作者。 旧名不会被静默忽略 —— 它会被 JSON Schema 直接拒绝：

(root): Additional properties are not allowed ('env' was unexpected)

改法就是把字段名改掉，cckit: 1 不变：

-env:
+kit_env:
   - name: OPENAI_API_KEY
     required: false

为什么选择"明确拒绝"而不是兼容旧名：静默忽略会让作者以为自己声明的变量已经生效，而用户从头到尾看不到该填什么。现在这个问题会在 cckit add 阶段就暴露出来。

行为变更：同名 Skill 安装会被拒绝

同一作用域内已存在同名 Skill 时，安装阶段会直接拒绝并点名占用者，而不是静默跳过：

以下 skill 名在全局作用域已被占用,同一作用域内 skill 名必须唯一:
  - foo: 已被 kit 'kit-a' 占用 → 先 `cckit remove kit-a`(或 `cckit disable foo --purge`)释放该名字
可用 `--only <skill,...>` 排除这些 skill,或按上面的提示释放该名字后重试。

此前这种情况是静默失效：建链接那一步（cckit.state.set_state）见到同名 link 直接跳过，后装的 Skill 只写进 registry 却永远建不上链接 —— 表现为"装好了但 CC 从不调用"，此后按名执行 enable / disable / exec 还会因为归属歧义全部报错。

跨作用域的同名仍然允许（全局一份 + 某个项目一份），由 CC 的优先级决定谁生效，cckit doctor 会给出提示。--only 排除掉的 Skill 不参与检查。

其他改进

• kit-builder 改造更准：--alt 依赖 Claude Code 把普通仓库改造成标准 kit，此前它对 kit_env / env / conf_files 常有遗漏。现在 Skill 里补了一套可执行的发现流程 —— 逐个脚本搜环境变量读取点（os.environ / os.getenv / process.env / $VAR）、按"被几个 Skill 读"决定放 kit 级还是 Skill 级、按"取不到会不会报错"决定 required，并要求改造时逐条给出依据。--alt 的改造与审计提示词同步收紧，漏声明现在会导致审计不通过。
• 修复测试的临时目录泄漏：Web 相关测试的夹具清理时只丢了引用、没删 StagedInstall 持有的临时目录，每跑一次测试就在系统临时目录里留下两个空壳，现已改为先 cleanup() 再清。

CCkitkit v0.3.1

cckit v0.3.1

Claude Code 的 Skill 工具箱管理器 —— 从任意 git 仓库拉取带环境依赖的 Skill，自动配置隔离环境，支持 skill 粒度的开关与干净卸载。

v0.3.1 是一个小版本：为 Web 管理面板新增子路径部署能力，并修复 v0.3.0 的两个问题（kit-builder 未随包分发、安装弹窗残留状态）。

---

从 Release 产物安装

从 wheel（推荐，最快）：

uv tool install ./cckit-0.3.1-py3-none-any.whl            # 纯命令行
uv tool install './cckit-0.3.1-py3-none-any.whl[web]'    # 带 Web 面板
uv tool install './cckit-0.3.1-py3-none-any.whl[alt]'    # 带非标准仓库导入(--alt)
uv tool install './cckit-0.3.1-py3-none-any.whl[web,alt]' # 面板 + 非标准仓库导入

从源码包（sdist）：

uv tool install ./cckit-0.3.1.tar.gz            # 纯命令行
uv tool install './cckit-0.3.1.tar.gz[web]'    # 带 Web 面板
uv tool install './cckit-0.3.1.tar.gz[alt]'    # 带非标准仓库导入

前置要求：先安装 uv（Windows PowerShell 可 irm https://astral.sh/uv/install.ps1 | iex），uv 会自己拉取所需 Python 版本，无需预装。

--alt 需要额外的 claude-agent-sdk（[alt] extra）；未装该 extra 时 --alt 会提示安装命令并以明确错误结束，不影响其余命令。

新能力：Web 面板子路径部署（--base）

此前 Web 面板的前后端都把 /api/*、/assets/* 硬编码为绝对路径，用 <iframe> 嵌入宿主 dashboard 时，面板的请求会撞上 dashboard 自身的 /api，无法挂到子路径。

现在 cckit web 支持 --base 根路径前缀：

cckit web --host 0.0.0.0 --base /cckit

• 后端把整站（/cckit/api/*、/cckit/assets/*）运行时挂到该前缀下，反向代理只需把 /cckit/* 原样转发；
• 宿主页 <iframe src="http://<server>:<port>/cckit/"> 即可，不再与宿主 /api 冲突；
• --base 是运行时配置：后端把 window.__CCKIT_BASE__ 注入 index.html、前端资源用相对路径（Vite base: "./"），无需重新构建前端；不传 --base 时行为与之前完全一致。

修复

• kit-builder 未随包分发：修复 uv tool install 'cckit[web,alt]' 后，Web 面板勾选「允许导入非标准仓库」检测不到 skills/kit-builder、无法给出「安装」选项的问题。现在 skills/kit-builder 始终随 wheel 打包到 cckit/skills/kit-builder。
• 安装弹窗残留状态：修复安装成功后关闭弹窗，再次点击「添加 Kit」仍显示上一次「安装成功」的问题；现在每次打开弹窗都会重置到初始表单。

CCkitkit v0.3.0

cckit v0.3.0

Claude Code 的 Skill 工具箱管理器 —— 从任意 git 仓库拉取带环境依赖的 Skill，自动配置隔离环境，支持 skill 粒度的开关与干净卸载。

本次发布带来一项新能力：非标准仓库导入（--alt）。此前 cckit 要求仓库根目录必须有合法的 cckit.yaml，普通 Skill 仓库一律无法安装；现在可以借助 Claude Code 把普通 Skill 仓库自动改造成标准 kit 后导入。

---

从 Release 产物安装

从 wheel（推荐，最快）：

uv tool install ./cckit-0.3.0-py3-none-any.whl          # 纯命令行
uv tool install './cckit-0.3.0-py3-none-any.whl[web]'  # 带 Web 面板
uv tool install './cckit-0.3.0-py3-none-any.whl[alt]'  # 带非标准仓库导入(--alt)

从源码包（sdist）：

uv tool install ./cckit-0.3.0.tar.gz          # 纯命令行
uv tool install './cckit-0.3.0.tar.gz[web]'  # 带 Web 面板
uv tool install './cckit-0.3.0.tar.gz[alt]'  # 带非标准仓库导入

前置要求：先安装 uv（Windows PowerShell 可 irm https://astral.sh/uv/install.ps1 | iex），uv 会自己拉取所需 Python 版本，无需预装。

--alt 需要额外的 claude-agent-sdk（[alt] extra）；未装该 extra 时 --alt 会提示安装命令并以明确错误结束，不影响其余命令。

非标准仓库导入（--alt）

普通 Skill 仓库通常不会为了 cckit 预先采用 cckit.yaml 目录结构。此前这类仓库会被直接拒绝安装。现在显式加上 --alt（或 Web 里的开关），cckit 会在安装前用 Claude Code 把它改造成标准 kit：

# 前置依赖：alt extra（含 claude-agent-sdk）
uv tool install 'cckit[alt]'

# 导入一个没有 cckit.yaml 的普通 skill 仓库
cckit add https://github.com/someone/my-skill --alt
cckit add ./my-skill --local --alt

流程：物化（拉取 / 复制）→ 用 kit-builder 改造 → 确定性校验（manifest / schema / 语义 / lint）→ Claude Code 审计 → 复用现有安装流程（安装计划确认、回滚）。

• 标准仓库不碰 LLM：只要仓库已有合法 cckit.yaml，即使带 --alt 也走原有确定性流程。
• 前置条件检查：需要 claude-agent-sdk 可导入 + 全局 kit-builder 处于 enabled；缺失、冲突或状态不合适时会明确提示，可自动修复的才允许一键安装 / 切换，不静默覆盖。
• Web 三阶段面板：「添加 Kit」弹窗新增「允许导入非标准仓库」开关（默认关闭），转换过程实时展示「准备仓库 / 改造仓库 / 审计结果」三个阶段的子步骤、文本、工具调用与错误，前端只认结构化字段、不靠自由文本判断状态。
• 审计是语义层补充：审计失败、无法完成或结论不明确时不得继续安装；不可绕过的安全闸门仍是确定性校验 + 安装计划确认 + 回滚。

修复

• 修复 Windows 上安装带 Node 依赖的 kit 时报 [WinError 2] 系统找不到指定的文件：npm 在 Windows 上是 npm.cmd，Python 的 subprocess 无法直接执行 .cmd，现已经 cmd /c 转发。

安全说明

--alt 会在安装前调用 Claude Code 改造并审计临时目录里的仓库，请知悉：

• 它会调用 Claude Code 修改临时目录中的仓库；临时目录在成功、失败、取消、Ctrl+C 后都会被清理。
• 权限模式是 auto——由 Claude Code 自动判断每个工具调用是否放行，不是无条件放行；不设 can_use_tool、不用 bypassPermissions，并隔离了仓库自带的 .claude/settings*.json 与 .mcp.json。
• alt 流程不记录改造后的 SHA，只保留原始来源 URL / ref。
• ⚠️ 安装一个 kit 等同于在本机运行该仓库作者的代码。请只对你信任的来源使用 --alt，并在安装前阅读 cckit 展示的执行计划。

CCkitkit v0.2.1

cckitkit v0.2.1

Claude Code 的 Skill 工具箱管理器 —— 从任意 git 仓库拉取带环境依赖的 Skill，自动配置隔离环境，支持 skill 粒度的开关与干净卸载。

本次发布是 v0.1.x 之后的首个功能版本，带来两大能力：Web 管理面板与全局 skill 项目级覆盖。

---

从 Release 产物安装

从 wheel（推荐，最快）：

uv tool install ./cckit-0.2.1-py3-none-any.whl          # 纯命令行
uv tool install './cckit-0.2.1-py3-none-any.whl[web]'  # 带 Web 面板

从源码包（sdist）：

uv tool install ./cckit-0.2.1.tar.gz          # 纯命令行
uv tool install './cckit-0.2.1.tar.gz[web]'  # 带 Web 面板

前置要求：先安装 uv（Windows PowerShell 可 irm https://astral.sh/uv/install.ps1 | iex），uv 会自己拉取所需 Python 版本，无需预装。

Web 管理面板

新增可选的 Web 管理面板，一条命令即可启动：

uv tool install 'cckit[web]'
cckit web    # 打开 http://127.0.0.1:8000

• dashboard 布局：官方 Sidebar（可收起成图标条）+ 右侧内容区
• 作用域管理：全局 / 项目 / 手动「关注」的项目，支持添加、取消关注
• skill 列表：四态开关（installed / enabled / name-only / off），kit 可收起/展开/卸载
• 添加 Kit：填仓库地址或本地路径 → 展示安装计划（依赖 / postinstall / 系统依赖 / 来源+sha）等确认 → 实时日志
• 诊断：勾选 --fix 自动修复明确安全的项，逐项展示结果
• 清单预算：可视化进度条，侧栏收起时自动变成圆环进度条

前端产物随 wheel 打包，uv tool install 'cckit[web]' 后开箱即用，无需源码。后端默认只绑 127.0.0.1，部署时用 cckit web --host 0.0.0.0（详见安全说明）。

全局 skill 项目级覆盖

项目作用域下现在能看到所有全局 skill，并可「按项目单独覆盖」——跟随全局 / 仅名字 / 关闭，不影响全局状态。

• CLI：cckit list --project 明确显示「项目覆盖 已关闭」或「跟随全局 已启用」
• Web：全局 skill 单独折叠一组，覆盖选择器只展示当前全局状态下允许的选项（不复用四态）

修复

• 修复 v0.2.0 sdist（源码包）误打包前端依赖 node_modules 的问题， 因此 v0.2.0 版本号被完全弃用

技术栈

• 后端：Python 3.12+ / FastAPI + uvicorn（[web] 可选依赖，核心仍是 3 个运行时依赖）
• 前端：Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui

CCkitkit v0.1.1

CCkitkit v0.1.1

推荐 从 PyPI 直接装：

uv tool install cckit

安装产物（两个包任选其一即可）：

# wheel（推荐，直接装）
uv tool install cckit-0.1.1-py3-none-any.whl

# 或 sdist（源码包，需要本地构建）
uv tool install cckit-0.1.1.tar.gz

cckit 装好后：cckit --help 查看全部 8 个命令。