Claude Code 程序化调用完全指南：从CLI到Agent SDK的深度实践

Claude Code 程序化调用完全指南：从CLI到Agent SDK的深度实践声明：📝 作者：甜城瑞庄的核桃（ZMJ）原创学习笔记，欢迎分享，但请保留作者信息及原文链接哦～一、概述1.1 什么是Claude Code程序化调用Claude Code提供了Agent SDK,允许开发者通过CLI、Python或TypeScript以编程方式运行Claude Code。Agent SDK提供了与Claude Code相同的工具、Agent循环和上下文管理能力,适用于脚本自动化和CI/CD集成场景。1.2 核心特性多语言支持: CLI命令行、Python和TypeScript SDK工具自动化: 自动批准工具调用,无需人工干预结构化输出: 支持JSON格式和自定义Schema输出会话管理: 支持会话持续和恢复流式响应: 实时接收Token生成结果1.3 适用场景自动化脚本执行CI/CD流水线集成代码审查自动化批量代码分析定时任务执行二、快速入门2.1 基础使用方式通过添加-p(或--print)参数,可以让Claude Code以非交互模式运行:claude-p"在auth.py中查找并修复bug"--allowedTools"Read,Edit,Bash"核心参数说明:-p/--print: 启用程序化模式--allowedTools: 自动批准指定工具--output-format: 控制输出格式2.2 CLI模式 vs 交互模式对比特性CLI模式(-p)交互模式执行方式非交互式,自动执行需要人工交互确认工具批准可预先配置自动批准每次调用需确认输出格式支持JSON结构化输出文本输出会话管理支持会话ID管理自动管理适用场景自动化脚本、CI/CD日常开发调试三、Bare模式深度解析3.1 什么是Bare模式Bare模式通过--bare参数启用,会跳过自动发现hooks、skills、plugins、MCP服务器、自动内存和CLAUDE.md配置,从而大幅减少启动时间。3.2 标准模式 vs Bare模式# 标准模式 - 加载所有上下文claude-p"总结这个项目"# Bare模式 - 最小化上下文claude--bare-p"总结这个文件"--allowedTools"Read"加载内容对比:内容类型标准模式Bare模式~/.claude配置✅ 加载❌ 跳过CLAUDE.md✅ 加载❌ 跳过.mcp.json✅ 加载❌ 跳过hooks/skills✅ 加载❌ 跳过自动内存✅ 加载❌ 跳过基础工具(Bash/Read/Edit)✅ 可用✅ 可用3.3 Bare模式上下文配置在Bare模式下,通过参数显式加载所需资源:资源类型配置参数系统提示词--append-system-prompt/--append-system-prompt-file配置文件--settings file-or-jsonMCP服务器--mcp-config file-or-json自定义Agent--agents json插件目录--plugin-dir path示例:claude--bare-p"执行任务"\--settingsconfig.json\--mcp-config mcp.json\--append-system-prompt"你是一个安全工程师"3.4 Bare模式认证机制Bare模式跳过OAuth和密钥链读取,认证方式:Anthropic: 通过ANTHROPIC_API_KEY环境变量或--settings中的apiKeyHelperBedrock/Vertex/Foundry: 使用各自提供商的标准凭证最佳实践: CI/CD和脚本场景推荐使用Bare模式,确保跨机器的结果一致性。四、结构化输出完全指南4.1 输出格式类型使用--output-format控制响应格式:格式说明适用场景text纯文本(默认)人类可读输出json结构化JSON,包含result、session_id和元数据程序化处理stream-json换行分隔的JSON流实时流式处理4.2 标准JSON输出基础用法:claude-p"总结这个项目"--output-format json输出结构:{"result":"项目总结的文本内容","session_id":"会话唯一标识","usage":{"input_tokens":1234,"output_tokens":567},"timestamp":"2026-04-03T10:30:00Z"}4.3 自定义Schema输出结合--json-schema实现符合特定结构的输出:claude-p"从auth.py提取主要函数名"\--output-format json\--json-schema'{ "type": "object", "properties": { "functions": { "type": "array", "items": {"type": "string"} } }, "required": ["functions"] }'输出示例:{"structured_output":{"functions":["authenticate","validate_token","refresh_session"]},"session_id":"abc-123","usage":{...}}4.4 使用jq解析输出提取文本结果:claude-p"总结项目"--output-format json|jq-r'.result'提取结构化输出:claude-p"提取函数名"\--output-format json\--json-schema'...'\|jq'.structured_output'复杂查询示例:# 提取函数名数组并转为逗号分隔字符串claude-p"提取函数名"--output-format json --json-schema'...'\|jq-r'.structured_output.functions | join(",")'五、流式响应实战5.1 启用流式输出claude-p"解释递归概念"\--output-format stream-json\--verbose\--include-p