Agentsd/docs/04-项目结构.md

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/                          # 运行时数据(实际位于可执行文件旁,即 target/debug|release/data/)
│   ├── memory.db                  # Memory syscall SQLite 数据库
│   └── plugins.json               # 插件注册状态
│
└── plugins/                       # 插件(任意语言)
    ├── _sdk/                      # 共享 Python gRPC stub
    │   ├── __init__.py
    │   ├── agentsd_pb2.py
    │   └── agentsd_pb2_grpc.py
    │
    ├── plugin-sdk/                # Rust 插件 SDK crate(连接/注册/元数据辅助)
    │   ├── Cargo.toml
    │   └── src/lib.rs
    │
    ├── echo/                      # 测试插件(Rust)
    │   ├── Cargo.toml
    │   ├── plugin.yaml
    │   └── src/main.rs
    │
    ├── ai_test/                   # AI 手动验证插件(Rust,enabled=false,autoload=false)
    │   ├── Cargo.toml
    │   ├── plugin.yaml
    │   └── src/main.rs
    │
    ├── hermes/                    # Hermes Agent 桥接(Python 桥接工具注册表;Rust 版提供 echo 验证路由)
    │   ├── Cargo.toml
    │   ├── plugin.yaml
    │   ├── hermes_plugin.py
    │   └── src/main.rs
    │
    └── claudecode/                # Claude Code CLI 桥接(Rust)
        ├── Cargo.toml
        ├── plugin.yaml
        └── src/main.rs

布局原则

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

构建

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

运行

# 启动内核
./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,默认不应被自动加载。

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

重新生成 SDK

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

注:protoc 只生成 agentsd_pb2.py 和 agentsd_pb2_grpc.py;plugins/_sdk/__init__.py 是手工维护的包标记文件,重新生成后不要删除。