install-bensz-skills

Files (13)

• CHANGELOG.md
• README.md
• SKILL.md
• config.yaml
• install-report-template.md · references/
• __init__.py · scripts/
• bootstrap_install.py · scripts/
• i18n.py · scripts/
• install.py · scripts/
• managed-runtime.json · scripts/
• managed_runtime.py · scripts/
• remove_legacy_skills.py · scripts/
• update_remote_skills.py · scripts/

SKILL.md (first lines)

# Install Bensz Skills（系统级安装器）

## 目标

当需要把本仓库 skills/alpha 下的生产 skills 安装到系统级（默认同时安装到 Codex: ~/.codex/skills 和 Claude Code: ~/.claude/skills），以便在任意项目/对话中可被发现与调用时使用。默认不安装 skills/beta；只有显式指定 beta 源目录时才处理 beta skill。使用 MD5 哈希进行版本控制，仅安装有更新的 skills；支持 --skill 指定单个或少量技能安装/更新、强制覆盖安装、指定单一目标安装和远程安装模式（--remote --check/--auto）。远程场景另提供版本预检脚本，默认只筛选包含 `huangwb8` 的远程源。

目的：把当前仓库 `skills/alpha/` 中的生产 skills（**包括 install-bensz-skills 自身**）**复制安装**到：

- Codex：`~/.codex/skills/`
- Claude Code：`~/.claude/skills/`

从而让这些 skills 在**任意项目**里都能被发现与触发（不依赖当前 workdir，也不使用软链接）。

## 流程

### 输入

#### 输入参数

- **源目录**：默认从当前项目或祖先目录发现 `./skills/alpha/`；beta 仅在显式传入 `--source` 时使用。
- **目标平台**：默认 Codex 与 Claude Code；可用 `--codex` 或 `--claude` 限定单一目标。
- **安装选择**：可选 `--skill`、`--force`、`--dry-run`、`--source`，以及远程模式的 `--remote --check/--auto` 与源过滤参数。
- **运行环境**：本地完整安装器要求 Python 3.11+；Python 3.8–3.10 仅支持标准库 bootstrap 的远程首次/应急安装。
- **远程快速更新**：运行 `scripts/update_remote_skills.py`；它只影响远程安装，本地源码安装仍使用原有 MD5 策略。
- **托管运行时**：默认使用安装器独占的 `~/.bensz-skills/envs/benszapi` Conda prefix；当前托管最新版生产 BSK，包清单由 `scripts/managed-runtime.json` 定义。
- **静默更新**：宿主在新任务/会话入口可调用 `python3 "$INSTALLER" --silent-update`；它只在 72 小时状态过期时检查，更新托管运行时，并增量更新已安装技能。

### 执行步骤

#### 你要做的事（触发后必须执行）

用户明确选择 `--remote --check` 仅授权下载、缓存和对比预览；安装/更新前仍按流程询问确认。用户明确选择 `--remote --auto` 才授权无确认的系统级安装/更新。未明确授权远程模式时，不进行远程下载或远程写入；本地模式仍按用户明确的安装请求执行本地源检查及系统级安装、更新或 legacy 清理。

执行前先确认 `python3` 版本。Python 3.11+ 才能使用本地完整安装器；不要检查当前项目目录下是否存在 `./install-bensz-skills/scripts/install.py`，也不要把本地脚本作为优先入口，而应直接从系统级已安装位置查找：优先 `~/.codex/skills/install-bensz-skills/scripts/install.py`，其次 `~/.claude/skills/install-bensz-skills/scripts/install.py`。安装源目录默认从当前工作目录及其祖先目录自动识别当前项目的 `./skills/alpha/`，因此可从项目子目录运行；`./skills/beta/` 永不自动选中，只有用户明确传入 `--source ./skills/beta`（或其它 beta 根目录）时才允许安装 beta。

Python 3.8–3.10 只能使用标准库 bootstrap 进行远程首次/应急安装，不得调用本地完整安装器；若任务要求安装本地源码、显式 beta 目录或运行 Kernel，应说明必须升级到 Python 3.11+。Python 3.8 以下不受支持。

本地安装器默认不会扫描历史 `pipelines/skills/alpha/`；仅迁移旧仓库时可显式传入 `--legacy-source`。bootstrap 最低支持 Python 3.8，仓库开发、本地完整安装器和 Kernel 统一要求 Python 3.11+。两入口写入同一 manifest 核心契约：`schema_version`、`source`、`target`、`target_root`、`skills[]`（名称、MD5、状态、原因）和运行时间；本地入口可附加实现细节。

##### 托管 benszapi 运行时

运行 BSK 前先确保系统级安装器可用，再执行：

```bash
# 创建缺失的 Conda 环境；超过 72 小时时更新到最新生产版并运行健康检查
python3 "$INSTALLER" --ensure-runtime

# 只读检查环境、已安装包版本和 BSK 健康状态
python3 "$INSTALLER" --runtime-status

# 忽略 TTL，立即检查并更新
python3 "$INSTALLER" --force-runtime-update

# 系统 Python 只有 3.8-3.10 或尚未安装完整安装器时，使用 bootstrap
python3 /path/to/bootstrap_install.py --ensure-runtime
```

环境固定在 `~/.bensz-skills/envs/benszapi`，不采用或修改其它 Conda 安装中的同名环境。安装器依次查找 `BENSZ_CONDA_EXE`、`CONDA_EXE`、`conda`、`mamba`、`micromamba`；首次创建后直接使用该 prefix 的 Python 更新包，避免 PATH 和解释器错配。成功后生成 `~/.bensz-skills/bin/bsk`；Skill 与 AI 应调用这个固定入口，不调用 PATH 中来源不明的裸 `bsk`，也不通过系统 `python3` 导入 Kernel。

`--ensure-runtime` 使用 72 小时 TTL；环境缺失、健康检查失败或实际包版本偏离上一次成功状态时不受 TTL 限制。更新完成后必须通过包版本读取、`bsk --version`、`bsk diagnostics` 和 `bsk capabilities`。更新失败时不删除已有环境；静默入口记录失败并继续当前任务，显式入口返回非零状态。

##### 本地安装

1) 先定位系统级安装器脚本：

```bash
CODEX_INSTALLER="$HOME/.codex/skills/install-bensz-skills/scripts/install.py"
CLAUDE_INSTALLER="$HOME/.claude/skills/install-bensz-skills/scripts/install.py"
if [ -f "$CODEX_INSTALLER" ]; then
  INSTALLER="$CODEX_INSTALLER"
elif [ -f "$CLAUDE_INSTALLER" ]; then
  INSTALLER="$CLAUDE_INSTALLER"
else
  echo "未找到系统级 install-bensz-skills 安装器" >&2
  exit 1
fi
```

2) 运行安装脚本：

```bash
# 默认：同时安装到 Codex 和 Claude Code（仅安装有更新的）
# 说明：脚本默认只自动识别 ./skills/alpha；beta 必须显式 --source
python3 "$INSTALLER"

# 仅安装到 Claude Code
python3 "$INSTALLER" --claude

# 仅安装到 Codex
python3 "$INSTALLER" --codex

# 强制重新安装所有 skills（忽略版本检查）
python3 "$INSTALLER" --force

# 仅安装/更新指定 skill（不存在则新安装，已存在则按 MD5 判断更新或跳过）
python3 "$INSTALLER" --skill nsfc-bib-manager

# 预览模式（不实际安装）
python3 "$INSTALLER" --dry-run

# 指定额外 skills 源目录
python3 "$INSTALLER" --source /path/to/skills

# 显式安装 beta（不会被默认扫描）
python3 "$INSTALLER" --source ./skills/beta

# 多个源目录（逗号分隔）
python3 "$INSTALLER" --source /path/skills-a,/path/skills-b
```

也可以直接运行某个系统级脚本路径：

```bash
# Codex 安装位置（优先）
python3 ~/.codex/skills/install-bensz-skills/scripts/install.py

# 或 Claude Code 安装位置
python3 ~/.claude/skills/install-bensz-skills/scripts/install.py

From huangwb8/skills, MIT.

More from huangwb8/skills