docs: complete Chinese proofreading and generated reference pairing

This commit is contained in:
xjt
2026-08-09 11:02:16 +08:00
parent 0543a6f79d
commit 7ff0cbcb7e
565 changed files with 10606 additions and 2171 deletions
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
README.zh.md: 799f01be6f27e00b740c7e0a2c68218f99317451
+4 -4
View File
@@ -4,7 +4,7 @@
零依赖的原子文件替换,供绝不允许在磁盘上留下不完整、被符号链接劫持或权限过宽内容的文件型存储共用:用户设置文档(`dsh-settings-local`)与凭据存储(`dsh-credentials-local`)。
## 接口
## 接口
```ts
import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
@@ -20,15 +20,15 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
})
```
`writeFileAtomic` 提交一份已经渲染好的字符串。约按故障利用它的先后顺序列出:
`writeFileAtomic` 提交一份已经渲染好的字符串。约按故障可能利用各项机制的先后顺序列出:
- **独占创建临时文件**`wx` + 随机后缀):open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
- **全新 inode 携带 `mode` 走完 rename**:替换权限过宽的旧文件时直接收窄,不存在 chmod 竞态。`mode` 为必填,让权限决策始终可见于每个调用点(与所有新建 inode 一样受进程 umask 影响)。
- **`rename` 替换的是符号链接目标本身**,绝不写穿到其指向的文件。
- **`rename` 替换的是符号链接本身**,绝不写穿到其指向的文件。
- **同目录兄弟文件**保证 rename 落在同一文件系统上,交换保持原子。
- 自动创建父目录;任何失败都会移除临时文件并重新抛出该失败;读取方只会观察到旧内容或完整的新内容。
`withFileLock` 跨进程串行化同一文件的写入方,服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`,因此读取方从不参与竞争;等待方按指数退避,超时即失败而非无限阻塞。竞争者绝不移除现有锁:锁无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
`withFileLock` 跨进程串行化同一文件的写入方,服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录同级文件 `<filename>.lock`,因此读取方从不参与竞争;等待方按指数退避,超时即失败而非无限阻塞。竞争者绝不移除现有锁:锁文件的存在时长无法区分已经崩溃的属主与被暂停但仍存活的写入方。
## 模型体验