@dybai/dsh-editor 0.0.0-stage → 0.5.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 dy.bai
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,92 @@
1
- # Temporary Holding Version
1
+ # @dybai/dsh-editor
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
+ **@dybai/dsh-editor** 让 DeepSeek Harness(DSH)工作区里的文本文件可以直接在对话旁就地编辑、保存(`Ctrl+S`)。DSH 原本只能只读预览工作区文件,想改就得跳出对话换外部工具;本插件补上「改文件」这一环:打开即编辑、保存写回磁盘,外部修改和误删都有保护。
4
+
5
+ 它同时是可扩展的**编辑器框架**:工具栏、状态栏、编辑模式、键位等全部开放给第三方插件,契约见 [docs/contracts.md](docs/contracts.md)。
6
+
7
+ ## 安装
8
+
9
+ 前置要求:DSH 引擎 `dsh >= 0.2.1-rc.5`;安装完成后浏览器 **Ctrl+F5** 刷新生效。
10
+
11
+ **插件市场(推荐)**:
12
+
13
+ 1. DSH 设置 → 插件 → 安装官方可选 bundle `@deepseek-ai/dsh-experimental-plugin-market-bundle`(实验性插件市场,提供 Discover 标签页);
14
+ 2. 在市场设置里**添加索引源**:`https://raw.githubusercontent.com/dybai/dsh-editor/main/market-index.json`;
15
+ 3. Discover 里找到「DSH 编辑器」→ 安装 → 刷新页面。
16
+
17
+ **npm 直接安装**:`plugin_manager` → `install_bundle`,spec 填 `@dybai/dsh-editor@0.4.0`(新版本号以 npm 页面或市场索引为准)。
18
+
19
+ **本地开发**:`install_bundle` 的目标为本仓库目录的绝对路径;开发循环见 [docs/deploy.zh-CN.md](docs/deploy.zh-CN.md) §3。
20
+
21
+ ## 框架概述
22
+
23
+ 三层架构:
24
+
25
+ - **集成层**(任意第三方插件,零依赖):注册座位 occupant、消费 `dshEditor` 服务、注册编辑模式、经导航契约打开文件——只依赖"名字",不 require 本包;
26
+ - **框架层**(本包):唯一状态与编排所有者——tab 状态机与保存队列(乐观并发 + 冲突横幅)、模式解析与挂载、工具栏/状态栏 chrome 与座位渲染、草稿持久化、Host RPC 桥;
27
+ - **模式层**(React 组件):内容视图。内置 `plain-text`(fallback);第三方以 `extension`/`builtin` 带注册排序接入,切换模式保草稿。
28
+
29
+ 完整契约见 **[docs/contracts.md](docs/contracts.md)**(座位 owner props、句柄切片、模式描述符、Host RPC、导航契约、持久化、演进规则)。
30
+
31
+ ## 快速开始
32
+
33
+ **安装**:见上方[「安装」](#安装)章节(插件市场 / npm 包 / 本地目录三条渠道)。
34
+
35
+ **打开**:
36
+
37
+ - 交互:文件预览工具栏的铅笔"编辑"按钮(只对文本文件渲染,原只读预览保留不动);
38
+ - 程序化:`ctx.get('dshEditor').open(address, { line })` 或 `ctx.sidebarRight.openResource(address, { kind: 'editor', params: { file: { line } } })`——带 `line` 时打开后定位到该行。
39
+
40
+ **保存与键位**:
41
+
42
+ - `Ctrl+S` 保存前台编辑器;`Ctrl+Shift+S` 保存当前会话全部未保存的编辑器;`Ctrl+D` 删除光标行/选区触及行。这三条是**框架自管键位**:编辑器根元素拦截 keydown 并自行 `preventDefault`(对任何组合有效,不受 DSH web 快捷键白名单限制),编辑器之外浏览器默认行为照旧;
43
+ - 键位是全局用户偏好:编辑器状态栏右端的小键盘图标打开键位面板,逐动作「录制」新组合(允许任何组合,含浏览器保留键)或「恢复默认」,持久化到 Host 存储、所有已挂载编辑器立即生效(详见 [docs/contracts.md](docs/contracts.md) §6);
44
+ - 磁盘文件被外部修改时出现冲突横幅:**重新加载并丢弃本地修改** 或 **仍要保存(覆盖磁盘)**;
45
+ - 编辑中途崩溃/刷新后重新打开同一文件,未保存草稿自动恢复(磁盘文件也变过时先出冲突横幅,绝不静默覆盖)。
46
+
47
+ **外部修改与删除检测**(0.3.0):
48
+
49
+ - 打开中的文件被外部修改时,编辑器顶部弹出浅黄悬浮条:**是[重新加载]**(丢弃本地修改读入磁盘)/ **否[放弃更新]**(保留本地修改,保存时冲突横幅兜底)/ **否[不再询问]**(本页签内不再询问,保存时仍兜底);
50
+ - 文件被外部删除时,页签文件名标红并画上删除线,悬浮条询问是否关闭页签;选择保留可继续编辑,**Ctrl+S 保存即重建文件**(成功后红标消失)。外部同路径重建会被识别并清除红标;
51
+ - 删除后**原样保存不需要先修改内容**:干净草稿下保存按钮/Ctrl+S 首次触发只布防确认(按钮变「确认重建」警示色),再次触发才执行重建;任何编辑或外部状态变化自动解除布防;
52
+ - 检测走宿主 `workspaceFiles/changes` 推送流(实时、零轮询),流不可用时自动降级为切换回页面/窗口聚焦时检查;
53
+ - 干净文件自动重载可在状态栏右端齿轮图标的**设置面板**中开启(默认关闭 = 一律询问),持久化到 Host 存储。
54
+
55
+ **活动行高亮**(0.4.0):
56
+
57
+ - 编辑区以光标所在行的上下细边线标记当前行(VS Code 风格,不填背景——为将来的语法高亮留出颜色空间),随光标移动、内容编辑与滚动实时跟随;多行选区时边线跟随光标端(拖拽释放所在行),选区本身由浏览器原生选区样式呈现,不逐行描边;
58
+ - 设置面板新增「高亮光标所在行」开关(默认开,全局持久化,对所有已挂载编辑器立即生效);
59
+ - 第三方模式可在描述符声明 `activeLine: true` 接入同一契约:经组件 prop `highlightActiveLine` 接收偏好、以快照 `selection.lineStart`/`lineEnd` 为高亮范围自行绘制(见 [docs/contracts.md](docs/contracts.md) §5.1 / §5.5)。
60
+
61
+ **行号列**(0.5.0):
62
+
63
+ - 编辑区内容左侧显示行号列:宽度随最大行号位数自适应(跨 100/1000 行等进位时自动加宽),随滚动、编辑、行导航实时同步;
64
+ - 设置面板新增「显示行号」开关(默认开,全局持久化,对所有已挂载编辑器立即生效)。开关只控制数字显隐:分界竖线与左侧预留带常驻,切换不会移动正文位置;
65
+ - 无描述符声明字段:`showLineNumbers` 偏好经组件 prop 直接送达到每个挂载的模式组件,第三方模式可自行接入(绘制行号列)或安全忽略(见 [docs/contracts.md](docs/contracts.md) §5.1 / §5.5)。
66
+
67
+ ## 集成接口摘要
68
+
69
+ | 契约面 | 入口 | 一句话 |
70
+ |---|---|---|
71
+ | 座位 ×3 | `ctx.slots.inject('dsh-editor.actions' / 'dsh-editor.status' / 'dsh-editor.unavailable', …)` | 向工具栏/状态栏/失败空态放 occupant,owner props 含 `address`/`path`/`sessionId`(status 另有渲染时刻 `snapshot`) |
72
+ | 客户端服务 | `ctx.get('dshEditor')` | `version` / `active`(前台句柄) / `open(address, { line })`;句柄提供 `content`/`selection`/`state`/`mode` 四个可观察切片与 `save()`/`navigateToLine()`/`close()`,失效后明确错误、从不抛异常 |
73
+ | 模式注册 | `ctx.get('dshEditorModes').register(descriptor)` | 一种内容渲染实现:`{ id, priority, globs, matches, label, contentKind, component } → disposer`;pin > 关联 > 三带排序 > `matches` 否决 |
74
+ | 导航契约 | `sidebarRight.openResource(address, { kind: 'editor', params: { file: { line } } })` | 把会话文件地址送进编辑器 tab 的唯一入口 |
75
+
76
+ 各面的形状、门控语义、代码示例与演进承诺以 [docs/contracts.md](docs/contracts.md) 为准。
77
+
78
+ ## 已知限制(v0.2 非目标)
79
+
80
+ 以下为契约已预留、v1 **不实现**的能力:
81
+
82
+ - `contentKind: 'raw'` 路径与自定义传输(二进制/分页内容由模式自带读写);
83
+ - hex / CodeMirror 高亮等 builtin 富模式及细粒度扩展面(编辑区浮层座位:find/minimap);
84
+ - `fs` 字节写 facet(当前仅整文件 UTF-8 文本写,≤4 MB,文本格式白名单);
85
+ - 光标位置恢复(草稿恢复后光标不回位);
86
+ - 模式关联管理设置页(关联目前仅经模式菜单"设为默认/恢复默认"管理)。
87
+
88
+ 另有:只能编辑会话工作区内的文本文件;编辑器以独立 tab 打开,不替换当前预览 tab;键位录制会拒绝浏览器生命周期保留组合(Ctrl/⌘+W/T/N/Q、Ctrl+Tab 等)并给出提示——页面层无法可靠拦截这类浏览器默认行为。
89
+
90
+ ## 契约变更记录
91
+
92
+ 维护在 [docs/contracts.md](docs/contracts.md) 顶部(`0.2.0 → 初版契约(全部条目)`);后续发布必须在该章节登记契约增量。