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

doc(packages): add the host/ and client/ group READMEs and table rows

Browse Source 
Both web-GUI groups shipped without the group README that the packages
table names as each group's canonical package/ctx-key map, and without
rows in that table. Adds both bilingual pairs, the two table rows
(ceiling 835→870: two genuinely new product groups joined the canonical
table at minimal row width), and fixes webserver README drift
(WebServerService/ctx.webServer → HttpServerService/ctx.httpServer,
matching src/index.ts).
This commit is contained in:
creatixchu
2026-07-28 15:04:59 +08:00
parent 01d68dee4e
commit d1ce22e7ad
13 changed files with 116 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/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/README.md
README.md: d16e395a42e491461c0862227205931894c27e39
README.zh.md: 3fb4181ce7ae7b0d79a13ca4358b9df39d83ef1f
README.md: ed1c2b65ef53793baf905791179b474c2f696637
README.zh.md: 14c91a5e1899e1df6c9ceedb274423a4b8e12461
packages/README.md
+2
View File
@@ -43,6 +43,8 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
| [`ui/`](ui/README.md) | Human/client integrations: TUI and JSON-RPC, approval/interaction seams, ask-user tool | Product — stable surface |
| [`host/`](host/README.md) | Web-GUI host half: shared API gateway + HTTP route server | Product — stable surface |
| [`client/`](client/README.md) | Web-GUI browser half: shell, wire consumer, object services, slot system, `ui-*` feature plugins | Product — stable surface |
| [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
packages/README.zh.md
+2
View File
@@ -43,6 +43,8 @@
| [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
| [`ui/`](ui/README.md) | 人类／客户端集成：TUI 与 JSON-RPC、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
| [`host/`](host/README.md) | web GUI 宿主半侧：共享 API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
| [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议消费层、对象服务、slot 系统、`ui-*` 特性插件 | 产品：稳定表面 |
| [`examples/`](examples/README.md) | 演示组合包（agent-spine + TUI/CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
| [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
| [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
packages/client/README.i18n.yaml
+6
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/client/README.md
README.md: b111d67fa49e06227e324a33bd53417ad28c3a5b
README.zh.md: b498008eb82f6ab357718f2af761f38e51140ef8
packages/client/README.md
+34
View File
@@ -0,0 +1,34 @@
# client/ — web-GUI browser half
English | [中文](README.zh.md)
The browser side of the dsh web GUI: shell kernel, module system, wire consumer, React-free object services, the slot system, and the `ui-*` feature-plugin roster. Authoring rules live in [AGENTS.md](AGENTS.md); the host half is [`host/`](../host/README.md). All **product** packages, named `@deepseek-ai/dsh-client-<name>`.
| Package | Role | ctx key / slot |
|---|---|---|
| `web/` | Shell kernel: `AppWebEntry` runs the two-stage boot over the host-pushed entry graph | (boots the tree) |
| `modules/` | Client module system: browser peer of Node's ESM loader as a lazy CJS table under the vendored cordis Loader | (module face) |
| `web-react/` | Shell-side React glue: `createSlotRenderer` + `SessionProvider` render seats | (renderer install) |
| `connection/` | Wire consumer both ends: browser `ctx.connection` (shared api client + stream loop) and the node half mounting the `/api` route with its browser-trust fence | `ctx.connection` |
| `runtime/` | Client cordis boot and React-free object services: slots, Sessions, Workspaces, per-session bindings | `ctx.slots` `ctx.sessions` `ctx.workspaces` |
| `hmr/` | Dev-only hot reload for fetch-arrival client plugins (`--dev` graphs) | (dev entry) |
| `locale/` | Browser locale preference (`zh`/`en`) plus the ns×locale dictionary registry | `ctx.locale` |
| `ui-slots/` | Slot registry pure core: SlotMap merging, single `register` API, the four-share props family | (types + core) |
| `ui-theme/` | Theme preference over the `--dsw-*` token stylesheets (`light`/`dark`/`system`) | `ctx.theme` |
| `ui-primitives/` | Pure React atoms: icons, Button/Pill/Menu/Modal/Input, markdown family | (component library) |
| `ui-layout/` | Shell three-column AppFrame; declares `sidebar` / `conversation` / `details` / `conversation.empty` | `ctx.layout` |
| `ui-sidebar/` | Sidebar shell: Workspace/session rail, search, collapse; declares `sidebar.workspaces` | (slot host) |
| `ui-workspace/` | Shared Workspace picker: browser region + hero picker over the same creation flow | (fills `sidebar.workspaces`, `conversation.hero.workspace`) |
| `ui-conversation/` | Conversation domain: skeleton, chat view, input dock, per-tool row slots | (slot host) |
| `ui-trajectory/` | Trajectory/Waterfall view tabs; the minimal pure-consumer plugin exemplar | (fills `conversation.view`) |
| `ui-command/` | Command surface: session-keyed directory cache, `/` source, three-kind dispatch | `ctx.command` |
| `ui-slash/` | Input trigger pipeline: `/` and `@` detection, grouped candidate menu, source roster | `ctx.slash` |
| `ui-skill/` | `/`-trigger skill reference source over the `skill.list` RPC | (registers into `ctx.slash`) |
| `ui-subagent/` | `@`-trigger subagent reference source over the sessions snapshot | (registers into `ctx.slash`) |
| `ui-model/` | Model selection: `/model` popupSelect + the composer model seat over `ModelService` | `ctx.models` |
| `ui-question/` | Web `ask_user_question`: host half mounts the tool, browser half fills the composer seat | (fills `conversation.composer`) |
| `ui-settings/` | Settings shell: trigger chrome + modal panel; declares the `settings.*` slots | (slot host) |
| `ui-settings-general/` | Settings ownerless copy: chrome content + General section skeleton | (fills `settings.*`) |
| `ui-models/` | Models settings nav entry (content column lands in a later phase) | (fills `settings.section`) |
Feature UI composes only through the slot system (`ctx.slots.register`) — the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) is the definitive model; the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) owns the loading chain and object layer.
packages/client/README.zh.md
+34
View File
@@ -0,0 +1,34 @@
# client/ — web GUI 浏览器半侧
[English](README.md) | 中文
dsh web GUI 的浏览器侧：shell 内核、模块系统、协议消费层、无 React 依赖的对象服务、slot 系统，以及 `ui-*` 特性插件阵列。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。全部为**产品**包，命名为 `@deepseek-ai/dsh-client-<name>`。
| 包 | 角色 | ctx 键／slot |
|---|---|---|
| `web/` | shell 内核：`AppWebEntry` 基于宿主推送的条目图运行两阶段启动 | （启动整棵树） |
| `modules/` | 客户端模块系统：Node ESM 加载器的浏览器对等物，是 vendored cordis Loader 之下的惰性 CJS 表 | （模块面） |
| `web-react/` | shell 侧 React 胶水：`createSlotRenderer` + `SessionProvider` 渲染座位 | （渲染器安装） |
| `connection/` | 协议两端的消费者：浏览器侧 `ctx.connection`（共享 api 客户端 + 流循环），node 半侧挂载带浏览器信任栅栏的 `/api` 路由 | `ctx.connection` |
| `runtime/` | 客户端 cordis 启动与无 React 对象服务：slots、Session、Workspace、逐会话绑定 | `ctx.slots` `ctx.sessions` `ctx.workspaces` |
| `hmr/` | 仅开发用的 fetch 到达型客户端插件热重载（`--dev` 图） | （开发条目） |
| `locale/` | 浏览器语言偏好（`zh`／`en`）与 ns×locale 词典注册表 | `ctx.locale` |
| `ui-slots/` | slot 注册表纯核心：SlotMap 合并、单一 `register` API、四份额 props 族 | （类型 + 核心） |
| `ui-theme/` | 基于 `--dsw-*` token 样式表的主题偏好（`light`／`dark`／`system`） | `ctx.theme` |
| `ui-primitives/` | 纯 React 原子：图标、Button/Pill/Menu/Modal/Input、markdown 族 | （组件库） |
| `ui-layout/` | shell 三栏 AppFrame；声明 `sidebar`／`conversation`／`details`／`conversation.empty` | `ctx.layout` |
| `ui-sidebar/` | 侧栏 shell：Workspace/会话栏、搜索、折叠；声明 `sidebar.workspaces` | （slot 宿主） |
| `ui-workspace/` | 共享 Workspace 选择器：浏览区域 + hero 选择器共用同一创建流程 | （填充 `sidebar.workspaces`、`conversation.hero.workspace`） |
| `ui-conversation/` | 会话域：骨架、聊天视图、输入坞、逐工具行 slot | （slot 宿主） |
| `ui-trajectory/` | Trajectory／Waterfall 视图标签；最小纯消费者插件范例 | （填充 `conversation.view`） |
| `ui-command/` | 命令面：按会话键控的目录缓存、`/` 源、三类分发 | `ctx.command` |
| `ui-slash/` | 输入触发流水线：光标下的 `/` 与 `@` 检测、分组候选菜单、源名册 | `ctx.slash` |
| `ui-skill/` | 基于 `skill.list` RPC 的 `/` 触发技能引用源 | （注册进 `ctx.slash`） |
| `ui-subagent/` | 基于会话快照的 `@` 触发子代理引用源 | （注册进 `ctx.slash`） |
| `ui-model/` | 模型选择：`/model` popupSelect + 输入坞模型座位，均由 `ModelService` 驱动 | `ctx.models` |
| `ui-question/` | Web `ask_user_question`：宿主半侧挂载工具，浏览器半侧填充输入坞座位 | （填充 `conversation.composer`） |
| `ui-settings/` | 设置 shell：触发 chrome + 模态面板；声明 `settings.*` slot | （slot 宿主） |
| `ui-settings-general/` | 设置的无主文案：chrome 内容 + General 分区骨架 | （填充 `settings.*`） |
| `ui-models/` | 模型设置导航项（内容列留待后续阶段） | （填充 `settings.section`） |
特性 UI 只通过 slot 系统组合（`ctx.slots.register`）——[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威模型；[web 客户端架构 Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) 拥有加载链与对象层。
packages/host/README.i18n.yaml
+6
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/host/README.md
README.md: 61e50cb64b95932085342b01a22d029cf8d5a228
README.zh.md: 3109eccf89ee4c2d4d01be546e3ee9ead9084edc
packages/host/README.md
+12
View File
@@ -0,0 +1,12 @@
# host/ — web-GUI host half
English | [中文](README.zh.md)
The host side of the dsh web GUI: the API gateway every client shape shares, and the plain HTTP server it rides on. The browser side lives in [`client/`](../client/README.md); the composed application is [`apps/cli`](../../apps/cli/cordis.yml) serving [`apps/web`](../../apps/web/). All **product** packages.
| Package | Role | ctx key |
|---|---|---|
| `apiproxy/` | The shared API gateway: the zero-Node TS wire contract (`src/api/`), the fetch carrier pair (`toFetchHandler` host-side, `AbstractApiClient` client-side), and the host implementation over `ctx.agents`/`ctx.workspace` | `ctx.apiProxy` |
| `webserver/` | Plain HTTP route-registration carrier: `node:http` server listening on activation; routes register as named `exact`/`prefix` handlers | `ctx.httpServer` |
`apiproxy` is transport-agnostic by design — it registers no routes; carriers wrap `ctx.apiProxy` themselves. The HTTP carrier route (with its `/api` browser-trust fence) is mounted by [`client/connection`](../client/connection/README.md)'s node half, which is why that package lives in the client group: it owns both ends of the wire.
packages/host/README.zh.md
+12
View File
@@ -0,0 +1,12 @@
# host/ — web GUI 宿主半侧
[English](README.md) | 中文
dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承载它的纯 HTTP 服务器。浏览器侧位于 [`client/`](../client/README.md)；组合后的应用是 [`apps/cli`](../../apps/cli/cordis.yml)，它负责服务 [`apps/web`](../../apps/web/)。全部为**产品**包。
| 包 | 角色 | ctx 键 |
|---|---|---|
| `apiproxy/` | 共享 API 网关：零 Node 依赖的 TS 协议契约（`src/api/`）、fetch 载体对（宿主侧 `toFetchHandler`、客户端侧 `AbstractApiClient`），以及基于 `ctx.agents`／`ctx.workspace` 的宿主实现 | `ctx.apiProxy` |
| `webserver/` | 纯 HTTP 路由注册载体：激活即监听的 `node:http` 服务器；路由以命名的 `exact`／`prefix` 处理器注册 | `ctx.httpServer` |
`apiproxy` 在设计上与传输方式无关——它不注册任何路由；载体自行包装 `ctx.apiProxy`。HTTP 载体路由（连同其 `/api` 浏览器信任栅栏）由 [`client/connection`](../client/connection/README.md) 的 node 半侧挂载，这正是该包住在 client 组的原因：它拥有这条线的两端。
packages/host/webserver/README.i18n.yaml
+3 -3
View File
@@ -1,6 +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
README.md: c589c32c4e641e188f19ac6c5ad2e88e3eb79be3
README.zh.md: 767195086b90a76160d87865caebf514ca75b0e3
# pnpm run verify-translation-pairing --write packages/host/webserver/README.md
README.md: e715e4452ddb808f36e6b097eee0fda7b8d0bfb0
README.zh.md: 05e7e10d7815c8f26bb90597b38b7c6b83a86dbc
packages/host/webserver/README.md
+1 -1
View File
@@ -2,7 +2,7 @@
English | [中文](README.zh.md)
Plain HTTP route-registration plugin (default-exported `WebServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.webServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics.
Plain HTTP route-registration plugin (default-exported `HttpServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.httpServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics.
The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
packages/host/webserver/README.zh.md
+1 -1
View File
@@ -2,7 +2,7 @@
[English](README.md) | 中文
朴素的 HTTP 路由注册插件（默认导出 `WebServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。
朴素的 HTTP 路由注册插件（默认导出 `HttpServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。
该包不了解任何 harness 概念：`/api` 桥接是 connection 插件的路由，插件 bundle 与 HMR（热模块替换）事件流则是 modules／hmr 插件的路由。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）；`distIndex` 是由组合应用解析并注入的组装事实，绝不会自行解析，因为 dist 位置属于应用的工作区知识。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。