@bovinphang/frontend-craft 2.5.0

package/templates/claude/CLAUDE.md

@@ -0,0 +1,106 @@
+# 项目说明
+
+本仓库由前端团队维护。
+
+核心要求：
+
+- 在调整架构前，先理解现有代码
+- 优先复用，而不是重复造轮子
+- 保持改动小、清晰、便于评审
+- 先遵循项目标准，再考虑通用模式
+
+## 项目基础信息
+
+<!-- 请根据项目实际情况修改以下配置 -->
+
+- 语言：TypeScript
+- 包管理器：pnpm
+- 构建工具：Vite
+- 测试工具: Vitest + Testing Library
+- UI 体系：优先复用现有组件库和设计 Token
+- 设计实现流程：如有条件，优先使用设计工具 MCP（Figma / MasterGo / Pixso / 墨刀 / Sketch）上下文
+
+## 常用命令
+
+优先使用仓库现有命令，不要自行发明替代命令。
+
+<!-- 请根据项目实际情况修改 -->
+
+- 安装：`pnpm install`
+- 开发：`pnpm dev`
+- Lint：`pnpm lint`
+- 类型检查：`pnpm type-check`
+- 测试：`pnpm test`
+- 构建：`pnpm build`
+
+如果命令缺失，先检查 `package.json`。
+
+## 通用工作原则
+
+改代码前：
+
+1. 阅读目标模块及其周边模块
+2. 搜索已有可复用组件或工具函数
+3. 理解当前样式和 Token 约定
+4. 如果仓库里已有一套模式，不要再引入第二套
+
+实现时：
+
+- 保持组件职责聚焦
+- 将重复逻辑提取到 hooks / composables / utils
+- 优先使用明确类型
+- 优先使用可推导状态，避免重复维护状态
+- 除非任务明确要求破坏性变更，否则保持向后兼容
+
+完成后：
+
+- 执行 lint
+- 如有类型检查则执行 type check
+- 如有测试则执行测试
+- 总结改动文件、关键决策和剩余风险
+
+## Git 规范
+
+- 提交前必须通过 lint 和类型检查
+- 未经我确认不要直接 commit
+- 分支命名: feature/xxx, fix/xxx, refactor/xxx
+- Commit 格式: 遵循 Conventional Commits（详见 rules/fec-git-conventions.md）
+
+## 设计稿实现工作流
+
+当存在设计上下文时：
+
+1. 先通过 MCP 读取设计上下文（Figma / MasterGo / Pixso / 墨刀 / Sketch，摹客则使用截图/标注）
+2. 检查项目现有组件体系
+3. 先产出简短实现计划
+4. 分步骤实现
+5. 执行校验命令
+6. 总结偏差和风险
+
+## 安全要求
+
+不要主动暴露或打印任何密钥。
+除非任务明确要求且权限允许，不要读取或修改敏感文件。
+除非明确要求并获得批准，不要执行破坏性 shell 命令。
+
+## 规则导入
+
+<!-- 按项目技术栈选择性导入，删除不需要的行 -->
+
+@./rules/fec-vue.md
+@./rules/fec-react.md
+@./rules/fec-design-system.md
+@./rules/fec-testing.md
+@./rules/fec-git-conventions.md
+@./rules/fec-i18n.md
+@./rules/fec-performance.md
+@./rules/fec-api-layer.md
+@./rules/fec-state-management.md
+@./rules/fec-error-handling.md
+@./rules/fec-naming-conventions.md
+@./rules/fec-typescript.md
+@./rules/fec-code-comments.md
+@./rules/fec-ci-cd.md
+@./rules/fec-refactoring.md
+@./rules/fec-agent-workflow.md
+@./rules/fec-working-modes.md

package/templates/claude/settings.json

@@ -0,0 +1,62 @@
+{
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "enableAllProjectMcpServers": true,
+    "permissions": {
+        "allow": [
+            "Bash(pnpm install)",
+            "Bash(pnpm dev)",
+            "Bash(pnpm lint)",
+            "Bash(pnpm lint *)",
+            "Bash(pnpm type-check)",
+            "Bash(pnpm type-check *)",
+            "Bash(pnpm typecheck)",
+            "Bash(pnpm typecheck *)",
+            "Bash(pnpm test)",
+            "Bash(pnpm test *)",
+            "Bash(pnpm build)",
+            "Bash(pnpm build *)",
+            "Bash(pnpm exec eslint *)",
+            "Bash(pnpm exec prettier *)",
+            "Bash(npm run lint)",
+            "Bash(npm run lint *)",
+            "Bash(npm run lint:fix)",
+            "Bash(npm run type-check)",
+            "Bash(npm run test)",
+            "Bash(npm run test *)",
+            "Bash(npm run build)",
+            "Bash(npm run build *)",
+            "Bash(yarn lint)",
+            "Bash(yarn lint *)",
+            "Bash(yarn type-check)",
+            "Bash(yarn typecheck)",
+            "Bash(yarn test)",
+            "Bash(yarn test *)",
+            "Bash(yarn build)",
+            "Bash(yarn build *)",
+            "Bash(npx prettier --write *)",
+            "Bash(git diff --stat)",
+            "Bash(git log *)"
+        ],
+        "deny": [
+            "Read(./.env)",
+            "Read(./.env.*)",
+            "Read(./secrets/**)",
+            "Read(./config/credentials.json)",
+            "Read(./*.pem)",
+            "Read(./*.key)",
+            "Read(./*.p12)",
+            "Read(./*.jks)",
+            "Bash(curl * | *sh*)",
+            "Bash(wget * | *sh*)",
+            "Bash(rm -rf /)",
+            "Bash(rm -rf /*)",
+            "Bash(git push * --force*)",
+            "Bash(npm publish)",
+            "Bash(sudo *)"
+        ]
+    },
+    "env": {
+        "BASH_DEFAULT_TIMEOUT_MS": "120000",
+        "BASH_MAX_OUTPUT_LENGTH": "30000"
+    }
+}

package/templates/codex/AGENTS.md

@@ -0,0 +1,105 @@
+# 项目说明
+
+本仓库由前端团队维护。
+
+核心要求：
+
+- 在调整架构前，先理解现有代码
+- 优先复用，而不是重复造轮子
+- 保持改动小、清晰、便于评审
+- 先遵循项目标准，再考虑通用模式
+
+## 项目基础信息
+
+<!-- 请根据项目实际情况修改以下配置 -->
+
+- 语言：TypeScript
+- 包管理器：pnpm
+- 构建工具：Vite
+- 测试工具: Vitest + Testing Library
+- UI 体系：优先复用现有组件库和设计 Token
+- 设计实现流程：如有条件，优先使用设计工具 MCP（Figma / MasterGo / Pixso / 墨刀 / Sketch）上下文
+
+## 常用命令
+
+优先使用仓库现有命令，不要自行发明替代命令。
+
+<!-- 请根据项目实际情况修改 -->
+
+- 安装：`pnpm install`
+- 开发：`pnpm dev`
+- Lint：`pnpm lint`
+- 类型检查：`pnpm type-check`
+- 测试：`pnpm test`
+- 构建：`pnpm build`
+
+如果命令缺失，先检查 `package.json`。
+
+## 通用工作原则
+
+改代码前：
+
+1. 阅读目标模块及其周边模块
+2. 搜索已有可复用组件或工具函数
+3. 理解当前样式和 Token 约定
+4. 如果仓库里已有一套模式，不要再引入第二套
+
+实现时：
+
+- 保持组件职责聚焦
+- 将重复逻辑提取到 hooks / composables / utils
+- 优先使用明确类型
+- 优先使用可推导状态，避免重复维护状态
+- 除非任务明确要求破坏性变更，否则保持向后兼容
+
+完成后：
+
+- 执行 lint
+- 如有类型检查则执行 type check
+- 如有测试则执行测试
+- 总结改动文件、关键决策和剩余风险
+
+## Git 规范
+
+- 提交前必须通过 lint 和类型检查
+- 未经我确认不要直接 commit
+- 分支命名: feature/xxx, fix/xxx, refactor/xxx
+- Commit 格式: 遵循 Conventional Commits（详见 .codex/rules/fec-git-conventions.md）
+
+## 设计稿实现工作流
+
+当存在设计上下文时：
+
+1. 先通过 MCP 读取设计上下文（Figma / MasterGo / Pixso / 墨刀 / Sketch，摹客则使用截图/标注）
+2. 检查项目现有组件体系
+3. 先产出简短实现计划
+4. 分步骤实现
+5. 执行校验命令
+6. 总结偏差和风险
+
+## 安全要求
+
+不要主动暴露或打印任何密钥。
+除非任务明确要求且权限允许，不要读取或修改敏感文件。
+除非明确要求并获得批准，不要执行破坏性 shell 命令。
+
+## 详细规则
+
+项目详细规则位于 `.codex/rules/` 目录，按技术栈选择性参考：
+
+- fec-vue.md / fec-react.md - 框架组件规范
+- fec-typescript.md - TypeScript/JavaScript 规范（与 `typescript-reviewer` 子代理联动）
+- fec-design-system.md - 设计系统与 Token
+- fec-testing.md - 测试规范
+- fec-git-conventions.md - Git 提交规范
+- fec-i18n.md - 国际化规范（如需要）
+- fec-performance.md - 性能优化
+- fec-api-layer.md - API 层规范
+- fec-state-management.md - 状态管理
+- fec-error-handling.md - 错误处理
+- fec-naming-conventions.md - 命名规范
+- fec-code-comments.md - 代码注释（何时写、写什么）
+- fec-ci-cd.md - CI/CD 规范
+- fec-refactoring.md - 重构约束
+- fec-agent-workflow.md - 子代理协作边界
+- fec-working-modes.md - 调研、计划、开发、评审、收尾模式

package/templates/codex/config.toml

@@ -0,0 +1,32 @@
+# Frontend Craft - Codex 项目配置
+# 复制到 .codex/config.toml 并根据项目需要调整
+
+# MCP 设计工具集成（按需取消注释并配置环境变量）
+# 需要设置: FIGMA_API_KEY, SKETCH_API_KEY, MG_MCP_TOKEN, MODAO_TOKEN
+
+# [mcp_servers.figma]
+# command = "npx"
+# args = ["-y", "figma-developer-mcp", "--stdio"]
+# env = { FIGMA_API_KEY = "${FIGMA_API_KEY}" }
+
+# [mcp_servers.figma-desktop]
+# command = "npx"
+# args = ["-y", "@anthropic/figma-mcp"]
+# env = { FIGMA_API_KEY = "${FIGMA_API_KEY}" }
+
+# [mcp_servers.sketch]
+# command = "npx"
+# args = ["-y", "sketch-mcp-server", "--stdio"]
+# env = { SKETCH_API_KEY = "${SKETCH_API_KEY}" }
+
+# [mcp_servers.mastergo]
+# command = "npx"
+# args = ["-y", "@mastergo/magic-mcp", "--token=${MG_MCP_TOKEN}", "--url=https://mastergo.com"]
+
+# [mcp_servers.pixso]
+# url = "http://localhost:3667/mcp"
+
+# [mcp_servers.modao]
+# command = "npx"
+# args = ["-y", "@modao-mcp/modao-proto-mcp"]
+# env = { MODAO_TOKEN = "${MODAO_TOKEN}" }

package/templates/openclaw/AGENTS.md

@@ -0,0 +1,101 @@
+# 项目说明
+
+本工作区由前端团队维护（由 **frontend-craft** OpenClaw 插件模板初始化）。
+
+核心要求：
+
+- 在调整架构前，先理解现有代码
+- 优先复用，而不是重复造轮子
+- 保持改动小、清晰、便于评审
+- 先遵循项目标准，再考虑通用模式
+
+## 项目基础信息
+
+<!-- 请根据项目实际情况修改以下配置 -->
+
+- 语言：TypeScript
+- 包管理器：pnpm
+- 构建工具：Vite
+- 测试工具: Vitest + Testing Library
+- UI 体系：优先复用现有组件库和设计 Token
+- 设计实现流程：如有条件，优先使用设计工具 MCP（Figma / MasterGo / Pixso / 墨刀 / Sketch）上下文
+
+## 常用命令
+
+优先使用仓库现有命令，不要自行发明替代命令。
+
+<!-- 请根据项目实际情况修改 -->
+
+- 安装：`pnpm install`
+- 开发：`pnpm dev`
+- Lint：`pnpm lint`
+- 类型检查：`pnpm type-check`
+- 测试：`pnpm test`
+- 构建：`pnpm build`
+
+如果命令缺失，先检查 `package.json`。
+
+## 通用工作原则
+
+改代码前：
+
+1. 阅读目标模块及其周边模块
+2. 搜索已有可复用组件或工具函数
+3. 理解当前样式和 Token 约定
+4. 如果仓库里已有一套模式，不要再引入第二套
+
+实现时：
+
+- 保持组件职责聚焦
+- 将重复逻辑提取到 hooks / composables / utils
+- 优先使用明确类型
+- 优先使用可推导状态，避免重复维护状态
+- 除非任务明确要求破坏性变更，否则保持向后兼容
+
+完成后：
+
+- 执行 lint
+- 如有类型检查则执行 type check
+- 如有测试则执行测试
+- 总结改动文件、关键决策和剩余风险
+
+## Git 规范
+
+- 提交前必须通过 lint 和类型检查
+- 未经我确认不要直接 commit
+- 分支命名: feature/xxx, fix/xxx, refactor/xxx
+- Commit 格式: 遵循 Conventional Commits（详见本文件同目录 skills 下的 `git-conventions.md`）
+
+## 设计稿实现工作流
+
+当存在设计上下文时：
+
+1. 先通过 MCP 读取设计上下文（Figma / MasterGo / Pixso / 墨刀 / Sketch，摹客则使用截图/标注）
+2. 检查项目现有组件体系
+3. 先产出简短实现计划
+4. 分步骤实现
+5. 执行校验命令
+6. 总结偏差和风险
+
+## 安全要求
+
+不要主动暴露或打印任何密钥。
+除非任务明确要求且权限允许，不要读取或修改敏感文件。
+除非明确要求并获得批准，不要执行破坏性 shell 命令。
+
+## 规则与扩展技能
+
+OpenClaw 会从本工作区的 `skills/` 加载 Markdown 技能。初始化后规则文件位于：
+
+`skills/frontend-craft-rules/`
+
+按需阅读并在对话中引用相关片段，例如：
+
+- `skills/frontend-craft-rules/fec-vue.md` / `fec-react.md` — 框架规范
+- `skills/frontend-craft-rules/fec-typescript.md` — TypeScript/JavaScript（与 `typescript-reviewer` 剧本联动）
+- `skills/frontend-craft-rules/fec-code-comments.md` — 代码注释（何时写、写什么）
+- `skills/frontend-craft-rules/fec-testing.md`、`fec-performance.md`、`fec-design-system.md` 等
+- `skills/frontend-craft-rules/fec-agent-workflow.md` — 子代理协作边界
+- `skills/frontend-craft-rules/fec-working-modes.md` — 调研、计划、开发、评审、收尾模式
+
+若项目不需要某项规则，可删除对应文件或在对话中说明忽略。

package/templates/openclaw/OPENCLAW-CONFIG.md

@@ -0,0 +1,12 @@
+# OpenClaw 配置说明（替代原 Claude Code settings.json）
+
+本插件不再提供 `settings.json`（Claude Code 专用）。在 OpenClaw 中请使用网关配置文件，例如：
+
+- 用户级：`~/.openclaw/openclaw.json`（或你的 profile 路径）
+- 工作区：按 `openclaw configure` / 文档约定
+
+常用关注点：
+
+- **沙箱与执行策略**：参见官方文档 [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing) 中的 `agents.defaults.sandbox` 等键
+- **插件开关**：`plugins.entries.frontend-craft` 下可覆盖本插件 `configSchema` 中的布尔项（如 `formatAfterWrite`、`notifyOnAgentEnd`）
+- **MCP**：原生插件不会自动合并仓库根目录的 `.mcp.json`；请将其中 `mcpServers` 合并到你的 embedded Pi / 网关 MCP 配置（见主 README 的 MCP 章节）

package/templates/shared/rules/fec-agent-workflow.md

@@ -0,0 +1,54 @@
+# 子代理协作规则
+
+当前端任务涉及多视角分析、跨模块规划、专项质量审查或验证失败修复时，优先使用职责明确的子代理。
+
+## 选择原则
+
+- 架构、页面拆分、状态流、目录规划：`fec-architect`
+- 前端 PR 综合评审：`fec-code-reviewer`
+- TypeScript / JavaScript 语义与类型风险：`fec-typescript-reviewer`
+- 安全风险：`fec-security-reviewer`
+- 测试策略：`fec-test-planner`
+- E2E 编写与运行：`fec-e2e-runner`
+- 性能瓶颈：`fec-performance-optimizer`
+- 来源/版本敏感决策：优先由主代理查项目事实和官方来源，再交给专项代理落地
+- UI 视觉与设计稿差异：`fec-ui-checker`
+- 设计稿实现：`fec-figma-implementer`
+- Token 映射：`fec-design-token-mapper`
+- 构建、类型、测试、CI 失败：`fec-build-fixer`
+- 死代码与无用依赖清理：`fec-refactor-cleaner`
+- README、runtime docs、能力表同步：`fec-doc-updater`
+
+## 多代理评审编排
+
+复杂 PR 可按质量维度并行评审，但必须有主代理负责合并结论。
+
+| 变更类型 | 建议组合 | 主合并者 |
+| --- | --- | --- |
+| UI feature | `fec-code-reviewer` + `fec-typescript-reviewer` + `fec-test-planner` | `fec-code-reviewer` |
+| 鉴权 / 上传 / 富文本 | `fec-security-reviewer` + `fec-code-reviewer` | `fec-security-reviewer` |
+| 大列表 / 图表 / 3D / 性能问题 | `fec-performance-optimizer` + `fec-code-reviewer` | `fec-performance-optimizer` |
+| 设计稿落地 | `fec-figma-implementer` + `fec-ui-checker` + `fec-code-reviewer` | `fec-figma-implementer` |
+| 大型重构 | `fec-architect` + `fec-refactor-cleaner` + `fec-test-planner` | `fec-architect` |
+
+合并规则：
+
+- 相同文件、相同行号、相同根因的问题合并为一条，保留最高严重级别。
+- 相同根因分布在多处时写成模式级发现，列代表性位置，不逐行刷屏。
+- 结论冲突时先回到项目事实、测试结果和用户影响，不用代理身份决定谁对。
+- 主代理输出最终 Verdict，并列出各专项代理覆盖的范围和未覆盖范围。
+
+## 协作约束
+
+- 委托前先明确范围、输入和输出，不把模糊任务丢给子代理。
+- 多个独立问题可以并行分析；彼此有依赖的任务按顺序推进。
+- 子代理输出必须落到可验证结论：报告、文件路径、命令结果或具体风险。
+- 子代理建议不自动等于实现决策；与仓库现有约定冲突时，优先遵循仓库约定。
+- 主代理必须复核关键证据、验证命令和改动边界，不能只转述子代理结论。
+
+## 反模式
+
+- 为简单单文件修改创建过多代理。
+- 让多个代理同时修改同一文件而没有边界。
+- 用子代理替代本应先做的代码阅读。
+- 只接收结论，不核对关键证据和验证命令。

package/templates/shared/rules/fec-api-layer.md

@@ -0,0 +1,99 @@
+# API 层规范
+
+凡是涉及 HTTP 请求、接口调用、数据获取或错误处理时，都应用本文件。
+
+## 核心原则
+
+- 请求和响应必须有类型定义
+- 统一错误处理，不在每个组件中重复 try-catch
+- API 层与 UI 层分离
+- 敏感操作（删除、支付）必须有二次确认
+
+## 目录结构
+
+<!-- 请根据项目实际情况调整 -->
+
+```
+src/
+├── api/                    # API 定义层
+│   ├── modules/
+│   │   ├── user.ts         # 用户相关接口
+│   │   ├── order.ts        # 订单相关接口
+│   │   └── ...
+│   ├── types/              # 请求/响应类型
+│   │   ├── user.types.ts
+│   │   └── order.types.ts
+│   └── request.ts          # 统一请求封装
+```
+
+## 类型规范
+
+```typescript
+// 请求参数类型
+interface GetUserListParams {
+    page: number;
+    pageSize: number;
+    keyword?: string;
+    status?: UserStatus;
+}
+
+// 响应数据类型
+interface GetUserListResponse {
+    list: User[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+
+// API 函数签名
+export function getUserList(params: GetUserListParams): Promise<GetUserListResponse>;
+```
+
+要求：
+
+- 禁止使用 `any` 作为请求参数或响应类型
+- 枚举值使用 TypeScript enum 或 union type
+- 分页参数和响应格式保持统一
+
+## 错误处理
+
+### 统一拦截器
+
+在请求封装层统一处理：
+
+- 401: 跳转登录或刷新 token
+- 403: 提示无权限
+- 500: 显示通用错误提示
+- 网络错误: 显示网络异常提示
+
+### 业务错误
+
+- 业务错误码与 HTTP 状态码分离
+- 业务错误信息使用 i18n key（如支持国际化）
+- 需要用户操作的错误（如表单校验失败）由调用方处理
+
+## Loading / Error / Empty 状态
+
+每个数据请求场景都需要考虑：
+
+- **Loading**: 首次加载 skeleton/spinner，后续刷新不阻断 UI
+- **Error**: 显示错误信息 + 重试按钮
+- **Empty**: 显示空状态占位 + 引导操作
+
+## 检查清单
+
+- [ ] 请求参数和响应有明确类型
+- [ ] 错误处理不依赖每个组件各自 try-catch
+- [ ] Loading / Error / Empty 三态均已处理
+- [ ] 敏感操作有二次确认
+- [ ] Token / 鉴权信息不在请求 URL 中明文传递
+- [ ] 大数据量使用分页或流式加载
+
+## 反模式
+
+- 在组件中直接使用 `fetch` / `axios` 而不经过统一封装
+- 请求参数或响应使用 `any`
+- 忽略错误处理，只处理成功场景
+- 将 token 拼接在 URL 中
+- 在 GET 请求中传递敏感数据
+- 同一个接口在多个文件中重复定义