KFShell Showcase

KFShell 是一个以 APK 交付的非 root Android Ubuntu 24.04 用户态运行环境，用于在手机上运行终端、后台服务、本机 Web 服务和 AI/Agent 开发工具链。

说明：本仓库是公开 showcase 内容包，只用于项目介绍、技术评估、赞助/额度申请和演示沟通。KFShell 主源码仓库当前为 private，不在此公开仓库中发布。

当前能力

• 通过 APK 在非 root Android 设备上交付 Ubuntu 24.04 用户态环境。
• 使用 pRoot 管理 rootfs、bind mount、环境变量、网络和 shell/exec 启动。
• 支持 Terminal 交互会话、Background runtime 和 supervisord 后台服务健康检查。
• 具备 runtime 状态投影、stale 状态回收、后台恢复/backoff、诊断输出和任务可视化能力。
• 支持工作区、PATH、日志、包环境和项目交换流程，为移动端开发环境和 AI Agent 运行做准备。
• 已验证本机 Web 服务可在手机浏览器通过 localhost / 127.0.0.1 访问。
• 已在真机上跑通 Hermes Agent + MiniMax-M2.7-highspeed 的 Agent 工作流验证。

技术架构

KFShell 当前按三层理解：

1. pRoot Base Layer
   负责 rootfs/runtime 目录、pRoot 启动参数、bind mount、网络、环境变量和基础进程启动。
2. Middle Runtime Layer
   负责 runtime root 归属、Terminal/Background runtime 状态、supervisord 健康、stale 记录回收、诊断和统一状态解释。
3. UI Projection Layer
   负责把中间层事实展示给用户，并触发终端、任务、状态刷新和导航等操作。

更详细说明见 docs/ARCHITECTURE_OVERVIEW.md。

AI / Agent 使用情况

KFShell 的目标不是只做一个 Android 终端，而是在手机上提供可持续运行的 Linux 用户态工作站，使 AI Agent、开发工具链、本机服务和自动化能力可以在真实移动设备上协同工作。

当前已验证方向包括：

• AI/开发环境一键补全与 bootstrap 流程。
• Hermes Agent 真机运行。
• MiniMax-M2.7-highspeed 真机调用链路验证。
• Agent 在 Ubuntu 用户态中读写文件、执行命令、访问本机服务的基础路径。
• 后续面向 WebUI/Gateway、ADB 自动化、子 App 协作和多 Agent 调度扩展。

详见 docs/AI_USAGE.md。

真机验证

当前项目已经完成多轮真实 Android 设备验证，重点包括：

• 升级安装后冷启动成功。
• Terminal 会话恢复到 running / observed。
• Task 页面可观察 Terminal proot/bash 与 Background proot/supervisord。
• Status 页面可展示 runtime roots、stale count、metrics pid 和 supervisord 健康信息。
• supervisord 服务采样正常，无 degraded services。
• 主题切换后 tab、title、fragment 和内容保持一致。
• 手机本机 Web 服务 localhost / 127.0.0.1 浏览器访问已验证。

当前状态见 docs/CURRENT_STATE.md。

后续方向

• WebUI / Gateway：把手机内运行的服务以更稳定的本机 Web 入口暴露给用户和 Agent。
• ADB 自动化：为真机调试、安装、日志、截图和回归验证建立自动化入口。
• 子 App 协作：探索主运行时、辅助 App、系统能力桥接之间的协同。
• Agent 工作区：补强包管理、环境补全、长期任务、日志导出和项目交换。
• 演示交付：准备不含账号、API key、token、私有日志和签名密钥的 demo APK 与视频。

路线图见 docs/ROADMAP.md。

私有源码说明

为保护项目安全和后续产品化空间，以下内容不在本 showcase 仓库公开：

• KFShell 主源码仓库。
• 完整 app/src 源码。
• keystore、jks、签名配置和发布密钥。
• .env、API key、token、账号、cookie、私有日志。
• 内部构建产物、完整调试日志和未脱敏真机数据。

如需评估源码质量、运行方式或演示能力，可通过私下方式提供受控演示、录屏或脱敏 demo APK。

截图与演示

• Demo APK 已作为 GitHub Release 产物发布：
  Download demo APK
• 截图放置说明见 screenshots/README.md。
• demo APK / 视频放置说明见 releases/README.md。

APK 不直接提交进 Git 历史；公开仓库通过 GitHub Releases 提供 demo build。当前最新 demo 产物为 kfshell-demo-u24-v0.24.0-20260525-1404-vc261451404-hardened.apk，可从 latest release 下载。

联系 / 演示说明

本 showcase 仓库用于 AI token、额度、赞助和技术评估沟通。评估方如需进一步了解，可请求：

• 真机录屏。
• 脱敏截图。
• 不含密钥和账号的 demo APK。
• 私下技术 walkthrough。
• 指定场景的 Agent / Web 服务演示。