cli-anything-mailchimp 实战：用 CLI-Anything 将 Mailchimp Marketing API v3.0 封装为 Agent 原生命令行接口

cli-anything-mailchimp 实战用 CLI-Anything 将 Mailchimp Marketing API v3.0 封装为 Agent 原生命令行接口【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything这篇指南以 mailchimp 子模块的 README 为主体结合其架构文档与源码系统讲解如何安装、认证、运行cli-anything-mailchimp覆盖 30 个资源组的 303 个命令、JSON 输出与 jq 组合、交互式 REPL 以及底层 HTTP 客户端实现。读完你将能够在 Shell 脚本或 Agent 工作流中直接管理 Mailchimp 的受众lists、邮件营销活动campaigns、报告reports、自动化automations与电商数据。一、工具定位把整个 Marketing API 变成 CLI 命令cli-anything-mailchimp是构建在 CLI-Anything 框架之上的 Python CLI harness目标是让 Mailchimp Marketing API v3.0全面 Agent-native——即每个 Swagger 端点都暴露为一个带类型检查的 Click 命令并提供 JSON 输出与 REPL 模式让大模型 Agent 无需编写 SDK 代码即可操作账号。在 架构文档 MAILCHIMP.md 中给出的口径是303 个命令、横跨 30 个资源组覆盖完整 Marketing API 表面。包内技能文件 SKILL.md 的 frontmatter 同步声明了该能力范围。源码侧同样可验证单元测试 test_core.py 中test_all_groups_importable断言len(ALL_GROUPS) 30且每个资源组都必须注册至少一个命令。它能够完成的核心业务动作包括受众Audiences/Lists创建、更新、删除列表添加/更新/归档成员管理合并字段merge fields、分组segments、标签tags与 webhooks营销活动Campaigns创建、排期、立即发送、暂停、复制并分析邮件活动报告Reports打开率、点击率、退订、邮件活动、地域分布等投放分析自动化Automations创建与管理自动化邮件工作流电商E-commerce店铺、订单、顾客、商品、购物车与促销码以及模板templates、文件管理器file-manager、落地页landing-pages、短信活动sms-campaigns、调查surveys等其余全部 Marketing API 资源。二、安装与前置条件2.1 环境要求Python3.10。该版本约束同时写入了包元数据 setup.pypython_requires3.10与 SKILL.md 的 Prerequisites 一节。运行时依赖click8.0、requests2.28、prompt-toolkit3.0见 setup.py 的install_requires。2.2 安装命令在仓库内以开发模式安装对应文档给出的本地开发方式cd mailchimp/agent-harness pip install -e .安装完成后setup.py的entry_points会注册可执行命令cli-anything-mailchimp其入口指向 mailchimp_cli.py 的main()。若需从 CLI-Anything 托管仓库的mailchimp/agent-harness子目录以pip install git...方式安装参见 MAILCHIMP.md 的安装说明。2.3 认证环境变量是唯一配置来源本工具遵循 CLI-Anything 的惯例——不读取任何配置文件只认环境变量。认证只需设置一个变量export MAILCHIMP_API_KEYyour-api-key-datacenter注意 API Key 必须带数据中心后缀例如abc123-us8、xyz-eu2。带后缀的原因在于 Mailchimp 的 API 域名是按数据中心路由的https://dc.api.mailchimp.com/3.0缺少后缀的 Key 无法确定请求发往哪个机房。三、快速上手五条命令走完核心链路安装并导出 Key 后即可直接执行cli-anything-mailchimp ping # 健康检查确认 API 连通性 cli-anything-mailchimp --json lists list # 以 JSON 列出所有受众 cli-anything-mailchimp --json campaigns list --count 10 # 列出前 10 个活动 cli-anything-mailchimp # 不带参数进入交互式 REPL其中ping命中GET /ping连通成功后返回{health_status: Everythings Chimpy!}root list则用于拉取账号基本信息。--json是根级全局开关作用于任意子命令。值得注意的一个命令层级细节是ping这类单端点资源组被生成为 Click group并在未显式给出子命令时自动调用其内部list命令见 ping.py因此cli-anything-mailchimp ping无需追加list即可执行健康检查——单元测试test_ping_group_invokes_health_check_without_list_subcommand专门锁定了这一行为。四、命令全景资源组与命令层级从架构文档 MAILCHIMP.md 可以还原完整命令层级操作数为文档口径cli-anything-mailchimp [--json] [--version] │ ├── ping # GET /ping —— 健康检查 ├── root # GET / —— 账号信息 ├── lists # 66 个操作受众、成员、合并字段、分组、标签、webhooks ├── campaigns # 22 个操作发送、排期、暂停、复制等 ├── reports # 22 个操作已发送活动的分析 ├── automations # 18 个操作工作流与自动化邮件 ├── ecommerce # 60 个操作店铺、订单、商品、购物车、促销码 ├── templates / template-folders / campaign-folders ├── file-manager # 11 个操作文件与文件夹 ├── reporting # 12 个操作Facebook/落地页报告 ├── landing-pages / sms-campaigns / surveys ├── audiences / contacts / customer-journeys / facebook-ads ├── batches / batch-webhooks ├── connected-sites / verified-domains / authorized-apps ├── conversations / activity-feed / account-exports └── search-campaigns / search-members这 30 个资源组模块存放在 commands/ 目录由 __init__.py 汇总为ALL_GROUPS再由根 CLI 统一注册mailchimp_cli.py 中for _group in ALL_GROUPS: cli.add_command(_group)。4.1 Root命令说明cli-anything-mailchimp ping健康检查确认 API 连通性cli-anything-mailchimp root list获取账号信息cli-anything-mailchimp --json cmd以 JSON 输出任意命令结果cli-anything-mailchimp启动交互式 REPL4.2 Lists受众命令说明lists list列出所有受众lists get LIST_ID获取受众信息lists create --data json创建受众lists update LIST_ID --data json更新受众lists delete LIST_ID删除受众lists list-lists-id-members LIST_ID列出受众成员lists get-lists-id-members-id LIST_ID SUBSCRIBER_HASH按 MD5 哈希获取成员lists create-lists-id-members LIST_ID --data json添加成员lists list-lists-id-merge-fields LIST_ID列出合并字段lists create-lists-id-merge-fields LIST_ID --data json添加合并字段lists list-lists-id-segments LIST_ID列出分组lists list-list-member-tags LIST_ID SUBSCRIBER_HASH列出成员标签lists create-list-member-tags LIST_ID SUBSCRIBER_HASH --data json添加/移除成员标签lists list-lists-id-webhooks LIST_ID列出 webhookslists create-lists-id-webhooks LIST_ID --data json添加 webhook从源码可见生成命令同时完整保留了 API 的查询参数。以 lists.py 中lists list为例它支持--fields、--exclude-fields、--count、--offset、--before-date-created、--since-date-created、--sort-field、--sort-dir、--has-ecommerce-store等开关其中count默认值为 10、最大值为 1000offset默认值为 0——这些取值约束直接源自 Mailchimp Swagger 规范的参数描述。每个命令还统一带有--extra-paramsJSON 对象用于透传未建模成独立开关的额外查询参数。4.3 Campaigns命令说明campaigns list列出活动campaigns get CAMPAIGN_ID获取活动信息campaigns create --data json创建活动campaigns update CAMPAIGN_ID --data json更新活动设置campaigns delete CAMPAIGN_ID删除活动campaigns send CAMPAIGN_ID立即发送活动campaigns schedule CAMPAIGN_ID --data json排期发送campaigns cancel-send CAMPAIGN_ID取消已排期的发送campaigns pause CAMPAIGN_ID暂停 RSS 活动campaigns resume CAMPAIGN_ID恢复 RSS 活动campaigns replicate CAMPAIGN_ID复制活动campaigns list-content CAMPAIGN_ID获取活动内容campaigns list-send-checklist CAMPAIGN_ID发送前检查清单4.4 Reports投放报告命令说明reports list列出所有活动报告reports get CAMPAIGN_ID获取活动汇总报告reports list-email-activity CAMPAIGN_ID逐订阅者打开/点击行为reports list-click-details CAMPAIGN_ID链接点击明细reports list-open-details CAMPAIGN_ID逐订阅者打开记录reports list-unsubscribed CAMPAIGN_ID退订名单reports list-locations CAMPAIGN_ID地域分布reports list-domain-performance CAMPAIGN_ID分域名统计4.5 Automations自动化工作流命令说明automations list列出自动化automations get WORKFLOW_ID获取自动化信息automations create --data json创建自动化automations pause WORKFLOW_ID暂停自动化automations start WORKFLOW_ID启动自动化automations archive WORKFLOW_ID归档自动化automations list-emails WORKFLOW_ID列出自动化邮件4.6 E-commerce电商数据命令说明ecommerce list-ecommerce-stores列出店铺ecommerce get STORE_ID获取店铺信息ecommerce create --data json添加店铺ecommerce list-ecommerce-stores-id-orders STORE_ID列出订单ecommerce list-ecommerce-stores-id-products STORE_ID列出商品ecommerce list-ecommerce-stores-id-customers STORE_ID列出顾客ecommerce list-ecommerce-stores-id-carts STORE_ID列出购物车ecommerce list-ecommerce-stores-id-promocodes PROMO_RULE_ID STORE_ID列出促销码4.7 其余资源组速览资源组说明templates邮件模板增删改查template-folders模板文件夹campaign-folders活动文件夹file-manager文件管理器中的文件与文件夹landing-pages落地页列出、创建、发布、取消发布sms-campaigns短信活动surveys调查列出、获取、发布reportingFacebook 广告与落地页报告search-campaigns按查询词搜索活动search-members跨全部受众搜索成员batches批量 API 操作batch-webhooks批量操作 webhooksverified-domains发件域名验证authorized-appsOAuth 已授权应用connected-sites关联站点集成conversations收件箱会话activity-feed账号活动流account-exports账号数据导出补充说明上表中很多“长命令”是生成器从 Swagger 路径自动命名的如list-lists-id-members对应GET /lists/{list_id}/members同时不少模块还维护了面向人的短别名如create-members、list-content、list-send-checklist。测试 test_core.py 中通过test_campaign_shortcut_aliases_match_generated_commands、test_report_shortcut_aliases_match_generated_commands、test_create_members_alias_matches_generated_command等用例逐一断言了别名与实际 HTTP 路径的一致性。五、设计决策与源码佐证架构文档 MAILCHIMP.md 记录了六条核心设计决策均能在源码中找到对应实现基于 Spec 的代码生成303 个命令由 _codegen/generate.py 从 Mailchimp 公开的 Swagger 2.0 规范自动生成生成产物直接入库。这样终端用户在拿到包后即可快速使用--help无需现场下载规范。生成代码均带有“Auto-generated… Do not edit manually”的头部注释见 lists.py 与 ping.py。测试中还专门守护了生成质量test_no_builtin_shadowing_in_function_names用 AST 检查生成函数不会遮蔽 Python 内建名。仅环境变量认证没有配置文件MAILCHIMP_API_KEY是唯一事实来源。客户端在缺 Key 时抛出MailchimpAuthErrorclient.pyget_client()负责向 stderr 打印错误并以退出码 1 结束。原样复制的repl_skin.pyREPL 皮肤按 CLI-Anything 贡献规则从cli-anything-plugin/repl_skin.py无修改复制位于 utils/repl_skin.py。路径参数作为位置参数Mailchimp 路径中的{list_id}、{campaign_id}等变量被生成为必填的位置 Click 参数令命令保持简洁例如campaigns get CAMPAIGN_ID。请求体统一走--dataJSONPOST/PATCH/PUT 的请求体以--data {key:value}传入避免为每个字段生成几十个 flag这对 Agent 尤其友好——可以直接构造 JSON payload。每个生成命令还支持--extra-params必须为 JSON 对象来补充查询参数。Subscriber hash 工具cli_anything.mailchimp.core.client.subscriber_hash(email)实现了 Mailchimp 用于标识成员的 MD5 计算先strip()去除首尾空白、再小写化邮箱后做 MD5与 Node.js 参考实现保持一致。六、输出策略JSON、人类可读与错误信封所有命令共享根级--json开关。在源码层面mailchimp_cli.py 读取该开关后写入 output.py 的模块级标志USE_JSON随后每个命令经_out()统一输出。# 以 JSON 列出所有受众 cli-anything-mailchimp --json lists list # 以 JSON 获取某活动报告 cli-anything-mailchimp --json reports get abc123def # 管道给 jq —— 请使用 Mailchimp 原生字段名 cli-anything-mailchimp --json lists list | jq .lists[].name cli-anything-mailchimp --json campaigns list | jq .campaigns[].id6.1 JSON 信封形态命令输出的是Mailchimp API 原生响应结构而非二次包装因此字段名与 API 文档一致// 集合类端点 —— 键与资源名一致lists、campaigns、members 等 {lists: [...], total_items: 42, _links: [...]} {campaigns: [...], total_items: 10, _links: [...]} // 单资源 GET / POST / PATCH {id: abc123, name: My List, ...} // DELETE {ok: true, message: Deleted.} // 错误 {ok: false, message: Resource Not Found: ..., data: {...}}各形态在 output.py 中均有对应实现_out()在USE_JSONTrue时打印美化 JSON_out_ok()用于变更类操作输出{ok: true, message: ...}_out_err()将 HTTP 状态、title、detail与原始错误体Mailchimp Problem Detail打包为{ok: false, ...}并写入 stderr、以非零码退出。其中 DELETE 的{ok: true}由 client.py 的delete()统一返回。在人类可读模式下单对象输出紧凑的键值对集合输出带注解的列表错误使用彩色✗前缀、成功使用✓前缀。6.2 分页与全量拉取集合命令直接暴露 Mailchimp 原生的count与offset查询参数但CLI 默认不会自动翻页拉取全部数据——单次返回一页其余数据由调用方按需翻页。若需要在脚本里做多页迭代可借助 pagination.py 提供的分页器原语paginate(client, path, result_key)以生成器逐页产出全部条目collect(client, path, result_key)则返回(items, total_items)元组。测试覆盖了单页、多页、空结果以及“恰好一页满时不多拉第二次空页”的边界test_exact_page_boundary_no_extra_fetch。七、常用 Agent 模式技能文件 SKILL.md 整理了一组开箱即用的“Agent 模式”全部是命令 jq的组合# 获取账号健康状态 cli-anything-mailchimp --json ping | jq .health_status # 列出所有受众 ID 与名称 cli-anything-mailchimp --json lists list | jq .lists[] | {id, name} # 找出某受众中所有已订阅成员 cli-anything-mailchimp --json lists list-lists-id-members list_id --status subscribed | jq .members[].email_address # 创建活动并抓取其发送前检查清单 cli-anything-mailchimp --json campaigns create --data {type:regular,settings:{subject_line:Hello,from_name:Me,reply_to:meexample.com}} | jq .id cli-anything-mailchimp --json campaigns list-send-checklist campaign_id | jq .items[] | select(.result false) # 获取某已发送活动的退订名单 cli-anything-mailchimp --json reports list-unsubscribed campaign_id | jq .unsubscribes[].email_address # 向受众添加成员subscriber hash 小写邮箱的 MD5 cli-anything-mailchimp --json lists create-members list_id --data {email_address:userexample.com,status:subscribed} # 跨全部受众搜索某成员 cli-anything-mailchimp --json search-members list --query userexample.com | jq .exact_matches.members[]注意--data必须是可以被json.loads成功解析的合法 JSON若传入{bad这类非法字符串Click 会以退出码 2 报出Invalid value for --data ... valid JSON而不会打印堆栈test_invalid_data_json_reports_click_error用例验证了这一行为。八、交互式 REPL不带任何参数运行cli-anything-mailchimp即进入 REPL。根 CLI 的invoke_without_commandTrue会拦截空调用并转发给_start_repl()见 mailchimp_cli.pyREPL 通过prompt_toolkit读取输入、用shlex分词后以standalone_modeFalse复用同一个 Click CLI 执行因此 REPL 内语法与命令行完全一致。help/?会列出所有资源组的一行简介quit/exit/q或 Ctrl-C/Ctrl-D 退出◆ cli-anything · Mailchimp v0.1.0 Type help for commands, quit to exit ◆ mailchimp ❯ ping ✓ {health_status: Everythings Chimpy!} ◆ mailchimp ❯ --json lists list {lists: [...], total_items: 3, _links: [...]} ◆ mailchimp ❯ quit九、HTTP 客户端底层原理核心客户端实现在 core/client.py值得关注以下几个机制数据中心自动推导_server_prefix()从 API Key 后缀-之后的最后一段提取dc如us8缺失连字符时抛出带提示的ValueError。测试TestServerPrefix验证了abc123-us8 → us8、xyz-eu2 → eu2的推导以及无后缀 Key 会抛错。基础 URL 拼接请求基址为https://dc.api.mailchimp.com/3.0超时统一为 30 秒。认证方式HTTP Basic Auth用户名为任意字符串anystring密码即 API Keyclient._session.auth (anystring, key)请求头携带User-Agent: cli-anything-mailchimp/0.1.0。测试test_auth_header断言了该元组形态。错误建模非 2xx 响应会被_raise()解析为MailchimpError(status, title, detail, raw)——优先取 JSON 中的title/detail解析失败则退回 HTTP reason 与前 200 字符响应体。测试test_get_error_raises构造 404 响应并断言异常携带的status与title。动词映射get/post/patch/put/delete分别对应 HTTP 方法post对 204 No Content 返回{}delete统一返回{ok: True}。十、注意事项与常见坑技能文档与源码共同确认了以下关键约束接入时务必留意Subscriber hashMailchimp 以“小写化邮箱的 MD5”作为成员标识。可用内置工具函数或以下一行命令计算python -c import hashlib; emailemailexample.com; print(hashlib.md5(email.strip().lower().encode()).hexdigest())实现位于 client.py其正确性由测试TestSubscriberHash守护对testexample.com输出已知 MD5 值55502f40dc8b7c769880b10874abc9d0且先去除首尾空白、再小写化。请求体所有 POST/PATCH/PUT 命令都接受--data json各端点的字段 schema 以 Mailchimp API 端点文档为准。数据中心后缀MAILCHIMP_API_KEY必须包含-us8、-eu2这类后缀CLI 会自动从中解析机房前缀无需手工配置 base URL。速率限制Marketing API 限制为 10 个并发连接外加账号级滚动限额批量写入场景应使用batches资源组走 Batch API而不是并发发起大量单条请求。分页默认值集合命令的count默认 10、最大 1000CLI 不自动翻页需要全量数据时请显式翻页或使用分页工具。十一、质量保障测试布局仓库为该 harness 提供了两级测试分别位于 tests/单元测试 test_core.py无需 API Key 即可运行。覆盖客户端地址推导与认证、subscriber_hash归一化、缺 Key 时报错退出、基于responses库 mock 的 GET/POST/DELETE 与错误处理、分页边界、输出模块的 JSON 模式以及大批“生成代码回归”用例30 个资源组可导入、命令必须带--extra-params、别名与真实 HTTP 路径一致、非法 JSON 报 Click 错误而非 Traceback 等。端到端测试 test_full_e2e.py包含 9 个真实链路用例以是否设置MAILCHIMP_API_KEY为门槛决定是否执行。若你希望进一步深入命令细节可直接阅读随包分发的完整命令参考 skills/SKILL.md也随包安装见 setup.py 的package_data或查看某资源组生成源码如 lists.py、campaigns.py。结合本文的架构说明与命令表格你可以把cli-anything-mailchimp无缝嵌入到 Shell 脚本、CI 管道或 Agent 工具调用中以统一的命令行界面驱动 Mailchimp 的营销自动化能力。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考