feat: 对照官方 CLI 全量对齐——修复契约缺陷、补齐能力、技能与版本绑定（v1.42.0）

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+# 最小 CI：只做离线检查，不使用任何飞书凭证、不调用线上 API。
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+env:
+  # 测试与 Skill 检查全部走内嵌 OpenAPI catalog，不拉远端 overlay
+  FEISHU_CLI_REMOTE_META: "off"
+
+jobs:
+  go:
+    name: gofmt / vet / test
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - name: gofmt
+        run: |
+          unformatted="$(gofmt -l .)"
+          if [ -n "$unformatted" ]; then
+            echo "$unformatted"
+            echo "::error::存在未格式化的 Go 文件，请运行 gofmt -w 后提交"
+            exit 1
+          fi
+      - name: go vet
+        run: go vet ./...
+      - name: go test
+        run: go test -count=1 ./...
+
+  skills-privacy:
+    name: check-skills / check-privacy
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      # Skill 检查与脚本回归只用 Python 标准库（YAML 由 go run ./scripts/skillmeta 解析），无需 pip 依赖
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - name: 隐私扫描
+        run: make check-privacy
+      - name: Skill 结构、命令归属与离线契约
+        run: make check-skills

.gitignore

@@ -28,8 +28,9 @@ vendor/
 .DS_Store
 Thumbs.db
 
-# GitHub 临时文件（PR 截图等）
-.github/
+# GitHub 临时文件（PR 截图等）；CI 工作流需要入库
+.github/*
+!.github/workflows/
 
 # 配置文件（包含敏感信息）
 .env

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build check-skills check-skill-contracts clean install test lint fmt help update-meta
+.PHONY: build check-skills check-skill-contracts check-privacy release-package clean install test lint fmt help update-meta
 
 # Go parameters
 GOCMD=go
@@ -41,6 +41,10 @@ check-skills: build
 check-skill-contracts: build
 	python3 scripts/check_skill_contracts.py ./$(BUILD_DIR)/$(BINARY_NAME)
 
+## check-privacy: Scan tracked files for internal emails, tenant-prefixed Feishu domains and real-looking tokens
+check-privacy:
+	python3 scripts/check_privacy.py
+
 ## install: Install the binary to $GOPATH/bin
 install:
 	$(GOBUILD) $(LDFLAGS) -o $(GOPATH)/bin/$(BINARY_NAME) .
@@ -92,6 +96,13 @@ build-windows:
 	@mkdir -p $(BUILD_DIR)
 	CGO_ENABLED=0 GOOS=windows GOARCH=amd64 $(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe .
 
+## release-package: Build 5 platform tar.gz + checksums.txt into dist/ with self-check (make release-package VERSION=vX.Y.Z)
+release-package:
+	@if [ "$(origin VERSION)" != "command line" ]; then \
+		echo "请显式指定发布版本: make release-package VERSION=vX.Y.Z" >&2; exit 2; \
+	fi
+	bash scripts/release_package.sh "$(VERSION)" dist
+
 ## run: Run the application
 run: build
 	./$(BUILD_DIR)/$(BINARY_NAME)

cmd/add_board.go

@@ -10,12 +10,12 @@ import (
 )
 
 var addBoardCmd = &cobra.Command{
-	Use:   "add-board <document_id>",
+	Use:   "add-board <document_id|url>",
 	Short: "添加画板到文档",
 	Long: `向飞书文档添加画板块。
 
 参数:
-  <document_id>  文档 ID（必填）
+  <document_id>  文档 ID 或 URL（必填；/wiki/ URL 自动解析为底层文档）
   --parent-id    父块 ID，空表示根级别，默认空
   --index        插入位置索引，-1 表示末尾，默认 -1
   --output, -o   输出格式 (json)
@@ -39,11 +39,15 @@ var addBoardCmd = &cobra.Command{
 			return err
 		}
 
-		documentID := args[0]
 		parentID, _ := cmd.Flags().GetString("parent-id")
 		index, _ := cmd.Flags().GetInt("index")
 		output, _ := cmd.Flags().GetString("output")
 		userAccessToken := resolveOptionalUserToken(cmd)
+		// 支持文档 ID、/docx/ URL 与 /wiki/ URL（wiki 自动解包为底层 docx 的 obj_token）
+		documentID, err := resolveDocxArg(args[0], "<document_id|url>", userAccessToken)
+		if err != nil {
+			return err
+		}
 
 		// 如果父块 ID 为空，使用文档根节点
 		if parentID == "" {

cmd/add_callout.go

@@ -13,19 +13,19 @@ import (
 // callout 类型对应的背景色
 // 飞书 Callout 背景色值: 1-灰色, 2-红色, 3-橙色, 4-黄色, 5-绿色, 6-蓝色, 7-紫色
 var calloutTypeConfig = map[string]int{
-	"info":    6, // 蓝色
-	"warning": 4, // 黄色
-	"error":   2, // 红色
-	"success": 5, // 绿色
+	"info":    converter.CalloutBgLightBlue,   // 蓝色（5）
+	"warning": converter.CalloutBgLightYellow, // 黄色（3）
+	"error":   converter.CalloutBgLightRed,    // 红色（1）
+	"success": converter.CalloutBgLightGreen,  // 绿色（4）
 }
 
 var addCalloutCmd = &cobra.Command{
-	Use:   "add-callout <document_id> <content>",
+	Use:   "add-callout <document_id|url> <content>",
 	Short: "添加高亮块",
 	Long: `向飞书文档添加高亮块（Callout）。
 
 参数:
-  <document_id>    文档 ID（必填）
+  <document_id>    文档 ID 或 URL（必填；/wiki/ URL 自动解析为底层文档）
   <content>        高亮块内容（必填）
   --parent-id      父块 ID，空表示根级别，默认空
   --index          插入位置索引，-1 表示末尾，默认 -1
@@ -57,14 +57,18 @@ var addCalloutCmd = &cobra.Command{
 			return err
 		}
 
-		documentID := args[0]
 		content := args[1]
 		parentID, _ := cmd.Flags().GetString("parent-id")
 		index, _ := cmd.Flags().GetInt("index")
 		calloutType, _ := cmd.Flags().GetString("callout-type")
 		icon, _ := cmd.Flags().GetString("icon")
 		output, _ := cmd.Flags().GetString("output")
 		userAccessToken := resolveOptionalUserToken(cmd)
+		// 支持文档 ID、/docx/ URL 与 /wiki/ URL（wiki 自动解包为底层 docx 的 obj_token）
+		documentID, err := resolveDocxArg(args[0], "<document_id|url>", userAccessToken)
+		if err != nil {
+			return err
+		}
 
 		// 获取 callout 类型配置
 		bgColor, ok := calloutTypeConfig[calloutType]

cmd/add_comment.go

@@ -19,15 +19,17 @@ var addCommentCmd = &cobra.Command{
   --text        评论内容（必填）
 
 身份说明:
-  默认以 App Token（Bot 身份）创建；推荐 feishu-cli auth login 后传 --user-access-token，
-  以用户身份创建评论。Bot 身份创建的评论只能被同一 App 自身删除。
+  User 优先：--user-access-token > FEISHU_USER_ACCESS_TOKEN > auth login 保存的 token.json
+  （过期自动刷新）> config.yaml 的 user_access_token；都未配置时以 App Token（Bot 身份）创建。
+  已配置 User Token 但不可用（如刷新失败）时会在 stderr 告警后改用 App Token。
+  Bot 身份创建的评论只能被同一 App 自身删除；App 未被加为协作者的个人文档会得到 1069303 forbidden。
 
 示例:
-  # 添加评论（Bot 身份）
+  # 添加评论（已 auth login 时自动以用户身份创建）
+  feishu-cli auth login
   feishu-cli comment add doccnXXX --type docx --text "这是一条评论"
 
-  # 添加评论（用户身份，推荐）
-  feishu-cli auth login
+  # 显式指定 User Token
   feishu-cli comment add doccnXXX --type docx --text "这是一条评论" \
     --user-access-token "u-xxxxx"