moluoxixi-ai-rules 0.2.11 → 0.2.13

package/README-en.md

@@ -82,7 +82,7 @@ Use grilling to question this development plan and establish validation criteria
 Use frontend-design to design this interface, then inspect it with Playwright.
 ```
 
-For a new development role, declare `extends_roles: [development]` and `capabilities: []` in its `role.yaml`. Add role-specific capabilities to its own declaration. Each role may extend at most one parent, and multi-level chains are supported.
+For a new development role, use `schema_version: 2` and declare `extends_roles: [development]` with `provides.capabilities: []` in its `role.yaml`. Add shared capabilities to its own declaration. v2 supports multiple parents, deduplicates shared ancestors and capabilities, and rejects conflicting configurations.
 
 ## `moluoxixi`
 
@@ -381,17 +381,17 @@ Role source: [`roles/trellis`](roles/trellis).
 
 ## Shared distribution
 
-Shared skills, MCP catalogs, and vendor declarations live together in `capabilities/<capability>/`, such as `capabilities/common/skills/`. Each capability is a data-only directory containing `capability.yaml`, skills, MCP catalogs, and documentation; roles select capabilities in `role.yaml`. The runtime loader lives in `scripts/lib/capabilities.ts`, composes vendors in declaration order, merges compatible projections, deduplicates identical projections, and rejects source or target conflicts. See [capabilities/README.md](capabilities/README.md) for the layout and complete mapping.
+Shared skills, MCP catalogs, and vendor declarations live together in `capabilities/<capability>/`, such as `capabilities/common/skills/`. Each capability is a data-only directory containing `capability.yaml`, skills, MCP catalogs, and documentation. v2 roles select shared capabilities in `provides.capabilities` and keep their own installation settings in `installation`. The runtime loader lives in `scripts/lib/capabilities.ts`, composes vendors in declaration order, merges compatible projections, deduplicates identical projections, and rejects source or target conflicts. See [capabilities/README.md](capabilities/README.md) for the layout and complete mapping.
 
-`extends_roles` combines capabilities along a single inheritance chain before the child's own choices. Each role may extend at most one parent; repeated capabilities are deduplicated. Multiple parents, missing parents, and inheritance cycles are rejected. A parent may be a declaration-only template. The child declares its own role vendor, hosts, and CLI packages. See [role inheritance](capabilities/README.md#角色继承).
+v2 `extends_roles` combines shared capabilities from multiple parents before the child's own choices. Traversal follows declared parent order and visits each ancestor and capability once. Same-name skills and MCP servers deduplicate only when their sources and effective configurations agree; conflicts, missing parents, and cycles fail. Only `provides.capabilities` is inherited. Private assets, the role vendor, hosts, and CLI packages come from the selected role's `installation`. Staging is validated before setup and managed output is committed. External setup effects cannot be rolled back, and semantic overlap between differently named skills still requires human judgment. v1 and legacy modules retain single inheritance. See [role inheritance](capabilities/README.md#角色继承).
 
 Host directories, aliases, skill projection switches, and MCP formats are declared in [hosts/hosts.yaml](hosts/hosts.yaml). `scripts/lib/hosts.ts` loads and validates the declaration and resolves paths; declaration types live in `scripts/lib/types/`. Adding a host only requires a YAML entry. See [hosts/README.md](hosts/README.md) for fields and maintenance guidance.
 
 ```text
 role manifest
   -> role inheritance and capability composition
-  -> pinned vendor checkout / package setup
-  -> vendor staging
+  -> pinned vendor checkout
+  -> staging validation / setup / commit
   -> canonical ~/.agents/skills
   -> host skill projection and MCP merge
 ```

package/README.md

@@ -82,7 +82,7 @@ general
 请使用 frontend-design 设计这个界面，并用 Playwright 检查效果。
 ```
 
-新增开发角色时，在其 `role.yaml` 中声明 `extends_roles: [development]`，并设置 `capabilities: []`；专属能力可在自身声明中追加。每个角色最多继承一个父角色，支持多层链。
+新增开发角色时，在其 `role.yaml` 中使用 `schema_version: 2`，声明 `extends_roles: [development]` 和 `provides.capabilities: []`；附加共享能力可在自身声明中追加。v2 支持多个父角色，重复祖先和能力自动去重，配置冲突时直接报错。
 
 ## `moluoxixi`
 
@@ -388,9 +388,9 @@ Plan 阶段创建并确认 PRD，复杂任务补齐 design/implement 后 `task.p
 
 ## 公共分发机制
 
-共享 skills、MCP 清单和供应商声明按能力集中在 `capabilities/<能力>/`，例如 `capabilities/common/skills/`。每个能力目录是纯数据目录，只包含 `capability.yaml`、skills、MCP 清单和文档；Role 在 `role.yaml` 中选择 capability。运行时加载器位于 `scripts/lib/capabilities.ts`，负责按声明顺序组合 vendor，合并兼容投影、去重完全相同的 projection，并拒绝来源或目标冲突。目录结构与完整映射见 [capabilities/README.md](capabilities/README.md)。
+共享 skills、MCP 清单和供应商声明按能力集中在 `capabilities/<能力>/`，例如 `capabilities/common/skills/`。每个能力目录是纯数据目录，只包含 `capability.yaml`、skills、MCP 清单和文档；Role 在 v2 `role.yaml` 的 `provides.capabilities` 中选择 capability，把自身安装设置放在 `installation`。运行时加载器位于 `scripts/lib/capabilities.ts`，负责按声明顺序组合 vendor，合并兼容投影、去重完全相同的 projection，并拒绝来源或目标冲突。目录结构与完整映射见 [capabilities/README.md](capabilities/README.md)。
 
-角色通过 `extends_roles` 沿单继承链读取父角色的 capabilities，再加入自身能力。每个角色最多继承一个父角色，链上的重复能力自动去重；多父角色、缺失父角色与循环继承会报错。父角色可作为纯声明模板；子角色使用自身的 role vendor、宿主和 CLI packages。规则见 [角色继承](capabilities/README.md#角色继承)。
+v2 角色通过 `extends_roles` 组合多个父模板的共享能力，再加入自身能力。遍历遵循父角色声明顺序，重复祖先和 capability 只处理一次；同名 skill 或 MCP 只有来源和有效配置一致时才去重，冲突、缺失父角色与循环继承会报错。继承只读取 `provides.capabilities`，私有资产、role vendor、宿主和 CLI packages 使用所选角色的 `installation`。校验通过后才执行 setup 和提交受管资产；外部 setup 的环境变化以及不同名称 skill 的语义重复仍需人工判断。v1 与旧模块继续兼容单继承。规则见 [角色继承](capabilities/README.md#角色继承)。
 
 宿主目录、别名、skills 投影开关和 MCP 格式统一声明在 [hosts/hosts.yaml](hosts/hosts.yaml)。`scripts/lib/hosts.ts` 负责加载、校验和路径解析，声明类型放在 `scripts/lib/types/`。新增宿主只需更新 YAML；字段与维护说明见 [hosts/README.md](hosts/README.md)。
 
@@ -399,8 +399,8 @@ Plan 阶段创建并确认 PRD，复杂任务补齐 design/implement 后 `task.p
 ```text
 role manifest
   -> 角色继承与 capabilities 合并
-  -> 固定 vendor checkout / package setup
-  -> vendor staging
+  -> 固定 vendor checkout
+  -> vendor staging 校验 / setup / 提交
   -> canonical ~/.agents/skills
   -> 宿主 skill 投影与 MCP 合并
 ```

package/capabilities/README.md

@@ -54,25 +54,63 @@ AIRules 自有共享 skills 实际存放在 `capabilities/<能力>/skills/`。
 
 ```yaml
 # roles/<role>/role.yaml
+schema_version: 2
+role_id: example
 extends_roles: [development]
-capabilities: []
+provides:
+  capabilities: []
 ```
 
-`roles/<role>/role.yaml` 声明角色自身的 `role_vendor`、CLI 安装命令、宿主支持、继承关系和 publishable packages。角色自有的 `init-project`、hooks、agents、packages 等仍放在 `roles/<role>/`，由 `role-assets` 全量同步。旧包若仍带有 `constants/skills.ts`，安装器会在没有 `role.yaml` 时兼容读取它。
+`roles/<role>/role.yaml` 把共享能力放在 `provides`，把角色自身的安装设置放在 `installation`。角色自有的 `init-project`、hooks、agents、packages 等仍放在 `roles/<role>/`，由 `role-assets` 全量远程同步。旧包若仍带有 `constants/skills.ts`，安装器会在没有 `role.yaml` 时兼容读取它；v2 声明不会执行这些旧模块。
 
-共享能力的上游仓库、固定 commit 和投影路径统一以 `capability.yaml` 的 `vendors` 为准；角色通过 `capabilities` 与 `extends_roles` 引用这些声明。
+共享能力的上游仓库、固定 commit 和投影路径统一以 `capability.yaml` 的 `vendors` 为准；角色通过 `provides.capabilities` 与 `extends_roles` 引用这些声明。
 
 ## 角色继承
 
-`extends_roles` 将角色作为可复用的能力模板。每个角色只允许继承一个父角色，或用 `extends_roles: []` 声明没有父角色。多父角色声明会在加载阶段报错，重复填写相同父角色也会报错；YAML 与旧 `extendsRoles` 导出使用同一校验规则。
+`schema_version: 2` 支持在 `extends_roles` 中声明多个父角色。角色可以作为纯能力模板，也可以独立安装。继承只读取 `provides.capabilities`；`installation` 中的设置始终属于当前选择的角色：
+
+| 字段 | 用途 | 是否继承 |
+|---|---|---|
+| `provides.capabilities` | 引用共享 skills、MCP 与供应商 setup | 是 |
+| `installation.role_vendor` | 当前角色的远程资产与专属 setup | 否 |
+| `installation.assets` | 当前角色的私有资产路径 | 否 |
+| `installation.hosts` | 宿主支持范围 | 否 |
+| `installation.packages` | 角色 CLI 与 npm 安装声明 | 否 |
+| `installation.distribution`、`installation.entrypoints` | 分发约定与初始化入口 | 否 |
+
+```yaml
+schema_version: 2
+role_id: example
+extends_roles: [development, general]
+provides:
+  capabilities: []
+installation:
+  hosts: all
+  role_vendor:
+    name: example-role
+    source: https://github.com/moluoxixi/AIRules.git
+    projections:
+      - kind: role-assets
+        source_dir: roles/example
+```
+
+安装器按父角色声明顺序进行深度优先遍历，先处理祖先，再处理自身。上例中 `development` 已继承 `general`，最终顺序仍是 `general → development → example`；同一祖先与 capability 只处理一次。父角色顺序不会产生隐式覆盖。
 
 `general` 提供记忆、skill 编写与文档整理；`development` 继承 `general`，集中维护 `coding`、`productivity` 与 `frontend`。具体开发角色统一继承 `development` 的基础 skills 与 MCP，再选择自己的工程工作流。`engineering` 由 Matt 角色单独选择。两个基础角色也可独立安装。
 
-子角色安装时沿单继承链读取父角色的 `capabilities`，再加入自己的能力；链上重复的能力只处理一次。子角色可用 `capabilities: []` 继承整组模板能力。能力组合仍会校验供应商版本和投影目标冲突。
+纯模板只需声明 `schema_version`、`role_id`、`extends_roles` 和 `provides.capabilities`。安装共享能力的具体角色必须提供自己的 `installation.role_vendor`，使第一方能力从该角色的 AIRules 远程 checkout 投影到 vendor；父模板的私有 skills、MCP、hooks、agents 和 packages 不会随继承安装。
 
-继承范围是 capability 声明及其 skills、MCP 与供应商 setup。子角色的 `role_vendor`、角色专属资产、CLI packages 和 hosts 由自身声明；安装器将继承的第一方能力从子角色的 AIRules 远程 checkout 投影到 vendor。能力模板可只声明 `capabilities` 和 `extends_roles`；独立安装的角色需提供自身 `role_vendor`。
+重复与冲突按以下规则处理：
 
-缺失父角色、循环继承、单份声明中的重复能力及供应商版本冲突会报错。同一供应商的同一源码只投影一次；不同来源的同名 skill 仍报冲突。`grilling` skill 归属 `productivity`，随该能力的 namespace 一起同步。
+- 同一供应商必须使用相同仓库、revision 和有效 setup；兼容的投影可以合并。
+- 同名 skill 只有供应商、来源、revision、源码路径、输出目标和有效 setup 全部相同时才去重。namespace 与显式 skill 选择的重叠也会校验；不同来源的同名 skill 直接报错。
+- 同名 MCP 只有完整连接配置和有效 setup 相同时才去重。JSON 对象字段顺序不影响比较，`args`、`env`、URL、headers 或 setup 的差异都会报错。
+- 相同 setup 命令组只执行一次；组内命令顺序与有意重复的命令保留。
+- 缺失父角色、循环继承、重复填写父角色、单份声明中的重复 capability，以及供应商或文件目标的大小写冲突都会报错。冲突信息包含角色继承路径与能力来源。
+
+安装器在执行 setup 前校验来源、内容和受管目标目录，再提交暂存结果。校验或 setup 失败时保留上一版受管资产；提交失败时尝试恢复旧内容，恢复失败会保留备份并报告错误。不同名称的 skills 仍可能在语义上重复，安装器无法判断这类冲突；外部 setup 命令造成的环境变化也不能自动回滚。
+
+`schema_version: 1`、未声明版本的旧 YAML 和旧 `extendsRoles` 模块继续兼容单继承。迁移到 v2 时，将顶层 `capabilities` 移入 `provides`，将安装字段移入 `installation`。`grilling` skill 仍归属 `productivity`，没有独立的 grilling 分类。
 
 ## MCP 清单
 
@@ -100,3 +138,11 @@ capabilities: []
 - 角色专属资产：放在 `roles/<role>/`。角色只选择能力，无需逐个复制公共供应商配置。
 
 公共分发和能力测试放在 `scripts/lib/__test__/`；角色专属测试放在 `roles/<role>/__test__/`。
+
+## 安装验证
+
+先执行 `npm run build`。`npm test` 中的 `role-install.e2e.test.mjs` 从空 AIRules home 开始，通过临时 `git://` 远端实际下载供应商，保留完整菱形继承声明，并执行真实 CLI 与 npm setup。用例覆盖重复 skills、MCP 和 setup 去重、父角色私有资产隔离、重复安装、冲突拒绝，以及 setup 失败后保留旧资产和宿主配置。宿主包含 Claude、Codex 和 OpenCode；用户目录、Git 配置与 npm prefix 均隔离。
+
+`npm run verify:packed-airules` 把 npm tarball 安装到独立消费项目，再用打包后的 CLI 执行同一组安装用例。CI 在 Linux、Windows 和 macOS 上运行这些检查。
+
+`npm run verify:remote-role-install` 从真实 GitHub 上游下载当前 AIRules commit 与 capability 固定的供应商 commit，安装 `common`、`productivity` 和 `frontend` 的菱形组合，比较 skills 与可视化资源内容，并校验三种宿主的 MCP 配置。该检查需要联网，由 Linux CI 执行；它验证安装与配置，不启动 MCP 服务或调用模型。

package/dist/scripts/lib/capabilities.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
+import { setupIdentity } from './mcp-catalog.js';
 /**
  * Capability content is data owned by each directory. This loader is the
  * shared runtime that turns capability.yaml into the existing vendor model.
@@ -204,40 +205,70 @@ export function composeCapabilityDefinitions(selections, options) {
     const seenCapabilities = new Set();
     const roleVendor = cloneVendor(options.roleVendor);
     const capabilityVendors = [];
+    const roleOrigin = options.roleOrigin ?? 'selected role installation';
+    const roleProjections = new Map();
     for (const selection of selections) {
         if (seenCapabilities.has(selection.name))
             throw new Error(`Capability "${selection.name}" is declared more than once`);
         seenCapabilities.add(selection.name);
-        for (const projection of selection.definition.roleProjections ?? [])
+        const origin = selection.origin ?? options.capabilityOrigins?.[selection.name] ?? `capability ${selection.name}`;
+        for (const projection of selection.definition.roleProjections ?? []) {
             appendProjection(roleVendor, projection);
+            const key = projectionKey(projection);
+            const origins = roleProjections.get(key) ?? [];
+            origins.push(origin);
+            roleProjections.set(key, origins);
+        }
         for (const vendor of selection.definition.vendors ?? [])
-            capabilityVendors.push(cloneVendor(vendor));
+            capabilityVendors.push({ vendor: cloneVendor(vendor), origin });
     }
+    const roleProjectionOrigins = roleVendor.projections.map((projection) => {
+        const origins = roleProjections.get(projectionKey(projection));
+        return origins?.length ? [...new Set(origins)] : [roleOrigin];
+    });
     const sequence = options.roleVendorPosition === 'after'
-        ? [...capabilityVendors, roleVendor]
-        : [roleVendor, ...capabilityVendors];
+        ? [...capabilityVendors, { vendor: roleVendor, origin: roleOrigin, projectionOrigins: roleProjectionOrigins }]
+        : [{ vendor: roleVendor, origin: roleOrigin, projectionOrigins: roleProjectionOrigins }, ...capabilityVendors];
     return mergeVendors(sequence);
 }
 function mergeVendors(sequence) {
     const result = [];
     const byName = new Map();
-    for (const candidate of sequence) {
-        const existing = byName.get(candidate.name);
+    for (const entry of sequence) {
+        const candidate = entry.vendor;
+        const caseAlias = [...byName.keys()].find(name => name.toLowerCase() === candidate.name.toLowerCase() && name !== candidate.name);
+        if (caseAlias)
+            throw new Error(`Vendor names differ only by case: ${caseAlias} (${byName.get(caseAlias).origin}), ${candidate.name} (${entry.origin})`);
+        const existingEntry = byName.get(candidate.name);
+        const existing = existingEntry?.vendor;
         if (!existing) {
             const cloned = cloneVendor(candidate);
-            byName.set(cloned.name, cloned);
+            byName.set(cloned.name, {
+                vendor: cloned,
+                origin: entry.origin,
+                projectionOrigins: entry.projectionOrigins ?? cloned.projections.map(() => [entry.origin]),
+            });
             result.push(cloned);
             continue;
         }
         if (existing.source !== candidate.source
             || existing.revision !== candidate.revision
             || setupKey(existing.setup) !== setupKey(candidate.setup)) {
-            throw new Error(`Vendor "${candidate.name}" has conflicting source, revision, or setup definitions`);
+            throw new Error(`Vendor "${candidate.name}" has conflicting source, revision, or setup definitions between ${existingEntry?.origin} and ${entry.origin}`);
         }
-        for (const projection of candidate.projections)
+        for (const [index, projection] of candidate.projections.entries()) {
+            const projectionOwner = existing.projections.findIndex(existingProjection => projectionKey(existingProjection) === projectionKey(projection));
+            if (projectionOwner >= 0) {
+                const origins = entry.projectionOrigins?.[index] ?? [entry.origin];
+                existingEntry.projectionOrigins[projectionOwner] = [...new Set([...existingEntry.projectionOrigins[projectionOwner], ...origins])];
+                continue;
+            }
             appendProjection(existing, projection);
+            existingEntry.projectionOrigins.push(entry.projectionOrigins?.[index] ?? [entry.origin]);
+        }
+        existingEntry.origin = `${existingEntry.origin}, ${entry.origin}`;
     }
-    validateProjectionTargets(result);
+    validateProjectionTargets([...byName.values()]);
     return result;
 }
 function appendProjection(vendor, projection) {
@@ -248,32 +279,41 @@ function appendProjection(vendor, projection) {
 }
 function validateProjectionTargets(vendors) {
     const owners = new Map();
-    for (const vendor of vendors) {
-        for (const projection of vendor.projections) {
-            const key = projectionKey(projection);
-            for (const target of projectionTargets(projection)) {
-                const owner = owners.get(target);
-                if (owner) {
-                    throw new Error(`Projection target "${target}" conflicts between vendor "${owner.vendor}" and vendor "${vendor.name}"`);
+    for (const entry of vendors) {
+        const vendor = entry.vendor;
+        for (const [index, projection] of vendor.projections.entries()) {
+            for (const { target, identity } of projectionClaims(projection)) {
+                const owner = owners.get(target.toLowerCase());
+                if (owner && (owner.vendor !== vendor.name || owner.projection !== identity)) {
+                    throw new Error(`Projection target "${target}" conflicts between vendor "${owner.vendor}" (${owner.origin}) and vendor "${vendor.name}" (${entry.projectionOrigins[index]?.join(', ') ?? entry.origin})`);
                 }
-                owners.set(target, { projection: key, vendor: vendor.name });
+                owners.set(target.toLowerCase(), { projection: identity, vendor: vendor.name, origin: entry.projectionOrigins[index]?.join(', ') ?? entry.origin });
             }
         }
     }
 }
-function projectionTargets(projection) {
+function projectionClaims(projection) {
+    const identity = projectionKey(projection);
     if (projection.kind === 'namespace')
-        return [`skill-namespace:${projection.output}`];
+        return [{ target: `skill-namespace:${leafName(projection.output)}`, identity }];
     if (projection.kind === 'skills') {
         return projection.skills.map((skill) => {
-            const name = typeof skill === 'string' ? skill : skill.output ?? leafName(skill.name);
-            return `skill:${name}`;
+            const source = typeof skill === 'string' ? skill : skill.name;
+            const name = leafName(typeof skill === 'string' ? skill : skill.output ?? skill.name);
+            return {
+                target: `skill:${name}`,
+                identity: JSON.stringify([
+                    path.posix.join(projection.sourceBaseDir.replaceAll('\\', '/'), source.replaceAll('\\', '/')),
+                    name,
+                    setupKey(typeof skill === 'string' ? undefined : skill.setup),
+                ]),
+            };
         });
     }
     if (projection.kind === 'mcp')
-        return [`mcp:${projection.output}`];
+        return [{ target: `mcp:${projection.output}`, identity }];
     if (projection.kind === 'role-assets')
-        return ['role-assets'];
+        return [{ target: 'role-assets', identity }];
     return assertNever(projection);
 }
 function projectionKey(projection) {
@@ -300,16 +340,11 @@ function projectionKey(projection) {
 }
 function skillKey(skill) {
     if (typeof skill === 'string')
-        return skill;
-    return [skill.name, skill.output, setupKey(skill.setup)];
+        return [skill, leafName(skill), setupKey(undefined)];
+    return [skill.name, leafName(skill.output ?? skill.name), setupKey(skill.setup)];
 }
 function setupKey(setup) {
-    return JSON.stringify((setup ?? []).map(command => [
-        command.command,
-        command.args ?? [],
-        command.windowsCommandShim,
-        command.skipIfCommandAvailable,
-    ]));
+    return setupIdentity(setup);
 }
 function cloneVendor(vendor) {
     return {

package/dist/scripts/lib/install.d.ts

@@ -32,7 +32,7 @@ interface SyncFlattenedSkillsOptions {
 }
 export declare function syncFlattenedSkills(sourceDir: string, targetDir: string, moluoHome: string, options?: SyncFlattenedSkillsOptions): void;
 /**
- * 将第一方 skills 源目录投影到 vendor/skills，作为第三方 vendor 后的本地覆盖层。
+ * 将第一方 skills 源目录投影到 vendor/skills；v2 仅投影所选角色并拒绝共享目标冲突。
  * 该函数只清理曾经指向同一 source skills 根目录的过时链接，不会删除第三方 vendor 技能。
  */
 export declare function syncFirstPartySkillsToVendor(sourceRoot: string, moluoHome: string, role?: string): Promise<void>;

package/dist/scripts/lib/install.js

@@ -5,9 +5,10 @@ import path from 'node:path';
 import { areSamePaths, canonicalPath, canonicalPathKey, isPathInside } from './canonical-path.js';
 import { findHostConfig, resolveGlobalAgentSkillsPath, resolveHostPaths } from './hosts.js';
 import { buildLinkPlan } from './links.js';
-import { loadMcpCatalog, validateMcpServerNames } from './mcp-catalog.js';
+import { loadMcpCatalog, mergeMcpServer, readMcpServerFile, setupIdentity } from './mcp-catalog.js';
 import { requireRoleName } from './role-assets.js';
-import { DEFAULT_ROLE, roleOverlayOrder } from './roles.js';
+import { readRoleContract } from './role-contract.js';
+import { DEFAULT_ROLE, resolveRoleInheritance } from './roles.js';
 import { collectFlattenedSkillSources, discoverSkillDirectories, flattenedSkillName } from './skill-projection.js';
 import { loadVendorManifest, rolePackageSetupCommands } from './vendors.js';
 /** 获取 vendor 技能目录的绝对路径 */
@@ -82,18 +83,13 @@ function isSetupCommandAvailable(command) {
  * @param manifest 已解析的 VendorManifest
  */
 export function runSkillSetupCommands(manifest, homeDir) {
-    const rolePackageCommands = rolePackageSetupCommands(manifest.packages);
-    if (rolePackageCommands.length > 0) {
-        console.log('\n[setup] 安装角色声明的 npm packages...');
-        runSetupCommandGroup('role packages', rolePackageCommands);
-    }
+    // Build and validate the whole command plan before executing its first command.
+    const groups = [{ owner: 'role packages', commands: rolePackageSetupCommands(manifest.packages) }];
+    const mcpOwners = new Map();
     for (const [vendorName, vendor] of Object.entries(manifest.vendors)) {
-        if (vendor.setup && vendor.setup.length > 0) {
-            console.log(`\n[setup] 执行 ${vendorName} 的安装前置命令...`);
-            runSetupCommandGroup(vendorName, vendor.setup);
-        }
+        groups.push({ owner: vendorName, commands: vendor.setup ?? [] });
         for (const link of vendor.links) {
-            const setupCommands = [...(link.setup ?? [])];
+            const owner = `${vendorName}/${link.kind === 'mcp-file' ? 'mcp' : path.basename(link.target)}`;
             if (link.kind === 'mcp-file') {
                 if (!homeDir) {
                     throw new Error(`[setup] ${vendorName} MCP setup requires the AIRules home directory`);
@@ -107,15 +103,34 @@ export function runSkillSetupCommands(manifest, homeDir) {
                 if (!stats?.isFile() || stats.isSymbolicLink() || !isPathInside(checkoutRoot, realpathSync(sourceFile))) {
                     throw new Error(`[setup] ${vendorName} MCP catalog must be a plain file inside its checkout: ${link.source}`);
                 }
-                setupCommands.push(...loadMcpCatalog(sourceFile).setup);
-            }
-            if (setupCommands.length === 0)
+                const catalog = loadMcpCatalog(sourceFile);
+                const serverGroups = [];
+                for (const [name, server] of Object.entries(catalog.servers)) {
+                    const setup = catalog.serverSetup[name] ?? [];
+                    if (mergeMcpServer(mcpOwners, name, {
+                        server,
+                        setup: [...(vendor.setup ?? []), ...(link.setup ?? []), ...setup],
+                    }, `${vendorName} (${sourceFile})`)) {
+                        serverGroups.push({ owner: `${owner}:${name}`, commands: setup });
+                    }
+                }
+                if (serverGroups.length > 0) {
+                    groups.push({ owner, commands: link.setup ?? [] }, ...serverGroups);
+                }
                 continue;
-            const assetName = link.kind === 'mcp-file' ? 'mcp' : path.basename(link.target);
-            console.log(`\n[setup] 执行 ${vendorName}/${assetName} 的安装前置命令...`);
-            runSetupCommandGroup(`${vendorName}/${assetName}`, setupCommands);
+            }
+            groups.push({ owner, commands: link.setup ?? [] });
         }
     }
+    const executed = new Set();
+    for (const { owner, commands } of groups) {
+        const identity = setupIdentity(commands);
+        if (commands.length === 0 || executed.has(identity))
+            continue;
+        executed.add(identity);
+        console.log(`\n[setup] 执行 ${owner} 的安装前置命令...`);
+        runSetupCommandGroup(owner, commands);
+    }
 }
 function runSetupCommandGroup(owner, commands) {
     for (const command of commands) {
@@ -249,18 +264,19 @@ export function syncFlattenedSkills(sourceDir, targetDir, moluoHome, options = {
     }
 }
 /**
- * 将第一方 skills 源目录投影到 vendor/skills，作为第三方 vendor 后的本地覆盖层。
+ * 将第一方 skills 源目录投影到 vendor/skills；v2 仅投影所选角色并拒绝共享目标冲突。
  * 该函数只清理曾经指向同一 source skills 根目录的过时链接，不会删除第三方 vendor 技能。
  */
 export async function syncFirstPartySkillsToVendor(sourceRoot, moluoHome, role = DEFAULT_ROLE) {
     const legacySkillsDir = path.join(sourceRoot, 'skills');
     const rolesRoot = path.join(sourceRoot, 'roles');
-    const sourceSkillRoots = existsSync(rolesRoot)
-        ? (await roleOverlayOrder(sourceRoot, role))
-            .map(roleName => path.join(sourceRoot, 'roles', roleName, 'skills'))
-            .filter(existsSync)
-        : [];
-    if (sourceSkillRoots.length === 0 && existsSync(legacySkillsDir)) {
+    const lineage = existsSync(rolesRoot) ? await resolveRoleInheritance(sourceRoot, role) : [];
+    const isV2 = lineage.at(-1)?.contract?.schemaVersion === 2;
+    const selectedRoles = isV2 ? lineage.slice(-1) : lineage;
+    const sourceSkillRoots = selectedRoles
+        .map(entry => path.join(sourceRoot, 'roles', entry.role, entry.contract?.assets?.skills ?? 'skills'))
+        .filter(existsSync);
+    if (!isV2 && sourceSkillRoots.length === 0 && existsSync(legacySkillsDir)) {
         sourceSkillRoots.push(legacySkillsDir);
     }
     if (sourceSkillRoots.length === 0) {
@@ -283,6 +299,13 @@ export async function syncFirstPartySkillsToVendor(sourceRoot, moluoHome, role =
         }
     }
     const skillSources = [...seenSkillNames.values()].map(({ name, source }) => ({ name, source }));
+    if (isV2) {
+        for (const skill of skillSources) {
+            const target = path.join(vendorSkillsDir, skill.name);
+            if (existsSync(target) && !isSamePath(realpathSync(target), skill.source))
+                throw new Error(`Role/shared skill target conflict "${skill.name}": ${target} conflicts with ${skill.source}`);
+        }
+    }
     const currentSkillNames = new Set(skillSources.map(skill => skill.name));
     const normalizedSourceSkillRoots = sourceSkillRoots.map(canonicalPath);
     const normalizedManagedSkillRoots = existsSync(rolesRoot)
@@ -400,37 +423,12 @@ function escapeTomlString(value) {
 function tomlKey(key) {
     return /^[\w-]+$/u.test(key) ? key : `"${escapeTomlString(key)}"`;
 }
-function readMcpServerFile(sourceFile) {
-    const stats = lstatSync(sourceFile);
-    if (!stats.isFile() || stats.isSymbolicLink())
-        throw new Error(`MCP source must be a plain file: ${sourceFile}`);
-    const raw = readFileSync(sourceFile, 'utf8').trim();
-    if (!raw)
-        return {};
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`MCP source is invalid JSON: ${sourceFile}`, { cause: error });
-    }
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
-    const servers = parsed.mcpServers;
-    if (servers === undefined)
-        return {};
-    if (servers === null || typeof servers !== 'object' || Array.isArray(servers))
-        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
-    const serverRecord = servers;
-    validateMcpServerNames(serverRecord, sourceFile);
-    return serverRecord;
-}
 function readVendorMcpServers(moluoHome) {
     const root = path.join(moluoHome, 'vendor', 'mcps');
     if (!existsSync(root))
         return {};
     const servers = Object.create(null);
-    const sources = new Map();
+    const owners = new Map();
     function visit(directory) {
         const stats = lstatSync(directory);
         if (!stats.isDirectory() || stats.isSymbolicLink())
@@ -445,12 +443,8 @@ function readVendorMcpServers(moluoHome) {
             else if (entry.isFile() && entry.name === 'mcp.json') {
                 const fileServers = readMcpServerFile(entryPath);
                 for (const [name, server] of Object.entries(fileServers)) {
-                    const previous = sources.get(name);
-                    if (previous) {
-                        throw new Error(`Duplicate shared MCP server "${name}": ${previous} conflicts with ${entryPath}`);
-                    }
-                    servers[name] = server;
-                    sources.set(name, entryPath);
+                    if (mergeMcpServer(owners, name, { server, setup: [] }, entryPath))
+                        servers[name] = server;
                 }
             }
         }
@@ -461,9 +455,19 @@ function readVendorMcpServers(moluoHome) {
 export function readInstalledMcpServers(moluoHome, role) {
     const servers = readVendorMcpServers(moluoHome);
     if (role) {
-        const roleSource = path.join(moluoHome, 'roles', requireRoleName(role), 'mcp', 'mcp.json');
-        if (existsSync(roleSource))
-            Object.assign(servers, readMcpServerFile(roleSource));
+        const roleRoot = path.join(moluoHome, 'roles', requireRoleName(role));
+        const contractPath = path.join(roleRoot, 'role.yaml');
+        const assets = existsSync(contractPath) ? readRoleContract(contractPath).assets : undefined;
+        const roleSource = path.resolve(roleRoot, assets?.mcp ?? 'mcp', 'mcp.json');
+        if (!isPathInside(roleRoot, roleSource))
+            throw new Error(`Role MCP source must stay inside the selected role: ${roleSource}`);
+        if (existsSync(roleSource)) {
+            const owners = new Map(Object.entries(servers).map(([name, server]) => [name, { server, setup: [], owner: 'shared capabilities' }]));
+            for (const [name, server] of Object.entries(readMcpServerFile(roleSource))) {
+                if (mergeMcpServer(owners, name, { server, setup: [] }, `${role} (${roleSource})`))
+                    servers[name] = server;
+            }
+        }
     }
     return Object.keys(servers).length > 0 ? servers : undefined;
 }

package/dist/scripts/lib/mcp-catalog.d.ts

@@ -1,7 +1,9 @@
-import type { SetupCommand } from './vendors.js';
-export interface McpCatalog {
-    servers: Record<string, Record<string, unknown>>;
-    setup: SetupCommand[];
-}
+import type { SetupCommand } from './types/manifest.js';
+import type { McpCatalog, McpServerDefinition, McpServerOwner } from './types/mcp.js';
+export type { McpCatalog } from './types/mcp.js';
 export declare function validateMcpServerNames(servers: Record<string, unknown>, sourceFile: string): void;
+export declare function readMcpServerFile(sourceFile: string): Record<string, unknown>;
 export declare function loadMcpCatalog(sourceFile: string): McpCatalog;
+export declare function setupIdentity(setup?: readonly SetupCommand[]): string;
+/** Returns false for a completely identical declaration; incompatible names fail closed. */
+export declare function mergeMcpServer(owners: Map<string, McpServerOwner>, name: string, definition: McpServerDefinition, owner: string): boolean;

package/dist/scripts/lib/mcp-catalog.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { canonicalJson } from './core/canonical-json.js';
 const reservedServerNames = new Set(['__proto__', 'constructor', 'prototype']);
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -33,6 +34,29 @@ export function validateMcpServerNames(servers, sourceFile) {
         }
     }
 }
+export function readMcpServerFile(sourceFile) {
+    const stats = fs.lstatSync(sourceFile);
+    if (!stats.isFile() || stats.isSymbolicLink())
+        throw new Error(`MCP source must be a plain file: ${sourceFile}`);
+    const raw = fs.readFileSync(sourceFile, 'utf8').trim();
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`MCP source is invalid JSON: ${sourceFile}`, { cause: error });
+    }
+    if (!isRecord(parsed))
+        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
+    if (parsed.mcpServers === undefined)
+        return {};
+    if (!isRecord(parsed.mcpServers))
+        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
+    validateMcpServerNames(parsed.mcpServers, sourceFile);
+    return parsed.mcpServers;
+}
 export function loadMcpCatalog(sourceFile) {
     let parsed;
     try {
@@ -47,6 +71,7 @@ export function loadMcpCatalog(sourceFile) {
     validateMcpServerNames(parsed.mcps, sourceFile);
     const servers = Object.create(null);
     const setup = [];
+    const serverSetup = Object.create(null);
     for (const [name, value] of Object.entries(parsed.mcps)) {
         if (!name || !isRecord(value) || !isRecord(value.mcp)) {
             throw new Error(`MCP catalog entry must contain an "mcp" object: ${sourceFile}#${name}`);
@@ -55,9 +80,29 @@ export function loadMcpCatalog(sourceFile) {
             throw new Error(`MCP catalog entry setup must be an array: ${sourceFile}#${name}`);
         }
         servers[name] = value.mcp;
-        for (const [index, command] of (value.setup ?? []).entries()) {
-            setup.push(parseSetupCommand(command, `${sourceFile}#${name}.setup[${index}]`));
+        serverSetup[name] = (value.setup ?? []).map((command, index) => parseSetupCommand(command, `${sourceFile}#${name}.setup[${index}]`));
+        setup.push(...serverSetup[name]);
+    }
+    return { servers, serverSetup, setup };
+}
+export function setupIdentity(setup = []) {
+    return canonicalJson(setup.map(command => ({
+        command: command.command,
+        args: command.args ?? [],
+        windowsCommandShim: command.windowsCommandShim ?? false,
+        skipIfCommandAvailable: command.skipIfCommandAvailable ?? null,
+    })));
+}
+/** Returns false for a completely identical declaration; incompatible names fail closed. */
+export function mergeMcpServer(owners, name, definition, owner) {
+    const previous = owners.get(name);
+    if (previous) {
+        if (canonicalJson(previous.server) !== canonicalJson(definition.server)
+            || setupIdentity(previous.setup) !== setupIdentity(definition.setup)) {
+            throw new Error(`Shared MCP server "${name}" has conflicting connection or setup definitions: ${previous.owner} conflicts with ${owner}`);
         }
+        return false;
     }
-    return { servers, setup };
+    owners.set(name, { ...definition, owner });
+    return true;
 }

package/dist/scripts/lib/role-contract.d.ts

@@ -0,0 +1,3 @@
+import type { RoleContractData } from './types/roles.js';
+export declare function requireRoleInheritance(value: unknown, location: string, schemaVersion?: number): string[];
+export declare function readRoleContract(contractPath: string): RoleContractData;