Local Coding Agent

Local Coding Agent

用于将编码任务从云端 Agent 委派给本机模型的本地执行与安全层。

什么是 Local Coding Agent？

Local Coding Agent 让云端编码 Agent 可以将范围明确的任务委派给本地模型，同时不向该模型开放对代码库的不受限访问权限。通过 MCP、可复用的 Agent Skill 或 local-agent CLI，连接 Codex、Claude Code、Cursor、Windsurf、Cline、OpenCode、Antigravity 或其他兼容的运行环境。云端 Agent 仍负责整体任务；Local Coding Agent 则提供受控的本地执行路径。

调用方 Agent 会发送明确的目标、工作区、允许访问的文件列表和检查项。本地模型会返回一份供审核的提案。本地模型负责提出方案；控制器负责验证。只有在确认声明的文件范围未被越界、补丁通过静态分析，并由真实的外部测试运行器确认配置的检查项通过后，才会报告变更已应用。如果应用后的检查失败，变更会被回滚，并依据记录的文件摘要验证回滚结果。本地模型无法在工作区中不受限制地执行 shell 命令或写入文件。

如果你需要 Windows 界面来进行本地聊天、选择模型、管理会话、查看任务状态和审核变更，请使用 Desktop Harness。终端、脚本、CI 或直接集成编码运行环境时，请使用 CLI。两者使用相同的控制器和安全规则。

Git 和交付流程由你掌控。Local Coding Agent 不会创建提交、推送分支、发布版本，也不会自行下载模型。

安全门禁会拒绝的情况

apply_proposal、local-agent apply 和桌面应用中的应用操作均由同一个安全门禁控制：

• 如果补丁涉及声明范围之外的文件，则会在修改工作区前被拒绝（error.kind: patch_outside_scope）。
• 如果没有针对性检查项，则拒绝应用——没有外部验证依据，就不应用（error.kind: apply_requires_checks）。
• 如果补丁未通过应用后的检查，则会回滚；结果为 "rejected"，且 error.kind 为 post_apply_check_failed。
• 如果无法依据记录的基线确认回滚结果，则会报告 workspace_modified: true、workspace_state: "unknown"，风险类型为 rollback_failed——绝不会将其报告为已干净恢复。

选择下载内容

当前公开版本：v1.1.1

如果你要用于终端工作流、脚本、CI 或与其他 AI 编码环境集成，请选择 CLI 版本。它提供 local-agent 命令、MCP 服务、Agent Skill、诊断工具、会话、模型工具和任务委派功能。

下载 CLI wheel 或 CLI 源码归档。Windows 用户可以下载 Desktop Harness 安装程序，并使用 SHA256SUMS.txt 验证已发布的文件。

v1.1.1 版本包含 CLI 归档文件和 Windows Desktop Harness 安装程序。本地推理始终在本地进行；请求实时模型响应前，请安装 Ollama 或运行兼容的本地模型服务。

桌面端 Harness

打开 Harness，选择一个工作区，选取一个本地模型，然后开始工作。桌面应用将完整的本地编码工作流整合到一个专注的界面中：

• 交互式聊天，用于提问、获取解释和处理日常编码工作。
• 聊天、构建、规划和自动模式，适用于不同类型的请求。
• 委派任务，将范围明确的编码更改交给本地模型处理。
• 工作区会话，方便你返回之前的对话和任务。
• 模型发现、模型配置、上下文设置、硬件遥测和诊断。
• 当本地后端已就绪、不可用或需要关注时，显示清晰的状态消息。
• 应用更改前，可检查代码更改并运行检查。

下面的截图展示了应用加载 qwen2.5-coder:7b，并针对所选工作区返回真实响应。

CLI 安装

要求：

• Python 3.10 或更高版本。
• Git 位于 PATH 中，以便执行工作区操作。
• Ollama 或兼容 OpenAI 的本地模型服务，用于实时推理。

安装 CLI 包：

pipx install local-coding-agent

或者从检出目录安装：

git clone https://github.com/pvnc228/local-coding-agent.git
cd local-coding-agent
python -m pip install -e .

检查安装情况：

local-agent doctor
local-agent test-run --mock

当输出将由其他工具使用时，在支持的命令中添加 --json。

连接其他 AI 编码 Agent

Local Coding Agent 可通过 MCP 或 Agent Skill 向其他 AI 编码环境提供其能力：

local-agent init-mcp --auto --write
local-agent init-skill --write

当客户端需要明确的命令时，手动启动 MCP 服务：

local-agent serve-mcp --workspace . --enable-tasks

客户端配置示例请参阅 docs/MCP_INTEGRATION.md，可复用的 Agent Skill 请参阅 skills/local-coding-agent/SKILL.md。

典型的编码请求

1. 选择一个工作区和本地模型。
2. 提出问题或描述你希望进行的更改。
3. 在应用中检查建议的代码更改。
4. 运行相关检查，确认无误后应用更改。

应用让工作流一目了然：你可以查看正在更改的内容、正在运行的检查，以及本地后端是否可用。提交、标签、推送和发布仍由你掌控。

CLI 命令

命令	用途
local-agent delegate	将范围明确的编码任务交给本地模型。
local-agent decompose	将较大的请求拆分为较小的编码任务。
local-agent apply	应用经过审查的更改并运行检查。
local-agent chat	运行提示词或持久聊天会话。
local-agent sessions	列出或检查已保存的会话。
local-agent profiles	检查已配置的模型配置。
local-agent memory	检查模型内存和 VRAM 设置。
local-agent calibrate	根据 VRAM 预算计算安全的工作进程范围。
local-agent benchmark	运行本地编码基准测试。
local-agent doctor	诊断 Python、Git、Ollama、RAM、VRAM 和模型。
local-agent monitor	提供本地指标仪表板。
local-agent test-run --mock	运行确定性的本地工作流检查。

示例：

local-agent chat "Explain what context_manager.py does"
local-agent chat --repl --session-id refactor-session
local-agent delegate --task task.json --model qwen2.5-coder:7b --json
local-agent apply --patch-file patch.diff --workspace . --file src/foo.py --check "pytest tests/"
local-agent monitor --port 8765

打开 http://127.0.0.1:8765/dashboard，查看队列负载、延迟、每秒令牌数和更改记录。

CLI 还提供一些预览功能界面，它们不属于稳定契约，可能会随时更改，恕不另行通知：ui/app、lsp、serve-acp、skeletonize、lint-patch、scan-models、spill-read 和 grep。稳定且经过测试的命令集为上表中的命令，以及 desktop、chat、serve-mcp、init-mcp 和 init-skill。

实测结果与局限性

已发布的数据来自一个包含 20 项任务的测试套件，因此应将其视为参考，而非定论：

• 在该测试套件中，qwen3.8-27b-q4 的正确率为 100.0%，95% Wilson 置信区间为 [83.9%, 100.0%]；qwen3-8b-q6k 的正确率为 90.0%，置信区间为 [69.9%, 97.2%]。区间较宽是因为样本量较小，并非舍入误差。
• 在此测试框架中，小模型可以处理单文件任务；跨文件协作（能力阶梯中的第 3 级）则需要宿主 Agent 先将任务分解为原子化任务包。
• 结果取决于模型和硬件。在依据任何数据前，请先使用 local-agent benchmark 复现结果。

请参阅 docs/BENCHMARK.md，了解方法和完整数据表。

本地模型

模型配置文件描述提供商、模型、上下文窗口、生成限制和保持运行行为。Harness 可以发现已安装的 Ollama 模型和本地 GGUF 文件，而 CLI 会向脚本和集成提供相同的信息。

local-agent profiles list --json
local-agent memory status --json

文档

• 快速入门
• MCP 集成
• 安全策略
• 更新日志
• 架构参考
• 协议参考
• 基准测试方法

许可证

Local Coding Agent 根据 MIT License 发布。