环境要求

• Node.js ≥ 22
• npm、pnpm 或其他兼容 npm registry 的包管理器

快速开始

安装

外部用户推荐通过 npm 安装：

npm install -g @q-code-cli/q-code
q-code

全局安装后可直接更新到 npm latest：

q-code update
q-code update --dry-run  # 仅查看将执行的更新命令

更新后再次启动时，若版本高于上次使用记录（~/.q-code/last-version.json），会在 TUI / 经典模式下展示自上次版本以来的变更摘要；完整历史见 CHANGELOG.md（合并到 main 后由 CI 自动维护，发版时 pnpm build 会生成最新的 changelog.json）。设为 Q_CODE_CHANGELOG=0 可关闭启动提示。

首次使用可运行交互式初始化向导，生成 config.toml：

q-code init              # 默认写入 ~/.q-code/config.toml
q-code init --local      # 写入当前项目的 .q-code/config.toml
q-code init --user       # 显式写入用户目录（与默认行为相同）

向导会引导填写 OpenAI 兼容 API 的 base_url、api_key，通过 /models 接口校验并选择主模型与摘要模型，可选配置 [env].file 复用项目 .env；并可选开启 GitLab Wiki 集成（写入 [gitlab_kb] 的 url、token、prefix）。

也可以不全局安装，直接临时运行：

npx @q-code-cli/q-code

本地开发时从源码安装依赖：

pnpm install

启动

q-code                  # npm 安装后的新会话
q-code --continue       # 恢复上次会话
pnpm start              # 新建会话
pnpm run continue       # 恢复上次会话

配置

npm 全局安装后推荐使用 ~/.q-code/config.toml，在任意目录运行 q-code 都能读取：

[openai]
api_key = "<your-api-key>"
base_url = "https://api.openai.com/v1"
model = "gpt-5.4"

[summary]
api_key = "<your-api-key>"
base_url = "https://api.openai.com/v1"
model = "gpt-5.4"

[langfuse]
enabled = false
base_url = "https://cloud.langfuse.com"
record_io = false

也可以在项目内使用 .q-code/config.toml 覆盖全局配置。配置优先级为：环境变量 > 项目 .q-code/config.toml > 全局 ~/.q-code/config.toml > 项目 .env > 内置默认值。

如果你想在 config.toml 里复用一份 .env 文件，可以这样写：

[env]
file = ".env.shared"

[openai]
model = "gpt-5.4"

[env].file 支持相对当前 config.toml 的路径，先加载该 .env，再由同一个 config.toml 里的显式 TOML 键继续覆盖。

本地开发仍可复制环境变量模板并填写：

cp .env.example .env

命令行参数

发布产物使用薄入口启动：help / version 只加载颜色环境、argv 解析和帮助/版本格式化后立即退出；update、audit、init、eval、dashboard 与主交互循环按需动态加载各自模块，避免互相支付依赖成本。主交互路径也只在确认进入 TUI 时动态加载 Ink/React；非 TTY、--classic 或 Q_CODE_TUI=0 会回退到传统 readline，且不会加载 TUI 运行时。TUI 会先渲染会话和输入界面，再继续完成 Custom Tools、Hooks、Skills、Agents、MCP、runtime context 与项目指令预热；如果用户在预热完成前提交会触发 Agent 或依赖预热状态的命令，ready gate 会显示“正在完成启动预热...”并在能力完整后自动继续。需要观察阶段耗时时，可设置 Q_CODE_STARTUP_TRACE=true 或使用 --debug，输出形如 [Startup] bootstrap 12ms 的阶段计时，不包含 API key、token 或工具输出。

11.1 企业 AI 基建配置同步

企业 AI 基建是可选集成功能，默认关闭。只有显式配置 Q_CODE_INFRA_ENABLED=true 后，q-code 才会读取 Q_CODE_INFRA_BASE_URL 和 Q_CODE_INFRA_TOKEN，并在启动时向企业配置中心解析当前仓库所属业务域，再把配置包增量写入本地项目：

<cwd>/.q-code/settings.json      # 企业 MCP server 配置
<cwd>/.q-code/skills/<name>/     # 云端下发 Skills
<cwd>/.q-code/infra-state.json   # 最近一次同步状态
<cwd>/AGENTS.md                  # 企业规则受管区块

未开启 Q_CODE_INFRA_ENABLED 时，q-code 不会写入任何企业配置文件，原有本地行为保持不变。开启后若配置中心不可用，Client 会保留最近一次成功状态，并在 /infra status 中标记为 stale 或 failed。

完整工作流程

┌─────────────────────────────────────────────────────────────┐
│                        启动阶段                              │
│                                                              │
│  1. 薄入口处理 help/version；其他子命令按需动态 import        │
│  2. 主交互路径加载环境变量，初始化会话/历史/模型基础状态       │
│  3. 仅 TUI 模式动态加载 Ink/React，并先渲染输入界面            │
│  4. 显式 startupWarmupPromise 并行预热 Hooks/Custom Tools/Infra│
│  5. 继续并行加载 runtime context、项目指令、MCP、Skills、Agents │
│  6. ready gate 在预热完成后注册完整工具并构建 System Prompt    │
│  7. 用户输入若早于预热完成，会等待 gate 后继续执行             │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    交互循环 (readline)                        │
│                                                              │
│  用户输入 ──→ 斜杠命令? ──→ 是 ──→ 处理内置命令             │
│                  │                                           │
│                  否 → Skill 斜杠展开? → 是 → 展开为消息      │
│                       │                                      │
│                       否 → 构造 user message                 │
│                                                              │
│  ──→ 注入后台 Agent 完成通知 (如有)                          │
│  ──→ 注入 Plan Mode 提醒 (如需)                              │
│  ──→ 保存消息到 SessionStore                                 │
│  ──→ 动态构建 System Prompt (buildSystemPrompt)              │
│  ──→ 进入 Agent Loop                                        │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Agent Loop (无默认步数硬限制)              │
│                                                              │
│  ┌──→ Step N:                                               │
│  │   1. Preflight: 检查上下文占用，超阈值则压缩              │
│  │   2. 流式调用 LLM (streamText)                            │
│  │   3. 收集工具调用 / 文本输出                              │
│  │   4. 输出触顶? → 升级 maxOutputTokens 重试                │
│  │   5. 执行工具 (并发控制 + 结果截断)                       │
│  │   6. 死循环检测 (三种检测器)                              │
│  │   7. stopAfterToolNames 检查 (如 exit_plan_mode)          │
│  │   8. 无工具调用 → 退出循环                                │
│  └─── 有工具调用 → 继续                                      │
│                                                              │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      后处理阶段                               │
│                                                              │
│  1. 保存新消息到 SessionStore                                │
│  2. Post-turn 压缩检查 (为下一轮腾出空间)                     │
│  3. Plan Mode 审批提示 (如有待确认计划)                      │
│  4. 回到交互循环，等待下一轮输入                              │
└─────────────────────────────────────────────────────────────┘

11. MCP 扩展

q-code 支持标准 mcpServers 配置，把外部 MCP server 适配成普通工具。配置分两级：

示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

支持的 transport：

MCP 工具名会规范化为 mcp__<server>__<tool>，例如 my.db 的 echo.tool 会变成 mcp__my_db__echo_tool。MCP 工具默认延迟加载，Agent 需要时通过 tool_search 按需激活，避免大量外部工具撑大 System Prompt。

启动时 MCP 连接在后台并行进行：慢 server 不会阻塞 CLI；连接成功后工具会增量注册。--dump-system-prompt 会等待 MCP bootstrap 完成，方便检查最终 prompt。

兼容说明：如果未配置 mcpServers.github，但设置了 GITHUB_PERSONAL_ACCESS_TOKEN，q-code 会按旧行为自动添加一个 GitHub stdio MCP server。新项目建议迁移到 settings.json。