@coreyuan/vector-mind 1.0.39 → 1.0.41

package/README.md

@@ -20,7 +20,48 @@ VectorMind 通过本地文件监听 + SQLite 关系记忆，把“需求 → 改
 - **上下文检索（semantic_search）**：默认使用本地 SQLite FTS 做召回（无需模型）；可选开启 embeddings，用向量相似度增强语义召回。
 - **会话恢复（brain dump）**：新会话开始时一键拉取最近需求与对应的改动意图，AI 直接接着做。
 - **紧凑输出 & token 计量**：`bootstrap_context/get_brain_dump/semantic_search/grep/list_project_files/read_file_*` 等高频工具默认返回 compact 文本，避免把大段 JSON/规则/文件包装字段塞进上下文；需要结构化数据时显式传 `format:"json"`。服务端会记录 raw-vs-compact 估算 token，可用 `get_token_savings` 查看节省。
-- **RTK 集成提示**：`detect_rtk` 可检测本机是否安装并用 `rtk gain` 验证 [rtk](https://github.com/rtk-ai/rtk)。若可用，AI 执行 shell 命令时应优先使用 `rtk git status`、`rtk npm run build`、`rtk rg ...` 等紧凑命令，进一步压缩命令输出。若未安装，可用 `install_rtk` 生成/执行安装计划（默认 dry-run，不静默改全局环境）。
+- **自带 RTK 入口**：安装本包后会同时提供 `vector-mind` 与 `rtk` 两个命令。`rtk` 是一个 VectorMind shim：优先代理本机已有 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)，没有时首次运行会自动下载官方 release 到用户缓存；下载失败才回退到 Cargo 安装。这样新电脑无需单独手动安装 RTK。
+- **RTK 集成提示**：`detect_rtk` 可检测 PATH 上的官方 RTK，也会回退检测本包内置的 `dist/rtk-shim.js`。若 `gain_ok=true`，AI 执行 shell 命令时应优先使用 `detect_rtk` 返回的 `command` 作为前缀（通常是 `rtk`，npx/MCP-only 场景可能是 `node .../rtk-shim.js`），进一步压缩命令输出。
+
+## 安装与 RTK 自动可用
+
+```bash
+npm install -g @coreyuan/vector-mind
+```
+
+安装后 npm 会暴露：
+
+```bash
+vector-mind   # MCP server
+rtk           # VectorMind 自带 RTK shim
+```
+
+如果用户不是全局安装，而是在 Codex MCP 配置里用 `npx -y @coreyuan/vector-mind` 启动服务，`rtk` 不一定会出现在 Codex 父进程 PATH；此时 `detect_rtk` 会自动回退到包内 `dist/rtk-shim.js`，并在返回结果里给出可直接用于命令前缀的 `command`。
+
+首次执行 `rtk ...` 或包内 shim 时：
+
+1. 如果 PATH 上已有官方 RTK，直接代理；
+2. 否则自动下载适配平台的 `rtk-ai/rtk` release 到 `~/.cache/vector-mind/rtk/`；
+3. 如果 release 下载/解压失败，再尝试 `cargo install --git https://github.com/rtk-ai/rtk --root <cache>`；
+4. 之后所有 `rtk ...` 都复用缓存的真实 RTK。
+
+如需禁用 shim 的自动安装：
+
+```bash
+VECTORMIND_RTK_NO_AUTO_INSTALL=1 rtk --version
+```
+
+如需指定已有 RTK 二进制：
+
+```bash
+VECTORMIND_RTK_REAL=/path/to/rtk rtk gain
+```
+
+让 Codex 全局读取 RTK 使用规则：
+
+```bash
+rtk init -g --codex
+```
 
 ## 工作流（强烈推荐）
 
@@ -31,7 +72,7 @@ VectorMind 通过本地文件监听 + SQLite 关系记忆，把“需求 → 改
 5) **需求完成时**：AI 调用 `complete_requirement()` 把需求标记为 `completed`（避免一直显示“处理中”）  
 5) **需要找代码定义时**：AI 调用 `query_codebase(query)`（不要靠猜）  
 6) **需要按语义找上下文/代码/文档时**：AI 调用 `semantic_search(query, ...)`（不要靠猜）
-7) **需要跑 shell 命令时**：先用 `detect_rtk()` 检查；如 `gain_ok=true`，优先给命令加 `rtk` 前缀以减少原始命令输出 tokens。若用户明确要求安装，再用 `install_rtk({ dry_run:true })` 展示计划，确认后才 `dry_run:false` 执行。
+7) **需要跑 shell 命令时**：先用 `detect_rtk()` 检查；如 `gain_ok=true`，优先使用返回的 `command` 作为命令前缀以减少原始命令输出 tokens。通常是 `rtk`，若只通过 npx 启动 MCP，则可能是 `node .../rtk-shim.js`。若用户明确要求安装，再用 `install_rtk({ dry_run:true })` 展示计划，确认后才 `dry_run:false` 执行。
 
 > 本 MCP Server 会在初始化时下发 `instructions`，提示 AI 按以上流程调用工具（避免盲猜）。
 > 这些 `instructions` 是**随包内置**的：只要用户安装并连接这个 MCP，就会自动拿到这层基础提示词；**不需要**他们再去写本地 config / policy 文件。
@@ -93,15 +134,15 @@ VectorMind 通过本地文件监听 + SQLite 关系记忆，把“需求 → 改
 
 ### `detect_rtk`
 - 入参：`{}`
-- 用途：检测本机 PATH 上是否有 `rtk`，并用 `rtk gain` 验证它是 rtk-ai/rtk 的 Rust Token Killer，而不是同名其他项目。
-- 说明：如果可用，shell 命令建议使用 `rtk` 前缀（例如 `rtk git status`、`rtk npm run build`、`rtk rg "foo" .`），让命令输出在进入 LLM 上下文前先被过滤压缩。
+- 用途：检测本机 PATH 上是否有 `rtk`；如果没有，再检测本包内置 `dist/rtk-shim.js`；并用 `gain` 验证它是 rtk-ai/rtk 的 Rust Token Killer，而不是同名其他项目。
+- 说明：如果可用，shell 命令建议使用返回的 `command` 作为前缀（通常是 `rtk git status`、`rtk npm run build`、`rtk rg "foo" .`；npx/MCP-only 场景可能是 `node .../rtk-shim.js git status`），让命令输出在进入 LLM 上下文前先被过滤压缩。
 
 ### `install_rtk`
-- 入参：`{ dry_run?: boolean, method?: "auto"|"cargo"|"brew"|"shell_script", init?: "none"|"global_no_patch"|"global_auto_patch"|"global_hook_only"|"local", uninstall_wrong_cargo_rtk?: boolean, timeout_ms?: number }`
+- 入参：`{ dry_run?: boolean, method?: "auto"|"cargo"|"brew"|"shell_script", init?: "none"|"global_no_patch"|"global_auto_patch"|"global_hook_only"|"local"|"codex_global"|"codex_local", uninstall_wrong_cargo_rtk?: boolean, timeout_ms?: number }`
 - 用途：在检测不到 rtk-ai/rtk 时安装 RTK。默认 `dry_run=true`，只返回计划命令，不执行安装。
 - 说明：
   - 默认 `method="auto"`：macOS 且有 Homebrew 时用 `brew install rtk`；否则优先 `cargo install --git https://github.com/rtk-ai/rtk`；Linux/macOS 可退到官方 shell installer；Windows 默认建议/使用 Cargo。
-  - 默认 `init="none"` 只安装二进制，不修改 Claude hook/settings。只有显式传 `global_*` 或 `local` 时才运行 `rtk init`。
+  - 默认 `init="none"` 只安装二进制，不修改 Claude/Codex 配置。显式传 `codex_global` 会执行 `rtk init -g --codex`；传 `codex_local` 会执行 `rtk init --codex`。
   - 如果已有 `rtk --version` 但 `rtk gain` 失败，可能是同名错误项目；只有确认安全后才传 `uninstall_wrong_cargo_rtk=true`。
 
 ### `get_token_savings`