@kingsoftcloud/agentkit-personal-assistant 0.0.0-stage → 0.1.6

package/scripts/build-client.mjs

@@ -0,0 +1,82 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build, context } from 'esbuild';
+
+/**
+ * DSH 客户端插件构建器。
+ *
+ * 运行入口是 `dist/client.js`（`package.json` 的 `exports['./client']`），
+ * 不是 `src/client/*.mjs`；改完源码必须重新构建，Studio 里按 Cmd+R 刷新即可生效，
+ * 不需要退出应用（只有 Host 代码、插件树/package.json bundles 变更才需要重启）。
+ *
+ * 用法：
+ *   node scripts/build-client.mjs
+ *   node scripts/build-client.mjs --watch
+ *   node scripts/build-client.mjs --watch --out-dir ~/.dsh/profiles/<profile>/node_modules/@kingsoftcloud/agentkit-personal-assistant/dist
+ */
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const watch = argv.includes('--watch');
+const outDirArg = argv.includes('--out-dir') ? argv[argv.indexOf('--out-dir') + 1] : '';
+const outDir = outDirArg ? resolve(outDirArg.replace(/^~(?=$|\/)/u, process.env.HOME || '~')) : resolve(root, 'dist');
+
+const stamp = new Date().toISOString();
+
+const options = {
+  absWorkingDir: root,
+  entryPoints: ['src/client/entry.mjs'],
+  bundle: true,
+  format: 'iife',
+  platform: 'browser',
+  target: 'es2022',
+  minify: true,
+  legalComments: 'none',
+  write: false,
+  metafile: true,
+  logLevel: 'silent',
+  // 面板可在页脚渲染构建时间，便于确认 Cmd+R 后拿到的是最新产物。
+  define: { __PA_CLIENT_BUILD__: JSON.stringify(stamp) },
+};
+
+function verifiedOutput(result) {
+  const output = result.outputFiles?.[0]?.text || '';
+  if (!output) throw new Error('客户端构建没有产物');
+  if (!output.includes('window.__ModuleLoader__.load({') || !output.includes('@kingsoftcloud/agentkit-personal-assistant')) throw new Error('DSH 客户端注册入口丢失');
+  if (Object.keys(result.metafile.inputs).some(path => !path.startsWith('src/client/'))) throw new Error('浏览器产物含 Host 代码');
+  return output;
+}
+
+async function emit(result) {
+  const output = verifiedOutput(result);
+  await mkdir(outDir, { recursive: true });
+  await writeFile(resolve(outDir, 'client.js'), output);
+  return output;
+}
+
+if (watch) {
+  const ctx = await context({
+    ...options,
+    plugins: [{
+      name: 'emit-verified-client',
+      setup(build) {
+        build.onEnd(async result => {
+          if (result.errors.length) return;
+          try {
+            const output = await emit(result);
+            const time = new Date().toLocaleTimeString('zh-CN', { hour12: false });
+            console.log(`[${time}] dist/client.js ${output.length} 字节 → ${outDir}（Studio 里 Cmd+R 刷新）`);
+          } catch (error) {
+            console.error(`[build:client] ${error.message}`);
+          }
+        });
+      },
+    }],
+  });
+  await ctx.watch();
+  console.log(`watching src/client → ${outDir}（改完在 Studio 按 Cmd+R，无需重启应用）`);
+} else {
+  const result = await build(options);
+  const output = await emit(result);
+  console.log(`dist/client.js ${output.length} 字节 → ${outDir}（build ${stamp}）`);
+}

package/scripts/computer-agentd-launcher.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+set -eu
+exec node "$(dirname "$0")/../runtime/computer-agentd.mjs" "$@"

package/scripts/deterministic_tar.py

@@ -0,0 +1,21 @@
+import os
+import sys
+import tarfile
+
+root, archive = sys.argv[1:]
+with tarfile.open(archive, 'w') as output:
+    for base, dirs, files in os.walk(root):
+        dirs.sort()
+        files.sort()
+        for name in dirs + files:
+            path = os.path.join(base, name)
+            arcname = os.path.relpath(path, root)
+            info = output.gettarinfo(path, arcname=arcname)
+            info.uid = info.gid = 0
+            info.uname = info.gname = ''
+            info.mtime = 0
+            if info.isfile():
+                with open(path, 'rb') as stream:
+                    output.addfile(info, stream)
+            else:
+                output.addfile(info)

package/scripts/install-local.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/** 离线安装个人助理、原生侧栏和可选的 Studio 宿主包；默认仅检查。 */
+import { promises as fs } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, posix } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { spawnSync } from 'node:child_process';
+
+const PA = '@kingsoftcloud/agentkit-personal-assistant';
+const SIDEBAR = '@deepseek-ai/dsh-client-ui-sidebar-right';
+const STUDIO = '@kingsoftcloud/agentkit-studio';
+const NODE = '/Applications/AgentKit Studio.app/Contents/MacOS/AgentKit Studio';
+const DSH = '/Applications/AgentKit Studio.app/Contents/Resources/app.asar/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js';
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const stat = async path => fs.lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+const fail = message => { throw new Error(message); };
+function parseJson(bytes, label) {
+  try { return JSON.parse(bytes.toString()); } catch (error) { fail(label + ' 不是有效 JSON；不打印原文'); }
+}
+
+function readTar(archive) {
+  const tar = gunzipSync(archive, { maxOutputLength: 200 * 1024 * 1024 });
+  const files = [], paths = new Set();
+  let offset = 0, unpacked = 0, pax = null;
+  const field = (header, start, length) => header.subarray(start, start + length).toString().replace(/\0.*$/s, '');
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512); offset += 512;
+    if (header.every(byte => byte === 0)) break;
+    const checksum = Number.parseInt(field(header, 148, 8).trim(), 8);
+    const actual = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+    if (checksum !== actual) fail('tar 头校验失败');
+    const sizeText = field(header, 124, 12).trim();
+    if (!/^[0-7]+$/.test(sizeText)) fail('tar 文件长度无效');
+    const size = Number.parseInt(sizeText, 8), type = field(header, 156, 1);
+    if (offset + size > tar.length || !Number.isSafeInteger(size)) fail('tar 文件被截断');
+    if (type === 'x') {
+      if (pax) fail('tar PAX 扩展头不能重叠');
+      pax = Object.create(null);
+      const data = tar.subarray(offset, offset + size);
+      for (let cursor = 0; cursor < data.length;) {
+        const space = data.indexOf(32, cursor), lengthText = data.subarray(cursor, space).toString();
+        if (space < cursor || !/^[1-9][0-9]*$/.test(lengthText)) fail('tar PAX 长度无效');
+        const end = cursor + Number(lengthText);
+        if (!Number.isSafeInteger(end) || end > data.length || end <= space + 2 || data[end - 1] !== 10) fail('tar PAX 内容无效');
+        const record = data.subarray(space + 1, end - 1).toString(), equal = record.indexOf('='), key = record.slice(0, equal);
+        if (equal < 1 || !['path', 'size', 'mtime', 'atime', 'ctime', 'uid', 'gid', 'uname', 'gname'].includes(key) || Object.hasOwn(pax, key)) fail('tar PAX 字段不安全');
+        pax[key] = record.slice(equal + 1); cursor = end;
+      }
+      offset += Math.ceil(size / 512) * 512; continue;
+    }
+    if (!['', '0', '5'].includes(type)) fail('tar 不允许链接或特殊文件');
+    if (pax?.size !== undefined && (!/^[0-9]+$/.test(pax.size) || Number(pax.size) !== size)) fail('tar PAX 文件长度不一致');
+    const prefix = field(header, 345, 155), name = pax?.path ?? ((prefix ? prefix + '/' : '') + field(header, 0, 100));
+    pax = null;
+    const normalized = name.replace(/\/$/, '');
+    if (!normalized.startsWith('package/') || normalized.includes('\\') || normalized.includes('\n') ||
+        posix.normalize(normalized) !== normalized || normalized.split('/').some(part => part === '..' || part === '.')) {
+      fail('tar 成员路径不安全');
+    }
+    if (paths.has(normalized)) fail('tar 成员路径重复');
+    paths.add(normalized);
+    const path = normalized.slice('package/'.length);
+    unpacked += size;
+    if (unpacked > 200 * 1024 * 1024) fail('tar 解包大小超限');
+    files.push({ path, directory: type === '5', mode: Number.parseInt(field(header, 100, 8).trim(), 8) & 0o777,
+      data: tar.subarray(offset, offset + size) });
+    offset += Math.ceil(size / 512) * 512;
+  }
+  if (pax) fail('tar PAX 扩展头缺少后续文件');
+  // 写入前检查文件/目录冲突，避免归档顺序改变路径解析。
+  const regular = new Set(files.filter(file => !file.directory).map(file => file.path));
+  for (const file of files) for (let parent = posix.dirname(file.path); parent !== '.'; parent = posix.dirname(parent)) {
+    if (regular.has(parent)) fail('tar 文件与目录冲突');
+  }
+  return files;
+}
+
+async function requireDirectory(path, description, optional = false) {
+  const info = await stat(path);
+  if (!info && optional) return false;
+  if (!info?.isDirectory() || info.isSymbolicLink()) fail(description + '必须为真实目录，拒绝链接');
+  return true;
+}
+
+async function extract(files, directory) {
+  await fs.mkdir(directory, { mode: 0o700 });
+  for (const file of files) {
+    const target = join(directory, file.path);
+    await fs.mkdir(file.directory ? target : dirname(target), { recursive: true });
+    if (!file.directory) await fs.writeFile(target, file.data, { flag: 'wx', mode: file.mode || 0o644 });
+  }
+}
+
+export async function installLocal({ profile, manifest, apply = false, dshNode = NODE, dshBin = DSH }) {
+  if (!isAbsolute(profile || '')) fail('--profile 必须是绝对路径');
+  profile = resolve(profile);
+  if (basename(dirname(profile)) !== 'profiles' || !basename(profile)) fail('目标必须是 <DSH_HOME>/profiles/<名称>');
+  await requireDirectory(profile, 'profile');
+  await requireDirectory(dirname(profile), 'profiles');
+  await requireDirectory(dirname(dirname(profile)), 'DSH_HOME');
+  const packagePath = join(profile, 'package.json');
+  const packageInfo = await stat(packagePath);
+  if (!packageInfo?.isFile()) fail('profile package.json 不存在或为链接');
+  const original = await fs.readFile(packagePath), pkg = parseJson(original, 'profile package.json');
+  const manifestPath = resolve(manifest), manifestBytes = await fs.readFile(manifestPath);
+  const release = parseJson(manifestBytes, 'release manifest');
+  if (!Array.isArray(release.packages) || ![2, 3].includes(release.packages.length)) fail('manifest 必须包含个人助理、原生侧栏和可选的 Studio 包');
+  const names = release.packages.map(item => item.pkgName);
+  if (new Set(names).size !== names.length || !names.includes(PA) || !names.includes(SIDEBAR) ||
+      names.some(name => ![PA, SIDEBAR, STUDIO].includes(name))) fail('manifest 包集合不正确');
+  const sourceCommit = release.sidebar?.sourceCommit || release.packages.find(item => item.pkgName === SIDEBAR).sourceCommit;
+  if (!/^[a-f0-9]{40}$/.test(sourceCommit || '')) fail('manifest 缺少侧栏 sourceCommit');
+  const prepared = [];
+  for (const item of release.packages) {
+    if (!item.version || typeof item.version !== 'string' || !/^[a-f0-9]{64}$/.test(item.sha256 || '') ||
+        !item.filename || basename(item.filename) !== item.filename || item.filename.includes('\\')) fail('包版本、文件名或 SHA256 无效');
+    const source = join(dirname(manifestPath), item.filename);
+    if (!(await stat(source))?.isFile()) fail('安装包不存在或为链接：' + item.filename);
+    const archive = await fs.readFile(source);
+    if (sha256(archive) !== item.sha256) fail('安装包 SHA256 不匹配：' + item.pkgName);
+    const files = readTar(archive), metaFile = files.find(file => file.path === 'package.json' && !file.directory);
+    const meta = metaFile && parseJson(metaFile.data, '归档 package.json');
+    if (meta?.name !== item.pkgName || meta?.version !== item.version) fail('归档包名或版本不匹配：' + item.pkgName);
+    const clientPath = item.pkgName === SIDEBAR ? 'lib/client.js' : 'dist/client.js';
+    const client = files.find(file => file.path === clientPath && !file.directory);
+    if (!client?.data.length || (item.pkgName === SIDEBAR && !client.data.includes(Buffer.from('registerPanelSurface')))) fail('客户端产物缺失：' + item.pkgName);
+    const [scope, leaf] = item.pkgName.split('/');
+    prepared.push({ item, source, archive, files, scope, leaf });
+  }
+  const modules = join(profile, 'node_modules'), cache = join(profile, '.pa-artifacts'), backups = join(profile, '.pa-backups');
+  const modulesExisted = await requireDirectory(modules, 'node_modules', true);
+  const cacheExisted = await requireDirectory(cache, '.pa-artifacts', true);
+  await requireDirectory(backups, '.pa-backups', true);
+  for (const entry of prepared) {
+    const scopeInfo = await stat(join(modules, entry.scope));
+    if (scopeInfo && !scopeInfo.isDirectory() && !scopeInfo.isSymbolicLink()) fail('包命名空间不是目录');
+    if (scopeInfo?.isSymbolicLink()) await fs.realpath(join(modules, entry.scope));
+    entry.namespaceIsLink = scopeInfo?.isSymbolicLink() || false;
+    entry.cacheName = entry.item.sha256 + '-' + entry.item.filename;
+    const cachePath = join(cache, entry.cacheName), cached = await stat(cachePath);
+    if (cached && (!cached.isFile() || sha256(await fs.readFile(cachePath)) !== entry.item.sha256)) fail('制品缓存存在冲突');
+  }
+  if (pkg.dependencies != null && (typeof pkg.dependencies !== 'object' || Array.isArray(pkg.dependencies))) fail('profile dependencies 格式无效');
+  if (pkg.dsh != null && (typeof pkg.dsh !== 'object' || Array.isArray(pkg.dsh))) fail('profile dsh 格式无效');
+  if (pkg.dsh?.profile != null && (typeof pkg.dsh.profile !== 'object' || Array.isArray(pkg.dsh.profile))) fail('profile dsh.profile 格式无效');
+  if (pkg.dsh?.profile?.bundles != null && !Array.isArray(pkg.dsh.profile.bundles)) fail('profile bundles 格式无效');
+  const plan = { dryRun: !apply, profile, manifestSha256: sha256(manifestBytes), sidebarSourceCommit: sourceCommit,
+    packages: prepared.map(({ item, namespaceIsLink }) => ({ ...item, namespaceIsLink })),
+    credentialsChanged: false, cloudBindingCreated: false, requiresUserRestart: true, appReplaced: false };
+  if (!apply) return plan;
+
+  const lock = join(profile, '.pa-install.lock');
+  const handle = await fs.open(lock, 'wx', 0o600).catch(error => { if (error.code === 'EEXIST') fail('该 profile 已有安装锁，请确认没有并发安装'); throw error; });
+  await handle.close();
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-') + '-' + randomUUID().slice(0, 8);
+  const backup = join(backups, stamp + '-personal-assistant'), stage = join(profile, '.pa-stage-' + stamp);
+  const changed = [], newCache = [], configNames = ['cordis.patch.yml', 'cordis.yml'], configModes = new Map();
+  let packageChanged = false, setupStarted = false;
+  try {
+    await fs.mkdir(backups, { recursive: true, mode: 0o700 });
+    await fs.mkdir(backup, { mode: 0o700 });
+    await fs.writeFile(join(backup, 'package.json'), original, { mode: 0o600 });
+    for (const name of configNames) {
+      const info = await stat(join(profile, name));
+      if (info) {
+        await fs.cp(join(profile, name), join(backup, name), { dereference: false, verbatimSymlinks: true });
+        if (!info.isSymbolicLink()) await fs.chmod(join(backup, name), 0o600);
+      }
+      configModes.set(name, info?.mode);
+    }
+    await fs.mkdir(stage, { mode: 0o700 });
+    for (const entry of prepared) await extract(entry.files, join(stage, entry.leaf));
+    setupStarted = true;
+    await fs.mkdir(modules, { recursive: true });
+    await fs.mkdir(cache, { recursive: true, mode: 0o700 });
+    for (const entry of prepared) {
+      const namespace = join(modules, entry.scope), target = join(namespace, entry.leaf);
+      const record = { namespace, target, namespaceBackup: join(backup, entry.scope + '.original'),
+        packageBackup: join(backup, entry.leaf + '.original'), namespaceCreated: false, namespaceMoved: false, packageMoved: false, installed: false };
+      changed.push(record);
+      const scopeInfo = await stat(namespace);
+      if (scopeInfo?.isSymbolicLink()) {
+        const oldRoot = await fs.realpath(namespace), children = await fs.readdir(oldRoot);
+        await fs.rename(namespace, record.namespaceBackup); record.namespaceMoved = true;
+        await fs.mkdir(namespace); record.namespaceCreated = true;
+        for (const child of children) if (child !== entry.leaf) await fs.symlink(join(oldRoot, child), join(namespace, child));
+      } else {
+        if (scopeInfo && !scopeInfo.isDirectory()) fail('包命名空间在安装过程中被替换');
+        if (!scopeInfo) { await fs.mkdir(namespace); record.namespaceCreated = true; }
+        if (await stat(target)) { await fs.rename(target, record.packageBackup); record.packageMoved = true; }
+      }
+      await fs.rename(join(stage, entry.leaf), target); record.installed = true;
+      await fs.writeFile(join(target, 'agentkit-local-release.json'), JSON.stringify({ ...entry.item, sidebarSourceCommit: sourceCommit }, null, 2) + '\n');
+      const cached = join(cache, entry.cacheName);
+      if (!await stat(cached)) { await fs.writeFile(cached, entry.archive, { flag: 'wx', mode: 0o600 }); newCache.push(cached); }
+      pkg.dependencies ??= {};
+      pkg.dependencies[entry.item.pkgName] = 'file:./.pa-artifacts/' + entry.cacheName;
+    }
+    pkg.dsh ??= {}; pkg.dsh.profile ??= {}; pkg.dsh.profile.bundles ??= [];
+    if (!pkg.dsh.profile.bundles.includes(PA)) pkg.dsh.profile.bundles.push(PA);
+    const pending = join(stage, 'package.json');
+    await fs.writeFile(pending, JSON.stringify(pkg, null, 2) + '\n', { mode: packageInfo.mode & 0o777 });
+    await fs.rename(pending, packagePath); packageChanged = true;
+    const dump = spawnSync(dshNode, [dshBin, '--profile', basename(profile), '--dump-config'], {
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1', DSH_HOME: dirname(dirname(profile)) },
+      timeout: 60000, maxBuffer: 32 * 1024 * 1024, encoding: 'utf8' });
+    if (dump.error || dump.status !== 0) fail('DSH 配置合成失败，退出码 ' + String(dump.status ?? dump.error?.code ?? 'unknown') + '；输出可能含凭据，不打印');
+    const proof = { ...plan, dryRun: false, backup, dumpConfigExit: 0, dumpConfigLines: dump.stdout.split('\n').length,
+      dumpConfigWarningLines: dump.stderr.split('\n').filter(Boolean).length, artifactCache: cache, studioRestarted: false };
+    await fs.writeFile(join(backup, 'install-proof.json'), JSON.stringify(proof, null, 2) + '\n', { mode: 0o600 });
+    return proof;
+  } catch (error) {
+    const rollbackErrors = [];
+    const restore = async action => { try { await action(); } catch (rollbackError) { rollbackErrors.push(rollbackError.code || 'RESTORE_FAILED'); } };
+    for (const record of changed.reverse()) {
+      if (record.installed) await restore(() => fs.rm(record.target, { recursive: true, force: true }));
+      if (record.namespaceMoved) {
+        await restore(() => fs.rm(record.namespace, { recursive: true, force: true }));
+        await restore(() => fs.rename(record.namespaceBackup, record.namespace));
+      } else {
+        if (record.packageMoved) await restore(() => fs.rename(record.packageBackup, record.target));
+        if (record.namespaceCreated) await restore(() => fs.rmdir(record.namespace));
+      }
+    }
+    if (packageChanged) await restore(async () => {
+      const pending = join(profile, '.pa-package-restore-' + stamp);
+      await fs.writeFile(pending, original, { mode: packageInfo.mode & 0o777 }); await fs.rename(pending, packagePath);
+    });
+    for (const name of configNames) if (configModes.has(name)) await restore(async () => {
+      await fs.rm(join(profile, name), { force: true });
+      if (configModes.get(name) !== undefined) {
+        await fs.cp(join(backup, name), join(profile, name), { dereference: false, verbatimSymlinks: true });
+        if (!(await stat(join(profile, name))).isSymbolicLink()) await fs.chmod(join(profile, name), configModes.get(name) & 0o777);
+      }
+    });
+    for (const file of newCache) await restore(() => fs.rm(file, { force: true }));
+    if (setupStarted && !cacheExisted) await restore(() => fs.rmdir(cache));
+    if (setupStarted && !modulesExisted) await restore(() => fs.rmdir(modules));
+    error.installResult = { rolledBack: rollbackErrors.length === 0, rollbackErrors, backup, studioRestarted: false };
+    throw error;
+  } finally {
+    await fs.rm(stage, { recursive: true, force: true });
+    await fs.rm(lock, { force: true });
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2), options = {};
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--apply') { options.apply = true; continue; }
+      const key = { '--profile': 'profile', '--manifest': 'manifest', '--dsh-node': 'dshNode', '--dsh-bin': 'dshBin' }[args[i]];
+      if (!key || !args[i + 1] || args[i + 1].startsWith('--')) fail('参数无效；用法：node install-local.mjs --profile <绝对路径> --manifest <release-manifest.json> [--apply]');
+      if (options[key] !== undefined) fail('参数重复'); options[key] = args[++i];
+    }
+    if (!options.manifest) fail('缺少 --manifest');
+    console.log(JSON.stringify(await installLocal(options), null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ error: error.message, ...error.installResult })); process.exitCode = 1;
+  }
+}

package/scripts/scan-secrets.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// 轻量密钥扫描：公开仓库 CI 用，检测 AK/SK、令牌、私钥和高危赋值。
+// 只做行级启发式检查；发现命中即失败，避免把凭证带进公开镜像。
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const ROOT = new URL('..', import.meta.url).pathname;
+
+const RULES = [
+  { name: '私钥块', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/u },
+  { name: 'AWS/金山云 AccessKey', pattern: /\bAKID[0-9A-Za-z]{16,}|\bAKIA[0-9A-Z]{16}\b|\bAKLT[0-9A-Za-z-]{10,}\b/u },
+  { name: '疑似 SecretKey 赋值', pattern: /(?:secret[_-]?key|access[_-]?key[_-]?secret)\s*[:=]\s*['"][A-Za-z0-9/+=]{24,}['"]/iu },
+  { name: 'npm token', pattern: /npm_[A-Za-z0-9]{36,}/u },
+  { name: 'GitHub token', pattern: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/u },
+  { name: 'Bearer 硬编码', pattern: /Bearer\s+[A-Za-z0-9._~+/-]{32,}/u },
+];
+
+const files = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8' }).trim().split('\n')
+  .filter(file => file && !/^(?:node_modules|\.artifacts)\//u.test(file));
+
+const hits = [];
+for (const file of files) {
+  let text;
+  try { text = readFileSync(ROOT + '/' + file, 'utf8'); }
+  catch { continue; }
+  // 测试夹具里允许出现假令牌（只保留私钥规则），避免把 mock 当成凭证。
+  const fixture = /^(?:test|\.artifacts)\//u.test(file);
+  text.split('\n').forEach((line, index) => {
+    for (const rule of RULES) {
+      if (fixture && rule.name !== '私钥块') continue;
+      if (rule.pattern.test(line)) hits.push(`${file}:${index + 1} [${rule.name}]`);
+    }
+  });
+}
+
+if (hits.length) {
+  console.error(`发现 ${hits.length} 处疑似密钥：`);
+  for (const hit of hits.slice(0, 50)) console.error('  ' + hit);
+  process.exit(1);
+}
+console.log(`密钥扫描通过：${files.length} 个文件，未发现疑似凭证`);

package/scripts/sync-public.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// 把当前提交导出成面向 GitHub 的公开快照：
+//   - 排除内部文档 docs/、本地产物 .artifacts/；不携带内部提交历史（单条初始提交）
+//   - 公开仓库只作为发布镜像，主仓仍在 ezone
+// 用法：
+//   node scripts/sync-public.mjs --remote git@github.com:kingsoftcloud/agentkit-personal-assistant.git [--apply]
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const root = resolve(import.meta.dirname, '..');
+const args = process.argv.slice(2);
+const apply = args.includes('--apply');
+const remote = args.includes('--remote') ? args[args.indexOf('--remote') + 1] : '';
+const EXCLUDE = ['docs/', '.artifacts/', '.worktrees/', 'output/'];
+
+const run = (file, args = []) => execFileSync(file, args, { cwd: root, stdio: 'pipe' }).toString();
+
+const dirty = run('git', ['status', '--porcelain']).trim();
+if (dirty) throw new Error('工作区不干净，先提交再同步：\n' + dirty);
+
+const files = run('git', ['ls-files']).trim().split('\n')
+  .filter(file => file && !EXCLUDE.some(prefix => file.startsWith(prefix)));
+if (!files.length) throw new Error('没有可导出的文件');
+
+const staging = mkdtempSync(join(tmpdir(), 'pa-public-'));
+try {
+  // 用 checkout-index 一次性导出当前索引（即 HEAD 的已跟踪文件）。
+  execFileSync('git', ['checkout-index', '-a', '-f', `--prefix=${staging}/`], { cwd: root, stdio: 'inherit' });
+  for (const prefix of EXCLUDE) rmSync(join(staging, prefix), { recursive: true, force: true });
+
+  const version = JSON.parse(run('git', ['show', 'HEAD:package.json'])).version;
+  const git = (...rest) => execFileSync('git', rest, { cwd: staging, stdio: 'pipe' });
+  git('init', '-q', '-b', 'main');
+  git('add', '-A');
+  git('-c', 'user.name=AgentKit', '-c', 'user.email=agentkit@kingsoft.cloud',
+    'commit', '-q', '-m', `AgentKit personal assistant ${version}`);
+  const head = git('rev-parse', '--short', 'HEAD').toString().trim();
+  console.log(`公开快照已生成：${staging}（${files.length} 个文件，提交 ${head}）`);
+  if (!apply) {
+    console.log('未传 --apply，未推送。');
+    process.exit(0);
+  }
+  if (!remote) throw new Error('--apply 需要同时提供 --remote <git url>');
+  git('remote', 'add', 'origin', remote);
+  git('push', '--force', 'origin', 'main');
+  console.log(`已推送到 ${remote} main`);
+}
+finally {
+  if (!apply) rmSync(staging, { recursive: true, force: true });
+}

package/scripts/verification/gateway-desktop-client.mjs

@@ -0,0 +1,142 @@
+/** 验收专用 Gateway WSS 客户端：TLS 保持验证，票据只放子协议，JPEG 只计数。 */
+import https from 'node:https';
+import { createHash, randomBytes } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+
+const PROTOCOL = 'agentkit.personal-assistant.desktop.v1', MAX_FRAME = 400 * 1024;
+const maskedFrame = (opcode, data = Buffer.alloc(0)) => {
+  const body = Buffer.isBuffer(data) ? data : Buffer.from(data), mask = randomBytes(4);
+  const header = Buffer.alloc(body.length < 126 ? 2 : 4);
+  header[0] = 0x80 | opcode;
+  if (body.length < 126) header[1] = 0x80 | body.length;
+  else { header[1] = 0x80 | 126; header.writeUInt16BE(body.length, 2); }
+  const payload = Buffer.from(body);
+  for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i % 4];
+  return Buffer.concat([header, mask, payload]);
+};
+
+export class GatewayDesktopClient extends EventEmitter {
+  constructor(socket, { openedAt = Date.now() } = {}) {
+    super(); this.socket = socket; this.openedAt = openedAt; this.events = []; this.sequence = 0;
+    this.frames = []; this.pending = Buffer.alloc(0); this.fragment = null; this.controlEpoch = 0; this.closed = false;
+    socket.on('data', chunk => { try { this.parse(chunk); } catch (error) { this.failure = error; socket.destroy(); this.emit('ended'); } });
+    socket.on('error', error => { this.failure = error; this.emit('ended'); });
+    socket.on('close', () => { this.closed = true; this.emit('ended'); });
+  }
+  parse(chunk) {
+    this.pending = Buffer.concat([this.pending, chunk]);
+    if (this.pending.length > 2 * 1024 * 1024) throw new Error('gateway WS receive buffer exceeds limit');
+    while (this.pending.length >= 2) {
+      const fin = Boolean(this.pending[0] & 0x80), opcode = this.pending[0] & 15;
+      if (this.pending[0] & 0x70) throw new Error('unexpected WS extension bits');
+      if (this.pending[1] & 0x80) throw new Error('server WS frames must not be masked');
+      let length = this.pending[1] & 127, offset = 2;
+      if (length === 126) { if (this.pending.length < 4) return; length = this.pending.readUInt16BE(2); offset = 4; }
+      if (length === 127) {
+        if (this.pending.length < 10) return;
+        const wide = this.pending.readBigUInt64BE(2);
+        if (wide > BigInt(MAX_FRAME)) throw new Error('gateway WS frame exceeds limit');
+        length = Number(wide); offset = 10;
+      }
+      if (length > MAX_FRAME) throw new Error('gateway WS frame exceeds limit');
+      if (this.pending.length < offset + length) return;
+      const payload = this.pending.subarray(offset, offset + length); this.pending = this.pending.subarray(offset + length);
+      if (opcode === 8) { this.closed = true; this.emit('ended'); return; }
+      if (opcode === 9) { this.socket.write(maskedFrame(10, payload)); continue; }
+      if (opcode === 10) continue;
+      if (opcode === 0) {
+        if (!this.fragment) throw new Error('unexpected WS continuation');
+        this.fragment.chunks.push(payload); this.fragment.bytes += length;
+        if (this.fragment.bytes > MAX_FRAME) throw new Error('fragmented WS message exceeds limit');
+        if (fin) { const fragment = this.fragment; this.fragment = null; this.message(fragment.opcode, Buffer.concat(fragment.chunks)); }
+      } else if (!fin) {
+        if (this.fragment || ![1, 2].includes(opcode)) throw new Error('invalid fragmented WS message');
+        this.fragment = { opcode, chunks: [payload], bytes: payload.length };
+      } else this.message(opcode, payload);
+    }
+  }
+  message(opcode, payload) {
+    if (opcode === 2) {
+      if (payload.length > 307200) throw new Error('JPEG exceeds 300 KiB');
+      if (payload.length < 4 || payload.readUInt16BE(0) !== 0xffd8 || payload.readUInt16BE(payload.length - 2) !== 0xffd9) throw new Error('gateway binary payload is not JPEG');
+      this.frames.push({ at: Date.now(), bytes: payload.length });
+      if (this.frames.length > 3000) this.frames.shift();
+      this.emit('frame'); return;
+    }
+    if (opcode !== 1) throw new Error('unsupported gateway WS opcode');
+    const value = JSON.parse(payload.toString('utf8'));
+    if (value.type === 'frame') return; // 不保留画面、base64 或帧正文。
+    if (['ready', 'control'].includes(value.type)) {
+      if (Number.isSafeInteger(value.controlEpoch)) this.controlEpoch = value.controlEpoch;
+      this.readOnly = value.readOnly; this.sessionId = value.sessionId || this.sessionId;
+    }
+    this.events.push({ sequence: ++this.sequence, value });
+    if (this.events.length > 256) this.events.shift();
+    this.emit('message');
+  }
+  send(value) { if (this.closed) throw this.failure || new Error('gateway WS is closed'); this.socket.write(maskedFrame(1, JSON.stringify(value))); }
+  next(predicate, { after = 0, timeoutMs = 12000 } = {}) {
+    return new Promise((resolve, reject) => {
+      let timer;
+      const finish = (error, value) => { clearTimeout(timer); this.off('message', inspect); this.off('ended', ended); error ? reject(error) : resolve(value); };
+      const inspect = () => {
+        const index = this.events.findIndex(event => event.sequence > after && predicate(event.value));
+        if (index >= 0) finish(null, this.events.splice(index, 1)[0].value);
+      };
+      const ended = () => finish(this.failure || new Error('gateway WS ended before response'));
+      timer = setTimeout(() => finish(new Error('gateway WS response timeout')), timeoutMs);
+      this.on('message', inspect); this.on('ended', ended); inspect();
+      if (this.closed) ended();
+    });
+  }
+  async request(value, predicate) {
+    const after = this.sequence; this.send(value);
+    const reply = await this.next(event => event.type === 'error' || predicate(event), { after });
+    if (reply.type === 'error') throw Object.assign(new Error(reply.message || reply.code), { code: reply.code, status: reply.status });
+    return reply;
+  }
+  async close() {
+    if (this.closed) return;
+    const done = new Promise(resolve => { const timer = setTimeout(() => { this.socket.destroy(); resolve(); }, 3000); this.socket.once('close', () => { clearTimeout(timer); resolve(); }); });
+    this.send({ type: 'close' }); this.socket.end(maskedFrame(8, Buffer.from([0x03, 0xe8])));
+    await done;
+  }
+}
+
+export async function openGatewayDesktop({ gatewayUrl, apiKey, agentId, botId, mode = 'control', taskId }) {
+  const gateway = new URL(gatewayUrl);
+  if (gateway.protocol !== 'https:' || gateway.username || gateway.password || gateway.search || gateway.hash || gateway.pathname !== '/') throw new Error('verification requires an HTTPS gateway origin');
+  const began = Date.now();
+  const issued = await fetch(new URL('IssuePersonalAssistantDesktopTicket', gateway), {
+    method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000),
+    headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ AgentId: agentId, BotId: botId, Mode: mode }),
+  });
+  const result = await issued.json();
+  if (!issued.ok || result.Code !== 0) throw Object.assign(new Error(`gateway ticket refused: HTTP ${issued.status}; ${String(result.Message || 'unknown').slice(0, 200)}`), { status: issued.status });
+  const data = result.Data;
+  // Server's public ticket contract is an integer Unix timestamp in seconds.
+  // Do not accept date strings or milliseconds: either can mask a bad fixture.
+  const expiresAt = Number.isSafeInteger(data?.ExpiresAt) ? data.ExpiresAt * 1000 : NaN;
+  if (!/^[A-Za-z0-9_-]{32,512}$/u.test(data?.Ticket || '') || data.WsPath !== 'personal-assistant/desktop/ws' || data.AgentId !== agentId || data.BotId !== botId
+    || !Number.isFinite(expiresAt) || expiresAt <= Date.now() || expiresAt - Date.now() > 60000) throw new Error('gateway ticket binding is invalid');
+  const url = new URL(data.WsPath, gateway), key = randomBytes(16).toString('base64');
+  const expected = createHash('sha1').update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest('base64');
+  const openedAt = Date.now();
+  const client = await new Promise((resolve, reject) => {
+    const request = https.request(url, { headers: { connection: 'Upgrade', upgrade: 'websocket', 'sec-websocket-version': '13', 'sec-websocket-key': key,
+      'sec-websocket-protocol': `${PROTOCOL}, agentkit.desktop.ticket.${data.Ticket}` }, timeout: 10000 });
+    request.on('upgrade', (response, socket, head) => {
+      if (response.headers['sec-websocket-accept'] !== expected || response.headers['sec-websocket-protocol'] !== PROTOCOL) { socket.destroy(); reject(new Error('gateway WS handshake identity is invalid')); return; }
+      const value = new GatewayDesktopClient(socket, { openedAt });
+      if (head.length) value.parse(head);
+      resolve(value);
+    });
+    request.on('response', response => { response.resume(); reject(Object.assign(new Error(`gateway WS upgrade refused: HTTP ${response.statusCode}`), { status: response.statusCode })); });
+    request.on('timeout', () => request.destroy(new Error('gateway WS upgrade timeout')));
+    request.on('error', reject); request.end();
+  });
+  client.ticketMs = openedAt - began; client.handshakeMs = Date.now() - openedAt;
+  const ready = await client.request({ type: 'open', botId, taskId, mode: mode === 'read' ? 'read' : 'observe' }, value => value.type === 'ready');
+  return { client, ready };
+}