dsh-agentone 0.5.38 → 0.5.40

package/lib/page.js

@@ -392,6 +392,46 @@ const renderPlan = async () => {
     ).then(() => renderPlan());
   });
 };
+const renderDefaults = (s) => {
+  const body = $('defaults-body');
+  const config = s.defaults;
+  const labels = { current: '已符合', missing: '待安装', pending: '待应用', running: '同步中',
+    failed: '失败', conflict: '本机冲突', report_pending: '已安装，待回报', restart_required: '已安装，重启后生效' };
+  const sources = { platform: '平台清单', compatibility: '旧平台兼容默认', cache: '本机缓存' };
+  if (!config || !s.logged_in) { body.innerHTML = '<div class="muted">登录后检查平台默认能力</div>'; return; }
+  const summary = '<div class="skill-sub">' + esc(sources[config.source] || '尚未检查')
+    + (config.revision !== null ? ' · 版本 ' + esc(config.revision) : '')
+    + (config.checked_at ? ' · ' + esc(new Date(config.checked_at).toLocaleString()) : '')
+    + (config.running ? ' · 正在检查' : '') + '</div>'
+    + (config.error || config.profile_error ? '<div class="skill-sub" style="color:var(--err)">' + esc(config.error || config.profile_error) + '</div>' : '');
+  const entries = [...(config.skills || []), ...(config.plugins || [])];
+  const html = summary + entries.map((item) => {
+    const action = ['failed', 'report_pending', 'missing'].includes(item.state) ? 'retry'
+      : ['conflict', 'pending'].includes(item.state) ? 'apply' : null;
+    const button = action ? '<button class="btn small ghost" data-default-action="' + action
+      + '" data-kind="' + item.kind + '" data-name="' + esc(item.name) + '"'
+      + (config.running ? ' disabled' : '') + '>' + (action === 'retry' ? '重试' : '确认应用') + '</button>' : '';
+    return '<div class="skill-item"><div class="skill-info"><div class="skill-name">'
+      + esc(item.description || item.name) + ' <span class="tag">' + (item.kind === 'skill' ? '技能' : '插件')
+      + '</span></div><div class="skill-sub">' + esc(item.name) + ' · ' + esc(labels[item.state] || item.state)
+      + (item.version ? ' · ' + esc(item.version) : '')
+      + (item.target_version && item.target_version !== item.version ? ' → ' + esc(item.target_version) : '')
+      + (item.error ? '<br><span style="color:var(--err)">' + esc(item.error) + '</span>' : '')
+      + '</div></div>' + button + '</div>';
+  }).join('') + (!entries.length ? '<div class="skill-sub">当前清单为空</div>' : '');
+  if (body.dataset.fingerprint !== html) {
+    body.dataset.fingerprint = html; body.innerHTML = html;
+    body.querySelectorAll('[data-default-action]').forEach((btn) => {
+      const request = () => fetch('api/defaults/' + btn.dataset.defaultAction, { method: 'POST',
+        headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ kind: btn.dataset.kind,
+          name: btn.dataset.name, confirm: btn.dataset.defaultAction === 'apply' }) });
+      btn.onclick = () => btn.dataset.defaultAction === 'apply'
+        ? confirmThen(btn, '替换当前版本？', request, '已开始应用，请查看同步状态')
+        : withLoading(btn, request, '已开始重试，请查看同步状态');
+    });
+  }
+  $('defaults-sync-btn').disabled = config.running;
+};
 const renderSkills = (s) => {
   const skillhubEnabled = s.capabilities?.channels?.skillhub?.enabled !== false;
   // null = 平台拉取失败（区别于 [] 套餐确实没配技能），见 /api/status 组装
@@ -415,7 +455,9 @@ const renderSkills = (s) => {
     return;
   }
   const rows = list.map((skill) => {
-    const tag = skill.source === 'plan' ? '<span class="tag">套餐</span>' : '';
+    const sources = skill.sources || (skill.source === 'plan' ? ['plan'] : []);
+    const tag = (sources.includes('plan') ? '<span class="tag">套餐</span>' : '')
+      + (sources.includes('builtin') ? '<span class="tag">平台默认</span>' : '');
     // 可升级：平台对比 latest 指纹/版本后给的结论，提示「v旧 → v新」；
     // latest 查询失败时平台降级 false，这里不额外猜测
     const upgradable = skill.installed && skill.upgrade_available;
@@ -966,13 +1008,13 @@ const renderPlugins = async () => {
     // 标签——它永远不进 bundle 层，不能显示「未激活/重启生效」误导用户
     const statePill = !plugin.version
       ? '<span class="pill warn" style="font-size:11px">未安装</span>'
-      : plugin.active
-        ? '<span class="pill ok" style="font-size:11px">已激活</span>'
+      : plugin.registered
+        ? '<span class="pill ok" style="font-size:11px">已注册</span>'
         : plugin.bundled
-          ? '<span class="pill warn" style="font-size:11px">未激活</span>'
+          ? '<span class="pill warn" style="font-size:11px">未注册</span>'
           : '<span class="tag">依赖</span>';
     const builtinTag = plugin.builtin
-      ? '<span class="tag">内置</span>'
+      ? '<span class="tag">受管</span>'
       : '';
     const version = plugin.latest
       ? esc(plugin.version) + ' → <b>' + esc(plugin.latest) + '</b>'
@@ -999,7 +1041,7 @@ const renderPlugins = async () => {
     return '<div class="skill-item"><div class="skill-info"><div class="skill-name">'
       + esc(plugin.name) + builtinTag + statePill
       + '</div><div class="skill-sub">' + desc + esc(plugin.source) + ' · ' + version
-      + (plugin.bundled && !plugin.active ? ' · 未在 bundle 层，重启 dsh 后生效' : '')
+      + (plugin.registered ? ' · 已安装并注册，重启后生效' : plugin.bundled ? ' · 未注册到当前 profile' : '')
       + '</div></div>' + actionHtml + '</div>';
   });
   // 指纹保护（与 renderSkills 同思路）：内容没变不碰 innerHTML——升级后
@@ -1008,7 +1050,7 @@ const renderPlugins = async () => {
     plugin.name,
     plugin.version || '',
     plugin.latest || '',
-    plugin.active ? 1 : 0,
+    plugin.registered ? 1 : 0,
     plugin.bundled ? 1 : 0,
     plugin.self_managed ? 1 : 0,
   ].join(':')).join('|');
@@ -1272,6 +1314,7 @@ const refresh = async () => {
     lines.push('<div class="kv"><span class="k">环境变量</span><span class="v muted">已写入 agentone/skillhub.env（0600）</span></div>');
     $('skillhub-body').innerHTML = lines.join('');
   }
+  renderDefaults(s);
   renderSkills(s);
   renderAbout(s);
 };
@@ -1302,6 +1345,9 @@ $('login-btn').onclick = async () => {
   btn.dataset.opened = '1';
   btn.textContent = '已打开授权窗口，完成后自动继续（可重开）';
 };
+$('defaults-sync-btn').onclick = () => withLoading($('defaults-sync-btn'),
+  () => fetch('api/defaults/sync', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }),
+  '已开始检查默认能力，请查看同步状态');
 $('sync-btn').onclick = () => syncModelNow($('sync-btn'));
 $('skillhub-sync-btn').onclick = () => withLoading(
   $('skillhub-sync-btn'),
@@ -1328,6 +1374,14 @@ logoutBtn.onclick = () => withLoading(
   () => fetch('api/logout', { method: 'POST' }),
   '已退出登录',
 );
+$('skill-direct-install').onclick = () => {
+  const slug = $('skill-direct-slug').value.trim();
+  if (!slug) { notify('请填写技能标识，例如 611/c611-ops-workbench', 'err'); return; }
+  return skillAction(slug, 'install', $('skill-direct-install'), '已安装最新版本');
+};
+$('skill-direct-slug').addEventListener('keydown', (event) => {
+  if (event.key === 'Enter') $('skill-direct-install').click();
+});
 $('search-btn').onclick = searchCatalog;
 $('search-input').addEventListener('keydown', (event) => {
   if (event.key === 'Enter') searchCatalog();
@@ -1420,14 +1474,22 @@ export function statusPageHtml() {
           <button id="search-btn" class="btn ghost small">搜索</button>
         </div>
         <div id="search-results"></div>
+        <div class="search" style="margin-top:12px">
+          <input id="skill-direct-slug" aria-label="技能标识" placeholder="命名空间/技能名，如 611/c611-ops-workbench" />
+          <button id="skill-direct-install" class="btn ghost small" data-loading="安装中…">安装最新版本</button>
+        </div>
       </div>
     </div>
 
     <div class="tabpane" id="pane-plugins" hidden>
       <div class="card">
-        <h3>dsh 插件 <span class="muted">镜像内置与自行安装的插件</span></h3>
+        <h3>平台默认能力 <button id="defaults-sync-btn" class="btn ghost small" style="margin-left:auto">检查并更新</button></h3>
+        <div id="defaults-body" aria-live="polite"><div class="skill-sub">检查中…</div></div>
+      </div>
+      <div class="card">
+        <h3>dsh 插件 <span class="muted">当前 profile 已安装的插件</span></h3>
         <div id="plugins-list"></div>
-        <div class="hint" id="plugins-hint">标注「内置」的插件由镜像预装，不可卸载，可升级到最新版。更多插件可在 dsh 设置的插件市场里安装。</div>
+        <div class="hint" id="plugins-hint">受管技能和插件始终更新到最新发布版本；仅管理员停用后可卸载受管插件。</div>
       </div>
     </div>
 

package/lib/platform-config.js

@@ -0,0 +1,56 @@
+// 平台默认清单的公开契约；合法空清单不会退回兼容默认。
+import { platformError, platformFetch } from './http.js';
+import { canonicalSkillSlug } from './skill-state.js';
+import { PROTECTED_PACKAGES, validatePackage } from './profile-plugins.js';
+
+export function compatibilityDefaults(userId) {
+  return { schema_version: 1, revision: 0, user_id: userId, auto_sync: true,
+    skills_enabled: true, skill_registry: '', skills: [], plugins: [
+      { name: 'dsh-better-sidebar', version: 'latest', description: '侧边工作台', enabled: true, allow_build: ['node-pty'] },
+      { name: 'dsh-harness-one', version: 'latest', description: '可视化 AI 工作流', enabled: true, allow_build: ['node-pty'] },
+      { name: 'dshmarket', version: 'latest', description: 'DSH 插件市场', enabled: true, allow_build: ['node-pty'] },
+      { name: 'dsh-im', version: 'latest', description: '即时通讯集成', enabled: true, allow_build: [] },
+    ] };
+}
+function invalid() { throw new Error('平台默认能力配置格式异常，请联系管理员检查配置'); }
+export function validatePlatformConfig(document, userId) {
+  if (!document || document.schema_version !== 1 || !Number.isSafeInteger(document.revision) || document.revision < 0
+    || typeof document.user_id !== 'string' || document.user_id !== userId
+    || typeof document.auto_sync !== 'boolean' || typeof document.skills_enabled !== 'boolean'
+    || typeof document.skill_registry !== 'string' || !Array.isArray(document.skills) || !Array.isArray(document.plugins)
+    || document.skills.length > 100 || document.plugins.length > 100) invalid();
+  const skills = document.skills.map((item) => {
+    if (!item || typeof item.description !== 'string' || item.description.length > 500 || typeof item.enabled !== 'boolean') invalid();
+    return { canonical_slug: canonicalSkillSlug(item.canonical_slug), description: item.description, enabled: item.enabled };
+  });
+  const plugins = document.plugins.map((item) => {
+    if (!item || typeof item.description !== 'string' || item.description.length > 500 || typeof item.enabled !== 'boolean'
+      || typeof item.version !== 'string' || !Array.isArray(item.allow_build)
+      || PROTECTED_PACKAGES.has(item.name)) invalid();
+    validatePackage(item.name, item.version, item.allow_build);
+    return { name: item.name, version: 'latest', description: item.description, enabled: item.enabled, allow_build: [...item.allow_build] };
+  });
+  if (new Set(skills.map((item) => item.canonical_slug)).size !== skills.length
+    || new Set(plugins.map((item) => item.name)).size !== plugins.length) invalid();
+  return { schema_version: 1, revision: document.revision, user_id: userId, auto_sync: document.auto_sync,
+    skills_enabled: document.skills_enabled, skill_registry: document.skill_registry,
+    skills: skills.filter((item) => item.enabled), plugins: plugins.filter((item) => item.enabled) };
+}
+export async function fetchPlatformConfig(platformUrl, token, userId, signal) {
+  const response = await platformFetch(`${platformUrl.replace(/\/+$/, '')}/api/plugin/v1/config`, {
+    signal, headers: { Authorization: `Bearer ${token}` },
+  });
+  if (response.status === 404) {
+    // 仅接受 FastAPI 缺路由的 JSON，不接受代理 HTML 404 或业务 404。
+    const body = response.headers.get('content-type')?.includes('application/json')
+      ? await response.json().catch(() => null) : null;
+    if (body?.detail === 'Not Found' && Object.keys(body).length === 1) {
+      return { document: compatibilityDefaults(userId), source: 'compatibility' };
+    }
+    throw new Error('默认能力接口不可用，请检查平台地址或升级后台');
+  }
+  if (!response.ok) throw await platformError(response, '获取默认能力配置失败，请稍后重试');
+  let document;
+  try { document = await response.json(); } catch { throw new Error('平台清单响应不是有效 JSON，请检查平台地址后重试'); }
+  return { document: validatePlatformConfig(document, userId), source: 'platform' };
+}

package/lib/proc.js

@@ -309,11 +309,12 @@ function composeChildEnv(extraEnv) {
   return childEnv;
 }
 
-function execResolvedPath(resolved, args, { timeoutMs, cwd, env } = {}) {
+function execResolvedPath(resolved, args, { timeoutMs, cwd, env, signal } = {}) {
   const childEnv = composeChildEnv(env);
   const shim = cmdShimInvocation(process.platform, resolved, args);
   return execFileAsync(shim ? shim.file : resolved, shim ? shim.args : args, {
     timeout: timeoutMs,
+    signal,
     killSignal: 'SIGKILL',
     cwd,
     env: childEnv,
@@ -396,12 +397,13 @@ function isLarkCliTool(tool) {
   return ['lark-cli', 'lark-cli.cmd', 'lark-cli.exe'].includes(name);
 }
 
-export async function runCliTool(tool, args, { timeoutMs = 300000, cwd, env } = {}) {
+export async function runCliTool(tool, args, { timeoutMs = 300000, cwd, env, signal } = {}) {
   try {
     const { stdout, stderr } = await execResolved(tool, args, {
       timeoutMs,
       cwd,
       env,
+      signal,
     });
     return { stdout, stderr };
   } catch (error) {
@@ -464,8 +466,8 @@ function missingCommandGuidance(tool) {
 }
 
 /** dsh plugin 子命令：转发给官方 CLI（profile 由调用方给出）。 */
-export function dshPluginCli(args, profile = 'web') {
-  return runCliTool('dsh', ['plugin', '--profile', profile, ...args]);
+export function dshPluginCli(args, profile = 'web', options = {}) {
+  return runCliTool('dsh', ['plugin', '--profile', profile, ...args], options);
 }
 
 /** pnpm 子命令（当前仅 view 查询）；cwd 指向目标 profile 目录。 */

package/lib/profile-plugins.js

@@ -0,0 +1,143 @@
+// 当前 profile 的插件操作；读取真实包和注册状态，写操作共享实例队列。
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { dshPluginCli, pnpmViewLatest } from './proc.js';
+import { resolveDshHome } from './store.js';
+
+export const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+export const EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const PROTECTED_PACKAGES = new Set([
+  'dsh-agentone', '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless',
+]);
+export function validatePackage(name, version = 'latest', allowBuild = []) {
+  if (typeof name !== 'string' || name.length > 214 || !NPM_NAME.test(name)) throw new Error('插件名不合法，请填写完整的 npm 包名');
+  if (version !== 'latest' && !EXACT_VERSION.test(version)) throw new Error('插件版本仅支持精确版本或 latest');
+  if (!Array.isArray(allowBuild) || allowBuild.length > 20 || allowBuild.some((entry) => typeof entry !== 'string' || entry.length > 214 || !NPM_NAME.test(entry))) {
+    throw new Error('安装期构建授权必须为明确的 npm 包名');
+  }
+}
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw new Error('插件配置文件无法读取，请检查本机 profile'); }
+}
+function validProfile(name) {
+  return typeof name === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$/.test(name) && name !== 'node_modules';
+}
+export function createProfilePlugins({ ctx, config = {}, desktopRun, runCli = dshPluginCli, latest = pnpmViewLatest }) {
+  let queue = Promise.resolve();
+  let closed = false;
+  let policy = [];
+  function target() {
+    if (closed) throw new Error('插件已停止，请重新打开后再试');
+    const desktop = ctx.get?.('desktopProfiles');
+    const isDesktop = Boolean(desktop) || /DSH Desktop\.(?:app|exe)/i.test(process.execPath);
+    const name = desktop?.current?.name || (!isDesktop ? config.profileName : null);
+    if (!validProfile(name)) throw new Error('无法确定当前 DSH profile，请在 AgentOne 插件配置中填写 profileName 后重启');
+    const homeService = ctx.get?.('dshHomePath');
+    const home = resolve(config.dshHome || (typeof homeService === 'function' ? homeService() : homeService) || resolveDshHome());
+    return { home, name, dir: join(home, 'profiles', name), desktop: isDesktop };
+  }
+  function enqueue(operation) {
+    let expected;
+    try { expected = target(); } catch (error) { return Promise.reject(error); }
+    const result = queue.catch(() => {}).then(() => { check(expected); return operation(expected); });
+    queue = result.catch(() => {});
+    return result;
+  }
+  function check(expected, options = {}) {
+    options.signal?.throwIfAborted();
+    if (options.isCurrent && !options.isCurrent()) throw new Error('登录身份或配置已改变，请重新同步');
+    const actual = target();
+    if (actual.dir !== expected.dir || actual.desktop !== expected.desktop) throw new Error('当前 profile 已改变，请重新同步');
+  }
+  async function list() {
+    const current = target();
+    const manifest = await readJson(join(current.dir, 'package.json'));
+    const dependencies = manifest?.dependencies || {};
+    const bundles = manifest?.dsh?.profile?.bundles || [];
+    if (!Array.isArray(bundles)) throw new Error('当前 profile 的插件注册清单格式异常');
+    const names = [...new Set([...Object.keys(dependencies), ...bundles, ...policy.map((item) => item.name)])]
+      .filter((name) => !name.startsWith('@deepseek-ai/dsh-') || !PROTECTED_PACKAGES.has(name));
+    const plugins = [];
+    for (const name of names) {
+      validatePackage(name);
+      const spec = dependencies[name] ?? null;
+      const pkg = await readJson(join(current.dir, 'node_modules', name, 'package.json'));
+      const version = typeof pkg?.version === 'string' ? pkg.version : null;
+      const patch = pkg?.dsh?.bundle?.patch;
+      let bundled = false;
+      if (typeof patch === 'string' && patch && !isAbsolute(patch)) {
+        const packageRoot = join(current.dir, 'node_modules', name);
+        const patchPath = resolve(packageRoot, patch);
+        const inside = relative(packageRoot, patchPath);
+        if (inside && !inside.startsWith('..') && !isAbsolute(inside)) {
+          try { bundled = Boolean((await readFile(patchPath, 'utf8')).trim()); } catch {}
+        }
+      }
+      const registered = Boolean(version && bundled && bundles.includes(name));
+      const managed = policy.find((item) => item.name === name);
+      plugins.push({ name, spec, version, bundled, registered, active: registered,
+        source: typeof spec === 'string' && /^(?:file|link|workspace):/.test(spec) ? '本地链接' : 'npm',
+        builtin: Boolean(managed) || name === 'dsh-agentone',
+        description: managed?.description || null, target_version: managed?.version || null,
+        state: registered ? 'restart_required' : version ? 'pending' : 'missing',
+        loaded: null,
+      });
+    }
+    return { profile: current.name, bundles, plugins };
+  }
+  async function execute(args, current, options) {
+    check(current, options);
+    await options.beforeCommit?.();
+    check(current, options);
+    if (current.desktop) {
+      const service = ctx.get?.('desktopPnpm');
+      if (!service || !desktopRun) throw new Error('桌面插件安装通道尚未就绪，请稍后重试');
+      return desktopRun(service, current.dir)(args, options);
+    }
+    return runCli(args, current.name, { env: { DSH_HOME: current.home }, signal: options.signal });
+  }
+  function install(name, version = 'latest', options = {}) {
+    validatePackage(name, version, options.allowBuild || []);
+    return enqueue(async () => {
+      const current = target(); check(current, options);
+      const before = (await list()).plugins.find((plugin) => plugin.name === name);
+      if (options.missingOnly && before?.source === '本地链接') throw new Error('插件使用本地链接，请确认后手动应用');
+      if (options.missingOnly && !options.updateLatest && before?.registered) {
+        return { ...before, state: version !== 'latest' && version !== before.version ? 'pending' : 'current' };
+      }
+      const wanted = options.missingOnly && !options.updateLatest && before?.version ? before.version
+        : version === 'latest' ? await latest(name, current.dir) : version;
+      if (before?.registered && before.version === wanted) return { ...before, state: 'current' };
+      if (!wanted || !EXACT_VERSION.test(wanted)) throw new Error('查询插件目标版本失败，请稍后重试');
+      let commandError = null;
+      try { await execute(['add', `${name}@${wanted}`, ...(options.allowBuild || []).map((entry) => `--allow-build=${entry}`)], current, options); }
+      catch (error) { commandError = error; }
+      check(current, options);
+      const installed = (await list()).plugins.find((plugin) => plugin.name === name);
+      const valid = installed?.version === wanted && installed?.bundled && installed?.registered;
+      if (commandError && (!/ERR_PNPM_IGNORED_BUILDS/.test(commandError.message) || !valid)) throw commandError;
+      if (!valid) throw new Error(`插件安装未完成：需确认版本 ${wanted}、插件声明与 profile 注册，请重试`);
+      return { ...installed, state: 'restart_required', registered: true, loaded: null };
+    });
+  }
+  function remove(name, options = {}) {
+    validatePackage(name);
+    if (PROTECTED_PACKAGES.has(name)) throw new Error('AgentOne 自身和 DSH 基础组件不可卸载');
+    if (policy.some((item) => item.name === name)) throw new Error('此插件由平台默认能力清单管理，请先由管理员停用');
+    return enqueue(async () => {
+      const current = target(); await execute(['remove', name], current, options); check(current, options);
+      const state = await list();
+      if (state.plugins.some((plugin) => plugin.name === name)) throw new Error('插件卸载未完成，请重试');
+      return state;
+    });
+  }
+  return { target, list, install, remove, resolveVersion: async (name, version = 'latest') => {
+    validatePackage(name, version);
+    const exact = version === 'latest' ? await latest(name, target().dir) : version;
+    if (!exact || !EXACT_VERSION.test(exact)) throw new Error('查询插件目标版本失败，请稍后重试');
+    return exact;
+  }, setPolicy(entries) { policy = entries; },
+    async dispose() { closed = true; await queue; },
+  };
+}

package/lib/skill-state.js

@@ -0,0 +1,102 @@
+// 技能的物理目录记录：绑定平台、用户与 registry；不保存 token。
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { resolveDshHome } from './store.js';
+
+export function canonicalSkillSlug(value) {
+  if (typeof value === 'string') {
+    value = value.trim();
+    if (value.includes('/')) {
+      const parts = value.split('/');
+      if (parts.length !== 2 || parts.some((part) => !/^[a-z0-9][a-z0-9_-]*$/.test(part) || part.includes('--'))) {
+        throw new Error('技能标识应为技能名、命名空间/技能名或命名空间--技能名');
+      }
+      value = parts.join('--');
+    }
+  }
+  if (typeof value !== 'string' || value.length > 255 || !/^[a-z0-9][a-z0-9_-]*$/.test(value)) {
+    throw new Error('技能标识格式不正确');
+  }
+  if (value.includes('--')) {
+    const [namespace, slug, ...extra] = value.split('--');
+    if (!namespace || !slug || extra.length) throw new Error('技能标识格式不正确');
+    if (namespace === 'global') return slug;
+  }
+  return value;
+}
+
+export function skillPaths(config, canonicalSlug) {
+  const slug = canonicalSkillSlug(canonicalSlug);
+  const home = resolve(config?.dshHome || resolveDshHome());
+  const root = join(home, 'skills');
+  return { home, root, dir: join(root, slug), record: join(home, 'agentone', 'skill-state', `${slug}.json`) };
+}
+
+export function skillOwner(platformUrl, options = {}) {
+  return {
+    platform: platformUrl.replace(/\/+$/, ''),
+    user_id: options.userId || null,
+    registry: (options.registry || '').replace(/\/+$/, ''),
+  };
+}
+
+export async function readSkillRecord(paths) {
+  try {
+    const record = JSON.parse(await readFile(paths.record, 'utf8'));
+    return record?.schema_version === 1 ? record : null;
+  } catch (error) {
+    if (error?.code && error.code !== 'ENOENT') throw error;
+    return null;
+  }
+}
+
+export async function writeSkillRecord(paths, record) {
+  const parent = join(paths.home, 'agentone', 'skill-state');
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const temporary = `${paths.record}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify(record) + '\n', { mode: 0o600 });
+  await rename(temporary, paths.record);
+}
+
+/** 摘要包含全部普通文件的相对路径与内容；拒绝 symlink，避免越界读写。 */
+export async function skillDigest(dir) {
+  const root = await lstat(dir);
+  if (root.isSymbolicLink() || !root.isDirectory()) throw new Error('技能目录必须是普通目录，请检查本机文件');
+  const hash = createHash('sha256');
+  async function walk(current, prefix) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const relative = `${prefix}${entry.name}`;
+      const path = join(current, entry.name);
+      if (entry.isSymbolicLink()) throw new Error('技能目录包含符号链接，请先检查本机文件');
+      if (entry.isDirectory()) await walk(path, `${relative}/`);
+      else if (entry.isFile()) {
+        const bytes = await readFile(path);
+        hash.update(JSON.stringify([relative, bytes.length])); hash.update(bytes);
+      } else throw new Error('技能目录包含不支持的文件类型');
+    }
+  }
+  await walk(dir, '');
+  return hash.digest('hex');
+}
+
+export async function localSkillState(platformUrl, canonicalSlug, options = {}) {
+  const paths = skillPaths(options.config, canonicalSlug);
+  const record = await readSkillRecord(paths);
+  let stat;
+  try { stat = await lstat(paths.dir); }
+  catch (error) { if (error.code === 'ENOENT') return { state: 'missing', record, paths }; throw error; }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return { state: 'conflict', record, paths };
+  const owner = skillOwner(platformUrl, options);
+  if (!record || Object.keys(owner).some((key) => owner[key] !== record[key])) {
+    return { state: 'conflict', record, paths };
+  }
+  let digest;
+  try {
+    if (!(await readFile(join(paths.dir, 'SKILL.md'), 'utf8')).trim()) return { state: 'conflict', record, paths };
+    digest = await skillDigest(paths.dir);
+  } catch { return { state: 'conflict', record, paths }; }
+  if (digest !== record.digest) return { state: 'conflict', record, paths };
+  return { state: record.report_pending ? 'report_pending' : 'current', record, paths };
+}