终端原生的
AI 编程智能体

# 1. 快速上手 (Getting Started)

LingXiAgent 为 macOS arm64、Linux x86_64、Windows x86_64 发布预编译安装包（当前最新 release：v1.1.0，权威来源为 GitHub Releases）。安装只需一条命令，即可自动完成平台与架构探测、可执行文件（lingxiagent、LingXiTUI、LingXiCoreHost）与资源包部署，并配置环境变量。Intel Mac 与 AArch64 Linux 需从源码构建。

步骤一：一键自动安装

步骤二：刷新终端并首次启动

# 2. 终端 TUI 使用指南 (TUI Usage)

LingXiAgent 的终端界面为原生 Swift 渲染（经 LingXiPlatform 的终端抽象对接真实 TTY），采用双栏式布局，支持思考流折叠、代码 Patch 高亮审查与键盘一键导航。帧率与延迟取决于终端模拟器与宿主环境，本页不给出未实测的数字。

常用快捷键

Slash 快捷命令与全套弹出式浮层 (Pickers & Modals)

• /theme — 唤起 24-bit TrueColor 主题选择器，6 套主题支持打字即时过滤与热重载。
• /mode — 弹出运行模式选择器 (Build / Plan / Explore 方向键直选)；Tab / Shift+Tab 循环切换。
• /permissions — 弹出安全策略选择器 (Ask / Auto / YOLO 档位直选)。
• /reasoning — 弹出思考等级选择器 (Auto / Off / Low / Med / High / Max 直选)。
• /keybindings — 弹出快捷键速查模态面板，可滚动查阅且不污染会话流。
• /diff — 弹出工作区 Git 变更审查模态框，支持平滑滚动查阅长篇变更。
• /tasks — 弹出后台任务管理面板，支持实时监控与定向中断强杀。
• /resume — 交互式会话选择器，按项目目录聚合，一键恢复历史。
• /model — 唤起模型选择器，在官方订阅与自定义 API 模型间毫秒切换。
• /status · /context · /perf · /mcp — 居中模态卡片，瞬态指标查完即走。
• /new — 秒级开辟全新对话流，自动重置视口与聚焦。

常用 CLI 实用子命令

# 3. 提供商与认证体系 (Providers & Auth)

LingXiAgent 确立了“官方内置渠道与自定义渠道物理隔离”的核心架构。内置渠道无需也不允许写入用户配置文件，确保升级平滑无污染。

官方订阅登录命令 (OAuth 认证)

自定义 API 提供商配置 (~/.lingxiagent/providers.json)

若想接入 DeepSeek、硅基流动、Ollama 等第三方 API，在配置文件中添加即可：

{
  "$schema": "https://lingxiagent.lingxifox.cn/schema/providers.json",
  "version": 1,
  "providers": {
    "deepseek": {
      "name": "DeepSeek 官方",
      "adapter": "openai-compatible",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      },
      "models": {
        "deepseek-chat": { "name": "DeepSeek V3" },
        "deepseek-reasoner": { "name": "DeepSeek R1" }
      }
    }
  }
}

# 4. 客户端请求画像与指纹 (Client Fingerprint)

访问官方订阅端点时，出站请求需要如实表明客户端形态：ClientFingerprint 按渠道生成 User-Agent 与伴随请求头，其中操作系统与架构字段取自当前真实宿主。本页不承诺任何“绕过风控”的效果；请求画像只描述客户端自身的形态，上游如何对待这些请求由上游决定。

动态出站指纹一览

表中的 darwin/arm64 会随真实宿主变化。客户端版本默认 0.154.0 / 2.1.258 / 2.9.1，可分别通过 CODEX_CLI_VERSION、CLAUDE_CLI_VERSION、ANTIGRAVITY_VERSION 覆盖；Gemini Code Assist 与 xAI Grok 订阅渠道走同一套画像生成逻辑。

# 5. 开放标准：ACP、LSP 与 MCP (Protocols & Extensions)

LingXiAgent 全面拥抱开放标准生态，原生支持 Agent Client Protocol (ACP)、Language Server Protocol (LSP) 以及 Model Context Protocol (MCP)。

⚡ 接入 Zed IDE (ACP 标准协议模式)

执行 lingxiagent-ops acp 启动通用 Agent 后端服务（ACP 属于 ops 入口）。在 Zed 的 settings.json 中配置：

{
  "assistant": {
    "version": "2",
    "default_model": { "provider": "acp", "model": "LingXiAgent" },
    "providers": {
      "acp": { "command": "lingxiagent-ops", "args": ["acp"] }
    }
  }
}

🔌 MCP 服务器配置 (~/.lingxiagent/mcp.json)

{
  "$schema": "https://lingxiagent.lingxifox.cn/schema/mcp.json",
  "version": 1,
  "servers": [
    {
      "id": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "arguments": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/path"],
      "enabled": true
    },
    {
      "id": "github",
      "transport": "stdio",
      "command": "npx",
      "arguments": ["-y", "@modelcontextprotocol/server-github"],
      "enabled": true,
      "environment": [
        { "name": "GITHUB_PERSONAL_ACCESS_TOKEN", "credential": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}" }
      ]
    }
  ]
}

凭据字段只接受 {env:VAR} / {vault:...} 引用形式，配置文件里不写明文 token。完整字段见 /docs.html#mcp-ecosystem。

# 6. 常见问题与排错 (Troubleshooting)