korg-ledger

English · 简体中文 · 繁體中文

korgex

终端里的 AI 编码伙伴——每一步都有据可查。

用通俗的英语告诉 korgex 你想做什么——“修复失败的测试”“添加一个健康检查端点”——它就会读取你的代码、进行修改、运行测试，并准确展示它做了什么。它免费且开源，支持你喜欢的各种 AI（Claude、ChatGPT、Gemini、Grok，或在你自己的电脑上运行的私有模型），因此你不会被某一家公司的产品锁定。

与众不同之处： korgex 所做的一切都会保存到防篡改记录中，供你日后核查。如果有人改动了这份记录——哪怕只改了一个字符——korgex 都能证明。它是可以审计的编码助手，而不是只能寄希望于值得信任的助手。

_{面向开发者：原生支持终端、先规划后执行，同时支持 Anthropic 和 OpenAI 的工具调用协议，可运行于任何兼容 OpenAI 或 Anthropic 的模型（包括通过 Ollama 使用本地模型），可连接任意 MCP 服务，支持实时流式输出，并将每次运行记录到哈希链式因果账本中，可通过 korgex verify 核查。采用 MIT 许可证。}

$ korgex "add a /healthz endpoint that returns 200 with uptime"
➤ Read(file_path=/app/routes.py)
➤ Edit(file_path=/app/routes.py, old_string=..., new_string=...)
➤ Bash(command=pytest tests/test_routes.py -q)
✓ Added GET /healthz returning {"status": "ok", "uptime_seconds": ...}

$ korgex verify
  ✓ ledger intact — 7 events, hash-chain + causal DAG verified

---

目录

• 安装
• 快速入门
• REPL——实时交互
• 工作原理
• 可验证的认知
• 工具
• 功能
• 安全与沙箱
• CLI 参考
• 环境变量
• 多模型路由
• MCP 集成
• 插件
• 流式 TUI
• 架构
• 项目结构
• 开发与测试
• 构建与发布
• 故障排除
• 已知限制
• 许可证

---

安装

从 PyPI 安装（推荐）

pip install -U korgex          # or, for an isolated global CLI:
uv tool install korgex@latest

需要 Python ≥ 3.10（已在 3.10、3.11、3.12、3.13 上测试）。

从源代码 / 最新 main 安装

git clone https://github.com/New1Direction/korgex.git && cd korgex && pip install -e .
# or, without cloning:
pip install git+https://github.com/New1Direction/korgex.git

---

快速入门

# 1. Connect a provider (interactive — saves to ~/.korgex/config.json)
korgex setup
# …or just export a key; any of these works:
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
export KORGEX_API_KEY="sk-or-v1-..." KORGEX_API_URL="https://openrouter.ai/api/v1"   # OpenRouter
export KORGEX_API_URL="http://your-gpu-box:8000/v1"   # self-hosted vLLM/llama.cpp → korgex --model Qwen2.5-Coder-32B "…"

# 2. Run the agent on a naked prompt
korgex "fix the failing test in tests/test_auth.py"

# 3. Or pick a model / mode
korgex --model claude-sonnet-4-6 "refactor src/handler.py"
korgex --mode plan "design a rate limiter for the API"
korgex --quiet "list the python files in src/"     # no TUI — pipe-friendly

# 4. Prove the run wasn't altered afterward
korgex verify

不带提示词直接运行 korgex，即可进入交互式 REPL。

---

REPL — 实时交互

直接运行 korgex，即可开启流式多轮会话。它会连接你的 MCP 服务，读取项目规则，并为每个会话保留回退日志。

斜杠命令

命令	功能
/loop <task>	无人值守地处理任务列表——逐轮自动继续，直到完成，并设有硬性上限（按 Ctrl-C 停止）。
/diff [n]	查看上一轮（或第 n 轮）的彩色差异。
/rewind [n]	列出撤销点，或将文件恢复到提示词 n 之前的状态。
/skills · /skills curate	列出 korgex 学到的技能（✦）；整理会合并相近的技能。
/tasks · /jobs	查看实时任务清单和后台 shell 作业。
/plan [on|off]	计划模式——在你批准 Agent 的计划之前只读。
/model [id]	显示带价格的模型菜单，或在会话中切换当前模型。
/verify · /cost	验证会话账本；根据记录的令牌显示预估花费（$）。
/resume [id]	将先前会话的转录重新载入上下文，并从上次中断处继续。
/<name> [args]	运行自定义命令——来自 .korgex/commands/ 的 Markdown 提示词（或 /code-review、/build-fix、/checkpoint 等内置命令）。
/clear · /help · /exit	重置对话 · 帮助 · 退出。

行内快捷方式

• @path/to/file ——提及文件，其内容会被载入本轮：refactor @src/auth.py to use @src/db.py。
• !command ——在当前位置运行 shell 命令：!git status、!pytest -q。

项目规则。 korgex init 会生成 AGENTS.md；korgex 会在每次会话中自动读取它，以及目录树中所有上级目录内的 AGENTS.md 和 .korgex/rules/*.md，从而遵循你的团队规范。

提示词缓存会在多轮之间保持系统提示词和工具处于热状态（OpenAI/Gemini/Grok/DeepSeek 上自动启用；Claude/Qwen 使用 cache_control 断点）。设置 KORGEX_CACHE_STATS=1 可查看每轮的缓存命中情况——每次命中都会记录到账本，因此 korgex cost 会按实际折扣费率计算缓存令牌的价格（并显示缓存为你节省的费用），你还可以用 korgex verify 验证。

---

工作原理

flowchart TD
    U["You — prompt or REPL"] --> CLI["korgex CLI / REPL"]
    CLI --> AG["KorgexAgent loop<br/>plan → act → verify"]
    AG -->|model id| PB{Provider}
    PB -->|"claude / anthropic/*"| ANT["Anthropic SDK"]
    PB -->|everything else| OAI["OpenAI-compatible SDK<br/>OpenAI · OpenRouter · Ollama · Grok · DeepSeek"]
    ANT --> TR["Tool router<br/>(src/tool_abstraction.py)"]
    OAI --> TR
    TR --> BT["Built-in tools<br/>Read · Edit · Bash · Grep · …"]
    TR --> MCP["MCP servers<br/>(any in mcp.json)"]
    TR --> CA["CodeAct kernel<br/>code = the action (opt-in)"]
    BT --> LED[("korg-ledger<br/>hash-chained + causal DAG")]
    MCP --> LED
    CA --> LED
    LED -. "verify · trace · why · cost" .-> U

该 Agent 在设计上与提供商无关：工具架构会针对不同提供商进行转换（Anthropic 使用 {name, description, input_schema}，OpenAI 使用 {type:"function", function:{…}}），响应会规范化为通用格式，工具结果则会按提供商所需的消息结构进行格式化。每次工具调用——无论是内置工具、MCP 工具还是 CodeAct——都会在发生时记录到账本。

---

可验证的认知

简单来说： korgex 会记录自己所做的一切——读取的每个文件、运行的每条命令。每条记录都会与前一条封存连接，就像链条中的环节，因此，之后任何人只要更改、添加或删除哪怕一条记录，链条就会明显断裂。由此产生的是对 AI 实际所做事情诚实、可核验的证明，可用于审计、合规、调试，或只是求个安心。据我们所知，没有其他编码 Agent 能做到这一点。

深入来说：每次运行都会记录到防篡改的因果账本中，而非不透明的日志中。每个事件都会通过哈希（prev_hash/entry_hash）与前一事件相连，并且通过因果关系（triggered_by）与触发它的事件相连——这样就能用密码学方式证明整个会话完好无损，并检测篡改、删除、重排或拼接，将问题定位到违规事件。

flowchart LR
    subgraph chain["korg-ledger — each event hash-linked to the last"]
      direction LR
      E0["prompt<br/>a1f3"] --> E1["Read<br/>7c0e"] --> E2["Edit<br/>b42d"] --> E3["Bash: pytest<br/>9d11"]
    end
    E3 --> V{{"korgex verify"}}
    V -->|chain intact| OK["✓ proven unaltered"]
    V -->|"edit / splice / reorder"| BAD["✗ localized to the bad event"]

korgex verify                 # prove the recorded run wasn't altered (exit 0/1, CI-friendly)
korgex trace                  # the causal trace — what the agent did + what caused it
korgex why src/auth.py        # walk the causal chain back from a file change to its prompt
korgex recall "rate limiter"  # pull lean, verified context for a query — retrieve, don't carry
korgex cost                   # estimated $ spend for the session, from recorded token counts
export KORG_LEDGER_HMAC_KEY=… # make the chain tamper-PROOF, not just tamper-evident

记忆漂移。 记住的事实会锚定到其来源的 sha256 基准值，因此来源发生变化时，过时程度会成为精确的信号——而保留／刷新／丢弃的协调决策本身也会记录到账本中。

korgex drift                  # scan persistent memories for drift vs their source baselines (exit 0/1)

使用你已有的审计日志——并分享证明。 korgex audit 会将已有的会话（自动发现 Claude Code 日志）导入可验证的链中。添加 --html 后，就能生成一个独立的文件，收件人可在浏览器中自行重新验证——其中还包括一个实时的篡改测试，会故意破坏链条，让任何人都能亲身验证证据。无需设置、无需付费，也不会发起网络请求。

korgex audit --html audit.html
#   audited <session> → 2,319 ledger events
#   chain:  ✓ INTACT — tamper-evident, cryptographically verifiable
#   report: audit.html  ← open in any browser; it re-verifies itself

korgex import transcript.json     # replay any vendor's session into a korg-ledger@v1 journal
korgex trajectory --out train.jsonl   # export the journal as a provenance-stamped training trajectory

给对方一份凭证。 korgex receipt 会生成一个便于携带的单文件，用于证明一次运行所做的事情——其中包含事件（因此可在离线状态下验证）、通俗易懂的 --claim、摘要，以及可选的 --sign，用你自己的密钥证明是谁签署的。收件人可通过 korgex receipt verify <file>（退出码 0/1）确认，也可以直接打开 --html 文件，观看它自行重新验证。这是一份可证明的交付物，而不是截图。

korgex receipt --claim "shipped /healthz + passing test" --sign --html receipt.html
#   ✓ receipt minted — 5 events, 3 tool calls, 2 files, $0.0078
#   signed by b251a84c… (your korgex identity) · tip 46263017…
#   receipt.html  ← open in any browser; it re-verifies itself

korgex receipt verify receipt.korgreceipt.json   # ✓ VALID / ✗ INVALID (CI-gateable)

在 CI 中设为门禁。 将 verify-ledger GitHub Action 添加到任意仓库，如果 Agent 的账本或凭证无法通过验证，就让构建失败——对生成它的工具实行零信任：

- uses: New1Direction/korgex/.github/actions/verify-ledger@main
  with:
    path: ".korg/journal.json"            # or "**/*.korgreceipt.json"
    pubkey: ${{ vars.KORG_SIGNER_PUBKEY }}  # optional: pin the signer

查看 Self-Coding Bench，了解跨模型的实时可靠性数据。

---

工具

Agent 可使用 23 个面向模型的高级工具（Claude-Code 风格），每个工具都附有详细说明，涵盖用法、边缘情况和反模式。底层会将请求路由到约 60 个内部处理程序（src/tools_impl.py）。

工具	用途
Read · Write · Edit	读取文件；创建／覆盖文件；精确替换字符串（内部会转换为 SEARCH/REPLACE）。
Bash · BashOutput	在超时限制内运行 shell 命令；轮询长时间运行的后台任务。
Grep · Glob	正则表达式内容搜索（如有则使用 ripgrep）；按模式列出文件。
Agent · Orchestrate	将子任务委派给子 Agent；运行由子 Agent 组成的并行 DAG（参见功能）。
TaskCreate · TaskUpdate	以任务列表的形式跟踪和更新多步骤工作。
AskUserQuestion	提出澄清问题，可附带多选项。
Skill · ToolSearch	调用已安装的技能；按关键字在运行时发现工具。
WebFetch · WebSearch	将 URL 抓取为纯文本；搜索网页。
Recall	从跨会话记忆中提取相关事实（已检查漂移）。
Retrieve	提取封存到 content-ref 的大型工具结果的确切字节内容。
BusSend · BusInbox	通过可验证的 Agent 消息总线发送／接收消息（防篡改协调）。
python (可选启用)	CodeAct——将 Python 作为行动来运行，并可将工具用作函数。
NetCapture (可选启用)	对你编写的应用进行可审计的 HTTP(S) 捕获——无需 cURL 即可调试 API 调用。
RemoteSignTip (可选启用)	通过你控制的远程签名器为账本末端签名（密钥保存在主机之外）。

---

功能

除了核心的文件／Shell／搜索循环外，korgex 还提供了多个更深入的系统。风险较高的功能默认关闭，需主动启用（只需设置一个环境变量），并且每项操作都会记录到可验证账本中。

• CodeAct — 以代码作为操作空间（KORGEX_CODEACT_ENABLE=1）。这是一个持久化、按燃料计量的 Python 内核，模型可以编写代码，将工具作为函数调用——比每轮调用一个工具更密集。嵌套执行轨迹会记录到账本中。启用后，若存在相应后端，内核默认会进行 OS 沙箱隔离：Linux 上使用 bubblewrap，macOS 上使用 Seatbelt，将其限制为无网络访问且只能写入工作区（KORGEX_CODEACT_ISOLATION=auto/required/off）。
• 多 Agent 编排（KORGEX_PARALLEL_AGENTS，以及 Orchestrate 工具）。并发运行由子 Agent 组成的 DAG——原生支持账本且可验证，严格限制为一层嵌套，每次子运行都会链接到其父级之下。
• 可审计的网络捕获（KORGEX_NETCAPTURE_ENABLE=1）。在本地 CA 签名的捕获代理下运行你编写的应用／脚本，并获取每次 HTTP(S) 交互的结构化、脱敏轨迹。捕获仅限于指定进程，且会在记录前屏蔽机密信息。
• 可验证浏览器（KORGEX_BROWSER_STEALTH、KORGEX_BROWSER_EVAL）。由 CDP 驱动的快照→操作浏览器自动化，记录到账本中；隐身模式需主动启用。
• 远程签名（KORGEX_REMOTE_SIGNER_*）。通过由你拥有并控制的 HTTP 签名器，为账本末端签名，因此签名密钥可以存放在 Agent 主机之外（例如另一台机器或 HSM）。失败时默认拒绝：使用 bearer token、主机允许列表、可选的公钥固定，以及本地签名验证。
• 可验证 Agent 总线（korgex bus、KORG_BUS_*）。Agent 通过由 Ed25519 签名且具备防篡改功能的 korg-ledger 日志进行协调——“谁说了什么”由签名证明，而非仅凭声称。
• 回忆 + 记忆——跨会话记忆，会根据来源基线检查漂移（可验证认知）。
• 本地模型（korgex local）。硬件感知顾问（CPU/RAM/GPU/VRAM → 通过 llmfit 提供按适配度评分并排序的推荐，可选），可将本地 Ollama 模型配置为默认模型。在 Apple Silicon 上，korgex local --omlx 会连接正在运行的 omlx MLX 服务（兼容 OpenAI，支持连续批处理和分层 KV 缓存）：直接运行命令会列出它正在提供服务的模型，--omlx --use <model-id> 会将指定模型配置为默认模型（非默认端口需添加 --omlx-url）。korgex 不会重新实现推理功能——它只会指向本地端点。

---

安全与沙箱

• 破坏性命令防护（默认开启；KORGEX_COMMAND_GUARD）。在 Bash（以及 CodeAct 桥接）上实施白名单优先、识别引号和注释的基础防护，拒绝明显具有破坏性的命令；拦截操作会在账本中记录为防篡改的 command_guard.block 事件。
• 出站／数据外泄防护（标记模式下默认开启；KORGEX_EGRESS=off|flag|redact|block）。通过出站工具（WebFetch/WebSearch/BusSend/browser_navigate/MCP/网络 Bash）检查离开隔离环境的数据形态：检测机密信息的特征形态（复用账本脱敏器的模式）和大型编码数据块。flag 会发出警告并记录 egress.flag 判定，但绝不会修改或拦截内容（仅附加记录）；redact 会在出站载荷离开前遮蔽机密信息；block 会拒绝操作。每次检测都会在账本中记录防篡改判定，且仅包含发现内容的形态——原始机密信息会从记录中脱敏，因此可共享的账本绝不会成为数据外泄渠道。可选择启用目标控制：KORGEX_EGRESS_ALLOW/KORGEX_EGRESS_DENY（以逗号分隔的主机名）。
• Bash 沙箱（KORGEX_SANDBOX=modal|docker|direct|auto）。控制 Shell 执行的隔离方式。
• CodeAct 操作系统隔离——代码内核默认使用沙箱（Linux/bubblewrap · macOS/Seatbelt）；设置 KORGEX_CODEACT_ISOLATION=required 可在隔离失败时拒绝运行，设置 =off 可禁用。
• **编辑确认。**在 TUI 中对关键文件执行 Edit/Write 时，会显示差异并提示输入 [y/N]；编辑策略可通过 KORGEX_EDIT_POLICY 配置。
• **所有强大功能默认需选择启用。**CodeAct、NetCapture、远程签名和浏览器隐身功能默认关闭，需手动开启。

---

CLI 参考

$ korgex --help
usage: korgex [-h] SUBCOMMAND ...

korgex — autonomous coding agent. Pass a naked prompt to run the agent, or use a subcommand.

任何非子命令参数都会被视为提示词：korgex "create hello.txt with 'hi'"。

标志

标志	用途
--model MODEL	覆盖模型（例如 claude-sonnet-4-6、gpt-4o、openai/gpt-4o-mini）。优先级始终高于 --mode。
--mode {plan,execute,explore,review,debug,research}	基于模式选择模型（参见多模型路由）。
--mcp	启动时从 mcp.json 加载 MCP 服务。
--quiet / -q	禁用流式 TUI；仅输出最终结果。适用于管道、脚本和 CI。
--version / -V	打印 korgex 版本并退出。
--resume	恢复上次会话——从可验证账本中重放其对话记录。若提供提示词，则恢复会话并运行该提示词；若直接运行 korgex --resume，则在该上下文中重新打开 REPL。

子命令

子命令	行为
korgex setup	连接模型提供商（可连接任意提供商）——将密钥和默认模型保存到 ~/.korgex/config.json。
korgex init	为仓库搭建入门版 AGENTS.md（检测技术栈以及测试／构建命令；绝不覆盖现有文件）。
korgex skills	列出技能；install <ref> / search <query> / adopt <dir> 可从开放的 Agent-Skills catalog 获取技能（本地目录、git URL 或 owner/repo[@skill]），并标记为 trust: installed；check/update [name|all] 可刷新从 git 获取的技能；export <name|all> [claude|cursor|codex|<dir>] 可将 korgex 技能（包括自行学习的技能）导出到其他 Agent。
korgex sessions	列出此仓库账本中的近期会话（使用 korgex --resume 恢复会话）。
korgex commands	列出自定义斜杠命令（内置、项目级、用户级）；在 REPL 中使用 /<name> 调用。
korgex local	推荐适合此计算机的本地模型（并可选择配置）。
可验证的认知
korgex verify [journal]	验证账本的哈希链和因果 DAG 完整无损（退出码为 0/1，适用于 CI）。
korgex trace	显示因果认知轨迹——Agent 做了什么，以及是什么导致了这些操作。
korgex why <path>	追溯文件被修改的原因，沿因果链回溯至对应提示词。
korgex cost	根据账本记录的令牌数估算本次会话的花费。
korgex drift	扫描持久记忆，检查其是否偏离源基线（退出码为 0/1）。
korgex audit [--html f]	将已运行的会话审计到可验证账本中（自动发现 Claude Code 日志）。
korgex import <file>	将其他供应商的会话转录重放到 korg-ledger@v1 日志中。
korgex trajectory	将日志导出为带有可验证来源标记的训练轨迹。
korgex bus	基于防篡改的 korg-ledger 日志提供可验证的 Agent 消息总线。
MCP 与集成
korgex mcp	管理 MCP 服务——在 mcp.json 中添加／列出／移除 stdio 或远程（url+auth）服务。
korgex mcp-server	运行 korg-ledger MCP 服务（基于 stdio 的 JSON-RPC）——供任何 MCP 主机执行验证／审计／导入。
korgex diag <path>	报告文件的语言服务诊断信息（错误／类型）——尽力而为。
仪表板／编辑器
korgex acp	通过 stdio 将 korgex 作为 Agent Client Protocol Agent 运行，以便 ACP 编辑器（如 Zed）驱动它——实时流式传输工具调用活动和回复文本。
korgex serve · dashboard	启动 FastAPI 仪表板（默认地址为 127.0.0.1:8090），并可选择是否打开 VS Code 伴随组件。
korgex status · stop	报告／终止后台后端。
korgex install-extension	将已编译的 .vsix 安装到本地 VS Code。

从编辑器驱动 korgex（ACP）

korgex 以 Agent 的身份支持开放的 Agent Client Protocol，因此支持 ACP 的编辑器可以直接驱动它——在编辑器的 Agent 面板中使用一个可验证、跨厂商的 Agent。在 Zed 中，在 settings.json 里将 korgex 添加为外部 Agent：

{
  "agent_servers": {
    "korgex": { "type": "custom", "command": "korgex", "args": ["acp"], "env": {} }
  }
}

Zed 要求每个外部 Agent 都设置 "type": "custom"——否则 Zed 会拒绝整个 agent_servers 块（"missing field type"），korgex 也不会显示。如果 Zed 无法在其（精简的 GUI）PATH 中找到 korgex，请在 command 中使用完整的二进制文件路径（例如 ~/.local/bin/korgex）。编辑设置后，Zed 会热重载；如果 korgex 仍未显示，请完全退出并重新打开 Zed。

然后从 Agent Panel 的 New Thread 菜单中选择 korgex。运行期间，编辑器会实时显示 tool_call 活动（读取／编辑／运行／搜索卡片，编辑时附带内联差异预览），并流式显示回复文本——这些内容由同一防篡改账本支持，因此整个会话都可通过 korgex verify 验证。（编辑器每条消息处理一个提示词轮次；支持嵌入的 @file 上下文和粘贴的资源。）

默认情况下，korgex 会自由执行。若要让编辑器审批编辑（显示包含 Allow / Allow-don't-ask-again / Reject 选项的 session/request_permission 提示），请使用 KORGEX_EDIT_POLICY=ask 运行：

{ "agent_servers": { "korgex": { "type": "custom", "command": "korgex", "args": ["acp"], "env": { "KORGEX_EDIT_POLICY": "ask" } } } }

---

环境变量

核心

变量	用途	默认值
ANTHROPIC_API_KEY	当模型 ID 包含 "claude" 或以 "anthropic/" 开头时使用。	—
OPENAI_API_KEY	用于所有非 Anthropic 模型。	—
KORGEX_API_KEY / KORGEX_API_URL	用于兼容 OpenAI 的端点（OpenRouter、Ollama、vLLM 等）的通用密钥和基础 URL。	— / https://api.openai.com/v1
KORGEX_MODEL	未指定 --model 或 --mode 时使用的默认模型。	claude-sonnet-4-6
KORGEX_PROVIDER	强制指定传输方式（openai|anthropic），覆盖基于模型 ID 的自动检测。	自动检测
KORGEX_MAX_ITERATIONS	放弃前 Agent 循环的最大迭代次数。	30
KORGEX_MCP	设为 1 可从 mcp.json 自动加载 MCP 服务。	未设置
KORGEX_SANDBOX	modal|docker|direct|auto — bash 隔离方式。	auto
KORGEX_DASHBOARD_HOST	仪表板绑定的主机。默认为 localhost；仅在经过身份验证的代理后方设为 0.0.0.0。	127.0.0.1

功能（选择启用）

变量	用途
KORGEX_LEAN_CONTEXT · KORGEX_LEAN_CONTEXT_TOKENS	注入与提示词相关的精简、已验证账本上下文，而非保留完整历史记录（默认预算为 800），让较小的／可自托管模型也能运行循环。
KORGEX_CODEACT_ENABLE · KORGEX_CODEACT_ISOLATION	启用 CodeAct 代码内核；操作系统隔离方式为 auto（默认 — 在可用时使用沙箱：Linux/bubblewrap、macOS/Seatbelt）· required（失败时关闭）· off。
KORGEX_NETCAPTURE_ENABLE	启用可审计的 HTTP(S) 捕获工具。
KORGEX_PARALLEL_AGENTS	多 Agent 编排的并发数。
KORGEX_REMOTE_SIGNER_TOKEN · _ALLOWED_HOSTS · _PUBKEY · _REQUIRE_HTTPS	远程签名器身份验证、主机允许列表、固定公钥、强制使用 https。
KORGEX_BROWSER_STEALTH · KORGEX_BROWSER_EVAL	浏览器隐身模式；允许在页面内执行 evaluate。
KORGEX_COMMAND_GUARD	切换破坏性命令保护（默认开启）。
KORGEX_EDIT_POLICY	编辑确认策略。
KORGEX_WEBHOOK_SECRET · KORGEX_WEBHOOK_ALLOW_UNSIGNED	GitHub webhook HMAC 密钥；除非明确设为 KORGEX_WEBHOOK_ALLOW_UNSIGNED=1 以供本地／开发环境使用，否则会拒绝未签名的 webhook。

账本与总线

变量	用途	默认值
KORG_JOURNAL_PATH	持久化 JSONL 账本；内容寻址的 blob 写入其旁边。	.korg/journal.jsonl
KORG_LEDGER_HMAC_KEY	设置后，链将使用 HMAC 密钥保护——具备防篡改能力，而不仅仅是篡改可检测。	未设置
KORG_BUS_AGENT · KORG_BUS_JOURNAL · KORG_BUS_KEY	可验证总线的 Agent ID、总线日志和 Ed25519 密钥。	—

提供方检测规则：如果模型 ID 包含 "claude" 或以 "anthropic/" 开头，则使用 Anthropic SDK；否则使用兼容 OpenAI 的 SDK（OpenAI、OpenRouter、Ollama、DeepSeek、vLLM 等）。设置 KORGEX_PROVIDER=openai 可通过兼容 OpenAI 的端点调用 claude/anthropic/* ID（例如通过 OpenRouter 使用 Claude）。

---

多模型路由

--mode 会根据工作类型选择合适的模型：

模式	模型	生成参数
plan	Opus 4.7	max_tokens=64000、thinking={budget_tokens: 20000}、temperature=0.7
execute	Sonnet 4.6	max_tokens=64000、temperature=0.3
explore	Opus 4.7	max_tokens=32000、temperature=0.5
review	Sonnet 4.6	max_tokens=16000、temperature=0.3
debug	Haiku 4.5	max_tokens=16000、temperature=0.2
research	Opus 4.7	max_tokens=32000、temperature=0.7

明确指定的 --model 始终优先于 --mode。两者均未设置时，默认使用 Sonnet 4.6。

korgex --mode plan "architect a multi-tenant billing system"
korgex --mode debug "trace why this 500 is happening"
korgex --mode execute "implement the plan we just made"

---

MCP 集成

简而言之：MCP 是面向 AI 的开放式“应用商店”标准，可让 korgex 接入外部服务（GitHub、你的文件、数据库，……），无需编写自定义胶水代码。

korgex 内置原生 MCP（Model Context Protocol）客户端。mcp.json 中的任何 MCP 服务都会成为 Agent 工具集的一部分。你可以通过命令行使用 korgex mcp 管理这些服务（添加、列出、移除 stdio 或远程 URL+身份验证服务），也可以使用 korgex mcp catalog / korgex mcp add <alias> 一键应用预设。值得一提的是：korgex mcp add mise 会接入 mise 自带的 Agent 服务，让 Agent 获取项目的工具版本、环境变量和可运行任务（以及 run_task），所有内容都可通过账本验证。

korgex 本身也是 MCP 服务

korgex mcp-server 通过 JSON-RPC/stdio 暴露可验证认知的基础设施，让任何 MCP 宿主（Claude Desktop、Cursor，……）都可以调用：

• korg_verify — 证明 korg-ledger 日志防篡改且完整；
• korg_audit — 审计宿主 Agent 自身的 Claude Code 日志（导入并验证），零配置；
• korg_import — 将供应商会话记录导入可验证的链式账本。

{ "mcpServers": { "korg-ledger": { "command": "korgex", "args": ["mcp-server"] } } }

已列入 MCP Registry — mcp-name: io.github.New1Direction/korg-ledger。

配置与使用

{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],     "env": { "GITHUB_TOKEN": "ghp_..." } },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

korgex --mcp "create a GitHub issue summarizing today's bug"

Agent 会在启动时发现每个服务的工具，将它们注册到面向用户的工具列表中，并将调用路由回对应的服务。服务故障会被记录并跳过，不会导致 Agent 崩溃。

---

插件

无需派生项目即可扩展 korgex。将 .py 文件放入 ~/.korgex/plugins/（全局）或 <repo>/.korgex/plugins/（项目本地），并在其中定义 register(registry) 函数，插件便会在启动时接入 Agent 循环。

# ~/.korgex/plugins/notify.py — ping me when a file is edited
def register(reg):
    @reg.on("post_tool")
    def on_edit(payload):
        call = payload["call"]
        if call["name"] in ("Edit", "Write"):
            print(f"  ✎ touched {call['args'].get('file_path')}")

生命周期钩子： on_user_prompt（每轮开始时）、pre_tool（工具运行前）、post_tool（工具返回后）、on_stop（运行结束时）。插件在进程内运行，拥有完整访问权限——只安装你信任的插件——并且具备故障安全机制：无法导入、缺少 register 或引发异常的插件都会被记录并跳过，不会导致启动崩溃。

---

流式 TUI

当 stdout 是 TTY 时，Agent 会通过 Rich 实时流式输出：思考内容以暗淡的斜体显示（Anthropic），文本逐字符显示，工具调用显示临时旋转指示器（⠋ Read(file_path=src/foo.py)），关键编辑会请求 [y/N] 差异确认，并支持优雅地通过 Ctrl+C 中断（连按两次强制终止）。当 stdout 被管道重定向、处于 CI 环境或使用 --quiet 时，流式输出会自动停用。OpenAI/OpenRouter 的流式输出也通过同一渲染器；工具调用增量会跨数据块累积。

---

架构

系统概览

flowchart TD
    U["You — CLI / REPL / ACP editor<br/>(src/cli.py · repl.py · acp.py)"] --> AG

    subgraph core["KorgexAgent loop — src/agent.py (plan, act, verify)"]
        AG["Agent loop: run_task()<br/>system prompt + memory + task list"]
        GATE["Per-call gates<br/>plan-mode · edit-policy · command / egress guard · hooks"]
        AG --> GATE
    end

    AG -->|"normalize tool-use shape"| PROV{"Provider<br/>(model id / KORGEX_PROVIDER)"}
    PROV -->|"claude family"| ANT["Anthropic SDK"]
    PROV -->|"everything else"| OAI["OpenAI-compatible SDK<br/>OpenAI · OpenRouter · Ollama · Grok · Nous · Venice · Gemini"]
    ANT --> GATE
    OAI --> GATE

    GATE --> TR["Tool router<br/>src/tool_abstraction.py"]
    TR --> BT["Built-in handlers<br/>file · Bash · search · git · GitHub · browser"]
    TR --> CA["CodeAct kernel<br/>Python-as-action, fuel/mem-metered (opt-in)"]
    TR --> MCP["MCP servers<br/>src/mcp_client.py"]

    BT --> LED
    CA --> LED
    MCP --> LED
    GATE -. "every decision + result" .-> LED

    LED[("korg-ledger · src/korg_ledger.py<br/>append-only · hash-chained · causal DAG")]
    LED --> HEAL["Test gate + self-heal<br/>src/test_gate.py · self_healing.py"]
    HEAL -->|"red, retry"| AG
    LED --> VERIFY["verify · trace · why · audit · receipt<br/>Ed25519 signing"]
    VERIFY --> U

工具路由 — 稳定的模型侧名称 → 内部处理程序

User tool call (LLM-visible):     Internal handler (src/tools_impl.py):
─────────────────────────────     ─────────────────────────────────────
Read(file_path=...)         →     tool_read_file(filepath=..., context=...)
Write(file_path=..., ...)   →     tool_write_file(filepath=..., ...)
Edit(file_path, old, new)   →     tool_replace_with_git_merge_diff(merge_diff="<<<<<<< SEARCH ...")
Bash(command=...)           →     tool_run_in_bash_session(command=...)

路由器（src/tool_abstraction.py）会在 _TOOL_ROUTING 中查找名称，应用 param_map 或自定义 adapter，过滤处理程序不接受的关键字参数，自动注入 context={'repo_root': cwd}，并将异常捕获为 {"error": ...}，确保单个工具故障不会终止循环。来自 MCP 的工具会绕过 _TOOL_ROUTING，通过 MCPServerManager.call_tool() 分发。

Agent 循环

flowchart TD
    S(["prompt"]) --> SEND["LLM.send(messages, tools)"]
    SEND --> Q{tool calls?}
    Q -->|no| F(["final result"])
    Q -->|yes| RT["route_tool_call(name, args)"]
    RT --> REC["record event → korg-ledger"]
    REC --> APP["append tool_result to messages"]
    APP --> SEND

优先规划的系统提示词会指示 Agent 先规划、进行验证、先诊断再修改，并且绝不修改构建产物（src/agent.py 中的 SYSTEM_PROMPT）。账本使用原生 Python 实现（src/korg_ledger.py、src/ledger_spec.py），无需外部运行时。

---

项目结构

korgex/
├── src/
│   ├── agent.py              # KorgexAgent — main loop, provider branching, streaming
│   ├── cli.py · repl.py      # argparse dispatch · interactive REPL
│   ├── tool_abstraction.py   # USER_TOOLS registry + router + MCP integration
│   ├── tools_impl.py         # ~60 internal handlers (file ops, git, GitHub, web, …)
│   ├── model_router.py       # mode → model mapping (plan/execute/debug/…)
│   ├── korg_ledger.py · ledger_spec.py · signing.py   # verifiable ledger + Ed25519
│   ├── codeact/              # code-as-action kernel (fuel-metered, isolated, traced)
│   ├── orchestrate.py        # multi-agent DAG orchestration
│   ├── recall.py · memory.py · memory_drift.py        # cross-session memory + drift
│   ├── command_guard.py · sandbox.py                  # destructive-cmd floor · bash sandbox
│   ├── netcapture.py · remote_signer.py · browser.py  # opt-in capability modules
│   ├── structured_output.py · skills.py · local_model.py
│   ├── mcp_client.py · dashboard.py · interactive.py
│   └── ...
├── docs/                     # CLI reference, comparison, getting-started, tools-reference, …
├── spec/korg-ledger-v1/      # the ledger spec (SPEC.md, EVENTS.md)
├── tests/                    # ~1,657 passing tests
├── .github/workflows/        # Linux CI (3.10–3.13) + PyPI publisher (OIDC)
├── pyproject.toml
└── README.md

---

开发与测试

git clone https://github.com/New1Direction/korgex.git && cd korgex
uv venv .venv && source .venv/bin/activate      # or python -m venv .venv
uv pip install -e ".[dev]"                       # pytest, build, ruff, …

ruff check src/                                   # lint
pytest -q                                         # the full suite

pyproject.toml 是软件包依赖的权威来源。requirements.txt 作为兼容性镜像保留，供源码检出和旧版自动化使用；开发时优先使用带附加依赖的可编辑安装。

测试套件包含 1,600+ 项测试，不调用在线大模型（所有内容均通过单元测试验证）；每次推送和 PR 都会在 Linux CI 上针对 Python 3.10、3.11、3.12、3.13 运行。主要覆盖领域：Agent 循环（路由、提供方架构、模式/模型解析、循环保护、停滞分类器、压缩）、工具（模糊 Edit、编辑新鲜度、后台 Bash、Web）、可验证账本（哈希链 + 因果 DAG、脱敏、Ed25519 签名总线）、CodeAct（内核隔离、燃料、工具桥接）、MCP（命名空间多服务路由器、OAuth 刷新、完整往返）、提示词缓存、技能（信任层级、自我学习、策展器）以及 REPL。

---

构建与发布

发布流程已自动化。更新 pyproject.toml 中的 version，更新 CHANGELOG.md，合并到 main，然后创建 GitHub Release——PyPI 发布工作流会在 release: published 时触发，并通过 OIDC Trusted Publishing 上传（同时附带数字证明）。无需手动处理令牌。

gh release create vX.Y.Z --title "vX.Y.Z" --notes "…"   # → triggers .github/workflows/publish.yml → PyPI

如需在本地构建以供检查：运行 python -m build，然后运行 python -m twine check dist/*。

---

故障排除

korgex: No API key found——设置 ANTHROPIC_API_KEY、OPENAI_API_KEY 或 KORGEX_API_KEY 其中之一（对于非 OpenAI 端点，还需设置 KORGEX_API_URL），或运行 korgex setup。

ModuleNotFoundError: No module named 'anthropic'（或 openai、rich）——依赖项尚未安装：运行 pip install -e .（会安装 pyproject.toml 中的所有依赖项）。

Agent 在工具调用上无限循环——降低上限：运行 export KORGEX_MAX_ITERATIONS=10，并使用 --quiet 仅查看最终状态。

--mcp 启动缓慢——客户端会依次连接到每个服务并等待握手；mcp.json 中无法访问的条目都会在跳过前超时。请移除失效的服务，或使用 korgex mcp 管理它们。

verify 报告中断——这是预期行为：它发现并定位了被篡改或拼接的事件。报告中的 seq_id 就是链发生分歧的位置。

---

已知限制

这些限制目前仍然存在；欢迎提交 PR。

• OpenAI 流式输出渲染的事件少于 Anthropic。 Anthropic 会发出思考块和消息增量用量信息；OpenAI 只会发出文本和工具调用块。两者都能正确渲染，但 Anthropic 的 TUI 信息更丰富。
• 尚未实现仪表盘身份验证。 默认绑定到 127.0.0.1；如果前面没有终止身份验证的反向代理，请勿设置 KORGEX_DASHBOARD_HOST=0.0.0.0。
• VS Code sidecar 是仪表盘的旧版配套组件；korgex 的主要界面是终端 REPL。

---

许可证

MIT——请参阅 LICENSE。

---

相关项目

• Model Context Protocol——korgex 实现的开放 MCP 标准（同时作为客户端和服务端）。
• korg · korgchat——围绕 korg-ledger 构建的更广泛生态系统。
• llmfit——korgex local 所基于的硬件感知型本地模型顾问（可选）。