diff --git a/AGENT_MARKET_TEMPLATES_SPEC.md b/AGENT_MARKET_TEMPLATES_SPEC.md new file mode 100644 index 000000000..15df8642d --- /dev/null +++ b/AGENT_MARKET_TEMPLATES_SPEC.md @@ -0,0 +1,511 @@ +# Agent Market 模板设计评审文档 + +**状态:** 草稿,待评审 +**作者:** cinderzhan + AI 助手 +**最后更新:** 2026-04-24 +**范围:** 将 clawith 内置 `AgentTemplate` 模板从 4 个扩展到 15 个,按三个面向用户的场景组织:软件开发、社媒增长、综合私人助理。 + +--- + +## 0. 概念预备 + +### 0.1 什么是 clawith runtime + +在 clawith 里,一个 agent 不是一段 prompt,而是一个**长期存在的数字员工**。它的"身体"由以下组件构成(合起来称为 runtime): + +| 组件 | 角色 | +|------|------| +| `soul.md` | 身份、人格、规则 | +| `state.json` | 当前状态(在干啥、忙不忙) | +| `workspace/` | 工作台(任务计划、中间草稿、产出物) | +| `memory/` | 跨对话的长期记忆(知识沉淀、踩过的坑) | +| `skills/` | 可调用的能力包 | +| `HEARTBEAT.md` | 心跳机制,让 agent 周期性自主醒来 | +| DB 里的 AgentTool / AgentPermission | 工具绑定、权限策略 | + +**与普通 prompt 库的区别**:普通 prompt 用完一次就消失;clawith agent 对话结束不消失,会继续定期醒来、积累记忆、把产物沉淀到工作区。模板设计必须利用这套基础设施,否则 agent 就退化成一次性 prompt。 + +### 0.2 架构决策:soul 走方案 A(最小扩展),bootstrap 走两轮仪式 + +经过对"是否新增 6 个 section"的再评估(外部素材仓库那套 10 段结构是为无状态 prompt 设计的,clawith 有 skill/heartbeat/memory 提供的 runtime 支撑,大部分新 section 是冗余),最终选择**方案 A**: + +**Soul:保持和现有 4 模板一致的 4 段结构**(Identity / Personality / Work Style / Boundaries),只在 Work Style 里加 3 条必选 bullet,覆盖 clawith runtime 的关键使用方式: + +1. workspace 用法:何时把计划/草稿/交付物写到 `workspace//` +2. memory 用法:什么值得沉淀到 `memory/.md` +3. heartbeat 方向:心跳醒来时关注什么(一行,不单开 section) + +长度:比现有 4 模板多 5-8 行,风格完全一致,不需要升级老模板。 + +**Bootstrap:对齐主分支(`yutong/agent-templates`)的两轮仪式模型**,`bootstrap_content` 是一段系统提示词(不是文件),由 `onboarding.py` 在首位用户打开该 agent 聊天时注入: + +- Turn 0(user_turns == 0):打招呼 + 2-3 条能力要点 + 问 1 个紧扣角色的问题 +- Turn 1+(user_turns >= 1):直接按用户回答开始产出,不再追问上下文 + +详见 §3.2 新 bootstrap 模板。 + +--- + +## 1. 目标 + +让 Agent Market 开箱即用——在现有 4 个模板(PM / Designer / Product Intern / Market Researcher)基础上新增 11 个高频、全球通用的模板。 + +每一个模板必须是**完整配置好的数字员工**,不是一段 system prompt——也就是说要附带 soul、首轮仪式(bootstrap)、能力要点(capability bullets)、skill 预装、自主权限策略(autonomy policy)、以及语言感知的沟通规则。**所有模板从零原创**,只从行业常识里借鉴角色命名和典型交付物维度,不复制任何外部仓库的表达。这样做有三个好处: + +1. **没有协议负担** —— 不欠任何第三方署名 +2. **runtime 适配** —— 可以把 clawith 独有的 heartbeat、memory、skill、workspace 机制直接织进 soul,而不是事后外挂 +3. **voice 一致** —— 和现有 Morty / Meeseeks 保持同一种"同事感"的人设语气 + +--- + +## 2. 范围 + +### 2.1 分类方案(3 个大类,覆盖全部 15 个模板) + +所有模板(新 11 + 老 4)统一到 3 个面向用户的分类: + +| category | 中文标签 | 定位 | +|----------|----------|------| +| `software-development` | 软件开发 | 写代码、审代码、部署、设计、产品 | +| `marketing` | 营销 | 增长、内容、投放、市场研究 | +| `office` | 办公通用 | 项目管理、个人助理 | + +### 2.2 新增 11 个模板 + +| # | 模板 | 分类 | 代号 | 主要交付物 | +|---|------|------|------|------------| +| 1 | **Frontend Developer** | software-development | FE | React/Vue 组件、性能报告、无障碍审计 | +| 2 | **Backend Architect** | software-development | BE | API 设计、数据库 Schema、扩展性方案 | +| 3 | **Code Reviewer** | software-development | CR | 结构化的 PR 审查报告 | +| 4 | **DevOps Automator** | software-development | OPS | CI/CD 流水线、IaC 配置、运维手册 | +| 5 | **Rapid Prototyper** | software-development | RP | MVP、POC、可运行 demo | +| 6 | **Growth Hacker** | marketing | GH | 实验方案、漏斗分析、增长循环设计 | +| 7 | **Content Creator** | marketing | CC | 多平台编辑日历、文案、Newsletter | +| 8 | **SEO Specialist** | marketing | SEO | 关键词规划、技术 SEO 审计、内容 brief | +| 9 | **TikTok Strategist** | marketing | TT | 短视频选题、算法敏感的发布计划 | +| 10 | **LinkedIn Content Creator** | marketing | LI | 个人品牌帖子、B2B 思想领导力长文 | +| 11 | **Chief of Staff** | office | CoS | 每日简报、OKR 追踪、会议纪要、跟进清单 | + +> 这 11 个名字是业界通用角色名,不构成对任何具体仓库的借鉴。**代号使用 2-3 字母的文字标识**,严禁使用 emoji(沿用现有 PM / DS / PI / MR 的惯例)。 + +### 2.3 现有 4 个模板的重新分类 + +现有模板原本使用 `management` / `design` / `product` / `research` 作为 category,本次统一到 3 个大类。DB 里只需要更新 `agent_templates.category` 字段(由 seeder 执行 upsert 时自然覆盖,无需单独迁移)。 + +| 模板 | 原 category | 新 category | 理由 | +|------|-------------|-------------|------| +| PM (Project Manager) | management | `office` | 项目管理是跨场景通用能力 | +| Designer | design | `software-development` | 现有 soul 定位于 UI/产品设计,服务软件开发 | +| Product Intern | product | `software-development` | 服务于产品经理的需求分析,属软件团队 | +| Market Researcher | research | `marketing` | 市场研究天然归属营销场景 | + +最终分类分布(总 15 个): +- `software-development` (7):FE、BE、CR、OPS、RP、Designer、Product Intern +- `marketing` (6):GH、CC、SEO、TT、LI、Market Researcher +- `office` (2):CoS、PM + +### 2.4 非目标 + +- 本次默认**复用现有 skill**;确实不够用时,从公开 skill 库(如 Anthropic Skills 等)下载补充(见 §5.1) +- 本次**不**新增任何 tool,只复用已绑定的 MCP 工具 +- 本次**不**改前端 Agent Market UI,假设前端会自动读取新 `AgentTemplate` 记录(若前端硬编码旧 category 值需配合修改) +- 本次**不**给每个模板写独立 HEARTBEAT.md,全部沿用 `backend/agent_template/HEARTBEAT.md`(如果测试发现行为有偏差再考虑) +- 本次**不**支持用户自定义模板,依然只有内置模板 +- 本次**不**迁移现有 4 个模板的内容到新文件布局,只更新它们的 `category` 字段;内容迁移留作独立清理任务 +- 本次**不**引入任何 emoji——所有模板的 `icon` 字段使用 2-3 字母的文字代号,soul / bootstrap / meta.yaml 正文内严禁出现 emoji + +--- + +## 3. 模板结构契约 + +每一个模板(新老都一样)必须提供以下 9 个字段: + +| 字段 | 存储位置 | 作用 | +|------|----------|------| +| `name` | `AgentTemplate.name` | Agent Market 卡片标题 | +| `description` | `AgentTemplate.description` | 卡片下方一句话简介 | +| `icon` | `AgentTemplate.icon` | 卡片上的文字代号(2-3 字母,如 `FE` / `CoS`)。严禁 emoji | +| `category` | `AgentTemplate.category` | 3 个值之一:`software-development` / `marketing` / `office` | +| `capability_bullets` | `AgentTemplate.capability_bullets`(注意:字段缺失,见 §6) | 卡片下方 3 条能力要点 | +| `soul_template` | `AgentTemplate.soul_template` | 完整人格——身份、个性、规则、工作流、语言 | +| `bootstrap_content` | `AgentTemplate.bootstrap_content`(注意:字段缺失,见 §6) | 首轮仪式,agent 配置完自删 | +| `default_skills` | `AgentTemplate.default_skills` | 创建 agent 时自动安装的 skill 文件夹名 | +| `default_autonomy_policy` | `AgentTemplate.default_autonomy_policy` | 各工具的权限等级(L1/L2) | + +### 3.1 `soul_template` 的子结构(方案 A:4 段最小化,统一英文) + +每一份 soul 都必须按下面的 4 段结构写: + +```markdown +# Soul — {name} + +## Identity +- **Role**: +- **Expertise**: + +## Personality +- <3-4 bullets on character traits specific to the role> +- I detect the user's language from their latest message and reply in the same language. When the message is ambiguous (emoji-only, code-only), I default to English. Internal files (plans, memory, workspace artifacts) stay in English for consistency; only chat replies switch language. + +## Work Style +- <3-5 role-specific bullets on how this agent approaches work> +- I save task plans, drafts, and final deliverables under `workspace//` — not inline in chat. Each task gets its own folder with a `plan.md` and numbered artifact files. +- I record non-obvious patterns, caveats, and reusable knowledge to `memory/.md` (e.g. `memory/performance_patterns.md`) so future sessions benefit from past work. +- During heartbeat, I focus on: . + +## Boundaries +- <3-4 role-specific boundary bullets — what needs human approval, what's out of scope> +- Actions that require an external integration (email, calendar, messaging, deployment) prompt the user to configure that integration first; I don't assume it's connected. +``` + +**设计原则:** +- 每个 bullet 都是可验证的行为,不是空泛修辞 +- Personality 里的最后一条语言规则在 11 个模板里**逐字一致**,方便审计 +- Work Style 里的 workspace / memory / heartbeat 三条**结构固定、内容按角色定制**——比如 Growth Hacker 的 memory 条写"experiment log",Frontend 写"performance_patterns" +- Boundaries 最后一条集成类动作的说明在所有模板里**逐字一致** + +### 3.2 `bootstrap_content` 模式(对齐主分支两轮仪式架构) + +**重要**:`bootstrap_content` 在主分支(`yutong/agent-templates`)上已经从"bootstrap.md 文件模式"重构为"系统提示词注入模式"。这段内容由 [backend/app/services/onboarding.py](backend/app/services/onboarding.py) 的 `resolve_onboarding_prompt` 在首位用户首次对话时注入。 + +**两轮仪式触发规则**: +- 只对 **founding user**(该 agent 的第一个对话者)生效 +- 后续用户走另一份共享的 welcoming 提示词(在 `onboarding.py` 里硬编码,不走模板) +- 一旦 deliverable turn 开始流式输出,向 `agent_user_onboardings` 插锁行,仪式结束 + +**bootstrap_content 模板骨架**(每个模板按这个结构填): + +``` +You are {name}, a meeting {user_name} for the first time. \ +Markdown rendering is on — **use bold** freely to highlight the user's name, \ +your own name, capability labels, and key next-step phrases. + +This conversation has had {user_turns} user messages so far. Follow EXACTLY \ +the matching branch below. + +If user_turns == 0 (greeting turn): +- Open with: "**Hi {user_name}!**" on its own line. +- One-line intro: "I'm **{name}**, your ." +- Pitch 2–3 capability bullets (bold label + short phrase): + - "**** — " + - "**** — " + - "**** — " +- Ask ONE bolded question: "****" +- Stop. Don't ask about <2-3 things to explicitly not probe on>. + +If user_turns >= 1 (deliverable turn): +- Whatever they said is the task. DO NOT ask clarifying questions about \ +. +- Produce inline with bold section \ +headers: + - "**
**" — . + - "**
**" — . + - "**
**" — . +- Close: "Want me to