feat(mcp): allowlist EXTRA merges with default; add Trilium keys to default

Co-authored-by: Cursor <cursoragent@cursor.com>

_local/system.env.example

@@ -184,9 +184,11 @@ AIA_LOCAL_ADAPTER_STARTUP_SELF_CHECK=1
 # AIA_MCP_SPECIALISTS    允许使用 MCP 的专家角色列表，逗号分隔。
 AIA_MCP_SPECIALISTS=generalist,manager
 
-# AIA_MCP_ENV_ALLOWLIST    允许注入 MCP 子进程的环境变量名列表。
+# AIA_MCP_ENV_ALLOWLIST    允许注入 MCP 子进程的环境变量名列表（非空则整表替换内置默认，慎用）。
 # 【前端】管理后台可维护同名设置。
 AIA_MCP_ENV_ALLOWLIST=
+# AIA_MCP_ENV_ALLOWLIST_EXTRA    在默认名单（或未设置 AIA_MCP_ENV_ALLOWLIST 时的内置默认）之后追加的变量名，逗号分隔；不必重复抄写默认里的键。
+AIA_MCP_ENV_ALLOWLIST_EXTRA=
 
 # AIA_MCP_SQLITE_COMMAND    表格附件走 MCP 时的 sqlite 命令路径覆盖。
 AIA_TABULAR_USE_MCP=

docs/ENVIRONMENT_VARIABLES.md

@@ -232,8 +232,13 @@
   - 生效：`oclaw/tools/mcp/adapter.py`
 
 - `AIA_MCP_ENV_ALLOWLIST`
-  - 默认：内置 allowlist（Brave/Google/GitHub/Context7/DashScope）
+  - 默认：未设置时使用内置 allowlist（Brave/Google/GitHub/Context7/DashScope、Trilium MCP 等，见 `mcp_env._DEFAULT_ALLOWLIST`）
-  - 作用：MCP 子进程可透传环境变量白名单
+  - 作用：若**非空**，则整表替换内置默认（仅列出的名可传入 MCP 子进程）；用于刻意缩小暴露面
+  - 生效：`oclaw/runtime/operations/mcp_env.py`
+
+- `AIA_MCP_ENV_ALLOWLIST_EXTRA`（兼容 `OPS_MCP_ENV_ALLOWLIST_EXTRA`）
+  - 默认：空
+  - 作用：在「当前主列表」（内置默认，或 `AIA_MCP_ENV_ALLOWLIST` 替换后的列表）之后**追加**变量名，合并去重；新增第三方 MCP 时优先用此项，无需手抄整份默认名单
   - 生效：`oclaw/runtime/operations/mcp_env.py`
 
 - `AIA_MCP_FILESYSTEM_EXTRA_ROOTS`

docs/ENVIRONMENT_VARIABLES_CHANGELOG.md

@@ -64,8 +64,11 @@
 - `AIA_IMAGE_EXPERT_REQUEST_EXTRA`：图片专家顶层 JSON；旧名 **`AIA_LEGACY_IMAGE_REQUEST_EXTRA`** 仍作别名可读。
 - `DASHSCOPE_IMAGE_*`（零散变量）：由 `image_legacy_client` 映射为请求体顶层字段。
 - **`AIA_OCR_*`**（四项）：仅存 **`query_image_attachment` / OCR 降级** 链路；已与图片专家链路拆分。
+- `AIA_MCP_ENV_ALLOWLIST_EXTRA`（兼容 `OPS_MCP_ENV_ALLOWLIST_EXTRA`）：在默认主表或 `AIA_MCP_ENV_ALLOWLIST` 替换表之后追加 MCP 子进程可透传的变量名，合并去重，避免为单个 MCP 手抄整份默认名单。
+- 内置 MCP 环境透传默认名单增加 `TRILIUM_API_URL`、`TRILIUM_API_TOKEN`、`PERMISSIONS`、`VERBOSE`（[triliumnext-mcp](https://github.com/tan-yong-sheng/triliumnext-mcp)）。
 
 ### Changed
+- `mcp_env.mcp_env_allowlist_keys()`：除「`AIA_MCP_ENV_ALLOWLIST` 非空则整表替换内置默认」外，`EXTRA` 始终追加到当前主表之后。
 - `send_ocr_image_messages` 未配 `AIA_OCR_MODEL`（且未传 `model`）失败；图片专家 **`send_legacy_image_messages`** 首选 **用户所选会话/专家绑定的模型的 `model`/`base_url`/`api_key`**，缺省时再回落 **`AIA_IMAGE_EXPERT_*`**（不读取 `AIA_OCR_*`）；服务端若模型不支持看图则直接报错，不做备用 payload。
 
 ### Removed（OCR 通道）

docs/MCP_LOCAL_SERVER.md

@@ -505,13 +505,13 @@ Keep responses deterministic and JSON-serializable.
 
 - **作用**：按库名/版本拉取较新的官方文档片段，减少「API 记错版本」类幻觉。  
 - **安装**：`python scripts/install_mcp_context7.py`，或管理台 `POST /admin/api/mcp/install` 使用 [`examples/mcp_install_context7.json`](../examples/mcp_install_context7.json) 中的 `payload`。
-- **密钥**：在 **`oclaw/_local/mcp_local.env`**（推荐）或 `data/mcp_local.env`（兼容）设置 `CONTEXT7_API_KEY`（见 [context7.com/dashboard](https://context7.com/dashboard)）。两处都存在时**同键以 `oclaw/_local/mcp_local.env` 为准**（覆盖 `data` 中的同键）。未自定义 `OPS_MCP_ENV_ALLOWLIST` 时，网关默认 allowlist 已包含 `CONTEXT7_API_KEY`（见 `oclaw/runtime/operations/mcp_env.py`）；若你自定义了 allowlist，请手动追加该键。  
+- **密钥**：在 **`oclaw/_local/mcp_local.env`**（推荐）或 `data/mcp_local.env`（兼容）设置 `CONTEXT7_API_KEY`（见 [context7.com/dashboard](https://context7.com/dashboard)）。两处都存在时**同键以 `oclaw/_local/mcp_local.env` 为准**（覆盖 `data` 中的同键）。内置默认 allowlist 已包含 `CONTEXT7_API_KEY`（见 `oclaw/runtime/operations/mcp_env.py`）；若你用 **`AIA_MCP_ENV_ALLOWLIST` 整表替换**默认，须在该列表里显式保留 `CONTEXT7_API_KEY`，或改用 **`AIA_MCP_ENV_ALLOWLIST_EXTRA`** 只追加新变量名而不动默认集合。  
 - **装完后**：`Health` → `Sync Tools` → 将 `mcp-context7` 加入通识 specialist 的 MCP 绑定（若脚本已成功 Sync，会自动追加）。
 
 ### Bailian WebSearch（DashScope）
 
 - **密钥**：在 `oclaw/_local/mcp_local.env`（推荐）设置 `DASHSCOPE_API_KEY=...`。
-- **关键注意**：如果你自定义了 `AIA_MCP_ENV_ALLOWLIST` / `OPS_MCP_ENV_ALLOWLIST`，必须显式包含 `DASHSCOPE_API_KEY`，否则 MCP 子进程拿不到该密钥，常见表现是：
+- **关键注意**：若使用 **`AIA_MCP_ENV_ALLOWLIST` 整表替换**内置默认，须在该列表里显式包含 `DASHSCOPE_API_KEY`，否则 MCP 子进程拿不到该密钥。更省事的做法是：**不要设置** `AIA_MCP_ENV_ALLOWLIST`，只在 **`AIA_MCP_ENV_ALLOWLIST_EXTRA`** 里追加其它 MCP 需要的变量名（与默认名单自动合并）。常见表现是：
   - `error_code: mcp_runtime_empty_response`
   - `error: empty_response`
 - **排查顺序**：

runtime/operations/mcp_env.py

@@ -9,15 +9,40 @@ from oclaw.platform.config.paths import PROJECT_ROOT, db_path
 
 _DEFAULT_ALLOWLIST = (
     "BRAVE_API_KEY,GOOGLE_OAUTH_CREDENTIALS,GOOGLE_CALENDAR_MCP_TOKEN_PATH,"
-    "GITHUB_PERSONAL_ACCESS_TOKEN,CONTEXT7_API_KEY,DASHSCOPE_API_KEY"
+    "GITHUB_PERSONAL_ACCESS_TOKEN,CONTEXT7_API_KEY,DASHSCOPE_API_KEY,"
+    "TRILIUM_API_URL,TRILIUM_API_TOKEN,PERMISSIONS,VERBOSE"
 )
 
 
+def _split_csv_keys(raw: str) -> list[str]:
+    return [x.strip() for x in str(raw or "").split(",") if x.strip()]
+
+
+def _dedupe_preserve_order(keys: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for k in keys:
+        if k not in seen:
+            seen.add(k)
+            out.append(k)
+    return out
+
+
 def mcp_env_allowlist_keys() -> list[str]:
-    raw = str(os.getenv("AIA_MCP_ENV_ALLOWLIST") or "").strip()
+    """MCP 子进程可继承的环境变量名：主列表 + EXTRA 合并去重。
-    if not raw:
+
-        return [x.strip() for x in _DEFAULT_ALLOWLIST.split(",") if x.strip()]
+    - 未设置 ``AIA_MCP_ENV_ALLOWLIST``：主列表为内置默认（含常用 MCP 密钥名）。
-    return [x.strip() for x in raw.split(",") if x.strip()]
+    - 已设置：主列表仅为该项（完全替换默认），用于刻意缩小暴露面。
+    - ``AIA_MCP_ENV_ALLOWLIST_EXTRA``（或兼容 ``OPS_MCP_ENV_ALLOWLIST_EXTRA``）：
+      始终在主列表之后追加，避免为新增 MCP 手抄整份默认名单。
+    """
+    primary_raw = str(os.getenv("AIA_MCP_ENV_ALLOWLIST") or "").strip()
+    primary = _split_csv_keys(primary_raw) if primary_raw else _split_csv_keys(_DEFAULT_ALLOWLIST)
+    extra_raw = str(os.getenv("AIA_MCP_ENV_ALLOWLIST_EXTRA") or "").strip()
+    if not extra_raw:
+        extra_raw = str(os.getenv("OPS_MCP_ENV_ALLOWLIST_EXTRA") or "").strip()
+    extra = _split_csv_keys(extra_raw)
+    return _dedupe_preserve_order([*primary, *extra])
 
 
 def _parse_env_file(path: Path) -> dict[str, str]:

tests/test_mcp_adapter.py

@@ -159,6 +159,9 @@ class McpAdapterTests(unittest.TestCase):
         from oclaw.runtime.operations import mcp_env
 
         old = os.environ.pop("OPS_MCP_ENV_ALLOWLIST", None)
+        old_aia = os.environ.pop("AIA_MCP_ENV_ALLOWLIST", None)
+        old_extra = os.environ.pop("AIA_MCP_ENV_ALLOWLIST_EXTRA", None)
+        old_ops_extra = os.environ.pop("OPS_MCP_ENV_ALLOWLIST_EXTRA", None)
         try:
             keys = mcp_env.mcp_env_allowlist_keys()
             self.assertIn("GOOGLE_OAUTH_CREDENTIALS", keys)
@@ -167,9 +170,58 @@ class McpAdapterTests(unittest.TestCase):
             self.assertIn("GITHUB_PERSONAL_ACCESS_TOKEN", keys)
             self.assertIn("CONTEXT7_API_KEY", keys)
             self.assertIn("DASHSCOPE_API_KEY", keys)
+            self.assertIn("TRILIUM_API_TOKEN", keys)
         finally:
             if old is not None:
                 os.environ["OPS_MCP_ENV_ALLOWLIST"] = old
+            if old_aia is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST"] = old_aia
+            if old_extra is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST_EXTRA"] = old_extra
+            if old_ops_extra is not None:
+                os.environ["OPS_MCP_ENV_ALLOWLIST_EXTRA"] = old_ops_extra
+
+    def test_mcp_env_allowlist_extra_merges_with_default(self) -> None:
+        from oclaw.runtime.operations import mcp_env
+
+        old_aia = os.environ.pop("AIA_MCP_ENV_ALLOWLIST", None)
+        old_extra = os.environ.pop("AIA_MCP_ENV_ALLOWLIST_EXTRA", None)
+        old_ops_extra = os.environ.pop("OPS_MCP_ENV_ALLOWLIST_EXTRA", None)
+        try:
+            os.environ["AIA_MCP_ENV_ALLOWLIST_EXTRA"] = "MY_CUSTOM_MCP_SECRET,CONTEXT7_API_KEY"
+            keys = mcp_env.mcp_env_allowlist_keys()
+            self.assertIn("BRAVE_API_KEY", keys)
+            self.assertIn("CONTEXT7_API_KEY", keys)
+            self.assertIn("MY_CUSTOM_MCP_SECRET", keys)
+            self.assertEqual(keys.index("MY_CUSTOM_MCP_SECRET"), len(keys) - 1)
+        finally:
+            if old_aia is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST"] = old_aia
+            if old_extra is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST_EXTRA"] = old_extra
+            if old_ops_extra is not None:
+                os.environ["OPS_MCP_ENV_ALLOWLIST_EXTRA"] = old_ops_extra
+
+    def test_mcp_env_allowlist_explicit_replace_plus_extra(self) -> None:
+        from oclaw.runtime.operations import mcp_env
+
+        old_aia = os.environ.pop("AIA_MCP_ENV_ALLOWLIST", None)
+        old_extra = os.environ.pop("AIA_MCP_ENV_ALLOWLIST_EXTRA", None)
+        try:
+            os.environ["AIA_MCP_ENV_ALLOWLIST"] = "ONLY_A,ONLY_B"
+            os.environ["AIA_MCP_ENV_ALLOWLIST_EXTRA"] = "ONLY_B,ONLY_C"
+            keys = mcp_env.mcp_env_allowlist_keys()
+            self.assertEqual(keys, ["ONLY_A", "ONLY_B", "ONLY_C"])
+            self.assertNotIn("BRAVE_API_KEY", keys)
+        finally:
+            if old_aia is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST"] = old_aia
+            else:
+                os.environ.pop("AIA_MCP_ENV_ALLOWLIST", None)
+            if old_extra is not None:
+                os.environ["AIA_MCP_ENV_ALLOWLIST_EXTRA"] = old_extra
+            else:
+                os.environ.pop("AIA_MCP_ENV_ALLOWLIST_EXTRA", None)
 
     def test_materialize_bailian_webparser_compat_tool(self) -> None:
         with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as td: