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

package/docs/usage.md

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 
 # Usage
 
-This page documents the model-facing tools, the settings card, and the image
+This page documents the model-facing tools, the Podman page, and the image
 model. See [Architecture](architecture.md) for how the pieces fit together.
 
 ## Model context
@@ -19,7 +19,10 @@ the assembled system prompt; the model is never told a misleading path.
 dsh-podman also adds its own prompt section clarifying that the built-in shell
 and filesystem tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) run
 inside the workspace's default container rather than on the host, and how they
-relate to the `container_*` tools.
+relate to the `container_*` tools. The same section steers the model toward
+building a custom image with `image_build` (then `container_start` or
+`container_recreate`) for software installs, and toward named volumes rather
+than `tmpfs` for data that must survive a container recreate.
 
 ## Image model
 
@@ -35,8 +38,8 @@ dsh-podman organizes the images its containers run into three tiers:
   manager. By default they are **built locally** from the primitive (installing
   the default packages); when `DSH_PODMAN_BASE_IMAGE_PREFIX` points at a
   registry (anything not starting with `localhost/`), they are **pulled**
-  instead. Base images are listed in the settings UI even when not yet
-  built/pulled, are rebuilt or pulled from the card, and their short names are
+  instead. Base images are listed on the Podman page even when not yet
+  built/pulled, are rebuilt or pulled from there, and their short names are
   reserved — they cannot be built over, rebuilt, or removed as custom images.
 - **Custom images** are user-built images created from a **parent** — a base
   image or another custom image — inheriting its package manager and adding
@@ -75,7 +78,8 @@ policy):
   `read`, `glob`, and `grep` always run.
 - **Workspace Write** — the `✱` tools ask through DSH's approval service (the
   call shows the standard approval prompt and is denied when no approval channel
-  is available); `container_start` asks only when `mounts` is passed.
+  is available); `container_start` asks only when `mounts` is passed or
+  `secretEnv` attaches secrets.
 - **Full access** — tools run without approval prompts.
 
 The harness's `sandbox_permissions` argument (a one-shot sandbox widening, e.g.
@@ -86,11 +90,12 @@ The prompt's reason is a full sentence naming the action and the objects it
 touches, quoting every identifier — for example
 `Add mount to container "web": volume "data" (read-only)`. It covers the
 container image, each mount's kind and destination, the environment variable
-keys, and the resolved file path. It follows the UI language: the browser client
-records the active locale in the plugin settings, with the durable locale
-preference as the fallback (English when neither is set). A policy denial — a
-read-only sandbox, or a destination on a project mount — is reported in the same
-language. The settings-card actions are direct control calls and are not gated.
+keys, the secret env var names, and the resolved file path. It follows the UI
+language: the browser client records the active locale in the plugin's
+`uiLocale` preference, which the Host persists in the plugin config (English
+when unset). A policy denial — a read-only sandbox, or a destination on a
+project mount — is reported in the same language. The Podman page's actions are
+direct control calls and are not gated.
 
 `container_start`, `container_recreate`, and `container_bash` accept an `env`
 map applied to the container (or the bash process); `container_exec` and
@@ -105,6 +110,14 @@ Environment variables are not treated as secrets, so the approval reason and
 reserved and rejected, since the orchestrator uses that namespace for
 guest-agent wiring.
 
+New containers are also seeded with the plugin's **default environment** (the
+`containerEnv` setting), so a git identity can be configured once instead of per
+project — see [Default environment](configuration.md#default-environment). The
+Podman page's **Git identity** popup fills the four
+`GIT_AUTHOR_*`/`GIT_COMMITTER_*` variables from one name and one email, and
+**Apply default environment variables** adds them to the running containers that
+lack them.
+
 `container_bash` and `container_exec` run with the same command-visible
 environment as the built-in `bash`: the harness's managed `DSH_*` facts
 (`DSH_HOME`, `DSH_SHELL`, `DSH_SESSION_ID`, `DSH_WEB_URL`) and its
@@ -114,14 +127,14 @@ managed `DSH_*` fact.
 
 ### Images
 
-| Tool                  | Params                          | Description                                                                                                                       |
-| --------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `image_build` ✱       | `imageId`, `parent`, `packages` | Build a new custom image from a base or custom parent and package list                                                            |
-| `image_get`           | `imageId`                       | Details for one image                                                                                                             |
-| `image_list`          | —                               | List the built workspace images, base images first                                                                                |
-| `image_rebuild_all` ✱ | —                               | Ensure every base, then rebuild every custom image in dependency order, skipping any image whose rebuild fails and its dependents |
-| `image_rebuild` ✱     | `imageId`                       | Rebuild an existing custom image in place                                                                                         |
-| `image_remove` ✱      | `imageId`                       | Remove a built image; refused while a workspace or container still references it                                                  |
+| Tool                  | Params                          | Description                                                                                                                                                                                       |
+| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_build` ✱       | `imageId`, `parent`, `packages` | Build a new custom image from a base or custom parent and package list                                                                                                                            |
+| `image_get`           | `imageId`                       | Details for one image                                                                                                                                                                             |
+| `image_list`          | —                               | List the built workspace images, base images first                                                                                                                                                |
+| `image_rebuild_all` ✱ | —                               | Ensure every base, then rebuild every custom image in dependency order, skipping any image whose rebuild fails and its dependents; a base it cannot ensure is reported in `skipped` by short name |
+| `image_rebuild` ✱     | `imageId`                       | Rebuild an existing custom image in place                                                                                                                                                         |
+| `image_remove` ✱      | `imageId`                       | Remove a built image; refused while a workspace or container still references it                                                                                                                  |
 
 ### Containers
 
@@ -136,7 +149,7 @@ managed `DSH_*` fact.
 | `container_read`       | `container`, `file_path`, optional `offset`, `limit`                                                  | Read a file                                                                                                                                 |
 | `container_recreate` ✱ | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | Recreate a container, keeping its current image when `image` is omitted, optionally with new project mounts, environment, or PATH additions |
 | `container_remove` ✱   | `container`                                                                                           | Remove a container (stops its daemons gracefully first)                                                                                     |
-| `container_start` ✱    | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | Start a container (default image when `image` is omitted); approval required only when `mounts` is passed                                   |
+| `container_start` ✱    | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | Start a container (default image when `image` is omitted); approval required only when `mounts` or `secretEnv` is passed                    |
 | `container_write`      | `container`, `file_path`, `content`                                                                   | Write a file                                                                                                                                |
 
 The `container_bash`, `container_exec`, `container_read`, `container_write`,
@@ -205,14 +218,13 @@ Project mounts do not take a `destination`: a project directory is always
 mounted at its mirrored path under the projects root. `destination` applies only
 to `tmpfs`, `volume` and `secret` mounts.
 
-In the settings card, the project path field of the add-mount and
-create-container dialogs has a **Browse…** button. It opens a directory picker
-that reads the projects root through dsh's own host-side directory listing — the
-same service behind dsh's workspace directory selection — not through the
-orchestrator or a container. Its layout follows dsh's own directory browser: two
-columns, chevron breadcrumbs, folder icons, and a hidden-entry toggle. The
-dialog is confined to the projects root, and the path it produces is stored
-relative to that root.
+On the Podman page, the project path field of the add-mount and create-container
+dialogs has a **Browse…** button. It opens a directory picker that reads the
+projects root through dsh's own host-side directory listing — the same service
+behind dsh's workspace directory selection — not through the orchestrator or a
+container. Its layout follows dsh's own directory browser: two columns, chevron
+breadcrumbs, folder icons, and a hidden-entry toggle. The dialog is confined to
+the projects root, and the path it produces is stored relative to that root.
 
 Removing a mount names it by `kind` plus that mount's own handle: `project` for
 a project mount, `volume` for a named volume, `secret` for a secret, and
@@ -283,7 +295,7 @@ read tool. A secret can be attached to a container either as a **mount**
 (`container_mount_add kind="secret"` + `secret` + `destination`, read-only, at
 an absolute path never under the projects root) or as an **environment
 variable** (`container_secret_add`; the env var name must not start with
-`DSH_PODMAN`). The settings card can **overwrite** a secret with user-typed
+`DSH_PODMAN`). The Podman page can **overwrite** a secret with user-typed
 content (write-only) but never reads it.
 
 A secret mounted at a path is created as a root-owned **file** (not a directory)
@@ -323,34 +335,34 @@ started with.
 
 ## Container management UI
 
-The plugin ships a browser half that registers a card in the dsh **Settings →
-Plugins** page. The card lists the orchestrator-created guest containers and the
-built images. A workspace with no container gets a **Create container** button
-that opens a configuration modal — image, environment, mounts (project, tmpfs,
-volume, and secret), PATH additions, and secret environment variables — and
-workspaces that already have containers offer an **Add container** button for
-additional, named containers through the same modal, which is titled after the
-button that opened it. In that modal each mount's mode is a dropdown
-(read-only/read-write), so the workspace project mount can be created read-only
-in one step; tmpfs and secret mounts are fixed (read-write and read-only
-respectively) and show a disabled dropdown. Container rows show their
-environment and secret-environment variables and their mounts, let you edit
-environment variables and add/remove mounts (each removal is confirmed), and
-attach/detach named secrets to a container's environment variables; each row
-also offers **Remove**, **Recreate** (same image), and **Recreate with image**.
-Every workspace row also offers **Remove pod**, which removes the workspace's
-pod, all of its containers, and the orchestrator's record for it (volumes,
-secrets, and project data are kept); removing a workspace's last container
-removes its pod as well, so an empty pod is never left behind. The card re-reads
-the live state whenever the Plugins page is opened, and its header has a
-**Reload this view** button. The images section can rebuild a single image or
-**rebuild all** in dependency order; **Build image** opens a popup with an
-image-id/base-image form and a chip input for the package list (type a name and
-press space/comma, or paste a list, to add removable chips). Volumes and secrets
-are listed as individual expandable rows, each with its own actions, and
-**Create volume** / **Create secret** open popup forms (the secret form takes an
-optional length; a secret's value can be overwritten, never read). Card actions
-are direct control calls and are not approval-gated.
+The plugin ships a browser half that registers its card on the **dsh-podman**
+page (sidebar **Plugins** panel → **Installed**). The page lists the
+orchestrator-created guest containers and the built images. A workspace with no
+container gets a **Create container** button that opens a configuration modal —
+image, environment, mounts (project, tmpfs, volume, and secret), PATH additions,
+and secret environment variables — and workspaces that already have containers
+offer an **Add container** button for additional, named containers through the
+same modal, which is titled after the button that opened it. In that modal each
+mount's mode is a dropdown (read-only/read-write), so the workspace project
+mount can be created read-only in one step; tmpfs and secret mounts are fixed
+(read-write and read-only respectively) and show a disabled dropdown. Container
+rows show their environment and secret-environment variables and their mounts,
+let you edit environment variables and add/remove mounts (each removal is
+confirmed), and attach/detach named secrets to a container's environment
+variables; each row also offers **Remove**, **Recreate** (same image), and
+**Recreate with image**. Every workspace row also offers **Remove pod**, which
+removes the workspace's pod, all of its containers, and the orchestrator's
+record for it (volumes, secrets, and project data are kept); removing a
+workspace's last container removes its pod as well, so an empty pod is never
+left behind. The page re-reads the live state whenever the Plugins panel opens
+it, and its footer has a **Reload this view** button. The images section can
+rebuild a single image or **rebuild all** in dependency order; **Build image**
+opens a popup with an image-id/base-image form and a chip input for the package
+list (type a name and press space/comma, or paste a list, to add removable
+chips). Volumes and secrets are listed as individual expandable rows, each with
+its own actions, and **Create volume** / **Create secret** open popup forms (the
+secret form takes an optional length; a secret's value can be overwritten, never
+read). Card actions are direct control calls and are not approval-gated.
 
 A **Package caches** section reports the size of every configured build cache
 (`DSH_PODMAN_HOST_PACMAN_CACHE`, `DSH_PODMAN_HOST_APT_CACHE`,
@@ -360,13 +372,47 @@ versions** removes every cached package file except the newest of each package
 safe — a cached package is only ever re-downloaded — and neither runs while an
 image build is in progress.
 
+## Podman terminal
+
+The plugin owns a **Podman terminal** right-Sidebar tab, separate from dsh's own
+Terminal tab. Open it from the right Sidebar's new-tab guide — the card is **New
+terminal** — or press
+**Ctrl+`**; the tab is named after the shell it runs
+(`bash`,`sh`, …). The built-in Terminal UI is disabled by the plugin's bundle
+patch, which frees that shortcut (if it is enabled again, the plugin falls back
+to **Ctrl+Shift+`**);
+the agent's `terminal` tool is unaffected. It always runs in the session's own
+workspace — each workspace has its own side panes and terminals — so the start
+form only asks for a container and then a shell, and a shell can run in the
+default container or in a named one. If the session's directory names no known
+workspace the form reports that instead of guessing; the harness's own Terminal
+always uses that workspace's default container. The container and shell you last
+started are remembered in the browser's local storage and preselected while they
+are still available — a container that disappeared falls back to the default,
+and a shell the image no longer ships falls back to the first one the container
+offers.
+
+The shell list is discovered **inside the chosen container**: candidate names
+are looked up on that container's PATH (`command -v`) and merged with
+`/etc/shells` and `$SHELL`, so a shell installed through a PATH addition or a
+mounted volume appears while one the image lacks does not. The list is ordered
+most capable first (`zsh`, `bash`, `fish`, … down to `dash`, `ash`, `sh`), so
+the picker preselects the best shell the container has. The selected shell is
+verified again before it starts.
+
+Terminals are retained on the host: switching tabs, closing the Sidebar or
+reloading the page keeps the shell and its scrollback, and reattaching replays
+the screen. Closing the tab leaves the shell retained for a while (until the
+host reaps it); **Reconnect** starts a fresh shell in the current selection.
+Closing or recreating a container drops its terminals, so reconnect afterwards.
+
 ## Podman operator mode
 
 The plugin ships an **agent preset** named _Podman operator mode_ (id
-`podman-ops`). On every load it (re)writes the preset into the harness's
-user-presets root (`~/.dsh/.agent-presets/podman-ops/`), overwriting any local
-copy so the shipped content stays authoritative. It appears in the session's
-agent-preset picker next to the shipped presets.
+`podman-ops`). The plugin's bundle patch declares it as a
+`@deepseek-ai/dsh-agent-preset` row, so the harness's preset registry serves it
+directly. It appears in the session's agent-preset picker next to the shipped
+presets.
 
 The preset composes a Podman-focused persona with the built-in task tools
 (`ask_user_question`, `todo_write`) and `web_search` (web fetch disabled). It
@@ -377,7 +423,8 @@ are global and all remain available, split as:
 - **Direct:** `image_list`, `image_get`, `container_list`, `container_read`,
   `container_glob`, `container_grep`, `container_mount_list`, `volume_list`,
   `secret_list`, `secret_create`, `daemon_list`, `daemon_logs`, `daemon_stop`,
-  `daemon_restart`, `container_start` (asks only when `mounts` is passed).
+  `daemon_restart`, `container_start` (asks only when `mounts` or `secretEnv` is
+  passed).
 - **Approval-gated** (the usual `✱` tools): `image_build`, `image_rebuild`,
   `image_rebuild_all`, `image_remove`, `container_recreate`, `container_remove`,
   `container_mount_add`, `container_mount_remove`, `container_mount_update`,

package/docs/usage.zh.md

@@ -6,7 +6,8 @@ SPDX-License-Identifier: MIT
 
 # 使用
 
-本页面记录了面向模型的工具、设置卡片以及镜像模型。参见[架构](architecture.zh.md)了解各部分如何组合在一起。
+本页面记录了面向模型的工具、Podman
+页面以及镜像模型。参见[架构](architecture.zh.md)了解各部分如何组合在一起。
 
 ## 模型上下文
 
@@ -16,7 +17,9 @@ Harness 会添加一个提示词区段，指明其自身的磁盘检出目录，
 
 dsh-podman 还会添加自己的提示词区段，说明内置的 shell
 与文件系统工具（`bash`、`read`、`write`、`edit`、`glob`、`grep`）在工作区的默认容器内运行，而非宿主机，并说明它们与
-`container_*` 工具的关系。
+`container_*` 工具的关系。同一区段还会引导模型：安装软件时用 `image_build`
+构建自定义镜像（再用 `container_start` 或 `container_recreate`
+启动），需要跨容器重建保留的数据应使用命名卷而非 `tmpfs`。
 
 ## 镜像模型
 
@@ -31,7 +34,8 @@ dsh-podman 将容器运行的镜像组织为三个层级：
   拥有的默认软件包列表及其软件包管理器定义。默认情况下它们从原始镜像**本地构建**（安装默认软件包）；当
   `DSH_PODMAN_BASE_IMAGE_PREFIX` 指向某个镜像仓库（任何不以 `localhost/`
   开头的名称）时，它们改为被**拉取**。即使尚未构建/拉取，基础镜像也会列在设置 UI
-  中，可从卡片重建或拉取，并且它们的短名称是保留的——它们不能被覆盖构建、重建或作为自定义镜像移除。
+  中，可从 Podman
+  页面重建或拉取，并且它们的短名称是保留的——它们不能被覆盖构建、重建或作为自定义镜像移除。
 - **自定义镜像**是从**父镜像**——基础镜像或另一个自定义镜像——创建的用户构建镜像，继承其软件包管理器并在此基础上添加额外软件包。它们通过短名称引用（例如
   `valkey`）。
 
@@ -60,14 +64,17 @@ dsh-podman 将容器运行的镜像组织为三个层级：
   和 `grep` 始终可运行。
 - **Workspace Write** — 带 `✱` 的工具通过 DSH
   的审批服务询问（调用会显示标准审批提示，当没有可用的审批通道时被拒绝）；`container_start`
-  仅在传入 `mounts` 时询问。
+  仅在传入 `mounts` 或 `secretEnv` 时询问。
 - **Full access** — 工具运行时不显示审批提示。
 
 harness 的 `sandbox_permissions` 参数（例如 `bash`
 上的一次性沙箱放宽）会被接受但在此处没有效果：沙箱在容器内被绕过，因此插件会直接授予该升权而不询问。
 
 审批提示的原因是一句话，说明操作及其涉及的对象，并对每个标识符加引号——例如
-`Add mount to container "web": volume "data" (read-only)`。它涵盖容器镜像、每个挂载的类型与目标路径、环境变量的键，以及解析后的文件路径。它会跟随界面语言：浏览器客户端将当前语言记录到插件设置中，并以持久化的语言偏好作为回退（两者都未设置时为英文）。策略拒绝——只读沙箱，或项目挂载上指定了目标路径——也会使用相同的语言。设置卡片操作是直接的控制调用，不进行门控。
+`Add mount to container "web": volume "data" (read-only)`。它涵盖容器镜像、每个挂载的类型与目标路径、环境变量的键、机密环境变量名，以及解析后的文件路径。它会跟随界面语言：浏览器客户端将当前语言记录到插件的
+`uiLocale`
+偏好中，并由主机持久化到插件配置（未设置时为英文）。策略拒绝——只读沙箱，或项目挂载上指定了目标路径——也会使用相同的语言。Podman
+页面操作是直接的控制调用，不进行门控。
 
 `container_start`、`container_recreate` 和 `container_bash` 接受应用于容器（或
 bash 进程）的 `env` 映射；`container_exec` 和 `daemon_start` 已经接受 `env`，而
@@ -79,6 +86,12 @@ bash 进程）的 `env` 映射；`container_exec` 和 `daemon_start` 已经接
 `container_list` 显示变量的**键**。以 `DSH_PODMAN`
 开头的键被保留并被拒绝，因为编排器将该命名空间用于 guest-agent 接线。
 
+新容器还会注入插件的**默认环境变量**（`containerEnv` 设置），因此 Git
+身份只需配置一次，而不必按项目重复设置——见[默认环境变量](configuration.zh.md#默认环境变量)。Podman
+页面中的 **Git 身份**弹窗用一份姓名与邮箱填入四个
+`GIT_AUTHOR_*`/`GIT_COMMITTER_*`
+变量，**应用默认环境变量**会把它们补给尚未具备的现有运行中容器。
+
 `container_bash` 和 `container_exec` 使用与内置 `bash`
 相同的命令可见环境运行：harness 托管的 `DSH_*`
 事实（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`、`DSH_WEB_URL`）及其非交互式终端覆盖项（`NO_COLOR`、`TERM=dumb`、`PAGER=cat`、`GIT_PAGER=cat`）。调用方的
@@ -86,30 +99,30 @@ bash 进程）的 `env` 映射；`container_exec` 和 `daemon_start` 已经接
 
 ### 镜像
 
-| 工具                  | 参数                            | 描述                                                                                 |
-| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
-| `image_build` ✱       | `imageId`, `parent`, `packages` | 从基础或自定义父镜像及软件包列表构建新的自定义镜像                                   |
-| `image_get`           | `imageId`                       | 单个镜像的详细信息                                                                   |
-| `image_list`          | —                               | 列出已构建的工作区镜像，基础镜像在前                                                 |
-| `image_rebuild_all` ✱ | —                               | 确保每个基础镜像，然后按依赖顺序重建每个自定义镜像，跳过重建失败的任何镜像及其依赖项 |
-| `image_rebuild` ✱     | `imageId`                       | 原地重建现有的自定义镜像                                                             |
-| `image_remove` ✱      | `imageId`                       | 移除已构建的镜像；当工作区或容器仍引用它时拒绝                                       |
+| 工具                  | 参数                            | 描述                                                                                                                                |
+| --------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `image_build` ✱       | `imageId`, `parent`, `packages` | 从基础或自定义父镜像及软件包列表构建新的自定义镜像                                                                                  |
+| `image_get`           | `imageId`                       | 单个镜像的详细信息                                                                                                                  |
+| `image_list`          | —                               | 列出已构建的工作区镜像，基础镜像在前                                                                                                |
+| `image_rebuild_all` ✱ | —                               | 确保每个基础镜像，然后按依赖顺序重建每个自定义镜像，跳过重建失败的任何镜像及其依赖项；无法确保的基础镜像以短名称出现在 `skipped` 中 |
+| `image_rebuild` ✱     | `imageId`                       | 原地重建现有的自定义镜像                                                                                                            |
+| `image_remove` ✱      | `imageId`                       | 移除已构建的镜像；当工作区或容器仍引用它时拒绝                                                                                      |
 
 ### 容器
 
-| 工具                   | 参数                                                                                                  | 描述                                                                                |
-| ---------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `container_bash`       | `container`, `command`, `description`, optional `workdir`, `timeoutMs`, `env`, `uid`, `gid`, `groups` | 运行 shell 命令                                                                     |
-| `container_edit`       | `container`, `file_path`, `old_string`, `new_string`, optional `replace_all`                          | 编辑文件                                                                            |
-| `container_exec`       | `container`, `argv`, `description`, optional `workdir`, `timeoutMs`, `env`, `uid`, `gid`, `groups`    | 运行程序                                                                            |
-| `container_glob`       | `container`, `pattern`, optional `path`                                                               | 列出匹配模式的文件                                                                  |
-| `container_grep`       | `container`, `pattern`, optional `path`, `include`                                                    | 按正则表达式搜索文件                                                                |
-| `container_list`       | —                                                                                                     | 列出当前工作区的容器                                                                |
-| `container_read`       | `container`, `file_path`, optional `offset`, `limit`                                                  | 读取文件                                                                            |
-| `container_recreate` ✱ | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | 重建容器，省略 `image` 时保留其当前镜像，可选地使用新的项目挂载、环境或 PATH 附加项 |
-| `container_remove` ✱   | `container`                                                                                           | 移除容器（先优雅地停止其守护进程）                                                  |
-| `container_start` ✱    | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | 启动容器（省略 `image` 时使用默认镜像）；仅在传入 `mounts` 时需要审批               |
-| `container_write`      | `container`, `file_path`, `content`                                                                   | 写入文件                                                                            |
+| 工具                   | 参数                                                                                                  | 描述                                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `container_bash`       | `container`, `command`, `description`, optional `workdir`, `timeoutMs`, `env`, `uid`, `gid`, `groups` | 运行 shell 命令                                                                      |
+| `container_edit`       | `container`, `file_path`, `old_string`, `new_string`, optional `replace_all`                          | 编辑文件                                                                             |
+| `container_exec`       | `container`, `argv`, `description`, optional `workdir`, `timeoutMs`, `env`, `uid`, `gid`, `groups`    | 运行程序                                                                             |
+| `container_glob`       | `container`, `pattern`, optional `path`                                                               | 列出匹配模式的文件                                                                   |
+| `container_grep`       | `container`, `pattern`, optional `path`, `include`                                                    | 按正则表达式搜索文件                                                                 |
+| `container_list`       | —                                                                                                     | 列出当前工作区的容器                                                                 |
+| `container_read`       | `container`, `file_path`, optional `offset`, `limit`                                                  | 读取文件                                                                             |
+| `container_recreate` ✱ | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | 重建容器，省略 `image` 时保留其当前镜像，可选地使用新的项目挂载、环境或 PATH 附加项  |
+| `container_remove` ✱   | `container`                                                                                           | 移除容器（先优雅地停止其守护进程）                                                   |
+| `container_start` ✱    | `container`, optional `image`, `mounts`, `env`, `secretEnv`, `paths`                                  | 启动容器（省略 `image` 时使用默认镜像）；仅在传入 `mounts` 或 `secretEnv` 时需要审批 |
+| `container_write`      | `container`, `file_path`, `content`                                                                   | 写入文件                                                                             |
 
 `container_bash`、`container_exec`、`container_read`、`container_write`、
 `container_edit`、`container_glob` 和 `container_grep` 的参数与 harness 内置的
@@ -166,7 +179,7 @@ UI 行（图标、标题、摘要和结果正文），因此它们会像内置
 根目录下与之对应的路径上。`destination` 仅适用于 `tmpfs`、`volume` 和 `secret`
 挂载。
 
-在设置卡片中，添加挂载与创建容器对话框的项目路径字段带有 **浏览…**
+在 Podman 页面中，添加挂载与创建容器对话框的项目路径字段带有 **浏览…**
 按钮。它会打开一个目录选择器，通过 dsh 自身的主机侧目录列表（也就是 dsh
 工作区目录选择所用的同一服务）读取 projects
 根目录，而不经过编排器或容器。其布局与 dsh
@@ -231,8 +244,8 @@ UI 使用短名称。`secret_create` 的值由服务端用 `crypto/rand`
 生成，且**永不暴露**——没有读取工具。机密可以附加到容器上，既可以作为**挂载**（`container_mount_add kind="secret"` +
 `secret` + `destination`，只读，位于绝不位于 projects
 根目录之下的绝对路径），也可以作为**环境变量**（`container_secret_add`；环境变量名不得以
-`DSH_PODMAN`
-开头）。设置卡片可以用用户输入的内容**覆盖**机密（只写），但绝不读取它。
+`DSH_PODMAN` 开头）。Podman
+页面可以用用户输入的内容**覆盖**机密（只写），但绝不读取它。
 
 挂载到某个路径的机密以 root 所有的**文件**（而非目录）形式创建，权限为除 root
 外一律拒绝，因此只有容器的默认（root）用户可以读取它；以其他 `uid`
@@ -267,8 +280,8 @@ UI 使用短名称。`secret_create` 的值由服务端用 `crypto/rand`
 
 ## 容器管理 UI
 
-插件附带一个浏览器端，在 dsh **Settings → Plugins**
-页面注册一个卡片。该卡片列出编排器创建的 guest
+插件附带一个浏览器端，把卡片注册到 **dsh-podman** 页面（侧边栏 **插件** 面板 →
+**已安装**）。该页面列出编排器创建的 guest
 容器和已构建的镜像。没有容器的工作区会得到一个 **Create container**
 按钮，打开一个配置模态框——镜像、环境、挂载（project、tmpfs、volume 和
 secret）、PATH 附加项以及机密环境变量——而已有容器的工作区通过同一个模态框提供
@@ -279,23 +292,48 @@ read-only），显示为不可编辑的下拉框。容器行显示其环境和
 **Remove**、**Recreate**（相同镜像）和 **Recreate with
 image**。每个工作区行还提供 **移除 Pod**，它会移除该工作区的
 Pod、其所有容器以及编排器对应的记录（卷、机密和项目数据会保留）；移除工作区的最后一个容器也会一并移除其
-Pod，因此不会留下空的 Pod。每次打开 Plugins
-页面时卡片都会重新读取实时状态，其头部还有一个 **Reload this view**
+Pod，因此不会留下空的 Pod。每次通过 **插件**
+面板打开该页面时都会重新读取实时状态，其底部还有一个 **Reload this view**
 按钮。镜像部分可以重建单个镜像或按依赖顺序**重建全部**；**Build image**
 打开一个弹窗，包含 image-id/base-image 表单和用于软件包列表的 chip
 输入框（输入名称并按空格/逗号，或粘贴列表，以添加可移除的
 chips）。卷和机密以独立的可展开行列出，每行都有自己的操作，**Create volume** /
 **Create secret**
-打开弹窗表单（机密表单接受可选的长度；机密的值可以被覆盖，但绝不读取）。卡片操作是直接的控制调用，不受审批门控。
+打开弹窗表单（机密表单接受可选的长度；机密的值可以被覆盖，但绝不读取）。Podman
+页面操作是直接的控制调用，不受审批门控。
 
 **软件包缓存**区段会报告每个已配置构建缓存（`DSH_PODMAN_HOST_PACMAN_CACHE`、`DSH_PODMAN_HOST_APT_CACHE`、`DSH_PODMAN_HOST_APK_CACHE`）的大小，并提供两个清理操作：**保留最新版本**会移除每个软件包除最新版本之外的所有缓存文件（连同其签名），**全部移除**会清空缓存。两者都是安全的——缓存的软件包只会被重新下载——且都不会在镜像构建进行时运行。
 
+## Podman 终端
+
+插件自带一个右侧边栏的 **Podman 终端**标签页，与 dsh
+自带的终端标签页相互独立。可从右侧边栏的“新建标签页”指南中打开（卡片名为**新建终端**），或按
+**Ctrl+`**；标签页以所运行的 shell 命名（`bash`、`sh`等）。插件的 bundle patch 会禁用 dsh 自带的终端界面，从而让出该快捷键（若重新启用，插件会回退到 **Ctrl+Shift+`**）；agent
+的 `terminal`
+工具不受影响。它始终在会话所在的工作区中运行——每个工作区都有自己的侧边栏和终端——因此启动表单只需选择容器和
+shell，既可在默认容器中运行，也可在命名容器中运行；若会话目录不属于任何已知工作区，表单会直接提示而不是猜测。harness
+自带的终端始终使用该工作区的默认容器。上次启动所使用的容器与 shell
+会记录在浏览器的本地存储中，只要仍然可用就会预先选中——容器已不存在时回退到默认容器，镜像不再提供该
+shell 时回退到容器提供的第一个 shell。
+
+shell 列表在**所选容器内部**探测：按候选名称在该容器的 PATH
+中查找（`command -v`），并与 `/etc/shells` 和 `$SHELL` 合并，因此通过 PATH
+追加项或挂载卷安装的 shell
+会出现，而镜像中不存在的则不会。列表按能力从强到弱排列（`zsh`、`bash`、`fish`……直到
+`dash`、`ash`、`sh`），因此选择器会预选容器中最好的
+shell。启动前还会再次校验所选 shell。
+
+终端由主机保留：切换标签页、关闭侧边栏或刷新页面都不会丢失 shell
+及其回滚缓冲，重新接入时会回放屏幕内容。关闭标签页后 shell
+仍会保留一段时间（直到主机回收）；**重新连接**会在当前选择中启动一个新的
+shell。关闭或重建容器会丢弃其终端，之后请重新连接。
+
 ## Podman 操作员模式
 
 插件附带一个名为 _Podman operator mode_（id `podman-ops`）的 **agent
-预设**。每次加载时，它都会将预设（重新）写入 harness
-的用户预设根目录（`~/.dsh/.agent-presets/podman-ops/`），覆盖任何本地副本，使发布的内容保持权威。它出现在会话的
-agent 预设选择器中，紧挨着内置预设。
+预设**。插件的 bundle patch 会把它声明为一行
+`@deepseek-ai/dsh-agent-preset`，因此 harness
+的预设注册表会直接提供它。它出现在会话的 agent 预设选择器中，紧挨着内置预设。
 
 该预设将聚焦 Podman 的人格与内置任务工具（`ask_user_question`、`todo_write`）和
 `web_search`（web fetch 已禁用）组合在一起。它不挂载主机 shell、主机文件系统或
@@ -304,7 +342,7 @@ mode、jobs）。插件自身的工具是全局的，全部保持可用，分为
 
 - **直接：**
   `image_list`、`image_get`、`container_list`、`container_read`、`container_glob`、`container_grep`、`container_mount_list`、`volume_list`、`secret_list`、`secret_create`、`daemon_list`、`daemon_logs`、`daemon_stop`、`daemon_restart`、`container_start`（仅在传入
-  `mounts` 时询问）。
+  `mounts` 或 `secretEnv` 时询问）。
 - **需审批**（通常的 `✱`
   工具）：`image_build`、`image_rebuild`、`image_rebuild_all`、`image_remove`、`container_recreate`、`container_remove`、`container_mount_add`、`container_mount_remove`、`container_mount_update`、`container_path_set`、`container_path_add`、`container_path_remove`、`volume_remove`、`secret_remove`、`container_secret_add`、`container_secret_remove`。
 - **仅在此预设中需审批：**

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-podman",
+    "description": "Podman-backed execution for DeepSeek Harness (dsh)."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-podman",
+    "description": "为 DeepSeek Harness（dsh）提供基于 Podman 的容器执行环境。"
+  }
+}