Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
8127c1e
fix: keep service editor save action inside safe window bounds
CN059 Sep 17, 2026
76b3b24
docs: 规范 commit 和 PR 标题格式
CN059 Sep 17, 2026
6163bd1
ci: 按改动范围跳过文档 PR 的 Android 构建
CN059 Sep 17, 2026
d7c469f
Merge pull request #6 from powercess/agent/fix-service-editor-save
CN059 Sep 17, 2026
a52c44e
Merge branch 'dev' into agent/title-conventions
CN059 Sep 17, 2026
55678a3
Merge branch 'dev' into agent/ci-skip-doc-build
CN059 Sep 17, 2026
6a3f015
Merge pull request #7 from powercess/agent/title-conventions
CN059 Sep 17, 2026
35b4746
docs: 合并 dev 并保留验证范围与标题规范
CN059 Sep 17, 2026
381741c
Merge pull request #8 from powercess/agent/ci-skip-doc-build
CN059 Sep 17, 2026
76c54c3
feat(remote): add embedded frpc multi-tunnel access
CN059 Sep 17, 2026
d03507a
feat(remote): 支持独立 frpc 多隧道与 TLS 证书管理
CN059 Sep 18, 2026
5541761
fix: 精简首页能力概览与网关控制
CN059 Sep 20, 2026
5df3771
Merge pull request #11 from powercess/agent/simplify-home-ui
CN059 Sep 20, 2026
7dd7d8d
fix: 精简能力页并按插件布局展示基础能力
CN059 Sep 20, 2026
891a279
Merge branch 'dev' into agent/frpc-multi-tunnel
CN059 Sep 22, 2026
e71e0a9
Merge pull request #9 from powercess/agent/frpc-multi-tunnel
CN059 Sep 22, 2026
daa205f
fix: resolve PR #10 conflicts with dev
CN059 Sep 22, 2026
b2d79fd
Merge branch 'dev' into agent/capabilities-plugins
CN059 Sep 22, 2026
8871733
Merge pull request #12 from powercess/agent/capabilities-plugins
CN059 Sep 22, 2026
b0f6eef
fix: resolve PR #10 conflicts with latest dev
CN059 Sep 22, 2026
a0f7e6e
Merge pull request #10 from powercess/agent/frpc-tunnels
CN059 Sep 23, 2026
8a5c2b8
fix(ui): 统一页面样式与公共组件规范
CN059 Sep 23, 2026
4ca1543
Merge pull request #13 from powercess/agent/ui-style-consistency
CN059 Sep 23, 2026
204e915
feat(remote): simplify TCP tunnels and prepare 0.2.0
CN059 Sep 23, 2026
c5724c9
Merge pull request #14 from powercess/agent/tunnel-servers
CN059 Sep 23, 2026
203e185
chore: sync main release history into dev
CN059 Sep 23, 2026
2fed85d
fix(test): wait for frpc cleanup before deleting temporary files
CN059 Sep 23, 2026
2b8ff73
fix(test): stabilize frpc cleanup and sync release history
CN059 Sep 23, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .agents/skills/mbrain-style/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
name: mbrain-style
description: 在 MBrain Android 项目新增、修改或审查 Compose 页面、操作行、图标、间距、主题和界面文案时使用,约束公共组件复用并防止样式漂移。不用于其他项目或纯后端修改。
---

# MBrain UI 样式约束

## 先确定依据

- 以本 skill 所在仓库为作用域;从 `.agents/skills/mbrain-style/` 向上三级定位仓库根目录,不使用个人电脑绝对路径。
- 修改前读取根目录 [DESIGN.md](../../../DESIGN.md),以及 `app/src/main/kotlin/com/powercess/mbrain/ui/DesignSystem.kt` 和目标页面。
- DESIGN.md 是视觉参数的唯一规范来源;DesignSystem.kt 是公共实现。二者不一致时指出具体差异,结合用户最新要求修正本次涉及的部分,不把偶然出现的页面样式当成新规范。
- 用户明确提出的新设计优先于现有约定;无需为普通样式修复再次索要批准。将已采用的公共规范变化同步到 DESIGN.md。

## 同类操作行只用同一实现

设置项、能力与插件入口、服务列表入口、工具入口,以及带状态或开关的设置行,默认复用 `Group`、`ActionRow`、`GroupDivider`。

- 组内使用 GroupDivider;禁止通过 Spacer、Arrangement.spacedBy 或额外 padding 自行模拟组内间隙。
- 首尾外圆角由 Group 裁切,中间小圆角由 ActionRow 提供;只有一个条目时仍包在 Group 中。不要给每一行另加大圆角卡片。
- 页面只提供内容、行为和语义明确的 trailing(状态、开关、进度);不为单页覆盖圆角、行高、图标尺寸、背景和文字层级。
- 导航行使用默认箭头,状态行使用 StatusPill,开关行复用现有 Switch 模式。不要把整行点击与子开关变成重复触发的操作。
- 行首图标使用现有单色线性图标风格,不使用彩色底框、emoji 或新绘制的装饰图标代替常规行图标。
- 公共组件不足时,先在 DesignSystem.kt 增加最小必要的语义能力,再让同类入口复用;不要复制出页面私有版本,不为假设中的用途增加任意样式参数。
- 静态分组显式放置 GroupDivider;动态列表使用 ScreenList(groupedRows = true)、ListSection 和 groupedItems,传入稳定 key,自动处理首尾圆角和行距。不要逐项再套 Group,也不要把长工具列表放入单个非懒加载 Column。

示例:

```kotlin
Group {
ActionRow("应用管理", "已启用", Icons.Outlined.Widgets, { open("cap:apps") })
GroupDivider()
ActionRow("设备信息", "已启用", Icons.Outlined.PhoneAndroid, { open("cap:device") })
}
```

## 页面、主题与文案

- 列表页面复用 ScreenList,分组标题复用 SectionLabel;四个主页面首组使用 `firstSection = true`,不要用负偏移或逐页补偿顶部留白。
- 颜色读取 MaterialTheme.colorScheme,字体使用 MaterialTheme.typography;不要在业务页硬编码主题色。不要靠固定高度裁剪大字体内容。
- 编辑页复用 EditorSaveBar,标题栏与页面背景一致;全宽次级操作复用 SecondaryAction;完整详情说明使用 ContentCard,提示和错误使用 Note。完整调用名称使用可选择的等宽文本,不截断;复制操作不显示导航箭头。
- 空状态统一使用无图标的 EmptyState,只提供必要信息和有效操作:MCP 无配置时用“暂无服务”与“添加服务”;工具页网关未启动时只提示“启动网关后查看工具”,不显示无效搜索框或装饰图标。
- 汇总入口称“全部工具”,数量写“共 N 个工具”;分来源列表不称“全部”。避免重复标题、营销式欢迎语和不影响操作的技术说明;保留凭据重置、删除等必要后果提示。
- 保留原生水波纹、焦点、禁用状态和可访问性语义;可操作区域不小于规范要求。

## 合理保留不同控件

首页统计卡片、网关启停、保存/添加/删除按钮、输入框、对话框和底部导航各有用途,不强行改成分组操作行。沿用其现有公共组件或 Material 控件。单次任务只迁移授权范围内的同类入口;全项目统一需逐一审查,不能机械替换所有 Surface 或 Button。

## 完成前检查

- 检查 diff 是否新增了业务页私有操作行、重复尺寸常量、硬编码颜色或多余嵌套 padding;如有,优先收敛到现有公共实现。
- 每完成一轮应用功能或 UI 修改,按用户要求 rebuild;使用已连接的测试设备覆盖安装并验证,不卸载或清除数据。构建命令与环境见 `docs/development.md`;通过 adb devices 读取当前连接,不把设备地址写入源码或 skill。
- 普通文案修改做构建与相关页面检查。公共布局、主题或组件修改另做相关 lint,检查受影响页面的浅色/深色、大字体、单项/多项分组和点击行为;四页共享布局修改需逐页核对。只报告实际完成的验证,说明环境限制。
- 截图和构建日志放在忽略的 `.local-tools/`;截图前隐藏 Token 等凭据。覆盖安装可能停止网关,检查并说明实际状态。
- 仅修改 skill/设计文档时验证文档、引用及 skill 格式,不为文档重新构建 APK。
- 完成后汇报改动和验证结果;当前项目协作约定是等待用户明确要求再创建 PR。
34 changes: 29 additions & 5 deletions .github/workflows/android.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,27 +32,45 @@ jobs:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false
fetch-depth: 0
- name: Select validation scope
id: scope
env:
PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: python3 scripts/ci_scope.py
- name: Inspect committed source
run: |
python3 -m unittest discover -s scripts -p 'test_*.py'
python3 scripts/check-source.py
- uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5
- if: steps.scope.outputs.android == 'true'
uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5
with:
distribution: temurin
java-version: '17'
- uses: gradle/actions/setup-gradle@4c125117fe7c5aed11272ec4213f602f012f89f2 # v5
- if: steps.scope.outputs.android == 'true'
uses: gradle/actions/setup-gradle@4c125117fe7c5aed11272ec4213f602f012f89f2 # v5
with:
cache-disabled: true
- name: Install Android SDK packages
if: steps.scope.outputs.android == 'true'
uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
with:
packages: platform-tools
log-accepted-android-sdk-licenses: false
- name: Install required SDK versions
run: sdkmanager "platforms;android-35" "build-tools;35.0.0"
if: steps.scope.outputs.android == 'true'
run: sdkmanager "platforms;android-35" "build-tools;35.0.0" "ndk;28.2.13676358"
- if: steps.scope.outputs.android == 'true'
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version: '1.26.3'
cache: false
- name: Build, unit tests and lint
run: ./gradlew :app:assembleDebug :app:assembleRelease testDebugUnitTest :app:lintDebug :app:lintRelease --no-daemon --no-build-cache --max-workers=2 --stacktrace
if: steps.scope.outputs.android == 'true'
run: ./gradlew :app:assembleDebug :app:assembleDebugAndroidTest :app:assembleRelease testDebugUnitTest :app:lintDebug :app:lintRelease --no-daemon --no-build-cache --max-workers=2 --stacktrace
- name: Verify supported ABIs and prepare APK
if: steps.scope.outputs.android == 'true'
run: |
python3 scripts/check-apk.py app/build/outputs/apk/debug/app-debug.apk
python3 scripts/check-apk.py app/build/outputs/apk/release/app-release-unsigned.apk
Expand All @@ -61,6 +79,7 @@ jobs:
cd dist
sha256sum *.apk > SHA256SUMS.txt
- name: Upload universal debug APK
if: steps.scope.outputs.android == 'true'
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: mbrain-debug-universal-${{ github.run_number }}-${{ github.run_attempt }}
Expand All @@ -69,7 +88,7 @@ jobs:
retention-days: 14
compression-level: 0
- name: Upload test and lint reports
if: ${{ !cancelled() }}
if: ${{ !cancelled() && steps.scope.outputs.android == 'true' }}
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: android-reports-${{ github.run_number }}-${{ github.run_attempt }}
Expand All @@ -80,6 +99,7 @@ jobs:
if-no-files-found: ignore
retention-days: 14
- name: Build summary
if: steps.scope.outputs.android == 'true'
run: |
cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
## MBrain testing build
Expand All @@ -91,3 +111,7 @@ jobs:
- Ephemeral CI signing keys may differ between runs; updating an existing installation may fail with a signature mismatch. Uninstalling clears app data.
- ABI packaging checks do not replace testing on each architecture.
EOF

- name: Documentation check summary
if: steps.scope.outputs.android == 'false'
run: echo 'Documentation-only PR; source checks passed. Android build skipped.' >> "$GITHUB_STEP_SUMMARY"
6 changes: 5 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,11 @@ jobs:
packages: platform-tools
log-accepted-android-sdk-licenses: false
- name: Install SDK
run: sdkmanager "platforms;android-35" "build-tools;35.0.0"
run: sdkmanager "platforms;android-35" "build-tools;35.0.0" "ndk;28.2.13676358"
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version: '1.26.3'
cache: false
- name: Build and test release
run: ./gradlew :app:assembleRelease testReleaseUnitTest :app:lintRelease --no-daemon --no-build-cache --max-workers=2 --stacktrace
- name: Verify and stage unsigned release
Expand Down
22 changes: 22 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,25 @@
- Do not bypass branch protections, force-push protected branches, or merge before required checks pass.
- Keep `dev` as the default branch and retain it after merging into `main`.
- Create release tags only on `main` commits and only when a release is explicitly authorized.

# Validation scope

- Choose local checks according to the changed behavior; do not run a full Android build for every PR by default.
- Documentation and repository-instruction changes need lightweight checks only. Workflow changes need workflow validation and tests of any changed CI logic.
- Run relevant builds, tests and lint for application, dependency and build-configuration changes. Repeat checks only after relevant changes or failures.
- CI keeps required checks reporting on every PR, but skips Android setup and builds for documentation-only PRs. Pushes to `dev`/`main`, manual runs and releases retain full validation.

# Commit and pull request titles

- Every commit title and pull request title must use `type: description` or `type(scope): description`.
- The scope is optional. Use a colon followed by a space, and a concise, non-empty description.
- Titles may be written in Chinese or English.
- Examples: `fix: 修复保存按钮遮挡`, `fix(ui): keep the save button visible`, `docs: 更新开发规范`.
- Apply the same format to merge and squash commit titles when creating or editing them.

# UI style skill

- For MBrain UI changes or reviews, read and apply [.agents/skills/mbrain-style/SKILL.md](.agents/skills/mbrain-style/SKILL.md) before editing.
- Keep visual values in DESIGN.md and shared implementations in DesignSystem.kt; do not create per-page variants of grouped action rows.
- After each application/UI change, rebuild and verify on the connected test device. Skill/documentation-only changes require lightweight validation.
- Do not create a pull request until the user explicitly requests it.
33 changes: 32 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,46 @@ Android 原生工具面板,面向管理手机能力与 MCP 服务的用户。
- 首页取消连接示意图和装饰图标;网关启停使用青绿色,工具与服务概览分别使用浅蓝和浅绿表面,深色模式使用对应暗色表面。
- 页面切换使用短淡入淡出;原生组件保留按压、水波纹、禁用与焦点反馈。

## 分组操作行的统一实现

设置项、能力与插件入口、服务及工具入口默认复用 `Group / ActionRow / GroupDivider`。单项使用同样的分组外壳;整组裁切首尾外圆角,内部行保留小圆角。业务页面不单独覆盖这些样式。静态分组显式放置 `GroupDivider`;动态列表使用 `ScreenList(groupedRows = true)`、`ListSection` 和 `groupedItems`,自动处理首尾圆角与 2dp 行间隙,并保留逐行懒加载和稳定 key。不要在动态列表中为每行再套独立 Group。

| 参数 | 统一值 |
| --- | --- |
| 外圆角 / 内圆角 / 组内间隙 | 20dp / 4dp / 2dp |
| 行内水平 / 垂直边距 | 16dp / 12dp |
| 图标与文字间距 / 标题与说明间距 | 16dp / 2dp |
| 行首图标 / 导航箭头 | 24dp / 20dp |
| 单行 / 双行最小高度 | 56dp / 72dp,内容可撑高 |
| 列表顶部 padding | 8dp |
| 四个主页面首组标题顶部 padding | 4dp(`firstSection = true`),合计留白 12dp |
| 其他分组标题顶部 padding | 16dp |

分组的行间隙保持透明,透出当前容器底色;不要绘制页面背景色分隔线,以免在弹层或卡片内形成黑边。普通 Group 底色透明,内容卡片保留表面色。

这些数值由 `DesignSystem.kt` 实现。新增同类入口直接复用;统一调整时同时更新这里和公共实现。首页概览卡片、网关启停、表单操作按钮等保留各自用途对应的样式,不混用操作行规范。

- 编辑页复用 `EditorSaveBar`:内容最大宽度 720dp,左右 16dp、上下 12dp 内边距,保存按钮最小高度 50dp;保留安全区与键盘避让。编辑页标题栏使用页面背景色。
- 添加、导入、重连等全宽次级操作复用 `SecondaryAction`,最小高度 48dp,可选图标 18dp、文字间距 8dp;选择行右侧使用下拉箭头,导航行使用右箭头。
- 完整说明使用 `ContentCard`(20dp 外圆角、16dp 内边距、正文 bodyMedium),不要当作提示消息使用 Note。调用名称完整显示、可选择,使用等宽字体;复制操作不显示导航箭头。
- 空状态统一复用无图标的 `EmptyState`,只保留简短标题和必要操作;错误及危险操作仍须说明后果。Note 保留给帮助、提醒和错误,不用作普通详情容器。

UI 修改流程见 [.agents/skills/mbrain-style/SKILL.md](.agents/skills/mbrain-style/SKILL.md)。Skill 约束复用与验证,不另存一套视觉参数。

## 交互规则

- 底部导航只用于四个主页面;详情页带返回按钮,系统返回与页面返回一致。
- 首页仅保留连接凭据入口和工具/服务概览;网关启停使用右下角 64dp 悬浮按钮,位于底部导航上方 16dp,播放/停止图标对应状态,处理中显示进度并防止重复点击。列表末尾预留空间避免遮挡。能力管理通过底栏进入,运行记录放在设置中。
- 首页仅展示顶部能力概览(工具/服务)和服务网关状态;网关卡片内使用 64dp 开关按钮,播放/停止图标对应状态,处理中显示进度并禁用按钮。首页不显示连接组件、说明文字或重复的顶栏状态;连接凭据和运行记录通过设置进入,错误通过 Snackbar 反馈。能力管理通过底栏进入。
- 手机能力与外部 MCP 服务分区只显示标题,不附加解释。基础能力按已接入的 droid 模块展示为分组设置行,包含图标、名称与启用状态;复用 Group、ActionRow 和 GroupDivider,与手机能力及设置页保持相同的圆角、间距和行高,点击进入现有详情。
- Root / Shizuku 详情只保留一个启用开关和工具入口。打开时自动检查并申请权限,授权成功才启用;拒绝、超时或服务未启动保持关闭并显示原因。权限流程不依赖 Activity 生命周期;已启用 Root 在进程启动时自动恢复检查,工具仅在权限可用时发布。不提供独立授权入口或手动身份验证。
- MCP 列表进入服务详情;添加先选择类型,再进入全屏表单。托管进程参数逐项填写,不要求 JSON。
- MCP 无配置时仅展示“暂无服务”和“添加服务”按钮,不展示装饰图标或技术说明;复用 EmptyState 的无图标模式。
- 添加类型仅包含 HTTP 服务与托管进程;名称和地址留空由用户填写,不内置 MT 或其他特定服务商入口。已保存连接按用户配置展示。
- 编辑页底部固定保存;未保存离开提示放弃修改。移除服务确认;连接失败显示在对应服务详情并提供重试。
- 工具列表只显示名称与来源;完整说明进入工具详情。搜索同时匹配中文名称、原始名称和描述。
- Token 默认隐藏,复制有反馈。运行记录在独立页,最多 40 条。
- 各主页面和详情保存滚动位置;编辑草稿与导航在 Activity 重建时恢复。
- 设置中的内网穿透只配置一台服务器,点击服务器行直接进入完整编辑页,不展示服务器列表、单独的编辑按钮或顶部说明。服务器仅填写名称、地址、端口和 Token;隧道共用服务器,只配置本地目标、TCP 映射端口与可选 HTTP 公网地址。没有 HTTPS、TLS、插件和证书入口。

## 实现入口

Expand All @@ -40,3 +69,5 @@ Android 原生工具面板,面向管理手机能力与 MCP 服务的用户。
- OverviewScreens.kt:首页、能力、设置、记录。
- ConnectionScreens.kt:MCP 列表、详情、完整编辑页。
- DetailScreens.kt:工具、凭据。

- 隧道详情默认只显示启用状态、已填写的访问地址和编辑入口;编辑入口合并本地目标与映射端口摘要。连接诊断、访问凭据、重连和删除放入“更多”,诊断与运行记录默认收起;错误直接显示。
Loading
Loading