From bac4fbb15c91ea82c6c2935e39e2b7720a49cddf Mon Sep 17 00:00:00 2001 From: ctrlcakepro <291766549+ctrlcakepro@users.noreply.github.com> Date: Mon, 21 Sep 2026 23:24:25 +0800 Subject: [PATCH] release 0.1.5: add AGENTS_INSTALL runbook; record npx 'not recognized' issue as unresolved The 0.1.4 npx failure on Windows no longer reproduces as of 2026-09-21 with no package or registry change, so the changelog no longer frames 0.1.5 as a re-publish experiment. --- .codex-plugin/plugin.json | 2 +- AGENTS_INSTALL.md | 150 ++++++++++++++++++++++++++++++++++++++ AGENTS_INSTALL.zh-CN.md | 150 ++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 6 ++ README.md | 26 ++++--- README.zh-CN.md | 26 ++++--- package-lock.json | 4 +- package.json | 2 +- 8 files changed, 338 insertions(+), 28 deletions(-) create mode 100644 AGENTS_INSTALL.md create mode 100644 AGENTS_INSTALL.zh-CN.md diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 41ec2c7..3cebccb 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "chilon-recall", - "version": "0.1.4", + "version": "0.1.5", "description": "Local-first knowledge retrieval for learning and serious knowledge work.", "author": { "name": "ctrlcakepro", diff --git a/AGENTS_INSTALL.md b/AGENTS_INSTALL.md new file mode 100644 index 0000000..4e02c84 --- /dev/null +++ b/AGENTS_INSTALL.md @@ -0,0 +1,150 @@ +# Agent install runbook — Chilon Recall + +This file is instructions for an AI coding agent (Claude Code, Codex CLI, Cursor, or similar), not end-user documentation. If you're a human, see [README.md](README.md) instead — or just copy the block below to your agent. + +## One-liner for humans + +Paste this to your agent, filling in your document folder path: + +> Read https://raw.githubusercontent.com/ctrlcakepro/chilon-recall/main/AGENTS_INSTALL.md and follow it to install and configure chilon-recall for me. My document folder is: ``. The MCP client I use is: ``. + +--- + +## Instructions for the agent + +You're installing [chilon-recall](https://github.com/ctrlcakepro/chilon-recall), a local MCP knowledge-retrieval server, for someone who may not be technical. Everything here is safe to automate **except step 4 (the API key)** — that one step you hand back to the human, and the reasons are explained inline rather than asserted. Don't shortcut it because it seems slower. + +Pinned version used in the commands below: `0.1.5`. That matches this repo's `package.json` as of when this file was written — check `CHANGELOG.md` or npm before assuming it's still current, and use the newer version if one has shipped since. + +### 0. Preconditions + +Run `node -v` and `python --version` (or `python3 --version`). You need Node.js ≥ 20 and Python ≥ 3.10. If either is missing, stop and tell the user to install it themselves — don't install a language runtime on their behalf without asking first. + +### 1. Collect two non-secret inputs + +Ask the user for whatever they didn't already give you: + +- the absolute path to the folder of documents they want indexed +- which MCP client they'll connect (Codex / Claude Desktop / Qoder / DeepSeek Harness) — needed in step 6 +- their embedding provider's API base URL (e.g. `https://api.siliconflow.cn/v1`) — this is an endpoint, not a secret + +### 2. Install + +```powershell +npx -y chilon-recall@0.1.5 install "" +``` + +This writes `\chilon-recall.json` and sets up a managed Python engine. No credentials are touched by this step. If it fails, show the user the actual error rather than retrying blindly — long/nested install paths, a missing Python 3.10+, and permission issues are the common causes, and there's no single fix to attempt automatically. + +### 3. Point the config at the real provider, and persist `RAG_MANAGER_CONFIG` (still no secrets) + +`install`'s own JSON output includes `"config": "\\chilon-recall.json"` — that's the path everything downstream needs. `RAG_MANAGER_CONFIG` has no default: `doctor`, `key`, and the MCP server all throw immediately if it isn't set (`resolveConfigPath()` in `src/config.mjs`). It isn't a secret, so unlike the API key, you set and persist it yourself, right now: + +```powershell +$env:RAG_MANAGER_CONFIG = "\chilon-recall.json" # this session, for the doctor/key calls below +setx RAG_MANAGER_CONFIG "\chilon-recall.json" # persists for new processes — you'll need this in step 5 and 6 +``` + +(bash/zsh: `export RAG_MANAGER_CONFIG=""` for the session, plus append the same line to `~/.bashrc`/`~/.zshrc` to persist it.) + +Then edit `\chilon-recall.json` and set `embedding.base_url` to the URL from step 1. Leave `embedding.model` on its placeholder for now — you'll fill in the real value after step 4 gives you a model name. + +### 4. Hand the API key step back to the human — do not automate this + +This is the one part of the flow to not do for the user, and not to ask them to paste into this chat either. Two concrete reasons, both grounded in this project's own code and changelog rather than generic caution: + +- `chilon-recall key`'s hidden-input prompt exists specifically so the key never has to pass through anything but the user's own terminal. This project's 0.1.4 changelog states the key "is used for a single request and is never written to disk" — that guarantee only holds if the key also stays out of *your* context and tool-call logs. +- If you built the command yourself and ran it through your own shell tool, the key would sit in your transcript in plaintext. That's a meaningfully different exposure than a single hidden terminal prompt designed for one human typing at one keyboard. + +So: tell the user to open a terminal window **they** control (not one you're driving) and run: + +```powershell +npx -y chilon-recall@0.1.5 key --base-url "" +``` + +Ask them to: + +1. Paste their key when prompted, as one line. (A clipboard that contains a newline gets truncated at the first one — if they copied a whole `KEY=...` block instead of just the value, warn them.) +2. Note the suggested embedding model name it prints — that part isn't secret, they can read it back to you. +3. Run **one** of the printed commands themselves: specifically the "persists for new windows/shells" variant (`setx` on Windows, or the `>> ~/.bashrc` / `>> ~/.zshrc` line on bash/zsh), not the "this window only" one. You need the persistent form because you'll check for it from a different process in step 5. +4. Come back, tell you the model name, and confirm they're done. + +Never ask them to paste the key itself. If they paste it anyway, don't write it anywhere or run anything with it — tell them the value is now exposed in this conversation, ask them to rotate it with their provider, and have them run the env-setting command directly instead. + +Once you have the model name, write it into `embedding.model` in `chilon-recall.json`. + +### 5. Verify credentials — from a fresh process + +A persistent env var only applies to processes started *after* it was set. Run `doctor` in a shell invocation that's new since step 4 (not one you already had open): + +```powershell +npx -y chilon-recall@0.1.5 doctor +``` + +It prints a JSON report and also exits `0`/`1` for `bootstrap_python.ready && engine.ready && configuration.ready && configuration.credentials_ready`. Read the JSON, not just the exit code: + +- `configuration.credentials_ready: true` → done, move to step 6. +- `configuration.error` mentioning `RAG_MANAGER_CONFIG is required` → it was never persisted, or this process started before step 3's `setx`/profile line took effect. Re-set it (session-scoped is enough to unblock this one check) and retry. +- `configuration.embedding_credential_available: false` → the API key variable didn't reach this process. Don't loop retrying silently — tell the user plainly that the shell/session you're running in probably needs to be restarted to pick up something set by `setx` or a profile file, and ask them to do that before you check again. +- `configuration.ready: false` with a placeholder-value error → `embedding.model` wasn't actually updated in step 4; fix it and retry. + +### 6. Configure the MCP client + +This part is fully automatable — the shapes below are exact. Reference environment variable *names* in every file you write, never values. + +**Qoder** — has a generator; use it instead of hand-editing anything: + +```powershell +npx -y chilon-recall@0.1.5 qoder "" +``` + +**Codex** (`~/.codex/config.toml`) — merge this block; don't overwrite other `[mcp_servers.*]` entries: + +```toml +[mcp_servers.chilon-recall] +command = "npx" +args = ["-y", "chilon-recall@0.1.5", "mcp"] +env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY"] +startup_timeout_sec = 15 +tool_timeout_sec = 1800 +default_tools_approval_mode = "writes" +``` + +`env_vars` forwards those names from whatever environment Codex itself inherits when it starts — it doesn't set values. That's why step 3 persists `RAG_MANAGER_CONFIG` and step 4 persists `RAG_API_KEY`: without that, Codex has nothing to forward. + +On Windows, if the client can't spawn `npx` (it's a `.cmd` shim some clients can't resolve when they spawn a process directly instead of through a shell), fall back to `npm install -g chilon-recall@0.1.5` and point `command` at `node` with the absolute installed script path, or at the global `chilon-recall` shim directly. + +**Claude Desktop** (`claude_desktop_config.json` — Windows: `%APPDATA%\Claude\claude_desktop_config.json`; macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) — merge into `mcpServers`, don't overwrite other entries: + +```json +"chilon-recall": { + "command": "npx", + "args": ["-y", "chilon-recall@0.1.5", "mcp"], + "env": { + "RAG_MANAGER_CONFIG": "\\chilon-recall.json" + } +} +``` + +Write `RAG_MANAGER_CONFIG` directly into this file — it's a path, not a secret, and doing so sidesteps whether Claude Desktop's process actually inherits whatever `setx` set (GUI apps often only pick that up after a full logoff, not just an app restart). `RAG_API_KEY` is different: leave it out of this file and rely on the environment Claude Desktop inherits. If the user tells you that isn't working, the documented fallback is adding it under this same `"env"` block — but that puts the raw key in a plaintext local file. Only do that on the user's explicit request, with a value they paste at that moment for that specific purpose, and remind them to restrict the file's permissions and never commit it. + +**DeepSeek Harness** — use the `dsh --patch` / `dsh plugin add` commands from [README.md](README.md#deepseek-harness); the same never-touch-the-raw-key rule applies. + +### 7. Restart and hand off + +You can't restart someone else's GUI app for them. Tell the user to restart or reload whichever client they configured, then suggest a smoke test — asking that client to call `rag_status`. + +### 8. Report back + +Tell the user what you did automatically, what they did by hand (the key), and say explicitly that you never saw the raw key value. + +--- + +## Hard rules + +These override convenience at every step above: + +- Never ask the user to paste their API key into this chat. +- Never construct or run a command that embeds the key value yourself. +- Never write a raw key into a file unless the user explicitly asks for that specific fallback, in that moment, for that reason. +- If a key ends up in this conversation anyway, say so plainly and suggest rotating it — don't quietly proceed as if nothing happened. diff --git a/AGENTS_INSTALL.zh-CN.md b/AGENTS_INSTALL.zh-CN.md new file mode 100644 index 0000000..0187cff --- /dev/null +++ b/AGENTS_INSTALL.zh-CN.md @@ -0,0 +1,150 @@ +# Agent 安装流程 — Chilon Recall + +这份文件是写给 AI coding agent（Claude Code、Codex CLI、Cursor 等）看的执行说明，不是人类用的说明书。如果你是人类，请看 [README.zh-CN.md](README.zh-CN.md)，或者直接把下面这段话复制给你的 agent。 + +## 给人类的一句话提示词 + +把路径填好后复制给你的 agent： + +> 请读取 https://raw.githubusercontent.com/ctrlcakepro/chilon-recall/main/AGENTS_INSTALL.zh-CN.md，照着帮我安装配置 chilon-recall。我的文档目录是：`<路径>`。我用的 MCP 客户端是：``。 + +--- + +## 给 agent 的执行说明 + +你正在为一个不一定懂技术的用户安装 [chilon-recall](https://github.com/ctrlcakepro/chilon-recall)，一个本地 MCP 知识检索 server。下面所有步骤都可以自动完成，**唯独第 4 步（API key）不行**——这一步要交还给人类自己做，原因写在那一节里，不是泛泛的谨慎，而是这个项目代码和更新日志里写明的具体理由。不要因为它看起来更慢就绕过去。 + +以下命令里固定使用的版本号：`0.1.5`。这是本文件编写时 `package.json` 里的版本；执行前先看一眼 `CHANGELOG.md` 或 npm，确认有没有更新的版本，如果有就用新的。 + +### 0. 前置检查 + +运行 `node -v` 和 `python --version`（或 `python3 --version`）。需要 Node.js ≥ 20、Python ≥ 3.10。缺哪个就停下来告诉用户自己装——不要没问过用户就擅自帮他们装语言运行时。 + +### 1. 收集两项不敏感的信息 + +问用户（如果对方第一条消息里已经给了就跳过）： + +- 想要建索引的文档文件夹的绝对路径 +- 打算连接哪个 MCP 客户端（Codex / Claude Desktop / Qoder / DeepSeek Harness）——第 6 步要用 +- 他们 embedding provider 的 API base URL（例如 `https://api.siliconflow.cn/v1`）——这是一个接口地址，不是密钥 + +### 2. 安装 + +```powershell +npx -y chilon-recall@0.1.5 install "<文档目录路径>" +``` + +会在 `<文档目录路径>\chilon-recall.json` 写入配置，并装好受管 Python engine。这一步完全不涉及凭据。如果这一步失败了，把真实报错展示给用户，不要盲目重试——路径太深太长、Python 版本不到 3.10、权限问题是常见原因，没有一个万能修复可以自动尝试。 + +### 3. 把配置指向真实 provider，并持久化 `RAG_MANAGER_CONFIG`（仍然不涉及密钥） + +`install` 自己打印的 JSON 结果里有 `"config": "<文档目录路径>\\chilon-recall.json"`——这是后面所有步骤都要用到的路径。`RAG_MANAGER_CONFIG` 没有默认值：`doctor`、`key`、MCP server 只要读不到它就会直接报错（见 `src/config.mjs` 里的 `resolveConfigPath()`）。它不是密钥，所以和 API key 不一样，这一步你自己就能设置并持久化： + +```powershell +$env:RAG_MANAGER_CONFIG = "<文档目录路径>\chilon-recall.json" # 当前会话，供下面 doctor/key 调用使用 +setx RAG_MANAGER_CONFIG "<文档目录路径>\chilon-recall.json" # 长期生效——第 5、6 步会用到 +``` + +（bash/zsh：当前会话用 `export RAG_MANAGER_CONFIG="<路径>"`，再把同一行追加进 `~/.bashrc` / `~/.zshrc` 做持久化。） + +然后编辑 `<文档目录路径>\chilon-recall.json`，把 `embedding.base_url` 改成第 1 步拿到的地址。`embedding.model` 先留着占位值不动——第 4 步会给你一个真实的模型名。 + +### 4. 把 API key 这一步交还给人类——不要自动化它 + +这是整个流程里唯一不该帮用户做、也不该让用户直接把 key 粘进这个对话里的一步。两个具体理由，都来自这个项目自己的代码和更新日志，不是套话： + +- `chilon-recall key` 的隐藏输入提示，设计目的就是让 key 除了用户自己的终端之外不经过任何中间层。这个项目 0.1.4 的更新日志写的是 key "is used for a single request and is never written to disk"——这个承诺只有在 key 也不进入*你*（agent）的上下文和工具调用日志时才成立。 +- 如果你自己拼出命令、通过你自己的 shell 工具去跑，key 就会以明文形式留在你的工具调用记录里。这和"专门为一个人在一个终端上输入"设计的隐藏输入提示，暴露程度完全不是一回事。 + +所以：告诉用户自己打开一个**他们自己控制的**终端窗口（不是你在操作的那个），运行： + +```powershell +npx -y chilon-recall@0.1.5 key --base-url "<第1步拿到的base-url>" +``` + +请他们： + +1. 按提示把 key 作为单行粘贴。（剪贴板里如果混进了换行，输入会在第一个换行处就被截断——如果他们复制的是整段 `KEY=...` 配置而不是纯 key 本身，提醒他们只复制 key 部分。） +2. 记下它打印出的推荐 embedding 模型名——这部分不是密钥，可以直接告诉你。 +3. 自己运行打印出来的其中**一条**命令：选"persists for new windows/shells"（长期生效）那一条——Windows 上是 `setx`，bash/zsh 上是追加到 `~/.bashrc` / `~/.zshrc` 的那一行——不要选"this window only"（仅当前窗口）的那条。要用长期生效的形式，因为第 5 步你要从另一个进程里检查它是否生效。 +4. 回来告诉你模型名，并确认已完成。 + +不要让他们把 key 本身粘给你。如果对方还是粘过来了，不要把它写进任何地方、也不要用它跑任何命令——直接告诉对方这个值现在已经暴露在这段对话记录里了，建议去 provider 那边把它作废重新生成，并请他们自己运行设置环境变量的命令。 + +拿到模型名之后，把它写进 `chilon-recall.json` 的 `embedding.model`。 + +### 5. 验证凭据——必须用一个全新的进程 + +长期生效的环境变量只对"设置之后才启动"的进程生效。用一个第 4 步之后才新开的 shell（不是你之前一直在用的那个）运行： + +```powershell +npx -y chilon-recall@0.1.5 doctor +``` + +它会打印一份 JSON 报告，退出码也是 `bootstrap_python.ready && engine.ready && configuration.ready && configuration.credentials_ready` 的结果（0/1）。要读 JSON 里的字段，不要只看退出码： + +- `configuration.credentials_ready: true` → 完成，进入第 6 步。 +- `configuration.error` 里提到 `RAG_MANAGER_CONFIG is required` → 说明它没被持久化，或者这个进程是在第 3 步的 `setx`/profile 生效之前就启动的。重新设置一次（当前会话级别就够用来通过这一项检查）再重试。 +- `configuration.embedding_credential_available: false` → API key 的变量没有传到这个进程里。不要默默重试，直接告诉用户：你现在这个 shell/会话大概率需要重启一下才能读到 `setx` 或 profile 文件里新写入的变量，请他们重启后再让你检查。 +- `configuration.ready: false` 且报的是占位值错误 → 说明第 4 步 `embedding.model` 其实没改成功，修好再试。 + +### 6. 配置 MCP 客户端 + +这一部分可以完全自动化——下面给的都是准确的格式。写进任何文件时都只引用环境变量的*名字*，不要写值。 + +**Qoder** —有专门的生成器，直接用它，不要手动改文件： + +```powershell +npx -y chilon-recall@0.1.5 qoder "<项目目录>" +``` + +**Codex**（`~/.codex/config.toml`）——合并进去，不要覆盖已有的其他 `[mcp_servers.*]` 条目： + +```toml +[mcp_servers.chilon-recall] +command = "npx" +args = ["-y", "chilon-recall@0.1.5", "mcp"] +env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY"] +startup_timeout_sec = 15 +tool_timeout_sec = 1800 +default_tools_approval_mode = "writes" +``` + +`env_vars` 只是把这些名字从 Codex 自己启动时继承到的环境变量里转发过去——它本身不设置值。这正是第 3 步要持久化 `RAG_MANAGER_CONFIG`、第 4 步要持久化 `RAG_API_KEY` 的原因：不这么做，Codex 就没有东西可转发。 + +如果在 Windows 上客户端起不来 `npx`（它是个 `.cmd` shim，有些客户端直接 spawn 进程、不经过 shell 时解析不了），退回用 `npm install -g chilon-recall@0.1.5` 全局安装，把 `command` 指向 `node` 加安装后脚本的绝对路径，或者直接指向全局的 `chilon-recall` shim。 + +**Claude Desktop**（`claude_desktop_config.json`——Windows: `%APPDATA%\Claude\claude_desktop_config.json`；macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`）——合并进 `mcpServers`，不要覆盖其他条目： + +```json +"chilon-recall": { + "command": "npx", + "args": ["-y", "chilon-recall@0.1.5", "mcp"], + "env": { + "RAG_MANAGER_CONFIG": "<文档目录路径>\\chilon-recall.json" + } +} +``` + +把 `RAG_MANAGER_CONFIG` 直接写进这个文件——它是路径，不是密钥，这样写还能绕开"Claude Desktop 的进程到底有没有继承到 `setx` 设置的值"这个不确定因素（GUI 程序往往要完整注销登录才能读到新值，光重启程序不够）。`RAG_API_KEY` 不一样：不要写进这个文件，靠 Claude Desktop 自己继承到的环境变量传递。如果用户告诉你这不生效，README 里给出的退路是在同一个 `"env"` 块里也加上它——但这会让 key 以明文形式存在本地文件里。只在用户明确要求、并且当场为这个用途粘贴一次 key 的情况下才这么做，并提醒他们限制文件权限、绝不要把它提交进版本库。 + +**DeepSeek Harness** —— 用 [README.zh-CN.md](README.zh-CN.md#deepseek-harness) 里的 `dsh --patch` / `dsh plugin add` 命令；"绝不经手真实 key"这条规则同样适用。 + +### 7. 重启并交接 + +别人的 GUI 客户端你没法替他们重启。请用户自己重启/重新加载配置好的那个客户端，然后建议做个冒烟测试——在客户端里调用一次 `rag_status`。 + +### 8. 向用户汇报 + +告诉用户你自动做了什么、他们手动做了什么（key 这一步），并明确说明你自始至终没有看到过真实的 key 值。 + +--- + +## 硬性规则 + +以下规则优先于上面任何一步里的"图省事"做法： + +- 不要让用户把 API key 粘进这个对话。 +- 不要自己拼出、或运行任何包含 key 值的命令。 +- 不要把明文 key 写进任何文件，除非用户当场明确要求走这条退路。 +- 如果 key 还是不小心暴露在了对话里，直接说清楚，建议去作废重新生成——不要装作什么都没发生地继续往下走。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 32b72ef..0c65f92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [0.1.5] - 2026-09-21 + +- Add `AGENTS_INSTALL.md` / `AGENTS_INSTALL.zh-CN.md`: a runbook an AI coding agent can follow to install and configure chilon-recall end to end. The API key step is deliberately left to the human — the agent is instructed to hand it back rather than pipe the key through its own shell or context. Both READMEs link to it from Quick start. +- Fix `AGENTS_INSTALL.md`/`.zh-CN.md` never telling the agent to set `RAG_MANAGER_CONFIG`, found by dry-running the runbook end to end: `doctor`, `key`, and the MCP server all require it with no default, so a literal first-time follow of the original text failed at the `doctor` check. The agent now persists it itself right after `install` (it isn't a secret), and the Claude Desktop snippet writes it straight into that client's `env` block instead of relying on environment inheritance. +- Known issue, unresolved: on 2026-09-18, `npx -y chilon-recall@0.1.4 ` — including `--help` and with no subcommand at all — failed on Windows with `'chilon-recall' is not recognized as an internal or external command`, while the identical package contents ran correctly via a direct `node scripts/cli.mjs` invocation or by calling the installed `.bin` shim directly. `npm cache verify` and a `--prefer-online` forced re-fetch ruled out a corrupted local cache; `package.json`'s `bin`/`scripts`/`engines`/`dependencies` and the resolved `node_modules/.bin` shims were byte-identical to the working 0.1.3 install. On 2026-09-21 the failure no longer reproduced on the same machine (Node 26.3, npm 11.16): `npx -y chilon-recall@0.1.4 --help`, `doctor`, and `@latest --version` all ran normally, with no change to the package or to the registry in between. The cause is still unknown, so the failure may recur. This release contains no fix for it, and whether 0.1.5 works via `npx` says nothing about the cause. If you hit it, run `node /scripts/cli.mjs` or `npm install -g chilon-recall` as a workaround, and please open an issue with the npm debug log and the contents of the matching `npm-cache/_npx//node_modules/.bin` directory before clearing the cache. + ## [0.1.4] - 2026-09-18 - Add `chilon-recall key`: a hidden-input prompt for a provider API key that calls the provider's own `/models` endpoint, suggests an embedding and reranker model, and prints ready-to-run `$env:`/`setx`/`export` commands. The key is used for a single request and is never written to disk. diff --git a/README.md b/README.md index 338ccdd..1aeb5d1 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ **Local-first knowledge retrieval for learning and serious knowledge work.** -[![version](https://img.shields.io/badge/version-0.1.4-blue.svg)](CHANGELOG.md) +[![version](https://img.shields.io/badge/version-0.1.5-blue.svg)](CHANGELOG.md) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org) [![python](https://img.shields.io/badge/python-%3E%3D3.10-brightgreen.svg)](https://www.python.org) @@ -40,12 +40,14 @@ It is an independent retrieval companion in the [Chilon Knowledge Work Harness]( > **New to MCP?** You only need a document folder, Node.js 20+, and Python 3.10+. Follow these three steps first; client configuration and technical details come later. +> **Using an AI coding agent instead (Claude Code, Codex CLI, Cursor, …)?** Paste this to it: *"Read https://raw.githubusercontent.com/ctrlcakepro/chilon-recall/main/AGENTS_INSTALL.md and follow it to install chilon-recall for me. My document folder is: ``."* It automates everything below except typing your own API key — see [AGENTS_INSTALL.md](AGENTS_INSTALL.md) for exactly what it will and won't do on its own. + ### 1. Install into your document folder Run the command below once. It creates a private configuration and a managed Python engine; it never stores API keys in the package or configuration file. ```powershell -npx -y chilon-recall@0.1.4 install C:\path\to\your\documents +npx -y chilon-recall@0.1.5 install C:\path\to\your\documents ``` ### 2. Set your provider key @@ -55,13 +57,13 @@ Open the generated `chilon-recall.json` and replace the placeholder `embedding.b ```powershell $env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json" $env:RAG_API_KEY = "your-provider-key" -npx -y chilon-recall@0.1.4 doctor +npx -y chilon-recall@0.1.5 doctor ``` `doctor` is an offline check: it catches the template placeholders and a missing key, but it never contacts your provider, so a real-looking `base_url` with a typo, or a wrong key, still passes. Then confirm them online with the key wizard: ```powershell -npx -y chilon-recall@0.1.4 key --base-url https://your-provider.example/v1 +npx -y chilon-recall@0.1.5 key --base-url https://your-provider.example/v1 ``` It prompts for the key once (hidden input), calls the provider's own `/models` endpoint — a mistyped URL fails here, and so does a key the provider rejects — suggests an embedding and reranker model, and prints ready-to-run `$env:`/`setx`/`export` commands with the key already filled in. chilon-recall uses the key for that one request only and never writes it to a file; the printed `setx` / `>> ~/.bashrc` commands do store it in plaintext if you run them. @@ -106,7 +108,7 @@ Requires Node.js 20+ and Python 3.10+. Use the published, pinned npm release to create a private configuration and install the isolated Python engine with one command: ```powershell -npx -y chilon-recall@0.1.4 install C:\path\to\your\documents +npx -y chilon-recall@0.1.5 install C:\path\to\your\documents ``` This writes `chilon-recall.json` in the document directory and creates a persistent managed Python engine in the operating system's user-data area. Both files are required for local operation; credentials remain outside both of them. @@ -120,7 +122,7 @@ To validate the runtime and private configuration: ```powershell $env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json" $env:RAG_API_KEY = "your-provider-key" -npx -y chilon-recall@0.1.4 doctor +npx -y chilon-recall@0.1.5 doctor ``` `doctor` exits `0` only when Python, the managed engine, the configuration, and its credentials are all ready — otherwise `1`, so it is safe to gate a script on. It also refuses to call the placeholder `embedding.base_url`/`model` from the install template "ready". @@ -186,12 +188,12 @@ tool_timeout_sec = 1800 default_tools_approval_mode = "writes" ``` -**npm release** — run `npx -y chilon-recall@0.1.4 setup` first under the same OS account. A pinned version prevents an unexpected package upgrade from changing a working MCP server. +**npm release** — run `npx -y chilon-recall@0.1.5 setup` first under the same OS account. A pinned version prevents an unexpected package upgrade from changing a working MCP server. ```toml [mcp_servers.chilon-recall] command = "npx" -args = ["-y", "chilon-recall@0.1.4", "mcp"] +args = ["-y", "chilon-recall@0.1.5", "mcp"] env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY"] startup_timeout_sec = 15 tool_timeout_sec = 1800 @@ -250,7 +252,7 @@ For an npm release, replace `command` and `args` with the following and omit `CH ```json "command": "npx", -"args": ["-y", "chilon-recall@0.1.4", "mcp"] +"args": ["-y", "chilon-recall@0.1.5", "mcp"] ``` Set `RAG_API_KEY` in the environment inherited by Claude Desktop, or add it only to your private local client configuration when your operating system cannot provide it. Claude Desktop stores `env` values in a local JSON file, so restrict file permissions and never commit that file. On Windows, use the virtual environment's `python.exe` path. @@ -260,12 +262,12 @@ Set `RAG_API_KEY` in the environment inherited by Claude Desktop, or add it only The Qoder client loads MCP servers from its own settings, and project-level skills and rules from the `.qoder/` directory. Generate all three from a checkout or an npm install: ```powershell -npx -y chilon-recall@0.1.4 qoder C:\path\to\your\project +npx -y chilon-recall@0.1.5 qoder C:\path\to\your\project ``` This writes `.qoder/mcp.json`, `.qoder/skills//SKILL.md` for every bundled skill, and `.qoder/rules/chilon-recall.md`. Add `--force` to regenerate over existing files. -> **Generating from `npx` embeds an unstable path.** `npx` unpacks the package into a temporary per-run cache (e.g. `...\npm-cache\_npx\\...` on Windows), and the `node`/`cli.mjs` path written into `.qoder/mcp.json` points there. Clearing the npm cache or bumping the pinned version moves that path and the MCP server stops starting, with no error beyond Qoder failing to load it. The command detects this and prints a warning; prefer running `chilon-recall qoder` from a stable install (`npm install -g chilon-recall@0.1.4`, or a source checkout) so the generated path survives cache clears. +> **Generating from `npx` embeds an unstable path.** `npx` unpacks the package into a temporary per-run cache (e.g. `...\npm-cache\_npx\\...` on Windows), and the `node`/`cli.mjs` path written into `.qoder/mcp.json` points there. Clearing the npm cache or bumping the pinned version moves that path and the MCP server stops starting, with no error beyond Qoder failing to load it. The command detects this and prints a warning; prefer running `chilon-recall qoder` from a stable install (`npm install -g chilon-recall@0.1.5`, or a source checkout) so the generated path survives cache clears. Qoder does not read `.qoder/mcp.json` automatically; it is a shareable snippet. Open **Qoder client Settings → MCP → My Servers → + Add**, paste its contents, and replace the `RAG_MANAGER_CONFIG` placeholder with your private configuration path: @@ -354,7 +356,7 @@ The publication check rejects likely secrets, personal email addresses, and user ## Limits -- Version 0.1.4 indexes UTF-8 `.md`, `.txt`, `.rst`, and `.csv` text. Convert PDFs to reviewed text first; scanned PDFs need OCR. +- Version 0.1.5 indexes UTF-8 `.md`, `.txt`, `.rst`, and `.csv` text. Convert PDFs to reviewed text first; scanned PDFs need OCR. - The included chunker recognizes Markdown `#` and `##` headings. It does not yet parse tables, citations, or document-native structure semantically. - `rag_build` is a deliberate full rebuild. Use `rag_sync` for content-hash incremental synchronization; it always writes a new staged FAISS index so row IDs remain aligned with metadata. - Local embedding and reranker models are not bundled in the first release. diff --git a/README.zh-CN.md b/README.zh-CN.md index c5504b1..61dc8ca 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -4,7 +4,7 @@ **面向学习与严肃知识工作的本地优先知识检索引擎。** -[![version](https://img.shields.io/badge/version-0.1.4-blue.svg)](CHANGELOG.md) +[![version](https://img.shields.io/badge/version-0.1.5-blue.svg)](CHANGELOG.md) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org) [![python](https://img.shields.io/badge/python-%3E%3D3.10-brightgreen.svg)](https://www.python.org) @@ -40,12 +40,14 @@ Chilon Recall 可将你自己的文本资料转换为私有、来源可追溯的 > **第一次接触 MCP？** 你只需要一个资料文件夹、Node.js 20+ 和 Python 3.10+。先完成下面三步；客户端配置和技术细节在后文。 +> **想用 AI coding agent（Claude Code、Codex CLI、Cursor 等）代劳？** 把这句话复制给它：*"请读取 https://raw.githubusercontent.com/ctrlcakepro/chilon-recall/main/AGENTS_INSTALL.zh-CN.md，照着帮我安装 chilon-recall。我的文档目录是：`<路径>`。"* 除了输入你自己的 API key 之外，其余步骤它都能替你完成——具体哪些能自动、哪些故意留给你，见 [AGENTS_INSTALL.zh-CN.md](AGENTS_INSTALL.zh-CN.md)。 + ### 1. 安装到资料文件夹 运行一次下面的命令。它会创建私有配置与受管 Python engine；不会把 API key 写入 package 或配置文件。 ```powershell -npx -y chilon-recall@0.1.4 install C:\path\to\your\documents +npx -y chilon-recall@0.1.5 install C:\path\to\your\documents ``` ### 2. 设置 provider key @@ -55,13 +57,13 @@ npx -y chilon-recall@0.1.4 install C:\path\to\your\documents ```powershell $env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json" $env:RAG_API_KEY = "your-provider-key" -npx -y chilon-recall@0.1.4 doctor +npx -y chilon-recall@0.1.5 doctor ``` `doctor` 是离线检查：它能发现模板占位值和缺失的 key，但不会联系你的 provider，所以一个"看起来真实但拼错了一个字母"的 `base_url`，或者一个错误的 key，仍然会通过。接下来用 key 向导做一次在线确认： ```powershell -npx -y chilon-recall@0.1.4 key --base-url https://your-provider.example/v1 +npx -y chilon-recall@0.1.5 key --base-url https://your-provider.example/v1 ``` 它会提示你粘贴一次 key（终端隐藏输入），调用该 provider 自己的 `/models` 接口——URL 拼错会在这一步直接报错，被 provider 拒绝的 key 也一样——推荐一个 embedding 和一个 reranker 模型，并打印出已经填好真实 key、可直接复制运行的 `$env:` / `setx` / `export` 命令。chilon-recall 只把这个 key 用于这一次请求，绝不写入任何文件；但打印出的 `setx` / `>> ~/.bashrc` 命令如果你执行了，会把 key 以明文存进注册表或 shell 配置文件。 @@ -106,7 +108,7 @@ Chilon Recall 同时支持直接检索和可复用的学习工作流： 使用已发布且固定版本的 npm package，只需一条命令即可创建私有配置并安装独立 Python engine： ```powershell -npx -y chilon-recall@0.1.4 install C:\path\to\your\documents +npx -y chilon-recall@0.1.5 install C:\path\to\your\documents ``` 该命令会在资料目录写入 `chilon-recall.json`，并在操作系统用户数据目录创建持久的受管 Python engine。这两个文件是本地运行所必需的；凭据不会写入其中任何一个。 @@ -120,7 +122,7 @@ npx -y chilon-recall@0.1.4 install C:\path\to\your\documents ```powershell $env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json" $env:RAG_API_KEY = "your-provider-key" -npx -y chilon-recall@0.1.4 doctor +npx -y chilon-recall@0.1.5 doctor ``` 只有当 Python、托管 engine、配置文件及其凭据都就绪时，`doctor` 才会以退出码 `0` 结束；否则退出码为 `1`，可以放心用于脚本化验收。安装模板里的占位 `embedding.base_url`/`model` 也不会被视为"就绪"。 @@ -188,12 +190,12 @@ tool_timeout_sec = 1800 default_tools_approval_mode = "writes" ``` -**npm 已发布版本** —— 先在同一操作系统账户下运行 `npx -y chilon-recall@0.1.4 setup`。固定版本可避免 package 意外升级改变已正常工作的 MCP server。 +**npm 已发布版本** —— 先在同一操作系统账户下运行 `npx -y chilon-recall@0.1.5 setup`。固定版本可避免 package 意外升级改变已正常工作的 MCP server。 ```toml [mcp_servers.chilon-recall] command = "npx" -args = ["-y", "chilon-recall@0.1.4", "mcp"] +args = ["-y", "chilon-recall@0.1.5", "mcp"] env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY"] startup_timeout_sec = 15 tool_timeout_sec = 1800 @@ -252,7 +254,7 @@ bundle 会在 `CHILON_RECALL_ROOT` 中运行 `node scripts/cli.mjs mcp`。如果 ```json "command": "npx", -"args": ["-y", "chilon-recall@0.1.4", "mcp"] +"args": ["-y", "chilon-recall@0.1.5", "mcp"] ``` 应在 Claude Desktop 能继承的系统环境中设置 `RAG_API_KEY`；若操作系统无法提供，只能把它加入你本机的私有客户端配置。Claude Desktop 会把 `env` 值保存在本地 JSON 中，因此请限制文件权限，且绝不能提交该配置。Windows 用户应指向虚拟环境中的 `python.exe`。 @@ -262,12 +264,12 @@ bundle 会在 `CHILON_RECALL_ROOT` 中运行 `node scripts/cli.mjs mcp`。如果 Qoder 客户端从自身设置中加载 MCP server，并从项目内的 `.qoder/` 目录加载项目级 skills 与 rules。可用一条命令生成这三部分： ```powershell -npx -y chilon-recall@0.1.4 qoder C:\path\to\your\project +npx -y chilon-recall@0.1.5 qoder C:\path\to\your\project ``` 该命令会写入 `.qoder/mcp.json`、每个内置 skill 对应的 `.qoder/skills//SKILL.md`，以及 `.qoder/rules/chilon-recall.md`。若要覆盖已有文件，请加 `--force`。 -> **用 `npx` 生成会写入一个不稳定的路径。** `npx` 会把包解压到一个临时的、按次运行的缓存目录（Windows 上类似 `...\npm-cache\_npx\\...`），写入 `.qoder/mcp.json` 的 `node`/`cli.mjs` 路径就指向那里。清理 npm 缓存或升级固定版本号都会移动这个路径，导致 MCP server 悄悄起不来，且没有明显报错——只会看到 Qoder 加载失败。该命令会检测到这种情况并打印警告；建议先做一次稳定安装（`npm install -g chilon-recall@0.1.4`，或使用源码 checkout），再从那个安装位置运行 `chilon-recall qoder`，这样生成的路径才不会因清缓存而失效。 +> **用 `npx` 生成会写入一个不稳定的路径。** `npx` 会把包解压到一个临时的、按次运行的缓存目录（Windows 上类似 `...\npm-cache\_npx\\...`），写入 `.qoder/mcp.json` 的 `node`/`cli.mjs` 路径就指向那里。清理 npm 缓存或升级固定版本号都会移动这个路径，导致 MCP server 悄悄起不来，且没有明显报错——只会看到 Qoder 加载失败。该命令会检测到这种情况并打印警告；建议先做一次稳定安装（`npm install -g chilon-recall@0.1.5`，或使用源码 checkout），再从那个安装位置运行 `chilon-recall qoder`，这样生成的路径才不会因清缓存而失效。 Qoder 不会自动读取 `.qoder/mcp.json`，它只是一份可共享的配置片段。请打开 **Qoder 客户端 Settings → MCP → My Servers → + Add**，粘贴其内容，并把 `RAG_MANAGER_CONFIG` 占位符替换为你的私有配置路径： @@ -356,7 +358,7 @@ npm audit --audit-level=high ## 已知限制 -- v0.1.4 只索引 UTF-8 `.md`、`.txt`、`.rst`、`.csv`。PDF 应先转换为经过核对的文本，扫描版需 OCR。 +- v0.1.5 只索引 UTF-8 `.md`、`.txt`、`.rst`、`.csv`。PDF 应先转换为经过核对的文本，扫描版需 OCR。 - 分块器识别 Markdown `#` 与 `##` 标题，尚未语义解析表格、引文或原生文档结构。 - `rag_build` 保留为全量重建入口；`rag_sync` 使用内容哈希做增量同步，并在 staging 中重建 FAISS，以保持行 ID 与元数据严格对齐。 - 首版不内置本地 embedding/reranker 模型。 diff --git a/package-lock.json b/package-lock.json index d0494a8..f533431 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "chilon-recall", - "version": "0.1.4", + "version": "0.1.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "chilon-recall", - "version": "0.1.4", + "version": "0.1.5", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.29.0", diff --git a/package.json b/package.json index 339453f..0b7cbb4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "chilon-recall", - "version": "0.1.4", + "version": "0.1.5", "description": "A local-first MCP knowledge engine for grounded learning, document recall, and serious knowledge work.", "type": "module", "bin": {