Claude Code 权限流程实战示例（含补全提示词）

Codex CLI 用法详解：命令、作用与常见工作流

Claude Code 权限 / 安全审查调用流程图

AI 编程最实用 10 条

拆解Claude Code权限系统：四层安全审查架构详解​

如何系统地使用 AI 进行编程

- prompt.md 是一份任务契约文档：目标定义最终必须完成的结果，执行步骤定义建议做法但允许调整；AI 必须以目标是否完成作为唯一完工标准，而不是以“我觉得差不多了”作为结束标准。

  结合项目实现，最关键的是这几条：

  - 必须有一段“冻结目标”
      - 最稳妥写法是显式 marker：
          - 
          - 
      - 这是项目优先识别的目标区，见 src/engine/planning.ts:302
  - 如果不用 marker，也最好用标准标题
      - 推荐：## 目标
      - 项目还能识别：Goals、不可变目标、最终目标、完成标准、验收标准、Deliverables
      - 见 src/engine/planning.ts:342
  - 目标要一行一个，用列表写
      - 推荐用 -
      - 例如：

        - 更新 README 的安装章节
        - 补齐 CLI 示例
        - 为规划模块补充单元测试
  - 目标要“结果导向”，不要写成“过程导向”
      - 好：- 为 xxx 增加单元测试
      - 不好：- 看一下测试
  - 每个目标要可判断完成与否
      - 好：- README 增加“快速开始”章节
      - 不好：- README 更完善一些
  - 执行步骤可以变，目标不要轻易变
      - 因为这个项目会冻结目标，再允许计划继续修正，见 src/engine/planning.ts:68
  - 如果你担心目标后续会被改坏，直接用 --frozen-goals-text
      - 这是最高优先级的冻结目标来源，见 src/engine/planning.ts:328

  最推荐的写法

  这是我建议你长期使用的“AI 最好理解”的模板：

  # 任务名称

  ## 定义

  这是一份任务契约，而不是普通备注。
  你必须把“目标”视为最终交付标准，把“执行步骤”视为可调整的施工计划。
  允许优化步骤、顺序和方法，但不允许擅自删除、弱化或改写目标。
  只有当所有目标都已实际完成、相关修改已落盘、并完成必要自检后，任务才算完成。
  不要把“已分析”“已思考”“已给建议”视为完成，必须以实际交付结果为准。

  ## 背景

  - 当前项目是什么
  - 这次任务为什么要做
  - 有哪些已知上下文

  ## 工作边界

  - 允许修改的范围：
    - `src/`
    - `README.md`
    - `test/`
  - 不允许修改的范围：
    - CI 配置
    - 发布流程
  - 如无必要，不新增依赖
  - 保持现有代码风格

  ## 不可变目标

  
  - 完成 README 的安装与快速开始章节更新
  - 为 CLI 增加至少一个真实可运行的示例
  - 为规划模块补充覆盖冻结目标逻辑的测试
  

  ## 执行步骤

  - 先阅读 README、CLI 入口和 planning 相关实现
  - 再确定最小修改范围
  - 先补文档，再补测试，最后统一自检
  - 如发现目标与仓库现状冲突，以目标为准做最小必要调整

  ## 输出要求

  - 修改应直接落盘到仓库
  - 说明中给出关键文件路径
  - 如果有取舍，说明原因
  - 不要只给建议而不动手

  ## 验收标准

  - 所有不可变目标都能逐项对账
  - 文档内容与实际命令一致
  - 新增测试能覆盖对应行为
  - 不引入明显的构建或运行错误

  ## 补充说明

  - 如果发现现有实现与目标冲突，优先满足目标，再在结果里解释
  - 如果某项无法完成，明确说明阻塞点和未完成部分

codex-autoresearch

手机相册端侧文本搜图方案调研

# 在 Linux 上开发 Android，其实没有想象中那么难

很多人一提到 Android 开发，第一反应就是：

- 必须装 Android Studio
- 环境变量很烦
- SDK / JDK / Gradle 版本经常打架
- 模拟器重，真机调试麻烦
- Linux 上搞 Android 感觉像“民间偏方”



但我这次在 Linux 上把一个真实的 Android APK 项目跑通、修改、编译、安装，反而更加确信一件事：

**Linux 完全可以作为 Android 的一线开发环境，而且命令行工作流其实很强。**

这篇文章我尽量用“手工搭环境 + 命令行构建 + 真机调试”的方式讲清楚，适合：

- 想在 Linux 上做 Android 开发的人
- 想搭 CI / 自动化构建环境的人
- 不想一上来就被 Android Studio 全家桶绑住的人
- 想用 VS Code / Neovim / JetBrains Fleet 之类编辑器配合 Gradle 的人

这份指南也结合了一个真实项目验证过的流程：

- JDK: 17
- Android SDK Command-line Tools: 20.0
- Android Platform Tools: 37.0.0
- Android SDK Platform: android-36
- Build Tools: 36.0.0
- 构建方式: `./gradlew :app:assembleDebug`

## 一、先把 Android 开发拆开看

Android 开发看起来复杂，本质上其实只需要理解 5 件事：

1. **JDK**：给 Gradle / Kotlin / Java 编译器用
2. **Android SDK**：给 Android 平台、构建工具、adb 用
3. **Gradle Wrapper**：项目自己的构建入口
4. **编辑器 / IDE**：写代码的工具，可选 Android Studio，也可以不用
5. **设备或模拟器**：用来安装和调试 APK

换句话说，Android Studio 只是把这些东西打包得更完整，但**不是唯一入口**。

如果你已经有：

- 一个正常的 Linux 开发环境
- 一台 Android 真机
- 一个带 `gradlew` 的 Android 项目

那你离能编译 APK，其实已经不远了。

## 二、Linux 上最小可用环境

下面以 Ubuntu / Debian 系为例。

### 1. 安装 JDK 和基础工具

```bash
sudo apt update
sudo apt install -y openjdk-17-jdk unzip zip wget curl git
```

检查 JDK：

```bash
java -version
javac -version
```

如果项目使用的是较新的 Android Gradle Plugin，**JDK 17 基本已经是当前最稳妥的选择**。

如果你机器上装了多个 JDK，建议显式设置：

```bash
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
```

不同发行版的 JDK 路径可能不同，可以这样查：

```bash
readlink -f $(which java)
```

## 三、安装 Android SDK Command-line Tools

Android 官方已经明确支持**不装 Android Studio，只安装命令行工具**的方式开发和构建 Android。这个方式尤其适合 Linux、服务器和 CI。

### 1. 选择一个 SDK 安装目录

比如：

```bash
mkdir -p $HOME/android-sdk
```

### 2. 下载 Command-line Tools

去 Android 官方下载页下载 **Command line tools for Linux**：

- https://developer.android.com/studio
- https://developer.android.com/tools/sdkmanager

下载完成后解压，并整理成 Android 官方推荐的目录结构：

```bash
mkdir -p $HOME/android-sdk/cmdline-tools
cd /tmp
unzip commandlinetools-linux-*.zip
mv cmdline-tools $HOME/android-sdk/cmdline-tools/latest
```

最终建议目录长这样：

```text
$HOME/android-sdk/
├── cmdline-tools/
│   └── latest/
│       ├── bin/
│       ├── lib/
│       └── source.properties
```

### 3. 配置环境变量

把下面这些内容写进 `~/.bashrc` 或 `~/.zshrc`：

```bash
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

生效：

```bash
source ~/.bashrc
```

检查：

```bash
sdkmanager --version
adb version
```

## 四、安装 Android 平台和构建工具

Command-line Tools 本身只是一把钥匙，真正构建项目时还需要平台包和 build-tools。

先接受许可证：

```bash
yes | sdkmanager --licenses
```

然后安装常用组件：

```bash
sdkmanager --install \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "cmdline-tools;latest"
```

如果你项目的 `compileSdk` 是别的版本，比如 34 或 35，就把 `platforms;android-36` 改掉。

### 如何知道项目需要什么版本？

直接看模块的 `build.gradle.kts` 或 `build.gradle`：

```kotlin
android {
    compileSdk = 36

    defaultConfig {
        minSdk = 33
        targetSdk = 36
    }
}
```

如果项目声明了：

- `compileSdk = 36`
- `targetSdk = 36`

那你至少要装：

- `platforms;android-36`
- 一套可用的 `build-tools`

## 五、为什么我强烈建议用项目自带的 `gradlew`

很多 Android 新手会直接装一个系统级 `gradle`，然后执行：

```bash
gradle build
```

这通常不是最稳的做法。

**更推荐使用项目自带的 `gradlew`**，因为：

- 它会使用项目锁定的 Gradle 版本
- 团队成员环境更一致
- CI 也通常这样跑
- 少掉很多“我这里能编，你那里不能编”的问题

也就是说，进入项目目录后，优先执行：

```bash
./gradlew tasks
```

而不是直接使用系统的 `gradle`。

## 六、一个真实 Android 项目的 Linux 构建流程

假设项目目录是：

```text
pipecat_apps/livekit_video_chat_apk/
```

这个目录里有：

- `gradlew`
- `settings.gradle.kts`
- `app/`

那么最常用的命令就是：

```bash
cd pipecat_apps/livekit_video_chat_apk
export ANDROID_HOME=/opt/android-sdk
export ANDROID_SDK_ROOT=/opt/android-sdk
./gradlew :app:compileDebugKotlin
./gradlew :app:assembleDebug
```

如果构建成功，APK 通常在：

```text
app/build/outputs/apk/debug/app-debug.apk
```

### 这两个命令分别做什么？

#### 1. 先跑 Kotlin 编译

```bash
./gradlew :app:compileDebugKotlin
```

作用：

- 先验证 Kotlin / Compose / 依赖是否能过编译
- 比直接全量打包更快
- 很适合作为“第一道烟雾测试”

#### 2. 再打完整 APK

```bash
./gradlew :app:assembleDebug
```

作用：

- 生成 debug APK
- 适合本地安装和真机测试

## 七、如何在 Linux 上安装 APK 到手机

我个人非常推荐：**Linux + 真机 + adb**。

因为很多时候，真机比模拟器更省心：

- 麦克风 / 摄像头 / 蓝牙 / 网络环境更真实
- 性能更稳定
- 少掉模拟器图形和硬件加速问题

### 1. 打开手机开发者选项

在 Android 手机上：

- 连续点击版本号，打开开发者模式
- 打开 USB 调试
- 用数据线连到 Linux 机器

### 2. 检查设备连接

```bash
adb devices
```

如果第一次连接，手机会弹授权框，点允许。

看到类似输出就说明连上了：

```text
List of devices attached
XXXXXXXXXXXX    device
```

### 3. 安装 APK

```bash
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

说明：

- `-r` 表示覆盖安装
- 这对频繁调试非常有用

如果你知道应用包名，也可以直接启动：

```bash
adb shell am start -n com.zhiyue.livekitvideochatapk/.MainActivity
```

## 八、Linux 上调 Android 日志，其实很好用

很多人只在 Android Studio 里看 Logcat，但 Linux 终端下调日志其实非常顺手。

### 1. 直接看全部日志

```bash
adb logcat
```

### 2. 先清空再看

```bash
adb logcat -c
adb logcat
```

### 3. 配合 `rg` 过滤关键词

```bash
adb logcat | rg "AndroidRuntime|FATAL|LiveKit|OkHttp|zhiyue"
```

这个组合在 Linux 上特别强：

- `adb logcat` 输出系统日志
- `rg` 做高性能筛选
- 出现崩溃时几乎可以秒定位

### 4. 看崩溃最有用的几个关键词

你可以重点关注：

- `AndroidRuntime`
- `FATAL EXCEPTION`
- `SecurityException`
- `NetworkSecurityConfig`
- `IllegalStateException`
- `NullPointerException`

## 九、如果你还想用模拟器，也完全可以

如果你没有真机，也可以在 Linux 上用模拟器，只是通常更重一些。

先安装：

```bash
sdkmanager --install \
  "emulator" \
  "platform-tools" \
  "platforms;android-36" \
  "system-images;android-36;google_apis;x86_64"
```

创建 AVD：

```bash
avdmanager create avd -n pixel-api-36 \
  -k "system-images;android-36;google_apis;x86_64"
```

启动模拟器：

```bash
emulator -avd pixel-api-36
```

不过，如果你的项目涉及：

- 摄像头
- 麦克风
- WebRTC / LiveKit
- 音视频实时交互
- 蓝牙 / 通话 / 系统悬浮窗

我还是建议**优先真机**。

## 十、Linux 上开发 Android，最常见的坑

### 1. `./gradlew: No such file or directory`

原因通常很简单：**你不在 Android 项目的根目录**。

比如要进到这个目录：

```bash
cd pipecat_apps/livekit_video_chat_apk
```

再执行：

```bash
./gradlew :app:assembleDebug
```

### 2. `SDK location not found`

说明 Gradle 没找到 Android SDK。

检查：

```bash
echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT
```

必要时显式设置：

```bash
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
```

### 3. `failed to find Build Tools revision`

说明缺少对应 `build-tools`。

解决：

```bash
sdkmanager --install "build-tools;36.0.0"
```

按项目实际版本替换即可。

### 4. `Platform android-XX not found`

说明缺少平台包。

解决：

```bash
sdkmanager --install "platforms;android-36"
```

### 5. JDK 版本不对

如果项目要求 JDK 17，而你机器默认还是 11 或 21，Gradle 可能会报莫名其妙的问题。

建议：

```bash
java -version
./gradlew --version
```

优先保证项目和本机 JDK 主版本一致。

### 6. `adb devices` 看不到手机

Linux 下这很常见，通常有几种原因：

- 数据线只是充电线
- 手机上没开 USB 调试
- 没点设备授权弹窗
- Linux 没配好 udev 规则

先试：

```bash
adb kill-server
adb start-server
adb devices
```

如果还是不行，再去补设备厂商的 udev 规则。

### 7. `10.0.2.2` 只对模拟器有效

这是非常高频的坑。

- **Android 模拟器访问宿主机回环地址**：用 `10.0.2.2`
- **真机访问宿主机服务**：不能用 `10.0.2.2`
- 真机应该用：
  - 局域网 IP
  - 公网 IP
  - 或正式域名

### 8. WebSocket / HTTP 明明服务是通的，App 却连不上

常见原因：

- 地址填错了端口
- 你在真机上还写着 `localhost`
- `ws://` 和 `wss://` 混用了
- App 没配置 cleartext HTTP
- 服务端证书或反向代理没配好

Android 联网问题，**七成不是代码，而是地址和网络边界**。

## 十一、Linux 命令行工作流，为什么反而更适合工程化

很多人觉得 Android Studio 才是“正统”，但如果你从工程效率角度看，Linux 命令行其实有很大优势。

### 1. 更容易自动化

比如你可以很自然地串起来：

```bash
./gradlew :app:compileDebugKotlin && \
./gradlew :app:assembleDebug && \
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

### 2. 更适合 CI / 远程开发

在服务器、远程工作站、容器、云开发机上，CLI 方案比 GUI 方案稳定得多。

### 3. 更适合和 AI 编码助手协作

当项目能通过：

- 读源码
- 跑 Gradle
- 看 logcat
- 直接构建 APK

形成完整闭环时，AI 其实能帮你做非常多事情。

### 4. 出问题时更透明

终端日志、Gradle 任务、依赖下载过程、打包路径，都更直接。

你不会只看到一个 IDE 弹窗写着：

```text
Build failed
```

而是能看到具体失败在哪个 task、哪个依赖、哪个源码文件。

## 十二、什么时候还是建议装 Android Studio

虽然我一直在强调 Linux CLI 工作流很好，但我并不反对 Android Studio。

如果你要做这些事情，Android Studio 依然很有价值：

- Compose Preview
- Layout Inspector
- Profiler
- 数据库查看器
- Manifest / Gradle 可视化编辑
- 模拟器图形化管理

我的建议是：

- **构建、安装、调试链路**：尽量学会 CLI
- **复杂 UI 调整、性能分析**：再结合 Android Studio

这样你的工作流最灵活。

## 十三、一套我自己比较推荐的 Linux Android 开发习惯

如果你问我，Linux 上开发 Android，最舒服的姿势是什么，我会推荐这套：

1. 用 JDK 17
2. Android SDK 用 command-line tools 安装
3. 永远优先用项目自带 `./gradlew`
4. 真机优先，模拟器次之
5. 用 `adb logcat | rg` 看日志
6. 编辑器随意，但构建和安装尽量脚本化
7. 把常用命令写到 `Makefile`、`justfile` 或 shell script

比如：

```bash
#!/usr/bin/env bash
set -e

export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME

./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

你会发现，一旦链路打通，Android 在 Linux 上并不“麻烦”，反而是**非常适合工程化和自动化**的一类开发工作。

## 十四、这篇文章最后想说的

Android 开发真正难的，不是 Linux。

真正难的是：

- 你第一次接触时，概念太多
- IDE 把很多细节藏起来了
- 出错时不知道是 JDK、SDK、Gradle、设备，还是网络问题

一旦你把它拆开，Android 在 Linux 上其实很清晰：

- JDK 负责编译器
- SDK 负责 Android 平台工具
- Gradle Wrapper 负责项目构建
- adb 负责设备通信
- 编辑器只是编辑器

搞明白这一层以后，你会发现：

**Linux 不但能开发 Android，而且非常适合认真做 Android。**

---

## 附：一套最小可用命令速查

### 安装依赖

```bash
sudo apt update
sudo apt install -y openjdk-17-jdk unzip zip wget curl git
```

### 环境变量

```bash
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

### 安装 SDK 组件

```bash
yes | sdkmanager --licenses
sdkmanager --install \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "cmdline-tools;latest"
```

### 构建 APK

```bash
cd pipecat_apps/livekit_video_chat_apk
./gradlew :app:compileDebugKotlin
./gradlew :app:assembleDebug
```

### 安装到手机

```bash
adb devices
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

### 看日志

```bash
adb logcat -c
adb logcat | rg "AndroidRuntime|FATAL|LiveKit|OkHttp"
```

---

## 参考资料

- Android SDK Command-line Tools / `sdkmanager`
  - https://developer.android.com/tools/sdkmanager
- Android Studio 下载页
  - https://developer.android.com/studio
- ADB 官方文档
  - https://developer.android.com/guide/developing/tools/adb.html
- Android Studio 安装说明
  - https://developer.android.com/studio/install