From a23418eb528c8803bb8ce77f57d7bd6934fae8e7 Mon Sep 17 00:00:00 2001 From: New1Direction <285551516+New1Direction@users.noreply.github.com> Date: Wed, 10 Jun 2026 11:36:01 -0700 Subject: [PATCH] docs(i18n): add Simplified + Traditional Chinese READMEs --- README.md | 4 ++ README.zh-CN.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ README.zh-TW.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 294 insertions(+) create mode 100644 README.zh-CN.md create mode 100644 README.zh-TW.md diff --git a/README.md b/README.md index a750df6..319c3d8 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,10 @@ License: MIT

+

+ English · 简体中文 · 繁體中文 +

+ # korgex **An AI coding teammate for your terminal — that keeps the receipts.** diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..73cd3a5 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,145 @@ +

+ korgex —— 可验证的编程智能体 +

+ +

+ PyPI 版本 + Python 版本 + 许可证: MIT +

+ +

+ English · 简体中文 · 繁體中文 +

+ +# korgex + +**一个跑在终端里、并且全程“留底”的 AI 编程搭档。** + +用大白话告诉 korgex 你想做什么——*“修好这个失败的测试”“加一个健康检查接口”*——它就会读你的代码、动手修改、跑测试,并把它做的每一步清清楚楚展示给你。它免费、开源,兼容你喜欢的任意 AI(Claude、ChatGPT、Gemini、Grok,或跑在你自己电脑上的私有模型),所以你永远不会被某一家公司绑死。 + +**它为什么不一样:** korgex 做的每一件事都会写进一份防篡改的记录,供你日后查验。哪怕有人只改了其中一个字符,korgex 都能证明。这是一个你可以*审计*、而不只是“但愿能信”的编程助手。 + +> 📖 **完整中文文档**:[简体中文文档](https://korgex-docs.pages.dev/zh-CN/docs) · 在中国大陆?见[在中国安装](https://korgex-docs.pages.dev/zh-CN/docs/install-china) + +```bash +$ korgex "加一个 /healthz 接口,返回 200 并带上运行时长" +➤ Read(file_path=/app/routes.py) +➤ Edit(file_path=/app/routes.py, old_string=..., new_string=...) +➤ Bash(command=pytest tests/test_routes.py -q) +✓ 已添加 GET /healthz,返回 {"status": "ok", "uptime_seconds": ...} + +$ korgex verify + ✓ 账本完整 —— 7 条事件,哈希链 + 因果 DAG 校验通过 +``` + +## 安装 + +```bash +pip install -U korgex # 或安装为独立的全局 CLI: +uv tool install korgex@latest +``` + +需要 Python ≥ 3.10。**在中国大陆**用国内镜像更快: + +```bash +pip install -U korgex -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +更多镜像(cargo / npm 等)见[在中国安装](https://korgex-docs.pages.dev/zh-CN/docs/install-china)。 + +## 快速开始 + +```bash +# 1. 接入一个厂商(交互式,保存到 ~/.korgex/config.json) +korgex setup +# ……或直接导出一个密钥,下面任意一种都行: +export ANTHROPIC_API_KEY="sk-ant-..." # Claude +export OPENAI_API_KEY="sk-proj-..." # ChatGPT +export KORGEX_API_KEY="..." KORGEX_API_URL="http://your-gpu-box:8000/v1" # 自建模型 + +# 2. 给它一个需求直接跑 +korgex "修好 tests/test_auth.py 里失败的测试" + +# 3. 或指定模型 / 模式 +korgex --model claude-sonnet-4-6 "重构 src/handler.py" +korgex --mode plan "为这个 API 设计一个限流器" + +# 4. 事后证明这次运行没被改过 +korgex verify +``` + +不带提示词直接运行 `korgex` 即可进入交互式 REPL。 + +## REPL —— 住在里面 + +直接运行 `korgex` 进入流式、多轮的会话:它会连接你的 MCP 服务、读取你的项目规则,并为每个会话保留可回退(rewind)的记录。 + +- **斜杠命令**:`/loop`(无人值守地刷完一串任务)、`/diff`、`/rewind`、`/plan`、`/model`、`/verify`、`/cost`、`/resume`、`/skills` 等。 +- **`@文件`**:把文件内容拉进本轮对话——`重构 @src/auth.py,改用 @src/db.py`。 +- **`!命令`**:就地执行 shell——`!git status`、`!pytest -q`。 +- **项目规则**:`korgex init` 会生成 `AGENTS.md`,korgex 每次会话都会自动读取它(以及上层目录的 `AGENTS.md` 和 `.korgex/rules/*.md`),按你的规范来做事。 + +## 可验证的认知(核心) + +**用大白话说:** korgex 会把它做的每件事记成一本流水账——读过的每个文件、运行过的每条命令。每一条都和前一条紧紧相扣,就像链条上的扣环;只要有人事后改动、新增或删除哪怕一条,链条就会明显断裂。于是你得到的是关于 AI 到底做了什么的、诚实且可核验的证明——用于审计、合规、排查问题,或只是图个安心。据我们所知,目前还没有别的编程智能体做到这一点。 + +底层实现:每次运行都写入一本**防篡改的因果账本**(而不是一份不透明的日志)。每条事件既与前一条**哈希相扣**(`prev_hash`/`entry_hash`),又与触发它的原因**因果相连**(`triggered_by`)——所以整段会话都能被密码学地证明完整,任何改动、删除、重排或拼接都会被发现并精确定位到出问题的那一条。 + +```bash +korgex verify # 证明记录在案的运行没被改过(退出码 0/1,可用于 CI) +korgex trace # 因果轨迹——它做了什么 + 每一步是被什么触发的 +korgex why src/auth.py # 从一处文件改动,沿因果链回溯到对应的提示词 +korgex cost # 这次会话的预估花费,按记录在案的 token 数算 +export KORG_LEDGER_HMAC_KEY=… # 让链条从“防篡改”升级为“防伪造” +``` + +**交一份凭证给别人。** `korgex receipt` 能生成一个可随身携带的单文件,证明某次运行做了什么——它能**离线**校验,或者直接用 `--html` 打开,在浏览器里看着它自我重新校验。可证明的交付物,而不是一张截图。 + +```bash +korgex receipt --claim "上线 /healthz + 测试通过" --sign --html receipt.html +korgex receipt verify receipt.korgreceipt.json # ✓ 有效 / ✗ 无效(可用于 CI 把关) +``` + +**在 CI 里把关。** 把 `verify-ledger` 这个 GitHub Action 放进任意仓库,一旦某个智能体的账本或凭证通不过校验,就让构建失败——对生成它的工具做到“零信任”。 + +## 能力(强力功能默认关闭、需手动开启) + +除了核心的“文件 / shell / 搜索”循环,korgex 还内置了几套更深的系统。其中风险较高的都**默认关闭,一个环境变量即可开启**,而且每一个开启后仍然会记录到可核验的账本。 + +- **CodeAct —— 代码即动作**(`KORGEX_CODEACT_ENABLE=1`):一个持久、带“燃料”计量的 Python 内核,模型直接写代码来调用工具。开启后默认进 **OS 沙箱**(Linux/bubblewrap、macOS/Seatbelt)。 +- **多智能体编排**(`KORGEX_PARALLEL_AGENTS` + `Orchestrate` 工具):并发跑一张子智能体的 DAG,账本原生、可核验。 +- **可审计的网络抓包**(`KORGEX_NETCAPTURE_ENABLE=1`):在本地抓取你自己写的应用的 HTTP(S) 交互,密钥在记录前先被脱敏。 +- **可验证的浏览器**:CDP 驱动的“快照→操作”自动化,全程记录,隐身模式可选。 +- **远程签名**:用一台**你自己掌控**的签名服务给账本盖章,签名私钥可放在 agent 主机之外。 +- **可验证的智能体总线**:多个 agent 通过 Ed25519 签名、防篡改的 korg 账本协作——“谁说了什么”是签名,而不是一句空口。 +- **跨会话记忆 + 漂移检测**:记住的事实会锚定到来源的 sha256 基线,来源变化时给出精确的“过期”信号。 +- **本地模型**(`korgex local`):按你机器的 CPU/内存/显卡推荐合适的本地模型,可一键把本地 **Ollama** 模型设为默认。 + +## 安全与沙箱 + +- **破坏性命令护栏**(默认开启):一道“白名单优先”的底线,拒绝明显具有破坏性的 shell 命令,拦截会记成一条防篡改的账本事件。 +- **外发 / 外泄护栏**(默认以“标记”模式开启):检查经由外发工具离开本机的数据,识别密钥形态与大块编码数据;`flag` 仅警告并记录,`redact` 在外发前脱敏,`block` 直接拒绝。 +- **沙箱执行**(`KORGEX_SANDBOX`)、**编辑确认**(关键文件改动会先给 diff 等你点头)。 +- **强力功能一律默认关闭**:CodeAct、网络抓包、远程签名、浏览器隐身——都要你亲自打开才生效。 + +## 多模型路由 + +`--mode` 会按工作类型挑选合适的模型(`plan` / `execute` / `explore` / `review` / `debug` / `research`);显式 `--model` 始终优先。默认是 Sonnet 4.6。 + +## MCP 集成 + +korgex 内置原生的 MCP(模型上下文协议)客户端:`mcp.json` 里的任意 MCP 服务都会成为 agent 的工具。用 `korgex mcp` 管理(stdio 或远程 url+鉴权)。korgex 本身**也是一个 MCP 服务**(`korgex mcp-server`),把“可验证认知”的能力(`korg_verify` / `korg_audit` / `korg_import`)暴露给任意 MCP 宿主。 + +## 完整参考 + +完整的 CLI 参考、环境变量、架构图与开发指南,见[**完整文档**](https://korgex-docs.pages.dev/zh-CN/docs) 或[英文 README](README.md)。 + +## 相关项目 + +- **[korg](https://github.com/New1Direction/korg)** · **[korgchat](https://github.com/New1Direction/korgchat)** —— korg 账本周边更广的生态。 +- **[Model Context Protocol](https://modelcontextprotocol.io/)** —— korgex 同时作为客户端与服务端实现的开放 MCP 标准。 + +## 许可证 + +MIT —— 见 [LICENSE](LICENSE)。 diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..c73d605 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,145 @@ +

+ korgex —— 可驗證的編程代理 +

+ +

+ PyPI 版本 + Python 版本 + 授權: MIT +

+ +

+ English · 简体中文 · 繁體中文 +

+ +# korgex + +**一個跑在終端裡、而且全程「留底」的 AI 編程夥伴。** + +用白話告訴 korgex 你想做什麼——*「修好這個失敗的測試」「加一個健康檢查端點」*——它就會讀你的程式碼、動手修改、跑測試,並把它做的每一步清清楚楚攤給你看。它免費、開源,相容你喜歡的任意 AI(Claude、ChatGPT、Gemini、Grok,或跑在你自己電腦上的私有模型),所以你永遠不會被某一家公司綁死。 + +**它為什麼不一樣:** korgex 做的每一件事都會寫進一份防竄改的紀錄,供你日後查驗。哪怕有人只改了其中一個字元,korgex 都能證明。這是一個你可以*稽核*、而不只是「但願可信」的編程助手。 + +> 📖 **完整中文文件**:[繁體中文文件](https://korgex-docs.pages.dev/zh-TW/docs) · 在中國大陸?見[在中國安裝](https://korgex-docs.pages.dev/zh-TW/docs/install-china) + +```bash +$ korgex "加一個 /healthz 端點,回傳 200 並帶上執行時間" +➤ Read(file_path=/app/routes.py) +➤ Edit(file_path=/app/routes.py, old_string=..., new_string=...) +➤ Bash(command=pytest tests/test_routes.py -q) +✓ 已新增 GET /healthz,回傳 {"status": "ok", "uptime_seconds": ...} + +$ korgex verify + ✓ 帳本完整 —— 7 條事件,雜湊鏈 + 因果 DAG 校驗通過 +``` + +## 安裝 + +```bash +pip install -U korgex # 或安裝為獨立的全域 CLI: +uv tool install korgex@latest +``` + +需要 Python ≥ 3.10。**在中國大陸**用國內鏡像更快: + +```bash +pip install -U korgex -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +更多鏡像(cargo / npm 等)見[在中國安裝](https://korgex-docs.pages.dev/zh-TW/docs/install-china)。 + +## 快速開始 + +```bash +# 1. 接上一個廠商(互動式,儲存到 ~/.korgex/config.json) +korgex setup +# ……或直接匯出一個金鑰,下面任一種都行: +export ANTHROPIC_API_KEY="sk-ant-..." # Claude +export OPENAI_API_KEY="sk-proj-..." # ChatGPT +export KORGEX_API_KEY="..." KORGEX_API_URL="http://your-gpu-box:8000/v1" # 自架模型 + +# 2. 給它一個需求直接跑 +korgex "修好 tests/test_auth.py 裡失敗的測試" + +# 3. 或指定模型 / 模式 +korgex --model claude-sonnet-4-6 "重構 src/handler.py" +korgex --mode plan "為這個 API 設計一個速率限制器" + +# 4. 事後證明這次執行沒被改過 +korgex verify +``` + +不帶提示詞直接執行 `korgex` 即可進入互動式 REPL。 + +## REPL —— 住在裡面 + +直接執行 `korgex` 進入串流、多輪的工作階段:它會連接你的 MCP 伺服器、讀取你的專案規則,並為每個工作階段保留可回退(rewind)的紀錄。 + +- **斜線指令**:`/loop`(無人值守地刷完一串任務)、`/diff`、`/rewind`、`/plan`、`/model`、`/verify`、`/cost`、`/resume`、`/skills` 等。 +- **`@檔案`**:把檔案內容拉進本輪對話——`重構 @src/auth.py,改用 @src/db.py`。 +- **`!指令`**:就地執行 shell——`!git status`、`!pytest -q`。 +- **專案規則**:`korgex init` 會產生 `AGENTS.md`,korgex 每次工作階段都會自動讀取它(以及上層目錄的 `AGENTS.md` 和 `.korgex/rules/*.md`),照你的規範做事。 + +## 可驗證的認知(核心) + +**用白話說:** korgex 會把它做的每件事記成一本流水帳——讀過的每個檔案、執行過的每一條指令。每一條都和前一條緊緊相扣,就像鏈條上的扣環;只要有人事後改動、新增或刪除哪怕一條,鏈條就會明顯斷裂。於是你得到的是關於 AI 到底做了什麼的、誠實且可核驗的證明——用於稽核、合規、排查問題,或只是圖個安心。據我們所知,目前還沒有別的編程代理做到這一點。 + +底層實作:每次執行都寫入一本**防竄改的因果帳本**(而不是一份不透明的紀錄檔)。每條事件既與前一條**雜湊相扣**(`prev_hash`/`entry_hash`),又與觸發它的原因**因果相連**(`triggered_by`)——所以整段工作階段都能被密碼學地證明完整,任何改動、刪除、重排或拼接都會被發現並精確定位到出問題的那一條。 + +```bash +korgex verify # 證明記錄在案的執行沒被改過(離開碼 0/1,可用於 CI) +korgex trace # 因果軌跡——它做了什麼 + 每一步是被什麼觸發的 +korgex why src/auth.py # 從一處檔案改動,沿因果鏈回溯到對應的提示詞 +korgex cost # 這次工作階段的預估花費,依記錄在案的 token 數算 +export KORG_LEDGER_HMAC_KEY=… # 讓鏈條從「防竄改」升級為「防偽造」 +``` + +**交一份憑證給別人。** `korgex receipt` 能產生一個可隨身攜帶的單一檔案,證明某次執行做了什麼——它能**離線**校驗,或者直接用 `--html` 打開,在瀏覽器裡看著它自我重新校驗。可證明的交付物,而不是一張截圖。 + +```bash +korgex receipt --claim "上線 /healthz + 測試通過" --sign --html receipt.html +korgex receipt verify receipt.korgreceipt.json # ✓ 有效 / ✗ 無效(可用於 CI 把關) +``` + +**在 CI 裡把關。** 把 `verify-ledger` 這個 GitHub Action 放進任意儲存庫,一旦某個代理的帳本或憑證通不過校驗,就讓建置失敗——對產生它的工具做到「零信任」。 + +## 能力(強力功能預設關閉、需手動開啟) + +除了核心的「檔案 / shell / 搜尋」循環,korgex 還內建了幾套更深的系統。其中風險較高的都**預設關閉,一個環境變數即可開啟**,而且每一個開啟後仍然會記錄到可核驗的帳本。 + +- **CodeAct —— 程式碼即動作**(`KORGEX_CODEACT_ENABLE=1`):一個持久、帶「燃料」計量的 Python 核心,模型直接寫程式碼來呼叫工具。開啟後預設進 **OS 沙箱**(Linux/bubblewrap、macOS/Seatbelt)。 +- **多代理編排**(`KORGEX_PARALLEL_AGENTS` + `Orchestrate` 工具):並行跑一張子代理的 DAG,帳本原生、可核驗。 +- **可稽核的網路擷取**(`KORGEX_NETCAPTURE_ENABLE=1`):在本機擷取你自己寫的應用的 HTTP(S) 交互,金鑰在記錄前先被遮蔽。 +- **可驗證的瀏覽器**:CDP 驅動的「快照→操作」自動化,全程紀錄,隱身模式可選。 +- **遠端簽章**:用一台**你自己掌控**的簽章服務替帳本蓋章,簽章私鑰可放在 agent 主機之外。 +- **可驗證的代理匯流排**:多個 agent 透過 Ed25519 簽章、防竄改的 korg 帳本協作——「誰說了什麼」是簽章,而不是一句空口。 +- **跨工作階段記憶 + 漂移偵測**:記住的事實會錨定到來源的 sha256 基線,來源變動時給出精確的「過期」訊號。 +- **本機模型**(`korgex local`):依你機器的 CPU/記憶體/顯示卡推薦合適的本機模型,可一鍵把本機 **Ollama** 模型設為預設。 + +## 安全與沙箱 + +- **破壞性指令護欄**(預設開啟):一道「白名單優先」的底線,拒絕明顯具破壞性的 shell 指令,攔截會記成一條防竄改的帳本事件。 +- **外送 / 外洩護欄**(預設以「標記」模式開啟):檢查經由外送工具離開本機的資料,識別金鑰形態與大量編碼資料;`flag` 僅警告並記錄,`redact` 在外送前遮蔽,`block` 直接拒絕。 +- **沙箱執行**(`KORGEX_SANDBOX`)、**編輯確認**(關鍵檔案改動會先給 diff 等你點頭)。 +- **強力功能一律預設關閉**:CodeAct、網路擷取、遠端簽章、瀏覽器隱身——都要你親自打開才生效。 + +## 多模型路由 + +`--mode` 會依工作類型挑選合適的模型(`plan` / `execute` / `explore` / `review` / `debug` / `research`);顯式 `--model` 始終優先。預設是 Sonnet 4.6。 + +## MCP 整合 + +korgex 內建原生的 MCP(模型上下文協定)用戶端:`mcp.json` 裡的任意 MCP 伺服器都會成為 agent 的工具。用 `korgex mcp` 管理(stdio 或遠端 url+驗證)。korgex 本身**也是一個 MCP 伺服器**(`korgex mcp-server`),把「可驗證認知」的能力(`korg_verify` / `korg_audit` / `korg_import`)暴露給任意 MCP 宿主。 + +## 完整參考 + +完整的 CLI 參考、環境變數、架構圖與開發指南,見[**完整文件**](https://korgex-docs.pages.dev/zh-TW/docs) 或[英文 README](README.md)。 + +## 相關專案 + +- **[korg](https://github.com/New1Direction/korg)** · **[korgchat](https://github.com/New1Direction/korgchat)** —— korg 帳本周邊更廣的生態。 +- **[Model Context Protocol](https://modelcontextprotocol.io/)** —— korgex 同時作為用戶端與伺服端實作的開放 MCP 標準。 + +## 授權 + +MIT —— 見 [LICENSE](LICENSE)。