docs: add release guide for VS Code and Obsidian publishing

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: CoderJackZhu

docs/发布指南.md

@@ -0,0 +1,211 @@
+# MindDoc 发布指南
+
+## 概述
+
+MindDoc 有两个发布渠道，各自独立版本管理：
+
+| 平台 | 包名 | Tag 格式 | 发布目标 |
+|------|------|----------|----------|
+| VS Code | `vscode-minddoc` | `vscode-v0.1.0` | VS Code Marketplace |
+| Obsidian | `minddoc` | `obsidian-v0.1.0` | Obsidian 社区插件 |
+
+---
+
+## 前置准备（只需做一次）
+
+### VS Code Marketplace
+
+1. **注册 Azure DevOps 组织**
+   - 访问 https://dev.azure.com
+   - 创建一个组织（Organization）
+
+2. **创建 Personal Access Token (PAT)**
+   - 进入组织 → User Settings → Personal Access Tokens
+   - Name: `vsce-publish`
+   - Scopes: 选择 **Marketplace > Manage**（勾选所有 Marketplace 权限）
+   - 记录生成的 token
+
+3. **创建 Publisher**
+   - 访问 https://marketplace.visualstudio.com/manage
+   - Create Publisher → ID 填 `minddoc`（必须与 package.json 中的 `publisher` 字段一致）
+
+4. **配置 GitHub Secrets**
+   - 仓库 Settings → Secrets and variables → Actions
+   - 添加 `VSCE_PAT`，值为上面创建的 PAT
+
+5. **本地登录（可选，用于手动发布）**
+   ```bash
+   npm install -g @vscode/vsce
+   vsce login minddoc
+   # 输入 PAT
+   ```
+
+### Obsidian 社区插件
+
+1. **确保仓库公开** — https://github.com/CoderJackZhu/MindDoc 设为 Public
+
+2. **首次提交到社区插件列表**
+   ```bash
+   # Fork https://github.com/obsidianmd/obsidian-releases
+   # 编辑 community-plugins.json，在数组末尾添加：
+   ```
+   ```json
+   {
+     "id": "minddoc",
+     "name": "MindDoc",
+     "author": "Jack Zhu",
+     "description": "Markdown-first structured outline editor with mind map view",
+     "repo": "CoderJackZhu/MindDoc"
+   }
+   ```
+   ```bash
+   # 提交 PR 到 obsidian-releases 仓库
+   # 审核周期：1-4 周
+   ```
+
+3. **审核要求**
+   - 不使用 `eval()` 或动态代码加载
+   - 无未说明的网络请求
+   - README 有使用说明
+   - manifest.json 中 minAppVersion 合理
+
+---
+
+## 日常发布流程
+
+### 发布 VS Code 扩展
+
+```bash
+# 1. 确保代码就绪
+pnpm build
+pnpm test
+
+# 2. 更新版本号（自动修改 package.json）
+pnpm release:vscode 0.2.0
+
+# 3. 提交并打 tag
+git add -A
+git commit -m "release(vscode): v0.2.0"
+git tag vscode-v0.2.0
+
+# 4. 推送（CI 自动发布到 Marketplace）
+git push origin main vscode-v0.2.0
+```
+
+**手动发布（备用）：**
+```bash
+cd packages/vscode
+pnpm build
+vsce publish --no-dependencies
+```
+
+**本地测试 VSIX：**
+```bash
+cd packages/vscode
+vsce package --no-dependencies
+# 产出 vscode-minddoc-x.x.x.vsix
+code --install-extension vscode-minddoc-0.2.0.vsix
+```
+
+### 发布 Obsidian 插件
+
+```bash
+# 1. 确保代码就绪
+pnpm build
+pnpm test
+
+# 2. 更新版本号（自动修改 manifest.json + versions.json + package.json）
+pnpm release:obsidian 0.2.0
+
+# 3. 提交并打 tag
+git add -A
+git commit -m "release(obsidian): v0.2.0"
+git tag obsidian-v0.2.0
+
+# 4. 推送（CI 自动创建 GitHub Release 并上传构建产物）
+git push origin main obsidian-v0.2.0
+```
+
+GitHub Release 会自动包含：`main.js`、`manifest.json`、`styles.css`
+
+Obsidian 客户端会自动检测新 Release 并提示用户更新。
+
+**本地测试：**
+```bash
+pnpm --filter @minddoc/obsidian build
+
+# 将产物复制到测试 vault
+cp packages/obsidian/main.js <vault>/.obsidian/plugins/minddoc/
+cp packages/obsidian/manifest.json <vault>/.obsidian/plugins/minddoc/
+cp packages/obsidian/styles.css <vault>/.obsidian/plugins/minddoc/
+
+# 在 Obsidian 中重载插件
+```
+
+---
+
+## 同时发布两个平台
+
+如果两个平台同时更新：
+
+```bash
+pnpm build && pnpm test
+
+pnpm release:vscode 0.2.0
+pnpm release:obsidian 0.2.0
+
+git add -A
+git commit -m "release: v0.2.0 (vscode + obsidian)"
+git tag vscode-v0.2.0
+git tag obsidian-v0.2.0
+
+git push origin main vscode-v0.2.0 obsidian-v0.2.0
+```
+
+---
+
+## 版本号约定
+
+遵循 [Semantic Versioning](https://semver.org/)：
+
+- `0.x.y` — 早期开发阶段，API 可能变动
+- patch (0.1.1) — bug 修复
+- minor (0.2.0) — 新功能，向后兼容
+- major (1.0.0) — 稳定版，API 不再随意变动
+
+两个平台版本号独立管理，可以不同步。
+
+---
+
+## CI/CD 工作流说明
+
+| 文件 | 触发条件 | 作用 |
+|------|----------|------|
+| `.github/workflows/ci.yml` | push/PR to main | typecheck + test + build |
+| `.github/workflows/release-vscode.yml` | tag `vscode-v*` | 构建并发布到 Marketplace |
+| `.github/workflows/release-obsidian.yml` | tag `obsidian-v*` | 构建并创建 GitHub Release |
+
+---
+
+## 故障排除
+
+### vsce publish 失败
+
+- **"Personal Access Token has expired"** → 重新创建 PAT 并更新 GitHub Secret
+- **"Publisher 'minddoc' not found"** → 去 https://marketplace.visualstudio.com/manage 创建
+- **依赖报错** → 确保使用 `--no-dependencies`（所有依赖已被 esbuild 打包进 dist）
+
+### Obsidian Release 未被检测
+
+- 确认 tag 格式正确：`obsidian-v0.2.0`
+- 确认 Release 中包含 `main.js` 和 `manifest.json`
+- 确认 `manifest.json` 中 version 与 tag 一致
+
+### 图标问题
+
+VS Code Marketplace 要求：
+- 格式：PNG
+- 尺寸：128x128 像素
+- 路径：`packages/vscode/assets/icon.png`
+
+当前使用占位图标，正式发布前替换为设计稿。