简体中文 | English
自愿支持项目维护 · Voluntarily support project maintenance · 赞助说明 / Sponsorship
DeepSeek Harness（DSH）插件 —— 让 DSH 里的 AI 用自然语言直接对 APK 做解包、回编、签名、DEX 处理、资源与文件编辑，不用敲命令行。
他把（apktool / aapt2 / apksigner / zipalign / baksmali / smali / d8 / APKEditor）包装成 AI 可调用的工具。
⚠️ 平台支持边界：当前仅声明并面向 Windows（64 位）发行。 本仓库的工具解析器在非 Windows 平台会主动返回EPLATFORM，因此 Linux / macOS / Termux 不属于受支持运行平台。package.json声明os: ["win32"]、cpu: ["x64", "arm64"]；本项目文档中的验证记录以 Windows x64 为主，Windows ARM64 虽被元数据允许，但未据此证明所有外部工具均原生兼容。32 位 Windows（ia32）不支持。
cd /path/to/parent
dsh plugin --profile web add ./apk-devkit以 link: 方式链接，改完代码重启 Web UI 即生效，无需重装。
dsh plugin --profile web add apk-devkitdsh plugin --profile web add github:qftuftfutg/apk-devkitdsh --profile web --dump-config | grep apk-devkit
dsh --profile web启动后确认：
--dump-config输出里能看到apk-devkit行- 启动日志正常应包含一行
[apk-devkit] loaded; registering N tools; workspace=...—— 这是插件正常的加载日志，不是报错。N应为 38。 若同时出现[apk-devkit] 模块加载失败 X: ...或[apk-devkit] N 个模块未加载，说明对应模块有问题（多为依赖缺失）， 工具数会少于 38 —— 这些行是正常的故障排查信息，不是多余的报错 - 会话中 AI 能列出
apk_decode、file_read、apkedit_decode等工具
若工具不可见，按顺序排查：
dsh --dump-config里根本没有apk-devkit行 →dsh.bundle.patch缺失或路径错，插件被当成普通依赖静默忽略 → 检查package.json的dsh.bundle.patch与files是否含cordis.patch.yml- 有 entry 但工具不可见
→
inject: ['tools']声明不全，loader 让 entry 一直waiting for service: X - 报
Cannot find module '@deepseek-ai/...'→ 有人往plugin.mjs里加了宿主包 import（禁止，见文件头注释） - 报
ERR_REQUIRE_ESM→"type": "commonjs"与宿主 ESM 冲突，见交接文档第十部分新发现 1 - 是否在
$DSH_HOME个人 patch 层重复 insert 了同一id（两层同 id 会导致 loader 组合失败）
关于
cordis.patch.yml的id：不必等于plugin.mjs导出的name。id是 patch 层用于定位/覆盖该行的键，name是模块说明符（包名或文件路径）。 将来若发布为@<scope>/apk-devkit，name必须同步改，id可不变。
| 依赖 | 版本 | 说明 |
|---|---|---|
| Windows | 10 / 11 | 当前唯一支持的平台 |
| Node.js | ≥ 18 | 推荐 20 LTS（fs.cp 在 Node 18 早期版本有符号链接循环卡死的 bug） |
| JDK | 17+ | java -version 必须可用（所有 jar 依赖它） |
放进 apk-devkit/tools/windows/，或设环境变量 APK_TOOLS_DIR 指向其所在目录
（如 Android SDK 的 build-tools\<ver>\）。
查找顺序：<tool>.exe → <tool>.bat / .cmd → <tool>.jar（走 java -jar）→ 系统 PATH。
APK_TOOLS_DIR指向的就是工具所在目录本身，不会再往下拼windows子目录。 例如指向 Android SDK 的build-tools\34.0.0\时，直接在该目录下找aapt2.exe。
apktool 解包 / 回编
aapt2 读取 APK 基本信息
apksigner 签名 / 验签
zipalign 对齐
baksmali DEX → smali
smali smali → DEX
d8 JAR → DEX
apkeditor 二进制资源（ARSC/XML）编辑，不依赖 aapt2
apkeditor 获取：
https://github.com/REAndroid/APKEditor/releases
下载后重命名为小写 apkeditor.jar 再放入（会自动走 java -jar）。
完整清单与放置规则见 tools/README.md。
未安装的工具，相关调用会返回明确报错与安装提示，不会静默失败。
sharp —— 图片模块（img_convert / img_resize）依赖它。该依赖在 package.json 中标为 optional；下面的安装命令主动省略可选依赖，因此默认不安装 sharp。不要把这一点解释成“Windows 没有预编译包”：sharp 官方安装文档列有 Windows x64 预编译包；本项目尚未在所有 Windows 架构上逐一验证。可参阅 sharp 官方平台与预编译二进制说明；官方清单不等于本项目在每种环境中的实测结果。
npm install --omit=optional # 跳过 sharp
npm i sharp # 需要图片模块时再单独装不装 sharp 不影响其余 36 个工具；两个图片工具仍会注册，但调用时会返回明确的 sharp 缺失提示。sharp 0.33.5 的 Node 运行时要求应以其包元数据为准；若使用 Node 18，至少应满足该版本声明的 18.17.0 要求。
| 变量 | 默认值 | 说明 |
|---|---|---|
APK_WORKSPACE |
./workspace |
工作区根目录，所有路径操作限定于此 |
APK_TOOLS_DIR |
./tools/windows |
外部工具目录；设置后直接使用该目录，不再拼接子目录 |
APK_KS_PASS |
— | 签名 keystore 密码（可选，通常由参数传入） |
APK_KEY_PASS |
— | 签名私钥密码 |
文件路径通过 lib/runner.js#guard 做词法路径与真实路径双重检查：拒绝 ../ 越界，并解析现存路径祖先以阻止 symlink/junction 指向 workspace 外部。ZIP 解压在全量预检阶段及每次写入前复核目标路径。该机制仍不是完整操作系统沙箱，无法消除检查与使用之间的 TOCTOU 竞态；不要让不可信本地进程同时修改 workspace。
| 模块 | 数量 | 工具 | 用途 |
|---|---|---|---|
| apk | 3 | apk_info |
读包名、版本、minSdk、权限 |
apk_decode |
解包到目录（出 smali） | ||
apk_build |
回编为未签名 APK | ||
| apkedit | 7 | apkedit_info |
深度信息：资源表/DEX/签名/语言/文件清单 |
apkedit_decode |
二进制资源解码为 json/xml | ||
apkedit_build |
重建 APK（自带 zipalign） | ||
apkedit_merge |
合并分割包（目录形式已可用；XAPK/APKM/APKS 待实测） | ||
apkedit_refactor |
混淆资源名反混淆 | ||
apkedit_xmlStrings |
打印 XML 字符串池（字符常量池） | ||
apkedit_xmlTree |
树形打印编译后 XML | ||
| sign | 3 | sign_apk |
V1/V2/V3 签名 |
sign_verify |
验签并输出证书 | ||
sign_align |
zipalign 对齐 | ||
| dex | 3 | dex_disassemble |
DEX → smali |
dex_assemble |
smali → DEX | ||
dex_jar2dex |
JAR → DEX | ||
| dex2jar | 1 | dex2jar_jar |
DEX → JAR（d2j-dex2jar） |
| diff | 2 | diff_files |
文本文件按行对比 |
diff_dirs |
目录递归对比 | ||
| zip | 4 | zip_list / zip_extract / zip_add / zip_remove |
压缩包增删改查 |
| file | 12 | file_read / file_write |
文本读写（自动剥 BOM） |
file_list |
列目录（AI 定位文件的眼睛） | ||
file_stat |
存在性/类型/大小/mtime | ||
file_delete / file_mkdir |
删除 / 建目录 | ||
file_copy / file_move / file_rename / file_batchRename |
复制/移动/改名 | ||
file_readHex / file_patch |
十六进制读写（对应"十六进制"功能） | ||
| img | 2 | img_convert / img_resize |
图片转换 / 缩放 |
| hash | 1 | hash_compute |
md5 / sha1 / sha256 |
npm run list-tools 输出完整清单（含 inputSchema）。
运行时若看到
[apk-devkit/apkedit] 注意：...，这是模块加载时的预期警告 （提示 APKEditor CLI 参数未经真机核实），不是错误。 JSON 结果正常输出到 stdout，不受影响；每个进程只打印一次。
改代码（smali）：
1. apk_decode 解包到 unpacked/
2. file_list 找到要改的 smali 文件
3. file_read / write 改内容
4. apk_build 回编为未签名 APK
5. sign_align → sign_apk → sign_verify
改资源（字符串/图标/ARSC）：
1. apkedit_decode 解码为可编辑 json
2. file_read / write 改 values-*/strings 等
3. apkedit_build 重建（自带 zipalign）
4. sign_apk → sign_verify
直接用自然语言让 DSH 完成，例如： 「把 workspace 里的 app.apk 解包，改完 AndroidManifest 后回编并签名」。
| plugin.mjs（主） | server.js（备用） | |
|---|---|---|
| 类型 | cordis 原生插件 | MCP stdio 服务 |
| 工具名 | apk_decode |
mcp__apk-devkit__apk_decode |
| 挂载 | 安装即生效 | 需手写 patch.yml 或 MCP 面板配置 |
| 渲染 | 有 output.render |
仅纯文本 |
两者共用同一套 orchestrator + modules，能力完全一致，可并存。
server.js 作为 bundle 支持不全时的退路保留。
MCP 协议版本 2024-11-05，实现 initialize / tools/list / tools/call。
功能缺口
file_read仅支持utf8/utf16le/latin1， GBK / GB18030 会读成乱码（老项目的res/values/strings.xml需注意）apkedit_merge的分割包合并：目录形式可用； XAPK / APKM / APKS 官方 README 声称支持，尚未实测
暂不提供
- 可视化编辑器面板、音视频播放、图片预览 —— 需 GUI，命令行工具给不了
- Linux 脚本 / 任意命令执行 —— 会击穿 workspace 沙箱
- DEX / RES 混淆对抗
工程限制
- ZIP 大文件（>100MB）处理有内存压力（
adm-zip全量读入） - 路径检查会拒绝可解析到 workspace 外部的 symlink/junction；但不是 OS 级沙箱，仍存在并发修改造成的 TOCTOU 边界
file_move跨盘（C:↔D:）会自动退化为「复制+删除」file_list单次最多返回 5000 条
详见交接文档第六、九、十部分。
本工具面向开发者对自己拥有权利或已获得明确授权的 Android APK 项目进行调试、 二次打包、签名与资源编辑。
禁止用途
- 未经授权破解、篡改或再分发第三方应用；
- 未经授权移除或规避技术保护措施、签名/许可/账号校验；
- 将工具用于侵犯他人知识产权、破坏计算机信息系统或其他违法行为。
具体行为是否违法取决于授权范围、技术措施性质、行为目的和实际影响；本项目说明不是法律意见，也不判断某一具体行为必然适用某一法条。
⚠️ 开源工具 ≠ 可以处理他人的 APK。 本工具调用的底层组件（APKEditor、Apktool、smali 等）均为 Apache-2.0 / BSD 等宽松许可的开源软件，这解决的是"你能不能用这个工具"； 而"你能不能用它去处理某个具体 APK"由《计算机软件保护条例》 与目标应用的用户协议约束，与工具是否开源无关。
本项目自研代码（orchestrator.js / server.js / plugin.mjs / lib/ / modules/） 采用 MIT 许可，见 LICENSE。
底层能力来自以下开源项目，本项目仅通过子进程调用其官方发布的 可执行文件或 jar，不复制、不翻译、不修改其源码，也不随本包分发：
| 项目 | 许可 | 用途 |
|---|---|---|
| REAndroid/APKEditor | Apache-2.0 | 二进制资源解码/回编/合并/反混淆 |
| REAndroid/ARSCLib | Apache-2.0 | 随 APKEditor 分发，本项目不直接调用 |
| iBotPeaches/Apktool | Apache-2.0 | 解包 / 回编 |
| JesusFreke/smali | BSD-3-Clause | DEX ↔ smali |
| AOSP（apksigner / zipalign / aapt2 / d8） | Apache-2.0 | 签名 / 对齐 / 信息 / JAR→DEX |
完整说明与致谢见 NOTICE。
lib/runner.js#guard同时检查词法路径和现存路径祖先的真实路径，可拒绝常见 symlink/junction 外逃；仍不等于 OS 级沙箱，TOCTOU 竞态无法仅靠路径检查彻底消除file_delete/file_move/file_copy拒绝操作 workspace 根目录file_rename/file_batchRename拒绝含路径分隔符的改名结果- 签名密码经环境变量中转，不出现在进程命令行
- Windows
.bat/.cmd调用会为参数加引号，并拒绝& | < > ^ ( ) % !、引号和换行等 cmd 元字符，避免把文件名/参数解释为 shell 命令；遇到拒绝时请改名或改用.exe/.jar server.js仅实现白名单方法（initialize / ping / tools/list / tools/call）- 子进程并发上限 2，防止 apktool / d8 吃满内存
已加固项（自动化测试覆盖的安全边界）
zip_extract/zip_add会校验压缩包内的条目名。 含../、绝对路径、盘符（C:\）的恶意条目，以及符号链接条目 （external_attr带S_IFLNK）会被整体拒绝 ——先全量校验再解压，不会留下半成品。zip_list的suspicious/isSymlink字段可在解压前先排查。- 指定
entries解压时按包内原始名匹配（也接受归一化名）。注：adm-zip 的
getEntry()对非最简条目名（含./）查不到， 本模块已自建索引 + 自己写文件绕开该限制。 - 子进程输出有 8MB 硬上限，超限会置
truncated标记， 防止 verbose 工具吐出几十 MB 打爆插件进程。 - 签名密码经
opts.env合并注入子进程，不再写入全局process.env， 并发签名互不干扰；命令行仍是--ks-pass env:APK_KS_PASS，密码不出现在 argv。
仍存在的边界
- 路径检查不是 OS 级沙箱，无法彻底消除检查与使用之间的 TOCTOU 竞态；不要让不可信本地进程同时修改 workspace。
file_rename/file_batchRename拒绝含路径分隔符的改名结果， 但不覆盖 TOCTOU 与外部进程抢先创建的同名文件。
⏱ 并发排队提示
- 长任务（
apk_build/apkedit_build/dex_disassemble，可达 10 分钟） 执行期间，短任务（hash_compute/file_read）会排队等待。 同一会话想并行做多件事时请留意。
MIT — 见 LICENSE