From 329fb5fed1fb534201249b496d606d5243d530de Mon Sep 17 00:00:00 2001
From: Yige <a@wyr.me>
Date: Tue, 9 Jun 2026 11:27:13 +0800
Subject: [PATCH] =?UTF-8?q?docs(dev-environment-setup):=20/environment/ref?=
 =?UTF-8?q?resh=20=E8=A1=A5=E5=85=85=E9=87=8D=E6=96=B0=E5=8A=A0=E8=BD=BD?=
 =?UTF-8?q?=E7=99=BB=E5=BD=95=E7=8E=AF=E5=A2=83=E5=8F=98=E9=87=8F=E8=AF=AD?=
 =?UTF-8?q?=E4=B9=89=20(#24)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 变更说明 / Description

配合客户端 PR
[desirecore/desirecore#808](https://github.com/desirecore/desirecore/pull/808)：`POST
/api/runtime/environment/refresh` 端点现在除清检测缓存外，还会**重新抓取登录 shell / Windows
注册表环境并精确同步到 `process.env`**。本 PR 更新 `dev-environment-setup` skill 文档，让
AI 在「用户改了 `.zshrc` / `setx` 但工具看不到」时能主动调用该端点（无需用户重启 App）。

Companion to client PR desirecore#808: the `/environment/refresh`
endpoint now also reloads login-shell / Windows-registry env and
precise-syncs into `process.env`. This PR updates the
`dev-environment-setup` skill docs so the AI proactively calls it when a
user reports a freshly-changed env var that tools can't see.

## 改动 / Changes

- `references/desirecore-runtime.md`：第三节端点表更新 + 第七节扩展（重新加载语义 + `envDiff`
返回结构 + 「何时主动调用」触发场景 + 局限）
- `SKILL.md` / `SKILL.zh-CN.md`：L1 路由表新增「用户改了 `.zshrc` / 环境变量 / 代理 /
`setx` 但工具看不到 → 刷新端点」+ 重要约束第 3 条扩展（中英双语同步）
- `version` 2.0.3 → 2.0.4；并修正 #16 起遗留的 `source_hash` stale 值（`7e4baaf` →
`748e754b`，已用 `scripts/i18n` 同款算法验证）

## 说明 / Notes

- 该 skill 为 `translated_by: human`，中英两份已手动同步
- 文档描述的端点能力随客户端 PR desirecore#808 发布；旧客户端调用该端点仍只清检测缓存（不报错），文档短暂超前可接受
---
 skills/dev-environment-setup/SKILL.md         | 13 ++++-----
 skills/dev-environment-setup/SKILL.zh-CN.md   |  3 ++-
 .../references/desirecore-runtime.md          | 27 ++++++++++++++++---
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/skills/dev-environment-setup/SKILL.md b/skills/dev-environment-setup/SKILL.md
index 986ccaa..0d0c76f 100644
--- a/skills/dev-environment-setup/SKILL.md
+++ b/skills/dev-environment-setup/SKILL.md
@@ -12,7 +12,7 @@ description: >-
   cross-cutting environment question. 使用场景：用户提到 环境配置、PATH、
   容器、Docker、Podman、WSL、WSL2、办公依赖、系统工具，或不确定属于 Python /
   Node.js 时的入口指引。
-version: 2.0.3
+version: 2.0.4
 type: procedural
 risk_level: low
 status: enabled
@@ -27,7 +27,7 @@ tags:
   - router
 metadata:
   author: desirecore
-  updated_at: '2026-05-05'
+  updated_at: '2026-06-09'
   i18n:
     default_locale: en-US
     source_locale: zh-CN
@@ -40,7 +40,7 @@ metadata:
       description: >-
         Use this skill as a router/index when the user faces a development environment question that spans multiple domains: containers (Docker/Podman), WSL2 on Windows, office-skill dependencies (DOCX/PDF/XLSX/ PPTX), or system tools (LibreOffice/Poppler/Pandoc/Tesseract). For pure Python issues use python-runtime skill; for pure Node.js issues use nodejs-runtime skill. Triggers include: "setup environment", "PATH", "WSL", "WSL2", "docker not found", "podman", "container", "office dependency", "LibreOffice", "poppler", "pandoc", "tesseract", or any cross-cutting environment question. 使用场景：用户提到 环境配置、PATH、 容器、Docker、Podman、WSL、WSL2、办公依赖、系统工具，或不确定属于 Python / Node.js 时的入口指引。
       body: ./SKILL.zh-CN.md
-      source_hash: sha256:7e4baaf42d5c0ace
+      source_hash: sha256:748e754b5537ea01
       translated_by: human
     en-US:
       name: Dev Environment Setup
@@ -48,9 +48,9 @@ metadata:
       description: >-
         Use this skill as a router/index when the user faces a development environment question that spans multiple domains: containers (Docker/Podman), WSL2 on Windows, office-skill dependencies (DOCX/PDF/XLSX/ PPTX), or system tools (LibreOffice/Poppler/Pandoc/Tesseract). For pure Python issues use python-runtime skill; for pure Node.js issues use nodejs-runtime skill. Triggers include: "setup environment", "PATH", "WSL", "WSL2", "docker not found", "podman", "container", "office dependency", "LibreOffice", "poppler", "pandoc", "tesseract", or any cross-cutting environment question. Use when the user mentions environment setup, PATH, containers, Docker, Podman, WSL, WSL2, office dependencies, system tools, or needs an entry-point guide when uncertain whether the issue belongs to Python or Node.js.
       body: ./SKILL.md
-      source_hash: sha256:7e4baaf42d5c0ace
+      source_hash: sha256:748e754b5537ea01
       translated_by: human
-      translated_at: '2026-05-03'
+      translated_at: '2026-06-09'
 market:
   icon: >-
     <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
@@ -101,6 +101,7 @@ Route directly to the corresponding skill or document by the keywords in the use
 | LibreOffice / poppler / pandoc / tesseract / qpdf | `references/system-tools.md` |
 | Unsure of category, want a quick diagnosis | First run `scripts/probe.sh` and inspect the JSON |
 | DesireCore Hatch / Volta / HTTP API / Socket.IO | `references/desirecore-runtime.md` |
+| User edited `.zshrc` / an env var / proxy / `setx`, but tools can't see it | `POST /api/runtime/environment/refresh` reloads the login environment (see `references/desirecore-runtime.md` §7, no app restart needed) |
 | Four-tier fallback decision (API → CLI → package manager → community solution) | `references/decision-tree.md` |
 
 ## L2: Detailed Specification
@@ -147,7 +148,7 @@ DesireCore embeds Hatch (Python) and Volta (Node.js), providing complete environ
 
 1. **Do not write strong keywords like python / node / pip / npm into this skill's description**—those belong to their respective sub-skills, to avoid trigger conflicts.
 2. **API first**: `scripts/probe.sh` first checks `${DESIRECORE_ROOT}/agent-service.port`; if it exists, recommend the HTTP API path.
-3. **Cache coherence**: after any install/uninstall completes, call `POST /api/runtime/environment/refresh` to invalidate the cache before issuing subsequent GETs.
+3. **Cache coherence + env reload**: after any install/uninstall completes, call `POST /api/runtime/environment/refresh` to invalidate the cache before subsequent GETs; the same endpoint also reloads login environment variables (re-reads `.zshrc` / registry and precise-syncs into `process.env`), so when a user reports a freshly-changed env var that tools can't see, call it proactively too (no app restart; the returned `envDiff` confirms the changes).
 4. **Cross-platform**: every command template provides both macOS / Linux and Windows (PowerShell) versions.
 
 ## Sub-skill and Document Manifest
diff --git a/skills/dev-environment-setup/SKILL.zh-CN.md b/skills/dev-environment-setup/SKILL.zh-CN.md
index 58b5ab0..542c797 100644
--- a/skills/dev-environment-setup/SKILL.zh-CN.md
+++ b/skills/dev-environment-setup/SKILL.zh-CN.md
@@ -32,6 +32,7 @@ HTTP API / Socket.IO 集成的事实源（`references/desirecore-runtime.md`）
 | LibreOffice / poppler / pandoc / tesseract / qpdf | `references/system-tools.md` |
 | 不确定属于哪类、想要快速诊断 | 先跑 `scripts/probe.sh` 看 JSON |
 | DesireCore Hatch / Volta / HTTP API / Socket.IO | `references/desirecore-runtime.md` |
+| 用户改了 `.zshrc` / 环境变量 / 代理 / `setx`，但工具看不到 | `POST /api/runtime/environment/refresh` 重新加载登录环境（见 `references/desirecore-runtime.md` 第七节，无需重启 App） |
 | 四级降级决策（API → CLI → 包管理器 → 社区方案） | `references/decision-tree.md` |
 
 ## L2：详细规范
@@ -78,7 +79,7 @@ DesireCore 内置 Hatch（Python）和 Volta（Node.js），通过 HTTP API + So
 
 1. **不要把 python / node / pip / npm 强关键词写入本 skill description**——这些归属各自的子 skill，避免触发冲突。
 2. **API 优先**：`scripts/probe.sh` 第一步检测 `${DESIRECORE_ROOT}/agent-service.port`；存在则推荐 HTTP API 路径。
-3. **缓存协同**：任何安装/移除完成后，调 `POST /api/runtime/environment/refresh` 失效缓存，再发后续 GET。
+3. **缓存协同 + 重新加载环境**：任何安装/移除完成后，调 `POST /api/runtime/environment/refresh` 失效缓存再发后续 GET；该端点同时会重新加载登录环境变量（重抓 `.zshrc` / 注册表并精确同步到 `process.env`），故用户改了环境变量却反馈工具看不到时，也应主动调它（无需重启 App，返回 `envDiff` 可向用户确认变更）。
 4. **跨平台**：所有命令模板提供 macOS / Linux + Windows（PowerShell）双版本。
 
 ## 子 skill 与文档清单
diff --git a/skills/dev-environment-setup/references/desirecore-runtime.md b/skills/dev-environment-setup/references/desirecore-runtime.md
index 7659d60..ffb6a5d 100644
--- a/skills/dev-environment-setup/references/desirecore-runtime.md
+++ b/skills/dev-environment-setup/references/desirecore-runtime.md
@@ -52,7 +52,7 @@ BASE="https://127.0.0.1:${PORT}/api/runtime"
 | 方法 | 路径 | 说明 |
 |------|------|------|
 | GET | `/environment` | 返回完整 `EnvironmentSnapshot`（platform/arch/tools/wsl） |
-| POST | `/environment/refresh` | 清除进程级缓存并重新检测，返回新快照 |
+| POST | `/environment/refresh` | **重新加载登录环境变量**（重抓 `.zshrc` / 注册表并精确同步到 `process.env`）+ 清除进程级检测缓存并重新检测；返回 `EnvironmentSnapshot & { envDiff }`（详见第七节） |
 
 ### 工具链状态与安装
 
@@ -149,15 +149,34 @@ type EnvironmentSnapshot = {
 }
 ```
 
-## 七、缓存与失效
+## 七、缓存失效 + 重新加载登录环境变量
 
-`detectRuntimeEnvironment()` 使用进程级缓存。当 skill 触发了安装/移除操作后，应立即调用：
+`POST /api/runtime/environment/refresh` 按顺序做两件事：
+
+1. **重新加载登录环境变量并精确同步到 `process.env`**：重新 fork 一个登录 shell（macOS/Linux：读最新 `.zshrc` / `.zprofile` / `.bashrc`）或重读 Windows 注册表（User + Machine），把用户最新 `export` / `setx` 的变量同步进 agent-service 主进程环境。删除采用可逆回退：用户在 rc 里删掉的变量，注入前不存在则移除、注入前是系统原值则回退到原值。受保护键（`HOME` / `USER` / `SHELL` / `DESIRECORE_*` 等）不受影响。
+2. **清除运行时检测缓存并重新检测**，返回最新 `EnvironmentSnapshot`。
 
 ```bash
 curl -sk -X POST "${DESIRECORE_API}/api/runtime/environment/refresh"
 ```
 
-强制刷新；否则后续 GET `/environment` 仍返回旧快照。
+返回结构（在 `EnvironmentSnapshot` 基础上附带 `envDiff`）：
+
+```ts
+type EnvDiff = {
+  added: string[]    // 本次新增的环境变量名
+  removed: string[]  // 本次移除 / 回退的环境变量名
+  changed: string[]  // 值发生变更的环境变量名
+}
+// 返回 = EnvironmentSnapshot & { envDiff: EnvDiff }
+```
+
+**何时主动调用此端点：**
+
+- **触发了任何安装/移除操作后**（Python/Node 版本、包管理器）：失效检测缓存，否则后续 GET `/environment` 仍返回旧快照。
+- **用户反馈「我改了 `.zshrc` / 某个环境变量 / 代理 / `export` 了新变量，但你（Agent）还是看不到」**：调此端点重新加载登录环境，用户**无需重启 App**。调用后**新执行**的 Bash / 脚本工具即可看到更新后的变量。可读取返回的 `envDiff.added` / `envDiff.removed` 向用户确认实际生效的变更。
+
+**局限**：刷新仅更新主进程 `process.env` 及刷新**后**新 spawn 的子进程；已常驻运行的子进程（已启动的 MCP server、后台 `&` 进程）仍持旧 env，需重启该子进程才能生效。
 
 ## 八、参考源代码