scriptoriumadmin/ReMe
1
0
Fork 0
mirror of https://github.com/agentscope-ai/ReMe.git synced 2026-11-05 07:39:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

docs(dsh): move environment setup into dedicated guides

Browse source 
The two READMEs keep a short introduction to the Environment tab and link
to docs/environment.md / docs/environment_ZH.md, which now carry the
setup and troubleshooting detail: Python and conda discovery plus the
recommendation rule, dependency installation, .env validation and
clearing, connection testing, the detached service lifetime, platform
support and the failure modes of each step.

The version lists include 0.2.2-alpha.2 and note that current DSH needs
Node 24.9 or newer. The package now ships docs/ as well, so the guide
travels with the published plugin.
This commit is contained in:
LiangshouX 2026-10-28 16:33:14 +08:00
parent 7584495744
commit 755a3cc26c
6 changed files with 354 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
integrations/dsh/README.md
View file

@ -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

28
integrations/dsh/README_ZH.md
View file

@ -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 上下文注入

177
integrations/dsh/docs/environment.md Normal file
View file

@ -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-<job>.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.

149
integrations/dsh/docs/environment_ZH.md Normal file
View file

@ -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-<job>.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 返回的结果。

1
integrations/dsh/package.json
View file

@ -20,6 +20,7 @@
"cordis.patch.yml",
"README.md",
"README_ZH.md",
"docs",
"figures"
],
"dsh": {

1
integrations/dsh/scripts/test-package.mjs
View file

@ -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}`);