CLI 工作流
用 CLI 稳定转换 JSON
先检查输入形状，再编写确定性的 jq filter，验证结果后才考虑替换文件。
数据与文本本地写入
开始前准备好工具、认证与证据
先安装推荐工具，确认最小权限，再区分兼容性和真实执行记录。
复制或下载本工作流 Skill
Skill 包含输入输出合同、推荐工具、审批点、回滚和证据边界；保存前仍应按当前环境审查。
transform-json-SKILL.md
---
name: transform-json-workflow
description: "先检查输入形状，再编写确定性的 jq filter，验证结果后才考虑替换文件。"
---
# 转换 JSON
## 适用目标
按目标 schema 生成有效 JSON，同时保留原始输入。
## 证据边界
- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。
## 推荐工具、安装与认证
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
- 安装：`brew install jq`
- 认证：基础操作无需认证
- 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。
## 输入合同
- JSON 文件或数据流
- 必需输出字段
- 筛选与排序规则
- 示例记录
## 输出合同
- jq filter
- 已验证 JSON
- 变更摘要
- 可选替换文件
## 安全工作流
1. **检查数据形状** — 写 filter 前先读取类型、代表性 key 和边界情况。
- 输入: 源 JSON
- 输出: 观察到的 schema 和边界情况
- 风险: `read-only`
- 命令: `jq 'type, (if type == "array" then .[0] else keys end)' input.json`
2. **转换到新文件** — 把结果写到临时输出，不直接覆盖源文件。
- 输入: 已审查 jq filter
- 输出: 候选 JSON 文件
- 风险: `local-write`
- 命令: `jq '[.items[] | {id, name}]' input.json > output.json`
3. **验证并比较** — 解析候选文件，检查必需字段，并在替换前比较数量或校验值。
- 输入: 源文件和候选文件
- 输出: 验证与变更摘要
- 风险: `read-only`
- 命令: `jq -e 'all(.[]; has("id") and has("name"))' output.json`
## 必须先确认
- 替换已有文件
- 删除需求未明确提到的字段
- 把本地 JSON 发到远程服务
## 回滚
- 验证通过前保持源文件不变
- 从已验证临时文件原子替换
- 从版本控制或备份恢复旧文件
## 官方来源
- [jq manual](https://jqlang.github.io/jq/manual/) — 用于核对当前命令、认证、输出和操作边界。
目标、输入与输出
在 Agent 选择命令前，先明确要交付的结果和证据。
用 CLI 稳定转换 JSON：安全执行步骤
每一步都要在已声明的边界内执行，验证输出后再继续。
审批点与回滚
在列出的决策点停下，并让恢复方法始终紧跟操作。
选 CLI、MCP 还是 API？
根据执行位置、身份、输出合同与权限边界选接口。
建议方案
本地使用 jq，并把覆盖写作为独立可审查步骤。
官方证据与参考
执行前使用这些官方或上游来源确认当前命令行为。