添加完整的双语注释和测试兼容性优化

- 给所有导出函数和类型添加双语注释（英文+中文）
- 优化 Firefox 和 w3m 测试的 CI 环境兼容性
- 添加测试函数注释说明跳过实际浏览器打开的原因
- 确保所有包级别和关键函数都有详细的功能说明

Author: yangyile1990

firefoxopen/firefox_open_test.go

@@ -1 +1,22 @@
 package firefoxopen
+
+import (
+	"os/exec"
+	"testing"
+)
+
+// TestOpen verifies Firefox availability without opening browser
+// Checks Firefox command availability for CI compatibility testing
+// Skips actual browser opening to avoid disrupting test automation
+//
+// TestOpen 验证 Firefox 可用性而不打开浏览器
+// 检查 Firefox 命令可用性以进行 CI 兼容性测试
+// 跳过实际的浏览器打开以避免干扰测试自动化
+func TestOpen(t *testing.T) {
+	path, err := exec.LookPath("firefox")
+	if err != nil {
+		t.Skip("firefox is not available on this system, skipping test case")
+	}
+	t.Log("firefox path:", path)
+	t.Log("skipping open firefox to avoid interrupting testcase...")
+}

firefoxopen/firefox_show.go

@@ -10,13 +10,27 @@ import (
 	"github.com/yyle88/osexec"
 )
 
+// FirefoxShow manages Firefox browser automation with webpage output control
+// Provides coordinated webpage generation and Firefox opening with timing control
+// Handles temporary HTTP service and browser window management
+//
+// FirefoxShow 管理 Firefox 浏览器自动化与网页输出控制
+// 提供协调的网页生成和 Firefox 打开及时间控制
+// 处理临时 HTTP 服务和浏览器窗口管理
 type FirefoxShow struct {
 	service  *gintestpage.Service
 	command  *osexec.OsCommand
 	showTime time.Time
 	doneOnce *sync.Once
 }
 
+// NewFirefoxShow creates Firefox automation instance with custom service and command
+// Initializes browser automation using provided HTTP service and OS command configuration
+// Returns configured Firefox automation handler for coordinated browser operations
+//
+// NewFirefoxShow 使用自定义服务和命令创建 Firefox 自动化实例
+// 使用提供的 HTTP 服务和操作系统命令配置初始化浏览器自动化
+// 返回配置的 Firefox 自动化处理器以实现协调的浏览器操作
 func NewFirefoxShow(service *gintestpage.Service, command *osexec.OsCommand) *FirefoxShow {
 	return &FirefoxShow{
 		service:  service,
@@ -26,23 +40,55 @@ func NewFirefoxShow(service *gintestpage.Service, command *osexec.OsCommand) *Fi
 	}
 }
 
+// NewFirefoxDraw creates Firefox automation with default configuration for development
+// Initializes browser automation using default HTTP test service and debug command setup
+// Returns ready-to-use Firefox automation handler with optimal development settings
+//
+// NewFirefoxDraw 使用开发的默认配置创建 Firefox 自动化
+// 使用默认 HTTP 测试服务和调试命令设置初始化浏览器自动化
+// 返回具有优化开发设置的即用 Firefox 自动化处理器
 func NewFirefoxDraw() *FirefoxShow {
 	return NewFirefoxShow(gintestpage.NewService(), osexec.NewOsCommand().WithDebug())
 }
 
+// Close terminates Firefox automation after specified wait time
+// Waits for remaining time based on when pages were shown and closes HTTP service
+// Uses sync.Once to ensure cleanup happens exactly once
+//
+// Close 在指定等待时间后终止 Firefox 自动化
+// 根据页面显示时间等待剩余时间并关闭 HTTP 服务
+// 使用 sync.Once 确保清理操作仅执行一次
 func (op *FirefoxShow) Close(waitTime time.Duration) {
 	op.doneOnce.Do(func() {
 		time.Sleep(waitTime - time.Since(op.showTime))
 		op.service.Close()
 	})
 }
 
+// ShowInNewWindows displays HTML pages in separate Firefox windows
+// Opens each page in its own Firefox window for independent viewing
+// Creates temporary URLs and launches Firefox with --new-window option
+//
+// ShowInNewWindows 在单独的 Firefox 窗口中显示 HTML 页面
+// 在独立的 Firefox 窗口中打开每个页面以供独立查看
+// 创建临时 URL 并使用 --new-window 选项启动 Firefox
 func (op *FirefoxShow) ShowInNewWindows(pages ...string) {
-	op.Show(pages, "--new-window") //打开若干个新窗口以打开若干个网页
+	op.Open(pages, "--new-window") //打开若干个新窗口以打开若干个网页
 }
 
+// ShowInNewTabs displays HTML pages in new Firefox tabs
+// Opens each page in a new tab within existing or new Firefox window
+// Creates temporary URLs and launches Firefox with --new-tab option
+//
+// ShowInNewTabs 在新的 Firefox 标签中显示 HTML 页面
+// 在现有或新的 Firefox 窗口的新标签中打开每个页面
+// 创建临时 URL 并使用 --new-tab 选项启动 Firefox
 func (op *FirefoxShow) ShowInNewTabs(pages ...string) {
-	op.Show(pages, "--new-tab") //打开若干个新标签以打开若干个网页
+	op.Open(pages, "--new-tab") //打开若干个新标签以打开若干个网页
+}
+
+func (op *FirefoxShow) Open(pages []string, openOption string) {
+	op.Show(pages, openOption)
 }
 
 func (op *FirefoxShow) Show(pages []string, openOption string) {

firefoxopen/firefox_show_test.go

@@ -1 +1,22 @@
 package firefoxopen
+
+import (
+	"os/exec"
+	"testing"
+)
+
+// TestFirefoxShow_Open verifies Firefox availability without opening browser
+// Checks Firefox command availability for CI compatibility testing
+// Skips actual browser opening to avoid disrupting test automation
+//
+// TestFirefoxShow_Open 验证 Firefox 可用性而不打开浏览器
+// 检查 Firefox 命令可用性以进行 CI 兼容性测试
+// 跳过实际的浏览器打开以避免干扰测试自动化
+func TestFirefoxShow_Open(t *testing.T) {
+	path, err := exec.LookPath("firefox")
+	if err != nil {
+		t.Skip("firefox is not available on this system, skipping test case")
+	}
+	t.Log("firefox path:", path)
+	t.Log("skipping open firefox to avoid interrupting testcase...")
+}

gintestpage/gin_test_page.go

@@ -21,11 +21,25 @@ import (
 	"github.com/yyle88/syncmap"
 )
 
+// Service provides HTTP test server functionality with dynamic page hosting
+// Manages temporary HTTP server and in-memory page storage for testing
+// Enables rapid webpage content serving with unique URL generation
+//
+// Service 提供带有动态页面托管的 HTTP 测试服务器功能
+// 管理临时 HTTP 服务器和内存中的页面存储以供测试
+// 启用具有唯一 URL 生成的快速网页内容服务
 type Service struct {
 	srvTest *httptest.Server
 	pageMap *syncmap.Map[string, []byte]
 }
 
+// NewService creates HTTP test server instance with Gin framework integration
+// Initializes temporary HTTP server with dynamic page routing capabilities
+// Returns configured service ready for webpage hosting and URL generation
+//
+// NewService 创建与 Gin 框架集成的 HTTP 测试服务器实例
+// 初始化具有动态页面路由功能的临时 HTTP 服务器
+// 返回准备好进行网页托管和 URL 生成的配置服务
 func NewService() *Service {
 	pageMap := syncmap.New[string, []byte]()
 
@@ -47,16 +61,37 @@ func NewService() *Service {
 	}
 }
 
+// Close terminates HTTP test server and releases resources
+// Stops the temporary HTTP server and cleans up network resources
+// Should be called when testing is complete
+//
+// Close 终止 HTTP 测试服务器并释放资源
+// 停止临时 HTTP 服务器并清理网络资源
+// 应在测试完成时调用
 func (service *Service) Close() {
 	service.srvTest.Close()
 }
 
+// SetPage registers HTML page content at specified path and returns access URL
+// Stores page content in memory and generates accessible URL for the content
+// Path must not contain slash characters for security
+//
+// SetPage 在指定路径注册 HTML 页面内容并返回访问 URL
+// 将页面内容存储在内存中并为内容生成可访问的 URL
+// 出于安全考虑，路径不能包含斜杠字符
 func (service *Service) SetPage(path string, page []byte) string {
 	muststrings.NotContains(must.Nice(path), "/")
 	service.pageMap.Store(path, page)
 	return service.GetLink(path)
 }
 
+// GetLink generates complete URL for specified path on test server
+// Constructs full HTTP URL using test server base and provided path
+// Path must not contain slash characters for security
+//
+// GetLink 为测试服务器上的指定路径生成完整 URL
+// 使用测试服务器基础地址和提供的路径构建完整 HTTP URL
+// 出于安全考虑，路径不能包含斜杠字符
 func (service *Service) GetLink(path string) string {
 	muststrings.NotContains(must.Nice(path), "/")
 	return rese.C1(url.JoinPath(service.srvTest.URL, path))

w3mopenpage/w3m_open_page.go

@@ -1,3 +1,12 @@
+// Package w3mopenpage: W3m console browser automation for webpage output
+// Provides command-line webpage rendering using w3m text browser
+// Enables HTML content display in console environment with text-based output
+// Supports both URL opening and direct HTML content processing via w3m
+//
+// w3mopenpage: 用于网页输出的 W3m 控制台浏览器自动化
+// 使用 w3m 文本浏览器提供命令行网页渲染
+// 在控制台环境中启用 HTML 内容显示，提供基于文本的输出
+// 支持通过 w3m 进行 URL 打开和直接 HTML 内容处理
 package w3mopenpage
 
 import (
@@ -9,11 +18,25 @@ import (
 	"github.com/yyle88/zaplog"
 )
 
+// Open displays webpage content from URL using w3m browser in console
+// Executes w3m with -dump option to render webpage as text output
+// Logs rendered webpage content for console-based webpage viewing
+//
+// Open 使用 w3m 浏览器在控制台中显示来自 URL 的网页内容
+// 使用 -dump 选项执行 w3m 以将网页渲染为文本输出
+// 记录渲染的网页内容以供基于控制台的网页查看
 func Open(command *osexec.OsCommand, link string) {
 	output := rese.V1(command.Exec("w3m", "-dump", link))
 	zaplog.SUG.Debug("[page]:", "\n", string(output), "\n", "----")
 }
 
+// Show renders HTML content directly using w3m browser via stdin input
+// Executes w3m with HTML input to display content as console text output
+// Processes HTML strings and displays formatted text results
+//
+// Show 通过 stdin 输入使用 w3m 浏览器直接渲染 HTML 内容
+// 使用 HTML 输入执行 w3m 以将内容显示为控制台文本输出
+// 处理 HTML 字符串并显示格式化的文本结果
 func Show(command *osexec.OsCommand, page string) {
 	output := rese.V1(command.ExecWith("w3m", []string{"-T", "text/html", "-dump"}, func(command *exec.Cmd) {
 		command.Stdin = strings.NewReader(page)

w3mopenpage/w3m_open_page_test.go

@@ -1,6 +1,7 @@
 package w3mopenpage_test
 
 import (
+	"os/exec"
 	"testing"
 
 	"github.com/brianvoe/gofakeit/v7"
@@ -12,6 +13,11 @@ import (
 )
 
 func TestShow(t *testing.T) {
+	path, err := exec.LookPath("w3m")
+	if err != nil {
+		t.Skip("w3m is not available on this system, skipping test case")
+	}
+	t.Log("w3m path:", path)
 	w3mopenpage.Show(osexec.NewOsCommand().WithDebug(), utils.NewPage("标题1", "内容1"))
 }
 
@@ -29,6 +35,11 @@ func newAccount() *Account {
 }
 
 func TestShowPage(t *testing.T) {
+	path, err := exec.LookPath("w3m")
+	if err != nil {
+		t.Skip("w3m is not available on this system, skipping test case")
+	}
+	t.Log("w3m path:", path)
 	w3mopenpage.Show(osexec.NewOsCommand().WithDebug(), utils.NewPage("accounts", slice2table.NewTable([]*Account{
 		newAccount(),
 		newAccount(),

w3mopenpage/w3m_show_page.go

@@ -6,32 +6,74 @@ import (
 	"github.com/yyle88/osexec"
 )
 
+// W3mShowPage manages w3m browser automation with webpage output control
+// Provides coordinated webpage generation and w3m opening with HTTP service
+// Handles temporary HTTP service and console browser operations
+//
+// W3mShowPage 管理 w3m 浏览器自动化与网页输出控制
+// 提供协调的网页生成和 w3m 打开及 HTTP 服务
+// 处理临时 HTTP 服务和控制台浏览器操作
 type W3mShowPage struct {
 	service *gintestpage.Service
 	command *osexec.OsCommand
 }
 
+// NewW3mShowPage creates w3m automation instance with custom service and command
+// Initializes console browser automation using provided HTTP service and OS command configuration
+// Returns configured w3m automation handler for coordinated console browser operations
+//
+// NewW3mShowPage 使用自定义服务和命令创建 w3m 自动化实例
+// 使用提供的 HTTP 服务和操作系统命令配置初始化控制台浏览器自动化
+// 返回配置的 w3m 自动化处理器以实现协调的控制台浏览器操作
 func NewW3mShowPage(service *gintestpage.Service, command *osexec.OsCommand) *W3mShowPage {
 	return &W3mShowPage{
 		service: service,
 		command: command,
 	}
 }
 
+// NewW3mDrawPage creates w3m automation with default configuration for development
+// Initializes console browser automation using default HTTP test service and debug command setup
+// Returns ready-to-use w3m automation handler with optimal development settings
+//
+// NewW3mDrawPage 使用开发的默认配置创建 w3m 自动化
+// 使用默认 HTTP 测试服务和调试命令设置初始化控制台浏览器自动化
+// 返回具有优化开发设置的即用 w3m 自动化处理器
 func NewW3mDrawPage() *W3mShowPage {
 	return NewW3mShowPage(gintestpage.NewService(), osexec.NewOsCommand().WithDebug())
 }
 
+// Close terminates w3m automation and shuts down HTTP service
+// Stops the temporary HTTP test service used for webpage hosting
+// Cleans up resources used by w3m automation instance
+//
+// Close 终止 w3m 自动化并关闭 HTTP 服务
+// 停止用于网页托管的临时 HTTP 测试服务
+// 清理 w3m 自动化实例使用的资源
 func (op *W3mShowPage) Close() {
 	op.service.Close()
 }
 
+// Show displays single HTML page content using w3m browser in console
+// Creates temporary URL for HTML content and opens it via w3m for console viewing
+// Generates unique path and serves page through HTTP service
+//
+// Show 使用 w3m 浏览器在控制台中显示单个 HTML 页面内容
+// 为 HTML 内容创建临时 URL 并通过 w3m 打开以供控制台查看
+// 生成唯一路径并通过 HTTP 服务提供页面
 func (op *W3mShowPage) Show(page string) {
 	path := uuid.New().String()
 	link := op.service.SetPage(path, []byte(page))
 	Open(op.command, link)
 }
 
+// ShowPages displays multiple HTML pages sequentially using w3m browser
+// Creates temporary URLs for each HTML page and opens them via w3m for console viewing
+// Processes pages in order with unique paths for each page
+//
+// ShowPages 使用 w3m 浏览器依序显示多个 HTML 页面
+// 为每个 HTML 页面创建临时 URL 并通过 w3m 打开以供控制台查看
+// 为每个页面使用唯一路径按顺序处理页面
 func (op *W3mShowPage) ShowPages(pages ...string) {
 	for _, page := range pages {
 		path := uuid.New().String()

w3mopenpage/w3m_show_page_test.go

@@ -1,6 +1,7 @@
 package w3mopenpage_test
 
 import (
+	"os/exec"
 	"testing"
 
 	"github.com/brianvoe/gofakeit/v7"
@@ -21,6 +22,11 @@ func TestMain(m *testing.M) {
 }
 
 func TestW3mShowPage_Show(t *testing.T) {
+	path, err := exec.LookPath("w3m")
+	if err != nil {
+		t.Skip("w3m is not available on this system, skipping test case")
+	}
+	t.Log("w3m path:", path)
 	caseDrawPage.Show(utils.NewPage("标题1", "内容1"))
 }
 
@@ -37,6 +43,11 @@ func newEmployee() *Employee {
 }
 
 func TestW3mShowPage_ShowPage(t *testing.T) {
+	path, err := exec.LookPath("w3m")
+	if err != nil {
+		t.Skip("w3m is not available on this system, skipping test case")
+	}
+	t.Log("w3m path:", path)
 	caseDrawPage.Show(utils.NewPage("employees", slice2table.NewTable([]*Employee{
 		newEmployee(),
 		newEmployee(),