dsh-root-bridge 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,63 @@
1
- # Temporary Holding Version
1
+ # dsh-root-bridge(DSH 插件)
2
2
 
3
- 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.
3
+ 在 DSH 里以**真正的 root** 执行 Android 侧命令,绕开 proot 容器的假 root。
4
+
5
+ 它给模型一个 `root_exec` 工具:命令通过本机回环上的 root 桥(`127.0.0.1:47913`,token 校验)
6
+ 交给 Android 系统侧执行,输出和退出码原样返回。
7
+
8
+ > 这是 **DSH 插件**(装在 DSH 主机上的 npm 包)。真正的 root 能力来自配套的
9
+ > **KernelSU 模块** [`dsh-root-bridge`](https://github.com/4344734/dsh-root-bridge),
10
+ > 先装模块、再装插件。
11
+
12
+ ## 为什么需要
13
+
14
+ DSH Go 的本机引擎跑在 proot 里,容器里的 `uid=0` 是假 root:`su` 执行不了,
15
+ 读不到其他 App 的数据,也不能 `mount`、改系统文件。
16
+ 配套模块在容器外开一条 root 命令通道,这个插件把它接成一个模型可用的工具。
17
+
18
+ ## 安装
19
+
20
+ 1. **先装 KernelSU 模块**(提供 root 桥):
21
+ 到 [Releases](https://github.com/4344734/dsh-root-bridge/releases) 下载
22
+ `dsh-root-bridge-v1.5.zip`,KernelSU → 模块 → 安装 → 重启。
23
+ 重启后在 DSH 的终端里确认:`dsh-root --status`
24
+ 2. **再装这个插件**:
25
+ - DSH Go:设置 › 插件 › 插件市场,搜 `dsh-root-bridge`,装到当前主机;
26
+ - 或者装到电脑上的 DSH:`npm i dsh-root-bridge`(DSH 插件管理器)
27
+
28
+ ## 工具
29
+
30
+ ### `root_exec`
31
+
32
+ | 参数 | 说明 |
33
+ |---|---|
34
+ | `command` | 交给 Android 侧 `/system/bin/sh -c` 执行的命令 |
35
+ | `timeoutMs` | 超时毫秒,默认 60000,最大 600000 |
36
+
37
+ 返回 `{ output, exitCode }`。
38
+
39
+ 例:
40
+
41
+ ```text
42
+ root_exec({ command: "id -u; uname -m" })
43
+ → exit 0
44
+ 0
45
+ aarch64
46
+ ```
47
+
48
+ ## 已知限制
49
+
50
+ - `pm` / `am` / `settings` / `input` / `wm` 这类 Android 框架命令会报
51
+ `Failed transaction (2147483646)`:ColorOS 的 binder 限制,root 域也绕不过。
52
+ - 需要配套 KernelSU 模块处于启用状态;桥没跑时工具会提示怎么恢复。
53
+ - 这个插件只负责「调用」,不会自己提权、也不会替你装模块。
54
+
55
+ ## 安全
56
+
57
+ - root 桥只监听 `127.0.0.1`,token 在 App 私有目录,普通 App 读不到。
58
+ - **拿到 token 就等于拿到这台手机的 root**;不要把 token 或 `~/.dsh` 发出去。
59
+ - 装上模块 + 插件,等于让模型能在这台手机上执行 root 命令,请只在信任的设备上用。
60
+
61
+ ## License
62
+
63
+ MIT
@@ -0,0 +1,3 @@
1
+ - insert:
2
+ - id: dsh-root-bridge
3
+ name: 'dsh-root-bridge'
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "dsh-root-bridge",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "在 DSH 里以真正的 root 执行 Android 侧命令(配合 KernelSU 模块 dsh-root-bridge)",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "exports": {
8
+ ".": "./src/index.js",
9
+ "./package.json": "./package.json"
10
+ },
11
+ "files": [
12
+ "src",
13
+ "cordis.patch.yml",
14
+ "README.md"
15
+ ],
16
+ "keywords": [
17
+ "dsh",
18
+ "dsh-plugin",
19
+ "android",
20
+ "root",
21
+ "kernelsu"
22
+ ],
23
+ "peerDependencies": {
24
+ "@deepseek-ai/cordis": "4.0.5 || 4.1.0",
25
+ "@deepseek-ai/dsh-tools": "0.2.1-rc.4 || 0.2.2-rc.1"
26
+ },
27
+ "dsh": {
28
+ "bundle": {
29
+ "patch": "./cordis.patch.yml"
30
+ }
31
+ },
32
+ "engines": {
33
+ "node": "^22.19.0 || >=24.0.0"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public"
37
+ },
38
+ "license": "MIT"
39
+ }
package/src/index.js ADDED
@@ -0,0 +1,149 @@
1
+ /**
2
+ * dsh-root-bridge — model-facing tool that runs commands as real root on the
3
+ * Android side, through the companion KernelSU module of the same name.
4
+ *
5
+ * The bridge listens on 127.0.0.1:47913, authenticated by the token in
6
+ * `$DSH_HOME/rootd/token`; the module restores that token file and the listener.
7
+ * This package only speaks that loopback protocol; it never escalates anything.
8
+ */
9
+ import net from 'node:net';
10
+ import fs from 'node:fs';
11
+ import path from 'node:path';
12
+ import os from 'node:os';
13
+ import { defineTool } from '@deepseek-ai/dsh-tools';
14
+
15
+ export const name = 'root-bridge';
16
+
17
+ /** Only the tool registry is needed; the bridge is a plain loopback socket. */
18
+ export const inject = ['tools'];
19
+
20
+ const MARK = '__RC__';
21
+ const DEFAULT_PORT = 47913;
22
+ const DEFAULT_TIMEOUT_MS = 60_000;
23
+ const MAX_TIMEOUT_MS = 600_000;
24
+
25
+ function dshHome() {
26
+ const env = process.env.DSH_HOME;
27
+ if (typeof env === 'string' && env.length > 0) return env;
28
+ return path.join(os.homedir(), '.dsh');
29
+ }
30
+
31
+ function bridgePort() {
32
+ try {
33
+ const text = fs.readFileSync(path.join(dshHome(), 'rootd', 'port'), 'utf8').trim();
34
+ const port = Number.parseInt(text, 10);
35
+ if (Number.isInteger(port) && port > 0 && port < 65536) return port;
36
+ } catch {
37
+ // Fall through to the default the module uses.
38
+ }
39
+ return DEFAULT_PORT;
40
+ }
41
+
42
+ function bridgeToken() {
43
+ const file = path.join(dshHome(), 'rootd', 'token');
44
+ try {
45
+ const token = fs.readFileSync(file, 'utf8').trim();
46
+ if (token.length > 0) return token;
47
+ } catch {
48
+ // Reported by the caller with the installation hint.
49
+ }
50
+ throw new Error(
51
+ `找不到 root 桥的 token(${file})。请先在手机上安装 dsh-root-bridge 的 KernelSU 模块并重启,` +
52
+ '然后运行 dsh-root --status 确认桥在线。',
53
+ );
54
+ }
55
+
56
+ function parseReply(buffer) {
57
+ const at = buffer.indexOf(MARK);
58
+ if (at < 0) throw new Error('root 桥没有回执(连接被提前关闭或 token 不匹配)');
59
+ const output = buffer.slice(0, at);
60
+ const code = Number.parseInt(buffer.slice(at + MARK.length).trim(), 10);
61
+ return { output, exitCode: Number.isInteger(code) ? code : 1 };
62
+ }
63
+
64
+ /** Send one authenticated command to the bridge and collect its reply. */
65
+ export function runRoot(command, timeoutMs = DEFAULT_TIMEOUT_MS) {
66
+ const timeout = Math.min(Math.max(1, Math.trunc(timeoutMs) || DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
67
+ const token = bridgeToken();
68
+ const port = bridgePort();
69
+ return new Promise((resolve, reject) => {
70
+ let buffer = '';
71
+ let settled = false;
72
+ const socket = net.createConnection({ host: '127.0.0.1', port });
73
+ const timer = setTimeout(() => {
74
+ finish(new Error(`命令超过 ${timeout}ms 仍未结束`));
75
+ }, timeout);
76
+
77
+ function finish(error, value) {
78
+ if (settled) return;
79
+ settled = true;
80
+ clearTimeout(timer);
81
+ socket.destroy();
82
+ if (error) reject(error);
83
+ else resolve(value);
84
+ }
85
+
86
+ socket.setEncoding('utf8');
87
+ socket.on('connect', () => {
88
+ socket.write(`${token}\n${command}`);
89
+ socket.end();
90
+ });
91
+ socket.on('data', (chunk) => {
92
+ buffer += chunk;
93
+ if (buffer.includes(MARK)) {
94
+ try {
95
+ finish(undefined, parseReply(buffer));
96
+ } catch (error) {
97
+ finish(error);
98
+ }
99
+ }
100
+ });
101
+ socket.on('error', (error) => {
102
+ const hint = error && error.code === 'ECONNREFUSED'
103
+ ? 'root 桥没在跑:确认 KernelSU 模块 dsh-root-bridge 已启用,或运行 dsh-root --status 检查。'
104
+ : String(error && error.message ? error.message : error);
105
+ finish(new Error(hint));
106
+ });
107
+ socket.on('close', () => {
108
+ if (!settled) finish(new Error('root 桥在回执前关闭了连接'));
109
+ });
110
+ });
111
+ }
112
+
113
+ export function apply(ctx) {
114
+ ctx.tools.register(defineTool({
115
+ name: 'root_exec',
116
+ description: '在 Android 系统侧以真正的 root 执行一条命令(绕过 DSH 的 proot 容器),返回合并后的输出与退出码。'
117
+ + '需要手机上已安装 dsh-root-bridge 的 KernelSU 模块;容器里普通的 bash 工具仍然是 proot 的假 root。'
118
+ + '注意:pm / am / settings / input 等 Android 框架命令在 ColorOS 上会被 binder 限制挡住,返回 Failed transaction;'
119
+ + '文件、系统、dumpsys、screencap、iptables 等正常。',
120
+ parameters: {
121
+ command: {
122
+ type: 'string',
123
+ required: true,
124
+ description: '交给 Android 侧 /system/bin/sh -c 执行的命令。',
125
+ },
126
+ timeoutMs: {
127
+ type: 'integer',
128
+ description: '超时毫秒数,默认 60000,最大 600000。',
129
+ },
130
+ },
131
+ output: {
132
+ schema: {
133
+ type: 'object',
134
+ additionalProperties: false,
135
+ properties: {
136
+ output: { type: 'string', required: true },
137
+ exitCode: { type: 'integer', required: true },
138
+ },
139
+ },
140
+ render: (_args, value) => [{
141
+ type: 'text',
142
+ text: `exit ${value.exitCode}\n${value.output}`,
143
+ }],
144
+ },
145
+ async execute(args) {
146
+ return runRoot(args.command, args.timeoutMs);
147
+ },
148
+ }));
149
+ }