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/python-runtime/SKILL.md
+++ b/skills/python-runtime/SKILL.md
@@ -52,7 +52,7 @@ metadata:
        Use this skill when the user needs to install, upgrade, or troubleshoot Python and pip environments. Covers four-tier fallback strategy: (1) DesireCore HTTP API for in-app installation, (2) DesireCore built-in Hatch CLI for Python version management, (3) system package managers (brew/apt/dnf/winget), (4) community pyenv as last resort. Also covers virtual environments (venv/pipx/conda), PEP 668 externally-managed errors, and import / PATH troubleshooting. Triggers include: "install python", "pip not found", "python not found", "PEP 668", "externally-managed", "venv", "virtualenv", "pipx", "conda", "miniconda", "pyenv", "hatch", "python version", "pip command not found", or any Python-related runtime error. Use when the user needs to install Python, install pip, configure virtual environments, manage multiple versions, resolve PEP 668, import failures, PATH issues, SSL certificate errors, etc.
      body: ./SKILL.md
      source_hash: sha256:ea796e0282dc77af
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -140,7 +140,7 @@ Decide using `../dev-environment-setup/references/decision-tree.md`:
 #### L1: HTTP API (→ `references/hatch-desirecore.md`)

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

 # List installable versions
@@ -158,14 +158,14 @@ curl -sk -X POST "${BASE}/environment/refresh"
 #### L2: Hatch CLI absolute path (→ `references/hatch-desirecore.md`)

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

 "$HATCH" python install 3.12
 "$HATCH" python show           # List installed/installable versions

 # Use the Hatch-installed Python directly
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
 ```

 Windows: `%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe`.
--- a/skills/python-runtime/SKILL.zh-CN.md
+++ b/skills/python-runtime/SKILL.zh-CN.md
@@ -62,7 +62,7 @@ cat /tmp/py-probe.json | jq .
 #### L1：HTTP API（→ `references/hatch-desirecore.md`）

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

 # 列出可装版本
@@ -80,14 +80,14 @@ curl -sk -X POST "${BASE}/environment/refresh"
 #### L2：Hatch CLI 绝对路径（→ `references/hatch-desirecore.md`）

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

 "$HATCH" python install 3.12
 "$HATCH" python show           # 列出已安装/可装版本

 # 直接使用 Hatch 安装的 Python
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
 ```

 Windows：`%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe`。
--- a/skills/python-runtime/references/hatch-desirecore.md
+++ b/skills/python-runtime/references/hatch-desirecore.md
@@ -1,15 +1,15 @@
 # DesireCore 内置 Hatch（L1 / L2 主路径）

-DesireCore 内置 [Hatch](https://hatch.pypa.io/) v1.16.5。Hatch 二进制随应用打包于 `static/hatch/`，运行时位于 `~/.desirecore/runtime/hatch/`，**用户无需单独安装**。
+DesireCore 内置 [Hatch](https://hatch.pypa.io/) v1.16.5。Hatch 二进制随应用打包于 `static/hatch/`，运行时位于 `${DESIRECORE_ROOT}/runtime/hatch/`，**用户无需单独安装**。

-> 与系统 Python 完全隔离：Hatch 安装的 Python 位于 `~/.desirecore/runtime/hatch/local/<version>/`，不修改系统 PATH。
+> 与系统 Python 完全隔离：Hatch 安装的 Python 位于 `${DESIRECORE_ROOT}/runtime/hatch/local/<version>/`，不修改系统 PATH。

 ## L1：通过 HTTP API 操作（推荐，DesireCore 应用内）

 ### 探测 API 可用性

 ```bash
-PORT_FILE="$HOME/.desirecore/agent-service.port"
+PORT_FILE="${DESIRECORE_ROOT}/agent-service.port"
 [ -r "$PORT_FILE" ] || { echo "API 不可用，降级到 L2"; exit 1; }
 PORT=$(cat "$PORT_FILE")
 BASE="https://127.0.0.1:${PORT}/api/runtime"
@@ -68,8 +68,8 @@ curl -sk -X POST "${BASE}/environment/refresh"
 ### macOS / Linux

 ```bash
-HATCH=~/.desirecore/runtime/hatch/hatch
-export HATCH_HOME=~/.desirecore/runtime/hatch
+HATCH=${DESIRECORE_ROOT}/runtime/hatch/hatch
+export HATCH_HOME=${DESIRECORE_ROOT}/runtime/hatch
 # export HATCH_PYTHON_MIRROR_URL=...   # 中国大陆加速可选

 # 列出版本表
@@ -89,7 +89,7 @@ export HATCH_HOME=~/.desirecore/runtime/hatch
 "$HATCH" python install 3.12 3.11 3.10   # 批量

 # 已装版本（直接读目录最稳）
-ls ~/.desirecore/runtime/hatch/local/
+ls ${DESIRECORE_ROOT}/runtime/hatch/local/

 # 移除
 "$HATCH" python remove 3.11
@@ -109,10 +109,10 @@ $env:HATCH_HOME = "$env:USERPROFILE\.desirecore\runtime\hatch"

 ```bash
 # 直接用绝对路径
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 --version
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 --version

 # 创建项目级虚拟环境（venv 推荐）
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 ```
@@ -128,7 +128,7 @@ DesireCore 应用 → 资源管理器（侧边栏文件夹图标）→ 计算资
 | 维度 | Hatch（DesireCore 内置） | pyenv（社区） |
 |------|--------------------------|---------------|
 | 安装方式 | 随应用自动内置 | 用户手动安装 |
-| Python 存放 | `~/.desirecore/runtime/hatch/local/` | `~/.pyenv/versions/` |
+| Python 存放 | `${DESIRECORE_ROOT}/runtime/hatch/local/` | `~/.pyenv/versions/` |
 | 版本切换 | 绝对路径 / venv | shell PATH (`pyenv global/local`) |
 | 系统影响 | 完全隔离 | 修改 shell 启动脚本 |
 | GUI | DesireCore 运行环境 Tab | 无 |
@@ -141,7 +141,7 @@ DesireCore 应用 → 资源管理器（侧边栏文件夹图标）→ 计算资

 | 现象 | 排查 |
 |------|------|
-| `~/.desirecore/runtime/hatch/hatch: not found` | 二进制未释放。先 `POST /api/runtime/hatch/install` 触发下载 |
+| `${DESIRECORE_ROOT}/runtime/hatch/hatch: not found` | 二进制未释放。先 `POST /api/runtime/hatch/install` 触发下载 |
 | Hatch 安装 Python 时网络超时 | 设置 `HATCH_PYTHON_MIRROR_URL` 镜像 |
 | 多版本共存路径混乱 | Hatch 永远绝对路径调用，**不要**写入 PATH |
-| macOS Gatekeeper 阻止运行 | `xattr -d com.apple.quarantine ~/.desirecore/runtime/hatch/hatch` |
+| macOS Gatekeeper 阻止运行 | `xattr -d com.apple.quarantine ${DESIRECORE_ROOT}/runtime/hatch/hatch` |
--- a/skills/python-runtime/references/virtualenv.md
+++ b/skills/python-runtime/references/virtualenv.md
@@ -30,7 +30,7 @@ deactivate
 ### 用 Hatch 安装的 Python 创建 venv

 ```bash
-~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+${DESIRECORE_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
 source .venv/bin/activate
 ```

--- a/skills/python-runtime/scripts/probe-python.sh
+++ b/skills/python-runtime/scripts/probe-python.sh
@@ -31,7 +31,7 @@ esac

 # ── DesireCore API ──────────────────────
 DESIRECORE_API=""
-PORT_FILE="$HOME/.desirecore/agent-service.port"
+PORT_FILE="${DESIRECORE_ROOT}/agent-service.port"
 if [ -r "$PORT_FILE" ]; then
  PORT=$(cat "$PORT_FILE" 2>/dev/null | tr -d '[:space:]')
  if [ -n "$PORT" ]; then
@@ -48,7 +48,7 @@ SYS_PIP=$(detect_tool pip3)
 [ "$(echo "$SYS_PIP" | grep -c '"path":""')" = "1" ] && SYS_PIP=$(detect_tool pip)

 # ── DesireCore Hatch ────────────────────
-HATCH_BIN="$HOME/.desirecore/runtime/hatch/hatch"
+HATCH_BIN="${DESIRECORE_ROOT}/runtime/hatch/hatch"
 HATCH_PATH=""
 HATCH_VERSION=""
 if [ -x "$HATCH_BIN" ]; then
@@ -57,7 +57,7 @@ if [ -x "$HATCH_BIN" ]; then
 fi

 # Hatch 已安装的 Python 版本（直接读 local/ 目录，避免依赖 hatch 命令）
-HATCH_LOCAL="$HOME/.desirecore/runtime/hatch/local"
+HATCH_LOCAL="${DESIRECORE_ROOT}/runtime/hatch/local"
 HATCH_VERSIONS="[]"
 if [ -d "$HATCH_LOCAL" ]; then
  versions=$(ls -1 "$HATCH_LOCAL" 2>/dev/null | sort -V | tr '\n' ',' | sed 's/,$//')