rrskill 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+# rrskill-cli
+
+`rrskill-cli/` 是当前官方 `rrskill` Node/TypeScript CLI 源码目录。
+
+这里的文档现在按职责拆开：
+
+- [README.md](./README.md)
+  - 面向使用、安装、开发
+- [ARCHITECTURE.md](./ARCHITECTURE.md)
+  - 面向架构、目录结构、文件目的、边界
+- [PUBLISHING.md](./PUBLISHING.md)
+  - 面向版本管理、打包、npm 发布、发布后 smoke
+
+## 1. 包定位
+
+这个目录里的 CLI 当前具备：
+
+- Node runtime
+- TypeScript 主实现
+- npm-only 分发
+- npm-only CLI 升级
+- `bootstrap` 作为宿主接入与修复入口
+
+官方同时维护两个 npm 包名：
+
+- `rrskill`
+- `@rrskill/cli`
+
+两个包都暴露同一个终端命令：
+
+- `rrskill`
+
+## 2. 安装方式
+
+### 2.1 直接 npm 安装
+
+全局安装：
+
+```bash
+npm install -g rrskill
+rrskill bootstrap --host openclaw
+```
+
+或：
+
+```bash
+npm install -g @rrskill/cli
+rrskill bootstrap --host openclaw
+```
+
+一次性运行：
+
+```bash
+npx rrskill@latest version
+npx @rrskill/cli@latest version
+bunx rrskill@latest version
+bunx @rrskill/cli@latest version
+pnpm dlx rrskill@latest version
+pnpm dlx @rrskill/cli@latest version
+```
+
+### 2.2 官网在线安装脚本
+
+```bash
+curl -fsSL https://rrskill.ai/install/install.sh | bash
+```
+
+指定宿主：
+
+```bash
+curl -fsSL https://rrskill.ai/install/install.sh | bash -s -- --openclaw
+```
+
+说明：
+
+- `install.sh` 默认走完整初始化流程：检查环境、安装 CLI、执行 bootstrap
+- `openclaw` 支持完整初始化
+- `codex` / `claude-code` 可以通过 `--skip-bootstrap` 完成 CLI 安装，但当前不支持完整宿主修复
+- `install.sh` 现在支持 `--check`、`--dry-run`、`--skip-bootstrap`、`--output json|text`
+
+`install.sh` 的职责只有：
+
+1. 检测系统和 Node/npm
+2. 必要时安装受管 Node
+3. 用 npm 安装 `rrskill`
+4. 调用 `rrskill bootstrap --host <name>`
+
+示例：
+
+```bash
+curl -fsSL https://rrskill.ai/install/install.sh | bash -s -- --check --output json
+curl -fsSL https://rrskill.ai/install/install.sh | bash -s -- --dry-run
+curl -fsSL https://rrskill.ai/install/install.sh | bash -s -- --host codex --skip-bootstrap --output json
+```
+
+另外有一个实现约束：
+
+- `install.sh` 顶部常量需要和 `src/installer/constants.ts` 保持一致
+- 我们现在用“显式顶部配置 + 测试校验”来避免 shell / TS 漂移
+
+## 3. 命令说明
+
+当前已接通的核心命令：
+
+| 命令 | 作用 |
+| --- | --- |
+| `rrskill <slug>` | `install` 简写 |
+| `rrskill install <slug>` | 安装指定 marketplace skill |
+| `rrskill search <query>` | 搜索 registry 中的 skill |
+| `rrskill list` | 查看当前宿主已安装 skill |
+| `rrskill upgrade` | 升级当前宿主已安装的 marketplace skill |
+| `rrskill bootstrap --host <name>` | 安装内置 skill、安装宿主 plugin、修复宿主配置、执行校验 |
+| `rrskill doctor --host <name>` | 检查当前 host 的初始化状态，并返回修复建议或直接执行修复 |
+| `rrskill version` | 输出 CLI 版本信息与升级提示 |
+
+host 参数：
+
+```bash
+--host <openclaw|codex|claude-code>
+--openclaw
+--codex
+--claude-code
+```
+
+规则：
+
+- `--host` 是 canonical 参数
+- `--openclaw` / `--codex` / `--claude-code` 是 sugar alias
+- 未传 host 时默认 `openclaw`
+- 非法 host 会直接报错，不再静默回退
+
+示例：
+
+```bash
+rrskill web-search
+rrskill web-search --codex
+rrskill install web-search --host claude-code
+rrskill bootstrap --openclaw
+rrskill doctor --host openclaw
+rrskill doctor --host openclaw --fix
+rrskill search browser automation
+```
+
+输出相关：
+
+```bash
+rrskill search react --output json
+rrskill doctor --host openclaw --output json
+rrskill search react --json
+```
+
+## 4. 配置说明
+
+默认配置文件：
+
+```text
+~/.rrskill/config.json
+```
+
+也可以通过环境变量覆盖：
+
+```bash
+RRSKILL_CONFIG_PATH=/path/to/config.json
+RRSKILL_HOST=codex
+RRSKILL_SKILLS_SEARCH_URL=https://api.rrskill.ai/skills?page=1&size={limit}&search={query}
+```
+
+当前支持的配置字段：
+
+```json
+{
+  "host": "codex",
+  "state_dir": "/Users/demo/.rrskill",
+  "skills_search_url": "https://api.rrskill.ai/skills?page=1&size={limit}&search={query}&orderBy=downloadCount&order=desc"
+}
+```
+
+兼容 key：
+
+- `state_dir` / `stateDir`
+- `skills_search_url` / `skillsSearchUrl`
+
+## 5. 当前宿主支持情况
+
+| 能力 | openclaw | codex | claude-code |
+| --- | --- | --- | --- |
+| `search/install/list/upgrade` | 支持 | 支持 | 支持 |
+| 默认路径推导 | 支持 | 支持 | 支持 |
+| `doctor` 检查 | 支持 | 支持 | 支持 |
+| `doctor --fix` 实际修复 | 支持 | 暂未支持 | 暂未支持 |
+| `bootstrap` 完整成功 | 支持 | 暂未支持 | 暂未支持 |
+| `bootstrap` 内置 skill 落点 | 支持 | 支持 | 支持 |
+| `bootstrap` 宿主 plugin 安装 | 支持 | 暂未实现 | 暂未实现 |
+| `bootstrap` 宿主配置修复 | 支持 | 暂未实现 | 暂未实现 |
+| `install.sh` 完整初始化 | 支持 | 需配合 `--skip-bootstrap` | 需配合 `--skip-bootstrap` |
+
+也就是说：
+
+- `openclaw` 是当前唯一做完整 bootstrap repair 的宿主
+- `codex` / `claude-code` 已经有统一路径模型和 skill 落点
+- 这两个宿主当前推荐用 `doctor` 做检查，用 `search/install/list/upgrade` 完成 CLI 侧操作
+- 它们的 `bootstrap` 目前会明确返回未支持，而不是假成功
+- 后续只需要补它们自己的宿主 plugin/config integration
+
+## 6. 开发
+
+当前 `rrskill-cli/` 是仓库内独立包，不在根 `pnpm-workspace.yaml` 里。
+
+开发时建议直接在目录内执行：
+
+```bash
+cd rrskill-cli
+pnpm install --ignore-workspace
+pnpm run test
+pnpm run build
+pnpm run build:packages
+```
+
+## 7. 发布
+
+发布教程现在独立放在：
+
+- [PUBLISHING.md](./PUBLISHING.md)
+
+这里单独拎出去的原因是：
+
+- 使用者不需要看维护者发布细节
+- 发布链路比“安装/使用”更强调步骤顺序和校验
+- 现在 `build:packages` 对默认开发版 `0.0.0-dev` 有保护，发布前必须先改版本号
+
+## 8. 进一步阅读
+
+如果你现在关心的是：
+
+- 怎么安装和使用：看这份 `README.md`
+- 为什么架构这么设计、每个目录和文件是干什么的：看 [ARCHITECTURE.md](./ARCHITECTURE.md)
+- 怎么发版、具体每一步怎么验证：看 [PUBLISHING.md](./PUBLISHING.md)

package/bin/rrskill.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+/** 文件作用：正式的 rrskill 可执行入口，负责加载 dist/index.js 中的 CLI 构建产物。 */
+import("../dist/index.js").catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Failed to start rrskill CLI: ${message}\n`);
+  process.exit(1);
+});