技能社
技能社 · 公众号 技能社Pro · 深度指南
WorkBuddy 开放平台深度指南
技能 · 专家 · 专家团 · 连接器 全解
从定位架构 · 四件套规范 · 生成提示词 · 到上架运营，一次讲透
公众号技能社Pro · 扫码关注
知识库免费教程 · 扫码直达
网站技能社 · 扫码直达
v1.0 · 2026
技能社 · 公众号 技能社Pro · jinengshe.com
© 2026 技能社 保留所有权利
从定位架构 · 四件套规范 · 生成提示词 · 到上架运营，一次讲透
版权声明。本书 © 2026 技能社（公众号：技能社Pro，jinengshe.com）保留所有权利。本书为面向公众的通用教学资料，欢迎个人学习、引用与注明出处地分享；未经许可，不得整本转载、改名倒卖或用于商业再分发。
商标说明。书中提及的产品/平台名称，其商标与权利归各自权利人所有。本书由 技能社 作为独立第三方编写，与上述官方无隶属或背书关系。
版本。v1.0 · 2026 · 由 技能社 制作发布。发现错漏欢迎通过公众号 技能社Pro 反馈勘误。
本指南基于 WorkBuddy 开放平台官方文档（open.workbuddy.cn/docs）梳理与深度推演，目标是让开发者真正「能落地地」在平台上交付技能、专家、专家团与连接器，并理解平台的底层逻辑与选择方法论。\ 凡引用规范、字段、尺寸、超时、版本号、枚举值，均来自官方文档；官方未披露的（如审核周期、token 预算）已明确标注「平台未明确，建议…」，不做臆造。
| 篇 | 章 | 主题 |
|---|---|---|
| 第一篇 平台底层逻辑 | 01–04 | 定位与生态位、底层架构与上下文工程、资产四件套差异与组合、审核合规底层逻辑 |
| 第二篇 技能 | 05–08 | 规范全解、设计方法论、通用生成提示词、热门技能 30 例 |
| 第三篇 专家 | 09–12 | 规范全解、人格工程、通用生成提示词、热门专家 25 例 |
| 第四篇 专家团 | 13–16 | 规范全解、团队拓扑与编排方法论、通用生成提示词、热门专家团 12 例 |
| 第五篇 连接器 | 17–20 | 规范全解（MCP/CLI）、认证与凭证体系、通用生成提示词、热门连接器 20 例 |
| 第六篇 分类与选择 | 21–22 | 分类体系与资质地图、如何选择资产形态与组合策略 |
| 第七篇 落地实操 | 23–25 | 入驻到上架、Open API 与 Buddy 应用、失败诊断与排错 |
| 附录 | A–B | 提示词速查手册、检查清单/模板库/术语表 |
本篇章目标： 1. 准确理解 WorkBuddy 开放平台的官方定义、五类可开发业务，以及 Buddy 应用这一"行业 Harness"形态在整个生态中的位置。 2. 把官方"快速开始 8 步"翻译成可执行的工程动作，明确每一步的产出物、所需材料、常见卡点与耗时量级。 3. 通过与传统应用商店、小程序、浏览器扩展、OpenAI GPTs、MCP 工具生态、企业 IM 机器人平台的横向对比，判断这个平台真正的差异化是什么。 4. 建立一套"什么 know-how 值得做成资产、什么不值得"的判断标准，避免在错误的方向上投入研发。
官方文档的第一句话是理解全局的锚点：
开放平台是面向 WorkBuddy 生态业务的一站式工作台。开发者在入驻后并通过相应的资质审核后，即可在该平台进行以下业务的开发管理。
这句话有三个必须拆开读的信息：
第一，"一站式工作台"而不是"应用商店"。 它同时承担了入驻认证、资产创建、调试验证、审核发布、运行数据、版本维护六件事。这意味着开发者从上到下的动作都在同一个闭环里，不需要在"开发者后台 + 审核系统 + 数据后台"之间来回跳。
第二，"入驻后并通过相应的资质审核"是前置条件，不是可选步骤。 平台把实名与资质放在了资产开发之前——这与传统应用商店"先开发后审核"的顺序相反。这个顺序差异后面会反复影响你的项目排期：如果你计划做一个金融或医疗方向的专家，资质准备必须提前到立项阶段，而不是等到提审前一周。
第三，"开发管理"这个词暗示了资产的生命周期属性。 资产不是提交一次就结束的交付物，而是需要持续迭代、持续维护的在线服务。第 8 步"持续查看运行数据并进行版本维护"就是官方对此的明确保留。
官方列出的五类业务是：
| 一句话本质 | 交付物形态 | 面向的核心问题 | |
|---|---|---|---|
| Markdown + 资源子目录 | |||
| 有稳定人设与领域方法的角色 | plugin.json + Agent 定义文件 + 头像 | 让 AI 像一个固定角色那样持续工作 | |
| 让你的系统反过来驱动 WorkBuddy | OAuth 2.1 应用 + Open API 调用 | 让 WorkBuddy 长在你的产品里 |
注意这五类并不是并列的技术选项，而是从"注入知识"到"注入角色"到"注入组织"到"注入能力"到"反向集成"的一条递进光谱。第 03 章会用"能力 = 知识 + 工具 + 人格 + 编排"这个四维模型把这条光谱彻底拆开，本章只先建立直觉：
除了五类业务，官方文档还单列了 Buddy 应用。它的官方定位是：
Buddy 应用是垂直行业的 AI Harness —— 伙伴无需从零构建一套 AI 产品，而是通过 Buddy 应用这层 Harness 封装，将自身的行业 know-how 整合进 WorkBuddy 的 AI 底座之中。最终用户打开即获得一个专属于该行业的完整 AI 工作台。
"伙伴不造产品，造配置" 是这一形态的核心。要理解它的独特性，先要理解 Harness 这个词在本语境下的含义：
Harness 原意是"挽具、线束"。在 AI 工程里，它指的是套在模型外面、把模型能力约束并导向特定用途的那一层装置——包括系统提示词、预绑定的工具、预置的工作流、可用的模型池、可见的能力市场。模型是发动机，Harness 是整车。
Buddy 应用给伙伴的不是"一个上架位"，而是六个可自定义的维度：
| System Prompt + 内置 Skill，构成模式级 Harness | 建议 2–4 个；如"投研模式""法务模式" | ||
Buddy 应用与前面五类资产的关系是容器与被包含的关系，而不是并列关系：一个 Buddy 应用内部会圈定一批技能、专家、专家团、连接器，形成一个只面向某行业的封闭市场。这也是为什么第 03 章会把"Buddy 应用（全部）"作为一种组合模式——它是唯一一个能同时吃掉另外四种资产形态的载体。
对行业伙伴的意义在于：你不需要说服用户"先安装一个技能"，而是直接给用户一个打开就对的行业工作台。分发粒度从"一个能力"升级成"一个行业入口"。
Buddy 应用文档里明确列出五项由 WorkBuddy 团队持续投入建设、伙伴无需重复造轮子的底层能力：
这五句话是本书第 02 章的全部推理起点。 它们不是营销话术，而是对平台运行时能力的责任划分声明：伙伴负责行业 know-how，平台负责让多个 Agent 跑起来、让上下文不溢出、让记忆跨会话生效、让工具调用被正确编排、让权限不被滥用。理解这一点，你就能理解后面所有"为什么规范要这么定"的问题——很多看似繁琐的约束，都是这五项底座能力在工程上的必然推论。
在做资产之前，必须先搞清楚资产的"货架"在哪里。官方给出的入口路径非常具体：
| 用户路径 | ||
|---|---|---|
| 专家团 | ||
开发者的创建入口同样有明确路径：
| 创建对象 | 后续动作 | |
|---|---|---|
| 专家 | 市场右上角【我的专家】-【创建专家】 | |
"跳转进入对话，补全创建技能的提示词"这句话值得单独强调。 它说明平台的资产创建是对话驱动的：你不是在表单里逐项填空，而是用自然语言描述你想要什么，由平台（或其背后的 AI）解析成资产骨架，再由你下载、修改、打包回传。
这带来一个实操上的重要后果：你的初始描述质量直接决定骨架质量。含糊的"帮我做个财务专家"和具体的"做一个面向 A 股上市公司财报的财务分析专家，输出格式固定为三张表 + 一段风险提示，需要能读取 PDF 财报"会产出完全不同的初始文件。
如果提交 zip 包后解析失败，官方给出的兜底路径是：先对照【技能基础结构】【子资源目录说明】自行定位；定位不到则发邮件至 openworkbuddy@tencent.com，或扫开放平台首页下方二维码加入社群。请在项目排期里为这一步预留缓冲——解析失败在第一次提交时并不罕见，常见原因是目录层级不对、SKILL.md 文件名大小写错误、zip 打包时多包了一层目录。
官方给出的 8 步是：
下面把每一步翻译成工程动作。耗时列全部为作者基于工程经验的估算，平台未公布官方时长，实际以平台当期节奏为准。
| 官方步骤 | 这一步实际要产出什么 | 常见卡点 | |||
|---|---|---|---|---|---|
| 2 | 通过认证的个人/企业主体 + 超级管理员身份 | 身份证已被其他账号占用；企业四要素不一致；第三方主体与执照不一致 | |||
| 6 | 资产包 + 服务类目 + 资质文件（如涉及） | 提交 10–30 分钟；审核时长平台未明确 | |||
| 8 | 查看运行数据并版本维护 |
这一步的本质是建立"账号"与"主体"两个概念的分离。 官方文档反复强调"不同账号认证产生的主体、开放资产和其他资产相互独立"，这说明平台的数据模型是：
账号（Account）──1:N──> 主体（Subject）──1:N──> 开放资产（Asset）
账号是登录凭据，主体是法律意义上的责任归属，资产挂在主体下面。这个三层模型在第 04 章会展开讲，这里只需要记住一个实操结论：在注册之前就决定好"用哪个账号承载哪个主体"，因为主体与资产的独立性意味着事后迁移成本极高。
需要准备的东西，官方列得很清楚：本人中国大陆二代居民身份证号码、已完成实名登记的本人手机号、可以正常接收验证码的邮箱、可以正常完成人脸识别的手机。
常见卡点：
这是 8 步里唯一有可能被外部因素（法人配合、第三方平台授权）阻塞的一步。详细规则见第 04 章，这里只讲排期影响：
排期建议：如果法人无法随时配合人脸核身，优先选择两种快速认证方式之一，把这一步从"依赖某人有空"变成"依赖某平台已认证"。这是唯一能显著压缩这一步耗时的手段。
这一步看起来最轻，实际是整个项目里投资回报率最高的决策点。选错形态的代价不是返工几小时，而是整个资产要重新设计。
一个极简的判断顺序（详细的四个判断题见第 03 章）：
你的 know-how 主要是"做事的方法"吗？ ├─ 是，且不依赖外部系统 → 技能 ├─ 是，但必须调用外部系统 → 连接器 + 技能 └─ 不是，核心是一个"人"的判断力与风格 ├─ 一个人就够 → 专家（+ 技能/连接器） └─ 需要多个视角互相博弈 → 专家团
常见卡点：团队里没有人对形态决策拍板，导致先做了再改。建议在第 3 步之前就用第 03 章的决策矩阵走一遍，把结论写进立项文档。
这是耗时最长、也最容易因为细节被打回的一步。不同形态的必填项完全不同，但有几条跨形态通用的硬约束值得先记住：
| 单个头像大小 ≤500KB | ||
| 专家、专家团 | displayDescription.zh | |
| tags 固定 3 个 | ||
| 连接器示例各 2～5 条 | 连接器 | |
"40–50 字"和"固定 3 个"这类约束是硬性的。它们不是建议，写少了写多了都会在解析或审核阶段失败。建议在写作前先用字数统计工具卡一遍。
常见卡点排序（按出现频率）：
description 要求英文，同时 description_zh / description_en 也要填；漏一个就 fail。defaultInitPrompt 与 quickPrompts[0] 文案不一致（哪怕差一个标点）。team-lead，而官方要求"名称须加专家团前缀，不可用通用 team-lead"。这一步的目标不是"跑通一次"，而是建立一组可复现的测试用例。建议至少准备：
| 目的 | ||
|---|---|---|
对技能而言，重点验证触发是否准确：你说的触发词能不能稳定唤起它，以及它在不该被唤起的时候会不会误触发。如果误触发严重，考虑用 disable-model-invocation: true 改成手动调用；如果只希望 AI 内部使用不想出现在菜单里，用 user-invocable: false。
对连接器而言，重点验证超时与鉴权：官方要求单次请求建议在 30 秒内响应（mcp.json 的 timeout 默认 30000 毫秒），且授权失效时要能返回可识别错误并引导用户重新连接。
提交动作本身很短，但前置检查清单要长。官方在连接器文档里给了一份"提交前检查"，本书第 04 章会把它扩展成覆盖四类资产的「上线前自检 40 条」。
审核阶段最容易出问题的不是技术，而是类目与资质：你选的服务类目要求的资质你没提供，或提供了但已过期，或提供了但主体与认证主体不一致。
上线这一步本身没什么可做的，但有一个必须写进运维手册的事实：后续更新需要重新提交审核。官方对连接器的口径是"后续更新重新提交审核即可，通常在 10～15 分钟内同步生效"。这意味着：
这一步决定了资产的长期价值。很多团队的失败不是做不出来，而是做出来就不管了。
建议建立的最小维护节奏：
| 周期 | |
|---|---|
| 上线首月 | |
官方对平台优势的表述是：
通过开放平台，开发者可以将行业 know how、业务系统和服务能力快速转化为 WorkBuddy 生态中的标准化产品，在降低开发与运营成本的同时，获得统一的发布渠道和用户触达能力。
这句话里有四个可拆解的商业价值点，下面逐个翻译成可算账的语言。
传统 SaaS 的增长模型里，获客成本（CAC）通常是最大的一块支出。开发者要自己建站、做 SEO、买投放、跑销售。
在开放平台上，你的资产出现在用户本来就在用的客户端里——左侧菜单【专家·技能·连接器】是一个高频入口，用户是带着"我现在有个任务要做"的明确意图进来的。这类意图驱动的货架，转化率与"用户在应用商店里随便逛"完全不是一个量级。
但要注意它的另一面：共享货架意味着共享竞争。你的技能旁边就是别人的技能，用户点击成本极低，切换成本也极低。所以分发优势真正兑现的前提是——你的资产在首次使用的最初 30 秒内就能交付可感知的价值。这直接决定了 quickPrompts 与 defaultInitPrompt 的设计质量，而不是"功能多不多"。
开放平台的触达机制是意图匹配：用户想要完成某个任务，平台把能做这个任务的资产递上去。这与广告的"人群匹配"有本质区别。
| 维度 | 人群匹配（广告/信息流） | |
|---|---|---|
这个区别带来一个反直觉的结论：在开放平台上，把 description 写清楚比把功能做多更重要。官方在技能规范里明确要求 description "写清用途和触发词"，就是这个道理——它是意图匹配的唯一入口。
传统咨询/服务模式的核心矛盾是：交付质量依赖人，而人的时间不可复制。一个资深行业顾问一年能交付的项目数量有硬上限。
把 know-how 做成资产后，成本结构变成：
但边际成本低不等于躺赚。 资产模式的持续成本转移到了"维护"上：外部 API 变更、平台规范升级（比如 minWorkbuddyVersion 相关的字段门槛）、用户预期变化，都会让你的资产退化。第 8 步"持续查看运行数据并进行版本维护"不是一句客套话，它是这个商业模型能否成立的必要条件。
这是四点上最具长期价值的一点，也最难做对。
know-how 资产化的本质是把隐性知识显性化。一个老法师判断一笔交易能不能做，靠的是二十年积累的模式识别；要把这个能力做成资产，你必须把它拆成可描述、可验证的步骤。
拆解质量决定了资产质量。一个可操作的拆解框架：
| 层级 | 内容 | 在 WorkBuddy 里的落点 |
|---|---|---|
| 连接器、scripts/ | ||
这六层里，最容易缺失的是"判据层"。 大多数失败的技能只写了流程（"第一步分析，第二步总结"），没写判据（"什么样的分析结果算合格"）。而判据恰恰是 know-how 中最值钱、也最难被复制的部分。
判断一个平台的真实位置，最有效的办法是把它放到同类里横向比。下面选了六个参照系：传统应用商店、小程序、浏览器扩展、OpenAI GPTs、MCP 工具生态、企业 IM 机器人平台。
| 变现 | 平台未公布统一变现规则 | 广告/交易/服务，规则成熟 | 付费/捐赠，能力弱 | 无成熟变现 | 企业采购/授权，To B 为主 | ||
| 中 | |||||||
| 可组合性 | 高：技能可被专家预加载、可被专家团共享、可被连接器配套；Buddy 应用可圈定子集 | 中：多个 Server 可并存但无编排层 | 中：可被工作流编排 |
传统应用商店与小程序都是流量货架——你在一个人流大的地方摆摊，靠位置、榜单、投放获取注意。这类货架的赢家通常是"能满足最多人最泛需求"的产品。
开放平台的货架是意图货架——用户带着"我要分析这只股票""我要写一份尽调报告"的具体任务进来。这类货架的赢家是"在这个具体任务上做得最好"的资产。
商业含义：在流量货架上，通用 > 垂直；在意图货架上，垂直 > 通用。这与 Buddy 应用"场景优先，价值不在于堆叠能力清单，而在于将高频场景做深做顺"的官方建议完全一致。
这是 WorkBuddy 与 GPTs、MCP 生态最大的分野。
结论：MCP 生态解决的是"连接"，WorkBuddy 解决的是"连接之后怎么把事做成"。这也解释了为什么平台要把 MCP 包一层做成"连接器"——因为裸 MCP 只提供 tools，不提供"AI 该怎么用这些 tools"的知识，而这个知识由配套的 Skill 提供（详见第 02 章 2.7 节）。
对比表里有一项容易被忽略：WorkBuddy 的专家内置工具包含 Read / Write / Grep / Glob / Bash / WebSearch / WebFetch。
这意味着资产不只是"生成文本"，而是可以：
scripts/ 就是靠它跑起来的）这是浏览器扩展（受沙箱与浏览器生命周期限制）、GPTs（无本地文件系统）、企业 IM 机器人（通常只有消息通道）都不具备的组合。"能动手"和"只能动嘴"是两类完全不同的产品。
同时也要注意边界的另一面：正因为有 Bash，平台才必须把工具权限收归系统统一分配、开发者不可自行添加 tools（详见第 02 章 2.5 节）。能力越大，权限模型越要收紧。
必须诚实说明：截至本书写作时，平台未在所给文档中公布面向开发者的统一变现规则（分成比例、订阅机制、付费资产等）。
这意味着：
这个判断会随着平台政策变化而改变，请以平台当期公告为准。 本书不对未公布的规则做任何推测。
对比表里，开放平台的审核强度与小程序并列最高，且多了两个别人没有的环节：强实名（个人身份证唯一 / 企业四要素） 与 服务类目资质。
原因不难理解：当 AI 能读写文件、能执行脚本、能调用外部服务时，一个恶意资产的破坏力远超一个普通 App。平台的合规体系不是形式主义，它是能力边界的直接对价。第 04 章会完整拆解这套体系。
这是 WorkBuddy 最独特的工程选择：技能是 Markdown，专家的人格定义是 Markdown（Agent 定义文件），只有连接器需要真正的后端开发。
| 是否需要写代码 | ||
|---|---|---|
| 专家团 | 不需要 | 多个人格定义 + 主理人 SOP + teamInfo 编排 |
| 连接器 | 需要（MCP Server 或 CLI） | 后端服务 + 协议对接 + 鉴权 |
| Buddy 应用 | 六大维度的配置与行业内容组织 |
成本含义：know-how 型团队（咨询公司、行业服务商、内部效率团队）不需要招工程师就能交付技能与专家；而连接器才是需要工程投入的部分。这个成本结构决定了"行业伙伴"是平台最自然的目标用户——也正是 Buddy 应用这一形态存在的理由。
对比表里这一项，WorkBuddy 明显高于其他所有参照系。它的组合关系是内建的：
| 专家预加载技能 | skills（否）：预加载的技能名称列表 | |
可组合性带来的是复利：一个技能写完，可以被一个专家预加载，被一个专家团共享，被一个连接器配套，被多个 Buddy 应用引用。这是其他生态里不存在的杠杆。
把七个维度放在一起看，我的判断是：
WorkBuddy 开放平台的差异化不在于"又一个 AI 应用市场"，而在于它是目前少数几个同时具备「强运行时能力」「原生可组合性」和「中心化合规体系」的生态。
拆开说：
1. 强运行时能力是地基。 多 Agent 协同 + 上下文工程 + 记忆 + 工具编排 + 权限管控这五项，GPTs 没有，MCP 生态不提供，浏览器扩展装不下，小程序用不上。这让平台上的资产可以做"真的活儿"，而不只是聊天。
2. 原生可组合性决定了天花板。 因为技能、专家、专家团、连接器之间可以互相嵌套引用，资产的价值不是线性叠加，而是网状放大。一个做得好的基础技能（比如"财报三表结构化提取"）可以被上面几十个专家复用。这是这个生态里最值得投资的位置——底层可复用能力，而非顶层花哨应用。
3. 中心化合规体系是门槛也是护城河。 强实名 + 服务类目资质 + 梯度违规处置，把"随便做做"的玩家挡在外面。对认真做的团队，这意味着货架不会被劣币挤满。
4. 但它有明确的短板，必须说清楚：
一句话定位：如果你的目标是"把一份行业 know-how 变成可复用、可组合、有合规背书的 AI 能力，并借 WorkBuddy 的客户端触达用户"，这个平台目前几乎没有同等强度的替代方案。如果你的目标是"做一个能到处跑的通用工具"，那应该做 MCP Server，而不是这里的连接器。
做了前面的对比，最后一个必须回答的问题是：我的 know-how 到底值不值得做？
| # | |||
|---|---|---|---|
| 1 | 边际成本优势才能兑现 | 技能 | |
| 3 | 产出物有固定结构：报告、清单、表格、代码骨架 | templates/ 能发挥作用，产出稳定 | |
| 5 | 人格维度有价值 | ||
| 7 | know-how 稀缺且难招人：行业老法师经验 | ||
| 特征 | |||
|---|---|---|---|
| 3 | |||
| 6 | 需要图形界面交互：拖拽式设计、可视化编辑 | ||
把上面两张清单量化成打分卡，总分 ≥ 20 分建议做，12–19 分谨慎做，\< 12 分不建议做。
| 2 分 | 3 分 | |||
|---|---|---|---|---|
| 是否需要稳定人设 | — | |||
| 人人都懂 |
使用示例：某券商的"上市公司财报速读"能力。
| 使用频率 | 财报季每周多次 | |
| 判据可描述性 | 三表勾稽、异常科目识别可写成规则 | |
| 产出结构稳定性 | 3 | |
| 依赖外部数据 | 3 | 必须读取财报 PDF 与行情数据 |
| 需要经验但不算极稀缺 | ||
最后补一个我认为比打分卡更重要的判断。
很多团队以为自己的 know-how 是"流程"（先做什么后做什么），但流程通常是行业公开的、模型也大致知道的。真正稀缺的是判据——在流程的每一步上，什么样的结果算合格，什么样的信号算异常。
| 流程型 know-how | "先收集需求，再设计方案，最后评审" | 产出的东西"看起来对"但没用 | 价值低，容易被模型自带能力覆盖 |
| 流程 + 判据 | 既有步骤又有每步的通过标准 | 强烈建议做 |
检验方法：把你的 know-how 拿给一个同行业但没做过这件事的人看，如果他说"步骤我知道了，但我还是不知道怎么判断对不对"——那你的判据还没写出来，资产还不到时候做。
本章建立了四件事：
在进入第 02 章之前，请确认你能回答以下问题：
我能说清技能、专家、专家团、连接器、外部应用接入五类业务各自解决的是 How / Who / Organization / With what / Where 中的哪一个问题吗？
我知道 Buddy 应用的六大自定义维度分别是什么，以及它们分别作用在哪个层级（应用级/模式级/场景级）吗？
我的项目计划里，是否为第 2 步资质认证预留了法人配合的时间？
我是否已经用第 03 章的决策矩阵（或本章 1.6.3 的打分卡）确定了资产形态？
我的核心 know-how 里，"判据"部分是否已经能写下来？如果写不下来，我是否应该先做判据梳理再开工？
我是否了解平台当前未公布统一变现规则，并据此调整了项目的收益预期？
我的资产如果需要在高频场景下使用，是否设计好了首次 30 秒内的价值交付（对应 quickPrompts / defaultInitPrompt）？
第 02 章将从 Buddy 应用文档里列出的五项底座能力出发，反推整个平台的架构逻辑，并回答一系列"为什么规范要这么定"的问题：为什么技能是 Markdown 而不是代码、为什么是 references/scripts/templates 三个目录、为什么专家不能自己加 tools、为什么专家团必须有主理人。理解这些约束，是做出正确设计决策的前提。
本篇章目标： 1. 从官方明示的五项底座能力（多 Agent 协同运行、上下文压缩工程、记忆工程、工具调用编排、安全与权限管控）反推出平台的完整分层架构，理解每一层各自负责什么、边界在哪。 2. 彻底理解"渐进式披露"机制，据此建立一套上下文预算模型，能够估算一个资产在一次对话中到底占用多少 token。 3. 理解每一个看似奇怪的规范约束背后的工程理由：为什么技能是 Markdown、为什么是 references/scripts/templates 三个目录、为什么专家不能自己加 tools、为什么专家团要有主理人、为什么连接器有两条路线。 4. 掌握本章结尾给出的「资产设计者必须理解的三条底层约束」，并用它们解释后面所有章节的设计决策。
buddy-app.md 里有一段话，是理解整个平台的钥匙：
## WorkBuddy 基础能力 以下底层能力由 WorkBuddy 团队持续投入建设，伙伴无需重复造轮子，开箱即用： - 多 Agent 协同运行 - 上下文压缩工程 - 记忆工程 - 工具调用编排 - 安全与权限管控
这段话表面上是"我们已经做好了，你别重复造"的承诺，实际上是一份运行时责任划分声明。逐条拆开，每一条都对应着一组必然的设计约束：
这五条不是功能列表，而是五条"你不需要做、也不可以做"的边界声明。 后面整章的内容，都是这五条边界的展开。
官方文档只写了"有什么"，没有写"为什么"。本章的方法是：从规范的形式反推运行时的机制。
举例：SKILL.md 必须放在 skills/{skill-name}/ 目录下，且文件名必须叫 SKILL.md，用 YAML frontmatter + Markdown 正文。这个形式约束为什么存在？因为它暗示了运行时是这样工作的：
skills/ 下所有子目录，找到 SKILL.md。description）常驻上下文。description 时，才把 Markdown 正文读进上下文。@references/xxx.md 时，才去读那个文件。如果运行时不是这样工作的，那"frontmatter + 正文 + 引用"这个三级结构就毫无意义。形式即机制的指纹。 本章大量使用这种推理，并会在每处明确标注哪些是官方明示、哪些是推理、哪些是估算。
标注约定：本章中，凡标注「官方明示」的均为文档原文可直接佐证；标注「推理」的为基于规范形式的逻辑推演；标注「估算」的为工程经验值，平台未公布，不得作为规范引用。
把官方文档里散落的线索拼起来，平台的逻辑架构可以画成这样：
┌──────────────────────────────────────────────────────────────────────┐ │ 端侧（Client） │ │ WorkBuddy 客户端：对话界面 / 市场入口 / 设置 / 移动端 │ │ 用户入口：左侧菜单【专家·技能·连接器】→【技能】【专家】【专家团】【连接器】 │ │ Buddy 应用：打开即进入行业专属工作台 │ └──────────────────────────────────────────────────────────────────────┘ ▲ │ 安装 / 召唤 / 连接 ┌──────────────────────────────────────────────────────────────────────┐ │ 市场层（Marketplace） │ │ · 展示：名称 / 头像 / 描述 / tags / quickPrompts / categoryId │ │ · 分发：安装、加号安装、召唤专家 │ │ · 合规：服务类目、资质、审核、违规梯度处置 │ │ · 主体：开发者主页（头像/昵称/简介/联系方式） │ └──────────────────────────────────────────────────────────────────────┘ ▲ │ 打包 / 提交 / 审核通过 ┌──────────────────────────────────────────────────────────────────────┐ │ 资产层（Assets） │ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 技能 │ │ 专家 │ │ 专家团 │ │ 连接器 │ │ 第三方应用│ │ │ │ SKILL.md │ │plugin.json│ │ teamInfo │ │mcp.json │ │ OAuth2.1 │ │ │ │ refs/ │ │agents/*.md│ │ members[] │ │cli.json │ │ Open API │ │ │ │ scripts/ │ │avatars/ │ │ settings.json│ │icon.svg │ │ ACP 通道 │ │ │ │templates/│ │.mcp.json │ │ agents/* │ │skills/ │ │ │ │ │ └──────────┘ └──────────┘ └────────────┘ └──────────┘ └──────────┘ │ │ 知识 知识+人格 知识+人格+编排 工具 反向集成 │ └──────────────────────────────────────────────────────────────────────┘ ▲ │ 预加载 / 依赖声明 / 圈定 ┌──────────────────────────────────────────────────────────────────────┐ │ Harness 层（约束与编排层） │ │ · 工作模式：System Prompt + 预绑定 Skill（模式级，全程生效，建议 2–4 个） │ │ · 场景胶囊：场景级 Harness，点击后叠加在工作模式之上 │ │ · 模型配置：从模型池勾选 + 排序 + 指定默认 │ │ · 垂直行业市场：决定用户可发现哪些资产 │ │ · 内嵌已有功能：MCP Apps │ │ → 这一层是 Buddy 应用的全部，也是"伙伴不造产品，造配置"的实现位置 │ └──────────────────────────────────────────────────────────────────────┘ ▲ │ 调度 / 注入 / 检索 ┌──────────────────────────────────────────────────────────────────────┐ │ 底座层（Runtime）— WorkBuddy 团队持续投入，伙伴无需重复造轮子 │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐ │ │ │ 多 Agent 协同运行 │ │ 上下文压缩工程 │ │ 记忆工程 │ │ │ │ · TeamCreate │ │ · 长对话压缩 │ │ · 跨会话记忆 │ │ │ │ · AgentTool │ │ · 渐进式披露 │ │ · 用户偏好 │ │ │ │ · SendMessage │ │ · 上下文预算 │ │ │ │ │ └────────────────┘ └────────────────┘ └────────────────────────┘ │ │ ┌────────────────────────────┐ ┌────────────────────────────────┐ │ │ │ 工具调用编排 │ │ 安全与权限管控 │ │ │ │ · 内置工具集（系统统一分配） │ │ · 凭证不落包、不落云端 │ │ │ │ · MCP 工具发现与调用 │ │ · OAuth 2.1 + PKCE │ │ │ │ · CLI 调度（init/auth/status）│ │ · 最小权限 Scope │ │ │ └────────────────────────────┘ └────────────────────────────────┘ │ │ 内置工具：Read / Write / Grep / Glob / Bash / WebSearch / WebFetch │ │ AgentTool / SendMessage（主理人可用） │ └──────────────────────────────────────────────────────────────────────┘
关键结论：你的可控域只有资产层（以及 Buddy 应用下的 Harness 层）。 底座层的五项能力你既改不了也不该改。所有"我想优化一下上下文管理""我想给 Agent 加个自定义工具"的念头，都撞在这条边界上。
注意架构图里资产层到 Harness 层的箭头是"预加载 / 依赖声明 / 圈定"，Harness 层到底座层的箭头是"调度 / 注入 / 检索"。
这说明资产本身不执行任何东西，它只是被底座读取、被 Harness 约束的一组声明。技能是声明，专家是声明，专家团是声明，连接器是声明 + 一个外部服务地址。
理解这一点，就能理解为什么平台上的资产开发这么"轻"——因为运行时不在你的包里。这个设计决定了后面所有的规范形态。
技能的核心文件是一个 Markdown 文件：
```markdown
---
name: your-skill-name
display_name: 展示名称
display_name_en:
description: 一句话描述技能能力
description_zh: 简短中文介绍
description_en: A Brief English Introduction
category: writing # 分类之一
version: 1.0.0
author: 合作方名称
---
# 技能指令正文
当用户需要做 XX 时，按以下步骤执行：
1. ...
2. ...
3. ...
**为什么不是 TypeScript？不是 Python？不是 JSON DSL？**
最直觉的答案是"Markdown 好写"，但这只是表面。真正的原因有三个，按重要性排序：
1. **Markdown 是模型可读与人类可读的最大公约数。** 技能的消费者是 LLM，不是解释器。用代码表达流程，需要一层解析器把代码翻译成模型能理解的指令；用 Markdown 表达，模型直接读。
2. **Markdown 天然支持"部分加载"。** 一个 Markdown 文件可以按 frontmatter / 章节 / 引用三级粒度拆开读，而一个代码模块要么整块加载要么不加载。**这个特性是渐进式披露的前提。**
3. **Markdown 天然支持"不精确执行"。** 代码要么执行成功要么报错，而模型执行 Markdown 指令时可以按上下文灵活调整。技能的很多场景（"分析一下这份财报"）恰恰需要这种弹性。
### 2.3.2 渐进式披露（Progressive Disclosure）机制
这是本章最重要的概念。
**定义**：渐进式披露是指，一个技能的完整内容不会一次性进入上下文，而是按"需要多少加载多少"的节奏分层注入。
根据官方给出的目录结构与引用语法，可以推导出三级结构（**推理**）：
| |
| |
| |
| |
| |
**为什么 L0 必须只放 frontmatter？** 因为一个用户可能安装了几十个技能。如果每个技能的全文都常驻上下文，上下文窗口瞬间耗尽。所以常驻的只能是"这个技能是干什么的、什么时候该用它"这一句话级别的摘要。
这解释了一个看似奇怪的官方要求：
> |description |是 |写清用途和触发词|
**"写清触发词"这个要求，正是因为 `description` 是 L0 常驻层里唯一的内容。** 它是模型判断"要不要加载 L1"的唯一依据。写得含糊，技能就永远不会被触发；写得太泛，就会误触发。
### 2.3.3 触发词设计的工程建议
基于 L0 常驻这一事实，`description` 的写法有明确的最优实践：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
**写法模板**：
description_zh: <做什么（动作 + 对象 + 产出）>。当用户<触发场景 1>、<触发场景 2>、<触发场景 3>时使用
三段缺一不可：**做什么**（让模型知道能力边界）、**产出什么**（让模型知道调用后的收益）、**什么时候用**（让模型知道触发条件）。
### 2.3.4 上下文预算模型
现在可以给出一个可计算的东西了。
> **⚠️ 免责声明：以下 token 分配表为作者基于工程经验的估算，WorkBuddy 官方未公布任何上下文窗口大小、分配比例或具体数值。本表仅用于建立"上下文是稀缺资源"的直觉与相对量级判断，严禁作为规范数字引用。**
假设一次典型对话的上下文窗口为 200K token（行业常见量级，非官方数值），一次"召唤专家 + 专家预加载 2 个技能 + 调用 1 个连接器"的任务，其预算分配估算如下：
| | | | | |
| --- | --- | --- | --- | --- |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
**从这张表能推出四条工程结论：**
**结论 1：L0 层的竞争是零和的。** 用户安装的技能越多，每个技能分到的"注意力"越少。这直接意味着：**`description` 写得越长，占用的 L0 预算越多，但触发准确率越高**——这是一组真实的权衡。建议 `description_zh` 控制在 50–120 字，既能说清触发条件，又不至于挤占太多预算。
**结论 2：L1 正文的成本远低于 L2。** 正文（L1）加载一次即可服务整个任务，而 references（L2）每读一次就占一次。所以**高频使用的知识应该放在 L1 正文，低频的才放 L2**。
**结论 3：工具调用结果是最大的不可控变量。** 估算占比 10–30%，且完全由外部数据决定。一个返回 50KB JSON 的 MCP 工具调用，一次就能吃掉四分之一预算。这正是官方要求"工具名称、描述、参数和返回值应清晰、稳定"以及"返回可读错误信息"的深层原因——**不是为了让 AI 看懂，首先是为了让返回值别太大**。
**结论 4：上下文压缩工程是你的朋友，但不是万能的。** 平台会压缩对话历史，但压缩是有损的。你在第 5 轮提到的某个关键约束，到第 30 轮可能已经被压缩掉了。**所以关键判据必须写进资产（L1 或 L2），而不是依赖对话历史里的口头交代。**
### 2.3.5 由预算模型推出的技能设计规则
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
## 2.4 为什么是 references / scripts / templates 三个子目录
官方给出的技能目录结构：
skills/
└── {skill-name}/
├── SKILL.md # ★ 技能定义（必须）
├── references/ # 参考资料（可选）
│ ├── api-spec.md # API 规范、字段类型等
│ └── examples.md # 示例数据
├── scripts/ # 可执行脚本（可选）
│ ├── fetch-data.js # 数据获取脚本
│ └── transform.py # 数据处理脚本
└── templates/ # 模板文件（可选）
├── report.sh # 报告生成模板
└── workflow.sh # 工作流模板格式
**为什么恰好是三个？为什么不是"一个 resources/ 目录随便放"？**
因为它们对应三种**本质不同**的上下文扩展策略：
| | | | | |
| --- | --- | --- | --- | --- |
| | | | | |
| | | | | |
| | | | | |
### 2.4.1 references/：知识分页
**机制**：正文中用 `@references/xxx.md` 引用，命中后平台才读取该文件内容注入上下文。
**本质**：这是一次"上下文换页"。把一本厚手册拆成若干页，每次只把当前需要的那一页摊在桌上。
**适用场景（正面清单）**：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**反例（什么时候不该用 references）**：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**一个具体的正例**：
```markdown
```markdown
# 技能指令正文
## 执行步骤
1. 读取用户提供的财报文件（PDF/Excel）
2. 提取三表主表数据
3. **若用户要求核查异常科目，参考 `@references/abnormal-checklist.md` 中的 12 项核查规则**
4. 若需要行业对比数据，执行 `scripts/fetch-industry.py --code {股票代码}`
5. 按 `templates/report.md` 的结构输出
## 重要
- 步骤 3 的核查规则只在用户明确要求核查时才读取，默认不读。
注意加粗那句的写法：**它明确告诉模型"什么情况下才读这一页"**。这是 references 机制能否被正确使用的关键——模型需要知道翻页的时机。
### 2.4.2 scripts/：确定性执行
**机制**：AI 通过 Bash 工具执行脚本，脚本的输出进入上下文。
**本质**：这是"用确定性替换概率性"。模型做算术、做精确字符串处理、做大规模数据遍历，都是既慢又不可靠的；脚本做这些是确定性的。
**这是三种策略里唯一不消耗上下文的**——脚本本身的代码不进上下文（只有调用命令进），只有执行结果进。这个特性极其重要：
上下文成本
知识分页（references） 高 ████████ ← 文件内容全进上下文
产出骨架（templates） 中 ████ ← 模板结构进上下文
确定性执行（scripts） 低 ██ ← 只有 stdout 进上下文
**适用场景（正面清单）**：
| | |
| --- | --- |
| | |
| | |
| | |
| | |
| | |
**反例（什么时候不该用 scripts）**：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
**一个正例**：
```python
```python
#!/usr/bin/env python3
# scripts/fetch-industry.py
# 用法：python scripts/fetch-industry.py --code 600519
# 输出：仅输出目标公司与行业中位数的 5 项核心指标（已裁剪）
import argparse, json, os, sys
import urllib.request
def main():
p = argparse.ArgumentParser()
p.add_argument("--code", required=True)
args = p.parse_args()
token = os.environ.get("INDUSTRY_API_TOKEN")
if not token:
print("ERROR: 未配置 INDUSTRY_API_TOKEN，请在连接器设置中填写", file=sys.stderr)
sys.exit(2)
req = urllib.request.Request(
f"https://api.example.com/industry/{args.code}/peer",
headers={"Authorization": f"Bearer {token}"}
)
with urllib.request.urlopen(req, timeout=30) as r:
data = json.load(r)
# 关键：只输出 5 个字段，不吐原始大 JSON
slim = {
"code": data.get("code"),
"pe": data.get("pe"),
"peer_pe_median": data.get("peer", {}).get("pe_median"),
"roe": data.get("roe"),
"peer_roe_median": data.get("peer", {}).get("roe_median"),
"rev_growth_yoy": data.get("rev_growth_yoy"),
}
print(json.dumps(slim, ensure_ascii=False))
if __name__ == "__main__":
main()
注意这个脚本的三个关键设计：
1. **凭证从环境变量读，不硬编码**（官方明令："包内严禁硬编码任何真实 Token / 密钥"）。
2. **输出做了裁剪**，只吐 5 个字段。
3. **失败时输出可读错误**（官方要求："返回可读错误信息"）。
### 2.4.3 templates/：产出骨架
**机制**：存放可复用的模板脚本或配置文件，模型按模板的结构产出。
**本质**：这是"约束产出空间"。不给模板，模型每次的输出结构都可能不同；给了模板，输出结构稳定，下游可解析、可比对、可入库。
**适用场景（正面清单）**：
| | |
| --- | --- |
| | |
| | |
| | |
| | |
**反例**：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**一个正例**：
```markdown
```markdown
# {{公司名称}}（{{股票代码}}）财报速读
> 数据期间：{{报告期}} 生成时间：{{生成时间}}
## 一、三表摘要
| 指标 | 本期 | 上年同期 | 同比 |
|---|---|---|---|
| 营业收入 | {{营业收入}} | {{营业收入_上年}} | {{营收同比}} |
| 归母净利润 | {{归母净利润}} | {{归母净利润_上年}} | {{净利同比}} |
| 经营活动现金流净额 | {{经营现金流}} | {{经营现金流_上年}} | {{现金流同比}} |
## 二、异常科目核查
{{异常科目清单或"本次未执行异常科目核查"}}
## 三、风险提示
1. {{风险点 1}}
2. {{风险点 2}}
## 四、结论
{{一句话结论}}
注意模板里两处 HTML 注释——**这是模板区别于示例的关键**：注释是给模型的指令，模型产出时会剔除；而 `{{占位符}}` 是给模型填充的位置。
### 2.4.4 三者的选择决策树
你需要扩展技能的能力，缺的是什么？
│
├─ 缺"知识/规则"（模型不知道某件事）
│ └─ 这份知识每次都要用吗？
│ ├─ 是 → 写进 SKILL.md 正文（L1）
│ └─ 否 → references/（L2，并写清何时读）
│
├─ 缺"确定性能力"（模型能做但做不准/太慢/不能碰凭证）
│ └─ scripts/（注意输出裁剪）
│
└─ 缺"产出结构的稳定性"
└─ templates/（注意留灵活区）
## 2.5 为什么专家的工具权限由系统统一分配
官方文档在"关于工具"一节写得非常直接：
> ###
> 关于工具
>
>
>
>
>
> 开发者不可自行添加 tools：所有工具权限由系统统一分配。\
> 系统内置工具（仅供了解，由系统自动分配）：
>
>
>
>
>
> |工具 |说明|\
> |Read |读取文件|\
> |Write |写入文件|\
> |Grep |搜索文件内容|\
> |Glob |按模式查找文件|\
> |Bash |执行命令行命令|\
> |WebSearch |搜索互联网|\
> |WebFetch |获取网页内容|\
> |AgentTool |调用其他 Agent（主理人可用）|\
> |SendMessage |发送消息（主理人可用）|
**"仅供了解，由系统自动分配"** 这句话是重点：你连"我要用哪些工具"的选择权都没有。
### 2.5.1 这个设计解决什么问题
设想如果允许开发者自定义 tools，会发生什么：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
**统一分配工具集解决的是"能力可枚举"这个根本问题。**
当工具集是固定的九个时：
1. **审核可静态化**：审核员只需要看专家的 Markdown 里有没有诱导越权的指令，不需要分析二进制。
2. **行为可预测**：用户在市场看到"技术工程"类专家，就知道它大概率会用 Read/Write/Bash——能力边界是透明的。
3. **上下文可控**：工具定义是固定的，不会因为装了 20 个专家就塞进 200 个工具定义。
4. **可移植**：同一个专家包在任何装了 WorkBuddy 的机器上行为一致。
### 2.5.2 这个设计的代价
必须诚实地说，这个取舍有明确的代价：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
**注意"规避方式"一列：MCP 连接器正是官方给这个限制留的出口。** 你不能自己造工具，但你可以提供一个 MCP Server，让平台把它作为连接器接入。这不是绕过限制，而是把"自定义能力"放到了一个可审核、可鉴权、可撤销的框架里。
这个设计逻辑非常清晰：
自定义工具（禁止） ──→ MCP 连接器（允许）
不可审核 · 有独立的 connector-meta.json
不可鉴权 · 有明确鉴权方式（oauth/token/none）
不可撤销 · 用户可随时断开连接
不可观测 · 有图标、名称、描述、示例
· 需通过审核进入市场
### 2.5.3 AgentTool 与 SendMessage 的特殊性
注意工具表里两条带括号说明的：
> |AgentTool |调用其他 Agent（主理人可用）|\
> |SendMessage |发送消息（主理人可用）|
**只有主理人能用。** 这是一个极强的架构信号：它意味着平台的多 Agent 模型是**中心化的星型拓扑**，不是对等的网状拓扑。
星型（平台采用的） 网状（平台禁止的）
主理人 A ←──→ B
╱ │ ╲ ╲ ╱
A B C ╲ ╱
（A/B/C 之间不直连） C ←─ （A/B/C 互相直连）
下一节会解释这个拓扑为什么被强制。
## 2.6 为什么专家团要有 settings.json + teamInfo + 主理人中转
### 2.6.1 专家团比专家多了什么
对比目录结构：
| | |
| --- | --- |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
多了四样东西：`settings.json`（必须）、`teamInfo`（必须）、`members` 数组（必须）、`skills/` 共享目录。
**为什么多一个专家团就必须多一个 `settings.json`？** 因为专家团引入了一个专家没有的东西：**需要被持久化的编排状态**。
单个专家是无状态的——每次召唤，加载 Agent 定义文件，开始对话。但专家团有"谁在指挥"这个问题，这个信息必须在一个专门的配置文件里声明，运行时才知道该把控制权交给谁。
### 2.6.2 三重声明：为什么主理人要被声明三次
官方要求主理人在三个地方出现：
```jsonc
```jsonc
// 1. plugin.json —— 主 Agent 名称
"agentName": "trading-team-lead",
// 2. plugin.json —— teamInfo 指定主理人
"teamInfo": {
"leadAgent": "trading-team-lead",
"memberAgents": ["market-analyst", "fundamentals-analyst", "..."]
},
// 3. members 数组中用 role 标记
"members": [
{ "id": "trading-team-lead", "name": {...}, "profession": {...}, "avatar": "...", "role": "lead" },
{ "id": "market-analyst", ..., "role": "member" }
]
再加上 `settings.json`（用于设置主理人）。
**为什么要重复声明四次？** 因为它解决的是四个不同的问题：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**实操陷阱**：这四个地方必须指向同一个 Agent。最常见的失败是 `agentName` 写了 `team-lead` 而 `teamInfo.leadAgent` 写了 `trading-team-lead`，或者 `members` 里有两个 `role: "lead"`。
另一条官方强调的命名规则：
> `agents/{team}-team-lead.md`（主理人名称须加专家团前缀，不可用通用 team-lead）
**为什么？** 因为 Agent 名称在平台上是需要区分的标识。如果所有专家团的主理人都叫 `team-lead`，那么：
- 日志与遥测无法区分是哪个团队的主理人。
- 若未来支持跨团引用，会命名冲突。
- 主理人 Agent 文件在解压与注册时可能与其他团冲突。
所以官方强制 `{team}-team-lead` 这个命名模式——`trading-team-lead`、`legal-team-lead`、`design-team-lead`。
### 2.6.3 主理人编排 vs 并行 subagent
官方文档里那段"团队协作机制（铁律）"是整个平台最值得逐字读的段落：
> 你必须走正式的**团队协作流程**，严禁简化或跳过：
>
>
>
>
> 1.
> **建立团队**：任务开始时由主理人亲自创建本次任务的团队（建议命名 `trading-<标的简称>`），明确本次协作的边界与上下文。**团队创建（TeamCreate）必须且只能由主理人执行，严禁委派任何成员创建团队**
>
>
>
> 2.
> **调度成员**：按 SOP 阶段将每位团队成员拉入协作、下发独立任务；团队成员作为独立协作方基于分析任务输出专业产出，不得由主理人代写
>
>
>
> 3.
> **消息中转**：成员的产出需回传给你，由你汇总、转交给下一阶段成员；所有跨成员的信息流必须经主理人中转，不得互相直连
>
>
>
> 4.
> **成员结论为准**：任何专业产出（技术分析/财报分析/多空论证/风险诊断/交易决策）必须由对应成员输出后再采信，主理人只做编排与汇编
>
>
>
> ###
> 严禁行为
>
>
>
>
> -
> ❌ 禁止跳过"建立团队"的正式流程，直接自己模拟成员发言或并行写出多角色内容
>
>
>
> -
> ❌ 禁止自己代写任何团队成员的专业产出
>
>
>
> -
> ❌ 禁止未完成前序阶段就跳到后续阶段
>
>
>
> -
> ❌ 禁止让成员互相直连通信，所有跨成员信息流必须经主理人中转
>
>
>
> -
> ❌ 禁止 spawn 主理人自己
**为什么平台要禁止"并行 subagent"这种看起来更高效的做法？**
对比两种模式：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
最后一行是**最关键的一条**，也是为什么官方要写进"严禁行为"而不是"建议"。
**"禁止跳过建立团队的正式流程，直接自己模拟成员发言或并行写出多角色内容"** —— 这条禁令针对的是什么？是针对模型的一个已知倾向：**在"上下文压力大"或"任务看起来简单"时，LLM 会偷懒，直接扮演多角色写一段对话，而不是真的去 spawn 多个 Agent。**
从 token 经济角度看，这个偷懒"很合理"——模拟 12 个角色写一段对话，可能只要 3000 token；真去 spawn 12 个 Agent，每个都要独立的上下文、独立的工具调用，成本是前者的几十倍。
**但偷懒的代价是：那份"专家团产出"实际上是单个模型的单次输出，完全失去了多 Agent 的意义。** 你花大力气设计的多空辩论、三方风险评估，变成了同一个模型在同一时刻的自言自语——它不会真的产生分歧，因为一个模型在同一上下文里对自己辩论，结果必然是"双方都有道理"式的和稀泥。
官方甚至预判到了这个后果，在协作规则里写：
> 1.
> **决策果断**：研究主管和风险主管必须给出明确 Buy/Sell/Hold，不得以"双方都有道理"为由默认 Hold
**这条规则就是"和稀泥检测器"。** 如果最终结论总是 Hold，说明主理人在偷懒模拟而不是真的调度。
### 2.6.4 maxTurns 200 vs 50：编排成本的量化证据
Agent 定义文件的 frontmatter 有一个 `maxTurns` 字段：
> |maxTurns |否 |最大对话轮数（默认 50）|
官方示例里：
- 主理人 `trading-team-lead`：`maxTurns: 200`
- 成员 `market-analyst`：`maxTurns: 50`
**这个 4 倍的差距，是理解多 Agent 成本结构的直接证据。**
一个 13 人的专家团，主理人要完成 5 个阶段：
Phase 1: 并行调度 4 个分析师（market / fundamentals / news / sentiment）
Phase 2: bull + bear 辩论 → research-manager 综合 （3 次调度）
Phase 3: trader 决策 （1 次调度）
Phase 4: 并行 3 个风险分析师 → risk-manager 综合 （4 次调度）
Phase 5: 汇编最终报告
────────────────────────────────────────────────────
合计：12 次成员调度 + 5 次阶段汇总 + 团队创建 + 最终报告
每一次调度至少占用主理人 2 轮（下发任务 + 接收回传），加上阶段间的汇总与进度通报，**保守估算主理人需要 12×2 + 5×2 + 若干 = 40 轮以上**。而每个成员只需 1 次任务执行，通常几轮工具调用就能完成，50 轮是充裕的。
**这就是 200 vs 50 的由来**：主理人的轮次消耗与成员数量近似线性相关，成员自己的轮次消耗只与自己的任务复杂度相关。
由此推出一条设计规则：
> **成员数量每增加 1，主理人的 maxTurns 至少要预留 4–6 轮的余量。**
如果你的专家团有 20 个成员，主理人 200 轮很可能不够，需要上调。反之，如果你只有 3 个成员却把主理人设成 200，那是浪费——轮次上限也是一种资源占用。
### 2.6.5 主理人 prompt 的最小骨架
基于官方示例，一个合格的主理人 Agent 定义文件至少要有五个部分：
```markdown
```markdown
---
name: {team}-team-lead
description: {英文描述，说明这个团队做什么、何时激活}
displayName:
en: "..."
zh: "..."
profession:
en: "..."
zh: "..."
maxTurns: 200
---
# {团队名} - 主理人
## 一、角色边界（必须写）
你**不直接做 XX 分析**，而是：1) 确认目标 2) 按阶段调度 3) 收集产出 4) 整合报告。
## 二、团队协作机制（铁律）（必须照抄官方五条）
1. 建立团队：TeamCreate 只能主理人执行...
2. 调度成员：按 SOP 阶段下发独立任务...
3. 消息中转：所有跨成员信息流经主理人...
4. 成员结论为准：专业产出必须由对应成员输出...
### 严禁行为
- ❌ 禁止跳过建立团队流程直接模拟成员发言
- ❌ 禁止代写成员产出
- ❌ 禁止未完成前序阶段就跳后续
- ❌ 禁止成员直连通信
- ❌ 禁止 spawn 主理人自己
## 三、团队成员表（必须写，供调度时参照）
| 成员 id | 名字 | 职责 | 所属阶段 |
## 四、标准工作流程 SOP（必须写）
### Phase 1: ...（并行调用哪些成员）
### Phase 2: ...
### Phase N: 最终报告
## 五、协作规则（建议照抄官方六条 + 补充）
1. 正式团队协作流程
2. 信息传递：每阶段结束将完整产出原文传给下一阶段
3. 进度通报：每完成一个阶段向用户简要通报
4. 语言一致：输出使用与用户相同的语言
5. 子任务命名：调度时在 Agent 工具的 name 参数传入角色名称（中文）
6. 决策果断：不得以"双方都有道理"为由默认中立
**五个部分缺一不可**。缺少"角色边界"，主理人会自己去干活；缺少"严禁行为"，主理人会偷懒模拟；缺少"成员表"，调度会遗漏；缺少"SOP"，阶段顺序会乱；缺少"协作规则"，产出质量不稳定。
## 2.7 为什么连接器有 MCP + Skill 与 CLI + Skill 两条路线
### 2.7.1 官方的方案选择表
> |方案 |适用场景 |说明|\
> |MCP + Skill（推荐） |已有 API 服务，或可以开发 MCP Server |基于 MCP 协议暴露工具；远程服务优先采用 HTTPS 的 SSE 或 streamableHttp|\
> |CLI + Skill |已有成熟的命令行工具 |WorkBuddy 负责安装和调度 CLI；CLI 自行管理登录态和凭证|
>
>
>
>
>
> 如果服务可以通过网络 API 提供能力，优先选择 MCP + Skill；只有在已有稳定、跨平台 CLI 的情况下，才选择 CLI + Skill。一个连接器只能选择一种方案，二者不可混用。
### 2.7.2 关键差异：工具发现协议的有无
对比两条路线的目录要求：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**为什么一个可选、一个强烈推荐？官方文档给了明确答案：**
> CLI 工具没有标准的工具描述协议，AI 需要依赖 Skill 了解可用命令和参数，因此本方案强烈推荐提供 Skill 文件。
这一句话揭示了连接器的底层逻辑：
MCP 协议 = 传输 + 工具发现（tools/list）+ 工具调用（tools/call）
↑
有标准工具描述：工具名、参数 schema、返回值说明
→ AI 自己就知道有什么工具、怎么用
→ Skill 只是"锦上添花"（补充使用策略、错误处理、高风险确认规则）
CLI = 只有进程执行，没有协议
↑
无工具描述：AI 不知道这个 CLI 有哪些子命令、参数是什么
→ 必须由 Skill 告诉 AI
→ Skill 是"必需品"
**这就是"工具发现协议（MCP 有、CLI 无）决定 Skill 是否必需"的完整推理。**
### 2.7.3 由此推出：Skill 在连接器里到底该写什么
官方明确了 Skill 的编写重点：
> -
> 每个 MCP Tool 或 CLI 命令的用途；
>
>
>
> -
> 参数名称、类型、是否必填和默认值；
>
>
>
> -
> 典型调用示例及返回格式；
>
>
>
> -
> 认证前置条件、错误场景和恢复方式；
>
>
>
> -
> 高风险操作需要的确认规则。
对 MCP 方案和 CLI 方案，这五条的权重不同：
| |
| |
| |
| |
| |
| |
| |
**一个 CLI 连接器的 SKILL.md 正例骨架**：
```markdown
````markdown
---
name: your-cli-usage
description_zh: 使用 your-cli 管理线上服务：查询服务列表、查看实时日志、执行灰度发布。当用户提到"查下服务状态""看看日志""发布到灰度"时使用
description_en: Manage services with your-cli: list services, tail logs, roll out canary releases.
version: 1.0.0
author: 你的主体名称
---
# your-cli 使用说明
## 前置条件
- 连接器已完成安装与登录（首次使用会引导执行 `your-cli auth login`）。
- 若命令返回 `UNAUTHORIZED`，说明登录态失效，提示用户重新连接连接器，不要反复重试。
## 可用命令
### 1. 查询服务列表
```bash
your-cli service list --env {prod|staging}
-
`--env`：必填，环境标识。
-
返回：JSON 数组，每项含 `name`、`status`、`replicas`、`version`。
-
**注意**：输出可能很长，只提取用户关心的字段，不要整体粘贴给用户。
###
2. 查看实时日志
```bash
```bash
your-cli logs tail --service {服务名} --lines {行数} --since {5m|1h|24h}
-
`--lines`：可选，默认 100，**最大 500**。
-
`--since`：可选，默认 5m。
-
返回：纯文本日志行。
###
3. 执行灰度发布
```bash
```bash
your-cli deploy canary --service {服务名} --version {版本号} --percent {1-100}
-
**高风险操作**：执行前必须向用户复述「服务名 + 版本号 + 灰度比例」并等待明确确认。
-
未获确认前不得执行。
##
错误处理
| |
| |
| |
| |
| |
### 2.7.4 为什么"一个连接器只配置一个 MCP Server"
官方要求：
> 一个连接器只配置一个 MCP Server。
以及：
> |mcpServers |必填 |基础 |顶层配置；仅配置一个 Server|
**为什么？** 从市场层的设计可以推出来：
1. **连接器的身份粒度是"一个服务"。** `connector-meta.json` 有 `source`（全局唯一标识）、`name`、`description`、`icon.svg`。一个连接器 = 一个图标 = 一个授权实体。如果一个连接器挂两个 Server，用户看到的是一个图标对应两个完全不同的服务，授权与断开的语义就混乱了。
2. **OAuth 的 redirect_uri 是绑定 source 的。** 官方给出的回调地址是 `workbuddy://workbuddy/mcp/connector%3A/oauth/callback`——注意 `%3A`，回调地址里编码了 source。如果两个 Server 各自要 OAuth，无法区分。
3. **失败隔离。** 一个 Server 挂了导致整个连接器不可用 vs 两个独立连接器各自独立——后者显然更好。
**推论**：如果你有多个 MCP Server 要接，正确做法是**提交多个连接器**，而不是塞进一个。这也解释了为什么 `source` 要求"全局唯一"。
### 2.7.5 凭证注入的三种路径与它们的底层差异
官方给了四种认证场景：
| 场景 | 方式 | 是否打开浏览器 | 凭证存储位置 |
|---|---|---|---|
| MCP Server 自带 OAuth 或无需认证 | `auth_mode` 省略 | 需授权时会打开 | 由 MCP Server / 平台管理 |
| WorkBuddy 云端托管 OAuth | `auth_mode: server-side` 或 `gateway` | 需授权时会打开 | WorkBuddy 云端 |
| 用户自填 Access Token / API Key | `auth_mode: "token"` + `token-schema.json` | **不打开** | **仅用户本机，不经过云端** |
| CLI 登录 | `cli.json` 的 auth/status/unAuth | 取决于 CLI | CLI 自行管理 |
**这里有一个非常值得注意的设计：`token` 模式明确写了"不经过云端"。**
官方原文：
> WorkBuddy 会弹出表单收集凭证，凭证仅保存在用户本机并在连接时注入，不经过云端，整个过程不打开浏览器。
这是一个**信任边界的主动收缩**。平台放弃了"把凭证存云端，多端同步"的便利，换取"凭证永远不会离开用户机器"的安全承诺。
从安全工程角度，这个选择意味着：
- 平台无法代用户调用这些服务（无服务端凭证）。
- 用户换机器需要重新填一次凭证。
- **但凭证泄露的影响面被限制在单台机器。**
对于金融、医疗、企业内部系统这类对凭证极度敏感的场景，`token` 模式是唯一可接受的选择。这也提示了它的典型使用姿势：
```jsonc
// mcp.json —— 用 ${VAR} 占位，绝不写实值
{
"mcpServers": {
"your-service": {
"type": "streamableHttp",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${SERVICE_TOKEN}" },
"timeout": 30000
}
}
}
```jsonc
```jsonc
// token-schema.json —— 描述表单，key 必须与 ${VAR} 完全一致（区分大小写）
{
"title": "服务对接配置",
"description": "连接您的账号以调用服务。凭证仅存储在本机 ~/.workbuddy 目录下。",
"docUrl": "https://example.com/docs/api-token",
"docLabel": "如何获取 Access Token？",
"fields": [
{
"key": "SERVICE_TOKEN",
"label": "Access Token",
"type": "password",
"required": true,
"placeholder": "在个人中心 → 开放平台 → API 中生成",
"description": "用于访问服务 OpenAPI 的个人访问令牌。"
}
]
}
**三个必死的坑**（都来自官方明确的约束）：
1. `${SERVICE_TOKEN}` 与 `fields[].key` 的 `SERVICE_TOKEN` **大小写不一致** → 占位符不会被替换，连接必然失败。
2. 敏感凭证的 `type` 写成 `text` 而不是 `password` → 违反"敏感凭证一律使用 password"。
3. 用了 `auth_mode: "token"` 但没声明 `minWorkbuddyVersion` ≥ 4.23.0 → 低版本客户端不认识这个字段。
### 2.7.6 CLI 方案的致命约束：auth 子进程会被终止
官方文档里有一条极其重要、也极其容易被忽略的约束：
> 关键约束：WorkBuddy 在提取到认证 URL 后会立即终止 auth 子进程，因此 auth 子进程本身不能作为 OAuth 回调的接收方。
配套的时间参数：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
**"auth 只有 10 秒"是理解 CLI 认证设计的钥匙。**
10 秒意味着 auth 命令**根本不能等待用户完成授权**——用户在浏览器里登录、输验证码、点同意，至少几十秒。auth 命令唯一能做的是：**在 10 秒内把认证 URL 打印到 stdout/stderr，然后退出。**
这就必然导致"auth 子进程不能作为 OAuth 回调接收方"——因为进程在 URL 一输出就被终止了，回调到来时它已经不在了。
官方给了三个方案：
| | | | |
| --- | --- | --- | --- |
| | | | |
| | | | |
| | | | |
**为什么 Device Code Flow 被标为"推荐"？** 因为它与平台的调度模型天然契合：
平台调度模型：
auth（10s，输出 URL 即退出）→ 平台打开浏览器 → 每 3 秒轮询 status（最长 5 分钟）
Device Code Flow：
auth 输出验证页 URL + user_code → 用户在别处输入 code → CLI 后台轮询换取 Token
↓
status 检测到已登录 → 平台判定连接成功
整个过程不需要本地监听端口，不需要回调地址，不需要常驻进程。**它是唯一一个"不违反任何平台约束"的方案。**
如果你在做 CLI 连接器，且认证服务端支持 Device Code Flow，**不要犹豫，直接选它**，并在 `cli.json` 中配置 `authDeviceFlow`（最低版本 5.0.0）。
### 2.7.7 auth 命令输出的四个硬性要求
> -
> 在 stdout 或 stderr 中输出完整的 https:// 认证 URL，并在 10 秒内输出；
>
>
>
> -
> URL 前后需有空白字符分隔，不能被引号或尖括号包裹，否则会被截断；
>
>
>
> -
> 不得进入交互式输入等待（执行环境没有 TTY），也不应自行打开浏览器而不输出 URL。
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
**"URL 可预先构造，无需网络往返"** 是最实用的一条：auth 命令不要先调接口拿 URL 再打印，而应该**本地拼好 URL 立即打印**，把网络请求放到 status 轮询里去。
## 2.8 token 经济学：一次对话的上下文账本
### 2.8.1 一次对话的完整账本
把一个"用户召唤专家团分析一只股票"的任务拆开，看 token 都花在哪（**全部为估算值，平台未公布**）：
| | | | |
| --- | --- | --- | --- |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
**粗算**：一次 13 人专家团的完整分析，token 消耗量级在 **10 万级**。其中：
- Agent 定义文件（人格）占比约 **10%**
- 工具调用结果占比约 **50–60%**
- 中转与汇编占比约 **20%**
- 输出占比约 **10%**
**结论：在多 Agent 场景下，人格定义不是成本大头，工具调用结果才是。**
### 2.8.2 这条结论的三个实操含义
**含义 1：优化上下文，优先优化工具返回，而不是精简提示词。**
很多人花大力气把 Agent 定义文件从 2000 字压到 1500 字（省 500 token），却放任一次 MCP 调用返回 20KB JSON（约 6000 token）。**方向错了。**
正确的做法是：
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
**含义 2：Agent 定义文件可以写得详细，不用过度压缩。**
因为人格定义只占总消耗的约 10%，把主理人的 SOP 写清楚、把"严禁行为"写全，带来的质量提升远大于它的 token 成本。**吝啬提示词而浪费工具返回，是新手最常见的错误。**
**含义 3：成员数量与 token 消耗近似线性，但有阶梯。**
成员数 3 → 主理人约 30–50 轮
成员数 6 → 主理人约 60–90 轮
成员数 13 → 主理人约 120–200 轮 （官方示例给 200）
成员数 20+ → 主理人 200 可能不够，需上调
每增加一个成员，成本增量 = 该成员的 Agent 定义 + 该成员的工具调用 + 产出回传 + 主理人 2 轮调度。**所以"多加一个视角"不是免费的，要判断这个视角带来的质量提升是否值这个成本。**
### 2.8.3 maxTurns 的真实含义
官方定义：
> |maxTurns |否 |最大对话轮数（默认 50）|
**"轮"在这里指什么？** 官方未明确定义。从 Agent 的运行模型推理，一轮（turn）最可能指**一次模型推理 + 其后的工具调用与结果回填**的完整循环。
**这个字段是"上限"而不是"目标"。** 它有三个作用：
| | |
| --- | --- |
| | |
| | |
| | |
**所以 maxTurns 被打满是一种故障信号，不是正常的完成方式。** 如果你发现主理人经常跑到 200 轮上限，正确的处理不是把上限调到 400，而是：
1. 检查是否有成员反复失败重试（工具调用错误未处理）。
2. 检查阶段划分是否合理（是否阶段太多、每阶段成员太多）。
3. 检查是否有信息重复中转（每阶段都把全部历史传给下一阶段，导致上下文膨胀与轮次浪费）。
### 2.8.4 上下文压缩工程与资产设计的相互作用
平台承诺了"上下文压缩工程"，但压缩是有损的。这对资产设计有三条直接影响：
| | |
| --- | --- |
| | |
| | |
| | |
第三条尤其值得展开：**在长流程的专家团里，用文件而不是上下文来传递中间产出。**
❌ 差的做法：主理人把成员 A 的 5000 字产出原文塞进给成员 B 的任务描述里
→ 主理人上下文 +5K，成员 B 上下文 +5K，且压缩后可能变形
✅ 好的做法：成员 A 用 Write 把产出写到 out/phase1-market.md
→ 主理人告诉成员 B："读取 out/phase1-market.md 作为输入"
→ 主理人上下文 +0.1K，成员 B 自己 Read（+5K，但用完即弃）
这个技巧在 10 人以上的专家团里能显著降低主理人的上下文压力，从而减少轮次消耗。
## 2.9 资产设计者必须理解的三条底层约束
到这里，可以把全章的推理收敛成三条约束。**后面所有章节的设计决策，都是这三条约束的推论。**
### 约束一：上下文是稀缺且不可由你管理的资源
**内容**：
- 你的资产内容按 L0（frontmatter）→ L1（正文）→ L2（references/脚本输出）三级渐进进入上下文。
- 你无法控制上下文窗口大小、压缩策略、记忆注入时机——这些由底座层负责。
- 你唯一能控制的是：**你的资产每个部分有多长、什么时候被加载**。
**它决定了**：
- 为什么 `description` 必须写触发词（它是 L0 唯一内容）。（→ 2.3.2）
- 为什么 `references/` 要拆小文件而不是一个大文件。（→ 2.4.1）
- 为什么脚本输出必须裁剪。（→ 2.4.2）
- 为什么 Agent 定义文件不必吝啬（它只占约 10%）。（→ 2.8.2）
- 为什么专家团要用文件传递中间产出。（→ 2.8.4）
- 技能写作的篇幅规范。（→ 第 05 章）
**违反它的典型症状**：技能不触发 / 误触发；长任务后期质量下降；上下文溢出导致任务失败。
### 约束二：能力可枚举性是安全与可审核性的前提
**内容**：
- 专家的工具集是固定的九个，开发者不可添加。
- 自定义能力必须通过 MCP 连接器接入，而连接器有独立的元信息、鉴权、图标、审核。
- 多 Agent 拓扑是星型，只有主理人能用 AgentTool / SendMessage。
**它决定了**：
- 为什么不能自定义 tools。（→ 2.5.1）
- 为什么 MCP 是唯一的能力扩展出口。（→ 2.5.2）
- 为什么一个连接器只能配一个 MCP Server。（→ 2.7.4）
- 为什么凭证不能硬编码、必须走 OAuth 或 Token 表单。（→ 2.7.5）
- 为什么主理人必须存在且唯一。（→ 2.6.3）
- 为什么违规处置是梯度式的、且能做到资产级下架。（→ 第 04 章）
**违反它的典型症状**：审核被拒（凭证硬编码、诱导越权）；专家行为不可预测；多 Agent 产出互相矛盾。
### 约束三：编排的真实性无法由提示词保证，必须由结构强制
**内容**：
- LLM 在上下文压力大时会倾向于"模拟"多角色而非真实调度。
- 平台用三重结构强制编排真实发生：`settings.json` + `teamInfo` + `members[].role` + 主理人铁律。
- `maxTurns` 是编排成本的量化旋钮：主理人 200（随成员数线性增长），成员 50（与成员数无关）。
**它决定了**：
- 为什么专家团必须多一个 `settings.json`。（→ 2.6.1）
- 为什么主理人要被声明四次。（→ 2.6.2）
- 为什么禁止主理人代写成员产出、禁止成员直连。（→ 2.6.3）
- 为什么主理人 maxTurns 远大于成员。（→ 2.6.4）
- 专家团的 SOP 设计规范与成员职责划分原则。（→ 第 07 章）
**违反它的典型症状**：专家团产出总是"和稀泥"；专业结论无法归因；成员职责重叠导致重复劳动。
### 2.9.1 三条约束的交叉验证表
用这三条约束去检验一个资产设计决策，是个很好用的工具：
| | | | | |
| --- | --- | --- | --- | --- |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
## 小结
本章从五项底座能力出发，完成了四件事：
1. **建立了分层架构认知**：端侧 → 市场层 → 资产层 → Harness 层 → 底座层。你的可控域只有资产层（以及 Buddy 应用的 Harness 层），底座层的五项能力既改不了也不该改。
2. **推导了渐进式披露机制与上下文预算模型**：L0（frontmatter 常驻）→ L1（正文命中加载）→ L2（references/脚本输出按需读取）。据此给出了技能篇幅、references 拆分、脚本输出裁剪的具体规则。**所有 token 数值均为估算，平台未公布。**
3. **解释了每一个"奇怪"的规范约束**：三个子目录对应知识分页 / 确定性执行 / 产出骨架三种策略；统一工具权限是为了能力可枚举（MCP 是唯一出口）；主理人机制是为了强制编排真实发生（maxTurns 200 vs 50 是其量化证据）；连接器双路线的分野在于有没有工具发现协议。
4. **收敛出三条底层约束**：上下文稀缺且不可由你管理、能力可枚举性是安全与可审核性的前提、编排真实性必须由结构强制。
## 检查清单
在进入第 03 章之前，请自查：
我能画出或复述平台的五层架构，并说清每一层的负责方吗？
我能解释为什么 `description` 必须写触发词，并用"动作 + 产出 + 触发场景"三段式重写我技能的 description 吗？
我的 `SKILL.md` 正文是否控制在合理长度？核心判据是否在正文里（而不是只在 references 里）？
我的 references 文件是否按主题拆分（单文件 ≤300 行）？正文里是否写清了"什么情况下读哪一页"？
我的 scripts 输出是否做了裁剪？是否从环境变量读凭证而不是硬编码？
我的 templates 是否只保留结构与占位符，且标注了可省略项？
做专家团时，`agentName` / `teamInfo.leadAgent` / `members[].role: "lead"` / `settings.json` 四处是否指向同一个 Agent？主理人文件名是否带了团名前缀？
我的主理人 Agent 定义文件是否包含完整的五个部分（角色边界 / 铁律与严禁 / 成员表 / SOP / 协作规则）？
我是否理解 maxTurns 是上限而非目标？主理人的 maxTurns 是否按成员数做了调整？
做连接器时，我是否知道自己的方案下 Skill 是"可选"还是"必需"？如果是 CLI 方案，我的 SKILL.md 是否列出了全部命令与参数？
我是否在任何文件里都没有硬编码真实凭证？
我能否用 2.9.1 的交叉验证表检验自己的每一个设计决策？
## 下一步
第 03 章将用 **「能力 = 知识 + 工具 + 人格 + 编排」** 这个四维模型，把技能、专家、专家团、连接器四类资产放到同一个坐标系里比较，并给出组合模式图谱、决策矩阵，以及五个高频反模式的症状—后果—修正。**本章讲的是"为什么规范是这样"，下一章讲的是"因此你应该选哪个"。**
本篇章目标： 1. 建立统一分析模型「能力 = 知识 + 工具 + 人格 + 编排」，并用它精确拆解技能、专家、专家团、连接器各自占据哪些维度。 2. 通过九维度大对比表，掌握四类资产在粒度、触发、状态、并行性、交付难度、审核难度、维护成本、复用性、适用团队规模上的差异。 3. 掌握 8 种组合模式图谱，并能用四判断题决策矩阵为自己的 know-how 定位正确形态。 4. 识别并规避 5 个高频反模式——这些错误在真实项目中出现率极高，且往往到提审或上线后才暴露。
四类资产看起来是完全不同的东西：一个是 Markdown，一个是带头像的角色，一个是多角色组织，一个是后端服务。但用下面这个四维模型去看，它们是同一个坐标系里的四个点。
图例：●●● 核心维度｜●●○ 重要但非核心｜●○○ 有但不重要｜○○○ 基本无
结论 1：技能与连接器是"互补的两半"。\ 技能有知识没工具，连接器有工具没知识。这解释了为什么官方的连接器目录里两种方案都带一个 skills/ 子目录——连接器需要技能告诉 AI 怎么用这些工具，技能需要连接器拿到外部数据。它们是天生的搭档。
结论 2：专家 = 技能 + 人格。\ 一个专家如果不绑定任何技能，它只有人格没有方法，产出会飘。官方在 Agent 定义文件里留了 skills 字段（"预加载的技能名称列表"）正是为此。专家的能力下限由人格决定，能力上限由它预加载的技能决定。
结论 3：专家团 = 专家 × N + 编排。\ 编排是这个维度里唯一"不可由单个资产独立存在"的维度——它必须依附于至少两个 Agent。这解释了为什么专家团是四类资产里唯一需要 settings.json 的（第 02 章 2.6.1 已述）。
结论 4：四类资产构成一条完整的组合链，而不是四个互斥选项。
知识 ──── 技能 ────┐ ├──→ 专家 ────┐ 工具 ──── 连接器 ───┘ ├──→ 专家团 ───→ Buddy 应用 │ 人格 ─────────────────────────────┘ 编排 ─────────────────────────→
实战含义：大多数真实项目不是"选一个"，而是"选一条链上的一段"。第 3.4 节的组合模式图谱会展开。
周期估算说明：以上为作者基于工程经验的估算，平台未公布官方周期，实际取决于团队熟悉度与领域复杂度。
技能的粒度是"一个任务"，这是所有资产里最小的可复用单元。粒度越小，复用面越广，但单次价值越低。
判断标准：一个技能的粒度是否合适，看它能否在一句话里说清"输入是什么、输出是什么"。说不清就是太粗；能被模型零指令完成就是太细。
这一点常被忽略。对比四类资产：
这意味着技能是唯一能"无感嵌入用户日常对话"的资产形式。 用户不需要记得你，只要说出那类需求，你就被唤起。
反过来，这也是技能的两个专属开关存在的原因：
user-invocable: false 是专家团共享技能的典型配置——那些技能是给成员 Agent 用的，不该出现在用户的技能列表里。
专家团的"阶段进度"是一个被低估的能力。 因为主理人持有阶段状态，所以专家团能做到技能做不到的事：中途插入、阶段回退、部分重做。
举例：一个 5 阶段的投研专家团，用户在 Phase 3 说"Phase 1 的数据好像有问题，重新查一下"。主理人可以只重跑 Phase 1 并把新数据传给 Phase 2/3，而不必从头开始。这是编排维度带来的真实价值，不是花架子。
"并行"是专家团最硬核的价值，但它有前提：并行的成员之间必须没有依赖。官方 SOP 的 Phase 1 四个分析师可以并行，是因为技术面、基本面、新闻面、情绪面互不依赖；而 Phase 2 的 bull/bear 辩论必须在 Phase 1 之后，research-manager 又必须在 bull/bear 之后。
设计规则：画一张依赖图，没有入边的成员可以并行，有入边的必须等待。这张图决定了你的阶段划分。
审核难度同理：连接器的官方"提交前检查"有 12 条，是四类资产里最详细的一份。这 12 条里大部分是安全与可用性项——因为连接器是唯一真的会碰用户数据和外部系统的资产。
连接器的维护成本最高，且退化是"硬失败"（直接不可用），不像技能是"软退化"（还能用但质量下降）。所以如果选了连接器路线，必须配运维。
这个结果可能反直觉——专家团看起来最"高级"，为什么复用性最低？
因为复用性 = 可被多少种上下文引用，而不是"能力多强"。
战略含义：如果你想在生态里建立长期影响力，应该投资底层可复用的技能与连接器，而不是顶层的专家团。专家团是一次完整的解决方案交付，而技能是能被复用几十次的零件。
下面给出 8 种组合模式。每种都标注：结构、适用场景、官方机制依据、典型例子、注意事项。
┌─────────────────┐ │ skills/xxx/ │ │ ├── SKILL.md │ ← 知识 │ ├── references/│ │ ├── scripts/ │ ← 用内置 Bash │ └── templates/ │ └─────────────────┘
┌──────────────────┐ ┌────────────────────┐ │ connector-meta │ │ skills/xxx/ │ │ mcp.json│cli.json│───────→│ └── SKILL.md │ │ icon.svg │ │ （说明怎么用工具） │ └──────────────────┘ └────────────────────┘ 工具 知识
┌──────────────────┐ │ agents/xxx.md │ ← 人格（+ 方法） │ skills: [a, b] │──────→ 预加载技能（知识） │ avatars/xxx.png │ └──────────────────┘
┌──────────────────┐ │ agents/xxx.md │ 人格 └────────┬─────────┘ ┌───────────┴───────────┐ ▼ ▼ ┌────────────────┐ ┌──────────────────┐ │ dependencies │ │ skills/（预加载） │ │ .connectors │ │ 知识 + 用法说明 │ │ .mcpServers │ └──────────────────┘ └────────────────┘ 工具
┌──────────────────────────────────────────────┐
│ my-team/ │
│ ├── agents/{team}-team-lead.md ← 编排 + 人格 │
│ ├── agents/member-a.md ... ← 人格 × N │
│ ├── skills/shared/ ← 共享知识 │
│ ├── .mcp.json ← 共享工具 │
│ └── settings.json ← 主理人 │
└──────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐ │ Buddy 应用（行业 Harness） │ │ ┌───────────┐ ┌───────────┐ ┌───────────────┐ │ │ │ 工作模式 │ │ 场景胶囊 │ │ 垂直行业市场 │ │ │ │ SysPrompt │ │ 场景级 │ │ · 专家/专家团 │ │ │ │ +Skill │ │ Harness │ │ · 技能 │ │ │ └───────────┘ └───────────┘ │ · 连接器 │ │ │ ┌───────────┐ ┌───────────┐ │ · 灵感案例 │ │ │ │ 模型配置 │ │内嵌已有功能│ └───────────────┘ │ │ │ 模型池+排序│ │ MCP Apps │ │ │ └───────────┘ └───────────┘ │ └─────────────────────────────────────────────────┘
┌──────────────┐ OAuth 2.1 ┌──────────────┐ │ 你的产品 │───────────→│ WorkBuddy │ │ │ 授权码流程 │ 开放平台 │ │ │←───────────│ │ │ │ Open API │ │ └──────────────┘ └──────────────┘ 你的界面编排 云端任务 / 本地助理 / 产物 / 兑换码
┌─────────────┐ │ 基础技能 A │←── 被 10 个专家引用 │ 基础技能 B │←── 被 3 个专家团共享 │ 基础技能 C │←── 被 1 个连接器配套 └─────────────┘
按顺序回答下面四个问题，即可定位形态：
案例 A：某律所想做"合同审查"能力
案例 B：某量化团队想做"个股投资分析"能力
案例 C：某企业想做"内部工单查询"能力
案例 D：某团队想把"本周热点总结"做成资产
这一节是本章最重要也最实用的一部分。下面五个反模式在真实项目中出现率极高，且往往到提审或上线后才暴露，返工代价巨大。
症状
后果
修正
判断标准很简单：你的核心价值是"做事的方法"还是"做事的人"？
修正后的正确结构：
模式 3：专家 + 技能 ├── 技能：financial-report-extract/ ← 纯方法，无人设 │ ├── SKILL.md（只写流程与判据） │ └── references/abnormal-rules.md └── 专家：finance-analyst/ ├── agents/finance-analyst.md ← 人设、视角、表达风格 │ └── frontmatter: skills: [financial-report-extract] └── avatars/expert.png
自检问题：如果把 SKILL.md 里的"你是一位……"整段删掉，这个技能还能正常工作吗？如果能，说明人设是多余的，应该移到专家里。
症状
displayName 是功能名而不是人名，比如 displayName.zh: "PPT 生成器"、profession.zh: "PPT 生成工具"。后果
修正
判断标准：这个资产需要一个"名字"吗？
注意官方示例里专家的 displayName 都是人名（Diana / 黛安娜 / Marco / Fiona / Nina / Stella / Bruno / Barry / Reed / Tyler / Aiden / Clara / Noel / Rex / 何执舟），profession 都是职业头衔（Design System Architect / Technical Analyst / Chief Strategist）。
如果你的 displayName 是个功能名，你大概率做错形态了。
症状
后果
修正
凡是"需要凭证才能访问的外部系统"，一律做成连接器。 正确的分层是：
❌ 错误： 专家（人设 + API 说明 + 让用户粘 Key）
✅ 正确： 连接器（mcp.json + 鉴权 + icon.svg） ↓ dependencies.connectors / dependencies.mcpServers 专家（人设 + 方法） ↓ 配套 技能（怎么用这个系统的工具）
官方给的连接器依赖声明方式：
```jsonc
// 方式一：plugin.json 内声明（推荐）
{
"dependencies": {
"mcpServers": "./.mcp.json",
"connectors": ["tencent-docs", "feishu"]
}
}
```jsonc
```jsonc
// 方式二：插件根目录 .mcp.json（plugin.json 未声明时的兜底）
{
"mcpServers": {
"your-service": {
"url": "https://your-service.example.com/mcp",
"x-workbuddy": {
"displayName": { "zh": "某某系统 MCP", "en": "Your Service MCP" },
"description": { "zh": "连接后可查询……", "en": "..." },
"icon": "./avatars/your-service.svg",
"auth": { "type": "oauth" }
}
}
}
}
**好处**：
1. 用户在召唤专家前会看到**内联引导卡片**，被逐个引导完成连接——这是官方提供的现成体验。
2. 连接后统一在「连接器 → 自定义连接器」中管理，用户可随时断开。
3. 已连接过的依赖再次召唤同名专家时**不会重复引导**。
4. 这个连接器可以被其他专家引用。
### 反模式 4：专家团成员职责重叠
**症状**
- 两个成员的 Agent 定义文件内容有大量重复段落（复制粘贴后只改了标题）。
- 两个成员的产出高度相似——同一个数据被分析两遍，结论几乎一样。
- 主理人的 SOP 里，Phase 1 和 Phase 2 的成员做着重叠的事。
- 用户的反馈是"报告很长，但好像很多内容是重复的"。
- 最终结论总是中立/和稀泥（官方协作规则第 6 条专门警告过这一点）。
**后果**
| | |
| --- | --- |
| | |
| | |
| | |
| | |
| | |
**修正**
**方法一：为每个成员写"不做什么"**
官方示例的成员 Agent 定义文件只写了"分析维度"和"输出格式"。但实践中，更有效的做法是**同时明确边界**：
```markdown
```markdown
---
name: fundamentals-analyst
description: Fundamentals analyst - analyzes financial statements, valuation models, industry comparison
displayName:
en: "Fiona"
zh: "Fiona"
profession:
en: "Fundamentals Analyst"
zh: "基本面分析师"
maxTurns: 50
---
# 基本面分析师 - Fiona
## 你负责
- 财报三表分析、估值模型、行业横向对比
## 你不负责（不要做）
- ❌ 不做技术面分析（K线、均线、技术指标）—— 由 market-analyst 负责
- ❌ 不做新闻与政策解读 —— 由 news-analyst 负责
- ❌ 不做市场情绪与资金流判断 —— 由 sentiment-analyst 负责
- ❌ 不给出最终买卖建议 —— 由 trader 与 risk-manager 负责
## 分析维度
1. ...
2. ...
## 输出格式
- ...
**"你不负责"这一节，是防止职责重叠最有效的手段。** 它比"你负责"更重要——因为模型倾向于"尽量多做"，明确禁止才能收住边界。
**方法二：用正交性检查表**
设计完成员后，逐对检查：
| | | | | | |
| --- | --- | --- | --- | --- | --- |
| | | | | | |
| | | | | | |
| | | | | | |
| | | | | | |
**判定标准**：如果两个成员在**相同输入**下用**相同方法**会得出**相同结论**——他们应该合并成一个成员。
**方法三：合并或拆分的量化参考**
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
**一个反直觉的建议：如果你的专家团少于 3 个成员，考虑用单个专家 + 多技能代替。** 两个成员的编排开销（主理人 + 成员 + 中转）相对于收益往往不划算。
### 反模式 5：把一次性任务做成资产
**症状**
- 这个需求只出现了一次（或一年一次）。
- 没有人能说清"下次什么时候会用"。
- 你在为一个非常具体的单次场景写通用逻辑（比如"2024 年 Q3 某项目复盘"）。
- 资产里包含了大量只适用于当前这一次的具体数据、具体人名、具体时间点。
- 做完之后没人负责维护它。
**后果**
| | |
| --- | --- |
| | |
| | |
| | |
| | |
**修正**
**判断标准：预期使用次数 × 单次节省时间 > 研发成本 + 维护成本？**
| | |
| --- | --- |
| | |
| | |
| | |
| | |
| | |
**如果确实要做，必须做"去具体化"处理**：
| | |
| --- | --- |
| | |
| | |
| | |
| | |
**自检问题**：把这个资产里的所有具体名词（时间、人名、公司名、路径）替换成占位符后，它还成立吗？如果不成立，说明它是一次性任务的包装，不是资产。
### 3.5.1 五个反模式速查卡
| | | |
| --- | --- | --- |
| | | |
| | | |
| | | |
| | | |
| | | |
## 3.6 从四维模型反推：怎么给资产定价（投入产出视角）
这一节不谈平台变现（平台未公布统一变现规则），只谈**投入产出比的自我评估**——帮你决定该在哪个资产上投入多少。
### 3.6.1 四类资产的投入产出特征
| | | | | | |
| --- | --- | --- | --- | --- | --- |
| | | | | | |
| | | | | | |
| | | | | | |
| | | | | | |
### 3.6.2 一个投入决策框架
第一步：算总拥有成本（TCO）
TCO = 首次研发 + 年维护 × 预期存续年数
第二步：算总收益
总收益 = Σ（单次节省时间 × 使用次数 × 单位时间价值）
+ 被其他资产引用带来的间接收益（难量化，但真实存在）
第三步：比较
总收益 / TCO > 3 → 值得做
总收益 / TCO 在 1–3 之间 → 做最小版本先验证
总收益 / TCO < 1 → 不做
**举例**：一个财报三表提取技能。
| | |
| --- | --- |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
**举例**：一个"年度战略复盘"专家团。
| |
| |
| |
| |
| |
| |
| |
| |
| |
**这个框架的真正价值在于：它会逼你把"使用次数"这个数字写实。** 绝大多数资产失败的原因是——立项时高估了使用次数。
## 小结
本章用「能力 = 知识 + 工具 + 人格 + 编排」这个四维模型统一了四类资产，得出五条核心结论：
1. **技能与连接器是互补的两半**（知识 vs 工具），所以连接器目录下必然带 `skills/`。
2. **专家 = 技能 + 人格**，所以 Agent 定义文件有 `skills` 预加载字段；专家的能力上限由它预加载的技能决定。
3. **专家团 = 专家 × N + 编排**，是唯一四维全占的形态，也是唯一需要 `settings.json` 与"阶段状态"的形态。
4. **复用性排序是：技能（5 处）> 连接器（4 处）> 专家 / 专家团（各 2 处）**。想建立生态影响力，投资底层可复用能力而非顶层方案。
5. **五个反模式**是真实项目中最常见的失败原因，其中"专家做成技能""技能做成专家""连接器做成专家"本质都是**维度错配**——把某个维度的需求放进了不承载该维度的容器里。
## 检查清单
我能用四维模型说清我的资产各占据哪些维度吗？
如果用四判断题（Q1 外部数据 / Q2 稳定人设 / Q3 多视角 / Q4 高频复用）重新走一遍，我的形态选择还是同一个吗？
我的技能里有没有混入人设描述？（反模式 1）
我的专家 `displayName` 是人名还是功能名？（反模式 2）
我有没有在专家/技能里让用户粘 API Key？（反模式 3）
我的专家团成员之间，是否都写了"你不负责"清单？做过正交性检查吗？（反模式 4）
我的资产里有没有写死具体时间、人名、路径？（反模式 5）
我的主理人 `maxTurns` 是否与成员数量匹配？
我是否计算过投入产出比，"使用次数"这个数字是否写实？
如果我的资产是连接器，`skills/` 是"可选"还是"必需"？（MCP 可选，CLI 强烈推荐）
## 下一步
第 04 章将转向合规维度，从入驻、资质、服务类目、开发者信息四个层面，反推平台合规体系的设计意图，并给出企业认证选型的决策表、认证失败 8 种场景的排查表、审核雷区的正反例对照，以及一份覆盖四类资产的「资产上线前自检 40 条」。**形态选错是返工，合规踩坑是下架——后者的代价更大。**
本篇章目标： 1. 理解平台合规体系的设计意图：为什么强实名、为什么要服务类目与资质、为什么违规处置是梯度式而不是一刀切。 2. 掌握主体模型（个人 vs 企业）与账号/主体的数量规则（10 / 50 / 1 的准确含义），并能为主体类型与认证方式做出正确选型。 3. 掌握开发者昵称、简介、头像、联系方式的审核雷区，每一条官方禁止项都配正反例，并识别高频踩坑点。 4. 拿到一份可直接使用的「资产上线前自检 40 条」，覆盖通用 / 技能 / 专家 / 连接器四组。
官方文档里散落着三组看似不相关的规定：
把它们放在一起，可以看出平台合规体系的三个设计意图。
为什么不放宽实名？ 因为平台上的资产有能力做真实动作。第 02 章已经说明，专家的内置工具包含 Read / Write / Grep / Glob / Bash / WebSearch / WebFetch——这意味着一个恶意资产有能力读写用户文件、执行任意命令、向外发送数据。
在这种能力边界下，"匿名开发者"是不可接受的风险。强实名解决的是三件事：
"一个身份证只能认证一个个人主体"这条规则的威力在于它的不对称性：你做一个资产的边际成本很低，但你失去这个身份的成本极高。这是典型的"提高作恶的机会成本"设计。
服务类目表不是平台自己发明的分类法，它直接对应中国的行业准入监管。证据就在配套的《法规依据及示例》文档里——每个类目下都给出了具体的政策法规条款：
这说明平台在设计服务类目时，做的是"把线下已有的行业准入许可，映射成线上的资质上传项"。
它的设计意图有三个：
1. 法律责任转移的完整性。 如果平台上有人提供法律服务但无证，平台作为分发方是有连带风险的。要求上传《律师执业资格证》，是把"平台审核义务"落实为可操作的动作。
2. 类目适用范围的精确约束，防止"挂羊头卖狗肉"。 注意每个类目都有一列"类目适用范围"和大量"注："。比如个人主体下的"教育服务 - 教育信息展示"：
仅适用于提供教育信息展示服务。注：该类目不支持提供教育视频播放/直播、课程产品销售等服务，建议去除。
这类"注："不是补充说明，而是边界声明——你选了这个类目，就必须把自己的能力裁剪到这个类目允许的范围内。这也是为什么很多资产被拒的原因是"类目适用范围不符"而不是"没资质"。
3. 个人主体与企业主体的能力差异，反映的是法律主体能力的差异。
对比两个版本的类目表：
这个差异不是平台歧视个人，而是法律事实：个人无法取得《快递业务经营许可证》《医疗机构执业许可证》《金融许可证》——这些许可证只发给法人组织。所以个人主体的类目表本质上是"个人在法律上能合法做的事"的清单。
官方的六档处置：
平台发现违规内容后，可视情况采取以下措施： - 将头像恢复为系统默认头像； - 使用兜底文案替代违规简介； - 隐藏违规联系方式； - 限制开发者主页展示； - 要求开发者修改后重新提交； - 对严重违规主体或能力采取下架等措施。
为什么不是"违规即下架"？
因为违规的严重程度差异极大：头像是默认生成的但内容不合适，和一个资产在窃取用户数据，是两件完全不同的事。一刀切下架会带来两个问题：
梯度式处置的精妙之处在于：前四档都是"局部可逆"的（头像、简介、联系方式、主页展示），第五档是"给你机会改"，只有第六档才是"全部剥夺"。这让开发者在每一个阶段都有"停下来整改"的动机，而不是"破罐破摔"。
另外一个细节值得注意：前四档是平台直接执行的（"将头像恢复为系统默认头像""使用兜底文案替代"），不需要开发者同意。这说明平台保留了即时止损权——发现违规内容可以立即停止其公开展示，不必等到开发者响应。
从官方规则可以还原出平台的数据模型：
账号（Account） ← 登录凭据，一个手机号/邮箱 │ │ 1 : N（每个账号最多认证 10 个企业主体） │ 1 : 1（每个账号最多创建一个个人主体） ▼ 主体（Subject） ← 法律意义上的责任归属 │ · 个人主体：绑定一个身份证 │ · 企业主体：绑定统一社会信用代码 + 法人 │ │ 1 : N ▼ 开放资产（Asset） ← 技能 / 专家 / 专家团 / 连接器 / Buddy 应用
核心规则：官方原文——"不同账号认证产生的主体、开放资产和其他资产相互独立"。
这句话的实操含义极其重要：如果你用 A 账号认证了公司甲，用 B 账号认证了公司乙，那么：
所以在注册之前就要想清楚账号规划，尤其是集团型企业、有多条业务线的公司。
关于 50 这个数字，必须澄清一个极易踩的坑：
"同一家企业最多可以被 50 个账号分别认证" 不等于 "这 50 个账号共享同一个企业主体的资产"。
因为前一条规则是"不同账号认证产生的主体、开放资产和其他资产相互独立"。所以第 2 个账号认证同一家企业时，创建的是另一个独立的主体实例（虽然背后是同一家法人企业），资产并不互通。
50 这个上限的真实作用是：给大企业里不同部门各自开号留空间（比如云团队一个号、文档团队一个号），同时防止有人用一家企业无限开号。
实操建议：
决策树：
你的资产需要金融/医疗/政务民生/房地产/文娱/电商/社交/汽车/资讯/深度合成 等类目吗？ ├─ 是 → 必须企业主体 └─ 否 ├─ 这是商业交付、要对外背书吗？ │ ├─ 是 → 建议企业主体（信任度 + 资产归属） │ └─ 否 → 个人主体可以，但注意身份证一旦用掉不可换号 └─ 你未来可能要转成企业吗？ ├─ 是 → 直接做企业主体（资产不能跨主体迁移） └─ 否 → 个人主体
最重要的提醒：资产不能跨主体迁移。 所以"先做个人试试，以后转企业"这条路的真实成本是"全部重做 + 重新审核"。如果有一丝可能商业化，一开始就做企业主体。
关键判断点：三种方式的第一步都是"上传营业执照 + OCR 识别 + 核对"，差别只在第三步的验证方式。所以选型只有一个问题要问："你的第三步能不能走通？"
Step 1：管理员实名认证
需要准备（官方原文）：本人中国大陆二代居民身份证号码；已完成实名登记的本人手机号；可以正常接收验证码的邮箱；可以正常完成人脸识别的手机。
Step 2：上传企业信息
官方流程：上传营业执照 → 系统 OCR 识别企业名称、统一社会信用代码、法定代表人姓名 → 核对识别结果 → 填写对外展示的开发者昵称 → 完成昵称命名规范校验。
Step 3：完成企业验证
认证成功后：系统生成企业主体，完成认证的账号成为该主体的超级管理员。
下表在官方"认证失败处理"表的基础上，补充了根因分析与预防措施。
补充三条官方表格未列、但实践中高频的失败原因（推理 + 经验）：
官方文档明确：
实名认证只采集认证所需信息。对外展示的头像、昵称、简介和联系方式需在"设置—开发者信息"中填写。
这句话很重要：实名信息（身份证、法人信息）不会对外展示，对外展示的是你自己在"设置—开发者信息"里填的内容。所以审核雷区全部集中在后者。
官方规则全文：
- 长度为 2—20 个字符； - 不得使用纯数字、纯空格、表情或不支持的特殊符号； - 不得包含敏感、违法或违禁内容； - 不得冒充官方、平台、客服或管理员； - 不得使用"官方、平台、客服、管理员、admin"等容易引起误解的表达； - 非腾讯内部主体不得冒充或仿冒腾讯系品牌； - 不得使用可能造成官方关联误解的腾讯系品牌名称； - 不得使用"认证、VIP、第一、独家、保证"等误导性背书； - 不得使用"测试、test、demo、试用"等测试性质名称。 昵称仅用于平台展示，不代表商标或品牌权利归属。昵称侵犯他人合法权益时，平台有权要求修改或收回。
官方规则：
开发者简介为必填项，长度为 20—120 个字符。简介应清楚说明个人、团队或企业的专业方向和主要资产，不得使用夸大、虚假或无法验证的宣传内容。
{主体名称}，专注{专业方向}。主要资产：{资产 1}、{资产 2}、{资产 3}。
示例：
远见投研，专注 A 股与港股基本面研究。主要资产：财报三表速读、行业对比分析、交易分析专家团。
这个模板的好处：同时满足"说清专业方向"和"说清主要资产"两个官方要求，且天然避免了夸大表述（因为你只是在陈述事实）。
官方规则：
开发者头像为必填项。主体创建后，系统根据开发者昵称生成默认头像，也可上传自定义头像替换。 - 尺寸：512×512 px； - 大小：不超过 5000KB； - 格式：JPG 或 PNG； - 内容不得包含违法、违规、侵权或误导信息。
⚠️ 高频错误：把专家头像的 500KB 限制记成了开发者头像的限制，或反之。最保险的做法是统一按 ≤500KB 准备所有头像，这样两边都能过。
官方规则：
联系方式会在开发者主页对外展示，支持官方网站、联系邮箱、微信公众号和自定义平台。 - 至少填写 1 项； - 最多填写 5 项； - 自定义平台可以填写平台名称和对应账号名称或账号 ID； - 不得填写违法、欺诈、侵权或与开发者无关的信息。
数量规则：1 ≤ 数量 ≤ 5。这是所有展示字段里唯一有上下限的——不能为空，也不能超过 5 个。
建议配置：
官方明确主页展示三部分：
注意最后一句："开发者主页的公开展示条件和入口状态以平台当期页面规则为准。"——这说明主页的可见性规则可能调整，不要把它当成永久承诺。
原则一：收到整改提示后立即处理。\ 官方明确："收到整改提示后，应及时修改违规内容并重新提交。整改通过后，相关信息才能恢复展示。"——注意"整改通过后……才能恢复"这个表述：在整改通过之前，你的内容一直是不展示状态。拖延 = 持续损失曝光。
原则二：L1–L3 是局部问题，L4 是系统性信号。\ 前三级只是替换掉某一个素材，说明平台认为你的问题局限在那个素材本身。一旦进入 L4（限制主页展示），说明平台认为你的整体信息有问题。此时不要只改被点名的那一项，要全量自查。
原则三：一次改对，不要反复试。\ 每一次整改提交都会进入平台的处理队列。反复提交不合规内容，不仅拖延恢复，也可能被视为整改态度不认真，加速升级。
与其等被处置，不如在填写时就避开。下面这张表把 4.4 节的所有禁止项压缩成一份填写前自查表：
下面的清单以官方给出的"提交前检查"（连接器文档，12 条）为基础，向前扩展到通用项、技能、专家三类，共 40 条。
说明：标 ⚑ 的条目直接对应官方文档明确要求；其余为基于规范推理与实践经验的补充项。平台未公布的细节，清单中不做硬性数值规定。
使用下表确认你的 minWorkbuddyVersion：
版本兼容行为的两个规则（官方明示）：
这意味着：调高 minWorkbuddyVersion 会让低版本新用户看不到你，但已连接的老用户不会被静默断掉（只是置灰提示升级）。这是一个相对友好的降级策略，所以在声明版本门槛时不必过度保守。
把本章的内容串成一条可执行的排期线。耗时均为经验估算，平台未公布官方时长。
排期上最重要的结论：T2（资质准备）必须与 T0（立项）并行启动，而不是等到 T8 提交前。 很多行业的资质（办学许可、金融牌照、医疗资质）申请周期以月计，如果等到开发完才发现没有资质，整个项目就废了。
本章从合规体系的设计意图出发，覆盖了四个层面：
我的主体类型（个人/企业）是否与我要经营的服务类目匹配？
我是否理解"资产不能跨主体迁移"，并据此确定了账号规划？
我需要的类目资质是否已经在申请中（而不是等开发完再准备）？
我的企业认证方式是否选对了？（法人能否配合核身 / 企业是否已在腾讯云或微信实名）
我的昵称是否避开了全部 9 类禁止项？是否含受监管行业词或品牌词？
我的简介是否在 20—120 字符之间，且不含无法验证的数字与"领先/第一/最好"？
我的头像是否 512×512？是否按 ≤500KB 准备（而非 5000KB）？
我的联系方式是否在 1–5 项之间，且每一项都与自己相关？
我是否跑完了 4.6 节的 40 条自检清单？
如果我用到了带版本号的字段，我的 minWorkbuddyVersion 是否取了最高值？
第一篇「平台底层逻辑」到此结束。你已经掌握了：平台定位与生态位（第 01 章）、底层架构与上下文工程（第 02 章）、资产四件套的差异与组合（第 03 章）、审核合规与资质（第 04 章）。
第二篇将进入逐类资产的规范全解——从技能开始，逐字段拆解 SKILL.md 的 frontmatter、三个子目录的编写方法，以及从零写出一个高质量技能的完整流程。第 02 章的渐进式披露机制、第 03 章的四维模型，都会在那里变成具体的写作动作。
本篇章目标：① 掌握技能在客户端的安装路径与创建入口，能独立把一个技能从零搭出来；② 逐字段吃透 SKILL.md 的 frontmatter，特别是disable-model-invocation与user-invocable的行为差异；③ 建立 zip 打包与「提交后解析失败」的排查能力，把返工率降到最低。
技能（Skill）是 WorkBuddy 开放平台五类可开发资产（技能、专家、专家团、连接器、外部应用接入）里最轻、最易上手、迭代最快的一种。它本质是一份「写给 AI 看的操作说明书」：用一份 SKILL.md 把某类任务的标准做法固定下来，需要时由 AI 自动或应你手动调用。本章只讲规范，不讲设计哲学——设计方法留到第 06 章。
理解技能的「栖息位置」，是避免后续路径、引用、命名 confusion 的前提。
官方原文给出的展示与安装路径如下：
技能展示在 WorkBuddy 市场上，用户点击左侧菜单【专家·技能·连接器】出现二级菜单，选择【技能】，进入【技能市场】。用户点击对应技能右上角加号，安装对应技能，并支持在对话中调用已安装的技能。
把它拆成一条可操作的链路：
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 左侧菜单【专家·技能·连接器】 | 一级入口，技能与专家、连接器并列 |
| 2 | 二级菜单【技能】 | 进入技能专属市场 |
| 3 | 【技能市场】 | 浏览/搜索全部已上架技能 |
| 4 | 目标技能卡片右上角「加号」 | 点击即安装到本机 |
| 5 | 对话中调用 | 安装后 AI 可在对话里触发或供手动调用 |
要点：技能是「安装在本地、在对话上下文里被调用」的能力，它不单独开一个 App，也不像专家那样占用一个完整对话窗口。它是专家与连接器的「补丁级」能力单元——这也是为什么一个专家可以预加载多个技能（plugin.json 的 skills 字段），一个连接器也强烈推荐附带 Skill 来说明用法。
官方原文：
技能创建工具：点击市场右上角【添加技能】-【创建技能】。跳转进入对话，补全创建技能的提示词，开启创建。
开发者创建链路：
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 进入【技能市场】 | 与用户侧同入口 |
| 2 | 市场右上角【添加技能】 | 注意是「添加技能」而非直接新建文件 |
| 3 | 选【创建技能】 | 与「导入已有」区分配 |
| 4 | 跳转对话，补全提示词 | 平台用对话式引导帮你生成初版 SKILL.md |
这意味着平台原生支持「对话生成」：你描述需求，它吐出一份技能草稿。但草稿不等于合规交付物——正式上架前你仍需按本章规范校验 frontmatter、目录结构、打包方式。第 07 章给出的生成提示词，就是把这个「对话补全」过程从「靠运气」变成「可复现的工程动作」。
很多开发者把「技能」和「专家」混为一谈。区分只需一句话：
简单说：专家是「谁」，技能是「怎么做」。一个分析师专家可以预加载「周报生成」「数据透视」等多个技能；一个连接器可以附带 Skill 教 AI 怎么调它的命令。
官方给出的技能基础结构：
skills/
└── {skill-name}/
├── SKILL.md # ★ 技能定义（必须）
├── references/ # 参考资料（可选）
│ ├── api-spec.md # API 规范、字段类型等
│ └── examples.md # 示例数据
├── scripts/ # 可执行脚本（可选）
│ ├── fetch-data.js # 数据获取脚本
│ └── transform.py # 数据处理脚本
└── templates/ # 模板文件（可选）
├── report.sh # 报告生成模板
└── workflow.sh # 工作流模板格式
注意根目录是 skills/，下面才是 {skill-name}/。一个连接器里能力较多时，可拆分为多个 Skill，每个放在独立子目录下，WorkBuddy 会全部加载。
下面逐层说明「放什么 / 不放什么 / 为什么」。
| 项 | 说明 |
|---|---|
| 放什么 | 技能的全部指令正文 + YAML frontmatter（元数据） |
| 不放什么 | 不要把大段参考知识、长字段表、原始数据堆在正文里 |
| 为什么 | 它是 AI 的「第一入口」。系统先读它来判断要不要触发、怎么执行；正文过长会稀释触发准确性，也会浪费上下文窗口 |
SKILL.md 采用 YAML frontmatter + Markdown 正文 两段式。frontmatter 在文件最上方，用 --- 包裹；其后是 Markdown 指令正文。
官方定义：
存放 SKILL.md 引用的补充知识文档，AI 执行技能时会读取这些文件作为上下文。适用场景：API 字段类型定义、协议规范、领域知识参考、示例数据等。使用方式：在 SKILL.md 中通过 @references/xxx.md 引用。
| 项 | 说明 |
|---|---|
| 放什么 | API 字段类型表、协议规范、领域知识、示例数据、术语表、模板说明 |
| 不放什么 | 不放可执行代码（那是 scripts/ 的事），不放「必须每次都读」的核心指令（应留在 SKILL.md 或按需引用） |
| 为什么 | 让 SKILL.md 保持精简，只在真正需要时才把大块知识拉进上下文（渐进式披露，详见第 06 章） |
引用语法是 @references/xxx.md（相对 SKILL.md 所在目录）。注意：不是 @./references/xxx.md，也不是 @/references/xxx.md，官方示例就是 @references/xxx.md，前缀不带斜杠。
官方定义：
存放技能执行中需要调用的脚本，AI 通过 Bash 工具执行。适用场景：调用外部 API、数据处理、批量操作、需要特定运行时的逻辑。使用方式：在 SKILL.md 中声明调用命令和参数。
| 项 | 说明 |
|---|---|
| 放什么 | 调外部 API 的脚本、数据清洗/转换脚本、批量文件处理、需要固定运行时（Node/Python）的逻辑 |
| 不放什么 | 不放「AI 自由发挥写一段」的代码——那种不该进 scripts，直接让模型生成即可；不放敏感凭证（见 5.7 安全） |
| 为什么 | 凡是「同样输入必须得到同样输出」「有副作用」「调用外部系统」的步骤，都应交给脚本而非模型脑补，保证确定性（见第 06 章确定性 vs 概率性） |
AI 通过内置的 Bash 工具执行 scripts 里的脚本，调用写法是 node scripts/fetch-data.js 或 python scripts/transform.py 这类标准命令行。scripts 里用什么语言都行，但要保证目标环境有对应运行时（连接器场景可用 cli.json/mcp.json 的 runtime 字段声明，纯技能场景需自行确保用户环境可用，平台未明确统一运行时托管规则，建议在 SKILL.md 正文里写明依赖与安装方式）。
官方定义：
存放可复用的模板脚本或配置文件。适用场景：标准化操作流程的模板、报告生成模板。
| 项 | 说明 |
|---|---|
| 放什么 | 报告生成模板（.sh/.md/.html）、工作流骨架、配置文件样例 |
| 不放什么 | 不放需要动态计算的脚本逻辑（那是 scripts/）；不放机密配置 |
| 为什么 | 把「格式固定但内容可变」的部分抽成模板，正文只描述「填哪里、填什么」，产出更稳定、更易维护 |
templates 与 scripts 的区别在于：scripts 是「会被执行的程序」，templates 是「被填充后产出/被引用的静态骨架」。一个 report.sh 既可能是脚本也可能是模板，关键看它是被 Bash 执行，还是被读取后作为输出格式参考。
frontmatter 是技能的「身份证 + 检索标签」。官方给出的字段清单与必填标记如下（BRIEF 基线）：
name(否)、display\_name、display\_name\_en、description(是，写清用途和触发词)、description\_zh(是)、description\_en(是)、category(分类之一，示例 writing)、version(是)、allowed-tools(否，逗号分隔工具白名单)、disable-model-invocation(否，true 则 AI 不自动触发只能手动调用)、user-invocable(否，false 隐藏菜单仅供 AI 内部使用)、author(是，合作方名称)。
必填集合（官方明确标「是」）：description、description_zh、description_en、version、author。
可选集合（官方明确标「否」）：name、allowed-tools、disable-model-invocation、user-invocable。
display_name、display_name_en、category 在官方 frontmatter 示例中出现（示例含 display_name/display_name_en/category: writing），但字段表中未单独标必填/可选。结论：平台示例均包含它们，建议填写以保证市场正确展示与归类的，但官方未把它们标为强制必填。
下面是逐字段表，给出是否必填、取值策略、好/坏例子、踩坑。
| 字段 | 必填 | 职责 | 取值策略 |
|---|---|---|---|
name | 否 | 技能内部标识 | kebab-case 小写连字符，如 weekly-report。官方示例用 your-skill-name |
display_name | 示例含（建议填） | 市场展示中文名 | 简短、可读、点明用途，如「周报生成器」 |
display_name_en | 示例含（建议填） | 市场展示英文名 | 与中文名对应，如 Weekly Report Generator |
description | 是 | 一句话描述能力 + 触发词 | 写清「用途 + 触发词」，这是召回关键（详见第 06 章） |
description_zh | 是 | 简短中文介绍 | 40 字内讲清「帮用户做什么」 |
description_en | 是 | 简短英文介绍 | 与中文对应 |
category | 示例含（建议填） | 分类 | 官方示例值为 writing，表示「分类之一」；完整枚举官方未在提供文档中给出，建议从平台可选分类中选取 |
version | 是 | 语义化版本 | MAJOR.MINOR.PATCH，如 1.0.0 |
allowed-tools | 否 | 工具白名单 | 逗号分隔，如 Read,Write,Bash |
disable-model-invocation | 否 | 是否禁止 AI 自动触发 | true/false；true 时只能手动调用 |
user-invocable | 否 | 是否对用户可见 | true/false；false 时隐藏菜单仅供 AI 内部使用 |
author | 是 | 合作方名称 | 你的团队/公司名，如「XX 科技」 |
{skill-name} 保持一致最不易出错。weekly-report、api-doc-generator、legal-contract-review。周报生成器（含中文，跨平台易乱码）、WeeklyReport（驼峰，不符合 kebab-case 习惯）、skill_01（无意义且与用途无关）。name 虽标「否」，但它是系统定位技能的依据。强烈建议填写且保持全局唯一，避免与其他已安装技能冲突。display_name: 周报生成器 / display_name_en: Weekly Report Generator。name 当展示名（weekly-report 直接展示很难看）。name。很多开发者两处写一样导致市场显示一串连字符。生成结构化的周报，当用户提到"写周报""汇总本周工作""周报模板"时使用。一个有用的工具。（没说用途、没给触发词，几乎不可能被召回）。description_zh 用中文、description_en 用英文，内容一致，各 40 字左右讲清核心能力。description_zh: 将零散工作记录整理为结构化周报，支持按项目/优先级分类。 / description_en: Turn scattered work logs into structured weekly reports grouped by project and priority.description_en 直接复制中文（非英文，失去双语意义）。writing，表示为「分类之一」。提供文档中未枚举技能的完整分类表，平台未明确全量枚举，建议提交时从平台创建界面提供的分类选项中选取，或与专家 15 类 categoryId 的命名风格对齐（产品设计、技术工程、内容创作……）。writing（按官方示例）。MAJOR.MINOR.PATCH，首版 1.0.0。每次更新递增（详见 5.6）。1.0.0、1.1.0、2.0.0。v1、1、2024（非语义化）、latest（无意义）。Read,Write,Bash（一个文件处理技能的最小集）。author: 某某科技有限公司。author: test、author: 张三（个人名，平台未要求，建议用合作方主体名更规范）、留空。
```yaml
---
name: weekly-report
display_name: 周报生成器
display_name_en: Weekly Report Generator
description: 将零散工作记录整理为结构化周报，当用户提到"写周报""汇总本周工作""生成本周汇报"时触发。
description_zh: 将零散工作记录整理为按项目分类的结构化周报，支持一键导出 Markdown。
description_en: Turn scattered work logs into structured weekly reports grouped by project, exportable as Markdown.
category: writing
version: 1.0.0
allowed-tools: Read,Write,Bash
disable-model-invocation: false
user-invocable: true
author: 某某科技有限公司
---
## 5.4 核心矩阵：disable-model-invocation × user-invocable
这两个布尔字段的组合，决定技能的「触发方式」和「可见性」。官方定义：
> `disable-model-invocation`(否，true 则 AI 不会自动触发，只能用户手动调用)；`user-invocable`(否，false 则隐藏菜单，仅供 AI 内部使用)。
把它们排成 2×2 矩阵：
| | `user-invocable: true`（用户可见） | `user-invocable: false`（用户不可见，仅供 AI 内部调用） |
| --- | --- | --- |
| **`disable-model-invocation: false`**（AI 可自动触发） | **① 公开自动型**：用户能在菜单看到，AI 也会按触发词自动调用。最通用的技能形态。 | **② 隐藏自动型**：用户看不到，但 AI 在合适的对话里会自动调用它作为子能力。适合被专家/其他技能内部复用的「零件」。 |
| **`disable-model-invocation: true`**（AI 不可自动触发，仅手动） | **③ 公开手动型**：用户在菜单能看到，但 AI 不会主动触发，必须由用户点选/显式调用。适合高风险、需人工确认的操作。 | **④ 隐藏手动型**：用户看不到，AI 也不自动触发——这种组合基本无意义，除非被某个显式流程在特定条件下调用。**平台未明确此组合的典型场景，建议避免使用**。 |
### 四种组合的适用场景
**① 公开自动型（false / true）**
- 行为：菜单可见 + AI 自动召回。
- 适合：绝大多数「用户说一句话就能用」的通用技能，如周报生成、文案润色、表格转换。
- 风险：最低，推荐默认。
**② 隐藏自动型（false / false）**
- 行为：菜单不可见 + AI 自动调用。
- 适合：被专家预加载、作为其他技能的「内部零件」的支撑技能。例如一个「按项目聚合工时」的零件技能，用户不需要知道它存在，专家在生成周报时自动调用。
- 注意：因为用户不可见，它必须被某个可见的技能/专家显式调度，否则等于「装了白装」。
**③ 公开手动型（true / true）**
- 行为：菜单可见 + 不自动触发，需用户主动调用。
- 适合：高风险或高成本操作——如「批量删除文件」「发送对外邮件」「调用付费 API」。让用户每次都明确点一下，避免 AI 自作主张造成损失。
- 设计要点：在 SKILL.md 正文里强调「执行前必须向用户确认参数」，因为 AI 不会自动触发，触发即代表用户已知情。
**④ 隐藏手动型（true / false）**
- 行为：不可见 + 不自动触发。
- 评估：**平台未明确给出此组合的典型用途，建议避免**。若确有需要（例如某个编排流程在固定步骤显式调用一个隐藏技能），请在测试环境充分验证其可达性。
记忆口诀：**`disable` 管「AI 主不主动」，`user-invocable` 管「用户看不看得到」**。
## 5.5 allowed-tools 白名单策略
`allowed-tools` 是「最小权限原则」在技能层的落地。不写=不限制（拿到系统能给的全部工具）；写了=只给清单内的工具。
### 5.5.1 什么时候该限制
| 场景 | 是否建议限制 | 理由 |
| --- | --- | --- |
| 纯文本生成技能（只产出文字） | **建议限制** | 只需 `Read`（读输入）、`Write`（写产出），限制掉 `Bash` 防止意外执行 |
| 文件处理技能（读文件→转格式→写回） | 建议限制 | `Read,Write` + 必要时 `Bash`（跑脚本） |
| 调外部 API 的技能 | 必须限制 | 只允许 `Bash`（执行 scripts）+ `Read`/`Write`，禁止 `WebSearch`/`AgentTool` 之类无关能力 |
| 高风险操作（删文件、发邮件、付费调用） | 必须严格限制 | 只给恰好够用的工具，降低误用面 |
| 通用助手型技能 | 可不写（不限制） | 场景开放，难以提前界定工具集 |
### 5.5.2 限制到什么粒度
- **按工具大类**：`Read,Write,Bash` 是最常见的最小集。
- **不要列无关工具**：如果技能根本不联网，就别给 `WebSearch`/`WebFetch`；如果不需要调其他 Agent，就别给 `AgentTool`。
- **写法是逗号分隔、无空格也可**：`Read,Write,Bash` 与 `Read, Write, Bash` 均可，保持团队统一即可。
- **踩坑**：白名单只做「减法」——它限制技能能用哪些工具，**不能**给技能添加系统未分配的工具（专家/技能的工具权限由系统统一分配，开发者不可自行添加 tools，这一点与专家的约束一致）。所以 `allowed-tools` 实际是「从系统已分配的工具里再收窄」。
## 5.6 version 语义化版本实践
官方：`version` 为必填，语义化版本号。行业通行规则（SemVer）套用到技能：
| 变更类型 | 版本位 | 算什么 | 例子 |
| --- | --- | --- | --- |
| 破坏性变更 | MAJOR | 改了触发逻辑导致旧用法失效、删了核心能力、改了输出格式且不兼容 | `1.3.0` → `2.0.0` |
| 新增能力 | MINOR | 加了新参数、新输出板块、新引用文件，但旧用法仍可用 | `1.0.0` → `1.1.0` |
| 修复/微调 | PATCH | 修错别字、优化措辞、修正一个示例、调小 bug 不影响接口 | `1.0.0` → `1.0.1` |
### 实操建议
- **首版必是 `1.0.0`**，不要用 `0.1.0` 上架（容易让用户以为是试用版，且语义上 `1.0.0` 才是「可交付」）。
- **每次提交审核都递增版本**，即使只是改了 description——平台靠版本判断是否需要重新解析。
- **MAJOR 变更前评估影响**：如果你的技能被某个专家 `skills` 预加载，大版本变更要同步验证专家侧调用是否仍成立。
- **踩坑**：版本号和「发布日期」无关，不要写成 `2024.09`；也不要写 `v1.0`（缺两位）；纯数字 `1` 会被拒或解析异常。
## 5.7 references / scripts / templates 的引用写法回顾
| 资源 | 在 SKILL.md 里怎么引用 | 谁去执行/读取 |
| --- | --- | --- |
| references | `@references/api-spec.md` | AI 在执行到相关步骤时读取为上下文 |
| scripts | `Bash` 调用，如 `node scripts/fetch-data.js {{参数}}` | 由内置 Bash 工具执行 |
| templates | 正文中指向 `templates/report.sh`，作为填充骨架参考 | AI 读取后按格式产出，或脚本引用 |
### references 的 `@` 引用机制要点
- 路径相对 SKILL.md 所在目录，**不带前导斜杠**：`@references/xxx.md` ✅，`@/references/xxx.md` ❌。
- 一份 SKILL.md 可引用多个 references 文件，按需分散知识。
- references 文件本身也是 Markdown，AI 直接读其文本作为补充指令/知识。
- **渐进式披露**：SKILL.md 正文只写「什么时候去读 `@references/xxx.md`」，把细节下沉，详见第 06 章。
### scripts 的 Bash 调用写法要点
- 在正文里写清楚命令、参数、预期输出。例：
```markdown
```markdown
调用数据获取脚本：
Bash: `node scripts/fetch-data.js --since "{{开始日期}}" --until "{{结束日期}}"`
该脚本输出 JSON 到 stdout，格式为 { "tasks": [...] }。
- 脚本应**幂等、有清晰退出码、输出可读错误**，便于 AI 判断成功失败。
- **严禁在脚本或任何文件里硬编码真实 Token / 密钥**（与连接器安全要求一致）。凭证应走环境变量或由连接器 `token-schema.json` 注入。
### templates 的用法要点
- 适合「结构固定、内容可变」的产出：周报模板、合同模板、SQL 模板。
- 正文描述「把 X 填到模板的 Y 处」，比让模型从零生成更稳。
- 可与 scripts 配合：脚本读取 templates 再填充变量，最后写出产物。
## 5.8 zip 打包与解析失败排查树
技能是以 **zip 包**形式提交审核的。官方明确：
> 在开放平台上如创建技能过程中，提交 zip 包后解析失败，可参考后续【技能基础结构】【子资源目录说明】定位问题，如定位问题失败，请发送邮件联系运营同学 [openworkbuddy@tencent.com](openworkbuddy@tencent.com)，或扫描开放平台首页下方的二维码，加入社群沟通。
下面是完整的「提交 zip 后解析失败」决策树。每一片叶子给出**验证方法**，你可以按顺序排查。
### 5.8.1 排查总原则
1. 先确认是不是**自己这边的结构问题**（占 90% 以上）；
2. 再确认是不是**编码/路径/命名**等低级错误；
3. 最后才是**平台侧**问题，此时按官方指引联系 `openworkbuddy@tencent.com` 或扫码进群。
### 5.8.2 决策树
提交 zip 后解析失败？
│
├─ A. 根目录结构对不对？
│ 验证：解压 zip，确认顶层是 skills/，且 skills/ 下每个技能有独立 {skill-name}/ 目录，
│ SKILL.md 在 {skill-name}/ 直接子级。
│ 错例：把 SKILL.md 直接放 zip 根、或少了 skills/ 这一层。
│ └─ 不对 → 重新按 5.2 结构打包
│
├─ B. 必填项是否齐全？
│ 验证：打开 SKILL.md 的 frontmatter，逐项核对：
│ description(是) / description_zh(是) / description_en(是) / version(是) / author(是)
│ 漏任一项 → 补上再打包
│ └─ 缺必填 → 补 frontmatter 字段
│
├─ C. frontmatter 语法是否合法？
│ 验证：确认 ---
│ 1) 文件最上方用 --- 开始、frontmatter 结束后用 --- 闭合；
│ 2) 字段名后是冒号+空格；
│ 3) 多语言/对象类字段（如有）缩进正确；
│ 4) 字符串含冒号/特殊符号时用引号包裹。
│ 常见错：description 值里含未转义的冒号、中文全角冒号、YAML 缩进错位。
│ └─ 语法错 → 用 YAML 校验器（如 yamllint / 在线 YAML 解析）过一遍
│
├─ D. 文件名与目录名是否合规？
│ 验证：
│ - {skill-name} 用 kebab-case（小写+连字符），避免中文/空格/大写；
│ - 文件名用 UTF-8，避免操作系统保留字；
│ - references/scripts/templates 内文件名清晰无空格（建议 kebab-case）。
│ 错例：目录名「我的技能」、脚本名「fetch data.js」(含空格)。
│ └─ 不合规 → 改名后重新打包
│
├─ E. 编码问题？
│ 验证：确认所有文件（尤其 SKILL.md 与中文 description）以 UTF-8 保存，
│ 而非 GBK/带 BOM 的 UTF-8。带 BOM 的 UTF-8 会在文件头插入不可见字符，
│ 破坏 frontmatter 解析。
│ └─ 编码错 → 转 UTF-8（无 BOM）后重打包
│
├─ F. 嵌套层级是否过深或路径引用错？
│ 验证：
│ - references 引用是否写成 @references/xxx.md（相对，无前导 /）；
│ - 是否存在 SKILL.md 引用了不存在的文件（引用了但又没打包进去）；
│ - 目录嵌套是否过深导致超出平台预期。
│ 错例：正文写 @/references/x.md、或引用 @references/missing.md 但文件没放进包。
│ └─ 路径错 → 修正引用或补文件
│
├─ G. 是否存在平台不允许的内容？
│ 验证：扫描全部文件，确认没有硬编码真实 Token / 密钥 / 敏感凭证
│ （connector 安全要求同样适用于技能包）。
│ └─ 有敏感信息 → 移除并改用环境变量/凭证注入
│
└─ H. 以上全部正确仍失败？
验证：换一个最小可复现包（仅 SKILL.md + 必填 frontmatter）单独提交，
定位是否某子资源（scripts/templates）引起。
└─ 仍失败 → 联系 openworkbuddy@tencent.com，或扫码加入开发者群，
附上：技能名、版本、报错截图、最小复现包。
### 5.8.3 一个「最小可复现包」写法（用于隔离问题）
当你怀疑是子资源导致失败时，先打一个只有必填项的包验证通道是否通：
skills/
└── my-test-skill/
└── SKILL.md
SKILL.md 仅含必填 frontmatter + 一句正文：
```yaml
```yaml
---
name: my-test-skill
description: 最小复现包，用于验证提交通道。触发词：测试技能。
description_zh: 最小复现包，用于验证提交通道。
description_en: Minimal repro skill to verify submission pipeline.
version: 1.0.0
author: 某某科技有限公司
---
# 测试技能
本技能仅用于验证提交与解析是否成功。
如果这个最小包能过，问题就在你原来包的子资源/引用/编码；如果它也失败，基本是平台侧或账号/审核配置问题，直接走官方联系方式。
## 5.9 小结与检查清单
**本章要点回顾**：
- 安装路径：左侧菜单【专家·技能·连接器】→【技能】→ 技能市场 → 右上角加号。
- 创建路径：市场右上角【添加技能】-【创建技能】→ 对话补全提示词。
- 目录四件套：`SKILL.md`（必须）+ `references/`、`scripts/`、`templates/`（可选）。
- 必填 frontmatter：`description`、`description_zh`、`description_en`、`version`、`author`。
- 行为开关矩阵：记住「`disable` 管 AI 主不主动，`user-invocable` 管用户看不看得到」。
- 版本严格 SemVer；allowed-tools 按最小权限收窄。
- zip 解析失败先自查结构/必填/语法/编码/路径，再用最小包隔离，最后联系官方。
**交付前检查清单（勾选后再提交）**：
zip 解压后顶层是 `skills/`，每个技能有独立 `{skill-name}/` 目录
`SKILL.md` 在技能目录直接子级
frontmatter 五个必填字段全部存在且非空
`description` 写清了「用途 + 触发词」
`description_zh` 与 `description_en` 语义一致
`version` 为合法 `MAJOR.MINOR.PATCH`
`disable-model-invocation` / `user-invocable` 组合符合预期（对照 5.4 矩阵）
`allowed-tools` 按需收窄，未越权申请工具
`references/` 引用均为 `@references/xxx.md`（无前导斜杠且文件已打包）
所有文件 UTF-8 无 BOM，目录/文件名 kebab-case 无空格
全包无硬编码真实凭证
已用最小复现包验证过提交通道（如曾失败）
下一步：第 06 章讲怎么把「一个真实需求」设计成高质量技能——触发词怎么写、正文怎么分五段、知识怎么渐进式披露。
本篇章目标：① 拿到一个模糊需求，能用「输入→输出→验收标准」三件套把它钉死，而不是凭感觉写；② 掌握触发词工程与五段式指令结构，让技能「在该触发时被触发、输出可验收」；③ 用渐进式披露和确定性/概率性判断，把技能从「能跑」提升到「稳、可维护、不劣化」。
第 05 章讲的是「规范是什么」，本章讲「怎么把一个真实需求设计成好技能」。规范告诉你边界，方法论告诉你如何在边界内写出高质量资产。读者带着一个具体需求（比如「帮销售自动写周报」）读完本章，应能产出一份可打包、可验收、可迭代的技能。
新手最大的坑是「拿到需求直接写正文」。正确的顺序是先定义产出契约，再写技能。契约由三件套组成：
| 件套 | 问题 | 作用 |
|---|---|---|
| 输入（Input） | 用户/系统会给技能什么？哪些必填、哪些可选、格式是什么？ | 防止「技能跑起来才发现缺信息」 |
| 输出（Output） | 技能产出的形态、结构、落点（写文件/回消息/调用脚本）？ | 防止「产出了一堆但用不了」 |
| 验收标准（Acceptance） | 怎样算「做对了」？可观测、可判定 | 防止「感觉还行但说不清好坏」 |
| 件套 | 定义 |
|---|---|
| 输入 | 用户提供的：本周工作记录（文本/文件）、时间范围（默认本周一~周日）、分组维度（默认按项目）。可选：模板偏好、导出格式 |
| 输出 | 一份 Markdown 周报，含「本周概览 / 按项目分类的工作项 / 风险与阻塞 / 下周计划」四段；可写入 周报-{{日期}}.md |
| 验收标准 | ① 覆盖用户给出的全部工作记录，无遗漏；② 分类维度正确；③ 含四段结构；④ 风险项被单独标注；⑤ 不得编造用户未提供的工作内容 |
为什么要先写验收标准？ 因为 AI 是概率模型，没有「及格线」它就会自由发挥。验收标准就是技能的「单元测试断言」——它决定了你第 6.6 节能不能写自动化测试用例。
description 字段官方要求是「写清用途和触发词」。它是 AI 决定「用户这句话该不该用这个技能」的第一依据。写不好，技能要么石沉大海（永远不触发），要么滥杀无辜（啥都触发）。
<用途一句话> + <触发词清单：当用户说/做 X、Y、Z 时使用>
| # | 技能 | 坏 description | 好 description |
|---|---|---|---|
| 1 | 周报生成 | 一个有用的工具。 | 将零散工作记录整理为结构化周报，当用户提到"写周报""汇总本周工作""生成本周汇报"时触发。 |
| 2 | 文案润色 | 润色文字。 | 优化中文/英文文案的语气与通顺度，当用户说"帮我润色""改得更专业""这段文字通顺点"时触发。 |
| 3 | SQL 生成 | 写 SQL。 | 根据自然语言需求生成 SQL 查询，当用户说"帮我查一下""写个 SQL 统计""按条件筛选数据"时触发。 |
| 4 | 合同审查 | 审查合同。 | 识别合同中的风险条款与缺失项，当用户说"看下这份合同""审查风险""合同条款有没有坑"时触发。 |
| 5 | 会议纪要 | 整理会议。 | 将会议录音稿/聊天记录提炼为结论与待办，当用户说"整理会议""出会议纪要""提炼待办"时触发。 |
| 6 | 数据透视 | 数据分析。 | 对表格数据做分组聚合与透视，当用户说"做个透视""按部门统计""数据汇总成表"时触发。 |
| 7 | 邮件草稿 | 写邮件。 | 按给定要点生成商务邮件草稿，当用户说"帮我起草邮件""写封回复""拟个邮件给客户"时触发。 |
| 8 | 代码审查 | 看代码。 | 对给定代码片段做安全与可读性评审，当用户说"review 这段代码""看看有没有 bug""代码评审"时触发。 |
| 9 | 翻译 | 翻译。 | 在指定语种间互译并保持术语一致，当用户说"翻译这段""译成英文""中英互译"时触发。 |
| 10 | API 文档生成 | 生成文档。 | 从代码或接口定义生成 API 文档，当用户说"出个接口文档""把这组 API 写成文档""生成 OpenAPI"时触发。 |
规律：坏例子都是「名词 + 句号」，好例子都是「动词用途 + 当用户说 X/Y/Z 时触发」。坏例子的共同问题——没给触发词、没说清用途、无法被召回。
技能有三个 description 字段：description（主，官方示例用中文写用途+触发词）、description_zh（简短中文介绍）、description_en（简短英文介绍）。三者职责不同：
| 字段 | 写法侧重 | 是否需触发词 |
|---|---|---|
description | 完整用途 + 触发词，是召回主依据 | 必须含触发词 |
description_zh | 40 字内讲清「帮用户做什么」，偏展示 | 可不列触发词，但要语义覆盖 |
description_en | 与 description_zh 对应英文，偏展示 | 可不列触发词 |
一致性要求（硬性）：
description_zh 与 description_en 必须语义一致——中文说周报、英文不能说月报。description 的用途部分要与 description_zh 对齐，避免「主描述说周报、中文简介说日报」的割裂。description 里写全；zh/en 简介做「人话概括」即可。一致性自检：把三个字段并排读一遍，向一个不懂业务的人描述，如果三句话像在说同一件事，就过关。
一个健壮的 SKILL.md 正文，建议固定为五段。每段职责清晰，缺一不可：
讲清「你是谁、做什么、不做什么」。边界尤其重要——防止技能越界去干别人的活。
模板 ```# 角色 你是一个「周报生成助手」，负责把用户提供的零散工作记录，整理成结构化的周报。 ## 边界 - 只整理用户已提供的内容，不得编造未提及的工作项。 - 不替代项目管理工具，不修改源数据。 - 若信息不足，向用户追问，不臆测。```
示例（周报）：见上。要点是「边界」用否定句写清禁区，比写「你要认真」有用得多。
把 6.1 的输入件套落成机器可读的约定。
模板 ```## 输入 必填： -工作记录：文本或文件，覆盖本周已完成/进行中/阻塞的事项。 可选： -时间范围：默认本周一 00:00 ~ 本周日 24:00。 -分组维度：默认「按项目」，可指定「按优先级」。 若必填缺失，停下并列出缺什么，请用户补充。```
按可复现顺序写步骤。确定性步骤指向 scripts，概率性步骤才让模型发挥。
模板 ```## 执行步骤 1. 解析用户输入，归类工作记录到「已完成/进行中/阻塞」。 2. 如含文件，用 Read 读取；如含结构化数据，调用scripts/aggregate.py（见 references/agg-spec.md）。 3. 按分组维度聚合，识别风险与阻塞项。 4. 套用 templates/weekly-report.md 生成四段结构。 5. 将结果写入周报-{{日期}}.md，并摘要回消息。```
定义产出的形态、结构、命名、格式。
模板 ```## 输出 文件：周报-{{YYYY-MM-DD}}.md 结构（四级固定）： 1. 本周概览（3 句话内） 2. 按项目分类的工作项（表格） 3. 风险与阻塞（单独标注，红色标记） 4. 下周计划（要点列表） 正文用 Markdown；数字用绝对计数。```
把验收标准写成可判定的断言，并定义「做不完怎么办」。
模板 ```## 验收 - [ ] 覆盖用户给出的全部工作记录，无遗漏 - [ ] 含上述四段结构 - [ ] 风险项被单独标注 - [ ] 未编造未提供的内容 ## 降级 - 信息不足：列出缺失项，请用户补充，不臆测。 - 脚本失败：报告错误并给出原始记录，不静默跳过。 - 超长记录：分批处理，先给概览再给明细。```
五段式不是死板八股——它对应「谁/要啥/咋做/出啥/算不算数」五个不可回避的问题。任何技能漏掉其中一段，都会在某个真实对话里翻车。
SKILL.md 正文的规模要克制。把所有细节塞进正文，会导致：① 触发判断被噪声干扰；② 每次调用都烧掉大量上下文；③ 维护时改一处牵全身。
原则：SKILL.md 正文只放「调度指令」——告诉 AI 什么时候、读哪个 references、跑哪个 scripts。细节下沉到 references/。
| 留在 SKILL.md 正文 | 下沉到 references/ |
|---|---|
| 角色、边界、输入契约摘要 | 完整字段类型表、协议规范 |
| 五段式骨架、步骤索引 | 每个步骤的详细算法/示例数据 |
| 「需要时读取 @references/xxx.md」的调度指令 | 长篇幅领域知识、术语表、示例库 |
| 输出结构骨架 | 输出样例全集 |
关键是在正文里写清「何时读哪个文件」：
```markdown
## 执行步骤（节选）
当需要根据项目字段聚合时，先读取 @references/agg-spec.md 了解聚合规则与字段定义。
生成报告前，参考 @references/output-examples.md 中的样例保证格式一致。
AI 看到 `@references/xxx.md` 会在该步骤把对应文件拉进上下文。**这就是渐进式披露**：默认不加载大块知识，用到才加载，省上下文又保精度。
### 6.4.3 规模经验值（平台未明确，建议）
平台未对 SKILL.md 正文字数做硬性上限。**建议**：正文控制在「一眼能读完」的规模（经验上 80–200 行内为宜），把超过一屏的细节都拆到 references。若正文已超过 300 行还无 references，基本说明该拆分了。
## 6.5 确定性 vs 概率性：哪些必须交给 scripts
AI 擅长「理解意图、组织语言」，不擅长「算得准、调得稳、不犯错」。判断某一步该不该写成脚本，用下面清单：
### 6.5.1 判断清单
| 步骤特征 | 交给 scripts（Bash 执行） | 留给模型自由发挥 |
| --- | --- | --- |
| 同样输入必须同样输出（如聚合、排序、格式化） | ✅ 必须 | ❌ |
| 有外部副作用（写库、调 API、删文件） | ✅ 必须（且加确认） | ❌ |
| 涉及精确计算（金额、日期、统计） | ✅ 必须 | ❌ 易错 |
| 需要调用特定运行时/SDK | ✅ 必须 | ❌ |
| 需要联网且结果要稳定 | ✅ 走脚本/连接器 | ❌ |
| 自然语言改写、润色、总结 | ❌ | ✅ 适合 |
| 分类、归类、提取要点 | 视精度要求 | ✅ 一般可模型做，高精度则脚本 |
| 创意生成（文案、标题） | ❌ | ✅ 适合 |
**一句话法则**：凡「错了会有后果」或「错了不易察觉」的步骤，一律脚本化；凡「错一点也无所谓、甚至需要多样性」的步骤，交给模型。
### 6.5.2 反例
- 让模型「算一下本月各部门工时总和」→ 容易加错，应写成 `scripts/sum.py` 读数据后精确计算。
- 让模型「调一下我们内部 API 拉数据」→ 必须脚本，且参数、鉴权、错误处理固定下来。
- 让模型「把这段周报改得更正式」→ 这步交给模型完全没问题。
## 6.6 技能质量的 7 个可量化指标
交付前用这 7 个指标给技能打分。每个都给定义与测量方法：
| # | 指标 | 定义 | 测量方法 |
| --- | --- | --- | --- |
| 1 | 触发准确率 | 该触发时触发、不该触发时不触发的比例 | 用第 6.7 节用例集跑，统计命中/误触/漏触 |
| 2 | 产出合规率 | 输出满足验收标准的用例占比 | 用例集逐条比对验收清单打勾 |
| 3 | 输入缺失处理率 | 缺必填时正确追问而非臆测的比例 | 故意删必填项跑用例，看是否停下追问 |
| 4 | 确定性步骤正确率 | 脚本/结构化步骤的输出正确比例 | 固定输入跑脚本，比对预期输出 |
| 5 | 上下文效率 | 单次调用消耗的有效 token 占比 | 对比「正文+引用」体积与产出价值，references 拆分是否合理 |
| 6 | 降级完备度 | 异常场景下按降级规则处理的比例 | 构造失败/超长/格式错用例，看是否按 6.3.5 降级 |
| 7 | 跨版本稳定性 | 迭代后旧用例是否仍通过 | 每次发版跑回归用例集（见 6.7.3），统计通过率 |
**阈值建议（平台未明确，建议）**：触发准确率 ≥ 90%、产出合规率 ≥ 95% 可作为内部上架门槛；低于则先修再发。
## 6.7 测试与迭代：防劣化
### 6.7.1 最小测试用例集
每个技能至少准备 4 类用例，覆盖「正常 / 边界 / 异常 / 跨语言」：
| 用例类型 | 目的 | 例子（周报） |
| --- | --- | --- |
| 正常 | 验证主路径 | 给一周工作记录，产出合规周报 |
| 边界 | 验证极值 | 空记录、单条记录、跨月边界 |
| 异常 | 验证降级 | 缺必填、文件损坏、脚本报错 |
| 跨语言 | 验证中英触发 | 用英文触发词也能召回并正确产出 |
### 6.7.2 用例写法（可复现）
每个用例固定三要素：**输入样本 + 预期行为 + 验收断言**。
用例 W-01（正常）
输入：工作记录文本（含 3 个项目共 8 条）
预期：产出四段结构周报，覆盖 8 条无遗漏
断言：[ ] 四段齐全 [ ] 无编造 [ ] 风险项标注
### 6.7.3 回归与版本防劣化
- **建回归集**：把上述用例固化成文件，每次改技能都重跑。
- **版本门禁**：发新版本前，回归集通过率须 ≥ 上一版（不能「修一个 bug 坏三个旧用例」）。
- **变更记录**：在 README 或版本说明里记「本次改了什么、影响了哪些用例」，便于回溯。
## 6.8 正反例完整对照：同一个「周报生成」需求
下面用同一需求给出「烂技能」与「好技能」全文，差异一目了然。
### 6.8.1 烂技能（反面教材）
```yaml
```yaml
---
name: wb
description: 帮你写东西。
version: 1
author: test
---
# 周报
用户给你工作记录你就写周报，写得好一点，专业一点，不要出错。
**它的问题**（逐条对号入座）：
1. `name: wb` 无意义、非 kebab-case；
2. `description` 无触发词、无用途，几乎不可能被召回；
3. 缺 `description_zh`/`description_en`（必填缺失，直接解析失败）；
4. `version: 1` 非语义化；
5. `author: test` 不像合作方主体；
6. 正文无角色/边界/输入契约/输出规范/验收，全靠「写得好一点」这种空话；
7. 没有任何 references/scripts 拆分，确定性聚合靠模型脑补；
8. 无降级、无验收，做错无法发现。
### 6.8.2 好技能（达标范本）
```yaml
```yaml
---
name: weekly-report
display_name: 周报生成器
display_name_en: Weekly Report Generator
description: 将零散工作记录整理为结构化周报，当用户提到"写周报""汇总本周工作""生成本周汇报"时触发。
description_zh: 将零散工作记录整理为按项目分类的结构化周报，支持一键导出 Markdown。
description_en: Turn scattered work logs into structured weekly reports grouped by project, exportable as Markdown.
category: writing
version: 1.0.0
allowed-tools: Read,Write,Bash
disable-model-invocation: false
user-invocable: true
author: 某某科技有限公司
---
# 角色
你是一个周报生成助手，负责把用户提供的零散工作记录整理成结构化周报。
## 边界
- 只整理用户已提供的内容，不得编造未提及的工作项。
- 不修改源数据，不替代项目管理工具。
- 信息不足时向用户追问，不臆测。
## 输入
必填：
- `工作记录`：文本或文件，含本周已完成/进行中/阻塞事项。
可选：
- `时间范围`：默认本周一 ~ 本周日。
- `分组维度`：默认「按项目」。
若必填缺失，停下并列出缺什么。
## 执行步骤
1. 解析输入，归类到「已完成/进行中/阻塞」。
2. 含文件用 Read 读取；结构化数据调用 `scripts/aggregate.py`（规则见 @references/agg-spec.md）。
3. 按分组维度聚合，识别风险与阻塞项。
4. 套用 templates/weekly-report.md 生成四段结构。
5. 写入 `周报-{{日期}}.md`，并摘要回消息。
## 输出
文件：周报-{{YYYY-MM-DD}}.md，四段结构：
1. 本周概览（≤3 句）
2. 按项目分类的工作项（表格）
3. 风险与阻塞（单独标注）
4. 下周计划（要点列表）
## 验收
- [ ] 覆盖全部工作记录，无遗漏
- [ ] 含四段结构
- [ ] 风险项单独标注
- [ ] 未编造内容
## 降级
- 信息不足：列缺失项，请用户补充。
- 脚本失败：报告错误并回退原始记录，不静默跳过。
- 超长：先给概览再给明细。
对比可知：**好技能的每个字段、每段正文，都在消除「不确定性」**——召回靠触发词、产出靠契约、正确靠脚本、兜底靠降级。
## 6.9 小结与检查清单
**本章要点回顾**：
- 先钉三件套（输入/输出/验收），再写技能，验收标准是技能的「单元测试」。
- `description` 用「用途 + 当用户说 X/Y/Z 时触发」公式，附 10 组对照。
- 正文五段式：角色与边界 / 输入契约 / 执行步骤 / 输出规范 / 验收与降级。
- 渐进式披露：正文只写调度指令，细节下沉 `@references/`。
- 确定性步骤（算得准、有副作用、需精确）必须脚本化。
- 7 个量化指标 + 最小用例集 + 回归防劣化。
- 同一需求的正反例对照证明：好技能在消除不确定性。
**设计前检查清单（动手写之前）**：
已写出「输入/输出/验收」三件套，验收标准可观测
`description` 含用途 + 至少 3 个触发词
`description_zh`/`description_en` 与 `description` 语义一致
正文按五段式组织，每段不缺
长细节已下沉到 `references/`，正文只写调度指令
确定性/有副作用步骤已规划为 `scripts/`
已定义降级路径（缺输入/脚本失败/超长）
已准备最小测试用例集（正常/边界/异常/跨语言）
已设定上架门槛指标（如触发准确率 ≥ 90%）
下一步：第 07 章直接给你「拿来就能用」的技能生成提示词（V1/V2/V3/元提示词/四种变体），把本章方法论固化成可复制的动作。
这一份给了封面、版权与目录，加前 7 章（WorkBuddy 开放平台深度指南：技能 · 专家 · 专家团 · 连接器 到 第06章 技能设计方法论）。全书共 25 章 + 附录 A–B，约 24.7 万字。
全本已上架 云拾阁（原创资料站），转存即取，一次到手全本，可离线翻阅与检索。
也可以直接说需求：公众号 技能社Pro · jinengshe@agent.qq.com · 或在技能社首页留言，按需求排产。