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 05:50:41 +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/_protected-paths.yaml
+++ b/skills/_protected-paths.yaml
@@ -71,12 +71,12 @@ protected_paths:
  # ============================================
  # 用户隐私（需用户本人确认）
  # ============================================
-  - path: "~/.desirecore/users/*/privacy.md"
+  - path: "${DESIRECORE_ROOT}/users/*/privacy.md"
    protection: owner_only
    reason: "隐私设置需用户本人或 owner 修改"
    description: "用户隐私边界配置"

-  - path: "~/.desirecore/users/*/agents/*/relationship.md"
+  - path: "${DESIRECORE_ROOT}/users/*/agents/*/relationship.md"
    section: "禁区"
    protection: confirm
    reason: "关系禁区需用户确认"
--- a/skills/dashscope-image-gen/SKILL.md
+++ b/skills/dashscope-image-gen/SKILL.md
@@ -95,7 +95,7 @@ market:
 Generate the image via media-proxy's compatible-mode endpoint; the response includes the image URL directly:

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -151,7 +151,7 @@ Locate the item with `type: "image"` inside `data.output.choices[0].message.cont
 The image URL is time-limited; download and persist it to the local media-store immediately:

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 IMAGE_URL="image URL from step 1's response"
 curl -sL "$IMAGE_URL" -o /tmp/dashscope-gen.png && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/dashscope-image-gen/SKILL.zh-CN.md
+++ b/skills/dashscope-image-gen/SKILL.zh-CN.md
@@ -31,7 +31,7 @@
 通过 media-proxy 的 compatible-mode 端点生成图片，响应直接包含图片 URL：

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -87,7 +87,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 图片 URL 有时效，必须立即下载并保存到本地 media-store：

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 IMAGE_URL="第一步响应中的 image URL"
 curl -sL "$IMAGE_URL" -o /tmp/dashscope-gen.png && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/dev-environment-setup/SKILL.md
+++ b/skills/dev-environment-setup/SKILL.md
@@ -49,7 +49,7 @@ metadata:
        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
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -146,7 +146,7 @@ DesireCore embeds Hatch (Python) and Volta (Node.js), providing complete environ
 ## Important Constraints

 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/agent-service.port`; if it exists, recommend the HTTP API path.
+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.
 4. **Cross-platform**: every command template provides both macOS / Linux and Windows (PowerShell) versions.

--- a/skills/dev-environment-setup/SKILL.zh-CN.md
+++ b/skills/dev-environment-setup/SKILL.zh-CN.md
@@ -77,7 +77,7 @@ DesireCore 内置 Hatch（Python）和 Volta（Node.js），通过 HTTP API + So
 ## 重要约束

 1. **不要把 python / node / pip / npm 强关键词写入本 skill description**——这些归属各自的子 skill，避免触发冲突。
-2. **API 优先**：`scripts/probe.sh` 第一步检测 `~/.desirecore/agent-service.port`；存在则推荐 HTTP API 路径。
+2. **API 优先**：`scripts/probe.sh` 第一步检测 `${DESIRECORE_ROOT}/agent-service.port`；存在则推荐 HTTP API 路径。
 3. **缓存协同**：任何安装/移除完成后，调 `POST /api/runtime/environment/refresh` 失效缓存，再发后续 GET。
 4. **跨平台**：所有命令模板提供 macOS / Linux + Windows（PowerShell）双版本。

--- 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+ 启用）

--- a/skills/dev-environment-setup/scripts/probe.sh
+++ b/skills/dev-environment-setup/scripts/probe.sh
@@ -32,7 +32,7 @@ case "$ARCH" in
 esac

 # ── DesireCore API 探测 ─────────────────
-PORT_FILE="$HOME/.desirecore/agent-service.port"
+PORT_FILE="${DESIRECORE_ROOT}/agent-service.port"
 DESIRECORE_API=""
 PORT_FILE_EXISTS="false"
 if [ -r "$PORT_FILE" ]; then
--- a/skills/mail-operations/SKILL.md
+++ b/skills/mail-operations/SKILL.md
@@ -45,7 +45,7 @@ metadata:
        Use this skill whenever the user wants to interact with email. This includes reading inbox, sending emails, replying, searching messages, managing labels and categories, downloading attachments, setting up auto-reply rules, or triggering agents to handle incoming emails. Supports Gmail, Outlook, and IMAP/SMTP (QQ Mail, 163, Yahoo, etc.) through DesireCore's local REST API. Use when the user mentions email, mailbox, inbox, sending email, replying, checking email, Gmail, Outlook, QQ Mail, 163 Mail, attachments, labels, drafts, auto-reply, email rules, forwarding, CC, unread email, receiving, sending, email sync, or email search.
      body: ./SKILL.md
      source_hash: sha256:24bffbade0dc09a7
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -397,7 +397,7 @@ The email system uses **local cache + periodic polling**:
 - **Read operations** (query, search): return the local cache; may be delayed (default 30-second polling)
 - **Remote changes** (the user operates from the official web UI): wait for the next polling cycle to sync

-**Storage path**: `~/.desirecore/mail/{provider}/{email}/` (index.json, messages/, sync.json)
+**Storage path**: `${DESIRECORE_ROOT}/mail/{provider}/{email}/` (index.json, messages/, sync.json)

 ---

--- a/skills/mail-operations/SKILL.zh-CN.md
+++ b/skills/mail-operations/SKILL.zh-CN.md
@@ -333,7 +333,7 @@ Outlook 使用 Categories 而非 Labels。
 - **读操作**（查询、搜索）：返回本地缓存，可能有延迟（默认 30 秒轮询）
 - **远程变更**（用户在官方页面操作）：需等待下次轮询同步

-**存储路径**：`~/.desirecore/mail/{provider}/{email}/`（index.json, messages/, sync.json）
+**存储路径**：`${DESIRECORE_ROOT}/mail/{provider}/{email}/`（index.json, messages/, sync.json）

 ---

--- a/skills/manage-skills/SKILL.md
+++ b/skills/manage-skills/SKILL.md
@@ -222,10 +222,10 @@ POST /api/agents/{agentId}/skills

 ```bash
 # Sidecar file path for a global Skill
-~/.desirecore/skills/{skillId}/{filename}
+${DESIRECORE_ROOT}/skills/{skillId}/{filename}

 # Sidecar file path for an Agent-scoped Skill
-~/.desirecore/agents/{agentId}/skills/{skillId}/{filename}
+${DESIRECORE_ROOT}/agents/{agentId}/skills/{skillId}/{filename}
 ```

 ### 3. Manage Existing Skills via API
@@ -351,7 +351,7 @@ When you need to create a Skill from scratch or the API approach is not flexible
 **Global Skill** (visible to all Agents):

 ```
-~/.desirecore/skills/
+${DESIRECORE_ROOT}/skills/
 └── my-new-skill/
    ├── SKILL.md          # required: skill definition file
    ├── examples/          # optional: example files
@@ -362,7 +362,7 @@ When you need to create a Skill from scratch or the API approach is not flexible
 **Agent-scoped Skill** (visible only to the specified Agent):

 ```
-~/.desirecore/agents/{agentId}/
+${DESIRECORE_ROOT}/agents/{agentId}/
 └── skills/
    └── my-new-skill/
        ├── SKILL.md
@@ -441,7 +441,7 @@ Describe the execution flow, API calls, and input/output formats stage by stage
 The following example shows how to create a global Skill with the Write tool:

 ```
-Target path: ~/.desirecore/skills/daily-summary/SKILL.md
+Target path: ${DESIRECORE_ROOT}/skills/daily-summary/SKILL.md
 ```

 Content to write:
@@ -535,8 +535,8 @@ Skills exist at three scope levels, listed from highest priority to lowest:
 | Priority | Scope     | Path                                     | Visibility           |
 | ------ | ---------- | ---------------------------------------- | ------------------ |
 | Highest   | Project | `.claude/skills/` (project root)           | All Agents in the current project |
-| Medium     | Agent   | `~/.desirecore/agents/{agentId}/skills/` | Only that Agent         |
-| Lowest    | Global  | `~/.desirecore/skills/`                  | All Agents         |
+| Medium     | Agent   | `${DESIRECORE_ROOT}/agents/{agentId}/skills/` | Only that Agent         |
+| Lowest    | Global  | `${DESIRECORE_ROOT}/skills/`                  | All Agents         |

 **Same-name override rule**: a Skill in a higher-priority scope overrides a same-named Skill in a lower-priority scope. For example, an Agent-scoped `data-analysis` Skill will shadow a global Skill of the same name.

--- a/skills/manage-skills/SKILL.zh-CN.md
+++ b/skills/manage-skills/SKILL.zh-CN.md
@@ -162,10 +162,10 @@ POST /api/agents/{agentId}/skills

 ```bash
 # 全局技能的 sidecar 文件路径
-~/.desirecore/skills/{skillId}/{filename}
+${DESIRECORE_ROOT}/skills/{skillId}/{filename}

 # Agent 级技能的 sidecar 文件路径
-~/.desirecore/agents/{agentId}/skills/{skillId}/{filename}
+${DESIRECORE_ROOT}/agents/{agentId}/skills/{skillId}/{filename}
 ```

 ### 3. 通过 API 管理已有技能
@@ -291,7 +291,7 @@ Content-Type: application/json
 **全局技能**（所有 Agent 可见）：

 ```
-~/.desirecore/skills/
+${DESIRECORE_ROOT}/skills/
 └── my-new-skill/
    ├── SKILL.md          # 必须：技能定义文件
    ├── examples/          # 可选：示例文件
@@ -302,7 +302,7 @@ Content-Type: application/json
 **Agent 级技能**（仅指定 Agent 可见）：

 ```
-~/.desirecore/agents/{agentId}/
+${DESIRECORE_ROOT}/agents/{agentId}/
 └── skills/
    └── my-new-skill/
        ├── SKILL.md
@@ -381,7 +381,7 @@ requires:
 以下示例展示如何使用 Write 工具创建一个全局技能：

 ```
-目标路径：~/.desirecore/skills/daily-summary/SKILL.md
+目标路径：${DESIRECORE_ROOT}/skills/daily-summary/SKILL.md
 ```

 写入内容：
@@ -475,8 +475,8 @@ metadata:
 | 优先级 | 作用域     | 路径                                     | 可见范围           |
 | ------ | ---------- | ---------------------------------------- | ------------------ |
 | 最高   | Project 级 | `.claude/skills/` (项目根目录)           | 当前项目所有 Agent |
-| 中     | Agent 级   | `~/.desirecore/agents/{agentId}/skills/` | 仅该 Agent         |
-| 最低   | Global 级  | `~/.desirecore/skills/`                  | 所有 Agent         |
+| 中     | Agent 级   | `${DESIRECORE_ROOT}/agents/{agentId}/skills/` | 仅该 Agent         |
+| 最低   | Global 级  | `${DESIRECORE_ROOT}/skills/`                  | 所有 Agent         |

 **同名覆盖规则**：高优先级作用域的同名技能会覆盖低优先级的。例如 Agent 级有一个 `data-analysis` 技能，会覆盖全局同名技能。

--- a/skills/minimax-image-gen/SKILL.md
+++ b/skills/minimax-image-gen/SKILL.md
@@ -44,7 +44,7 @@ metadata:
        Use this skill when the user wants to generate images using MiniMax's image-01 model. Supports text-to-image and subject reference for character consistency. Use when the user mentions generate images, draw a picture, text-to-image, create an image, AI painting, generate illustration, draw one for me, help me draw, design an image, MiniMax drawing.
      body: ./SKILL.md
      source_hash: sha256:4630268ef3bd4e23
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -78,7 +78,7 @@ market:
 ### Step 1: Call the API to generate the image

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -100,7 +100,7 @@ Extract `data.data.image_urls[0]` from the JSON response to obtain the image URL
 ### Step 2: Download and upload to media-store

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 IMAGE_URL="第一步拿到的图片URL"
 curl -sL "$IMAGE_URL" -o /tmp/minimax-gen.png && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/minimax-image-gen/SKILL.zh-CN.md
+++ b/skills/minimax-image-gen/SKILL.zh-CN.md
@@ -15,7 +15,7 @@
 ### 第一步：调用 API 生成图片

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -37,7 +37,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 ### 第二步：下载并上传到 media-store

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 IMAGE_URL="第一步拿到的图片URL"
 curl -sL "$IMAGE_URL" -o /tmp/minimax-gen.png && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/minimax-music-gen/SKILL.md
+++ b/skills/minimax-music-gen/SKILL.md
@@ -118,7 +118,7 @@ Example lyrics format:
 **Note: Do not pass the `output_format` parameter; use the default hex format.**

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -142,7 +142,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 ### Generate Pure Instrumental

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -198,7 +198,7 @@ The API returns JSON; audio data is hex-encoded and stored in the `data.data.aud
 Extract the hex string from the `data.data.audio.data` field of the response JSON, convert it to binary, and upload:

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 # Save the API response to a temporary file (avoid letting large hex data overflow shell variables)
 # Assume the curl output of the previous step has been saved to /tmp/minimax-music-resp.json

@@ -256,7 +256,7 @@ Example: `"独立民谣,温暖治愈,木吉他为主,轻柔的鼓点,渐进式
 If the user only describes the desired music style without providing lyrics, set `lyrics_optimizer: true` and the model will auto-generate lyrics from the prompt:

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
--- a/skills/minimax-music-gen/SKILL.zh-CN.md
+++ b/skills/minimax-music-gen/SKILL.zh-CN.md
@@ -54,7 +54,7 @@ lyrics 字段支持以下结构标签来组织歌曲段落：
 **注意：不要传 `output_format` 参数，使用默认的 hex 格式。**

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -78,7 +78,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 ### 生成纯器乐

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -134,7 +134,7 @@ API 返回 JSON，音频数据以 hex 编码存放在 `data.data.audio.data` 字
 从响应 JSON 中提取 `data.data.audio.data` 字段的 hex 字符串，转为二进制后上传：

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 # 将 API 响应保存到临时文件（避免 hex 数据过大撑爆 shell 变量）
 # 假设上一步的 curl 输出已保存到 /tmp/minimax-music-resp.json

@@ -192,7 +192,7 @@ prompt 用于描述音乐的风格、情绪和乐器编排，建议用逗号分
 如果用户只描述了想要的音乐风格但没有提供歌词，可以设置 `lyrics_optimizer: true`，模型会根据 prompt 自动生成歌词：

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
--- a/skills/minimax-tts/SKILL.md
+++ b/skills/minimax-tts/SKILL.md
@@ -45,7 +45,7 @@ metadata:
        Use this skill when the user wants to convert text to speech using MiniMax's T2A (Text-to-Audio) API. Supports multiple voice styles, emotional control, and voice cloning. Use when the user mentions text-to-speech, TTS, read aloud, read it out, generate speech, generate audio, text-to-audio, voiceover, narrate it, MiniMax voice.
      body: ./SKILL.md
      source_hash: sha256:455a2ee6365958c2
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -92,7 +92,7 @@ market:
 MiniMax TTS returns JSON (containing an audio URL or hex data); use `"json"` for `responseType`.

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -164,7 +164,7 @@ Audio URLs have a time limit, so they must be downloaded immediately and saved t

 **URL format**:
 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 AUDIO_URL="响应中的audio_url"
 curl -sL "$AUDIO_URL" -o /tmp/minimax-tts.mp3 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
@@ -173,7 +173,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \

 **Hex format**:
 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 HEX_DATA="响应中的hex数据"
 echo -n "$HEX_DATA" | xxd -r -p > /tmp/minimax-tts.mp3 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/minimax-tts/SKILL.zh-CN.md
+++ b/skills/minimax-tts/SKILL.zh-CN.md
@@ -29,7 +29,7 @@
 MiniMax TTS 返回 JSON（包含音频 URL 或 hex 数据），`responseType` 使用 `"json"`。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -101,7 +101,7 @@ MiniMax TTS 返回 JSON，根据请求参数可能返回 URL 或 hex 格式：

 **URL 格式**：
 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 AUDIO_URL="响应中的audio_url"
 curl -sL "$AUDIO_URL" -o /tmp/minimax-tts.mp3 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
@@ -110,7 +110,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \

 **Hex 格式**：
 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 HEX_DATA="响应中的hex数据"
 echo -n "$HEX_DATA" | xxd -r -p > /tmp/minimax-tts.mp3 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/minimax-video-gen/SKILL.md
+++ b/skills/minimax-video-gen/SKILL.md
@@ -102,7 +102,7 @@ MiniMax video generation uses an asynchronous task model:
 ### Step 1: Submit a Text-to-Video Task

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -126,7 +126,7 @@ Extract `data.task_id` from the JSON response.
 ### Step 1 (alternative): Image-to-Video

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -147,7 +147,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 Call once every 10 seconds until `status` is `"Success"` or `"Fail"`. Replace `TASK_ID` with the `task_id` returned in Step 1.

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 TASK_ID="task_id returned from step 1"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
@@ -189,7 +189,7 @@ Polling response (completed):
 Replace `FILE_ID` with the `file_id` from the completed response in Step 2.

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 FILE_ID="file_id returned from step 2"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
@@ -209,7 +209,7 @@ Extract `data.file.download_url` from the response.
 The download URL is valid for 24 hours; you must download immediately and save it to the local media-store.

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 VIDEO_URL="download_url obtained in step 3"
 curl -sL "$VIDEO_URL" -o /tmp/minimax-video.mp4 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/minimax-video-gen/SKILL.zh-CN.md
+++ b/skills/minimax-video-gen/SKILL.zh-CN.md
@@ -39,7 +39,7 @@ MiniMax 视频生成采用异步任务模式：
 ### 第一步：提交文生视频任务

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -63,7 +63,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 ### 第一步（备选）：图生视频

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -84,7 +84,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 每隔 10 秒调用一次，直到 `status` 为 `"Success"` 或 `"Fail"`。将 `TASK_ID` 替换为第一步返回的 `task_id`。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 TASK_ID="第一步返回的task_id"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
@@ -126,7 +126,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 将 `FILE_ID` 替换为第二步完成响应中的 `file_id`。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 FILE_ID="第二步返回的file_id"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
@@ -146,7 +146,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 下载 URL 有 24 小时时效，必须立即下载并保存到本地 media-store。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 VIDEO_URL="第三步获取的download_url"
 curl -sL "$VIDEO_URL" -o /tmp/minimax-video.mp4 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
--- a/skills/nodejs-runtime/SKILL.md
+++ b/skills/nodejs-runtime/SKILL.md
@@ -51,7 +51,7 @@ metadata:
        Use this skill when the user needs to install, upgrade, or troubleshoot Node.js, npm, pnpm, yarn, and JavaScript/TypeScript runtime environments. Covers four-tier fallback strategy: (1) DesireCore HTTP API for in-app installation, (2) DesireCore built-in Volta CLI for Node.js + package manager version management, (3) system package managers (brew/apt/dnf/winget/NodeSource), (4) community nvm/fnm as last resort. Also covers global package management, npm registry/proxy configuration, EACCES permission errors, and PATH troubleshooting. Triggers include: "install node", "node not found", "npm not found", "npm EACCES", "pnpm", "yarn", "volta", "nvm", "fnm", "nodejs version", "package-lock", or any Node.js / npm runtime error. Use cases: the user needs to install Node.js, install npm, pnpm, yarn, configure global packages, resolve EACCES, PATH issues, registry mirror / proxy configuration.
      body: ./SKILL.md
      source_hash: sha256:2b8a00816c65d71c
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -132,7 +132,7 @@ See `../dev-environment-setup/references/probe-snapshot.md` for field definition
 #### L1: HTTP API (→ `references/volta-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"

 # 列出可装版本
@@ -155,8 +155,8 @@ curl -sk -X POST "${BASE}/environment/refresh"
 #### L2: Volta CLI Absolute Path (→ `references/volta-desirecore.md`)

 ```bash
-VOLTA=~/.desirecore/runtime/volta/volta
-export VOLTA_HOME=~/.desirecore/runtime/volta
+VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta
+export VOLTA_HOME=${DESIRECORE_ROOT}/runtime/volta
 export VOLTA_FEATURE_PNPM=1

 "$VOLTA" install node@22
--- a/skills/nodejs-runtime/SKILL.zh-CN.md
+++ b/skills/nodejs-runtime/SKILL.zh-CN.md
@@ -59,7 +59,7 @@ cat /tmp/node-probe.json | jq .
 #### L1：HTTP API（→ `references/volta-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"

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

 ```bash
-VOLTA=~/.desirecore/runtime/volta/volta
-export VOLTA_HOME=~/.desirecore/runtime/volta
+VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta
+export VOLTA_HOME=${DESIRECORE_ROOT}/runtime/volta
 export VOLTA_FEATURE_PNPM=1

 "$VOLTA" install node@22
--- a/skills/nodejs-runtime/references/package-managers.md
+++ b/skills/nodejs-runtime/references/package-managers.md
@@ -12,7 +12,7 @@
 ## 通过 DesireCore Volta 安装

 ```bash
-VOLTA=~/.desirecore/runtime/volta/volta
+VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta
 export VOLTA_FEATURE_PNPM=1

 "$VOLTA" install pnpm@latest
@@ -23,7 +23,7 @@ export VOLTA_FEATURE_PNPM=1
 或 HTTP API：

 ```bash
-BASE="https://127.0.0.1:$(cat ~/.desirecore/agent-service.port)/api/runtime"
+BASE="https://127.0.0.1:$(cat ${DESIRECORE_ROOT}/agent-service.port)/api/runtime"
 curl -sk -X POST "${BASE}/pkg/pnpm/install" -H "Content-Type: application/json" -d '{"version":"latest"}'
 ```

--- a/skills/nodejs-runtime/references/troubleshooting.md
+++ b/skills/nodejs-runtime/references/troubleshooting.md
@@ -14,8 +14,8 @@ export NVM_DIR="$HOME/.nvm"
 node --version

 # 3. Volta 已装但未在 PATH？
-ls ~/.desirecore/runtime/volta/volta 2>/dev/null && \
-  echo "运行 ~/.desirecore/runtime/volta/volta 直接调用，无需 PATH"
+ls ${DESIRECORE_ROOT}/runtime/volta/volta 2>/dev/null && \
+  echo "运行 ${DESIRECORE_ROOT}/runtime/volta/volta 直接调用，无需 PATH"
 ```

 **根治**：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。
--- a/skills/nodejs-runtime/references/volta-desirecore.md
+++ b/skills/nodejs-runtime/references/volta-desirecore.md
@@ -1,15 +1,15 @@
 # DesireCore 内置 Volta（L1 / L2 主路径）

-DesireCore 内置 [Volta](https://volta.sh/) v2.0.2（Rust 实现的 Node.js 工具链管理器）。Volta 二进制随应用打包于 `static/volta/`，运行时位于 `~/.desirecore/runtime/volta/`，**用户无需单独安装**。
+DesireCore 内置 [Volta](https://volta.sh/) v2.0.2（Rust 实现的 Node.js 工具链管理器）。Volta 二进制随应用打包于 `static/volta/`，运行时位于 `${DESIRECORE_ROOT}/runtime/volta/`，**用户无需单独安装**。

-> 与系统 Node.js 完全隔离：Volta 安装的工具位于 `~/.desirecore/runtime/volta/tools/image/`，不修改系统 PATH。
+> 与系统 Node.js 完全隔离：Volta 安装的工具位于 `${DESIRECORE_ROOT}/runtime/volta/tools/image/`，不修改系统 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"
@@ -76,8 +76,8 @@ curl -sk -X POST "${BASE}/environment/refresh"   # 安装结束后刷新
 ### macOS / Linux

 ```bash
-VOLTA=~/.desirecore/runtime/volta/volta
-export VOLTA_HOME=~/.desirecore/runtime/volta
+VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta
+export VOLTA_HOME=${DESIRECORE_ROOT}/runtime/volta
 export VOLTA_FEATURE_PNPM=1
 # export VOLTA_NODE_MIRROR=https://npmmirror.com/mirrors/node   # 中国大陆加速

@@ -123,7 +123,7 @@ $env:VOLTA_FEATURE_PNPM = "1"
 Volta 没有 `volta uninstall node`，直接删目录或用 HTTP API：

 ```bash
-rm -rf ~/.desirecore/runtime/volta/tools/image/node/<version>
+rm -rf ${DESIRECORE_ROOT}/runtime/volta/tools/image/node/<version>
 ```

 或：
--- a/skills/nodejs-runtime/scripts/probe-node.sh
+++ b/skills/nodejs-runtime/scripts/probe-node.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
@@ -46,7 +46,7 @@ SYS_NODE=$(detect_tool node)
 SYS_NPM=$(detect_tool npm)

 # ── DesireCore Volta ────────────────────
-VOLTA_BIN="$HOME/.desirecore/runtime/volta/volta"
+VOLTA_BIN="${DESIRECORE_ROOT}/runtime/volta/volta"
 VOLTA_PATH=""
 VOLTA_VERSION=""
 if [ -x "$VOLTA_BIN" ]; then
@@ -55,7 +55,7 @@ if [ -x "$VOLTA_BIN" ]; then
 fi

 # Volta 已装工具（直接读 image 目录最稳）
-VOLTA_IMG="$HOME/.desirecore/runtime/volta/tools/image"
+VOLTA_IMG="${DESIRECORE_ROOT}/runtime/volta/tools/image"
 list_dir() {
  local dir="$1"
  if [ -d "$dir" ]; then
--- 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/,$//')
--- a/skills/s3-storage-operations/SKILL.md
+++ b/skills/s3-storage-operations/SKILL.md
@@ -37,7 +37,7 @@ metadata:
        Operate S3-compatible object storage (upload, download, list, delete) via the DesireCore HTTP API. Use when the user requests file upload/download/sharing, needs a download link, or when workflow outputs need persistent storage and distribution.
      body: ./SKILL.md
      source_hash: sha256:6ea8e1375f12de72
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -95,7 +95,7 @@ Core principle: the user's S3 connection is pre-configured under **Resources →
 ### Port Discovery

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 ```

 ### API Endpoints
@@ -111,7 +111,7 @@ PORT=$(cat ~/.desirecore/agent-service.port)
 ### Quick Reference

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)

 # 列出连接
 curl -k "https://127.0.0.1:${PORT}/api/s3/connections"
@@ -163,4 +163,4 @@ Error codes: `NO_CONNECTION` | `NOT_FOUND` | `UPLOAD_FAILED` | `DOWNLOAD_FAILED`
 - **S3 Client** — `lib/agent-service/s3-client.ts`: AWS V4 signing, CRUD operations
 - **Connection Resolver** — `lib/agent-service/s3-connection-resolver.ts`: automatic connection selection
 - **Global Skill Sync** — `lib/agent-service/global-skill-sync.ts`: writes the Global Skill on startup
- **Port Discovery** — `~/.desirecore/agent-service.port`: port discovery file
+- **Port Discovery** — `${DESIRECORE_ROOT}/agent-service.port`: port discovery file
--- a/skills/s3-storage-operations/SKILL.zh-CN.md
+++ b/skills/s3-storage-operations/SKILL.zh-CN.md
@@ -30,7 +30,7 @@ s3-storage-operations 是一个**工具技能（Tool-Skill）**，通过 DesireC
 ### 端口发现

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 ```

 ### API 端点
@@ -46,7 +46,7 @@ PORT=$(cat ~/.desirecore/agent-service.port)
 ### 快速参考

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)

 # 列出连接
 curl -k "https://127.0.0.1:${PORT}/api/s3/connections"
@@ -98,4 +98,4 @@ curl -k -X DELETE "https://127.0.0.1:${PORT}/api/s3/objects" \
 - **S3 Client** — `lib/agent-service/s3-client.ts`: AWS V4 签名，CRUD 操作
 - **Connection Resolver** — `lib/agent-service/s3-connection-resolver.ts`: 自动选择连接
 - **Global Skill Sync** — `lib/agent-service/global-skill-sync.ts`: 启动时写入 Global Skill
- **Port Discovery** — `~/.desirecore/agent-service.port`: 端口发现文件
+- **Port Discovery** — `${DESIRECORE_ROOT}/agent-service.port`: 端口发现文件
--- a/skills/skill-creator/SKILL.md
+++ b/skills/skill-creator/SKILL.md
@@ -359,7 +359,7 @@ Validates SKILL.md format, the legality of frontmatter fields, and the directory
 **Option A: Install via API (recommended; requires the Agent Service to be running)**

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port 2>/dev/null)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port 2>/dev/null)

 # Install as a global Skill (visible to all Agents)
 curl -k -X POST "https://127.0.0.1:${PORT}/api/skills" \
@@ -376,10 +376,10 @@ curl -k -X POST "https://127.0.0.1:${PORT}/api/agents/<agentId>/skills" \

 ```bash
 # Global Skill
-cp -r path/to/skill-name ~/.desirecore/skills/
+cp -r path/to/skill-name ${DESIRECORE_ROOT}/skills/

 # Agent-scoped Skill
-cp -r path/to/skill-name ~/.desirecore/agents/<agentId>/skills/
+cp -r path/to/skill-name ${DESIRECORE_ROOT}/agents/<agentId>/skills/
 ```

 **Option C: Package as a .skill file (Claude Code compatible)**
@@ -409,7 +409,7 @@ Skills exist at three scope levels, listed from highest priority to lowest:
 | Priority | Scope | Path | Visibility |
 |--------|--------|------|---------|
 | Highest | Project | `.claude/skills/` | All Agents in the current project |
-| Medium | Agent | `~/.desirecore/agents/{agentId}/skills/` | Only that Agent |
-| Lowest | Global | `~/.desirecore/skills/` | All Agents |
+| Medium | Agent | `${DESIRECORE_ROOT}/agents/{agentId}/skills/` | Only that Agent |
+| Lowest | Global | `${DESIRECORE_ROOT}/skills/` | All Agents |

 Skills with the same name override each other by priority—a higher-priority Skill shadows a lower-priority one with the same name.
--- a/skills/skill-creator/SKILL.zh-CN.md
+++ b/skills/skill-creator/SKILL.zh-CN.md
@@ -299,7 +299,7 @@ scripts/quick_validate.py <path/to/skill-folder>
 **方式 A：通过 API 安装（推荐，需 Agent Service 运行中）**

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port 2>/dev/null)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port 2>/dev/null)

 # 安装为全局技能（所有 Agent 可见）
 curl -k -X POST "https://127.0.0.1:${PORT}/api/skills" \
@@ -316,10 +316,10 @@ curl -k -X POST "https://127.0.0.1:${PORT}/api/agents/<agentId>/skills" \

 ```bash
 # 全局技能
-cp -r path/to/skill-name ~/.desirecore/skills/
+cp -r path/to/skill-name ${DESIRECORE_ROOT}/skills/

 # Agent 级技能
-cp -r path/to/skill-name ~/.desirecore/agents/<agentId>/skills/
+cp -r path/to/skill-name ${DESIRECORE_ROOT}/agents/<agentId>/skills/
 ```

 **方式 C：打包为 .skill 文件（Claude Code 兼容）**
@@ -349,7 +349,7 @@ scripts/package_skill.py <path/to/skill-folder>
 | 优先级 | 作用域 | 路径 | 可见范围 |
 |--------|--------|------|---------|
 | 最高 | Project | `.claude/skills/` | 当前项目所有 Agent |
-| 中 | Agent | `~/.desirecore/agents/{agentId}/skills/` | 仅该 Agent |
-| 最低 | Global | `~/.desirecore/skills/` | 所有 Agent |
+| 中 | Agent | `${DESIRECORE_ROOT}/agents/{agentId}/skills/` | 仅该 Agent |
+| 最低 | Global | `${DESIRECORE_ROOT}/skills/` | 所有 Agent |

 同名技能按优先级覆盖——高优先级的技能会遮蔽低优先级的同名技能。
--- a/skills/skill-creator/scripts/init_skill.py
+++ b/skills/skill-creator/scripts/init_skill.py
@@ -6,8 +6,8 @@ Usage:
    init_skill.py <skill-name> --path <path> [--format basic|desirecore]

 Examples:
-    init_skill.py my-new-skill --path ~/.desirecore/skills
-    init_skill.py my-api-helper --path ~/.desirecore/skills --format basic
+    init_skill.py my-new-skill --path ${DESIRECORE_ROOT}/skills
+    init_skill.py my-api-helper --path ${DESIRECORE_ROOT}/skills --format basic
 """

 import sys
@@ -230,8 +230,8 @@ def main():
    parser = argparse.ArgumentParser(
        description='Initialize a new skill from template',
        epilog='Examples:\n'
-               '  init_skill.py my-new-skill --path ~/.desirecore/skills\n'
-               '  init_skill.py my-api-helper --path ~/.desirecore/skills --format basic',
+               '  init_skill.py my-new-skill --path ${DESIRECORE_ROOT}/skills\n'
+               '  init_skill.py my-api-helper --path ${DESIRECORE_ROOT}/skills --format basic',
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument('skill_name', help='Skill name (kebab-case, max 64 chars)')
--- a/skills/skill-creator/scripts/package_skill.py
+++ b/skills/skill-creator/scripts/package_skill.py
@@ -127,9 +127,9 @@ def install_skill(skill_path, scope='global', agent_id=None):
        print("❌ Error: Agent Service not running (port file not found)")
        print("\nFallback — install via file system:")
        if scope == 'agent' and agent_id:
-            print(f"  cp -r {skill_path} ~/.desirecore/agents/{agent_id}/skills/")
+            print(f"  cp -r {skill_path} ${DESIRECORE_ROOT}/agents/{agent_id}/skills/")
        else:
-            print(f"  cp -r {skill_path} ~/.desirecore/skills/")
+            print(f"  cp -r {skill_path} ${DESIRECORE_ROOT}/skills/")
        return None

    content = skill_md.read_text()
--- a/skills/update-agent/CHANGELOG.md
+++ b/skills/update-agent/CHANGELOG.md
@@ -4,7 +4,7 @@

 - **Breaking**：从 HTTP API 迁移到 AgentFS 直接文件操作
 - 移除所有 HTTP API 端点引用（PUT persona/principles/files）
- 变更应用改为直接读写 `~/.desirecore/agents/<agentId>/` 下的文件
+- 变更应用改为直接读写 `${DESIRECORE_ROOT}/agents/<agentId>/` 下的文件
 - 回滚流程改用 git log/show 命令查看历史版本
 - 错误处理改为文件系统错误（文件不存在、权限不足等）

--- a/skills/update-agent/SKILL.md
+++ b/skills/update-agent/SKILL.md
@@ -36,7 +36,7 @@ metadata:
        Safely update an existing Agent's config, persona, principles, skills, and memory, producing reviewable diffs that are applied and committed only after confirmation. Use when the user asks to modify Agent behavior, install/uninstall skills, adjust config, roll back changes, or revise rules.
      body: ./SKILL.md
      source_hash: sha256:a0fecd84f92204bd
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-03'
 market:
  icon: >-
@@ -200,7 +200,7 @@ diff_metadata:

 Apply the change by reading and writing files directly through AgentFS. **Do not call HTTP APIs, and do not operate Git directly** (version management is handled automatically by the backend).

-**AgentFS root directory**: `~/.desirecore/agents/<agentId>/`
+**AgentFS root directory**: `${DESIRECORE_ROOT}/agents/<agentId>/`

 **Read file**: Use the `cat` command to read the current contents of the target file.

@@ -231,7 +231,7 @@ After a successful change, present a user-friendly receipt (do not expose intern

 ```bash
 # 查看版本历史
-cd ~/.desirecore/agents/<agentId>
+cd ${DESIRECORE_ROOT}/agents/<agentId>
 git log --oneline -10

 # 查看某个版本的文件内容
@@ -246,12 +246,12 @@ git show <commit>:persona.md

 | User Intent                  | Target File     | AgentFS Path                                   |
 | ---------------------------- | --------------- | ---------------------------------------------- |
-| Modify personality/style     | `persona.md`    | `~/.desirecore/agents/<agentId>/persona.md`    |
-| Modify behavioral rules      | `principles.md` | `~/.desirecore/agents/<agentId>/principles.md` |
-| Install/uninstall skills     | `skills/`       | `~/.desirecore/agents/<agentId>/skills/`       |
-| Modify tools config          | `tools/`        | `~/.desirecore/agents/<agentId>/tools/`        |
-| Add memory                   | `memory/`       | `~/.desirecore/agents/<agentId>/memory/`       |
-| Modify runtime config        | `agent.json`    | `~/.desirecore/agents/<agentId>/agent.json`    |
+| Modify personality/style     | `persona.md`    | `${DESIRECORE_ROOT}/agents/<agentId>/persona.md`    |
+| Modify behavioral rules      | `principles.md` | `${DESIRECORE_ROOT}/agents/<agentId>/principles.md` |
+| Install/uninstall skills     | `skills/`       | `${DESIRECORE_ROOT}/agents/<agentId>/skills/`       |
+| Modify tools config          | `tools/`        | `${DESIRECORE_ROOT}/agents/<agentId>/tools/`        |
+| Add memory                   | `memory/`       | `${DESIRECORE_ROOT}/agents/<agentId>/memory/`       |
+| Modify runtime config        | `agent.json`    | `${DESIRECORE_ROOT}/agents/<agentId>/agent.json`    |

 ### Error Handling

@@ -285,7 +285,7 @@ git show <commit>:persona.md

 ```bash
 # 1. 读取当前 persona.md
-cat ~/.desirecore/agents/legal-assistant/persona.md
+cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md

 # 输出示例:
 # # 法律顾问小助手
@@ -304,7 +304,7 @@ cat ~/.desirecore/agents/legal-assistant/persona.md
 # 3. 用户确认后，直接编辑文件，将 Personality 和 Communication Style 修改为目标值

 # 4. 验证写入结果
-cat ~/.desirecore/agents/legal-assistant/persona.md
+cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md
 ```

 ---
--- a/skills/update-agent/SKILL.zh-CN.md
+++ b/skills/update-agent/SKILL.zh-CN.md
@@ -140,7 +140,7 @@ diff_metadata:

 通过 AgentFS 直接读写文件完成变更。**不要调用 HTTP API，不要直接操作 Git**（版本管理由后端自动处理）。

-**AgentFS 根目录**：`~/.desirecore/agents/<agentId>/`
+**AgentFS 根目录**：`${DESIRECORE_ROOT}/agents/<agentId>/`

 **读取文件**：使用 `cat` 命令读取目标文件当前内容。

@@ -171,7 +171,7 @@ diff_metadata:

 ```bash
 # 查看版本历史
-cd ~/.desirecore/agents/<agentId>
+cd ${DESIRECORE_ROOT}/agents/<agentId>
 git log --oneline -10

 # 查看某个版本的文件内容
@@ -186,12 +186,12 @@ git show <commit>:persona.md

 | 用户意图       | 目标文件        | AgentFS 路径                                   |
 | -------------- | --------------- | ---------------------------------------------- |
-| 修改性格/风格  | `persona.md`    | `~/.desirecore/agents/<agentId>/persona.md`    |
-| 修改行为规则   | `principles.md` | `~/.desirecore/agents/<agentId>/principles.md` |
-| 安装/卸载技能  | `skills/`       | `~/.desirecore/agents/<agentId>/skills/`       |
-| 修改工具配置   | `tools/`        | `~/.desirecore/agents/<agentId>/tools/`        |
-| 添加记忆       | `memory/`       | `~/.desirecore/agents/<agentId>/memory/`       |
-| 修改运行时配置 | `agent.json`    | `~/.desirecore/agents/<agentId>/agent.json`    |
+| 修改性格/风格  | `persona.md`    | `${DESIRECORE_ROOT}/agents/<agentId>/persona.md`    |
+| 修改行为规则   | `principles.md` | `${DESIRECORE_ROOT}/agents/<agentId>/principles.md` |
+| 安装/卸载技能  | `skills/`       | `${DESIRECORE_ROOT}/agents/<agentId>/skills/`       |
+| 修改工具配置   | `tools/`        | `${DESIRECORE_ROOT}/agents/<agentId>/tools/`        |
+| 添加记忆       | `memory/`       | `${DESIRECORE_ROOT}/agents/<agentId>/memory/`       |
+| 修改运行时配置 | `agent.json`    | `${DESIRECORE_ROOT}/agents/<agentId>/agent.json`    |

 ### 错误处理

@@ -225,7 +225,7 @@ git show <commit>:persona.md

 ```bash
 # 1. 读取当前 persona.md
-cat ~/.desirecore/agents/legal-assistant/persona.md
+cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md

 # 输出示例:
 # # 法律顾问小助手
@@ -244,7 +244,7 @@ cat ~/.desirecore/agents/legal-assistant/persona.md
 # 3. 用户确认后，直接编辑文件，将 Personality 和 Communication Style 修改为目标值

 # 4. 验证写入结果
-cat ~/.desirecore/agents/legal-assistant/persona.md
+cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md
 ```

 ---
--- a/skills/web-access/SKILL.md
+++ b/skills/web-access/SKILL.md
@@ -156,14 +156,14 @@ Launch a dedicated Chrome instance with remote debugging enabled:
 ```bash
 /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/.desirecore/chrome-profile"
+  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
 ```

 **Linux**:
 ```bash
 google-chrome \
  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/.desirecore/chrome-profile"
+  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
 ```

 **Windows (PowerShell)**:
@@ -359,7 +359,7 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:
 | `BrowserNavigate({ target, url })` | Navigate an existing tab |
 | `BrowserEval({ target, expression })` | Run JS in the tab to extract structured data |
 | `BrowserClick({ target, selector, mode: 'real-mouse' })` | Real-mouse mode for anti-bot-strict sites |
-| `BrowserScreenshot({ target })` | Saved under ~/.desirecore/screenshots/ |
+| `BrowserScreenshot({ target })` | Saved under ${DESIRECORE_ROOT}/screenshots/ |
 | `BrowserScroll({ target, direction: 'bottom' })` | Trigger lazy loading |
 | `BrowserSetFiles({ target, selector, files })` | Upload local files (**user confirmation required**) |
 | `BrowserCloseTab({ target })` | Clean up temporary tabs at task end |
--- a/skills/web-access/SKILL.zh-CN.md
+++ b/skills/web-access/SKILL.zh-CN.md
@@ -70,14 +70,14 @@ Launch a dedicated Chrome instance with remote debugging enabled:
 ```bash
 /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/.desirecore/chrome-profile"
+  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
 ```

 **Linux**:
 ```bash
 google-chrome \
  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/.desirecore/chrome-profile"
+  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
 ```

 **Windows (PowerShell)**:
@@ -273,7 +273,7 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:
 | `BrowserNavigate({ target, url })` | 在指定 tab 跳转 |
 | `BrowserEval({ target, expression })` | 在 tab 内跑 JS，提取结构化数据 |
 | `BrowserClick({ target, selector, mode: 'real-mouse' })` | 反爬严格站点用真实鼠标事件 |
-| `BrowserScreenshot({ target })` | 写入 ~/.desirecore/screenshots/ |
+| `BrowserScreenshot({ target })` | 写入 ${DESIRECORE_ROOT}/screenshots/ |
 | `BrowserScroll({ target, direction: 'bottom' })` | 触发懒加载 |
 | `BrowserSetFiles({ target, selector, files })` | 上传本地文件（**需用户确认**） |
 | `BrowserCloseTab({ target })` | 任务收尾清理临时 tab |
--- a/skills/web-access/references/browser-tools.md
+++ b/skills/web-access/references/browser-tools.md
@@ -76,7 +76,7 @@ BrowserClick:
 ```yaml
 BrowserScreenshot:
  target: <targetId>
-  filename: 自定义文件名.png  # 可选；写入 ~/.desirecore/screenshots/
+  filename: 自定义文件名.png  # 可选；写入 ${DESIRECORE_ROOT}/screenshots/
 ```

 ### BrowserScroll
--- a/skills/web-access/references/cdp-browser.md
+++ b/skills/web-access/references/cdp-browser.md
@@ -280,7 +280,7 @@ print(clean_md)

 Chrome is not running with remote debugging. Tell the user:
 > "请先用下面的命令启动 Chrome：
-> `/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222 --user-data-dir=\"$HOME/.desirecore/chrome-profile\"`
+> `/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222 --user-data-dir=\"${DESIRECORE_ROOT}/chrome-profile\"`
 > 然后手动登录需要抓取的网站，再让我继续。"

 ### `browser.contexts[0]` is empty
@@ -316,7 +316,7 @@ The selector is stale — the site updated its DOM. Dump `page.content()[:5000]`
 - **Never log or print cookies** from `context.cookies()` even during debugging
 - **Never extract and store** the user's session tokens to files
 - **Never use the CDP session** to perform writes (post, comment, like) unless the user explicitly requested it
- The `~/.desirecore/chrome-profile` directory contains the user's credentials — treat it as sensitive
+- The `${DESIRECORE_ROOT}/chrome-profile` directory contains the user's credentials — treat it as sensitive
 - If the user asks to "log in automatically", refuse and explain they must log in manually in the Chrome window; the skill only reads already-authenticated sessions

 ---
--- a/skills/workflow/SKILL.md
+++ b/skills/workflow/SKILL.md
@@ -38,7 +38,7 @@ metadata:
        Guides the Agent to design, edit, test, and execute Workflow workflows. Use when the user asks to create a workflow, orchestrate multi-step automation, design an approval pipeline, or turn repetitive multi-node tasks into a reusable DSL.
      body: ./SKILL.md
      source_hash: sha256:aa197c62ae8a33d7
-      translated_by: ai:claude-opus-4-7
+      translated_by: human
      translated_at: '2026-05-04'
 market:
  icon: >-
@@ -147,7 +147,7 @@ workflow is a **Procedural Skill** that empowers the Agent to orchestrate multi-
 **DSL file location**:

 ```
-~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
 ```

 Where `wf_id` uses a `wf_` prefix + snake_case, e.g. `wf_legal_review`, `wf_daily_report`.
@@ -539,7 +539,7 @@ All dynamic values in the DSL are uniformly referenced using the `{{}}` template

 A workflow can reference user-preconfigured secrets via `{{secrets.keyName}}` for scenarios such as API calls.

- Secrets are preconfigured by the user in `~/.desirecore/config/secrets.json`
+- Secrets are preconfigured by the user in `${DESIRECORE_ROOT}/config/secrets.json`
 - The engine automatically resolves `{{secrets.*}}` at runtime, replacing them with the actual values
 - Secrets are resolved only during the execution phase; their actual values are not exposed during validation or dry-run

@@ -563,7 +563,7 @@ Use the `WorkflowValidate` tool to validate the structure and reference integrit
 ```
 Tool: WorkflowValidate
 Parameters:
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
 ```

 **What is validated**:
@@ -587,7 +587,7 @@ Use the `WorkflowTest` tool to perform a simulated execution (dry-run) without a
 ```
 Tool: WorkflowTest
 Parameters:
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
  params:                      # Optional, used to simulate trigger parameters
    filePath: /path/to/input.md
 ```
@@ -610,7 +610,7 @@ Use the `WorkflowRun` tool to start the workflow.
 ```
 Tool: WorkflowRun
 Parameters:
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
  params:                      # Optional, passed in as the {{trigger.key}} context
    filePath: /path/to/input.md
 ```
--- a/skills/workflow/SKILL.zh-CN.md
+++ b/skills/workflow/SKILL.zh-CN.md
@@ -72,7 +72,7 @@ workflow 是一个**流程型技能（Procedural Skill）**，赋予 Agent 编
 **DSL 文件位置**：

 ```
-~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
 ```

 其中 `wf_id` 使用 `wf_` 前缀 + snake_case，如 `wf_legal_review`、`wf_daily_report`。
@@ -464,7 +464,7 @@ DSL 中所有动态值统一使用 `{{}}` 模板语法引用：

 工作流可通过 `{{secrets.keyName}}` 引用用户预配置的密钥，用于 API 调用等场景。

- Secrets 由用户在 `~/.desirecore/config/secrets.json` 中预配置
+- Secrets 由用户在 `${DESIRECORE_ROOT}/config/secrets.json` 中预配置
 - 引擎在运行时自动解析 `{{secrets.*}}`，将其替换为实际值
 - Secrets 仅在执行阶段解析，校验和干跑阶段不会暴露实际值

@@ -488,7 +488,7 @@ config:
 ```
 工具：WorkflowValidate
 参数：
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
 ```

 **校验内容**：
@@ -512,7 +512,7 @@ config:
 ```
 工具：WorkflowTest
 参数：
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
  params:                      # 可选，用于模拟 trigger 参数
    filePath: /path/to/input.md
 ```
@@ -535,7 +535,7 @@ config:
 ```
 工具：WorkflowRun
 参数：
-  path: ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+  path: ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
  params:                      # 可选，作为 {{trigger.key}} 上下文传入
    filePath: /path/to/input.md
 ```
--- a/skills/workflow/templates/workflow.dsl.yaml
+++ b/skills/workflow/templates/workflow.dsl.yaml
@@ -4,7 +4,7 @@
 #       五种基座节点的完整 DSL 结构。Agent 可参考此模板构建工作流。
 #
 # 使用方式：
-#   1. 复制此模板到 ~/.desirecore/workflows/<wf_id>/workflow.dsl.yaml
+#   1. 复制此模板到 ${DESIRECORE_ROOT}/workflows/<wf_id>/workflow.dsl.yaml
 #   2. 修改 id、name、nodes、flow 等字段
 #   3. 用 WorkflowValidate 工具校验
 #   4. 用 WorkflowTest 工具干跑测试
--- a/skills/xiaomi-tts/SKILL.md
+++ b/skills/xiaomi-tts/SKILL.md
@@ -118,7 +118,7 @@ Generate speech via media-proxy's `/chat/completions` endpoint.
 **Important**: `messages` must use the `assistant` role (not `user`); the text to synthesize goes in the assistant message's content.

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -173,7 +173,7 @@ The audio comes back as base64; decode it and save to the local media-store.
 **Recommended approach** (write the full response to a file first to avoid overlong shell arguments):

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 # Save the full request and response to a file
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
--- a/skills/xiaomi-tts/SKILL.zh-CN.md
+++ b/skills/xiaomi-tts/SKILL.zh-CN.md
@@ -54,7 +54,7 @@
 **重要**：messages 必须使用 `assistant` role（不是 user），要合成的文本放在 assistant 消息的 content 中。

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
@@ -109,7 +109,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 **推荐方式**（先保存完整响应到文件，避免 shell 参数过长）：

 ```bash
-PORT=$(cat ~/.desirecore/agent-service.port)
+PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 # 将完整请求和响应保存到文件
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \