@whyshu/argent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @whyshu/argent（启动器）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一条命令启动**打包好的 dsh + Argent 插件/角色预设**，并管理本机 runner 常驻：
+
+```bash
+npx -y @whyshu/argent login --server-url https://whyshu.com --phone <手机号>   # 首跑登录（短信验证码，写 600 auth.json）
+npx -y @whyshu/argent pair --from-login --tenant ly-0001                     # 用登录态签发 runner token（写 600 runner.json）
+npx -y @whyshu/argent web        # 生成/复用 profile 并启动 dsh web（默认 http://127.0.0.1:3080）
+npx -y @whyshu/argent health     # 版本/宿主/profile/端口/runner 配置自检
+npx -y @whyshu/argent setup      # 只生成/更新 $DSH_HOME/profiles/argent，不启动
+npx -y @whyshu/argent service install   # 生成 launchd（macOS）/ systemd（Linux）常驻 P4 runner
+```
+
+- 启动器 **exact pin** `@deepseek-ai/dsh@0.2.1-rc.2`，避免混合版本事故；
+- profile 由启动器生成：bundles（base/web-app/argent-presets，可用 `--bundles a,b` 追加）+ 用户层 patch（默认角色 preset）；
+- `setup` 会自动执行 `dsh plugin --profile argent install` 装配依赖（`--no-install` 可跳过）；
+- 两种装配模式：本地仓库（`ARGENT_REPO`/`--repo`，插件用 `file:`）与**发布模式**（无本地 plugins/ 时用启动器 package.json 的 npm 版本）；
+- 首跑写入 `$DSH_HOME/argent/runner.json`（600，含 serverUrl/tenantAppId/runnerToken）；
+- ⛔ 凭据不进包、不进日志；发布与客户机重装由交付方执行。
+
+本地仓库联调：`ARGENT_REPO=/path/to/argent-dsh node launcher/bin/argent.mjs setup --dsh-home /tmp/x`
+（从仓库 `plugins/` 用 `file:` 装配；正式发布时改用 npm 依赖解析）。

package/bin/argent.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * @whyshu/argent CLI
+ *
+ *   argent web                       生成/复用 profile 并启动 dsh web
+ *   argent health                    版本/宿主/profile/runner 自检（--json）
+ *   argent setup                     只生成/更新 profile
+ *   argent service install|uninstall runner 常驻（macOS launchd；--print-only/--plist-dir）
+ *
+ * 公共参数：--dsh-home <dir>  --profile <name>  --repo <dir>  --json  --dry-run
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  DSH_EXACT_VERSION, PROFILE_NAME, PROD_BUNDLES, buildLaunchdPlist, buildProfile, dshHomeOf,
+  depsInstalled, health, installDeps, loginWithPhone, pairRunner, probeDshVersion, readAuthToken, repoRoot, runnerConfigPath, sendLoginCode, versionMatches,
+} from '../lib/index.mjs';
+
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const val = (f, d = '') => { const i = argv.indexOf(f); return i > -1 ? (argv[i + 1] ?? d) : d; };
+const JSON_OUT = has('--json');
+const DRY_RUN = has('--dry-run');
+
+const command = (() => {
+  const positional = argv.filter((a) => !a.startsWith('--') && !['-h'].includes(a));
+  const i = argv.findIndex((a) => a === 'web' || a === 'health' || a === 'setup' || a === 'pair' || a === 'login' || a === 'service');
+  if (i < 0) return '';
+  if (argv[i] === 'service') return `service ${argv[i + 1] || ''}`.trim();
+  return argv[i];
+})();
+
+const opts = {
+  dshHome: dshHomeOf(val('--dsh-home')),
+  profile: val('--profile', PROFILE_NAME),
+  repo: repoRoot({ repo: val('--repo') }),
+  port: Number(val('--port', '3080')) || 3080,
+  extraBundles: (() => { const raw = val('--bundles', '').split(',').map((x) => x.trim()).filter(Boolean); return raw.flatMap((x) => (x === 'prod' ? PROD_BUNDLES : [x])); })(),
+};
+
+function print(obj) {
+  if (JSON_OUT) console.log(JSON.stringify(obj, null, 2));
+  else for (const [k, v] of Object.entries(obj)) console.log(`${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+}
+
+function ensureProfile({ install = true } = {}) {
+  const built = buildProfile({ dshHome: opts.dshHome, profile: opts.profile, repo: opts.repo, extraBundles: opts.extraBundles });
+  if (!built.ok) {
+    console.error(`❌ ${built.message}`);
+    process.exit(2);
+  }
+  if (install && !depsInstalled(opts.dshHome, opts.profile) && !has('--no-install')) {
+    console.error('→ 装配 profile 依赖（dsh plugin --profile ' + opts.profile + ' install）…');
+    const r = installDeps({ dshHome: opts.dshHome, profile: opts.profile });
+    if (!r.ok) {
+      console.error(`❌ profile 依赖装配失败：${r.message}`);
+      console.error('   可手动重试：DSH_HOME=' + opts.dshHome + ' dsh plugin --profile ' + opts.profile + ' install');
+      process.exit(2);
+    }
+    console.error('✅ profile 依赖装配完成');
+  }
+  return built;
+}
+
+function checkVersionOrExit() {
+  const probe = probeDshVersion();
+  if (!probe.ok) {
+    console.error(`❌ 未找到 dsh（${probe.error}）。安装器不代装宿主：请先按官方方式准备 dsh@${DSH_EXACT_VERSION}（npx @deepseek-ai/dsh@${DSH_EXACT_VERSION} web）。`);
+    process.exit(2);
+  }
+  if (!versionMatches(probe.version)) {
+    console.error(`❌ dsh 版本不匹配：当前 ${probe.version}，要求 exact ${DSH_EXACT_VERSION}。`);
+    console.error('   启动器按 exact pin 运行（防混合版本事故）；请切换 dsh 版本后重试。');
+    process.exit(2);
+  }
+  return probe.version;
+}
+
+function launchWeb() {
+  const built = ensureProfile();
+  const version = checkVersionOrExit();
+  const args = ['--profile', opts.profile, ...(opts.port !== 3080 ? ['--port', String(opts.port)] : [])];
+  if (DRY_RUN) {
+    print({ ok: true, dryRun: true, dshVersion: version, profile: built.dir, command: `dsh ${args.join(' ')}` });
+    return;
+  }
+  const child = spawn('dsh', args, { stdio: 'inherit', env: process.env });
+  child.on('close', (code) => process.exit(code ?? 0));
+  child.on('error', (error) => { console.error(`❌ 启动 dsh 失败：${error.message}`); process.exit(1); });
+}
+
+async function webCommand() {
+  if (DRY_RUN || JSON_OUT) {
+    const built = ensureProfile();
+    const probe = probeDshVersion();
+    print({
+      ok: probe.ok && versionMatches(probe.version),
+      dshVersion: probe.ok ? probe.version : '', expected: DSH_EXACT_VERSION,
+      profile: built.dir, command: 'dsh --profile ' + opts.profile + (opts.port !== 3080 ? ' --port ' + opts.port : ''),
+      note: probe.ok && versionMatches(probe.version) ? '版本匹配，可启动' : '版本不匹配/未安装 dsh',
+    });
+    return;
+  }
+  launchWeb();
+}
+
+async function healthCommand() {
+  const h = health({ dshHome: opts.dshHome, profile: opts.profile, repo: opts.repo, port: opts.port });
+  if (JSON_OUT) console.log(JSON.stringify(h, null, 2));
+  else {
+    console.log(`dsh: ${h.dsh.ok ? h.dsh.version : '(未找到)'} ${h.dsh.matchesExact ? '✅ exact' : `❌ 期望 ${h.expectedDsh}`}`);
+    console.log(`profile: ${h.profile.dir} ${h.profile.packageJson && h.profile.patch ? '✅' : '❌ 未生成（跑 argent setup）'}`);
+    console.log(`runner 配置: ${h.runner.configPresent ? `✅ ${h.runner.configPath}（${h.runner.mode}）` : `— 未配置（${h.runner.configPath}）`}`);
+    console.log(`web: ${h.webUrl}`);
+    console.log(h.ok ? '✅ 可启动' : '❌ 有前置未满足');
+  }
+  process.exit(h.ok ? 0 : 1);
+}
+
+async function readLine(promptText) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(promptText)).trim(); } finally { rl.close(); }
+}
+
+async function loginCommand() {
+  const serverUrl = val('--server-url');
+  const phone = val('--phone');
+  if (!serverUrl || !phone) { console.error('用法：argent login --server-url <url> --phone <手机号> [--code <验证码>]'); process.exit(2); }
+  let code = val('--code');
+  if (!code) {
+    const sent = await sendLoginCode({ serverUrl, phone });
+    if (!sent.ok) { console.error(`❌ 发送验证码失败：${sent.message}`); process.exit(2); }
+    if (sent.devCode) console.error(`（开发环境验证码：${sent.devCode}）`);
+    code = await readLine('请输入短信验证码：');
+  }
+  const r = await loginWithPhone({ serverUrl, phone, code, dshHome: opts.dshHome });
+  if (!r.ok) { console.error(`❌ 登录失败：${r.message}`); process.exit(2); }
+  print({ ok: true, auth: r.path, serverUrl: r.serverUrl, phone: r.phone, tokenTail: `…${r.tokenTail}`, next: '运行 argent pair --from-login --tenant <appId>' });
+}
+
+async function pairCommand() {
+  const r = await pairRunner({
+    serverUrl: val('--server-url'),
+    tenantAppId: val('--tenant') || val('--tenant-app-id'),
+    adminToken: val('--admin-token') || (has('--from-login') ? (readAuthToken(opts.dshHome)?.token || '') : ''),
+    runnerToken: val('--runner-token'),
+    runnerId: val('--runner-id'),
+    label: val('--label', 'argent-launcher'),
+    dshHome: opts.dshHome,
+  });
+  if (!r.ok) { console.error(`❌ ${r.message}`); process.exit(2); }
+  print({ ok: true, config: r.configPath, serverUrl: r.serverUrl, tenantAppId: r.tenantAppId, runnerId: r.runnerId, tokenTail: `…${r.tokenTail}` });
+}
+
+function setupCommand() {
+  const built = ensureProfile();
+  print({ ok: true, profile: built.dir, bundles: built.bundles.join(', '), plugins: built.plugins.join(', '), preset: built.preset, depsInstalled: depsInstalled(opts.dshHome, opts.profile) });
+}
+
+function serviceCommand(sub) {
+  const plist = buildLaunchdPlist({ dshHome: opts.dshHome, repo: opts.repo });
+  const outDir = val('--plist-dir', '');
+  const targetDir = outDir || join(homedir(), 'Library', 'LaunchAgents');
+  const target = join(targetDir, plist.file);
+  if (sub === 'uninstall') {
+    if (existsSync(target)) { rmSync(target); print({ ok: true, removed: target }); } else print({ ok: true, removed: '', note: '未安装' });
+    return;
+  }
+  if (sub !== 'install') { console.error('用法：argent service install|uninstall [--print-only|--plist-dir <dir>]'); process.exit(2); }
+  if (!plist.script) {
+    console.error('❌ 找不到 scripts/argent-runner.mjs（发布包应内置 runner；本地联调请给 --repo）');
+    process.exit(2);
+  }
+  if (has('--print-only')) { console.log(plist.content); return; }
+  mkdirSync(targetDir, { recursive: true });
+  writeFileSync(target, plist.content);
+  print({
+    ok: true, plist: target, label: plist.label,
+    next: [
+      `launchctl unload ${target} 2>/dev/null || true`,
+      `launchctl load -w ${target}`,
+      `# 日志：${join(opts.dshHome, 'argent', 'runner', 'logs')}`,
+    ].join('\n'),
+    runnerConfig: runnerConfigPath(opts.dshHome),
+  });
+}
+
+const main = async () => {
+  if (!command || has('-h') || has('--help')) {
+    console.log('用法：argent <web|health|setup|login|pair|service install|service uninstall> [--dsh-home <dir>] [--json] [--dry-run]');
+    process.exit(command ? 0 : 2);
+  }
+  if (command === 'health') return healthCommand();
+  if (command === 'setup') return setupCommand();
+  if (command === 'pair') return pairCommand();
+  if (command === 'login') return loginCommand();
+  if (command === 'service install' || command === 'service uninstall') return serviceCommand(command.split(' ')[1]);
+  return webCommand();
+};
+
+main().catch((error) => { console.error(`❌ ${error.message}`); process.exit(1); });

package/lib/index.mjs

@@ -0,0 +1,274 @@
+/**
+ * @whyshu/argent 启动器内核（纯函数，便于单测；bin 只做 CLI 编排）。
+ *
+ * 职责：
+ *   · exact pin 的 dsh 版本（0.2.1-rc.2）——启动前校验，避免混合版本事故；
+ *   · 生成/更新 $DSH_HOME/profiles/argent（bundles + 用户层 patch）——本地仓库用 file: 装配；
+ *   · runner 配置路径与 launchd/systemd 常驻单元生成；
+ *   · 状态自检（版本/profile/runner 配置/端口）。
+ * ⛔ 不读写任何凭据内容（runner.json 由首跑引导写，权限 600）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir, hostname as osHostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DSH_EXACT_VERSION = '0.2.1-rc.2';
+export const PROFILE_NAME = 'argent';
+export const BASE_BUNDLES = [
+  '@deepseek-ai/dsh-base',
+  '@deepseek-ai/dsh-web-app',
+  '@whyshu/argent-presets',
+];
+export const DEFAULT_PRESET = 'argent-general';
+/** 生产 profile 追加 bundles（--bundles prod 展开；版本见启动器 package.json 依赖） */
+export const PROD_BUNDLES = [
+  '@whyshu/argent-core', '@whyshu/argent-dsh', '@whyshu/argent-skin',
+  '@whyshu/argent-gateway', '@whyshu/argent-flow', '@whyshu/argent-ml',
+  '@michengai/dsh-im-connect', '@linxin666/dsh-client-ui-task-board',
+];
+export const RUNNER_LABEL = 'com.whyshu.argent-runner';
+
+/** 仓库根：launcher/lib → ../../（本地联调）；发布包内由 ARGENT_REPO 覆盖 */
+export function repoRoot({ repo } = {}) {
+  if (repo) return resolve(repo);
+  if (process.env.ARGENT_REPO) return resolve(process.env.ARGENT_REPO);
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+export function dshHomeOf(value) {
+  return resolve(value || process.env.DSH_HOME || join(homedir(), '.dsh'));
+}
+
+/** 解析 `dsh --version` 输出（只取第一行，去掉 v 前缀） */
+export function parseVersion(text) {
+  const line = String(text || '').trim().split('\n')[0] || '';
+  return line.replace(/^v/, '').trim();
+}
+
+export function versionMatches(version, expected = DSH_EXACT_VERSION) {
+  return parseVersion(version) === parseVersion(expected);
+}
+
+/** 跑 `dsh --version`（可注入 bin；默认 PATH 上的 dsh） */
+export function probeDshVersion({ dshBin = 'dsh', spawn = spawnSync } = {}) {
+  const r = spawn(dshBin, ['--version'], { encoding: 'utf8', timeout: 15000 });
+  if (r.error || r.status !== 0) return { ok: false, version: '', error: r.error?.message || `exit ${r.status}` };
+  return { ok: true, version: parseVersion(r.stdout), error: '' };
+}
+
+/** 仓库内插件目录（本地 file: 装配用；发布包改为其自身 node_modules） */
+export function pluginDirs({ repo = repoRoot() } = {}) {
+  const candidates = {
+    '@whyshu/argent-presets': join(repo, 'plugins', 'argent-presets'),
+  };
+  const out = {};
+  for (const [name, dir] of Object.entries(candidates)) {
+    if (existsSync(join(dir, 'package.json'))) out[name] = dir;
+  }
+  return out;
+}
+
+/** 启动器自身依赖里的版本（发布模式：本地没有 plugins/ 时改用 npm 依赖） */
+function launcherDependencyVersions() {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const deps = JSON.parse(readFileSync(pkgPath, 'utf8')).dependencies || {};
+    return deps;
+  } catch { return {}; }
+}
+
+export function profileDir(dshHome, profile = PROFILE_NAME) {
+  return join(dshHome, 'profiles', profile);
+}
+
+/** 生成/更新 profile（幂等）：package.json（file: 依赖 + bundles）+ cordis.patch.yml（用户层） */
+export function buildProfile({ dshHome = dshHomeOf(), profile = PROFILE_NAME, repo = repoRoot(), extraBundles = [] } = {}) {
+  const dir = profileDir(dshHome, profile);
+  mkdirSync(dir, { recursive: true });
+  const plugins = pluginDirs({ repo });
+  const npmVersions = launcherDependencyVersions();
+  const bundles = [...BASE_BUNDLES, ...(extraBundles || [])];
+  const deps = {};
+  const missing = [];
+  for (const name of bundles.filter((b) => !b.startsWith('@deepseek-ai/'))) {
+    if (plugins[name]) deps[name] = `file:${plugins[name]}`;
+    else if (npmVersions[name]) deps[name] = npmVersions[name];
+    else missing.push(name);
+  }
+  if (missing.length > 0) {
+    return { ok: false, code: 'plugins_missing', message: `找不到插件：${missing.join('、')}（本地无 plugins/ 且启动器 package.json 未声明依赖）`, dir };
+  }
+  // 非 @whyshu 的 bundle（dsh 官方）由宿主管，不进 profile dependencies
+  const pkg = {
+    name: `dsh-profile-${profile}`,
+    private: true,
+    dependencies: deps,
+    dsh: { profile: { bundles } },
+  };
+  writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+  const patch = [
+    '# @whyshu/argent 生成（幂等；手工改动会在此文件重生成时被覆盖）',
+    '- id: agent-preset-registry',
+    '  config:',
+    `    default: ${DEFAULT_PRESET}`,
+    '',
+  ].join('\n');
+  writeFileSync(join(dir, 'cordis.patch.yml'), patch);
+  // pnpm 配置必须与现有 web profile 同口径：否则 pnpm 会尝试从 registry 自动装 peer（含未发布版本）⇒ 安装失败
+  writeFileSync(join(dir, 'pnpm-workspace.yaml'), 'packages:\n  - .\nnodeLinker: hoisted\nautoInstallPeers: false\nallowBuilds:\n  protobufjs: true\n');
+  return { ok: true, dir, plugins: Object.keys(plugins), bundles: [...bundles], preset: DEFAULT_PRESET };
+}
+
+export function depsInstalled(dshHome = dshHomeOf(), profile = PROFILE_NAME) {
+  return existsSync(join(profileDir(dshHome, profile), 'node_modules'));
+}
+
+/** 装配 profile 依赖：`dsh plugin --profile <p> install`（pnpm 在 profile 目录内执行） */
+export function installDeps({ dshHome = dshHomeOf(), profile = PROFILE_NAME, dshBin = 'dsh', spawn = spawnSync } = {}) {
+  const r = spawn(dshBin, ['plugin', '--profile', profile, 'install'], {
+    cwd: profileDir(dshHome, profile), env: { ...process.env, DSH_HOME: dshHome }, encoding: 'utf8', timeout: 300000,
+  });
+  const out = `${r.stdout || ''}${r.stderr || ''}`.trim();
+  if (r.error || r.status !== 0) return { ok: false, status: r.status, message: out.slice(-500) || r.error?.message || 'install failed' };
+  return { ok: true, status: 0, tail: out.slice(-300) };
+}
+
+export function authPath(dshHome = dshHomeOf()) {
+  return join(dshHome, 'argent', 'auth.json');
+}
+
+/** 读取已登录账号 token（600 文件；不存在/损坏返回 null） */
+export function readAuthToken(dshHome = dshHomeOf()) {
+  try {
+    const doc = JSON.parse(readFileSync(authPath(dshHome), 'utf8'));
+    return doc?.token ? doc : null;
+  } catch { return null; }
+}
+
+/** 发送短信验证码（首跑引导；开发环境服务端会返回 devCode） */
+export async function sendLoginCode({ serverUrl, phone, fetchImpl = globalThis.fetch }) {
+  const base = String(serverUrl || '').replace(/\/+$/, '');
+  const res = await fetchImpl(`${base}/api/user/sms/send`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ phone }),
+  });
+  const text = await res.text(); let data = null; try { data = JSON.parse(text); } catch { data = null; }
+  if (!res.ok) return { ok: false, code: 'send_failed', message: data?.error || `HTTP ${res.status}`, cooldown: data?.cooldown };
+  return { ok: true, cooldown: data?.cooldown, devCode: data?.devCode || data?.code || '' };
+}
+
+/** 手机号+验证码登录（保存 token 到 600 auth.json，供 pair 使用） */
+export async function loginWithPhone({ serverUrl, phone, code, dshHome = dshHomeOf(), fetchImpl = globalThis.fetch }) {
+  const base = String(serverUrl || '').replace(/\/+$/, '');
+  const res = await fetchImpl(`${base}/api/user/login/phone`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ phone, code }),
+  });
+  const text = await res.text(); let data = null; try { data = JSON.parse(text); } catch { data = null; }
+  const token = data?.token || data?.data?.token || '';
+  if (!res.ok || !token) return { ok: false, code: 'login_failed', message: data?.error || `HTTP ${res.status}` };
+  const path = authPath(dshHome);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ serverUrl: base, phone, token, savedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
+  return { ok: true, path, phone, serverUrl: base, tokenTail: token.slice(-6) };
+}
+
+export function runnerConfigPath(dshHome = dshHomeOf()) {
+  return join(dshHome, 'argent', 'runner.json');
+}
+
+export function runnerScriptPath({ repo = repoRoot() } = {}) {
+  const candidate = join(repo, 'scripts', 'argent-runner.mjs');
+  return existsSync(candidate) ? candidate : '';
+}
+
+/** P4 runner 的 launchd plist（macOS）；Linux 可换 systemd unit（TODO 发布前补） */
+export function buildLaunchdPlist({ dshHome = dshHomeOf(), repo = repoRoot(), nodeBin = process.execPath } = {}) {
+  const script = runnerScriptPath({ repo });
+  const logDir = join(dshHome, 'argent', 'runner', 'logs');
+  return {
+    file: `${RUNNER_LABEL}.plist`,
+    content: `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${RUNNER_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodeBin}</string>
+    <string>${script || '<argent-runner.mjs>'}</string>
+    <string>--config</string>
+    <string>${runnerConfigPath(dshHome)}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${join(logDir, 'launchd.out.log')}</string>
+  <key>StandardErrorPath</key><string>${join(logDir, 'launchd.err.log')}</string>
+</dict>
+</plist>
+`,
+    label: RUNNER_LABEL,
+    script,
+  };
+}
+
+/** 状态自检（不启动任何东西；JSON 友好） */
+export function health({ dshHome = dshHomeOf(), profile = PROFILE_NAME, repo = repoRoot(), dshBin = 'dsh', port = 3080 } = {}) {
+  const version = probeDshVersion({ dshBin });
+  const dir = profileDir(dshHome, profile);
+  const profilePackage = join(dir, 'package.json');
+  const profilePatch = join(dir, 'cordis.patch.yml');
+  const runnerCfg = runnerConfigPath(dshHome);
+  const runnerCfgMode = existsSync(runnerCfg) ? (statSync(runnerCfg).mode & 0o777).toString(8) : '';
+  return {
+    ok: version.ok && versionMatches(version.version) && existsSync(profilePackage) && existsSync(profilePatch),
+    expectedDsh: DSH_EXACT_VERSION,
+    dsh: { ok: version.ok, version: version.ok ? version.version : '', matchesExact: version.ok && versionMatches(version.version), error: version.error },
+    profile: { dir, packageJson: existsSync(profilePackage), patch: existsSync(profilePatch) },
+    runner: { configPath: runnerCfg, configPresent: existsSync(runnerCfg), mode: runnerCfgMode },
+    webUrl: `http://127.0.0.1:${port}`,
+    repo,
+  };
+}
+
+/**
+ * 首跑配对：把 runner 配置写到 `$DSH_HOME/argent/runner.json`（600）。
+ * 两种来源：
+ *   · adminToken：调服务端 `POST /tenants/:appId/runner-tokens` 现场签发（90 天、绑定 appId）；
+ *   · runnerToken：直接使用已签发的 token（由管理员线下交付）。
+ * ⛔ 返回值/日志不回显 token；写盘前校验端口与响应。
+ */
+export async function pairRunner({
+  serverUrl, tenantAppId, adminToken = '', runnerToken = '',
+  runnerId = '', label = '', dshHome = dshHomeOf(), fetchImpl = globalThis.fetch,
+}) {
+  const base = String(serverUrl || '').replace(/\/+$/, '');
+  const appId = String(tenantAppId || '').trim();
+  if (!base || !appId) return { ok: false, code: 'validation', message: 'serverUrl / tenantAppId 必填' };
+  if (!adminToken && !runnerToken) return { ok: false, code: 'validation', message: '需要 --admin-token 或 --runner-token 之一' };
+  let token = String(runnerToken || '').trim();
+  if (!token) {
+    const res = await fetchImpl(`${base}/api/argent/v1/tenants/${encodeURIComponent(appId)}/runner-tokens`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${String(adminToken).trim()}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ label: String(label || 'argent-launcher') }),
+    });
+    const text = await res.text();
+    let data = null;
+    try { data = JSON.parse(text); } catch { data = null; }
+    if (!res.ok || !data?.data?.token) {
+      return { ok: false, code: 'issue_failed', message: `签发 runner token 失败：HTTP ${res.status} ${data?.error?.code || ''} ${data?.error?.message || ''}`.trim() };
+    }
+    token = data.data.token;
+  }
+  if (token.split('.').length !== 3) return { ok: false, code: 'token_shape', message: 'runner token 形态不正确（应为 JWT）' };
+  const cfgPath = runnerConfigPath(dshHome);
+  mkdirSync(dirname(cfgPath), { recursive: true });
+  const config = {
+    serverUrl: base, tenantAppId: appId, runnerToken: token,
+    runnerId: runnerId || `runner-${osHostname()}`,
+    leaseSec: 90, pollWaitMs: 20000, execTimeoutSec: 900,
+  };
+  writeFileSync(cfgPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  return { ok: true, configPath: cfgPath, serverUrl: base, tenantAppId: appId, runnerId: config.runnerId, tokenTail: token.slice(-6) };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@whyshu/argent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Argent 启动器：一条命令启动「打包好的 dsh + Argent 插件/角色预设」，并管理本机 runner 常驻。",
+  "type": "module",
+  "bin": {
+    "argent": "./bin/argent.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh": "0.2.1-rc.2",
+    "@whyshu/argent-presets": "0.1.1",
+    "@whyshu/argent-core": "0.1.5",
+    "@whyshu/argent-dsh": "0.1.0",
+    "@whyshu/argent-skin": "0.1.4",
+    "@whyshu/argent-gateway": "0.2.3",
+    "@whyshu/argent-flow": "0.1.0",
+    "@whyshu/argent-ml": "0.1.0",
+    "@michengai/dsh-im-connect": "1.0.2",
+    "@linxin666/dsh-client-ui-task-board": "0.4.7"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test/"
+  }
+}