人工智能AI Agent工具调用MCP Clients大模型【免费下载链接】claude-agent-sdk-python项目地址https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python点击查看免费下载导读本文围绕本仓库examples/plugins/demo-plugin/commands/greet.md这份插件命令定义文档展开深入讲解如何在 Claude Code 中通过 Python SDK 加载本地插件、以 Markdown 指令文件的形式定义自定义斜杠命令/greet并剖析该命令从文件定义、SDK 配置到 CLI 底层参数传递的完整链路。读完本文你将掌握插件目录的标准结构、greet.md的指令语义、ClaudeAgentOptions.plugins的配置方式以及如何基于源码验证插件是否真正被加载从而在自己的 SDK 应用中扩展 Claude Code 的自定义命令、Agent、技能与钩子hooks。一、greet.md 是什么一份驱动 Claude 行为的命令指令文档在 Claude Code 的插件体系中自定义命令Custom Commands并非可执行代码而是一份置于插件commands/目录下的 Markdown 指令文档。Claude 在被调用该命令时会读取这份文档并按照其中的指令执行。本仓库中的 examples/plugins/demo-plugin/commands/greet.md 全文如下# Greet Command This is a custom greeting command from the demo plugin. When the user runs this command, greet them warmly and explain that this message came from a custom plugin loaded via the Python SDK. Tell them that plugins can be used to extend Claude Code with custom commands, agents, skills, and hooks.这份文档看似简短实则定义了完整的行为契约# Greet Command命令的主题说明Claude 会将其作为该命令的用途上下文正文第一段说明这是来自 demo 插件的自定义问候命令帮助 Claude 理解命令来源与性质正文第二段关键行为指令当用户运行该命令时Claude 应当热情地打招呼并主动说明这条消息来自通过 Python SDK 加载的自定义插件同时告知用户插件可用于扩展 Claude Code 的自定义命令、Agents、技能skills和 hooks。这里的核心机制是Markdown 文件即指令本身。Claude 并不执行脚本而是把文档内容作为提示注入对话上下文据此生成响应。因此命令的实现质量完全取决于指令文档写的有多清晰、多可执行——这与传统编程中的命令源码概念有本质区别。二、插件目录的标准结构与 greet.md 的定位从仓库目录布局可以确认 demo 插件的完整结构examples/plugins/demo-plugin/ ├── commands/ │ └── greet.md ← 本文讲解的自定义命令定义在 Claude Code 插件规范中commands/目录是插件存放自定义斜杠命令的约定位置目录下每个 Markdown 文件名即命令名。因此commands/greet.md注册的命令就是/greet——用户输入/greet时Claude 读取该文档并按其指令行事。从仓库源码结构看这个目录结构配合本仓库的 examples/plugin_example.py 共同构成一个完整的插件演示闭环示例代码负责把整个demo-plugin目录作为本地插件加载greet.md负责在被调用时提供命令行为。二者缺一不可。三、通过 SDK 加载插件ClaudeAgentOptions.plugins 配置详解仅编写greet.md还不够必须在 SDK 层面把包含它的插件目录加载进会话。本仓库的 examples/plugin_example.py 给出了完整可运行的加载范例from pathlib import Path import anyio from claude_agent_sdk import ( ClaudeAgentOptions, SystemMessage, query, ) async def plugin_example(): print( Plugin Example \n) # 定位 demo 插件目录 # 生产环境中可以指向任意插件目录路径 plugin_path Path(__file__).parent / plugins / demo-plugin options ClaudeAgentOptions( plugins[ { type: local, path: str(plugin_path), } ], max_turns1, # 演示用限制为单轮 ) print(fLoading plugin from: {plugin_path}\n) found_plugins False async for message in query(promptHello!, optionsoptions): if isinstance(message, SystemMessage) and message.subtype init: print(System initialized!) print(fSystem message data keys: {list(message.data.keys())}\n) # 在系统消息中检查插件是否被加载 plugins_data message.data.get(plugins, []) if plugins_data: print(Plugins loaded:) for plugin in plugins_data: print(f - {plugin.get(name)} (path: {plugin.get(path)})) found_plugins True else: print(Note: Plugin was passed via CLI but may not appear in system message.) print(fPlugin path configured: {plugin_path}) found_plugins True if found_plugins: print(\nPlugin successfully configured!\n) async def main(): await plugin_example() if __name__ __main__: anyio.run(main)3.1 plugins 配置项的类型定义plugins字段的类型在 src/claude_agent_sdk/types.py 中定义为SdkPluginConfigclass SdkPluginConfig(TypedDict): SDK plugin configuration. Currently only local plugins are supported via the local type. type: Literal[local] path: str配置要点type当前唯一支持的取值是字面量local即加载本地目录形式的插件Literal[local]在类型层面保证了这一点path插件目录的绝对路径或可解析路径指向包含commands/等子目录的插件根目录配置项位于ClaudeAgentOptions.plugins见 types.py注释明确说明插件为会话提供自定义命令、Agents、技能和 hooks用于扩展 Claude Code 的能力当前仅支持本地插件。3.2 运行示例在仓库根目录执行python examples/plugin_example.py程序会打印加载的插件信息名称与路径并在初始化系统消息中确认插件已注入会话。示例中max_turns1仅用于快速演示单轮往返实际使用中可根据场景调整轮数上限。四、源码级原理plugins 配置如何变成 CLI 的 --plugin-dirgreet.md最终能生效依赖 SDK 把plugins配置翻译成 Claude Code CLI 能够识别的启动参数。这条链路在 src/claude_agent_sdk/_internal/transport/subprocess_cli.py 中清晰可见# Add plugin directories if self._options.plugins: for plugin in self._options.plugins: if plugin[type] local: cmd.extend([--plugin-dir, plugin[path]]) else: raise ValueError(fUnsupported plugin type: {plugin[type]})这段实现说明了两点关键事实SDK 通过子进程启动 Claude Code CLI 并附加--plugin-dir参数指向插件目录CLI 在启动阶段扫描该目录从而把commands/greet.md注册为/greet命令类型校验发生在命令构建期若传入type不是local会立即抛出ValueError(Unsupported plugin type: ...)与SdkPluginConfig中仅支持 local 类型的文档约束完全一致。这也解释了为何示例中必须写成{type: local, path: ...}而非其他形式。配合 CHANGELOG.md 中插件支持可通过 SDK 程序化加载 Claude Code 插件plugins字段配合SdkPluginConfig支持按路径加载本地插件的变更记录可以确认这是该 SDK 面向插件扩展的一项正式能力而非临时实验特性。五、验证插件是否加载从系统消息中读取插件清单加载插件后如何确认它真的生效示例代码展示了基于初始化系统消息SystemMessagesubtype init的验证思路SDK 在会话建立时下发初始化系统消息其data字典中包含plugins键若插件成功加载遍历plugins_data即可打印每个插件的name与path若插件已通过 CLI 传入但未出现在系统消息中示例代码也会给出明确提示并把配置的plugin_path打印出来供排查。plugins_data message.data.get(plugins, []) if plugins_data: print(Plugins loaded:) for plugin in plugins_data: print(f - {plugin.get(name)} (path: {plugin.get(path)}))这套检查逻辑是插件开发中非常实用的冒烟测试在编写greet.md之后先运行一次 SDK 查询确认插件清单里出现了demo-plugin再在真实会话中输入/greet验证命令响应。六、从 demo 到生产基于 greet.md 扩展自己的自定义命令理解greet.md的机制后扩展自定义命令只需遵循同样的三步模式在插件目录下新建命令文档在commands/下新增your-command.md命令名即文件名如/your-command用指令式语言撰写文档正文参考greet.md的做法第一段说明命令用途后续段落明确 Claude 应当执行的具体行为必要时可补充步骤、约束与输出格式要求指令越具体执行越稳定通过 SDK 加载并验证在ClaudeAgentOptions.plugins中配置指向插件根目录的{type: local, path: ...}然后按第五节的方法从系统消息确认加载再实际调用命令观察响应。需要注意的适用前提与限制均有仓库源码依据当前 SDK 版本仅支持type: local的本地插件types.py远程/市场插件不在本文演示范围内插件命令的行为完全由 Markdown 指令文档驱动Claude 依据文档内容生成响应因此指令文档的质量直接决定命令效果若把plugins配置为其他类型会在启动时触发ValueErrorsubprocess_cli.py编写时务必保持type字段正确。七、总结greet.md是理解 Claude Code 插件命令机制的最佳最小样本一份 Markdown 指令文件定义了/greet命令的行为契约ClaudeAgentOptions.plugins负责把它所在的插件目录加载进会话subprocess_cli.py在底层把它翻译为 CLI 的--plugin-dir参数而初始化系统消息则提供了可编程的加载验证手段。掌握这条从文档定义 → SDK 配置 → CLI 参数 → 运行时生效的完整链路你便拥有了基于本仓库扩展自定义命令、Agents、技能与 hooks 的完整工具箱这也是插件机制赋予 Claude Code 与 Python SDK 应用的核心扩展力所在。赞分享人工智能AI Agent工具调用MCP Clients大模型【免费下载链接】claude-agent-sdk-python项目地址https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python点击查看免费下载相关推荐Claude Code 的 /new-sdk-app 命令从零搭建 Claude Agent SDK 应用TypeScript 与 PythonClaude Code 的 /new sdk app 命令从零搭建 Claude Agent SDK 应用TypeScript 与 Python 本篇指南AI 应用AI 技能/插件开发工具Claude Code自定义命令开发创建属于你的自然语言指令Claude Code自定义命令开发创建属于你的自然语言指令 你是否还在重复编写相同的终端命令是否希望用自然语言直接控制代码工具Claude Code的自AI 应用AI 技能/插件开发工具Claude Code自定义命令开发全攻略从构思到发布Claude Code自定义命令开发全攻略从构思到发布 你是否在使用Claude Code时遇到过重复执行相似命令的烦恼是否希望根据自己的开发习惯定制专属功AI 应用AI 技能/插件开发工具上一篇Ursa.Avalonia 1.8.1版本发布UI组件库的全面优化下一篇Mermaid Live Editor 在线编辑器敲 5 行字一条链接拿到流程图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考