@gavinc-cn/dsh-path-rules 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,9 @@ DSH 第五权限模式「路径规则」的逐调用闸门：挂在 `tools/pre-e
 - **白名单**内的目录可读可写（直通，不弹框）；
 - **黑名单**内的目录读写**都要审批**（优先级最高，压过白名单与项目内）；
 - `bash` / `pwsh`：只读命令直接放行；写入目标可静态解析时按上述规则判定；
-  解析不出的命令默认拒绝并提示模型改写成可判定形式。
+  解析不出的命令默认拒绝并提示模型改写成可判定形式；
+- **自动白名单**（可选，`autoWhitelist: true`）：用户在审批框里批准的沙箱升权写入目标，
+  其目录会自动进入白名单（持久化），下次同目录的写入不再弹框。见下文。
 
 ## 激活条件
 
@@ -51,10 +53,78 @@ shell 判不出 → unanalyzable 策略（默认 deny + 改写指引）
     failMode: closed              # closed | open：插件内部异常时的兜底
     dryRun: false                 # true = 只记日志不拦（灰度用）
     modelFallback: false          # 预留字段：置 true 仅记一条 warn 日志，判定行为不变
+    autoWhitelist: false          # true = 用户批准的沙箱升权写入目标自动进白名单（默认关闭）
+    autoWhitelistFile: <dsh home>/path-rules/auto-whitelist.json   # 自动白名单状态文件（可选）
     logPath: ~/.kimi-code/hooks/logs/path_rules.dsh.log
 ```
 
-日志事件：`plugin-loaded / allow / ask / deny / pass / dry-run / error`。
+日志事件：`plugin-loaded / allow / ask / deny / pass / dry-run / error`，
+以及自动白名单的 `auto-whitelist / auto-whitelist-skip / auto-whitelist-load /
+auto-whitelist-save / auto-whitelist-error`。
+
+## 自动白名单（`autoWhitelist`，2026-10-18 新增）
+
+**用途**：路径规则档下，项目外写入的审批通路是"沙箱拒绝 → 模型带 `sandbox_permissions` 重试 →
+框架弹审批框"。同一个目录反复写就会反复弹框。打开 `autoWhitelist` 后，用户**批准过一次**的写入目标，
+其目录会被自动记进白名单；之后同一目录的升权请求由本插件直接答 `allowed-once`（不弹框）。
+
+**触发条件**（缺一不可）：
+
+1. `autoWhitelist: true` 且 `enabled: true`、`dryRun: false`；
+2. 会话当前处于「路径规则」档（`activationPreset` 命中，子代理沿父链上溯；其它四档不学习）；
+3. 审批类型是**沙箱升权**（`reason` 以 `escalate sandbox to ` 开头）；
+4. 用户在审批框点了同意（`approval/request` 瀑布下游返回 `allowed-once`；拒绝/取消/不可用都不学）。
+
+**学什么**：从该次调用的参数静态解析写入目标 —— `write`/`edit` 的 `file_path`、`bash`/`pwsh` 的
+写目标（复用 `analyze.mjs`）；目标是已存在的目录就取它自己，否则取父目录。**解析不出就什么都不学**
+（不猜）：MCP/未知工具、判不出的 shell 命令、参数没被记住的调用都只记一条 skip 日志。
+
+**生效方式**：条目并入内存白名单（下一条消息起系统提示里可见），此后：
+
+- 该目录的写入由本插件直接 `allow`（但**沙箱仍会先拒绝首次写入** —— 跨层限制见下）；
+- 模型按提示带 `sandbox_permissions` 重试时，`approval/request` 命中白名单 ⇒ 插件答 `allowed-once`，
+  用户**不再看到弹框**。
+
+命令类（`bash`/`pwsh`）升权请求的命中判定 2026-10-18 起改为**按静态写目标**：全部写目标都落在
+白名单/项目内/临时区、且至少一个命中白名单才自动放行；任一目标命中黑名单或项目外就交给用户。
+只有命令判不出写目标时才退回旧的「命令文本包含白名单路径」粗粒度口径。
+（旧口径会把 `cp /white/f.txt /elsewhere/f.txt` 这类命令静默放行；自动白名单让白名单动态变化后必须收紧。）
+
+**持久化**：默认状态文件 `<dsh home>/path-rules/auto-whitelist.json`（可用 `autoWhitelistFile` 覆盖，
+支持 `~`），格式：
+
+```json
+{
+  "version": 1,
+  "entries": [
+    { "path": "/srv/data", "platform": "linux", "addedAt": "2026-10-18T06:00:00.000Z", "tool": "write", "callId": "call_..." }
+  ]
+}
+```
+
+- 按 `process.platform` **分区存放**：容器（linux）与宿主（win32）共享同一份 `~/.dsh` 时互不串味，
+  写回时保留另一平台的条目；跨平台写法的路径在加载时直接忽略。
+- 原子写（临时文件 + rename）、坏文件容错（只记 error 日志，不影响插件加载）、上限 200 条
+  （超出淘汰最旧）。
+- 用户可直接编辑/删除该文件；**生效时机 = 插件重新加载**（改本行 config 是 patch 层热加载约 2 秒；
+  改代码需重启 dsh）。`loader` 日志里 `auto-whitelist loaded=N` 可确认读到了多少条。
+
+**安全护栏**（自动加入前逐条过滤，丢弃原因写进日志）：
+
+| 跳过原因 | 含义 |
+|---|---|
+| `blacklist` | 目标/目录命中黑名单 ⇒ 不学（黑名单优先级最高，加了也无效） |
+| `no-need` | 目标在项目内或临时区，本来就直通，无需白名单 |
+| `already-whitelisted` | 目录已被现有白名单覆盖 |
+| `protected` | 与插件状态/日志文件或 DSH home 相关（防"自动白名单自己改写自己"） |
+| `sensitive` | 目录是系统根（`/`、`/etc`、`/usr`、`/var`、`/opt` …）或用户 home **自身或其祖先** |
+
+即：批准一个文件**不会**被放大成整个 home/系统目录的长期信任；`/root/data` 这类更深层目录可以自动加入，
+但 `/root` 本身不行（要用就手工写进 config 的 `whitelist`）。
+
+**跨层限制（重要）**：自动白名单**不突破沙箱**。工作区外第一次写入仍会被 `workspace-write` 拒绝一次，
+模型需按错误提示带 `sandbox_permissions` + `justification` 重试；区别只在于重试的审批请求
+由插件自动放行、不再弹框。详见下文「已知盲区 8」。
 
 ## 已知盲区（未覆盖，别当安全）
 
@@ -71,6 +141,12 @@ shell 判不出 → unanalyzable 策略（默认 deny + 改写指引）
    项目外/白名单（工作区外）的写会被沙箱拦下，模型需带 `sandbox_permissions` + `justification`
    重试同一调用以触发框架审批；白名单目标的升权请求由本插件自动答 `allowed-once`（无弹框）。
    详见 spec §4.4。
+9. **自动白名单只学"能静态解析写目标"的调用**：MCP/未知工具、`unanalyzable` 的 shell、参数未被记忆的
+   调用都不学习（只记 skip 日志）；`bash` 的间接产物（脚本内部、后台进程）同既有盲区。
+10. **自动白名单是父目录粒度**：批准 `/a/b/f.txt` 会把整个 `/a/b` 加入白名单（用户语义如此）；
+    敏感根保护只挡系统根与 home 自身/祖先，不挡更深的目录。
+11. **命令判不出写目标时升权放行退回子串口径**：`bash`/`pwsh` 命令若静态分析判不出（`unanalyzable`、
+    参数未记忆），仍按"命令文本包含白名单路径"粗粒度放行 —— 这是旧插件沿用口径，无法在不分析的前提下收紧。
 
 ## 测试
 
@@ -78,10 +154,10 @@ shell 判不出 → unanalyzable 策略（默认 deny + 改写指引）
 cd packages/runtime/dsh-path-rules
 node --test test/rules.test.mjs test/classify.test.mjs test/analyze-lex.test.mjs \
   test/analyze-bash.test.mjs test/analyze-pwsh.test.mjs test/decide.test.mjs \
-  test/plugin.test.mjs test/analyze-security.test.mjs
+  test/plugin.test.mjs test/analyze-security.test.mjs test/auto-whitelist.test.mjs
 ```
 
-（Node v24 下 `node --test test/` 目录形式会失败，必须显式给出文件。）
+（Node v24 下 `node --test test/` 目录形式会失败，必须显式给出文件；`npm test` 已包含全部 9 个文件。）
 
 设计文档：`docs/superpowers/specs/2026-10-16-dsh-path-rules-permission-mode-design.md`；
 实现计划：`docs/superpowers/plans/2026-10-17-dsh-path-rules-permission-mode.md`。

package/lib/auto-whitelist.mjs

@@ -0,0 +1,260 @@
+// dsh-path-rules 的自动白名单（2026-10-18 新增）。
+//
+// 目的：用户批准过一次「沙箱升权写入」后，把该次写入目标折叠成的**目录**记进白名单，
+// 之后同一目录的升权请求由插件自动答 allowed-once、不再反复弹框。
+//
+// 三层职责（全部可独立测试，index.mjs 只做接线）：
+//   ① writableDirsOf      ：从一次工具调用（工具名 + 参数）推导写入目标 → 父目录；
+//   ② filterAutoWhitelistDirs：安全护栏（黑名单/项目内/临时区/已覆盖/保护路径/敏感根）；
+//   ③ loadAutoWhitelist / saveAutoWhitelist：按平台分区的 JSON 状态文件读写（原子写）。
+//
+// 重要边界：本模块只负责「学什么、记到哪」，**不改变**判定链本身的优先级
+// （黑名单仍压过白名单；自动条目只是追加进 config.whitelist）。
+
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+import { analyzeCommand } from './analyze.mjs'
+import { classifyTool } from './classify.mjs'
+import { classifyPath, normalizePath, underRoot } from './rules.mjs'
+
+/** 自动白名单条数上限（每个平台），超出淘汰最旧。 */
+export const MAX_AUTO_ENTRIES = 200
+
+/** 状态文件格式版本。 */
+const STATE_VERSION = 1
+
+/** POSIX 系统目录：既不允许自身也不允许它们的祖先目录被自动加入（更深目录可以）。 */
+const POSIX_SENSITIVE_ROOTS = ['/', '/etc', '/usr', '/bin', '/sbin', '/boot', '/var', '/lib', '/lib64', '/opt', '/proc', '/sys', '/dev']
+
+/** 展开 `~` / `~/` / `~\` 前缀；其它写法原样返回。 */
+export function expandHome(path, home = homedir()) {
+  if (typeof path !== 'string') return path
+  if (path === '~') return home
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(home, path.slice(2))
+  return path
+}
+
+/**
+ * 目标路径 → 该自管目录：目标本身是已存在的目录就取它自己，否则取父目录。
+ * （批准后写入目标往往还没创建，所以只能靠"是否已是目录"这一条证据；新目录取父目录是保守估计。）
+ */
+function directoryOf(target) {
+  try {
+    if (statSync(target).isDirectory()) return target
+  } catch {
+    /* 不存在/不可读 ⇒ 按"待创建的文件"处理 */
+  }
+  return dirname(target)
+}
+
+/** 把若干原始写目标归一化并折叠成 {target, dir} 对（去重、丢弃空路径）。 */
+function toPairs(rawTargets, cwd) {
+  const pairs = []
+  const seen = new Set()
+  for (const raw of Array.isArray(rawTargets) ? rawTargets : []) {
+    const target = normalizePath(raw, cwd)
+    if (target.length === 0) continue
+    const dir = directoryOf(target)
+    if (dir.length === 0) continue
+    const key = `${target}\n${dir}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    pairs.push({ target, dir })
+  }
+  return pairs
+}
+
+/**
+ * 从一次工具调用推导"用户批准后要学的目录"。
+ *
+ * 只认写目标：read 不触发升权；shell 用静态分析结果，判不出就**不猜**（返回空）。
+ * 工具/参数不可读时不抛（审批监听器里必须容忍任何异常）。
+ *
+ * @param toolName - 工具名（审批请求里的 request.toolName）。
+ * @param args - 该次调用的参数（pre-execute 按 callId 记忆下来的那份）。
+ * @param cwd - 相对路径解析基准（会话 cwd）。
+ * @returns { pairs: Array<{target: string, dir: string}>, reason?: string }
+ */
+export function writableDirsOf(toolName, args, cwd) {
+  let effect
+  try {
+    effect = classifyTool(toolName, args)
+  } catch {
+    return { pairs: [], reason: 'unreadable-args' }
+  }
+  if (effect.kind === 'write') return { pairs: toPairs(effect.targets, cwd) }
+  if (effect.kind !== 'shell') return { pairs: [], reason: 'not-a-write' }
+  const base = effect.workdir.length > 0 ? effect.workdir : cwd
+  const analysis = analyzeCommand(effect.command, { shell: effect.shell, cwd: base })
+  if (analysis.unanalyzable !== null) return { pairs: [], reason: 'unanalyzable' }
+  return { pairs: toPairs(analysis.writes, base) }
+}
+
+/** 目录是否与受保护路径相关（自身、祖先或后代都算）——状态/日志文件与 DSH home 用它。 */
+function isProtected(dir, protectedPaths) {
+  return protectedPaths.some((path) => underRoot(path, dir) || underRoot(dir, path))
+}
+
+/** 目录是否等于某个敏感根、或是敏感根的祖先（更深层目录允许）。 */
+function isSensitive(dir, sensitiveRoots) {
+  return sensitiveRoots.some((root) => underRoot(root, dir))
+}
+
+/**
+ * 过滤候选目录：只保留"值得且可以自动加入白名单"的那些。
+ *
+ * 跳过原因（写进审计日志用）：
+ *   blacklist         目标或目录命中黑名单（黑名单优先级最高，加了也无效）
+ *   no-need           目标在项目内 / 临时区（本来就直通，无需白名单）
+ *   already-whitelisted 目录已被现有白名单覆盖
+ *   protected         与插件状态/日志文件或 DSH home 相关（防"自动白名单自己改写自己"）
+ *   sensitive         目录是系统根/用户 home 自身或其祖先（防止一次批准放大成整个系统/home）
+ *
+ * @param pairs - writableDirsOf 的输出。
+ * @param options - { roots, protectedPaths, sensitiveRoots }。
+ * @returns { accepted: string[], skipped: Array<{dir, target, reason}> }
+ */
+export function filterAutoWhitelistDirs(pairs, options = {}) {
+  const roots = options.roots ?? {}
+  const whitelist = Array.isArray(roots.whitelist) ? roots.whitelist : []
+  const protectedPaths = (Array.isArray(options.protectedPaths) ? options.protectedPaths : [])
+    .filter((path) => typeof path === 'string' && path.length > 0)
+  const sensitive = (Array.isArray(options.sensitiveRoots) ? options.sensitiveRoots : [])
+    .filter((path) => typeof path === 'string' && path.length > 0)
+  const accepted = []
+  const skipped = []
+  for (const pair of Array.isArray(pairs) ? pairs : []) {
+    const target = pair?.target
+    const dir = pair?.dir
+    if (typeof target !== 'string' || typeof dir !== 'string' || target.length === 0 || dir.length === 0) continue
+    const classification = classifyPath(target, roots)
+    if (classification === 'blacklist') {
+      skipped.push({ dir, target, reason: 'blacklist' })
+      continue
+    }
+    if (classification === 'project' || classification === 'temp') {
+      skipped.push({ dir, target, reason: 'no-need' })
+      continue
+    }
+    if (classifyPath(dir, roots) === 'blacklist') {
+      skipped.push({ dir, target, reason: 'blacklist' })
+      continue
+    }
+    if (whitelist.some((root) => underRoot(dir, root))) {
+      skipped.push({ dir, target, reason: 'already-whitelisted' })
+      continue
+    }
+    if (isProtected(dir, protectedPaths)) {
+      skipped.push({ dir, target, reason: 'protected' })
+      continue
+    }
+    if (isSensitive(dir, sensitive)) {
+      skipped.push({ dir, target, reason: 'sensitive' })
+      continue
+    }
+    if (!accepted.includes(dir)) accepted.push(dir)
+  }
+  return { accepted, skipped }
+}
+
+/** 读状态文件里的全部原始条目（其它平台的要原样保留；文件坏了就当没有）。 */
+function readRawEntries(file) {
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'))
+    return Array.isArray(data?.entries) ? data.entries : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 读取当前平台的自动白名单条目。
+ *
+ * 容错是硬要求：状态文件由用户手改/跨平台同步产生，坏了只记 error 日志、不能影响插件加载。
+ *
+ * @param file - 状态文件绝对路径。
+ * @param platform - 当前平台（默认 process.platform）。
+ * @returns { entries: Array<object>, error?: string }
+ */
+export function loadAutoWhitelist(file, platform = process.platform) {
+  let raw
+  try {
+    raw = readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { entries: [], error: undefined }
+    return { entries: [], error: `读取失败：${String(error)}` }
+  }
+  let data
+  try {
+    data = JSON.parse(raw)
+  } catch (error) {
+    return { entries: [], error: `JSON 解析失败：${String(error)}` }
+  }
+  const entries = []
+  const seen = new Set()
+  for (const item of Array.isArray(data?.entries) ? data.entries : []) {
+    if (item === null || typeof item !== 'object') continue
+    const itemPlatform = item.platform === undefined ? platform : item.platform
+    if (itemPlatform !== platform) continue
+    const path = typeof item.path === 'string' ? item.path.trim() : ''
+    // 相对路径（含跨平台同步过来的另一平台写法）一律忽略，且不写回原文件。
+    if (path.length === 0 || !isAbsolute(path) || seen.has(path)) continue
+    seen.add(path)
+    entries.push({ ...item, path, platform })
+  }
+  return { entries, error: undefined }
+}
+
+/**
+ * 原子写当前平台的自动白名单（保留其它平台条目，防容器/宿主双写互删）。
+ *
+ * @param file - 状态文件绝对路径。
+ * @param platform - 当前平台。
+ * @param entries - 当前平台的完整条目列表（调用方已按上限裁剪）。
+ * @returns { ok: true } | { ok: false, error: string }
+ */
+export function saveAutoWhitelist(file, platform, entries) {
+  const current = Array.isArray(entries) ? entries : []
+  const others = readRawEntries(file).filter((item) => item?.platform !== undefined && item.platform !== platform)
+  const payload = { version: STATE_VERSION, entries: [...others, ...current] }
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+    renameSync(tmp, file)
+    return { ok: true }
+  } catch (error) {
+    return { ok: false, error: String(error) }
+  }
+}
+
+/** Windows 敏感根：优先取环境变量（盘符可能不是 C:）。 */
+function windowsSensitiveRoots() {
+  const roots = []
+  for (const key of ['SystemRoot', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramData']) {
+    const value = process.env[key]
+    if (typeof value === 'string' && value.trim().length > 0) roots.push(value.trim())
+  }
+  roots.push('C:\\')
+  return roots
+}
+
+/**
+ * 敏感根列表：这些目录自身与其祖先不会被自动加入白名单，更深层目录可以。
+ * 用途是防止"批准了一个文件"被放大成"整个系统目录/home"的长期信任。
+ *
+ * @param options - { platform, home }（测试可注入）。
+ * @returns 归一化后的绝对路径列表。
+ */
+export function sensitiveRoots(options = {}) {
+  const platform = options.platform ?? process.platform
+  const home = typeof options.home === 'string' && options.home.length > 0 ? options.home : homedir()
+  const raw = platform === 'win32' ? [...windowsSensitiveRoots(), home] : [...POSIX_SENSITIVE_ROOTS, home]
+  const roots = []
+  for (const path of raw) {
+    const normalized = normalizePath(path, home)
+    if (normalized.length > 0 && !roots.includes(normalized)) roots.push(normalized)
+  }
+  return roots
+}

package/lib/index.mjs

@@ -18,6 +18,15 @@ import { appendFileSync, mkdirSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 import { analyzeCommand } from './analyze.mjs'
+import {
+  MAX_AUTO_ENTRIES,
+  expandHome,
+  filterAutoWhitelistDirs,
+  loadAutoWhitelist,
+  saveAutoWhitelist,
+  sensitiveRoots,
+  writableDirsOf,
+} from './auto-whitelist.mjs'
 import { classifyTool } from './classify.mjs'
 import { combine, classifyPath, decideTarget, normalizePath, normalizeRoots, underRoot } from './rules.mjs'
 
@@ -61,6 +70,9 @@ export function normalizeConfig(raw) {
   if (c.failMode !== undefined && !FAIL_MODES.has(c.failMode)) {
     throw new Error(`dsh-path-rules: failMode must be "closed" or "open", got ${JSON.stringify(c.failMode)}`)
   }
+  if (c.autoWhitelistFile !== undefined && (typeof c.autoWhitelistFile !== 'string' || c.autoWhitelistFile.trim().length === 0)) {
+    throw new Error('dsh-path-rules: autoWhitelistFile must be a non-empty string')
+  }
   const activationPreset = c.activationPreset === undefined ? 'path-rules' : c.activationPreset
   if (typeof activationPreset !== 'string' || activationPreset.trim().length === 0) {
     throw new Error('dsh-path-rules: activationPreset must be a non-empty string')
@@ -75,6 +87,8 @@ export function normalizeConfig(raw) {
     failMode: c.failMode ?? 'closed',
     dryRun: c.dryRun === true,
     modelFallback: c.modelFallback === true,
+    autoWhitelist: c.autoWhitelist === true,
+    autoWhitelistFile: typeof c.autoWhitelistFile === 'string' ? c.autoWhitelistFile.trim() : '',
     logPath: typeof c.logPath === 'string' && c.logPath.trim().length > 0 ? c.logPath.trim() : DEFAULT_LOG,
   }
 }
@@ -197,13 +211,43 @@ function escalationTargetFromArgs(args) {
   return undefined
 }
 
-/** 升权请求的目标是否命中白名单（文件按 realpath 后前缀；命令按粗粒度子串，沿用旧插件口径）。 */
-function escalationIsWhitelisted(target, config, session) {
+/**
+ * 命令类升权请求是否允许自动放行（2026-10-18 严格化）。
+ *
+ * 旧口径只看"命令文本里是否出现白名单路径"，`cp /white/f.txt /elsewhere/f.txt` 也会被静默批准
+ * （自动白名单让白名单动态变化后风险更大）。这里改为按静态分析出的**写目标**判定：
+ *
+ * @returns true      = 全部写目标都在白名单/项目内/临时区，且至少一个命中白名单 ⇒ 可自动放行；
+ *          false     = 存在黑名单或项目外写目标 ⇒ 必须交给用户；
+ *          undefined = 判不出（参数缺失/不可解析/没有写目标）⇒ 退回旧的子串口径兜底。
+ */
+function commandEscalationIsWhitelisted(config, session, services, toolName, args) {
+  if (args === undefined) return undefined
+  const cwd = sessionCwdOf(session, services)
+  const derived = writableDirsOf(toolName, args, cwd)
+  if (derived.pairs.length === 0) return undefined
+  const roots = buildRoots(session, config, services)
+  let sawWhitelist = false
+  for (const pair of derived.pairs) {
+    const kind = classifyPath(pair.target, roots)
+    if (kind === 'blacklist' || kind === 'outside') return false
+    if (kind === 'whitelist') sawWhitelist = true
+  }
+  return sawWhitelist ? true : undefined
+}
+
+/**
+ * 升权请求的目标是否命中白名单（文件按 realpath 后前缀；命令优先按静态写目标严格判定，
+ * 判不出时再用粗粒度子串兜底）。
+ */
+function escalationIsWhitelisted(target, config, session, commandCheck) {
   if (config.whitelist.length === 0) return false
   if (target.kind === 'file') {
     const resolved = normalizePath(target.value, session?.header?.cwd ?? process.cwd())
     return config.whitelist.some((root) => underRoot(resolved, root))
   }
+  const strict = typeof commandCheck === 'function' ? commandCheck() : undefined
+  if (strict !== undefined) return strict
   return config.whitelist.some((root) => target.value.includes(root))
 }
 
@@ -306,8 +350,37 @@ function logLine(logPath, event, summary, detail) {
   }
 }
 
+/**
+ * 解析 DSH home：优先用宿主提供的 `dshHomePath` 服务（尊重 `DSH_HOME`），
+ * 缺失时按 `$DSH_HOME` → `~/.dsh` 回退。用于定位自动白名单状态文件与保护路径。
+ */
+function resolveDshHome(ctx) {
+  const homePath = ctx.get?.('dshHomePath')
+  if (typeof homePath === 'function') {
+    try {
+      const home = homePath()
+      if (typeof home === 'string' && home.length > 0) return home
+    } catch {
+      /* 服务不可用时走环境变量回退 */
+    }
+  }
+  const fromEnv = typeof process.env.DSH_HOME === 'string' ? process.env.DSH_HOME.trim() : ''
+  return fromEnv.length > 0 ? fromEnv : join(homedir(), '.dsh')
+}
+
+/**
+ * 自动白名单状态文件路径：配置优先（支持 `~`），否则放在 `<dsh home>/path-rules/auto-whitelist.json`。
+ * 按平台分区写在文件内部（见 auto-whitelist.mjs），所以容器与宿主同步同一份文件也不会串味。
+ */
+function resolveAutoWhitelistFile(config, ctx) {
+  if (config.autoWhitelistFile.length > 0) {
+    return normalizePath(expandHome(config.autoWhitelistFile, homedir()), process.cwd())
+  }
+  return normalizePath(join(resolveDshHome(ctx), 'path-rules', 'auto-whitelist.json'), process.cwd())
+}
+
 /** 给模型看的规则说明；**只有本会话真的受该模式管辖时才注入**（否则模型会误判自己的权限档）。 */
-function renderRules(config, session, services) {
+function renderRules(config, session, services, extras = {}) {
   if (session === undefined || session === null) return ''
   if (typeof services.presetOf !== 'function') return ''
   try {
@@ -316,15 +389,20 @@ function renderRules(config, session, services) {
     return ''
   }
   const cwd = typeof session?.header?.cwd === 'string' ? session.header.cwd : ''
+  const declaredWhitelist = Array.isArray(extras.declaredWhitelist) ? extras.declaredWhitelist : config.whitelist
+  const autoEntries = Array.isArray(extras.autoEntries) ? extras.autoEntries : []
   const lines = [
     '[path-rules] 当前权限模式：路径规则。',
     `会话工作区（可自由读写）：${cwd.length > 0 ? cwd : '(未知)'}`,
     '工作区外：读取允许；写入需要用户审批（会弹工具审批框）。',
   ]
-  if (config.whitelist.length > 0) lines.push(`白名单（可自由读写）：${config.whitelist.join(', ')}`)
+  if (declaredWhitelist.length > 0) lines.push(`白名单（可自由读写）：${declaredWhitelist.join(', ')}`)
+  if (autoEntries.length > 0) {
+    lines.push(`自动白名单（用户批准后自动学习，升权请求会被自动放行、不弹框）：${autoEntries.map((entry) => entry.path).join(', ')}`)
+  }
   if (config.blacklist.length > 0) lines.push(`黑名单（读写都需要审批）：${config.blacklist.join(', ')}`)
   lines.push('bash/pwsh：只读命令直接放行；写命令请写成可静态判定的形式（显式路径），判不出的命令会被拒绝。')
-  lines.push('工作区外写入若先被沙箱拒绝：用 sandbox_permissions（能覆盖该目标的最窄更宽模式）+ justification 重试同一调用，用户审批后即可写入；白名单内的目标会自动放行。')
+  lines.push('工作区外写入若先被沙箱拒绝：用 sandbox_permissions（能覆盖该目标的最窄更宽模式）+ justification 重试同一调用，用户审批后即可写入；白名单与自动白名单内的目标会自动放行。')
   return lines.join('\n')
 }
 
@@ -374,17 +452,36 @@ function compose(downstream, decision, config, log, exec) {
  */
 export function apply(ctx, rawConfig) {
   const base = normalizeConfig(rawConfig)
+  const declaredWhitelist = normalizeRoots(base.whitelist, process.cwd())
   const config = {
     ...base,
-    whitelist: normalizeRoots(base.whitelist, process.cwd()),
+    whitelist: [...declaredWhitelist],
     blacklist: normalizeRoots(base.blacklist, process.cwd()),
   }
   const log = (event, summary, detail) => logLine(config.logPath, event, summary, detail)
-  log('plugin-loaded', `enabled=${config.enabled}`, `activationPreset=${config.activationPreset} dryRun=${config.dryRun}`)
+  log('plugin-loaded', `enabled=${config.enabled} autoWhitelist=${config.autoWhitelist}`, `activationPreset=${config.activationPreset} dryRun=${config.dryRun}`)
   if (config.modelFallback) {
     log('error', 'warn:model-fallback-ignored', 'modelFallback 本期不改变判定行为（模型裁决路径需另立 spec）')
   }
 
+  // 自动白名单的状态文件与保护路径（只在开关打开时才读盘；关闭时零 IO、零行为变化）。
+  const autoWhitelistFile = resolveAutoWhitelistFile(config, ctx)
+  const dshHome = resolveDshHome(ctx)
+  const protectedPaths = [...new Set([autoWhitelistFile, config.logPath, dshHome])]
+  /** 当前进程内的自动白名单条目（与 config.whitelist 同步追加；持久化只写本平台分区）。 */
+  const autoEntries = []
+  if (config.autoWhitelist) {
+    const loaded = loadAutoWhitelist(autoWhitelistFile, process.platform)
+    if (loaded.error !== undefined) log('error', 'auto-whitelist-load', loaded.error)
+    for (const entry of loaded.entries) {
+      const normalized = normalizePath(entry.path, process.cwd())
+      if (normalized.length === 0 || autoEntries.some((item) => item.path === normalized)) continue
+      autoEntries.push({ ...entry, path: normalized })
+      if (!config.whitelist.includes(normalized)) config.whitelist.push(normalized)
+    }
+    if (autoEntries.length > 0) log('auto-whitelist', `loaded=${autoEntries.length}`, autoWhitelistFile)
+  }
+
   const services = {
     presetOf: (session) => ctx.get('permissionPresets')?.current?.(session),
     workspaceRootOf: (session) => ctx.get('sandboxPolicy')?.resolve?.({ session })?.workspaceRoot,
@@ -412,29 +509,100 @@ export function apply(ctx, rawConfig) {
     scope.systemPrompt.context({
       name: 'path-rules',
       order: 111,
-      text: (context) => renderRules(config, context?.agent?.session, services),
+      text: (context) => renderRules(config, context?.agent?.session, services, { declaredWhitelist, autoEntries }),
     })
   })
 
+  /**
+   * 把一次"用户批准的沙箱升权调用"学进自动白名单。
+   *
+   * 只在 path-rules 档激活的会话里学（其它档不改变任何状态）；任何异常都吞掉并记日志 ——
+   * 它只是顺手降低重复弹框，绝不能影响审批结果本身。
+   */
+  const learnFromApproval = (request) => {
+    const session = request.agent?.session
+    if (session === undefined || session === null) return
+    if (!isActive(session, config, services)) return
+    const args = recentCallArgs.get(request.callId)
+    if (args === undefined) {
+      log('auto-whitelist-skip', 'no-remembered-args', request.callId)
+      return
+    }
+    const cwd = sessionCwdOf(session, services)
+    const derived = writableDirsOf(request.toolName, args, cwd)
+    if (derived.pairs.length === 0) {
+      log('auto-whitelist-skip', derived.reason ?? 'no-write-target', request.callId)
+      return
+    }
+    const roots = buildRoots(session, config, services)
+    const { accepted, skipped } = filterAutoWhitelistDirs(derived.pairs, {
+      roots,
+      protectedPaths,
+      sensitiveRoots: sensitiveRoots(),
+    })
+    for (const item of skipped) log('auto-whitelist-skip', `${item.reason} ${item.dir}`, describeCall({ name: request.toolName, arguments: args }))
+    if (accepted.length === 0) return
+
+    const added = []
+    for (const dir of accepted) {
+      if (autoEntries.some((entry) => entry.path === dir)) continue
+      autoEntries.push({
+        path: dir,
+        platform: process.platform,
+        addedAt: new Date().toISOString(),
+        tool: String(request.toolName ?? ''),
+        callId: request.callId,
+      })
+      if (!config.whitelist.includes(dir)) config.whitelist.push(dir)
+      added.push(dir)
+    }
+    // 上限按"最旧淘汰"：自动白名单只是便利，不能无限膨胀。
+    while (autoEntries.length > MAX_AUTO_ENTRIES) {
+      const dropped = autoEntries.shift()
+      const index = config.whitelist.indexOf(dropped.path)
+      if (index >= 0) config.whitelist.splice(index, 1)
+    }
+    if (added.length === 0) return
+    const saved = saveAutoWhitelist(autoWhitelistFile, process.platform, autoEntries)
+    if (!saved.ok) log('error', 'auto-whitelist-save', saved.error)
+    log('auto-whitelist', `added=${added.length}`, added.join(', '))
+  }
+
   // 白名单目标的沙箱升权请求自动放行（承接已退役的 sandbox-path-allowlist 能力）：
   // 只作答 "escalate sandbox to " 开头的请求，且目标必须命中白名单；其余一律交给下游弹框。
+  // autoWhitelist 打开时再包一层：等用户的结论，只有 allowed-once（用户点了同意）才学习。
   ctx.on('approval/request', (request, next) => {
     if (typeof request?.callId !== 'string') return next()
     if (typeof request.reason !== 'string' || !request.reason.startsWith(SANDBOX_ESCALATION_PREFIX)) return next()
+
+    let target
     try {
       const remembered = recentCallArgs.get(request.callId)
       const session = request.agent?.session
       // remembered 优先：真实运行态里审批请求附带的 session 不暴露 events，无法按 callId 回查
       // 会话日志（实测 hasEvents=false），只有 pre-execute 时记下的参数可靠。
-      const target = escalationTargetFromArgs(remembered) ?? escalationTargetOf(session, request.callId)
-      if (target === undefined || !escalationIsWhitelisted(target, config, session)) return next()
-      // remembered 只进审计日志，便于区分"走记忆命中"与"走会话日志兜底命中"
-      log('allow', 'whitelist-escalation', `${request.callId} remembered=${remembered !== undefined} ${target.value}`)
-      return 'allowed-once'
+      target = escalationTargetFromArgs(remembered) ?? escalationTargetOf(session, request.callId)
+      const commandCheck = () => commandEscalationIsWhitelisted(config, session, services, request.toolName, remembered)
+      if (target !== undefined && escalationIsWhitelisted(target, config, session, commandCheck)) {
+        // remembered 只进审计日志，便于区分"走记忆命中"与"走会话日志兜底命中"
+        log('allow', 'whitelist-escalation', `${request.callId} remembered=${remembered !== undefined} ${target.value}`)
+        return 'allowed-once'
+      }
     } catch (error) {
       log('error', 'approval-error', String(error))
       return next()
     }
+    if (target === undefined || !config.autoWhitelist || !config.enabled || config.dryRun) return next()
+    return Promise.resolve(next()).then((outcome) => {
+      if (outcome === 'allowed-once') {
+        try {
+          learnFromApproval(request)
+        } catch (error) {
+          log('error', 'auto-whitelist-error', String(error))
+        }
+      }
+      return outcome
+    })
   }, { prepend: true })
 
   ctx.on('tools/pre-execute', async (exec, next) => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@gavinc-cn/dsh-path-rules",
   "title": "路径规则守卫",
   "description": "第五权限模式「路径规则」的逐调用闸门：项目内可读写 / 项目外读允许·写审批 / 白名单直通 / 黑名单读写都审批 / bash·pwsh 只读放行；经 tools/pre-execute 返回 allow|ask|deny。",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "./lib/index.mjs",
   "files": [
@@ -15,7 +15,7 @@
     "./locale/*.json": "./locale/*.json"
   },
   "scripts": {
-    "test": "node --test test/rules.test.mjs test/classify.test.mjs test/analyze-lex.test.mjs test/analyze-bash.test.mjs test/analyze-pwsh.test.mjs test/decide.test.mjs test/plugin.test.mjs test/analyze-security.test.mjs"
+    "test": "node --test test/rules.test.mjs test/classify.test.mjs test/analyze-lex.test.mjs test/analyze-bash.test.mjs test/analyze-pwsh.test.mjs test/decide.test.mjs test/plugin.test.mjs test/analyze-security.test.mjs test/auto-whitelist.test.mjs"
   },
   "license": "MIT",
   "repository": {