berry-agent 0.1.0-alpha.1

package/dist/skills/agents.js

@@ -0,0 +1,242 @@
+/**
+ * 声明式子代理解析层（06 §11.6——解析层住 core:skills、机器住 core:subagent）。
+ *
+ * agents/*.md = frontmatter（name/description/tools/requires/skills/model）+ 正文即
+ * 系统提示。发现位置镜像技能位 1-4：project `.agents/agents`（需目录信任）>
+ * user `<dataDir>/agents` > 跨库 `~/.agents/agents` 与 `~/.claude/agents` >
+ * 插件声明载荷；位 5 CLI/动态不纳入、位 6 无出厂位。层序即信任序，
+ * first-wins 同名压制。坏文件 warning 跳过不炸装配（同技能纪律）。
+ *
+ * 本件只产纯数据 def（SubagentDef——contracts 归位）；yaml 解析复用技能
+ * frontmatter 机器（yaml 裸导入白名单不扩——subagent 收 def 零 yaml）。
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+import { canonicalWorkspaceRoot } from '../context/index.js';
+import { parseSkillFrontmatter, validateSkillName, validateSkillRefList } from './frontmatter.js';
+import { SKILL_DESCRIPTION_MAX } from './types.js';
+/**
+ * 从 agents/*.md 全文解析声明式子代理 def。
+ *
+ * 处置逐条（06 §11.6 + §11.2 技能纪律镜像）：
+ *  - frontmatter 坏形（无开闭 --- 等）→ 拒；
+ *  - description 非字符串或空白 → 拒（唯一硬条件——披露段清单行的唯一依据）；
+ *  - description 超 1024 → 截断装载（清单行帽同技能律）；
+ *  - name 缺席 → 回落文件基名（去 .md）；提供时须与基名一致（身份键纪律：
+ *    静态工具名 agent_<name> 与文件名漂移即双名混乱）且过技能名词法
+ *    （物化为工具名的词法安全面）——违例拒（name 是注册键不宽容）；
+ *  - tools/requires/skills 非字符串数组 → 拒；model 非字符串 → 拒；
+ *    skills 项数帽 8/项词法/重复项拒（06 §11.6 形状护栏——存在性归工厂复验）；
+ *  - 正文空（trim 后）→ 拒（正文即系统提示——空正文无装载面）；
+ *  - 未采用字段（license 等生态超集）→ 静默忽略（生态宽容——CC 形可装载）。
+ */
+export function parseAgentDef(raw, context) {
+    const parsed = parseSkillFrontmatter(raw);
+    if ('error' in parsed) {
+        return { error: parsed.error };
+    }
+    const frontmatter = parsed.frontmatter;
+    // description：必填（模型选择依据——声明式工具 description 直传此值）
+    const rawDescription = frontmatter['description'];
+    if (typeof rawDescription !== 'string' || rawDescription.trim() === '') {
+        return { error: 'description 缺席或为空（必填——披露段清单行的唯一依据）' };
+    }
+    const description = rawDescription.length > SKILL_DESCRIPTION_MAX ? rawDescription.slice(0, SKILL_DESCRIPTION_MAX) : rawDescription;
+    // name：缺席回落文件基名（去扩展名）；提供须一致 + 技能名词法（工具名安全面）
+    const stem = basename(context.filePath).replace(/\.md$/i, '');
+    const rawName = frontmatter['name'];
+    const name = typeof rawName === 'string' && rawName !== '' ? rawName : stem;
+    if (name !== stem) {
+        return { error: `name（${name}）与文件基名（${stem}）不一致——agents 文件约定 = 同名文件承载同名子代理` };
+    }
+    const nameErrors = validateSkillName(name);
+    if (nameErrors.length > 0) {
+        return { error: nameErrors.join('；') };
+    }
+    // tools/requires/skills：可选字符串数组（白名单/前置要求/技能注入三键正交——语义执法在机器侧）
+    const tools = parseStringList(frontmatter['tools'], 'tools');
+    if ('error' in tools)
+        return { error: tools.error };
+    const requires = parseStringList(frontmatter['requires'], 'requires');
+    if ('error' in requires)
+        return { error: requires.error };
+    // skills 键形状三验在解析层（帽 8/技能名词法/重复拒——06 §11.6 声明面低宽容）；
+    // 存在性不在此查（装载序晚于装配期物化——存在性归工厂 spawn 时点复验）
+    const skills = parseStringList(frontmatter['skills'], 'skills');
+    if ('error' in skills)
+        return { error: skills.error };
+    const skillRefErrors = skills.value !== undefined ? validateSkillRefList(skills.value) : [];
+    if (skillRefErrors.length > 0) {
+        return { error: skillRefErrors.join('；') };
+    }
+    // model：可选字符串（模型覆盖——启动参数直传工厂）
+    const rawModel = frontmatter['model'];
+    if (rawModel !== undefined && typeof rawModel !== 'string') {
+        return { error: 'model 须为字符串（模型覆盖名）' };
+    }
+    // 正文即系统提示（保留原始缩进——frontmatter 闭合 --- 之后全文）
+    if (parsed.body.trim() === '') {
+        return { error: '正文空（正文即系统提示——空正文无装载面）' };
+    }
+    return {
+        name,
+        description,
+        ...(tools.value !== undefined ? { tools: tools.value } : {}),
+        ...(requires.value !== undefined ? { requires: requires.value } : {}),
+        ...(skills.value !== undefined ? { skills: skills.value } : {}),
+        ...(rawModel !== undefined ? { model: rawModel } : {}),
+        systemPrompt: parsed.body,
+        filePath: context.filePath,
+    };
+}
+/** 字符串数组字段解析（undefined 放行；非数组/含非字符串 → 拒） */
+function parseStringList(value, field) {
+    if (value === undefined)
+        return {};
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        return { error: `${field} 须为字符串数组` };
+    }
+    return { value: value };
+}
+/**
+ * 扁平目录层 provider 工厂：每根目录直扫 `*.md`（不递归——agents 是平铺
+ * 单文件形，非技能目录树形；无 gitignore 机器——树形剪枝纪律不适用平铺面）。
+ * trusted=false → 空扫描 + 单诊断（镜像技能层语义：不入清单即零注入面）。
+ */
+export function createAgentLayerProvider(options) {
+    return {
+        id: options.id,
+        roots: options.roots,
+        ...(options.trusted !== undefined ? { trusted: options.trusted } : {}),
+        scan: async () => {
+            const defs = [];
+            const diagnostics = [];
+            if (options.trusted === false) {
+                return {
+                    defs,
+                    diagnostics: [
+                        {
+                            type: 'warning',
+                            message: 'project 子代理目录未获目录信任锚——整层跳过（04 目录信任条：装载不激活）',
+                            path: options.roots[0],
+                        },
+                    ],
+                };
+            }
+            const seen = options.seenRealPaths ?? new Set();
+            const seenNames = new Set(); // 同层同名（跨文件声明 name 撞）——后到跳过带诊断
+            for (const root of options.roots) {
+                if (!existsSync(root))
+                    continue;
+                let entries;
+                try {
+                    entries = await readdir(root, { withFileTypes: true });
+                }
+                catch {
+                    continue; // 读失败（权限/竞态消失）——跳过继续
+                }
+                // 文件名排序——同层装载序确定（readdir 序不保证）
+                const files = entries
+                    .filter((entry) => entry.isFile() && /\.md$/i.test(entry.name))
+                    .map((entry) => entry.name)
+                    .sort();
+                for (const fileName of files) {
+                    const filePath = join(root, fileName);
+                    let realPath;
+                    try {
+                        realPath = realpathSync(filePath);
+                    }
+                    catch {
+                        continue; // 断链符号链——跳过
+                    }
+                    if (seen.has(realPath))
+                        continue; // 同文件双发现去重（静默——跨层 symlink 别名）
+                    let raw;
+                    try {
+                        raw = await readFile(realPath, 'utf8');
+                    }
+                    catch (error) {
+                        diagnostics.push({
+                            type: 'warning',
+                            message: `agents 文件读取失败：${error instanceof Error ? error.message : String(error)}`,
+                            path: filePath,
+                        });
+                        continue;
+                    }
+                    seen.add(realPath);
+                    const parsed = parseAgentDef(raw, { filePath });
+                    if ('error' in parsed) {
+                        // 坏文件 warning 跳过不炸装配（06 §11.6——诊断语义同技能坏文件）
+                        diagnostics.push({ type: 'invalid-metadata', message: parsed.error, path: filePath });
+                        continue;
+                    }
+                    if (seenNames.has(parsed.name)) {
+                        diagnostics.push({
+                            type: 'collision',
+                            message: `同层子代理撞名「${parsed.name}」——后到文件跳过（first-wins）`,
+                            path: filePath,
+                        });
+                        continue;
+                    }
+                    seenNames.add(parsed.name);
+                    defs.push(parsed);
+                }
+            }
+            return { defs, diagnostics };
+        },
+    };
+}
+/**
+ * 标准发现层（06 §11.6 位 1-4 镜像技能位）：project > user > 跨库 > 插件。
+ * 位 5 CLI/动态不纳入、位 6 无出厂位（与技能差异两处——无 skill_manage
+ * 写面故无 writable 标记、无宿主出厂 agents）。
+ */
+export function createStandardAgentLayers(options) {
+    const home = options.homeDir ?? homedir();
+    const seen = options.seenRealPaths ?? new Set();
+    return [
+        // 位 1：project `.agents/agents`（canonical 工作区根锚——需目录信任）
+        createAgentLayerProvider({
+            id: 'project',
+            roots: [join(canonicalWorkspaceRoot(options.cwd ?? process.cwd()), '.agents', 'agents')],
+            trusted: options.trustedProject ?? true,
+            seenRealPaths: seen,
+        }),
+        // 位 2：user `<dataDir>/agents`（无需信任——dataDir 缺席跳位，:memory: 形）
+        ...(options.dataDir !== undefined
+            ? [createAgentLayerProvider({ id: 'user', roots: [join(options.dataDir, 'agents')], seenRealPaths: seen })]
+            : []),
+        // 位 3：跨库 `~/.agents/agents` 与 `~/.claude/agents`（生态复用——CC 形可装载）
+        createAgentLayerProvider({
+            id: 'cross-repo',
+            roots: [join(home, '.agents', 'agents'), join(home, '.claude', 'agents')],
+            seenRealPaths: seen,
+        }),
+        // 位 4：插件声明载荷层（信任序低于主人位——first-wins 全序表达）
+        ...(options.pluginLayers ?? []).map((layer) => createAgentLayerProvider({ ...layer, seenRealPaths: seen })),
+    ];
+}
+/**
+ * 按层序合并（first-wins 同名压制——层序即信任序，project 恒压 user）。
+ * 后层同名静默压制（主人位既定，后者诊断只作装载日志不作冲突面——
+ * 与同层撞名的 collision 诊断分立）。
+ */
+export async function collectAgentDefs(providers) {
+    const defs = [];
+    const diagnostics = [];
+    const seenNames = new Set();
+    for (const provider of providers) {
+        const scan = await provider.scan();
+        diagnostics.push(...scan.diagnostics);
+        for (const def of scan.defs) {
+            if (seenNames.has(def.name))
+                continue; // 跨层同名——先到主人位胜出（first-wins）
+            seenNames.add(def.name);
+            defs.push(def);
+        }
+    }
+    return { defs, diagnostics };
+}

package/dist/skills/codes.js

@@ -0,0 +1,51 @@
+/**
+ * skills 域错误码注册（06 篇 §11 技能机制 + §12.1 skill_manage——SKILLS_ 前缀族）。
+ *
+ * 前缀族在 contracts/errors.ts ERROR_CODE_PREFIXES 已注册（02 §5.3 #1）；八码全为
+ * 落码批定名（规范具名面只有机制语义无码名——06 §11.2 校验族 / §12.1 create 亮拒·
+ * patch 三拒 / provider 链装配期撞名）。本文件由模块公开面 index.ts 引入
+ * （注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'SKILLS_NAME_INVALID',
+        module: 'skills',
+        description: '技能名词法/长度违例（≤64、^[a-z0-9-]+$、首尾与连续连字符禁——skill_manage create 载荷校验面；装载面同规则仅警告不拒）',
+    },
+    {
+        code: 'SKILLS_NAME_EXISTS',
+        module: 'skills',
+        description: 'skill_manage create 同名亮拒不覆写——判据 = 注册表在册名 ∪ 盘上文件在场（坏 frontmatter 文件对 get() 隐身，只查在册名会静默毁文件，06 §12.1）',
+    },
+    {
+        code: 'SKILLS_CONTENT_INVALID',
+        module: 'skills',
+        description: 'skill_manage create 载荷校验拒——description 非空且 ≤1024 / 正文非空（06 §12.1）',
+    },
+    {
+        code: 'SKILLS_NOT_FOUND',
+        module: 'skills',
+        description: '注册表查无该名——skill_manage patch 目标不在册（先刷新后改；盘上坏文件不入册者同报，修坏文件走人面）与 load_skill name 未命中（指路 <available_skills> 清单）两消费面（06 §12.1/§11.5）',
+    },
+    {
+        code: 'SKILLS_LAYER_READONLY',
+        module: 'skills',
+        description: 'skill_manage patch 仅 project 层可改——user/package 层拒并指路人面（06 §12.1 patch 域条款）',
+    },
+    {
+        code: 'SKILLS_PATCH_MATCH_INVALID',
+        module: 'skills',
+        description: 'skill_manage patch find 串零匹配或多匹配均拒（不猜改点——与节级寻址歧义报错不猜同律，06 §11.3/§12.1）',
+    },
+    {
+        code: 'SKILLS_WRITE_ROOT_DENIED',
+        module: 'skills',
+        description: 'skill_manage create/patch 写点前置可写根断言拒——物理写（含 mkdir）前走装配注入的可写根推导，read-only 档空根即拒（06 §12.1；绕过 fence 的直写即缺陷）',
+    },
+    {
+        code: 'SKILLS_PROVIDER_CONFLICT',
+        module: 'skills',
+        description: '技能 provider 撞名拒——同 id 两方注册属装配期错误 fail-loud（03 skills_change 载荷 = provider id 清单，id 即身份）',
+    },
+]);

package/dist/skills/discovery.js

@@ -0,0 +1,266 @@
+/**
+ * 技能发现层（06 §11.4 发现位置与优先级——六位序列的位 1/2/3/4/6 落码形态；
+ * 位 5 CLI/动态注入不纳入 v1）。
+ *
+ * 发现规则（pi 蓝本同律）：目录含 SKILL.md 即为技能根不再递归；否则递归子目录。
+ * 尊重 .gitignore——前缀化锚定判据与检索族（tools/search.ts）/快照遍历三副本
+ * 同笔同判（06 §11.4 括注：模式体去尾随目录标记斜杠后含斜杠或带前导 / = 锚定
+ * 本层精确匹配；纯 basename 模式前缀化插目录通配前缀（`**`+`/`）保本层与
+ * symlink 目录跟随（realpath 去重防环——与 pi 同律；检索族防环不跟随是遍历
+ * 面差异：技能面文件量小且 realpath 集合天然断环）。
+ *
+ * 信任语义（04 目录信任条）：project 层需目录信任锚——trusted=false 时整层跳过
+ * 扫描并落诊断（装载不激活的 v1 实现：不入清单即零注入面）；user/跨库/出厂层
+ * 无需信任（出厂 = 与官方插件同源分发恒扫描）。
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ignore from 'ignore';
+import { canonicalWorkspaceRoot } from '../context/index.js';
+import { loadSkillFromText } from './frontmatter.js';
+/** 遍历常量剪枝（与检索族同表语义：依赖目录与 git 元数据） */
+const PRUNE_DIRS = new Set(['node_modules', '.git']);
+/** 平台路径分隔符归一为 /（gitignore 模式语义在 posix 路径上） */
+function toPosix(p) {
+    return p.split(sep).join('/');
+}
+/**
+ * 单行 gitignore 模式前缀化（06 §11.4 锚定判据——与检索族/快照遍历三副本同笔
+ * 同判；实现与 tools/search.ts 逐分支对齐）。注释/空行丢弃；`!` 否定与 `\!`/
+ * `\#` 转义保留；纯 basename 模式前缀化插目录通配前缀（`**`+`/`）保深层同配。
+ */
+function prefixIgnorePattern(line, prefix) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('#') && !trimmed.startsWith('\\#'))
+        return null;
+    let pattern = line;
+    let negated = false;
+    if (pattern.startsWith('!')) {
+        negated = true;
+        pattern = pattern.slice(1);
+    }
+    else if (pattern.startsWith('\\!')) {
+        pattern = pattern.slice(1);
+    }
+    // 前导 / = 显式锚定标记（先记下再去掉；锚定形相对本目录精确匹配）
+    const rooted = pattern.startsWith('/');
+    if (rooted)
+        pattern = pattern.slice(1);
+    if (!prefix) {
+        // 根 .gitignore 锚定形保留前导 /（git 语义：前导分隔符 = 锚定本层——剥掉
+        // 透传会把锚定降级成任意层匹配；检索族同笔同判同修）
+        const passed = rooted ? `/${pattern}` : pattern;
+        return negated ? `!${passed}` : passed;
+    }
+    const body = pattern.endsWith('/') ? pattern.slice(0, -1) : pattern;
+    const anchored = rooted || body.includes('/');
+    const prefixed = anchored ? `${prefix}${pattern}` : `${prefix}**/${pattern}`;
+    return negated ? `!${prefixed}` : prefixed;
+}
+/** 读 dir 下 .gitignore 并按所在目录前缀化挂上匹配器（嵌套规则只作用本子树） */
+async function addIgnoreRules(matcher, dir, rootDir) {
+    let content;
+    try {
+        content = await readFile(join(dir, '.gitignore'), 'utf8');
+    }
+    catch {
+        return; // 无 .gitignore 或读失败——本目录无额外规则
+    }
+    const prefix = toPosix(relative(rootDir, dir));
+    const prefixed = prefix ? `${prefix}/` : '';
+    const patterns = content
+        .split(/\r?\n/)
+        .map((line) => prefixIgnorePattern(line, prefixed))
+        .filter((line) => line !== null);
+    if (patterns.length > 0)
+        matcher.add(patterns);
+}
+/**
+ * 扫描一个技能层根目录（06 §11.4「目录含 SKILL.md 即为技能根不再递归」）。
+ *
+ * 缺席目录 = 空结果不诊断（跨库目录 ~/.claude/skills 等常态缺席）。
+ * realpath 去重集由调用方传入（跨根共享——同文件经符号链双发现的去重锚）。
+ */
+export async function scanSkillsDir(dir, options = { providerId: 'unknown' }) {
+    const seen = options.seenRealPaths ?? new Set();
+    const result = await scanDirInternal(resolve(dir), resolve(dir), options.providerId, ignore(), seen);
+    return result;
+}
+/** 实际递归（每层目录同一规则：本目录含 SKILL.md 即技能根不再下钻；否则递归子目录） */
+async function scanDirInternal(dir, root, providerId, matcher, seen) {
+    const skills = [];
+    const diagnostics = [];
+    if (!existsSync(dir))
+        return { skills, diagnostics };
+    await addIgnoreRules(matcher, dir, root);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return { skills, diagnostics }; // 读失败（权限/竞态消失）——跳过继续
+    }
+    // 第一遍：本目录含 SKILL.md 即技能根（不递归）——发现即返回
+    const skillMd = entries.find((e) => e.name === 'SKILL.md');
+    if (skillMd !== undefined) {
+        const filePath = join(dir, 'SKILL.md');
+        if (!ignoredPath(matcher, root, filePath)) {
+            const loaded = await loadSkillFile(filePath, providerId, seen);
+            skills.push(...loaded.skills);
+            diagnostics.push(...loaded.diagnostics);
+        }
+        return { skills, diagnostics };
+    }
+    // 第二遍：递归子目录（点目录与依赖目录剪枝；符号链目录跟随——realpath 断环）
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || PRUNE_DIRS.has(entry.name))
+            continue;
+        const fullPath = join(dir, entry.name);
+        let isDirectory = entry.isDirectory();
+        if (entry.isSymbolicLink()) {
+            try {
+                isDirectory = (await stat(fullPath)).isDirectory();
+            }
+            catch {
+                continue; // 断链——跳过
+            }
+        }
+        if (!isDirectory)
+            continue; // 技能面只认 <名>/SKILL.md 目录形（散 .md 非技能）
+        if (ignoredPath(matcher, root, fullPath, true))
+            continue;
+        const sub = await scanDirInternal(fullPath, root, providerId, matcher, seen);
+        skills.push(...sub.skills);
+        diagnostics.push(...sub.diagnostics);
+    }
+    return { skills, diagnostics };
+}
+/** 路径 gitignore 判定（目录双测带/不带尾斜杠——兼容 `dir/` 与 `dir` 两种写法） */
+function ignoredPath(matcher, root, fullPath, isDir = false) {
+    const rel = toPosix(relative(root, fullPath));
+    if (rel === '')
+        return false; // 根自身不判
+    return isDir ? matcher.ignores(rel) || matcher.ignores(`${rel}/`) : matcher.ignores(rel);
+}
+/** 单 SKILL.md 装载（读失败/realpath 已见 → 跳过；校验诊断透传） */
+async function loadSkillFile(filePath, providerId, seen) {
+    const diagnostics = [];
+    let realPath;
+    try {
+        realPath = realpathSync(filePath);
+    }
+    catch {
+        return { skills: [], diagnostics }; // 断链符号链——跳过
+    }
+    if (seen.has(realPath))
+        return { skills: [], diagnostics }; // 同文件双发现去重（静默）
+    let raw;
+    try {
+        raw = await readFile(realPath, 'utf8');
+    }
+    catch (error) {
+        diagnostics.push({
+            type: 'warning',
+            message: `SKILL.md 读取失败：${error instanceof Error ? error.message : String(error)}`,
+            path: filePath,
+        });
+        return { skills: [], diagnostics };
+    }
+    seen.add(realPath);
+    const loaded = loadSkillFromText(raw, { filePath, providerId });
+    return { skills: loaded.skill !== undefined ? [loaded.skill] : [], diagnostics: [...loaded.diagnostics] };
+}
+/**
+ * 目录扫描 provider 工厂（标准层与插件声明载荷层共用——03 §6.1 mount 即注册）。
+ *
+ * trusted=false → 空扫描 + 单诊断（装载不激活：不入清单即零注入面——信任授予
+ * 是用户动作，模型不可自授）。
+ */
+export function createDirProvider(options) {
+    return {
+        id: options.id,
+        roots: options.roots,
+        ...(options.writable !== undefined ? { writable: options.writable } : {}),
+        ...(options.trusted !== undefined ? { trusted: options.trusted } : {}),
+        // passSeen = 本轮扫描 pass 的去重集（registry.refresh 铸新集透传——层间
+        // 同文件去重；缺省独立集 = provider 自身多根跨根去重）。不持有跨 refresh
+        // 持久集（曾致二次 refresh 起 realpath 全「已见」整册静默清空）
+        scan: async (passSeen) => {
+            if (options.trusted === false) {
+                return {
+                    skills: [],
+                    diagnostics: [
+                        {
+                            type: 'warning',
+                            message: 'project 技能目录未获目录信任锚——整层跳过（04 目录信任条：装载不激活）',
+                            path: options.roots[0],
+                        },
+                    ],
+                };
+            }
+            const skills = [];
+            const diagnostics = [];
+            const seen = passSeen ?? new Set();
+            for (const root of options.roots) {
+                const scanned = await scanSkillsDir(root, { providerId: options.id, seenRealPaths: seen });
+                skills.push(...scanned.skills);
+                diagnostics.push(...scanned.diagnostics);
+            }
+            return { skills, diagnostics };
+        },
+    };
+}
+/**
+ * 出厂技能目录定位（06 §11.4 位 6：`<包根>/skills/`——包根 = 发现模块位置上推
+ * 两级；源码 src/skills/* 与产物 dist/skills/* 双形态同构，上推两级皆包根）。
+ */
+export function resolveFactorySkillsDir(moduleUrl = import.meta.url) {
+    // dist/skills/discovery.js → dirname 两次 = 包根（src 形同理）
+    const moduleDir = dirname(fileURLToPath(moduleUrl));
+    return resolve(moduleDir, '..', '..', 'skills');
+}
+/**
+ * 构造六位序列标准层（注册序即优先序——project > user > 跨库 > 插件 > 出厂；
+ * provider 注册序即优先序 06 §11.3 护栏②，同名 first-wins 由扫描序表达）。
+ *
+ * realpath 去重集 pass 域律：各层不持有跨 refresh 持久去重集——层间同文件
+ * 去重由注册表 refresh 时铸新集经 scan(passSeen) 透传（曾因共享持久集致
+ * 第二次 refresh 起 realpath 全「已见」整册静默清空——装配尾 resync 与
+ * skill_manage 写后刷新共用径全灭，回归锁在 discovery.test.ts）。
+ */
+export function createStandardLayers(options) {
+    const home = options.homeDir ?? homedir();
+    const layers = [
+        // 位 1：project `.agents/skills`（canonical 工作区根锚——与 memory owner_key/
+        // project 域键同源一处实现；需目录信任、可改写）
+        createDirProvider({
+            id: 'project',
+            roots: [join(canonicalWorkspaceRoot(options.cwd ?? process.cwd()), '.agents', 'skills')],
+            writable: true,
+            trusted: options.trustedProject ?? true,
+        }),
+        // 位 2：user `<dataDir>/skills`（无需信任）——缺席跳过（:memory: 形无
+        // 用户技能面，不造空根目录）
+        ...(options.dataDir !== undefined
+            ? [createDirProvider({ id: 'user', roots: [join(options.dataDir, 'skills')] })]
+            : []),
+        // 位 3：跨库 `~/.agents/skills` 与 `~/.claude/skills`（agentskills.io 生态复用）
+        createDirProvider({
+            id: 'cross-repo',
+            roots: [join(home, '.agents', 'skills'), join(home, '.claude', 'skills')],
+        }),
+        // 位 4：插件声明载荷层（信任序低于主人位——first-wins 全序表达）
+        ...(options.pluginLayers ?? []).map((layer) => createDirProvider({ ...layer })),
+        // 位 6：宿主出厂 `<包根>/skills/`（恒扫描、末位——用户/project 同名恒压出厂件）
+        createDirProvider({
+            id: 'factory',
+            roots: [options.factoryDir ?? resolveFactorySkillsDir()],
+        }),
+    ];
+    return layers;
+}