lingcode 命令行

安装

支持 macOS（Apple Silicon 与 Intel）与 Linux x86_64；也可先在浏览器演示里试用 Claude、DeepSeek、OpenAI、Gemini 等对拍，无需安装。

两种方式，挑你已经有的。

独立安装 — 不需要 App

curl -fsSL https://lingcode.dev/install-cli.sh | sh

下载已签名、已公证的压缩包（macOS）或未签名的 tarball（Linux）到 ~/.lingcode/cli/，并在 ~/.local/bin/lingcode 建立符号链接。压缩包内含 Node 桥接，Claude 提供方无需 LingCode.app 也能用（仍需 Node.js 与 API 密钥）。

从已安装的 LingCode.app

/Applications/LingCode.app/Contents/Resources/bin/lingcode install

install 子命令会优先尝试 /usr/local/bin,失败回退到 ~/.local/bin,必要时输出 PATH 提示。

快速开始

# 一条命令把密钥存入钥匙串(会打开浏览器)
lingcode auth login

# 交互式会话(默认 Claude)
lingcode

# 用其他提供方启动交互式会话
lingcode --provider ollama --model llama3.2
lingcode --provider groq --model llama-3.1-70b-versatile

# 一次性问答
lingcode ask "解释这个报错" < build.log
echo "2+2 等于几?" | lingcode ask -

# 检查配置
lingcode auth status
lingcode --help

交互式 REPL

lingcode 不带参数即进入交互式多轮会话，等价于 lingcode repl，只是输入更短。

依据提供方，REPL 有两种形态：

• Claude 模式 —— 完整 Agent 循环：工具调用、文件编辑、MCP 服务器、Hooks、会话续接、权限询问、彩色 diff。经由内置 Node 桥接加载 @anthropic-ai/claude-agent-sdk。
• OpenAI 兼容模式 —— 在任意 OpenAI 兼容端点上同样具备完整 Agent 循环（工具派发、MCP、Skills、子代理、Hooks、自定义斜杠命令），覆盖 OpenAI、Groq、Together、OpenRouter、Mistral、xAI、Fireworks、Ollama、DeepSeek 及自建代理等。

行编辑器

当 stdin 是终端时,你有一个完整的行编辑器:

提示符

REPL 在非零时显示轮次与累计费用:

lingcode> 解释这个仓库
…
lingcode [1t $0.003]> 建议一种重构方式
…
lingcode [2t $0.011]>

提供方

用 --provider 选择；可按需覆盖 model、base URL、API key 环境变量。默认情况下，每个提供方都会启用带工具调用的 Agent 循环。

两种 DeepSeek 用法

deepseek-compat 使用 DeepSeek 的 OpenAI 兼容端点，由 lingcode 自有的 Agent 循环驱动。deepseek-claude 使用 DeepSeek 的 Anthropic 兼容端点，让完整的 Claude/SDK 通路（会话、Hooks、Skills、子代理）驱动 DeepSeek‑V4，横幅会显示 (claude→deepseek)。deepseek-claude 功能更齐全，但通过兼容层不包含 MCP 服务端与经由 --file 的图片输入（对端字段会被忽略）。

lingcode --provider deepseek-claude     # Claude 全流程体验，deepseek-v4-pro[1m]
lingcode --provider deepseek-compat     # OpenAI 格式，默认 deepseek-v4-flash
lingcode --provider deepseek-compat --model deepseek-v4-pro

任意 OpenAI 兼容端点

lingcode --provider openai \
  --base-url https://my-proxy.example.com/v1 \
  --api-key-env MY_KEY_VAR \
  --model gpt-4o

工具调用、MCP 服务器、Hooks、Skills、子代理、自定义斜杠命令、输出样式、settings.json 里的权限模板，以及可配置的状态行在每个提供方上均可用。会话续接与使用 --file（走 Agent SDK）的图片输入仅限 Claude——依赖自带 SDK；OpenAI 兼容提供方请参阅 lingcode ask --help 中的 --image 等附件选项。

Linux 要点

CLI 在 Linux x86_64 上均可构建运行。与 macOS 相比：没有对接 LingCode.app 的 IPC 子命令（ping、open、status、watch、install 仅 macOS）；密钥写入 $XDG_CONFIG_HOME/lingcode/keys.json（默认为 ~/.config/lingcode/keys.json），chmod 600，代替钥匙串。lingcode auth login / set / status / delete 与环境变量在两个平台上行为一致。

一次性 ask

# 基本用法
lingcode ask "总结这个仓库的架构"

# 把内容 pipe 进去
cat error.log | lingcode ask "解释一下"

# 整段 prompt 从 stdin 读入
echo "2+2 等于几?" | lingcode ask -

# 切换提供方
lingcode ask --provider groq "一行话解释这个正则:/\d{3}-\d{4}/"

# Claude 全工具模式,自动批准
lingcode ask --provider claude --yolo "给 .gitignore 加一条 .DS_Store"

# 附加文件
lingcode ask --provider claude --file screenshot.png "这个界面哪里不对?"

# 结构化输出(适合脚本)
lingcode ask --output-format stream-json "修复 main.swift 里失败的测试"

常用 flag

斜杠命令

在 REPL 提示符下输入。

全部提供方

仅 Claude

仅 OpenAI 兼容

自定义

把一个 Markdown 文件放到 .claude/commands/<name>.md,就能用 /project:<name> 调用。放到 ~/.claude/commands/ 下用 /user:<name>。纯 /<name> 先查 project,再查 user。命令名后的任何文字会追加到正文之后。

$ echo "用中文解释一下当前 git 暂存区的变更。" > .claude/commands/explain-staged.md
$ lingcode
lingcode> /project:explain-staged

鉴权与 API 密钥

三类来源，按顺序检查：环境变量、操作系统密钥库（macOS 为钥匙串，Linux 为 chmod 600 的 ~/.config/lingcode/keys.json）、配置文件。任一生效即可。

# 浏览器辅助:打开提供方控制台,粘贴密钥,存入钥匙串
lingcode auth login
lingcode auth login --provider deepseek

# 直接写入
lingcode auth set anthropic sk-ant-...
lingcode auth set deepseek sk-...

# 查看已配置项(值已脱敏)
lingcode auth status

# 删除密钥
lingcode auth delete anthropic

关于 OAuth:Anthropic 不向第三方 CLI 发放 OAuth client ID,因此无法做真正的 /login OAuth 流程。lingcode auth login 是实际可行的替代方案 —— 打开浏览器,等你粘贴密钥,然后写入钥匙串。

其他提供方（openai、groq、together、openrouter、mistral、xai、fireworks、gemini、kimi、qwen、ollama 等）若未走浏览器登录路径，通常在 shell 中设置对应环境变量即可：

export OPENAI_API_KEY=sk-...
export GROQ_API_KEY=gsk-...

Skills 与子代理

与 Claude Code 使用相同加载路径，已有技能库可直接复用。项目在 .claude/，用户在 ~/.claude/；同名时项目优先。

Skills

在相关时能拉取的一包「专长说明」。放在 .claude/skills/<name>/SKILL.md，带 YAML front matter：

---
name: pr-reviewer
description: Review a GitHub PR with focus on security, correctness, and style.
---

When asked to review a PR, fetch it via `gh pr view`, then check:
1. Security issues (injection, auth bypass)
2. Correctness (edge cases, error handling)
3. Style (matches repo conventions)

所有提供方下都会自动合并进系统提示。可用 --no-skills 关闭；在 REPL 用 /skills 查看已加载列表。

子代理

模型可通过 Task 工具下发给专注子会话的代理——独立上下文、自有系统提示，并可按需指定模型与工具子集。放在 .claude/agents/<name>.md：

---
name: flake-hunter
description: Diagnose intermittently-failing tests by rerunning and correlating with recent commits.
model: deepseek-v4-pro
tools: Read, Grep, Bash
---

Check git log for recent changes near the failing test. Run the test N times
and look for non-determinism: time, network, randomness, parallel ordering.

模型以 Task(agent: "flake-hunter", prompt: "...") 调用。子代理串行运行，不能再嵌套派发 Task（无 Task-in-Task），并与父会话共用同一权限判决链。/agents 列出配置。选用 Claude 提供方时，子代理亦可由 Agent SDK 内置 Task 提供，对模型的交互方式一致。

MCP 服务器、Hooks、自定义命令

与各提供方上的 Claude Code 项目约定兼容。

MCP 服务器

项目根放一个 .mcp.json(全局放 ~/.claude.json):

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

用 --mcp-config <path> 覆盖，用 --no-mcp 关闭。Claude 与 OpenAI 兼容提供方均可连接 MCP（stdio）——接入的工具会像内置工具一样出现在模型工具清单中。deepseek-claude 因对端兼容性限制不包含 MCP。

Hooks

在 .claude/settings.json 中配置，以 shell 命令执行；环境变量含 CLAUDE_TOOL_NAME、CLAUDE_TOOL_INPUT；对 PostToolUse 还有 CLAUDE_TOOL_RESULT；对 UserPromptSubmit 含有 CLAUDE_USER_PROMPT。若不希望依赖 Claude 前缀名，亦可使用并行的 LINGCODE_*。**所有提供方**都会触发这些 Hooks。

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "echo 即将编辑: $CLAUDE_TOOL_INPUT" }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "logger -t lingcode \"$CLAUDE_USER_PROMPT\"" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "say 完成" }] }
    ]
  }
}

自定义斜杠命令

放在项目 .claude/commands/ 或用户 ~/.claude/commands/ 下的 Markdown；格式与 Claude Code 相同——文件正文即 prompt。

权限模板、输出样式与状态行

以下三组配置同样在 .claude/settings.json 中，且对每一个提供方生效。

权限模式模板（permission patterns）

细粒度允许 / 拒绝 / 询问规则，叠加在全局权限模式之上。Glob：* 匹配不含斜杠的一段，** 匹配路径。**优先级：deny > ask > allow。** ask 会强制弹出交互询问，即使在 --yolo 下也不例外。

{
  "permissions": {
    "allow": ["Bash(git *)", "Read(**/*.swift)"],
    "deny":  ["Bash(rm *)", "Bash(curl *)"],
    "ask":   ["Write(**)", "Edit(**)"]
  }
}

硬性安全拦截

一组破坏性极强的模式会被无条件拦截，无法用设置覆盖；在启动时编译进判决链，先于普通权限问询：

• rm -rf / 及对系统根路径的递归删除
• mkfs（格式化文件系统）
• 向裸盘设备写入的 dd
• 对 /etc、/System 等的篡改
• 篡改 ~/.ssh/authorized_keys
• Fork bomb 一类模式

上述规则覆盖 REPL、ask、serve 与 acp-serve 的每一轮权限路径；即使你或外部客户端倾向自动放行，仍会先命中硬拦截。

输出样式（output styles）

在系统提示后追加的语气 / 体裁。文件放在 .claude/output-styles/<name>.md 或 ~/.claude/output-styles/。命令行用 --output-style <name>；REPL 用 /output-styles。内置默认样式为 engineer。

状态行（status line）

用 shell 自定义提示符后缀。每轮执行一次（不是每个按键）；约 2 秒超时；失败则静默回退内置提示。

{
  "statusLine": {
    "type": "command",
    "command": "printf '%s · %st · $%s' \"$LINGCODE_MODEL\" \"$LINGCODE_TURN\" \"$LINGCODE_COST_USD\""
  }
}

可用的环境变量包括 LINGCODE_SESSION、LINGCODE_MODEL、LINGCODE_TURN、LINGCODE_INPUT_TOKENS、LINGCODE_OUTPUT_TOKENS、LINGCODE_COST_USD、LINGCODE_CWD；亦会设置 Claude Code 风格的 CLAUDE_* 镜像变量。

后台任务

长时间运行的 Shell（例如 dev server、监听进程）应以 Bash(run_in_background: true) 拉起，随即返回任务 id。用 Monitor 工具轮询增量输出并查看是否仍在运行；Monitor(action: "list") 列出全部；Monitor(action: "kill", id: "bg_3") 终止一条。默认每会话至多 8 个并发后台任务。

与运行中的 App 通信

当 LingCode.app 打开时,以下命令通过 ~/Library/Application Support/LingCode/ipc.sock 的 Unix socket 驱动它:

给 ask 加 --headless 可强制本地执行，即使 App 开着。

HTTP 服务模式（serve）

lingcode serve 启动常驻 HTTP 服务，通过 Server-Sent Events (SSE) 向外暴露与本机 REPL、ask 相同的 Agent 核心。可把 VS Code 扩展、Web UI、另一台机器上的脚本都对接到这一套接口。

lingcode serve                                   # 绑定 127.0.0.1:7878
lingcode serve --port 8080
lingcode serve --bind 0.0.0.0 --allow-remote     # 显式允许监听非 loopback
lingcode serve --new-token                       # 轮换 Bearer 令牌
lingcode serve --bridge-daemon auto              # 复用已运行的 bridge 守护进程（省冷启动）

鉴权：Authorization: Bearer <token>。首次启动生成令牌，写入 ~/.lingcode/server.token（chmod 600），并在 stderr 打印。默认仅 127.0.0.1；若要对外网卡监听须加 --allow-remote。

路由（v1）

流式发起一次 ask

TOKEN=$(cat ~/.lingcode/server.token)

# 存活
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7878/v1/ping

# SSE 流式问答（curl -N 禁止缓冲）
curl -N -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"provider":"claude","prompt":"list files","cwd":"'"$PWD"'"}' \
     http://127.0.0.1:7878/v1/agent/ask

SSE 每帧一条 JSON。Claude 常见事件：query_started、assistant_text、tool_use、tool_result、permission_request、permission_resolved、token_usage、终结帧 query_finished，以及 query_failed / query_cancelled / error。DeepSeek 与典型 OpenAI 兼容提供方输出的子集会略精简：仍会包含 tool_use，但通常不会出现 permission_request（工具直接执行，不经交互授权）。

工具权限往返（Claude）

当某次工具调用需要人工批准，流里会出现携带 requestId 的 permission_request 事件；客户端 POST 回结果后 SSE 继续：

curl -s -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"behavior":"allow"}' \
     http://127.0.0.1:7878/v1/agent/permission/<requestId>

拒绝时可传 {"behavior":"deny","message":"…"}，附带给模型阅读的简短原因。

多账号与守护进程复用

在 ask 的 JSON 体中加 "account": "work"，可与 lingcode auth login --account work 对齐，按请求选用不同钥匙串条目。服务端加 --bridge-daemon auto 可重用正在运行的 lingcode bridge daemon-start，通常每轮 Claude 查询可省掉约 200–500 ms 的 Node 冷启动。

默认禁用 CORS，也未内置 TLS——若需在主机之外暴露端口，请在前面加 caddy、nginx、cloudflared 等反向代理与 TLS。

ACP 宿主（acp-serve）

lingcode acp-serve 提供基于 stdin/stdout 的 Agent Control Protocol (ACP)。Zed、gemini-cli 等外部编辑器或 Agent 宿主可在不走 HTTP 的情况下驱动完整 LingCode Agent 循环；已注册的任一提供方皆可。

# stdio 对接 Claude Agent
lingcode acp-serve --agent claude

# DeepSeek
lingcode acp-serve --agent deepseek

# 任意 OpenAI 兼容别名
lingcode acp-serve --agent openai-compat:groq
lingcode acp-serve --agent openai-compat:openrouter

# 指定工作目录（默认当前目录）
lingcode acp-serve --agent claude --cwd ~/my-project

协议为 JSON Lines：外部客户端发 Prompt，stdin/stdout 上持续收到结构化事件——assistant_text、tool_use、tool_result、permission_request，以及 session_finished 等收尾帧。

HardcodedDenyDecider 在每轮往返前先做硬性安全否决；余下的权限请求再由 ACPClientPermissionDecider 转交给外部客户端 allow/deny。凭据解析顺序与 REPL 相同：macOS 钥匙串 → 环境变量 → 配置文件——若你已用 lingcode auth login 存过密钥，一般无需额外配置。

子命令参考

故障排查

lingcode: ANTHROPIC_API_KEY is not set

用 lingcode auth login 搞定,或在 shell 里 export,或 lingcode config set anthropic-api-key sk-ant-...。

lingcode: <PROVIDER_API_KEY> is not set

OpenAI 兼容提供方直接用环境变量。想用自定义变量名:lingcode --provider openai --api-key-env MY_KEY。

lingcode: couldn't find Claude agent bridge

Claude 提供方需要 bridge.mjs,它附带在 LingCode.app 或独立 CLI 压缩包里。要么把 LingCode.app 装到 /Applications,要么用 export LINGCODE_AGENT_BRIDGE_DIR=/path/to/agent-bridge 指向开发副本。

lingcode: bundled Node.js runtime is missing

macOS CLI 压缩包自带 Node 运行时,正常情况下不用自己装。看到这个报错说明自带二进制丢了(安装损坏、手工删过,或 Linux 构建):重装 lingcode(curl -fsSL https://lingcode.dev/install-cli.sh | sh)。也可以装系统 Node.js(nodejs.org)或把 NODE 指向具体路径作为兜底。只有 Claude 提供方用到 Node;OpenAI 兼容提供方走纯 Swift。

被限流 / 429 / overloaded

ask 和 repl 都会自动以指数退避重试(最多 5 次,间隔最长 60 秒)。你会在 stderr 看到 rate limited (attempt N/5) — retrying in Xs…。

App 响应了,但我想要 headless

App 开着时 lingcode ask 默认路由给 App。加 --headless 强制本地执行。

我在终端里粘贴过 API 密钥

去提供方控制台轮换。shell 历史或 tmux scrollback 里的内容都要当作泄露处理。下次用 lingcode auth login(浏览器粘贴)或 lingcode auth set <provider> <key> —— 都不会把密钥打印到 stdout。