Sanguok | 山月修改

:root {
  --obsidian-text: var(--vscode-editor-foreground, #2a2a2a);
  --obsidian-bg: var(--vscode-editor-background, #ffffff);
  --obsidian-muted: var(--vscode-descriptionForeground, #6b7280);
  --obsidian-link: var(--vscode-textLink-foreground, #5b7db1);
  --obsidian-border: var(--vscode-panel-border, #d7dce3);
  --obsidian-code-bg: var(--vscode-textCodeBlock-background, #f5f7fa);
}

body {
  margin: 0 auto;
  max-width: 860px;
  background: var(--obsidian-bg);
  color: var(--obsidian-text);
  font-family: "Source Han Sans", "Source Han Sans HC", "Source Han Sans TC",
    "Source Han Sans JP", sans-serif;
  line-height: 1.75;
}

code,
pre,
kbd,
samp {
  font-family: Consolas, "Cascadia Code", monospace;
}

a {
  color: var(--obsidian-link);
  text-decoration-thickness: 1px;
  text-underline-offset: 2px;
}

img,
video,
audio {
  max-width: 100%;
}

blockquote {
  margin-left: 0;
  padding-left: 1rem;
  border-left: 3px solid var(--obsidian-border);
  color: var(--obsidian-muted);
}

pre,
code {
  background: var(--obsidian-code-bg);
}

pre {
  padding: 0.9rem 1rem;
  border-radius: 8px;
}

table {
  border-collapse: collapse;
}

th,
td {
  border: 1px solid var(--obsidian-border);
  padding: 0.5rem 0.75rem;
}

{
  "markdown.updateLinksOnFileMove.enabled": "always",
  "markdown.copyFiles.destination": {
    "/**/*.md": "_resources/"
  },
  "markdown.preview.scrollEditorWithPreview": true,
  "markdown.preview.scrollPreviewWithEditor": true,
  "markdown.styles": [
    ".vscode/obsidian-preview.css"
  ],
  "foam.files.exclude": [
    ".venv/**/*",
    ".vscode/**/*",
    ".git/**/*",
    "node_modules/**/*",
    "**/desktop.ini",
    "**/.DS_Store"
  ],
  "foam.files.newNotePath": "currentDir",
  "foam.templates.folder": "Templates",
  "foam.links.sync.enable": true,
  "foam.links.hover.enable": true,
  "markdown-preview-enhanced.enableWikiLinkSyntax": true,
  "markdown-preview-enhanced.useGitHubStylePipedLink": false,
  "markdown-preview-enhanced.wikiLinkTargetFileExtension": ".md",
  "markdown-preview-enhanced.scrollSync": true,
  "markdown-preview-enhanced.automaticallyShowPreviewOfMarkdownBeingEdited": true,
  "markdown-preview-enhanced.enableHTML5Embed": true,
  "markdown-preview-enhanced.HTML5EmbedUseImageSyntax": true,
  "markdown-image.base.uploadMethod": "Local",
  "markdown-image.local.path": "_resources",
  "markdown-image.local.referencePath": "",
  "[markdown]": {
    "editor.wordWrap": "on",
    "files.trimTrailingWhitespace": false
  }
}

這裡有兩點需要特別說明：

• markdown.copyFiles.destination控制拖放或複製附件時，VS Code內建Markdown功能使用的附件目錄。
• markdown-image.local.path控制Markdown Image貼圖時的儲存位置。本文使用_resources，表示圖片儲存在當前Markdown檔同級的_resources目錄。若你想改成工作區根目錄的統一附件倉，應寫成/_resources。

可選：修正Markdown Preview Enhanced中的代碼塊背景

如果你在Markdown Preview Enhanced中採用none.css之類較少干預的預覽主題，有時會遇到fenced code block背景不一致，出現整塊底色與局部小底色混在一起的情況。這時可在工作區根目錄建立.crossnote/style.less：

.markdown-preview.markdown-preview pre {
  background: var(--vscode-textCodeBlock-background, #1f252d) !important;
}

.markdown-preview.markdown-preview pre code,
.markdown-preview.markdown-preview pre code *,
.markdown-preview.markdown-preview pre tt,
.markdown-preview.markdown-preview pre tt * {
  background: transparent !important;
  box-shadow: none !important;
}

這份樣式只影響pre中的程式碼，不會改動行內code。

可選：保留Markdown Preview Enhanced的主題選擇在使用者層

若你希望Markdown Preview Enhanced正文不額外套主題，而是盡量跟隨VS Code本身的明暗風格，可以把這類偏好放在使用者自己的settings.json中，而不要寫進工作區：

{
  "markdown-preview-enhanced.previewTheme": "none.css",
  "markdown-preview-enhanced.codeBlockTheme": "github-dark.css"
}

這屬於個人閱讀偏好，不屬於專案必需配置。

需按自己情況調整的項目

• 附件目錄：如果你的Obsidian附件規則不是當前檔案同級的_resources，就同步修改markdown.copyFiles.destination與markdown-image.local.path。
• 模板目錄：如果你的模板資料夾不是Templates，就調整foam.templates.folder。
• 忽略規則：foam.files.exclude應按自己的vault與工作區結構增刪，不必照抄。
• 貼圖插件：如果你使用Paste Image，就把文中的markdown-image.*配置換成對應的pasteImage.*鍵；若已切到Markdown Image，記得清理舊的pasteImage.*殘留設定。
• 預覽字體：如果你不想指定字體，可刪除obsidian-preview.css中的font-family。

啟用方式

1. 在命令面板執行Developer: Reload Window。
2. 打開任意Markdown檔案，使用Markdown Preview Enhanced: Open Preview to the Side作為主要預覽窗格。
3. 測試一次wikilink跳轉、圖片貼上與多媒體引用，確認附件路徑與預覽結果符合自己的Obsidian習慣。

完成後，VS Code即可在編輯、預覽與附件管理上提供一套接近Obsidian的Markdown工作流，同時保留VS Code本身的擴充能力與由Git驅動的版本管理環境。

本文介绍如何在Windows环境（笔者用的是Python 3.13 Microsoft Store版）安装Zotero MCP并配置给LM Studio使用。

前置准备

需要安装以下软件：

• Zotero 7+
• LM Studio 0.3.17+
• Python 3.10+

开启Zotero本地API

Zotero默认关闭此功能，需手动开启。

1. 打开Zotero，进入 Edit > Preferences。
2. 在 Advanced 标签页下，勾选 “Allow other applications on this computer to communicate with Zotero”。

安装Zotero MCP

在终端运行安装命令。

使用uv（官方推荐）：

# 如果尚未安装 uv
pip install uv

# 安装 zotero-mcp
uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"

或使用pip：

pip install -U "git+https://github.com/54yyyu/zotero-mcp.git"

安装后若提示"The script zotero-mcp.exe is installed in ... which is not on PATH"，说明系统无法直接识别命令。复制提示信息中zotero-mcp.exe的完整路径（例如：C:\Users\[用户名]\AppData\...\Scripts\zotero-mcp.exe），后续配置需要用到。

配置LM Studio

打开LM Studio，点击+ Install以打开mcp.json。在 mcpServers 字段中加入以下配置：

{
  "mcpServers": {
    "zotero": {
      "command": "C:\\Users\\[你的用户名]\\AppData\\...\\Scripts\\zotero-mcp.exe",
      "args": [],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

• command：填入上一步获取的zotero-mcp.exe绝对路径。JSON中路径的反斜杠需写作双斜杠\\。
• env：ZOTERO_LOCAL设为true以启用本地全文检索支持。

验证与使用

1. 在LM Studio加载支持Tool Use的模型（如Llama 3.1 8B Instruct或Qwen 2.5）。
2. 确认MCP装载。
3. 输入测试指令，如：“Find the most recent paper I added to my library.”

启用语义搜索（可选）

默认仅支持关键词搜索。如需语义检索，需手动建立索引。

在命令提示符使用完整路径运行update-db命令（路径请按实际情况替换）：

C:\Users\[你的用户名]\AppData\...\Scripts\zotero-mcp.exe update-db

此指南适用于开发环境或通过Git管理的生产环境。Docker环境可用。

核心概念

MCP Adapter既可以作为Composer库被其他插件引用（推荐），也可以作为独立插件运行。

• 依赖管理：该插件不包含vendor目录（第三方库），必须在本地通过Composer生成。
• 运行环境：需要PHP 7.4+和WordPress 6.8+。

首次安装流程

步骤A：下载源码

进入WordPress的插件目录并克隆仓库：

cd /path/to/wp-content/plugins/
git clone https://github.com/WordPress/mcp-adapter.git
cd mcp-adapter

步骤B：安装依赖

此步骤用于生成vendor/autoload.php文件。若跳过此步，插件将无法运行。

Docker环境下的命令：

docker run --rm \
    -v $(pwd):/app \
    composer install

会下载wordpress/abilities-api等核心依赖并生成自动加载映射。

步骤C：激活插件

# 使用 WP-CLI 或在后台激活
wp plugin activate mcp-adapter

HTTPS协议一致性

配置WP_API_URL时，必须严格匹配站点的实际协议。

• ❌ 错误做法：站点强制 HTTPS，但填写http://yousite.com/...
• ✅ 正确做法：填写https://yousite.com/...

如果站点强制使用 HTTPS（生产环境标准配置），而在配置中填写了http://，WordPress或服务器（Nginx/Apache）会返回一个301 Redirect跳转到HTTPS。在这个跳转过程中，出于安全规范，客户端发送的Authorization标头（包含密码）通常会被丢弃。这将导致请求虽然到达了最终地址，但因丢失凭据而报401 Unauthorized错误。

后续更新流程

由于插件通过Git安装，勿使用WordPress后台的“更新”按钮，以免覆盖Git配置。应按照以下步骤进行更新：

第一步：同步代码

获取最新的功能和修复：

cd /path/to/wp-content/plugins/mcp-adapter
git pull origin trunk

第二步：同步依赖

代码更新可能包含依赖包版本的变化（composer.lock变更）。每次git pull后运行：

docker run --rm \
    -v $(pwd):/app \
    composer install

如果跳过此步，可能会因为缺少新引入的类文件导致网站出现Fatal Error。

常见问题

• Plugin could not be activated (Fatal Error):
  • 原因：忘记执行composer install，导致vendor/autoload.php缺失。
  • 解决：重新执行安装流程中的步骤B。
• 类名冲突:
  • 原因：如果有多个插件都使用了MCP Adapter。
  • 解决：文档建议使用Jetpack Autoloader来解决多版本冲突（composer require automattic/jetpack-autoloader），但在单插件模式下非必须。
• API 404 错误:
  • 解决：确保WordPress的固定链接（Permalinks）设置不是“朴素 (Plain)”，需要设置为“文章名 (Post name)”或其他结构。
• API 401 错误 (Unauthorized):
  • 现象：MCP error -32603: WordPress API error (401)，且确认密码无误。
  • 解决：检查mcp.json中的WP_API_URL是否误写为了http://。将其修改为https://以避免重定向导致的凭据丢失。

核心概念：所有权 > 权限

在Linux中，权限（755/644）必须配合正确的所有权（User:Group）才能生效。换言之，PHP进程（即WordPress）必须是文件/目录的“所有者”，才能在755/644权限下进行写入（上传图片、升级插件、生成缓存）。

标准化操作流程

确保位于WordPress根目录（通常为/var/www/html或public_html）下执行。

第一步：修正所有权

对当前目录下所有文件的所有者和组，行统一之设定。兹以33 (www-data) 为例（后文同此）。

chown -R 33:33 .

第二步：批量重置目录权限

按：使用+模式代替\;可显著提高执行效率。

find . -type d -exec chmod 755 {} +

第三步：批量重置文件权限

find . -type f -exec chmod 644 {} +

第四步：关键文件安全加固

针对敏感文件设置更严格的只读权限。

# wp-config.php 包含数据库密码，生产环境应设为 440 或 400
# 前提：文件所有者必须是 PHP 运行用户，否则设为 400 后 PHP 无法读取将导致网站无法访问
chmod 440 wp-config.php

# .htaccess 控制伪静态，通常设为 644，若不频繁修改可设为 604
chmod 644 .htaccess

针对部分具体插件的特殊分析

按，任何要求设置777权限的插件通常都存在设计缺陷与安全隐患。

但在应用上述“严格权限”时，以下插件模块可能会遇到权限阻碍：

缓存类：Super Cache (超级缓存)

该插件需要向wp-config.php写入开启缓存的定义代码，并修改.htaccess。当wp-config.php被设置为440时，插件后台更新设置会报错或白屏。是故，作为运维策略：

1. 配置/更新插件前：chmod 644 wp-config.php
2. 完成配置后：chmod 440 wp-config.php

按：日常运行中，插件生成的静态文件在wp-content/cache，该目录保持755即可正常读写。

翻译与本地化：Loco Translate

插件直接写入wp-content/languages目录生成.po/.mo文件。

只要第一步的chown -R 33:33 .执行正确，标准755目录权限即可满足需求。如果无法保存翻译，通常是所有者变成了别的（例如：在www-data才OK的情况下，所有者却变为了root）。

联邦宇宙与导入类 (ActivityPub, Import/Export)

• 依赖：wp-content/uploads。
• 注意：导入大型XML/CSV或处理ActivityPub媒体流时，会产生临时文件。
• 排查：如果导入失败或头像不显示，通过ls -ld wp-content/uploads检查权限是否为drwxr-xr-x (755)且所有者为www-data。

另外，像WP File Manager这样的插件，虽然对于共享主机用户来说非常地便利，但其风险其实极高。如果该插件存在0-day漏洞，攻击者可绕过WordPress权限体系，直接以www-data身份操作服务器文件（上传Webshell），此时440或644设置将失效。对于自托管用户来说，如已经拥有SSH命令行权限，该插件会增加不必要的攻击面。不如卸载。

常见故障排查清单

1. 错误：440导致某些环境白屏

   如果服务器使用的不是PHP-FPM (User: www-data) 而是以CGI模式运行（User: 系统账户），将wp-config.php设为440且所有者为www-data（或33）可能导致文件无法被读取，引发HTTP 500错误。

   • 验证：执行完命令后，如果网站正常访问，说明配置正确。

2. 插件更新失败 / 无法创建目录

   • 现象：后台提示“无法创建目录”。
   • 原因：通常不是权限问题（755是对的），而是所有权问题。
   • 复查：运行ls -ld wp-content/plugins，确保输出包含www-data www-data（或33 33）。如果显示的是root root，插件将无法更新。

3. Git/开发环境

   如使用Git管理代码，.git目录的权限不要设置为755/644，且不应允许Web访问。宜在Nginx/Apache配置中显式禁止访问.git目录。

推荐操作脚本

确认在WordPress根目录后，按顺序执行：

# 1. 修正所有权 (兹以www-data为例，即id 33)
chown -R 33:33 .

# 2. 修正目录权限
find . -type d -exec chmod 755 {} +

# 3. 修正文件权限
find . -type f -exec chmod 644 {} +

# 4. 加固配置文件 (注意：配置 Super Cache 插件时可能需临时改为 640/644)
chmod 440 wp-config.php

# 5. 确保 .htaccess 对 WP 可写但安全
chmod 644 .htaccess