mizcausevic-dev/agent-card-diff

# agent-card-diff 对比两个 [A2A Agent Card](https://github.com/mizcausevic-dev/agent-cards-spec) 文档并对更改进行分类。它是 [`mcp-tools-diff`](https://github.com/mizcausevic-dev/mcp-tools-diff) 在 agent-cards 领域的对应工具。 ## 为什么需要 Agent cards 声明了 agent 的 autonomy level、memory persistence、models、tools、refusal taxonomy、evaluations 以及 incident-response posture。其中许多内容对采购和安全审查起着关键支撑作用。当 card 在两个版本之间发生变化时，**哪些更改破坏了下游运营者已经批准的信任假设？** 该库能够确定性地回答这个问题。 ## 什么被视为破坏性更改 | 更改 | 破坏性？ | 原因 | |---|---|---| | `autonomy_level` 提升（例如 supervised → autonomous） | ✅ | 超出了之前审查的权限范围 | | `memory_persistence` 提升（例如 session → persistent） | ✅ | 新增了数据保留面 | | `max_context_tokens` 减少 | ✅ | 之前可用的 prompt 可能不再适用 | | 移除 Tool | ✅ | 依赖它的调用方会出错 | | 移除 Model | ✅ | 成本或行为基准发生变化 | | 移除 Refusal category | ✅ | Agent 现在会回答之前拒绝的内容 | | 移除 `incident_response_uri` | ✅ | 在 `autonomy_level=autonomous` 时尤为严重 | | 新增 Tool / model / refusal | — | 属于增量变化 | | Description、evaluations、deployment 更改 | — | 属于文档记录，不破坏契约 | ## CLI ``` npx agent-card-diff [--format json|markdown|summary] [--strict] [--out FILE] ``` 退出代码： - `0` — 无更改，或仅有非破坏性更改 - `1` — diff 包含破坏性更改（或者指定了 `--strict` 且存在任何更改） - `2` — 用法 / I/O 错误 在 CI 中使用它来拦截 AgentCard PR：当出现破坏性更改时，`agent-card-diff old.json new.json --format summary` 会导致任务失败。 ## 库 ``` import { diffAgentCards, toMarkdown, toSummary } from "agent-card-diff"; const diff = diffAgentCards(previous, next); console.log(diff.breaking); // boolean console.log(diff.changes); // [{ reason, detail? }, …] console.log(diff.added.tools); // names of newly-listed tools console.log(diff.removed.models); // names of removed models console.log(toMarkdown(diff)); console.log(toSummary(diff)); // "BREAKING 7 changes" / "no changes" ``` ## 组合使用 - [**`agent-cards-spec`**](https://github.com/mizcausevic-dev/agent-cards-spec) — 本库进行 diff 对比时所依据的 schema。 - [**`a2a-mcp-bridge`**](https://github.com/mizcausevic-dev/a2a-mcp-bridge) — 根据 MCP server descriptors 生成 AgentCards；与该 diff 工具配合使用可拦截 bridge 的重新生成。 - [**`mcp-tools-diff`**](https://github.com/mizcausevic-dev/mcp-tools-diff) — 用于 MCP `tools/list` 快照的同源 diff 工具；结构相同，退出代码语义一致。 ## 开发 ``` npm install npm run lint && npm run typecheck && npm run coverage && npm run build npm run demo ``` ## 许可证 [AGPL-3.0-or-later](LICENSE)

标签：AI智能体, MITM代理, SOC Prime, TypeScript, 安全审查, 安全插件, 开发工具, 暗色界面, 自动化攻击, 配置比对