AgentSkillsCN

swiftui-api-gap

自动生成并持续维护 SwiftUI 与 Raven 的确定性 API 对齐报告及自动化工具。当用户请求审计缺失的 SwiftUI 组件或 API、更新覆盖率报告、降低报告噪音、优化匹配逻辑（如按所有者限定名称、构造函数、运算符进行匹配），或更新每周通过 GitHub Actions 自动化发布的 PR 工作流——该工作流会将 Reports/swiftui-api-gap/gap_report.md 文件推送到仓库中时，即可使用此技能。

SKILL.md
--- frontmatter
name: swiftui-api-gap
description: Generate and maintain deterministic SwiftUI-vs-Raven API parity reports and automation. Use when users ask to audit missing SwiftUI components/APIs, refresh coverage reports, reduce report noise, tune matching logic (owner-qualified names, constructors, operators), or update the weekly GitHub Actions PR workflow that publishes Reports/swiftui-api-gap/gap_report.md.

SwiftUI API Gap

Overview

Use this skill to keep Raven's SwiftUI parity tracking deterministic, actionable, and automated.

Primary implementation files:

  • •Scripts/swiftui_api_gap_report.py
  • •.github/workflows/swiftui-api-gap-report.yml
  • •Documentation/SwiftUI-API-Gap-Automation.md

Primary artifact:

  • •Reports/swiftui-api-gap/gap_report.md

Workflow

  1. •Run report generation.
bash
Scripts/swiftui_api_gap_report.py --repo-root . --output-dir Reports/swiftui-api-gap
  1. •Validate outputs exist.
bash
ls -lh Reports/swiftui-api-gap
  1. •Check report quality quickly.
  • •Confirm summary section has counts and coverage.
  • •Confirm named APIs are separate from operator-like overloads.
  • •Confirm constructor coverage is owner-qualified (Type.init) and not globally skipped.
  1. •If asked to improve actionability, prioritize:
  • •Owner-qualified matching for members (Type.func, Type.var, Type.init).
  • •Noise separation for operator-like signatures.
  • •Stable high-signal lists for components/modifiers.
  • •Clear markdown sections that humans can triage.

Automation

Weekly workflow:

  • •.github/workflows/swiftui-api-gap-report.yml
  • •Runs Monday via cron.
  • •Uses macOS runner compatible with Swift/Xcode tooling.
  • •Uploads artifact bundle.
  • •Opens/updates PR with refreshed report.

When editing automation:

  1. •Keep Reports/swiftui-api-gap/gap_report.md in add-paths for PR commits.
  2. •Keep workflow permissions at least:
    • •contents: write
    • •pull-requests: write
  3. •Keep workflow_dispatch so maintainers can run immediately.

Matching Rules

Use these rules unless user asks to change methodology:

  • •Source of truth: swift-api-digester against Apple SwiftUI module.
  • •Build SwiftUI inventory from digester output.
  • •Build Raven inventory from public declarations under Sources/Raven/**/*.swift.
  • •Match by owner-qualified member names when possible.
  • •Keep constructors scored by owner (Type.init) unless upgraded to full signature matching.
  • •Keep operator overloads summarized separately from named actionable APIs.

Troubleshooting

  • •If skill tooling scripts fail with missing yaml, use repo venv:
bash
venv/bin/python -m pip install pyyaml
  • •

    If report looks noisy, inspect:

    • •missing.operator_like in gap_report.json
    • •owner context fields in high-signal sections
  • •

    If workflow cannot be triggered remotely, ensure workflow file is committed to default branch first.