KuteSmart 海外发货地址管理

要解决的具体问题

海外运营平台对接发货地址数据时，开发者常常陷入几个典型的工程困境：

• 全链路耦合：获取地址列表的接口与创建订单、扣减库存等操作交织在同一个调用链中，导致代码难以复用、单点测试成本高；
• 调用参数混乱：开发者自行拼接 HTTP 请求参数，很容易把 Query 参数塞进 URL 路径，或者把 accessToken 遗漏在 Body 里，引发认证失败却难以定位；
• 基础地址被随意覆盖：同一套接口在测试环境和正式环境间切换时，开发者手动修改 URL，一旦忘记切换，请求就打到错误的服务器上；
• 错误处理不透明：接口返回认证失败或权限不足时，上层 Agent 往往只能看到模糊的异常，无法快速决策重试或切换租户；
• 字段被臆造：调用方为了补全业务视图，自行填充库存、价格或物流状态，制造出不存在的幽灵数据。

技能如何工作

该技能的核心目标是把地址信息列表查询拆成最小可用的原子操作，让上层 Agent 可以像搭积木一样组装发货管理流程。

• 固定正式环境地址：执行器读取 SKILL.md 中 frontmatter 声明的 base_url，调用时不从用户输入覆盖该值，从根本上避免请求被重定向到非预期环境。
• 统一参数结构：所有请求参数都封装在嵌套的 params 对象中。具体映射规则如下：

- params.path：承载 URL 路径参数；
- params.query：承载 GET 请求的查询参数；
- params.body：承载 POST/PUT 的 JSON 请求体；
- params.headers：承载额外 HTTP 头。

• 响应零臆测：接口返回什么，上层 Agent 就看到什么。该技能不会自动补全库存、价格、订单号或物流状态，所有返回字段均以 API 响应为事实来源。
• 错误透明传递：当接口返回认证失败、权限不足或参数错误时，原始错误码和错误信息会原封不动地传递给上层 Agent，由上层决定是否重试、切换租户或中止流程。

适用边界

• 本技能只处理地址信息列表查询，不负责地址的创建、更新、删除或物流状态跟踪。
• 需要组合完整发货管理链路时，必须由上层 Agent 按聚合 skill 或计划文档编排多个原子技能，例如先调用本技能获取地址列表，再调用库存扣减技能、订单创建技能。
• 调用前必须确保已获得有效登录态和租户权限。本技能不负责获取 Token，也不负责多租户隔离，这些职责由上层 Agent 或安全网关承担。
• 若需修改请求基础地址或调整认证策略，请修改 SKILL.md 中的 frontmatter 配置，而非在调用参数中覆盖。