Sync: add agent design notes

2026-04-24 21:06:05 +08:00
parent e677a87510
commit 4b6b2f970c
8 changed files with 888 additions and 4 deletions
--- a/wiki/concepts/Agent-Design-Principles.md
+++ b/wiki/concepts/Agent-Design-Principles.md
@@ -0,0 +1,50 @@
+---
+title: "Agent Design Principles"
+type: concept
+tags: [multi-agent, agent-design, the-agency]
+sources: [contributing_zh-cn, contributing-to-the-agency]
+last_updated: 2026-04-24
+---
+
+# Agent Design Principles
+
+The five core design principles for building high-quality AI agents in The Agency framework.
+
+## Five Principles
+
+### 1. 🎭 Distinct Personality
+- Give each agent a unique tone and persona
+- Avoid generic "I am a helpful assistant" — be specific and memorable
+- Example: "I will find 3-5 problems by default and ask for visual evidence" (Evidence Collector)
+
+### 2. 📋 Clear Deliverables
+- Provide actionable code examples
+- Include templates and frameworks
+- Show real output, not vague descriptions
+
+### 3. ✅ Success Metrics
+- Include specific, quantifiable metrics
+- Example: "Page load time under 3 seconds on 3G network"
+- Example: "10,000+ combined karma points across accounts"
+
+### 4. 🔄 Verified Workflows
+- Step-by-step processes that are clear
+- Validated in real-world scenarios
+- Reject pure theory without testing
+
+### 5. 💡 Learning & Memory
+- Agents identify which patterns to recognize
+- How they iterate and optimize over time
+- What they remember between sessions
+
+## Anti-Patterns (Avoid)
+- ❌ Generic "helpful assistant" persona
+- ❌ Vague "I will help you..." descriptions
+- ❌ No code examples or deliverables
+- ❌ Too broad scope (jack of all trades)
+- ❌ Untested theoretical solutions
+
+## Connections
+- Extends [[Multi-Agent-System-Reliability]] — design-time quality standards complement runtime reliability patterns
+- Used by [[Multi-Agent-Team]] — standardized agent creation framework
+- Related to [[Agent-Template]] — the structural template implementing these principles
--- a/wiki/concepts/Agent-Template.md
+++ b/wiki/concepts/Agent-Template.md
@@ -0,0 +1,77 @@
+---
+title: "Agent Template"
+type: concept
+tags: [multi-agent, agent-design, the-agency]
+sources: [contributing_zh-cn, contributing-to-the-agency]
+last_updated: 2026-04-24
+---
+
+# Agent Template
+
+The standardized YAML frontmatter + structured document template for creating The Agency agents.
+
+## YAML Frontmatter
+
+```yaml
+---
+name: Agent Name
+description: One-sentence description of agent's specialty and positioning
+color: Color Name or "#hex-value"
+---
+```
+
+## Document Structure
+
+### 🧠 Identity & Memory
+- **Role**: Clear role description
+- **Personality**: Personality traits and communication style
+- **Memory**: What the agent needs to remember and learn
+- **Experience**: Domain expertise and perspective
+
+### 🎯 Core Mission
+- Core Responsibility 1 (with clear deliverables)
+- Core Responsibility 2 (with clear deliverables)
+- Core Responsibility 3 (with clear deliverables)
+- **Default Requirement**: Always follow best practices
+
+### 🚨 Critical Rules
+Domain-specific rules and constraints that define how the agent operates.
+
+### 📋 Technical Deliverables
+Concrete outputs the agent produces:
+- Code examples
+- Templates
+- Frameworks
+- Documentation
+
+### 🔄 Workflow
+Step-by-step process the agent follows:
+1. Phase 1: Exploration & Research
+2. Phase 2: Planning & Strategy
+3. Phase 3: Execution & Implementation
+4. Phase 4: Review & Optimization
+
+### 💭 Communication Style
+- How the agent communicates
+- Example phrases and expression patterns
+- Tone and style
+
+### 🔄 Learning & Memory
+What the agent continuously learns from:
+- Success patterns
+- Failure cases
+- User feedback
+- Domain evolution
+
+### 🎯 Success Metrics
+Quantifiable outcomes:
+- Quantitative metrics (with specific values)
+- Qualitative metrics
+- Performance benchmarks
+
+### 🚀 Advanced Capabilities
+Advanced techniques and methods the agent masters.
+
+## Connections
+- Implements [[Agent-Design-Principles]] — structural template for the five design principles
+- Used in [[Multi-Agent-Team]] — standardized agent creation
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -4,6 +4,9 @@
 - [Overview](overview.md) — living synthesis

 ## Sources
+- [2026-04-24] [Contributing to The Agency](sources/contributing.md)
+- [2026-04-24] [为 The Agency 贡献代码](sources/contributing_zh-cn.md)
+- [2026-04-24] [CTP Topic 12 Using SES SMTP service terraform module](sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md)
 - [2026-04-24] [Learning Sessions Cloud Transformation Programme-Deploying RDS via Terraform](sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md)
 - [2026-04-24] [Learning Sessions Cloud Transformation Programme-20230808 183322-Meeting Recording](sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md)
 - [2026-04-24] [CTP Topic 16 Cross-account Terraform modules](sources/ctp-topic-16-cross-account-terraform-modules.md)
@@ -295,7 +298,6 @@
 - [2026-04-21] [What I Know About Cloud Service Delivery 1](sources/what-i-know-about-cloud-service-delivery-1.md)
 - [2026-04-21] [Cloud DevOp Maturity - Guideline](sources/cloud-devop-maturity-guideline.md)
 - [2026-04-21] [DevOps Culture and Transformation: Fostering Collaboration, Agile Practices, and Innovation](sources/devops-culture-and-transformation-fostering-collaboration-agile-practices-and-innovation-linkedin.md)
- [2026-04-21] [contributing](sources/contributing.md) — (expected: wiki/sources/contributing.md — source missing)
 - [2026-04-21] [marketing-weibo-strategist](sources/marketing-weibo-strategist.md) — (expected: wiki/sources/marketing-weibo-strategist.md — source missing)
 - [2026-04-21] [marketing-baidu-seo-specialist](sources/marketing-baidu-seo-specialist.md) — (expected: wiki/sources/marketing-baidu-seo-specialist.md — source missing)
 - [2026-04-21] [marketing-carousel-growth-engine](sources/marketing-carousel-growth-engine.md) — (expected: wiki/sources/marketing-carousel-growth-engine.md — source missing)
@@ -412,8 +414,6 @@
 - [2026-04-20] [design-ux-researcher](sources/design-ux-researcher.md) — (expected: wiki/sources/design-ux-researcher.md — source missing)
 - [2026-04-20] [design-whimsy-injector](sources/design-whimsy-injector.md) — (expected: wiki/sources/design-whimsy-injector.md — source missing)
 - [2026-04-20] [design-ux-architect](sources/design-ux-architect.md) — (expected: wiki/sources/design-ux-architect.md — source missing)
- [2026-04-20] [contributing_zh-cn](sources/contributing_zh-cn.md) — (expected: wiki/sources/contributing_zh-cn.md — source missing)
- [2026-04-14] [CTP Topic 12 Using SES SMTP service terraform module](sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md) — Micro Focus 团队通过 Terraform 模块自动化部署 AWS SES SMTP 服务以替代本地 SMTP 网关；Christian + Filos 主讲；VPC 端点私有连接 + IAM/Secrets Manager 凭证管理
 - [Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog](sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md) — (expected: wiki/sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md — source missing)
 - [Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend](sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md) — (expected: wiki/sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md — source missing)
 - [zk-steward](sources/zk-steward.md) — (expected: wiki/sources/zk-steward.md — source missing)
@@ -774,12 +774,14 @@
 - [Adaptive-Tone](concepts/Adaptive-Tone.md)
 - [Adversarial-Debate-Pattern](concepts/Adversarial-Debate-Pattern.md)
 - [Agent-Build-Gate](concepts/Agent-Build-Gate.md)
+- [Agent-Design-Principles](concepts/Agent-Design-Principles.md)
 - [Agent-Driven-Market-Research](concepts/Agent-Driven-Market-Research.md)
 - [Agent-Memory](concepts/Agent-Memory.md)
 - [Agent-Mode](concepts/Agent-Mode.md)
 - [Agent-Personality](concepts/Agent-Personality.md)
 - [Agent-Routing-Rules](concepts/Agent-Routing-Rules.md)
 - [Agent-Specialization](concepts/Agent-Specialization.md)
+- [Agent-Template](concepts/Agent-Template.md)
 - [AGENTS.md](concepts/AGENTS.md.md)
 - [Agile-Ceremonies](concepts/Agile-Ceremonies.md)
 - [AgilePractices](concepts/AgilePractices.md)
@@ -1125,7 +1127,6 @@
 - [Secrets-Management](concepts/Secrets-Management.md)
 - [Security-and-Compliance](concepts/Security-and-Compliance.md)
 - [Self-Education](concepts/Self-Education.md)
- [SES-Sandbox-Mode](concepts/SES-Sandbox-Mode.md)
 - [Self-Healing-Systems](concepts/Self-Healing-Systems.md)
 - [self-hosted-password-manager](concepts/self-hosted-password-manager.md)
 - [Self-Improving-Skill](concepts/Self-Improving-Skill.md)
@@ -1138,6 +1139,7 @@
 - [Sequential-Thinking](concepts/Sequential-Thinking.md)
 - [Serverless-Computing](concepts/Serverless-Computing.md)
 - [Service-Control-Policies-SCPs](concepts/Service-Control-Policies-SCPs.md)
+- [SES-Sandbox-Mode](concepts/SES-Sandbox-Mode.md)
 - [Shared-Memory-Architecture](concepts/Shared-Memory-Architecture.md)
 - [Shared-Responsibility-Model](concepts/Shared-Responsibility-Model.md)
 - [SharedStateCoordination](concepts/SharedStateCoordination.md)
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -1,3 +1,33 @@
+## [2026-05-05] ingest | Contributing to The Agency
+- Source file: Agent/agency-agents/CONTRIBUTING.md
+- Status: ✅ 成功摄入
+- Summary: The Agency 多智能体框架贡献者指南英文原版——涵盖 Code of Conduct、四大贡献方式（创建智能体/优化现有/分享案例/报告问题）、智能体设计模板（YAML frontmatter + 结构化文档）、五大设计原则（鲜明性格/明确交付物/可量化指标/验证工作流/学习记忆）、PR 流程规范（单文件优先/Discussion 前置/提交前检查）、代码风格指南。
+- Concepts linked: [[Agent-Design-Principles]], [[Agent-Template]], [[Multi-Agent-Team]], [[Multi-Agent-System-Reliability]]
+- Entities linked: [[The Agency]], [[OpenClaw]], [[msitarzewski]]
+- Source page: wiki/sources/contributing.md
+- Notes: index.md 已替换占位符条目；overview.md 已更新 contributing_zh-cn 条目，补充英文原版 wikilink；无新 Entity 需创建（msitarzewski/The Agency 仅出现 1 次，不足建页阈值）；无实质内容冲突，与 contributing_zh-cn 差异属语言版本差异
+
+## [2026-05-05] ingest | 为 The Agency 贡献代码
+- Source file: Agent/agency-agents/CONTRIBUTING_zh-CN.md
+- Status: ✅ 成功摄入
+- Summary: The Agency 项目（agency-agents）贡献者指南，定义智能体设计规范、贡献流程和社区标准。核心贡献方式：创建全新智能体（8大分类）、优化现有智能体、分享成功案例、反馈问题。智能体设计五原则：鲜明性格、明确交付物、可量化指标、经过验证的工作流、学习记忆。PR 流程含提交前检查（真实场景测试、遵循模板、补充示例）、社区评审与迭代优化。
+- Concepts created: [[Agent-Design-Principles]], [[Agent-Template]]
+- Entities created: none（The Agency 已在 Wiki 中存在引用，无需新建 Entity 页面）
+- Concepts linked: [[Multi-Agent-System-Reliability]], [[Multi-Agent-Team]]
+- Source page: wiki/sources/contributing_zh-cn.md
+- Notes: index.md 已新增 Sources 条目；overview.md 已新增独立段落（Multi-Agent AI Systems 主题下，置于 multi-channel-assistant 之前）；Agent-Design-Principles 和 Agent-Template 为新创建 Concept 页面；无 Entity 需创建；无冲突内容
+
+## [2026-05-05] ingest | CTP Topic 12 Using SES SMTP service terraform module
+- Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/ctp-topic-12-using-ses-smtp-service-terraform-module.md
+- Status: ✅ 成功摄入
+- Summary: Christian Deckelmann 和 Filos Christolakis 主讲，Micro Focus 团队通过 Terraform 模块自动化部署 AWS SES SMTP 服务以替代传统本地 SMTP 网关——SES 是网络安全部门唯一批准的云端邮件发送方案；Terraform 模块封装 SMTP 终端节点配置，支持现有应用程序通过标准 SMTP 协议集成；VPC 端点私有连接 + IAM 用户凭证转 SMTP 认证信息存储于 Secrets Manager；自动化 DKIM 验证和 Infoblox DNS 记录创建；两个手动步骤（脱离 Sandbox Mode + 手动更新 DNS TXT 记录）；未来计划收件人限制和凭证滚动更新。
+- Concepts created: [[VPC-Endpoint]], [[DKIM-Email-Authentication]], [[SES-Sandbox-Mode]]
+- Entities created: none（Christian Deckelmann、Filos Christolakis、Infoblox 出现频次不足建页阈值，以 wikilink 形式记录于 Source page）
+- Concepts linked: [[Infrastructure-as-Code]], [[Secrets-Management]]
+- Source page: wiki/sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md
+- Notes: index.md 已替换占位符条目（日期 2026-04-14）；overview.md 已新增独立段落（Terraform 段落末尾，置于 RDS via Terraform 和 Topic 21 之间）；VPC-Endpoint/DKIM-Email-Authentication/SES-Sandbox-Mode 为新创建 Concept 页面；Secrets-Management 已存在，已建立 wikilink；无其他 Entity 需创建
+- Conflicts: 与 [[ctp-topic-36-sendgrid-as-an-email-service]] 在邮件服务选型上的差异——SendGrid 被选定为新标准云邮件服务，SES 则服务现有应用通过 SMTP 协议平滑迁移上云，两者互补而非互斥
+
 ## [2026-05-05] ingest | Learning Sessions Cloud Transformation Programme-20230808 183322-Meeting Recording
 - Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md
 - Status: ✅ 成功摄入
--- a/wiki/overview.md
+++ b/wiki/overview.md
@@ -7,6 +7,8 @@ This wiki is a living synthesis of curated sources spanning AI agents, cloud inf
 ### Multi-Agent AI Systems
 The wiki covers two major multi-agent frameworks: **The Agency** (agency-agents) and **OpenClaw**. The Agency provides 147 specialized agents across 12 business divisions (Engineering, Design, Finance, Game Dev, Marketing, Paid Media, Product, Project Management, Testing, Support, Spatial Computing, Specialized). OpenClaw focuses on autonomous agents with persistent memory and workflow orchestration via n8n.

+**The Agency 贡献指南**（[[contributing_zh-cn]] + [[contributing]] 英文原版）：The Agency 项目贡献者指南——核心贡献方式：①创建全新智能体（8大分类：engineering/design/marketing/product/project-management/testing/support/spatial-computing/specialized）；②优化现有智能体；③分享成功案例；④反馈问题。智能体设计五原则：**鲜明性格**（拒绝通用人设）、**明确交付物**（真实代码/模板）、**可量化指标**、**经过验证的工作流**、**学习记忆机制**。PR 流程包含提交前检查（真实场景测试、遵循模板、补充示例）、社区评审与迭代优化。属 [[Multi-Agent-System-Reliability]] 的智能体设计规范层，为 [[Multi-Agent-Team]] 提供标准化的智能体创建框架。
+
 **[[multi-channel-assistant]]**：基于 [[OpenClaw]] 的多渠道个人助理方案——以 Telegram Topic 路由为统一入口，整合 Google Workspace（gog）、Slack、Todoist、Asana，实现"说一句话完成全套工作"。核心价值：消除应用切换疲劳，AI 主动推送定时提醒（如每周垃圾清理、公司周报）。

 **[[phone-based-personal-assistant]]**：通过 ClawdTalk + Telnyx 将任意手机变成 AI 助理语音入口——拨打电话即可与 [[OpenClaw]] 对话，支持日历查询、Jira 任务更新、网络搜索等技能，无需智能手机 App 或浏览器，覆盖驾驶、步行等双手占用场景。与 [[multi-channel-assistant]] 互补：文字入口覆盖图文交互，语音入口覆盖无屏场景。
--- a/wiki/sources/contributing.md
+++ b/wiki/sources/contributing.md
@@ -0,0 +1,47 @@
+---
+title: "Contributing to The Agency"
+type: source
+tags: [multi-agent, openclaw, contribution, the-agency]
+date: 2026-04-21
+---
+
+## Source File
+- [[Agent/agency-agents/CONTRIBUTING.md]]
+
+## Summary（用中文描述）
+- 核心主题：The Agency（agency-agents）多智能体框架的贡献者指南英文原版
+- 问题域：如何规范地向 The Agency 项目贡献高质量 AI 智能体，以及社区协作标准
+- 方法/机制：通过智能体设计模板、五大设计原则、PR 流程规范和代码风格指南确保贡献质量
+- 结论/价值：为 OpenClaw 多智能体生态提供标准化的智能体创建框架和质量门槛
+
+## Key Claims（用中文描述）
+- The Agency 通过**五大设计原则**确保智能体质量：鲜明性格、明确交付物、可量化指标、经过验证的工作流、学习记忆
+- PR 最佳实践：**单文件优先**（一个 `.md` 就是一个 PR），复杂变更（工具链/架构）需先开 Discussion 对齐
+- 外部服务依赖须在 frontmatter 的 `services` 字段声明，且智能体应**脱离 API 后仍有独立价值**
+- 提交前必须完成：真实场景测试、遵循模板、至少 2-3 个代码/模板示例、可量化成功指标
+
+## Key Quotes
+> "The fastest path to a merged PR is **one markdown file** — a new or improved agent. That's the sweet spot." — PR 流程说明
+> "An agent that solves the user's problem using a service belongs here. A service's quickstart guide wearing an agent costume does not." — 外部服务评判标准
+
+## Key Concepts
+- [[Agent-Design-Principles]]：五大设计原则——鲜明性格/明确交付物/可量化指标/验证工作流/学习记忆
+- [[Agent-Template]]：YAML frontmatter + 结构化文档模板规范
+- [[Multi-Agent-Team]]：The Agency 框架下多智能体协作模式
+- [[Multi-Agent-System-Reliability]]：多智能体系统可靠性架构模式
+
+## Key Entities
+- [[The Agency]]：msitarzewski 主导的多智能体开源项目（147 个专业化智能体，覆盖 12 个业务领域）
+- [[OpenClaw]]：The Agency 智能体运行的基础平台
+- [[msitarzewski]]（mar.mod）：The Agency 项目维护者
+
+## Connections
+- [[contributing_zh-cn]] ← 同一文档的中文翻译版本，包含中文社区协作规范
+- [[Agent-Design-Principles]] ← 来源一致，均引用本文档定义五大设计原则
+- [[Agent-Template]] ← 来源一致，均引用本文档定义智能体文件结构
+- [[multi-agent-system-reliability]] ← 智能体设计规范层补充运行时可靠性模式
+- [[multi-agent-team]] ← The Agency 框架的多智能体协作模式
+
+## Contradictions
+- 无与其他 Wiki 页面的实质性内容冲突
+- 与 [[contributing_zh-cn]] 的差异：英文原版包含 Code of Conduct（行为准则）和 Recognition（贡献者认可机制）章节，中文翻译版侧重核心贡献流程和设计规范
--- a/wiki/sources/contributing_zh-cn.md
+++ b/wiki/sources/contributing_zh-cn.md
@@ -0,0 +1,44 @@
+---
+title: "为 The Agency 贡献代码"
+type: source
+tags: []
+date: 2026-04-24
+---
+
+## Source File
+- [[Agent/agency-agents/CONTRIBUTING_zh-CN.md]]
+
+## Summary（用中文描述）
+- 核心主题：**The Agency**（agency-agents）项目的贡献者指南，定义智能体（Agent）设计规范、贡献流程和社区标准
+- 问题域：AI 智能体系统的标准化设计、社区协作与质量保障
+- 方法/机制：YAML frontmatter 元数据 + 分层结构化文档模板；通过 Pull Request 流程和 PR 模板实现质量把控；通过智能体设计原则（性格塑造、交付物定义、指标量化）确保智能体质量
+- 结论/价值：提供可操作的智能体设计框架，降低社区贡献门槛，同时通过规范保证生态一致性
+
+## Key Claims（用中文描述）
+- 优秀智能体必须具备鲜明性格，拒绝"通用型有用助手"人设
+- 智能体应提供可量化的成功指标，而非模糊描述
+- 每个智能体必须经过真实场景测试和迭代优化
+- 贡献者通过 PR 流程和社区评审确保智能体质量
+
+## Key Quotes
+> "赋予智能体独特语气与人设，避免'我是一个有用的助手'，要具体、让人印象深刻" — 智能体性格设计原则
+> "提供可落地的代码示例，包含模板与框架，展示真实输出，而非模糊描述" — 交付物标准
+> "包含具体、可量化的指标" — 成功指标要求
+
+## Key Concepts
+- [[Agent-Design-Principles]]：The Agency 智能体设计五原则（鲜明性格、明确交付物、成功指标、经过验证的工作流、学习记忆）
+- [[Agent-Template]]：YAML frontmatter + 分层结构（身份/使命/规则/交付物/工作流/沟通/学习/指标）
+- [[Pull-Request-Template]]：标准化 PR 提交模板，包含智能体信息、创作动机、测试情况、检查清单
+
+## Key Entities
+- [[The-Agency]]（agency-agents 项目）：包含 147 个专业智能体，覆盖 12 个业务领域
+- [[Agency-Engineering-Agent]]：前端开发者智能体示例，结构规范参考
+- [[Agency-Marketing-reddit-Community-Builder]]：Reddit 社区运营者示例，性格塑造优秀参考
+
+## Connections
+- [[Multi-Agent-System-Reliability]] ← extends ← [[Agent-Design-Principles]]
+- [[OpenClaw]] ← related_to ← [[The-Agency]]
+- [[Multi-Agent-Team]] ← related_to ← [[Agent-Orchestration]]
+
+## Contradictions
+- 无已知冲突内容