diff --git a/integrations/dsh/README.md b/integrations/dsh/README.md index d9435e03..4fe00b44 100644 --- a/integrations/dsh/README.md +++ b/integrations/dsh/README.md @@ -4,7 +4,7 @@ This guide explains how to install, configure, and use `@agentscope-ai/reme-dsh-plugin` with DeepSeek Harness (DSH), including memory guidance injection, the `reme_search` tool, automatic memory, daily consolidation, and the ReMe Status page. -The screenshots record an earlier local integration test against DSH `0.1.5-rc.2`; the supported releases are `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-alpha.2`, `0.2.1-alpha.4`, and `0.2.1-rc.2`. Both the interface and ReMe guidance are set to English, and the isolated DSH and ReMe workspaces contain only fictional Project Aurora data. No `.env` values, API keys, access tokens, or personal memories appear in the screenshots. +The screenshots record an earlier local integration test against DSH `0.1.5-rc.2`; the supported releases are `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-alpha.2`, `0.2.1-alpha.4`, `0.2.1-rc.2`, and `0.2.2-alpha.2`. Both the interface and ReMe guidance are set to English, and the isolated DSH and ReMe workspaces contain only fictional Project Aurora data. No `.env` values, API keys, access tokens, or personal memories appear in the screenshots. ## 1. How the plugin works @@ -26,8 +26,8 @@ The DSH adapter injects **usage guidance**, not every historical memory. Relevan ## 2. Requirements - ReMe is installed and its configuration exposes the `search`, `auto_memory`, and `auto_dream` jobs. -- DeepSeek Harness `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-alpha.2`, `0.2.1-alpha.4`, or `0.2.1-rc.2`. -- Node.js `^22.19.0` or `>=24.0.0`, matching the current DSH engine range. +- DeepSeek Harness `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-alpha.2`, `0.2.1-alpha.4`, `0.2.1-rc.2`, or `0.2.2-alpha.2`. +- Node.js `^22.19.0` or `>=24.0.0`, matching the current DSH engine range (DSH `0.2.2` needs Node 24.9 or newer). - The browser running DSH can reach the configured ReMe HTTP endpoint. Cross-machine deployments must also allow the DSH browser origin. The default ReMe endpoint is `http://127.0.0.1:2333`. ReMe HTTP does not use API-key authentication, so do not expose it directly to an untrusted network. @@ -133,22 +133,19 @@ Deployment configuration also supports `REME_URL`, or `REME_HOST` together with ## 4.1 Environment management (Environment tab) -The **Environment** tab (inside **Plugins → ReMe bundle → reme-memory → Configure**) covers setup that otherwise needs a separate terminal: local Python discovery, installing ReMe, writing credentials, and starting the service. It applies to a local endpoint; a remote service URL only shows connection state. +The **Environment** tab (inside **Plugins → ReMe bundle → reme-memory → Configure**) covers the setup that +otherwise needs a separate terminal, on the machine that runs DSH: -| Section | Capability | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Service connection | Shows the configured URL and health; manual connection test | -| Local Python | Discovers PEP 514 registry entries, the py launcher, PATH and conda (base and named environments), labels their origin and `reme-ai` state, and stores the selection in `pythonPath` | -| ReMe dependency | Checks `reme-ai` version, the `[core]` extras and the `reme` CLI for the selected interpreter; installs or upgrades `reme-ai[core]` with an optional package index, live log and cancel | -| ReMe parameters | Edits the workspace `.env`; secrets stay in that file and are shown masked (last four characters). Saving requires a non-empty `EMBEDDING_API_KEY`, because ReMe 0.4.0.x aborts startup without one (`EMPTY` is a valid placeholder). Provides an LLM connectivity test | -| Service control | Starts and stops the local ReMe service, showing PID, version and log; startup injects UTF-8 and `NO_PROXY`, sets `enable_logo=false`, and runs inside the workspace so `.env` discovery works | +| Step | What it does | +| --------------- | ------------------------------------------------------------------------------------------------------------------------- | +| Local Python | Finds PEP 514, `py` launcher, `PATH` and conda interpreters, labels each origin and `reme-ai` state, stores `pythonPath` | +| ReMe dependency | Checks `reme-ai`, the `[core]` extras and the `reme` CLI; installs or upgrades `reme-ai[core]` with a live log and cancel | +| ReMe parameters | Edits the workspace `.env`; secrets stay in that file and are shown masked; provides an LLM connectivity test | +| Service control | Starts and stops the local ReMe service, showing PID, version and log | -Notes: - -- `workspace_dir` is always absolute; the default workspace is `~/.reme`. -- Services started here record their PID and launch arguments in `$DSH_HOME/reme-memory/service.json`, enabling a one-click stop. Instances started elsewhere are only observed. -- Installing `reme-ai[core]` downloads large dependencies (about 15 minutes in our local test); the job runs in the Host and survives closing the configuration page. -- The optional auto-start setting pulls the service up when DSH starts; it is off by default. +See the [Environment management guide](https://github.com/agentscope-ai/ReMe/blob/main/integrations/dsh/docs/environment.md) +for interpreter discovery and the recommendation rule, dependency installation, `.env` validation, connection +testing, service lifetime, platform support and troubleshooting. ## 5. Memory context injection diff --git a/integrations/dsh/README_ZH.md b/integrations/dsh/README_ZH.md index a43a7709..f9fcc5ca 100644 --- a/integrations/dsh/README_ZH.md +++ b/integrations/dsh/README_ZH.md @@ -26,8 +26,8 @@ DSH 启动新会话时，插件向根 Agent 注入一段“如何使用长期记 ## 2. 环境要求 - ReMe Python 服务已安装，且配置中提供 `search`、`auto_memory` 和 `auto_dream` Job。 -- DeepSeek Harness `0.1.7-rc.2`、`0.2.0-rc.2`、`0.2.1-alpha.2`、`0.2.1-alpha.4` 或 `0.2.1-rc.2`。 -- Node.js `^22.19.0` 或 `>=24.0.0`，与当前 DSH 的 engine 范围一致。 +- DeepSeek Harness `0.1.7-rc.2`、`0.2.0-rc.2`、`0.2.1-alpha.2`、`0.2.1-alpha.4`、`0.2.1-rc.2` 或 `0.2.2-alpha.2`。 +- Node.js `^22.19.0` 或 `>=24.0.0`，与当前 DSH 的 engine 范围一致（DSH `0.2.2` 需要 Node 24.9 以上）。 - DSH 页面能够访问 ReMe HTTP 地址；跨机器部署时还要允许 DSH 页面所在的浏览器 Origin。 ReMe HTTP 服务默认监听 `http://127.0.0.1:2333`，不使用 API Key 认证。因此不建议未经网络隔离直接暴露到公网。 @@ -138,22 +138,18 @@ dsh web --no-open --port 3090 ## 4.1 环境管理（Environment 标签） -**插件 → ReMe 插件包 → reme-memory → 配置 → 环境管理** 把「安装 Python、安装 ReMe、写凭据、启动服务」收进插件本体，无需另开终端。该标签面向本机服务；服务地址指向远程时只显示连接状态。 +**插件 → ReMe 插件包 → reme-memory → 配置 → 环境管理** 把「找 Python、装 ReMe、写凭据、启停服务」收进插件本体，无需另开终端； +这些操作都发生在运行 DSH 的那台机器上： -| 分区 | 能力 | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 服务连接 | 显示当前服务地址与健康状态，可手动测试连接 | -| 本地 Python 环境 | 自动发现 PEP 514 注册表、py 启动器、PATH 与 conda（base 及命名环境），标注来源与 `reme-ai` 安装状态；选中即写入 `pythonPath` | -| ReMe 依赖 | 对所选解释器检测 `reme-ai` 版本、`[core]` 依赖与 `reme` CLI；可一键安装/升级 `reme-ai[core]`（可选软件源），安装日志实时可见、可取消 | -| ReMe 参数 | 读写 workspace 的 `.env`：密钥只保存在该文件、界面仅显示末四位；保存时强制 `EMBEDDING_API_KEY` 非空（ReMe 0.4.0.x 缺少该项会启动即退出，可填占位值 `EMPTY`）；提供 LLM 连通性测试 | -| 服务控制 | 启动/停止本机 ReMe 服务，显示 PID、版本与日志；启动时自动注入 UTF-8/`NO_PROXY`、使用 `enable_logo=false` 并以 workspace 为工作目录，使 `.env` 发现规则生效 | +| 步骤 | 做什么 | +| ---------------- | ------------------------------------------------------------------------------------------------------------ | +| 本地 Python 环境 | 发现 PEP 514 注册表、`py` 启动器、`PATH` 与 conda 解释器，标注来源与 `reme-ai` 状态，选中即写入 `pythonPath` | +| ReMe 依赖 | 检测 `reme-ai`、`[core]` 依赖与 `reme` CLI；可一键安装/升级 `reme-ai[core]`，日志实时可见、可取消 | +| ReMe 参数 | 编辑 workspace 的 `.env`：密钥只保存在该文件、界面仅显示掩码；提供 LLM 连通性测试 | +| 服务控制 | 启停本机 ReMe 服务，显示 PID、版本与日志 | -要点： - -- `workspace_dir` 始终写绝对路径；未指定时使用 `~/.reme`。 -- 由插件启动的服务会记录 PID 与启动参数（`$DSH_HOME/reme-memory/service.json`），因此可一键停止；不是由插件启动的实例只显示状态。 -- `reme-ai[core]` 首次安装需要下载较多依赖（实测约 15 分钟），安装任务在后台执行，关闭配置页不会中断。 -- 可选「随 DSH 启动时自动拉起服务」，默认关闭。 +解释器发现与推荐规则、依赖安装、`.env` 校验、连接测试、服务生命周期、平台支持与故障排查见 +[环境管理指南](https://github.com/agentscope-ai/ReMe/blob/main/integrations/dsh/docs/environment_ZH.md)。 ## 5. 普通对话中的 memory 上下文注入 diff --git a/integrations/dsh/docs/environment.md b/integrations/dsh/docs/environment.md new file mode 100644 index 00000000..56839e0a --- /dev/null +++ b/integrations/dsh/docs/environment.md @@ -0,0 +1,177 @@ +# Environment management + +The **Environment** tab is the setup surface for a local ReMe install. It finds a Python interpreter on the +machine that runs DSH, installs `reme-ai[core]` into it, writes the workspace `.env`, and starts or stops the +local ReMe service — the work that otherwise needs several terminals. + +Open it from **Plugins → ReMe bundle → reme-memory → Configure → Environment**. + +The tab manages a **loopback** endpoint (`http://127.0.0.1:…` or `http://localhost:…`). With a remote service +URL it only reports whether that URL answers, and hides the local steps. + +Everything the tab reports comes from the DSH **Host**, not from the browser: Python discovery, file access, +the LLM probe and the service health check all run on the Host machine. A browser on another machine therefore +sees the Host's environment, and the hero and the service card can never disagree about it. + +## What each step does + +| Section | Capability | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Local Python | Discovers PEP 514 registry entries, the `py` launcher, `PATH` and conda (base and named environments), labels their origin and `reme-ai` state, and stores the selection in `pythonPath` | +| ReMe dependency | Checks the `reme-ai` version, the `[core]` extras and the `reme` CLI for the selected interpreter; installs or upgrades `reme-ai[core]` with an optional package index, a live log and cancel | +| ReMe parameters | Edits the workspace `.env`; secrets stay in that file and are shown masked. Saving requires a non-empty `EMBEDDING_API_KEY` (use `EMPTY` when vector search is off). Provides an LLM connectivity test | +| Service control | Starts and stops the local ReMe service, showing PID, version and log; the launch injects UTF-8 and `NO_PROXY`, sets `enable_logo=false`, and runs inside the workspace so `.env` discovery works | + +The hero summarises the same state as three chips — service, Python, ReMe — plus the endpoint, the detection +time and the two refresh actions. + +## Python discovery + +ReMe needs **Python 3.11 or newer**. The tab probes these channels on the Host and keeps only interpreters that +answered `--version`: + +- Windows: PEP 514 registry entries (`HKLM`/`HKCU`), the `py` launcher list, `PATH`, and `conda env list`. +- macOS and Linux: `PATH`, `/usr/bin`, Homebrew and `pyenv` locations, and `conda env list`. + +Microsoft Store placeholder links under `WindowsApps` are skipped, because they are shell aliases rather than +interpreters. When conda is present, named environments are listed both under `conda env list` and as +interpreters, and the conda root is reported separately. + +Detection is cached for 60 seconds; **Refresh** (in the hero) probes again. The recommended interpreter is +chosen in this order: + +1. A named conda environment (`base` excluded) that already has a supported `reme-ai`. +2. Another interpreter that already has a supported `reme-ai`. +3. Any named conda environment, which is ready for a ReMe install. +4. The first usable interpreter. + +Hover the **recommended** tag to see which rule applied. Picking another interpreter writes `pythonPath` and +nothing else; leaving it unset keeps following the recommendation. The list shows six rows and expands on +demand, with a filter over version, origin and path. + +## ReMe dependency + +The check asks the selected interpreter three questions and reports them as metrics: + +- `reme-ai` metadata version (`importlib.metadata.version("reme-ai")`), and whether it satisfies the minimum + this integration targets. +- `[core]` extras: whether `import agentscope` works. Without it, `auto_memory` and `auto_dream` are unavailable. +- `reme` CLI: the console script beside the interpreter, or the Python wrapper fallback used at start time. + +**Install reme-ai[core]** runs `python -m pip install reme-ai[core]`, optionally with an upgrade and a package +index (PyPI, Tsinghua, Aliyun). Large wheels are downloaded on first use; expect 5–20 minutes depending on the +network. + +The installation is a Host-owned job: + +- It keeps running when the configuration page closes, and reopening the tab restores it for the same + interpreter. +- Progress is polled by job id, so a second installation for another interpreter cannot replace what you see. +- **Cancel** stops pip and its build children, and the interpreter stays locked until the process has actually + exited. +- The log is written to `$DSH_HOME/reme-memory/install-.log` and its tail is shown in place. +- When the plugin unloads, running jobs are stopped. + +## Workspace `.env` + +ReMe reads credentials from the `.env` in the workspace directory at service start; the tab never stores them in +DSH settings. + +| Group | Keys | +| --------- | -------------------------------------------------------------------------------------- | +| LLM | `LLM_BACKEND`, `LLM_MODEL_NAME`, `LLM_API_KEY`, `LLM_BASE_URL` | +| Embedding | `EMBEDDING_BACKEND`, `EMBEDDING_MODEL_NAME`, `EMBEDDING_API_KEY`, `EMBEDDING_BASE_URL` | + +- The workspace directory defaults to `~/.reme` and must be absolute; changing it reloads the `.env` it points at. +- API keys are write-only: the Host returns a mask (last four characters) and a blank field means “keep the + stored key”. Leaving a key untouched never rewrites it. +- Emptying a non-secret field and saving **clears** it. Only fields you edited are written, so the rest of the + file keeps its comments, unknown keys and order. +- Saving validates the whole merged file, not just the values you typed: ReMe 0.4.0.x instantiates the embedding + component unconditionally, so `EMBEDDING_API_KEY` must be non-empty even without vector search (`EMPTY` is the + documented placeholder). A duplicated key is rewritten in every position, and the file keeps its own line + ending. +- **Test LLM connection** runs a one-token `chat/completions` request from inside the workspace with the selected + interpreter, and adds a hint for `401`/`403` (key), `404` (model or base URL) and network errors. +- Drafts are bound to the workspace they were typed in: switching the workspace drops them, so a key typed for + one workspace cannot be saved into another. + +## Connection testing + +**Test connection** in the hero asks the Host to `POST /health_check` on the configured endpoint. A healthy answer +must contain a ReMe health report, so a generic HTTP server that answers `200` with `{}` is not reported as a +running ReMe service. When the settings carry an `authToken`, the Host sends it as `Authorization: Bearer`, scoped +to that endpoint. + +## Service lifetime + +Starting the service here is equivalent to running `reme start` in a terminal — with one deliberate difference: +**the service outlives DSH**. Closing DSH does not stop it, and stopping it is an explicit action in the tab. + +That is why the plugin does not hand the service to DSH's local subprocess provider, which terminates the +processes it manages when the Host exits. The plugin owns a small service adapter instead: + +- The launch is recorded in `$DSH_HOME/reme-memory/service.json` (pid, endpoint, workspace, command, start time) + **after** the OS acknowledged the spawn, so a missing interpreter leaves no state behind. +- A service is reported as managed — and offered a **Stop** button — only when the record matches the endpoint on + screen, the pid is still alive, and its image is still a Python or `reme` executable. A record for port 2333 + never claims a service on port 2444, and a recycled pid is not mistaken for this service. +- **Stop** tree-kills the recorded process (on Windows `taskkill /T /F`) and clears the record. A service started + elsewhere stays untouched and is only observed. +- **Start** is serialized: two requests cannot spawn two services, and the second observes the first launch. +- **Auto-start** (`autoStart`, off by default) pulls the service up when DSH starts, if it is not already running. + +Python probes and pip installs are bounded Host operations; the service is the only intentionally detached +process. + +## Platform support + +| Area | Notes | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DSH | `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-alpha.2`, `0.2.1-alpha.4`, `0.2.1-rc.2`, `0.2.2-alpha.2` | +| Node.js | `^22.19.0` or `>=24.0.0`; current DSH releases need Node 24.9 or newer, and the compatibility matrix is validated with Node 24.16 | +| Windows | Tested on Windows 11 with Miniconda: registry/PATH/conda discovery, `tasklist`/`taskkill` for identity and stop, `PYTHONUTF8`/`PYTHONIOENCODING` for pip output | +| macOS / Linux | Discovery, detached start and `SIGTERM` stop are covered by unit tests; documented but less exercised on real machines than Windows | + +## Troubleshooting + +**No usable Python found.** Install Miniconda or any Python 3.11+, then press **Refresh**. Store placeholders +are filtered by design, so install a real distribution instead of the Store alias. + +**The selected interpreter is not in the list.** The tab shows it with a “not detected” tag and still uses it. +Refresh, or pick a detected interpreter. + +**Installation fails.** Open the log tail: missing wheels, a stale proxy or a restricted network usually show +there. Try a mirror. In a conda environment `pip` works, but a dedicated environment avoids dependency conflicts +with other projects. + +**Saving `.env` is refused.** `LLM_API_KEY` and `EMBEDDING_API_KEY` must both be non-empty in the saved file; +use `EMPTY` for the embedding key when vector search is off. An explicit clear of a required key is refused, and +the file is left unchanged. + +**The service reports “Port occupied”.** Something else listens on the endpoint. Change the port in the service +URL (Memory settings) or stop the other program. + +**The service does not become healthy.** The Start action polls for 90 seconds and then reports a timeout. Use +**View log** (`$DSH_HOME`-independent: the workspace `service.log`) for the startup trace — a missing `reme-ai`, +an invalid `.env`, or a port conflict all appear there. + +**The service shows as foreign.** It was started outside the plugin, so it is observed but not managed. Stop it +in its own terminal if you want the tab to manage the next launch. + +**Stop is disabled.** The running service does not belong to this endpoint, or its record is gone. Restart it +from the tab to make it managed. + +**LLM test fails.** The result distinguishes `401`/`403` (key), `404` (model name or base URL) and network +errors. The probe reads the workspace `.env`, so save before testing. + +## Where the code lives + +```text +integrations/dsh/src/environment/ +├── types.ts shared, browser-safe RPC types +├── host/ detection, install, service adapter, manager, gateway +└── client/ the tab, one module per step, copy and styles +``` + +The Host modules are the only place that touches processes or files; the client renders what the Host returns. diff --git a/integrations/dsh/docs/environment_ZH.md b/integrations/dsh/docs/environment_ZH.md new file mode 100644 index 00000000..31838266 --- /dev/null +++ b/integrations/dsh/docs/environment_ZH.md @@ -0,0 +1,149 @@ +# 环境管理 + +**Environment（环境管理）** 标签页用于在本机完成 ReMe 的准备工作：找到运行 DSH 那台机器上的 Python、把 +`reme-ai[core]` 装进该解释器、写入 workspace 的 `.env`、并启动或停止本地 ReMe 服务——这些原本需要在多个终端里完成。 + +入口：**插件 → ReMe Bundle → reme-memory → 配置 → 环境管理**。 + +该标签页只管理**回环地址**（`http://127.0.0.1:…` 或 `http://localhost:…`）。服务地址为远程 URL 时，它只显示该地址是否可 +用，并隐藏本地步骤。 + +页面上的所有结果都来自 DSH **Host**，而不是浏览器：Python 探测、文件读写、LLM 探测、服务健康检查都在 Host 上执行。因此即使 +浏览器在另一台机器上，看到的也是 Host 的真实环境，顶部概览与服务卡片不会给出不一致的结论。 + +## 每一步做什么 + +| 分组 | 能力 | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| 本地 Python | 探测 PEP 514 注册表、`py` 启动器、`PATH` 与 conda（base 与命名环境），标注来源和 `reme-ai` 状态，选择结果写入 `pythonPath` | +| ReMe 依赖 | 针对所选解释器检查 `reme-ai` 版本、`[core]` 附加依赖与 `reme` CLI；可选用软件源安装或升级 `reme-ai[core]`，显示实时日志并支持取消 | +| ReMe 参数 | 编辑 workspace 的 `.env`；密钥只存在该文件中，界面仅显示掩码。保存要求 `EMBEDDING_API_KEY` 非空（关闭向量检索时用 `EMPTY`）。提供 LLM 连通性测试 | +| 服务控制 | 启动/停止本地 ReMe 服务，显示 PID、版本与日志；启动时注入 UTF-8 与 `NO_PROXY`、设置 `enable_logo=false`，并在 workspace 内运行以保证 `.env` 能被发现 | + +顶部的概览区用三个标签（服务、Python、ReMe）概括同一份状态，并显示服务地址、探测时间与两个刷新操作。 + +## Python 探测 + +ReMe 需要 **Python 3.11 或更新版本**。标签页在 Host 上探测下列来源，只保留能回应 `--version` 的解释器： + +- Windows：PEP 514 注册表项（`HKLM`/`HKCU`）、`py` 启动器列表、`PATH`、`conda env list`。 +- macOS / Linux：`PATH`、`/usr/bin`、Homebrew 与 `pyenv` 常见路径、`conda env list`。 + +`WindowsApps` 下的 Microsoft Store 占位符会被跳过，因为它们只是别名而不是解释器。装有 conda 时，命名环境会同时出现在 +`conda env list` 与环境列表中，conda 根目录单独上报。 + +探测结果缓存 60 秒，点击概览区的**重新探测**会重新执行。推荐解释器按以下顺序选出： + +1. 已安装受支持 `reme-ai` 的命名 conda 环境（排除 `base`）。 +2. 其他已安装受支持 `reme-ai` 的解释器。 +3. 任意命名 conda 环境（可直接安装 ReMe）。 +4. 第一个可用解释器。 + +把鼠标悬停在**推荐**标签上可以看命中的是哪条规则。选择其它解释器只会写入 `pythonPath`；保持未选择则一直跟随推荐。列表默认 +显示 6 行并可展开，支持按版本、来源、路径筛选。 + +## ReMe 依赖 + +检查会向所选解释器询问三件事，并以指标形式展示： + +- `reme-ai` 元数据版本（`importlib.metadata.version("reme-ai")`），以及是否达到本集成要求的最低版本。 +- `[core]` 附加依赖：`import agentscope` 是否可用。缺失时 `auto_memory` 与 `auto_dream` 不可用。 +- `reme` CLI：解释器旁的命令行入口，或启动时回退使用的 Python 包装。 + +**安装 reme-ai[core]** 执行 `python -m pip install reme-ai[core]`，可附加升级与软件源（PyPI、清华、阿里云）。首次使用需要 +下载较大的依赖，视网络情况通常 5–20 分钟。 + +安装是 Host 侧的任务： + +- 关闭配置页后仍在运行；重新打开标签页会为同一个解释器恢复进度。 +- 进度按任务 ID 轮询，为另一个解释器发起的安装不会顶替当前显示。 +- **取消**会同时终止 pip 及其构建子进程，且在进程真正退出前该解释器保持占用。 +- 日志写入 `$DSH_HOME/reme-memory/install-.log`，页面直接显示尾部。 +- 插件卸载时，仍在运行的安装会被停止。 + +## Workspace `.env` + +ReMe 在服务启动时读取 workspace 目录下的 `.env`；标签页从不把密钥写进 DSH 设置。 + +| 分组 | 键 | +| --------- | -------------------------------------------------------------------------------------- | +| LLM | `LLM_BACKEND`、`LLM_MODEL_NAME`、`LLM_API_KEY`、`LLM_BASE_URL` | +| Embedding | `EMBEDDING_BACKEND`、`EMBEDDING_MODEL_NAME`、`EMBEDDING_API_KEY`、`EMBEDDING_BASE_URL` | + +- workspace 目录默认 `~/.reme`，必须是绝对路径；修改后会重新读取它指向的 `.env`。 +- API Key 是只写的：Host 只返回掩码（末四位），留空表示保留已存的值。没有编辑过的键不会被重写。 +- 清空非密钥字段并保存即表示**删除**该值。只有编辑过的字段会被写入，文件其余部分的注释、未知键与顺序保持不变。 +- 保存时会校验合并后的整份文件，而不只是本次输入：ReMe 0.4.0.x 会无条件实例化 embedding 组件，因此即使不使用向量检索 + `EMBEDDING_API_KEY` 也必须非空（`EMPTY` 是文档化的占位值）。重复出现的键会在每一处被改写，文件原有的换行风格也会保留。 +- **测试 LLM 连接**在 workspace 内、用所选解释器发送一次只需 1 个 token 的 `chat/completions` 请求，并对 `401`/`403` + （密钥）、`404`（模型名或 Base URL）与网络错误给出提示。 +- 草稿与输入它的 workspace 绑定：切换 workspace 会丢弃草稿，因此为某个 workspace 输入的密钥不会被保存到另一个。 + +## 连接测试 + +概览区的**测试连接**让 Host 对配置的服务地址执行 `POST /health_check`。健康响应必须包含 ReMe 的健康报告，所以只回 +`200` 与 `{}` 的普通 HTTP 服务不会被当成运行中的 ReMe。设置里填了 `authToken` 时，Host 会以 `Authorization: Bearer` 发送， +且只作用于该服务地址。 + +## 服务生命周期 + +在这里启动服务等价于在终端执行 `reme start`，但有一点是刻意的差异：**服务会比 DSH 活得更久**。关闭 DSH 不会停止它，停止 +它是在标签页里的一次显式操作。 + +因此本插件没有把服务交给 DSH 的本地子进程提供方——后者会在 Host 退出时终止它托管的进程。插件自带一个小型服务适配器： + +- 启动在操作系统确认 spawn 之后才记录到 `$DSH_HOME/reme-memory/service.json`（pid、地址、workspace、命令行、启动时间）， + 所以解释器缺失时不会留下残留状态。 +- 只有记录与当前地址一致、pid 仍存活、且进程映像仍是 Python 或 `reme` 时，服务才被判定为“由本插件托管”并给出**停止**按钮。 + 2333 端口上的记录绝不会声称管理 2444 端口上的服务，被复用的 pid 也不会被误认。 +- **停止**会树杀记录的进程（Windows 上为 `taskkill /T /F`）并清除记录。别处启动的服务不受影响，只会被观察。 +- **启动**是串行化的：两个请求不会拉起两个服务，第二个会看到第一个的启动结果。 +- **自动启动**（`autoStart`，默认关闭）会在 DSH 启动时把尚未运行的服务拉起。 + +Python 探测与 pip 安装都是有界的 Host 操作；服务是唯一被刻意分离出去的进程。 + +## 平台支持 + +| 方面 | 说明 | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| DSH | `0.1.7-rc.2`、`0.2.0-rc.2`、`0.2.1-alpha.2`、`0.2.1-alpha.4`、`0.2.1-rc.2`、`0.2.2-alpha.2` | +| Node.js | `^22.19.0` 或 `>=24.0.0`；当前 DSH 需要 Node 24.9 以上，兼容矩阵以 Node 24.16 验证 | +| Windows | 在 Windows 11 + Miniconda 上实测：注册表/PATH/conda 探测、`tasklist`/`taskkill` 身份校验与停止、`PYTHONUTF8`/`PYTHONIOENCODING` 保证 pip 输出不乱码 | +| macOS/Linux | 探测、分离启动与 `SIGTERM` 停止均有单元测试覆盖；真机验证程度低于 Windows | + +## 常见问题 + +**未检测到可用的 Python。** 安装 Miniconda 或任意 Python 3.11+，再点**重新探测**。Store 占位符会被过滤，请安装真实的发行版 +而不是 Store 别名。 + +**所选解释器不在列表里。** 标签页会用“不在探测结果中”标注它，但仍然使用它。重新探测，或改选探测到的解释器。 + +**安装失败。** 先看日志尾部：缺少 wheel、代理配置过期或网络受限通常都能看出来，可以换一个软件源。conda 环境里 `pip` 也可 +用，但独立环境更能避免与其它项目的依赖冲突。 + +**保存 `.env` 被拒绝。** 保存后的文件中 `LLM_API_KEY` 与 `EMBEDDING_API_KEY` 都必须非空；关闭向量检索时 embedding 用 +`EMPTY`。显式清空必需键会被拒绝，文件保持原样。 + +**服务显示“端口被占用”。** 该端口被其它程序占用。请在服务地址（记忆设置）中换一个端口，或停止占用它的程序。 + +**服务迟迟未就绪。** 启动会轮询 90 秒后报超时。用**查看日志**（workspace 下的 `service.log`）看启动过程——缺少 `reme-ai`、 +`.env` 不合法、端口冲突都会体现在那里。 + +**服务显示为外部启动。** 它不是由本插件启动的，因此只被观察而不被管理。若希望在标签页里管理，先在它自己的终端里停止，再从 +这里启动。 + +**停止按钮不可用。** 运行中的服务不属于当前服务地址，或记录已丢失。从标签页重新启动一次即可纳入管理。 + +**LLM 测试失败。** 结果会区分 `401`/`403`（密钥）、`404`（模型名或 Base URL）与网络错误。探测读取的是 workspace 的 +`.env`，所以请先保存再测试。 + +## 代码位置 + +```text +integrations/dsh/src/environment/ +├── types.ts 浏览器安全的共享 RPC 类型 +├── host/ 探测、安装、服务适配器、manager、gateway +└── client/ 标签页：每个步骤一个模块，以及文案与样式 +``` + +只有 Host 模块会接触进程与文件；客户端只负责渲染 Host 返回的结果。 diff --git a/integrations/dsh/package.json b/integrations/dsh/package.json index 42e330a6..99bd5f00 100644 --- a/integrations/dsh/package.json +++ b/integrations/dsh/package.json @@ -20,6 +20,7 @@ "cordis.patch.yml", "README.md", "README_ZH.md", + "docs", "figures" ], "dsh": { diff --git a/integrations/dsh/scripts/test-package.mjs b/integrations/dsh/scripts/test-package.mjs index 66f0029c..de77a6f1 100644 --- a/integrations/dsh/scripts/test-package.mjs +++ b/integrations/dsh/scripts/test-package.mjs @@ -89,6 +89,7 @@ try { "dist/client.js", "cordis.patch.yml", "README.md", + "docs/environment.md", "figures/reme-status-overview.png", ]) { assert.ok(files.has(file), `missing ${file}`);