交互式配置向导 (setup)
0.166.128：共享模型推荐目录
CLI setup、VS Code 和 JetBrains 使用同一模型入门目录 llm-onboarding-catalog.json 的推荐信息，并保留自定义 provider、base URL 和模型配置。目录限定为新连接推荐，runtimeVerified: false / accountVerified: false 明确表示未验证当前运行环境与账户，不是所有列出模型都已通过真实任务验收。
IDE 配置读取区分已配置、未配置与读取失败；读取失败时先检查路径和权限，不按缺省值覆盖旧配置。只读取配置状态不会发起推理；显式连接测试会调用模型，并继续受预算、超时、输出上限与已知用量结算约束。会话覆盖与恢复默认的用法见IDE 插件指南。
引导用户完成 ChainlessChain 的首次配置，包括环境检查、版本选择、LLM 配置、二进制下载和 Docker 服务启动。
概述
setup 命令提供一个 8 步交互式向导，引导用户完成 ChainlessChain 的首次配置。向导依次执行环境检查、配置目录初始化、版本选择、LLM 提供商配置、桌面应用下载和 Docker 服务启动，完成后将所有配置写入本地 config.json。
核心特性
- 🔹 环境检查: 自动检测 Node.js 版本、Docker、Docker Compose
- 🔹 版本选择: 支持个人版和企业版
- 🔹 LLM 配置: 选择 LLM 提供商、配置 API 密钥和模型
- 🔹 二进制下载: 自动下载桌面应用程序
- 🔹 服务启动: 可选启动 Docker 后端服务
系统架构
setup 命令 → setup.js (Commander) → 交互式向导 (8 步)
│
┌──────────┬──────────┬────────┼────────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼
1.Node.js 2.Docker 3.配置目录 4.版本 5.LLM 6.下载 7.保存配置
版本检查 检测 初始化 选择 提供商 二进制 config.json
配置 (可跳过) │
▼
8.Docker
服务启动
(可跳过)命令参考
chainlesschain setup # 启动交互式配置向导
chainlesschain setup --skip-download # 跳过二进制下载
chainlesschain setup --skip-services # 跳过 Docker 服务配置选项说明
| 选项 | 说明 |
|---|---|
--skip-download | 跳过桌面应用二进制下载步骤 |
--skip-services | 跳过 Docker 服务启动步骤 |
向导步骤详解
步骤 1：Node.js 版本检查
检查当前 Node.js 版本是否满足最低要求。不满足时自动退出。
步骤 2：Docker 环境检查
检测 Docker 和 Docker Compose 是否可用。Docker 为可选依赖（仅后端服务需要）。
步骤 3：配置目录初始化
创建 .chainlesschain/ 配置目录（位于 Electron userData 下）。
步骤 4：版本选择
选择使用版本：
- 个人版 (Personal) — 个人 AI 管理
- 企业版 (Enterprise) — 企业级功能
步骤 5：LLM 提供商配置
从内置提供商列表中选择，配置 API 密钥和模型：
- 需要 API 密钥的提供商会提示输入（密码输入模式）
- 选择
custom提供商可自定义 API 地址和模型名 - 默认模型可确认使用或自定义修改
步骤 6：下载桌面应用
自动下载当前版本的预编译桌面应用。下载失败不会中断向导，可后续使用 chainlesschain update 手动下载。
步骤 7：保存配置
将所有配置写入 config.json，包含：版本、LLM 提供商、API 密钥、模型、完成时间等。
步骤 8：Docker 服务启动
可选启动 Docker 后端服务（需要 Docker 可用且有 docker-compose.yml）。
配置参考
# CLI 标志
--skip-download # 跳过桌面应用二进制下载步骤
--skip-services # 跳过 Docker 服务启动步骤
# 配置路径（平台自适应）
# Windows: %APPDATA%/chainlesschain-desktop-vue/.chainlesschain/config.json
# macOS: ~/Library/Application Support/chainlesschain-desktop-vue/.chainlesschain/config.json
# Linux: ~/.config/chainlesschain-desktop-vue/.chainlesschain/config.json
# 环境变量（优先级高于 config.json）
OLLAMA_HOST # Ollama 服务地址
OPENAI_API_KEY # OpenAI API 密钥
ANTHROPIC_API_KEY # Anthropic API 密钥性能指标
| 操作 | 目标 | 实际 | 状态 |
|---|---|---|---|
| Node.js 版本检查 | < 100ms | ~50ms | ✅ |
| Docker 环境检测 | < 1s | ~400ms | ✅ |
| 配置目录初始化 | < 50ms | ~20ms | ✅ |
| config.json 保存 | < 30ms | ~10ms | ✅ |
| 完整向导流程 | < 2 分钟 | 取决于用户输入 | ✅ |
测试覆盖率
✅ setup.test.js - 覆盖 CLI 主要路径
├── 参数解析
├── 正常路径
├── 错误处理
└── JSON 输出关键文件
packages/cli/src/commands/setup.js— 命令实现packages/cli/src/lib/config-manager.js— 配置读写packages/cli/src/lib/paths.js— 配置目录管理packages/cli/src/lib/downloader.js— 二进制下载packages/cli/src/lib/prompts.js— 交互式提示封装packages/cli/src/constants.js— 版本、提供商、端口等常量
安全考虑
- API 密钥通过密码输入模式收集，输入时不显示明文
- 配置文件存储在用户本地目录，已加入
.gitignore - API 密钥存储在本地
config.json中，不会上传到外部服务 - 建议使用环境变量覆盖敏感配置（优先级高于 config.json）
使用示例
场景 1：首次完整配置
chainlesschain setup按提示逐步完成版本选择、LLM 配置、下载和服务启动。配置完成后可直接使用 chainlesschain start 启动应用。
场景 2：CI/CD 环境快速配置
chainlesschain setup --skip-download --skip-services跳过下载和 Docker 服务步骤，仅完成基础配置。适用于 CI/CD 或已有二进制的环境。
场景 3：重新配置 LLM 提供商
chainlesschain setup重新运行向导即可修改 LLM 提供商和模型配置。新配置会覆盖旧的 config.json。
故障排查
| 问题 | 解决方案 |
|---|---|
Node.js X+ required | 升级 Node.js 到要求的最低版本 |
| 下载失败 | 检查网络连接，后续可用 chainlesschain update 重试 |
| Docker 服务启动失败 | 确认 Docker Desktop 运行中，检查端口占用 |
ExitPromptError | 用户按 Ctrl+C 取消向导，正常退出 |
| 配置丢失 | 检查配置目录路径：chainlesschain config list |