Postar 开发指南

📦 项目概述

Postar 是一个基于 WXT 框架构建的浏览器扩展项目，使用现代前端技术栈（Vue 3 + TypeScript）。支持声明式开发和实时热重载。Postar 专注于国际媒体平台的内容同步和分发，采用插件化架构实现平台可扩展性。

🛠️ 开发环境要求

前提条件

• Node.js
• 包管理器：pnpm（推荐）

可选工具

• Git 版本控制
• Chrome 浏览器（最新版本）

🔧 开发流程

1. 安装依赖

   pnpm i

2. 启动开发服务器

   pnpm dev  # WXT 开发模式，支持实时重载和 HMR

3. 加载扩展
   • 导航到 chrome://extensions
   • 启用开发者模式
   • 点击加载已解压的扩展程序
   • 选择 .output/chrome-mv3-dev 目录

🚀 构建与发布

• 生产构建：

  pnpm build

• 生成发布包（ZIP 格式）：

  pnpm zip

🛠️ 开发指南

Background Script

• 管理扩展生命周期（安装/更新/卸载）
• 监听浏览器事件（标签页更新、历史记录变更等）
• 无 DOM 访问（无法直接访问网页 DOM；必须使用 content scripts 作为代理）
• 非持久化执行（在 Manifest V3 中，按需唤醒并在事件处理后休眠）
• 通过 chrome.runtime.sendMessage 接收来自 content scripts/popups 的消息
• 通过 chrome.tabs.sendMessage 向特定标签页发送命令

Content Script

• 可以直接访问页面 DOM，但无法调用大多数 Chrome API
• 通过 chrome.runtime.sendMessage 与后台通信
• 支持智能网页内容提取（Readability 解析）
• 支持文本选择同步和图片检测

Sidepanel

• 支持 Vue.js 组件开发，拥有完整的 Chrome API 访问权限
• 使用 chrome.storage 进行数据持久化

插件系统

• 基于插件引擎（@gitcoffee/postbot-plugin-engine）实现平台可扩展性
• 默认包含国际平台发布插件（@gitcoffee/postbot-publisher-en）
• 支持自定义平台注册和元数据管理

📁 项目结构

src/
├── api/              # API 接口和配置
├── assets/           # 静态资源（图标等）
├── background/       # 后台脚本
├── config/           # 配置文件
├── content/          # 内容脚本（浮动按钮、弹窗）
├── entrypoints/      # WXT 入口点
│   ├── background.ts
│   ├── content.ts
│   └── sidepanel/    # 侧边栏
├── events/           # 事件处理（右键菜单等）
├── locales/          # 国际化（en/zh）
├── media/            # 媒体处理
│   ├── adapter/      # 媒体适配器
│   ├── handler/      # 媒体处理器
│   ├── meta/         # 平台元数据
│   ├── parser/       # 内容解析器
│   ├── processor/    # 媒体处理器
│   └── publisher/    # 发布器
├── message/          # 消息通信
├── plugins/          # 插件系统
├── stores/           # 状态管理（Pinia）
└── styles/           # 全局样式

❓ 常见问题

• 热重载不工作：尝试刷新扩展页面或重启开发服务器。
• 类型错误：检查 tsconfig.json 配置并确保所有依赖已安装。

🙌 参与贡献

欢迎通过 Pull Request 贡献代码。请确保：

• 代码风格与项目一致
• 现有测试用例通过
• 相关文档已更新

贡献指南