lcagent-cli

一个从当前仓库架构中抽出来的最小独立 Agent CLI 项目。

当前能力

• lcagent -p "..."：单次非交互执行
• lcagent chat：交互式聊天
• lcagent tools：查看当前工具
• lcagent provider [name]：查看或修改模型 provider
• lcagent model [name]：查看或修改默认模型
• lcagent doctor：检查当前模型配置和接口连通性
• lcagent config set approvalMode auto|manual：切换工具权限模式
• lcagent config set autoContinueOnMaxTurns true|false：切换超限自动续跑
• lcagent config show
• lcagent config set <key> <value>

已实现工具

• read_file
• edit_file
• grep
• run_shell

其中 edit_file 现已支持：

• 单文件 unified diff / patch 应用
• 精确文本替换
• 直引号 / 弯引号不一致时的归一化匹配
• 命中弯引号内容时自动保留原文件引号风格
• 多处命中时提示使用 occurrence 或 replaceAll
• 替换失败时返回更具体的上下文诊断

edit_file 现在有两种模式：

• 文本替换模式：传 path + oldText + newText
• 新建/整文件写入模式：传 path + content；若覆盖已有文件，额外传 replaceEntireFile=true
• Patch 模式：传 patch，也可以额外传 path

Patch 模式当前限制：

• 只支持单文件 unified diff
• patch 需要能对当前文件内容干净应用
• 如果 path 与 patch 头里的目标文件不一致，会直接报错

Windows 下如果模型需要创建目录或文件，优先建议：

• 用 run_shell 执行 Windows 兼容命令，而不是 Bash 专用语法
• 或者直接用 edit_file 的 content 模式创建文件

安装

cd my-agent-cli
npm install
npm run build

如果你想先确认本地最小闭环是否正常，可以直接运行：

npm run smoke

这条命令不会访问模型服务，只会验证：

• lcagent tools
• lcagent config show
• read_file
• grep
• edit_file
• run_shell

发布到公网 npm

先登录 npm 官方仓库：

npm login --registry https://registry.npmjs.org/

发布前先做一次本地打包验证：

npm run build
npm pack

确认 package.json 中的包名还未被占用后，执行发布：

npm publish --registry https://registry.npmjs.org/

如果后续改成 scope 包（例如 @your-scope/lcagent-cli），首次发布时建议使用：

npm publish --access public --registry https://registry.npmjs.org/

从公网 npm 安装和执行

全局安装：

npm install -g lcagent-cli --registry https://registry.npmjs.org/
lcagent --help

不做全局安装时，也可以直接执行：

npx --registry https://registry.npmjs.org/ lcagent-cli --help
npx --registry https://registry.npmjs.org/ lcagent-cli chat

配置

方式一：Anthropic 环境变量

export ANTHROPIC_API_KEY="your-key"

方式二：写入本地配置

npm run start -- config set apiKey your-key
npm run start -- model claude-3-7-sonnet-latest

使用本地 Qwen / OpenAI-compatible 服务

如果你的本地服务提供 OpenAI-compatible 接口（例如 http://127.0.0.1:8000/v1），可以这样配置：

npm run start -- provider openai-compatible
npm run start -- config set baseUrl http://127.0.0.1:8000/v1
npm run start -- model Qwen3-Coder-30B-A3B-Instruct-FP8

或者直接一条命令初始化：

npm run start -- init-local --base-url http://127.0.0.1:8000/v1 --model Qwen3-Coder-30B-A3B-Instruct-FP8

如果你的本地服务需要 token：

npm run start -- init-local --base-url http://127.0.0.1:8000/v1 --model Qwen3-Coder-30B-A3B-Instruct-FP8 --api-key your-local-token

如果你的本地服务需要 Bearer Token：

export OPENAI_API_KEY="your-local-token"

如果本地服务不需要 token，可以不配置 apiKey。

建议第一版优先用代码模型：

Qwen3-Coder-30B-A3B-Instruct-FP8

配置文件默认在：

~/.lcagent-cli/config.json

运行

npm run start -- -p "阅读 README 并总结项目结构"
npm run start -- chat
npm run start -- tools
npm run start -- provider
npm run start -- model
npm run start -- doctor
npm run start -- config set approvalMode manual

注意：chat 和 -p 都依赖一个可用的模型配置。

• 如果你走 anthropic，需要先配置 ANTHROPIC_API_KEY 或 lcagent config set apiKey ...
• 如果你走本地模型，建议先执行 init-local，再执行 doctor，最后再进入 chat

最小闭环验收顺序

推荐按下面顺序验证当前版本：

1. 本地静态能力：

npm run check
npm run build
npm run smoke

2. 本地模型接入（OpenAI-compatible）：

npm run start -- init-local --base-url http://127.0.0.1:8000/v1 --model your-model-name
npm run start -- doctor

如果你使用 Anthropic 官方接口，则把上面两条替换成：

export ANTHROPIC_API_KEY="your-key"
npm run start -- doctor

3. 交互式 chat：

npm run start -- chat

进到 chat 后，建议先做一个最小读文件任务，例如：

• 读取 README.md 的前 40 行并总结项目结构
• 搜索项目里有哪些 edit_file 相关实现

如果 doctor 可通过、chat 能读文件、npm run smoke 通过，就说明当前最小闭环已经稳定可用。

如果 doctor 能跑但 chat 提示缺少 API key，通常不是程序损坏，而是当前配置仍停留在默认的 anthropic 且没有完成认证。先执行 config show 检查当前 provider，再按上面的配置步骤修正即可。

权限模式

lcagent 当前支持两种最小权限模式：

• auto：工具直接执行
• manual：read_file / grep 直接放行，edit_file / run_shell 在执行前询问确认

其中 manual 模式已经裁剪复用了 Claude Code 权限层里的两类思路：

• 权限模式分层思路
• 危险文件 / 危险目录名单（如 .git、.vscode、.claude、shell 配置文件）

如果 edit_file 命中的目标位于这些高风险路径下，确认提示会给出更高风险说明。

如果当前不是交互式终端，manual 模式下的写入/执行工具会被拒绝，并返回明确原因。

当模型触发工具时，CLI 会打印：

• [tool-call] 工具名：后面跟模型传入的原始 JSON 参数
• [tool-result] 工具名：显示工具执行结果
• [tool-result] 工具名 (error)：显示工具失败原因
• 同时附带 cwd、执行耗时、审批状态、失败阶段等元数据，便于排查是校验失败、审批拒绝还是工具执行异常

这样可以直接看出是模型参数字段名不对、路径不对，还是工具执行本身报错。

超限续跑

当前默认配置下，lcagent 在单段运行达到 maxTurns 后，不会立刻报错退出，而是会自动续跑下一段：

• maxTurns：每一段最多运行多少轮，默认 8
• autoContinueOnMaxTurns：达到上限后是否自动续跑，默认 true
• maxContinuations：最多自动续跑多少段，默认 3

也就是说，默认情况下最多会跑 1 + 3 = 4 段。

如果自动续跑次数也耗尽了，CLI 不会只打印一条生硬错误，而是会额外输出：

• 最近的 assistant 文本进展
• 最近几次工具调用
• 最近几次工具结果
• 一个建议的“继续”提示词

常用配置示例：

npm run start -- config set maxTurns 12
npm run start -- config set autoContinueOnMaxTurns true
npm run start -- config set maxContinuations 4

如果你想恢复原来那种“达到上限就停止”的行为：

npm run start -- config set autoContinueOnMaxTurns false

设计目标

• 保留 Claude Code 式的核心代理循环
• 不依赖原仓库的内部 feature gate
• 保持目录清晰，便于后续继续演进

已知限制

• 当前是最小版，没有流式输出
• 工具权限策略还是简化版
• grep 是纯 Node 实现，不如 ripgrep 快
• 当前按 Anthropic Messages API 直接调用，需要有效 API Key

对于 OpenAI-compatible 本地模型：

• 你的服务需要支持 POST /chat/completions
• 最好支持 tool calling / function calling
• 如果不支持 tool calling，Agent 的工具闭环能力会明显下降

可以先用下面这条命令做自检：

npm run start -- doctor

doctor 会额外探测多个端点（如 /v1、/v1/models、/v1/chat/completions），并尽量打印底层网络错误；对于 OpenAI-compatible 服务，还会额外检查 tool calling 是否真的返回 tool_calls。