feat(zh): add Chinese translations in zh/ directory
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
This commit is contained in:
Luong NGUYEN
43
zh/.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
43
zh/.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: 报告示例、指南或文档中的问题
|
||||
title: "[BUG] "
|
||||
labels: bug
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## 问题描述
|
||||
简要说明问题。
|
||||
|
||||
## 复现步骤
|
||||
1. 第 1 步
|
||||
2. 第 2 步
|
||||
3. 第 3 步
|
||||
|
||||
## 预期行为
|
||||
应该发生什么？
|
||||
|
||||
## 实际行为
|
||||
实际发生了什么？
|
||||
|
||||
## 环境
|
||||
- **Claude Code 版本**：（例如 1.0.5）
|
||||
- **操作系统**：（例如 macOS 14.1、Ubuntu 22.04、Windows 11）
|
||||
- **Python 版本**：（如有相关，例如 3.11）
|
||||
- **受影响的组件**：（例如 01-slash-commands、03-skills 等）
|
||||
|
||||
## 示例代码
|
||||
如果适用，请提供无法正常工作的示例代码：
|
||||
```
|
||||
[在这里插入代码]
|
||||
```
|
||||
|
||||
## 截图
|
||||
如果适用，请附上显示问题的截图。
|
||||
|
||||
## 其他上下文
|
||||
还有哪些信息可能有助于我们理解这个问题？
|
||||
|
||||
## 可能的解决方案
|
||||
如果你有修复建议，也可以写在这里。
|
||||
44
zh/.github/ISSUE_TEMPLATE/documentation.md
vendored
Normal file
44
zh/.github/ISSUE_TEMPLATE/documentation.md
vendored
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
name: Documentation Issue
|
||||
about: 报告文档中的不清晰、错别字或缺失信息
|
||||
title: "[DOCS] "
|
||||
labels: documentation
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## 问题类型
|
||||
- [ ] 拼写或语法错误
|
||||
- [ ] 解释不清
|
||||
- [ ] 缺少信息
|
||||
- [ ] 链接或引用损坏
|
||||
- [ ] 内容过时
|
||||
- [ ] 需要更好的示例
|
||||
|
||||
## 位置
|
||||
哪一部分有问题？
|
||||
- **文件**：（例如 README.md、03-skills/README.md）
|
||||
- **章节**：（例如 "Installation Quick Reference"）
|
||||
- **行号/区域**：（如有具体位置）
|
||||
|
||||
## 当前内容
|
||||
当前写的是什么？
|
||||
```
|
||||
[在这里粘贴当前文本]
|
||||
```
|
||||
|
||||
## 问题说明
|
||||
哪里有问题？
|
||||
|
||||
## 建议改进
|
||||
应该如何改进或澄清？
|
||||
```
|
||||
[在这里提供改进后的文本或建议]
|
||||
```
|
||||
|
||||
## 这样做的重要性
|
||||
这个问题会怎样影响用户？
|
||||
|
||||
## 相关文档
|
||||
相关章节链接：
|
||||
- 相关指南：<!-- 在这里添加链接 -->
|
||||
46
zh/.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
46
zh/.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: 建议新增示例、指南或改进
|
||||
title: "[FEATURE] "
|
||||
labels: enhancement
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## 描述
|
||||
描述你希望看到的功能或改进。
|
||||
|
||||
## 它解决了什么问题
|
||||
它解决了什么问题或缺口？
|
||||
|
||||
示例：
|
||||
- 没有 X 功能的示例
|
||||
- Y 功能的现有文档不清楚
|
||||
- 我们需要 Z 场景的指南
|
||||
- 结构可以通过以下方式改进……
|
||||
|
||||
## 使用场景
|
||||
这个功能会在什么时候、怎样使用？请包含真实场景。
|
||||
|
||||
## 建议方案
|
||||
应该如何实现或记录？
|
||||
|
||||
## 示例
|
||||
如果适用，请提供你设想的示例：
|
||||
```
|
||||
[在这里插入示例]
|
||||
```
|
||||
|
||||
## 相关示例
|
||||
链接任何已有的相关示例或指南：
|
||||
- 现有指南：<!-- 在这里添加链接 -->
|
||||
- 功能：（例如 Skills、Hooks、Subagents）
|
||||
|
||||
## 其他上下文
|
||||
还有哪些可能有帮助的信息？
|
||||
|
||||
## 验收标准
|
||||
怎样才算这个功能完成？
|
||||
- [ ] 标准 1
|
||||
- [ ] 标准 2
|
||||
- [ ] 标准 3
|
||||
40
zh/.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
40
zh/.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: Question
|
||||
about: 提出关于 Claude Code 或本指南的问题
|
||||
title: "[QUESTION] "
|
||||
labels: question
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## 问题
|
||||
你想了解什么？
|
||||
|
||||
## 背景
|
||||
请提供一些背景或上下文：
|
||||
- 你想做什么？
|
||||
- 你已经尝试过什么？
|
||||
- 你看过哪些示例或指南？
|
||||
|
||||
## 相关主题
|
||||
这个问题属于哪个主题？
|
||||
- [ ] Slash Commands
|
||||
- [ ] Memory
|
||||
- [ ] Skills
|
||||
- [ ] Subagents
|
||||
- [ ] MCP Protocol
|
||||
- [ ] Hooks
|
||||
- [ ] Plugins
|
||||
- [ ] Checkpoints
|
||||
- [ ] Advanced Features
|
||||
- [ ] CLI Reference
|
||||
- [ ] 其他
|
||||
|
||||
## 你尝试过什么
|
||||
你已经尝试了什么？结果如何？
|
||||
|
||||
## 期望结果
|
||||
什么样的结果能帮助你解决问题？
|
||||
|
||||
## 其他资源
|
||||
还有哪些可能相关的链接或资源？
|
||||
309
zh/.github/SECURITY_REPORTING.md
vendored
Normal file
309
zh/.github/SECURITY_REPORTING.md
vendored
Normal file
@@ -0,0 +1,309 @@
|
||||
# 安全漏洞报告
|
||||
|
||||
本文说明如何向 Claude How To 项目报告安全漏洞。
|
||||
|
||||
## 快速链接
|
||||
|
||||
- **私密报告**：<https://github.com/luongnv89/claude-howto/security/advisories>
|
||||
- **安全政策**：[SECURITY.md](../SECURITY.md)
|
||||
- **报告模板**：见下文
|
||||
|
||||
## 报告漏洞
|
||||
|
||||
### 选项 1：GitHub 私密漏洞报告（推荐）
|
||||
|
||||
这是报告安全漏洞的首选方式。
|
||||
|
||||
**步骤：**
|
||||
1. 访问：<https://github.com/luongnv89/claude-howto/security/advisories>
|
||||
2. 点击 “Report a vulnerability”
|
||||
3. 填写详情（可使用下方模板）
|
||||
4. 提交
|
||||
|
||||
**优点：**
|
||||
- 在修复发布前保持漏洞私密
|
||||
- 自动通知维护者
|
||||
- 内置协作功能
|
||||
- 与 GitHub 安全工具集成
|
||||
|
||||
### 选项 2：GitHub 安全警报（依赖漏洞）
|
||||
|
||||
如果你在依赖中发现漏洞：
|
||||
|
||||
1. 访问：<https://github.com/luongnv89/claude-howto/security/advisories>
|
||||
2. 查看警报
|
||||
3. 提交包含修复的 pull request
|
||||
4. 加上 `security` 标签
|
||||
|
||||
### 选项 3：私密邮箱（GitHub 不可用时）
|
||||
|
||||
如果你无法使用 GitHub 的报告系统：
|
||||
|
||||
**即将提供**：这里会补充安全联系邮箱
|
||||
|
||||
目前请优先使用上面的 GitHub 私密漏洞报告。
|
||||
|
||||
## 漏洞报告模板
|
||||
|
||||
报告漏洞时可使用以下模板：
|
||||
|
||||
```
|
||||
**标题**：[漏洞简述]
|
||||
|
||||
**严重性**：[Critical/High/Medium/Low]
|
||||
Estimated CVSS Score: [0-10]
|
||||
|
||||
**类型**：[代码/文档/依赖/配置]
|
||||
|
||||
**受影响组件**：
|
||||
- File: [path/to/file.py]
|
||||
- Section: [文档章节名，如适用]
|
||||
- Version: [latest/具体版本]
|
||||
|
||||
**描述**：
|
||||
[对漏洞的清晰说明]
|
||||
|
||||
**潜在影响**：
|
||||
[攻击者可以利用该漏洞做什么？]
|
||||
[可能影响哪些人？]
|
||||
|
||||
**复现步骤**：
|
||||
1. [第一步]
|
||||
2. [第二步]
|
||||
3. [第三步]
|
||||
[预期结果与实际结果]
|
||||
|
||||
**PoC**（如有）：
|
||||
[用于演示漏洞的代码或步骤]
|
||||
|
||||
**建议修复**：
|
||||
[你的建议方案，如有]
|
||||
|
||||
**附加上下文**：
|
||||
[任何其他相关信息]
|
||||
|
||||
**你的信息**：
|
||||
- Name: [你的名字或匿名]
|
||||
- Email: [你的邮箱]
|
||||
- Credit: [你希望如何署名，如有]
|
||||
```
|
||||
|
||||
## 提交后会发生什么
|
||||
|
||||
### 时间线
|
||||
|
||||
1. **立刻（< 1 小时）**
|
||||
- 自动通知会发送给项目维护者
|
||||
|
||||
2. **24 小时内**
|
||||
- 对报告进行初步评估
|
||||
- 确认已收到
|
||||
- 初步严重性评估
|
||||
|
||||
3. **48 小时内**
|
||||
- 安全团队给出详细回复
|
||||
- 如需更多信息会继续询问
|
||||
- 如果确认漏洞存在，会给出修复时间线
|
||||
|
||||
4. **1-7 天内**（取决于严重性）
|
||||
- 完成修复并测试
|
||||
- 准备安全公告
|
||||
- 发布修复并公开公告
|
||||
|
||||
### 沟通方式
|
||||
|
||||
我们会通过以下方式与你保持沟通：
|
||||
- GitHub 私密漏洞讨论
|
||||
- 邮件（如果你提供了）
|
||||
- 讨论线程中的更新
|
||||
|
||||
你可以：
|
||||
- 提出澄清问题
|
||||
- 补充更多信息
|
||||
- 建议改进修复方案
|
||||
- 请求调整时间线
|
||||
|
||||
### 披露时间线
|
||||
|
||||
**严重问题（CVSS 9.0-10.0）**
|
||||
- 修复：立即发布（24 小时内）
|
||||
- 披露：当天发布公开公告
|
||||
- 通知：提前 24 小时通知报告者
|
||||
|
||||
**高危问题（CVSS 7.0-8.9）**
|
||||
- 修复：48-72 小时内发布
|
||||
- 披露：发布时公开公告
|
||||
- 通知：提前 5 天通知报告者
|
||||
|
||||
**中危问题（CVSS 4.0-6.9）**
|
||||
- 修复：纳入下一次常规更新
|
||||
- 披露：发布时公开公告
|
||||
- 通知：协调时间线
|
||||
|
||||
**低危问题（CVSS 0.1-3.9）**
|
||||
- 修复：纳入下一次常规更新
|
||||
- 披露：发布时公告
|
||||
- 通知：与发布同日
|
||||
|
||||
## 安全漏洞标准
|
||||
|
||||
### 范围内
|
||||
|
||||
我们接受以下类型的报告：
|
||||
|
||||
- **代码漏洞**
|
||||
- 注入攻击（命令、SQL 等）
|
||||
- 示例中的跨站脚本（XSS）
|
||||
- 认证/授权缺陷
|
||||
- 路径穿越漏洞
|
||||
- 密码学问题
|
||||
|
||||
- **文档安全**
|
||||
- 暴露的秘密或凭据
|
||||
- 不安全代码模式
|
||||
- 安全反模式
|
||||
- 误导性的安全声明
|
||||
|
||||
- **依赖漏洞**
|
||||
- 依赖中的已知 CVE
|
||||
- 供应链攻击
|
||||
- 恶意依赖
|
||||
|
||||
- **配置问题**
|
||||
- 不安全默认值
|
||||
- 缺失安全头
|
||||
- 示例中的凭据暴露
|
||||
|
||||
### 范围外
|
||||
|
||||
以下内容不接受报告：
|
||||
|
||||
- Claude Code 本身的漏洞（请联系 Anthropic）
|
||||
- 外部服务中的漏洞
|
||||
- 没有证明的理论漏洞
|
||||
- 已向上游项目报告的问题
|
||||
- 社会工程学或钓鱼
|
||||
- 用户教育 / 培训问题
|
||||
|
||||
## 负责任披露指南
|
||||
|
||||
### 应该做的 ✅
|
||||
|
||||
- **先私下报告**，再公开披露
|
||||
- **尽量具体**，提供文件路径和行号
|
||||
- **提供证明**，说明漏洞确实存在
|
||||
- **给我们时间**修复（协调披露）
|
||||
- **补充更新**，如果你发现了更多细节
|
||||
- **保持专业**，在所有沟通中都如此
|
||||
- **尊重保密性**，直到我们公开发布
|
||||
|
||||
### 不应该做的 ❌
|
||||
|
||||
- **不要在修复前公开披露**
|
||||
- **不要超出测试所需范围去利用漏洞**
|
||||
- **不要修改**其他用户的数据
|
||||
- **不要索要**报酬或好处
|
||||
- **不要把漏洞**分享给其他人
|
||||
- **不要用于**任何有害用途
|
||||
- **不要用**非安全相关 issue 刷屏
|
||||
|
||||
## 协调披露
|
||||
|
||||
我们遵循负责任披露流程：
|
||||
|
||||
1. **私密报告**：你先私下告诉我们
|
||||
2. **我们评估**：判断并评估严重性
|
||||
3. **开发修复**：我们开发并测试修复
|
||||
4. **提前通知**：在公开披露前提前通知你
|
||||
5. **公开发布**：我们同时发布修复和公告
|
||||
6. **你的署名**：如你愿意，会在公告中致谢
|
||||
|
||||
**具体时间会根据严重性变化**（见上文）
|
||||
|
||||
## 修复发布后
|
||||
|
||||
### 公开公告
|
||||
|
||||
公开安全公告通常包含：
|
||||
- 漏洞描述
|
||||
- 受影响版本
|
||||
- 严重性（CVSS 分数）
|
||||
- 修复步骤
|
||||
- 修复链接
|
||||
- 对报告者的致谢（如获许可）
|
||||
|
||||
### 你的署名
|
||||
|
||||
如果你希望被致谢：
|
||||
- 公告中会写上你的名字/昵称
|
||||
- 可附上你的个人资料或网站链接
|
||||
- 在发布说明中致谢
|
||||
- 如果未来建立名人堂，也可能加入
|
||||
|
||||
### 不提供金钱补偿
|
||||
|
||||
请注意：
|
||||
- 这是一个志愿者维护的开源项目
|
||||
- 我们无法提供金钱奖励
|
||||
- 但会提供认可和署名
|
||||
- 你的贡献会帮助整个社区
|
||||
|
||||
## 安全研究
|
||||
|
||||
如果你在做安全研究：
|
||||
|
||||
1. **先取得许可**：先联系维护者
|
||||
2. **明确范围**：约定你会测试什么
|
||||
3. **报告发现**：使用本流程
|
||||
4. **尊重时间线**：给我们时间修复
|
||||
5. **负责任地发布**：与我们协调
|
||||
|
||||
## 有问题？
|
||||
|
||||
如果你对这个流程有疑问：
|
||||
|
||||
1. 查看 [SECURITY.md](../SECURITY.md) 的完整政策
|
||||
2. 查看下方的 [FAQ](#faq)
|
||||
3. 使用 `[SECURITY]` 标签发起 discussion
|
||||
4. 对敏感问题使用私密漏洞报告
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: 我的报告会保密吗？**
|
||||
A: 会，直到修复发布。我们只会与参与修复的人共享细节。
|
||||
|
||||
**Q: 我需要等多久才能公开披露？**
|
||||
A: 我们会按照严重性遵循负责任披露时间线（24 小时到 7 天）。如有需要，你可以同意延长。
|
||||
|
||||
**Q: 我会获得署名吗？**
|
||||
A: 会，会出现在安全公告和发布说明中（除非你希望匿名）。
|
||||
|
||||
**Q: 如果漏洞很小怎么办？**
|
||||
A: 所有真实的安全问题都会被认真对待，即使很小也会被记录和致谢。
|
||||
|
||||
**Q: 我可以只报告文档里的漏洞吗？**
|
||||
A: 可以。文档安全同样重要。不安全示例也在范围内。
|
||||
|
||||
**Q: 如果我不确定这是不是安全问题呢？**
|
||||
A: 先报告即可！如果不是安全问题，我们会告诉你。误报没关系。
|
||||
|
||||
**Q: 报告后我可以公开讨论吗？**
|
||||
A: 不可以，请在我们公开公告前保持私密。过早披露可能让用户面临风险。
|
||||
|
||||
**Q: 我怎么知道你收到了我的报告？**
|
||||
A: GitHub 会发送自动通知，我们会在 24 小时内跟进。
|
||||
|
||||
**Q: 如果我一直没收到回复怎么办？**
|
||||
A: 检查 GitHub security advisories 页面。如果仍看不到回复，可以在私密报告里继续留言跟进。
|
||||
|
||||
## 资源
|
||||
|
||||
- [SECURITY.md](../SECURITY.md) - 完整安全政策
|
||||
- [CONTRIBUTING.md](../CONTRIBUTING.md) - 贡献指南
|
||||
- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - 社区标准
|
||||
- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - 负责任披露最佳实践
|
||||
- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html)
|
||||
|
||||
---
|
||||
|
||||
感谢你帮助维护项目安全！🔒
|
||||
341
zh/.github/TESTING.md
vendored
Normal file
341
zh/.github/TESTING.md
vendored
Normal file
@@ -0,0 +1,341 @@
|
||||
# 测试指南
|
||||
|
||||
本文档说明 Claude How To 的测试基础设施。
|
||||
|
||||
## 概览
|
||||
|
||||
项目使用 GitHub Actions 在每次 push 和 pull request 时自动运行测试。测试覆盖：
|
||||
|
||||
- **单元测试**：使用 pytest 的 Python 测试
|
||||
- **代码质量**：使用 Ruff 做 lint 和格式化
|
||||
- **安全**：使用 Bandit 做漏洞扫描
|
||||
- **类型检查**：使用 mypy 做静态类型分析
|
||||
- **构建验证**：EPUB 生成测试
|
||||
|
||||
## 在本地运行测试
|
||||
|
||||
### 前置条件
|
||||
|
||||
```bash
|
||||
# 安装 uv（快速 Python 包管理器）
|
||||
pip install uv
|
||||
|
||||
# 或者在 macOS 上使用 Homebrew
|
||||
brew install uv
|
||||
```
|
||||
|
||||
### 配置环境
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone https://github.com/luongnv89/claude-howto.git
|
||||
cd claude-howto
|
||||
|
||||
# 创建虚拟环境
|
||||
uv venv
|
||||
|
||||
# 激活虚拟环境
|
||||
source .venv/bin/activate # macOS/Linux
|
||||
# 或者
|
||||
.venv\Scripts\activate # Windows
|
||||
|
||||
# 安装开发依赖
|
||||
uv pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 运行所有单元测试
|
||||
pytest scripts/tests/ -v
|
||||
|
||||
# 运行带覆盖率的测试
|
||||
pytest scripts/tests/ -v --cov=scripts --cov-report=html
|
||||
|
||||
# 运行指定测试文件
|
||||
pytest scripts/tests/test_build_epub.py -v
|
||||
|
||||
# 运行指定测试函数
|
||||
pytest scripts/tests/test_build_epub.py::test_function_name -v
|
||||
|
||||
# 以 watch 模式运行测试（需要 pytest-watch）
|
||||
ptw scripts/tests/
|
||||
```
|
||||
|
||||
### 运行 lint
|
||||
|
||||
```bash
|
||||
# 检查代码格式
|
||||
ruff format --check scripts/
|
||||
|
||||
# 自动修复格式问题
|
||||
ruff format scripts/
|
||||
|
||||
# 运行 lint
|
||||
ruff check scripts/
|
||||
|
||||
# 自动修复 lint 问题
|
||||
ruff check --fix scripts/
|
||||
```
|
||||
|
||||
### 运行安全扫描
|
||||
|
||||
```bash
|
||||
# 运行 Bandit 安全扫描
|
||||
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/
|
||||
|
||||
# 生成 JSON 报告
|
||||
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json
|
||||
```
|
||||
|
||||
### 运行类型检查
|
||||
|
||||
```bash
|
||||
# 使用 mypy 检查类型
|
||||
mypy scripts/ --ignore-missing-imports --no-implicit-optional
|
||||
```
|
||||
|
||||
## GitHub Actions 工作流
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 推送到 `main` 或 `develop` 分支（当 `scripts` 有变更时）
|
||||
- 向 `main` 提交 Pull Request（当 `scripts` 有变更时）
|
||||
- 手动触发 workflow
|
||||
|
||||
### 作业
|
||||
|
||||
#### 1. 单元测试（pytest）
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **Python 版本**：3.10、3.11、3.12
|
||||
- **执行内容**：
|
||||
- 从 `requirements-dev.txt` 安装依赖
|
||||
- 运行 pytest 并生成覆盖率报告
|
||||
- 将覆盖率上传到 Codecov
|
||||
- 归档测试结果和 HTML 覆盖率报告
|
||||
|
||||
**结果**：如果任何测试失败，工作流失败（关键）
|
||||
|
||||
#### 2. 代码质量（Ruff）
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **Python 版本**：3.11
|
||||
- **执行内容**：
|
||||
- 使用 `ruff format` 检查格式
|
||||
- 使用 `ruff check` 运行 lint
|
||||
- 报告问题，但不会让整个工作流失败
|
||||
|
||||
**结果**：非阻塞（仅警告）
|
||||
|
||||
#### 3. 安全扫描（Bandit）
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **Python 版本**：3.11
|
||||
- **执行内容**：
|
||||
- 扫描安全漏洞
|
||||
- 生成 JSON 报告
|
||||
- 将报告作为 artifact 上传
|
||||
|
||||
**结果**：非阻塞（仅警告）
|
||||
|
||||
#### 4. 类型检查（mypy）
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **Python 版本**：3.11
|
||||
- **执行内容**：
|
||||
- 执行静态类型分析
|
||||
- 报告类型不匹配
|
||||
- 帮助尽早发现 bug
|
||||
|
||||
**结果**：非阻塞（仅警告）
|
||||
|
||||
#### 5. 构建 EPUB
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **依赖**：pytest、lint、安全扫描（都必须通过）
|
||||
- **执行内容**：
|
||||
- 使用 `scripts/build_epub.py` 构建 EPUB
|
||||
- 验证 EPUB 是否成功生成
|
||||
- 将 EPUB 作为 artifact 上传
|
||||
|
||||
**结果**：如果构建失败，工作流失败（关键）
|
||||
|
||||
#### 6. 总结
|
||||
|
||||
- **运行环境**：Ubuntu latest
|
||||
- **依赖**：所有其他作业
|
||||
- **执行内容**：
|
||||
- 生成工作流总结
|
||||
- 列出所有 artifacts
|
||||
- 汇总总体状态
|
||||
|
||||
## 编写测试
|
||||
|
||||
### 测试结构
|
||||
|
||||
测试应放在 `scripts/tests/` 中，文件名形如 `test_*.py`：
|
||||
|
||||
```python
|
||||
# scripts/tests/test_example.py
|
||||
import pytest
|
||||
from scripts.example_module import some_function
|
||||
|
||||
def test_basic_functionality():
|
||||
"""测试 some_function 是否正常工作。"""
|
||||
result = some_function("input")
|
||||
assert result == "expected_output"
|
||||
|
||||
def test_error_handling():
|
||||
"""测试 some_function 是否能优雅处理错误。"""
|
||||
with pytest.raises(ValueError):
|
||||
some_function("invalid_input")
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_async_function():
|
||||
"""测试异步函数。"""
|
||||
result = await async_function()
|
||||
assert result is not None
|
||||
```
|
||||
|
||||
### 测试最佳实践
|
||||
|
||||
- **使用有描述性的名称**：例如 `test_function_returns_correct_value()`
|
||||
- **尽量每个测试只做一个断言**：更容易排查失败原因
|
||||
- **使用 fixture** 复用初始化逻辑：见 `scripts/tests/conftest.py`
|
||||
- **Mock 外部服务**：使用 `unittest.mock` 或 `pytest-mock`
|
||||
- **测试边界情况**：空输入、None 值、错误情况
|
||||
- **保持测试快速**：避免 `sleep()` 和外部 I/O
|
||||
- **使用 pytest 标记**：例如 `@pytest.mark.slow` 标记慢测试
|
||||
|
||||
### Fixtures
|
||||
|
||||
常用 fixture 定义在 `scripts/tests/conftest.py`：
|
||||
|
||||
```python
|
||||
# 在测试中使用 fixture
|
||||
def test_something(tmp_path):
|
||||
"""tmp_path fixture 提供临时目录。"""
|
||||
test_file = tmp_path / "test.txt"
|
||||
test_file.write_text("content")
|
||||
assert test_file.read_text() == "content"
|
||||
```
|
||||
|
||||
## 覆盖率报告
|
||||
|
||||
### 本地覆盖率
|
||||
|
||||
```bash
|
||||
# 生成覆盖率报告
|
||||
pytest scripts/tests/ --cov=scripts --cov-report=html
|
||||
|
||||
# 在浏览器中打开覆盖率报告
|
||||
open htmlcov/index.html
|
||||
```
|
||||
|
||||
### 覆盖率目标
|
||||
|
||||
- **最低覆盖率**：80%
|
||||
- **分支覆盖率**：启用
|
||||
- **重点区域**：核心功能和错误路径
|
||||
|
||||
## Pre-commit Hooks
|
||||
|
||||
项目使用 pre-commit hooks 在每次提交前自动运行检查：
|
||||
|
||||
```bash
|
||||
# 安装 pre-commit hooks
|
||||
pre-commit install
|
||||
|
||||
# 手动运行 hooks
|
||||
pre-commit run --all-files
|
||||
|
||||
# 跳过某次提交的 hooks（不推荐）
|
||||
git commit --no-verify
|
||||
```
|
||||
|
||||
在 `.pre-commit-config.yaml` 中配置的 hooks：
|
||||
- Ruff formatter
|
||||
- Ruff linter
|
||||
- Bandit security scanner
|
||||
- YAML validation
|
||||
- 文件大小检查
|
||||
- 合并冲突检测
|
||||
|
||||
## 排障
|
||||
|
||||
### 本地测试通过，但 CI 失败
|
||||
|
||||
常见原因：
|
||||
1. **Python 版本差异**：CI 使用 3.10、3.11、3.12
|
||||
2. **依赖缺失**：更新 `requirements-dev.txt`
|
||||
3. **平台差异**：路径分隔符、环境变量
|
||||
4. **测试不稳定**：依赖时序或执行顺序的测试
|
||||
|
||||
解决方案：
|
||||
```bash
|
||||
# 使用相同的 Python 版本测试
|
||||
uv python install 3.10 3.11 3.12
|
||||
|
||||
# 使用干净环境测试
|
||||
rm -rf .venv
|
||||
uv venv
|
||||
uv pip install -r requirements-dev.txt
|
||||
pytest scripts/tests/
|
||||
```
|
||||
|
||||
### Bandit 报告误报
|
||||
|
||||
某些安全警告可能是误报。可在 `pyproject.toml` 中配置：
|
||||
|
||||
```toml
|
||||
[tool.bandit]
|
||||
exclude_dirs = ["scripts/tests"]
|
||||
skips = ["B101"] # 跳过 assert_used 警告
|
||||
```
|
||||
|
||||
### 类型检查太严格
|
||||
|
||||
对特定文件放宽类型检查：
|
||||
|
||||
```python
|
||||
# 放在文件顶部
|
||||
# type: ignore
|
||||
|
||||
# 或者针对特定行
|
||||
some_dynamic_code() # type: ignore
|
||||
```
|
||||
|
||||
## 持续集成最佳实践
|
||||
|
||||
1. **保持测试快速**：每个测试最好在 1 秒内完成
|
||||
2. **不要测试外部 API**：用 mock 替代外部服务
|
||||
3. **测试要隔离**：每个测试都应独立
|
||||
4. **断言要清晰**：写 `assert x == 5`，不要写 `assert x`
|
||||
5. **处理异步测试**：使用 `@pytest.mark.asyncio`
|
||||
6. **生成报告**：覆盖率、安全扫描、类型检查
|
||||
|
||||
## 资源
|
||||
|
||||
- [pytest Documentation](https://docs.pytest.org/)
|
||||
- [Ruff Documentation](https://docs.astral.sh/ruff/)
|
||||
- [Bandit Documentation](https://bandit.readthedocs.io/)
|
||||
- [mypy Documentation](https://mypy.readthedocs.io/)
|
||||
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
||||
|
||||
## 贡献测试
|
||||
|
||||
提交 PR 时：
|
||||
|
||||
1. **为新功能编写测试**
|
||||
2. **本地运行测试**：`pytest scripts/tests/ -v`
|
||||
3. **检查覆盖率**：`pytest scripts/tests/ --cov=scripts`
|
||||
4. **运行 lint**：`ruff check scripts/`
|
||||
5. **安全扫描**：`bandit -r scripts/ --exclude scripts/tests/`
|
||||
6. **如果测试变化，更新文档**
|
||||
|
||||
所有 PR 都必须包含测试！🧪
|
||||
|
||||
---
|
||||
|
||||
如果你对测试有问题或疑问，请在 GitHub 上创建 issue 或 discussion。
|
||||
57
zh/.github/pull_request_template.md
vendored
Normal file
57
zh/.github/pull_request_template.md
vendored
Normal file
@@ -0,0 +1,57 @@
|
||||
## 描述
|
||||
简要说明这个 PR 做了什么。
|
||||
|
||||
## 变更类型
|
||||
- [ ] 新增示例或模板
|
||||
- [ ] 文档改进
|
||||
- [ ] Bug 修复
|
||||
- [ ] 功能指南
|
||||
- [ ] 其他（请说明）
|
||||
|
||||
## 相关 Issues
|
||||
Closes #(issue number)
|
||||
|
||||
## 已做的修改
|
||||
- 修改 1
|
||||
- 修改 2
|
||||
- 修改 3
|
||||
|
||||
## 需要重点查看的内容
|
||||
审阅者应该重点关注什么？
|
||||
|
||||
## 变更文件
|
||||
- `path/to/file1.md`
|
||||
- `path/to/file2.md`
|
||||
|
||||
## 测试
|
||||
你如何测试的？
|
||||
- [ ] 已在 Claude Code 本地测试
|
||||
- [ ] 已验证示例可用
|
||||
- [ ] 已检查链接和引用
|
||||
- [ ] 已检查拼写和清晰度
|
||||
|
||||
## 检查清单
|
||||
- [ ] 符合项目结构和规范
|
||||
- [ ] 包含清晰的文档 / 示例
|
||||
- [ ] 代码 / 示例可直接复制使用
|
||||
- [ ] 所有链接都已验证且可用
|
||||
- [ ] 没有包含敏感信息（密钥、token、凭证）
|
||||
- [ ] 已更新相关 README 文件
|
||||
- [ ] Commit 信息符合 conventional commit 格式
|
||||
- [ ] 没有添加大文件（>1MB）
|
||||
|
||||
## 截图或示例
|
||||
如有必要，展示这个 PR 增加的内容：
|
||||
```
|
||||
[示例代码或前后对比]
|
||||
```
|
||||
|
||||
## 破坏性变更
|
||||
这个变更是否影响现有内容或行为？
|
||||
- [ ] 没有破坏性变更
|
||||
- [ ] 是，并已在下方说明
|
||||
|
||||
如果有，请描述：
|
||||
|
||||
## 其他说明
|
||||
还有哪些信息需要审阅者了解？
|
||||
Reference in New Issue
Block a user