Initial release v0.1.0

docs/core-package.md

@@ -0,0 +1,96 @@
+# TZ Core Package v1
+
+本规范定义 TZ 如何发现、校验和调用本地代理内核。core 包包含运行契约、二进制和该 core 固定的只读运行资源，不包含 profile、用户配置、secret、日志、PID 或缓存。
+
+## 目录结构
+
+稳定槽位名推荐使用 `mihomo`、`sing-box`：
+
+```text
+<data_dir>/cores/
+└── mihomo/
+    ├── core.toml
+    ├── mihomo
+    ├── Country.mmdb # Mihomo GEOIP 规则数据库
+    ├── GeoSite.dat  # Mihomo GEOSITE 规则数据库
+    ├── LICENSE      # 可选
+    ├── NOTICE       # 可选
+    └── README.md    # 可选，TZ 不解析
+```
+
+目录名必须与 `core.name` 完全一致。完整版本保存在 `core.version`；需要多版本并存时使用完整槽位名，例如 `mihomo-1.19.14`。
+
+Mihomo 标准包固定携带 `Country.mmdb` 和 `GeoSite.dat`。生成配置实际引用 GEOIP/GEOSITE 时，TZ 才把缺失资源复制到 `state/runtime/<core>/`；用户无需逐个 profile 手工下载。自制 Mihomo core 包也应携带这两个文件，否则 TZ 会在 build/check 阶段给出明确提示。
+
+## Manifest
+
+```toml
+schema_version = 1
+
+[core]
+name = "mihomo"
+family = "clash"
+version = "1.19.18"
+binary = "mihomo"
+os = "linux"
+arch = "x86_64"
+
+[runtime]
+entrypoint = "config.yaml"
+format = "yaml"
+
+[capabilities.config]
+mixed_proxy = true
+http_proxy = true
+socks_proxy = true
+api = true
+dns = true
+tun = true
+
+[commands.start]
+args = ["-d", "{workdir}", "-f", "{config}"]
+
+[commands.check]
+args = ["-t", "-d", "{workdir}", "-f", "{config}"]
+
+[commands.version]
+args = ["-v"]
+```
+
+字段约束：
+
+- schema 当前仅支持 `1`，未知字段会被拒绝。
+- name 只允许 ASCII 字母、数字、点、下划线和连字符。
+- family/format 当前只允许 `clash/yaml` 和 `sing-box/json`。
+- os/arch 必须等于当前运行平台的 Rust target 常量。
+- binary 与 entrypoint 必须是单个相对文件名，禁止绝对路径和 `..`。
+- binary 必须是普通可执行文件。
+- start 必填；check、version、reload 可选。命令存在即表示支持对应动作。
+- 参数只支持 `{config}` 和 `{workdir}`；TZ 直接执行 binary，不经过 shell。
+
+## 安装方式
+
+手工复制是标准方式，无注册数据库：
+
+```bash
+cp -a ./mihomo <data_dir>/cores/mihomo
+chmod +x <data_dir>/cores/mihomo/mihomo
+tz core list
+```
+
+本地便捷导入：
+
+```bash
+tz core add ./mihomo
+tz core info mihomo
+tz core use mihomo
+tz core remove mihomo
+```
+
+`core add` 只接收本地目录，不接收 URL。它会拒绝符号链接和特殊文件，复制到 staging，重新校验后原子移动；重名直接拒绝。成功后不自动选择或启动。
+
+`core remove` 在受管进程运行时拒绝。服务停止时可以删除当前 core，并原子清空 current，同时清理同名 generated/runtime 派生目录。
+
+## 网络分发
+
+网络下载不属于 `core add`。未来 `core install` 必须使用可信 registry 提供的外部 SHA256，且 URL 只能是 HTTP/HTTPS；请求和每次重定向前必须拒绝 localhost、环回、私有和保留地址。