Update CONTRIBUTING_zh-CN.md

Updated Chinese translation.
2026-03-08 20:43:59 +08:00
parent 7343f607b6
commit a8aef6d3e3
1 changed files with 276 additions and 112 deletions
--- a/CONTRIBUTING_zh-CN.md
+++ b/CONTRIBUTING_zh-CN.md
@@ -1,154 +1,318 @@
+# 🤝 为 The Agency 贡献代码
+首先，非常感谢你愿意为 The Agency 贡献力量！正是有像你这样的参与者，才能让这套 AI 智能体集合变得越来越好。

-# 贡献指南：为 The Agency 做出贡献
-
-首先，感谢你考虑为 The Agency 做出贡献！正是因为有像你这样的人，才让这套 AI 智能体（Agents）集变得更好。
-
-📋 **目录**
-
-* [行为准则](https://www.google.com/search?q=%23%E8%A1%8C%E4%B8%BA%E5%87%86%E5%88%99)
-* [我能如何贡献？](https://www.google.com/search?q=%23%E6%88%91%E8%83%BD%E5%A6%82%E4%BD%95%E8%B4%A1%E7%8C%AE)
-* [智能体设计规范](https://www.google.com/search?q=%23%E6%99%BA%E8%83%BD%E4%BD%93%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83)
-* [Pull Request (PR) 流程](https://www.google.com/search?q=%23pull-request-%E6%B5%81%E7%A8%8B)
-* [风格指南](https://www.google.com/search?q=%23%E9%A3%8E%E6%A0%BC%E6%8C%87%E5%8D%97)
-* [社区](https://www.google.com/search?q=%23%E7%A4%BE%E5%8C%BA)
+## 📋 **目录**
+- [行为准则](#📜-行为准则)
+- [我能如何贡献？](#🎯-我能如何贡献)
+- [智能体设计规范](#🎨-智能体设计规范)
+- [Pull Request (PR) 流程](#🔄-pull-request-流程)
+- [风格指南](#📐-风格指南)
+- [社区](#🤔-疑问)

 ---

 ## 📜 行为准则
+本项目及所有参与者均受《行为准则》约束。参与即代表你同意遵守以下准则：

-本项目及所有参与者均受我们的行为准则约束。参与时，请遵守以下准则：
-
-* **保持尊重**：尊重每一个人。鼓励健康的辩论，但绝不容忍人身攻击。
-* **包容性**：欢迎并支持各种背景和身份的人。
-* **协作精神**：我们共同创造的东西比独自创造的更好。
-* **保持专业**：让讨论聚焦于提升智能体和社区。
+- **保持尊重**：友善对待每一个人。鼓励理性讨论，但严禁人身攻击。
+- **包容多元**：欢迎并支持来自不同背景、不同身份的参与者。
+- **乐于协作**：我们共同创造的成果，远胜于单打独斗。
+- **专业严谨**：讨论请聚焦于优化智能体与建设社区。

 ---

-## 🎯 我能如何贡献？
+## 🎯 如何贡献？

-### 1. 创建新智能体 (Create a New Agent)
+### 1. 创建全新智能体
+有专属智能体的创意？太棒了！按以下步骤添加：

-有特定领域智能体的创意吗？太棒了！添加方法如下：
+1. Fork 本仓库
+2. 选择合适的分类（或提议新增分类）：
+   - `engineering/` —— 软件开发专家
+   - `design/` —— UX/UI 与创意设计专家
+   - `marketing/` —— 增长与营销专家
+   - `product/` —— 产品管理专家
+   - `project-management/` —— 项目管理与协调专家
+   - `testing/` —— 质量保证与测试专家
+   - `support/` —— 运营与支持专家
+   - `spatial-computing/` —— AR/VR/XR 专家
+   - `specialized/` —— 无法归入其他分类的独特专家
+3. 按照下方模板创建智能体文件
+4. 在真实场景中测试你的智能体
+5. 提交 Pull Request（拉取请求）

-1. **Fork 本仓库**。
-2. **选择合适的类别**（或提议新类别）：
-* `engineering/` - 软件开发专家
-* `design/` - UI/UI 及创意专家
-* `marketing/` - 增长与营销专家
-* `product/` - 产品管理专家
-* `project-management/` - 项目管理与协调专家
-* `testing/` - QA 与测试专家
-* `support/` - 运营与支持专家
-* `spatial-computing/` - AR/VR/XR 专家
-* `specialized/` - 无法归类到其他地方的独特专家
+### 2. 优化现有智能体
+找到优化现有智能体的方法？非常欢迎贡献：
+- 补充真实案例与使用场景
+- 用现代模式完善代码示例
+- 基于最新最佳实践更新工作流
+- 增加成功指标与基准
+- 修正错别字、提升清晰度、完善文档

+### 3. 分享成功案例
+如果你成功使用了这些智能体：
+- 在 [GitHub Discussions](https://github.com/msitarzewski/agency-agents/discussions) 发布心得
+- 在 README 中补充案例研究
+- 撰写博客文章并附上链接
+- 制作视频教程

-3. **按照下方模板**创建你的智能体文件。
-4. **在真实场景中测试**你的智能体。
-5. **提交 Pull Request (PR)**。
-
-### 2. 改进现有智能体
-
-* 添加真实世界的示例和用例。
-* 使用现代模式优化代码示例。
-* 根据新的最佳实践更新工作流。
-* 添加成功指标（Success Metrics）和基准。
-* 修复错别字、提升清晰度、完善文档。
-
-### 3. 分享成功故事
-
-在 GitHub Discussions 中发布心得，或在 README 中添加案例研究。
-
-### 4. 报告问题 (Issue)
-
-发现问题了吗？请告诉我们：提供清晰的复现步骤，并附带你的使用背景。
+### 4. 反馈问题
+发现问题？请告诉我们：
+- 先检查是否已有相同 issue
+- 提供清晰的复现步骤
+- 说明你的使用场景与上下文
+- 如有思路，可以提出潜在解决方案

 ---

-## 🎨 智能体设计规范
+# 🎨 智能体设计规范

-每个智能体文件都应遵循以下结构：
+### 智能体文件结构
+每个智能体都应遵循以下结构：

-```markdown
+```yaml
 ---
 name: 智能体名称
-description: 一句话描述该智能体的专长和重点
-color: 颜色名称或 "#十六进制代码"
+description: 一句话描述该智能体的专长与定位
+color: 颜色名 或 "#十六进制色值"
 ---
-
-# 智能体名称
-
-## 🧠 身份与记忆
- **角色 (Role)**: 清晰的角色描述。
- **性格 (Personality)**: 性格特征与沟通风格。
- **记忆 (Memory)**: 智能体需要记住和学习的内容。
- **经验 (Experience)**: 领域专业知识与视角。
-
-## 🎯 核心使命
- 具有明确产出物的核心职责 1、2、3。
- **默认要求**: 始终开启的最佳实践。
-
-## 🚨 必须遵守的硬性规则
-定义智能体方法的领域特定规则和约束。
-
-## 📋 技术产出物 (Technical Deliverables)
-智能体产出的具体示例：代码示例、模板、框架、文档。
-
-## 🔄 工作流流程 (Workflow Process)
-1. 第一阶段：探索与研究
-2. 第二阶段：规划与策略
-3. 第三阶段：执行与实现
-4. 第四阶段：复盘与优化
-
-## 💭 沟通风格
-语气、常用短语模式等。
-
-## 🎯 成功指标 (Success Metrics)
-* 量化指标（带数字）
-* 定性指标
-* 性能基准
-
 ```

+## 智能体名称
+
+### 🧠 身份与记忆
+- **角色**：清晰的角色描述
+- **性格**：性格特点与沟通风格
+- **记忆**：智能体需要记住与学习的内容
+- **经验**：领域专业能力与视角
+
+### 🎯 核心使命
+- 核心职责 1（含明确交付物）
+- 核心职责 2（含明确交付物）
+- 核心职责 3（含明确交付物）
+- **默认要求**：始终遵循最佳实践
+
+### 🚨 必须遵守的关键规则
+领域专属规则与约束，定义智能体的工作方式。
+
+### 📋 技术交付物
+智能体实际产出的具体内容：
+- 代码示例
+- 模板
+- 框架
+- 文档
+
+### 🔄 工作流程
+智能体遵循的分步流程：
+1. 阶段 1：探索与调研
+2. 阶段 2：规划与策略
+3. 阶段 3：执行与落地
+4. 阶段 4：评审与优化
+
+### 💭 沟通风格
+- 智能体如何沟通
+- 示例话术与表达模式
+- 语气与风格
+
+### 🔄 学习与记忆
+智能体从以下内容中持续学习：
+- 成功模式
+- 失败案例
+- 用户反馈
+- 领域演进
+
+### 🎯 成功指标
+可量化的成果：
+- 量化指标（带具体数值）
+- 质性指标
+- 性能基准
+
+### 🚀 高级能力
+该智能体掌握的高级技巧与方法。
+
 ---

-## 🔄 Pull Request (PR) 流程
+## 智能体设计原则
+ 1. 🎭 **鲜明性格**
+- 赋予智能体独特语气与人设
+- 避免“我是一个有用的助手”，要具体、让人印象深刻
+- 示例：“我默认会找出 3–5 个问题，并要求提供视觉证据”（证据收集专家）
+
+ 2. 📋 **明确交付物**
+- 提供可落地的代码示例
+- 包含模板与框架
+- 展示真实输出，而非模糊描述
+
+ 3. ✅ **成功指标**
+- 包含具体、可量化的指标
+- 示例：“3G 网络下页面加载时间低于 3 秒”
+- 示例：“全账号合计 karma 积分 10,000+”
+
+ 4. 🔄 **经过验证的工作流**
+- 分步流程清晰
+- 经过真实场景验证
+- 拒绝纯理论、纸上谈兵
+
+ 5. 💡 **学习记忆**
+- 智能体能识别哪些模式
+- 如何随时间迭代优化
+- 会话之间会记住什么
+
+### 优秀智能体的标准
+ - ✅ 专精、深入的领域定位
+ - ✅ 独特性格与语气
+ - ✅ 具体的代码/模板示例
+ - ✅ 可量化的成功指标
+ - ✅ 分步工作流
+ - ✅ 真实场景测试与迭代
+
+**避免：**
+ - ❌ 通用型“有用助手”人设
+ - ❌ 模糊的“我会帮你……”描述
+ - ❌ 无代码示例、无交付物
+ - ❌ 范围过宽（样样通样样松）
+ - ❌ 未经测试的理论方案
+
+---
+
+## 🔄 拉取请求（PR）流程

 ### 提交前
+- **测试智能体**：在真实场景使用，根据反馈迭代
+- **遵循模板**：与现有智能体结构保持一致
+- **补充示例**：至少包含 2–3 个代码/模板示例
+- **定义指标**：包含具体、可量化的成功标准
+- **校对检查**：检查错别字、格式、清晰度

-* **测试你的智能体**：在真实场景中使用，并根据反馈进行迭代。
-* **遵循模板**：与现有智能体的结构保持一致。
-* **添加示例**：包含至少 2-3 个代码/模板示例。
-* **校对**：检查错别字、格式问题和清晰度。
+### 提交 PR
+1. Fork 仓库
+2. 创建分支：
+   ```bash
+   git checkout -b add-agent-name
+   ```
+3. 完成修改：添加智能体文件
+4. 提交：
+   ```bash
+   git commit -m "Add [智能体名称] specialist"
+   ```
+5. 推送：
+   ```bash
+   git push origin add-agent-name
+   ```
+6. 发起 Pull Request，包含：
+   - 清晰标题：`Add [智能体名称] - [分类]`
+   - 智能体功能描述
+   - 该智能体的必要性（使用场景）
+   - 已做的测试

-### 提交 PR 步骤
+### PR 审核流程
+- **社区评审**：其他贡献者可提供反馈
+- **迭代优化**：根据反馈修改完善
+- **通过审核**：维护者确认无误后通过
+- **合并上线**：你的贡献正式加入 The Agency！

-1. **Fork** 仓库。
-2. **创建分支**：`git checkout -b add-agent-name`。
-3. **提交更改**：`git commit -m "Add [Agent Name] specialist"`。
-4. **推送**：`git push origin add-agent-name`。
-5. **开启 PR**：标题清晰（如 "Add [Name] - [Category]"），并描述其用途和测试情况。
+### PR 模板
+```markdown
+## 智能体信息
+**智能体名称**：[名称]
+**分类**：[engineering/design/marketing 等]
+**专长**：一句话描述
+
+## 创作动机
+[为什么需要这个智能体？解决了什么空白？]
+
+## 测试情况
+[你如何测试该智能体？有哪些真实场景？]
+
+## 检查清单
+- [ ] 遵循智能体模板结构
+- [ ] 包含性格与语气
+- [ ] 有具体代码/模板示例
+- [ ] 定义成功指标
+- [ ] 包含分步工作流
+- [ ] 已校对并正确格式化
+- [ ] 在真实场景测试过
+```

 ---

 ## 📐 风格指南

-* **具体化**：写“减少 60% 加载时间”，而不是“加快速度”。
-* **务实**：包含真实可用的代码，而不是伪代码。
-* **格式化**：始终使用 Markdown；章节标题加入 Emoji 方便扫描；代码示例使用代码块。
+### 写作风格
+- **具体明确**：写“页面加载速度降低 60%”，而非“让它更快”
+- **落地务实**：写“用 TypeScript 编写 React 组件”，而非“做界面”
+- **让人记住**：给智能体赋予性格，避免通用官话
+- **实用可用**：提供真实代码，而非伪代码
+
+### 格式规范
+- 统一使用 Markdown 格式
+- 章节标题使用表情符号 🎯🧠📋 方便快速浏览
+- 所有代码示例使用代码块并开启语法高亮
+- 用表格对比选项或展示指标
+- 用**粗体**强调重点，用 `` `代码` `` 表示技术术语
+
+### 代码示例
+```typescript
+// 务必包含：
+// 1. 语言标注以支持语法高亮
+// 2. 关键逻辑注释
+// 3. 真实可运行代码（非伪代码）
+// 4. 现代最佳实践
+
+interface AgentExample {
+  name: string;
+  specialty: string;
+  deliverables: string[];
+}
+```
+
+### 语气
+- 专业且亲和：不过于正式，也不过于随意
+- 自信不自大：用“这是最佳方案”，而非“或许你可以试试……”
+- 有助但不包办：默认用户具备基础能力，提供深度内容
+- 性格鲜明：每个智能体都有独特语气

 ---

-## 🌟 荣誉榜
-
-做出重大贡献的参与者将：
-
-* 列入 README 的致谢名单。
-* 在发布说明（Release Notes）中被重点介绍。
-* 有机会在“本周智能体”中展示。
+## 🌟 贡献表彰
+做出重要贡献的参与者将获得：
+- 在 README 致谢区署名
+- 在版本发布说明中重点提及
+- 入选“每周智能体”展示（如适用）
+- 在智能体文件中标注作者信息

 ---

-🎉 **谢谢你！**
-无论你是添加新智能体、修复 Bug 还是分享故事，你都在让 The Agency 变得更好。谢谢！
+## 🤔 有疑问？
+- 常规问题：[GitHub Discussions](https://github.com/msitarzewski/agency-agents/discussions)
+- Bug 反馈：[GitHub Issues](https://github.com/msitarzewski/agency-agents/issues)
+- 功能需求：[GitHub Issues](https://github.com/msitarzewski/agency-agents/issues)
+- 社区交流：参与 [Discussions](https://github.com/msitarzewski/agency-agents/discussions)
+
+---
+
+## 📚 资源
+
+### 新贡献者指南
+- [README.md](https://github.com/DawnnnHuang/agency-agents/blob/add-chinese-translation/README.md) —— 项目概览与智能体目录
+- [示例：前端开发者](https://github.com/DawnnnHuang/agency-agents/blob/add-chinese-translation/engineering/engineering-frontend-developer.md) —— 结构规范的智能体示例
+- [示例：Reddit 社区运营者](https://github.com/DawnnnHuang/agency-agents/blob/add-chinese-translation/marketing/marketing-reddit-community-builder.md) —— 性格塑造优秀示例
+- [示例：趣味注入器](https://github.com/DawnnnHuang/agency-agents/blob/add-chinese-translation/design/design-whimsy-injector.md) —— 创意型专家示例
+
+### 智能体设计参考
+- 阅读现有智能体获取灵感
+- 学习已验证的有效模式
+- 在真实场景测试你的智能体
+- 根据反馈持续迭代
+
+---
+
+## 🎉 再次感谢！
+你的每一份贡献都在让 The Agency 变得更好。无论你是：
+- 新增智能体
+- 完善文档
+- 修复错误
+- 分享成功案例
+- 帮助其他贡献者
+
+你都在创造真实价值。感谢你！