mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 05:30:39 +08:00
xyx
a582f0f4f9
## 背景 / Background #16 (4f7037a) 将 16 个 SKILL.md 的 `~/.desirecore` 路径批量替换为 `${DESIRECORE_ROOT}`，但只升了 `manifest.json`，**未升任何 per-skill version**。 客户端按 SKILL.md frontmatter 的 per-skill `version` 做 semver 同步：version 不变即判定「无更新」而永久跳过，导致已升级用户的全局技能正文停留在替换前的旧内容（与线上不同步）。 #16 (4f7037a) bulk-replaced `~/.desirecore` with `${DESIRECORE_ROOT}` in 16 SKILL.md files but only bumped `manifest.json`, leaving every per-skill `version` untouched. Clients sync by per-skill semver, so an unchanged version is treated as "no update" and skipped forever — upgraded users' global skills stay frozen on pre-replacement content. ## 改动 / Changes - 对 #16 触及且至今仍未升号的 **14 个在册技能** 各 patch +1 - `manifest.json` 1.2.2 → 1.2.3（沿用 #16「内容改动同步升 manifest」的约定） - 退役技能 `minimax-image-gen` / `minimax-tts`（不在 builtin-skills.json，不下发）跳过 - diff 为纯 version 行，未触动正文 Bumps the 14 in-manifest skills changed by #16 that were never version-bumped; manifest 1.2.2 → 1.2.3; retired skills skipped. Version-line-only diff.
10 KiB
10 KiB
name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market
| name | description | version | type | risk_level | status | disable-model-invocation | tags | metadata | market | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| python-runtime | 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. 使用场景：用户需要 安装 Python、安装 pip、配置虚拟环境、管理多版本、 解决 PEP 668、import 失败、PATH 问题、SSL 证书错误等。 | 1.0.2 | procedural | low | enabled | true |
|
|
|
python-runtime Skill
L0: One-line Summary
When to use: The user needs to install Python / upgrade Python / switch
between multiple Python versions / configure pip / create virtual environments
(venv / pipx / conda) / troubleshoot python: command not found,
pip: command not found, PEP 668 "externally-managed", SSL certificates,
import failures, PATH anomalies, and other Python runtime issues; or when
another skill (docx / pdf / xlsx / pptx) reports "Python unavailable".
How to do it: Prefer DesireCore's built-in Hatch, executing through the four-tier fallback (HTTP API → Hatch CLI → system package manager brew/apt/dnf/winget → community solution pyenv).
L1: Overview and Use Cases
Capability Description
Procedural skill. Before each Python environment operation, first run scripts/probe-python.sh to obtain a JSON snapshot, then follow references/decision-tree (→ ../dev-environment-setup/references/decision-tree.md) to choose a path through the four-tier fallback.
Use Cases
- "python not found" / "pip not found"
- The user requests to install/upgrade Python
- The user requests multi-version management (3.10/3.11/3.12 switching)
- Create/activate/debug virtual environments (venv/pipx/conda)
- "externally-managed-environment" (PEP 668) error
- import failures, PATH issues, SSL certificate errors
- Other skills (docx/pdf/xlsx/pptx) report Python unavailable
Core Value
- DesireCore first: Hatch + HTTP API as mandatory L1/L2, avoiding pollution of system Python
- JSON-driven decisions: the probe script outputs structured data that Claude can parse directly
- Cross-platform consistency: macOS / Linux / Windows share a unified 4-tier fallback
L2: Detailed Specification
Step 1: Environment Probe (mandatory)
bash skills/python-runtime/scripts/probe-python.sh > /tmp/py-probe.json
cat /tmp/py-probe.json | jq .
For the meaning of output fields, see ../dev-environment-setup/references/probe-snapshot.md.
Step 2: Choose an Execution Path
Decide using ../dev-environment-setup/references/decision-tree.md:
| Condition | Path |
|---|---|
desirecore_api is non-empty |
L1 HTTP API |
desirecore_api empty, hatch_path non-empty |
L2 Hatch CLI |
| Neither of the above | L3 system package manager (brew/apt/dnf/winget) |
| L1–L3 all fail or user explicitly requests | L4 community solution (pyenv) |
Step 3: Execute (only the main path is shown; see references for details)
L1: HTTP API (→ references/hatch-desirecore.md)
PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
BASE="https://127.0.0.1:${PORT}/api/runtime"
# List installable versions
curl -sk "${BASE}/python/available"
# Trigger install (asynchronous; subscribe to runtime:terminal for progress)
curl -sk -X POST "${BASE}/python/install" \
-H "Content-Type: application/json" \
-d '{"version":"3.12"}'
# Force-refresh the cache after install completes
curl -sk -X POST "${BASE}/environment/refresh"
L2: Hatch CLI absolute path (→ references/hatch-desirecore.md)
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_ROOT}/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
Windows: %USERPROFILE%\.desirecore\runtime\hatch\hatch.exe.
L3: System Package Manager
| Platform | Command |
|---|---|
| macOS | brew install python3 |
| Debian/Ubuntu | sudo apt install python3 python3-pip python3-venv |
| Fedora/RHEL | sudo dnf install python3 python3-pip |
| Arch | sudo pacman -S python python-pip |
| Windows | winget install Python.Python.3 |
L4: pyenv (→ references/pyenv-fallback.md)
Only enable when the user explicitly requests it or the above paths fail.
Step 4: Virtual Environments
For virtual environment strategy, see references/virtualenv.md:
- venv (recommended, standard library)
- pipx (global CLI tools such as black/ruff/markitdown)
- conda / miniconda (data-science scenarios)
Step 5: Troubleshooting
When errors occur, look up references/troubleshooting.md:
- "python: command not found" / "pip: command not found"
- PEP 668 "externally-managed-environment"
- SSL/TLS certificate errors
- import failures (package name vs. import name differences)
- macOS xcrun / Xcode CLI missing
- Windows PowerShell execution policy blocking scripts
- Proxy environment configuration
Important Constraints
- Never
sudo pip install: always use a virtual environment orpipx. - Refresh after modifying the environment: for L1 call
POST /api/runtime/environment/refresh; for L2/L3/L4 re-run probe. - Cross-skill collaboration: when
docx/pdf/xlsx/pptxreport "Python unavailable", fall into L1/L2 install; for office dependency lookup see../dev-environment-setup/references/office-deps.md. - Do not pollute system Python: at the project level always use venv; for global CLI use pipx.
References
- Decision tree:
../dev-environment-setup/references/decision-tree.md - DesireCore base:
../dev-environment-setup/references/desirecore-runtime.md - Probe protocol:
../dev-environment-setup/references/probe-snapshot.md - Office dependencies:
../dev-environment-setup/references/office-deps.md - System tools:
../dev-environment-setup/references/system-tools.md