feat: 拆分 environment-setup 为 Python/Node.js 运行时双核心 + 父级路由

新增双核心 skill（深度集成 DesireCore Hatch/Volta + HTTP API + Socket.IO）： - python-runtime v1.0.1：Python 运行时管理 · 四级降级：HTTP API → Hatch CLI 绝对路径 → 系统包管理器 → pyenv · references：hatch-desirecore / pyenv-fallback / virtualenv / troubleshooting · scripts/probe-python.sh：输出 JSON 快照供 Claude 解析决策 - nodejs-runtime v1.0.1：Node.js 运行时管理 · 四级降级：HTTP API → Volta CLI → 系统包管理器/NodeSource → nvm/fnm · references：volta-desirecore / nvm-fallback / package-managers / troubleshooting · scripts/probe-node.sh：输出 JSON 快照（含 volta_tools / package_json_volta 等） environment-setup → dev-environment-setup v2.0.1（重命名 + 重写为 router）： - 从 1380 行手册瘦身为 ~150 行索引 - 仅负责容器（Docker/Podman）/ WSL2 / 办公依赖速查 / 系统工具 - references/desirecore-runtime.md 沉淀 Hatch/Volta 路径表 + HTTP API 速查 + Socket.IO 事件契约，作为两个核心 skill 的共享底座 - references/decision-tree.md 定义四级降级决策树 - scripts/probe.sh + probe.ps1 系统级 JSON 探测三个 SKILL.md 的 L0 改为场景驱动结构（何时使用 / 何时不要用 / 怎么做），让 AI 凭名字与 L0 即可判断匹配场景。注册更新： - builtin-skills.json：新增 python-runtime / nodejs-runtime / dev-environment-setup （原 environment-setup 移除），按字母序，共 21 个 skill - manifest.json：totalSkills 19→21，lastUpdated 2026-05-02 下游同步： - docx / pdf / xlsx / pptx 中的环境引用从 environment-setup 拆分为 python-runtime / nodejs-runtime / dev-environment-setup 三向指引 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-06 08:10:48 +08:00 · 2026-05-02 13:30:23 +08:00
parent 5472359814
commit 1a50969b93
29 changed files with 3310 additions and 1386 deletions
--- a/skills/dev-environment-setup/references/probe-snapshot.md
+++ b/skills/dev-environment-setup/references/probe-snapshot.md
@@ -0,0 +1,118 @@
+# 环境探测 JSON 协议
+
+`probe.sh` / `probe.ps1` / `probe-python.sh` / `probe-node.sh` 输出统一 JSON。Skill 解析 JSON 后再决策，避免逐条 grep。
+
+## 通用字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `platform` | `"darwin" \| "linux" \| "win32"` | 操作系统标识 |
+| `arch` | `"arm64" \| "x64" \| ...` | CPU 架构 |
+| `desirecore_api` | `string` | 探测到的 DesireCore agent-service URL，不可达时为 `""` |
+| `desirecore_port_file` | `string` | `~/.desirecore/agent-service.port` 是否存在 |
+
+## probe.sh / probe.ps1（父级 dev-environment-setup）
+
+输出系统级总览：
+
+```json
+{
+  "platform": "darwin",
+  "arch": "arm64",
+  "desirecore_api": "https://127.0.0.1:38291",
+  "desirecore_port_file": true,
+  "tools": {
+    "python3": { "available": true, "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
+    "pip3":    { "available": true, "path": "/opt/homebrew/bin/pip3",    "version": "24.0" },
+    "node":    { "available": true, "path": "/opt/homebrew/bin/node",    "version": "22.4.1" },
+    "npm":     { "available": true, "path": "/opt/homebrew/bin/npm",     "version": "10.8.1" },
+    "docker":  { "available": false },
+    "podman":  { "available": false },
+    "git":     { "available": true, "path": "/usr/bin/git", "version": "2.43.0" }
+  },
+  "wsl": null
+}
+```
+
+Windows 上 `wsl` 字段值类似 `{ "installed": true, "version": "2", "defaultDistro": "Ubuntu" }`。
+
+## probe-python.sh（python-runtime 专用）
+
+```json
+{
+  "platform": "darwin",
+  "arch": "arm64",
+  "desirecore_api": "https://127.0.0.1:38291",
+  "system_python": { "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
+  "system_pip": { "path": "/opt/homebrew/bin/pip3", "version": "24.0" },
+  "hatch_path": "/Users/wangyi/.desirecore/runtime/hatch/hatch",
+  "hatch_version": "1.16.5",
+  "hatch_versions": ["3.11", "3.12"],
+  "active_venv": "/Users/wangyi/proj/.venv",
+  "pep668": false,
+  "pyenv_path": "",
+  "conda_path": ""
+}
+```
+
+字段语义：
+- `hatch_path` 空字符串表示二进制不存在
+- `hatch_versions` 是 `~/.desirecore/runtime/hatch/local/` 下的目录列表（即已通过 Hatch 安装的 Python 版本）
+- `active_venv` 取自 `$VIRTUAL_ENV` 环境变量
+- `pep668` 检测 `/usr/lib/python*/EXTERNALLY-MANAGED` 是否存在（Debian 12+/Ubuntu 23.04+ 启用）
+
+## probe-node.sh（nodejs-runtime 专用）
+
+```json
+{
+  "platform": "darwin",
+  "arch": "arm64",
+  "desirecore_api": "https://127.0.0.1:38291",
+  "system_node": { "path": "/opt/homebrew/bin/node", "version": "22.4.1" },
+  "system_npm":  { "path": "/opt/homebrew/bin/npm",  "version": "10.8.1" },
+  "volta_path": "/Users/wangyi/.desirecore/runtime/volta/volta",
+  "volta_version": "2.0.2",
+  "volta_tools": {
+    "node": ["22.4.1"],
+    "pnpm": ["9.5.0"],
+    "yarn": [],
+    "npm":  []
+  },
+  "package_json_volta": null,
+  "nvm_path": "",
+  "fnm_path": "",
+  "registry": "https://registry.npmmirror.com/",
+  "proxy": ""
+}
+```
+
+字段语义：
+- `volta_tools` 来自 `<volta> list --format=plain`，按工具分类
+- `package_json_volta` 若当前目录存在 `package.json` 且其中有 `"volta"` 字段，填入对象；否则 `null`
+- `registry` / `proxy` 来自 `npm config get registry` / `npm config get https-proxy`
+
+## 设计约定
+
+1. **JSON 必合法**：缺字段也保留键并赋空字符串/`null`，避免 Claude 解析失败。
+2. **不阻塞**：每个外部命令都加 `2>/dev/null`，失败用空值，不让脚本中途退出。
+3. **超时控制**：HTTP 探测 0.5s 超时；CLI 调用最长 5s。
+4. **跨平台**：`probe.sh` / `probe-python.sh` / `probe-node.sh` 共用 POSIX 子集；Windows 同等功能由 `probe.ps1` 提供（仅父级提供，python/nodejs 子 skill 可由 PowerShell 直接 invoke 父级或自行实现）。
+5. **路径展开**：所有 `~` 在 JSON 中展开为绝对路径，避免下游解析歧义。
+
+## 调用约定
+
+```bash
+SNAPSHOT=$(bash skills/python-runtime/scripts/probe-python.sh)
+echo "$SNAPSHOT" | jq .
+
+# 关键字段判定
+HATCH=$(echo "$SNAPSHOT" | jq -r .hatch_path)
+[ -n "$HATCH" ] && [ "$HATCH" != "null" ] && echo "Hatch 可用"
+```
+
+PowerShell 等价：
+
+```powershell
+$snapshot = & "$PWD\skills\dev-environment-setup\scripts\probe.ps1" | ConvertFrom-Json
+if ($snapshot.tools.node.available) { ... }
+```