docs: bilingual credentials/settings-consumer documentation, catalogs, and gates

New credentials data-structure page (type-equiv manifested), group README,
rewritten llm-deepseek/llm-pi-ai READMEs (dynamic configuration, dict
profiles, credential chain), capability-seams/service-role registration,
Agent Note (bilingual), demo compositions mounting settings-local +
credentials-local with no inline key plumbing, installSettingsSection
consumer helper on the settings seam (deduplicating both adapters' wiring),
jscpd symmetry markers for the provider twins, runtime-closure additions for
python/sdk-runtime, and doc-budget ceilings AGENTS.md 1750→1755 /
packages/README.md 850→865 for the structural one-line group rows.
This commit is contained in:
Yichen Jiang
2026-07-29 14:20:06 +08:00
parent d77db29f01
commit b0a2011d95
61 changed files with 732 additions and 153 deletions

View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# 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: 2cd57a0fa42601e393a41de68af3f9b1e2f033b5
README.zh.md: e8f18a8ec6ef6077f15cebed0062fabc0638ee0e

View File

@@ -9,6 +9,8 @@ Zero-dependency atomic file replacement shared by file-backed stores that must n
```ts
import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
declare const text: string
await writeFileAtomic('/home/u/.dsh/settings.yaml', text, { mode: 0o600 })
```
@@ -24,6 +26,10 @@ One export. The contract, in the order failures would exploit it:
None, as this is a pure filesystem primitive; nothing here reaches a model request.
#### KV Cache effect
None; nothing here enters a request prefix.
## Known Limitations and Deferred Work
- **Atomic, not durable** — no `fsync` of the file or its directory, so after a crash the rename may be observed unwound. The file-backed stores here re-read and republish on boot, keeping durability the caller's policy.

View File

@@ -2,29 +2,35 @@
[English](README.md) | 中文
零依赖的原子文件替换,供绝不允许在磁盘上留下半截内容、被符号链接劫持或权限过宽内容的文件型存储共用——用户设置文档(`dsh-settings-local`)与凭据存储(`dsh-credentials-local`)。
零依赖的原子文件替换,供绝不允许在磁盘上留下不完整、被符号链接劫持或权限过宽内容的文件型存储共用用户设置文档(`dsh-settings-local`)与凭据存储(`dsh-credentials-local`)。
## 接口面
```ts
import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
declare const text: string
await writeFileAtomic('/home/u/.dsh/settings.yaml', text, { mode: 0o600 })
```
仅一个导出。契约按攻击面利用顺序列出:
仅一个导出。契约按故障利用它的先后顺序列出:
- **独占创建临时文件**`wx` + 随机后缀open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
- **全新 inode 携带 `mode` 走完 rename**:替换权限过宽的旧文件时直接收窄,不存在 chmod 竞态。`mode` 为必填,让权限决策始终可见于每个调用点(与所有新建 inode 一样受进程 umask 影响)。
- **`rename` 替换的是符号链接目标本身**,绝不写穿到其指向的文件。
- **同目录兄弟文件**保证 rename 落在同一文件系统上,交换保持原子。
- 自动创建父目录;任何失败都会清理临时文件并重新抛出;读者只会看到旧内容或完整的新内容。
- 自动创建父目录;任何失败都会移除临时文件并重新抛出该失败;读取方只会观察到旧内容或完整的新内容。
## Model Experience
None, as this is a pure filesystem primitive; nothing here reaches a model request.
无:本包是纯文件系统原语,此处没有任何内容会到达模型请求。
#### KV Cache effect
无;此处没有任何内容会进入请求前缀。
## Known Limitations and Deferred Work
- **原子但不保证落盘持久**——不对文件或目录做 `fsync`,崩溃后可能观察到 rename 被回退。此处的文件型存储在启动时重新读取并重新发布,持久化策略留给调用方
- **仅支持字符串内容**——在出现真实消费者之前不提供 `Buffer` 或流式形态。
- **原子但不保证持久**——不对文件或其所在目录做 `fsync`因此崩溃后可能观察到 rename 被回退。此处的文件型存储在启动时重新读取并重新发布,持久性留作调用方的策略
- **仅支持字符串内容**——在有消费方需要之前不提供 `Buffer` 或流式形态。