zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 21:53:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

Browse Source 
* docs(zh-CN): sync Chinese docs with latest upstream changes

* update

---------

Co-authored-by: neo <neo.dowithless@gmail.com>
This commit is contained in:
zdoc.app
2026-03-03 14:28:27 +08:00
committed by GitHub
parent adc0f67008
commit ada4cd75a3
114 changed files with 11161 additions and 4790 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/zh-CN/CONTRIBUTING.md
View File

@@ -89,10 +89,11 @@ skills/
### SKILL.md 模板
```markdown
````markdown
---
name: your-skill-name
description: Brief description shown in skill list
origin: ECC
---
# 你的技能标题
@@ -101,30 +102,16 @@ description: Brief description shown in skill list
## 核心概念
解释关键模式和准则。
解释关键模式和指导原则。
## 代码示例
`​`​`typescript
```typescript
// 包含实用、经过测试的示例
function example() {
// 注释良好的代码
}
`​`​`
## 最佳实践
- 可操作的指导原则
- 该做与不该做的事项
- 需要避免的常见陷阱
## 适用场景
描述此技能适用的场景。
```
````
### 技能清单

576
docs/zh-CN/README.md
View File

@@ -1,4 +1,4 @@
**语言:** English | [繁體中文](../zh-TW/README.md) | [简体中文](README.md)
**语言：** 英语 | [繁體中文](../zh-TW/README.md) | [简体中文](../../README.md)
# Everything Claude Code
@@ -13,7 +13,7 @@
![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk\&logoColor=white)
![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown\&logoColor=white)
> **42K+ 星标** | **5K+ 分支** | **24 位贡献者** | **支持 6 种语言**
> **5万+ stars** | **6千+ forks** | **30位贡献者** | **支持6种语言** | **Anthropic黑客马拉松获胜者**
***
@@ -21,7 +21,7 @@
**🌐 语言 / 语言 / 語言**
[**English**](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../../docs/zh-TW/README.md)
[**English**](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md)
</div>
@@ -69,6 +69,23 @@
## 最新动态
### v1.7.0 — 跨平台扩展与演示文稿生成器（2026年2月）
* **Codex 应用 + CLI 支持** — 基于 `AGENTS.md` 的直接 Codex 支持、安装器目标定位以及 Codex 文档
* **`frontend-slides` 技能** — 零依赖的 HTML 演示文稿生成器，附带 PPTX 转换指导和严格的视口适配规则
* **5个新的通用业务/内容技能** — `article-writing`、`content-engine`、`market-research`、`investor-materials`、`investor-outreach`
* **更广泛的工具覆盖** — 加强了对 Cursor、Codex 和 OpenCode 的支持，使得同一代码仓库可以在所有主要平台上干净地部署
* **992项内部测试** — 在插件、钩子、技能和打包方面扩展了验证和回归测试覆盖
### v1.6.0 — Codex CLI、AgentShield 与市场（2026年2月）
* **Codex CLI 支持** — 新的 `/codex-setup` 命令生成 `codex.md` 以实现 OpenAI Codex CLI 兼容性
* **7个新技能** — `search-first`、`swift-actor-persistence`、`swift-protocol-di-testing`、`regex-vs-llm-structured-text`、`content-hash-cache-pattern`、`cost-aware-llm-pipeline`、`skill-stocktake`
* **AgentShield 集成** — `/security-scan` 技能直接从 Claude Code 运行 AgentShield；1282 项测试，102 条规则
* **GitHub 市场** — ECC Tools GitHub 应用已在 [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) 上线，提供免费/专业/企业版
* **合并了 30+ 个社区 PR** — 来自 6 种语言的 30 位贡献者的贡献
* **978项内部测试** — 在代理、技能、命令、钩子和规则方面扩展了验证套件
### v1.4.1 — 错误修复 (2026年2月)
* **修复了直觉导入内容丢失问题** — `parse_instinct_file()` 在 `/instinct-import` 期间会静默丢弃 frontmatter 之后的所有内容（Action, Evidence, Examples 部分）。已由社区贡献者 @ericcai0814 修复 ([#148](https://github.com/affaan-m/everything-claude-code/issues/148), [#161](https://github.com/affaan-m/everything-claude-code/pull/161))
@@ -120,27 +137,32 @@
```bash
# Clone the repo first
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
# Install common rules (required)
cp -r everything-claude-code/rules/common/* ~/.claude/rules/
# Install language-specific rules (pick your stack)
cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/
cp -r everything-claude-code/rules/python/* ~/.claude/rules/
cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
# Recommended: use the installer (handles common + language rules safely)
./install.sh typescript # or python or golang
# You can pass multiple languages:
# ./install.sh typescript python golang
# or target cursor:
# ./install.sh --target cursor typescript
```
手动安装说明请参阅 `rules/` 文件夹中的 README。
### 步骤 3：开始使用
```bash
# Try a command
/plan "Add user authentication"
# Try a command (plugin install uses namespaced form)
/everything-claude-code:plan "Add user authentication"
# Manual install (Option 2) uses the shorter form:
# /plan "Add user authentication"
# Check available commands
/plugin list everything-claude-code@everything-claude-code
```
✨ **就是这样！** 您现在可以访问 15+ 个智能体，30+ 个技能，以及 30+ 个命令。
✨ **就是这样！** 你现在可以访问 13 个代理、56 个技能和 32 个命令。
***
@@ -185,11 +207,11 @@ node scripts/setup-package-manager.js --detect
```
everything-claude-code/
|-- .claude-plugin/ # 插件和插件市场清单
|-- .claude-plugin/ # 插件和市场清单
| |-- plugin.json # 插件元数据和组件路径
| |-- marketplace.json # 用于 /plugin marketplace add 的市场目录
|
|-- agents/ # 用于任务委派的专用子代理
|-- agents/ # 用于委派的专用子代理
| |-- planner.md # 功能实现规划
| |-- architect.md # 系统设计决策
| |-- tdd-guide.md # 测试驱动开发
@@ -205,20 +227,28 @@ everything-claude-code/
| |-- database-reviewer.md # 数据库/Supabase 审查（新增）
|
|-- skills/ # 工作流定义与领域知识
| |-- coding-standards/ # 各语言最佳实践
| |-- coding-standards/ # 语言最佳实践
| |-- clickhouse-io/ # ClickHouse 分析、查询与数据工程
| |-- backend-patterns/ # API、数据库、缓存模式
| |-- frontend-patterns/ # React、Next.js 模式
| |-- continuous-learning/ # 从会话中自动提取模式（长文档指南）
| |-- frontend-slides/ # HTML 幻灯片与 PPTX 转 Web 演示流程（新增）
| |-- article-writing/ # 使用指定风格进行长文写作（避免通用 AI 语气）（新增）
| |-- content-engine/ # 多平台内容创作与再利用工作流（新增）
| |-- market-research/ # 带来源标注的市场、竞品与投资人研究（新增）
| |-- investor-materials/ # 融资路演材料、单页纸、备忘录与财务模型（新增）
| |-- investor-outreach/ # 个性化融资外联与跟进（新增）
| |-- continuous-learning/ # 从会话中自动提取模式（长文指南）
| |-- continuous-learning-v2/ # 基于直觉的学习与置信度评分
| |-- iterative-retrieval/ # 子代理的渐进式上下文精炼
| |-- strategic-compact/ # 手动压缩建议（长文档指南）
| |-- iterative-retrieval/ # 子代理渐进式上下文优化
| |-- strategic-compact/ # 手动压缩建议（长文指南）
| |-- tdd-workflow/ # TDD 方法论
| |-- security-review/ # 安全检查清单
| |-- eval-harness/ # 验证循环评估（长文档指南）
| |-- verification-loop/ # 持续验证（长文档指南）
| |-- golang-patterns/ # Go 语言惯用法与最佳实践
| |-- eval-harness/ # 验证循环评估（长文指南）
| |-- verification-loop/ # 持续验证（长文指南）
| |-- golang-patterns/ # Go 惯用法与最佳实践
| |-- golang-testing/ # Go 测试模式、TDD 与基准测试
| |-- cpp-testing/ # 使用 GoogleTest、CMake/CTest 的 C++ 测试（新增）
| |-- cpp-coding-standards/ # 来自 C++ Core Guidelines 的 C++ 编码规范（新增）
| |-- cpp-testing/ # 使用 GoogleTest 与 CMake/CTest 的 C++ 测试（新增）
| |-- django-patterns/ # Django 模式、模型与视图（新增）
| |-- django-security/ # Django 安全最佳实践（新增）
| |-- django-tdd/ # Django TDD 工作流（新增）
@@ -228,25 +258,46 @@ everything-claude-code/
| |-- springboot-patterns/ # Java Spring Boot 模式（新增）
| |-- springboot-security/ # Spring Boot 安全（新增）
| |-- springboot-tdd/ # Spring Boot TDD（新增）
| |-- springboot-verification/ # Spring Boot 验证流程（新增）
| |-- springboot-verification/ # Spring Boot 验证（新增）
| |-- configure-ecc/ # 交互式安装向导（新增）
| |-- security-scan/ # AgentShield 安全审计集成（新增）
| |-- java-coding-standards/ # Java 编码规范（新增）
| |-- jpa-patterns/ # JPA/Hibernate 模式（新增）
| |-- postgres-patterns/ # PostgreSQL 优化模式（新增）
| |-- nutrient-document-processing/ # 使用 Nutrient API 的文档处理（新增）
| |-- project-guidelines-example/ # 项目专用技能模板
| |-- database-migrations/ # 迁移模式（Prisma、Drizzle、Django、Go）（新增）
| |-- api-design/ # REST API 设计、分页与错误响应（新增）
| |-- deployment-patterns/ # CI/CD、Docker、健康检查与回滚（新增）
| |-- docker-patterns/ # Docker Compose、网络、卷与容器安全（新增）
| |-- e2e-testing/ # Playwright 端到端模式与页面对象模型（新增）
| |-- content-hash-cache-pattern/ # 基于 SHA-256 内容哈希的文件处理缓存（新增）
| |-- cost-aware-llm-pipeline/ # LLM 成本优化、模型路由与预算跟踪（新增）
| |-- regex-vs-llm-structured-text/ # 决策框架：文本解析使用正则还是 LLM（新增）
| |-- swift-actor-persistence/ # 使用 Actor 实现线程安全的 Swift 数据持久化（新增）
| |-- swift-protocol-di-testing/ # 基于协议的依赖注入，实现可测试的 Swift 代码（新增）
| |-- search-first/ # 先研究后编码的工作流（新增）
| |-- skill-stocktake/ # 技能与命令质量审计（新增）
| |-- liquid-glass-design/ # iOS 26 Liquid Glass 设计系统（新增）
| |-- foundation-models-on-device/ # Apple 设备端 LLM 与 FoundationModels（新增）
| |-- swift-concurrency-6-2/ # Swift 6.2 易用并发（新增）
|
|-- commands/ # 快捷执行的 Slash 命令
|-- commands/ # 快速执行的斜杠命令
| |-- tdd.md # /tdd - 测试驱动开发
| |-- plan.md # /plan - 实现规划
| |-- e2e.md # /e2e - 端到端测试生成
| |-- code-review.md # /code-review - 质量审查
| |-- build-fix.md # /build-fix - 修复构建错误
| |-- refactor-clean.md # /refactor-clean - 清理无用代码
| |-- learn.md # /learn - 会话中提取模式（长文档指南）
| |-- checkpoint.md # /checkpoint - 保存验证状态（长文档指南）
| |-- verify.md # /verify - 运行验证循环（长文档指南）
| |-- refactor-clean.md # /refactor-clean - 无用代码清理
| |-- learn.md # /learn - 会话中提取模式（长文指南）
| |-- learn-eval.md # /learn-eval - 提取、评估并保存模式（新增）
| |-- checkpoint.md # /checkpoint - 保存验证状态（长文指南）
| |-- verify.md # /verify - 执行验证循环（长文指南）
| |-- setup-pm.md # /setup-pm - 配置包管理器
| |-- go-review.md # /go-review - Go 代码审查（新增）
| |-- go-test.md # /go-test - Go 的 TDD 工作流（新增）
| |-- go-test.md # /go-test - Go TDD 工作流（新增）
| |-- go-build.md # /go-build - 修复 Go 构建错误（新增）
| |-- skill-create.md # /skill-create - 从 Git 历史生成技能（新增）
| |-- skill-create.md # /skill-create - 从 git 历史生成技能（新增）
| |-- instinct-status.md # /instinct-status - 查看已学习的直觉（新增）
| |-- instinct-import.md # /instinct-import - 导入直觉（新增）
| |-- instinct-export.md # /instinct-export - 导出直觉（新增）
@@ -257,26 +308,34 @@ everything-claude-code/
| |-- multi-backend.md # /multi-backend - 后端多服务编排（新增）
| |-- multi-frontend.md # /multi-frontend - 前端多服务编排（新增）
| |-- multi-workflow.md # /multi-workflow - 通用多服务工作流（新增）
| |-- orchestrate.md # /orchestrate - 多代理协调
| |-- sessions.md # /sessions - 会话历史管理
| |-- eval.md # /eval - 按标准评估
| |-- test-coverage.md # /test-coverage - 测试覆盖率分析
| |-- update-docs.md # /update-docs - 更新文档
| |-- update-codemaps.md # /update-codemaps - 更新代码映射
| |-- python-review.md # /python-review - Python 代码审查（新增）
|
|-- rules/ # 必须遵循的规则（复制到 ~/.claude/rules/）
| |-- README.md # 结构概览与安装指南
| |-- common/ # 与语言无关的通用原则
| |-- README.md # 结构说明与安装指南
| |-- common/ # 与语言无关的原则
| | |-- coding-style.md # 不可变性与文件组织
| | |-- git-workflow.md # 提交格式与 PR 流程
| | |-- testing.md # TDD，80% 覆盖率要求
| | |-- testing.md # TDD 与 80% 覆盖率要求
| | |-- performance.md # 模型选择与上下文管理
| | |-- patterns.md # 设计模式与项目骨架
| | |-- patterns.md # 设计模式与骨架项目
| | |-- hooks.md # Hook 架构与 TodoWrite
| | |-- agents.md # 何时委派给子代理
| | |-- security.md # 强制安全检查
| |-- typescript/ # TypeScript / JavaScript 专用
| |-- typescript/ # TypeScript/JavaScript 专用
| |-- python/ # Python 专用
| |-- golang/ # Go 专用
|
|-- hooks/ # 基于触发器的自动化
| |-- README.md # Hook 文档、示例与自定义指南
| |-- hooks.json # 所有 Hook 配置（PreToolUse、PostToolUse、Stop 等）
| |-- memory-persistence/ # 会话生命周期 Hook（长文档指南）
| |-- strategic-compact/ # 压缩建议（长文档指南）
| |-- memory-persistence/ # 会话生命周期 Hook（长文指南）
| |-- strategic-compact/ # 压缩建议（长文指南）
|
|-- scripts/ # 跨平台 Node.js 脚本（新增）
| |-- lib/ # 共享工具
@@ -286,7 +345,7 @@ everything-claude-code/
| | |-- session-start.js # 会话开始时加载上下文
| | |-- session-end.js # 会话结束时保存状态
| | |-- pre-compact.js # 压缩前状态保存
| | |-- suggest-compact.js # 战略性压缩建议
| | |-- suggest-compact.js # 战略压缩建议
| | |-- evaluate-session.js # 从会话中提取模式
| |-- setup-package-manager.js # 交互式包管理器设置
|
@@ -295,19 +354,23 @@ everything-claude-code/
| |-- hooks/ # Hook 测试
| |-- run-all.js # 运行所有测试
|
|-- contexts/ # 动态系统提示注入上下文（长文档指南）
|-- contexts/ # 动态系统提示注入上下文（长文指南）
| |-- dev.md # 开发模式上下文
| |-- review.md # 代码审查模式上下文
| |-- research.md # 研究/探索模式上下文
|
|-- examples/ # 示例配置与会话
| |-- CLAUDE.md # 项目级配置示例
| |-- user-CLAUDE.md # 用户级配置示例
| |-- CLAUDE.md # 项目级配置示例
| |-- user-CLAUDE.md # 用户级配置示例
| |-- saas-nextjs-CLAUDE.md # 实际 SaaS 示例（Next.js + Supabase + Stripe）
| |-- go-microservice-CLAUDE.md # 实际 Go 微服务示例（gRPC + PostgreSQL）
| |-- django-api-CLAUDE.md # 实际 Django REST API 示例（DRF + Celery）
| |-- rust-api-CLAUDE.md # 实际 Rust API 示例（Axum + SQLx + PostgreSQL）（新增）
|
|-- mcp-configs/ # MCP 服务器配置
| |-- mcp-servers.json # GitHub、Supabase、Vercel、Railway 等
|
|-- marketplace.json # 自托管插件市场配置（用于 /plugin marketplace add）
|-- marketplace.json # 自托管市场配置（用于 /plugin marketplace add）
```
***
@@ -350,6 +413,8 @@ everything-claude-code/
### AgentShield — 安全审计器
> 在 Claude Code 黑客马拉松（Cerebral Valley x Anthropic，2026年2月）上构建。1282 项测试，98% 覆盖率，102 条静态分析规则。
扫描您的 Claude Code 配置，查找漏洞、错误配置和注入风险。
```bash
@@ -359,14 +424,18 @@ npx ecc-agentshield scan
# Auto-fix safe issues
npx ecc-agentshield scan --fix
# Deep analysis with Opus 4.6
# Deep analysis with three Opus 4.6 agents
npx ecc-agentshield scan --opus --stream
# Generate secure config from scratch
npx ecc-agentshield init
```
检查 CLAUDE.md、settings.json、MCP 服务器、钩子和智能体定义。生成带有可操作发现的安全等级 (A-F)。
**它扫描什么：** CLAUDE.md、settings.json、MCP 配置、钩子、代理定义以及 5 个类别的技能 —— 密钥检测（14 种模式）、权限审计、钩子注入分析、MCP 服务器风险剖析和代理配置审查。
**`--opus` 标志** 在红队/蓝队/审计员管道中运行三个 Claude Opus 4.6 代理。攻击者寻找利用链，防御者评估保护措施，审计员将两者综合成优先风险评估。对抗性推理，而不仅仅是模式匹配。
**输出格式：** 终端（按颜色分级的 A-F）、JSON（CI 管道）、Markdown、HTML。在关键发现时退出代码 2，用于构建门控。
在 Claude Code 中使用 `/security-scan` 来运行它，或者通过 [GitHub Action](https://github.com/affaan-m/agentshield) 添加到 CI。
@@ -449,23 +518,23 @@ Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded fil
这将使您能够立即访问所有命令、代理、技能和钩子。
> **注意：** Claude Code 插件系统不支持通过插件分发 `rules`（[上游限制](https://code.claude.com/docs/en/plugins-reference)）。您需要手动安装规则：
> **注意：** Claude Code 插件系统不支持通过插件分发 `rules`（[上游限制](https://code.claude.com/docs/en/plugins-reference)）。你需要手动安装规则：
>
> ```bash
> # 首先克隆仓库
> git clone https://github.com/affaan-m/everything-claude-code.git
>
> # 选项 A：用户级规则（适用于所有项目）
> # 选项 A：用户级规则（应用于所有项目）
> mkdir -p ~/.claude/rules
> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # 选择您的技术栈
> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # 选择你的技术栈
> cp -r everything-claude-code/rules/python/* ~/.claude/rules/
> cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
>
> # 选项 B：项目级规则（仅适用于当前项目）
> # 选项 B：项目级规则（仅应用于当前项目）
> mkdir -p .claude/rules
> cp -r everything-claude-code/rules/common/* .claude/rules/
> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # 选择您的技术栈
> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # 选择你的技术栈
> ```
***
@@ -564,7 +633,136 @@ rules/
golang/ # Go specific patterns and tools
```
有关安装和结构详情，请参阅 [`rules/README.md`](rules/README.md)。
有关安装和结构详情，请参阅 [`rules/README.md`](../../rules/README.md)。
***
## 🗺️ 我应该使用哪个代理？
不确定从哪里开始？使用这个快速参考：
| 我想要... | 使用此命令 | 使用的代理 |
|--------------|-----------------|------------|
| 规划新功能 | `/everything-claude-code:plan "Add auth"` | planner |
| 设计系统架构 | `/everything-claude-code:plan` + architect agent | architect |
| 先写带测试的代码 | `/tdd` | tdd-guide |
| 审查我刚写的代码 | `/code-review` | code-reviewer |
| 修复失败的构建 | `/build-fix` | build-error-resolver |
| 运行端到端测试 | `/e2e` | e2e-runner |
| 查找安全漏洞 | `/security-scan` | security-reviewer |
| 移除死代码 | `/refactor-clean` | refactor-cleaner |
| 更新文档 | `/update-docs` | doc-updater |
| 审查 Go 代码 | `/go-review` | go-reviewer |
| 审查 Python 代码 | `/python-review` | python-reviewer |
| 审计数据库查询 | *(自动委派)* | database-reviewer |
### 常见工作流
**开始新功能：**
```
/everything-claude-code:plan "Add user authentication with OAuth"
→ planner creates implementation blueprint
/tdd → tdd-guide enforces write-tests-first
/code-review → code-reviewer checks your work
```
**修复错误：**
```
/tdd → tdd-guide: write a failing test that reproduces it
→ implement the fix, verify test passes
/code-review → code-reviewer: catch regressions
```
**准备生产环境：**
```
/security-scan → security-reviewer: OWASP Top 10 audit
/e2e → e2e-runner: critical user flow tests
/test-coverage → verify 80%+ coverage
```
***
## ❓ 常见问题
<details>
<summary><b>How do I check which agents/commands are installed?</b></summary>
```bash
/plugin list everything-claude-code@everything-claude-code
```
这会显示插件中所有可用的代理、命令和技能。
</details>
<details>
<summary><b>My hooks aren't working / I see "Duplicate hooks file" errors</b></summary>
这是最常见的问题。**不要在 `.claude-plugin/plugin.json` 中添加 `"hooks"` 字段。** Claude Code v2.1+ 会自动从已安装的插件加载 `hooks/hooks.json`。显式声明它会导致重复检测错误。参见 [#29](https://github.com/affaan-m/everything-claude-code/issues/29), [#52](https://github.com/affaan-m/everything-claude-code/issues/52), [#103](https://github.com/affaan-m/everything-claude-code/issues/103)。
</details>
<details>
<summary><b>My context window is shrinking / Claude is running out of context</b></summary>
太多的 MCP 服务器会消耗你的上下文。每个 MCP 工具描述都会消耗你 200k 窗口的令牌，可能将其减少到约 70k。
**修复：** 按项目禁用未使用的 MCP：
```json
// In your project's .claude/settings.json
{
"disabledMcpServers": ["supabase", "railway", "vercel"]
}
```
保持启用的 MCP 少于 10 个，活动工具少于 80 个。
</details>
<details>
<summary><b>Can I use only some components (e.g., just agents)?</b></summary>
是的。使用选项 2（手动安装）并仅复制你需要的部分：
```bash
# Just agents
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Just rules
cp -r everything-claude-code/rules/common/* ~/.claude/rules/
```
每个组件都是完全独立的。
</details>
<details>
<summary><b>Does this work with Cursor / OpenCode / Codex?</b></summary>
是的。ECC 是跨平台的：
* **Cursor**：`.cursor/` 中的预翻译配置。参见 [Cursor IDE 支持](#cursor-ide-支持)。
* **OpenCode**：`.opencode/` 中的完整插件支持。参见 [OpenCode 支持](#-opencode-支持)。
* **Codex**：提供适配器漂移保护和 SessionStart 回退的一流支持。参见 PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257)。
* **Claude Code**：原生支持 — 这是主要目标。
</details>
<details>
<summary><b>How do I contribute a new skill or agent?</b></summary>
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。简短版本：
1. Fork 仓库
2. 在 `skills/your-skill-name/SKILL.md` 中创建你的技能（带有 YAML 前言）
3. 或在 `agents/your-agent.md` 中创建代理
4. 提交 PR，清晰描述其功能和使用时机
</details>
***
@@ -609,31 +807,109 @@ node tests/hooks/hooks.test.js
## Cursor IDE 支持
ecc-universal 包含为 [Cursor IDE](https://cursor.com) 预翻译的配置。`.cursor/` 目录包含适用于 Cursor 格式的规则、智能体、技能、命令和 MCP 配置。
ECC 提供**完整的 Cursor IDE 支持**，包括为 Cursor 原生格式适配的钩子、规则、代理、技能、命令和 MCP 配置。
### 快速开始 (Cursor)
```bash
# Install the package
npm install ecc-universal
# Install for your language(s)
./install.sh --target cursor typescript
./install.sh --target cursor python golang
./install.sh --target cursor python golang swift
```
### 已翻译内容
### 包含内容
| 组件 | Claude Code → Cursor | 对等性 |
|-----------|---------------------|--------|
| 规则 | 添加了 YAML frontmatter，路径扁平化 | 完全 |
| 智能体 | 模型 ID 已扩展，工具 → 只读标志 | 完全 |
| 技能 | 无需更改 (标准相同) | 相同 |
| 命令 | 路径引用已更新，多-\* 已存根 | 部分 |
| MCP 配置 | 环境变量插值语法已更新 | 完全 |
| 钩子 | Cursor 中无等效项 | 参见替代方案 |
| 组件 | 数量 | 详情 |
|-----------|-------|---------|
| 钩子事件 | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, 以及另外 10 个 |
| 钩子脚本 | 16 | 通过共享适配器委托给 `scripts/hooks/` 的轻量 Node.js 脚本 |
| 规则 | 29 | 9 条通用规则 (alwaysApply) + 20 条语言特定规则 (TypeScript, Python, Go, Swift) |
| 代理 | 共享 | 通过根目录下的 AGENTS.md（被 Cursor 原生读取） |
| 技能 | 共享 + 捆绑 | 通过根目录下的 AGENTS.md 和用于翻译补充的 `.cursor/skills/` |
| 命令 | 共享 | `.cursor/commands/`（如果已安装） |
| MCP 配置 | 共享 | `.cursor/mcp.json`（如果已安装） |
详情请参阅 [.cursor/README.md](.cursor/README.md)，完整迁移指南请参阅 [.cursor/MIGRATION.md](.cursor/MIGRATION.md)。
### 钩子架构（DRY 适配器模式）
Cursor 的**钩子事件比 Claude Code 多**（20 对 8）。`.cursor/hooks/adapter.js` 模块将 Cursor 的 stdin JSON 转换为 Claude Code 的格式，允许重用现有的 `scripts/hooks/*.js` 而无需重复。
```
Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js
(shared with Claude Code)
```
关键钩子：
* **beforeShellExecution** — 阻止在 tmux 外启动开发服务器（退出码 2），git push 审查
* **afterFileEdit** — 自动格式化 + TypeScript 检查 + console.log 警告
* **beforeSubmitPrompt** — 检测提示中的密钥（sk-、ghp\_、AKIA 模式）
* **beforeTabFileRead** — 阻止 Tab 读取 .env、.key、.pem 文件（退出码 2）
* **beforeMCPExecution / afterMCPExecution** — MCP 审计日志记录
### 规则格式
Cursor 规则使用带有 `description`、`globs` 和 `alwaysApply` 的 YAML 前言：
```yaml
---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---
```
***
## Codex CLI 支持
ECC 提供**一流的 Codex CLI 支持**，包含参考配置、Codex 特定的 AGENTS.md 补充和 16 个移植的技能。
### 快速开始（Codex）
```bash
# Copy the reference config to your home directory
cp .codex/config.toml ~/.codex/config.toml
# Run Codex in the repo — AGENTS.md is auto-detected
codex
```
### 包含内容
| 组件 | 数量 | 详情 |
|-----------|-------|---------|
| 配置 | 1 | `.codex/config.toml` — 模型、权限、MCP 服务器、持久指令 |
| AGENTS.md | 2 | 根目录（通用）+ `.codex/AGENTS.md`（Codex 特定补充） |
| 技能 | 16 | `.agents/skills/` — 每个技能包含 SKILL.md + agents/openai.yaml |
| MCP 服务器 | 4 | GitHub、Context7、Memory、Sequential Thinking（基于命令） |
| 配置文件 | 2 | `strict`（只读沙箱）和 `yolo`（完全自动批准） |
### 技能
位于 `.agents/skills/` 的技能会被 Codex 自动加载：
| 技能 | 描述 |
|-------|-------------|
| tdd-workflow | 测试驱动开发，覆盖率 80%+ |
| security-review | 全面的安全检查清单 |
| coding-standards | 通用编码标准 |
| frontend-patterns | React/Next.js 模式 |
| frontend-slides | HTML 演示文稿、PPTX 转换、视觉风格探索 |
| article-writing | 根据笔记和语音参考进行长文写作 |
| content-engine | 平台原生的社交内容和再利用 |
| market-research | 带来源归属的市场和竞争对手研究 |
| investor-materials | 幻灯片、备忘录、模型和一页纸文档 |
| investor-outreach | 个性化外联、跟进和介绍摘要 |
| backend-patterns | API 设计、数据库、缓存 |
| e2e-testing | Playwright 端到端测试 |
| eval-harness | 评估驱动的开发 |
| strategic-compact | 上下文管理 |
| api-design | REST API 设计模式 |
| verification-loop | 构建、测试、代码检查、类型检查、安全 |
### 关键限制
Codex CLI **尚不支持钩子**（[GitHub Issue #2109](https://github.com/openai/codex/issues/2109)，430+ 点赞）。安全强制执行是通过 `persistent_instructions` 中的指令和沙箱权限系统实现的。
***
@@ -655,15 +931,15 @@ opencode
### 功能对等
| 特性 | Claude Code | OpenCode | 状态 |
| 功能 | Claude Code | OpenCode | 状态 |
|---------|-------------|----------|--------|
| 智能体 | ✅ 14 agents | ✅ 12 agents | **Claude Code 领先** |
| 命令 | ✅ 30 commands | ✅ 24 commands | **Claude Code 领先** |
| 技能 | ✅ 28 skills | ✅ 16 skills | **Claude Code 领先** |
| 钩子 | ✅ 3 phases | ✅ 20+ events | **OpenCode 更多！** |
| 规则 | ✅ 8 rules | ✅ 8 rules | **完全一致** |
| MCP Servers | ✅ Full | ✅ Full | **完全一致** |
| 自定义工具 | ✅ Via hooks | ✅ Native support | **OpenCode 更好** |
| 代理 | ✅ 13 个代理 | ✅ 12 个代理 | **Claude Code 领先** |
| 命令 | ✅ 33 个命令 | ✅ 24 个命令 | **Claude Code 领先** |
| 技能 | ✅ 50+ 个技能 | ✅ 37 个技能 | **Claude Code 领先** |
| 钩子 | ✅ 8 种事件类型 | ✅ 11 种事件 | **OpenCode 更多！** |
| 规则 | ✅ 29 条规则 | ✅ 13 条指令 | **Claude Code 领先** |
| MCP 服务器 | ✅ 14 个服务器 | ✅ 完整支持 | **完全对等** |
| 自定义工具 | ✅ 通过钩子 | ✅ 6 个原生工具 | **OpenCode 更好** |
### 通过插件实现的钩子支持
@@ -679,14 +955,13 @@ OpenCode 的插件系统比 Claude Code 更复杂，有 20 多种事件类型：
**额外的 OpenCode 事件**：`file.edited`、`file.watcher.updated`、`message.updated`、`lsp.client.diagnostics`、`tui.toast.show` 等等。
### 可用命令 (24)
### 可用命令（32个）
| 命令 | 描述 |
|---------|-------------|
| `/plan` | 创建实施计划 |
| `/tdd` | 强制执行 TDD 工作流 |
| `/code-review` | 审查代码变更 |
| `/security` | 运行安全审查 |
| `/build-fix` | 修复构建错误 |
| `/e2e` | 生成端到端测试 |
| `/refactor-clean` | 移除死代码 |
@@ -701,11 +976,20 @@ OpenCode 的插件系统比 Claude Code 更复杂，有 20 多种事件类型：
| `/go-review` | Go 代码审查 |
| `/go-test` | Go TDD 工作流 |
| `/go-build` | 修复 Go 构建错误 |
| `/python-review` | Python 代码审查（PEP 8、类型提示、安全） |
| `/multi-plan` | 多模型协作规划 |
| `/multi-execute` | 多模型协作执行 |
| `/multi-backend` | 后端聚焦的多模型工作流 |
| `/multi-frontend` | 前端聚焦的多模型工作流 |
| `/multi-workflow` | 完整的多模型开发工作流 |
| `/pm2` | 自动生成 PM2 服务命令 |
| `/sessions` | 管理会话历史 |
| `/skill-create` | 从 git 生成技能 |
| `/instinct-status` | 查看习得的本能 |
| `/instinct-status` | 查看已学习的本能 |
| `/instinct-import` | 导入本能 |
| `/instinct-export` | 导出本能 |
| `/evolve` | 将本能聚类为技能 |
| `/learn-eval` | 在保存前提取和评估模式 |
| `/setup-pm` | 配置包管理器 |
### 插件安装
@@ -740,6 +1024,35 @@ npm install ecc-universal
***
## 跨工具功能对等
ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以下是每个平台的比较：
| 功能 | Claude Code | Cursor IDE | Codex CLI | OpenCode |
|---------|------------|------------|-----------|----------|
| **代理** | 13 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
| **命令** | 33 | 共享 | 基于指令 | 24 |
| **技能** | 50+ | 共享 | 10 (原生格式) | 37 |
| **钩子事件** | 8 种类型 | 15 种类型 | 尚无 | 11 种类型 |
| **钩子脚本** | 9 个脚本 | 16 个脚本 (DRY 适配器) | 不适用 | 插件钩子 |
| **规则** | 29 (通用 + 语言) | 29 (YAML 前言) | 基于指令 | 13 条指令 |
| **自定义工具** | 通过钩子 | 通过钩子 | 不适用 | 6 个原生工具 |
| **MCP 服务器** | 14 | 共享 (mcp.json) | 4 (基于命令) | 完整 |
| **配置格式** | settings.json | hooks.json + rules/ | config.toml | opencode.json |
| **上下文文件** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md |
| **密钥检测** | 基于钩子 | beforeSubmitPrompt 钩子 | 基于沙箱 | 基于钩子 |
| **自动格式化** | PostToolUse 钩子 | afterFileEdit 钩子 | 不适用 | file.edited 钩子 |
| **版本** | 插件 | 插件 | 参考配置 | 1.6.0 |
**关键架构决策：**
* 根目录下的 **AGENTS.md** 是通用的跨工具文件（被所有 4 个工具读取）
* **DRY 适配器模式** 让 Cursor 可以重用 Claude Code 的钩子脚本而无需重复
* **技能格式**（带有 YAML 前言的 SKILL.md）在 Claude Code、Codex 和 OpenCode 上都能工作
* Codex 缺乏钩子的问题通过 `persistent_instructions` 和沙箱权限来弥补
***
## 📖 背景
我从实验性推出以来就一直在使用 Claude Code。在 2025 年 9 月，与 [@DRodriguezFX](https://x.com/DRodriguezFX) 一起使用 Claude Code 构建 [zenith.chat](https://zenith.chat)，赢得了 Anthropic x Forum Ventures 黑客马拉松。
@@ -748,19 +1061,96 @@ npm install ecc-universal
***
## ⚠️ 重要说明
## 令牌优化
如果不管理令牌消耗，使用 Claude Code 可能会很昂贵。这些设置能在不牺牲质量的情况下显著降低成本。
### 推荐设置
添加到 `~/.claude/settings.json`：
```json
{
"model": "sonnet",
"env": {
"MAX_THINKING_TOKENS": "10000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
}
}
```
| 设置 | 默认值 | 推荐值 | 影响 |
|---------|---------|-------------|--------|
| `model` | opus | **sonnet** | 约 60% 的成本降低；处理 80%+ 的编码任务 |
| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | 每个请求的隐藏思考成本降低约 70% |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | 更早压缩 —— 在长会话中质量更好 |
仅在需要深度架构推理时切换到 Opus：
```
/model opus
```
### 日常工作流命令
| 命令 | 何时使用 |
|---------|-------------|
| `/model sonnet` | 大多数任务的默认选择 |
| `/model opus` | 复杂架构、调试、深度推理 |
| `/clear` | 在不相关的任务之间（免费，即时重置） |
| `/compact` | 在逻辑任务断点处（研究完成，里程碑达成） |
| `/cost` | 在会话期间监控令牌花费 |
### 策略性压缩
`strategic-compact` 技能（包含在此插件中）建议在逻辑断点处进行 `/compact`，而不是依赖在 95% 上下文时的自动压缩。完整决策指南请参见 `skills/strategic-compact/SKILL.md`。
**何时压缩：**
* 研究/探索之后，实施之前
* 完成一个里程碑之后，开始下一个之前
* 调试之后，继续功能工作之前
* 失败的方法之后，尝试新方法之前
**何时不压缩：**
* 实施过程中（你会丢失变量名、文件路径、部分状态）
### 上下文窗口管理
**关键：** 不要一次性启用所有 MCP。启用过多工具后，你的 200k 上下文窗口可能会缩小到 70k。
**关键：** 不要一次性启用所有 MCP。每个 MCP 工具描述都会消耗你 200k 窗口的令牌，可能将其减少到约 70k。
经验法则：
* 每个项目保持启用的 MCP 少于 10 个
* 保持活动工具少于 80 个
* 在项目配置中使用 `disabledMcpServers` 来禁用未使用的 MCP
* 配置 20-30 个 MCP
* 每个项目保持启用少于 10 个
* 活动工具少于 80 个
### 代理团队成本警告
在项目配置中使用 `disabledMcpServers` 来禁用未使用的工具。
代理团队会生成多个上下文窗口。每个团队成员独立消耗令牌。仅用于并行性能提供明显价值的任务（多模块工作、并行审查）。对于简单的顺序任务，子代理更节省令牌。
***
## ⚠️ 重要说明
### 令牌优化
达到每日限制？参见 **[令牌优化指南](../token-optimization.md)** 获取推荐设置和工作流提示。
快速见效的方法：
```json
// ~/.claude/settings.json
{
"model": "sonnet",
"env": {
"MAX_THINKING_TOKENS": "10000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
}
}
```
在不相关的任务之间使用 `/clear`，在逻辑断点处使用 `/compact`，并使用 `/cost` 来监控花费。
### 定制化
@@ -773,6 +1163,14 @@ npm install ecc-universal
***
## 💜 赞助商
这个项目是免费和开源的。赞助商帮助保持其维护和发展。
[**成为赞助商**](https://github.com/sponsors/affaan-m) | [赞助商等级](SPONSORS.md)
***
## 🌟 Star 历史
[![Star History Chart](https://api.star-history.com/svg?repos=affaan-m/everything-claude-code\&type=Date)](https://star-history.com/#affaan-m/everything-claude-code\&Date)
@@ -781,11 +1179,11 @@ npm install ecc-universal
## 🔗 链接
* **速查指南 (从此开始):** [Claude Code 万事速查指南](https://x.com/affaanmustafa/status/2012378465664745795)
* **详细指南 (进阶):** [Claude Code 万事详细指南](https://x.com/affaanmustafa/status/2014040193557471352)
* **关注:** [@affaanmustafa](https://x.com/affaanmustafa)
* **zenith.chat:** [zenith.chat](https://zenith.chat)
* **技能目录:** awesome-agent-skills（社区维护的智能体技能目录）
* **速查指南（从这里开始）：** [Claude Code 速查指南](https://x.com/affaanmustafa/status/2012378465664745795)
* **详细指南（进阶）：** [Claude Code 详细指南](https://x.com/affaanmustafa/status/2014040193557471352)
* **关注：** [@affaanmustafa](https://x.com/affaanmustafa)
* **zenith.chat：** [zenith.chat](https://zenith.chat)
* **技能目录：** awesome-agent-skills（社区维护的智能体技能目录）
***

585
docs/zh-CN/agents/build-error-resolver.md
View File

@@ -1,556 +1,119 @@
---
name: build-error-resolver
description: 构建与TypeScript错误解决专家。在构建失败或类型错误发生时主动使用。仅通过最小差异修复构建/类型错误，不进行架构编辑。专注于快速使构建变绿。
description: 构建和TypeScript错误解决专家。在构建失败或类型错误发生时主动使用。仅以最小差异修复构建/类型错误，不进行架构编辑。专注于快速使构建通过。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# 构建错误解决器
你是一位专注于快速高效修复 TypeScript、编译和构建错误的构建错误解决专家。你的任务是让构建通过，且改动最小，不进行架构修改。
你是一名专业的构建错误解决专家。你的任务是以最小的改动让构建通过——不重构、不改变架构、不进行改进。
## 核心职责
1. **TypeScript 错误解决** - 修复类型错误、推断问题、泛型约束
2. **构建错误修复** - 解决编译失败、模块解析问题
3. **依赖项问题** - 修复导入错误、缺失的包、版本冲突
4. **配置错误** - 解决 tsconfig.json、webpack、Next.js 配置问题
5. **最小化差异** - 做出尽可能小的更改来修复错误
6. **无架构更改** - 只修复错误，不重构或重新设计
1. **TypeScript 错误解决** — 修复类型错误、推断问题、泛型约束
2. **构建错误修复** — 解决编译失败、模块解析问题
3. **依赖问题** — 修复导入错误、缺失包、版本冲突
4. **配置错误** — 解决 tsconfig、webpack、Next.js 配置问题
5. **最小差异** — 做尽可能小的改动来修复错误
6. **不改变架构** — 只修复错误，不重新设计
## 可用的工具
### 构建和类型检查工具
* **tsc** - TypeScript 编译器，用于类型检查
* **npm/yarn** - 包管理
* **eslint** - 代码检查（可能导致构建失败）
* **next build** - Next.js 生产构建
### 诊断命令
## 诊断命令
```bash
# TypeScript type check (no emit)
npx tsc --noEmit
# TypeScript with pretty output
npx tsc --noEmit --pretty
# Show all errors (don't stop at first)
npx tsc --noEmit --pretty --incremental false
# Check specific file
npx tsc --noEmit path/to/file.ts
# ESLint check
npx eslint . --ext .ts,.tsx,.js,.jsx
# Next.js build (production)
npx tsc --noEmit --pretty --incremental false # Show all errors
npm run build
# Next.js build with debug
npm run build -- --debug
npx eslint . --ext .ts,.tsx,.js,.jsx
```
## 错误解决工作流程
## 工作流程
### 1. 收集所有错误
```
a) Run full type check
- npx tsc --noEmit --pretty
- Capture ALL errors, not just first
* 运行 `npx tsc --noEmit --pretty` 获取所有类型错误
* 分类：类型推断、缺失类型、导入、配置、依赖
* 优先级：首先处理阻塞构建的错误，然后是类型错误，最后是警告
b) Categorize errors by type
- Type inference failures
- Missing type definitions
- Import/export errors
- Configuration errors
- Dependency issues
### 2. 修复策略（最小改动）
c) Prioritize by impact
- Blocking build: Fix first
- Type errors: Fix in order
- Warnings: Fix if time permits
```
对于每个错误：
### 2. 修复策略（最小化更改）
1. 仔细阅读错误信息——理解预期与实际结果
2. 找到最小的修复方案（类型注解、空值检查、导入修复）
3. 验证修复不会破坏其他代码——重新运行 tsc
4. 迭代直到构建通过
```
For each error:
### 3. 常见修复
1. Understand the error
- Read error message carefully
- Check file and line number
- Understand expected vs actual type
| 错误 | 修复 |
|-------|-----|
| `implicitly has 'any' type` | 添加类型注解 |
| `Object is possibly 'undefined'` | 可选链 `?.` 或空值检查 |
| `Property does not exist` | 添加到接口或使用可选 `?` |
| `Cannot find module` | 检查 tsconfig 路径、安装包或修复导入路径 |
| `Type 'X' not assignable to 'Y'` | 解析/转换类型或修复类型 |
| `Generic constraint` | 添加 `extends { ... }` |
| `Hook called conditionally` | 将钩子移到顶层 |
| `'await' outside async` | 添加 `async` 关键字 |
2. Find minimal fix
- Add missing type annotation
- Fix import statement
- Add null check
- Use type assertion (last resort)
## 做与不做
3. Verify fix doesn't break other code
- Run tsc again after each fix
- Check related files
- Ensure no new errors introduced
**做：**
4. Iterate until build passes
- Fix one error at a time
- Recompile after each fix
- Track progress (X/Y errors fixed)
```
* 在缺失的地方添加类型注解
* 在需要的地方添加空值检查
* 修复导入/导出
* 添加缺失的依赖项
* 更新类型定义
* 修复配置文件
### 3. 常见错误模式及修复方法
**不做：**
**模式 1：类型推断失败**
* 重构无关代码
* 改变架构
* 重命名变量（除非导致错误）
* 添加新功能
* 改变逻辑流程（除非为了修复错误）
* 优化性能或样式
```typescript
// ❌ ERROR: Parameter 'x' implicitly has an 'any' type
function add(x, y) {
return x + y
}
## 优先级等级
// ✅ FIX: Add type annotations
function add(x: number, y: number): number {
return x + y
}
```
| 等级 | 症状 | 行动 |
|-------|----------|--------|
| 严重 | 构建完全中断，开发服务器无法启动 | 立即修复 |
| 高 | 单个文件失败，新代码类型错误 | 尽快修复 |
| 中 | 代码检查警告、已弃用的 API | 在可能时修复 |
**模式 2：Null/Undefined 错误**
```typescript
// ❌ ERROR: Object is possibly 'undefined'
const name = user.name.toUpperCase()
// ✅ FIX: Optional chaining
const name = user?.name?.toUpperCase()
// ✅ OR: Null check
const name = user && user.name ? user.name.toUpperCase() : ''
```
**模式 3：缺少属性**
```typescript
// ❌ ERROR: Property 'age' does not exist on type 'User'
interface User {
name: string
}
const user: User = { name: 'John', age: 30 }
// ✅ FIX: Add property to interface
interface User {
name: string
age?: number // Optional if not always present
}
```
**模式 4：导入错误**
```typescript
// ❌ ERROR: Cannot find module '@/lib/utils'
import { formatDate } from '@/lib/utils'
// ✅ FIX 1: Check tsconfig paths are correct
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}
// ✅ FIX 2: Use relative import
import { formatDate } from '../lib/utils'
// ✅ FIX 3: Install missing package
npm install @/lib/utils
```
**模式 5：类型不匹配**
```typescript
// ❌ ERROR: Type 'string' is not assignable to type 'number'
const age: number = "30"
// ✅ FIX: Parse string to number
const age: number = parseInt("30", 10)
// ✅ OR: Change type
const age: string = "30"
```
**模式 6：泛型约束**
```typescript
// ❌ ERROR: Type 'T' is not assignable to type 'string'
function getLength<T>(item: T): number {
return item.length
}
// ✅ FIX: Add constraint
function getLength<T extends { length: number }>(item: T): number {
return item.length
}
// ✅ OR: More specific constraint
function getLength<T extends string | any[]>(item: T): number {
return item.length
}
```
**模式 7：React Hook 错误**
```typescript
// ❌ ERROR: React Hook "useState" cannot be called in a function
function MyComponent() {
if (condition) {
const [state, setState] = useState(0) // ERROR!
}
}
// ✅ FIX: Move hooks to top level
function MyComponent() {
const [state, setState] = useState(0)
if (!condition) {
return null
}
// Use state here
}
```
**模式 8：Async/Await 错误**
```typescript
// ❌ ERROR: 'await' expressions are only allowed within async functions
function fetchData() {
const data = await fetch('/api/data')
}
// ✅ FIX: Add async keyword
async function fetchData() {
const data = await fetch('/api/data')
}
```
**模式 9：模块未找到**
```typescript
// ❌ ERROR: Cannot find module 'react' or its corresponding type declarations
import React from 'react'
// ✅ FIX: Install dependencies
npm install react
npm install --save-dev @types/react
// ✅ CHECK: Verify package.json has dependency
{
"dependencies": {
"react": "^19.0.0"
},
"devDependencies": {
"@types/react": "^19.0.0"
}
}
```
**模式 10：Next.js 特定错误**
```typescript
// ❌ ERROR: Fast Refresh had to perform a full reload
// Usually caused by exporting non-component
// ✅ FIX: Separate exports
// ❌ WRONG: file.tsx
export const MyComponent = () => <div />
export const someConstant = 42 // Causes full reload
// ✅ CORRECT: component.tsx
export const MyComponent = () => <div />
// ✅ CORRECT: constants.ts
export const someConstant = 42
```
## 项目特定的构建问题示例
### Next.js 15 + React 19 兼容性
```typescript
// ❌ ERROR: React 19 type changes
import { FC } from 'react'
interface Props {
children: React.ReactNode
}
const Component: FC<Props> = ({ children }) => {
return <div>{children}</div>
}
// ✅ FIX: React 19 doesn't need FC
interface Props {
children: React.ReactNode
}
const Component = ({ children }: Props) => {
return <div>{children}</div>
}
```
### Supabase 客户端类型
```typescript
// ❌ ERROR: Type 'any' not assignable
const { data } = await supabase
.from('markets')
.select('*')
// ✅ FIX: Add type annotation
interface Market {
id: string
name: string
slug: string
// ... other fields
}
const { data } = await supabase
.from('markets')
.select('*') as { data: Market[] | null, error: any }
```
### Redis Stack 类型
```typescript
// ❌ ERROR: Property 'ft' does not exist on type 'RedisClientType'
const results = await client.ft.search('idx:markets', query)
// ✅ FIX: Use proper Redis Stack types
import { createClient } from 'redis'
const client = createClient({
url: process.env.REDIS_URL
})
await client.connect()
// Type is inferred correctly now
const results = await client.ft.search('idx:markets', query)
```
### Solana Web3.js 类型
```typescript
// ❌ ERROR: Argument of type 'string' not assignable to 'PublicKey'
const publicKey = wallet.address
// ✅ FIX: Use PublicKey constructor
import { PublicKey } from '@solana/web3.js'
const publicKey = new PublicKey(wallet.address)
```
## 最小化差异策略
**关键：做出尽可能小的更改**
### 应该做：
✅ 在缺少的地方添加类型注解
✅ 在需要的地方添加空值检查
✅ 修复导入/导出
✅ 添加缺失的依赖项
✅ 更新类型定义
✅ 修复配置文件
### 不应该做：
❌ 重构无关的代码
❌ 更改架构
❌ 重命名变量/函数（除非导致错误）
❌ 添加新功能
❌ 更改逻辑流程（除非为了修复错误）
❌ 优化性能
❌ 改进代码风格
**最小化差异示例：**
```typescript
// File has 200 lines, error on line 45
// ❌ WRONG: Refactor entire file
// - Rename variables
// - Extract functions
// - Change patterns
// Result: 50 lines changed
// ✅ CORRECT: Fix only the error
// - Add type annotation on line 45
// Result: 1 line changed
function processData(data) { // Line 45 - ERROR: 'data' implicitly has 'any' type
return data.map(item => item.value)
}
// ✅ MINIMAL FIX:
function processData(data: any[]) { // Only change this line
return data.map(item => item.value)
}
// ✅ BETTER MINIMAL FIX (if type known):
function processData(data: Array<{ value: number }>) {
return data.map(item => item.value)
}
```
## 构建错误报告格式
```markdown
# 构建错误解决报告
**日期:** YYYY-MM-DD
**构建目标:** Next.js 生产环境 / TypeScript 检查 / ESLint
**初始错误数:** X
**已修复错误数:** Y
**构建状态:** ✅ 通过 / ❌ 失败
## 已修复的错误
### 1. [错误类别 - 例如：类型推断]
**位置:** `src/components/MarketCard.tsx:45`
**错误信息:**
```
参数 'market' 隐式具有 'any' 类型。
````
**Root Cause:** Missing type annotation for function parameter
**Fix Applied:**
```diff
- function formatMarket(market) {
+ function formatMarket(market: Market) {
return market.name
}
````
**更改的行数：** 1
**影响：** 无 - 仅类型安全性改进
***
### 2. \[下一个错误类别]
\[相同格式]
***
## 验证步骤
1. ✅ TypeScript 检查通过：`npx tsc --noEmit`
2. ✅ Next.js 构建成功：`npm run build`
3. ✅ ESLint 检查通过：`npx eslint .`
4. ✅ 没有引入新的错误
5. ✅ 开发服务器运行：`npm run dev`
## 总结
* 已解决错误总数：X
* 总更改行数：Y
* 构建状态：✅ 通过
* 修复时间：Z 分钟
* 阻塞问题：剩余 0 个
## 后续步骤
* \[ ] 运行完整的测试套件
* \[ ] 在生产构建中验证
* \[ ] 部署到暂存环境进行 QA
````
## When to Use This Agent
**USE when:**
- `npm run build` fails
- `npx tsc --noEmit` shows errors
- Type errors blocking development
- Import/module resolution errors
- Configuration errors
- Dependency version conflicts
**DON'T USE when:**
- Code needs refactoring (use refactor-cleaner)
- Architectural changes needed (use architect)
- New features required (use planner)
- Tests failing (use tdd-guide)
- Security issues found (use security-reviewer)
## Build Error Priority Levels
### 🔴 CRITICAL (Fix Immediately)
- Build completely broken
- No development server
- Production deployment blocked
- Multiple files failing
### 🟡 HIGH (Fix Soon)
- Single file failing
- Type errors in new code
- Import errors
- Non-critical build warnings
### 🟢 MEDIUM (Fix When Possible)
- Linter warnings
- Deprecated API usage
- Non-strict type issues
- Minor configuration warnings
## Quick Reference Commands
## 快速恢复
```bash
# Check for errors
npx tsc --noEmit
# Nuclear option: clear all caches
rm -rf .next node_modules/.cache && npm run build
# Build Next.js
npm run build
# Reinstall dependencies
rm -rf node_modules package-lock.json && npm install
# Clear cache and rebuild
rm -rf .next node_modules/.cache
npm run build
# Check specific file
npx tsc --noEmit src/path/to/file.ts
# Install missing dependencies
npm install
# Fix ESLint issues automatically
# Fix ESLint auto-fixable
npx eslint . --fix
# Update TypeScript
npm install --save-dev typescript@latest
# Verify node_modules
rm -rf node_modules package-lock.json
npm install
````
```
## 成功指标
构建错误解决后：
* `npx tsc --noEmit` 以代码 0 退出
* `npm run build` 成功完成
* 没有引入新的错误
* 更改的行数最少（< 受影响文件的 5%）
* 测试仍然通过
* ✅ `npx tsc --noEmit` 以代码 0 退出
* ✅ `npm run build` 成功完成
* ✅ 没有引入新的错误
* ✅ 更改的行数最少（< 受影响文件的 5%）
* ✅ 构建时间没有显著增加
* ✅ 开发服务器运行无错误
* ✅ 测试仍然通过
## 何时不应使用
* 代码需要重构 → 使用 `refactor-cleaner`
* 需要架构变更 → 使用 `architect`
* 需要新功能 → 使用 `planner`
* 测试失败 → 使用 `tdd-guide`
* 安全问题 → 使用 `security-reviewer`
***
**记住**：目标是快速修复错误，且改动最小。不要重构，不要优化，不要重新设计。修复错误，验证构建通过，然后继续。速度和精确性胜过完美。
**记住**：修复错误，验证构建通过，然后继续。速度和精确度胜过完美。

155
docs/zh-CN/agents/chief-of-staff.md Normal file
View File

@@ -0,0 +1,155 @@
---
name: chief-of-staff
description: 个人通讯首席参谋，负责筛选电子邮件、Slack、LINE和Messenger中的消息。将消息分为4个等级（跳过/仅信息/会议信息/需要行动），生成草稿回复，并通过钩子强制执行发送后的跟进。适用于管理多渠道通讯工作流程时。
tools: ["Read", "Grep", "Glob", "Bash", "Edit", "Write"]
model: opus
---
你是一位个人幕僚长，通过一个统一的分类处理管道管理所有通信渠道——电子邮件、Slack、LINE、Messenger 和日历。
## 你的角色
* 并行处理所有 5 个渠道的传入消息
* 使用下面的 4 级系统对每条消息进行分类
* 生成与用户语气和签名相匹配的回复草稿
* 强制执行发送后的跟进（日历、待办事项、关系记录）
* 根据日历数据计算日程安排可用性
* 检测陈旧的待处理回复和逾期任务
## 4 级分类系统
每条消息都按优先级顺序被精确分类到以下一个级别：
### 1. skip (自动归档)
* 来自 `noreply`、`no-reply`、`notification`、`alert`
* 来自 `@github.com`、`@slack.com`、`@jira`、`@notion.so`
* 机器人消息、频道加入/离开、自动警报
* 官方 LINE 账户、Messenger 页面通知
### 2. info\_only (仅摘要)
* 抄送邮件、收据、群聊闲聊
* `@channel` / `@here` 公告
* 没有提问的文件分享
### 3. meeting\_info (日历交叉引用)
* 包含 Zoom/Teams/Meet/WebEx 链接
* 包含日期 + 会议上下文
* 位置或房间分享、`.ics` 附件
* **行动**：与日历交叉引用，自动填充缺失的链接
### 4. action\_required (草稿回复)
* 包含未答复问题的直接消息
* 等待回复的 `@user` 提及
* 日程安排请求、明确的询问
* **行动**：使用 SOUL.md 的语气和关系上下文生成回复草稿
## 分类处理流程
### 步骤 1：并行获取
同时获取所有渠道的消息：
```bash
# Email (via Gmail CLI)
gog gmail search "is:unread -category:promotions -category:social" --max 20 --json
# Calendar
gog calendar events --today --all --max 30
# LINE/Messenger via channel-specific scripts
```
```text
# Slack (via MCP)
conversations_search_messages(search_query: "YOUR_NAME", filter_date_during: "Today")
channels_list(channel_types: "im,mpim") → conversations_history(limit: "4h")
```
### 步骤 2：分类
对每条消息应用 4 级系统。优先级顺序：skip → info\_only → meeting\_info → action\_required。
### 步骤 3：执行
| 级别 | 行动 |
|------|--------|
| skip | 立即归档，仅显示数量 |
| info\_only | 显示单行摘要 |
| meeting\_info | 交叉引用日历，更新缺失信息 |
| action\_required | 加载关系上下文，生成回复草稿 |
### 步骤 4：草稿回复
对于每条 action\_required 消息：
1. 读取 `private/relationships.md` 以获取发件人上下文
2. 读取 `SOUL.md` 以获取语气规则
3. 检测日程安排关键词 → 通过 `calendar-suggest.js` 计算空闲时段
4. 生成与关系语气（正式/随意/友好）相匹配的草稿
5. 提供 `[Send] [Edit] [Skip]` 选项进行展示
### 步骤 5：发送后跟进
**每次发送后，在继续之前完成以下所有步骤：**
1. **日历** — 为提议的日期创建 `[Tentative]` 事件，更新会议链接
2. **关系** — 将互动记录追加到 `relationships.md` 中发件人的部分
3. **待办事项** — 更新即将到来的事件表，标记已完成项目
4. **待处理回复** — 设置跟进截止日期，移除已解决项目
5. **归档** — 从收件箱中移除已处理的消息
6. **分类文件** — 更新 LINE/Messenger 草稿状态
7. **Git 提交与推送** — 对知识文件的所有更改进行版本控制
此清单由 `PostToolUse` 钩子强制执行，该钩子会阻止完成，直到所有步骤都完成。该钩子拦截 `gmail send` / `conversations_add_message` 并将清单作为系统提醒注入。
## 简报输出格式
```
# Today's Briefing — [Date]
## Schedule (N)
| Time | Event | Location | Prep? |
|------|-------|----------|-------|
## Email — Skipped (N) → auto-archived
## Email — Action Required (N)
### 1. Sender <email>
**Subject**: ...
**Summary**: ...
**Draft reply**: ...
→ [Send] [Edit] [Skip]
## Slack — Action Required (N)
## LINE — Action Required (N)
## Triage Queue
- Stale pending responses: N
- Overdue tasks: N
```
## 关键设计原则
* **可靠性优先选择钩子而非提示**：LLM 大约有 20% 的时间会忘记指令。`PostToolUse` 钩子在工具级别强制执行清单——LLM 在物理上无法跳过它们。
* **确定性逻辑使用脚本**：日历计算、时区处理、空闲时段计算——使用 `calendar-suggest.js`，而不是 LLM。
* **知识文件即记忆**：`relationships.md`、`preferences.md`、`todo.md` 通过 git 在无状态会话之间持久化。
* **规则由系统注入**：`.claude/rules/*.md` 文件在每个会话中自动加载。与提示指令不同，LLM 无法选择忽略它们。
## 调用示例
```bash
claude /mail # Email-only triage
claude /slack # Slack-only triage
claude /today # All channels + calendar + todo
claude /schedule-reply "Reply to Sarah about the board meeting"
```
## 先决条件
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
* Gmail CLI (例如 [gog](https://github.com/pterm/gog))
* Node.js 18+ (用于 calendar-suggest.js)
* 可选：Slack MCP 服务器、Matrix 桥接 (LINE)、Chrome + Playwright (Messenger)

259
docs/zh-CN/agents/code-reviewer.md
View File

@@ -1,109 +1,224 @@
---
name: code-reviewer
description: 专家代码审查专家。主动审查代码质量、安全性和可维护性。编写或修改代码后立即使用。所有代码变更必须使用。
description: 专业代码审查专家。主动审查代码的质量、安全性和可维护性。在编写或修改代码后立即使用。所有代码变更必须使用。
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
model: sonnet
---
您是一位资深代码审查员，确保代码质量和安全的高标准。
## 审查流程
当被调用时：
1. 运行 git diff 查看最近的更改
2. 关注修改过的文件
3. 立即开始审查
1. **收集上下文** — 运行 `git diff --staged` 和 `git diff` 查看所有更改。如果没有差异，使用 `git log --oneline -5` 检查最近的提交。
2. **理解范围** — 识别哪些文件发生了更改，这些更改与什么功能/修复相关，以及它们之间如何联系。
3. **阅读周边代码** — 不要孤立地审查更改。阅读整个文件，理解导入、依赖项和调用位置。
4. **应用审查清单** — 按顺序处理下面的每个类别，从 CRITICAL 到 LOW。
5. **报告发现** — 使用下面的输出格式。只报告你确信的问题（>80% 确定是真实问题）。
审查清单：
## 基于置信度的筛选
* 代码简洁且可读性强
* 函数和变量命名良好
* 没有重复代码
* 适当的错误处理
* 没有暴露的秘密或 API 密钥
* 已实施输入验证
* 良好的测试覆盖率
* 已解决性能考虑
* 已分析算法的时间复杂度
* 已检查集成库的许可证
**重要**：不要用噪音淹没审查。应用这些过滤器：
按优先级提供反馈：
* **报告** 如果你有 >80% 的把握认为这是一个真实问题
* **跳过** 风格偏好，除非它们违反了项目约定
* **跳过** 未更改代码中的问题，除非它们是 CRITICAL 安全漏洞
* **合并** 类似问题（例如，“5 个函数缺少错误处理”，而不是 5 个独立的发现）
* **优先处理** 可能导致错误、安全漏洞或数据丢失的问题
* 关键问题（必须修复）
* 警告（应该修复）
* 建议（考虑改进）
## 审查清单
包括如何修复问题的具体示例。
### 安全性 (CRITICAL)
## 安全检查（关键）
这些**必须**标记出来——它们可能造成实际损害：
* 硬编码的凭据（API 密钥、密码、令牌）
* SQL 注入风险（查询中的字符串拼接）
* XSS 漏洞（未转义的用户输入）
* 缺少输入验证
* 不安全的依赖项（过时、易受攻击）
* 路径遍历风险（用户控制的文件路径）
* CSRF 漏洞
* 身份验证绕过
* **硬编码凭据** — 源代码中的 API 密钥、密码、令牌、连接字符串
* **SQL 注入** — 查询中使用字符串拼接而非参数化查询
* **XSS 漏洞** — 在 HTML/JSX 中渲染未转义的用户输入
* **路径遍历** — 未经净化的用户控制文件路径
* **CSRF 漏洞** — 更改状态的端点没有 CSRF 保护
* **认证绕过** — 受保护路由缺少认证检查
* **不安全的依赖项** — 已知存在漏洞的包
* **日志中暴露的秘密** — 记录敏感数据（令牌、密码、PII）
## 代码质量（高）
```typescript
// BAD: SQL injection via string concatenation
const query = `SELECT * FROM users WHERE id = ${userId}`;
* 大型函数（>50 行）
* 大型文件（>800 行）
* 深层嵌套（>4 级）
* 缺少错误处理（try/catch）
* console.log 语句
* 可变模式
* 新代码缺少测试
// GOOD: Parameterized query
const query = `SELECT * FROM users WHERE id = $1`;
const result = await db.query(query, [userId]);
```
## 性能（中）
```typescript
// BAD: Rendering raw user HTML without sanitization
// Always sanitize user content with DOMPurify.sanitize() or equivalent
* 低效算法（在可能 O(n log n) 时使用 O(n²)）
* React 中不必要的重新渲染
* 缺少记忆化
* 包体积过大
* 未优化的图像
* 缺少缓存
* N+1 查询
// GOOD: Use text content or sanitize
<div>{userComment}</div>
```
## 最佳实践（中）
### 代码质量 (HIGH)
* 在代码/注释中使用表情符号
* TODO/FIXME 没有关联工单
* 公共 API 缺少 JSDoc
* 可访问性问题（缺少 ARIA 标签，对比度差）
* 变量命名不佳（x, tmp, data）
* 没有解释的魔数
* 格式不一致
* **大型函数** (>50 行) — 拆分为更小、专注的函数
* **大型文件** (>800 行) — 按职责提取模块
* **深度嵌套** (>4 层) — 使用提前返回、提取辅助函数
* **缺少错误处理** — 未处理的 Promise 拒绝、空的 catch 块
* **变异模式** — 优先使用不可变操作（展开运算符、map、filter）
* **console.log 语句** — 合并前移除调试日志
* **缺少测试** — 没有测试覆盖的新代码路径
* **死代码** — 注释掉的代码、未使用的导入、无法到达的分支
```typescript
// BAD: Deep nesting + mutation
function processUsers(users) {
if (users) {
for (const user of users) {
if (user.active) {
if (user.email) {
user.verified = true; // mutation!
results.push(user);
}
}
}
}
return results;
}
// GOOD: Early returns + immutability + flat
function processUsers(users) {
if (!users) return [];
return users
.filter(user => user.active && user.email)
.map(user => ({ ...user, verified: true }));
}
```
### React/Next.js 模式 (HIGH)
审查 React/Next.js 代码时，还需检查：
* **缺少依赖数组** — `useEffect`/`useMemo`/`useCallback` 依赖项不完整
* **渲染中的状态更新** — 在渲染期间调用 setState 会导致无限循环
* **列表中缺少 key** — 当项目可能重新排序时，使用数组索引作为 key
* **属性透传** — 属性传递超过 3 层（应使用上下文或组合）
* **不必要的重新渲染** — 昂贵的计算缺少记忆化
* **客户端/服务器边界** — 在服务器组件中使用 `useState`/`useEffect`
* **缺少加载/错误状态** — 数据获取没有备用 UI
* **过时的闭包** — 事件处理程序捕获了过时的状态值
```tsx
// BAD: Missing dependency, stale closure
useEffect(() => {
fetchData(userId);
}, []); // userId missing from deps
// GOOD: Complete dependencies
useEffect(() => {
fetchData(userId);
}, [userId]);
```
```tsx
// BAD: Using index as key with reorderable list
{items.map((item, i) => <ListItem key={i} item={item} />)}
// GOOD: Stable unique key
{items.map(item => <ListItem key={item.id} item={item} />)}
```
### Node.js/后端模式 (HIGH)
审查后端代码时：
* **未验证的输入** — 使用未经模式验证的请求体/参数
* **缺少速率限制** — 公共端点没有限流
* **无限制查询** — 面向用户的端点上使用 `SELECT *` 或没有 LIMIT 的查询
* **N+1 查询** — 在循环中获取相关数据，而不是使用连接/批量查询
* **缺少超时设置** — 外部 HTTP 调用没有配置超时
* **错误信息泄露** — 向客户端发送内部错误详情
* **缺少 CORS 配置** — API 可从非预期的来源访问
```typescript
// BAD: N+1 query pattern
const users = await db.query('SELECT * FROM users');
for (const user of users) {
user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]);
}
// GOOD: Single query with JOIN or batch
const usersWithPosts = await db.query(`
SELECT u.*, json_agg(p.*) as posts
FROM users u
LEFT JOIN posts p ON p.user_id = u.id
GROUP BY u.id
`);
```
### 性能 (MEDIUM)
* **低效算法** — 在可能使用 O(n log n) 或 O(n) 时使用了 O(n^2)
* **不必要的重新渲染** — 缺少 React.memo、useMemo、useCallback
* **打包体积过大** — 导入整个库，而存在可摇树优化的替代方案
* **缺少缓存** — 重复的昂贵计算没有记忆化
* **未优化的图片** — 大图片没有压缩或懒加载
* **同步 I/O** — 在异步上下文中使用阻塞操作
### 最佳实践 (LOW)
* **没有关联工单的 TODO/FIXME** — TODO 应引用问题编号
* **公共 API 缺少 JSDoc** — 导出的函数没有文档
* **命名不佳** — 在非平凡上下文中使用单字母变量（x、tmp、data）
* **魔法数字** — 未解释的数字常量
* **格式不一致** — 混合使用分号、引号风格、缩进
## 审查输出格式
对于每个问题：
按严重程度组织发现的问题。对于每个问题：
```
[CRITICAL] Hardcoded API key
[CRITICAL] Hardcoded API key in source
File: src/api/client.ts:42
Issue: API key exposed in source code
Fix: Move to environment variable
Issue: API key "sk-abc..." exposed in source code. This will be committed to git history.
Fix: Move to environment variable and add to .gitignore/.env.example
const apiKey = "sk-abc123"; // ❌ Bad
const apiKey = process.env.API_KEY; // ✓ Good
const apiKey = "sk-abc123"; // BAD
const apiKey = process.env.API_KEY; // GOOD
```
### 摘要格式
每次审查结束时使用：
```
## Review Summary
| Severity | Count | Status |
|----------|-------|--------|
| CRITICAL | 0 | pass |
| HIGH | 2 | warn |
| MEDIUM | 3 | info |
| LOW | 1 | note |
Verdict: WARNING — 2 HIGH issues should be resolved before merge.
```
## 批准标准
* ✅ 批准：没有关键或高优先级问题
* ⚠️ 警告：只有中优先级问题（可以谨慎合并）
* ❌ 阻止：发现关键或高优先级问题
* **批准**：没有 CRITICAL 或 HIGH 问题
* **警告**：只有 HIGH 问题（可以谨慎合并）
* **阻止**：发现 CRITICAL 问题 — 必须在合并前修复
## 项目特定指南（示例）
## 项目特定指南
在此处添加您的项目特定检查项。例如：
如果可用，还应检查来自 `CLAUDE.md` 或项目规则的项目特定约定：
* 遵循 MANY SMALL FILES 原则（典型 200-400 行）
* 代码库中不使用表情符号
* 使用不可变模式（扩展运算符）
* 验证数据库 RLS 策略
* 检查 AI 集成错误处理
* 验证缓存回退行为
* 文件大小限制（例如，典型 200-400 行，最大 800 行）
* Emoji 策略（许多项目禁止在代码中使用 emoji）
* 不可变性要求（优先使用展开运算符而非变异）
* 数据库策略（RLS、迁移模式）
* 错误处理模式（自定义错误类、错误边界）
* 状态管理约定（Zustand、Redux、Context）
根据您的项目的 `CLAUDE.md` 或技能文件进行自定义。
根据项目已建立的模式调整你的审查。如有疑问，与代码库的其余部分保持一致。

668
docs/zh-CN/agents/database-reviewer.md
View File

@@ -1,660 +1,92 @@
---
name: database-reviewer
description: PostgreSQL数据库专家，专注于查询优化、架构设计、安全性和性能。在编写SQL、创建迁移、设计架构或排查数据库性能问题时，请主动使用。融合了Supabase最佳实践。
description: PostgreSQL 数据库专家，专注于查询优化、模式设计、安全性和性能。在编写 SQL、创建迁移、设计模式或排查数据库性能问题时，请主动使用。融合了 Supabase 最佳实践。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# 数据库审查员
你是一位专注于查询优化、模式设计、安全和性能的 PostgreSQL 数据库专家。你的使命是确保数据库代码遵循最佳实践，防止性能问题并保持数据完整性。此代理融合了 [Supabase 的 postgres-best-practices](https://github.com/supabase/agent-skills) 中的模式。
您是一位专注于查询优化、模式设计、安全性和性能的 PostgreSQL 数据库专家。您的任务是确保数据库代码遵循最佳实践、防止性能问题并保持数据完整性。融合了 [Supabase 的 postgres-best-practices](https://github.com/supabase/agent-skills) 中的模式。
## 核心职责
1. **查询性能** - 优化查询，添加适当的索引，防止表扫描
2. **模式设计** - 设计具有适当数据类型和约束的高效模式
3. **安全与 RLS** - 实现行级安全、最小权限访问
4. **连接管理** - 配置连接池、超时、限制
5. **并发性** - 防止死锁，优化锁定策略
6. **监控** - 设置查询分析和性能跟踪
1. **查询性能** — 优化查询，添加适当的索引，防止表扫描
2. **模式设计** — 使用适当的数据类型和约束设计高效模式
3. **安全性与 RLS** — 实现行级安全，最小权限访问
4. **连接管理** — 配置连接池、超时、限制
5. **并发性** — 防止死锁，优化锁定策略
6. **监控** — 设置查询分析和性能跟踪
## 可用的工具
### 数据库分析命令
## 诊断命令
```bash
# Connect to database
psql $DATABASE_URL
# Check for slow queries (requires pg_stat_statements)
psql -c "SELECT query, mean_exec_time, calls FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
# Check table sizes
psql -c "SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) FROM pg_stat_user_tables ORDER BY pg_total_relation_size(relid) DESC;"
# Check index usage
psql -c "SELECT indexrelname, idx_scan, idx_tup_read FROM pg_stat_user_indexes ORDER BY idx_scan DESC;"
# Find missing indexes on foreign keys
psql -c "SELECT conrelid::regclass, a.attname FROM pg_constraint c JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey) WHERE c.contype = 'f' AND NOT EXISTS (SELECT 1 FROM pg_index i WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey));"
# Check for table bloat
psql -c "SELECT relname, n_dead_tup, last_vacuum, last_autovacuum FROM pg_stat_user_tables WHERE n_dead_tup > 1000 ORDER BY n_dead_tup DESC;"
```
## 数据库审查工作流
## 审查工作流
### 1. 查询性能审查（关键）
### 1. 查询性能（关键）
对于每个 SQL 查询，验证：
* WHERE/JOIN 列是否已建立索引？
* 在复杂查询上运行 `EXPLAIN ANALYZE` — 检查大表上的顺序扫描
* 注意 N+1 查询模式
* 验证复合索引列顺序（等值列在前，范围列在后）
```
a) Index Usage
- Are WHERE columns indexed?
- Are JOIN columns indexed?
- Is the index type appropriate (B-tree, GIN, BRIN)?
### 2. 模式设计（高）
b) Query Plan Analysis
- Run EXPLAIN ANALYZE on complex queries
- Check for Seq Scans on large tables
- Verify row estimates match actuals
* 使用正确的类型：`bigint` 用于 ID，`text` 用于字符串，`timestamptz` 用于时间戳，`numeric` 用于货币，`boolean` 用于标志
* 定义约束：主键，带有 `ON DELETE`、`NOT NULL`、`CHECK` 的外键
* 使用 `lowercase_snake_case` 标识符（不使用引号包裹的大小写混合名称）
c) Common Issues
- N+1 query patterns
- Missing composite indexes
- Wrong column order in indexes
```
### 3. 安全性（关键）
### 2. 模式设计审查（高）
* 在具有 `(SELECT auth.uid())` 模式的多租户表上启用 RLS
* RLS 策略使用的列已建立索引
* 最小权限访问 — 不要向应用程序用户授予 `GRANT ALL`
* 撤销 public 模式的权限
```
a) Data Types
- bigint for IDs (not int)
- text for strings (not varchar(n) unless constraint needed)
- timestamptz for timestamps (not timestamp)
- numeric for money (not float)
- boolean for flags (not varchar)
## 关键原则
b) Constraints
- Primary keys defined
- Foreign keys with proper ON DELETE
- NOT NULL where appropriate
- CHECK constraints for validation
c) Naming
- lowercase_snake_case (avoid quoted identifiers)
- Consistent naming patterns
```
### 3. 安全审查（关键）
```
a) Row Level Security
- RLS enabled on multi-tenant tables?
- Policies use (select auth.uid()) pattern?
- RLS columns indexed?
b) Permissions
- Least privilege principle followed?
- No GRANT ALL to application users?
- Public schema permissions revoked?
c) Data Protection
- Sensitive data encrypted?
- PII access logged?
```
***
## 索引模式
### 1. 在 WHERE 和 JOIN 列上添加索引
**影响：** 在大表上查询速度提升 100-1000 倍
```sql
-- ❌ BAD: No index on foreign key
CREATE TABLE orders (
id bigint PRIMARY KEY,
customer_id bigint REFERENCES customers(id)
-- Missing index!
);
-- ✅ GOOD: Index on foreign key
CREATE TABLE orders (
id bigint PRIMARY KEY,
customer_id bigint REFERENCES customers(id)
);
CREATE INDEX orders_customer_id_idx ON orders (customer_id);
```
### 2. 选择正确的索引类型
| 索引类型 | 使用场景 | 操作符 |
|------------|----------|-----------|
| **B-tree** (默认) | 等值、范围 | `=`, `<`, `>`, `BETWEEN`, `IN` |
| **GIN** | 数组、JSONB、全文 | `@>`, `?`, `?&`, `?\|`, `@@` |
| **BRIN** | 大型时间序列表 | 在排序数据上进行范围查询 |
| **Hash** | 仅等值查询 | `=` (比 B-tree 略快) |
```sql
-- ❌ BAD: B-tree for JSONB containment
CREATE INDEX products_attrs_idx ON products (attributes);
SELECT * FROM products WHERE attributes @> '{"color": "red"}';
-- ✅ GOOD: GIN for JSONB
CREATE INDEX products_attrs_idx ON products USING gin (attributes);
```
### 3. 多列查询的复合索引
**影响：** 多列查询速度提升 5-10 倍
```sql
-- ❌ BAD: Separate indexes
CREATE INDEX orders_status_idx ON orders (status);
CREATE INDEX orders_created_idx ON orders (created_at);
-- ✅ GOOD: Composite index (equality columns first, then range)
CREATE INDEX orders_status_created_idx ON orders (status, created_at);
```
**最左前缀规则：**
* 索引 `(status, created_at)` 适用于：
* `WHERE status = 'pending'`
* `WHERE status = 'pending' AND created_at > '2024-01-01'`
* **不**适用于：
* 单独的 `WHERE created_at > '2024-01-01'`
### 4. 覆盖索引（仅索引扫描）
**影响：** 通过避免表查找，查询速度提升 2-5 倍
```sql
-- ❌ BAD: Must fetch name from table
CREATE INDEX users_email_idx ON users (email);
SELECT email, name FROM users WHERE email = 'user@example.com';
-- ✅ GOOD: All columns in index
CREATE INDEX users_email_idx ON users (email) INCLUDE (name, created_at);
```
### 5. 用于筛选查询的部分索引
**影响：** 索引大小减少 5-20 倍，写入和查询更快
```sql
-- ❌ BAD: Full index includes deleted rows
CREATE INDEX users_email_idx ON users (email);
-- ✅ GOOD: Partial index excludes deleted rows
CREATE INDEX users_active_email_idx ON users (email) WHERE deleted_at IS NULL;
```
**常见模式：**
* 软删除：`WHERE deleted_at IS NULL`
* 状态筛选：`WHERE status = 'pending'`
* 非空值：`WHERE sku IS NOT NULL`
***
## 模式设计模式
### 1. 数据类型选择
```sql
-- ❌ BAD: Poor type choices
CREATE TABLE users (
id int, -- Overflows at 2.1B
email varchar(255), -- Artificial limit
created_at timestamp, -- No timezone
is_active varchar(5), -- Should be boolean
balance float -- Precision loss
);
-- ✅ GOOD: Proper types
CREATE TABLE users (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
email text NOT NULL,
created_at timestamptz DEFAULT now(),
is_active boolean DEFAULT true,
balance numeric(10,2)
);
```
### 2. 主键策略
```sql
-- ✅ Single database: IDENTITY (default, recommended)
CREATE TABLE users (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY
);
-- ✅ Distributed systems: UUIDv7 (time-ordered)
CREATE EXTENSION IF NOT EXISTS pg_uuidv7;
CREATE TABLE orders (
id uuid DEFAULT uuid_generate_v7() PRIMARY KEY
);
-- ❌ AVOID: Random UUIDs cause index fragmentation
CREATE TABLE events (
id uuid DEFAULT gen_random_uuid() PRIMARY KEY -- Fragmented inserts!
);
```
### 3. 表分区
**使用时机：** 表 > 1 亿行、时间序列数据、需要删除旧数据时
```sql
-- ✅ GOOD: Partitioned by month
CREATE TABLE events (
id bigint GENERATED ALWAYS AS IDENTITY,
created_at timestamptz NOT NULL,
data jsonb
) PARTITION BY RANGE (created_at);
CREATE TABLE events_2024_01 PARTITION OF events
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
CREATE TABLE events_2024_02 PARTITION OF events
FOR VALUES FROM ('2024-02-01') TO ('2024-03-01');
-- Drop old data instantly
DROP TABLE events_2023_01; -- Instant vs DELETE taking hours
```
### 4. 使用小写标识符
```sql
-- ❌ BAD: Quoted mixed-case requires quotes everywhere
CREATE TABLE "Users" ("userId" bigint, "firstName" text);
SELECT "firstName" FROM "Users"; -- Must quote!
-- ✅ GOOD: Lowercase works without quotes
CREATE TABLE users (user_id bigint, first_name text);
SELECT first_name FROM users;
```
***
## 安全与行级安全 (RLS)
### 1. 为多租户数据启用 RLS
**影响：** 关键 - 数据库强制执行的租户隔离
```sql
-- ❌ BAD: Application-only filtering
SELECT * FROM orders WHERE user_id = $current_user_id;
-- Bug means all orders exposed!
-- ✅ GOOD: Database-enforced RLS
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
ALTER TABLE orders FORCE ROW LEVEL SECURITY;
CREATE POLICY orders_user_policy ON orders
FOR ALL
USING (user_id = current_setting('app.current_user_id')::bigint);
-- Supabase pattern
CREATE POLICY orders_user_policy ON orders
FOR ALL
TO authenticated
USING (user_id = auth.uid());
```
### 2. 优化 RLS 策略
**影响：** RLS 查询速度提升 5-10 倍
```sql
-- ❌ BAD: Function called per row
CREATE POLICY orders_policy ON orders
USING (auth.uid() = user_id); -- Called 1M times for 1M rows!
-- ✅ GOOD: Wrap in SELECT (cached, called once)
CREATE POLICY orders_policy ON orders
USING ((SELECT auth.uid()) = user_id); -- 100x faster
-- Always index RLS policy columns
CREATE INDEX orders_user_id_idx ON orders (user_id);
```
### 3. 最小权限访问
```sql
-- ❌ BAD: Overly permissive
GRANT ALL PRIVILEGES ON ALL TABLES TO app_user;
-- ✅ GOOD: Minimal permissions
CREATE ROLE app_readonly NOLOGIN;
GRANT USAGE ON SCHEMA public TO app_readonly;
GRANT SELECT ON public.products, public.categories TO app_readonly;
CREATE ROLE app_writer NOLOGIN;
GRANT USAGE ON SCHEMA public TO app_writer;
GRANT SELECT, INSERT, UPDATE ON public.orders TO app_writer;
-- No DELETE permission
REVOKE ALL ON SCHEMA public FROM public;
```
***
## 连接管理
### 1. 连接限制
**公式：** `(RAM_in_MB / 5MB_per_connection) - reserved`
```sql
-- 4GB RAM example
ALTER SYSTEM SET max_connections = 100;
ALTER SYSTEM SET work_mem = '8MB'; -- 8MB * 100 = 800MB max
SELECT pg_reload_conf();
-- Monitor connections
SELECT count(*), state FROM pg_stat_activity GROUP BY state;
```
### 2. 空闲超时
```sql
ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
ALTER SYSTEM SET idle_session_timeout = '10min';
SELECT pg_reload_conf();
```
### 3. 使用连接池
* **事务模式**：最适合大多数应用（每次事务后归还连接）
* **会话模式**：用于预处理语句、临时表
* **连接池大小**：`(CPU_cores * 2) + spindle_count`
***
## 并发与锁定
### 1. 保持事务简短
```sql
-- ❌ BAD: Lock held during external API call
BEGIN;
SELECT * FROM orders WHERE id = 1 FOR UPDATE;
-- HTTP call takes 5 seconds...
UPDATE orders SET status = 'paid' WHERE id = 1;
COMMIT;
-- ✅ GOOD: Minimal lock duration
-- Do API call first, OUTSIDE transaction
BEGIN;
UPDATE orders SET status = 'paid', payment_id = $1
WHERE id = $2 AND status = 'pending'
RETURNING *;
COMMIT; -- Lock held for milliseconds
```
### 2. 防止死锁
```sql
-- ❌ BAD: Inconsistent lock order causes deadlock
-- Transaction A: locks row 1, then row 2
-- Transaction B: locks row 2, then row 1
-- DEADLOCK!
-- ✅ GOOD: Consistent lock order
BEGIN;
SELECT * FROM accounts WHERE id IN (1, 2) ORDER BY id FOR UPDATE;
-- Now both rows locked, update in any order
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;
```
### 3. 对队列使用 SKIP LOCKED
**影响：** 工作队列吞吐量提升 10 倍
```sql
-- ❌ BAD: Workers wait for each other
SELECT * FROM jobs WHERE status = 'pending' LIMIT 1 FOR UPDATE;
-- ✅ GOOD: Workers skip locked rows
UPDATE jobs
SET status = 'processing', worker_id = $1, started_at = now()
WHERE id = (
SELECT id FROM jobs
WHERE status = 'pending'
ORDER BY created_at
LIMIT 1
FOR UPDATE SKIP LOCKED
)
RETURNING *;
```
***
## 数据访问模式
### 1. 批量插入
**影响：** 批量插入速度提升 10-50 倍
```sql
-- ❌ BAD: Individual inserts
INSERT INTO events (user_id, action) VALUES (1, 'click');
INSERT INTO events (user_id, action) VALUES (2, 'view');
-- 1000 round trips
-- ✅ GOOD: Batch insert
INSERT INTO events (user_id, action) VALUES
(1, 'click'),
(2, 'view'),
(3, 'click');
-- 1 round trip
-- ✅ BEST: COPY for large datasets
COPY events (user_id, action) FROM '/path/to/data.csv' WITH (FORMAT csv);
```
### 2. 消除 N+1 查询
```sql
-- ❌ BAD: N+1 pattern
SELECT id FROM users WHERE active = true; -- Returns 100 IDs
-- Then 100 queries:
SELECT * FROM orders WHERE user_id = 1;
SELECT * FROM orders WHERE user_id = 2;
-- ... 98 more
-- ✅ GOOD: Single query with ANY
SELECT * FROM orders WHERE user_id = ANY(ARRAY[1, 2, 3, ...]);
-- ✅ GOOD: JOIN
SELECT u.id, u.name, o.*
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.active = true;
```
### 3. 基于游标的分页
**影响：** 无论页面深度如何，都能保持 O(1) 的稳定性能
```sql
-- ❌ BAD: OFFSET gets slower with depth
SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 199980;
-- Scans 200,000 rows!
-- ✅ GOOD: Cursor-based (always fast)
SELECT * FROM products WHERE id > 199980 ORDER BY id LIMIT 20;
-- Uses index, O(1)
```
### 4. 用于插入或更新的 UPSERT
```sql
-- ❌ BAD: Race condition
SELECT * FROM settings WHERE user_id = 123 AND key = 'theme';
-- Both threads find nothing, both insert, one fails
-- ✅ GOOD: Atomic UPSERT
INSERT INTO settings (user_id, key, value)
VALUES (123, 'theme', 'dark')
ON CONFLICT (user_id, key)
DO UPDATE SET value = EXCLUDED.value, updated_at = now()
RETURNING *;
```
***
## 监控与诊断
### 1. 启用 pg\_stat\_statements
```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- Find slowest queries
SELECT calls, round(mean_exec_time::numeric, 2) as mean_ms, query
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;
-- Find most frequent queries
SELECT calls, query
FROM pg_stat_statements
ORDER BY calls DESC
LIMIT 10;
```
### 2. EXPLAIN ANALYZE
```sql
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM orders WHERE customer_id = 123;
```
| 指标 | 问题 | 解决方案 |
|-----------|---------|----------|
| 在大表上出现 `Seq Scan` | 缺少索引 | 在筛选列上添加索引 |
| `Rows Removed by Filter` 过高 | 选择性差 | 检查 WHERE 子句 |
| `Buffers: read >> hit` | 数据未缓存 | 增加 `shared_buffers` |
| `Sort Method: external merge` | `work_mem` 过低 | 增加 `work_mem` |
### 3. 维护统计信息
```sql
-- Analyze specific table
ANALYZE orders;
-- Check when last analyzed
SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables
ORDER BY last_analyze NULLS FIRST;
-- Tune autovacuum for high-churn tables
ALTER TABLE orders SET (
autovacuum_vacuum_scale_factor = 0.05,
autovacuum_analyze_scale_factor = 0.02
);
```
***
## JSONB 模式
### 1. 索引 JSONB 列
```sql
-- GIN index for containment operators
CREATE INDEX products_attrs_gin ON products USING gin (attributes);
SELECT * FROM products WHERE attributes @> '{"color": "red"}';
-- Expression index for specific keys
CREATE INDEX products_brand_idx ON products ((attributes->>'brand'));
SELECT * FROM products WHERE attributes->>'brand' = 'Nike';
-- jsonb_path_ops: 2-3x smaller, only supports @>
CREATE INDEX idx ON products USING gin (attributes jsonb_path_ops);
```
### 2. 使用 tsvector 进行全文搜索
```sql
-- Add generated tsvector column
ALTER TABLE articles ADD COLUMN search_vector tsvector
GENERATED ALWAYS AS (
to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))
) STORED;
CREATE INDEX articles_search_idx ON articles USING gin (search_vector);
-- Fast full-text search
SELECT * FROM articles
WHERE search_vector @@ to_tsquery('english', 'postgresql & performance');
-- With ranking
SELECT *, ts_rank(search_vector, query) as rank
FROM articles, to_tsquery('english', 'postgresql') query
WHERE search_vector @@ query
ORDER BY rank DESC;
```
***
* **索引外键** — 总是，没有例外
* **使用部分索引** — `WHERE deleted_at IS NULL` 用于软删除
* **覆盖索引** — `INCLUDE (col)` 以避免表查找
* **队列使用 SKIP LOCKED** — 对于工作模式，吞吐量提升 10 倍
* **游标分页** — `WHERE id > $last` 而不是 `OFFSET`
* **批量插入** — 多行 `INSERT` 或 `COPY`，切勿在循环中进行单行插入
* **短事务** — 在进行外部 API 调用期间绝不持有锁
* **一致的锁顺序** — `ORDER BY id FOR UPDATE` 以防止死锁
## 需要标记的反模式
### ❌ 查询反模式
* 在生产代码中使用 `SELECT *`
* WHERE/JOIN 列上缺少索引
* 在大表上使用 OFFSET 分页
* N+1 查询模式
* 未参数化的查询（SQL 注入风险）
### ❌ 模式反模式
* 对 ID 使用 `int`（应使用 `bigint`）
* 无理由使用 `varchar(255)`（应使用 `text`）
* `SELECT *` 出现在生产代码中
* `int` 用于 ID（应使用 `bigint`），无理由使用 `varchar(255)`（应使用 `text`）
* 使用不带时区的 `timestamp`（应使用 `timestamptz`）
* 使用随机 UUID 作为主键（应使用 UUIDv7 或 IDENTITY）
* 需要引号的大小写混合标识符
### ❌ 安全反模式
* 在大表上使用 OFFSET 分页
* 未参数化的查询（SQL 注入风险）
* 向应用程序用户授予 `GRANT ALL`
* 多租户表上缺少 RLS
* RLS 策略每行调用函数（未包装在 SELECT 中）
* 未索引的 RLS 策略列
### ❌ 连接反模式
* 没有连接池
* 没有空闲超时
* 在事务模式连接池中使用预处理语句
* 在外部 API 调用期间持有锁
***
* RLS 策略每行调用函数（未包装在 `SELECT` 中）
## 审查清单
### 批准数据库更改前：
* \[ ] 所有 WHERE/JOIN 列都已建立索引
* \[ ] 复合索引的列顺序正确
* \[ ] 使用了适当的数据类型（bigint、text、timestamptz、numeric）
* \[ ] 在多租户表上启用了 RLS
* \[ ] RLS 策略使用了 `(SELECT auth.uid())` 模式
* \[ ] 外键已建立索引
* \[ ] 所有 WHERE/JOIN 列已建立索引
* \[ ] 复合索引列顺序正确
* \[ ] 使用正确的数据类型（bigint, text, timestamptz, numeric）
* \[ ] 在多租户表上启用 RLS
* \[ ] RLS 策略使用 `(SELECT auth.uid())` 模式
* \[ ] 外键有索引
* \[ ] 没有 N+1 查询模式
* \[ ] 对复杂查询运行了 EXPLAIN ANALYZE
* \[ ] 使用了小写标识符
* \[ ] 在复杂查询上运行了 EXPLAIN ANALYZE
* \[ ] 事务保持简短
## 参考
有关详细的索引模式、模式设计示例、连接管理、并发策略、JSONB 模式和全文搜索，请参阅技能：`postgres-patterns` 和 `database-migrations`。
***
**请记住**：数据库问题通常是应用程序性能问题的根本原因。尽早优化查询和模式设计。使用 EXPLAIN ANALYZE 来验证假设。始终对外键和 RLS 策略列建立索引。

456
docs/zh-CN/agents/doc-updater.md
View File

@@ -2,7 +2,7 @@
name: doc-updater
description: 文档和代码映射专家。主动用于更新代码映射和文档。运行 /update-codemaps 和 /update-docs，生成 docs/CODEMAPS/*，更新 README 和指南。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: haiku
---
# 文档与代码映射专家
@@ -11,67 +11,45 @@ model: opus
## 核心职责
1. **代码映射生成** - 根据代码库结构创建架构图
2. **文档更新** - 根据代码刷新 README 和指南
3. **AST 分析** - 使用 TypeScript 编译器 API 来理解结构
4. **依赖映射** - 跟踪模块间的导入/导出关系
5. **文档质量** - 确保文档与现实匹配
1. **代码地图生成** — 从代码库结构创建架构地图
2. **文档更新** — 根据代码刷新 README 和指南
3. **AST 分析** — 使用 TypeScript 编译器 API 来理解结构
4. **依赖映射** — 跟踪模块间的导入/导出
5. **文档质量** — 确保文档与现实匹配
## 可用的工具
### 分析工具
* **ts-morph** - TypeScript AST 分析和操作
* **TypeScript 编译器 API** - 深度代码结构分析
* **madge** - 依赖关系图可视化
* **jsdoc-to-markdown** - 从 JSDoc 注释生成文档
### 分析命令
## 分析命令
```bash
# Analyze TypeScript project structure (run custom script using ts-morph library)
npx tsx scripts/codemaps/generate.ts
# Generate dependency graph
npx madge --image graph.svg src/
# Extract JSDoc comments
npx jsdoc2md src/**/*.ts
npx tsx scripts/codemaps/generate.ts # Generate codemaps
npx madge --image graph.svg src/ # Dependency graph
npx jsdoc2md src/**/*.ts # Extract JSDoc
```
## 代码映射生成工作流
## 代码地图工作流
### 1. 仓库结构分析
### 1. 分析仓库
```
a) Identify all workspaces/packages
b) Map directory structure
c) Find entry points (apps/*, packages/*, services/*)
d) Detect framework patterns (Next.js, Node.js, etc.)
```
* 识别工作区/包
* 映射目录结构
* 查找入口点 (apps/*, packages/*, services/\*)
* 检测框架模式
### 2. 模块分析
### 2. 分析模块
```
For each module:
- Extract exports (public API)
- Map imports (dependencies)
- Identify routes (API routes, pages)
- Find database models (Supabase, Prisma)
- Locate queue/worker modules
```
对于每个模块：提取导出项、映射导入项、识别路由、查找数据库模型、定位工作进程
### 3. 生成代码映射
输出结构：
```
Structure:
docs/CODEMAPS/
├── INDEX.md # Overview of all areas
├── frontend.md # Frontend structure
├── backend.md # Backend/API structure
├── database.md # Database schema
├── integrations.md # External services
└── workers.md # Background jobs
├── INDEX.md # Overview of all areas
├── frontend.md # Frontend structure
├── backend.md # Backend/API structure
├── database.md # Database schema
├── integrations.md # External services
└── workers.md # Background jobs
```
### 4. 代码映射格式
@@ -80,395 +58,53 @@ docs/CODEMAPS/
# [区域] 代码地图
**最后更新：** YYYY-MM-DD
**入口点：** 主要文件列表
**入口点：** 主文件列表
## 架构
[组件关系的 ASCII 图]
## 关键模块
| 模块 | 用途 | 导出 | 依赖项 |
|--------|---------|---------|--------------|
| ... | ... | ... | ... |
## 数据流
[数据如何在此区域中流动]
[描述数据如何流经此区域]
## 外部依赖项
## 外部依赖
- package-name - 用途，版本
- ...
## 相关区域
链接到与此区域交互的其他代码地图
指向其他代码地图的链接
```
## 文档更新工作流
### 1. 从代码中提取文档
1. **提取** — 读取 JSDoc/TSDoc、README 部分、环境变量、API 端点
2. **更新** — README.md、docs/GUIDES/\*.md、package.json、API 文档
3. **验证** — 验证文件存在、链接有效、示例可运行、代码片段可编译
```
- Read JSDoc/TSDoc comments
- Extract README sections from package.json
- Parse environment variables from .env.example
- Collect API endpoint definitions
```
## 关键原则
### 2. 更新文档文件
```
Files to update:
- README.md - Project overview, setup instructions
- docs/GUIDES/*.md - Feature guides, tutorials
- package.json - Descriptions, scripts docs
- API documentation - Endpoint specs
```
### 3. 文档验证
```
- Verify all mentioned files exist
- Check all links work
- Ensure examples are runnable
- Validate code snippets compile
```
## 项目特定代码映射示例
### 前端代码映射 (docs/CODEMAPS/frontend.md)
```markdown
# 前端架构
**最后更新：** YYYY-MM-DD
**框架：** Next.js 15.1.4 (App Router)
**入口点：** website/src/app/layout.tsx
## 结构
website/src/
├── app/ # Next.js App Router
│ ├── api/ # API 路由
│ ├── markets/ # 市场页面
│ ├── bot/ # 机器人交互
│ └── creator-dashboard/
├── components/ # React 组件
├── hooks/ # 自定义钩子
└── lib/ # 工具函数
## 关键组件
| 组件 | 用途 | 位置 |
|-----------|---------|----------|
| HeaderWallet | 钱包连接 | components/HeaderWallet.tsx |
| MarketsClient | 市场列表 | app/markets/MarketsClient.js |
| SemanticSearchBar | 搜索界面 | components/SemanticSearchBar.js |
## 数据流
用户 → 市场页面 → API 路由 → Supabase → Redis (可选) → 响应
## 外部依赖
- Next.js 15.1.4 - 框架
- React 19.0.0 - UI 库
- Privy - 身份验证
- Tailwind CSS 3.4.1 - 样式
```
### 后端代码映射 (docs/CODEMAPS/backend.md)
```markdown
# 后端架构
**最后更新:** YYYY-MM-DD
**运行时:** Next.js API 路由
**入口点:** website/src/app/api/
## API 路由
| 路由 | 方法 | 用途 |
|-------|--------|---------|
| /api/markets | GET | 列出所有市场 |
| /api/markets/search | GET | 语义搜索 |
| /api/market/[slug] | GET | 单个市场 |
| /api/market-price | GET | 实时定价 |
## 数据流
API 路由 → Supabase 查询 → Redis (缓存) → 响应
## 外部服务
- Supabase - PostgreSQL 数据库
- Redis Stack - 向量搜索
- OpenAI - 嵌入
```
### 集成代码映射 (docs/CODEMAPS/integrations.md)
```markdown
# 外部集成
**最后更新：** YYYY-MM-DD
## 认证 (Privy)
- 钱包连接 (Solana, Ethereum)
- 邮箱认证
- 会话管理
## 数据库 (Supabase)
- PostgreSQL 表
- 实时订阅
- 行级安全
## 搜索 (Redis + OpenAI)
- 向量嵌入 (text-embedding-ada-002)
- 语义搜索 (KNN)
- 回退到子字符串搜索
## 区块链 (Solana)
- 钱包集成
- 交易处理
- Meteora CP-AMM SDK
```
## README 更新模板
更新 README.md 时：
```markdown
# 项目名称
简要描述
## 设置
`​`​`bash
# 安装
npm install
# 环境变量
cp .env.example .env.local
# 填写：OPENAI_API_KEY, REDIS_URL 等
# 开发
npm run dev
# 构建
npm run build
`​`​`
## 架构
详细架构请参阅 [docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md)。
### 关键目录
- `src/app` - Next.js App Router 页面和 API 路由
- `src/components` - 可复用的 React 组件
- `src/lib` - 工具库和客户端
## 功能
- [功能 1] - 描述
- [功能 2] - 描述
## 文档
- [设置指南](docs/GUIDES/setup.md)
- [API 参考](docs/GUIDES/api.md)
- [架构](docs/CODEMAPS/INDEX.md)
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)
```
## 支持文档的脚本
### scripts/codemaps/generate.ts
```typescript
/**
* Generate codemaps from repository structure
* Usage: tsx scripts/codemaps/generate.ts
*/
import { Project } from 'ts-morph'
import * as fs from 'fs'
import * as path from 'path'
async function generateCodemaps() {
const project = new Project({
tsConfigFilePath: 'tsconfig.json',
})
// 1. Discover all source files
const sourceFiles = project.getSourceFiles('src/**/*.{ts,tsx}')
// 2. Build import/export graph
const graph = buildDependencyGraph(sourceFiles)
// 3. Detect entrypoints (pages, API routes)
const entrypoints = findEntrypoints(sourceFiles)
// 4. Generate codemaps
await generateFrontendMap(graph, entrypoints)
await generateBackendMap(graph, entrypoints)
await generateIntegrationsMap(graph)
// 5. Generate index
await generateIndex()
}
function buildDependencyGraph(files: SourceFile[]) {
// Map imports/exports between files
// Return graph structure
}
function findEntrypoints(files: SourceFile[]) {
// Identify pages, API routes, entry files
// Return list of entrypoints
}
```
### scripts/docs/update.ts
```typescript
/**
* Update documentation from code
* Usage: tsx scripts/docs/update.ts
*/
import * as fs from 'fs'
import { execSync } from 'child_process'
async function updateDocs() {
// 1. Read codemaps
const codemaps = readCodemaps()
// 2. Extract JSDoc/TSDoc
const apiDocs = extractJSDoc('src/**/*.ts')
// 3. Update README.md
await updateReadme(codemaps, apiDocs)
// 4. Update guides
await updateGuides(codemaps)
// 5. Generate API reference
await generateAPIReference(apiDocs)
}
function extractJSDoc(pattern: string) {
// Use jsdoc-to-markdown or similar
// Extract documentation from source
}
```
## 拉取请求模板
提交包含文档更新的拉取请求时：
```markdown
## 文档：更新代码映射和文档
### 摘要
重新生成了代码映射并更新了文档，以反映当前代码库状态。
### 变更
- 根据当前代码结构更新了 docs/CODEMAPS/*
- 使用最新的设置说明刷新了 README.md
- 使用当前 API 端点更新了 docs/GUIDES/*
- 向代码映射添加了 X 个新模块
- 移除了 Y 个过时的文档章节
### 生成的文件
- docs/CODEMAPS/INDEX.md
- docs/CODEMAPS/frontend.md
- docs/CODEMAPS/backend.md
- docs/CODEMAPS/integrations.md
### 验证
- [x] 文档中的所有链接有效
- [x] 代码示例是最新的
- [x] 架构图与现实匹配
- [x] 没有过时的引用
### 影响
🟢 低 - 仅文档更新，无代码变更
有关完整的架构概述，请参阅 docs/CODEMAPS/INDEX.md。
```
## 维护计划
**每周：**
* 检查 `src/` 中是否出现未在代码映射中记录的新文件
* 验证 README.md 中的说明是否有效
* 更新 package.json 描述
**主要功能完成后：**
* 重新生成所有代码映射
* 更新架构文档
* 刷新 API 参考
* 更新设置指南
**发布前：**
* 全面的文档审计
* 验证所有示例是否有效
* 检查所有外部链接
* 更新版本引用
1. **单一事实来源** — 从代码生成，而非手动编写
2. **新鲜度时间戳** — 始终包含最后更新日期
3. **令牌效率** — 保持每个代码地图不超过 500 行
4. **可操作** — 包含实际有效的设置命令
5. **交叉引用** — 链接相关文档
## 质量检查清单
提交文档前：
* \[ ] 代码映射从实际代码生成
* \[ ] 代码地图从实际代码生成
* \[ ] 所有文件路径已验证存在
* \[ ] 代码示例可编译/运行
* \[ ] 链接已测试（内部和外部）
* \[ ] 链接已测试
* \[ ] 新鲜度时间戳已更新
* \[ ] ASCII 图表清晰
* \[ ] 没有过时的引用
* \[ ] 拼写/语法已检查
* \[ ] 无过时引用
## 最佳实践
## 何时更新
1. **单一事实来源** - 从代码生成，不要手动编写
2. **新鲜度时间戳** - 始终包含最后更新日期
3. **令牌效率** - 保持每个代码映射在 500 行以内
4. **结构清晰** - 使用一致的 Markdown 格式
5. **可操作** - 包含实际可用的设置命令
6. **链接化** - 交叉引用相关文档
7. **示例** - 展示真实可运行的代码片段
8. **版本控制** - 在 git 中跟踪文档变更
**始终：** 新增主要功能、API 路由变更、添加/移除依赖项、架构变更、设置流程修改。
## 何时更新文档
**在以下情况必须更新文档：**
* 添加新主要功能时
* API 路由变更时
* 添加/移除依赖项时
* 架构发生重大变更时
* 设置流程修改时
**在以下情况可选择性地更新：**
* 小的错误修复
* 外观变更
* 不涉及 API 变更的重构
**可选：** 次要错误修复、外观更改、内部重构。
***
**记住**：与现实不符的文档比没有文档更糟。始终从事实来源（实际代码）生成。
**记住：** 与现实不符的文档比没有文档更糟糕。始终从事实来源生成。

860
docs/zh-CN/agents/e2e-runner.md
View File

@@ -1,822 +1,110 @@
---
name: e2e-runner
description: 端到端测试专家，首选使用 Vercel Agent Browser，备选使用 Playwright。主动用于生成、维护和运行 E2E 测试。管理测试旅程，隔离不稳定测试，上传工件（截图、视频、跟踪），并确保关键用户流程正常工作。
description: 使用Vercel Agent Browser（首选）和Playwright备选方案进行端到端测试的专家。主动用于生成、维护和运行E2E测试。管理测试流程，隔离不稳定的测试，上传工件（截图、视频、跟踪），并确保关键用户流程正常运行。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# E2E 测试运行器
您是一位专业的端到端测试专家。您的使命是通过创建、维护和执行全面的 E2E 测试，并配合适当的工件管理和不稳定测试处理，确保关键用户旅程正常工作。
## 主要工具：Vercel Agent Browser
**优先使用 Agent Browser 而非原始 Playwright** - 它针对 AI 代理进行了优化，具有语义选择器并能更好地处理动态内容。
### 为什么选择 Agent Browser？
* **语义选择器** - 通过含义查找元素，而非脆弱的 CSS/XPath
* **AI 优化** - 专为 LLM 驱动的浏览器自动化设计
* **自动等待** - 智能等待动态内容
* **基于 Playwright 构建** - 完全兼容 Playwright 作为备用方案
### Agent Browser 设置
```bash
# Install agent-browser globally
npm install -g agent-browser
# Install Chromium (required)
agent-browser install
```
### Agent Browser CLI 用法（主要）
Agent Browser 使用针对 AI 代理优化的快照 + refs 系统：
```bash
# Open a page and get a snapshot with interactive elements
agent-browser open https://example.com
agent-browser snapshot -i # Returns elements with refs like [ref=e1]
# Interact using element references from snapshot
agent-browser click @e1 # Click element by ref
agent-browser fill @e2 "user@example.com" # Fill input by ref
agent-browser fill @e3 "password123" # Fill password field
agent-browser click @e4 # Click submit button
# Wait for conditions
agent-browser wait visible @e5 # Wait for element
agent-browser wait navigation # Wait for page load
# Take screenshots
agent-browser screenshot after-login.png
# Get text content
agent-browser get text @e1
```
### 脚本中的 Agent Browser
对于程序化控制，通过 shell 命令使用 CLI：
```typescript
import { execSync } from 'child_process'
// Execute agent-browser commands
const snapshot = execSync('agent-browser snapshot -i --json').toString()
const elements = JSON.parse(snapshot)
// Find element ref and interact
execSync('agent-browser click @e1')
execSync('agent-browser fill @e2 "test@example.com"')
```
### 程序化 API（高级）
用于直接浏览器控制（屏幕录制、低级事件）：
```typescript
import { BrowserManager } from 'agent-browser'
const browser = new BrowserManager()
await browser.launch({ headless: true })
await browser.navigate('https://example.com')
// Low-level event injection
await browser.injectMouseEvent({ type: 'mousePressed', x: 100, y: 200, button: 'left' })
await browser.injectKeyboardEvent({ type: 'keyDown', key: 'Enter', code: 'Enter' })
// Screencast for AI vision
await browser.startScreencast() // Stream viewport frames
```
### Agent Browser 与 Claude Code
如果您安装了 `agent-browser` 技能，请使用 `/agent-browser` 进行交互式浏览器自动化任务。
***
## 备用工具：Playwright
当 Agent Browser 不可用或用于复杂的测试套件时，回退到 Playwright。
## 核心职责
1. **测试旅程创建** - 为用户流程编写测试（优先使用 Agent Browser，回退到 Playwright）
2. **测试维护** - 保持测试与 UI 更改同步
3. **不稳定测试管理** - 识别并隔离不稳定的测试
4. **工件管理** - 捕获截图、视频、跟踪记录
5. **CI/CD 集成** - 确保测试在流水线中可靠运行
6. **测试报告** - 生成 HTML 报告和 JUnit XML
1. **测试旅程创建** — 为用户流程编写测试（首选 Agent Browser，备选 Playwright）
2. **测试维护** — 保持测试与 UI 更改同步更新
3. **不稳定测试管理** — 识别并隔离不稳定的测试
4. **产物管理** — 捕获截图、视频、追踪记录
5. **CI/CD 集成** — 确保测试在流水线中可靠运行
6. **测试报告** — 生成 HTML 报告和 JUnit XML
## Playwright 测试框架（备用）
## 主要工具：Agent Browser
### 工具
* **@playwright/test** - 核心测试框架
* **Playwright Inspector** - 交互式调试测试
* **Playwright Trace Viewer** - 分析测试执行情况
* **Playwright Codegen** - 根据浏览器操作生成测试代码
### 测试命令
**首选 Agent Browser 而非原始 Playwright** — 语义化选择器、AI 优化、自动等待，基于 Playwright 构建。
```bash
# Run all E2E tests
npx playwright test
# Setup
npm install -g agent-browser && agent-browser install
# Run specific test file
npx playwright test tests/markets.spec.ts
# Run tests in headed mode (see browser)
npx playwright test --headed
# Debug test with inspector
npx playwright test --debug
# Generate test code from actions
npx playwright codegen http://localhost:3000
# Run tests with trace
npx playwright test --trace on
# Show HTML report
npx playwright show-report
# Update snapshots
npx playwright test --update-snapshots
# Run tests in specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
# Core workflow
agent-browser open https://example.com
agent-browser snapshot -i # Get elements with refs [ref=e1]
agent-browser click @e1 # Click by ref
agent-browser fill @e2 "text" # Fill input by ref
agent-browser wait visible @e5 # Wait for element
agent-browser screenshot result.png
```
## E2E 测试工作流
## 备选方案：Playwright
### 1. 测试规划阶段
```
a) Identify critical user journeys
- Authentication flows (login, logout, registration)
- Core features (market creation, trading, searching)
- Payment flows (deposits, withdrawals)
- Data integrity (CRUD operations)
b) Define test scenarios
- Happy path (everything works)
- Edge cases (empty states, limits)
- Error cases (network failures, validation)
c) Prioritize by risk
- HIGH: Financial transactions, authentication
- MEDIUM: Search, filtering, navigation
- LOW: UI polish, animations, styling
```
### 2. 测试创建阶段
```
For each user journey:
1. Write test in Playwright
- Use Page Object Model (POM) pattern
- Add meaningful test descriptions
- Include assertions at key steps
- Add screenshots at critical points
2. Make tests resilient
- Use proper locators (data-testid preferred)
- Add waits for dynamic content
- Handle race conditions
- Implement retry logic
3. Add artifact capture
- Screenshot on failure
- Video recording
- Trace for debugging
- Network logs if needed
```
### 3. 测试执行阶段
```
a) Run tests locally
- Verify all tests pass
- Check for flakiness (run 3-5 times)
- Review generated artifacts
b) Quarantine flaky tests
- Mark unstable tests as @flaky
- Create issue to fix
- Remove from CI temporarily
c) Run in CI/CD
- Execute on pull requests
- Upload artifacts to CI
- Report results in PR comments
```
## Playwright 测试结构
### 测试文件组织
```
tests/
├── e2e/ # End-to-end user journeys
│ ├── auth/ # Authentication flows
│ │ ├── login.spec.ts
│ │ ├── logout.spec.ts
│ │ └── register.spec.ts
│ ├── markets/ # Market features
│ │ ├── browse.spec.ts
│ │ ├── search.spec.ts
│ │ ├── create.spec.ts
│ │ └── trade.spec.ts
│ ├── wallet/ # Wallet operations
│ │ ├── connect.spec.ts
│ │ └── transactions.spec.ts
│ └── api/ # API endpoint tests
│ ├── markets-api.spec.ts
│ └── search-api.spec.ts
├── fixtures/ # Test data and helpers
│ ├── auth.ts # Auth fixtures
│ ├── markets.ts # Market test data
│ └── wallets.ts # Wallet fixtures
└── playwright.config.ts # Playwright configuration
```
### 页面对象模型模式
```typescript
// pages/MarketsPage.ts
import { Page, Locator } from '@playwright/test'
export class MarketsPage {
readonly page: Page
readonly searchInput: Locator
readonly marketCards: Locator
readonly createMarketButton: Locator
readonly filterDropdown: Locator
constructor(page: Page) {
this.page = page
this.searchInput = page.locator('[data-testid="search-input"]')
this.marketCards = page.locator('[data-testid="market-card"]')
this.createMarketButton = page.locator('[data-testid="create-market-btn"]')
this.filterDropdown = page.locator('[data-testid="filter-dropdown"]')
}
async goto() {
await this.page.goto('/markets')
await this.page.waitForLoadState('networkidle')
}
async searchMarkets(query: string) {
await this.searchInput.fill(query)
await this.page.waitForResponse(resp => resp.url().includes('/api/markets/search'))
await this.page.waitForLoadState('networkidle')
}
async getMarketCount() {
return await this.marketCards.count()
}
async clickMarket(index: number) {
await this.marketCards.nth(index).click()
}
async filterByStatus(status: string) {
await this.filterDropdown.selectOption(status)
await this.page.waitForLoadState('networkidle')
}
}
```
### 包含最佳实践的示例测试
```typescript
// tests/e2e/markets/search.spec.ts
import { test, expect } from '@playwright/test'
import { MarketsPage } from '../../pages/MarketsPage'
test.describe('Market Search', () => {
let marketsPage: MarketsPage
test.beforeEach(async ({ page }) => {
marketsPage = new MarketsPage(page)
await marketsPage.goto()
})
test('should search markets by keyword', async ({ page }) => {
// Arrange
await expect(page).toHaveTitle(/Markets/)
// Act
await marketsPage.searchMarkets('trump')
// Assert
const marketCount = await marketsPage.getMarketCount()
expect(marketCount).toBeGreaterThan(0)
// Verify first result contains search term
const firstMarket = marketsPage.marketCards.first()
await expect(firstMarket).toContainText(/trump/i)
// Take screenshot for verification
await page.screenshot({ path: 'artifacts/search-results.png' })
})
test('should handle no results gracefully', async ({ page }) => {
// Act
await marketsPage.searchMarkets('xyznonexistentmarket123')
// Assert
await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
const marketCount = await marketsPage.getMarketCount()
expect(marketCount).toBe(0)
})
test('should clear search results', async ({ page }) => {
// Arrange - perform search first
await marketsPage.searchMarkets('trump')
await expect(marketsPage.marketCards.first()).toBeVisible()
// Act - clear search
await marketsPage.searchInput.clear()
await page.waitForLoadState('networkidle')
// Assert - all markets shown again
const marketCount = await marketsPage.getMarketCount()
expect(marketCount).toBeGreaterThan(10) // Should show all markets
})
})
```
## 示例项目特定的测试场景
### 示例项目的关键用户旅程
**1. 市场浏览流程**
```typescript
test('user can browse and view markets', async ({ page }) => {
// 1. Navigate to markets page
await page.goto('/markets')
await expect(page.locator('h1')).toContainText('Markets')
// 2. Verify markets are loaded
const marketCards = page.locator('[data-testid="market-card"]')
await expect(marketCards.first()).toBeVisible()
// 3. Click on a market
await marketCards.first().click()
// 4. Verify market details page
await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
await expect(page.locator('[data-testid="market-name"]')).toBeVisible()
// 5. Verify chart loads
await expect(page.locator('[data-testid="price-chart"]')).toBeVisible()
})
```
**2. 语义搜索流程**
```typescript
test('semantic search returns relevant results', async ({ page }) => {
// 1. Navigate to markets
await page.goto('/markets')
// 2. Enter search query
const searchInput = page.locator('[data-testid="search-input"]')
await searchInput.fill('election')
// 3. Wait for API call
await page.waitForResponse(resp =>
resp.url().includes('/api/markets/search') && resp.status() === 200
)
// 4. Verify results contain relevant markets
const results = page.locator('[data-testid="market-card"]')
await expect(results).not.toHaveCount(0)
// 5. Verify semantic relevance (not just substring match)
const firstResult = results.first()
const text = await firstResult.textContent()
expect(text?.toLowerCase()).toMatch(/election|trump|biden|president|vote/)
})
```
**3. 钱包连接流程**
```typescript
test('user can connect wallet', async ({ page, context }) => {
// Setup: Mock Privy wallet extension
await context.addInitScript(() => {
// @ts-ignore
window.ethereum = {
isMetaMask: true,
request: async ({ method }) => {
if (method === 'eth_requestAccounts') {
return ['0x1234567890123456789012345678901234567890']
}
if (method === 'eth_chainId') {
return '0x1'
}
}
}
})
// 1. Navigate to site
await page.goto('/')
// 2. Click connect wallet
await page.locator('[data-testid="connect-wallet"]').click()
// 3. Verify wallet modal appears
await expect(page.locator('[data-testid="wallet-modal"]')).toBeVisible()
// 4. Select wallet provider
await page.locator('[data-testid="wallet-provider-metamask"]').click()
// 5. Verify connection successful
await expect(page.locator('[data-testid="wallet-address"]')).toBeVisible()
await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
})
```
**4. 市场创建流程（已验证身份）**
```typescript
test('authenticated user can create market', async ({ page }) => {
// Prerequisites: User must be authenticated
await page.goto('/creator-dashboard')
// Verify auth (or skip test if not authenticated)
const isAuthenticated = await page.locator('[data-testid="user-menu"]').isVisible()
test.skip(!isAuthenticated, 'User not authenticated')
// 1. Click create market button
await page.locator('[data-testid="create-market"]').click()
// 2. Fill market form
await page.locator('[data-testid="market-name"]').fill('Test Market')
await page.locator('[data-testid="market-description"]').fill('This is a test market')
await page.locator('[data-testid="market-end-date"]').fill('2025-12-31')
// 3. Submit form
await page.locator('[data-testid="submit-market"]').click()
// 4. Verify success
await expect(page.locator('[data-testid="success-message"]')).toBeVisible()
// 5. Verify redirect to new market
await expect(page).toHaveURL(/\/markets\/test-market/)
})
```
**5. 交易流程（关键 - 真实资金）**
```typescript
test('user can place trade with sufficient balance', async ({ page }) => {
// WARNING: This test involves real money - use testnet/staging only!
test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
// 1. Navigate to market
await page.goto('/markets/test-market')
// 2. Connect wallet (with test funds)
await page.locator('[data-testid="connect-wallet"]').click()
// ... wallet connection flow
// 3. Select position (Yes/No)
await page.locator('[data-testid="position-yes"]').click()
// 4. Enter trade amount
await page.locator('[data-testid="trade-amount"]').fill('1.0')
// 5. Verify trade preview
const preview = page.locator('[data-testid="trade-preview"]')
await expect(preview).toContainText('1.0 SOL')
await expect(preview).toContainText('Est. shares:')
// 6. Confirm trade
await page.locator('[data-testid="confirm-trade"]').click()
// 7. Wait for blockchain transaction
await page.waitForResponse(resp =>
resp.url().includes('/api/trade') && resp.status() === 200,
{ timeout: 30000 } // Blockchain can be slow
)
// 8. Verify success
await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
// 9. Verify balance updated
const balance = page.locator('[data-testid="wallet-balance"]')
await expect(balance).not.toContainText('--')
})
```
## Playwright 配置
```typescript
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'
export default defineConfig({
testDir: './tests/e2e',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: [
['html', { outputFolder: 'playwright-report' }],
['junit', { outputFile: 'playwright-results.xml' }],
['json', { outputFile: 'playwright-results.json' }]
],
use: {
baseURL: process.env.BASE_URL || 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
actionTimeout: 10000,
navigationTimeout: 30000,
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
{
name: 'mobile-chrome',
use: { ...devices['Pixel 5'] },
},
],
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
timeout: 120000,
},
})
```
## 不稳定测试管理
### 识别不稳定测试
当 Agent Browser 不可用时，直接使用 Playwright。
```bash
# Run test multiple times to check stability
npx playwright test tests/markets/search.spec.ts --repeat-each=10
# Run specific test with retries
npx playwright test tests/markets/search.spec.ts --retries=3
npx playwright test # Run all E2E tests
npx playwright test tests/auth.spec.ts # Run specific file
npx playwright test --headed # See browser
npx playwright test --debug # Debug with inspector
npx playwright test --trace on # Run with trace
npx playwright show-report # View HTML report
```
### 隔离模式
## 工作流程
### 1. 规划
* 识别关键用户旅程（认证、核心功能、支付、增删改查）
* 定义场景：成功路径、边界情况、错误情况
* 按风险确定优先级：高（财务、认证）、中（搜索、导航）、低（UI 优化）
### 2. 创建
* 使用页面对象模型（POM）模式
* 优先使用 `data-testid` 定位器而非 CSS/XPath
* 在关键步骤添加断言
* 在关键点捕获截图
* 使用适当的等待（绝不使用 `waitForTimeout`）
### 3. 执行
* 本地运行 3-5 次以检查是否存在不稳定性
* 使用 `test.fixme()` 或 `test.skip()` 隔离不稳定的测试
* 将产物上传到 CI
## 关键原则
* **使用语义化定位器**：`[data-testid="..."]` > CSS 选择器 > XPath
* **等待条件，而非时间**：`waitForResponse()` > `waitForTimeout()`
* **内置自动等待**：`page.locator().click()` 自动等待；原始的 `page.click()` 不会
* **隔离测试**：每个测试应独立；无共享状态
* **快速失败**：在每个关键步骤使用 `expect()` 断言
* **重试时追踪**：配置 `trace: 'on-first-retry'` 以调试失败
## 不稳定测试处理
```typescript
// Mark flaky test for quarantine
test('flaky: market search with complex query', async ({ page }) => {
test.fixme(true, 'Test is flaky - Issue #123')
// Test code here...
// Quarantine
test('flaky: market search', async ({ page }) => {
test.fixme(true, 'Flaky - Issue #123')
})
// Or use conditional skip
test('market search with complex query', async ({ page }) => {
test.skip(process.env.CI, 'Test is flaky in CI - Issue #123')
// Test code here...
})
// Identify flakiness
// npx playwright test --repeat-each=10
```
### 常见的不稳定原因及修复方法
**1. 竞态条件**
```typescript
// ❌ FLAKY: Don't assume element is ready
await page.click('[data-testid="button"]')
// ✅ STABLE: Wait for element to be ready
await page.locator('[data-testid="button"]').click() // Built-in auto-wait
```
**2. 网络时序**
```typescript
// ❌ FLAKY: Arbitrary timeout
await page.waitForTimeout(5000)
// ✅ STABLE: Wait for specific condition
await page.waitForResponse(resp => resp.url().includes('/api/markets'))
```
**3. 动画时序**
```typescript
// ❌ FLAKY: Click during animation
await page.click('[data-testid="menu-item"]')
// ✅ STABLE: Wait for animation to complete
await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
await page.waitForLoadState('networkidle')
await page.click('[data-testid="menu-item"]')
```
## 产物管理
### 截图策略
```typescript
// Take screenshot at key points
await page.screenshot({ path: 'artifacts/after-login.png' })
// Full page screenshot
await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
// Element screenshot
await page.locator('[data-testid="chart"]').screenshot({
path: 'artifacts/chart.png'
})
```
### 跟踪记录收集
```typescript
// Start trace
await browser.startTracing(page, {
path: 'artifacts/trace.json',
screenshots: true,
snapshots: true,
})
// ... test actions ...
// Stop trace
await browser.stopTracing()
```
### 视频录制
```typescript
// Configured in playwright.config.ts
use: {
video: 'retain-on-failure', // Only save video if test fails
videosPath: 'artifacts/videos/'
}
```
## CI/CD 集成
### GitHub Actions 工作流
```yaml
# .github/workflows/e2e.yml
name: E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- name: Install dependencies
run: npm ci
- name: Install Playwright browsers
run: npx playwright install --with-deps
- name: Run E2E tests
run: npx playwright test
env:
BASE_URL: https://staging.pmx.trade
- name: Upload artifacts
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-report
path: playwright-report/
retention-days: 30
- name: Upload test results
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-results
path: playwright-results.xml
```
## 测试报告格式
```markdown
# E2E 测试报告
**日期:** YYYY-MM-DD HH:MM
**持续时间:** Xm Ys
**状态:** ✅ 通过 / ❌ 失败
## 概要
- **总测试数:** X
- **通过:** Y (Z%)
- **失败:** A
- **不稳定:** B
- **跳过:** C
## 按测试套件分类的结果
### 市场 - 浏览与搜索
- ✅ 用户可以浏览市场 (2.3s)
- ✅ 语义搜索返回相关结果 (1.8s)
- ✅ 搜索处理无结果情况 (1.2s)
- ❌ 搜索包含特殊字符 (0.9s)
### 钱包 - 连接
- ✅ 用户可以连接 MetaMask (3.1s)
- ⚠️ 用户可以连接 Phantom (2.8s) - 不稳定
- ✅ 用户可以断开钱包连接 (1.5s)
### 交易 - 核心流程
- ✅ 用户可以下买单 (5.2s)
- ❌ 用户可以下卖单 (4.8s)
- ✅ 余额不足显示错误 (1.9s)
## 失败的测试
### 1. search with special characters
**文件:** `tests/e2e/markets/search.spec.ts:45`
**错误:** 期望元素可见，但未找到
**截图:** artifacts/search-special-chars-failed.png
**跟踪文件:** artifacts/trace-123.zip
**重现步骤:**
1. 导航到 /markets
2. 输入包含特殊字符的搜索查询："trump & biden"
3. 验证结果
**建议修复:** 对搜索查询中的特殊字符进行转义
---
### 2. user can place sell order
**文件:** `tests/e2e/trading/sell.spec.ts:28`
**错误:** 等待 API 响应 /api/trade 超时
**视频:** artifacts/videos/sell-order-failed.webm
**可能原因:**
- 区块链网络慢
- Gas 不足
- 交易被回退
**建议修复:** 增加超时时间或检查区块链日志
## 产物
- HTML 报告: playwright-report/index.html
- 截图: artifacts/*.png (12 个文件)
- 视频: artifacts/videos/*.webm (2 个文件)
- 跟踪文件: artifacts/*.zip (2 个文件)
- JUnit XML: playwright-results.xml
## 后续步骤
- [ ] 修复 2 个失败的测试
- [ ] 调查 1 个不稳定的测试
- [ ] 如果全部通过，则审阅并合并
```
常见原因：竞态条件（使用自动等待定位器）、网络时序（等待响应）、动画时序（等待 `networkidle`）。
## 成功指标
E2E 测试运行后：
* 所有关键旅程通过（100%）
* 总体通过率 > 95%
* 不稳定率 < 5%
* 测试持续时间 < 10 分钟
* 产物已上传并可访问
* ✅ 所有关键旅程通过 (100%)
* ✅ 总体通过率 > 95%
* ✅ 不稳定率 < 5%
* ✅ 没有失败的测试阻塞部署
* ✅ 产物已上传并可访问
* ✅ 测试持续时间 < 10 分钟
* ✅ HTML 报告已生成
## 参考
有关详细的 Playwright 模式、页面对象模型示例、配置模板、CI/CD 工作流和产物管理策略，请参阅技能：`e2e-testing`。
***
**请记住**：E2E 测试是进入生产环境前的最后一道防线。它们能捕捉单元测试遗漏的集成问题。投入时间让它们变得稳定、快速且全面。对于示例项目，请特别关注资金流相关的测试——一个漏洞就可能让用户损失真实资金。
**记住**：端到端测试是上线前的最后一道防线。它们能捕获单元测试遗漏的集成问题。投资于稳定性、速度和覆盖率。

381
docs/zh-CN/agents/go-build-resolver.md
View File

@@ -1,8 +1,8 @@
---
name: go-build-resolver
description: Go 构建、vet 和编译错误解决专家。以最小更改修复构建错误、go vet 问题和 linter 警告。在 Go 构建失败时使用。
description: Go 构建、vet 和编译错误解决专家。以最小改动修复构建错误、go vet 问题和 linter 警告。在 Go 构建失败时使用。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# Go 构建错误解决器
@@ -19,366 +19,77 @@ model: opus
## 诊断命令
按顺序运行这些命令以理解问题：
按顺序运行这些命令：
```bash
# 1. Basic build check
go build ./...
# 2. Vet for common mistakes
go vet ./...
# 3. Static analysis (if available)
staticcheck ./... 2>/dev/null || echo "staticcheck not installed"
golangci-lint run 2>/dev/null || echo "golangci-lint not installed"
# 4. Module verification
go mod verify
go mod tidy -v
# 5. List dependencies
go list -m all
```
## 常见错误模式及修复方法
### 1. 未定义的标识符
**错误：** `undefined: SomeFunc`
**原因：**
* 缺少导入
* 函数/变量名拼写错误
* 未导出的标识符（首字母小写）
* 函数定义在具有构建约束的不同文件中
**修复：**
```go
// Add missing import
import "package/that/defines/SomeFunc"
// Or fix typo
// somefunc -> SomeFunc
// Or export the identifier
// func someFunc() -> func SomeFunc()
```
### 2. 类型不匹配
**错误：** `cannot use x (type A) as type B`
**原因：**
* 错误的类型转换
* 接口未满足
* 指针与值不匹配
**修复：**
```go
// Type conversion
var x int = 42
var y int64 = int64(x)
// Pointer to value
var ptr *int = &x
var val int = *ptr
// Value to pointer
var val int = 42
var ptr *int = &val
```
### 3. 接口未满足
**错误：** `X does not implement Y (missing method Z)`
**诊断：**
```bash
# Find what methods are missing
go doc package.Interface
```
**修复：**
```go
// Implement missing method with correct signature
func (x *X) Z() error {
// implementation
return nil
}
// Check receiver type matches (pointer vs value)
// If interface expects: func (x X) Method()
// You wrote: func (x *X) Method() // Won't satisfy
```
### 4. 导入循环
**错误：** `import cycle not allowed`
**诊断：**
```bash
go list -f '{{.ImportPath}} -> {{.Imports}}' ./...
```
**修复：**
* 将共享类型移动到单独的包中
* 使用接口来打破循环
* 重构包依赖关系
```text
# Before (cycle)
package/a -> package/b -> package/a
# After (fixed)
package/types <- shared types
package/a -> package/types
package/b -> package/types
```
### 5. 找不到包
**错误：** `cannot find package "x"`
**修复：**
```bash
# Add dependency
go get package/path@version
# Or update go.mod
go mod tidy
# Or for local packages, check go.mod module path
# Module: github.com/user/project
# Import: github.com/user/project/internal/pkg
```
### 6. 缺少返回
**错误：** `missing return at end of function`
**修复：**
```go
func Process() (int, error) {
if condition {
return 0, errors.New("error")
}
return 42, nil // Add missing return
}
```
### 7. 未使用的变量/导入
**错误：** `x declared but not used` 或 `imported and not used`
**修复：**
```go
// Remove unused variable
x := getValue() // Remove if x not used
// Use blank identifier if intentionally ignoring
_ = getValue()
// Remove unused import or use blank import for side effects
import _ "package/for/init/only"
```
### 8. 单值上下文中的多值
**错误：** `multiple-value X() in single-value context`
**修复：**
```go
// Wrong
result := funcReturningTwo()
// Correct
result, err := funcReturningTwo()
if err != nil {
return err
}
// Or ignore second value
result, _ := funcReturningTwo()
```
### 9. 无法分配给字段
**错误：** `cannot assign to struct field x.y in map`
**修复：**
```go
// Cannot modify struct in map directly
m := map[string]MyStruct{}
m["key"].Field = "value" // Error!
// Fix: Use pointer map or copy-modify-reassign
m := map[string]*MyStruct{}
m["key"] = &MyStruct{}
m["key"].Field = "value" // Works
// Or
m := map[string]MyStruct{}
tmp := m["key"]
tmp.Field = "value"
m["key"] = tmp
```
### 10. 无效操作（类型断言）
**错误：** `invalid type assertion: x.(T) (non-interface type)`
**修复：**
```go
// Can only assert from interface
var i interface{} = "hello"
s := i.(string) // Valid
var s string = "hello"
// s.(int) // Invalid - s is not interface
```
## 模块问题
### Replace 指令问题
```bash
# Check for local replaces that might be invalid
grep "replace" go.mod
# Remove stale replaces
go mod edit -dropreplace=package/path
```
### 版本冲突
```bash
# See why a version is selected
go mod why -m package
# Get specific version
go get package@v1.2.3
# Update all dependencies
go get -u ./...
```
### 校验和不匹配
```bash
# Clear module cache
go clean -modcache
# Re-download
go mod download
```
## Go Vet 问题
### 可疑结构
```go
// Vet: unreachable code
func example() int {
return 1
fmt.Println("never runs") // Remove this
}
// Vet: printf format mismatch
fmt.Printf("%d", "string") // Fix: %s
// Vet: copying lock value
var mu sync.Mutex
mu2 := mu // Fix: use pointer *sync.Mutex
// Vet: self-assignment
x = x // Remove pointless assignment
```
## 修复策略
1. **阅读完整的错误信息** - Go 错误信息是描述性的
2. **识别文件和行号** - 直接定位到源代码
3. **理解上下文** - 阅读周围的代码
4. **进行最小化修复** - 不要重构，只修复错误
5. **验证修复** - 再次运行 `go build ./...`
6. **检查级联错误** - 一个修复可能会暴露其他错误
## 解决工作流
```text
1. go build ./...
↓ Error?
2. Parse error message
↓
3. Read affected file
↓
4. Apply minimal fix
↓
5. go build ./...
↓ Still errors?
→ Back to step 2
↓ Success?
6. go vet ./...
↓ Warnings?
→ Fix and repeat
↓
7. go test ./...
↓
8. Done!
1. go build ./... -> Parse error message
2. Read affected file -> Understand context
3. Apply minimal fix -> Only what's needed
4. go build ./... -> Verify fix
5. go vet ./... -> Check for warnings
6. go test ./... -> Ensure nothing broke
```
## 常见修复模式
| 错误 | 原因 | 修复方法 |
|-------|-------|-----|
| `undefined: X` | 缺少导入、拼写错误、未导出 | 添加导入或修正大小写 |
| `cannot use X as type Y` | 类型不匹配、指针/值 | 类型转换或解引用 |
| `X does not implement Y` | 缺少方法 | 使用正确的接收器实现方法 |
| `import cycle not allowed` | 循环依赖 | 将共享类型提取到新包中 |
| `cannot find package` | 缺少依赖项 | `go get pkg@version` 或 `go mod tidy` |
| `missing return` | 控制流不完整 | 添加返回语句 |
| `declared but not used` | 未使用的变量/导入 | 删除或使用空白标识符 |
| `multiple-value in single-value context` | 未处理的返回值 | `result, err := func()` |
| `cannot assign to struct field in map` | 映射值修改 | 使用指针映射或复制-修改-重新赋值 |
| `invalid type assertion` | 对非接口进行断言 | 仅从 `interface{}` 进行断言 |
## 模块故障排除
```bash
grep "replace" go.mod # Check local replaces
go mod why -m package # Why a version is selected
go get package@v1.2.3 # Pin specific version
go clean -modcache && go mod download # Fix checksum issues
```
## 关键原则
* **仅进行针对性修复** -- 不要重构，只修复错误
* **绝不**在没有明确批准的情况下添加 `//nolint`
* **绝不**更改函数签名，除非必要
* **始终**在添加/删除导入后运行 `go mod tidy`
* 修复根本原因，而非压制症状
## 停止条件
如果出现以下情况，请停止并报告：
* 尝试修复 3 次后相同错误仍然存在
* 修复引入的错误比它解决的错误更多
* 错误需要超出范围的架构更改
* 需要包重构的循环依赖
* 需要手动安装的缺失外部依赖项
* 尝试修复3次后，相同错误仍然存在
* 修复引入的错误比解决的问题更多
* 错误需要的架构更改超出当前范围
## 输出格式
每次尝试修复后：
```text
[FIXED] internal/handler/user.go:42
Error: undefined: UserService
Fix: Added import "project/internal/service"
Remaining errors: 3
```
最终总结：
最终：`Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`
```text
Build Status: SUCCESS/FAILED
Errors Fixed: N
Vet Warnings Fixed: N
Files Modified: list
Remaining Issues: list (if any)
```
## 重要注意事项
* **绝不**在未经明确批准的情况下添加 `//nolint` 注释
* **绝不**更改函数签名，除非修复需要
* **始终**在添加/删除导入后运行 `go mod tidy`
* **优先**修复根本原因，而不是掩盖症状
* **使用**内联注释记录任何不明显的修复
应该精准地修复构建错误。目标是获得可工作的构建，而不是重构代码库。
有关详细的 Go 错误模式和代码示例，请参阅 `skill: golang-patterns`。

280
docs/zh-CN/agents/go-reviewer.md
View File

@@ -1,8 +1,8 @@
---
name: go-reviewer
description: 专门研究地道Go语言、并发模式、错误处理和性能的专家Go代码审查员。适用于所有Go代码更改。必须用于Go项目。
description: 专业的Go代码审查专家，专注于地道Go语言、并发模式、错误处理和性能优化。适用于所有Go代码变更。必须用于Go项目。
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
model: sonnet
---
您是一名高级 Go 代码审查员，确保符合 Go 语言惯用法和最佳实践的高标准。
@@ -14,278 +14,70 @@ model: opus
3. 关注修改过的 `.go` 文件
4. 立即开始审查
## 安全检查（关键）
## 审查优先级
### 关键 -- 安全性
* **SQL 注入**：`database/sql` 查询中的字符串拼接
```go
// 错误
db.Query("SELECT * FROM users WHERE id = " + userID)
// 正确
db.Query("SELECT * FROM users WHERE id = $1", userID)
```
* **命令注入**：`os/exec` 中的未经验证输入
```go
// 错误
exec.Command("sh", "-c", "echo " + userInput)
// 正确
exec.Command("echo", userInput)
```
* **路径遍历**：用户控制的文件路径
```go
// 错误
os.ReadFile(filepath.Join(baseDir, userPath))
// 正确
cleanPath := filepath.Clean(userPath)
if strings.HasPrefix(cleanPath, "..") {
return ErrInvalidPath
}
```
* **竞态条件**：无同步的共享状态
* **Unsafe 包**：无正当理由使用 `unsafe`
* **硬编码密钥**：源代码中的 API 密钥、密码
* **命令注入**：`os/exec` 中未经验证的输入
* **路径遍历**：用户控制的文件路径未使用 `filepath.Clean` + 前缀检查
* **竞争条件**：共享状态未同步
* **不安全的包**：使用未经论证的包
* **硬编码的密钥**：源代码中的 API 密钥、密码
* **不安全的 TLS**：`InsecureSkipVerify: true`
* **弱加密**：出于安全目的使用 MD5/SHA1
### 关键 -- 错误处理
## 错误处理（关键）
* **忽略的错误**：使用 `_` 丢弃错误
* **缺少错误包装**：`return err` 没有 `fmt.Errorf("context: %w", err)`
* **对可恢复的错误使用 panic**：应使用错误返回
* **缺少 errors.Is/As**：使用 `errors.Is(err, target)` 而非 `err == target`
* **忽略的错误**：使用 `_` 忽略错误
```go
// 错误
result, _ := doSomething()
// 正确
result, err := doSomething()
if err != nil {
return fmt.Errorf("do something: %w", err)
}
```
### 高 -- 并发
* **缺少错误包装**：没有上下文的错误
```go
// 错误
return err
// 正确
return fmt.Errorf("load config %s: %w", path, err)
```
* **Goroutine 泄漏**：没有取消机制（应使用 `context.Context`）
* **无缓冲通道死锁**：发送方没有接收方
* **缺少 sync.WaitGroup**：Goroutine 未协调
* **互斥锁误用**：未使用 `defer mu.Unlock()`
* **使用 Panic 而非错误**：对可恢复错误使用 panic
* **errors.Is/As**：未用于错误检查
```go
// 错误
if err == sql.ErrNoRows
// 正确
if errors.Is(err, sql.ErrNoRows)
```
## 并发性（高）
* **Goroutine 泄漏**：永不终止的 Goroutine
```go
// 错误：无法停止 goroutine
go func() {
for { doWork() }
}()
// 正确：用于取消的上下文
go func() {
for {
select {
case <-ctx.Done():
return
default:
doWork()
}
}
}()
```
* **竞态条件**：运行 `go build -race ./...`
* **无缓冲通道死锁**：发送时无接收者
* **缺少 sync.WaitGroup**：无协调的 Goroutine
* **上下文未传播**：在嵌套调用中忽略上下文
* **Mutex 误用**：未使用 `defer mu.Unlock()`
```go
// 错误：panic 时可能不会调用 Unlock
mu.Lock()
doSomething()
mu.Unlock()
// 正确
mu.Lock()
defer mu.Unlock()
doSomething()
```
## 代码质量（高）
* **大型函数**：超过 50 行的函数
* **深度嵌套**：超过 4 层缩进
* **接口污染**：定义未用于抽象的接口
### 高 -- 代码质量
* **函数过大**：超过 50 行
* **嵌套过深**：超过 4 层
* **非惯用法**：使用 `if/else` 而不是提前返回
* **包级变量**：可变的全局状态
* **接口污染**：定义未使用的抽象
* **裸返回**：在超过几行的函数中使用
```go
// 在长函数中错误
func process() (result int, err error) {
// ... 30 行 ...
return // 返回的是什么？
}
```
* **非惯用代码**：
```go
// 错误
if err != nil {
return err
} else {
doSomething()
}
// 正确：尽早返回
if err != nil {
return err
}
doSomething()
```
## 性能（中）
* **低效的字符串构建**：
```go
// 错误
for _, s := range parts { result += s }
// 正确
var sb strings.Builder
for _, s := range parts { sb.WriteString(s) }
```
* **切片预分配**：未使用 `make([]T, 0, cap)`
* **指针与值接收器**：使用不一致
* **不必要的分配**：在热点路径中创建对象
### 中 -- 性能
* **循环中的字符串拼接**：应使用 `strings.Builder`
* **缺少切片预分配**：`make([]T, 0, cap)`
* **N+1 查询**：循环中的数据库查询
* **不必要的内存分配**：热点路径中的对象分配
* **缺少连接池**：为每个请求创建新的数据库连接
## 最佳实践（中）
* **接受接口，返回结构体**：函数应接受接口参数
* **上下文优先**：上下文应为第一个参数
```go
// 错误
func Process(id string, ctx context.Context)
// 正确
func Process(ctx context.Context, id string)
```
### 中 -- 最佳实践
* **Context 优先**：`ctx context.Context` 应为第一个参数
* **表驱动测试**：测试应使用表驱动模式
* **Godoc 注释**：导出的函数需要文档
```go
// ProcessData 将原始输入转换为结构化输出。
// 如果输入格式错误，则返回错误。
func ProcessData(input []byte) (*Data, error)
```
* **错误信息**：应为小写，无标点符号
```go
// 错误
return errors.New("Failed to process data.")
// 正确
return errors.New("failed to process data")
```
* **错误信息**：小写，无标点
* **包命名**：简短，小写，无下划线
## Go 特定的反模式
* **init() 滥用**：在 init 函数中使用复杂逻辑
* **空接口过度使用**：使用 `interface{}` 而非泛型
* **无 `ok` 的类型断言**：可能导致 panic
```go
// 错误
v := x.(string)
// 正确
v, ok := x.(string)
if !ok { return ErrInvalidType }
```
* **循环中的延迟调用**：资源累积
```go
// 错误：文件打开直到函数返回
for _, path := range paths {
f, _ := os.Open(path)
defer f.Close()
}
// 正确：在循环迭代中关闭
for _, path := range paths {
func() {
f, _ := os.Open(path)
defer f.Close()
process(f)
}()
}
```
## 审查输出格式
对于每个问题：
```text
[CRITICAL] SQL Injection vulnerability
File: internal/repository/user.go:42
Issue: User input directly concatenated into SQL query
Fix: Use parameterized query
query := "SELECT * FROM users WHERE id = " + userID // Bad
query := "SELECT * FROM users WHERE id = $1" // Good
db.Query(query, userID)
```
* **循环中的 defer 调用**：存在资源累积风险
## 诊断命令
运行这些检查：
```bash
# Static analysis
go vet ./...
staticcheck ./...
golangci-lint run
# Race detection
go build -race ./...
go test -race ./...
# Security scanning
govulncheck ./...
```
## 批准标准
* **批准**：无关键或高优先级问题
* **警告**：仅存在中优先级问题（可谨慎合并）
* **批准**：没有关键或高优先级问题
* **警告**：仅存在中优先级问题
* **阻止**：发现关键或高优先级问题
## Go 版本注意事项
* 检查 `go.mod` 以获取最低 Go 版本
* 注意代码是否使用了较新 Go 版本的功能（泛型 1.18+，模糊测试 1.18+）
* 标记标准库中已弃用的函数
以这样的心态进行审查：“这段代码能在谷歌或顶级的 Go 公司通过审查吗？”
有关详细的 Go 代码示例和反模式，请参阅 `skill: golang-patterns`。

99
docs/zh-CN/agents/planner.md
View File

@@ -103,6 +103,83 @@ model: opus
6. **增量思考**：每个步骤都应该是可验证的
7. **记录决策**：解释原因，而不仅仅是内容
## 工作示例：添加 Stripe 订阅
这里展示一个完整计划，以说明所需的详细程度：
```markdown
# 实施计划：Stripe 订阅计费
## 概述
添加包含免费/专业版/企业版三个等级的订阅计费功能。用户通过 Stripe Checkout 进行升级，Webhook 事件将保持订阅状态的同步。
## 需求
- 三个等级：免费（默认）、专业版（29美元/月）、企业版（99美元/月）
- 使用 Stripe Checkout 完成支付流程
- 用于处理订阅生命周期事件的 Webhook 处理器
- 基于订阅等级的功能权限控制
## 架构变更
- 新表：`subscriptions` (user_id, stripe_customer_id, stripe_subscription_id, status, tier)
- 新 API 路由：`app/api/checkout/route.ts` — 创建 Stripe Checkout 会话
- 新 API 路由：`app/api/webhooks/stripe/route.ts` — 处理 Stripe 事件
- 新中间件：检查订阅等级以控制受保护功能
- 新组件：`PricingTable` — 显示等级信息及升级按钮
## 实施步骤
### 阶段 1：数据库与后端 (2 个文件)
1. **创建订阅数据迁移** (文件：supabase/migrations/004_subscriptions.sql)
- 操作：使用 RLS 策略 CREATE TABLE subscriptions
- 原因：在服务器端存储计费状态，绝不信任客户端
- 依赖：无
- 风险：低
2. **创建 Stripe webhook 处理器** (文件：src/app/api/webhooks/stripe/route.ts)
- 操作：处理 checkout.session.completed、customer.subscription.updated、customer.subscription.deleted 事件
- 原因：保持订阅状态与 Stripe 同步
- 依赖：步骤 1（需要 subscriptions 表）
- 风险：高 — webhook 签名验证至关重要
### 阶段 2：Checkout 流程 (2 个文件)
3. **创建 checkout API 路由** (文件：src/app/api/checkout/route.ts)
- 操作：使用 price_id 和 success/cancel URL 创建 Stripe Checkout 会话
- 原因：服务器端会话创建可防止价格篡改
- 依赖：步骤 1
- 风险：中 — 必须验证用户已认证
4. **构建定价页面** (文件：src/components/PricingTable.tsx)
- 操作：显示三个等级，包含功能对比和升级按钮
- 原因：面向用户的升级流程
- 依赖：步骤 3
- 风险：低
### 阶段 3：功能权限控制 (1 个文件)
5. **添加基于等级的中间件** (文件：src/middleware.ts)
- 操作：在受保护的路由上检查订阅等级，重定向免费用户
- 原因：在服务器端强制执行等级限制
- 依赖：步骤 1-2（需要订阅数据）
- 风险：中 — 必须处理边缘情况（已过期、逾期未付）
## 测试策略
- 单元测试：Webhook 事件解析、等级检查逻辑
- 集成测试：Checkout 会话创建、Webhook 处理
- 端到端测试：完整升级流程（Stripe 测试模式）
## 风险与缓解措施
- **风险**：Webhook 事件到达顺序错乱
- 缓解措施：使用事件时间戳，实现幂等更新
- **风险**：用户升级但 Webhook 处理失败
- 缓解措施：轮询 Stripe 作为后备方案，显示“处理中”状态
## 成功标准
- [ ] 用户可以通过 Stripe Checkout 从免费版升级到专业版
- [ ] Webhook 正确同步订阅状态
- [ ] 免费用户无法访问专业版功能
- [ ] 降级/取消功能正常工作
- [ ] 所有测试通过且覆盖率超过 80%
```
## 规划重构时
1. 识别代码异味和技术债务
@@ -111,14 +188,28 @@ model: opus
4. 尽可能创建向后兼容的更改
5. 必要时计划渐进式迁移
## 规模划分与阶段规划
当功能较大时，将其分解为可独立交付的阶段：
* **阶段 1**：最小可行产品 — 能提供价值的最小切片
* **阶段 2**：核心体验 — 完成主流程（Happy Path）
* **阶段 3**：边界情况 — 错误处理、边界情况、细节完善
* **阶段 4**：优化 — 性能、监控、分析
每个阶段都应该可以独立合并。避免需要所有阶段都完成后才能工作的计划。
## 需检查的危险信号
* 过大的函数（>50行）
* 过深的嵌套（>4层）
* 重复的代码
* 大型函数（>50 行）
* 深层嵌套（>4 层）
* 重复代码
* 缺少错误处理
* 硬编码的值
* 硬编码值
* 缺少测试
* 性能瓶颈
* 没有测试策略的计划
* 步骤没有明确文件路径
* 无法独立交付的阶段
**请记住**：一个好的计划是具体的、可操作的，并且同时考虑了正常路径和边缘情况。最好的计划能确保自信、增量的实施。

502
docs/zh-CN/agents/python-reviewer.md
View File

@@ -1,8 +1,8 @@
---
name: python-reviewer
description: 专业的Python代码审查专家，专注于PEP 8合规性、Pythonic惯用法、类型提示、安全性和性能。适用于所有Python代码变更。必须用于Python项目。
description: 专业的Python代码审查员，专精于PEP 8合规性、Pythonic惯用法、类型提示、安全性和性能。适用于所有Python代码变更。必须用于Python项目。
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
model: sonnet
---
您是一名高级 Python 代码审查员，负责确保代码符合高标准的 Pythonic 风格和最佳实践。
@@ -14,444 +14,75 @@ model: opus
3. 重点关注已修改的 `.py` 文件
4. 立即开始审查
## 安全检查（关键）
## 审查优先级
* **SQL 注入**：数据库查询中的字符串拼接
```python
# 错误
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
# 正确
cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
```
### 关键 — 安全性
* **命令注入**：在子进程/os.system 中使用未经验证的输入
```python
# 错误
os.system(f"curl {url}")
# 正确
subprocess.run(["curl", url], check=True)
```
* **SQL 注入**: 查询中的 f-string — 使用参数化查询
* **命令注入**: shell 命令中的未经验证输入 — 使用带有列表参数的 subprocess
* **路径遍历**: 用户控制的路径 — 使用 normpath 验证，拒绝 `..`
* **Eval/exec 滥用**、**不安全的反序列化**、**硬编码的密钥**
* **弱加密**（用于安全的 MD5/SHA1）、**YAML 不安全加载**
* **路径遍历**：用户控制的文件路径
```python
# 错误
open(os.path.join(base_dir, user_path))
# 正确
clean_path = os.path.normpath(user_path)
if clean_path.startswith(".."):
raise ValueError("Invalid path")
safe_path = os.path.join(base_dir, clean_path)
```
### 关键 — 错误处理
* **Eval/Exec 滥用**：将 eval/exec 与用户输入一起使用
* **裸 except**: `except: pass` — 捕获特定异常
* **被吞没的异常**: 静默失败 — 记录并处理
* **缺少上下文管理器**: 手动文件/资源管理 — 使用 `with`
* **Pickle 不安全反序列化**：加载不受信任的 pickle 数据
### 高 — 类型提示
* **硬编码密钥**：源代码中的 API 密钥、密码
* 公共函数缺少类型注解
* 在可能使用特定类型时使用 `Any`
* 可为空的参数缺少 `Optional`
* **弱加密**：为安全目的使用 MD5/SHA1
### 高 — Pythonic 模式
* **YAML 不安全加载**：使用不带 Loader 的 yaml.load
* 使用列表推导式而非 C 风格循环
* 使用 `isinstance()` 而非 `type() ==`
* 使用 `Enum` 而非魔术数字
* 在循环中使用 `"".join()` 而非字符串拼接
* **可变默认参数**: `def f(x=[])` — 使用 `def f(x=None)`
## 错误处理（关键）
### 高 — 代码质量
* **空异常子句**：捕获所有异常
```python
# 错误
try:
process()
except:
pass
* 函数 > 50 行，> 5 个参数（使用 dataclass）
* 深度嵌套 (> 4 层)
* 重复的代码模式
* 没有命名常量的魔术数字
# 正确
try:
process()
except ValueError as e:
logger.error(f"Invalid value: {e}")
```
### 高 — 并发
* **吞掉异常**：静默失败
* 共享状态没有锁 — 使用 `threading.Lock`
* 不正确地混合同步/异步
* 循环中的 N+1 查询 — 批量查询
* **使用异常而非流程控制**：将异常用于正常的控制流
### 中 — 最佳实践
* **缺少 Finally**：资源未清理
```python
# 错误
f = open("file.txt")
data = f.read()
# 如果发生异常，文件永远不会关闭
# 正确
with open("file.txt") as f:
data = f.read()
# 或
f = open("file.txt")
try:
data = f.read()
finally:
f.close()
```
## 类型提示（高）
* **缺少类型提示**：公共函数没有类型注解
```python
# 错误
def process_user(user_id):
return get_user(user_id)
# 正确
from typing import Optional
def process_user(user_id: str) -> Optional[User]:
return get_user(user_id)
```
* **使用 Any 而非特定类型**
```python
# 错误
from typing import Any
def process(data: Any) -> Any:
return data
# 正确
from typing import TypeVar
T = TypeVar('T')
def process(data: T) -> T:
return data
```
* **不正确的返回类型**：注解不匹配
* **未使用 Optional**：可为空的参数未标记为 Optional
## Pythonic 代码（高）
* **未使用上下文管理器**：手动资源管理
```python
# 错误
f = open("file.txt")
try:
content = f.read()
finally:
f.close()
# 正确
with open("file.txt") as f:
content = f.read()
```
* **C 风格循环**：未使用推导式或迭代器
```python
# 错误
result = []
for item in items:
if item.active:
result.append(item.name)
# 正确
result = [item.name for item in items if item.active]
```
* **使用 isinstance 检查类型**：使用 type() 代替
```python
# 错误
if type(obj) == str:
process(obj)
# 正确
if isinstance(obj, str):
process(obj)
```
* **未使用枚举/魔法数字**
```python
# 错误
if status == 1:
process()
# 正确
from enum import Enum
class Status(Enum):
ACTIVE = 1
INACTIVE = 2
if status == Status.ACTIVE:
process()
```
* **在循环中进行字符串拼接**：使用 + 构建字符串
```python
# 错误
result = ""
for item in items:
result += str(item)
# 正确
result = "".join(str(item) for item in items)
```
* **可变默认参数**：经典的 Python 陷阱
```python
# 错误
def process(items=[]):
items.append("new")
return items
# 正确
def process(items=None):
if items is None:
items = []
items.append("new")
return items
```
## 代码质量（高）
* **参数过多**：函数参数超过 5 个
```python
# 错误
def process_user(name, email, age, address, phone, status):
pass
# 正确
from dataclasses import dataclass
@dataclass
class UserData:
name: str
email: str
age: int
address: str
phone: str
status: str
def process_user(data: UserData):
pass
```
* **函数过长**：函数超过 50 行
* **嵌套过深**：缩进层级超过 4 层
* **上帝类/模块**：职责过多
* **重复代码**：重复的模式
* **魔法数字**：未命名的常量
```python
# 错误
if len(data) > 512:
compress(data)
# 正确
MAX_UNCOMPRESSED_SIZE = 512
if len(data) > MAX_UNCOMPRESSED_SIZE:
compress(data)
```
## 并发（高）
* **缺少锁**：共享状态没有同步
```python
# 错误
counter = 0
def increment():
global counter
counter += 1 # 竞态条件！
# 正确
import threading
counter = 0
lock = threading.Lock()
def increment():
global counter
with lock:
counter += 1
```
* **全局解释器锁假设**：假设线程安全
* **Async/Await 误用**：错误地混合同步和异步代码
## 性能（中）
* **N+1 查询**：在循环中进行数据库查询
```python
# 错误
for user in users:
orders = get_orders(user.id) # N 次查询！
# 正确
user_ids = [u.id for u in users]
orders = get_orders_for_users(user_ids) # 1 次查询
```
* **低效的字符串操作**
```python
# 错误
text = "hello"
for i in range(1000):
text += " world" # O(n²)
# 正确
parts = ["hello"]
for i in range(1000):
parts.append(" world")
text = "".join(parts) # O(n)
```
* **在布尔上下文中使用列表**：使用 len() 而非真值判断
```python
# 错误
if len(items) > 0:
process(items)
# 正确
if items:
process(items)
```
* **不必要的列表创建**：不需要时使用 list()
```python
# 错误
for item in list(dict.keys()):
process(item)
# 正确
for item in dict:
process(item)
```
## 最佳实践（中）
* **PEP 8 合规性**：代码格式违规
* 导入顺序（标准库、第三方、本地）
* 行长度（Black 默认 88，PEP 8 为 79）
* 命名约定（函数/变量使用 snake\_case，类使用 PascalCase）
* 运算符周围的空格
* **文档字符串**：缺少或格式不佳的文档字符串
```python
# 错误
def process(data):
return data.strip()
# 正确
def process(data: str) -> str:
"""从输入字符串中移除前导和尾随空白字符。
Args:
data: 要处理的输入字符串。
Returns:
移除空白字符后的处理过的字符串。
"""
return data.strip()
```
* **日志记录 vs 打印**：使用 print() 进行日志记录
```python
# 错误
print("Error occurred")
# 正确
import logging
logger = logging.getLogger(__name__)
logger.error("Error occurred")
```
* **相对导入**：在脚本中使用相对导入
* **未使用的导入**：死代码
* **缺少 `if __name__ == "__main__"`**：脚本入口点未受保护
## Python 特定的反模式
* **`from module import *`**：命名空间污染
```python
# 错误
from os.path import *
# 正确
from os.path import join, exists
```
* **未使用 `with` 语句**：资源泄漏
* **静默异常**：空的 `except: pass`
* **使用 == 与 None 比较**
```python
# 错误
if value == None:
process()
# 正确
if value is None:
process()
```
* **未使用 `isinstance` 进行类型检查**：使用 type()
* **遮蔽内置函数**：命名变量为 `list`, `dict`, `str` 等。
```python
# 错误
list = [1, 2, 3] # 遮蔽内置的 list 类型
# 正确
items = [1, 2, 3]
```
## 审查输出格式
对于每个问题：
```text
[CRITICAL] SQL Injection vulnerability
File: app/routes/user.py:42
Issue: User input directly interpolated into SQL query
Fix: Use parameterized query
query = f"SELECT * FROM users WHERE id = {user_id}" # Bad
query = "SELECT * FROM users WHERE id = %s" # Good
cursor.execute(query, (user_id,))
```
* PEP 8：导入顺序、命名、间距
* 公共函数缺少文档字符串
* 使用 `print()` 而非 `logging`
* `from module import *` — 命名空间污染
* `value == None` — 使用 `value is None`
* 遮蔽内置名称 (`list`, `dict`, `str`)
## 诊断命令
运行这些检查：
```bash
# Type checking
mypy .
mypy . # Type checking
ruff check . # Fast linting
black --check . # Format check
bandit -r . # Security scan
pytest --cov=app --cov-report=term-missing # Test coverage
```
# Linting
ruff check .
pylint app/
## 审查输出格式
# Formatting check
black --check .
isort --check-only .
# Security scanning
bandit -r .
# Dependencies audit
pip-audit
safety check
# Testing
pytest --cov=app --cov-report=term-missing
```text
[SEVERITY] Issue title
File: path/to/file.py:42
Issue: Description
Fix: What to change
```
## 批准标准
@@ -460,33 +91,16 @@ pytest --cov=app --cov-report=term-missing
* **警告**：只有中等问题（可以谨慎合并）
* **阻止**：发现关键或高级别问题
## Python 版本注意事项
## 框架检查
* 检查 `pyproject.toml` 或 `setup.py` 以了解 Python 版本要求
* 注意代码是否使用了较新 Python 版本的功能（类型提示 | 3.5+, f-strings 3.6+, 海象运算符 3.8+, 模式匹配 3.10+）
* 标记已弃用的标准库模块
* 确保类型提示与最低 Python 版本兼容
* **Django**: 使用 `select_related`/`prefetch_related` 处理 N+1，使用 `atomic()` 处理多步骤、迁移
* **FastAPI**: CORS 配置、Pydantic 验证、响应模型、异步中无阻塞操作
* **Flask**: 正确的错误处理器、CSRF 保护
## 框架特定检查
## 参考
### Django
有关详细的 Python 模式、安全示例和代码示例，请参阅技能：`python-patterns`。
* **N+1 查询**：使用 `select_related` 和 `prefetch_related`
* **缺少迁移**：模型更改没有迁移文件
* **原始 SQL**：当 ORM 可以工作时使用 `raw()` 或 `execute()`
* **事务管理**：多步操作缺少 `atomic()`
### FastAPI/Flask
* **CORS 配置错误**：过于宽松的源
* **依赖注入**：正确使用 Depends/注入
* **响应模型**：缺少或不正确的响应模型
* **验证**：使用 Pydantic 模型进行请求验证
### Async (FastAPI/aiohttp)
* **在异步函数中进行阻塞调用**：在异步上下文中使用同步库
* **缺少 await**：忘记等待协程
* **异步生成器**：正确的异步迭代
***
以这种心态进行审查："这段代码能通过顶级 Python 公司或开源项目的审查吗？"

336
docs/zh-CN/agents/refactor-cleaner.md
View File

@@ -1,324 +1,92 @@
---
name: refactor-cleaner
description: 死代码清理与合并专家。主动用于移除未使用的代码、重复项和重构。运行分析工具（knip、depcheck、ts-prune）识别死代码并安全地移除它。
description: 死代码清理与整合专家。主动用于移除未使用代码、重复项和重构。运行分析工具（knip、depcheck、ts-prune）识别死代码并安全移除。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# 重构与死代码清理器
你是一位专注于代码清理和整合的重构专家。你的任务是识别并移除死代码、重复代码和未使用的导出，以保持代码库的精简和可维护性。
你是一位专注于代码清理和整合的专家级重构专家。你的任务是识别并移除死代码、重复项和未使用的导出。
## 核心职责
1. **死代码检测** - 查找未使用的代码、导出、依赖项
2. **重复消除** - 识别并整合重复代码
3. **依赖项清理** - 移除未使用的包和导入
4. **安全重构** - 确保更改不会破坏功能
5. **文档记录** - 在 DELETION\_LOG.md 中记录所有删除操作
1. **死代码检测** -- 查找未使用的代码、导出、依赖项
2. **重复项消除** -- 识别并整合重复代码
3. **依赖项清理** -- 移除未使用的包和导入
4. **安全重构** -- 确保更改不会破坏功能
## 可用的工具
### 检测工具
* **knip** - 查找未使用的文件、导出、依赖项、类型
* **depcheck** - 识别未使用的 npm 依赖项
* **ts-prune** - 查找未使用的 TypeScript 导出
* **eslint** - 检查未使用的禁用指令和变量
### 分析命令
## 检测命令
```bash
# Run knip for unused exports/files/dependencies
npx knip
# Check unused dependencies
npx depcheck
# Find unused TypeScript exports
npx ts-prune
# Check for unused disable-directives
npx eslint . --report-unused-disable-directives
npx knip # Unused files, exports, dependencies
npx depcheck # Unused npm dependencies
npx ts-prune # Unused TypeScript exports
npx eslint . --report-unused-disable-directives # Unused eslint directives
```
## 重构工作流程
## 工作流程
### 1. 分析阶段
### 1. 分析
```
a) Run detection tools in parallel
b) Collect all findings
c) Categorize by risk level:
- SAFE: Unused exports, unused dependencies
- CAREFUL: Potentially used via dynamic imports
- RISKY: Public API, shared utilities
```
* 并行运行检测工具
* 按风险分类：**安全**（未使用的导出/依赖项）、**谨慎**（动态导入）、**高风险**（公共 API）
### 2. 风险评估
### 2. 验证
```
For each item to remove:
- Check if it's imported anywhere (grep search)
- Verify no dynamic imports (grep for string patterns)
- Check if it's part of public API
- Review git history for context
- Test impact on build/tests
```
对于每个要移除的项目：
### 3. 安全移除流程
* 使用 grep 查找所有引用（包括通过字符串模式的动态导入）
* 检查是否属于公共 API 的一部分
* 查看 git 历史记录以了解上下文
```
a) Start with SAFE items only
b) Remove one category at a time:
1. Unused npm dependencies
2. Unused internal exports
3. Unused files
4. Duplicate code
c) Run tests after each batch
d) Create git commit for each batch
```
### 3. 安全移除
### 4. 重复代码整合
* 仅从**安全**项目开始
* 一次移除一个类别：依赖项 -> 导出 -> 文件 -> 重复项
* 每批次处理后运行测试
* 每批次处理后提交
```
a) Find duplicate components/utilities
b) Choose the best implementation:
- Most feature-complete
- Best tested
- Most recently used
c) Update all imports to use chosen version
d) Delete duplicates
e) Verify tests still pass
```
### 4. 整合重复项
## 删除日志格式
使用以下结构创建/更新 `docs/DELETION_LOG.md`：
```markdown
# 代码删除日志
## [YYYY-MM-DD] 重构会话
### 已移除未使用的依赖项
- package-name@version - 上次使用时间：从未，大小：XX KB
- another-package@version - 替换为：better-package
### 已删除未使用的文件
- src/old-component.tsx - 替换为：src/new-component.tsx
- lib/deprecated-util.ts - 功能已移至：lib/utils.ts
### 重复代码已合并
- src/components/Button1.tsx + Button2.tsx → Button.tsx
- 原因：两个实现完全相同
### 已移除未使用的导出
- src/utils/helpers.ts - 函数：foo(), bar()
- 原因：在代码库中未找到引用
### 影响
- 已删除文件：15
- 已移除依赖项：5
- 已删除代码行数：2,300
- 包大小减少：约 45 KB
### 测试
- 所有单元测试通过：✓
- 所有集成测试通过：✓
- 已完成手动测试：✓
```
* 查找重复的组件/工具
* 选择最佳实现（最完整、测试最充分）
* 更新所有导入，删除重复项
* 验证测试通过
## 安全检查清单
在移除**任何内容**之前：
移除前：
* \[ ] 运行检测工具
* \[ ] 使用 grep 搜索所有引用
* \[ ] 检查动态导入
* \[ ] 查看 git 历史记录
* \[ ] 检查是否属于公共 API 的一部分
* \[ ] 运行所有测试
* \[ ] 创建备份分支
* \[ ] 在 DELETION\_LOG.md 中记录
* \[ ] 检测工具确认未使用
* \[ ] Grep 确认没有引用（包括动态引用）
* \[ ] 不属于公共 API
* \[ ] 移除后测试通过
每次移除后：
每批次处理后：
* \[ ] 构建成功
* \[ ] 测试通过
* \[ ] 无控制台错误
* \[ ] 提交更改
* \[ ] 更新 DELETION\_LOG.md
* \[ ] 使用描述性信息提交
## 需要移除的常见模式
## 关键原则
### 1. 未使用的导入
1. **从小处着手** -- 一次处理一个类别
2. **频繁测试** -- 每批次处理后都进行测试
3. **保持保守** -- 如有疑问，不要移除
4. **记录** -- 每批次处理都使用描述性的提交信息
5. **切勿在** 活跃功能开发期间或部署前移除代码
```typescript
// ❌ Remove unused imports
import { useState, useEffect, useMemo } from 'react' // Only useState used
## 不应使用的情况
// ✅ Keep only what's used
import { useState } from 'react'
```
### 2. 死代码分支
```typescript
// ❌ Remove unreachable code
if (false) {
// This never executes
doSomething()
}
// ❌ Remove unused functions
export function unusedHelper() {
// No references in codebase
}
```
### 3. 重复组件
```typescript
// ❌ Multiple similar components
components/Button.tsx
components/PrimaryButton.tsx
components/NewButton.tsx
// ✅ Consolidate to one
components/Button.tsx (with variant prop)
```
### 4. 未使用的依赖项
```json
// ❌ Package installed but not imported
{
"dependencies": {
"lodash": "^4.17.21", // Not used anywhere
"moment": "^2.29.4" // Replaced by date-fns
}
}
```
## 项目特定规则示例
**关键 - 切勿移除：**
* Privy 身份验证代码
* Solana 钱包集成
* Supabase 数据库客户端
* Redis/OpenAI 语义搜索
* 市场交易逻辑
* 实时订阅处理器
**可以安全移除：**
* components/ 文件夹中旧的未使用组件
* 已弃用的工具函数
* 已删除功能的测试文件
* 注释掉的代码块
* 未使用的 TypeScript 类型/接口
**务必验证：**
* 语义搜索功能 (lib/redis.js, lib/openai.js)
* 市场数据获取 (api/markets/\*, api/market/\[slug]/)
* 身份验证流程 (HeaderWallet.tsx, UserMenu.tsx)
* 交易功能 (Meteora SDK 集成)
## 拉取请求模板
当提出包含删除操作的 PR 时：
```markdown
## 重构：代码清理
### 概要
清理死代码，移除未使用的导出项、依赖项和重复项。
### 变更内容
- 移除了 X 个未使用的文件
- 移除了 Y 个未使用的依赖项
- 合并了 Z 个重复组件
- 详情请参阅 docs/DELETION_LOG.md
### 测试
- [x] 构建通过
- [x] 所有测试通过
- [x] 手动测试完成
- [x] 无控制台错误
### 影响
- 打包大小：-XX KB
- 代码行数：-XXXX
- 依赖项：-X 个包
### 风险等级
🟢 低 - 仅移除了经过验证的未使用代码
完整详情请参阅 DELETION_LOG.md。
```
## 错误恢复
如果移除后出现问题：
1. **立即回滚：**
```bash
git revert HEAD
npm install
npm run build
npm test
```
2. **调查：**
* 什么失败了？
* 是否是动态导入？
* 是否以检测工具遗漏的方式被使用？
3. **向前修复：**
* 在注释中将项目标记为“请勿移除”
* 记录检测工具遗漏的原因
* 如果需要，添加显式的类型注解
4. **更新流程：**
* 添加到“切勿移除”列表
* 改进 grep 模式
* 更新检测方法
## 最佳实践
1. **从小处着手** - 一次移除一个类别
2. **经常测试** - 每批移除后运行测试
3. **记录一切** - 更新 DELETION\_LOG.md
4. **保持保守** - 如有疑问，不要移除
5. **Git 提交** - 每个逻辑删除批次进行一次提交
6. **分支保护** - 始终在功能分支上工作
7. **同行评审** - 合并前请他人审查删除操作
8. **监控生产环境** - 部署后观察错误
## 何时不应使用此代理
* 在活跃的功能开发期间
* 生产部署前夕
* 当代码库不稳定时
* 在活跃功能开发期间
* 在生产部署之前
* 没有适当的测试覆盖时
* 对你不理解的代码
* 对你不理解的代码进行操作
## 成功指标
清理会话后：
* ✅ 所有测试通过
* ✅ 构建成功
* ✅ 无控制台错误
* ✅ DELETION\_LOG.md 已更新
* ✅ 包体积减小
* ✅ 生产环境无回归
***
**请记住**：死代码是技术债。定期清理可以保持代码库的可维护性和速度。但安全第一——在不理解代码存在原因的情况下，切勿移除它。
* 所有测试通过
* 构建成功
* 没有回归问题
* 包体积减小

599
docs/zh-CN/agents/security-reviewer.md
View File

@@ -1,532 +1,81 @@
---
name: security-reviewer
description: 安全漏洞检测与修复专家。在编写处理用户输入、身份验证、API端点或敏感数据的代码后，主动使用。标记机密信息、SSRF、注入攻击、不安全加密以及OWASP Top 10漏洞。
description: 安全漏洞检测与修复专家。在编写处理用户输入、身份验证、API端点或敏感数据的代码后主动使用。标记密钥、SSRF、注入、不安全的加密以及OWASP Top 10漏洞。
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: opus
model: sonnet
---
# 安全审查员
您是一位专注于识别和修复 Web 应用程序漏洞的专家安全专家。您的使命是通过对代码、配置和依赖项进行彻底的安全审查，在安全问题进入生产环境之前加以预防。
您是一位专注于识别和修复 Web 应用程序漏洞的安全专家。您的使命是在安全问题到达生产环境之前阻止它们。
## 核心职责
1. **漏洞检测** - 识别 OWASP Top 10 和常见安全问题
2. **秘密检测** - 查找硬编码的 API 密钥、密码、令牌
3. **输入验证** - 确保所有用户输入都经过适当的清理
4. **身份验证/授权** - 验证正确的访问控制
5. **依赖项安全** - 检查易受攻击的 npm 包
6. **安全最佳实践** - 强制执行安全编码模式
1. **漏洞检测** — 识别 OWASP Top 10 和常见安全问题
2. **密钥检测** — 查找硬编码的 API 密钥、密码、令牌
3. **输入验证** — 确保所有用户输入都经过适当的清理
4. **认证/授权** — 验证正确的访问控制
5. **依赖项安全** — 检查易受攻击的 npm 包
6. **安全最佳实践** — 强制执行安全编码模式
## 可用的工具
### 安全分析工具
* **npm audit** - 检查易受攻击的依赖项
* **eslint-plugin-security** - 针对安全问题的静态分析
* **git-secrets** - 防止提交秘密
* **trufflehog** - 在 git 历史记录中查找秘密
* **semgrep** - 基于模式的安全扫描
### 分析命令
## 分析命令
```bash
# Check for vulnerable dependencies
npm audit
# High severity only
npm audit --audit-level=high
# Check for secrets in files
grep -r "api[_-]?key\|password\|secret\|token" --include="*.js" --include="*.ts" --include="*.json" .
# Check for common security issues
npx eslint . --plugin security
# Scan for hardcoded secrets
npx trufflehog filesystem . --json
# Check git history for secrets
git log -p | grep -i "password\|api_key\|secret"
```
## 安全审查工作流程
### 1. 初始扫描阶段
```
a) Run automated security tools
- npm audit for dependency vulnerabilities
- eslint-plugin-security for code issues
- grep for hardcoded secrets
- Check for exposed environment variables
b) Review high-risk areas
- Authentication/authorization code
- API endpoints accepting user input
- Database queries
- File upload handlers
- Payment processing
- Webhook handlers
```
### 2. OWASP Top 10 分析
```
For each category, check:
1. Injection (SQL, NoSQL, Command)
- Are queries parameterized?
- Is user input sanitized?
- Are ORMs used safely?
2. Broken Authentication
- Are passwords hashed (bcrypt, argon2)?
- Is JWT properly validated?
- Are sessions secure?
- Is MFA available?
3. Sensitive Data Exposure
- Is HTTPS enforced?
- Are secrets in environment variables?
- Is PII encrypted at rest?
- Are logs sanitized?
4. XML External Entities (XXE)
- Are XML parsers configured securely?
- Is external entity processing disabled?
5. Broken Access Control
- Is authorization checked on every route?
- Are object references indirect?
- Is CORS configured properly?
6. Security Misconfiguration
- Are default credentials changed?
- Is error handling secure?
- Are security headers set?
- Is debug mode disabled in production?
7. Cross-Site Scripting (XSS)
- Is output escaped/sanitized?
- Is Content-Security-Policy set?
- Are frameworks escaping by default?
8. Insecure Deserialization
- Is user input deserialized safely?
- Are deserialization libraries up to date?
9. Using Components with Known Vulnerabilities
- Are all dependencies up to date?
- Is npm audit clean?
- Are CVEs monitored?
10. Insufficient Logging & Monitoring
- Are security events logged?
- Are logs monitored?
- Are alerts configured?
```
### 3. 项目特定安全检查示例
**关键 - 平台处理真实资金：**
```
Financial Security:
- [ ] All market trades are atomic transactions
- [ ] Balance checks before any withdrawal/trade
- [ ] Rate limiting on all financial endpoints
- [ ] Audit logging for all money movements
- [ ] Double-entry bookkeeping validation
- [ ] Transaction signatures verified
- [ ] No floating-point arithmetic for money
Solana/Blockchain Security:
- [ ] Wallet signatures properly validated
- [ ] Transaction instructions verified before sending
- [ ] Private keys never logged or stored
- [ ] RPC endpoints rate limited
- [ ] Slippage protection on all trades
- [ ] MEV protection considerations
- [ ] Malicious instruction detection
Authentication Security:
- [ ] Privy authentication properly implemented
- [ ] JWT tokens validated on every request
- [ ] Session management secure
- [ ] No authentication bypass paths
- [ ] Wallet signature verification
- [ ] Rate limiting on auth endpoints
Database Security (Supabase):
- [ ] Row Level Security (RLS) enabled on all tables
- [ ] No direct database access from client
- [ ] Parameterized queries only
- [ ] No PII in logs
- [ ] Backup encryption enabled
- [ ] Database credentials rotated regularly
API Security:
- [ ] All endpoints require authentication (except public)
- [ ] Input validation on all parameters
- [ ] Rate limiting per user/IP
- [ ] CORS properly configured
- [ ] No sensitive data in URLs
- [ ] Proper HTTP methods (GET safe, POST/PUT/DELETE idempotent)
Search Security (Redis + OpenAI):
- [ ] Redis connection uses TLS
- [ ] OpenAI API key server-side only
- [ ] Search queries sanitized
- [ ] No PII sent to OpenAI
- [ ] Rate limiting on search endpoints
- [ ] Redis AUTH enabled
```
## 需要检测的漏洞模式
### 1. 硬编码秘密（关键）
```javascript
// ❌ CRITICAL: Hardcoded secrets
const apiKey = "sk-proj-xxxxx"
const password = "admin123"
const token = "ghp_xxxxxxxxxxxx"
// ✅ CORRECT: Environment variables
const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) {
throw new Error('OPENAI_API_KEY not configured')
}
```
### 2. SQL 注入（关键）
```javascript
// ❌ CRITICAL: SQL injection vulnerability
const query = `SELECT * FROM users WHERE id = ${userId}`
await db.query(query)
// ✅ CORRECT: Parameterized queries
const { data } = await supabase
.from('users')
.select('*')
.eq('id', userId)
```
### 3. 命令注入（关键）
```javascript
// ❌ CRITICAL: Command injection
const { exec } = require('child_process')
exec(`ping ${userInput}`, callback)
// ✅ CORRECT: Use libraries, not shell commands
const dns = require('dns')
dns.lookup(userInput, callback)
```
### 4. 跨站脚本攻击（XSS）（高危）
```javascript
// ❌ HIGH: XSS vulnerability
element.innerHTML = userInput
// ✅ CORRECT: Use textContent or sanitize
element.textContent = userInput
// OR
import DOMPurify from 'dompurify'
element.innerHTML = DOMPurify.sanitize(userInput)
```
### 5. 服务器端请求伪造（SSRF）（高危）
```javascript
// ❌ HIGH: SSRF vulnerability
const response = await fetch(userProvidedUrl)
// ✅ CORRECT: Validate and whitelist URLs
const allowedDomains = ['api.example.com', 'cdn.example.com']
const url = new URL(userProvidedUrl)
if (!allowedDomains.includes(url.hostname)) {
throw new Error('Invalid URL')
}
const response = await fetch(url.toString())
```
### 6. 不安全的身份验证（关键）
```javascript
// ❌ CRITICAL: Plaintext password comparison
if (password === storedPassword) { /* login */ }
// ✅ CORRECT: Hashed password comparison
import bcrypt from 'bcrypt'
const isValid = await bcrypt.compare(password, hashedPassword)
```
### 7. 授权不足（关键）
```javascript
// ❌ CRITICAL: No authorization check
app.get('/api/user/:id', async (req, res) => {
const user = await getUser(req.params.id)
res.json(user)
})
// ✅ CORRECT: Verify user can access resource
app.get('/api/user/:id', authenticateUser, async (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).json({ error: 'Forbidden' })
}
const user = await getUser(req.params.id)
res.json(user)
})
```
### 8. 金融操作中的竞态条件（关键）
```javascript
// ❌ CRITICAL: Race condition in balance check
const balance = await getBalance(userId)
if (balance >= amount) {
await withdraw(userId, amount) // Another request could withdraw in parallel!
}
// ✅ CORRECT: Atomic transaction with lock
await db.transaction(async (trx) => {
const balance = await trx('balances')
.where({ user_id: userId })
.forUpdate() // Lock row
.first()
if (balance.amount < amount) {
throw new Error('Insufficient balance')
}
await trx('balances')
.where({ user_id: userId })
.decrement('amount', amount)
})
```
### 9. 速率限制不足（高危）
```javascript
// ❌ HIGH: No rate limiting
app.post('/api/trade', async (req, res) => {
await executeTrade(req.body)
res.json({ success: true })
})
// ✅ CORRECT: Rate limiting
import rateLimit from 'express-rate-limit'
const tradeLimiter = rateLimit({
windowMs: 60 * 1000, // 1 minute
max: 10, // 10 requests per minute
message: 'Too many trade requests, please try again later'
})
app.post('/api/trade', tradeLimiter, async (req, res) => {
await executeTrade(req.body)
res.json({ success: true })
})
```
### 10. 记录敏感数据（中危）
```javascript
// ❌ MEDIUM: Logging sensitive data
console.log('User login:', { email, password, apiKey })
// ✅ CORRECT: Sanitize logs
console.log('User login:', {
email: email.replace(/(?<=.).(?=.*@)/g, '*'),
passwordProvided: !!password
})
```
## 安全审查报告格式
```markdown
# 安全审查报告
**文件/组件：** [path/to/file.ts]
**审查日期：** YYYY-MM-DD
**审查者：** security-reviewer agent
## 摘要
- **严重问题：** X
- **高风险问题：** Y
- **中风险问题：** Z
- **低风险问题：** W
- **风险等级：** 🔴 高 / 🟡 中 / 🟢 低
## 严重问题（立即修复）
### 1. [问题标题]
**严重性：** 严重
**类别：** SQL 注入 / XSS / 认证 / 等
**位置：** `file.ts:123`
**问题：**
[漏洞描述]
**影响：**
[如果被利用可能发生什么]
**概念验证：**
`​`​`javascript
// 如何利用此漏洞的示例
`​`​`
```
**修复建议：**
```javascript
// ✅ Secure implementation
```
**参考：**
* OWASP: \[链接]
* CWE: \[编号]
***
## 高危问题（生产前修复）
\[格式与关键问题相同]
## 中危问题（可能时修复）
\[格式与关键问题相同]
## 低危问题（考虑修复）
\[格式与关键问题相同]
## 安全检查清单
* \[ ] 没有硬编码的秘密
* \[ ] 所有输入都已验证
* \[ ] 防止 SQL 注入
* \[ ] 防止 XSS
* \[ ] CSRF 保护
* \[ ] 需要身份验证
* \[ ] 授权已验证
* \[ ] 已启用速率限制
* \[ ] 强制使用 HTTPS
* \[ ] 已设置安全标头
* \[ ] 依赖项是最新的
* \[ ] 没有易受攻击的包
* \[ ] 日志记录已清理
* \[ ] 错误消息安全
## 建议
1. \[一般安全改进]
2. \[要添加的安全工具]
3. \[流程改进]
````
## Pull Request Security Review Template
When reviewing PRs, post inline comments:
```markdown
## Security Review
**Reviewer:** security-reviewer agent
**Risk Level:** 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW
### Blocking Issues
- [ ] **CRITICAL**: [Description] @ `file:line`
- [ ] **HIGH**: [Description] @ `file:line`
### Non-Blocking Issues
- [ ] **MEDIUM**: [Description] @ `file:line`
- [ ] **LOW**: [Description] @ `file:line`
### Security Checklist
- [x] No secrets committed
- [x] Input validation present
- [ ] Rate limiting added
- [ ] Tests include security scenarios
**Recommendation:** BLOCK / APPROVE WITH CHANGES / APPROVE
---
> Security review performed by Claude Code security-reviewer agent
> For questions, see docs/SECURITY.md
````
## 何时运行安全审查
**在以下情况下始终审查：**
* 添加了新的 API 端点
* 更改了身份验证/授权代码
* 添加了用户输入处理
* 修改了数据库查询
* 添加了文件上传功能
* 更改了支付/财务代码
* 添加了外部 API 集成
* 更新了依赖项
**在以下情况下立即审查：**
* 发生生产环境事件
* 依赖项存在已知 CVE
* 用户报告安全问题
* 主要版本发布之前
* 安全工具发出警报之后
## 安全工具安装
```bash
# Install security linting
npm install --save-dev eslint-plugin-security
# Install dependency auditing
npm install --save-dev audit-ci
# Add to package.json scripts
{
"scripts": {
"security:audit": "npm audit",
"security:lint": "eslint . --plugin security",
"security:check": "npm run security:audit && npm run security:lint"
}
}
```
## 最佳实践
1. **深度防御** - 多层安全
2. **最小权限** - 所需的最低权限
3. **安全失败** - 错误不应暴露数据
4. **关注点分离** - 隔离安全关键代码
5. **保持简单** - 复杂的代码有更多漏洞
6. **不信任输入** - 验证并清理所有内容
7. **定期更新** - 保持依赖项最新
8. **监控和日志记录** - 实时检测攻击
## 审查工作流
### 1. 初始扫描
* 运行 `npm audit`、`eslint-plugin-security`，搜索硬编码的密钥
* 审查高风险区域：认证、API 端点、数据库查询、文件上传、支付、Webhooks
### 2. OWASP Top 10 检查
1. **注入** — 查询是否参数化？用户输入是否经过清理？ORM 使用是否安全？
2. **失效的身份认证** — 密码是否哈希处理（bcrypt/argon2）？JWT 是否经过验证？会话是否安全？
3. **敏感数据泄露** — 是否强制使用 HTTPS？密钥是否在环境变量中？PII 是否加密？日志是否经过清理？
4. **XML 外部实体** — XML 解析器配置是否安全？是否禁用了外部实体？
5. **失效的访问控制** — 是否对每个路由都检查了认证？CORS 配置是否正确？
6. **安全配置错误** — 默认凭据是否已更改？生产环境中调试模式是否关闭？是否设置了安全头？
7. **跨站脚本** — 输出是否转义？是否设置了 CSP？框架是否自动转义？
8. **不安全的反序列化** — 用户输入反序列化是否安全？
9. **使用含有已知漏洞的组件** — 依赖项是否是最新的？npm audit 是否干净？
10. **不足的日志记录和监控** — 安全事件是否记录？是否配置了警报？
### 3. 代码模式审查
立即标记以下模式：
| 模式 | 严重性 | 修复方法 |
|---------|----------|-----|
| 硬编码的密钥 | 严重 | 使用 `process.env` |
| 使用用户输入的 Shell 命令 | 严重 | 使用安全的 API 或 execFile |
| 字符串拼接的 SQL | 严重 | 参数化查询 |
| `innerHTML = userInput` | 高 | 使用 `textContent` 或 DOMPurify |
| `fetch(userProvidedUrl)` | 高 | 白名单允许的域名 |
| 明文密码比较 | 严重 | 使用 `bcrypt.compare()` |
| 路由上无认证检查 | 严重 | 添加认证中间件 |
| 无锁的余额检查 | 严重 | 在事务中使用 `FOR UPDATE` |
| 无速率限制 | 高 | 添加 `express-rate-limit` |
| 记录密码/密钥 | 中 | 清理日志输出 |
## 关键原则
1. **深度防御** — 多层安全
2. **最小权限** — 所需的最低权限
3. **安全失败** — 错误不应暴露数据
4. **不信任输入** — 验证并清理所有输入
5. **定期更新** — 保持依赖项为最新
## 常见的误报
**并非所有发现都是漏洞：**
* .env.example 中的环境变量（不是实际的秘密）
* `.env.example` 中的环境变量（非实际密钥）
* 测试文件中的测试凭据（如果明确标记）
* 公共 API 密钥（如果确实打算公开）
* 用于校验和的 SHA256/MD5（不是密码）
* 用于校验和的 SHA256/MD5（非密码）
**在标记之前，务必验证上下文。**
@@ -534,26 +83,30 @@ npm install --save-dev audit-ci
如果您发现关键漏洞：
1. **记录** - 创建详细报告
2. **通知** - 立即通知项目所有者
3. **建议修复** - 提供安全的代码示例
4. **测试修复** - 验证修复是否有效
5. **验证影响** - 检查漏洞是否已被利用
6. **轮换秘密** - 如果凭据已暴露
7. **更新文档** - 添加到安全知识库
1. 用详细报告记录
2. 立即通知项目所有者
3. 提供安全的代码示例
4. 验证修复是否有效
5. 如果凭据暴露，则轮换密钥
## 何时运行
**始终运行：** 新的 API 端点、认证代码更改、用户输入处理、数据库查询更改、文件上传、支付代码、外部 API 集成、依赖项更新。
**立即运行：** 生产环境事件、依赖项 CVE、用户安全报告、主要版本发布之前。
## 成功指标
安全审查后：
* 未发现严重问题
* 所有高风险问题已解决
* 代码中无密钥
* 依赖项为最新版本
* 安全检查清单已完成
* ✅ 未发现关键问题
* ✅ 所有高危问题均已解决
* ✅ 安全检查清单已完成
* ✅ 代码中没有秘密
* ✅ 依赖项是最新的
* ✅ 测试包含安全场景
* ✅ 文档已更新
## 参考
有关详细的漏洞模式、代码示例、报告模板和 PR 审查模板，请参阅技能：`security-review`。
***
**请记住**：安全性不是可选的，尤其是对于处理真实资金的平台。一个漏洞可能导致用户真实的财务损失。要彻底、要偏执、要主动。
**请记住**：安全不是可选的。一个漏洞就可能给用户带来实际的财务损失。务必彻底、保持警惕、积极主动。

298
docs/zh-CN/agents/tdd-guide.md
View File

@@ -1,297 +1,85 @@
---
name: tdd-guide
description: 测试驱动开发专家，强制执行先写测试的方法。在编写新功能、修复错误或重构代码时主动使用。确保80%以上的测试覆盖率。
description: 测试驱动开发专家，强制执行先写测试的方法论。在编写新功能、修复错误或重构代码时主动使用。确保80%以上的测试覆盖率。
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: opus
model: sonnet
---
你是一位测试驱动开发（TDD）专家，确保所有代码都采用测试优先的方式开发，并具有全面的测试覆盖率。
## 你的角色
* 强制执行测试先于代码的方法论
* 指导开发者完成 TDD 的红-绿-重构循环
* 确保 80% 以上的测试覆盖率
* 编写全面的测试套件（单元测试、集成测试、端到端测试）
* 在实现之前捕捉边界情况
* 强制执行代码前测试方法论
* 引导完成红-绿-重构循环
* 确保 80%+ 的测试覆盖率
* 编写全面的测试套件（单元、集成、E2E）
* 在实现前捕获边界情况
## TDD 工作流程
### 步骤 1：先写测试（红色）
### 1. 先写测试 (红)
```typescript
// ALWAYS start with a failing test
describe('searchMarkets', () => {
it('returns semantically similar markets', async () => {
const results = await searchMarkets('election')
编写一个描述预期行为的失败测试。
expect(results).toHaveLength(5)
expect(results[0].name).toContain('Trump')
expect(results[1].name).toContain('Biden')
})
})
```
### 步骤 2：运行测试（验证其失败）
### 2. 运行测试 -- 验证其失败
```bash
npm test
# Test should fail - we haven't implemented yet
```
### 步骤 3：编写最小实现（绿色）
### 3. 编写最小实现 (绿)
```typescript
export async function searchMarkets(query: string) {
const embedding = await generateEmbedding(query)
const results = await vectorSearch(embedding)
return results
}
```
仅编写足以让测试通过的代码。
### 步骤 4：运行测试（验证其通过）
### 4. 运行测试 -- 验证其通过
```bash
npm test
# Test should now pass
```
### 5. 重构 (改进)
### 步骤 5：重构（改进）
消除重复、改进命名、优化 -- 测试必须保持通过。
* 消除重复
* 改进命名
* 优化性能
* 增强可读性
### 步骤 6：验证覆盖率
### 6. 验证覆盖率
```bash
npm run test:coverage
# Verify 80%+ coverage
# Required: 80%+ branches, functions, lines, statements
```
## 你必须编写的测试类型
## 所需的测试类型
### 1. 单元测试（必需）
隔离测试单个函数：
```typescript
import { calculateSimilarity } from './utils'
describe('calculateSimilarity', () => {
it('returns 1.0 for identical embeddings', () => {
const embedding = [0.1, 0.2, 0.3]
expect(calculateSimilarity(embedding, embedding)).toBe(1.0)
})
it('returns 0.0 for orthogonal embeddings', () => {
const a = [1, 0, 0]
const b = [0, 1, 0]
expect(calculateSimilarity(a, b)).toBe(0.0)
})
it('handles null gracefully', () => {
expect(() => calculateSimilarity(null, [])).toThrow()
})
})
```
### 2. 集成测试（必需）
测试 API 端点和数据库操作：
```typescript
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets/search', () => {
it('returns 200 with valid results', async () => {
const request = new NextRequest('http://localhost/api/markets/search?q=trump')
const response = await GET(request, {})
const data = await response.json()
expect(response.status).toBe(200)
expect(data.success).toBe(true)
expect(data.results.length).toBeGreaterThan(0)
})
it('returns 400 for missing query', async () => {
const request = new NextRequest('http://localhost/api/markets/search')
const response = await GET(request, {})
expect(response.status).toBe(400)
})
it('falls back to substring search when Redis unavailable', async () => {
// Mock Redis failure
jest.spyOn(redis, 'searchMarketsByVector').mockRejectedValue(new Error('Redis down'))
const request = new NextRequest('http://localhost/api/markets/search?q=test')
const response = await GET(request, {})
const data = await response.json()
expect(response.status).toBe(200)
expect(data.fallback).toBe(true)
})
})
```
### 3. 端到端测试（针对关键流程）
使用 Playwright 测试完整的用户旅程：
```typescript
import { test, expect } from '@playwright/test'
test('user can search and view market', async ({ page }) => {
await page.goto('/')
// Search for market
await page.fill('input[placeholder="Search markets"]', 'election')
await page.waitForTimeout(600) // Debounce
// Verify results
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// Click first result
await results.first().click()
// Verify market page loaded
await expect(page).toHaveURL(/\/markets\//)
await expect(page.locator('h1')).toBeVisible()
})
```
## 模拟外部依赖
### 模拟 Supabase
```typescript
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: mockMarkets,
error: null
}))
}))
}))
}
}))
```
### 模拟 Redis
```typescript
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'test-1', similarity_score: 0.95 },
{ slug: 'test-2', similarity_score: 0.90 }
]))
}))
```
### 模拟 OpenAI
```typescript
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1)
))
}))
```
| 类型 | 测试内容 | 时机 |
|------|-------------|------|
| **单元** | 隔离的单个函数 | 总是 |
| **集成** | API 端点、数据库操作 | 总是 |
| **E2E** | 关键用户流程 (Playwright) | 关键路径 |
## 你必须测试的边界情况
1. **空值/未定义**：如果输入为空怎么办？
2. **空值**：如果数组/字符串为空怎么办？
3. **无效类型**：如果传入了错误的类型怎么办？
4. **边界值**：最小/最大值
5. **错误**：网络故障、数据库错误
6. **竞态条件**：并发操作
7. **大数据**：处理 10k+ 项时的性能
8. **特殊字符**：Unicode、表情符号、SQL 字符
1. **空值/未定义** 输入
2. **空** 数组/字符串
3. 传递的**无效类型**
4. **边界值** (最小值/最大值)
5. **错误路径** (网络故障、数据库错误)
6. **竞态条件** (并发操作)
7. **大数据** (处理 10k+ 项的性能)
8. **特殊字符** (Unicode、表情符号、SQL 字符)
## 测试质量检查清单
## 应避免的测试反模式
在标记测试完成之前：
* 测试实现细节（内部状态）而非行为
* 测试相互依赖（共享状态）
* 断言过于宽泛（通过的测试没有验证任何内容）
* 未对外部依赖进行模拟（Supabase、Redis、OpenAI 等）
## 质量检查清单
* \[ ] 所有公共函数都有单元测试
* \[ ] 所有 API 端点都有集成测试
* \[ ] 关键用户流程都有端到端测试
* \[ ] 覆盖了边界情况（空值、空、无效）
* \[ ] 测试了错误路径（不仅仅是正常路径）
* \[ ] 关键用户流程都有 E2E 测试
* \[ ] 覆盖边界情况（空值、空值、无效）
* \[ ] 测试了错误路径（不仅是正常路径）
* \[ ] 对外部依赖使用了模拟
* \[ ] 测试是独立的（无共享状态）
* \[ ] 测试名称描述了正在测试的内容
* \[ ] 断言是具体且有意义的
* \[ ] 覆盖率在 80% 以上（通过覆盖率报告验证）
* \[ ] 覆盖率在 80% 以上
## 测试异味（反模式）
### ❌ 测试实现细节
```typescript
// DON'T test internal state
expect(component.state.count).toBe(5)
```
### ✅ 测试用户可见的行为
```typescript
// DO test what users see
expect(screen.getByText('Count: 5')).toBeInTheDocument()
```
### ❌ 测试相互依赖
```typescript
// DON'T rely on previous test
test('creates user', () => { /* ... */ })
test('updates same user', () => { /* needs previous test */ })
```
### ✅ 独立的测试
```typescript
// DO setup data in each test
test('updates user', () => {
const user = createTestUser()
// Test logic
})
```
## 覆盖率报告
```bash
# Run tests with coverage
npm run test:coverage
# View HTML report
open coverage/lcov-report/index.html
```
要求阈值：
* 分支：80%
* 函数：80%
* 行：80%
* 语句：80%
## 持续测试
```bash
# Watch mode during development
npm test -- --watch
# Run before commit (via git hook)
npm test && npm run lint
# CI/CD integration
npm test -- --coverage --ci
```
**记住**：没有测试就没有代码。测试不是可选的。它们是安全网，使我们能够自信地进行重构、快速开发并确保生产可靠性。
有关详细的模拟模式和特定框架示例，请参阅 `skill: tdd-workflow`。

77
docs/zh-CN/commands/build-fix.md
View File

@@ -1,29 +1,64 @@
# 构建与修复
逐步修复 TypeScript 和构建错误：
以最小、安全的更改逐步修复构建和类型错误。
1. 运行构建：npm run build 或 pnpm build
## 步骤 1：检测构建系统
2. 解析错误输出：
* 按文件分组
* 按严重性排序
识别项目的构建工具并运行构建：
3. 对于每个错误：
* 显示错误上下文（前后 5 行）
* 解释问题
* 提出修复方案
* 应用修复
* 重新运行构建
* 验证错误是否已解决
| 指示器 | 构建命令 |
|-----------|---------------|
| `package.json` 包含 `build` 脚本 | `npm run build` 或 `pnpm build` |
| `tsconfig.json`（仅限 TypeScript） | `npx tsc --noEmit` |
| `Cargo.toml` | `cargo build 2>&1` |
| `pom.xml` | `mvn compile` |
| `build.gradle` | `./gradlew compileJava` |
| `go.mod` | `go build ./...` |
| `pyproject.toml` | `python -m py_compile` 或 `mypy .` |
4. 在以下情况停止：
* 修复引入了新的错误
* 同一错误在 3 次尝试后仍然存在
* 用户请求暂停
## 步骤 2：解析并分组错误
5. 显示摘要：
* 已修复的错误
* 剩余的错误
* 新引入的错误
1. 运行构建命令并捕获 stderr
2. 按文件路径对错误进行分组
3. 按依赖顺序排序（先修复导入/类型错误，再修复逻辑错误）
4. 统计错误总数以跟踪进度
为了安全起见，一次只修复一个错误！
## 步骤 3：修复循环（一次处理一个错误）
对于每个错误：
1. **读取文件** — 使用读取工具查看错误上下文（错误周围的 10 行代码）
2. **诊断** — 确定根本原因（缺少导入、类型错误、语法错误）
3. **最小化修复** — 使用编辑工具进行最小的更改以解决错误
4. **重新运行构建** — 验证错误已消失且未引入新错误
5. **移至下一个** — 继续处理剩余的错误
## 步骤 4：防护措施
在以下情况下停止并询问用户：
* 一个修复**引入的错误比它解决的更多**
* **同一错误在 3 次尝试后仍然存在**（可能是更深层次的问题）
* 修复需要**架构更改**（不仅仅是构建修复）
* 构建错误源于**缺少依赖项**（需要 `npm install`、`cargo add` 等）
## 步骤 5：总结
显示结果：
* 已修复的错误（包含文件路径）
* 剩余的错误（如果有）
* 引入的新错误（应为零）
* 针对未解决问题的建议后续步骤
## 恢复策略
| 情况 | 操作 |
|-----------|--------|
| 缺少模块/导入 | 检查包是否已安装；建议安装命令 |
| 类型不匹配 | 读取两种类型定义；修复更窄的类型 |
| 循环依赖 | 使用导入图识别循环；建议提取 |
| 版本冲突 | 检查 `package.json` / `Cargo.toml` 中的版本约束 |
| 构建工具配置错误 | 读取配置文件；与有效的默认配置进行比较 |
为了安全起见，一次只修复一个错误。优先使用最小的改动，而不是重构。

79
docs/zh-CN/commands/claw.md Normal file
View File

@@ -0,0 +1,79 @@
---
description: 启动 NanoClaw 代理 REPL —— 一个由 claude CLI 驱动的持久、会话感知的 AI 助手。
---
# Claw 命令
启动一个交互式 AI 代理会话，该会话将会话历史持久化到磁盘，并可选择加载 ECC 技能上下文。
## 使用方法
```bash
node scripts/claw.js
```
或通过 npm：
```bash
npm run claw
```
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CLAW_SESSION` | `default` | 会话名称（字母数字 + 连字符） |
| `CLAW_SKILLS` | *(空)* | 要加载为系统上下文的技能名称，以逗号分隔 |
## REPL 命令
在 REPL 内部，直接在提示符下输入这些命令：
```
/clear Clear current session history
/history Print full conversation history
/sessions List all saved sessions
/help Show available commands
exit Quit the REPL
```
## 工作原理
1. 读取 `CLAW_SESSION` 环境变量以选择命名会话（默认：`default`）
2. 从 `~/.claude/claw/{session}.md` 加载会话历史
3. 可选地从 `CLAW_SKILLS` 环境变量加载 ECC 技能上下文
4. 进入一个阻塞式提示循环 —— 每条用户消息都会连同完整历史记录发送到 `claude -p`
5. 响应会被追加到会话文件中，以便在重启后保持持久性
## 会话存储
会话以 Markdown 文件形式存储在 `~/.claude/claw/` 中：
```
~/.claude/claw/default.md
~/.claude/claw/my-project.md
```
每一轮对话的格式如下：
```markdown
### [2025-01-15T10:30:00.000Z] 用户
这个函数是做什么的？
---
### [2025-01-15T10:30:05.000Z] 助手
这个函数用于计算...
---
```
## 示例
```bash
# Start default session
node scripts/claw.js
# Named session
CLAW_SESSION=my-project node scripts/claw.js
# With skill context
CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
```

4
docs/zh-CN/commands/evolve.md
View File

@@ -51,7 +51,7 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [
* `new-table-step2`: "当添加数据库表时，更新模式"
* `new-table-step3`: "当添加数据库表时，重新生成类型"
→ 创建：`/new-table` 命令
→ 创建：**new-table** 命令
### → 技能（自动触发）
@@ -84,7 +84,7 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [
* `debug-step3`: "当调试时，创建最小复现"
* `debug-step4`: "当调试时，用测试验证修复"
→ 创建：`debugger` 代理
→ 创建：**debugger** 代理
## 操作步骤

92
docs/zh-CN/commands/learn-eval.md Normal file
View File

@@ -0,0 +1,92 @@
---
description: 从会话中提取可重用模式，在保存前自我评估质量，并确定正确的保存位置（全局与项目）。
---
# /learn-eval - 提取、评估、然后保存
扩展 `/learn`，在写入任何技能文件之前加入质量门和保存位置决策。
## 提取内容
寻找：
1. **错误解决模式** — 根本原因 + 修复方法 + 可重用性
2. **调试技术** — 非显而易见的步骤、工具组合
3. **变通方法** — 库的怪癖、API 限制、特定版本的修复
4. **项目特定模式** — 约定、架构决策、集成模式
## 流程
1. 回顾会话，寻找可提取的模式
2. 识别最有价值/可重用的见解
3. **确定保存位置：**
* 提问："这个模式在其他项目中会有用吗？"
* **全局** (`~/.claude/skills/learned/`)：可在 2 个以上项目中使用的通用模式（bash 兼容性、LLM API 行为、调试技术等）
* **项目** (当前项目中的 `.claude/skills/learned/`)：项目特定的知识（特定配置文件的怪癖、项目特定的架构决策等）
* 不确定时，选择全局（将全局 → 项目移动比反向操作更容易）
4. 使用此格式起草技能文件：
```markdown
---
name: pattern-name
description: "Under 130 characters"
user-invocable: false
origin: auto-extracted
---
# [描述性模式名称]
**提取日期：** [日期]
**上下文：** [简要描述此模式适用的场景]
## 问题
[此模式解决的具体问题 - 请详细说明]
## 解决方案
[模式/技术/变通方案 - 附带代码示例]
## 何时使用
[触发条件]
```
5. **在保存前自我评估**，使用此评分标准：
| 维度 | 1 | 3 | 5 |
|-----------|---|---|---|
| 具体性 | 仅抽象原则，无代码示例 | 有代表性代码示例 | 包含所有使用模式的丰富示例 |
| 可操作性 | 不清楚要做什么 | 主要步骤可理解 | 立即可操作，涵盖边界情况 |
| 范围契合度 | 过于宽泛或过于狭窄 | 基本合适，存在一些边界模糊 | 名称、触发器和内容完美匹配 |
| 非冗余性 | 几乎与另一技能相同 | 存在一些重叠但有独特视角 | 完全独特的价值 |
| 覆盖率 | 仅涵盖目标任务的一小部分 | 涵盖主要情况，缺少常见变体 | 涵盖主要情况、边界情况和陷阱 |
* 为每个维度评分 1–5
* 如果任何维度评分为 1–2，改进草案并重新评分，直到所有维度 ≥ 3
* 向用户展示评分表和最终草案
6. 请求用户确认：
* 展示：提议的保存路径 + 评分表 + 最终草案
* 在写入前等待明确确认
7. 保存到确定的位置
## 第 5 步的输出格式（评分表）
| 维度 | 评分 | 理由 |
|-----------|-------|-----------|
| 具体性 | N/5 | ... |
| 可操作性 | N/5 | ... |
| 范围契合度 | N/5 | ... |
| 非冗余性 | N/5 | ... |
| 覆盖率 | N/5 | ... |
| **总计** | **N/25** | |
## 注意事项
* 不要提取琐碎的修复（拼写错误、简单的语法错误）
* 不要提取一次性问题（特定的 API 中断等）
* 专注于能在未来会话中节省时间的模式
* 保持技能聚焦 — 每个技能一个模式
* 如果覆盖率评分低，在保存前添加相关变体

6
docs/zh-CN/commands/plan.md
View File

@@ -106,9 +106,9 @@ Agent (planner):
计划之后：
* 使用 `/tdd` 以测试驱动开发的方式实施
* 如果出现构建错误，使用 `/build-fix`
* 使用 `/code-review` 审查已完成的实施
* 使用 `/tdd` 通过测试驱动开发来实现
* 如果出现构建错误，请使用 `/build-fix`
* 使用 `/code-review` 来审查已完成的实现
## 相关代理

93
docs/zh-CN/commands/refactor-clean.md
View File

@@ -1,28 +1,83 @@
# 重构清理
通过测试验证安全识别并删除无用代码：
通过测试验证安全识别和删除死代码的每一步。
1. 运行无用代码分析工具：
* knip：查找未使用的导出和文件
* depcheck：查找未使用的依赖项
* ts-prune：查找未使用的 TypeScript 导出
## 步骤 1：检测死代码
2. 在 .reports/dead-code-analysis.md 中生成综合报告
根据项目类型运行分析工具：
3. 按严重程度对发现进行分类：
* 安全：测试文件、未使用的工具函数
* 注意：API 路由、组件
* 危险：配置文件、主要入口点
| 工具 | 查找内容 | 命令 |
|------|--------------|---------|
| knip | 未使用的导出、文件、依赖项 | `npx knip` |
| depcheck | 未使用的 npm 依赖项 | `npx depcheck` |
| ts-prune | 未使用的 TypeScript 导出 | `npx ts-prune` |
| vulture | 未使用的 Python 代码 | `vulture src/` |
| deadcode | 未使用的 Go 代码 | `deadcode ./...` |
| cargo-udeps | 未使用的 Rust 依赖项 | `cargo +nightly udeps` |
4. 仅建议安全的删除操作
如果没有可用工具，使用 Grep 查找零次导入的导出：
5. 每次删除前：
* 运行完整的测试套件
* 验证测试通过
* 应用更改
* 重新运行测试
* 如果测试失败则回滚
```
# Find exports, then check if they're imported anywhere
```
6. 显示已清理项目的摘要
## 步骤 2：分类发现结果
切勿在不首先运行测试的情况下删除代码！
将发现结果按安全层级分类：
| 层级 | 示例 | 操作 |
|------|----------|--------|
| **安全** | 未使用的工具函数、测试辅助函数、内部函数 | 放心删除 |
| **谨慎** | 组件、API 路由、中间件 | 验证没有动态导入或外部使用者 |
| **危险** | 配置文件、入口点、类型定义 | 在操作前仔细调查 |
## 步骤 3：安全删除循环
对于每个 **安全** 项：
1. **运行完整测试套件** — 建立基准（全部通过）
2. **删除死代码** — 使用编辑工具进行精确删除
3. **重新运行测试套件** — 验证没有破坏任何功能
4. **如果测试失败** — 立即使用 `git checkout -- <file>` 回滚并跳过此项
5. **如果测试通过** — 处理下一项
## 步骤 4：处理谨慎项
在删除 **谨慎** 项之前：
* 搜索动态导入：`import()`、`require()`、`__import__`
* 搜索字符串引用：配置中的路由名称、组件名称
* 检查是否从公共包 API 导出
* 验证没有外部使用者（如果已发布，请检查依赖项）
## 步骤 5：合并重复项
删除死代码后，查找：
* 近似的重复函数（>80% 相似）— 合并为一个
* 冗余的类型定义 — 整合
* 没有增加价值的包装函数 — 内联它们
* 没有作用的重新导出 — 移除间接引用
## 步骤 6：总结
报告结果：
```
Dead Code Cleanup
──────────────────────────────
Deleted: 12 unused functions
3 unused files
5 unused dependencies
Skipped: 2 items (tests failed)
Saved: ~450 lines removed
──────────────────────────────
All tests passing ✅
```
## 规则
* **切勿在不先运行测试的情况下删除代码**
* **一次只删除一个** — 原子化的变更便于回滚
* **如果不确定就跳过** — 保留死代码总比破坏生产环境好
* **清理时不要重构** — 分离关注点（先清理，后重构）

75
docs/zh-CN/commands/test-coverage.md
View File

@@ -1,28 +1,69 @@
# 测试覆盖率
分析测试覆盖率并生成缺失的测试：
分析测试覆盖率，识别缺口，并生成缺失的测试以达到 80%+ 的覆盖率。
1. 运行带有覆盖率的测试：npm test --coverage 或 pnpm test --coverage
## 步骤 1：检测测试框架
2. 分析覆盖率报告 (coverage/coverage-summary.json)
| 指标 | 覆盖率命令 |
|-----------|-----------------|
| `jest.config.*` 或 `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
| `vitest.config.*` | `npx vitest run --coverage` |
| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
| `Cargo.toml` | `cargo llvm-cov --json` |
| `pom.xml` 与 JaCoCo | `mvn test jacoco:report` |
| `go.mod` | `go test -coverprofile=coverage.out ./...` |
3. 识别覆盖率低于 80% 阈值的文件
## 步骤 2：分析覆盖率报告
4. 对于每个覆盖率不足的文件：
* 分析未测试的代码路径
* 为函数生成单元测试
* 为 API 生成集成测试
* 为关键流程生成端到端测试
1. 运行覆盖率命令
2. 解析输出（JSON 摘要或终端输出）
3. 列出**覆盖率低于 80%** 的文件，按最差情况排序
4. 对于每个覆盖率不足的文件，识别：
* 未测试的函数或方法
* 缺失的分支覆盖率（if/else、switch、错误路径）
* 增加分母的死代码
5. 验证新测试通过
## 步骤 3：生成缺失的测试
6. 显示覆盖率指标的前后对比
对于每个覆盖率不足的文件，按以下优先级生成测试：
7. 确保项目整体覆盖率超过 80%
1. **快乐路径** — 使用有效输入的核心功能
2. **错误处理** — 无效输入、缺失数据、网络故障
3. **边界情况** — 空数组、null/undefined、边界值（0、-1、MAX\_INT）
4. **分支覆盖率** — 每个 if/else、switch case、三元运算符
重点关注：
### 测试生成规则
* 正常路径场景
* 错误处理
* 边界情况（null、undefined、空值）
* 边界条件
* 将测试放在源代码旁边：`foo.ts` → `foo.test.ts`（或遵循项目惯例）
* 使用项目中现有的测试模式（导入风格、断言库、模拟方法）
* 模拟外部依赖项（数据库、API、文件系统）
* 每个测试都应该是独立的 — 测试之间没有共享的可变状态
* 描述性地命名测试：`test_create_user_with_duplicate_email_returns_409`
## 步骤 4：验证
1. 运行完整的测试套件 — 所有测试必须通过
2. 重新运行覆盖率 — 验证改进
3. 如果仍然低于 80%，针对剩余的缺口重复步骤 3
## 步骤 5：报告
显示前后对比：
```
Coverage Report
──────────────────────────────
File Before After
src/services/auth.ts 45% 88%
src/utils/validation.ts 32% 82%
──────────────────────────────
Overall: 67% 84% ✅
```
## 重点关注领域
* 具有复杂分支的函数（高圈复杂度）
* 错误处理程序和 catch 块
* 整个代码库中使用的工具函数
* API 端点处理程序（请求 → 响应流程）
* 边界情况：null、undefined、空字符串、空数组、零、负数

76
docs/zh-CN/commands/update-codemaps.md
View File

@@ -1,21 +1,73 @@
# 更新代码地图
分析代码库结构并更新架构文档：
分析代码库结构并生成简洁的架构文档。
1. 扫描所有源文件的导入、导出和依赖关系
## 步骤 1：扫描项目结构
2. 以以下格式生成简洁的代码地图：
* codemaps/architecture.md - 整体架构
* codemaps/backend.md - 后端结构
* codemaps/frontend.md - 前端结构
* codemaps/data.md - 数据模型和模式
1. 识别项目类型（单体仓库、单应用、库、微服务）
2. 查找所有源码目录（src/, lib/, app/, packages/）
3. 映射入口点（main.ts, index.ts, app.py, main.go 等）
3. 计算与之前版本的差异百分比
## 步骤 2：生成代码地图
4. 如果变更 > 30%，则在更新前请求用户批准
在 `docs/CODEMAPS/`（或 `.reports/codemaps/`）中创建或更新代码地图：
5. 为每个代码地图添加新鲜度时间戳
| 文件 | 内容 |
|------|----------|
| `architecture.md` | 高层系统图、服务边界、数据流 |
| `backend.md` | API 路由、中间件链、服务 → 仓库映射 |
| `frontend.md` | 页面树、组件层级、状态管理流 |
| `data.md` | 数据库表、关系、迁移历史 |
| `dependencies.md` | 外部服务、第三方集成、共享库 |
6. 将报告保存到 .reports/codemap-diff.txt
### 代码地图格式
使用 TypeScript/Node.js 进行分析。专注于高层结构，而非实现细节。
每个代码地图应为简洁风格 —— 针对 AI 上下文消费进行优化：
```markdown
# 后端架构
## 路由
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
## 关键文件
src/services/user.ts (业务逻辑，120行)
src/repos/user.ts (数据库访问，80行)
## 依赖项
- PostgreSQL (主要数据存储)
- Redis (会话缓存，速率限制)
- Stripe (支付处理)
```
## 步骤 3：差异检测
1. 如果存在先前的代码地图，计算差异百分比
2. 如果变更 > 30%，显示差异并在覆盖前请求用户批准
3. 如果变更 <= 30%，则原地更新
## 步骤 4：添加元数据
为每个代码地图添加一个新鲜度头部：
```markdown
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
```
## 步骤 5：保存分析报告
将摘要写入 `.reports/codemap-diff.txt`：
* 自上次扫描以来添加/删除/修改的文件
* 检测到的新依赖项
* 架构变更（新路由、新服务等）
* 超过 90 天未更新的文档的陈旧警告
## 提示
* 关注**高层结构**，而非实现细节
* 优先使用**文件路径和函数签名**，而非完整代码块
* 为高效加载上下文，将每个代码地图保持在 **1000 个 token 以内**
* 使用 ASCII 图表表示数据流，而非冗长的描述
* 在主要功能添加或重构会话后运行

99
docs/zh-CN/commands/update-docs.md
View File

@@ -1,31 +1,86 @@
# 更新文档
从单一事实来源同步文档：
将文档与代码库同步，从单一事实来源文件生成。
1. 读取 package.json 的 scripts 部分
* 生成脚本参考表
* 包含来自注释的描述
## 步骤 1：识别单一事实来源
2. 读取 .env.example
* 提取所有环境变量
* 记录其用途和格式
| 来源 | 生成内容 |
|--------|-----------|
| `package.json` 脚本 | 可用命令参考 |
| `.env.example` | 环境变量文档 |
| `openapi.yaml` / 路由文件 | API 端点参考 |
| 源代码导出 | 公共 API 文档 |
| `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |
3. 生成 docs/CONTRIB.md，内容包含：
* 开发工作流程
* 可用脚本
* 环境设置
* 测试流程
## 步骤 2：生成脚本参考
4. 生成 docs/RUNBOOK.md，内容包含：
* 部署流程
* 监控和警报
* 常见问题及修复
* 回滚流程
1. 读取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
2. 提取所有脚本/命令及其描述
3. 生成参考表格：
5. 识别过时的文档：
* 查找 90 天以上未修改的文档
* 列出以供人工审查
```markdown
| Command | Description |
|---------|-------------|
| `npm run dev` | 启动带热重载的开发服务器 |
| `npm run build` | 执行带类型检查的生产构建 |
| `npm test` | 运行带覆盖率测试的测试套件 |
```
6. 显示差异摘要
## 步骤 3：生成环境文档
单一事实来源：package.json 和 .env.example
1. 读取 `.env.example` (或 `.env.template`, `.env.sample`)
2. 提取所有变量及其用途
3. 按必需项与可选项分类
4. 记录预期格式和有效值
```markdown
| 变量 | 必需 | 描述 | 示例 |
|----------|----------|-------------|---------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | 否 | 日志详细程度（默认：info） | `debug`, `info`, `warn`, `error` |
```
## 步骤 4：更新贡献指南
生成或更新 `docs/CONTRIBUTING.md`，包含：
* 开发环境设置（先决条件、安装步骤）
* 可用脚本及其用途
* 测试流程（如何运行、如何编写新测试）
* 代码风格强制（linter、formatter、预提交钩子）
* PR 提交清单
## 步骤 5：更新运行手册
生成或更新 `docs/RUNBOOK.md`，包含：
* 部署流程（逐步说明）
* 健康检查端点和监控
* 常见问题及其修复方法
* 回滚流程
* 告警和升级路径
## 步骤 6：检查文档时效性
1. 查找 90 天以上未修改的文档文件
2. 与最近的源代码变更进行交叉引用
3. 标记可能过时的文档以供人工审核
## 步骤 7：显示摘要
```
Documentation Update
──────────────────────────────
Updated: docs/CONTRIBUTING.md (scripts table)
Updated: docs/ENV.md (3 new variables)
Flagged: docs/DEPLOY.md (142 days stale)
Skipped: docs/API.md (no changes detected)
──────────────────────────────
```
## 规则
* **单一事实来源**：始终从代码生成，切勿手动编辑生成的部分
* **保留手动编写部分**：仅更新生成的部分；保持手写内容不变
* **标记生成的内容**：在生成的部分周围使用 `<!-- AUTO-GENERATED -->` 标记
* **不主动创建文档**：仅在命令明确要求时才创建新的文档文件

308
docs/zh-CN/examples/django-api-CLAUDE.md Normal file
View File

@@ -0,0 +1,308 @@
# Django REST API — 项目 CLAUDE.md
> 使用 PostgreSQL 和 Celery 的 Django REST Framework API 真实示例。
> 将此复制到你的项目根目录并针对你的服务进行自定义。
## 项目概述
**技术栈:** Python 3.12+, Django 5.x, Django REST Framework, PostgreSQL, Celery + Redis, pytest, Docker Compose
**架构:** 采用领域驱动设计，每个业务领域对应一个应用。DRF 用于 API 层，Celery 用于异步任务，pytest 用于测试。所有端点返回 JSON — 无模板渲染。
## 关键规则
### Python 约定
* 所有函数签名使用类型提示 — 使用 `from __future__ import annotations`
* 不使用 `print()` 语句 — 使用 `logging.getLogger(__name__)`
* 字符串格式化使用 f-strings，绝不使用 `%` 或 `.format()`
* 文件操作使用 `pathlib.Path` 而非 `os.path`
* 导入排序使用 isort：标准库、第三方库、本地库（由 ruff 强制执行）
### 数据库
* 所有查询使用 Django ORM — 原始 SQL 仅与 `.raw()` 和参数化查询一起使用
* 迁移文件提交到 git — 生产中绝不使用 `--fake`
* 使用 `select_related()` 和 `prefetch_related()` 防止 N+1 查询
* 所有模型必须具有 `created_at` 和 `updated_at` 自动字段
* 在 `filter()`、`order_by()` 或 `WHERE` 子句中使用的任何字段上建立索引
```python
# BAD: N+1 query
orders = Order.objects.all()
for order in orders:
print(order.customer.name) # hits DB for each order
# GOOD: Single query with join
orders = Order.objects.select_related("customer").all()
```
### 认证
* 通过 `djangorestframework-simplejwt` 使用 JWT — 访问令牌（15 分钟）+ 刷新令牌（7 天）
* 每个视图都设置权限类 — 绝不依赖默认设置
* 使用 `IsAuthenticated` 作为基础，为对象级访问添加自定义权限
* 为登出启用令牌黑名单
### 序列化器
* 简单 CRUD 使用 `ModelSerializer`，复杂验证使用 `Serializer`
* 当输入/输出结构不同时，分离读写序列化器
* 在序列化器层面进行验证，而非在视图中 — 视图应保持精简
```python
class CreateOrderSerializer(serializers.Serializer):
product_id = serializers.UUIDField()
quantity = serializers.IntegerField(min_value=1, max_value=100)
def validate_product_id(self, value):
if not Product.objects.filter(id=value, active=True).exists():
raise serializers.ValidationError("Product not found or inactive")
return value
class OrderDetailSerializer(serializers.ModelSerializer):
customer = CustomerSerializer(read_only=True)
product = ProductSerializer(read_only=True)
class Meta:
model = Order
fields = ["id", "customer", "product", "quantity", "total", "status", "created_at"]
```
### 错误处理
* 使用 DRF 异常处理器确保一致的错误响应
* 业务逻辑中的自定义异常放在 `core/exceptions.py`
* 绝不向客户端暴露内部错误细节
```python
# core/exceptions.py
from rest_framework.exceptions import APIException
class InsufficientStockError(APIException):
status_code = 409
default_detail = "Insufficient stock for this order"
default_code = "insufficient_stock"
```
### 代码风格
* 代码或注释中不使用表情符号
* 最大行长度：120 个字符（由 ruff 强制执行）
* 类名：PascalCase，函数/变量名：snake\_case，常量：UPPER\_SNAKE\_CASE
* 视图保持精简 — 业务逻辑放在服务函数或模型方法中
## 文件结构
```
config/
settings/
base.py # Shared settings
local.py # Dev overrides (DEBUG=True)
production.py # Production settings
urls.py # Root URL config
celery.py # Celery app configuration
apps/
accounts/ # User auth, registration, profile
models.py
serializers.py
views.py
services.py # Business logic
tests/
test_views.py
test_services.py
factories.py # Factory Boy factories
orders/ # Order management
models.py
serializers.py
views.py
services.py
tasks.py # Celery tasks
tests/
products/ # Product catalog
models.py
serializers.py
views.py
tests/
core/
exceptions.py # Custom API exceptions
permissions.py # Shared permission classes
pagination.py # Custom pagination
middleware.py # Request logging, timing
tests/
```
## 关键模式
### 服务层
```python
# apps/orders/services.py
from django.db import transaction
def create_order(*, customer, product_id: uuid.UUID, quantity: int) -> Order:
"""Create an order with stock validation and payment hold."""
product = Product.objects.select_for_update().get(id=product_id)
if product.stock < quantity:
raise InsufficientStockError()
with transaction.atomic():
order = Order.objects.create(
customer=customer,
product=product,
quantity=quantity,
total=product.price * quantity,
)
product.stock -= quantity
product.save(update_fields=["stock", "updated_at"])
# Async: send confirmation email
send_order_confirmation.delay(order.id)
return order
```
### 视图模式
```python
# apps/orders/views.py
class OrderViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
pagination_class = StandardPagination
def get_serializer_class(self):
if self.action == "create":
return CreateOrderSerializer
return OrderDetailSerializer
def get_queryset(self):
return (
Order.objects
.filter(customer=self.request.user)
.select_related("product", "customer")
.order_by("-created_at")
)
def perform_create(self, serializer):
order = create_order(
customer=self.request.user,
product_id=serializer.validated_data["product_id"],
quantity=serializer.validated_data["quantity"],
)
serializer.instance = order
```
### 测试模式 (pytest + Factory Boy)
```python
# apps/orders/tests/factories.py
import factory
from apps.accounts.tests.factories import UserFactory
from apps.products.tests.factories import ProductFactory
class OrderFactory(factory.django.DjangoModelFactory):
class Meta:
model = "orders.Order"
customer = factory.SubFactory(UserFactory)
product = factory.SubFactory(ProductFactory, stock=100)
quantity = 1
total = factory.LazyAttribute(lambda o: o.product.price * o.quantity)
# apps/orders/tests/test_views.py
import pytest
from rest_framework.test import APIClient
@pytest.mark.django_db
class TestCreateOrder:
def setup_method(self):
self.client = APIClient()
self.user = UserFactory()
self.client.force_authenticate(self.user)
def test_create_order_success(self):
product = ProductFactory(price=29_99, stock=10)
response = self.client.post("/api/orders/", {
"product_id": str(product.id),
"quantity": 2,
})
assert response.status_code == 201
assert response.data["total"] == 59_98
def test_create_order_insufficient_stock(self):
product = ProductFactory(stock=0)
response = self.client.post("/api/orders/", {
"product_id": str(product.id),
"quantity": 1,
})
assert response.status_code == 409
def test_create_order_unauthenticated(self):
self.client.force_authenticate(None)
response = self.client.post("/api/orders/", {})
assert response.status_code == 401
```
## 环境变量
```bash
# Django
SECRET_KEY=
DEBUG=False
ALLOWED_HOSTS=api.example.com
# Database
DATABASE_URL=postgres://user:pass@localhost:5432/myapp
# Redis (Celery broker + cache)
REDIS_URL=redis://localhost:6379/0
# JWT
JWT_ACCESS_TOKEN_LIFETIME=15 # minutes
JWT_REFRESH_TOKEN_LIFETIME=10080 # minutes (7 days)
# Email
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.example.com
```
## 测试策略
```bash
# Run all tests
pytest --cov=apps --cov-report=term-missing
# Run specific app tests
pytest apps/orders/tests/ -v
# Run with parallel execution
pytest -n auto
# Only failing tests from last run
pytest --lf
```
## ECC 工作流
```bash
# Planning
/plan "Add order refund system with Stripe integration"
# Development with TDD
/tdd # pytest-based TDD workflow
# Review
/python-review # Python-specific code review
/security-scan # Django security audit
/code-review # General quality check
# Verification
/verify # Build, lint, test, security scan
```
## Git 工作流
* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
* 功能分支从 `main` 创建，需要 PR
* CI：ruff（代码检查 + 格式化）、mypy（类型检查）、pytest（测试）、safety（依赖检查）
* 部署：Docker 镜像，通过 Kubernetes 或 Railway 管理

267
docs/zh-CN/examples/go-microservice-CLAUDE.md Normal file
View File

@@ -0,0 +1,267 @@
# Go 微服务 — 项目 CLAUDE.md
> 一个使用 PostgreSQL、gRPC 和 Docker 的 Go 微服务真实示例。
> 将此文件复制到您的项目根目录，并根据您的服务进行自定义。
## 项目概述
**技术栈:** Go 1.22+, PostgreSQL, gRPC + REST (grpc-gateway), Docker, sqlc (类型安全的 SQL), Wire (依赖注入)
**架构:** 采用领域、仓库、服务和处理器层的清晰架构。gRPC 作为主要传输方式，REST 网关用于外部客户端。
## 关键规则
### Go 规范
* 遵循 Effective Go 和 Go Code Review Comments 指南
* 使用 `errors.New` / `fmt.Errorf` 配合 `%w` 进行包装 — 绝不对错误进行字符串匹配
* 不使用 `init()` 函数 — 在 `main()` 或构造函数中进行显式初始化
* 没有全局可变状态 — 通过构造函数传递依赖项
* Context 必须是第一个参数，并在所有层中传播
### 数据库
* `queries/` 中的所有查询都使用纯 SQL — sqlc 生成类型安全的 Go 代码
* 在 `migrations/` 中使用 golang-migrate 进行迁移 — 绝不直接更改数据库
* 通过 `pgx.Tx` 为多步骤操作使用事务
* 所有查询必须使用参数化占位符 (`$1`, `$2`) — 绝不使用字符串格式化
### 错误处理
* 返回错误，不要 panic — panic 仅用于真正无法恢复的情况
* 使用上下文包装错误：`fmt.Errorf("creating user: %w", err)`
* 在 `domain/errors.go` 中定义业务逻辑的哨兵错误
* 在处理器层将领域错误映射到 gRPC 状态码
```go
// Domain layer — sentinel errors
var (
ErrUserNotFound = errors.New("user not found")
ErrEmailTaken = errors.New("email already registered")
)
// Handler layer — map to gRPC status
func toGRPCError(err error) error {
switch {
case errors.Is(err, domain.ErrUserNotFound):
return status.Error(codes.NotFound, err.Error())
case errors.Is(err, domain.ErrEmailTaken):
return status.Error(codes.AlreadyExists, err.Error())
default:
return status.Error(codes.Internal, "internal error")
}
}
```
### 代码风格
* 代码或注释中不使用表情符号
* 导出的类型和函数必须有文档注释
* 函数保持在 50 行以内 — 提取辅助函数
* 对所有具有多个用例的逻辑使用表格驱动测试
* 对于信号通道，优先使用 `struct{}`，而不是 `bool`
## 文件结构
```
cmd/
server/
main.go # Entrypoint, Wire injection, graceful shutdown
internal/
domain/ # Business types and interfaces
user.go # User entity and repository interface
errors.go # Sentinel errors
service/ # Business logic
user_service.go
user_service_test.go
repository/ # Data access (sqlc-generated + custom)
postgres/
user_repo.go
user_repo_test.go # Integration tests with testcontainers
handler/ # gRPC + REST handlers
grpc/
user_handler.go
rest/
user_handler.go
config/ # Configuration loading
config.go
proto/ # Protobuf definitions
user/v1/
user.proto
queries/ # SQL queries for sqlc
user.sql
migrations/ # Database migrations
001_create_users.up.sql
001_create_users.down.sql
```
## 关键模式
### 仓库接口
```go
type UserRepository interface {
Create(ctx context.Context, user *User) error
FindByID(ctx context.Context, id uuid.UUID) (*User, error)
FindByEmail(ctx context.Context, email string) (*User, error)
Update(ctx context.Context, user *User) error
Delete(ctx context.Context, id uuid.UUID) error
}
```
### 使用依赖注入的服务
```go
type UserService struct {
repo domain.UserRepository
hasher PasswordHasher
logger *slog.Logger
}
func NewUserService(repo domain.UserRepository, hasher PasswordHasher, logger *slog.Logger) *UserService {
return &UserService{repo: repo, hasher: hasher, logger: logger}
}
func (s *UserService) Create(ctx context.Context, req CreateUserRequest) (*domain.User, error) {
existing, err := s.repo.FindByEmail(ctx, req.Email)
if err != nil && !errors.Is(err, domain.ErrUserNotFound) {
return nil, fmt.Errorf("checking email: %w", err)
}
if existing != nil {
return nil, domain.ErrEmailTaken
}
hashed, err := s.hasher.Hash(req.Password)
if err != nil {
return nil, fmt.Errorf("hashing password: %w", err)
}
user := &domain.User{
ID: uuid.New(),
Name: req.Name,
Email: req.Email,
Password: hashed,
}
if err := s.repo.Create(ctx, user); err != nil {
return nil, fmt.Errorf("creating user: %w", err)
}
return user, nil
}
```
### 表格驱动测试
```go
func TestUserService_Create(t *testing.T) {
tests := []struct {
name string
req CreateUserRequest
setup func(*MockUserRepo)
wantErr error
}{
{
name: "valid user",
req: CreateUserRequest{Name: "Alice", Email: "alice@example.com", Password: "secure123"},
setup: func(m *MockUserRepo) {
m.On("FindByEmail", mock.Anything, "alice@example.com").Return(nil, domain.ErrUserNotFound)
m.On("Create", mock.Anything, mock.Anything).Return(nil)
},
wantErr: nil,
},
{
name: "duplicate email",
req: CreateUserRequest{Name: "Alice", Email: "taken@example.com", Password: "secure123"},
setup: func(m *MockUserRepo) {
m.On("FindByEmail", mock.Anything, "taken@example.com").Return(&domain.User{}, nil)
},
wantErr: domain.ErrEmailTaken,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
repo := new(MockUserRepo)
tt.setup(repo)
svc := NewUserService(repo, &bcryptHasher{}, slog.Default())
_, err := svc.Create(context.Background(), tt.req)
if tt.wantErr != nil {
assert.ErrorIs(t, err, tt.wantErr)
} else {
assert.NoError(t, err)
}
})
}
}
```
## 环境变量
```bash
# Database
DATABASE_URL=postgres://user:pass@localhost:5432/myservice?sslmode=disable
# gRPC
GRPC_PORT=50051
REST_PORT=8080
# Auth
JWT_SECRET= # Load from vault in production
TOKEN_EXPIRY=24h
# Observability
LOG_LEVEL=info # debug, info, warn, error
OTEL_ENDPOINT= # OpenTelemetry collector
```
## 测试策略
```bash
/go-test # TDD workflow for Go
/go-review # Go-specific code review
/go-build # Fix build errors
```
### 测试命令
```bash
# Unit tests (fast, no external deps)
go test ./internal/... -short -count=1
# Integration tests (requires Docker for testcontainers)
go test ./internal/repository/... -count=1 -timeout 120s
# All tests with coverage
go test ./... -coverprofile=coverage.out -count=1
go tool cover -func=coverage.out # summary
go tool cover -html=coverage.out # browser
# Race detector
go test ./... -race -count=1
```
## ECC 工作流
```bash
# Planning
/plan "Add rate limiting to user endpoints"
# Development
/go-test # TDD with Go-specific patterns
# Review
/go-review # Go idioms, error handling, concurrency
/security-scan # Secrets and vulnerabilities
# Before merge
go vet ./...
staticcheck ./...
```
## Git 工作流
* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码更改
* 从 `main` 创建功能分支，需要 PR
* CI: `go vet`, `staticcheck`, `go test -race`, `golangci-lint`
* 部署: 在 CI 中构建 Docker 镜像，部署到 Kubernetes

285
docs/zh-CN/examples/rust-api-CLAUDE.md Normal file
View File

@@ -0,0 +1,285 @@
# Rust API 服务 — 项目 CLAUDE.md
> 使用 Axum、PostgreSQL 和 Docker 构建 Rust API 服务的真实示例。
> 将此文件复制到您的项目根目录，并根据您的服务进行自定义。
## 项目概述
**技术栈：** Rust 1.78+, Axum (Web 框架), SQLx (异步数据库), PostgreSQL, Tokio (异步运行时), Docker
**架构：** 采用分层架构，包含 handler → service → repository 分离。Axum 用于 HTTP，SQLx 用于编译时类型检查的 SQL，Tower 中间件用于横切关注点。
## 关键规则
### Rust 约定
* 库错误使用 `thiserror`，仅在二进制 crate 或测试中使用 `anyhow`
* 生产代码中不使用 `.unwrap()` 或 `.expect()` — 使用 `?` 传播错误
* 函数参数中优先使用 `&str` 而非 `String`；所有权转移时返回 `String`
* 使用 `clippy` 和 `#![deny(clippy::all, clippy::pedantic)]` — 修复所有警告
* 在所有公共类型上派生 `Debug`；仅在需要时派生 `Clone`、`PartialEq`
* 除非有 `// SAFETY:` 注释说明理由，否则不使用 `unsafe` 块
### 数据库
* 所有查询使用 SQLx 的 `query!` 或 `query_as!` 宏 — 针对模式进行编译时验证
* 在 `migrations/` 中使用 `sqlx migrate` 进行迁移 — 切勿直接修改数据库
* 使用 `sqlx::Pool<Postgres>` 作为共享状态 — 切勿为每个请求创建连接
* 所有查询使用参数化占位符 (`$1`, `$2`) — 切勿使用字符串格式化
```rust
// BAD: String interpolation (SQL injection risk)
let q = format!("SELECT * FROM users WHERE id = '{}'", id);
// GOOD: Parameterized query, compile-time checked
let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
.fetch_optional(&pool)
.await?;
```
### 错误处理
* 为每个模块使用 `thiserror` 定义一个领域错误枚举
* 通过 `IntoResponse` 将错误映射到 HTTP 响应 — 切勿暴露内部细节
* 使用 `tracing` 进行结构化日志记录 — 切勿使用 `println!` 或 `eprintln!`
```rust
use thiserror::Error;
#[derive(Debug, Error)]
pub enum AppError {
#[error("Resource not found")]
NotFound,
#[error("Validation failed: {0}")]
Validation(String),
#[error("Unauthorized")]
Unauthorized,
#[error(transparent)]
Internal(#[from] anyhow::Error),
}
impl IntoResponse for AppError {
fn into_response(self) -> Response {
let (status, message) = match &self {
Self::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
Self::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
Self::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
Self::Internal(err) => {
tracing::error!(?err, "internal error");
(StatusCode::INTERNAL_SERVER_ERROR, "Internal error".into())
}
};
(status, Json(json!({ "error": message }))).into_response()
}
}
```
### 测试
* 单元测试放在每个源文件内的 `#[cfg(test)]` 模块中
* 集成测试放在 `tests/` 目录中，使用真实的 PostgreSQL (Testcontainers 或 Docker)
* 使用 `#[sqlx::test]` 进行数据库测试，包含自动迁移和回滚
* 使用 `mockall` 或 `wiremock` 模拟外部服务
### 代码风格
* 最大行长度：100 个字符（由 rustfmt 强制执行）
* 导入分组：`std`、外部 crate、`crate`/`super` — 用空行分隔
* 模块：每个模块一个文件，`mod.rs` 仅用于重新导出
* 类型：PascalCase，函数/变量：snake\_case，常量：UPPER\_SNAKE\_CASE
## 文件结构
```
src/
main.rs # Entrypoint, server setup, graceful shutdown
lib.rs # Re-exports for integration tests
config.rs # Environment config with envy or figment
router.rs # Axum router with all routes
middleware/
auth.rs # JWT extraction and validation
logging.rs # Request/response tracing
handlers/
mod.rs # Route handlers (thin — delegate to services)
users.rs
orders.rs
services/
mod.rs # Business logic
users.rs
orders.rs
repositories/
mod.rs # Database access (SQLx queries)
users.rs
orders.rs
domain/
mod.rs # Domain types, error enums
user.rs
order.rs
migrations/
001_create_users.sql
002_create_orders.sql
tests/
common/mod.rs # Shared test helpers, test server setup
api_users.rs # Integration tests for user endpoints
api_orders.rs # Integration tests for order endpoints
```
## 关键模式
### Handler (薄层)
```rust
async fn create_user(
State(ctx): State<AppState>,
Json(payload): Json<CreateUserRequest>,
) -> Result<(StatusCode, Json<UserResponse>), AppError> {
let user = ctx.user_service.create(payload).await?;
Ok((StatusCode::CREATED, Json(UserResponse::from(user))))
}
```
### Service (业务逻辑)
```rust
impl UserService {
pub async fn create(&self, req: CreateUserRequest) -> Result<User, AppError> {
if self.repo.find_by_email(&req.email).await?.is_some() {
return Err(AppError::Validation("Email already registered".into()));
}
let password_hash = hash_password(&req.password)?;
let user = self.repo.insert(&req.email, &req.name, &password_hash).await?;
Ok(user)
}
}
```
### Repository (数据访问)
```rust
impl UserRepository {
pub async fn find_by_email(&self, email: &str) -> Result<Option<User>, sqlx::Error> {
sqlx::query_as!(User, "SELECT * FROM users WHERE email = $1", email)
.fetch_optional(&self.pool)
.await
}
pub async fn insert(
&self,
email: &str,
name: &str,
password_hash: &str,
) -> Result<User, sqlx::Error> {
sqlx::query_as!(
User,
r#"INSERT INTO users (email, name, password_hash)
VALUES ($1, $2, $3) RETURNING *"#,
email, name, password_hash,
)
.fetch_one(&self.pool)
.await
}
}
```
### 集成测试
```rust
#[tokio::test]
async fn test_create_user() {
let app = spawn_test_app().await;
let response = app
.client
.post(&format!("{}/api/v1/users", app.address))
.json(&json!({
"email": "alice@example.com",
"name": "Alice",
"password": "securepassword123"
}))
.send()
.await
.expect("Failed to send request");
assert_eq!(response.status(), StatusCode::CREATED);
let body: serde_json::Value = response.json().await.unwrap();
assert_eq!(body["email"], "alice@example.com");
}
#[tokio::test]
async fn test_create_user_duplicate_email() {
let app = spawn_test_app().await;
// Create first user
create_test_user(&app, "alice@example.com").await;
// Attempt duplicate
let response = create_user_request(&app, "alice@example.com").await;
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
}
```
## 环境变量
```bash
# Server
HOST=0.0.0.0
PORT=8080
RUST_LOG=info,tower_http=debug
# Database
DATABASE_URL=postgres://user:pass@localhost:5432/myapp
# Auth
JWT_SECRET=your-secret-key-min-32-chars
JWT_EXPIRY_HOURS=24
# Optional
CORS_ALLOWED_ORIGINS=http://localhost:3000
```
## 测试策略
```bash
# Run all tests
cargo test
# Run with output
cargo test -- --nocapture
# Run specific test module
cargo test api_users
# Check coverage (requires cargo-llvm-cov)
cargo llvm-cov --html
open target/llvm-cov/html/index.html
# Lint
cargo clippy -- -D warnings
# Format check
cargo fmt -- --check
```
## ECC 工作流
```bash
# Planning
/plan "Add order fulfillment with Stripe payment"
# Development with TDD
/tdd # cargo test-based TDD workflow
# Review
/code-review # Rust-specific code review
/security-scan # Dependency audit + unsafe scan
# Verification
/verify # Build, clippy, test, security scan
```
## Git 工作流
* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
* 从 `main` 创建功能分支，需要 PR
* CI：`cargo fmt --check`、`cargo clippy`、`cargo test`、`cargo audit`
* 部署：使用 `scratch` 或 `distroless` 基础镜像的 Docker 多阶段构建

166
docs/zh-CN/examples/saas-nextjs-CLAUDE.md Normal file
View File

@@ -0,0 +1,166 @@
# SaaS 应用程序 — 项目 CLAUDE.md
> 一个 Next.js + Supabase + Stripe SaaS 应用程序的真实示例。
> 将此复制到您的项目根目录，并根据您的技术栈进行自定义。
## 项目概览
**技术栈：** Next.js 15（App Router）、TypeScript、Supabase（身份验证 + 数据库）、Stripe（计费）、Tailwind CSS、Playwright（端到端测试）
**架构：** 默认使用服务器组件。仅在需要交互性时使用客户端组件。API 路由用于 Webhook，服务器操作用于数据变更。
## 关键规则
### 数据库
* 所有查询均使用启用 RLS 的 Supabase 客户端 — 绝不要绕过 RLS
* 迁移在 `supabase/migrations/` 中 — 绝不要直接修改数据库
* 使用带有明确列列表的 `select()`，而不是 `select('*')`
* 所有面向用户的查询必须包含 `.limit()` 以防止返回无限制的结果
### 身份验证
* 在服务器组件中使用来自 `@supabase/ssr` 的 `createServerClient()`
* 在客户端组件中使用来自 `@supabase/ssr` 的 `createBrowserClient()`
* 受保护的路由检查 `getUser()` — 绝不要仅依赖 `getSession()` 进行身份验证
* `middleware.ts` 中的中间件会在每个请求上刷新身份验证令牌
### 计费
* Stripe webhook 处理程序在 `app/api/webhooks/stripe/route.ts` 中
* 绝不要信任客户端的定价数据 — 始终在服务器端从 Stripe 获取
* 通过 `subscription_status` 列检查订阅状态，由 webhook 同步
* 免费层用户：3 个项目，每天 100 次 API 调用
### 代码风格
* 代码或注释中不使用表情符号
* 仅使用不可变模式 — 使用展开运算符，永不直接修改
* 服务器组件：不使用 `'use client'` 指令，不使用 `useState`/`useEffect`
* 客户端组件：`'use client'` 放在顶部，保持最小化 — 将逻辑提取到钩子中
* 所有输入验证（API 路由、表单、环境变量）优先使用 Zod 模式
## 文件结构
```
src/
app/
(auth)/ # Auth pages (login, signup, forgot-password)
(dashboard)/ # Protected dashboard pages
api/
webhooks/ # Stripe, Supabase webhooks
layout.tsx # Root layout with providers
components/
ui/ # Shadcn/ui components
forms/ # Form components with validation
dashboard/ # Dashboard-specific components
hooks/ # Custom React hooks
lib/
supabase/ # Supabase client factories
stripe/ # Stripe client and helpers
utils.ts # General utilities
types/ # Shared TypeScript types
supabase/
migrations/ # Database migrations
seed.sql # Development seed data
```
## 关键模式
### API 响应格式
```typescript
type ApiResponse<T> =
| { success: true; data: T }
| { success: false; error: string; code?: string }
```
### 服务器操作模式
```typescript
'use server'
import { z } from 'zod'
import { createServerClient } from '@/lib/supabase/server'
const schema = z.object({
name: z.string().min(1).max(100),
})
export async function createProject(formData: FormData) {
const parsed = schema.safeParse({ name: formData.get('name') })
if (!parsed.success) {
return { success: false, error: parsed.error.flatten() }
}
const supabase = await createServerClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) return { success: false, error: 'Unauthorized' }
const { data, error } = await supabase
.from('projects')
.insert({ name: parsed.data.name, user_id: user.id })
.select('id, name, created_at')
.single()
if (error) return { success: false, error: 'Failed to create project' }
return { success: true, data }
}
```
## 环境变量
```bash
# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY= # Server-only, never expose to client
# Stripe
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
## 测试策略
```bash
/tdd # Unit + integration tests for new features
/e2e # Playwright tests for auth flow, billing, dashboard
/test-coverage # Verify 80%+ coverage
```
### 关键的端到端测试流程
1. 注册 → 邮箱验证 → 创建第一个项目
2. 登录 → 仪表盘 → CRUD 操作
3. 升级计划 → Stripe 结账 → 订阅激活
4. Webhook：订阅取消 → 降级到免费层
## ECC 工作流
```bash
# Planning a feature
/plan "Add team invitations with email notifications"
# Developing with TDD
/tdd
# Before committing
/code-review
/security-scan
# Before release
/e2e
/test-coverage
```
## Git 工作流
* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
* 从 `main` 创建功能分支，需要 PR
* CI 运行：代码检查、类型检查、单元测试、端到端测试
* 部署：在 PR 上部署到 Vercel 预览环境，在合并到 `main` 时部署到生产环境

24
docs/zh-CN/rules/README.md
View File

@@ -17,7 +17,8 @@ rules/
│ └── security.md
├── typescript/ # TypeScript/JavaScript specific
├── python/ # Python specific
└── golang/ # Go specific
├── golang/ # Go specific
└── swift/ # Swift specific
```
* **common/** 包含通用原则 —— 没有语言特定的代码示例。
@@ -32,6 +33,7 @@ rules/
./install.sh typescript
./install.sh python
./install.sh golang
./install.sh swift
# Install multiple languages at once
./install.sh typescript python
@@ -51,6 +53,7 @@ cp -r rules/common ~/.claude/rules/common
cp -r rules/typescript ~/.claude/rules/typescript
cp -r rules/python ~/.claude/rules/python
cp -r rules/golang ~/.claude/rules/golang
cp -r rules/swift ~/.claude/rules/swift
# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
```
@@ -78,3 +81,22 @@ cp -r rules/golang ~/.claude/rules/golang
> 此文件通过 <语言> 特定内容扩展了 [common/xxx.md](../common/xxx.md)。
```
4. 如果现有技能可用，则引用它们，或者在 `skills/` 下创建新的技能。
## 规则优先级
当语言特定规则与通用规则冲突时，**语言特定规则优先**（具体规则覆盖通用规则）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
* `rules/common/` 定义了适用于所有项目的通用默认值。
* `rules/golang/`、`rules/python/`、`rules/typescript/` 等在语言习惯用法不同的地方会覆盖这些默认值。
### 示例
`common/coding-style.md` 建议将不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
> 符合 Go 语言习惯的做法是使用指针接收器进行结构体修改——关于通用原则请参阅 [common/coding-style.md](../../../common/coding-style.md)，但此处更推荐符合 Go 语言习惯的修改方式。
### 带有覆盖说明的通用规则
`rules/common/` 中可能被语言特定文件覆盖的规则会标记为：
> **语言说明**：对于此模式不符合语言习惯的语言，此规则可能会被语言特定规则覆盖。

29
docs/zh-CN/rules/common/development-workflow.md Normal file
View File

@@ -0,0 +1,29 @@
# 开发工作流程
> 本文档在 [common/git-workflow.md](git-workflow.md) 的基础上进行了扩展，涵盖了在 git 操作之前发生的完整功能开发过程。
功能实现工作流程描述了开发管道：规划、测试驱动开发、代码审查，然后提交到 git。
## 功能实现工作流程
1. **先行规划**
* 使用 **planner** 代理创建实现计划
* 识别依赖项和风险
* 分解为多个阶段
2. **测试驱动开发方法**
* 使用 **tdd-guide** 代理
* 先编写测试（红）
* 实现代码以通过测试（绿）
* 重构（改进）
* 验证 80% 以上的覆盖率
3. **代码审查**
* 编写代码后立即使用 **code-reviewer** 代理
* 解决 CRITICAL 和 HIGH 级别的问题
* 尽可能修复 MEDIUM 级别的问题
4. **提交与推送**
* 详细的提交信息
* 遵循约定式提交格式
* 有关提交信息格式和 PR 流程，请参阅 [git-workflow.md](git-workflow.md)

24
docs/zh-CN/rules/common/git-workflow.md
View File

@@ -22,25 +22,5 @@
4. 包含带有 TODO 的测试计划
5. 如果是新分支，使用 `-u` 标志推送
## 功能实现工作流程
1. **先做计划**
* 使用 **planner** 代理创建实施计划
* 识别依赖项和风险
* 分解为多个阶段
2. **TDD 方法**
* 使用 **tdd-guide** 代理
* 先写测试（RED）
* 实现代码以通过测试（GREEN）
* 重构（IMPROVE）
* 验证 80%+ 的覆盖率
3. **代码审查**
* 编写代码后立即使用 **code-reviewer** 代理
* 解决 CRITICAL 和 HIGH 级别的问题
* 尽可能修复 MEDIUM 级别的问题
4. **提交与推送**
* 详细的提交信息
* 遵循约定式提交格式
> 有关 git 操作之前的完整开发流程（规划、TDD、代码审查），
> 请参阅 [development-workflow.md](development-workflow.md)。

2
docs/zh-CN/rules/common/performance.md
View File

@@ -8,7 +8,7 @@
* 结对编程和代码生成
* 多智能体系统中的工作智能体
**Sonnet 4.5** (最佳编码模型):
**Sonnet 4.6** (最佳编码模型):
* 主要的开发工作
* 编排多智能体工作流

7
docs/zh-CN/rules/golang/coding-style.md
View File

@@ -1,3 +1,10 @@
---
paths:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
---
# Go 编码风格
> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上，扩展了 Go 语言的特定内容。

7
docs/zh-CN/rules/golang/hooks.md
View File

@@ -1,3 +1,10 @@
---
paths:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
---
# Go 钩子
> 本文件通过 Go 特定内容扩展了 [common/hooks.md](../common/hooks.md)。

7
docs/zh-CN/rules/golang/patterns.md
View File

@@ -1,3 +1,10 @@
---
paths:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
---
# Go 模式
> 本文档在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 Go 语言特定的内容。

7
docs/zh-CN/rules/golang/security.md
View File

@@ -1,3 +1,10 @@
---
paths:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
---
# Go 安全
> 此文件基于 [common/security.md](../common/security.md) 扩展了 Go 特定内容。

7
docs/zh-CN/rules/golang/testing.md
View File

@@ -1,3 +1,10 @@
---
paths:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
---
# Go 测试
> 本文档在 [common/testing.md](../common/testing.md) 的基础上扩展了 Go 特定的内容。

6
docs/zh-CN/rules/python/coding-style.md
View File

@@ -1,3 +1,9 @@
---
paths:
- "**/*.py"
- "**/*.pyi"
---
# Python 编码风格
> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 Python 特定的内容。

6
docs/zh-CN/rules/python/hooks.md
View File

@@ -1,3 +1,9 @@
---
paths:
- "**/*.py"
- "**/*.pyi"
---
# Python 钩子
> 本文档扩展了 [common/hooks.md](../common/hooks.md) 中关于 Python 的特定内容。

6
docs/zh-CN/rules/python/patterns.md
View File

@@ -1,3 +1,9 @@
---
paths:
- "**/*.py"
- "**/*.pyi"
---
# Python 模式
> 本文档扩展了 [common/patterns.md](../common/patterns.md)，补充了 Python 特定的内容。

6
docs/zh-CN/rules/python/security.md
View File

@@ -1,3 +1,9 @@
---
paths:
- "**/*.py"
- "**/*.pyi"
---
# Python 安全
> 本文档基于 [通用安全指南](../common/security.md) 扩展，补充了 Python 相关的内容。

6
docs/zh-CN/rules/python/testing.md
View File

@@ -1,3 +1,9 @@
---
paths:
- "**/*.py"
- "**/*.pyi"
---
# Python 测试
> 本文件在 [通用/测试.md](../common/testing.md) 的基础上扩展了 Python 特定的内容。

48
docs/zh-CN/rules/swift/coding-style.md Normal file
View File

@@ -0,0 +1,48 @@
---
paths:
- "**/*.swift"
- "**/Package.swift"
---
# Swift 编码风格
> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 Swift 相关的内容。
## 格式化
* **SwiftFormat** 用于自动格式化，**SwiftLint** 用于风格检查
* `swift-format` 已作为替代方案捆绑在 Xcode 16+ 中
## 不变性
* 优先使用 `let` 而非 `var` — 将所有内容定义为 `let`，仅在编译器要求时才改为 `var`
* 默认使用具有值语义的 `struct`；仅在需要标识或引用语义时才使用 `class`
## 命名
遵循 [Apple API 设计指南](https://www.swift.org/documentation/api-design-guidelines/)：
* 在使用时保持清晰 — 省略不必要的词语
* 根据方法和属性的作用而非类型来命名
* 对于常量，使用 `static let` 而非全局常量
## 错误处理
使用类型化 throws (Swift 6+) 和模式匹配：
```swift
func load(id: String) throws(LoadError) -> Item {
guard let data = try? read(from: path) else {
throw .fileNotFound(id)
}
return try decode(data)
}
```
## 并发
启用 Swift 6 严格并发检查。优先使用：
* `Sendable` 值类型用于跨越隔离边界的数据
* Actors 用于共享可变状态
* 结构化并发 (`async let`, `TaskGroup`) 而非非结构化的 `Task {}`

21
docs/zh-CN/rules/swift/hooks.md Normal file
View File

@@ -0,0 +1,21 @@
---
paths:
- "**/*.swift"
- "**/Package.swift"
---
# Swift 钩子
> 此文件扩展了 [common/hooks.md](../common/hooks.md) 的内容，添加了 Swift 特定内容。
## PostToolUse 钩子
在 `~/.claude/settings.json` 中配置：
* **SwiftFormat**: 在编辑后自动格式化 `.swift` 文件
* **SwiftLint**: 在编辑 `.swift` 文件后运行代码检查
* **swift build**: 在编辑后对修改的包进行类型检查
## 警告
标记 `print()` 语句 — 在生产代码中请改用 `os.Logger` 或结构化日志记录。

67
docs/zh-CN/rules/swift/patterns.md Normal file
View File

@@ -0,0 +1,67 @@
---
paths:
- "**/*.swift"
- "**/Package.swift"
---
# Swift 模式
> 此文件使用 Swift 特定内容扩展了 [common/patterns.md](../common/patterns.md)。
## 面向协议的设计
定义小型、专注的协议。使用协议扩展来提供共享的默认实现：
```swift
protocol Repository: Sendable {
associatedtype Item: Identifiable & Sendable
func find(by id: Item.ID) async throws -> Item?
func save(_ item: Item) async throws
}
```
## 值类型
* 使用结构体（struct）作为数据传输对象和模型
* 使用带有关联值的枚举（enum）来建模不同的状态：
```swift
enum LoadState<T: Sendable>: Sendable {
case idle
case loading
case loaded(T)
case failed(Error)
}
```
## Actor 模式
使用 actor 来处理共享可变状态，而不是锁或调度队列：
```swift
actor Cache<Key: Hashable & Sendable, Value: Sendable> {
private var storage: [Key: Value] = [:]
func get(_ key: Key) -> Value? { storage[key] }
func set(_ key: Key, value: Value) { storage[key] = value }
}
```
## 依赖注入
使用默认参数注入协议 —— 生产环境使用默认值，测试时注入模拟对象：
```swift
struct UserService {
private let repository: any UserRepository
init(repository: any UserRepository = DefaultUserRepository()) {
self.repository = repository
}
}
```
## 参考
查看技能：`swift-actor-persistence` 以了解基于 actor 的持久化模式。
查看技能：`swift-protocol-di-testing` 以了解基于协议的依赖注入和测试。

34
docs/zh-CN/rules/swift/security.md Normal file
View File

@@ -0,0 +1,34 @@
---
paths:
- "**/*.swift"
- "**/Package.swift"
---
# Swift 安全
> 此文件扩展了 [common/security.md](../common/security.md)，并包含 Swift 特定的内容。
## 密钥管理
* 使用 **Keychain Services** 处理敏感数据（令牌、密码、密钥）—— 切勿使用 `UserDefaults`
* 使用环境变量或 `.xcconfig` 文件来管理构建时的密钥
* 切勿在源代码中硬编码密钥 —— 反编译工具可以轻易提取它们
```swift
let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
guard let apiKey, !apiKey.isEmpty else {
fatalError("API_KEY not configured")
}
```
## 传输安全
* 默认强制执行 App Transport Security (ATS) —— 不要禁用它
* 对关键端点使用证书锁定
* 验证所有服务器证书
## 输入验证
* 在显示之前清理所有用户输入，以防止注入攻击
* 使用带验证的 `URL(string:)`，而不是强制解包
* 在处理来自外部源（API、深度链接、剪贴板）的数据之前，先进行验证

46
docs/zh-CN/rules/swift/testing.md Normal file
View File

@@ -0,0 +1,46 @@
---
paths:
- "**/*.swift"
- "**/Package.swift"
---
# Swift 测试
> 本文档在 [common/testing.md](../common/testing.md) 的基础上扩展了 Swift 特定的内容。
## 框架
对于新测试，使用 **Swift Testing** (`import Testing`)。使用 `@Test` 和 `#expect`：
```swift
@Test("User creation validates email")
func userCreationValidatesEmail() throws {
#expect(throws: ValidationError.invalidEmail) {
try User(email: "not-an-email")
}
}
```
## 测试隔离
每个测试都会获得一个全新的实例 —— 在 `init` 中设置，在 `deinit` 中拆卸。测试之间没有共享的可变状态。
## 参数化测试
```swift
@Test("Validates formats", arguments: ["json", "xml", "csv"])
func validatesFormat(format: String) throws {
let parser = try Parser(format: format)
#expect(parser.isValid)
}
```
## 覆盖率
```bash
swift test --enable-code-coverage
```
## 参考
关于基于协议的依赖注入和 Swift Testing 的模拟模式，请参阅技能：`swift-protocol-di-testing`。

8
docs/zh-CN/rules/typescript/coding-style.md
View File

@@ -1,3 +1,11 @@
---
paths:
- "**/*.ts"
- "**/*.tsx"
- "**/*.js"
- "**/*.jsx"
---
# TypeScript/JavaScript 编码风格
> 本文件基于 [common/coding-style.md](../common/coding-style.md) 扩展，包含 TypeScript/JavaScript 特定内容。

8
docs/zh-CN/rules/typescript/hooks.md
View File

@@ -1,3 +1,11 @@
---
paths:
- "**/*.ts"
- "**/*.tsx"
- "**/*.js"
- "**/*.jsx"
---
# TypeScript/JavaScript 钩子
> 此文件扩展了 [common/hooks.md](../common/hooks.md)，并添加了 TypeScript/JavaScript 特有的内容。

8
docs/zh-CN/rules/typescript/patterns.md
View File

@@ -1,3 +1,11 @@
---
paths:
- "**/*.ts"
- "**/*.tsx"
- "**/*.js"
- "**/*.jsx"
---
# TypeScript/JavaScript 模式
> 此文件在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 TypeScript/JavaScript 特定的内容。

8
docs/zh-CN/rules/typescript/security.md
View File

@@ -1,3 +1,11 @@
---
paths:
- "**/*.ts"
- "**/*.tsx"
- "**/*.js"
- "**/*.jsx"
---
# TypeScript/JavaScript 安全
> 本文档扩展了 [common/security.md](../common/security.md)，包含了 TypeScript/JavaScript 特定的内容。

8
docs/zh-CN/rules/typescript/testing.md
View File

@@ -1,3 +1,11 @@
---
paths:
- "**/*.ts"
- "**/*.tsx"
- "**/*.js"
- "**/*.jsx"
---
# TypeScript/JavaScript 测试
> 本文档基于 [common/testing.md](../common/testing.md) 扩展，补充了 TypeScript/JavaScript 特定的内容。

523
docs/zh-CN/skills/api-design/SKILL.md Normal file
View File

@@ -0,0 +1,523 @@
---
name: api-design
description: REST API设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。
origin: ECC
---
# API 设计模式
用于设计一致、对开发者友好的 REST API 的约定和最佳实践。
## 何时启用
* 设计新的 API 端点时
* 审查现有的 API 契约时
* 添加分页、过滤或排序功能时
* 为 API 实现错误处理时
* 规划 API 版本策略时
* 构建面向公众或合作伙伴的 API 时
## 资源设计
### URL 结构
```
# Resources are nouns, plural, lowercase, kebab-case
GET /api/v1/users
GET /api/v1/users/:id
POST /api/v1/users
PUT /api/v1/users/:id
PATCH /api/v1/users/:id
DELETE /api/v1/users/:id
# Sub-resources for relationships
GET /api/v1/users/:id/orders
POST /api/v1/users/:id/orders
# Actions that don't map to CRUD (use verbs sparingly)
POST /api/v1/orders/:id/cancel
POST /api/v1/auth/login
POST /api/v1/auth/refresh
```
### 命名规则
```
# GOOD
/api/v1/team-members # kebab-case for multi-word resources
/api/v1/orders?status=active # query params for filtering
/api/v1/users/123/orders # nested resources for ownership
# BAD
/api/v1/getUsers # verb in URL
/api/v1/user # singular (use plural)
/api/v1/team_members # snake_case in URLs
/api/v1/users/123/getOrders # verb in nested resource
```
## HTTP 方法和状态码
### 方法语义
| 方法 | 幂等性 | 安全性 | 用途 |
|--------|-----------|------|---------|
| GET | 是 | 是 | 检索资源 |
| POST | 否 | 否 | 创建资源，触发操作 |
| PUT | 是 | 否 | 完全替换资源 |
| PATCH | 否\* | 否 | 部分更新资源 |
| DELETE | 是 | 否 | 删除资源 |
\*通过适当的实现，PATCH 可以实现幂等
### 状态码参考
```
# Success
200 OK — GET, PUT, PATCH (with response body)
201 Created — POST (include Location header)
204 No Content — DELETE, PUT (no response body)
# Client Errors
400 Bad Request — Validation failure, malformed JSON
401 Unauthorized — Missing or invalid authentication
403 Forbidden — Authenticated but not authorized
404 Not Found — Resource doesn't exist
409 Conflict — Duplicate entry, state conflict
422 Unprocessable Entity — Semantically invalid (valid JSON, bad data)
429 Too Many Requests — Rate limit exceeded
# Server Errors
500 Internal Server Error — Unexpected failure (never expose details)
502 Bad Gateway — Upstream service failed
503 Service Unavailable — Temporary overload, include Retry-After
```
### 常见错误
```
# BAD: 200 for everything
{ "status": 200, "success": false, "error": "Not found" }
# GOOD: Use HTTP status codes semantically
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }
# BAD: 500 for validation errors
# GOOD: 400 or 422 with field-level details
# BAD: 200 for created resources
# GOOD: 201 with Location header
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123
```
## 响应格式
### 成功响应
```json
{
"data": {
"id": "abc-123",
"email": "alice@example.com",
"name": "Alice",
"created_at": "2025-01-15T10:30:00Z"
}
}
```
### 集合响应（带分页）
```json
{
"data": [
{ "id": "abc-123", "name": "Alice" },
{ "id": "def-456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"per_page": 20,
"total_pages": 8
},
"links": {
"self": "/api/v1/users?page=1&per_page=20",
"next": "/api/v1/users?page=2&per_page=20",
"last": "/api/v1/users?page=8&per_page=20"
}
}
```
### 错误响应
```json
{
"error": {
"code": "validation_error",
"message": "Request validation failed",
"details": [
{
"field": "email",
"message": "Must be a valid email address",
"code": "invalid_format"
},
{
"field": "age",
"message": "Must be between 0 and 150",
"code": "out_of_range"
}
]
}
}
```
### 响应包装器变体
```typescript
// Option A: Envelope with data wrapper (recommended for public APIs)
interface ApiResponse<T> {
data: T;
meta?: PaginationMeta;
links?: PaginationLinks;
}
interface ApiError {
error: {
code: string;
message: string;
details?: FieldError[];
};
}
// Option B: Flat response (simpler, common for internal APIs)
// Success: just return the resource directly
// Error: return error object
// Distinguish by HTTP status code
```
## 分页
### 基于偏移量（简单）
```
GET /api/v1/users?page=2&per_page=20
# Implementation
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;
```
**优点：** 易于实现，支持“跳转到第 N 页”
**缺点：** 在大偏移量时速度慢（例如 OFFSET 100000），并发插入时结果不一致
### 基于游标（可扩展）
```
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
# Implementation
SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21; -- fetch one extra to determine has_next
```
```json
{
"data": [...],
"meta": {
"has_next": true,
"next_cursor": "eyJpZCI6MTQzfQ"
}
}
```
**优点：** 无论位置如何，性能一致；在并发插入时结果稳定
**缺点：** 无法跳转到任意页面；游标是不透明的
### 何时使用哪种
| 用例 | 分页类型 |
|----------|----------------|
| 管理仪表板，小数据集 (<10K) | 偏移量 |
| 无限滚动，信息流，大数据集 | 游标 |
| 公共 API | 游标（默认）配合偏移量（可选） |
| 搜索结果 | 偏移量（用户期望有页码） |
## 过滤、排序和搜索
### 过滤
```
# Simple equality
GET /api/v1/orders?status=active&customer_id=abc-123
# Comparison operators (use bracket notation)
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/orders?created_at[after]=2025-01-01
# Multiple values (comma-separated)
GET /api/v1/products?category=electronics,clothing
# Nested fields (dot notation)
GET /api/v1/orders?customer.country=US
```
### 排序
```
# Single field (prefix - for descending)
GET /api/v1/products?sort=-created_at
# Multiple fields (comma-separated)
GET /api/v1/products?sort=-featured,price,-created_at
```
### 全文搜索
```
# Search query parameter
GET /api/v1/products?q=wireless+headphones
# Field-specific search
GET /api/v1/users?email=alice
```
### 稀疏字段集
```
# Return only specified fields (reduces payload)
GET /api/v1/users?fields=id,name,email
GET /api/v1/orders?fields=id,total,status&include=customer.name
```
## 认证和授权
### 基于令牌的认证
```
# Bearer token in Authorization header
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
# API key (for server-to-server)
GET /api/v1/data
X-API-Key: sk_live_abc123
```
### 授权模式
```typescript
// Resource-level: check ownership
app.get("/api/v1/orders/:id", async (req, res) => {
const order = await Order.findById(req.params.id);
if (!order) return res.status(404).json({ error: { code: "not_found" } });
if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
return res.json({ data: order });
});
// Role-based: check permissions
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
await User.delete(req.params.id);
return res.status(204).send();
});
```
## 速率限制
### 响应头
```
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
# When exceeded
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Try again in 60 seconds."
}
}
```
### 速率限制层级
| 层级 | 限制 | 时间窗口 | 用例 |
|------|-------|--------|----------|
| 匿名用户 | 30/分钟 | 每个 IP | 公共端点 |
| 认证用户 | 100/分钟 | 每个用户 | 标准 API 访问 |
| 高级用户 | 1000/分钟 | 每个 API 密钥 | 付费 API 套餐 |
| 内部服务 | 10000/分钟 | 每个服务 | 服务间调用 |
## 版本控制
### URL 路径版本控制（推荐）
```
/api/v1/users
/api/v2/users
```
**优点：** 明确，易于路由，可缓存
**缺点：** 版本间 URL 会变化
### 请求头版本控制
```
GET /api/users
Accept: application/vnd.myapp.v2+json
```
**优点：** URL 简洁
**缺点：** 测试更困难，容易忘记
### 版本控制策略
```
1. Start with /api/v1/ — don't version until you need to
2. Maintain at most 2 active versions (current + previous)
3. Deprecation timeline:
- Announce deprecation (6 months notice for public APIs)
- Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
- Return 410 Gone after sunset date
4. Non-breaking changes don't need a new version:
- Adding new fields to responses
- Adding new optional query parameters
- Adding new endpoints
5. Breaking changes require a new version:
- Removing or renaming fields
- Changing field types
- Changing URL structure
- Changing authentication method
```
## 实现模式
### TypeScript (Next.js API 路由)
```typescript
import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";
const createUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1).max(100),
});
export async function POST(req: NextRequest) {
const body = await req.json();
const parsed = createUserSchema.safeParse(body);
if (!parsed.success) {
return NextResponse.json({
error: {
code: "validation_error",
message: "Request validation failed",
details: parsed.error.issues.map(i => ({
field: i.path.join("."),
message: i.message,
code: i.code,
})),
},
}, { status: 422 });
}
const user = await createUser(parsed.data);
return NextResponse.json(
{ data: user },
{
status: 201,
headers: { Location: `/api/v1/users/${user.id}` },
},
);
}
```
### Python (Django REST Framework)
```python
from rest_framework import serializers, viewsets, status
from rest_framework.response import Response
class CreateUserSerializer(serializers.Serializer):
email = serializers.EmailField()
name = serializers.CharField(max_length=100)
class UserSerializer(serializers.ModelSerializer):
class Meta:
model = User
fields = ["id", "email", "name", "created_at"]
class UserViewSet(viewsets.ModelViewSet):
serializer_class = UserSerializer
permission_classes = [IsAuthenticated]
def get_serializer_class(self):
if self.action == "create":
return CreateUserSerializer
return UserSerializer
def create(self, request):
serializer = CreateUserSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
user = UserService.create(**serializer.validated_data)
return Response(
{"data": UserSerializer(user).data},
status=status.HTTP_201_CREATED,
headers={"Location": f"/api/v1/users/{user.id}"},
)
```
### Go (net/http)
```go
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
var req CreateUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
return
}
if err := req.Validate(); err != nil {
writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
return
}
user, err := h.service.Create(r.Context(), req)
if err != nil {
switch {
case errors.Is(err, domain.ErrEmailTaken):
writeError(w, http.StatusConflict, "email_taken", "Email already registered")
default:
writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
}
return
}
w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
writeJSON(w, http.StatusCreated, map[string]any{"data": user})
}
```
## API 设计清单
发布新端点前请检查：
* \[ ] 资源 URL 遵循命名约定（复数、短横线连接、不含动词）
* \[ ] 使用了正确的 HTTP 方法（GET 用于读取，POST 用于创建等）
* \[ ] 返回了适当的状态码（不要所有情况都返回 200）
* \[ ] 使用模式（Zod, Pydantic, Bean Validation）验证了输入
* \[ ] 错误响应遵循带代码和消息的标准格式
* \[ ] 列表端点实现了分页（游标或偏移量）
* \[ ] 需要认证（或明确标记为公开）
* \[ ] 检查了授权（用户只能访问自己的资源）
* \[ ] 配置了速率限制
* \[ ] 响应未泄露内部细节（堆栈跟踪、SQL 错误）
* \[ ] 与现有端点命名一致（camelCase 对比 snake\_case）
* \[ ] 已记录（更新了 OpenAPI/Swagger 规范）

92
docs/zh-CN/skills/article-writing/SKILL.md Normal file
View File

@@ -0,0 +1,92 @@
---
name: article-writing
description: 根据提供的示例或品牌指导，以独特的语气撰写文章、指南、博客帖子、教程、新闻简报等长篇内容。当用户需要超过一段的精致书面内容时使用，尤其是当语气一致性、结构和可信度至关重要时。
origin: ECC
---
# 文章写作
撰写听起来像真人或真实品牌的长篇内容，而非通用的 AI 输出。
## 何时使用
* 起草博客文章、散文、发布帖、指南、教程或新闻简报时
* 将笔记、转录稿或研究转化为精炼文章时
* 根据示例匹配现有的创始人、运营者或品牌声音时
* 强化已有长篇文稿的结构、节奏和论据时
## 核心规则
1. **以具体事物开头**：示例、输出、轶事、数据、截图描述或代码块。
2. 先展示示例，再解释。
3. 倾向于简短、直接的句子，而非冗长的句子。
4. 尽可能使用具体且有来源的数据。
5. **绝不编造**传记事实、公司指标或客户证据。
## 声音捕捉工作流
如果用户需要特定的声音，请收集以下一项或多项：
* 已发表的文章
* 新闻简报
* X / LinkedIn 帖子
* 文档或备忘录
* 简短的风格指南
然后提取：
* 句子长度和节奏
* 声音是正式、对话式还是犀利的
* 偏好的修辞手法，如括号、列表、断句或设问
* 对幽默、观点和反主流框架的容忍度
* 格式习惯，如标题、项目符号、代码块和引用块
如果未提供声音参考，则默认为直接、运营者风格的声音：具体、实用，且少用夸张宣传。
## 禁止模式
删除并重写以下任何内容：
* 通用开头，如“在当今快速发展的格局中”
* 填充性过渡词，如“此外”和“而且”
* 夸张短语，如“游戏规则改变者”、“尖端”或“革命性的”
* 没有证据支持的模糊主张
* 没有提供上下文支持的传记或可信度声明
## 写作流程
1. 明确受众和目的。
2. 构建一个框架大纲，每个部分一个目的。
3. 每个部分都以证据、示例或场景开头。
4. 只在下一句话有其存在价值的地方展开。
5. 删除任何听起来像模板化或自我祝贺的内容。
## 结构指导
### 技术指南
* 以读者能获得什么开头
* 在每个主要部分使用代码或终端示例
* 以具体的要点结束，而非软性的总结
### 散文 / 观点文章
* 以张力、矛盾或尖锐的观察开头
* 每个部分只保持一个论点线索
* 使用能支撑观点的示例
### 新闻简报
* 保持首屏内容有力
* 将见解与更新结合，而非日记式填充
* 使用清晰的部分标签和易于浏览的结构
## 质量检查
交付前：
* 根据提供的来源核实事实主张
* 删除填充词和企业语言
* 确认声音与提供的示例匹配
* 确保每个部分都添加了新信息
* 检查针对目标平台的格式

13
docs/zh-CN/skills/backend-patterns/SKILL.md
View File

@@ -1,12 +1,23 @@
---
name: backend-patterns
description: 后端架构模式、API设计、数据库优化以及针对Node.js、Express和Next.js API路由的服务器端最佳实践。
description: 后端架构模式、API设计、数据库优化以及适用于Node.js、Express和Next.js API路由的服务器端最佳实践。
origin: ECC
---
# 后端开发模式
用于可扩展服务器端应用程序的后端架构模式和最佳实践。
## 何时激活
* 设计 REST 或 GraphQL API 端点时
* 实现仓储层、服务层或控制器层时
* 优化数据库查询（N+1问题、索引、连接池）时
* 添加缓存（Redis、内存缓存、HTTP 缓存头）时
* 设置后台作业或异步处理时
* 为 API 构建错误处理和验证结构时
* 构建中间件（认证、日志记录、速率限制）时
## API 设计模式
### RESTful API 结构

12
docs/zh-CN/skills/clickhouse-io/SKILL.md
View File

@@ -1,12 +1,22 @@
---
name: clickhouse-io
description: ClickHouse数据库模式、查询优化、分析和数据工程最佳实践，适用于高性能分析工作负载。
description: ClickHouse数据库模式、查询优化、分析以及高性能分析工作负载的数据工程最佳实践。
origin: ECC
---
# ClickHouse 分析模式
用于高性能分析和数据工程的 ClickHouse 特定模式。
## 何时激活
* 设计 ClickHouse 表架构（MergeTree 引擎选择）
* 编写分析查询（聚合、窗口函数、连接）
* 优化查询性能（分区裁剪、投影、物化视图）
* 摄取大量数据（批量插入、Kafka 集成）
* 为分析目的从 PostgreSQL/MySQL 迁移到 ClickHouse
* 实现实时仪表板或时间序列分析
## 概述
ClickHouse 是一个用于在线分析处理 (OLAP) 的列式数据库管理系统 (DBMS)。它针对大型数据集上的快速分析查询进行了优化。

10
docs/zh-CN/skills/coding-standards/SKILL.md
View File

@@ -1,12 +1,22 @@
---
name: coding-standards
description: 适用于TypeScript、JavaScript、React和Node.js开发的通用编码标准、最佳实践和模式。
origin: ECC
---
# 编码标准与最佳实践
适用于所有项目的通用编码标准。
## 何时激活
* 开始新项目或新模块时
* 审查代码质量和可维护性时
* 重构现有代码以遵循约定时
* 强制执行命名、格式或结构一致性时
* 设置代码检查、格式化或类型检查规则时
* 引导新贡献者熟悉编码规范时
## 代码质量原则
### 1. 可读性优先

28
docs/zh-CN/skills/configure-ecc/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: configure-ecc
description: Everything Claude Code 的交互式安装程序 — 引导用户选择并安装技能和规则到用户级或项目级目录，验证路径，并可选择性地优化已安装的文件。
description: Everything Claude Code 的交互式安装程序 — 引导用户选择并安装技能和规则到用户级或项目级目录，验证路径，并可选择优化已安装文件。
origin: ECC
---
# 配置 Everything Claude Code (ECC)
@@ -83,25 +84,26 @@ Options:
对于每个选定的类别，打印下面的完整技能列表，并要求用户确认或取消选择特定的技能。如果列表超过 4 项，将列表打印为文本，并使用 `AskUserQuestion`，提供一个 "安装所有列出项" 的选项，以及一个 "其他" 选项供用户粘贴特定名称。
**类别：框架与语言（16 项技能）**
**类别：框架与语言（17 项技能）**
| 技能 | 描述 |
|-------|-------------|
| `backend-patterns` | Node.js/Express/Next.js 的后端架构、API 设计、服务器端最佳实践 |
| `coding-standards` | TypeScript、JavaScript、React、Node.js 的通用编码标准 |
| `django-patterns` | Django 架构、使用 DRF 的 REST API、ORM、缓存、信号、中间件 |
| `django-security` | Django 安全：身份验证、CSRF、SQL 注入、XSS 防护 |
| `django-tdd` | 使用 pytest-django、factory\_boy、模拟、覆盖率的 Django 测试 |
| `django-security` | Django 安全性：身份验证、CSRF、SQL 注入、XSS 防护 |
| `django-tdd` | 使用 pytest-django、factory\_boy、模拟、覆盖率进行 Django 测试 |
| `django-verification` | Django 验证循环：迁移、代码检查、测试、安全扫描 |
| `frontend-patterns` | React、Next.js、状态管理、性能、UI 模式 |
| `golang-patterns` | 地道的 Go 模式、健壮 Go 应用程序的约定 |
| `golang-testing` | Go 测试：表格驱动测试、子测试、基准测试、模糊测试 |
| `frontend-slides` | 零依赖的 HTML 演示文稿、样式预览以及 PPTX 到网页的转换 |
| `golang-patterns` | 地道的 Go 模式、构建健壮 Go 应用程序的约定 |
| `golang-testing` | Go 测试：表驱动测试、子测试、基准测试、模糊测试 |
| `java-coding-standards` | Spring Boot 的 Java 编码标准：命名、不可变性、Optional、流 |
| `python-patterns` | Pythonic 惯用法、PEP 8、类型提示、最佳实践 |
| `python-testing` | 使用 pytest、TDD、夹具、模拟、参数化的 Python 测试 |
| `python-testing` | 使用 pytest、TDD、固件、模拟、参数化进行 Python 测试 |
| `springboot-patterns` | Spring Boot 架构、REST API、分层服务、缓存、异步 |
| `springboot-security` | Spring Security：身份验证/授权、验证、CSRF、密钥、速率限制 |
| `springboot-tdd` | 使用 JUnit 5、Mockito、MockMvc、Testcontainers 的 Spring Boot TDD |
| `springboot-tdd` | 使用 JUnit 5、Mockito、MockMvc、Testcontainers 进行 Spring Boot TDD |
| `springboot-verification` | Spring Boot 验证：构建、静态分析、测试、安全扫描 |
**类别：数据库（3 项技能）**
@@ -125,6 +127,16 @@ Options:
| `tdd-workflow` | 强制要求 TDD，覆盖率 80% 以上：单元测试、集成测试、端到端测试 |
| `verification-loop` | 验证和质量循环模式 |
**类别：业务与内容（5 项技能）**
| 技能 | 描述 |
|-------|-------------|
| `article-writing` | 使用笔记、示例或源文档，以指定的口吻进行长篇写作 |
| `content-engine` | 多平台社交内容、脚本和内容再利用工作流 |
| `market-research` | 带有来源标注的市场、竞争对手、基金和技术研究 |
| `investor-materials` | 宣传文稿、一页简介、投资者备忘录和财务模型 |
| `investor-outreach` | 个性化的投资者冷邮件、熟人介绍和后续跟进 |
**独立技能**
| 技能 | 描述 |

97
docs/zh-CN/skills/content-engine/SKILL.md Normal file
View File

@@ -0,0 +1,97 @@
---
name: content-engine
description: 为X、LinkedIn、TikTok、YouTube、新闻通讯和跨平台重新利用的多平台活动创建平台原生内容系统。适用于当用户需要社交媒体帖子、帖子串、脚本、内容日历，或一个源资产在多个平台上清晰适配时。
origin: ECC
---
# 内容引擎
将一个想法转化为强大的、平台原生的内容，而不是到处发布相同的东西。
## 何时激活
* 撰写 X 帖子或主题串时
* 起草 LinkedIn 帖子或发布更新时
* 编写短视频或 YouTube 解说稿时
* 将文章、播客、演示或文档改写成社交内容时
* 围绕发布、里程碑或主题制定轻量级内容计划时
## 首要问题
明确：
* 来源素材：我们从什么内容改编
* 受众：构建者、投资者、客户、运营者，还是普通受众
* 平台：X、LinkedIn、TikTok、YouTube、新闻简报，还是多平台
* 目标：品牌认知、转化、招聘、建立权威、支持发布，还是互动参与
## 核心规则
1. 为平台进行适配。不要交叉发布相同的文案。
2. 开篇钩子比总结更重要。
3. 每篇帖子应承载一个清晰的想法。
4. 使用具体细节而非口号。
5. 保持呼吁行动小而清晰。
## 平台指南
### X
* 开场要快
* 每个帖子或主题串中的每条推文只讲一个想法
* 除非必要，避免在主文中放置链接
* 避免滥用话题标签
### LinkedIn
* 第一行要强有力
* 使用短段落
* 围绕经验教训、结果和要点进行更明确的框架构建
### TikTok / 短视频
* 前 3 秒必须抓住注意力
* 围绕视觉内容编写脚本，而不仅仅是旁白
* 一个演示、一个主张、一个行动号召
### YouTube
* 尽早展示结果
* 按章节构建内容
* 每 20-30 秒刷新一次视觉内容
### 新闻简报
* 提供一个清晰的视角，而不是一堆不相关的内容
* 使章节标题易于浏览
* 让开篇段落真正发挥作用
## 内容再利用流程
默认级联：
1. 锚定素材：文章、视频、演示、备忘录或发布文档
2. 提取 3-7 个原子化想法
3. 撰写平台原生的变体内容
4. 修剪不同输出内容中的重复部分
5. 使行动号召与平台意图保持一致
## 交付物
当被要求进行一项宣传活动时，请返回：
* 核心角度
* 针对特定平台的草稿
* 可选的发布顺序
* 可选的行动号召变体
* 发布前所需的任何缺失信息
## 质量门槛
在交付前检查：
* 每份草稿读起来都符合其平台原生风格
* 开篇钩子强大且具体
* 没有通用的炒作语言
* 除非特别要求，否则各平台间没有重复文案
* 行动号召与内容和受众相匹配

161
docs/zh-CN/skills/content-hash-cache-pattern/SKILL.md Normal file
View File

@@ -0,0 +1,161 @@
---
name: content-hash-cache-pattern
description: 使用SHA-256内容哈希缓存昂贵的文件处理结果——路径无关、自动失效、服务层分离。
origin: ECC
---
# 内容哈希文件缓存模式
使用 SHA-256 内容哈希作为缓存键，缓存昂贵的文件处理结果（PDF 解析、文本提取、图像分析）。与基于路径的缓存不同，此方法在文件移动/重命名后仍然有效，并在内容更改时自动失效。
## 何时激活
* 构建文件处理管道时（PDF、图像、文本提取）
* 处理成本高且同一文件被重复处理时
* 需要一个 `--cache/--no-cache` CLI 选项时
* 希望在不修改现有纯函数的情况下为其添加缓存时
## 核心模式
### 1. 基于内容哈希的缓存键
使用文件内容（而非路径）作为缓存键：
```python
import hashlib
from pathlib import Path
_HASH_CHUNK_SIZE = 65536 # 64KB chunks for large files
def compute_file_hash(path: Path) -> str:
"""SHA-256 of file contents (chunked for large files)."""
if not path.is_file():
raise FileNotFoundError(f"File not found: {path}")
sha256 = hashlib.sha256()
with open(path, "rb") as f:
while True:
chunk = f.read(_HASH_CHUNK_SIZE)
if not chunk:
break
sha256.update(chunk)
return sha256.hexdigest()
```
**为什么使用内容哈希？** 文件重命名/移动 = 缓存命中。内容更改 = 自动失效。无需索引文件。
### 2. 用于缓存条目的冻结数据类
```python
from dataclasses import dataclass
@dataclass(frozen=True, slots=True)
class CacheEntry:
file_hash: str
source_path: str
document: ExtractedDocument # The cached result
```
### 3. 基于文件的缓存存储
每个缓存条目都存储为 `{hash}.json` —— 通过哈希实现 O(1) 查找，无需索引文件。
```python
import json
from typing import Any
def write_cache(cache_dir: Path, entry: CacheEntry) -> None:
cache_dir.mkdir(parents=True, exist_ok=True)
cache_file = cache_dir / f"{entry.file_hash}.json"
data = serialize_entry(entry)
cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:
cache_file = cache_dir / f"{file_hash}.json"
if not cache_file.is_file():
return None
try:
raw = cache_file.read_text(encoding="utf-8")
data = json.loads(raw)
return deserialize_entry(data)
except (json.JSONDecodeError, ValueError, KeyError):
return None # Treat corruption as cache miss
```
### 4. 服务层包装器（单一职责原则）
保持处理函数的纯净性。将缓存作为一个单独的服务层添加。
```python
def extract_with_cache(
file_path: Path,
*,
cache_enabled: bool = True,
cache_dir: Path = Path(".cache"),
) -> ExtractedDocument:
"""Service layer: cache check -> extraction -> cache write."""
if not cache_enabled:
return extract_text(file_path) # Pure function, no cache knowledge
file_hash = compute_file_hash(file_path)
# Check cache
cached = read_cache(cache_dir, file_hash)
if cached is not None:
logger.info("Cache hit: %s (hash=%s)", file_path.name, file_hash[:12])
return cached.document
# Cache miss -> extract -> store
logger.info("Cache miss: %s (hash=%s)", file_path.name, file_hash[:12])
doc = extract_text(file_path)
entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)
write_cache(cache_dir, entry)
return doc
```
## 关键设计决策
| 决策 | 理由 |
|----------|-----------|
| SHA-256 内容哈希 | 与路径无关，内容更改时自动失效 |
| `{hash}.json` 文件命名 | O(1) 查找，无需索引文件 |
| 服务层包装器 | 单一职责原则：提取功能保持纯净，缓存是独立的关注点 |
| 手动 JSON 序列化 | 完全控制冻结数据类的序列化 |
| 损坏时返回 `None` | 优雅降级，在下次运行时重新处理 |
| `cache_dir.mkdir(parents=True)` | 在首次写入时惰性创建目录 |
## 最佳实践
* **哈希内容，而非路径** —— 路径会变，内容标识不变
* 对大文件进行哈希时**分块处理** —— 避免将整个文件加载到内存中
* **保持处理函数的纯净性** —— 它们不应了解任何关于缓存的信息
* **记录缓存命中/未命中**，并使用截断的哈希值以便调试
* **优雅地处理损坏** —— 将无效的缓存条目视为未命中，永不崩溃
## 应避免的反模式
```python
# BAD: Path-based caching (breaks on file move/rename)
cache = {"/path/to/file.pdf": result}
# BAD: Adding cache logic inside the processing function (SRP violation)
def extract_text(path, *, cache_enabled=False, cache_dir=None):
if cache_enabled: # Now this function has two responsibilities
...
# BAD: Using dataclasses.asdict() with nested frozen dataclasses
# (can cause issues with complex nested types)
data = dataclasses.asdict(entry) # Use manual serialization instead
```
## 适用场景
* 文件处理管道（PDF 解析、OCR、文本提取、图像分析）
* 受益于 `--cache/--no-cache` 选项的 CLI 工具
* 跨多次运行出现相同文件的批处理
* 在不修改现有纯函数的情况下为其添加缓存
## 不适用场景
* 必须始终保持最新的数据（实时数据流）
* 缓存条目可能极其庞大的情况（应考虑使用流式处理）
* 结果依赖于文件内容之外参数的情况（例如，不同的提取配置）

17
docs/zh-CN/skills/continuous-learning-v2/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: continuous-learning-v2
description: 基于本能的学习系统，通过钩子观察会话，创建具有置信度评分的原子本能，并将其演化为技能/命令/代理。
description: 基于本能的学习系统，通过钩子观察会话，创建具有置信度评分的原子本能，并将其进化为技能/命令/代理。
origin: ECC
version: 2.0.0
---
@@ -8,6 +9,16 @@ version: 2.0.0
一个高级学习系统，通过原子化的“本能”——带有置信度评分的小型习得行为——将你的 Claude Code 会话转化为可重用的知识。
部分灵感来源于 [humanplane](https://github.com/humanplane) 的 Homunculus 项目。
## 何时激活
* 设置从 Claude Code 会话中自动学习时
* 通过钩子配置基于本能的行为提取时
* 调整学习行为的置信度阈值时
* 审查、导出或导入本能库时
* 将本能进化为完整技能、命令或代理时
## v2 的新特性
| 特性 | v1 | v2 |
@@ -282,8 +293,8 @@ v2 与 v1 完全兼容：
## 相关链接
* [技能创建器](https://skill-creator.app) - 从仓库历史生成本能
* Homunculus - 启发 v2 架构的社区项目（原子观察、置信度评分、本能演化管线）
* [长文指南](https://x.com/affaanmustafa/status/2014040193557471352) - 持续学习部分
* Homunculus - 启发了 v2 基于本能的架构的社区项目（原子观察、置信度评分、本能进化管道）
* [长篇指南](https://x.com/affaanmustafa/status/2014040193557471352) - 持续学习部分
***

13
docs/zh-CN/skills/continuous-learning/SKILL.md
View File

@@ -1,12 +1,21 @@
---
name: continuous-learning
description: 自动从Claude Code会话中提取可重用模式，并将其保存为学习技能供未来使用。
description: 自动从Claude Code会话中提取可重复使用的模式，并将其保存为学习到的技能以供将来使用。
origin: ECC
---
# 持续学习技能
自动评估 Claude Code 会话的结尾，以提取可重用的模式，这些模式可以保存为学习到的技能。
## 何时激活
* 设置从 Claude Code 会话中自动提取模式
* 为会话评估配置停止钩子
* 在 `~/.claude/skills/learned/` 中审查或整理已学习的技能
* 调整提取阈值或模式类别
* 比较 v1（本方法）与 v2（基于本能的方法）
## 工作原理
此技能作为 **停止钩子** 在每个会话结束时运行：
@@ -83,7 +92,7 @@ description: 自动从Claude Code会话中提取可重用模式，并将其保
## 对比说明（研究：2025年1月）
### 与 Homunculus 对比
### 与 Homunculus 的对比
Homunculus v2 采用了更复杂的方法：

183
docs/zh-CN/skills/cost-aware-llm-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,183 @@
---
name: cost-aware-llm-pipeline
description: LLM API 使用成本优化模式 —— 基于任务复杂度的模型路由、预算跟踪、重试逻辑和提示缓存。
origin: ECC
---
# 成本感知型 LLM 流水线
在保持质量的同时控制 LLM API 成本的模式。将模型路由、预算跟踪、重试逻辑和提示词缓存组合成一个可组合的流水线。
## 何时激活
* 构建调用 LLM API（Claude、GPT 等）的应用程序时
* 处理具有不同复杂度的批量项目时
* 需要将 API 支出控制在预算范围内时
* 需要在复杂任务上优化成本而不牺牲质量时
## 核心概念
### 1. 根据任务复杂度进行模型路由
自动为简单任务选择更便宜的模型，为复杂任务保留昂贵的模型。
```python
MODEL_SONNET = "claude-sonnet-4-6"
MODEL_HAIKU = "claude-haiku-4-5-20251001"
_SONNET_TEXT_THRESHOLD = 10_000 # chars
_SONNET_ITEM_THRESHOLD = 30 # items
def select_model(
text_length: int,
item_count: int,
force_model: str | None = None,
) -> str:
"""Select model based on task complexity."""
if force_model is not None:
return force_model
if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
return MODEL_SONNET # Complex task
return MODEL_HAIKU # Simple task (3-4x cheaper)
```
### 2. 不可变的成本跟踪
使用冻结的数据类跟踪累计支出。每个 API 调用都会返回一个新的跟踪器 —— 永不改变状态。
```python
from dataclasses import dataclass
@dataclass(frozen=True, slots=True)
class CostRecord:
model: str
input_tokens: int
output_tokens: int
cost_usd: float
@dataclass(frozen=True, slots=True)
class CostTracker:
budget_limit: float = 1.00
records: tuple[CostRecord, ...] = ()
def add(self, record: CostRecord) -> "CostTracker":
"""Return new tracker with added record (never mutates self)."""
return CostTracker(
budget_limit=self.budget_limit,
records=(*self.records, record),
)
@property
def total_cost(self) -> float:
return sum(r.cost_usd for r in self.records)
@property
def over_budget(self) -> bool:
return self.total_cost > self.budget_limit
```
### 3. 窄范围重试逻辑
仅在暂时性错误时重试。对于认证或错误请求错误，快速失败。
```python
from anthropic import (
APIConnectionError,
InternalServerError,
RateLimitError,
)
_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
_MAX_RETRIES = 3
def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
"""Retry only on transient errors, fail fast on others."""
for attempt in range(max_retries):
try:
return func()
except _RETRYABLE_ERRORS:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Exponential backoff
# AuthenticationError, BadRequestError etc. → raise immediately
```
### 4. 提示词缓存
缓存长的系统提示词，以避免在每个请求上重新发送它们。
```python
messages = [
{
"role": "user",
"content": [
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"}, # Cache this
},
{
"type": "text",
"text": user_input, # Variable part
},
],
}
]
```
## 组合
将所有四种技术组合到一个流水线函数中：
```python
def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
# 1. Route model
model = select_model(len(text), estimated_items, config.force_model)
# 2. Check budget
if tracker.over_budget:
raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
# 3. Call with retry + caching
response = call_with_retry(lambda: client.messages.create(
model=model,
messages=build_cached_messages(system_prompt, text),
))
# 4. Track cost (immutable)
record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
tracker = tracker.add(record)
return parse_result(response), tracker
```
## 价格参考（2025-2026）
| 模型 | 输入（美元/百万令牌） | 输出（美元/百万令牌） | 相对成本 |
|-------|---------------------|----------------------|---------------|
| Haiku 4.5 | $0.80 | $4.00 | 1x |
| Sonnet 4.6 | $3.00 | $15.00 | ~4x |
| Opus 4.5 | $15.00 | $75.00 | ~19x |
## 最佳实践
* **从最便宜的模型开始**，仅在达到复杂度阈值时才路由到昂贵的模型
* **在处理批次之前设置明确的预算限制** —— 尽早失败而不是超支
* **记录模型选择决策**，以便您可以根据实际数据调整阈值
* **对于超过 1024 个令牌的系统提示词，使用提示词缓存** —— 既能节省成本，又能降低延迟
* **切勿在认证或验证错误时重试** —— 仅针对暂时性故障（网络、速率限制、服务器错误）重试
## 应避免的反模式
* 无论复杂度如何，对所有请求都使用最昂贵的模型
* 对所有错误都进行重试（在永久性故障上浪费预算）
* 改变成本跟踪状态（使调试和审计变得困难）
* 在整个代码库中硬编码模型名称（使用常量或配置）
* 对重复的系统提示词忽略提示词缓存
## 适用场景
* 任何调用 Claude、OpenAI 或类似 LLM API 的应用程序
* 成本快速累积的批处理流水线
* 需要智能路由的多模型架构
* 需要预算护栏的生产系统

723
docs/zh-CN/skills/cpp-coding-standards/SKILL.md Normal file
View File

@@ -0,0 +1,723 @@
---
name: cpp-coding-standards
description: 基于C++核心指南（isocpp.github.io）的C++编码标准。在编写、审查或重构C++代码时使用，以强制实施现代、安全和惯用的实践。
origin: ECC
---
# C++ 编码标准（C++ 核心准则）
源自 [C++ 核心准则](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) 的现代 C++（C++17/20/23）综合编码标准。强制执行类型安全、资源安全、不变性和清晰性。
## 何时使用
* 编写新的 C++ 代码（类、函数、模板）
* 审查或重构现有的 C++ 代码
* 在 C++ 项目中做出架构决策
* 在 C++ 代码库中强制执行一致的风格
* 在语言特性之间做出选择（例如，`enum` 对比 `enum class`，原始指针对比智能指针）
### 何时不应使用
* 非 C++ 项目
* 无法采用现代 C++ 特性的遗留 C 代码库
* 特定准则与硬件限制冲突的嵌入式/裸机环境（选择性适配）
## 贯穿性原则
这些主题在整个准则中反复出现，并构成了基础：
1. **处处使用 RAII** (P.8, R.1, E.6, CP.20)：将资源生命周期绑定到对象生命周期
2. **默认为不可变性** (P.10, Con.1-5, ES.25)：从 `const`/`constexpr` 开始；可变性是例外
3. **类型安全** (P.4, I.4, ES.46-49, Enum.3)：使用类型系统在编译时防止错误
4. **表达意图** (P.3, F.1, NL.1-2, T.10)：名称、类型和概念应传达目的
5. **最小化复杂性** (F.2-3, ES.5, Per.4-5)：简单的代码就是正确的代码
6. **值语义优于指针语义** (C.10, R.3-5, F.20, CP.31)：优先按值返回和作用域对象
## 哲学与接口 (P.\*, I.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **P.1** | 直接在代码中表达想法 |
| **P.3** | 表达意图 |
| **P.4** | 理想情况下，程序应是静态类型安全的 |
| **P.5** | 优先编译时检查而非运行时检查 |
| **P.8** | 不要泄漏任何资源 |
| **P.10** | 优先不可变数据而非可变数据 |
| **I.1** | 使接口明确 |
| **I.2** | 避免非 const 全局变量 |
| **I.4** | 使接口精确且强类型化 |
| **I.11** | 切勿通过原始指针或引用转移所有权 |
| **I.23** | 保持函数参数数量少 |
### 应该做
```cpp
// P.10 + I.4: Immutable, strongly typed interface
struct Temperature {
double kelvin;
};
Temperature boil(const Temperature& water);
```
### 不应该做
```cpp
// Weak interface: unclear ownership, unclear units
double boil(double* temp);
// Non-const global variable
int g_counter = 0; // I.2 violation
```
## 函数 (F.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **F.1** | 将有意义的操作打包为精心命名的函数 |
| **F.2** | 函数应执行单一逻辑操作 |
| **F.3** | 保持函数简短简单 |
| **F.4** | 如果函数可能在编译时求值，则将其声明为 `constexpr` |
| **F.6** | 如果你的函数绝不能抛出异常，则将其声明为 `noexcept` |
| **F.8** | 优先纯函数 |
| **F.16** | 对于 "输入" 参数，按值传递廉价可复制类型，其他类型通过 `const&` 传递 |
| **F.20** | 对于 "输出" 值，优先返回值而非输出参数 |
| **F.21** | 要返回多个 "输出" 值，优先返回结构体 |
| **F.43** | 切勿返回指向局部对象的指针或引用 |
### 参数传递
```cpp
// F.16: Cheap types by value, others by const&
void print(int x); // cheap: by value
void analyze(const std::string& data); // expensive: by const&
void transform(std::string s); // sink: by value (will move)
// F.20 + F.21: Return values, not output parameters
struct ParseResult {
std::string token;
int position;
};
ParseResult parse(std::string_view input); // GOOD: return struct
// BAD: output parameters
void parse(std::string_view input,
std::string& token, int& pos); // avoid this
```
### 纯函数和 constexpr
```cpp
// F.4 + F.8: Pure, constexpr where possible
constexpr int factorial(int n) noexcept {
return (n <= 1) ? 1 : n * factorial(n - 1);
}
static_assert(factorial(5) == 120);
```
### 反模式
* 从函数返回 `T&&` (F.45)
* 使用 `va_arg` / C 风格可变参数 (F.55)
* 在传递给其他线程的 lambda 中通过引用捕获 (F.53)
* 返回 `const T`，这会抑制移动语义 (F.49)
## 类与类层次结构 (C.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **C.2** | 如果存在不变式，使用 `class`；如果数据成员独立变化，使用 `struct` |
| **C.9** | 最小化成员的暴露 |
| **C.20** | 如果你能避免定义默认操作，就这么做（零规则） |
| **C.21** | 如果你定义或 `=delete` 任何拷贝/移动/析构函数，则处理所有（五规则） |
| **C.35** | 基类析构函数：公开虚函数或受保护非虚函数 |
| **C.41** | 构造函数应创建完全初始化的对象 |
| **C.46** | 将单参数构造函数声明为 `explicit` |
| **C.67** | 多态类应禁止公开拷贝/移动 |
| **C.128** | 虚函数：精确指定 `virtual`、`override` 或 `final` 中的一个 |
### 零规则
```cpp
// C.20: Let the compiler generate special members
struct Employee {
std::string name;
std::string department;
int id;
// No destructor, copy/move constructors, or assignment operators needed
};
```
### 五规则
```cpp
// C.21: If you must manage a resource, define all five
class Buffer {
public:
explicit Buffer(std::size_t size)
: data_(std::make_unique<char[]>(size)), size_(size) {}
~Buffer() = default;
Buffer(const Buffer& other)
: data_(std::make_unique<char[]>(other.size_)), size_(other.size_) {
std::copy_n(other.data_.get(), size_, data_.get());
}
Buffer& operator=(const Buffer& other) {
if (this != &other) {
auto new_data = std::make_unique<char[]>(other.size_);
std::copy_n(other.data_.get(), other.size_, new_data.get());
data_ = std::move(new_data);
size_ = other.size_;
}
return *this;
}
Buffer(Buffer&&) noexcept = default;
Buffer& operator=(Buffer&&) noexcept = default;
private:
std::unique_ptr<char[]> data_;
std::size_t size_;
};
```
### 类层次结构
```cpp
// C.35 + C.128: Virtual destructor, use override
class Shape {
public:
virtual ~Shape() = default;
virtual double area() const = 0; // C.121: pure interface
};
class Circle : public Shape {
public:
explicit Circle(double r) : radius_(r) {}
double area() const override { return 3.14159 * radius_ * radius_; }
private:
double radius_;
};
```
### 反模式
* 在构造函数/析构函数中调用虚函数 (C.82)
* 在非平凡类型上使用 `memset`/`memcpy` (C.90)
* 为虚函数和重写函数提供不同的默认参数 (C.140)
* 将数据成员设为 `const` 或引用，这会抑制移动/拷贝 (C.12)
## 资源管理 (R.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **R.1** | 使用 RAII 自动管理资源 |
| **R.3** | 原始指针 (`T*`) 是非拥有的 |
| **R.5** | 优先作用域对象；不要不必要地在堆上分配 |
| **R.10** | 避免 `malloc()`/`free()` |
| **R.11** | 避免显式调用 `new` 和 `delete` |
| **R.20** | 使用 `unique_ptr` 或 `shared_ptr` 表示所有权 |
| **R.21** | 除非共享所有权，否则优先 `unique_ptr` 而非 `shared_ptr` |
| **R.22** | 使用 `make_shared()` 来创建 `shared_ptr` |
### 智能指针使用
```cpp
// R.11 + R.20 + R.21: RAII with smart pointers
auto widget = std::make_unique<Widget>("config"); // unique ownership
auto cache = std::make_shared<Cache>(1024); // shared ownership
// R.3: Raw pointer = non-owning observer
void render(const Widget* w) { // does NOT own w
if (w) w->draw();
}
render(widget.get());
```
### RAII 模式
```cpp
// R.1: Resource acquisition is initialization
class FileHandle {
public:
explicit FileHandle(const std::string& path)
: handle_(std::fopen(path.c_str(), "r")) {
if (!handle_) throw std::runtime_error("Failed to open: " + path);
}
~FileHandle() {
if (handle_) std::fclose(handle_);
}
FileHandle(const FileHandle&) = delete;
FileHandle& operator=(const FileHandle&) = delete;
FileHandle(FileHandle&& other) noexcept
: handle_(std::exchange(other.handle_, nullptr)) {}
FileHandle& operator=(FileHandle&& other) noexcept {
if (this != &other) {
if (handle_) std::fclose(handle_);
handle_ = std::exchange(other.handle_, nullptr);
}
return *this;
}
private:
std::FILE* handle_;
};
```
### 反模式
* 裸 `new`/`delete` (R.11)
* C++ 代码中的 `malloc()`/`free()` (R.10)
* 在单个表达式中进行多次资源分配 (R.13 -- 异常安全风险)
* 在 `unique_ptr` 足够时使用 `shared_ptr` (R.21)
## 表达式与语句 (ES.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **ES.5** | 保持作用域小 |
| **ES.20** | 始终初始化对象 |
| **ES.23** | 优先 `{}` 初始化语法 |
| **ES.25** | 除非打算修改，否则将对象声明为 `const` 或 `constexpr` |
| **ES.28** | 使用 lambda 进行 `const` 变量的复杂初始化 |
| **ES.45** | 避免魔法常量；使用符号常量 |
| **ES.46** | 避免有损的算术转换 |
| **ES.47** | 使用 `nullptr` 而非 `0` 或 `NULL` |
| **ES.48** | 避免强制类型转换 |
| **ES.50** | 不要丢弃 `const` |
### 初始化
```cpp
// ES.20 + ES.23 + ES.25: Always initialize, prefer {}, default to const
const int max_retries{3};
const std::string name{"widget"};
const std::vector<int> primes{2, 3, 5, 7, 11};
// ES.28: Lambda for complex const initialization
const auto config = [&] {
Config c;
c.timeout = std::chrono::seconds{30};
c.retries = max_retries;
c.verbose = debug_mode;
return c;
}();
```
### 反模式
* 未初始化的变量 (ES.20)
* 使用 `0` 或 `NULL` 作为指针 (ES.47 -- 使用 `nullptr`)
* C 风格强制类型转换 (ES.48 -- 使用 `static_cast`、`const_cast` 等)
* 丢弃 `const` (ES.50)
* 没有命名常量的魔法数字 (ES.45)
* 混合有符号和无符号算术 (ES.100)
* 在嵌套作用域中重用名称 (ES.12)
## 错误处理 (E.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **E.1** | 在设计早期制定错误处理策略 |
| **E.2** | 抛出异常以表示函数无法执行其分配的任务 |
| **E.6** | 使用 RAII 防止泄漏 |
| **E.12** | 当抛出异常不可能或不可接受时，使用 `noexcept` |
| **E.14** | 使用专门设计的用户定义类型作为异常 |
| **E.15** | 按值抛出，按引用捕获 |
| **E.16** | 析构函数、释放和 swap 绝不能失败 |
| **E.17** | 不要试图在每个函数中捕获每个异常 |
### 异常层次结构
```cpp
// E.14 + E.15: Custom exception types, throw by value, catch by reference
class AppError : public std::runtime_error {
public:
using std::runtime_error::runtime_error;
};
class NetworkError : public AppError {
public:
NetworkError(const std::string& msg, int code)
: AppError(msg), status_code(code) {}
int status_code;
};
void fetch_data(const std::string& url) {
// E.2: Throw to signal failure
throw NetworkError("connection refused", 503);
}
void run() {
try {
fetch_data("https://api.example.com");
} catch (const NetworkError& e) {
log_error(e.what(), e.status_code);
} catch (const AppError& e) {
log_error(e.what());
}
// E.17: Don't catch everything here -- let unexpected errors propagate
}
```
### 反模式
* 抛出内置类型，如 `int` 或字符串字面量 (E.14)
* 按值捕获（有切片风险） (E.15)
* 静默吞掉错误的空 catch 块
* 使用异常进行流程控制 (E.3)
* 基于全局状态（如 `errno`）的错误处理 (E.28)
## 常量与不可变性 (Con.\*)
### 所有规则
| 规则 | 摘要 |
|------|---------|
| **Con.1** | 默认情况下，使对象不可变 |
| **Con.2** | 默认情况下，使成员函数为 `const` |
| **Con.3** | 默认情况下，传递指向 `const` 的指针和引用 |
| **Con.4** | 对构造后不改变的值使用 `const` |
| **Con.5** | 对可在编译时计算的值使用 `constexpr` |
```cpp
// Con.1 through Con.5: Immutability by default
class Sensor {
public:
explicit Sensor(std::string id) : id_(std::move(id)) {}
// Con.2: const member functions by default
const std::string& id() const { return id_; }
double last_reading() const { return reading_; }
// Only non-const when mutation is required
void record(double value) { reading_ = value; }
private:
const std::string id_; // Con.4: never changes after construction
double reading_{0.0};
};
// Con.3: Pass by const reference
void display(const Sensor& s) {
std::cout << s.id() << ": " << s.last_reading() << '\n';
}
// Con.5: Compile-time constants
constexpr double PI = 3.14159265358979;
constexpr int MAX_SENSORS = 256;
```
## 并发与并行 (CP.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **CP.2** | 避免数据竞争 |
| **CP.3** | 最小化可写数据的显式共享 |
| **CP.4** | 从任务的角度思考，而非线程 |
| **CP.8** | 不要使用 `volatile` 进行同步 |
| **CP.20** | 使用 RAII，切勿使用普通的 `lock()`/`unlock()` |
| **CP.21** | 使用 `std::scoped_lock` 来获取多个互斥量 |
| **CP.22** | 持有锁时切勿调用未知代码 |
| **CP.42** | 不要在没有条件的情况下等待 |
| **CP.44** | 记得为你的 `lock_guard` 和 `unique_lock` 命名 |
| **CP.100** | 除非绝对必要，否则不要使用无锁编程 |
### 安全加锁
```cpp
// CP.20 + CP.44: RAII locks, always named
class ThreadSafeQueue {
public:
void push(int value) {
std::lock_guard<std::mutex> lock(mutex_); // CP.44: named!
queue_.push(value);
cv_.notify_one();
}
int pop() {
std::unique_lock<std::mutex> lock(mutex_);
// CP.42: Always wait with a condition
cv_.wait(lock, [this] { return !queue_.empty(); });
const int value = queue_.front();
queue_.pop();
return value;
}
private:
std::mutex mutex_; // CP.50: mutex with its data
std::condition_variable cv_;
std::queue<int> queue_;
};
```
### 多个互斥量
```cpp
// CP.21: std::scoped_lock for multiple mutexes (deadlock-free)
void transfer(Account& from, Account& to, double amount) {
std::scoped_lock lock(from.mutex_, to.mutex_);
from.balance_ -= amount;
to.balance_ += amount;
}
```
### 反模式
* 使用 `volatile` 进行同步 (CP.8 -- 它仅用于硬件 I/O)
* 分离线程 (CP.26 -- 生命周期管理变得几乎不可能)
* 未命名的锁保护：`std::lock_guard<std::mutex>(m);` 会立即销毁 (CP.44)
* 调用回调时持有锁 (CP.22 -- 死锁风险)
* 没有深厚专业知识就进行无锁编程 (CP.100)
## 模板与泛型编程 (T.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **T.1** | 使用模板来提高抽象级别 |
| **T.2** | 使用模板为多种参数类型表达算法 |
| **T.10** | 为所有模板参数指定概念 |
| **T.11** | 尽可能使用标准概念 |
| **T.13** | 对于简单概念，优先使用简写符号 |
| **T.43** | 优先 `using` 而非 `typedef` |
| **T.120** | 仅在确实需要时使用模板元编程 |
| **T.144** | 不要特化函数模板（改用重载） |
### 概念 (C++20)
```cpp
#include <concepts>
// T.10 + T.11: Constrain templates with standard concepts
template<std::integral T>
T gcd(T a, T b) {
while (b != 0) {
a = std::exchange(b, a % b);
}
return a;
}
// T.13: Shorthand concept syntax
void sort(std::ranges::random_access_range auto& range) {
std::ranges::sort(range);
}
// Custom concept for domain-specific constraints
template<typename T>
concept Serializable = requires(const T& t) {
{ t.serialize() } -> std::convertible_to<std::string>;
};
template<Serializable T>
void save(const T& obj, const std::string& path);
```
### 反模式
* 在可见命名空间中使用无约束模板 (T.47)
* 特化函数模板而非重载 (T.144)
* 在 `constexpr` 足够时使用模板元编程 (T.120)
* 使用 `typedef` 而非 `using` (T.43)
## 标准库 (SL.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **SL.1** | 尽可能使用库 |
| **SL.2** | 优先标准库而非其他库 |
| **SL.con.1** | 优先 `std::array` 或 `std::vector` 而非 C 数组 |
| **SL.con.2** | 默认情况下优先 `std::vector` |
| **SL.str.1** | 使用 `std::string` 来拥有字符序列 |
| **SL.str.2** | 使用 `std::string_view` 来引用字符序列 |
| **SL.io.50** | 避免 `endl`（使用 `'\n'` -- `endl` 会强制刷新） |
```cpp
// SL.con.1 + SL.con.2: Prefer vector/array over C arrays
const std::array<int, 4> fixed_data{1, 2, 3, 4};
std::vector<std::string> dynamic_data;
// SL.str.1 + SL.str.2: string owns, string_view observes
std::string build_greeting(std::string_view name) {
return "Hello, " + std::string(name) + "!";
}
// SL.io.50: Use '\n' not endl
std::cout << "result: " << value << '\n';
```
## 枚举 (Enum.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **Enum.1** | 优先枚举而非宏 |
| **Enum.3** | 优先 `enum class` 而非普通 `enum` |
| **Enum.5** | 不要对枚举项使用全大写 |
| **Enum.6** | 避免未命名的枚举 |
```cpp
// Enum.3 + Enum.5: Scoped enum, no ALL_CAPS
enum class Color { red, green, blue };
enum class LogLevel { debug, info, warning, error };
// BAD: plain enum leaks names, ALL_CAPS clashes with macros
enum { RED, GREEN, BLUE }; // Enum.3 + Enum.5 + Enum.6 violation
#define MAX_SIZE 100 // Enum.1 violation -- use constexpr
```
## 源文件与命名 (SF.*, NL.*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **SF.1** | 代码文件使用 `.cpp`，接口文件使用 `.h` |
| **SF.7** | 不要在头文件的全局作用域内写 `using namespace` |
| **SF.8** | 所有 `.h` 文件都应使用 `#include` 防护 |
| **SF.11** | 头文件应是自包含的 |
| **NL.5** | 避免在名称中编码类型信息（不要使用匈牙利命名法） |
| **NL.8** | 使用一致的命名风格 |
| **NL.9** | 仅宏名使用 ALL\_CAPS |
| **NL.10** | 优先使用 `underscore_style` 命名 |
### 头文件防护
```cpp
// SF.8: Include guard (or #pragma once)
#ifndef PROJECT_MODULE_WIDGET_H
#define PROJECT_MODULE_WIDGET_H
// SF.11: Self-contained -- include everything this header needs
#include <string>
#include <vector>
namespace project::module {
class Widget {
public:
explicit Widget(std::string name);
const std::string& name() const;
private:
std::string name_;
};
} // namespace project::module
#endif // PROJECT_MODULE_WIDGET_H
```
### 命名约定
```cpp
// NL.8 + NL.10: Consistent underscore_style
namespace my_project {
constexpr int max_buffer_size = 4096; // NL.9: not ALL_CAPS (it's not a macro)
class tcp_connection { // underscore_style class
public:
void send_message(std::string_view msg);
bool is_connected() const;
private:
std::string host_; // trailing underscore for members
int port_;
};
} // namespace my_project
```
### 反模式
* 在头文件的全局作用域内使用 `using namespace std;` (SF.7)
* 依赖包含顺序的头文件 (SF.10, SF.11)
* 匈牙利命名法，如 `strName`、`iCount` (NL.5)
* 宏以外的事物使用 ALL\_CAPS (NL.9)
## 性能 (Per.\*)
### 关键规则
| 规则 | 摘要 |
|------|---------|
| **Per.1** | 不要无故优化 |
| **Per.2** | 不要过早优化 |
| **Per.6** | 没有测量数据，不要断言性能 |
| **Per.7** | 设计时应考虑便于优化 |
| **Per.10** | 依赖静态类型系统 |
| **Per.11** | 将计算从运行时移至编译时 |
| **Per.19** | 以可预测的方式访问内存 |
### 指导原则
```cpp
// Per.11: Compile-time computation where possible
constexpr auto lookup_table = [] {
std::array<int, 256> table{};
for (int i = 0; i < 256; ++i) {
table[i] = i * i;
}
return table;
}();
// Per.19: Prefer contiguous data for cache-friendliness
std::vector<Point> points; // GOOD: contiguous
std::vector<std::unique_ptr<Point>> indirect_points; // BAD: pointer chasing
```
### 反模式
* 在没有性能分析数据的情况下进行优化 (Per.1, Per.6)
* 选择“巧妙”的低级代码而非清晰的抽象 (Per.4, Per.5)
* 忽略数据布局和缓存行为 (Per.19)
## 快速参考检查清单
在标记 C++ 工作完成之前：
* \[ ] 没有裸 `new`/`delete` —— 使用智能指针或 RAII (R.11)
* \[ ] 对象在声明时初始化 (ES.20)
* \[ ] 变量默认是 `const`/`constexpr` (Con.1, ES.25)
* \[ ] 成员函数尽可能设为 `const` (Con.2)
* \[ ] 使用 `enum class` 而非普通 `enum` (Enum.3)
* \[ ] 使用 `nullptr` 而非 `0`/`NULL` (ES.47)
* \[ ] 没有窄化转换 (ES.46)
* \[ ] 没有 C 风格转换 (ES.48)
* \[ ] 单参数构造函数是 `explicit` (C.46)
* \[ ] 应用了零法则或五法则 (C.20, C.21)
* \[ ] 基类析构函数是 public virtual 或 protected non-virtual (C.35)
* \[ ] 模板使用概念进行约束 (T.10)
* \[ ] 头文件全局作用域内没有 `using namespace` (SF.7)
* \[ ] 头文件有包含防护且是自包含的 (SF.8, SF.11)
* \[ ] 锁使用 RAII (`scoped_lock`/`lock_guard`) (CP.20)
* \[ ] 异常是自定义类型，按值抛出，按引用捕获 (E.14, E.15)
* \[ ] 使用 `'\n'` 而非 `std::endl` (SL.io.50)
* \[ ] 没有魔数 (ES.45)

3
docs/zh-CN/skills/cpp-testing/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: cpp-testing
description: 仅在编写/更新/修复C++测试、配置GoogleTest/CTest、诊断失败或不稳定的测试，或添加覆盖率/消毒器时使用。
description: 仅用于编写/更新/修复C++测试、配置GoogleTest/CTest、诊断失败或不稳定的测试，或添加覆盖率/消毒器时使用。
origin: ECC
---
# C++ 测试（代理技能）

335
docs/zh-CN/skills/database-migrations/SKILL.md Normal file
View File

@@ -0,0 +1,335 @@
---
name: database-migrations
description: 数据库迁移最佳实践，涵盖模式变更、数据迁移、回滚以及零停机部署，适用于PostgreSQL、MySQL及常用ORM（Prisma、Drizzle、Django、TypeORM、golang-migrate）。
origin: ECC
---
# 数据库迁移模式
为生产系统提供安全、可逆的数据库模式变更。
## 何时激活
* 创建或修改数据库表
* 添加/删除列或索引
* 运行数据迁移（回填、转换）
* 计划零停机模式变更
* 为新项目设置迁移工具
## 核心原则
1. **每个变更都是一次迁移** — 切勿手动更改生产数据库
2. **迁移在生产环境中是只进不退的** — 回滚使用新的前向迁移
3. **模式迁移和数据迁移是分开的** — 切勿在一个迁移中混合 DDL 和 DML
4. **针对生产规模的数据测试迁移** — 适用于 100 行的迁移可能在 1000 万行时锁定
5. **迁移一旦部署就是不可变的** — 切勿编辑已在生产中运行的迁移
## 迁移安全检查清单
应用任何迁移之前：
* \[ ] 迁移同时包含 UP 和 DOWN（或明确标记为不可逆）
* \[ ] 对大表没有全表锁（使用并发操作）
* \[ ] 新列有默认值或可为空（切勿添加没有默认值的 NOT NULL）
* \[ ] 索引是并发创建的（对于现有表，不与 CREATE TABLE 内联创建）
* \[ ] 数据回填是与模式变更分开的迁移
* \[ ] 已针对生产数据副本进行测试
* \[ ] 回滚计划已记录
## PostgreSQL 模式
### 安全地添加列
```sql
-- GOOD: Nullable column, no lock
ALTER TABLE users ADD COLUMN avatar_url TEXT;
-- GOOD: Column with default (Postgres 11+ is instant, no rewrite)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;
-- BAD: NOT NULL without default on existing table (requires full rewrite)
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- This locks the table and rewrites every row
```
### 无停机添加索引
```sql
-- BAD: Blocks writes on large tables
CREATE INDEX idx_users_email ON users (email);
-- GOOD: Non-blocking, allows concurrent writes
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
-- Note: CONCURRENTLY cannot run inside a transaction block
-- Most migration tools need special handling for this
```
### 重命名列（零停机）
切勿在生产中直接重命名。使用扩展-收缩模式：
```sql
-- Step 1: Add new column (migration 001)
ALTER TABLE users ADD COLUMN display_name TEXT;
-- Step 2: Backfill data (migration 002, data migration)
UPDATE users SET display_name = username WHERE display_name IS NULL;
-- Step 3: Update application code to read/write both columns
-- Deploy application changes
-- Step 4: Stop writing to old column, drop it (migration 003)
ALTER TABLE users DROP COLUMN username;
```
### 安全地删除列
```sql
-- Step 1: Remove all application references to the column
-- Step 2: Deploy application without the column reference
-- Step 3: Drop column in next migration
ALTER TABLE orders DROP COLUMN legacy_status;
-- For Django: use SeparateDatabaseAndState to remove from model
-- without generating DROP COLUMN (then drop in next migration)
```
### 大型数据迁移
```sql
-- BAD: Updates all rows in one transaction (locks table)
UPDATE users SET normalized_email = LOWER(email);
-- GOOD: Batch update with progress
DO $$
DECLARE
batch_size INT := 10000;
rows_updated INT;
BEGIN
LOOP
UPDATE users
SET normalized_email = LOWER(email)
WHERE id IN (
SELECT id FROM users
WHERE normalized_email IS NULL
LIMIT batch_size
FOR UPDATE SKIP LOCKED
);
GET DIAGNOSTICS rows_updated = ROW_COUNT;
RAISE NOTICE 'Updated % rows', rows_updated;
EXIT WHEN rows_updated = 0;
COMMIT;
END LOOP;
END $$;
```
## Prisma (TypeScript/Node.js)
### 工作流
```bash
# Create migration from schema changes
npx prisma migrate dev --name add_user_avatar
# Apply pending migrations in production
npx prisma migrate deploy
# Reset database (dev only)
npx prisma migrate reset
# Generate client after schema changes
npx prisma generate
```
### 模式示例
```prisma
model User {
id String @id @default(cuid())
email String @unique
name String?
avatarUrl String? @map("avatar_url")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
orders Order[]
@@map("users")
@@index([email])
}
```
### 自定义 SQL 迁移
对于 Prisma 无法表达的操作（并发索引、数据回填）：
```bash
# Create empty migration, then edit the SQL manually
npx prisma migrate dev --create-only --name add_email_index
```
```sql
-- migrations/20240115_add_email_index/migration.sql
-- Prisma cannot generate CONCURRENTLY, so we write it manually
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);
```
## Drizzle (TypeScript/Node.js)
### 工作流
```bash
# Generate migration from schema changes
npx drizzle-kit generate
# Apply migrations
npx drizzle-kit migrate
# Push schema directly (dev only, no migration file)
npx drizzle-kit push
```
### 模式示例
```typescript
import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";
export const users = pgTable("users", {
id: uuid("id").primaryKey().defaultRandom(),
email: text("email").notNull().unique(),
name: text("name"),
isActive: boolean("is_active").notNull().default(true),
createdAt: timestamp("created_at").notNull().defaultNow(),
updatedAt: timestamp("updated_at").notNull().defaultNow(),
});
```
## Django (Python)
### 工作流
```bash
# Generate migration from model changes
python manage.py makemigrations
# Apply migrations
python manage.py migrate
# Show migration status
python manage.py showmigrations
# Generate empty migration for custom SQL
python manage.py makemigrations --empty app_name -n description
```
### 数据迁移
```python
from django.db import migrations
def backfill_display_names(apps, schema_editor):
User = apps.get_model("accounts", "User")
batch_size = 5000
users = User.objects.filter(display_name="")
while users.exists():
batch = list(users[:batch_size])
for user in batch:
user.display_name = user.username
User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)
def reverse_backfill(apps, schema_editor):
pass # Data migration, no reverse needed
class Migration(migrations.Migration):
dependencies = [("accounts", "0015_add_display_name")]
operations = [
migrations.RunPython(backfill_display_names, reverse_backfill),
]
```
### SeparateDatabaseAndState
从 Django 模型中删除列，而不立即从数据库中删除：
```python
class Migration(migrations.Migration):
operations = [
migrations.SeparateDatabaseAndState(
state_operations=[
migrations.RemoveField(model_name="user", name="legacy_field"),
],
database_operations=[], # Don't touch the DB yet
),
]
```
## golang-migrate (Go)
### 工作流
```bash
# Create migration pair
migrate create -ext sql -dir migrations -seq add_user_avatar
# Apply all pending migrations
migrate -path migrations -database "$DATABASE_URL" up
# Rollback last migration
migrate -path migrations -database "$DATABASE_URL" down 1
# Force version (fix dirty state)
migrate -path migrations -database "$DATABASE_URL" force VERSION
```
### 迁移文件
```sql
-- migrations/000003_add_user_avatar.up.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;
-- migrations/000003_add_user_avatar.down.sql
DROP INDEX IF EXISTS idx_users_avatar;
ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;
```
## 零停机迁移策略
对于关键的生产变更，遵循扩展-收缩模式：
```
Phase 1: EXPAND
- Add new column/table (nullable or with default)
- Deploy: app writes to BOTH old and new
- Backfill existing data
Phase 2: MIGRATE
- Deploy: app reads from NEW, writes to BOTH
- Verify data consistency
Phase 3: CONTRACT
- Deploy: app only uses NEW
- Drop old column/table in separate migration
```
### 时间线示例
```
Day 1: Migration adds new_status column (nullable)
Day 1: Deploy app v2 — writes to both status and new_status
Day 2: Run backfill migration for existing rows
Day 3: Deploy app v3 — reads from new_status only
Day 7: Migration drops old status column
```
## 反模式
| 反模式 | 为何会失败 | 更好的方法 |
|-------------|-------------|-----------------|
| 在生产中手动执行 SQL | 没有审计追踪，不可重复 | 始终使用迁移文件 |
| 编辑已部署的迁移 | 导致环境间出现差异 | 改为创建新迁移 |
| 没有默认值的 NOT NULL | 锁定表，重写所有行 | 添加可为空列，回填数据，然后添加约束 |
| 在大表上内联创建索引 | 在构建期间阻塞写入 | 使用 CREATE INDEX CONCURRENTLY |
| 在一个迁移中混合模式和数据的变更 | 难以回滚，事务时间长 | 分开的迁移 |
| 在移除代码之前删除列 | 应用程序在缺失列时出错 | 先移除代码，下一次部署再删除列 |

432
docs/zh-CN/skills/deployment-patterns/SKILL.md Normal file
View File

@@ -0,0 +1,432 @@
---
name: deployment-patterns
description: 部署工作流、CI/CD流水线模式、Docker容器化、健康检查、回滚策略以及Web应用程序的生产就绪检查清单。
origin: ECC
---
# 部署模式
生产环境部署工作流和 CI/CD 最佳实践。
## 何时启用
* 设置 CI/CD 流水线时
* 将应用容器化（Docker）时
* 规划部署策略（蓝绿、金丝雀、滚动）时
* 实现健康检查和就绪探针时
* 准备生产发布时
* 配置环境特定设置时
## 部署策略
### 滚动部署（默认）
逐步替换实例——在发布过程中，新旧版本同时运行。
```
Instance 1: v1 → v2 (update first)
Instance 2: v1 (still running v1)
Instance 3: v1 (still running v1)
Instance 1: v2
Instance 2: v1 → v2 (update second)
Instance 3: v1
Instance 1: v2
Instance 2: v2
Instance 3: v1 → v2 (update last)
```
**优点：** 零停机时间，渐进式发布
**缺点：** 两个版本同时运行——需要向后兼容的更改
**适用场景：** 标准部署，向后兼容的更改
### 蓝绿部署
运行两个相同的环境。原子化地切换流量。
```
Blue (v1) ← traffic
Green (v2) idle, running new version
# After verification:
Blue (v1) idle (becomes standby)
Green (v2) ← traffic
```
**优点：** 即时回滚（切换回蓝色环境），切换干净利落
**缺点：** 部署期间需要双倍的基础设施
**适用场景：** 关键服务，对问题零容忍
### 金丝雀部署
首先将一小部分流量路由到新版本。
```
v1: 95% of traffic
v2: 5% of traffic (canary)
# If metrics look good:
v1: 50% of traffic
v2: 50% of traffic
# Final:
v2: 100% of traffic
```
**优点：** 在全量发布前，通过真实流量发现问题
**缺点：** 需要流量分割基础设施和监控
**适用场景：** 高流量服务，风险性更改，功能标志
## Docker
### 多阶段 Dockerfile (Node.js)
```dockerfile
# Stage 1: Install dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false
# Stage 2: Build
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
RUN npm prune --production
# Stage 3: Production image
FROM node:22-alpine AS runner
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]
```
### 多阶段 Dockerfile (Go)
```dockerfile
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
FROM alpine:3.19 AS runner
RUN apk --no-cache add ca-certificates
RUN adduser -D -u 1001 appuser
USER appuser
COPY --from=builder /server /server
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
CMD ["/server"]
```
### 多阶段 Dockerfile (Python/Django)
```dockerfile
FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install --no-cache-dir uv
COPY requirements.txt .
RUN uv pip install --system --no-cache -r requirements.txt
FROM python:3.12-slim AS runner
WORKDIR /app
RUN useradd -r -u 1001 appuser
USER appuser
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
```
### Docker 最佳实践
```
# GOOD practices
- Use specific version tags (node:22-alpine, not node:latest)
- Multi-stage builds to minimize image size
- Run as non-root user
- Copy dependency files first (layer caching)
- Use .dockerignore to exclude node_modules, .git, tests
- Add HEALTHCHECK instruction
- Set resource limits in docker-compose or k8s
# BAD practices
- Running as root
- Using :latest tags
- Copying entire repo in one COPY layer
- Installing dev dependencies in production image
- Storing secrets in image (use env vars or secrets manager)
```
## CI/CD 流水线
### GitHub Actions (标准流水线)
```yaml
name: CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run lint
- run: npm run typecheck
- run: npm test -- --coverage
- uses: actions/upload-artifact@v4
if: always()
with:
name: coverage
path: coverage/
build:
needs: test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v5
with:
push: true
tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
deploy:
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
environment: production
steps:
- name: Deploy to production
run: |
# Platform-specific deployment command
# Railway: railway up
# Vercel: vercel --prod
# K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
echo "Deploying ${{ github.sha }}"
```
### 流水线阶段
```
PR opened:
lint → typecheck → unit tests → integration tests → preview deploy
Merged to main:
lint → typecheck → unit tests → integration tests → build image → deploy staging → smoke tests → deploy production
```
## 健康检查
### 健康检查端点
```typescript
// Simple health check
app.get("/health", (req, res) => {
res.status(200).json({ status: "ok" });
});
// Detailed health check (for internal monitoring)
app.get("/health/detailed", async (req, res) => {
const checks = {
database: await checkDatabase(),
redis: await checkRedis(),
externalApi: await checkExternalApi(),
};
const allHealthy = Object.values(checks).every(c => c.status === "ok");
res.status(allHealthy ? 200 : 503).json({
status: allHealthy ? "ok" : "degraded",
timestamp: new Date().toISOString(),
version: process.env.APP_VERSION || "unknown",
uptime: process.uptime(),
checks,
});
});
async function checkDatabase(): Promise<HealthCheck> {
try {
await db.query("SELECT 1");
return { status: "ok", latency_ms: 2 };
} catch (err) {
return { status: "error", message: "Database unreachable" };
}
}
```
### Kubernetes 探针
```yaml
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 10
periodSeconds: 30
failureThreshold: 3
readinessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
failureThreshold: 2
startupProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 0
periodSeconds: 5
failureThreshold: 30 # 30 * 5s = 150s max startup time
```
## 环境配置
### 十二要素应用模式
```bash
# All config via environment variables — never in code
DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://host:6379/0
API_KEY=${API_KEY} # injected by secrets manager
LOG_LEVEL=info
PORT=3000
# Environment-specific behavior
NODE_ENV=production # or staging, development
APP_ENV=production # explicit app environment
```
### 配置验证
```typescript
import { z } from "zod";
const envSchema = z.object({
NODE_ENV: z.enum(["development", "staging", "production"]),
PORT: z.coerce.number().default(3000),
DATABASE_URL: z.string().url(),
REDIS_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});
// Validate at startup — fail fast if config is wrong
export const env = envSchema.parse(process.env);
```
## 回滚策略
### 即时回滚
```bash
# Docker/Kubernetes: point to previous image
kubectl rollout undo deployment/app
# Vercel: promote previous deployment
vercel rollback
# Railway: redeploy previous commit
railway up --commit <previous-sha>
# Database: rollback migration (if reversible)
npx prisma migrate resolve --rolled-back <migration-name>
```
### 回滚检查清单
* \[ ] 之前的镜像/制品可用且已标记
* \[ ] 数据库迁移向后兼容（无破坏性更改）
* \[ ] 功能标志可以在不部署的情况下禁用新功能
* \[ ] 监控警报已配置，用于错误率飙升
* \[ ] 在生产发布前，回滚已在预演环境测试
## 生产就绪检查清单
在任何生产部署之前：
### 应用
* \[ ] 所有测试通过（单元、集成、端到端）
* \[ ] 代码或配置文件中没有硬编码的密钥
* \[ ] 错误处理覆盖所有边缘情况
* \[ ] 日志是结构化的（JSON）且不包含 PII
* \[ ] 健康检查端点返回有意义的状态
### 基础设施
* \[ ] Docker 镜像可重复构建（版本已固定）
* \[ ] 环境变量已记录并在启动时验证
* \[ ] 资源限制已设置（CPU、内存）
* \[ ] 水平伸缩已配置（最小/最大实例数）
* \[ ] 所有端点均已启用 SSL/TLS
### 监控
* \[ ] 应用指标已导出（请求率、延迟、错误）
* \[ ] 已配置错误率超过阈值的警报
* \[ ] 日志聚合已设置（结构化日志，可搜索）
* \[ ] 健康端点有正常运行时间监控
### 安全
* \[ ] 依赖项已扫描 CVE
* \[ ] CORS 仅配置允许的来源
* \[ ] 公共端点已启用速率限制
* \[ ] 身份验证和授权已验证
* \[ ] 安全头已设置（CSP、HSTS、X-Frame-Options）
### 运维
* \[ ] 回滚计划已记录并测试
* \[ ] 数据库迁移已针对生产规模的数据进行测试
* \[ ] 常见故障场景的应急预案
* \[ ] 待命轮换和升级路径已定义

3
docs/zh-CN/skills/django-patterns/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: django-patterns
description: Django架构模式、使用DRF的REST API设计、ORM最佳实践、缓存、信号、中间件以及生产级Django应用程序。
description: Django架构模式，使用DRF设计REST API，ORM最佳实践，缓存，信号，中间件，以及生产级Django应用程序。
origin: ECC
---
# Django 开发模式

3
docs/zh-CN/skills/django-security/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: django-security
description: Django安全最佳实践，身份验证，授权，CSRF保护，SQL注入预防，XSS预防和安全部署配置。
description: Django 安全最佳实践、认证、授权、CSRF 防护、SQL 注入预防、XSS 预防和安全部署配置。
origin: ECC
---
# Django 安全最佳实践

3
docs/zh-CN/skills/django-tdd/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: django-tdd
description: Django测试策略，包括pytest-django、TDD方法论、factory_boy、模拟、覆盖率以及测试Django REST Framework API。
description: Django 测试策略，包括 pytest-django、TDD 方法、factory_boy、模拟、覆盖率以及测试 Django REST Framework API。
origin: ECC
---
# 使用 TDD 进行 Django 测试

11
docs/zh-CN/skills/django-verification/SKILL.md
View File

@@ -1,12 +1,21 @@
---
name: django-verification
description: Verification loop for Django projects: migrations, linting, tests with coverage, security scans, and deployment readiness checks before release or PR.
description: "Django项目的验证循环：迁移、代码检查、带覆盖率的测试、安全扫描，以及在发布或PR前的部署就绪检查。"
origin: ECC
---
# Django 验证循环
在发起 PR 之前、进行重大更改之后以及部署之前运行，以确保 Django 应用程序的质量和安全性。
## 何时激活
* 在为一个 Django 项目开启拉取请求之前
* 在重大模型变更、迁移更新或依赖升级之后
* 用于暂存或生产环境的预部署验证
* 运行完整的环境 → 代码检查 → 测试 → 安全 → 部署就绪流水线时
* 验证迁移安全性和测试覆盖率时
## 阶段 1: 环境检查
```bash

365
docs/zh-CN/skills/docker-patterns/SKILL.md Normal file
View File

@@ -0,0 +1,365 @@
---
name: docker-patterns
description: 用于本地开发的Docker和Docker Compose模式，包括容器安全、网络、卷策略和多服务编排。
origin: ECC
---
# Docker 模式
适用于容器化开发的 Docker 和 Docker Compose 最佳实践。
## 何时启用
* 为本地开发设置 Docker Compose
* 设计多容器架构
* 排查容器网络或卷问题
* 审查 Dockerfile 的安全性和大小
* 从本地开发迁移到容器化工作流
## 用于本地开发的 Docker Compose
### 标准 Web 应用栈
```yaml
# docker-compose.yml
services:
app:
build:
context: .
target: dev # Use dev stage of multi-stage Dockerfile
ports:
- "3000:3000"
volumes:
- .:/app # Bind mount for hot reload
- /app/node_modules # Anonymous volume -- preserves container deps
environment:
- DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
- REDIS_URL=redis://redis:6379/0
- NODE_ENV=development
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
command: npm run dev
db:
image: postgres:16-alpine
ports:
- "5432:5432"
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: app_dev
volumes:
- pgdata:/var/lib/postgresql/data
- ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 5
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redisdata:/data
mailpit: # Local email testing
image: axllent/mailpit
ports:
- "8025:8025" # Web UI
- "1025:1025" # SMTP
volumes:
pgdata:
redisdata:
```
### 开发与生产 Dockerfile
```dockerfile
# Stage: dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
# Stage: dev (hot reload, debug tools)
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]
# Stage: build
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production
# Stage: production (minimal image)
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]
```
### 覆盖文件
```yaml
# docker-compose.override.yml (auto-loaded, dev-only settings)
services:
app:
environment:
- DEBUG=app:*
- LOG_LEVEL=debug
ports:
- "9229:9229" # Node.js debugger
# docker-compose.prod.yml (explicit for production)
services:
app:
build:
target: production
restart: always
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
```
```bash
# Development (auto-loads override)
docker compose up
# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```
## 网络
### 服务发现
同一 Compose 网络中的服务可通过服务名解析：
```
# From "app" container:
postgres://postgres:postgres@db:5432/app_dev # "db" resolves to the db container
redis://redis:6379/0 # "redis" resolves to the redis container
```
### 自定义网络
```yaml
services:
frontend:
networks:
- frontend-net
api:
networks:
- frontend-net
- backend-net
db:
networks:
- backend-net # Only reachable from api, not frontend
networks:
frontend-net:
backend-net:
```
### 仅暴露所需内容
```yaml
services:
db:
ports:
- "127.0.0.1:5432:5432" # Only accessible from host, not network
# Omit ports entirely in production -- accessible only within Docker network
```
## 卷策略
```yaml
volumes:
# Named volume: persists across container restarts, managed by Docker
pgdata:
# Bind mount: maps host directory into container (for development)
# - ./src:/app/src
# Anonymous volume: preserves container-generated content from bind mount override
# - /app/node_modules
```
### 常见模式
```yaml
services:
app:
volumes:
- .:/app # Source code (bind mount for hot reload)
- /app/node_modules # Protect container's node_modules from host
- /app/.next # Protect build cache
db:
volumes:
- pgdata:/var/lib/postgresql/data # Persistent data
- ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql # Init scripts
```
## 容器安全
### Dockerfile 加固
```dockerfile
# 1. Use specific tags (never :latest)
FROM node:22.12-alpine3.20
# 2. Run as non-root
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app
# 3. Drop capabilities (in compose)
# 4. Read-only root filesystem where possible
# 5. No secrets in image layers
```
### Compose 安全
```yaml
services:
app:
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
- /app/.cache
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE # Only if binding to ports < 1024
```
### 密钥管理
```yaml
# GOOD: Use environment variables (injected at runtime)
services:
app:
env_file:
- .env # Never commit .env to git
environment:
- API_KEY # Inherits from host environment
# GOOD: Docker secrets (Swarm mode)
secrets:
db_password:
file: ./secrets/db_password.txt
services:
db:
secrets:
- db_password
# BAD: Hardcoded in image
# ENV API_KEY=sk-proj-xxxxx # NEVER DO THIS
```
## .dockerignore
```
node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/
```
## 调试
### 常用命令
```bash
# View logs
docker compose logs -f app # Follow app logs
docker compose logs --tail=50 db # Last 50 lines from db
# Execute commands in running container
docker compose exec app sh # Shell into app
docker compose exec db psql -U postgres # Connect to postgres
# Inspect
docker compose ps # Running services
docker compose top # Processes in each container
docker stats # Resource usage
# Rebuild
docker compose up --build # Rebuild images
docker compose build --no-cache app # Force full rebuild
# Clean up
docker compose down # Stop and remove containers
docker compose down -v # Also remove volumes (DESTRUCTIVE)
docker system prune # Remove unused images/containers
```
### 调试网络问题
```bash
# Check DNS resolution inside container
docker compose exec app nslookup db
# Check connectivity
docker compose exec app wget -qO- http://api:3000/health
# Inspect network
docker network ls
docker network inspect <project>_default
```
## 反模式
```
# BAD: Using docker compose in production without orchestration
# Use Kubernetes, ECS, or Docker Swarm for production multi-container workloads
# BAD: Storing data in containers without volumes
# Containers are ephemeral -- all data lost on restart without volumes
# BAD: Running as root
# Always create and use a non-root user
# BAD: Using :latest tag
# Pin to specific versions for reproducible builds
# BAD: One giant container with all services
# Separate concerns: one process per container
# BAD: Putting secrets in docker-compose.yml
# Use .env files (gitignored) or Docker secrets
```

329
docs/zh-CN/skills/e2e-testing/SKILL.md Normal file
View File

@@ -0,0 +1,329 @@
---
name: e2e-testing
description: Playwright E2E 测试模式、页面对象模型、配置、CI/CD 集成、工件管理和不稳定测试策略。
origin: ECC
---
# E2E 测试模式
用于构建稳定、快速且可维护的 E2E 测试套件的全面 Playwright 模式。
## 测试文件组织
```
tests/
├── e2e/
│ ├── auth/
│ │ ├── login.spec.ts
│ │ ├── logout.spec.ts
│ │ └── register.spec.ts
│ ├── features/
│ │ ├── browse.spec.ts
│ │ ├── search.spec.ts
│ │ └── create.spec.ts
│ └── api/
│ └── endpoints.spec.ts
├── fixtures/
│ ├── auth.ts
│ └── data.ts
└── playwright.config.ts
```
## 页面对象模型 (POM)
```typescript
import { Page, Locator } from '@playwright/test'
export class ItemsPage {
readonly page: Page
readonly searchInput: Locator
readonly itemCards: Locator
readonly createButton: Locator
constructor(page: Page) {
this.page = page
this.searchInput = page.locator('[data-testid="search-input"]')
this.itemCards = page.locator('[data-testid="item-card"]')
this.createButton = page.locator('[data-testid="create-btn"]')
}
async goto() {
await this.page.goto('/items')
await this.page.waitForLoadState('networkidle')
}
async search(query: string) {
await this.searchInput.fill(query)
await this.page.waitForResponse(resp => resp.url().includes('/api/search'))
await this.page.waitForLoadState('networkidle')
}
async getItemCount() {
return await this.itemCards.count()
}
}
```
## 测试结构
```typescript
import { test, expect } from '@playwright/test'
import { ItemsPage } from '../../pages/ItemsPage'
test.describe('Item Search', () => {
let itemsPage: ItemsPage
test.beforeEach(async ({ page }) => {
itemsPage = new ItemsPage(page)
await itemsPage.goto()
})
test('should search by keyword', async ({ page }) => {
await itemsPage.search('test')
const count = await itemsPage.getItemCount()
expect(count).toBeGreaterThan(0)
await expect(itemsPage.itemCards.first()).toContainText(/test/i)
await page.screenshot({ path: 'artifacts/search-results.png' })
})
test('should handle no results', async ({ page }) => {
await itemsPage.search('xyznonexistent123')
await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
expect(await itemsPage.getItemCount()).toBe(0)
})
})
```
## Playwright 配置
```typescript
import { defineConfig, devices } from '@playwright/test'
export default defineConfig({
testDir: './tests/e2e',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: [
['html', { outputFolder: 'playwright-report' }],
['junit', { outputFile: 'playwright-results.xml' }],
['json', { outputFile: 'playwright-results.json' }]
],
use: {
baseURL: process.env.BASE_URL || 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
actionTimeout: 10000,
navigationTimeout: 30000,
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
{ name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
],
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
timeout: 120000,
},
})
```
## 不稳定测试模式
### 隔离
```typescript
test('flaky: complex search', async ({ page }) => {
test.fixme(true, 'Flaky - Issue #123')
// test code...
})
test('conditional skip', async ({ page }) => {
test.skip(process.env.CI, 'Flaky in CI - Issue #123')
// test code...
})
```
### 识别不稳定性
```bash
npx playwright test tests/search.spec.ts --repeat-each=10
npx playwright test tests/search.spec.ts --retries=3
```
### 常见原因与修复
**竞态条件：**
```typescript
// Bad: assumes element is ready
await page.click('[data-testid="button"]')
// Good: auto-wait locator
await page.locator('[data-testid="button"]').click()
```
**网络时序：**
```typescript
// Bad: arbitrary timeout
await page.waitForTimeout(5000)
// Good: wait for specific condition
await page.waitForResponse(resp => resp.url().includes('/api/data'))
```
**动画时序：**
```typescript
// Bad: click during animation
await page.click('[data-testid="menu-item"]')
// Good: wait for stability
await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
await page.waitForLoadState('networkidle')
await page.locator('[data-testid="menu-item"]').click()
```
## 产物管理
### 截图
```typescript
await page.screenshot({ path: 'artifacts/after-login.png' })
await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })
```
### 跟踪记录
```typescript
await browser.startTracing(page, {
path: 'artifacts/trace.json',
screenshots: true,
snapshots: true,
})
// ... test actions ...
await browser.stopTracing()
```
### 视频
```typescript
// In playwright.config.ts
use: {
video: 'retain-on-failure',
videosPath: 'artifacts/videos/'
}
```
## CI/CD 集成
```yaml
# .github/workflows/e2e.yml
name: E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
env:
BASE_URL: ${{ vars.STAGING_URL }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
```
## 测试报告模板
```markdown
# E2E 测试报告
**日期：** YYYY-MM-DD HH:MM
**持续时间：** Xm Ys
**状态：** 通过 / 失败
## 概要
- 总计：X | 通过：Y (Z%) | 失败：A | 不稳定：B | 跳过：C
## 失败的测试
### test-name
**文件：** `tests/e2e/feature.spec.ts:45`
**错误：** 期望元素可见
**截图：** artifacts/failed.png
**建议修复：** [description]
## 产物
- HTML 报告：playwright-report/index.html
- 截图：artifacts/*.png
- 视频：artifacts/videos/*.webm
- 追踪文件：artifacts/*.zip
```
## 钱包 / Web3 测试
```typescript
test('wallet connection', async ({ page, context }) => {
// Mock wallet provider
await context.addInitScript(() => {
window.ethereum = {
isMetaMask: true,
request: async ({ method }) => {
if (method === 'eth_requestAccounts')
return ['0x1234567890123456789012345678901234567890']
if (method === 'eth_chainId') return '0x1'
}
}
})
await page.goto('/')
await page.locator('[data-testid="connect-wallet"]').click()
await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
})
```
## 金融 / 关键流程测试
```typescript
test('trade execution', async ({ page }) => {
// Skip on production — real money
test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
await page.goto('/markets/test-market')
await page.locator('[data-testid="position-yes"]').click()
await page.locator('[data-testid="trade-amount"]').fill('1.0')
// Verify preview
const preview = page.locator('[data-testid="trade-preview"]')
await expect(preview).toContainText('1.0')
// Confirm and wait for blockchain
await page.locator('[data-testid="confirm-trade"]').click()
await page.waitForResponse(
resp => resp.url().includes('/api/trade') && resp.status() === 200,
{ timeout: 30000 }
)
await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
})
```

9
docs/zh-CN/skills/eval-harness/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: eval-harness
description: 克劳德代码会话的正式评估框架，实施评估驱动开发（EDD）原则
origin: ECC
tools: Read, Write, Edit, Bash, Grep, Glob
---
@@ -8,6 +9,14 @@ tools: Read, Write, Edit, Bash, Grep, Glob
一个用于 Claude Code 会话的正式评估框架，实现了评估驱动开发 (EDD) 原则。
## 何时激活
* 为 AI 辅助工作流程设置评估驱动开发 (EDD)
* 定义 Claude Code 任务完成的标准（通过/失败）
* 使用 pass@k 指标衡量代理可靠性
* 为提示或代理变更创建回归测试套件
* 跨模型版本对代理性能进行基准测试
## 理念
评估驱动开发将评估视为 "AI 开发的单元测试"：

244
docs/zh-CN/skills/foundation-models-on-device/SKILL.md Normal file
View File

@@ -0,0 +1,244 @@
---
name: foundation-models-on-device
description: 苹果FoundationModels框架用于设备上的LLM——文本生成、使用@Generable进行引导生成、工具调用，以及在iOS 26+中的快照流。
---
# FoundationModels：设备端 LLM（iOS 26）
使用 FoundationModels 框架将苹果的设备端语言模型集成到应用中的模式。涵盖文本生成、使用 `@Generable` 的结构化输出、自定义工具调用以及快照流式传输——全部在设备端运行，以保护隐私并支持离线使用。
## 何时启用
* 使用 Apple Intelligence 在设备端构建 AI 功能
* 无需依赖云端即可生成或总结文本
* 从自然语言输入中提取结构化数据
* 为特定领域的 AI 操作实现自定义工具调用
* 流式传输结构化响应以实现实时 UI 更新
* 需要保护隐私的 AI（数据不离开设备）
## 核心模式 — 可用性检查
在创建会话之前，始终检查模型可用性：
```swift
struct GenerativeView: View {
private var model = SystemLanguageModel.default
var body: some View {
switch model.availability {
case .available:
ContentView()
case .unavailable(.deviceNotEligible):
Text("Device not eligible for Apple Intelligence")
case .unavailable(.appleIntelligenceNotEnabled):
Text("Please enable Apple Intelligence in Settings")
case .unavailable(.modelNotReady):
Text("Model is downloading or not ready")
case .unavailable(let other):
Text("Model unavailable: \(other)")
}
}
}
```
## 核心模式 — 基础会话
```swift
// Single-turn: create a new session each time
let session = LanguageModelSession()
let response = try await session.respond(to: "What's a good month to visit Paris?")
print(response.content)
// Multi-turn: reuse session for conversation context
let session = LanguageModelSession(instructions: """
You are a cooking assistant.
Provide recipe suggestions based on ingredients.
Keep suggestions brief and practical.
""")
let first = try await session.respond(to: "I have chicken and rice")
let followUp = try await session.respond(to: "What about a vegetarian option?")
```
指令的关键点：
* 定义模型的角色（"你是一位导师"）
* 指定要做什么（"帮助提取日历事件"）
* 设置风格偏好（"尽可能简短地回答"）
* 添加安全措施（"对于危险请求，回复'我无法提供帮助'"）
## 核心模式 — 使用 @Generable 进行引导式生成
生成结构化的 Swift 类型，而不是原始字符串：
### 1. 定义可生成类型
```swift
@Generable(description: "Basic profile information about a cat")
struct CatProfile {
var name: String
@Guide(description: "The age of the cat", .range(0...20))
var age: Int
@Guide(description: "A one sentence profile about the cat's personality")
var profile: String
}
```
### 2. 请求结构化输出
```swift
let response = try await session.respond(
to: "Generate a cute rescue cat",
generating: CatProfile.self
)
// Access structured fields directly
print("Name: \(response.content.name)")
print("Age: \(response.content.age)")
print("Profile: \(response.content.profile)")
```
### 支持的 @Guide 约束
* `.range(0...20)` — 数值范围
* `.count(3)` — 数组元素数量
* `description:` — 生成的语义引导
## 核心模式 — 工具调用
让模型调用自定义代码以执行特定领域的任务：
### 1. 定义工具
```swift
struct RecipeSearchTool: Tool {
let name = "recipe_search"
let description = "Search for recipes matching a given term and return a list of results."
@Generable
struct Arguments {
var searchTerm: String
var numberOfResults: Int
}
func call(arguments: Arguments) async throws -> ToolOutput {
let recipes = await searchRecipes(
term: arguments.searchTerm,
limit: arguments.numberOfResults
)
return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
}
}
```
### 2. 创建带工具的会话
```swift
let session = LanguageModelSession(tools: [RecipeSearchTool()])
let response = try await session.respond(to: "Find me some pasta recipes")
```
### 3. 处理工具错误
```swift
do {
let answer = try await session.respond(to: "Find a recipe for tomato soup.")
} catch let error as LanguageModelSession.ToolCallError {
print(error.tool.name)
if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
// Handle specific tool error
}
}
```
## 核心模式 — 快照流式传输
使用 `PartiallyGenerated` 类型为实时 UI 流式传输结构化响应：
```swift
@Generable
struct TripIdeas {
@Guide(description: "Ideas for upcoming trips")
var ideas: [String]
}
let stream = session.streamResponse(
to: "What are some exciting trip ideas?",
generating: TripIdeas.self
)
for try await partial in stream {
// partial: TripIdeas.PartiallyGenerated (all properties Optional)
print(partial)
}
```
### SwiftUI 集成
```swift
@State private var partialResult: TripIdeas.PartiallyGenerated?
@State private var errorMessage: String?
var body: some View {
List {
ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
Text(idea)
}
}
.overlay {
if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
}
.task {
do {
let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
for try await partial in stream {
partialResult = partial
}
} catch {
errorMessage = error.localizedDescription
}
}
}
```
## 关键设计决策
| 决策 | 理由 |
|----------|-----------|
| 设备端执行 | 隐私性——数据不离开设备；支持离线工作 |
| 4,096 个令牌限制 | 设备端模型约束；跨会话分块处理大数据 |
| 快照流式传输（非增量） | 对结构化输出友好；每个快照都是一个完整的部分状态 |
| `@Generable` 宏 | 为结构化生成提供编译时安全性；自动生成 `PartiallyGenerated` 类型 |
| 每个会话单次请求 | `isResponding` 防止并发请求；如有需要，创建多个会话 |
| `response.content`（而非 `.output`） | 正确的 API——始终通过 `.content` 属性访问结果 |
## 最佳实践
* 在创建会话之前**始终检查 `model.availability`**——处理所有不可用的情况
* **使用 `instructions`** 来引导模型行为——它们的优先级高于提示词
* 在发送新请求之前**检查 `isResponding`**——会话一次处理一个请求
* 通过 `response.content` **访问结果**——而不是 `.output`
* **将大型输入分块处理**——4,096 个令牌的限制适用于指令、提示词和输出的总和
* 对于结构化输出**使用 `@Generable`**——比解析原始字符串提供更强的保证
* **使用 `GenerationOptions(temperature:)`** 来调整创造力（值越高越有创意）
* **使用 Instruments 进行监控**——使用 Xcode Instruments 来分析请求性能
## 应避免的反模式
* 未先检查 `model.availability` 就创建会话
* 发送超过 4,096 个令牌上下文窗口的输入
* 尝试在单个会话上进行并发请求
* 使用 `.output` 而不是 `.content` 来访问响应数据
* 当 `@Generable` 结构化输出可行时，却去解析原始字符串响应
* 在单个提示词中构建复杂的多步逻辑——将其拆分为多个聚焦的提示词
* 假设模型始终可用——设备的资格和设置各不相同
## 何时使用
* 为注重隐私的应用进行设备端文本生成
* 从用户输入（表单、自然语言命令）中提取结构化数据
* 必须离线工作的 AI 辅助功能
* 逐步显示生成内容的流式 UI
* 通过工具调用（搜索、计算、查找）执行特定领域的 AI 操作

11
docs/zh-CN/skills/frontend-patterns/SKILL.md
View File

@@ -1,12 +1,23 @@
---
name: frontend-patterns
description: React、Next.js、状态管理、性能优化和UI最佳实践的前端开发模式。
origin: ECC
---
# 前端开发模式
适用于 React、Next.js 和高性能用户界面的现代前端模式。
## 何时激活
* 构建 React 组件（组合、属性、渲染）
* 管理状态（useState、useReducer、Zustand、Context）
* 实现数据获取（SWR、React Query、服务器组件）
* 优化性能（记忆化、虚拟化、代码分割）
* 处理表单（验证、受控输入、Zod 模式）
* 处理客户端路由和导航
* 构建可访问、响应式的 UI 模式
## 组件模式
### 组合优于继承

195
docs/zh-CN/skills/frontend-slides/SKILL.md Normal file
View File

@@ -0,0 +1,195 @@
---
name: frontend-slides
description: 从零开始或通过转换PowerPoint文件创建令人惊艳、动画丰富的HTML演示文稿。当用户想要构建演示文稿、将PPT/PPTX转换为网页格式，或为演讲/推介创建幻灯片时使用。帮助非设计师通过视觉探索而非抽象选择发现他们的美学。
origin: ECC
---
# 前端幻灯片
创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行。
灵感来源于 [zarazhangrui](https://github.com/zarazhangrui) 的作品中展示的视觉探索方法。
## 何时启用
* 创建演讲文稿、推介文稿、研讨会文稿或内部演示文稿时
* 将 `.ppt` 或 `.pptx` 幻灯片转换为 HTML 演示文稿时
* 改进现有 HTML 演示文稿的布局、动效或排版时
* 与尚不清楚其设计偏好的用户一起探索演示文稿风格时
## 不可妥协的原则
1. **零依赖**：默认使用一个包含内联 CSS 和 JS 的自包含 HTML 文件。
2. **必须适配视口**：每张幻灯片必须适配一个视口，内部不允许滚动。
3. **展示，而非描述**：使用视觉预览，而非抽象的风格问卷。
4. **独特设计**：避免通用的紫色渐变、白色背景加 Inter 字体、模板化的文稿外观。
5. **生产质量**：保持代码注释清晰、可访问、响应式且性能良好。
在生成之前，请阅读 `STYLE_PRESETS.md` 以了解视口安全的 CSS 基础、密度限制、预设目录和 CSS 陷阱。
## 工作流程
### 1. 检测模式
选择一条路径：
* **新演示文稿**：用户有主题、笔记或完整草稿
* **PPT 转换**：用户有 `.ppt` 或 `.pptx`
* **增强**：用户已有 HTML 幻灯片并希望改进
### 2. 发现内容
只询问最低限度的必要信息：
* 目的：推介、教学、会议演讲、内部更新
* 长度：短 (5-10张)、中 (10-20张)、长 (20+张)
* 内容状态：已完成文案、粗略笔记、仅主题
如果用户有内容，请他们在进行样式设计前粘贴内容。
### 3. 发现风格
默认采用视觉探索方式。
如果用户已经知道所需的预设，则跳过预览并直接使用。
否则：
1. 询问文稿应营造何种感觉：印象深刻、充满活力、专注、激发灵感。
2. 在 `.ecc-design/slide-previews/` 中生成 **3 个单幻灯片预览文件**。
3. 每个预览必须是自包含的，清晰地展示排版/色彩/动效，并且幻灯片内容大约保持在 100 行以内。
4. 询问用户保留哪个预览或混合哪些元素。
在将情绪映射到风格时，请使用 `STYLE_PRESETS.md` 中的预设指南。
### 4. 构建演示文稿
输出以下之一：
* `presentation.html`
* `[presentation-name].html`
仅当文稿包含提取的或用户提供的图像时，才使用 `assets/` 文件夹。
必需的结构：
* 语义化的幻灯片部分
* 来自 `STYLE_PRESETS.md` 的视口安全的 CSS 基础
* 用于主题值的 CSS 自定义属性
* 用于键盘、滚轮和触摸导航的演示文稿控制器类
* 用于揭示动画的 Intersection Observer
* 支持减少动效
### 5. 强制执行视口适配
将此视为硬性规定。
规则：
* 每个 `.slide` 必须使用 `height: 100vh; height: 100dvh; overflow: hidden;`
* 所有字体和间距必须随 `clamp()` 缩放
* 当内容无法适配时，将其拆分为多张幻灯片
* 切勿通过将文本缩小到可读尺寸以下来解决溢出问题
* 绝不允许幻灯片内部出现滚动条
使用 `STYLE_PRESETS.md` 中的密度限制和强制性 CSS 代码块。
### 6. 验证
在这些尺寸下检查完成的文稿：
* 1920x1080
* 1280x720
* 768x1024
* 375x667
* 667x375
如果可以使用浏览器自动化，请使用它来验证没有幻灯片溢出且键盘导航正常工作。
### 7. 交付
在交付时：
* 除非用户希望保留，否则删除临时预览文件
* 在有用时使用适合当前平台的开源工具打开文稿
* 总结文件路径、使用的预设、幻灯片数量以及简单的主题自定义点
为当前操作系统使用正确的开源工具：
* macOS: `open file.html`
* Linux: `xdg-open file.html`
* Windows: `start "" file.html`
## PPT / PPTX 转换
对于 PowerPoint 转换：
1. 优先使用 `python3` 和 `python-pptx` 来提取文本、图像和备注。
2. 如果 `python-pptx` 不可用，询问是安装它还是回退到基于手动/导出的工作流程。
3. 保留幻灯片顺序、演讲者备注和提取的资源。
4. 提取后，运行与新演示文稿相同的风格选择工作流程。
保持转换跨平台。当 Python 可以完成任务时，不要依赖仅限 macOS 的工具。
## 实现要求
### HTML / CSS
* 除非用户明确希望使用多文件项目，否则使用内联 CSS 和 JS。
* 字体可以来自 Google Fonts 或 Fontshare。
* 优先使用氛围背景、强烈的字体层次结构和清晰的视觉方向。
* 使用抽象形状、渐变、网格、噪点和几何图形，而非插图。
### JavaScript
包含：
* 键盘导航
* 触摸/滑动导航
* 鼠标滚轮导航
* 进度指示器或幻灯片索引
* 进入时触发的揭示动画
### 可访问性
* 使用语义化结构 (`main`, `section`, `nav`)
* 保持对比度可读
* 支持仅键盘导航
* 尊重 `prefers-reduced-motion`
## 内容密度限制
除非用户明确要求更密集的幻灯片且可读性仍然保持，否则使用以下最大值：
| 幻灯片类型 | 限制 |
|------------|-------|
| 标题 | 1 个标题 + 1 个副标题 + 可选标语 |
| 内容 | 1 个标题 + 4-6 个要点或 2 个短段落 |
| 功能网格 | 最多 6 张卡片 |
| 代码 | 最多 8-10 行 |
| 引用 | 1 条引用 + 出处 |
| 图像 | 1 张受视口约束的图像 |
## 反模式
* 没有视觉标识的通用初创公司渐变
* 除非是特意采用编辑风格，否则避免系统字体文稿
* 冗长的要点列表
* 需要滚动的代码块
* 在短屏幕上会损坏的固定高度内容框
* 无效的否定 CSS 函数，如 `-clamp(...)`
## 相关 ECC 技能
* `frontend-patterns` 用于围绕文稿的组件和交互模式
* `liquid-glass-design` 当演示文稿有意借鉴苹果玻璃美学时
* `e2e-testing` 如果您需要为最终文稿进行自动化浏览器验证
## 交付清单
* 演示文稿可在浏览器中从本地文件运行
* 每张幻灯片适配视口，无需滚动
* 风格独特且有意图
* 动画有意义，不喧闹
* 尊重减少动效设置
* 在交付时解释文件路径和自定义点

333
docs/zh-CN/skills/frontend-slides/STYLE_PRESETS.md Normal file
View File

@@ -0,0 +1,333 @@
# 样式预设参考
为 `frontend-slides` 整理的视觉样式。
使用此文件用于：
* 强制性的视口适配 CSS 基础
* 预设选择和情绪映射
* CSS 陷阱和验证规则
仅使用抽象形状。除非用户明确要求，否则避免使用插图。
## 视口适配不容妥协
每张幻灯片必须完全适配一个视口。
### 黄金法则
```text
Each slide = exactly one viewport height.
Too much content = split into more slides.
Never scroll inside a slide.
```
### 内容密度限制
| 幻灯片类型 | 最大内容量 |
|---|---|
| 标题幻灯片 | 1 个标题 + 1 个副标题 + 可选标语 |
| 内容幻灯片 | 1 个标题 + 4-6 个要点或 2 个段落 |
| 功能网格 | 最多 6 张卡片 |
| 代码幻灯片 | 最多 8-10 行 |
| 引用幻灯片 | 1 条引用 + 出处 |
| 图片幻灯片 | 1 张图片，理想情况下低于 60vh |
## 强制基础 CSS
将此代码块复制到每个生成的演示文稿中，然后在其基础上应用主题。
```css
/* ===========================================
VIEWPORT FITTING: MANDATORY BASE STYLES
=========================================== */
html, body {
height: 100%;
overflow-x: hidden;
}
html {
scroll-snap-type: y mandatory;
scroll-behavior: smooth;
}
.slide {
width: 100vw;
height: 100vh;
height: 100dvh;
overflow: hidden;
scroll-snap-align: start;
display: flex;
flex-direction: column;
position: relative;
}
.slide-content {
flex: 1;
display: flex;
flex-direction: column;
justify-content: center;
max-height: 100%;
overflow: hidden;
padding: var(--slide-padding);
}
:root {
--title-size: clamp(1.5rem, 5vw, 4rem);
--h2-size: clamp(1.25rem, 3.5vw, 2.5rem);
--h3-size: clamp(1rem, 2.5vw, 1.75rem);
--body-size: clamp(0.75rem, 1.5vw, 1.125rem);
--small-size: clamp(0.65rem, 1vw, 0.875rem);
--slide-padding: clamp(1rem, 4vw, 4rem);
--content-gap: clamp(0.5rem, 2vw, 2rem);
--element-gap: clamp(0.25rem, 1vw, 1rem);
}
.card, .container, .content-box {
max-width: min(90vw, 1000px);
max-height: min(80vh, 700px);
}
.feature-list, .bullet-list {
gap: clamp(0.4rem, 1vh, 1rem);
}
.feature-list li, .bullet-list li {
font-size: var(--body-size);
line-height: 1.4;
}
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(min(100%, 250px), 1fr));
gap: clamp(0.5rem, 1.5vw, 1rem);
}
img, .image-container {
max-width: 100%;
max-height: min(50vh, 400px);
object-fit: contain;
}
@media (max-height: 700px) {
:root {
--slide-padding: clamp(0.75rem, 3vw, 2rem);
--content-gap: clamp(0.4rem, 1.5vw, 1rem);
--title-size: clamp(1.25rem, 4.5vw, 2.5rem);
--h2-size: clamp(1rem, 3vw, 1.75rem);
}
}
@media (max-height: 600px) {
:root {
--slide-padding: clamp(0.5rem, 2.5vw, 1.5rem);
--content-gap: clamp(0.3rem, 1vw, 0.75rem);
--title-size: clamp(1.1rem, 4vw, 2rem);
--body-size: clamp(0.7rem, 1.2vw, 0.95rem);
}
.nav-dots, .keyboard-hint, .decorative {
display: none;
}
}
@media (max-height: 500px) {
:root {
--slide-padding: clamp(0.4rem, 2vw, 1rem);
--title-size: clamp(1rem, 3.5vw, 1.5rem);
--h2-size: clamp(0.9rem, 2.5vw, 1.25rem);
--body-size: clamp(0.65rem, 1vw, 0.85rem);
}
}
@media (max-width: 600px) {
:root {
--title-size: clamp(1.25rem, 7vw, 2.5rem);
}
.grid {
grid-template-columns: 1fr;
}
}
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.2s !important;
}
html {
scroll-behavior: auto;
}
}
```
## 视口检查清单
* 每个 `.slide` 都有 `height: 100vh`、`height: 100dvh` 和 `overflow: hidden`
* 所有排版都使用 `clamp()`
* 所有间距都使用 `clamp()` 或视口单位
* 图片有 `max-height` 约束
* 网格使用 `auto-fit` + `minmax()` 进行适配
* 短高度断点存在于 `700px`、`600px` 和 `500px`
* 如果感觉任何内容拥挤，请拆分幻灯片
## 情绪到预设的映射
| 情绪 | 推荐的预设 |
|---|---|
| 印象深刻 / 自信 | Bold Signal, Electric Studio, Dark Botanical |
| 兴奋 / 充满活力 | Creative Voltage, Neon Cyber, Split Pastel |
| 平静 / 专注 | Notebook Tabs, Paper & Ink, Swiss Modern |
| 受启发 / 感动 | Dark Botanical, Vintage Editorial, Pastel Geometry |
## 预设目录
### 1. Bold Signal
* 氛围：自信，高冲击力，适合主题演讲
* 最适合：推介演示，产品发布，声明
* 字体：Archivo Black + Space Grotesk
* 调色板：炭灰色基底，亮橙色焦点卡片，纯白色文本
* 特色：超大章节编号，深色背景上的高对比度卡片
### 2. Electric Studio
* 氛围：简洁，大胆，机构级精致
* 最适合：客户演示，战略评审
* 字体：仅 Manrope
* 调色板：黑色，白色，饱和钴蓝色点缀
* 特色：双面板分割和锐利的编辑式对齐
### 3. Creative Voltage
* 氛围：充满活力，复古现代，俏皮自信
* 最适合：创意工作室，品牌工作，产品故事叙述
* 字体：Syne + Space Mono
* 调色板：电光蓝，霓虹黄，深海军蓝
* 特色：半色调纹理，徽章，强烈的对比
### 4. Dark Botanical
* 氛围：优雅，高端，有氛围感
* 最适合：奢侈品牌，深思熟虑的叙述，高端产品演示
* 字体：Cormorant + IBM Plex Sans
* 调色板：接近黑色，温暖的象牙色，腮红，金色，赤陶色
* 特色：模糊的抽象圆形，精细的线条，克制的动效
### 5. Notebook Tabs
* 氛围：编辑感，有条理，有触感
* 最适合：报告，评审，结构化的故事叙述
* 字体：Bodoni Moda + DM Sans
* 调色板：炭灰色上的奶油色纸张搭配柔和色彩标签
* 特色：纸张效果，彩色侧边标签，活页夹细节
### 6. Pastel Geometry
* 氛围：平易近人，现代，友好
* 最适合：产品概览，入门介绍，较轻松的品牌演示
* 字体：仅 Plus Jakarta Sans
* 调色板：淡蓝色背景，奶油色卡片，柔和的粉色/薄荷色/薰衣草色点缀
* 特色：垂直药丸形状，圆角卡片，柔和阴影
### 7. Split Pastel
* 氛围：有趣，现代，有创意
* 最适合：机构介绍，研讨会，作品集
* 字体：仅 Outfit
* 调色板：桃色 + 薰衣草色分割背景搭配薄荷色徽章
* 特色：分割背景，圆角标签，轻网格叠加层
### 8. Vintage Editorial
* 氛围：诙谐，个性鲜明，受杂志启发
* 最适合：个人品牌，观点性演讲，故事叙述
* 字体：Fraunces + Work Sans
* 调色板：奶油色，炭灰色，灰暗的暖色点缀
* 特色：几何点缀，带边框的标注，醒目的衬线标题
### 9. Neon Cyber
* 氛围：未来感，科技感，动感
* 最适合：AI，基础设施，开发工具，关于未来趋势的演讲
* 字体：Clash Display + Satoshi
* 调色板：午夜海军蓝，青色，洋红色
* 特色：发光效果，粒子，网格，数据雷达能量感
### 10. Terminal Green
* 氛围：面向开发者，黑客风格简洁
* 最适合：API，CLI 工具，工程演示
* 字体：仅 JetBrains Mono
* 调色板：GitHub 深色 + 终端绿色
* 特色：扫描线，命令行框架，精确的等宽字体节奏
### 11. Swiss Modern
* 氛围：极简，精确，数据导向
* 最适合：企业，产品战略，分析
* 字体：Archivo + Nunito
* 调色板：白色，黑色，信号红色
* 特色：可见的网格，不对称，几何秩序感
### 12. Paper & Ink
* 氛围：文学性，深思熟虑，故事驱动
* 最适合：散文，主题演讲叙述，宣言式演示
* 字体：Cormorant Garamond + Source Serif 4
* 调色板：温暖的奶油色，炭灰色，深红色点缀
* 特色：引文突出，首字下沉，优雅的线条
## 直接选择提示
如果用户已经知道他们想要的样式，让他们直接从上面的预设名称中选择，而不是强制生成预览。
## 动画感觉映射
| 感觉 | 动效方向 |
|---|---|
| 戏剧性 / 电影感 | 缓慢淡入淡出，视差滚动，大比例缩放进入 |
| 科技感 / 未来感 | 发光，粒子，网格运动，文字乱序出现 |
| 有趣 / 友好 | 弹性缓动，圆角形状，漂浮运动 |
| 专业 / 企业 | 微妙的 200-300 毫秒过渡，干净的幻灯片切换 |
| 平静 / 极简 | 非常克制的运动，留白优先 |
| 编辑感 / 杂志感 | 强烈的层次感，错落的文字和图片互动 |
## CSS 陷阱：否定函数
切勿编写这些：
```css
right: -clamp(28px, 3.5vw, 44px);
margin-left: -min(10vw, 100px);
```
浏览器会静默忽略它们。
始终改为编写这个：
```css
right: calc(-1 * clamp(28px, 3.5vw, 44px));
margin-left: calc(-1 * min(10vw, 100px));
```
## 验证尺寸
至少测试以下尺寸：
* 桌面：`1920x1080`，`1440x900`，`1280x720`
* 平板：`1024x768`，`768x1024`
* 手机：`375x667`，`414x896`
* 横屏手机：`667x375`，`896x414`
## 反模式
请勿使用：
* 紫底白字的初创公司模板
* Inter / Roboto / Arial 作为视觉声音，除非用户明确想要实用主义的中性风格
* 要点堆砌、过小字体或需要滚动的代码块
* 装饰性插图，当抽象几何形状能更好地完成工作时

3
docs/zh-CN/skills/golang-patterns/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: golang-patterns
description: 构建稳健、高效且可维护的Go应用程序的惯用Go模式、最佳实践和约定。
description: 用于构建健壮、高效且可维护的Go应用程序的惯用Go模式、最佳实践和约定。
origin: ECC
---
# Go 开发模式

1
docs/zh-CN/skills/golang-testing/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: golang-testing
description: Go测试模式包括表格驱动测试、子测试、基准测试、模糊测试和测试覆盖率。遵循TDD方法论，采用地道的Go实践。
origin: ECC
---
# Go 测试模式

104
docs/zh-CN/skills/investor-materials/SKILL.md Normal file
View File

@@ -0,0 +1,104 @@
---
name: investor-materials
description: 创建和更新宣传文稿、一页简介、投资者备忘录、加速器申请、财务模型和融资材料。当用户需要面向投资者的文件、预测、资金用途表、里程碑计划或必须在多个融资资产中保持内部一致性的材料时使用。
origin: ECC
---
# 投资者材料
构建面向投资者的材料，要求一致、可信且易于辩护。
## 何时启用
* 创建或修订融资演讲稿
* 撰写投资者备忘录或一页摘要
* 构建财务模型、里程碑计划或资金使用表
* 回答加速器或孵化器申请问题
* 围绕单一事实来源统一多个融资文件
## 黄金法则
所有投资者材料必须彼此一致。
在撰写前创建或确认单一事实来源：
* 增长指标
* 定价和收入假设
* 融资规模和工具
* 资金用途
* 团队简介和头衔
* 里程碑和时间线
如果出现冲突的数字，请停止起草并解决它们。
## 核心工作流程
1. 清点规范事实
2. 识别缺失的假设
3. 选择资产类型
4. 用明确的逻辑起草资产
5. 根据事实来源交叉核对每个数字
## 资产指南
### 融资演讲稿
推荐流程：
1. 公司 + 切入点
2. 问题
3. 解决方案
4. 产品 / 演示
5. 市场
6. 商业模式
7. 增长
8. 团队
9. 竞争 / 差异化
10. 融资需求
11. 资金用途 / 里程碑
12. 附录
如果用户想要一个基于网页的演讲稿，请将此技能与 `frontend-slides` 配对使用。
### 一页摘要 / 备忘录
* 用一句清晰的话说明公司做什么
* 展示为什么是现在
* 尽早包含增长数据和证明点
* 使融资需求精确
* 保持主张易于验证
### 财务模型
包含：
* 明确的假设
* 在有用时包含悲观/基准/乐观情景
* 清晰的逐层收入逻辑
* 与里程碑挂钩的支出
* 在决策依赖于假设的地方进行敏感性分析
### 加速器申请
* 回答被问的确切问题
* 优先考虑增长数据、洞察力和团队优势
* 避免夸大其词
* 保持内部指标与演讲稿和模型一致
## 需避免的危险信号
* 无法验证的主张
* 没有假设的模糊市场规模估算
* 不一致的团队角色或头衔
* 收入计算不清晰
* 在假设脆弱的地方夸大确定性
## 质量关卡
在交付前：
* 每个数字都与当前事实来源匹配
* 资金用途和收入层级计算正确
* 假设可见，而非隐藏
* 故事清晰，没有夸张语言
* 最终资产在合伙人会议上可辩护

81
docs/zh-CN/skills/investor-outreach/SKILL.md Normal file
View File

@@ -0,0 +1,81 @@
---
name: investor-outreach
description: 草拟冷邮件、热情介绍简介、跟进邮件、更新邮件和投资者沟通以筹集资金。当用户需要向天使投资人、风险投资公司、战略投资者或加速器进行推广，并需要简洁、个性化的面向投资者的消息时使用。
origin: ECC
---
# 投资者接洽
撰写简短、个性化且易于采取行动的投资者沟通内容。
## 何时激活
* 向投资者发送冷邮件时
* 起草熟人介绍请求时
* 在会议后或无回复时发送跟进邮件时
* 在融资过程中撰写投资者更新时
* 根据基金投资主题或合伙人契合度定制接洽内容时
## 核心规则
1. 个性化每一条外发信息。
2. 保持请求低门槛。
3. 使用证据，而非形容词。
4. 保持简洁。
5. 绝不发送可发给任何投资者的通用文案。
## 冷邮件结构
1. 主题行：简短且具体
2. 开头：说明为何选择这位特定投资者
3. 推介：公司做什么，为何是现在，什么证据重要
4. 请求：一个具体的下一步行动
5. 签名：姓名、职位，如需可加上一个可信度锚点
## 个性化来源
参考以下一项或多项：
* 相关的投资组合公司
* 公开的投资主题、演讲、帖子或文章
* 共同的联系人
* 与投资者关注点明确匹配的市场或产品契合度
如果缺少相关背景信息，请询问或说明草稿是等待个性化的模板。
## 跟进节奏
默认节奏：
* 第 0 天：初次外发
* 第 4-5 天：简短跟进，附带一个新数据点
* 第 10-12 天：最终跟进，干净利落地收尾
之后除非用户要求更长的跟进序列，否则不再继续提醒。
## 熟人介绍请求
为介绍人提供便利：
* 解释为何这次介绍是合适的
* 包含可转发的简介
* 将可转发的简介控制在 100 字以内
## 会后更新
包含：
* 讨论的具体事项
* 承诺的答复或更新
* 如有可能，提供一个新证据点
* 下一步行动
## 质量关卡
在交付前检查：
* 信息已个性化
* 请求明确
* 没有废话或乞求性语言
* 证据点具体
* 字数保持紧凑

11
docs/zh-CN/skills/iterative-retrieval/SKILL.md
View File

@@ -1,12 +1,21 @@
---
name: iterative-retrieval
description: 用于逐步优化上下文检索以解决子代理上下文问题的模式
description: 逐步优化上下文检索以解决子代理上下文问题的模式
origin: ECC
---
# 迭代检索模式
解决多智能体工作流中的“上下文问题”，即子智能体在开始工作前不知道需要哪些上下文。
## 何时激活
* 当需要生成需要代码库上下文但无法预先预测的子代理时
* 构建需要逐步完善上下文的多代理工作流时
* 在代理任务中遇到"上下文过大"或"缺少上下文"的失败时
* 为代码探索设计类似 RAG 的检索管道时
* 在代理编排中优化令牌使用时
## 问题
子智能体被生成时上下文有限。它们不知道：

11
docs/zh-CN/skills/java-coding-standards/SKILL.md
View File

@@ -1,12 +1,21 @@
---
name: java-coding-standards
description: Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout.
description: "Spring Boot服务的Java编码标准：命名、不可变性、Optional用法、流、异常、泛型和项目布局。"
origin: ECC
---
# Java 编码规范
适用于 Spring Boot 服务中可读、可维护的 Java (17+) 代码的规范。
## 何时激活
* 在 Spring Boot 项目中编写或审查 Java 代码时
* 强制执行命名、不可变性或异常处理约定时
* 使用记录类、密封类或模式匹配（Java 17+）时
* 审查 Optional、流或泛型的使用时
* 构建包和项目布局时
## 核心原则
* 清晰优于巧妙

12
docs/zh-CN/skills/jpa-patterns/SKILL.md
View File

@@ -1,12 +1,22 @@
---
name: jpa-patterns
description: Spring Boot中的JPA/Hibernate实体设计、关系、查询优化、事务、审计、索引、分页和连接池模式。
description: Spring Boot中的JPA/Hibernate模式，用于实体设计、关系处理、查询优化、事务管理、审计、索引、分页和连接池。
origin: ECC
---
# JPA/Hibernate 模式
用于 Spring Boot 中的数据建模、存储库和性能调优。
## 何时激活
* 设计 JPA 实体和表映射时
* 定义关系时 (@OneToMany, @ManyToOne, @ManyToMany)
* 优化查询时 (N+1 问题预防、获取策略、投影)
* 配置事务、审计或软删除时
* 设置分页、排序或自定义存储库方法时
* 调整连接池 (HikariCP) 或二级缓存时
## 实体设计
```java

280
docs/zh-CN/skills/liquid-glass-design/SKILL.md Normal file
View File

@@ -0,0 +1,280 @@
---
name: liquid-glass-design
description: iOS 26 液态玻璃设计系统 — 适用于 SwiftUI、UIKit 和 WidgetKit 的动态玻璃材质，具有模糊、反射和交互式变形效果。
---
# Liquid Glass 设计系统 (iOS 26)
实现苹果 Liquid Glass 的模式指南——这是一种动态材质，会模糊其后的内容，反射周围内容的颜色和光线，并对触摸和指针交互做出反应。涵盖 SwiftUI、UIKit 和 WidgetKit 集成。
## 何时启用
* 为 iOS 26+ 构建或更新采用新设计语言的应用程序时
* 实现玻璃风格的按钮、卡片、工具栏或容器时
* 在玻璃元素之间创建变形过渡时
* 将 Liquid Glass 效果应用于小组件时
* 将现有的模糊/材质效果迁移到新的 Liquid Glass API 时
## 核心模式 — SwiftUI
### 基本玻璃效果
为任何视图添加 Liquid Glass 的最简单方法：
```swift
Text("Hello, World!")
.font(.title)
.padding()
.glassEffect() // Default: regular variant, capsule shape
```
### 自定义形状和色调
```swift
Text("Hello, World!")
.font(.title)
.padding()
.glassEffect(.regular.tint(.orange).interactive(), in: .rect(cornerRadius: 16.0))
```
关键自定义选项：
* `.regular` — 标准玻璃效果
* `.tint(Color)` — 添加颜色色调以增强突出度
* `.interactive()` — 对触摸和指针交互做出反应
* 形状：`.capsule`（默认）、`.rect(cornerRadius:)`、`.circle`
### 玻璃按钮样式
```swift
Button("Click Me") { /* action */ }
.buttonStyle(.glass)
Button("Important") { /* action */ }
.buttonStyle(.glassProminent)
```
### 用于多个元素的 GlassEffectContainer
出于性能和变形考虑，始终将多个玻璃视图包装在一个容器中：
```swift
GlassEffectContainer(spacing: 40.0) {
HStack(spacing: 40.0) {
Image(systemName: "scribble.variable")
.frame(width: 80.0, height: 80.0)
.font(.system(size: 36))
.glassEffect()
Image(systemName: "eraser.fill")
.frame(width: 80.0, height: 80.0)
.font(.system(size: 36))
.glassEffect()
}
}
```
`spacing` 参数控制合并距离——距离更近的元素会将其玻璃形状融合在一起。
### 统一玻璃效果
使用 `glassEffectUnion` 将多个视图组合成单个玻璃形状：
```swift
@Namespace private var namespace
GlassEffectContainer(spacing: 20.0) {
HStack(spacing: 20.0) {
ForEach(symbolSet.indices, id: \.self) { item in
Image(systemName: symbolSet[item])
.frame(width: 80.0, height: 80.0)
.glassEffect()
.glassEffectUnion(id: item < 2 ? "group1" : "group2", namespace: namespace)
}
}
}
```
### 变形过渡
在玻璃元素出现/消失时创建平滑的变形效果：
```swift
@State private var isExpanded = false
@Namespace private var namespace
GlassEffectContainer(spacing: 40.0) {
HStack(spacing: 40.0) {
Image(systemName: "scribble.variable")
.frame(width: 80.0, height: 80.0)
.glassEffect()
.glassEffectID("pencil", in: namespace)
if isExpanded {
Image(systemName: "eraser.fill")
.frame(width: 80.0, height: 80.0)
.glassEffect()
.glassEffectID("eraser", in: namespace)
}
}
}
Button("Toggle") {
withAnimation { isExpanded.toggle() }
}
.buttonStyle(.glass)
```
### 将水平滚动延伸到侧边栏下方
要允许水平滚动内容延伸到侧边栏或检查器下方，请确保 `ScrollView` 内容到达容器的 leading/trailing 边缘。当布局延伸到边缘时，系统会自动处理侧边栏下方的滚动行为——无需额外的修饰符。
## 核心模式 — UIKit
### 基本 UIGlassEffect
```swift
let glassEffect = UIGlassEffect()
glassEffect.tintColor = UIColor.systemBlue.withAlphaComponent(0.3)
glassEffect.isInteractive = true
let visualEffectView = UIVisualEffectView(effect: glassEffect)
visualEffectView.translatesAutoresizingMaskIntoConstraints = false
visualEffectView.layer.cornerRadius = 20
visualEffectView.clipsToBounds = true
view.addSubview(visualEffectView)
NSLayoutConstraint.activate([
visualEffectView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
visualEffectView.centerYAnchor.constraint(equalTo: view.centerYAnchor),
visualEffectView.widthAnchor.constraint(equalToConstant: 200),
visualEffectView.heightAnchor.constraint(equalToConstant: 120)
])
// Add content to contentView
let label = UILabel()
label.text = "Liquid Glass"
label.translatesAutoresizingMaskIntoConstraints = false
visualEffectView.contentView.addSubview(label)
NSLayoutConstraint.activate([
label.centerXAnchor.constraint(equalTo: visualEffectView.contentView.centerXAnchor),
label.centerYAnchor.constraint(equalTo: visualEffectView.contentView.centerYAnchor)
])
```
### 用于多个元素的 UIGlassContainerEffect
```swift
let containerEffect = UIGlassContainerEffect()
containerEffect.spacing = 40.0
let containerView = UIVisualEffectView(effect: containerEffect)
let firstGlass = UIVisualEffectView(effect: UIGlassEffect())
let secondGlass = UIVisualEffectView(effect: UIGlassEffect())
containerView.contentView.addSubview(firstGlass)
containerView.contentView.addSubview(secondGlass)
```
### 滚动边缘效果
```swift
scrollView.topEdgeEffect.style = .automatic
scrollView.bottomEdgeEffect.style = .hard
scrollView.leftEdgeEffect.isHidden = true
```
### 工具栏玻璃集成
```swift
let favoriteButton = UIBarButtonItem(image: UIImage(systemName: "heart"), style: .plain, target: self, action: #selector(favoriteAction))
favoriteButton.hidesSharedBackground = true // Opt out of shared glass background
```
## 核心模式 — WidgetKit
### 渲染模式检测
```swift
struct MyWidgetView: View {
@Environment(\.widgetRenderingMode) var renderingMode
var body: some View {
if renderingMode == .accented {
// Tinted mode: white-tinted, themed glass background
} else {
// Full color mode: standard appearance
}
}
}
```
### 用于视觉层次结构的强调色组
```swift
HStack {
VStack(alignment: .leading) {
Text("Title")
.widgetAccentable() // Accent group
Text("Subtitle")
// Primary group (default)
}
Image(systemName: "star.fill")
.widgetAccentable() // Accent group
}
```
### 强调模式下的图像渲染
```swift
Image("myImage")
.widgetAccentedRenderingMode(.monochrome)
```
### 容器背景
```swift
VStack { /* content */ }
.containerBackground(for: .widget) {
Color.blue.opacity(0.2)
}
```
## 关键设计决策
| 决策 | 理由 |
|----------|-----------|
| 使用 GlassEffectContainer 包装 | 性能优化，实现玻璃元素之间的变形 |
| `spacing` 参数 | 控制合并距离——微调元素需要多近才能融合 |
| `@Namespace` + `glassEffectID` | 在视图层次结构变化时实现平滑的变形过渡 |
| `interactive()` 修饰符 | 明确选择加入触摸/指针反应——并非所有玻璃都应响应 |
| UIKit 中的 UIGlassContainerEffect | 与 SwiftUI 保持一致的容器模式 |
| 小组件中的强调色渲染模式 | 当用户选择带色调的主屏幕时，系统会应用带色调的玻璃效果 |
## 最佳实践
* **始终使用 GlassEffectContainer** 来为多个兄弟视图应用玻璃效果——它支持变形并提高渲染性能
* **在其他外观修饰符**（frame、font、padding）**之后应用** `.glassEffect()`
* **仅在响应用户交互的元素**（按钮、可切换项目）**上使用** `.interactive()`
* **仔细选择容器中的间距**，以控制玻璃效果何时合并
* 在更改视图层次结构时**使用** `withAnimation`，以启用平滑的变形过渡
* **在各种外观模式下测试**——浅色模式、深色模式和强调色/色调模式
* **确保可访问性对比度**——玻璃上的文本必须保持可读性
## 应避免的反模式
* 使用多个独立的 `.glassEffect()` 视图而不使用 GlassEffectContainer
* 嵌套过多玻璃效果——会降低性能和视觉清晰度
* 对每个视图都应用玻璃效果——保留给交互元素、工具栏和卡片
* 在 UIKit 中使用圆角时忘记 `clipsToBounds = true`
* 忽略小组件中的强调色渲染模式——破坏带色调的主屏幕外观
* 在玻璃效果后面使用不透明背景——破坏了半透明效果
## 使用场景
* 采用 iOS 26 新设计的导航栏、工具栏和标签栏
* 浮动操作按钮和卡片式容器
* 需要视觉深度和触摸反馈的交互控件
* 应与系统 Liquid Glass 外观集成的小组件
* 相关 UI 状态之间的变形过渡

85
docs/zh-CN/skills/market-research/SKILL.md Normal file
View File

@@ -0,0 +1,85 @@
---
name: market-research
description: 进行市场研究、竞争分析、投资者尽职调查和行业情报，附带来源归属和决策导向的摘要。适用于用户需要市场规模、竞争对手比较、基金研究、技术扫描或为商业决策提供信息的研究时。
origin: ECC
---
# 市场研究
产出支持决策的研究，而非研究表演。
## 何时激活
* 研究市场、品类、公司、投资者或技术趋势时
* 构建 TAM/SAM/SOM 估算时
* 比较竞争对手或相邻产品时
* 在接触前准备投资者档案时
* 在构建、投资或进入市场前对论点进行压力测试时
## 研究标准
1. 每个重要主张都需要有来源。
2. 优先使用近期数据，并明确指出陈旧数据。
3. 包含反面证据和不利情况。
4. 将发现转化为决策，而不仅仅是总结。
5. 清晰区分事实、推论和建议。
## 常见研究模式
### 投资者 / 基金尽职调查
收集：
* 基金规模、阶段和典型投资额度
* 相关的投资组合公司
* 公开的投资理念和近期动态
* 该基金适合或不适合的理由
* 任何明显的危险信号或不匹配之处
### 竞争分析
收集：
* 产品现实情况，而非营销文案
* 公开的融资和投资者历史
* 公开的吸引力指标
* 分销和定价线索
* 优势、劣势和定位差距
### 市场规模估算
使用：
* 来自报告或公共数据集的"自上而下"估算
* 基于现实的客户获取假设进行的"自下而上"合理性检查
* 对每个逻辑跳跃的明确假设
### 技术 / 供应商研究
收集：
* 其工作原理
* 权衡取舍和采用信号
* 集成复杂度
* 锁定、安全、合规和运营风险
## 输出格式
默认结构：
1. 执行摘要
2. 关键发现
3. 影响
4. 风险和注意事项
5. 建议
6. 来源
## 质量门
在交付前检查：
* 所有数字均已注明来源或标记为估算
* 陈旧数据已标注
* 建议源自证据
* 风险和反对论点已包含在内
* 输出使决策更容易

5
docs/zh-CN/skills/nutrient-document-processing/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: nutrient-document-processing
description: 使用Nutrient DWS API处理、转换、OCR、提取、编辑、签署和填写文档。支持PDF、DOCX、XLSX、PPTX、HTML和图像文件。
description: 使用Nutrient DWS API处理、转换、OCR识别、提取、编辑、签名和填写文档。支持PDF、DOCX、XLSX、PPTX、HTML和图像格式。
origin: ECC
---
# 文档处理
@@ -159,6 +160,6 @@ curl -X POST https://api.nutrient.io/build \
## 链接
* [API 演练场](https://dashboard.nutrient.io/processor-api/playground/)
* [API 游乐场](https://dashboard.nutrient.io/processor-api/playground/)
* [完整 API 文档](https://www.nutrient.io/guides/dws-processor/)
* [npm MCP 服务器](https://www.npmjs.com/package/@nutrient-sdk/dws-mcp-server)

3
docs/zh-CN/skills/postgres-patterns/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: postgres-patterns
description: 基于Supabase最佳实践的PostgreSQL数据库模式，用于查询优化、架构设计、索引和安全。
description: 用于查询优化、模式设计、索引和安全性的PostgreSQL数据库模式。基于Supabase最佳实践。
origin: ECC
---
# PostgreSQL 模式

8
docs/zh-CN/skills/project-guidelines-example/SKILL.md
View File

@@ -1,11 +1,15 @@
---
name: project-guidelines-example
description: "基于真实生产应用的示例项目特定技能模板。"
origin: ECC
---
# 项目指南技能（示例）
这是一个项目特定技能的示例。将其用作您自己项目的模板。
基于一个真实的生产应用程序：[Zenith](https://zenith.chat) - 由 AI 驱动的客户发现平台。
***
## 何时使用
在为其设计的特定项目上工作时，请参考此技能。项目技能包含：

3
docs/zh-CN/skills/python-patterns/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: python-patterns
description: Pythonic 惯用法、PEP 8 标准、类型提示以及构建健壮、高效、可维护的 Python 应用程序的最佳实践。
description: Pythonic 惯用法、PEP 8 标准、类型提示以及构建稳健、高效且可维护的 Python 应用程序的最佳实践。
origin: ECC
---
# Python 开发模式

3
docs/zh-CN/skills/python-testing/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: python-testing
description: 使用pytest、TDD方法、夹具、模拟、参数化和覆盖率要求的Python测试策略。
description: 使用pytest的Python测试策略，包括TDD方法、夹具、模拟、参数化和覆盖率要求。
origin: ECC
---
# Python 测试模式

220
docs/zh-CN/skills/regex-vs-llm-structured-text/SKILL.md Normal file
View File

@@ -0,0 +1,220 @@
---
name: regex-vs-llm-structured-text
description: 选择在解析结构化文本时使用正则表达式还是大型语言模型的决策框架——从正则表达式开始，仅在低置信度的边缘情况下添加大型语言模型。
origin: ECC
---
# 正则表达式 vs LLM 用于结构化文本解析
一个用于解析结构化文本（测验、表单、发票、文档）的实用决策框架。核心见解是：正则表达式能以低成本、确定性的方式处理 95-98% 的情况。将昂贵的 LLM 调用留给剩余的边缘情况。
## 何时使用
* 解析具有重复模式的结构化文本（问题、表单、表格）
* 决定在文本提取时使用正则表达式还是 LLM
* 构建结合两种方法的混合管道
* 在文本处理中优化成本/准确性权衡
## 决策框架
```
Is the text format consistent and repeating?
├── Yes (>90% follows a pattern) → Start with Regex
│ ├── Regex handles 95%+ → Done, no LLM needed
│ └── Regex handles <95% → Add LLM for edge cases only
└── No (free-form, highly variable) → Use LLM directly
```
## 架构模式
```
Source Text
│
▼
[Regex Parser] ─── Extracts structure (95-98% accuracy)
│
▼
[Text Cleaner] ─── Removes noise (markers, page numbers, artifacts)
│
▼
[Confidence Scorer] ─── Flags low-confidence extractions
│
├── High confidence (≥0.95) → Direct output
│
└── Low confidence (<0.95) → [LLM Validator] → Output
```
## 实现
### 1. 正则表达式解析器（处理大多数情况）
```python
import re
from dataclasses import dataclass
@dataclass(frozen=True)
class ParsedItem:
id: str
text: str
choices: tuple[str, ...]
answer: str
confidence: float = 1.0
def parse_structured_text(content: str) -> list[ParsedItem]:
"""Parse structured text using regex patterns."""
pattern = re.compile(
r"(?P<id>\d+)\.\s*(?P<text>.+?)\n"
r"(?P<choices>(?:[A-D]\..+?\n)+)"
r"Answer:\s*(?P<answer>[A-D])",
re.MULTILINE | re.DOTALL,
)
items = []
for match in pattern.finditer(content):
choices = tuple(
c.strip() for c in re.findall(r"[A-D]\.\s*(.+)", match.group("choices"))
)
items.append(ParsedItem(
id=match.group("id"),
text=match.group("text").strip(),
choices=choices,
answer=match.group("answer"),
))
return items
```
### 2. 置信度评分
标记可能需要 LLM 审核的项：
```python
@dataclass(frozen=True)
class ConfidenceFlag:
item_id: str
score: float
reasons: tuple[str, ...]
def score_confidence(item: ParsedItem) -> ConfidenceFlag:
"""Score extraction confidence and flag issues."""
reasons = []
score = 1.0
if len(item.choices) < 3:
reasons.append("few_choices")
score -= 0.3
if not item.answer:
reasons.append("missing_answer")
score -= 0.5
if len(item.text) < 10:
reasons.append("short_text")
score -= 0.2
return ConfidenceFlag(
item_id=item.id,
score=max(0.0, score),
reasons=tuple(reasons),
)
def identify_low_confidence(
items: list[ParsedItem],
threshold: float = 0.95,
) -> list[ConfidenceFlag]:
"""Return items below confidence threshold."""
flags = [score_confidence(item) for item in items]
return [f for f in flags if f.score < threshold]
```
### 3. LLM 验证器（仅用于边缘情况）
```python
def validate_with_llm(
item: ParsedItem,
original_text: str,
client,
) -> ParsedItem:
"""Use LLM to fix low-confidence extractions."""
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Cheapest model for validation
max_tokens=500,
messages=[{
"role": "user",
"content": (
f"Extract the question, choices, and answer from this text.\n\n"
f"Text: {original_text}\n\n"
f"Current extraction: {item}\n\n"
f"Return corrected JSON if needed, or 'CORRECT' if accurate."
),
}],
)
# Parse LLM response and return corrected item...
return corrected_item
```
### 4. 混合管道
```python
def process_document(
content: str,
*,
llm_client=None,
confidence_threshold: float = 0.95,
) -> list[ParsedItem]:
"""Full pipeline: regex -> confidence check -> LLM for edge cases."""
# Step 1: Regex extraction (handles 95-98%)
items = parse_structured_text(content)
# Step 2: Confidence scoring
low_confidence = identify_low_confidence(items, confidence_threshold)
if not low_confidence or llm_client is None:
return items
# Step 3: LLM validation (only for flagged items)
low_conf_ids = {f.item_id for f in low_confidence}
result = []
for item in items:
if item.id in low_conf_ids:
result.append(validate_with_llm(item, content, llm_client))
else:
result.append(item)
return result
```
## 实际指标
来自一个生产中的测验解析管道（410 个项目）：
| 指标 | 值 |
|--------|-------|
| 正则表达式成功率 | 98.0% |
| 低置信度项目 | 8 (2.0%) |
| 所需 LLM 调用次数 | ~5 |
| 相比全 LLM 的成本节省 | ~95% |
| 测试覆盖率 | 93% |
## 最佳实践
* **从正则表达式开始** — 即使不完美的正则表达式也能提供一个改进的基线
* **使用置信度评分** 来以编程方式识别需要 LLM 帮助的内容
* **使用最便宜的 LLM** 进行验证（Haiku 类模型已足够）
* **切勿修改** 已解析的项 — 从清理/验证步骤返回新实例
* **TDD 效果很好** 用于解析器 — 首先为已知模式编写测试，然后是边缘情况
* **记录指标**（正则表达式成功率、LLM 调用次数）以跟踪管道健康状况
## 应避免的反模式
* 当正则表达式能处理 95% 以上的情况时，将所有文本发送给 LLM（昂贵且缓慢）
* 对自由格式、高度可变的文本使用正则表达式（LLM 在此处更合适）
* 跳过置信度评分，希望正则表达式“能正常工作”
* 在清理/验证步骤中修改已解析的对象
* 不测试边缘情况（格式错误的输入、缺失字段、编码问题）
## 适用场景
* 测验/考试题目解析
* 表单数据提取
* 发票/收据处理
* 文档结构解析（标题、章节、表格）
* 任何具有重复模式且成本重要的结构化文本

174
docs/zh-CN/skills/search-first/SKILL.md Normal file
View File

@@ -0,0 +1,174 @@
---
name: search-first
description: 研究优先于编码的工作流程。在编写自定义代码之前，搜索现有的工具、库和模式。调用研究员代理。
origin: ECC
---
# /search-first — 编码前先研究
系统化“在实现之前先寻找现有解决方案”的工作流程。
## 触发时机
在以下情况使用此技能：
* 开始一项很可能已有解决方案的新功能
* 添加依赖项或集成
* 用户要求“添加 X 功能”而你准备开始编写代码
* 在创建新的实用程序、助手或抽象之前
## 工作流程
```
┌─────────────────────────────────────────────┐
│ 1. NEED ANALYSIS │
│ Define what functionality is needed │
│ Identify language/framework constraints │
├─────────────────────────────────────────────┤
│ 2. PARALLEL SEARCH (researcher agent) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ Skills │ │ Web │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. EVALUATE │
│ Score candidates (functionality, maint, │
│ community, docs, license, deps) │
├─────────────────────────────────────────────┤
│ 4. DECIDE │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Adopt │ │ Extend │ │ Build │ │
│ │ as-is │ │ /Wrap │ │ Custom │ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. IMPLEMENT │
│ Install package / Configure MCP / │
│ Write minimal custom code │
└─────────────────────────────────────────────┘
```
## 决策矩阵
| 信号 | 行动 |
|--------|--------|
| 完全匹配，维护良好，MIT/Apache 许可证 | **采纳** — 直接安装并使用 |
| 部分匹配，基础良好 | **扩展** — 安装 + 编写薄封装层 |
| 多个弱匹配 | **组合** — 组合 2-3 个小包 |
| 未找到合适的 | **构建** — 编写自定义代码，但需基于研究 |
## 使用方法
### 快速模式（内联）
在编写实用程序或添加功能之前，在脑中过一遍：
1. 这是常见问题吗？ → 搜索 npm/PyPI
2. 有相关的 MCP 吗？ → 检查 `~/.claude/settings.json` 并搜索
3. 有相关的技能吗？ → 检查 `~/.claude/skills/`
4. 有 GitHub 模板吗？ → 搜索 GitHub
### 完整模式（代理）
对于非平凡的功能，启动研究员代理：
```
Task(subagent_type="general-purpose", prompt="
Research existing tools for: [DESCRIPTION]
Language/framework: [LANG]
Constraints: [ANY]
Search: npm/PyPI, MCP servers, Claude Code skills, GitHub
Return: Structured comparison with recommendation
")
```
## 按类别搜索快捷方式
### 开发工具
* Linting → `eslint`, `ruff`, `textlint`, `markdownlint`
* Formatting → `prettier`, `black`, `gofmt`
* Testing → `jest`, `pytest`, `go test`
* Pre-commit → `husky`, `lint-staged`, `pre-commit`
### AI/LLM 集成
* Claude SDK → 使用 Context7 获取最新文档
* 提示词管理 → 检查 MCP 服务器
* 文档处理 → `unstructured`, `pdfplumber`, `mammoth`
### 数据与 API
* HTTP 客户端 → `httpx` (Python), `ky`/`got` (Node)
* 验证 → `zod` (TS), `pydantic` (Python)
* 数据库 → 首先检查是否有 MCP 服务器
### 内容与发布
* Markdown 处理 → `remark`, `unified`, `markdown-it`
* 图片优化 → `sharp`, `imagemin`
## 集成点
### 与规划器代理
规划器应在阶段 1（架构评审）之前调用研究员：
* 研究员识别可用的工具
* 规划器将它们纳入实施计划
* 避免在计划中“重新发明轮子”
### 与架构师代理
架构师应向研究员咨询：
* 技术栈决策
* 集成模式发现
* 现有参考架构
### 与迭代检索技能
结合进行渐进式发现：
* 循环 1：广泛搜索 (npm, PyPI, MCP)
* 循环 2：详细评估顶级候选方案
* 循环 3：测试与项目约束的兼容性
## 示例
### 示例 1：“添加死链检查”
```
Need: Check markdown files for broken links
Search: npm "markdown dead link checker"
Found: textlint-rule-no-dead-link (score: 9/10)
Action: ADOPT — npm install textlint-rule-no-dead-link
Result: Zero custom code, battle-tested solution
```
### 示例 2：“添加 HTTP 客户端包装器”
```
Need: Resilient HTTP client with retries and timeout handling
Search: npm "http client retry", PyPI "httpx retry"
Found: got (Node) with retry plugin, httpx (Python) with built-in retry
Action: ADOPT — use got/httpx directly with retry config
Result: Zero custom code, production-proven libraries
```
### 示例 3：“添加配置文件 linter”
```
Need: Validate project config files against a schema
Search: npm "config linter schema", "json schema validator cli"
Found: ajv-cli (score: 8/10)
Action: ADOPT + EXTEND — install ajv-cli, write project-specific schema
Result: 1 package + 1 schema file, no custom validation logic
```
## 反模式
* **直接跳转到编码**：不检查是否存在就编写实用程序
* **忽略 MCP**：不检查 MCP 服务器是否已提供该能力
* **过度定制**：对库进行如此厚重的包装以至于失去了其优势
* **依赖项膨胀**：为了一个小功能安装一个庞大的包

3
docs/zh-CN/skills/security-review/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: security-review
description: Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist and patterns.
description: 在添加身份验证、处理用户输入、处理机密信息、创建API端点或实现支付/敏感功能时使用此技能。提供全面的安全检查清单和模式。
origin: ECC
---
# 安全审查技能

3
docs/zh-CN/skills/security-scan/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: security-scan
description: 使用AgentShield扫描您的Claude Code配置（.claude/目录），检测安全漏洞、错误配置和注入风险。检查CLAUDE.md、settings.json、MCP服务器、钩子和代理定义。
description: 使用AgentShield扫描您的Claude代码配置（.claude/目录），以发现安全漏洞、配置错误和注入风险。检查CLAUDE.md、settings.json、MCP服务器、钩子和代理定义。
origin: ECC
---
# 安全扫描技能

176
docs/zh-CN/skills/skill-stocktake/SKILL.md Normal file
View File

@@ -0,0 +1,176 @@
---
description: "用于审计Claude技能和命令的质量。支持快速扫描（仅变更技能）和全面盘点模式，采用顺序子代理批量评估。"
origin: ECC
---
# skill-stocktake
斜杠命令 (`/skill-stocktake`)，用于使用质量检查清单 + AI 整体判断来审核所有 Claude 技能和命令。支持两种模式：用于最近更改技能的快速扫描，以及用于完整审查的全面盘点。
## 范围
该命令针对以下**相对于调用命令所在目录**的路径：
| 路径 | 描述 |
|------|-------------|
| `~/.claude/skills/` | 全局技能（所有项目） |
| `{cwd}/.claude/skills/` | 项目级技能（如果目录存在） |
**在第 1 阶段开始时，该命令会明确列出找到并扫描了哪些路径。**
### 针对特定项目
要包含项目级技能，请从该项目根目录运行：
```bash
cd ~/path/to/my-project
/skill-stocktake
```
如果项目没有 `.claude/skills/` 目录，则只评估全局技能和命令。
## 模式
| 模式 | 触发条件 | 持续时间 |
|------|---------|---------|
| 快速扫描 | `results.json` 存在（默认） | 5–10 分钟 |
| 全面盘点 | `results.json` 不存在，或 `/skill-stocktake full` | 20–30 分钟 |
**结果缓存：** `~/.claude/skills/skill-stocktake/results.json`
## 快速扫描流程
仅重新评估自上次运行以来发生更改的技能（5–10 分钟）。
1. 读取 `~/.claude/skills/skill-stocktake/results.json`
2. 运行：`bash ~/.claude/skills/skill-stocktake/scripts/quick-diff.sh \ ~/.claude/skills/skill-stocktake/results.json`
（项目目录从 `$PWD/.claude/skills` 自动检测；仅在需要时显式传递）
3. 如果输出是 `[]`：报告“自上次运行以来无更改。”并停止
4. 使用相同的第 2 阶段标准仅重新评估那些已更改的文件
5. 沿用先前结果中未更改的技能
6. 仅输出差异
7. 运行：`bash ~/.claude/skills/skill-stocktake/scripts/save-results.sh \ ~/.claude/skills/skill-stocktake/results.json <<< "$EVAL_RESULTS"`
## 全面盘点流程
### 第 1 阶段 — 清单
运行：`bash ~/.claude/skills/skill-stocktake/scripts/scan.sh`
脚本枚举技能文件，提取 frontmatter，并收集 UTC 修改时间。
项目目录从 `$PWD/.claude/skills` 自动检测；仅在需要时显式传递。
从脚本输出中呈现扫描摘要和清单表：
```
Scanning:
✓ ~/.claude/skills/ (17 files)
✗ {cwd}/.claude/skills/ (not found — global skills only)
```
| 技能 | 7天使用 | 30天使用 | 描述 |
|-------|--------|---------|-------------|
### 第 2 阶段 — 质量评估
启动一个 Task 工具子代理（**Explore 代理，模型：opus**），提供完整的清单和检查清单。
子代理读取每个技能，应用检查清单，并返回每个技能的 JSON：
`{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }`
**分块指导：** 每个子代理调用处理约 20 个技能，以保持上下文可管理。在每个块之后将中间结果保存到 `results.json` (`status: "in_progress"`)。
所有技能评估完成后：设置 `status: "completed"`，进入第 3 阶段。
**恢复检测：** 如果在启动时找到 `status: "in_progress"`，则从第一个未评估的技能处恢复。
每个技能都根据此检查清单进行评估：
```
- [ ] Content overlap with other skills checked
- [ ] Overlap with MEMORY.md / CLAUDE.md checked
- [ ] Freshness of technical references verified (use WebSearch if tool names / CLI flags / APIs are present)
- [ ] Usage frequency considered
```
判定标准：
| 判定 | 含义 |
|---------|---------|
| Keep | 有用且最新 |
| Improve | 值得保留，但需要特定改进 |
| Update | 引用的技术已过时（通过 WebSearch 验证） |
| Retire | 质量低、陈旧或成本不对称 |
| Merge into \[X] | 与另一技能有大量重叠；命名合并目标 |
评估是**整体 AI 判断** — 不是数字评分标准。指导维度：
* **可操作性**：代码示例、命令或步骤，让你可以立即行动
* **范围契合度**：名称、触发器和内容保持一致；不过于宽泛或狭窄
* **独特性**：价值不能被 MEMORY.md / CLAUDE.md / 其他技能取代
* **时效性**：技术引用在当前环境中有效
**原因质量要求** — `reason` 字段必须是自包含且能支持决策的：
* 不要只写“未更改” — 始终重述核心证据
* 对于 **Retire**：说明 (1) 发现了什么具体缺陷，(2) 有什么替代方案覆盖了相同需求
* 差：`"Superseded"`
* 好：`"disable-model-invocation: true already set; superseded by continuous-learning-v2 which covers all the same patterns plus confidence scoring. No unique content remains."`
* 对于 **Merge**：命名目标并描述要集成什么内容
* 差：`"Overlaps with X"`
* 好：`"42-line thin content; Step 4 of chatlog-to-article already covers the same workflow. Integrate the 'article angle' tip as a note in that skill."`
* 对于 **Improve**：描述所需的具体更改（哪个部分，什么操作，如果相关则说明目标大小）
* 差：`"Too long"`
* 好：`"276 lines; Section 'Framework Comparison' (L80–140) duplicates ai-era-architecture-principles; delete it to reach ~150 lines."`
* 对于 **Keep**（快速扫描中仅 mtime 更改）：重述原始判定理由，不要写“未更改”
* 差：`"Unchanged"`
* 好：`"mtime updated but content unchanged. Unique Python reference explicitly imported by rules/python/; no overlap found."`
### 第 3 阶段 — 摘要表
| 技能 | 7天使用 | 判定 | 原因 |
|-------|--------|---------|--------|
### 第 4 阶段 — 整合
1. **Retire / Merge**：在用户确认之前，按文件呈现详细理由：
* 发现了什么具体问题（重叠、陈旧、引用损坏等）
* 什么替代方案覆盖了相同功能（对于 Retire：哪个现有技能/规则；对于 Merge：目标文件以及要集成什么内容）
* 移除的影响（是否有依赖技能、MEMORY.md 引用或受影响的工作流）
2. **Improve**：呈现具体的改进建议及理由：
* 更改什么以及为什么（例如，“将 430 行压缩至 200 行，因为 X/Y 部分与 python-patterns 重复”）
* 用户决定是否采取行动
3. **Update**：呈现已检查来源的更新后内容
4. 检查 MEMORY.md 行数；如果超过 100 行，则建议压缩
## 结果文件模式
`~/.claude/skills/skill-stocktake/results.json`：
**`evaluated_at`**：必须设置为评估完成时的实际 UTC 时间。
通过 Bash 获取：`date -u +%Y-%m-%dT%H:%M:%SZ`。切勿使用仅日期的近似值，如 `T00:00:00Z`。
```json
{
"evaluated_at": "2026-02-21T10:00:00Z",
"mode": "full",
"batch_progress": {
"total": 80,
"evaluated": 80,
"status": "completed"
},
"skills": {
"skill-name": {
"path": "~/.claude/skills/skill-name/SKILL.md",
"verdict": "Keep",
"reason": "Concrete, actionable, unique value for X workflow",
"mtime": "2026-01-15T08:30:00Z"
}
}
}
```
## 注意事项
* 评估是盲目的：无论来源如何（ECC、自创、自动提取），所有技能都应用相同的检查清单
* 归档 / 删除操作始终需要明确的用户确认
* 不按技能来源进行判定分支

12
docs/zh-CN/skills/springboot-patterns/SKILL.md
View File

@@ -1,12 +1,22 @@
---
name: springboot-patterns
description: Spring Boot 架构模式、REST API 设计、分层服务、数据访问、缓存、异步处理和日志记录。适用于 Java Spring Boot 后端工作。
description: Spring Boot架构模式、REST API设计、分层服务、数据访问、缓存、异步处理和日志记录。用于Java Spring Boot后端工作。
origin: ECC
---
# Spring Boot 开发模式
用于可扩展、生产级服务的 Spring Boot 架构和 API 模式。
## 何时激活
* 使用 Spring MVC 或 WebFlux 构建 REST API
* 构建控制器 → 服务 → 仓库层结构
* 配置 Spring Data JPA、缓存或异步处理
* 添加验证、异常处理或分页
* 为开发/预发布/生产环境设置配置文件
* 使用 Spring Events 或 Kafka 实现事件驱动模式
## REST API 结构
```java

155
docs/zh-CN/skills/springboot-security/SKILL.md
View File

@@ -1,12 +1,23 @@
---
name: springboot-security
description: Java Spring Boot 服务中关于身份验证/授权、验证、CSRF、密钥、标头、速率限制和依赖安全的 Spring Security 最佳实践。
description: Java Spring Boot 服务中认证/授权、验证、CSRF、密钥、标头、速率限制和依赖安全性的 Spring Security 最佳实践。
origin: ECC
---
# Spring Boot 安全审查
在添加身份验证、处理输入、创建端点或处理密钥时使用。
## 何时激活
* 添加身份验证（JWT、OAuth2、基于会话）
* 实现授权（@PreAuthorize、基于角色的访问控制）
* 验证用户输入（Bean Validation、自定义验证器）
* 配置 CORS、CSRF 或安全标头
* 管理密钥（Vault、环境变量）
* 添加速率限制或暴力破解防护
* 扫描依赖项以查找 CVE
## 身份验证
* 优先使用无状态 JWT 或带有撤销列表的不透明令牌
@@ -42,17 +53,88 @@ public class JwtAuthFilter extends OncePerRequestFilter {
* 使用 `@PreAuthorize("hasRole('ADMIN')")` 或 `@PreAuthorize("@authz.canEdit(#id)")`
* 默认拒绝；仅公开必需的 scope
```java
@RestController
@RequestMapping("/api/admin")
public class AdminController {
@PreAuthorize("hasRole('ADMIN')")
@GetMapping("/users")
public List<UserDto> listUsers() {
return userService.findAll();
}
@PreAuthorize("@authz.isOwner(#id, authentication)")
@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
userService.delete(id);
return ResponseEntity.noContent().build();
}
}
```
## 输入验证
* 在控制器上使用带有 `@Valid` 的 Bean 验证
* 在 DTO 上应用约束：`@NotBlank`、`@Email`、`@Size`、自定义验证器
* 在渲染之前使用白名单清理任何 HTML
```java
// BAD: No validation
@PostMapping("/users")
public User createUser(@RequestBody UserDto dto) {
return userService.create(dto);
}
// GOOD: Validated DTO
public record CreateUserDto(
@NotBlank @Size(max = 100) String name,
@NotBlank @Email String email,
@NotNull @Min(0) @Max(150) Integer age
) {}
@PostMapping("/users")
public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserDto dto) {
return ResponseEntity.status(HttpStatus.CREATED)
.body(userService.create(dto));
}
```
## SQL 注入预防
* 使用 Spring Data 存储库或参数化查询
* 对于原生查询，使用 `:param` 绑定；切勿拼接字符串
```java
// BAD: String concatenation in native query
@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
// GOOD: Parameterized native query
@Query(value = "SELECT * FROM users WHERE name = :name", nativeQuery = true)
List<User> findByName(@Param("name") String name);
// GOOD: Spring Data derived query (auto-parameterized)
List<User> findByEmailAndActiveTrue(String email);
```
## 密码编码
* 始终使用 BCrypt 或 Argon2 哈希密码——切勿存储明文
* 使用 `PasswordEncoder` Bean，而非手动哈希
```java
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder(12); // cost factor 12
}
// In service
public User register(CreateUserDto dto) {
String hashedPassword = passwordEncoder.encode(dto.password());
return userRepository.save(new User(dto.email(), hashedPassword));
}
```
## CSRF 保护
* 对于浏览器会话应用程序，保持 CSRF 启用；在表单/头中包含令牌
@@ -70,6 +152,25 @@ http
* 保持 `application.yml` 不包含凭据；使用占位符
* 定期轮换令牌和数据库凭据
```yaml
# BAD: Hardcoded in application.yml
spring:
datasource:
password: mySecretPassword123
# GOOD: Environment variable placeholder
spring:
datasource:
password: ${DB_PASSWORD}
# GOOD: Spring Cloud Vault integration
spring:
cloud:
vault:
uri: https://vault.example.com
token: ${VAULT_TOKEN}
```
## 安全头
```java
@@ -82,11 +183,63 @@ http
.referrerPolicy(rp -> rp.policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.NO_REFERRER)));
```
## CORS 配置
* 在安全过滤器级别配置 CORS，而非按控制器配置
* 限制允许的来源——在生产环境中切勿使用 `*`
```java
@Bean
public CorsConfigurationSource corsConfigurationSource() {
CorsConfiguration config = new CorsConfiguration();
config.setAllowedOrigins(List.of("https://app.example.com"));
config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
config.setAllowCredentials(true);
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/api/**", config);
return source;
}
// In SecurityFilterChain:
http.cors(cors -> cors.configurationSource(corsConfigurationSource()));
```
## 速率限制
* 在昂贵的端点上应用 Bucket4j 或网关级限制
* 记录突发流量并告警；返回 429 并提供重试提示
```java
// Using Bucket4j for per-endpoint rate limiting
@Component
public class RateLimitFilter extends OncePerRequestFilter {
private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
private Bucket createBucket() {
return Bucket.builder()
.addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
.build();
}
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
FilterChain chain) throws ServletException, IOException {
String clientIp = request.getRemoteAddr();
Bucket bucket = buckets.computeIfAbsent(clientIp, k -> createBucket());
if (bucket.tryConsume(1)) {
chain.doFilter(request, response);
} else {
response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
response.getWriter().write("{\"error\": \"Rate limit exceeded\"}");
}
}
}
```
## 依赖项安全
* 在 CI 中运行 OWASP Dependency Check / Snyk

1
docs/zh-CN/skills/springboot-tdd/SKILL.md
View File

@@ -1,6 +1,7 @@
---
name: springboot-tdd
description: 使用JUnit 5、Mockito、MockMvc、Testcontainers和JaCoCo进行Spring Boot的测试驱动开发。适用于添加功能、修复错误或重构时。
origin: ECC
---
# Spring Boot TDD 工作流程

Some files were not shown because too many files have changed in this diff Show More