cckit 0.3.1__tar.gz → 0.3.2__tar.gz

{cckit-0.3.1 → cckit-0.3.2}/Docs/01-overview.md

@@ -29,6 +29,14 @@ Claude Code 2.1.245 原生已有 plugin + marketplace 系统,并且已经解决
 后果:Python 依赖、原生编译、系统级二进制,官方全部无解。作者只能自己写
 `SessionStart` hook 比对 `package.json` 哈希再手动装——只覆盖 Node,且很笨。
 
+同一个缺口还有另一半:**skill 需要的用户配置**(API key、字体目录、一份要改的
+`config.json`)官方同样没有位置可放。作者只能在 SKILL.md 里写"请先 export XXX",
+用户装完看不出缺什么,唯一发现时机是脚本跑崩那一刻。cckit 把这两半一起补上:
+
+- 依赖由 `requires` 声明,`cckit add` 建隔离环境(D-01 / D-02);
+- 用户配置由 `kit_env` / `env` / `conf_files` 声明,用户在 CLI 与 Web 面板里填,
+  `cckit exec` 时注入(见 [03-manifest-spec.md](03-manifest-spec.md))。
+
 > **CCKitKit 的核心功能,正是官方明确拒绝实现的那件事。**
 > 这不代表不能做——我们是本机工具、用户自己装的,信任模型不同。但安全责任是官方
 > 推给我们的,不是顺手接的。详见 [07-security.md](07-security.md)。

{cckit-0.3.1 → cckit-0.3.2}/Docs/02-architecture.md

@@ -154,11 +154,16 @@ cckit 负责:
    - `CCKIT_SKILL_DIR` — skill 自己的目录。**必需**,因为 CC 跑 Bash 时 cwd 是项目根,
      脚本引用自己的资源文件需要这个
    - `CCKIT_KIT_DIR`、`CCKIT_ENV_DIR`
-   - manifest `env:` 段声明的变量
+   - `kit_env`(kit 级)与 skill 的 `env`(skill 级)声明的变量。同名时 skill 级优先;
+     **值先取用户在 CLI/Web 填的**(`~/.cckit/envs.json`),没有再回落调用方的进程环境
 4. 记录用量(用于预算优化建议)
 5. cwd **保持调用方的 cwd**,让用户给的相对路径正常工作
 
-env 缺失时不静默失败,报错并提示跑 `cckit doctor`。
+必需的变量却哪儿都取不到时不静默失败,报错并给出填写的命令。
+
+> 值**不写 Claude Code 的 `settings.json`**。往那里写会把用户的 `model`/`env`/
+> `permissions` 一起卷进写入路径,而且"哪些变量是 cckit 写的"无从追踪、卸载时不敢删。
+> 改由 cckit 自己存(`envs.json`,按 `{作用域}|{kit}[|{skill}]` 分桶),只在 exec 时注入。
 
 > 这个入口顺带给了我们一个真实的拦截点——用户最初设想的"总控 skill 拦截调用"在这里
 > 才真正拿得到。但它只覆盖带脚本的 skill;纯 prompt skill 的开关仍靠可见性。详见 D-04。

{cckit-0.3.1 → cckit-0.3.2}/Docs/05-design-log.md

@@ -457,6 +457,65 @@ Web 把全局 skill 单独折叠一组、用独立覆盖选择器(不复用四
 kit 作者诱导的操作。因此审计这一步聚焦 prompt injection / 敏感读取 / 外传 /
 越界,并要求输出明确的 PASS/FAIL 结论,结论不明确一律视为不通过。
 
+## D-17 用户配置:声明在 manifest,值由用户填,只在 exec 注入
+
+**提出的问题**:skill 常常需要用户提供参数——一个 API key、一个字体目录、一份要改的
+`config.json`。cckit 原本只有一份 **kit 级**的 `env:` 声明,而且值必须由用户自己在
+shell 里 export。结果是:装完看不出缺什么(唯一发现时机是脚本跑崩那一刻),CLI 与
+Web 上都没有填写的入口,粒度还和 `needs`(skill 级)不一致。
+
+**最终方案**:分两层声明 + 一个独立的值存储 + 只在 exec 注入。
+
+- **manifest 三层字段**:顶层 `env` 改名 `kit_env`(kit 共用);skill 新增 `env`
+  (skill 专属,同名时覆盖 kit 级)与 `conf_files`(相对 skill 目录的可改文件)。
+  三者都**只声明"要什么"**,没有 `value` / `default`。
+- **值**:用户在 `cckit env <skill> <NAME> <VALUE>` 或 Web 面板里填,存
+  `~/.cckit/envs.json`(按 `{作用域}|{kit}[|{skill}]` 分桶,带锁 + 原子写)。
+  取值优先级:`envs.json` > 调用方的进程环境。`cckit exec` 时注入。
+- **声明快照进 registry**:与 `needs` 同样处理,`list` 与 Web 不必每次现场解析 manifest。
+- **缺配置要看得见**:`list_skills` 顺带算出每个 skill "声明了 `required` 却还没值"的变量名
+  (`missing_env`),CLI 在 `cckit list` 对应行末尾提醒、Web 在 skill 名字旁挂一个琥珀色钥匙
+  图标。**判定口径与 `cckit exec` 注入完全一致**(kit 级+skill 级、同名 skill 覆盖、值先看
+  `envs.json` 再看进程环境),否则会出现"列表说没事、一跑就报错"这种最费解的不一致。
+
+**为什么这样定**:
+
+- **不写 Claude Code 的 `settings.json`。** 最初的设计是把值写进 CC `settings.json`
+  的 `env` 键,并维护"基线快照 + 变量引用计数"。放弃它的理由有两条:一是那个键里
+  装着用户的核心配置(`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等),写坏等于
+  Claude Code 直接不可用;二是**基线快照抓不住快照之后发生的事**——用户事后手改
+  会被误判成 cckit 写的进而删除,基线文件丢了又会把 cckit 自己写的变量当成用户原有的
+  从而永远删不掉。改成自己存、exec 时注入之后,这些问题连同"误删用户凭据"的风险
+  一起消失(见 [07-security.md](07-security.md) 第 10 条)。
+- **值不由作者提供。** manifest 里没有放值的地方,从根上堵死"作者把密钥提交进仓库、
+  随 kit 分发给所有用户"。作者能做的只有声明"我需要这个变量",值一律由用户填。
+- **`envs.json` 不并进 `registry.json`。** registry 是安装元数据(`remove` 即清),
+  用户填的值是用户数据。混在一起会让"重装即恢复"的语义变乱。
+- **分桶键带 (kit, skill),因此不需要引用计数。** 删一个 skill 只删它自己那份,
+  不会波及同 kit 的其他 skill。key 必须带作用域:同名 skill 在全局与项目各装一份时,
+  各自的配置是独立的。
+- **`conf_files` 就放在 skill 目录里**,承认它会被 `remove`/重装一起删掉。要长期保留的
+  数据应由脚本写到用户自己的目录——把用户数据搬出 store 会引入"配置目录 + 注入路径 +
+  升级时合并用户改动"一整套设计,而那是作者该决定的事,不该由 cckit 规定。
+- **`envs` 这个名字留给虚拟环境。** 代码里 `envs` 早已指 `{runtime: env_dir}` 与
+  `~/.cckit/envs/`(venv 目录),`env_ok`、doctor 的 env 项、`CCKIT_ENV_DIR` 也都是这个
+  意思。所以"环境变量"一律用 `env`(单数):`kit_env` / skill 的 `env` / `envs.json`。
+  同一份 registry 记录里 `envs` 与 `env` 并存,这是刻意区分的,不是笔误。
+- **版本号不变(`cckit: 1`)。** 顶层 schema 是 `additionalProperties: false`,所以改名后
+  仍写旧 `env:` 的 kit 会被新 schema **明确拒绝**安装,而不是静默忽略——可以接受的
+  失败方式。代价是"1"从此不再能表达兼容性边界(见下)。
+
+**代价(必须记录)**:
+
+- **`env` → `kit_env` 是破坏性改名。** 任何已发布的、用了顶层 `env:` 的 kit,在新版
+  cckit 下会被 schema 拒绝安装,作者需要改字段名。因为 cckit 尚在 0.x 且生态未铺开,
+  判断为可接受;官方 kit-builder 的规范文档、模板与自检清单已同步更新。
+- **`conf_files` 里的用户改动会随卸载/重装丢失。** 这是明确接受的限制,已在
+  manifest-spec 与 kit-authoring 里以警告形式写给作者。
+- **`installed` 态(无 link)与 `managed=False` 的 skill 不允许改配置。** 前者尚未启用,
+  后者不是 cckit 管的。UI 禁用之外,服务端也重新校验一遍——UI 禁用了不代表可以信任
+  客户端传来的请求。
+
 ## 我的判断失误汇总
 
 集中列出,便于后续开发者校准对本文档其余部分的信任度:

{cckit-0.3.1 → cckit-0.3.2}/Docs/07-security.md

@@ -106,6 +106,48 @@ Web 管理界面能改 CC 行为、能触发安装(而安装会执行仓库作
 **绝不能监听 `0.0.0.0`。** 确需远程访问必须加鉴权。这条要写在用户文档显眼处,
 不能默认放开让用户自己发现。
 
+### 10. 用户配置:注入点是 `exec`,写入面只有 skill 目录
+
+skill 需要的用户配置(环境变量的值、可改的配置文件)有两个新面:
+
+**a) 环境变量的值不写 `settings.json`。** 最初的设想是把值写进 CC `settings.json`
+的 `env` 键,被否决:那个键是用户的核心配置,写进去就要处理"哪些变量是 cckit 写的"
+(基线快照 + 引用计数),而快照抓不住用户事后手改、基线丢了又会把 cckit 自己写的变量
+误判成用户原有的。改为 cckit 自己存 (`envs.json`) 并在 `cckit exec` 时注入,
+上述问题连同"误删用户凭据"的风险一起消失。
+
+**b) 保存配置文件必须服务端校验路径。** Web 面板能改 skill 目录里的文件,这是一个
+**任意文件写入**的潜在入口。两道闸缺一不可:
+
+- 路径必须**逐字命中** registry 快照里的 `conf_files` 声明 —— 客户端传来的一律不可信,
+  "装的时候声明过"不等于"这次传的就是那一条";
+- 解析(`resolve`)之后仍要落在 skill 目录内 —— 防 `..` 与符号链接逃逸。
+
+安装时 `semantic_check` 会先拦一遍(拒绝绝对路径与 `..`),但那只是作者侧的第一道;
+文件系统在安装之后仍可能变化,所以运行期必须重新校验。
+
+**c) 值不在终端回显。** `cckit list --envs` 与 `cckit env <skill>` 只显示
+"变量名 + 是否必需 + 已设/未设",不回显明文 —— 否则密钥会进终端 scrollback 与日志。
+面板里的值绑定在 127.0.0.1 上传输(见第 9 条)。
+
+**d) manifest 里没有放值的地方。** `kit_env` / `env` 只有 `name` / `required` /
+`description`,没有 `value` / `default`。这从根上堵死了"作者把自己的密钥提交进仓库、
+随 kit 分发给所有用户"。作者能做的只有声明"我需要这个变量"。
+
+### 11. 管理员通知的内容等同公开
+
+`cckit web --notice TITLE FILE` 让运维在面板顶部挂一条公告。两点必须写进用户文档:
+
+- **能访问面板的人都看得到 `FILE` 的内容。** 默认只绑 `127.0.0.1` 时还好,但文档是
+  明确支持 `--host 0.0.0.0` 部署的 —— 那时公告就是公开的。**不要往公告文件里放密钥。**
+- **正文按纯文本渲染,不走 HTML 也不走 Markdown。** 文件内容原样进 `<pre>`,既不能
+  执行脚本,也不会因为解析器的某个 bug 变成注入点。每多支持一种富文本格式就多一个
+  XSS 面,而这个功能并不需要它。
+
+实现上另有两道防御:`--notice` 的 TITLE 会被注入 `index.html`,所以对 `<` / `>` / `&`
+做了转义(与 `--base` 同一套 `_js_string`),防止标题里的 `</script>` 跳出去;正文读取
+有 256 KiB 上限、用 `errors="replace"` 解码,免得一个非 UTF-8 文件把面板打挂。
+
 ## alt 流程的安全边界(非标准仓库导入)
 
 `--alt` 会在安装前调用 Claude Code 去改造并审计一个**临时目录里**的仓库。它没有

{cckit-0.3.1 → cckit-0.3.2}/Docs/09-state-api.md

@@ -42,10 +42,15 @@ CC 实际   不加载
 |---|---|---|
 | 装了哪些 kit、版本、sha、来源 | `registry.json` | 观测不出来,必须存 |
 | env 路径映射(runtime → env_dir)| `registry.json` | 同上 |
+| 声明快照(`kit_env` / `env` / `conf_files` / `needs`)| `registry.json` | 从 manifest 抄一份,免得 list/Web 每次现场解析 |
 | 用量统计 | `registry.json` | 同上 |
+| **用户填的环境变量值** | `envs.json` | 用户的输入,观测不出来;与安装元数据分开存 |
 | 团队期望装什么 | `cckit.lock` | 这是声明,不是现状 |
 | **是否启用 / name-only / off** | **文件系统 + settings.json** | 观测得到,存了会漂移 |
 
+> `envs.json` 单独一个文件、不并进 `registry.json`:registry 是**安装元数据**
+> (`remove` 即清),用户填的值是**用户数据**,混在一起会让"重装即恢复"的语义变乱。
+
 ## API 契约
 
 ```python
@@ -64,13 +69,33 @@ class SkillState:
     is_global_skill: bool = False   # project 作用域下,此条目是「全局 skill 的项目覆盖/跟随」
     global_state: str | None = None # 全局 skill 在全局作用域的状态
     override: bool = False          # 全局 skill 是否带项目级覆盖(off/name-only)
+    envs: list[dict] = []           # skill 级环境变量声明(name/required/description)
+    conf_files: list[str] = []      # 可修改的配置文件,相对 skill 根
+    missing_env: list[str] = []     # 声明 required 却还没值的变量名(CLI/Web 的提醒就靠它)
 
 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]: ...   # (已用字符, 上限)
+
+# 用户填的环境变量值(envs.json,带锁 + 原子写)
+def set_user_env(name, value, *, kit, skill=None, scope='global', root=None) -> None: ...
+def remove_user_envs(kit, scope='global', *, skill=None, root=None) -> None: ...
+def stored_env(scope, kit, skill=None, root=None) -> dict[str, str]: ...
+def env_requirements(kit, skill, scope='global', root=None) -> list[EnvRequirement]: ...
+def missing_required_env(kit_info, skill_rec, values) -> list[str]: ...
+def env_scope_of(s) -> str: ...      # 该条目的值存在哪个作用域(全局 skill 的项目视图仍是 global)
+
+# 可修改的配置文件(conf_files)
+def ensure_config_editable(scope, root, kit, skill) -> None: ...
+def conf_files(kit, skill) -> list[str]: ...
+def read_conf_file(kit, skill, rel) -> str: ...
+def write_conf_file(kit, skill, rel, content) -> None: ...   # 原子替换
 ```
 
+⚠️ `envs` 与 `env` 是**两个不同的东西**,只差一个字母:前者是 `{runtime: env_dir}`
+(虚拟环境目录),后者是环境变量声明。同一份 registry 记录里两者并存,别混。
+
 `list_skills()` 必须同时列出**非 cckit 管理**的 skill,标记 `managed=False`。
 用户看到的是完整工具箱视图,但只有 cckit 装的能被开关。
 
@@ -106,11 +131,17 @@ def budget(scope=None, root=None) -> tuple[int, int]: ...   # (已用字符, 上
       "version": "1.2.0",
       "installed_at": "2026-08-27T02:10:00Z",
       "store": "~/.cckit/store/video-toolkit",
+      "kit_env": [
+        { "name": "OPENAI_API_KEY", "required": false, "description": "字幕润色" }
+      ],
       "skills": [
         { "name": "burn-subtitles",
           "envs": { "python": "~/.cckit/envs/video-toolkit__burn-subtitles__python" },
-          "needs": ["ffmpeg", "python"] },
-        { "name": "describe-video", "envs": {}, "needs": [] }
+          "needs": ["ffmpeg", "python"],
+          "env": [{ "name": "FONT_DIR", "required": true, "description": "字体目录" }],
+          "conf_files": ["config.json"] },
+        { "name": "describe-video", "envs": {}, "needs": [],
+          "env": [], "conf_files": [] }
       ],
       "known_scopes": ["global", "C:/work/proj-a"],
       "override_scopes": []
@@ -119,6 +150,33 @@ def budget(scope=None, root=None) -> tuple[int, int]: ...   # (已用字符, 上
 }
 ```
 
+注意 `envs`(虚拟环境目录)与 `env`(环境变量声明)并存 —— 前者由 `installer.build_envs`
+建好后写入,后者是从 manifest 抄来的声明快照。
+
+## `envs.json` 结构
+
+用户在 CLI(`cckit env`)或 Web 面板里填的环境变量值。按
+`{作用域}|{kit}` 与 `{作用域}|{kit}|{skill}` 分桶;作用域是 `"global"` 或项目根绝对路径
+(与 `known_scopes` 的表示一致)。
+
+```json
+{
+  "version": 1,
+  "kit_env": {
+    "global|video-toolkit": { "OPENAI_API_KEY": "sk-..." }
+  },
+  "skill_env": {
+    "global|video-toolkit|burn-subtitles": { "FONT_DIR": "D:/fonts" }
+  }
+}
+```
+
+- **按 (kit, skill) 分桶意味着不需要引用计数**:删一个 skill 只删它自己那份,
+  不会波及同 kit 的其他 skill。`remove_kit` 会把这个 kit 的 kit 桶与全部 skill 桶一起清掉
+  (除非 `--keep-env`)。
+- 读取顺序:`stored_env()` 先取 kit 桶打底、再叠加 skill 桶(同名以 skill 级为准)。
+- 与写 `settings.json` 同一套纪律:**文件锁 + 原子替换**。空桶会被顺手删掉。
+
 `skills[].envs` 是 `runtime → env_dir` 的映射。一个 skill 可同时有 `python` 与
 `node` 两个 env(各自独立目录);纯 prompt skill 为 `{}`。
 

{cckit-0.3.1 → cckit-0.3.2}/Docs/11-web-panel.md

@@ -1,6 +1,6 @@
 # Web 管理面板
 
-配套 v0.3.1 的可选管理面板:平时展示 skill 列表,支持导入（add）、卸载（remove）、
+配套 v0.3.2 的可选管理面板:平时展示 skill 列表,支持导入（add）、卸载（remove）、
 四态开关切换、诊断（doctor）。**纯增量**——不装 `[web]` 额外依赖时,`cckit` 本体
 与命令行工具完全不变。
 
@@ -38,7 +38,7 @@ FastAPI (src/cckit/web/)  ── 静态托管 web/dist/
    │  ├─ cckit.installer        └── POST /api/doctor        (SSE)
    │  └─ cckit.doctor
    ▼
-~/.cckit/  store + registry.json + projects.json + envs
+~/.cckit/  store + registry.json + projects.json + envs/ + envs.json
 <CC 配置目录>/skills + settings.json   (状态派生源)
 ```
 
@@ -53,8 +53,13 @@ FastAPI (src/cckit/web/)  ── 静态托管 web/dist/
 |---|---|---|
 | `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` |
+| `GET /api/skills?scope=&root=` | `state.list_skills` + `state.budget` | 列表 + 预算一次返回;skill 带 `is_global_skill`/`global_state`/`override`/`envs`/`conf_files`;另含 `kit_env`(按 kit 名索引的 kit 级声明) |
 | `POST /api/skills/{name}/state` | `state.set_state` | 四态切换,返回 `{message}` |
+| `GET /api/config?scope=&kit=&skill=` | `state.env_requirements` + `state.conf_files` | 配置需求 + 当前值;`skill` 省略时只返回 kit 级(`kit_env`) |
+| `POST /api/config/env` | `state.set_user_env` | 保存/清除一个环境变量的值 |
+| `GET /api/config/conf?scope=&kit=&skill=&path=` | `state.read_conf_file` | 读一个可修改的配置文件 |
+| `PUT /api/config/conf` | `state.write_conf_file` | 写回(服务端校验路径,见下) |
+| `GET /api/info` | 读 `--notice` 指定的文件 | 管理员通知正文。**没配 `--notice` 时 404**,前端据此不渲染控件 |
 | `GET /api/kits` | `registry.load()` | kit 头部元信息 |
 | `POST /api/kits/{kit}/remove` | `installer.remove_kit` | 卸载 |
 | `POST /api/add/preview` | `installer.stage_install` | 克隆+校验+计划,存 `preview_id` |
@@ -149,17 +154,42 @@ src/
   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)
+    AppSidebar / KitList / AddKitDialog / DoctorDialog / AddScopeDialog / NoticeMenu
+    ui/                  # shadcn 组件(button/dialog/dropdown-menu/tooltip/input/textarea/
+                         #   card/badge/progress/separator/popover/sonner/sidebar/sheet/skeleton)
 ```
 
 - **布局**:dashboard 式——官方 `Sidebar`(variant=inset)+ 右侧 `SidebarInset`。
   Sidebar 内:Header(CCKitKit + 版本)、4 个分组(作用域 / 添加关注项目 / Kit 管理 /
   刷新)、Footer(清单预算,收起时变圆环);右侧顶部 `SidebarTrigger` 收起/展开。
+- **管理员通知**(`cckit web --notice TITLE FILE`,没配就完全不渲染):
+  在右侧 **`Skills` 那一行的最右端**。位置选这里的理由:这行 header 在 `SidebarInset` 里,
+  与 `<Sidebar>` 是兄弟节点,所以**收起侧栏不影响它**,而且它在滚动容器之外,始终可见。
+  控件用 `Dialog` + `DialogTrigger` + `Button`(都是已装的官方组件)拼成:按钮用
+  **`default`(`primary`)变体**让它在 header 里足够显眼,左侧一个 `Megaphone` 图标,
+  右侧两行——第一行 `管理员通知`,第二行是 `TITLE`。图标与文字都用按钮自己的
+  `primary-foreground`(标签行取 70% 那一档),不另指定灰色,免得压在彩色底上发糊。
+  按钮宽度是 `w-1/2`,即**内容区宽度的一半**(用百分比而非固定值:这样侧栏收起/展开时
+  它自动跟着变,不需要读侧栏状态);标题超出用 `truncate` 截断,完整标题在弹窗里。
+  点击弹窗以**纯文本**(`<pre>`)显示 `FILE` 内容。
+  标题由后端启动时注入、**首屏即渲染**;正文在打开弹窗时才请求,所以改了公告不用重启。
 - **列表**:项目 kit 可收起/展开/卸载(卸载用 Popover + destructive 确认);skill
   四态选择器(`name-only` 附解释)、`env_ok=False` 警示、`managed=False` 置灰只读;
   全局 skill 单独折叠一组、无卸载按钮、用覆盖选择器。
+  名字旁边有两类互不相同的提示图标:
+  - 🔴 **红色 `Warning`** —— `env_ok === false`,运行环境(venv)缺失或损坏,去「诊断」修;
+  - 🔑 **琥珀色 `Key`** —— `missing_env` 非空,有声明 `required: true` 的环境变量还没填。
+    Tooltip 列出变量名并提示"点右侧齿轮填写"。**只是提醒不是报错**,所以用琥珀色与红色
+    区分开——点齿轮就能解决,不用离开这一屏。
+  两者都只在真有事时出现,不给每一行加噪声。
+- **配置管理**(齿轮图标 + 下拉,内容为空时显示「无」):
+  - **skill 级**:在**状态下拉左侧**。下拉分「环境变量」与「配置文件」两段;
+    点 env 行弹对话框改值(输入框 + 取消/保存),点 conf 行弹对话框预览与编辑
+    (Textarea + 取消/保存)。
+  - **kit 级**:在**卸载按钮左侧**,复用同一形态,只有环境变量(没有 `conf_files`)。
+  - 值在展开时才向后端取 —— 可能在别处改过,缓存会给出过期的默认值。
+  - `installed` 态(无 link)与 `managed=False` 的 skill 一律禁用;服务端也拦
+    (见 [07-security.md](07-security.md) 第 10 条)。
 - **添加 Kit**:两阶段弹窗(表单 → 计划确认,lint error 禁用安装 → SSE 日志)。
 - **诊断**:`--fix` 勾选 + SSE 进度 + findings 结果。
 - **刷新三层**:侧栏刷新按钮 + 写操作后 `invalidateQueries` 自动重拉 + 可选轮询。

{cckit-0.3.1 → cckit-0.3.2}/Docs/README.md

@@ -54,8 +54,9 @@
 
 ## 当前状态
 
-**v0.3.1 已实现**:`cckit` 命令行工具与全部 9 个命令(`add` / `list` / `enable` /
-`disable` / `name-only` / `remove` / `doctor` / `exec` / `web`),`uv run cckit --help` 可用。（0.2.0因为打包失误，版本号被弃用）
+**v0.3.2 已实现**:`cckit` 命令行工具与全部 10 个命令(`add` / `list` / `env` /
+`enable` / `disable` / `name-only` / `remove` / `doctor` / `exec` / `web`),
+`uv run cckit --help` 可用。（0.2.0因为打包失误，版本号被弃用）
 
 已落地模块(`src/cckit/`):
 
@@ -64,15 +65,15 @@
 - `env` —— uv venv / node env 与解释器解析
 - `installer` —— add 全流程(锁 sha、计划确认、store/env/postinstall/registry/link)
 - `alt` —— 非标准仓库导入(前置条件 → 物化 → kit-builder 改造 → 审计 → 复用本地安装)
-- `exec` —— skill 脚本统一入口(白名单 + 环境变量注入)
-- `state` —— 四态派生 + 文件锁 + 原子写 + 清单预算
+- `exec` —— skill 脚本统一入口(白名单 + 环境变量注入:`envs.json` 优先,回落进程环境)
+- `state` —— 四态派生 + 文件锁 + 原子写 + 清单预算 + 用户配置(envs.json / conf_files)
 - `registry` —— registry.json 原子读写
 - `lint` —— 命名 / description / CRLF / prompt injection / typosquatting
 - `doctor` —— 只读诊断 + 安全修复
 - `projects` —— 关注项目清单 projects.json 原子读写
-- `web` —— Web 管理面板后端(FastAPI,惰性 import,`[web]` 可选依赖)
+- `web` —— Web 管理面板后端(FastAPI,惰性 import,`[web]` 可选依赖;含配置读写与管理员通知端点)
 
-测试:`tests/` 下 132 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
+测试:`tests/` 下 189 项,`uv run pytest -q` 全绿;`Docs/examples/video-toolkit` 作为夹具。
 
 ## v0.1 范围
 
@@ -102,6 +103,26 @@
   「允许导入非标准仓库」检测不到 `skills/kit-builder`、无法给出安装选项的问题。
 - **修复安装弹窗残留状态**:安装成功后关闭弹窗,再次打开不再显示上一次的「安装成功」。
 
+## v0.3.2 范围
+
+- **skill 级用户配置(`kit_env` / `env` / `conf_files`)**:作者在 manifest 里只**声明**
+  需要哪些环境变量、哪些文件用户可改;值由用户在 `cckit env` 或 Web 面板里填,存在
+  `~/.cckit/envs.json`,由 `cckit exec` 注入——**不写 CC 的 `settings.json`**。
+  配套:`cckit list` 的 `[env]` / `[envs]` / `[conf_files]` 标记与 `--envs` / `--confs`
+  明细、「缺必需变量」提醒、Web 上每个 kit / skill 的配置入口。
+  ⚠️ **顶层 `env` 改名为 `kit_env`**,旧字段名的 kit 会被 schema 直接拒绝(见 D-17)。
+  详见 [05](05-design-log.md) 的 D-17、[09](09-state-api.md)、[cli-spec](cli-spec.md)。
+- **管理员通知(`cckit web --notice TITLE FILE`)**:面板顶部(`Skills` 那一行最右端)
+  挂一条公告,点开看文件内容;不传该参数就完全不渲染。⚠️ 内容对所有能访问面板的人可见。
+  详见 [11](11-web-panel.md)、[07](07-security.md)。
+- **同名 skill 明确报错**:同一作用域内已存在同名 skill 时,安装阶段直接拒绝并点名占用者,
+  不再静默跳过 link(那会让新装的 skill 永远不生效,且此后按名操作全部歧义报错)。
+  详见 [cli-spec](cli-spec.md) 的「必须拦截的情况」。
+- **kit-builder 改造更准**:补上一套可执行的「从代码里找环境变量与可配置文件」流程
+  (逐个脚本搜读取点、判定 kit 级还是 skill 级、`required` 怎么定),并要求逐条给出依据;
+  `--alt` 的改造 / 审计提示词同步收紧,漏声明现在会导致审计不通过。
+  规范与流程见 [`../skills/kit-builder/`](../skills/kit-builder/)。
+
 **推迟到 v0.4+**:`cckit.lock` 与 `sync`、`profile`、`update` 的 diff 展示、
 用量统计。
 

{cckit-0.3.1 → cckit-0.3.2}/Docs/cli-spec.md

@@ -84,15 +84,24 @@ cckit add ./my-skill --local --alt
 - 当前平台不在 `platforms` 内 → 拒绝,不等装完才发现
 - 系统依赖缺失 → 报告并给**当前平台**的 hint,询问是继续(env 仍可建)还是中止
 - link 目标已存在真实目录 → 报错说明这是用户手写的 skill,不覆盖
-- **项目安装时存在同名全局 skill → 明确警告"全局会覆盖项目版"**
+- **同作用域已存在同名 skill → 拒绝安装**。CC 的 skill 名字空间是单层的(link 落点
+  是 `<skills_dir>/<name>`,没有 kit 前缀),一个名字在一个作用域内只能属于一个 kit。
+  不拦的后果是静默失效:`state.set_state` 见到已有 link 直接 `pass`,后装的 skill
+  只写进 registry 却永远建不上 link(在 `list` 里显示为 installed),此后按名操作
+  (`enable` / `disable` / `exec`)还会因归属歧义报错。报错需点名占用者(哪个 kit、
+  悬空 link、还是用户手写的目录)并给出释放该名字的办法;`--only` 排除掉的 skill
+  本次不建 link,不参与检查。检查看的是**目标作用域的名字有没有被 link 占用**,
+  与 `--no-enable` 无关(该名字在这个作用域已注定建不上 link)。
+- **项目安装时存在同名全局 skill → 明确警告"全局会覆盖项目版"**(跨作用域同名是
+  允许的,由 CC 的优先级决定谁生效,不属于上一条的拒绝范围)
 
 ## `cckit list`
 
 ```
 $ cckit list
 
-video-toolkit  1.2.0  (sha 30287f5)
-  ● burn-subtitles     enabled     env ok
+video-toolkit  1.2.0  [env]
+  ● burn-subtitles     enabled     env ok        [envs]  [conf_files]  ⚠ 缺必需变量 FONT_DIR → cckit env
   ◐ describe-video     name-only   prompt-only
 doc-tools      0.4.1  (sha a1b2c3d)
   ○ pdf-extract        off         env ok
@@ -106,9 +115,59 @@ doc-tools      0.4.1  (sha a1b2c3d)
 
 选项:`--project` 只列项目;`--all` 全作用域;`--json` 机器可读。
 
+**依赖标记**:kit 行末尾的 `[env]` 表示该 kit 有 `kit_env` 声明;skill 行末尾的
+`[envs]` / `[conf_files]` 表示该 skill 有相应声明。没有就不显示,不给每一行加噪声。
+
+**缺配置提醒**:skill 行末尾的 `⚠ 缺必需变量 <名字> → cckit env` 表示该 skill 生效的
+环境变量里有声明 `required: true` 却还没值的(见下)。判定口径与 `cckit exec` 注入时完全
+一致:kit 级与 skill 级声明都算、同名以 skill 级为准、值先看 `envs.json` 再看进程环境。
+没有未填的项就不显示这行 —— 与依赖标记同样是"只在真有事时出现"。
+
+> 注意与 `env MISSING → cckit doctor` 区分:那个是**运行环境(venv)坏了**,要去诊断;
+> 这个只是**变量还没填**,`cckit env` 填上即可。
+
+**`--envs` / `--confs`** 在列表之后追加明细:
+
+```
+$ cckit list --envs
+
+[envs]
+  burn-subtitles
+    [kit  ] OPENAI_API_KEY       可选  未设  用于字幕润色,不填则跳过
+    [skill] FONT_DIR             必需  已设  字幕字体所在目录
+  describe-video
+    无
+```
+
+⚠️ **只报"已设/未设",绝不回显值** —— 否则密钥会进终端 scrollback 与日志。
+没有声明时显示「无」。
+
+`--json` 每个 skill 额外带 `envs` / `conf_files`。
+
 `--json` 应同时列出**非 cckit 管理**的 skill(用户手写、插件带的),标记为只读。
 用户看到的是完整工具箱视图,但只有 cckit 装的能被开关。
 
+## `cckit env <skill> [name] [value]`
+
+查看 / 设置 / 清除 skill 需要的环境变量。
+
+```bash
+cckit env burn-subtitles                      # 列出声明与「已设/未设」
+cckit env burn-subtitles FONT_DIR /usr/fonts  # 设置
+cckit env burn-subtitles FONT_DIR             # 省略值则交互输入
+cckit env burn-subtitles FONT_DIR --unset     # 清除
+cckit env burn-subtitles FONT_DIR --project   # 作用于项目作用域
+```
+
+- 变量必须**已在 manifest 里声明**(`kit_env` 或 skill 的 `env`),不能凭空造 ——
+  否则就是往脚本环境里塞任意变量。
+- 声明在 `kit_env` 里的写 **kit 桶**(整个 kit 共用一份);声明在 skill 里的写
+  **skill 桶**。同名时 skill 级覆盖 kit 级。
+- 值存在 cckit 数据目录的 `envs.json`(锁 + 原子写),由 `cckit exec` 注入。
+  **不写 Claude Code 的 `settings.json`** —— 见 [07-security.md](07-security.md) 第 10 条。
+- 取值优先级:`envs.json` > 调用方的进程环境。两处都没有且声明 `required: true`
+  时,`cckit exec` 报错中止(不静默跳过)。
+
 实现上直接调 `cckit.state.list_skills()`,**不要自己扫目录**——该函数同时服务
 Web 接口,两边必须共用同一份逻辑。
 
@@ -170,6 +229,14 @@ skill 脚本的统一入口。SKILL.md 里只写这一句,不写解释器路径
 要点:cwd **保持调用方 cwd**(让用户给的相对路径正常工作),脚本自身资源通过
 `CCKIT_SKILL_DIR` 定位。`scripts` 未在 manifest 声明的路径应拒绝执行。
 
+除 `CCKIT_SKILL_DIR` / `CCKIT_KIT_DIR` / `CCKIT_ENV_DIR`(以及 node 的 `NODE_PATH`)
+外,还注入 `kit_env` 与 skill 的 `env` 声明的环境变量:
+
+- 同名时 **skill 级覆盖 kit 级**;
+- 值先取用户在 CLI/Web 填的(`envs.json`),没有再回落调用方的进程环境;
+- 声明 `required: true` 却两处都取不到 → **报错中止**,并给出 `cckit env` 的填写命令;
+- `required: false` 且没值 → 不注入、不报错,由脚本自己决定跳过哪一步。
+
 ## `cckit web`
 
 启动 Web 管理面板(需 `[web]` extra,缺失时提示 `uv tool install 'cckit[web]'`)。
@@ -179,6 +246,7 @@ skill 脚本的统一入口。SKILL.md 里只写这一句,不写解释器路径
 cckit web                            # 前端后端一起起,打开 http://127.0.0.1:8000 即用
 cckit web --host 0.0.0.0 --port 8000 # 部署到服务器
 cckit web --base /cckit              # 挂到根路径前缀 /cckit 下
+cckit web --notice "维护通知" ./notice.md   # 面板顶部挂一条管理员通知
 ```
 
 | 选项 | 说明 |
@@ -187,6 +255,25 @@ cckit web --base /cckit              # 挂到根路径前缀 /cckit 下
 | `--port` | 端口,默认 `8000` |
 | `--static-dir` | 前端静态产物目录(缺省不托管,配合 vite dev 使用) |
 | `--base` | 根路径前缀(如 `/cckit`)。运行时把整站(`/api/*`、`/assets/*`)挂到该前缀下,反向代理只需原样透传 `/base/*`;用于把面板以 iframe 嵌入宿主 dashboard 的子路径而不与宿主 `/api` 冲突 |
+| `--notice TITLE FILE` | 面板顶部显示一条**管理员通知**,点开看 `FILE` 的内容。不传就不显示任何控件 |
 
 `--base` 是**运行时**配置:后端 serve 时把 `window.__CCKIT_BASE__` 注入 `index.html`,
 前端据此拼 `/api` 前缀;前端资源用相对路径(`Vite base: "./"`)自动跟随子路径,无需重新构建。
+
+### 管理员通知(`--notice`)
+
+给运维一个"在面板上挂公告"的口子。**不传 `--notice` 时前后端都不做任何额外的事** ——
+没有控件、没有额外请求。
+
+- **启动时校验 `FILE` 是否存在**(不是普通文件就直接报错退出)。路径写错当场暴露,
+  不会等到用户点开弹窗才发现。
+- 标题随 `index.html` 注入(`window.__CCKIT_NOTICE_TITLE__`),所以**首屏就画得出来**,
+  不会先空一下再冒出来;正文走 `GET /api/info` **按需取**,因此改了公告文件**不用重启服务**。
+- 正文按**纯文本**返回、前端用 `<pre>` 渲染 —— 不解析 Markdown,也不走 HTML,
+  免得平白多一个 XSS 面。大小上限 256 KiB,非 UTF-8 用 `errors="replace"` 兜住。
+- 没配 `--notice` 时 `/api/info` 返回 **404**,前端据此完全不渲染那个控件
+  (比返回空对象更能区分"没配置"和"配置了但没内容")。
+
+⚠️ **通知内容对所有能访问面板的人都可见。** 默认只绑 `127.0.0.1` 没问题,但
+`--host 0.0.0.0` 部署时它就是公开的 —— **不要往公告文件里放密钥**。见
+[07-security.md](07-security.md)。

{cckit-0.3.1 → cckit-0.3.2}/Docs/examples/video-toolkit/cckit.yaml

@@ -24,7 +24,9 @@ requires:
   python:
     file: requirements.txt
 
-env:
+# kit 共用的环境变量:只声明名字与用途,值由用户在 CLI/Web 填写。
+# 值存在 ~/.cckit/envs.json(不写 Claude Code 的 settings.json),cckit exec 时注入。
+kit_env:
   - name: OPENAI_API_KEY
     required: false
     description: 用于 describe-video 的字幕润色;不填则跳过该步骤
@@ -34,6 +36,11 @@ skills:
   - name: burn-subtitles
     needs: [ffmpeg, python]
     scripts: [scripts/burn.py]
+    env:                          # skill 专属环境变量;与 kit_env 同名时以这里为准
+      - name: FONT_DIR
+        required: true
+        description: 字幕字体所在目录
+    conf_files: [config.json]     # 相对 skill 根;用户可在 CLI/Web 里查看与修改
 
   # 纯 prompt:needs 为空,装它不触发任何环境安装
   - name: describe-video

{cckit-0.3.1 → cckit-0.3.2}/Docs/pics/architecture.md

@@ -16,7 +16,7 @@ flowchart TB
         Manifest["manifest / schema · cckit.yaml 校验"]
         Lint["lint · 安全检查"]
         Env["env · 隔离环境"]
-        State["state · 四态派生 + 原子写"]
+        State["state · 四态派生 + 原子写 + 用户配置"]
         Registry["registry · registry.json 读写"]
         Link["link · 目录链接"]
         ExecMod["exec · 脚本执行"]
@@ -28,6 +28,7 @@ flowchart TB
         Store["store / kit / skill / SKILL.md"]
         Envs["envs / kit__skill__runtime /"]
         Reg["registry.json"]
+        UserEnv["envs.json / 用户填的环境变量值"]
         Usage["usage.jsonl"]
     end
 
@@ -55,9 +56,11 @@ flowchart TB
     Registry --> Reg
     State --> Usage
     State -. 扫描 .-> Reg
+    State --> UserEnv
     Link --> Store
     Link --> Global
     Link --> Project
     ExecMod --> Store
     ExecMod --> Envs
+    ExecMod --> UserEnv
 ```

{cckit-0.3.1 → cckit-0.3.2}/Docs/pics/directory-layout.md

@@ -5,6 +5,7 @@ flowchart TD
     Root["~/.cckit/"] --> Store["store / {kit}/"]
     Root --> Envs["envs / {kit}__{skill}__{runtime}/"]
     Root --> Reg["registry.json"]
+    Root --> UserEnv["envs.json<br/>用户填的环境变量值"]
     Root --> Usage["usage.jsonl"]
 
     Store --> Skill["{skill} / SKILL.md"]

{cckit-0.3.1 → cckit-0.3.2}/Docs/schema/cckit.schema.json

@@ -25,7 +25,11 @@
       "description": "缺省视为全平台支持"
     },
     "requires": { "$ref": "#/$defs/requires" },
-    "env": { "type": "array", "items": { "$ref": "#/$defs/envVar" } },
+    "kit_env": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/envVar" },
+      "description": "kit 共用的环境变量。只声明名字与用途,值由用户在 CLI/Web 填写"
+    },
     "skills": {
       "type": "array",
       "minItems": 1,
@@ -117,7 +121,18 @@
           "items": { "type": "string" },
           "description": "python/node 触发环境安装;其余值须为 requires.system[].bin"
         },
-        "scripts": { "type": "array", "items": { "type": "string" } }
+        "scripts": { "type": "array", "items": { "type": "string" } },
+        "env": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/envVar" },
+          "description": "该 skill 专属的环境变量。与 kit_env 同名时 skill 级优先"
+        },
+        "conf_files": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string" },
+          "description": "相对 skill 根目录的路径,标识可供用户修改的配置文件。不得逃逸出 skill 目录"
+        }
       }
     },
     "postinstallStep": {