未知时光
e75cfc6812
- docs/01: sync all syscall signatures with proto (missing params, invented callback params, stream semantics, return types) - docs/02: mark unimplemented features (FFI system plugins, topo sort, lifecycle CLI, watchdog); clarify plugin.yaml is not parsed by the kernel - registration goes through gRPC PluginBridge.Register; correct permission model and session_id descriptions - docs/03: check off implemented stage 3 items (Hermes adapter, Claude Code plugin) - docs/04: data/ actual location, add Cargo.toml to plugin trees, note __init__.py is hand-maintained - README: status line now reflects actual progress Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
168 lines
4.4 KiB
Markdown
168 lines
4.4 KiB
Markdown
# 01 - 内核系统调用
|
|
|
|
agentsd 定义 9 个 syscall 接口。类比 Linux 内核 syscall 表——接口稳定,实现可换(由系统插件提供)。
|
|
|
|
---
|
|
|
|
## 1. Display
|
|
|
|
向用户呈现信息。类比: `write(stdout)` / framebuffer / DRM。
|
|
|
|
**管**:给人看的输出 | **不管**:文件写入、设备控制
|
|
|
|
```
|
|
display.text(content)
|
|
display.rich(markup, format)
|
|
display.image(data, format)
|
|
display.clear()
|
|
display.notify(message)
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Audio
|
|
|
|
声音播放与采集。类比: `/dev/snd` / ALSA / PipeWire。
|
|
|
|
**管**:扬声器输出、麦克风输入 | **不管**:TTS/STT(插件的事)
|
|
|
|
```
|
|
audio.play(stream AudioChunk{data, format}) # 客户端流式上传音频帧
|
|
audio.stop()
|
|
audio.volume(level)
|
|
audio.record_start(format)
|
|
audio.record_stop() -> data
|
|
audio.record_stream(format) -> stream AudioChunk # 服务端流式返回录音帧
|
|
```
|
|
|
|
---
|
|
|
|
## 3. FS
|
|
|
|
文件系统。类比: `open / read / write / stat / readdir / inotify`。
|
|
|
|
**管**:磁盘文件 | **不管**:结构化数据(Memory)
|
|
|
|
```
|
|
fs.read(path, offset?, length?) -> data
|
|
fs.write(path, data, append?)
|
|
fs.delete(path)
|
|
fs.rename(from, to)
|
|
fs.stat(path) -> metadata
|
|
fs.list(dir) -> entries
|
|
fs.watch(path) -> stream FsWatchEvent{path, kind}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Memory
|
|
|
|
结构化存储。类比: `mmap / shmem`,但面向 KV + 索引。
|
|
|
|
**管**:持久数据、查询 | **不管**:文件(FS)
|
|
|
|
```
|
|
memory.read(key) -> value
|
|
memory.write(key, value)
|
|
memory.delete(key)
|
|
memory.list(prefix?, limit?) -> keys
|
|
memory.search(query, limit?) -> results
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Network
|
|
|
|
远程通信。类比: `socket / connect / bind / listen / send / recv`。
|
|
|
|
**管**:对外连接、监听 | **不管**:本地 IPC(内核 gRPC 总线)
|
|
|
|
```
|
|
network.request(url, method, headers?, body?) -> response # HTTP 请求
|
|
network.open_conn(addr, protocol) -> stream ConnEvent # TCP 建连,流式推送入站数据
|
|
network.send(conn_id, data) # 向已有连接发数据
|
|
network.close(conn_id) # 关闭连接
|
|
network.listen(port, protocol) -> stream ConnEvent # 监听端口,每 accept 推送 ConnEvent
|
|
network.available() -> bool # 网络连通性探测
|
|
```
|
|
|
|
gRPC 流式语义:OpenConn/Listen 返回 `stream ConnEvent{conn_id, data, kind}`。
|
|
- 首帧 kind="open"/"accept" 携带 conn_id,后续 kind="data" 携带入站字节,kind="closed" 表示对端关闭。
|
|
- 发送用单独的 `Send` RPC(需传 conn_id),关闭用 `Close` RPC。
|
|
|
|
---
|
|
|
|
## 6. Process
|
|
|
|
子进程管理。类比: `fork / execve / waitpid / kill / pipe`。
|
|
|
|
**管**:子进程生命周期、stdio | **不管**:插件间路由(内核调度)
|
|
|
|
```
|
|
proc.spawn(cmd, args, env?, cwd?) -> pid
|
|
proc.kill(pid)
|
|
proc.wait(pid) -> exitcode
|
|
proc.stdin(pid, data)
|
|
proc.stdout(pid) -> stream DataChunk # 服务端流式输出
|
|
proc.signal(pid, sig)
|
|
proc.list() -> [ProcInfo{pid, cmd, status}]
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Timer
|
|
|
|
定时调度。类比: `timer_create / timerfd_create`。
|
|
|
|
**管**:时间触发 | **不管**:用户事件(Input)
|
|
|
|
```
|
|
timer.once(delay, callback) -> id # 到期后通过 PluginBridge.StreamCall 投递事件
|
|
timer.cron(expr, callback) -> id # cron 表达式格式(7段): sec min hour day month weekday year
|
|
timer.cancel(id)
|
|
timer.now() -> timestamp
|
|
```
|
|
|
|
---
|
|
|
|
## 8. HID
|
|
|
|
屏幕截取与输入模拟。类比: `/dev/input` + `/dev/fb` + uinput。
|
|
|
|
能力可缺失。
|
|
|
|
**管**:屏幕读取、输入模拟 | **不管**:向用户展示(Display)、用户主动输入(Input)
|
|
|
|
```
|
|
hid.capture(x, y, width, height) -> image
|
|
hid.mouse(x, y, action, button)
|
|
hid.keyboard(key, action, modifiers?)
|
|
hid.ocr(x, y, width, height) -> text
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Input
|
|
|
|
用户主动输入。类比: `read(stdin)` / evdev。
|
|
|
|
**管**:用户给的东西 | **不管**:文件读(FS)、录音(Audio)、屏幕读(HID)
|
|
|
|
```
|
|
input.text() -> string
|
|
input.key() -> keyevent
|
|
input.clipboard() -> data
|
|
input.events() -> stream InputEvent # 服务端流式事件
|
|
```
|
|
|
|
---
|
|
|
|
## 设计原则
|
|
|
|
1. **接口稳定,实现可换** — syscall 签名不变,系统插件可替换(= 换驱动不改应用)
|
|
2. **每个独立** — 可单独实现、测试、编译(= 内核模块独立)
|
|
3. **能力可缺失** — 无声卡则 Audio 不可用,不崩(= Linux 无设备则驱动不加载)
|
|
4. **权限在此层** — 白名单外的 syscall 拒绝(= seccomp)
|
|
5. **离线 = Network 不可用** — 其余八个正常(= 拔网线不影响本地)
|
|
6. **内核不做业务** — TTS/浏览器/Agent 全是插件(= 内核不含 Web 服务器)
|