Muvon/octofs

## 为什么选择 Octofs？ 你的 AI 编程助手（Cursor、Claude、Windsurf 等）很聪明——但它对你的文件系统**一无所知**。Octofs 弥补了这一鸿沟，赋予你的 AI： - **眼睛** — 读取文件、搜索内容、浏览目录 - **双手** — 创建、编辑、原子化批量修改文件 - **上下文** — 执行命令、管理工作目录 ``` ┌─────────────────────────────────────────────────────────────┐ │ You: "Refactor all error handling to use anyhow::Context" │ ├─────────────────────────────────────────────────────────────┤ │ AI without Octofs: │ │ • "I can't see your project structure" │ │ • "Please paste the relevant files" │ │ • *Wastes 10 minutes on back-and-forth* │ ├─────────────────────────────────────────────────────────────┤ │ AI with Octofs: │ │ • Scans entire codebase in milliseconds │ │ • Finds all 47 error handling patterns │ │ • Suggests atomic batch edits │ │ • Applies changes with your approval │ └─────────────────────────────────────────────────────────────┘ ``` ## 有何不同 | 特性 | Octofs | 其他实现 | |---------|--------|--------| | **速度** | Rust 驱动，亚毫秒级响应 | Python/Node 实现，速度较慢 | | **内容搜索** | 内置搜索并包含上下文行 | 仅字符串匹配 | | **批量操作** | 单文件原子化多次编辑 | 一次仅一项 | | **行模式** | 基于 Hash（编辑后保持稳定）或基于行号 | 仅基于行号 | | **传输方式** | STDIO + HTTP (可流式传输的 HTTP) | 仅 STDIO | | **Shell 集成** | 支持后台进程 | 有限或完全不支持 | | **安全性** | 感知 Gitignore，路径验证 | 完全文件系统访问 | ## 安装说明 ### 从源码安装 需要 Rust 1.92 或更高版本。 ``` # Clone and build git clone https://github.com/muvon/octofs cd octofs cargo build --release # Binary will be at ./target/release/octofs # Optionally install globally cargo install --path . ``` ### 预编译二进制文件 从 [GitHub Releases](https://github.com/muvon/octofs/releases) 下载适合你平台的版本。 ## 快速开始 ### 1. 配置 AI 助手 **Cursor** (`~/.cursor/mcp.json`): ``` { "mcpServers": { "octofs": { "command": "/path/to/octofs" } } } ``` **Claude Desktop** (macOS 上位于 `~/Library/Application Support/Claude/claude_desktop_config.json`): ``` { "mcpServers": { "octofs": { "command": "/path/to/octofs" } } } ``` **Windsurf** (`~/.windsurf/mcp.json`): ``` { "mcpServers": { "octofs": { "command": "/path/to/octofs" } } } ``` ### 2. 重启 AI 助手 当你的 AI 助手连接时，MCP server 会自动启动。 ### 3. 尝试使用 让你的 AI 助手执行： - "展示项目结构" - "读取 main.rs 文件" - "搜索代码库中所有 `unwrap()` 的使用" - "创建一个名为 `test.rs` 的新文件" ## 功能特性 ### 📁 文件系统操作 - **查看文件与目录** — 读取单个/多个文件，使用 glob 模式列出目录，搜索内容 - **智能截断** — 大文件会被智能截断，以免上下文过载 - **感知 Gitignore** — 在遍历目录时遵守 `.gitignore` 规则 - **行范围** — 读取特定行范围，支持负索引（`-1` 表示最后一行） ### ✏️ 文本编辑 - **创建文件** — 创建新文件并自动创建父目录 - **字符串替换** — 替换精确匹配的字符串，并针对空格提供模糊回退 - **撤销** — 恢复上一次编辑（每个文件最多支持 10 级撤销） - **批量编辑** — 在单个文件上原子性地执行多次插入/替换操作 ### 🔍 代码智能 - **内容搜索** — 在文件中搜索字符串并包含上下文行 - **行提取** — 从一个文件复制特定行范围到另一个文件 ### 🖥️ Shell 与系统 - **命令执行** — 运行 shell 命令并捕获输出 - **后台进程** — 在后台运行长时命令，获取 PID 以便后续管理 - **工作目录** — 为操作设置/获取/重置工作目录上下文 ## 配置 ### 行标识符模式 Octofs 支持两种模式来标识文件中的行： #### Number 模式（默认） 行通过从 1 开始的行号标识： ``` 1: fn main() { 2: println!("Hello"); 3: } ``` 适用于：简单操作，一次性编辑。 #### Hash 模式 行通过基于内容生成的 4 字符十六进制 hash 标识： ``` a3bd: fn main() { c7f2: println!("Hello"); e9f1: } ``` 适用于：行号会发生变动的复杂多步编辑。Hash 在编辑过程中保持稳定。 **启用 hash 模式：** ``` { "mcpServers": { "octofs": { "command": "/path/to/octofs", "args": ["--line-mode", "hash"] } } } ``` ### 传输模式 #### STDIO（默认） 标准输入/输出传输。适用于所有 MCP 客户端。 ``` octofs # defaults to STDIO ``` #### HTTP 可流式传输的 HTTP 传输，适用于远程访问或多客户端场景。 ``` octofs --bind 0.0.0.0:12345 ``` 将客户端连接到 `http://localhost:12345/mcp`。 ### 工作目录 默认情况下，Octofs 在当前目录中运行。指定不同的根目录： ``` { "mcpServers": { "octofs": { "command": "/path/to/octofs", "args": ["--path", "/path/to/your/project"] } } } ``` ## MCP 工具参考 ### `view` — 读取文件，列出目录，搜索内容 **读取文件：** ``` {"paths": ["src/main.rs"]} {"paths": ["src/main.rs"], "lines": [10, 20]} {"paths": ["src/main.rs"], "lines": ["a3bd", "c7f2"]} // hash mode ``` **多文件读取（最多 50 个）：** ``` {"paths": ["src/main.rs", "src/lib.rs", "src/cli.rs"]} ``` **目录列表：** ``` {"paths": ["src/"]} {"paths": ["src/"], "pattern": "*.rs"} {"paths": ["src/"], "max_depth": 2, "include_hidden": true} ``` **内容搜索：** ``` {"paths": ["src"], "content": "fn main"} {"paths": ["src"], "content": "unwrap()", "context": 3} ``` ### `text_editor` — 创建，编辑，替换文本 **创建文件：** ``` {"command": "create", "path": "src/new.rs", "content": "pub fn new() {}"} ``` **替换字符串：** ``` { "command": "str_replace", "path": "src/main.rs", "old_text": "fn old()", "new_text": "fn new()" } ``` **撤销上一次编辑：** ``` {"command": "undo_edit", "path": "src/main.rs"} ``` ### `batch_edit` — 原子化多操作编辑 在单个文件上原子性地执行多次插入/替换操作。 **在开头插入：** ``` { "path": "src/main.rs", "operations": [ {"operation": "insert", "line_range": 0, "content": "// Header\n"} ] } ``` **替换行：** ``` { "path": "src/main.rs", "operations": [ {"operation": "replace", "line_range": [10, 15], "content": "new code here"} ] } ``` **Hash 模式（编辑后保持稳定）：** ``` { "path": "src/main.rs", "operations": [ {"operation": "replace", "line_range": ["a3bd", "c7f2"], "content": "new code"} ] } ``` ### `extract_lines` — 在文件之间复制行 ``` { "from_path": "src/utils.rs", "from_range": [10, 25], "append_path": "src/new.rs", "append_line": -1 } ``` ### `shell` — 执行命令 **前台运行：** ``` {"command": "cargo test"} {"command": "cd foo && cargo build"} ``` **后台运行：** ``` {"command": "python -m http.server 8000", "background": true} // Returns PID, kill later with: {"command": "kill 12345"} ``` ### `workdir` — 管理工作目录 **获取当前目录：** ``` {} ``` **设置新目录：** ``` {"path": "/path/to/project"} ``` **重置为会话根目录：** ``` {"reset": true} ``` ## 架构 ``` octofs/ ├── src/ │ ├── main.rs # Entry point, STDIO/HTTP server setup │ ├── cli.rs # CLI argument parsing (clap) │ └── mcp/ │ ├── server.rs # MCP protocol handler (rmcp SDK) │ ├── shared_utils.rs # Shared utilities │ ├── hint_accumulator.rs # Tool feedback hints │ └── fs/ # Filesystem tools │ ├── core.rs # view, batch_edit, extract_lines, text_editor │ ├── text_editing.rs # str_replace, undo, batch operations │ ├── directory.rs # Directory traversal │ ├── file_ops.rs # File operations │ ├── search.rs # Content search │ ├── shell.rs # Command execution │ ├── workdir.rs # Working directory management │ └── fs_tests.rs # Unit tests └── src/utils/ ├── glob.rs # Glob pattern matching ├── line_hash.rs # Content-based line hashing └── truncation.rs # Smart content truncation ``` **核心组件：** - **rmcp SDK** — 官方 Rust MCP SDK，用于协议处理 - **Tokio** — 用于并发操作的异步运行时 - **文件锁** — 每个文件独立的异步锁，防止并发写入冲突 - **撤销历史** — 每个文件最多 10 级撤销，线程安全存储 ## 开发 ``` # Build cargo build --release # Run tests cargo test # Lint (zero warnings policy) cargo clippy # Format cargo fmt # Run locally cargo run ``` ### 运行测试 ``` # All tests cargo test # Specific test cargo test test_view_file # With output cargo test -- --nocapture ``` ## 贡献 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 **快速清单：** 1. 提交前运行 `cargo fmt` 2. 确保 `cargo clippy` 通过且无警告 3. 为新功能添加测试 4. 根据需要更新文档 ## 安全 请参阅 [SECURITY.md](SECURITY.md) 了解安全政策和报告漏洞。 ## 许可证 Apache-2.0 — 请参阅 [LICENSE](LICENSE) ## 致谢 - [rmcp](https://github.com/anthropics/rust-sdk) — 官方 Rust MCP SDK - [Model Context Protocol](https://modelcontextprotocol.io) — 协议规范

标签：AI助手, Claude, Cursor, CVE检测, DLL 劫持, DNS解析, IDE插件, LLM工具, MCP服务器, Model Context Protocol, Rust, SOC Prime, 人工智能, 代码重构, 原子操作, 可视化界面, 命令执行, 大语言模型, 开发工具, 开源项目, 批量修改, 文件管理, 文件系统, 用户模式Hook绕过, 网络流量审计, 通知系统