前言¶
在 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 即可。
