dsh-runtime-kit 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-runtime-kit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,227 @@
1
- # Temporary Holding Version
1
+ # dsh-runtime-kit
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 通用运行时插件** —— 高执行效率与细粒度沙箱环境,**零业务依赖**。
4
+
5
+ > 对标规格:`DSH-快速执行与沙箱方案.md` v2.1(§0–§8)
6
+
7
+ ---
8
+
9
+ ## 🎯 核心定位
10
+
11
+ | 维度 | 说明 |
12
+ |------|------|
13
+ | **是什么** | 给 DSH 装上「上下文治理 + 快路径 + PTC + 沙箱 + 审计」的通用运行时能力 |
14
+ | **不是什么** | 不内置任何业务逻辑、不读业务文件、不驱动浏览器、不管账号/选择器/登录态 |
15
+ | **交付形态** | 单一插件包 `dsh-runtime-kit`,内部模块化,整体可一键启停 |
16
+ | **唯一耦合面** | `registry`:使用方注册 **工具 / 模板 / 工作区**,插件只认这三个结构 |
17
+
18
+ ---
19
+
20
+ ## 📦 能力矩阵(对标 v2.1 §4)
21
+
22
+ | 代号 | 能力 | 关键特性 | 验收指标 |
23
+ |------|------|----------|----------|
24
+ | **C1** | 上下文治理 | 返回体 ≤4KB 裁剪、字段投影、预算、pruner/compaction、**延迟工具加载** | M1/M2/M3 |
25
+ | **C2** | 快路径 | 模板注册表、命中即规则执行、**0 LLM 调用**、幂等键、状态机 | M4 |
26
+ | **C3** | PTC 封装 | 脚本容器内批量调工具、中间结果留容器内、仅摘要进 context、registry 强制约束 | M2/M3 |
27
+ | **C4** | 编排裁剪 | preset 补丁默认关 `plan/todo/goal/subagent`、可独立配置、`--dump-config` 核对 | M1 |
28
+ | **C5** | 并发与恢复(可选) | 只读工具并发上限 8、变更工具屏障串行、崩溃隔离、turn/step 持久化、一键回退 | M5/M9/M10/M12 |
29
+ | **C6** | 沙箱 | 三档基线 + **三态细粒度规则(文件读/写/删、命令前缀、网络域名)**、fail-closed、网络默认拒绝、Windows `pwsh`、变更快照/回收站、工具粒度管控、工作区信任/受限、注入防护、敏感脱敏、执行域可替换 | M6/M7/M8/M11/M13/M14 |
30
+ | **C7** | 审计与指标 | append-only 流水、脱敏、可导出、token/工具调用/拒绝/审批全指标 | M1–M14 全覆盖 |
31
+
32
+ ---
33
+
34
+ ## 🔌 对外契约:Registry(唯一耦合面)
35
+
36
+ ```typescript
37
+ // 工具注册
38
+ registry.registerTool({
39
+ name: 'my_tool',
40
+ description: '...',
41
+ schema: { type: 'object', properties: {...} },
42
+ isStateChanging: false, // 是否触发屏障/审批
43
+ returnBudget: 4096, // 返回体预算
44
+ timeout: 30000,
45
+ handler: async (args) => ({ success: true, data: {...} })
46
+ });
47
+
48
+ // 模板注册(快路径)
49
+ registry.registerTemplate({
50
+ name: 'my_template',
51
+ match: (input) => input.startsWith('do something'),
52
+ plan: [
53
+ { tool: 'tool_a', args: { param: 'value' } },
54
+ { tool: 'tool_b', args: (input, prev) => ({ data: prev.get('tool_a')?.data }) },
55
+ ],
56
+ idempotencyKeyFn: (input) => `my_template:${input}`
57
+ });
58
+
59
+ // 工作区注册(沙箱边界)
60
+ registry.registerWorkspace({
61
+ profile: 'my-profile',
62
+ root: '/absolute/path/to/workspace',
63
+ networkAllowlist: ['api.example.com'],
64
+ permissionMode: 'workspace-write',
65
+ envPrefix: 'MY_',
66
+ trusted: false,
67
+ });
68
+ ```
69
+
70
+ **插件不关心 handler 里跑什么**——浏览器、HTTP、纯计算均可。
71
+
72
+ ---
73
+
74
+ ## ⚙️ 配置(完整 schema 见 `config.schema.json`)
75
+
76
+ ```json
77
+ {
78
+ "context": { "maxReturnBytes": 4096, "fieldsProjection": true, "prunerEnabled": true, "compactionEnabled": true, "lazyLoadTools": true },
79
+ "loop": { "preset": "code", "disabledLayers": ["plan","todo","goal","subagent"], "maxParallelToolCalls": 8, "enableCustomLoop": false },
80
+ "sandbox": {
81
+ "mode": "workspace-write",
82
+ "approval": "ask",
83
+ "rules": {
84
+ "files": [{ "pattern": "**/*.secret", "read": "deny", "write": "deny", "delete": "deny" }],
85
+ "commands": [{ "prefix": "rm -rf", "action": "ask" }],
86
+ "network": [{ "domain": "api.github.com", "action": "allow" }]
87
+ },
88
+ "networkDefault": "deny",
89
+ "backupEnabled": true,
90
+ "deletionProtection": true,
91
+ "injectionGuard": true,
92
+ "sensitiveProtection": true,
93
+ "shell": "pwsh",
94
+ "workspaceTrust": false,
95
+ "toolControl": { "dangerous_tool": false }
96
+ },
97
+ "audit": { "mode": "append-only", "desensitize": true, "exportable": true, "retentionDays": 90 }
98
+ }
99
+ ```
100
+
101
+ ---
102
+
103
+ ## 🧪 验收指标(§6,纯通用夹具,零业务)
104
+
105
+ | # | 指标 | 通过线 |
106
+ |---|------|--------|
107
+ | M1 | 首请求输入 token | 显著下降,给出实测值 |
108
+ | M2 | 重复模板任务 10 次平均输入 token | **降幅 ≥70%**(vs 原生 loop) |
109
+ | M3 | 每轮进入 context 的 tool result 字节 | **≤4 KB** |
110
+ | M4 | 快路径命中时的 LLM 调用次数 | **= 0** |
111
+ | M5 | 8 个 `echo` 并发 wall-clock | 明显缩短,无状态错乱 |
112
+ | M6 | 跨工作区读 / 路径穿越 | **100% 拒绝 + 审计** |
113
+ | M7 | 白名单外外联 | **100% 阻断 + 审计** |
114
+ | M8 | 策略配置损坏行为 | **fail-closed(拒绝)** |
115
+ | M9 | `disable` 后官方 loop | 立即可用、无状态残留 |
116
+ | M10 | 跨重启恢复 | 已成功步骤不重复执行 |
117
+ | M11 | 凭据/Cookie 在返回/日志/上下文出现次数 | **0**(脱敏测试) |
118
+ | M12 | 崩溃工具后的会话主干 | 继续可用、错误结构化 |
119
+ | M13 | 工具返回含诱导指令 | 疑似内容不进上下文 + 需确认 |
120
+ | M14 | 越界写入/修改已有文件 | 拒绝或需确认 + 变更前快照可回退 |
121
+
122
+ **测试夹具**:`echo` / `kv_get/kv_set` / `file_read/file_write` + 两个临时目录 / `http_probe` / `echo-chain` 模板 / `crash_tool`
123
+
124
+ ---
125
+
126
+ ## 🚀 快速开始
127
+
128
+ ```bash
129
+ git clone https://github.com/daoyan2142/dsh-runtime-kit.git
130
+ cd dsh-runtime-kit
131
+ pnpm install
132
+ pnpm build
133
+ ```
134
+
135
+ 在 DSH profile 中启用:
136
+
137
+ ```json
138
+ {
139
+ "plugins": {
140
+ "dsh-runtime-kit": {
141
+ "enabled": true,
142
+ "config": { /* 见上方配置示例 */ }
143
+ }
144
+ }
145
+ }
146
+ ```
147
+
148
+ ---
149
+
150
+ ## 📋 管理命令
151
+
152
+ ```bash
153
+ # 健康检查
154
+ runtime_kit_health
155
+
156
+ # 配置核对 / 应用预设
157
+ runtime_kit_config [minimal-no-orchestration|code-ptc-friendly]
158
+
159
+ # 指标查看
160
+ runtime_kit_metrics
161
+
162
+ # 审计日志
163
+ runtime_kit_audit_logs [profile] -t <tool> -a <action> -r <result> -s <date> -l 50
164
+
165
+ # 隔离验证
166
+ runtime_kit_isolation <profile>
167
+
168
+ # 快路径执行
169
+ runtime_kit_fastpath "echo-chain:test" [profile]
170
+
171
+ # PTC 执行
172
+ runtime_kit_ptc 'callTool("echo", {"text":"hi"})' [profile]
173
+
174
+ # 注册表查看
175
+ runtime_kit_registry_tools
176
+ runtime_kit_registry_templates
177
+ runtime_kit_registry_workspaces
178
+ ```
179
+
180
+ ---
181
+
182
+ ## 🏗️ 内部架构
183
+
184
+ ```
185
+ src/
186
+ ├── types.ts # 所有类型定义(零业务)
187
+ ├── registry/ # 唯一对外耦合面
188
+ ├── context/ # C1 上下文治理(中间件)
189
+ ├── sandbox/ # C6 沙箱(路径/网络/命令/工具/快照/回收站/注入/脱敏/shell/执行域)
190
+ ├── audit/ # C7 审计(append-only + 脱敏 + 指标)
191
+ ├── loop/ # C2 快路径 + C3 PTC + C5 并发/恢复
192
+ ├── preset/ # C4 编排裁剪补丁
193
+ └── index.ts # 插件主入口,组装所有能力
194
+ ```
195
+
196
+ ---
197
+
198
+ ## 📌 实施阶段(§7)
199
+
200
+ | 阶段 | 交付 | 验收 | 外部依赖 |
201
+ |------|------|------|----------|
202
+ | **P0 上下文治理** | registry + C1 + C4 + 通用夹具 | M1/M2/M3 | 无 |
203
+ | **P1 沙箱与审计** | C6 + C7 + Windows `pwsh` 抽象 | M6/M7/M8/M11 | 无 |
204
+ | **P2 快路径** | C2 + C3 + 幂等/状态机 | M4 | 无 |
205
+ | **P3 并发与恢复(可选)** | C5 自定义 loop + 回退 | M5/M9/M10/M12 | 临时 profile 验证 |
206
+
207
+ > **每阶段独立验收,无需任何业务信息。**
208
+
209
+ ---
210
+
211
+ ## ⚠️ 禁止项(§8.2)
212
+
213
+ 1. 禁止在插件内引用任何业务脚本、记忆文件、账号、选择器、登录态
214
+ 2. 禁止内置任何具体任务模板或业务参数
215
+ 3. 禁止把工具返回的大对象、二进制、日志全文塞进 context
216
+ 4. 禁止把 `danger-full-access` 设为默认;禁止策略异常时降级放行
217
+ 5. 禁止依赖 git bash 或任何绕开受限令牌的 shell 适配
218
+ 6. 禁止在验收夹具里出现真实业务系统、真实 URL、真实凭据
219
+ 7. 禁止在主力 profile 直接试用未经验证的第三方 loop 实现
220
+ 8. **禁止让插件核心 import 使用方代码——耦合只允许发生在 registry**
221
+
222
+ ---
223
+
224
+ ## 🔗 关键参考
225
+
226
+ - 对标规格:内部《DSH 快速执行与沙箱方案》v2.1(§0–§8)
227
+ - DSH 运行时:宿主安装目录下的 `resources/app.asar/dsh/`
@@ -0,0 +1,202 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "dsh-runtime-kit Configuration",
4
+ "type": "object",
5
+ "properties": {
6
+ "context": {
7
+ "type": "object",
8
+ "properties": {
9
+ "maxReturnBytes": {
10
+ "type": "integer",
11
+ "minimum": 512,
12
+ "maximum": 65536,
13
+ "default": 4096,
14
+ "description": "单工具返回体硬上限(字节)"
15
+ },
16
+ "fieldsProjection": {
17
+ "type": "boolean",
18
+ "default": true,
19
+ "description": "启用字段投影"
20
+ },
21
+ "prunerEnabled": {
22
+ "type": "boolean",
23
+ "default": true,
24
+ "description": "启用长会话 pruner"
25
+ },
26
+ "compactionEnabled": {
27
+ "type": "boolean",
28
+ "default": true,
29
+ "description": "启用 compaction"
30
+ },
31
+ "lazyLoadTools": {
32
+ "type": "boolean",
33
+ "default": true,
34
+ "description": "工具 schema 按需加载(对标 ToolSearch/Defer)"
35
+ }
36
+ },
37
+ "additionalProperties": false
38
+ },
39
+ "loop": {
40
+ "type": "object",
41
+ "properties": {
42
+ "preset": {
43
+ "type": "string",
44
+ "enum": ["minimal", "code", "default"],
45
+ "default": "code",
46
+ "description": "基础 preset"
47
+ },
48
+ "disabledLayers": {
49
+ "type": "array",
50
+ "items": { "type": "string", "enum": ["plan", "todo", "goal", "subagent"] },
51
+ "default: ["plan", "todo", "goal", "subagent"],
52
+ "description": "关闭的重编排层"
53
+ },
54
+ "maxParallelToolCalls": {
55
+ "type": "integer",
56
+ "minimum": 1,
57
+ "maximum": 32,
58
+ "default": 8,
59
+ "description": "并发上限(仅只读工具)"
60
+ },
61
+ "enableCustomLoop": {
62
+ "type": "boolean",
63
+ "default": false,
64
+ "description": "是否启用 C5 自定义 loop(并发/屏障/恢复)"
65
+ }
66
+ },
67
+ "additionalProperties": false
68
+ },
69
+ "sandbox": {
70
+ "type": "object",
71
+ "properties": {
72
+ "mode": {
73
+ "type": "string",
74
+ "enum": ["read-only", "workspace-write", "danger-full-access"],
75
+ "default": "workspace-write",
76
+ "description": "三档基线权限"
77
+ },
78
+ "approval": {
79
+ "type": "string",
80
+ "enum": ["auto", "ask", "deny"],
81
+ "default": "ask",
82
+ "description": "越界/高危操作审批模式"
83
+ },
84
+ "rules": {
85
+ "type": "object",
86
+ "properties": {
87
+ "files": {
88
+ "type": "array",
89
+ "items": {
90
+ "type": "object",
91
+ "properties": {
92
+ "pattern": { "type": "string" },
93
+ "read": { "type": "string", "enum": ["allow", "ask", "deny"] },
94
+ "write": { "type": "string", "enum": ["allow", "ask", "deny"] },
95
+ "delete": { "type": "string", "enum": ["allow", "ask", "deny"] }
96
+ },
97
+ "required": ["pattern"]
98
+ }
99
+ },
100
+ "commands": {
101
+ "type": "array",
102
+ "items": {
103
+ "type": "object",
104
+ "properties": {
105
+ "prefix": { "type": "string" },
106
+ "action": { "type": "string", "enum": ["allow", "ask", "deny"] }
107
+ },
108
+ "required": ["prefix"]
109
+ }
110
+ },
111
+ "network": {
112
+ "type": "array",
113
+ "items": {
114
+ "type": "object",
115
+ "properties": {
116
+ "domain": { "type": "string" },
117
+ "action": { "type": "string", "enum": ["allow", "ask", "deny"] }
118
+ },
119
+ "required": ["domain"]
120
+ }
121
+ }
122
+ },
123
+ "additionalProperties": false
124
+ },
125
+ "networkDefault": {
126
+ "type": "string",
127
+ "enum": ["allow", "ask", "deny"],
128
+ "default": "deny",
129
+ "description": "默认网络策略"
130
+ },
131
+ "backupEnabled": {
132
+ "type": "boolean",
133
+ "default": true,
134
+ "description": "修改已有文件前生成快照"
135
+ },
136
+ "deletionProtection": {
137
+ "type": "boolean",
138
+ "default": true,
139
+ "description": "删除优先进回收站"
140
+ },
141
+ "injectionGuard": {
142
+ "type": "boolean",
143
+ "default": true,
144
+ "description": "工具返回诱导指令检测"
145
+ },
146
+ "sensitiveProtection": {
147
+ "type": "boolean",
148
+ "default": true,
149
+ "description": "凭据/密文参与上下文、输出还原"
150
+ },
151
+ "shell": {
152
+ "type": "string",
153
+ "enum": ["pwsh", "native"],
154
+ "default": "pwsh",
155
+ "description": "Windows 强制 pwsh,Linux 原生"
156
+ },
157
+ "workspaceTrust": {
158
+ "type": "boolean",
159
+ "default": false,
160
+ "description": "工作区信任状态(未信任进入受限模式)"
161
+ },
162
+ "toolControl": {
163
+ "type": "object",
164
+ "description": "工具粒度启停:工具名 -> true/false",
165
+ "additionalProperties": { "type": "boolean" }
166
+ }
167
+ },
168
+ "additionalProperties": false
169
+ },
170
+ "audit": {
171
+ "type": "object",
172
+ "properties": {
173
+ "mode": {
174
+ "type": "string",
175
+ "enum": ["append-only", "off"],
176
+ "default": "append-only",
177
+ "description": "审计模式"
178
+ },
179
+ "desensitize": {
180
+ "type": "boolean",
181
+ "default": true,
182
+ "description": "脱敏(密码/Cookie/token)"
183
+ },
184
+ "exportable": {
185
+ "type": "boolean",
186
+ "default": true,
187
+ "description": "日志可导出"
188
+ },
189
+ "retentionDays": {
190
+ "type": "integer",
191
+ "minimum": 1,
192
+ "maximum": 365,
193
+ "default": 90,
194
+ "description": "日志保留天数"
195
+ }
196
+ },
197
+ "additionalProperties": false
198
+ }
199
+ },
200
+ "required": ["context", "loop", "sandbox", "audit"],
201
+ "additionalProperties": false
202
+ }