@trim21/personal-pi-extensions 0.1.555 → 0.1.557

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.555",
+  "version": "0.1.557",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/aft/guidelines.md

@@ -0,0 +1,3 @@
+### AFT 工具
+
+调查代码库时先用 AFT 工具（aft_outline / aft_zoom / aft_callgraph / aft_search）摸清结构、查看符号、追踪调用关系，再退回 grep 或整文件读取——它们成本更低，也是为此专门构建的。

package/src/aft/tools.ts

@@ -41,6 +41,14 @@ const SEARCH_PROMPT = readFileSync(
   fileURLToPath(new URL("search.md", import.meta.url)),
   "utf8",
 ).trim();
+/**
+ * 四个工具共用的使用准则，挂在结构入口 aft_outline 上注入一次：pi 的
+ * promptGuidelines 是 per-tool 的，而这条讲的是整个 AFT 工具集的分工。
+ */
+const AFT_GUIDELINES = readFileSync(
+  fileURLToPath(new URL("guidelines.md", import.meta.url)),
+  "utf8",
+).trim();
 
 export interface AftToolContext {
   cwd: string;
@@ -124,7 +132,7 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
       "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
     ].join("\n"),
     promptSnippet: "Output structural outline of a file/directory",
-    promptGuidelines: [OUTLINE_PROMPT],
+    promptGuidelines: [OUTLINE_PROMPT, AFT_GUIDELINES],
     parameters: OutlineParams,
     async execute(_id, params, signal, _onUpdate, extCtx) {
       const target = coerceTargetParam(params.target);

package/src/gh-readonly.ts

@@ -18,6 +18,7 @@
  *   - read-github-repo: Get repo info
  *   - list-github-releases: List releases
  *   - read-github-release: Get release details
+ *   - download-github-release-assets: Download a release's assets with gh credentials
  *   - wait-github-pr-checks: Watch PR CI checks
  *   - wait-github-commit-checks: Watch CI checks of a commit (no PR required)
  *   - watch-github-run: Watch a workflow run
@@ -29,14 +30,14 @@
  *   cp gh-readonly.ts .pi/extensions/
  *
  * Proxy (for the gh CLI and for the octokit-backed search/checks requests):
- *   ~/.pi/agent/gh.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }
+ *   ~/.pi/agent/proxy.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }
  *   HTTPS_PROXY / HTTP_PROXY / ALL_PROXY and NO_PROXY are used instead for the
  *   fields the config file leaves out. The config is read once per process.
  */
 
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 
@@ -44,7 +45,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
-import { createGhProxy } from "./lib/gh-proxy.js";
 import {
   type ActionJob,
   type CheckRun,
@@ -57,13 +57,14 @@ import {
   type RunJob,
 } from "./lib/github.js";
 import { type ToolPendant } from "./lib/pendant.js";
+import { createHttpProxy } from "./lib/proxy.js";
 import { createSeqState } from "./lib/seq-state.js";
 
 /**
- * 代理配置（~/.pi/agent/gh.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
+ * 代理配置（~/.pi/agent/proxy.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
  * `gh` 子进程与 octokit 请求都从这里取，配置只在首次使用时读一次。
  */
-const ghProxy = createGhProxy();
+const httpProxy = createHttpProxy();
 
 interface GhResult {
   stdout: string;
@@ -111,7 +112,7 @@ export function runGh(
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
       // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
-      env: { ...process.env, ...ghProxy.env, ...ctx.env, GH_PAGER: "cat" },
+      env: { ...process.env, ...httpProxy.env, ...ctx.env, GH_PAGER: "cat" },
     });
 
     let stdout = "";
@@ -302,6 +303,12 @@ const repoViewSchema = Type.Object({ nameWithOwner: Type.String() });
 
 const prHeadSchema = Type.Object({ headRefOid: Type.String() });
 
+/** `gh release view --json tagName,assets` 里本工具真正读取的字段。 */
+const releaseViewSchema = Type.Object({
+  tagName: Type.String(),
+  assets: Type.Array(Type.Object({ name: Type.String(), size: Type.Number() })),
+});
+
 function truncate(
   text: string,
   maxLines = 2000,
@@ -444,6 +451,19 @@ export function jobLogPath(repo: string, runId: string, jobId: number): string {
   return join(homedir(), ".cache", "pi", "github", "ci-logs", owner, name, runId, `${jobId}.log`);
 }
 
+/**
+ * Directory the release assets of one release are downloaded into:
+ * `~/.cache/pi/github/releases/<owner>/<repo>/<tag>/`.
+ *
+ * A tag is a git ref name and may contain `/`; only the characters that are safe
+ * in one path segment survive, so a tag can never escape its own directory.
+ */
+export function releaseAssetDir(repo: string, tag: string): string {
+  const { owner, repo: name } = splitRepo(repo);
+  const safeTag = tag.replaceAll(/[^A-Za-z0-9._+-]/g, "_").replace(/^\.+$/, "_");
+  return join(homedir(), ".cache", "pi", "github", "releases", owner, name, safeTag);
+}
+
 async function getJobLog(
   job: RunJob,
   signal: AbortSignal | undefined,
@@ -1163,6 +1183,13 @@ interface CommitChecksWaitParams {
   fail_fast?: boolean;
 }
 
+interface ReleaseDownloadParams {
+  repo?: string;
+  tag?: string;
+  pattern?: string;
+  archive?: "zip" | "tar.gz";
+}
+
 /** What a toolcall handler receives from the framework. */
 export interface ToolCall<Params> {
   params: Params;
@@ -1185,7 +1212,7 @@ export class GhClient {
   private readonly search: GithubSearch;
   private readonly checks: GithubChecksClient;
 
-  constructor(fetchImpl: typeof globalThis.fetch = ghProxy.fetch) {
+  constructor(fetchImpl: typeof globalThis.fetch = httpProxy.fetch) {
     this.fetch = fetchImpl;
     this.search = createGithubSearch({ fetch: fetchImpl });
     this.checks = createGithubChecks({ fetch: fetchImpl });
@@ -1434,6 +1461,155 @@ export class GhClient {
   }
 }
 
+// ── release asset download ───────────────────────────────────────────────────
+
+/** One regular file in a release's download directory. */
+interface ReleaseFile {
+  name: string;
+  path: string;
+  bytes: number;
+}
+
+/** Split the comma-separated `pattern` toolcall parameter into gh pattern values. */
+export function releasePatterns(pattern: string | undefined): string[] {
+  if (pattern === undefined) return [];
+  return pattern
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value !== "");
+}
+
+/**
+ * The `gh release download` argv. `--skip-existing` is always on: the download
+ * directory is a cache, and rewriting a file that is already there would pull
+ * the ground out from under anything reading it.
+ */
+export function releaseDownloadArgs(options: {
+  tag: string;
+  repo: string;
+  dir: string;
+  patterns: readonly string[];
+  archive?: "zip" | "tar.gz";
+}): string[] {
+  const { tag, repo, dir, patterns, archive } = options;
+  const args = ["release", "download", tag, ...repoArgs(repo)];
+  if (archive !== undefined) args.push("--archive", archive);
+  for (const pattern of patterns) args.push("--pattern", pattern);
+  args.push("--dir", dir, "--skip-existing");
+  return args;
+}
+
+/** Regular files directly inside `dir`, with their sizes, sorted by name. */
+async function listReleaseFiles(dir: string): Promise<ReleaseFile[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: ReleaseFile[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const path = join(dir, entry.name);
+    const info = await stat(path);
+    files.push({ name: entry.name, path, bytes: info.size });
+  }
+  return files.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * `gh release download` answers this exact message when a `--pattern` matched no
+ * asset. It is the only signal the CLI offers, so the enrichment below degrades
+ * to gh's own error (still thrown) if the wording ever changes.
+ */
+const GH_NO_ASSET_MATCH = "no assets match the file pattern";
+
+/**
+ * `download-github-release-assets`: fetch a release's assets (or source archive)
+ * into `releaseAssetDir` with the gh credentials, so private repositories work
+ * and the shell sandbox's network limits do not apply.
+ *
+ * The tag is resolved through `gh release view` before downloading: a tag that
+ * does not exist and a pattern that matched nothing are different answers, and
+ * the release's own asset names are what the model needs to fix the second one.
+ */
+export async function downloadReleaseAssets(
+  call: ToolCall<ReleaseDownloadParams>,
+): Promise<ToolResult> {
+  const { params, ctx, signal } = call;
+  const patterns = releasePatterns(params.pattern);
+  if (params.archive !== undefined && patterns.length > 0) {
+    throw new Error(
+      "pattern and archive are mutually exclusive (pick asset globs or the source archive)",
+    );
+  }
+
+  const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
+  const view = Value.Parse(
+    releaseViewSchema,
+    JSON.parse(
+      await ghExec(
+        [
+          "release",
+          "view",
+          ...(params.tag === undefined ? [] : [params.tag]),
+          ...repoArgs(effectiveRepo),
+          "--json",
+          "tagName,assets",
+        ],
+        { cwd: ctx.cwd, signal, input: params },
+      ),
+    ),
+  );
+
+  const assetNames = view.assets.map((asset) => asset.name);
+  const dir = releaseAssetDir(effectiveRepo, view.tagName);
+  await mkdir(dir, { recursive: true });
+  try {
+    await ghExec(
+      releaseDownloadArgs({
+        tag: view.tagName,
+        repo: effectiveRepo,
+        dir,
+        patterns,
+        ...(params.archive !== undefined && { archive: params.archive }),
+      }),
+      { cwd: ctx.cwd, signal, input: params },
+    );
+  } catch (error) {
+    // gh names the fault but not the choices; the release's asset list turns a
+    // dead end into the next toolcall.
+    if (error instanceof GhError && error.stderr.includes(GH_NO_ASSET_MATCH)) {
+      throw new Error(
+        `no asset of ${effectiveRepo}@${view.tagName} matched ${JSON.stringify(patterns)}; the release has: ${assetNames.join(", ") || "(no assets)"}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+
+  const files = await listReleaseFiles(dir);
+  const payload = { repo: effectiveRepo, tag: view.tagName, dir, files };
+  const pendant = subtitlePendant({ repo: effectiveRepo, tag: view.tagName }, "tag");
+
+  if (files.length === 0 && params.archive === undefined) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Nothing to download from ${effectiveRepo}@${view.tagName}: the release has no assets (try archive for the source tarball)`,
+        },
+      ],
+      details: {
+        ...payload,
+        available_assets: assetNames,
+        input: params,
+        ...(pendant && { pendant }),
+      },
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: { ...payload, input: params, ...(pendant && { pendant }) },
+  };
+}
+
 // ── tools ────────────────────────────────────────────────────────────────────
 
 export default function ghReadonlyTools(pi: ExtensionAPI) {
@@ -1853,6 +2029,40 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     },
   });
 
+  // ── download-github-release-assets ────────────────────────────────────────
+  pi.registerTool({
+    name: "download-github-release-assets",
+    label: "GitHub Release Download",
+    description:
+      "Download a GitHub release's assets (or its source archive) into " +
+      "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the gh CLI's credentials, " +
+      "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
+      "Files already in that directory are kept, never re-fetched. The result is the JSON " +
+      "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
+      "directory; file contents are not echoed. Read the entries you need from `path`.",
+    promptSnippet: "Download GitHub release assets",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      tag: Type.Optional(
+        Type.String({ description: "Release tag (defaults to the latest release)" }),
+      ),
+      pattern: Type.Optional(
+        Type.String({
+          description:
+            'Comma-separated glob patterns for asset names, e.g. "*.tar.gz,*.deb" (default: every asset)',
+        }),
+      ),
+      archive: Type.Optional(
+        Type.Union([Type.Literal("zip"), Type.Literal("tar.gz")], {
+          description: "Download the release's source archive instead of its assets",
+        }),
+      ),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return downloadReleaseAssets({ params, ctx, signal });
+    },
+  });
+
   // ── wait-github-pr-checks ─────────────────────────────────────────────────
   pi.registerTool({
     name: "wait-github-pr-checks",

package/src/lib/{gh-proxy.ts → proxy.ts}

@@ -1,16 +1,19 @@
 /**
- * gh-readonly 的代理配置与请求层。
+ * HTTP 代理层：gh-readonly 与 web_fetch 共用的出网配置。
  *
  * 配置来源（配置文件优先，未写的字段回退到环境变量）：
- *   - ~/.pi/agent/gh.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost,.corp" }
+ *   - ~/.pi/agent/proxy.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost,.corp" }
  *   - HTTPS_PROXY / HTTP_PROXY / ALL_PROXY（小写变体同样接受）、NO_PROXY
  *
- * 两条出口共用同一份配置，且在扩展加载时一次性读完：
+ * 这份配置是全局出网代理，不专属 GitHub：gh 子进程、octokit 请求、web_fetch 都走它。
+ *
+ * 三条出口共用同一份配置，且在扩展加载时一次性读完：
  *   - gh CLI 子进程：env 给出要注入子进程的 HTTP(S)_PROXY / NO_PROXY 等变量
- *   - octokit 请求：fetch 是挂了代理 dispatcher 的 fetch；未配置代理时就是全局 fetch
+ *   - octokit 请求：fetch 是挂了代理 dispatcher 的 fetch（octokit 只认自定义 fetch）
+ *   - web_fetch：同样用 fetch（Node 的全局 fetch 不认 HTTPS_PROXY 环境变量）
  *
- * 配置有错（JSON 语法错、字段类型不符、proxy 不是 http(s) URL）直接抛错——扩展
- * 加载即失败，而不是带着一份被忽略的配置静默直连。
+ * 未配置代理时 fetch 就是全局 fetch。配置有错（JSON 语法错、字段类型不符、proxy 不是
+ * http(s) URL）直接抛错——扩展加载即失败，而不是带着一份被忽略的配置静默直连。
  */
 
 import { readFileSync } from "node:fs";
@@ -22,25 +25,25 @@ import { EnvHttpProxyAgent } from "undici";
 
 import { parseWithSchema } from "./parse-with-schema.js";
 
-const ghConfigSchema = Type.Object({
+const proxyConfigSchema = Type.Object({
   proxy: Type.Optional(Type.String()),
   noProxy: Type.Optional(Type.String()),
 });
 
-export interface GhProxySettings {
+export interface HttpProxySettings {
   /** 代理 URL（http/https）；undefined 表示不使用代理。 */
   proxy?: string;
   /** 不走代理的 host 列表（逗号分隔），语义同 NO_PROXY。 */
   noProxy?: string;
 }
 
-export function ghProxyConfigPath(): string {
-  return join(homedir(), ".pi", "agent", "gh.json");
+export function proxyConfigPath(): string {
+  return join(homedir(), ".pi", "agent", "proxy.json");
 }
 
-/** 解析 gh.json 的内容；字段类型不符时抛出带字段路径的错误。 */
-export function parseGhProxyConfig(value: unknown): GhProxySettings {
-  const parsed = parseWithSchema(ghConfigSchema, value);
+/** 解析 proxy.json 的内容；字段类型不符时抛出带字段路径的错误。 */
+export function parseProxyConfig(value: unknown): HttpProxySettings {
+  const parsed = parseWithSchema(proxyConfigSchema, value);
   const proxy = parsed.proxy?.trim();
   const noProxy = parsed.noProxy?.trim();
   return { ...(proxy && { proxy }), ...(noProxy && { noProxy }) };
@@ -84,10 +87,10 @@ function normalizeProxy(value: string): string {
  * 这里是仓库里允许的同步例外）。文件不存在 = 未配置；文件读不了、JSON 非法或
  * 字段不符都直接抛。
  */
-export function readGhProxySettings(
-  configPath: string = ghProxyConfigPath(),
+export function readProxySettings(
+  configPath: string = proxyConfigPath(),
   env: NodeJS.ProcessEnv = process.env,
-): GhProxySettings {
+): HttpProxySettings {
   let raw: string | undefined;
   try {
     raw = readFileSync(configPath, "utf8");
@@ -99,10 +102,10 @@ export function readGhProxySettings(
     }
   }
 
-  let file: GhProxySettings = {};
+  let file: HttpProxySettings = {};
   if (raw !== undefined) {
     try {
-      file = parseGhProxyConfig(JSON.parse(raw));
+      file = parseProxyConfig(JSON.parse(raw));
     } catch (error) {
       throw new Error(`${configPath}: ${error instanceof Error ? error.message : String(error)}`, {
         cause: error,
@@ -119,7 +122,7 @@ export function readGhProxySettings(
 }
 
 /** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象（子进程继承父进程环境）。 */
-export function proxyEnvVars(settings: GhProxySettings): NodeJS.ProcessEnv {
+export function proxyEnvVars(settings: HttpProxySettings): NodeJS.ProcessEnv {
   const { proxy, noProxy } = settings;
   if (!proxy) return {};
   return {
@@ -154,9 +157,9 @@ function createProxyDispatcher(
   }) as unknown as NonNullable<RequestInit["dispatcher"]>;
 }
 
-export interface GhProxy {
+export interface HttpProxy {
   /** 生效的代理设置（配置文件与环境变量合并后的结果）。 */
-  readonly settings: GhProxySettings;
+  readonly settings: HttpProxySettings;
   /** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象。 */
   readonly env: NodeJS.ProcessEnv;
   /** 走代理的 fetch；未配置代理时就是全局 fetch。 */
@@ -168,11 +171,11 @@ export interface GhProxy {
  * `globalThis.fetch` 本身：每次调用都取当前的全局 fetch，否则首个请求之后替换
  * `globalThis.fetch`（插桩、测试替身）就不再生效。
  */
-export function createGhProxy(
-  configPath: string = ghProxyConfigPath(),
+export function createHttpProxy(
+  configPath: string = proxyConfigPath(),
   env: NodeJS.ProcessEnv = process.env,
-): GhProxy {
-  const settings = readGhProxySettings(configPath, env);
+): HttpProxy {
+  const settings = readProxySettings(configPath, env);
   const { proxy, noProxy } = settings;
   let dispatcher: NonNullable<RequestInit["dispatcher"]> | undefined;
 

package/src/system-prompt/prompt.md

@@ -17,7 +17,6 @@ In addition to the tools above, you may have access to other custom tools depend
 
 ## Doing tasks
 
-- When investigating a codebase, first use the AFT tools (aft_outline / aft_zoom / aft_callgraph / aft_search) to map the structure, inspect named symbols, and trace call relationships before falling back to grep or full-file reads — they are cheaper and purpose-built for this.
 - The user will primarily request you to perform software engineering tasks. These may include solving bugs, adding new functionality, refactoring code, explaining code, and more. When given an unclear or generic instruction, consider it in the context of these software engineering tasks and the current working directory. For example, if the user asks you to change "methodName" to snake case, do not reply with just "method_name", instead find the method in the code and modify the code.
 - You are highly capable and often allow users to complete ambitious tasks that would otherwise be too complex or take too long. You should defer to user judgement about whether a task is too large to attempt.
 - For exploratory questions ("what could we do about X?", "how should we approach this?", "what do you think?"), respond in 2-3 sentences with a recommendation and the main tradeoff. Present it as something the user can redirect, not a decided plan. Don't implement until the user agrees.

package/src/web/fetch.ts

@@ -1,13 +1,19 @@
 /**
- * `web_fetch` 工具：抓取 URL 并提取正文为 markdown。
+ * `web_fetch` 工具：抓取 URL 并提取正文为 markdown，或按 `output_path` 原样落盘。
  *
  * SSRF 防护：DNS 预解析 + 拒绝私有/保留地址 + 每跳重定向重新校验，
  * 防止把 agent 变成内网探测口。正文提取用 readability 主内容算法。
  *
+ * 出网走 `src/lib/proxy.ts` 的代理层（~/.pi/agent/proxy.json，回退 HTTPS_PROXY 等环境
+ * 变量）：Node 的全局 fetch 不认代理环境变量，GitHub 的用户附件、release 资产这类只在
+ * 代理可达的 host 上，必须从这里挂出去，否则沙箱内一律 fetch failed。
+ *
  * 本文件是独立扩展入口（见 package.json 的 pi.extensions），可在配置里单独禁用。
  */
 import { lookup } from "node:dns/promises";
+import { mkdir, open, rm } from "node:fs/promises";
 import { isIP } from "node:net";
+import { dirname } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Readability } from "@mozilla/readability";
@@ -15,9 +21,17 @@ import { parseHTML } from "linkedom";
 import TurndownService from "turndown";
 import { Type } from "typebox";
 
+import { resolvePathArg } from "../lib/path.js";
+import { createHttpProxy } from "../lib/proxy.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+
+const httpProxy = createHttpProxy();
+
 const MAX_REDIRECTS = 5;
 const TIMEOUT_MS = 30_000;
 const MAX_BYTES = 5 * 1024 * 1024;
+/** 落盘模式的上限：附件、镜像、release 资产都比网页大得多，文本模式仍用 MAX_BYTES。 */
+const MAX_FILE_BYTES = 200 * 1024 * 1024;
 const MIN_USEFUL_CONTENT = 200;
 const MAX_MARKDOWN_BYTES = 100 * 1024;
 
@@ -84,12 +98,20 @@ interface FetchedPage {
   markdown: string;
 }
 
-/** 手动跟随重定向，每跳重新做 SSRF 校验（防 DNS rebinding 简化处理） */
+/** 落盘结果：最终 URL、本地路径、响应的 content-type 与写出的字节数。 */
+interface SavedFile {
+  url: string;
+  filePath: string;
+  contentType: string;
+  bytes: number;
+}
+
+/** 手动跟随重定向，每跳重新做 SSRF 校验（防 DNS rebinding 简化处理）。 */
 async function fetchWithRedirects(
   url: URL,
   signal: AbortSignal | undefined,
-  fetchFn: typeof fetch = fetch,
-): Promise<Response> {
+  fetchFn: typeof fetch = httpProxy.fetch,
+): Promise<{ response: Response; url: URL }> {
   let current = url;
   for (let redirects = 0; ; redirects++) {
     await assertPublicHostname(current.hostname);
@@ -109,11 +131,19 @@ async function fetchWithRedirects(
       }
       continue;
     }
-    return response;
+    return { response, url: current };
   }
 }
 
-export async function fetchPage(url: string, signal?: AbortSignal): Promise<FetchedPage> {
+/** 已确认 2xx 的响应，连同手动重定向后跟踪到的最终地址。 */
+interface OpenedResponse {
+  response: Response;
+  /** 手动重定向下 `response.url` 可能是空的，最终地址由重定向循环给出。 */
+  url: string;
+}
+
+/** 校验 URL、逐跳跟随重定向、要求 2xx；响应体怎么处理由调用方决定。 */
+async function openResponse(url: string, signal?: AbortSignal): Promise<OpenedResponse> {
   let target: URL;
   try {
     target = new URL(url);
@@ -124,10 +154,15 @@ export async function fetchPage(url: string, signal?: AbortSignal): Promise<Fetc
     throw new Error(`只支持 http/https，收到: ${target.protocol}`);
   }
 
-  const response = await fetchWithRedirects(target, signal);
+  const { response, url: finalUrl } = await fetchWithRedirects(target, signal);
   if (!response.ok) {
     throw new Error(`HTTP ${response.status} ${response.statusText}`);
   }
+  return { response, url: finalUrl.href };
+}
+
+export async function fetchPage(url: string, signal?: AbortSignal): Promise<FetchedPage> {
+  const { response, url: finalUrl } = await openResponse(url, signal);
   const contentType = response.headers.get("content-type") ?? "";
   const category = classifyContentType(contentType);
   if (category === null) {
@@ -155,10 +190,58 @@ export async function fetchPage(url: string, signal?: AbortSignal): Promise<Fetc
   }
 
   if (category === "html") {
-    return extractMarkdown(body, response.url);
+    return extractMarkdown(body, finalUrl);
   }
   // JSON / XML / text/*：原样返回
-  return { url: response.url, title: response.url, markdown: body.trim() };
+  return { url: finalUrl, title: finalUrl, markdown: body.trim() };
+}
+
+/**
+ * 把响应体原样写进 `filePath`（二进制安全：不做 content-type 白名单、不解码、不转换），
+ * 用于 GitHub 用户附件、release 资产这类不能当正文读的下载。
+ * 任何一步失败都会删掉半成品，不留下看着完整其实截断的文件。
+ */
+export async function saveUrlToFile(
+  url: string,
+  filePath: string,
+  signal?: AbortSignal,
+): Promise<SavedFile> {
+  const { response, url: finalUrl } = await openResponse(url, signal);
+
+  const declaredLength = Number(response.headers.get("content-length") ?? "0");
+  if (declaredLength > MAX_FILE_BYTES) {
+    throw new Error(`文件过大 (${declaredLength} bytes)，上限 ${MAX_FILE_BYTES}`);
+  }
+
+  await mkdir(dirname(filePath), { recursive: true });
+  const handle = await open(filePath, "w");
+  let bytes = 0;
+  try {
+    if (response.body) {
+      const reader = response.body.getReader();
+      for (;;) {
+        const chunk = (await reader.read()) as { done: boolean; value: Uint8Array };
+        if (chunk.done) break;
+        bytes += chunk.value.byteLength;
+        if (bytes > MAX_FILE_BYTES) {
+          throw new Error(`文件过大，上限 ${MAX_FILE_BYTES} bytes`);
+        }
+        await handle.write(chunk.value);
+      }
+    }
+  } catch (error) {
+    await handle.close();
+    await rm(filePath, { force: true });
+    throw error;
+  }
+  await handle.close();
+
+  return {
+    url: finalUrl,
+    filePath,
+    contentType: response.headers.get("content-type") ?? "",
+    bytes,
+  };
 }
 
 /** 按 mime 主体分类响应；html 走 readability，其余文本类原样返回 */
@@ -232,14 +315,48 @@ export default function webFetchTool(pi: ExtensionAPI): void {
     label: "Web Fetch",
     description:
       "Fetch a URL and return its content as markdown (HTML pages) or raw text " +
-      "(JSON/XML/plain-text API responses). SSRF-protected: refuses private/internal " +
-      "addresses.",
-    promptSnippet: "Fetch a web page or API response",
+      "(JSON/XML/plain-text API responses). With output_path the body is saved to that " +
+      "file verbatim instead — any content type, no extraction, no truncation — and the " +
+      "result is the JSON summary {url, file_path, content_type, bytes} rather than the " +
+      "content; use it for images, logs and other attachments (GitHub user-attachments " +
+      "links from issue bodies, release assets, raw files). Give the file the extension " +
+      "matching the response's content_type: the Read tool decides image support by " +
+      "extension. Requests honour the proxy in ~/.pi/agent/proxy.json, so they reach hosts " +
+      "the shell sandbox blocks. SSRF-protected: refuses private/internal addresses.",
+    promptSnippet: "Fetch a web page, API response, or download a file",
     parameters: Type.Object({
       url: Type.String({ description: "The URL to fetch" }),
+      output_path: Type.Optional(
+        Type.String({
+          description:
+            "Save the response body to this path verbatim instead of returning it (absolute, or relative to the session cwd; ~ is expanded). Parent directories are created and an existing file is overwritten.",
+        }),
+      ),
     }),
-    async execute(_id, params, signal) {
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const destination =
+        params.output_path === undefined ? undefined : resolvePathArg(ctx.cwd, params.output_path);
+      // 落盘位置的审批与写文件工具同一套：工作区与 /tmp 自动放行，其余问用户。
+      // 放在 try 外面，拒绝的原因（user deny）不该被改写成「抓取失败」。
+      if (destination !== undefined) {
+        await guardWriteAccess(ctx, { toolName: "web_fetch", absolutePath: destination });
+      }
+
       try {
+        if (destination !== undefined) {
+          const file = await saveUrlToFile(params.url, destination, signal);
+          const payload = {
+            url: file.url,
+            file_path: file.filePath,
+            content_type: file.contentType,
+            bytes: file.bytes,
+          };
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+
         const page = await fetchPage(params.url, signal);
         const { text, truncated } = truncateMarkdown(page.markdown);
         const details: Record<string, unknown> = {