wanctl Docs

Architecture reference card

This page has not been translated yet. It is shown in Chinese.

这张卡片用于快速复习和设计评审，可以直接打印。需要推导时，打开对应课程；不要把卡片当作完整的使用手册。

1. 职责

模型决定做什么；宿主组织工具并处理自身审批；控制端定位与发送；Relay 帮助到达；设备端检查并执行；工作区组织连续的远端工作。

追问：读文件、改文件和跑测试，是否真的到达同一个工作地点？ 复习第一篇

2. 边界

wanctl 只能控制经过自己的调用。原生工具统一切换后端需要宿主适配。共享 HTTP 服务不能用一个账号级的默认工作区承载多个聊天。

追问：当前承诺覆盖的是 wanctl 工具，还是宿主所有工具？ 复习第二篇

3. 状态

状态 持有者 需要保留到什么时候
访问授权 授权系统与调用方 到期、撤销或注销前
工作区引用 对话／终端的调用方 本次工作结束前
shell 与命令账本 设备端 显式退出或设备端失效前
已写入项目文件 设备文件系统 按项目文件生命周期管理

追问：断掉的是连接，还是拥有状态的进程？ 复习第三篇

4. 结果契约

字段或标识 用途
workspace 定位本次工作
sha256 / expected_sha256 核对文件版本
request_id 找回同一次命令
state 判断工作区生命周期
done / code 判断命令是否完成及最终退出状态
next_offset / retained_bytes 判断命令输出是否收齐

文件读取的偏移单位是行，命令轮询的偏移单位是字节。生命周期回复没有命令时，done=false 不代表操作失败。

追问：下一步究竟依赖上一份结果中的哪个字段？ 复习第四篇

5. 故障与授权

命令结果不明先查原编号；写入结果不明先读文件核对；摘要冲突先重新读取；身份不符或权限拒绝先解决对应的授权问题。停止等待、取消命令、退出工作区分别处理。

追问：这个恢复动作依据什么事实，会不会重复副作用或换了工作地点？ 复习第五篇

6. 证据与接入

接口校验、真实设备任务、真实模型使用分别验证。编译不等于真机通过，工具可见不等于能执行。选择 CLI 环境绑定、专属 stdio 或显式 HTTP 引用，应以宿主实际的进程和对话生命周期为依据。

追问：哪些能力已经有证据，哪些只是目标？ 复习第六篇 · 复习第七篇

课程目录 · 术语速查