amber-pm/AGENTS.md

# APM 代理与助手（AGENTS）

本文档描述了 APM 项目中使用的代理和助手工具，它们用于增强 APM 的功能和用户体验。

## 1. 核心代理工具

### 1.1 amber-pm-debug

**功能**：用于在 APM 环境中执行命令，提供调试和诊断功能。

**使用场景**：
- 执行 apt 相关命令
- 执行 dpkg 相关命令
- 进入调试环境

**示例**：
```bash
amber-pm-debug apt update
amber-pm-debug dpkg --configure -a
```

### 1.2 amber-pm-app-launcher

**功能**：通过应用启动器启动 APM 软件包。

**使用场景**：
- 启动已安装的 APM 应用
- 传递参数给应用

**示例**：
```bash
amber-pm-app-launcher firefox
amber-pm-app-launcher gedit --new-document
```

### 1.3 amber-pm-configure-nvidia

**功能**：配置 NVIDIA 驱动支持。

**使用场景**：
- 自动从主机获取 NVIDIA 驱动文件
- 为 APM 应用提供 GPU 加速支持

**示例**：
```bash
amber-pm-configure-nvidia /path/to/ace-env
```

## 2. 构建与转换工具

### 2.1 amber-pm-convert

**功能**：将普通 Deb 包转换为 APM 软件包。

**使用场景**：
- 转换第三方 Deb 包为 APM 格式
- 自定义包名和版本号

**示例**：
```bash
amber-pm-convert --base amber-pm-trixie /path/to/package.deb
amber-pm-convert --base amber-pm-bookworm-spark-wine /path/to/package.deb --pkgname new-pkg --version 1.0.0
```

### 2.2 amber-pm-addons-maker

**功能**：创建 APM addons 包，用于在 base 之上叠加额外的环境层。

**使用场景**：
- 为 base 环境添加 NVIDIA 驱动、Mesa 补丁
- 为 base 环境添加 Git、Java、Python 等运行时
- 所有基于该 base 的应用自动继承 addons 环境

**示例**：
```bash
amber-pm-addons-maker --base amber-pm-bookworm --manual --pkgname amber-pm-bookworm-nvidia-addons
amber-pm-addons-maker --base amber-pm-trixie /path/to/mesa-patch.deb --pkgname amber-pm-trixie-mesa-addons
```

**说明**：
- addons 包命名格式建议为 `<base>-<描述>-addons`
- 安装后自动在对应 base 的 `info_layer_addons.d/` 中注册
- 支持 `--manual` 参数进入交互式创建流程

### 2.3 amber-pm-dstore-patch

**功能**：修补应用商店相关配置。

**使用场景**：
- 安装或更新软件包后自动执行
- 确保应用商店配置正确

### 2.3 amber-pm-desktop-fix

**功能**：修复桌面环境相关问题，维护应用程序和图标链接。

**使用场景**：
- 安装或移除软件包后自动执行
- 确保桌面环境正常运行
- 自动迁移旧版链接到新目录结构

**说明**：
- 银河麒麟系统：链接到 `/usr/share/applications/`
- 其他发行版：链接到 `/usr/local/share/applications/apm/`

## 3. 沙箱与安全工具

### 3.1 APM_USE_SANDBOX

**功能**：启用主目录沙箱化。

**使用场景**：
- 运行不受信任的应用
- 保护用户主目录

**示例**：
```bash
apm sandbox-run firefox
```

### 3.2 APM_USE_BWRAP

**功能**：使用 bwrap 进行额外的隔离。

**使用场景**：
- 需要更强隔离性的应用
- 增强安全性

**示例**：
```bash
apm bwrap-run firefox
```

## 4. 本地安装工具

### 4.1 ssinstall

**功能**：使用 ssinstall 进行本地软件安装。

**使用场景**：
- 安装本地软件包
- 与 spark-store 集成

**示例**：
```bash
apm ssinstall /path/to/package
```

### 4.2 ssaudit

**功能**：使用 ssaudit 进行本地软件安装。

**使用场景**：
- 安装本地软件包并进行审计
- 与 spark-store 集成

**示例**：
```bash
apm ssaudit /path/to/package
```

## 5. 环境变量

### 5.1 APM_PKG_NAME

**功能**：指定当前运行的包名。

**使用场景**：
- 在脚本中识别当前包
- 为应用提供包信息

### 5.2 PATH_PREFIX

**功能**：指定 APM 基础路径。

**使用场景**：
- 自定义 APM 安装位置
- 多环境管理

## 6. 工作原理

APM 代理和助手工具通过以下方式工作：

1. **环境隔离**：使用 fuse-overlayfs 创建隔离的文件系统环境
2. **命令转发**：将用户命令转发到适当的环境中执行
3. **资源共享**：从主机系统获取必要的资源（如 NVIDIA 驱动）
4. **安全增强**：提供沙箱和隔离机制
5. **用户体验**：简化应用的安装和运行过程

## 7. 故障排除

### 7.1 常见问题

- **NVIDIA 驱动问题**：确保主机已安装 NVIDIA 驱动，APM 会自动检测并使用
- **沙箱权限**：确保用户有足够的权限创建和管理沙箱
- **包依赖**：使用 `apm show <package>` 查看包依赖，确保所有依赖已安装

### 7.2 调试命令

```bash
# 查看调试信息
apm debug

# 检查包状态
amber-pm-debug dpkg -l | grep <package>

# 检查 NVIDIA 配置
apm-nvidia-toggle
```

## 8. 扩展与定制

APM 代理系统设计为可扩展的，您可以：

1. **添加自定义代理**：在 `src/var/lib/apm/apm/files/ace-env/usr/bin/` 目录添加新的代理脚本
2. **修改现有代理**：根据需要调整现有代理的行为
3. **创建自定义基础环境**：使用 `amber-pm-convert` 工具创建基于特定需求的基础环境

通过这些工具和技术，APM 提供了一个灵活、安全、高效的软件包管理系统，适用于各种 Linux 发行版。