mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-06-06 04:30:42 +08:00

Files

Yige 1f7c8b9673 feat: skills i18n 改造（schemaVersion 1.1，零向后兼容） (#1 )

* feat: skills i18n 改造 — schemaVersion 1.1，零向后兼容

把 21 个 skills + 1 个 agent + manifest/categories 全量迁移到 schemaVersion 1.1
的 i18n 结构，配套 CI AI 翻译流水线（GitHub Models）与本地工具链。

## 关键变更

### 数据结构（破坏性，schemaVersion 1.0 → 1.1）
- SKILL.md: 顶层 name 改为 ASCII slug（== 目录名，符合 agentskills.io 规范）；
  中文显示名/short_desc/description 全部迁入 metadata.i18n.<locale>
- agents/<id>/agent.json: shortDesc/fullDesc/tags/persona.{role,traits} 迁入
  i18n.<locale>；changelog[].changes 改为 { <locale>: string[] } 对象
- categories.json: 每个分类的 label/description 迁入 i18n.<locale>，顶层只剩
  color/icon
- manifest.json: 加 supportedLocales / defaultLocale；顶层 description 迁入
  i18n.<locale>

### Body 文件结构
- 根 SKILL.md = frontmatter + default_locale (en-US) body
- SKILL.<locale>.md = 各 locale 的 markdown body（首行 <!-- locale: xx --> 自校验）

### 工具链（scripts/i18n/）
- glossary.json: zh→en 术语表 + do_not_translate 白名单
- schema/skill-frontmatter.schema.json: i18n frontmatter JSON Schema
- validate-i18n.py: 8 条校验规则（name 合规 / locale 完整性 / hash 一致性等）
- translate.py: GitHub Models / Anthropic 双 backend，sha256 增量翻译
- migrate.py: 一次性迁移脚本（旧格式 → i18n 结构）

### CI（.github/workflows/）
- i18n-validate.yml: PR 触发跑 validate + translate --check
- i18n-translate.yml: PR 触发用 GitHub Models（默认 openai/gpt-5-mini）翻译缺失
  locale，自动追加 commit；可切到 ANTHROPIC_API_KEY 走 Claude

### 文档
- docs/I18N.md: 作者贡献指南（schema 说明 / 提交流程 / 常见问题）
- README.md: 加多语言段落

## 验证

- uv run scripts/i18n/validate-i18n.py: OK，49 文件 0 错误
- uv run scripts/i18n/translate.py --check: 0 stale locale
- 21 skills 标题数 zh-CN == en-US 严格对齐（最大 66=66）
- skills-ref 规范校验：全部通过（顶层 name ASCII slug + description 单字段）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(i18n): 修复 PR #1 review 反馈的 6 项问题

- schema: translated_by 正则放宽为 ^(human|ai:[A-Za-z0-9._:/-]+)$，接受
  'ai:github:openai/gpt-5-mini' 这类 backend:model 形式（CI 翻译输出格式）
- README + docs/I18N.md: 修正"CI 用 Claude API"误导描述，正确说明默认是
  GitHub Models（openai/gpt-5-mini）+ GITHUB_TOKEN，可选切到 Anthropic
- skills/minimax-tts/SKILL.md & SKILL.zh-CN.md: 删除多余的 ``` 闭合，避免
  Markdown 后续渲染错乱
- skills/docx/SKILL.md: 翻译时丢失的 • Unicode escape 示例已恢复，
  与 zh-CN 版本对齐

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-05 00:26:33 +08:00

5.0 KiB

Raw Blame History

python-runtime 技能

L0：一句话摘要

何时使用：用户需要安装 Python / 升级 Python / 切换 Python 多版本 / 配置 pip / 创建虚拟环境（venv / pipx / conda）/ 排查 python: command not found、 pip: command not found、PEP 668 "externally-managed"、SSL 证书、import 失败、 PATH 异常等 Python 运行时问题，或其他 skill（docx / pdf / xlsx / pptx）报告 "Python 不可用" 时。

怎么做：优先使用 DesireCore 内置 Hatch，按四级降级（HTTP API → Hatch CLI → 系统包管理器 brew/apt/dnf/winget → 社区方案 pyenv）执行。

L1：概述与使用场景

能力描述

procedural skill。每次执行 Python 环境操作前，先运行 scripts/probe-python.sh 取 JSON 快照，再按 references/decision-tree（→ ../dev-environment-setup/references/decision-tree.md）四级降级选择路径。

使用场景

"python not found" / "pip not found"
用户要求安装/升级 Python
用户要求多版本管理（3.10/3.11/3.12 切换）
创建/激活/调试虚拟环境（venv/pipx/conda）
"externally-managed-environment"（PEP 668）报错
import 失败、PATH 问题、SSL 证书错误
其他 skill（docx/pdf/xlsx/pptx）报告 Python 不可用

核心价值

DesireCore 优先：Hatch + HTTP API 作为强制 L1/L2，避免污染系统 Python
JSON 决策：probe 脚本输出结构化数据，Claude 可直接解析
跨平台一致：macOS / Linux / Windows 统一 4 级降级

L2：详细规范

第一步：环境探测（必须）

bash skills/python-runtime/scripts/probe-python.sh > /tmp/py-probe.json
cat /tmp/py-probe.json | jq .

输出字段含义见 ../dev-environment-setup/references/probe-snapshot.md。

第二步：选择执行路径

按 ../dev-environment-setup/references/decision-tree.md 判断：

条件	路径
`desirecore_api` 非空	L1 HTTP API
`desirecore_api` 空，`hatch_path` 非空	L2 Hatch CLI
上述都不满足	L3 系统包管理器（brew/apt/dnf/winget）
L1–L3 全部失败或用户明示	L4 社区方案（pyenv）

第三步：执行（仅展示主路径，详见各 references）

L1：HTTP API（→ `references/hatch-desirecore.md`）

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

# 列出可装版本
curl -sk "${BASE}/python/available"

# 触发安装（异步，订阅 runtime:terminal 看进度）
curl -sk -X POST "${BASE}/python/install" \
  -H "Content-Type: application/json" \
  -d '{"version":"3.12"}'

# 安装完成后强制刷新缓存
curl -sk -X POST "${BASE}/environment/refresh"

L2：Hatch CLI 绝对路径（→ `references/hatch-desirecore.md`）

HATCH=~/.desirecore/runtime/hatch/hatch
export HATCH_HOME=~/.desirecore/runtime/hatch

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

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

Windows：%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe。

L3：系统包管理器

平台	命令
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`）

仅在用户明示或上述失败时启用。

第四步：虚拟环境

虚拟环境策略详见 references/virtualenv.md：

venv（推荐，标准库）
pipx（全局 CLI 工具如 black/ruff/markitdown）
conda / miniconda（数据科学场景）

第五步：故障排查

报错时按 references/troubleshooting.md 查表：

"python: command not found" / "pip: command not found"
PEP 668 "externally-managed-environment"
SSL/TLS 证书错误
import 失败（包名 vs import 名差异）
macOS xcrun / Xcode CLI 缺失
Windows PowerShell 执行策略阻止脚本
代理环境配置

重要约束

绝不 sudo pip install：始终用虚拟环境或 pipx。
修改了环境后必须刷新：L1 调 POST /api/runtime/environment/refresh；L2/L3/L4 重新跑 probe。
跨 skill 协作：docx / pdf / xlsx / pptx 报"Python 不可用"时，进入 L1/L2 安装；办公依赖速查见 ../dev-environment-setup/references/office-deps.md。
不污染系统 Python：项目级别一律使用 venv，全局 CLI 用 pipx。

引用关系

决策树：../dev-environment-setup/references/decision-tree.md
DesireCore 底座：../dev-environment-setup/references/desirecore-runtime.md
探测协议：../dev-environment-setup/references/probe-snapshot.md
办公依赖：../dev-environment-setup/references/office-deps.md
系统工具：../dev-environment-setup/references/system-tools.md

5.0 KiB Raw Blame History Unescape Escape