Initial Agentsd project commit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

@@ -0,0 +1,164 @@
+# 01 - 内核系统调用
+
+agentsd 定义 9 个 syscall 接口。类比 Linux 内核 syscall 表——接口稳定,实现可换(由系统插件提供)。
+
+---
+
+## 1. Display
+
+向用户呈现信息。类比: `write(stdout)` / framebuffer / DRM。
+
+**管**:给人看的输出 | **不管**:文件写入、设备控制
+
+```
+display.text(content)
+display.rich(markup)
+display.image(data, format)
+display.clear()
+display.notify(message)
+```
+
+---
+
+## 2. Audio
+
+声音播放与采集。类比: `/dev/snd` / ALSA / PipeWire。
+
+**管**:扬声器输出、麦克风输入 | **不管**:TTS/STT(插件的事)
+
+```
+audio.play(data, format)
+audio.stop()
+audio.volume(level)
+audio.record.start(format)
+audio.record.stop() -> data
+audio.record.stream(callback)
+```
+
+---
+
+## 3. FS
+
+文件系统。类比: `open / read / write / stat / readdir / inotify`。
+
+**管**:磁盘文件 | **不管**:结构化数据(Memory)
+
+```
+fs.read(path) -> data
+fs.write(path, data)
+fs.delete(path)
+fs.rename(from, to)
+fs.stat(path) -> metadata
+fs.list(dir) -> entries
+fs.watch(path, callback)
+```
+
+---
+
+## 4. Memory
+
+结构化存储。类比: `mmap / shmem`,但面向 KV + 索引。
+
+**管**:持久数据、查询 | **不管**:文件(FS)
+
+```
+memory.read(key) -> value
+memory.write(key, value)
+memory.delete(key)
+memory.list(prefix?) -> keys
+memory.search(query) -> results
+```
+
+---
+
+## 5. Network
+
+远程通信。类比: `socket / connect / bind / listen / send / recv`。
+
+**管**:对外连接、监听 | **不管**:本地 IPC(内核 gRPC 总线)
+
+```
+net.request(url, method, body?) -> response
+net.connect(addr, protocol) -> conn
+net.listen(port, protocol) -> listener
+net.send(conn, data)
+net.recv(conn) -> data
+net.close(conn)
+net.available() -> bool
+```
+
+---
+
+## 6. Process
+
+子进程管理。类比: `fork / execve / waitpid / kill / pipe`。
+
+**管**:子进程生命周期、stdio | **不管**:插件间路由(内核调度)
+
+```
+proc.spawn(cmd, args, env?) -> pid
+proc.kill(pid)
+proc.wait(pid) -> exitcode
+proc.stdin(pid, data)
+proc.stdout(pid) -> data
+proc.signal(pid, sig)
+proc.list() -> [pid]
+```
+
+---
+
+## 7. Timer
+
+定时调度。类比: `timer_create / timerfd_create`。
+
+**管**:时间触发 | **不管**:用户事件(Input)
+
+```
+timer.once(delay, callback) -> id  # 到期后通过 PluginBridge.StreamCall 投递事件
+timer.cron(expr, callback) -> id
+timer.cancel(id)
+timer.now() -> timestamp
+```
+
+---
+
+## 8. HID
+
+屏幕截取与输入模拟。类比: `/dev/input` + `/dev/fb` + uinput。
+
+能力可缺失。
+
+**管**:屏幕读取、输入模拟 | **不管**:向用户展示(Display)、用户主动输入(Input)
+
+```
+hid.capture(region?) -> image
+hid.mouse(x, y, action)
+hid.keyboard(key, action)
+hid.ocr(region?) -> text
+```
+
+---
+
+## 9. Input
+
+用户主动输入。类比: `read(stdin)` / evdev。
+
+**管**:用户给的东西 | **不管**:文件读(FS)、录音(Audio)、屏幕读(HID)
+
+```
+input.text() -> string
+input.key() -> keyevent
+input.clipboard() -> data
+input.event() -> event
+```
+
+---
+
+## 设计原则
+
+1. **接口稳定,实现可换** — syscall 签名不变,系统插件可替换(= 换驱动不改应用)
+2. **每个独立** — 可单独实现、测试、编译(= 内核模块独立)
+3. **能力可缺失** — 无声卡则 Audio 不可用,不崩(= Linux 无设备则驱动不加载)
+4. **权限在此层** — 白名单外的 syscall 拒绝(= seccomp)
+5. **离线 = Network 不可用** — 其余八个正常(= 拔网线不影响本地)
+6. **内核不做业务** — TTS/浏览器/Agent 全是插件(= 内核不含 Web 服务器)