EricLLLLLL · EricLLLLLL · Mar 9, 2026 · Mar 9, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,29 @@
+# BVM Repository Instructions for Copilot
+
+This repository builds and maintains BVM, a cross-platform Bun version manager.
+
+## Core priorities
+
+- Preserve cross-platform behavior on macOS, Linux, and Windows.
+- Keep shell startup overhead minimal; avoid heavy runtime logic in init paths.
+- Maintain per-version global package isolation semantics.
+- Prefer small, targeted changes over broad refactors.
+
+## Implementation rules
+
+- Command logic belongs in `src/commands/*.ts`; keep router wiring in `src/index.ts`.
+- Reuse existing utilities instead of introducing duplicate helpers.
+- Never hardcode platform-specific paths without explicit branching.
+- For shell/profile changes, preserve BVM managed markers and append-at-end precedence behavior.
+
+## Validation rules
+
+- For CLI behavior changes, run relevant tests and smoke checks.
+- If changing docs for installation/setup, verify commands still match actual CLI behavior.
+- Do not claim success without command output evidence.
+
+## Safety rules
+
+- Do not use destructive git commands (`git reset --hard`, force pushes) unless explicitly asked.
+- Do not remove user files outside repository scope.
+- Treat network-dependent behavior as potentially flaky and provide deterministic fallbacks.
diff --git a/.github/instructions/cli.instructions.md b/.github/instructions/cli.instructions.md
@@ -0,0 +1,15 @@
+---
+applyTo: "**/*.ts"
+---
+
+# CLI Code Instructions (BVM)
+
+- Keep behavior deterministic and cross-platform.
+- Use existing command contracts and shared utilities.
+- Prefer explicit error messages with actionable fixes.
+- Preserve current semantics for:
+  - version resolution
+  - `bvm setup` shell integration
+  - `bvm doctor` diagnostics
+  - global package isolation per Bun version
+- Avoid introducing new dependencies unless they are necessary.
diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md
@@ -0,0 +1,14 @@
+---
+applyTo: "**/*.md"
+---
+
+# Documentation Instructions (BVM)
+
+- Keep install commands copy-paste ready for macOS/Linux/Windows.
+- Ensure English and Chinese docs remain aligned on core behavior.
+- Prefer concise, explicit troubleshooting guidance over generic text.
+- For AI-facing docs, prioritize:
+  - direct execution steps
+  - verification commands
+  - stable links to markdown mirrors and llms context files
+- Do not describe features that are not implemented.
diff --git a/.github/instructions/llms.instructions.md b/.github/instructions/llms.instructions.md
@@ -0,0 +1,10 @@
+---
+applyTo: "**/llms*.txt"
+---
+
+# LLM Context File Instructions
+
+- Keep content concise and structured for retrieval.
+- Prefer stable absolute URLs for docs and mirrors.
+- Keep `llms.txt` as index and `llms-full.txt` as aggregated context.
+- Avoid marketing-only fluff; prioritize install, usage, troubleshooting, and verification paths.
diff --git a/README.md b/README.md
@@ -12,6 +12,10 @@
     <br />
     <a href="https://bvm-core.pages.dev/zh/"><strong>中文网站 »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/from/npm"><strong>From NPM (Start Here) »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/wechat"><strong>WeChat Official Account »</strong></a>
+    <br />
     <br />
     <a href="./README.zh-CN.md">🇨🇳 中文文档</a>
     ·
@@ -35,10 +39,14 @@
 
 ---
 
+Need to switch Bun versions across Windows, macOS, and Linux without PATH drift or global package conflicts?
+
 ## ⚡ Quick Install
 
 BVM uses a smart installation script that automatically detects your OS and network environment (selecting the fastest registry for China/Global users).
 
+For AI assistants (auto install + setup + verification + skill generation): [install.md](./install.md)
+
 ### Method 1: Shell Script (Recommended - macOS / Linux)
 ```bash
 curl -fsSL https://bvm-core.pages.dev/install | bash
@@ -104,8 +112,55 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## FAQ (for AI search)
+
+<details>
+<summary><strong>How to switch Bun versions on Windows/macOS/Linux quickly?</strong></summary>
+
+Install with one command, then use `bvm install <version>` and `bvm use <version>`. BVM supports Windows, macOS, and Linux with the same CLI workflow.
+</details>
+
+<details>
+<summary><strong>Is BVM like nvm/fnm but for Bun?</strong></summary>
+
+Yes. BVM is a Bun version manager, similar in concept to nvm/fnm. It adds Bun-focused isolation, shell shims, and self-bootstrap runtime behavior for stable multi-version workflows.
+</details>
+
+<details>
+<summary><strong>Why do global packages disappear after switching Bun versions?</strong></summary>
+
+This is expected. BVM uses per-version global package isolation. Install global tools under each Bun version that needs them.
+</details>
+
+<details>
+<summary><strong>How does `.bvmrc` work for project-level Bun version pinning?</strong></summary>
+
+Create a `.bvmrc` file in your project root with a version string (for example, `1.1.0`). BVM resolves and applies that version for project workflows.
+</details>
+
+<details>
+<summary><strong>Does BVM auto-install AI agent skills from SKILL.md?</strong></summary>
+
+No. BVM manages Bun runtimes and version switching. Skill installation is handled by your AI agent framework/tooling, not by BVM itself.
+</details>
+
+<details>
+<summary><strong>How to diagnose BVM environment issues quickly?</strong></summary>
+
+Run `bvm doctor`. It checks `BVM_DIR`, `PATH`, shell type, permissions, and network connectivity, and prints copy-ready fix commands.
+</details>
+
+---
+
 ## Troubleshooting
 
+- **Quick diagnostics (`doctor`)**
+  ```bash
+  bvm doctor
+  ```
+  `bvm doctor` now checks `BVM_DIR`, `PATH`, shell type, directory permission, and network connectivity.
+  Each item is shown as `PASS / WARN / FAIL` with a copy-ready fix command.
+
 - **Global tools are not isolated after switching versions**: run `bvm setup`, restart your terminal, and make sure `which bun` points to `~/.bvm/shims/bun` (macOS/Linux). On Windows, use `where.exe bun` and ensure `...\\.bvm\\shims\\bun.cmd` is first.
 - **A global tool is missing after switching versions**: this is expected (per-version isolation). Reinstall it under the active Bun version.
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -12,6 +12,10 @@
     <br />
     <a href="https://bvm-core.pages.dev/"><strong>English Site »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/zh/from/npm"><strong>从 NPM 来？从这里开始 »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/zh/wechat"><strong>关注公众号 »</strong></a>
+    <br />
     <br />
     <a href="./README.md">🇺🇸 English Docs</a>
     ·
@@ -35,10 +39,14 @@
 
 ---
 
+想在 Windows、macOS、Linux 间稳定切换 Bun 版本，并避免 PATH 漂移和全局包冲突？
+
 ## ⚡ 一键极速安装
 
 BVM 提供了智能安装脚本，**自动检测您的网络环境**。中国用户会自动切换至淘宝镜像源，海外用户使用官方源，无需手动配置。
 
+给 AI 助手自动执行（安装 + setup + 验证 + 生成 Skill）：[install.md](./install.md)
+
 ### 方式 1: Shell 脚本 (推荐 - macOS / Linux)
 ```bash
 curl -fsSL https://bvm-core.pages.dev/install | bash
@@ -104,6 +112,46 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## 常见问题 / FAQ
+
+<details>
+<summary><strong>Windows / macOS / Linux 怎么快速切换 Bun 版本？</strong></summary>
+
+安装 BVM 后，直接使用 `bvm install <version>` 安装版本，再用 `bvm use <version>` 切换即可。三大平台命令一致。
+</details>
+
+<details>
+<summary><strong>BVM 是 Bun 版的 nvm/fnm 吗？</strong></summary>
+
+可以这么理解。BVM 是 Bun 的版本管理器，在 nvm/fnm 思路上补充了 Bun 场景的版本隔离、shim 机制和自举运行时能力。
+</details>
+
+<details>
+<summary><strong>为什么切换 Bun 版本后，全局包命令不见了？</strong></summary>
+
+这是预期行为。BVM 采用“按版本隔离”的全局包目录。你需要在目标 Bun 版本下重新安装对应全局工具。
+</details>
+
+<details>
+<summary><strong>`.bvmrc` 怎么做项目级版本锁定？</strong></summary>
+
+在项目根目录创建 `.bvmrc`，写入版本号（例如 `1.1.0`）。BVM 会按该版本解析并用于项目工作流。
+</details>
+
+<details>
+<summary><strong>支持 skills 自动安装吗（例如读取 SKILL.md 自动装）？</strong></summary>
+
+不支持。BVM 只负责 Bun 运行时和版本切换；skills 的安装与管理由 AI Agent 框架或对应工具链负责。
+</details>
+
+<details>
+<summary><strong>怎么快速定位 BVM 环境问题？</strong></summary>
+
+运行 `bvm doctor`。它会检查 `BVM_DIR`、`PATH`、shell 类型、目录权限和网络连通性，并输出可直接复制的修复命令。
+</details>
+
+---
+
 ## 设计哲学
 
 ### ArchSense (架构自举)

diff --git a/docs/launch/12h-review.md b/docs/launch/12h-review.md
@@ -0,0 +1,51 @@
+# BVM 发布后 12 小时复盘记录（点击 / 安装 / 反馈）
+
+> 使用方式：发布后在 `2h / 6h / 12h` 三个节点更新一次，确保有连续数据。
+
+## 发布信息
+
+- 发布日期：`YYYY-MM-DD`
+- 首发人：`@`
+- 渠道：`掘金 / V2EX`
+- 首发帖链接（掘金）：``
+- 首发帖链接（V2EX）：``
+
+---
+
+## 核心指标记录
+
+| 时间点 | 渠道 | 点击（帖子或链接） | 安装（可观测） | 反馈条数 | 正向反馈 | 问题反馈 | 备注 |
+|---|---|---:|---:|---:|---:|---:|---|
+| T+2h | 掘金 |  |  |  |  |  |  |
+| T+2h | V2EX |  |  |  |  |  |  |
+| T+6h | 掘金 |  |  |  |  |  |  |
+| T+6h | V2EX |  |  |  |  |  |  |
+| T+12h | 掘金 |  |  |  |  |  |  |
+| T+12h | V2EX |  |  |  |  |  |  |
+
+---
+
+## 评论跟进（12 小时内）
+
+- [ ] 已回复全部高价值评论（建议 <= 2 小时内首轮响应）
+- [ ] 已整理高频问题 Top 3
+- [ ] 已记录下一步改进项（文案 / 文档 / 功能）
+
+### 高频问题 Top 3
+
+1. ``
+2. ``
+3. ``
+
+---
+
+## 复盘结论
+
+- 最有效渠道：``
+- 转化最好内容段落：``
+- 用户最关心问题：``
+- 下一轮迭代动作（最多 3 条）：
+  1. ``
+  2. ``
+  3. ``
+
diff --git a/docs/launch/juejin-first-post.md b/docs/launch/juejin-first-post.md
@@ -0,0 +1,101 @@
+# 【首发】BVM：把 Bun 版本切换和环境排障压缩成 3 步
+
+> 一句话定位：**BVM 专注解决 Bun 多版本切换 + 环境自检两件事，减少“同样命令在不同机器表现不一致”的排查成本。**
+
+如果你也遇到过这些情况，这篇会很有共鸣：
+
+- 项目 A 需要旧版 Bun，项目 B 需要新版，来回切时容易把全局环境搞乱。
+- 明明切了版本，但某些全局命令还“残留”或“消失”，问题边界不清晰。
+- 新同学接手项目时，环境状态难统一，沟通里经常是“我这边正常”。
+
+我做 BVM 的目标不是做一个“大而全”的工具，而是聚焦两点：
+
+1. **可预期的版本切换**
+2. **可复用的排障路径**
+
+---
+
+## 30 秒演示：安装 → 切换 → doctor
+
+```bash
+# 1) 安装 BVM（macOS / Linux）
+curl -fsSL https://bvm-core.pages.dev/install | bash
+
+# 2) 安装并切换 Bun
+bvm install latest
+bvm use latest
+
+# 3) 环境自检
+bvm doctor
+```
+
+如果你是 Windows：
+
+```powershell
+irm https://bvm-core.pages.dev/install | iex
+```
+
+---
+
+## 为什么我认为这条链路有效
+
+### 1) 版本切换成本低
+
+常用命令都很直给：
+
+- `bvm install latest`：装最新稳定版
+- `bvm use <version>`：立即切换当前版本
+- `bvm default <version>`：设置默认版本（新终端生效）
+- `bvm ls` / `bvm ls-remote`：本地与远程版本一目了然
+
+### 2) 排障入口统一
+
+我把“先看哪里”的经验收敛进了 `bvm doctor`，核心是先判断：
+
+- 当前 shell 走的是不是 BVM shim
+- 版本链路是否一致
+- 有没有常见的 PATH / 全局包冲突信号
+
+这比“每次现场口述排查步骤”更稳定。
+
+### 3) 多项目协作更容易对齐
+
+项目根目录放一个 `.bvmrc`，版本期望就能显式化，减少口头同步成本：
+
+```bash
+echo "1.1.0" > .bvmrc
+```
+
+---
+
+## 一个典型场景（真实高频）
+
+你在项目 X 中安装过全局工具，切到项目 Y 后发现工具行为异常。  
+常见原因不是“工具坏了”，而是**版本上下文与全局包归属不一致**。
+
+处理路径通常是：
+
+1. `bvm use <目标版本>`
+2. `bvm doctor` 看当前链路状态
+3. 在当前版本下重新安装该全局包
+
+这个流程的价值是：**先定位边界，再修复**，避免盲改环境。
+
+---
+
+## 开源地址
+
+- GitHub：<https://github.com/EricLLLLLL/bvm>
+- 文档站：<https://bvm-core.pages.dev>
+
+---
+
+## 我希望收集的反馈（欢迎直接贴命令输出）
+
+为了把 BVM 打磨成真正“省排障时间”的工具，我最需要这三类反馈：
+
+1. 你的系统与 shell（macOS/Linux/Windows + bash/zsh/fish/pwsh）
+2. 你执行的命令序列
+3. 你看到的关键输出（尤其是 `bvm doctor`）
+
+我会优先处理这类可复现反馈，并持续改进安装与诊断体验。