102 lines
5.2 KiB
Markdown
102 lines
5.2 KiB
Markdown
# 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。
|