# 04 - 项目结构

```
Agentsd/
├── Cargo.toml                     # workspace 根
├── README.md                      # 设计总览
│
├── docs/                          # 设计文档
│   ├── 01-内核系统调用.md
│   ├── 02-插件模型.md
│   ├── 03-实施路线.md
│   └── 04-项目结构.md            # 本文件
│
├── proto/                         # 协议定义(单一事实来源)
│   └── agentsd.proto              # 9 service + PluginBridge
│
├── core/                          # Rust 源码
│   ├── proto/                     # gRPC 协议 crate
│   │   ├── Cargo.toml
│   │   ├── build.rs
│   │   └── src/lib.rs
│   │
│   └── agentsd/                   # 主二进制 crate
│       ├── Cargo.toml
│       └── src/
│           ├── main.rs            # 入口
│           ├── server.rs          # gRPC server
│           ├── plugin.rs          # 插件注册表 + data/plugins.json 持久化
│           ├── paths.rs           # 程序目录 data/ 路径
│           ├── callback.rs        # Timer 回调事件通道
│           ├── permission.rs      # syscall 权限白名单校验
│           └── syscall/           # 9 个 syscall 模块
│               ├── mod.rs
│               ├── display.rs
│               ├── audio.rs
│               ├── fs.rs
│               ├── memory.rs
│               ├── network.rs
│               ├── process.rs
│               ├── timer.rs
│               ├── hid.rs
│               └── input.rs
│
├── data/                          # 运行时数据(程序启动后自动创建)
│   ├── memory.db                  # Memory syscall SQLite 数据库
│   └── plugins.json               # 插件注册状态
│
└── plugins/                       # 插件(任意语言)
    ├── _sdk/                      # 共享 Python gRPC stub
    │   ├── __init__.py
    │   ├── agentsd_pb2.py
    │   └── agentsd_pb2_grpc.py
    │
    ├── echo/                      # 测试插件(Rust)
    │   ├── plugin.yaml
    │   └── src/main.rs
    │
    ├── ai_test/                   # AI 手动验证插件(Rust,enabled=false,autoload=false)
    │   ├── plugin.yaml
    │   └── src/main.rs
    │
    ├── hermes/                    # Hermes Agent 桥接(Python,Rust 版仅 stub)
    │   ├── plugin.yaml
    │   └── hermes_plugin.py
    │
    └── claudecode/                # Claude Code CLI 桥接(Rust)
        ├── plugin.yaml
        └── src/main.rs
```

## 布局原则

| 目录 | 职责 | 规则 |
|---|---|---|
| `docs/` | 设计文档 | 只放 .md |
| `proto/` | 协议定义 | 只放 .proto,单一事实来源 |
| `core/` | Rust 代码 | workspace members |
| `data/` | 运行时数据 | 默认路径为程序所在目录的 data 文件夹 |
| `plugins/` | 所有插件 | 每个插件一个目录,含 plugin.yaml |
| `plugins/_sdk/` | 共享 stub | 生成一次,插件 import 引用,不复制 |

## 构建

```bash
cargo build --release       # 约 6.1MB 单二进制
```

## 运行

```bash
# 启动内核
./target/release/agentsd.exe

# 启动插件(各开一个终端)
python plugins/hermes/hermes_plugin.py
cargo run -p agentsd-plugin-claudecode
```

## 手动验证插件

`plugins/ai_test` 是专门给 AI/人工做端到端验证的插件,`plugin.yaml` 中 `enabled: false`、`autoload: false`,默认不应被自动加载。

```bash
RUST_LOG=agentsd=info ./target/release/agentsd.exe
cargo run -p agentsd-plugin-ai-test
```

## 重新生成 SDK

```bash
python -m grpc_tools.protoc \
  -Iproto \
  --python_out=plugins/_sdk \
  --grpc_python_out=plugins/_sdk \
  proto/agentsd.proto
```