feat: add npx Skill installation

.github/workflows/build.yml

@@ -7,7 +7,41 @@ on:
       - "v*"
 
 jobs:
+  verify:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Verify Python
+        run: |
+          uv sync --dev
+          uv run pytest -q
+          uv run python -m compileall -q scripts
+
+      - name: Verify Node launcher
+        run: node --test tests/test_getbijiex_launcher.mjs
+
+      - name: Verify npx Skill installation
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          npx -y skills@1.5.20 add . --list | tee /tmp/getbijiex-skills.txt
+          grep -q "getbijiex" /tmp/getbijiex-skills.txt
+
   build:
+    needs: verify
     strategy:
       fail-fast: false
       matrix:

.gitignore

@@ -25,5 +25,15 @@ tmp/
 # Local scripts artifacts
 .DrissionPage/
 
+# Node/npm artifacts
+node_modules/
+.npm/
+npm-debug.log*
+*.tgz
+coverage/
+
+# Claude Code local worktrees
+.claude/
+
 # macOS
 .DS_Store

GetbijiEx.spec

@@ -14,7 +14,7 @@ a = Analysis(
     binaries=[],
     datas=[
         (str(ROOT / 'scripts'), './scripts'),
-        (str(ROOT / 'skill'), './skill'),
+        (str(ROOT / 'skills'), './skills'),
     ],
     hiddenimports=[
         'scripts.app_paths',

README.md

@@ -4,6 +4,30 @@
 
 **不会终端、不会 Python、只会用 Agent，也可以安装。直接看下面第一部分。**
 
+## 已经装好软件？一条 npx 命令安装 Skill
+
+如果电脑里已经保留了 GetbijiEx App、Windows 程序或源码，可以把下面一整行复制给支持 Agent Skills 的 Agent 执行：
+
+```bash
+npx skills add Likely7/GetbijiEx --skill getbijiex
+```
+
+指定安装到 Claude Code：
+
+```bash
+npx skills add Likely7/GetbijiEx --skill getbijiex --agent claude-code -g -y
+```
+
+指定安装到 Codex：
+
+```bash
+npx skills add Likely7/GetbijiEx --skill getbijiex --agent codex -g -y
+```
+
+> **这条 npx 命令只安装 Skill，不会安装 GetbijiEx 软件本身。** 它使用的是公开的 `skills` 安装工具，不是本项目发布了一个同名 npm 软件包。执行这条命令需要 Node.js 22.20+。第一次导出时，Skill 会自动查找标准位置和 PATH 中已有的 GetbijiEx；如果没有找到，Agent 会在本机查找并代你配置真实路径。使用源码版时还需要 Python 3.11+ 和 `uv`。
+
+如果你的 Agent 不支持标准 Agent Skills 目录，继续使用下面的完整提示词，让它自己确认 Skill 目录并安装。
+
 ---
 
 ## 最简单的用法：把这段话复制给你的 Agent
@@ -56,7 +80,17 @@
 
 ## 已经装好 GetbijiEx，只想单独安装 Skill
 
-有。Skill 的安装命令就是 `install-skill`。
+### 支持 Agent Skills 的 Agent：直接复制 npx 命令
+
+```bash
+npx skills add Likely7/GetbijiEx --skill getbijiex
+```
+
+不带 `-g` 时默认安装到当前项目；希望这个 Agent 在所有项目中都能使用时，加上 `-g`。如果 Agent 要求明确指定目标，可以加上 `--agent claude-code`、`--agent codex` 或它实际支持的 Agent 名称。安装工具会把整个 `getbijiex` Skill 和跨平台启动器一起安装。
+
+### 不支持标准安装方式：让 Agent 调用 GetbijiEx 自带安装器
+
+GetbijiEx 自带的 Skill 安装子命令是 `install-skill`。
 
 > **注意：Skill 不是导出软件本身。** Skill 只是告诉 Agent 怎么调用 GetbijiEx。电脑里必须同时保留 GetbijiEx 软件或源码，删掉以后 Skill 就无法导出。
 
@@ -277,12 +311,16 @@ CLI 的 stdout 只输出 JSON，过程日志写入 stderr，供 Agent 稳定解
 
 PyInstaller 不能从 macOS 直接交叉构建 Windows 应用。仓库中的 GitHub Actions 会在对应系统分别构建。
 
-## 自动化测试
+## 自动化验证
 
 ```bash
 uv run pytest -q
+node --test tests/test_getbijiex_launcher.mjs
+npx -y skills@1.5.20 add . --list
 ```
 
+最后一条命令用于确认标准 Skill 安装工具能从本仓库发现 `getbijiex`。
+
 </details>
 
 ---

docs/DECISIONS.md

@@ -1,6 +1,6 @@
 # 技术决策记录
 
-> 最后更新：2026-07-25
+> 最后更新：2026-07-26
 
 本文记录已经确定并影响后续维护的关键决策。若要改变某项决策，应新增一条替代记录，不直接删除历史原因。
 
@@ -41,10 +41,10 @@
 
 ## ADR-006：Skill 随应用打包并支持多 Agent 安装
 
-**状态：** 已采用  
-**背景：** 单独维护 Skill 仓库会增加版本漂移，小白用户也难以手动配置调用路径。  
-**决策：** `skill/SKILL.md` 作为模板随应用打包，安装时把占位符替换为真实 CLI 路径；预设 Claude Code、Codex，并允许 `--dir` 指定其他 Agent 目录。  
-**结果：** Skill 与应用版本同步，GUI 和 CLI 都能完成安装。
+**状态：** 已采用
+**背景：** 单独维护 Skill 仓库会增加版本漂移，小白用户也难以手动配置调用路径。
+**决策：** `skills/getbijiex/` 作为唯一 Skill 来源并随应用打包；GetbijiEx 自带安装器会复制完整目录，并把默认 npx 启动区块替换为真实 CLI 路径；预设 Claude Code、Codex，并允许 `--dir` 指定其他 Agent 目录。
+**结果：** Skill 与应用版本同步，GUI、GetbijiEx CLI 和标准 Agent Skills 安装工具都能完成安装。
 
 ## ADR-007：应用数据使用操作系统标准目录
 
@@ -66,3 +66,10 @@
 **背景：** `config/biji_auth.json` 曾进入本地 Git 历史，公开推送会泄露认证信息。  
 **决策：** 文件加入 `.gitignore`，并在首次公开推送前清理全部待推送历史。  
 **结果：** 当前公开仓库与构建产物不包含认证文件；后续发布检查必须继续验证。
+
+## ADR-010：使用标准 Agent Skills CLI 分发独立 Skill
+
+**状态：** 已采用
+**背景：** 用户需要一条可以直接复制的 npx 命令，但项目尚无正式 GitHub Release；此时发布自有 npm 软件安装器会引入二进制下载、校验、平台版本和 npm 发布权限等额外依赖。
+**决策：** 仓库使用标准 `skills/getbijiex/` 结构，通过 `npx skills add Likely7/GetbijiEx --skill getbijiex` 从 GitHub 分发 Skill。原样安装的 Skill 携带 Node 启动器，用于定位标准安装位置、PATH、环境变量或用户明确配置的 GetbijiEx；为避免执行当前项目中的不可信脚本，不自动信任工作目录里的同名源码。本阶段不发布 `npx getbijiex` 软件安装器。
+**结果：** Skill 可以在没有自有 npm 包和正式 Release 的情况下单独安装，同时保留“Skill 不等于软件本体”的边界。正式 Release 完成后，再独立评估通过 npm 下载和校验应用程序。

docs/PROJECT_STATUS.md

@@ -23,25 +23,26 @@ GetbijiEx 用于把 biji.com（Get笔记/得到大脑）知识库中订阅博主
 | 导出进度 | 已完成 | GUI 显示当前条目和总体进度，完成后打开输出目录 |
 | 跨平台数据目录 | 已完成 | macOS、Windows、Linux 分别使用各自标准应用数据目录 |
 | 双模式应用 | 已完成 | 无参数启动 GUI，带参数进入 JSON CLI |
-| Agent Skill | 已完成 | 支持 Claude Code、Codex 和自定义 Skill 根目录 |
-| 小白安装说明 | 已完成 | README 提供可直接复制给 Agent 的完整安装提示词、单独安装 Skill 提示词和各平台命令 |
+| Agent Skill | 已完成 | 支持标准 `npx skills add`、Claude Code、Codex 和自定义 Skill 根目录 |
+| 小白安装说明 | 已完成 | README 提供 npx 单行命令、可直接复制给 Agent 的完整安装提示词和各平台命令 |
 | macOS 打包 | 已完成 | 本机与 GitHub Actions 均已验证 |
 | Windows 打包 | 已完成 | GitHub Actions 已验证可生成 Windows 产物 |
-| 自动化测试 | 已完成 | 覆盖 Token 提取、列表分页、CLI、Skill 安装和数据迁移 |
+| 自动化测试 | 已完成 | 覆盖 Token 提取、列表分页、CLI、Skill 安装、npx 启动器和数据迁移 |
 | 正式 Release | 待完成 | 需要确定版本号、生成发布说明并上传版本产物 |
 
 ## 最近验证基线
 
-最近一次完整发布基线为提交 `9d466ca`：
+2026-07-26 对 npx Skill 安装改造完成了本地发布前验证：
 
-- `pytest`：20 个测试通过。
-- macOS PyInstaller 构建成功。
-- Windows GitHub Actions 构建成功。
-- macOS GUI 已实际启动并检查关键控件。
-- Claude Code、Codex、自定义目录三种 Skill 安装方式均验证通过。
-- Git 历史和打包产物中不包含 `config/biji_auth.json`。
+- `pytest`：28 个测试通过。
+- Node 启动器：15 个测试通过，其中包含不信任工作目录源码、缺失 `uv`、CLI 依赖导入失败提示和参数/退出码转发测试。
+- 标准 `skills` CLI 可以发现并在隔离 HOME 中安装 `getbijiex`。
+- 源码版和打包版 `install-skill` 均能复制完整 Skill 资源并生成直连命令。
+- macOS Apple Silicon PyInstaller 构建成功，打包版 CLI 和 Skill 安装命令通过烟雾测试。
+- Git diff 格式检查和敏感信息扫描通过。
+- Linux 与 Windows 的 Node 启动器测试已纳入 GitHub Actions；推送后仍需确认远端工作流结果。
 
-本文件之后的改动必须按 [发布检查清单](RELEASE_CHECKLIST.md) 重新验证，不能沿用旧结果代替新验证。
+历史完整发布基线为提交 `9d466ca`；本文件之后的改动仍须按 [发布检查清单](RELEASE_CHECKLIST.md) 重新验证，不能沿用旧结果代替新验证。
 
 ## 当前工作重点
 
@@ -57,6 +58,7 @@ GetbijiEx 用于把 biji.com（Get笔记/得到大脑）知识库中订阅博主
 - macOS 应用未做 Apple Developer ID 签名和公证，首次打开可能需要用户在系统安全设置中确认。
 - macOS 构建产物与构建机器架构一致；当前本地验证产物为 Apple Silicon。
 - GitHub Actions 可以构建 Windows 产物，但真实 Windows GUI 与 Chrome 联动仍需要人工验收。
+- npx 命令只安装 Skill，不包含 GetbijiEx 软件本身；使用 npx 安装的 Skill 需要 Node.js 22.20+，本机必须已有 App、Windows 程序或源码；源码模式还需要 Python 3.11+ 和 `uv`。
 - Biji 是外部服务，其接口结构和鉴权规则变化可能导致功能失效。
 
 ## 项目文档

docs/RELEASE_CHECKLIST.md

@@ -16,11 +16,15 @@
 uv sync --dev
 uv run pytest -q
 uv run python -m compileall -q scripts
+node --test tests/test_getbijiex_launcher.mjs
+npx -y skills@1.5.20 add . --list
 git diff --check
 ```
 
 - [ ] 全部测试通过，失败数为 0。
 - [ ] Python 模块编译检查通过。
+- [ ] Node 跨平台启动器测试在 Linux 和 Windows CI 上通过。
+- [ ] 标准 `skills` CLI 能发现 `getbijiex`。
 - [ ] Git diff 格式检查通过。
 
 ## 3. 敏感信息检查
@@ -49,7 +53,11 @@ git diff --check
 - [ ] Claude Code 安装路径正确。
 - [ ] Codex 安装路径正确。
 - [ ] `--dir` 自定义目录安装正确。
-- [ ] 安装后的 `SKILL.md` 不再包含 `{{CLI_COMMAND}}` 占位符。
+- [ ] GetbijiEx 自带安装器会复制完整 Skill 资源，并把默认启动区块替换为本机直连命令。
+- [ ] `npx skills add Likely7/GetbijiEx --skill getbijiex` 能安装 `SKILL.md` 和跨平台启动器。
+- [ ] npx 安装后的启动器能自动定位、显式配置并调用现有 GetbijiEx，参数和退出码不会丢失。
+- [ ] 启动器不会自动执行当前工作目录或父目录中的同名 `scripts/biji_cli.py`。
+- [ ] Skill 中不存在未处理的 `{{CLI_COMMAND}}` 占位符。
 
 ## 6. 平台构建
 

docs/ROADMAP.md

@@ -20,6 +20,7 @@
 - [x] 完成 GetbijiEx 品牌改名与旧数据目录迁移。
 - [x] 建立 macOS、Windows 自动构建流程。
 - [x] README 提供可直接复制给 Agent 的安装和单独安装 Skill 提示词。
+- [x] 支持 `npx skills add` 从 GitHub 单独安装 Skill，并提供跨平台本机启动器。
 
 ## 阶段二：首个公开版本（当前阶段）
 
@@ -35,7 +36,7 @@
 
 - [x] 给 Windows 用户补充 SmartScreen 和首次运行说明。
 - [x] 给 macOS 用户补充未签名应用的首次打开说明。
-- [ ] 在 CI 中增加自动测试步骤，构建前先运行 `pytest`。
+- [x] 在 CI 中增加 Python、Linux/Windows Node 启动器和标准 Skill 发现测试，验证通过后再构建。
 - [ ] 增加失败导出的可恢复机制或失败条目清单。
 - [ ] 改善窄窗口、小屏幕和系统字体放大时的 GUI 布局。
 

scripts/skill_installer.py

@@ -1,18 +1,16 @@
-"""
-把 GetbijiEx 的 Skill 安装到 Claude Code、Codex 或自定义 Agent 目录。
-
-模板在仓库 skill/SKILL.md，其中的 {{CLI_COMMAND}} 会被替换为
-当前环境的真实调用方式：
-- 打包版：app 可执行文件的绝对路径
-- 源码版：uv run python scripts/biji_cli.py
-"""
+"""把 GetbijiEx Skill 安装到 Claude Code、Codex 或自定义 Agent 目录。"""
+
+import os
 import shlex
+import shutil
 import sys
 from pathlib import Path
 
 from scripts.app_paths import is_frozen, project_root, resources_root
 
 SKILL_NAME = "getbijiex"
+COMMAND_START = "<!-- GETBIJIEX_CLI_COMMAND_START -->"
+COMMAND_END = "<!-- GETBIJIEX_CLI_COMMAND_END -->"
 
 # 各 Agent 的 Skill 安装根目录（相对 home）
 AGENT_SKILL_DIRS = {
@@ -25,11 +23,26 @@ class UnsupportedAgentError(ValueError):
     pass
 
 
-def cli_command() -> str:
+class SkillTemplateError(ValueError):
+    pass
+
+
+def _powershell_quote(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def cli_command(platform: str | None = None) -> str:
+    platform = platform or sys.platform
     if is_frozen():
-        return shlex.quote(str(Path(sys.executable).resolve()))
-    root = project_root()
-    return f"cd {shlex.quote(str(root))} && uv run python scripts/biji_cli.py"
+        executable = str(Path(sys.executable).resolve())
+        if platform.startswith("win"):
+            return f"& {_powershell_quote(executable)}"
+        return shlex.quote(executable)
+
+    root = str(project_root().resolve())
+    if platform.startswith("win"):
+        return f"uv --directory {_powershell_quote(root)} run python scripts/biji_cli.py"
+    return f"uv --directory {shlex.quote(root)} run python scripts/biji_cli.py"
 
 
 def skill_target(agent: str = "claude", target_dir: str | None = None) -> Path:
@@ -46,10 +59,49 @@ def skill_target(agent: str = "claude", target_dir: str | None = None) -> Path:
     return base / SKILL_NAME / "SKILL.md"
 
 
+def _render_direct_command(
+    template: str,
+    command: str,
+    platform: str | None = None,
+) -> str:
+    if template.count(COMMAND_START) != 1 or template.count(COMMAND_END) != 1:
+        raise SkillTemplateError("Skill 模板必须包含且只包含一组 CLI 命令标记。")
+    platform = platform or sys.platform
+    shell_description = (
+        "PowerShell 中" if platform.startswith("win") else "Bash 兼容终端中"
+    )
+    code_fence = "powershell" if platform.startswith("win") else "bash"
+    start = template.index(COMMAND_START)
+    end = template.index(COMMAND_END, start) + len(COMMAND_END)
+    replacement = (
+        f"{COMMAND_START}\n"
+        "以下命令前缀由 GetbijiEx 安装器生成，后文统称为 `CLI`。"
+        f"请在 {shell_description}执行：\n\n"
+        f"```{code_fence}\n"
+        f"{command}\n"
+        "```\n"
+        f"{COMMAND_END}"
+    )
+    return template[:start] + replacement + template[end:]
+
+
 def install_skill(agent: str = "claude", target_dir: str | None = None) -> Path:
-    template_path = resources_root() / "skill" / "SKILL.md"
+    source = resources_root() / "skills" / SKILL_NAME
+    template_path = source / "SKILL.md"
     template = template_path.read_text(encoding="utf-8")
+    rendered = _render_direct_command(template, cli_command(), sys.platform)
+
     target = skill_target(agent, target_dir)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(template.replace("{{CLI_COMMAND}}", cli_command()), encoding="utf-8")
+    destination = target.parent
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    temporary = destination.with_name(f".{destination.name}.tmp-{os.getpid()}")
+    if temporary.exists():
+        shutil.rmtree(temporary)
+    shutil.copytree(source, temporary)
+    (temporary / "SKILL.md").write_text(rendered, encoding="utf-8")
+
+    if destination.exists():
+        shutil.rmtree(destination)
+    temporary.replace(destination)
     return target