codewave-openclaw-installer 2.2.3 → 2.3.0

package/README.md

@@ -16,17 +16,17 @@ npx codewave-openclaw-installer
 
 | 工具 | 包管理器 | 说明 |
 |------|---------|------|
-| `razel-py-cli` | pipx | Python CLI（验收文档、音视频转写等） |
-| `razel-cli` | npm | Node CLI（PoPo 文档、PoPo 机器人、腾讯会议等） |
+| `razel-py-cli` | 插件私有运行时 | Python CLI（验收文档、音视频转写等） |
+| `razel-cli` | 插件私有运行时 | Node CLI（PoPo 文档、PoPo 机器人、腾讯会议等） |
 
-Python CLI 安装建议：
+说明：
 
 ```bash
-brew install pipx
-pipx ensurepath
-pipx install razel-py-cli
+npx codewave-openclaw-installer
 ```
 
+安装器会优先使用仓库 `pkg/` 里的离线包，在 `~/.openclaw/runtime/codewave-openclaw-installer/` 下创建插件私有 Python venv 和 Node 运行目录，并在 `~/.local/bin/` 写入 `razel-py-cli` / `razel-cli` wrapper。
+
 ### OpenClaw Skills（自动注册）
 
 安装后 Skills 作为 OpenClaw Extension 自动加载，无需手动复制：
@@ -66,7 +66,7 @@ pipx install razel-py-cli
 
 1. `preflight`：检测本机依赖、配置和渠道线索
 2. `core-install`：安装并初始化 `razel-py-cli` / `razel-cli`
-3. `extension-install`：将本包安装到 `~/.openclaw/extensions/codewave-toolkit/`
+3. `extension-install`：通过 OpenClaw 官方插件安装流程将本包注册到 `~/.openclaw/extensions/codewave-openclaw-installer/`
 4. `postflight`：重启 OpenClaw Gateway，并运行统一检查输出最终状态
 5. `channel-bootstrap`：检测到飞书或钉钉线索时，按官方入口自动安装并初始化
 
@@ -107,7 +107,9 @@ codewave-check --json
 ## 卸载
 
 ```bash
-rm -rf ~/.openclaw/extensions/codewave-toolkit
+rm -rf ~/.openclaw/extensions/codewave-openclaw-installer
+rm -rf ~/.openclaw/runtime/codewave-openclaw-installer
+rm -f ~/.local/bin/razel-py-cli ~/.local/bin/razel-cli
 openclaw gateway restart
 ```
 

package/bin/check.mjs

@@ -17,7 +17,9 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform } from 'node:os';
 import {
+  CODEWAVE_TOOLKIT_RUNTIME_ROOT,
   CHANNEL_DEFINITIONS,
+  getManagedCommandPath,
   detectDesktopAppInstallMatches,
   getDesktopAppCandidates,
 } from './install-lib.mjs';
@@ -47,6 +49,10 @@ let windowsUninstallDisplayNamesPromise = null;
 // ─── 工具函数 ───
 
 function commandExists(cmd) {
+  const managed = getManagedCommandPath(cmd);
+  if (managed && existsSync(managed)) {
+    return Promise.resolve(true);
+  }
   return new Promise((resolve) => {
     const check = isWin ? 'where' : 'which';
     const child = spawn(check, [cmd], { stdio: 'ignore', shell: isWin });
@@ -56,8 +62,9 @@ function commandExists(cmd) {
 }
 
 function getCommandVersion(cmd, args = ['--version']) {
+  const executable = (getManagedCommandPath(cmd) && existsSync(getManagedCommandPath(cmd))) ? getManagedCommandPath(cmd) : cmd;
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: isWin });
+    const child = spawn(executable, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: isWin && !existsSync(executable) });
     let stdout = '';
     child.stdout?.on('data', (d) => { stdout += d.toString(); });
     child.on('close', (code) => resolve(code === 0 ? stdout.trim().split('\n')[0] : null));
@@ -90,16 +97,18 @@ function openclawChannelHints() {
 }
 
 function run(cmd, args) {
+  const executable = (getManagedCommandPath(cmd) && existsSync(getManagedCommandPath(cmd))) ? getManagedCommandPath(cmd) : cmd;
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: 'inherit', shell: isWin });
+    const child = spawn(executable, args, { stdio: 'inherit', shell: isWin && !existsSync(executable) });
     child.on('close', (code) => resolve(code ?? 1));
     child.on('error', () => resolve(1));
   });
 }
 
 function runCapture(cmd, args) {
+  const executable = (getManagedCommandPath(cmd) && existsSync(getManagedCommandPath(cmd))) ? getManagedCommandPath(cmd) : cmd;
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: isWin });
+    const child = spawn(executable, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: isWin && !existsSync(executable) });
     let stdout = '';
     let stderr = '';
     child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
@@ -202,9 +211,17 @@ async function checkOpenClawConfig() {
 }
 
 async function checkPythonDocx() {
+  const managedPython = join(
+    CODEWAVE_TOOLKIT_RUNTIME_ROOT,
+    'py',
+    isWin ? 'Scripts' : 'bin',
+    isWin ? 'python.exe' : 'python3',
+  );
+  const pythonExecutable = existsSync(managedPython) ? managedPython : 'python3';
   return new Promise((resolve) => {
-    const child = spawn('python3', ['-c', 'import docx; print(docx.__version__)'], {
+    const child = spawn(pythonExecutable, ['-c', 'import docx; print(docx.__version__)'], {
       stdio: ['ignore', 'pipe', 'pipe'],
+      shell: isWin && !existsSync(pythonExecutable),
     });
     let stdout = '';
     child.stdout?.on('data', (d) => { stdout += d.toString(); });
@@ -216,12 +233,12 @@ async function checkPythonDocx() {
           name: 'python-docx',
           status: 'warn',
           message: '未安装（DOCX 解析的 fallback 方案之一）',
-          fix: 'pip3 install python-docx',
+          fix: '重新运行 npx codewave-openclaw-installer，或手动补齐 python-docx',
         });
       }
     });
     child.on('error', () => {
-      resolve({ name: 'python-docx', status: 'warn', message: 'python3 不可用' });
+      resolve({ name: 'python-docx', status: 'warn', message: 'Python 运行时不可用' });
     });
   });
 }
@@ -243,7 +260,7 @@ async function checkDocxPipeline() {
       name: 'DOCX 解析工具链',
       status: 'fail',
       message: '缺少所有 DOCX 解析方案 (pandoc / textutil / python-docx)',
-      fix: isMac ? 'brew install pandoc' : isLinux ? 'sudo apt install pandoc' : 'pip3 install python-docx',
+      fix: isMac ? 'brew install pandoc，或重新运行 npx codewave-openclaw-installer' : isLinux ? 'sudo apt install pandoc，或重新运行 npx codewave-openclaw-installer' : '重新运行 npx codewave-openclaw-installer',
     };
   }
   return {
@@ -433,10 +450,10 @@ async function main() {
 
   // CLI 工具
   checks['razel-py-cli'] = await checkCli('razel-py-cli', {
-    installCmd: 'pipx install razel-py-cli && razel-py-cli init',
+    installCmd: '重新运行 npx codewave-openclaw-installer（将优先安装插件私有 razel-py-cli 运行时）',
   });
   checks['razel-cli'] = await checkCli('razel-cli', {
-    installCmd: 'npm install -g @lcap-delivery/razel-cli@latest && razel-cli init',
+    installCmd: '重新运行 npx codewave-openclaw-installer（将优先安装插件私有 razel-cli 运行时）',
   });
   checks['jq'] = await checkCli('jq', {
     installCmd: isMac ? 'brew install jq' : 'sudo apt install jq',

package/bin/install-lib.mjs

@@ -3,6 +3,12 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import * as path from 'node:path';
 
+export const CODEWAVE_TOOLKIT_CONFIG_PATH = join(homedir(), '.openclaw', 'codewave-toolkit.json');
+export const CODEWAVE_TOOLKIT_EXTENSION_ID = 'codewave-openclaw-installer';
+export const CODEWAVE_TOOLKIT_EXTENSION_ROOT = join(homedir(), '.openclaw', 'extensions', CODEWAVE_TOOLKIT_EXTENSION_ID);
+export const CODEWAVE_TOOLKIT_RUNTIME_ROOT = join(homedir(), '.openclaw', 'runtime', CODEWAVE_TOOLKIT_EXTENSION_ID);
+export const CODEWAVE_TOOLKIT_WRAPPER_BIN = join(homedir(), '.local', 'bin');
+
 export const SKILL_SUMMARIES = [
   'acceptance-doc-entry    — 项目验收文档生成',
   'pmo-weekly-report       — PMO 项目看板周报',
@@ -199,13 +205,13 @@ export function classifyPythonInstallFailure(stderr = '') {
   if (stderr.includes('externally-managed-environment') || stderr.includes('PEP 668')) {
     return {
       code: 'pep668',
-      message: '当前 Python 环境受 PEP 668 管理，建议改用 pipx 安装 razel-py-cli',
+      message: '当前 Python 环境受 PEP 668 管理，建议改用安装器创建插件私有运行时',
     };
   }
 
   return {
     code: 'generic',
-    message: 'Python CLI 安装失败，请检查 python3/pip3 是否可用',
+    message: 'Python CLI 安装失败，请检查 python3/venv/pip 是否可用',
   };
 }
 
@@ -511,3 +517,56 @@ export function buildRazelConfigBootstrap({
 
   return { writes, missing };
 }
+
+export function getSmartCustomerServiceDocsDir({
+  env = process.env,
+  toolkitConfig = {},
+} = {}) {
+  const envDir = typeof env.SMART_CS_DOCS_DIR === 'string' ? env.SMART_CS_DOCS_DIR.trim() : '';
+  if (envDir) {
+    return envDir;
+  }
+
+  const configDir = typeof toolkitConfig?.smartCustomerService?.docsDir === 'string'
+    ? toolkitConfig.smartCustomerService.docsDir.trim()
+    : '';
+  if (configDir) {
+    return configDir;
+  }
+
+  return '';
+}
+
+export function getSmartCustomerServiceVectorConfig({
+  env = process.env,
+  toolkitConfig = {},
+} = {}) {
+  const config = toolkitConfig?.smartCustomerService?.vector || {};
+  const enabled = env.SMART_CS_VECTOR_ENABLED
+    ? ['1', 'true', 'yes', 'on'].includes(String(env.SMART_CS_VECTOR_ENABLED).trim().toLowerCase())
+    : config.enabled === true;
+
+  return {
+    enabled,
+    baseUrl: (env.SMART_CS_VECTOR_BASE_URL || config.baseUrl || '').trim?.() || '',
+    apiKey: (env.SMART_CS_VECTOR_API_KEY || config.apiKey || '').trim?.() || '',
+    model: (env.SMART_CS_VECTOR_MODEL || config.model || '').trim?.() || '',
+  };
+}
+
+export function getManagedCommandPath(command, {
+  platform = process.platform,
+  runtimeRoot = CODEWAVE_TOOLKIT_RUNTIME_ROOT,
+} = {}) {
+  const isWindows = platform === 'win32';
+
+  if (command === 'razel-py-cli') {
+    return join(runtimeRoot, 'py', isWindows ? 'Scripts' : 'bin', isWindows ? 'razel-py-cli.exe' : 'razel-py-cli');
+  }
+
+  if (command === 'razel-cli') {
+    return join(runtimeRoot, 'node', 'node_modules', '.bin', isWindows ? 'razel-cli.cmd' : 'razel-cli');
+  }
+
+  return null;
+}

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve, join } from 'node:path';
 import * as path from 'node:path';
 import { homedir } from 'node:os';
@@ -9,16 +9,21 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 
 import {
+  CODEWAVE_TOOLKIT_CONFIG_PATH,
+  CODEWAVE_TOOLKIT_EXTENSION_ROOT,
+  CODEWAVE_TOOLKIT_RUNTIME_ROOT,
+  CODEWAVE_TOOLKIT_WRAPPER_BIN,
   CHANNEL_DEFINITIONS,
   SKILL_SUMMARIES,
   buildRazelConfigBootstrap,
-  classifyPythonInstallFailure,
   createInstallContext,
   detectDesktopAppInstallMatches,
   evaluateChannelDetection,
   getCoreBootstrapPlan,
   getDesktopAppCandidates,
-  getPipxBootstrapPlan,
+  getManagedCommandPath,
+  getSmartCustomerServiceDocsDir,
+  getSmartCustomerServiceVectorConfig,
   preserveEnabledTruePreference,
   resolvePromptDefault,
   shouldDryRun,
@@ -56,7 +61,21 @@ function refreshLocalToolPaths() {
     : path.posix.join(homedir(), '.local', 'bin'));
 }
 
+refreshLocalToolPaths();
+
+function resolveManagedExecutable(cmd) {
+  const managedPath = getManagedCommandPath(cmd);
+  if (managedPath && existsSync(managedPath)) {
+    return managedPath;
+  }
+  return null;
+}
+
 function resolveExecutable(cmd) {
+  const managed = resolveManagedExecutable(cmd);
+  if (managed) {
+    return managed;
+  }
   if (!isWin) {
     return cmd;
   }
@@ -114,6 +133,10 @@ function runCapture(cmd, args, opts = {}) {
 }
 
 function commandExists(cmd) {
+  const managed = resolveManagedExecutable(cmd);
+  if (managed) {
+    return Promise.resolve(true);
+  }
   return new Promise((resolve) => {
     const check = isWin ? 'where' : 'which';
     const child = spawn(check, [cmd], { stdio: 'ignore', shell: false });
@@ -134,6 +157,69 @@ function readJson(filePath) {
   }
 }
 
+function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+function writeJson(filePath, value) {
+  ensureParentDir(filePath);
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function readToolkitConfig() {
+  return readJson(CODEWAVE_TOOLKIT_CONFIG_PATH) || {};
+}
+
+function writeToolkitConfig(updater) {
+  if (DRY_RUN) {
+    return false;
+  }
+  const current = readToolkitConfig();
+  const next = updater(current) || current;
+  writeJson(CODEWAVE_TOOLKIT_CONFIG_PATH, next);
+  return true;
+}
+
+function getPrivatePythonBin(command) {
+  return getManagedCommandPath(command, { runtimeRoot: CODEWAVE_TOOLKIT_RUNTIME_ROOT });
+}
+
+function getPrivatePythonPipPath() {
+  return join(CODEWAVE_TOOLKIT_RUNTIME_ROOT, 'py', isWin ? 'Scripts' : 'bin', isWin ? 'pip.exe' : 'pip');
+}
+
+function getPrivateNodeRoot() {
+  return join(CODEWAVE_TOOLKIT_RUNTIME_ROOT, 'node');
+}
+
+function getWrapperPath(command) {
+  const filename = isWin ? `${command}.cmd` : command;
+  return join(CODEWAVE_TOOLKIT_WRAPPER_BIN, filename);
+}
+
+function ensureWrapper(command, targetPath) {
+  if (DRY_RUN || !targetPath) {
+    return false;
+  }
+  mkdirSync(CODEWAVE_TOOLKIT_WRAPPER_BIN, { recursive: true });
+  const wrapperPath = getWrapperPath(command);
+  try {
+    if (existsSync(wrapperPath) || lstatSync(wrapperPath).isSymbolicLink()) {
+      rmSync(wrapperPath, { force: true });
+    }
+  } catch {
+    // ignore cleanup errors and let writeFileSync surface real failures
+  }
+  const content = isWin
+    ? `@echo off\r\n"${targetPath}" %*\r\n`
+    : `#!/bin/sh\nexec "${targetPath}" "$@"\n`;
+  writeFileSync(wrapperPath, content, 'utf8');
+  if (!isWin) {
+    chmodSync(wrapperPath, 0o755);
+  }
+  return true;
+}
+
 function clearPluginRegistration(pluginIds) {
   if (DRY_RUN) {
     return false;
@@ -548,94 +634,54 @@ async function resolvePythonRuntime() {
   };
 }
 
-async function ensurePipx(context) {
-  if (await commandExists('pipx')) {
-    contextResult(context, 'pipx', 'reused');
-    return {
-      available: true,
-      invoke: { cmd: 'pipx', args: [] },
-      pythonCommand: (await resolvePythonRuntime()).pythonCommand,
-    };
+async function installPythonCli(context) {
+  const managedCli = getPrivatePythonBin('razel-py-cli');
+  if (managedCli && existsSync(managedCli)) {
+    console.log(dim('  ↺ 已检测到私有 razel-py-cli 运行时，跳过安装'));
+    ensureWrapper('razel-py-cli', managedCli);
+    contextResult(context, 'razel-py-cli', 'reused (private)');
+    return;
   }
 
   const runtime = await resolvePythonRuntime();
-  if (!runtime.pythonCommand && !runtime.pythonLauncher) {
-    console.log(yellow('  ⚠️ 缺少 Python 运行时，无法安装 pipx'));
-    contextResult(context, 'pipx', 'blocked (missing python3)');
-    return { available: false, invoke: null, pythonCommand: null };
-  }
-
-  const pipxPlan = getPipxBootstrapPlan({
-    platform: process.platform,
-    hasBrew: await commandExists('brew'),
-    pythonCommand: runtime.pythonCommand || 'python3',
-    pythonLauncher: runtime.pythonLauncher,
-  });
-
-  if (!(await commandExists(pipxPlan.install.cmd))) {
-    console.log(yellow(`  ⚠️ 缺少 ${pipxPlan.install.cmd}，无法自动安装 pipx`));
-    contextResult(context, 'pipx', `blocked (${pipxPlan.install.cmd} missing)`);
-    return { available: false, invoke: null, pythonCommand: runtime.pythonCommand };
-  }
-
-  console.log(dim('  正在安装 pipx...'));
-  const installCode = await run(pipxPlan.install.cmd, pipxPlan.install.args);
-  if (installCode !== 0) {
-    if (runtime.pipCommand) {
-      const classification = classifyPythonInstallFailure('externally-managed-environment');
-      console.log(dim(`  提示: ${classification.message}`));
-    }
-    contextResult(context, 'pipx', 'failed');
-    return { available: false, invoke: null, pythonCommand: runtime.pythonCommand };
-  }
-
-  await run(pipxPlan.ensurePath.cmd, pipxPlan.ensurePath.args);
-  refreshLocalToolPaths();
-  const pipxAvailable = await commandExists('pipx');
-  contextResult(context, 'pipx', pipxAvailable ? 'ok' : 'ok (path refresh may be needed)');
-  return {
-    available: true,
-    invoke: pipxAvailable ? { cmd: 'pipx', args: [] } : pipxPlan.invoke,
-    pythonCommand: runtime.pythonCommand,
-  };
-}
-
-async function installPythonCli(context) {
-  const pipxState = await ensurePipx(context);
-
-  if (await commandExists('razel-py-cli')) {
-    console.log(dim('  ↺ 已检测到 razel-py-cli，跳过安装'));
-    contextResult(context, 'razel-py-cli', 'reused');
+  if (!runtime.pythonCommand) {
+    console.log(yellow('  ⚠️ 缺少 Python 运行时，无法继续安装私有 razel-py-cli'));
+    contextResult(context, 'razel-py-cli', 'blocked (missing python3)');
     return;
   }
 
-  if (!pipxState.available || !pipxState.invoke) {
-    console.log(yellow('  ⚠️ 未检测到 pipx，无法继续安装 razel-py-cli'));
-    contextResult(context, 'razel-py-cli', 'blocked (pipx missing)');
+  const privatePyRoot = join(CODEWAVE_TOOLKIT_RUNTIME_ROOT, 'py');
+  rmSync(privatePyRoot, { recursive: true, force: true });
+  mkdirSync(CODEWAVE_TOOLKIT_RUNTIME_ROOT, { recursive: true });
+
+  console.log(dim('  正在创建私有 Python 运行时...'));
+  const venvCode = await run(runtime.pythonCommand, ['-m', 'venv', privatePyRoot]);
+  if (venvCode !== 0) {
+    console.log(yellow(`  ⚠️ 私有 Python 运行时创建失败${runtime.pythonCommand ? ` (python=${runtime.pythonCommand})` : ''}`));
+    contextResult(context, 'razel-py-cli', 'failed (venv)');
     return;
   }
 
-  const pipxArgs = [...pipxState.invoke.args, 'install'];
-  if (pipxState.pythonCommand) {
-    pipxArgs.push('--python', pipxState.pythonCommand);
+  const pipPath = getPrivatePythonPipPath();
+  const upgradeCode = await run(pipPath, ['install', '--upgrade', 'pip']);
+  if (upgradeCode !== 0) {
+    console.log(dim('  提示: pip 升级失败，继续尝试安装 razel-py-cli'));
   }
-  pipxArgs.push('razel-py-cli');
 
-  const pipxCode = await run(pipxState.invoke.cmd, pipxArgs);
-  if (pipxCode !== 0) {
-    console.log(yellow(`  ⚠️ razel-py-cli 通过 pipx 安装失败${pipxState.pythonCommand ? ` (python=${pipxState.pythonCommand})` : ''}`));
-    contextResult(context, 'razel-py-cli', 'failed (pipx)');
+  const localWhl = join(PKG_ROOT, 'pkg', 'razel_py_cli-0.0.4-py3-none-any.whl');
+  const source = existsSync(localWhl) ? localWhl : 'razel-py-cli';
+  const installCode = await run(pipPath, ['install', source]);
+  if (installCode !== 0) {
+    console.log(yellow(`  ⚠️ razel-py-cli 私有安装失败${runtime.pythonCommand ? ` (python=${runtime.pythonCommand})` : ''}`));
+    contextResult(context, 'razel-py-cli', 'failed (private)');
     return;
   }
 
-  console.log(green('  ✅ razel-py-cli 通过 pipx 安装成功'));
-  refreshLocalToolPaths();
+  ensureWrapper('razel-py-cli', managedCli);
+  console.log(green('  ✅ razel-py-cli 私有安装成功'));
   console.log(dim('  正在初始化...'));
-  let initCode = await run('razel-py-cli', ['init']);
-  if (initCode !== 0 && pipxState.invoke) {
-    initCode = await run(pipxState.invoke.cmd, [...pipxState.invoke.args, 'run', 'razel-py-cli', 'init']);
-  }
-  contextResult(context, 'razel-py-cli', initCode === 0 ? 'ok' : 'installed via pipx (init failed)');
+  const initCode = await run(managedCli, ['init']);
+  contextResult(context, 'razel-py-cli', initCode === 0 ? 'ok (private)' : 'installed (private init failed)');
 }
 
 async function applyConfigWrites(writes) {
@@ -786,6 +832,74 @@ async function collectInteractiveConfigWrites(missing, options = {}) {
     console.log(dim('  已选择跳过 PoPo 服务配置'));
   }
 
+  const toolkitConfig = readToolkitConfig();
+  const configuredDocsDir = getSmartCustomerServiceDocsDir({
+    env: process.env,
+    toolkitConfig,
+  });
+  const configuredVector = getSmartCustomerServiceVectorConfig({
+    env: process.env,
+    toolkitConfig,
+  });
+  console.log(dim('  [smart-customer-service] 可配置外部知识目录；留空则继续使用 skill 自带 docs/'));
+  if (configuredDocsDir) {
+    console.log(dim(`    当前知识目录: ${configuredDocsDir}`));
+  }
+  const wantsDocsDir = await askYesNo('  是否现在配置 smart-customer-service 知识目录？[Y/n] ', false);
+  if (wantsDocsDir) {
+    const docsDir = await ask('    SMART_CS_DOCS_DIR / docsDir absolute path: ');
+    if (docsDir) {
+      writeToolkitConfig((current) => ({
+        ...current,
+        smartCustomerService: {
+          ...(current.smartCustomerService || {}),
+          docsDir,
+          configuredAt: new Date().toISOString(),
+        },
+      }));
+      console.log(green(`  ✅ 已写入 smart-customer-service 知识目录: ${docsDir}`));
+    } else {
+      console.log(dim('  未填写知识目录，将继续使用默认 docs/'));
+    }
+  }
+
+  console.log(dim('  [smart-customer-service] 可选配置向量检索；安装时只记录配置，不立即构建索引'));
+  if (configuredVector.enabled) {
+    console.log(dim(`    当前向量配置: enabled=true, model=${configuredVector.model || '(unset)'}`));
+  }
+  const wantsVector = await askYesNo('  是否现在配置 smart-customer-service 向量模型？[y/N] ', true);
+  if (wantsVector) {
+    console.log(dim('  [Vector] 回车可跳过；若填写完整，首次使用时自动建索引，后续按文档变更增量重建'));
+    const baseUrl = await ask('    SMART_CS_VECTOR_BASE_URL: ');
+    const apiKey = await ask('    SMART_CS_VECTOR_API_KEY: ');
+    const model = await ask('    SMART_CS_VECTOR_MODEL: ');
+    if (baseUrl && apiKey && model) {
+      writeToolkitConfig((current) => ({
+        ...current,
+        smartCustomerService: {
+          ...(current.smartCustomerService || {}),
+          retrieval: {
+            mode: 'auto',
+          },
+          vector: {
+            enabled: true,
+            baseUrl,
+            apiKey,
+            model,
+          },
+          index: {
+            buildStrategy: 'lazy-on-first-use',
+            rebuildStrategy: 'incremental-by-mtime-or-hash',
+          },
+          configuredAt: new Date().toISOString(),
+        },
+      }));
+      console.log(green(`  ✅ 已写入 smart-customer-service 向量配置: ${model}`));
+    } else {
+      console.log(dim('  向量配置未填写完整，保持 grep / 默认检索路径'));
+    }
+  }
+
   rl.close();
   return { writes, skipPopo };
 }
@@ -1076,7 +1190,39 @@ async function runCoreInstall(context) {
     await installCoreDependency(spec, context);
   }
   await installPythonCli(context);
-  await ensureCommand('razel-cli', [NPM, 'install', '-g', '@lcap-delivery/razel-cli@latest'], 'razel-cli', context, ['init']);
+  const managedRazelCli = getManagedCommandPath('razel-cli', { runtimeRoot: CODEWAVE_TOOLKIT_RUNTIME_ROOT });
+  if (managedRazelCli && existsSync(managedRazelCli)) {
+    console.log(dim('  ↺ 已检测到私有 razel-cli 运行时，跳过安装'));
+    ensureWrapper('razel-cli', managedRazelCli);
+    contextResult(context, 'razel-cli', 'reused (private)');
+    return;
+  }
+
+  if (!(await commandExists('npm'))) {
+    console.log(yellow('  ⚠️ 未检测到 npm，无法继续安装私有 razel-cli'));
+    contextResult(context, 'razel-cli', 'blocked (npm missing)');
+    return;
+  }
+
+  const privateNodeRoot = getPrivateNodeRoot();
+  rmSync(privateNodeRoot, { recursive: true, force: true });
+  mkdirSync(privateNodeRoot, { recursive: true });
+
+  const localTgz = join(PKG_ROOT, 'pkg', 'lcap-delivery-razel-cli-0.0.4.tgz');
+  const razelCliSource = existsSync(localTgz) ? localTgz : '@lcap-delivery/razel-cli@latest';
+  console.log(dim('  正在安装私有 razel-cli 运行时...'));
+  const installCode = await run(NPM, ['install', '--prefix', privateNodeRoot, '--no-audit', '--no-fund', razelCliSource]);
+  if (installCode !== 0) {
+    console.log(yellow('  ⚠️ 私有 razel-cli 安装失败'));
+    contextResult(context, 'razel-cli', 'failed (private)');
+    return;
+  }
+
+  ensureWrapper('razel-cli', managedRazelCli);
+  console.log(green('  ✅ razel-cli 私有安装成功'));
+  console.log(dim('  正在初始化...'));
+  const initCode = await run(managedRazelCli, ['init']);
+  contextResult(context, 'razel-cli', initCode === 0 ? 'ok (private)' : 'installed (private init failed)');
 }
 
 async function runConfigBootstrap(context) {
@@ -1313,6 +1459,20 @@ async function main() {
     console.log(`  Skill 就绪情况: ${context.postflight.summary.ok} ok / ${context.postflight.summary.warn} warn / ${context.postflight.summary.fail} fail`);
     console.log('');
   }
+  const toolkitConfig = readToolkitConfig();
+  const smartDocsDir = getSmartCustomerServiceDocsDir({
+    env: process.env,
+    toolkitConfig,
+  });
+  const smartVector = getSmartCustomerServiceVectorConfig({
+    env: process.env,
+    toolkitConfig,
+  });
+  const smartMode = smartVector.enabled ? 'vector(auto)' : 'grep';
+  console.log('  smart-customer-service：');
+  console.log(`    知识目录             : ${smartDocsDir || '内置 docs/'}`);
+  console.log(`    检索模式             : ${smartMode}`);
+  console.log('');
   console.log('  使用方式：');
   console.log(cyan('    razel-py-cli --help'));
   console.log(cyan('    razel-cli --help'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewave-openclaw-installer",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "网易智企 CodeWave OpenClaw 扩展：Skills + CLI 依赖一键安装",
   "type": "module",
   "main": "index.js",
@@ -24,6 +24,7 @@
     "index.js",
     "bin/",
     "skills/",
+    "pkg/",
     "openclaw.plugin.json"
   ],
   "peerDependencies": {

package/skills/acceptance-doc-entry/SKILL.md

@@ -30,9 +30,9 @@ razel-py-cli acceptance-toolkit <command>
 | 命令 | 必填参数 | 说明 |
 |------|---------|------|
 | `parse-template` | `--template <PATH>` | 解析模板结构，创建任务目录 |
-| `plan` | `--task-dir <DIR> --materials <M1> [M2...]` | 解析素材 + LLM 语义映射 |
+| `plan` | `--task-dir <DIR> --materials <M1> [--materials <M2> ...]` | 解析素材 + LLM 语义映射 |
 | `build` | `--task-dir <DIR>` | 生成草稿 DOCX |
-| `revise` | `--task-dir <DIR> --add-materials <M1> [M2...]` | 追加素材 → 重新 plan → 重新 build |
+| `revise` | `--task-dir <DIR> --add-materials <M1> [--add-materials <M2> ...]` | 追加素材 → 重新 plan → 重新 build |
 | `finalize` | `--task-dir <DIR> --confirmed` | 生成正式版（清理草稿标记） |
 
 可选参数：`parse-template` 支持 `--task-id <ID>` 指定任务标识。
@@ -54,7 +54,61 @@ razel-py-cli acceptance-toolkit parse-template --template <TEMPLATE.docx> [--tas
 ### 2. plan — 解析素材 + 映射
 
 ```bash
-razel-py-cli acceptance-toolkit plan --task-dir <TASK_DIR> --materials <M1.docx> <M2.docx>
+razel-py-cli acceptance-toolkit plan --task-dir <TASK_DIR> --materials <M1.docx> --materials <M2.docx>
+```
+
+⚠️ `plan` 的 `--materials` 当前实现为“可重复参数”，不是“一次接收多个文件”。
+也就是说，正确写法是重复传 `--materials`：
+
+```bash
+razel-py-cli acceptance-toolkit plan \
+  --task-dir <TASK_DIR> \
+  --materials /path/a.docx \
+  --materials /path/b.docx \
+  --materials /path/c.docx
+```
+
+如果要把某个目录下的多个文件一起传入，应先在 Agent 或 shell 层展开成多次 `--materials`，不要写成：
+
+```bash
+# 错误示例：当前 CLI 不支持
+razel-py-cli acceptance-toolkit plan --task-dir <TASK_DIR> --materials a.docx b.docx c.docx
+```
+
+### 目录与批量素材规则
+
+当用户给的是“目录”“文件夹”“一批素材”“多个附件”时，Agent 不要把目录路径原样传给 CLI，而要先展开成文件列表，再重复传 `--materials`。
+
+执行规则：
+- 如果用户给的是单个文件，直接传一次 `--materials <FILE>`
+- 如果用户给的是多个文件，按文件数重复传 `--materials`
+- 如果用户给的是目录，先枚举目录下的素材文件，再按文件数重复传 `--materials`
+- 如果目录下包含子目录，默认递归查找常见素材类型；若用户明确只要当前层，则只扫当前层
+- 默认只纳入验收相关常见素材：`.docx`、`.doc`、`.pdf`、`.xlsx`、`.xls`、`.csv`、`.md`、`.txt`
+- 图片、聊天导出、录音转写等非 DOCX 素材，只有在底层 CLI 已支持或前置处理后才传入；否则先由 Agent 提炼或转换，再决定是否进入 `plan`
+- 传参前先去重，并保持稳定顺序（建议按文件名或修改时间排序），避免同一素材重复进入 task
+
+推荐做法：
+
+```bash
+# 用户给目录时，先展开，再重复传参
+razel-py-cli acceptance-toolkit plan \
+  --task-dir <TASK_DIR> \
+  --materials /materials/01-项目方案.docx \
+  --materials /materials/02-实施报告.docx \
+  --materials /materials/03-测试记录.pdf
+```
+
+错误做法：
+
+```bash
+# 错误：不要把目录原样传给 --materials
+razel-py-cli acceptance-toolkit plan --task-dir <TASK_DIR> --materials /materials
+```
+
+```bash
+# 错误：不要把多个文件堆在一个 --materials 后面
+razel-py-cli acceptance-toolkit plan --task-dir <TASK_DIR> --materials a.docx b.docx c.docx
 ```
 
 行为：
@@ -91,9 +145,20 @@ razel-py-cli acceptance-toolkit build --task-dir <TASK_DIR>
 ### 4. revise — 补充素材重新生成
 
 ```bash
-razel-py-cli acceptance-toolkit revise --task-dir <TASK_DIR> --add-materials <M3.docx> [M4.docx...]
+razel-py-cli acceptance-toolkit revise --task-dir <TASK_DIR> --add-materials <M3.docx> [--add-materials <M4.docx> ...]
+```
+
+同理，`revise` 的 `--add-materials` 也需要重复传参：
+
+```bash
+razel-py-cli acceptance-toolkit revise \
+  --task-dir <TASK_DIR> \
+  --add-materials /path/new-1.docx \
+  --add-materials /path/new-2.docx
 ```
 
+如果用户补充的是一个目录，也要先展开成多个文件，再重复传 `--add-materials`，不要把目录路径直接传给 CLI。
+
 行为（三步串联）：
 1. **backup** — 备份当前草稿为 `acceptance-doc.draft.prev.docx`
 2. **plan** — 追加新素材到 input，重新解析全部素材，重新 LLM 映射
@@ -184,7 +249,7 @@ razel-py-cli acceptance-toolkit finalize --task-dir <TASK_DIR> --confirmed
 
 `revise` 命令会自动串联 plan + build，跳过用户确认映射的环节。正确做法：
 
-1. 用户补充素材时，使用 `plan --task-dir <DIR> --materials <全部素材文件>`（包含新旧所有素材）
+1. 用户补充素材时，使用 `plan --task-dir <DIR> --materials <旧素材1> --materials <旧素材2> --materials <新素材...>`（包含新旧所有素材，并重复传 `--materials`）
 2. 展示映射计划，等待用户确认
 3. 用户确认后，再执行 `build`
 

package/skills/smart-customer-service/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: smart-customer-service
-description: 严格依据 docs/ 目录下的产品文档、开发手册等文档，为平台上线后提供技术答疑支持。文档未涵盖的问题一律拒绝回答。激活场景：平台使用、配置、部署、报错排查、技术答疑、产品文档等问题咨询。
+description: 严格依据已配置知识目录中的产品文档、开发手册等文档，为平台上线后提供技术答疑支持。安装时应要求用户配置知识目录，并可选配置向量模型；若未配置，则回退到 skill 自带 docs/ 与 grep 检索。文档未涵盖的问题一律拒绝回答。激活场景：平台使用、配置、部署、报错排查、技术答疑、产品文档等问题咨询。
 version: 1.0.0
 ---
 
@@ -8,18 +8,102 @@ version: 1.0.0
 
 ## 概述
 
-- **职责**：平台上线后技术答疑，仅依据 `smart-customer-service/docs/` 作答
+- **职责**：平台上线后技术答疑，仅依据“已配置知识目录”或 skill 自带 `docs/` 作答
 - **知识边界**：严禁编造、推断；文档未涵盖时明确无法解答并引导补充信息
 - **激活**：用户提及平台使用、配置、部署、报错、故障、技术答疑、产品文档、开发手册等
 
+## 安装与知识目录配置
+
+此 skill 保留内置 `docs/` 作为默认知识源，但在安装或首次启用时，应优先要求用户配置业务文档目录。
+
+### 推荐配置方式
+
+- 用户显式提供知识目录路径，例如：`/data/customer-service-docs`
+- 安装时将该目录记录为固定配置，例如环境变量 `SMART_CS_DOCS_DIR`
+- 若安装器已写入 `~/.openclaw/codewave-toolkit.json`，则从其中的 `smartCustomerService.docsDir` 读取
+- 若安装器已配置向量模型，则从同一配置文件中的 `smartCustomerService.vector` 读取
+- 如果用户配置了多个知识目录，可按顺序逐个检索，或先检索用户指定目录，再回退内置 `docs/`
+
+### 知识源优先级
+
+按以下顺序选择知识源：
+
+1. 用户在当前对话中明确指定的检索目录
+2. 安装时配置的外部知识目录，例如 `SMART_CS_DOCS_DIR`
+3. 安装器落盘的固定配置：`~/.openclaw/codewave-toolkit.json` 中的 `smartCustomerService.docsDir`
+4. skill 自带默认目录：`smart-customer-service/docs/`
+
+## 检索模式与索引策略
+
+### 检索模式优先级
+
+默认使用 `auto` 模式：
+
+1. 若用户明确指定“只用 grep”或“只用向量检索”，按用户要求执行
+2. 若已配置向量模型，优先尝试向量检索
+3. 若向量配置缺失、索引不可用、建索引失败或检索失败，则自动回退到 `grep`
+
+### 向量模型配置
+
+推荐在安装时记录以下配置：
+
+- `SMART_CS_VECTOR_BASE_URL`
+- `SMART_CS_VECTOR_API_KEY`
+- `SMART_CS_VECTOR_MODEL`
+
+也可由安装器写入：
+
+- `~/.openclaw/codewave-toolkit.json`
+  - `smartCustomerService.vector.enabled`
+  - `smartCustomerService.vector.baseUrl`
+  - `smartCustomerService.vector.apiKey`
+  - `smartCustomerService.vector.model`
+
+### 索引构建策略
+
+当向量模型已配置时，索引生命周期按以下规则执行：
+
+1. 安装时只记录知识目录和向量模型配置，不立即建索引
+2. 首次使用时，如果索引不存在，则自动构建索引
+3. 后续每次使用前，检查知识目录变更
+4. 若目录更新时间变化、文件数量变化、或文件 hash 变化，则执行增量重建
+5. 若增量重建失败，则回退到全量重建；若仍失败，则降级为 `grep`
+
+### Agent 执行要求
+
+- 不要因为配置了向量模型，就跳过原有的原文引用校验
+- 向量检索只负责召回候选片段，后续仍需做去重、扩展、强弱匹配和引用核对
+- 若向量召回结果置信度低、来源分散或无明确原文支撑，必须回退到 `grep` 或判定为弱匹配
+- 若用户明确要求“仅依据原文精确匹配”，优先使用 `grep` 或 `grep + 精读`
+
+### 安装时要求
+
+安装或启用本 skill 时，应主动要求用户确认以下内容：
+
+1. 是否已有独立的产品/交付/运维知识库目录
+2. 该目录的绝对路径是什么
+3. 若未提供，则明确告知当前将回退使用 skill 自带 `docs/`
+
+### 未配置时的行为
+
+- 若已配置外部目录，则默认检索外部目录
+- 若外部目录不存在、无权限或为空，则提示用户并回退到 skill 自带 `docs/`
+- 若用户明确要求“只查外部目录”，则外部目录不可用时应直接报出原因，不自动回退
+
+### 推荐提示语
+
+```text
+为保证智能客服回答基于你们自己的产品文档，建议在安装或首次启用时配置知识目录绝对路径。若未配置，将暂时使用 skill 自带 docs/ 目录作为默认知识源。
+```
+
 ## 核心工作流
 
 ```
-1.问题归类 ──→ 2.Query改写 ──→ 3.检索(grep) ──→ 4.后处理(去重+扩展) ──→ 5.判定与分级(判定强/弱/无匹配) ──→ 6.自检与生成(校验原文引用并按模板输出)
-        │          ↑                                                           │
-        │ 非技术    │                                                           │ 强/弱匹配
-        ▼          │                                                           ▼
-    引导话术结束     └─────────────────────────────────────── 无匹配：ReAct 回步骤2，最多3轮；仍无匹配 → 无法回答话术
+1.问题归类 ──→ 2.Query改写 ──→ 3.检索(auto: vector 或 grep) ──→ 4.后处理(去重+扩展) ──→ 5.判定与分级(判定强/弱/无匹配) ──→ 6.自检与生成(校验原文引用并按模板输出)
+        │          ↑                                                                        │
+        │ 非技术    │                                                                        │ 强/弱匹配
+        ▼          │                                                                        ▼
+    引导话术结束     └─────────────────────────────────────────────── 无匹配：ReAct 回步骤2，最多3轮；仍无匹配 → 无法回答话术
 ```
 
 ## 标准工作流步骤说明（内部执行，不对外暴露）
@@ -28,7 +112,7 @@ version: 1.0.0
 |------|----------|------|
 | 1 | **问题归类**：判断是否属于平台技术/使用/配置范畴等技术类问题；**非技术** → 使用引导话术结束（不进入检索）；否则进入步骤 2 | [response-templates 四](templates/response-templates.md#四非技术问题引导)、[指南 步骤1](references/retrieval-guide.md#步骤-1-问题归类) |
 | 2 | **Query 改写**：口语→文档表述、同义词；按需 HyDE / Step-Back / 意图分解 等 | [指南 步骤2](references/retrieval-guide.md#步骤-2-query-改写) |
-| 3 | **检索**：用户明确指定检索目录时，在按指定目录检索；否则默认在 `docs/` 目录下检索 | [指南 步骤3](references/retrieval-guide.md#步骤-3-检索) |
+| 3 | **检索**：用户明确指定检索目录时，按指定目录检索；否则按“当前对话目录 → 安装时配置目录 → 内置 docs/”优先级检索。若已配置向量模型，优先走向量召回；失败时回退 grep | [指南 步骤3](references/retrieval-guide.md#步骤-3-检索) |
 | 4 | **后处理**：去重 + 上下文扩展 | [指南 步骤4](references/retrieval-guide.md#步骤-4-后处理) |
 | 5 | **判定与分级**：已匹配材料与原问题强/弱/无匹配；**无匹配 → ReAct 回步骤2**（最多3轮），仍无匹配→无法回答 | [指南 步骤5](references/retrieval-guide.md#步骤-5-判定与分级)、下表 |
 | 6 | **自检与生成**：严格校验是否有原文引用，按强/弱匹配 模板输出| [response-templates](templates/response-templates.md) |
@@ -56,7 +140,10 @@ version: 1.0.0
 
 ## 附加资源
 
-- **文档路径**：`smart-customer-service/docs/`
+- **默认文档路径**：`smart-customer-service/docs/`
+- **推荐外部知识目录配置项**：`SMART_CS_DOCS_DIR`
+- **推荐向量配置项**：`SMART_CS_VECTOR_BASE_URL`、`SMART_CS_VECTOR_API_KEY`、`SMART_CS_VECTOR_MODEL`
+- **安装器配置文件**：`~/.openclaw/codewave-toolkit.json`
 - 文档目录：[docs/README.md](docs/README.md)
 - 应答模板：[templates/response-templates.md](templates/response-templates.md)
 - 检索指南：[references/retrieval-guide.md](references/retrieval-guide.md)