Skip to content

Developer Guide

Jump to bottom
sun_y edited this page Jun 13, 2026 · 2 revisions

Developer Guide & Release SOP (开发者手册与静默发布规范)

Important

🤖 AI 助理协同开发与发布宪法 (AI Agent Execution Constitution)

本指南中所列的本地开发安全规范与一键静默发行（SOP）双轨流程，是专为参与 Clash Mini 项目开发协作的 AI Agent（AI 助理） 设立的核心行为红线与操作约束。

  • AI Agent 在动用任何工具排查、修改项目或执行推送前，必须无条件遵循本规范。
  • 任何绕过本 SOP 流程的“后台默默顺手修复”或“强制云端发布”行为，都将被直接判定为严重系统故障并终止操作。

🛠️ AI Agent 本地调试与开发安全红线 (Law of Environment Safety)

AI Agent 在本地修改代码并启动开发服务时，必须严格遵守**「环境安全基本法」**，锁死以下环境边界以防越界：

  1. 网络接管锁定为 false：启动本地 pnpm dev 调试服务前，必须确保前端和 Rust 配置文件中的网络接管模式（TUN 模式、系统代理）默认均为 false，避免干扰宿主机真实网络。
  2. 禁止运行生产内核：AI Agent 严禁直接启动或常驻运行任何本地生产构建出的 clash-mini.exe。
  3. 禁止劫持物理机：AI Agent 严禁在本地开发调试过程中运行任何修改物理宿主机路由表或劫持全局系统代理的命令。

常用调试指令

  • 启动前端与 Tauri 混合开发服务： 
    pnpm dev
  • 启动纯前端 WebView Vite 服务（快速热更排布样式）： 
    pnpm web:dev

🚀 AI Agent 一键静默发行双轨系统 (One-Click Silent Release SOP)

为了实现 “单次授权、后续全局静默” 的发布实践，AI Agent 涉及编译与 GitHub 发行操作时，必须严格遵循以下决策路径和 8 步闭环静默发布流程，严禁产生任何非预期的用户打扰：

🚦 决策树：选择发行路径

  • 默认路径（云端极速发布）：用户未明确要求“本地测试”或直接下达“直接发布/静默发布”指令时，直接走模块二（云端发布）。
  • 分支路径（本地验证后发布）：用户明确提出“本地测试/真机确认效果”时，先清理环境锁并在本地进行 pnpm dev 校验，得到用户口头允许后，再终止本地服务并进入模块二。

📋 模块二：云端静默发布 SOP 8 步流程

第一步：文档先行（修改顺序铁律）

在改动任何业务代码前，必须首先在 clash_mini_agreements.md 的对应章节中将相关设计或行为变更写入协议。在 bug_list.md 中登记 Bug，其状态为 代码已修正，待确认。

第二步：先独立提交文档

使用 Git 仅添加文档修改并执行提交，与业务代码隔离：

git add clash_mini_agreements.md bug_list.md
git commit -m "docs: register changes" --no-verify

第三步：静态类型安全校验 (唯一的防线)

在本地运行前端编译命令，确保无任何 Typescript 报错或 Vite 编译警告。如果有任何警告/报错，必须立即终止发布：

pnpm web:build

第四步：提交业务代码

确认无误后，添加并提交所有业务代码：

git add .
git commit -m "feat: implement logic" --no-verify

第五步：Git 临时代理配置与清理旧 Tag

为防止推送时网络超时，配置 Git 临时代理：

git config --local http.proxy http://127.0.0.1:7890
git config --local http.sslBackend openssl

如果是重新发布当前版本，需先清除本地与远程同名 Tag：

git tag -d v<版本号>
git push origin :refs/tags/v<version>

第六步：升级版本号并推送 Tag

运行发布脚本，触发 GitHub Actions 构建（注：所有发行版本必须锁定并使用 v1.19.26 旧版内核进行打包，严禁拉取 latest 内核）：

pnpm publish-version <版本号>
  • 构建时间参考：普通 Windows x64 便携版发布约 25-30 分钟；包含全平台的完整版（带 -full 尾缀）约 30-40 分钟。

第七步：静默监控 Actions 并拉回构建包

  • 打印 GitHub Actions 构建工作流链接（形如 https://github.com/qiu-yuxiao/clash-mini/actions）引导用户。
  • 利用根目录下的 github_token.txt 中的 Token 作为 API 授权凭证，在后台静默调用 GitHub API 查询构建状态。
  • 构建成功后，通过 GitHub CLI 将生成的 Windows x64 便携包（*_x64_portable.zip）拉回到项目根目录的 portable_test 文件夹下以供本地真机解包点对点测试： 
    $token = (Get-Content 'github_token.txt' -Raw).Trim()
$env:GH_TOKEN = $token
gh release download v<版本号> --pattern '*_x64_portable.zip' --dir 'portable_test' --clobber --repo qiu-yuxiao/clash-mini

第八步：环境复原与重置

  • 清除 Git 的临时本地代理配置，保持开发环境整洁： 
    git config --local --unset http.proxy
git config --local --unset http.sslBackend
  • 清空 Vite 开发缓存（node_modules/.vite）。
  • 在 .brain/walkthrough.md 中归档真机物理验证结果，并在 .brain/task.md 中重置任务看板，完成当前发行周期的完整生命周期闭环。

Clone this wiki locally