original-flipster69/koko

# koko 🦍💻    一个以安全和隐私为首要考量的沙盒化终端编码助手。`koko` 可连接至您所有喜爱的 LLM 提供商，并为您的文件和 shell 提供最小权限访问。您不希望离开设备的任何内容都不会离开。无忧的代理式编码。 ## 功能 ### 多提供商 LLM 支持 koko 支持三种 LLM 后端： - **Claude** — 通过 Anthropic API 使用的 Claude 模型 (`CLAUDE_API_KEY`) - **Mistral** — 通过 Mistral API 或任何兼容端点使用的 Mistral 模型 (`MISTRAL_API_KEY`) - **Ollama** — 本地模型，无需 API 密钥（默认地址：`http://localhost:11434`） 可在运行时使用 `:model ` 切换活动模型，或在 `~/.koko/config.toml` 中设置默认值。 ### 沙盒 沙盒是核心安全边界。每个文件操作在执行前都会根据其进行验证。 - **目录允许列表** — 代理只能读取、写入或列出于显式允许的目录内部。默认是当前工作目录；可配置额外目录。 - **符号链接安全路径解析** — 路径在验证前会通过符号链接进行规范化。最终组件的打开操作使用 `O_NOFOLLOW` 以防止 TOCTOU 替换。 - **类型化验证令牌** — 路径必须通过 `ValidatePath`（返回类型化的 `ValidPath`）才能到达任何 I/O 方法。编译器强制执行“编辑器中不使用原始路径”。 - **拒绝的文件模式** — 敏感文件通过 glob 模式被阻止，无论其位于哪个目录。默认值： - `.env`, `.env.*` - `*.pem`, `*.key`, `id_rsa*` - `credentials.json` - `*.secret`, `*.password` - **文件大小限制** — 读取/写入有可配置的最大值上限（默认：1 MB）。 ### 命令策略 通过 `exec_command` 运行的 shell 命令受基于正则表达式的策略控制： - **默认拒绝列表** 涵盖权限提升 (`sudo`, `su`)、远程网络 (`ssh`, `scp`, `nc`, `telnet`)、shell 求值 (`eval`, `source`, 反引号, `$(…)`)、管道到 shell (`curl|sh`, `wget|sh`) 以及其他经典的潜在风险。 - **可选的允许列表** — 设置后，每个命令的第一个标记必须出现在该列表中。拒绝模式优先。 - **用户确认** — 每次调用 `exec_command` 运行前都会提示用户明确批准。 - **执行加固** — 命令在运行时受 `ulimit` 对 CPU 秒数、内存和输出文件大小的限制。标准输出/标准错误有缓冲区限制。 ### 代理工具 代理拥有 12 个工具，全部通过沙盒进行调用： **文件操作** | 工具 | 描述 | |------|-------------| | `read_file` | 读取文件内容，可选行偏移量/限制 | | `write_file` | 创建新文件（除非 `overwrite=true`，否则拒绝覆盖） | | `replace_in_file` | 查找并替换，要求匹配唯一 | | `rename_file` | 移动或重命名文件 | | `delete_file` | 删除文件（支持 `/undo`） | | `list_dir` | 列出目录内容，可选递归树形结构 | | `search_files` | 跨文件模式搜索，带上下文行 | **Shell 操作** | 工具 | 描述 | |------|-------------| | `exec_command` | 运行 shell 命令（受策略控制，需要用户确认） | **记忆操作** | 工具 | 描述 | |------|-------------| | `save_memory` | 保存跨会话的持久记忆 | | `delete_memory` | 删除已存储的记忆 | | `list_memories` | 列出所有已存储的记忆及其正文 | **规划操作** | 工具 | 描述 | |------|-------------| | `exit_plan_mode` | 提出计划供用户批准（仅在计划模式下可调用） | ### 隐私与编辑 两层自动编辑： - **机密信息** — 扫描并编辑已知的令牌格式：AWS 密钥、GitHub PAT (`ghp_`/`gho_`/`ghu_`/`ghr_`/`ghs_`)、Google API 密钥、Slack 令牌、Stripe 密钥、OpenAI/Anthropic 密钥、JWT、PEM 私钥头，以及赋值式机密 (`API_KEY=...`)。 - **PII（个人身份信息）** — 电子邮件、美国 SSN、NANP 格式的美国电话号码、经 Luhn 验证的信用卡以及公共 IPv4 地址（不包括环回地址 / RFC1918 / 链路本地地址）。 编辑在发送到 LLM 的出站消息流上运行（当 `scrub_pii=true` 时，此为默认值），以及在会话写入磁盘时运行。`write_file` 和 `replace_in_file` 也会对其新内容运行机密扫描。 ### 项目检测 koko 扫描沙盒根目录下的标记文件（`go.mod`、`package.json`、`Cargo.toml`、`pyproject.toml`、`Dockerfile` 等），并在启动横幅和 LLM 系统提示中（用于定位）展示结果。 ### 审计日志 每个工具调用都记录到 `~/.koko/audit.jsonl`，包含时间戳、工具名称、参数、结果，以及一个链式 SHA-256 哈希（链接到前一个条目）。该链在启动时进行验证 — 哈希中断或缺失会导致明显失败。 ### 记忆 持久的跨会话记忆存储在 `~/.koko/memory/`。代理可以保存 (`save_memory`) 和删除 (`delete_memory`) 类型化的条目（用户 / 反馈 / 项目 / 引用），这些条目会在未来的会话中作为上下文显示。 ### 剧本 `~/.koko/plays/` 中的 Markdown 文件注册为命名的 playbook。可通过斜杠命令按名称调用任何 play（例如，`:review` 运行 `review.md` play）。`:plays` 列出已安装的 plays。 ### 计划模式 使用 `:plan` 切换以进入只读调查模式。写入工具被禁用，直到代理通过 `exit_plan_mode` 提出计划并经您批准。 ### 交互式 REPL | 命令 | 描述 | |---------|-------------| | `:help` | 显示可用命令 | | `:koko` | 打印 koko 吉祥物 | | `:clear` | 重置对话历史 | | `:history` | 显示消息计数 | | `:tokens` | 显示令牌使用情况统计 | | `:undo` | 撤销上一次文件更改 | | `:run ` | 直接运行 shell 命令（绕过代理） | | `:compact` | 总结历史以回收上下文 | | `:model [name]` | 显示或切换活动模型 | | `:config` | 显示当前配置 | | `:save` | 将当前会话保存到磁盘 | | `:resume` | 恢复已保存的会话 | | `:plays` | 列出已安装的 plays | | `:plan` | 切换计划模式 | | `:` | 运行命名的 play（例如，`:review`） | 当代理完成一个回合时，会话会自动保存。 ## 安装 **单行命令（macOS / Linux，amd64 / arm64）：** ``` curl -fsSL https://raw.githubusercontent.com/original-flipster69/koko/main/install.sh | sh ``` 该脚本会下载与您平台匹配的最新 GitHub 发行版，根据 `checksums.txt` 验证其 SHA-256 校验和，并将二进制文件安装到 `/usr/local/bin/koko`（如果该目录不可写，则使用 `sudo`）。 使用 `KOKO_INSTALL_DIR` 覆盖安装位置，或使用 `KOKO_VERSION` 固定版本： ``` KOKO_INSTALL_DIR=$HOME/.local/bin sh install.sh KOKO_VERSION=v0.1.0 sh install.sh ``` **通过 Go 安装：** ``` go install github.com/original-flipster69/koko@latest ``` ## 从源码构建 ``` ./build.sh ``` 构建脚本运行 `go build -buildvcs=false`，并且（如果 `goda` 在 `PATH` 中）会重新生成 `docs/deps.svg`。 ## 用法 ``` koko [flags] ``` | 标志 | 描述 | 默认值 | |------|-------------|---------| | `-provider` | LLM 提供商：`Claude`、`mistral`、`ollama` | `mistral` | | `-model` | 模型名称 | `mistral-large-latest` | | `-llm-url` | API URL（用于本地或自定义端点） | 提供商默认值 | | `-sandbox` | 沙盒根目录 | 当前工作目录 | | `-config` | 配置文件路径 | `~/.koko/config.toml` | ## 配置 koko 从 `~/.koko/config.toml` 读取配置： ``` [llm] provider = "Claude" model = "claude-sonnet-4-20250514" url = "" max_tokens = 16384 max_session_tokens = 1000000 [sandbox] root = "/home/user/projects" additional_dirs = [] deny_files = [".env", ".env.*", "*.pem", "*.key", "id_rsa*", "credentials.json", "*.secret", "*.password"] max_file_size = 1048576 scrub_pii = true [sandbox.exec] profile = "default" allow = [] deny = [] [ignore] mode = "gitignore" files = [] [style] thinking_verbs = ["thinking", "pondering", "scheming"] ``` API 密钥来自环境变量： - `CLAUDE_API_KEY` 用于 Claude - `MISTRAL_API_KEY` 用于 Mistral - Ollama 无需密钥 命令行标志会覆盖配置值；环境变量仅填充在配置 + 标志之后仍为空的项。 ## 数据目录 koko 将运行时数据存储在 `~/.koko/` 中： | 路径 | 用途 | |------|---------| | `config.toml` | 用户配置 | | `audit.jsonl` | 链式哈希工具调用日志 | | `koko.log` | 应用程序日志（JSON 格式） | | `session.json` | 已保存的对话历史（已编辑） | | `memory/` | 持久的跨会话记忆 | | `plays/` | 可作为 `:` 调用的 Markdown playbook |

标签：EVTX分析, Go语言, Homebrew安装, LLM集成, Python安全, XML 请求, 人工智能助手, 代理编码, 安全开发, 安全编码, 数据隔离, 日志审计, 最小权限访问, 沙箱化, 秘密管理, 程序破解, 终端助手, 编码助手, 编程工具, 网络安全, 远程代码执行, 隐私保护, 隐私编程