Skills 模块实施状态
最后更新：2026-03-22 关联里程碑：M1 Skills运行时契约
1. 模块概览
Skills 模块实现了 Agent 能力的注入机制，通过 SKILL.md 文件定义技能，支持： - 多源发现（bundled/global/workspace） - 运行时契约校验 - 多种执行路径（Python-native/Node-wrapper/MCP-bridge）
2. 技能发现机制
| 来源 | 路径 | 优先级 | 说明 |
| Bundled | skills/ → pyclaw/bundled_skills | 最高 | 内置技能，打包随发行 |
| Global | ~/.pyclaw/skills/ | 中 | 全局技能，所有项目共享 |
| Workspace | <workspace>/.pyclaw/skills/ | 最高 | 项目级技能，覆盖全局 |
加载器：src/pyclaw/agents/skills/loader.py
3. 内置技能清单（14个）
| 技能 | 目录 | 状态 | 运行时 | 功能说明 |
| repo-review | skills/repo-review/ | ✅ 完成 | Python-native | 代码审查与风险清单 |
| docs-sync | skills/docs-sync/ | ✅ 完成 | Python-native | 文档与实现一致性巡检 |
| release-helper | skills/release-helper/ | ✅ 完成 | Python-native + MCP | 发布检查与变更汇总 |
| incident-triage | skills/incident-triage/ | ✅ 完成 | Python-native | 故障分诊与应急模板 |
| channel-ops | skills/channel-ops/ | ✅ 完成 | Python-native | 通道健康与策略巡检 |
| node-toolchain | skills/node-toolchain/ | ✅ 完成 | Node-wrapper | Node生态技能桥接 |
| mcp-admin | skills/mcp-admin/ | ✅ 完成 | MCP-bridge | MCP服务治理 |
| pdf | skills/pdf/ | ✅ 完成 | Python-native | PDF处理 |
| docx | skills/docx/ | ✅ 完成 | Python-native | Word文档处理 |
| xlsx | skills/xlsx/ | ✅ 完成 | Python-native | Excel表格处理 |
| pptx | skills/pptx/ | ✅ 完成 | Python-native | PowerPoint处理 |
| social | skills/social/ | ✅ 完成 | Python-native | 社交媒体 |
| xiaohongshu-core | skills/xiaohongshu-core/ | ✅ 完成 | Python-native | 小红书核心 |
| wechat-mp-publisher | skills/wechat-mp-publisher/ | ✅ 完成 | Python-native | 微信公众号发布 |
4. 运行时契约（Skill Runtime Contract）
4.1 契约字段
| 维度 | 字段 | 必填 | 说明 |
| spec | skill_key, description, version | ✅ | 技能标识与版本 |
| runtime | python-native / node-wrapper / mcp-bridge | ✅ | 技能执行路径 |
| capability | tools, inputs, outputs | ✅ | 能力声明 |
| deps | python, node, binary, mcp | ✅ | 依赖声明 |
| security | security_level, requires_approval, network_policy | ✅ | 安全与审批 |
| lifecycle | install, healthcheck, rollback | ✅ | 运维动作 |
| observability | metrics, logs, trace_tags | 推荐 | 可观测字段 |
4.2 执行前契约门禁
| 检查项 | 阻断行为 | 说明 |
| 依赖缺失 | needs_attention + missing_dep:* | 默认阻断 |
userInvocable: false | invalid | 非用户可调用 |
| 诊断模式 | 正常执行 | ignore_runtime_contract=true 绕过 |
5. 运行时类型矩阵
| 类型 | 适用场景 | 优点 | 风险 | 约束策略 |
| Python-native | 本地工具与数据处理 | 集成最深、性能稳定 | 依赖冲突 | venv/extra分层 + import检测 |
| Node-wrapper | 复用TS/Node生态技能 | 可快速迁移上游技能 | 进程与安全复杂 | 受控exec + allowlist + timeout + sandbox |
| MCP-bridge | 远程/独立服务能力 | 解耦好、跨语言统一 | 网络与可用性依赖外部 | healthcheck + 重试 + 降级策略 |
6. 技能生命周期门禁
| 阶段 | 必做项 | 产出 |
| Design | 契约字段定义、权限边界 | Skill Spec草案 |
| Build | 依赖检测、执行器适配、错误降级 | 可安装技能包 |
| Verify | 单测 + 集成 + 安全审计 | 验证报告 |
| Release | 版本、变更记录、回滚策略 | 发布记录 |
| Operate | 健康检查、错误率、使用率追踪 | 运维看板 |
7. Code Review 修复记录
| 发现项 | 风险 | 处置 |
pyclaw skills run 未执行契约门禁 | 技能声明与真实执行行为不一致 | 已在 runner.py 增加执行前预检 |
| 非用户可调用技能缺少CLI阻断 | 内部技能可能被直接触发 | 已增加 skill_not_user_invocable 阻断 |
| 探测型技能需保留故障态可执行 | 若强阻断会损失诊断能力 | 按技能类型豁免预检阻断 |
8. 测试覆盖
| 测试文件 | 状态 | 覆盖范围 |
tests/pyclaw/agents/skills/test_runtime_contract.py | ✅ 完成 | 运行时契约 |
tests/pyclaw/cli/test_skills_run.py | ✅ 完成 | skills run命令 |
9. 关键文件索引
| 文件 | 职责 |
skills/*/SKILL.md | 技能定义（唯一真源） |
src/pyclaw/agents/skills/loader.py | 技能发现与加载 |
src/pyclaw/agents/skills/runner.py | 技能执行入口 |
reference/ops/M1_BUILTIN_SKILLS_CANDIDATES.md | M1内置技能候选清单 |
10. 待办事项
- [ ] 更多内置技能（office-reader等）
- [ ] 技能健康检查机制
- [ ] 技能使用率追踪
- [ ] ClawHub marketplace 集成