fix: replace hardcoded ~/.desirecore paths with ${DESIRECORE_ROOT} variable (#16)

## Summary - 将所有技能文件中的硬编码 `~/.desirecore/` 和 `$HOME/.desirecore/` 路径替换为 `${DESIRECORE_ROOT}/` 变量 - 递增 manifest.json version 至 1.2.1 ## Why dev 模式下 `DESIRECORE_HOME=~/.desirecore-dev`，硬编码路径导致技能读取错误的端口文件和目录。主仓库的 `variable-substitutor.ts` 会在运行时将 `${DESIRECORE_ROOT}` 替换为实际根目录。 ## Test plan - [ ] `npm run dev` 启动后触发任意技能，确认端口路径解析为 `~/.desirecore-dev/agent-service.port` - [ ] prod 模式确认路径为 `~/.desirecore/agent-service.port` 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-06 08:10:48 +08:00 · 2026-05-29 15:36:19 +08:00
parent 3015a3ffb8
commit 4f7037a6b6
52 changed files with 192 additions and 192 deletions
--- a/skills/dev-environment-setup/references/decision-tree.md
+++ b/skills/dev-environment-setup/references/decision-tree.md
@@ -35,14 +35,14 @@

 **触发条件**

- `~/.desirecore/agent-service.port` 文件存在且可读
+- `${DESIRECORE_ROOT}/agent-service.port` 文件存在且可读
 - `curl -sk --max-time 0.5 https://127.0.0.1:${PORT}/api/runtime/environment` 返回 2xx
 - 当前会话能订阅 Socket.IO（DesireCore 内部 Agent 默认满足）

 **典型操作**

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 BASE="https://127.0.0.1:${PORT}/api/runtime"

 # 1. 拉取快照
@@ -74,11 +74,11 @@ curl -sk -X POST "${BASE}/python/install" \
 **典型操作（macOS / Linux）**

 ```bash
-HATCH=~/.desirecore/runtime/hatch/hatch
-VOLTA=~/.desirecore/runtime/volta/volta
+HATCH=${DESIRECORE_ROOT}/runtime/hatch/hatch
+VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta

-export HATCH_HOME=~/.desirecore/runtime/hatch
-export VOLTA_HOME=~/.desirecore/runtime/volta
+export HATCH_HOME=${DESIRECORE_ROOT}/runtime/hatch
+export VOLTA_HOME=${DESIRECORE_ROOT}/runtime/volta

 "$HATCH" python install 3.12
 "$VOLTA" install node@22
--- a/skills/dev-environment-setup/references/desirecore-runtime.md
+++ b/skills/dev-environment-setup/references/desirecore-runtime.md
@@ -8,19 +8,19 @@ DesireCore 内置了完整的开发环境管理基础设施。`python-runtime`

 | 平台 | 运行时绝对路径（用户安装版，优先） | 静态打包兜底 |
 |------|----------------------------------|--------------|
-| macOS / Linux | `~/.desirecore/runtime/hatch/hatch` | 应用包内 `static/hatch/hatch` |
+| macOS / Linux | `${DESIRECORE_ROOT}/runtime/hatch/hatch` | 应用包内 `static/hatch/hatch` |
 | Windows | `%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe` | 应用包内 `static/hatch/hatch.exe` |

-**Python 版本安装目录**：`~/.desirecore/runtime/hatch/local/<版本>/python/bin/python3`（macOS/Linux），Windows 为 `python.exe`。
+**Python 版本安装目录**：`${DESIRECORE_ROOT}/runtime/hatch/local/<版本>/python/bin/python3`（macOS/Linux），Windows 为 `python.exe`。

 ### Volta（Node.js 工具链管理器，v2.0.2）

 | 平台 | 运行时绝对路径 | 静态打包兜底 |
 |------|----------------|--------------|
-| macOS / Linux | `~/.desirecore/runtime/volta/volta` | 应用包内 `static/volta/volta` |
+| macOS / Linux | `${DESIRECORE_ROOT}/runtime/volta/volta` | 应用包内 `static/volta/volta` |
 | Windows | `%USERPROFILE%\.desirecore\runtime\volta\volta.exe` | 应用包内 `static/volta/volta.exe` |

-**Node.js 安装目录**：`~/.desirecore/runtime/volta/tools/image/node/<version>/`，包管理器在 `tools/image/{packages,pnpm,yarn,npm}/`。
+**Node.js 安装目录**：`${DESIRECORE_ROOT}/runtime/volta/tools/image/node/<version>/`，包管理器在 `tools/image/{packages,pnpm,yarn,npm}/`。

 ### 优先级规则

@@ -30,9 +30,9 @@ DesireCore 内置了完整的开发环境管理基础设施。`python-runtime`

 | 变量 | 作用 | 默认/示例 |
 |------|------|----------|
-| `HATCH_HOME` | Hatch 工作目录 | `~/.desirecore/runtime/hatch` |
+| `HATCH_HOME` | Hatch 工作目录 | `${DESIRECORE_ROOT}/runtime/hatch` |
 | `HATCH_PYTHON_MIRROR_URL` | Python 下载镜像 | 加速节点（中国大陆） |
-| `VOLTA_HOME` | Volta 工作目录 | `~/.desirecore/runtime/volta` |
+| `VOLTA_HOME` | Volta 工作目录 | `${DESIRECORE_ROOT}/runtime/volta` |
 | `VOLTA_NODE_MIRROR` | Node.js 下载镜像 | `https://npmmirror.com/mirrors/node` |
 | `VOLTA_FEATURE_PNPM` | 启用 pnpm 管理 | `1` |

@@ -40,10 +40,10 @@ DesireCore 在启动子进程时会自动注入这些变量；外部直接调用

 ## 三、HTTP API 速查表

-DesireCore agent-service 启动后将端口写入 `~/.desirecore/agent-service.port`。全部接口走 **HTTPS + 自签名证书**（curl 需要 `-k`）。
+DesireCore agent-service 启动后将端口写入 `${DESIRECORE_ROOT}/agent-service.port`。全部接口走 **HTTPS + 自签名证书**（curl 需要 `-k`）。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 BASE="https://127.0.0.1:${PORT}/api/runtime"
 ```

@@ -106,7 +106,7 @@ BASE="https://127.0.0.1:${PORT}/api/runtime"
 skill 必须先判定 API 是否可达，再决定走 HTTP 还是 CLI：

 ```bash
-PORT_FILE="$HOME/.desirecore/agent-service.port"
+PORT_FILE="${DESIRECORE_ROOT}/agent-service.port"
 if [ -r "$PORT_FILE" ]; then
  PORT=$(cat "$PORT_FILE")
  if curl -sk --max-time 0.5 "https://127.0.0.1:${PORT}/api/runtime/environment" >/dev/null 2>&1; then
@@ -166,4 +166,4 @@ curl -sk -X POST "${DESIRECORE_API}/api/runtime/environment/refresh"
 | 工具检测 | `lib/agent-service/environment-detection.ts` | 1–310 |
 | 工具链管理（Hatch/Volta + 版本安装） | `lib/agent-service/runtime-manager.ts` | 1–1165 |
 | HTTP 路由 | `lib/agent-service/routes/runtime-env-routes.ts` | 1–186 |
-| 端口文件 | `~/.desirecore/agent-service.port` | DesireCore 启动时写入 |
+| 端口文件 | `${DESIRECORE_ROOT}/agent-service.port` | DesireCore 启动时写入 |
--- a/skills/dev-environment-setup/references/office-deps.md
+++ b/skills/dev-environment-setup/references/office-deps.md
@@ -166,10 +166,10 @@ DesireCore 内置 Hatch/Volta，但**不直接管理 pip / npm 包安装**——

 如果使用 Hatch 创建的 Python：
 ```bash
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m pip install lxml defusedxml
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m pip install lxml defusedxml
 ```

 如果使用 Volta 安装的 Node：
 ```bash
-~/.desirecore/runtime/volta/bin/npm install -g docx pptxgenjs
+${DESIRECORE_ROOT}/runtime/volta/bin/npm install -g docx pptxgenjs
 ```
--- a/skills/dev-environment-setup/references/probe-snapshot.md
+++ b/skills/dev-environment-setup/references/probe-snapshot.md
@@ -9,7 +9,7 @@
 | `platform` | `"darwin" \| "linux" \| "win32"` | 操作系统标识 |
 | `arch` | `"arm64" \| "x64" \| ...` | CPU 架构 |
 | `desirecore_api` | `string` | 探测到的 DesireCore agent-service URL，不可达时为 `""` |
-| `desirecore_port_file` | `boolean` | `~/.desirecore/agent-service.port` 是否存在（probe.sh / probe.ps1 输出原生 JSON boolean） |
+| `desirecore_port_file` | `boolean` | `${DESIRECORE_ROOT}/agent-service.port` 是否存在（probe.sh / probe.ps1 输出原生 JSON boolean） |

 ## probe.sh / probe.ps1（父级 dev-environment-setup）

@@ -57,7 +57,7 @@ Windows 上 `wsl` 字段值类似 `{ "installed": true, "version": "2", "default

 字段语义：
 - `hatch_path` 空字符串表示二进制不存在
- `hatch_versions` 是 `~/.desirecore/runtime/hatch/local/` 下的目录列表（即已通过 Hatch 安装的 Python 版本）
+- `hatch_versions` 是 `${DESIRECORE_ROOT}/runtime/hatch/local/` 下的目录列表（即已通过 Hatch 安装的 Python 版本）
 - `active_venv` 取自 `$VIRTUAL_ENV` 环境变量
 - `pep668` 检测 `/usr/lib/python*/EXTERNALLY-MANAGED` 是否存在（Debian 12+/Ubuntu 23.04+ 启用）