Skip to content

CCKitKit v0.3.2

Choose a tag to compare

View all tags
@0Ra1n416 0Ra1n416 released this 10 Sep 16:29
· 1 commit to main since this release
v0.3.2
df87c92

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() 再清。
Assets 4
Loading