@jonathanleelx/meddle 0.5.0-beta.23 → 0.5.0-beta.24

package/CONFIG_STRUCTURE.md

@@ -204,6 +204,7 @@ https://localhost:13001/micro/app?a=1
 | `detailBodySizeKB` | 日志详情保存的请求/响应体截断阈值（KB），默认 `256`；调大可保留更大 body 便于排查，但会增加内存占用（最多 `MAX_DETAIL_SIZE=200` 条同时驻留）。作用范围为单个 session，解析顺序：当前 session 的 `settings.json` → 默认 session（`~/.meddle/settings.json`，仅非默认 session 继承）→ 环境变量 `MEDDLE_MAX_DETAIL_BODY_KB` → 默认 `256`。修改后下次请求即生效（基于 mtime 缓存检测） |
 | `activeRuleFiles` | 当前启用的路由规则文件名称，顺序即合并顺序 |
 | `ruleFileOrder` | Web 规则文件 Tab 的完整显示顺序（含禁用文件）；启用文件的合并顺序与其在该数组中的相对顺序一致 |
+| `readonlyRuleFiles` | 只读（加锁）的规则文件名称。可选，缺省即全部可读写。只能在 Web 界面中修改；锁住的规则文件拒绝 CLI / MCP / API 的一切写入。见 [只读规则集](./docs/RULESET_READONLY.md) |
 | `mocksFilePath` | 自定义 Mock JSON 路径；空值使用默认位置 |
 | `pluginMode` | 插件 Pipeline 模式：`off`、`shadow` 或 `on` |
 | `clientAliases` | 客户端 IP 到设备名称的映射 |

package/README.md

@@ -181,6 +181,22 @@ meddle --remote --no-intercept-https
 
 所有 `mock_rule_*`、`route_rule_*`、`route_preview` 工具均支持可选 `session` 参数，指定后可操作对应 session 的规则，不传则操作默认 session。
 
+**路由规则写入**（`route_rule_add` / `route_rule_update` / `route_rule_delete`）只改包含该 pattern 的那一行，规则文件里的注释、空行、`//` 禁用规则和其他规则（连同排除项）都按原样保留：
+
+- **不传 `exclusions`**：保留该规则原有的排除规则（`route_rule_add` 覆盖已有规则时也一样；新规则则没有排除规则）。
+- **传 `exclusions: []`**：清空该规则的排除规则。
+- 传非空数组：用它替换原有的排除规则。
+- 如果一行写了多个 pattern，修改或删除其中一个时，若剩下的 pattern 以 `//` 或 `#` 开头（拆开后会被当成注释），写入会被拒绝并提示「该行剩余的 pattern 以 // 或 # 开头，拆开后会被当成注释，请用文本编辑器手动修改」，规则文件不变。
+- 新增规则的 pattern 不能以 `#` 或 `//` 开头（例如 `#foo.com`、`//foo.com`），否则写进文件后会被当成注释或禁用行。写入会被拒绝并提示「规则不能以 // 或 # 开头，否则会被当成禁用行或注释。要写注释或禁用规则，请用文本编辑器。」，规则文件不变。
+- CLI 没有单独的排除规则参数：`meddle route add/update` 的 pattern 参数里写了 `!path`（如 `"api.example.com !/health"`）就替换，不写就保留原有的；CLI 无法清空排除规则，需要清空时用 MCP 传 `[]`，或在 Web 界面里编辑。
+
+**只读规则集**（[详细说明](./docs/RULESET_READONLY.md)）：规则集（规则文件）可以在 Meddle Web 界面中加只读锁，防止 Agent 误改。
+
+- `route_rule_list` 的结果带 `readonly: true|false`。
+- 锁住后 `route_rule_add` / `route_rule_update` / `route_rule_delete` / `route_rule_active_set`（会改变锁住规则集的启用状态时）全部被拒绝，规则文件不变，工具返回 `isError: true` 与 `{"error":{"code":"RULESET_READONLY","message":"该规则集已设为只读，只能在 Meddle 界面中解锁","ruleFile":"…"}}`。CLI 同样拒绝，退出码为 `3`。
+- **CLI 和 MCP 都没有加锁 / 解锁的命令或工具**，只能由人在 Meddle 界面中操作。界面使用页面令牌 + 同源校验；这只是防误改，不是安全隔离（可被 `curl` 取页面令牌并伪造 `Origin` 绕过，有 shell 的 Agent 也能直接改磁盘文件）。
+- 锁住的规则集不能重命名，需先在 Meddle 界面中解锁再改名；在 Meddle 之外直接改文件名视为新规则集（可读写），旧锁记录自动清除。
+
 ### 多 Session 隔离（预览功能）
 
 多 Session 允许同时运行多个独立的 `meddle` 代理进程，每个进程拥有独立的配置目录（MEDDLE_HOME）、端口、路由规则和 Mock 规则，适用于多个 Agent 或项目需要隔离代理环境的场景。

package/bin/commands/route/active.js

@@ -5,7 +5,13 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet, apiPut } = require('../../lib/api-client')
-const { listRuleFiles, getActiveRuleFileNames, setActiveRuleFileNames, setRuleFileEnabled } = require('../../lib/file-access')
+const { listRuleFiles, getActiveRuleFileNames, setRuleFileEnabled } = require('../../lib/file-access')
+const { isRulesetReadonlyError, exitRulesetReadonly, assertListedFilesWritable } = require('../../lib/ruleset-readonly')
+
+/** Names whose enabled state `active set <file>` would change. */
+function pendingToggles(files, target) {
+  return files.filter((f) => !!f.enabled !== (f.name === target)).map((f) => f.name)
+}
 
 // Parse arguments (skip 'route' and 'active' from argv)
 const args = process.argv.slice(4)
@@ -39,6 +45,9 @@ async function run() {
           process.exit(1)
         }
 
+        // Issue #137: refuse up front so a locked ruleset never leaves a half-applied switch.
+        assertListedFilesWritable(files, pendingToggles(files, targetFile))
+
         for (const f of files) {
           const nextEnabled = f.name === targetFile
           if (!!f.enabled === nextEnabled) continue
@@ -53,6 +62,7 @@ async function run() {
         output.header('Active Route File Set')
         output.success(targetFile)
       } catch (e) {
+        if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: targetFile })
         // Fallback to file mode
         const files = listRuleFiles()
         const target = files.find(f => f.name === targetFile)
@@ -61,6 +71,7 @@ async function run() {
           process.exit(1)
         }
 
+        assertListedFilesWritable(files, pendingToggles(files, targetFile))
         // Disable all, then enable target
         files.forEach(f => setRuleFileEnabled(f.name, f.name === targetFile))
 
@@ -83,6 +94,7 @@ async function run() {
         process.exit(1)
       }
 
+      assertListedFilesWritable(files, pendingToggles(files, targetFile))
       files.forEach(f => setRuleFileEnabled(f.name, f.name === targetFile))
 
       output.warnFileOnlyMode()
@@ -140,6 +152,7 @@ async function run() {
 }
 
 run().catch(e => {
+  if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: targetFile })
   output.error(e.message)
   process.exit(1)
 })

package/bin/commands/route/add.js

@@ -5,7 +5,9 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet, apiPut } = require('../../lib/api-client')
-const { getRuleFileContent, saveRuleFileContent, parseEprc, ruleMapToEprcText } = require('../../lib/file-access')
+const { getRuleFileContent, saveRuleFileContent } = require('../../lib/file-access')
+const { addRouteRule, splitPatternArg } = require('../../lib/rule-file-edit')
+const { isRulesetReadonlyError, exitRulesetReadonly } = require('../../lib/ruleset-readonly')
 
 // Parse arguments (skip 'route' and 'add' from argv)
 const args = process.argv.slice(4)
@@ -18,6 +20,24 @@ const fileName = positionalArgs[0]
 const pattern = positionalArgs[1]
 const target = positionalArgs[2]
 
+/**
+ * Issue #145: edit only the line(s) holding this pattern; comments, blank
+ * lines and other rules (with their `!exclusions`) keep their exact bytes.
+ * Exclusions may be given inside the pattern argument ("app.example.com !/api").
+ */
+function applyAdd(text) {
+  const { patterns, exclusions } = splitPatternArg(pattern)
+  if (patterns.length === 0) {
+    output.error('Missing required argument: <pattern>')
+    process.exit(1)
+  }
+  let next = text
+  for (const p of patterns) {
+    next = addRouteRule(next, { pattern: p, target: target.trim(), exclusions: exclusions.length ? exclusions : undefined }).content
+  }
+  return next
+}
+
 async function run() {
   if (!fileName) {
     output.error('Missing required argument: <file>')
@@ -42,17 +62,7 @@ async function run() {
       // Get current content
       let content = await apiGet(`/api/rule-files/${encodeURIComponent(fileName)}/content`)
       const text = typeof content === 'string' ? content : String(content)
-      const ruleMap = parseEprc(text)
-
-      // Handle [marker] syntax
-      const bm = pat.match(/\[([^\]]+)\]/)
-      if (bm) {
-        ruleMap[pat.replace(bm[0], bm[1])] = tgt + bm[0]
-      } else {
-        ruleMap[pat] = tgt
-      }
-
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyAdd(text)
       await apiPut(`/api/rule-files/${encodeURIComponent(fileName)}/content`, { content: newContent })
 
       if (jsonFlag) {
@@ -64,6 +74,8 @@ async function run() {
       output.success(`${pat} -> ${tgt}`)
       output.kv('File', fileName)
     } catch (e) {
+      // Issue #137: a locked ruleset is a final answer, never a cue to write the file directly.
+      if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
       // Fallback to file mode
       const content = getRuleFileContent(fileName)
       if (!content) {
@@ -71,15 +83,7 @@ async function run() {
         process.exit(1)
       }
 
-      const ruleMap = parseEprc(content)
-      const bm = pat.match(/\[([^\]]+)\]/)
-      if (bm) {
-        ruleMap[pat.replace(bm[0], bm[1])] = tgt + bm[0]
-      } else {
-        ruleMap[pat] = tgt
-      }
-
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyAdd(content)
       saveRuleFileContent(fileName, newContent)
       output.warnFileOnlyMode()
 
@@ -104,15 +108,7 @@ async function run() {
       process.exit(1)
     }
 
-    const ruleMap = parseEprc(content)
-    const bm = pat.match(/\[([^\]]+)\]/)
-    if (bm) {
-      ruleMap[pat.replace(bm[0], bm[1])] = tgt + bm[0]
-    } else {
-      ruleMap[pat] = tgt
-    }
-
-    const newContent = ruleMapToEprcText(ruleMap)
+    const newContent = applyAdd(content)
     saveRuleFileContent(fileName, newContent)
     output.warnFileOnlyMode()
 
@@ -132,6 +128,7 @@ async function run() {
 }
 
 run().catch(e => {
+  if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
   output.error(e.message)
   process.exit(1)
 })

package/bin/commands/route/delete.js

@@ -5,7 +5,9 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet, apiPut } = require('../../lib/api-client')
-const { getRuleFileContent, saveRuleFileContent, parseEprc, ruleMapToEprcText } = require('../../lib/file-access')
+const { getRuleFileContent, saveRuleFileContent } = require('../../lib/file-access')
+const { deleteRouteRule, splitPatternArg } = require('../../lib/rule-file-edit')
+const { isRulesetReadonlyError, exitRulesetReadonly } = require('../../lib/ruleset-readonly')
 
 // Parse arguments (skip 'route' and 'delete' from argv)
 const args = process.argv.slice(4)
@@ -17,6 +19,28 @@ const positionalArgs = args.filter(a => !a.startsWith('--'))
 const fileName = positionalArgs[0]
 const pattern = positionalArgs[1]
 
+/**
+ * Issue #145: remove only this pattern; every other line (comments, blank
+ * lines, other rules and their `!exclusions`) keeps its exact bytes.
+ */
+function applyDelete(text) {
+  const { patterns } = splitPatternArg(pattern)
+  if (patterns.length === 0) {
+    output.error('Missing required argument: <pattern>')
+    process.exit(1)
+  }
+  let next = text
+  for (const p of patterns) {
+    const result = deleteRouteRule(next, { pattern: p })
+    if (!result.found) {
+      output.error(`Pattern not found: ${pattern.trim()}`)
+      process.exit(1)
+    }
+    next = result.content
+  }
+  return next
+}
+
 async function run() {
   if (!fileName) {
     output.error('Missing required argument: <file>')
@@ -31,23 +55,11 @@ async function run() {
 
   const pat = pattern.trim()
 
-  // Handle [marker] syntax for lookup
-  const bm = pat.match(/\[([^\]]+)\]/)
-  const internalKey = bm ? pat.replace(bm[0], bm[1]) : pat
-
   if (running) {
     try {
       let content = await apiGet(`/api/rule-files/${encodeURIComponent(fileName)}/content`)
       const text = typeof content === 'string' ? content : String(content)
-      const ruleMap = parseEprc(text)
-
-      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-        output.error(`Pattern not found: ${pat}`)
-        process.exit(1)
-      }
-
-      delete ruleMap[internalKey]
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyDelete(text)
       await apiPut(`/api/rule-files/${encodeURIComponent(fileName)}/content`, { content: newContent })
 
       if (jsonFlag) {
@@ -59,6 +71,8 @@ async function run() {
       output.success(pat)
       output.kv('File', fileName)
     } catch (e) {
+      // Issue #137: a locked ruleset is a final answer, never a cue to write the file directly.
+      if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
       // Fallback to file mode
       const content = getRuleFileContent(fileName)
       if (!content) {
@@ -66,14 +80,7 @@ async function run() {
         process.exit(1)
       }
 
-      const ruleMap = parseEprc(content)
-      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-        output.error(`Pattern not found: ${pat}`)
-        process.exit(1)
-      }
-
-      delete ruleMap[internalKey]
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyDelete(content)
       saveRuleFileContent(fileName, newContent)
       output.warnFileOnlyMode()
 
@@ -98,14 +105,7 @@ async function run() {
       process.exit(1)
     }
 
-    const ruleMap = parseEprc(content)
-    if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-      output.error(`Pattern not found: ${pat}`)
-      process.exit(1)
-    }
-
-    delete ruleMap[internalKey]
-    const newContent = ruleMapToEprcText(ruleMap)
+    const newContent = applyDelete(content)
     saveRuleFileContent(fileName, newContent)
     output.warnFileOnlyMode()
 
@@ -125,6 +125,7 @@ async function run() {
 }
 
 run().catch(e => {
+  if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
   output.error(e.message)
   process.exit(1)
 })

package/bin/commands/route/index.js

@@ -43,6 +43,10 @@ Route Commands:
   meddle route update <file> <pattern> <target> Update a rule in file
   meddle route delete <file> <pattern>          Delete a rule from file
 
+Read-only route files:
+  Files locked in the Meddle web UI reject add/update/delete and active set
+  (error RULESET_READONLY, exit code 3). Lock/unlock is only available in the web UI.
+
 Examples:
   meddle route list
   meddle route show dev-rules

package/bin/commands/route/list.js

@@ -48,7 +48,7 @@ async function run() {
     output.section('Active Files')
     active.forEach(f => {
       const excludeInfo = f.excludeCount > 0 ? `, ${f.excludeCount} exclusions` : ''
-      output.success(`${f.name} (${f.ruleCount} rules${excludeInfo})`)
+      output.success(`${f.name} (${f.ruleCount} rules${excludeInfo})${f.readonly ? ' [read-only]' : ''}`)
     })
   }
 
@@ -56,7 +56,7 @@ async function run() {
     output.section('Inactive Files')
     inactive.forEach(f => {
       const excludeInfo = f.excludeCount > 0 ? `, ${f.excludeCount} exclusions` : ''
-      output.bullet(`${f.name} (${f.ruleCount} rules${excludeInfo})`, false)
+      output.bullet(`${f.name} (${f.ruleCount} rules${excludeInfo})${f.readonly ? ' [read-only]' : ''}`, false)
     })
   }
 }

package/bin/commands/route/show.js

@@ -5,7 +5,7 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet } = require('../../lib/api-client')
-const { getRuleFileContent, parseEprcWithExclusions } = require('../../lib/file-access')
+const { getRuleFileContent, parseEprcWithExclusions, isRuleFileReadonly } = require('../../lib/file-access')
 
 // Parse arguments (skip 'route' and 'show' from argv)
 const args = process.argv.slice(4)
@@ -26,10 +26,15 @@ async function run() {
   let content = null
   let ruleMap = {}
   let excludeMap = {}
+  // Issue #137: report the lock state (read-only for the CLI either way).
+  let readonly = false
 
   if (running) {
     try {
       content = await apiGet(`/api/rule-files/${encodeURIComponent(fileName)}/content`)
+      const files = await apiGet('/api/rule-files')
+      const info = Array.isArray(files) ? files.find((f) => f && f.name === fileName) : null
+      readonly = Boolean(info && info.readonly)
       const parsed = parseEprcWithExclusions(typeof content === 'string' ? content : String(content))
       ruleMap = parsed.ruleMap
       excludeMap = parsed.excludeMap
@@ -43,6 +48,7 @@ async function run() {
       const parsed = parseEprcWithExclusions(content)
       ruleMap = parsed.ruleMap
       excludeMap = parsed.excludeMap
+      readonly = isRuleFileReadonly(fileName)
     }
   } else {
     content = getRuleFileContent(fileName)
@@ -53,6 +59,7 @@ async function run() {
     const parsed = parseEprcWithExclusions(content)
     ruleMap = parsed.ruleMap
     excludeMap = parsed.excludeMap
+    readonly = isRuleFileReadonly(fileName)
   }
 
   // Build display rules (handle [marker] syntax)
@@ -76,6 +83,7 @@ async function run() {
   if (jsonFlag) {
     output.jsonRaw({
       file: fileName,
+      readonly,
       rules: displayRules,
       ruleCount: Object.keys(displayRules).length,
       exclusionCount: totalExclusions
@@ -84,6 +92,7 @@ async function run() {
   }
 
   output.header(`Route File: ${fileName}`)
+  output.kv('Read-only', readonly ? 'Yes (unlock in the Meddle UI)' : 'No')
   output.kv('Rules', Object.keys(displayRules).length)
   if (totalExclusions > 0) {
     output.kv('Exclusions', totalExclusions)

package/bin/commands/route/update.js

@@ -5,7 +5,9 @@
 const output = require('../../lib/output')
 const { isProxyRunning } = require('../../lib/proxy-detect')
 const { apiGet, apiPut } = require('../../lib/api-client')
-const { getRuleFileContent, saveRuleFileContent, parseEprc, ruleMapToEprcText } = require('../../lib/file-access')
+const { getRuleFileContent, saveRuleFileContent } = require('../../lib/file-access')
+const { updateRouteRule, splitPatternArg } = require('../../lib/rule-file-edit')
+const { isRulesetReadonlyError, exitRulesetReadonly } = require('../../lib/ruleset-readonly')
 
 // Parse arguments (skip 'route' and 'update' from argv)
 const args = process.argv.slice(4)
@@ -18,6 +20,29 @@ const fileName = positionalArgs[0]
 const pattern = positionalArgs[1]
 const newTarget = positionalArgs[2]
 
+/**
+ * Issue #145: rewrite only the line(s) holding this pattern. The rule keeps its
+ * own `!exclusions` unless new ones are given in the pattern argument; every
+ * other line keeps its exact bytes.
+ */
+function applyUpdate(text) {
+  const { patterns, exclusions } = splitPatternArg(pattern)
+  if (patterns.length === 0) {
+    output.error('Missing required argument: <pattern>')
+    process.exit(1)
+  }
+  let next = text
+  for (const p of patterns) {
+    const result = updateRouteRule(next, { pattern: p, target: newTarget.trim(), exclusions: exclusions.length ? exclusions : undefined })
+    if (!result.found) {
+      output.error(`Pattern not found: ${pattern.trim()}`)
+      process.exit(1)
+    }
+    next = result.content
+  }
+  return next
+}
+
 async function run() {
   if (!fileName) {
     output.error('Missing required argument: <file>')
@@ -37,23 +62,11 @@ async function run() {
   const pat = pattern.trim()
   const tgt = newTarget.trim()
 
-  // Handle [marker] syntax for lookup
-  const bm = pat.match(/\[([^\]]+)\]/)
-  const internalKey = bm ? pat.replace(bm[0], bm[1]) : pat
-
   if (running) {
     try {
       let content = await apiGet(`/api/rule-files/${encodeURIComponent(fileName)}/content`)
       const text = typeof content === 'string' ? content : String(content)
-      const ruleMap = parseEprc(text)
-
-      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-        output.error(`Pattern not found: ${pat}`)
-        process.exit(1)
-      }
-
-      ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyUpdate(text)
       await apiPut(`/api/rule-files/${encodeURIComponent(fileName)}/content`, { content: newContent })
 
       if (jsonFlag) {
@@ -65,6 +78,8 @@ async function run() {
       output.success(`${pat} -> ${tgt}`)
       output.kv('File', fileName)
     } catch (e) {
+      // Issue #137: a locked ruleset is a final answer, never a cue to write the file directly.
+      if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
       // Fallback to file mode
       const content = getRuleFileContent(fileName)
       if (!content) {
@@ -72,14 +87,7 @@ async function run() {
         process.exit(1)
       }
 
-      const ruleMap = parseEprc(content)
-      if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-        output.error(`Pattern not found: ${pat}`)
-        process.exit(1)
-      }
-
-      ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
-      const newContent = ruleMapToEprcText(ruleMap)
+      const newContent = applyUpdate(content)
       saveRuleFileContent(fileName, newContent)
       output.warnFileOnlyMode()
 
@@ -104,14 +112,7 @@ async function run() {
       process.exit(1)
     }
 
-    const ruleMap = parseEprc(content)
-    if (!Object.prototype.hasOwnProperty.call(ruleMap, internalKey)) {
-      output.error(`Pattern not found: ${pat}`)
-      process.exit(1)
-    }
-
-    ruleMap[internalKey] = bm ? tgt + bm[0] : tgt
-    const newContent = ruleMapToEprcText(ruleMap)
+    const newContent = applyUpdate(content)
     saveRuleFileContent(fileName, newContent)
     output.warnFileOnlyMode()
 
@@ -131,6 +132,7 @@ async function run() {
 }
 
 run().catch(e => {
+  if (isRulesetReadonlyError(e)) exitRulesetReadonly(e, { json: jsonFlag, ruleFile: fileName })
   output.error(e.message)
   process.exit(1)
 })

package/bin/lib/api-client.js

@@ -25,14 +25,26 @@ async function apiRequest(method, pathname, body, timeoutMs = DEFAULT_TIMEOUT) {
 
   if (!response.ok) {
     const text = await response.text()
-    throw new Error(text || response.statusText)
+    const err = new Error(text || response.statusText)
+    err.status = response.status
+    // Structured errors (e.g. issue #137 RULESET_READONLY) keep their code.
+    try {
+      const data = JSON.parse(text)
+      if (data && typeof data === 'object') {
+        if (typeof data.code === 'string') err.code = data.code
+        if (typeof data.ruleFile === 'string') err.ruleFile = data.ruleFile
+      }
+    } catch (_) {}
+    throw err
   }
 
   const contentType = response.headers.get('content-type')
   if (contentType && contentType.includes('application/json')) {
     return response.json()
   }
-  return response.text()
+  // Issue #145: `Response.text()` strips a leading UTF-8 BOM, so a rule file
+  // read and written back through the API would silently lose it.
+  return new TextDecoder('utf-8', { ignoreBOM: true }).decode(await response.arrayBuffer())
 }
 
 /**

package/bin/lib/file-access.js

@@ -5,6 +5,7 @@
 const fs = require('fs')
 const path = require('path')
 const { meddleDir } = require('./proxy-detect')
+const { RulesetReadonlyError } = require('./ruleset-readonly')
 
 const routeRulesDir = path.join(meddleDir, 'route-rules')
 const settingsPath = path.join(meddleDir, 'settings.json')
@@ -51,6 +52,33 @@ function setActiveRuleFileNames(names) {
   saveSettings(settings)
 }
 
+/**
+ * Issue #137: locked rule files (settings.json `readonlyRuleFiles`). Entries
+ * whose file no longer exists are dropped silently. A missing field = none locked.
+ */
+function getReadonlyRuleFileNames() {
+  const settings = loadSettings()
+  if (!Object.prototype.hasOwnProperty.call(settings, 'readonlyRuleFiles')) return []
+  const raw = settings.readonlyRuleFiles
+  const names = Array.isArray(raw) ? raw.filter((n, i, arr) => typeof n === 'string' && n && arr.indexOf(n) === i) : []
+  const live = names.filter((name) => fs.existsSync(path.join(routeRulesDir, `${name}.txt`)))
+  if (!Array.isArray(raw) || live.length !== raw.length) {
+    settings.readonlyRuleFiles = live
+    saveSettings(settings)
+  }
+  return live
+}
+
+function isRuleFileReadonly(name) {
+  const fold = (n) => (process.platform === 'darwin' || process.platform === 'win32' ? n.toLowerCase() : n)
+  return getReadonlyRuleFileNames().some((item) => fold(item) === fold(name))
+}
+
+/** Throws RulesetReadonlyError (code RULESET_READONLY) for a locked rule file. */
+function assertRuleFileWritable(name) {
+  if (isRuleFileReadonly(name)) throw new RulesetReadonlyError(name)
+}
+
 // ========== Mocks ==========
 
 /**
@@ -217,6 +245,7 @@ function listRuleFiles() {
     .map(f => f.replace(/\.txt$/, ''))
 
   const ordered = resolveRuleFileOrder(files, getRuleFileOrderNames(), activeNames)
+  const readonlyNames = new Set(getReadonlyRuleFileNames())
 
   return ordered.map(name => {
     const filePath = getRuleFilePath(name)
@@ -234,6 +263,7 @@ function listRuleFiles() {
     return {
       name,
       enabled: activeNames.includes(name),
+      readonly: readonlyNames.has(name),
       ruleCount,
       excludeCount
     }
@@ -258,6 +288,7 @@ function getRuleFileContent(name) {
  */
 function saveRuleFileContent(name, content) {
   ensureRouteRulesDir()
+  assertRuleFileWritable(name)
   const filePath = getRuleFilePath(name)
   fs.writeFileSync(filePath, content, 'utf8')
 }
@@ -274,6 +305,8 @@ function createRuleFile(name, content = '', enabled = true) {
     throw new Error(`规则文件 "${safeName}" 已存在`)
   }
 
+  // Drop stale lock entries so a new file never inherits an old lock.
+  getReadonlyRuleFileNames()
   fs.writeFileSync(filePath, content, 'utf8')
 
   if (enabled) {
@@ -285,7 +318,7 @@ function createRuleFile(name, content = '', enabled = true) {
   }
 
   const ruleCount = content.trim() ? Object.keys(parseEprc(content)).length : 0
-  return { name: safeName, enabled, ruleCount }
+  return { name: safeName, enabled, readonly: false, ruleCount }
 }
 
 /**
@@ -296,6 +329,7 @@ function deleteRuleFile(name) {
   if (!fs.existsSync(filePath)) {
     throw new Error('规则文件不存在')
   }
+  assertRuleFileWritable(name)
   fs.unlinkSync(filePath)
 
   const activeNames = getActiveRuleFileNames()
@@ -317,6 +351,7 @@ function setRuleFileEnabled(name, enabled) {
 
   const activeNames = getActiveRuleFileNames()
   const idx = activeNames.indexOf(name)
+  if ((enabled && idx === -1) || (!enabled && idx !== -1)) assertRuleFileWritable(name)
 
   if (enabled && idx === -1) {
     activeNames.push(name)
@@ -352,6 +387,9 @@ module.exports = {
   saveSettings,
   getActiveRuleFileNames,
   setActiveRuleFileNames,
+  getReadonlyRuleFileNames,
+  isRuleFileReadonly,
+  assertRuleFileWritable,
 
   // Mocks
   getMocksPath,