mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
更新指导
This commit is contained in:
ryan
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: "release-guide"
|
||||
description: "Wavelet 项目专用：根据自上一个正式版本 Tag 以来的提交记录，整理生成规范的 Version Bump Commit Message，用于触发自动双语 Release。"
|
||||
---
|
||||
|
||||
# Release Commit Message Guide
|
||||
|
||||
## 目标
|
||||
|
||||
当用户准备发布 Wavelet 新版本时，本 Skill 只负责生成用于版本提交的 Commit Message。
|
||||
|
||||
## 生成提交信息
|
||||
|
||||
将原始 commit log 整理为面向 Release 的更新说明。
|
||||
|
||||
要求：
|
||||
|
||||
1. 合并重复或相近提交。
|
||||
2. 删除无意义提交，例如格式化、临时调试、无关重构。
|
||||
3. 将内部实现描述改写为用户可理解的变更。
|
||||
4. 每条使用完整中文句子。
|
||||
5. 尽量说明“修复/优化了什么”以及“带来的效果”。
|
||||
6. 不要编造 commit log 中没有的信息。
|
||||
7. 不要加入 token、密钥、私有地址等敏感信息。
|
||||
8. 如果某个分类没有内容，可以省略。
|
||||
|
||||
固定使用以下分类：
|
||||
|
||||
text ### 🛠 修复 ### ⚡️ 优化与改进 ### 💄 其他/体验
|
||||
|
||||
分类规则：
|
||||
|
||||
- Bug、异常行为、错误逻辑：放入 ### 🛠 修复
|
||||
- 性能、稳定性、接口、架构、兼容性：放入 ### ⚡️ 优化与改进
|
||||
- 日志、文案、UI、文档、开发体验：放入 ### 💄 其他/体验
|
||||
|
||||
示例:
|
||||
|
||||
```
|
||||
### 🛠 修复
|
||||
- 修复了通过 MCP 接口操作时笔记库范围限制未正确生效的问题。
|
||||
- 修复了 MCP 接口返回数据格式不一致的问题。
|
||||
- 修复了 WebSocket 客户端异常断开后僵尸连接未及时清理的问题。
|
||||
|
||||
### ⚡️ 优化与改进
|
||||
- 优化了 WebGUI 登录机制，引入设备令牌自动轮转，减少因 IP 变化产生的冗余令牌。
|
||||
|
||||
### 💄 其他/体验
|
||||
- 优化了 WebSocket 错误日志，增加请求路径信息，方便问题排查。
|
||||
```
|
||||
|
||||
## 提交
|
||||
|
||||
生成完 Commit Message 后调用命令工具修改最后一次提交信息, 不要提交, 不要推送, 你的任务到此结束。
|
||||
@@ -32,8 +32,36 @@ permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
prepare-message:
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
commit_msg: ${{ steps.trans.outputs.commit_msg }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ github.ref }}
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Prepare Commit Message
|
||||
id: trans
|
||||
shell: bash
|
||||
run: |
|
||||
msg=$(git log -1 --pretty=%B)
|
||||
pip install deep-translator > /dev/null 2>&1 || true
|
||||
|
||||
export COMMIT_MSG="$msg"
|
||||
echo "commit_msg<<EOF" >> "$GITHUB_OUTPUT"
|
||||
if [ -f "scripts/translate_commit.py" ]; then
|
||||
python3 scripts/translate_commit.py >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "Translation script not found, using raw message"
|
||||
echo "$msg" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
echo "EOF" >> "$GITHUB_OUTPUT"
|
||||
|
||||
create-release:
|
||||
name: Create Release
|
||||
needs: prepare-message
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
version: ${{ steps.metadata.outputs.version }}
|
||||
@@ -75,7 +103,7 @@ jobs:
|
||||
with:
|
||||
tag_name: ${{ steps.metadata.outputs.version }}
|
||||
name: ${{ steps.metadata.outputs.version }}
|
||||
generate_release_notes: true
|
||||
body: ${{ needs.prepare-message.outputs.commit_msg }}
|
||||
prerelease: ${{ contains(steps.metadata.outputs.version, 'alpha') || contains(steps.metadata.outputs.version, 'beta') || contains(steps.metadata.outputs.version, 'rc') }}
|
||||
|
||||
build-frontend:
|
||||
|
||||
@@ -1,17 +1,34 @@
|
||||
# Wavelet Agent 索引
|
||||
# AGENTS.md — 项目AI助手工作操作手册
|
||||
|
||||
本文件是 Wavelet 项目中 Agent 工作的项目级指南。更具体的专门工作流仍保留在 `.agent/skills/` 中。
|
||||
本文件面向 AI 开发助手，定义其职责与操作规范。
|
||||
|
||||
## Git 提交规范指南
|
||||
|
||||
### 提交信息基本格式
|
||||
|
||||
每次提交更改时，应当使用以下提交格式:
|
||||
|
||||
```text
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
```
|
||||
|
||||
* **Type**: 提交类型（例如 `feat`, `fix`, `refactor`, `perf`, `docs`, `chore` 等）。
|
||||
* **Scope** (可选): 影响的范围（例如 `api`, `frontend`, `auth`, `mcp` 等）。
|
||||
* **Subject**: 简短的一句话描述变更。
|
||||
* **Body** (可选): 详细的说明，多行叙述。
|
||||
|
||||
## 务必阅读匹配的 Skill
|
||||
|
||||
- `new-api`：在添加或修改自定义业务 API、Handler、服务层逻辑或注册自定义端点时使用。
|
||||
- `new-async-task`：在添加或修改 Asynq 任务、定时任务、任务元数据、任务负载验证、任务日志、任务重试行为或 Admin 任务 API 时使用。
|
||||
- `new-setting`：在添加或修改启动配置、基于数据库的系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置时使用。
|
||||
- `database-migration`：在添加或修改数据库 Schema、索引、Seed 数据、系统配置默认值、模板默认值、默认管理员数据、goose SQL 迁移或数据库升级流程时使用。
|
||||
- `new-async-task`：在添加或修改 Asynq 任务、定时任务时使用。
|
||||
- `new-setting`：在添加或修改基于数据库的系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置时使用。
|
||||
- `database-migration`：在数据库升级流程时使用。
|
||||
- Go skills：使用针对性的 `go-*` skills 来获取 Go 实现细节，如测试、错误处理、包、Context、并发、日志、文档和审查。
|
||||
- `shadcn`：在添加、修改或组合 shadcn/ui 组件时使用。
|
||||
|
||||
## 不可逾越的项目红线 (Guardrails)
|
||||
## 严格遵循事项 (Guardrails)
|
||||
|
||||
- 切勿删除 `frontend/node_modules`；如果需要刷新依赖，请使用 `pnpm install` 重新安装。
|
||||
- 保持 `internal/util/` 不引入任何框架。不要从 `internal/util/` 及其子包中导入 Gin、GORM、sessions 或其他 HTTP/框架包。
|
||||
@@ -20,33 +37,14 @@
|
||||
- 在提交更改前运行 `make code-check`。
|
||||
- 需要缓存或文件管理能力时，必须复用现有平台实现，禁止在业务包中自行创建缓存目录、直接管理缓存文件或重复封装存储后端。
|
||||
|
||||
## 缓存与文件能力
|
||||
## 项目介绍
|
||||
|
||||
- `internal/diskcache`：通过 `diskcache.GetGlobalCache()` 提供字节缓存读写、TTL、最大空间限制、LRU 淘汰、清空、状态统计和配置热更新。写入时使用 `DefaultExpiration`（全局默认 TTL）、正数 `time.Duration`（业务 TTL）或 `NoExpiration`（值为 `-1`，永不过期）；永久缓存仍受空间限制和 LRU 淘汰。
|
||||
- `internal/storage`：提供 S3 兼容对象上传、读取、删除、CDN/代理读取及远端文件本地缓存。
|
||||
- `internal/apps/upload`：提供上传记录、文件访问控制、本地/S3 文件响应、下载及图片 WebP 压缩；业务应复用这些入口，不直接操作底层文件。
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 适用场景 |
|
||||
| --- | --- |
|
||||
| `make code-check` | 提交前的必要检查 |
|
||||
| `make build-test` | 功能性构建验证 |
|
||||
| `make swagger` | 添加/修改 API 后 |
|
||||
| `make build-embedded` | 发布带有内嵌前端的二进制文件 |
|
||||
| `make license` | 添加 Go 文件后 |
|
||||
| `make license-check` | CI/许可证验证 |
|
||||
|
||||
# Wavelet 项目开发指南
|
||||
|
||||
本指南用于普通的 Wavelet 开发。如果任务是关于 Asynq/后台/定时任务的，请使用 `new-async-task` 作为详细的工作流。
|
||||
|
||||
## 技术栈
|
||||
### 技术栈
|
||||
|
||||
- 后端：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2、Snowflake IDs。
|
||||
- 前端：Next.js App Router、TypeScript、Tailwind CSS、pnpm、shadcn/ui。
|
||||
|
||||
## 目录结构映射
|
||||
### 目录结构与平台能力
|
||||
|
||||
顶层目录：
|
||||
|
||||
@@ -58,17 +56,19 @@
|
||||
- `frontend/`：Next.js 应用。
|
||||
- `internal/`：私有 Go 后端代码。
|
||||
- `scripts/`：本地和 CI 辅助脚本。
|
||||
- `support-files/`：辅助部署文件。
|
||||
- `support-files/`：部署和数据库辅助文件。
|
||||
|
||||
后端目录：
|
||||
|
||||
- `internal/cmd/`：用于 API、worker、scheduler、root init 的 Cobra 命令。
|
||||
- `internal/config/`：Viper 加载和配置结构体。运行时代码应使用 `config.Config.<Section>.<Field>`。
|
||||
- `internal/router/`：唯一的 HTTP 路由注册点。
|
||||
- `internal/apps/`：功能模块和 HTTP Handler。
|
||||
- `internal/apps/`：按领域组织的 HTTP Handler 和模块逻辑；管理端模块位于 `internal/apps/admin/`。
|
||||
- `internal/apps/upload/`：上传记录、文件访问控制、本地/S3 文件响应、下载及图片 WebP 压缩。业务应复用这些入口，不直接操作底层文件。
|
||||
- `internal/model/`：GORM 实体和模型级业务方法。
|
||||
- `internal/db/`：PostgreSQL、Redis、ClickHouse、GORM 日志、ID 生成和 goose SQL 迁移的布线。
|
||||
- `internal/storage/`：兼容 S3 的存储和缓存抽象。
|
||||
- `internal/diskcache/`：平台级磁盘字节缓存，通过 `diskcache.GetGlobalCache()` 提供 TTL、最大空间限制、LRU 淘汰、清空、状态统计和配置热更新。写入时使用 `DefaultExpiration`（全局默认 TTL）、正数 `time.Duration`（业务 TTL）或 `NoExpiration`（无 TTL，仍受空间限制和 LRU 淘汰）。
|
||||
- `internal/storage/`：S3 兼容对象存储适配，提供对象上传、读取、删除、CDN/代理读取及远端对象本地缓存。
|
||||
- `internal/task/`：Asynq 任务框架；参见 `new-async-task` 了解变更。
|
||||
- `internal/service/`：当 Handler/Model 层次过于狭窄时使用的复杂业务服务。
|
||||
- `internal/common/`：共享的响应、绑定（bind）、常量以及通用错误。
|
||||
@@ -76,6 +76,7 @@
|
||||
- `internal/logger/`：Zap 和 OTel 日志助手。
|
||||
- `internal/listener/`：事件监听器和消息/Webhook 消费者。
|
||||
- `internal/otel_trace/`：链路追踪（tracing）助手。
|
||||
- `internal/testhelper/`：后端测试共享辅助能力。
|
||||
|
||||
前端目录：
|
||||
|
||||
@@ -84,19 +85,27 @@
|
||||
- `frontend/components/common/`：跨页面的业务组件。
|
||||
- `frontend/components/layout/`：Header、Sidebar、Footer 等应用布局组件。
|
||||
- `frontend/components/auth/`、`home/`、`animate-ui/`、`providers/`：特定作用域的 UI 组件。
|
||||
- `frontend/contexts/`、`hooks/`、`lib/`、`types/`、`public/`：共享状态、Hook、客户端/实用工具、TypeScript 类型、静态资产。
|
||||
- `frontend/lib/services/`：基于 `BaseService` 的类型化 API 服务，按业务域拆分并由 `services` 对象统一导出。
|
||||
- `frontend/contexts/`、`hooks/`、`lib/`、`types/`、`public/`：共享状态、Hook、客户端与实用工具、TypeScript 类型、静态资产。
|
||||
- `frontend/scripts/`：前端构建和维护脚本。
|
||||
- `frontend/.next/`、`frontend/out/`、`frontend/node_modules/`：本地生成或安装的产物，不作为业务源码编辑。
|
||||
|
||||
重要的公共组件：
|
||||
|
||||
- `components/common/admin/tasks.tsx`：任务分发 UI。
|
||||
- `components/common/admin/task-executions.tsx`：任务执行日志/重试 UI。
|
||||
- `components/common/admin/system.tsx`：系统配置管理。
|
||||
- `components/common/admin/users.tsx`：用户管理。
|
||||
- `components/common/general/manage-pannel.tsx`：通用的列表/详情管理器。
|
||||
- `components/common/general/password-dialog.tsx`：敏感操作密码确认对话框。
|
||||
- `components/common/settings/system-settings.tsx`：管理员系统设置。
|
||||
- `frontend/components/common/admin/task-manager.tsx`：任务管理和分发入口。
|
||||
- `frontend/components/common/admin/task-executions.tsx`：任务执行日志和重试 UI。
|
||||
- `frontend/components/common/admin/task-schedules.tsx`：定时任务管理 UI。
|
||||
- `frontend/components/common/admin/system.tsx`：系统参数管理。
|
||||
- `frontend/components/common/admin/files.tsx`：上传文件管理。
|
||||
- `frontend/components/common/admin/users.tsx`：用户管理。
|
||||
- `frontend/components/common/general/manage-pannel.tsx`：通用列表/详情管理器。
|
||||
- `frontend/components/common/general/password-dialog.tsx`：敏感操作密码确认对话框。
|
||||
- `frontend/components/common/settings/system-settings.tsx`：管理员图形化系统设置。
|
||||
|
||||
## 后端规则
|
||||
|
||||
## 开发要求
|
||||
|
||||
### 后端规则
|
||||
|
||||
命名规范：
|
||||
|
||||
@@ -168,16 +177,10 @@ Handler 规范：
|
||||
4. 在 `internal/router/router.go` 中注册路由。
|
||||
5. 运行 `make swagger`。
|
||||
|
||||
## 前端规则
|
||||
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
|
||||
# Next.js: 在编码前务必阅读文档
|
||||
### 前端规则
|
||||
|
||||
在进行任何 Next.js 工作之前，请在 `node_modules/next/dist/docs/` 中找到并阅读相关文档。您的训练数据已过时 —— 这些文档是唯一的真理来源。
|
||||
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
样式规范：
|
||||
|
||||
- shadcn/ui 基础组件应该使用它们的 `variant` 系统和全局 CSS 变量。当组件的变体（variant）应该拥有某种外观时，不要在业务 `className` 中硬编码颜色、背景或阴影。
|
||||
@@ -209,14 +212,3 @@ frontend/lib/services/<service-name>/
|
||||
|
||||
- 服务类继承 `BaseService`，定义 `basePath`，并暴露有类型的静态方法。
|
||||
- 在 `frontend/lib/services/index.ts` 中注册新服务。
|
||||
|
||||
## 质量门禁 (Quality Gates)
|
||||
|
||||
- `make code-check`：提交前的必要检查；前端类型检查 + ESLint 以及后端 golangci-lint。
|
||||
- `make build-test`：前端和 Go 后端的构建验证。
|
||||
- `make swagger`：API 变更后重新生成 Swagger。
|
||||
- `make build-embedded`：发布带有前端静态导出嵌入的二进制文件。
|
||||
- `make license`：添加 Go 文件后运行。
|
||||
- `make license-check`：验证 Go 许可证头。
|
||||
|
||||
切勿删除 `frontend/node_modules`；使用 `pnpm install` 刷新依赖。
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
import os
|
||||
import sys
|
||||
from deep_translator import GoogleTranslator
|
||||
|
||||
def main():
|
||||
# Get message from environment variable or command line argument
|
||||
msg = os.environ.get('COMMIT_MSG', '')
|
||||
if len(sys.argv) > 1:
|
||||
msg = sys.argv[1]
|
||||
|
||||
if not msg:
|
||||
print("No commit message found.")
|
||||
return
|
||||
|
||||
# Use a single instance of translators to potentially benefit from some caching if it exists
|
||||
translator_zh = GoogleTranslator(source='auto', target='zh-CN')
|
||||
translator_en = GoogleTranslator(source='auto', target='en')
|
||||
|
||||
lines = msg.split('\n')
|
||||
|
||||
for line in lines:
|
||||
# Extract leading whitespace (indentation)
|
||||
indent = line[:len(line) - len(line.lstrip())]
|
||||
content = line.strip()
|
||||
|
||||
if not content:
|
||||
print(line) # Preserve empty lines or lines with only spaces
|
||||
continue
|
||||
|
||||
try:
|
||||
# Translate only the content to avoid translator messing with indentation
|
||||
zh_trans = translator_zh.translate(content)
|
||||
en_trans = translator_en.translate(content)
|
||||
|
||||
# Re-apply indentation to both translations
|
||||
print(f"{indent}{zh_trans}")
|
||||
print(f"{indent}{en_trans}")
|
||||
|
||||
except Exception as e:
|
||||
# If translation fails, print original line (which contains indentation)
|
||||
print(f"{line}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user