Pine/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity

docs: rescan rebased documentation hierarchy

Browse Source
This commit is contained in:
Turtle
2026-08-05 12:46:38 +08:00
parent 012bb0a549
commit 8af3babaea
304 changed files with 1091 additions and 1983 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/storage/README.i18n.yaml
+2 -2
View File
@@ -2,5 +2,5 @@
# 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/storage/README.md
README.md: c9eca7355fd63e1023e9723486c86673e4c3574b
README.zh.md: 43449f0a7a72e48dbd8a6b5d731f130f04f2d780
README.md: a5f9d0204b93445699d28b1285a4a18f0408930e
README.zh.md: 0710dfb57f96011755b253ad95a0f9d2c0923a70
packages/storage/README.zh.md
+6 -6
View File
@@ -2,13 +2,13 @@
[English](README.md) | 中文
存储家族持久化会话事件日志之外的一切数据：命名后端与类型化数据形式在一个中心相接。设计记录：[领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)。
本家族通过具名后端和类型化数据形式，持久化会话事件日志以外的应用数据。
| 包 | 职责 | ctx key |
|---|---|---|
| `storage/` | 中心：命名后端注册表 + 可通过合并扩展的数据形式挂载、后端分面词汇、共享一致性测试套件 | `ctx.storage` |
| `storage-json/` | JSON 后端：每个单元一个人类可读文件，以原子方式重写整个文件 | 注册后端 `json` |
| `storage-sqlite/` | SQLite 后端：一个数据库承载所有已路由单元，每行一个文档 | 注册后端 `sqlite` |
| `domain/` | 领域数据形式：经 zod 验证的记录、逐领域写入链、`domain/changed` 事件、按配置路由后端 | `ctx.storageDomain` + `ctx.storage.domain` |
| [`storage/`](storage/README.md) | 将已注册后端与类型化数据形式连接起来 | `ctx.storage` |
| [`storage-json/`](storage-json/README.md) | 在 JSON 文件中存储数据 | 注册后端 `json` |
| [`storage-sqlite/`](storage-sqlite/README.md) | 在 SQLite 中存储数据 | 注册后端 `sqlite` |
| [`storage-domain/`](storage-domain/README.md) | 提供经过验证的领域记录存储 | `ctx.storageDomain` |
每个后端拥有一种介质，并公开数据形状**分面**（目前为 `kv`；为未来的会话后端迁移预留追加日志分面）。每个后端插件都会在注册后发布内部生命周期服务；领域插件在公开自身服务前注入每个已配置的后端 key，因此配置树中的条目顺序不影响启动顺序。消费方绝不直接接触后端，而是注入 `storageDomain` 并通过它打开已声明的领域。
消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
packages/storage/storage/README.i18n.yaml
+2 -2
View File
@@ -2,5 +2,5 @@
# 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/storage/storage/README.md
README.md: 994285842925539e73f8f11780f19495f71d0280
README.zh.md: 9e03b5cf09350d3af134e2c7b099f9379fa917f1
README.md: bf827220afe0d8b1cbc53b3a12e6d0034004e1d2
README.zh.md: 6c1a5b4c05f665cdedd16fa67b47c87a04737e7b
packages/storage/storage/README.md
+3 -12
View File
@@ -2,22 +2,13 @@
English | [中文](README.zh.md)
Storage hub (`ctx.storage`) for non-session data: a named backend registry plus mounted data-form facilities. The hub performs no IO itself — backends own media, data forms own semantics. Design and trade-offs: [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
Storage hub (`ctx.storage`) for non-session data: a named backend registry plus mounted data-form facilities. The hub performs no IO itself — backends own media, and data forms own semantics. The [storage family overview](../README.md) maps those packages; the [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the design rationale.
## Shape
- `ctx.storage.backend` — name → backend table. Multiple backends stay mounted side by side (`json`, `sqlite`); which backend serves a consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register()` returns the disposer; duplicate names and unknown lookups fail loud.
- `ctx.storage.mount(form, facility)` / `ctx.storage.form(form)` — data-form mounting. `StorageForms` is merge-extensible; the domain layer merges `domain` and is reached as `ctx.storage.domain`.
- A backend owns one medium (file-tree root, database file) and exposes optional data-shape **facets** — `kv` today; an append-log facet is reserved for the future session-backend migration. `src/backend.ts` is the normative contract text; `tests/contract.ts` exports the shared conformance suite every backend runs.
## Packages in this group
| Package | Role |
| --- | --- |
| `dsh-storage` | The hub service + backend vocabulary + shared conformance suite |
| `dsh-storage-json` | JSON backend: one unit per human-readable file, atomic whole-file rewrite |
| `dsh-storage-sqlite` | SQLite backend: one database hosting all routed units, document-per-row |
| `dsh-storage-domain` | Domain data form (`ctx.storage.domain`): typed schemas, write chain, change events |
- A backend owns one medium and exposes the data-shape facets it supports. `kv` is the current facet; `src/backend.ts` owns its exact contract.
## Model Experience
@@ -37,5 +28,5 @@ Independent of live requests: the hub never touches a request prefix, so it cann
## Known Limitations and Deferred Work
- **`kv` is the only data shape** — the append-log facet the future session-backend migration needs is reserved in the design note but not yet defined; backends currently have exactly one facet to implement.
- **`kv` is the only data shape** — backends currently have one facet to implement.
- **Forms resolve lazily** — reading `ctx.storage.domain` before the domain plugin mounts throws `form-not-mounted`; assemblies order plugins accordingly (misconfiguration fails loud rather than silently deferring).
packages/storage/storage/README.zh.md
+3 -12
View File
@@ -2,22 +2,13 @@
[English](README.md) | 中文
非会话数据的存储中心（`ctx.storage`）：命名后端注册表加已挂载的数据形式设施。中心自身不执行 IO：后端拥有介质，数据形式拥有语义。设计与取舍见[领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)。
非会话数据的存储中心（`ctx.storage`）：具名后端注册表加已挂载的数据形式设施。中心自身不执行 IO：后端拥有介质，数据形式拥有语义。[存储家族概述](../README.md)列出了这些包；[领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了设计理由。
## 结构
- `ctx.storage.backend`：名称 → 后端表。多个后端并排保持挂载（`json`、`sqlite`）；为消费方提供服务的后端由该消费方自身的配置决定（领域层的路由表），绝非中心的全局选择。`register()` 返回资源释放函数；注册重复名称或查找未知名称时都会明确报错。
- `ctx.storage.mount(form, facility)`／`ctx.storage.form(form)`：数据形式挂载。`StorageForms` 可通过合并扩展；领域层合并 `domain`，并通过 `ctx.storage.domain` 访问。
- 后端拥有一种介质（文件树根、数据库文件），并公开可选的数据形状**分面**：目前为 `kv`；为未来的会话后端迁移预留追加日志分面。`src/backend.ts` 是规范契约文本；`tests/contract.ts` 导出每个后端都会运行的共享一致性测试套件。
## 该分组中的包
| 包 | 职责 |
| --- | --- |
| `dsh-storage` | 中心服务 + 后端词汇 + 共享一致性测试套件 |
| `dsh-storage-json` | JSON 后端：每个单元一个人类可读文件，以原子方式重写整个文件 |
| `dsh-storage-sqlite` | SQLite 后端：一个数据库承载所有已路由单元，每行一个文档 |
| `dsh-storage-domain` | 领域数据形式（`ctx.storage.domain`）：类型化 schema、写入链、变更事件 |
- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；其确切契约由 `src/backend.ts` 负责。
## 模型体验
@@ -37,5 +28,5 @@
## 已知限制与暂缓事项
- **`kv` 是唯一的数据形状**：设计记录为未来的会话后端迁移预留了 append-log facet，但尚未定义；后端目前恰好只有一个 facet 需要实现。
- **`kv` 是唯一的数据形状**：后端目前只有一个分面需要实现。
- **数据形式按需解析**：在领域插件挂载前读取 `ctx.storage.domain` 会抛出 `form-not-mounted`；组装会按相应顺序排列插件（错误配置会明确报错，而不是静默推迟处理）。