moluoxixi-ai-rules 0.2.6 → 0.2.7

package/README-en.md

@@ -301,6 +301,8 @@ Role source: [`roles/trellis`](roles/trellis).
 
 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.
 
+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
   -> pinned vendor checkout / package setup

package/README.md

@@ -308,6 +308,8 @@ 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 格式统一声明在 [hosts/hosts.yaml](hosts/hosts.yaml)。`scripts/lib/hosts.ts` 负责加载、校验和路径解析，声明类型放在 `scripts/lib/types/`。新增宿主只需更新 YAML；字段与维护说明见 [hosts/README.md](hosts/README.md)。
+
 分发链路为：
 
 ```text

package/capabilities/README.md

@@ -2,7 +2,7 @@
 
 `capabilities/` 集中维护跨角色复用的供应商声明、skills 和 MCP 配置。每个能力目录同时容纳资产与安装声明；角色在 `roles/<role>/role.yaml` 中选择能力。
 
-能力和角色声明都使用 YAML，因为它们是安装器、校验器和其它分发工具共享的配置数据，而不是执行逻辑。增加能力或角色字段时只需更新目录声明，不需要编写 TypeScript。运行时类型集中在 `scripts/lib/manifest-types.ts` 和 `scripts/lib/capability-types.ts`；旧角色的 `constants/skills.ts` 仅作为兼容回退，不是权威来源。
+能力、角色和[宿主声明](../hosts/README.md)都使用 YAML，因为它们是安装器、校验器和其它分发工具共享的配置数据，而不是执行逻辑。新增能力、角色或宿主只需更新声明，不需要编写 TypeScript 注册表。声明类型集中在 `scripts/lib/types/`；旧角色的 `constants/skills.ts` 仅作为兼容回退，不是权威来源。
 
 ## 目录与职责
 
@@ -28,7 +28,7 @@ capabilities/
 └── engineering/capability.yaml # Matt Pocock engineering 上游声明
 ```
 
-每个能力目录的 `capability.yaml` 描述从哪个 Git 仓库、哪个固定 commit、哪个路径获取资产，以及投影到哪里；目录中的 `skills/` 和 `mcps.json` 是能力实际携带的资产。`scripts/lib/capabilities.ts` 是安装器使用的通用加载器，按角色选择顺序组合这些声明，合并相同供应商并拒绝配置冲突；`scripts/lib/capability-types.ts` 只存放运行时类型。新增能力只需新增目录和 `capability.yaml`，无需修改 TypeScript 注册表。
+每个能力目录的 `capability.yaml` 描述从哪个 Git 仓库、哪个固定 commit、哪个路径获取资产，以及投影到哪里；目录中的 `skills/` 和 `mcps.json` 是能力实际携带的资产。`scripts/lib/capabilities.ts` 是安装器使用的通用加载器，按角色选择顺序组合这些声明，合并相同供应商并拒绝配置冲突；`scripts/lib/types/capabilities.ts` 只存放声明类型。新增能力只需新增目录和 `capability.yaml`，无需修改 TypeScript 注册表。
 
 AIRules 自有共享 skills 实际存放在 `capabilities/<能力>/skills/`。第三方 skills 保留在上游，安装时按声明的固定 commit 远程同步，不在此目录复制源码。AIRules 自有资产也从 AIRules 的远程 checkout 投影，符合本项目的远程分发机制。
 

package/dist/scripts/cli.js

@@ -4,8 +4,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import kleur from 'kleur';
-import { HOST_IDS } from '../constants/hosts.js';
 import { compareContractFiles, createContractErrorAudit, serializeContractAudit, writeContractAudit, } from './lib/contract-diff.js';
+import { HOST_IDS } from './lib/hosts.js';
 import { requireRoleName } from './lib/role-assets.js';
 import { getDefaultMoluoHome, syncToHosts, verifyHosts, } from './lib/tool.js';
 function findPackageRoot(fromFileUrl) {

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

@@ -1,6 +1,6 @@
-import type { CapabilityDefinition, CapabilityName, CapabilitySelection, ComposeCapabilitiesOptions } from './capability-types.js';
-import type { VendorRepo } from './manifest-types.js';
-export type { CapabilityDefinition, CapabilityName, CapabilitySelection, ComposeCapabilitiesOptions } from './capability-types.js';
+import type { CapabilityDefinition, CapabilityName, CapabilitySelection, ComposeCapabilitiesOptions } from './types/capabilities.js';
+import type { VendorRepo } from './types/manifest.js';
+export type { CapabilityDefinition, CapabilityName, CapabilitySelection, ComposeCapabilitiesOptions } from './types/capabilities.js';
 export declare const CAPABILITY_NAMES: readonly string[];
 export declare const capabilityRegistry: Readonly<Record<CapabilityName, CapabilityDefinition>>;
 export declare function loadCapabilityDefinition(name: CapabilityName): CapabilityDefinition;

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

@@ -0,0 +1,12 @@
+import type { HostConfig, HostDeclaration, ResolvedHostPaths } from './types/hosts.js';
+/** 所有角色都必须获得的 canonical skills 公共层，不是可选宿主。 */
+export declare const GLOBAL_AGENT_SKILLS: import("./types/hosts.js").AgentSkillsConfig;
+export declare const HOST_CONFIGS: HostConfig[];
+/** 所有已登记宿主 ID，供显式 --host 校验与帮助输出使用。 */
+export declare const HOST_IDS: string[];
+/** 校验 YAML 后转换成安装器使用的类型；配置错误在文件投影前失败。 */
+export declare function loadHostDeclaration(declarationPath?: string): HostDeclaration;
+export declare function findHostConfig(id: string): HostConfig | undefined;
+export declare function resolveHostId(id: string): string | undefined;
+export declare function resolveGlobalAgentSkillsPath(userHome: string): string;
+export declare function resolveHostPaths(config: HostConfig, userHome: string): ResolvedHostPaths;

package/dist/scripts/lib/hosts.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+const declaration = loadHostDeclaration();
+/** 所有角色都必须获得的 canonical skills 公共层，不是可选宿主。 */
+export const GLOBAL_AGENT_SKILLS = declaration.globalAgentSkills;
+export const HOST_CONFIGS = declaration.hosts;
+/** 所有已登记宿主 ID，供显式 --host 校验与帮助输出使用。 */
+export const HOST_IDS = HOST_CONFIGS.map(host => host.id);
+/** 从源码或 npm 包自身读取声明，不依赖 CLI 的工作目录。 */
+function resolveHostDeclarationPath() {
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(moduleDirectory, '..', '..', 'hosts', 'hosts.yaml'),
+        path.resolve(moduleDirectory, '..', '..', '..', 'hosts', 'hosts.yaml'),
+    ];
+    const declarationPath = candidates.find(candidate => fs.existsSync(candidate));
+    if (!declarationPath)
+        throw new Error(`Unable to locate hosts/hosts.yaml from ${moduleDirectory}`);
+    return declarationPath;
+}
+/** 校验 YAML 后转换成安装器使用的类型；配置错误在文件投影前失败。 */
+export function loadHostDeclaration(declarationPath = resolveHostDeclarationPath()) {
+    const location = `Host declaration "${declarationPath}"`;
+    const document = parseDocument(fs.readFileSync(declarationPath, 'utf8'), {
+        merge: false,
+        prettyErrors: true,
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (document.errors.length > 0)
+        throw new Error(`${location} is invalid: ${document.errors.map(error => error.message).join('; ')}`);
+    let value;
+    try {
+        value = document.toJS({ maxAliasCount: 0 });
+    }
+    catch (error) {
+        throw new Error(`${location} is invalid: ${String(error)}`, { cause: error });
+    }
+    const record = requireRecord(value, location, ['schema_version', 'global_agent_skills', 'hosts']);
+    if (record.schema_version !== 1)
+        throw new Error(`${location} must use schema_version: 1`);
+    const globalLocation = `${location}.global_agent_skills`;
+    const global = requireRecord(record.global_agent_skills, globalLocation, ['home_rel_path', 'skills_dir_name']);
+    if (!Array.isArray(record.hosts) || record.hosts.length === 0)
+        throw new TypeError(`${location}.hosts must be a non-empty array`);
+    const hosts = record.hosts.map((host, index) => readHost(host, `${location}.hosts[${index}]`));
+    const names = new Set(['all']);
+    for (const host of hosts) {
+        for (const name of [host.id, ...host.aliases ?? []]) {
+            if (names.has(name))
+                throw new Error(`${location} has a duplicate or reserved host id/alias: "${name}"`);
+            names.add(name);
+        }
+    }
+    return {
+        globalAgentSkills: {
+            homeRelPath: requireRelativePath(global.home_rel_path, `${globalLocation}.home_rel_path`),
+            skillsDirName: requirePathSegment(global.skills_dir_name, `${globalLocation}.skills_dir_name`),
+        },
+        hosts,
+    };
+}
+function requireRecord(value, location, allowedKeys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError(`${location} must be a mapping`);
+    const record = value;
+    const unknownKey = allowedKeys && Object.keys(record).find(key => !allowedKeys.includes(key));
+    if (unknownKey !== undefined)
+        throw new Error(`${location} has an unknown field "${unknownKey}"`);
+    return record;
+}
+function requireString(value, location) {
+    if (typeof value !== 'string' || value.trim().length === 0 || value.trim() !== value)
+        throw new TypeError(`${location} must be a non-empty string without surrounding whitespace`);
+    return value;
+}
+function requireRelativePath(value, location) {
+    const configured = requireString(value, location);
+    const normalized = configured.replaceAll('\\', '/');
+    if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(configured) || /^[A-Za-z]:/u.test(normalized) || normalized.includes('\0') || normalized.split('/').includes('..'))
+        throw new Error(`${location} must be a relative path without parent traversal`);
+    return normalized;
+}
+function requirePathSegment(value, location) {
+    const configured = requireRelativePath(value, location);
+    if (configured === '.' || configured.includes('/'))
+        throw new Error(`${location} must be a single file or directory name`);
+    return configured;
+}
+function optionalBoolean(value, location) {
+    if (value !== undefined && typeof value !== 'boolean')
+        throw new TypeError(`${location} must be boolean`);
+    return value;
+}
+function optionalStringArray(value, location) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new TypeError(`${location} must be an array of strings`);
+    return value.map((entry, index) => requireString(entry, `${location}[${index}]`));
+}
+function optionalRecord(value, location) {
+    return value === undefined ? undefined : requireRecord(value, location);
+}
+function readHost(value, location) {
+    const record = requireRecord(value, location, ['id', 'aliases', 'home_rel_path', 'skills_dir_name', 'excluded_skills', 'project_skills', 'mcp']);
+    const id = requireString(record.id, `${location}.id`);
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(id))
+        throw new Error(`${location}.id must contain lowercase letters, digits, and hyphens`);
+    const excludedSkills = optionalStringArray(record.excluded_skills, `${location}.excluded_skills`)
+        ?.map((skill, index) => requirePathSegment(skill, `${location}.excluded_skills[${index}]`));
+    return {
+        id,
+        aliases: optionalStringArray(record.aliases, `${location}.aliases`),
+        homeRelPath: requireRelativePath(record.home_rel_path, `${location}.home_rel_path`),
+        skillsDirName: record.skills_dir_name === undefined ? undefined : requirePathSegment(record.skills_dir_name, `${location}.skills_dir_name`),
+        excludedSkills,
+        projectSkills: optionalBoolean(record.project_skills, `${location}.project_skills`),
+        mcp: record.mcp === undefined ? undefined : readMcpProjection(record.mcp, `${location}.mcp`),
+    };
+}
+function readMcpProjection(value, location) {
+    const record = requireRecord(value, location, [
+        'home_rel_path',
+        'rel_dir',
+        'file_name',
+        'servers_key',
+        'format',
+        'require_host_home',
+        'default_top_level',
+        'server_defaults',
+        'server_overrides',
+        'server_command_format',
+    ]);
+    const format = record.format;
+    if (format !== 'json' && format !== 'toml')
+        throw new Error(`${location}.format must be "json" or "toml"`);
+    const serverCommandFormat = record.server_command_format;
+    if (serverCommandFormat !== undefined && serverCommandFormat !== 'command-and-args' && serverCommandFormat !== 'command-array')
+        throw new Error(`${location}.server_command_format must be "command-and-args" or "command-array"`);
+    const overrides = optionalRecord(record.server_overrides, `${location}.server_overrides`);
+    return {
+        homeRelPath: record.home_rel_path === undefined ? undefined : requireRelativePath(record.home_rel_path, `${location}.home_rel_path`),
+        relDir: requireRelativePath(record.rel_dir, `${location}.rel_dir`),
+        fileName: requirePathSegment(record.file_name, `${location}.file_name`),
+        serversKey: requireString(record.servers_key, `${location}.servers_key`),
+        format,
+        requireHostHome: optionalBoolean(record.require_host_home, `${location}.require_host_home`),
+        defaultTopLevel: optionalRecord(record.default_top_level, `${location}.default_top_level`),
+        serverDefaults: optionalRecord(record.server_defaults, `${location}.server_defaults`),
+        serverOverrides: overrides === undefined
+            ? undefined
+            : Object.fromEntries(Object.entries(overrides).map(([name, override]) => [name, requireRecord(override, `${location}.server_overrides.${name}`)])),
+        serverCommandFormat,
+    };
+}
+export function findHostConfig(id) {
+    const canonical = resolveHostId(id);
+    return canonical ? HOST_CONFIGS.find(host => host.id === canonical) : undefined;
+}
+export function resolveHostId(id) {
+    return HOST_CONFIGS.find(host => host.id === id || host.aliases?.includes(id))?.id;
+}
+function resolveUserRelativePath(userHome, relPath) {
+    return path.join(userHome, ...relPath.split(/[\\/]+/u).filter(Boolean));
+}
+export function resolveGlobalAgentSkillsPath(userHome) {
+    return path.join(resolveUserRelativePath(userHome, GLOBAL_AGENT_SKILLS.homeRelPath), GLOBAL_AGENT_SKILLS.skillsDirName);
+}
+export function resolveHostPaths(config, userHome) {
+    const hostHome = resolveUserRelativePath(userHome, config.homeRelPath);
+    return {
+        hostHome,
+        skillsDirName: config.skillsDirName ?? 'skills',
+        excludedSkills: config.excludedSkills ?? [],
+        projectSkills: config.projectSkills ?? true,
+        mcpHome: config.mcp?.homeRelPath ? resolveUserRelativePath(userHome, config.mcp.homeRelPath) : hostHome,
+        mcp: config.mcp,
+    };
+}

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

@@ -1,5 +1,5 @@
-import type { McpProjection } from '../../constants/hosts.js';
 import type { LinkEntry } from './links.js';
+import type { McpProjection } from './types/hosts.js';
 import type { VendorManifest } from './vendors.js';
 export declare function resolveSetupCommandExecutable(command: string, windowsCommandShim?: boolean): string;
 export declare function shouldUseShellForSetupCommand(command: string, windowsCommandShim?: boolean): boolean;

package/dist/scripts/lib/install.js

@@ -2,8 +2,8 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { findHostConfig, resolveGlobalAgentSkillsPath, resolveHostPaths } from '../../constants/hosts.js';
 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 { requireRoleName } from './role-assets.js';

package/dist/scripts/lib/tool.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { HOST_IDS, resolveHostId } from '../../constants/hosts.js';
+import { HOST_IDS, resolveHostId } from './hosts.js';
 import { ensureGlobalSkillLink, ensureInstallRoot, getDefaultInstallPaths, projectHostById, runSkillSetupCommands, } from './install.js';
 import { resolveRoleManifestPath } from './roles.js';
 import { cleanupEmptyVendorSkillDirectories, rebuildVendorAssets } from './vendor-staging.js';

package/dist/scripts/lib/{capability-types.d.ts → types/capabilities.d.ts}

@@ -1,4 +1,4 @@
-import type { VendorProjection, VendorRepo } from './manifest-types.js';
+import type { VendorProjection, VendorRepo } from './manifest.js';
 /** Capability ids are discovered from capability directories containing capability.yaml. */
 export type CapabilityName = string;
 export interface CapabilityDefinition {

package/dist/{constants → scripts/lib/types}/hosts.d.ts

@@ -30,20 +30,14 @@ export interface HostConfig {
     /** 角色可选 MCP 中性源到该宿主配置的投影规则。 */
     mcp?: McpProjection;
 }
-/** 所有角色都必须获得的 canonical skills 公共层，不是可选宿主。 */
-export declare const GLOBAL_AGENT_SKILLS: {
-    readonly homeRelPath: ".agents";
-    readonly skillsDirName: "skills";
-};
-/**
- * 公共分发层登记 canonical skills 与角色可选 MCP 的宿主投影规则。
- * Agents、commands、hooks、settings 等宿主原生资产由角色的项目初始化器安装。
- */
-export declare const HOST_CONFIGS: HostConfig[];
-/** 所有已登记宿主 ID，供显式 `--host` 校验与帮助输出使用。 */
-export declare const HOST_IDS: string[];
-export declare function findHostConfig(id: string): HostConfig | undefined;
-export declare function resolveHostId(id: string): string | undefined;
+export interface AgentSkillsConfig {
+    homeRelPath: string;
+    skillsDirName: string;
+}
+export interface HostDeclaration {
+    globalAgentSkills: AgentSkillsConfig;
+    hosts: HostConfig[];
+}
 export interface ResolvedHostPaths {
     hostHome: string;
     skillsDirName: string;
@@ -52,5 +46,3 @@ export interface ResolvedHostPaths {
     mcpHome: string;
     mcp?: McpProjection;
 }
-export declare function resolveGlobalAgentSkillsPath(userHome: string): string;
-export declare function resolveHostPaths(config: HostConfig, userHome: string): ResolvedHostPaths;

package/dist/scripts/lib/types/hosts.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,5 +1,5 @@
-import type { RolePackageConfig, SetupCommand, Vendor, VendorManifest } from './manifest-types.js';
-export type { RolePackageConfig, RolePackageInstall, SetupCommand, SkillConfig, SkillDef, Vendor, VendorLink, VendorManifest, VendorNode, VendorProjection, VendorRepo, VendorsConfig, } from './manifest-types.js';
+import type { RolePackageConfig, SetupCommand, Vendor, VendorManifest } from './types/manifest.js';
+export type { RolePackageConfig, RolePackageInstall, SetupCommand, SkillConfig, SkillDef, Vendor, VendorLink, VendorManifest, VendorNode, VendorProjection, VendorRepo, VendorsConfig, } from './types/manifest.js';
 export declare function normalizePath(value: string): string;
 export declare function rolePackageSetupCommands(packages?: RolePackageConfig[]): SetupCommand[];
 /**

package/dist/scripts/lib/vendors.js

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL, URL } from 'node:url';
 import { parseDocument } from 'yaml';
-import { HOST_IDS } from '../../constants/hosts.js';
 import { CAPABILITY_NAMES, composeCapabilities } from './capabilities.js';
+import { HOST_IDS } from './hosts.js';
 import { flattenedSkillName, flattenedVendorSkillTarget } from './skill-projection.js';
 const vendorNamePattern = /^[A-Za-z0-9][\w-]*$/u;
 const npmPackageNamePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;

package/dist/scripts/lib/verify.js

@@ -2,7 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import kleur from 'kleur';
-import { findHostConfig, resolveGlobalAgentSkillsPath, resolveHostPaths } from '../../constants/hosts.js';
+import { findHostConfig, resolveGlobalAgentSkillsPath, resolveHostPaths } from './hosts.js';
 import { applyMcpServerProjection, readInstalledMcpServers, readTomlMcpServerNames } from './install.js';
 import { DEFAULT_ROLE } from './roles.js';
 /** Verify the mandatory canonical skills layer shared by every role and host. */

package/hosts/README.md

@@ -0,0 +1,58 @@
+# 宿主声明
+
+`hosts.yaml` 是公共安装器的宿主配置来源，与角色的 `role.yaml`、能力的 `capability.yaml` 一样采用 YAML。这里维护配置数据；`scripts/lib/hosts.ts` 负责加载、校验、别名查找和路径解析，类型位于 `scripts/lib/types/hosts.ts`。
+
+声明随 npm 包分发。源码运行和打包后的 CLI 都从自身所在的包定位声明，不依赖用户的当前工作目录。字段使用 `snake_case`，加载器转换为运行时使用的 `camelCase`。
+
+## 添加宿主
+
+在 `hosts.yaml` 的 `hosts` 数组中追加条目；数组顺序也是帮助输出和 `--host all` 的处理顺序。角色的 `hosts: all` 自动包含新增宿主，显式列出的角色需自行加入新 ID。
+
+```yaml
+- id: example
+  aliases: [example desktop]
+  home_rel_path: .example
+  project_skills: false
+  mcp:
+    rel_dir: .
+    file_name: mcp.json
+    servers_key: mcpServers
+    format: json
+    server_defaults:
+      type: stdio
+```
+
+`id` 使用小写字母、数字和连字符；别名仅供 CLI 输入，角色声明必须使用 ID。所有 ID 和别名必须唯一，`all` 为保留名称。
+
+## 字段
+
+顶层必须包含 `schema_version: 1`、`global_agent_skills` 和非空的 `hosts`。`global_agent_skills` 声明所有角色共享的 skills 目录，当前为 `~/.agents/skills`。
+
+| 宿主字段 | 含义 |
+| --- | --- |
+| `id` | 宿主 ID，必填 |
+| `aliases` | 可选的 CLI 别名列表 |
+| `home_rel_path` | 相对用户 home 的宿主目录，必填 |
+| `skills_dir_name` | 私有 skills 目录名，默认 `skills` |
+| `excluded_skills` | 最终宿主投影时排除的 skill 名称列表 |
+| `project_skills` | 是否创建私有 skills 投影，默认 `true`；`false` 表示宿主复用 canonical skills |
+| `mcp` | 可选的 MCP 投影配置 |
+
+| MCP 字段 | 含义 |
+| --- | --- |
+| `home_rel_path` | MCP 配置的根目录，相对用户 home；默认使用宿主目录 |
+| `rel_dir` | 配置文件相对 MCP 根目录的位置，必填；`.` 表示根目录 |
+| `file_name` | 配置文件名，必填 |
+| `servers_key` | 宿主使用的 MCP servers 字段名，必填 |
+| `format` | `json` 或 `toml`，必填 |
+| `require_host_home` | 为 `true` 时，只有宿主目录存在才写入 MCP |
+| `default_top_level` | 新配置的顶层默认字段，不覆盖已有用户字段 |
+| `server_defaults` | 每个 server 的默认字段，不覆盖源配置 |
+| `server_overrides` | 按 server 名称指定宿主适配字段 |
+| `server_command_format` | `command-and-args`（默认）或 `command-array` |
+
+路径统一使用 `/`，运行时按系统转换。目录路径必须相对且不含 `..`；文件名、skills 目录名和排除的 skill 名称必须为单个路径段。加载器拒绝未知字段、错误类型、重复 YAML key、YAML alias 和冲突的 ID/别名。
+
+宿主原生 agents、commands、hooks、settings 由角色的项目初始化器安装。这里负责用户级 skills 和 MCP 的公共投影。
+
+修改后运行 `pnpm run lint:check`、`pnpm run typecheck`、`pnpm test` 和 `pnpm run verify:packed-airules`，验证声明、安装行为及 npm 包中的加载路径。

package/hosts/hosts.yaml

@@ -0,0 +1,134 @@
+schema_version: 1
+
+# 所有角色共享的 canonical skills 目录。
+global_agent_skills:
+  home_rel_path: .agents
+  skills_dir_name: skills
+
+# 路径相对于用户 home，统一使用 /；顺序决定 --host all 和帮助输出顺序。
+# 宿主原生 agents、commands、hooks、settings 由角色的项目初始化器安装。
+hosts:
+  - id: claude
+    home_rel_path: .claude
+    mcp:
+      home_rel_path: .
+      rel_dir: .
+      file_name: .claude.json
+      servers_key: mcpServers
+      format: json
+      require_host_home: true
+      server_defaults:
+        type: stdio
+      server_overrides:
+        codegraph:
+          args: [serve, --mcp]
+
+  - id: codex
+    home_rel_path: .codex
+    project_skills: false
+    mcp:
+      rel_dir: .
+      file_name: config.toml
+      servers_key: mcp_servers
+      format: toml
+      server_overrides:
+        codegraph:
+          args: [serve, --mcp]
+
+  - id: hermes
+    aliases: [hermes desktop]
+    home_rel_path: AppData/Local/hermes
+    project_skills: false
+
+  - id: cursor
+    home_rel_path: .cursor
+    skills_dir_name: skills-cursor
+    project_skills: false
+    mcp:
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      server_defaults:
+        type: stdio
+
+  - id: qoderwork
+    home_rel_path: .qoderwork
+
+  - id: trae
+    home_rel_path: .trae
+    project_skills: false
+    mcp:
+      home_rel_path: AppData/Roaming/Trae/User
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      default_top_level:
+        inputs: []
+
+  - id: trae-cn
+    home_rel_path: .trae-cn
+    project_skills: false
+    mcp:
+      home_rel_path: AppData/Roaming/Trae CN/User
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      default_top_level:
+        inputs: []
+
+  - id: trae-solo
+    home_rel_path: .trae-solo
+    project_skills: false
+    mcp:
+      home_rel_path: AppData/Roaming/TRAE SOLO/User
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      default_top_level:
+        inputs: []
+
+  - id: trae-solo-cn
+    home_rel_path: .trae-solo-cn
+    project_skills: false
+    mcp:
+      home_rel_path: AppData/Roaming/TRAE SOLO CN/User
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      default_top_level:
+        inputs: []
+
+  - id: qoder
+    home_rel_path: .qoder
+    project_skills: false
+    mcp:
+      home_rel_path: AppData/Roaming/Qoder/SharedClientCache
+      rel_dir: .
+      file_name: mcp.json
+      servers_key: mcpServers
+      format: json
+      server_defaults:
+        type: stdio
+
+  - id: opencode
+    home_rel_path: .config/opencode
+    project_skills: false
+    mcp:
+      rel_dir: .
+      file_name: opencode.json
+      servers_key: mcp
+      format: json
+      default_top_level:
+        $schema: https://opencode.ai/config.json
+      server_defaults:
+        type: local
+        enabled: true
+      server_overrides:
+        codegraph:
+          args: [serve, --mcp]
+      server_command_format: command-array

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moluoxixi-ai-rules",
   "type": "module",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Remote AI role asset distribution for supported hosts.",
   "license": "MIT",
   "repository": "https://github.com/moluoxixi/AIRules",
@@ -24,6 +24,7 @@
     "bin",
     "capabilities",
     "dist",
+    "hosts",
     "roles/*/role.yaml"
   ],
   "scripts": {

package/dist/constants/hosts.js

@@ -1,167 +0,0 @@
-import path from 'node:path';
-/** 所有角色都必须获得的 canonical skills 公共层，不是可选宿主。 */
-export const GLOBAL_AGENT_SKILLS = {
-    homeRelPath: '.agents',
-    skillsDirName: 'skills',
-};
-/**
- * 公共分发层登记 canonical skills 与角色可选 MCP 的宿主投影规则。
- * Agents、commands、hooks、settings 等宿主原生资产由角色的项目初始化器安装。
- */
-export const HOST_CONFIGS = [
-    {
-        id: 'claude',
-        homeRelPath: '.claude',
-        mcp: {
-            homeRelPath: '.',
-            relDir: '.',
-            fileName: '.claude.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            requireHostHome: true,
-            serverDefaults: { type: 'stdio' },
-            serverOverrides: { codegraph: { args: ['serve', '--mcp'] } },
-        },
-    },
-    {
-        id: 'codex',
-        homeRelPath: '.codex',
-        projectSkills: false,
-        mcp: {
-            relDir: '.',
-            fileName: 'config.toml',
-            serversKey: 'mcp_servers',
-            format: 'toml',
-            serverOverrides: { codegraph: { args: ['serve', '--mcp'] } },
-        },
-    },
-    {
-        id: 'hermes',
-        aliases: ['hermes desktop'],
-        homeRelPath: path.join('AppData', 'Local', 'hermes'),
-        projectSkills: false,
-    },
-    {
-        id: 'cursor',
-        homeRelPath: '.cursor',
-        skillsDirName: 'skills-cursor',
-        projectSkills: false,
-        mcp: {
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            serverDefaults: { type: 'stdio' },
-        },
-    },
-    {
-        id: 'qoderwork',
-        homeRelPath: '.qoderwork',
-    },
-    {
-        id: 'trae',
-        homeRelPath: '.trae',
-        projectSkills: false,
-        mcp: {
-            homeRelPath: path.join('AppData', 'Roaming', 'Trae', 'User'),
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            defaultTopLevel: { inputs: [] },
-        },
-    },
-    {
-        id: 'trae-cn',
-        homeRelPath: '.trae-cn',
-        projectSkills: false,
-        mcp: {
-            homeRelPath: path.join('AppData', 'Roaming', 'Trae CN', 'User'),
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            defaultTopLevel: { inputs: [] },
-        },
-    },
-    {
-        id: 'trae-solo',
-        homeRelPath: '.trae-solo',
-        projectSkills: false,
-        mcp: {
-            homeRelPath: path.join('AppData', 'Roaming', 'TRAE SOLO', 'User'),
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            defaultTopLevel: { inputs: [] },
-        },
-    },
-    {
-        id: 'trae-solo-cn',
-        homeRelPath: '.trae-solo-cn',
-        projectSkills: false,
-        mcp: {
-            homeRelPath: path.join('AppData', 'Roaming', 'TRAE SOLO CN', 'User'),
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            defaultTopLevel: { inputs: [] },
-        },
-    },
-    {
-        id: 'qoder',
-        homeRelPath: '.qoder',
-        projectSkills: false,
-        mcp: {
-            homeRelPath: path.join('AppData', 'Roaming', 'Qoder', 'SharedClientCache'),
-            relDir: '.',
-            fileName: 'mcp.json',
-            serversKey: 'mcpServers',
-            format: 'json',
-            serverDefaults: { type: 'stdio' },
-        },
-    },
-    {
-        id: 'opencode',
-        homeRelPath: path.join('.config', 'opencode'),
-        projectSkills: false,
-        mcp: {
-            relDir: '.',
-            fileName: 'opencode.json',
-            serversKey: 'mcp',
-            format: 'json',
-            defaultTopLevel: { $schema: 'https://opencode.ai/config.json' },
-            serverDefaults: { type: 'local', enabled: true },
-            serverOverrides: { codegraph: { args: ['serve', '--mcp'] } },
-            serverCommandFormat: 'command-array',
-        },
-    },
-];
-/** 所有已登记宿主 ID，供显式 `--host` 校验与帮助输出使用。 */
-export const HOST_IDS = HOST_CONFIGS.map(host => host.id);
-export function findHostConfig(id) {
-    const canonical = resolveHostId(id);
-    return canonical ? HOST_CONFIGS.find(host => host.id === canonical) : undefined;
-}
-export function resolveHostId(id) {
-    return HOST_CONFIGS.find(host => host.id === id || host.aliases?.includes(id))?.id;
-}
-function resolveUserRelativePath(userHome, relPath) {
-    return path.join(userHome, ...relPath.split(/[\\/]+/u).filter(Boolean));
-}
-export function resolveGlobalAgentSkillsPath(userHome) {
-    return path.join(resolveUserRelativePath(userHome, GLOBAL_AGENT_SKILLS.homeRelPath), GLOBAL_AGENT_SKILLS.skillsDirName);
-}
-export function resolveHostPaths(config, userHome) {
-    const hostHome = resolveUserRelativePath(userHome, config.homeRelPath);
-    return {
-        hostHome,
-        skillsDirName: config.skillsDirName ?? 'skills',
-        excludedSkills: config.excludedSkills ?? [],
-        projectSkills: config.projectSkills ?? true,
-        mcpHome: config.mcp?.homeRelPath ? resolveUserRelativePath(userHome, config.mcp.homeRelPath) : hostHome,
-        mcp: config.mcp,
-    };
-}