@vetta-org/plugin-sdk 0.3.1 → 0.3.3

package/docs/manifest.md

@@ -182,7 +182,7 @@ revision 读取；不要依次调用多次 `writeFile()` 冒充多文件事务
 | `agent.mcpServers` | **插件内聚 MCP**（三源聚合之插件源）：相对路径 `.mcp.json` 或内联 map。需 `agent.mcp.control`。内联 map 里的 `agent_mode` 已废弃（ADR-0071），容忍存在但被忽略。 |
 | `agent.toolPolicy.allow` / `.deny` | 声明式工具可见性策略（注册后的工具 id）。需 `agent.tools.control`。 |
 | `agent.agents` | **插件贡献的智能体**：人设、头像、系统提示词由插件提供，宿主把它们铺进用户的智能体库。**不需要权限**，见[贡献智能体与团队](#贡献智能体与团队)。 |
-| `agent.teams` | **插件贡献的团队**：成员只能是本插件 `agent.agents` 里的智能体。同上。 |
+| `agent.teams` | **插件贡献的团队**：成员可以是本插件的智能体、别的插件的智能体，或一个**角色槽位**。同上。 |
 
 > 在 JS 里**动态**注册 agent 工具走 `ctx.agent.registerTool`（见 [conversation-and-agent.md](./conversation-and-agent.md#注册-agent-工具)），与此处的**声明式**清单字段是两条不同路径。
 >
@@ -265,6 +265,7 @@ revision 读取；不要依次调用多次 `writeFile()` 冒充多文件事务
 | `systemPromptPath` / `systemPrompt` | ✅（二选一） | 人设提示词。推荐用 `systemPromptPath` 指向 Markdown：提示词值得单独 diff。内联上限 64 000 字符。 |
 | `abilities` | ❌ | `all`（默认）继承宿主全部已启用能力；`own` 只用本插件的能力。两种模式下**本插件的能力都强制激活，用户在能力面板里关不掉**——这个智能体存在的意义就是操作它自己的插件。 |
 | `legacyIds` | ❌ | 本智能体**接管**的历史 blueprint id（≤ 16 个）。见下方「接管与升级」。 |
+| `roles` | ❌ | 本智能体能顶的**角色 slug**（≤ 8 个）。声明了就能被别的插件按角色引用，见下方「被别人引用」。 |
 
 ### teams[] 字段
 
@@ -272,17 +273,110 @@ revision 读取；不要依次调用多次 `writeFile()` 冒充多文件事务
 | --- | --- | --- |
 | `id` | ✅ | 规则同 agents。 |
 | `name` / `description` | `name` ✅ | 同样支持 `%key%` 占位。 |
-| `members` | ✅ | 1–32 个 `{ agent, responsibility }`。**`agent` 只能写本插件 `agent.agents` 里的 id**：跨插件引用会让一个插件能否用取决于另一个插件装没装，宿主直接拒掉这一支团队并打 warn。 |
+| `members` | ✅ | 1–32 个成员，每个写 `{ agent \| role, responsibility, optional? }`。见下方「members[] 的两种引用」。 |
 | `workflow` / `workflowPath` | ❌ | 队长的团队任务书，把这支团队的固定流水线写死。 |
 | `legacyIds` | ❌ | 本团队接管的历史团队 id。 |
 
-**第一个成员即队长**，也是用户在团队会话里唯一的对话入口。
+**第一个成员即队长**，也是用户在团队会话里唯一的对话入口。因此**队长只能是本插件自己的智能体**（写不带斜杠的 `agent`）：让它落在别的插件上，那个插件一卸载这支团队就成了打不开的壳。
+
+### members[] 的两种引用
+
+| 字段 | 说明 |
+| --- | --- |
+| `agent` | **实体引用**。`<agentId>` 指本插件的智能体；`<pluginId>/<agentId>` 指别的插件的。就是要那个人时用它。 |
+| `role` | **角色槽位**。只声明「这里需要一个什么角色」，宿主在全部已启用插件里解析。 |
+| `optional` | 解析不到这名成员时是否照常发布团队。缺省按引用方式走：本插件的实体引用 `false`，跨插件引用与角色槽位 `true`。 |
+| `responsibility` | 一句全队可见的职责摘要，进共享名册。必填。 |
+| `instructions` / `instructionsPath` | **这名成员的任务书**：追加在它本体人格之后、只给它看的交待。二选一，内联上限 64 000 字符。 |
+
+`agent` 与 `role` **必须恰好写一个**，写零个或两个都会在构建期失败。
+
+**队长的任务书写在团队的 `workflow` 里**，不要写进 `members[0].instructions`——两处都能写就没人说得清哪份生效，所以构建期直接拒掉。
+
+**优先用角色槽位。** 实体引用把消费方钉死在一个具体的插件 id 上；角色槽位只耦合到一个角色名，提供方换人、换插件、被第三方取代都不影响你，用户还能把槽位改绑到自己调教过的智能体。
+
+> **用到 `role` / `roles` / `optional` 的插件要把 `pluginApiVersion` 写成 `^2.2.0`；再用上 `members[].instructions` 的写 `^2.3.0`。** 清单校验对未知字段 fail-closed，旧宿主会整个拒掉这份清单（不是少一项贡献）；声明版本后，旧宿主给出的是「版本不支持」这种指向明确的错误。
+
+```json
+{
+  "agent": {
+    "teams": [
+      {
+        "id": "design-team",
+        "name": "%team.design.name%",
+        "workflowPath": "agent/workflows/design-team.md",
+        "members": [
+          { "agent": "my-lead", "responsibility": "Owns the visual result end to end." },
+          {
+            "role": "designer",
+            "responsibility": "Turns the brief into reviewable frames.",
+            "instructionsPath": "agent/briefs/designer.md"
+          },
+          { "role": "developer", "responsibility": "Implements the design." }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 给借来的成员派任务书
+
+`instructions` 解决的正是「把别的插件的智能体拉进来，但要它按本团队的方式做事」：
+
+- 任务书**挂在你的团队上，不碰对方的人设**。同一个设计师在别处照旧，在你的团队里按你交待的来。
+- 与 `responsibility` 分工不同：后者是一句全队可见的职责摘要（进共享名册），前者是只给这名成员看的做事方式。
+- 用 `instructionsPath` 指向 Markdown：任务书值得单独 diff，和人设提示词一个道理。**记得文件要能被打包**——路径会自动登记为插件资源，但源文件得真的在包里，缺了这名成员会让整支团队被跳过并打 warn。
+- 用户之后可以在团队设置里改这份任务书，改过的不会被插件升级盖掉。
+
+### 被别人引用（roles）
+
+供货方要做的只有一件事：给智能体写上 `roles`。
+
+```json
+{ "id": "developer", "name": "%agent.developer.name%", "roles": ["developer"] }
+```
+
+之后谁引用、引用几次，供货方都不需要知道。
+
+#### 装机自带的智能体
+
+下面这些由预置插件供货，**任何一台机器上都解析得到**，可以放心引用。`role` 一列就是写进 `members[].role` 的值；想钉死某一个人，用 `agent` 列的全名。
+
+来自 `preset-agent`（装机自带的五位）：
+
+| role | agent | 名称 | 擅长什么 |
+| --- | --- | --- | --- |
+| `master` | `preset-agent/master` | 主控 | 端到端负责目标：规划流程、分派每一步、验收或打回结果 |
+| `developer` | `preset-agent/developer` | 开发员 | 产出核心交付物：代码、成稿或一份做实的分析 |
+| `researcher` | `preset-agent/researcher` | 检索员 | 收集事实、文档、既有方案与市场信号，并逐条核实 |
+| `auditor` | `preset-agent/auditor` | 审计员 | 红队挑刺：正确性、安全、边界、回归与无依据的结论 |
+| `business` | `preset-agent/business` | 业务员 | 把目标落成需求、范围与商业模式，并说清假设与风险 |
+
+来自 `vetta-ui-design`：
+
+| role | agent | 名称 | 擅长什么 |
+| --- | --- | --- | --- |
+| `designer` | `vetta-ui-design/designer` | 设计师 | 在 Vetta 设计画布上产出界面：App 页面、落地页、幻灯片与海报 |
+
+这两个插件是**预置插件**，用户可以禁用但不会卸载。禁用时槽位按 `optional` 规则降级——用 `role` 引用它们的团队会少一名队员，重新启用后原样回来。
+
+角色词表**不是白名单**：写表外的角色照样能解析，只是团队编辑器里没有现成的槽位选择器。反过来，你的插件也可以给自己的智能体写上这几个 role，用户装了之后同一个槽位就多一个候选（本插件优先，其次按 `pluginId` 字典序）。
+
+**解析规则**（`BUILTIN_PLUGIN_AGENT_ROLES` 在 SDK 里导出）：
+
+- 多个插件供同一个角色时，**本插件的人优先**，其次按 `pluginId` 字典序取第一个。刻意不看安装顺序——否则同一份配置在两台机器上会铺出不同的团队。
+- 解析不到且 `optional`（跨插件引用与角色槽位的缺省值）：**少一名队员，不是少一支团队**。
+- 解析不到且必填：整支团队跳过并打 warn。
+- 成员 id 由**槽位**推导，不由占槽的人推导。角色换了提供方、阵容中间插了一个人，已有成员的 id 都不会漂——它们身上挂着用户的 `@handle` 与运行时状态。
 
 ### 生命周期
 
 - **启用插件**：宿主把缺失的档案补齐——判据是「用户文档里现在有没有」，不是「历史上铺过没有」。因此用户误删、旧版本数据缺失都会被补回来。
 - **升级插件**：没被用户手改过的档案跟着提供方走（铺档案时**不落 `systemPrompt`**，人设升级才能自动生效）；用户改过的字段保留。
 - **禁用插件**：档案**灰着留在原地**，既不隐藏也不从团队里摘掉，并标出「插件已禁用」。重新启用后一切原样回来——中途不动用户的档案。
+- **供货方后到**：铺团队时解析不到的槽位，会在提供方装上之后**自动补进阵容**。前提是阵容还是提供方铺的那一份——用户自己加过人就整支不动，宁可少补一个也不往用户编辑过的阵容里插队。
+- **跨插件引用的能力面**：别的插件的智能体自带 `pinnedPlugins`，进了你的团队就等于隐式拉起那个插件的能力，用户在能力面板里关不掉。引用之前想清楚这一点。
 - **贡献出错**：单个智能体/团队解析失败（提示词读不到、头像超限、成员引用非法）只跳过它自己并打 warn，不影响同插件的其它贡献。
 
 ### 接管与升级（legacyIds）

package/docs/styling-and-pitfalls.md

@@ -144,12 +144,12 @@ function Icon() {
 - `package.json` 里的 `react` 只用于类型与本地构建，别试图 bundle 一份自己的 React。
 - `@vetta-org/plugin-sdk` 同样 external，运行时由宿主提供。
 
-## 可选：`@vetta/ui` 宿主 primitives
+## 可选：`@vetta-org/ui` 宿主 primitives
 
 插件**可以**直接使用宿主的设计系统 primitives，与 App chrome 对齐：
 
 ```tsx
-import { Button, Switch, Slider, Dialog, DialogContent, cn } from "@vetta/ui";
+import { Button, Switch, Slider, Dialog, DialogContent, cn } from "@vetta-org/ui";
 ```
 
 约定：
@@ -157,20 +157,20 @@ import { Button, Switch, Slider, Dialog, DialogContent, cn } from "@vetta/ui";
 | 项 | 说明 |
 | --- | --- |
 | 运行时 | 由宿主单例提供（MF share + `vetta-host://ui`），**不要**打进插件 bundle |
-| 构建 | `vettaPluginFederation` 已把 `@vetta/ui` 设为 `shared.singleton + import:false`，并 rollup external |
-| `package.json` | 仅作类型 / 本地 tsc：`devDependencies` 里 `@vetta/ui`（仓库内 `workspace:*`，仓库外按发布版本） |
+| 构建 | `vettaPluginFederation` 已把 `@vetta-org/ui` 设为 `shared.singleton + import:false`，并 rollup external |
+| `package.json` | 仅作类型 / 本地 tsc：`devDependencies` 里 `@vetta-org/ui`（仓库内 `workspace:*`，仓库外按发布版本） |
 | 样式 | 组件 class 走宿主全局 token / Tailwind；插件 scoped CSS **管不到** Dialog 等 portal 到 `document.body` 的浮层（浮层依赖宿主已加载的全局样式，这是预期行为） |
-| 宿主版本 | 需要宿主提供 `vetta-host://ui` shim：desktop **>= 0.5.31**，且 `@vetta-org/plugin-vite` **>= 0.0.5**。旧宿主上 import `@vetta/ui` 会在加载插件时解析失败（模块找不到，整个插件不激活）——若你的插件要兼容更早的 App，就别用这条通道，自写 JSX + 语义 class |
+| 宿主版本 | 需要宿主提供 `vetta-host://ui` shim：desktop **>= 0.5.31**，且 `@vetta-org/plugin-vite` **>= 0.0.5**。旧宿主上 import `@vetta-org/ui` 会在加载插件时解析失败（模块找不到，整个插件不激活）——若你的插件要兼容更早的 App，就别用这条通道，自写 JSX + 语义 class |
 | 稳定性 | **半稳定、可选**。宿主会尽量不无故破坏，但不对跨 App 大版本做 semver 承诺；props / 导出变更时官方插件随 monorepo 同改 |
-| 不在此列 | `@vetta/theme-ui/plugin-ui` 是独立的按需共享合同，见下节；不要从其它 `@vetta/theme-ui/*` 入口导入宿主业务 View |
+| 不在此列 | `@vetta-org/theme-ui/plugin-ui` 是独立的按需共享合同，见下节；不要从其它 `@vetta-org/theme-ui/*` 入口导入宿主业务 View |
 
-默认路径仍是：自写 JSX + 语义 class（`bg-background` / `text-foreground`…）。`@vetta/ui` 适合按钮、开关、对话框等控件统一，不是强制。
+默认路径仍是：自写 JSX + 语义 class（`bg-background` / `text-foreground`…）。`@vetta-org/ui` 适合按钮、开关、对话框等控件统一，不是强制。
 
-顶层不要对 `@vetta/ui` 做立即求值（与 React 相同，见上文「MF 顶层 JSX 陷阱」）——在组件函数内使用即可。
+顶层不要对 `@vetta-org/ui` 做立即求值（与 React 相同，见上文「MF 顶层 JSX 陷阱」）——在组件函数内使用即可。
 
-## 按需：`@vetta/theme-ui/plugin-ui` 宿主成品 UI
+## 按需：`@vetta-org/theme-ui/plugin-ui` 宿主成品 UI
 
-少量经过明确审核的宿主成品组件会从窄入口 `@vetta/theme-ui/plugin-ui` 开放。
+少量经过明确审核的宿主成品组件会从窄入口 `@vetta-org/theme-ui/plugin-ui` 开放。
 它不是默认共享依赖；只有实际使用这些组件的插件才应开启：
 
 ```ts
@@ -180,10 +180,10 @@ vettaPluginFederation({
 });
 ```
 
-同时在 `devDependencies` 声明基础包 `@vetta/theme-ui`（仓库内使用
+同时在 `devDependencies` 声明基础包 `@vetta-org/theme-ui`（仓库内使用
 `workspace:*`）。`hostThemeUi` 只让运行时从宿主共享域取组件，不会把 Theme UI
 打进插件 bundle。不要为了消除构建警告给未使用该入口的插件增加依赖；也不要把
-`@vetta/theme-ui` 的其它业务入口当作插件公共 API。
+`@vetta-org/theme-ui` 的其它业务入口当作插件公共 API。
 
 ## 缓存刷新
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vetta-org/plugin-sdk",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",