financial-services dry-run模式：部署前校验POST请求体的正确姿势-酒店常州论坛

financial-services dry-run模式：部署前校验POST请求体的正确姿势

【免费下载链接】financial-services项目地址: https://gitcode.com/GitHub_Trending/fi/financial-services

在financial-services开源项目中，部署 Claude Managed Agent 模板需要向POST /v1/agents提交一份解析后的 JSON 请求体。想避免"技能传错、系统提示为空、子代理层级越界"这类线上事故？dry-run 模式就是答案：它不发任何真实请求、不需要 API Key，就能把最终要 POST 的完整请求体解析出来供你逐字段校验。🛡️

为什么部署前必须校验 POST 请求体？

这个仓库的每个金融代理（GL 对账员、Pitch 投手、KYC 审查员等）都以"配方"（cookbook）形式存放在 managed-agent-cookbooks/ 目录下，部署由 scripts/deploy-managed-agent.sh 一键完成。

但配方里的 agent.yaml 用的是语法糖写法，真实请求体要经过脚本转换才能生成。一旦真实部署，脚本会按顺序执行：

上传技能包（zip 打包后 POST 到/v1/skills，拿回skill_id）
递归创建叶子子代理（callable_agents中的每个 manifest）
最后 POST 编排器本体到/v1/agents

这意味着：如果配方里system.file路径写错、技能目录不存在、或${MCP_URL}环境变量没设，错误要到真实部署时才会暴露，且部分资源已经创建，很难回滚。

dry-run 模式正好卡在"转换之后、POST 之前"，把最终请求体完整打印给你审。

三步上手：最快完成 dry-run 校验

第 1 步：克隆仓库

git clone https://gitcode.com/GitHub_Trending/fi/financial-services cd financial-services

第 2 步：确认依赖

dry-run 只做本地解析，依赖很轻：jq+python3（含pyyaml）。脚本启动时会自检，缺失会直接报错退出（见 scripts/deploy-managed-agent.sh）。

第 3 步：加`--dry-run`参数

bash scripts/deploy-managed-agent.sh gl-reconciler --dry-run

就这么简单。注意一个关键细节：dry-run 模式下无需设置ANTHROPIC_API_KEY——脚本只有在真实部署时才强制要求密钥（scripts/deploy-managed-agent.sh#L22）。也就是说，你甚至可以在没有 API 权限的 CI 机器上跑校验。

dry-run 到底校验了哪 4 件事？

脚本在 scripts/deploy-managed-agent.sh#L164-L187 实现了 dry-run 分支，它完整走一遍"配方 → 请求体"的解析流水线：

#	解析动作	校验点
1	`system: {file: ...}`内联	系统提示文件必须真实存在，否则直接报错退出（L127-L129）
2	`skills: [{from_plugin: ...}]`展开	目录下每个`skills/`都会被"上传"；dry-run 时替换为`DRYRUN_<技能名>`占位符，不产生真实 skill_id*（L67-L71）
3	`callable_agents`递归解析	子代理先于编排器解析，`output_schema`等纯配方字段在进请求体前被`del`掉
4	`${ENV_VAR}`环境变量替换	值若含非法字符（`[A-Za-z0-9._/:@-]`之外）会拒绝替换并退出，防止注入

如何读懂 dry-run 输出？

执行后你会看到这样的结构：

# --dry-run: resolved POST /v1/agents bodies (subagents first, orchestrator last) [ { ...reader... }, { ...critic... }, { ...resolver... }, { ...gl-reconciler... } ]

三个阅读要点：

顺序即层级：数组里先是所有子代理，最后一个是编排器本体（scripts/deploy-managed-agent.sh#L183-L184），对应"先建叶子、后建父节点"的真实部署顺序。
DRYRUN_前缀是占位符：所有skill_id、子代理id都以DRYRUN_开头，看到它们说明该处将在真实部署时被真实 ID 替换，不要把 dry-run 输出直接当请求体发出去。
顶层是合法 JSON 数组：可以直接管道给jq做进一步断言，例如bash scripts/deploy-managed-agent.sh gl-reconciler --dry-run | tail -n +2 | jq 'last.name'。

💡 提示：#开头那行是注释性 header，管道给 jq 前记得tail -n +2跳过——仓库自己的测试脚本就是这么做的。

进阶：用 test-cookbooks.sh 做批量回归校验

单看输出是"人眼校验"，仓库还配了一个更狠的自动化方案：scripts/test-cookbooks.sh。

它遍历 managed-agent-cookbooks/ 下全部 10 个配方，对每个执行 dry-run，并用 Python 断言请求体满足 4 条硬规则（scripts/test-cookbooks.sh#L10-L26）：

✅ 输出是合法 JSON
✅ 每个请求体system非空（系统提示没丢）
✅ 子代理不含callable_agents（委托层级 ≤ 1，防止深度越界）
✅ 全文档搜不到output_schema泄漏进请求体

任一失败，脚本以非零码退出——天生适配 CI。你修改任何agent.yaml后跑一遍它，等于对 POST 请求体做了一次回归测试。

校验通过后：从 dry-run 切换到真实部署

# 1. 校验（无密钥） bash scripts/deploy-managed-agent.sh gl-reconciler --dry-run # 2. 真实部署（需要密钥 + 环境变量如 GL_MCP_URL、SUBLEDGER_MCP_URL） export ANTHROPIC_API_KEY=sk-ant-... bash scripts/deploy-managed-agent.sh gl-reconciler

真实部署成功后，脚本会回显agent id和控制台链接（scripts/deploy-managed-agent.sh#L189-L194）。建议养成"先 dry-run 看请求体，再真实部署"的两段式习惯，把配置错误拦截在 API 调用之前。

速查表：配方写法 → 请求体解析结果

来自 managed-agent-cookbooks/README.md 的官方映射表，dry-run 输出就是按这张表解析的：

配方写法（agent.yaml）	解析为（POST 请求体）
`system: {file: ..., append: "..."}`	`system: "<文件内容 + 追加文本>"`
`system: {text: "..."}`	`system: "<text>"`
`skills: [{from_plugin: ...}]`	上传每个`skills/*`→`[{type: custom, skill_id: ...}]`
`callable_agents: [{manifest: ...}]`	先创建 →`[{type: agent, id: ..., version: latest}]`

关键文件导航：

部署脚本与 dry-run 实现：scripts/deploy-managed-agent.sh
批量校验脚本：scripts/test-cookbooks.sh
配方总览与映射规则：managed-agent-cookbooks/README.md
带output_schema的子代理示例：managed-agent-cookbooks/gl-reconciler/subagents/reader.yaml
项目入口文档：README.md

常见问题

Q1：dry-run 输出能直接发给 API 吗？不能。里面的skill_id、子代理id都是DRYRUN_占位符，必须去掉--dry-run真实执行后由 API 分配真实 ID。

Q2：dry-run 需要网络吗？不需要。它不产生任何 HTTP 请求，纯本地解析，断网也能跑。

Q3：如何校验自定义的新配方？把新目录放进managed-agent-cookbooks/后，直接bash scripts/deploy-managed-agent.sh <新slug> --dry-run；也可以跑bash scripts/test-cookbooks.sh让它自动纳入全量回归。

Q4：dry-run 会检查 MCP 服务器连通性吗？不会。${MCP_URL}只做字符白名单校验，不发起连接探测。MCP 端点可用性需要在真实部署后通过代理实际调用来验证。

掌握 dry-run 模式后，"改配方 → 本地校验 → CI 回归 → 真实部署"就成了一条可信赖的发布流水线——这正是 financial-services 这类金融场景下，对 POST 请求体做部署前校验的正确姿势。

【免费下载链接】financial-services项目地址: https://gitcode.com/GitHub_Trending/fi/financial-services

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析