CodeZaiku

CodeZaiku

一款可在本地模型或托管 API上运行的编码与开发工具。它是一个面向终端的 AI 编码 Agent，类似于 Claude Code 或 aider，可搭配运行在 Ollama、llama.cpp、LM Studio 或任何 OpenAI 兼容服务上的小型模型使用。它还会审查 git 差异，在你允许时修复损坏的 docker compose 栈并支持回滚，报告服务器 Docker 容器中的安全问题，研究问题并提供引用来源，还可作为 MCP 服务、ACP Agent 运行，或输出 JSON 供其他 Agent 使用的命令运行。

大多数此类 Agent 都假设通过他人的 API 使用前沿模型。CodeZaiku 则反其道而行——使用你自己硬件上的 9B 模型，并通过工具链让这种方式切实可行：使用确定性证据而非模型猜测，为所有执行操作的行为设置防护层，并在每次更改后验证，必要时回滚。

它可连接任何 OpenAI 兼容服务，且不附带权重。参考配置为 9B。

→ ARCHITECTURE.md — 工作原理 → LIMITATIONS.md — 实测数据

快速开始

你需要一个OpenAI 兼容模型服务，以及 JDK 21+；除非你选择附带 Java 运行时的构建版本（从 0.3.2 起，每个平台各有一个；如果缺少 Java，安装程序会自动选择相应版本）。CodeZaiku 不附带权重。

Linux 是受支持的平台。macOS 可运行编码和研究功能（也可通过 ssh 操作远程 Linux 主机）；Windows 可在 WSL2 下运行。另提供容器镜像。参见 PLATFORMS.md。

三种使用方式

在终端中自行使用 — 继续阅读下文；命令见 可以用它做什么。

作为其他 Agent 或编排器的后端 — CodeZaiku 既是后端，也是工具。它支持 CLI 子进程约定（codezaiku run）、ACP（codezaiku acp）和 MCP（codezaiku mcp）。 约定、结果格式和故障模式见 DEPLOYING_AS_A_BACKEND.md；建议从那里开始，而不是从这里开始。

在 Wyrdsekai 中使用 — CodeZaiku 在 Wyrdsekai 旗下发布，是 Wyrdsekai 可调用的编码后端之一：你向这个伴侣提出需求，它就会把工作交给 CodeZaiku。 WITH_WYRDSEKAI.md 是上文的简要版本——只介绍接线方式，以及两个容易让人卡住的问题。CodeZaiku 不依赖 Wyrdsekai，可独立运行。

安装

二进制制品只有一个，且与平台无关。 CodeZaiku 是不含原生组件的 JVM 字节码，因此同一个 tarball 可安装在 Linux、macOS 和 Windows 上——无需查找 .pkg 或 .msi，也不需要它们。

Linux 是参考平台。macOS 和原生 Windows 也经过了实测，并且安装程序已在这三种平台上通过全新解压验证。在 Windows 上，请从 Git Bash 安装——工具链会通过 bash 调用外部命令，而 Git for Windows 提供了它。各平台的安装步骤，以及每个平台支持与不支持的功能，参见 PLATFORMS.md。 Linux 和 macOS：

curl -fsSL https://codezaiku.org/install | sh

Windows，在 PowerShell 中运行（还需要安装 Git for Windows——此工具会通过 bash 调用 shell）：

irm https://codezaiku.org/install.ps1 | iex

只有脚本来自 codezaiku.org；程序包和校验和均来自同一个 GitHub 版本发布页。该 URL 提供的是此仓库中的 scripts/install-remote.sh（以及 scripts/install.ps1），内容完全一致——你也可以先在此处阅读，再将其与网站提供的版本进行比较。两个安装程序都会获取版本发布包，并在安装任何内容之前，使用该版本发布页自带的 SHA256SUMS 对其进行校验——校验不匹配时会拒绝安装。只有脚本来自上述 URL；程序包和校验和均来自同一个 GitHub 版本发布页，因此脚本无法提供与校验和不匹配的程序包。通常都应谨慎对待将脚本通过管道传给 shell 的做法：先获取脚本并阅读，再决定是否运行。

安装位置为 ~/.local（Windows 上为 %LOCALAPPDATA%\Programs）。使用 CODEZAIKU_PREFIX 可指定其他位置，使用 CODEZAIKU_VERSION 可固定版本。

机器上还没有 JRE？ 在 Debian 或 Ubuntu 上，请改为下载最新版本中的 .deb——它声明了 JRE 依赖，因此 apt 会为你安装 JRE：

sudo apt install ./codezaiku_0.1.1_all.deb

这些一行命令有意不自行安装 JRE：通过管道传给 shell 的脚本不应调用 sudo。它们会检查是否已有 JRE；如果没有，就会安装附带自身运行时的对应平台构建版本（codezaiku-<version>-<platform>.tar.gz，自 0.3.2 起提供；也可以设置 CODEZAIKU_RUNTIME=1 明确请求该版本），而 codezaiku update 会让这类安装继续使用相同类型的版本。

如需升级，请运行 codezaiku update now，或再次运行相同的安装命令。update now 会获取最新版本，根据该版本发布页的 SHA256SUMS 进行校验，然后替换现有版本；下次启动时会运行新版本。若已安装 ResearchZosho，该命令随后还会调用 ResearchZosho 自己的更新程序执行相同操作，并告知各自的更新结果。每个程序都由自己的更新程序替换文件，因此两个程序同时更新时不会冲突：后启动的更新程序会发现前一个正在更新，然后停止操作。在 Windows 上，CodeZaiku 运行时无法替换自身文件，因此需要重新运行安装命令。安装程序每次都会解析最新版本，并替换旧安装，而不是覆盖旧文件，因此不会遗留过时文件。~/.codezaiku 中的配置和数据不会受到影响。使用 sudo apt install ./codezaiku_<new>_all.deb 可原地升级 .deb，并保留 /var/lib/codezaiku；如果你启用了 codezaiku.service，升级不会重启该服务，而是提示你在方便时重启。

tar xzf codezaiku-0.1.1.tar.gz          # unpacks a ready-to-run ./codezaiku
./codezaiku/bin/codezaiku --version     # works immediately
sudo mv codezaiku /opt/codezaiku
sudo ln -s /opt/codezaiku/bin/codezaiku /usr/local/bin/codezaiku

如果你想自行构建或参与开发，可以从源代码开始：

git clone https://github.com/Wyrdsekai/codezaiku.git && cd codezaiku

# 1. install — builds and puts `codezaiku` on your PATH (~/.local by default;
#    --system for /usr/local, --prefix DIR for anywhere else)
scripts/install.sh

# 2. point it at your model server (install.sh already wrote a starter config)
codezaiku setup               # the first ten minutes: the model (found, served on demand, or a hosted key), web search, your editor's agent over MCP, the library if wanted
codezaiku model serve install # this machine's memory, on demand: the measured model, llama.cpp behind a proxy that starts it when asked and stops it after 20 idle minutes (on Linux llama.cpp's container for the GPU it finds: NVIDIA, AMD or Intel; Metal on macOS, Vulkan on Windows)
codezaiku model detect        # finds Ollama / llama.cpp / LM Studio / vLLM if running
codezaiku model use http://localhost:8200
codezaiku model add deepseek openrouter deepseek/deepseek-v4.1-flash --prices 0.032/0.144/0.002   # a hosted model under a name,
codezaiku model key openrouter --file ~/openrouter-key.txt                                        # its key kept for its host,
                              # chosen per job: codezaiku code . "…" --model deepseek; `codezaiku spend` says what the jobs cost

# 3. check the environment — names exactly what is missing and how to fix it
codezaiku doctor

# 4. confirm the model answers and can call a tool
codezaiku smoke

安装包包含自己的启动器、JAR 文件和知识库，运行时不会下载任何内容。它不包含 JVM——install.sh 会检查是否安装了 JDK 21+，若未找到则会停止。程序也不包含模型权重。scripts/install.sh --uninstall 会移除程序，但保留 ~/.codezaiku——其中包含你的配置、已学习的卡片、研究发现和审计记录。--purge 也会移除这些内容，但会先列出将要删除的内容并要求你确认。

如果不想安装，但要在仓库中进行开发，可以直接运行检出目录中的 bin/codezaiku。

如果你还没有服务端：

docker run -d --name codezaiku-drive -p 8200:8200 \
  -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/<your-model>.gguf --port 8200 --host 0.0.0.0 --jinja --ctx-size 32768

如需在自己的 AWS 账户中使用自己的 AWS 登录信息来调用模型（Amazon Bedrock），请参阅 BEDROCK.md。 --jinja 是必需的——没有它，模型会把工具调用作为普通文本返回，一切都无法正常工作。 请参阅 MODELS.md，了解运行框架对模型的要求、我们测评了哪些模型，以及为什么 codezaiku smoke 才是关键检查。

Debian / Ubuntu

sudo apt install ./codezaiku_0.1.1_all.deb     # build it: packaging/deb/build-deb.sh

安装到 /opt/codezaiku，并提供 /usr/bin/codezaiku。其中包含一个 systemd 单元，但不会启用——CodeZaiku 可以修改正在运行的系统，因此启动它必须是有意为之的操作。

验证下载的内容

每个发行版资源都附带 SHA256SUMS 和一个 Sigstore 捆绑包（<asset>.sigstore.json）：

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify codezaiku-0.1.1.tar.gz --repo Wyrdsekai/codezaiku \
  --predicate-type https://codezaiku.org/attestation/release/v1

gh attestation 需要 GitHub CLI 2.49 或更高版本。较旧的 gh 会报告 unknown command，却不提示原因——在断定签名有问题之前，请用 gh --version 检查版本。

该签名表明，在对应标签上运行的发行工作流认可了这些确切的字节。它证明的是真实性，而非构建来源——这些构件是在真实硬件上构建和验证的，而不是在 CI 中，因为没人运行过的构件不值得发布。发行资源不可变；修复会作为新版本发布，绝不会重新上传。

你可以用它做什么

codezaiku help                                  # all commands, grouped by intent

与它对话

codezaiku chat ~/myproject

一个可以在终端中与你对话的编码助手——与 Claude Code、Codex CLI 或 aider 属于同类工具，不同之处在于，你可以自行选择它背后的模型：在自己的硬件上运行的模型，或托管 API。输入你的需求——“为什么登录测试会失败？”、“给上传器添加重试机制”、“查查其他项目是如何处理这个问题的”——它就会读取你的代码、进行修改、运行命令或搜索网络，然后向你汇报。你可以逐轮引导它。

默认情况下，它会在进行任何更改或运行任何命令前征求同意，并先向你展示具体更改。你可以对此次操作作出确认，或选择“始终允许”该命令。/undo 可以逐步撤销它的操作。对话会被保存，之后可以继续；/remember 则会让某条信息在该项目的所有后续对话中保持可用。在聊天中输入 /help，可以查看其他所有功能——后台任务、委派工作给第二个 Agent、切换模型、费用跟踪。

codezaiku v1 ~/myproject 会通过与 OpenAI 兼容的 API（/v1/chat/completions）提供同一个助手，因此 Open WebUI 这样的聊天界面可以作为前端。通过该接口，它只能读取，不能进行任何更改——API 无法向你征求许可，因此不会被授予任何需要许可的能力。

研究问题

codezaiku research "your question" broad
codezaiku research "your question" fan

它会搜索网络、阅读网页，并撰写附有来源引用的答案。broad 是一位独立工作的研究员。fan 会把问题拆分成多个部分，并行研究这些部分，让评论者检查覆盖范围是否确实充分，然后撰写综合答案——速度较慢，但面对包含多个部分的问题时效果好得多。

搜索开箱即用，配置后端后效果更佳。 如果没有配置后端，web_search 会回退到 Wikipedia 和学术文献（Crossref 和 OpenAlex）：按 DOI 搜索参考页面和论文，而非整个网络。每次研究运行也都会使用 scholar_search 搜索按 DOI 索引的文献，无论配置了什么后端。要搜索整个网络，有两个选项，推荐第一个：

codezaiku config set CODEZAIKU_BRAVE_KEY <key>        # recommended: Brave Search API
codezaiku config set CODEZAIKU_SEARXNG http://host:8888   # or: your own SearXNG instance

Brave Search API 提供免费套餐（每月 2,000 次查询），搜索结果也明显更好——搜索工具的效果取决于它搜索的内容。SearXNG 完全可自托管，无需账号，但它聚合的公共搜索引擎在持续使用时会限制请求频率。如果两者都已配置，会优先使用 Brave，SearXNG 作为备用。配置其中任意一个，也会启用 chat 中的网络搜索功能。

研究运行找到的内容会被保存。~/.codezaiku/research 中的研究记忆会保存每条发现及其来源；下次研究相关问题时，会从已有内容开始，而不是从零开始。这是内置功能：无需安装其他任何东西即可使用。 对于真正的研究——那种耗时数小时，最终会产出一份可供核查的报告的研究——可以使用同一系列中的独立程序 ResearchZosho。codezaiku install researchzosho 会获取并验证它，然后运行其安装程序。之后，聊天中的 /research 文件会使用它运行，/librarian 会询问它掌握了什么，而它掌握的内容会注入每一轮对话。研究记忆中的问题会作为开放问题交给它。发布新版 ResearchZosho 时，codezaiku doctor 和聊天都会提示；codezaiku update now 会调用 ResearchZosho 自带的更新程序进行安装，资料库和设置都会保留。

在代码库上工作

codezaiku code ~/myproject "add pagination to the /items endpoint"
codezaiku decompose ~/myproject "add an admin dashboard with login and audit view"
codezaiku review ~/myproject HEAD~3             # read-only review -> findings

code 会持续进行同一段对话，直到达成目标。适用于模型可以一次掌握整个任务的情况。decompose 会先将目标拆分为有序的部分，然后使用同一循环执行计划，并将计划固定为每轮都会重新注入的 TODO——因此，完成第一部分后，你就会得到一个正在运行的程序，并在此基础上逐步扩展。适用于任务足够庞大、模型可能因此失去思路的情况。loop 是 code 的旧名称，仍然可用。

运维一个技术栈 — 感知、定位故障服务、修复、验证，失败时回滚

codezaiku fix myproject propose                 # diagnose and propose (default, safe)
codezaiku fix myproject guarded                 # act, behind the full guard stack
codezaiku watch myproject propose 60            # continuous: fix on degraded, else report
codezaiku investigate myproject                 # diagnose only — capped at localize, never acts

范围可以是本地的（myproject）、远程的（ssh://host/myproject），也可以是容器（docker://name）。其他内容——健康检查端点、验证命令——都会自动发现。

运维整台机器 — 同一个运维程序，只是边界设为整台机器，而非单个技术栈

codezaiku triage local                          # enumerate the box, report what is broken
codezaiku triage local "" 20 guarded            # ...and repair the unhealthy compose stacks
codezaiku watch-machine local 300               # the same sweep on a loop, as a daemon

triage 会枚举它能看到的所有内容——compose 技术栈、故障的 systemd 单元、主机磁盘和内存——针对每个不健康的技术栈运行 SRE 运维程序，并将 systemd 和主机检查结果呈现给人工处理。每个技术栈仍受爆炸半径和权限阶梯约束，因此扩大边界不会扩大任何单项修复可触及的范围。

请注意默认设置的差异，因为这是整机命令比单个技术栈命令更不保守的唯一之处：除非传入 guarded 或 unattended，否则 triage 只会报告；而 watch-machine 默认使用 guarded——它是一个旨在保持机器健康的守护进程，因此会采取行动。如果你希望它只监控，请明确传入上限：codezaiku watch-machine local 300 "" propose。在实际机器上通过 systemd 运行它。

审查安全态势 — 仅报告，绝不自动修复

codezaiku secure local

根据实时来源研究问题

codezaiku research "what changed in the Foo API in v3" depth

由另一个 Agent 驱动

codezaiku run --text "add pagination" --output-format json   # one task, one JSON result
codezaiku acp                                   # Agent Client Protocol v1 agent on stdio
codezaiku mcp                                   # MCP server on stdio, all surfaces exposed
npx -y @wyrdsekai/codezaiku-mcp                 # the same, from any client that runs npm packages; installs the release if needed
codezaiku serve 7070                            # HTTP: POST /fix, GET /health, GET /audit

安全性

运维程序可以更改你的系统，因此默认设置较为保守，防护措施不可省略。

• 权限阶梯 — observe < localize < propose < guarded < unattended。默认值为 propose：它会告诉你要运行什么命令，但不会运行。未经验证的修复绝不会自动应用。
• 爆炸半径为 1 — 修复只能影响已定位故障的服务，不能触及其他内容。
• 回滚 — 破坏性变更前创建快照，变更后进行验证，验证失败时恢复。这里有一个反事实案例：开启此功能后，模型损坏数据库配置时，系统进行了回滚，技术栈恢复正常；关闭此功能时，同样的故障会导致服务停机。
• 危害检查 — 修复目标的同时破坏健康依赖项，仍属于失败。
• 紧急停止开关 — CODEZAIKU_OPS_HALT=on 会立即强制切换到 observe。
• 安全问题在权限阶梯的所有级别都只会报告，不会自动修复。 错误的可靠性修复会重启服务；错误的遏制操作则会封锁你自己的负载均衡器。

不可信输入会被视为不可信：容器日志可被攻击者写入；在进行结构性修复之前，通过日志实施的注入曾在两个模型层级上 40/40 次引导运维程序。参见 ARCHITECTURE.md §6。

它不是什么

• 不是前沿编码 Agent。 9B 模型在 SWE-bench Lite 上约为 1/8；重构为 0/8。它无法替代基于大得多的模型构建的工具。
• 尚未达到生产环境的稳健性。 目前还没有长时间运行的测试证据。
• 不是多 Agent 框架。 一个循环、出色的工具、严格的测量。早期的黑板式 Agent 架构曾经过设计并部分构建，后来被移除。

完整的说明见 LIMITATIONS.md。

仓库结构

特意将 bench/ 一并发布。LIMITATIONS.md 中的每个数字都是通过这些工具组得出的，包括那些结果不理想的数字。

文档

• ARCHITECTURE.md — 设计
• LIMITATIONS.md — 实测数据
• MODELS.md — 选择和运行模型服务
• PLATFORMS.md — Linux、Docker、macOS、Windows
• CONFIGURATION.md — 六项重要设置及其他设置
• DEPLOYING_AS_A_BACKEND.md — 在其他 Agent 或编排器下运行
• WITH_WYRDSEKAI.md — 将其配置为 Wyrdsekai 编码后端
• ROADMAP.md — 后续计划，按测量结果所显示的阻碍因素排序
• CONTRIBUTING.md — 包括测量规则
• SECURITY.md — 问题报告方式及 Agent 自身的威胁模型

联系。 Bug 和功能请求请提交到 issues，方便其他人查看问题及答复。其他事宜请联系 [email protected]。漏洞请发送至 [email protected] 或提交私人安全公告——详见 SECURITY.md；行为规范相关问题请联系 [email protected]。

相关项目

CodeZaiku 是 Wyrdsekai 的一部分，其姊妹项目是 ResearchZosho，这是一个研究资料库：它会保存研究运行所得的内容，根据来源核查结论，并依据所持资料回答问题。 运行 codezaiku install researchzosho 即可将其安装在 CodeZaiku 旁边；两者共用一个模型服务，因此一台机器上的一个按需模型即可同时为它们提供服务。

许可证

Apache 2.0 — 详见 LICENSE。