mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 09:10:41 +08:00
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>
This commit is contained in:
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 环境管理四级降级决策树
|
||||
|
||||
`python-runtime` 与 `nodejs-runtime` 在执行任何安装/版本切换前必须按本决策树选择路径。
|
||||
|
||||
## 总体流程
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ 执行 probe 脚本 │
|
||||
└─────────┬────────┘
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ desirecore_api 字段非空？ │
|
||||
└────────┬───────────────┬─────┘
|
||||
是 │ │ 否
|
||||
▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ L1：HTTP API 路径 │ │ hatch_path / │
|
||||
└────────┬─────────┘ │ volta_path 非空？ │
|
||||
│ └────────┬──┬──────┘
|
||||
失败/超时 是 │ │ 否
|
||||
▼ ▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ L2：DesireCore CLI │ │ L3：系统包管理器 │
|
||||
└────────┬─────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
二进制损坏 / 安装失败 失败/不可用
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ L4：社区方案（pyenv / nvm / fnm / conda）│
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## L1：DesireCore HTTP API（最高优先级）
|
||||
|
||||
**触发条件**
|
||||
|
||||
- `~/.desirecore/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)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
|
||||
# 1. 拉取快照
|
||||
curl -sk "${BASE}/environment"
|
||||
|
||||
# 2. 触发安装（异步）
|
||||
curl -sk -X POST "${BASE}/python/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"3.12"}'
|
||||
|
||||
# 3. 订阅 runtime:terminal / runtime:complete 事件展示日志
|
||||
```
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- HTTP 状态码 ≥ 500 或 502（远端镜像不可用，详见 runtime-env-routes.ts 130/162 行）
|
||||
- `runtime:complete` 事件 `success: false`
|
||||
- Socket.IO 连接断开后超过 30 秒未收到 `runtime:complete`
|
||||
|
||||
**切换提示**：API 失败立即降级到 L2 CLI，不要重试同一接口（可能是镜像被墙）。
|
||||
|
||||
## L2：DesireCore 内置 CLI（绝对路径）
|
||||
|
||||
**触发条件**
|
||||
|
||||
- API 不可达或失败
|
||||
- probe 脚本中 `hatch_path` / `volta_path` 字段非空（即二进制存在）
|
||||
|
||||
**典型操作（macOS / Linux）**
|
||||
|
||||
```bash
|
||||
HATCH=~/.desirecore/runtime/hatch/hatch
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
|
||||
export HATCH_HOME=~/.desirecore/runtime/hatch
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
|
||||
"$HATCH" python install 3.12
|
||||
"$VOLTA" install node@22
|
||||
```
|
||||
|
||||
**典型操作（Windows PowerShell）**
|
||||
|
||||
```powershell
|
||||
$Hatch = "$env:USERPROFILE\.desirecore\runtime\hatch\hatch.exe"
|
||||
$Volta = "$env:USERPROFILE\.desirecore\runtime\volta\volta.exe"
|
||||
|
||||
$env:HATCH_HOME = "$env:USERPROFILE\.desirecore\runtime\hatch"
|
||||
$env:VOLTA_HOME = "$env:USERPROFILE\.desirecore\runtime\volta"
|
||||
|
||||
& $Hatch python install 3.12
|
||||
& $Volta install node@22
|
||||
```
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- exit code ≠ 0
|
||||
- stderr 包含 `network`、`timeout`、`ENOTFOUND`、`failed to fetch`
|
||||
- 可执行文件被反病毒软件隔离（macOS Gatekeeper / Windows Defender）
|
||||
|
||||
**切换提示**：失败后才考虑 L3，不要在 L2 内重试。
|
||||
|
||||
## L3：系统包管理器
|
||||
|
||||
**触发条件**：DesireCore 二进制全部缺失，或用户明确要求"系统级"安装。
|
||||
|
||||
| 平台 | Python | Node.js |
|
||||
|------|--------|---------|
|
||||
| macOS | `brew install python3` | `brew install node` |
|
||||
| Debian/Ubuntu | `sudo apt install python3 python3-pip python3-venv` | NodeSource 仓库或 `sudo apt install nodejs npm` |
|
||||
| Fedora/RHEL | `sudo dnf install python3 python3-pip` | `sudo dnf install nodejs` |
|
||||
| Arch | `sudo pacman -S python python-pip` | `sudo pacman -S nodejs npm` |
|
||||
| Windows | `winget install Python.Python.3` | `winget install OpenJS.NodeJS.LTS` |
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- `command not found`（包管理器自身缺失，如 `brew` 未装）
|
||||
- PEP 668 报错（Linux 新版发行版 `pip install` 全局被拒）→ 见 python-runtime troubleshooting
|
||||
- 权限被拒（缺少 sudo / 非管理员）
|
||||
|
||||
**切换提示**：仅在系统包管理器都失败、并且用户明确希望安装时升级到 L4。
|
||||
|
||||
## L4：社区方案
|
||||
|
||||
仅在以下情况启用：
|
||||
|
||||
1. 用户明确指定（"我要 pyenv"、"用 nvm 装"）
|
||||
2. L1–L3 全部失败
|
||||
3. 项目已经使用社区方案（存在 `.python-version` / `.nvmrc` 文件）
|
||||
|
||||
| 工具 | 用途 | 文档 |
|
||||
|------|------|------|
|
||||
| pyenv / pyenv-win | Python 多版本 | python-runtime/references/pyenv-fallback.md |
|
||||
| nvm / nvm-windows | Node.js 多版本（shell 脚本） | nodejs-runtime/references/nvm-fallback.md |
|
||||
| fnm | Rust 实现的 nvm 替代 | nodejs-runtime/references/nvm-fallback.md |
|
||||
| conda / miniconda | 数据科学场景 | python-runtime/references/virtualenv.md |
|
||||
|
||||
## 何时跳过决策树
|
||||
|
||||
skill 直接执行用户原话——不要走决策树——的情况：
|
||||
|
||||
- 用户明示路径："用 brew 装 python"、"在 .venv 里 pip install xxx"
|
||||
- 用户在 skill 之外手工修改了环境（识别到 `.python-version`、`.nvmrc`、`package.json#volta`）
|
||||
- skill 上下文已经存在激活的虚拟环境（`$VIRTUAL_ENV` 非空）
|
||||
|
||||
## 每次升级版本后
|
||||
|
||||
无论走哪条路径，**安装/移除完成后立即调用**：
|
||||
|
||||
```bash
|
||||
# L1 模式
|
||||
curl -sk -X POST "${BASE}/environment/refresh"
|
||||
|
||||
# L2/L3/L4 模式（强制 probe 输出最新结果）
|
||||
bash <skill>/scripts/probe-{python,node}.sh
|
||||
```
|
||||
|
||||
避免后续判断基于陈旧缓存。
|
||||
Reference in New Issue
Block a user