amethyst

内容来源：SKILL.md（标准 Skill 格式） · 原始地址 · 查看安装指南

原始内容

# Amethyst Builder Skill

Build customized Amethyst Nostr clients for Android. Fork, rebrand, customize, and distribute your own version.

## Overview

[Amethyst](https://github.com/vitorpamplona/amethyst) is the premier Nostr client for Android. This skill enables you to:
- Create rebranded versions (custom name, package, icons)
- Build F-Droid-compatible releases (no Google Play dependencies)
- Add or modify features
- Sign and distribute APKs

## Prerequisites

### Required Tools

1. **Java 21** (via SDKMAN)
   ```bash
   curl -s "https://get.sdkman.io" | bash
   source "$HOME/.sdkman/bin/sdkman-init.sh"
   sdk install java 21.0.5-tem
   sdk use java 21.0.5-tem
   ```

2. **Android SDK**
   - Command-line tools from https://developer.android.com/studio#command-line-tools-only
   - Required components: build-tools, platform-tools, platforms;android-37
   - The exact SDK level is `android-compileSdk` in `gradle/libs.versions.toml` —
     check there if this number has drifted.

3. **Git** for cloning the repository

### Environment Setup

```bash
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

## Build Workflow

### 1. Clone the Repository

```bash
mkdir -p ~/projects/your-app-name
cd ~/projects/your-app-name
git clone https://github.com/vitorpamplona/amethyst.git .
```

### 2. Create Signing Key

```bash
keytool -genkeypair -v \
  -keystore ./release-key.jks \
  -alias your-app \
  -keyalg RSA -keysize 2048 \
  -validity 10000
```

Create `keystore.properties` in project root:
```properties
storeFile=release-key.jks
storePassword=your-password
keyAlias=your-app
keyPassword=your-password
```

### 3. Configure Signing

Add to `amethyst/build.gradle.kts` inside the `android {}` block:

```kotlin
val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties()
if (keystorePropertiesFile.exists()) {
    keystorePropertiesFile.inputStream().use { keystoreProperties.load(it) }
}

signingConfigs {
    create("release") {
        if (keystorePropertiesFile.exists()) {
            storeFile = rootProject.file(keystoreProperties["storeFile"] as String)
            storePassword = keystoreProperties["storePassword"] as String
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
        }
    }
}
```

This needs `import java.util.Properties` at the top of the file.

Update the release buildType to use the signing config:
```kotlin
buildTypes {
    getByName("release") {
        signingConfig = signingConfigs.getByName("release")
        // ... existing config
    }
}
```

Verify with `./gradlew :amethyst:signingReport` — the release variants should
report your keystore rather than `~/.android/debug.keystore`.

### 4. Disable Google Services (Required for F-Droid)

**⚠️ CRITICAL:** The Google Services plugin fails when you change the package name. For F-Droid builds, disable it.

Edit `amethyst/build.gradle.kts`, comment out the plugin:
```kotlin
plugins {
    alias(libs.plugins.androidApplication)
    // alias(libs.plugins.googleServices)  // DISABLED for F-Droid
    alias(libs.plugins.jetbrainsComposeCompiler)
    alias(libs.plugins.serialization)
    alias(libs.plugins.googleKsp)
}
```

### 5. Build

```bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk use java 21.0.5-tem
./gradlew assembleFdroidRelease
```

**Build time:** ~9 minutes first build, faster on subsequent builds.

### 6. Locate APKs

Output directory: `amethyst/build/outputs/apk/fdroid/release/`

Files generated:
- `amethyst-fdroid-arm64-v8a-release.apk` - ARM64 (most phones)
- `amethyst-fdroid-universal-release.apk` - All architectures (larger)

## Customizations

### Change App Name

Edit `amethyst/src/main/res/values/strings.xml`:
```xml
<string name="app_name" translatable="false">YourAppName</string>
<string name="app_name_debug" translatable="false">YourAppName Debug</string>
```

### Change Package ID

Edit `amethyst/build.gradle.kts`:
```kotlin
android {
    defaultConfig {
        applicationId = "com.yourcompany.yourapp"
    }
}
```

### Change Project Name

Edit `settings.gradle.kts`:
```kotlin
rootProject.name = "YourAppName"
```

### Change App Icon

Replace icon files in:
- `amethyst/src/main/res/mipmap-*/ic_launcher.webp`
- `amethyst/src/main/res/mipmap-*/ic_launcher_round.webp`

### Add Client Tag to Posts

Make your app identify itself on posts with `["client", "YourAppName"]`.

You do **not** need to add the tag per event type. The client tag is applied
centrally by `NostrSignerWithClientTag`, a signer decorator that appends the tag
to everything it signs (and respects the user's "add client tag" privacy
setting). Changing the name is a one-constant edit:

Edit `amethyst/src/main/java/com/vitorpamplona/amethyst/model/accountsCache/AccountCacheState.kt`:
```kotlin
const val CLIENT_TAG_NAME = "YourAppName"
```

That constant is passed to `NostrSignerWithClientTag` when the account's signer
is built, so every signed event carries your name.

The tag itself lives in
`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip89AppHandlers/clientTag/`
(`ClientTag`, `TagArrayBuilderExt`, `NostrSignerWithClientTag`) — you only need to
touch it if you want the optional NIP-89 handler address / relay hint variants.

### Modify Default Relays

Edit `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/defaults/Constants.kt`
(see also `AmethystDefaults.kt` and `DefaultDmIndexerRelays.kt` in the same folder).

## Troubleshooting

### google-services.json error
Disable the Google Services plugin (see step 4).

### Java version error
```bash
sdk use java 21.0.5-tem
java -version  # Must show 21.x
```

### Out of memory
Edit `gradle.properties`:
```properties
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m
```

### Clean build
```bash
./gradlew --stop
./gradlew clean
./gradlew assembleFdroidRelease
```

## Distribution

Deploy APKs via:
- **Surge.sh:** `surge ./releases your-app.surge.sh`
- **Zapstore:** Submit to zapstore.dev
- **Direct download:** Host on any web server

Amethyst Builder Skill

Build customized Amethyst Nostr clients for Android. Fork, rebrand, customize, and distribute your own version.

Overview

Amethyst is the premier Nostr client for Android. This skill enables you to:

Create rebranded versions (custom name, package, icons)
Build F-Droid-compatible releases (no Google Play dependencies)
Add or modify features
Sign and distribute APKs

Prerequisites

Required Tools

Java 21 (via SDKMAN)

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 21.0.5-tem
sdk use java 21.0.5-tem

Android SDK
- Command-line tools from https://developer.android.com/studio#command-line-tools-only
- Required components: build-tools, platform-tools, platforms;android-37
- The exact SDK level is android-compileSdk in gradle/libs.versions.toml — check there if this number has drifted.
Git for cloning the repository

Environment Setup

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

Build Workflow

1. Clone the Repository

mkdir -p ~/projects/your-app-name
cd ~/projects/your-app-name
git clone https://github.com/vitorpamplona/amethyst.git .

2. Create Signing Key

keytool -genkeypair -v \
  -keystore ./release-key.jks \
  -alias your-app \
  -keyalg RSA -keysize 2048 \
  -validity 10000

Create keystore.properties in project root:

storeFile=release-key.jks
storePassword=your-password
keyAlias=your-app
keyPassword=your-password

3. Configure Signing

Add to amethyst/build.gradle.kts inside the android {} block:

val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties()
if (keystorePropertiesFile.exists()) {
    keystorePropertiesFile.inputStream().use { keystoreProperties.load(it) }
}

signingConfigs {
    create("release") {
        if (keystorePropertiesFile.exists()) {
            storeFile = rootProject.file(keystoreProperties["storeFile"] as String)
            storePassword = keystoreProperties["storePassword"] as String
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
        }
    }
}

This needs import java.util.Properties at the top of the file.

Update the release buildType to use the signing config:

buildTypes {
    getByName("release") {
        signingConfig = signingConfigs.getByName("release")
        // ... existing config
    }
}

Verify with ./gradlew :amethyst:signingReport — the release variants should report your keystore rather than ~/.android/debug.keystore.

4. Disable Google Services (Required for F-Droid)

⚠️ CRITICAL: The Google Services plugin fails when you change the package name. For F-Droid builds, disable it.

Edit amethyst/build.gradle.kts, comment out the plugin:

plugins {
    alias(libs.plugins.androidApplication)
    // alias(libs.plugins.googleServices)  // DISABLED for F-Droid
    alias(libs.plugins.jetbrainsComposeCompiler)
    alias(libs.plugins.serialization)
    alias(libs.plugins.googleKsp)
}

5. Build

source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk use java 21.0.5-tem
./gradlew assembleFdroidRelease

Build time: ~9 minutes first build, faster on subsequent builds.

6. Locate APKs

Output directory: amethyst/build/outputs/apk/fdroid/release/

Files generated:

amethyst-fdroid-arm64-v8a-release.apk - ARM64 (most phones)
amethyst-fdroid-universal-release.apk - All architectures (larger)

Customizations

Change App Name

Edit amethyst/src/main/res/values/strings.xml:

<string name="app_name" translatable="false">YourAppName</string>
<string name="app_name_debug" translatable="false">YourAppName Debug</string>

Change Package ID

Edit amethyst/build.gradle.kts:

android {
    defaultConfig {
        applicationId = "com.yourcompany.yourapp"
    }
}

Change Project Name

Edit settings.gradle.kts:

rootProject.name = "YourAppName"

Change App Icon

Replace icon files in:

amethyst/src/main/res/mipmap-*/ic_launcher.webp
amethyst/src/main/res/mipmap-*/ic_launcher_round.webp

Add Client Tag to Posts

Make your app identify itself on posts with ["client", "YourAppName"].

You do not need to add the tag per event type. The client tag is applied centrally by NostrSignerWithClientTag, a signer decorator that appends the tag to everything it signs (and respects the user's "add client tag" privacy setting). Changing the name is a one-constant edit:

Edit amethyst/src/main/java/com/vitorpamplona/amethyst/model/accountsCache/AccountCacheState.kt:

const val CLIENT_TAG_NAME = "YourAppName"

That constant is passed to NostrSignerWithClientTag when the account's signer is built, so every signed event carries your name.

The tag itself lives in quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip89AppHandlers/clientTag/ (ClientTag, TagArrayBuilderExt, NostrSignerWithClientTag) — you only need to touch it if you want the optional NIP-89 handler address / relay hint variants.

Modify Default Relays

Edit commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/defaults/Constants.kt (see also AmethystDefaults.kt and DefaultDmIndexerRelays.kt in the same folder).

Troubleshooting

google-services.json error

Disable the Google Services plugin (see step 4).

Java version error

sdk use java 21.0.5-tem
java -version  # Must show 21.x

Out of memory

Edit gradle.properties:

org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m

Clean build

./gradlew --stop
./gradlew clean
./gradlew assembleFdroidRelease

Distribution

Deploy APKs via:

Surge.sh: surge ./releases your-app.surge.sh
Zapstore: Submit to zapstore.dev
Direct download: Host on any web server