@exagone313/dsh-podman 1.7.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/cordis.patch.yml +3 -1
  2. package/dist/approval-reasons.d.ts +37 -0
  3. package/dist/approval-reasons.js +128 -0
  4. package/dist/approval-template-summary.d.ts +8 -0
  5. package/dist/approval-template-summary.js +163 -0
  6. package/dist/approval.d.ts +8 -4
  7. package/dist/approval.js +104 -10
  8. package/dist/client/ContainerCard.js +8 -2
  9. package/dist/client/container-card-controller.d.ts +13 -5
  10. package/dist/client/container-card-controller.js +60 -24
  11. package/dist/client/container-card-create-config.d.ts +23 -0
  12. package/dist/client/container-card-create-config.js +48 -0
  13. package/dist/client/container-card-create-modal.d.ts +9 -1
  14. package/dist/client/container-card-create-modal.js +37 -41
  15. package/dist/client/container-card-create-volume.d.ts +10 -0
  16. package/dist/client/container-card-create-volume.js +34 -0
  17. package/dist/client/container-card-dialog-styles.d.ts +4 -2
  18. package/dist/client/container-card-dialog-styles.js +47 -4
  19. package/dist/client/container-card-edit-modal.d.ts +5 -1
  20. package/dist/client/container-card-edit-modal.js +55 -19
  21. package/dist/client/container-card-editors.d.ts +9 -0
  22. package/dist/client/container-card-editors.js +300 -43
  23. package/dist/client/container-card-form.d.ts +2 -1
  24. package/dist/client/container-card-form.js +26 -8
  25. package/dist/client/container-card-images.js +9 -31
  26. package/dist/client/container-card-mount-actions.d.ts +12 -0
  27. package/dist/client/container-card-mount-actions.js +35 -0
  28. package/dist/client/container-card-mount-sources.d.ts +34 -0
  29. package/dist/client/container-card-mount-sources.js +180 -0
  30. package/dist/client/container-card-names.d.ts +2 -0
  31. package/dist/client/container-card-names.js +12 -0
  32. package/dist/client/container-card-row.d.ts +16 -1
  33. package/dist/client/container-card-row.js +69 -25
  34. package/dist/client/container-card-secrets.d.ts +2 -0
  35. package/dist/client/container-card-secrets.js +60 -17
  36. package/dist/client/container-card-shared.d.ts +17 -9
  37. package/dist/client/container-card-shared.js +122 -93
  38. package/dist/client/container-card-styles.d.ts +6 -0
  39. package/dist/client/container-card-styles.js +22 -0
  40. package/dist/client/container-card-table-styles.d.ts +2 -1
  41. package/dist/client/container-card-table-styles.js +14 -0
  42. package/dist/client/container-card-templates.d.ts +81 -0
  43. package/dist/client/container-card-templates.js +1004 -0
  44. package/dist/client/container-card-toast.js +1 -1
  45. package/dist/client/container-card-volumes.js +6 -20
  46. package/dist/client/container-card-workspace.d.ts +10 -2
  47. package/dist/client/container-card-workspace.js +98 -5
  48. package/dist/client/container-template-ui.d.ts +163 -0
  49. package/dist/client/container-template-ui.js +579 -0
  50. package/dist/client/download.d.ts +1 -0
  51. package/dist/client/download.js +23 -0
  52. package/dist/client/image-facts.d.ts +18 -0
  53. package/dist/client/image-facts.js +44 -0
  54. package/dist/client/index.js +13478 -3438
  55. package/dist/client/locales.d.ts +1 -1
  56. package/dist/client/locales.js +120 -0
  57. package/dist/client/podman-containers.js +47 -18
  58. package/dist/client/podman-terminal-guide.js +4 -2
  59. package/dist/client/podman-terminal.js +4 -2
  60. package/dist/client/template-client.d.ts +9 -0
  61. package/dist/client/template-client.js +52 -0
  62. package/dist/client/template-protocol.d.ts +60 -0
  63. package/dist/client/template-protocol.js +4 -0
  64. package/dist/client/terminal-errors.d.ts +11 -0
  65. package/dist/client/terminal-errors.js +26 -0
  66. package/dist/client/terminal-protocol.d.ts +5 -0
  67. package/dist/client/terminal-protocol.js +5 -0
  68. package/dist/client/terminal-styles.d.ts +2 -1
  69. package/dist/client/terminal-styles.js +9 -1
  70. package/dist/client/terminal-transport.d.ts +17 -2
  71. package/dist/client/terminal-transport.js +31 -8
  72. package/dist/client/tool-presentations.d.ts +32 -0
  73. package/dist/client/tool-presentations.js +33 -0
  74. package/dist/client/tool-views.js +17 -7
  75. package/dist/client/workspace-target.d.ts +54 -0
  76. package/dist/client/workspace-target.js +86 -0
  77. package/dist/container-template.d.ts +153 -0
  78. package/dist/container-template.js +1058 -0
  79. package/dist/generated/version.d.ts +2 -2
  80. package/dist/generated/version.js +2 -2
  81. package/dist/grpc/proto/dshguest/v1/guest.proto +11 -0
  82. package/dist/guest-rpc.d.ts +1 -0
  83. package/dist/guest-rpc.js +12 -0
  84. package/dist/index.js +7 -1
  85. package/dist/mount-enums.d.ts +2 -0
  86. package/dist/mount-enums.js +17 -0
  87. package/dist/mount-order.d.ts +14 -0
  88. package/dist/mount-order.js +49 -0
  89. package/dist/project-path.d.ts +14 -0
  90. package/dist/project-path.js +25 -0
  91. package/dist/template-apply.d.ts +21 -0
  92. package/dist/template-apply.js +102 -0
  93. package/dist/template-files.d.ts +23 -0
  94. package/dist/template-files.js +186 -0
  95. package/dist/template-image.d.ts +22 -0
  96. package/dist/template-image.js +80 -0
  97. package/dist/template-route.d.ts +9 -0
  98. package/dist/template-route.js +278 -0
  99. package/dist/terminal-route.js +49 -7
  100. package/dist/tool-defs.js +27 -1
  101. package/dist/tool-handlers.js +69 -1
  102. package/dist/tool-params.d.ts +38 -0
  103. package/dist/tool-params.js +30 -0
  104. package/docs/README.md +4 -3
  105. package/docs/architecture.md +42 -12
  106. package/docs/architecture.zh.md +22 -8
  107. package/docs/configuration.md +19 -20
  108. package/docs/configuration.zh.md +3 -4
  109. package/docs/development-prompt.md +49 -45
  110. package/docs/development-prompt.zh.md +47 -43
  111. package/docs/development.md +46 -28
  112. package/docs/development.zh.md +60 -46
  113. package/docs/uninstall.md +3 -3
  114. package/docs/uninstall.zh.md +2 -2
  115. package/docs/usage.md +155 -23
  116. package/docs/usage.zh.md +104 -14
  117. package/package.json +6 -5
@@ -548,3 +548,33 @@ export const daemonLogsParameters = {
548
548
  },
549
549
  required: ["container", "name"],
550
550
  };
551
+ const templateNameParam = {
552
+ type: "string",
553
+ description: 'Template name: a YAML file in the project\'s .dsh-podman directory, with or without the ".yml" suffix.',
554
+ };
555
+ export const containerTemplateLoadParameters = {
556
+ type: "object",
557
+ properties: {
558
+ template: templateNameParam,
559
+ container: {
560
+ type: "string",
561
+ description: 'Logical name of the container to create; defaults to "default".',
562
+ },
563
+ },
564
+ required: ["template"],
565
+ };
566
+ export const containerTemplateExportParameters = {
567
+ type: "object",
568
+ properties: {
569
+ container: containerParam,
570
+ },
571
+ required: ["container"],
572
+ };
573
+ export const containerTemplateSaveParameters = {
574
+ type: "object",
575
+ properties: {
576
+ container: containerParam,
577
+ name: templateNameParam,
578
+ },
579
+ required: ["container", "name"],
580
+ };
package/docs/README.md CHANGED
@@ -24,7 +24,8 @@ SPDX-License-Identifier: MIT
24
24
  - [Development](development.md) — build the plugin from this repository and run
25
25
  it from a development checkout.
26
26
  - [Development container setup prompt](development-prompt.md) — the prompt that
27
- creates the development image, volume and container.
27
+ sets up the workspace's development container from the project's `develop`
28
+ template.
28
29
  - [Uninstall](uninstall.md) — remove dsh-podman and the Quadlet units, and run
29
30
  dsh without it.
30
31
 
@@ -39,7 +40,7 @@ SPDX-License-Identifier: MIT
39
40
  环境变量,以及插件的界面设置。
40
41
  - [使用](usage.zh.md) — 面向模型的工具、Podman 页面以及镜像模型。
41
42
  - [开发](development.zh.md) — 从本仓库构建插件,并在开发检出环境中运行。
42
- - [开发容器设置提示词](development-prompt.zh.md) —
43
- 用于创建开发镜像、卷与容器的提示词。
43
+ - [开发容器设置提示词](development-prompt.zh.md) — 从项目的 `develop`
44
+ 模板设置工作区开发容器的提示词。
44
45
  - [卸载](uninstall.zh.md) — 移除 dsh-podman 与 Quadlet
45
46
  单元,并在没有它的情况下运行 dsh。
@@ -42,15 +42,13 @@ tools): `ListContainers` (returns only the guest containers the orchestrator
42
42
  created — containers it does not own are never exposed),
43
43
  `EnsureContainer{workspace_slug, container}` (the single attach path: returns
44
44
  the named container, recreating it first when it is missing, stopped, or running
45
- an outdated guest agent),
46
- `StartContainer{workspace_slug, container, image_id, mounts, env, secret_env,
47
- paths}`
48
- (creates or replaces a container in the workspace's pod; an empty `container`
49
- targets the default container and other names are validated),
50
- `RecreateContainer{workspace_slug, container, image_id, mounts, env, paths}`
51
- (stops, removes, and recreates a container, optionally with a new image, project
52
- mounts, environment, or PATH additions; an empty `image_id` keeps the
53
- workspace's current image), `RemoveContainer`, `AddContainerMount`,
45
+ an outdated guest agent), `StartContainer{workspace_slug, container, image_id,
46
+ mounts, env, secret_env, paths}` (creates or replaces a container in the
47
+ workspace's pod; an empty `container` targets the default container and other
48
+ names are validated), `RecreateContainer{workspace_slug, container, image_id,
49
+ mounts, env, paths}` (stops, removes, and recreates a container, optionally with
50
+ a new image, project mounts, environment, or PATH additions; an empty `image_id`
51
+ keeps the workspace's current image), `RemoveContainer`, `AddContainerMount`,
54
52
  `UpdateContainerMount`, `RemoveContainerMount`, `SetContainerPaths`,
55
53
  `AddContainerSecret`, and `RemoveContainerSecret`. The service also exposes the
56
54
  workspace, volume, secret, image (build, rebuild, remove and base-image pull),
@@ -139,6 +137,14 @@ and writes files. Each guest container gets exactly one socket directory
139
137
  bind-mounted into it, so a guest never sees the orchestrator's control socket
140
138
  nor any other workspace's socket directory.
141
139
 
140
+ The guest agent also serves `WriteTemplate`, which saves a container-template
141
+ YAML into the project's `.dsh-podman` directory: it creates the directory when
142
+ missing, refuses a name that is not a plain basename, and reports a read-only
143
+ project mount as `PermissionDenied` before any I/O. The plugin's own host view
144
+ of the project is read-only (the dsh container mounts the projects root that
145
+ way), so listing and inspecting templates happen on the host while saving always
146
+ goes through this RPC.
147
+
142
148
  The guest API exposes no watcher, so the plugin's `ctx.fs` provider reports
143
149
  `FS_IO_ERROR` (`Filesystem watching is not supported by this provider.`) for
144
150
  `watch`. The harness's workspace-file change stream therefore answers
@@ -228,6 +234,22 @@ Custom images are layered on top of a parent image and add extra packages. Every
228
234
  build streams its context to the Podman API as a tar holding the generated
229
235
  Containerfile, so a build writes nothing to the orchestrator's state directory.
230
236
 
237
+ Container templates build a deterministic custom image per template:
238
+ `template-<sanitized file basename>-<first 8 hex of sha256(absolute template
239
+ path)>`. The plugin compares the template's canonical package list with what
240
+ `ListImages` reports and rebuilds only when it (or the parent base) differs; a
241
+ template whose packages are all base built-ins names the base image instead and
242
+ builds nothing, and a template image no longer needed is removed once nothing
243
+ references it. Loading a template creates a container through
244
+ `CreateWorkspace`/`StartContainer`, always with the workspace project mount
245
+ added read-write, and publishes its ports after the container exists — a
246
+ publishing failure is a warning, not a failed load. Replacing an existing
247
+ container is an edit: the popup opens the edit editor with the template's fields
248
+ filled in (the fields it omits stay as the container currently has them, and its
249
+ ports stay out of the editor) and the normal edit-apply path updates the
250
+ container, so nothing is removed or recreated up front. The template's ports are
251
+ then published through the same warning-only path.
252
+
231
253
  `image_rebuild_all` first ensures every base image (building locally or pulling
232
254
  from a public registry per `DSH_PODMAN_BASE_IMAGE_PREFIX`), then rebuilds the
233
255
  stored custom images **in dependency order** — each parent before the images
@@ -245,9 +267,10 @@ under a running build.
245
267
 
246
268
  ## Podman page transport
247
269
 
248
- The Podman page talks to the host over one authenticated fetch route below the
249
- harness API path (`/api/podman/card`), registered on the connection service so
250
- the carrier applies its Host/Origin fence and browser authentication first:
270
+ The Podman page talks to the host over authenticated fetch routes below the
271
+ harness API path, registered on the connection service so the carrier applies
272
+ its Host/Origin fence and browser authentication first. The settings card uses
273
+ `/api/podman/card`:
251
274
 
252
275
  - `GET` returns the live orchestrator snapshot (containers, images, workspaces,
253
276
  volumes, secrets, caches), built fresh on every request.
@@ -255,6 +278,13 @@ the carrier applies its Host/Origin fence and browser authentication first:
255
278
  `image_rebuild` / `image_rebuild_all` / volume / secret / secret-env / mount
256
279
  ops) against the orchestrator and returns the notice to show.
257
280
 
281
+ The load-template popup uses its own route (`/api/podman/templates`), because
282
+ its operations return structured results rather than one notice: `GET` lists the
283
+ project's `.dsh-podman` templates from the host filesystem (the read-only view
284
+ the workspace directory picker also reads), and `POST` inspects a template
285
+ (including an upload), builds the image it needs, creates a container from it,
286
+ or publishes the ports of a template whose replace the edit editor applied.
287
+
258
288
  The plugin's own config therefore holds **only real preferences**: the default
259
289
  image, the default environment, and the page's active locale (`uiLocale`, so the
260
290
  host can render approval text in the session language — see
@@ -34,12 +34,14 @@ token(`DSH_PODMAN_ORCHESTRATOR_TOKEN`)作为 `authorization: bearer` 标头
34
34
 
35
35
  orchestrator 服务公开以下 gRPC 方法(同时支撑 UI
36
36
  和工具):`ListContainers`(仅返回 orchestrator 创建的 guest
37
- 容器——它不拥有的容器永远不会被暴露)、`EnsureContainer{workspace_slug, container}`(唯一的接入路径:返回指定容器,若其缺失、已停止或运行过期的
38
- guest
39
- agent,则先重建它)、`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env, paths}`(在工作区的
40
- pod 中创建或替换容器;空的 `container`
41
- 指向默认容器,其他名称会被校验)、`RecreateContainer{workspace_slug, container, image_id, mounts, env, paths}`(停止、删除并重新创建容器,可选择使用新镜像、项目挂载、环境或
42
- PATH 附加项;空的 `image_id`
37
+ 容器——它不拥有的容器永远不会被暴露)、`EnsureContainer{workspace_slug,
38
+ container}`(唯一的接入路径:返回指定容器,若其缺失、已停止或运行过期的 guest
39
+ agent,则先重建它)、`StartContainer{workspace_slug, container, image_id,
40
+ mounts, env, secret_env, paths}`(在工作区的 pod 中创建或替换容器;空的
41
+ `container` 指向默认容器,其他名称会被校验)、`RecreateContainer{workspace_slug,
42
+ container, image_id, mounts, env,
43
+ paths}`(停止、删除并重新创建容器,可选择使用新镜像、项目挂载、环境或 PATH
44
+ 附加项;空的 `image_id`
43
45
  保留工作区当前的镜像)、`RemoveContainer`、`AddContainerMount`、`UpdateContainerMount`、`RemoveContainerMount`、`SetContainerPaths`、`AddContainerSecret`
44
46
  和 `RemoveContainerSecret`。该服务还公开支撑 Podman
45
47
  页面的工作区、卷、机密、镜像(构建、重建、删除以及拉取基础镜像)和缓存(列出与清理)操作,以及
@@ -111,8 +113,8 @@ API,运行并监督后台**守护进程**,并读取和写入文件。每个
111
113
  的 control socket,也不会看到任何其他工作区的套接字目录。
112
114
 
113
115
  Guest API 不提供监视器,因此插件的 `ctx.fs` 提供者对 `watch` 返回
114
- `FS_IO_ERROR`(`Filesystem watching is not supported by this provider.`)。harness
115
- 的工作区文件变更流因此返回
116
+ `FS_IO_ERROR`(`Filesystem watching is not supported by this
117
+ provider.`)。harness 的工作区文件变更流因此返回
116
118
  `workspace-file/watch-unsupported`,浏览器的文件树改为按需刷新,而非实时刷新——与
117
119
  harness 自带的 SSH 文件系统提供者对远程路径采取的做法一致。
118
120
 
@@ -186,6 +188,12 @@ orchestrator 通过 Podman 构建工作区镜像(有关原始/基础/自定义
186
188
  API,因此构建不会向 orchestrator 的状态目录写入任何内容。
187
189
 
188
190
  `image_rebuild_all` 首先确保每个基础镜像(根据 `DSH_PODMAN_BASE_IMAGE_PREFIX`
191
+ 容器模板按模板构建确定的镜像:`template-<净化后的文件基本名>-<模板绝对路径
192
+ sha256 的前 8 个十六进制字符>`。插件把模板的规范软件包列表与 `ListImages`
193
+ 报告的内容比较,仅当列表(或父基础镜像)不同时才重建;软件包全部属于基础镜像内置项的模板改为引用基础镜像、不构建,而不再需要的模板镜像会在无人引用后删除。加载模板通过
194
+ `CreateWorkspace`/`StartContainer`
195
+ 创建或替换容器,始终以读写方式加入工作区项目挂载,并在容器存在后发布端口——发布失败只是警告,不会让加载失败。
196
+
189
197
  在本地构建或从公共注册表拉取),然后**按依赖顺序**重建存储的自定义镜像——每个父镜像都在从它派生的镜像之前。重建失败的镜像以及依赖它的每个镜像都会被报告在
190
198
  `skipped`
191
199
  中,其余镜像继续。本次调用无法构建或拉取的基础镜像也会以短名称报告在那里;`rebuilt`
@@ -195,6 +203,12 @@ API,因此构建不会向 orchestrator 的状态目录写入任何内容。
195
203
  中),构建会复用已下载的软件包。Podman
196
204
  页面会报告每个缓存的大小并可清理它——保留每个软件包的最新版本,或清空缓存。构建器用读写锁将清理与构建串行化,因此清理绝不会在构建进行时删除其正在使用的软件包。
197
205
 
206
+ guest agent 还提供 `WriteTemplate`,把容器模板 YAML 保存到项目的 `.dsh-podman`
207
+ 目录:目录缺失时创建、拒绝不是纯基本名的名称,并在任何 I/O
208
+ 之前把只读项目挂载报告为
209
+ `PermissionDenied`。插件自身对项目的宿主机视图是只读的(dsh 容器就是这样挂载
210
+ projects root 的),因此模板的列出与查看在宿主机侧完成,而保存始终经过该 RPC。
211
+
198
212
  ## Podman 页面传输
199
213
 
200
214
  Podman 页面通过 harness API 路径(`/api/podman/card`)之下的一个已认证 fetch
@@ -112,15 +112,14 @@ alone.
112
112
 
113
113
  ### `DSH_PODMAN_BASE_IMAGE_PREFIX`
114
114
 
115
- Prefix under which base images are tagged, as
116
- `BASE_IMAGE_PREFIX + <short> +
117
- ":latest"`. When the prefix starts with
118
- `localhost/`, base images are **built locally** by the orchestrator from their
119
- upstream primitive reference; any other prefix marks them as **public**, in
120
- which case the orchestrator **pulls** the tagged base images from that registry
121
- instead of building them. The built-in base images are `archlinux` (pacman),
122
- `ubuntu` (apt), and `alpine` (apk); their short names are reserved and cannot be
123
- built over, rebuilt, or removed as custom images.
115
+ Prefix under which base images are tagged, as `BASE_IMAGE_PREFIX + <short> +
116
+ ":latest"`. When the prefix starts with `localhost/`, base images are **built
117
+ locally** by the orchestrator from their upstream primitive reference; any other
118
+ prefix marks them as **public**, in which case the orchestrator **pulls** the
119
+ tagged base images from that registry instead of building them. The built-in
120
+ base images are `archlinux` (pacman), `ubuntu` (apt), and `alpine` (apk); their
121
+ short names are reserved and cannot be built over, rebuilt, or removed as custom
122
+ images.
124
123
 
125
124
  ### `DSH_PODMAN_GUEST_AGENT_IMAGE` and `DSH_PODMAN_HOST_GUEST_AGENT_BIN`
126
125
 
@@ -177,22 +176,22 @@ configuration.
177
176
 
178
177
  An arbitrary shared secret string that the orchestrator and the plugin must
179
178
  agree on; every control-plane request carries it as the gRPC metadata header
180
- `authorization: bearer <token>`. Use a long, random value — for example
181
- `openssl rand -hex 32` — and set the same value on both sides. When the
182
- orchestrator has no token set, it accepts unauthenticated control-plane calls
183
- (relying on the socket's file permissions instead); when a token is set,
184
- requests without the matching header are rejected with `Unauthenticated`.
179
+ `authorization: bearer <token>`. Use a long, random value — for example `openssl
180
+ rand -hex 32` — and set the same value on both sides. When the orchestrator has
181
+ no token set, it accepts unauthenticated control-plane calls (relying on the
182
+ socket's file permissions instead); when a token is set, requests without the
183
+ matching header are rejected with `Unauthenticated`.
185
184
 
186
185
  ### `DSH_PODMAN_GATEWAY_TOKEN`
187
186
 
188
187
  An arbitrary shared secret string that the gateway and the orchestrator must
189
188
  agree on; every gateway control call carries it as the gRPC metadata header
190
- `authorization: bearer <token>`. Use a long, random value — for example
191
- `openssl rand -hex 32` — and set the same value on both sides. When the gateway
192
- has no token set, it accepts unauthenticated control calls (relying on the
193
- socket's file permissions instead) and logs a warning; when a token is set,
194
- calls without the matching header are rejected with `Unauthenticated`. The dsh
195
- plugin does not talk to the gateway and does not need this variable.
189
+ `authorization: bearer <token>`. Use a long, random value — for example `openssl
190
+ rand -hex 32` — and set the same value on both sides. When the gateway has no
191
+ token set, it accepts unauthenticated control calls (relying on the socket's
192
+ file permissions instead) and logs a warning; when a token is set, calls without
193
+ the matching header are rejected with `Unauthenticated`. The dsh plugin does not
194
+ talk to the gateway and does not need this variable.
196
195
 
197
196
  ### `DSH_PODMAN_ORCHESTRATOR_STATE`
198
197
 
@@ -153,8 +153,8 @@ guest-agent 镜像在容器创建时提供 agent:orchestrator 使用 podman
153
153
 
154
154
  ### `DSH_PODMAN_GUEST_TOKEN`
155
155
 
156
- 每次 guest-agent gRPC 调用所需的共享机密,以 gRPC 元数据头
157
- `authorization: bearer <token>` 传递。实际上,orchestrator
156
+ 每次 guest-agent gRPC 调用所需的共享机密,以 gRPC 元数据头 `authorization:
157
+ bearer <token>` 传递。实际上,orchestrator
158
158
  会为每个工作区生成一个新的随机令牌,并通过 `DSH_PODMAN_GUEST_TOKEN` 注入到 guest
159
159
  容器中,同时将相同的值连同 guest 套接字路径一起交给插件——因此通常无需手动配置。
160
160
 
@@ -170,8 +170,7 @@ orchestrator 和插件必须约定的任意共享机密字符串;每个控制
170
170
 
171
171
  gateway 与 orchestrator 必须一致的任意共享机密字符串;每次 gateway
172
172
  控制调用都会以 gRPC 元数据标头 `authorization: bearer <token>`
173
- 携带它。请使用足够长的随机值——例如
174
- `openssl rand -hex
173
+ 携带它。请使用足够长的随机值——例如 `openssl rand -hex
175
174
  32`——并在两端设置相同的值。gateway
176
175
  未设置令牌时会接受未经认证的控制调用(改由套接字文件权限保护)并记录一条警告;设置了令牌后,缺少匹配标头的调用会被拒绝并返回
177
176
  `Unauthenticated`。dsh 插件不访问 gateway,因此不需要该变量。
@@ -8,15 +8,29 @@ SPDX-License-Identifier: MIT
8
8
 
9
9
  English | [中文](development-prompt.zh.md)
10
10
 
11
- This page carries the prompt that builds a development image, creates the
12
- toolchain volume and wires the workspace container to it, as described in
13
- [Development](development.md#development-container-toolchain). Nothing it needs
14
- exists beforehand.
11
+ This page carries the prompt that sets up the development container: it builds
12
+ the development image, creates the `dsh-podman-toolchain` volume and wires the
13
+ workspace container to it with the mounts, environment and PATH additions, as
14
+ described in [Development](development.md#development-container-toolchain). The
15
+ prompt does this by applying the project's committed
16
+ [`.dsh-podman/develop.yml`](../.dsh-podman/develop.yml) container template,
17
+ which declares those elements.
15
18
 
16
19
  Paste the block below into a dsh session attached to the workspace. It is safe
17
- to run again: it inspects the workspace first and only creates, mounts or
18
- changes what is missing or different. Recreating a container stops its daemons
19
- and clears its tmpfs, so expect that whenever a change is needed.
20
+ to run again: loading the template replaces the default container's image and
21
+ mounts with the template's, replaces the environment, secret environment and
22
+ PATH additions it declares, and keeps the groups it leaves undeclared at their
23
+ current values. Replacing a container stops its daemons and clears its tmpfs, so
24
+ expect that whenever the template is applied.
25
+
26
+ Before the prompt, clone the `deepseek-harness` repository into the projects
27
+ root so it exists there as the project `deepseek-harness`. The template mounts
28
+ that project read-only and cannot be loaded while it is missing. Run this from
29
+ the projects root, the directory that holds this checkout:
30
+
31
+ ```sh
32
+ git clone https://github.com/deepseek-ai/deepseek-harness.git
33
+ ```
20
34
 
21
35
  Two steps stay manual on the host, and the prompt asks for them instead of
22
36
  attempting them:
@@ -28,47 +42,37 @@ attempting them:
28
42
  [Install development builds](development.md#install-development-builds)).
29
43
 
30
44
  ```text
31
- Set up a development environment for this dsh-podman workspace. It must be safe
32
- to run again: inspect the current state first, and only create, mount or change
33
- what is missing or different, keeping whatever is already configured. Use the
34
- container tools; never run `make` or edit files on the host.
45
+ Set up a development environment for this dsh-podman workspace from the
46
+ project's committed `.dsh-podman/develop.yml` container template. It must be
47
+ safe to run again: applying the template reconciles the default container with
48
+ the image, mounts, environment and PATH it declares. Use the container tools,
49
+ and never run `make` or edit files on the host.
35
50
 
36
- 1. Image: build a custom image named `dsh-podman-tooling` from the `archlinux`
37
- base with packages `go`, `nodejs`, `npm`, `reuse` and
38
- `python-chardet`. It is a local image, not a published one; leave an existing
39
- one alone when it already carries exactly these packages, and rebuild it from
40
- this list when it does not.
41
- 2. Volume: create the workspace volume `dsh-podman-toolchain` unless it already
42
- exists.
43
- 3. Container: inspect the default container's image, mounts, PATH additions and
44
- environment. Recreate it once, only if something below is missing or
45
- different, passing the complete merged sets so nothing existing is dropped:
46
- - image `dsh-podman-tooling`;
47
- - `dsh-podman-toolchain` mounted at `/opt/toolchain`, read-write, plus the
48
- workspace project mount and every mount already there;
49
- - PATH additions `/opt/toolchain/gopath/bin`,
50
- `/opt/toolchain/npm-global/bin` and `/opt/toolchain/pnpm-home`, in
51
- addition to the ones already there;
52
- - environment `GOCACHE=/opt/toolchain/gocache`,
53
- `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`,
54
- `npm_config_cache=/opt/toolchain/npm-cache`,
55
- `npm_config_prefix=/opt/toolchain/npm-global`,
56
- `PNPM_HOME=/opt/toolchain/pnpm-home` and
57
- `GOENV=/opt/toolchain/home/.config/go/env`, merged with the variables
58
- already on the container.
59
- 4. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
51
+ 1. Prerequisite: check that the project `deepseek-harness` exists under the
52
+ projects root. If it does not, stop and ask me to clone the
53
+ `deepseek-harness` repository there (a host step); the template mounts that
54
+ project read-only and cannot be loaded without it.
55
+ 2. Template: call the `container_template_load` tool with template `develop`
56
+ and container `default`; the change needs approval. The tool builds the
57
+ template image when needed, replaces the default container with the
58
+ template's image, mounts, environment, secret environment and PATH
59
+ additions, and publishes the template's ports. The template's mounts replace
60
+ the container's mounts; the environment, secret environment and PATH
61
+ additions it declares replace those groups, and groups it leaves undeclared
62
+ keep their current values. The resulting image is `archlinux`-based and
63
+ carries `go`, `nodejs`, `npm`, `python-chardet` and `reuse`.
64
+ 3. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
60
65
  report the version `package.json` pins in `packageManager`, install it with
61
66
  `npm install -g pnpm@<that version>` and check again. dprint, the formatter,
62
67
  is a project devDependency and arrives with `pnpm install`.
63
- 5. Git identity: do not write a `~/.gitconfig`. If no Git identity is
64
- configured, tell me to set it once on the Podman page (sidebar **Plugins**
65
- panel → **Installed** → **dsh-podman**): **Default
66
- environment → Git identity**.
67
- 6. Verify from inside the container, without sourcing anything: `make build`,
68
+ 4. Git identity: do not write a `~/.gitconfig`. If no identity is configured,
69
+ tell me to set it once on the Podman page's **Defaults** tab: **Default
70
+ environment variables** → **Git identity**.
71
+ 5. Verify from inside the container, without sourcing anything: `make build`,
68
72
  `make vet` and `pnpm test` must succeed in the repository.
69
- 7. Report what you created or changed, or that everything was already in place.
70
- If a step needs the host — rebuilding the dsh, orchestrator or guest-agent
71
- images (`make image`), or editing the Quadlet units under
72
- `~/.config/containers/systemd/` and reloading systemd — stop and ask me
73
- instead of trying it.
73
+ 6. Report what changed, or that everything already matched the template. If a
74
+ step needs the host — cloning `deepseek-harness`, rebuilding the dsh,
75
+ orchestrator or guest-agent images (`make image`), or editing the Quadlet
76
+ units under `~/.config/containers/systemd/` and reloading systemd — stop and
77
+ ask me instead of trying it.
74
78
  ```
@@ -8,16 +8,30 @@ SPDX-License-Identifier: MIT
8
8
 
9
9
  [English](development-prompt.md) | 中文
10
10
 
11
- 本页给出用于构建开发镜像、创建工具链卷并把工作区容器接好的提示词,参见[开发](development.zh.md#开发容器工具链)。其中没有任何东西是现成的。
11
+ 本页给出设置开发容器的提示词:它构建开发镜像、创建 `dsh-podman-toolchain`
12
+ 卷,并把工作区容器接好(挂载、环境变量与 PATH
13
+ 追加项),参见[开发](development.zh.md#开发容器工具链)。提示词通过应用项目已提交的
14
+ [`.dsh-podman/develop.yml`](../.dsh-podman/develop.yml)
15
+ 容器模板来完成这些,模板声明了上述内容。
16
+
17
+ 在粘贴提示词之前,请先把 `deepseek-harness` 仓库克隆到 projects
18
+ 根目录,使其成为项目
19
+ `deepseek-harness`。模板会以只读方式挂载该项目,项目缺失时无法加载模板。请在
20
+ projects 根目录(即包含本检出的目录)中运行:
21
+
22
+ ```sh
23
+ git clone https://github.com/deepseek-ai/deepseek-harness.git
24
+ ```
12
25
 
13
26
  把下面的文本块粘贴到已接入该工作区的 dsh
14
- 会话中。它可以反复运行:先检查工作区现状,只创建、挂载或修改缺失或不同的部分。重建容器会终止其守护进程并清空
15
- tmpfs,因此在需要变更时请预期这一点。
27
+ 会话中。它可以反复运行:加载模板会把默认容器的镜像与挂载替换为模板的镜像与挂载,并替换模板声明的环境变量、机密环境变量与
28
+ PATH 追加项,模板未声明的分组则保留当前值。替换容器会终止其守护进程并清空
29
+ tmpfs,因此每次应用模板时请预期这一点。
16
30
 
17
31
  以下步骤仍需在宿主机上手动完成,提示词只会请求它们,而不会自行尝试:
18
32
 
19
- - 重建 dsh、orchestrator 和 guest-agent
20
- 镜像(`make image`),这需要宿主机上的仓库检出与 podman;
33
+ - 重建 dsh、orchestrator 和 guest-agent 镜像(`make
34
+ image`),这需要宿主机上的仓库检出与 podman;
21
35
  - 安装或编辑 `~/.config/containers/systemd/` 下的 Quadlet 单元,随后执行
22
36
  `systemctl --user daemon-reload`
23
37
  并重启(见[安装开发构建](development.zh.md#安装开发构建))。
@@ -25,47 +39,37 @@ tmpfs,因此在需要变更时请预期这一点。
25
39
  下面的提示词与英文页保持一致,原样粘贴即可。
26
40
 
27
41
  ```text
28
- Set up a development environment for this dsh-podman workspace. It must be safe
29
- to run again: inspect the current state first, and only create, mount or change
30
- what is missing or different, keeping whatever is already configured. Use the
31
- container tools; never run `make` or edit files on the host.
42
+ Set up a development environment for this dsh-podman workspace from the
43
+ project's committed `.dsh-podman/develop.yml` container template. It must be
44
+ safe to run again: applying the template reconciles the default container with
45
+ the image, mounts, environment and PATH it declares. Use the container tools,
46
+ and never run `make` or edit files on the host.
32
47
 
33
- 1. Image: build a custom image named `dsh-podman-tooling` from the `archlinux`
34
- base with packages `go`, `nodejs`, `npm`, `reuse` and
35
- `python-chardet`. It is a local image, not a published one; leave an existing
36
- one alone when it already carries exactly these packages, and rebuild it from
37
- this list when it does not.
38
- 2. Volume: create the workspace volume `dsh-podman-toolchain` unless it already
39
- exists.
40
- 3. Container: inspect the default container's image, mounts, PATH additions and
41
- environment. Recreate it once, only if something below is missing or
42
- different, passing the complete merged sets so nothing existing is dropped:
43
- - image `dsh-podman-tooling`;
44
- - `dsh-podman-toolchain` mounted at `/opt/toolchain`, read-write, plus the
45
- workspace project mount and every mount already there;
46
- - PATH additions `/opt/toolchain/gopath/bin`,
47
- `/opt/toolchain/npm-global/bin` and `/opt/toolchain/pnpm-home`, in
48
- addition to the ones already there;
49
- - environment `GOCACHE=/opt/toolchain/gocache`,
50
- `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`,
51
- `npm_config_cache=/opt/toolchain/npm-cache`,
52
- `npm_config_prefix=/opt/toolchain/npm-global`,
53
- `PNPM_HOME=/opt/toolchain/pnpm-home` and
54
- `GOENV=/opt/toolchain/home/.config/go/env`, merged with the variables
55
- already on the container.
56
- 4. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
48
+ 1. Prerequisite: check that the project `deepseek-harness` exists under the
49
+ projects root. If it does not, stop and ask me to clone the
50
+ `deepseek-harness` repository there (a host step); the template mounts that
51
+ project read-only and cannot be loaded without it.
52
+ 2. Template: call the `container_template_load` tool with template `develop`
53
+ and container `default`; the change needs approval. The tool builds the
54
+ template image when needed, replaces the default container with the
55
+ template's image, mounts, environment, secret environment and PATH
56
+ additions, and publishes the template's ports. The template's mounts replace
57
+ the container's mounts; the environment, secret environment and PATH
58
+ additions it declares replace those groups, and groups it leaves undeclared
59
+ keep their current values. The resulting image is `archlinux`-based and
60
+ carries `go`, `nodejs`, `npm`, `python-chardet` and `reuse`.
61
+ 3. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
57
62
  report the version `package.json` pins in `packageManager`, install it with
58
63
  `npm install -g pnpm@<that version>` and check again. dprint, the formatter,
59
64
  is a project devDependency and arrives with `pnpm install`.
60
- 5. Git identity: do not write a `~/.gitconfig`. If no Git identity is
61
- configured, tell me to set it once on the Podman page (sidebar **Plugins**
62
- panel → **Installed** → **dsh-podman**): **Default
63
- environment → Git identity**.
64
- 6. Verify from inside the container, without sourcing anything: `make build`,
65
+ 4. Git identity: do not write a `~/.gitconfig`. If no identity is configured,
66
+ tell me to set it once on the Podman page's **Defaults** tab: **Default
67
+ environment variables** → **Git identity**.
68
+ 5. Verify from inside the container, without sourcing anything: `make build`,
65
69
  `make vet` and `pnpm test` must succeed in the repository.
66
- 7. Report what you created or changed, or that everything was already in place.
67
- If a step needs the host — rebuilding the dsh, orchestrator or guest-agent
68
- images (`make image`), or editing the Quadlet units under
69
- `~/.config/containers/systemd/` and reloading systemd — stop and ask me
70
- instead of trying it.
70
+ 6. Report what changed, or that everything already matched the template. If a
71
+ step needs the host — cloning `deepseek-harness`, rebuilding the dsh,
72
+ orchestrator or guest-agent images (`make image`), or editing the Quadlet
73
+ units under `~/.config/containers/systemd/` and reloading systemd — stop and
74
+ ask me instead of trying it.
71
75
  ```