@izzetemre
使用 ast-grep 进行基于 AST 的代码模式分析，用于发现安全性、性能和结构问题。适用场景：(1) 审查代码中的安全漏洞，(2) 分析 React hook 依赖或性能模式，(3) 在大型代码库中检测结构性反模式，(4) 需要超越人工检查的系统化模式匹配。
--- name: ast-code-analysis-superpower description: 使用 ast-grep 进行基于 AST 的代码模式分析，用于发现安全性、性能和结构问题。适用场景：(1) 审查代码中的安全漏洞，(2) 分析 React hook 依赖或性能模式，(3) 在大型代码库中检测结构性反模式，(4) 需要超越人工检查的系统化模式匹配。 --- # AST-Grep 代码分析 AST 模式匹配通过结构识别而非逐行阅读来发现代码问题。代码结构揭示了表面检查所遗漏的隐藏关系、漏洞和反模式。 ## 配置 - **目标语言**：javascript - **分析重点**：security - **严重级别**：ERROR - **框架**：React - **最大嵌套深度**：3 ## 前置条件 ```bash # 安装 ast-grep（如果尚未安装） npm install -g @ast-grep/cli # 或：mise install -g ast-grep ``` ## 决策树：何时使用 AST 分析 ``` 需要代码审查？ | +-- 简单代码（<50 行，结构明显）--> 人工审查 | +-- 复杂代码（嵌套、多文件、抽象层） | +-- 需要安全审查？--> 使用安全模式 +-- 性能分析？--> 使用性能模式 +-- 结构质量？--> 使用结构模式 +-- 跨文件模式？--> 使用 --include glob 运行 ``` ## 模式类别 | 类别 | 重点 | 常见发现 | |----------|-------|-----------------| | 安全性 | 加密函数、认证流程 | 硬编码密钥、弱令牌 | | 性能 | Hooks、循环、异步 | 无限重渲染、内存泄漏 | | 结构 | 嵌套、复杂度 | 深层条件判断、可维护性 | ## 核心模式 ### 安全性：硬编码密钥 ```yaml # sg-rules/security/hardcoded-secrets.yml id: hardcoded-secrets language: javascript rule: pattern: | const $VAR = '$LITERAL'; $FUNC($VAR, ...) meta: severity: ERROR message: "检测到潜在的硬编码密钥" ``` ### 安全性：不安全的令牌生成 ```yaml # sg-rules/security/insecure-tokens.yml id: insecure-token-generation language: javascript rule: pattern: | btoa(JSON.stringify($OBJ) + '.' + $SECRET) meta: severity: ERROR message: "使用 base64 的不安全令牌生成" ``` ### 性能：React Hook 依赖 ```yaml # sg-rules/performance/react-hook-deps.yml id: react-hook-dependency-array language: typescript rule: pattern: | useEffect(() => { $BODY }, [$FUNC]) meta: severity: WARNING message: "函数依赖可能导致无限重渲染" ``` ### 结构：深层嵌套 ```yaml # sg-rules/structure/deep-nesting.yml id: deep-nesting language: javascript rule: any: - pattern: | if ($COND1) { if ($COND2) { if ($COND3) { $BODY } } } - pattern: | for ($INIT) { for ($INIT2) { for ($INIT3) { $BODY } } } meta: severity: WARNING message: "深层嵌套（>3 层）- 考虑重构" ``` ## 运行分析 ```bash # 安全扫描 ast-grep run -r sg-rules/security/ # 对 React 文件进行性能扫描 ast-grep run -r sg-rules/performance/ --include="*.tsx,*.jsx" # 完整扫描并输出 JSON ast-grep run -r sg-rules/ --format=json > analysis-report.json # 交互模式进行调查 ast-grep run -r sg-rules/ --interactive ``` ## 模式编写检查清单 - [ ] 模式匹配特定反模式，而非通用代码 - [ ] 使用 `inside` 或 `has` 进行上下文约束 - [ ] 包含 `not` 约束以减少误报 - [ ] 按语言分别编写规则（JS 与 TS） - [ ] 适当的严重级别（ERROR/WARNING/INFO） ## 常见错误 | 错误 | 症状 | 修复 | |---------|---------|-----| | 模式过于通用 | 大量误报 | 添加上下文约束 | | 缺少 `inside` | 匹配错误位置 | 使用父级上下文限定范围 | | 没有 `not` 子句 | 匹配有效模式 | 排除已知正常情况 | | 在 TS 上使用 JS 模式 | 类型注解导致匹配失败 | 创建语言特定规则 | ## 验证步骤 1. **测试模式准确性**：在已知存在漏洞的代码样本上运行 2. **检查误报率**：人工审查前 10 个匹配项 3. **验证严重级别**：确认 ERROR 级别的发现是可操作的 4. **跨文件覆盖**：验证模式在预期范围内运行 ## 示例输出 ``` $ ast-grep run -r sg-rules/ src/components/UserProfile.jsx:15: ERROR [insecure-tokens] 不安全的令牌生成 src/hooks/useAuth.js:8: ERROR [hardcoded-secrets] 潜在的硬编码密钥 src/components/Dashboard.tsx:23: WARNING [react-hook-deps] 函数依赖 src/utils/processData.js:45: WARNING [deep-nesting] 检测到深层嵌套 发现 4 个问题（2 个错误，2 个警告） ``` ## 项目设置 ```bash # 在项目中初始化 ast-grep ast-grep init # 创建规则目录 mkdir -p sg-rules/{security,performance,structure} # 添加到 CI 流水线 # .github/workflows/lint.yml # - run: ast-grep run -r sg-rules/ --format=json ``` ## 自定义模式模板 ### React 特定模式 ```yaml # 列表渲染中缺少 key id: missing-list-key language: typescript rule: pattern: | $ARRAY.map(($ITEM) => <$COMPONENT $$$PROPS />) constraints: $PROPS: not: has: pattern: 'key={$_}' meta: severity: WARNING message: "列表渲染中缺少 key 属性" ``` ### 异步/Await 模式 ```yaml # 异步中缺少错误处理 id: unhandled-async language: javascript rule: pattern: | async function $NAME($$$) { $$$BODY } constraints: $BODY: not: has: pattern: 'try { $$$ } catch' meta: severity: WARNING message: "异步函数缺少 try-catch 错误处理" ``` ## 与 CI/CD 集成 ```yaml # GitHub Actions 示例 name: AST Analysis on: [push, pull_request] jobs: analyze: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install ast-grep run: npm install -g @ast-grep/cli - name: Run analysis run: | ast-grep run -r sg-rules/ --format=json > report.json if grep -q '"severity": "ERROR"' report.json; then echo "发现严重问题！" exit 1 fi ```
设计和实施 AWS 云架构，重点关注 Well-Architected Framework、成本优化和安全性。适用场景：1. 设计或审查 AWS 基础设施架构 2. 将工作负载迁移到 AWS 或在 AWS 服务之间迁移 3. 优化 AWS 成本（合理调整规模、预留实例、Savings Plans）4. 实施 AWS 安全、合规或灾难恢复 5. 排查 AWS 服务问题或性能问题
--- name: aws-cloud-expert description: | 设计和实现 AWS 云架构，重点关注 Well-Architected Framework、成本优化和安全性。适用于： 1. 设计或审查 AWS 基础设施架构 2. 将工作负载迁移到 AWS 或在 AWS 服务之间迁移 3. 优化 AWS 成本（合理调整规模、预留实例、Savings Plans） 4. 实施 AWS 安全、合规或灾难恢复 5. 排查 AWS 服务问题或性能问题 --- **区域**: us-east-1 **次要区域**: us-west-2 **环境**: production **VPC CIDR**: 10.0.0.0/16 **实例类型**: t3.medium # AWS 架构决策框架 ## 服务选择矩阵 | 工作负载类型 | 主要服务 | 替代方案 | 决策因素 | |---------------|-----------------|-------------|-----------------| | 无状态 API | Lambda + API Gateway | ECS Fargate | 请求持续时间 >15 分钟 -> ECS | | 有状态 Web 应用 | ECS/EKS | EC2 Auto Scaling | 容器专业知识 -> ECS/EKS | | 批处理 | Step Functions + Lambda | AWS Batch | GPU/长时间运行 -> Batch | | 实时流处理 | Kinesis Data Streams | MSK (Kafka) | 现有 Kafka -> MSK | | 静态网站 | S3 + CloudFront | Amplify | 全栈 -> Amplify | | 关系型数据库 | Aurora | RDS | 高可用性 -> Aurora | | 键值存储 | DynamoDB | ElastiCache | 亚毫秒级延迟 -> ElastiCache | | 数据仓库 | Redshift | Athena | 即席查询 -> Athena | ## 计算决策树 ``` 开始：你的工作负载模式是什么？ | +-> 事件驱动，执行时间 <15 分钟 | +-> Lambda | 考虑：内存 512MB、并发执行、冷启动 | +-> 长时间运行的容器 | +-> 需要 Kubernetes？ | +-> 是：EKS（托管）或 EC2 上的自管理 K8s | +-> 否：ECS Fargate（无服务器）或 ECS EC2（成本优化） | +-> 需要 GPU/HPC/自定义 AMI | +-> 使用适当实例系列的 EC2 | g4dn/p4d (ML)、c6i (计算)、r6i (内存)、i3en (存储) | +-> 批处理作业，基于队列 +-> 使用 Spot 实例的 AWS Batch（最高节省 90%） ``` ## 网络架构 ### VPC 设计模式 ``` production VPC (10.0.0.0/16) | +-- 公有子网 (10.0.0.0/24, 10.0.1.0/24, 10.0.2.0/24) | +-- ALB、NAT 网关、堡垒机（如需要） | +-- 私有子网 (10.0.10.0/24, 10.0.11.0/24, 10.0.12.0/24) | +-- 应用层（ECS、EC2、Lambda VPC） | +-- 数据子网 (10.0.20.0/24, 10.0.21.0/24, 10.0.22.0/24) +-- RDS、ElastiCache、其他数据存储 ``` ### 安全组规则 | 层级 | 入站来源 | 端口 | |------|--------------|-------| | ALB | 0.0.0.0/0 | 443 | | 应用 | ALB 安全组 | 8080 | | 数据 | 应用安全组 | 5432 | ### VPC 终端节点（成本优化） 始终为高流量服务创建： - S3 网关终端节点（免费） - DynamoDB 网关终端节点（免费） - 接口终端节点：ECR、Secrets Manager、SSM、CloudWatch Logs ## 成本优化检查清单 ### 立即行动（第 1 周） - [ ] 启用 Cost Explorer 并设置带警报的预算 - [ ] 审查并终止未使用的资源（Cost Explorer 空闲资源报告） - [ ] 合理调整 EC2 实例规模（AWS Compute Optimizer 建议） - [ ] 删除未附加的 EBS 卷和旧快照 - [ ] 审查 NAT 网关数据处理费用 ### 成本估算快速参考 | 资源 | 月度成本估算 | |----------|----------------------| | t3.medium（按需） | ~$30 | | t3.medium（1 年预留实例） | ~$18 | | Lambda（100 万次调用，1 秒，512MB） | ~$8 | | RDS db.t3.medium（多可用区） | ~$100 | | Aurora Serverless v2（平均 8 ACU） | ~$350 | | NAT 网关 + 100GB 数据 | ~$50 | | S3（1TB 标准） | ~$23 | | CloudFront（1TB 传输） | ~$85 | ## 安全实施 ### IAM 最佳实践 ``` 原则：最小权限，显式拒绝 1. 为应用程序使用 IAM 角色（而非用户） 2. 要求所有人类用户使用 MFA 3. 为委派管理员使用权限边界 4. 在组织级别实施 SCP 5. 使用 IAM Access Analyzer 定期进行访问审查 ``` ### IAM 策略模式示例 ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowS3BucketAccess", "Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject"], "Resource": "arn:aws:s3:::my-bucket/*", "Condition": { "StringEquals": {"aws:PrincipalTag/Environment": "production"} } } ] } ``` ### 安全检查清单 - [ ] 在所有区域启用 CloudTrail 并验证日志文件完整性 - [ ] 配置 AWS Config 规则以进行合规监控 - [ ] 启用 GuardDuty 进行威胁检测 - [ ] 使用 Secrets Manager 或 Parameter Store 存储机密（而非环境变量） - [ ] 为所有数据存储启用静态加密 - [ ] 对所有连接强制使用 TLS 1.2+ - [ ] 实施 VPC 流日志以进行网络监控 - [ ] 使用 Security Hub 获得集中安全视图 ## 高可用性模式 ### 多可用区架构（目标 99.99%） ``` 区域：us-east-1 | +-- AZ-a +-- AZ-b +-- AZ-c | | | ALB（活动） ALB（活动） ALB（活动） | | | ECS 任务（2） ECS 任务（2） ECS 任务（2） | | | Aurora 写入器 Aurora 读取器 Aurora 读取器 ``` ### 多区域架构（目标 99.999%） ``` 主区域：us-east-1 次要区域：us-west-2 | | Route 53（故障转移路由） Route 53（健康检查） | | CloudFront CloudFront | | 全栈 全栈（被动或主动） | | Aurora 全球数据库 -------> Aurora 只读副本 （异步复制） ``` ### RTO/RPO 决策矩阵 | 层级 | RTO 目标 | RPO 目标 | 策略 | |------|------------|------------|----------| | 第 1 层（关键） | <15 分钟 | <1 分钟 | 多区域主动-主动 | | 第 2 层（重要） | <1 小时 | <15 分钟 | 多区域主动-被动 | | 第 3 层（标准） | <4 小时 | <1 小时 | 多可用区加跨区域备份 | | 第 4 层（非关键） | <24 小时 | <24 小时 | 单区域，备份/恢复 | ## 监控和可观测性 ### CloudWatch 实施 | 指标类型 | 服务 | 关键指标 | |-------------|---------|-------------| | 计算 | EC2/ECS | CPUUtilization、MemoryUtilization、NetworkIn/Out | | 数据库 | RDS/Aurora | DatabaseConnections、ReadLatency，WriteLatency | | 无服务器 | Lambda | 持续时间、错误、节流、并发执行数 | | API | API Gateway | 4XX错误、5XX错误、延迟、计数 | | 存储 | S3 | 存储桶大小字节数、对象数量、4xx错误 | ### 告警阈值 | 资源 | 警告 | 严重 | 操作 | |----------|---------|----------|--------| | EC2 CPU | >70% 5分钟 | >90% 5分钟 | 横向扩展，调查 | | RDS CPU | >80% 5分钟 | >95% 5分钟 | 纵向扩展，查询优化 | | Lambda 错误 | >1% | >5% | 调查，回滚 | | ALB 5xx | >0.1% | >1% | 调查后端 | | DynamoDB 节流 | 任何 | 持续 | 增加容量 | ## 验证清单 ### 生产环境启动前 - [ ] 完成 Well-Architected 审查（全部 6 个支柱） - [ ] 完成负载测试，包含预期峰值 + 50% 余量 - [ ] 灾难恢复测试完成，并记录 RTO/RPO - [ ] 安全评估通过（如需要，进行渗透测试） - [ ] 合规控制已验证（如适用） - [ ] 监控仪表板和告警已配置 - [ ] 常见操作的运行手册已记录 - [ ] 成本预测已验证，并设置预算 - [ ] 为所有资源实施标记策略 - [ ] 备份和恢复程序已测试
测试并修复无障碍问题，以确保符合 WCAG 标准并与辅助技术兼容。适用于：(1) 审核 UI 的无障碍违规问题，(2) 实现键盘导航或屏幕阅读器支持，(3) 修复颜色对比度或焦点指示器问题，(4) 确保表单无障碍性和错误处理，(5) 创建 ARIA 实现。
--- name: accessibility-expert description: 测试并修复无障碍问题，以确保符合 WCAG 标准并兼容辅助技术。适用于以下场景：(1) 审计 UI 的无障碍违规问题，(2) 实现键盘导航或屏幕阅读器支持，(3) 修复颜色对比度或焦点指示器问题，(4) 确保表单无障碍和错误处理，(5) 创建 ARIA 实现。 --- # 无障碍测试与修复 ## 配置 - **WCAG 等级**：AA - **目标组件**：Application - **合规标准**：WCAG 2.1 - **测试范围**：full-audit - **屏幕阅读器**：NVDA ## WCAG 2.1 快速参考 ### 合规等级 | 等级 | 要求 | 常见问题 | |-------|-------------|---------------| | A | 最低基线 | 缺少替代文本、无键盘访问、缺少表单标签 | | AA | 标准目标 | 对比度 < 4.5:1、缺少焦点指示器、标题结构不佳 | | AAA | 增强 | 对比度 < 7:1、手语、扩展音频描述 | ### 四项原则（POUR） 1. **可感知**：内容可通过感官获取（替代文本、字幕、对比度） 2. **可操作**：UI 可通过所有输入方式导航（键盘、触摸、语音） 3. **可理解**：内容和 UI 可预测且可读 4. **健壮**：与当前及未来的辅助技术兼容 ## 违规严重性矩阵 ``` 严重（立即修复）： - 交互元素无法通过键盘访问 - 缺少表单标签 - 图片缺少替代文本 - 自动播放音频无控件 - 键盘陷阱 高（发布前修复）： - 对比度低于 4.5:1（文本）或 3:1（大文本） - 缺少跳转链接 - 标题层级不正确 - 焦点不可见 - 缺少错误识别 中（下个冲刺修复）： - 导航不一致 - 缺少地标 - 链接文本不佳（“点击这里”） - 缺少语言属性 - 复杂表格缺少表头 低（待办列表）： - 时间调整 - 多种查找内容的方式 - 上下文相关帮助 ``` ## 测试决策树 ``` 开始：你在测试什么？ | +-- 新组件 | +-- 有交互元素？ --> 键盘导航检查清单 | +-- 有文本内容？ --> 检查对比度 + 标题结构 | +-- 有图片？ --> 验证替代文本的适当性 | +-- 有表单？ --> 表单无障碍检查清单 | +-- 现有页面/功能 | +-- 先运行自动扫描（axe-core、Lighthouse） | +-- 手动键盘走查 | +-- 屏幕阅读器验证 | +-- 颜色对比度抽查 | +-- 第三方小部件 +-- 检查 ARIA 实现 +-- 验证键盘支持 +-- 使用屏幕阅读器测试 +-- 记录限制 ``` ## 键盘导航检查清单 ```markdown [ ] 所有交互元素可通过 Tab 键到达 [ ] Tab 顺序遵循视觉/逻辑流程 [ ] 焦点指示器可见（2px+ 轮廓，3:1 对比度） [ ] 无键盘陷阱（可从所有元素 Tab 出去） [ ] 跳转链接作为第一个可聚焦元素 [ ] Enter 激活按钮和链接 [ ] 空格激活复选框和按钮 [ ] 方向键在组件内导航（选项卡、菜单、单选组） [ ] Escape 关闭模态框和下拉菜单 [ ] 模态框在关闭前捕获焦点 ``` ## 屏幕阅读器测试模式 ### 需要验证的基本播报 ``` 交互元素： 按钮：“[标签]，按钮” 链接：“[文本]，链接” 复选框：“[标签]，复选框，[已选中/未选中]” 单选按钮：“[标签]，单选按钮，[已选择]，[位置] 共 [总数]” 组合框：“[标签]，组合框，[已折叠/已展开]” 动态内容： 加载：在容器上使用 aria-busy="true" 状态：对于非关键更新使用 role="status" 警报：对于关键消息使用 role="alert" 实时区域：aria-live="polite" 表单： 必填：“必填”随标签播报 无效：“无效输入”及错误消息 说明：通过 aria-describedby 随标签播报 ``` ### 测试顺序 1. 使用 Tab 键导航整个页面，听取播报 2. 测试标题导航（屏幕阅读器中的 H 键） 3. 测试地标导航（D 键 / 转子） 4. 测试表格（T 键，表格内方向键） 5. 测试表单（F 键，完成表单提交） 6. 测试动态内容更新（验证实时区域） ## 颜色对比度要求 | 文本类型 | 最低比率 | 增强（AAA） | |-----------|---------------|----------------| | 普通文本（<18pt） | 4.5:1 | 7:1 | | 大文本（>=18pt 或 14pt 粗体） | 3:1 | 4.5:1 | | UI 组件和图形 | 3:1 | 不适用 | | 焦点指示器 | 3:1 | 不适用 | ### 对比度检查流程 ``` 1. 识别所有前景/背景颜色对 2. 计算对比度：(L1 + 0.05) / (L2 + 0.05) 其中 L1 = 较亮亮度，L2 = 较暗亮度 3. 需要检查的常见失败： - 占位符文本（通常太浅） - 禁用状态（豁免但考虑可用性） - 文本内的链接（必须与文本区分） - 彩色背景上的错误/成功状态 - 图片上的文本（使用叠加或文本阴影） ``` ## ARIA 实现指南 ### ARIA 第一规则 尽可能使用原生 HTML 元素。ARIA 仅用于自定义小部件。 ```html <!-- 错误：在原生元素上使用 ARIA --> <div role="button" tabindex="0">提交</div> <!-- 正确：原生按钮 --> <button type="submit">提交</button> ``` ### 何时需要 ARIA ```html <!-- 自定义选项卡 --> <div role="tablist"> <button role="tab" aria-selected="true" aria-controls="panel1">选项卡 1</button> <button role="tab" aria-selected="false" aria-controls="panel2">选项卡 2</button> </div> <div role="tabpanel" id="panel1">内容 1</div> <div role="tabpanel" id="panel2" hidden>内容 2</div> <!-- 可展开部分 --> <button aria-expanded="false" aria-controls="content">显示详情</button> <div id="content" hidden>可展开内容</div> <!-- 模态对话框 --> <div role="dialog" aria-modal="true" aria-labelledby="title"> <h2 id="title">对话框标题</h2> <!-- 内容 --> </div> <!-- 用于动态更新的实时区域 --> <div aria-live="polite" aria-atomic="true"> <!-- 状态消息注入此处 --> </div> ``` ### 常见 ARIA 错误 ``` - role="button" 但无键盘支持（Enter/空格） - aria-label 与可见文本重复 - 在可聚焦元素上使用 aria-hidden="true" - 展开按钮缺少 aria-expanded - aria-controls 引用不正确 - 使用 aria-describedby 提供关键信息 ``` ## 表单无障碍模式 ### 必需的表单结构 ```html <form> <!-- 显式标签关联 --> <label for="email">电子邮件地址</label> <input type="email" id="email" name="email" aria-required="true" aria-describedby="email-hint email-error"> <span id="email-hint">我们绝不会分享您的电子邮件</span> <span id="email-error" role="alert"></span> <!-- 分组相关字段 --> <fieldset> <legend>收货地址</legend> <!-- 地址字段 --> </fieldset> <!-- 明确的提交按钮 --> <button type="submit">完成订单</button> </form> ``` ### 错误处理要求 ``` 1. 识别出错的字段（高亮 + 图标） 2. 用文字描述错误（不仅仅是颜色） 3. 将错误与字段关联（aria-describedby） 4. 向屏幕阅读器宣布错误（role="alert"） 5. 提交失败时将焦点移至第一个错误 6. 尽可能提供更正建议 ``` ## 移动端无障碍检查清单 ```markdown 触摸目标： [ ] 最小 44x44 CSS 像素 [ ] 目标之间有足够的间距（8px+） [ ] 触摸操作不依赖于手势路径 手势： [ ] 多指手势的替代方案 [ ] 基于路径的手势（滑动）的替代方案 [ ] 基于动作的操作有替代方案 屏幕阅读器（iOS/Android）： [ ] 为图像和图标设置 accessibilityLabel [ ] 为复杂交互设置 accessibilityHint [ ] accessibilityRole 与元素行为匹配 [ ] 焦点顺序遵循视觉布局 ``` ## 自动化测试集成 ### 预提交钩子 ```bash #!/bin/bash # 对更改的文件运行 axe-core npx axe-core-cli --exit src/**/*.html # 检查常见问题 grep -r "onClick.*div\|onClick.*span" src/ && \ echo "警告：非交互元素上的点击处理程序" && exit 1 ``` ### CI 流水线检查 ```yaml accessibility-audit: script: - npx pa11y-ci --config .pa11yci.json - npx lighthouse --accessibility --output=json artifacts: paths: - accessibility-report.json rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' ``` ### 最低 CI 阈值 ``` axe-core: 0 个严重违规，0 个严重违规 Lighthouse 无障碍: >= 90 pa11y: 0 个错误（警告可接受） ``` ## 修复优先级框架 ``` 优先级 1（本次冲刺）： - 阻碍用户完成任务 - 法律合规风险 - 影响许多用户 优先级 2（下次冲刺）： - 显著降低体验 - 自动化工具标记为错误 - 违反 AA 要求 优先级 3（待办）： - 轻微不便 - 仅违反 AAA - 影响边缘情况 优先级 4（增强）： - 改善所有人的可用性 - 最佳实践，而非要求 - 面向未来 ``` ## 验证检查清单 在标记无障碍工作完成之前： ```markdown 自动化： [ ] axe-core: 0 个违规 [ ] Lighthouse 无障碍: 90+ [ ] HTML 验证通过 [ ] 无控制台无障碍警告 键盘： [ ] 仅用键盘完成所有任务 [ ] 焦点始终可见 [ ] Tab 顺序合理 [ ] 无键盘陷阱 屏幕阅读器（至少测试一个）： [ ] 所有内容已宣布 [ ] 交互元素已标记 [ ] 错误和更新已宣布 [ ] 导航高效 视觉： [ ] 所有文本通过对比度 [ ] UI 组件通过对比度 [ ] 在 200% 缩放下工作 [ ] 在高对比度模式下工作 [ ] 无引发癫痫的闪烁 表单： [ ] 所有字段已标记 [ ] 错误可识别 [ ] 必填字段已指示 [ ] 说明可用 ``` ## 文档模板 ```markdown # 无障碍声明 ## 符合性状态 本[网站/应用程序] [完全/部分] 符合 WCAG 2.1 AA 级。 ## 已知限制 | 功能 | 问题 | 解决方法 | 时间线 | |---------|-------|------------|----------| | [功能] | [描述] | [替代方案] | [修复日期] | ## 测试的辅助技术 - NVDA [版本] 与 Firefox [版本] - VoiceOver 与 Safari [版本] - JAWS [版本] 与 Chrome [版本] ## 反馈 联系 [电子邮件] 报告无障碍问题。 最后更新：[日期] ```
对 Web 应用程序执行 WCAG 合规性审计和无障碍修复。适用场景：1) 审计 UI 是否符合 WCAG 2.1/2.2 2) 修复屏幕阅读器或键盘导航问题 3) 正确实现 ARIA 模式 4) 审查颜色对比度和视觉无障碍性 5) 创建无障碍表单或交互组件
--- name: accessibility-testing-superpower description: | 为 Web 应用程序执行 WCAG 合规性审计和无障碍修复。 使用场景：1) 审计 UI 是否符合 WCAG 2.1/2.2 2) 修复屏幕阅读器或键盘导航问题 3) 正确实现 ARIA 模式 4) 审查颜色对比度和视觉无障碍性 5) 创建无障碍表单或交互组件 --- # 无障碍测试工作流 ## 配置 - **WCAG 等级**: AA - **被测组件**: Page - **合规标准**: WCAG 2.1 - **最低 Lighthouse 分数**: 90 - **主要屏幕阅读器**: NVDA - **测试框架**: jest-axe ## 审计决策树 ``` 收到无障碍请求 | +-- 新组件/页面？ | +-- 先运行自动化扫描（axe-core、Lighthouse） | +-- 键盘导航测试 | +-- 屏幕阅读器播报检查 | +-- 颜色对比度验证 | +-- 要修复现有违规？ | +-- 识别 WCAG 成功标准 | +-- 检查语义 HTML 是否能解决 | +-- 仅在 HTML 不足时应用 ARIA | +-- 使用辅助技术验证修复 | +-- 合规审计？ +-- 自动化扫描（捕获约 30% 的问题） +-- 手动测试清单 +-- 按严重程度记录违规 +-- 创建修复路线图 ``` ## WCAG 快速参考 ### 严重程度分类 | 严重程度 | 影响 | 示例 | 修复时间线 | |----------|--------|----------|--------------| | 严重 | 完全阻止访问 | 无键盘焦点、空按钮、功能图像缺少 alt | 立即 | | 重要 | 主要障碍 | 对比度差、缺少表单标签、无跳过链接 | 冲刺内 | | 中等 | 困难但可用 | 导航不一致、错误消息不清晰 | 下个版本 | | 轻微 | 不便 | 冗余 alt 文本、轻微的标题顺序问题 | 待办列表 | ### 常见违规及修复 **缺少可访问名称** ```html <!-- 违规 --> <button><svg>...</svg></button> <!-- 修复：aria-label --> <button aria-label="关闭对话框"><svg>...</svg></button> <!-- 修复：视觉隐藏文本 --> <button><span class="sr-only">关闭对话框</span><svg>...</svg></button> ``` **表单标签关联** ```html <!-- 违规 --> <label>Email</label> <input type="email"> <!-- 修复：显式关联 --> <label for="email">Email</label> <input type="email" id="email"> <!-- 修复：隐式关联 --> <label>Email <input type="email"></label> ``` **颜色对比度失败** ``` 最低比率（WCAG AA）： - 正常文本（<18px 或 <14px 粗体）：4.5:1 - 大文本（>=18px 或 >=14px 粗体）：3:1 - UI 组件和图形：3:1 工具：WebAIM Contrast Checker、浏览器 DevTools ``` **焦点可见性** ```css /* 永远不要在没有替代方案的情况下这样做 */ :focus { outline: none; } /* 正确的自定义焦点 */ :focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; } ``` ## ARIA 决策框架 ``` 需要向辅助技术传达信息？ | +-- 语义 HTML 能做到吗？ | +-- 是：使用 HTML（<button>、<nav>、<main>、<article>） | +-- 否：继续使用 ARIA | +-- 需要哪种类型的 ARIA？ +-- 角色：这个元素是什么？（role="dialog"、role="tab"） +-- 状态：什么条件？（aria-expanded、aria-checked） +-- 属性：什么关系？（aria-labelledby、aria-describedby） +-- 实时区域：动态内容？（aria-live="polite"） ``` ### 常见部件的 ARIA 模式 **展开/收起（显示/隐藏）** ```html <button aria-expanded="false" aria-controls="content-1"> 显示详情 </button> <div id="content-1" hidden> 内容在此 </div> ``` **标签页界面** ```html <div role="tablist" aria-label="Settings"> <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1"> 常规 </button> <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1"> 隐私 </button> </div> <div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div> <div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div> ``` **模态对话框** ```html <div role="dialog" aria-modal="true" aria-labelledby="dialog-title"> <h2 id="dialog-title">确认操作</h2> <p>您确定要继续吗？</p> <button>取消</button> <button>确认</button> </div> ``` ## 键盘导航清单 ``` [ ] 所有交互元素可通过 Tab 键聚焦 [ ] 焦点顺序与视觉/逻辑顺序一致 [ ] 所有元素焦点可见 [ ] 无键盘陷阱（始终可以 Tab 出去） [ ] 跳过链接作为第一个可聚焦元素 [ ] Escape 关闭模态框/下拉菜单 [ ] 方向键在部件内导航（标签页、菜单、网格） [ ] Enter/Space 激活按钮和链接 [ ] 自定义快捷键已记录且可配置 ``` ### 焦点管理模式 **模态焦点陷阱** ```javascript // 打开模态框时： // 1. 保存之前聚焦的元素 // 2. 将焦点移动到模态框中的第一个可聚焦元素 // 3. 在模态框边界内捕获 Tab // 关闭模态框时： // 1. 将焦点返回到保存的元素 ``` **动态内容** ```javascript // 添加内容后： // - 通过 aria-live 区域播报，或 // - 将焦点移动到新内容标题 // 移除内容后： // - 将焦点移动到逻辑上的下一个元素 // - 永远不要将焦点留在已移除的元素上 ``` ## 屏幕阅读器测试 ### 播报验证 | 元素 | 应播报 | |---------|-----------------| | 按钮 | 角色 + 名称 + 状态（"提交按钮"） | | 链接 | 名称 + "链接"（"主页链接"） | | 图像 | Alt 文本或 "装饰性"（跳过） | | 标题 | 级别 + 文本（"标题级别 2，关于我们"） | | 表单字段 | 标签 + 类型 + 状态 + 说明 | | 错误 | 错误消息 + 字段关联 | ### 测试命令（快速参考） **VoiceOver (macOS)** - VO = Ctrl + Option - VO + A：朗读全部 - VO + 右/左：导航元素 - VO + Cmd + H：下一个标题 - VO + Cmd + J：下一个表单控件 **NVDA (Windows)** - NVDA + 下：朗读全部 - Tab：下一个可聚焦元素 - H：下一个标题 - F：下一个表单字段 - B：下一个按钮 ## 自动化测试集成 ### 测试中的 axe-core ```javascript // jest-axe import { axe, toHaveNoViolations } from 'jest-axe'; expect.extend(toHaveNoViolations); test('component 是无障碍的', async () => { const { container } = render(<MyComponent />); const results = await axe(container); expect(results).toHaveNoViolations(); }); ``` ### Lighthouse CI 阈值 ```javascript // lighthouserc.js module.exports = { assertions: { 'categories:accessibility': ['error', { minScore: 90 / 100 }], }, }; ``` ## 修复优先级矩阵 ``` 影响 vs 努力： 低投入 高投入 高影响 | 优先执行 | 计划后续 | | 替代文本 | 重新设计 | | 标签 | 导航重建 | ----------------|--------------|---------------| 低影响 | 快速见效 | 待办清单 | | 对比度 | 锦上添花 | | 微调 | 增强功能 | ``` ## 验证清单 在将无障碍工作标记为完成之前： ``` 自动化测试： [ ] axe-core 报告零违规 [ ] Lighthouse 无障碍评分 >= 90 [ ] HTML 验证器通过（影响辅助技术解析） 键盘测试： [ ] 无需鼠标即可完成全部任务 [ ] 焦点始终可见 [ ] 逻辑 Tab 顺序 [ ] 无焦点陷阱 屏幕阅读器测试： [ ] 已使用至少一种屏幕阅读器测试（NVDA） [ ] 所有内容均正确播报 [ ] 交互元素具有角色/状态 [ ] 动态更新已播报 视觉测试： [ ] 对比度已验证（最低 4.5:1） [ ] 在 200% 缩放下正常工作 [ ] 无仅靠颜色传达的信息 [ ] 遵循 prefers-reduced-motion ```
多智能体编排技能，用于团队组建、任务分解、工作流优化和协调策略，以实现最佳团队性能和资源利用率。
--- name: agent-organization-expert description: 多智能体编排技能，用于团队组建、任务分解、工作流优化和协调策略，以实现最佳团队性能和资源利用率。 --- # 智能体组织 通过系统化任务分析、能力映射和工作流设计，组建并协调多智能体团队。 ## 配置 - **智能体数量**：3 - **任务类型**：general - **编排模式**：parallel - **最大并发数**：5 - **超时（秒）**：300 - **重试次数**：3 ## 核心流程 1. **分析需求**：理解任务范围、约束和成功标准 2. **映射能力**：将可用智能体与所需技能匹配 3. **设计工作流**：创建包含依赖关系和检查点的执行计划 4. **编排执行**：协调 3 个智能体并监控进度 5. **持续优化**：根据性能反馈进行调整 ## 任务分解 ### 需求分析 - 将复杂任务分解为离散的子任务 - 确定每个子任务的输入/输出要求 - 估算每个组件的复杂度和资源需求 - 为每个单元定义明确的成功标准 ### 依赖映射 - 记录任务执行顺序约束 - 识别子任务之间的数据依赖关系 - 映射资源共享需求 - 检测潜在瓶颈和冲突 ### 时间线规划 - 按依赖关系对任务排序 - 识别并行化机会（最多 5 个并发） - 为高风险组件分配缓冲时间 - 定义用于进度验证的检查点 ## 智能体选择 ### 能力匹配 根据以下因素选择智能体： - 所需技能与智能体专长 - 在类似任务上的历史表现 - 当前可用性和工作负载容量 - 针对任务复杂度的成本效率 ### 选择标准优先级 1. **能力契合度**：智能体必须具备所需技能 2. **过往记录**：优先选择有成功经验的智能体 3. **可用性**：有足够容量按时完成 4. **成本**：在约束内优化资源利用 ### 备份规划 - 为关键角色确定替代智能体 - 定义故障转移触发条件和交接程序 - 为单点故障任务保持冗余 ## 团队组建 ### 组成原则 - 确保所有子任务的技能覆盖完整 - 在 3 名团队成员之间平衡工作负载 - 最小化沟通开销 - 为关键功能包含冗余 ### 角色分配 - 根据优势将智能体匹配到子任务 - 定义明确的所有权和问责制 - 在依赖角色之间建立沟通渠道 - 记录阻塞问题的升级路径 ### 团队规模 - 紧密耦合的任务使用较小团队 - 可并行的工作负载使用较大团队 - 在规模决策中考虑协调开销 - 根据进度动态调整规模 ## 编排模式 ### 顺序执行 当任务有严格顺序要求时使用： - 任务 B 需要任务 A 的输出 - 步骤之间状态必须一致 - 错误处理需要有序回滚 ### 并行处理 当任务相互独立时使用（parallel）： - 任务之间没有数据依赖 - 资源需求相互独立 - 结果可在完成后聚合 - 最多 5 个并发操作 ### 流水线模式 用于流式或连续处理： - 每个阶段处理并转发结果 - 支持不同阶段的并发执行 - 降低多步骤工作流的整体延迟 ### 分层委托 用于需要子编排的复杂任务： - 主智能体协调子团队 - 每个子团队处理一个领域 - 结果通过层级向上聚合 ### Map-Reduce 用于大规模数据处理： - Map 阶段将工作分配给各智能体 - 每个智能体处理一个分区 - Reduce 阶段合并结果 ## 工作流设计 ### 流程结构 1. **入口点**：验证输入并初始化状态 2. **执行阶段**：有序的任务分组 3. **检查点**：状态持久化和验证点 4. **出口点**：结果聚合和清理 ### 控制流 - 为替代路径定义分支条件 - 为瞬时故障指定重试策略（最多 3 次重试） - 为每个阶段建立超时阈值（默认 300 秒） - 为部分失败规划优雅降级 ### 数据流 - 记录阶段之间的数据转换 - 指定数据格式和验证规则 - 规划检查点处的数据持久化 - 处理完成后的数据清理 ## 协调策略 ### 通信模式 - **直接**：智能体到智能体，用于紧密耦合 - **广播**：一对多，用于状态更新 - **基于队列**：异步，用于解耦任务 - **事件驱动**：对状态变化做出反应 ### 同步 - 为依赖任务定义同步点 - 实现带超时的等待机制（300 秒） - 优雅处理乱序完成 - 在智能体之间保持状态一致 ### 冲突解决 - 为资源争用建立优先级规则 - 为冲突定义仲裁机制 - 记录死锁的回滚程序 - 通过仔细调度预防冲突 ## 性能优化 ### 负载均衡 - 根据智能体容量分配工作 - 监控利用率并动态重新平衡 - 避免使高性能智能体过载 - 对数据密集型任务考虑智能体本地性 ### 瓶颈管理 - 通过监控识别慢速阶段 - 为受限资源增加容量 - 重构工作流以减少依赖 - 在有益时缓存中间结果 ### 资源效率 - 在智能体之间池化共享资源 - 使用后及时释放资源 - 批处理类似操作以减少开销 - 监控并告警资源浪费 ## 监控与适应 ### 进度跟踪 - 监控每个任务的完成状态 - 跟踪实际耗时与估算的对比 - 识别有延迟风险的任务 - 向利益相关者报告聚合进度 ### 性能指标 - 任务完成率和延迟 - 智能体利用率和吞吐量 - 错误率和恢复时间 - 资源消耗和成本 ### 动态调整 - 根据进度重新分配智能体 - 根据阻塞问题调整优先级 - 根据工作负载调整团队规模 - 根据学习结果修改工作流 ## 错误处理 ### 故障检测 - 监控任务失败和超时（300 秒阈值） - 及时检测智能体不可用 - 识别级联故障模式 - 对异常行为发出告警 ### 恢复程序 - 使用退避重试瞬时故障（最多 3 次尝mpts) - 需要时故障转移到备用代理 - 关键故障时回滚到上一个检查点 - 升级无法恢复的问题 ### 预防 - 执行前验证输入 - 分配前测试代理可用性 - 设计优雅降级 - 在关键路径中构建冗余 ## 质量保证 ### 验证关卡 - 在每个检查点验证输出 - 交叉检查并行任务的结果 - 验证最终聚合结果 - 确认满足成功标准 ### 性能标准 - 代理选择准确率目标：>95% - 任务完成率目标：>99% - 响应时间目标：<5 秒 - 资源利用率：最佳范围 60-80% ## 最佳实践 ### 规划 - 投入时间进行彻底的任务分析 - 记录假设和约束 - 预先规划故障场景 - 定义明确的成功指标 ### 执行 - 从最小可行团队开始（3 个代理） - 根据观察到的需求进行扩展 - 保持清晰的沟通渠道 - 对照里程碑跟踪进度 ### 学习 - 捕获性能数据以供分析 - 识别成功和失败的模式 - 优化选择和协调策略 - 在未来的编排中分享经验教训
