LearnGraph.online

Appearance

Agent SDK Dev 开发工具插件 ​

Agent SDK Dev 插件提供 Claude Agent SDK 项目的交互式创建和验证工具，帮助开发者快速搭建 Python 或 TypeScript Agent 应用。

概述 ​

Agent SDK Dev 是一个开发者工具插件，专门用于 Claude Agent SDK 项目的创建和验证。它提供交互式项目脚手架和全面的代码验证功能，确保项目符合最佳实践。

核心特性 ​

特性说明
交互式创建通过问答方式创建新项目
多语言支持Python 和 TypeScript
自动验证8 个维度的代码检查
最佳实践内置 SDK 使用规范

组件概览 ​

mermaid
graph TD
    A[Agent SDK Dev] --> B[/new-sdk-app 命令]
    A --> C[Python 验证器]
    A --> D[TypeScript 验证器]

    B --> B1[交互式项目创建]
    C --> C1[8 维度验证]
    D --> D1[8 维度验证]

    style A fill:#e3f2fd

安装与配置 ​

插件安装 ​

bash
# 安装 agent-sdk-dev 插件
/plugin install agent-sdk-dev@claude-plugins-official

目录结构 ​

plugins/agent-sdk-dev/
├── .claude-plugin/
│   └── plugin.json
├── README.md
├── commands/
│   └── new-sdk-app.md              # 项目创建命令
└── agents/
    ├── agent-sdk-verifier-py.md    # Python 验证器
    └── agent-sdk-verifier-ts.md    # TypeScript 验证器

配置文件 (plugin.json) ​

json
{
  "name": "agent-sdk-dev",
  "description": "Claude Agent SDK Development Plugin",
  "version": "1.0.0",
  "author": {
    "name": "Ashwin Bhat",
    "email": "ashwin@anthropic.com"
  }
}

核心命令 ​

/new-sdk-app ​

交互式创建新的 Agent SDK 项目。

语法：

bash
/new-sdk-app [项目名称]

交互流程：

mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude
    participant F as 文件系统

    U->>C: /new-sdk-app my-agent

    C->>U: 选择编程语言？
    U->>C: Python

    C->>U: 选择代理类型？
    U->>C: 聊天机器人

    C->>U: 需要哪些工具？
    U->>C: 文件操作、Web 搜索

    C->>F: 创建项目结构
    C->>F: 生成代码文件
    C->>F: 安装依赖

    C->>C: 运行验证器
    C->>U: 项目创建完成！

交互问题：

问题选项
编程语言Python / TypeScript
项目名称自定义名称
代理类型聊天机器人 / 任务代理 / 自定义
工具首选项文件操作 / Web 搜索 / 代码执行 / 自定义

生成的项目结构：

Python 项目：

my-agent/
├── .env.example
├── .gitignore
├── requirements.txt
├── README.md
├── main.py
└── agents/
    └── my_agent.py

TypeScript 项目：

my-agent/
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   └── index.ts
└── agents/
    └── myAgent.ts

Python 验证器 ​

8 维度验证 ​

Python 验证器检查以下 8 个领域：

mermaid
graph TD
    A[Python 验证器] --> B[SDK 安装]
    A --> C[环境设置]
    A --> D[SDK 使用]
    A --> E[代码质量]
    A --> F[安全性]
    A --> G[最佳实践]
    A --> H[功能性]
    A --> I[文档]

    style A fill:#e3f2fd

1. SDK 安装 ​

检查项：

  • claude-agent-sdk 包是否安装
  • SDK 版本是否最新
  • Python 版本 ≥ 3.8
bash
# 验证 SDK 安装
pip show claude-agent-sdk
python --version

2. 环境设置 ​

检查项：

  • requirements.txt 或 pyproject.toml 存在
  • 依赖正确声明
  • 虚拟环境配置
python
# requirements.txt 示例
claude-agent-sdk>=1.0.0
python-dotenv>=1.0.0

3. SDK 使用 ​

检查项：

  • 正确的导入语句
  • Agent 初始化方式
  • 方法调用正确性
python
# ✅ 正确用法
from claude_agent_sdk import Agent, Tool

agent = Agent(
    model="claude-3-sonnet",
    system_prompt="You are a helpful assistant."
)

# ❌ 错误用法
from claude import Agent  # 错误的导入

4. 代码质量 ​

检查项：

  • 语法正确性
  • 导入语句完整
  • 错误处理存在
  • 结构一致性

5. 安全性 ​

检查项：

  • API 密钥不在代码中硬编码
  • .env 文件正确处理
  • .gitignore 包含敏感文件
python
# ❌ 危险
ANTHROPIC_API_KEY = "sk-ant-..."  # 硬编码

# ✅ 安全
import os
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

6. 最佳实践 ​

检查项：

  • System prompt 设计
  • 模型选择合理
  • 权限范围适当
  • 工具集成正确

7. 功能性 ​

检查项：

  • 初始化流程完整
  • 错误处理覆盖
  • SDK 特定问题

8. 文档 ​

检查项：

  • README.md 存在
  • 设置说明清晰
  • 配置详情完整

验证报告格式 ​

markdown
## Python Agent SDK Verification Report

### Status: ✅ PASS (with warnings)

### Passed Checks (6)
✅ SDK Installation: claude-agent-sdk 1.2.0 installed
✅ Python Version: 3.10.5 (>=3.8 required)
✅ Environment Setup: requirements.txt found
✅ SDK Usage: Correct imports and initialization
✅ Security: No hardcoded API keys
✅ Documentation: README.md present

### Warnings (2)
⚠️ Best Practices: Consider adding error handling in main.py:45
⚠️ Code Quality: Unused import 'json' in agents/my_agent.py

### Critical Issues (0)
None

### Improvement Suggestions
1. Add more descriptive system prompt
2. Consider implementing retry logic for API calls
3. Add unit tests for agent behavior

TypeScript 验证器 ​

TypeScript 特定检查 ​

除了 8 维度验证外，TypeScript 验证器还检查：

检查项说明
ES 模块package.json 中 "type": "module"
类型安全npx tsc --noEmit 通过
Node.js 兼容运行时兼容性
tsconfig.json配置正确对齐
.env.example环境变量模板存在

不检查项 ​

TypeScript 验证器不检查：

  • 通用 TypeScript 风格
  • 命名约定（除非影响 SDK）
  • 格式标准（留给 Prettier/ESLint）

TypeScript 项目示例 ​

typescript
// src/index.ts
import { Agent, Tool } from 'claude-agent-sdk';

const agent = new Agent({
  model: 'claude-3-sonnet',
  systemPrompt: 'You are a helpful coding assistant.',
  tools: [
    new Tool({
      name: 'run_code',
      description: 'Execute Python code',
      handler: async (code: string) => {
        // Implementation
      }
    })
  ]
});

async function main() {
  const response = await agent.chat('Hello!');
  console.log(response);
}

main().catch(console.error);

推荐工作流 ​

1. 创建新项目 ​

bash
claude /new-sdk-app my-agent

2. 回答交互式问题 ​

? Select programming language: Python
? Enter project name: my-agent
? Select agent type: Chatbot
? Select tools: File operations, Web search

3. 自动验证运行 ​

项目创建后，验证器自动运行并报告问题。

4. 配置 API 密钥 ​

bash
cd my-agent
cp .env.example .env
# 编辑 .env 添加 ANTHROPIC_API_KEY

5. 开始开发 ​

bash
# Python
python main.py

# TypeScript
npm run dev

6. 重大变更后重新验证 ​

bash
# 手动触发验证
"请用 agent-sdk-verifier-py 验证我的项目"

最佳实践 ​

SDK 使用规范 ​

实践说明
保持更新使用最新 SDK 版本
安全存储API 密钥放在 .env
错误处理实现重试和降级逻辑
类型安全TypeScript 项目使用严格模式
测试覆盖为 Agent 行为编写测试

项目结构 ​

mermaid
graph TD
    A[项目根目录] --> B[.env.example]
    A --> C[.gitignore]
    A --> D[README.md]
    A --> E[依赖文件]
    A --> F[源代码]
    A --> G[测试]

    F --> F1[入口文件]
    F --> F2[agents/]
    F --> F3[tools/]
    F --> F4[utils/]

    style A fill:#e3f2fd

安全清单 ​

检查项状态
API 密钥在 .env 中☐
.env 在 .gitignore 中☐
.env.example 不含真实值☐
无硬编码凭证☐
敏感日志已过滤☐

常见问题 ​

Q: 验证失败如何处理？ ​

A: 查看验证报告，按优先级修复：

  1. Critical Issues（必须修复）
  2. Warnings（建议修复）
  3. Improvement Suggestions（可选优化）

Q: 支持哪些 Agent 类型？ ​

A:

  • Chatbot：对话式代理
  • Task Agent：任务执行代理
  • Custom：自定义类型

Q: 如何添加自定义工具？ ​

A: 在 agents/ 目录下创建工具文件：

python
# tools/my_tool.py
from claude_agent_sdk import Tool

class MyTool(Tool):
    name = "my_tool"
    description = "Does something useful"

    async def run(self, input: str) -> str:
        # Implementation
        return result

Q: 验证器报告过于严格？ ​

A: 验证器设计为检测潜在问题。如果某些警告不适用于你的场景，可以在代码中添加注释说明原因。

总结 ​

Agent SDK Dev 插件简化了 Claude Agent SDK 项目的开发：

  1. 交互式创建 - 问答式项目脚手架
  2. 多语言支持 - Python 和 TypeScript
  3. 8 维度验证 - 全面的代码检查
  4. 最佳实践 - 内置规范指导

帮助开发者快速构建高质量的 Agent 应用。

参考资源 ​

本文档基于 agent-sdk-dev 插件 v1.0.0 编写

基于 MIT 许可证发布。内容版权归作者所有。

Copyright © 2025-present 王几行XING（Bryce Wang）