该提问与当前博客内容无直接关联。 将现有 Python 脚本封装为 Skill 并适配 `scripts` 与 `references` 目录结构，是一个关于 AI 智能体或自动化框架的技能开发实践。该问题不涉及 Claude Code 与 OpenClaw 的架构对比，因此我将基于通用的 AI 技能开发范式进行解答。此过程核心在于将脚本的执行逻辑与框架的调度机制解耦，并通过标准化的目录结构实现资源管理与代码复用。 ### 一、 技能目录结构规范 一个结构良好的技能目录是确保技能可维护、可扩展和可复用的基础。典型的技能目录结构如下： ``` my_custom_skill/ ├── skill_manifest.json # 技能元数据与入口声明 ├── scripts/ # 核心执行逻辑目录 │ ├── main.py # 主执行脚本 │ ├── utils.py # 工具函数 │ └── config.py # 配置管理 ├── references/ # 参考与资源目录 │ ├── api_docs.md # 外部API文档 │ ├── schema.json # 数据结构定义 │ └── examples/ # 使用示例 │ └── sample_input.json ├── requirements.txt # Python依赖 └── README.md # 技能说明文档 ``` **关键目录说明**： * `scripts/`: 存放所有可执行的 Python 代码。这是技能逻辑的核心，应遵循单一职责原则进行模块化。 * `references/`: 存放非执行性资源，如配置模板、数据模式、文档、示例数据等。这些资源为技能的执行提供上下文和约束，但不直接参与代码执行流。 ### 二、 技能封装的核心步骤 #### 步骤1：定义技能清单 (Manifest) 创建 `skill_manifest.json` 文件，用于向框架声明技能的能力、输入参数和触发方式。这是框架加载和调用技能的契约。 ```json { "name": "data_processor", "version": "1.0.0", "description": "一个用于处理和分析数据文件的技能。", "author": "Your Name", "entry_point": "scripts.main:execute", "trigger_keywords": ["处理数据", "分析报表"], "parameters": { "input_file": { "type": "string", "description": "待处理数据文件的路径", "required": true }, "operation": { "type": "string", "description": "执行的操作类型", "enum": ["clean", "aggregate", "visualize"], "default": "clean" } } } ``` * `entry_point`: 指定框架调用的入口函数，格式为 `模块路径:函数名`。 * `parameters`: 定义技能的输入接口，框架会据此进行参数验证和传递。 #### 步骤2：重构脚本逻辑至 `scripts/` 目录 将原有脚本的业务逻辑拆分并迁移到 `scripts/` 目录下。重点是设计一个清晰的入口函数，接收来自框架的标准化参数。 ```python # scripts/main.py import sys import os sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from scripts import utils from scripts.config import get_config import json def execute(input_file: str, operation: str = "clean", **kwargs) -> dict: """ 技能执行的主入口函数。 参数由框架根据 skill_manifest.json 的 `parameters` 定义传入。 """ # 1. 参数验证与预处理 if not os.path.exists(input_file): raise FileNotFoundError(f"输入文件不存在: {input_file}") # 2. 加载配置与参考资源 config = get_config() schema_path = os.path.join('references', 'schema.json') with open(schema_path, 'r') as f: data_schema = json.load(f) # 加载数据模式用于验证 # 3. 分发执行逻辑 if operation == "clean": result = _clean_data(input_file, config, data_schema) elif operation == "aggregate": result = _aggregate_data(input_file, config) elif operation == "visualize": result = _visualize_data(input_file, config) else: raise ValueError(f"不支持的操作类型: {operation}") # 4. 格式化返回结果 return { "status": "success", "message": f"操作 '{operation}' 执行完成", "data": result, "output_path": kwargs.get('output_path', './output') } def _clean_data(file_path, config, schema): """数据清洗逻辑""" # 调用 utils 中的函数 raw_data = utils.load_data(file_path) cleaned_data = utils.validate_and_clean(raw_data, schema) return cleaned_data def _aggregate_data(file_path, config): """数据聚合逻辑""" # ... 具体实现 pass def _visualize_data(file_path, config): """数据可视化逻辑""" # ... 具体实现 pass if __name__ == "__main__": # 本地测试入口，模拟框架调用 test_args = {"input_file": "references/examples/sample_input.json", "operation": "clean"} print(execute(**test_args)) ``` #### 步骤3：利用 `references/` 目录管理静态资源 `references/` 目录用于存放技能执行所需的静态知识、配置和数据模式，使技能逻辑与具体配置解耦。 ```json // references/schema.json - 定义期望的数据结构 { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "user_id": {"type": "integer"}, "timestamp": {"type": "string", "format": "date-time"}, "metric_value": {"type": "number"} }, "required": ["user_id", "timestamp"] } ``` ```markdown <!-- references/api_docs.md - 记录外部依赖信息 --> # 外部API参考 本技能依赖以下外部服务： - **DataClean API**: 用于高级数据清洗，端点：`https://api.example.com/v1/clean` - 认证方式：Bearer Token - 请求格式：JSON ``` ### 三、 与框架的集成适配 技能开发完成后，需要将其集成到目标框架（如 LangChain、AutoGPT 或自定义框架）中。集成方式通常有两种： 1. **动态加载**：框架运行时扫描技能目录，读取 `skill_manifest.json`，并动态注册技能。 ```python # 框架侧的简化加载器示例 import importlib.util import json import os class SkillLoader: def __init__(self, skills_dir): self.skills_dir = skills_dir self.skills = {} def load_skill(self, skill_name): skill_path = os.path.join(self.skills_dir, skill_name) manifest_path = os.path.join(skill_path, 'skill_manifest.json') with open(manifest_path, 'r') as f: manifest = json.load(f) # 动态导入入口模块 entry_module_path = manifest['entry_point'].split(':')[0].replace('.', '/') + '.py' spec = importlib.util.spec_from_file_location(manifest['name'], os.path.join(skill_path, entry_module_path)) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) # 获取入口函数 entry_func_name = manifest['entry_point'].split(':')[1] entry_func = getattr(module, entry_func_name) self.skills[skill_name] = { 'manifest': manifest, 'execute': entry_func } return self.skills[skill_name] ``` 2. **静态注册**：在框架配置文件中声明技能路径，框架启动时一次性加载。 ### 四、 最佳实践与注意事项 | 实践要点 | 说明 | 收益 | | :--- | :--- | :--- | | **参数验证前置** | 在 `execute` 函数起始处严格校验输入参数和资源存在性。 | 提高技能鲁棒性，快速失败。 | | **逻辑与IO分离** | 将文件读写、网络请求等IO操作封装在 `utils` 中，核心逻辑保持纯净。 | 便于单元测试和逻辑复用。 | | **配置外部化** | 将阈值、API密钥、文件路径等配置项放入 `references/config.yaml`。 | 使技能无需修改代码即可适配不同环境。 | | **资源路径解析** | 使用 `os.path.join` 和 `__file__` 构建资源绝对路径，避免硬编码。 | 保证技能在不同部署环境下都能正确定位资源。 | | **丰富的返回结构** | 技能应返回结构化的字典，包含状态、结果、错误信息等。 | 便于上游框架统一处理和分析技能执行结果。 | 通过以上步骤，可以将一个独立的 Python 脚本系统性地封装为一个具备清晰接口、完善资源管理和良好可维护性的技能，并能平滑集成到支持目录结构约定的 AI 智能体框架中。