dsh-mobile 0.1.0-alpha.30 → 0.1.0-alpha.32

package/README.en.md

@@ -101,7 +101,33 @@ a session status panel, and a press-and-hold voice entry. Narrow screens only;
 do not modify the DSH source.
 ```
 
-Changes are applied to open Android and browser pages within a few seconds. Customization is not limited to colors: `mobile.js` can add navigation, shortcuts, dashboards, camera, voice, scanning, and complete interactions with same-origin DeepSeek Harness APIs.
+Changes are applied to open Android and browser pages within a few seconds. `mobile.css` and `mobile.js` own the phone UI, interactions, and orchestration of existing APIs; they cannot create computer files, run commands, or access computer hardware by themselves. Browsers fall back to available Web APIs, while the Android app exposes a narrow native bridge for file picking, camera capture, sharing, clipboard, notifications, and speech.
+
+### Add computer-side capabilities
+
+For a new capability on the computer, create an extension under `$DSH_HOME/mobile-access/extensions/<id>/`:
+
+```text
+extension.json   # metadata
+host.mjs         # trusted local Node.js code
+mobile.js        # optional phone-side script
+mobile.css       # optional phone-side styles
+assets/          # optional static files
+```
+
+Generate a complete starter extension with:
+
+```powershell
+dsh plugin --profile web exec dsh-mobile extension create media-tools --name "Media tools"
+```
+
+`host.mjs` can register schema-validated actions, ordinary HTTP/streaming/SSE routes, and teardown effects; `mobile.js` calls them through `api.host.invoke()` or `api.host.fetch()`. Extension source files can be changed only on the computer by the user or DSH; the phone has no endpoint that writes them. Closing Mobile Access, revoking a device, refreshing an extension, or stopping the gateway aborts its active requests.
+
+A published DSH plugin can also call `ctx.mobileAccess.registerExtension(definition)` from a Cordis effect. It shares the same authentication, routes, and client SDK as local directory extensions without modifying DSH core.
+
+Extension IDs are unique. Host code, scripts, and CSS switch as one generation; if a new generation fails, the previous one remains active. An empty `extensions/` directory is inert. Paired devices have every registered extension permission, so install and edit only trusted `host.mjs` code.
+
+Normal DSH community plugins continue to load through standard `dsh.client` and Slot contributions: conversation nodes, tool cards, settings sections, sidebar items, header actions, composer docks, and overlays remain available in the same session. Plugins that depend on hover, fixed desktop widths, system file pickers, or private DOM selectors need additional mobile adaptation.
 
 ## How it works
 
@@ -111,7 +137,7 @@ flowchart LR
   Gateway -->|"loopback proxy"| DSH["Stock DSH Web and Host"]
 ```
 
-The Host face owns discovery, pairing, HTTPS, and the proxy. The Client face replaces only the phone layout entry while reusing native feature plugins. Neither the DeepSeek Harness source nor its desktop page on port 3080 is modified.
+The three layers are: the Host face for discovery, pairing, HTTPS, loopback proxying, and extension registration; the Client face for the dedicated mobile root, multi-extension SDK, and hot updates; and the Android app for an exact-origin native bridge. Neither the DeepSeek Harness source nor its desktop page on port 3080 is modified.
 
 ## Security
 
@@ -125,7 +151,7 @@ See [SECURITY.md](SECURITY.md).
 
 | DSH Mobile | Verified DeepSeek Harness releases |
 | --- | --- |
-| `0.1.0-alpha.30` | `0.1.0-rc.5`, `0.1.0-rc.6`, `0.1.0-rc.7` |
+| `0.1.0-alpha.32` | `0.1.0-rc.5`, `0.1.0-rc.6`, `0.1.0-rc.7` |
 
 At startup, the plugin verifies the DSH Host version and the frontend dependencies required by the mobile layout. An unverified release fails with a clear error instead of serving a broken page. CI also tracks the DSH main branch layout slots and mobile semantic markers. If a DSH upgrade reports an incompatibility, update DSH Mobile first.
 

package/README.md

@@ -106,7 +106,33 @@ $DSH_HOME/mobile-access/mobile.js
 会话状态面板和长按语音入口。只影响窄屏，不修改 DSH 源码。
 ```
 
-保存后，已打开的 App 和浏览器通常会在几秒内应用变化。自定义不限于配色：`mobile.js` 可以添加导航、快捷操作、状态面板、相机、语音、扫码，以及调用同源 DSH API 的完整交互。
+保存后，已打开的 App 和浏览器通常会在几秒内应用变化。`mobile.css` 和 `mobile.js` 负责手机页面的样式、交互和已有 API 编排；它们不能单独创建电脑文件、运行命令或访问电脑硬件。浏览器按 Web API 能力降级，Android App 通过受限的原生 Bridge 提供文件选择、拍照、分享、剪贴板、通知和语音等能力。
+
+### 扩展电脑端能力
+
+需要手机调用新的电脑能力时，在 `$DSH_HOME/mobile-access/extensions/<id>/` 创建扩展：
+
+```text
+extension.json   # 元数据
+host.mjs         # 电脑端 Node.js 代码（可信本地代码）
+mobile.js        # 手机端脚本，可选
+mobile.css       # 手机端样式，可选
+assets/          # 静态资源，可选
+```
+
+可用命令生成模板：
+
+```powershell
+dsh plugin --profile web exec dsh-mobile extension create media-tools --name "媒体工具"
+```
+
+`host.mjs` 可以注册经过 Schema 校验的 Action、普通 HTTP/流式/SSE Route 和清理 Effect；`mobile.js` 通过 `api.host.invoke()` 或 `api.host.fetch()` 调用它们。扩展文件只能在电脑端由用户或 DSH 修改，手机没有写入这些文件的接口。Mobile Access 关闭、设备撤销、扩展刷新或网关关闭时，扩展请求会被中止。
+
+发布型 DSH 插件也可以在 Cordis effect 中调用 `ctx.mobileAccess.registerExtension(definition)`，与本地目录扩展共用认证、路由和客户端 SDK，不需要修改 DSH 核心。
+
+每个扩展的 `id` 必须唯一，Host、脚本和 CSS 会作为同一版本热切换；新版本加载失败时保留上一版本。空的 `extensions/` 目录不产生副作用。配对设备拥有所有已注册扩展的权限，因此只应安装和编辑自己信任的 `host.mjs`。
+
+普通 DSH 社区插件仍按标准 `dsh.client` 和 Slot 贡献加载：对话节点、工具卡、设置区、侧栏项、Header Action、Composer Dock 和 Overlay 会随同一会话同步。只有依赖鼠标悬停、固定桌面宽度、系统文件选择器或私有 DOM 的插件需要额外移动适配。
 
 ## 工作原理
 
@@ -117,7 +143,7 @@ flowchart LR
   DSH -->|"同一工作区、会话和事件流"| Phone
 ```
 
-插件包含两部分：Host face 提供发现、配对、HTTPS 和回环代理；Client face 替换移动端的布局入口，并复用原生功能插件。DeepSeek Harness 的源码和 3080 桌面页面都不会被修改，安装和卸载完全通过插件机制完成。
+插件包含三层：Host face 提供发现、配对、HTTPS、回环代理和扩展注册表；Client face 提供独立的移动根布局、多扩展 SDK 和热更新；Android App 提供精确 Origin 限定的原生 Bridge。DeepSeek Harness 的源码和 3080 桌面页面都不会被修改，安装和卸载完全通过插件机制完成。
 
 ## 安全
 
@@ -132,7 +158,7 @@ flowchart LR
 
 | DSH Mobile       | 已验证的 DeepSeek Harness                |
 | ------------------ | ------------------------------------------ |
-| `0.1.0-alpha.30` | `0.1.0-rc.5`、`0.1.0-rc.6`、`0.1.0-rc.7` |
+| `0.1.0-alpha.32` | `0.1.0-rc.5`、`0.1.0-rc.6`、`0.1.0-rc.7` |
 
 插件会在启动时检查 DSH Host 版本和移动布局所需的前端依赖；遇到未经验证的版本会直接给出错误，不会带着不兼容页面继续启动。CI 也会持续检查 DSH 主分支的布局插槽和移动端语义标记。升级 DSH 后如遇兼容提示，请先升级 DSH Mobile。
 

package/SECURITY.md

@@ -24,6 +24,8 @@ The maintainer will acknowledge a complete report within seven days. Publication
 - Do not expose the gateway directly to the public Internet.
 - Treat every paired device as a fully trusted operator. Stock DSH methods reached through the authenticated loopback proxy may read configuration or run tools with the desktop user's authority.
 - Treat `mobile.js` as application code with the paired page's same-origin authority. Restrict write access to trusted host-side DSH sessions and review generated API calls or browser-permission use.
+- Treat every extension `host.mjs` as a local program with the desktop user's Node.js privileges. It is never sandboxed and is not editable through the mobile gateway; only place code there that you trust.
+- Extension Actions and Routes receive filtered request data, a device identifier, and an abort signal. They cannot set proxy security headers or access the gateway's cookies, device tokens, CSRF tokens, or internal request headers.
 
 ## Known alpha limitation
 

package/lib/cli.js

@@ -6,6 +6,8 @@ import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { X509Certificate, createPrivateKey, createPublicKey } from "node:crypto";
 import { generate } from "selfsigned";
+import "@deepseek-ai/cordis";
+import "@deepseek-ai/schemastery";
 //#region src/managed-setup.ts
 const execFile$2 = promisify(execFile);
 const VIRTUAL_INTERFACE_MARKERS = [
@@ -253,6 +255,28 @@ async function refreshManagedServerCertificate(setup, address) {
 	});
 	await Promise.all([atomicWrite(setup.tls.certFile, server.cert), atomicWrite(setup.tls.keyFile, server.private)]);
 }
+Object.freeze({
+	manifest: 65536,
+	script: 1048576,
+	css: 524288,
+	asset: 8388608
+});
+/** A controlled business failure returned by an extension action or route. */
+var MobileExtensionError = class extends Error {
+	code;
+	status;
+	constructor(code, message, status = 400) {
+		super(message);
+		this.code = code;
+		this.status = status;
+		this.name = "MobileExtensionError";
+	}
+};
+/** Validate a stable extension id. */
+function assertExtensionId(value) {
+	if (typeof value !== "string" || !/^[a-z][a-z0-9-]{0,63}$/u.test(value)) throw new MobileExtensionError("invalid_manifest", "extension id is invalid");
+	return value;
+}
 //#endregion
 //#region src/cli.ts
 const execFile$1 = promisify(execFile);
@@ -407,6 +431,12 @@ async function setup(args) {
 			""
 		].join("\n"), { mode: 384 });
 	}
+	const extensions = join(directory, "extensions");
+	await mkdir(extensions, {
+		recursive: true,
+		mode: 448
+	});
+	await createExtensionScaffold(extensions, "custom", "自定义移动扩展", false);
 	const origin = `https://${network.address}:${String(options.port)}`;
 	await Promise.all([writeFile(join(directory, "setup.json"), `${JSON.stringify({
 		...managedSetup,
@@ -415,9 +445,69 @@ async function setup(args) {
 	console.log(`DSH Mobile follows ${network.name} and is currently configured for ${origin}`);
 	console.log(`Install this CA certificate on Android once: ${androidCertificate}`);
 	console.log(`Ask DSH to customize the mobile Web UI and features in: ${customCss} and ${customScript}`);
+	console.log(`Additional extensions live in: ${extensions}`);
 	console.log("Start DSH with: dsh --profile web");
 	console.log("Then open the Mobile card in the lower-left corner and create a pairing key.");
 }
+async function createExtensionScaffold(root, id, name, refuseExisting = true) {
+	assertExtensionId(id);
+	await mkdir(root, {
+		recursive: true,
+		mode: 448
+	});
+	const directory = join(root, id);
+	try {
+		await mkdir(directory, {
+			recursive: false,
+			mode: 448
+		});
+	} catch (error) {
+		if (error.code === "EEXIST" && !refuseExisting) return;
+		if (error.code === "EEXIST") throw new Error(`extension directory already exists: ${id}`);
+		throw error;
+	}
+	const files = {
+		"extension.json": `${JSON.stringify({
+			schemaVersion: 1,
+			id,
+			name,
+			version: "0.1.0",
+			description: "在手机端扩展 DSH"
+		}, null, 2)}\n`,
+		"host.mjs": `export default async function activate(api) {\n  api.action('hello', {\n    input: api.schema.object({ name: api.schema.string().max(80) }),\n    async run({ signal, deviceId }, input) {\n      void signal; void deviceId\n      return { message: \`Hello, \${input.name}\` }\n    },\n  })\n}\n`,
+		"mobile.js": `window.dshMobile?.define?.({\n  apiVersion: 1,\n  id: '${id}',\n  activate(api) {\n    return api.ui.registerSurface({\n      id: '${id}-page', placement: 'page', label: ${JSON.stringify(name)},\n      mount(container) {\n        container.textContent = ${JSON.stringify(`这是 ${name} 的移动页面。`)}\n        return () => container.replaceChildren()\n      },\n    })\n  },\n})\n`,
+		"mobile.css": `/* ${name.replaceAll("*/", "* /")} 的移动端样式。保存后通常会在几秒内刷新。 */\n`
+	};
+	try {
+		for (const [file, contents] of Object.entries(files)) await writeFile(join(directory, file), contents, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		await rm(directory, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	console.log(`Created extension: ${directory}`);
+}
+async function extensionCommand(args) {
+	const [subcommand, id, ...rest] = args;
+	if (subcommand !== "create" || id === void 0) throw new Error("usage: extension create <id> [--name <name>]");
+	let name = id;
+	for (let index = 0; index < rest.length; index += 1) {
+		if (rest[index] === "--name" && rest[index + 1] !== void 0) {
+			name = rest[index + 1];
+			index += 1;
+			continue;
+		}
+		throw new Error(`unknown extension option: ${rest[index] ?? ""}`);
+	}
+	if (name.length === 0 || name.length > 120 || /[\u0000-\u001f\u007f]/u.test(name)) throw new Error("--name is invalid");
+	await createExtensionScaffold(join(dshHome(), "mobile-access", "extensions"), id, name);
+}
 async function purge(args) {
 	if (args.length !== 1 || args[0] !== "--yes") throw new Error("purge requires --yes");
 	const home = dshHome();
@@ -431,6 +521,7 @@ async function purge(args) {
 function help() {
 	console.log([
 		"dsh-mobile setup [--address 192.168.x.x] [--port 3443] [--dsh-port 3080] [--no-firewall]",
+		"dsh-mobile extension create <id> [--name <name>]",
 		"dsh-mobile purge --yes",
 		"",
 		"Run through the DSH profile:",
@@ -440,6 +531,7 @@ function help() {
 async function main() {
 	const [command = "help", ...args] = process.argv.slice(2);
 	if (command === "setup") await setup(args);
+	else if (command === "extension") await extensionCommand(args);
 	else if (command === "purge") await purge(args);
 	else if (command === "help" || command === "--help" || command === "-h") help();
 	else throw new Error(`unknown command: ${command}`);