本文档说明本目录下 Python Skill 的统一环境管理方式。
跨设备搭建手册:新设备(Linux/WSL 或 Windows)从零配置环境,见 docs/runbook/跨设备搭建.md。
注意:本文件为辅助说明文档,不影响 Claude Code/OpenCode 的 Skill 系统。各子目录中的
SKILL.md(需含 YAML frontmatter)才是 Skill 的规范定义文件。
~/projects/dc-skills/
├── README.md # 本说明文档
├── AGENTS.md # 执行约束与三条铁律(唯一实体,无软链)
├── docs/ # 文档归类:specs(规范)/ arch(登记)/ runbook(手册)/ research(档案,历史快照)
│ ├── INDEX.md # ⭐ 全局文档索引(唯一文档地图)
├── pyproject.toml / uv.lock / .venv/ # 统一依赖与虚拟环境(轻量 skill 共享)
│
├── diagram/ # 图表聚合入口。flow 在 references/flow.md,没有 diagram-flow 目录
│ ├── SKILL.md # 路由表 + 通用规范
│ └── references/ # 各类型规程分册(er/ers/module/usecase/sequence/flow/draft)
│
├── diagram-er/ # ⚠️ 非独立技能:聚合技能的脚本目录(单表 ER 图)
│ ├── .venv -> ../.venv # 符号链接到统一环境
│ └── scripts/ # -m scripts.cli 入口 + renderer/parser/models
├── diagram-ers/ # 多实体 ER 图脚本目录(ECharts/Playwright 或 Pillow)
├── diagram-module/ # 功能模块树形图脚本目录
├── diagram-sequence/ # UML 时序图脚本目录(mmdc 渲染)
├── diagram-usecase/ # UML 用例图脚本目录
├── diagram-draft/ # ASCII 架构草稿(graph-easy render.sh,无 Python)
│
├── design-ui/ # 前端页面设计(原 artifact-design)
├── design-diagram/ # Artifact 内联 SVG 图表(原 artifact-diagramming)
├── design-dataviz/ # 数据可视化设计系统(原 dataviz)
│
├── db-skill/ # MySQL/PostgreSQL 工具
├── word-extractor/ # .docx 提取
├── unified-search/ # 10 源聚合搜索(含 keenable 源,原 keenable-cli 已并入)
├── drawio-xml/ # .drawio 图表(MCP 协同,npx 按需拉取)
├── kimi-webbridge/ # 真实浏览器控制(daemon)
├── vision-workflow/ # 视觉任务编排(Vision MCP)
├── thesis-writing/ thesis-ref-check/ md-to-thesis-latex/ # 论文写作族
├── paper-metrics/ # 论文写作特征指标层(纯 stdlib 确定性测量;Mode B 上游)
│
├── paper-reader/ # ⚠️ 例外:持有独立重型 venvs
│ └── venvs/ # marker ~5.1GB / mineru ~613MB(GPU 模型权重,不共享)
├── debugging/ git-master/ programming/ remove-ai-slops/ # omo vendor 4 技能(oh-my-openagent 4.17.1;git-master 已扩为 git/GitHub 全流程)
├── dsh-ui-optimization/ dsh-plugin-troubleshooting/ # DSH 插件技能(plugin-specialist 预设)
├── agent-infra/ # Agent 基础设施族群入口(统揽网关运维与各 Agent 额度对账)
├── unified-gateway/ agent-balances/ # Agent-Infra 成员技能(网关运维与额度用量)
├── proxy-ops/ cloudreve-storage/ # 运维与云存储单体技能
└── wsl-windows-bridge/ # WSL→Windows 桥接(系统 Python,不纳入统一 .venv)
主库是全机唯一物理技能目录(git 仓库,远端为 GitHub)。每个 Agent 只通过自己技能目录里的软链接看到启用技能;未登记的技能对任何 Agent 不可见。唯一事实源为根目录 agent-map.yaml,由 scripts/skills-sync 物化:
| Agent | 农场目录 | 默认技能 |
|---|---|---|
| Claude Code | ~/.claude/skills |
base |
| Grok | ~/.grok/skills |
base |
| dsh | ~/.dsh/skills |
base |
| zcode | ~/.zcode/skills |
base |
| Codex | ~/.codex/skills |
base |
cd ~/projects/dc-skills
uv run python scripts/skills-sync # 物化全部农场(含 dsh 的 thesis-agent / plugin-specialist 预设)
uv run python scripts/skills-sync --check # 只检查漂移,不修改- 安装器着陆区
~/.agents/skills/:软件官方技能常驻该区走官方更新,不收编主库——Orca 系(orca-cli/orchestration/computer-use,源stablyai/orca)与 lark 官方 28 域(lark-*,源larksuite/cli),由npx skills update <名> --global维护;其他来源新技能出现时mv进主库 → 在agent-map.yaml登记 → 跑 skills-sync。 - 各 App 自带技能不收编主库:
~/.grok/bundled/skills/、~/.codex/skills/.system/与各插件市场缓存由 App 自行管理更新;同名用户技能会覆盖 App 本体,收编等于制造随 App 更新而过期的分叉。 - 全机技能台账与自注册监控:
uv run python scripts/skillctl inventory(主库 vs App 自管根、重名与着陆区漂移)。
完整管理架构(各 Agent 自注册机制、dsh 发现优先级、管理规约 P1–P8、风险台账)见 docs/specs/技能管理.md;文档地图见 docs/INDEX.md。
| 类别 | 环境 | 适合的 Skill | 说明 |
|---|---|---|---|
| A. 统一共享 | .venv/ 符号链接 |
diagram 聚合的脚本目录(diagram-er/ers/module/sequence/usecase)、db-skill、word-extractor、unified-search、thesis-writing、paper-metrics | 依赖轻量(Pillow/sqlglot/psycopg2/requests/pytest 等),共享一份 venv |
| B. 独立重型 | skill 内 venvs/ |
paper-reader | 含 GPU 模型权重(5GB+),不可合并,.gitignore 已忽略 |
| C. 无统一 venv | 系统/Windows Python 或二进制 | diagram-draft/flow、design-ui/diagram/dataviz(纯文档)、drawio-xml(npx)、kimi-webbridge、md-to-thesis-latex、thesis-ref-check、agent-infra、unified-gateway、proxy-ops、wsl-windows-bridge | 无统一 venv(系统/Windows Python 或自带运行时) |
所有 Python 脚本必须先 cd ~/projects/dc-skills 再用 uv run 执行,绝不依赖用户当前项目的 pyproject.toml。
cd ~/projects/dc-skills && uv run python <skill-name>/scripts/<script>.py ...uv run --directory 只影响 pyproject.toml 的查找位置,但脚本相对路径仍基于当前工作目录解析。先 cd 再执行可同时保证:pyproject.toml 正确 + 相对路径正确。
diagram 聚合技能(er/ers/module/sequence/usecase 五类)使用 Python 包形式(-m scripts.cli),
脚本保留在原 diagram-* 目录,需进入对应子目录执行:
cd ~/projects/dc-skills/diagram-er && uv run python -m scripts.cli ...这是因为 -m scripts.cli 要求 scripts/ 在 cwd 下;脚本内 sys.path 引用顶层 scripts/common.py
(plan_output,实现 docs/specs/输出规范.md C-1)。其 .venv 符号链接确保 uv 仍解析到统一环境。
类型路由与使用规范见 diagram/SKILL.md。
cd ~/projects/dc-skills
uv add <package-name>cd ~/projects/dc-skills
uv synccd ~/projects/dc-skills
uv run python -c "import PIL, sqlglot, psycopg2, pymysql; print('OK')"cd ~/projects/dc-skills
for skill in diagram-er diagram-ers diagram-module diagram-sequence diagram-usecase db-skill; do
ln -sf ../.venv "$skill/.venv"
done
# 注:diagram-er 等为 diagram 聚合技能的脚本目录(非独立技能)bash ~/projects/dc-skills/paper-reader/scripts/bootstrap.shuv run 通过当前工作目录查找 pyproject.toml 来定位虚拟环境。以下场景需注意:
-
在 skills 目录内运行(推荐)
cd ~/projects/dc-skills uv run python db-skill/scripts/pg_tool.py ...
正常找到虚拟环境。
-
在临时/外部目录运行(错误)
cd /tmp uv run python ~/projects/dc-skills/db-skill/scripts/pg_tool.py ...
uv在/tmp找不到pyproject.toml,会使用系统默认 Python,导致依赖缺失(如psycopg2找不到)。 -
子进程调用时应使用
sys.executable当脚本需要作为子进程在其他目录运行时,应使用当前 Python 解释器的绝对路径,而非uv run:import sys subprocess.run([sys.executable, "db-skill/scripts/pg_tool.py", ...])
-
db-skill 配置发现也依赖 cwd
mysql_tool.py和pg_tool.py会从当前工作目录向上查找.db-skill/mysql.json或.db-skill/pg.json。在项目根目录下运行才能正确发现配置,或使用--config显式指定。
| 包名 | 用途 |
|---|---|
Pillow |
图片生成与处理(diagram 聚合:er/ers/module/usecase 脚本) |
sqlglot |
SQL 解析(diagram 聚合:er 脚本) |
python-docx |
.docx 提取(word-extractor) |
psycopg2-binary |
PostgreSQL(db-skill) |
pymysql |
MySQL(db-skill) |
cryptography |
加密(db-skill) |
requests |
HTTP 请求(kimi-web-search 已删,unified-search 等) |
beautifulsoup4 |
HTML 解析 |
openai |
OpenAI 兼容 API |
httpx |
异步 HTTP |
pyyaml |
YAML 解析 |
feedparser |
RSS/Atom 解析 |
Node 工具(非 Python 依赖,完整登记表见 docs/arch/环境依赖.md):
@mermaid-js/mermaid-cli(mmdc):用于 diagram 聚合的 sequence 类渲染 Mermaid 到 PNG(推荐用npx调用,避免全局安装)。lark-cli:lark 官方 28 域技能(驻着陆区)与lark-cli skills read的硬依赖(Node 全局安装)。keenable:unified-search 硬依赖(安装/认证/MCP 配置见 unified-search/references/keenable-setup.md)。
以下 skill 需要 Windows 侧执行,不适用于纯 Linux 环境:
| Skill | Windows 依赖 | 机制 |
|---|---|---|
paper-reader |
E:\venvs\marker、E:\venvs\mineru |
paper_reader.py 自动检测 WSL,通过 cmd.exe 桥接 GPU 到 Windows 原生 Python |
wsl-windows-bridge |
cmd.exe、powershell.exe、reg.exe 等 |
三层桥接:cmd.exe(~55ms) / Direct EXE(~10ms) / PowerShell(~600ms) + GPU 资源治理(GpuLimits + GpuGovernor) |
- 在该 Skill 目录下创建符号链接:
ln -sf ~/projects/dc-skills/.venv ~/projects/dc-skills/<new-skill>/.venv
- 如果新 Skill 需要新的 Python 包,在
~/projects/dc-skills/pyproject.toml中添加依赖,然后执行uv lock或uv sync。 - 如果新 Skill 依赖 GPU/重型模型(如 paper-reader),保持独立
venvs/,并在.gitignore中添加忽略条目。 - SKILL.md 必须以 YAML frontmatter 开头(
---包裹的name+description),否则 OpenCode 无法识别。 - 更新本 README 的依赖列表和环境分类表。