From fd19fda4fdeca69d04ad1042c4d057779f662986 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=BA=90=E6=96=87=E9=9B=A8?=
 <41315874+fumiama@users.noreply.github.com>
Date: Sun, 21 Sep 2025 14:52:52 +0800
Subject: [PATCH] doc: add more docs

---
 .golangci.yml | 11 +++++++++--
 agent.go      |  3 +++
 perm.go       |  9 ++++++---
 types.go      |  1 +
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.golangci.yml b/.golangci.yml
index 6fca97b..c60f502 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -1,11 +1,15 @@
 linters-settings:
   errcheck:
-    ignore: fmt:.*,io/ioutil:^Read.*
     ignoretests: true
 
   goimports:
     local-prefixes: github.com/fumiama/go-onebot-agent
 
+  forbidigo:
+    # Forbid the following identifiers
+    forbid:
+      - ^fmt\.Errorf$ # consider errors.Errorf in github.com/pkg/errors
+
 linters:
   # please, do not use `enable-all`: it's deprecated and will be removed soon.
   # inverted configuration with `enable-all` and `disable` is not scalable during updates of golangci-lint
@@ -46,7 +50,6 @@ linters:
     - forbidigo
     - makezero
 
-
 run:
   # default concurrency is a available CPU number.
   # concurrency: 4 # explicitly omit this value to fully utilize available resources.
@@ -66,3 +69,7 @@ output:
 issues:
   # Fix found issues (if it's supported by the linter)
   fix: true
+  exclude-use-default: false
+  exclude:
+    - "Error return value of .((os.)?std(out|err)..*|.*Close|.*Seek|.*Flush|os.Remove(All)?|.*print(f|ln)?|os.(Un)?Setenv). is not check"
+    - 'identifier ".*" contain non-ASCII character: U\+.*'
diff --git a/agent.go b/agent.go
index 0810eb5..a71f494 100644
--- a/agent.go
+++ b/agent.go
@@ -1,3 +1,4 @@
+// Package goba OneBot 11 协议 QQ 聊天 Agent
 package goba
 
 import (
@@ -37,10 +38,12 @@ func NewAgent(
 	}
 }
 
+// AddEvent 添加接收到的事件
 func (ag *Agent) AddEvent(grp int64, ev *Event) {
 	ag.log.Add(grp, ev, false)
 }
 
+// AddRequest 一般无需主动调用, 由 GetAction 自动添加
 func (ag *Agent) AddRequest(grp int64, req *zero.APIRequest) {
 	ag.log.Add(grp, req, true)
 }
diff --git a/perm.go b/perm.go
index 98c8548..49bfe9d 100644
--- a/perm.go
+++ b/perm.go
@@ -15,22 +15,25 @@ var (
 	ErrUnexpectedAction = errors.New("unexpected action")
 )
 
+// PermRole 和 yaml config 一一对应
 type PermRole string
 
 const (
-	PermRoleOwner PermRole = "owner"
-	PermRoleAdmin PermRole = "admin"
-	PermRoleUser  PermRole = "user"
+	PermRoleOwner PermRole = "owner" // PermRoleOwner 群主或主人
+	PermRoleAdmin PermRole = "admin" // PermRoleAdmin 管理
+	PermRoleUser  PermRole = "user"  // PermRoleUser 普通用户
 )
 
 //go:embed actions.yaml
 var innerpermtable []byte
 
+// PermAction 记录 action 的描述和 params
 type PermAction struct {
 	Desc   string `yaml:"desc"`
 	Params string `yaml:"params"`
 }
 
+// Perm 即 actions.yaml 的 Go struct 映射
 type Perm struct {
 	Actions map[string]PermAction        `yaml:"actions"`
 	Config  map[PermRole][]string        `yaml:"config"`
diff --git a/types.go b/types.go
index 4e5625d..6cb1979 100644
--- a/types.go
+++ b/types.go
@@ -29,6 +29,7 @@ type Event struct {
 	Message     json.RawMessage `json:"message,omitempty"` // JSON 格式的消息内容
 }
 
+// String dumps JSON without tailing \n
 func (ev *Event) String() string {
 	sb := strings.Builder{}
 	err := json.NewEncoder(&sb).Encode(ev)