agency-agents/CONTRIBUTING_zh-CN.md

# 🤝 为 The Agency 贡献代码
首先，非常感谢你愿意为 The Agency 贡献力量！正是有像你这样的参与者，才能让这套 AI 智能体集合变得越来越好。

## 📋 **目录**
- [行为准则](#📜-行为准则)
- [我能如何贡献？](#🎯-我能如何贡献)
- [智能体设计规范](#🎨-智能体设计规范)
- [Pull Request (PR) 流程](#🔄-pull-request-流程)
- [风格指南](#📐-风格指南)
- [社区](#🤔-疑问)

---

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

- **保持尊重**：友善对待每一个人。鼓励理性讨论，但严禁人身攻击。
- **包容多元**：欢迎并支持来自不同背景、不同身份的参与者。
- **乐于协作**：我们共同创造的成果，远胜于单打独斗。
- **专业严谨**：讨论请聚焦于优化智能体与建设社区。

---

## 🎯 如何贡献？

### 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（拉取请求）

### 2. 优化现有智能体
找到优化现有智能体的方法？非常欢迎贡献：
- 补充真实案例与使用场景
- 用现代模式完善代码示例
- 基于最新最佳实践更新工作流
- 增加成功指标与基准
- 修正错别字、提升清晰度、完善文档

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

### 4. 反馈问题
发现问题？请告诉我们：
- 先检查是否已有相同 issue
- 提供清晰的复现步骤
- 说明你的使用场景与上下文
- 如有思路，可以提出潜在解决方案

---

# 🎨 智能体设计规范

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

```yaml
---
name: 智能体名称
description: 一句话描述该智能体的专长与定位
color: 颜色名 或 "#十六进制色值"
---
```

## 智能体名称

### 🧠 身份与记忆
- **角色**：清晰的角色描述
- **性格**：性格特点与沟通风格
- **记忆**：智能体需要记住与学习的内容
- **经验**：领域专业能力与视角

### 🎯 核心使命
- 核心职责 1（含明确交付物）
- 核心职责 2（含明确交付物）
- 核心职责 3（含明确交付物）
- **默认要求**：始终遵循最佳实践

### 🚨 必须遵守的关键规则
领域专属规则与约束，定义智能体的工作方式。

### 📋 技术交付物
智能体实际产出的具体内容：
- 代码示例
- 模板
- 框架
- 文档

### 🔄 工作流程
智能体遵循的分步流程：
1. 阶段 1：探索与调研
2. 阶段 2：规划与策略
3. 阶段 3：执行与落地
4. 阶段 4：评审与优化

### 💭 沟通风格
- 智能体如何沟通
- 示例话术与表达模式
- 语气与风格

### 🔄 学习与记忆
智能体从以下内容中持续学习：
- 成功模式
- 失败案例
- 用户反馈
- 领域演进

### 🎯 成功指标
可量化的成果：
- 量化指标（带具体数值）
- 质性指标
- 性能基准

### 🚀 高级能力
该智能体掌握的高级技巧与方法。

---

## 智能体设计原则
 1. 🎭 **鲜明性格**
- 赋予智能体独特语气与人设
- 避免“我是一个有用的助手”，要具体、让人印象深刻
- 示例：“我默认会找出 3–5 个问题，并要求提供视觉证据”（证据收集专家）

 2. 📋 **明确交付物**
- 提供可落地的代码示例
- 包含模板与框架
- 展示真实输出，而非模糊描述

 3. ✅ **成功指标**
- 包含具体、可量化的指标
- 示例：“3G 网络下页面加载时间低于 3 秒”
- 示例：“全账号合计 karma 积分 10,000+”

 4. 🔄 **经过验证的工作流**
- 分步流程清晰
- 经过真实场景验证
- 拒绝纯理论、纸上谈兵

 5. 💡 **学习记忆**
- 智能体能识别哪些模式
- 如何随时间迭代优化
- 会话之间会记住什么

### 优秀智能体的标准
 - ✅ 专精、深入的领域定位
 - ✅ 独特性格与语气
 - ✅ 具体的代码/模板示例
 - ✅ 可量化的成功指标
 - ✅ 分步工作流
 - ✅ 真实场景测试与迭代

**避免：**
 - ❌ 通用型“有用助手”人设
 - ❌ 模糊的“我会帮你……”描述
 - ❌ 无代码示例、无交付物
 - ❌ 范围过宽（样样通样样松）
 - ❌ 未经测试的理论方案

---

## 🔄 拉取请求（PR）流程

### 提交前
- **测试智能体**：在真实场景使用，根据反馈迭代
- **遵循模板**：与现有智能体结构保持一致
- **补充示例**：至少包含 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 审核流程
- **社区评审**：其他贡献者可提供反馈
- **迭代优化**：根据反馈修改完善
- **通过审核**：维护者确认无误后通过
- **合并上线**：你的贡献正式加入 The Agency！

### PR 模板
```markdown
## 智能体信息
**智能体名称**：[名称]
**分类**：[engineering/design/marketing 等]
**专长**：一句话描述

## 创作动机
[为什么需要这个智能体？解决了什么空白？]

## 测试情况
[你如何测试该智能体？有哪些真实场景？]

## 检查清单
- [ ] 遵循智能体模板结构
- [ ] 包含性格与语气
- [ ] 有具体代码/模板示例
- [ ] 定义成功指标
- [ ] 包含分步工作流
- [ ] 已校对并正确格式化
- [ ] 在真实场景测试过
```

---

## 📐 风格指南

### 写作风格
- **具体明确**：写“页面加载速度降低 60%”，而非“让它更快”
- **落地务实**：写“用 TypeScript 编写 React 组件”，而非“做界面”
- **让人记住**：给智能体赋予性格，避免通用官话
- **实用可用**：提供真实代码，而非伪代码

### 格式规范
- 统一使用 Markdown 格式
- 章节标题使用表情符号 🎯🧠📋 方便快速浏览
- 所有代码示例使用代码块并开启语法高亮
- 用表格对比选项或展示指标
- 用**粗体**强调重点，用 `` `代码` `` 表示技术术语

### 代码示例
```typescript
// 务必包含：
// 1. 语言标注以支持语法高亮
// 2. 关键逻辑注释
// 3. 真实可运行代码（非伪代码）
// 4. 现代最佳实践

interface AgentExample {
  name: string;
  specialty: string;
  deliverables: string[];
}
```

### 语气
- 专业且亲和：不过于正式，也不过于随意
- 自信不自大：用“这是最佳方案”，而非“或许你可以试试……”
- 有助但不包办：默认用户具备基础能力，提供深度内容
- 性格鲜明：每个智能体都有独特语气

---

## 🌟 贡献表彰
做出重要贡献的参与者将获得：
- 在 README 致谢区署名
- 在版本发布说明中重点提及
- 入选“每周智能体”展示（如适用）
- 在智能体文件中标注作者信息

---

## 🤔 有疑问？
- 常规问题：[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/msitarzewski/agency-agents/blob/main/README.md) —— 项目概览与智能体目录
- [示例：前端开发者](https://github.com/msitarzewski/agency-agents/blob/main/engineering/engineering-frontend-developer.md ) —— 结构规范的智能体示例
- [示例：Reddit 社区运营者](https://github.com/msitarzewski/agency-agents/blob/main/marketing/marketing-reddit-community-builder.md) —— 性格塑造优秀示例
- [示例：趣味注入器](https://github.com/msitarzewski/agency-agents/blob/main/design/design-whimsy-injector.md) —— 创意型专家示例

### 智能体设计参考
- 阅读现有智能体获取灵感
- 学习已验证的有效模式
- 在真实场景测试你的智能体
- 根据反馈持续迭代

---

## 🎉 再次感谢！
你的每一份贡献都在让 The Agency 变得更好。无论你是：
- 新增智能体
- 完善文档
- 修复错误
- 分享成功案例
- 帮助其他贡献者

你都在创造真实价值。感谢你！