Initial Agentsd project commit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-09 15:09:56 +08:00
commit 1bf1f08f9a
41 changed files with 8106 additions and 0 deletions
--- a/docs/04-项目结构.md
+++ b/docs/04-项目结构.md
@@ -0,0 +1,117 @@
+# 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/                      # 测试插件
+    │   ├── plugin.yaml
+    │   └── echo_plugin.py
+    │
+    ├── ai_test/                   # AI 手动验证插件(enabled=false,autoload=false)
+    │   ├── plugin.yaml
+    │   └── ai_test_plugin.py
+    │
+    ├── hermes/                    # Hermes Agent 桥接(63 tool)
+    │   ├── plugin.yaml
+    │   └── hermes_plugin.py
+    │
+    └── claudecode/                # Claude Code CLI 桥接
+        ├── plugin.yaml
+        ├── claudecode_plugin.py
+        └── test_chat.py
+```
+
+## 布局原则
+
+| 目录 | 职责 | 规则 |
+|---|---|---|
+| `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
+python plugins/claudecode/claudecode_plugin.py
+```
+
+## 手动验证插件
+
+`plugins/ai_test` 是专门给 AI/人工做端到端验证的插件,`plugin.yaml` 中 `enabled: false`、`autoload: false`,默认不应被自动加载。
+
+```bash
+RUST_LOG=agentsd=info ./target/release/agentsd.exe
+python plugins/ai_test/ai_test_plugin.py
+```
+
+## 重新生成 SDK
+
+```bash
+python -m grpc_tools.protoc \
+  -Iproto \
+  --python_out=plugins/_sdk \
+  --grpc_python_out=plugins/_sdk \
+  proto/agentsd.proto
+```