chore: initial commit

Author: magisk317

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "dev"]
+  pull_request:
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm i
+      - run: pnpm type-check

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm i
+      - run: pnpm pack:zip
+      - run: pnpm pack:tgz
+      - run: pnpm -s marketplace:snippet > marketplace-index-snippet.json
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            release/*
+            marketplace-index-snippet.json

.gitignore

@@ -0,0 +1,5 @@
+dist/
+release/
+.cache/
+node_modules/
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,183 @@
+# napgram-plugin-template
+
+NapGram 原生插件模板仓库（可作为 GitHub **Template repository** 使用）。
+
+这是 **NapGram 原生插件** 模板：插件直接运行在 NapGram 进程内，通过原生 API 访问平台功能（不需要 Koishi，也不需要 WebSocket Gateway）。
+
+## 特点
+
+- ✅ **原生集成** - 直接运行在 NapGram 进程内，无需独立进程
+- ✅ **类型安全** - 内置最小 TypeScript 类型，开箱即用
+- ✅ **高性能** - 内存级事件通信，零延迟
+- ✅ **简单易用** - 清晰的 API，开箱即用
+
+## 快速开始
+
+### 1) 安装依赖
+
+```bash
+pnpm install
+```
+
+### 2) 开发插件
+
+编辑 `src/index.ts`，实现你的插件逻辑：
+
+```typescript
+import type { NapGramPlugin } from '@naplink/napgram-plugin-types';
+
+const plugin: NapGramPlugin = {
+  id: 'my-plugin',
+  name: 'My Plugin',
+  version: '1.0.0',
+  
+  async install(ctx) {
+    ctx.on('message', async (event) => {
+      if (event.message.text === 'ping') await event.reply('pong');
+    });
+  }
+};
+
+export default plugin;
+```
+
+> 注：模板内包含 `src/types/@naplink/napgram-plugin-types/index.d.ts` 的最小类型声明，便于直接开发与通过 CI；构建产物不会包含该依赖。
+
+### 3) 构建
+
+```bash
+pnpm build
+```
+
+### 3.1) 本地安装（可选）
+
+将构建产物安装到 NapGram 的 data 目录（无需改 `plugins.yaml`）：
+
+```bash
+./scripts/install-local.sh /path/to/napgram/data
+```
+
+重载方式（二选一）：
+
+- 重启 NapGram
+- `POST /api/admin/plugins/reload`（全量重载）或 `POST /api/admin/plugins/:id/reload`（单插件重载）
+
+### 4) 打包发布
+
+```bash
+# 打包为 zip
+pnpm pack:zip
+
+# 打包为 tgz
+pnpm pack:tgz
+
+# 生成 marketplace 索引片段
+pnpm marketplace:snippet
+```
+
+产物位于 `release/` 目录。
+
+## 插件 API
+
+### 核心接口
+
+- **PluginContext** - 插件上下文，提供所有 API
+- **MessageEvent** - 消息事件
+- **MessageAPI** - 发送/撤回消息
+- **InstanceAPI** - 实例管理
+- **UserAPI** - 用户信息
+- **GroupAPI** - 群组管理
+- **PluginStorage** - 数据存储
+- **PluginLogger** - 日志记录
+
+### 事件监听
+
+```typescript
+ctx.on('message', async (event) => {
+  // 处理消息
+});
+
+ctx.on('friend-request', async (event) => {
+  // 处理好友请求
+});
+```
+
+### 消息发送
+
+```typescript
+// 回复消息
+await event.reply('Hello!');
+
+// 发送消息
+await event.send([
+  { type: 'text', data: { text: 'Hello ' } },
+  { type: 'at', data: { userId: 'user123' } }
+]);
+```
+
+### 数据存储
+
+```typescript
+// 保存数据
+await ctx.storage.set('key', { data: 'value' });
+
+// 读取数据
+const data = await ctx.storage.get('key');
+
+// 删除数据
+await ctx.storage.delete('key');
+```
+
+### 日志记录
+
+```typescript
+ctx.logger.info('插件已启动');
+ctx.logger.debug('调试信息');
+ctx.logger.warn('警告信息');
+ctx.logger.error('错误信息');
+```
+
+## 权限声明
+
+在 `napgram-plugin.json` 中声明插件权限：
+
+```json
+{
+  "permissions": {
+    "instances": [0],        // 可访问的实例（按需填写）
+    "network": [],           // 网络访问 allowlist（默认空 = 不申请）
+    "fs": []                 // 文件系统访问（默认空 = 不申请）
+  }
+}
+```
+
+## 目录结构
+
+```
+napgram-plugin-template/
+├── src/
+│   ├── index.ts              # 插件主文件
+│   └── types/                # 内置类型声明（仅用于开发）
+├── scripts/
+│   ├── pack.mjs              # 打包脚本
+│   └── marketplace-snippet.mjs
+├── napgram-plugin.json       # 插件元信息
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 发布到 Marketplace
+
+1. 打包插件：`pnpm pack:zip`
+2. 上传到 GitHub Release 或 CDN
+3. 生成索引片段：`pnpm marketplace:snippet`
+4. 提交 PR 到 NapGram Marketplace 仓库
+
+## 示例插件
+
+查看 `src/index.ts` 中的 Ping Pong 插件示例。
+
+## License
+
+MIT

napgram-plugin.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "native",
+  "id": "ping-pong",
+  "name": "Ping Pong Plugin (Template)",
+  "description": "A native NapGram plugin example that replies pong to ping.",
+  "entry": "dist/index.mjs",
+  "permissions": {
+    "network": [],
+    "fs": [],
+    "instances": [0]
+  }
+}

package.json

@@ -0,0 +1,21 @@
+{
+  "name": "napgram-plugin-template",
+  "private": true,
+  "version": "0.1.0",
+  "description": "NapGram native plugin template (runs directly in NapGram runtime).",
+  "type": "module",
+  "packageManager": "pnpm@10.26.0",
+  "scripts": {
+    "clean": "rm -rf dist release .cache",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "pack:zip": "pnpm build && node scripts/pack.mjs zip",
+    "pack:tgz": "pnpm build && node scripts/pack.mjs tgz",
+    "marketplace:snippet": "node scripts/marketplace-snippet.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  }
+}

pnpm-lock.yaml

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DATA_DIR="${1:-}"
+if [[ -z "${DATA_DIR}" ]]; then
+  echo "usage: ./scripts/install-local.sh /path/to/napgram/data"
+  echo "example: ./scripts/install-local.sh ../NapGram/main/data"
+  exit 1
+fi
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PKG_JSON="${ROOT}/package.json"
+META_JSON="${ROOT}/napgram-plugin.json"
+
+ID="$(node -p "JSON.parse(require('fs').readFileSync('${META_JSON}','utf8')).id")"
+VER="$(node -p "require('${PKG_JSON}').version")"
+
+echo "[1/3] build..."
+(cd "${ROOT}" && pnpm build)
+
+DEST_DIR="${DATA_DIR}/plugins/local"
+DEST_FILE="${DEST_DIR}/${ID}.mjs"
+echo "[2/3] copy to ${DEST_FILE} ..."
+mkdir -p "${DEST_DIR}"
+if [[ -f "${ROOT}/dist/index.mjs" ]]; then
+  cp -f "${ROOT}/dist/index.mjs" "${DEST_FILE}"
+else
+  cp -f "${ROOT}/dist/index.js" "${DEST_FILE}"
+fi
+
+echo "[3/3] next steps:"
+echo "  - Restart NapGram, or call: POST /api/admin/plugins/reload"
+echo "  - Or reload only this plugin: POST /api/admin/plugins/${ID}/reload"