berry-agent 0.1.0-alpha.1

package/dist/skills/frontmatter.js

@@ -0,0 +1,215 @@
+/**
+ * SKILL.md frontmatter 解析与校验（06 §11.2——向 agentskills.io 标准靠拢；
+ * 装载层护栏：description 超 1024 截断装载 + invalid-metadata 警告注明「已截断」、
+ * name 超长不截断仅警告——name 是身份键，截断会伪造碰撞）。
+ *
+ * 宽容度语义：校验失败一律警告 + 对应处置（截断/丢弃字段/跳过文件）不抛——
+ * 坏文件不炸装载（与 berry 装载实证同律）；唯一拒载条件 = description 缺席
+ * （清单行 = 模型选择依据，无描述即无渐进披露面）与 frontmatter 不可解析。
+ */
+import { basename, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { SKILL_DESCRIPTION_MAX, SKILL_NAME_MAX, SKILL_PROVENANCE_MEMORIES_MAX, SKILL_REFS_MAX } from './types.js';
+import { splitSkillSections } from './sections.js';
+/**
+ * 解析 SKILL.md：剥 BOM、CRLF/CR 统一 LF、`---` 开闭行包裹的 YAML 头。
+ *
+ * 开闭行判定：首行恰 `---`（行尾空白容差）；闭合 = 后续首个恰 `---` 的行。
+ * 无开行/无闭合行 → 错误（SKILL.md 的 description 必填，头缺失即无装载面）；
+ * 空头（`---` 紧邻 `---`）与字面 null 按空映射续走——description 缺席判在装载层。
+ */
+export function parseSkillFrontmatter(raw) {
+    // BOM 剥离（U+FEFF——编辑器写入时常见；charCode 判比字面量嵌入可检）
+    const unbommed = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const normalized = unbommed.replace(/\r\n?/g, '\n');
+    const lines = normalized.split('\n');
+    const first = (lines[0] ?? '').trimEnd();
+    if (first !== '---') {
+        return { error: '缺 frontmatter 开行 ---' };
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? '').trimEnd() === '---') {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return { error: 'frontmatter 未闭合（缺 --- 闭合行）' };
+    }
+    const yamlText = lines.slice(1, closeIndex).join('\n');
+    let parsed;
+    if (yamlText.trim() !== '') {
+        try {
+            parsed = parseYaml(yamlText);
+        }
+        catch (error) {
+            return { error: `YAML 解析失败：${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    // 空头/字面 null 按空映射续走（正文仍在——不可因头空丢正文）；数组/标量才拒
+    let frontmatter;
+    if (parsed === null || parsed === undefined) {
+        frontmatter = {};
+    }
+    else if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { error: 'frontmatter 须为映射（键值对）' };
+    }
+    else {
+        frontmatter = parsed;
+    }
+    const bodyStart = lines.slice(0, closeIndex + 1).join('\n').length + 1; // +1 = 跳过闭合行后的换行
+    const body = normalized.slice(bodyStart);
+    return { frontmatter, body, bodyStart };
+}
+/**
+ * 技能名词法校验（agentskills.io 标准 + 06 §11.2：小写字母/数字/连字符）。
+ * 返回违例清单（空 = 合法）——装载面与 skill_manage create 同一真源。
+ */
+export function validateSkillName(name) {
+    const errors = [];
+    if (name.length > SKILL_NAME_MAX) {
+        errors.push(`name 超 ${SKILL_NAME_MAX} 字符（现 ${name.length}）`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        errors.push('name 含非法字符（只许小写字母/数字/连字符）');
+    }
+    if (name.startsWith('-') || name.endsWith('-')) {
+        errors.push('name 首尾不得为连字符');
+    }
+    if (name.includes('--')) {
+        errors.push('name 不得含连续连字符');
+    }
+    return errors;
+}
+/**
+ * 技能引用清单校验（06 §11.6 skills 键形状护栏——帽 8 / 词法 / 重复三验单源）。
+ *
+ * 消费面两腿同一真源：agents frontmatter 解析层 + 子代理工厂 spawn 前复验
+ * （解析层管形状、工厂复验兜底——程序化注册与直呼 SubagentRequest 绕过解析层，
+ * 工厂侧是唯一全覆盖执法点）。存在性不在本函数查（装载序晚于装配期物化，
+ * 存在性归工厂 resolve 时点）。返回违例清单（空 = 合法）。
+ */
+export function validateSkillRefList(names) {
+    const errors = [];
+    if (names.length > SKILL_REFS_MAX) {
+        errors.push(`skills 引用超 ${SKILL_REFS_MAX} 项（现 ${names.length}）`);
+    }
+    const seen = new Set();
+    for (const name of names) {
+        for (const error of validateSkillName(name)) {
+            errors.push(`skills 项「${name}」${error}`);
+        }
+        if (seen.has(name)) {
+            errors.push(`skills 项「${name}」重复`);
+        }
+        seen.add(name);
+    }
+    return errors;
+}
+/**
+ * 从 SKILL.md 全文装载技能（校验 + 剥离 + 节骨架）。
+ *
+ * 处置逐条（06 §11.2/§11.3/§9.1 第 2 项）：
+ *  - description 非字符串或空白 → 拒载（唯一硬条件）；
+ *  - description > 1024 → 截断装载 + invalid-metadata「已截断」；
+ *  - name 缺席 → 回落父目录基名；词法/长度/与父目录同名违例 → 警告（仍装载）；
+ *  - provenance 形状非法（非对象/memories 非字符串数组/超 50）→ 警告 + 字段丢弃
+ *    （宿主只读解析不校验记忆 id 存在性——跨面校验属审批/诊断面）；
+ *  - metadata 非纯对象 → 警告 + 丢弃；
+ *  - license/compatibility/allowed-tools 等未采用字段 → 静默忽略（非警告面）。
+ */
+export function loadSkillFromText(raw, context) {
+    const diagnostics = [];
+    const parsed = parseSkillFrontmatter(raw);
+    if ('error' in parsed) {
+        diagnostics.push({ type: 'invalid-metadata', message: parsed.error, path: context.filePath });
+        return { diagnostics };
+    }
+    // description：必填（清单行 = 模型选择依据）
+    const rawDescription = parsed.frontmatter['description'];
+    if (typeof rawDescription !== 'string' || rawDescription.trim() === '') {
+        diagnostics.push({
+            type: 'invalid-metadata',
+            message: 'description 缺席或为空（必填——渐进披露清单行的唯一依据）',
+            path: context.filePath,
+        });
+        return { diagnostics };
+    }
+    let description = rawDescription;
+    if (description.length > SKILL_DESCRIPTION_MAX) {
+        description = description.slice(0, SKILL_DESCRIPTION_MAX);
+        diagnostics.push({
+            type: 'invalid-metadata',
+            message: `description 超 ${SKILL_DESCRIPTION_MAX} 已截断装载（全文可经 read 读原文件）`,
+            path: context.filePath,
+        });
+    }
+    // name：缺席回落父目录基名；违例仅警告（name 是身份键不截断）
+    const rawName = parsed.frontmatter['name'];
+    const skillDir = dirname(context.filePath);
+    const parentName = basename(skillDir);
+    const name = typeof rawName === 'string' && rawName !== '' ? rawName : parentName;
+    for (const error of validateSkillName(name)) {
+        diagnostics.push({ type: 'invalid-metadata', message: error, path: context.filePath });
+    }
+    if (name !== parentName) {
+        diagnostics.push({
+            type: 'invalid-metadata',
+            message: `name 与父目录不同名（${name} ≠ ${parentName}）——技能目录约定 = 同名目录承载同名技能`,
+            path: context.filePath,
+        });
+    }
+    // provenance：形状校验宽容丢弃（§9.1 第 2 项——不校验记忆存在性）
+    let provenance;
+    const rawProvenance = parsed.frontmatter['provenance'];
+    if (rawProvenance !== undefined) {
+        const valid = typeof rawProvenance === 'object' &&
+            rawProvenance !== null &&
+            !Array.isArray(rawProvenance) &&
+            Array.isArray(rawProvenance.memories) &&
+            rawProvenance.memories.every((m) => typeof m === 'string') &&
+            rawProvenance.memories.length <= SKILL_PROVENANCE_MEMORIES_MAX;
+        if (valid) {
+            provenance = { memories: rawProvenance.memories };
+        }
+        else {
+            diagnostics.push({
+                type: 'invalid-metadata',
+                message: `provenance 形状非法须 { memories: [id, …] } 且 ≤ ${SKILL_PROVENANCE_MEMORIES_MAX}——字段丢弃`,
+                path: context.filePath,
+            });
+        }
+    }
+    // metadata：客户端扩展槽——非纯对象丢弃
+    let metadata;
+    const rawMetadata = parsed.frontmatter['metadata'];
+    if (rawMetadata !== undefined) {
+        if (typeof rawMetadata === 'object' && rawMetadata !== null && !Array.isArray(rawMetadata)) {
+            metadata = rawMetadata;
+        }
+        else {
+            diagnostics.push({ type: 'invalid-metadata', message: 'metadata 须为对象——字段丢弃', path: context.filePath });
+        }
+    }
+    const content = parsed.body.trim();
+    const sections = splitSkillSections(content).map((s) => ({
+        path: s.path,
+        level: s.level,
+        startLine: s.startLine,
+        endLine: s.endLine,
+    }));
+    const skill = {
+        name,
+        description,
+        filePath: context.filePath,
+        baseDir: skillDir,
+        providerId: context.providerId,
+        content,
+        disableModelInvocation: parsed.frontmatter['disable-model-invocation'] === true,
+        ...(provenance !== undefined ? { provenance } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+        sections,
+    };
+    return { skill, diagnostics };
+}

package/dist/skills/index.js

@@ -0,0 +1,28 @@
+/**
+ * skills 件公开面（02 §4.1 席 13：SKILL.md 双层结构 + 发现六位序列 + 注册表 +
+ * 渐进披露三层护栏 + skill_manage——deps {contracts, context}）。
+ *
+ * 装载态集成归批 12 装载面后装配批：标准六位层经 createStandardLayers 构造、
+ * registry.onChange 桥接 skills_change 事件（03 §6.1——载荷 = 现行 provider id
+ * 清单）；清单重物化消费面（系统提示词拼装）归 conversation/host 消费批。
+ * 出厂技能目录内容（三件样例含 plugins-quickstart）挂 07 出厂清单定名批。
+ */
+import './codes.js';
+// 常量与类型
+export { SKILL_DESCRIPTION_MAX, SKILL_MANIFEST_BYTE_CAP, SKILL_NAME_MAX, SKILL_PROVENANCE_MEMORIES_MAX, SKILL_REFS_MAX, SKILL_SNAPSHOT_CAP, } from './types.js';
+// frontmatter 解析与单文件装载
+export { loadSkillFromText, parseSkillFrontmatter, validateSkillName, validateSkillRefList } from './frontmatter.js';
+// 渐进披露第三层细化（节级寻址/行级过滤/模式词表推导）
+export { deriveModeVocabulary, filterSkillBody, findSkillSection, splitSkillSections } from './sections.js';
+// 发现六位序列（目录扫描 + 标准层构造）
+export { createDirProvider, createStandardLayers, resolveFactorySkillsDir, scanSkillsDir } from './discovery.js';
+// 声明式子代理解析层（06 §11.6——解析层住本件、机器住 core:subagent）
+export { collectAgentDefs, createAgentLayerProvider, createStandardAgentLayers, parseAgentDef } from './agents.js';
+// 注册表
+export { createSkillsRegistry } from './registry.js';
+// 渐进披露渲染层（清单块 + 具名块单源 + 激活包装）
+export { formatSkillBlock, formatSkillInvocation, parseSkillInvocation, renderAvailableSkills } from './render.js';
+// skill_manage 工具（§12.1 管理动词）
+export { createSkillManageTool } from './manage.js';
+// load_skill 工具（§11.5(a) 按需拉取模——具名通道）
+export { createLoadSkillTool } from './load.js';

package/dist/skills/load.js

@@ -0,0 +1,118 @@
+/**
+ * load_skill 工具（06 §11.5(a) 按需拉取模——双模装载第二模）。
+ *
+ * 注册位：core:skills 件注册的全局工具（boot 全局层同 skill_manage 恒挂载）；
+ * 只读无审批对（不写任何根——effect 面空）。与 read 的分工：read 是 FS 通道
+ * （模型自持路径语义）、本工具是具名通道（注册表解析 + 节级寻址/行级过滤
+ * 两细化承载）——两通道等价合法。
+ *
+ * 错误面纪律：name 未命中复用 SKILLS_NOT_FOUND 词面（回执指路清单不内联）；
+ * disable-model-invocation 件拒载并指路用户显式通道（清单滤除律配套执法）；
+ * section/mode 错误 = 无码 guidance 文本（isError true）；一切错误走文本回执
+ * 不 throw（模型可读可自纠——同 skill_manage 错误面形）。
+ */
+import { Type } from 'typebox';
+import { formatSkillBlock } from './render.js';
+import { deriveModeVocabulary, filterSkillBody, findSkillSection } from './sections.js';
+/** 错误结果工厂（数据面——[码] 人读信息；与 skill_manage 同形） */
+function toolError(code, message) {
+    return { content: [{ type: 'text', text: `[${code}] ${message}` }], isError: true };
+}
+/** 无码 guidance 回执（section/mode 错误面——非注册表错，码册外指路文本） */
+function toolGuidance(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** 成功结果工厂 */
+function toolText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * 按层级重建节标题串（06 §11.5 节级寻址——重建层号规则）。
+ *
+ * 祖先标题自 section.level−1 逐级递降、下限 1——重建是节档结构的确定性呈现
+ * 非原文层号保真（SkillSection 只记自身层号，跳级标题下祖先层号以本规则赋值，
+ * 两实现者同读法）。
+ */
+function rebuildSectionHeading(section) {
+    const ancestors = section.path.split(' > ');
+    const own = ancestors[ancestors.length - 1] ?? section.title;
+    const lines = [];
+    const depth = ancestors.length - 1; // 祖先数（不含本节）
+    for (let i = 0; i < depth; i++) {
+        const level = Math.max(1, section.level - (depth - i));
+        lines.push(`${'#'.repeat(level)} ${ancestors[i]}`);
+    }
+    lines.push(`${'#'.repeat(section.level)} ${own}`);
+    return lines.join('\n');
+}
+/** 节回执内容 = 重建标题串 + 空行 + 节正文（正文不含标题行——splitSkillSections 契约） */
+function sectionContent(section) {
+    return `${rebuildSectionHeading(section)}\n\n${section.body}`;
+}
+/** trim + 小写归一（与 filterSkillBody 比对同源） */
+function normalizeModeLabel(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * 创建 load_skill 工具定义（装配注册进工具表——03 §2.3 defineTool 形）。
+ */
+export function createLoadSkillTool(deps) {
+    return {
+        name: 'load_skill',
+        description: '按名装载技能内容（注册表具名通道——与 read 按 location 直读等价，另承节级寻址与' +
+            '行级过滤两细化）：name 必填；section 缺省装载全文、给祖先路径（"A > B" 式）只装' +
+            '命中节；mode 按双形词表行级过滤正文（词表由内容自身的强度表行与带引号示例行' +
+            '交集推导）。回执为具名技能块。',
+        parameters: Type.Object({
+            name: Type.String({ description: '技能名（<available_skills> 清单 name 位）' }),
+            section: Type.Optional(Type.String({ description: '节祖先路径（"Mode 3 > Workflow" 式；缺省 = 全文）' })),
+            mode: Type.Optional(Type.String({ description: '行级过滤模式名（缺省 = 不过滤）' })),
+        }, { additionalProperties: false }),
+        execute: async (args) => {
+            // typebox 已在管道层验形——此处收窄仅满足 TS（非 string 形结构性不达）
+            const name = typeof args.name === 'string' ? args.name : '';
+            const section = typeof args.section === 'string' ? args.section : undefined;
+            const mode = typeof args.mode === 'string' ? args.mode : undefined;
+            const skill = deps.registry.get(name);
+            if (skill === undefined) {
+                return toolError('SKILLS_NOT_FOUND', `技能「${name}」不在册——核对 <available_skills> 清单的 name 位（同名以高优先层为准）`);
+            }
+            // 清单滤除律配套执法：隐藏件不在模型装载面，指路用户显式通道
+            if (skill.disableModelInvocation) {
+                return toolGuidance(`技能「${skill.name}」不对模型自动装载（disable-model-invocation）——` +
+                    `可请用户显式激活（/skill:${skill.name}）`);
+            }
+            // 节级寻址：报错不猜（歧义带行号、未命中列全部可寻址 path——指路而非裸拒）
+            let content = skill.content;
+            if (section !== undefined) {
+                const found = findSkillSection(skill.content, section);
+                if (!found.ok) {
+                    if (found.reason === 'ambiguous') {
+                        return toolGuidance(`节「${section}」歧义（${found.candidates.length} 处同名）——候选：\n` +
+                            found.candidates.map((c) => `- ${c}`).join('\n'));
+                    }
+                    return toolGuidance(`节「${section}」未命中——可寻址节：\n` +
+                        (found.candidates.length > 0
+                            ? found.candidates.map((c) => `- ${c}`).join('\n')
+                            : '（正文无可寻址节——不含任何标题）'));
+                }
+                content = sectionContent(found.section);
+            }
+            // 行级过滤：词表推导域 = 待回执内容自身（节形即节内容——mode+section 组合时词表随节重推导）
+            if (mode !== undefined && mode.trim() !== '') {
+                const vocabulary = deriveModeVocabulary(content);
+                if (vocabulary.length === 0) {
+                    // 词表空 = mode 无可作用行——原样回执 + 就地注明（诚实无操作，非静默忽略）
+                    return toolText(`注：该内容未推导出模式词表（无强度表行 ∩ 带引号示例行的双形标签），` +
+                        `mode「${mode}」未生效，按原样装载。\n\n${formatSkillBlock(skill, content)}`);
+                }
+                const active = normalizeModeLabel(mode);
+                if (!vocabulary.includes(active)) {
+                    return toolGuidance(`mode「${mode}」不在词表——可用模式：${vocabulary.join(' / ')}`);
+                }
+                content = filterSkillBody(content, { modes: vocabulary, active: mode });
+            }
+            return toolText(formatSkillBlock(skill, content));
+        },
+    };
+}

package/dist/skills/manage.js

@@ -0,0 +1,201 @@
+/**
+ * skill_manage 工具（06 §12.1——技能的面内管理动词：list / create / patch）。
+ *
+ * - 恒 effect:'write'（list 也不例外——同工具三动词统一审批面，守门段管道执法）；
+ * - create 恒 project 层 `<workspace>/.agents/skills/<名>/SKILL.md`；同名亮拒不
+ *   覆写——判据 = 注册表在册名 ∪ 盘上文件在场（坏 frontmatter 文件对 get()
+ *   隐身，只查在册名会静默毁文件）；
+ * - patch 仅 project 层可改（user/package 层拒并指路人面）；find 串零/多匹配
+ *   均拒（不猜改点）；替换区间限 frontmatter 闭合 --- 之后（正文域）；replace
+ *   字面写出（split/join——防 $&/$` 展开家族）；校验域与替换域统一在 CRLF→LF
+ *   归一化整文件；
+ * - 写点前置可写根断言：物理写（含 mkdir）前走装配注入的 writableRoots 推导，
+ *   read-only 档空根即拒（绕过 fence 的直写即缺陷）；
+ * - 写后自动 registry.refresh()（技能面刷新 + 渐进披露清单重物化同径）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { Type } from 'typebox';
+import { parseSkillFrontmatter, validateSkillName } from './frontmatter.js';
+import { SKILL_DESCRIPTION_MAX, SKILL_PROVENANCE_MEMORIES_MAX } from './types.js';
+/** 错误结果工厂（数据面——[码] 人读信息；与 exec 族同形） */
+function toolError(code, message) {
+    return { content: [{ type: 'text', text: `[${code}] ${message}` }], isError: true };
+}
+/** 成功结果工厂 */
+function toolText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/** 路径落在可写根集合内（resolve 归一 + 边界分隔符守卫——`/a` 不匹配 `/ab`） */
+function isWithinRoots(path, roots) {
+    const abs = resolve(path);
+    return roots.some((root) => {
+        const base = resolve(root);
+        return abs === base || abs.startsWith(base + sep);
+    });
+}
+/** 校验非空字符串参数（schema 之外的语义校验面——空串 trim 后拒） */
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 创建 skill_manage 工具定义（装配注册进工具表——03 §2.3 defineTool 形）。
+ */
+export function createSkillManageTool(deps) {
+    return {
+        name: 'skill_manage',
+        description: '管理技能（渐进披露清单的来源文件）：list 列出在册技能（含来源层与溯源）；' +
+            'create 在 project 层 .agents/skills/<名>/ 下新建 SKILL.md（同名亮拒不覆写）；' +
+            'patch 对 project 层技能正文做单点 find-replace（零/多匹配均拒；user/出厂层' +
+            '只读）。写后自动刷新技能面。',
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal('list'), Type.Literal('create'), Type.Literal('patch')], {
+                description: '管理动词',
+            }),
+            name: Type.Optional(Type.String({ description: '技能名（create/patch 必填）' })),
+            description: Type.Optional(Type.String({ description: `技能描述（create 必填，≤ ${SKILL_DESCRIPTION_MAX} 字符）` })),
+            body: Type.Optional(Type.String({ description: '技能正文 Markdown（create 必填）' })),
+            provenance_memories: Type.Optional(Type.Array(Type.String(), {
+                description: `溯源记忆 id 清单（可选，≤ ${SKILL_PROVENANCE_MEMORIES_MAX} 条）`,
+            })),
+            find: Type.Optional(Type.String({ description: 'patch 查找串（正文域单点匹配）' })),
+            replace: Type.Optional(Type.String({ description: 'patch 替换串（字面写出——$& 等不展开）' })),
+        }, { additionalProperties: false }),
+        // 三动词统一走写面审批（06 §12.1 恒 effect:'write'——守门段管道执法）
+        effect: 'write',
+        execute: async (args) => {
+            const action = args.action;
+            if (action === 'list')
+                return executeList(deps);
+            if (action === 'create')
+                return executeCreate(deps, args);
+            return executePatch(deps, args);
+        },
+    };
+}
+/** list：清单 + 来源层 + 溯源（含隐藏件——管理面见全量） */
+function executeList(deps) {
+    const skills = deps.registry.list();
+    const diagnostics = deps.registry.diagnostics();
+    if (skills.length === 0) {
+        const diagNote = diagnostics.length > 0
+            ? `\n诊断 ${diagnostics.length} 条：\n${diagnostics.map((d) => `- [${d.type}] ${d.message}`).join('\n')}`
+            : '';
+        return toolText(`在册技能 0 件。${diagNote}`);
+    }
+    const rows = skills.map((skill) => {
+        const flags = [
+            skill.disableModelInvocation ? '隐藏' : '',
+            skill.provenance ? `溯源 ${skill.provenance.memories.length}` : '',
+        ]
+            .filter((f) => f !== '')
+            .map((f) => `[${f}]`)
+            .join(' ');
+        return `- ${skill.name}（${skill.providerId} 层）${flags ? `${flags} ` : ''}${skill.filePath}`;
+    });
+    const diagNote = diagnostics.length > 0
+        ? `\n诊断 ${diagnostics.length} 条：\n${diagnostics.map((d) => `- [${d.type}] ${d.message}`).join('\n')}`
+        : '';
+    return toolText(`在册技能 ${skills.length} 件：\n${rows.join('\n')}${diagNote}`);
+}
+/** create：project 层新建（校验链 → 同名亮拒 → 可写根断言 → 写盘 → 刷新） */
+async function executeCreate(deps, args) {
+    const name = nonEmptyString(args.name);
+    if (name === undefined) {
+        return toolError('SKILLS_NAME_INVALID', 'create 须携带技能名（name）');
+    }
+    const nameErrors = validateSkillName(name);
+    if (nameErrors.length > 0) {
+        return toolError('SKILLS_NAME_INVALID', `技能名违例：${nameErrors.join('；')}`);
+    }
+    const description = nonEmptyString(args.description);
+    if (description === undefined || description.length > SKILL_DESCRIPTION_MAX) {
+        return toolError('SKILLS_CONTENT_INVALID', `description 须非空且 ≤ ${SKILL_DESCRIPTION_MAX} 字符（现 ${typeof args.description === 'string' ? args.description.length : '缺席'}）`);
+    }
+    const body = nonEmptyString(args.body);
+    if (body === undefined) {
+        return toolError('SKILLS_CONTENT_INVALID', '正文（body）须非空');
+    }
+    const rawMemories = args.provenance_memories;
+    if (rawMemories !== undefined &&
+        (!Array.isArray(rawMemories) ||
+            !rawMemories.every((m) => typeof m === 'string') ||
+            rawMemories.length > SKILL_PROVENANCE_MEMORIES_MAX)) {
+        return toolError('SKILLS_CONTENT_INVALID', `provenance_memories 须字符串数组且 ≤ ${SKILL_PROVENANCE_MEMORIES_MAX} 条`);
+    }
+    const memories = rawMemories;
+    // 同名亮拒不覆写：在册名 ∪ 盘上文件在场（坏文件对 get() 隐身——只查在册名会静默毁文件）
+    if (deps.registry.get(name) !== undefined) {
+        return toolError('SKILLS_NAME_EXISTS', `技能 ${name} 已在册（${deps.registry.get(name)?.providerId} 层）——create 不覆写，改内容走 patch 或先人面清理`);
+    }
+    for (const root of deps.registry.scanRoots()) {
+        if (existsSync(join(root, name, 'SKILL.md'))) {
+            return toolError('SKILLS_NAME_EXISTS', `盘上已有 ${join(root, name, 'SKILL.md')}（可能未入册——坏 frontmatter 文件同算占用）——create 不覆写`);
+        }
+    }
+    const target = join(deps.workspaceRoot(), '.agents', 'skills', name, 'SKILL.md');
+    if (!isWithinRoots(target, deps.writableRoots())) {
+        return toolError('SKILLS_WRITE_ROOT_DENIED', `写点 ${target} 不在可写根内（read-only 档或根未授权）——技能创建需可写的工作区`);
+    }
+    // frontmatter 物化（yaml stringify——描述含冒号/引号/换行均安全）
+    const fm = { name, description };
+    if (memories !== undefined && memories.length > 0) {
+        fm['provenance'] = { memories };
+    }
+    const fileContent = `---\n${stringifyYaml(fm)}---\n\n${body}\n`;
+    mkdirSync(join(deps.workspaceRoot(), '.agents', 'skills', name), { recursive: true });
+    writeFileSync(target, fileContent, 'utf8');
+    await deps.registry.refresh(); // 写后自动技能面刷新 + 清单重物化（同径）
+    return toolText(`已创建技能 ${name}：${target}\n（project 层；技能面已刷新，在册 ${deps.registry.list().length} 件）`);
+}
+/** patch：project 层正文单点 find-replace（域限定 + 单点匹配 + 字面替换 + 归一化） */
+async function executePatch(deps, args) {
+    const name = nonEmptyString(args.name);
+    const find = nonEmptyString(args.find);
+    const replace = typeof args.replace === 'string' ? args.replace : undefined;
+    if (name === undefined)
+        return toolError('SKILLS_NOT_FOUND', 'patch 须携带技能名（name）');
+    if (find === undefined || replace === undefined) {
+        return toolError('SKILLS_PATCH_MATCH_INVALID', 'patch 须携带 find（非空）与 replace（可为空串=删除）');
+    }
+    const skill = deps.registry.get(name);
+    if (skill === undefined) {
+        return toolError('SKILLS_NOT_FOUND', `技能 ${name} 不在册（先刷新；盘上坏 frontmatter 文件不入册者同报——修坏文件走人面）`);
+    }
+    const provider = deps.registry.getProvider(skill.providerId);
+    if (provider === undefined || provider.writable !== true) {
+        return toolError('SKILLS_LAYER_READONLY', `技能 ${name} 属 ${skill.providerId} 层——patch 仅 project 层可改（user/跨库/出厂层是用户自持面，走文件编辑器人面改）`);
+    }
+    // 校验域与替换域统一：BOM 剥离 + CRLF/CR→LF 归一化整文件（写回归一化全文）
+    let raw;
+    try {
+        raw = readFileSync(skill.filePath, 'utf8');
+    }
+    catch (error) {
+        return toolError('SKILLS_NOT_FOUND', `技能文件读取失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const unbommed = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const normalized = unbommed.replace(/\r\n?/g, '\n');
+    const parsed = parseSkillFrontmatter(normalized);
+    if ('error' in parsed) {
+        return toolError('SKILLS_CONTENT_INVALID', `技能文件不可解析：${parsed.error}`);
+    }
+    // 替换区间限 frontmatter 闭合 --- 之后（正文域——frontmatter 是结构面不走自由文本改）
+    const domain = normalized.slice(parsed.bodyStart);
+    const occurrences = domain.split(find).length - 1;
+    if (occurrences === 0) {
+        return toolError('SKILLS_PATCH_MATCH_INVALID', `find 串在正文域零匹配（frontmatter 域不计入）——检查拼写或换 find 串`);
+    }
+    if (occurrences > 1) {
+        return toolError('SKILLS_PATCH_MATCH_INVALID', `find 串在正文域 ${occurrences} 处匹配——patch 只做单点替换（不猜改点），加长 find 串到唯一`);
+    }
+    if (!isWithinRoots(skill.filePath, deps.writableRoots())) {
+        return toolError('SKILLS_WRITE_ROOT_DENIED', `写点 ${skill.filePath} 不在可写根内（read-only 档或根未授权）——拒绝直写`);
+    }
+    // 字面替换（split/join——String.replace 的 $&/$`/$' 展开家族不入场）
+    const patched = normalized.slice(0, parsed.bodyStart) + domain.split(find).join(replace);
+    writeFileSync(skill.filePath, patched, 'utf8');
+    await deps.registry.refresh();
+    return toolText(`已修改技能 ${name} 正文 1 处（${skill.filePath}；技能面已刷新）`);
+}