TIIEHenry · Mar 4, 2026 · Mar 6, 2026 · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@ build/
 /app/foss/release
 /app/premium/release
 /captures
+/.kotlin/
 
 # Ignore Gradle GUI config
 gradle-app.setting
@@ -62,5 +63,9 @@ google-services.json
 # logs
 *.log
 
+# Python bytecode
+__pycache__/
+*.pyc
+
 # MacOS
 .DS_Store
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,56 @@
+# AGENTS.md — 开发向导
+
+> 本文件是 ClashMetaForAndroid 的开发向导。`CLAUDE.md` 只指向这里。
+
+ClashMetaX 是 [mihomo](https://github.com/MetaCubeX/mihomo) 的 Android 图形界面。本仓库是 TIIEHenry fork，在上游应用上保留应用分流策略、访问控制应用集合和 WebDAV 同步。
+
+> **新会话必读顺序：**
+> 1. 本文件
+> 2. [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) — 文档维护规则
+> 3. [dev/progress/status.md](dev/progress/status.md) — 当前快照
+
+编码前再看相关的 [docs/systems/](docs/systems/) 或 [docs/modules/](docs/modules/)。构建、签名和内核子模块的约束见 [构建指南](docs/guides/getting-started/build.md)。
+
+## 文档导航
+
+| 文档 | 说明 |
+|:-----|:-----|
+| [文档索引](docs/INDEX.md) | 全局入口 |
+| [产品需求](docs/product/INDEX.md) | 用户可观察的承诺 |
+| [高层设计](DESIGN.md) | 进程与模块边界 |
+| [架构概览](docs/architecture/overview.md) | 模块依赖 |
+| [文档规范](docs/DOCS-SPEC.md) | 目录与归属 |
+| [维护规则](docs/DOCUMENTATION.md) | frontmatter、提交前文档门禁 |
+| [术语表](docs/glossary.md) | 本仓库用词 |
+
+## 模块
+
+Gradle 模块由 `settings.gradle.kts` 决定：`app`、`core`、`service`、`design`、`common`、`hideapi`。导航在 [docs/modules/](docs/modules/)。
+
+依赖方向：`app` 使用 `core`、`service`、`design`、`common`，并 `compileOnly` `hideapi`。`service` 与 `design` 使用 `core` 和 `common`。`common` `compileOnly` `hideapi`。
+
+## 构建
+
+```bash
+git submodule update --init --recursive
+./gradlew :app:assembleMetaRelease
+```
+
+默认 flavor 是 `alpha`。已安装到手机上的包使用 `meta` flavor，包名 `com.github.metacubex.clash.meta`。JDK 目标是 21。没有 `signing.properties` 时 release 使用 debug 签名。细节与内核 pin 见 [构建指南](docs/guides/getting-started/build.md)。
+
+## 开发流程
+
+1. 行为或契约变更先写进 `dev/plans/` 或对应 `docs/systems/`，需要取舍时写 ADR。
+2. 编码。
+3. 提交前按 [规则 3a](docs/DOCUMENTATION.md#规则-3a提交前文档门禁) 更新行动层；用户可见行为再更新知识层。
+4. 只 `git add` 本次主题的文件。工作区里其他未提交改动留在原地。
+
+单行且无行为变化的修改可以只提交代码。
+
+## 约束
+
+- 过时文档移入 `dev/archive/`，不删除。
+- `status.md` 保持 200 行以内的当前快照。溢出后注用 `bash scripts/archive-status-overflow.sh` 滚入归档。
+- 结构变更后运行 `python3 scripts/check-docs-health.py`。
+- 不要把设备序列号、签名指纹、密钥口令写进仓库文档。WebDAV 默认常量以 `service` 模块源码为准，文档只链接，不另抄一套。
+- 根 `README.md` 保持上游英文介绍。Fork 的架构与构建说明写在 `docs/`。
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+本文件是指针。开发向导以 [AGENTS.md](AGENTS.md) 为准。
+
+文档维护规则见 [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)。当前快照见 [dev/progress/status.md](dev/progress/status.md)。
diff --git a/DESIGN.md b/DESIGN.md
@@ -0,0 +1,41 @@
+---
+title: "ClashMetaX 高层设计"
+type: architecture
+status: accepted
+phase: N/A
+updated: 2026-10-15
+summary: "UI 进程与 :background 进程的边界，以及六个 Gradle 模块的职责"
+---
+
+# 高层设计
+
+本应用把 mihomo 跑在 Android VPN 服务里，并用一套配置界面管理配置文件、代理选择和按应用分流。
+
+## 进程
+
+界面跑在默认进程。`ClashService`、`TunService`、`RemoteService`、配置处理与状态 Provider 声明在 `:background`。界面通过 `service` 模块的远程接口读写配置和隧道状态，不在 UI 进程里加载 `libclash.so` 的业务循环。
+
+`TunService` 持有 `android.net.VpnService`。流量是否进入隧道，由当前配置、访问控制名单，以及可选的应用分流策略决定。
+
+## 模块
+
+| 模块 | 职责 |
+|:-----|:-----|
+| app | Activity、外部控制入口、日志界面 |
+| design | 界面布局、列表与设置控件 |
+| service | `:background` 服务、配置库、WebDAV、访问控制与分流策略的存储 |
+| core | JNI 与 Go 桥，链到 mihomo，产出 `libclash.so` |
+| common | 跨模块常量、Store、兼容工具 |
+| hideapi | 隐藏 API 的编译期存根 |
+
+模块依赖与阅读入口见 [架构概览](docs/architecture/overview.md)。
+
+## 内核
+
+mihomo 以 Git 子模块放在 `core/src/foss/golang/clash`。`core/src/main/golang` 用 `replace` 指向它，再由 golang-android 插件编进 native 库。子模块的检出约束见 [构建指南](docs/guides/getting-started/build.md)。
+
+## Fork 行为
+
+相对上游界面，本 fork 增加三类用户可见行为：命名的应用分流策略、访问控制里的系统/国内应用集合、配置与策略的 WebDAV 同步。契约分别见 [访问控制](docs/systems/access-control/INDEX.md) 与 [WebDAV](docs/systems/webdav/INDEX.md)。
+
+产品承诺见 [docs/product/](docs/product/INDEX.md)。这里不写验收步骤。
diff --git a/NOTICE b/NOTICE
@@ -1,5 +1,14 @@
 3th-party software licenses
 
+ * AgenticUILibrary
+==========================================================================
+design/src/main/java/nota/ui and design/src/main/java/universe/agentic/ui/search
+contain source copied from AgenticUILibrary under the Apache License 2.0.
+Adapted for this AndroidX Compose module: Material 3 theme calls were
+removed, dark mode follows UiStore through LocalShellIosDark, and the
+switch thumb is a round rect because the iOS spec is a circle.
+The upstream tree did not ship a NOTICE file.
+
  * Clash
 ==========================================================================
                     GNU GENERAL PUBLIC LICENSE

diff --git a/README.md b/README.md
@@ -2,6 +2,10 @@
 
 A Graphical user interface of [Clash.Meta](https://github.com/MetaCubeX/Clash.Meta) for Android
 
+### Documentation
+
+Architecture, build constraints, and product behavior for this fork are in the documentation system. Start at [docs/INDEX.md](docs/INDEX.md). The agent guide is [AGENTS.md](AGENTS.md).
+
 ### Feature
 
 Feature of [Clash.Meta](https://github.com/MetaCubeX/Clash.Meta)

diff --git a/app/README.md b/app/README.md
@@ -0,0 +1,16 @@
+---
+title: "app 模块"
+type: overview
+status: accepted
+phase: N/A
+updated: 2026-10-15
+summary: "Android 应用模块：Activity、外部控制和日志"
+---
+
+# app
+
+应用进程里的界面入口。屏幕布局在 `design`，隧道和配置存储在 `service`。
+
+导航：[docs/modules/app/INDEX.md](../docs/modules/app/INDEX.md)
+
+模块设计：[app/docs/INDEX.md](docs/INDEX.md)
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
@@ -46,8 +46,11 @@ task("downloadGeoFiles") {
 
     doLast {
         geoFilesUrls.forEach { (downloadUrl, outputFileName) ->
-            val url = URL(downloadUrl)
             val outputPath = file("$geoFilesDownloadDir/$outputFileName")
+            if (outputPath.exists()) {
+                return@forEach
+            }
+            val url = URL(downloadUrl)
             outputPath.parentFile.mkdirs()
             url.openStream().use { input ->
                 Files.copy(input, outputPath.toPath(), StandardCopyOption.REPLACE_EXISTING)

diff --git a/app/docs/INDEX.md b/app/docs/INDEX.md
@@ -0,0 +1,31 @@
+---
+title: "app 模块设计"
+type: index
+status: accepted
+phase: N/A
+updated: 2026-10-15
+summary: "应用进程的 Activity、对 :background 的调用，以及日志捕获"
+---
+
+# app 模块设计
+
+`app` 是默认进程里的界面入口。屏幕在 `design`，隧道、配置库和 WebDAV 实现在 `service` 的 `:background` 进程。本目录只写这个模块自己怎么把两边接起来。
+
+| 文档 | 写什么 |
+|:-----|:-------|
+| [Activity](activities.md) | `BaseActivity` 如何把界面交给 `design`，各 Activity 的职责，外部控制与主界面的差别 |
+| [远程调用](remote.md) | 应用进程怎样绑定 `:background`，以及状态、文件、偏好和启停各走哪条路 |
+| [日志捕获](logcat.md) | `LogcatService` 到 `LogcatReader` 的实际链路，以及崩溃页用的系统 logcat |
+
+模块导航在 [docs/modules/app/INDEX.md](../../docs/modules/app/INDEX.md)。
+
+跨模块行为以这些文档为准，这里不重写：
+
+| 主题 | 文档 |
+|:-----|:-----|
+| 界面分层 | [界面](../../docs/systems/ui/INDEX.md) |
+| 隧道与外部控制动作 | [运行时](../../docs/systems/runtime/INDEX.md) |
+| 配置 | [配置](../../docs/systems/profiles/INDEX.md) |
+| 访问控制与分流策略 | [访问控制](../../docs/systems/access-control/INDEX.md) |
+| WebDAV | [WebDAV](../../docs/systems/webdav/INDEX.md) |
+| 用户可观察的承诺 | [产品需求](../../docs/product/requirements/INDEX.md) |