LingXiAgent 核心技术概览

官方安装脚本会自动探测系统类型与 CPU 架构，从最新 GitHub Release 下载对应预编译包（macOS arm64、Linux x86_64、Windows x86_64）并配置环境变量。每个发布资产附带同名 .sha256。Intel Mac 与 AArch64 Linux 没有预编译包，在具备 Swift 工具链时脚本会自动浅克隆源码极速编译。

LingXiAgent 的全局配置位于数据目录 ~/.lingxiagent/，按职责分成四个文档，各自带 JSON Schema（$schema 指向 lingxiagent.lingxifox.cn/schema/*.json）：config.json（行为与预算）、providers.json（自定义 Provider）、mcp.json（MCP 服务器）、plugins.json（插件）。四个文档均由单一数据根解析，不存在按项目目录覆盖的同名配置文件。

{
  "$schema": "https://lingxiagent.lingxifox.cn/schema/config.json",
  "version": 1,
  "core": { "locale": "system", "logLevel": "info" },
  "agent": {
    "executionProfile": "workspace",
    "permissionPolicy": "ask",
    "codeIntelligenceEnabled": false,
    "pCoreProjectMaxCharacters": 32768,
    "eCoreRecallMaxCharacters": 262144,
    "maxConcurrentSubagents": 4,
    "maxSubagentDepth": 3,
    "maxTotalRunsPerRootRun": 32
  },
  "runtime": {
    "commandTimeoutSeconds": 60,
    "interactive": false,
    "execution": {
      "foregroundShellSeconds": 60,
      "agentRunSeconds": 1800,
      "providerSeconds": 120,
      "maximumSeconds": 3600
    }
  },
  "context": {
    "addressableBudget": 1048576,
    "reserve": 22000,
    "economicThreshold": 272000,
    "pCore": { "target": 220000, "softLimit": 235000, "hardLimit": 250000 },
    "eCore": {
      "storageBudget": 456576,
      "recallBudget": 350000,
      "pressureThreshold": 0.85,
      "useRemainingBudget": true
    },
    "fabric": {
      "objectizationThreshold": 32768,
      "fullSendCount": 4,
      "placeholderExcerpt": 1024,
      "recallMaxBytes": 16384,
      "recallMaxLines": 400,
      "heatTrackingEnabled": true,
      "heatDecayHalfLifeSeconds": 3600
    }
  }
}

旧键 l1ProjectMaxCharacters / l2MaxCharacters 与 context.l1/l2/l3、ecoreStorageEnabled 仍可读，用于向后兼容；读取优先级为「新 P/E 键 → 旧键 → 默认值」，写入只落新键。这些旧名不代表三级缓存架构，当前架构只有 P-Core 与 E-Core。

内置三层权限拦截引擎，杜绝任何未授权的静默危险操作：

所有 Provider 凭据、MCP 环境变量与 OAuth token 统一存放在数据目录下的 credentials.vault，由 UniversalCredentialStore 读写。配置文件里不允许出现明文凭据：providers.json 与 mcp.json 的凭据字段只接受 {env:VAR_NAME} 或 {vault:...} 引用，Schema 用正则强制。

一次工具调用可能返回上万行测试日志或整份文件。如果这些内容全部留在模型请求里，上下文窗口会被低价值数据填满，既推高成本，也让模型注意力被稀释。LingXiAgent 因此把「留在请求里的内容」与「完整内容的存放与取回」拆成两个核心。

下列阈值均为 config.json 中 context 分段（ContextCacheConfiguration）的默认值，可按模型窗口调整；表内键名相对 context 书写，语义以 Sources/LingXiCore/Configuration/ConfigurationTypes.swift 为准。

LingXiTUI、LingXiWebUI、macOS GUI 与 ACP 接入的编辑器都不自行维护真值。它们通过 LingXiClient 连接 CoreHost，由 LingXiApplication 做状态投影与 reducer：Goal、Todo、分支预测、P/E 上下文、Subagent 生命周期、Permission / Question 交互、Git 与 Workspace 状态全部来自 Core 的同一份投影。

• ▸ 传输：Stdio IPC（TUI / CLI）与 HTTP + SSE（lingxiagent serve）
• ▸ 契约：Wire 协议与前端契约由 ContractTests 跨平台校验
• ▸ 后果：新增前端不需要重复实现会话、权限或上下文逻辑

执行宿主命令并捕获标准输出与错误。深度集成了跨平台沙箱引擎与超时看门狗（Watchdog）：

坚决杜绝大文件“全量重写”带来的 Token 浪费与偶发幻觉断行。智能体使用精确字符串替换块：

{
  "targetFile": "/path/to/source.swift",
  "startLine": 42,
  "endLine": 48,
  "targetContent": "func oldImplementation() {\n    ...\n}",
  "replacementContent": "func newOptimizedImplementation() {\n    ...\n}"
}

内置原生极速代码发现引擎，支持大规模千万级代码库瞬时检索：

• grep_search：底层动态调用 ripgrep，支持正则与多文件过滤。
• find_by_name：底层动态调用 fd，秒级定位文件路径，自动遵循 .gitignore。

当需求存在歧义或有多个架构方案需要用户定夺时，Agent 会主动调用此工具，在终端界面以精美的方向键导航浮层供用户勾选（单选/多选/自定义输入），彻底告别大模型臆想。

自定义渠道写在 ~/.lingxiagent/providers.json（Schema：lingxiagent.lingxifox.cn/schema/providers.json）。providers 是以渠道 id 为键的对象；adapter 只接受三种协议契约：openai-compatible、openai-responses、anthropic-messages；options.baseURL 必填，apiKey 若出现则必须是引用形式。

{
  "$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" }
      }
    }
  }
}

• ▸ 凭据不可写死：apiKey 的 Schema 正则只接受 {env:VAR} 与 {vault:...}，明文 key 会被校验拒绝。
• ▸ 目录与运行时分离：模型元数据来自 models.lingxifox.cn/models.json；能否选用还取决于本机运行时契约与账号可用性，两者取交集。
• ▸ Prompt Cache：Anthropic 渠道使用 cache_control 断点，OpenAI 兼容渠道读取 prompt_cache_hit_tokens 等回传字段计入观测；P-Core 的稳定前缀就是为命中缓存设计的。
• ▸ 命令入口：lingxiagent-ops auth status <product>、lingxiagent-ops models sync <product>；TUI 内用 /providers、/connect、/model。

MCP 服务器写在 ~/.lingxiagent/mcp.json 的 servers 数组里（Schema 同名路径）。两种传输：stdio 用 command + arguments 拉起子进程；streamableHTTP 用 endpoint 连接远端。凭据同样只能是引用形式，配置文件里不出现 token。

{
  "$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,
      "timeoutSeconds": 60
    },
    {
      "id": "remote-example",
      "transport": "streamableHTTP",
      "endpoint": "https://example.com/mcp",
      "protocolPreference": "auto",
      "enabled": true,
      "authentication": { "kind": "bearer", "credential": "{env:EXAMPLE_MCP_TOKEN}" },
      "environment": [ { "name": "EXAMPLE_MCP_TOKEN", "credential": "{env:EXAMPLE_MCP_TOKEN}" } ]
    }
  ]
}

• ▸ 命令入口：lingxiagent-ops mcp list | status | enable | disable | add | login | auth | remove；TUI 内 /mcp 打开状态面板。
• ▸ 授权：远端服务器支持 OAuth 授权码流程 + PKCE，本地回环端口接收回调（实现见 MCPOAuthClient 与 MCPCLI 的 login / auth 子命令）。mcp.json 的凭据字段写引用，不写明文。
• ▸ 超时：timeoutSeconds 覆盖默认值；Runtime 侧 MCP 类调用默认预算为 60 秒（config.json 的 runtime.execution.mcpSeconds）。

Skill 是「一个目录 + 一份 SKILL.md」的提示词包，被当作可发现扩展注入 Agent，而不是插件二进制。发现路径固定为三处：

• ▸ ~/.lingxiagent/skills/<name>/SKILL.md
• ▸ ~/.lingxiagent/.lingxi/skills/<name>/SKILL.md
• ▸ <project>/.lingxi/skills/<name>/SKILL.md

命令入口：lingxiagent-ops skills list | info | enable | disable；TUI 内 /skills 查看与切换。技能内容属于提示词层：它改变模型的行为倾向，不改变权限判定——写操作仍要过 Permission Engine。

以下清单来自 LingXiTUI 的命令描述符与前端命令表，不是设想稿。输入 /help 可在运行时看到同一份列表。

别名：/theme ⇄ /themes，/keybindings ⇄ /keys ⇄ /shortcuts。自定义命令与插件命令会合并进同一张表（见 Plugin SDK 文档）。

安装包内有两个不同职责的可执行入口（同源 SwiftPM products）：

# 交互与 WebUI
lingxiagent                          # 进入 TUI
lingxiagent serve --port 8080        # HTTP + SSE 前端

# 渠道与模型
lingxiagent-ops auth login openai-codex
lingxiagent-ops auth status
lingxiagent-ops models sync openai-codex

# 批量与诊断
lingxiagent-ops review
lingxiagent-ops doctor
git diff | lingxiagent-ops exec "为本批变更写英文 commit message"
lingxiagent-ops resume --last

LingXiAgent 拒绝在业务逻辑中散落条件编译宏，采用纯契约协议层与物理目录隔离架构：

官方订阅端点期望看到与自身生态一致的客户端标识。ClientFingerprint（Sources/LingXiCore/Configuration/ClientFingerprint.swift）负责按渠道生成出站 User-Agent 与伴随 Header。其中平台字段来自 currentPlatform() 对真实宿主的读取：osName（darwin / linux / windows）、arch（arm64 / x86_64）、TERM。

• ▸ 版本默认值与覆盖：0.154.0 / 2.1.258 / 2.9.1 / 0.1.5 / 0.2.120，分别可用 CODEX_CLI_VERSION、CLAUDE_CLI_VERSION、ANTIGRAVITY_VERSION、GEMINI_CLI_VERSION、XAI_GROK_CLI_VERSION 覆盖；Codex 还支持 CODEX_CLIENT_FLAVOR（codex-cli / codex-tui）。平台字段不可覆盖，始终实测。
• ▸ 能力边界：本机制只影响应用层 HTTP 头部。它不改变传输层 TLS/TCP 栈，因此不存在、也不宣称「TLS/JA3/JA4 指纹伪装」；同理不承诺任何「免封」「反检测」效果——上游如何判定由其自身策略决定。
• ▸ 用途定位：让官方 CLI 生态的渠道识别、灰度与故障归因落到正确客户端上，同时保证本地排障时看到的 OS/架构与真实宿主一致。

两个公共 SDK 是独立 GitHub 仓库、独立 MIT 许可、独立 SemVer 的 Swift Package，与 LingXiAgent 的版本号互不绑定；LingXiAgent 自己也通过公开 SwiftPM 入口消费它们，与第三方拿到的是同一份产物。

职责区分：ModelSDK 面向模型目录消费者，PluginSDK 面向插件作者，LingXiAgent 是 Agent 产品与运行时（LCSAL-1.1 / PolyForm Noncommercial，见仓库 LICENSE-MATRIX）。完整插件文档在 /sdk.html，模型数据在 Models Hub。