@baimingtao/lbs-agent 1.0.0 → 1.1.0

package/bin/lbs.js

@@ -2,13 +2,16 @@
 /**
  * lbs — CLI wrapper for Leaving Blank Space Agent.
  *
- * 用户通过 npm install -g @lbs/agent 安装后，
- * 直接使用 `lbs` 命令启动 Agent CLI。
+ * 架构 (对标 Hermes):
+ *   包代码 (只读)        ← npm install -g 安装的目录
+ *   state root (可写)    ← %LOCALAPPDATA%/lbs-agent 或 ~/.lbs-agent
+ *     ├── venv/          ← Python 虚拟环境
+ *     ├── config.yaml    ← 用户配置
+ *     ├── .env           ← API keys
+ *     ├── sessions/      ← 会话数据
+ *     └── ...
  *
- * 工作流程:
- * 1. 检查 Python 虚拟环境是否已创建
- * 2. 如果没有，自动运行 init 脚本
- * 3. 用虚拟环境的 Python 执行 lbs.py
+ * venv 不再建在包目录里，升级/重装 npm 包不会丢失运行时状态。
  */
 
 const { spawn, spawnSync } = require('child_process');
@@ -16,92 +19,169 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
-// 解析项目根目录（npm install 后 bin 的上级是包根目录）
 const PKG_ROOT = path.resolve(__dirname, '..');
-const PYTHON = process.env.LBS_PYTHON || (
-  process.platform === 'win32'
-    ? path.join(PKG_ROOT, 'venv', 'Scripts', 'python.exe')
-    : path.join(PKG_ROOT, 'venv', 'bin', 'python')
-);
-const INIT_FLAG = path.join(PKG_ROOT, '.lbs-initialized');
+
+// ── State Root 解析 (对标 Hermes get_hermes_home) ──────────────
+
+function getStateRoot() {
+  // 1. 环境变量 LBS_HOME 优先
+  const envHome = process.env.LBS_HOME;
+  if (envHome) return path.resolve(envHome);
+
+  // 2. 平台默认: Windows → %LOCALAPPDATA%/lbs-agent, 其他 → ~/.lbs-agent
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(localAppData, 'lbs-agent');
+  }
+  return path.join(os.homedir(), '.lbs-agent');
+}
+
+const STATE_ROOT = getStateRoot();
+const VENV_DIR = path.join(STATE_ROOT, 'venv');
+const VENV_PYTHON = process.platform === 'win32'
+  ? path.join(VENV_DIR, 'Scripts', 'python.exe')
+  : path.join(VENV_DIR, 'bin', 'python');
+const INIT_FLAG = path.join(STATE_ROOT, '.lbs-initialized');
 const INIT_SCRIPT = path.join(PKG_ROOT, 'scripts', 'init.js');
 
-// 检查是否已初始化
+// ── 颜色与图标 (对标 Hermes banner/colors) ─────────────────────
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gold: '\x1b[1;38;2;255;191;0m',
+};
+
+function supportsColor() {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.TERM === 'dumb') return false;
+  return process.stdout.isTTY;
+}
+
+function paint(text, ...colors) {
+  if (!supportsColor()) return text;
+  return colors.join('') + text + C.reset;
+}
+
+// ── ASCII Logo ─────────────────────────────────────────────────
+
+const LOGO = String.raw`
+ ${paint('██╗', C.gold)}  ${paint('██╗', C.gold)}${paint('███████╗', C.cyan)}${paint('██████╗', C.cyan)}  ${paint('██╗', C.gold)}   ${paint('██╗', C.gold)}${paint('███████╗', C.cyan)}${paint('███████╗', C.cyan)}
+ ${paint('██║', C.gold)}  ${paint('██║', C.gold)}${paint('██╔════╝', C.cyan)}${paint('██╔══██╗', C.cyan)}${paint('████╗', C.gold)} ${paint('████║', C.gold)}${paint('██╔════╝', C.cyan)}${paint('██╔════╝', C.cyan)}
+ ${paint('███████║', C.cyan)}${paint('█████╗', C.cyan)}  ${paint('██████╔╝', C.cyan)}${paint('██╔████╔██║', C.gold)}${paint('█████╗', C.cyan)}  ${paint('███████╗', C.gold)}${paint('█████╗', C.cyan)}
+ ${paint('██╔══██║', C.cyan)}${paint('██╔══╝', C.cyan)}  ${paint('██╔══██╗', C.cyan)}${paint('██║╚██╔╝██║', C.gold)}${paint('██╔══╝', C.cyan)}  ${paint('╚════██║', C.gold)}${paint('╚════╝', C.cyan)}
+ ${paint('██║', C.gold)}  ${paint('██║', C.gold)}${paint('███████╗', C.cyan)}${paint('██║', C.gold)}  ${paint('██║', C.gold)}${paint('██║', C.gold)} ${paint('╚═╝', C.gold)} ${paint('██║', C.gold)}${paint('███████╗', C.gold)}${paint('███████║', C.cyan)}      ${paint('██║', C.gold)}  ${paint('██║', C.gold)}${paint('╚██████╔╝', C.gold)}
+ ${paint('╚═╝', C.gold)}  ${paint('╚═╝', C.gold)}${paint('╚══════╝', C.dim)}${paint('╚═╝', C.gold)}  ${paint('╚═╝', C.gold)}${paint('╚═╝', C.gold)}     ${paint('╚═╝', C.gold)}${paint('╚══════╝', C.dim)}${paint('╚══════╝', C.dim)}      ${paint('╚═╝', C.gold)}  ${paint('╚═╝', C.gold)} ${paint('╚═════╝', C.dim)}
+`;
+
+function printBanner() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
+  console.log();
+  console.log(LOGO);
+  console.log(paint(`  LBS Agent v${pkg.version}`, C.bold, C.gold));
+  console.log(paint(`  Leaving Blank Space Agent — 多 Agent 编排框架`, C.dim));
+  console.log();
+}
+
+// ── 初始化检查 ─────────────────────────────────────────────────
+
 function isInitialized() {
-  return fs.existsSync(INIT_FLAG) && fs.existsSync(PYTHON);
+  return fs.existsSync(INIT_FLAG) && fs.existsSync(VENV_PYTHON);
 }
 
-// 首次运行自动初始化
 function ensureInitialized() {
   if (isInitialized()) return true;
 
-  console.log('🔧 首次运行，正在初始化 LBS Agent...');
-  console.log('   创建 Python 虚拟环境 + 安装依赖（约 1-2 分钟）\n');
+  console.log(paint('⚙ ', C.gold) + paint('首次运行，正在初始化 LBS Agent...', C.bold));
+  console.log(paint('   状态目录: ', C.dim) + paint(STATE_ROOT, C.cyan));
+  console.log(paint('   创建 Python 虚拟环境 + 安装依赖（约 1-2 分钟）', C.dim));
+  console.log();
 
   if (!fs.existsSync(INIT_SCRIPT)) {
-    console.error('❌ 初始化脚本不存在: ' + INIT_SCRIPT);
-    console.error('   请手动运行: python -m venv venv && venv/bin/pip install -r requirements.txt');
+    console.error(paint('✖ ', C.red) + '初始化脚本不存在: ' + INIT_SCRIPT);
     return false;
   }
 
   const result = spawnSync('node', [INIT_SCRIPT], {
     cwd: PKG_ROOT,
     stdio: 'inherit',
-    env: { ...process.env, LBS_PKG_ROOT: PKG_ROOT },
+    env: { ...process.env, LBS_STATE_ROOT: STATE_ROOT, LBS_PKG_ROOT: PKG_ROOT },
   });
 
   if (result.status !== 0) {
-    console.error('\n❌ 初始化失败。请手动运行:');
-    console.error('   python -m venv venv');
-    console.error('   ' + (process.platform === 'win32' ? 'venv\\Scripts\\pip' : 'venv/bin/pip') + ' install -r requirements.txt');
+    console.error(paint('\n✖ ', C.red) + '初始化失败');
     return false;
   }
 
-  console.log('\n✅ 初始化完成！\n');
+  console.log(paint('\n✓ ', C.green) + paint('初始化完成！', C.bold, C.green));
+  console.log();
   return true;
 }
 
-// 主逻辑
+// ── 主逻辑 ─────────────────────────────────────────────────────
+
 const args = process.argv.slice(2);
+const subcmd = args[0];
 
-// 特殊命令：不需要初始化
-if (args[0] === 'init' || args[0] === '--init') {
+// 不需要初始化的命令
+if (subcmd === 'init' || subcmd === '--init') {
+  printBanner();
   if (fs.existsSync(INIT_SCRIPT)) {
-    const result = spawnSync('node', [INIT_SCRIPT], { cwd: PKG_ROOT, stdio: 'inherit' });
+    const result = spawnSync('node', [INIT_SCRIPT], {
+      cwd: PKG_ROOT,
+      stdio: 'inherit',
+      env: { ...process.env, LBS_STATE_ROOT: STATE_ROOT, LBS_PKG_ROOT: PKG_ROOT },
+    });
     process.exit(result.status || 0);
   }
-  console.error('初始化脚本不存在');
+  console.error(paint('✖ ', C.red) + '初始化脚本不存在');
   process.exit(1);
 }
 
-if (args[0] === 'doctor' || args[0] === '--doctor') {
-  // doctor 不需要完整初始化，只需 Python 存在
-  const sysPython = process.env.LBS_PYTHON || (
-    process.platform === 'win32' ? 'python' : 'python3'
-  );
+if (subcmd === 'version' || subcmd === '--version' || subcmd === '-v') {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
+  console.log(`lbs ${pkg.version}`);
+  process.exit(0);
+}
+
+if (subcmd === 'doctor' || subcmd === '--doctor') {
+  // doctor 用系统 Python，不需要完整初始化
+  const sysPython = process.env.LBS_PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
   const result = spawnSync(sysPython, [path.join(PKG_ROOT, 'lbs.py'), 'doctor'], {
-    cwd: PKG_ROOT,
+    cwd: process.cwd(),
     stdio: 'inherit',
+    env: { ...process.env, LBS_HOME: STATE_ROOT },
   });
   process.exit(result.status || 0);
 }
 
-if (args[0] === 'version' || args[0] === '--version' || args[0] === '-v') {
-  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
-  console.log(`lbs ${pkg.version}`);
-  process.exit(0);
+if (subcmd === 'setup' || subcmd === '--setup') {
+  // setup 需要初始化
+  if (!ensureInitialized()) process.exit(1);
+  const result = spawnSync(VENV_PYTHON, [path.join(PKG_ROOT, 'lbs.py'), 'setup', ...args.slice(1)], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: { ...process.env, LBS_HOME: STATE_ROOT },
+  });
+  process.exit(result.status || 0);
 }
 
-// 确保初始化
+// 默认：确保初始化后用 venv Python 执行
 if (!ensureInitialized()) {
   process.exit(1);
 }
 
-// 用虚拟环境 Python 执行
-const child = spawn(PYTHON, [path.join(PKG_ROOT, 'lbs.py'), ...args], {
+const child = spawn(VENV_PYTHON, [path.join(PKG_ROOT, 'lbs.py'), ...args], {
   cwd: process.cwd(),
   stdio: 'inherit',
-  env: process.env,
+  env: { ...process.env, LBS_HOME: STATE_ROOT },
 });
 
 child.on('close', (code) => {

package/config/state_root.py

@@ -2,20 +2,38 @@
 
 提供统一的 resolve_state_root() 函数，
 被多个模块用于定位 session/memory/cron 等运行时数据的存储位置。
+
+架构对标 Hermes:
+  包代码 (只读)      ← pip/npm 安装的目录
+  state root (可写)  ← %LOCALAPPDATA%/lbs-agent (Windows) 或 ~/.lbs-agent (其他)
+
+这样 venv/config/sessions 全在 state root,
+升级/重装包不会丢失运行时状态。
 """
 
 from __future__ import annotations
 
 import os
+import sys
 from pathlib import Path
 
 
+def _platform_default_state_root() -> Path:
+    """返回平台默认的 state root 路径 (对标 Hermes _get_platform_default_hermes_home)。"""
+    if sys.platform == "win32":
+        local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
+        base = Path(local_appdata) if local_appdata else Path.home() / "AppData" / "Local"
+        return base / "lbs-agent"
+    return Path.home() / ".lbs-agent"
+
+
 def resolve_state_root(project_root: str | Path | None = None) -> Path:
     """解析状态根目录。优先级：
 
     1. LBS_HOME 环境变量
     2. project_root / .lbs-agent（如果传了 project_root）
-    3. 默认：~/.lbs-agent
+    3. 平台默认：Windows → %LOCALAPPDATA%/lbs-agent, 其他 → ~/.lbs-agent
+
     返回 Path 对象，调用者可直接使用 .exists() / / 等 Path 操作。
     """
     env = os.environ.get("LBS_HOME")
@@ -25,4 +43,4 @@ def resolve_state_root(project_root: str | Path | None = None) -> Path:
     if project_root:
         return Path(str(project_root)).resolve() / ".lbs-agent"
 
-    return Path.home() / ".lbs-agent"
+    return _platform_default_state_root()

package/interfaces/cli/_impl/commands/setup.py

@@ -0,0 +1,519 @@
+"""LBS Agent 交互式配置向导 (对标 Hermes setup wizard)。
+
+用法:
+  lbs setup             — 完整向导
+  lbs setup model       — 只配置模型/供应商
+  lbs setup agent       — 只配置 Agent 参数
+  lbs setup keys        — 只配置 API Keys
+
+配置写入 state_root (LBS_HOME)，不修改包目录里的出厂 models.yaml/agents.yaml。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+# ═══════════════════════════════════════════════════════════════
+# State Root 解析 (不 import config.state_root, 架构边界要求)
+# ═══════════════════════════════════════════════════════════════
+
+def _resolve_state_root() -> Path:
+    """解析状态根目录。优先级: LBS_HOME 环境变量 → 平台默认。"""
+    env = os.environ.get("LBS_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+    if sys.platform == "win32":
+        local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
+        base = Path(local_appdata) if local_appdata else Path.home() / "AppData" / "Local"
+        return base / "lbs-agent"
+    return Path.home() / ".lbs-agent"
+
+
+# ═══════════════════════════════════════════════════════════════
+# 颜色与 UI 工具 (对标 Hermes colors.py)
+# ═══════════════════════════════════════════════════════════════
+
+class _C:
+    """ANSI 颜色码。"""
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    GOLD = "\033[1;38;2;255;191;0m"
+
+
+def _use_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    return sys.stdout.isatty()
+
+
+def _paint(text: str, *codes: str) -> str:
+    if not _use_color():
+        return text
+    return "".join(codes) + text + _C.RESET
+
+
+def _header(title: str) -> None:
+    """打印章节标题 (带边框)。"""
+    print()
+    print(_paint("  ┌─────────────────────────────────────────────────────────┐", _C.MAGENTA))
+    print(_paint("  │ ", _C.MAGENTA) + _paint(f"⚙  LBS Setup — {title}", _C.BOLD, _C.GOLD)
+          + _paint(" " * max(0, 47 - len(title) - 14) + "│", _C.MAGENTA))
+    print(_paint("  └─────────────────────────────────────────────────────────┘", _C.MAGENTA))
+    print()
+
+
+def _info(msg: str) -> None:
+    print(_paint("  ℹ  ", _C.BLUE) + msg)
+
+
+def _success(msg: str) -> None:
+    print(_paint("  ✓  ", _C.GREEN) + _paint(msg, _C.GREEN))
+
+
+def _warn(msg: str) -> None:
+    print(_paint("  ⚠  ", _C.YELLOW) + _paint(msg, _C.YELLOW))
+
+
+def _error(msg: str) -> None:
+    print(_paint("  ✖  ", _C.RED) + _paint(msg, _C.RED))
+
+
+def _prompt(label: str, default: str = "") -> str:
+    """带默认值的输入提示。"""
+    suffix = f" [{default}]" if default else ""
+    try:
+        val = input(_paint(f"  ▸ {label}{suffix}: ", _C.CYAN)).strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return default
+    return val or default
+
+
+def _prompt_choice(label: str, options: list[str], default: str = "") -> str:
+    """带选项列表的输入提示。"""
+    print(_paint(f"  ▸ {label}", _C.CYAN))
+    for i, opt in enumerate(options, 1):
+        marker = _paint("→", _C.GREEN) if opt == default else " "
+        print(f"    {marker} {i}. {opt}")
+    val = _prompt("选择编号或直接输入", default)
+    if val.isdigit():
+        idx = int(val) - 1
+        if 0 <= idx < len(options):
+            return options[idx]
+    return val
+
+
+def _prompt_password(label: str) -> str:
+    """密码输入（不回显）。"""
+    import getpass
+    try:
+        val = getpass.getpass(_paint(f"  ▸ {label}: ", _C.CYAN))
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return ""
+    return val.strip()
+
+
+def _prompt_yes_no(label: str, default: bool = True) -> bool:
+    """是/否选择。"""
+    suffix = "Y/n" if default else "y/N"
+    val = _prompt(f"{label} ({suffix})", "y" if default else "n")
+    return val.lower().startswith("y")
+
+
+# ═══════════════════════════════════════════════════════════════
+# 配置文件读写
+# ═══════════════════════════════════════════════════════════════
+
+def _state_root() -> Path:
+    return _resolve_state_root()
+
+
+def _models_yaml_path() -> Path:
+    """用户级 models.yaml 覆盖文件。"""
+    return _state_root() / "models.override.yaml"
+
+
+def _agents_yaml_path() -> Path:
+    """用户级 agents.yaml 覆盖文件。"""
+    return _state_root() / "agents.override.yaml"
+
+
+def _env_path() -> Path:
+    """.env 文件，存 API keys。"""
+    return _state_root() / ".env"
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if not yaml or not path.exists():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception:
+        return {}
+
+
+def _save_yaml(path: Path, data: dict[str, Any]) -> None:
+    if not yaml:
+        _error("PyYAML 未安装，无法保存配置")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+
+def _load_env() -> dict[str, str]:
+    env: dict[str, str] = {}
+    path = _env_path()
+    if path.exists():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, _, val = line.partition("=")
+                env[key.strip()] = val.strip()
+    return env
+
+
+def _save_env(env: dict[str, str]) -> None:
+    path = _env_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [f"{k}={v}" for k, v in sorted(env.items())]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+# ═══════════════════════════════════════════════════════════════
+# 内置供应商目录
+# ═══════════════════════════════════════════════════════════════
+
+_PROVIDERS = {
+    "openai": {
+        "display": "OpenAI",
+        "env_key": "OPENAI_API_KEY",
+        "base_url": "https://api.openai.com/v1",
+        "api_mode": "chat_completions",
+        "models": ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-4.1", "o3-mini"],
+    },
+    "anthropic": {
+        "display": "Anthropic",
+        "env_key": "ANTHROPIC_API_KEY",
+        "base_url": "https://api.anthropic.com",
+        "api_mode": "anthropic_messages",
+        "models": ["claude-opus-4.6", "claude-sonnet-4.6", "claude-sonnet-4.5", "claude-haiku-4.5"],
+    },
+    "deepseek": {
+        "display": "DeepSeek",
+        "env_key": "DEEPSEEK_API_KEY",
+        "base_url": "https://api.deepseek.com/v1",
+        "api_mode": "chat_completions",
+        "models": ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-chat", "deepseek-reasoner"],
+    },
+    "openrouter": {
+        "display": "OpenRouter (聚合 300+ 模型)",
+        "env_key": "OPENROUTER_API_KEY",
+        "base_url": "https://openrouter.ai/api/v1",
+        "api_mode": "chat_completions",
+        "models": ["openai/gpt-5.5", "anthropic/claude-sonnet-4.6", "google/gemini-3-pro-preview"],
+    },
+    "qwen": {
+        "display": "通义千问 (阿里云)",
+        "env_key": "QWEN_API_KEY",
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "api_mode": "chat_completions",
+        "models": ["qwen3.7-max", "qwen3.6-plus", "qwen3.5-plus", "qwen-max", "qwen-plus"],
+    },
+    "zai": {
+        "display": "智谱 AI (GLM)",
+        "env_key": "ZAI_API_KEY",
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "api_mode": "chat_completions",
+        "models": ["glm-5.2", "glm-5.1", "glm-5", "glm-4.7", "glm-4-plus", "glm-4-flash"],
+    },
+    "gemini": {
+        "display": "Google Gemini",
+        "env_key": "GEMINI_API_KEY",
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "api_mode": "chat_completions",
+        "models": ["gemini-3-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro"],
+    },
+    "kimi": {
+        "display": "Kimi (月之暗面)",
+        "env_key": "KIMI_API_KEY",
+        "base_url": "https://api.moonshot.cn/v1",
+        "api_mode": "chat_completions",
+        "models": ["kimi-k2.6", "kimi-k2.5", "moonshot-v1-128k"],
+    },
+    "custom": {
+        "display": "自定义供应商 (兼容 OpenAI/Anthropic API)",
+        "env_key": "",
+        "base_url": "",
+        "api_mode": "chat_completions",
+        "models": [],
+    },
+}
+
+
+# ═══════════════════════════════════════════════════════════════
+# Step 1: 模型 & 供应商配置
+# ═══════════════════════════════════════════════════════════════
+
+def setup_model_provider() -> None:
+    """配置推理供应商和默认模型。"""
+    _header("模型 & 供应商")
+
+    provider_keys = list(_PROVIDERS.keys())
+    provider_displays = [f"{_PROVIDERS[k]['display']}" for k in provider_keys]
+
+    _info("选择你的 LLM 供应商（决定 API 端点和认证方式）")
+    _info(f"   文档: https://lbs-agent.nousresearch.com/docs/providers")
+    print()
+
+    choice = _prompt_choice("选择供应商", provider_displays, default=provider_displays[0])
+    idx = provider_displays.index(choice) if choice in provider_displays else 0
+    provider_key = provider_keys[idx]
+    provider = _PROVIDERS[provider_key]
+
+    print()
+    _info(f"已选: {provider['display']}")
+
+    # 输入 API Key
+    env = _load_env()
+    existing_key = env.get(provider["env_key"], "") if provider["env_key"] else ""
+    if provider["env_key"]:
+        print()
+        if existing_key:
+            _info(f"已有 API Key: {existing_key[:8]}...{existing_key[-4:]}")
+            if not _prompt_yes_no("是否更换 Key?", default=False):
+                pass
+            else:
+                key = _prompt_password(f"输入 {provider['display']} API Key")
+                if key:
+                    env[provider["env_key"]] = key
+        else:
+            key = _prompt_password(f"输入 {provider['display']} API Key")
+            if key:
+                env[provider["env_key"]] = key
+                _success("API Key 已保存")
+
+    # 自定义供应商需要额外信息
+    if provider_key == "custom":
+        print()
+        custom_name = _prompt("供应商名称 (如 myapi)", "custom")
+        custom_base = _prompt("API Base URL", "")
+        custom_mode = _prompt_choice("API 模式", ["chat_completions", "anthropic_messages"], "chat_completions")
+        custom_key_env = f"{custom_name.upper()}_API_KEY"
+        key = _prompt_password(f"输入 API Key")
+        if key:
+            env[custom_key_env] = key
+
+        provider = {
+            "display": custom_name,
+            "env_key": custom_key_env,
+            "base_url": custom_base,
+            "api_mode": custom_mode,
+            "models": [],
+        }
+        provider_key = custom_name
+
+    # 选择模型
+    print()
+    models = provider["models"]
+    if models:
+        _info(f"可选模型:")
+        model = _prompt_choice("选择默认模型", models, default=models[0])
+    else:
+        model = _prompt("输入模型名称", "")
+
+    # 写入 override YAML
+    override = _load_yaml(_models_yaml_path())
+
+    # 写入 default
+    override["default"] = {
+        "provider": provider_key,
+        "model": model,
+    }
+
+    # 写入 builtin/custom 供应商
+    if provider_key == "custom" and provider_key not in _PROVIDERS:
+        custom_section = override.setdefault("custom", {})
+        custom_section[provider_key] = {
+            "display_name": provider["display"],
+            "base_url": provider["base_url"],
+            "api_mode": provider["api_mode"],
+            "api_key": f"${{{provider['env_key']}}}" if provider["env_key"] else "",
+            "models": [model] if model else [],
+        }
+    else:
+        builtin_section = override.setdefault("builtin", {})
+        if provider_key not in builtin_section:
+            builtin_section[provider_key] = {
+                "api_key": f"${{{provider['env_key']}}}" if provider["env_key"] else "",
+                "base_url": provider["base_url"],
+                "api_mode": provider["api_mode"],
+            }
+
+    _save_yaml(_models_yaml_path(), override)
+    _save_env(env)
+
+    print()
+    _success(f"模型配置已保存: {_models_yaml_path()}")
+    _success(f"默认模型: {provider_key} / {model}")
+
+
+# ═══════════════════════════════════════════════════════════════
+# Step 2: Agent 参数
+# ═══════════════════════════════════════════════════════════════
+
+def setup_agent_settings() -> None:
+    """配置 Agent 运行参数。"""
+    _header("Agent 设置")
+
+    override = _load_yaml(_agents_yaml_path())
+    global_cfg = override.get("global", {})
+
+    _info("配置 Agent 全局参数")
+    print()
+
+    max_concurrent = int(_prompt("最大并发 Agent 数", str(global_cfg.get("max_concurrent", 3))))
+    max_depth = int(_prompt("最大嵌套深度", str(global_cfg.get("max_spawn_depth", 1))))
+    default_timeout = int(_prompt("默认超时 (秒)", str(global_cfg.get("default_timeout", 600))))
+    auto_approve = _prompt_yes_no("自动批准危险操作 (不推荐)", default=global_cfg.get("auto_approve_dangerous", False))
+
+    override["global"] = {
+        "max_concurrent": max_concurrent,
+        "max_spawn_depth": max_depth,
+        "default_timeout": default_timeout,
+        "auto_approve_dangerous": auto_approve,
+    }
+
+    _save_yaml(_agents_yaml_path(), override)
+    print()
+    _success(f"Agent 配置已保存: {_agents_yaml_path()}")
+
+
+# ═══════════════════════════════════════════════════════════════
+# Step 3: API Keys 管理
+# ═══════════════════════════════════════════════════════════════
+
+def setup_keys() -> None:
+    """配置所有 API Keys。"""
+    _header("API Keys")
+
+    env = _load_env()
+
+    known_keys = [
+        ("OPENAI_API_KEY", "OpenAI"),
+        ("ANTHROPIC_API_KEY", "Anthropic"),
+        ("DEEPSEEK_API_KEY", "DeepSeek"),
+        ("OPENROUTER_API_KEY", "OpenRouter"),
+        ("QWEN_API_KEY", "通义千问"),
+        ("ZAI_API_KEY", "智谱 AI"),
+        ("GEMINI_API_KEY", "Google Gemini"),
+        ("KIMI_API_KEY", "Kimi"),
+    ]
+
+    for env_key, display_name in known_keys:
+        existing = env.get(env_key, "")
+        if existing:
+            _info(f"{display_name}: {existing[:8]}...{existing[-4:]}")
+            if not _prompt_yes_no(f"  更换?", default=False):
+                continue
+        else:
+            if not _prompt_yes_no(f"配置 {display_name} Key?", default=False):
+                continue
+        key = _prompt_password(f"输入 {display_name} API Key")
+        if key:
+            env[env_key] = key
+            _success(f"{display_name} Key 已保存")
+        print()
+
+    _save_env(env)
+    _success(f"Keys 已保存到: {_env_path()}")
+
+
+# ═══════════════════════════════════════════════════════════════
+# 主入口
+# ═══════════════════════════════════════════════════════════════
+
+SECTIONS = [
+    ("model", "模型 & 供应商", setup_model_provider),
+    ("agent", "Agent 设置", setup_agent_settings),
+    ("keys", "API Keys", setup_keys),
+]
+
+
+def run_setup(section: str | None = None) -> int:
+    """运行配置向导。"""
+    # 确保 state root 存在
+    root = _state_root()
+    root.mkdir(parents=True, exist_ok=True)
+
+    print()
+    print(_paint("  ┌─────────────────────────────────────────────────────────┐", _C.GOLD))
+    print(_paint("  │ ", _C.GOLD) + _paint("⚙  LBS Agent Setup Wizard", _C.BOLD, _C.GOLD)
+          + _paint("                              │", _C.GOLD))
+    print(_paint("  └─────────────────────────────────────────────────────────┘", _C.GOLD))
+    print()
+    _info(f"配置目录: {root}")
+    print()
+
+    if section:
+        # 只运行指定 section
+        for key, label, func in SECTIONS:
+            if key == section:
+                func()
+                _print_done()
+                return 0
+        _error(f"未知配置项: {section}")
+        _info(f"可用项: {', '.join(k for k, _, _ in SECTIONS)}")
+        return 1
+
+    # 完整向导
+    for key, label, func in SECTIONS:
+        func()
+
+    _print_done()
+    return 0
+
+
+def _print_done() -> None:
+    print()
+    print(_paint("  ┌─────────────────────────────────────────────────────────┐", _C.GREEN))
+    print(_paint("  │ ", _C.GREEN) + _paint("✅ 配置完成！", _C.BOLD, _C.GREEN)
+          + _paint("                                            │", _C.GREEN))
+    print(_paint("  │                                                         │", _C.GREEN))
+    print(_paint("  │ ", _C.GREEN) + _paint("配置文件:", _C.BOLD) + paint_path(_models_yaml_path()) + _paint(" │", _C.GREEN))
+    print(_paint("  │ ", _C.GREEN) + _paint("密钥文件:", _C.BOLD) + paint_path(_env_path()) + _paint(" │", _C.GREEN))
+    print(_paint("  │                                                         │", _C.GREEN))
+    print(_paint("  │ ", _C.GREEN) + _paint("现在可以运行:", _C.BOLD) + paint_cmd(" lbs status") + _paint("                    │", _C.GREEN))
+    print(_paint("  └─────────────────────────────────────────────────────────┘", _C.GREEN))
+    print()
+
+
+def paint_path(p: Path) -> str:
+    s = str(p)
+    if len(s) > 40:
+        s = "..." + s[-37:]
+    return _paint(s, _C.CYAN)
+
+
+def paint_cmd(cmd: str) -> str:
+    return _paint(cmd, _C.CYAN, _C.BOLD)

package/interfaces/cli/_impl/main.py

@@ -50,6 +50,7 @@ from interfaces.cli._impl.commands.cron import (
 )
 from interfaces.cli._impl.commands.soul import cmd_soul_list, cmd_soul_switch, cmd_soul_show
 from interfaces.cli._impl.commands.smoke_test import main as smoke_main
+from interfaces.cli._impl.commands.setup import run_setup
 
 
 # --- 命令注册表 ---
@@ -657,6 +658,12 @@ def _cmd_doctor_handler(config: Any) -> int:
     return 1 if report.get("failed", 0) else 0
 
 
+def _cmd_setup_handler(_config: Any) -> int:
+    """交互式配置向导。"""
+    section = sys.argv[2] if len(sys.argv) > 2 else None
+    return run_setup(section)
+
+
 # --- 注册表实例 ---
 
 _REGISTRY = CommandRegistry()
@@ -689,6 +696,7 @@ def _build_registry() -> None:
     _REGISTRY.register("gateway", _cmd_gateway_handler, help="网关操作")
     _REGISTRY.register("doctor", _cmd_doctor_handler, help="诊断配置问题")
     _REGISTRY.register("smoke-test", lambda _config: smoke_main(), aliases=["smoke"], help="快速冒烟测试")
+    _REGISTRY.register("setup", _cmd_setup_handler, help="交互式配置向导（model/agent/keys）")
 
 
 # --- 入口 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baimingtao/lbs-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/init.js

@@ -2,15 +2,13 @@
 /**
  * LBS Agent 初始化脚本 — 跨平台 (Windows / macOS / Linux)
  *
- * 功能:
- * 1. 检测系统 Python (3.10+)
- * 2. 创建虚拟环境 venv/
- * 3. 安装 requirements.txt 依赖
- * 4. 创建 .lbs-initialized 标记文件
+ * 架构 (对标 Hermes):
+ *   venv 建在 state root (%LOCALAPPDATA%/lbs-agent/venv), 不在包目录
+ *   config/sessions 也在 state root, npm 升级不丢数据
  *
- * 用法:
- *   node scripts/init.js          # 正常初始化
- *   LBS_PKG_ROOT=/path node scripts/init.js  # 指定项目根目录
+ * 环境变量:
+ *   LBS_STATE_ROOT  ← bin/lbs.js 传入的 state root 路径
+ *   LBS_PKG_ROOT    ← bin/lbs.js 传入的包根路径
  */
 
 const { spawnSync } = require('child_process');
@@ -19,31 +17,48 @@ const fs = require('fs');
 const os = require('os');
 
 const PKG_ROOT = process.env.LBS_PKG_ROOT || path.resolve(__dirname, '..');
-const VENV_DIR = path.join(PKG_ROOT, 'venv');
-const INIT_FLAG = path.join(PKG_ROOT, '.lbs-initialized');
+const STATE_ROOT = process.env.LBS_STATE_ROOT || path.join(os.homedir(), '.lbs-agent');
+const VENV_DIR = path.join(STATE_ROOT, 'venv');
+const INIT_FLAG = path.join(STATE_ROOT, '.lbs-initialized');
 const REQUIREMENTS = path.join(PKG_ROOT, 'requirements.txt');
 
 const isWin = process.platform === 'win32';
 const PYTHON = isWin ? path.join(VENV_DIR, 'Scripts', 'python.exe') : path.join(VENV_DIR, 'bin', 'python');
 const PIP = isWin ? path.join(VENV_DIR, 'Scripts', 'pip.exe') : path.join(VENV_DIR, 'bin', 'pip');
 
-function log(msg) { console.log(msg); }
-function err(msg) { console.error(msg); }
+// ── 颜色 ───────────────────────────────────────────────────────
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
+  blue: '\x1b[34m', magenta: '\x1b[35m', cyan: '\x1b[36m',
+  gold: '\x1b[1;38;2;255;191;0m',
+};
+
+function paint(text, ...colors) {
+  if (process.env.NO_COLOR || process.env.TERM === 'dumb' || !process.stdout.isTTY) return text;
+  return colors.join('') + text + C.reset;
+}
+
+// ── 工具函数 ───────────────────────────────────────────────────
 
 function run(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, {
+  return spawnSync(cmd, args, {
     stdio: opts.silent ? 'pipe' : 'inherit',
     encoding: 'utf-8',
     shell: isWin,
     ...opts,
   });
-  return result;
 }
 
-// ── Step 1: 检测系统 Python ──────────────────────────
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// ── Step 1: 检测系统 Python ────────────────────────────────────
 
 function findSystemPython() {
-  log('🔍 检测系统 Python...');
+  console.log(paint('  🔍 ', C.gold) + '检测系统 Python...');
 
   const candidates = isWin
     ? ['python', 'python3', 'py -3']
@@ -53,102 +68,138 @@ function findSystemPython() {
     const result = run(cmd, ['--version'], { silent: true, shell: isWin });
     if (result.status === 0) {
       const version = (result.stdout || result.stderr || '').trim();
-      log(`  ✓ ${cmd}: ${version}`);
+      console.log(paint('  ✓ ', C.green) + `${cmd}: ${version}`);
 
-      // 检查版本 >= 3.10
       const match = version.match(/(\d+)\.(\d+)/);
       if (match) {
         const major = parseInt(match[1]);
         const minor = parseInt(match[2]);
-        if (major >= 3 && minor >= 10) {
-          return cmd;
-        }
+        if (major >= 3 && minor >= 10) return cmd;
       }
-      log(`  ⚠ 版本低于 3.10，继续寻找...`);
+      console.log(paint('  ⚠ ', C.yellow) + '版本低于 3.10，继续寻找...');
     }
   }
 
-  err('\n❌ 未找到 Python 3.10+');
-  err('   请安装 Python:');
-  err('   Windows: https://www.python.org/downloads/');
-  err('   macOS:   brew install python@3.12');
-  err('   Linux:   sudo apt install python3 python3-venv');
+  console.error(paint('\n  ✖ ', C.red) + '未找到 Python 3.10+');
+  console.error(paint('     ', C.dim) + 'Windows: https://www.python.org/downloads/');
+  console.error(paint('     ', C.dim) + 'macOS:   brew install python@3.12');
+  console.error(paint('     ', C.dim) + 'Linux:   sudo apt install python3 python3-venv');
   return null;
 }
 
-// ── Step 2: 创建虚拟环境 ─────────────────────────────
+// ── Step 2: 创建 state root + venv ─────────────────────────────
 
 function createVenv(sysPython) {
   if (fs.existsSync(PYTHON)) {
-    log('✓ 虚拟环境已存在，跳过创建');
+    console.log(paint('  ✓ ', C.green) + '虚拟环境已存在，跳过创建');
     return true;
   }
 
-  log('📦 创建 Python 虚拟环境...');
+  // 确保 state root 存在
+  ensureDir(STATE_ROOT);
+  console.log(paint('  📦 ', C.gold) + `创建 Python 虚拟环境 → ${paint(STATE_ROOT + '/venv', C.cyan)}`);
+
   const result = run(sysPython, ['-m', 'venv', VENV_DIR]);
   if (result.status !== 0 || !fs.existsSync(PYTHON)) {
-    err('❌ 创建虚拟环境失败');
+    console.error(paint('  ✖ ', C.red) + '创建虚拟环境失败');
     return false;
   }
-  log('  ✓ venv/ 已创建');
+  console.log(paint('  ✓ ', C.green) + 'venv 已创建');
   return true;
 }
 
-// ── Step 3: 安装依赖 ─────────────────────────────────
+// ── Step 3: 安装依赖 ───────────────────────────────────────────
 
 function installDeps() {
   if (!fs.existsSync(REQUIREMENTS)) {
-    err('❌ requirements.txt 不存在: ' + REQUIREMENTS);
+    console.error(paint('  ✖ ', C.red) + 'requirements.txt 不存在: ' + REQUIREMENTS);
     return false;
   }
 
-  log('📥 安装 Python 依赖 (可能需要 1-2 分钟)...');
-  const pipCmd = isWin ? PIP : PIP;
-  const result = run(pipCmd, ['install', '-r', REQUIREMENTS, '--disable-pip-version-check']);
+  console.log(paint('  📥 ', C.gold) + '安装 Python 依赖 (可能需要 1-2 分钟)...');
+  const result = run(PIP, ['install', '-r', REQUIREMENTS, '--disable-pip-version-check']);
   if (result.status !== 0) {
-    err('❌ 依赖安装失败');
+    console.error(paint('  ✖ ', C.red) + '依赖安装失败');
     return false;
   }
-  log('  ✓ 依赖安装完成');
+  console.log(paint('  ✓ ', C.green) + '依赖安装完成');
   return true;
 }
 
-// ── Step 4: 验证 ─────────────────────────────────────
+// ── Step 4: 创建默认目录结构 ───────────────────────────────────
+
+function createDefaultDirs() {
+  const dirs = ['sessions', 'uploads', 'skills', 'skills/active', 'skills/local', 'approvals'];
+  for (const d of dirs) {
+    ensureDir(path.join(STATE_ROOT, d));
+  }
+
+  // 默认 config.yaml (如果不存在)
+  const configPath = path.join(STATE_ROOT, 'config.yaml');
+  if (!fs.existsSync(configPath)) {
+    const defaultConfig = [
+      '# LBS Agent 配置文件',
+      '# 运行 lbs setup 进入交互式配置向导',
+      '',
+      'model:',
+      '  provider: ""',
+      '  name: ""',
+      '',
+      'agent:',
+      '  max_iterations: 10',
+      '  default_agent: chat',
+      '',
+      '# 自定义供应商列表',
+      'custom_providers: []',
+      '',
+    ].join('\n');
+    fs.writeFileSync(configPath, defaultConfig, 'utf-8');
+  }
+
+  console.log(paint('  ✓ ', C.green) + '目录结构已创建');
+}
+
+// ── Step 5: 验证 ───────────────────────────────────────────────
 
 function verifyInstall() {
-  log('🔍 验证安装...');
+  console.log(paint('  🔍 ', C.gold) + '验证安装...');
   const result = run(PYTHON, [path.join(PKG_ROOT, 'lbs.py'), 'status'], {
     silent: true,
     cwd: PKG_ROOT,
+    env: { ...process.env, LBS_HOME: STATE_ROOT },
   });
   if (result.status === 0) {
-    log('  ✓ lbs status 运行正常');
-    return true;
+    console.log(paint('  ✓ ', C.green) + 'lbs status 运行正常');
+  } else {
+    console.log(paint('  ⚠ ', C.yellow) + 'lbs status 运行异常（可能是配置问题，不影响初始化）');
   }
-  err('  ⚠ lbs status 运行异常（可能是配置问题，不影响初始化）');
-  return true; // 不阻断
+  return true;
 }
 
-// ── Step 5: 写入标记 ─────────────────────────────────
+// ── Step 6: 写入标记 ───────────────────────────────────────────
 
 function writeFlag() {
   fs.writeFileSync(INIT_FLAG, JSON.stringify({
     initialized_at: new Date().toISOString(),
+    state_root: STATE_ROOT,
+    pkg_root: PKG_ROOT,
     platform: os.platform(),
     node_version: process.version,
   }, null, 2));
-  log('  ✓ .lbs-initialized 已创建');
+  console.log(paint('  ✓ ', C.green) + '.lbs-initialized 已创建');
 }
 
-// ── 主流程 ───────────────────────────────────────────
+// ── 主流程 ─────────────────────────────────────────────────────
 
 function main() {
-  console.log(`
-╔══════════════════════════════════════════════╗
-║   LBS Agent — 初始化                        ║
-║   Leaving Blank Space Agent                  ║
-╚══════════════════════════════════════════════╝
-`);
+  console.log();
+  console.log(paint('  ┌─────────────────────────────────────────────────────────┐', C.gold));
+  console.log(paint('  │ ', C.gold) + paint('⚙  LBS Agent — 初始化', C.bold, C.gold) + paint('                                       │', C.gold));
+  console.log(paint('  └─────────────────────────────────────────────────────────┘', C.gold));
+  console.log();
+  console.log(paint('  包目录 (只读): ', C.dim) + paint(PKG_ROOT, C.cyan));
+  console.log(paint('  状态目录 (可写): ', C.dim) + paint(STATE_ROOT, C.cyan));
+  console.log();
 
   // Step 1: Python
   const sysPython = findSystemPython();
@@ -160,28 +211,28 @@ function main() {
   // Step 3: deps
   if (!installDeps()) process.exit(1);
 
-  // Step 4: verify
+  // Step 4: dirs
+  createDefaultDirs();
+
+  // Step 5: verify
   verifyInstall();
 
-  // Step 5: flag
+  // Step 6: flag
   writeFlag();
 
-  console.log(`
-╔══════════════════════════════════════════════╗
-║   ✅ 初始化完成！                             ║
-║                                              ║
-║   使用方法:                                  ║
-║   lbs status          查看系统状态           ║
-║   lbs models          查看模型列表           ║
-║   lbs help            查看所有命令           ║
-║                                              ║
-║   启动 Web 端:                               ║
-║   lbs web             打开浏览器界面         ║
-║                                              ║
-║   如果 lbs 命令不可用，手动运行:              ║
-║   node bin/lbs.js status                     ║
-╚══════════════════════════════════════════════╝
-`);
+  console.log();
+  console.log(paint('  ┌─────────────────────────────────────────────────────────┐', C.green));
+  console.log(paint('  │ ', C.green) + paint('✅ 初始化完成！', C.bold, C.green) + paint('                                            │', C.green));
+  console.log(paint('  │                                                         │', C.green));
+  console.log(paint('  │ ', C.green) + paint('下一步:', C.bold) + paint('                                                  │', C.green));
+  console.log(paint('  │ ', C.green) + paint('  lbs setup     配置模型/供应商/Agent', C.cyan) + paint('                  │', C.green));
+  console.log(paint('  │ ', C.green) + paint('  lbs status    查看系统状态', C.cyan) + paint('                           │', C.green));
+  console.log(paint('  │ ', C.green) + paint('  lbs help      查看所有命令', C.cyan) + paint('                           │', C.green));
+  console.log(paint('  │ ', C.green) + paint('  lbs web       启动 Web 界面', C.cyan) + paint('                           │', C.green));
+  console.log(paint('  │                                                         │', C.green));
+  console.log(paint('  │ ', C.green) + paint('状态目录: ', C.dim) + paint(STATE_ROOT, C.cyan) + paint('                   │', C.green));
+  console.log(paint('  └─────────────────────────────────────────────────────────┘', C.green));
+  console.log();
 }
 
 main();