dsh-go-android-app 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keyboard3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# dsh-go-android-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`dsh-go-android-app` 是给 DSH Go 的 DeepSeek Harness 用的插件。把想做的 Android 应用告诉 Agent，先在手机上点图标预览，确认后生成签名 APK。装好的应用可以从手机桌面独立打开。
+
+## 快速开始
+
+以下步骤适用于 DSH Go 1.0.13 的本机引擎（DeepSeek Harness `0.2.2-rc.1`，Node.js 24.9 或更新版本）。先在 DSH Go 完成本机引擎初始化并配置可用的模型。
+
+### 安装插件
+
+插件还在等待 DSH Go 市场收录，现阶段可以直接安装 npm 的发布包。[查看上架进度](https://github.com/ccch1mneyyy/dsh-go-market/pull/39)
+
+把下面这条命令发给 DSH Go 本机聊天里的 Agent，请它执行。也可以在 DSH Go 的本机终端直接运行。弹出审批时，核对命令后选「仅允许一次」。
+
+```sh
+dsh plugin --profile web add https://registry.npmjs.org/dsh-go-android-app/-/dsh-go-android-app-0.1.1.tgz
+```
+
+安装成功后，在 DSH Go 的「引擎」页重启本机引擎，让插件生效。[DSH Go 主机与安装指南](https://github.com/ccch1mneyyy/dsh-Go/blob/v1.0.13/docs/plugins/hosts.md)
+
+### 做第一个应用
+
+在 DSH Go 新开一个本机聊天，选择工作区，然后直接说你想做什么。
+
+> 我想做一个叫「随身跑记」的跑步计时器。能开始、暂停和结束计时，并记住每次跑了多久。
+
+1. 在同一台手机上点聊天里的「打开手机桌面预览」，再点 **随身跑记** 的图标。可以回到聊天继续提修改意见。
+2. 满意后在同一聊天里回复「确认打包」。首次构建可能需要确认下载 Android 工具和接受 SDK 许可，见[配置构建环境](#配置构建环境)。
+3. 打开 Agent 返回的 APK 文件卡或链接，按 Android 安装器的提示安装，再从手机桌面打开应用。
+
+## 从想法到 APK
+
+下面是「随身跑记」的完整实战案例。它在 Android 手机上用 DSH Go 构建并安装，另外接入了 GPS 和 Health Connect。当时发给 DSH Go 的需求如下。
+
+> 直接在这台真机做一个中文原生 Android App「随身跑记」。需求：从 Health Connect 经用户授权读取今日总步数和最近跑步记录；用户点击开始后用手机 GPS 记录用时、距离和平均配速，结束后保存到本机并在 App 里查看。
+
+1. 先请 DSH Go 用插件预览「随身跑记」的离线界面。打开手机桌面预览，点橙色的 **随身跑记** 图标进入应用预览。
+2. 确认界面后，在同一 DSH Go 会话里要求 **用 Android SDK 构建并签名随身跑记的原生 APK**。打开 APK，在 Android 安装器确认安装。
+3. 打开随身跑记，按系统提示授权后开始跑步。结束时保存记录，可以回看用时、距离、平均配速和轨迹。
+
+| 手机桌面预览 | 点图标进入应用预览 | 安装后记录跑步 |
+| --- | --- | --- |
+| <img src="docs/images/runlog-launcher.webp" width="230" alt="手机桌面预览上的橙色随身跑记图标"> | <img src="docs/images/runlog-preview.webp" width="230" alt="从桌面图标打开的随身跑记浏览器预览"> | <img src="docs/images/runlog-recording.webp" width="230" alt="随身跑记的跑步计时、距离、平均配速和轨迹"> |
+
+桌面预览由插件生成，点开的是原 APK 中的页面。浏览器预览中的健康数据是示例数据。安装后的跑步画面来自 Android 14 模拟器，轨迹使用模拟定位。Health Connect 和 GPS 由 DSH Go 在原生构建阶段接入，目前尚未接入插件模板。
+
+## 配置构建环境
+
+DSH Go 的 ARM64 PRoot 环境如果使用 glibc 2.38 或更新版本，可以在第一次确认构建时自动配置。请使用能显示审批提示的会话权限，例如「工作区内修改」。确认框会提示下载缺少的工具并接受 [Android SDK 许可](https://developer.android.com/studio/terms)。
+
+插件会复用已有的 JDK 和 SDK，从固定的上游地址补齐缺少的组件。空环境首次下载约 330 MB。安装前验证下载大小和 SHA-256，试编译并验证一个临时 APK 后保存配置。以后构建复用已配置的工具。[工具链清单](lib/toolchain-sources.json)
+
+也可以在 DSH Go 终端提前配置。默认 DSH Home 是 `~/.dsh`，如果你的安装位置不同，请调整 `PLUGIN`。
+
+```sh
+PLUGIN="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/dsh-go-android-app"
+node "$PLUGIN/bin/dsh-go-android-app.js" setup --accept-android-sdk-license
+node "$PLUGIN/bin/dsh-go-android-app.js" doctor
+```
+
+已有工具链时，可用 `configure` 指定实际路径。需要 JDK 17 或更新版本、Android API 34 的 `android.jar`、本机架构的 `aapt2` 和 `zipalign`，以及 `d8.jar` 和 `apksigner.jar`。
+
+```sh
+node "$PLUGIN/bin/dsh-go-android-app.js" configure \
+  /path/to/jdk /path/to/build-tools-bin /path/to/android.jar /path/to/tool-jars
+```
+
+标准桌面 SDK 布局也可通过 `JAVA_HOME` 和 `ANDROID_HOME` 定位 Build Tools 34.0.0 及 API 34。配置和本地签名密钥保存在 `~/.local/share/dsh-go-app/`，可用 `DSH_GO_APP_HOME` 指定目录。
+
+## 查阅 Android API
+
+`dsh_app_android_docs` 先从 `developer.android.com` 读取 API 参考。访问失败或正文缺少目标声明时，再尝试 `developer.android.google.cn` 的同路径和锚点，并返回实际来源。为插件项目传入 `projectId`，可以用当前构建 SDK 的 `android.jar` 核对平台 API 签名。AndroidX 用法按项目解析出的依赖版本核对，权限和运行条件查对应的官方文档。
+
+## 插件工作流
+
+1. Harness 先用 `dsh_app_doctor` 检查所需能力，再创建 `dsh-apps/<项目 ID>/`，生成 `index.html` 和桌面图标 `icon.json`。需要三轴陀螺仪时，声明 `gyroscope` 就会选中 `gyroscope-webview`，由 Android 原生读取角速度，WebView 显示数据。相机、定位和 Health Connect 等会列为当前模板不支持的能力。
+2. 在 Harness 聊天里点「打开手机桌面预览」，再点 App 图标进入应用。没有图标的项目会直接提供应用预览入口。使用 DSH Go 的本机引擎时，请在这台手机上打开。看完后回复修改意见或确认打包。链接有效期为 15 分钟，过期后回复「刷新预览」。陀螺仪的实时数据与硬件可用性可在目标设备安装 APK 后验证。
+3. 确认打包后，插件检查页面、图标和模板是否与预览一致，构建并验证 APK。如果当前会话禁止弹出审批，切换到「工作区内修改」等会显示审批提示的模式再试。有 `present` 时，在聊天里点 APK 文件卡打开 Android 安装器。其他客户端可使用返回的文件链接。
+4. 要更新应用，继续使用原项目。保留 `app.json`、`dist/` 和原签名密钥，插件会递增版本号并使用同一包名和签名，支持覆盖安装。
+
+桌面图标预览会在模拟手机壁纸上显示 App 名称和圆角图标，点图标即可打开同一版本的应用预览。图标会打包为 Android 自适应图标，最终轮廓由设备的启动器决定。旧项目可以在原目录补上 `icon.json`，再预览和打包。
+
+插件使用 Android Activity 和 WebView 运行单文件 HTML、CSS、JavaScript，支持 `localStorage`。陀螺仪模板在前台采样，通过页面同源的 `GET /gyroscope.json` 提供 X/Y/Z 角速度（rad/s）和开机后的采样时间。GPS、Health Connect、通用 Gradle 项目和自动设备测试属于后续能力。生成 APK 使用本地开发签名，适合直接安装试用。
+
+## 从源码安装
+
+在仓库根目录执行 `npm pack`。若在电脑上打包，先把生成的 `.tgz` 文件传到手机，再在 DSH Go 的本机终端运行下列命令。把路径和文件名换成实际的打包结果。
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-go-android-app-0.1.1.tgz
+```
+
+安装后重启 DSH Go 的本机引擎。[DSH Go 插件开发指南](https://github.com/ccch1mneyyy/dsh-Go/blob/v1.0.13/docs/plugins/from-zero.md)
+
+## 从旧名称迁移
+
+旧包名是 `dsh-go-app`。在 DSH Go 本机终端移除旧包，再安装新包，然后重启本机引擎。
+
+```sh
+dsh plugin --profile web remove dsh-go-app
+dsh plugin --profile web add https://registry.npmjs.org/dsh-go-android-app/-/dsh-go-android-app-0.1.1.tgz
+```
+
+继续使用原工作区里的项目即可。新包沿用 `~/.local/share/dsh-go-app/` 中的工具链配置和签名密钥，以及 `DSH_GO_APP_HOME` 等已有环境变量，便于继续构建和覆盖安装已有应用。
+
+**开发预览。** 已验证桌面 Harness 加载插件和签名构建，以及 Android 模拟器覆盖安装后保留应用数据。另在一台 Android 16 真机上通过 DSH Go 完成了陀螺仪模板选择、页面生成、预览、签名、安装和实时采样。

package/bin/dsh-go-android-app.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { buildApk, configureToolchain } from '../lib/android.js'
+import { createPreviewManager, createProject, readProject } from '../lib/project.js'
+import { inspectToolchain, setupToolchain } from '../lib/setup.js'
+
+const help = `dsh-go-android-app doctor
+dsh-go-android-app setup --accept-android-sdk-license
+dsh-go-android-app configure JAVA_HOME SDK_TOOLS ANDROID_JAR TOOL_JARS
+dsh-go-android-app create PROJECT_ID "App name"
+dsh-go-android-app preview PROJECT_ID
+dsh-go-android-app build PROJECT_ID PREVIEW_SHA256`
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2)
+  const workspace = process.cwd()
+  switch (command) {
+    case 'doctor':
+      if (args.length === 0) {
+        const { ready, detail } = await inspectToolchain()
+        if (!ready) throw new Error(detail)
+        return { ready: true }
+      }
+      break
+    case 'setup':
+      if (args.length === 0 || (args.length === 1 && args[0] === '--accept-android-sdk-license')) {
+        return setupToolchain({ acceptAndroidSdkLicense: args.length === 1 })
+      }
+      break
+    case 'configure':
+      if (args.length === 4) {
+        const [javaHome, sdkTools, androidJar, toolJars] = args
+        return configureToolchain({ javaHome, sdkTools, androidJar, toolJars })
+      }
+      break
+    case 'create':
+      if (args.length === 2) return createProject(workspace, args[0], args[1])
+      break
+    case 'preview':
+      if (args.length === 1) {
+        const preview = createPreviewManager()
+        const { url, iconUrl, sha256 } = await preview.open(await readProject(workspace, args[0]))
+        process.once('SIGINT', () => preview.close())
+        process.once('SIGTERM', () => preview.close())
+        return { url, iconUrl, sha256 }
+      }
+      break
+    case 'build':
+      if (args.length === 2) return buildApk(await readProject(workspace, args[0]), args[1])
+      break
+    case undefined:
+    case '--help':
+      console.log(help)
+      return
+  }
+  throw new Error(help)
+}
+
+try {
+  const output = await main()
+  if (output) console.log(JSON.stringify(output, null, 2))
+} catch (error) {
+  console.error(error.message)
+  process.exitCode = 1
+}

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-go-android-app
+      name: dsh-go-android-app

package/lib/android/GyroscopeActivity.java

@@ -0,0 +1,75 @@
+package app.dshgo.shell;
+
+import android.hardware.Sensor;
+import android.hardware.SensorEvent;
+import android.hardware.SensorEventListener;
+import android.hardware.SensorManager;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+
+public final class GyroscopeActivity extends MainActivity implements SensorEventListener {
+    private static final String SAMPLE_URL = PAGE_ORIGIN + "/gyroscope.json";
+    private static final String INACTIVE = "{\"status\":\"inactive\"}";
+
+    // The listener runs on the main thread. WebView reads an immutable snapshot on its worker.
+    private volatile String snapshot = INACTIVE;
+    private SensorManager activeManager;
+
+    @Override
+    protected void onResume() {
+        super.onResume();
+        SensorManager manager = getSystemService(SensorManager.class);
+        Sensor sensor = manager == null ? null : manager.getDefaultSensor(Sensor.TYPE_GYROSCOPE);
+        if (sensor == null) {
+            snapshot = "{\"status\":\"unavailable\"}";
+            return;
+        }
+        snapshot = "{\"status\":\"waiting\"}";
+        if (manager.registerListener(this, sensor, SensorManager.SENSOR_DELAY_UI)) {
+            activeManager = manager;
+        } else {
+            snapshot = "{\"status\":\"error\"}";
+        }
+    }
+
+    @Override
+    protected void onPause() {
+        if (activeManager != null) {
+            activeManager.unregisterListener(this);
+            activeManager = null;
+        }
+        snapshot = INACTIVE;
+        super.onPause();
+    }
+
+    @Override
+    public void onSensorChanged(SensorEvent event) {
+        if (activeManager == null) return;
+        float x = event.values[0];
+        float y = event.values[1];
+        float z = event.values[2];
+        if (!Float.isFinite(x) || !Float.isFinite(y) || !Float.isFinite(z)) return;
+        snapshot = "{\"status\":\"active\",\"x\":" + x + ",\"y\":" + y + ",\"z\":" + z
+            + ",\"timestampNanos\":\"" + event.timestamp + "\"}";
+    }
+
+    @Override
+    public void onAccuracyChanged(Sensor sensor, int accuracy) {
+    }
+
+    @Override
+    String pagePolicy() {
+        return super.pagePolicy() + "; connect-src " + SAMPLE_URL;
+    }
+
+    @Override
+    WebResourceResponse localResource(WebResourceRequest request) {
+        if (!"GET".equals(request.getMethod()) || !SAMPLE_URL.equals(request.getUrl().toString())) return null;
+        return new WebResourceResponse("application/json", "UTF-8", 200, "OK",
+            Collections.singletonMap("Cache-Control", "no-store"),
+            new ByteArrayInputStream(snapshot.getBytes(StandardCharsets.UTF_8)));
+    }
+}

package/lib/android/MainActivity.java

@@ -0,0 +1,89 @@
+package app.dshgo.shell;
+
+import android.app.Activity;
+import android.content.res.AssetManager;
+import android.os.Bundle;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import android.webkit.WebSettings;
+import android.webkit.WebView;
+import android.webkit.WebViewClient;
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.util.Collections;
+
+public class MainActivity extends Activity {
+    static final String PAGE_ORIGIN = "https://appassets.androidplatform.net";
+    private static final String PAGE = PAGE_ORIGIN + "/index.html";
+    private static final String PAGE_POLICY =
+        "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; "
+        + "img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+    private WebView webView;
+
+    @Override
+    public void onCreate(Bundle state) {
+        super.onCreate(state);
+        webView = new WebView(this);
+        WebSettings settings = webView.getSettings();
+        settings.setJavaScriptEnabled(true);
+        settings.setDomStorageEnabled(true);
+        settings.setAllowFileAccess(false);
+        settings.setAllowContentAccess(false);
+        settings.setMixedContentMode(WebSettings.MIXED_CONTENT_NEVER_ALLOW);
+        webView.setWebViewClient(new AppPageClient(this));
+        setContentView(webView);
+        webView.loadUrl(PAGE);
+    }
+
+    String pagePolicy() {
+        return PAGE_POLICY;
+    }
+
+    WebResourceResponse localResource(WebResourceRequest request) {
+        return null;
+    }
+
+    private static final class AppPageClient extends WebViewClient {
+        private final MainActivity activity;
+        private final AssetManager assets;
+
+        AppPageClient(MainActivity activity) {
+            this.activity = activity;
+            this.assets = activity.getAssets();
+        }
+
+        @Override
+        public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
+            return true;
+        }
+
+        @Override
+        public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
+            if (request.isForMainFrame() && PAGE.equals(request.getUrl().toString())) {
+                try {
+                    return new WebResourceResponse("text/html", "UTF-8", 200, "OK",
+                        Collections.singletonMap("Content-Security-Policy", activity.pagePolicy()),
+                        assets.open("index.html"));
+                } catch (IOException unavailable) {
+                    return emptyResponse(404, "Not Found");
+                }
+            }
+            if (!request.isForMainFrame()) {
+                WebResourceResponse resource = activity.localResource(request);
+                if (resource != null) return resource;
+            }
+            return emptyResponse(403, "Forbidden");
+        }
+    }
+
+    private static WebResourceResponse emptyResponse(int status, String reason) {
+        return new WebResourceResponse("text/plain", "UTF-8", status, reason,
+            Collections.emptyMap(), new ByteArrayInputStream(new byte[0]));
+    }
+
+    @Override
+    protected void onDestroy() {
+        if (webView != null) webView.destroy();
+        super.onDestroy();
+    }
+}

package/lib/android/gyroscope.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<html lang="zh-CN">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{APP_NAME}}</title>
+<style>
+  body { margin: 0; background: #f5f8f6; color: #19332b; font: 1rem system-ui, sans-serif; }
+  main { max-width: 32rem; margin: 2rem auto; padding: 1.5rem; }
+  h1 { margin: 0 0 1rem; }
+  p { line-height: 1.5; }
+  dl { padding: 1rem 1.25rem; border-radius: .75rem; background: white; }
+  dl div { display: flex; justify-content: space-between; align-items: baseline; padding: .6rem 0; }
+  dd { margin: 0; font-size: 1.5rem; font-variant-numeric: tabular-nums; }
+</style>
+<main>
+  <h1>{{APP_NAME}}</h1>
+  <p id="status" role="status">正在准备采样</p>
+  <dl aria-label="三轴角速度，单位弧度每秒">
+    <div><dt>X 轴</dt><dd id="x">—</dd></div>
+    <div><dt>Y 轴</dt><dd id="y">—</dd></div>
+    <div><dt>Z 轴</dt><dd id="z">—</dd></div>
+  </dl>
+  <p>角速度单位为 rad/s。转动手机，观察各轴的读数。</p>
+  <p id="timestamp"></p>
+</main>
+<script>
+  const status = document.getElementById('status')
+  const timestamp = document.getElementById('timestamp')
+  const axes = ['x', 'y', 'z']
+  const messages = {
+    active: '正在读取原生陀螺仪',
+    waiting: '正在等待陀螺仪数据',
+    inactive: '采样已暂停',
+    unavailable: '这台设备没有可用的陀螺仪',
+    error: '无法读取陀螺仪',
+  }
+
+  function render(sample) {
+    const message = messages[sample.status] || messages.error
+    if (status.textContent !== message) status.textContent = message
+    const active = sample.status === 'active'
+    for (const axis of axes) {
+      document.getElementById(axis).textContent = active ? sample[axis].toFixed(4) : '—'
+    }
+    timestamp.textContent = active ? '采样时间（开机后 ns）' + sample.timestampNanos : ''
+  }
+
+  async function refresh() {
+    try {
+      if (!document.hidden) {
+        const response = await fetch('/gyroscope.json', { cache: 'no-store' })
+        if (!response.ok) throw new Error('Sensor reading unavailable')
+        render(await response.json())
+      }
+    } catch {
+      render({ status: 'error' })
+    } finally {
+      setTimeout(refresh, 150)
+    }
+  }
+
+  if (location.origin === 'https://appassets.androidplatform.net') {
+    refresh()
+  } else {
+    status.textContent = '浏览器预览。安装 APK 后可读取真机数据。'
+  }
+</script>
+</html>

package/lib/android-docs.js

@@ -0,0 +1,134 @@
+import { execFile } from 'node:child_process'
+import { isAbsolute, join } from 'node:path'
+import { promisify } from 'node:util'
+import { formatFetchOutput } from '@deepseek-ai/dsh-tool-web'
+import { DEFAULT_USER_AGENT, HttpFetchProvider } from '@deepseek-ai/dsh-web-fetch-http'
+import { toolchainCandidates } from './android.js'
+
+const run = promisify(execFile)
+const hosts = ['developer.android.com', 'developer.android.google.cn']
+const maxExcerpt = 12_000
+const identifier = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/
+const docsWeb = new HttpFetchProvider({
+  // Devsite puts a large navigation tree before the reference article.
+  maxResponseBytes: 8_000_000,
+  maxBodyChars: 8_000_000,
+  timeoutMs: 25_000,
+  maxRedirects: 3,
+  userAgent: DEFAULT_USER_AGENT,
+})
+
+function normalizeAnchor(value) {
+  try {
+    value = decodeURIComponent(value)
+  } catch {
+    // A literal percent sign can appear in an HTML heading ID.
+  }
+  return value.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&').replace(/\s/g, '')
+}
+
+function findSection(body, symbol, fragment) {
+  if (body.kind === 'text') {
+    if (fragment) return undefined
+    const heading = [...body.content.matchAll(/^#{1,6}\s+([^\r\n]+)$/gm)].find((match) => match[1].replaceAll('`', '').trim() === symbol)
+    if (!heading) return undefined
+    return { content: body.content.slice(heading.index, heading.index + maxExcerpt), kind: 'text' }
+  }
+
+  const start = body.content.indexOf('<div class="devsite-article-body')
+  if (start === -1) return undefined
+  const end = body.content.indexOf('</devsite-article>', start)
+  const article = body.content.slice(start, end === -1 ? undefined : end)
+  const headings = [...article.matchAll(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi)]
+  const matches = []
+  for (const [index, heading] of headings.entries()) {
+    const anchor = heading[2].match(/\bid=["']([^"']+)["']/i)?.[1]
+    const label = heading[3].replace(/<[^>]*>/g, '').trim()
+    const named = label === symbol || label.endsWith('.' + symbol)
+    const matched = named && (!fragment || (anchor && normalizeAnchor(anchor) === fragment))
+    if (!matched) continue
+    const next = headings[index + 1]?.index ?? article.length
+    matches.push(article.slice(heading.index, Math.min(next, heading.index + maxExcerpt)))
+    if (fragment || matches.length === 3) break
+  }
+  if (!matches.length) return undefined
+  return { content: matches.join('\n'), kind: 'html' }
+}
+
+export async function lookupAndroidReference({ url, api }, signal, web = docsWeb) {
+  const requested = new URL(url)
+  if (requested.protocol !== 'https:' || !hosts.includes(requested.host)
+    || requested.username || requested.password || !requested.pathname.startsWith('/reference/')) {
+    throw new Error('Supply an HTTPS Android API reference URL on developer.android.com or developer.android.google.cn.')
+  }
+  if (!identifier.test(api) || api.length > 160) throw new Error('Supply an API class, method, or field name.')
+  const symbol = api.split('.').at(-1)
+  const fragment = normalizeAnchor(requested.hash.slice(1))
+  const language = requested.searchParams.get('hl')
+  requested.search = ''
+  if (language && /^[a-z]{2,3}(?:-[a-zA-Z]{2,4})?$/.test(language)) requested.searchParams.set('hl', language)
+  const attempts = []
+  for (const host of hosts) {
+    signal?.throwIfAborted()
+    requested.hostname = host
+    const source = requested.href
+    try {
+      const page = await web.fetch({ url: source }, signal)
+      const finalUrl = new URL(page.url)
+      if (page.statusCode < 200 || page.statusCode >= 300) {
+        attempts.push(`${source} returned HTTP ${page.statusCode}.`)
+        continue
+      }
+      if (finalUrl.protocol !== 'https:' || !hosts.includes(finalUrl.host) || !finalUrl.pathname.startsWith('/reference/')) {
+        attempts.push(`${source} redirected outside the official Android reference hosts.`)
+        continue
+      }
+      const section = findSection(page.body, symbol, fragment)
+      if (!section) {
+        const result = page.truncated ? 'The response was incomplete' : 'No matching reference section was found'
+        attempts.push(`${source}: ${result} for ${api}.`)
+        continue
+      }
+      finalUrl.hash = requested.hash
+      const excerpt = formatFetchOutput({ ...page, url: finalUrl.href, body: section }, maxExcerpt)
+      return { found: true, source: finalUrl.href, excerpt, attempts }
+    } catch (error) {
+      signal?.throwIfAborted()
+      attempts.push(`${source}: ${String(error.message).slice(0, 250)}`)
+    }
+  }
+  return { found: false, attempts }
+}
+
+export async function verifyPlatformDeclaration(url, api, signal) {
+  const path = new URL(url).pathname.replace(/^\/reference\/(?:kotlin\/)?/, '')
+  if (!path.startsWith('android/')) return undefined
+  const className = path.replaceAll('/', '.')
+  if (!identifier.test(className)) return undefined
+  let config
+  try {
+    config = await toolchainCandidates()
+  } catch (error) {
+    return `Could not read the project SDK configuration: ${String(error.message).slice(0, 250)}`
+  }
+  const { javaHome, androidJar } = config
+  if (!javaHome || !androidJar || !isAbsolute(javaHome) || !isAbsolute(androidJar)) {
+    return 'The project SDK is unavailable. Verify the signature after configuring the build tools.'
+  }
+  try {
+    const { stdout } = await run(join(javaHome, 'bin', 'javap'), ['-public', '-classpath', androidJar, className], {
+      signal, timeout: 5_000, maxBuffer: 256 * 1024,
+    })
+    const symbol = api.split('.').at(-1)
+    const declaration = symbol === className.split('.').at(-1)
+      ? /\b(class|interface|enum)\b/
+      : new RegExp(`\\b${RegExp.escape(symbol)}(?=\\(|\\s*[;=])`)
+    const lines = stdout.split('\n').map((line) => line.trim()).filter((line) => declaration.test(line))
+    return lines.length
+      ? `Public declarations in ${androidJar}:\n${lines.slice(0, 6).join('\n')}`
+      : `No direct declaration matched in ${androidJar}. Check inherited members and exact overloads.`
+  } catch (error) {
+    signal?.throwIfAborted()
+    return `Could not verify ${className} against ${androidJar}: ${String(error.stderr || error.message).trim().slice(0, 250)}`
+  }
+}