插件脚本开发指南

脚本目录结构

scripts/
├── __init__.py
├── main.py                  # CLI 入口（必需）
├── hooks.py                 # 钩子处理（可选）
├── mcp.py                   # MCP 服务器（可选）
└── <module>.py              # 业务逻辑模块

CLI 入口实现

main.py 模板

python
1#!/usr/bin/env python3
2"""插件 CLI 入口。"""
3
4import click
5from lib import logging
6
7@click.group()
8def main():
9    """插件命令组。"""
10    pass
11
12@main.command()
13def my_command():
14    """我的命令说明。"""
15    click.echo("执行我的命令")
16
17@main.command()
18def hooks():
19    """钩子处理模式。"""
20    from scripts.hooks import handle_hook
21    handle_hook()
22
23if __name__ == "__main__":
24    main()

Click 命令装饰器

示例

python
1@main.command()
2@click.argument("name")
3@click.option("--verbose", "-v", is_flag=True, help="详细输出")
4def greet(name, verbose):
5    """问候用户。"""
6    if verbose:
7        logging.info(f"收到问候请求: {name}")
8    click.echo(f"Hello, {name}!")

共享库使用

日志模块

python
1from lib import logging
2
3logging.info("信息日志")
4logging.error("错误日志")
5logging.debug("调试日志")

钩子系统

python
1from lib.hooks import load_hooks
2
3hook_data = load_hooks()

插件中注册脚本

脚本通过命令和钩子调用，无需在 plugin.json 中单独注册：

json
1{
2  "hooks": {
3    "SessionStart": [
4      {
5        "hooks": [
6          {
7            "type": "command",
8            "command": "uv run --directory ${CLAUDE_PLUGIN_ROOT} ./scripts/main.py hooks"
9          }
10        ]
11      }
12    ]
13  }
14}

相关技能

• plugin-development - 插件开发
• plugin-hook-development - 插件钩子开发
• plugin-mcp-development - 插件 MCP 开发