文档发布插件 (Cursor Plugin)

Cursor插件，用于在编辑器中一键发布项目文档到NextCloud。

插件用途

在项目开发过程中，需要编写和维护各种文档（设计文档、需求文档、技术文档、API文档等）。本插件解决以下问题：

问题场景：

📝 项目文档包含大量图片、附件，直接提交到Git会导致仓库体积膨胀
🔗 图片资源分散存储，文档中的引用链接难以维护
🌐 需要将文档发布到团队共享平台（NextCloud），方便查阅和分享
🔄 手动上传资源、发布文档，操作繁琐易出错
💻 需要在编写文档后切换到终端执行命令，打断工作流

解决方案：

✅ 在项目中创建 doc 目录，在Cursor中编写Markdown文档
✅ 图片、PDF等资源放在 assets 目录，使用相对路径引用
✅ 在Cursor中点击按钮或执行命令，自动上传资源和文档到NextCloud
✅ 文档自动发布到NextCloud，Git仓库只保留Markdown文本
✅ 无需切换终端，在编辑器内完成整个发布流程

支持的文档类型

📋 设计文档：架构设计、详细设计、数据库设计
📄 需求文档：需求规格、用户故事、功能说明
🔧 技术文档：技术方案、调研报告、最佳实践
🌐 API文档：接口文档、API规范
📚 开发文档：开发指南、部署文档、运维手册
📊 项目文档：项目计划、会议记录、总结报告

核心功能

🔄 自动上传 assets 目录下的资源文件到NextCloud
📚 自动发布Markdown原始文档到NextCloud（保持相对路径引用）
📁 按版本和服务自动创建目录结构
🖱️ Cursor编辑器内一键发布，无需切换终端
📊 实时显示上传进度和结果
📄 支持单个文档发布和批量目录发布两种模式
🔗 为资源文件创建NextCloud分享链接（可选查看）

工作流程

单个文档发布流程

flowchart TD
    A[在Cursor中编写Markdown] --> B[点击'发布当前文档'按钮]
    B --> C[读取插件配置]
    C --> D{配置是否完整?}
    D -->|否| E[提示配置错误]
    D -->|是| F[初始化NextCloud客户端]
    
    F --> G[获取当前文档路径]
    G --> H[扫描文档中的assets引用]
    
    H --> I{有引用资源?}
    I -->|否| J[跳过资源上传]
    I -->|是| K[创建NextCloud目标目录]
    
    K --> L[上传引用的资源文件]
    L --> M[为资源创建分享链接]
    M --> N[上传原始Markdown文档]
    J --> N
    
    N --> O[显示发布成功通知]
    O --> P[完成]
    
    style A fill:#e1f5e1
    style R fill:#e1f5e1
    style E fill:#ffe1e1

批量目录发布流程

flowchart TD
    A[选择文档目录] --> B[点击'批量发布目录'按钮]
    B --> C[读取插件配置]
    C --> D{配置是否完整?}
    D -->|否| E[提示配置错误]
    D -->|是| F[初始化NextCloud客户端]
    
    F --> G[扫描目录下所有.md文件]
    G --> H{发现Markdown文件?}
    H -->|否| I[提示无文档]
    H -->|是| J[收集assets目录所有资源]
    
    J --> K{有资源文件?}
    K -->|否| L[跳过资源上传]
    K -->|是| M[创建NextCloud目标目录]
    
    M --> N[批量上传所有资源]
    N --> O[批量创建分享链接]
    O --> P[批量上传原始Markdown文档]
    L --> P
    
    P --> Q{还有其他文档?}
    Q -->|是| P
    Q -->|否| R[显示批量发布统计]
    R --> S[完成]
    
    style A fill:#e1f5e1
    style U fill:#e1f5e1
    style E fill:#ffe1e1
    style I fill:#fff4e1

关键步骤：

在Cursor中编写文档
选择发布模式：
- 单个文档：快捷键 Cmd/Ctrl + Shift + U
- 批量目录：右键目录 -> "Publish Directory to NextCloud"
上传资源到NextCloud，生成公开分享链接
上传原始Markdown文档到NextCloud /Docs/{VERSION}/{SERVICE_NAME}/
在Cursor中显示发布结果

📚 文档

NextCloud 配置 - 详细配置说明
应用专用密码指南 - 如何获取应用专用密码
故障排查指南 - 常见问题解决方案
开发指南 - 开发、调试、测试
更新日志 - 版本记录

快速开始

⚠️ 重要前置步骤

1. 创建应用专用密码（必需）

NextCloud WebDAV API 必须使用应用专用密码，不能使用登录密码！

获取步骤：

登录 NextCloud 网页版
→ 头像 → 设置（Settings）
→ 安全（Security）
→ 应用密码（App passwords）
→ 输入名称（如：Cursor Doc Publisher）
→ 创建 → 复制密码（格式：xxxxx-xxxxx-xxxxx-xxxxx-xxxxx）

📖 详细图文教程：应用专用密码获取指南

2. 在 NextCloud 创建根目录

必须手动创建 basePath 目录：

登录 NextCloud → 文件 → 新建文件夹
创建你的团队目录（如：/Docs）

插件会自动创建 basePath 下的所有子目录。

3. 获取 WebDAV 文件空间地址（重要！）

很多用户的 WebDAV 地址与登录用户名不同，需要单独获取：

登录 NextCloud 网页版
→ 左下角点击 "文件设置"（齿轮图标）
→ 在设置面板左侧选择 "WebDAV"
→ 复制显示的 WebDAV 地址（如：https://your-domain/remote.php/dav/files/username_1234）

关键信息：

URL：从 WebDAV 地址中提取 NextCloud 服务器地址
Username：您的登录用户名（用于认证）
WebDAV文件空间用户名：WebDAV 地址中的最后部分（如 username_1234）

📖 详细说明：NextCloud 配置指南

第1步：安装插件

从 Cursor 插件市场搜索安装 "NextCloud Doc Publisher"

第2步：配置

Ctrl + , → 搜索 "NextCloud Doc Publisher"

必填项：
- NextCloud URL: https://your-nextcloud.com
- Username: your-username
- Password: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx  ← 使用应用专用密码！
- Base Path: /Docs  ← 刚才创建的目录
- Service Name: your-service
- Version: V1.0.0

可选项（企业环境可能需要）：
- WebDAV文件空间用户名: your-username_1234  ← 如果与登录用户名不同

⚠️ 重要说明：

Password 必须填写应用专用密码，不能填写登录密码！
如果 NextCloud 提示使用 username_数字 格式的 WebDAV 地址，请填写 WebDAV文件空间用户名

第3步：创建文档

doc/
└── test/
    ├── test.md
    └── assets/
        └── image.png

第4步：发布

打开 test.md → Ctrl + Shift + U

完成！文档会上传到：/Docs/V1.0.0/your-service/test.md

遇到问题？

✅ 执行测试连接：Ctrl + Shift + P → Test Connection
✅ 检查是否使用了应用专用密码（不是登录密码）
✅ 查看故障排查指南

详细使用

以在 base-server-service 项目中发布文档为例：

步骤1：在NextCloud创建文档根目录（已废弃，见上方快速开始）

登录NextCloud Web界面，创建文档存储目录：

进入"文件"页面
在根目录创建文件夹：Docs
设置适当的访问权限（可选）

/Docs/          # 文档根目录（需手动创建）

说明：

插件会自动创建版本和服务子目录，无需手动创建
如需使用其他目录名，可通过插件配置指定

步骤2：安装Cursor插件

方式一：从Cursor插件市场安装（推荐）

打开Cursor
按 Cmd/Ctrl + Shift + P 打开命令面板
输入 "Extensions: Install Extensions"
搜索 "NextCloud Doc Publisher"
点击 "Install"

方式二：从源码安装

# 克隆插件仓库
git clone https://github.com/your-org/cursor-doc-publish-plugin.git

# 安装到Cursor
cd cursor-doc-publish-plugin
npm install
npm run build
# 在Cursor中加载插件目录

步骤3：配置插件

在Cursor中配置NextCloud连接信息：

方式一：通过Cursor设置界面（推荐）

打开Cursor设置：Cmd/Ctrl + ,
搜索 "NextCloud Doc Publisher"
填写配置项：

NextCloud URL: https://nextcloud.example.com
Username: deploy-user
Password: your-app-password
Service Name: base-server-service
Version: V2.16.13
Base Path: /Docs （可选，默认值）

方式二：通过项目配置文件

在项目根目录创建 .cursor/doc-publish-config.json：

{
  "nextcloud": {
    "url": "https://nextcloud.example.com",
    "username": "deploy-user",
    "password": "your-app-password",
    "basePath": "/Docs"
  },
  "project": {
    "serviceName": "base-server-service",
    "version": "V2.16.13"
  }
}

说明：

项目配置文件优先级高于全局设置
建议将配置文件加入 .gitignore，避免泄露密码
支持使用环境变量：${env:NEXTCLOUD_URL}
插件默认使用 doc 目录，自动上传资源和文档，默认覆盖已存在的文件

创建NextCloud App Password（推荐）：

使用应用专用密码代替主密码，更加安全：

登录NextCloud -> 右上角头像 -> 设置
左侧菜单"安全" -> "应用专用密码"
输入应用名称：cursor-doc-publish-plugin
点击"创建"并复制生成的密码
将密码填入Cursor插件配置

步骤4：在项目中创建文档目录

# 进入项目目录
cd base-server-service

# 方式一：按文档类型组织
mkdir -p doc/design/V2.16.13/assets
mkdir -p doc/requirements/V2.16.13/assets
mkdir -p doc/api/V2.16.13/assets

# 方式二：直接按版本组织
mkdir -p doc/V2.16.13/assets

推荐目录结构（方式一）：

base-server-service/           # 项目根目录
├── src/
├── pom.xml
├── .cursor/
│   └── doc-publish-config.json # 插件配置文件（可选）
└── doc/                       # 文档根目录
    ├── design/                # 设计文档
    │   └── V2.16.13/
    │       ├── assets/
    │       └── (待创建.md文件)
    ├── requirements/          # 需求文档
    │   └── V2.16.13/
    │       └── assets/
    ├── api/                   # API文档
    │   └── V2.16.13/
    │       └── assets/
    └── tech/                  # 技术文档
        └── V2.16.13/
            └── assets/

简化目录结构（方式二）：

base-server-service/
└── doc/
    └── V2.16.13/
        ├── 设计文档.md
        ├── 需求文档.md
        ├── API文档.md
        └── assets/

步骤5：在Cursor中编写文档

示例1：设计文档 doc/design/V2.16.13/用户权限管理设计.md

# 用户权限管理设计文档

## 需求背景

本期需要实现基于RBAC的用户权限管理功能...

## 架构设计

![系统架构](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/architecture.png)

## 数据模型

![数据模型](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/data-model.png)

示例2：API文档 doc/api/V2.16.13/用户管理API.md

# 用户管理API文档

## 接口列表

![API概览](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/api-overview.png)

## 详细说明

[接口详细文档](https://github.com/chengang-97/cursor-doc-publish-plugin/blob/HEAD/assets/api-detail.pdf)

示例3：技术方案 doc/tech/V2.16.13/缓存优化方案.md

# 缓存优化技术方案

## 方案对比

![方案对比](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/solution-comparison.png)

## 实施计划

[详细计划](https://github.com/chengang-97/cursor-doc-publish-plugin/blob/HEAD/assets/implementation-plan.xlsx)

添加资源文件：

将图片和文档拖拽到对应的 assets/ 目录，或使用命令：

cp ~/architecture.png doc/design/V2.16.13/assets/
cp ~/api-detail.pdf doc/api/V2.16.13/assets/

资源引用规范：

使用相对路径：assets/文件名
图片：![描述](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/xxx.png)
附件：[链接文字](https://github.com/chengang-97/cursor-doc-publish-plugin/blob/HEAD/assets/xxx.pdf)
上传后文档保持原始引用，在NextCloud中可正常访问

步骤6：发布文档到NextCloud

插件支持两种发布模式：

单个文档发布：发布当前打开的Markdown文件
目录批量发布：发布指定目录下的所有Markdown文件

模式一：发布单个文档

适用于编写完成单个文档后快速发布。

操作方式：

方式1：使用命令面板（推荐）

在Cursor中打开要发布的Markdown文档（如 doc/design/V2.16.13/用户权限管理设计.md）
按 Cmd/Ctrl + Shift + P 打开命令面板
输入 "Publish Current Doc to NextCloud"
回车执行

方式2：使用右键菜单

在文件树中右键点击要发布的Markdown文件
选择 "Publish to NextCloud"

方式3：使用快捷键

Mac: Cmd + Shift + U
Windows/Linux: Ctrl + Shift + U

（需要在Cursor中打开要发布的文档）

发布过程：

[Publishing] Initializing NextCloud client...
[Publishing] Processing document: 用户权限管理设计.md
[Publishing] Uploading assets... (1/3) architecture.png
[Publishing] Uploading assets... (2/3) data-model.png
[Publishing] Uploading assets... (3/3) api-design.pdf
[Publishing] Creating share links...
[Publishing] Uploading markdown document...
[Success] ✓ Published: 用户权限管理设计.md
[Success] ✓ URL: https://nextcloud.example.com/s/AbC123

模式二：批量发布目录下的文档

适用于一次性发布多个文档或整个版本的文档。

操作方式：

方式1：使用命令面板

按 Cmd/Ctrl + Shift + P 打开命令面板
输入 "Publish Doc Directory to NextCloud"
选择要发布的目录（如 doc/design/V2.16.13/）
回车执行

方式2：使用右键菜单（推荐）

在文件树中右键点击文档目录（如 doc/design/V2.16.13/）
选择 "Publish Directory to NextCloud"

方式3：使用快捷键

Mac: Cmd + Option + Shift + U
Windows/Linux: Ctrl + Alt + Shift + U

（会发布当前打开文档所在的版本目录）

发布过程：

[Publishing] Initializing NextCloud client...
[Publishing] Scanning directory: doc/design/V2.16.13
[Publishing] Found 3 markdown file(s)
[Publishing] Uploading shared assets... (1/5) architecture.png
[Publishing] Uploading shared assets... (2/5) data-model.png
[Publishing] Uploading shared assets... (3/5) flow-chart.png
[Publishing] Uploading shared assets... (4/5) api-design.pdf
[Publishing] Uploading shared assets... (5/5) sequence.png
[Publishing] Creating share links...
[Publishing] Processing: 用户权限管理设计.md (1/3)
[Publishing] Processing: 数据迁移方案.md (2/3)
[Publishing] Processing: API接口设计.md (3/3)
[Success] ✓ Published 3 documents to: /Docs/V2.16.13/base-server-service/design/

两种模式的区别

特性	单个文档发布	目录批量发布
发布范围	当前打开的文档	目录下所有文档
assets处理	仅上传当前文档引用的资源	上传目录下所有资源
速度	快速	相对较慢
适用场景	快速迭代、单文档更新	首次发布、批量发布
操作复杂度	简单	需选择目录

使用建议

首次发布：

日常更新：

使用"单个文档发布"，快速发布修改的文档

版本发布：

使用"目录批量发布"，确保所有文档同步更新

步骤7：验证发布结果

发布成功后，Cursor会显示通知，包含NextCloud链接：

✓ 文档发布成功！
📂 查看文档: https://nextcloud.example.com/index.php/f/12345

点击链接访问NextCloud查看：

/Docs/V2.16.13/base-server-service/
├── design/
│   ├── 用户权限管理设计.md
│   └── assets/
│       ├── architecture.png
│       └── data-model.png
├── api/
│   ├── 用户管理API.md
│   └── assets/
│       └── api-detail.pdf
└── tech/
    ├── 缓存优化方案.md
    └── assets/
        └── solution-comparison.png

步骤8：提交到Git

只提交Markdown文件，不提交资源文件：

在Cursor中使用源代码管理面板：

打开源代码管理：Cmd/Ctrl + Shift + G
勾选 doc/**/*.md 文件
确保 assets/ 目录未被选中（应在 .gitignore 中）
输入提交信息："docs: 添加用户权限管理文档"
点击提交

配置 .gitignore：

# 添加到 .gitignore
echo "doc/**/assets/" >> .gitignore
echo ".cursor/doc-publish-config.json" >> .gitignore

为什么不提交assets？

资源文件已上传到NextCloud，无需在Git中保存
减小Git仓库体积
Markdown中保持相对路径引用，在NextCloud中可正常访问

目录结构说明

本地项目结构（推荐）

base-server-service/           # 组件服务项目
├── src/
├── pom.xml
├── .cursor/
│   └── doc-publish-config.json # 插件配置文件
├── .gitignore
└── doc/                       # 项目文档根目录
    ├── design/                # 设计文档
    │   ├── V2.16.13/
    │   │   ├── 用户权限管理设计.md
    │   │   ├── 数据迁移方案.md
    │   │   └── assets/
    │   └── V2.16.12/
    ├── requirements/          # 需求文档
    │   └── V2.16.13/
    │       ├── 用户故事.md
    │       └── assets/
    ├── api/                   # API文档
    │   └── V2.16.13/
    │       ├── 用户API.md
    │       └── assets/
    ├── tech/                  # 技术文档
    │   └── V2.16.13/
    │       └── assets/
    └── operations/            # 运维文档
        └── V2.16.13/
            └── assets/

NextCloud存储结构

/Docs/                         # 文档根目录
├── V2.16.13/                  # 版本目录
│   ├── base-server-service/   # 服务目录
│   │   ├── design/
│   │   │   ├── 用户权限管理设计.md
│   │   │   └── assets/
│   │   ├── requirements/
│   │   │   └── 用户故事.md
│   │   ├── api/
│   │   │   └── 用户API.md
│   │   └── tech/
│   ├── user-service/          # 其他服务
│   │   └── ...
│   └── order-service/
│       └── ...
└── V2.16.12/                  # 历史版本
    └── ...

组织原则：

按版本组织，方便追溯历史
按文档类型分类，便于查找
按服务隔离，避免文档混乱
资源集中管理，便于维护

配置说明

插件配置项

配置项	必填	默认值	说明	示例
`nextcloud.url`	是	-	NextCloud服务器地址	https://nextcloud.example.com
`nextcloud.username`	是	-	NextCloud用户名	deploy-user
`nextcloud.password`	是	-	NextCloud密码（应用专用密码）	xxxxx-xxxxx-xxxxx
`nextcloud.basePath`	是	-	NextCloud存储根路径	/Docs
`nextcloud.webdavUsername`	否	-	WebDAV文件空间用户名	username_1234
`project.serviceName`	是	-	当前服务名称	base-server-service
`project.version`	是	-	当前开发版本	V2.16.13

文档存储路径：{basePath}/{version}/{serviceName}

配置文件示例

完整配置示例 (.cursor/doc-publish-config.json)：

{
  "nextcloud": {
    "url": "https://nextcloud.example.com",
    "username": "deploy-user",
    "password": "your-app-password",
    "basePath": "/Docs",
    "webdavUsername": "deploy-user_1234"
  },
  "project": {
    "serviceName": "base-server-service",
    "version": "V2.16.13"
  }
}

说明：

插件默认使用 doc 目录作为文档根目录
默认上传所有资源文件和文档
默认覆盖已存在的文件

配置项说明：

url：从 WebDAV 地址中提取的服务器地址（如：https://docs.streamax.com:18001）
username：您的 NextCloud 登录用户名（用于认证）
password：应用专用密码（不是登录密码！）
basePath：您手动创建的根目录路径
webdavUsername：WebDAV 地址中的用户名部分（如果与登录用户名不同）

示例： 如果您的 WebDAV 地址是：https://docs.streamax.com:18001/remote.php/dav/files/chengang_3074

url: https://docs.streamax.com:18001
username: chengang（您的登录用户名）
webdavUsername: chengang_3074（WebDAV 地址中的用户名）

使用环境变量：

{
  "nextcloud": {
    "url": "${env:NEXTCLOUD_URL}",
    "username": "${env:NEXTCLOUD_USERNAME}",
    "password": "${env:NEXTCLOUD_PASSWORD}"
  },
  "project": {
    "serviceName": "${env:SERVICE_NAME}",
    "version": "${env:VERSION}"
  }
}

使用技巧

技巧1：根据场景选择发布模式

场景A：编写完单个文档，立即发布

使用"单个文档发布"
快捷键：Cmd/Ctrl + Shift + U
优势：速度快，只上传相关资源

场景B：首次发布或版本发布

使用"目录批量发布"
右键点击目录 -> "Publish Directory to NextCloud"
优势：确保所有文档同步

场景C：更新已发布的文档

修改文档后，使用"单个文档发布"
插件会自动覆盖NextCloud上的旧版本

技巧2：批量发布多个文档

如果在同一版本目录下有多个Markdown文档：

doc/design/V2.16.13/
            ├── 用户管理设计.md
            ├── 权限设计.md
├── 数据迁移方案.md
└── assets/

使用"目录批量发布"模式，插件会自动处理所有文档。

技巧3：按文档类型组织

推荐按文档类型创建子目录：

# 设计文档
doc/design/V2.16.13/

# 需求文档
doc/requirements/V2.16.13/

# API文档
doc/api/V2.16.13/

# 技术文档
doc/tech/V2.16.13/

发布时可以选择发布特定类型的文档。

技巧4：快速切换版本

在配置文件中使用变量：

{
  "project": {
    "version": "${env:VERSION}"
  }
}

在 .bashrc 或 .zshrc 中设置：

export VERSION="V2.16.13"

切换版本时只需修改环境变量，无需修改配置文件。

技巧5：查看发布历史

Cursor插件会在输出面板显示详细日志：

打开输出面板：Cmd/Ctrl + Shift + U
选择 "NextCloud Doc Publisher" 通道
查看发布历史和详细日志

技巧6：预览发布效果

在发布前，可以使用插件的预览功能：

按 Cmd/Ctrl + Shift + P
输入 "Preview Doc Upload"
查看将要上传的文件列表预览

故障排查

常见问题诊断

检查配置：

在Cursor中打开命令面板：Cmd/Ctrl + Shift + P
输入 "NextCloud Doc Publisher: Show Configuration"
查看当前配置是否完整

查看详细日志：

打开输出面板：Cmd/Ctrl + Shift + U
选择 "NextCloud Doc Publisher" 通道
查看详细执行日志

常见错误

1. 配置不完整

错误：NextCloud configuration is incomplete

原因：必填的配置项未填写

解决：

检查Cursor设置中的插件配置
或检查 .cursor/doc-publish-config.json 文件
确保所有必填项已填写

2. 认证失败

错误：401 Unauthorized

原因：用户名或密码错误

解决：

确认用户名和密码正确
建议使用App Password而非主密码
尝试在NextCloud Web界面登录验证

3. 权限不足

错误：403 Forbidden

原因：用户没有上传权限

解决：

在NextCloud中检查用户权限
确认目标目录可写
尝试在Web界面手动上传测试

4. 文件未找到

错误：No markdown files found

原因：文档目录不存在或路径配置错误

解决：

# 检查目录是否存在
ls -la doc/${VERSION}/

# 确认VERSION环境变量正确
echo $VERSION

5. 资源文件未上传

现象：Markdown发布了，但图片显示不出来

原因：assets目录为空或路径不对

解决：

# 检查assets目录
ls -la doc/${VERSION}/assets/

# 确认Markdown中的引用路径
grep "assets/" doc/${VERSION}/*.md

6. 插件未响应

现象：点击按钮或执行命令无反应

解决：

重启Cursor：Cmd/Ctrl + Shift + P -> "Reload Window"
检查插件是否正常加载：查看扩展列表
查看Cursor开发者工具：Help -> Toggle Developer Tools

常见问题

Q1: 如何验证插件配置正确？

A: 在命令面板中执行：

Cmd/Ctrl + Shift + P -> NextCloud Doc Publisher: Test Connection

插件会测试NextCloud连接并显示结果。

Q2: 如何获取正确的 WebDAV 地址？

A: 按照以下步骤获取：

1. 登录 NextCloud 网页版
2. 左下角点击 "文件设置"（齿轮图标）
3. 在设置面板左侧选择 "WebDAV"
4. 复制显示的 WebDAV 地址
5. 从地址中提取：
   - url: 服务器地址部分
   - webdavUsername: 地址最后的用户名部分

示例：

WebDAV 地址：https://docs.streamax.com:18001/remote.php/dav/files/chengang_3074
配置：
- url: https://docs.streamax.com:18001
- webdavUsername: chengang_3074

Q3: 支持哪些资源文件格式？

A: 支持所有格式，包括：

图片：png、jpg、gif、svg、webp
文档：pdf、docx、xlsx、pptx
其他：txt、json、xml、zip等

Q4: 多个文档如何管理？

A: 在同一版本目录下创建多个.md文件，插件会自动处理所有文档：

doc/design/V2.16.13/
├── 设计文档A.md
├── 设计文档B.md
├── 设计文档C.md
        └── assets/

Q4: 资源文件更新后需要重新发布吗？

A: 是的。如果修改了assets中的文件，需要重新执行发布命令，插件会自动覆盖旧文件。

Q5: NextCloud分享链接无法访问？

A: 检查以下几点：

NextCloud分享功能是否启用
分享链接权限是否为"公开"
网络是否可访问NextCloud服务器
防火墙或代理设置

Q6: 如何删除已发布的文档？

A: 登录NextCloud Web界面，在 /Docs/{VERSION}/{SERVICE_NAME}/ 目录下手动删除。

Q7: 插件是否支持离线工作？

A: 插件需要网络连接才能上传到NextCloud。编写文档可以离线进行，发布时需要联网。

Q8: 可以发布非设计类的文档吗？

A: 可以！插件支持发布任何类型的Markdown文档，包括需求文档、技术方案、API文档、运维手册等。

Q9: 如何组织不同类型的文档？

A: 推荐在doc目录下按类型创建子目录：

doc/
├── design/      # 设计文档
├── requirements/ # 需求文档
├── api/         # API文档
├── tech/        # 技术文档
└── operations/  # 运维文档

Q10: 单个文档发布和批量发布有什么区别？

A: 主要区别：

单个文档发布：只发布当前打开的文档，只上传该文档引用的资源，速度快
批量发布：发布整个目录下的所有文档，上传所有资源，确保完整性

建议：日常更新用单个发布，首次发布或版本发布用批量发布。

Q11: 如何只发布单个文档而不发布整个目录？

在Cursor中打开要发布的Markdown文件
按 Cmd/Ctrl + Shift + U（快捷键）
或在文件树中右键点击该文件 -> "Publish to NextCloud"

Q12: 发布单个文档时，其他文档会受影响吗？

A: 不会。单个文档发布只会：

上传/更新当前文档
上传/更新当前文档引用的资源
不会影响目录下的其他文档

Q13: 批量发布会覆盖之前发布的文档吗？

A: 会。批量发布会：

上传目录下的所有Markdown文件
如果NextCloud已存在同名文档，会被覆盖
所有资源文件也会被重新上传

技术原理

工作机制

单个文档发布流程：

配置读取：从Cursor设置或项目配置文件读取NextCloud连接信息
当前文档解析：获取当前打开的Markdown文件路径
资源分析：扫描文档中引用的 assets/xxx 资源
资源上传：仅上传当前文档引用的资源到NextCloud
分享链接生成：为上传的资源创建公开分享链接
文档上传：直接上传原始Markdown文件到NextCloud
结果反馈：显示发布成功通知和文档链接

批量目录发布流程：

配置读取：从Cursor设置或项目配置文件读取NextCloud连接信息
目录扫描：扫描指定目录下的所有 .md 文件
资源收集：收集 assets/ 目录下的所有资源文件
资源上传：通过WebDAV协议批量上传所有资源
分享链接生成：调用NextCloud Sharing API为每个资源创建公开分享链接
批量上传：直接上传所有原始Markdown文件
结果反馈：显示批量发布统计信息

技术栈

Cursor Extension API：Cursor插件开发框架
Node.js：插件运行环境
Sardine/WebDAV Client：WebDAV协议文件上传
Axios：HTTP客户端，调用NextCloud Sharing API
正则表达式：Markdown语法解析和资源引用扫描

关键实现

资源文件扫描：

// 匹配所有资源引用: [xxx](https://github.com/chengang-97/cursor-doc-publish-plugin/blob/HEAD/assets/yyy) 和 ![xxx](https://github.com/chengang-97/cursor-doc-publish-plugin/raw/HEAD/assets/yyy)
const assetPattern = /!?\[([^\]]*)\]\((assets\/[^)]+)\)/g;

WebDAV上传路径：

{NEXTCLOUD_URL}/remote.php/dav/files/{USERNAME}/{BASE_PATH}/{VERSION}/{SERVICE_NAME}/

进度通知：

vscode.window.withProgress({
  location: vscode.ProgressLocation.Notification,
  title: "Publishing Document",
  cancellable: false
}, async (progress) => {
  // 上传逻辑
});

插件开发

如果您想参与插件开发或自定义功能：

开发环境设置

前置要求：

Node.js 16+
npm 或 yarn
Cursor IDE

克隆并安装：

# 克隆仓库
git clone https://github.com/your-org/cursor-doc-publish-plugin.git
cd cursor-doc-publish-plugin

# 安装依赖
npm install

# 或使用yarn
yarn install

项目结构

cursor-doc-publish-plugin/
├── src/
│   ├── extension.ts          # 插件入口
│   ├── commands/
│   │   ├── publishCurrent.ts    # 发布单个文档
│   │   ├── publishDirectory.ts  # 批量发布目录
│   │   └── testConnection.ts    # 测试连接
│   ├── services/
│   │   ├── nextcloud.ts      # NextCloud服务
│   │   ├── markdown.ts       # Markdown处理
│   │   └── config.ts         # 配置管理
│   └── utils/
│       └── logger.ts         # 日志工具
├── package.json              # 插件配置和依赖
├── tsconfig.json             # TypeScript配置
├── .vscodeignore             # 打包时忽略的文件
└── README.md

本地开发调试

方式一：使用调试模式

在Cursor中打开插件项目
按 F5 启动调试
会打开一个新的Cursor窗口（扩展开发宿主）
在新窗口中测试插件功能
修改代码会自动热重载

方式二：使用watch模式

# 启动TypeScript编译watch模式
npm run watch

# 或
yarn watch

然后按 F5 启动调试。

插件打包

使用 vsce (Visual Studio Code Extension Manager) 工具打包插件：

1. 安装vsce工具

npm install -g @vscode/vsce

2. 准备package.json

确保 package.json 包含必要的信息：

{
  "name": "cursor-doc-publish-plugin",
  "displayName": "NextCloud Doc Publisher",
  "description": "一键发布项目文档到NextCloud",
  "version": "1.0.0",
  "publisher": "your-publisher-name",
  "engines": {
    "vscode": "^1.80.0"
  },
  "categories": ["Other"],
  "activationEvents": [
    "onCommand:docPublish.publishCurrent",
    "onCommand:docPublish.publishDirectory"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "docPublish.publishCurrent",
        "title": "Publish Current Doc to NextCloud"
      },
      {
        "command": "docPublish.publishDirectory",
        "title": "Publish Doc Directory to NextCloud"
      }
    ],
    "keybindings": [
      {
        "command": "docPublish.publishCurrent",
        "key": "ctrl+shift+u",
        "mac": "cmd+shift+u",
        "when": "editorTextFocus"
      },
      {
        "command": "docPublish.publishDirectory",
        "key": "ctrl+alt+shift+u",
        "mac": "cmd+option+shift+u"
      }
    ],
    "menus": {
      "explorer/context": [
        {
          "command": "docPublish.publishCurrent",
          "when": "resourceExtname == .md",
          "group": "navigation"
        },
        {
          "command": "docPublish.publishDirectory",
          "when": "explorerResourceIsFolder",
          "group": "navigation"
        }
      ]
    },
    "configuration": {
      "title": "NextCloud Doc Publisher",
      "properties": {
        "docPublish.nextcloud.url": {
          "type": "string",
          "description": "NextCloud服务器地址"
        },
        "docPublish.nextcloud.username": {
          "type": "string",
          "description": "NextCloud用户名"
        }
      }
    }
  }
}

3. 创建.vscodeignore文件

指定打包时要忽略的文件：

.vscode/**
.vscode-test/**
src/**
.gitignore
.yarnrc
vsc-extension-quickstart.md
**/tsconfig.json
**/.eslintrc.json
**/*.map
**/*.ts
node_modules/**
.cursor/**

4. 执行打包命令

# 打包为VSIX文件
vsce package

# 输出示例：
# Created: cursor-doc-publish-plugin-1.0.0.vsix

打包成功后会生成 .vsix 文件，这是可安装的插件包。

插件发布

方式一：发布到 VSCode Marketplace（推荐）

VSCode Marketplace 是微软官方的扩展市场，用户最多，Cursor 完全兼容。

为什么选择 VSCode Marketplace？

🎯 用户基数最大（VSCode + Cursor + 其他兼容编辑器）
🔍 搜索便捷，用户可以直接在编辑器内搜索安装
🏆 官方认可，可信度高
📊 提供下载量、评分等统计数据
🔄 支持自动更新

前置准备：

在开始之前，确保你的项目具备以下条件：

✅ 项目已在 Git 仓库中管理（推荐 GitHub）
✅ package.json 配置完整（见下方说明）
✅ 有 README.md、LICENSE、CHANGELOG.md 等文件
✅ 代码已测试，功能稳定

详细发布步骤：

第 1 步：创建 Azure DevOps 账号

VSCode Marketplace 使用 Azure DevOps 进行发布者身份验证。

1.1 注册 Azure DevOps

访问 https://dev.azure.com/
点击 "Start free"
使用 Microsoft 账号登录（或创建新账号）
创建一个组织（Organization）
- 组织名称可以随意填写（如：your-name-extensions）
- 选择托管区域（推荐选择离你最近的区域）

1.2 创建 Personal Access Token (PAT)

这是发布插件的关键凭证，请妥善保管。

登录 Azure DevOps：https://dev.azure.com/
点击右上角的用户头像
选择 "Personal access tokens"（个人访问令牌）
点击 "+ New Token"（新建令牌）
填写令牌信息：
- Name（名称）：vscode-marketplace-publisher（建议使用描述性名称）
- Organization（组织）：选择 "All accessible organizations"
- Expiration（过期时间）：
  - 建议选择 "Custom defined"
  - 设置较长的有效期（如 1 年或更长）
  - ⚠️ 注意：令牌过期后需要重新创建
- Scopes（权限范围）：
  - 滚动到 "Marketplace" 部分
  - 勾选 "Marketplace" -> "Manage"
  - ✅ 只需要这一个权限即可
点击 "Create"（创建）
重要：立即复制生成的 Token
- ⚠️ Token 只会显示一次，关闭后无法再次查看
- 建议保存到密码管理器中
- Token 格式示例：a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

第 2 步：完善 package.json 配置

发布到市场前，需要确保 package.json 包含必要的信息。

必填字段：

{
  "name": "cursor-doc-publish-plugin",  // 插件唯一标识（小写，连字符分隔）
  "displayName": "NextCloud Doc Publisher",  // 市场显示名称
  "description": "一键发布项目文档到 NextCloud，支持资源自动上传",  // 简短描述
  "version": "1.0.0",  // 版本号（遵循语义化版本）
  "publisher": "your-publisher-id",  // 发布者ID（下一步创建）
  "license": "MIT",  // 许可证类型
  
  "engines": {
    "vscode": "^1.80.0"  // 支持的 VSCode 最低版本
  },
  
  "categories": [
    "Other"  // 插件分类
    // 可选：Documentation, SCM Providers, Publishing, etc.
  ],
  
  "keywords": [  // 关键词（帮助用户搜索）
    "nextcloud",
    "documentation",
    "markdown",
    "publish",
    "webdav"
  ],
  
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/cursor-doc-publish-plugin.git"
  },
  
  "bugs": {
    "url": "https://github.com/your-username/cursor-doc-publish-plugin/issues"
  },
  
  "homepage": "https://github.com/your-username/cursor-doc-publish-plugin#readme",
  
  "icon": "icon.png",  // 可选：128x128 的图标（放在项目根目录）
  
  "activationEvents": [
    "onCommand:docPublish.publishCurrent"
  ],
  
  "main": "./out/extension.js",
  
  "contributes": {
    "commands": [...],
    "configuration": {...}
  }
}

推荐字段：

{
  "galleryBanner": {
    "color": "#0066CC",  // 市场页面横幅颜色
    "theme": "dark"  // 或 "light"
  },
  
  "badges": [  // 徽章展示
    {
      "url": "https://img.shields.io/visual-studio-marketplace/v/your-publisher.cursor-doc-publish-plugin",
      "href": "https://marketplace.visualstudio.com/items?itemName=your-publisher.cursor-doc-publish-plugin",
      "description": "Marketplace Version"
    }
  ]
}

第 3 步：安装 vsce 工具

vsce (Visual Studio Code Extensions) 是微软提供的扩展打包和发布工具。

# 全局安装 vsce
npm install -g @vscode/vsce

# 验证安装
vsce --version

第 4 步：创建发布者账号

发布者（Publisher）是你在 VSCode Marketplace 上的身份标识。

4.1 创建发布者

方式一：使用命令行创建

vsce create-publisher your-publisher-id

会提示输入：

Publisher ID：唯一标识符（建议使用你的 GitHub 用户名或公司名）
- 只能包含字母、数字、连字符
- 一旦创建不可更改
- 示例：chengang、your-company
Publisher Name：显示名称（可以包含空格和中文）
- 示例：陈刚、Your Company
Email：联系邮箱

方式二：在网页上创建（推荐）

访问：https://marketplace.visualstudio.com/manage
使用之前创建的 Azure DevOps 账号登录
点击 "Create publisher"
填写发布者信息：
- ID：发布者唯一标识
- Name：显示名称
- Email：联系邮箱
点击 "Create"

4.2 更新 package.json

创建发布者后，更新 package.json 中的 publisher 字段：

{
  "publisher": "your-publisher-id"  // 使用你刚创建的发布者ID
}

第 5 步：登录 vsce

使用创建的 Personal Access Token 登录。

vsce login your-publisher-id

提示输入 Personal Access Token 时，粘贴之前创建的 Token。

成功后会显示：

The Personal Access Token verification succeeded for the publisher 'your-publisher-id'.

第 6 步：打包插件（可选但推荐）

在正式发布前，先打包测试一下。

# 打包为 .vsix 文件
vsce package

# 输出示例：
# Executing prepublish script 'npm run compile'...
# Created: cursor-doc-publish-plugin-1.0.0.vsix (123 KB)

验证打包结果：

检查生成的 .vsix 文件大小是否合理

安装测试：

code --install-extension cursor-doc-publish-plugin-1.0.0.vsix

在 VSCode/Cursor 中测试功能是否正常

常见打包问题：

❌ 问题 1：文件过大

# 检查 .vscodeignore 文件，排除不必要的文件
# 应该排除：
.vscode/
.git/
node_modules/
src/
.gitignore
tsconfig.json
*.map
*.ts (如果已编译为 .js)

❌ 问题 2：缺少文件

# 确保 out/ 目录中有编译后的 .js 文件
npm run compile

第 7 步：发布到 Marketplace

7.1 首次发布

# 直接发布当前版本
vsce publish

# 或指定版本号发布
vsce publish 1.0.0

发布过程会：

自动运行 prepublish 脚本（如 npm run compile）
打包扩展
上传到 Marketplace
验证和审核（通常几分钟内完成）

7.2 更新版本发布

# 自动递增补丁版本（1.0.0 -> 1.0.1）
vsce publish patch

# 自动递增次版本（1.0.0 -> 1.1.0）
vsce publish minor

# 自动递增主版本（1.0.0 -> 2.0.0）
vsce publish major

# 或手动指定版本
vsce publish 1.2.3

这些命令会：

自动更新 package.json 中的版本号
打包并发布新版本
用户会自动收到更新通知

第 8 步：验证发布

8.1 查看发布状态

访问：https://marketplace.visualstudio.com/manage/publishers/your-publisher-id
查看插件状态：
- ✅ Published：发布成功
- 🔄 Publishing：正在发布中
- ❌ Failed：发布失败（查看错误信息）

8.2 访问插件页面

成功后，你的插件会出现在：

https://marketplace.visualstudio.com/items?itemName=your-publisher-id.cursor-doc-publish-plugin

8.3 在 Cursor 中搜索

打开 Cursor
按 Cmd/Ctrl + Shift + X 打开扩展面板
搜索你的插件名称
应该能看到并安装

第 9 步：更新插件信息（可选）

9.1 更新 README

Marketplace 会自动显示项目的 README.md，确保包含：

插件介绍
功能特性
使用说明
配置示例
截图/GIF 演示
常见问题

9.2 添加插件图标

创建 128x128 像素的 PNG 图标，放在项目根目录，命名为 icon.png。

9.3 更新 CHANGELOG

维护 CHANGELOG.md，记录每个版本的更新内容：

# Change Log

## [1.0.1] - 2025-10-16
### Fixed
- 修复资源上传失败的问题
- 优化错误提示信息

## [1.0.0] - 2025-10-15
### Added
- 初始版本发布
- 支持单个文档发布
- 支持批量目录发布

常见问题和注意事项

Q1: Personal Access Token 过期了怎么办？

A: 重新创建 Token，然后再次登录：

vsce login your-publisher-id

Q2: 如何撤销已发布的版本？

访问 Marketplace 管理页面
找到对应的插件版本
点击 "Unpublish"（不推荐，会影响用户）
更好的做法是发布修复版本

Q3: 发布失败常见原因？

❌ package.json 中的 publisher 字段不匹配
❌ 版本号重复（需要递增版本号）
❌ Token 权限不足或已过期
❌ README.md 或 LICENSE 文件缺失
❌ 违反市场政策（如包含恶意代码）

Q4: 如何查看下载统计？

访问：https://marketplace.visualstudio.com/manage/publishers/your-publisher-id 可以看到：

总下载量
每日下载趋势
评分和评论

Q5: 可以更改发布者 ID 吗？

不可以。发布者 ID 一旦创建就无法更改。如需更改，只能：

创建新的发布者
重新发布插件
废弃旧插件

自动化发布（推荐）

使用 GitHub Actions 自动发布，每次打 tag 时自动发布到市场：

# .github/workflows/publish.yml
name: Publish to Marketplace

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run compile
      
      - name: Publish to VSCode Marketplace
        run: |
          npm install -g @vscode/vsce
          vsce publish -p ${{ secrets.VSCE_TOKEN }}
        env:
          VSCE_TOKEN: ${{ secrets.VSCE_TOKEN }}

在 GitHub 仓库设置中添加 Secret：

名称：VSCE_TOKEN
值：你的 Personal Access Token

这样每次推送 tag 时就会自动发布：

git tag v1.0.1
git push origin v1.0.1

发布成功后，你的插件就可以被全球的 VSCode 和 Cursor 用户搜索和安装了！🎉

方式二：发布到 Open VSX Registry（推荐开源项目）

Open VSX 是 Eclipse 基金会维护的开源扩展市场，兼容 VSCode 和其他编辑器。

为什么选择 Open VSX？

完全开源，无需 Azure 账号
支持 VSCodium、Theia、Gitpod 等编辑器
Cursor 也支持从 Open VSX 安装扩展
适合开源项目

发布步骤：

1. 访问 Open VSX

访问 https://open-vsx.org/ 并注册账号（可以使用 GitHub 登录）

2. 创建 Personal Access Token

登录后访问：https://open-vsx.org/user-settings/tokens
点击 "New Access Token"
输入名称（如：cursor-doc-publish-plugin）
复制生成的 Token

3. 安装 ovsx 工具

npm install -g ovsx

4. 发布插件

# 登录（可选）
ovsx login

# 发布 .vsix 文件
ovsx publish cursor-doc-publish-plugin-1.0.0.vsix -p YOUR_ACCESS_TOKEN

# 或直接发布（自动打包）
ovsx publish -p YOUR_ACCESS_TOKEN

5. 验证发布

访问 https://open-vsx.org/extension/your-publisher/cursor-doc-publish-plugin

方式三：发布到 GitHub Releases

直接在 GitHub 发布 .vsix 文件，用户可以下载安装。

优势：

无需注册市场账号
完全掌控发布流程
适合企业内部或小范围分发
用户可以查看源码和历史版本

发布步骤：

1. 创建 Git Tag

git tag v1.0.0
git push origin v1.0.0

2. 打包插件

npm run build
vsce package

3. 创建 GitHub Release

访问项目的 Releases 页面
点击 "Create a new release"
选择刚才创建的 Tag
上传打包好的 .vsix 文件
填写 Release Notes
点击 "Publish release"

4. 用户安装方式

用户可以：

访问 GitHub Releases 页面
下载最新的 .vsix 文件
在 Cursor 中通过 "Extensions: Install from VSIX" 命令安装

自动化发布（推荐）：

使用 GitHub Actions 自动发布：

# .github/workflows/release.yml
name: Release Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build
        run: npm run build
      
      - name: Package
        run: |
          npm install -g @vscode/vsce
          vsce package
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: '*.vsix'
          generate_release_notes: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      # 可选：同时发布到 VSCode Marketplace
      - name: Publish to VSCode Marketplace
        if: ${{ secrets.VSCE_TOKEN }}
        run: vsce publish -p ${{ secrets.VSCE_TOKEN }}
      
      # 可选：同时发布到 Open VSX
      - name: Publish to Open VSX
        if: ${{ secrets.OVSX_TOKEN }}
        run: |
          npm install -g ovsx
          ovsx publish *.vsix -p ${{ secrets.OVSX_TOKEN }}

方式四：团队内部分发

如果不想公开发布，可以通过以下方式在团队内部分发：

1. 共享VSIX文件

将打包好的 .vsix 文件上传到团队文件服务器或Git仓库：

# 示例：上传到公司内网
scp cursor-doc-publish-plugin-1.0.0.vsix user@internal-server:/plugins/

# 或放到Git仓库的releases
git tag v1.0.0
git push origin v1.0.0
# 在GitHub/GitLab创建Release并上传.vsix文件

2. 创建安装说明文档

提供给团队成员：

## 安装插件

1. 下载插件文件：cursor-doc-publish-plugin-1.0.0.vsix
2. 打开Cursor
3. 按 Cmd/Ctrl + Shift + P
4. 输入 "Extensions: Install from VSIX"
5. 选择下载的.vsix文件
6. 重启Cursor

3. 自动更新机制

可以配置内部更新服务器，插件定期检查更新。

插件安装

Cursor 支持多种插件安装方式：

方式一：从 VSCode Marketplace 安装（推荐）

适用场景：插件已发布到 VSCode 市场

打开Cursor
点击左侧扩展图标（或按 Cmd/Ctrl + Shift + X）
搜索 "NextCloud Doc Publisher"
点击 "Install"
重启Cursor（如需要）

说明：Cursor 完全兼容 VSCode Marketplace，所有发布到 VSCode 市场的扩展都可以在 Cursor 中安装。

方式二：从 Open VSX Registry 安装

适用场景：插件发布在 Open VSX

访问 https://open-vsx.org/
搜索插件名称
下载 .vsix 文件
在 Cursor 中通过命令面板安装（见方式三）

或配置 Cursor 使用 Open VSX：

在 Cursor 设置中添加：

{
  "extensions.gallery": {
    "serviceUrl": "https://open-vsx.org/vscode/gallery",
    "itemUrl": "https://open-vsx.org/vscode/item"
  }
}

方式三：从 GitHub Releases 安装

适用场景：从 GitHub 下载 .vsix 文件

访问项目的 GitHub Releases 页面
下载最新版本的 .vsix 文件
在 Cursor 中按 Cmd/Ctrl + Shift + P
输入 "Extensions: Install from VSIX..."
选择下载的 .vsix 文件
重启 Cursor

方式四：从本地 VSIX 文件安装

使用命令面板：

打开Cursor
按 Cmd/Ctrl + Shift + P 打开命令面板
输入 "Extensions: Install from VSIX..."
选择 .vsix 文件
等待安装完成
重启Cursor

使用命令行：

# Mac/Linux
cursor --install-extension cursor-doc-publish-plugin-1.0.0.vsix

# Windows
cursor.exe --install-extension cursor-doc-publish-plugin-1.0.0.vsix

使用code命令（如果Cursor支持）：

code --install-extension cursor-doc-publish-plugin-1.0.0.vsix

插件发布渠道对比

发布渠道	适用场景	优势	劣势	Cursor支持
VSCode Marketplace	公开发布	用户最多，搜索方便	需要Azure账号	✅ 完全支持
Open VSX Registry	开源项目	开源免费，多编辑器支持	用户相对较少	✅ 支持
GitHub Releases	开源/内部项目	简单直接，版本管理清晰	需要手动安装	✅ 支持
内部服务器	企业内部	完全掌控，安全可靠	需要自建基础设施	✅ 支持

推荐策略：

个人开源项目：发布到 Open VSX Registry
商业插件：发布到 VSCode Marketplace
企业内部：使用 GitHub Releases 或内部服务器
最佳实践：同时发布到多个渠道，覆盖更多用户

方式五：手动安装（开发模式）

适用于开发和测试：

构建插件：

cd cursor-doc-publish-plugin
npm run build

Mac：

cp -r . ~/.cursor/extensions/cursor-doc-publish-plugin

Windows：

xcopy /E /I . %USERPROFILE%\.cursor\extensions\cursor-doc-publish-plugin

Linux：

cp -r . ~/.cursor/extensions/cursor-doc-publish-plugin

重启Cursor

版本管理

更新版本号：

# 使用npm version命令
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# 自动更新package.json和创建git tag

发布新版本：

# 1. 更新版本
npm version patch

# 2. 构建
npm run build

# 3. 打包
vsce package

# 4. 发布
vsce publish

# 或一步完成（自动递增版本并发布）
vsce publish patch

验证安装

安装完成后，验证插件是否正常工作：

1. 检查插件列表

Cmd/Ctrl + Shift + X -> 已安装 -> 查找 "NextCloud Doc Publisher"

2. 测试命令

Cmd/Ctrl + Shift + P -> 输入 "Publish"

应该能看到两个命令：

"Publish Current Doc to NextCloud" - 发布单个文档
"Publish Doc Directory to NextCloud" - 批量发布目录

如果能看到这些命令，说明插件已正确安装。

3. 查看插件日志

Cmd/Ctrl + Shift + U -> 选择 "NextCloud Doc Publisher"

故障排除

打包失败

错误：vsce: command not found

解决：

npm install -g @vscode/vsce

安装失败

错误：Extension 'xxx' is not compatible with this version of Cursor

解决：检查 package.json 中的 engines.vscode 版本要求。

插件不生效

解决：

检查 activationEvents 配置
查看开发者工具控制台错误：Help -> Toggle Developer Tools
重启Cursor

持续集成

使用GitHub Actions自动化打包和发布：

.github/workflows/release.yml：

name: Release Plugin

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build
        run: npm run build
      
      - name: Package
        run: |
          npm install -g @vscode/vsce
          vsce package
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: '*.vsix'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Publish to VSCode Marketplace
        run: vsce publish -p ${{ secrets.VSCE_TOKEN }}

贡献指南

欢迎提交Issue和Pull Request！

提交PR前请确保：

代码通过TypeScript编译
运行测试通过：npm test
更新相关文档

注意事项

配置文件安全
- 将 .cursor/doc-publish-config.json 加入 .gitignore
- 优先使用App Password而非主密码
- 避免将密码明文提交到Git仓库
版本号规范
- 建议格式：V{主版本}.{次版本}.{修订版本}
- 示例：V2.16.13、V3.0.1
资源引用规范
- 使用指向assets/的相对路径引用
- 上传后保持原始引用格式
- 不要使用../等复杂相对路径
- HTTP/HTTPS链接保持不变
Git提交建议
- 只提交.md文件到Git
- 将doc/**/assets/加入.gitignore
- 资源文件已在NextCloud，无需版本控制
网络要求
- 发布时需要网络连接到NextCloud服务器
- 建议在稳定网络环境下发布
- 大文件上传可能需要较长时间
NextCloud权限
- 确保用户有目标目录的写入权限
- 确保有创建公开分享链接的权限
- 首次使用需手动创建 /Docs 根目录

文档版本: V10.3 (Cursor Plugin - 多渠道发布指南)
最后更新: 2025-10-16
维护团队: 技术架构组
联系方式: architecture@example.com

NextCloud Doc Publisher

shon-chen