本文档说明遇到问题时如何提交有效反馈，帮助维护者快速判断是环境、签名证书、APK 兼容性还是工具本身的问题。
提交 issue 前建议先确认：
- 已使用 最新 Release。
- 本机已安装完整 JDK 8+，且
java、keytool可用。 - 输入 APK 已签名，且不是已经加固过的 APK。
- 如果涉及签名或自动签名，证书页中的证书已校验通过。
- 如果是 macOS 未签名应用无法打开，已按 README 中的
xattr说明移除隔离标记。
本地命令排障可参考 本地诊断与排障命令。
| 场景 | 模板 |
|---|---|
| 加固、签名、证书管理、环境检测、界面交互异常 | Bug 反馈 |
| Google Play 16 KB 对齐、安装失败、启动崩溃、覆盖安装失败、设备兼容问题 | APK 兼容性问题 |
| 新功能、工作流或使用体验建议 | 功能建议；提交与评审规则见功能需求收集与评审 |
| 安全漏洞、可直接复现的攻击细节 | 不提交公开 issue，使用 GitHub Security Advisories |
软件内的 Bug 反馈会自动附带诊断信息：在 设置 → 问题反馈 中填写表单后，提交前可以预览将要发送的反馈正文与诊断信息，无需手动复制。手动在 GitHub 提交 issue 时，请自行填写版本、操作系统与 Java 状态。
反馈与手动提交的 issue 一样会在 GitHub 上创建公开 issue，反馈正文（Bug 反馈还包括自动附带的诊断信息）任何访客都能看到，请只填写可以公开的内容。服务端不可用时，软件会提供在浏览器打开预填 issue 页面的入口，反馈正文与诊断信息会预填到表单中，仍需在 GitHub 上确认后提交。
加固页出现预检风险或任务失败时，可点击“复制诊断摘要”。该摘要包含预检结论、风险代码、运行策略和失败阶段；PVM2 零方法转换失败还包含方法数量与固定分类的跳过统计，不复制原始错误文本、路径、包名或业务类名。AAB 的零转换错误也提供该复制入口。输出目录的 pvm2-failure-*.json 为本地逐方法失败报告，含业务标识，不能直接公开。需要补充该报告、错误或日志时，应先由用户手动脱敏。
诊断信息包含：
- Shellsmith 版本、Git hash、构建日期
- 系统平台与 CPU 架构
- Java /
keytool状态 apktool/apksigner状态- 配置目录与数据目录是否可用
诊断信息不会包含：
- APK 路径
- 证书路径
- Keystore 密码或 Key 密码
- 完整用户目录
- APK、证书或其他业务文件内容
软件内问题反馈和手动提交的 issue 一样会创建公开 issue，请确保正文与附件都可以公开。公开 issue 中不要上传或粘贴：
- APK、AAB、加固前后产物
- keystore、p12、jks 等证书文件
- Keystore 密码、Key 密码、Alias 对应的私密上下文
- 完整用户目录、公司内部路径、包名或业务类名
- 可直接复现攻击细节的漏洞利用步骤
如果确实需要提供样本，请先使用最小可复现 demo，确认不包含真实业务代码、密钥或用户数据。
请提供：
- 软件内问题反馈自动附带的诊断信息
- 证书类型：JKS 或 PKCS12
- 是否使用证书页校验通过的证书
- 错误提示完整文本
不要提供证书文件、证书密码或真实证书路径。
请提供：
- 软件内问题反馈自动附带的诊断信息
- 证书类型：JKS 或 PKCS12
keytool -list是否能在本机成功执行- GUI 中的错误提示完整文本
不要提供证书密码。
请提供：
- 软件内问题反馈自动附带的诊断信息
- Android 版本、设备 ABI
adb install的脱敏输出- 原 APK 是否已签名
- 是否启用自动签名
请提供脱敏后的 adb logcat 关键日志，建议先过滤：
adb logcat | grep -E "AndroidRuntime|ax|lx|rx|e[1-4]"提交前请确认日志不包含业务敏感信息、真实用户信息或内部路径。
请提供：
- Google Play 的拒绝提示或检查工具输出
- 软件内问题反馈自动附带的诊断信息
- APK 中包含的 ABI，例如
arm64-v8a、armeabi-v7a - 加固后是否又经过第三方工具重新处理或重新打包
安全问题请阅读根目录 SECURITY.md。不要在公开 issue 中披露可直接复现的攻击细节。