前言¶
在 DSH 里给智能体查 Android 系统实现时，常见做法是本机 git clone 整棵 AOSP，或依赖能访问 github.com 的 API。实际环境里往往又不一样：github.com 页面和 API 不通，但 codeload.github.com 还能下包；国内 AOSP git 镜像 git fetch 长时间无进展；手机上也没有 Python，repo 工具用不了。编译整套 AOSP 更不现实（需要 x86_64 Linux、数百 GB 磁盘和大内存）。
dsh-aosp（维护者 Verchiel666，分类为联网工具）走另一条路：从 GitHub aosp-mirror 组织用 codeload tar 快照 拉单个镜像仓，系统 tar 解包，再用 ripgrep 在本机已落地源码里搜索。不需要 root、不需要 git、不编译。npm 包当前版本为 0.2.0，许可证 MIT；GitHub 仓库星标为 0。
下面介绍它做什么、怎么装、怎么用，以及已知边界。
这是什么¶
dsh-aosp 是 DeepSeek Harness（DSH）下的联网工具类插件。它在 DSH 进程里注册一组只读/写盘工具：下载并解包 AOSP 镜像项目、列出已落地模块、正则搜索、按模块聚合 grep、增量更新、启发式调用链追踪、按行读文件。默认落地目录为 $HOME/work/aosp-src，可与手工放置的源码共用。
插件声明能力包括 tools:register、network:egress、subprocess、fs:write；aosp_fetch 等写盘操作会走审批。安装前建议自行查看 GitHub 源码 与许可证，插件以当前 DSH 进程权限运行。
为什么用 tar 快照而不是 git¶
维护者在 README 中说明的典型约束包括：
github.com不通，但api.github.com/codeload.github.com可达；- 部分国内 AOSP git 镜像
git fetch会卡死； - 无 Python，无法使用
repo。
GitHub 上 aosp-mirror 镜像了 AOSP 主要项目（如 frameworks/base、packages/apps/*、system/core、bionic、build、external/* 等约 100 个仓）。流程为 tar 快照 → 解包 → ripgrep。README 记载实测下载约 3–12 MB/s，packages/apps/Settings 约 46 MB、7 秒完成一类场景。
核心工具¶
| 工具 | 风险 | 作用 |
|---|---|---|
aosp_list |
只读 | 列出已落地模块（大小/文件数/ref/sha）；默认用缓存，refresh:true 才重扫 |
aosp_fetch |
写盘 | 下载并解包一个项目；ref 可为分支或 tag（如 android-14.0.0_r1） |
aosp_search |
只读 | 在已落地源码里用 ripgrep 搜正则，可限定 glob、带上下文 |
aosp_grep |
只读 | 跨模块正则，一次 rg，结果按模块聚合 |
aosp_update |
写盘 | 增量更新：比对远端 commit，只拉改动文件 |
aosp_trace |
只读 | 给函数名，沿调用或被调用方向钻 1–3 层；通用名自动不展开 |
aosp_read |
只读 | 按行读源码（带行号，最多 400 行） |
aosp_fetch 会触发写盘审批，单仓体积可能达数百 MB。
安装与启用¶
官方 README 给出的安装方式为 npm：
npm i dsh-aosp
DSH 引擎要求见 package.json：engines.dsh 为 >=0.2.0。
在 Cordis 配置中可插入插件并设置目录与 ripgrep 路径：
- insert:
- id: aosp
name: dsh-aosp
config:
rootDir: '' # 默认 $HOME/work/aosp-src
rgPath: '' # 默认 App 自带 bin/rg
rootDir 为空时使用 $HOME/work/aosp-src；rgPath 为空时使用应用自带 bin/rg。
典型用法¶
在 DSH 对话或工具调用中，参数为 JSON。README 示例：
aosp_fetch {"project":"frameworks/base"}
aosp_fetch {"project":"packages/apps/Settings","ref":"android-14.0.0_r1"}
aosp_search {"pattern":"class ActivityManagerService","glob":"*.java"}
aosp_grep {"pattern":"zygote_socket","maxPerModule":3}
aosp_grep {"pattern":"IPCThreadState","glob":"*.cpp","modules":["system_core"]}
aosp_update {"module":"frameworks_base"}
aosp_trace {"symbol":"attachApplicationLocked","direction":"both","depth":2}
aosp_read {"path":"frameworks_base/services/core/java/com/android/server/am/ActivityManagerService.java","offset":520,"limit":40}
建议顺序：先用 aosp_fetch 拉需要的 project，再用 aosp_search / aosp_grep 定位符号，用 aosp_read 看片段，用 aosp_trace 粗看调用关系；远端有更新时用 aosp_update，改动过大时按提示 aosp_fetch 并 force:true 整包重下。
增量更新与性能¶
aosp_fetch 会解析 ref 的 commit sha，按 sha 下包，并把 sha 写入 <root>/.dsh-aosp.json。aosp_update 流程简述：
- 查远端 HEAD sha，相同则返回已是最新（零下载）；
- 不同则调 GitHub compare API 取改动清单；
- 删除类直接删本地文件，新增/修改/改名通过 jsDelivr（
gcore.jsdelivr.net/gh/aosp-mirror/<repo>@<sha>/<path>）按 commit 取单文件； - 改动文件数超过默认上限 300 时，提示改用
aosp_fetch force:true整包重下。
老版本落地且 meta 里没有 sha 的模块不能增量，需重新 aosp_fetch。
README 记载：aosp_list 默认读缓存约 14 ms；强制 refresh:true 重扫大量文件需数分钟。解包 frameworks/base（约 5.6 万文件 / 1.8 GB）曾测约 551 秒，而小仓如 packages/apps/Settings 解包约 2.1 秒——小文件越多解包越慢；tar 超时设为 30 分钟，下载失败自动重试 3 次。
适用场景与注意¶
适合：需要在 DSH 智能体流程里快速查 AOSP Java/C++ 实现、跨模块找符号、在 github.com 不通但 codeload 可达的环境下做只读源码分析。
边界（来自 README「已知边界」）：
- 镜像数据截至约 2025-11-12（约 Android 15/16），与最新 Android 有漂移；
- 仅约 100 个仓，例如
frameworks/native（libbinder 原生实现）不在其中； - 只读源码，不编译。
社区目录页：SkillHub - dsh-aosp。DSH 生态是「一切皆插件」；SkillHub 为社区独立站点，与 DeepSeek / 幻方无官方从属关系。问题与贡献可走 GitHub Issues。
结尾¶
经过上面的步骤可以看出：dsh-aosp 把 AOSP 镜像仓收成可下载的 tar 快照，在本机用 ripgrep 完成搜索与阅读，并支持按 commit 的增量更新，针对 git/API 不可用、又不打算整机构建 AOSP 的场景。若要接入，从 npm i dsh-aosp 与 rootDir 配置开始，再按项目粒度 aosp_fetch 即可。
