221 lines
7.5 KiB
Markdown
221 lines
7.5 KiB
Markdown
# Contributing to The Agency
|
||
|
||
## Source File
|
||
- [[raw/Agent/agency-agents/CONTRIBUTING.md]]
|
||
|
||
## Overview
|
||
|
||
The Agency 是一个开源 AI Agent 精选集合，其 CONTRIBUTING.md 定义了完整的贡献指南体系，涵盖行为准则、贡献方式、Agent 设计规范、PR 流程和写作风格指南。
|
||
|
||
## Code of Conduct
|
||
|
||
项目遵守明确的行为准则：
|
||
- **Be Respectful**：尊重每个人，鼓励健康辩论，拒绝人身攻击
|
||
- **Be Inclusive**：欢迎并支持各种背景和身份的人
|
||
- **Be Collaborative**：协作创造优于独自创作
|
||
- **Be Professional**：保持讨论聚焦于改进 agents 和社区
|
||
|
||
## How to Contribute
|
||
|
||
### 1. 创建新 Agent
|
||
|
||
贡献者在选择合适分类后，按模板创建 Agent 文件：
|
||
- `engineering/` — 软件开发专家
|
||
- `design/` — UX/UI 和创意专家
|
||
- `finance/` — 财务规划和投资专家
|
||
- `game-development/` — 游戏设计与开发专家
|
||
- `marketing/` — 增长和营销专家
|
||
- `paid-media/` — 付费获客专家
|
||
- `product/` — 产品管理专家
|
||
- `project-management/` — PM 和协调专家
|
||
- `testing/` — QA 和测试专家
|
||
- `support/` — 运营和支持专家
|
||
- `spatial-computing/` — AR/VR/XR 专家
|
||
- `specialized/` — 不属于以上分类的专家
|
||
|
||
### 2. 改进现有 Agent
|
||
|
||
贡献方向包括：
|
||
- 添加真实案例和使用场景
|
||
- 用现代模式增强代码示例
|
||
- 基于最新最佳实践更新工作流
|
||
- 添加成功指标和基准
|
||
- 修复错字、改善清晰度、增强文档
|
||
|
||
### 3. 分享成功案例
|
||
|
||
通过 GitHub Discussions、案例研究、博客文章和视频教程分享。
|
||
|
||
### 4. 报告问题
|
||
|
||
提供清晰的复现步骤、使用场景上下文和建议的解决方案。
|
||
|
||
## Agent Design Guidelines
|
||
|
||
### Agent 文件结构
|
||
|
||
Agent 文件遵循 YAML frontmatter + Markdown 内容的两段式结构：
|
||
|
||
#### YAML Frontmatter
|
||
```yaml
|
||
---
|
||
name: Agent Name
|
||
description: One-line description
|
||
color: colorname or "#hexcode"
|
||
emoji: 🎯
|
||
vibe: One-line personality hook
|
||
services: # optional — only if the agent requires external services
|
||
- name: Service Name
|
||
url: https://service-url.com
|
||
tier: free # free, freemium, or paid
|
||
---
|
||
```
|
||
|
||
#### Content Sections
|
||
|
||
文档定义了 Agent 文件的两大语义分组：
|
||
|
||
**Persona（Agent 的身份）**：
|
||
- Identity & Memory — 角色、个性、背景
|
||
- Communication Style — 语气、声音、方式
|
||
- Critical Rules — 边界和约束
|
||
|
||
**Operations（Agent 的行为）**：
|
||
- Core Mission — 主要职责
|
||
- Technical Deliverables — 具体输出和模板
|
||
- Workflow Process — 分步方法论
|
||
- Success Metrics — 可衡量成果
|
||
- Advanced Capabilities — 专业化技术
|
||
|
||
#### 结构原则
|
||
|
||
不需要特殊格式——只需将 persona 相关部分（身份、沟通、规则）与操作部分（使命、交付物、工作流、指标）分开。`convert.sh` 脚本使用这些章节标题自动将 agents 拆分为工具特定格式。
|
||
|
||
### Agent Design Principles
|
||
|
||
1. **Strong Personality**：赋予 agent 独特的声音和个性，而非泛泛的"helpful assistant"
|
||
2. **Clear Deliverables**：提供具体代码示例、模板和框架，展示真实输出
|
||
3. **Success Metrics**：包含具体、可衡量的指标（如"3G 网络下页面加载 < 3 秒"）
|
||
4. **Proven Workflows**：分步流程，经过真实场景测试
|
||
5. **Learning Memory**：agent 识别的模式和随时间的改进方式
|
||
|
||
### External Services
|
||
|
||
Agent 依赖外部服务时的设计原则：
|
||
1. 在 frontmatter 的 `services` 字段中声明依赖
|
||
2. Agent 必须独立自主——移除 API 调用后仍应有有用的 persona、工作流和专业知识
|
||
3. 不复制供应商文档——引用而非再现
|
||
4. 优先选择有免费层级的服务
|
||
|
||
关键测试：*这个 agent 是为用户服务的，还是为供应商服务的？*
|
||
|
||
### Qwen Code Compatibility
|
||
|
||
Agent body 支持 `${variable}` 模板语法以实现动态上下文（如 `${project_name}`、`${task_description}`）。Qwen SubAgents 使用最小化 frontmatter：仅需要 `name` 和 `description`；`color`、`emoji` 和 `version` 字段被省略。
|
||
|
||
### What Makes a Great Agent
|
||
|
||
**Great agents have**：
|
||
- ✅ 狭窄而深入的专业化
|
||
- ✅ 独特的个性和声音
|
||
- ✅ 具体的代码/模板示例
|
||
- ✅ 可衡量的成功指标
|
||
- ✅ 分步工作流
|
||
- ✅ 真实场景测试和迭代
|
||
|
||
**Avoid**：
|
||
- ❌ 泛化的"helpful assistant"个性
|
||
- ❌ 模糊的"我将帮助你..."描述
|
||
- ❌ 无代码示例或交付物
|
||
- ❌ 过于宽泛的范围（什么都做等于什么都没做）
|
||
- ❌ 未经测试的理论方法
|
||
|
||
## Pull Request Process
|
||
|
||
### PR 边界管理
|
||
|
||
最佳路径是一个 markdown 文件（一个新或改进的 agent），这是最理想的情况。
|
||
|
||
**始终欢迎作为 PR**：
|
||
- 添加新 agent（一个 `.md` 文件）
|
||
- 改进现有 agent 的内容、示例或个性
|
||
- 修复错字或澄清文档
|
||
|
||
**先开 Discussion**：
|
||
- 新工具、构建系统或 CI 工作流
|
||
- 架构变更（新目录、新脚本、网站生成器）
|
||
- 跨多文件变更
|
||
- 新集成格式或平台
|
||
|
||
**始终关闭的内容**：
|
||
- 已提交构建输出（`_site/`、编译资产、转换后的 agent 文件）
|
||
- 批量修改现有 agents 而未先讨论的 PR
|
||
|
||
### Before Submitting
|
||
|
||
1. **Test Your Agent**：在真实场景中使用并迭代反馈
|
||
2. **Follow the Template**：匹配现有 agents 的结构
|
||
3. **Add Examples**：至少包含 2-3 个代码/模板示例
|
||
4. **Define Metrics**：包含具体、可衡量的成功标准
|
||
5. **Proofread**：检查错字、格式问题和清晰度
|
||
|
||
### PR Review Process
|
||
|
||
1. **Community Review**：其他贡献者提供反馈
|
||
2. **Iteration**：响应反馈并进行改进
|
||
3. **Approval**：维护者批准后合并
|
||
4. **Merge**：贡献成为 The Agency 的一部分
|
||
|
||
## Style Guide
|
||
|
||
### Writing Style
|
||
|
||
- **Be specific**："Reduce page load by 60%" 而非 "Make it faster"
|
||
- **Be concrete**："Create React components with TypeScript" 而非 "Build UIs"
|
||
- **Be memorable**：赋予 agents 个性，而非泛化的企业用语
|
||
- **Be practical**：包含真实代码，而非伪代码
|
||
|
||
### Formatting
|
||
|
||
- 一致使用 **Markdown formatting**
|
||
- 章节标题使用 **emojis**（便于扫描）
|
||
- 所有代码示例使用 **code blocks** 并标注语法高亮
|
||
- 使用 **tables** 对比选项或展示指标
|
||
- 使用 **bold** 强调，`code` 标注技术术语
|
||
|
||
### Tone
|
||
|
||
- **Professional but approachable**：不过于正式或随意
|
||
- **Confident but not arrogant**："Here's the best approach" 而非"Maybe you could try..."
|
||
- **Helpful but not hand-holding**：假设能力，提供深度
|
||
- **Personality-driven**：每个 agent 应有独特声音
|
||
|
||
## Recognition
|
||
|
||
重要贡献者将被：
|
||
- 列在 README 致谢部分
|
||
- 在发布说明中突出
|
||
- 在"本周最佳 Agent"展示中亮相（如适用）
|
||
- 在 agent 文件本身中获得荣誉
|
||
|
||
## Questions & Resources
|
||
|
||
- **General Questions**: GitHub Discussions
|
||
- **Bug Reports**: GitHub Issues
|
||
- **Feature Requests**: GitHub Issues
|
||
- **Community Chat**: Join discussions
|
||
|
||
### For New Contributors
|
||
|
||
- README.md — 总览和 agent 目录
|
||
- engineering-frontend-developer.md — 结构良好的 agent 示例
|
||
- marketing-reddit-community-builder.md — 个性出色的示例
|
||
- design-whimsy-injector.md — 创意专家示例
|
||
|
||
## Related
|
||
|
||
- [[The Agency]] — 项目主实体
|
||
- [[agency-agents]] — GitHub 仓库实体
|
||
- [[agency-agents-examples]] — Examples 页面
|
||
- [[agency-agents-integrations]] — 集成文档
|