@exagone313/dsh-podman 0.2.0-rc.3 → 0.2.0

package/docs/development.md

@@ -20,8 +20,8 @@ This page is for **contributors** building the plugin from this repository.
 
 ## Building
 
-Prerequisites: Go 1.27, Node ≥ 22, pnpm 12, and (for the browser half) the
-`@deepseek-ai/dsh-client-*` packages published on npm.
+Prerequisites: Go 1.27, Node ≥ 22, pnpm 12, Deno ≥ 2.9 (formatting), and (for
+the browser half) the `@deepseek-ai/dsh-client-*` packages published on npm.
 
 ```sh
 pnpm install
@@ -36,20 +36,22 @@ The `Makefile` wraps the common workflows:
 ```sh
 make build-go       # build both Go binaries into bin/<os>-<arch>/
 make build          # build-go + pnpm-build
-make vet            # go vet with the build tags
+make vet            # gofmt -s check + go vet with the build tags
 make test-go        # go test with the build tags
 make test           # test-go + pnpm test (JS tests, which run against dist/)
-make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
-make image          # build the orchestrator and guest-agent container images
+make fmt            # gofmt -s + deno fmt (TypeScript and Markdown)
+make fmt-check      # verify the formatting without rewriting anything
+make download-licenses  # generate third-party-licenses.pkg from the project and third-party Go licenses
+make image          # build the orchestrator, guest-agent and dsh container images
 ```
 
-`make image` depends on `LICENSE.pkg`: the `download-licenses` target runs the
-Go collector in `scripts/download-licenses`, which shells out to
+`make image` depends on `third-party-licenses.pkg`: the `download-licenses`
+target runs the Go collector in `scripts/download-licenses`, which shells out to
 `go-licenses save` and gathers the project's MIT license plus every third-party
-Go license and Apache `NOTICE` into `LICENSE.pkg`. That file is gitignored
-(never committed) and is baked into the orchestrator and guest-agent images at
-`/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers mount the
-guest-agent image, it also rides along into every workspace container.
+Go license and Apache `NOTICE` into `third-party-licenses.pkg`. That file is
+gitignored (never committed) and is baked into the orchestrator and guest-agent
+images at `/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers
+mount the guest-agent image, it also rides along into every workspace container.
 
 `pnpm test` runs `node --test dist/*.test.js`, so it requires `pnpm build` to
 have run first (the `test` target handles this).
@@ -66,6 +68,19 @@ The JS side loads the raw `.proto` files at runtime via `@grpc/proto-loader`
 (copied to `dist/grpc/proto/` at build time); no TypeScript bindings are
 generated. Optionally validate the schema with `buf lint` and `buf breaking`.
 
+## Naming
+
+Proto field names are `lower_snake_case` (Buf's `BASIC` lint enforces it), and
+the JS side reads them through proto-loader's camelCase projection, so
+`secret_env` becomes `secretEnv` and `image_id` becomes `imageId`. Never spell a
+proto field in its snake_case form in TypeScript: proto-loader ignores an
+unknown property, so the value would be silently dropped.
+
+Tool parameters are camelCase, except the ones that deliberately mirror the
+harness's built-in tools (`file_path`, `old_string`, `new_string`,
+`replace_all`). Settings are camelCase; the persisted TOML state uses snake_case
+tags.
+
 ## Install development builds
 
 ### Build
@@ -75,33 +90,165 @@ make  # builds plugin and go binaries
 make image  # build images
 ```
 
-### Recreate containers
+### Run the local images (Quadlet)
+
+The shipped units pull the release images. Point them at the images built by
+`make image` to run a local build as the real services; comment the original
+line out so switching back is a one-line edit.
+
+In `~/.config/containers/systemd/dsh.container`:
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/dsh:1
+Image=localhost/dsh-podman-dsh:latest
+Environment=DSH_PODMAN_PLUGIN_SOURCE=%h/project/dsh-podman
+```
+
+The unit already mounts `%h/project` read-only, so a repository checked out
+under `~/project` needs no extra `Volume=`. `npm pack` leaves the archive the
+entrypoint installs next to `package.json` (see
+[Install a local plugin build](#install-a-local-plugin-build)).
+
+In `~/.config/containers/systemd/dsh-podman-orchestrator.container`:
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/orchestrator:1
+Image=localhost/dsh-podman-orchestrator:latest
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=ghcr.io/exagone313/dsh-podman/guest-agent
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG=true
+Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=localhost/dsh-podman-guest-agent:latest
+```
+
+The release reference is version-tagged, so every release gets a distinct image
+reference. The local build reuses a single `:latest` tag instead; the
+orchestrator then cannot tell that the agent was rebuilt, which is what
+[Update workspace containers](#update-workspace-containers) is about.
+
+Reload systemd after editing the units:
 
 ```bash
+systemctl --user daemon-reload
+```
+
+### Deploy a change
+
+```bash
+make            # Go binaries + the plugin bundle
+make image      # orchestrator, guest-agent and dsh images
+npm pack        # the plugin archive the dsh entrypoint installs
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
-### Update plugin
+The dsh image installs the plugin at container start, so restarting dsh is what
+reinstalls the freshly packed archive; restarting the orchestrator picks up the
+new orchestrator and guest-agent images.
+
+### Update workspace containers
+
+The guest-agent image is mounted into each container when it is created, so a
+running container keeps the agent it started with. The orchestrator recreates a
+container by itself only when its guest-agent image reference differs from the
+configured one — which happens with the version-tagged release reference, but
+not with the local `:latest` tag. After rebuilding the guest agent, recreate the
+containers yourself:
+
+- from the Podman page (sidebar **Plugins** panel → **Installed** →
+  **dsh-podman**), per container: **Recreate** (same image) or **Recreate with
+  image**;
+- with `container_recreate`, for a named container or the default one.
+
+To rebuild a whole workspace instead, use **Remove pod** on its row (or
+`RemoveWorkspace`): the pod and all its containers are removed, and the next
+attach creates the pod and its default container again. Restarting the two
+services never touches workspace containers, and neither action removes volumes,
+secrets, or project data.
+
+A container that still runs an agent from an older image makes dsh log
+`rejected by server because of excess pings` for its guest socket. The message
+is harmless (grpc-js backs off and reconnects) and disappears once the container
+is recreated; the same message for `orchestrator.sock` means the orchestrator
+service is still running the previous image.
+
+### Development container toolchain
+
+A workspace container's root filesystem is read-only and disposable, so the
+toolchain a contributor builds with needs a workspace volume. No development
+image is distributed: build a custom one — the
+[setup prompt](development-prompt.md) builds `dsh-podman-tooling` from the
+`archlinux` base with `go`, `nodejs-lts-jod`, `npm`, `deno`, `reuse` and
+`python-chardet` — and create a workspace volume for the state an image cannot
+keep: the Go and npm caches, `gopath` with the `go install`ed tools, and pnpm,
+which `package.json` pins to a version the Arch repositories do not carry.
+
+The prompt mounts that volume as `dsh-podman-toolchain` at `/opt/toolchain`
+(read-write) and points the container's caches at it, so commands work without
+sourcing anything:
+
+| Container setting | Value                                                                                                                                                                                                                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PATH additions    | `/opt/toolchain/gopath/bin`, `/opt/toolchain/npm-global/bin`, `/opt/toolchain/pnpm-home`                                                                                                                                                                                                                                   |
+| Environment       | `GOCACHE=/opt/toolchain/gocache`, `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`, `npm_config_cache=/opt/toolchain/npm-cache`, `npm_config_prefix=/opt/toolchain/npm-global`, `PNPM_HOME=/opt/toolchain/pnpm-home`, `DENO_DIR=/opt/toolchain/deno-dir`, `GOENV=/opt/toolchain/home/.config/go/env` |
+
+Set the commit identity once on the Podman page (sidebar **Plugins** panel →
+**Installed** → **dsh-podman**) under
+[Default environment](configuration.md#default-environment) → **Git identity**,
+so containers get `GIT_AUTHOR_*`/`GIT_COMMITTER_*` without a `~/.gitconfig`.
+
+The prompt applies all of this from inside dsh and can be pasted again to repair
+a workspace. Podman stores managed volumes with `DSH_PODMAN_VOLUME_PREFIX`
+prepended, so it lists the volume as `dsh-podman-dsh-podman-toolchain`.
+
+### Install a local plugin build
+
+The dsh image installs the plugin itself at container start, so a development
+build is served by pointing that install at a bind-mounted package. The Quadlet
+setup above is the first form below, with the repository directory itself
+(`%h/project/dsh-podman`) already visible through the unit's read-only
+`%h/project` mount. Build the plugin and pack it:
 
 ```bash
-npm pack
-v="$(jq -r .version package.json)"
-podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
-podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
-podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
-systemctl --user restart dsh
+pnpm build
+npm pack          # writes exagone313-dsh-podman-<version>.tgz
+```
+
+Then add one of these to the dsh container unit and restart it:
+
+```
+# the repository directory, which must contain the packed archive
+Volume=/path/to/repo:/mnt/dsh-podman:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
 ```
 
+```
+# or the archive itself
+Volume=/path/to/exagone313-dsh-podman-x.y.z.tgz:/mnt/dsh-podman.tgz:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
+```
+
+The entrypoint installs that package on every start and never falls back to the
+registry — a missing package is an error. Re-run `pnpm build && npm pack` and
+restart dsh to pick up changes.
+
+Without `DSH_PODMAN_PLUGIN_SOURCE`, the entrypoint installs
+`@exagone313/dsh-podman@$DSH_PODMAN_PLUGIN_VERSION` (the version baked into the
+image) exactly, upgrading or downgrading the profile's copy to match.
+
 ## Continuous integration
 
-CI (`.github/workflows/ci.yml`) runs on every branch push and pull request:
+CI runs on every **branch** push and pull request, split across
+`.github/workflows/ci-common.yml` (REUSE lint and zizmor), `ci-code.yml` (Go,
+JS, images, Trivy), `ci-docs.yml` (Deno fmt) and `ci-dsh-image.yml`. A **tag**
+push runs only `release.yml`, which repeats the build, vet and tests itself:
 
 - **actions-lint** — zizmor scans the workflows for insecure practices.
-- **go** — build, vet, tests, and govulncheck (Go vulnerabilities). Unfixed
-  findings don't fail the job; fixable ones do.
-- **js** — install, typecheck, build, tests, and `pnpm audit`.
+- **reuse** — REUSE license compliance.
+- **go** — build, `gofmt -s` check, vet, tests, and govulncheck (Go
+  vulnerabilities). Unfixed findings don't fail the job; fixable ones do.
+- **js** — TypeScript formatting check, install, typecheck, build, tests, and
+  `pnpm audit`.
+- **docs** — Markdown formatting check (`deno fmt` via `make fmt-check-md`).
 - **images** — builds the orchestrator and guest-agent images (runs only after
-  the test jobs pass).
+  the test jobs pass); **dsh image** builds `Containerfile.dsh`.
 - **trivy** — filesystem vulnerability scan (unfixed ignored) and container
   misconfiguration scan (DS-0002 excluded via `.trivyignore.yaml`).
 
@@ -115,9 +262,12 @@ pre-releases like `1.0.0-rc.1` also work). The release workflow
 
 1. Runs the tests, then builds both binaries for `linux/amd64` and
    `linux/arm64`.
-2. Pushes the **orchestrator** and **guest-agent** images to GHCR
-   (`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`), tagged with the
-   version plus `latest` for stable releases (pre-releases never get `latest`).
+2. Pushes the **dsh**, **orchestrator** and **guest-agent** images to GHCR
+   (`ghcr.io/exagone313/dsh-podman/{dsh,orchestrator,guest-agent}`). Every
+   release is tagged with its version; a **stable** release — `1.0.0` or above
+   with no pre-release suffix — is also tagged with its major version (`1`) and
+   `latest`. A `0.x` release and any hyphenated tag are pre-releases: they get
+   the version tag only.
 3. Publishes the plugin to **npm** (`@exagone313/dsh-podman`) with provenance;
    pre-releases are published under the `next` dist-tag.
 4. Creates a **GitHub release** with auto-generated notes and attaches the
@@ -127,8 +277,8 @@ The tag must match `package.json`'s version — the workflow fails otherwise —
 bump both with the version script:
 
 ```sh
-pnpm bump-version 0.1.1            # add --dry-run to validate only
-git push origin master 0.1.1
+pnpm bump-version x.y.z            # add --dry-run to validate only
+git push origin master x.y.z
 ```
 
 `scripts/bump-version.mjs` checks that the version is a semver release or
@@ -139,4 +289,9 @@ built plugin and binaries report, since `scripts/generate-version.mjs` derives
 the embedded version from `git describe --tags`. Pre-releases (`1.0.0-rc.1`) are
 bumped the same way.
 
+A release can also be triggered, or a failed one re-run, from the Actions tab
+with `workflow_dispatch`, which takes the version as input. Already-published
+steps are skipped (npm skips a version it already has, and an existing GitHub
+release is left alone), so a retry never republishes.
+
 The `NPM_TOKEN` secret must be configured on the repository for the npm step.

package/docs/development.zh.md

@@ -19,7 +19,8 @@ SPDX-License-Identifier: MIT
 
 ## 构建
 
-前置要求：Go 1.27、Node ≥ 22、pnpm 12，以及（浏览器端所需的）发布在 npm 上的
+前置要求：Go 1.27、Node ≥ 22、pnpm 12、Deno ≥
+2.9（用于格式化），以及（浏览器端所需的）发布在 npm 上的
 `@deepseek-ai/dsh-client-*` 包。
 
 ```sh
@@ -35,19 +36,22 @@ Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动，它们需要宿
 ```sh
 make build-go       # build both Go binaries into bin/<os>-<arch>/
 make build          # build-go + pnpm-build
-make vet            # go vet with the build tags
+make vet            # gofmt -s check + go vet with the build tags
 make test-go        # go test with the build tags
 make test           # test-go + pnpm test (JS tests, which run against dist/)
-make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
-make image          # build the orchestrator and guest-agent container images
+make fmt            # gofmt -s + deno fmt (TypeScript and Markdown)
+make fmt-check      # verify the formatting without rewriting anything
+make download-licenses  # generate third-party-licenses.pkg from the project and third-party Go licenses
+make image          # build the orchestrator, guest-agent and dsh container images
 ```
 
-`make image` 依赖 `LICENSE.pkg`：`download-licenses` 目标会运行
+`make image` 依赖 `third-party-licenses.pkg`：`download-licenses` 目标会运行
 `scripts/download-licenses` 中的 Go 收集器，它调用 `go-licenses save` 并将项目的
-MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到 `LICENSE.pkg`
-中。该文件被 gitignore （从不提交），并被烘焙进 orchestrator 和 guest-agent
-镜像，位于 `/usr/share/licenses/dsh-podman/LICENSE`；由于工作区容器会挂载
-guest-agent 镜像，因此它也会随之进入每个工作区容器。
+MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到
+`third-party-licenses.pkg` 中。该文件被 gitignore （从不提交），并被烘焙进
+orchestrator 和 guest-agent 镜像，位于
+`/usr/share/licenses/dsh-podman/LICENSE`；由于工作区容器会挂载 guest-agent
+镜像，因此它也会随之进入每个工作区容器。
 
 `pnpm test` 运行 `node --test dist/*.test.js`，因此它要求先运行 `pnpm build`
 （`test` 目标会处理这一点）。
@@ -64,6 +68,17 @@ JS 端在运行时通过 `@grpc/proto-loader` 加载原始 `.proto` 文件（构
 `dist/grpc/proto/`）；不生成 TypeScript 绑定。也可以使用 `buf lint` 和
 `buf breaking` 校验 schema。
 
+## 命名
+
+`.proto` 字段名为 `lower_snake_case`（Buf 的 `BASIC` lint 会强制检查），JS
+端通过 proto-loader 的 camelCase 投影读取，因此 `secret_env` 变为
+`secretEnv`、`image_id` 变为 `imageId`。切勿在 TypeScript 中使用下划线形式的
+proto 字段名：proto-loader 会忽略未知属性，该值会被静默丢弃。
+
+工具参数使用 camelCase，只有刻意与 harness
+内置工具保持一致的名字除外（`file_path`、`old_string`、`new_string`、`replace_all`）。设置项使用
+camelCase；持久化的 TOML 状态使用下划线标签。
+
 ## 安装开发构建
 
 ### 构建
@@ -73,32 +88,151 @@ make  # builds plugin and go binaries
 make image  # build images
 ```
 
-### 重建容器
+### 运行本地镜像（Quadlet）
+
+随附的单元会拉取发布镜像。把它们指向 `make image`
+构建的镜像，就能把本地构建当作正式服务来运行；把原来的行注释掉，切回时只需改一行。
+
+在 `~/.config/containers/systemd/dsh.container` 中：
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/dsh:1
+Image=localhost/dsh-podman-dsh:latest
+Environment=DSH_PODMAN_PLUGIN_SOURCE=%h/project/dsh-podman
+```
+
+该单元已经把 `%h/project` 以只读方式挂载，因此检出在 `~/project`
+下的仓库无需额外的 `Volume=`。`npm pack` 会把入口脚本要安装的归档放在
+`package.json` 旁边（见[安装本地插件构建](#安装本地插件构建)）。
+
+在 `~/.config/containers/systemd/dsh-podman-orchestrator.container` 中：
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/orchestrator:1
+Image=localhost/dsh-podman-orchestrator:latest
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=ghcr.io/exagone313/dsh-podman/guest-agent
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG=true
+Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=localhost/dsh-podman-guest-agent:latest
+```
+
+发布引用带有版本标签，因此每个发布版本都有各自不同的镜像引用。本地构建则复用同一个
+`:latest` 标签；orchestrator 因此无法察觉 guest agent
+已被重建，详见[更新工作区容器](#更新工作区容器)。
+
+编辑单元后重新加载 systemd：
+
+```bash
+systemctl --user daemon-reload
+```
+
+### 部署改动
 
 ```bash
+make            # Go binaries + the plugin bundle
+make image      # orchestrator, guest-agent and dsh images
+npm pack        # the plugin archive the dsh entrypoint installs
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
-### 更新插件
+dsh 镜像会在容器启动时安装插件，因此重启 dsh 才会重新安装刚打包的归档；重启
+orchestrator 则会采用新的 orchestrator 与 guest-agent 镜像。
+
+### 更新工作区容器
+
+guest-agent 镜像会在容器创建时挂载进去，因此正在运行的容器仍使用它启动时的那份
+agent。只有当容器的 guest-agent 镜像引用与当前配置不一致时，orchestrator
+才会自行重建该容器——带版本标签的发布引用会如此，本地 `:latest` 标签则不会。重建
+guest agent 之后，请自行重建容器：
+
+- 在 Podman 页面（侧边栏 **插件** 面板 → **已安装** →
+  **dsh-podman**）中按容器操作：**Recreate**（沿用当前镜像）或 **Recreate with
+  image**；
+- 或使用 `container_recreate`，作用于命名容器或默认容器。
+
+若要重建整个工作区，可在其行上使用 **Remove pod**（或 `RemoveWorkspace`）：pod
+及其所有容器都会被移除，下次接入时会重新创建 pod
+与默认容器。重启这两个服务绝不会触及工作区容器，上述两种操作也都不会删除卷、机密或项目数据。
+
+仍在运行旧镜像中 guest agent 的容器会让 dsh 为其 guest 套接字记录
+`rejected by server because of excess pings`。该消息无害（grpc-js
+会退避并重连），重建该容器后即消失；若同样的消息出现在 `orchestrator.sock`
+上，则说明 orchestrator 服务仍在运行上一个镜像。
+
+### 开发容器工具链
+
+工作区容器的根文件系统是只读且一次性的，因此贡献者构建所用的工具链需要工作区的一个卷。项目并不分发开发镜像：请自行构建一个自定义镜像——[设置提示词](development-prompt.zh.md)
+会以 `archlinux` 为父镜像构建 `dsh-podman-tooling`，包含
+`go`、`nodejs-lts-jod`、`npm`、`deno`、`reuse` 和
+`python-chardet`——并为镜像无法保存的状态创建工作区卷：Go 与 npm 缓存、含
+`go install` 工具的 `gopath`， 以及 `package.json` 固定版本、Arch 仓库没有的
+pnpm。
+
+提示词会把该卷以 `dsh-podman-toolchain` 挂载到
+`/opt/toolchain`（读写），并让容器的缓存都指向它，因此无需 source
+任何脚本即可使用：
+
+| 容器设置    | 值                                                                                                                                                                                                                                                                                                                         |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PATH 追加项 | `/opt/toolchain/gopath/bin`、`/opt/toolchain/npm-global/bin`、`/opt/toolchain/pnpm-home`                                                                                                                                                                                                                                   |
+| 环境变量    | `GOCACHE=/opt/toolchain/gocache`、`GOMODCACHE=/opt/toolchain/gomodcache`、`GOPATH=/opt/toolchain/gopath`、`npm_config_cache=/opt/toolchain/npm-cache`、`npm_config_prefix=/opt/toolchain/npm-global`、`PNPM_HOME=/opt/toolchain/pnpm-home`、`DENO_DIR=/opt/toolchain/deno-dir`、`GOENV=/opt/toolchain/home/.config/go/env` |
+
+在 Podman 页面（侧边栏 **插件** 面板 → **已安装** →
+**dsh-podman**）的[默认环境变量](configuration.zh.md#默认环境变量) → **Git
+身份** 中设置一次提交身份，容器便无需 `~/.gitconfig` 即可获得
+`GIT_AUTHOR_*`/`GIT_COMMITTER_*`。
+
+提示词会在 dsh 内完成上述全部配置，并且可以反复粘贴以修复工作区。Podman
+存储受管卷时会加上 `DSH_PODMAN_VOLUME_PREFIX` 前缀，因此该卷显示为
+`dsh-podman-dsh-podman-toolchain`。
+
+### 安装本地插件构建
+
+dsh 镜像会在容器启动时自行安装插件，因此本地开发构建通过将安装源指向 bind mount
+的包来使用。上面的 Quadlet 配置就是下面第一种形式，仓库目录本身
+（`%h/project/dsh-podman`）已经通过单元的只读 `%h/project`
+挂载可见。先构建并打包插件：
 
 ```bash
-npm pack
-v="$(jq -r .version package.json)"
-podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
-podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
-podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
-systemctl --user restart dsh
+pnpm build
+npm pack          # 生成 exagone313-dsh-podman-<version>.tgz
 ```
 
+然后在 dsh 容器单元中加入以下之一并重启：
+
+```
+# 仓库目录，其中必须包含已打包的归档
+Volume=/path/to/repo:/mnt/dsh-podman:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
+```
+
+```
+# 或者归档本身
+Volume=/path/to/exagone313-dsh-podman-x.y.z.tgz:/mnt/dsh-podman.tgz:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
+```
+
+入口脚本会在每次启动时安装该包，且绝不会回退到注册表——找不到包即为错误。重新运行
+`pnpm build && npm pack` 并重启 dsh 即可生效。
+
+未设置 `DSH_PODMAN_PLUGIN_SOURCE` 时，入口脚本会精确安装
+`@exagone313/dsh-podman@$DSH_PODMAN_PLUGIN_VERSION`（镜像构建时写入的版本），并相应升级或降级配置中的副本。
+
 ## 持续集成
 
-CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行：
+CI 在每次**分支**推送和拉取请求时运行，分散在
+`.github/workflows/ci-common.yml`（REUSE lint 与
+zizmor）、`ci-code.yml`（Go、JS、镜像、Trivy）、`ci-docs.yml`（Deno fmt）和
+`ci-dsh-image.yml` 中。推送**标签**时只运行 `release.yml`，它自身会重复构建、vet
+和测试：
 
 - **actions-lint** — zizmor 扫描工作流是否存在不安全实践。
-- **go** — 构建、vet、测试和 govulncheck（Go 漏洞）。未修复的
+- **reuse** — REUSE 许可证合规检查。
+- **go** — 构建、`gofmt -s` 检查、vet、测试和 govulncheck（Go 漏洞）。未修复的
   发现不会导致任务失败；可修复的会导致失败。
-- **js** — 安装、类型检查、构建、测试和 `pnpm audit`。
-- **images** — 构建 orchestrator 和 guest-agent 镜像（仅在测试任务通过后运行）。
+- **js** — TypeScript 格式检查、安装、类型检查、构建、测试和 `pnpm audit`。
+- **docs** — Markdown 格式检查（通过 `make fmt-check-md` 运行 `deno fmt`）。
+- **images** — 构建 orchestrator 和 guest-agent
+  镜像（仅在测试任务通过后运行）；**dsh image** 构建 `Containerfile.dsh`。
 - **trivy** — 文件系统漏洞扫描（未修复的被忽略）和容器 错误配置扫描（DS-0002
   通过 `.trivyignore.yaml` 排除）。
 
@@ -110,9 +244,10 @@ CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行
 这样的预发布同样有效）触发。发布工作流 （`.github/workflows/release.yml`）：
 
 1. 运行测试，然后为 `linux/amd64` 和 `linux/arm64` 构建两个二进制文件。
-2. 将 **orchestrator** 和 **guest-agent** 镜像推送到 GHCR
-   （`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`），并打上
-   版本号以及稳定版的 `latest` 标签（预发布永远不会获得 `latest`）。
+2. 将 **dsh**、**orchestrator** 和 **guest-agent** 镜像推送到 GHCR
+   （`ghcr.io/exagone313/dsh-podman/{dsh,orchestrator,guest-agent}`）。每个发布都打上其版本标签；**稳定**发布——`1.0.0`
+   及以上且不带预发布后缀——还会打上其主版本号（`1`）和 `latest`。`0.x`
+   发布以及任何带连字符的标签都属于预发布：只打版本标签。
 3. 将插件发布到 **npm**（`@exagone313/dsh-podman`），附带来源证明； 预发布在
    `next` dist-tag 下发布。
 4. 创建带有自动生成说明的 **GitHub release**，并附上 二进制文件和 npm tarball。
@@ -121,8 +256,8 @@ CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行
 中的版本一致——否则工作流会失败——因此请用版本脚本同时更新两者：
 
 ```sh
-pnpm bump-version 0.1.1            # 加上 --dry-run 则仅校验
-git push origin master 0.1.1
+pnpm bump-version x.y.z            # 加上 --dry-run 则仅校验
+git push origin master x.y.z
 ```
 
 `scripts/bump-version.mjs` 会检查版本是否为递增的 Semver
@@ -132,4 +267,8 @@ git push origin master 0.1.1
 `scripts/generate-version.mjs` 从 `git describe --tags`
 推导嵌入的版本。预发布版（`1.0.0-rc.1`）也用同样的方式递增。
 
+也可以在 Actions 页面通过 `workflow_dispatch`
+触发发布，或重新运行失败的发布，版本作为输入传入。已完成的步骤会被跳过（npm
+会跳过已存在的版本，已有的 GitHub release 不会被改动），因此重试不会重复发布。
+
 npm 步骤要求仓库配置 `NPM_TOKEN` 密钥。

package/docs/install-dsh-and-dsh-podman.md

@@ -10,11 +10,14 @@ SPDX-License-Identifier: MIT
 
 The goal of this guide is to install:
 
-- [DeepSeek Harness](https://deepseek.com/harness), referred to later as _dsh_
+- [DeepSeek Harness](https://deepseek.com/harness), referred to later as _dsh_,
+  in its own Podman container
 - the dsh-podman plugin in dsh, which replaces host filesystem and shell access
 - the dsh-podman orchestrator, a separate Podman container that integrates with
   Podman
 
+Note that if there is existing installation data at `~/.dsh`, it will be reused.
+
 Having the dsh plugin and the orchestrator running as separate containers is an
 important part of the security design of dsh-podman: dsh itself doesn't have
 direct access to Podman, only the orchestrator does, with limitations. dsh
@@ -95,12 +98,13 @@ could be added in the future.
 
 ## Installation
 
-### dsh setup
-
 This installation uses
 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html),
 which adds Podman integration into systemd.
 
+Note that the dsh-podman plugin will be installed at dsh container startup,
+which requires online access.
+
 1. Create the Quadlet directory for your user:
    ```bash
    mkdir -p ~/.config/containers/systemd
@@ -108,6 +112,9 @@ which adds Podman integration into systemd.
 2. Copy the files [dsh.container](../quadlet/dsh.container) and
    [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
    to `~/.config/containers/systemd/`.
+   ```bash
+   cp quadlet/* ~/.config/containers/systemd/
+   ```
    - Adapt the files to your desired project directory if you wish to change it.
 3. Reload systemd session configuration:
    ```bash
@@ -137,29 +144,25 @@ which adds Podman integration into systemd.
 9. Once your web browser has saved this token, you'll be able to access dsh with
    the URL [http://127.0.0.1:3080/](http://127.0.0.1:3080/).
 
-### dsh-podman plugin installation
-
-1. Run this command to install the dsh-podman plugin:
-   ```bash
-   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
-   ```
-2. Restart dsh to complete the installation:
-   ```bash
-   systemctl --user restart dsh
-   ```
-
 ## Verification
 
-- Open **Settings → Plugins → dsh-podman**: the card should list the base images
-  and, for a workspace, offer to create its default container.
+- Open the sidebar's **Plugins** panel → **Installed** → **dsh-podman**: the
+  page should list the base images and, for a workspace, offer to create its
+  default container.
 - In a dsh session, run a shell command. It should execute inside a Podman
   container for the current workspace (the plugin auto-creates the workspace's
   default container on first use).
 
-## Enable daily auto-updates (optional)
+## Set Git identity (recommended)
+
+- Open settings from the sidebar's **Plugins** panel → **Installed** →
+  **dsh-podman**
+- Scroll down to **Default environment**
+- Click on **Git identity**
+- Enter the name and email to use for Git and click on **Apply**
+- Click on **Apply default environment variables** and then **Confirm**
 
-This requires enabling lingering for your user.
+## Updating dsh & dsh-podman
 
-```bash
-systemctl --user enable --now podman-auto-update.timer
-```
+Read the [update documentation](./update.md) to know how to manually update or
+set up auto-updates.