@trim21/personal-pi-extensions 0.1.495 → 0.1.497

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.495",
+  "version": "0.1.497",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -105,6 +105,7 @@
     "linkedom": "^0.18.0",
     "lodash-es": "^4.18.1",
     "minimatch": "^10.2.6",
+    "octokit": "^5.0.5",
     "turndown": "^7.2.0",
     "vscode-jsonrpc": "^9.0.1",
     "vscode-languageserver-types": "^3.18.0",

package/src/gh-readonly.ts

@@ -38,6 +38,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { createGithubSearch, type GithubSearch, renderHits } from "./lib/github.js";
 import { type ToolPendant } from "./lib/pendant.js";
 import { createSeqState } from "./lib/seq-state.js";
 
@@ -333,52 +334,30 @@ interface ListFilters {
   assignee?: string;
   milestone?: string;
   limit?: number;
+  /** Comma-separated field names for the keyword-search result rows. */
+  fields?: string;
 }
 
 /**
- * Build the `gh` argv for listing or keyword-searching issues/PRs.
+ * Build the `gh` argv for browsing issues/PRs (no keyword search).
  *
- * Keyword searches route through `gh search issues` / `gh search prs`, which rank
- * results by relevance and are the only path that can include closed items.
- * `gh issue list --search` would silently stay on the list's state filter (open
- * by default), so keyword lookups must not use it. Browse calls (no keywords)
- * keep `gh issue list` / `gh pr list` semantics.
- *
- * The state value sets differ between the two command families: `gh issue list`
- * accepts `--state all` and `gh pr list` `--state merged`, while `gh search`
- * only knows `--state open|closed` plus `--merged` for PRs. The shared `state`
- * param is translated here: search defaults to open, `all` means open+closed
- * (no state filter), and `merged` maps to `--merged` for PRs.
+ * Keyword searches no longer go through the `gh` CLI — the octokit-based client
+ * in `./lib/github.ts` handles them with state values (`all`, and `merged` for
+ * PRs) that `gh search` cannot express. Browse calls keep `gh issue list` /
+ * `gh pr list` semantics: `state` is passed through verbatim, since `gh issue
+ * list` accepts open/closed/all and `gh pr list` additionally accepts merged.
  */
 export function listGithubArgs(kind: "issue" | "pr", params: ListFilters): string[] {
-  const { repo, keywords, state, label, author, assignee, milestone, limit } = params;
-
-  const addFilters = (args: string[]) => {
-    if (label) args.push("--label", label);
-    if (author) args.push("--author", author);
-    if (assignee) args.push("--assignee", assignee);
-    if (milestone) args.push("--milestone", milestone);
-    if (limit) args.push("--limit", String(limit));
-    return args;
-  };
-
-  if (keywords) {
-    const args = ["search", kind === "issue" ? "issues" : "prs", ...repoArgs(repo), keywords];
-    if (kind === "pr" && state === "merged") {
-      args.push("--merged");
-    } else if (state && state !== "all") {
-      args.push("--state", state);
-    } else if (!state) {
-      // keep the browse tools' default rather than gh search's implicit
-      // open+closed; pass state="all" to cover closed items
-      args.push("--state", "open");
-    }
-    return addFilters(args);
-  }
+  const { repo, state, label, author, assignee, milestone, limit } = params;
 
   const args = [kind, "list", ...repoArgs(repo)];
   if (state) args.push("--state", state);
-  return addFilters(args);
+  if (label) args.push("--label", label);
+  if (author) args.push("--author", author);
+  if (assignee) args.push("--assignee", assignee);
+  if (milestone) args.push("--milestone", milestone);
+  if (limit) args.push("--limit", String(limit));
+  return args;
 }
 
 async function listGithub(
@@ -389,6 +368,19 @@ async function listGithub(
   return ghExec(listGithubArgs(kind, params), ctx);
 }
 
+/** Run a keyword search through the octokit client and render the rows. */
+async function searchList(
+  kind: "issue" | "pr",
+  params: ListFilters,
+  githubSearch: GithubSearch,
+): Promise<string> {
+  const hits = await githubSearch.search(kind, params);
+  if (hits.length === 0) {
+    return `(no matching ${kind === "issue" ? "issues" : "pull requests"})`;
+  }
+  return renderHits(hits, { repo: params.repo, fields: params.fields });
+}
+
 // ── CI helpers ───────────────────────────────────────────────────────────────
 
 export interface StepInfo {
@@ -1144,6 +1136,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     return;
   }
 
+  const githubSearch = createGithubSearch();
+
   // ── read-github-issue ──────────────────────────────────────────────────────
   pi.registerTool({
     name: "read-github-issue",
@@ -1180,25 +1174,36 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "list-github-issues",
     label: "GitHub Issues List",
     description:
-      'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword results default to open issues — pass state="all" to include closed ones.',
+      'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones. Set fields to choose the columns of each result row.',
     promptSnippet: "List or search GitHub issues",
     parameters: Type.Object({
       repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
       keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
       state: Type.Optional(
         Type.String({
-          description: "open, closed, all (default: open; with keywords, all covers closed too)",
+          description:
+            "open, closed, all (default: open; all applies to keyword search and covers closed too)",
         }),
       ),
       label: Type.Optional(Type.String({ description: "Filter by label" })),
       author: Type.Optional(Type.String({ description: "Filter by author" })),
-      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
       milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 30)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt",
+        }),
+      ),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const result = toToolResult(
-        await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
+        params.keywords
+          ? await searchList("issue", params, githubSearch)
+          : await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
         params,
       );
       result.details.pendant = subtitlePendant(params);
@@ -1242,7 +1247,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "list-github-prs",
     label: "GitHub PRs List",
     description:
-      'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword results default to open PRs — pass state="all" (open + closed) or state="merged" to broaden.',
+      'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden. Set fields to choose the columns of each result row.',
     promptSnippet: "List or search GitHub PRs",
     parameters: Type.Object({
       repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
@@ -1250,18 +1255,28 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       state: Type.Optional(
         Type.String({
           description:
-            "open, closed, merged, all (default: open; with keywords, merged and all broaden the search)",
+            "open, closed, merged, all (default: open; all applies to keyword search and covers open + closed + merged)",
         }),
       ),
       label: Type.Optional(Type.String({ description: "Filter by label" })),
       author: Type.Optional(Type.String({ description: "Filter by author" })),
-      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
       milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 30)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt,mergedAt",
+        }),
+      ),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const result = toToolResult(
-        await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
+        params.keywords
+          ? await searchList("pr", params, githubSearch)
+          : await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
         params,
       );
       result.details.pendant = subtitlePendant(params);

package/src/lib/github.ts

@@ -0,0 +1,294 @@
+/**
+ * GitHub search client built on octokit, authenticated with the token from the
+ * system `gh` CLI (`gh auth token`). Used by the gh-readonly search tools.
+ *
+ * Unlike the `gh search` CLI, the search API has no `--state all` and treats a
+ * merged PR's state as `closed` — so merged/closed disambiguation is expressed
+ * through qualifiers here (`is:merged`, `state:closed -is:merged`) and the
+ * rendered state is derived from `pull_request.merged_at`.
+ */
+
+import { spawn } from "node:child_process";
+
+import { Octokit } from "octokit";
+
+export type SearchKind = "issue" | "pr";
+
+export interface SearchParams {
+  repo?: string;
+  keywords?: string;
+  state?: string;
+  label?: string;
+  author?: string;
+  assignee?: string;
+  milestone?: string;
+  limit?: number;
+}
+
+/** REST /search/issues response shape we consume (item is an issue/pr union). */
+interface RawSearchItem {
+  number: number;
+  state: string;
+  title: string;
+  html_url: string;
+  /** The search API exposes the repo as a URL, not as an object. */
+  repository_url: string;
+  user: { login: string } | null;
+  labels: { name: string }[];
+  milestone: { title: string } | null;
+  assignees: { login: string }[];
+  comments: number;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  pull_request: { merged_at: string | null } | null;
+}
+
+export interface SearchHit {
+  number: number;
+  /** `open`, `closed` or `merged` (merged is inferred from pull_request.merged_at). */
+  state: "open" | "closed" | "merged";
+  title: string;
+  url: string;
+  repo: string;
+  author: string;
+  labels: string[];
+  milestone: string;
+  assignees: string[];
+  comments: number;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string;
+  mergedAt: string;
+}
+
+/**
+ * Build the `q` parameter for the issues-and-pull-requests search endpoint.
+ *
+ * State semantics (the whole reason this client exists):
+ * - default is `open`, matching the browse tools
+ * - `all` applies no state filter (open + closed)
+ * - for PRs, `merged` maps to `is:merged` and `closed` excludes merged PRs,
+ *   because the search API reports a merged PR's state as `closed`
+ */
+export function buildSearchQuery(kind: SearchKind, params: SearchParams): string {
+  const { repo, keywords, label, author, assignee, milestone } = params;
+  const state = params.state ?? "open";
+
+  const parts: string[] = [];
+  if (repo) parts.push(`repo:${repo}`);
+  parts.push(kind === "issue" ? "is:issue" : "is:pr");
+  switch (state) {
+    case "open": {
+      parts.push("state:open");
+
+      break;
+    }
+    case "closed": {
+      parts.push(kind === "pr" ? "state:closed -is:merged" : "state:closed");
+
+      break;
+    }
+    case "merged": {
+      if (kind === "issue") throw new Error("state=merged is only valid for PR searches");
+      parts.push("is:merged");
+
+      break;
+    }
+    default: {
+      if (state !== "all") {
+        throw new Error(
+          `invalid state: ${state} (expected open, closed, ${kind === "pr" ? "merged, " : ""}all)`,
+        );
+      }
+    }
+  }
+  if (keywords) parts.push(keywords);
+  if (label) parts.push(`label:${quoteQualifier(label)}`);
+  if (author) parts.push(`author:${author}`);
+  if (assignee) parts.push(`assignee:${assignee}`);
+  if (milestone) parts.push(`milestone:${quoteQualifier(milestone)}`);
+  return parts.join(" ");
+}
+
+/** Quote a qualifier value that contains whitespace or special characters. */
+function quoteQualifier(value: string): string {
+  if (/^[\w@./-]+$/.test(value)) return value;
+  return `"${value.replaceAll('"', String.raw`\"`)}"`;
+}
+
+const FIELD_EXTRACTORS: Record<string, (hit: SearchHit) => string> = {
+  number: (h) => String(h.number),
+  state: (h) => h.state,
+  title: (h) => h.title,
+  url: (h) => h.url,
+  repo: (h) => h.repo,
+  author: (h) => h.author,
+  labels: (h) => h.labels.join(","),
+  milestone: (h) => h.milestone,
+  assignees: (h) => h.assignees.join(","),
+  comments: (h) => String(h.comments),
+  createdAt: (h) => h.createdAt,
+  updatedAt: (h) => h.updatedAt,
+  closedAt: (h) => h.closedAt,
+  mergedAt: (h) => h.mergedAt,
+};
+
+export const SEARCH_FIELDS: readonly string[] = Object.keys(FIELD_EXTRACTORS);
+
+/** Render search hits as tab-separated rows; one row per hit, one column per field. */
+export function renderHits(hits: SearchHit[], options: { repo?: string; fields?: string }): string {
+  const requested = options.fields
+    ? options.fields
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean)
+    : options.repo
+      ? ["number", "state", "title", "labels", "updatedAt"]
+      : ["repo", "number", "state", "title", "labels", "updatedAt"];
+  const unknown = requested.filter((f) => !(f in FIELD_EXTRACTORS));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown field${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (valid: ${SEARCH_FIELDS.join(", ")})`,
+    );
+  }
+  return hits.map((hit) => requested.map((f) => FIELD_EXTRACTORS[f](hit)).join("\t")).join("\n");
+}
+
+function toDate(iso: string | null | undefined): string {
+  return iso ? iso.slice(0, 10) : "";
+}
+
+const REPO_URL_RE = /\/repos\/([^/]+\/[^/]+)$/;
+
+/** repository_url looks like https://api.github.com/repos/OWNER/REPO */
+function repoName(raw: RawSearchItem): string {
+  const match = REPO_URL_RE.exec(raw.repository_url);
+  return match?.[1] ?? "";
+}
+
+function normalize(raw: RawSearchItem): SearchHit {
+  const mergedAt = raw.pull_request?.merged_at ?? "";
+  return {
+    number: raw.number,
+    state: mergedAt ? "merged" : (raw.state as "open" | "closed"),
+    title: raw.title,
+    url: raw.html_url,
+    repo: repoName(raw),
+    author: raw.user?.login ?? "",
+    labels: raw.labels.map((l) => l.name),
+    milestone: raw.milestone?.title ?? "",
+    assignees: raw.assignees.map((a) => a.login),
+    comments: raw.comments,
+    createdAt: toDate(raw.created_at),
+    updatedAt: toDate(raw.updated_at),
+    closedAt: toDate(raw.closed_at),
+    mergedAt: toDate(mergedAt),
+  };
+}
+
+function ghAuthToken(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("gh", ["auth", "token"], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => proc.kill("SIGTERM"), 10_000);
+    proc.stdout.on("data", (d: Buffer) => {
+      stdout += String(d);
+    });
+    proc.stderr.on("data", (d: Buffer) => {
+      stderr += String(d);
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      reject(new Error(`failed to start gh: ${err.message}`));
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      const token = stdout.trim();
+      if (code === 0 && token) {
+        resolve(token);
+      } else {
+        reject(
+          new Error(
+            stderr.trim() || `gh auth token exited with code ${code} — run "gh auth login" first`,
+          ),
+        );
+      }
+    });
+  });
+}
+
+/**
+ * Error thrown when the GitHub search API rejects the request. Carries the
+ * original toolcall params so the model can see the exact input.
+ */
+export class GithubSearchError extends Error {
+  readonly params: SearchParams;
+  readonly status: number | undefined;
+
+  constructor(message: string, params: SearchParams, status?: number) {
+    super(`${message} (input: ${JSON.stringify(params)})`);
+    this.name = "GithubSearchError";
+    this.params = params;
+    this.status = status;
+  }
+}
+
+function describeHttpError(status: number | undefined): string {
+  if (status === 401)
+    return 'GitHub auth failed (401): token invalid or expired — run "gh auth login"';
+  if (status === 403) return "GitHub rate limit or permissions error (403)";
+  if (status === 404) return "repository not found, or the token has no access to it (404)";
+  return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
+}
+
+export interface GithubSearch {
+  search(kind: SearchKind, params: SearchParams): Promise<SearchHit[]>;
+}
+
+/**
+ * Create a search client. The octokit instance (and its auth token) is cached
+ * in the returned closure, so repeated searches reuse the same client without
+ * module-level state.
+ */
+export function createGithubSearch(): GithubSearch {
+  let client: Octokit | undefined;
+
+  async function getClient(): Promise<Octokit> {
+    client ??= new Octokit({ auth: await ghAuthToken() });
+    return client;
+  }
+
+  return {
+    async search(kind, params) {
+      const limit = Math.min(Math.max(params.limit ?? 30, 1), 100);
+      const effective = { ...params, limit };
+
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          const octokit = await getClient();
+          if (effective.assignee === "@me") {
+            const { data } = await octokit.rest.users.getAuthenticated();
+            effective.assignee = data.login;
+          }
+          const q = buildSearchQuery(kind, effective);
+          const { data } = await octokit.rest.search.issuesAndPullRequests({
+            q,
+            per_page: limit,
+          });
+          return data.items.map((item) => normalize(item as unknown as RawSearchItem));
+        } catch (error) {
+          const status = (error as { status?: number }).status;
+          // A stale cached token can produce 401s; drop the cache and retry once.
+          if (status === 401 && attempt === 0 && client) {
+            client = undefined;
+            continue;
+          }
+          const message = (error as { message?: string }).message ?? String(error);
+          throw new GithubSearchError(`${describeHttpError(status)}: ${message}`, params, status);
+        }
+      }
+    },
+  };
+}

package/src/lib/lsp/client.ts

@@ -266,6 +266,19 @@ interface ServerCapabilities {
   [key: string]: unknown;
 }
 
+/**
+ * create 的直连缺省（单一来源）：lsp.ts 的 resolveConfig 解析超时/LRU 时引用
+ * 同一组数值，保证配置层缺省与直连调用方取值一致。
+ */
+export const clientDefaults = {
+  diagnosticsDebounceMs: 150,
+  diagnosticsDocumentWaitTimeoutMs: 5_000,
+  diagnosticsFullWaitTimeoutMs: 10_000,
+  diagnosticsRequestTimeoutMs: 3_000,
+  initializeTimeoutMs: 45_000,
+  maxOpenDocuments: 32,
+} as const;
+
 export interface CreateInput {
   serverID: string;
   server: LspServerHandle;
@@ -416,12 +429,15 @@ function stopProcess(process: LspServerHandle["process"]): Promise<void> {
 }
 
 export async function create(input: CreateInput): Promise<LspClient> {
-  const diagnosticsDebounceMs = input.diagnosticsDebounceMs ?? 150;
-  const diagnosticsDocumentWaitTimeoutMs = input.diagnosticsDocumentWaitTimeoutMs ?? 5_000;
-  const diagnosticsFullWaitTimeoutMs = input.diagnosticsFullWaitTimeoutMs ?? 10_000;
-  const diagnosticsRequestTimeoutMs = input.diagnosticsRequestTimeoutMs ?? 3_000;
-  const initializeTimeoutMs = input.initializeTimeoutMs ?? 45_000;
-  const maxOpenDocuments = input.maxOpenDocuments ?? 32;
+  const diagnosticsDebounceMs = input.diagnosticsDebounceMs ?? clientDefaults.diagnosticsDebounceMs;
+  const diagnosticsDocumentWaitTimeoutMs =
+    input.diagnosticsDocumentWaitTimeoutMs ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs;
+  const diagnosticsFullWaitTimeoutMs =
+    input.diagnosticsFullWaitTimeoutMs ?? clientDefaults.diagnosticsFullWaitTimeoutMs;
+  const diagnosticsRequestTimeoutMs =
+    input.diagnosticsRequestTimeoutMs ?? clientDefaults.diagnosticsRequestTimeoutMs;
+  const initializeTimeoutMs = input.initializeTimeoutMs ?? clientDefaults.initializeTimeoutMs;
+  const maxOpenDocuments = input.maxOpenDocuments ?? clientDefaults.maxOpenDocuments;
 
   const connection = createMessageConnection(
     new StreamMessageReader(input.server.process.stdout),

package/src/lib/lsp/lsp.ts

@@ -5,7 +5,9 @@
  *   闭包变量，不做成模块级全局；
  * - 配置来源：全局 `~/.pi/agent/lsp.json` + 本地 `<cwd>/.pi/lsp.json`
  *   （本地覆盖全局）：`servers` 按 id 合并（同名 id 整体覆盖、新增 id，全局
- *   其余服务器保留），`enabled`/`disabled` 白名单与各超时参数继续生效；
+ *   其余服务器保留），`watch` 按字段合并（本地逐字段覆盖、`ignore` 取并集）；
+ *   合并结果解析为 `ResolvedLspConfig`（缺省值应用、超时换算为 ms、白名单转
+ *   Set），消费方不接触"未配置"歧义；
  *   没有内置默认服务器，所有服务器均须在配置里定义；
  *   配置在每个工具的调用 cwd 下惰性读取；enabled 引用不存在的服务器 id
  *   是配置错误：全局配置在扩展加载（createLspService）时抛错，本地配置在
@@ -29,8 +31,8 @@ import type { Hover, WorkspaceEdit } from "vscode-languageserver-types";
 
 import { type LspServerAdapter } from "./adapter.js";
 import {
+  clientDefaults,
   create,
-  type CreateInput,
   type Diagnostic,
   type Info as LspClient,
   type InspectLocation,
@@ -41,27 +43,32 @@ import {
   WATCH_KIND_DELETE,
 } from "./client.js";
 import { report } from "./diagnostic.js";
-import { createAdapters, mergeServerRecords, serverConfigSchema } from "./server-config.js";
+import {
+  createAdapters,
+  mergeServerRecords,
+  type ServerConfig,
+  serverConfigSchema,
+} from "./server-config.js";
 import { type FileChange, watchWorkspace, type WorkspaceWatcher } from "./watcher.js";
 
-/** 超时值：number（毫秒，>=1）或字符串（"500"、"5s"、"1m"），Parse 后由 toMs 统一换算。 */
+/** 超时值：number（毫秒，>=1）或字符串（"500"、"5s"、"1m"），换算发生在 resolveConfig。 */
 const timeoutValue = Type.Union([Type.Number({ minimum: 1 }), Type.String()]);
 
 /** lsp.json 顶层 `watch` 段：工作区文件监听配置。 */
 const watchConfigSchema = Type.Object({
-  /** 是否启用工作区文件监听（缺省 true）。 */
+  /** 是否启用工作区文件监听。 */
   enabled: Type.Optional(Type.Boolean()),
-  /** 事件去抖时长（ms，缺省 300），沿用 timeoutValue 字符串写法。 */
+  /** 事件去抖时长（ms，沿用 timeoutValue 字符串写法）。 */
   debounceMs: Type.Optional(timeoutValue),
-  /** 单批事件上限（缺省 500），超出截断并提示一次。 */
+  /** 单批事件上限，超出截断并提示一次。 */
   maxBatch: Type.Optional(Type.Number({ minimum: 1 })),
   /** 追加忽略 glob（相对工作区根的 POSIX 路径）。 */
   ignore: Type.Optional(Type.Array(Type.String())),
 });
 
-/** lsp.json 的配置项（全局与本地同构）。 */
+/** lsp.json 的配置项（全局与本地同构；只描述用户可写的原始形态，缺省见 configDefaults）。 */
 const lspConfigSchema = Type.Object({
-  /** 配置文件版本（当前 1）；未知版本会被 typebox 严格校验拒绝并回退空配置。 */
+  /** 配置文件版本（当前 1）；未知版本会被 typebox 严格校验拒绝。 */
   version: Type.Optional(Type.Number()),
   /** 配置驱动的语言服务器定义（id → 配置）；无内置默认，全部在此定义。 */
   servers: Type.Optional(Type.Record(Type.String(), serverConfigSchema)),
@@ -69,26 +76,69 @@ const lspConfigSchema = Type.Object({
   enabled: Type.Optional(Type.Array(Type.String())),
   /** 从启用集中排除的服务器 id（缺省 = 无）。 */
   disabled: Type.Optional(Type.Array(Type.String())),
-  /** 工作区文件监听配置（缺省全部字段用 watcher 默认值）。 */
+  /** 工作区文件监听配置（缺省全部字段见 configDefaults.watch）。 */
   watch: Type.Optional(watchConfigSchema),
-  /** 驻留文档上限（LRU 容量，缺省 32）。 */
+  /** 驻留文档上限（LRU 容量），超过时淘汰最久未使用并 didClose。 */
   maxOpenDocuments: Type.Optional(Type.Number({ minimum: 1 })),
-  /** push 诊断去抖（ms，缺省 150）。 */
+  /** push 诊断去抖（ms）。 */
   diagnosticsDebounceMs: Type.Optional(timeoutValue),
-  /** document 模式诊断等待上限（ms，缺省 5_000）。 */
+  /** document 模式诊断等待上限（ms）。 */
   diagnosticsDocumentWaitTimeoutMs: Type.Optional(timeoutValue),
-  /** full 模式诊断等待上限（ms，缺省 10_000）。 */
+  /** full 模式诊断等待上限（ms）。 */
   diagnosticsFullWaitTimeoutMs: Type.Optional(timeoutValue),
-  /** 单次 pull 诊断请求超时（ms，缺省 3_000）。 */
+  /** 单次 pull 诊断请求超时（ms）。 */
   diagnosticsRequestTimeoutMs: Type.Optional(timeoutValue),
-  /** 服务器 initialize 握手超时（ms，缺省 45_000）。 */
+  /** 服务器 initialize 握手超时（ms）。 */
   initializeTimeoutMs: Type.Optional(timeoutValue),
 });
 
-/** 配置值；超时字段为原始写法（number 或字符串），换算发生在 timeoutOptions。 */
+/** 配置值（单文件解析结果）；超时字段为原始写法（number 或字符串），换算在 resolveConfig。 */
 export type LspConfig = Static<typeof lspConfigSchema>;
 
-/** "500" → 500、"5s" → 5000、"1m" → 60000；无效字符串返回 NaN（由 toMs 过滤）。 */
+/**
+ * 解析期缺省（单一来源）。超时/LRU 与 client.create 共用 clientDefaults；
+ * watch 无 client 对应项，数值在此集中。
+ */
+export const configDefaults = {
+  watch: {
+    enabled: true,
+    debounceMs: 300,
+    flushMs: 1_000,
+    maxBatch: 500,
+  },
+  maxOpenDocuments: clientDefaults.maxOpenDocuments,
+} as const;
+
+/** 生效的工作区监听配置（缺省值已应用）。 */
+export interface EffectiveWatchConfig {
+  enabled: boolean;
+  debounceMs: number;
+  flushMs: number;
+  maxBatch: number;
+  ignore: string[];
+}
+
+/** 全局 + 本地合并并解析后的生效配置：所有字段为确定值，无"未配置"歧义。 */
+export interface ResolvedLspConfig {
+  /** 合并后的服务器定义（未配置任何服务器时为空表）。 */
+  servers: Record<string, ServerConfig>;
+  /** enabled 白名单（undefined = 全部启用）。 */
+  enabled: Set<string> | undefined;
+  /** 从启用集中排除的服务器 id（undefined = 无排除）。 */
+  disabled: Set<string> | undefined;
+  /** 工作区监听配置（缺省值已应用）。 */
+  watch: EffectiveWatchConfig;
+  /** 驻留文档 LRU 容量。 */
+  maxOpenDocuments: number;
+  /** 以下超时均为换算后的毫秒数（缺省见 configDefaults / clientDefaults）。 */
+  diagnosticsDebounceMs: number;
+  diagnosticsDocumentWaitTimeoutMs: number;
+  diagnosticsFullWaitTimeoutMs: number;
+  diagnosticsRequestTimeoutMs: number;
+  initializeTimeoutMs: number;
+}
+
+/** "500" → 500、"5s" → 5000、"1m" → 60000；无效字符串返回 NaN（由调用方兜底缺省）。 */
 function parseTimeoutString(value: string): number {
   // 单位组永远参与匹配（缺省为空串），避免"可选捕获组在类型上不可空"的歧义
   const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|)\s*$/.exec(value.trim());
@@ -105,65 +155,51 @@ function parseTimeoutString(value: string): number {
   return amount * (factor ?? 1);
 }
 
+/** 时长字段换算为 ms：number 原样、字符串按 parseTimeoutString；无效值返回 undefined。 */
 function toMs(value: number | string | undefined): number | undefined {
   if (value === undefined) return undefined;
   const ms = typeof value === "number" ? value : parseTimeoutString(value);
   return Number.isFinite(ms) && ms > 0 ? ms : undefined;
 }
 
-/** 从配置里取超时字段（缺省 undefined，create 用自身默认值）。 */
-function timeoutOptions(
-  config: LspConfig,
-): Pick<
-  CreateInput,
-  | "diagnosticsDebounceMs"
-  | "diagnosticsDocumentWaitTimeoutMs"
-  | "diagnosticsFullWaitTimeoutMs"
-  | "diagnosticsRequestTimeoutMs"
-  | "initializeTimeoutMs"
-> {
+/** 把合并后的原始配置解析为生效配置：应用 configDefaults 缺省、字符串时长换算、白名单转 Set。 */
+export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
   return {
-    diagnosticsDebounceMs: toMs(config.diagnosticsDebounceMs),
-    diagnosticsDocumentWaitTimeoutMs: toMs(config.diagnosticsDocumentWaitTimeoutMs),
-    diagnosticsFullWaitTimeoutMs: toMs(config.diagnosticsFullWaitTimeoutMs),
-    diagnosticsRequestTimeoutMs: toMs(config.diagnosticsRequestTimeoutMs),
-    initializeTimeoutMs: toMs(config.initializeTimeoutMs),
-  };
-}
-
-/** 生效的工作区监听配置（应用缺省值）。 */
-export interface EffectiveWatchConfig {
-  enabled: boolean;
-  debounceMs: number;
-  flushMs: number;
-  maxBatch: number;
-  ignore: string[];
-}
-
-/** lsp.json 的 `watch` 段 + 缺省值；debounceMs 字符串时长在此换算。 */
-export function watchOptions(config: LspConfig): EffectiveWatchConfig {
-  const watch = config.watch;
-  return {
-    enabled: watch?.enabled ?? true,
-    debounceMs: toMs(watch?.debounceMs) ?? 300,
-    flushMs: 1_000,
-    maxBatch: watch?.maxBatch ?? 500,
-    ignore: watch?.ignore ?? [],
+    servers: raw.servers ?? {},
+    enabled: raw.enabled === undefined ? undefined : new Set(raw.enabled),
+    disabled: raw.disabled === undefined ? undefined : new Set(raw.disabled),
+    watch: {
+      enabled: raw.watch?.enabled ?? configDefaults.watch.enabled,
+      debounceMs: toMs(raw.watch?.debounceMs) ?? configDefaults.watch.debounceMs,
+      flushMs: configDefaults.watch.flushMs,
+      maxBatch: raw.watch?.maxBatch ?? configDefaults.watch.maxBatch,
+      ignore: raw.watch?.ignore ?? [],
+    },
+    maxOpenDocuments: raw.maxOpenDocuments ?? configDefaults.maxOpenDocuments,
+    diagnosticsDebounceMs: toMs(raw.diagnosticsDebounceMs) ?? clientDefaults.diagnosticsDebounceMs,
+    diagnosticsDocumentWaitTimeoutMs:
+      toMs(raw.diagnosticsDocumentWaitTimeoutMs) ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs,
+    diagnosticsFullWaitTimeoutMs:
+      toMs(raw.diagnosticsFullWaitTimeoutMs) ?? clientDefaults.diagnosticsFullWaitTimeoutMs,
+    diagnosticsRequestTimeoutMs:
+      toMs(raw.diagnosticsRequestTimeoutMs) ?? clientDefaults.diagnosticsRequestTimeoutMs,
+    initializeTimeoutMs: toMs(raw.initializeTimeoutMs) ?? clientDefaults.initializeTimeoutMs,
   };
 }
 
-/** 驻留文档 LRU 容量（缺省 32）。 */
-export function maxOpenDocuments(config: LspConfig): number {
-  return config.maxOpenDocuments ?? 32;
+/** 文件不存在的读取错误（ENOENT），其余错误原样抛出。 */
+function isMissingFile(error: unknown): boolean {
+  return (error as { code?: unknown }).code === "ENOENT";
 }
 
-/** 读取并解析单个配置文件；文件不存在或解析失败时返回空配置。 */
+/** 读取并解析单个配置文件；文件不存在视为空配置，JSON / typebox 校验错误直接抛出。 */
 async function readConfigFile(filePath: string): Promise<LspConfig> {
   try {
     const raw = await readFile(filePath, "utf8");
     return Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
-  } catch {
-    return {};
+  } catch (error) {
+    if (isMissingFile(error)) return {};
+    throw error;
   }
 }
 
@@ -172,8 +208,9 @@ function readConfigFileSync(filePath: string): LspConfig {
   try {
     const raw = readFileSync(filePath, "utf8");
     return Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
-  } catch {
-    return {};
+  } catch (error) {
+    if (isMissingFile(error)) return {};
+    throw error;
   }
 }
 
@@ -182,11 +219,11 @@ function readConfigFileSync(filePath: string): LspConfig {
  * servers），否则抛配置错误（避免白名单静默失效）。disabled 中未注册的 id
  * 直接忽略。
  */
-function validateConfig(config: LspConfig, adapters?: LspServerAdapter[]): void {
+function validateConfig(config: ResolvedLspConfig, adapters?: LspServerAdapter[]): void {
   const available = new Set(
-    adapters ? adapters.map((adapter) => adapter.id) : Object.keys(config.servers ?? {}),
+    adapters ? adapters.map((adapter) => adapter.id) : Object.keys(config.servers),
   );
-  const unknown = (config.enabled ?? []).filter((id) => !available.has(id));
+  const unknown = config.enabled === undefined ? [] : [...config.enabled.difference(available)];
   if (unknown.length > 0) {
     const list = [...available].toSorted().join(", ") || "none";
     throw new Error(
@@ -195,26 +232,46 @@ function validateConfig(config: LspConfig, adapters?: LspServerAdapter[]): void
   }
 }
 
+/** 合并 watch 段：全局为基底、本地逐字段覆盖；ignore 取并集去重（全局在前）。两边都未配置时返回 undefined，调用方据此省略 watch 键。 */
+function mergeWatch(
+  globalWatch: LspConfig["watch"],
+  localWatch: LspConfig["watch"],
+): LspConfig["watch"] {
+  if (!globalWatch && !localWatch) return undefined;
+  return {
+    ...globalWatch,
+    ...localWatch,
+    ignore: [...new Set([...(globalWatch?.ignore ?? []), ...(localWatch?.ignore ?? [])])],
+  };
+}
+
 /**
- * 合并后的生效配置：全局 `~/.pi/agent/lsp.json` 为基底，本地
- * `<cwd>/.pi/lsp.json` 覆盖——顶层标量字段（enabled/disabled、超时等）本地
- * 直接替换；`servers` 按 id 合并（同名 id 整体覆盖、新增 id，全局其余服务器
- * 保留）。
+ * 合并全局与本地两份原始配置（纯函数，供 loadLspConfig 与针对性测试使用）：
+ * 全局为基底、本地逐字段覆盖；`servers` 按 id 合并（同名 id 整体覆盖、新增 id，
+ * 全局其余服务器保留）；`watch` 按字段合并（本地逐字段覆盖、缺省用全局，
+ * `ignore` 取并集去重）。
  */
+export function mergeConfig(globalConfig: LspConfig, localConfig: LspConfig): LspConfig {
+  const servers = mergeServerRecords(globalConfig.servers, localConfig.servers);
+  const watch = mergeWatch(globalConfig.watch, localConfig.watch);
+  return {
+    ...globalConfig,
+    ...localConfig,
+    ...(servers && { servers }),
+    ...(watch && { watch }),
+  };
+}
+
+/** 读取全局 + 本地配置，合并并解析为生效配置。 */
 export async function loadLspConfig(
   cwd: string,
   globalConfigPath: string = join(homedir(), ".pi", "agent", "lsp.json"),
-): Promise<LspConfig> {
+): Promise<ResolvedLspConfig> {
   const [globalConfig, localConfig] = await Promise.all([
     readConfigFile(globalConfigPath),
     readConfigFile(join(cwd, ".pi", "lsp.json")),
   ]);
-  const servers = mergeServerRecords(globalConfig.servers, localConfig.servers);
-  return {
-    ...globalConfig,
-    ...localConfig,
-    ...(servers && { servers }),
-  };
+  return resolveConfig(mergeConfig(globalConfig, localConfig));
 }
 
 /**
@@ -223,12 +280,12 @@ export async function loadLspConfig(
  */
 export function filterAdapters(
   adapters: LspServerAdapter[],
-  config: LspConfig,
+  config: ResolvedLspConfig,
 ): LspServerAdapter[] {
   validateConfig(config, adapters);
   return adapters.filter((adapter) => {
-    if (config.enabled && !config.enabled.includes(adapter.id)) return false;
-    if (config.disabled?.includes(adapter.id)) return false;
+    if (config.enabled && !config.enabled.has(adapter.id)) return false;
+    if (config.disabled?.has(adapter.id)) return false;
     return true;
   });
 }
@@ -357,7 +414,9 @@ export function createLspService(
 ): LspService {
   // 扩展加载时校验全局配置（本地配置在 session_start 预加载时校验）
   validateConfig(
-    readConfigFileSync(globalConfigPath ?? join(homedir(), ".pi", "agent", "lsp.json")),
+    resolveConfig(
+      readConfigFileSync(globalConfigPath ?? join(homedir(), ".pi", "agent", "lsp.json")),
+    ),
     adapters,
   );
   const state: LspState = {
@@ -443,7 +502,7 @@ export function createLspService(
   async function ensureWatcher(cwd: string, notify?: ExtensionUIContext["notify"]): Promise<void> {
     if (state.closing || state.disabled) return;
     const config = await loadLspConfig(cwd, globalConfigPath);
-    const watch = watchOptions(config);
+    const watch = config.watch;
     if (!watch.enabled) return;
     if (watcher && watcherCwd === cwd) return;
     await stopWatcher();
@@ -502,7 +561,13 @@ export function createLspService(
     if (state.closing || state.disabled) return [];
     if (!containsPath(file, cwd)) return [];
     const config = await loadLspConfig(cwd, globalConfigPath);
-    const timeout = timeoutOptions(config);
+    const timeout = {
+      diagnosticsDebounceMs: config.diagnosticsDebounceMs,
+      diagnosticsDocumentWaitTimeoutMs: config.diagnosticsDocumentWaitTimeoutMs,
+      diagnosticsFullWaitTimeoutMs: config.diagnosticsFullWaitTimeoutMs,
+      diagnosticsRequestTimeoutMs: config.diagnosticsRequestTimeoutMs,
+      initializeTimeoutMs: config.initializeTimeoutMs,
+    };
     const active = filterAdapters(adapters ?? createAdapters(config.servers), config);
     const extension = extname(file) || file;
     const result: LspClient[] = [];
@@ -556,7 +621,7 @@ export function createLspService(
             initializeTimeoutMs: adapter.startupTimeoutMs ?? timeout.initializeTimeoutMs,
             diagnosticsDocumentWaitTimeoutMs:
               adapter.diagnosticsWaitMs ?? timeout.diagnosticsDocumentWaitTimeoutMs,
-            maxOpenDocuments: maxOpenDocuments(config),
+            maxOpenDocuments: config.maxOpenDocuments,
           });
           if (state.closing || state.disabled) {
             await client.shutdown();
@@ -883,11 +948,11 @@ function getNoopService(): LspService {
 }
 
 /** 会话配置里生效（未被 enabled 白名单排除、未被 disabled）的服务器数量。 */
-function enabledServerCount(config: LspConfig, adapters?: LspServerAdapter[]): number {
-  const ids = adapters ? adapters.map((adapter) => adapter.id) : Object.keys(config.servers ?? {});
+function enabledServerCount(config: ResolvedLspConfig, adapters?: LspServerAdapter[]): number {
+  const ids = adapters ? adapters.map((adapter) => adapter.id) : Object.keys(config.servers);
   return ids.filter((id) => {
-    if (config.enabled && !config.enabled.includes(id)) return false;
-    if (config.disabled?.includes(id)) return false;
+    if (config.enabled && !config.enabled.has(id)) return false;
+    if (config.disabled?.has(id)) return false;
     return true;
   }).length;
 }