RedHatInsights/platform-frontend-ai-toolkit
GitHub: RedHatInsights/platform-frontend-ai-toolkit
HCC前端AI工具包：助力前端开发，提升效率与质量。
Stars: 4 | Forks: 15
# HCC 前端 AI 工具包
为前端开发团队定制的 Claude Code 市场和插件仓库。
## 这是什么？
此仓库作为 **定制的 Claude Code 市场场**，提供针对不同工作流程的专业插件：
1. **前端插件** - React、TypeScript、测试和代码质量的开发工具
2. **基础设施插件** - Konflux 的 DevOps 自动化、数据库升级和密钥管理
3. **管理插件** - JIRA、报告和分析的项目管理工具
每个插件都包含针对特定用例定制的代理和 MCP 服务器，允许团队仅安装他们需要的部分。
## 入门
### 🤖 Claude Code 设置
#### 安装插件
```
# 1. 将此仓库添加到市场
/plugin marketplace add RedHatInsights/platform-frontend-ai-toolkit
# 2. 安装您需要的插件：
# - 前端开发（React、TypeScript、测试）
/plugin install frontend-plugin@hcc-frontend-toolkit
# - 基础设施/DevOps（Konflux、数据库升级、密钥）
/plugin install infrastructure-plugin@hcc-frontend-toolkit
# - 项目管理（JIRA、报告、分析）
/plugin install management-plugin@hcc-frontend-toolkit
```
**安装所有三个：**
```
/plugin install frontend-plugin infrastructure-plugin management-plugin@hcc-frontend-toolkit
```
📖 更多关于 Claude Code 插件的详细信息，请参阅 [官方插件指南](https://code.claude.com/docs/en/plugins#install-and-manage-plugins).
#### ⚠️ 重要：需要重启
**安装后，重启您的 Claude Code 会话以查看代理和其他功能。**
#### 团队配置（可选）
为了在您的团队中自动设置市场，请将以下内容添加到 `.claude/settings.json`：
```
{
"extraKnownMarketplaces": {
"hcc-frontend-toolkit": {
"source": {
"source": "github",
"repo": "RedHatInsights/platform-frontend-ai-toolkit"
}
}
}
}
```
#### 测试您的安装
安装和重启后，测试插件：
```
# 测试 hello world 代理
Task with subagent_type='hcc-frontend-hello-world' to greet the user
```
hello world 代理应将其自身识别为 HCC 前端 AI 工具包插件的一部分，确认安装成功。
## 代理开发
### 📋 开发指南
**想要创建自己的代理吗？** 请参阅我们的全面指南：[AGENT_GUIDELINES.md](AGENT_GUIDELINES.md)
此指南涵盖：
- 如何有效地规划代理（小而专注）
- 使用 Claude Code 的 `/agents` 命令进行开发
- 命名约定和最佳实践
- 优秀设计 vs. 差劣设计的代理示例
### 快速入门：创建代理
1. **使用 Claude Code** - 使用 Claude Code 中的 `/agents` 命令创建代理
2. **遵循命名约定** - 使用 `hcc-frontend-` 前缀（例如，`hcc-frontend-css-utilities`）
3. **保持专注范围** - 代理应该是小而专业的（CSS 工具、钩子测试等）
4. **使用正确的格式** - 遵循 [Claude 代理文件格式](https://code.claude.com/docs/en/sub-agents#file-format)
### 代理文件格式
代理使用 **Claude 格式**，带有 YAML 前置内容：
```
---
description: Brief description of what this agent specializes in
capabilities: ["specific-task-1", "specific-task-2", "specific-task-3"]
---
# 代理名称
Detailed description of when and how Claude should use this agent...
```
### 开发工作流程
当修改 Claude 代理时：
1. **编辑** Claude 代理文件在 `claude/agents/`
2. **转换** 到 Cursor 格式：`npm run convert-cursor`
3. **验证** 同步：`npm run check-cursor-sync`
4. **提交** Claude 和 Cursor 文件
### ⚠️ 重要：Cursor 规则同步
**当您修改 Claude 代理时，您必须在使用提交之前重新生成 Cursor 规则。**
我们的 CI 将 **自动失败** 如果 Cursor 规则与 Claude 代理不同步。
```
# 1. 编辑 Claude 代理
vim claude/agents/hcc-frontend-example.md
# 2. 重新生成游标规则
npm run convert-cursor
# 3. 确认一切同步
npm run check-cursor-sync
# 4. 提交所有更改
git add claude/agents/hcc-frontend-example.md cursor/rules/example.mdc
git commit -m "feat: update example agent"
```
## 可用代理
### 前端开发代理
- **hcc-frontend-hello-world** - 简单的问候代理，用于验证插件安装和功能
- **hcc-frontend-patternfly-component-builder** - 专家，擅长创建用于表单、布局、导航和模态的 PatternFly React 组件
- **hcc-frontend-patternfly-dataview-specialist** - 专家，擅长 PatternFly DataView 组件，用于表格、列表和数据网格
- **hcc-frontend-patternfly-css-utility-specialist** - 专家，擅长应用 PatternFly CSS 工具类进行样式和布局
- **hcc-frontend-storybook-specialist** - 专家，擅长创建具有测试和文档的全面 Storybook 故事
- **hcc-frontend-typescript-type-refiner** - 专家，擅长分析和精炼 TypeScript 类型，以消除 'any' 并提高类型安全性
- **hcc-frontend-unit-test-writer** - 专家，擅长编写针对 JavaScript/TypeScript 函数和 React 钩子的专注单元测试
- **hcc-frontend-react-patternfly-code-quality-scanner** - 专家，擅长扫描 React + PatternFly 项目以查找反模式和技术债务
- **hcc-frontend-dependency-cleanup-agent** - 专家，擅长安全地删除文件并清理孤立依赖项
- **hcc-frontend-weekly-report** - 专家，通过分析 JIRA 问题生成每周团队报告（用户提供团队识别标准）
- **hcc-frontend-yaml-setup-specialist** - 专家，擅长为新应用程序创建前端.yaml 文件，包括适当的 FEO 配置
- **hcc-frontend-feo-migration-specialist** - 专家，擅长将现有应用程序从静态 Chrome 配置迁移到 Frontend Operator 管理系统
- **hcc-frontend-iqe-test-analyzer** - 专家，擅长分析 IQE 测试并创建迁移计划（阶段 1：分析）
- **hcc-frontend-iqe-to-playwright-converter** - 专家，擅长将 IQE 测试转换为 Playwright TypeScript（阶段 2：转换）
- **hcc-frontend-playwright-test-finalizer** - 专家，擅长通过文档、PR 和 CodeRabbit 解决方案完成迁移（阶段 3：最终化）
### 测试迁移
此工具包包括三个针对 IQE-to-Playwright 迁移的专业代理，按顺序工作：
#### 1. **hcc-frontend-iqe-test-analyzer**（分析与规划）
分析 IQE 测试并创建全面的迁移计划，包括：
- 仓库识别（确定哪个前端仓库拥有每个测试）
- 现有测试覆盖率重叠检测
- 多用户身份验证检测
- 身份验证状态修改检测（注销、组织切换等）
- 环境状态假设检测
- 自定义凭据检测
- 按照仓库组织的全面迁移计划
**输出**：包含警告和用户决策所需的迁移计划
#### 2. **hcc-frontend-iqe-to-playwright-converter**（代码转换）
将 IQE 测试转换为 Playwright TypeScript，包括：
- 正确的 `@redhat-cloud-services/playwright-test-auth` 集成，用于 Red Hat SSO
- 独立的身份验证，用于影响会话状态的测试
- 符号超时常量（无硬编码值）
- CI 优化配置（单线程，无重试，最多 2 次失败）
- 从 Widgetastic 视图转换为页面对象
- 选择器现代化（XPath → 基于角色的/CSS）
- 参数化测试转换
- 处理跳过的测试的 test.skip()
**输出**：按仓库组织的转换后的测试文件
#### 3. **hcc-frontend-playwright-test-finalizer**（文档与集成）
通过以下方式完成迁移：
- 为每个测试创建 QE 验证文档
- 为跳过的测试创建 JIRA 问题
- 将文件交互式地移植到目标仓库
- 创建 Git 分支和 PR
- 监控和解决 CodeRabbit 注释（主要+优先级）
- 创建迁移总结文档
**输出**：包含 PR 和文档的完整迁移
**⚠️ 限制**：仅支持使用单个用户帐户的测试。多用户测试需要手动转换或拆分。
**快速入门（顺序工作流程）：**
```
# 步骤 1：分析
Use hcc-frontend-iqe-test-analyzer to analyze test_login.py from /path/to/iqe-platform-ui-plugin
# 步骤 2：转换（计划批准后）
Use hcc-frontend-iqe-to-playwright-converter to convert test_login.py using approved plan
# 步骤 3：最终确定
Use hcc-frontend-playwright-test-finalizer to generate docs and create PR for insights-chrome
```
📋 **有关详细迁移指南，请参阅**：[tests/migration-demo/QUICKSTART.md](tests/migration-demo/QUICKSTART.md)
**迁移工作流程：**
- **分析** → 创建包含警告和仓库分配的迁移计划
- **转换** → 生成具有正确身份验证和现代模式的 Playwright 测试文件
- **最终化** → 通过文档、移植、PR 和 CodeRabbit 解决方案完成集成
**关键功能：**
- ✅ 全局身份验证设置（无每个测试的登录）
- ✅ 用于修改会话状态的测试的独立身份验证
- ✅ 符号超时常量（TIMEOUTS.PAGE_LOAD 等）
- ✅ 禁用 Cookie 允许提示
- ✅ 参数化测试转换
- ✅ 环境状态假设检测
- ✅ 测试覆盖率重叠检测
- ✅ 跳过的测试的 JIRA 跟踪
- ✅ 交互式文件移植
- ✅ 自动创建 PR
- ✅ 解决 CodeRabbit 反馈
### 基础设施代理
- **hcc-infra-db-upgrade-orchestrator** - 通过分析状态并将任务委派给专门的子代理来编排 RDS 数据库升级
- **hcc-infra-db-upgrade-status-page** - 为生产数据库升级创建状态页维护公告
- **hcc-infra-db-upgrade-replication-check** - 创建 SQL 查询以在 DB 升级之前验证没有活动的复制槽
- **hcc-infra-db-upgrade-post-maintenance** - 创建升级后的 VACUUM 和 REINDEX 维护脚本
- **hcc-infra-db-upgrade-switchover** - 执行 RDS 蓝绿部署切换
- **hcc-infra-db-upgrade-cleanup** - 升级成功后删除蓝绿部署配置
📋 **有关详细数据库升级文档，请参阅**：[DB_UPGRADE_AGENTS.md](DB_UPGRADE_AGENTS.md)
所有代理都使用 `hcc-frontend-` 或 `hcc-infra-` 前缀，以避免与其他插件和内置代理发生名称冲突。
### 前端操作员（FEO）配置代理
此工具包包括用于前端操作员配置管理的专业代理：
- **hcc-frontend-yaml-setup-specialist** - 从头开始为新应用程序创建完整的 frontend.yaml 文件，包括适当的 FEO 配置、模块设置、导航包段、服务磁贴和搜索条目
- **hcc-frontend-feo-migration-specialist** - 将现有应用程序从静态 Chrome 服务后端配置迁移到 Frontend Operator 管理系统，处理导航、服务磁贴、fed-modules.json 转换和搜索条目
**这些代理有助于：**
- 使用适当的模式验证设置 `deploy/frontend.yaml`
- 配置 `feoConfigEnabled: true` 和相关的 FEO 功能
- 将 fed-modules.json 引用转换为模块配置
- 将导航从 chrome-service-backend 迁移到包段
- 将服务下拉磁贴转换为 FEO 服务磁贴格式
- 设置全局搜索的显式搜索条目
- 确保适当的依赖项升级（`@redhat-cloud-services/frontend-components-config@^6.6.9`）
**相关文档：**
- [FEO 迁移指南](https://github.com/RedHatInsights/chrome-service-backend/blob/main/docs/feo-migration-guide.md)
- [前端操作员文档](https://github.com/RedHatInsights/frontend-starter-app/blob/master/docs/frontend-operator/index.md)
- [前端 CRD 模式](https://raw.githubusercontent.com/RedHatInsights/frontend-components/refs/heads/master/packages/config-utils/src/feo/spec/frontend-crd.schema.json)
## 使用工具包
### 生成每周团队报告
此工具包包括一个强大的每周报告功能，可自动分析您的团队 JIRA 活动。
**先决条件：**
1. 安装 HCC 前端 AI 工具包插件（见入门部分）
2. 配置 [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP 服务器
3. 设置您的 JIRA 凭据（见下文）
4. 重新加载 Claude Code/VSCode
**设置 JIRA MCP 服务器：**
将以下内容添加到您的 Claude Code MCP 设置中：
```
{
"mcpServers": {
"mcp-atlassian": {
"command": "podman",
"args": [
"run",
"-i",
"--rm",
"-e",
"JIRA_URL",
"-e",
"JIRA_PERSONAL_TOKEN",
"ghcr.io/sooperset/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://issues.redhat.com",
"JIRA_PERSONAL_TOKEN": "your-jira-personal-access-token"
}
}
}
}
```
**获取您的 JIRA 个人访问令牌：**
1. 登录到您的 JIRA 实例
2. 前往您的配置文件设置
3. 导航到安全 → 创建和管理 API 令牌
4. 创建新的令牌并复制它
5. 使用此令牌作为 `JIRA_PERSONAL_TOKEN` 的值
**基本用法：**
只需让 Claude Code 生成报告：
```
"Show me what Platform Framework accomplished this week"
```
Claude Code 将：
- 自动计算日期范围（上周三到今天）
- 查询 JIRA 以获取您团队完成的工作
- 分析和将问题分类到有意义的部分
- 生成包含统计信息和见解的格式化报告
**报告包括：**
- 📊 摘要统计信息（总问题、按类型细分）
- ✅ 成就（安全、质量、产品功能、基础设施）
- ⚠️ 风险和阻塞器
- 🤝 跨团队依赖关系
- 👥 团队健康指标
## 可用 MCP 服务器
- **hcc-patternfly-data-view** - 模型上下文协议服务器，为所有 PatternFly 包提供全面的组件文档、源代码访问、模块发现和 CSS 工具集成
- **hcc-feo-mcp** - 前端操作员（FEO）MCP 服务器，提供模式管理、模板生成、验证和前端.yaml 配置的最佳实践
📋 **有关详细 MCP 服务器文档和独立使用，请参阅**：
- PatternFly MCP：[packages/hcc-pf-mcp/README.md](packages/hcc-pf-mcp/README.md)
- FEO MCP：[packages/hcc-feo-mcp/README.md](packages/hcc-feo-mcp/README.md)
### MCP 服务器工具
当插件安装后，这些 MCP 工具将可用：
#### 数据视图文档和示例
- **getPatternFlyDataViewDescription** - 获取 @patternfly/react-data-view 包功能的全面文档
- **getPatternFlyDataViewExample** - 获取各种数据表场景的实现示例（基本用法、排序、过滤、分页、选择等）
#### 前端操作员（FEO）配置工具
- **getFEOSchema** - 获取最新的 FEO 模式以进行验证和参考
- **getFEOMigrationTemplate** - 为现有应用程序生成定制的迁移模板
- **getFEOYamlSetupTemplate** - 为新应用程序生成完整的 frontend.yaml 模板
- **getFEOExamples** - 获取特定的 FEO 配置示例和模式
- **validateFEOConfig** - 将前端.yaml 与 FEO 模式进行验证
- **getFEOBestPractices** - 获取当前的 FEO 最佳实践和模式
- **getFEONavigationPositioning** - 获取导航定位指南
- **getFEOServiceTilesSections** - 获取可用的服务磁贴部分和组
**注意**：FEO 代理（`hcc-frontend-yaml-setup-specialist` 和 `hcc-frontend-feo-migration-specialist`）自动使用这些 MCP 工具来提供最新的模板、验证和指南，显著减少令牌使用量，同时保持全面的功能。
#### PatternFly 模块发现和源代码
- **getAvailableModules** - 在本地环境中发现可用的Fly 组件，包括 react-core、react-icons、react-table、react-data-view 和 react-component-groups 包
- **getComponentSourceCode** - 获取任何 PatternFly 组件的实际 TypeScript/React 源代码
#### PatternFly CSS 工具
- **getReactUtilityClasses** - 访问用于样式的 PatternFly CSS 工具类（间距、显示、flex、颜色、排版等）
## 开发 MCP 服务器
### 必要依赖项
**CRITICAL**：此存储库中的所有 MCP 服务器 **必须** 包含 `zod` 作为依赖项。MCP SDK（v1.22+）需要 Zod 进行工具模式验证。
将以下内容添加到您的 MCP 服务器 `package.json`：
```
{
"dependencies": {
"@modelcontextprotocol/sdk": "^1.22.0",
"zod": "^3.25.76"
}
}
```
### 工具模式定义
工具模式 **必须** 使用 **Zod 模式** 定义，而不是普通的 JSON 模式对象。MCP SDK 将在您的模式上调用 Zod 验证方法，如 `safeParseAsync()`。
#### ✅ 正确 - 使用 Zod 模式
```
import { z } from 'zod';
export function myTool(): McpTool {
async function tool(args: any): Promise {
const { param1, param2 } = args;
// Tool implementation
}
return [
'myTool',
{
description: 'Tool description',
inputSchema: {
// Use Zod schema constructors
param1: z.string().describe('Required string parameter'),
param2: z.number().optional().describe('Optional number parameter'),
param3: z.enum(['option1', 'option2', 'option3']).describe('Enum parameter'),
param4: z.boolean().optional().default(true).describe('Boolean with default'),
},
},
tool
];
}
// For tools with no parameters
return [
'noParamTool',
{
description: 'Tool with no parameters',
inputSchema: {}, // Empty object, not JSON Schema
},
tool
];
```
#### ❌ 错误 - 使用 JSON 模式（将失败）
```
// DON'T DO THIS - Will cause "v3Schema.safeParseAsync is not a function" error
return [
'myTool',
{
description: 'Tool description',
inputSchema: {
type: 'object', // ❌ JSON Schema syntax
properties: {
param1: {
type: 'string', // ❌ Will fail
description: 'Parameter'
}
},
required: ['param1'] // ❌ Use z.string() instead
},
},
tool
];
```
### 常见的 Zod 模式模式
```
// Required string
z.string().describe('Description')
// Optional string
z.string().optional().describe('Description')
// String with default
z.string().default('default-value').describe('Description')
// Enum/Union type
z.enum(['value1', 'value2', 'value3']).describe('Description')
// Boolean
z.boolean().describe('Description')
// Number
z.number().describe('Description')
// Optional boolean with default
z.boolean().optional().default(true).describe('Description')
```
### 最佳实践
1. **始终使用 `describe()`** 为参数添加描述 - 这些将成为工具的文档
2. **使用 `optional()`** 为非必需参数而不是 JSON 模式的 `required` 数组
3. **使用 `default()`** 在模式内指定默认值
4. **在每个工具文件顶部导入 Zod**：`import { z } from 'zod';`
5. **在提交之前测试您的工具**：使用 MCP Inspector 在部署之前
### 测试 MCP 工具
```
# 构建您的 MCP 服务器
npm run build
# 使用 MCP Inspector 进行测试
npx @modelcontextprotocol/inspector node dist/index.js
```
### 参考文档
- [MCP SDK 文档](https://github.com/modelcontextprotocol/sdk)
- [Zod 文档](https://zod.dev)
- [示例 MCP 服务器](packages/hcc-feo-mcp/src/lib/tools/) - 此存储库中的参考实现
## 未完成的工作与未来路线图
📋 **查看我们的路线图和计划集成**：[OUTSTANDING_WORK.md](OUTSTANDING_WORK.md)
此文档跟踪：
- MCP 服务器集成（浏览器工具、Figma、Playwright）
- 新代理开发（Scalprum、数据驱动表单）
- 团队建议和社区贡献
- 实施优先级和时间段
## 存储库结构
```
platform-frontend-ai-toolkit/
├── .claude-plugin/
│ └── marketplace.json # Marketplace config (lists all plugins)
├── plugins/ # Claude Code plugins
│ ├── frontend/ # Frontend development plugin
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── agents/ # 14 frontend development agents
│ │ ├── package.json # For NX versioning (private)
│ │ └── project.json # NX project config
│ ├── infrastructure/ # Infrastructure & DevOps plugin
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── agents/ # 13 infrastructure agents
│ │ ├── skills/ # Utility skills (db-upgrader)
│ │ ├── package.json
│ │ └── project.json
│ └── management/ # Project management plugin
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── agents/ # 3 management agents
│ ├── package.json
│ └── project.json
├── packages/ # MCP servers (npm packages)
│ ├── hcc-pf-mcp/ # PatternFly documentation MCP
│ ├── hcc-feo-mcp/ # FEO configuration MCP
│ └── hcc-kessel-mcp/ # Kessel permissions MCP
├── scripts/
│ └── sync-plugin-versions.js # Sync package.json → plugin.json
├── docs/ # Documentation
├── nx.json # NX workspace config
└── README.md
```
**关键功能：**
- **模块化插件**：仅安装您需要的部分（前端、基础设施或管理）
- **自动化版本控制**：NX Release 管理插件和 MCP 包版本
- **集中式分发**：一个市场，多个专业插件
## 更新插件
### 检查更新
```
# 列出已安装插件及其版本
claude plugins list
# 检查是否有更新可用
claude plugins status
```
### 更新插件
```
# 更新市场以获取最新插件版本
/plugin marketplace update hcc-frontend-toolkit
# 然后更新特定插件：
/plugin install frontend-plugin@hcc-frontend-toolkit
/plugin install infrastructure-plugin@hcc-frontend-toolkit
/plugin install management-plugin@hcc-frontend-toolkit
# 或更新所有已安装插件
claude plugins update
```
### 手动更新过程
标签：AI 工具, Claude Code, JIRA, Linux 内核安全, PPID欺骗, React 开发, TypeScript, 代码市场, 代码示例, 团队协作, 安全插件, 市场配置, 插件安装, 插件管理, 数据分析, 数据库升级, 测试工具, 特权提升, 自动化攻击, 自动化部署, 请求拦截, 项目管理