@zerozhang-giza/kdl-agent 0.1.0-beta.1

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@zerozhang-giza/kdl-agent",
+  "version": "0.1.0-beta.1",
+  "description": "快代理 CLI：账户与订单查询、授权操作及代理便利命令",
+  "license": "MIT",
+  "engines": { "node": ">=22.14.0" },
+  "bin": { "kdl-agent": "scripts/run.cjs" },
+  "repository": { "type": "git", "url": "git+https://github.com/gizaZerozhang/kdl-agent-cli.git" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "files": ["scripts/runtime", "scripts/run.cjs", "scripts/install.cjs", "scripts/wizard.cjs", "scripts/verify-package.cjs", "SHA256SUMS", "release.json", "CHANGELOG.md", "THIRD_PARTY_NOTICES.txt"],
+  "scripts": {
+    "postinstall": "node scripts/install.cjs",
+    "prepack": "node scripts/verify-package.cjs",
+    "test": "node --test tests/*.test.cjs",
+    "release:prepare": "node scripts/prepare-package.cjs"
+  },
+  "dependencies": { "https-proxy-agent": "7.0.6", "tar": "7.5.22", "yauzl": "3.4.0" },
+  "devDependencies": { "yazl": "3.3.1" },
+  "kdl": { "command": "kdl-agent", "skill": "kdl-agent", "skillsPackage": "skills@1.5.25" }
+}

package/release.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.1.0-beta.1",
+  "repository": "gizaZerozhang/kdl-agent-cli",
+  "commit": "a50bc08164a9ab11a8f9d8b5435eb3553fcdeed8",
+  "dirty": false,
+  "macosSigned": false,
+  "sha256": "856588de2e6e97c166f8c0a1573a1ef97c747db9df132e3f9ee5c3a95e1061e9"
+}

package/scripts/install.cjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+// npx 安装向导先执行预检；真正调用业务命令时仍会校验并补装原生程序。
+if (process.env.npm_command !== 'exec') {
+  require('./runtime/install.cjs').ensureInstalled().catch(error => {
+    console.error(`安装失败：${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/run.cjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+const { spawn } = require('node:child_process');
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === 'install') return require('./wizard.cjs').main(args.slice(1));
+  const binary = await require('./runtime/install.cjs').ensureInstalled();
+  const child = spawn(binary, args, { stdio: 'inherit' });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
+  child.on('error', error => { console.error(`运行失败：${error.message}`); process.exitCode = 1; });
+  child.on('exit', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 1); });
+}
+main().catch(error => { console.error(`运行失败：${error.message}`); process.exitCode = 1; });

package/scripts/runtime/install.cjs

@@ -0,0 +1,192 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const crypto = require('node:crypto');
+const { pipeline } = require('node:stream/promises');
+const { Transform } = require('node:stream');
+const { spawnSync } = require('node:child_process');
+const { HttpsProxyAgent } = require('https-proxy-agent');
+const tar = require('tar');
+const yauzl = require('yauzl');
+
+const ROOT = path.resolve(__dirname, '../..');
+const MAX_BYTES = 256 * 1024 * 1024;
+const HOSTS = new Set(['github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com']);
+const TARGETS = new Set(['darwin-arm64', 'darwin-amd64', 'linux-arm64', 'linux-amd64', 'windows-amd64']);
+
+function config(root = ROOT) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (!/^\d+\.\d+\.\d+(?:-beta\.\d+)?$/.test(pkg.version)) throw new Error('不支持的发行版本');
+  const url = new URL(pkg.repository.url.replace(/^git\+/, '').replace(/\.git$/, ''));
+  if (url.origin !== 'https://github.com' || !/^\/[\w-]+\/[\w.-]+$/.test(url.pathname)) throw new Error('无效源码仓库地址');
+  return { pkg, repository: url.pathname.slice(1), root };
+}
+
+function target(version, platform = process.platform, arch = process.arch) {
+  const system = platform === 'win32' ? 'windows' : platform;
+  const cpu = arch === 'x64' ? 'amd64' : arch;
+  if (!TARGETS.has(`${system}-${cpu}`)) throw new Error(`不支持的平台：${platform}/${arch}`);
+  const ext = system === 'windows' ? 'zip' : 'tar.gz';
+  return { name: `kdl-agent_${version}_${system}_${cpu}.${ext}`, binary: system === 'windows' ? 'kdl-agent.exe' : 'kdl-agent' };
+}
+
+function checksums(text) {
+  const values = new Map();
+  for (const line of text.trim().split(/\r?\n/)) {
+    const match = /^([a-f0-9]{64})  ([A-Za-z0-9_.-]+)$/.exec(line);
+    if (!match || values.has(match[2])) throw new Error('校验清单格式错误或文件重复');
+    values.set(match[2], match[1]);
+  }
+  return values;
+}
+
+function allowedURL(raw) {
+  const url = new URL(raw);
+  if (url.protocol !== 'https:' || url.username || url.password || (url.port && url.port !== '443') || !HOSTS.has(url.hostname)) {
+    throw new Error('下载地址不属于允许的 GitHub HTTPS 资源');
+  }
+  return url;
+}
+
+async function download(raw, destination, redirects = 0) {
+  const url = allowedURL(raw);
+  if (redirects > 5) throw new Error('下载重定向次数过多');
+  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+  const response = await new Promise((resolve, reject) => {
+    const request = https.get(url, { agent: proxy ? new HttpsProxyAgent(proxy) : undefined, headers: { 'User-Agent': 'kdl-agent-installer' } }, resolve);
+    request.setTimeout(60000, () => request.destroy(new Error('下载超时，请检查网络或 HTTPS_PROXY')));
+    request.on('error', reject);
+  });
+  if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+    response.resume();
+    if (!response.headers.location) throw new Error('下载重定向缺少地址');
+    return download(new URL(response.headers.location, url).href, destination, redirects + 1);
+  }
+  if (response.statusCode !== 200) {
+    response.resume();
+    throw new Error(`下载失败 HTTP ${response.statusCode}；请核对版本及 Release 是否公开`);
+  }
+  let size = 0;
+  const limit = new Transform({ transform(chunk, encoding, callback) {
+    size += chunk.length;
+    callback(size > MAX_BYTES ? new Error('发行包超过大小限制') : null, chunk);
+  } });
+  await pipeline(response, limit, fs.createWriteStream(destination, { flags: 'wx', mode: 0o600 }));
+}
+
+async function hashFile(file) {
+  const hash = crypto.createHash('sha256');
+  for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+function safeEntry(name) {
+  if (!name || name.includes('\\') || name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.split('/').includes('..')) throw new Error('归档包含非法路径');
+}
+
+async function extractBinary(archive, binary, destination) {
+  let found = false;
+  async function save(stream, name, size) {
+    if (name !== binary) { stream.resume(); return; }
+    if (found || size > MAX_BYTES) throw new Error('归档可执行文件重复或过大');
+    found = true;
+    await pipeline(stream, fs.createWriteStream(destination, { flags: 'wx', mode: 0o755 }));
+  }
+  if (archive.endsWith('.zip')) {
+    await new Promise((resolve, reject) => yauzl.open(archive, { lazyEntries: true }, (error, zip) => {
+      if (error) return reject(error);
+      const fail = err => { zip.close(); reject(err); };
+      zip.on('error', fail);
+      zip.on('end', resolve);
+      zip.on('entry', entry => {
+        try {
+          safeEntry(entry.fileName);
+          const mode = entry.externalFileAttributes >>> 16;
+          if ((mode & 0o170000) === 0o120000) throw new Error('归档不允许符号链接');
+          if (entry.fileName !== binary) return zip.readEntry();
+          zip.openReadStream(entry, (err, stream) => {
+            if (err) return fail(err);
+            save(stream, entry.fileName, entry.uncompressedSize).then(() => zip.readEntry(), fail);
+          });
+        } catch (err) { fail(err); }
+      });
+      zip.readEntry();
+    }));
+  } else {
+    const pending = [];
+    let invalid;
+    await tar.t({ file: archive, strict: true, onReadEntry(entry) {
+      try {
+        safeEntry(entry.path);
+        if (!['File', 'Directory', 'ExtendedHeader', 'GlobalExtendedHeader'].includes(entry.type)) throw new Error('归档不允许链接或特殊文件');
+        const task = save(entry, entry.path, entry.size);
+        task.catch(() => {});
+        pending.push(task);
+      } catch (err) { invalid = err; entry.resume(); }
+    } });
+    await Promise.all(pending);
+    if (invalid) throw invalid;
+  }
+  if (!found) throw new Error('归档缺少可执行文件');
+  fs.chmodSync(destination, 0o755);
+}
+
+function regular(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('程序路径不是普通文件');
+}
+
+function verifyBinary(file, version, commit) {
+  regular(file);
+  const result = spawnSync(file, ['--version'], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const output = result.stdout?.trim();
+  if (result.status !== 0 || !output?.startsWith(`kdl-agent ${version} (commit `) || (commit && output !== `kdl-agent ${version} (commit ${commit})`)) throw new Error('下载程序无法运行或版本、来源不匹配');
+}
+
+async function ensureInstalled({ root = ROOT, fetchFile = download, platform = process.platform, arch = process.arch, verify = verifyBinary } = {}) {
+  const { pkg, repository } = config(root);
+  const release = JSON.parse(fs.readFileSync(path.join(root, 'release.json'), 'utf8'));
+  if (release.version !== pkg.version || release.repository !== repository || !/^[a-f0-9]{40}$/.test(release.commit) || release.dirty !== false) throw new Error('发行元数据与 npm 包不一致');
+  const artifact = target(pkg.version, platform, arch);
+  const expected = checksums(fs.readFileSync(path.join(root, 'SHA256SUMS'), 'utf8')).get(artifact.name);
+  if (!expected) throw new Error('npm 包缺少对应平台的校验值，请重新安装完整发行包');
+  const directory = path.join(root, '.native');
+  fs.mkdirSync(directory, { recursive: true });
+  if (fs.lstatSync(directory).isSymbolicLink()) throw new Error('安装目录不能是符号链接');
+  const lock = path.join(directory, '.lock');
+  try { fs.mkdirSync(lock); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('另一个安装正在进行；确认没有安装进程后可删除 .native/.lock 重试');
+    throw error;
+  }
+  const destination = path.join(directory, artifact.binary);
+  const old = destination + '.old';
+  let temporary;
+  try {
+    if (fs.existsSync(old) && !fs.existsSync(destination)) { regular(old); fs.renameSync(old, destination); }
+    if (fs.existsSync(destination)) {
+      try { verify(destination, pkg.version, release.commit); return destination; } catch { regular(destination); }
+    }
+    temporary = fs.mkdtempSync(path.join(directory, '.download-'));
+    const archive = path.join(temporary, artifact.name);
+    const extracted = path.join(temporary, artifact.binary);
+    await fetchFile(`https://github.com/${repository}/releases/download/v${pkg.version}/${artifact.name}`, archive);
+    if (await hashFile(archive) !== expected) throw new Error('SHA256 校验失败，未替换现有程序');
+    await extractBinary(archive, artifact.binary, extracted);
+    verify(extracted, pkg.version, release.commit);
+    if (fs.existsSync(old)) { regular(old); fs.unlinkSync(old); }
+    const hadOld = fs.existsSync(destination);
+    if (hadOld) fs.renameSync(destination, old);
+    try { fs.renameSync(extracted, destination); } catch (error) {
+      if (hadOld) fs.renameSync(old, destination);
+      throw error;
+    }
+    if (hadOld) fs.unlinkSync(old);
+    return destination;
+  } finally {
+    if (temporary) fs.rmSync(temporary, { recursive: true, force: true });
+    fs.rmdirSync(lock);
+  }
+}
+
+module.exports = { ROOT, TARGETS, config, target, checksums, allowedURL, download, hashFile, extractBinary, ensureInstalled, verifyBinary };

package/scripts/verify-package.cjs

@@ -0,0 +1,24 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { config, checksums, TARGETS, target } = require('./runtime/install.cjs');
+function verify(root = path.resolve(__dirname, '..')) {
+  const { pkg, repository } = config(root);
+  if (pkg.name.includes('pending') || !/^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(pkg.name)) throw new Error('请先绑定实际个人 npm 包名');
+  const release = JSON.parse(fs.readFileSync(path.join(root, 'release.json'), 'utf8'));
+  if (release.version !== pkg.version || release.repository !== repository || !/^[a-f0-9]{40}$/.test(release.commit) || release.dirty !== false) throw new Error('发行来源、版本或仓库不一致');
+  if (!pkg.version.includes('-beta.') && !release.macosSigned) throw new Error('稳定发行缺少 macOS 签名公证记录');
+  const sums = checksums(fs.readFileSync(path.join(root, 'SHA256SUMS'), 'utf8'));
+  for (const item of TARGETS) {
+    const [platform, arch] = item.split('-');
+    if (!sums.has(target(pkg.version, platform, arch).name)) throw new Error(`缺少平台校验：${item}`);
+  }
+  for (const file of ['kdl-agent-skill.zip', 'openapi.yaml', 'BUILD.json', 'install.md', 'cli-guide.md', 'api-guide.md', 'release-notes.md']) if (!sums.has(file)) throw new Error(`缺少配套资料校验：${file}`);
+  if (release.sha256 !== require('node:crypto').createHash('sha256').update(fs.readFileSync(path.join(root, 'SHA256SUMS'))).digest('hex')) throw new Error('校验清单与发行记录不一致');
+  return release;
+}
+if (require.main === module) {
+  try { const release = verify(); console.log(`发行检查通过：${release.version} (${release.commit})`); }
+  catch (error) { console.error(`发行检查失败：${error.message}`); process.exitCode = 1; }
+}
+module.exports = { verify };

package/scripts/wizard.cjs

@@ -0,0 +1,97 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const readline = require('node:readline/promises');
+const { config, ensureInstalled, verifyBinary } = require('./runtime/install.cjs');
+
+function command(name, args, options = {}) {
+  // npm/npx 在 Windows 是 .cmd；只传入配置中校验过的标识和固定参数。
+  if (process.platform === 'win32' && ['npm', 'npx'].includes(name)) {
+    if (args.some(arg => /[&|<>^%!"\r\n]/.test(arg))) throw new Error('命令参数包含 Windows shell 特殊字符');
+    return spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `${name}.cmd ${args.map(arg => `"${arg}"`).join(' ')}`], { encoding: 'utf8', ...options });
+  }
+  return spawnSync(name, args, { encoding: 'utf8', ...options });
+}
+
+function parse(args) {
+  const options = { yes: false, noLogin: false, noSkills: false, agents: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--no-login') options.noLogin = true;
+    else if (arg === '--no-skills') options.noSkills = true;
+    else if (arg === '--agent') {
+      const name = args[++i];
+      if (!name || !/^[a-z0-9-]+$/.test(name)) throw new Error('--agent 需要目标工具标识');
+      options.agents.push(name);
+    } else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`未知安装参数：${arg}`);
+  }
+  return options;
+}
+
+async function main(args, { run = command, install = ensureInstalled, readConfig = config, checkBinary = verifyBinary, tty = process.stdin.isTTY } = {}) {
+  const options = parse(args);
+  if (options.help) {
+    console.log('安装快代理 CLI 与同版本 Skill\n\n用法：npx <包名>@<版本> install [--yes] [--agent codex] [--no-login] [--no-skills]\n\n--yes 非交互安装；安装 Skill 时须指定 --agent\n--no-login 仅安装，稍后在本地终端执行 kdl-agent auth login\n--no-skills 跳过 Skill，适用于直接使用 CLI\n升级或回退：使用目标版本再次运行；卸载 npm 包保留 .kdl 与 Skill。');
+    return;
+  }
+  if (!tty && !options.yes) throw new Error('非交互环境需 --yes；Agent 请同时使用 --no-login，敏感凭证由用户在本地终端输入');
+  if (options.yes && !options.noSkills && !options.agents.length) throw new Error('非交互 Skill 安装须通过 --agent 指定目标工具，或显式 --no-skills');
+  const { pkg, repository } = readConfig();
+  if (!/^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(pkg.name)) throw new Error('npm 包名尚未绑定');
+  console.log(`目标版本：${pkg.name}@${pkg.version}`);
+  console.log('正在下载并校验原生程序...');
+  await install();
+  const prefixResult = run('npm', ['prefix', '-g'], { timeout: 15000 });
+  if (prefixResult.status !== 0) throw new Error('无法读取 npm 全局目录，请检查 Node.js/npm');
+  const prefix = prefixResult.stdout.trim();
+  const modules = process.platform === 'win32' ? path.join(prefix, 'node_modules') : path.join(prefix, 'lib/node_modules');
+  const installedRoot = path.join(modules, ...pkg.name.split('/'));
+  let previous;
+  try { previous = JSON.parse(fs.readFileSync(path.join(installedRoot, 'package.json'), 'utf8')).version; } catch {}
+  const binary = path.join(installedRoot, '.native', process.platform === 'win32' ? 'kdl-agent.exe' : 'kdl-agent');
+  let current = false;
+  if (previous === pkg.version) { try { checkBinary(binary, pkg.version); current = true; } catch {} }
+  if (!current) {
+    const result = run('npm', ['install', '-g', `${pkg.name}@${pkg.version}`, '--registry=https://registry.npmjs.org/'], { stdio: 'inherit', timeout: 180000 });
+    if (result.status !== 0) {
+      if (previous && /^\d+\.\d+\.\d+(?:-beta\.\d+)?$/.test(previous)) {
+        console.error(`正在尝试恢复原版本 ${previous}...`);
+        const restore = run('npm', ['install', '-g', `${pkg.name}@${previous}`, '--registry=https://registry.npmjs.org/'], { stdio: 'inherit', timeout: 180000 });
+        console.error(restore.status === 0 ? '已恢复原 npm 版本' : `恢复未完成，请执行 npm install -g ${pkg.name}@${previous}`);
+      }
+      throw new Error('全局安装失败；请检查网络和 npm 全局目录权限，不要使用 sudo 自动提权');
+    }
+  }
+  await install({ root: installedRoot });
+  console.log(`CLI：已安装 ${pkg.version}\n程序：${binary}\n命令目录：${process.platform === 'win32' ? prefix : path.join(prefix, 'bin')}（须位于 PATH）`);
+  if (!options.noSkills) {
+    const source = `https://github.com/${repository}/tree/v${pkg.version}/skills/${pkg.kdl.skill}`;
+    const skillArgs = ['--yes', pkg.kdl.skillsPackage, 'add', source, '--global', '--skill', pkg.kdl.skill];
+    if (options.yes) skillArgs.push('--yes');
+    for (const agent of options.agents) skillArgs.push('--agent', agent);
+    const result = run('npx', skillArgs, { stdio: 'inherit', timeout: 180000 });
+    if (result.status !== 0) throw new Error('CLI 已安装，Skill 安装未完成；重新运行此向导重试，已安装 CLI 将跳过');
+    console.log('Skill：已安装；目标 Agent 可能需要刷新会话');
+  } else console.log('Skill：按要求跳过');
+  if (options.noLogin) { console.log('登录：按要求跳过；用户稍后在本地终端执行 kdl-agent auth login 和 kdl-agent auth status'); return; }
+  let status = run(binary, ['auth', 'status', '--format', 'json'], { timeout: 25000 });
+  if (status.status !== 0) {
+    if (!tty) throw new Error('CLI/Skill 已安装，登录待用户在本地终端完成：kdl-agent auth login');
+    console.log('凭证管理：https://www.kuaidaili.com/uc/agent/settings/\n请仅在本地终端输入凭证，不发送给 Agent。');
+    const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let answer;
+    try { answer = await prompt.question('现在隐藏输入并验证登录？[y/N] '); } finally { prompt.close(); }
+    if (!/^y(es)?$/i.test(answer.trim())) throw new Error('安装已完成，登录待完成；稍后执行 kdl-agent auth login');
+    const login = run(binary, ['auth', 'login'], { stdio: 'inherit' });
+    if (login.status !== 0) throw new Error('登录未完成；安装结果保留，请检查凭证或 Gateway 后重试');
+    status = run(binary, ['auth', 'status', '--format', 'json'], { timeout: 25000 });
+  }
+  if (status.status !== 0) throw new Error('远端状态未通过验证；请执行 kdl-agent auth status 排查');
+  const query = run(binary, ['account', 'summary', '--format', 'json'], { timeout: 25000 });
+  if (query.status !== 0) throw new Error('状态有效，首次查询失败；请执行 kdl-agent account summary 排查');
+  console.log('登录：远端验证有效\n首次只读查询：通过（账户数据未输出到安装日志）');
+}
+module.exports = { main, parse, command };