Coddy Agent

科迪特工

无发行版友好 利用 为了跑步 代理客户端协议（ACP） 通过stdio进行代理。它作为一个静态友好的Go二进制文件发布，因此您可以将其放入 最小容器图像(scratch, distroless，只读工作区），没有完整的操作系统外壳 在图像内部。

捆绑默认值为 交互式推理与行动 使用文件系统、shell（暴露时）、todo循环， 网页搜索与页面提取(websearch, webfetch)以及MCP工具， 这使得Coddy成为ACP stdio的编码代理 适用于任何兼容的ACP客户端或线束脚本。

如果收紧工具集或 从自动化而不是IDE驱动它。

目录

• 特性
• 快速开始

- 安装 - 构建标签 - 码头工人 - 路径(CODDY_HOME, CODDY_CWD) - 配置

• 操作模式
• 编辑器和IDE集成
• 光标规则和技巧
• MCP服务器集成
• 配置（参考）
• 建筑
• 文档
• 示例（ACP超过stdio）
• 持续会话
• 发展
• 许可证

特性

• 先系安全带 -ACP服务器、会话生命周期、提示、LLM后端、MCP合并、无发行版就绪二进制文件
• ReAct循环 -LLM在推理、行动（工具调用）和观察结果（开箱即用的编码代理角色）之间交替进行
• 两种操作模式 - agent （完全工具访问权限）和 plan （仅计划+文本文件）
• 游标规则支持 -阅读 .cursor/rules/ 当这些路径出现在中时，Cursor使用相同的磁盘布局和技能 skills.dirs
• MCP服务器集成 -连接任何MCP服务器以获取其他工具
• 多供应商法学硕士 -OpenAI、Anthropic、Ollama、任何与OpenAI兼容的API
• ACP协议 -科迪是一个 ACP服务器 (coddy acp)；将其与实现ACP客户端的编辑器或脚本配对（请参见 编辑器和IDE集成)

编辑器和IDE集成

科迪说话 ACP作为服务器 通过stdin/stdout。A兼容 客户 必须产卵 coddy acp 并交换JSON-RPC消息（请参阅 docs/acp-protocol.md 和 examples/acp/).

• 泽德 以及其他支持 外部ACP药物 可以将他们的代理命令指向 coddy acp （具体设置取决于该产品；请参阅其ACP或外部代理文档）。
• 光标桌面 （应用内Agent或Composer） 不 记录一种支持的方式，用自定义代理替换内置代理 coddy acp 二元的。Cursor发布的ACP指南描述 agent acp，在哪里 Cursor自己的代理人 作为ACP运行 服务器 第三方 客户 （例如连接的Neovim或JetBrains集成 到 光标）。这与将Coddy作为本地代理进程运行是相反的。
• 磁盘上的光标样式路径 -Coddy仍然可以从加载规则和技能 .cursor/rules/, ~/.cursor/skills，及其他 skills.dirs 条目在 config.yaml这是与Cursor的文件布局兼容性，而不是充当Coddy运行时主机的Cursor。

快速开始

安装

先决条件

• 去 -与相同的次要版本 go.mod （目前 1.25).
• Git -由Makefile用于嵌入式版本字符串。
• Node.js/npm -只有当你用 http 和 ui （Makefile运行 ui-build 嵌入式资产）。

使用Go安装（快速、默认上游标签）

go install github.com/EvilFreelancer/coddy-agent/cmd/coddy@latest

无论模块运送什么，它都能建造 没有 定制 -tags.为 coddy http，将SPA、调度器和长期内存捆绑在一起， 从源代码构建 带有以下标签（默认值与 / ).

推荐源代码的完整二进制文件（HTTP+UI+调度器+内存）

通过 memory 构建标签以链接长期记忆；可选的HTTP、SPA和调度程序使用它们自己的标签（请参见 构建标签).运行时 memory.enabled 仅当二进制文件包含 memory.

git clone https://github.com/EvilFreelancer/coddy-agent
cd coddy-agent
make build TAGS="http ui scheduler memory"

CLI被写入 build/coddy （不是回购根）。

安装 build/coddy 进入你的路径

make install TAGS="http ui scheduler memory"

• 根 - /usr/local/bin/coddy
• 普通用户 - ~/.local/bin/coddy （把那个目录放在 PATH 如果需要）

无需安装即可构建

make build TAGS="http ui scheduler memory"

手册 go build （与Makefile相同）

当 TAGS 包括 http 和 ui，跑 make ui-build 首先（或依赖 make build，这会触发它）。

make ui-build   # required before go build when using -tags=...,ui,... with http
VERSION="$(make -s print-version)"
go build -tags=http,ui,scheduler,memory \
  -ldflags "-X github.com/EvilFreelancer/coddy-agent/internal/version.Version=${VERSION}" \
  -o build/coddy \
  ./cmd/coddy/

精益 仅限ACP 二进制（否 coddy http，没有嵌入式UI，没有调度程序包）：

make build

在任何本地构建之后，首选 ./build/coddy 或 make install 这样你就不会不小心跑另一个 coddy 已经开启 PATH。请查看 which coddy 和 coddy -v.

完整细节， LDFLAGS，以及 make print-version - docs/build.md.

特工通过标准电话说ACP。一 ACP客户端 （编辑器集成或工具）启动 coddy 一旦配置为生成 coddy acp. coddy -v 或 coddy --version 打印嵌入式构建版本(dev 如果未在链接时设置）。ACP的标志在子命令上生效，例如 coddy acp --help (--log-level, --home, --cwd, --config等等）。

构建标签

使用 Makefile 变量 TAGS 随着 空间 (make build TAGS="http ui scheduler memory"). go build 用途 逗号 (-tags=http,ui,scheduler,memory).

扩展叙事和Docker对齐- docs/build.md.

码头工人

** 描述 docker compose （图像构建参数、体积、烟雾脚本 examples/httpserver/docker.sh).默认图像标签与推荐的完整二进制文件匹配(http, scheduler, ui, memory**).

路径(CODDY_HOME, CODDY_CWD)

• CODDY_HOME （或 coddy acp --home)是代理状态目录。默认 ~/.coddy。该过程创建 sessions/ 和 skills/ Config默认为 $CODDY_HOME/config.yaml.
• CODDY_CWD （或 coddy acp --cwd)是以下情况下的默认会话工作目录 session/new 发送一个空 cwd默认值是启动时的进程当前目录。传递路径的编辑器 session/new 请改用该路径。

配置

CODDY_HOME 默认为 ~/.coddy除非你设定 CODDY_CONFIG 或通过 --config，主配置文件是 config.yaml 在 $CODDY_HOME/config.yaml.

复制示例并编辑：

mkdir -p ~/.coddy && cp config.example.yaml ~/.coddy/config.yaml

如果 $CODDY_HOME/config.yaml 如果不存在，装载机可以使用 config.yaml 在流程工作目录中（从存储库克隆运行时很有用）。看 docs/config.md.

供应商和模型

• providers -命名后端(type: openai 对于OpenAI和OpenAI兼容的HTTP API， anthropic Anthropic）。每 name 必须是ASCII字母、数字、连字符或下划线，以字母开头（它将成为模型id中的前缀）。每一行都有 api_key （字面意思， ${ENV} 文件加载时展开，或为空以读取 NAME_API_KEY 在LLM呼叫时从环境中 NAME 源自 providers[].name 大写字母和映射到下划线的连字符），以及可选 api_base 当API不是供应商默认值时。
• models -可选型号。每 model 字符串是 **`

/** 哪里 **provider_name** 火柴 **providers[].name**可调产品包括 **max_tokens**, **temperature**，可选 **max_context_tokens`**.

• agent - model 选择默认的ReAct模型（必须匹配一个 models[].model 入口）。 max_turns 和 max_tokens_per_turn 绑定一个用户回合。

示例(openai 供应商和 gpt-5.4-mini；将机密存储在环境中，而不是git中）：

providers:
  - name: openai
    type: openai
    api_key: "${OPENAI_API_KEY}"

models:
  - model: "openai/gpt-5.4-mini"
    max_tokens: 400000
    temperature: 0.2

agent:
  model: "openai/gpt-5.4-mini"
  max_turns: 35
  max_tokens_per_turn: 128000

然后导出YAML引用的密钥：

export OPENAI_API_KEY="sk-..."

其他设置（Anthropic、Ollama、非默认设置 api_base，以及基于env的默认值）包含在 config.example.yaml 和 docs/config.md.

操作模式

代理模式（默认）

全任务执行模式。代理可以访问所有工具：

• 读取和写入文件
• 执行shell命令（带权限提示）
• 搜索代码库
• 调用MCP服务器工具

最适合：代码生成、重构、调试、功能实现。

计划模式

规划和文件编制模式。受限工具：

• 读取文件（不写入代码文件）
• 编写/编辑文本和标记文件
• 搜索代码库

计划准备就绪后，切换到 代理 自行建模以获取完整的工具和实现。

最适合：架构规划、编写规范、设计文档、代码审查。

使用编辑器会话模式选择器（或 session/set_config_option).

光标规则和技巧

默认情况下，代理从读取技能文件和规则（请参见 skills 在 docs/config.md):

1. $CODDY_HOME/skills/ （安装技能）

规则支持标准的Cursor frontmatter格式：

---
description: "Go coding standards"
globs: ["**/*.go"]
alwaysApply: false
---

Write all comments in English.
Use fmt.Errorf("context: %w", err) for error wrapping.

看 技能指南 了解详情。

MCP服务器集成

通过MCP服务器连接外部工具。在中全局配置 config.yaml 或 ACP客户端在每个会话中传递。

在配置中添加GitHub MCP服务器的示例：

mcp_servers:
  - name: "github"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      - name: "GITHUB_PERSONAL_ACCESS_TOKEN"
        value: "${GITHUB_TOKEN}"

看 MCP集成指南 了解详情。

配置

完整配置参考 docs/config.md.

关键设置：

providers:
  - name: local
    type: openai
    api_key: "${OPENAI_API_KEY}"
    api_base: "${OPENAI_API_BASE}"

models:
  - model: "local/gpt-4o"
    max_tokens: 8192
    temperature: 0.2

agent:
  model: "local/gpt-4o"
  max_turns: 30

tools:
  require_permission_for_commands: true

建筑

ACP client (editor / script / CI)
        |
    JSON-RPC 2.0 over stdio
        |
    ACP Server Layer
        |
    Session Manager
        |
    ReAct Agent Loop
 /      |       |      \
LLM   Tools    Skills    MCP

看 架构文档 了解全部细节。

文档

• 从源代码构建 -先决条件， make build, TAGS vs go build -tags, build/coddy
• 码头工人 - Dockerfile 和 docker compose
• 建筑 -系统设计和组件概述
• ACP协议 -协议参考和消息格式
• ReAct 智能体 -ReAct循环设计和工具规范
• 配置 -完整配置文件引用
• HTTP API -REST网关(-tags=http)嵌入式用户界面(-tags=http,ui)；包括 /coddy/config 用于从SPA进行实时YAML编辑(#/设置).
• 嵌入式用户界面 -Vite SPA、开发工作流程、构建标签
• 设计.md -UI标记和布局（英文）
• 代理商.md -自动化的repo映射和贡献者注释
• 技能与规则 -光标规则和技能指南
• MCP集成 -MCP服务器集成指南

示例（ACP超过stdio）

examples/acp/acp_e2e_todo.py 是一个以换行符分隔的JSON-RPC线束 coddy acp ( stdbuf -oL，权限自动回复，无结果响应）。在构建自己的最小客户端时将其用作参考，而不是简单地链接 echo 将管线插入管道。

examples/acp/acp_e2e_memory.py 驱动 build/coddy，一个孤立的 CODDY_HOME，以及 RPA_API_KEY 验证召回、持续和可选的降价修剪 $CODDY_HOME/memory。有关标志，请参阅脚本docstring。所有线束概述- examples/README.md.

持续会话

默认情况下， coddy acp 和 coddy http 将每个会话包存储在 $CODDY_HOME/sessions// （默认值 ~/.coddy/sessions/)与 session.json, messages.json一 assets/ 目录，以及 todos/active.md （加 todos/archive/ 当替换完成的列表时）。用以下命令覆盖根 coddy acp --sessions-dir, coddy http --sessions-dir，或 sessions.dir 在 config.yaml。如果无法创建会话目录，则启动失败并出现错误。

• coddy sessions list 打印存储的会话(--sessions-dir 和 --cwd 支持过滤器）。
• coddy acp --session-id 使 下一个 session/new 要么重新打开该文件夹的快照（如果存在），要么创建一个目录名与该id匹配的新捆绑包。
• session/load 恢复历史记录并通知客户端； session/list 列出了ACP感知客户端的捆绑包。

coddy todo工具将活动清单镜像到 todos/active.md.批发 coddy_todo_plan_replace 如果项目不完整，则会被拒绝，直到您完成行或运行 coddy_todo_plan_archive；当每一行都是 completed 移动优先级 active.md 进入 todos/archive/ (todo-.md). coddy_todo_plan_archive 完成打开的行 completed，写道 todos/archive/plan_.md，然后在启用持久性时清除会话计划。

当坚持的计划是 非空的，药剂注入 ### Current todo checklist 将渲染的markdown检查表行添加到系统提示模板中（嵌入式默认值或下的文件 prompts.dir 使用 prompts.agent_prompt 和 prompts.plan_prompt，默认为 agent.md 和 plan.md)via {{if .TodoList}} … {{end}}。当没有可跟踪的内容时，该块会被省略。之前 每个 LLM呼叫在一个 session/prompt 反过来，Coddy会刷新该系统消息，以便在同一ReAct剧集中较早创建或更新的待办事项列表立即可见。

发展

# Run tests
go test ./...
make test

# Example harnesses (see examples/README.md): ./examples/build_coddy.sh && ./examples/test_acp.sh && ./examples/test_httpserver.sh

# Full-featured local binary (HTTP + UI + scheduler), same defaults as Docker
make build TAGS="http ui scheduler memory"

./build/coddy -v    # same as --version

# Run with debug logging (ACP mode); optional --log-output, --log-file, --log-format
coddy acp --log-level debug

# Single-line sanity check only (responses may omit JSON-RPC "result" for nil payloads; prefer examples/acp/acp_e2e_todo.py)
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}' | coddy acp

许可证

此项目根据MIT许可证获得许可，请参阅 许可证 有关详细信息，请访问存储库根目录中的文件。