Initial release v0.1.0

docs/control-interface.md

@@ -0,0 +1,102 @@
+# TZ Control Interface v0.1
+
+TZ 的公开命令围绕用户动作设计。配置文件是可查阅的内部存储格式，修改由固定命令完成并经过校验、锁保护和原子保存。
+
+## 当前指令
+
+```text
+tz init
+tz status
+tz start
+tz stop
+tz restart
+tz list [keyword]
+tz node test [keyword] [--url <url>] [--timeout <ms>] [--select]
+
+tz tun status|on|off
+tz proxy status|on|off
+tz proxy terminal status|on|off
+tz proxy system status|on|off
+tz proxy env|noenv [bash|zsh|fish]
+tz proxy shell-init bash|zsh|fish
+
+tz setting [list]
+tz setting get <key>
+tz setting set <key> [value]
+tz setting reset [key]
+
+tz profile add <name> <url-or-file> --family clash|sing-box
+tz profile list [--family clash|sing-box] [--all]
+tz profile info <name>
+tz profile use [name]
+tz profile update
+tz profile remove <name>
+
+tz core add <directory>
+tz core list
+tz core info [name]
+tz core use [name]
+tz core remove <name>
+
+tz config build|check|show
+tz completion generate bash|zsh|fish
+```
+
+`profile list` 默认只显示当前 core family，`--all` 显示全部。`profile update` 不接名称，更新所有远程 profile；本地 profile 自动跳过。
+
+`profile list`、`core list` 和节点 `list` 在 TTY 中显示编号、用 `*` 标出当前项并允许直接选择；非交互环境只输出简洁列表。`profile/core use` 保留，作为脚本和明确指定名称的稳定入口。详细来源和路径使用 `info` 查看。
+
+`list/-l` 与 `node test` 都通过当前 core controller API 最多并发测试 8 个节点并按延迟排序。`list/-l` 在 TTY 中允许从测速后的列表选择节点；`node test --select` 自动选择最快的成功节点。默认 URL 为 Google 204，默认超时 1800ms；最新结果保存在 `cache/speedtest/latest.json`。
+
+Mihomo 的 family 固定为 `clash`，sing-box 的 family 固定为 `sing-box`，不能互换。
+
+## 简洁指令
+
+```text
+tz                 # status，并测速当前节点
+tz on              # 使用上次的可用 profile 启动并显示 status
+tz off | tz end    # stop
+tz -l [keyword]    # 测速、按延迟排序、搜索和选择
+tz select          # profile list
+```
+
+节点 keyword 使用不区分大小写的子串匹配。`list/-l` 在 TTY 中可输入测速后列表的编号切换当前节点；选择写入当前 profile，并在下次启动后恢复。
+
+## 快捷键
+
+快捷键是当前指令的命令缩写，完整写法始终可用：
+
+```text
+tz st              # status
+tz r               # restart
+tz set              # setting
+tz p                # profile
+tz c                # core
+tz cfg              # config
+tz comp              # completion
+
+tz p a|l|i|u|up|rm
+tz c a|l|i|u|rm
+```
+
+Tab 补全通过 `tz completion generate <shell>` 生成。例如 Bash 当前会话可执行 `eval "$(tz completion generate bash)"`。
+
+## Proxy 与 TUN
+
+`proxy terminal on|off` 保存终端代理状态。子进程不能直接修改父 shell，因此当前 shell 使用 `eval "$(tz proxy env)"` 或 `eval "$(tz proxy noenv)"`；长期使用把 `eval "$(tz proxy shell-init bash)"` 加入对应 shell 启动文件。Fish 和 Zsh 使用各自的 shell 参数。
+
+`proxy system on|off` 使用 GNOME `gsettings` 设置 HTTP、HTTPS、SOCKS 和 ignore-hosts，端口与 bypass 均来自 TZ 配置。开启前要求 core 正在运行，避免桌面流量指向空端口。TZ 会先私有备份原桌面代理，关闭或应用失败时逐项恢复；未由 TZ 开启时，`system off` 不修改桌面设置。`proxy on|off` 同时控制 terminal 和 system。
+
+`tun on|off` 检查当前 core 的 TUN capability 和 `/dev/net/tun`。开启还要求受管 core 二进制具有 `CAP_NET_ADMIN`；缺少时打印对应的 `sudo setcap cap_net_admin,cap_net_raw+ep ...` 命令。运行中的切换会安全重启，失败时恢复原状态。
+
+## Profile 下载
+
+URL 只允许 HTTP/HTTPS，并校验 DNS 与重定向目标。下载按 family 使用对应 provider User-Agent：Clash 对齐 `mh`，sing-box 对齐 `sb`，以支持服务端按客户端返回不同格式。下载优先尝试环境代理，失败后回退直连，只要一种路径成功即完成添加或更新。实际成功路径保存为 profile 的 `download_via=proxy|direct`，可用 `tz profile info <name>` 查看；错误信息不会打印订阅 token。
+
+## 运行闭环
+
+`config build/check` 根据当前 core family 生成 Clash YAML 或 sing-box JSON，并调用 core manifest 的 check 命令。Mihomo profile 引用 GEOIP/GEOSITE 时，builder 从 core 包按需复制 `Country.mmdb` 和 `GeoSite.dat` 到独立工作目录；标准 core 包已携带这两份规则数据库，用户无需手工处理。自定义 core 包缺失时会明确提示，可先启用其他代理取得资源后补入 core 包。
+
+`start/on` 读取当前 family 上次选择且 source 可用的 profile，在校验通过后启动受管进程、等待 API 并显示 status；没有可用 profile 时提示运行 `tz profile list`。`stop` 在发送信号前核对进程用户和 `/proc/<pid>/exe`；`status/tz` 简洁显示 core、profile、服务 PID，并实时测试当前节点延迟，失败时才回退显示缓存结果。
+
+当前尚未开放的是 core 在线下载与自动更新。System proxy 的 v0.1 平台适配范围是 GNOME；其他 Linux 桌面环境后续增加 adapter。