skill-creator 2.0.2 → 2.2.0

package/README.md

@@ -1,18 +1,12 @@
 <!--
-文件意图（2026-07-22）
-用户原始需求摘录：
-- 「参考 ../../pnpm-pub 这个项目的架构：cli+gui(webui+opentray)，基于 ../ccski 这个 sdk 来快速搭建一个 skills 管理器。」
-- 「skills manager 只是路由的一部分(`/workspace/~/`)；我们还需要支持导入 workspace；创造、编辑技能的路由(/creator)；以及 `/repository/`。」
-- [2026-07-22]「home 目录定义为特殊的 GlobalWorkspace；一个 Workspace 下可以包含多个 providers；下载到某个 Workspace.provider，且能多选。」
-- 「继续迭代，大胆创新……以人为本，要让小白到各行各业到专业工程师用起来都舒心。」
-- [2026-07-15]「按照你自己的节奏去推进开发迭代。」
-- [2026-07-19]「我们已经不做 keepOnTop:true 的模式了。而是走 appMode:true 模式。所以走原生的窗口管理。」
-- [2026-07-21]「我们默认是破坏性更新的……使用 zod 的 safeParse 来统一解决这个问题，遇到不兼容的就当是空值。」
-- [2026-07-21]「任何外部输入都应该遵循这个规则：各种配置文件、数据库结构、网络返回等。」
-- [2026-07-21]「`skill-creator stop` 找不到 daemon，但 `pnpm dev` 又说已有 daemon 持有 socket。」
-- [2026-07-22]「同意，但是改成 `skill-creator openinbrowser`。」
-正交意图：1. 定义产品边界；2. 给出真实安装与运行方式；3. 说明协议和安全模型；4. 提供开发验证入口；5. 承载品牌门面图（color-symbol）。
-妥协声明：README 是包发布后唯一随包分发的公开入口，安装、运行、边界与安全事实必须同处一份文件，拆分会使发布包缺失必要上下文。品牌图经项目相对路径 `./resources/color-symbol.png` 引用，GitHub 自动渲染为 raw 链接；resources 不进 npm 包，npm 端图片缺失不影响文本可读性，repository 字段引导读者到 GitHub。
+File intent (2026-09-15, bilingual restructure — Owner ruling: "at least bilingual").
+Original user requests: see README-zh.md's intent header (Chinese, canonical history).
+Orthogonal intents: 1. Define the product boundary. 2. State the real install and run path.
+3. Document the protocol and security model. 4. Provide the development verification entry.
+5. Carry the storefront brand mark (color-symbol).
+Compromise: the README ships inside the published package as the only public entry —
+install, run, boundary, and security facts must live in one file; this English canon and
+README-zh.md must evolve in lockstep (same facts, both languages).
 -->
 
 <p align="center">
@@ -21,7 +15,9 @@
 
 <h1 align="center">Skill Creator</h1>
 
-Skill Creator 是本地优先的 Agent 技能工作台。薄 CLI 管理单例 daemon，daemon 以自己的 shell（SPA + ChromeTabs 三 App）作为唯一宿主：右侧 Agent 面板承载聊天对话，DSH（DeepSeek Harness）只作为 headless 内核（agent/session/llm/approval）驱动会话；Manager 的领域能力以 MCP server（`/mcp`，同一实现另有 `skill-creator mcp` stdio 形态）供给内核与外部 client——mutation 一律产 proposal 待人工审批。技能的发现、校验和安装以 ccski SDK 完成；Workspace/Provider 投影、权限边界和跨路由体验属于 Skill Creator，而不是 ccski。内核不可用时 daemon 降级为 Manager-only 面，不阻塞启动。
+English | [简体中文](README-zh.md) · Site <https://skill-creator.jixoai.com>
+
+Skill Creator is a local-first workbench for Agent skills. A thin CLI manages a single daemon; the daemon hosts everything in its own shell (an SPA with three ChromeTabs-style apps): the agent panel on the right carries conversations, a headless DSH (DeepSeek Harness) kernel drives sessions (agent/session/llm/approval), and the Manager's domain capabilities are exposed as an MCP server (`/mcp`, plus a `skill-creator mcp` stdio form from the same implementation) for the kernel and external clients — every mutation arrives as a proposal awaiting human approval. Skill discovery, validation, and installation run through the ccski SDK; Workspace/Provider projection, permission boundaries, and the cross-route experience belong to Skill Creator, not ccski. When the kernel is unavailable the daemon degrades to a Manager-only surface without blocking startup.
 
 ```text
                                Skill Creator
@@ -41,21 +37,21 @@ Skill Creator 是本地优先的 Agent 技能工作台。薄 CLI 管理单例 da
   validate / toggle          change log              curated + user sources
 ```
 
-一级导航是 Workspaces、Creator、Repository 三个 App；WebUI 使用 ChromeTabs 式标签 Shell（`webui/src/lib/shell` + `webui/src/lib/apps`），URL 由 shell 内 route registry 解析，SvelteKit 侧只有一个 catch-all 承载点。
+The top-level navigation is three apps — Workspaces, Creator, Repository. The WebUI uses a ChromeTabs-style tab shell (`webui/src/lib/shell` + `webui/src/lib/apps`); URLs are resolved by the shell's route registry and SvelteKit serves a single catch-all mount point.
 
-## 产品边界
+## Product boundary
 
-| Surface                    | 责任                                                                                                                                               | 写入边界                                                                                    |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `/workspaces` home         | 索引 Global 与 Imported Workspace，提供导入与移除恢复入口                                                                                          | Remove Workspace 只删除 registry entry，不删除用户目录                                      |
-| `/workspaces` provider tab | 在一个 Workspace 的 Provider 中发现、筛选、查看、校验、启用或禁用技能；对比上游检查并按需重装过时技能；`Workflow` 标签承载技能管家工作流（见下文） | 每次操作显式携带 Workspace ID + Provider ID                                                 |
-| Global Workspace（`~`）    | 聚合各 Agent 的全局 skills roots                                                                                                                   | 可读/可管理现有技能，不作为 Creator 或 Repository 的写入目标                                |
-| `/creator`                 | 在已导入 Workspace.Provider 中创建、加载、编辑和删除 `SKILL.md`；查看 change log（Agent 会话由右侧面板承载，见下文）                               | `workspace`+`provider` 预选新建；再加 `skill` 加载编辑；更新和删除需要内容 revision         |
-| `/repository`              | 扫描 Git 仓库、预览技能、dry-run、多目标安装并复核结果；管理 curated 与自建 Discover 源                                                            | 扫描会话固定到一个 commit；可多选已导入 Workspace.Provider 写入目标；用户源仅 https Git URL |
+| Surface                    | Responsibility                                                                                                                                                                                                    | Write boundary                                                                                                                 |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `/workspaces` home         | Index Global and Imported Workspaces; entry points for import and remove-recovery                                                                                                                                 | Remove Workspace deletes only the registry entry, never the user's directory                                                   |
+| `/workspaces` provider tab | Discover, filter, inspect, validate, enable, or disable skills in one Workspace's Providers; compare against upstream and reinstall outdated skills; the `Workflow` tab hosts the skill steward workflows (below) | Every operation carries an explicit Workspace ID + Provider ID                                                                 |
+| Global Workspace (`~`)     | Aggregates each Agent's global skills roots                                                                                                                                                                       | Read/manage existing skills; never a write target for Creator or Repository                                                    |
+| `/creator`                 | Create, load, edit, and delete `SKILL.md` inside imported Workspace.Providers; view the change log (agent sessions live in the right-hand panel, below)                                                           | `workspace`+`provider` preselects a new draft; adding `skill` loads it for editing; update/delete require the content revision |
+| `/repository`              | Scan Git repositories, preview skills, dry-run, install to multiple targets, and review results; manage curated and user Discover sources                                                                         | A scan session pins one commit; multiple imported Workspace.Provider write targets; user sources are https-only Git URLs       |
 
-Workspace 是技能作用域的第一层，Provider 是其中的 Agent skills root。Global Workspace（`~`）从社区 catalog 解析本机 Agent 全局目录；Imported Workspace 从其 canonical directory 派生每个 Provider 根目录。用户只在导入 Workspace 时提交目录路径；注册后，技能读写使用 daemon 验证的 `WorkspaceProviderTarget`、opaque Workspace ID 和 Skill ID，不由 WebUI 拼接输出路径。
+Workspace is the first scope layer for skills; a Provider is one Agent skills root inside it. The Global Workspace (`~`) resolves this machine's Agent global directories from a community catalog; an Imported Workspace derives each Provider root from its canonical directory. The user submits a directory path only when importing; afterwards, skill reads and writes use daemon-verified `WorkspaceProviderTarget`s, opaque Workspace IDs, and Skill IDs — the WebUI never assembles output paths.
 
-Provider catalog 是 [vercel-labs/skills](https://github.com/vercel-labs/skills) `src/agents.ts` 的审阅快照，运行时位于 `src/shared/provider-catalog.ts`。本地研究检出说明见 [references/README.md](references/README.md)；它不是运行时或发布依赖。
+The Provider catalog is a reviewed snapshot of [vercel-labs/skills](https://github.com/vercel-labs/skills) `src/agents.ts`, living at `src/shared/provider-catalog.ts` at runtime. See [references/README.md](references/README.md) for the local research checkout notes; it is not a runtime or release dependency.
 
 ```text
 /creator
@@ -70,42 +66,42 @@ Repository install
           -> daemon-verified local Skill IDs -> Review installed -> Creator edit
 ```
 
-## 环境要求
+## Requirements
 
-- Node.js `>=24`（内核持久化使用 `node:zlib` 的 zstd；`package.json` engines 同源）
-- Bun `>=1.3`（开发与构建脚本）
+- Node.js `>=24` (kernel persistence uses `node:zlib`'s zstd; the `package.json` engines field is the same source of truth)
+- Bun `>=1.3` (development and build scripts)
 - pnpm `>=10`
-- Git，可被当前进程通过 `git` 命令调用
-- macOS、Windows（`arm64` / `x64`）或 Linux
+- Git, callable as `git` by the daemon process
+- macOS, Windows (`arm64` / `x64`), or Linux
 
-macOS 与 Windows 使用 `@opentray/ext-webview` 承载原生应用窗口（`appMode: true` 进入任务栏/Dock 与应用切换器；窗口焦点、层级和关闭由系统管理）。Linux 上 `@opentray/ext-webview` 没有原生包，默认进入 **web 模式**：daemon 只挂载纯 opentray 通知栏图标（菜单 + 图标），WebUI 在系统浏览器中打开。任何平台都可用 `--web` / `--no-web` 显式覆盖。
+macOS and Windows host the native app window through `@opentray/ext-webview` (`appMode: true` joins the taskbar/Dock and app switcher; focus, layering, and closing are managed by the OS). On Linux `@opentray/ext-webview` has no native package, so the default is **web mode**: the daemon mounts a plain OpenTray notification-bar icon (menu + icon) and the WebUI opens in the system browser. Any platform can override explicitly with `--web` / `--no-web`.
 
-## 安装与开发
+## Install and development
 
-根目录是 pnpm workspace，包含 `webui`。只需安装一次：
+The repository root is a pnpm workspace that includes `webui`. One install is enough:
 
 ```bash
 pnpm install
 ```
 
-启动带 HMR 的 WebUI 与开发 daemon：
+Start the WebUI with HMR and the development daemon:
 
 ```bash
-pnpm dev              # 默认（macOS/Windows 用原生窗口）
-pnpm dev --web        # 强制 web 模式：纯 tray + 浏览器，无原生窗口
-pnpm dev --no-web     # 强制 windowed 模式（覆盖 Linux 默认）
+pnpm dev              # default (native window on macOS/Windows)
+pnpm dev --web        # force web mode: plain tray + browser, no native window
+pnpm dev --no-web     # force windowed mode (overrides the Linux default)
 ```
 
-`pnpm dev` 由 `scripts/dev.sh.ts` 包装：它拦截 `--web` / `--no-web` 转成 `SKILL_CREATOR_WEB` env（vite 本身不容忍未知 flag），其余参数原样透传给 vite。Vite 会先释放正式 daemon 与上一棵开发进程树，再分配 daemon 端口，于 SvelteKit SPA fallback 之前挂载 `/api/` 与 `/ws/` 代理，并挂载开发态 OpenTray。重复执行 `pnpm dev` 不需要手动清理旧 socket；接管会等待旧 daemon 的 PID 和 IPC endpoint 同时释放。daemon 启动窗口返回可重试 `503`，不会把 API 请求误回退为 `index.html`。macOS 开发态的 home 默认为 `/tmp/sc-v2`，因此应用状态位于 `/tmp/sc-v2/.skill-creator/`，不会读写正式用户状态。Windows 使用系统临时目录下的 `skill-creator-v2-dev`。
+`pnpm dev` is wrapped by `scripts/dev.sh.ts`: it intercepts `--web` / `--no-web` into the `SKILL_CREATOR_WEB` env (vite itself rejects unknown flags) and passes everything else through to vite. Vite first releases the production daemon and any previous dev process tree, then allocates the daemon port, mounts the `/api/` and `/ws/` proxies ahead of the SvelteKit SPA fallback, and mounts the dev-mode OpenTray. Repeated `pnpm dev` runs need no manual socket cleanup; the takeover waits for both the old daemon's PID and IPC endpoint to release. During the daemon startup window the API returns a retryable `503` instead of falling back to `index.html`. On macOS the dev home defaults to `/tmp/sc-v2`, so app state lives under `/tmp/sc-v2/.skill-creator/` and never touches your real user state. Windows uses `skill-creator-v2-dev` under the system temp directory.
 
-构建与完整静态检查：
+Build and full static checks:
 
 ```bash
 pnpm build
 pnpm check
 ```
 
-`pnpm build` 产出：
+`pnpm build` produces:
 
 ```text
 dist/
@@ -117,64 +113,77 @@ dist/
 
 ## CLI
 
-构建后可在仓库内使用 `pnpm skill-creator <command>`；作为包安装后使用 `skill-creator <command>`。
+Inside the repository use `pnpm skill-creator <command>` after building; as an installed package use `skill-creator <command>`.
 
-| Command         | 行为                                                                                                                          |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `start`         | 启动 daemon，等待 WebUI 与 tray 完成挂载，然后显示原生窗口；web 模式打开浏览器；headless 时只提示 `openinbrowser`，不自动打开 |
-| `start --web`   | 以 web 模式启动：只挂纯 tray 图标（菜单 + 图标），不创建原生窗口，WebUI 在系统浏览器打开（Linux 默认）                        |
-| `open`          | 显示并聚焦现有 tray 窗口；web 模式降级为打开浏览器；headless 时不可用并提示 `openinbrowser`                                   |
-| `openinbrowser` | 显式在系统浏览器打开当前 daemon 的带 token WebUI URL                                                                          |
-| `status`        | 输出 PID、版本、HTTP 端口、tray 状态（mounted/web/headless）和可用的 tray 错误                                                |
-| `stop`          | 停止正式 daemon；若正式 endpoint 不存在则发现开发 daemon，并等待 endpoint 释放                                                |
-| `version`       | 输出包版本                                                                                                                    |
-| `help`          | 输出命令帮助                                                                                                                  |
+| Command         | Behavior                                                                                                                                                                         |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`         | Start the daemon, wait for the WebUI and tray to mount, then show the native window; web mode opens the browser; headless prints the `openinbrowser` hint and does not auto-open |
+| `start --web`   | Start in web mode: mount only the plain tray icon (menu + icon), no native window; the WebUI opens in the system browser (the Linux default)                                     |
+| `open`          | Show and focus the existing tray window; web mode falls back to opening the browser; unavailable headless, hinting `openinbrowser`                                               |
+| `openinbrowser` | Explicitly open the current daemon's tokened WebUI URL in the system browser                                                                                                     |
+| `status`        | Print PID, version, HTTP port, tray state (mounted/web/headless), and any tray error                                                                                             |
+| `stop`          | Stop the production daemon; if the production endpoint is gone, discover and stop the dev daemon, waiting for endpoint release                                                   |
+| `search`        | Search local skills in-process (BM25 + skill tokenizer, no daemon required); see [Skill search](#skill-search)                                                                   |
+| `version`       | Print the package version                                                                                                                                                        |
+| `help`          | Print command help                                                                                                                                                               |
 
 ```bash
 pnpm build
 pnpm skill-creator start
-pnpm skill-creator start --web   # 强制 web 模式（纯 tray + 浏览器）
+pnpm skill-creator start --web   # force web mode (plain tray + browser)
 pnpm skill-creator status
 pnpm skill-creator open
 pnpm skill-creator openinbrowser
 pnpm skill-creator stop
 ```
 
-以上命令在构建产物（`dist/`，与发布包同内容）上实测：`start` headless 输出恢复提示并以退出码 0 返回；`status` 输出 pid/版本/端口/tray 终态、DSH 宿主健康行（`--json` 输出完整状态）与带 token 的 WebUI URL；`open` 在 headless 态不可用并提示 `openinbrowser`；`openinbrowser` 打印并调用系统浏览器；`stop` 后 HTTP endpoint 立即释放，再次 `status` 报 ENOENT 并给出 `start` 恢复入口。发布包在仓库外空目录 `npm install <tarball>` 后同样以黑盒方式完成 start/status/stop/restart 实测（ccski 已打入产物，无 `link:` 依赖；复现：`bun scripts/clean-install-check.sh.ts`，证据见 `docs/release/skill-steward.md`）。运行要求 Node `>=24.0.0`（内核持久化使用 `node:zlib` 的 zstd；DSH code-runtime 依赖的 `node:module` `stripTypeScriptTypes` 需 `>=22.13`，已被 24 覆盖）。
+The commands above were exercised against the built output (`dist/`, identical to the published package): headless `start` prints the recovery hint and exits 0; `status` prints pid/version/port/tray state, the DSH host health line (`--json` prints the full state), and the tokened WebUI URL; `open` is unavailable headless and hints `openinbrowser`; `openinbrowser` prints and invokes the system browser; after `stop` the HTTP endpoint releases immediately and `status` reports ENOENT with the `start` recovery entry. The published package was black-box tested the same way (start/status/stop/restart) after `npm install <tarball>` in an empty directory outside the repo (ccski is bundled into the output, no `link:` dependency; reproduce with `bun scripts/clean-install-check.sh.ts`, evidence in `docs/release/skill-steward.md`). Runtime requires Node `>=24.0.0` (kernel persistence uses `node:zlib`'s zstd; the `node:module` `stripTypeScriptTypes` that DSH code-runtime needs requires `>=22.13`, already covered by 24).
+
+## Skill search
+
+`skill-creator search <query...>` searches every local skill — all Global Workspace provider roots plus every Imported Workspace — in-process, without the daemon:
+
+```bash
+skill-creator search "React组件设计"            # human-readable output
+skill-creator search react component --json    # machine-readable: { "results": [...] }
+skill-creator search http3 --limit 20          # limit 1..50, default 10
+```
+
+Results are canonical: multiple installations of the same skill (symlinks included) collapse into one entry with an `installations` list, and byte-identical copies fold into `duplicates`. Ranking is field-weighted BM25+ (name ×10 … body ×1) plus a frozen rerank pass, with prefix and fuzzy (typo) matching; ordering is deterministic and replayable. The first run builds a persistent index under `~/.skill-creator/search-index.json`; later runs refresh it incrementally via stat checks (mtime/size/inode/ctime), so unchanged corpora are not re-read. Exit codes: `0` on a successful query (including zero results), `1` for an empty query, a bad flag, or an index I/O failure. Design, frozen tokenizer/ranking contracts, and benchmark methodology: [docs/search-design.md](docs/search-design.md).
 
-## 技能管家（Skill Steward）
+## Skill Steward
 
-技能管家是 Manager-owned 的维护工作流：选择任务与范围 → 运行 → 审阅证据 → 人工批准 → 应用 → 必要时回滚。入口在 Workspaces 的 provider 视图 **Workflow** 标签。
+The skill steward is a Manager-owned maintenance workflow: choose a task and scope → run → review evidence → human approval → apply → roll back if needed. The entry point is the **Workflow** tab in the Workspaces provider view.
 
-## Agent 面板与 MCP 能力面
+## Agent panel and the MCP capability surface
 
-- **Agent 面板**：shell 级右栏 drawer（≥720px 常驻 440px，窄屏单屏覆盖），跨 tab 存活。会话列表/新建/切换、对话流（工具行可展开输入/结果）、ask_user_question 审批卡、model/preset/approval 配置投影；断线可见与恢复。
-- **headless 内核**：daemon 内 boot 单 `dsh-base` bundle（无 DSH webui/HTTP 面）；产品 preset 只含 persona + ask-user，bash/fs/web 等通用工具行禁用；官方 `@deepseek-ai/dsh-mcp-client` 桥把 Manager 能力注册为 `mcp__skill-creator__*` 工具。
-- **MCP 面**：`/mcp`（loopback + Bearer web token，stateless streamable HTTP）与 `skill-creator mcp`（stdio，readonly 收窄）同一实现；技能文档另有只读 resource 模板。工具结果按能力面自动附带 `ui://` 视觉卡（skill 信息/finding/proposal/安装结果，含应用内跳转），面板以沙箱 iframe 渲染，不可信文本强制转义。
-- **authority 红线**：MCP mutation 一律产 proposal（`*_propose` 工具）待人工在面板审批后经 Manager 执行；Manager 永远拥有路径、revision、启停、安装、更新与审批 authority。
+- **Agent panel**: a shell-level right drawer (440px resident ≥720px, full-screen overlay on narrow screens) that survives tab switches. Session list/create/switch, conversation streams (tool rows expand inputs/results), ask_user_question approval cards, model/preset/approval configuration projection; disconnects are visible and recoverable.
+- **Headless kernel**: the daemon boots a single `dsh-base` bundle (no DSH webui/HTTP surface); the product preset carries only persona + ask-user, with generic bash/fs/web tool rows disabled; the official `@deepseek-ai/dsh-mcp-client` bridge registers Manager capabilities as `mcp__skill-creator__*` tools.
+- **MCP surface**: `/mcp` (loopback + Bearer web token, stateless streamable HTTP) and `skill-creator mcp` (stdio, readonly-narrowed) share one implementation; skill documents also have a readonly resource template. Tool results automatically attach `ui://` visual cards per capability (skill info/findings/proposals/install results, with in-app navigation); the panel renders them in sandboxed iframes with untrusted text forcibly escaped.
+- **Authority red line**: MCP mutations always produce proposals (`*_propose` tools) awaiting human approval in the panel before the Manager executes them; the Manager forever owns path, revision, toggle, install, update, and approval authority.
 
-### 模型配置
+### Model configuration
 
-- 打开 Workflow 标签即显示当前 runtime config（模型、preset、approval 策略、revision）。preset 为 `deterministic`（内置脚本化 transport，零凭据、可离线）或 `live`（真实 provider）。
-- 切到 `live` 需要先为所选 provider 写入 API key（凭据存 daemon 私有文件 `0600`，UI 只回显 configured 状态，永不回显值）。
-- approval 策略 `ask` / `never` 只影响 agent 运行时的交互策略；**apply 永远要求人工批准的一次性 grant**，该策略不构成授权放宽。
+- Opening the Workflow tab shows the current runtime config (model, preset, approval policy, revision). The preset is `deterministic` (built-in scripted transport, zero credentials, works offline) or `live` (a real provider).
+- Switching to `live` requires writing an API key for the chosen provider first (credentials live in a daemon-private file `0600`; the UI only echoes the configured state, never the value).
+- The approval policy `ask` / `never` only affects the agent's interaction policy while running; **apply always requires a human-approved one-time grant** — the policy never widens authorization.
 
-### 维护流程
+### Maintenance flow
 
-1. 选任务：`Check`（只读体检）、`Optimize`（编辑优化）、`Organize`（拆分/合并/启停整理）。
-2. 选范围：勾选技能子集（留空 = 整个 Provider），可附加上限 2000 字的补充指令。
-3. `Run`：daemon 建快照、agent 通过五个域白名单工具执行（每次调用回 Manager registry 审计），产出提案。
-4. 审阅：每张提案卡 `Validate`（逐项 checks）→ `Approve`（铸造一次性 grant，绑定 patch fingerprint 与全部输入 revision）→ `Apply`（journaled 事务；mutation diff 表列出 relPath/语义/revision 变化）。
-5. 回滚：`Prepare rollback` 后按提案类型二选一——启停类逆操作是反向提案（需再走 Approve reverse / Apply reverse）；拆分/合并类直接 `Rollback (replay)` 反向重放 journal。磁盘逐字节恢复由事务层保证。
+1. Pick a task: `Check` (read-only health inspection), `Optimize` (edit optimization), `Organize` (split/merge/toggle cleanup).
+2. Pick a scope: check a subset of skills (empty = the whole Provider), optionally with up to 2000 characters of supplementary instructions.
+3. `Run`: the daemon takes a snapshot, the agent executes through five domain-whitelisted tools (every call returns to the Manager registry for audit), and proposals come out.
+4. Review: each proposal card goes `Validate` (per-item checks) → `Approve` (mints a one-time grant bound to the patch fingerprint and all input revisions) → `Apply` (a journaled transaction; the mutation diff table lists relPath/semantics/revision changes).
+5. Roll back: after `Prepare rollback`, choose per proposal type — toggle-type reverse operations are reverse proposals (Approve reverse / Apply reverse again); split/merge types roll back directly with `Rollback (replay)` replaying the journal backwards. Byte-exact disk restoration is guaranteed by the transaction layer.
 
-### 恢复流程
+### Recovery flows
 
-- **DSH 内核不可用**（缺包/版本不符/插件失败）：daemon 显式降级为 Manager-only 面（无 Agent 会话；`agent.*` 返回 typed UNAVAILABLE），`status` 的 `dsh` 字段携带降级原因；重启 daemon 是恢复内核的入口。
-- **apply 终态 `recovery-required` / `compensated`**：提案卡显示横幅与 daemon 侧失败原因；`compensated` 表示事务内已自动回滚，`recovery-required` 表示需要按提示处理残留（文件状态被保全，不静默覆盖）。处理后重新运行任务生成新提案——revision 漂移的旧提案在 validation 即被拒绝（`stale`）。
-- **断线重连**：任务/范围选择、runtime config 与最近一次 run 投影跨重连存活；迟到响应一律不覆盖新状态。
-- **daemon 重启**：`skill-creator stop && skill-creator start`；未消费的审批 grant 全部失效（不重放授权），需要重新批准。
+- **DSH kernel unavailable** (missing package/version mismatch/plugin failure): the daemon explicitly degrades to the Manager-only surface (no agent sessions; `agent.*` returns a typed UNAVAILABLE) and `status`'s `dsh` field carries the reason; restarting the daemon is the recovery path.
+- **Apply terminal states `recovery-required` / `compensated`**: the proposal card shows a banner with the daemon-side failure reason; `compensated` means the transaction already rolled itself back, `recovery-required` means leftovers must be handled per the hint (file state is preserved, never silently overwritten). Re-run the task for fresh proposals afterwards — proposals whose revisions drifted are rejected at validation (`stale`).
+- **Reconnects**: task/scope selection, runtime config, and the latest run projection survive reconnects; late responses never overwrite newer state.
+- **Daemon restart**: `skill-creator stop && skill-creator start`; unconsumed approval grants all expire (authorizations are never replayed) and need re-approval.
 
-## 运行架构
+## Runtime architecture
 
 ```text
 src/cli/cli.ts
@@ -210,7 +219,7 @@ src/daemon/ipc-server.ts ---------------------- single-instance owner
                     |       `-- proposals --------- mutation→proposal approval chain
                     |-- capability/ ------------- capability-core + domain registry
                     |-- dsh-settings.ts ------- model/preset/permissions
-                    `-- acp-bridge-service.ts  [internal legacy] agent subprocess + fs security gate（产品入口已移除，3.2）
+                    `-- acp-bridge-service.ts  [internal legacy] agent subprocess + fs security gate (product entry removed, 3.2)
 
 src/shared/rpc-contract.ts
     ^                    ^
@@ -218,24 +227,24 @@ src/shared/rpc-contract.ts
  daemon              webui/src/lib/rpc-client.ts
 ```
 
-浏览器安全的契约由 `src/shared/rpc-contract.ts` 统一组合，具体 schema 物理拆分在 `src/shared/contracts/`：
+Browser-safe contracts compose in `src/shared/rpc-contract.ts`, with the concrete schemas physically split under `src/shared/contracts/`:
 
-| RPC module     | Procedures                                                                                                                                                                                     |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `skills`       | `list`, `info`, `toggle`, `validate`, `update.check`, `update.apply`                                                                                                                           |
-| `workspace`    | `list`, `add`, `remove`, `setActive`                                                                                                                                                           |
-| `creator`      | `save`, `load`, `remove`, `revisions`                                                                                                                                                          |
-| `repository`   | `scan`, `preview`, `install`, `sources.list`, `sources.add`, `sources.remove`                                                                                                                  |
-| `daemon`       | `status`                                                                                                                                                                                       |
-| `skillSteward` | `startRun`, `validate`, `approve`, `apply`, `prepareRollback`, `applyRollback`（人类审批面；apply/rollback 为 journaled 事务）                                                                 |
-| `agent`        | `sessions.list/streams`, `session.create/prompt/cancel/stream/answer`, `card.get`, `proposals.list/approve/reject`, `settings.get/update`, `credentials.set/clear`（面板 + 审批链 + 配置投影） |
-| `acp`          | `agents.list`, `session.open`, `session.close`（internal legacy，非产品入口）                                                                                                                  |
+| RPC module     | Procedures                                                                                                                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `skills`       | `list`, `info`, `toggle`, `validate`, `update.check`, `update.apply`                                                                                                                                            |
+| `workspace`    | `list`, `add`, `remove`, `setActive`                                                                                                                                                                            |
+| `creator`      | `save`, `load`, `remove`, `revisions`                                                                                                                                                                           |
+| `repository`   | `scan`, `preview`, `install`, `sources.list`, `sources.add`, `sources.remove`                                                                                                                                   |
+| `daemon`       | `status`                                                                                                                                                                                                        |
+| `skillSteward` | `startRun`, `validate`, `approve`, `apply`, `prepareRollback`, `applyRollback` (human approval surface; apply/rollback are journaled transactions)                                                              |
+| `agent`        | `sessions.list/streams`, `session.create/prompt/cancel/stream/answer`, `card.get`, `proposals.list/approve/reject`, `settings.get/update`, `credentials.set/clear` (panel + approval chain + config projection) |
+| `acp`          | `agents.list`, `session.open`, `session.close` (internal legacy, not a product entry)                                                                                                                           |
 
-WebUI 直接从共享契约推导 client 类型；daemon 通过同一契约实现 handler。网络输入和输出都经过 Zod runtime validation。
+The WebUI derives its client types from the shared contract; the daemon implements handlers against the same one. Network input and output both pass Zod runtime validation.
 
-Workspace 列表、Skill 列表/详情和 Repository 扫描/预览分别使用独立请求代次；新请求、作用域切换或 RPC client 更替会使旧响应失去提交资格，避免慢响应覆盖新界面状态。失效的读写请求不会触发新连接的后续刷新或导航；Creator 已接纳的 dirty draft 不因断线重连被清空。
+Workspace lists, skill lists/details, and repository scan/preview each carry an independent request generation; a newer request, a scope switch, or an RPC client replacement revokes an older response's commit eligibility so slow responses never clobber fresh UI state. Revoked read/write requests never trigger follow-up refreshes or navigation on a new connection; a dirty draft the Creator has accepted survives disconnect-reconnects.
 
-## 安全模型
+## Security model
 
 ```text
 explicit import path
@@ -253,32 +262,32 @@ Git source + ref --> temporary clone --> commit SHA --> repo_<session>
                                       preview/install --+--> same snapshot
 ```
 
-- HTTP 仅监听 `127.0.0.1`。`/api/health` 和静态 SPA 不执行文件系统 mutation。
-- daemon 每次启动生成 32-byte Web token。token 经 URL fragment 交给 WebUI，捕获到当前标签页的 `sessionStorage` 后从地址栏移除；`/ws/rpc` 在升级前校验 token。
-- IPC endpoint 是单例锁。macOS 上 runtime 目录权限为 `0700`、socket 为 `0600`；Windows 使用 `\\.\pipe\skill-creator-sock`。
-- Workspace、Provider、Skill、Repository Session 与 Remote Skill 均由 server 生成或验证的身份约束。除 `workspace.add` 的显式导入和 `repository.scan` 的 Git source 外，mutation 不接受调用方输出路径。
-- daemon 生命周期内只有一个内存 Workspace Registry。持久路径必须绝对且规范化，`ws_*` 必须与路径 digest 相符；导入、移除和切换先原子提交完整 next state，再替换内存状态。`skillCount` 与可用性只在读取时派生，永不写入 registry。
-- Creator 新建只允许已导入 Workspace.Provider 的直接子目录；编辑和删除必须仍在该 Provider root 内。文档使用临时文件加 rename 原子落盘，update/delete 以 SHA-256 revision 拒绝陈旧操作。
-- Repository 扫描先 clone，再用 Zod 收窄 HEAD commit。预览和安装复用同一临时快照与 session ID；淘汰立即拒绝新操作，但会让已接受的安装持有快照直到完成。daemon stop 会终止 pending clone，且 late scan 不得重新登记 session。
-- Repository 安装不能指向 `~`；每个目标必须是一个已导入、可写的 Workspace.Provider。多选目标会得到逐 skill、逐目标的独立结果。
-- Repository 安装汇总携带提交时的 Workspace.Provider target；ccski installer output 先经 runtime schema 收窄，只有实际 `installed` / `overwritten` 且重新验证为 Provider root 直属、非符号链接 `SKILL.md` 目录的结果项会获得本地 Skill ID，供 Creator 复核。
-- daemon 在 tray mount 前发布 stop coordinator 与 signal listeners。stop 先关闭 HTTP/WebSocket 与 IPC admission，再并行回收 Repository、tray 与连接；mount 期间迟到的 native handles 会被立即销毁，非协作 socket 在 grace deadline 后强制关闭，并发 stop 合并为同一完成态。
-- 所有外部读取先解码为 `unknown`，再用当前 Zod schema `safeParse`。配置文件、未来数据库记录和第三方/网络返回中不兼容的快照按其领域投影为空，集合丢弃无效项，不能读取为安全空值的结果返回类型化失败；RPC/IPC、鉴权、路径和 mutation 输入仍明确拒绝，绝不降级为空。
-- 当前 v2 registry 没有旧 schema 的迁移层。JSON 语法错误或不符合当前 Zod schema 的旧状态整体按空值加载：不读取、不转换、不在加载时写回；下一次正常 workspace mutation 才原子提交当前 v2 状态。文件 I/O 错误仍拒绝启动并写入当前 home 下的 `.skill-creator/logs/daemon.log`。当前没有数据库实现；引入后数据库读取必须遵循同一投影法则。
-
-## 状态路径
-
-| 状态               | macOS / release                           | Windows / release                              |
+- HTTP listens on `127.0.0.1` only. `/api/health` and the static SPA perform no filesystem mutations.
+- The daemon mints a 32-byte web token at every startup. The token reaches the WebUI through the URL fragment, is captured into the tab's `sessionStorage`, and is removed from the address bar; `/ws/rpc` validates it before the protocol upgrade.
+- The IPC endpoint is the single-instance lock. On macOS the runtime directory is `0700` and the socket `0600`; Windows uses `\\.\pipe\skill-creator-sock`.
+- Workspace, Provider, Skill, Repository Session, and Remote Skill are all bound to server-generated or server-verified identities. Apart from the explicit import in `workspace.add` and the Git source in `repository.scan`, mutations never accept caller-supplied output paths.
+- Exactly one in-memory Workspace Registry lives for the daemon's lifetime. Persisted paths must be absolute and normalized; `ws_*` must match the path digest; import, remove, and switch atomically commit the full next state before replacing memory. `skillCount` and availability derive at read time and are never written back.
+- Creator drafts may only create direct children of an imported Workspace.Provider; edits and deletes must stay inside that Provider root. Documents land atomically via a temp file plus rename; update/delete reject stale operations on SHA-256 revision mismatch.
+- Repository scans clone first, then narrow the HEAD commit with Zod. Preview and install reuse the same temporary snapshot and session ID; eviction immediately rejects new operations but lets accepted installs hold the snapshot until done. daemon stop aborts pending clones, and late scans cannot re-register a session.
+- Repository installs cannot target `~`; every target must be an imported, writable Workspace.Provider. Multiple targets yield per-skill, per-target independent results.
+- The repository install summary carries the Workspace.Provider targets committed at install time; the ccski installer output is first narrowed by a runtime schema, and only items actually `installed` / `overwritten` and re-verified as a direct, non-symlink `SKILL.md` child of the Provider root receive a local Skill ID for Creator review.
+- The daemon publishes its stop coordinator and signal listeners before mounting the tray. Stop closes HTTP/WebSocket and IPC admission first, then reclaims repository, tray, and connections in parallel; native handles arriving late during mount are destroyed immediately, uncooperative sockets are force-closed after the grace deadline, and concurrent stops converge on one completion state.
+- Every external read decodes to `unknown` first and then runs the current Zod schema's `safeParse`. Incompatible snapshots inside config files, future database records, and third-party/network responses project to their domain's empty value; collections drop invalid entries; results that cannot safely read as empty return typed failures. RPC/IPC, authentication, paths, and mutation inputs are still rejected explicitly — never degraded to empty.
+- The current v2 registry has no migration layer for older schemas. JSON syntax errors or states that fail the current Zod schema load as empty: nothing is read, converted, or written back at load time; the next normal workspace mutation atomically commits the current v2 state. File I/O errors still refuse startup and log to `.skill-creator/logs/daemon.log` under the current home. There is no database today; when one lands, database reads must follow the same projection law.
+
+## State paths
+
+| State              | macOS / release                           | Windows / release                              |
 | ------------------ | ----------------------------------------- | ---------------------------------------------- |
-| 应用目录           | `~/.skill-creator/`                       | `%USERPROFILE%\.skill-creator\`                |
+| App directory      | `~/.skill-creator/`                       | `%USERPROFILE%\.skill-creator\`                |
 | Workspace registry | `~/.skill-creator/workspaces.json`        | `%USERPROFILE%\.skill-creator\workspaces.json` |
-| 用户 Repository 源 | `~/.skill-creator/sources.json`           | `%USERPROFILE%\.skill-creator\sources.json`    |
+| User repo sources  | `~/.skill-creator/sources.json`           | `%USERPROFILE%\.skill-creator\sources.json`    |
 | Daemon log         | `~/.skill-creator/logs/daemon.log`        | `%USERPROFILE%\.skill-creator\logs\daemon.log` |
 | IPC                | `~/.skill-creator/run/skill-creator.sock` | `\\.\pipe\skill-creator-sock-<home-digest>`    |
 
-`SKILL_CREATOR_HOME` 可覆盖当前命令的 home 根目录；应用仍在该目录下创建 `.skill-creator/`。`SKILL_CREATOR_DEV_HOME` 专门覆盖开发 runtime 的发现路径；macOS 默认对应 `/tmp/sc-v2/.skill-creator/`。
+`SKILL_CREATOR_HOME` overrides the home root for the current command; the app still creates `.skill-creator/` under it. `SKILL_CREATOR_DEV_HOME` overrides the dev runtime discovery path specifically; on macOS it defaults to `/tmp/sc-v2/.skill-creator/`.
 
-## 验证
+## Verification
 
 ```bash
 pnpm test