agency-agents/CONTRIBUTING_zh-CN.md

🤝 为 The Agency 贡献代码

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

📋 目录

• 行为准则
• 我能如何贡献？
• 智能体设计规范
• Pull Request (PR) 流程
• 风格指南
• 社区

---

📜 行为准则

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

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

---

🎯 如何贡献？

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 发布心得
• 在 README 中补充案例研究
• 撰写博客文章并附上链接
• 制作视频教程

4. 反馈问题

发现问题？请告诉我们：

• 先检查是否已有相同 issue
• 提供清晰的复现步骤
• 说明你的使用场景与上下文
• 如有思路，可以提出潜在解决方案

---

🎨 智能体设计规范

智能体文件结构

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

---
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. 创建分支：

   git checkout -b add-agent-name
   

3. 完成修改：添加智能体文件
4. 提交：

   git commit -m "Add [智能体名称] specialist"
   

5. 推送：

   git push origin add-agent-name
   

6. 发起 Pull Request，包含：
   • 清晰标题：Add [智能体名称] - [分类]
   • 智能体功能描述
   • 该智能体的必要性（使用场景）
   • 已做的测试

PR 审核流程

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

PR 模板

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

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

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

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

---

📐 风格指南

写作风格

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

格式规范

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

代码示例

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

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

语气

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

---

🌟 贡献表彰

做出重要贡献的参与者将获得：

• 在 README 致谢区署名
• 在版本发布说明中重点提及
• 入选“每周智能体”展示（如适用）
• 在智能体文件中标注作者信息

---

🤔 有疑问？

• 常规问题：GitHub Discussions
• Bug 反馈：GitHub Issues
• 功能需求：GitHub Issues
• 社区交流：参与 Discussions

---

📚 资源

新贡献者指南

• README.md —— 项目概览与智能体目录
• 示例：前端开发者 —— 结构规范的智能体示例
• 示例：Reddit 社区运营者 —— 性格塑造优秀示例
• 示例：趣味注入器 —— 创意型专家示例

智能体设计参考

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

---

🎉 再次感谢！

你的每一份贡献都在让 The Agency 变得更好。无论你是：

• 新增智能体
• 完善文档
• 修复错误
• 分享成功案例
• 帮助其他贡献者

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