Agentsd/docs/01-内核系统调用.md

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 服务器)