From f9fd86a7ac9c23dea94a460bfb7f12a3d6ca891b Mon Sep 17 00:00:00 2001 From: forrestlinfeng Date: Mon, 28 Sep 2026 19:56:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=B8=A4=E5=A4=84?= =?UTF-8?q?=E5=AE=89=E8=A3=85=E8=AF=B4=E6=98=8E=EF=BC=8C=E6=94=B9=E6=8E=89?= =?UTF-8?q?=E5=87=A0=E6=9D=A1=E8=B7=91=E4=B8=8D=E9=80=9A=E7=9A=84=E5=91=BD?= =?UTF-8?q?=E4=BB=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 插件侧：`dsh plugin --profile X ...` 是把余下参数透传给 profile 目录里的 pnpm，所以 `add -w ./` 里的 `./` 指的是 profile 自己，不是你的 checkout。 本地开发要用绝对路径，而且该用 link 而不是 add——add 装的是硬链接快照， 改已有文件能同步，新增和删除文件不会，下次启动就 ERR_MODULE_NOT_FOUND。 仓库里 scripts/sync-dsh-profile.sh 正是为此存在，之前文档里一个字没提。 重装也救不回来：profile 的 lockfile 钉着 registry 已不再提供的预发布 peer。 顺带补上 -w 的原因（profile 目录是 pnpm workspace 根），列出实际存在的 四个 profile，并说明仓库是公开的、按 commit 安装不需要凭证。npm 那条 改成如实说"尚未发布"。 evolver 侧：原来只有 npm 一条。补上 GitHub Releases 的独立二进制，含 校验与安装命令，以及各平台产物名。两者的实质差别是自更新——npm 形态下 Proxy 会明确报告没有自更新目标并关掉它，这一点选之前就该知道。 Co-Authored-By: Claude Opus 5 --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 72 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0083bd7..ba2836e 100644 --- a/README.md +++ b/README.md @@ -35,43 +35,100 @@ workspace, session, turn, turn reason, and diff fingerprint. ## Install -Until the first npm release, install from a pinned repository commit: +`dsh plugin --profile ...` forwards everything after it to pnpm **inside that +profile's directory**. Paths are therefore resolved there, not in your shell's working +directory, and a bare `./` means the profile itself. Profiles ship as `web`, `desktop`, +`headless` and `dsh-tui`; use the one you actually boot. A profile directory is a pnpm +workspace root, so `add` needs `-w` — without it pnpm stops with `ERR_PNPM_ADDING_TO_ROOT`. + +### From a pinned commit + +This repository is public, so no credentials are involved: ```bash -dsh plugin --profile web add -w github:EvoMap/evolver-dsh-plugin# +dsh plugin --profile dsh-tui add -w github:EvoMap/evolver-dsh-plugin# ``` -Or install from a local checkout: +### From npm + +`@evomap/dsh-evolver` is not published yet. Once it is: ```bash -dsh plugin --profile web add -w ./ +dsh plugin --profile dsh-tui add -w @evomap/dsh-evolver ``` -After `@evomap/dsh-evolver@0.1.0` is published: +### From a local checkout + +Use an absolute path, and link rather than add: ```bash -dsh plugin --profile web add -w @evomap/dsh-evolver +dsh plugin --profile dsh-tui link /absolute/path/to/evolver-dsh-plugin ``` -The package declares `dsh.bundle`, so dsh adds it to the selected profile without manual -`cordis.patch.yml` edits. Verify and boot the profile: +`link` leaves `node_modules` pointing at the working tree, so edits, new files and deleted +files are all live. `add -w /absolute/path/...` looks equivalent and is not: it installs a +hardlink snapshot, where edits to existing files are shared but files you add or delete +never reach `node_modules`, and the next boot fails with `ERR_MODULE_NOT_FOUND`. A profile +already installed that way is repaired by re-linking the tree file by file: ```bash -dsh --profile web --dump-config | grep -A2 'dsh-evolver' -dsh --profile web +./scripts/sync-dsh-profile.sh dsh-tui +``` + +Reinstalling does not repair it. The profile's lockfile pins prerelease peers that the +registry no longer serves, so `pnpm install` fails before it reaches this package. + +### Verify and boot + +The package declares `dsh.bundle`, so dsh adds it to the profile's patch stack without +manual `cordis.patch.yml` edits: + +```bash +dsh --profile dsh-tui --dump-config | grep -A2 'dsh-evolver' +dsh --profile dsh-tui ``` ## Connect the EvoMap network -Local memory works without an account or network connection. To enable network assets: +Local memory works without an account or network connection. Network assets need the +Evolver engine, which ships two ways. + +**From npm**, if you already manage global CLIs with node: + +```bash +npm install -g @evomap/evolver +evolver --version +``` + +**From GitHub Releases**, as a standalone binary with no node on the host. Pick the +artifact for your platform — `evolver-darwin-arm64`, `evolver-darwin-x64`, +`evolver-linux-arm64` or `evolver-linux-x64`: + +```bash +base=https://github.com/EvoMap/evolver/releases/latest/download +curl -fLO $base/evolver-darwin-arm64 +curl -fLO $base/evolver-darwin-arm64.sha256 +shasum -a 256 -c evolver-darwin-arm64.sha256 +install -m 755 evolver-darwin-arm64 /usr/local/bin/evolver +``` + +Each release also publishes `evolver-update-manifest.json`, carrying every artifact's +version, size and digest. + +The two shapes differ in one respect worth knowing before you choose: self-update works +only for the standalone binary. Started from the npm install, the Proxy reports +`running from the npm/JS install shape, which has no standalone binary target for +self-update` and carries on with it off, so npm installs are upgraded by `npm install -g` +again. + +Then, either way: -1. Install the engine: `npm install -g @evomap/evolver`. -2. Run `evolver` once inside a git repository. It starts the local Proxy and prints a +1. Run `evolver` once inside a git repository. It starts the local Proxy and prints a claim link for a fresh node. -3. Open the claim link while signed in to [evomap.ai](https://evomap.ai). The `/evolver-status` +2. Open the claim link while signed in to [evomap.ai](https://evomap.ai). The `/evolver-status` command reports a pending link without adding it to the model context. Set `claimNudgeEnabled: true` only if periodic reminders are desired. -4. Run `/evolver-status` to confirm the Proxy and node state. +3. Run `/evolver-status` to confirm the Proxy and node state. The Proxy is a separate loopback process. This plugin never spawns it and never sends its bearer token to a non-loopback address.