kld-sdd 2.6.16 → 2.6.21

package/bin/kld-sdd-init.js

@@ -9,6 +9,7 @@
  *   log          SDD Telemetry CLI（记录阶段事件、查询指标）
  *   link-spec    将代码仓关联到本地 spec clone（git config sdd.specPath）
  *   sync-repos   工作目录下发现新增代码仓并轻量接入（不装 skills）
+ *   auth         用户账号绑定：login / logout / status
  */
 
 const path = require('path');
@@ -50,6 +51,15 @@ if (args[0] === 'log') {
     process.exit(1);
   }
   console.log(`✅ sync-repos 完成，接入 ${result.attached.length} 个代码仓`);
+} else if (args[0] === 'auth') {
+  const sub = args[1] || 'status';
+  const { runAuthCommand } = require('../lib/device-auth-cli.js');
+  runAuthCommand(sub, args.slice(2)).then((code) => {
+    process.exit(code);
+  }).catch((error) => {
+    console.error(`❌ auth 失败: ${error.message}`);
+    process.exit(1);
+  });
 } else {
   // 正常初始化模式
   const { main } = require('../lib/init');

package/kld-sdd-guide.html

@@ -1116,6 +1116,28 @@ node skywalk-sdd/log.cjs semantic-observe --project=. --change=add-user-auth">
       <div class="metric reveal"><div class="key">P-H</div><h4>Telemetry 健康度</h4><div class="value">doctor health × 100</div><p>与 P-C 阶段闭合率一起判断数据是否足够可信。</p></div>
     </div>
 
+    <p class="lead reveal" style="margin-top:32px"><b>KB 实时进度同步（Progress Agent）</b>：本地 JSONL 事实经 canonical CloudEvent 适配后发送到 Engineering KB；仅 durable ACK（accepted / duplicate_accepted）且仍 active 的 Run 才会发送 heartbeat。Agent 是<strong>事件触发、有限会话</strong>的用户级单实例——<strong>不再默认开机自启动/长期驻留</strong>：每条新 SDD 事实 durable append 后自动拉起（<code>ensureAgentRunning</code> 按 <code>agent.lock</code> 探测避免重复 spawn），按 5/15/10 分钟三档租约（clean idle / active silence / retry budget）自行退出；旧版开机自启动会在 init/config 时被幂等迁移移除。</p>
+    <div class="codeblock reveal">
+      <button type="button" class="copy" data-copy="# 配置 KB（需 progress:write scope）后 init 会自动 register，best-effort 迁移旧自启动 + 拉起当前会话 Agent
+npx kld-sdd --tool codex
+
+# 手动单次同步（强制 batch → ACK 落盘 → heartbeat，不进入有限会话循环）
+node skywalk-sdd/progress/agent-main.cjs --once --user-state-root=%LOCALAPPDATA%/kld-sdd/progress
+
+# 手动触发有限会话（正常由新 SDD 事实自动拉起，一般无需手动执行）
+node skywalk-sdd/progress/agent-main.cjs --user-state-root=%LOCALAPPDATA%/kld-sdd/progress
+
+# 查看自启动/迁移状态（degraded 时可再次 config/init 恢复）
+node -e &quot;require('./skywalk-sdd/progress/autostart.cjs').statusAutostart({testMode:true}).then(console.log)&quot;">复制</button>
+<pre><span class="k-c"># apiBase 必须包含 /api，例如 http://host:8090/api</span>
+<span class="k-c"># 状态目录：%LOCALAPPDATA%/kld-sdd/progress（Windows）或 ~/.local/state/kld-sdd/progress</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/progress/agent-main.cjs <span class="k-f">--once</span> --user-state-root=&lt;USER_STATE_ROOT&gt;
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/progress/agent-main.cjs --user-state-root=&lt;USER_STATE_ROOT&gt; <span class="k-o">(triggered finite session)</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/progress/autostart.cjs <span class="k-f">status</span> <span class="k-o">(platform adapter)</span></pre>
+    </div>
+    <div class="callout reveal"><b>破坏性对齐（CloudEvent 出站）：</b>出站 envelope 已与 KB canonical 契约对齐——<code>type</code> 为 <code>com.kunlunzhima.sdd.&lt;event_kind&gt;.v1</code>，<code>source</code> 为 <code>urn:kld-sdd:installation:…:workspace:…</code>，payload 含 <code>seq</code>/<code>change_key</code>，哈希模式 <code>canonical-json-v1</code>。旧版自定义 type/source/外壳<strong>不再兼容</strong>；升级后请以 KB schema/fixture 为准，勿依赖旧出站字段。</div>
+    <div class="callout reveal"><b>排障：</b>401/403 或 rejected_scope → 检查 API Key 是否含 <code>progress:write</code>；schema 拒绝只隔离单条事件；<code>autostart=degraded</code> 不破坏 kb-state，可重跑 config/init；heartbeat 不含 <code>active</code> 字段，资格来自 durable ACK + 本地 active Run 交集；可选 <code>agent_state</code>（<code>active</code>/<code>sleeping</code>/<code>terminal</code>）仅在会话启动/唤醒与计划退出前 best-effort 上报。</div>
+
     <p class="lead reveal" style="margin-top:32px"><b>事件与单变更报告</b>：事件落 <code>skywalk-sdd/events/</code>、活跃状态落 <code>skywalk-sdd/state/</code>（均 gitignored）；归档报告落 <code>openspec/changes/archive/&lt;date&gt;-&lt;name&gt;/reports/</code>。</p>
     <div class="codeblock reveal">
       <button type="button" class="copy" data-copy="node skywalk-sdd/log.cjs start --command=propose --project=. --change=add-user-auth --agent=codex --source=opsx-skill --session-id=sess_001

package/lib/device-auth-cli.js

@@ -0,0 +1,130 @@
+// kld-T03 — auth 子命令 CLI 薄层
+// 仅做参数解析、交互提示与退出码；业务逻辑在 lib/device-auth.js + skywalk-sdd/lib/user-config.cjs
+'use strict';
+
+const readline = require('node:readline');
+
+const {
+  resolveServer,
+  runDeviceFlow,
+  DEFAULT_SERVER_URL,
+} = require('./device-auth.js');
+const {
+  readUserConfig,
+  clearUserToken,
+  redactToken,
+  USER_CONFIG_VERSION,
+} = require('../skywalk-sdd/lib/user-config.cjs');
+const { normalizeServerUrl } = require('../skywalk-sdd/lib/usage-contract.cjs');
+
+async function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim())));
+}
+
+async function cmdStatus() {
+  const cfg = readUserConfig();
+  if (!cfg || !cfg.token) {
+    console.log('未绑定平台账号。');
+    console.log('使用 `kld-sdd auth login` 完成 Device Flow 绑定。');
+    return 0;
+  }
+  console.log('已绑定平台账号：');
+  console.log(`  server:   ${cfg.server || '(未设置)'}`);
+  console.log(`  userName: ${cfg.userName || '(未知)'}`);
+  console.log(`  boundAt:  ${cfg.boundAt || '(未知)'}`);
+  console.log(`  token:    ${redactToken(cfg.token)}`);
+  return 0;
+}
+
+async function cmdLogout() {
+  const removed = clearUserToken();
+  if (removed) {
+    console.log('✅ 已清除本地绑定（其他配置保留）。');
+  } else {
+    console.log('未检测到已绑定 token。');
+  }
+  return 0;
+}
+
+async function cmdLogin(args) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    // 解析 server：已有绑定 → env → 交互输入
+    let server = resolveServer();
+    const forceArg = args.find((a) => a.startsWith('--server='));
+    if (forceArg) {
+      const normalized = normalizeServerUrl(forceArg.slice('--server='.length));
+      if (!normalized) {
+        console.error('❌ --server 必须是 http/https URL');
+        return 1;
+      }
+      server = normalized;
+    }
+    if (!server) {
+      const answer = await ask(rl, `请输入平台地址（http/https，回车默认 ${DEFAULT_SERVER_URL}）：`);
+      const normalized = normalizeServerUrl(answer || DEFAULT_SERVER_URL);
+      if (!normalized) {
+        console.error('❌ 非法地址，必须 http/https');
+        return 1;
+      }
+      server = normalized;
+    }
+
+    const existing = readUserConfig();
+    if (existing && existing.token && existing.server === server) {
+      const answer = await ask(rl, `已绑定 ${server}（userName=${existing.userName || '未知'}），是否更新绑定？[y/N] `);
+      if (!/^[yY]/.test(answer)) {
+        console.log('保留原有绑定。');
+        return 0;
+      }
+    }
+
+    const pkg = require('../package.json');
+    console.log(`正在通过 Device Flow 绑定到 ${server} ...`);
+    const ac = new AbortController();
+    const sigint = () => { ac.abort(); };
+    process.on('SIGINT', sigint);
+    try {
+      const result = await runDeviceFlow({
+        server,
+        clientName: 'kld-sdd',
+        clientVersion: pkg && pkg.version ? String(pkg.version) : 'unknown',
+        onPrint: (msg) => console.log(msg),
+        signal: ac.signal,
+      });
+      if (result.status === 'bound') {
+        console.log('✅ 绑定成功。');
+        return 0;
+      }
+      if (result.status === 'aborted') {
+        console.log('已取消。');
+        return 130;
+      }
+      if (result.status === 'expired') {
+        console.log('⏱ 授权已过期，请重试。');
+        return 1;
+      }
+      if (result.status === 'denied') {
+        console.log('已拒绝授权。');
+        return 1;
+      }
+      console.error(`❌ 绑定失败：${result.reason || 'unknown'}`);
+      return 1;
+    } finally {
+      process.removeListener('SIGINT', sigint);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function runAuthCommand(sub, args) {
+  if (sub === 'status') return cmdStatus(args);
+  if (sub === 'login') return cmdLogin(args);
+  if (sub === 'logout') return cmdLogout(args);
+  console.error(`未知 auth 子命令：${sub}`);
+  console.error('用法: kld-sdd auth [status|login|logout] [--server=<url>]');
+  return 2;
+}
+
+module.exports = { runAuthCommand };

package/lib/device-auth.js

@@ -0,0 +1,345 @@
+// kld-T03 — Device Flow 授权客户端
+// 职责：code/poll、浏览器打开降级、过期/拒绝/Ctrl+C 状态、原子写入用户配置。
+// 与 kb-sdd 跨仓契约对齐；Node 14 兼容；不依赖全局 fetch。
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  normalizeServerUrl,
+  parseDeviceCodeResponse,
+  classifyDevicePollResponse,
+  postJson,
+  unwrapApiResponse,
+} = require('../skywalk-sdd/lib/usage-contract.cjs');
+const {
+  readUserConfig,
+  writeUserConfig,
+  USER_CONFIG_VERSION,
+} = require('../skywalk-sdd/lib/user-config.cjs');
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_EXPIRES_IN_MS = 600 * 1000;
+// 交互输入平台地址时的默认值（回车即采用）
+const DEFAULT_SERVER_URL = 'http://10.29.213.80:8080/';
+
+/**
+ * 解析 server URL：已有用户绑定 → 项目现有 KB server（kb-state.json.api）→ env KLD_SDD_SERVER → null。
+ * @param {{homeDir?:string, env?:object, projectRoot?:string}} [options]
+ * @returns {string|null} 规范化后的 server URL；未找到返回 null
+ */
+function resolveServer(options = {}) {
+  const homeDir = options.homeDir;
+  const env = options.env || process.env;
+  const projectRoot = options.projectRoot || process.cwd();
+  // 1. 已有用户绑定
+  const existing = readUserConfig(homeDir);
+  if (existing && typeof existing.server === 'string') {
+    const normalized = normalizeServerUrl(existing.server);
+    if (normalized) return normalized;
+  }
+  // 2. 项目现有 KB server（kld-fixback YELLOW#3）
+  try {
+    const kbStatePath = path.join(projectRoot, 'kb-state.json');
+    if (fs.existsSync(kbStatePath)) {
+      const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
+      if (kbState && typeof kbState.api === 'string') {
+        const normalized = normalizeServerUrl(kbState.api);
+        if (normalized) return normalized;
+      }
+    }
+  } catch {
+    // kb-state 读取失败时静默，继续下一级
+  }
+  // 3. env KLD_SDD_SERVER
+  if (env && typeof env.KLD_SDD_SERVER === 'string') {
+    const normalized = normalizeServerUrl(env.KLD_SDD_SERVER);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
+/**
+ * 请求 Device Flow code。
+ * @param {string} server — 已规范化的 server URL
+ * @param {{clientName?:string,clientVersion?:string,timeoutMs?:number}} [options]
+ * @returns {Promise<{deviceCode,userCode,verificationUri,verificationUriComplete,expiresIn,interval}>}
+ * @throws {Error} 网络失败 / 响应非法
+ */
+async function requestDeviceCode(server, options = {}) {
+  const normalized = normalizeServerUrl(server);
+  if (!normalized) throw new Error('server must be http/https URL');
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+    ? options.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+  const payload = {
+    clientName: typeof options.clientName === 'string' && options.clientName
+      ? options.clientName
+      : 'kld-sdd',
+    clientVersion: typeof options.clientVersion === 'string' && options.clientVersion
+      ? options.clientVersion
+      : 'unknown',
+  };
+  const result = await postJson(`${normalized}/api/v1/auth/device/code`, payload, { timeoutMs });
+  if (result.statusCode == null) {
+    throw new Error(`device code request failed: ${result.error ? result.error.message : 'network error'}`);
+  }
+  if (result.statusCode < 200 || result.statusCode >= 300) {
+    throw new Error(`device code request HTTP ${result.statusCode}`);
+  }
+  // 兼容两种格式：直接 data 或 ApiResponse 信封
+  let data = result.body;
+  if (result.body && typeof result.body === 'object' && typeof result.body.code === 'number') {
+    data = unwrapApiResponse(result.body);
+  }
+  const parsed = parseDeviceCodeResponse(data);
+  if (!parsed) throw new Error('device code response missing required fields (deviceCode/userCode/verificationUri)');
+  return parsed;
+}
+
+/**
+ * 轮询 Device Flow token，直到 authorized / expired / denied / aborted / error。
+ *
+ * @param {string} server — 已规范化 server URL
+ * @param {string} deviceCode
+ * @param {{intervalMs?:number,expiresInMs?:number,timeoutMs?:number,signal?:AbortSignal,onPending?:Function}} [options]
+ * @returns {Promise<{kind:'authorized',token:string,user:*}|{kind:'expired'}|{kind:'denied'}|{kind:'aborted'}|{kind:'error',message?:string}>}
+ */
+async function pollDeviceToken(server, deviceCode, options = {}) {
+  const normalized = normalizeServerUrl(server);
+  if (!normalized) return { kind: 'error', message: 'invalid server' };
+  const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0
+    ? options.intervalMs
+    : DEFAULT_POLL_INTERVAL_MS;
+  const expiresInMs = Number.isFinite(options.expiresInMs) && options.expiresInMs > 0
+    ? options.expiresInMs
+    : DEFAULT_EXPIRES_IN_MS;
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+    ? options.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+  const signal = options.signal;
+  const onPending = typeof options.onPending === 'function' ? options.onPending : null;
+
+  const startedAt = Date.now();
+  const deadline = startedAt + expiresInMs;
+  let currentInterval = intervalMs;
+  let consecutiveNetworkErrors = 0;
+  const MAX_CONSECUTIVE_NETWORK_ERRORS = 5;
+
+  // 主循环
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    if (signal && signal.aborted) return { kind: 'aborted' };
+    if (Date.now() >= deadline) return { kind: 'expired' };
+
+    const result = await postJson(
+      `${normalized}/api/v1/auth/device/poll`,
+      { deviceCode },
+      { timeoutMs: Math.min(timeoutMs, Math.max(1, deadline - Date.now())) },
+    );
+    if (signal && signal.aborted) return { kind: 'aborted' };
+
+    if (result.statusCode == null) {
+      consecutiveNetworkErrors += 1;
+      if (consecutiveNetworkErrors >= MAX_CONSECUTIVE_NETWORK_ERRORS) {
+        return { kind: 'error', message: result.error ? result.error.message : 'network error' };
+      }
+    } else {
+      consecutiveNetworkErrors = 0;
+    }
+
+    // 平台可能返回成功信封（{code:0,message,data}）：先解包再分类，
+    // 与 requestDeviceCode 的信封处理对齐；非 0 code 或裸契约响应保持原样，
+    // 交给分类器走 RFC 8628 error 字段等防御路径（向后兼容）。
+    let pollBody = result.body;
+    if (pollBody && typeof pollBody === 'object' && pollBody.code === 0) {
+      try {
+        pollBody = unwrapApiResponse(pollBody);
+      } catch {
+        pollBody = result.body;
+      }
+    }
+    const classified = classifyDevicePollResponse(result.statusCode, pollBody);
+    if (classified.kind === 'authorized') {
+      return { kind: 'authorized', token: classified.token, user: classified.user };
+    }
+    if (classified.kind === 'expired') return { kind: 'expired' };
+    if (classified.kind === 'denied') return { kind: 'denied' };
+    if (classified.kind === 'slow_down') {
+      currentInterval = Math.min(currentInterval + 1000, 10000);
+    }
+    if (classified.kind === 'error' && result.statusCode != null && result.statusCode >= 500) {
+      // 5xx 当网络错误处理，继续
+    } else if (classified.kind === 'error') {
+      return { kind: 'error', message: classified.message };
+    }
+    // pending / slow_down / 5xx 都继续轮询
+    if (onPending) {
+      try { onPending({ kind: classified.kind, intervalMs: currentInterval }); } catch { /* ignore */ }
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: 'expired' };
+    const sleepMs = Math.min(currentInterval, remaining);
+    await sleep(sleepMs, signal);
+    if (signal && signal.aborted) return { kind: 'aborted' };
+  }
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      if (signal) signal.removeEventListener('abort', done);
+      clearTimeout(timer);
+      resolve();
+    }
+    if (signal) {
+      if (signal.aborted) return done();
+      signal.addEventListener('abort', done, { once: true });
+    }
+  });
+}
+
+/**
+ * 构造各平台打开浏览器的命令（纯函数，便于测试）。
+ * win32 用 PowerShell Start-Process（ShellExecute 打开默认浏览器）：
+ * - cmd /c start：部分机器静默失败，退出码 0 但浏览器未开（探测服务器无请求）；
+ * - explorer.exe <url>：URL 含 ? query 时解析失败，退而弹出文件夹窗口（真机复现）；
+ * - Start-Process 经探测验证可完整传递带 query 的 URL。
+ * 用 -EncodedCommand（UTF-16LE base64）传参，Node→CreateProcess→PowerShell 全程无引号转义问题。
+ * @param {'win32'|'darwin'|string} platform
+ * @param {string} url
+ * @returns {{cmd:string,args:string[]}}
+ */
+function buildOpenCommand(platform, url) {
+  const target = String(url);
+  if (platform === 'win32') {
+    // 单引号在 PowerShell 单引号字符串中用 '' 转义；URL 正常不含单引号，防御处理
+    const ps = `Start-Process '${target.replace(/'/g, "''")}'`;
+    const encoded = Buffer.from(ps, 'utf16le').toString('base64');
+    return { cmd: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded] };
+  }
+  if (platform === 'darwin') return { cmd: 'open', args: [target] };
+  return { cmd: 'xdg-open', args: [target] };
+}
+
+/**
+ * 打开浏览器（best-effort）。任何失败均不抛错，返回 false 让调用方走打印降级。
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+async function openSystemBrowser(url) {
+  if (typeof url !== 'string' || !url) return false;
+  const platform = process.platform;
+  const { cmd, args } = buildOpenCommand(platform, url);
+  return new Promise((resolve) => {
+    let child;
+    try {
+      // win32 不能 detached：DETACHED_PROCESS（无控制台）下 PowerShell Start-Process
+      // 会静默失败——退出码 0 但浏览器未开（真机矩阵验证）。子进程秒退 + unref，
+      // 不依赖 detached 也能让父进程正常退出。
+      child = spawn(cmd, args, { detached: platform !== 'win32', stdio: 'ignore' });
+    } catch {
+      resolve(false);
+      return;
+    }
+    let settled = false;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    child.on('error', () => finish(false));
+    child.on('close', (code) => finish(code === 0));
+    child.unref();
+    // 浏览器启动命令通常立刻返回；超过 3s 未返回视为已脱手
+    setTimeout(() => finish(true), 3000).unref();
+  });
+}
+
+/**
+ * 完整 Device Flow 编排。
+ *
+ * @param {object} options
+ * @param {string} options.server — 已规范化 server URL（必需）
+ * @param {string} [options.clientName]
+ * @param {string} [options.clientVersion]
+ * @param {string} [options.homeDir] — 注入 home（测试用）
+ * @param {Function} [options.openUrl] — 自定义浏览器打开；返回 Promise<boolean>
+ * @param {Function} [options.onPrint] — 输出提示（默认 console.log）
+ * @param {number} [options.intervalMs]
+ * @param {number} [options.expiresInMs]
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<{status:'bound'|'expired'|'denied'|'aborted'|'error',reason?:string,config?:object}>}
+ */
+async function runDeviceFlow(options = {}) {
+  const normalized = normalizeServerUrl(options.server || '');
+  const onPrint = typeof options.onPrint === 'function' ? options.onPrint : () => {};
+  if (!normalized) {
+    return { status: 'error', reason: 'server must be http/https URL' };
+  }
+  const openUrl = typeof options.openUrl === 'function' ? options.openUrl : openSystemBrowser;
+
+  let code;
+  try {
+    code = await requestDeviceCode(normalized, options);
+  } catch (err) {
+    return { status: 'error', reason: String(err && err.message || err) };
+  }
+
+  // 打开浏览器；失败时打印降级
+  let opened = false;
+  try {
+    opened = await openUrl(code.verificationUriComplete || code.verificationUri);
+  } catch {
+    opened = false;
+  }
+  if (!opened) {
+    onPrint(`请访问以下链接完成授权：`);
+    onPrint(`  ${code.verificationUriComplete || code.verificationUri}`);
+    onPrint(`验证码：${code.userCode}`);
+  }
+
+  const pollResult = await pollDeviceToken(normalized, code.deviceCode, {
+    intervalMs: Number.isFinite(options.intervalMs) ? options.intervalMs : code.interval * 1000,
+    expiresInMs: Number.isFinite(options.expiresInMs) ? options.expiresInMs : code.expiresIn * 1000,
+    signal: options.signal,
+  });
+
+  if (pollResult.kind === 'aborted') return { status: 'aborted' };
+  if (pollResult.kind === 'expired') return { status: 'expired' };
+  if (pollResult.kind === 'denied') return { status: 'denied' };
+  if (pollResult.kind === 'error') return { status: 'error', reason: pollResult.message || 'poll error' };
+
+  // authorized：原子写入配置
+  const existing = readUserConfig(options.homeDir) || {};
+  const displayName = pollResult.user && typeof pollResult.user === 'object'
+    ? (pollResult.user.displayName || pollResult.user.userName || pollResult.user.userId || null)
+    : null;
+  const next = Object.assign({}, existing, {
+    version: USER_CONFIG_VERSION,
+    server: normalized,
+    token: pollResult.token,
+    userName: displayName || existing.userName || null,
+    boundAt: new Date().toISOString(),
+  });
+  try {
+    writeUserConfig(next, options.homeDir);
+  } catch (err) {
+    return { status: 'error', reason: `write config failed: ${err && err.message || err}` };
+  }
+  return { status: 'bound', config: next };
+}
+
+module.exports = {
+  resolveServer,
+  requestDeviceCode,
+  pollDeviceToken,
+  runDeviceFlow,
+  openSystemBrowser,
+  buildOpenCommand,
+  DEFAULT_SERVER_URL,
+};

package/lib/init-account-binding.js

@@ -0,0 +1,108 @@
+// kld-B1 — init 向导平台账号绑定（Device Flow）编排
+// 职责：已绑定提示更新 / 未绑定引导授权 / 跳过写仅 server 配置 / 失败不阻塞 init。
+// 依赖注入（runDeviceFlow/readUserConfig/writeUserConfig/resolveServer/ask/onPrint）便于单测 mock。
+// 提示语不出现“使用统计”字样（B1 评审要求）。
+'use strict';
+
+const deviceAuth = require('./device-auth');
+const userConfig = require('../skywalk-sdd/lib/user-config.cjs');
+
+const LATER_LOGIN_HINT = '稍后运行 npx kld-sdd auth login 绑定平台账号';
+const DEFAULT_SERVER_URL = deviceAuth.DEFAULT_SERVER_URL;
+
+function defaultPrint(line) {
+  console.log(line);
+}
+
+/**
+ * 账号绑定向导。
+ *
+ * @param {object} options
+ * @param {Function} [options.ask] — 交互提问（question）=> Promise<answer>；非交互环境可不传
+ * @param {boolean} [options.skipAuth] — --skip-auth：不询问，打印稍后绑定提示
+ * @param {Function} [options.isInteractive] — 是否交互终端（默认按 stdin.isTTY 判定）
+ * @param {Function} [options.onPrint] — 输出（默认 console.log）
+ * @param {Function} [options.readUserConfig] — 默认 skywalk-sdd/lib/user-config.cjs
+ * @param {Function} [options.writeUserConfig]
+ * @param {Function} [options.resolveServer] — 默认 lib/device-auth.js
+ * @param {Function} [options.runDeviceFlow]
+ * @param {string} [options.homeDir] — 注入 home（测试用）
+ * @param {AbortSignal} [options.signal] — Ctrl+C 等外部取消信号
+ * @returns {Promise<{status:'bound'|'kept'|'skipped'|'failed'|'deferred',userName?:string,config?:object,reason?:string}>}
+ */
+async function runAccountBinding(options = {}) {
+  const print = typeof options.onPrint === 'function' ? options.onPrint : defaultPrint;
+  const readCfg = typeof options.readUserConfig === 'function' ? options.readUserConfig : userConfig.readUserConfig;
+  const writeCfg = typeof options.writeUserConfig === 'function' ? options.writeUserConfig : userConfig.writeUserConfig;
+  const resolveSrv = typeof options.resolveServer === 'function' ? options.resolveServer : deviceAuth.resolveServer;
+  const runFlow = typeof options.runDeviceFlow === 'function' ? options.runDeviceFlow : deviceAuth.runDeviceFlow;
+  const isInteractive = typeof options.isInteractive === 'function'
+    ? options.isInteractive
+    : () => Boolean(process.stdin && process.stdin.isTTY);
+  const homeDir = options.homeDir;
+
+  // --skip-auth 或 stdin 非 TTY：不询问，打印一行稍后绑定提示
+  if (options.skipAuth || !isInteractive() || typeof options.ask !== 'function') {
+    print(`🔗 ${LATER_LOGIN_HINT}`);
+    return { status: 'deferred' };
+  }
+  const ask = options.ask;
+
+  const existing = readCfg(homeDir);
+  if (existing && existing.token) {
+    const boundDate = typeof existing.boundAt === 'string' && existing.boundAt
+      ? existing.boundAt.slice(0, 10)
+      : '未知日期';
+    const answer = String(await ask(`? 已绑定账号：${existing.userName || '未知用户'}（${boundDate} 绑定）。是否需要更新用户绑定？(y/N) `))
+      .trim().toLowerCase();
+    if (answer !== 'y' && answer !== 'yes') {
+      print(`✓ 保留现有绑定：${existing.userName || '未知用户'}`);
+      return { status: 'kept', userName: existing.userName || null, config: existing };
+    }
+  }
+
+  const bindAnswer = String(await ask('? 是否绑定平台账号？(Y/n) ')).trim().toLowerCase();
+  if (bindAnswer === 'n' || bindAnswer === 'no') {
+    // 选择不绑定/跳过：写仅含 server 的用户级 config（resolveServer 无结果则不写）
+    const server = resolveSrv({ homeDir });
+    if (server) {
+      try {
+        writeCfg({ version: userConfig.USER_CONFIG_VERSION, server }, homeDir);
+      } catch (err) {
+        print(`⚠️  写入用户配置失败（${err && err.message ? err.message : err}），已跳过`);
+      }
+    }
+    print(`🔗 ${LATER_LOGIN_HINT}`);
+    return { status: 'skipped' };
+  }
+
+  let server = resolveSrv({ homeDir });
+  if (!server) {
+    const input = String(await ask(`? 请输入平台地址（http/https，回车默认 ${DEFAULT_SERVER_URL}）：`)).trim();
+    server = input || DEFAULT_SERVER_URL;
+  }
+
+  print('请在浏览器完成授权，等待中…（按 Ctrl+C 取消）');
+  const result = await runFlow({ server, homeDir, onPrint: print, signal: options.signal });
+  if (result && result.status === 'bound') {
+    const name = result.config && result.config.userName ? result.config.userName : '未知用户';
+    print(`✓ 已绑定：${name}`);
+    return { status: 'bound', userName: name, config: result.config };
+  }
+
+  const status = result && result.status;
+  const hints = {
+    expired: '⚠️  授权已过期，未完成绑定',
+    denied: '⚠️  授权被拒绝，未完成绑定',
+    aborted: '⚠️  已取消绑定',
+  };
+  print(hints[status] || `⚠️  绑定失败${result && result.reason ? `：${result.reason}` : ''}`);
+  print(`🔗 ${LATER_LOGIN_HINT}`);
+  return { status: 'failed', reason: status || 'error' };
+}
+
+module.exports = {
+  runAccountBinding,
+  LATER_LOGIN_HINT,
+  DEFAULT_SERVER_URL,
+};