# Platform Audit

> 平台能力审计 — 检索 AI IDE 最新文档，与 CataForge 平台配置进行差异分析，输出更新方案并执行修复。适用于定期对齐 Claude Code / Cursor / Codex / OpenCode 等平台的 tool / hook / agent / dispatch / sandbox / CLI / plugin / 扩展能力 / agent配置 / 平台特性 / 权限模型 / 模型路由 能力变化，确保 profile.yaml、adapter 源码、hook bridge、conformance 检查、测试用例保持最新。当用户提到平台升级、能力变化、profile 过期、跨平台兼容性检查、新增平台接入时，务必使用此 skill。

- Skill: `lync-cyber/platform-audit` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add lync-cyber/platform-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/platform-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/platform-audit

---


# 平台能力审计 (platform-audit)

## 能力边界
- 能做: 检索各 AI IDE 最新能力文档、与现有 profile.yaml 差异分析、更新配置/源码/测试、运行合规检查
- 不做: 新增全新平台 adapter（需先在 `src/cataforge/adapter/platform/` 创建 adapter 类）、修改核心调度逻辑、审查 `.cataforge/` 下框架内部 agents/skills/hooks（由 framework-review 负责）

## 设计原理

CataForge 通过多层抽象覆盖 AI IDE 的能力差异:

1. **核心能力 ID** (`CAPABILITY_IDS`) — 工具级映射（file_read, shell_exec, agent_dispatch 等；其中 `OPTIONAL_CAPABILITY_IDS` 所列项可选）
2. **扩展能力 ID** (`EXTENDED_CAPABILITY_IDS`) — 部分平台独有的工具（notebook_edit, browser_preview, image_input, code_review）
3. **Agent 配置** (`AGENT_FRONTMATTER_FIELDS`) — agent 定义 frontmatter 字段的跨平台超集
4. **平台特性** (`PLATFORM_FEATURES`) — boolean 功能标志（cloud_agents, agent_teams, scheduled_tasks 等；清单与计数以 `types.py` 为准）
5. **权限模型** — 审批模式集，各平台在 `profile.yaml` 的 `permissions.modes` 声明所支持的子集
6. **模型路由** — 可用模型列表和 per-agent 模型选择支持
7. **Hook 事件** — 5 个标准事件 + 降级策略

每个平台通过 `profile.yaml` 声明它如何映射这些抽象。平台版本快速迭代，工具名称/hook 事件/agent 格式/功能特性随时可能变化（各平台当前能力快照见 [`references/capability-matrix.md`](references/capability-matrix.md)）。本 skill 将"检索 → 对比 → 更新 → 验证"的完整审计流程标准化，防止配置漂移。

## 输入规范
调用方提供:
- **审计范围**: 平台 ID 列表（默认 all = claude-code, cursor, codex, opencode）
- **关注维度**: tools / hooks / dispatch / agent / features / permissions / models / mcp（默认全部）
- **触发原因**（可选）: 如"Cursor 刚发布 v3.2"或"Codex 新增了沙箱模式"

## 输出规范
- 差异分析报告（结构化 Markdown）
- 更新后的 `profile.yaml` 文件
- 必要时更新的源码文件（adapter / bridge / types / conformance）
- 更新后的测试文件
- 合规检查（含扩展合规）+ 测试套件通过确认

---

## 操作指令

| 模式 | 适用场景 | 详见 |
|------|---------|------|
| **full** | 定期对齐（建议每月一次）或已知某平台有重大版本更新 | 指令 1 |
| **quick-check** | 只想知道当前配置是否过期，不执行修改 | 指令 2 |
| **deep `<platform_id>`** | 某平台刚发布重大更新，需深度审计 | 指令 3 |
| **evaluate `<platform_name>`** | 评估新 AI IDE 是否可接入（不修改仓库内任何文件，输出可行性报告供决策） | `references/evaluate-new-platform.md` |
| **offline** | CI / 本地静态门禁：不联网、不需 LLM，只跑可执行的合规子集 | 指令 4 |

---

### 指令1: 完整审计 (full)

#### Phase 1: 文档检索与情报收集

> 此阶段的目标是建立每个平台的**最新能力快照**。不要依赖训练数据——平台更新非常频繁，profile.yaml 可能已经过期数月。

**Step 1: 读取当前配置基线**

并行读取所有目标平台的 `profile.yaml` (`.cataforge/platforms/<platform_id>/profile.yaml`)，提取并记录每个平台当前的:

- `version_tested` — 上次审计的版本号
- `tool_map` / `extended_capabilities` — 类型化 capability binding
- `agent_config.supported_fields` / `memory_scopes` / `isolation_modes` — agent 配置
- `features` — 17 个平台特性 flag
- `permissions.modes` — 支持的审批模式
- `model_routing` — 模型路由配置
- `hooks.event_map` / capability `hook_matchers` / `hooks.policies` — hook 配置
- `agent_definition` — agent 格式和扫描目录
- `dispatch` — 调度方式和参数

**Step 2: 检索最新平台文档**

对每个目标平台，使用 WebSearch + WebFetch 获取**最新官方文档**。搜索策略（按优先级）:

1. 先尝试 ctx7 CLI（如果可用）:
   ```bash
   npx ctx7@latest library "<platform>" "tools hooks agent SDK"
   npx ctx7@latest docs "<libraryId>" "tool names hook events agent format"
   ```

2. 若 ctx7 不可用或结果不足，使用 WebSearch — 搜索词模板见 `references/platform-sources.md`，每个平台至少覆盖: 官方文档站、GitHub repo（README / CHANGELOG）、SDK reference

3. WebFetch 关键文档页面，提取: 工具/tool 列表、hook/lifecycle 事件、agent 定义格式、agent 高级特性（memory, isolation, model, effort, skills, mcpServers）、平台特性、权限/审批模式、可用模型、CLI 命令变化、沙箱模式、插件/extension 机制、MCP 配置格式、上下文窗口和模型版本

> 检索要点: 关注**工具名称的精确拼写**（大小写敏感）、**新增/移除/重命名的事件**、**配置文件路径变化**、**新增的 agent frontmatter 字段**、**新增的平台特性**。

**Step 3: 整理平台能力快照**

为每个平台填写 `references/snapshot-template.md` 的快照模板（**不写文件，保持在上下文中**），作为 Phase 2 差异对比的输入。

#### Phase 2: 差异分析

**Step 4: 逐维度对比**

对比 Phase 1 的快照与当前 profile.yaml，按以下维度逐一检查:

| 维度 | 对比项 | 影响级别判定 |
|------|--------|-------------|
| **tool_map** | tool / kind / availability / hook_matchers 变化 | CRITICAL: 原生工具或 matcher 名称错误; MAJOR: 新增原生或条件能力; MINOR: unsupported 不变 |
| **extended_capabilities** | 扩展能力变化 | MAJOR: unsupported→native/replacement; MINOR: 仍 unsupported |
| **agent_config.supported_fields** | 支持字段变化 | MAJOR: 新增可支持字段; MINOR: 已声明字段不变 |
| **agent_config.memory_scopes** | memory scope 变化 | MAJOR: 新增 scope; MINOR: 不变 |
| **features** | 特性 flag 变化 | MAJOR: false→true（平台新增特性）; MINOR: 不变或 true→false |
| **permissions.modes** | 审批模式变化 | MAJOR: 新增模式; MINOR: 不变 |
| **model_routing** | 模型列表变化 | MAJOR: 新增模型; MINOR: 不变 |
| **hooks.event_map** | 事件名称/新增事件 | CRITICAL: 已有事件名变更; MAJOR: 新增可用事件 |
| **capability hook_matchers** | matcher 名称变化 | CRITICAL: matcher 名称与平台不符 |
| **hooks.policies** | hook mode / fallback / coverage 变化 | MAJOR: degraded→native/hybrid 可升级; CRITICAL: coverage 被错误标成 equivalent |
| **agent_definition** | 格式/路径变化 | CRITICAL: 格式不兼容; MAJOR: 路径变更 |
| **dispatch** | 调度方式/参数变化 | CRITICAL: 参数签名变更 |
| **version_tested** | 版本号过期 | INFO: 需要更新 |

**Step 5: 影响范围评估**

对每个差异项，按 [`references/audit-checklist.md`](references/audit-checklist.md) §16 源码影响矩阵定位波及文件；`profile.yaml` 几乎全部差异都涉及。

**Step 6: 输出差异报告**

按 `references/report-templates.md` 中的模板输出（直接展示给用户，不写文件）。

#### Phase 3: 执行更新

> 更新顺序很重要: profile.yaml 优先（它是所有其他文件的数据源），然后是 types.py，再是源码，最后是测试。

**Step 7: 更新 profile.yaml**

对每个需要更新的平台，按 Phase 2 的差异项更新对应字段（version_tested / tool_map / extended_capabilities / agent_config / features / permissions / model_routing / hooks / agent_definition / dispatch）。

**Step 8: 更新 types.py**

仅当需要新增跨平台抽象时:
- 新增 `EXTENDED_CAPABILITY_IDS` 条目 — 当新工具出现在 2+ 平台上
- 新增 `AGENT_FRONTMATTER_FIELDS` 条目 — 当新字段出现在 2+ 平台上
- 新增 `PLATFORM_FEATURES` 条目 — 当新特性出现在 2+ 平台上
- 调整 `OPTIONAL_CAPABILITY_IDS` — 当可选能力变为必需或反之

新增审批模式时不改 types.py — 在对应 `profile.yaml` 的 `permissions.modes` 声明即可。

**Step 9: 更新源码**

仅当差异影响到源码逻辑时才修改。常见场景:

- **新增 hook matcher**: 在对应 CapabilityBinding 的 `hook_matchers` 配置
- **_md_to_toml() 变更**: 当 Codex agent 格式变化时修改 `codex.py`
- **新增 Capability ID**: 同时更新 `types.py` 和所有 `profile.yaml`
- **conformance 逻辑**: 当检查逻辑需要适配新维度时更新 `conformance.py`
- **bridge.py**: 当 hook 生成逻辑需要适配新事件类型时
- **deployer.py**: 当部署流程需要适配新的目标路径或配置格式时
- **base.py**: 仅当新增的 profile section 需要专用 accessor 方法时

> 原则: 优先用数据驱动（profile.yaml 新增 key）而非代码驱动（新增 adapter 方法）。profile.yaml 的 features / extended_capabilities / agent_config 设计允许新增 key 而无需修改 adapter 代码。

**Step 10: 更新 dispatch-prompt.md 模板**

检查 `.cataforge/platforms/<id>/overrides/dispatch-prompt.md`:
- `<!-- OVERRIDE:tool_usage -->` 中的工具名称是否与最新 tool_map 一致
- `<!-- OVERRIDE:context_limits -->` 中的上下文窗口/模型信息是否最新
- `<!-- OVERRIDE:dispatch_syntax -->` 中的调度参数是否正确

**Step 11: 更新测试**

对每个受影响的测试文件:
1. 更新 fixture 中的 profile 数据
2. 更新断言中的预期值（工具名称 / 事件名称 / 特性 flag）
3. 如有新增能力或降级状态变化，添加对应的测试用例
4. 保持现有测试的覆盖范围不缩减

#### Phase 4: 验证

**Step 12: 运行 conformance 检查**

核心 + 扩展合规:
```bash
python -c "from cataforge.adapter.platform.conformance import check_all_conformance; print('\n'.join(check_all_conformance()))"
python -c "from cataforge.adapter.platform.conformance import check_all_extended_conformance; print('\n'.join(check_all_extended_conformance()))"
```

确认所有平台通过核心合规（FAIL=0，WARN 仅针对已知缺失的可选能力）。扩展合规的 INFO 表示该平台不支持的扩展能力/特性，属于预期行为。

**Step 13: 运行完整测试套件**

按项目指令文件 §执行环境 的测试命令（本仓为 `uv run pytest`）跑全量 tests/。

所有测试必须通过。如有失败: 分析（通常是 fixture 数据未同步更新）→ 修复 → 重跑。特别注意 `test_deployer_refactor.py` — 它使用内联 profile，不受 profile.yaml 变更影响，但 deployer 代码变更可能影响它。

**Step 14: 运行 linter**

按项目指令文件 §执行环境 的 lint 命令（本仓为 `uv run ruff check`）。

确保修改的文件无 lint 错误。预先存在的非相关文件的 lint 错误无需修复。

**Step 15: 输出审计总结**

按 `references/report-templates.md` 中的"审计完成总结"模板输出。

---

### 指令2: 快速检查 (quick-check)

适用于: 只想知道当前配置是否过期，不执行修改。

1. 读取所有目标平台的 `profile.yaml`，记录 `version_tested`
2. WebSearch 每个平台的最新版本号
3. 对比版本号，标记过期平台
4. 对过期平台执行 Phase 2 的差异分析（Step 4-6）
5. 运行核心 + 扩展合规检查
6. 输出差异报告 + 合规状态，**不执行修改**

---

### 指令3: 单平台深度审计 (deep `<platform_id>`)

适用于: 某个平台刚发布重大更新，需要深度审计该平台。

执行完整审计流程（Phase 1-4），但仅针对指定平台。额外步骤:

**附加: 交叉验证**
1. 检查该平台的 `overrides/` 目录下所有文件是否需要更新
2. 检查 `hooks.yaml` 中所有 hook 脚本在该平台的降级状态是否正确
3. 检查该平台的 `inject_mcp_config()` 实现是否与最新 MCP 配置格式兼容
4. 验证 capability binding 的 `hook_matchers` 在最新版 hook payload 中仍然有效
5. 验证 `agent_config.supported_fields` 是否完整覆盖平台最新的 agent frontmatter
6. 验证 `features` 中的 flag 是否反映平台最新发布的功能
7. 验证 `permissions.modes` 是否覆盖平台所有审批模式
8. 验证 `model_routing` 中的模型列表是否最新

---

### 指令4: 离线子集 (offline)

CI 与本地预检用的无网络子集，由 builtin 执行、不需要 LLM：

```bash
cataforge skill run platform-audit -- --offline
```

跑三项静态检查并按严重度分级退出：

- **core conformance** — 每端必需能力映射 + dispatch 声明；profile 加载失败或缺必需能力 → **阻断**（退出非 0）
- **consistency** — 跨字段/跨平台一致性（工具替换、feature↔cap 路由不可见、隔离字段缺失、native 离群声明）→ **WARN**，打印但不阻断（追踪已接受的降级）
- **profile schema** — 每端 profile.yaml 含 `_schema.yaml` 全部 required_fields；缺失 → **阻断**

`version_tested` 时效是基于 git 历史的独立周扫守卫（`check_profile_version_tested`，anti-rot.yml），不在本子集内。需联网检索 + 修复的完整审计见指令 1。

---

## 关键检查维度详解

审计需要覆盖的维度与各维度判定规则见 `references/audit-checklist.md`。以下仅列 checklist 之外的易错点:

- **名称大小写**: Claude Code 用 `Bash`，Codex 用 `shell`，OpenCode 用 `bash` — 大小写敏感
- **合并工具**: Cursor v3 将 `file_edit` 和 `file_write` 合并为同一个 `Write` 工具
- **null 语义**: `null` 表示平台不提供该能力，不是"未知" — 需确认是真的不支持还是名称未查到
- **版本号约定**: `version_tested` 记录的是**审计时的平台版本**（非 CataForge 版本），格式跟随各平台自己的版本号格式

## Anti-Patterns
- 禁止: 修改 adapter 代码而不先更新 profile.yaml —— profile 是 single source of truth；倒序修改让代码与配置漂移
- 禁止: 在 full 模式下只审单一平台 —— 平台对比矩阵价值在横向，full 模式至少 claude-code / codex / cursor 同审才能暴露能力差异；针对单平台的深度审计应走 `deep <platform_id>` 模式
- 禁止: 把 audit 报告写入 docs/reviews/code/ 或 doc/ —— 与业务审查混淆会污染 sprint-review 聚合
- 避免: 在 capability 表里用主观语义（"良好支持" / "基本可用"）—— 必须用 yes / no / partial 三态枚举，否则 deploy-time 选不出能力差异

## 效率策略
- **并行检索**: 对多个平台的文档检索应尽量并行（使用 Agent 工具分派子任务）
- **增量更新**: 如果 `version_tested` 与最新版本相同，跳过该平台（除非用户强制审计）
- **profile 优先**: 所有变更从 profile.yaml 开始，它是整个系统的 single source of truth
- **数据驱动优先**: 新增能力/特性优先在 profile.yaml 添加 key，而非修改 adapter 代码
- **测试驱动**: 先更新测试中的预期值，再修改源码，确保修改方向正确
- **最小变更**: 不重构无关代码，只更新审计发现的差异项