@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/skills/chinese-code-review/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: chinese-code-review
+description: 中文代码审查规范——在保持专业严谨的同时，用符合国内团队文化的方式给出有效反馈
+---
+
+# 中文代码审查规范
+
+## 概述
+
+国内团队做 Code Review 常遇到两个极端：要么过度客气导致关键问题被放过，要么照搬西方直白风格让同事下不来台。本技能帮你找到平衡点——**既不回避问题，又让人愿意接受反馈**。
+
+**核心原则：** 用"建议"代替"命令"，用"提问"代替"否定"，但绝不因为面子而放过 bug。
+
+## 审查反馈的表达方式
+
+### 用建议代替命令
+
+| 避免（命令式） | 推荐（建议式） |
+|---------------|---------------|
+| 你必须改成 X | 建议考虑用 X，因为 Y |
+| 这里写错了 | 这里可能存在一个问题，是否考虑过 Z 的情况？ |
+| 不要用这个方法 | 这个方法在 A 场景下可能有性能问题，可以看看 B 方案 |
+| 这段代码不行 | 这段逻辑我理解得对吗？如果输入为空的话会怎样？ |
+
+### 用提问代替否定
+
+当你不确定对方意图时，先问再评：
+
+```
+# 好的方式
+这里用 sync 方式读文件是出于什么考虑？如果并发量上来，可能会阻塞事件循环。
+
+# 不好的方式
+这里不应该用 sync 方式读文件。
+```
+
+### 分级标注
+
+统一使用优先级标记，让作者快速判断轻重缓急：
+
+- **[必须修复]** — 安全漏洞、数据丢失风险、逻辑错误（不修不能合）
+- **[建议修改]** — 性能问题、可维护性、缺少校验（本次或下次迭代修复）
+- **[仅供参考]** — 命名优化、风格建议、替代方案（不改也行）
+- **[问题]** — 不确定的地方，需要作者解释意图
+
+### 审查评论模板
+
+```
+[必须修复] SQL 注入风险
+
+第 42 行：用户输入直接拼接到 SQL 语句中。
+
+原因：攻击者可以通过 name 参数注入 `'; DROP TABLE users; --`。
+
+建议：使用参数化查询：
+  db.query('SELECT * FROM users WHERE name = $1', [name])
+
+参考：https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html
+```
+
+## 中英混排代码注释规范
+
+### 何时用中文
+
+- **业务逻辑说明** — 用中文解释业务背景和需求来源
+- **复杂算法注释** — 用中文写思路，确保团队成员都能理解
+- **TODO / FIXME** — 用中文描述待办事项，方便搜索和追踪
+- **文档注释（内部项目）** — JSDoc / Javadoc 中的描述文字用中文
+
+```typescript
+/**
+ * 计算用户的会员等级折扣
+ *
+ * 业务规则：
+ * - 普通会员 9.5 折
+ * - 银卡会员 9 折
+ * - 金卡会员 8.5 折
+ * - 钻石会员 8 折
+ *
+ * @param level - 会员等级（MemberLevel enum）
+ * @param amount - 原始金额（单位：分）
+ * @returns 折后金额（单位：分）
+ */
+function calculateDiscount(level: MemberLevel, amount: number): number {
+  // ...
+}
+```
+
+### 何时用英文
+
+- **变量名、函数名、类名** — 始终用英文命名，遵循团队命名规范
+- **Git commit message** — 参考下方 commit 规范
+- **开源项目注释** — 面向国际社区的项目，注释统一用英文
+- **错误信息和日志** — 生产环境的 error message 用英文（避免编码问题）
+- **API 接口文档** — 对外暴露的 API 用英文
+
+### 混排格式要求
+
+```typescript
+// 好：中英文之间加空格
+// 使用 Redis 缓存来减少 MySQL 的查询压力
+
+// 坏：中英文之间没有空格
+// 使用Redis缓存来减少MySQL的查询压力
+
+// 好：技术术语保留英文
+// 这里用 debounce 防抖处理，避免频繁触发 API 请求
+
+// 坏：强行翻译技术术语
+// 这里用防抖动处理，避免频繁触发应用程序接口请求
+```
+
+## Commit Message 中英双语格式
+
+### 推荐格式
+
+团队内部项目使用中文 commit message，采用约定式提交（Conventional Commits）的中文版：
+
+```
+<类型>(<范围>): <简要描述>
+
+<详细说明（可选）>
+
+<关联信息（可选）>
+```
+
+### 类型对照表
+
+| 类型 | 含义 | 示例 |
+|------|------|------|
+| feat | 新功能 | feat(用户): 新增手机号登录功能 |
+| fix | 修复 Bug | fix(支付): 修复微信支付回调重复处理的问题 |
+| docs | 文档变更 | docs: 更新 API 接口文档 |
+| style | 代码格式 | style: 统一缩进为 2 个空格 |
+| refactor | 重构 | refactor(订单): 拆分订单服务，提取公共逻辑 |
+| perf | 性能优化 | perf(列表): 虚拟滚动优化长列表渲染性能 |
+| test | 测试 | test(auth): 补充登录模块单元测试 |
+| chore | 构建/工具 | chore: 升级 Node.js 至 v20 |
+
+### 示例
+
+```
+fix(支付): 修复支付宝异步回调签名校验失败的问题
+
+原因：升级 SDK 后签名算法从 RSA 变为 RSA2，但回调校验仍使用旧算法。
+方案：回调处理中同时兼容 RSA 和 RSA2 签名校验。
+
+Closes #1234
+```
+
+### 面向国际社区的项目
+
+如果项目面向国际社区或有外籍成员，commit message 用英文，PR 描述中可附加中文说明：
+
+```
+fix(payment): fix Alipay async callback signature verification failure
+
+The SDK upgrade changed the signature algorithm from RSA to RSA2,
+but the callback handler still used the old algorithm.
+
+Closes #1234
+```
+
+## 常见反模式与对策
+
+### 反模式一：过度客气
+
+**表现：** 所有评论都是"我觉得可能也许大概好像这里有个小问题"。
+
+**后果：** 关键 bug 被隐藏在一堆委婉语里，作者根本不知道哪些必须改。
+
+**对策：** 使用分级标注。[必须修复] 就是必须修复，语气可以温和，但级别必须准确。
+
+```
+# 坏：过度客气
+不知道我理解得对不对，这里好像可能有一点点并发问题，不过也许我看错了...
+
+# 好：温和但清晰
+[必须修复] 并发安全问题
+
+这里的 map 在多个 goroutine 中同时读写，会触发 panic。
+建议加 sync.RWMutex，或者换成 sync.Map。
+
+复现方式：加 -race flag 跑测试就能看到。
+```
+
+### 反模式二：不敢给高级开发者提意见
+
+**表现：** 高级开发者或 Leader 的代码直接 Approve，不仔细看。
+
+**后果：** 代码质量双标，团队对 Code Review 失去信任。
+
+**对策：** Code Review 对事不对人。可以换个表达方式：
+
+```
+# 提问式（适合给资深同事的反馈）
+想请教一下，这里选择用递归而不是迭代，是出于什么考虑？
+我在想如果递归深度超过 1000 层会不会有栈溢出的风险？
+
+# 学习式
+学到了一个新写法！不过有个小疑问——这里的类型断言在运行时不会做检查，
+如果上游数据结构变了，这里会静默通过。是否考虑加个 runtime validation？
+```
+
+### 反模式三：审查变成风格之争
+
+**表现：** 大量评论纠结于缩进、空格、花括号位置。
+
+**后果：** 浪费时间，忽略真正的问题。
+
+**对策：** 风格问题交给 ESLint / Prettier / gofmt 等工具自动处理。Code Review 聚焦逻辑、安全、性能。
+
+### 反模式四：只写"LGTM"
+
+**表现：** 随手一个 LGTM 就 Approve，没有实质性审查。
+
+**后果：** Code Review 形同虚设，出了问题没人兜底。
+
+**对策：** 即使代码质量很好，也要写出你关注了哪些方面：
+
+```
+LGTM
+
+审查了以下方面：
+- 并发安全：锁的粒度合理
+- 错误处理：所有外部调用都有 error handling
+- 向下兼容：新增字段都有默认值，不影响老版本
+
+一个小建议 [仅供参考]：第 78 行的变量名 `d` 可以改成 `duration`，更易读。
+```
+
+## 审查流程建议
+
+### 开始审查前
+
+1. **先看 PR 描述**，理解改动的背景和目的
+2. **看关联的 Issue 或需求文档**
+3. **先整体浏览**，再逐文件细看
+
+### 审查顺序
+
+1. **架构层面** — 方案是否合理？有没有更好的方式？
+2. **正确性** — 逻辑对不对？边界条件处理了吗？
+3. **安全性** — 有没有注入、越权、信息泄露？
+4. **性能** — 有没有 N+1 查询、内存泄漏、不必要的循环？
+5. **可维护性** — 半年后能看懂吗？测试覆盖了吗？
+6. **风格** — 只关注工具无法自动处理的部分
+
+### 给出总结
+
+审查结束后，给一段总结，包括：
+- 整体评价（一句话）
+- 值得学习的地方（先扬后抑）
+- 主要问题列表（按优先级）
+- 建议的修改方向
+
+```
+总结：整体实现思路清晰，支付回调的幂等处理很到位。
+
+主要问题：
+1. [必须修复] 并发写 map 的问题（2 处）
+2. [建议修改] 缺少对空值的校验（3 处）
+3. [仅供参考] 几个变量命名可以更语义化
+
+建议先修复并发问题，校验的部分可以本次一起改或者拆到下个迭代。
+```
+
+## 检查清单
+
+在提交审查意见前，确认：
+
+- [ ] 每条评论都标注了优先级
+- [ ] [必须修复] 的问题都给出了具体的修复建议
+- [ ] 没有因为面子而跳过关键问题
+- [ ] 没有纠结于工具能自动处理的风格问题
+- [ ] 对好的代码给予了肯定
+- [ ] 给出了整体总结

package/plugins/superharness/skills/chinese-commit-conventions/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: chinese-commit-conventions
+description: 中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化
+---
+
+# 中文 Git 提交规范
+
+## 1. Conventional Commits 中文适配
+
+基于 Conventional Commits 1.0.0 规范，针对中文团队的实际使用习惯进行适配。
+
+### 类型（type）定义
+
+| 类型       | 说明                         | 示例场景                   |
+| ---------- | ---------------------------- | -------------------------- |
+| `feat`     | 新功能                       | 添加用户注册模块           |
+| `fix`      | 修复缺陷                     | 修复登录页白屏问题         |
+| `docs`     | 文档变更                     | 更新 API 接口文档          |
+| `style`    | 代码格式（不影响逻辑）       | 调整缩进、补充分号         |
+| `refactor` | 重构（非新功能、非修复）     | 拆分过长的服务类           |
+| `perf`     | 性能优化                     | 优化首页列表查询速度       |
+| `test`     | 测试相关                     | 补充用户模块单元测试       |
+| `chore`    | 构建/工具/依赖变更           | 升级 webpack 到 v5         |
+| `ci`       | 持续集成配置                 | 修改 GitHub Actions 流程   |
+| `revert`   | 回滚提交                     | 回滚 v2.1.0 的登录重构     |
+
+### 原则
+
+- type 保留英文关键字（工具链兼容性好）
+- scope 和 description 使用中文
+- body 使用中文完整描述
+
+## 2. 中文 commit message 模板
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 完整示例
+
+```
+feat(用户模块): 添加手机号一键登录功能
+
+- 接入运营商一键登录 SDK
+- 支持移动、联通、电信三网
+- 登录失败自动降级到短信验证码
+
+Closes #128
+```
+
+```
+fix(订单): 修复并发下单导致库存超卖的问题
+
+在高并发场景下，原有的库存扣减逻辑存在竞态条件。
+改用 Redis 分布式锁 + 数据库乐观锁双重保障。
+
+影响范围：订单服务、库存服务
+测试确认：已通过 500 并发压测验证
+
+Closes #256
+```
+
+## 3. Subject 行规范
+
+### 格式
+
+```
+<type>(<scope>): <description>
+```
+
+### 规则
+
+- **type**: 必填，从上方类型表中选取
+- **scope**: 选填，表示影响范围，使用中文模块名
+  - 示例：`用户模块`、`订单`、`支付`、`基础组件`
+- **description**: 必填，中文简述，不超过 50 个字符
+  - 使用动宾短语：「添加 xxx」「修复 xxx」「优化 xxx」
+  - 不加句号结尾
+  - 不要写「修改了代码」这种无意义描述
+
+### 好的示例
+
+```
+feat(权限): 添加基于 RBAC 的细粒度权限控制
+fix(支付): 修复微信支付回调签名验证失败的问题
+perf(列表页): 优化大数据量表格的虚拟滚动渲染
+refactor(网关): 将单体网关拆分为独立微服务
+```
+
+### 反面示例
+
+```
+# 以下写法应避免
+fix: 修了一个 bug
+feat: 更新代码
+chore: 改了点东西
+```
+
+## 4. Body 编写规范
+
+Body 用于详细说明本次变更的动机、方案和影响。
+
+### 编写要点
+
+- 说明**为什么**要做这个改动（背景/原因）
+- 说明**怎么做**的（技术方案摘要）
+- 说明**影响范围**（哪些模块、接口受影响）
+- 每行不超过 72 个字符（中文约 36 个汉字）
+- 正文与标题之间空一行
+
+### Body 模板
+
+```
+<改动背景和原因>
+
+技术方案：
+- <方案要点 1>
+- <方案要点 2>
+
+影响范围：<受影响的模块或服务>
+```
+
+## 5. Breaking Changes 标注
+
+当提交包含不兼容变更时，必须在 footer 中标注。
+
+### 格式一：footer 标注
+
+```
+feat(接口): 重构用户信息返回结构
+
+将用户接口返回的扁平结构改为嵌套结构，前端需同步调整字段取值路径。
+
+BREAKING CHANGE: /api/user/info 返回结构变更
+- avatar 字段移入 profile 对象
+- 移除已废弃的 nickname 字段，统一使用 displayName
+```
+
+### 格式二：type 后加感叹号
+
+```
+feat(接口)!: 重构用户信息返回结构
+```
+
+### 团队约定
+
+- 涉及数据库表结构变更 -> 必须标注 BREAKING CHANGE
+- 涉及公共 API 参数/返回值变更 -> 必须标注
+- 涉及配置文件格式变更 -> 必须标注
+- 标注时须写明迁移方法或升级步骤
+
+## 6. Issue 关联
+
+### GitHub 格式
+
+```
+Closes #128
+Refs #129, #130
+```
+
+### Gitee 格式
+
+```
+Closes #I5ABC1
+相关需求: https://gitee.com/org/repo/issues/I5ABC1
+```
+
+### Coding 格式
+
+```
+关联 Coding 缺陷 #12345
+fixed=project-2024/issues/678
+```
+
+### 通用写法
+
+```
+# footer 中关联多个平台
+Closes #128
+Jira: PROJ-456
+禅道: #789
+```
+
+## 7. Changelog 自动生成配置
+
+### 安装 conventional-changelog
+
+```bash
+npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits
+```
+
+### package.json 脚本
+
+```json
+{
+  "scripts": {
+    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
+    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s -r 0",
+    "release": "standard-version"
+  }
+}
+```
+
+### .versionrc.js 中文配置
+
+```javascript
+module.exports = {
+  types: [
+    { type: 'feat', section: '新功能' },
+    { type: 'fix', section: '缺陷修复' },
+    { type: 'perf', section: '性能优化' },
+    { type: 'refactor', section: '代码重构' },
+    { type: 'docs', section: '文档更新' },
+    { type: 'test', section: '测试' },
+    { type: 'chore', section: '构建/工具', hidden: true },
+    { type: 'ci', section: '持续集成', hidden: true },
+    { type: 'style', section: '代码格式', hidden: true }
+  ],
+  commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
+  compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'
+}
+```
+
+## 8. commitlint 中文配置
+
+### 安装
+
+```bash
+npm install -D @commitlint/cli @commitlint/config-conventional
+```
+
+### commitlint.config.js
+
+```javascript
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [2, 'always', [
+      'feat', 'fix', 'docs', 'style', 'refactor',
+      'perf', 'test', 'chore', 'ci', 'revert'
+    ]],
+    'type-case': [2, 'always', 'lower-case'],
+    'type-empty': [2, 'never'],
+    'subject-empty': [2, 'never'],
+    'subject-max-length': [2, 'always', 100],
+    // 允许中文字符，关闭 subject-case 限制
+    'subject-case': [0],
+    // 关闭 header-max-length 或放宽（中文占宽较大）
+    'header-max-length': [2, 'always', 120],
+    'body-max-line-length': [1, 'always', 200],
+    'footer-max-line-length': [1, 'always', 200]
+  },
+  prompt: {
+    messages: {
+      type: '选择提交类型:',
+      scope: '输入影响范围（可选）:',
+      subject: '填写简短描述:',
+      body: '填写详细描述（可选，使用 "|" 换行）:',
+      breaking: '列出不兼容变更（可选）:',
+      footer: '关联的 Issue（可选，例如 #123）:',
+      confirmCommit: '确认提交以上信息？'
+    }
+  }
+}
+```
+
+## 9. husky + lint-staged 集成
+
+### 安装与初始化
+
+```bash
+npm install -D husky lint-staged
+npx husky init
+```
+
+### 配置 commit-msg 钩子
+
+```bash
+# .husky/commit-msg
+npx --no -- commitlint --edit "$1"
+```
+
+### 配置 pre-commit 钩子
+
+```bash
+# .husky/pre-commit
+npx lint-staged
+```
+
+### lint-staged 配置（package.json）
+
+```json
+{
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,vue}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,scss,less}": [
+      "stylelint --fix",
+      "prettier --write"
+    ],
+    "*.md": [
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### 交互式提交（可选）
+
+```bash
+npm install -D commitizen cz-conventional-changelog
+
+# package.json 中添加
+{
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "scripts": {
+    "commit": "cz"
+  }
+}
+```
+
+运行 `npm run commit` 即可进入交互式提交引导。
+
+## 10. 团队规范检查清单
+
+### 提交前自查
+
+- [ ] type 是否正确选择（feat/fix/docs/...）
+- [ ] scope 是否准确描述了影响模块
+- [ ] subject 是否为动宾短语且不超过 50 字符
+- [ ] subject 末尾是否去掉了句号
+- [ ] body 是否说明了变更原因和方案
+- [ ] 不兼容变更是否标注了 BREAKING CHANGE
+- [ ] 相关 Issue 是否已关联
+- [ ] 一次提交是否只做了一件事（原子性）
+
+### 团队落地步骤
+
+1. **工具链配置**：按上述步骤配置 commitlint + husky，让规范可执行
+2. **模板共享**：将 `.commitlintrc`、`.husky/` 等配置提交到仓库
+3. **团队培训**：组织 15 分钟的规范说明会，演示工具使用
+4. **Code Review**：Review 时关注 commit message 质量
+5. **持续迭代**：每季度回顾规范执行情况，根据团队反馈调整
+
+### 常见问题
+
+**Q: 中英文混排时空格怎么处理？**
+A: 中文与英文/数字之间加一个空格，如「添加 Redis 缓存」。
+
+**Q: scope 用中文还是英文？**
+A: 团队内统一即可。推荐中文（可读性好），但需在 commitlint 中关闭 scope-case 检查。
+
+**Q: 多人协作时如何保证规范一致？**
+A: 靠工具而非靠自觉。配置好 husky + commitlint，不符合规范的提交会被拦截。