update at 2026-04-21 18:00:42

README.md

@@ -218,8 +218,67 @@ c=+-sqrt(a^2+b^2)
 本仓库提供多种构建选项：
 - `npm run build`：生成未混淆的 `main.js`，便于调试和开发
 - `npm run build:obf`：生产模式启用 `javascript-obfuscator`，生成混淆后的 `main.js`
-- `./build.sh`：执行默认构建并同步到本地 Obsidian 插件目录
-- `./build.sh obf`：执行混淆构建后再进行同步
+- `npm run build:server`：编译 `server/` 下的 TypeScript 服务端代码
+- `./build.sh`：执行默认构建并同步到本地 Obsidian 插件目录；如果 `server/` 目录存在改动，会额外自动执行远端更新
+- `./build.sh obf`：执行混淆构建后再进行同步；如果 `server/` 目录存在改动，同样会自动执行远端更新
+
+### 📦 build.sh 行为说明
+
+- `build.sh` 会先构建插件并同步 `main.js`、`styles.css`、`manifest.json` 和 `assets/` 到本地 Obsidian 插件目录
+- 构建完成后，脚本会检查 `server/` 目录是否存在 Git 可见的变动，包括未跟踪的新文件
+- 检测到 `server/` 变动时，脚本会调用 `server/deploy.sh`，编译服务端并同步到远端服务器
+- 如果 `server/` 无变动，则跳过远端部署，仅完成本地插件同步
+
+使用 `build.sh` 自动更新远端前，请确保当前环境已具备 `server/deploy.sh` 依赖的 SSH 访问能力和远端部署权限。
+
+### 🔗 Obsidian 插件与 server 调用逻辑
+
+Note2Any 目前采用“Obsidian 插件前端 + 远端轻量 server”的方式工作，但 `server/` 并不是所有能力的统一后端，当前主要服务于微信公众号鉴权相关流程。
+
+**1. Obsidian 本地侧负责什么**
+
+- 插件运行在 Obsidian 客户端内，负责读取当前笔记、解析 Markdown、套用主题样式、生成预览 HTML
+- 图片扫描、封面选择、正文整理、复制到剪贴板等逻辑都在本地完成
+- 插件设置中的公众号列表 `wxInfo` 保存在 Obsidian 插件数据里，其中 `secret` 保存的是加密后的字符串，而不是明文
+
+**2. server 负责什么**
+
+仓库中的 `server/` 当前只实现了几类微信公众号相关接口：
+
+- `POST /v1/wx/encrypt`
+  用于把用户输入的公众号 `AppSecret` 加密后返回给插件保存
+- `POST /v1/wx/token`
+  用于接收插件传来的 `appid + 加密后的 secret`，在服务端解密后向微信官方接口申请 `access_token`
+- `GET /v1/wx/info/:authkey`
+  当前返回简单状态信息
+
+这部分逻辑的目的，是避免在插件本地长期保存明文 `AppSecret`，同时把“解密 secret 并换取 token”这一步放到远端完成。
+
+**3. 微信公众号发布时的实际调用链**
+
+调用链并不是“Obsidian -> server -> 微信”的全量代理，而是分两段：
+
+1. Obsidian 插件先调用远端 `server` 的 `/v1/wx/token` 获取 `access_token`
+2. 拿到 `access_token` 后，插件直接调用微信官方接口上传图片、上传封面、创建草稿
+
+也就是说：
+
+- `server` 负责“鉴权前置步骤”
+- 真正的素材上传和草稿发布，仍然是插件直接请求 `api.weixin.qq.com`
+
+**4. 典型流程**
+
+- 保存公众号配置时：
+  插件调用 `/v1/wx/encrypt`，把返回的 `SECRET...` 加密串写入本地设置
+- 测试公众号配置时：
+  插件调用 `/v1/wx/token`，验证当前 `appid/secret` 是否可正常换取 token
+- 发布公众号草稿时：
+  插件先调用 `/v1/wx/token`，再直接调用微信素材接口和草稿接口完成发布
+
+**5. 与其它功能的边界**
+
+- 小红书相关流程当前不依赖本仓库 `server/` 的 `/v1/wx/*` 接口
+- 数学公式等能力在插件里同样通过 `API_HOST` 访问远端接口，但这些接口不属于当前 `server/src/index.ts` 中实现的微信公众号代理范围
 
 ### 🏗️ 架构特性
 
@@ -651,5 +710,3 @@ https://www.bilibili.com/video/BV15XWVeEEJa/
 
 本项目基于相应许可证开源，详见项目仓库。
 
-
-