article

README

项目上下文

这是一个使用 React 和 Next.js 的 TypeScript 项目。

开发指南

使用函数式组件和 Hooks
遵循现有文件结构
为新功能编写测试
使用 TypeScript 严格模式

**特性：**
- 内容自动作为 `<system_prompt>...</system_prompt>` 注入到每个提示前。
- 最大大小：1 MB。
- 超过限制自动截断（UTF-8 字符边界安全）。

### 🔒 安全特性
- ✅ **默认只读** - 无 `auto` 参数时仅允许读取操作。
- ✅ **显式权限** - 需明确指定 `auto` 级别才能修改。
- ✅ **超时强制** - 防止无限执行（默认 10 分钟）。
- ✅ **高权限保护** - `high` 级别需配置文件允许。
- ✅ **资源限制** - 自动大小和内存限制：
  - Agent 消息：10 MB。
  - 所有消息：50 MB。
  - DROID.md：1 MB。
  - stderr：100 KB。

### 🛠️ 开发指南
#### 构建命令
```bash
cargo build              # 调试构建
cargo build --release    # 优化构建（启用 LTO）
cargo clean              # 清理构建产物

测试和代码质量

cargo test               # 运行测试
cargo clippy             # 代码检查
cargo fmt                # 代码格式化
cargo check              # 快速类型检查

开发要求

Rust 1.70+。
Droid CLI 已安装并在 PATH 中。

🏗️ 架构概览

数据流

Claude Code (MCP Client)
    ↓ stdio transport
MCP Server (main.rs)
    ↓ clap CLI parsing
Tool Handler (server.rs::droid)
    ↓ parameter validation + MCP protocol
CLI Wrapper (droid.rs::run)
    ↓ async process spawn + JSON stream parsing
droid exec CLI (subprocess)

核心文件

| 文件 | 行数 | 职责 | |-----------------|-------|-------------------------| | src/main.rs | ~93 | MCP 服务器入口点，CLI 参数解析 | | src/server.rs | ~369 | MCP 工具定义，参数验证，TOON 编码 | | src/droid.rs | ~820 | Droid CLI 封装，流解析，配置管理 | | src/lib.rs | ~3 | 模块声明 |

关键设计模式

延迟配置加载 - 使用 OnceLock 缓存静态配置。
流式处理 - 异步逐行解析 JSON 流。
大小限制 - 多层截断边界（10MB/50MB/1MB）。
超时包装 - tokio::time::timeout 强制超时。
自定义模型系统 - 智能 GPT 优先 + 索引引用。

📁 配置文件位置总结

| 文件 | 位置 | 用途 | |---------------------------|---------------------------------------------|-----------| | droid-mcp.config.json | 工作目录或 $DROID_MCP_CONFIG_PATH | 服务器配置 | | ~/.factory/config.json | ~/.factory/ 或 %USERPROFILE%\.factory\ | 自定义模型配置 | | DROID.md | cwd 指定的工作目录 | 项目特定上下文 |

🎉 功能完整性检查

✓ 核心功能

[x] MCP 协议完整支持。
[x] 所有 droid exec 参数映射。
[x] 会话管理（SESSION_ID）。
[x] 自定义模型系统。
[x] DROID.md 注入。
[x] 智能模型选择（GPT 优先）。

✓ 高级功能

[x] 推理模式（reasoning_effort）。
[x] 规范模式（use_spec）。
[x] 权限跳过（skip_permissions_unsafe）。
[x] 输出格式控制（output_format）。
[x] 文件输入（file）。
[x] 工具控制（enabled_tools/disabled_tools）。

✓ 质量保证

[x] 零警告编译。
[x] Clippy 全通过。
[x] 跨平台支持（Windows/Linux/macOS）。
[x] 完整错误处理。
[x] 资源限制和安全控制。

💻 使用示例

场景 1️⃣：基础查询（使用所有默认值）

await use_mcp_tool("droid", {
  PROMPT: "分析这个项目的代码质量"
});
// 自动使用：auto=high, 第一个 GPT 模型, stream-json

场景 2️⃣：深度推理 + 规范模式

await use_mcp_tool("droid", {
  PROMPT: "重构认证模块，提升安全性",
  reasoning_effort: "high",  // 深度推理
  use_spec: true,            // 先规划后执行
  spec_model: "gpt-5.1"      // 使用 GPT-5.1 规划
});

场景 3️⃣：多轮会话

// 第一轮：开始任务
const result1 = await use_mcp_tool("droid", {
  PROMPT: "创建用户认证功能"
});

// 第二轮：继续会话
const result2 = await use_mcp_tool("droid", {
  PROMPT: "添加单元测试",
  SESSION_ID: result1.SESSION_ID  // 恢复上下文
});

// 第三轮：继续完善
const result3 = await use_mcp_tool("droid", {
  PROMPT: "优化性能",
  SESSION_ID: result2.SESSION_ID
});

场景 4️⃣：从文件读取任务

// prompt.md 内容：
// # 任务
// 重构整个项目架构...

await use_mcp_tool("droid", {
  file: "./prompt.md",      // 从文件读取
  reasoning_effort: "high"
});

场景 5️⃣：自定义模型

await use_mcp_tool("droid", {
  PROMPT: "生成 API 文档",
  model: "custom:Sonnet-4.5-[88code]-0"  // 使用自定义模型
});

场景 6️⃣：隔离环境无限制执行

// ⚠️ 仅在 Docker 容器等隔离环境使用！
await use_mcp_tool("droid", {
  PROMPT: "系统级配置修改",
  skip_permissions_unsafe: true  // 跳过所有权限检查
});

场景 7️⃣：精细控制工具

await use_mcp_tool("droid", {
  PROMPT: "分析代码但不要修改",
  enabled_tools: "read,grep,find",   // 仅允许读取类工具
  disabled_tools: "write,edit,bash"  // 禁用写入类工具
});

droid-mcp-rs