前言¶

在 DeepSeek Harness（DSH）里，智能体经常要分页读文件、再按行改代码。若读和写之间文件被其他进程或并行工具改过，普通「按行号替换」容易覆盖新内容或产生冲突。DSH 内置的 read/edit 并不自带「读时快照 + 写前再验」这一套机制。@lightjunction/dsh-hashline（仓库 LIghtJUNction/dsh-hashline）为 DSH 增加 hashline_read 与 hashline_edit，读取时返回整文件 SHA-256 revision 和每行的 LINE:HASH 锚点，编辑时同时校验 revision 与锚点，不一致则拒绝写入。维护者为 LIghtJUNction，社区目录分类为工作流；行为思路来自 coctostan/pi-hashline-readmap（MIT），本仓库为独立 DSH 实现，首版不替换 DSH 内置 read/edit。

这是什么¶

一句话：Stale-safe hash-anchored line editing for DSH——在 DSH 工具链里做「过期安全」的行级编辑。

插件向 Cordis 注册两个工具名：hashline_read、hashline_edit。读结果里带完整文件 revision、带哈希前缀的行文本、分页字段；写操作必须带上读时得到的 revision 和起止行的 LINE:HASH 锚点。任意文件变化（包括编辑范围之外）都需要重新读取后再编辑。

核心功能¶

下面只列 README 与 package 中已说明的能力。

hashline_read¶

• 参数示例：path、offset（从 1 开始）、limit（每页最多 1000 行）。
• 返回：revision（整文件 SHA-256）、lines（形如 12:0123456789abcdef|原文）、totalLines、nextOffset（为 0 表示没有下一页）。

hashline_edit¶

• 必须提供读返回的 revision 以及锚定的 start（和可选的 end）。
• operation 支持 replace；省略 end 表示只替换一行。insert_after 在 start 行后插入，不接受 end。
• text 为行内容；末尾换行不会多出一空行；replace 且 text 为空时删除范围。
• 写入保留原文件 LF/CRLF、末尾换行习惯和普通权限位；使用同目录临时文件并原子 rename，提交前再次检查哈希、inode 和路径。

与上游 pi 实现的差异（v0.1）¶

• 行哈希为 SHA-256 的 16 位十六进制，并要求整文件 revision；与上游 xxhash 三位锚点不兼容。
• 不含 readmap、AST 搜索、模糊锚点重定位、copy/move lines、语法检查或 TUI diff；README 明确不应把这些未实现能力算作已迁移。

边界与拒绝条件¶

• 默认通过当前 agent 的 workingDirectory 定位工作区；无 agent 的宿主需在插件 overlay 配置 root（绝对路径仓库根）。
• 只处理宿主机本地文件系统，不使用 DSH remote world 或 sandbox 文件接口。
• 拒绝：工作区外路径、路径分量中的符号链接、.git 元数据、目录、多重硬链接、非 UTF-8/NUL、混合换行、超过 1 MiB 的文件。
• 不创建文件、不提供跨文件事务；不保留 inode、ACL、扩展属性或特殊权限位。

安装与启用¶

面向 Node.js 24+、DeepSeek Harness 0.2.1-rc.2。当前交付为源码与本地构建，README 未表示已发布 npm。插件以当前 dsh 进程权限访问本地磁盘，安装前请自行审阅源码与 MIT 许可证。

在已安装 monorepo 依赖的目录执行：

npm run check --workspace @lightjunction/dsh-hashline
cd plugins/dsh-hashline
npm pack
dsh plugin --profile web add "$PWD/lightjunction-dsh-hashline-0.1.0.tgz" --ignore-scripts

npm pack 会触发构建；不要把未构建的源码直接当编译入口安装。重启目标 profile 后，在工具列表确认 hashline_read 和 hashline_edit。TUI 使用者将命令中的 web 换成实际 profile 名。

本地验证（不含远程模型或 remote world）：

npm run check --workspace @lightjunction/dsh-hashline

典型用法¶

先做分页读取。下面 JSON 为 hashline_read 参数示例：

{"path":"src/example.ts","offset":1,"limit":100}

从返回结果中取出实际的 revision 和行锚点（如 12:0123456789abcdef），再调用 hashline_edit：

{"path":"src/example.ts","revision":"<read 返回的 revision>","operation":"replace","start":"<起始 LINE:HASH>","end":"<结束 LINE:HASH>","text":"替换后的代码"}

单行替换可省略 end；范围外或 revision 过期时编辑会被拒绝，应重新 hashline_read 后再写。

适用场景与注意¶

适合谁： 需要在 DSH agent 循环里稳定做「读—改—再读」、且希望避免静默覆盖并发修改的开发者；分类上归入工作流类插件，与目录页 skillhub.cn 条目 一致。

务必注意：

• 插件不是路径隔离沙箱，以 dsh 进程权限读写工作区内的普通文件。
• README 说明无法通过 Node 可移植 API 排除所有「外部进程同时替换父目录」的竞态。
• 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装来源以 GitHub 仓库与上述 pack 流程为准。

结尾¶

dsh-hashline 把「整文件 revision + 行哈希锚点」接到 DSH 工具面，让行级编辑在文件已变 stale 时失败而不是误写。需要细节、Issue 或上游说明时，见 GitHub README 与目录页 https://www.skillhub.cn/plugins/LIghtJUNction/dsh-hashline。