skills-console 0.4.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,145 @@
+# Skills Console 架构说明
+
+本文描述 `0.4.0` 的实际实现、信任边界和故障语义。产品介绍与命令入口见 [README](../README.md)，部署和发布操作见 [运维与发布手册](OPERATIONS.md)。
+
+## 1. 系统边界
+
+Skills Console 是单机、单进程的 Node.js 应用，没有服务端、数据库、守护进程或产品遥测。它由三个边界清晰的部分组成：
+
+1. 扫描器只读本地 Agent Skill 根目录，生成统一 Inventory。
+2. TUI/CLI 消费 Inventory，提供查看、诊断和期望状态能力。
+3. 变更适配器委托固定版本的 `skills` CLI 写入，并由事务层备份、记录和复扫验证。
+
+```text
+Agent Skill roots ──read──> filesystem adapters ──> Inventory
+                                                    │
+                                      ┌─────────────┴─────────────┐
+                                      │                           │
+                                  Ink TUI                  non-interactive CLI
+                                      │
+                               application use cases
+                                      │
+                           snapshot → skills CLI → rescan
+                                      │
+                              History + verification
+```
+
+本地文件系统而非上游终端文本是安装状态的事实来源。上游 CLI 的退出码是执行信号，不能单独代表状态已经改变。
+
+## 2. 代码分层
+
+```text
+src/
+├── cli.tsx                    # 进程入口、TTY/CLI 分流
+├── cli-commands.ts            # 非交互命令与退出码
+├── version.ts                 # 应用显示版本
+├── ui/                        # Ink 页面、向导和键盘交互
+├── application/               # 清单、操作、Profile、历史、备份和恢复用例
+├── domain/                    # Inventory、Profile、Operation 类型和规则
+├── adapters/
+│   ├── filesystem/            # Agent registry、SKILL.md、lock 与目录扫描
+│   └── skills-cli/            # 命令计划、执行器和来源预览解析
+└── platform/                  # 环境检测、XDG 路径和脱敏
+```
+
+Domain 不依赖 Ink 或具体外部 CLI。UI 只编排 use case；文件系统、副进程和持久化行为集中在 adapter/application 层，因此核心规则可以在非 TTY 和临时目录中测试。
+
+## 3. Inventory 读取模型
+
+启动或刷新时执行以下流程：
+
+1. 解析当前目录向上的 `.git`，确定项目根；没有 Git 根时使用当前目录。
+2. 检测 OS、WSL、Node、`npx` 和各 Agent 的命令、配置标记及已有私有目录。
+3. 合并同一物理路径被多个 Agent 共享的根目录。
+4. 扫描包含 `SKILL.md` 的目录或软链接，解析 YAML frontmatter 和 `skills-lock.json` 来源。
+5. 按 realpath 去重，保留一个 Skill 的多个安装实例、作用域、Agent 归属和有效性。
+6. 将无权限、无效 manifest、断链、重复或覆盖等问题转为诊断，不因单个根失败而终止全部扫描。
+
+根目录分为 `agent`、`shared`、`system` 和 `plugin-cache`。可变性来自 registry 声明与实际写权限的共同约束；`system` 和 `plugin-cache` 始终只读。
+
+## 4. 上游 CLI 集成
+
+`skills` 固定为直接依赖 `1.5.17`。运行时通过 Node 模块解析得到该包的 `bin/cli.mjs`，再由当前 Node 可执行文件启动；界面将同一计划显示为熟悉的 `npx skills@1.5.17 ...` 形式。
+
+每个命令计划包含：
+
+- executable 与独立 args 数组；
+- cwd、环境变量和是否修改文件系统；
+- 操作类型、Skill、Agent、作用域和来源；
+- 由相同参数生成并脱敏的 displayCommand。
+
+执行器使用 `spawn(..., {shell: false})`，并设置 `DISABLE_TELEMETRY=1` 和 `DO_NOT_TRACK=1`。Skill 名称和 Agent ID 必须满足小写连字符格式，来源拒绝控制字符。产品不会执行来源仓库中的 Skill 脚本。
+
+## 5. 写操作事务
+
+安装、更新、移除和可逆 Doctor 修复都遵循同一个安全框架：
+
+```text
+构建计划 → 展示预览/确认 → 解析允许写入的根
+        → 创建快照和进行中 History
+        → 执行外部 CLI 或内部可逆修复
+        → 重新扫描 Inventory
+        → 完成快照中的新增路径清单
+        → 记录退出码、脱敏日志和验证结论
+```
+
+快照保存已有目录内容、原路径、realpath、作用域和软链接元数据。恢复时先删除本次新增路径，再恢复旧内容。所有目标必须位于该快照记录的允许根内；备份内容也必须位于快照目录内。软链接原目标不存在时，以普通目录恢复内容并记录 fallback。
+
+验证状态有三种：
+
+- `verified`：安装目标存在，或被移除的可变实例已消失。
+- `failed`：外部命令失败、上游报告 no-op，或复扫状态与预期冲突。
+- `indeterminate`：更新后 Skill 仍存在，但当前没有可靠的内容级版本证明。
+
+上游即使退出 `0`，只要输出匹配已知 no-op 语义也会判为失败。
+
+## 6. History 与数据持久化
+
+默认数据根为 `~/.local/share/skills-console/`；设置 `XDG_DATA_HOME` 时使用 `$XDG_DATA_HOME/skills-console/`。
+
+```text
+skills-console/
+├── history/<operation-id>.json
+└── backups/<snapshot-id>/
+    ├── snapshot.json
+    └── content/<entry-id>/...
+```
+
+History JSON 和 snapshot manifest 均带 `schemaVersion: 1`。操作日志在落盘前移除控制序列并脱敏，最多保留最后 200 行。当前版本没有自动保留期限，容量治理由运维人员负责，删除前应确认不再需要回滚。
+
+## 7. Profile 期望状态
+
+Profile schema v1 将 Skill 名称、可复现来源、目标 Agent、作用域和安装模式声明为项目期望状态。Diff 完全只读；Apply 将 drift 编译为安装、移除或跳过计划并顺序执行：
+
+- 缺失或来源不一致但没有 source 时跳过；
+- 来源未知时拒绝覆盖；
+- 默认不删除 extra，只有 `removeExtras: true` 才生成移除计划；
+- 默认忽略用户作用域，只有 `manageUserScope: true` 才管理；
+- 每项变更拥有独立快照；任一验证失败后停止后续操作。
+
+完整协议见 [PROFILES](PROFILES.md)。
+
+## 8. 安全与隐私
+
+主要信任边界是本地文件系统、用户提供的来源和受版本约束的上游 CLI。
+
+- 不使用 shell 字符串拼接，减少命令注入面。
+- 不跟随越界软链接执行删除或恢复。
+- 只向 registry 明确标记为 mutable 的根写入。
+- 备份失败、路径越界或目标冲突时 fail closed。
+- 日志中的 URL 凭据、token 和敏感参数先脱敏再持久化。
+- 产品本身不上传本地路径、Skill 元数据或使用情况。
+- 上游依赖仍属于供应链边界；升级 `skills` 必须重新执行完整发布验证。
+
+## 9. 已知边界
+
+- 更新没有内容 hash 或上游 commit 的强验证，结果可能是 `indeterminate`。
+- 来源清单解析依赖 `skills@1.5.17` 的人类可读输出；固定版本降低但不能消除格式风险。
+- 目前没有跨进程锁；同一数据根不应并发执行多个写操作。
+- History/backup 没有自动清理策略。
+- Windows 原生的路径与软链接权限尚未完成发布验收。
+- JSON Inventory 当前由领域模型直接序列化，消费者应固定 Skills Console 版本并容忍新增字段。
+
+## 10. 质量门禁
+
+核心扫描、frontmatter、lock、命令构建/执行、操作验证、备份/恢复、Doctor、Profile 和 CLI 均由 Vitest 覆盖。自动化测试使用临时 HOME/XDG 与 fake process，不接触真实用户 Skill 目录。每次交付至少执行类型检查、测试、构建、tarball 清单检查和隔离安装冒烟测试。

package/docs/OPERATIONS.md

@@ -0,0 +1,200 @@
+# Skills Console 运维与发布手册
+
+本文是 `0.4.0` 的安装、运行、恢复和版本发布 runbook。架构与安全边界见 [ARCHITECTURE](ARCHITECTURE.md)。
+
+## 1. 交付基线
+
+正式交付形态包括：
+
+- Git 源码与 lockfile；
+- 经 `tsc` 生成的 Node.js ESM CLI/TUI；
+- 由 `npm pack` 生成、可在隔离环境安装的 tarball；
+- README、架构、Profile 协议、运维手册和 changelog；
+- Vitest 自动化测试。
+
+| 项目 | 发布基线 |
+| --- | --- |
+| 版本 | `0.4.0` |
+| 运行时 | Node.js `>=22`、npm `>=10` |
+| 固定写操作后端 | `skills@1.5.17` |
+
+支持矩阵：Linux、macOS、WSL；Windows 原生未发布验收
+
+项目以 MIT License 开源，通过公开 GitHub 仓库和 `skills-console` npm 包交付。`publishConfig` 固定为 public 并启用 provenance；长期发布使用 GitHub Actions OIDC，不保存 npm 写入 token。
+
+## 2. 标准安装
+
+生产或验收环境应从 lockfile 做确定性安装：
+
+```bash
+node --version
+npm --version
+npm ci
+npm run build
+node dist/cli.js --version
+```
+
+全局安装 tarball：
+
+```bash
+npm pack
+npm install --global ./skills-console-0.4.0.tgz
+skills-console --version
+```
+
+从 npm 安装：
+
+```bash
+npx skills-console
+npm install --global skills-console
+```
+
+不要以 root 运行 TUI，也不要让多个 Skills Console 进程并发修改同一 HOME/XDG 数据根。
+
+## 3. 上线冒烟检查
+
+在目标用户身份、目标项目目录中依次执行：
+
+```bash
+skills-console --version
+skills-console inventory
+skills-console inventory --json
+skills-console profile validate ./examples/skills-profile.json
+```
+
+交互环境再启动 `skills-console`，确认：
+
+1. 六个页面可导航，项目根和 OS/WSL 识别正确。
+2. Inventory 数量与已知 Agent 目录相符；单个损坏 Skill 只形成诊断，不导致退出。
+3. 安装来源预览可以取消且不产生目标文件。
+4. 使用测试 Skill 完成一次安装、移除和 History 恢复。
+5. 更新成功后若显示 `indeterminate`，按已知限制处理，不将其误报为强验证成功。
+
+真实写操作验收应使用专门测试 HOME 或可丢弃项目，不能以维护者日常 Skill 目录作为测试夹具。
+
+## 4. 自动化与退出码
+
+推荐 CI 使用：
+
+```bash
+skills-console inventory --json
+skills-console profile validate skills-profile.json
+skills-console profile diff skills-profile.json --json
+```
+
+退出码：
+
+| 代码 | 含义 |
+| --- | --- |
+| `0` | 成功，或 Profile 已满足 |
+| `1` | 命令、配置或运行错误 |
+| `2` | `profile diff` 发现可执行 drift |
+
+代码 `2` 是状态信号而非运行故障。CI 可将其用于提示或阻断，是否自动 apply 由项目自己的变更策略决定；本版本不提供非交互 apply 命令。
+
+## 5. 数据、备份与恢复
+
+数据根：
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/skills-console/
+```
+
+`history/` 保存操作元数据，`backups/` 保存恢复内容。二者通过 operation/snapshot ID 关联。恢复优先通过 TUI 的 History 页面选择记录并按 `z`，确认预览后执行。
+
+运维规则：
+
+- 将数据根视为可能包含本地路径和 Skill 内容的敏感数据。
+- 不单独删除仍有 History 引用的 snapshot。
+- 执行容量清理前备份整个数据根，并确认对应变更已不再需要恢复。
+- 若历史 manifest 损坏，不要手工猜测并覆盖 Skill；先复制数据根，再从 `snapshot.json` 审计 `allowedRoots`、`entries` 和 `createdPaths`。
+- 恢复结果报告 symlink fallback 时，目标已作为普通目录恢复，需要人工决定是否重建链接。
+
+## 6. 故障处理
+
+### 清单出现错误
+
+先运行 `skills-console inventory --json`，按 diagnostics 中的 `path` 和 `code` 定位。无权限、无效 frontmatter 或断链不会阻塞其他根扫描。Doctor 只对目录名不一致提供自动修复；其他问题应在来源或 Agent 目录中人工处理。
+
+### 外部命令退出 0 但状态未变化
+
+Skills Console 会识别已知 no-op 文本并判为失败，再复扫文件系统。检查 History 的脱敏日志、所选作用域和 Agent；不要只依赖上游退出码。
+
+### 更新显示 indeterminate
+
+这表示更新命令成功且 Skill 仍存在，但没有内容级证据证明版本变化。需要强保证时，在操作前后人工比较来源 commit、lock 元数据或目录 hash。
+
+### 写操作中断或失败
+
+不要立即重复批量操作。先刷新 Inventory，查看最新 History 和 verification messages；如状态不符合预期，从 History 恢复该事务，然后逐项重试。
+
+### TUI 无法启动
+
+确认当前 stdout 是 TTY、Node 版本满足要求，并使用 `skills-console inventory` 验证非交互路径。无 TTY 的 CI/管道应只使用 CLI 子命令。
+
+## 7. 版本发布质量门禁
+
+每个版本必须在干净 checkout 中执行：
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --version
+node dist/cli.js inventory --json
+node dist/cli.js profile validate examples/skills-profile.json
+npm pack --dry-run
+npm audit --omit=dev
+npm approve-scripts --allow-scripts-pending
+```
+
+检查要求：
+
+- `package.json`、lockfile、CLI 输出和 changelog 版本一致。
+- 测试与类型检查零失败。
+- tarball 只包含 `dist/`、`docs/`、`examples/`、README、CHANGELOG、LICENSE 和必要 package metadata。
+- tarball 不包含测试 fixture、coverage、日志、凭据、`.env`、本地 History 或 backup。
+- 将 tarball 安装到空临时目录，验证 `--version`、inventory 和 Profile validate。
+- Linux、macOS、WSL 至少各完成一次真实安装、更新、移除和恢复验收后，才能宣称完整平台发布。
+- 依赖审计结果必须记录；无法在线审计时明确标记为尚未完成，而不是默认为通过。
+- `allowScripts` 只批准经过审查的精确依赖版本；pending 列表必须为空。
+
+## 8. 首次 npm 发布与可信发布绑定
+
+首次占用包名需要维护者在可信终端登录 npm，并启用 2FA：
+
+```bash
+npm login
+npm whoami
+npm publish --provenance=false
+```
+
+首次发布尚未建立 OIDC 信任关系，因此必须显式关闭 provenance；这是一次性 bootstrap 例外。不要为此创建长期 automation token。
+
+首次发布成功且 `publish.yml` 已位于默认分支后，建立 GitHub Actions OIDC 信任关系：
+
+```bash
+npm trust github skills-console \
+  --file publish.yml \
+  --repo CaoLiangqiang/skills-console \
+  --allow-publish \
+  --yes
+npm trust list skills-console
+```
+
+完成绑定后不再从本地发布，也不创建或保存长期 npm 写 token。后续版本只能由 tag 触发 `publish.yml`，并使用 `package.json` 中默认启用的 provenance。仓库必须保持 public，repository URL 必须与可信发布仓库一致。
+
+## 9. Git/GitHub 发布流程
+
+1. 从受保护的默认分支创建发布准备分支。
+2. 更新版本、CHANGELOG 和与行为相关的文档。
+3. 执行第 7 节全部质量门禁并保存结果。
+4. 只提交本次发布范围内的文件，使用简短、可审计的提交说明。
+5. 推送发布分支到所有已配置、可写的远程仓库。
+6. 针对主托管仓库创建 draft PR，正文包含产品形态、实现、安全边界、验证结果和残余限制。
+7. CI 在 Node.js 22/24 上通过后将 PR 标记为 ready 并合并。
+8. 创建与 `package.json` 完全一致的 `v<version>` tag；tag 触发 `publish.yml`，使用 OIDC 发布 npm 包。
+9. 在 GitHub 创建 Release，并验证 npm 页面、provenance 和全新环境安装。
+
+如果没有远程、没有可用认证、默认分支不存在或无法确定仓库可见性，应停止外部发布并请求所有者补齐信息，不擅自创建公开仓库。

package/docs/PROFILES.md

@@ -0,0 +1,83 @@
+# Skills Profile 协议
+
+`skills-profile.json` 描述项目期望使用的 Agent Skills。该文件适合纳入版本控制，用于比较不同开发环境与项目声明的差异。当前 schema 版本为 `1`。
+
+## 示例
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "frontend-project",
+  "description": "Agent Skills desired state for the frontend project.",
+  "policy": {
+    "removeExtras": false,
+    "manageUserScope": false
+  },
+  "skills": [
+    {
+      "name": "design-taste-frontend",
+      "source": "Leonxlnx/taste-skill",
+      "agentIds": ["codex", "claude-code"],
+      "scope": "project",
+      "mode": "symlink"
+    }
+  ]
+}
+```
+
+仓库中另有可直接校验的 [示例文件](../examples/skills-profile.json)。
+
+## 字段
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `schemaVersion` | 是 | 当前必须为 `1` |
+| `name` | 是 | 配置集名称 |
+| `description` | 否 | 配置集用途说明 |
+| `policy.removeExtras` | 否 | 是否允许移除未声明 Skill，默认 `false` |
+| `policy.manageUserScope` | 否 | 是否管理用户作用域，默认 `false` |
+| `skills[].name` | 是 | 符合 Agent Skills 小写连字符规则的名称 |
+| `skills[].source` | 否 | 可复现安装来源；缺失时不能自动补装 |
+| `skills[].agentIds` | 是 | 一个或多个目标 Agent ID |
+| `skills[].scope` | 是 | `project` 或 `user` |
+| `skills[].mode` | 是 | `symlink` 或 `copy` |
+
+同一名称可以在不同作用域中分别声明；完全重复或冲突的声明会在校验阶段拒绝。
+
+## Diff 状态
+
+| 状态 | 含义 | Apply 行为 |
+| --- | --- | --- |
+| `satisfied` | 当前安装满足声明 | 无操作 |
+| `missing` | 缺少全部或部分目标 Agent 安装 | 有 source 时安装，否则跳过 |
+| `source-mismatch` | 已安装来源与声明不同 | 有 source 时重新安装，否则跳过 |
+| `source-unknown` | 无法可靠确定当前来源 | 拒绝覆盖 |
+| `extra` | 当前安装未在 Profile 声明 | 仅在 `removeExtras: true` 时移除 |
+
+## 安全语义
+
+- `profile diff` 永远只读。
+- 默认只比较项目作用域且不删除 extra。
+- Profile apply 只能在交互 TUI 中确认执行；本版本没有非交互 apply。
+- `source-unknown` 不会被自动覆盖。
+- 每一项写操作独立创建事务快照和 History。
+- Apply 顺序执行；任一项验证失败后停止后续操作。
+- 只有 `manageUserScope: true` 时，用户作用域才参与 diff/apply。
+
+开启 `removeExtras` 或 `manageUserScope` 会显著扩大写入范围，必须经过代码评审并在 TUI 中核对最终计划。
+
+## CLI
+
+```bash
+skills-console profile export [path] [--include-user] [--json]
+skills-console profile validate [path]
+skills-console profile diff [path] [--json]
+```
+
+默认路径为当前项目根的 `skills-profile.json`。Export 默认只输出项目作用域；`--include-user` 将用户安装也写入 Profile。
+
+`profile diff` 在期望状态满足时退出 `0`，存在可执行 drift 时退出 `2`，配置或运行错误退出 `1`。JSON 输出适合 CI 消费，但消费者应固定 Skills Console 版本并容忍新增字段。
+
+## 兼容性
+
+未知 `schemaVersion` 会被拒绝，不做隐式升级。对 schema 的破坏性修改必须增加版本号、迁移说明和测试，不能在 schema v1 中静默改变字段语义。

package/examples/skills-profile.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "name": "example-project",
+  "description": "Example Agent Skills desired state.",
+  "policy": {
+    "removeExtras": false,
+    "manageUserScope": false
+  },
+  "skills": [
+    {
+      "name": "design-taste-frontend",
+      "source": "Leonxlnx/taste-skill",
+      "agentIds": [
+        "codex",
+        "claude-code"
+      ],
+      "scope": "project",
+      "mode": "symlink"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "skills-console",
+  "version": "0.4.0",
+  "description": "A visual TUI control plane for Agent Skills, powered by the npx skills ecosystem.",
+  "author": {
+    "name": "CaoLiangqiang",
+    "url": "https://github.com/CaoLiangqiang"
+  },
+  "type": "module",
+  "bin": {
+    "skills-console": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CaoLiangqiang/skills-console.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CaoLiangqiang/skills-console/issues"
+  },
+  "homepage": "https://github.com/CaoLiangqiang/skills-console#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "tui",
+    "codex",
+    "claude-code",
+    "gemini-cli"
+  ],
+  "scripts": {
+    "dev": "node --import tsx src/cli.tsx",
+    "start": "node dist/cli.js",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "packageManager": "npm@11.16.0",
+  "allowScripts": {
+    "esbuild@0.28.1": true
+  },
+  "dependencies": {
+    "ink": "^7.1.0",
+    "react": "^19.2.7",
+    "skills": "1.5.17",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}