openfang/CLAUDE.md

# OpenFang — Agent Instructions

## Project Overview
OpenFang is an open-source Agent Operating System written in Rust (14 crates).
- Config: `~/.openfang/config.toml`
- Default API: `http://127.0.0.1:4200`
- CLI binary: `target/release/openfang.exe` (or `target/debug/openfang.exe`)

---

## Architecture Overview

### Crate Structure (14 crates)
```
openfang-types     # 基础类型 (零依赖，被所有 crate 使用)
openfang-memory    # 存储层 (SQLite + 向量 + 知识图谱)
openfang-runtime   # Agent 运行时 (LLM 驱动 + 工具执行 + WASM)
openfang-kernel    # 核心协调器 (Registry + Scheduler + EventBus)
openfang-api       # HTTP 服务 (Axum + WebSocket + SSE)
openfang-wire      # P2P 协议 (OFP + HMAC 认证)
openfang-channels  # 消息渠道 (40+ 适配器)
openfang-skills    # 技能系统 (4 运行时 + 60 技能)
openfang-hands     # 自主能力包 (7 预构建 Agent)
openfang-extensions # 集成系统 (25+ MCP 模板)
openfang-cli       # 命令行 (14+ 子命令)
openfang-desktop   # 桌面应用 (Tauri 2.0)
openfang-migrate   # 迁移工具 (OpenClaw 导入)
```

### Dependency Rules
1. `openfang-types` 不能依赖任何内部 crate
2. `openfang-kernel` 依赖 `openfang-runtime`, `openfang-memory`
3. `openfang-api` 依赖 `openfang-kernel`
4. **禁止循环依赖** - 使用 `KernelHandle` trait 解决 runtime ↔ kernel 循环

### Key Design Patterns
- **KernelHandle Trait**: 解决 runtime ↔ kernel 循环依赖
- **Plugin Architecture**: Skills/Hands/Extensions 可扩展
- **Event-Driven**: EventBus 发布订阅模式
- **Dual Persistence**: 内存 (DashMap) + SQLite 双写

---

## Build & Verify Workflow

After every feature implementation, run ALL THREE checks:
```bash
cargo build --workspace --lib          # Must compile (use --lib if exe is locked)
cargo test --workspace                 # All tests must pass (currently 1744+)
cargo clippy --workspace --all-targets -- -D warnings  # Zero warnings
```

---

## MANDATORY: Live Integration Testing

**After implementing any new endpoint, feature, or wiring change, you MUST run live integration tests.** Unit tests alone are not enough — they can pass while the feature is actually dead code.

### Live Test Checklist
- [ ] Route registered in `server.rs` router
- [ ] Handler implemented in `routes.rs`
- [ ] GET returns real data (not empty/null)
- [ ] POST/PUT persists data (read back to verify)
- [ ] LLM integration works (real API call)
- [ ] Side effects tracked (metering/budget)
- [ ] Dashboard UI shows new components

### Quick Integration Test Script
```bash
# Stop any running daemon
tasklist | grep -i openfang && taskkill //PID <pid> //F
sleep 3

# Build and start
cargo build --release -p openfang-cli
GROQ_API_KEY=<key> target/release/openfang.exe start &
sleep 6

# Verify health
curl -s http://127.0.0.1:4200/api/health

# Test your new endpoint
curl -s http://127.0.0.1:4200/api/<your-endpoint>

# Cleanup
taskkill //PID <pid> //F
```

---

## Persistence Rules (CRITICAL)

### Rule 1: Dual Write Pattern
所有 Agent 修改操作必须同时更新:
1. **内存**: `registry.xxx()` 更新 DashMap
2. **SQLite**: `memory.save_agent(&entry)` 持久化

```rust
// ✅ 正确: Kernel 层包装方法
pub fn set_agent_mode(&self, agent_id: AgentId, mode: AgentMode) -> KernelResult<()> {
    self.registry.set_mode(agent_id, mode)?;  // 内存
    if let Some(entry) = self.registry.get(agent_id) {
        let _ = self.memory.save_agent(&entry);  // SQLite
    }
    Ok(())
}

// ❌ 错误: 直接调用 registry (不持久化)
state.kernel.registry.set_mode(agent_id, mode)
```

### Rule 2: 使用 Kernel 包装方法
在 API 层 (`routes.rs`) 始终调用 kernel 方法，不要直接调用 registry:

| ❌ 错误调用 | ✅ 正确调用 |
|------------|------------|
| `registry.set_mode()` | `kernel.set_agent_mode()` |
| `registry.set_state()` | `kernel.set_agent_state()` |
| `registry.update_identity()` | `kernel.update_agent_identity()` |
| `registry.update_name()` | `kernel.update_agent_name()` |
| `registry.update_description()` | `kernel.update_agent_description()` |

### Rule 3: 已持久化的操作
以下操作已正确实现持久化，可直接使用:
- `kernel.update_agent_model()`
- `kernel.update_agent_system_prompt()`
- `kernel.set_agent_skills()`
- `kernel.set_agent_mcp_servers()`
- `kernel.kill_agent()` (调用 `memory.remove_agent()`)

---

## API Development Rules

### Rule 1: Route Registration
新路由必须在两处注册:
1. `server.rs` - 添加到 router
2. `routes.rs` - 实现 handler 函数

```rust
// server.rs
.route("/api/agents/{id}/custom", axum::routing::get(routes::get_custom).put(routes::set_custom))

// routes.rs
pub async fn get_custom(...) -> impl IntoResponse { ... }
pub async fn set_custom(...) -> impl IntoResponse { ... }
```

### Rule 2: AppState Access
```rust
// AppState 结构
pub struct AppState {
    pub kernel: Arc<OpenFangKernel>,
    pub started_at: Instant,
    pub peer_registry: Option<Arc<PeerRegistry>>,  // 注意: Option<Arc<...>>
    pub bridge_manager: tokio::sync::Mutex<Option<BridgeManager>>,
    pub channels_config: tokio::sync::RwLock<ChannelsConfig>,
    pub shutdown_notify: Arc<tokio::sync::Notify>,
}
```

### Rule 3: Error Response Format
```rust
// 统一错误响应格式
(StatusCode::NOT_FOUND, Json(serde_json::json!({"error": "Agent not found"})))
(StatusCode::BAD_REQUEST, Json(serde_json::json!({"error": "Invalid input"})))
(StatusCode::CONFLICT, Json(serde_json::json!({"error": "Name already exists"})))
```

### Rule 4: Success Response Format
```rust
// 统一成功响应格式
(StatusCode::OK, Json(serde_json::json!({"status": "ok", "agent_id": id})))
(StatusCode::CREATED, Json(serde_json::json!({"id": new_id, "name": name})))
```

---

## Config & Types Rules

### Rule 1: New Config Fields
添加新配置字段需要:
1. 在 struct 中添加字段
2. 添加 `#[serde(default)]`
3. 在 `Default` impl 中添加默认值
4. 确保 `Serialize + Deserialize` derived

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KernelConfig {
    // ... existing fields ...

    #[serde(default)]
    pub new_field: String,  // 必须有 #[serde(default)]
}

impl Default for KernelConfig {
    fn default() -> Self {
        Self {
            // ... existing defaults ...
            new_field: String::new(),  // 必须在 Default 中
        }
    }
}
```

### Rule 2: Type Definitions
新类型定义放在正确的 crate:
- **共享类型**: `openfang-types/`
- **API 特有**: `openfang-api/src/`
- **Kernel 特有**: `openfang-kernel/src/`

---

## Security Rules

### 16-Layer Security Model
1. Capability-based access control
2. Path traversal protection
3. SSRF protection (私有 IP 阻断)
4. Ed25519 signed manifests
5. Merkle hash chain audit
6. Information flow taint tracking
7. HMAC-SHA256 mutual auth
8. API key Bearer auth
9. GCRA rate limiter
10. Security headers (CSP/HSTS/X-Frame-Options)
11. Secret zeroization
12. Subprocess environment isolation
13. Health endpoint redaction
14. Loop guard with SHA256 detection
15. Session repair
16. Circuit breaker thresholds

### Security Checklist for New Features
- [ ] 输入验证 (sanitize user input)
- [ ] 权限检查 (capability-based)
- [ ] 路径安全 (no path traversal)
- [ ] SSRF 防护 (block private IPs)
- [ ] 敏感信息脱敏 (logs, health endpoint)

---

## Common Gotchas

### Build Issues
| 问题 | 解决方案 |
|------|----------|
| `openfang.exe` locked | 使用 `--lib` flag 或 kill daemon |
| cargo not found | 检查 PATH 环境变量 |
| clippy warnings | 所有 warning 必须修复 (`-D warnings`) |

### Type Mismatches
| 问题 | 解决方案 |
|------|----------|
| `PeerRegistry` 类型 | kernel: `Option<PeerRegistry>`, AppState: `Option<Arc<PeerRegistry>>` |
| `AgentLoopResult.response` | 不是 `.response_text` |
| UUID parsing | 使用 `.parse::<AgentId>()` |

### Windows-Specific
| 问题 | 解决方案 |
|------|----------|
| taskkill syntax | `taskkill //PID <pid> //F` (double slashes) |
| Path separators | 使用 `/` 或 `std::path::PathBuf` |
| Sleep command | `sleep` 在 Git Bash/MSYS2 中可用 |

### CLI Commands
- 启动守护进程: `openfang start` (不是 `daemon`)
- 停止守护进程: `taskkill //PID <pid> //F`

---

## Frontend Rules (Alpine.js SPA)

### File Locations
- HTML: `crates/openfang-api/static/index_body.html`
- JS: `crates/openfang-api/static/js/`
- CSS: `crates/openfang-api/static/css/`

### Adding New UI Components
1. 在 `index_body.html` 添加 HTML 结构
2. 在对应的 JS 文件中添加 Alpine.js data/methods
3. 在 `api.js` 中添加 API 调用方法

### Alpine.js Pattern
```javascript
// 在页面组件中
function myPage() {
    return {
        data: [],
        loading: false,

        async loadData() {
            this.loading = true;
            try {
                this.data = await OpenFangAPI.getData();
            } finally {
                this.loading = false;
            }
        },

        init() {
            this.loadData();
        }
    }
}
```

---

## Testing Rules

### Test Categories
1. **Unit Tests**: `#[cfg(test)] mod tests { ... }` 在各模块内
2. **Integration Tests**: `tests/` 目录
3. **Live Tests**: 运行 daemon 后 curl 测试

### Test Requirements
- 所有新功能必须有测试
- 测试覆盖率目标: 90%+
- 测试名称: `test_<功能>_<场景>`

### Test Pattern
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature_success() {
        // Arrange
        let store = setup();

        // Act
        let result = store.do_something();

        // Assert
        assert!(result.is_ok());
    }

    #[test]
    fn test_feature_error_case() {
        // Test error handling
    }
}
```

---

## LLM Provider Support

### Supported Providers (30+)
- Anthropic (Claude)
- OpenAI (GPT)
- Google (Gemini)
- Groq, OpenRouter, DeepSeek, Together, Mistral, Fireworks
- Ollama, vLLM, LM Studio (local)
- Perplexity, Cohere, AI21, Cerebras, SambaNova
- HuggingFace, xAI, Replicate
- GitHub Copilot, Codex, Claude Code CLI
- 中国提供商: 智谱 GLM, 百炼, Moonshot, Qwen, Minimax, 千帆

### Adding New Provider
1. 在 `openfang-types/src/model_catalog.rs` 添加 BASE_URL 常量
2. 在 `openfang-runtime/src/model_catalog.rs` 添加模型和提供商信息
3. 在 `openfang-runtime/src/drivers/mod.rs` 添加 `provider_defaults()` 条目
4. 添加测试用例

---

## Code Style Guidelines

### Rust Conventions
- 使用 `use` 导入，避免完整路径
- 错误处理使用 `Result<T, E>` 和 `?` 操作符
- 使用 `tracing` crate 进行日志记录
- 异步代码使用 `tokio` 运行时

### Naming Conventions
- 函数/变量: `snake_case`
- 类型/Trait: `PascalCase`
- 常量: `SCREAMING_SNAKE_CASE`
- 模块: `snake_case`

### Documentation
- 公共 API 必须有文档注释 (`///`)
- 复杂逻辑必须有注释说明
- 使用 `//!` 作为模块级文档

---

## Key Files Quick Reference

| 文件 | 用途 |
|------|------|
| `crates/openfang-kernel/src/kernel.rs` | 核心协调器，所有子系统的入口 |
| `crates/openfang-kernel/src/registry.rs` | Agent 内存注册表 (DashMap) |
| `crates/openfang-memory/src/structured.rs` | Agent SQLite 持久化 |
| `crates/openfang-api/src/server.rs` | HTTP 路由注册 |
| `crates/openfang-api/src/routes.rs` | HTTP 处理函数 |
| `crates/openfang-api/src/ws.rs` | WebSocket 处理 |
| `crates/openfang-runtime/src/drivers/mod.rs` | LLM 提供商驱动 |
| `crates/openfang-types/src/model_catalog.rs` | 模型/提供商常量 |

---

## Current Date
Today's date is 2026-03-01.