@hyzyn/dsh-docker 0.11.0 → 0.12.0

package/README.en.md

@@ -608,7 +608,8 @@ and reconnect". The record list can be deleted / reset in the settings card (del
 | `docker_ps` | always registered | `target?` (**pass `*` = all targets**), `all?: boolean` | lists containers (name / state / health / image / ports / compose project and service / short ID); by default only running ones, `all:true` includes stopped. With `target:'*'` it returns results grouped by target, and **one unreachable target does not affect the others** (that group carries `error`). Ports are merged across the IPv4/IPv6 dual-stack expansion (one `-p` no longer shows twice, D130); an empty `ports` does **not** mean "nothing exposed" — host-network containers publish on the host itself, and that case now carries a `net` field (D131). The first step of troubleshooting |
 | `docker_attention` | always registered | `target?` (supports `*`), `limit?: number` | a **needs-attention summary**: unhealthy / repeatedly restarting / OOM-killed / non-zero exit / zombie; every item carries `reasons`, `exitCode`, `oomKilled`, `restartCount`. OOM and the real exit code come from one `docker inspect` (a ps summary cannot distinguish a manual kill from 137). The troubleshooting entry point: call it first when you are unsure which machine or container to look at |
 | `docker_inspect` | always registered | `target?`, `id` (required) | `docker inspect`'s authoritative details: state / health check / exit code / restart count / ports / mounts / networks / startup command |
-| `docker_logs` | always registered | `target?`, `id`, `tail?` (1–5000, default `logTailDefault`), `timestamps?`, `since?` | the tail from `docker logs --tail`; `since` uses docker syntax (such as `10m`, `2026-09-09T10:00:00`); over the cap it is marked `truncated` |
+| `docker_logs` | always registered | `target?`, `id`, `tail?` (1–5000, default `logTailDefault`), `timestamps?`, `since?`, `until?` | the tail from `docker logs --tail`; `since` / `until` use docker syntax (e.g. `10m`, `2026-09-09T10:00:00`) to bound a time window; over the cap it is marked `truncated` |
+| `docker_logs_grep` | always registered | `target?`, `id`, `pattern` (required, ≤512 chars), `regexp?`, `ignoreCase?`, `since?`, `until?`, `context?` (0–20, default 2), `limit?` (1–500, default 200), `tail?` (omitted = scan all history), `timestamps?` (on by default) | **server-side log search**: line-by-line filtering in the host (never touches the remote shell, never pipes `| grep`), returns hit lines plus ±context lines, and honestly reports `matched` (all hits even when not returned) / `scanned` / `limited` / `truncated` — "only scanned this far" is distinguishable from "scanned everything"; the scan window is **aligned to line boundaries** (the partial line left by a byte-level cut is never returned as a line, so every entry in `lines` is a complete line). Division of labour with `docker_logs`: error in the recent tail → `docker_logs` (cheaper); buried deep / a specific time window / keywords, error codes, request IDs → this tool. Literal substring by default (grep -F semantics, zero ReDoS); JS regex only with `regexp: true` |
 | `docker_stats` | always registered | `target?`, `ids?` (comma-separated container names/IDs) | a `docker stats --no-stream` snapshot: CPU% / memory usage and share / network IO / block IO / PIDs; omitting `ids` means all running containers. Live following is a panel capability (SSE), and the tool keeps single-value snapshot semantics |
 | `docker_images` | always registered | `target?` | image list (repository:tag / size / created / short ID) |
 | `docker_events` | always registered | `target?`, `since?` (docker `--since` syntax, default `10m`) | a container-event snapshot (`docker events --since <d> --until <now>`, likewise through the server-side allowlist): the nine kinds start / die / stop / kill / oom / health_status / destroy / rename / update, with noise such as `exec_*` already dropped server-side. For continuous observation have the user watch the "Activity" strip in the panel's container list |
@@ -637,7 +638,9 @@ and reconnect". The record list can be deleted / reset in the settings card (del
   static switches above: the switches govern registration (host-level, persistent grant), the tier gate governs
   each registered call (per call, follows the tier immediately). Mechanism:
   [docs/permission-tier-plan.md](../../docs/permission-tier-plan.md).
-- Recommended troubleshooting order: `docker_targets` → `docker_ps` → `docker_logs` →
+- Recommended troubleshooting order: `docker_targets` → `docker_ps` → `docker_logs`
+  (when the tail does not explain the failure, `docker_logs_grep` with `pattern` /
+  `since` / `until` to search deeper) →
   `docker_inspect` → `docker_stats`; for image problems `docker_images` →
   `docker_image_inspect`.
 - With `announceToAgent` on, the plugin injects a capability announcement into the systemPrompt (including the
@@ -1028,7 +1031,7 @@ Host half (src/index.ts)
   ├─ image routes: /images/inspect (read-only) · /images/remove · /images/prune (allowMutations)
   ├─ network / volume routes: /networks · /volumes and their inspect (read-only), remove / prune (allowMutations)
   └─ agent tools: docker_targets / docker_ps / docker_inspect /
-     docker_logs (snapshot semantics unchanged) / docker_stats / docker_events / docker_images /
+     docker_logs (snapshot semantics unchanged) / docker_logs_grep (server-side search) / docker_stats / docker_events / docker_images /
      docker_image_inspect / docker_networks / docker_volumes (always registered)
      + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
        (allowMutations) / docker_exec (allowExec)
@@ -1162,8 +1165,8 @@ lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 fo
      should **name podman** and say "put podman in 'docker CLI' and it works", while **not**
      rewriting `dockerBin` for you (go back to the settings card — the value is still `docker`).
 4. **Read-only interception**: with both switches off, `/action`, `/exec`, `/images/remove`,
-   `/images/prune`, `/images/pull/stream` all return 403; on the agent side exactly 12 read-only tools are
-   registered (`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `stats` / `events` / `images` /
+   `/images/prune`, `/images/pull/stream` all return 403; on the agent side exactly 13 read-only tools are
+   registered (`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `logs_grep` / `stats` / `events` / `images` /
    `image_inspect` / `networks` / `volumes` — see the tool table for the authoritative list), and
    the panel's start / stop / remove, image removal, pruning and pull buttons are greyed out. After turning on
    "allow mutations" these routes and tools appear immediately (no restart needed).
@@ -1291,6 +1294,25 @@ lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 fo
     Reverse check: switch to Target2 and then immediately back to Target1 (which still cannot connect) → the banner
     should describe Target1's own
     failure, not treat Target2's successful result as Target1's.
+21. **`docker_logs_grep` server-side search** (the shape used for the 2026-10-09 real-machine run): start a
+   container whose log content you know in advance (any image you already have locally; no network needed):
+   `docker run -d --rm --name dsh-grep-probe <local image> sh -c 'echo "[boot] starting"; for i in 1 2 3 4 5; do echo "tick $i ok"; done; echo "FATAL request-id=REQ-7788"; echo "WARN disk 91%" >&2; sleep 3600'`
+   Then have the agent search it with `docker_logs_grep` and **check the raw return value item by item** (do not
+   accept a paraphrase):
+   - search `FATAL` → 1 hit, "scanned 8 lines", the hit marked `>` with ±2 context lines;
+   - `tick [0-9]+` **without** `regexp` → 0 hits; with `regexp=true` → 5 hits (proves the default is **literal**);
+   - `fatal` without `ignoreCase` → 0; with `ignoreCase=true` → 1;
+   - `tick` + `limit=1` → "5 hits" reported but only one window returned, plus the "hits exceed the limit" note (`limited`);
+   - `since=1h` hits / `until=1h` and `since=1s` both 0 hits **and "scanned 0 lines"** (proves `--since`/`--until` really pass through);
+   - search `WARN` → the hit line's stream is `[err]`;
+   - search a container that does not exist → docker's own error text, **not** an empty result.
+   Forcing `truncated` needs a log **>8MB** (the 8MB scan floor is hard; lowering "output limit (KB)" does not move it):
+   let a container write ~300k lines with the needles at the **very head** and the **very tail** → a full scan gives
+   0 hits + the "scan output exceeded the byte limit" note for the former and a hit + the same note for the latter;
+   adding `tail=5000` makes the note disappear in both (proving it reports a **real** scan-side overflow, not
+   "the log is big so it is always true"). Also, **every returned line must be a complete line** (timestamp prefix):
+   the byte gate cuts mid-line, and `lineAlign` drops that partial line (see the real-machine correction in ROADMAP)
+   — a fragment such as `g line 174798` without a timestamp means this has regressed.
 
 ## Version / license
 

package/README.md

@@ -579,7 +579,8 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 | `docker_ps` | 恒注册 | `target?`（**传 `*` = 全部目标**）、`all?: boolean` | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。`target:'*'` 时按目标分组返回，**单个目标不可达不影响其他目标**（该组带 `error`）。端口是 IPv4/IPv6 双栈归并后的映射（同一次 `-p` 不再出现两遍，D130）；`ports` 为空**不等于**没暴露端口——host 网络容器的端口即宿主机端口，这种情况会给 `net` 字段（D131）。排障第一步 |
 | `docker_attention` | 恒注册 | `target?`（支持 `*`）、`limit?: number` | **需关注汇总**：不健康 / 反复重启 / 被 OOM 杀 / 非零退出 / 僵死；每条带 `reasons`、`exitCode`、`oomKilled`、`restartCount`。OOM 与真实退出码来自一次 `docker inspect`（ps 摘要里 137 无法区分手动 kill）。排障入口：不确定从哪台/哪个容器看起时先调它 |
 | `docker_inspect` | 恒注册 | `target?`、`id`（必填） | `docker inspect` 的权威详情：状态 / 健康检查 / 退出码 / 重启次数 / 端口 / 挂载 / 网络 / 启动命令 |
-| `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?` | `docker logs --tail` 尾部；`since` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）；超上限标记 `truncated` |
+| `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?`、`until?` | `docker logs --tail` 尾部；`since` / `until` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）圈时间窗；超上限标记 `truncated` |
+| `docker_logs_grep` | 恒注册 | `target?`、`id`、`pattern`（必填，≤512 字符）、`regexp?`、`ignoreCase?`、`since?`、`until?`、`context?`（0~20，默认 2）、`limit?`（1~500，默认 200）、`tail?`（缺省 = 扫全部历史）、`timestamps?`（默认开） | **日志服务端检索**：宿主侧逐行过滤（不碰远端 shell、不拼 `\| grep`），返回命中行 + 前后上下文，并如实报告 `matched`（全量命中数，即使没返回）/ `scanned` / `limited` / `truncated`——「只扫到这些」与「扫完了没更多」可区分；扫描窗口**对齐到行边界**（按字节截断处的半行不当作一行返回，所以 `lines` 里每一行都是完整的行）。与 `docker_logs` 的分工：报错就在最近尾部 → `docker_logs`（便宜）；埋在深处 / 特定时间窗 / 找关键词、异常码、请求 ID → 本工具。默认字面子串（grep -F 语义，零 ReDoS），`regexp: true` 才按 JS 正则 |
 | `docker_stats` | 恒注册 | `target?`、`ids?`（逗号分隔的容器名/ID） | `docker stats --no-stream` 快照：CPU% / 内存用量与占比 / 网络 IO / 块 IO / PIDs；`ids` 省略 = 全部运行中容器。实时跟随是面板能力（SSE），工具保持单值快照语义 |
 | `docker_images` | 恒注册 | `target?` | 镜像列表（仓库:标签 / 大小 / 创建时间 / 短 ID） |
 | `docker_events` | 恒注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
@@ -605,7 +606,8 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
   `tier-gate: services absent (…), per-call gate disabled`。它与上面两个静态开关是**双层**：
   静态开关管注册（宿主级、持久授权），档位闸管已注册调用的放行（逐调用、随档位即时变）。
   机制见 [docs/permission-tier-plan.md](../../docs/permission-tier-plan.md)。
-- 推荐排障顺序：`docker_targets` → `docker_ps` → `docker_logs` →
+- 推荐排障顺序：`docker_targets` → `docker_ps` → `docker_logs`（尾部看不到成因就
+  `docker_logs_grep` 带 `pattern` / `since` / `until` 检索深处）→
   `docker_inspect` → `docker_stats`；镜像排查 `docker_images` →
   `docker_image_inspect`。
 - `announceToAgent` 开启时，插件向 systemPrompt 注入一段能力公告（含「默认
@@ -977,7 +979,7 @@ abort）、客户端断开静默中止。各自只差执行器与结束原因：
   ├─ 镜像路由：/images/inspect（只读）· /images/remove · /images/prune（allowMutations）
   ├─ 网络 / 卷路由：/networks · /volumes 与各自的 inspect（只读）、remove / prune（allowMutations）
   └─ agent 工具：docker_targets / docker_ps / docker_inspect /
-     docker_logs（快照语义不变）/ docker_stats / docker_events / docker_images /
+     docker_logs（快照语义不变）/ docker_logs_grep（服务端检索）/ docker_stats / docker_events / docker_images /
      docker_image_inspect / docker_networks / docker_volumes（恒注册）
      + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
        （allowMutations）/ docker_exec（allowExec）
@@ -1110,9 +1112,9 @@ network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoin
      **点名 podman** 并说明「把『docker CLI』填成 podman 就能用」，同时**不该**替你
      改 `dockerBin`（回头去设置卡片看，值仍是 `docker`）。
 4. **只读拦截**：两个开关都关时，`/action`、`/exec`、`/images/remove`、
-   `/images/prune`、`/images/pull/stream` 全部 403；agent 侧恒注册 12 个只读工具
-   （`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `stats` / `events` /
-   `images` / `image_inspect` / `networks` / `volumes`，数量以工具表为准），
+   `/images/prune`、`/images/pull/stream` 全部 403；agent 侧恒注册 13 个只读工具
+   （`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` /
+   `logs_grep` / `stats` / `events` / `images` / `image_inspect` / `networks` / `volumes`，数量以工具表为准），
    面板的启停删 / 镜像删除 / 清理 / 拉取按钮置灰。打开「允许变更操作」后这些
    路由与工具立即出现（无需重启）。
 5. **日志 / 统计 / 镜像**：`tail` 与 `timestamps` / `since` 生效；统计显示
@@ -1205,6 +1207,23 @@ network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoin
    目标1 的容器。从总览点 目标1 那张红色计数卡进去，同样不该看到上一个目标的失败。
    反向验证：切到目标2 后立刻切回目标1（它仍然连不上）→ 横幅应写的是目标1 自己的
    失败，而不是把目标2 的成功结果当成了目标1 的。
+21. **`docker_logs_grep` 服务端检索**（2026-10-09 真机实测的口径）：起一个日志内容已知的容器
+   （用本地已有镜像即可，不必联网）：
+   `docker run -d --rm --name dsh-grep-probe <本地镜像> sh -c 'echo "[boot] starting"; for i in 1 2 3 4 5; do echo "tick $i ok"; done; echo "FATAL request-id=REQ-7788"; echo "WARN disk 91%" >&2; sleep 3600'`
+   然后在会话里让 agent 用 `docker_logs_grep` 检索它，**逐项看原始返回值**（别接受转述）：
+   - 找 `FATAL` → 命中 1 行、「扫描 8 行」、命中行标 `>` 且带 ±2 行上下文；
+   - `tick [0-9]+` **不传** `regexp` → 0 命中；传 `regexp=true` → 5 命中（证明默认是**字面**匹配）；
+   - `fatal` 不传 `ignoreCase` → 0；传 `ignoreCase=true` → 1；
+   - `tick` + `limit=1` → 「命中 5 行」但只返回 1 组窗口，并出现「命中超过上限」提示（`limited`）；
+   - `since=1h` 命中 / `until=1h` 与 `since=1s` 各 0 命中**且「扫描 0 行」**（证明 `--since`/`--until` 真透传）；
+   - 找 `WARN` → 命中行的 stream 是 `[err]`；
+   - 检索不存在的容器 → 报 docker 原文错误，**不是**空结果。
+   `truncated` 只能用 **>8MB** 日志逼出来（扫描侧 8MB 硬下限，调小「输出上限（KB）」没用）：
+   让容器打 ~30 万行、探针分别写在**最开头**与**最末尾** → 全量扫时前者 0 命中 + 「扫描输出超过
+   字节上限」提示，后者命中 + 同一提示；加 `tail=5000` 后两者都不再出现该提示（证明它报的是
+   扫描侧**真溢出**，不是「日志大就恒 true」）。另外**返回的每一行都必须是完整行**（带时间戳
+   前缀）：字节闸的切口会切在行中间，`lineAlign` 负责丢掉那个半行（见 ROADMAP 的真机验收补正）
+   —— 看到 `g line 174798` 这种没时间戳的碎片，就是这条回归了。
 
 ## 版本 / 许可证
 

package/lib/docker.d.ts

@@ -348,6 +348,22 @@ export interface ContainerDetail {
 export declare function parseInspectJson(text: string): ContainerDetail[];
 /** inspect 的 `NetworkSettings.Ports`：`{ "80/tcp": [{HostIp, HostPort}] }`。 */
 export declare function parseInspectPorts(value: unknown): PortMapping[];
+/**
+ * 一次性命令的选项**子集**（Runner 面）：= `ExecOptions` 去掉 `input`（这条通道喂不了
+ * stdin）并加上 `signal`。
+ *
+ * 刻意写成具名类型：它原先在 `Runner.run` 与 `createRunner` 的 `withSignal` 里各写了一份
+ * 字面量，于是新增一个字段只能靠对象字面量处的 tsc 报错兜住——`lineAlign` 那次就是先漏在
+ * 第二份上。具名类型之后不存在「第二份」。
+ */
+export interface RunnerRunOptions {
+    timeoutMs?: number;
+    maxBytes?: number;
+    keepTail?: boolean;
+    /** 截断后对齐到行边界（见 `ExecOptions.lineAlign`）；只有 `docker_logs_grep` 用。 */
+    lineAlign?: boolean;
+    signal?: AbortSignal;
+}
 /** 一个目标（target）背后的命令执行通道。 */
 export interface Runner {
     /** 展示用标签：`本机` 或 `user@host`。 */
@@ -358,12 +374,7 @@ export interface Runner {
      * 目前只有跨目标聚合（`aggregateAcrossTargets`）会传——单目标路径的截止时间是
      * `timeoutMs`，它本来就够。
      */
-    run(argv: readonly string[], options?: {
-        timeoutMs?: number;
-        maxBytes?: number;
-        keepTail?: boolean;
-        signal?: AbortSignal;
-    }): Promise<ExecResult>;
+    run(argv: readonly string[], options?: RunnerRunOptions): Promise<ExecResult>;
     /** 长流（logs --follow）：逐块回调，signal 中止；无总超时与输出上限。 */
     stream(argv: readonly string[], handlers: StreamHandlers, signal?: AbortSignal): Promise<StreamResult>;
 }
@@ -375,9 +386,65 @@ export interface LogsOptions {
     tail?: number;
     timestamps?: boolean;
     since?: string;
+    /** 结束时间（docker --until 语法：ISO 8601 时间戳或 Go duration，如 2026-09-09T10:00:00、1h）。*/
+    until?: string;
     /** 实时跟随（`docker logs --follow`）：仅 logsStream() 使用，logs() 忽略。 */
     follow?: boolean;
 }
+/**
+ * 日志检索选项：**默认字面子串**匹配（grep -F 等价），零 ReDoS 风险；
+ * `regexp: true` 时才按 JS 正则解释 pattern（仍建议配 since/until 收窄窗口）。
+ */
+export interface LogGrepOptions {
+    /** 要搜索的字面子串，或（regexp=true 时）正则表达式源文。 */
+    pattern: string;
+    /** true = 把 pattern 当正则；默认 false = 字面子串。 */
+    regexp?: boolean;
+    /** 忽略大小写（字面模式 = grep -i，正则模式 = /i 标志）。 */
+    ignoreCase?: boolean;
+    /** 扫描行数上限（1~5000）；缺省 = `--tail all` 扫全部历史。 */
+    tail?: number;
+    /** 起始时间（与 docker_logs 的 since 同一口径，D45）。 */
+    since?: string;
+    /** 结束时间（docker --until 语法，与 since 同一口径）。 */
+    until?: string;
+    /** 每个命中前后各保留的上下文行数（0~20，默认 2）。 */
+    context?: number;
+    /** 返回命中数上限（1~500，默认 200）。 */
+    limit?: number;
+    /** 时间戳（默认开——深处的命中没有时间等于没用）。 */
+    timestamps?: boolean;
+}
+/** 检索结果里的一行（命中行或它的上下文行）。 */
+export interface LogGrepLine {
+    /** 该通道内的行号（从 1 开始；stdout 在前、stderr 在后，与 logs() 的拼接序一致）。 */
+    seq: number;
+    stream: 'out' | 'err';
+    text: string;
+    /** 这行本身是否命中（false = 只是上下文）。 */
+    hit: boolean;
+    /** 命中时：匹配到的子串（供调用方定位；上下文行为 null）。 */
+    highlight: string | null;
+}
+/** 日志检索结果。两个「截断」要分清：truncated = 扫描侧字节闸截断，limited = 命中数达到 limit。 */
+export interface LogGrepResult {
+    id: string;
+    /** 命中总行数（即使超过 limit 也如实计数）。 */
+    matched: number;
+    /** 实际扫描的行数。 */
+    scanned: number;
+    /** 返回的行数（命中 + 去重后的上下文）。 */
+    returned: number;
+    /** 命中数达到 limit、还有命中没返回。 */
+    limited: boolean;
+    /**
+     * 扫描输出超过字节上限（按**字节**丢最旧——窗口偏新，缩小 since/until 或换目标时段）。
+     * 窗口已对齐到行边界，所以 `lines` 里不会出现半行；但切口之前的内容确实没参与检索。
+     */
+    truncated: boolean;
+    contextLines: number;
+    lines: LogGrepLine[];
+}
 export interface ProbeResult {
     ok: boolean;
     bin: string;
@@ -586,9 +653,26 @@ export declare class DockerApi {
      * 只要新行、不要重放历史；`--tail 0` 正是不补历史、只跟随的原生语义）。
      */
     logsStream(id: string, options: LogsOptions | undefined, handlers: StreamHandlers, signal?: AbortSignal): Promise<StreamResult>;
+    /**
+     * 日志检索（grep）：**宿主侧逐行过滤，不碰远端 shell**——绝不拼 `| grep`
+     * （那会违反「argv 构造、绝不做字符串拼接」的铁律，且 SSH 路径的转义面完全不同）。
+     *
+     * 与 logs() 的分工（写进工具描述，供模型选择）：「报错在最近尾部」→ docker_logs；
+     * 「埋在深处 / 特定时间窗 / 找关键词」→ docker_logs_grep。扫描与返回的预算是**分开**
+     * 的：扫描侧给到 8~32MB（maxOutputKb 只是单命令返回闸，grep 的意义就是从大量原文里
+     * 筛出少量命中），返回侧由 limit × context 夹住；两侧截断各有独立信号位
+     * （truncated = 扫描侧溢出丢最旧、limited = 命中超过 limit），都不静默。扫描窗口
+     * **对齐到行边界**（`lineAlign`）：切口处的半行不当作一行返回，否则它会以没有时间戳的
+     * 噪音形式进模型上下文，看起来像「检索结果里有脏行」。
+     *
+     * 默认字面子串匹配（grep -F 等价，零 ReDoS）；regexp=true 才按 JS 正则解释，
+     * pattern 上限 512 字符。时间戳默认开——深处的命中没有时间等于没用。
+     */
+    logsGrep(id: string, options: LogGrepOptions): Promise<LogGrepResult>;
     /**
      * 日志 argv 的唯一构造点：快照与流式只在 `--follow` 与 tail 下限上有差异，
      * 校验与夹紧必须逐字一致（否则同一 id 在两条路径上行为漂移）。
+     * `tailOverride` 供 logsGrep 传 `all`（检索要扫全部历史，而不是尾部 5000 行）。
      */
     private logsArgv;
     /** 生命周期操作；调用方负责 readOnly / allowMutations 门禁。 */

package/lib/docker.js

@@ -1421,22 +1421,141 @@ export class DockerApi {
         const safe = assertRef(id, 'container');
         return await this.runner.stream(this.logsArgv(safe, options, true), handlers, signal);
     }
+    /**
+     * 日志检索（grep）：**宿主侧逐行过滤，不碰远端 shell**——绝不拼 `| grep`
+     * （那会违反「argv 构造、绝不做字符串拼接」的铁律，且 SSH 路径的转义面完全不同）。
+     *
+     * 与 logs() 的分工（写进工具描述，供模型选择）：「报错在最近尾部」→ docker_logs；
+     * 「埋在深处 / 特定时间窗 / 找关键词」→ docker_logs_grep。扫描与返回的预算是**分开**
+     * 的：扫描侧给到 8~32MB（maxOutputKb 只是单命令返回闸，grep 的意义就是从大量原文里
+     * 筛出少量命中），返回侧由 limit × context 夹住；两侧截断各有独立信号位
+     * （truncated = 扫描侧溢出丢最旧、limited = 命中超过 limit），都不静默。扫描窗口
+     * **对齐到行边界**（`lineAlign`）：切口处的半行不当作一行返回，否则它会以没有时间戳的
+     * 噪音形式进模型上下文，看起来像「检索结果里有脏行」。
+     *
+     * 默认字面子串匹配（grep -F 等价，零 ReDoS）；regexp=true 才按 JS 正则解释，
+     * pattern 上限 512 字符。时间戳默认开——深处的命中没有时间等于没用。
+     */
+    async logsGrep(id, options) {
+        const safe = assertRef(id, 'container');
+        if (typeof options.pattern !== 'string' || options.pattern === '')
+            throw new Error('pattern 必填（要搜索的字面子串或正则表达式）');
+        if (options.pattern.length > 512)
+            throw new Error('pattern 过长（≤512 字符）');
+        const useRegexp = options.regexp === true;
+        const ignoreCase = options.ignoreCase === true;
+        /** 单行判定：命中返回匹配子串（用作 highlight），未命中返回 null。 */
+        let testLine;
+        if (useRegexp) {
+            let re;
+            try {
+                re = new RegExp(options.pattern, ignoreCase ? 'i' : '');
+            }
+            catch (error) {
+                throw new Error(`无效的正则表达式：${error instanceof Error ? error.message : String(error)}`);
+            }
+            testLine = (line) => {
+                const match = re.exec(line);
+                return match === null ? null : match[0];
+            };
+        }
+        else {
+            const needle = ignoreCase ? options.pattern.toLowerCase() : options.pattern;
+            testLine = (line) => {
+                const hay = ignoreCase ? line.toLowerCase() : line;
+                const at = hay.indexOf(needle);
+                return at === -1 ? null : line.slice(at, at + needle.length);
+            };
+        }
+        const contextLines = Math.min(Math.max(Math.trunc(options.context ?? 2), 0), 20);
+        const limit = Math.min(Math.max(Math.trunc(options.limit ?? 200), 1), 500);
+        // tail 缺省 = all（docker logs --tail all）；给了数字就夹到 1~5000——检索的默认语义是「全历史里找」
+        const tailOverride = typeof options.tail === 'number' && Number.isInteger(options.tail) && options.tail > 0
+            ? String(Math.min(options.tail, 5000))
+            : 'all';
+        const argv = this.logsArgv(safe, {
+            timestamps: options.timestamps !== false,
+            ...(typeof options.since === 'string' && options.since.trim() !== '' ? { since: options.since.trim() } : {}),
+            ...(typeof options.until === 'string' && options.until.trim() !== '' ? { until: options.until.trim() } : {}),
+        }, false, tailOverride);
+        // 扫描预算独立于返回预算：下限 8MB、上限 32MB（宿主内存有界），超时给到 60s 档
+        const scanBytes = Math.min(Math.max(this.limits.maxBytes, 8 * 1024 * 1024), 32 * 1024 * 1024);
+        const result = await this.runner.run(argv, {
+            timeoutMs: Math.max(this.limits.timeoutMs, 60_000),
+            maxBytes: scanBytes,
+            keepTail: true, // 溢出丢最旧（与 logs() 同方向，D14）；报告里如实说明窗口偏新
+            // 再对齐到行边界：保留尾部是按字节切的，不对齐的话窗口第一行是**半行**（没有时间戳、
+            // 内容从中途开始），会以噪音形式进模型上下文。理由与边界见 ExecOptions.lineAlign。
+            lineAlign: true,
+        });
+        this.assertOk(result, '检索容器日志');
+        // 拆行（stdout 在前、stderr 在后，与 logs() 的拼接序一致；只去掉块尾的空行）
+        const splitChunk = (text) => {
+            const lines = text.split('\n');
+            if (lines.length > 0 && lines[lines.length - 1] === '')
+                lines.pop();
+            return lines;
+        };
+        const rows = [
+            ...splitChunk(result.stdout).map((text) => ({ text, stream: 'out' })),
+            ...splitChunk(result.stderr).map((text) => ({ text, stream: 'err' })),
+        ];
+        // 全量扫命中（matched 如实计数，即使超过 limit）；limit 只决定「返回哪些窗」
+        const hitIndexes = [];
+        for (let i = 0; i < rows.length; i++) {
+            if (testLine(rows[i].text) !== null)
+                hitIndexes.push(i);
+        }
+        const limited = hitIndexes.length > limit;
+        const keptHits = hitIndexes.slice(0, limit);
+        // 上下文窗口合并去重（相邻命中共享的行只输出一份），按原序输出
+        const take = new Set();
+        const hitSet = new Set(keptHits);
+        for (const idx of keptHits) {
+            for (let j = Math.max(0, idx - contextLines); j <= Math.min(rows.length - 1, idx + contextLines); j++)
+                take.add(j);
+        }
+        const lines = [...take]
+            .sort((a, b) => a - b)
+            .map((j) => {
+            const row = rows[j];
+            return {
+                seq: j + 1,
+                stream: row.stream,
+                text: row.text,
+                hit: hitSet.has(j),
+                highlight: hitSet.has(j) ? testLine(row.text) : null,
+            };
+        });
+        return {
+            id: safe,
+            matched: hitIndexes.length,
+            scanned: rows.length,
+            returned: lines.length,
+            limited,
+            truncated: result.truncated,
+            contextLines,
+            lines,
+        };
+    }
     /**
      * 日志 argv 的唯一构造点：快照与流式只在 `--follow` 与 tail 下限上有差异，
      * 校验与夹紧必须逐字一致（否则同一 id 在两条路径上行为漂移）。
+     * `tailOverride` 供 logsGrep 传 `all`（检索要扫全部历史，而不是尾部 5000 行）。
      */
-    logsArgv(id, options, follow) {
+    logsArgv(id, options, follow, tailOverride) {
         // 流式允许 0（D133：重连只补新行）；快照路径保持 1 起步——「取 0 行快照」没有意义
         const min = follow ? 0 : 1;
-        const tail = Math.min(Math.max(Math.trunc(options?.tail ?? 200), min), 5000);
+        const tail = tailOverride ?? String(Math.min(Math.max(Math.trunc(options?.tail ?? 200), min), 5000));
         return [
             this.bin,
             'logs',
             ...(follow ? ['--follow'] : []),
             '--tail',
-            String(tail),
+            tail,
             ...(options?.timestamps === true ? ['--timestamps'] : []),
             ...(typeof options?.since === 'string' && options.since.trim() !== '' ? ['--since', options.since.trim()] : []),
+            ...(typeof options?.until === 'string' && options.until.trim() !== '' ? ['--until', options.until.trim()] : []),
             id,
         ];
     }