cckit 0.2.1__tar.gz → 0.3.0__tar.gz

cckit-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+release-notes/
+.claude/
+TODO.md

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

@@ -4,4 +4,7 @@
 README.md
 
 # ignore pics
-pics/
+pics/
+
+# ignore test skills
+test/

{cckit-0.2.1 → cckit-0.3.0}/Docs/02-architecture.md

@@ -89,6 +89,21 @@ skill,全局 `--purge` 还会清掉它在各项目根留下的项目级覆盖(
 **纯 prompt 类 skill 不创建 env。** 由 manifest 的 `needs: []` 表达,装它时完全不触发
 环境安装。
 
+## 非标准仓库导入(alt)
+
+标准安装的唯一硬判据是仓库根目录有合法 `cckit.yaml`;没有它,`cckit add` 直接拒绝。
+`--alt`(或 Web 的「允许导入非标准仓库」开关)是一条**显式开启的旁路**:
+
+    物化(pull/copy)→ kit-builder 改造 → 确定性校验 → Claude Code 审计 → 复用本地安装。
+
+- **标准仓库不碰 LLM**:即使带 `--alt`,只要有 `cckit.yaml` 就走原确定性流程。
+- **Claude Code 只做改造与审计,不做安装**:安装仍是 `stage_install → execute_install`
+  的确定性管线,审计失败/不明确即中止。
+- **`alt.py` 是编排层**:负责前置条件(claude-agent-sdk 可导入 + 全局 `kit-builder`
+  处于 enabled)、临时目录生命周期、物化、Agent SDK 调用、事件转发、取消与清理;复用
+  `installer.stage_install` / `execute_install`,不复制安装逻辑。
+- 安全边界见 [07-security.md](07-security.md);决策记录见 [05-design-log.md](05-design-log.md) 的 D-16。
+
 ## 状态真相来源
 
 避免多处记录同一事实导致漂移:

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

@@ -409,6 +409,51 @@ Web 把全局 skill 单独折叠一组、用独立覆盖选择器(不复用四
 
 ---
 
+## D-16 非标准仓库导入:显式开启的 alt 流程
+
+**提出的问题**:普通 Skill 仓库通常不会为了 cckit 预先采用 `cckit.yaml` 目录结构,
+于是 `cckit add` 对它们一律拒绝,扩展性受限。能否放宽?
+
+**最终方案**:不放宽标准校验,而是加一个**显式开启**(`--alt` / Web 开关)、经过
+前置条件检查、由 Claude Code 辅助改造的可选 `alt` 流程:
+
+    物化 → kit-builder 改造 → 确定性校验 → Claude Code 审计 → 复用本地安装。
+
+标准仓库即使带 `--alt` 也走原流程、**不调用 Claude Code**——alt 只是"发现非标准时
+允许转换",不是"所有仓库都过一遍 LLM"。
+
+**为什么这样定**:
+
+- **不改 `manifest.py` 放宽校验。** 标准 Kit 的唯一硬判据仍是根目录有合法
+  `cckit.yaml`。alt 是标准安装之外的一条旁路,不是给标准校验松绑。这也保证了
+  D-01「确定性安装不碰 LLM」对标准仓库仍然成立。
+- **Claude Code 只做改造与审计,不做安装。** 安装仍是 `stage_install →
+  execute_install` 的确定性管线。审计是语义层补充,不可绕过的安全闸门仍是
+  manifest 校验 + lint + 安装计划确认 + 回滚。
+- **`kit-builder` 的唯一可信来源是当前源码树。** 同名 Skill 在网络上不可依赖,
+  所以自动安装只能等价 `cckit add <abs>/skills/kit-builder --local` 到全局。
+  检测到同名冲突、来源冲突、项目作用域安装时一律停止,不静默覆盖。
+- **不伪造 SHA。** 改造后临时目录已非原始仓库状态,本地目录可能根本没有 Git。
+  alt 最终按本地目录交给安装接口,registry 不记录改造后 SHA,只保留原始来源 URL/ref。
+- **权限用 `auto`,不设 `can_use_tool`、不用 `bypassPermissions`。** 一旦设了
+  `can_use_tool`,SDK 会把权限请求转交回调,`auto` 的自动判断就不再生效,退化成
+  逐工具人工确认。`auto` 是"由模型自动判断是否放行",不是无条件放行。
+- **隔离仓库自带的 settings/MCP。** `cwd` 指向的是不可信仓库的副本,若照默认加载,
+  仓库里的 `.claude/settings.json`(权限 allow-list、additionalDirectories)与
+  `.mcp.json`(MCP 服务器)会被 Claude Code 读入,等于让仓库给自己授权、甚至借
+  MCP 初始化执行任意代码。故 `setting_sources=["user"]`(只加载用户级 settings,
+  含 kit-builder 的 enabled 态,跳过 project/local)+ `strict_mcp_config=True`
+  (忽略一切 MCP 配置)。
+- **`cwd` 不是沙箱。** 它只是把 Agent 的工作目录限定在临时仓库,不能误认为完整
+  文件系统隔离。真正的防线仍是确定性校验 + 安装计划确认(与 D-02 一致)。
+- **临时目录在最外层 `try/finally` 清理。** 成功、失败、取消、Ctrl+C 都要清掉
+  `cckit-alt-*` 目录,并关闭 SDK client 与底层 CLI 子进程。
+
+**代价(必须记录)**:alt 在安装前多跑两次 LLM 调用(builder + audit),成本与
+不确定性都比标准安装高;且 `auto` 权限模式下模型仍可能在临时仓库里执行
+kit 作者诱导的操作。因此审计这一步聚焦 prompt injection / 敏感读取 / 外传 /
+越界,并要求输出明确的 PASS/FAIL 结论,结论不明确一律视为不通过。
+
 ## 我的判断失误汇总
 
 集中列出,便于后续开发者校准对本文档其余部分的信任度:

{cckit-0.2.1 → cckit-0.3.0}/Docs/06-platform-findings.md

@@ -192,6 +192,10 @@ os.open(O_CREAT|O_EXCL) 加锁 + os.replace → 8 条完整保留
 
 - **venv 布局**:Windows `.venv/Scripts/python.exe`,POSIX `.venv/bin/python`。
   这是 `cckit exec` 存在的理由之一——SKILL.md 里不写解释器路径。
+- **npm 是 .cmd(已实测)**:Windows 上 `subprocess.run(["npm", ...])` 抛
+  `FileNotFoundError`(WinError 2)——Python 的 `CreateProcess` 只能直接执行 `.exe`,
+  找不到 `.cmd`。`env.create_node_env` 已用 `cmd /c` 转发(不用 shell=True,避免
+  路径含空格时的注入)。实测 npm install 成功。
 - **大小写敏感**:Linux 上 `Foo` 与 `foo` 是两个目录(已实测),Windows 上是一个。
   故 skill 名强制小写 kebab-case,lint 拒大写。否则同一 kit 在 Linux 装出两个 skill、
   在 Windows 装出一个。

{cckit-0.2.1 → cckit-0.3.0}/Docs/07-security.md

@@ -106,6 +106,40 @@ Web 管理界面能改 CC 行为、能触发安装(而安装会执行仓库作
 **绝不能监听 `0.0.0.0`。** 确需远程访问必须加鉴权。这条要写在用户文档显眼处,
 不能默认放开让用户自己发现。
 
+## alt 流程的安全边界(非标准仓库导入)
+
+`--alt` 会在安装前调用 Claude Code 去改造并审计一个**临时目录里**的仓库。它没有
+推翻上面的任何一条硬要求,只是在标准安装之前插入了一段 LLM 辅助的改造。额外的
+边界如下:
+
+- **标准仓库不碰 LLM。** 仓库根目录已有合法 `cckit.yaml` 时,即使带 `--alt` 也走
+  原确定性流程。alt 只在"没有 `cckit.yaml` 且显式开启"时触发。
+- **权限是 `auto`,不是无条件放行。** `ClaudeAgentOptions(permission_mode="auto")`
+  由 Claude Code 自动判断每个工具调用是否放行。**不设置** `can_use_tool`(否则
+  回调会接管权限判断、退化成逐工具人工确认),**不使用** `bypassPermissions`。
+- **`cwd` 只是工作目录,不是沙箱。** 它把 Agent 的工作目录限定在临时仓库,但不能
+  误认为完整文件系统隔离。SDK 的 sandbox 配置主要作用于 Bash 沙箱、依赖
+  macOS/Linux,而本项目重点环境是 Windows,故不采用 `bypassPermissions + sandbox`。
+- **隔离仓库自带的 settings/MCP。** `cwd` 是不可信仓库的副本,必须阻止它自我授权:
+  `setting_sources=["user"]` 只加载用户级 settings(含 kit-builder 的 enabled 态),
+  跳过仓库自带的 `.claude/settings*.json`(权限 allow-list / additionalDirectories);
+  `strict_mcp_config=True` 忽略仓库自带的 `.mcp.json`,避免借 MCP 初始化执行任意代码。
+- **确定性校验与安装计划确认仍是不可绕过的闸门。** 改造完成后依次跑
+  `manifest.load → validate_schema → semantic_check → lint`,审计通过后再走
+  `stage_install` 的安装计划展示与用户确认、`execute_install` 的回滚。审计失败、
+  无法完成或结论不明确时不得继续。
+- **审计聚焦语义层威胁。** 重点看 `cckit.yaml` 是否忠实反映仓库内容、是否添加了
+  不必要或危险的 `postinstall`、是否存在 prompt injection / 敏感文件读取 /
+  外传数据 / 越界操作意图。
+- **不记录改造后的 SHA。** 改造后的临时内容已非原始仓库状态,registry 保留原始
+  来源 URL / ref,但**不**把原始 SHA 误标为改造后内容的 SHA。
+- **临时目录必然清理。** 成功、失败、取消、Ctrl+C 都在最外层 `try/finally` 清理
+  `cckit-alt-*` 目录,并关闭 SDK client 与底层 CLI 子进程。
+
+> ⚠️ `--alt` 意味着在安装前,Claude Code 会拿着工具执行权限去读并改造一个陌生仓库。
+> 它比标准安装多暴露一层"仓库内容影响一个带工具权限的 agent"的风险。请只对
+> **你信任的来源**使用 `--alt`。
+
 ## 明确不做的事
 
 ### 不让 CC 读 README 自行配置环境

{cckit-0.2.1 → cckit-0.3.0}/Docs/08-installation.md

@@ -17,6 +17,18 @@ uv tool install cckit
 **用户不需要预装 Python。** `uv` 是独立静态二进制,会自己拉 cckit 需要的 Python 3.12+。
 安装前提只有 `uv` 一个。
 
+## 可选 extra
+
+cckit 本体只有 3 个依赖。两个可选功能各自独立成 extra,不装则完全不影响:
+
+```bash
+uv tool install 'cckit[web]'   # Web 管理面板(FastAPI + 前端静态产物)
+uv tool install 'cckit[alt]'   # 非标准仓库导入(--alt,含 claude-agent-sdk)
+```
+
+`--alt` 依赖 `claude-agent-sdk`,只在需要把普通 skill 仓库改造成 kit 时才需要;
+未装该 extra 时,`cckit add <src> --alt` 会提示安装命令并以明确错误结束。
+
 ## 为什么是 `uv tool install`
 
 ### `pip install` 出局:Linux 上被 PEP 668 拒绝

{cckit-0.2.1 → cckit-0.3.0}/Docs/11-web-panel.md

@@ -1,6 +1,6 @@
 # Web 管理面板
 
-配套 v0.2.1 的可选管理面板:平时展示 skill 列表,支持导入（add）、卸载（remove）、
+配套 v0.3.0 的可选管理面板:平时展示 skill 列表,支持导入（add）、卸载（remove）、
 四态开关切换、诊断（doctor）。**纯增量**——不装 `[web]` 额外依赖时,`cckit` 本体
 与命令行工具完全不变。
 
@@ -60,6 +60,11 @@ FastAPI (src/cckit/web/)  ── 静态托管 web/dist/
 | `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 |
+| `GET /api/add/alt/check` | `alt.check_sdk_available` + `alt.kit_builder_status` | alt 开关的前置条件检查 |
+| `POST /api/add/alt/fix` | `alt.apply_kit_builder_fix` | 修复 kit-builder(安装/切 enabled),重新校验前置条件防冲突/来源不一致 |
+| `POST /api/add/alt/start` | `alt.run_alt_conversion`(后台线程) | 三阶段转换,SSE `alt_progress`/`alt_done`/`alt_error`/`alt_cancelled` |
+| `POST /api/add/alt/cancel` | 取消标志 + `ClaudeSDKClient.interrupt` | 终止后台转换,等线程结束 + 清理 |
+| `POST /api/add/alt/complete` | `installer.stage_install` | 转换结果交给现有本地安装流程 |
 
 错误契约:`CckitError`(含 `InstallError`)统一捕获 → `{error:{message}}` + 400;
 参数校验失败 → 422。前端只读 `message`,不依赖状态码区分。
@@ -116,6 +121,24 @@ CLI 与 Web 共用这套语义:CLI `list --project` 显示「项目覆盖 已关
 已启用」;Web 把全局 skill 单独折叠成一组,用独立的覆盖选择器(不复用四态),只展示
 当前全局状态下允许的选项。
 
+### 非标准仓库导入(alt)
+
+「添加 Kit」弹窗新增「允许导入非标准仓库」开关(默认关闭)。开启时立即执行与 CLI 一致的
+前置条件检查:未装 `alt` extra → 提示 `uv tool install 'cckit[alt]'`;`kit-builder`
+缺失/冲突/状态不合适 → 分别给出安装、修改或仅关闭的处理,开关保持关闭;全部满足才保持开启。
+
+标准仓库不触发转换,直接复用原有「计划 → 确认 → 安装」流程。非标准仓库则进入三阶段
+进度面板(准备仓库 / 改造仓库 / 审计结果),后端在**独立后台线程**里跑 `alt` 流程,
+线程内部用 `asyncio.run()` 执行 Claude Agent SDK,通过线程安全队列 → 现有 SSE 机制把
+结构化事件(`event: alt_progress`,含 `stage` / `kind` / `message`)推给前端。前端
+**不依赖自由文本判断阶段状态**,只认结构化字段。
+
+三阶段全部成功后「完成」才可点击;点击后把转换出的临时 Kit 交给现有 `stage_install`,
+复用安装计划弹窗、lint 展示、确认与安装进度。「终止」不只断开 SSE:设置取消标志、
+请求 `ClaudeSDKClient` 断开、等待后台线程结束、清理临时目录,并向前端发 `cancelled`。
+转换、取消、出错、浏览器断开等路径都保证临时目录最终被清理,清理完成前不报告
+「资源已全部释放」。
+
 ## 前端(`web/`)
 
 ```

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

@@ -54,7 +54,7 @@
 
 ## 当前状态
 
-**v0.2.1 已实现**:`cckit` 命令行工具与全部 9 个命令(`add` / `list` / `enable` /
+**v0.3.0 已实现**:`cckit` 命令行工具与全部 9 个命令(`add` / `list` / `enable` /
 `disable` / `name-only` / `remove` / `doctor` / `exec` / `web`),`uv run cckit --help` 可用。（0.2.0因为打包失误，版本号被弃用）
 
 已落地模块(`src/cckit/`):
@@ -63,6 +63,7 @@
 - `config` / `schema` / `manifest` —— 配置解析、JSON Schema + 语义校验
 - `env` —— uv venv / node env 与解释器解析
 - `installer` —— add 全流程(锁 sha、计划确认、store/env/postinstall/registry/link)
+- `alt` —— 非标准仓库导入(前置条件 → 物化 → kit-builder 改造 → 审计 → 复用本地安装)
 - `exec` —— skill 脚本统一入口(白名单 + 环境变量注入)
 - `state` —— 四态派生 + 文件锁 + 原子写 + 清单预算
 - `registry` —— registry.json 原子读写
@@ -71,7 +72,7 @@
 - `projects` —— 关注项目清单 projects.json 原子读写
 - `web` —— Web 管理面板后端(FastAPI,惰性 import,`[web]` 可选依赖)
 
-测试:`tests/` 下 82 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
+测试:`tests/` 下 126 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
 
 ## v0.1 范围
 
@@ -86,7 +87,13 @@
 
 - Web 管理面板(`cckit web`):列表/导入/卸载/四态开关/诊断,iframe 融合(见 [11](11-web-panel.md))
 
-**推迟到 v0.3+**:`cckit.lock` 与 `sync`、`profile`、`update` 的 diff 展示、
+## v0.3 范围
+
+- 非标准仓库导入(`--alt` / Web 开关):对没有 `cckit.yaml` 的普通 skill 仓库,
+  由 Claude Code(kit-builder)改造 + 审计后复用现有安装流程;标准仓库不碰 LLM。
+  详见 [cli-spec](cli-spec.md)、[02](02-architecture.md) 的 alt 节、[05](05-design-log.md) 的 D-16。
+
+**推迟到 v0.4+**:`cckit.lock` 与 `sync`、`profile`、`update` 的 diff 展示、
 用量统计。
 
 ## 约定

{cckit-0.2.1 → cckit-0.3.0}/Docs/cli-spec.md

@@ -36,8 +36,49 @@ cckit add ./local-kit --project --local
 | `--no-enable` | 只装不启用(落到 `installed` 态) |
 | `--project` | 装到当前项目而非全局 |
 | `--only <skill,...>` | 只启用 kit 中的部分 skill |
+| `--alt` | 允许导入非标准仓库(没有 `cckit.yaml` 的普通 skill 仓库),由 Claude Code 改造 |
 | `-y` | 跳过确认。CI 用,文档需警示风险 |
 
+### 非标准仓库导入(`--alt`)
+
+默认情况下,仓库根目录没有合法 `cckit.yaml` 会直接拒绝安装。加上 `--alt` 后,
+cckit 会在**显式开启、经过前置条件检查**的前提下,调用 Claude Code 把一个普通
+skill 仓库改造成标准 kit,再复用现有安装流程:
+
+```bash
+# 前置依赖:alt extra(内含 claude-agent-sdk)
+uv tool install 'cckit[alt]'
+
+# 导入一个普通 skill 仓库(没有 cckit.yaml)
+cckit add https://github.com/someone/my-skill --alt
+cckit add ./my-skill --local --alt
+```
+
+流程:
+
+1. 把远程仓库按 `--ref` 拉取、或把本地目录复制到临时目录(总是剥离 `.git`);
+2. 若仓库根目录已有 `cckit.yaml`,**仍走标准流程,不调用 Claude Code**;
+3. 前置条件检查:`claude-agent-sdk` 可导入 + 全局 `kit-builder` 处于 `enabled`;
+   - 未装 SDK → 提示 `uv tool install 'cckit[alt]'` 并以错误结束;
+   - `kit-builder` 缺失/状态不合适 → 提示修复命令,无冲突时可选择自动修复;
+   - 存在作用域/来源冲突 → 停止,不静默覆盖;
+4. 以临时仓库为 `cwd` 调用 `kit-builder` 改造仓库;
+5. 确定性校验:`manifest.load → validate_schema → semantic_check → lint`;
+6. 调用 Claude Code **审计**改造结果(prompt injection、敏感读取、外传、越界等);
+7. 只有校验与审计都通过,才把临时目录作为本地 Kit 交给现有安装接口,继续沿用
+   `--project` / `--no-enable` / `--only` / `-y` 等参数与安装计划确认;
+8. 无论成功、失败、取消还是 Ctrl+C,临时目录都在最外层 `try/finally` 清理。
+
+安全边界(详见 [07-security.md](07-security.md) 与 [05-design-log.md](05-design-log.md)):
+
+- 使用 `ClaudeAgentOptions(permission_mode="auto", cwd=临时目录)`,**不设置**
+  `can_use_tool`,**不使用** `bypassPermissions`;`auto` 是自动权限判断,不是无条件放行;
+- **隔离仓库自带的 settings/MCP**:`setting_sources=["user"]` 只加载用户级 settings,
+  `strict_mcp_config=True` 忽略仓库的 `.mcp.json`,防止仓库自我授权或借 MCP 执行代码;
+- `cwd` 只是限定 Agent 的工作目录,不是完整文件系统沙箱;
+- 审计失败、审计无法完成或审计结论不明确时,不得继续安装;
+- alt 流程**不记录改造后的 SHA**(改造后的内容已非原始仓库状态);保留原始来源 URL、ref。
+
 ### 必须拦截的情况
 
 - 当前平台不在 `platforms` 内 → 拒绝,不等装完才发现

cckit-0.3.0/Docs/kit-development.md

@@ -0,0 +1,12 @@
+# kit 开发手册
+
+请参照 [manifest-spec.md](../skills/kit-builder/kit-builder/manifest-spec.md) 和
+[kit-authoring.md](../skills/kit-builder/kit-builder/kit-authoring.md)
+
+或者使用 `kit-builder` [SKILL](../skills/kit-builder/kit-builder/SKILL.md) 来把 skill 构建成 cckit 支持的模式。
+
+如果你的仓库是**没有 `cckit.yaml` 的普通 skill 仓库**,也可以直接用
+`cckit add <仓库> --alt` 让它自动走 `kit-builder` 改造 + Claude Code 审计后导入,
+无需手动写 manifest(需先装 `cckit[alt]`,详见 [cli-spec.md](./cli-spec.md))。
+
+*当然，建议您手动进行构建，使用自动构建可能造成部分内容与您的预期不符！*

cckit-0.3.0/Docs/test/hello-skill/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: hello-skill
+version: 0.1.0
+description: 这是一个简单的技能，用于测试，回复hello。
+---
+
+该技能用于测试对非标准仓库的转换流程，当你调用该skill时，回复 hello 即可。

cckit-0.3.0/Docs/test/test-skill-dependency/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+node_modules/
+.env
+report.csv

cckit-0.3.0/Docs/test/test-skill-dependency/README.md

@@ -0,0 +1,63 @@
+# test-skill-dependency
+
+一个用于测试 cckit **非标准仓库导入（`--alt`）** 功能的示例 Skill 仓库。
+
+> ⚠️ 这是一个**非标准仓库**：根目录**没有** `cckit.yaml`。
+> - 用 `cckit add <本目录> --local` 会被直接拒绝（缺少合法 cckit.yaml）；
+> - 用 `cckit add <本目录> --local --alt` 会先由 Claude Code（kit-builder）把它改造成标准 kit，再走正常安装。
+
+## 包含的 Skill
+
+| Skill | 类型 | 依赖 |
+|---|---|---|
+| `test-skill-dependency` | 带脚本 | Python（pandas）+ 系统工具 ffmpeg + 可选环境变量 `OPENAI_API_KEY` |
+| `json-pretty` | 带脚本 | Node（js-yaml） |
+| `plain-advisor` | 纯 prompt | 无 |
+
+## 依赖
+
+### Python
+
+见 [requirements.txt](./requirements.txt)（`pandas`），由 `test-skill-dependency` 使用。
+
+### Node
+
+见 [package.json](./package.json)（`js-yaml`），由 `json-pretty` 使用。
+
+### 系统工具
+
+- `ffmpeg` —— `test-skill-dependency` 用它读取视频信息。缺失时 cckit 只提示、**不自动安装**。
+
+### 环境变量
+
+- `OPENAI_API_KEY`（可选）—— `test-skill-dependency` 用于字幕润色，不填则跳过该步骤。
+
+## 安装（测试 alt）
+
+```bash
+# 标准安装会被拒绝（没有 cckit.yaml）
+cckit add ./Docs/test/test-skill-dependency --local
+
+# alt 安装：由 Claude Code 改造后安装
+cckit add ./Docs/test/test-skill-dependency --local --alt
+```
+
+## 目录结构
+
+```
+test-skill-dependency/               # 仓库根 = 传给 cckit 的 source
+├── README.md
+├── .gitignore
+├── requirements.txt                 # Python 依赖
+├── package.json                     # Node 依赖
+├── test-skill-dependency/           # skill 1：python + ffmpeg + env
+│   ├── SKILL.md
+│   └── scripts/
+│       └── test.py
+├── json-pretty/                     # skill 2：node
+│   ├── SKILL.md
+│   └── scripts/
+│       └── pretty.js
+└── plain-advisor/                   # skill 3：纯 prompt
+    └── SKILL.md
+```

cckit-0.3.0/Docs/test/test-skill-dependency/json-pretty/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: json-pretty
+description: 把 JSON 文件转成 YAML 输出，方便查看配置文件；需要 Node 与 js-yaml。
+---
+
+# json-pretty
+
+读取一个 JSON 文件，用 `js-yaml` 转成 YAML 输出，便于阅读配置。
+
+## 依赖
+
+- **Node**：`js-yaml`（见根目录 `package.json`）
+
+## 脚本调用
+
+```bash
+cckit exec json-pretty scripts/pretty.js <file.json>
+```

cckit-0.3.0/Docs/test/test-skill-dependency/json-pretty/scripts/pretty.js

@@ -0,0 +1,12 @@
+// 把 JSON 文件转成 YAML 输出。依赖 js-yaml(见根目录 package.json)。
+const fs = require("fs");
+const yaml = require("js-yaml");
+
+const input = process.argv[2];
+if (!input) {
+  console.error("用法: cckit exec json-pretty scripts/pretty.js <file.json>");
+  process.exit(1);
+}
+
+const data = JSON.parse(fs.readFileSync(input, "utf8"));
+process.stdout.write(yaml.dump(data));

cckit-0.3.0/Docs/test/test-skill-dependency/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "test-skill-dependency",
+  "version": "1.0.0",
+  "private": true,
+  "description": "cckit alt 测试仓库的 Node 依赖",
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

cckit-0.3.0/Docs/test/test-skill-dependency/plain-advisor/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: plain-advisor
+description: 纯 prompt 的示例 Skill，无脚本、无依赖，用于测试 cckit 的「纯 prompt」安装路径。
+---
+
+# plain-advisor
+
+一个不建任何运行环境的纯 prompt Skill。安装它不会触发任何依赖安装，只建一个 link。
+
+## 用途
+
+测试 cckit 对「`needs: []` 纯 prompt skill」的处理：不建 env、不装依赖。

cckit-0.3.0/Docs/test/test-skill-dependency/requirements.txt

@@ -0,0 +1 @@
+pandas>=2.0

cckit-0.3.0/Docs/test/test-skill-dependency/test-skill-dependency/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: test-skill-dependency
+description: 读取视频文件并提取元数据、生成 CSV 报告；需要 pandas 与 ffmpeg，可用 OPENAI_API_KEY 做字幕润色。
+---
+
+# test-skill-dependency
+
+读取一个视频文件，用 `ffmpeg` 提取格式信息，用 `pandas` 汇总成一份 CSV 报告。
+
+## 依赖
+
+- **Python**：`pandas`（见根目录 `requirements.txt`）
+- **系统工具**：`ffmpeg`（读取视频信息；缺失时请手动安装，cckit 只提示不自动装）
+- **环境变量**：`OPENAI_API_KEY`（可选，用于字幕润色，不填则跳过该步骤）
+
+## 脚本调用
+
+```bash
+cckit exec test-skill-dependency scripts/test.py <视频文件>
+```
+
+脚本通过 `CCKIT_SKILL_DIR` 定位自身资源，不要假设当前工作目录。

cckit-0.3.0/Docs/test/test-skill-dependency/test-skill-dependency/scripts/test.py

@@ -0,0 +1,48 @@
+"""分析视频文件并生成 CSV 报告。
+
+依赖:
+  - pandas(requirements.txt)
+  - ffmpeg(系统工具,用 `ffmpeg -i` 读视频信息)
+  - 环境变量 OPENAI_API_KEY(可选,字幕润色)
+"""
+import os
+import subprocess
+import sys
+
+import pandas as pd
+
+
+def read_video_info(path: str) -> str:
+    """用 ffmpeg 读取视频格式信息(ffmpeg 会把信息写到 stderr)。"""
+    proc = subprocess.run(
+        ["ffmpeg", "-i", path],
+        capture_output=True,
+        text=True,
+    )
+    return (proc.stderr or proc.stdout).strip()
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("用法: cckit exec test-skill-dependency scripts/test.py <视频文件>")
+        return 1
+
+    video = sys.argv[1]
+    info = read_video_info(video)
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    polished = bool(api_key)
+
+    df = pd.DataFrame([
+        {"file": video, "info": info[:200], "polished": polished},
+    ])
+
+    out_dir = os.environ.get("CCKIT_SKILL_DIR", ".")
+    out = os.path.join(out_dir, "report.csv")
+    df.to_csv(out, index=False)
+    print(f"已生成报告: {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())