shared-dependency-manager
> 跨项目 Python 依赖共享与隔离管理 Skill。
>
> ## 1. Purpose
> 在多个 Python 项目之间复用高成本、稳定、可跨项目的依赖，同时保持每个项目环境独立可复现，避免重复安装/下载，并防止项目之间互相破坏环境。
>本 Skill 不把"让所有项目共用一个环境"当作目标，而是建立 Shared Dependency（共享依赖）与 Project Environment（项目环境）两层结构，由 Agent 在两处之间做正确决策。
2. Scope
2.1 负责
- 发现项目依赖并核验实际 Python 环境。
- 发现共享依赖环境并分析兼容性。
- 判断依赖应共享还是项目隔离。
- 创建/准备项目级 Python 环境，建立对共享依赖的引用（
.pth）。 - 安装项目专属依赖，防止破坏共享环境。
- 验证共享与项目依赖实际可导入、可运行。
- 更新共享依赖登记（registry）并检查 drift。
2.2 不负责
业务代码开发、API/前端/数据库设计、模型算法实现、与依赖无关的运行时 Bug、为绕过冲突随意改业务代码、未经分析直接升级/降级/卸载共享依赖、把整个项目迁移到共享环境。
> 若任务核心不是 Python 依赖管理，不应触发本 Skill。
3. Trigger Conditions
满足任一情况应考虑调用：
- 项目初始化：新建 Python 项目环境、首次安装依赖、存在
pyproject.toml/requirements.txt/uv.lock。 - 依赖共享：项目需要大型/高成本/高复用依赖、已存在共享环境、需要判断依赖进 shared 还是 project。
- 依赖冲突：项目要求与共享环境版本冲突、Python 版本不一致、平台/架构/ABI/binary 可能冲突、runtime/backend 无法满足。
- 环境维护：检查共享环境实际安装状态、核对 registry 与实际一致、更新共享资产、验证项目仍能使用共享依赖。
不应触发：修改普通业务逻辑、调试与依赖无关的错误、Git/数据库操作、单纯运行已有程序且无需改环境。
4. Inputs
显式输入（最少）：
operation: initialize | install | inspect | verify | audit | update
project_path: <path>
可选：shared_environment_path、registry_path、requested_dependencies。
自动探测：应优先实际探测而非依赖描述。探测 Python executable/version/platform/architecture、项目依赖文件、共享环境、共享环境 Python 版本、已安装包、包位置、uv 可用性。
项目依赖来源：优先读 pyproject.toml、uv.lock、requirements.txt、项目环境配置；不得仅凭 README 示例命令推断完整依赖。
5. Outputs
同时产生人类可读结果与机器可读结果。机器可读结果统一为：
status: success | partial | blocked | failed
project:
path: ...
python: ...
shared_environment:
path: ...
python: ...
dependencies:
shared: []
project: []
conflicts: []
unknown: []
actions: []
verification:
status: passed | failed | not_run
errors: []
warnings: []
> 脚本层输出契约（inspect/scan/configure/verify 的具体字段）见 references/contracts.md。
6. Shared vs Project Environment
- Shared Environment 保存：安装成本高、下载体积大、多项目高复用概率、版本稳定、能形成兼容集合的依赖。共享环境不应成为"什么都装"的垃圾环境，默认只读受保护。
- Project Environment 保存：项目专属、低复用、实验性版本、与共享冲突、需独立生命周期、不确定是否适合共享的依赖。
原则：不确定是否安全共享时，优先项目隔离。
7. Sharing Decision Policy
对每个候选共享依赖，检查：复用价值、安装成本、版本约束、Python 版本、平台/架构、ABI/binary 兼容性、已有共享依赖关系、项目专属程度。
| 条件 | Shared | Project |
|---|---|---|
| 高安装成本 | ✅ | 可选 |
| 高复用价值 | ✅ | |
| 版本稳定 | ✅ | |
| 项目专属 | ✅ | |
| 明显版本冲突 | ✅ | |
| Python 版本冲突 | ✅ | |
| ABI/binary 风险高 | ✅ | |
| 实验性版本 | ✅ | |
| 无法证明兼容 | ✅ |
不得仅依据包名称判断共享与否。
8. Environment Protection
共享环境默认受保护：
protect_shared_environment: true
auto_upgrade: false
auto_downgrade: false
auto_uninstall: false
项目任务不得为满足自身需求自动升级/降级/卸载/替换共享核心依赖、修改共享 Python。若项目需要冲突版本：Shared 保持不变，冲突依赖隔离到 Project Environment。
只有满足以下条件才允许提出共享环境变更：1) 明显跨项目复用价值；2) 已有项目影响已分析；3) 新版本兼容性已确认；4) 变更可验证；5) 变更已记录。
脚本安全规则：不删除共享环境、不卸载/自动升级/自动降级共享依赖、修改共享前必须显式进入 shared-change workflow、项目环境修改优先于共享环境、所有 destructive action 默认 dry-run 或显式确认、输出实际修改的路径/包/版本。
9. 调用链（Workflow）
标准调用链（脚本负责采集事实并执行受控动作，Agent 负责共享/隔离决策）：
inspect_python_env
↓
scan_project_dependencies
↓
inspect_shared_env
↓
Agent 决策（复用 / 隔离 / 候选 / blocked）
↓
configure_shared_path（需要实际复用时）
↓
verify_shared_dependencies
↓
Agent 生成 agent-result
> 各脚本职责、CLI 与输出字段详见 references/contracts.md。
10. Verification Rules
验证必须区分 import 与 location，不能只验证 install 命令返回成功：
- Import：
import package成功。 - Location：确认 package 从哪里加载（
package.__file__）。若被视为 Shared Dependency，实际路径必须来自 Shared Environment 的 site-packages。 - Version：确认
package.__version__或 metadata。 - Interpreter：确认
sys.executable、sys.prefix。 - Project-specific runtime：若项目需要特定能力（GPU/native extension/DB driver），验证该能力而非只验证 import。
共享成功的三项验收标准（必须共同满足）：
importable == true
reused_from_shared == true
sys_path_contains_shared == true
三者缺一不可，Agent 才能把该依赖判定为"已实际复用"。
11. Error Handling
- Shared package 无法 import：检查 project sys.path → .pth → shared site-packages → interpreter 兼容性。
- import 失败但包存在：优先检查 Python 版本/ABI/platform/架构/子依赖/项目本地冲突包，不要第一时间改 Shared。
- 项目要求冲突版本：保持 Shared 不变，安装/隔离到 Project 版本。
- Registry 与实际不一致：报告 "Shared Environment Drift Detected"，默认不自动纠正。
- 无法确认安全共享：按 Unknown → Project Environment，保守优先。
12. Final Decision Algorithm
INPUT
project / dependency requirements / actual Python env / shared environment
↓
DISCOVER project dependencies, shared packages, Python compatibility
↓
CLASSIFY reusable | project-local | conflicting | unknown
↓
DECIDE
reusable + compatible → reuse Shared
missing + high reuse + compatible → candidate for Shared
project-specific / conflict / unknown → Project
↓
CONNECT 建立共享引用 → 验证实际 import 路径
↓
INSTALL 仅安装缺失的项目本地依赖
↓
VERIFY interpreter / import / version / package location / runtime capability
↓
RECORD Registry / PROJECT_ENV.md
↓
OUTPUT human-readable report + structured result
13. Success Criteria
一次成功执行至少满足：
- Trigger 判断正确；项目依赖已识别；实际 Python 环境与 Shared Environment 均已检查。
- Shared/Project 决策有依据；未破坏 Shared Environment；项目环境独立存在。
- 共享引用机制可解释；Shared package 实际 import 成功；location 与版本关系验证通过。
- Project-specific 依赖可用；registry/环境记录已更新；可重复执行而不产生无意义安装。
最终目标：让 Root Agent 能把"Python 依赖安装问题"交给一个稳定、可验证、与具体框架和包管理器解耦的基础设施 Skill，由该 Skill 在 Shared 与 Project 之间做正确决策。
附录：实现契约与可迁移决策案例
references/README.md— references 索引（实现契约 + 决策案例库）。references/contracts.md— 脚本/schema 契约摘要（脚本职责、CLI、输出字段、幂等changed语义、.pth落位要求、opencv 导入名提示）。references/scenario-01.md~scenario-07.md— 7 个可迁移决策案例（环境情形 / 依赖条件 / Agent 决策 / 关键依据 / 可复用要点，用占位符表述，不绑定本机路径）。
