@flotiarenor/dsh-tool-text-editor 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,177 @@
+# dsh-tool-text-editor
+
+[中文](README.zh.md) | English
+
+Model-facing tools for [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) that edit text
+files **byte-faithfully**: `edit_text` and `write_text`.
+
+They exist because the built-in tools lose Windows file conventions:
+
+| Case (file is UTF-8 **BOM + CRLF**) | built-in `edit` | built-in `write` | this plugin |
+|---|---|---|---|
+| change one line | CRLF kept / **BOM lost** | — | BOM + CRLF kept |
+| full overwrite | — | **BOM lost + CRLF flattened to LF** | BOM + CRLF kept |
+
+`@deepseek-ai/dsh-fs-local` has no BOM handling at all (Node's `TextDecoder` strips a leading BOM
+byte by default) and `writeText` does not restore a file's line-ending style.
+
+On top of fidelity: **unified diffs** (with a `dry_run` preview), **automatic backups**, an **edit
+ledger**, **`grep` / `lines` anchors** so old text never has to be copied by hand, **ambiguity
+refusal**, and **near-miss candidates** when an anchor does not match.
+
+## Implementation and requirements
+
+The implementation is **in-process Node** (`lib/core.mjs`): `node:` builtins only, no subprocess, no
+build step, no third-party package.
+
+| Requirement | Notes |
+|---|---|
+| Node | **The only dependency** — no interpreter, no external runtime, no process-startup cost per call. |
+
+The package installs nothing of its own. Its single `peerDependencies` entry, `@deepseek-ai/dsh-tools`,
+is the host contract — "needs this dsh or newer" — and resolves from the dsh installation rather than
+being installed beside the plugin.
+
+## Install
+
+### Option 1 — preset (recommended, tightly scoped)
+
+Only sessions that select this preset see the two tools. Run this from the root of a clone of this
+repository:
+
+```powershell
+node scripts/install-preset.mjs
+# flags: --id <preset-id> (default texteditor) / --base <shipped-preset> (default standard)
+#        / --force / --dry-run / --from <agent.cordis.yml path>
+```
+
+Then restart `dsh web` and start a new session on preset `texteditor`; a preset is a session-creation
+fact, so a running session cannot switch to it.
+
+### Option 2 — install into the profile (available to every session)
+
+`dsh plugin add` accepts several kinds of source, and every one of them works here: the package is
+prebuilt, dependency-free ESM, so there is no `prepare`/`build` step to authorize or run.
+
+| Source | Command |
+|---|---|
+| a local checkout | `dsh plugin --profile web add link:<absolute-path-to-this-checkout>` |
+| npm, once published | `dsh plugin --profile web add @flotiarenor/dsh-tool-text-editor` |
+| a packed tarball | `pnpm pack`, then `dsh plugin --profile web add ./<the-file-it-printed>.tgz` |
+| a git repository (tracks the default branch) | `dsh plugin --profile web add github:Flotiarenor/dsh-tool-text-editor` |
+
+Verify the layer without starting anything, then restart:
+
+```powershell
+dsh --profile web --dump-config   # look for the "# == @flotiarenor/dsh-tool-text-editor" layer
+```
+
+The tool names do not collide with the built-ins, so a host-plane insert is safe. The trade-off is
+that both tools (and their guidance section) show up in **every** session. Uninstall with
+`dsh plugin --profile web remove @flotiarenor/dsh-tool-text-editor`.
+
+Both installs may coexist: the preset layer shadows the host layer with an identical definition.
+
+## Tools
+
+### `edit_text` — targeted replacement
+
+`file_path` and `new_text` are required; give **exactly one** anchor: `old_text` (literal, copied from
+`read`), `grep` (regex; the matched line/block including its trailing newline), or `lines` (e.g.
+`"263:270"`). `mode` is `replace` (default) / `after` / `before` / `append` / `prepend`; also `count`
+(require exactly N occurrences and replace all), `nth` (k-th occurrence), `strict`, `dry_run`, `note`.
+`count` and `nth` are mutually exclusive.
+
+### `write_text` — create or fully replace a file
+
+`file_path` + `content`; creation needs no flag, an overwrite is backed up first, and a brand-new file
+follows the **majority** line-ending style of its siblings (same extension first) with no BOM by
+default.
+
+Both **write by default** (like the built-ins); pass `dry_run: true` to preview. The returned text
+always includes the diff.
+
+## Deliberate limitations
+
+These are design choices, not defects to be fixed; check them against your use case before relying on
+the tools.
+
+- **Writes bypass `ctx.fs`.** The file is written by the plugin itself, so the fs-observation policy
+  (read-before-write, version freshness), the sandbox, `sandbox_permissions` escalation and Windows
+  DACL preservation are all skipped — and the Web UI therefore shows no diff card (the model still
+  receives the textual diff).
+- **Line anchors are not content-verified.** `lines` and `before` / `after <line>` locate text by line
+  number alone: a wrong number does not fail, it edits somewhere else. When the anchor has to be
+  verifiable, use `old_text` or `grep`.
+- **Per-target serialization is per process.** An in-process queue per target plus an atomic write
+  keeps parallel tool calls from overwriting each other, but another dsh instance, an editor or any
+  other process writing the same file still can, and external changes are not detected.
+- **UTF-8 text only.** Files containing NUL bytes (binary) or invalid UTF-8 are refused, as are paths
+  inside `.git/` or `.dsh/` and paths outside the workspace.
+
+## Configuration
+
+There is no Config schema: the preset row's `config:` mapping is passed through as-is.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `backup` | `true` | copy the previous content into `artifactsDir/backups` before writing |
+| `ledger` | `true` | append a JSONL record to `artifactsDir/edits.log` |
+| `artifactsDir` | `<workspace>/.dsh` | where backups and the ledger live |
+| `newFileBom` | `false` | write a UTF-8 BOM when creating a new file |
+| `context` | `3` | context lines in the unified diff |
+| `root` | `process.cwd()` | fallback workspace when a call has no agent session |
+
+`DSH_TEXT_EDITOR_EOL` (`lf` \| `crlf`) overrides the line-ending inference for **new** files.
+
+## Self-test and gates
+
+```powershell
+# run from the root of a clone of this repository
+node tools/selftest.mjs        # 75/75 on Windows + Node 24
+node tools/check-license.mjs   # license / dependency / Node-only gate
+node tools/gen-schema.mjs      # embedded schemas still match the DSL
+```
+
+These three live in the repository only: `tools/` is deliberately outside the `files` whitelist, so
+the published package is just the plugin, its preset installer, the docs and the license.
+
+`tools/selftest.mjs` covers BOM/EOL fidelity, `dry_run`, all four anchor kinds, `count`, ambiguity
+refusal, usage errors, binary/invalid-UTF-8 refusal, `.dsh/` and outside-workspace guards, majority
+EOL inference, multi-hunk diffs, end-of-file newline changes and concurrent writes — **plus a
+plugin-layer suite** that drives `apply()` with a fake context and asserts tool registration, the
+guidance section, that every returned value satisfies `OUTPUT_SCHEMA`, the `render()` text, and the
+config plumbing (`root` / `backup` / `ledger` / `newFileBom`).
+
+`tools/gen-schema.mjs` needs an installed `@deepseek-ai/dsh-tools`: it looks for one under the dsh
+profile's `node_modules` and under the npm global prefix, and `DSH_TOOLS_ENTRY` overrides that lookup.
+It exits 2 when it cannot find one.
+
+## Layout
+
+```
+lib/core.mjs             # the core: BOM/EOL, anchors, matching, diff, backups, ledger, atomic write, per-target lock
+lib/editor.mjs           # the plugin: schemas, validation, tool registration (zero-dep ESM, no build)
+preset/preset.yml        # preset name/description, as dsh lists it
+scripts/install-preset.mjs  # derives the user preset from the local dsh installation
+cordis.patch.yml         # host-plane bundle patch
+tools/selftest.mjs       # end-to-end self-test (core + plugin layer)
+tools/check-license.mjs  # license / dependency / Node-only hygiene gate
+tools/gen-schema.mjs     # authoritative source and checker for the embedded JSON Schemas
+```
+
+Backups and the ledger use fixed, documented names and fields: one file per edit under
+`.dsh/backups/`, named `<flattened-absolute-path>@<timestamp>`, and one JSON object per line in
+`.dsh/edits.log` (`time`, `id`, `tool`, `file`, `abspath`, `action`, `kinds`, `line_start`,
+`line_end`, `added`, `removed`, `bom`, `eol`, `backup`, `summary`).
+
+## License
+
+**Apache-2.0** — see [LICENSE](LICENSE). Copyright 2026 Flotiarenor. The package has **no runtime
+dependencies**, so it carries no third-party license obligations of its own. Three notes:
+
+- The embedded JSON Schemas in `lib/editor.mjs` are generated *output* of the `@deepseek-ai/dsh-tools`
+  converter (MIT, Copyright (c) 2026 DeepSeek) via `tools/gen-schema.mjs`.
+- The preset composition is **not** part of this package: `scripts/install-preset.mjs` reads the one
+  shipped with the user's own dsh installation at install time.
+- Source files carry an `SPDX-License-Identifier` header, so the license is machine-readable per file.

package/README.zh.md

@@ -0,0 +1,167 @@
+# dsh-tool-text-editor
+
+中文 | [English](README.md)
+
+[DeepSeek Harness](https://github.com/deepseek-ai)（dsh）的模型工具插件，提供两个**字节保真**的
+文本编辑工具：`edit_text` 与 `write_text`。
+
+原生工具在 Windows 上存在两处缺陷：
+
+| 场景（文件为 UTF-8 **BOM + CRLF**） | 原生 `edit`                  | 原生 `write`                       | 本插件            |
+| ---------------------------------------- | ----------------------------- | ----------------------------------- | ----------------- |
+| 改一行                                   | CRLF 保住 / **BOM 丢失** | —                                  | BOM + CRLF 都保住 |
+| 整篇覆盖                                 | —                            | **BOM 丢失 + CRLF 被拍成 LF** | BOM + CRLF 都保住 |
+
+原因在于 `@deepseek-ai/dsh-fs-local` 完全没有 BOM 处理（Node 的 `TextDecoder` 默认吞掉前导
+BOM 字节），且 `writeText` 不按原文件风格还原行尾。
+
+在保真之外，本插件还提供：**统一 diff**（可用 dry-run 预览）、**写入前自动备份**、**编辑台账**、
+**`grep` / `lines` 锚点**（无需人工誊抄原文）、**歧义时拒绝写入**，以及**最接近候选**提示。
+
+## 实现与依赖
+
+实现是**进程内 Node**（`lib/core.mjs`）：只用 `node:` 内置模块，不启动任何子进程，无构建步骤、
+无第三方依赖。
+
+| 依赖 | 说明                                                                           |
+| ---- | ------------------------------------------------------------------------------ |
+| Node | 插件唯一的依赖。不启动解释器、不引入外部运行时；每次调用均无进程启动开销。 |
+
+## 安装
+
+### 方式一：preset（推荐，作用域最小）
+
+仅选定该 preset 的会话可见这两个工具，其它项目与会话的工具表不受影响。**在本仓库根目录**执行：
+
+```powershell
+node scripts/install-preset.mjs
+# 可选：--id <preset-id>（默认 texteditor）/ --base <自带 preset>（默认 standard）
+#       / --force / --dry-run / --from <agent.cordis.yml 路径>
+```
+
+随后重启 `dsh web`，新建会话时选择 preset `texteditor`；preset 属会话创建期事实，已在运行的会话无法切换。
+
+### 方式二：安装到 profile（所有会话可用）
+
+`dsh plugin add` 支持多种来源，**以下来源均受支持**：本包为预构建的零依赖 ESM，无
+`prepare` / `build` 步骤，因此既无需用户授权构建，安装时也不会执行任何构建脚本。
+
+| 来源           | 命令                                                                        |
+| -------------- | --------------------------------------------------------------------------- |
+| 本地仓库       | `dsh plugin --profile web add link:<本仓库的绝对路径>`                    |
+| npm（发布后）  | `dsh plugin --profile web add @flotiarenor/dsh-tool-text-editor`          |
+| 打包的 tarball | 先 `pnpm pack`，再 `dsh plugin --profile web add ./<pnpm pack 输出的文件名>.tgz` |
+| git 仓库（跟随默认分支） | `dsh plugin --profile web add github:Flotiarenor/dsh-tool-text-editor` |
+
+可在启动前用以下命令确认该层是否生效：
+
+```powershell
+dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-text-editor"
+```
+
+`edit_text` / `write_text` 与原生工具不重名，插入宿主组合不会产生注册冲突。
+
+卸载：`dsh plugin --profile web remove @flotiarenor/dsh-tool-text-editor`。
+
+两种方式可以并存：同名时 preset 层的注册会遮蔽宿主层的注册，二者定义相同、行为一致。
+
+## 工具契约
+
+### `edit_text` —— 局部替换
+
+| 参数          | 必填 | 说明                                                                     |
+| ------------- | ---- | ------------------------------------------------------------------------ |
+| `file_path` | ✅   | 目标文件；相对路径按会话工作区解析。                           |
+| `new_text`  | ✅   | 替换或插入的内容。                                                       |
+| `old_text`  | -    | 字面量锚点（可直接复制 `read` 的输出）。                            |
+| `grep`      | -    | 正则锚点：命中的行或行块作为锚点（含行尾换行符）。                       |
+| `lines`     | -    | 行号锚点，如 `"263:270"` 或 `"120"`。                                 |
+| `mode`      | -    | `replace`（默认）/ `after` / `before` / `append` / `prepend`。 |
+| `count`     | -    | 要求恰好 N 处命中并全部替换（不符则拒绝写入）。                |
+| `nth`       | -    | 只替换第 k 处（1-based）。                                               |
+| `strict`    | -    | 禁用宽松匹配（只接受精确匹配）。                                         |
+| `dry_run`   | -    | 只输出 diff，不写入文件。                                                |
+| `note`      | -    | 一行说明，记入编辑台账。                                                 |
+
+`old_text` / `grep` / `lines` **必须且只能提供一个**；`append` / `prepend` 不接受锚点，`after` / `before`
+只能与 `grep` / `lines` 搭配。数量不符将拒绝写入。`count` 与 `nth` 互斥。
+
+### `write_text` —— 整文件新建/覆盖
+
+`file_path` + `content`；目标不存在时自动新建，覆盖前先备份。新建文件的行尾风格取自
+同目录的多数派（同扩展名优先），默认不写 BOM。
+
+## 已知限制
+
+以下均为有意的设计取舍，而非缺陷；采用前请对照自身场景确认。
+
+- **写入不经由 `ctx.fs`。** 文件由本插件直接写入，因此不经过 fs 观察策略（先读后写、版本新鲜度校验）、
+  沙箱与 `sandbox_permissions` 审批升权，也不保留 Windows DACL。对应地，Web UI 不会生成 diff 卡片
+  （模型仍可读到文本 diff）。
+- **行号锚点不做内容校验。** `lines` 与 `before` / `after <行号>` 仅按行号定位：行号有误不会报错，
+  改动会落在非预期位置；定位需要可校验时，请改用 `old_text` 或 `grep`。
+- **同目标串行仅限本进程。** 进程内按目标路径排队，并配合原子写，故并行的工具调用不会相互覆盖；
+  但另一个 dsh 实例、编辑器或其它进程同时修改同一文件时，仍可能相互覆盖，本插件也不检测外部改动。
+- **仅处理 UTF-8 文本。** 含 NUL 字节的二进制文件与非法 UTF-8 文件一律拒绝；`.git/`、`.dsh/` 内部
+  以及工作区之外的路径一律拒绝写入。
+
+## 配置
+
+本插件不定义 Config schema：preset 行的 `config:` 字段原样透传。
+
+| 键               | 默认              | 含义                                             |
+| ---------------- | ----------------- | ------------------------------------------------ |
+| `backup`       | `true`          | 写入前把原内容复制到 `artifactsDir/backups`     |
+| `ledger`       | `true`          | 往 `artifactsDir/edits.log` 追加一条 JSONL 记录 |
+| `artifactsDir` | `<工作区>/.dsh` | 备份与台账所在目录                               |
+| `newFileBom`   | `false`         | 新建文件时是否写 UTF-8 BOM                       |
+| `context`      | `3`             | unified diff 的上下文行数                        |
+| `root`         | `process.cwd()` | 无 agent 会话时的回退工作区                      |
+
+环境变量 `DSH_TEXT_EDITOR_EOL`（`lf` \| `crlf`）可覆盖**新建文件**的行尾推断。
+
+## 自测与门禁
+
+```powershell
+# 在本仓库根目录执行
+node tools/selftest.mjs        # Windows + Node 24 参考结果 75/75
+node tools/check-license.mjs   # 许可证 / 依赖 / 纯 Node 门禁
+node tools/gen-schema.mjs      # 内嵌 schema 是否仍与作者 DSL 一致
+```
+
+`tools/selftest.mjs` 覆盖：BOM 与行尾保真、`dry_run`、四种锚点、`count`、歧义时拒绝写入、用法错误、
+二进制与非法 UTF-8、路径护栏（`.dsh/`、工作区之外）、行尾多数派推断、跨多个 hunk、末尾换行差异、
+并发写入不产生半截文件；**并含一层插件层断言**：以模拟 ctx 驱动 `apply()`，验证工具注册、引导段
+身份、每个返回值均满足 `OUTPUT_SCHEMA`、`render()` 输出，以及 config 透传（`root` / `backup` /
+`ledger` / `newFileBom`）。
+
+`tools/gen-schema.mjs` 需要一份装有 `@deepseek-ai/dsh-tools` 的 dsh：它会在 dsh profile 的
+`node_modules` 与 npm 全局目录中自动查找，也可用 `DSH_TOOLS_ENTRY` 显式指定；找不到入口时退出码为 2。
+
+## 目录结构
+
+```
+lib/core.mjs             # 编辑核心：BOM/行尾、锚点、匹配、diff、备份、台账、原子写、同目标串行
+lib/editor.mjs           # 插件本体：schema、参数校验、工具注册（零依赖 ESM，无构建）
+preset/preset.yml        # preset 的名字/描述（dsh 列表里显示的内容）
+scripts/install-preset.mjs  # 从本机 dsh 派生用户 preset
+cordis.patch.yml         # 宿主平面安装用的 bundle patch
+tools/selftest.mjs       # 端到端自测（核心 + 插件层）
+tools/check-license.mjs  # 许可证 / 依赖 / 纯 Node 卫生门禁
+tools/gen-schema.mjs     # 内嵌 schema 的权威来源与校验器
+```
+
+备份与台账采用固定的命名与字段：每次编辑在 `.dsh/backups/` 下留存一个文件，命名为
+`<绝对路径扁平化>@<时间戳>`；`.dsh/edits.log` 每行一个 JSON 对象（`time`、`id`、`tool`、`file`、
+`abspath`、`action`、`kinds`、`line_start`、`line_end`、`added`、`removed`、`bom`、`eol`、
+`backup`、`summary`）。
+
+## License
+
+**Apache-2.0**，见 [LICENSE](LICENSE)。Copyright 2026 Flotiarenor。本包**零运行时依赖**，因此不承担
+任何第三方许可证义务。
+
+- `lib/editor.mjs` 内嵌的 JSON Schema 是 `@deepseek-ai/dsh-tools`（MIT，Copyright (c) 2026 DeepSeek）
+  转换器的**生成产物**（由 `tools/gen-schema.mjs` 离线生成）。
+- preset 组合**不在本包内**：`scripts/install-preset.mjs` 在安装时读取使用者所装 dsh 自带的组合。
+- 源文件均带 `SPDX-License-Identifier` 头，许可证**逐文件机器可读**。

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 Flotiarenor
+# SPDX-License-Identifier: Apache-2.0
+# dsh-tool-text-editor bundle patch：把 edit_text / write_text 两个工具行插进 profile 的宿主组合，
+# 从而对**所有**会话可见（不限于某一个 preset）。
+#
+#   dsh plugin --profile web add link:<本仓库的绝对路径>
+#   # 然后重启 dsh web
+#
+# 为什么可以走宿主平面：本插件注册的是 `edit_text` / `write_text` 两个**不与原生工具重名**的工具，
+# 不存在同名注册冲突；它也消费宿主服务（tools / systemPrompt）、不发布任何服务，实现是纯 Node
+# （进程内、零依赖、不启动外部进程），因此宿主平面插入没有额外依赖。
+#
+# 与 preset 安装方式的区别：
+#   * 这里（宿主层）= 每个会话都有这两个工具，任何 preset 都能用；
+#   * `scripts/install-preset.mjs`（preset 层）= 只有选了这个 preset 的会话有，
+#     其它项目/会话的工具表保持干净。
+# 两种方式可以同时存在：preset 层的注册在同名时遮蔽宿主层的，定义相同、行为一致。
+#
+# 卸载：`dsh plugin --profile web remove @flotiarenor/dsh-tool-text-editor`，再重启 dsh web。
+- insert:
+    - id: tool-text-editor
+      name: '@flotiarenor/dsh-tool-text-editor'