@restregular/dsh-skill-center 0.2.2 → 0.3.1

package/lib/index.js

@@ -22,12 +22,18 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** Loader identity of the Host half. */
 export const name = 'skill-center';
 
-/** Services this plugin needs; absent `webServer` keeps it inert instead of throwing. */
-export const inject = ['skills', 'webServer'];
+/**
+ * Services this plugin needs. `webServer` is *not* listed here: the loopback
+ * route is mounted through `ctx.inject(['webServer'], …)` so a deployment
+ * without a web server still gets the bundled skill and the `skill_create`
+ * tool instead of an inert plugin.
+ */
+export const inject = ['skills'];
 
 /** Loopback route prefix owned by this plugin. */
 const ROUTE = '/dsh-skill-center';
@@ -52,6 +58,35 @@ const ROOT_LABELS = {
   'user-agents': { label: '用户 Agents 技能', rank: 500 },
 };
 
+/**
+ * 随包(内嵌)技能:目录名 == frontmatter name,正文与资源都在本包 `skills/` 下。
+ * 这些技能以 provider 形式注册,资源通过 `resourceBase` 目录暴露给模型 ——
+ * 与第一方的 `@deepseek-ai/dsh-skill-office` 同一形态。
+ */
+const BUNDLED_SKILL_ROOT = fileURLToPath(new URL('../skills/', import.meta.url));
+
+/** 随包技能的名字列表。 */
+const BUNDLED_SKILL_NAMES = ['skill-authoring'];
+
+/** provider 名:面板的 provider 列显示这个名字。 */
+const BUNDLED_SKILL_PROVIDER = 'dsh-skill-center';
+
+/**
+ * 浏览器模块图里本插件那一行的 id 候选:图按**包名**编号,插件 id 只是宿主侧名字。
+ * 两个都收,免得 loader 行名或注册 id 变一处就误报。
+ */
+const BROWSER_ENTRY_IDS = new Set([
+  '@restregular/dsh-skill-center',
+  'dsh-skill-center',
+]);
+
+/**
+ * 随包技能的 rank,与 `@deepseek-ai/dsh-skill` 的 `BUNDLED_SKILL_RANK` 一致:
+ * 项目根(100/200)与用户根(400/500)的同名技能都能盖过它。
+ * 这里写字面量而不是 import,是为了让本插件保持零运行时依赖。
+ */
+const BUNDLED_SKILL_RANK = 600;
+
 // ---------------------------------------------------------------------------
 // HTTP 小工具
 // ---------------------------------------------------------------------------
@@ -174,6 +209,109 @@ function frontmatterField(text, key) {
   return raw.replace(/^["']/u, '').replace(/["']$/u, '');
 }
 
+/**
+ * 读 frontmatter 里的布尔字段,取值规则与 dsh-skill-filesystem 的
+ * `frontmatterBoolean` 一致(true/false/1/0/yes/no/on/off,大小写不敏感)。
+ * @param text - 文件全文。
+ * @param key - 字段名。
+ * @returns 布尔值,或 undefined(缺字段或值非法)。
+ */
+function frontmatterBoolean(text, key) {
+  const raw = frontmatterField(text, key);
+  if (raw === undefined) return undefined;
+  const value = raw.toLowerCase();
+  if (value === 'true' || value === '1' || value === 'yes' || value === 'on') return true;
+  if (value === 'false' || value === '0' || value === 'no' || value === 'off') return false;
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 随包技能:注册成 provider,资源用 resourceBase 目录暴露
+// ---------------------------------------------------------------------------
+
+/**
+ * 把本包 `skills/<name>/` 读成注册表候选。
+ *
+ * `resourceBase` 是模型能不能用上这个技能资源的关键:注册表会把
+ * "Base directory for this skill: <绝对路径>" 渲染进 `<skill_resources>`,
+ * 并告诉模型把正文里的相对路径解析到这个目录。缺了它,资源引用就只是空话。
+ *
+ * @param name - 技能名(等于目录名)。
+ * @returns 注册表候选。
+ * @throws 当 SKILL.md 缺失或没有 description 时(属于打包错误,要立刻看见)。
+ */
+function bundledSkillCandidate(name) {
+  const directory = join(BUNDLED_SKILL_ROOT, name);
+  const path = join(directory, 'SKILL.md');
+  const text = readFileSync(path, 'utf8');
+  const description = frontmatterField(text, 'description');
+  if (description === undefined) {
+    throw new Error(`随包技能 "${name}" 的 SKILL.md 缺少 description:${path}`);
+  }
+  return {
+    name,
+    description,
+    invocation: { modelInvocable: true, userInvocable: true },
+    provider: BUNDLED_SKILL_PROVIDER,
+    source: 'bundled',
+    rank: BUNDLED_SKILL_RANK,
+    resourceBase: { kind: 'directory', path: directory },
+    locator: path,
+    path,
+  };
+}
+
+/**
+ * 读随包技能的正文(frontmatter 之后的部分)。
+ * @param name - 技能名。
+ * @returns 已 trim 的 Markdown 正文。
+ */
+function bundledSkillBody(name) {
+  const text = readFileSync(join(BUNDLED_SKILL_ROOT, name, 'SKILL.md'), 'utf8');
+  const match = matchFrontmatter(text);
+  return (match === undefined ? text : text.slice(match[0].length)).trim();
+}
+
+/**
+ * 构造随包技能的 provider。
+ *
+ * `list()` 只回目录摘要;正文每次 `get()` 现读,所以仓库里的 SKILL.md 改完
+ * 下一次加载就生效(注册表只缓存目录,不缓存正文)。
+ *
+ * @returns skill provider 对象。
+ */
+function createBundledSkillProvider() {
+  const candidates = BUNDLED_SKILL_NAMES.map((name) => bundledSkillCandidate(name));
+  const byName = new Map(candidates.map((candidate) => [candidate.name, candidate]));
+  return {
+    name: BUNDLED_SKILL_PROVIDER,
+    list: () => Promise.resolve(candidates),
+    get(winner) {
+      const known = byName.get(winner?.name);
+      if (known === undefined) throw new Error(`随包技能 "${String(winner?.name)}" 不存在`);
+      const { rank: _rank, locator: _locator, ...summary } = known;
+      return Promise.resolve({ ...summary, content: bundledSkillBody(known.name) });
+    },
+  };
+}
+
+/**
+ * 注册随包技能。失败只记一行日志:技能资产出问题不该把整个插件(含面板)带下水。
+ * @param ctx - 宿主上下文。
+ */
+function mountBundledSkills(ctx) {
+  const skills = ctx.skills ?? ctx.get('skills');
+  if (skills === undefined) return;
+  try {
+    ctx.effect(
+      () => skills.registerProvider(createBundledSkillProvider),
+      'skill-center: bundled skills',
+    );
+  } catch (error) {
+    ctx.logger?.warn?.(`skill-center: 随包技能未能注册:${error?.message ?? error}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // 技能根目录
 // ---------------------------------------------------------------------------
@@ -374,13 +512,29 @@ function describeSkill(skill, roots) {
   const root = rootOfPath(path, roots);
   const onDisk = path !== undefined && existsSync(path) && statSync(path).isFile();
   let bytes;
+  let invocation;
   if (onDisk) {
     try {
       bytes = statSync(path).size;
     } catch {
       bytes = undefined;
     }
+    // 受管根里的技能以**磁盘为准**:技能目录是缓存的,写完盘之后 watcher 的失效
+    // 事件到达之前,快照里的调用策略还是旧值 —— 面板若照抄快照,刚拨完开关的界面
+    // 会被自己重读回来的旧值弹回去(手动刷新才会变)。这里现读一次 frontmatter 求解。
+    if (root !== undefined) {
+      try {
+        const text = readFileSync(path, 'utf8');
+        invocation = {
+          modelInvocable: frontmatterBoolean(text, 'disable-model-invocation') !== true,
+          userInvocable: frontmatterBoolean(text, 'user-invocable') !== false,
+        };
+      } catch {
+        invocation = undefined;
+      }
+    }
   }
+  const effective = invocation ?? skill.invocation;
   return {
     name: skill.name,
     description: skill.description,
@@ -389,8 +543,8 @@ function describeSkill(skill, roots) {
     source: skill.source,
     path,
     directory: path === undefined ? undefined : dirname(path),
-    modelInvocable: skill.invocation?.modelInvocable !== false,
-    userInvocable: skill.invocation?.userInvocable !== false,
+    modelInvocable: effective?.modelInvocable !== false,
+    userInvocable: effective?.userInvocable !== false,
     rootId: root?.id,
     rootLabel: root?.label,
     writable: root !== undefined && onDisk,
@@ -438,7 +592,10 @@ async function opDiagnose(ctx, request) {
   const clientModules = ctx.get('clientModules');
   const graph = clientModules?.graph?.();
   const entries = Array.isArray(graph?.entries) ? graph.entries : [];
-  const mine = entries.find((entry) => entry.id === 'dsh-skill-center');
+  // 浏览器模块图按**包名**给行编号(客户端 bundle 的注册 id 也是包名),
+  // 插件 id 只是宿主侧的 loader 名字:只按 'dsh-skill-center' 找会永远找不到,
+  // diagnose 就会把"客户端半边好好地挂在图里"误报成 inGraph: false。
+  const mine = entries.find((entry) => BROWSER_ENTRY_IDS.has(entry.id));
   let catalog;
   try {
     const catalogRead = await readCatalog(ctx, request);
@@ -451,6 +608,7 @@ async function opDiagnose(ctx, request) {
     host: { mounted: true, route: ROUTE },
     client: {
       inGraph: mine !== undefined,
+      entryId: mine?.id,
       graphRevision: graph?.rev,
       graphEntryCount: entries.length,
       url: mine?.url,
@@ -548,45 +706,163 @@ async function opSetInvocation(ctx, request) {
 }
 
 /**
- * 新建一个技能目录包。
+ * 归一化资源相对路径:必须是技能包目录内的相对路径,拒绝绝对路径、`.`/`..` 段与
+ * 二次写入 SKILL.md。面板与模型工具都走这道闸。
+ *
+ * @param raw - 原始路径(允许 `\` 分隔)。
+ * @param directory - 技能包目录。
+ * @returns 归一化后的 posix 相对路径,或 undefined(非法)。
+ */
+function normalizeResourcePath(raw, directory) {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.replace(/\\/gu, '/').trim();
+  if (value === '' || value.startsWith('/') || /^[A-Za-z]:/u.test(value)) return undefined;
+  const segments = value.split('/').filter((segment) => segment !== '');
+  if (segments.length === 0) return undefined;
+  if (segments.some((segment) => segment === '.' || segment === '..')) return undefined;
+  const relative = segments.join('/');
+  if (relative.toLowerCase() === 'skill.md') return undefined;
+  const base = resolve(directory);
+  const target = resolve(base, ...segments);
+  if (target !== base && !target.startsWith(base.endsWith(sep) ? base : base + sep)) return undefined;
+  return relative;
+}
+
+/**
+ * 新建(或按 `overwrite` 覆盖)一个技能包:写 frontmatter + 正文,再把资源文件落到
+ * 同一个技能目录里。面板的 `create` 与模型工具 `skill_create` 共用这一份实现。
+ *
  * @param ctx - 宿主上下文。
- * @param request - `{ sessionId, cwd, name, description, body, rootId, modelInvocable, userInvocable }`。
- * @returns 响应体。
+ * @param request - `{ sessionId, cwd, name, description, whenToUse, body, rootId, resources, overwrite, modelInvocable, userInvocable }`。
+ * @returns 响应体;`ok` 为 false 时带 `error`。
  */
-async function opCreate(ctx, request) {
+async function createSkillBundle(ctx, request) {
   const skillName = String(request.name ?? '').trim();
   if (!SKILL_NAME.test(skillName)) {
     return { ok: false, error: `技能名 "${skillName}" 不合法:只允许小写字母、数字与单个连字符(kebab-case)` };
   }
-  const description = String(request.description ?? '').trim();
+  const description = String(request.description ?? '').replace(/\s+/gu, ' ').trim();
   if (description === '') return { ok: false, error: 'description 必填' };
+  const whenToUse = String(request.whenToUse ?? '').replace(/\s+/gu, ' ').trim();
+  const overwrite = request.overwrite === true;
+  const rawResources = Array.isArray(request.resources) ? request.resources : [];
 
   const catalog = await readCatalog(ctx, request);
-  if (catalog.skills.some((skill) => skill.name === skillName)) {
-    return { ok: false, error: `技能 "${skillName}" 已存在` };
+  const existing = locateOnDisk(skillName, catalog.roots);
+  if (existing === undefined && catalog.skills.some((skill) => skill.name === skillName)) {
+    return {
+      ok: false,
+      error: `技能 "${skillName}" 已存在,但由插件内嵌或其它来源提供,不在可管理的技能根目录里`,
+    };
+  }
+  if (existing !== undefined && !overwrite) {
+    return { ok: false, error: `技能 "${skillName}" 已存在:${existing.path}(需要覆盖请传 overwrite)` };
   }
-  const roots = catalog.roots.filter((root) => root.exists || root.id.startsWith('user-'));
-  const root = roots.find((candidate) => candidate.id === request.rootId)
-    ?? roots.find((candidate) => candidate.id === 'user-agents')
-    ?? roots[0];
-  if (root === undefined) return { ok: false, error: '没有可用的技能根目录' };
-
-  const dir = join(root.path, skillName);
-  if (existsSync(dir)) return { ok: false, error: `目录已存在:${dir}` };
+
+  let root = existing?.root;
+  let directory = existing?.dir;
+  if (existing === undefined) {
+    if (request.rootId !== undefined && request.rootId !== '') {
+      // 显式指定的根允许尚不存在(mkdir 会补上):项目根就在工作区里,
+      // 由调用方明确点名比"静默换到用户根"更可预期。
+      root = catalog.roots.find((candidate) => candidate.id === request.rootId);
+      if (root === undefined) {
+        return {
+          ok: false,
+          error: `未知的技能根 "${request.rootId}";可选:${catalog.roots.map((candidate) => candidate.id).join('、')}`,
+        };
+      }
+    } else {
+      const usable = catalog.roots.filter((candidate) => candidate.exists || candidate.id.startsWith('user-'));
+      root = usable.find((candidate) => candidate.id === 'user-agents') ?? usable[0];
+    }
+    if (root === undefined) return { ok: false, error: '没有可用的技能根目录' };
+    directory = join(root.path, skillName);
+    if (existsSync(directory) && !overwrite) {
+      return { ok: false, error: `目录已存在:${directory}(需要覆盖请传 overwrite)` };
+    }
+  }
+
+  const resources = [];
+  if (existing?.flat === true) {
+    if (rawResources.length > 0) {
+      return {
+        ok: false,
+        error: `技能 "${skillName}" 是平坦文件 ${existing.path},无法承载资源文件;请改用目录包`,
+      };
+    }
+  } else {
+    for (const entry of rawResources) {
+      const relative = normalizeResourcePath(entry?.path, directory);
+      if (relative === undefined) {
+        return {
+          ok: false,
+          error: `资源路径 "${String(entry?.path ?? '')}" 不合法:必须是技能目录内的相对路径,不能是 SKILL.md,也不能含 . 或 .. 段`,
+        };
+      }
+      if (typeof entry?.content !== 'string') {
+        return { ok: false, error: `资源 "${relative}" 缺少 content` };
+      }
+      resources.push({
+        relative,
+        content: entry.content,
+        target: join(directory, ...relative.split('/')),
+      });
+    }
+  }
+
   const invocation = {
     modelInvocable: request.modelInvocable !== false,
     userInvocable: request.userInvocable !== false,
   };
   const lines = ['---', `name: ${skillName}`, `description: ${JSON.stringify(description)}`];
+  if (whenToUse !== '') lines.push(`whenToUse: ${JSON.stringify(whenToUse)}`);
   if (invocation.modelInvocable === false) lines.push('disable-model-invocation: true');
   if (invocation.userInvocable === false) lines.push('user-invocable: false');
   lines.push('---', '');
   const body = String(request.body ?? '').trim();
   lines.push(body === '' ? `# ${skillName}` : body, '');
-  mkdirSync(dir, { recursive: true });
-  const path = join(dir, 'SKILL.md');
+
+  const flat = existing?.flat === true;
+  const path = flat ? existing.path : join(directory, 'SKILL.md');
+  mkdirSync(flat ? dirname(path) : directory, { recursive: true });
   writeFileSync(path, lines.join('\n'), 'utf8');
-  return { ok: true, name: skillName, path, rootId: root.id };
+  for (const resource of resources) {
+    mkdirSync(dirname(resource.target), { recursive: true });
+    writeFileSync(resource.target, resource.content, 'utf8');
+  }
+
+  return {
+    ok: true,
+    name: skillName,
+    path,
+    directory: flat ? dirname(path) : directory,
+    rootId: root?.id,
+    rootLabel: root?.label,
+    replaced: existing !== undefined,
+    resources: resources.map((resource) => resource.relative),
+  };
+}
+
+/**
+ * 新建一个技能目录包(HTTP `op=create`)。
+ * @param ctx - 宿主上下文。
+ * @param request - 见 createSkillBundle。
+ * @returns 响应体。
+ */
+async function opCreate(ctx, request) {
+  const created = await createSkillBundle(ctx, request);
+  if (created.ok !== true) return created;
+  return {
+    ok: true,
+    name: created.name,
+    path: created.path,
+    directory: created.directory,
+    rootId: created.rootId,
+    rootLabel: created.rootLabel,
+    replaced: created.replaced,
+    resources: created.resources,
+  };
 }
 
 /**
@@ -614,6 +890,161 @@ async function opDelete(ctx, request) {
   return { ok: true, name: request.name, movedTo: target, rootId: entry.root.id };
 }
 
+// ---------------------------------------------------------------------------
+// 模型工具:skill_create
+// ---------------------------------------------------------------------------
+
+/**
+ * `skill_create` 的参数 schema。
+ *
+ * 这里手写**原始 JSON Schema**,而不是 import `@deepseek-ai/dsh-tools` 的
+ * `defineTool`:本包因此保持零运行时依赖,也不依赖宿主 node_modules 的解析路径。
+ * 只使用注册表支持的子集:type/oneOf/properties/required/additionalProperties/
+ * items/enum/const 加注解键(description/title…)。
+ */
+const SKILL_CREATE_PARAMETERS = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Kebab-case skill name; it is also the bundle directory name.',
+    },
+    description: {
+      type: 'string',
+      description: 'Frontmatter description — the only routing signal the model catalog shows. Write it as "Use when …".',
+    },
+    whenToUse: {
+      type: 'string',
+      description: 'Optional "whenToUse" frontmatter field (provider metadata; not rendered into the catalog).',
+    },
+    body: {
+      type: 'string',
+      description: 'Full Markdown body that follows the frontmatter. Omit to write a placeholder "# <name>" heading.',
+    },
+    root: {
+      type: 'string',
+      enum: ['project-dsh', 'project-agents', 'user-dsh', 'user-agents'],
+      description: 'Target skill root. Defaults to user-agents (~/.agents/skills); pass a project root for a repository-scoped skill.',
+    },
+    resources: {
+      type: 'array',
+      description: 'Extra files written inside the same bundle directory, e.g. references/roots.md or scripts/check.py.',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Relative path inside the bundle directory.' },
+          content: { type: 'string', description: 'Full UTF-8 file content.' },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+      },
+    },
+    modelInvocable: {
+      type: 'boolean',
+      description: 'Default true; false writes disable-model-invocation: true, keeping the skill out of the model catalog.',
+    },
+    userInvocable: {
+      type: 'boolean',
+      description: 'Default true; false writes user-invocable: false, disabling the user-facing /name entry point.',
+    },
+    overwrite: {
+      type: 'boolean',
+      description: 'Default false: fail when the skill already exists. true rewrites SKILL.md and the listed resources in place.',
+    },
+  },
+  required: ['name', 'description'],
+  additionalProperties: false,
+};
+
+/** `skill_create` 的返回值 schema,与 execute 的返回字段一一对应。 */
+const SKILL_CREATE_OUTPUT = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    directory: { type: 'string' },
+    skillFile: { type: 'string' },
+    rootId: { type: 'string' },
+    rootLabel: { type: 'string' },
+    resources: { type: 'array', items: { type: 'string' } },
+    replaced: { type: 'boolean' },
+  },
+  required: ['name', 'directory', 'skillFile', 'resources', 'replaced'],
+  additionalProperties: false,
+};
+
+/**
+ * 构造 `skill_create` 工具定义:把面板的"新建"能力交给模型,并顺带解决
+ * "技能根目录在工作区之外"这个真实障碍 —— 文件写入工具被沙箱限制在工作区内,
+ * 而受管技能根不在工作区。
+ *
+ * @param ctx - 宿主上下文。
+ * @returns 可交给 `ctx.tools.register()` 的定义。
+ */
+function skillCreateTool(ctx) {
+  return {
+    name: 'skill_create',
+    description: 'Create a Harness skill bundle: writes <root>/<name>/SKILL.md with the given frontmatter and body, plus any extra files listed in resources, inside that same directory. Use it to author or scaffold a skill, especially when the target skill root is outside the session workspace (~/.agents/skills, ~/.dsh/skills), where the file-write tools are sandboxed and cannot write. Put long-form detail in resources (for example references/<topic>.md, scripts/<tool>.py) and refer to those files by relative path from the body. Fails when a skill of that name already exists unless overwrite is true.',
+    parameters: SKILL_CREATE_PARAMETERS,
+    output: {
+      schema: SKILL_CREATE_OUTPUT,
+      render(_args, value) {
+        const lines = [
+          `${value.replaced === true ? 'Replaced' : 'Created'} skill "${value.name}"`,
+          `directory: ${value.directory}`,
+          `SKILL.md: ${value.skillFile}`,
+          `root: ${value.rootLabel} (${value.rootId})`,
+          value.resources.length === 0 ? 'resources: none' : `resources: ${value.resources.join(', ')}`,
+        ];
+        return [{ type: 'text', text: lines.join('\n') }];
+      },
+    },
+    async execute(args, exec) {
+      const session = exec?.agent?.session;
+      const created = await createSkillBundle(ctx, {
+        sessionId: session?.id,
+        cwd: session?.header?.cwd,
+        name: args.name,
+        description: args.description,
+        whenToUse: args.whenToUse,
+        body: args.body,
+        rootId: args.root,
+        resources: args.resources,
+        overwrite: args.overwrite,
+        modelInvocable: args.modelInvocable,
+        userInvocable: args.userInvocable,
+      });
+      if (created.ok !== true) throw new Error(created.error);
+      return {
+        name: created.name,
+        directory: created.directory,
+        skillFile: created.path,
+        rootId: created.rootId,
+        rootLabel: created.rootLabel,
+        resources: created.resources,
+        replaced: created.replaced,
+      };
+    },
+  };
+}
+
+/**
+ * 注册 `skill_create`。没有 tools 服务的组合里只是少一个工具,
+ * 面板与随包技能照常工作。
+ * @param ctx - 宿主上下文。
+ */
+function mountSkillTools(ctx) {
+  ctx.inject(['tools'], (scoped) => {
+    try {
+      scoped.effect(
+        () => scoped.tools.register(skillCreateTool(scoped)),
+        'skill-center: skill_create tool',
+      );
+    } catch (error) {
+      scoped.logger?.warn?.(`skill-center: skill_create 未能注册:${error?.message ?? error}`);
+    }
+  });
+}
+
 /** 路由表:op → 处理器。 */
 const OPERATIONS = {
   ping: async () => ({ ok: true, plugin: 'dsh-skill-center', version: 1 }),
@@ -631,9 +1062,9 @@ const OPERATIONS = {
 
 /**
  * 挂载回环路由,向客户端暴露技能目录与管理操作。
- * @param ctx - 宿主上下文(已保证 skills 与 webServer 就绪)。
+ * @param ctx - 宿主上下文(已保证 webServer 就绪)。
  */
-export function apply(ctx) {
+function mountRoutes(ctx) {
   const webServer = ctx.webServer ?? ctx.get('webServer');
   if (webServer === undefined) return;
 
@@ -689,3 +1120,14 @@ export function apply(ctx) {
     },
   }), 'skill-center: loopback routes');
 }
+
+/**
+ * 插件体:随包技能、模型工具、回环路由三块互相独立降级 ——
+ * 任何一块失败都只记日志,不会让宿主启动失败,也不会拖垮另外两块。
+ * @param ctx - 宿主上下文(已保证 skills 就绪)。
+ */
+export function apply(ctx) {
+  mountBundledSkills(ctx);
+  mountSkillTools(ctx);
+  ctx.inject(['webServer'], (scoped) => mountRoutes(scoped));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@restregular/dsh-skill-center",
-  "version": "0.2.2",
-  "description": "技能中心 — DeepSeek Harness 技能管理面板：浏览当前会话可见的所有技能、查看正文、开关模型/用户调用、新建与删除。 · Skill Center for DeepSeek Harness: browse and manage the skills visible to the current session.",
+  "version": "0.3.1",
+  "description": "技能中心 — DeepSeek Harness 技能管理面板：浏览当前会话可见的所有技能、查看正文、开关模型/用户调用、新建与删除；随包附带 skill-authoring 指导技能与 skill_create 模型工具。 · Skill Center for DeepSeek Harness: browse and manage the skills visible to the current session, with a bundled skill-authoring skill and a skill_create model tool.",
   "type": "module",
   "main": "lib/index.js",
   "license": "MIT",
@@ -17,6 +17,7 @@
   "files": [
     "lib",
     "client",
+    "skills",
     "cordis.patch.yml"
   ],
   "exports": {
@@ -45,7 +46,9 @@
     "deepseek",
     "skills",
     "skill-center",
-    "agent-skills"
+    "agent-skills",
+    "skill-authoring",
+    "skill-create"
   ],
   "publishConfig": {
     "access": "public",

package/skills/skill-authoring/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-authoring
+description: "Use when creating, editing, moving, or reviewing a Harness skill: choosing the skill root for project or user scope, writing SKILL.md frontmatter and body, placing the skill's resource files next to it, or shipping a skill inside a plugin."
+---
+
+# Authoring Harness skills
+
+A skill is a **directory bundle**: `<root>/<name>/SKILL.md` plus every resource file that `SKILL.md` refers to. The model sees only each skill's `name` and `description` in the session catalog; the body is loaded on demand when the model or the user invokes it, and resource files are never loaded automatically. A skill's body must therefore say which file to read and when.
+
+## Short path
+
+1. Pick the root — see `references/roots.md`. Project-scoped skill: `<projectRoot>/.agents/skills`. Available in every project: `$DSH_AGENTS_HOME/skills` (`~/.agents/skills`).
+2. Create `<root>/<name>/SKILL.md`. `name` is kebab-case and should equal the directory name.
+3. Keep the frontmatter minimal: `name` and `description` are required; the body starts after the closing `---`.
+4. Put resource files in subdirectories of **that same bundle directory** and point at them with relative paths.
+5. Verify: the frontmatter parses, `name` matches the directory, every referenced file exists, and the skill appears in the Skill Center panel (and in the catalog of the next model step).
+
+Use the `skill_create` tool when the target root is outside the current workspace: the file-write tools are sandboxed to the workspace, while the managed skill roots are not, so a direct write to `~/.agents/skills/...` is denied. `skill_create` writes `<root>/<name>/SKILL.md` plus any `resources` you pass, in one call, and returns the absolute bundle directory. Inside the workspace (for example `<projectRoot>/.agents/skills`) ordinary file writes work fine.
+
+## Frontmatter decides who can invoke the skill
+
+| Field | Effect |
+|---|---|
+| `description` | the only routing signal in the catalog — write it as "Use when …" and name the tasks, not the implementation |
+| `disable-model-invocation: true` | the skill leaves the model catalog entirely; only an explicit `/name` from the user loads it |
+| `user-invocable: false` | `/name` stops working for humans; the model can still load the skill |
+
+The camelCase spellings (`disableModelInvocation`, `modelInvocable`, `userInvocable`) are **rejected**: a skill carrying one is skipped with a warning instead of loading. The full contract, the accepted boolean spellings, and the silent failure modes are in `references/frontmatter.md`.
+
+## Resource placement
+
+Everything a skill needs lives under its own bundle directory, because the base directory reported to the model *is* that directory and relative paths resolve against it:
+
+```
+<root>/<name>/
+  SKILL.md
+  references/   long-form detail the body points at by relative path
+  scripts/      commands the body tells the model to run
+  assets/       fixtures, templates, images
+```
+
+The loaded skill arrives wrapped in `<skill_content>` with a `<skill_resources>` block that names the absolute base directory; the model is told to resolve relative paths against it before reading. Files under a bundle's resource subtrees are read directly by the file tools when the body asks for them, so editing a reference file needs no catalog refresh — only the skill *list* (names, descriptions, invocation policy) is cached. Details, path rules and the Desktop `app.asar` caveat: `references/resources.md`.
+
+## Shipping a skill inside a plugin
+
+A plugin publishes its own skills instead of writing into the user's roots: it registers a skill provider (or a runtime skill) and points each candidate at an asset directory inside the package. Use this when the skill's instructions and resources must version together with the code they describe. `references/plugin-bundled.md` has the provider contract, the candidate fields, the rank, and the two registration APIs.
+
+## Read next
+
+Read only the files this task needs; the table is complete.
+
+| Task | File |
+|---|---|
+| Which root a skill belongs in, root precedence, project-root detection | `references/roots.md` |
+| Frontmatter fields, validation, and why a skill silently does not load | `references/frontmatter.md` |
+| Where resource files go, how the model is told to find them, Desktop limits | `references/resources.md` |
+| Shipping skill instructions and resources inside a plugin package | `references/plugin-bundled.md` |
+| Starter bundle for a new skill | `templates/minimal/SKILL.md` |