fix: 还原 README 到合并前版本

Merge origin/master into zk_branch, resolve conflicts in milestone/issue/README
Merge pull request '修改测试脚本' (#38 ) from mc_branch into master
2026-07-14 17:00:32 +08:00 · 2026-07-14 16:41:56 +08:00 · 2026-07-12 18:31:54 +08:00 · 2026-07-12 18:31:21 +08:00 · 2026-07-12 18:31:12 +08:00 · 2026-07-11 00:39:56 +08:00
185 changed files with 41955 additions and 3342 deletions
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@ -0,0 +1,107 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C \"C:\\\\Users\\\\Lenovo\\\\Desktop\\\\soft运维\\\\gitlink-cli\" rev-parse --git-common-dir)",
+      "Bash(git -C \"C:\\\\Users\\\\Lenovo\\\\Desktop\\\\soft运维\\\\gitlink-cli\" rev-parse --git-dir)",
+      "Bash(git:*)",
+      "Bash(wc -l \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/skills/gitlink-compliance/SKILL.md\" \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/skills/gitlink-compliance/references/\"*.md)",
+      "Bash(go build:*)",
+      "Bash(go vet:*)",
+      "Bash(wc -l \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/shortcuts/compliance/\"*.go)",
+      "Bash(wc -l \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/shortcuts/onboard/\"*.go)",
+      "Bash(# 复制两个 skill 到全局 agents 目录\ncp -r \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/skills/gitlink-compliance\" \"C:/Users/Lenovo/.agents/skills/gitlink-compliance\"\ncp -r \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/skills/gitlink-onboard\" \"C:/Users/Lenovo/.agents/skills/gitlink-onboard\"\n\n# 建立符号链接\ncd \"C:/Users/Lenovo/.claude/skills\" && cmd /c \"mklink /D gitlink-compliance C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-compliance\" && cmd /c \"mklink /D gitlink-onboard C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-onboard\")",
+      "Bash(cmd.exe /c \"mklink /D C:\\\\Users\\\\Lenovo\\\\.claude\\\\skills\\\\gitlink-compliance C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-compliance\")",
+      "Bash(powershell.exe -Command \"New-Item -ItemType SymbolicLink -Path 'C:\\\\Users\\\\Lenovo\\\\.claude\\\\skills\\\\gitlink-compliance' -Target 'C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-compliance' -Force\")",
+      "Bash(cmd.exe /c \"mklink /J C:\\\\Users\\\\Lenovo\\\\.claude\\\\skills\\\\gitlink-compliance C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-compliance\")",
+      "Bash(cmd.exe /c \"mklink /J C:\\\\Users\\\\Lenovo\\\\.claude\\\\skills\\\\gitlink-onboard C:\\\\Users\\\\Lenovo\\\\.agents\\\\skills\\\\gitlink-onboard\")",
+      "Bash(ln -s \"/c/Users/Lenovo/.agents/skills/gitlink-compliance\" \"/c/Users/Lenovo/.claude/skills/gitlink-compliance\")",
+      "Bash(ln -s \"/c/Users/Lenovo/.agents/skills/gitlink-onboard\" \"/c/Users/Lenovo/.claude/skills/gitlink-onboard\")",
+      "Bash(export GITLINK_TOKEN=\"ce538a7a6b60b189e8ee28c6bf2a2e8186da8141\")",
+      "Bash(gitlink-cli api:*)",
+      "Bash(gitlink-cli auth:*)",
+      "Bash(gitlink-cli user:*)",
+      "Bash(gitlink-cli issue:*)",
+      "Bash(./gitlink-cli.exe onboard:*)",
+      "Bash(./gitlink-cli.exe compliance:*)",
+      "Bash(gitlink-cli onboard:*)",
+      "Bash(./gitlink-cli-tmp.exe onboard:*)",
+      "Bash(printf \"y\\\\nn\\\\n\")",
+      "Bash(printf \"y\\\\ny\\\\n\")",
+      "Bash(\"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/template-13.txt\":*)",
+      "Bash(jq --version)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Bash(bash -n \"$f\")",
+      "Bash(done)",
+      "Bash(bash workflows/01-community-ops.sh --help)",
+      "Bash(bash workflows/02-code-quality-gatekeeper.sh --help)",
+      "Bash(bash workflows/03-project-init.sh --help)",
+      "Bash(bash workflows/04-multi-repo-collab.sh --help)",
+      "Bash(bash workflows/05-contributor-growth.sh --help)",
+      "Bash(gitlink-cli repo:*)",
+      "Bash(bash workflows/01-community-ops.sh --owner nudt_zk --repo gitlink-cli --dry-run)",
+      "Bash(bash workflows/01-community-ops.sh --owner zzx-coder --repo gitlink-cli --dry-run)",
+      "Bash(bash workflows/02-code-quality-gatekeeper.sh --owner zzx-coder --repo gitlink-cli --dry-run)",
+      "Bash(bash workflows/03-project-init.sh --owner nudt_zk --name test-workflow-03 --description \"Testing workflow 03\" --lang go --dry-run)",
+      "Bash(bash workflows/04-multi-repo-collab.sh --org nudt_zk --dry-run)",
+      "Bash(bash workflows/05-contributor-growth.sh --owner zzx-coder --repo gitlink-cli --dry-run)",
+      "Bash(ls:*)",
+      "Bash(claude --version)",
+      "Bash(claude -p --output-format json)",
+      "Bash(export CLAUDE_CODE_GIT_BASH_PATH=\"C:\\\\Program Files\\\\Git\\\\bin\\\\bash.exe\")",
+      "Read(//c/Program Files/Git/usr/bin/**)",
+      "Read(//c/Program Files/Git/bin/**)",
+      "Bash(export CLAUDE_CODE_GIT_BASH_PATH=\"D:\\\\Git\\\\bin\\\\bash.exe\")",
+      "Bash(bash workflows/02-code-quality-gatekeeper.sh --owner zzx-coder --repo gitlink-cli --pr-id 21 --dry-run)",
+      "Bash(source workflows/lib/common.sh)",
+      "Bash(echo \"EXIT: $?\")",
+      "Bash(cp:*)",
+      "Bash(cmd.exe /c \"mklink /J C:\\\\\\\\Users\\\\\\\\Lenovo\\\\\\\\.claude\\\\\\\\skills\\\\\\\\gitlink-research C:\\\\\\\\Users\\\\\\\\Lenovo\\\\\\\\.agents\\\\\\\\skills\\\\\\\\gitlink-research\")",
+      "Bash(mkdir -p \"C:/Users/Lenovo/.agents/skills/gitlink-research/workflows/lib\")",
+      "Bash(mkdir -p \"C:/Users/Lenovo/.agents/skills/gitlink-research/workflows/templates\")",
+      "Bash(mkdir -p \"C:/Users/Lenovo/.agents/skills/gitlink-research/workflows/schemas\")",
+      "Bash(cp \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/workflows/0\"*\"-research\"*\".sh\" \"C:/Users/Lenovo/.agents/skills/gitlink-research/workflows/\")",
+      "Bash(cp \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/workflows/1\"*\"-research\"*\".sh\" \"C:/Users/Lenovo/.agents/skills/gitlink-research/workflows/\")",
+      "Bash(bash workflows/11-research-citation.sh --owner zzx-coder --repo gitlink-cli --format bibtex)",
+      "Bash(bash -x workflows/11-research-citation.sh --owner zzx-coder --repo gitlink-cli --format bibtex)",
+      "Bash(gitlink-cli pr:*)",
+      "Bash(gitlink-cli search:*)",
+      "Bash(gitlink-cli ci:*)",
+      "Bash(bash -n workflows/06-research-insights.sh)",
+      "Bash(timeout 60 bash workflows/06-research-insights.sh --owner zzx-coder --repo gitlink-cli --dry-run)",
+      "Bash(bash -n workflows/08-research-compliance.sh)",
+      "Bash(timeout 90 bash workflows/08-research-compliance.sh --owner zzx-coder --repo gitlink-cli --local-path . --dry-run)",
+      "Bash(timeout:*)",
+      "Bash(bash -c 'set -euo pipefail; cand_ids=\"\"; analyzed=0; while IFS=\"\t\" read -r c_owner c_repo; do echo \"loop\"; done <<< \"$cand_ids\"; echo \"done loop\"')",
+      "Bash(bash -c 'cand_ids=\"\"; while IFS=\" \" read -r line; do echo \"GOT: [$line]\"; done <<< \"$cand_ids\"; echo \"AFTER LOOP\"')",
+      "Bash(xxd C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/workflows/09-research-collab.sh)",
+      "Bash(xxd)",
+      "Bash(# Remove debug lines first, then replace here-string with pipe\ncp \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/workflows/09-research-collab.sh\" \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/workflows/09-research-collab.sh.bak\"\n# Restore original and make targeted fix\ngit -C \"C:/Users/Lenovo/Desktop/soft运维/gitlink-cli\" checkout -- workflows/09-research-collab.sh 2>/dev/null\n# Now apply all the fixes we discovered)",
+      "Bash(./gitlink-cli.exe repo:*)",
+      "Bash(./gitlink-cli.exe api:*)",
+      "Bash(./gitlink-cli.exe issue:*)",
+      "Bash(./gitlink-cli.exe pr:*)",
+      "mcp__zai-mcp-server__extract_text_from_screenshot",
+      "mcp__zai-mcp-server__analyze_image",
+      "Bash(python3 -c \":*)",
+      "Bash(python -c \":*)",
+      "Bash(where tesseract:*)",
+      "Bash(pip list:*)",
+      "Bash(find C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/internal -type f -name *.go)",
+      "Bash(find C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/shortcuts -type f -name *.go)",
+      "Bash(find C:/Users/Lenovo/Desktop/soft运维/gitlink-cli -name *_test.go -type f)",
+      "Bash(sed 's/\"\"\"\"//g')",
+      "Bash(sed 's/CallAPI\\(\"\"\"\"//g')",
+      "Read(//tmp/**)",
+      "Bash(go test:*)",
+      "Bash(go run:*)",
+      "Bash(gitlink-cli.exe wiki:*)",
+      "Bash(gitlink-cli board:*)",
+      "Bash(./gitlink-cli.exe board:*)",
+      "Bash(where gitlink-cli:*)",
+      "Bash(./gitlink-cli.exe milestone:*)",
+      "Bash(cd:*)",
+      "Bash(gitlink-cli file:*)"
+    ]
+  }
+}
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@ -23,6 +23,9 @@ jobs:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

+      - name: Run tests
+        run: go test ./... -cover -race
+
      - name: Build binaries
        run: |
          mkdir -p dist
--- a/2
+++ b/2
@ -15,4 +15,4 @@ clean:
 	rm -f $(BINARY)

 test:
-	go test ./...
+	go test ./... -race
--- a/README.md
+++ b/README.md
@ -27,9 +27,11 @@ The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans
 | Category | Capabilities |
 |----------|-------------|
 | 📦 Repo | List, create, fork, delete repositories, view repo info |
-| 🐛 Issue | Create, update, close, comment on issues, 6 batch operations (close/status/priority/assignee/label/create) |
+| 🐛 Issue | Create, update, close, comment on issues, 6 batch operations (close/status/priority/assignee/label/create), metadata queries, comment management |
 | 📖 Wiki | View, create, update, delete Wiki pages |
-| 🔀 PR | Create, merge, review pull requests, view changed files |
+| 🔀 PR | Create, merge, review pull requests, reopen, update, view commits/versions/diffs, comment management |
+| 📁 File | Browse directories, read files, create/update/delete files, batch commit, view commit history and diffs |
+| 🏁 Milestone | List, create, view, update, delete milestones, change status |
 | 🌿 Branch | Create, delete, list, protect, unprotect branches |
 | 🏷️ Release | Create, view, delete releases |
 | 🔗 Webhook | Create, view, update, delete, test webhooks, configure automation triggers |
@ -37,6 +39,7 @@ The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans
 | 🔧 CI | View builds, logs, CI/CD operations |
 | 🔍 Search | Search repositories, users |
 | 👤 User | View user profiles and info |
+| 📋 Board | View kanban board, filter issues by status/assignee/priority, move tasks, assign people, workload analytics |
 | 📋 PM | Sprint management, kanban boards, weekly reports |
 | 🤖 Workflow | AI-powered issue triage, PR review, release notes |

@ -191,6 +194,34 @@ gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.cs

 # Add a comment
 gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed"
+
+# Batch delete issues
+gitlink-cli issue +batch-destroy --owner Gitlink --repo forgeplus --numbers 100,101,102
+```
+
+### Issue Metadata & Comments
+
+```bash
+# List available issue statuses
+gitlink-cli issue +statuses
+
+# List issue authors
+gitlink-cli issue +authors --keyword zhang
+
+# List issue assignees
+gitlink-cli issue +assigners
+
+# List issue priorities
+gitlink-cli issue +priorities
+
+# Edit a comment
+gitlink-cli issue +comment-edit --number 42 --comment-id 100 --body "updated comment"
+
+# Delete a comment
+gitlink-cli issue +comment-delete --number 42 --comment-id 100
+
+# List replies to a comment
+gitlink-cli issue +replies --number 42 --comment-id 100
 ```

 ### Pull Requests
@ -215,6 +246,93 @@ gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
 gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
 ```

+### File & Code Operations
+
+```bash
+# List root directory
+gitlink-cli file +ls --owner Gitlink --repo forgeplus
+
+# Browse subdirectory
+gitlink-cli file +tree --path src/
+
+# Read file content
+gitlink-cli file +read --path README.md
+
+# Read README
+gitlink-cli file +readme
+
+# Search files by name
+gitlink-cli file +search --q "test"
+
+# Create a file
+gitlink-cli file +create --path docs/new.md --content "# New Doc" --branch master --message "add doc"
+
+# Update a file (auto-fetches sha)
+gitlink-cli file +update --path README.md --content "updated" --branch master --message "update readme"
+
+# Delete a file (auto-fetches sha)
+gitlink-cli file +delete --path old.txt --branch master
+
+# Batch commit multiple files
+gitlink-cli file +batch --branch master --message "batch update" --files '[{"action_type":"create","file_path":"a.txt","content":"hello"}]'
+
+# View commit history
+gitlink-cli file +commits
+
+# View commit diff
+gitlink-cli file +diff --sha abc1234
+```
+
+### Milestone Management
+
+```bash
+# List milestones
+gitlink-cli milestone +list --owner Gitlink --repo forgeplus
+
+# Create a milestone
+gitlink-cli milestone +create --name "v1.0" --description "First release" --date 2026-12-31
+
+# View milestone details
+gitlink-cli milestone +view --id 1
+
+# Update a milestone
+gitlink-cli milestone +update --id 1 --name "v1.0-rc1"
+
+# Close a milestone
+gitlink-cli milestone +status --id 1 --status closed
+
+# Delete a milestone
+gitlink-cli milestone +delete --id 1
+```
+
+### PR Enhanced Operations
+
+```bash
+# Reopen a closed PR
+gitlink-cli pr +reopen --id 42
+
+# Update PR title/description
+gitlink-cli pr +update --id 42 --title "New title"
+
+# List commits in a PR
+gitlink-cli pr +commits --id 42
+
+# List PR versions
+gitlink-cli pr +versions --id 42
+
+# View diff of a specific PR version
+gitlink-cli pr +vdiff --id 42 --version 5
+
+# List changed files (v1 API with pagination)
+gitlink-cli pr +filesv1 --id 42
+
+# Edit a PR review comment
+gitlink-cli pr +comment-edit --id 42 --comment-id 100 --body "updated" --state resolved
+
+# Delete a PR review comment
+gitlink-cli pr +comment-delete --id 42 --comment-id 100
+```
+
 ### Branch Management

 ```bash
@ -234,6 +352,28 @@ gitlink-cli branch +protect --name main
 gitlink-cli branch +unprotect --name main
 ```

+### Board (Kanban)
+
+```bash
+# View kanban board layout
+gitlink-cli board +view --owner Gitlink --repo forgeplus
+
+# List status columns with issue counts
+gitlink-cli board +columns --owner Gitlink --repo forgeplus
+
+# Filter issues by status and assignee
+gitlink-cli board +issues --owner Gitlink --repo forgeplus --status in-progress --assignee zhangsan
+
+# Move an issue to a different status
+gitlink-cli board +move --owner Gitlink --repo forgeplus --number 42 --status resolved
+
+# Assign an issue to someone
+gitlink-cli board +assign --owner Gitlink --repo forgeplus --number 42 --assignee zhangsan
+
+# View board analytics and statistics
+gitlink-cli board +stats --owner Gitlink --repo forgeplus
+```
+
 ### Webhook Management

 ```bash
@ -408,6 +548,7 @@ gitlink-cli/
 │   ├── repo/                 # Repository shortcuts
 │   ├── issue/                # Issue shortcuts
 │   ├── pr/                   # PR shortcuts
+│   ├── board/                # Board (kanban) shortcuts
 │   ├── branch/               # Branch shortcuts
 │   ├── release/              # Release shortcuts
 │   ├── org/                  # Organization shortcuts
@ -415,6 +556,8 @@ gitlink-cli/
 │   ├── search/               # Search shortcuts
 │   ├── user/                 # User shortcuts
 │   ├── wiki/                 # Wiki shortcuts
+│   ├── file/                 # File & code shortcuts
+│   ├── milestone/            # Milestone shortcuts
 │   └── register.go           # Registration entry point
 ├── skills/                   # AI Agent Skills
 │   ├── README.md             # Skills guide
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -27,9 +27,11 @@
 | 分类 | 能力 |
 |------|------|
 | 📦 仓库 | 列出、创建、Fork、删除仓库，查看仓库信息 |
-| 🐛 Issue | 创建、更新、关闭、评论 Issue，6 个批量操作（关闭/状态/优先级/负责人/标记/创建） |
+| 🐛 Issue | 创建、更新、关闭、评论 Issue，6 个批量操作，元数据查询，评论管理 |
 | 📖 Wiki | 查看、创建、更新、删除 Wiki 页面 |
-| 🔀 PR | 创建、合并、Review Pull Request，查看变更文件 |
+| 🔀 PR | 创建、合并、Review Pull Request，重新打开、更新，查看提交/版本/Diff，评论管理 |
+| 📁 文件 | 浏览目录、读取文件、创建/更新/删除文件、批量提交、查看提交历史和 Diff |
+| 🏁 里程碑 | 列出、创建、查看、更新、删除里程碑，变更状态 |
 | 🌿 分支 | 创建、删除、保护分支 |
 | 🏷️ 发布 | 创建、查看、删除 Release |
 | 🔗 Webhook | 创建、查看、更新、删除、测试 Webhook，配置自动化触发器 |
@ -37,6 +39,7 @@
 | 🔧 CI | 查看构建、日志、CI/CD 操作 |
 | 🔍 搜索 | 搜索仓库、用户 |
 | 👤 用户 | 查看用户资料和信息 |
+| 📋 看板 | 查看看板、按状态/指派人/优先级筛选、移动任务、指派人员、工作负载分析 |
 | 📋 项目管理 | Sprint 管理、看板、周报 |
 | 🤖 工作流 | AI 驱动的 Issue 分类、PR Review、Release Notes |

@ -204,6 +207,9 @@ gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.cs
 # 添加评论
 gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "已修复"

+# 批量删除 Issue
+gitlink-cli issue +batch-destroy --owner Gitlink --repo forgeplus --numbers 100,101,102
+
 # 批量修改状态
 gitlink-cli issue +batch-status --state resolved --numbers 1,2,3  --owner Gitlink --repo forgeplus  

@ -224,6 +230,31 @@ gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 1,2,3

 ```

+### Issue 元数据与评论
+
+```bash
+# 查看可用的 Issue 状态列表
+gitlink-cli issue +statuses
+
+# 查看 Issue 发布人列表
+gitlink-cli issue +authors --keyword zhang
+
+# 查看 Issue 负责人列表
+gitlink-cli issue +assigners
+
+# 查看 Issue 优先级列表
+gitlink-cli issue +priorities
+
+# 编辑评论
+gitlink-cli issue +comment-edit --number 42 --comment-id 100 --body "修正后的评论"
+
+# 删除评论
+gitlink-cli issue +comment-delete --number 42 --comment-id 100
+
+# 查看评论的回复列表
+gitlink-cli issue +replies --number 42 --comment-id 100
+```
+
 ### Pull Request

 ```bash
@ -246,6 +277,115 @@ gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
 gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
 ```

+### PR 增强操作
+
+```bash
+# 重新打开已关闭的 PR
+gitlink-cli pr +reopen --id 42
+
+# 更新 PR 标题/描述
+gitlink-cli pr +update --id 42 --title "新标题"
+
+# 查看 PR 中的提交列表
+gitlink-cli pr +commits --id 42
+
+# 查看 PR 版本历史
+gitlink-cli pr +versions --id 42
+
+# 查看 PR 某版本的 Diff
+gitlink-cli pr +vdiff --id 42 --version 5
+
+# 查看 PR 变更文件列表（v1 API，支持分页）
+gitlink-cli pr +filesv1 --id 42
+
+# 编辑 PR 审查评论
+gitlink-cli pr +comment-edit --id 42 --comment-id 100 --body "更新内容" --state resolved
+
+# 删除 PR 审查评论
+gitlink-cli pr +comment-delete --id 42 --comment-id 100
+```
+
+### 文件与代码操作
+
+```bash
+# 列出根目录文件
+gitlink-cli file +ls --owner Gitlink --repo forgeplus
+
+# 浏览子目录
+gitlink-cli file +tree --path src/
+
+# 读取文件内容
+gitlink-cli file +read --path README.md
+
+# 读取 README
+gitlink-cli file +readme
+
+# 按文件名搜索
+gitlink-cli file +search --q "test"
+
+# 创建文件
+gitlink-cli file +create --path docs/new.md --content "# 新文档" --branch master --message "add doc"
+
+# 更新文件（自动获取 sha）
+gitlink-cli file +update --path README.md --content "更新内容" --branch master --message "update readme"
+
+# 删除文件（自动获取 sha）
+gitlink-cli file +delete --path old.txt --branch master
+
+# 批量提交多个文件
+gitlink-cli file +batch --branch master --message "batch update" --files '[{"action_type":"create","file_path":"a.txt","content":"hello"}]'
+
+# 查看提交历史
+gitlink-cli file +commits
+
+# 查看提交 Diff
+gitlink-cli file +diff --sha abc1234
+```
+
+### 里程碑管理
+
+```bash
+# 列出里程碑
+gitlink-cli milestone +list --owner Gitlink --repo forgeplus
+
+# 创建里程碑
+gitlink-cli milestone +create --name "v1.0" --description "首个正式版" --date 2026-12-31
+
+# 查看里程碑详情
+gitlink-cli milestone +view --id 1
+
+# 更新里程碑
+gitlink-cli milestone +update --id 1 --name "v1.0-rc1"
+
+# 关闭里程碑
+gitlink-cli milestone +status --id 1 --status closed
+
+# 删除里程碑
+gitlink-cli milestone +delete --id 1
+```
+
+### 看板操作
+
+```bash
+# 查看看板布局
+gitlink-cli board +view --owner Gitlink --repo forgeplus
+
+# 列出各状态列及 Issue 数量
+gitlink-cli board +columns --owner Gitlink --repo forgeplus
+
+# 按状态和指派人筛选任务
+gitlink-cli board +issues --owner Gitlink --repo forgeplus --status in-progress --assignee zhangsan
+
+# 移动任务状态
+gitlink-cli board +move --owner Gitlink --repo forgeplus --number 42 --status resolved
+
+# 指派任务给用户
+gitlink-cli board +assign --owner Gitlink --repo forgeplus --number 42 --assignee zhangsan
+
+# 查看看板统计分析
+gitlink-cli board +stats --owner Gitlink --repo forgeplus
+```
+
 ### Webhook 管理

 ```bash
@ -406,6 +546,7 @@ gitlink-cli/
 │   ├── repo/                 # 仓库 shortcuts
 │   ├── issue/                # Issue shortcuts
 │   ├── pr/                   # PR shortcuts
+│   ├── board/                # 看板 shortcuts
 │   ├── branch/               # 分支 shortcuts
 │   ├── release/              # Release shortcuts
 │   ├── org/                  # 组织 shortcuts
@ -413,6 +554,8 @@ gitlink-cli/
 │   ├── search/               # 搜索 shortcuts
 │   ├── user/                 # 用户 shortcuts
 │   ├── wiki/                 # Wiki shortcuts
+│   ├── file/                 # 文件与代码 shortcuts
+│   ├── milestone/            # 里程碑 shortcuts
 │   └── register.go           # 注册入口
 ├── skills/                   # AI Agent Skills
 │   ├── README.md             # Skills 使用指南
--- a/cmd/api/api.go
+++ b/cmd/api/api.go
@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/url"
+	"os"
 	"strings"

 	"github.com/spf13/cobra"
@ -20,12 +21,14 @@ func NewAPICmd() *cobra.Command {
 		Long:  `Send arbitrary HTTP requests to the GitLink API. Authentication is injected automatically.`,
 		Example: `  gitlink-cli api GET /users/me
  gitlink-cli api GET /projects --query 'page=1&limit=10'
-  gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"Bug","description":"..."}'`,
+  gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"Bug","description":"..."}'
+  gitlink-cli api POST /:owner/:repo/issues --body-file ./issue.json`,
 		Args: cobra.ExactArgs(2),
 		RunE: runAPI,
 	}

 	apiCmd.Flags().String("body", "", "Request body (JSON string)")
+	apiCmd.Flags().String("body-file", "", "Read JSON body from a file (avoids shell quoting issues)")
 	apiCmd.Flags().String("query", "", "Query parameters (key=val&key2=val2)")
 	apiCmd.Flags().StringSlice("header", nil, "Additional headers (key:value)")

@ -48,9 +51,20 @@ func runAPI(c *cobra.Command, args []string) error {

 	var body interface{}
 	bodyStr, _ := c.Flags().GetString("body")
+	bodyFile, _ := c.Flags().GetString("body-file")
+	if bodyStr != "" && bodyFile != "" {
+		return printAPIError(400, "cannot use both --body and --body-file", "请只用其中一个：--body 用于内联 JSON，--body-file 用于从文件读取")
+	}
+	if bodyFile != "" {
+		raw, err := os.ReadFile(bodyFile)
+		if err != nil {
+			return printAPIError(400, fmt.Sprintf("read --body-file failed: %v", err), "检查 --body-file 路径是否正确、文件是否存在且有读权限")
+		}
+		bodyStr = string(raw)
+	}
 	if bodyStr != "" {
 		if err := json.Unmarshal([]byte(bodyStr), &body); err != nil {
-			return fmt.Errorf("invalid JSON body: %w", err)
+			return printAPIError(400, fmt.Sprintf("invalid JSON body: %v", err), "确认 body 是合法 JSON；PowerShell 调用 .exe 时会剥离内嵌双引号，推荐改用 --body-file 从文件读取")
 		}
 	}

@ -60,7 +74,7 @@ func runAPI(c *cobra.Command, args []string) error {
 		var err error
 		query, err = url.ParseQuery(queryStr)
 		if err != nil {
-			return fmt.Errorf("invalid query string: %w", err)
+			return printAPIError(400, fmt.Sprintf("invalid query string: %v", err), "query 应为 key=value&key2=value2 形式，注意值需要 URL 编码")
 		}
 	}

@ -68,14 +82,26 @@ func runAPI(c *cobra.Command, args []string) error {
 	if err != nil {
 		if apiErr, ok := err.(*client.APIError); ok {
 			errEnv := output.ErrorEnvelope(apiErr.Code, apiErr.Message, apiErr.Suggestion)
-			return output.Print(errEnv, resolveFormat())
+			_ = output.Print(errEnv, resolveFormat())
+			return cmdutil.ErrSilent
 		}
-		return fmt.Errorf("API 请求失败 [%s %s]: %w", method, path, err)
+		// 网络错误 / DNS 失败 / 超时等非 API 错误，也按 envelope 输出保持一致
+		return printAPIError(503, fmt.Sprintf("API 请求失败 [%s %s]: %v", method, path, err), "检查网络连接、GitLink 主机可达性、token 是否有效")
 	}

 	return output.Print(env, resolveFormat())
 }

+// printAPIError 把本地校验/IO/网络错误统一按标准 envelope 输出到 stdout，
+// 并返回 cmdutil.ErrSilent 让 cmd.Execute 跳过 stderr 重复打印，仅保留非零退出码。
+// 设计意图：让 `api` 命令的所有错误（包括 JSON 解析、参数冲突、读文件失败、APIError、
+// 网络错误）输出格式与 shortcut 一致，便于 `--format json` + jq 自动化解析。
+func printAPIError(code int, message, suggestion string) error {
+	env := output.ErrorEnvelope(code, message, suggestion)
+	_ = output.Print(env, resolveFormat())
+	return cmdutil.ErrSilent
+}
+
 func resolveFormat() string {
 	f := cmdutil.Format
 	if f == "" {
--- a/cmd/cmdutil/globals.go
+++ b/cmd/cmdutil/globals.go
@ -1,9 +1,25 @@
 package cmdutil

+import "errors"
+
 // Global flags shared across all commands.
 var (
-	Owner  string
-	Repo   string
-	Format string
-	Debug  bool
+	Owner      string
+	Repo       string
+	Format     string
+	Debug      bool
+	NoTruncate bool   // disable 60-char truncation in table output
+	Columns    string // comma-separated column names for table output
+	NoColor    bool   // disable ANSI color output
 )
+
+// ErrSilent 是 sentinel error：表示错误已经被上层处理过（如已按 envelope 格式
+// 输出到 stdout），调用方（cmd.Execute）只需返回非零退出码，不要再把消息
+// 打印到 stderr。
+//
+// 使用方式：
+//
+//	if TryPrintError(err, format) {
+//	    return cmdutil.ErrSilent
+//	}
+var ErrSilent = errors.New("silent error: already reported via envelope")
--- a/cmd/root.go
+++ b/cmd/root.go
@ -1,6 +1,7 @@
 package cmd

 import (
+	"errors"
 	"fmt"
 	"os"

@ -10,6 +11,7 @@ import (
 	authCmd "github.com/gitlink-org/gitlink-cli/cmd/auth"
 	apiCmd "github.com/gitlink-org/gitlink-cli/cmd/api"
 	configCmd "github.com/gitlink-org/gitlink-cli/cmd/config"
+	"github.com/gitlink-org/gitlink-cli/internal/compliance"
 	"github.com/gitlink-org/gitlink-cli/shortcuts"
 )

@ -26,13 +28,18 @@ var rootCmd = &cobra.Command{
 func init() {
 	rootCmd.PersistentFlags().StringVar(&cmdutil.Owner, "owner", "", "Repository owner (auto-detected from git remote)")
 	rootCmd.PersistentFlags().StringVar(&cmdutil.Repo, "repo", "", "Repository name (auto-detected from git remote)")
-	rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "", "Output format: json, table, yaml (default: table)")
+	rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "table", "Output format: json, table, yaml")
 	rootCmd.PersistentFlags().BoolVar(&cmdutil.Debug, "debug", false, "Enable debug output")
+	rootCmd.PersistentFlags().BoolVar(&cmdutil.NoTruncate, "no-truncate", false, "Disable value truncation in table output")
+	rootCmd.PersistentFlags().StringVar(&cmdutil.Columns, "columns", "", "Columns to show in table output (comma-separated)")
+	rootCmd.PersistentFlags().BoolVar(&cmdutil.NoColor, "no-color", false, "Disable colored output")

 	rootCmd.AddCommand(authCmd.NewAuthCmd())
 	rootCmd.AddCommand(apiCmd.NewAPICmd())
 	rootCmd.AddCommand(configCmd.NewConfigCmd())
 	rootCmd.AddCommand(versionCmd)
+	rootCmd.AddCommand(completionCmd)
+	rootCmd.AddCommand(compliance.NewCommand())

 	shortcuts.RegisterAll(rootCmd)
 }
@ -45,8 +52,38 @@ var versionCmd = &cobra.Command{
 	},
 }

+var completionCmd = &cobra.Command{
+	Use:       "completion [bash|zsh|fish|powershell]",
+	Short:     "Generate shell completion script",
+	Long:      "Generate shell autocompletion script for the specified shell.\n\nTo load completions:\n\n  Bash:\n    source <(gitlink-cli completion bash)\n\n  Zsh:\n    source <(gitlink-cli completion zsh)\n\n  fish:\n    gitlink-cli completion fish | source\n\n  PowerShell:\n    gitlink-cli completion powershell | Out-String | Invoke-Expression",
+	ValidArgs: []string{"bash", "zsh", "fish", "powershell"},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		shell := "bash"
+		if len(args) > 0 {
+			shell = args[0]
+		}
+		switch shell {
+		case "bash":
+			return cmd.Root().GenBashCompletion(os.Stdout)
+		case "zsh":
+			return cmd.Root().GenZshCompletion(os.Stdout)
+		case "fish":
+			return cmd.Root().GenFishCompletion(os.Stdout, true)
+		case "powershell":
+			return cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
+		default:
+			return fmt.Errorf("unsupported shell: %s (valid: bash, zsh, fish, powershell)", shell)
+		}
+	},
+}
+
 func Execute() error {
 	if err := rootCmd.Execute(); err != nil {
+		// ErrSilent 表示错误已经按 envelope 格式输出到 stdout（如 API 错误），
+		// 这里只需保留非零退出码，不需要再 stderr 重复打印。
+		if errors.Is(err, cmdutil.ErrSilent) {
+			return err
+		}
 		fmt.Fprintln(os.Stderr, err)
 		return err
 	}
--- a/demo/index.html
+++ b/demo/index.html
--- a/demo/server.py
+++ b/demo/server.py
@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+"""
+GitLink CLI Demo Server — 子任务一 交互式展示
+启动后访问 http://127.0.0.1:8765
+"""
+
+import http.server
+import json
+import subprocess
+import os
+import sys
+import tempfile
+import threading
+import shutil
+import uuid
+from pathlib import Path
+
+PORT = 8765
+WORKING_DIR = r"D:\code\SE\Evolution_and_Maintenance_of_SE\Mission2\gitlink-cli"
+HTML_DIR = Path(__file__).parent
+
+# ── 定位 Claude Code CLI ─────────────────────────
+def _find_claude() -> str | None:
+    """查找 claude 可执行文件，优先返回 .exe 以避开 .cmd 的编码问题"""
+    # 1) 直接找 claude.exe（npm 全局安装路径）
+    candidates = [
+        # npm global on Windows
+        Path(os.environ.get("APPDATA", "")) / r"npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe",
+        # 直接 which（可能返回 .cmd）
+        shutil.which("claude"),
+        shutil.which("claude.exe"),
+    ]
+    for p in candidates:
+        if p and Path(str(p)).is_file():
+            return str(p)
+
+    # 2) 尝试 shutil.which 返回的 .cmd 对应的 .exe
+    cmd = shutil.which("claude.cmd")
+    if cmd:
+        exe = Path(cmd).with_suffix(".exe")
+        if exe.is_file():
+            return str(exe)
+
+    return None
+
+CLAUDE_EXE = _find_claude()
+
+# 全局：当前正在运行的进程（用于取消）
+_proc_lock = threading.Lock()
+_current_proc = None
+
+
+class DemoHandler(http.server.BaseHTTPRequestHandler):
+    """HTTP 请求处理器：静态文件 + API 端点"""
+
+    # ── 日志 ────────────────────────────────────────────
+    def log_message(self, fmt, *args):
+        print(f"[{self.log_date_time_string()}] {args[0]}")
+
+    # ── GET ─────────────────────────────────────────────
+    def do_GET(self):
+        path = self.path.split("?")[0]
+        if path in ("/", "/index.html"):
+            self._serve_file("index.html", "text/html; charset=utf-8")
+        else:
+            self.send_error(404)
+
+    # ── POST ────────────────────────────────────────────
+    def do_POST(self):
+        if self.path == "/api/exec":
+            self._handle_exec()
+        elif self.path == "/api/claude":
+            self._handle_claude()
+        elif self.path == "/api/cancel":
+            self._handle_cancel()
+        else:
+            self.send_error(404)
+
+    # ── OPTIONS (CORS preflight) ────────────────────────
+    def do_OPTIONS(self):
+        self._send_cors_headers()
+        self.send_response(204)
+        self.end_headers()
+
+    # ── 取消当前命令 ────────────────────────────────────
+    def _handle_cancel(self):
+        global _current_proc
+        with _proc_lock:
+            proc = _current_proc
+        if proc is None or proc.poll() is not None:
+            self._send_json({"ok": True, "message": "没有正在运行的命令"})
+            return
+        try:
+            proc.kill()
+            self._send_json({"ok": True, "message": "已发送终止信号"})
+        except Exception as e:
+            self._send_json({"ok": False, "error": str(e)})
+
+    # ── Claude Code 执行 ────────────────────────────────
+    def _handle_claude(self):
+        global _current_proc
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(content_length)
+        try:
+            data = json.loads(body)
+        except json.JSONDecodeError:
+            self._send_json({"ok": False, "error": "Invalid JSON body"})
+            return
+
+        prompt = data.get("prompt", "").strip()
+        if not prompt:
+            self._send_json({"ok": False, "error": "Empty prompt", "session_id": data.get("session_id", "")})
+            return
+
+        timeout = min(data.get("timeout", 600), 600)  # 10 min for Claude
+
+        if not CLAUDE_EXE:
+            self._send_json({
+                "ok": False, "stdout": "",
+                "stderr": "❌ 找不到 Claude Code CLI（claude.exe）。请确认已通过 npm 安装：npm install -g @anthropic-ai/claude-code",
+                "exit_code": -1,
+                "session_id": "",
+            })
+            return
+
+        # ── 会话管理：支持多轮对话 ──
+        session_id = data.get("session_id", "").strip()
+        new_session = data.get("new_session", False)
+
+        if new_session or not session_id:
+            # 新会话：生成 UUID
+            session_id = str(uuid.uuid4())
+            args = [CLAUDE_EXE, "-p", prompt, "--session-id", session_id, "--permission-mode", "bypassPermissions"]
+        else:
+            # 继续已有会话
+            args = [CLAUDE_EXE, "-p", prompt, "--resume", session_id, "--permission-mode", "bypassPermissions"]
+
+        proc = None
+        try:
+            proc = subprocess.Popen(
+                args,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=WORKING_DIR,
+                env={**os.environ, "NO_COLOR": "1"},
+            )
+
+            # 注册为当前进程（允许取消）
+            with _proc_lock:
+                _current_proc = proc
+
+            try:
+                stdout, stderr = proc.communicate(timeout=timeout)
+                exit_code = proc.returncode
+                killed = False
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                stdout, stderr = proc.communicate()
+                exit_code = -1
+                killed = True
+
+            if killed:
+                self._send_json({
+                    "ok": False,
+                    "stdout": stdout or "",
+                    "stderr": f"❌ Claude Code 执行超时（超过 {timeout} 秒）已被终止",
+                    "exit_code": -1,
+                    "session_id": session_id,
+                })
+            else:
+                self._send_json({
+                    "ok": exit_code == 0,
+                    "stdout": stdout,
+                    "stderr": stderr,
+                    "exit_code": exit_code,
+                    "session_id": session_id,
+                })
+
+        except FileNotFoundError:
+            self._send_json({
+                "ok": False, "stdout": "",
+                "stderr": "❌ 找不到 Claude Code CLI（claude.exe）。请确认已通过 npm 安装：npm install -g @anthropic-ai/claude-code",
+                "exit_code": -1,
+                "session_id": session_id,
+            })
+        except Exception as e:
+            self._send_json({
+                "ok": False, "stdout": "",
+                "stderr": f"❌ {e}", "exit_code": -1,
+                "session_id": session_id,
+            })
+        finally:
+            with _proc_lock:
+                if _current_proc is proc:
+                    _current_proc = None
+
+    # ── 命令执行 ────────────────────────────────────────
+    def _handle_exec(self):
+        global _current_proc
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(content_length)
+        try:
+            data = json.loads(body)
+        except json.JSONDecodeError:
+            self._send_json({"ok": False, "error": "Invalid JSON body"})
+            return
+
+        command = data.get("command", "").strip()
+        if not command:
+            self._send_json({"ok": False, "error": "Empty command"})
+            return
+
+        timeout = min(data.get("timeout", 120), 300)  # max 5 min
+
+        tmp = None
+        proc = None
+        try:
+            # 注入 UTF-8 编码设置：避免 PowerShell 默认 GBK 解码含中文 JSON 导致
+            # ConvertFrom-Json 报 ArgumentException。对已有该设置的命令重复无害。
+            command = "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8\n" + command
+
+            tmp = tempfile.NamedTemporaryFile(
+                mode="w", suffix=".ps1", delete=False, encoding="utf-8-sig"
+            )
+            tmp.write(command)
+            tmp.close()
+
+            proc = subprocess.Popen(
+                [
+                    "powershell",
+                    "-ExecutionPolicy", "Bypass",
+                    "-NoProfile",
+                    "-File", tmp.name,
+                ],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=WORKING_DIR,
+                env={**os.environ, "NO_COLOR": "1"},
+            )
+
+            # 注册为当前进程（允许取消）
+            with _proc_lock:
+                _current_proc = proc
+
+            try:
+                stdout, stderr = proc.communicate(timeout=timeout)
+                exit_code = proc.returncode
+                killed = False
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                stdout, stderr = proc.communicate()
+                exit_code = -1
+                killed = True
+
+            if killed:
+                self._send_json({
+                    "ok": False,
+                    "stdout": stdout or "",
+                    "stderr": f"❌ 命令执行超时（超过 {timeout} 秒）已被终止",
+                    "exit_code": -1,
+                })
+            else:
+                self._send_json({
+                    "ok": exit_code == 0,
+                    "stdout": stdout,
+                    "stderr": stderr,
+                    "exit_code": exit_code,
+                })
+
+        except FileNotFoundError:
+            self._send_json({
+                "ok": False, "stdout": "",
+                "stderr": "❌ 找不到 PowerShell，请确认系统已安装 PowerShell",
+                "exit_code": -1,
+            })
+        except Exception as e:
+            self._send_json({
+                "ok": False, "stdout": "",
+                "stderr": f"❌ {e}", "exit_code": -1,
+            })
+        finally:
+            with _proc_lock:
+                if _current_proc is proc:
+                    _current_proc = None
+            if tmp:
+                try:
+                    os.unlink(tmp.name)
+                except OSError:
+                    pass
+
+    # ── 辅助方法 ────────────────────────────────────────
+    def _serve_file(self, filename: str, content_type: str):
+        filepath = HTML_DIR / filename
+        try:
+            with open(filepath, "rb") as f:
+                content = f.read()
+            self.send_response(200)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(content)))
+            self.send_header("Cache-Control", "no-cache")
+            self._send_cors_headers()
+            self.end_headers()
+            self.wfile.write(content)
+        except FileNotFoundError:
+            self.send_error(404)
+
+    def _send_json(self, data: dict):
+        body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self._send_cors_headers()
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_cors_headers(self):
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+
+
+def main():
+    if not os.path.isdir(WORKING_DIR):
+        print(f"⚠️  警告：工作目录不存在 — {WORKING_DIR}")
+        print("   请修改 server.py 中的 WORKING_DIR 变量")
+        sys.exit(1)
+
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", PORT), DemoHandler)
+
+    claude_status = f"✅ {CLAUDE_EXE}" if CLAUDE_EXE else "❌ 未找到 claude.exe（Skills 功能不可用）"
+    print(f"""
+╔════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+║                                  GitLink CLI 作品展示 · 交互式平台                                         ║
+╠════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
+║  打开浏览器访问: http://127.0.0.1:{PORT}                                                                     ║
+║  工作目录: {WORKING_DIR}                                 ║
+║  Claude Code: {claude_status:<55} ║
+║  按 Ctrl+C 停止服务器                                                                                      ║
+╚════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+""")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n👋 服务器已停止。")
+
+
+if __name__ == "__main__":
+    main()
--- a/doc/.claude/settings.local.json
+++ b/doc/.claude/settings.local.json
@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(go build:*)",
+      "Bash(/c/Users/Lenovo/Desktop/soft运维/gitlink-cli/gitlink-cli.exe board:*)",
+      "Bash(go install:*)",
+      "Bash(gitlink-cli board:*)",
+      "Bash(/c/Users/Lenovo/go/bin/gitlink-cli.exe board:*)",
+      "Bash(gitlink-cli repo:*)",
+      "Bash(gitlink-cli api:*)",
+      "Bash(gitlink-cli issue:*)",
+      "Bash(find C:/Users/Lenovo/Desktop/soft运维/gitlink-cli -name *.go -not -path */vendor/* -exec wc -l {} +)",
+      "Bash(pip install:*)",
+      "Bash(python gen_docx.py)",
+      "Bash(python -c \"import docx; print\\(''ok''\\)\")",
+      "Bash(ls -la \"C:\\\\Users\\\\Lenovo\\\\Desktop\\\\soft运维\\\\gitlink-cli\\\\doc/\"*.docx)",
+      "Bash(python gen_ppt.py)"
+    ]
+  }
+}
--- a/doc/1.png
+++ b/doc/1.png
--- a/doc/PR格式模板-board功能示例.md
+++ b/doc/PR格式模板-board功能示例.md
@ -0,0 +1,450 @@
+# PR 格式模板（以 board 功能为例）
+
+## PR 标题
+
+```
+feat(board): 新增项目看板 shortcut — 查看/筛选/移动/指派/统计
+```
+
+格式：`type(scope): 简述`，与仓库现有 commit 风格一致。
+
+---
+
+## PR 描述
+
+```markdown
+## Summary
+
+- 新增 `board` 命令组，提供 6 个看板操作子命令
+- 基于 issue list API 实现看板视图（按 status_id 分组为 5 列）
+- 写操作（+move/+assign）复用 issue PATCH API，支持 --dry-run
+- 包含单元测试和帮助文档
+
+## Changes
+
+### 新增文件
+- `shortcuts/board/board.go` — 6 个命令 + 辅助函数
+- `shortcuts/board/board_test.go` — 单元测试
+
+### 修改文件
+- `shortcuts/register.go` — 注册 board 组
+
+## Commands
+
+| 命令 | 类型 | 说明 |
+|------|------|------|
+| `board +view` | 读 | 按状态分组显示看板 |
+| `board +columns` | 读 | 列出各状态列及 issue 数量 |
+| `board +issues` | 读 | 按状态/指派人/优先级筛选 |
+| `board +move` | 写 | 移动任务状态 |
+| `board +assign` | 写 | 指派任务 |
+| `board +stats` | 读 | 完成率/工作负载/瓶颈分析 |
+
+## Test plan
+
+- [x] `go test ./shortcuts/board/...` 通过
+- [x] `go build ./...` 编译通过
+- [x] `board +view` 输出正确的看板结构
+- [x] `board +columns` 返回 5 列
+- [x] `board +issues --status in-progress` 筛选正确
+- [x] `board +move --dry-run` 预览不执行
+- [x] `board +assign --dry-run` 预览不执行
+- [x] `board +stats` 完成率计算正确
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+---
+
+## Commit 规范
+
+仓库使用 conventional commits 格式：
+
+```
+type(scope): description
+```
+
+常用 type：
+- `feat` — 新功能
+- `fix` — 修复
+- `refactor` — 重构
+- `docs` — 文档
+- `test` — 测试
+
+board 功能的 commit 示例：
+
+```
+feat(board): 新增 board shortcut — 看板查看/筛选/移动/指派/统计
+test(board): 添加 board 命令单元测试
+```
+
+如果拆成多个 commit：
+
+```
+feat(board): 新增 board +view/+columns/+issues 读命令
+feat(board): 新增 board +move/+assign 写命令
+test(board): 添加 board 命令单元测试
+```
+
+---
+
+## 单元测试模板
+
+仓库测试风格：用 `httptest.NewServer` mock API，直接构造 `RuntimeContext` 调用 `Run` 函数。
+
+### 文件：`shortcuts/board/board_test.go`
+
+```go
+package board
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// === mock server ===
+
+func newBoardTestServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(handler)
+}
+
+func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
+	t.Helper()
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(payload)
+}
+
+func decodeJSON(t *testing.T, r *http.Request) map[string]interface{} {
+	t.Helper()
+	var payload map[string]interface{}
+	json.NewDecoder(r.Body).Decode(&payload)
+	return payload
+}
+
+// 模拟 issue list API 响应
+func mockIssueListResponse() map[string]interface{} {
+	return map[string]interface{}{
+		"issues": []interface{}{
+			map[string]interface{}{
+				"id":                    101,
+				"subject":               "Fix login bug",
+				"status_id":             float64(1),
+				"status_name":           "待处理",
+				"priority_id":           float64(2),
+				"priority_name":         "正常",
+				"project_issues_index":  float64(1),
+				"assigners":             []interface{}{},
+			},
+			map[string]interface{}{
+				"id":                    102,
+				"subject":               "Add dark mode",
+				"status_id":             float64(2),
+				"status_name":           "进行中",
+				"priority_id":           float64(3),
+				"priority_name":         "高",
+				"project_issues_index":  float64(2),
+				"assigners": []interface{}{
+					map[string]interface{}{"login": "zhangsan", "name": "Zhang San"},
+				},
+			},
+			map[string]interface{}{
+				"id":                    103,
+				"subject":               "Update README",
+				"status_id":             float64(3),
+				"status_name":           "已解决",
+				"priority_id":           float64(1),
+				"priority_name":         "低",
+				"project_issues_index":  float64(3),
+				"assigners":             []interface{}{},
+			},
+		},
+		"total_count":        float64(3),
+		"total_issues_count": float64(3),
+	}
+}
+
+// === helper ===
+
+func runBoardShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
+	t.Helper()
+	shortcut := findBoardShortcut(t, name)
+	ctx := &common.RuntimeContext{
+		Client: &client.Client{
+			HTTP:    server.Client(),
+			BaseURL: server.URL,
+		},
+		Owner:  "owner",
+		Repo:   "repo",
+		Format: "json",
+		Args:   args,
+	}
+	return shortcut.Run(ctx)
+}
+
+func findBoardShortcut(t *testing.T, name string) *common.Shortcut {
+	t.Helper()
+	for _, s := range Shortcuts() {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("shortcut %q not found", name)
+	return nil
+}
+
+// === 测试用例 ===
+
+func TestBoardViewGroupsByStatus(t *testing.T) {
+	server := newBoardTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == "GET" && strings.Contains(r.URL.Path, "/issues") {
+			writeJSON(t, w, mockIssueListResponse())
+			return
+		}
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	})
+	defer server.Close()
+
+	err := runBoardShortcut(t, server, "view", map[string]string{"state": "all"})
+	if err != nil {
+		t.Fatalf("board +view failed: %v", err)
+	}
+	// 验证：view 命令不报错即通过，输出由 ctx.OutputData 处理
+}
+
+func TestBoardColumnsReturnsAllStatuses(t *testing.T) {
+	server := newBoardTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == "GET" && strings.Contains(r.URL.Path, "/issues") {
+			writeJSON(t, w, mockIssueListResponse())
+			return
+		}
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	})
+	defer server.Close()
+
+	// columns 命令输出到 stdout，这里只验证不报错
+	err := runBoardShortcut(t, server, "columns", map[string]string{"state": "all"})
+	if err != nil {
+		t.Fatalf("board +columns failed: %v", err)
+	}
+}
+
+func TestBoardIssuesFilterByStatus(t *testing.T) {
+	server := newBoardTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == "GET" && strings.Contains(r.URL.Path, "/issues") {
+			writeJSON(t, w, mockIssueListResponse())
+			return
+		}
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	})
+	defer server.Close()
+
+	err := runBoardShortcut(t, server, "issues", map[string]string{
+		"state":  "all",
+		"status": "in-progress",
+	})
+	if err != nil {
+		t.Fatalf("board +issues --status in-progress failed: %v", err)
+	}
+}
+
+func TestBoardMoveSendsCorrectStatusID(t *testing.T) {
+	var patchPayload map[string]interface{}
+	server := newBoardTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET" && strings.Contains(r.URL.Path, "/issues/1"):
+			writeJSON(t, w, map[string]interface{}{
+				"subject":     "Fix login bug",
+				"description": "Steps to reproduce...",
+			})
+		case r.Method == "PATCH" && strings.Contains(r.URL.Path, "/issues/1"):
+			patchPayload = decodeJSON(t, r)
+			writeJSON(t, w, patchPayload)
+		default:
+			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runBoardShortcut(t, server, "move", map[string]string{
+		"number": "1",
+		"status": "in-progress",
+	})
+	if err != nil {
+		t.Fatalf("board +move failed: %v", err)
+	}
+
+	// 验证 PATCH body 包含正确的 status_id
+	if patchPayload["status_id"] != float64(2) {
+		t.Errorf("expected status_id=2, got %v", patchPayload["status_id"])
+	}
+	// 验证 subject 和 description 被保留
+	if patchPayload["subject"] != "Fix login bug" {
+		t.Errorf("subject not preserved: got %v", patchPayload["subject"])
+	}
+	if patchPayload["description"] != "Steps to reproduce..." {
+		t.Errorf("description not preserved: got %v", patchPayload["description"])
+	}
+}
+
+func TestBoardAssignSendsAssignedToID(t *testing.T) {
+	var patchPayload map[string]interface{}
+	server := newBoardTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET" && r.URL.Path == "/users/zhangsan.json":
+			writeJSON(t, w, map[string]interface{}{"id": float64(999), "login": "zhangsan"})
+		case r.Method == "GET" && strings.Contains(r.URL.Path, "/issues/1"):
+			writeJSON(t, w, map[string]interface{}{
+				"subject":     "Fix login bug",
+				"description": "Steps to reproduce...",
+			})
+		case r.Method == "PATCH" && strings.Contains(r.URL.Path, "/issues/1"):
+			patchPayload = decodeJSON(t, r)
+			writeJSON(t, w, patchPayload)
+		default:
+			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runBoardShortcut(t, server, "assign", map[string]string{
+		"number":   "1",
+		"assignee": "zhangsan",
+	})
+	if err != nil {
+		t.Fatalf("board +assign failed: %v", err)
+	}
+
+	if patchPayload["assigned_to_id"] != float64(999) {
+		t.Errorf("expected assigned_to_id=999, got %v", patchPayload["assigned_to_id"])
+	}
+}
+
+func TestParseStatusID(t *testing.T) {
+	tests := []struct {
+		input string
+		want  int
+		err   bool
+	}{
+		{"new", 1, false},
+		{"in-progress", 2, false},
+		{"in_progress", 2, false},
+		{"resolved", 3, false},
+		{"closed", 5, false},
+		{"rejected", 6, false},
+		{"进行中", 2, false},
+		{"42", 42, false},
+		{"invalid", 0, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got, err := parseStatusID(tt.input)
+			if tt.err && err == nil {
+				t.Errorf("expected error for %q", tt.input)
+			}
+			if !tt.err && err != nil {
+				t.Errorf("unexpected error for %q: %v", tt.input, err)
+			}
+			if got != tt.want {
+				t.Errorf("parseStatusID(%q) = %d, want %d", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParsePriorityID(t *testing.T) {
+	tests := []struct {
+		input string
+		want  int
+		err   bool
+	}{
+		{"low", 1, false},
+		{"normal", 2, false},
+		{"high", 3, false},
+		{"urgent", 4, false},
+		{"99", 99, false},
+		{"invalid", 0, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got, err := parsePriorityID(tt.input)
+			if tt.err && err == nil {
+				t.Errorf("expected error for %q", tt.input)
+			}
+			if !tt.err && err != nil {
+				t.Errorf("unexpected error for %q: %v", tt.input, err)
+			}
+			if got != tt.want {
+				t.Errorf("parsePriorityID(%q) = %d, want %d", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestGroupByStatus(t *testing.T) {
+	issues := []issueItem{
+		{ID: 1, StatusID: 1},
+		{ID: 2, StatusID: 2},
+		{ID: 3, StatusID: 2},
+		{ID: 4, StatusID: 3},
+	}
+	grouped := groupByStatus(issues)
+	if len(grouped[1]) != 1 {
+		t.Errorf("expected 1 issue in status 1, got %d", len(grouped[1]))
+	}
+	if len(grouped[2]) != 2 {
+		t.Errorf("expected 2 issues in status 2, got %d", len(grouped[2]))
+	}
+	if len(grouped[3]) != 1 {
+		t.Errorf("expected 1 issue in status 3, got %d", len(grouped[3]))
+	}
+}
+```
+
+---
+
+## 帮助文档更新
+
+board 的帮助信息已经在 `board.go` 的 `Description`/`Long`/`Example` 字段中定义，`board --help` 会自动输出。无需额外文档文件。
+
+如果要更新项目 README 或 skill 文档，在对应文件中添加：
+
+```markdown
+### Board (看板)
+
+```bash
+# 查看看板
+gitlink-cli board +view
+
+# 按状态筛选
+gitlink-cli board +issues --status in-progress --assignee zhangsan
+
+# 移动任务
+gitlink-cli board +move --number 42 --status resolved
+
+# 统计分析
+gitlink-cli board +stats
+```
+```
+
+---
+
+## PR Checklist
+
+```markdown
+## Checklist
+
+- [ ] `go build ./...` 编译通过
+- [ ] `go test ./shortcuts/board/...` 测试通过
+- [ ] `go vet ./...` 无警告
+- [ ] 新命令 `--help` 输出正确
+- [ ] 写命令支持 `--dry-run`
+- [ ] 错误信息使用 `clierrors.OpError` 包装
+- [ ] commit message 符合 `type(scope): description` 格式
+```
--- a/doc/dashboard.html
+++ b/doc/dashboard.html
@ -0,0 +1,400 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>gitlink-cli · 功能全景</title>
+<style>
+  :root {
+    --bg:           #0d1117;
+    --bg-subtle:    #161b22;
+    --bg-inset:     #010409;
+    --border:       #30363d;
+    --border-muted: #21262d;
+    --text:         #c9d1d9;
+    --text-muted:   #8b949e;
+    --accent:       #58a6ff;
+    --accent-soft:  rgba(56,139,253,0.15);
+    --green:        #3fb950;
+    --green-soft:   rgba(63,185,80,0.12);
+    --purple:       #bc8cff;
+    --radius:       12px;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html { scroll-behavior: smooth; }
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
+                 "Microsoft YaHei", "Hiragino Sans GB", Helvetica, Arial, sans-serif;
+    line-height: 1.55;
+    -webkit-font-smoothing: antialiased;
+    min-height: 100vh;
+    background-image:
+      radial-gradient(900px 380px at 100% -8%, rgba(56,139,253,0.10), transparent 60%),
+      radial-gradient(800px 360px at -8% -4%, rgba(188,140,255,0.08), transparent 60%);
+    background-attachment: fixed;
+  }
+
+  /* ---------- Header ---------- */
+  header {
+    position: sticky; top: 0; z-index: 50;
+    backdrop-filter: blur(12px);
+    background: rgba(13,17,23,0.78);
+    border-bottom: 1px solid var(--border);
+  }
+  .header-inner {
+    max-width: 1200px; margin: 0 auto;
+    padding: 22px 24px 18px;
+    display: flex; align-items: center; gap: 16px; flex-wrap: wrap;
+  }
+  .brand { display: flex; align-items: center; gap: 12px; margin-right: auto; }
+  .logo {
+    width: 44px; height: 44px; border-radius: 11px;
+    background: linear-gradient(135deg, #2f81f7, #8957e5);
+    display: grid; place-items: center;
+    font-size: 24px; color: #fff; font-weight: 800;
+    box-shadow: 0 4px 14px rgba(56,139,253,0.45);
+  }
+  .brand h1 { font-size: 20px; font-weight: 650; letter-spacing: -0.3px; }
+  .brand .sub { font-size: 12.5px; color: var(--text-muted); }
+
+  .search-wrap { position: relative; flex: 0 1 320px; min-width: 200px; }
+  .search-wrap svg { position: absolute; left: 12px; top: 50%; transform: translateY(-50%); color: var(--text-muted); }
+  input#search {
+    width: 100%; padding: 10px 14px 10px 38px;
+    background: var(--bg-inset); color: var(--text);
+    border: 1px solid var(--border); border-radius: 9px;
+    font-size: 14px; outline: none; transition: .15s;
+  }
+  input#search:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+  .kbd {
+    position: absolute; right: 10px; top: 50%; transform: translateY(-50%);
+    font-size: 11px; color: var(--text-muted);
+    border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px;
+    background: var(--bg-subtle);
+  }
+
+  /* ---------- Stats ---------- */
+  .stats {
+    max-width: 1200px; margin: 0 auto;
+    padding: 26px 24px 6px;
+    display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px;
+  }
+  .stat {
+    background: var(--bg-subtle);
+    border: 1px solid var(--border-muted);
+    border-radius: var(--radius);
+    padding: 16px 18px;
+    position: relative; overflow: hidden;
+  }
+  .stat::after {
+    content: ""; position: absolute; left: 0; top: 0; bottom: 0; width: 3px;
+    background: var(--accent);
+  }
+  .stat.green::after { background: var(--green); }
+  .stat.purple::after { background: var(--purple); }
+  .stat.muted::after { background: var(--text-muted); }
+  .stat .num { font-size: 28px; font-weight: 700; letter-spacing: -1px; }
+  .stat .label { font-size: 12.5px; color: var(--text-muted); margin-top: 2px; }
+
+  /* ---------- Layout ---------- */
+  main { max-width: 1200px; margin: 0 auto; padding: 22px 24px 64px; }
+  .grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; }
+
+  /* ---------- Category card ---------- */
+  .card {
+    background: var(--bg-subtle);
+    border: 1px solid var(--border-muted);
+    border-radius: var(--radius);
+    overflow: hidden; transition: border-color .15s;
+  }
+  .card:hover { border-color: var(--border); }
+  .card-head {
+    display: flex; align-items: center; gap: 12px;
+    padding: 15px 18px; cursor: pointer; user-select: none;
+    transition: background .12s;
+  }
+  .card-head:hover { background: rgba(177,186,196,0.04); }
+  .card-icon { font-size: 20px; line-height: 1; }
+  .card-title { font-size: 15px; font-weight: 600; flex: 1; }
+  .count-badge {
+    font-size: 12px; color: var(--text-muted);
+    background: var(--bg-inset); border: 1px solid var(--border);
+    padding: 2px 9px; border-radius: 20px; font-variant-numeric: tabular-nums;
+  }
+  .chev { color: var(--text-muted); transition: transform .2s; flex-shrink: 0; }
+  .card.open .chev { transform: rotate(90deg); }
+
+  .card-body { max-height: 0; overflow: hidden; transition: max-height .25s ease; }
+  .card.open .card-body { max-height: 2400px; }
+
+  .row {
+    border-top: 1px solid var(--border-muted);
+    padding: 11px 18px;
+    cursor: pointer; transition: background .12s;
+  }
+  .row:hover { background: rgba(56,139,253,0.06); }
+  .row-main { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+  .cmd {
+    font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+    font-size: 13px; color: var(--accent); font-weight: 600;
+  }
+  .tag {
+    font-size: 10.5px; font-weight: 600; letter-spacing: .3px;
+    padding: 2px 7px; border-radius: 20px; white-space: nowrap;
+  }
+  .tag.auth   { color: var(--green);  background: var(--green-soft); }
+  .tag.public { color: var(--accent); background: var(--accent-soft); }
+  .desc { color: var(--text-muted); font-size: 13px; flex: 1; min-width: 120px; }
+
+  .example {
+    max-height: 0; overflow: hidden; transition: max-height .2s ease;
+  }
+  .row.expanded .example { max-height: 140px; padding-top: 8px; }
+  .example code {
+    display: block;
+    font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+    font-size: 12px; color: var(--text);
+    background: var(--bg-inset);
+    border: 1px solid var(--border-muted); border-left: 3px solid var(--accent);
+    border-radius: 7px; padding: 10px 12px;
+    white-space: pre-wrap; word-break: break-all;
+  }
+
+  /* ---------- Empty / footer ---------- */
+  #empty {
+    text-align: center; padding: 60px 20px; color: var(--text-muted);
+    display: none;
+  }
+  #empty .big { font-size: 40px; margin-bottom: 10px; }
+  footer {
+    max-width: 1200px; margin: 0 auto;
+    padding: 0 24px 40px; text-align: center;
+    color: var(--text-muted); font-size: 12.5px;
+  }
+  footer a { color: var(--accent); text-decoration: none; }
+  footer a:hover { text-decoration: underline; }
+
+  @media (max-width: 760px) {
+    .stats { grid-template-columns: repeat(2, 1fr); }
+    .grid { grid-template-columns: 1fr; }
+    .search-wrap { flex: 1 1 100%; }
+    .header-inner { gap: 12px; }
+  }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="header-inner">
+    <div class="brand">
+      <div class="logo">G</div>
+      <div>
+        <h1>gitlink-cli · 功能全景</h1>
+        <div class="sub">交互式命令浏览仪表盘</div>
+      </div>
+    </div>
+    <div class="search-wrap">
+      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M11.5 7a4.5 4.5 0 1 1-9 0 4.5 4.5 0 0 1 9 0Zm-.82 4.74a6 6 0 1 1 1.06-1.06l3.04 3.04a.75.75 0 1 1-1.06 1.06l-3.04-3.04Z"/></svg>
+      <input id="search" type="text" placeholder="搜索命令或描述…  ( 按 / 聚焦 )" autocomplete="off">
+      <span class="kbd">/</span>
+    </div>
+  </div>
+</header>
+
+<section class="stats">
+  <div class="stat"><div class="num" id="st-cat">0</div><div class="label">功能分类</div></div>
+  <div class="stat purple"><div class="num" id="st-total">0</div><div class="label">Shortcuts 总数</div></div>
+  <div class="stat green"><div class="num" id="st-auth">0</div><div class="label">需认证命令</div></div>
+  <div class="stat muted"><div class="num" id="st-public">0</div><div class="label">公开命令</div></div>
+</section>
+
+<main>
+  <div class="grid" id="grid"></div>
+  <div id="empty">
+    <div class="big">🔍</div>
+    <div>没有匹配的命令，换个关键词试试。</div>
+  </div>
+</main>
+
+<footer>
+  Generated by <strong>gitlink-code-insight</strong> skill ·
+  <a href="https://gitlink.org.cn" target="_blank" rel="noopener">Gitlink</a> ·
+  共 <span id="ft-total">0</span> 个命令
+</footer>
+
+<script>
+const DATA = [
+  { cat: "仓库管理", icon: "📦", items: [
+    { cmd: "repo +list", desc: "仓库列表", auth: false, ex: "gitlink-cli repo +list --user zhangsan" },
+    { cmd: "repo +info", desc: "仓库详情", auth: false, ex: "gitlink-cli repo +info --owner Gitlink --repo forgeplus" },
+    { cmd: "repo +create", desc: "创建仓库", auth: true, ex: 'gitlink-cli repo +create --name my-project --description "项目描述"' },
+    { cmd: "repo +fork", desc: "Fork 仓库", auth: true, ex: "gitlink-cli repo +fork --owner Gitlink --repo forgeplus" },
+    { cmd: "repo +delete", desc: "删除仓库（不可逆）", auth: true, ex: "gitlink-cli repo +delete --owner myuser --repo old-project" },
+    { cmd: "repo +batch-create", desc: "批量创建仓库", auth: true, ex: "gitlink-cli repo +batch-create --from repos.csv" },
+    { cmd: "repo +batch-update", desc: "批量更新仓库", auth: true, ex: "gitlink-cli repo +batch-update --from updates.csv" },
+    { cmd: "repo +add-member", desc: "添加仓库成员", auth: true, ex: "gitlink-cli repo +add-member --owner myuser --repo myrepo --user newmember --role developer" },
+  ]},
+  { cat: "分支管理", icon: "🌿", items: [
+    { cmd: "branch +list", desc: "分支列表", auth: false, ex: "gitlink-cli branch +list --owner Gitlink --repo forgeplus" },
+    { cmd: "branch +create", desc: "创建分支", auth: true, ex: "gitlink-cli branch +create --name feature/new-feature" },
+    { cmd: "branch +delete", desc: "删除分支（不可逆）", auth: true, ex: "gitlink-cli branch +delete --name feature/old-feature" },
+    { cmd: "branch +protect", desc: "保护分支", auth: true, ex: "gitlink-cli branch +protect --name main" },
+    { cmd: "branch +unprotect", desc: "取消保护", auth: true, ex: "gitlink-cli branch +unprotect --name main" },
+  ]},
+  { cat: "Issue 管理", icon: "🐛", items: [
+    { cmd: "issue +list", desc: "Issue 列表", auth: false, ex: "gitlink-cli issue +list --owner Gitlink --repo forgeplus --state open" },
+    { cmd: "issue +view", desc: "Issue 详情", auth: false, ex: "gitlink-cli issue +view --owner Gitlink --repo forgeplus --number 4" },
+    { cmd: "issue +create", desc: "创建 Issue", auth: true, ex: 'gitlink-cli issue +create --owner myuser --repo myrepo --title "Bug: 登录失败" --body "复现步骤"' },
+    { cmd: "issue +update", desc: "更新 Issue", auth: true, ex: 'gitlink-cli issue +update --number 4 --title "新标题" --body "更新描述"' },
+    { cmd: "issue +close", desc: "关闭 Issue", auth: true, ex: "gitlink-cli issue +close --number 4" },
+    { cmd: "issue +batch-close", desc: "批量关闭 Issue", auth: true, ex: "gitlink-cli issue +batch-close --numbers 123,124 --dry-run" },
+    { cmd: "issue +comment", desc: "添加评论", auth: true, ex: 'gitlink-cli issue +comment --number 4 --body "已修复"' },
+  ]},
+  { cat: "Pull Request", icon: "🔀", items: [
+    { cmd: "pr +list", desc: "PR 列表", auth: false, ex: "gitlink-cli pr +list --owner Gitlink --repo forgeplus --state open" },
+    { cmd: "pr +view", desc: "PR 详情", auth: false, ex: "gitlink-cli pr +view --id 3" },
+    { cmd: "pr +create", desc: "创建 PR", auth: true, ex: 'gitlink-cli pr +create --title "feat: 新功能" --head feature/x --base master' },
+    { cmd: "pr +merge", desc: "合并 PR", auth: true, ex: "gitlink-cli pr +merge --id 3 --method squash" },
+    { cmd: "pr +close", desc: "关闭 PR", auth: true, ex: "gitlink-cli pr +close --id 3" },
+    { cmd: "pr +files", desc: "变更文件列表", auth: false, ex: "gitlink-cli pr +files --id 3" },
+    { cmd: "pr +diff", desc: "查看提交列表", auth: false, ex: "gitlink-cli pr +diff --id 3" },
+    { cmd: "pr +comment", desc: "PR 评论", auth: true, ex: 'gitlink-cli pr +comment --id 3 --body "LGTM"' },
+    { cmd: "pr +review", desc: "代码审查", auth: true, ex: 'gitlink-cli pr +review --id 3 --event COMMENT --body "整体 LGTM"' },
+  ]},
+  { cat: "版本发布", icon: "🚀", items: [
+    { cmd: "release +list", desc: "发布列表", auth: false, ex: "gitlink-cli release +list --owner Gitlink --repo forgeplus" },
+    { cmd: "release +view", desc: "发布详情", auth: false, ex: "gitlink-cli release +view --id <version_id>" },
+    { cmd: "release +create", desc: "创建发布", auth: true, ex: 'gitlink-cli release +create --tag v1.0.0 --name "v1.0.0" --target master' },
+    { cmd: "release +delete", desc: "删除发布（不可逆）", auth: true, ex: "gitlink-cli release +delete --id <version_id>" },
+  ]},
+  { cat: "Wiki 管理", icon: "📖", items: [
+    { cmd: "wiki +list", desc: "Wiki 页面列表", auth: false, ex: "gitlink-cli wiki +list --owner Gitlink --repo forgeplus" },
+    { cmd: "wiki +view", desc: "查看页面内容", auth: false, ex: 'gitlink-cli wiki +view --owner Gitlink --repo forgeplus --title "Home"' },
+    { cmd: "wiki +create", desc: "创建页面", auth: true, ex: 'gitlink-cli wiki +create --owner myuser --repo myrepo --title "API 文档" --file ./api.md' },
+    { cmd: "wiki +update", desc: "更新页面", auth: true, ex: 'gitlink-cli wiki +update --owner myuser --repo myrepo --title "设计文档" --add "新内容"' },
+    { cmd: "wiki +delete", desc: "删除页面", auth: true, ex: 'gitlink-cli wiki +delete --owner myuser --repo myrepo --title "废弃页面"' },
+  ]},
+  { cat: "CI/CD", icon: "⚙️", items: [
+    { cmd: "ci +builds", desc: "构建列表", auth: true, ex: "gitlink-cli ci +builds --owner myuser --repo myrepo" },
+    { cmd: "ci +logs", desc: "构建日志", auth: true, ex: "gitlink-cli ci +logs --build 42 --stage 1 --step 1" },
+    { cmd: "ci +restart", desc: "重启构建", auth: true, ex: "gitlink-cli ci +restart --build 42" },
+    { cmd: "ci +stop", desc: "停止构建", auth: true, ex: "gitlink-cli ci +stop --build 42" },
+  ]},
+  { cat: "Webhook", icon: "🔔", items: [
+    { cmd: "webhook +list", desc: "Webhook 列表", auth: true, ex: "gitlink-cli webhook +list --owner myuser --repo myrepo" },
+    { cmd: "webhook +info", desc: "Webhook 详情", auth: true, ex: "gitlink-cli webhook +info --owner myuser --repo myrepo --id 123" },
+    { cmd: "webhook +events", desc: "支持的事件类型", auth: false, ex: "gitlink-cli webhook +events" },
+    { cmd: "webhook +create", desc: "创建 Webhook", auth: true, ex: "gitlink-cli webhook +create --url https://example.com/hook --events push" },
+    { cmd: "webhook +update", desc: "更新 Webhook", auth: true, ex: "gitlink-cli webhook +update --id 123 --events push,pull_request" },
+    { cmd: "webhook +test", desc: "测试 Webhook", auth: true, ex: "gitlink-cli webhook +test --id 123 --event push" },
+    { cmd: "webhook +delete", desc: "删除 Webhook", auth: true, ex: "gitlink-cli webhook +delete --id 123" },
+  ]},
+  { cat: "组织管理", icon: "🏢", items: [
+    { cmd: "org +list", desc: "组织列表", auth: false, ex: "gitlink-cli org +list" },
+    { cmd: "org +info", desc: "组织详情", auth: false, ex: "gitlink-cli org +info --id Gitlink" },
+    { cmd: "org +members", desc: "成员列表", auth: false, ex: "gitlink-cli org +members --id Gitlink" },
+    { cmd: "org +create", desc: "创建组织", auth: true, ex: 'gitlink-cli org +create --name my-org --description "我的组织"' },
+    { cmd: "org +batch-add", desc: "批量添加成员", auth: true, ex: 'gitlink-cli org +batch-add --id my-org --users "user1,user2"' },
+  ]},
+  { cat: "用户与搜索", icon: "👤", items: [
+    { cmd: "user +me", desc: "当前登录用户", auth: true, ex: "gitlink-cli user +me" },
+    { cmd: "user +info", desc: "用户详情", auth: false, ex: "gitlink-cli user +info --login zhangsan" },
+    { cmd: "search +repos", desc: "搜索仓库", auth: false, ex: 'gitlink-cli search +repos --keyword "machine learning"' },
+    { cmd: "search +users", desc: "搜索用户", auth: false, ex: 'gitlink-cli search +users --keyword "zhangsan"' },
+  ]},
+  { cat: "安全与合规", icon: "🛡️", items: [
+    { cmd: "compliance +scan", desc: "全量扫描", auth: false, ex: "gitlink-cli compliance +scan" },
+    { cmd: "compliance +license", desc: "许可证合规检查", auth: false, ex: "gitlink-cli compliance +license" },
+    { cmd: "compliance +deps", desc: "依赖许可证检查", auth: false, ex: "gitlink-cli compliance +deps" },
+    { cmd: "compliance +secrets", desc: "敏感信息扫描", auth: false, ex: "gitlink-cli compliance +secrets" },
+    { cmd: "compliance +exposure", desc: "PII 与暴露面扫描", auth: false, ex: "gitlink-cli compliance +exposure" },
+    { cmd: "compliance +vocab", desc: "敏感词汇扫描", auth: false, ex: "gitlink-cli compliance +vocab" },
+  ]},
+  { cat: "新人引导", icon: "👋", items: [
+    { cmd: "onboard +welcome", desc: "添加引导评论", auth: true, ex: 'gitlink-cli onboard +welcome --issues "3,7,15"' },
+  ]},
+  { cat: "团队管理", icon: "👥", items: [
+    { cmd: "team +list", desc: "团队列表", auth: false, ex: "gitlink-cli team +list --org my-org" },
+    { cmd: "team +create", desc: "创建团队", auth: true, ex: "gitlink-cli team +create --org my-org --name dev-team" },
+    { cmd: "team +add-member", desc: "添加成员", auth: true, ex: "gitlink-cli team +add-member --org my-org --team dev-team --user newmember" },
+  ]},
+  { cat: "贡献报告", icon: "📊", items: [
+    { cmd: "contrib +report", desc: "贡献统计报告", auth: false, ex: "gitlink-cli contrib +report --owner myuser --repo myrepo" },
+  ]},
+];
+
+const esc = s => s.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;");
+const grid = document.getElementById("grid");
+const empty = document.getElementById("empty");
+
+// 全量统计（不随搜索变化）
+const TOTAL  = DATA.reduce((n, c) => n + c.items.length, 0);
+const AUTHN  = DATA.reduce((n, c) => n + c.items.filter(i => i.auth).length, 0);
+const PUBLIC = TOTAL - AUTHN;
+document.getElementById("st-cat").textContent = DATA.length;
+document.getElementById("st-total").textContent = TOTAL;
+document.getElementById("st-auth").textContent = AUTHN;
+document.getElementById("st-public").textContent = PUBLIC;
+document.getElementById("ft-total").textContent = TOTAL;
+
+function render(filter = "") {
+  const q = filter.trim().toLowerCase();
+  grid.innerHTML = "";
+  let shownCats = 0;
+
+  DATA.forEach(c => {
+    const matched = c.items.filter(it =>
+      !q || it.cmd.toLowerCase().includes(q) || it.desc.toLowerCase().includes(q) || c.cat.toLowerCase().includes(q)
+    );
+    if (!matched.length) return;
+    shownCats++;
+
+    const card = document.createElement("div");
+    card.className = "card" + (q ? " open" : ""); // 搜索时自动展开
+    card.innerHTML = `
+      <div class="card-head">
+        <span class="card-icon">${c.icon}</span>
+        <span class="card-title">${c.cat}</span>
+        <span class="count-badge">${matched.length}</span>
+        <svg class="chev" width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06Z"/></svg>
+      </div>
+      <div class="card-body">
+        ${matched.map(it => `
+          <div class="row">
+            <div class="row-main">
+              <span class="cmd">${esc(it.cmd)}</span>
+              <span class="tag ${it.auth ? "auth" : "public"}">${it.auth ? "需认证" : "公开"}</span>
+              <span class="desc">${esc(it.desc)}</span>
+            </div>
+            <div class="example"><code>$ ${esc(it.ex)}</code></div>
+          </div>`).join("")}
+      </div>`;
+    grid.appendChild(card);
+  });
+
+  empty.style.display = shownCats === 0 ? "block" : "none";
+
+  // 绑定交互
+  grid.querySelectorAll(".card-head").forEach(h =>
+    h.addEventListener("click", () => h.parentElement.classList.toggle("open")));
+  grid.querySelectorAll(".row").forEach(r =>
+    r.addEventListener("click", e => { e.stopPropagation(); r.classList.toggle("expanded"); }));
+}
+
+// 搜索（带去抖）
+const input = document.getElementById("search");
+let t;
+input.addEventListener("input", e => { clearTimeout(t); t = setTimeout(() => render(e.target.value), 80); });
+
+// 快捷键
+document.addEventListener("keydown", e => {
+  if (e.key === "/" && document.activeElement !== input) { e.preventDefault(); input.focus(); }
+  if (e.key === "Escape") { input.value = ""; render(""); input.blur(); }
+});
+
+render();
+</script>
+</body>
+</html>
--- a/doc/generate_word.py
+++ b/doc/generate_word.py
@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""生成系统动态模型章节的 Word 文档 - 四个赛题"""
+
+from docx import Document
+from docx.shared import Pt, Inches, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+
+def set_cell_shading(cell, color):
+    """设置单元格背景颜色"""
+    shading = OxmlElement('w:shd')
+    shading.set(qn('w:fill'), color)
+    cell._tc.get_or_add_tcPr().append(shading)
+
+def add_table(doc, headers, rows, header_color="4472C4"):
+    """添加表格"""
+    table = doc.add_table(rows=len(rows)+1, cols=len(headers))
+    table.style = 'Table Grid'
+    table.alignment = WD_TABLE_ALIGNMENT.CENTER
+
+    # 表头
+    for i, header in enumerate(headers):
+        cell = table.rows[0].cells[i]
+        cell.text = header
+        set_cell_shading(cell, header_color)
+        for paragraph in cell.paragraphs:
+            paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            for run in paragraph.runs:
+                run.font.bold = True
+                run.font.color.rgb = RGBColor(255, 255, 255)
+
+    # 数据行
+    for i, row in enumerate(rows):
+        for j, value in enumerate(row):
+            table.rows[i+1].cells[j].text = value
+
+    return table
+
+def create_document():
+    doc = Document()
+
+    # 设置默认字体
+    style = doc.styles['Normal']
+    style.font.name = 'Microsoft YaHei'
+    style._element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')
+
+    # 标题
+    title = doc.add_heading('系统动态模型', 0)
+    title.alignment = WD_ALIGN_PARAGRAPH.CENTER
+
+    # 概述
+    doc.add_heading('概述', level=1)
+    doc.add_paragraph(
+        '系统动态模型描述了 gitlink-cli 在四个赛题场景下的运行时行为，'
+        '展示了各组件之间的交互流程和数据流向。每个赛题对应一个核心能力方向，'
+        '覆盖 CLI 功能扩展、Skills 开发、自动化工作流和科研辅助四大领域。'
+    )
+
+    # ==================== 赛题一 ====================
+    doc.add_heading('子赛题一：增加和完善 GitLink-CLI 能力', level=1)
+
+    doc.add_heading('1.1 能构建的模型', level=2)
+    doc.add_paragraph(
+        '本赛题聚焦于 CLI 命令系统的功能扩展和优化。可构建以下动态模型：'
+    )
+    doc.add_paragraph('命令执行模型：描述 Shortcut 命令从参数解析到 API 调用的完整执行流程', style='List Bullet')
+    doc.add_paragraph('批量操作模型：描述批量命令（batch-close、batch-create 等）的遍历执行和错误处理机制', style='List Bullet')
+    doc.add_paragraph('参数校验模型：描述 Choices 枚举校验和 Validate 自定义校验的执行流程', style='List Bullet')
+    doc.add_paragraph('输出格式化模型：描述 Envelope 数据经过 table/json/yaml 格式化后的输出流程', style='List Bullet')
+
+    doc.add_heading('1.2 新生成的组件', level=2)
+    add_table(doc,
+        ['组件类型', '组件名称', '功能说明'],
+        [
+            ['Shortcut', 'wiki +list/+view/+create/+update/+delete', 'Wiki 页面 CRUD 操作'],
+            ['Shortcut', 'webhook +list/+create/+update/+delete/+test', 'Webhook 配置管理'],
+            ['Shortcut', 'board +view/+columns/+issues/+move/+assign', '项目看板操作'],
+            ['Shortcut', 'issue +batch-close/+batch-create/+batch-assign', 'Issue 批量操作'],
+            ['Shortcut', 'repo +batch-create/+batch-update', '仓库批量操作'],
+            ['Shortcut', 'pr +merge (支持 merge/rebase/squash)', 'PR 合并方式选择'],
+            ['Shortcut', 'branch +protect/+unprotect', '分支保护规则管理'],
+            ['Shortcut', 'release +list/+create/+view/+delete', '版本发布管理'],
+            ['结构体', 'Flag.Choices', '枚举参数校验，自动追加 [val1|val2] 提示'],
+            ['结构体', 'Flag.Validate', '自定义校验函数，跨参数约束'],
+            ['结构体', 'PrintOptions', '输出选项：列过滤、禁用截断、彩色输出'],
+            ['函数', 'OpError()', '统一错误构造函数，中英文双语错误信息'],
+        ]
+    )
+
+    doc.add_heading('1.3 交互流程示例', level=2)
+
+    doc.add_paragraph('示例一：Wiki 页面创建', style='List Bullet')
+    steps = [
+        '用户输入：gitlink-cli wiki +create --title "API文档" --content "# API Reference"',
+        'Cobra 解析命令，匹配到 wiki +create Shortcut',
+        'Validate 校验：检查 --title 是否为空',
+        'ResolveOwnerRepo() 从 git remote 解析 owner/repo',
+        'CallAPI("POST", "/wiki/open/createWiki", body) 调用 Gateway API',
+        'OutputData() 格式化输出创建结果',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例二：枚举参数校验', style='List Bullet')
+    steps = [
+        '用户输入：gitlink-cli pr +merge --id 42 --method unknown',
+        'Cobra 解析参数，发现 --method 值为 unknown',
+        'Choices 校验：unknown 不在 [merge, rebase, squash] 中',
+        '输出错误：invalid value "unknown" for --method，有效值: merge, rebase, squash',
+        '命令终止，exit code = 1',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例三：批量关闭 Issue（dry-run 预览）', style='List Bullet')
+    steps = [
+        '用户输入：gitlink-cli issue +batch-close --numbers 101,102,103 --dry-run',
+        '解析 --numbers 参数，得到 [101, 102, 103]',
+        'IsDryRun() == true，进入预览模式',
+        '构建 BatchSummary {dry_run: true, total: 3, results: [{status: "planned"},...]}',
+        '输出预览结果，不发起 HTTP 请求',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    # ==================== 赛题二 ====================
+    doc.add_heading('子赛题二：编写和丰富 GitLink Skills', level=1)
+
+    doc.add_heading('2.1 能构建的模型', level=2)
+    doc.add_paragraph(
+        '本赛题聚焦于 AI Agent Skill 的开发。可构建以下动态模型：'
+    )
+    doc.add_paragraph('Skill 加载模型：描述 Claude Code 触发 Skill、加载 SKILL.md 和 reference 文档的流程', style='List Bullet')
+    doc.add_paragraph('AI 分析模型：描述 AI 对 PR Diff、Issue 内容、仓库数据的分析和决策流程', style='List Bullet')
+    doc.add_paragraph('自动执行模型：描述 AI 分析结果转化为 CLI 命令执行的流程', style='List Bullet')
+
+    doc.add_heading('2.2 新生成的组件', level=2)
+    add_table(doc,
+        ['组件类型', '组件名称', '功能说明'],
+        [
+            ['Skill', 'gitlink-code-review', '智能代码审查：分析 PR diff，输出结构化 Review 意见'],
+            ['Skill', 'gitlink-issue-triage', 'Issue 自动分拣：根据内容自动分类、打标签、分配责任人'],
+            ['Skill', 'gitlink-changelog', 'Release Notes 生成：根据 commit 和 PR 生成版本说明'],
+            ['Skill', 'gitlink-health', '项目健康度报告：统计 Issue 响应时间、PR 合并效率'],
+            ['Skill', 'gitlink-compliance', '许可证合规检查：扫描许可证合规性和敏感信息泄露'],
+            ['Skill', 'gitlink-onboard', '新人引导：为 good-first-issue 自动添加引导评论'],
+            ['Skill', 'gitlink-stale', '过期 Issue 管理：自动标记和关闭长期未活动的 Issue'],
+            ['Skill', 'gitlink-faq', 'FAQ 自动回复：根据 Issue 内容匹配 FAQ 并自动评论'],
+            ['Reference', 'references/pr-review.md', 'PR 审查参考文档：审查维度、评分标准、评论模板'],
+            ['Reference', 'references/issue-triage.md', 'Issue 分类参考文档：分类规则、标签映射、分配策略'],
+        ]
+    )
+
+    doc.add_heading('2.3 交互流程示例', level=2)
+
+    doc.add_paragraph('示例一：智能代码审查', style='List Bullet')
+    steps = [
+        '用户触发："帮我审查 PR #42"',
+        'Claude Code 加载 gitlink-code-review skill',
+        '获取 PR 详情：gitlink-cli pr +view --id 42 --format json',
+        '获取变更文件：gitlink-cli pr +files --id 42 --format json',
+        'AI 分析代码：检测未处理 error、SQL 注入风险、性能问题',
+        '生成审查报告：质量评分 8.5/10，列出 3 个问题',
+        '提交审查评论：gitlink-cli pr +review --id 42 --body "..." --event comment',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例二：Issue 自动分拣', style='List Bullet')
+    steps = [
+        '用户触发："帮我分类本周的 Issue"',
+        'Claude Code 加载 gitlink-issue-triage skill',
+        '获取 Issue 列表：gitlink-cli issue +list --state open --format json',
+        'AI 分析内容：识别关键词（bug/功能/提问）',
+        '自动添加标签：gitlink-cli issue +label-add --number 101 --labels "缺陷"',
+        '自动分配责任人：gitlink-cli issue +update --number 101 --assignee "zhangsan"',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例三：Release Notes 生成', style='List Bullet')
+    steps = [
+        '用户触发："帮我生成 v2.1.0 的 Release Notes"',
+        'Claude Code 加载 gitlink-changelog skill',
+        '获取已合并 PR：gitlink-cli pr +list --state merged --format json',
+        '获取 commit 历史：git log --oneline v2.0.0..HEAD',
+        'AI 分类整理：新功能、Bug 修复、性能优化、Breaking Changes',
+        '生成 Release Notes：gitlink-cli release +create --tag v2.1.0 --body "..."',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    # ==================== 赛题三 ====================
+    doc.add_heading('子赛题三：构建端到端自动化工作流', level=1)
+
+    doc.add_heading('3.1 能构建的模型', level=2)
+    doc.add_paragraph(
+        '本赛题聚焦于串联多个步骤的完整解决方案。可构建以下动态模型：'
+    )
+    doc.add_paragraph('工作流调度模型：描述工作流从触发、菜单选择、步骤执行到结果输出的完整流程', style='List Bullet')
+    doc.add_paragraph('多步骤编排模型：描述多个 CLI 命令和 Skill 的串联执行和错误处理', style='List Bullet')
+    doc.add_paragraph('数据聚合模型：描述从多个数据源采集数据并汇总生成报告的流程', style='List Bullet')
+
+    doc.add_heading('3.2 新生成的组件', level=2)
+    add_table(doc,
+        ['组件类型', '组件名称', '功能说明'],
+        [
+            ['Skill', 'gitlink-workflows', '工作流调度入口，提供功能菜单选择'],
+            ['Workflow', '01-community-ops.sh', '社区运营自动化：Issue 分类 + 周报生成'],
+            ['Workflow', '01a-issue-triage.sh', 'Issue 分类子工作流'],
+            ['Workflow', '01a-webhook-setup.sh', 'Webhook 配置子工作流'],
+            ['Workflow', '02-code-quality-gatekeeper.sh', '代码质量门禁：PR 审查 + 评分'],
+            ['Workflow', '03-project-init.sh', '项目一键初始化：仓库 + 文件 + CI + Issues'],
+            ['Workflow', '04-multi-repo-collab.sh', '多仓库协同：依赖追踪 + 协同发版'],
+            ['Workflow', '05-contributor-growth.sh', '贡献者成长体系：评分 + 排行 + Badge'],
+            ['Lib', 'lib/common.sh', '公共函数库：认证检查、错误处理、日志输出'],
+        ]
+    )
+
+    doc.add_heading('3.3 交互流程示例', level=2)
+
+    doc.add_paragraph('示例一：项目一键初始化', style='List Bullet')
+    steps = [
+        '用户触发："帮我初始化新项目 my-project"',
+        'Claude Code 加载 gitlink-workflows skill，显示菜单',
+        '用户选择"项目一键初始化"',
+        '认证检查：gitlink-cli auth status',
+        '创建仓库：gitlink-cli repo +create --name my-project --private',
+        '初始化文件：gitlink-cli file +create --path README.md --content "..."',
+        '初始化文件：gitlink-cli file +create --path .gitignore --content "..."',
+        '初始化文件：gitlink-cli file +create --path LICENSE --content "..."',
+        '配置分支保护：gitlink-cli branch +protect --name master --require-review',
+        '创建 Issues：gitlink-cli issue +create --title "完善单元测试" --labels "good-first-issue"',
+        '输出初始化报告',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例二：多仓库协同发版', style='List Bullet')
+    steps = [
+        '用户触发："帮我管理多仓库协同"',
+        '扫描仓库列表：gitlink-cli repo +list --user my-org --format json',
+        '分析依赖关系：frontend → api-client → backend',
+        '查询跨仓库 PR：gitlink-cli pr +list --state open --format json',
+        '检查发版就绪：gitlink-cli release +list --format json',
+        '识别阻塞项：backend PR #456 未合并',
+        '生成协同 Dashboard：显示各仓库状态、依赖关系、阻塞项',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例三：贡献者成长体系', style='List Bullet')
+    steps = [
+        '用户触发："帮我生成贡献者排行榜"',
+        '获取贡献者列表：gitlink-cli repo +members --format json',
+        '统计 PR 活动：gitlink-cli pr +list --state merged --format json',
+        '统计 Issue 活动：gitlink-cli issue +list --state closed --format json',
+        'AI 计算贡献评分：PR 数量 × 3 + Issue 数量 × 1 + Review × 2',
+        '生成排行榜：zhangsan(85分) > lisi(72分) > wangwu(68分)',
+        '自动颁发 Badge：为 top 3 贡献者添加 "core-contributor" 标签',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    # ==================== 赛题四 ====================
+    doc.add_heading('子赛题四：应用 GitLink 辅助科研', level=1)
+
+    doc.add_heading('4.1 能构建的模型', level=2)
+    doc.add_paragraph(
+        '本赛题聚焦于科研场景的智能化赋能。可构建以下动态模型：'
+    )
+    doc.add_paragraph('科研项目洞悉模型：描述从仓库数据提取科研项目信息（技术栈、活跃度、依赖）的流程', style='List Bullet')
+    doc.add_paragraph('热点追踪模型：描述从 Issue/PR/Commit 数据挖掘科研热点趋势的流程', style='List Bullet')
+    doc.add_paragraph('合规检查模型：描述许可证合规性扫描和敏感信息检测的流程', style='List Bullet')
+    doc.add_paragraph('协作匹配模型：描述根据贡献者技能和项目需求进行智能匹配的流程', style='List Bullet')
+
+    doc.add_heading('4.2 新生成的组件', level=2)
+    add_table(doc,
+        ['组件类型', '组件名称', '功能说明'],
+        [
+            ['Skill', 'gitlink-research', '科研辅助系统总入口，提供科研场景菜单'],
+            ['Skill', 'gitlink-code-insight', '仓库级科研项目洞悉：技术栈、活跃度、依赖分析'],
+            ['Skill', 'gitlink-compliance', '科研项目合规与复现性检查：许可证、依赖、环境'],
+            ['Workflow', '06-research-insights.sh', '科研热点追踪：从 Issue/PR 挖掘研究趋势'],
+            ['Workflow', '08-research-compliance.sh', '科研合规检查：扫描许可证和敏感信息'],
+            ['Workflow', '10-research-progress.sh', '科研进度跟踪：里程碑进度、阻塞项识别'],
+            ['Workflow', '11-research-citation.sh', '论文引用分析：追踪仓库的学术引用情况'],
+        ]
+    )
+
+    doc.add_heading('4.3 交互流程示例', level=2)
+
+    doc.add_paragraph('示例一：仓库级科研项目洞悉', style='List Bullet')
+    steps = [
+        '用户触发："帮我分析这个仓库的科研价值"',
+        'Claude Code 加载 gitlink-code-insight skill',
+        '获取仓库信息：gitlink-cli repo +info --format json',
+        '分析技术栈：扫描 package.json/go.mod/requirements.txt',
+        '分析活跃度：gitlink-cli pr +list --state merged --format json',
+        '分析依赖：识别上下游依赖关系',
+        '生成科研洞悉报告：技术栈、活跃贡献者、核心模块、研究方向',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例二：科研热点追踪', style='List Bullet')
+    steps = [
+        '用户触发："帮我追踪 AI 领域的科研热点"',
+        '扫描相关仓库：gitlink-cli search +repos --query "machine-learning"',
+        '获取 Issue 列表：gitlink-cli issue +list --state open --format json',
+        '获取 PR 列表：gitlink-cli pr +list --state merged --format json',
+        'AI 分析关键词：识别高频技术词汇（transformer、diffusion、LLM）',
+        '生成热点报告：技术趋势、热门项目、活跃研究者',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    doc.add_paragraph('示例三：科研合规与复现性检查', style='List Bullet')
+    steps = [
+        '用户触发："帮我检查这个科研项目的合规性"',
+        'Claude Code 加载 gitlink-compliance skill',
+        '扫描许可证：检查 LICENSE 文件和依赖许可证',
+        '扫描敏感信息：检查 API Key、密码、私钥泄露',
+        '检查复现性：验证 requirements.txt/go.mod 完整性',
+        '生成合规报告：许可证合规、依赖风险、复现性评分',
+    ]
+    for i, step in enumerate(steps, 1):
+        doc.add_paragraph(f'  {i}. {step}')
+
+    # ==================== 赛题对比总结 ====================
+    doc.add_heading('赛题对比总结', level=1)
+    add_table(doc,
+        ['维度', '赛题一：CLI 能力', '赛题二：Skills 开发', '赛题三：自动化工作流', '赛题四：辅助科研'],
+        [
+            ['核心目标', '扩展 CLI 命令', '开发 AI Skill', '串联完整流程', '科研场景赋能'],
+            ['技术栈', 'Go + Cobra', 'Markdown + CLI', 'Shell + CLI + Skill', '数据分析 + AI'],
+            ['交付物', 'Shortcut + 结构体', 'SKILL.md + Reference', 'Workflow 脚本', '科研 Skill + 报告'],
+            ['AI 参与', '无', '核心（AI 分析）', '调度 + 分析', '深度（知识挖掘）'],
+            ['典型场景', 'Wiki/Webhook/批量', '代码审查/Issue 分类', '项目初始化/协同发版', '热点追踪/合规检查'],
+        ]
+    )
+
+    # ==================== 组件依赖关系 ====================
+    doc.add_heading('组件依赖关系', level=1)
+    dep_tree = """gitlink-cli (CLI 核心)
+├── Shortcuts (赛题一)
+│   ├── wiki +list/+view/+create/+update/+delete
+│   ├── webhook +list/+create/+update/+delete/+test
+│   ├── board +view/+columns/+issues/+move/+assign
+│   ├── issue +batch-close/+batch-create/+batch-assign
+│   ├── repo +batch-create/+batch-update
+│   └── branch +protect/+unprotect
+│
+├── Skills (赛题二)
+│   ├── gitlink-code-review (代码审查)
+│   ├── gitlink-issue-triage (Issue 分类)
+│   ├── gitlink-changelog (Release Notes)
+│   ├── gitlink-health (项目健康度)
+│   ├── gitlink-compliance (合规检查)
+│   ├── gitlink-onboard (新人引导)
+│   └── gitlink-stale (过期管理)
+│
+├── Workflows (赛题三)
+│   ├── 01-community-ops.sh (社区运营)
+│   ├── 02-code-quality-gatekeeper.sh (质量门禁)
+│   ├── 03-project-init.sh (项目初始化)
+│   ├── 04-multi-repo-collab.sh (多仓库协同)
+│   └── 05-contributor-growth.sh (贡献者成长)
+│
+└── Research Skills (赛题四)
+    ├── gitlink-research (科研总入口)
+    ├── gitlink-code-insight (项目洞悉)
+    ├── gitlink-compliance (合规检查)
+    └── research workflows (热点/进度/引用)"""
+    p = doc.add_paragraph()
+    run = p.add_run(dep_tree)
+    run.font.name = 'Consolas'
+
+    # ==================== 状态转换说明 ====================
+    doc.add_heading('状态转换说明', level=1)
+
+    doc.add_heading('Shortcut 命令执行状态', level=2)
+    doc.add_paragraph('Init → Parsing → Validation → Resolving → Loading → Executing → APICall → Done/Error')
+    doc.add_paragraph('任何阶段出现错误都会进入 Error 状态，输出结构化错误信息后终止。')
+
+    doc.add_heading('Skill 触发状态', level=2)
+    doc.add_paragraph('Idle → Triggered → Loaded → AuthCheck → DataCollection → AIAnalysis → Execution → Output')
+    doc.add_paragraph('Skill 加载失败时回退到 Idle 状态，AI 分析失败时输出错误提示。')
+
+    doc.add_heading('Workflow 执行状态', level=2)
+    doc.add_paragraph('Idle → Selecting → Loading → AuthCheck → Step1 → Step2 → ... → StepN → Done')
+    doc.add_paragraph('任一步骤失败时根据配置决定继续或终止，最终输出执行汇总。')
+
+    # 保存
+    output_path = r'C:\Users\Lenovo\Desktop\soft运维\gitlink-cli\doc\系统动态模型章节.docx'
+    doc.save(output_path)
+    print(f'Word 文档已生成：{output_path}')
+
+if __name__ == '__main__':
+    create_document()
--- a/doc/reading_notes/01_types.md
+++ b/doc/reading_notes/01_types.md
@ -0,0 +1,552 @@
+# shortcuts/common/types.go 阅读笔记（面向 Go 小白）
+
+***
+
+## 第 1 行：`package common`
+
+**字面意思**：声明这个文件属于 `common` 包
+
+**运行时作用**：这是一个通用工具包，里面定义的类型和函数可以被所有其他 shortcut 模块（wiki、webhook、issue 等）复用。
+
+**小白补充**：
+
+- 包名 `common` 表示"公共的"，说明这里的内容是大家都需要用的
+- 其他文件通过 `import "github.com/gitlink-org/gitlink-cli/shortcuts/common"` 来使用
+
+***
+
+## 第 3-18 行：import 导入依赖
+
+```go
+import (
+    "bufio"                  // 缓冲输入（用于读取用户确认）
+    "encoding/json"          // JSON 处理
+    "fmt"                    // 格式化输出
+    "net/http"               // HTTP 客户端
+    "net/url"                // URL 处理
+    "os"                     // 操作系统交互
+    "strings"                // 字符串操作
+
+    "github.com/gitlink-org/gitlink-cli/cmd/cmdutil"      // 命令行工具（全局变量）
+    "github.com/gitlink-org/gitlink-cli/internal/client"  // HTTP 客户端
+    "github.com/gitlink-org/gitlink-cli/internal/config"  // 配置管理
+    "github.com/gitlink-org/gitlink-cli/internal/context" // 上下文解析（owner/repo）
+    clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"  // 错误定义
+    "github.com/gitlink-org/gitlink-cli/internal/output"  // 输出格式化
+)
+```
+
+**小白补充**：
+
+| 包名                 | 用途                                                          |
+| ------------------ | ----------------------------------------------------------- |
+| `bufio`            | 读取用户输入（比如确认操作时的 y/N）                                        |
+| `cmd/cmdutil`      | 存放全局变量（如 `cmdutil.Owner`, `cmdutil.Repo`, `cmdutil.Format`） |
+| `internal/config`  | 加载配置文件                                                      |
+| `internal/context` | 从 git remote 解析 owner/repo                                  |
+
+***
+
+## 第 20-28 行：`Shortcut` 结构体（核心！）
+
+```go
+type Shortcut struct {
+    Name        string
+    Description string
+    Flags       []Flag
+    DryRun      bool
+    DryRunHint  func(ctx *RuntimeContext) (string, error)
+    Run         func(ctx *RuntimeContext) error
+}
+```
+
+**字面意思**：定义一个名为 `Shortcut` 的结构体类型
+
+**运行时作用**：这是整个 CLI 命令系统的**核心数据结构**，每个 `Shortcut` 代表一个可执行的命令（如 `wiki +list`, `issue +create`）。
+
+**小白补充**：
+
+### ① 结构体是什么？
+
+结构体（struct）是 Go 语言中用来**组织相关数据和函数**的方式。可以把它想象成一个"数据容器"，里面装着各种属性。
+
+### ② 每个字段的含义：
+
+| 字段            | 类型                                          | 含义                         |
+| ------------- | ------------------------------------------- | -------------------------- |
+| `Name`        | `string`                                    | 命令名，用户通过 `+name` 调用        |
+| `Description` | `string`                                    | 命令描述，`--help` 时显示          |
+| `Flags`       | `[]Flag`                                    | 命令行参数列表（如 `--title`, `-t`） |
+| `DryRun`      | `bool`                                      | 是否支持预览模式（`--dry-run`）      |
+| `DryRunHint`  | `func(ctx *RuntimeContext) (string, error)` | 预览时显示的提示信息                 |
+| `Run`         | `func(ctx *RuntimeContext) error`           | **真正执行的函数**，命令的核心逻辑        |
+
+### ③ 函数类型字段：
+
+注意 `DryRunHint` 和 `Run` 的类型是**函数**！这在 Go 中是完全合法的，函数可以作为结构体的字段。
+
+```go
+Run func(ctx *RuntimeContext) error
+```
+
+- 这表示 `Run` 字段存储了一个**函数**
+- 这个函数接收 `*RuntimeContext` 类型的参数
+- 返回 `error` 类型的值（如果执行失败）
+
+***
+
+## 第 30-38 行：`Flag` 结构体
+
+```go
+type Flag struct {
+    Name     string
+    Short    string
+    Usage    string
+    Required bool
+    Default  string
+    Bool     bool
+}
+```
+
+**字面意思**：定义命令行参数的结构
+
+**运行时作用**：描述一个命令行参数，比如 `--title "Home"` 或 `-t "Home"`。
+
+**小白补充**：
+
+| 字段         | 含义     | 例子                        |
+| ---------- | ------ | ------------------------- |
+| `Name`     | 参数名    | `"title"` → `--title`     |
+| `Short`    | 短参数名   | `"t"` → `-t`              |
+| `Usage`    | 帮助说明   | `"Page title"`            |
+| `Required` | 是否必填   | `true` → 用户必须提供           |
+| `Default`  | 默认值    | `"1"` → 不提供时使用的默认值        |
+| `Bool`     | 是否布尔类型 | `true` → `--dry-run` 不需要值 |
+
+***
+
+## 第 40-50 行：`RuntimeContext` 结构体（核心！）
+
+```go
+type RuntimeContext struct {
+    Client            *client.Client
+    Owner             string
+    Repo              string
+    Format            string
+    CommandName       string
+    Args              map[string]string
+    GatewayBaseURL    string
+    GatewayHTTPClient *http.Client
+}
+```
+
+**字面意思**：定义运行时上下文的结构
+
+**运行时作用**：这是每个命令执行时的**全局环境**，包含了所有需要的信息。
+
+**小白补充**：
+
+### ① 为什么需要 RuntimeContext？
+
+每个命令执行时都需要很多信息：
+
+- 用哪个 HTTP 客户端发请求？
+- 当前操作的仓库是哪个（owner/repo）？
+- 输出格式是 JSON 还是 Table？
+- 用户传入了哪些参数？
+
+`RuntimeContext` 把这些信息打包在一起，方便传递和使用。
+
+### ② 每个字段的含义：
+
+| 字段                  | 类型                  | 含义                          |
+| ------------------- | ------------------- | --------------------------- |
+| `Client`            | `*client.Client`    | HTTP 客户端，用来调用 GitLink API   |
+| `Owner`             | `string`            | 仓库所有者（如 `zzx-coder`）        |
+| `Repo`              | `string`            | 仓库名称（如 `gitlink-cli`）       |
+| `Format`            | `string`            | 输出格式（`json`/`table`/`yaml`） |
+| `CommandName`       | `string`            | 当前命令名（如 `"wiki +list"`）     |
+| `Args`              | `map[string]string` | 用户传入的所有参数（key-value）        |
+| `GatewayBaseURL`    | `string`            | Wiki Gateway API 的地址        |
+| `GatewayHTTPClient` | `*http.Client`      | 可选的自定义 HTTP 客户端（主要用于测试）     |
+
+### ③ `*client.Client` 是什么？
+
+- `*` 表示这是一个**指针**类型
+- `client.Client` 是 `internal/client` 包中定义的结构体
+- 指针的好处：避免拷贝大对象，多个地方共享同一个实例
+
+***
+
+## 第 52-80 行：`NewRuntimeContext` 函数
+
+```go
+func NewRuntimeContext(args map[string]string, commandName string) (*RuntimeContext, error) {
+    // 1. 创建 HTTP 客户端
+    cli, err := client.New()
+    if err != nil {
+        return nil, err
+    }
+    cli.Debug = cmdutil.Debug  // 设置调试模式
+    
+    // 2. 确定输出格式
+    format := cmdutil.Format
+    if format == "" {
+        format = "json"  // 默认 JSON 格式
+    }
+    
+    // 3. 获取 Gateway URL
+    gatewayBaseURL := config.DefaultGatewayBaseURL
+    if cfg, err := config.Load(); err == nil && cfg.GatewayBaseURL != "" {
+        gatewayBaseURL = cfg.GatewayBaseURL  // 使用配置文件中的地址
+    }
+    
+    // 4. 创建并返回 RuntimeContext
+    return &RuntimeContext{
+        Client:            cli,
+        Owner:             cmdutil.Owner,
+        Repo:              cmdutil.Repo,
+        Format:            format,
+        CommandName:       commandName,
+        Args:              args,
+        GatewayBaseURL:    gatewayBaseURL,
+        GatewayHTTPClient: nil,
+    }, nil
+}
+```
+
+**字面意思**：创建一个新的 RuntimeContext 实例
+
+**运行时作用**：这是 `RuntimeContext` 的**构造函数**，负责初始化所有字段。
+
+**小白补充**：
+
+### ① 构造函数模式：
+
+Go 没有专门的构造函数语法，通常约定用 `NewXXX()` 函数来创建结构体实例。
+
+### ② `cmdutil` 是什么？
+
+`cmdutil` 是 `cmd/cmdutil/globals.go` 中定义的全局变量模块：
+
+```go
+// cmd/cmdutil/globals.go 中定义
+var (
+    Owner  string  // 通过 --owner 参数设置
+    Repo   string  // 通过 --repo 参数设置
+    Format string  // 通过 --format 参数设置
+    Debug  bool    // 通过 --debug 参数设置
+)
+```
+
+这些是**全局变量**，在命令行参数解析时被赋值，然后在这里被读取。
+
+### ③ 配置加载：
+
+```go
+gatewayBaseURL := config.DefaultGatewayBaseURL
+if cfg, err := config.Load(); err == nil && cfg.GatewayBaseURL != "" {
+    gatewayBaseURL = cfg.GatewayBaseURL
+}
+```
+
+- 先使用默认值 `config.DefaultGatewayBaseURL`
+- 尝试加载配置文件，如果配置文件中有自定义的 Gateway URL，就使用配置文件中的值
+
+***
+
+## 第 82-91 行：`ResolveOwnerRepo` 方法
+
+```go
+func (ctx *RuntimeContext) ResolveOwnerRepo() error {
+    owner, repo, err := context.ResolveOwnerRepo(ctx.Owner, ctx.Repo)
+    if err != nil {
+        return err
+    }
+    ctx.Owner = owner
+    ctx.Repo = repo
+    return nil
+}
+```
+
+**字面意思**：解析 owner 和 repo
+
+**运行时作用**：这是 `RuntimeContext` 的**方法**，用来确定当前操作的仓库。
+
+**小白补充**：
+
+### ① 方法是什么？
+
+方法是和结构体绑定的函数。在 Go 中：
+
+```go
+func (ctx *RuntimeContext) ResolveOwnerRepo() error {
+    // ...
+}
+```
+
+- `(ctx *RuntimeContext)` 表示这个函数绑定到 `RuntimeContext` 类型
+- `ctx` 是方法内部的**接收器**（receiver），类似其他语言的 `this` 或 `self`
+- 调用方式：`ctx.ResolveOwnerRepo()`
+
+### ② 解析逻辑：
+
+`context.ResolveOwnerRepo(ctx.Owner, ctx.Repo)` 的作用：
+
+1. 如果用户通过 `--owner` 和 `--repo` 参数明确指定了，直接使用
+2. 如果没有指定，尝试从当前目录的 `git remote` 中自动解析
+
+***
+
+## 第 93-96 行：`CallAPI` 方法
+
+```go
+func (ctx *RuntimeContext) CallAPI(method, path string, body interface{}) (*output.Envelope, error) {
+    return ctx.Client.Do(method, path, body, nil)
+}
+```
+
+**字面意思**：调用 API（无查询参数）
+
+**运行时作用**：封装 HTTP 请求，是所有 API 调用的入口。
+
+**小白补充**：
+
+- 这是一个**包装方法**，把 `ctx.Client.Do()` 包装一层
+- 其他模块只需要调用 `ctx.CallAPI()` 就能发送请求，不需要关心底层的 `client.Client`
+
+***
+
+## 第 98-101 行：`CallAPIWithQuery` 方法
+
+```go
+func (ctx *RuntimeContext) CallAPIWithQuery(method, path string, query url.Values) (*output.Envelope, error) {
+    return ctx.Client.Do(method, path, nil, query)
+}
+```
+
+**字面意思**：调用 API（带查询参数）
+
+**运行时作用**：和 `CallAPI` 类似，但支持 URL 查询参数（`?key=value`）。
+
+***
+
+## 第 103-106 行：`PaginateAll` 方法
+
+```go
+func (ctx *RuntimeContext) PaginateAll(path string, params url.Values) ([]json.RawMessage, error) {
+    return ctx.Client.PaginateAll(path, params)
+}
+```
+
+**字面意思**：获取所有分页数据
+
+**运行时作用**：处理分页 API，自动获取所有页的数据。
+
+**小白补充**：
+
+- GitLink API 常用分页返回大量数据（如 `page=1&limit=20`）
+- `PaginateAll` 会自动遍历所有页，把结果合并成一个大列表
+
+***
+
+## 第 108-111 行：`Output` 方法
+
+```go
+func (ctx *RuntimeContext) Output(env *output.Envelope) error {
+    return output.Print(env, ctx.Format)
+}
+```
+
+**字面意思**：输出结果
+
+**运行时作用**：根据用户指定的格式（JSON/Table/YAML）输出 API 响应。
+
+***
+
+## 第 113-116 行：`OutputData` 方法
+
+```go
+func (ctx *RuntimeContext) OutputData(data interface{}) error {
+    return output.Print(output.SuccessEnvelope(data, nil), ctx.Format)
+}
+```
+
+**字面意思**：输出数据（自动包装成 Envelope）
+
+**运行时作用**：如果只有数据，没有完整的 Envelope，可以用这个方法自动包装。
+
+**小白补充**：
+
+- `output.SuccessEnvelope(data, nil)` 创建一个成功的包装结构：`{"ok": true, "data": ...}`
+
+***
+
+## 第 118-121 行：`RepoPath` 方法
+
+```go
+func (ctx *RuntimeContext) RepoPath() string {
+    return fmt.Sprintf("/%s/%s", ctx.Owner, ctx.Repo)
+}
+```
+
+**字面意思**：返回仓库的 API 路径前缀
+
+**运行时作用**：生成 `/owner/repo` 格式的路径，避免重复拼接。
+
+***
+
+## 第 123-129 行：`Arg` 方法
+
+```go
+func (ctx *RuntimeContext) Arg(name string) string {
+    if v, ok := ctx.Args[name]; ok {
+        return v
+    }
+    return ""
+}
+```
+
+**字面意思**：获取命令行参数值
+
+**运行时作用**：从 `ctx.Args` map 中获取指定参数的值。
+
+**小白补充**：
+
+- `ctx.Args` 是 `map[string]string` 类型
+- 调用方式：`ctx.Arg("title")` → 获取 `--title` 参数的值
+
+***
+
+## 第 131-145 行：`RequireArg` 方法（核心！）
+
+```go
+func (ctx *RuntimeContext) RequireArg(name, example string) (string, error) {
+    v := ctx.Arg(name)
+    if v == "" {
+        suggestion := fmt.Sprintf("请提供 --%s 参数", name)
+        if example != "" {
+            suggestion += fmt.Sprintf("，例如：%s", example)
+        }
+        return "", clierrors.InputError(
+            fmt.Sprintf("required flag --%s is missing", name),
+            suggestion,
+        ).WithCommand(ctx.CommandName)
+    }
+    return v, nil
+}
+```
+
+**字面意思**：获取必填参数，如果缺失则返回错误
+
+**运行时作用**：强制检查必填参数，确保用户提供了必要的输入。
+
+**小白补充**：
+
+### ① 使用场景：
+
+```go
+title, err := ctx.RequireArg("title", `--title "Home Page"`)
+if err != nil {
+    return err  // 用户没提供 --title，直接返回错误
+}
+```
+
+### ② 错误处理：
+
+如果用户没提供参数，会返回一个 `CLIError`，包含：
+
+- `Kind`: `KindInput`（输入错误）
+- `Message`: `"required flag --title is missing"`
+- `Suggestion`: `"请提供 --title 参数，例如：--title \"Home Page\""`
+
+***
+
+## 第 147-150 行：`IsDryRun` 方法
+
+```go
+func (ctx *RuntimeContext) IsDryRun() bool {
+    return ctx.Arg("dry-run") == "true"
+}
+```
+
+**字面意思**：检查是否是预览模式
+
+**运行时作用**：判断用户是否传入了 `--dry-run` 参数。
+
+***
+
+## 第 152-166 行：`ConfirmAction` 函数
+
+```go
+func ConfirmAction(ctx *RuntimeContext) (bool, error) {
+    if !ctx.IsDryRun() {
+        return true, nil  // 不是预览模式，直接执行
+    }
+    
+    // 预览模式，提示用户确认
+    fmt.Fprint(os.Stderr, "\nProceed? [y/N] ")
+    reader := bufio.NewReader(os.Stdin)
+    answer, _ := reader.ReadString('\n')
+    answer = strings.TrimSpace(strings.ToLower(answer))
+    
+    if answer == "y" || answer == "yes" {
+        return true, nil  // 用户确认，继续执行
+    }
+    
+    fmt.Fprintln(os.Stderr, "Aborted.")
+    return false, nil  // 用户取消，不执行
+}
+```
+
+**字面意思**：确认操作（预览模式下）
+
+**运行时作用**：在 `--dry-run` 模式下，提示用户确认是否真的要执行操作。
+
+**小白补充**：
+
+### ① `fmt.Fprint(os.Stderr, ...)`：
+
+- `os.Stderr` 是标准错误输出流
+- 把提示信息输出到 stderr 而不是 stdout，这样 stdout 可以保持干净（用于管道输出）
+
+### ② `bufio.NewReader(os.Stdin)`：
+
+- `os.Stdin` 是标准输入流（用户键盘输入）
+- `bufio.NewReader` 创建一个缓冲读取器，用来读取用户输入
+
+***
+
+## 调用关系图
+
+```
+NewRuntimeContext(args, commandName)
+    ↓ 创建
+RuntimeContext{
+    Client: client.New(),           // HTTP 客户端
+    Owner: cmdutil.Owner,           // 全局变量
+    Repo: cmdutil.Repo,            // 全局变量
+    Format: cmdutil.Format,        // 全局变量
+    Args: args,                    // 命令行参数
+}
+
+RuntimeContext 的方法：
+├── ResolveOwnerRepo()     → 解析 owner/repo（自动或手动）
+├── CallAPI()              → 调用 API（无参数）
+├── CallAPIWithQuery()     → 调用 API（带参数）
+├── PaginateAll()          → 获取所有分页数据
+├── Output()               → 输出结果
+├── OutputData()           → 输出数据（自动包装）
+├── RepoPath()             → 返回 /owner/repo 路径
+├── Arg()                  → 获取参数值
+├── RequireArg()           → 获取必填参数（缺则报错）
+└── IsDryRun()             → 检查预览模式
+
+Shortcut 结构体：
+├── Name: "list"
+├── Flags: [{Name:"title", Short:"t", Required:true}]
+└── Run: func(ctx *RuntimeContext) error {
+        // 命令执行逻辑
+    }
+```
+
--- a/doc/reading_notes/02_client.md
+++ b/doc/reading_notes/02_client.md
@ -0,0 +1,560 @@
+# internal/client/client.go 阅读笔记（面向 Go 小白）
+
+---
+
+## 第 1 行：`package client`
+
+**字面意思**：声明这个文件属于 `client` 包
+
+**运行时作用**：这是项目的 HTTP 客户端模块，负责所有与 GitLink API 的通信。
+
+---
+
+## 第 3-16 行：import 导入依赖
+
+```go
+import (
+    "bytes"               // 字节缓冲（用于构造请求体）
+    "encoding/json"       // JSON 序列化/反序列化
+    "fmt"                 // 格式化输出
+    "io"                  // 输入输出接口
+    "net/http"            // HTTP 协议
+    "net/url"             // URL 处理
+    "strings"             // 字符串操作
+
+    "github.com/gitlink-org/gitlink-cli/internal/auth"       // 认证模块（带 Token 的 HTTP 客户端）
+    "github.com/gitlink-org/gitlink-cli/internal/config"    // 配置管理
+    clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"  // 错误定义
+    "github.com/gitlink-org/gitlink-cli/internal/output"    // 输出格式化
+)
+```
+
+**小白补充**：
+
+| 包名 | 用途 | 在本文件中的作用 |
+|------|------|-----------------|
+| `bytes` | 字节操作 | 把 JSON 数据转成 HTTP 请求体 |
+| `io` | 输入输出 | 读取 HTTP 响应体 |
+| `net/http` | HTTP 协议 | 创建和发送 HTTP 请求 |
+
+---
+
+## 第 18-23 行：`Client` 结构体（核心！）
+
+```go
+type Client struct {
+    HTTP           *http.Client
+    BaseURL        string
+    Debug          bool
+    SkipJSONSuffix bool
+}
+```
+
+**字面意思**：定义 HTTP 客户端的结构
+
+**运行时作用**：这是项目封装的 HTTP 客户端，所有 API 调用都通过它来完成。
+
+**小白补充**：
+
+### ① 每个字段的含义：
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `HTTP` | `*http.Client` | Go 标准库的 HTTP 客户端（核心） |
+| `BaseURL` | `string` | API 基础地址（如 `https://www.gitlink.org.cn/api`） |
+| `Debug` | `bool` | 是否开启调试模式（打印请求/响应） |
+| `SkipJSONSuffix` | `bool` | 是否跳过自动添加 `.json` 后缀（Wiki Gateway 需要） |
+
+### ② `*http.Client` 是什么？
+
+`http.Client` 是 Go 标准库提供的 HTTP 客户端，它包含：
+- 连接池管理
+- 超时设置
+- Cookie 管理
+- 传输层配置（如 TLS、代理）
+
+我们项目在 `internal/auth/transport.go` 中对它进行了扩展，自动添加认证 Token。
+
+---
+
+## 第 25-35 行：`APIError` 结构体
+
+```go
+type APIError struct {
+    StatusCode int
+    Code       interface{}
+    Message    string
+    Kind       clierrors.ErrorKind
+    Suggestion string
+}
+
+func (e *APIError) Error() string {
+    return fmt.Sprintf("[%v] %s", e.Code, e.Message)
+}
+```
+
+**字面意思**：定义 API 错误的结构
+
+**运行时作用**：封装 API 返回的错误信息，包含错误码、消息和解决建议。
+
+**小白补充**：
+
+### ① `Error()` 方法：
+
+```go
+func (e *APIError) Error() string {
+    return fmt.Sprintf("[%v] %s", e.Code, e.Message)
+}
+```
+
+- 这是实现了 Go 的 `error` 接口
+- 任何实现了 `Error() string` 方法的类型都可以作为 `error` 返回
+- 这样 `APIError` 就可以像普通错误一样使用：`return apiErr`
+
+### ② 为什么需要自定义错误类型？
+
+普通的 `error` 只能包含一条消息，而我们需要：
+- `StatusCode`：HTTP 状态码（404/403/500 等）
+- `Code`：API 返回的业务错误码
+- `Kind`：错误分类（认证错误/输入错误/服务器错误等）
+- `Suggestion`：给用户的解决建议
+
+---
+
+## 第 37-46 行：`New` 函数（构造函数）
+
+```go
+func New() (*Client, error) {
+    // 1. 加载配置
+    cfg, err := config.Load()
+    if err != nil {
+        return nil, err
+    }
+    
+    // 2. 创建并返回 Client
+    return &Client{
+        HTTP:    auth.NewHTTPClient(),  // 带认证的 HTTP 客户端
+        BaseURL: cfg.BaseURL,           // 从配置获取 API 地址
+    }, nil
+}
+```
+
+**字面意思**：创建一个新的 Client 实例
+
+**运行时作用**：这是 Client 的构造函数，自动加载配置并创建带认证的 HTTP 客户端。
+
+**小白补充**：
+
+### ① `auth.NewHTTPClient()` 做了什么？
+
+这个函数在 `internal/auth/transport.go` 中，它创建了一个 HTTP 客户端，并且：
+- 自动从配置文件读取 Token
+- 在每个请求的 `Authorization` 头中添加 `Bearer {token}`
+- 处理 Token 过期等情况
+
+### ② 配置文件的内容：
+
+配置文件位于 `~/.config/gitlink-cli/config.yaml`，内容大致如下：
+
+```yaml
+base_url: https://www.gitlink.org.cn/api
+gateway_base_url: https://gateway.gitlink.org.cn/api
+token: your-token-here
+```
+
+---
+
+## 第 48-168 行：`Do` 方法（核心！）
+
+这是整个文件中**最重要的函数**，负责发送 HTTP 请求并解析响应。
+
+### ① 路径处理（第 48-67 行）
+
+```go
+func (c *Client) Do(method, path string, body interface{}, query url.Values) (*output.Envelope, error) {
+    // 自动添加 .json 后缀（GitLink API 约定）
+    if c.shouldAppendJSONSuffix(path) {
+        if idx := strings.Index(path, "?"); idx != -1 {
+            // 路径已经包含查询参数，在 ? 前面加 .json
+            basePath := path[:idx]
+            queryStr := path[idx:]
+            path = basePath + ".json" + queryStr
+        } else {
+            // 路径没有查询参数，直接加 .json
+            path += ".json"
+        }
+    }
+    
+    // 构建完整 URL
+    fullURL := c.BaseURL + path
+    if query != nil && len(query) > 0 {
+        sep := "?"
+        if strings.Contains(fullURL, "?") {
+            sep = "&"  // URL 已经有 ?，用 & 连接
+        }
+        fullURL += sep + query.Encode()
+    }
+    // ...
+}
+```
+
+**字面意思**：处理请求路径，构建完整 URL
+
+**运行时作用**：GitLink API 约定所有路径都需要 `.json` 后缀，这里自动添加。
+
+**小白补充**：
+
+- `c.BaseURL` 是 `https://www.gitlink.org.cn/api`
+- `path` 是 `/users/me`
+- 最终 `fullURL` 变成 `https://www.gitlink.org.cn/api/users/me.json`
+
+### ② 请求体处理（第 69-77 行）
+
+```go
+// 处理请求体
+var bodyReader io.Reader
+if body != nil {
+    // 把 body 序列化成 JSON
+    data, err := json.Marshal(body)
+    if err != nil {
+        return nil, err
+    }
+    // 转成 io.Reader（HTTP 请求需要的格式）
+    bodyReader = bytes.NewReader(data)
+}
+```
+
+**字面意思**：把请求体转成 HTTP 可以发送的格式
+
+**运行时作用**：如果有请求体（如 POST/PUT 请求），把 Go 的 map 转成 JSON 字符串，再转成字节流。
+
+**小白补充**：
+
+- `json.Marshal(body)`：把 Go 结构体/map 转成 JSON 字节数组
+- `bytes.NewReader(data)`：把字节数组包装成 `io.Reader`（HTTP 请求体需要这个接口）
+
+### ③ 创建 HTTP 请求（第 79-87 行）
+
+```go
+// 创建 HTTP 请求
+req, err := http.NewRequest(method, fullURL, bodyReader)
+if err != nil {
+    return nil, err
+}
+
+// 调试模式：打印请求信息
+if c.Debug {
+    fmt.Printf("→ %s %s\n", method, fullURL)
+}
+```
+
+**字面意思**：创建一个 HTTP 请求对象
+
+**运行时作用**：`http.NewRequest` 创建请求对象，包含方法、URL 和请求体。
+
+### ④ 发送请求（第 89-92 行）
+
+```go
+// 发送请求
+resp, err := c.HTTP.Do(req)
+if err != nil {
+    return nil, fmt.Errorf("request failed: %w", err)
+}
+defer resp.Body.Close()  // 确保响应体被关闭
+```
+
+**字面意思**：发送 HTTP 请求并获取响应
+
+**运行时作用**：`c.HTTP.Do(req)` 发送请求，返回响应对象。
+
+**小白补充**：
+
+- `defer resp.Body.Close()`：**非常重要！** 确保响应体被关闭，避免资源泄漏
+- `defer` 是 Go 的关键字，它会在函数返回前执行后面的语句
+- 如果不关闭 `resp.Body`，HTTP 连接池会被占满，导致后续请求失败
+
+### ⑤ 读取响应体（第 94-101 行）
+
+```go
+// 读取响应体
+respData, err := io.ReadAll(resp.Body)
+if err != nil {
+    return nil, fmt.Errorf("failed to read response: %w", err)
+}
+
+// 调试模式：打印响应信息
+if c.Debug {
+    fmt.Printf("← %d %s\n", resp.StatusCode, string(respData[:min(len(respData), 200)]))
+}
+```
+
+**字面意思**：把响应体读取成字节数组
+
+**运行时作用**：`io.ReadAll(resp.Body)` 读取整个响应体内容。
+
+**小白补充**：
+- `resp.StatusCode` 是 HTTP 状态码（200=成功，404=未找到，500=服务器错误）
+
+### ⑥ HTTP 状态码检查（第 103-113 行）
+
+```go
+// 检查 HTTP 状态码
+if resp.StatusCode >= 400 {
+    info := lookupStatusInfo(resp.StatusCode)
+    return nil, &APIError{
+        StatusCode: resp.StatusCode,
+        Code:       resp.StatusCode,
+        Message:    fmt.Sprintf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(respData))),
+        Kind:       info.kind,
+        Suggestion: info.suggestion,
+    }
+}
+```
+
+**字面意思**：如果状态码 >= 400，返回错误
+
+**运行时作用**：HTTP 4xx/5xx 都是错误，这里封装成 `APIError` 返回。
+
+**小白补充**：
+- `lookupStatusInfo(resp.StatusCode)` 根据状态码查找对应的错误分类和建议
+
+### ⑦ JSON 解析（第 115-120 行）
+
+```go
+// 解析 JSON 响应
+var raw map[string]interface{}
+if err := json.Unmarshal(respData, &raw); err != nil {
+    // 不是 JSON，直接返回原始内容
+    return output.SuccessEnvelope(string(respData), nil), nil
+}
+```
+
+**字面意思**：把响应体解析成 Go 的 map
+
+**运行时作用**：`json.Unmarshal` 把 JSON 字符串转成 Go 的 `map[string]interface{}`。
+
+**小白补充**：
+
+- `json.Unmarshal` 的第二个参数需要传递**指针**（`&raw`）
+- `interface{}` 是 Go 的"万能类型"，可以存储任何值
+- 如果响应不是 JSON（比如返回的是 HTML 错误页面），就直接返回字符串
+
+### ⑧ GitLink 业务错误检查（第 122-142 行）
+
+```go
+// 检查 GitLink 业务错误（响应体中的 status 字段）
+if status, ok := raw["status"]; ok {
+    var statusCode float64
+    switch v := status.(type) {
+    case float64:
+        statusCode = v
+    case int:
+        statusCode = float64(v)
+    }
+    
+    // status 不为 0、1、200 都是错误
+    if statusCode != 0 && statusCode != 200 && statusCode != 1 {
+        msg, _ := raw["message"].(string)
+        info := lookupStatusInfo(int(statusCode))
+        return output.ErrorEnvelope(int(statusCode), msg, info.suggestion), &APIError{
+            StatusCode: int(statusCode),
+            Code:       int(statusCode),
+            Message:    msg,
+            Kind:       info.kind,
+            Suggestion: info.suggestion,
+        }
+    }
+}
+```
+
+**字面意思**：检查 GitLink API 返回的业务错误码
+
+**运行时作用**：GitLink API 有时 HTTP 状态码是 200，但响应体中的 `status` 字段表示业务失败（如参数校验失败）。
+
+**小白补充**：
+
+GitLink API 的响应格式：
+```json
+{
+    "status": 0,      // 0=失败, 1=成功, 200=成功
+    "message": "...", // 错误信息
+    "data": {...}     // 数据
+}
+```
+
+### ⑨ 自动解析 JSON 字符串数据（第 144-150 行）
+
+```go
+// 自动解析 JSON 字符串数据（GitLink API 的一个特性）
+if dataStr, ok := raw["data"].(string); ok {
+    var parsedData interface{}
+    if err := json.Unmarshal([]byte(dataStr), &parsedData); err == nil {
+        raw["data"] = json.RawMessage(dataStr)
+    }
+}
+```
+
+**字面意思**：处理 data 字段是 JSON 字符串的情况
+
+**运行时作用**：GitLink 某些 API 返回的 `data` 字段是字符串形式的 JSON，需要再次解析。
+
+**小白补充**：
+
+比如响应是这样的：
+```json
+{
+    "status": 1,
+    "data": "{\"name\": \"test\"}"  // data 是字符串！
+}
+```
+
+这里需要把 `"{\"name\": \"test\"}"` 再解析成 `{"name": "test"}`。
+
+### ⑩ 构建分页元数据（第 152-166 行）
+
+```go
+// 构建分页元数据
+var meta *output.Meta
+if tc, ok := raw["total_count"]; ok {
+    meta = &output.Meta{}
+    if v, ok := tc.(float64); ok {
+        meta.TotalCount = int(v)
+    }
+    if v, ok := raw["page"].(float64); ok {
+        meta.Page = int(v)
+    }
+    if v, ok := raw["limit"].(float64); ok {
+        meta.Limit = int(v)
+    }
+}
+
+// 返回成功的 Envelope
+return output.SuccessEnvelope(raw, meta), nil
+```
+
+**字面意思**：从响应中提取分页信息
+
+**运行时作用**：如果 API 返回了分页信息（total_count/page/limit），提取出来作为 `Meta`。
+
+---
+
+## 第 170-184 行：便捷方法
+
+```go
+func (c *Client) Get(path string, query url.Values) (*output.Envelope, error) {
+    return c.Do("GET", path, nil, query)
+}
+
+func (c *Client) Post(path string, body interface{}) (*output.Envelope, error) {
+    return c.Do("POST", path, body, nil)
+}
+
+func (c *Client) Put(path string, body interface{}) (*output.Envelope, error) {
+    return c.Do("PUT", path, body, nil)
+}
+
+func (c *Client) Delete(path string, query url.Values) (*output.Envelope, error) {
+    return c.Do("DELETE", path, nil, query)
+}
+```
+
+**字面意思**：封装常见的 HTTP 方法
+
+**运行时作用**：提供更简洁的调用方式，比如 `client.Get("/users/me", nil)` 而不是 `client.Do("GET", "/users/me", nil, nil)`。
+
+---
+
+## 第 186-225 行：错误信息映射
+
+```go
+type statusInfo struct {
+    kind       clierrors.ErrorKind
+    message    string
+    suggestion string
+}
+
+var statusMessages = map[int]statusInfo{
+    -2: {clierrors.KindAuth, "未登录或 Token 已过期",
+        "运行 gitlink-cli auth login 重新登录"},
+    -1: {clierrors.KindInput, "参数校验失败",
+        "检查必填参数是否缺失"},
+    401: {clierrors.KindAuth, "认证失败",
+        "运行 gitlink-cli auth login 登录"},
+    403: {clierrors.KindForbidden, "权限不足",
+        "请确认账号有此仓库的访问权限"},
+    404: {clierrors.KindNotFound, "资源不存在",
+        "检查 owner/repo/id 是否正确"},
+    // ... 更多状态码
+}
+
+func lookupStatusInfo(code int) statusInfo {
+    if info, ok := statusMessages[code]; ok {
+        return info
+    }
+    return statusInfo{
+        kind:    clierrors.KindUnknown,
+        message: fmt.Sprintf("API 返回错误码 %d", code),
+    }
+}
+```
+
+**字面意思**：根据错误码查找对应的错误信息
+
+**运行时作用**：把枯燥的错误码转换成人类可读的错误信息和解决建议。
+
+---
+
+## 第 227-246 行：`shouldAppendJSONSuffix` 方法
+
+```go
+func (c *Client) shouldAppendJSONSuffix(path string) bool {
+    // 1. 如果设置了 SkipJSONSuffix，不添加
+    if c.SkipJSONSuffix {
+        return false
+    }
+    // 2. 如果已经有 .json 后缀，不添加
+    if strings.HasSuffix(path, ".json") {
+        return false
+    }
+    // 3. 如果是 raw 内容路径，不添加
+    parts := strings.Split(strings.Trim(path, "/"), "/")
+    for i, part := range parts {
+        if part == "raw" && i >= 2 && i+2 < len(parts) {
+            return false
+        }
+    }
+    // 4. 其他情况，添加 .json 后缀
+    return true
+}
+```
+
+**字面意思**：判断是否应该添加 `.json` 后缀
+
+**运行时作用**：控制是否自动添加 `.json` 后缀。
+
+**小白补充**：
+
+为什么需要这个方法？
+- Wiki Gateway API 不需要 `.json` 后缀（设置 `SkipJSONSuffix: true`）
+- 某些路径（如 `/owner/repo/raw/...`）返回的是原始文件内容，不是 JSON
+
+---
+
+## 完整调用流程
+
+```
+ctx.CallAPI("GET", "/users/me", nil)
+    ↓
+Client.Do("GET", "/users/me", nil, nil)
+    ↓
+1. 路径处理：/users/me → /users/me.json
+2. 构建 URL：https://www.gitlink.org.cn/api/users/me.json
+3. 创建 HTTP 请求：http.NewRequest("GET", url, nil)
+4. 发送请求：c.HTTP.Do(req)
+   ↓ (auth.NewHTTPClient() 自动添加 Authorization 头)
+5. 读取响应体：io.ReadAll(resp.Body)
+6. 检查状态码：如果 >= 400，返回 APIError
+7. 解析 JSON：json.Unmarshal → map[string]interface{}
+8. 检查业务错误：判断 status 字段
+9. 返回 Envelope：output.SuccessEnvelope(raw, meta)
+```
--- a/doc/reading_notes/03_wiki.md
+++ b/doc/reading_notes/03_wiki.md
@ -0,0 +1,706 @@
+# shortcuts/wiki/wiki.go 阅读笔记（面向 Go 小白）
+
+---
+
+## 第 1 行：`package wiki`
+
+**字面意思**：声明这个文件属于 `wiki` 包
+
+**运行时作用**：Go 语言规定每个文件必须属于一个包。包名决定了其他文件如何引用这里的函数/变量。
+
+**小白补充**：
+- 包就像"工具箱"，`wiki` 包就是专门处理 Wiki 功能的工具箱
+- 同一个包下的文件可以直接互相调用函数，不需要导入
+- 包名一般和目录名一致（这里文件在 `shortcuts/wiki/` 目录下，所以包名是 `wiki`）
+
+---
+
+## 第 3-22 行：import 导入依赖
+
+```go
+import (
+    "encoding/base64"      // Base64 编解码
+    "encoding/json"        // JSON 序列化/反序列化
+    "errors"               // 错误处理
+    "fmt"                  // 格式化输出（类似 Python 的 print）
+    "net/http"             // HTTP 客户端
+    "net/url"              // URL 编码/解析
+    "os"                   // 操作系统交互（读文件等）
+    "regexp"               // 正则表达式
+    "strconv"              // 字符串转数字
+    "strings"              // 字符串操作
+    "sync"                 // 并发同步（锁、线程安全）
+    "time"                 // 时间处理
+
+    "github.com/gitlink-org/gitlink-cli/internal/auth"      // 认证模块
+    "github.com/gitlink-org/gitlink-cli/internal/client"    // HTTP 客户端封装
+    clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"  // CLI 错误定义
+    "github.com/gitlink-org/gitlink-cli/internal/output"    // 输出格式化
+    "github.com/gitlink-org/gitlink-cli/shortcuts/common"   // 通用工具
+)
+```
+
+**字面意思**：导入需要用到的外部库/包
+
+**运行时作用**：告诉 Go 编译器，我需要使用这些包提供的功能。编译时会把这些包的代码链接进来。
+
+**小白补充**：
+
+| 包名 | 一句话解释 | 在本文件中的用途 |
+|------|-----------|-----------------|
+| `encoding/base64` | 把文字转成 Base64 编码 | Wiki 内容需要用 Base64 编码后发送 |
+| `encoding/json` | 处理 JSON 数据 | 解析 API 返回的 JSON |
+| `errors` | Go 标准错误处理工具 | 判断错误类型 |
+| `fmt` | 格式化打印 | 输出错误信息、拼接字符串 |
+| `net/http` | HTTP 协议客户端 | 发送 HTTP 请求 |
+| `net/url` | URL 处理 | 构建查询参数、URL 编码 |
+| `os` | 操作系统接口 | 读取本地文件内容 |
+| `regexp` | 正则表达式 | 匹配 Markdown 链接和图片 |
+| `strconv` | 字符串转换 | 把字符串转成数字 |
+| `strings` | 字符串操作 | 切割、查找、替换字符串 |
+| `sync` | 并发同步 | 提供线程安全的缓存（`sync.Map`） |
+| `time` | 时间处理 | 设置 HTTP 请求超时 |
+| `internal/auth` | 项目内部认证模块 | 获取带 Token 的 HTTP 客户端 |
+| `internal/client` | 项目内部客户端模块 | 封装 API 调用逻辑 |
+| `internal/errors` | 项目内部错误定义 | 自定义错误类型 |
+| `internal/output` | 项目内部输出模块 | 格式化输出结果（JSON/Table） |
+| `shortcuts/common` | 通用工具模块 | 提供 RuntimeContext 等基础结构 |
+
+---
+
+## 第 24 行：`var projectIDCache sync.Map`
+
+**字面意思**：声明一个全局变量 `projectIDCache`，类型是 `sync.Map`
+
+**运行时作用**：这是一个**线程安全的缓存**，用来存储 `owner/repo -> projectID` 的映射关系，避免重复调用 API 获取项目 ID。
+
+**小白补充**：
+- `var` 是 Go 声明变量的关键字
+- `sync.Map` 是 Go 标准库提供的**并发安全的 map**（普通 map 在多线程下读写会崩溃）
+- `projectIDCache` 是全局变量（在函数外面声明），整个包内都可以访问
+- 为什么需要缓存？因为每次操作 Wiki 都需要 projectID，但获取 projectID 需要调用一次 API，缓存可以节省网络请求
+
+---
+
+## 第 26-28 行：`wikiPath` 函数
+
+```go
+func wikiPath(endpoint string) string {
+    return "/wiki/open/" + endpoint
+}
+```
+
+**字面意思**：定义一个函数 `wikiPath`，接收一个字符串参数 `endpoint`，返回一个字符串Wiki 功能调用的是 Gateway API （网关 API），所有 Wiki 相关的接口都有一个固定的前缀 /wiki/open/
+
+**运行时作用**：拼接 Wiki API 的路径前缀。比如传入 `"wikiPages"`，返回 `"/wiki/open/wikiPages"`。
+
+**小白补充**：
+- `func` 是 Go 定义函数的关键字
+- `wikiPath(endpoint string)`：函数名是 `wikiPath`，参数名是 `endpoint`，参数类型是 `string`
+- `string`（返回类型）：表示函数执行完返回一个字符串
+- 这是一个**工具函数**，用来避免重复写相同的路径前缀
+
+---
+
+## 第 30-49 行：`getGatewayClient` 函数
+
+```go
+func getGatewayClient(ctx *common.RuntimeContext) *client.Client {
+    baseURL := ctx.GatewayBaseURL
+    if baseURL == "" {
+        baseURL = "https://gateway.gitlink.org.cn/api"
+    }
+    httpClient := ctx.GatewayHTTPClient
+    if httpClient == nil {
+        httpClient = auth.NewHTTPClient()
+    }
+    return &client.Client{
+        HTTP:           httpClient,
+        BaseURL:        baseURL,
+        SkipJSONSuffix: true,
+        Debug:          ctx.Client.Debug,
+    }
+}
+```
+
+**字面意思**：定义一个函数 `getGatewayClient`，接收 `*common.RuntimeContext` 类型的指针参数 `ctx`，返回 `*client.Client` 类型的指针
+
+**运行时作用**：创建一个专门访问 **Wiki Gateway API** 的客户端实例。
+
+**小白补充**：
+
+### ① 为什么需要单独的 Gateway 客户端？
+
+GitLink 的 Wiki API 和主 API 不在同一个域名：
+- 主 API：`https://www.gitlink.org.cn/api`（用于获取项目信息等）
+- Wiki Gateway API：`https://gateway.gitlink.org.cn/api`（专门处理 Wiki 操作）
+
+### ② 代码逐句解析：
+
+```go
+baseURL := ctx.GatewayBaseURL  // 从上下文获取 Gateway 地址
+if baseURL == "" {             // 如果没配置，用默认地址
+    baseURL = "https://gateway.gitlink.org.cn/api"
+}
+```
+
+```go
+httpClient := ctx.GatewayHTTPClient  // 获取自定义的 HTTP 客户端
+if httpClient == nil {               // 如果没有自定义的，创建一个带认证的默认客户端
+    httpClient = auth.NewHTTPClient()
+}
+```
+
+```go
+return &client.Client{...}  // 创建并返回 Client 结构体实例
+```
+
+### ③ 结构体初始化语法：
+
+```go
+&client.Client{
+    HTTP:           httpClient,           // 使用上面创建的 HTTP 客户端
+    BaseURL:        baseURL,              // Gateway API 地址
+    SkipJSONSuffix: true,                 // 关键：Gateway API 不需要 .json 后缀
+    Debug:          ctx.Client.Debug,     // 继承调试模式
+}
+```
+
+- `&` 符号表示取地址，返回指针（Go 中结构体传参常用指针，避免拷贝）
+- `client.Client` 是一个**结构体类型**，里面定义了客户端的各种配置
+
+---
+
+## 第 51-58 行：`callWikiAPI` 函数
+
+```go
+func callWikiAPI(ctx *common.RuntimeContext, method, path string, body interface{}) (*output.Envelope, error) {
+    gc := getGatewayClient(ctx)
+    env, err := gc.Do(method, path, body, nil)
+    if err != nil {
+        return nil, err
+    }
+    return unwrapGatewayResponse(env)
+}
+```
+
+**字面意思**：定义函数 `callWikiAPI`，接收上下文、HTTP 方法、路径、请求体，返回 `(*output.Envelope, error)`
+
+**运行时作用**：封装对 Wiki Gateway API 的调用流程。
+
+**小白补充**：
+
+### ① 参数说明：
+- `ctx *common.RuntimeContext`：运行时上下文，包含认证信息、owner/repo 等
+- `method string`：HTTP 方法（GET/POST/PUT/DELETE）
+- `path string`：API 路径
+- `body interface{}`：请求体（可以是任何类型，Go 中 `interface{}` 表示万能类型）
+
+### ② 返回值说明：
+- `(*output.Envelope, error)`：Go 可以返回多个值！第一个是 API 返回的包装数据，第二个是错误
+
+### ③ 执行流程：
+1. `gc := getGatewayClient(ctx)` → 获取 Gateway 客户端
+2. `gc.Do(...)` → 调用客户端的 Do 方法发送 HTTP 请求
+3. `unwrapGatewayResponse(env)` → 解析并处理响应（后面会讲）
+
+---
+
+## 第 60-67 行：`callWikiAPIWithQuery` 函数
+
+```go
+func callWikiAPIWithQuery(ctx *common.RuntimeContext, method, path string, query url.Values) (*output.Envelope, error) {
+    gc := getGatewayClient(ctx)
+    env, err := gc.Do(method, path, nil, query)
+    if err != nil {
+        return nil, err
+    }
+    return unwrapGatewayResponse(env)
+}
+```
+
+**字面意思**：和 `callWikiAPI` 类似，但专门用于带查询参数的请求
+
+**运行时作用**：当需要发送带 `?key=value` 查询参数的 GET 请求时使用。
+
+**小白补充**：
+- `url.Values` 是 Go 标准库类型，本质是 `map[string][]string`，用来存储 URL 查询参数
+- 比如 `?owner=zzx&repo=test` 会被表示为 `{"owner": ["zzx"], "repo": ["test"]}`
+
+---
+
+## 第 69-99 行：`unwrapGatewayResponse` 函数（核心！）
+
+```go
+func unwrapGatewayResponse(env *output.Envelope) (*output.Envelope, error) {
+    // 1. 尝试把响应数据转成 map
+    resp, ok := env.Data.(map[string]interface{})
+    if !ok {
+        return env, nil  // 不是 map 格式，直接返回
+    }
+    
+    // 2. 检查响应中的 code 字段
+    if code, ok := resp["code"]; ok {
+        switch v := code.(type) {
+        case float64:
+            // HTTP 2xx 都算成功（包括 200/201/204 等）
+            if v < 200 || v >= 300 {
+                // 错误情况：提取错误信息
+                msg, _ := resp["msg"].(string)
+                kind := clierrors.KindServer
+                if int(v) == 404 {
+                    kind = clierrors.KindNotFound
+                } else if int(v) == 401 || int(v) == 403 {
+                    kind = clierrors.KindForbidden
+                }
+                // 返回自定义错误
+                return nil, clierrors.New(kind, msg,
+                    "检查 owner/repo 是否正确，或确认仓库已在 GitLink 网页端开启 Wiki 功能")
+            }
+        }
+    }
+    
+    // 3. 如果响应有 data 字段，提取出来作为新的响应数据
+    if innerData, ok := resp["data"]; ok {
+        return output.SuccessEnvelope(innerData, env.Meta), nil
+    }
+    
+    return env, nil
+}
+```
+
+**字面意思**："拆开" Gateway API 的响应，提取真正的数据
+
+**运行时作用**：处理 Gateway API 返回的特殊格式，统一成标准的 `Envelope` 结构。
+
+**小白补充**：
+
+### ① Gateway API 的响应格式：
+
+Gateway API 返回的 JSON 格式是这样的：
+```json
+{
+    "code": 200,
+    "msg": "success",
+    "data": { "真正的数据在这里" }
+}
+```
+
+而我们需要的是直接拿到 `data` 里面的内容。
+
+### ② 类型断言（Go 的特色语法）：
+
+```go
+resp, ok := env.Data.(map[string]interface{})
+```
+
+- 这是**类型断言**，把 `env.Data`（类型是 `interface{}`）转换成 `map[string]interface{}`
+- `ok` 是一个布尔值，表示转换是否成功
+- 如果转换失败（比如 `env.Data` 是个字符串而不是 map），`ok` 就是 `false`
+
+### ③ switch type 语法：
+
+```go
+switch v := code.(type) {
+case float64:
+    // code 是浮点数类型时执行这里
+}
+```
+
+- 这是 Go 的**类型 switch**，用来判断一个 `interface{}` 变量的具体类型
+- JSON 解析数字时，默认会转成 `float64` 类型
+
+### ④ 为什么要判断 2xx 状态码？
+
+```go
+if v < 200 || v >= 300 {
+    // 错误处理
+}
+```
+
+- HTTP 状态码中，200-299 表示成功
+- 之前的代码只判断了 200/201，导致 DELETE 返回 204（No Content）时被误判为失败
+- 现在扩展到所有 2xx 都算成功
+
+---
+
+## 第 101-135 行：`resolveProjectID` 函数（核心！）
+
+```go
+func resolveProjectID(ctx *common.RuntimeContext) (string, error) {
+    // 1. 生成缓存 key
+    key := ctx.Owner + "/" + ctx.Repo
+    
+    // 2. 先查缓存
+    if cached, ok := projectIDCache.Load(key); ok {
+        return cached.(string), nil  // 缓存命中，直接返回
+    }
+    
+    // 3. 缓存没命中，调用主 API 获取项目详情
+    path := fmt.Sprintf("/%s/%s/detail", ctx.Owner, ctx.Repo)
+    env, err := ctx.CallAPI("GET", path, nil)
+    if err != nil {
+        return "", fmt.Errorf("failed to fetch project details (needed for projectId): %w", err)
+    }
+    
+    // 4. 从响应中提取 project_id
+    data, ok := env.Data.(map[string]interface{})
+    if !ok {
+        return "", fmt.Errorf("unexpected response from project detail API")
+    }
+    
+    pid, ok := data["project_id"]
+    if !ok {
+        return "", fmt.Errorf("project_id not found in project detail response")
+    }
+    
+    // 5. 处理 project_id 的不同类型（可能是 float64 或 int）
+    var pidStr string
+    switch v := pid.(type) {
+    case float64:
+        pidStr = fmt.Sprintf("%.0f", v)
+    case int:
+        pidStr = fmt.Sprintf("%d", v)
+    default:
+        pidStr = fmt.Sprintf("%v", v)
+    }
+    
+    // 6. 存入缓存
+    projectIDCache.Store(key, pidStr)
+    return pidStr, nil
+}
+```
+
+**字面意思**：根据 owner/repo 解析出项目的数字 ID
+
+**运行时作用**：Wiki API 需要 `projectId`（数字），但用户只知道 `owner/repo`（字符串），这个函数就是做转换的。
+
+**小白补充**：
+
+### ① 为什么需要 projectID？
+
+GitLink 的 Wiki Gateway API 设计要求传入数字形式的 `projectId`，而不是字符串形式的 `owner/repo`。所以必须先调用主 API 获取项目详情，从中提取 `project_id`。
+
+### ② 缓存机制：
+
+```go
+if cached, ok := projectIDCache.Load(key); ok {
+    return cached.(string), nil
+}
+```
+
+- `projectIDCache.Load(key)` 从缓存中查找
+- 如果找到（`ok == true`），直接返回缓存的值，不需要再调用 API
+- 这是**性能优化**，避免重复请求
+
+### ③ fmt.Sprintf 的用法：
+
+```go
+path := fmt.Sprintf("/%s/%s/detail", ctx.Owner, ctx.Repo)
+```
+
+- 类似 Python 的 `"%s/%s/detail" % (owner, repo)`
+- `%s` 是占位符，会被后面的参数替换
+
+### ④ ctx.CallAPI 是什么？
+
+```go
+env, err := ctx.CallAPI("GET", path, nil)
+```
+
+- `ctx` 是 `*common.RuntimeContext` 类型
+- `CallAPI` 是 `RuntimeContext` 结构体的**方法**（后面会详细讲）
+- 它内部调用 `ctx.Client.Do()` 发送 HTTP 请求
+
+---
+
+## 第 137-140 行：`parseProjectIDInt` 函数
+
+```go
+func parseProjectIDInt(pid string) int {
+    n, _ := strconv.Atoi(pid)
+    return n
+}
+```
+
+**字面意思**：把字符串形式的 projectID 转成整数
+
+**运行时作用**：Wiki API 的某些接口要求 `projectId` 是整数类型，所以需要转换。
+
+**小白补充**：
+- `strconv.Atoi` 是 string convert to int 的缩写
+- `_` 是 Go 语言的"忽略符"，表示忽略返回的错误（这里假设 pid 一定是合法数字）
+
+---
+
+## 第 142-154 行：`resolveUpdateContent` 函数
+
+```go
+func resolveUpdateContent(ctx *common.RuntimeContext, text, filePath string) (string, error) {
+    if text != "" {
+        return text, nil  // 直接使用提供的文本
+    }
+    if filePath != "" {
+        data, err := os.ReadFile(filePath)  // 从文件读取
+        if err != nil {
+            return "", fmt.Errorf("failed to read file %s: %w", filePath, err)
+        }
+        return string(data), nil
+    }
+    return "", fmt.Errorf("no content provided")
+}
+```
+
+**字面意思**：解析更新 Wiki 时的内容来源
+
+**运行时作用**：支持两种方式提供内容：直接文本（`--cover`）或文件路径（`--file`）。
+
+---
+
+## 第 156-179 行：`fetchPageContent` 函数（带自动重试）
+
+```go
+func fetchPageContent(ctx *common.RuntimeContext, projectID, pageName string) (content string, actualPageName string, err error) {
+    // 第一次尝试
+    c, actual, err := fetchPageContentOnce(ctx, projectID, pageName)
+    if err == nil {
+        return c, actual, nil  // 成功了，直接返回
+    }
+    
+    // 第一次失败，且 pageName 不带 ".-" 后缀，自动重试
+    if !strings.HasSuffix(pageName, ".-") {
+        c2, actual2, err2 := fetchPageContentOnce(ctx, projectID, pageName+".-")
+        if err2 == nil {
+            return c2, actual2, nil  // 重试成功
+        }
+    }
+    
+    // 两次都失败
+    return "", "", fmt.Errorf("获取 Wiki 页面现有内容失败: %w", err)
+}
+```
+
+**字面意思**：获取 Wiki 页面的明文内容，带自动重试机制
+
+**运行时作用**：解决 GitLink 后端的一个命名问题。
+
+**小白补充**：
+
+### ① GitLink 后端的命名 bug：
+
+GitLink 创建 Wiki 页面时，会自动给内部存储的 `sub_url` 追加 `".-"` 后缀。但 `wiki +list` 返回的 `title` 不带后缀。
+
+比如：
+- 用户创建页面 "Home"
+- 后端实际存储的 key 是 "Home.-"
+- 但 list API 返回的 title 是 "Home"
+
+所以用 "Home" 去查询会 404，必须用 "Home.-" 才能查到。
+
+### ② 自动重试逻辑：
+1. 先用原始 `pageName` 尝试查询
+2. 如果失败，且 `pageName` 不带 `".-"` 后缀
+3. 自动用 `pageName+".-"` 重试一次
+
+---
+
+## 第 181-205 行：`fetchPageContentOnce` 函数（单次查询）
+
+```go
+func fetchPageContentOnce(ctx *common.RuntimeContext, projectID, pageName string) (string, string, error) {
+    // 构建查询参数
+    q := url.Values{}
+    q.Set("owner", ctx.Owner)
+    q.Set("repo", ctx.Repo)
+    q.Set("projectId", projectID)
+    q.Set("pageName", pageName)
+    
+    // 调用 API
+    env, err := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
+    if err != nil {
+        return "", "", err
+    }
+    
+    // 解析响应
+    data, ok := env.Data.(map[string]interface{})
+    if !ok {
+        return "", "", fmt.Errorf("unexpected response from getWiki")
+    }
+    
+    // 提取 base64 编码的内容
+    b64, _ := data["content_base64"].(string)
+    if b64 == "" {
+        return "", pageName, nil  // 内容为空，返回空字符串
+    }
+    
+    // Base64 解码
+    decoded, err := base64.StdEncoding.DecodeString(b64)
+    if err != nil {
+        return "", "", fmt.Errorf("failed to decode page content: %w", err)
+    }
+    
+    return string(decoded), pageName, nil
+}
+```
+
+**字面意思**：单次尝试获取 Wiki 页面内容
+
+**运行时作用**：发送 GET 请求到 `/wiki/open/getWiki`，获取页面数据并解码。
+
+**小白补充**：
+
+### ① URL 查询参数构建：
+
+```go
+q := url.Values{}
+q.Set("owner", ctx.Owner)
+```
+
+- `url.Values` 是 map 类型，用来存储查询参数
+- 最终会变成 `?owner=zzx&repo=test&projectId=12345&pageName=Home`
+
+### ② Base64 编解码：
+
+```go
+b64, _ := data["content_base64"].(string)  // 获取 base64 编码的内容
+decoded, err := base64.StdEncoding.DecodeString(b64)  // 解码
+return string(decoded), pageName, nil  // 转成字符串返回
+```
+
+- Wiki API 返回的内容是 Base64 编码的（可能是为了支持二进制文件）
+- 需要解码才能得到人类可读的文本
+
+---
+
+## 第 207-216 行：`fetchWikiPage` 函数
+
+```go
+func fetchWikiPage(ctx *common.RuntimeContext, projectID, pageName string) (*output.Envelope, error) {
+    q := url.Values{}
+    q.Set("owner", ctx.Owner)
+    q.Set("repo", ctx.Repo)
+    q.Set("projectId", projectID)
+    q.Set("pageName", pageName)
+    return callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
+}
+```
+
+**字面意思**：获取 Wiki 页面的完整响应（不解码）
+
+**运行时作用**：和 `fetchPageContent` 类似，但返回完整的 `Envelope` 而不是解码后的文本。
+
+---
+
+## 第 218-230 行：`resolveContent` 函数
+
+```go
+func resolveContent(ctx *common.RuntimeContext) (string, error) {
+    if content := ctx.Arg("content"); content != "" {
+        return content, nil
+    }
+    if filePath := ctx.Arg("file"); filePath != "" {
+        data, err := os.ReadFile(filePath)
+        if err != nil {
+            return "", fmt.Errorf("failed to read file %s: %w", filePath, err)
+        }
+        return string(data), nil
+    }
+    return "", fmt.Errorf("--content or --file is required to provide wiki page content")
+}
+```
+
+**字面意思**：解析创建 Wiki 时的内容来源
+
+**运行时作用**：支持 `--content` 直接传内容，或 `--file` 从文件读取。
+
+**小白补充**：
+- `ctx.Arg("content")` 是从命令行参数中获取 `--content` 的值
+- 如果两个参数都没提供，返回错误
+
+---
+
+## 第 232-249 行：`cleanWikiList` 函数
+
+```go
+func cleanWikiList(env *output.Envelope) {
+    // 把 data 转成 slice
+    items, ok := env.Data.([]interface{})
+    if !ok {
+        return
+    }
+    
+    // 遍历每个 wiki 页面
+    for _, item := range items {
+        m, ok := item.(map[string]interface{})
+        if !ok {
+            continue
+        }
+        
+        // 删除不需要的字段
+        delete(m, "wiki_clone_link")
+        
+        // URL 解码 sub_url
+        if raw, ok := m["sub_url"].(string); ok {
+            if decoded, err := url.QueryUnescape(raw); err == nil {
+                m["sub_url"] = decoded
+            }
+        }
+    }
+}
+```
+
+**字面意思**：清理 Wiki 列表数据
+
+**运行时作用**：对 `wiki +list` 返回的数据进行清洗，去掉无用字段，解码 URL。
+
+---
+
+## 第 251-299 行：`outputWithDecodedContent` 函数
+
+```go
+func outputWithDecodedContent(ctx *common.RuntimeContext, env *output.Envelope) error {
+    data := env.Data
+    
+    // 处理 JSON 字符串形式的 data
+    if raw, ok := data.(json.RawMessage); ok {
+        var m map[string]interface{}
+        if err := json.Unmarshal(raw, &m); err == nil {
+            data = m
+            env.Data = m
+        }
+    }
+    
+    // 转成 map
+    m, ok := data.(map[string]interface{})
+    if !ok {
+        return ctx.Output(env)
+    }
+    
+    // content_base64 → content（重命名并解码）
+    if b64, ok := m["content_base64"].(string); ok && b64 != "" {
+        if decoded, err := base64.StdEncoding.DecodeString(b64); err == nil {
+            m["content"] = string(decoded)
+            delete(m, "content_base64")  // 删除原字段
+        }
+    }
+    
+    // sidebar / footer 原地解码
+    for _, field := range []string{"sidebar", "footer"} {
+        if b64, ok := m[field].(string); ok && b64 != "" {
+            if decoded, err := base64.StdEncoding.DecodeString(b64); err == nil {
+                m[field] = string(decoded)
+            }
+        }
+    }
+    
+    return ctx.Output(env)
+}
+```
+
+**字面意思**：解码 Wiki 响应中的所有 Base64 字段，用明文替换
+
+**运行时作用**：让返回的 Wiki 内容更易读，同时节省 token（Base64 编码会增加约 33% 的体积）。
+
+---
+
+## 第 301-526 行：Lint 相关
--- a/doc/reading_notes/04_webhook.md
+++ b/doc/reading_notes/04_webhook.md
@ -0,0 +1,510 @@
+# 逐行讲解 shortcuts/webhook/webhook.go（面向 Go 小白）
+
+## 文件概述
+
+这个文件实现了 **Webhook 管理**功能，可以对 GitLink 仓库的 Webhook 进行增删改查操作。
+
+---
+
+## 一、包声明和导入
+
+```go
+package webhook
+
+import (
+    "fmt"
+    "net/url"
+    "strings"
+
+    clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
+    "github.com/gitlink-org/gitlink-cli/internal/output"
+    "github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+```
+
+| 导入库 | 作用 |
+|-------|------|
+| `fmt` | 格式化输出，用于拼接字符串和格式化错误信息 |
+| `net/url` | URL 相关操作，用于构建查询参数 |
+| `strings` | 字符串处理，用于分割、修剪等操作 |
+| `clierrors` | 自定义 CLI 错误类型，用于返回友好的错误提示 |
+| `output` | 输出格式化，用于返回统一格式的结果 |
+| `common` | 公共工具包，包含 Shortcut、RuntimeContext 等核心类型 |
+
+---
+
+## 二、支持的 Webhook 事件类型
+
+```go
+var supportedEvents = []string{
+    "push",
+    "pull_request",
+    "issue",
+    "issue_assign",
+    "issue_comment",
+    "pull_request_assign",
+    "pull_request_comment",
+    "merge_request",
+    "repository",
+    "branch",
+    "tag",
+}
+```
+
+这是一个**全局变量**，定义了 GitLink 支持的所有 Webhook 事件类型：
+- `push`：代码推送事件
+- `pull_request`：PR 事件
+- `issue`：Issue 事件
+- `issue_assign`：Issue 分配事件
+- `issue_comment`：Issue 评论事件
+- `pull_request_assign`：PR 分配事件
+- `pull_request_comment`：PR 评论事件
+- `merge_request`：合并请求事件
+- `repository`：仓库事件
+- `branch`：分支创建/删除事件
+- `tag`：标签创建/删除事件
+
+---
+
+## 三、事件验证函数
+
+```go
+func isEventSupported(event string) bool {
+    for _, supported := range supportedEvents {
+        if event == supported {
+            return true
+        }
+    }
+    return false
+}
+```
+
+**功能**：检查某个事件类型是否被支持
+
+**工作原理**：遍历 `supportedEvents` 数组，逐一比对，如果找到匹配项就返回 `true`，否则返回 `false`
+
+---
+
+## 四、解析事件字符串
+
+```go
+func parseEvents(eventsStr string) []string {
+    if eventsStr == "" {
+        return []string{"push"} // 默认事件
+    }
+    events := strings.Split(eventsStr, ",")
+    var validEvents []string
+    for _, event := range events {
+        event = strings.TrimSpace(event)
+        if isEventSupported(event) {
+            validEvents = append(validEvents, event)
+        }
+    }
+    return validEvents
+}
+```
+
+**功能**：把用户输入的逗号分隔的事件字符串（如 `"push,pull_request"`）解析成事件数组
+
+**逐行解读**：
+1. 如果输入为空，返回默认值 `["push"]`
+2. 使用 `strings.Split` 按逗号分割字符串
+3. 遍历每个事件，用 `strings.TrimSpace` 去掉前后空格
+4. 用 `isEventSupported` 验证有效性，有效才加入结果数组
+5. 返回过滤后的有效事件数组
+
+---
+
+## 五、API 路径构建函数
+
+```go
+func webhookRepoPath(ctx *common.RuntimeContext) string {
+    return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+}
+```
+
+**功能**：构建 Webhook API 的基础路径
+
+**参数**：`ctx` 是运行时上下文，包含 `Owner`（仓库所有者）和 `Repo`（仓库名）
+
+**返回值**：类似 `/v1/owner/repo` 的字符串
+
+**注意**：注释说明了 BaseURL 已经包含 `/api` 前缀，所以这里不需要再加
+
+---
+
+## 六、Shortcuts 主函数
+
+```go
+func Shortcuts() []*common.Shortcut {
+    return []*common.Shortcut{
+        // list 命令
+        // create 命令
+        // update 命令
+        // delete 命令
+        // test 命令
+        // info 命令
+        // events 命令
+    }
+}
+```
+
+**功能**：返回所有 Webhook 相关的 CLI 命令列表
+
+这个函数是整个文件的核心，它定义了7个命令：
+1. `list` - 列出所有 Webhook
+2. `create` - 创建新 Webhook
+3. `update` - 更新现有 Webhook
+4. `delete` - 删除 Webhook
+5. `test` - 测试 Webhook 发送
+6. `info` - 查看 Webhook 详情
+7. `events` - 列出所有支持的事件类型
+
+---
+
+## 七、命令详解
+
+### 7.1 list 命令
+
+```go
+{
+    Name:        "list",
+    Description: "List all webhooks for a repository",
+    Flags: []common.Flag{
+        {Name: "page", Short: "p", Usage: "Page number", Default: "1"},
+        {Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        if err := ctx.ResolveOwnerRepo(); err != nil {
+            return err
+        }
+        q := url.Values{}
+        q.Set("page", ctx.Arg("page"))
+        q.Set("limit", ctx.Arg("limit"))
+        env, err := ctx.CallAPIWithQuery("GET", webhookRepoPath(ctx)+"/webhooks", q)
+        if err != nil {
+            return fmt.Errorf("获取 Webhook 列表失败: %w", err)
+        }
+        return ctx.Output(env)
+    },
+}
+```
+
+**Flags 参数说明**：
+- `--page/-p`：页码，默认第1页
+- `--limit/-l`：每页条数，默认20条
+
+**执行流程**：
+1. 调用 `ctx.ResolveOwnerRepo()` 解析仓库信息
+2. 创建 URL 查询参数 `url.Values{}`
+3. 设置 `page` 和 `limit` 参数
+4. 调用 `CallAPIWithQuery` 发送 GET 请求到 `/v1/owner/repo/webhooks`
+5. 返回结果给用户
+
+---
+
+### 7.2 create 命令
+
+```go
+{
+    Name:        "create",
+    Description: "Create a new webhook",
+    Flags: []common.Flag{
+        {Name: "url", Short: "u", Usage: "Webhook callback URL", Required: true},
+        {Name: "events", Short: "e", Usage: "Trigger events", Default: "push"},
+        {Name: "active", Usage: "Webhook active status", Default: "true"},
+        {Name: "secret", Usage: "Webhook secret for HMAC verification"},
+        {Name: "description", Short: "d", Usage: "Webhook description"},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        if err := ctx.ResolveOwnerRepo(); err != nil {
+            return err
+        }
+
+        webhookURL, err := ctx.RequireArg("url", "--url https://example.com/hook")
+        if err != nil {
+            return err
+        }
+
+        events := parseEvents(ctx.Arg("events"))
+        if len(events) == 0 {
+            return clierrors.InputError(...)
+        }
+
+        payload := map[string]interface{}{
+            "url":          webhookURL,
+            "http_method":  "POST",
+            "active":       true,
+            "content_type": "json",
+        }
+
+        // 添加可选参数
+        if len(events) > 0 {
+            payload["events"] = events
+        }
+        if secret := ctx.Arg("secret"); secret != "" {
+            payload["secret"] = secret
+        }
+        if description := ctx.Arg("description"); description != "" {
+            payload["description"] = description
+        }
+
+        env, err := ctx.CallAPI("POST", webhookRepoPath(ctx)+"/webhooks", payload)
+        if err != nil {
+            return fmt.Errorf("创建 Webhook 失败: %w", err)
+        }
+        return ctx.Output(env)
+    },
+}
+```
+
+**执行流程**：
+1. 解析仓库信息
+2. 必须获取 `--url` 参数（用 `RequireArg`，如果没提供会报错）
+3. 解析事件类型
+4. 创建 payload 映射，包含必填字段
+5. 添加可选的 secret 和 description
+6. 发送 POST 请求创建 Webhook
+
+---
+
+### 7.3 update 命令
+
+```go
+{
+    Name:        "update",
+    Description: "Update an existing webhook",
+    Flags: []common.Flag{
+        {Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
+        {Name: "url", Short: "u", Usage: "Webhook callback URL"},
+        {Name: "events", Short: "e", Usage: "Trigger events"},
+        {Name: "active", Usage: "Webhook active status"},
+        {Name: "content_type", Usage: "Content type"},
+        {Name: "secret", Usage: "Webhook secret"},
+        {Name: "description", Short: "d", Usage: "Webhook description"},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        // ... 解析仓库和 ID
+        
+        webhookURL := ctx.Arg("url")
+        if webhookURL == "" {
+            // 如果用户没提供 URL，先获取当前 URL
+            getEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
+            // ... 解析响应获取当前 URL
+            webhookURL = currentURL
+        }
+        payload["url"] = webhookURL
+        
+        // ... 发送 PUT 请求
+    },
+}
+```
+
+**亮点**：如果用户没有提供新的 URL，会自动调用 GET API 获取当前 URL，这样就不需要用户重复输入
+
+---
+
+### 7.4 delete 命令
+
+```go
+{
+    Name:        "delete",
+    Description: "Delete a webhook",
+    Flags: []common.Flag{
+        {Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        // ... 解析仓库和 ID
+        
+        _, delErr := ctx.CallAPI("DELETE", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
+        if delErr != nil {
+            // 验证是否真的删除成功
+            _, viewErr := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
+            if viewErr != nil {
+                // GET 也失败，说明 Webhook 确实不存在了，删除成功
+                return ctx.Output(output.SuccessEnvelope(map[string]interface{}{
+                    "message": "Webhook deleted successfully",
+                }, nil))
+            }
+            return fmt.Errorf("删除 Webhook 失败: %w", delErr)
+        }
+        return ctx.Output(output.SuccessEnvelope(...))
+    },
+}
+```
+
+**亮点**：删除操作有一个**双重验证**机制：
+1. 先调用 DELETE 请求
+2. 如果 DELETE 返回错误，再调用 GET 请求检查 Webhook 是否还存在
+3. 如果 GET 也失败，说明 Webhook 已经被删除了，视为成功
+
+---
+
+### 7.5 test 命令
+
+```go
+{
+    Name:        "test",
+    Description: "Test a webhook delivery",
+    Flags: []common.Flag{
+        {Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
+        {Name: "event", Short: "e", Usage: "Event type to test", Default: "push"},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        // ... 解析参数
+        
+        eventType := ctx.Arg("event")
+        if !isEventSupported(eventType) {
+            return clierrors.InputError(...)
+        }
+        
+        env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/webhooks/%s/tests", webhookRepoPath(ctx), webhookID), nil)
+        // ...
+    },
+}
+```
+
+**功能**：向指定的 Webhook 发送测试请求，验证 Webhook 是否正常工作
+
+---
+
+### 7.6 info 命令
+
+```go
+{
+    Name:        "info",
+    Description: "Show webhook details",
+    Flags: []common.Flag{
+        {Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
+    },
+    Run: func(ctx *common.RuntimeContext) error {
+        // ... 调用 GET /v1/owner/repo/webhooks/{id}
+    },
+}
+```
+
+**功能**：查看单个 Webhook 的详细信息
+
+---
+
+### 7.7 events 命令
+
+```go
+{
+    Name:        "events",
+    Description: "List all supported event types for webhooks",
+    Run: func(ctx *common.RuntimeContext) error {
+        eventInfo := make([]map[string]interface{}, 0)
+        for _, event := range supportedEvents {
+            eventInfo = append(eventInfo, map[string]interface{}{
+                "event":      event,
+                "supported":  true,
+                "description": getEventDescription(event),
+            })
+        }
+        return ctx.Output(output.SuccessEnvelope(eventInfo, nil))
+    },
+}
+```
+
+**功能**：列出所有支持的 Webhook 事件类型及其描述
+
+---
+
+## 八、事件描述函数
+
+```go
+func getEventDescription(event string) string {
+    descriptions := map[string]string{
+        "push":                "Code push events",
+        "pull_request":        "Pull request events",
+        "issue":               "Issue events",
+        // ... 其他事件描述
+    }
+    if desc, ok := descriptions[event]; ok {
+        return desc
+    }
+    return "Custom event"
+}
+```
+
+**功能**：返回事件类型的英文描述
+
+**工作原理**：使用 map 查找事件对应的描述，如果找不到就返回 "Custom event"
+
+---
+
+## 九、完整调用流程
+
+```
+用户命令 (gitlink webhook list)
+    ↓
+解析命令行参数
+    ↓
+Shortcuts() 返回命令列表
+    ↓
+匹配到 "list" 命令
+    ↓
+执行 Run 函数
+    ↓
+ctx.ResolveOwnerRepo() → 解析仓库信息
+    ↓
+ctx.CallAPIWithQuery() → 调用 HTTP 客户端
+    ↓
+内部调用 client.Do() → 发送 GET 请求
+    ↓
+解析响应 → ctx.Output() → 格式化输出给用户
+```
+
+---
+
+## 十、Go 语言知识点
+
+### 1. map[string]interface{} 类型
+
+```go
+payload := map[string]interface{}{
+    "url":          webhookURL,
+    "http_method":  "POST",
+    "active":       true,
+}
+```
+
+这是一个**万能类型**，可以存储任意类型的值：
+- `"url"` 对应字符串
+- `"active"` 对应布尔值
+- `"events"` 对应字符串数组
+
+### 2. 字符串拼接
+
+```go
+fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+```
+
+类似 Python 的 `f"/v1/{owner}/{repo}"`，用 `%s` 占位符
+
+### 3. 错误包装
+
+```go
+return fmt.Errorf("获取 Webhook 列表失败: %w", err)
+```
+
+`%w` 是 Go 1.13+ 的错误包装语法，保留原始错误信息
+
+### 4. 函数作为参数
+
+```go
+Run: func(ctx *common.RuntimeContext) error {
+    // 匿名函数
+}
+```
+
+这是一个**匿名函数**，作为 `Shortcut` 结构体的 `Run` 字段值
+
+### 5. 字符串分割
+
+```go
+events := strings.Split(eventsStr, ",")
+```
+
+按逗号分割字符串，返回字符串数组
--- a/doc/reading_notes/05_issue_batch.md
+++ b/doc/reading_notes/05_issue_batch.md
@ -0,0 +1,546 @@
+# 逐行讲解 shortcuts/issue/batch.go（面向 Go 小白）
+
+## 文件概述
+
+这个文件实现了 **Issue 批量操作**功能，可以对多个 Issue 进行批量关闭、修改状态、修改优先级、分配人和修改标签等操作。
+
+---
+
+## 一、包声明和导入
+
+```go
+package issue
+
+import (
+    "encoding/csv"
+    "fmt"
+    "os"
+    "strconv"
+    "strings"
+
+    "github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+```
+
+| 导入库 | 作用 |
+|-------|------|
+| `encoding/csv` | CSV 文件解析，用于从文件读取 Issue 编号 |
+| `fmt` | 格式化输出 |
+| `os` | 文件操作，用于打开 CSV 文件 |
+| `strconv` | 字符串和数字之间的转换 |
+| `strings` | 字符串处理 |
+| `common` | 公共工具包 |
+
+---
+
+## 二、常量定义
+
+```go
+const (
+    priorityLow    = 1
+    priorityNormal = 2
+    priorityHigh   = 3
+    priorityUrgent = 4
+)
+```
+
+**优先级常量**：定义了 Issue 优先级对应的数字 ID
+
+```go
+const (
+    statusNew        = 1
+    statusInProgress = 2
+    statusResolved   = 3
+    statusClosed     = 5
+    statusRejected   = 6
+)
+```
+
+**状态常量**：定义了 Issue 状态对应的数字 ID
+
+```go
+const (
+    trackerBug       = 1
+    trackerFeature   = 2
+    trackerSupport   = 3
+    trackerDoc       = 4
+    trackerTest      = 5
+    trackerDuplicate = 6
+    trackerQuestion  = 7
+)
+```
+
+**类型常量**：定义了 Issue 类型对应的数字 ID
+
+---
+
+## 三、名称映射表
+
+```go
+var priorityNames = map[int]string{
+    priorityLow:    "low",
+    priorityNormal: "normal",
+    priorityHigh:   "high",
+    priorityUrgent: "urgent",
+}
+
+var statusNames = map[int]string{
+    statusNew:        "new",
+    statusInProgress: "in-progress",
+    statusResolved:   "resolved",
+    statusClosed:     "closed",
+    statusRejected:   "rejected",
+}
+
+var trackerNames = map[int]string{
+    trackerBug:       "bug",
+    trackerFeature:   "feature",
+    // ...
+}
+```
+
+**作用**：把数字 ID 转换成可读的英文名称，方便输出结果
+
+---
+
+## 四、标签 ID 映射
+
+```go
+var tagIDs = map[string]int{
+    "缺陷": 315526,
+    "功能": 315527,
+    "文档": 315533,
+    "重复": 315525,
+    "疑问": 315528,
+    "支持": 315529,
+    "任务": 315530,
+    "测试": 315534,
+    "协助": 315531,
+    "搁置": 315532,
+}
+```
+
+**作用**：中文标签名称到 GitLink 标签 ID 的映射
+
+**注意**：这些 ID 是从网页端 DevTools 抓包获取的，不同项目可能不同
+
+---
+
+## 五、结果结构体
+
+```go
+type BatchResult struct {
+    Number string `json:"number" yaml:"number"`
+    Action string `json:"action" yaml:"action"`
+    Status string `json:"status" yaml:"status"`
+    Error  string `json:"error,omitempty" yaml:"error,omitempty"`
+}
+```
+
+**单个操作结果**：记录单个 Issue 的操作结果
+
+```go
+type BatchSummary struct {
+    Repository string        `json:"repository" yaml:"repository"`
+    Action     string        `json:"action" yaml:"action"`
+    Value      string        `json:"value,omitempty" yaml:"value,omitempty"`
+    DryRun     bool          `json:"dry_run" yaml:"dry_run"`
+    Total      int           `json:"total" yaml:"total"`
+    Succeeded  int           `json:"succeeded" yaml:"succeeded"`
+    Failed     int           `json:"failed" yaml:"failed"`
+    Results    []BatchResult `json:"results" yaml:"results"`
+}
+```
+
+**批量操作汇总**：记录整个批量操作的统计信息
+
+---
+
+## 六、批量操作命令
+
+### 6.1 batch-close 命令
+
+```go
+func newBatchCloseShortcut() *common.Shortcut {
+    return &common.Shortcut{
+        Name:        "batch-close",
+        Description: "Close multiple issues by issue numbers or a CSV file",
+        Flags: []common.Flag{
+            {Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers"},
+            {Name: "from", Usage: "Read issue numbers from a CSV file"},
+            {Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
+        },
+        Run: runBatchClose,
+    }
+}
+```
+
+**执行函数**：
+
+```go
+func runBatchClose(ctx *common.RuntimeContext) error {
+    if err := ctx.ResolveOwnerRepo(); err != nil {
+        return err
+    }
+    numbers, err := collectIssueNumbers(ctx.Arg("numbers"), ctx.Arg("from"))
+    if err != nil {
+        return err
+    }
+    if len(numbers) == 0 {
+        return fmt.Errorf("no issue numbers provided")
+    }
+
+    dryRun := parseBool(ctx.Arg("dry-run"))
+    summary := BatchSummary{
+        Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+        Action:     "close",
+        DryRun:     dryRun,
+        Total:      len(numbers),
+        Results:    make([]BatchResult, 0, len(numbers)),
+    }
+
+    for _, number := range numbers {
+        result := BatchResult{Number: number, Action: "close"}
+        if dryRun {
+            result.Status = "planned"
+            summary.Succeeded++
+            summary.Results = append(summary.Results, result)
+            continue
+        }
+        if err := updateIssueField(ctx, number, map[string]interface{}{"status_id": statusClosed}); err != nil {
+            result.Status = "failed"
+            result.Error = err.Error()
+            summary.Failed++
+        } else {
+            result.Status = "closed"
+            summary.Succeeded++
+        }
+        summary.Results = append(summary.Results, result)
+    }
+
+    if err := ctx.OutputData(summary); err != nil {
+        return err
+    }
+    if summary.Failed > 0 {
+        return fmt.Errorf("%d of %d issue(s) failed", summary.Failed, summary.Total)
+    }
+    return nil
+}
+```
+
+**执行流程**：
+1. 解析仓库信息
+2. 收集 Issue 编号（从 `--numbers` 参数或 CSV 文件）
+3. 初始化 `BatchSummary` 汇总对象
+4. 遍历每个 Issue 编号：
+   - 如果是 dry-run，直接标记为 planned
+   - 否则调用 `updateIssueField` 更新状态为 closed
+5. 输出汇总结果
+
+---
+
+### 6.2 batch-status 命令
+
+```go
+func runBatchStatus(ctx *common.RuntimeContext) error {
+    // ... 解析参数
+    state := ctx.Arg("state")
+    statusID, err := parseStatus(state)
+    if err != nil {
+        return err
+    }
+    // ... 遍历更新
+    updateIssueField(ctx, number, map[string]interface{}{"status_id": statusID})
+}
+```
+
+**功能**：批量修改 Issue 状态
+
+**参数**：`--state` 指定目标状态（new/in-progress/resolved/closed/rejected）
+
+---
+
+### 6.3 batch-priority 命令
+
+```go
+func runBatchPriority(ctx *common.RuntimeContext) error {
+    // ...
+    priority := ctx.Arg("priority")
+    priorityID, err := parsePriority(priority)
+    // ...
+    updateIssueField(ctx, number, map[string]interface{}{"priority_id": priorityID})
+}
+```
+
+**功能**：批量修改 Issue 优先级
+
+**参数**：`--priority` 指定目标优先级（low/normal/high/urgent）
+
+---
+
+### 6.4 batch-assign 命令
+
+```go
+func runBatchAssign(ctx *common.RuntimeContext) error {
+    // ...
+    assignee := ctx.Arg("assignee")
+    var assigneeID interface{}
+    if !dryRun {
+        id, err := resolveUserID(ctx, assignee)
+        assigneeID = id
+    }
+    // ...
+    updateIssueField(ctx, number, map[string]interface{}{"assigned_to_id": assigneeID})
+}
+```
+
+**功能**：批量分配 Issue 给指定用户
+
+**亮点**：需要先把用户名转换成用户 ID
+
+---
+
+### 6.5 batch-label 命令
+
+```go
+func runBatchLabel(ctx *common.RuntimeContext) error {
+    // ...
+    label := ctx.Arg("label")
+    trackerID, err := parseTracker(label)
+    // ...
+    updateIssueField(ctx, number, map[string]interface{}{"issue_tag_ids": []int{trackerID}})
+}
+```
+
+**功能**：批量修改 Issue 的标签
+
+**参数**：`--label` 可以是英文（bug/feature）或中文（缺陷/功能）
+
+---
+
+## 七、核心辅助函数
+
+### 7.1 updateIssueField
+
+```go
+func updateIssueField(ctx *common.RuntimeContext, number string, fields map[string]interface{}) error {
+    current, err := fetchExistingIssue(ctx, number)
+    if err != nil {
+        return fmt.Errorf("fetch issue #%s: %w", number, err)
+    }
+
+    body := map[string]interface{}{
+        "subject":     current.Subject,
+        "description": current.Description,
+    }
+    for k, v := range fields {
+        body[k] = v
+    }
+
+    if _, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body); err != nil {
+        return fmt.Errorf("update issue #%s: %w", number, err)
+    }
+    return nil
+}
+```
+
+**功能**：更新 Issue 的指定字段
+
+**关键点**：
+1. 先调用 `fetchExistingIssue` 获取当前 Issue 的标题和描述
+2. 必须在请求体中包含 `subject` 和 `description`，否则会被清空
+3. 把要更新的字段合并到 body 中
+4. 发送 PATCH 请求
+
+---
+
+### 7.2 resolveUserID
+
+```go
+func resolveUserID(ctx *common.RuntimeContext, login string) (interface{}, error) {
+    if id, err := strconv.Atoi(login); err == nil {
+        return id, nil
+    }
+
+    env, err := ctx.CallAPI("GET", fmt.Sprintf("/users/%s", login), nil)
+    if err != nil {
+        return nil, fmt.Errorf("lookup user %q: %w", login, err)
+    }
+    data, ok := env.Data.(map[string]interface{})
+    if !ok {
+        return nil, fmt.Errorf("unexpected response for user %q", login)
+    }
+    idFloat, ok := data["id"].(float64)
+    if ok {
+        return int(idFloat), nil
+    }
+    userIDFloat, ok := data["user_id"].(float64)
+    if ok {
+        return int(userIDFloat), nil
+    }
+    return nil, fmt.Errorf("cannot determine user ID for %q", login)
+}
+```
+
+**功能**：把用户名转换成用户 ID
+
+**工作原理**：
+1. 如果输入已经是数字，直接返回
+2. 否则调用 `/users/{login}` API 获取用户信息
+3. 从响应中提取 `id` 或 `user_id` 字段
+4. API 返回的数字是 float64 类型，需要转换成 int
+
+---
+
+### 7.3 collectIssueNumbers
+
+```go
+func collectIssueNumbers(numbersValue, csvPath string) ([]string, error) {
+    numbers, err := parseIssueNumbers(numbersValue)
+    if err != nil {
+        return nil, err
+    }
+    if csvPath == "" {
+        return numbers, nil
+    }
+    csvNumbers, err := readIssueNumbersFromCSV(csvPath)
+    if err != nil {
+        return nil, err
+    }
+    return mergeIssueNumbers(numbers, csvNumbers), nil
+}
+```
+
+**功能**：从 `--numbers` 参数和 CSV 文件中收集 Issue 编号
+
+---
+
+### 7.4 readIssueNumbersFromCSV
+
+```go
+func readIssueNumbersFromCSV(path string) ([]string, error) {
+    file, err := os.Open(path)
+    if err != nil {
+        return nil, fmt.Errorf("read CSV: %w", err)
+    }
+    defer file.Close()
+
+    reader := csv.NewReader(file)
+    reader.TrimLeadingSpace = true
+    records, err := reader.ReadAll()
+    if err != nil {
+        return nil, fmt.Errorf("parse CSV: %w", err)
+    }
+
+    numberColumn := -1
+    startRow := 0
+    for i, cell := range records[0] {
+        switch strings.ToLower(strings.TrimSpace(cell)) {
+        case "number", "issue_number", "project_issues_index":
+            numberColumn = i
+            startRow = 1
+        }
+    }
+    if numberColumn == -1 {
+        numberColumn = 0
+    }
+
+    values := make([]string, 0, len(records)-startRow)
+    for _, record := range records[startRow:] {
+        if numberColumn >= len(record) {
+            continue
+        }
+        values = append(values, record[numberColumn])
+    }
+    return normalizeIssueNumbers(values)
+}
+```
+
+**功能**：从 CSV 文件读取 Issue 编号
+
+**智能表头识别**：
+- 自动识别 `number`、`issue_number`、`project_issues_index` 列
+- 如果没有匹配的表头，默认使用第一列
+- 跳过表头行，从第二行开始读取
+
+---
+
+## 八、类型转换函数
+
+```go
+func parseStatus(state string) (int, error) {
+    switch strings.ToLower(strings.TrimSpace(state)) {
+    case "new":
+        return statusNew, nil
+    case "in-progress", "in_progress", "inprogress":
+        return statusInProgress, nil
+    // ...
+    default:
+        if id, err := strconv.Atoi(state); err == nil {
+            return id, nil
+        }
+        return 0, fmt.Errorf("invalid state %q", state)
+    }
+}
+```
+
+**功能**：把用户输入的状态字符串转换成数字 ID
+
+**容错处理**：
+- 支持多种写法：`in-progress`、`in_progress`、`inprogress`
+- 如果输入是数字，直接返回
+
+`parsePriority` 和 `parseTracker` 函数类似
+
+---
+
+## 九、Go 语言知识点
+
+### 1. const 常量定义
+
+```go
+const (
+    priorityLow    = 1
+    priorityNormal = 2
+)
+```
+
+在 `const` 块中，后续常量会继承前一个常量的值并自动加1
+
+### 2. defer 语句
+
+```go
+file, err := os.Open(path)
+defer file.Close()
+```
+
+`defer` 会在函数返回前执行，确保文件被关闭
+
+### 3. map 遍历
+
+```go
+for k, v := range fields {
+    body[k] = v
+}
+```
+
+遍历 map 的键值对
+
+### 4. type assertion（类型断言）
+
+```go
+data, ok := env.Data.(map[string]interface{})
+if !ok {
+    return nil, fmt.Errorf("unexpected response")
+}
+```
+
+把接口类型转换成具体类型，`ok` 表示转换是否成功
+
+### 5. strconv.Atoi
+
+```go
+id, err := strconv.Atoi(login)
+```
+
+把字符串转换成整数，如果失败返回错误
--- a/doc/reading_notes/06_issue_batch_create.md
+++ b/doc/reading_notes/06_issue_batch_create.md
@ -0,0 +1,673 @@
+# 逐行讲解 shortcuts/issue/batch_create.go（面向 Go 小白）
+
+## 文件概述
+
+这个文件实现了 **Issue 批量创建**功能，可以从命令行或 CSV 文件批量创建多个 Issue，并支持 bug 和 feature 两种模板。
+
+---
+
+## 一、包声明和导入
+
+```go
+package issue
+
+import (
+    "encoding/csv"
+    "fmt"
+    "net/url"
+    "os"
+    "strconv"
+    "strings"
+    "sync"
+
+    "github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+```
+
+| 导入库 | 作用 |
+|-------|------|
+| `encoding/csv` | CSV 文件解析 |
+| `fmt` | 格式化输出 |
+| `net/url` | URL 查询参数构建 |
+| `os` | 文件操作 |
+| `strconv` | 字符串和数字转换 |
+| `strings` | 字符串处理 |
+| `sync` | 并发安全，用于缓存 |
+| `common` | 公共工具包 |
+
+---
+
+## 二、标签缓存
+
+```go
+var issueTagCache sync.Map
+```
+
+**作用**：缓存项目的标签列表，避免重复请求 API
+
+**sync.Map**：Go 语言提供的并发安全的 map，可以在多个 goroutine 中安全地读写
+
+---
+
+## 三、resolveIssueTags 函数
+
+```go
+func resolveIssueTags(ctx *common.RuntimeContext) (map[string]int, error) {
+    key := ctx.Owner + "/" + ctx.Repo
+    if cached, ok := issueTagCache.Load(key); ok {
+        return cached.(map[string]int), nil
+    }
+
+    path := fmt.Sprintf("/v1/%s/%s/issue_tags", ctx.Owner, ctx.Repo)
+    q := url.Values{}
+    q.Set("only_name", "true")
+    env, err := ctx.CallAPIWithQuery("GET", path, q)
+    if err != nil {
+        return nil, fmt.Errorf("获取项目标签列表失败: %w", err)
+    }
+
+    data, ok := env.Data.(map[string]interface{})
+    if !ok {
+        return nil, fmt.Errorf("标签列表响应格式异常")
+    }
+
+    rawTags, ok := data["issue_tags"].([]interface{})
+    if !ok {
+        return nil, fmt.Errorf("标签列表响应缺少 issue_tags 字段")
+    }
+
+    tags := make(map[string]int, len(rawTags))
+    for _, item := range rawTags {
+        tag, ok := item.(map[string]interface{})
+        if !ok {
+            continue
+        }
+        name, _ := tag["name"].(string)
+        if name == "" {
+            continue
+        }
+        var id int
+        switch v := tag["id"].(type) {
+        case float64:
+            id = int(v)
+        case int:
+            id = v
+        default:
+            id, _ = strconv.Atoi(fmt.Sprintf("%v", v))
+        }
+        if id == 0 {
+            continue
+        }
+        tags[name] = id
+    }
+
+    if len(tags) == 0 {
+        return nil, fmt.Errorf("项目没有配置任何标签，请先在 GitLink 网页端创建标签")
+    }
+
+    issueTagCache.Store(key, tags)
+    return tags, nil
+}
+```
+
+**功能**：获取项目的 Issue 标签列表，并缓存结果
+
+**执行流程**：
+1. 构建缓存 key（owner/repo）
+2. 先从缓存中查找，如果有就直接返回
+3. 如果缓存中没有，调用 API 获取标签列表
+4. 解析 API 响应，提取标签名称和 ID
+5. 处理多种 ID 类型（float64、int、其他）
+6. 把结果存入缓存
+7. 返回标签映射
+
+---
+
+## 四、命令定义
+
+```go
+func newBatchCreateShortcut() *common.Shortcut {
+    return &common.Shortcut{
+        Name:        "batch-create",
+        Description: "Create multiple issues from CLI flags or a CSV file",
+        Flags: []common.Flag{
+            {Name: "titles", Usage: "Comma-separated issue titles"},
+            {Name: "priority", Short: "p", Usage: "Priority: low, normal, high, urgent"},
+            {Name: "label", Short: "l", Usage: "Label name"},
+            {Name: "assignee", Short: "a", Usage: "Assignee login name"},
+            {Name: "state", Short: "s", Usage: "Initial state", Default: "new"},
+            {Name: "from", Usage: "CSV file path"},
+            {Name: "template", Short: "t", Usage: "Template: bug or feature"},
+            {Name: "dry-run", Usage: "Preview without creating", Bool: true, Default: "false"},
+        },
+        Run: runBatchCreate,
+    }
+}
+```
+
+**Flags 参数说明**：
+- `--titles`：逗号分隔的 Issue 标题
+- `--priority/-p`：优先级
+- `--label/-l`：标签
+- `--assignee/-a`：分配人
+- `--state/-s`：初始状态
+- `--from`：CSV 文件路径
+- `--template/-t`：模板类型（bug/feature）
+- `--dry-run`：预览模式
+
+---
+
+## 五、输入结构体
+
+```go
+type createIssueInput struct {
+    Title    string
+    Body     string
+    Priority string
+    Label    string
+    Assignee string
+    Status   string
+    // template-specific fields
+    Version    string
+    Severity   string
+    Steps      string
+    Expected   string
+    Actual     string
+    UserStory  string
+    Acceptance string
+}
+```
+
+**作用**：存储创建 Issue 的所有输入参数
+
+**模板专用字段**：
+- `Version`、`Severity`、`Steps`、`Expected`、`Actual`：用于 bug 模板
+- `UserStory`、`Acceptance`：用于 feature 模板
+
+---
+
+## 六、runBatchCreate 主函数
+
+```go
+func runBatchCreate(ctx *common.RuntimeContext) error {
+    if err := ctx.ResolveOwnerRepo(); err != nil {
+        return err
+    }
+
+    tags, err := resolveIssueTags(ctx)
+    if err != nil {
+        return err
+    }
+
+    dryRun := parseBool(ctx.Arg("dry-run"))
+    template := strings.ToLower(strings.TrimSpace(ctx.Arg("template")))
+
+    var inputs []createIssueInput
+    if titlesStr := ctx.Arg("titles"); titlesStr != "" {
+        inputs = append(inputs, parseTitles(titlesStr, ctx)...)
+    }
+    if csvPath := ctx.Arg("from"); csvPath != "" {
+        csvInputs, err := readCreateInputsFromCSV(csvPath, template)
+        if err != nil {
+            return err
+        }
+        inputs = append(inputs, csvInputs...)
+    }
+    if len(inputs) == 0 {
+        return fmt.Errorf("no issue titles provided")
+    }
+
+    cliState := ctx.Arg("state")
+    for i := range inputs {
+        if inputs[i].Status == "" {
+            inputs[i].Status = cliState
+        }
+    }
+
+    summary := BatchSummary{
+        Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+        Action:     "create",
+        Value:      template,
+        DryRun:     dryRun,
+        Total:      len(inputs),
+        Results:    make([]BatchResult, 0, len(inputs)),
+    }
+
+    for i, input := range inputs {
+        label := fmt.Sprintf("#%d", i+1)
+        if input.Title != "" {
+            label = truncate(input.Title, 40)
+        }
+        result := BatchResult{Number: label, Action: "create"}
+
+        if dryRun {
+            result.Status = "planned"
+            summary.Succeeded++
+            summary.Results = append(summary.Results, result)
+            continue
+        }
+
+        body := buildCreateBody(ctx, input, template, tags)
+        env, err := ctx.CallAPI("POST", v1RepoPath(ctx)+"/issues", body)
+        if err != nil {
+            result.Status = "failed"
+            result.Error = err.Error()
+            summary.Failed++
+        } else {
+            result.Status = "created"
+            if data, ok := env.Data.(map[string]interface{}); ok {
+                if num, ok := data["project_issues_index"]; ok {
+                    result.Number = fmt.Sprintf("%v", num)
+                }
+            }
+            summary.Succeeded++
+        }
+        summary.Results = append(summary.Results, result)
+    }
+
+    if err := ctx.OutputData(summary); err != nil {
+        return err
+    }
+    if summary.Failed > 0 {
+        return fmt.Errorf("%d of %d issue(s) failed to create", summary.Failed, summary.Total)
+    }
+    return nil
+}
+```
+
+**执行流程**：
+1. 解析仓库信息
+2. 获取项目标签列表
+3. 收集输入（从 `--titles` 和/或 `--from`）
+4. 为没有指定状态的输入应用默认状态
+5. 遍历创建每个 Issue：
+   - 如果是 dry-run，标记为 planned
+   - 否则构建请求体并调用 API
+   - 从响应中提取新创建的 Issue 编号
+6. 输出汇总结果
+
+---
+
+## 七、buildCreateBody 函数
+
+```go
+func buildCreateBody(ctx *common.RuntimeContext, input createIssueInput, template string, tags map[string]int) map[string]interface{} {
+    statusID := statusNew
+    if input.Status != "" {
+        if sid, err := parseStatus(input.Status); err == nil {
+            statusID = sid
+        }
+    }
+    body := map[string]interface{}{
+        "subject":     input.Title,
+        "status_id":   statusID,
+        "priority_id": priorityNormal,
+        "done_ratio":  0,
+    }
+
+    if template != "" {
+        body["description"] = buildTemplateDescription(input, template)
+        if template == "bug" {
+            body["issue_tag_ids"] = []interface{}{tags["缺陷"]}
+        } else if template == "feature" {
+            body["issue_tag_ids"] = []interface{}{tags["功能"]}
+        }
+    } else if input.Body != "" {
+        body["description"] = input.Body
+    }
+
+    if input.Priority != "" {
+        if pid, err := parsePriority(input.Priority); err == nil {
+            body["priority_id"] = pid
+        }
+    }
+    if input.Label != "" {
+        if tid, err := parseLabel(input.Label, tags); err == nil {
+            body["issue_tag_ids"] = []interface{}{tid}
+        }
+    }
+    if input.Assignee != "" {
+        if id, err := resolveUserID(ctx, input.Assignee); err == nil {
+            body["assigner_ids"] = []interface{}{id}
+        }
+    }
+
+    return body
+}
+```
+
+**功能**：构建创建 Issue 的请求体
+
+**逻辑**：
+1. 设置默认值（状态、优先级、完成比例）
+2. 如果指定了模板，构建模板描述并设置对应的标签
+3. 否则使用自定义描述
+4. 应用优先级、标签、分配人等可选参数
+
+---
+
+## 八、模板描述构建
+
+### 8.1 buildTemplateDescription
+
+```go
+func buildTemplateDescription(input createIssueInput, template string) string {
+    switch template {
+    case "bug":
+        return buildBugDescription(input)
+    case "feature":
+        return buildFeatureDescription(input)
+    default:
+        return input.Body
+    }
+}
+```
+
+### 8.2 buildBugDescription
+
+```go
+func buildBugDescription(input createIssueInput) string {
+    var b strings.Builder
+    b.WriteString("## Bug 描述\n")
+    b.WriteString(input.Title)
+    b.WriteString("\n")
+
+    if input.Version != "" {
+        b.WriteString("\n## 版本\n")
+        b.WriteString(input.Version)
+    }
+    if input.Severity != "" {
+        b.WriteString("\n## 严重程度\n")
+        b.WriteString(input.Severity)
+    }
+    if input.Steps != "" {
+        b.WriteString("\n## 复现步骤\n")
+        b.WriteString(input.Steps)
+    }
+    if input.Expected != "" {
+        b.WriteString("\n## 期望结果\n")
+        b.WriteString(input.Expected)
+    }
+    if input.Actual != "" {
+        b.WriteString("\n## 实际结果\n")
+        b.WriteString(input.Actual)
+    }
+    return b.String()
+}
+```
+
+**功能**：构建标准化的 Bug 描述
+
+**输出格式**：
+```markdown
+## Bug 描述
+标题内容
+
+## 版本
+v1.0.0
+
+## 严重程度
+高
+
+## 复现步骤
+步骤1
+步骤2
+
+## 期望结果
+期望的行为
+
+## 实际结果
+实际的行为
+```
+
+### 8.3 buildFeatureDescription
+
+```go
+func buildFeatureDescription(input createIssueInput) string {
+    var b strings.Builder
+    b.WriteString("## 用户故事\n")
+    if input.UserStory != "" {
+        b.WriteString(input.UserStory)
+    } else {
+        b.WriteString(input.Title)
+    }
+
+    if input.Body != "" {
+        b.WriteString("\n## 描述\n")
+        b.WriteString(input.Body)
+    }
+    if input.Acceptance != "" {
+        b.WriteString("\n## 验收标准\n")
+        b.WriteString(input.Acceptance)
+    }
+    if input.Priority != "" {
+        b.WriteString("\n## 优先级\n")
+        b.WriteString(input.Priority)
+    }
+    return b.String()
+}
+```
+
+**功能**：构建标准化的 Feature 描述
+
+**输出格式**：
+```markdown
+## 用户故事
+作为用户，我想...
+
+## 描述
+详细描述
+
+## 验收标准
+- 标准1
+- 标准2
+
+## 优先级
+high
+```
+
+---
+
+## 九、CSV 读取
+
+```go
+func readCreateInputsFromCSV(path string, template string) ([]createIssueInput, error) {
+    file, err := os.Open(path)
+    if err != nil {
+        return nil, fmt.Errorf("read CSV: %w", err)
+    }
+    defer file.Close()
+
+    reader := csv.NewReader(file)
+    reader.TrimLeadingSpace = true
+    records, err := reader.ReadAll()
+    if err != nil {
+        return nil, fmt.Errorf("parse CSV: %w", err)
+    }
+    if len(records) < 2 {
+        return nil, fmt.Errorf("CSV must have a header row and at least one data row")
+    }
+
+    header := records[0]
+    col := make(map[string]int)
+    for i, h := range header {
+        col[normalizeHeader(h)] = i
+    }
+
+    if _, ok := col["title"]; !ok {
+        return nil, fmt.Errorf("CSV must have a 'title' column")
+    }
+
+    var inputs []createIssueInput
+    for _, record := range records[1:] {
+        input := createIssueInput{
+            Title:    getCol(record, col, "title"),
+            Body:     getCol(record, col, "body"),
+            Priority: getCol(record, col, "priority"),
+            Label:    getCol(record, col, "label"),
+            Assignee: getCol(record, col, "assignee"),
+            Status:   getCol(record, col, "status"),
+            Version:  getCol(record, col, "version"),
+            Severity: getCol(record, col, "severity"),
+            Steps:    getCol(record, col, "steps"),
+            Expected: getCol(record, col, "expected"),
+            Actual:   getCol(record, col, "actual"),
+            UserStory:  getCol(record, col, "user_story"),
+            Acceptance: getCol(record, col, "acceptance"),
+        }
+        if input.UserStory == "" {
+            input.UserStory = getCol(record, col, "user story")
+        }
+        if input.Title == "" {
+            continue
+        }
+        inputs = append(inputs, input)
+    }
+    return inputs, nil
+}
+```
+
+**CSV 列支持**：
+- `title`（必填）：Issue 标题
+- `body`：描述内容
+- `priority`：优先级
+- `label`：标签
+- `assignee`：分配人
+- `status`：状态
+- `version`：版本（bug 模板）
+- `severity`：严重程度（bug 模板）
+- `steps`：复现步骤（bug 模板）
+- `expected`：期望结果（bug 模板）
+- `actual`：实际结果（bug 模板）
+- `user_story` / `user story`：用户故事（feature 模板）
+- `acceptance`：验收标准（feature 模板）
+
+---
+
+## 十、辅助函数
+
+### 10.1 parseTitles
+
+```go
+func parseTitles(titlesStr string, ctx *common.RuntimeContext) []createIssueInput {
+    parts := strings.Split(titlesStr, ",")
+    inputs := make([]createIssueInput, 0, len(parts))
+    for _, title := range parts {
+        title = strings.TrimSpace(title)
+        if title == "" {
+            continue
+        }
+        inputs = append(inputs, createIssueInput{
+            Title:    title,
+            Priority: ctx.Arg("priority"),
+            Label:    ctx.Arg("label"),
+            Assignee: ctx.Arg("assignee"),
+            Status:   ctx.Arg("state"),
+        })
+    }
+    return inputs
+}
+```
+
+**功能**：从逗号分隔的标题字符串创建输入对象
+
+### 10.2 normalizeHeader
+
+```go
+func normalizeHeader(h string) string {
+    return strings.ToLower(strings.TrimSpace(h))
+}
+```
+
+**功能**：标准化 CSV 表头（转小写、去空格）
+
+### 10.3 getCol
+
+```go
+func getCol(record []string, col map[string]int, name string) string {
+    if idx, ok := col[name]; ok && idx < len(record) {
+        return strings.TrimSpace(record[idx])
+    }
+    return ""
+}
+```
+
+**功能**：从 CSV 记录中获取指定列的值
+
+### 10.4 truncate
+
+```go
+func truncate(s string, n int) string {
+    runes := []rune(s)
+    if len(runes) <= n {
+        return s
+    }
+    return string(runes[:n]) + "..."
+}
+```
+
+**功能**：截断字符串到指定长度，超出部分用 `...` 表示
+
+**注意**：使用 `[]rune` 处理，可以正确处理中文等多字节字符
+
+---
+
+## 十一、Go 语言知识点
+
+### 1. sync.Map
+
+```go
+var issueTagCache sync.Map
+
+// 读取
+if cached, ok := issueTagCache.Load(key); ok {
+    return cached.(map[string]int), nil
+}
+
+// 写入
+issueTagCache.Store(key, tags)
+```
+
+**作用**：并发安全的 map，用于多个 goroutine 同时读写
+
+### 2. strings.Builder
+
+```go
+var b strings.Builder
+b.WriteString("## Bug 描述\n")
+b.WriteString(input.Title)
+return b.String()
+```
+
+**作用**：高效拼接字符串，避免产生大量临时字符串
+
+### 3. []interface{}
+
+```go
+body["issue_tag_ids"] = []interface{}{tags["缺陷"]}
+```
+
+**作用**：创建一个包含任意类型的数组，用于 JSON 序列化
+
+### 4. switch 类型断言
+
+```go
+switch v := tag["id"].(type) {
+case float64:
+    id = int(v)
+case int:
+    id = v
+default:
+    id, _ = strconv.Atoi(fmt.Sprintf("%v", v))
+}
+```
+
+**作用**：根据值的实际类型执行不同的处理逻辑
+
+### 5. 可变参数
+
+```go
+inputs = append(inputs, parseTitles(titlesStr, ctx)...)
+```
+
+`...` 表示把切片展开成多个参数
--- a/doc/reading_notes/07_repo_batch_create.md
+++ b/doc/reading_notes/07_repo_batch_create.md
@ -0,0 +1,405 @@
+# 逐行讲解 shortcuts/repo/batch_create.go（面向 Go 小白）
+
+## 文件概述
+
+这个文件实现了 **仓库批量创建**功能，可以从命令行或 CSV 文件批量创建多个 GitLink 仓库。
+
+---
+
+## 一、包声明和导入
+
+```go
+package repo
+
+import (
+    "encoding/csv"
+    "fmt"
+    "os"
+    "strings"
+
+    "github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+```
+
+| 导入库 | 作用 |
+|-------|------|
+| `encoding/csv` | CSV 文件解析 |
+| `fmt` | 格式化输出 |
+| `os` | 文件操作 |
+| `strings` | 字符串处理 |
+| `common` | 公共工具包 |
+
+---
+
+## 二、结构体定义
+
+### 2.1 repoCreateInput
+
+```go
+type repoCreateInput struct {
+    Name        string
+    Description string
+    Private     bool
+}
+```
+
+**作用**：存储创建单个仓库的输入参数
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| `Name` | string | 仓库名称 |
+| `Description` | string | 仓库描述 |
+| `Private` | bool | 是否私有仓库 |
+
+### 2.2 repoBatchResult
+
+```go
+type repoBatchResult struct {
+    Name   string `json:"name" yaml:"name"`
+    Status string `json:"status" yaml:"status"`
+    Error  string `json:"error,omitempty" yaml:"error,omitempty"`
+}
+```
+
+**作用**：存储单个仓库创建的结果
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| `Name` | string | 仓库名称 |
+| `Status` | string | 创建状态（planned/created/failed） |
+| `Error` | string | 错误信息（如果失败） |
+
+### 2.3 repoBatchSummary
+
+```go
+type repoBatchSummary struct {
+    Owner     string            `json:"owner" yaml:"owner"`
+    Action    string            `json:"action" yaml:"action"`
+    DryRun    bool              `json:"dry_run" yaml:"dry_run"`
+    Total     int               `json:"total" yaml:"total"`
+    Succeeded int               `json:"succeeded" yaml:"succeeded"`
+    Failed    int               `json:"failed" yaml:"failed"`
+    Results   []repoBatchResult `json:"results" yaml:"results"`
+}
+```
+
+**作用**：存储批量创建的汇总结果
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| `Owner` | string | 仓库所有者（用户名） |
+| `Action` | string | 操作类型（create） |
+| `DryRun` | bool | 是否是预览模式 |
+| `Total` | int | 总数量 |
+| `Succeeded` | int | 成功数量 |
+| `Failed` | int | 失败数量 |
+| `Results` | []repoBatchResult | 每个仓库的详细结果 |
+
+---
+
+## 三、命令定义
+
+```go
+func newBatchCreateShortcut() *common.Shortcut {
+    return &common.Shortcut{
+        Name:        "batch-create",
+        Description: "Create multiple repositories from CLI flags or a CSV file",
+        Flags: []common.Flag{
+            {Name: "names", Short: "n", Usage: "Comma-separated repository names"},
+            {Name: "from", Usage: "CSV file path"},
+            {Name: "description", Short: "d", Usage: "Shared description for all repos"},
+            {Name: "private", Usage: "Make repos private", Bool: true, Default: "false"},
+            {Name: "dry-run", Usage: "Preview without creating", Bool: true, Default: "false"},
+        },
+        Run: runBatchCreate,
+    }
+}
+```
+
+**Flags 参数说明**：
+- `--names/-n`：逗号分隔的仓库名称
+- `--from`：CSV 文件路径
+- `--description/-d`：所有仓库共享的描述
+- `--private`：创建私有仓库
+- `--dry-run`：预览模式
+
+---
+
+## 四、runBatchCreate 主函数
+
+```go
+func runBatchCreate(ctx *common.RuntimeContext) error {
+    var inputs []repoCreateInput
+
+    if namesStr := ctx.Arg("names"); namesStr != "" {
+        for _, name := range strings.Split(namesStr, ",") {
+            name = strings.TrimSpace(name)
+            if name == "" {
+                continue
+            }
+            inputs = append(inputs, repoCreateInput{
+                Name:        name,
+                Description: ctx.Arg("description"),
+                Private:     ctx.Arg("private") == "true",
+            })
+        }
+    }
+
+    if csvPath := ctx.Arg("from"); csvPath != "" {
+        csvInputs, err := readRepoInputsFromCSV(csvPath)
+        if err != nil {
+            return err
+        }
+        inputs = append(inputs, csvInputs...)
+    }
+
+    if len(inputs) == 0 {
+        return fmt.Errorf("no repository names provided")
+    }
+
+    dryRun := ctx.Arg("dry-run") == "true"
+
+    var login string
+    var userID int
+    if !dryRun {
+        userEnv, err := ctx.CallAPI("GET", "/users/me", nil)
+        if err != nil {
+            return fmt.Errorf("failed to get current user: %w", err)
+        }
+        userData, _ := userEnv.Data.(map[string]interface{})
+        login, _ = userData["login"].(string)
+        if login == "" {
+            return fmt.Errorf("cannot determine current user login")
+        }
+        if uid, ok := userData["user_id"].(float64); ok {
+            userID = int(uid)
+        }
+    }
+
+    summary := repoBatchSummary{
+        Owner:   login,
+        Action:  "create",
+        DryRun:  dryRun,
+        Total:   len(inputs),
+        Results: make([]repoBatchResult, 0, len(inputs)),
+    }
+
+    for _, input := range inputs {
+        result := repoBatchResult{Name: input.Name}
+        if dryRun {
+            result.Status = "planned"
+            summary.Succeeded++
+            summary.Results = append(summary.Results, result)
+            continue
+        }
+
+        body := map[string]interface{}{
+            "name":            input.Name,
+            "repository_name": input.Name,
+            "user_id":         userID,
+        }
+        if input.Description != "" {
+            body["description"] = input.Description
+        }
+        if input.Private {
+            body["private"] = true
+        }
+
+        if _, err := ctx.CallAPI("POST", fmt.Sprintf("/%s/%s", login, input.Name), body); err != nil {
+            result.Status = "failed"
+            result.Error = err.Error()
+            summary.Failed++
+        } else {
+            result.Status = "created"
+            summary.Succeeded++
+        }
+        summary.Results = append(summary.Results, result)
+    }
+
+    if err := ctx.OutputData(summary); err != nil {
+        return err
+    }
+    if summary.Failed > 0 {
+        return fmt.Errorf("%d of %d repo(s) failed to create", summary.Failed, summary.Total)
+    }
+    return nil
+}
+```
+
+**执行流程**：
+1. 收集输入（从 `--names` 和/或 `--from`）
+2. 如果不是 dry-run，调用 `/users/me` 获取当前用户信息
+3. 初始化汇总对象
+4. 遍历每个仓库：
+   - 如果是 dry-run，标记为 planned
+   - 否则构建请求体并调用 API
+   - 记录结果
+5. 输出汇总结果
+
+---
+
+## 五、readRepoInputsFromCSV 函数
+
+```go
+func readRepoInputsFromCSV(path string) ([]repoCreateInput, error) {
+    file, err := os.Open(path)
+    if err != nil {
+        return nil, fmt.Errorf("read CSV: %w", err)
+    }
+    defer file.Close()
+
+    reader := csv.NewReader(file)
+    reader.TrimLeadingSpace = true
+    records, err := reader.ReadAll()
+    if err != nil {
+        return nil, fmt.Errorf("parse CSV: %w", err)
+    }
+    if len(records) < 2 {
+        return nil, fmt.Errorf("CSV must have a header row and at least one data row")
+    }
+
+    header := records[0]
+    col := make(map[string]int)
+    for i, h := range header {
+        col[strings.ToLower(strings.TrimSpace(h))] = i
+    }
+    if _, ok := col["name"]; !ok {
+        return nil, fmt.Errorf("CSV must have a 'name' column")
+    }
+
+    var inputs []repoCreateInput
+    for _, record := range records[1:] {
+        name := getCol(record, col, "name")
+        if name == "" {
+            continue
+        }
+        private := false
+        if p := strings.ToLower(getCol(record, col, "private")); p == "true" || p == "1" {
+            private = true
+        }
+        inputs = append(inputs, repoCreateInput{
+            Name:        name,
+            Description: getCol(record, col, "description"),
+            Private:     private,
+        })
+    }
+    return inputs, nil
+}
+```
+
+**CSV 列支持**：
+- `name`（必填）：仓库名称
+- `description`：仓库描述
+- `private`：是否私有（true/false 或 1/0）
+
+---
+
+## 六、getCol 函数
+
+```go
+func getCol(record []string, col map[string]int, name string) string {
+    if idx, ok := col[name]; ok && idx < len(record) {
+        return strings.TrimSpace(record[idx])
+    }
+    return ""
+}
+```
+
+**功能**：从 CSV 记录中获取指定列的值
+
+**逻辑**：
+1. 查找列名对应的索引
+2. 检查索引是否有效
+3. 返回该位置的值（去除前后空格）
+4. 如果找不到，返回空字符串
+
+---
+
+## 七、完整调用流程
+
+```
+用户命令 (gitlink repo batch-create -n repo-a,repo-b)
+    ↓
+解析命令行参数
+    ↓
+newBatchCreateShortcut() 返回命令定义
+    ↓
+执行 runBatchCreate 函数
+    ↓
+收集输入（解析 --names 参数）
+    ↓
+调用 /users/me 获取当前用户信息
+    ↓
+遍历每个仓库名称：
+    ↓
+构建请求体（name, repository_name, user_id）
+    ↓
+调用 POST /{login}/{repo_name} 创建仓库
+    ↓
+记录创建结果
+    ↓
+输出汇总结果
+```
+
+---
+
+## 八、Go 语言知识点
+
+### 1. 结构体标签（Struct Tags）
+
+```go
+type repoBatchResult struct {
+    Name   string `json:"name" yaml:"name"`
+    Status string `json:"status" yaml:"status"`
+    Error  string `json:"error,omitempty" yaml:"error,omitempty"`
+}
+```
+
+**作用**：告诉序列化库（如 JSON、YAML）如何给字段命名
+
+- `json:"name"`：JSON 序列化时使用 `name` 作为字段名
+- `json:"error,omitempty"`：如果 `Error` 为空，JSON 中不包含这个字段
+
+### 2. 布尔值判断
+
+```go
+dryRun := ctx.Arg("dry-run") == "true"
+```
+
+**注意**：`ctx.Arg()` 返回的是字符串，需要和字符串 `"true"` 比较，不能直接用 `bool()` 转换
+
+### 3. interface{} 类型断言
+
+```go
+userData, _ := userEnv.Data.(map[string]interface{})
+login, _ = userData["login"].(string)
+```
+
+**作用**：把 `interface{}` 类型转换成具体类型
+
+### 4. float64 转 int
+
+```go
+if uid, ok := userData["user_id"].(float64); ok {
+    userID = int(uid)
+}
+```
+
+**原因**：JSON 解析后，数字默认是 `float64` 类型，需要手动转换成 `int`
+
+### 5. defer 语句
+
+```go
+file, err := os.Open(path)
+defer file.Close()
+```
+
+**作用**：确保文件在函数返回前被关闭，防止资源泄漏
+
+### 6. make 和预分配容量
+
+```go
+Results: make([]repoBatchResult, 0, len(inputs))
+```
+
+**作用**：创建一个初始长度为 0、容量为 `len(inputs)` 的切片，避免动态扩容的性能开销
--- a/doc/reading_notes/1.txt
+++ b/doc/reading_notes/1.txt
@ -0,0 +1,83 @@
+ ctx 就是 *common.RuntimeContext。一句话：它是每个 Shortcut
+  命令的"工具箱"，所有能力（发API请求、读参数、输出结果）都挂在这个对象上。
+
+  ---
+  它长什么样（shortcuts/common/types.go:41-50）
+
+  type RuntimeContext struct {
+      Client            *client.Client   // ← 发 HTTP 请求的客户端
+      Owner             string           // ← --owner 的值（如 "zzx-coder"）
+      Repo              string           // ← --repo 的值（如 "gitlink-cli"）
+      Format            string           // ← --format 的值（"json" / "table" / "yaml"）
+      CommandName       string           // ← 当前命令名（如 "wiki +delete"）
+      Args              map[string]string // ← 所有 flag 的键值对（如 {"title":"Home","dry-run":"false"}）
+      GatewayBaseURL    string           // ← Wiki/Webhook网关地址（跟标准API不同）
+      GatewayHTTPClient *http.Client     // ← 网关专用 HTTP 客户端（nil 则自动创建）
+  }
+
+  ---
+  它怎么创建出来的（types.go:53-80）
+  你敲 gitlink-cli wiki +delete --title "Home" 时：
+
+  第1步：cobra 解析命令行 → flagValues = {"title": "Home"}
+  第2步：runner.go:34 → NewRuntimeContext(flagValues, "wiki +delete")
+  第3步：NewRuntimeContext 内部：
+      → client.New()           // 读取配置文件，拿到 BaseURL + 带 auth 的 HTTP Client
+      → 读取全局 flag          // cmdutil.Owner, cmdutil.Repo, cmdutil.Format
+      → 组装成 RuntimeContext  // 把所有东西塞进去
+  第4步：传给 s.Run(ctx)       // 你的业务逻辑拿到这个 ctx
+
+  ---
+  它上面的方法（你可以直接用 ctx.XXX() 调用的）
+
+  ┌──────────────────────────────────────┬───────────────────────────────────┬──────────────────────────────────────┐
+  │                 方法                 │              做什么               │                  例                  │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.Arg("title")                     │ 读用户传入的 flag 值              │ "Home"                               │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.RequireArg("title", "提示")      │ 读必填参数，为空就报 CLIError     │ 同上，但自动校验                     │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.CallAPI("GET", path, body)       │ 调 GitLink 标准 API               │ ctx.CallAPI("GET", "/users/me", nil) │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.CallAPIWithQuery("GET", path,    │ 带查询参数的 API                  │ ctx.CallAPIWithQuery("GET",          │
+  │ query)                               │                                   │ "/issues", q)                        │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.Output(env)                      │ 输出 API 响应（自动选             │ ctx.Output(env)                      │
+  │                                      │ json/table/yaml）                 │                                      │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.OutputData(data)                 │ 包装数据成成功 envelope 再输出    │ ctx.OutputData(myStruct)             │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.ResolveOwnerRepo()               │ 从 git remote 自动推断 owner/repo │ 没传 --owner 时自动填充              │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.RepoPath()                       │ 返回 "/owner/repo" 字符串         │ "/zzx-coder/gitlink-cli"             │
+  ├──────────────────────────────────────┼───────────────────────────────────┼──────────────────────────────────────┤
+  │ ctx.IsDryRun()                       │ 判断用户是否传了 --dry-run        │ true / false                         │
+  └──────────────────────────────────────┴───────────────────────────────────┴──────────────────────────────────────┘
+
+  ---
+  一条命令里 ctx 的完整生命周期
+
+  以 wiki +delete --title "Home" 为例：
+
+  1. runner.go:20-31 收集 flag
+     flagValues = {"title": "Home"}
+
+  2. runner.go:34 创建 ctx
+     ctx = NewRuntimeContext({"title":"Home"}, "wiki +delete")
+     → ctx.Client    = 带认证的HTTP客户端（BaseURL = https://gitlink.org.cn/api）
+     → ctx.Owner     = "zzx-coder"（从 git remote 或 --owner 来的）
+     → ctx.Repo      = "gitlink-cli"
+     → ctx.Format    = "table"（默认值）
+     → ctx.Args      = {"title": "Home"}
+
+  3. runner.go:60 调用你的业务逻辑
+     err = s.Run(ctx)
+
+  4. wiki.go:747 你的 Run 函数里用 ctx
+     title, _ = ctx.RequireArg("title", ...)    // → "Home"
+     projectID, _ = resolveProjectID(ctx)       // → ctx 传进子函数
+     body = {..., "pageName": actualPageName}
+     callWikiAPI(ctx, "DELETE", ..., body)      // → ctx 用于构造网关 Client
+     ctx.OutputData(result)                     // → ctx.Format 决定输出格式
+
+  ---
--- a/doc/代码逻辑.md
+++ b/doc/代码逻辑.md
@ -0,0 +1,787 @@
+# gitlink-cli 子任务一代码逻辑说明
+
+## ? 目录
+
+- [系统架构概述](#系统架构概述)
+- [Wiki 管理功能](#wiki-管理功能)
+- [Webhook 管理功能](#webhook-管理功能)
+- [批量操作功能](#批量操作功能)
+- [Raw API 功能](#raw-api-功能)
+- [命令优化功能](#命令优化功能)
+- [跨平台兼容性](#跨平台兼容性)
+
+## ?? 系统架构概述
+
+### 核心设计模式
+
+**Shortcut 架构模式**:
+- 每个功能模块（wiki、webhook、issue等）实现一个 `Shortcuts()` 函数
+- 返回 `[]*common.Shortcut` 切片，每个 Shortcut 代表一个命令
+- 命令执行通过 `Run: func(ctx *common.RuntimeContext) error` 实现
+
+**RuntimeContext 上下文**:
+```go
+type RuntimeContext struct {
+    Client *client.Client    // HTTP 客户端
+    Owner  string            // 仓库所有者
+    Repo   string            // 仓库名称
+    Format string            // 输出格式 (json/table/yaml)
+    Args   map[string]string  // 命令行参数
+}
+```
+
+**API 调用流程**:
+1. `ctx.ResolveOwnerRepo()` - 解析 owner/repo（支持 git remote 自动解析）
+2. `ctx.CallAPI()` - 发送 HTTP 请求到 GitLink API
+3. `ctx.Output()` - 格式化输出结果
+
+---
+
+## ? Wiki 管理功能
+
+### 核心架构
+
+**双重 API 调用机制**:
+- `BaseURL`: `https://www.gitlink.org.cn/api` - 主 API（获取项目信息）
+- `GatewayBaseURL`: `https://gateway.gitlink.org.cn/api` - Gateway API（Wiki 操作）
+
+### 关键代码逻辑
+
+#### 1. Project ID 解析机制 (`resolveProjectID`)
+
+**问题**: Wiki API 需要 `projectId` 数字 ID，而用户只知道 `owner/repo`
+
+**解决方案**:
+```go
+func resolveProjectID(ctx *common.RuntimeContext) (string, error) {
+    key := ctx.Owner + "/" + ctx.Repo
+    
+    // 1. 检查缓存 (sync.Map 实现线程安全)
+    if cached, ok := projectIDCache.Load(key); ok {
+        return cached.(string), nil
+    }
+    
+    // 2. 调用主 API 获取项目详情
+    path := fmt.Sprintf("/%s/%s/detail", ctx.Owner, ctx.Repo)
+    env, err := ctx.CallAPI("GET", path, nil)
+    
+    // 3. 提取 project_id 并缓存
+    projectIDCache.Store(key, pidStr)
+    return pidStr, nil
+}
+```
+
+#### 2. Base64 编解码处理
+
+**Wiki 内容编码**:
+```go
+// 创建 Wiki 时编码
+body["content_base64"] = base64.StdEncoding.EncodeToString([]byte(content))
+
+// 查看 Wiki 时解码
+if b64, ok := data["content_base64"].(string); ok {
+    decoded, err := base64.StdEncoding.DecodeString(b64)
+    data["content_decoded"] = string(decoded)  // 额外提供解码后的内容
+}
+```
+
+#### 3. Wiki 更新策略 (`update` 命令)
+
+**三种更新模式**:
+```go
+if coverText != "" || filePath != "" && coverText == "" && addText == "" {
+    // --cover 或 --file: 完全覆盖内容
+    finalContent = content
+} else if addText != "" {
+    // --add: 追加到现有内容
+    existing, err := fetchPageContent(ctx, projectID, pageName)
+    finalContent = existing + newPart
+}
+```
+
+#### 4. 删除验证机制
+
+**问题**: API 删除操作可能返回错误但实际删除成功
+
+**解决方案**:
+```go
+delErr := callWikiAPI(ctx, "DELETE", wikiPath("deleteWiki"), body)
+if delErr != nil {
+    // 验证是否真的删除成功
+    _, viewErr := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
+    if viewErr != nil {
+        // GET 也失败，说明已删除成功
+        return ctx.OutputData(map[string]string{"message": "Wiki page deleted successfully"})
+    }
+    return delErr  // GET 成功，说明删除确实失败
+}
+```
+
+### API 路径设计
+
+| 命令 | HTTP 方法 | Gateway API 路径 |
+|------|----------|-----------------|
+| list | GET | `/wiki/open/wikiPages` |
+| view | GET | `/wiki/open/getWiki` |
+| create | POST | `/wiki/open/createWiki` |
+| update | PUT | `/wiki/open/updateWiki` |
+| delete | DELETE | `/wiki/open/deleteWiki` |
+
+---
+
+## ? Webhook 管理功能
+
+### 核心设计
+
+**统一的 API 路径前缀**:
+```go
+func webhookRepoPath(ctx *common.RuntimeContext) string {
+    return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+}
+```
+
+### 关键代码逻辑
+
+#### 1. 事件类型管理
+
+**支持的事件列表**:
+```go
+var supportedEvents = []string{
+    "push", "pull_request", "issue", "issue_assign", "issue_comment",
+    "pull_request_assign", "pull_request_comment", "merge_request",
+    "repository", "branch", "tag",
+}
+
+// 事件解析和验证
+func parseEvents(eventsStr string) []string {
+    events := strings.Split(eventsStr, ",")
+    for _, event := range events {
+        if isEventSupported(event) {
+            validEvents = append(validEvents, event)
+        }
+    }
+    return validEvents
+}
+```
+
+#### 2. Webhook 创建逻辑
+
+**完整的 Payload 构造**:
+```go
+payload := map[string]interface{}{
+    "url":          webhookURL,        // 必需
+    "http_method":  "POST",            // 固定
+    "active":       true,              // 默认激活
+    "content_type": "json",            // 默认 JSON
+    "events":       validEvents,       // 事件列表
+}
+
+// 可选字段
+if secret := ctx.Arg("secret"); secret != "" {
+    payload["secret"] = secret  // HMAC 验证密钥
+}
+if description := ctx.Arg("description"); description != "" {
+    payload["description"] = description
+}
+```
+
+#### 3. 智能 URL 获取（Update 命令）
+
+**问题**: 更新 Webhook 时用户不记得当前 URL
+
+**解决方案**:
+```go
+webhookURL := ctx.Arg("url")
+if webhookURL == "" {
+    // 自动获取当前 Webhook 的 URL
+    getEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
+    webhookData := getEnv.Data.(map[string]interface{})
+    currentURL := webhookData["url"].(string)
+    webhookURL = currentURL  // 使用现有 URL
+}
+payload["url"] = webhookURL
+```
+
+#### 4. 删除验证机制
+
+```go
+delErr := ctx.CallAPI("DELETE", webhookPath, nil)
+if delErr != nil {
+    // 验证是否真的删除成功
+    _, viewErr := ctx.CallAPI("GET", webhookPath, nil)
+    if viewErr != nil {
+        // GET 返回错误，说明已删除
+        return ctx.Output(output.SuccessEnvelope(map[string]interface{}{
+            "message": "Webhook deleted successfully",
+        }, nil))
+    }
+    return delErr
+}
+```
+
+#### 5. Test 端点修复
+
+**正确路径**: `/webhooks/{id}/tests` (复数)
+```go
+env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/webhooks/%s/tests", webhookRepoPath(ctx), webhookID), nil)
+```
+
+### API 路径设计
+
+| 命令 | HTTP 方法 | API 路径 |
+|------|----------|---------|
+| list | GET | `/v1/{owner}/{repo}/webhooks` |
+| create | POST | `/v1/{owner}/{repo}/webhooks` |
+| update | PUT | `/v1/{owner}/{repo}/webhooks/{id}` |
+| delete | DELETE | `/v1/{owner}/{repo}/webhooks/{id}` |
+| test | POST | `/v1/{owner}/{repo}/webhooks/{id}/tests` |
+| info | GET | `/v1/{owner}/{repo}/webhooks/{id}` |
+| events | - | (本地静态列表，不调用 API) |
+
+---
+
+## ? 批量操作功能
+
+### 核心设计模式
+
+**统一的结果统计结构**:
+```go
+type BatchSummary struct {
+    Repository string        // 仓库标识
+    Action     string        // 操作类型
+    Value      string        // 操作值
+    DryRun     bool          // 是否预览
+    Total      int           // 总数
+    Succeeded  int           // 成功数
+    Failed     int           // 失败数
+    Results    []BatchResult // 详细结果
+}
+```
+
+### 关键代码逻辑
+
+#### 1. Issue 批量创建 (`batch_create.go`)
+
+**输入源合并**:
+```go
+var inputs []createIssueInput
+
+// 1. 从命令行参数收集
+if titlesStr := ctx.Arg("titles"); titlesStr != "" {
+    inputs = append(inputs, parseTitles(titlesStr, ctx)...)
+}
+
+// 2. 从 CSV 文件收集
+if csvPath := ctx.Arg("from"); csvPath != "" {
+    csvInputs, err := readCreateInputsFromCSV(csvPath, template)
+    inputs = append(inputs, csvInputs...)
+}
+```
+
+**模板支持**:
+```go
+func buildCreateBody(input createIssueInput, template string) map[string]interface{} {
+    if template == "bug" {
+        body["description"] = buildBugDescription(input)
+        body["issue_tag_ids"] = []interface{}{tagIDs["缺陷"]}
+    } else if template == "feature" {
+        body["description"] = buildFeatureDescription(input)
+        body["issue_tag_ids"] = []interface{}{tagIDs["功能"]}
+    }
+}
+```
+
+#### 2. Issue 批量操作 (`batch.go`)
+
+**通用批量操作流程**:
+```go
+func runBatchClose(ctx *common.RuntimeContext) error {
+    // 1. 收集 Issue 编号
+    numbers, err := collectIssueNumbers(ctx.Arg("numbers"), ctx.Arg("from"))
+    
+    // 2. 初始化统计结构
+    summary := BatchSummary{Total: len(numbers)}
+    
+    // 3. 逐个处理
+    for _, number := range numbers {
+        if dryRun {
+            result.Status = "planned"  // 预览模式
+        } else {
+            err := updateIssueField(ctx, number, payload)
+            if err != nil {
+                result.Status = "failed"
+                result.Error = err.Error()
+                summary.Failed++
+            } else {
+                result.Status = "closed"
+                summary.Succeeded++
+            }
+        }
+        summary.Results = append(summary.Results, result)
+    }
+    
+    // 4. 输出统计结果
+    return ctx.OutputData(summary)
+}
+```
+
+#### 3. 仓库批量创建 (`batch_create.go`)
+
+**用户信息获取**:
+```go
+// 获取当前用户信息
+userEnv, err := ctx.CallAPI("GET", "/users/me", nil)
+login := userData["login"].(string)    // 用于 API 路径
+userID := int(userData["user_id"].(float64))  // 用于请求体
+
+// 创建仓库
+body := map[string]interface{}{
+    "name":            repoName,
+    "repository_name": repoName,
+    "user_id":         userID,
+}
+ctx.CallAPI("POST", fmt.Sprintf("/%s/%s", login, repoName), body)
+```
+
+#### 4. CSV 文件处理
+
+**通用 CSV 读取模式**:
+```go
+func readRepoInputsFromCSV(path string) ([]repoCreateInput, error) {
+    file, err := os.Open(path)
+    reader := csv.NewReader(file)
+    records, err := reader.ReadAll()
+    
+    // 1. 解析表头
+    header := records[0]
+    col := make(map[string]int)
+    for i, h := range header {
+        col[strings.ToLower(strings.TrimSpace(h))] = i
+    }
+    
+    // 2. 验证必需列
+    if _, ok := col["name"]; !ok {
+        return nil, fmt.Errorf("CSV must have a 'name' column")
+    }
+    
+    // 3. 读取数据行
+    for _, record := range records[1:] {
+        name := getCol(record, col, "name")
+        inputs = append(inputs, repoCreateInput{Name: name})
+    }
+    return inputs, nil
+}
+```
+
+#### 5. Issue 编号收集
+
+**多源合并**:
+```go
+func collectIssueNumbers(numbersValue, csvPath string) ([]string, error) {
+    // 1. 解析命令行参数
+    numbers, err := parseIssueNumbers(numbersValue)  // "1,2,3" -> []string{"1","2","3"}
+    
+    // 2. 读取 CSV 文件
+    csvNumbers, err := readIssueNumbersFromCSV(csvPath)
+    
+    // 3. 合并去重
+    return mergeIssueNumbers(numbers, csvNumbers)
+}
+```
+
+### 批量操作对比
+
+| 功能 | 输入源 | 特殊处理 |
+|------|--------|----------|
+| repo +batch-create | names CSV | 获取当前用户 login/userID |
+| issue +batch-create | titles CSV | 支持模板 (bug/feature) |
+| issue +batch-close | numbers CSV | 状态 ID 转换 (closed=5) |
+| issue +batch-status | numbers CSV | 状态 ID 转换 |
+| issue +batch-priority | numbers CSV | 优先级 ID 转换 |
+| issue +batch-assign | numbers CSV | 用户名→用户ID解析 |
+| issue +batch-label | numbers CSV | 标签名→标签ID映射 |
+
+---
+
+## ? Raw API 功能
+
+### 核心设计
+
+**统一的 HTTP 客户端**:
+```go
+type Client struct {
+    HTTP           *http.Client
+    BaseURL        string
+    Debug          bool
+    SkipJSONSuffix bool  // Wiki Gateway 不需要 .json 后缀
+}
+```
+
+### 关键代码逻辑
+
+#### 1. 请求路径处理
+
+**自动添加 .json 后缀**:
+```go
+func (c *Client) Do(method, path string, body interface{}, query url.Values) (*output.Envelope, error) {
+    // GitLink API 约定: 所有路径需要 .json 后缀
+    if !c.SkipJSONSuffix {
+        if !strings.HasSuffix(path, ".json") {
+            path += ".json"
+        }
+    }
+    
+    // 构造完整 URL
+    fullURL := c.BaseURL + path
+    if query != nil {
+        fullURL += "?" + query.Encode()
+    }
+    
+    // 发送 HTTP 请求
+    req, _ := http.NewRequest(method, fullURL, bodyReader)
+    resp, _ := c.HTTP.Do(req)
+}
+```
+
+#### 2. 响应解析策略
+
+**多层错误处理**:
+```go
+// 1. HTTP 状态码检查
+if resp.StatusCode >= 400 {
+    return nil, &APIError{
+        StatusCode: resp.StatusCode,
+        Message:    fmt.Sprintf("HTTP %d: %s", resp.StatusCode, body),
+    }
+}
+
+// 2. 解析 JSON 响应
+var raw map[string]interface{}
+json.Unmarshal(respData, &raw)
+
+// 3. GitLink 业务错误检查
+if status, ok := raw["status"]; ok {
+    if statusCode != 0 && statusCode != 200 {
+        msg := raw["message"].(string)
+        suggestion := suggestFix(int(statusCode))  // 智能错误提示
+        return ErrorEnvelope(code, msg, suggestion)
+    }
+}
+
+// 4. 处理 JSON 字符串数据 (GitLink API 特性)
+if dataStr, ok := raw["data"].(string); ok {
+    var parsedData interface{}
+    json.Unmarshal([]byte(dataStr), &parsedData)
+    raw["data"] = parsedData  // 自动解析嵌套 JSON
+}
+```
+
+#### 3. 智能错误提示
+
+```go
+func suggestFix(code int) string {
+    switch code {
+    case 401:
+        return "请先运行 gitlink-cli auth login 登录"
+    case 403:
+        return "权限不足，请确认账户权限或联系项目管理员"
+    case 404:
+        return "资源不存在，请检查 owner/repo/id 是否正确"
+    case 422:
+        return "参数校验失败，请检查请求参数"
+    }
+}
+```
+
+#### 4. HTTP 方法封装
+
+```go
+func (c *Client) Get(path string, query url.Values) (*output.Envelope, error) {
+    return c.Do("GET", path, nil, query)
+}
+
+func (c *Client) Post(path string, body interface{}) (*output.Envelope, error) {
+    return c.Do("POST", path, body, nil)
+}
+
+func (c *Client) Put(path string, body interface{}) (*output.Envelope, error) {
+    return c.Do("PUT", path, body, nil)
+}
+
+func (c *Client) Delete(path string, query url.Values) (*output.Envelope, error) {
+    return c.Do("DELETE", path, nil, query)
+}
+```
+
+### Raw API 使用示例
+
+```bash
+# GET 请求
+./gitlink-cli.exe api GET /users/me
+
+# POST 请求
+./gitlink-cli.exe api POST /zzx-coder/gitlink-cli/issues --body '{"subject":"测试"}'
+
+# PUT 请求
+./gitlink-cli.exe api PUT /zzx-coder/gitlink-cli/issues/123 --body '{"status":"closed"}'
+
+# DELETE 请求
+./gitlink-cli.exe api DELETE /zzx-coder/gitlink-cli/issues/123
+
+# 带查询参数
+./gitlink-cli.exe api GET "/zzx-coder/gitlink-cli/issues" --query "status=open&limit=20"
+```
+
+---
+
+## ? 命令优化功能
+
+### 1. 参数设计优化
+
+**短参数支持**:
+```go
+Flags: []common.Flag{
+    {Name: "title", Short: "t", Usage: "Issue title", Required: true},
+    {Name: "body", Short: "b", Usage: "Issue description"},
+}
+
+// 用户可以使用:
+// --title "Bug" 或 -t "Bug"
+```
+
+**参数别名和映射**:
+```go
+func parseStatus(state string) (int, error) {
+    switch strings.ToLower(strings.TrimSpace(state)) {
+    case "open":
+        return 1, nil
+    case "closed":
+        return 5, nil
+    case "in-progress", "in_progress", "inprogress":  // 支持多种格式
+        return 2, nil
+    }
+}
+```
+
+### 2. 输出格式优化
+
+**Envelope 结构**:
+```go
+type Envelope struct {
+    OK    bool       // 操作是否成功
+    Data  interface{} // 数据
+    Error *ErrorInfo  // 错误信息
+    Meta  *Meta      // 元数据 (分页等)
+}
+```
+
+**格式化输出**:
+```go
+// JSON 格式
+{
+  "ok": true,
+  "data": {...},
+  "meta": {
+    "total_count": 100,
+    "page": 1,
+    "limit": 20
+  }
+}
+
+// Table 格式 (自动格式化)
+----+-------------------+---------+
+| ID | Title             | Status  |
+----+-------------------+---------+
+| 1  | Bug fix           | open    |
+----+-------------------+---------+
+```
+
+### 3. 错误提示优化
+
+**友好的错误消息**:
+```go
+type ErrorInfo struct {
+    Code       interface{} // 错误代码
+    Message    string      // 错误描述
+    Suggestion string      // 解决建议 (新增)
+}
+
+// 示例:
+{
+  "ok": false,
+  "error": {
+    "code": 401,
+    "message": "Authentication failed",
+    "suggestion": "请先运行 gitlink-cli auth login 登录"
+  }
+}
+```
+
+**智能错误处理**:
+```go
+// Wiki 创建时的错误处理
+if err != nil {
+    if strings.Contains(err.Error(), "404") {
+        return fmt.Errorf("Wiki page not found\n\nSuggestions:\n- Check if the wiki page exists\n- Verify you have the correct permissions\n- Use 'gitlink-cli wiki +list' to see available pages")
+    }
+    return err
+}
+```
+
+### 4. CSV 编码错误提示
+
+```go
+// 批量操作时的编码检查
+if !isUTF8CSV(file) {
+    return fmt.Errorf(`? CSV 文件编码错误
+文件编码不是 UTF-8，当前编码: %s
+
+解决方案:
+1. 使用支持 UTF-8 的编辑器重新保存文件
+2. 或使用以下命令创建 UTF-8 文件:
+   cat > repos.csv << 'EOF'
+   name,description,private
+   test1,测试1,false
+   EOF`, currentEncoding)
+}
+```
+
+---
+
+## ? 跨平台兼容性
+
+### 1. 路径处理
+
+**配置目录解析**:
+```go
+func ConfigDir() string {
+    // 优先使用环境变量
+    if dir := os.Getenv("GITLINK_CONFIG_DIR"); dir != "" {
+        return dir
+    }
+    
+    // 跨平台主目录
+    home, _ := os.UserHomeDir()
+    return filepath.Join(home, ".config", "gitlink-cli")
+}
+
+// Windows: C:\Users\{user}\.config\gitlink-cli
+// Linux/Mac: /home/{user}/.config/gitlink-cli
+```
+
+### 2. Git Remote 解析
+
+**自动解析仓库路径**:
+```go
+// 1. 从 git remote 获取 owner/repo
+gitRemote := "https://gitlink.org.cn/zzx-coder/gitlink-cli.git"
+owner, repo := "zzx-coder", "gitlink-cli"
+
+// 2. 支持多种 remote 格式
+// https://gitlink.org.cn/owner/repo.git
+// git@gitlink.org.cn:owner/repo.git
+// ssh://git@gitlink.org.cn/owner/repo.git
+```
+
+### 3. 字符编码处理
+
+**Base64 编解码**:
+```go
+// Wiki 内容处理 (支持多语言)
+content := "# 中文内容\n\nThis is English."
+encoded := base64.StdEncoding.EncodeToString([]byte(content))
+decoded := base64.StdEncoding.DecodeString(encoded)
+```
+
+**Emoji 支持**:
+```go
+// 支持 Emoji 字符
+title := "? Feature request ?"
+body := "Add emoji support ?"
+```
+
+### 4. 平台特定处理
+
+**文件权限**:
+```go
+// 配置文件权限: 0600 (仅用户可读写)
+os.WriteFile(configPath, data, 0600)
+
+// 目录权限: 0700 (仅用户可访问)
+os.MkdirAll(configDir, 0700)
+```
+
+**二进制文件**:
+```bash
+# Windows: gitlink-cli.exe
+# Linux/Mac: gitlink-cli
+```
+
+---
+
+## ? 数据流程示例
+
+### Issue 创建完整流程
+
+```
+用户输入:
+./gitlink-cli.exe issue +create --owner zzx-coder --repo gitlink-cli --title "Bug" --body "Fix it"
+
+1. 参数解析
+   Args = {"owner": "zzx-coder", "repo": "gitlink-cli", "title": "Bug", "body": "Fix it"}
+
+2. 创建 RuntimeContext
+   ctx = RuntimeContext{
+       Client: httpClient,
+       Owner:  "zzx-coder",
+       Repo:   "gitlink-cli",
+       Format: "json",
+       Args:   Args
+   }
+
+3. API 调用
+   path = "/v1/zzx-coder/gitlink-cli/issues.json"
+   body = {
+       "subject": "Bug",
+       "description": "Fix it",
+       "status_id": 1,
+       "priority_id": 2
+   }
+
+4. HTTP 请求
+   POST https://www.gitlink.org.cn/api/v1/zzx-coder/gitlink-cli/issues.json
+   Authorization: Bearer {token}
+   Content-Type: application/json
+
+5. 响应处理
+   解析 JSON → Envelope{OK: true, Data: {...}}
+
+6. 输出格式化
+   格式化为 JSON/Table → 输出到终端
+```
+
+### Wiki 创建完整流程
+
+```
+用户输入:
+./gitlink-cli.exe wiki +create --owner zzx-coder --repo gitlink-cli --title "Test" --content "# Test"
+
+1. 第一次 API 调用 (获取 Project ID)
+   GET https://www.gitlink.org.cn/api/zzx-coder/gitlink-cli/detail.json
+   响应: {"project_id": 12345}
+
+2. Project ID 缓存
+   projectIDCache.Store("zzx-coder/gitlink-cli", "12345")
+
+3. 第二次 API 调用 (创建 Wiki)
+   POST https://gateway.gitlink.org.cn/api/wiki/open/createWiki
+   body = {
+       "owner": "zzx-coder",
+       "repo": "gitlink-cli",
+       "projectId": 12345,
+       "pageName": "Test",
+       "content_base64": "I1BUV\Q=="  // Base64 编码
+   }
+
+4. Gateway 响应处理
+   解析 {"code": 200, "data": {...}} → 提取 data 部分
--- a/doc/任务一/.claude/settings.local.json
+++ b/doc/任务一/.claude/settings.local.json
@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -c \"import docx; print\\(''ok''\\)\")",
+      "Bash(pip install:*)",
+      "Bash(python generate_report.py)"
+    ]
+  }
+}
--- a/doc/任务一/CLI优化报告.md
+++ b/doc/任务一/CLI优化报告.md
@ -0,0 +1,535 @@
+# GitLink CLI 命令系统优化报告
+
+## 一、参数设计
+
+### 问题：枚举参数无校验，错误信息延迟到 API 调用才暴露
+
+命令 `pr +merge --method` 接受 `merge`、`rebase`、`squash` 三种值，`issue +list --state` 接受 `open`、`closed`、`all`，但输入非法值时没有任何拦截。用户输入 `--method unknown` 会直接发往 API，等到服务端返回 422 才知道参数错了，反馈链路长。
+
+**修改前** — 校验逻辑散落在 Run 函数内部：
+
+```go
+// shortcuts/issue/issue.go
+Flags: []common.Flag{
+    {Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "open"},
+}
+
+// 枚举值定义在 Usage 文本里（给人看），校验在 Run() 里手写（给机器做）
+// 两者没有关联，容易出现文本和代码不同步
+func normalizeIssueStatus(state string) (interface{}, error) {
+    switch strings.ToLower(strings.TrimSpace(state)) {
+    case "open":
+        return 1, nil
+    case "closed":
+        return 5, nil
+    default:
+        if id, err := strconv.Atoi(state); err == nil {
+            return id, nil
+        }
+        return nil, fmt.Errorf("invalid --state %q: use open, closed, or a numeric status_id", state)
+    }
+}
+```
+
+**问题总结**：每个有枚举值的 flag 都需要在 `Run()` 里手写一个 validate 函数，重复劳动且容易遗漏；枚举值在 Usage 文本里写一遍、在代码里再写一遍，两处不同步时有发生。
+
+**解决方案**：在 `Flag` 结构体中增加 `Choices` 字段，框架层在 parse 阶段自动校验，同时将可选值追加到 `--help` 输出。
+
+**修改后**：
+
+```go
+// ① 结构体扩展 — shortcuts/common/types.go
+type Flag struct {
+    Name     string
+    Short    string
+    Usage    string
+    Required bool
+    Default  string
+    Bool     bool
+    Choices  []string                  // 新增：枚举校验
+    Validate func(value string) error  // 新增：自定义校验函数
+}
+
+// ② 框架自动校验 — shortcuts/common/runner.go
+for _, f := range s.Flags {
+    val := getFlagValue(cmd, f)
+    // Choices 枚举校验
+    if len(f.Choices) > 0 && val != "" && val != "false" {
+        if !contains(f.Choices, val) {
+            return clierrors.InputError(
+                fmt.Sprintf("invalid value %q for --%s", val, f.Name),
+                fmt.Sprintf("有效值: %s。运行 'gitlink-cli %s --help' 查看用法。",
+                    strings.Join(f.Choices, ", "), commandName),
+            ).WithCommand(commandName)
+        }
+    }
+    // 自定义校验
+    if f.Validate != nil && val != "" {
+        if err := f.Validate(val); err != nil {
+            return clierrors.InputError(
+                fmt.Sprintf("invalid --%s: %v", f.Name, err),
+                fmt.Sprintf("运行 'gitlink-cli %s --help' 查看用法。", commandName),
+            ).WithCommand(commandName)
+        }
+    }
+}
+
+// ③ 命令行只需声明 Choices — shortcuts/pr/pr.go
+Flags: []common.Flag{
+    {Name: "method", Short: "m", Usage: "Merge method", Default: "merge",
+     Choices: []string{"merge", "rebase", "squash"}},
+}
+```
+
+Choices 声明后，无需再写校验函数，`--help` 也会自动追加 `[merge|rebase|squash]`。
+
+---
+
+### 问题：跨参数约束靠手写 fmt.Errorf，格式不统一
+
+`issue +update` 要求 "至少提供 --title、--body 或 --state 中的一个"；`repo +update` 要求 "至少提供 --description 或 --private 中的一个"。这类跨参数约束都散落在 `Run()` 里用 `fmt.Errorf` 写死，每种错误格式各异、中英文混杂。
+
+**修改前**：
+
+```go
+// shortcuts/issue/issue.go — 在 Run() 内部手写校验
+if title == "" && description == "" && state == "" {
+    return fmt.Errorf("at least one of --title, --body, or --state is required")
+}
+
+// shortcuts/repo/repo.go — 同样手写，格式不同
+if len(body) == 0 {
+    return fmt.Errorf("at least one of --description, --private is required")
+}
+```
+
+**解决方案**：在 `Shortcut` 结构体中增加 `Validate` 字段，支持声明式跨参数校验；同时引入 `clierrors.InputError` 统一错误格式（英文技术消息 + 中文操作建议）。
+
+**修改后**：
+
+```go
+// ① Shortcut 结构体新增 Validate 字段 — shortcuts/common/types.go
+type Shortcut struct {
+    Name        string
+    Description string
+    Flags       []Flag
+    Validate    func(args map[string]string) error  // 新增：跨参数校验
+    Run         func(ctx *RuntimeContext) error
+}
+
+// ② MountShortcut 中自动执行 — shortcuts/common/runner.go
+if s.Validate != nil {
+    if err := s.Validate(flagValues); err != nil {
+        return clierrors.InputError(
+            err.Error(),
+            fmt.Sprintf("运行 'gitlink-cli %s --help' 查看用法。", commandName),
+        ).WithCommand(commandName)
+    }
+}
+
+// ③ 命令中统一使用 InputError — shortcuts/issue/issue.go
+if title == "" && description == "" && state == "" {
+    return clierrors.InputError(
+        "at least one of --title, --body, or --state is required",
+        "至少需要提供 --title、--body 或 --state 中的一个参数",
+    ).WithCommand(ctx.CommandName)
+}
+```
+
+---
+
+## 二、输出格式
+
+### 问题：默认格式与帮助文本不一致
+
+`cmd/root.go` 中 `--format` 帮助文本写明 "default: table"，但 `shortcuts/common/types.go` 中 `NewRuntimeContext` 的代码默认值是 `"json"`。用户不传 `--format` 时拿到的是 JSON 而非表格。
+
+**修改前**：
+
+```go
+// cmd/root.go — 帮助文本说 "default: table"
+rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "",
+    "Output format: json, table, yaml (default: table)")
+
+// shortcuts/common/types.go — 代码实际默认 json
+format := cmdutil.Format
+if format == "" {
+    format = "json"
+}
+```
+
+**解决方案**：将代码默认值改为 `"table"`，同时将 persistent flag 的默认值参数从空字符串改为 `"table"`，让 cobra 显示的默认值与实际行为一致。
+
+**修改后**：
+
+```go
+// cmd/root.go — 默认值显式化为 "table"
+rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "table",
+    "Output format: json, table, yaml")
+
+// shortcuts/common/types.go — 代码默认值与帮助文本一致
+format := cmdutil.Format
+if format == "" {
+    format = "table"
+}
+```
+
+---
+
+### 问题：表格输出无列过滤、长文本被硬截断、无可读性增强
+
+现状：表格渲染时列全量输出、复杂值（JSON 嵌套、长文本）在 60 字符处硬截断后加 `...`、无色彩区分。用户想只看 id + title 两列也要扛着十几列的输出；想看完整描述被 `...` 截断无能为力。
+
+**修改前**：
+
+```go
+// internal/output/formatter.go — 截断硬编码，无列过滤
+func formatValue(v interface{}) string {
+    // ...
+    if len(s) > 60 {
+        return s[:57] + "..."  // 硬截断，不可配置
+    }
+    return s
+}
+
+func Print(envelope *Envelope, format string) error {
+    // 无任何渲染选项
+    return PrintTo(os.Stdout, envelope, format)
+}
+```
+
+**解决方案**：引入 `PrintOptions` 结构体，支持 `Columns`（列过滤）、`NoTruncate`（关闭截断）、`UseColor`（彩色表头）；新增 3 个全局 persistent flag（`--columns`、`--no-truncate`、`--no-color`）；通过 `RuntimeContext` 透明传递到所有输出调用。
+
+**修改后**：
+
+```go
+// ① PrintOptions 结构体 — internal/output/formatter.go
+type PrintOptions struct {
+    Columns    []string // 要显示的列，nil = 全部
+    NoTruncate bool     // 禁用 60 字符截断
+    UseColor   bool     // 启用 ANSI 颜色
+}
+
+func PrintWithOpts(envelope *Envelope, format string, opts PrintOptions) error {
+    // ...
+    case "table":
+        return printTableOpts(w, envelope, opts)  // 传递 opts
+}
+
+// ② 列过滤实现
+func filterColumns(all, wanted []string) []string {
+    wantedSet := make(map[string]bool, len(wanted))
+    for _, w := range wanted { wantedSet[w] = true }
+    result := make([]string, 0, len(wanted))
+    for _, h := range all {
+        if wantedSet[h] { result = append(result, h) }
+    }
+    return result
+}
+
+// ③ 可配置截断
+func formatValueOpts(v interface{}, noTruncate bool) string {
+    if !noTruncate && len(s) > 60 {
+        return s[:57] + "..."
+    }
+    return s
+}
+
+// ④ 彩色表头（仅终端且 --no-color 未设置）
+func isTerminal(w io.Writer) bool {
+    if f, ok := w.(*os.File); ok {
+        return term.IsTerminal(int(f.Fd()))
+    }
+    return false
+}
+
+// ⑤ RuntimeContext 无缝传递 — shortcuts/common/types.go
+func (ctx *RuntimeContext) Output(env *output.Envelope) error {
+    opts := output.PrintOptions{
+        NoTruncate: ctx.NoTruncate,
+        UseColor:   !ctx.NoColor,
+    }
+    if ctx.Columns != "" {
+        // "id,title,state" → []string{"id", "title", "state"}
+        for _, p := range strings.Split(ctx.Columns, ",") {
+            p = strings.TrimSpace(p)
+            if p != "" { opts.Columns = append(opts.Columns, p) }
+        }
+    }
+    return output.PrintWithOpts(env, ctx.Format, opts)
+}
+
+// ⑥ 全局 flag 注册 — cmd/root.go
+rootCmd.PersistentFlags().BoolVar(&cmdutil.NoTruncate, "no-truncate", false,
+    "Disable value truncation in table output")
+rootCmd.PersistentFlags().StringVar(&cmdutil.Columns, "columns", "",
+    "Columns to show in table output (comma-separated)")
+rootCmd.PersistentFlags().BoolVar(&cmdutil.NoColor, "no-color", false,
+    "Disable colored output")
+```
+
+用法：
+
+```
+gitlink-cli issue +list --columns id,subject,status
+gitlink-cli issue +list --no-truncate
+gitlink-cli issue +list --no-color
+```
+
+---
+
+## 三、错误提示
+
+### 问题：中英文混用，fmt.Errorf 不被框架识别
+
+现状：各快捷命令中的错误用 `fmt.Errorf` 随意构造，中文和英文混用。`fmt.Errorf` 生成的错误不是 `CLIError` 类型，不被 `TryPrintError` 识别，只能走 `cmd.Execute` 的 stderr 兜底输出，无法享受 envelope 结构化错误格式。
+
+**修改前** — 同一项目中三种不同风格：
+
+```go
+// 风格 A：中文 — shortcuts/issue/issue.go
+return fmt.Errorf("获取 Issue 列表失败: %w", err)
+return fmt.Errorf("创建 Issue 失败: %w", err)
+
+// 风格 B：英文 — shortcuts/repo/repo.go
+return fmt.Errorf("failed to list members for %s/%s: %w", ctx.Owner, ctx.Repo, err)
+return fmt.Errorf("cannot determine current user login")
+
+// 风格 C：中英混合 — shortcuts/pr/pr.go
+return fmt.Errorf("获取 PR 列表失败: %w", err)
+return fmt.Errorf("添加 PR 评论失败: %w", err)
+```
+
+**问题根源**：没有统一的错误构造入口，开发者各自手写 `fmt.Errorf`。
+
+**解决方案**：新增 `OpError` 构造函数，入参只需动词和资源名，自动生成英文 `Message`（给脚本 / jq 解析）和中文 `Suggestion`（给用户阅读），且返回 `*CLIError` 类型可被框架自动识别为 envelope 格式。
+
+**修改后**：
+
+```go
+// ① 统一构造函数 — internal/errors/errors.go
+func OpError(kind ErrorKind, op, resource string, cause error) *CLIError {
+    msg := fmt.Sprintf("failed to %s %s", op, resource)
+    sugg := opSuggestion(op, resource)
+    return Wrap(kind, msg, sugg, cause)
+}
+
+func opSuggestion(op, resource string) string {
+    suggestions := map[string]string{
+        "list":    "获取列表失败，请检查参数或网络连接，稍后重试",
+        "create":  "创建失败，请检查必填参数是否正确（--help 查看用法）或 API 权限",
+        "view":    "查看失败，请确认资源 ID 是否存在",
+        "update":  "更新失败，请检查参数值或资源 ID 是否正确",
+        "delete":  "删除失败，请确认资源是否存在或是否有删除权限",
+        "close":   "关闭失败，请确认资源是否存在或已被关闭",
+        "merge":   "合并失败，请检查是否有冲突或权限不足",
+        "comment": "添加评论失败，请确认资源是否存在",
+        "fork":    "Fork 失败，请确认仓库存在或有权限",
+        "invite":  "邀请失败，请确认用户 ID 是否正确",
+        "remove":  "移除失败，请确认成员存在",
+    }
+    if s, ok := suggestions[op]; ok { return s }
+    return "操作失败，请稍后重试或运行 --help 查看用法"
+}
+
+// ② 命令中一行调用 — shortcuts/issue/issue.go
+env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
+if err != nil {
+    return clierrors.OpError(clierrors.KindServer, "list", "issues", err).
+        WithCommand(ctx.CommandName)
+}
+
+// ③ 框架自动识别 — shortcuts/common/error_print.go
+// TryPrintError 检测到 *CLIError 类型后自动输出为结构化 JSON：
+var cliErr *clierrors.CLIError
+if errors.As(err, &cliErr) {
+    env := output.ErrorEnvelope(kindToCode(cliErr.Kind), cliErr.Message, cliErr.Suggestion)
+    _ = output.Print(env, format)
+    return true
+}
+```
+
+输出效果：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": 500,
+    "message": "failed to list issues",
+    "suggestion": "获取列表失败，请检查参数或网络连接，稍后重试"
+  }
+}
+```
+
+`message` 用英文保证脚本可解析，`suggestion` 用中文直接给人看。
+
+---
+
+## 四、帮助文档
+
+### 问题：Shortcut 无详细帮助，Group 命令只有一行描述
+
+现状：`Shortcut` 结构体只有 `Description` 一个短描述字段，没有 `Long`（详细说明）和 `Example`（使用示例）。`--help` 输出只有一个命令行和 flag 列表，用户看不到用法示例。
+
+Group 命令（`repo`、`issue`、`pr` 等）同理，15 个 group 全部只有一行 `Short`：
+
+```go
+descriptions := map[string]string{
+    "repo":      "Repository operations",
+    "pr":        "Pull request operations",
+    // 14 个 group 完全一样...
+}
+```
+
+**修改前**：
+
+```go
+// shortcuts/common/types.go — 结构体缺少 Long 和 Example
+type Shortcut struct {
+    Name        string
+    Description string   // 仅此一个描述字段
+    Flags       []Flag
+    Run         func(ctx *RuntimeContext) error
+}
+
+// shortcuts/common/runner.go — cobra 命令只有 Use 和 Short
+cmd := &cobra.Command{
+    Use:   "+" + s.Name,
+    Short: s.Description,
+    RunE:  /* ... */,
+}
+
+// shortcuts/register.go — group 命令也只有 Short
+groupCmd := &cobra.Command{
+    Use:   name,
+    Short: descriptions[name],
+}
+```
+
+**问题总结**：`--help` 输出仅包含一句话描述 + 参数列表，没有用法示例。对于 `pr +merge` 这类参数较多的命令，用户无从得知 `--method` 有哪些可选值、典型调用怎么写。
+
+**解决方案**：`Shortcut` 结构体新增 `Long` 和 `Example` 字段，挂载到 cobra 的 `Long` 和 `Example`；`register.go` 中 15 个 Group 命令全部补充 Long 描述和使用示例；新增 `completion` 子命令支持 4 种 shell 的自动补全。
+
+**修改后**：
+
+```go
+// ① Shortcut 结构体扩展 — shortcuts/common/types.go
+type Shortcut struct {
+    Name        string
+    Description string
+    Long        string   // 新增：详细帮助文本
+    Example     string   // 新增：使用示例
+    Flags       []Flag
+    Run         func(ctx *RuntimeContext) error
+}
+
+// ② MountShortcut 挂载到 cobra — shortcuts/common/runner.go
+cmd := &cobra.Command{
+    Use:     "+" + s.Name,
+    Short:   s.Description,
+    Long:    s.Long,       // 新增
+    Example: s.Example,    // 新增
+    RunE:    /* ... */,
+}
+
+// ③ 命令中填写 — shortcuts/pr/pr.go
+{
+    Name:        "merge",
+    Description: "Merge a pull request",
+    Example:     "  gitlink-cli pr +merge --id 42\n" +
+                 "  gitlink-cli pr +merge --id 42 --method rebase\n" +
+                 "  gitlink-cli pr +merge --id 42 --method squash --dry-run",
+    Flags: []common.Flag{
+        {Name: "id", Short: "i", Usage: "PR number", Required: true},
+        {Name: "method", Short: "m", Usage: "Merge method", Default: "merge",
+         Choices: []string{"merge", "rebase", "squash"}},
+    },
+}
+
+// ④ Group 命令补充 Long 和 Example — shortcuts/register.go
+type groupInfo struct {
+    Short   string
+    Long    string
+    Example string
+}
+
+infos := map[string]groupInfo{
+    "pr": {
+        Short:   "Pull request operations",
+        Long:    "Manage pull requests: list, create, view, merge, close, review, and view changed files.",
+        Example: "  gitlink-cli pr +list --state open\n" +
+                 "  gitlink-cli pr +create --title \"Fix login\" --head feat-branch\n" +
+                 "  gitlink-cli pr +merge --id 42",
+    },
+    // 其余 14 个 group 同上
+}
+
+groupCmd := &cobra.Command{
+    Use:     name,
+    Short:   info.Short,
+    Long:    info.Long,
+    Example: info.Example,
+}
+```
+
+### 问题：无 Shell 自动补全
+
+cobra 框架原生支持 bash/zsh/fish/powershell 的补全生成，但 gitlink-cli 没有暴露这个能力。用户需要记忆 15 个 group 和 80+ 个子命令的完整名称。
+
+**解决方案**：新增 `completion` 子命令。
+
+```go
+// cmd/root.go
+var completionCmd = &cobra.Command{
+    Use:       "completion [bash|zsh|fish|powershell]",
+    Short:     "Generate shell completion script",
+    ValidArgs: []string{"bash", "zsh", "fish", "powershell"},
+    RunE: func(cmd *cobra.Command, args []string) error {
+        shell := "bash"
+        if len(args) > 0 { shell = args[0] }
+        switch shell {
+        case "bash":
+            return cmd.Root().GenBashCompletion(os.Stdout)
+        case "zsh":
+            return cmd.Root().GenZshCompletion(os.Stdout)
+        case "fish":
+            return cmd.Root().GenFishCompletion(os.Stdout, true)
+        case "powershell":
+            return cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
+        default:
+            return fmt.Errorf("unsupported shell: %s (valid: bash, zsh, fish, powershell)", shell)
+        }
+    },
+}
+```
+
+启用：
+
+```bash
+source <(gitlink-cli completion bash)                              # Bash
+source <(gitlink-cli completion zsh)                               # Zsh
+gitlink-cli completion fish | source                                # fish
+gitlink-cli completion powershell | Out-String | Invoke-Expression  # PowerShell
+```
+
+---
+
+## 五、影响范围
+
+| 文件 | 改动性质 |
+|------|----------|
+| `cmd/cmdutil/globals.go` | 新增 NoTruncate / Columns / NoColor 全局变量 |
+| `cmd/root.go` | 新增 3 个 persistent flag + completion 子命令 + format 默认值修正 |
+| `shortcuts/common/types.go` | Shortcut / Flag / RuntimeContext 结构体扩展（6 个新增字段） |
+| `shortcuts/common/runner.go` | Choices/Validate 校验逻辑 + Long/Example 挂载 + Choices→Usage 自动追加 |
+| `internal/output/formatter.go` | PrintOptions + PrintWithOpts + 列过滤 + 去截断 + 彩色表头 |
+| `internal/errors/errors.go` | OpError 统一构造函数 |
+| `shortcuts/register.go` | 15 个 Group 命令补充 Long / Example |
+| `shortcuts/issue/issue.go` | 错误统一 + Choices(state) + Long/Example（list, create, view, close, update） |
+| `shortcuts/pr/pr.go` | 错误统一 + Choices(state, method) + Long/Example（list, create, merge） |
+| `shortcuts/repo/repo.go` | 错误统一 + Choices(category) + Long/Example（list, create, update） |
+
+所有新增字段零值安全，现有 80+ Shortcut 无需修改即可编译。`output.Print()` 签名不变，内部包装为 `PrintWithOpts`。Workflow 脚本显式使用 `--format json`，不受默认格式变化影响。
+
+验证：`go build` 通过，`go vet` 通过（仅 pre-existing milestone 包有构建错误），`go test ./...` 7 个测试包全部通过。
--- a/doc/任务一/board-shortcut-修改笔记.md
+++ b/doc/任务一/board-shortcut-修改笔记.md
@ -0,0 +1,224 @@
+# Board (看板) Shortcut 修改笔记
+
+## 一、功能概述
+
+新增 `board` 快捷命令组，提供项目看板的查看、筛选、任务操作和统计分析功能。
+
+| 命令 | 类型 | 说明 |
+|------|------|------|
+| `board +view` | 读 | 按状态分组显示看板全貌 |
+| `board +columns` | 读 | 列出各状态列及 issue 数量 |
+| `board +issues` | 读 | 按状态/指派人/优先级筛选任务 |
+| `board +move` | 写 | 移动任务状态（支持 dry-run） |
+| `board +assign` | 写 | 指派任务给用户（支持 dry-run） |
+| `board +stats` | 读 | 完成率、工作负载、瓶颈分析 |
+
+---
+
+## 二、解决思路
+
+### 2.1 API 选型
+
+最初计划使用 PM 看板 API (`GET /pm/dashboards?project_id=...`)，但实际测试发现该端点不存在（返回 HTML 页面）。skill 参考文档 `pm-kanban.md` 中的 API 描述有误。
+
+**最终方案**：基于已有的 issue list API (`GET /v1/{owner}/{repo}/issues`) 实现看板视图。每个 issue 带有 `status_id`、`status_name`、`assigners`、`priority` 等字段，按 `status_id` 分组即可构建看板。
+
+### 2.2 看板列设计
+
+按 `status_id` 映射为 5 列：
+
+| status_id | 列名 |
+|-----------|------|
+| 1 | 待处理 |
+| 2 | 进行中 |
+| 3 | 已解决 |
+| 5 | 已关闭 |
+| 6 | 已拒绝 |
+
+### 2.3 写操作复用
+
+`board +move` 和 `board +assign` 复用 issue PATCH API (`PATCH /v1/{owner}/{repo}/issues/{id}`)。关键点：PATCH body 必须包含 `subject` + `description`，否则会被清空。
+
+---
+
+## 三、代码指令
+
+### 3.1 文件变更
+
+```
+新建：shortcuts/board/board.go     # 6 个命令 + 辅助函数（约 580 行）
+修改：shortcuts/register.go        # 添加 board 组的 import + 注册
+```
+
+### 3.2 编译部署
+
+```bash
+# 编译
+cd /c/Users/Lenovo/Desktop/soft运维/gitlink-cli
+go install .
+
+# 同步到 npm（npm shim 调用同目录的 gitlink-cli.exe）
+cp ~/go/bin/gitlink-cli.exe ~/AppData/Roaming/npm/node_modules/@gitlink-ai/cli/bin/gitlink-cli.exe
+```
+
+### 3.3 核心辅助函数
+
+```go
+// fetchAllIssuesWithState — 分页获取所有 issue
+func fetchAllIssuesWithState(ctx *common.RuntimeContext, state string) ([]issueItem, error)
+
+// groupByStatus — 按 status_id 分组
+func groupByStatus(issues []issueItem) map[int][]issueItem
+
+// fetchExistingIssue — 获取 issue 的 subject+description（PATCH 前必须调用）
+func fetchExistingIssue(ctx *common.RuntimeContext, number string) (string, string, error)
+
+// resolveUserID — 用户名转用户 ID（调用 GET /users/{login}）
+func resolveUserID(ctx *common.RuntimeContext, login string) (interface{}, error)
+```
+
+### 3.4 register.go 变更
+
+```go
+// 新增 import
+"github.com/gitlink-org/gitlink-cli/shortcuts/board"
+
+// groups map 新增
+"board": board.Shortcuts(),
+
+// infos map 新增
+"board": {
+    Short:   "Board (kanban) operations",
+    Long:    "View and manage kanban boards: ...",
+    Example: "  gitlink-cli board +view\n  ...",
+},
+```
+
+---
+
+## 四、输出参考
+
+### 4.1 board --help
+
+```
+View and manage kanban boards: view board layout, list columns, filter issues,
+move tasks between columns, assign people, and analyze workload.
+
+Usage:
+  gitlink-cli board [command]
+
+Available Commands:
+  +assign     Assign an issue to someone
+  +columns    List status columns with issue counts
+  +issues     List issues with optional filters
+  +move       Move an issue to a different status
+  +stats      Show board analytics and statistics
+  +view       View kanban board layout
+```
+
+### 4.2 board +view
+
+```json
+{
+  "ok": true,
+  "data": {
+    "repository": "zzx-coder/gitlink-cli",
+    "total_issues": 44,
+    "columns": [
+      {
+        "status_id": 1,
+        "status_name": "待处理",
+        "issue_count": 0,
+        "issues": []
+      },
+      {
+        "status_id": 2,
+        "status_name": "进行中",
+        "issue_count": 0,
+        "issues": []
+      },
+      {
+        "status_id": 3,
+        "status_name": "已解决",
+        "issue_count": 44,
+        "issues": [
+          {"number": 16, "id": 143115, "subject": "fix:增加相关test.go文件", "priority": "normal"},
+          {"number": 25, "id": 143700, "subject": "fix: 统一错误提示优化", "priority": "normal"}
+        ]
+      },
+      {"status_id": 5, "status_name": "已关闭", "issue_count": 0, "issues": []},
+      {"status_id": 6, "status_name": "已拒绝", "issue_count": 0, "issues": []}
+    ]
+  }
+}
+```
+
+### 4.3 board +columns
+
+```json
+{
+  "ok": true,
+  "data": [
+    {"status_id": 1, "status_name": "待处理", "issue_count": 0},
+    {"status_id": 2, "status_name": "进行中", "issue_count": 0},
+    {"status_id": 3, "status_name": "已解决", "issue_count": 44},
+    {"status_id": 5, "status_name": "已关闭", "issue_count": 0},
+    {"status_id": 6, "status_name": "已拒绝", "issue_count": 0}
+  ]
+}
+```
+
+### 4.4 board +issues --status resolved --limit 3
+
+```json
+{
+  "ok": true,
+  "data": [
+    {"number": 16, "id": 143115, "subject": "fix:增加相关test.go文件", "status": "已解决", "priority": "normal", "assigned_to": ""},
+    {"number": 25, "id": 143700, "subject": "fix: 统一错误提示优化", "status": "已解决", "priority": "normal", "assigned_to": ""},
+    {"number": 2, "id": 142700, "subject": "新增issue批量操作", "status": "已解决", "priority": "normal", "assigned_to": ""}
+  ]
+}
+```
+
+### 4.5 board +move --number 16 --status in-progress --dry-run
+
+```
+[dry-run] Move issue #16 to status "in-progress"
+
+Proceed? [y/N] Aborted.
+```
+
+### 4.6 board +stats
+
+```json
+{
+  "ok": true,
+  "data": {
+    "repository": "zzx-coder/gitlink-cli",
+    "total_issues": 44,
+    "completion_rate": 100,
+    "column_breakdown": [
+      {"status_name": "待处理", "count": 0, "percentage": 0},
+      {"status_name": "进行中", "count": 0, "percentage": 0},
+      {"status_name": "已解决", "count": 44, "percentage": 100},
+      {"status_name": "已关闭", "count": 0, "percentage": 0},
+      {"status_name": "已拒绝", "count": 0, "percentage": 0}
+    ],
+    "assignee_load": [
+      {"assignee": "(unassigned)", "count": 44}
+    ],
+    "bottleneck": "已解决"
+  }
+}
+```
+
+---
+
+## 五、踩坑记录
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `unknown command "board"` | npm shim (`cli.js`) 调用的是 npm 包内的 `gitlink-cli.exe`，不是 `go/bin` 的 | 编译后同步覆盖 npm 包内的 exe |
+| `failed to parse dashboard data` | `/pm/dashboards` API 端点不存在，返回 HTML | 改用 issue list API + 客户端分组 |
+| `json: cannot unmarshal string` | API 返回 HTML 字符串而非 JSON 对象 | 同上，放弃 PM API |
--- a/doc/任务一/generate_report.py
+++ b/doc/任务一/generate_report.py
@ -0,0 +1,386 @@
+"""生成子赛题一报告 Word 文档"""
+from docx import Document
+from docx.shared import Pt, Inches, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml.ns import qn
+
+doc = Document()
+
+# === 样式设置 ===
+style = doc.styles['Normal']
+style.font.name = '宋体'
+style.font.size = Pt(12)
+style.element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')
+
+def add_heading(text, level=1):
+    h = doc.add_heading(text, level=level)
+    for run in h.runs:
+        run.font.name = '黑体'
+        run.element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
+    return h
+
+def add_para(text, bold=False):
+    p = doc.add_paragraph()
+    run = p.add_run(text)
+    run.bold = bold
+    run.font.name = '宋体'
+    run.font.size = Pt(12)
+    run.element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')
+    return p
+
+def add_table(headers, rows):
+    table = doc.add_table(rows=1, cols=len(headers), style='Table Grid')
+    table.alignment = WD_TABLE_ALIGNMENT.CENTER
+    for i, h in enumerate(headers):
+        cell = table.rows[0].cells[i]
+        cell.text = h
+        for p in cell.paragraphs:
+            p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            for run in p.runs:
+                run.bold = True
+                run.font.size = Pt(10)
+    for row_data in rows:
+        row = table.add_row()
+        for i, val in enumerate(row_data):
+            row.cells[i].text = str(val)
+            for p in row.cells[i].paragraphs:
+                for run in p.runs:
+                    run.font.size = Pt(10)
+    return table
+
+def add_code(text):
+    p = doc.add_paragraph()
+    run = p.add_run(text)
+    run.font.name = 'Consolas'
+    run.font.size = Pt(9)
+    run.font.color.rgb = RGBColor(0x33, 0x33, 0x33)
+    return p
+
+# ============================================================
+# 正文
+# ============================================================
+
+add_heading('第二章 子赛题一：增强与完善 GitLink-CLI 能力', level=1)
+
+# 2.1
+add_heading('2.1 任务目标与整体思路', level=2)
+add_para(
+    '子赛题一的定位是扩展 gitlink-cli 的功能覆盖面和使用体验。本项目选择的切入方向有三个：'
+    '新增 Shortcut 命令（填补功能空白）、优化命令系统框架（提升开发效率和用户体验）、'
+    '补全 Raw API 封装（对齐 OpenAPI 接口）。'
+)
+add_para(
+    '整体设计思路是"先框架后业务"：先完善底层的 Shortcut 抽象层（参数校验、输出格式、错误处理、帮助文档），'
+    '再基于这个框架快速新增业务命令。这样做的好处是，新增的命令天然继承框架能力'
+    '（dry-run、枚举校验、结构化错误输出），不需要每个命令重复造轮子。'
+)
+
+# 2.2
+add_heading('2.2 三层命令体系架构', level=2)
+add_para('gitlink-cli 采用三层命令体系：')
+
+add_table(
+    ['层级', '名称', '说明', '示例'],
+    [
+        ['第一层', 'Shortcuts（+前缀命令）', '人类和 AI Agent 直接使用，参数精简，结构化输出', 'issue +list --state open'],
+        ['第二层', 'API Commands（元数据驱动）', '自动从 OpenAPI spec 生成，覆盖所有 API 端点', 'api get /v1/{owner}/{repo}/issues'],
+        ['第三层', 'Raw API（HTTP 原始调用）', '完全透传，适合调试和边缘场景', 'raw GET /v1/owner/repo/issues'],
+    ]
+)
+
+add_para('')
+add_para(
+    '本次工作主要落在第一层（Shortcuts），同时涉及底层框架的增强。新增了 board、file、milestone '
+    '三个 Shortcut 模块，以及对 issue、pr、repo 等已有模块的扩展。'
+)
+add_para(
+    '架构说明：cmd/root.go 是 cobra 根命令，通过 shortcuts/register.go 挂载 15 个命令组，'
+    '每个组的子命令通过 common/runner.go 的 MountShortcut() 自动注册 flags、校验逻辑和错误处理。'
+    '业务模块只需定义 Shortcut 结构体数组。'
+)
+
+# 2.3
+add_heading('2.3 新增 Shortcut 命令', level=2)
+
+# 2.3.1 Wiki
+add_heading('2.3.1 Wiki 管理命令', level=3)
+add_para('新增 wiki 命令组，提供 6 个子命令：')
+add_table(
+    ['命令', '功能', 'DryRun'],
+    [
+        ['wiki +list', '列出所有 Wiki 页面', '-'],
+        ['wiki +view', '查看指定页面内容', '-'],
+        ['wiki +create', '创建 Wiki 页面', 'Yes'],
+        ['wiki +update', '更新 Wiki 页面', 'Yes'],
+        ['wiki +delete', '删除 Wiki 页面（带二次验证）', 'Yes'],
+        ['wiki +lint', '检查 Wiki 内容质量', '-'],
+    ]
+)
+add_para('技术要点：')
+add_para('（1）Wiki API 走网关（gateway.gitlink.org.cn/api），而非主 API。')
+add_para('（2）内容使用 base64 编码传输，outputWithDecodedContent() 自动解码，节省 AI Agent token。')
+add_para('（3）+delete 有删除后验证机制，GET 确认页面真的被删除了。')
+add_para('（4）+lint 检查项：空内容、标题层级、内容过短、链接有效性、图片引用。')
+
+# 2.3.2 Webhook
+add_heading('2.3.2 Webhook 配置命令', level=3)
+add_para('新增 webhook 命令组，提供 7 个子命令：')
+add_table(
+    ['命令', '功能', 'DryRun'],
+    [
+        ['webhook +list', '列出所有 webhook', '-'],
+        ['webhook +create', '创建 webhook', 'Yes'],
+        ['webhook +update', '更新 webhook（智能获取当前 URL）', 'Yes'],
+        ['webhook +delete', '删除 webhook（双重验证）', 'Yes'],
+        ['webhook +test', '测试 webhook 触发', '-'],
+        ['webhook +info', '查看 webhook 详情', '-'],
+        ['webhook +events', '列出支持的事件类型', '-'],
+    ]
+)
+add_para('支持 11 种事件类型：push, pull_request, issue, issue_assign, issue_comment, pull_request_assign, pull_request_comment, merge_request, repository, branch, tag。')
+
+# 2.3.3 Board
+add_heading('2.3.3 项目看板（Board）', level=3)
+add_para('新增 board 命令组，提供 6 个子命令：')
+add_table(
+    ['命令', '功能', '实现方式'],
+    [
+        ['board +view', '按状态分组显示看板全貌', '基于 issue list API + 客户端按 status_id 分组'],
+        ['board +columns', '列出各状态列及 issue 数量', '同上'],
+        ['board +issues', '按状态/指派人/优先级筛选任务', '同上，增加过滤逻辑'],
+        ['board +move', '移动任务状态', '复用 issue PATCH API'],
+        ['board +assign', '指派任务给用户', '先 resolveUserID，再 PATCH'],
+        ['board +stats', '完成率、工作负载、瓶颈分析', '统计聚合'],
+    ]
+)
+add_para(
+    '设计决策：最初计划使用 PM 看板 API（/pm/dashboards），但实际测试发现该端点不存在。'
+    '最终方案基于已有的 issue list API 实现，按 status_id 映射为 5 列'
+    '（待处理/进行中/已解决/已关闭/已拒绝）。'
+)
+
+# 2.3.4 Milestone
+add_heading('2.3.4 里程碑管理（Milestone）', level=3)
+add_para('新增 milestone 命令组，提供 6 个子命令：')
+add_table(
+    ['命令', '功能'],
+    [
+        ['milestone +list', '列出里程碑，支持按状态筛选和排序'],
+        ['milestone +create', '创建里程碑'],
+        ['milestone +view', '查看里程碑详情及关联 Issue'],
+        ['milestone +update', '更新里程碑（自动获取当前值，只覆盖指定字段）'],
+        ['milestone +delete', '删除里程碑（先 GET 获取必填字段再 DELETE）'],
+        ['milestone +status', '打开或关闭里程碑'],
+    ]
+)
+
+# 2.3.5 File
+add_heading('2.3.5 文件操作（File）', level=3)
+add_para('新增 file 命令组，提供 11 个子命令：')
+add_table(
+    ['命令', '功能', 'DryRun'],
+    [
+        ['file +ls', '列出根目录文件', '-'],
+        ['file +tree', '查看子目录/文件详情', '-'],
+        ['file +read', '读取文件内容', '-'],
+        ['file +readme', '读取 README', '-'],
+        ['file +search', '按文件名搜索', '-'],
+        ['file +create', '创建文件（自动 base64 编码）', 'Yes'],
+        ['file +update', '更新文件（自动获取 SHA）', 'Yes'],
+        ['file +delete', '删除文件（自动获取 SHA）', 'Yes'],
+        ['file +batch', '批量创建/更新/删除文件', 'Yes'],
+        ['file +commits', '提交历史', '-'],
+        ['file +diff', '查看 commit diff', '-'],
+    ]
+)
+
+# 2.4
+add_heading('2.4 优化部分', level=2)
+
+add_heading('2.4.1 参数设计优化', level=3)
+add_para(
+    '问题：枚举参数无校验，错误信息延迟到 API 调用才暴露。'
+    'pr +merge --method 接受 merge/rebase/squash，但输入非法值时直接发往 API，'
+    '等到服务端返回 422 才知道参数错了。'
+)
+add_para('方案：在 Flag 结构体中增加 Choices 和 Validate 字段，框架层在 parse 阶段自动校验。')
+add_code(
+    'type Flag struct {\n'
+    '    Name     string\n'
+    '    Choices  []string                  // 枚举校验\n'
+    '    Validate func(value string) error  // 自定义校验\n'
+    '}'
+)
+add_para('同时，Choices 声明后 --help 会自动追加 [merge|rebase|squash]，无需手动维护。')
+add_para('跨参数约束：Shortcut 结构体新增 Validate 字段，支持声明式校验（如"至少提供 --title、--body 或 --state 中的一个"）。')
+
+add_heading('2.4.2 输出格式优化', level=3)
+add_para('问题：默认格式与帮助文本不一致（帮助说 table，代码默认 json）；表格输出无列过滤、长文本被硬截断。')
+add_para('方案：')
+add_para('（1）修正默认值为 table。')
+add_para('（2）引入 PrintOptions 结构体，支持 --columns（列过滤）、--no-truncate（关闭截断）、--no-color（禁用彩色）。')
+add_para('（3）通过 RuntimeContext 透明传递到所有输出调用。')
+
+add_heading('2.4.3 错误提示优化', level=3)
+add_para('问题：中英文混用，fmt.Errorf 不被框架识别，无法输出结构化错误。')
+add_para('方案：新增 OpError 统一构造函数，入参只需动词和资源名，自动生成英文 Message（给脚本解析）和中文 Suggestion（给用户阅读）：')
+add_code('clierrors.OpError(clierrors.KindServer, "list", "issues", err)\n// 输出：failed to list issues / 获取列表失败，请检查参数或网络连接')
+
+add_heading('2.4.4 帮助文档优化', level=3)
+add_para('问题：Shortcut 只有短描述，无使用示例；15 个 Group 命令全部只有一行 Short。')
+add_para('方案：Shortcut 结构体新增 Long 和 Example 字段，挂载到 cobra 的对应字段；15 个 Group 命令全部补充 Long 描述和使用示例；新增 completion 子命令支持 bash/zsh/fish/powershell 的自动补全。')
+
+# 2.5
+add_heading('2.5 批量操作能力增强', level=2)
+
+add_heading('Issue 批量操作（6 个）', level=3)
+add_table(
+    ['命令', '功能'],
+    [
+        ['issue +batch-close', '批量关闭 Issue'],
+        ['issue +batch-status', '批量修改状态'],
+        ['issue +batch-priority', '批量修改优先级'],
+        ['issue +batch-assign', '批量指派负责人'],
+        ['issue +batch-label', '批量添加/移除标签'],
+        ['issue +batch-create', '批量创建 Issue'],
+    ]
+)
+
+add_heading('Repo 批量操作（4 个）', level=3)
+add_table(
+    ['命令', '功能'],
+    [
+        ['repo +batch-create', '批量创建仓库'],
+        ['repo +batch-update', '批量更新仓库设置'],
+        ['repo +batch-delete', '批量删除仓库'],
+        ['repo +batch-member', '批量邀请/移除成员'],
+    ]
+)
+
+add_heading('Issue 增强（4 个元数据查询 + 3 个评论管理）', level=3)
+add_table(
+    ['命令', '功能'],
+    [
+        ['issue +statuses', '获取所有可用的 Issue 状态'],
+        ['issue +authors', '获取发布过 Issue 的用户列表'],
+        ['issue +assigners', '获取可被指派的用户列表'],
+        ['issue +priorities', '获取所有可用的优先级'],
+        ['issue +comment-edit', '编辑 Issue 评论'],
+        ['issue +comment-delete', '删除 Issue 评论'],
+        ['issue +replies', '查看评论下的回复'],
+    ]
+)
+
+add_heading('PR 增强（6 个命令 + 2 个评论管理）', level=3)
+add_table(
+    ['命令', '功能'],
+    [
+        ['pr +reopen', '重新打开已关闭的 PR'],
+        ['pr +update', '更新 PR 标题/描述/分支'],
+        ['pr +commits', '查看 PR 中的所有提交'],
+        ['pr +versions', '查看 PR 版本历史'],
+        ['pr +vdiff', '查看 PR 某版本的 diff'],
+        ['pr +filesv1', '查看 PR 变更文件列表（v1 API）'],
+        ['pr +comment-edit', '编辑 PR 审查评论'],
+        ['pr +comment-delete', '删除 PR 审查评论'],
+    ]
+)
+
+# 2.6
+add_heading('2.6 跨平台兼容性与安装体验', level=2)
+add_para('本项目支持 macOS、Linux、Windows（x64/arm64）三个平台。')
+add_para('安装方式：')
+add_para('（1）一键安装脚本：curl -sSL .../install.sh | bash，自动检测平台和架构。')
+add_para('（2）npm 安装：npm install -g @gitlink-ai/cli，postinstall 自动下载对应平台二进制。')
+add_para('（3）源码编译：go install . 后手动同步到 npm 包。')
+add_para('Windows 特殊处理：npm shim（cli.js）调用的是 npm 包内的 gitlink-cli.exe，编译后需要同步覆盖。路径处理兼容 Windows 反斜杠。')
+
+# 2.7
+add_heading('2.7 Raw API 封装补全', level=2)
+add_para('对齐 GitLink OpenAPI，新封装的接口清单：')
+add_table(
+    ['模块', '接口数', '涉及 API 端点'],
+    [
+        ['File 操作', '11', 'entries, sub_entries, readme, files, create_file, update_file, delete_file, batch, commits, diff'],
+        ['Issue 元数据', '4', 'issue_statues, issue_authors, issue_assigners, issue_priorities'],
+        ['Milestone', '6', 'milestones CRUD + update_status'],
+        ['PR 增强', '6', 'reopen, update, commits, versions, versions/diff, files(v1)'],
+        ['评论管理', '5', 'issue journals CRUD + children_journals, PR journals CRUD'],
+        ['合计', '32', '-'],
+    ]
+)
+
+# 2.8
+add_heading('2.8 单元测试与命令帮助文档', level=2)
+
+add_heading('测试文件位置', level=3)
+add_table(
+    ['模块', '测试文件'],
+    [
+        ['board', 'shortcuts/board/board_test.go'],
+        ['file', 'shortcuts/file/file_test.go'],
+        ['milestone', 'shortcuts/milestone/milestone_test.go'],
+        ['wiki', 'shortcuts/wiki/wiki_test.go'],
+        ['webhook', 'shortcuts/webhook/webhook_test.go'],
+        ['issue', 'shortcuts/issue/issue_test.go, batch_test.go, batch_create_test.go'],
+        ['pr', 'shortcuts/pr/pr_test.go'],
+        ['repo', 'shortcuts/repo/batch_test.go, batch_delete_test.go'],
+        ['common', 'shortcuts/common/runner_test.go'],
+    ]
+)
+
+add_heading('测试方法', level=3)
+add_para('使用 httptest.NewServer mock API，构造 RuntimeContext 直接调用 Run 函数，验证输出和 PATCH body 内容。')
+
+add_heading('帮助文档更新', level=3)
+add_para('（1）所有 Shortcut 的 Long 和 Example 字段已填写。')
+add_para('（2）15 个 Group 命令补充了详细描述和使用示例。')
+add_para('（3）新增 completion 子命令支持 4 种 shell 自动补全。')
+
+# 2.9
+add_heading('2.9 PR 提交记录与变更说明', level=2)
+add_table(
+    ['PR', '标题', '内容摘要', '状态'],
+    [
+        ['#27', '实现场景1：社区运营自动化', 'Webhook 接收器 + 部署 + systemd', '已合并'],
+        ['-', 'feat(board): 新增项目看板 shortcut', '6 个看板命令 + 单元测试', '待提交'],
+        ['-', 'feat(file): 新增文件操作模块', '11 个文件命令 + 单元测试', '待提交'],
+        ['-', 'feat(milestone): 新增里程碑管理', '6 个里程碑命令 + 单元测试', '待提交'],
+        ['-', 'feat(wiki): 新增 Wiki 管理命令', '6 个 Wiki 命令 + lint', '待提交'],
+        ['-', 'feat(webhook): 新增 Webhook 配置', '7 个 Webhook 命令', '待提交'],
+        ['-', 'refactor(shortcuts): 优化命令框架', 'Choices/Validate/PrintOptions/OpError', '待提交'],
+        ['-', 'feat(issue): 批量操作 + 元数据查询 + 评论管理', '13 个命令', '待提交'],
+        ['-', 'feat(pr): PR 增强 + 评论管理', '8 个命令', '待提交'],
+    ]
+)
+
+add_para('')
+add_para('涉及文件变更汇总：', bold=True)
+add_table(
+    ['文件', '改动性质'],
+    [
+        ['shortcuts/common/types.go', '结构体扩展（6 个新增字段）'],
+        ['shortcuts/common/runner.go', '校验逻辑 + Long/Example 挂载'],
+        ['shortcuts/register.go', '注册 board/file/milestone 模块'],
+        ['internal/errors/errors.go', 'OpError 统一构造函数'],
+        ['internal/output/formatter.go', 'PrintOptions + 列过滤 + 彩色表头'],
+        ['cmd/root.go', '3 个 persistent flag + completion 子命令'],
+        ['cmd/cmdutil/globals.go', '新增全局变量'],
+        ['shortcuts/board/board.go', '新建，6 个命令'],
+        ['shortcuts/file/file.go', '新建，11 个命令'],
+        ['shortcuts/milestone/milestone.go', '新建，6 个命令'],
+        ['shortcuts/wiki/wiki.go', '新建，6 个命令'],
+        ['shortcuts/webhook/webhook.go', '新建，7 个命令'],
+        ['shortcuts/issue/issue.go', '新增 13 个命令'],
+        ['shortcuts/pr/pr.go', '新增 8 个命令'],
+    ]
+)
+
+add_para('')
+add_para('验证结果：go build 通过，go test ./... 全部通过。')
+
+# === 保存 ===
+output_path = r'C:\Users\Lenovo\Desktop\soft运维\gitlink-cli\doc\任务一\子赛题一报告.docx'
+doc.save(output_path)
+print(f'报告已生成: {output_path}')
--- a/doc/任务一/raw-api-封装笔记.md
+++ b/doc/任务一/raw-api-封装笔记.md
@ -0,0 +1,645 @@
+# Raw API 封装修改笔记
+
+## 第一批：代码/文件操作模块（file）
+
+### 1. file +ls — 根目录文件列表
+
+**功能**：列出项目根目录下的文件和子目录。
+
+**解决思路**：调用 `GET /{owner}/{repo}/entries` API，支持 `--ref` 指定分支。
+
+**代码指令**：
+```bash
+gitlink-cli file +ls --owner <user> --repo <repo>
+gitlink-cli file +ls --ref develop
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "entries": [
+      {"name": "README.md", "path": "README.md", "type": "file", "sha": "abc123"},
+      {"name": "src", "path": "src", "type": "dir", "sha": "def456"}
+    ],
+    "last_commit": {"message": "update readme", "author": {"name": "user"}},
+    "commits_count": 42
+  }
+}
+```
+
+---
+
+### 2. file +tree — 子目录/文件详情
+
+**功能**：查看指定路径的目录结构或文件元信息。
+
+**解决思路**：调用 `GET /{owner}/{repo}/sub_entries`，`filepath` 参数必填。
+
+**代码指令**：
+```bash
+gitlink-cli file +tree --path src/
+gitlink-cli file +tree --path src/main.go --ref v1.0
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "entries": {
+      "name": "main.go",
+      "path": "src/main.go",
+      "type": "file",
+      "size": 1234,
+      "sha": "abc123",
+      "commit": {"message": "add main.go"}
+    }
+  }
+}
+```
+
+---
+
+### 3. file +read — 读取文件内容
+
+**功能**：读取指定文件的实际内容。
+
+**解决思路**：调用 `GET /{owner}/{repo}/sub_entries`，响应的 `entries.content` 字段包含文件内容。
+
+**代码指令**：
+```bash
+gitlink-cli file +read --path README.md
+gitlink-cli file +read --path go.mod --ref develop
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "entries": {
+      "name": "README.md",
+      "path": "README.md",
+      "content": "# Project Title\n\nThis is the content...",
+      "sha": "abc123",
+      "size": 567
+    }
+  }
+}
+```
+
+---
+
+### 4. file +readme — 读取 README
+
+**功能**：读取项目的 README 文件，支持子目录 README。
+
+**解决思路**：调用 `GET /{owner}/{repo}/readme`，可选 `filepath` 和 `ref` 参数。
+
+**代码指令**：
+```bash
+gitlink-cli file +readme
+gitlink-cli file +readme --path docs/
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "name": "README.md",
+    "content": "# Project Title\n\nDescription...",
+    "sha": "abc123",
+    "encoding": "text"
+  }
+}
+```
+
+---
+
+### 5. file +search — 搜索文件
+
+**功能**：按文件名关键词搜索。
+
+**解决思路**：调用 `GET /{owner}/{repo}/files`，`search` 查询参数。
+
+**代码指令**：
+```bash
+gitlink-cli file +search --q "test"
+gitlink-cli file +search --q ".go" --ref main
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": [
+    {"name": "main_test.go", "path": "main_test.go", "sha": "abc", "size": 234},
+    {"name": "util_test.go", "path": "util/util_test.go", "sha": "def", "size": 567}
+  ]
+}
+```
+
+---
+
+### 6. file +create — 创建文件
+
+**功能**：在指定分支创建新文件。
+
+**解决思路**：调用 `POST /{owner}/{repo}/create_file`。注意 `content` 和 `base64_filepath` 都需要 Base64 编码，CLI 自动处理。
+
+**代码指令**：
+```bash
+gitlink-cli file +create --path docs/new.md --content "# New Doc" --branch master --message "add doc"
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "name": "new.md",
+    "sha": "abc123",
+    "size": 9,
+    "encoding": "base64",
+    "commit": {"message": "add doc", "author": {"name": "user"}}
+  }
+}
+```
+
+---
+
+### 7. file +update — 更新文件
+
+**功能**：更新已有文件内容。如果未提供 `--sha`，CLI 自动通过 sub_entries API 获取。
+
+**解决思路**：调用 `PUT /{owner}/{repo}/update_file`。`content` 传明文（非 Base64），需要文件当前 `sha`。
+
+**代码指令**：
+```bash
+# 自动获取 sha
+gitlink-cli file +update --path README.md --content "updated" --branch master --message "update readme"
+# 手动指定 sha
+gitlink-cli file +update --path README.md --content "updated" --branch master --sha abc123 --message "update"
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {"status": 1, "message": "更新成功"}
+}
+```
+
+---
+
+### 8. file +delete — 删除文件
+
+**功能**：删除指定文件。如果未提供 `--sha`，CLI 自动获取。
+
+**解决思路**：调用 `DELETE /{owner}/{repo}/delete_file`，需要 `sha`。body 参数（非 query）。
+
+**代码指令**：
+```bash
+gitlink-cli file +delete --path old-file.txt --branch master
+gitlink-cli file +delete --path old.txt --branch master --sha abc123
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {"status": 1, "message": "文件删除成功"}
+}
+```
+
+---
+
+### 9. file +batch — 批量提交文件
+
+**功能**：在一个 commit 中同时创建/更新/删除多个文件。
+
+**解决思路**：调用 `POST /v1/{owner}/{repo}/contents/batch`。`--files` 接收 JSON 数组，每个元素含 `action_type`、`file_path`、`content`。
+
+**代码指令**：
+```bash
+gitlink-cli file +batch --branch master --message "batch update" --files '[
+  {"action_type":"create","file_path":"a.txt","content":"hello"},
+  {"action_type":"update","file_path":"b.txt","content":"world"},
+  {"action_type":"delete","file_path":"c.txt"}
+]'
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "commit": {"sha": "abc123", "message": "batch update"},
+    "contents": [
+      {"name": "a.txt", "path": "a.txt", "sha": "def"},
+      {"name": "b.txt", "path": "b.txt", "sha": "ghi"}
+    ]
+  }
+}
+```
+
+---
+
+### 10. file +commits — 提交历史
+
+**功能**：查看项目的提交历史列表。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/commits`，支持分页和 `--ref` 过滤。
+
+**代码指令**：
+```bash
+gitlink-cli file +commits
+gitlink-cli file +commits --ref main --page 2 --limit 10
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": [
+    {"sha": "abc123", "message": "fix bug", "author": {"name": "user"}, "authored_date": "2026-07-09"},
+    {"sha": "def456", "message": "add feature", "author": {"name": "user"}, "authored_date": "2026-07-08"}
+  ]
+}
+```
+
+---
+
+### 11. file +diff — 提交 diff
+
+**功能**：查看某次提交的文件变更 diff。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/commits/{sha}/diff`。
+
+**代码指令**：
+```bash
+gitlink-cli file +diff --sha abc1234
+```
+
+**输出参考**：
+```json
+{
+  "ok": true,
+  "data": {
+    "files": [
+      {"filename": "main.go", "status": "modified", "additions": 5, "deletions": 2, "patch": "@@ -10,3 +10,6 @@..."}
+    ]
+  }
+}
+```
+
+---
+
+## 涉及文件
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `shortcuts/file/file.go` | 新建 | file 模块，11 个 shortcut |
+| `shortcuts/register.go` | 修改 | 注册 file 模块 |
+
+---
+
+## 第二批：Issue 增强 + PR 增强 + 评论管理（21 命令）
+
+### A. Issue 元数据查询（4 命令）
+
+### 12. issue +statuses — 疑修状态列表
+
+**功能**：获取项目所有可用的 Issue 状态（新增、正在解决、已解决、关闭、拒绝）。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/issue_statues`，无参数。
+
+**代码指令**：
+```bash
+gitlink-cli issue +statuses
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"total_count":5,"statues":[{"id":1,"name":"新增"},{"id":2,"name":"正在解决"},{"id":3,"name":"已解决"},{"id":5,"name":"关闭"},{"id":6,"name":"拒绝"}]}}
+```
+
+---
+
+### 13. issue +authors — 发布人列表
+
+**功能**：获取项目中发布过 Issue 的用户列表。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/issue_authors`，支持 `--keyword` 搜索。
+
+**代码指令**：
+```bash
+gitlink-cli issue +authors
+gitlink-cli issue +authors --keyword zhang
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"total_count":3,"authors":[{"id":1,"name":"张三","login":"zhangsan","type":"User"}]}}
+```
+
+---
+
+### 14. issue +assigners — 负责人列表
+
+**功能**：获取项目中可被指派为负责人的用户列表。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/issue_assigners`，支持 `--keyword` 搜索。
+
+**代码指令**：
+```bash
+gitlink-cli issue +assigners
+```
+
+---
+
+### 15. issue +priorities — 优先级列表
+
+**功能**：获取项目所有可用的 Issue 优先级。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/issue_priorities`，无参数。
+
+**代码指令**：
+```bash
+gitlink-cli issue +priorities
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"total_count":5,"priorities":[{"id":1,"name":"低"},{"id":2,"name":"正常"},{"id":3,"name":"高"},{"id":4,"name":"紧急"}]}}
+```
+
+---
+
+### B. 里程碑管理（6 命令）
+
+### 16. milestone +list — 里程碑列表
+
+**功能**：列出项目的里程碑，支持按状态筛选和排序。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/milestones`，支持 `--category`、`--keyword`、`--sort-by`、分页。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +list
+gitlink-cli milestone +list --category opening
+gitlink-cli milestone +list --sort-by issues_count --limit 5
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"total_count":3,"opening_milestone_count":2,"closed_milestone_count":1,"milestones":[{"id":1,"name":"v1.0","status":"open","issues_count":10,"percent":60}]}}
+```
+
+---
+
+### 17. milestone +create — 创建里程碑
+
+**功能**：创建新里程碑。
+
+**解决思路**：调用 `POST /v1/{owner}/{repo}/milestones`，body 必填 `name`、`description`、`effective_date`。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +create --name "v1.0" --description "First release" --date 2026-12-31
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"status":0,"message":"success"}}
+```
+
+---
+
+### 18. milestone +view — 里程碑详情
+
+**功能**：查看里程碑详情及其关联的 Issue 列表。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/milestones/{id}`，支持 `--category` 过滤 Issue 状态。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +view --id 1
+gitlink-cli milestone +view --id 1 --category opened
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"milestone":{"id":1,"name":"v1.0","percent":60},"total_issues_count":10,"issues":[{"id":42,"subject":"Fix login","status_name":"新增"}]}}
+```
+
+---
+
+### 19. milestone +update — 更新里程碑
+
+**功能**：更新里程碑的名称、描述或截止日期。自动获取当前值，只覆盖用户指定的字段。
+
+**解决思路**：先 `GET` 获取当前里程碑，再 `PATCH` 提交修改后的完整数据。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +update --id 1 --name "v1.0-rc1"
+gitlink-cli milestone +update --id 1 --date 2027-01-31
+```
+
+---
+
+### 20. milestone +delete — 删除里程碑
+
+**功能**：删除指定里程碑。
+
+**解决思路**：API 要求 body 中包含 `name`/`description`/`effective_date`，先 GET 获取再 DELETE。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +delete --id 1 --dry-run
+```
+
+---
+
+### 21. milestone +status — 里程碑状态变更
+
+**功能**：打开或关闭里程碑。
+
+**解决思路**：调用 `POST /{owner}/{repo}/milestones/{id}/update_status`（注意无 `/v1/` 前缀）。
+
+**代码指令**：
+```bash
+gitlink-cli milestone +status --id 1 --status closed
+gitlink-cli milestone +status --id 1 --status opening
+```
+
+---
+
+### C. PR 增强（6 命令）
+
+### 22. pr +reopen — 重新打开 PR
+
+**功能**：重新打开已关闭的 PR。
+
+**解决思路**：调用 `POST /v1/{owner}/{repo}/pulls/{index}/reopen`，无 body。
+
+**代码指令**：
+```bash
+gitlink-cli pr +reopen --id 42
+```
+
+---
+
+### 23. pr +update — 更新 PR
+
+**功能**：更新 PR 的标题、描述、源分支或目标分支。自动获取当前值，只覆盖用户指定的字段。
+
+**解决思路**：先 GET 获取当前 PR 数据，再 PUT 提交（API 要求所有字段必填）。
+
+**代码指令**：
+```bash
+gitlink-cli pr +update --id 42 --title "New title"
+gitlink-cli pr +update --id 42 --body "Updated description"
+```
+
+---
+
+### 24. pr +commits — PR 提交列表
+
+**功能**：查看 PR 中的所有提交。
+
+**解决思路**：调用 `GET /{owner}/{repo}/pulls/{id}/commits`（无 `/v1/` 前缀）。
+
+**代码指令**：
+```bash
+gitlink-cli pr +commits --id 42
+```
+
+**输出参考**：
+```json
+{"ok":true,"data":{"commits_count":3,"commits":[{"sha":"abc","message":"fix bug","author":{"name":"user"}}]}}
+```
+
+---
+
+### 25. pr +versions — PR 版本列表
+
+**功能**：查看 PR 的版本历史（每次 push 新提交会生成新版本）。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/pulls/{index}/versions`。
+
+**代码指令**：
+```bash
+gitlink-cli pr +versions --id 42
+```
+
+---
+
+### 26. pr +vdiff — PR 版本 diff
+
+**功能**：查看 PR 某个版本的文件变更 diff。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/pulls/{index}/versions/{version_id}/diff`，支持 `--filepath` 过滤。
+
+**代码指令**：
+```bash
+gitlink-cli pr +vdiff --id 42 --version 5
+gitlink-cli pr +vdiff --id 42 --version 5 --filepath main.go
+```
+
+---
+
+### 27. pr +filesv1 — PR 文件列表(v1)
+
+**功能**：使用 v1 API 查看 PR 变更的文件列表，支持分页。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/pulls/{index}/files`，支持 `--filepath` 过滤和分页。
+
+**代码指令**：
+```bash
+gitlink-cli pr +filesv1 --id 42
+gitlink-cli pr +filesv1 --id 42 --filepath src/
+```
+
+---
+
+### D. 评论管理（5 命令）
+
+### 28. issue +comment-edit — 编辑 Issue 评论
+
+**功能**：修改已有 Issue 评论的内容。
+
+**解决思路**：调用 `PATCH /v1/{owner}/{repo}/issues/{index}/journals/{id}`，body 需 `notes`（复数）和 `attachment_ids`。
+
+**代码指令**：
+```bash
+gitlink-cli issue +comment-edit --number 42 --comment-id 100 --body "修正后的评论"
+```
+
+---
+
+### 29. issue +comment-delete — 删除 Issue 评论
+
+**功能**：删除 Issue 的某条评论。
+
+**解决思路**：调用 `DELETE /v1/{owner}/{repo}/issues/{index}/journals/{id}`。
+
+**代码指令**：
+```bash
+gitlink-cli issue +comment-delete --number 42 --comment-id 100
+```
+
+---
+
+### 30. issue +replies — 子评论列表
+
+**功能**：查看某条评论下的所有回复。
+
+**解决思路**：调用 `GET /v1/{owner}/{repo}/issues/{index}/journals/{id}/children_journals`。
+
+**代码指令**：
+```bash
+gitlink-cli issue +replies --number 42 --comment-id 100
+```
+
+---
+
+### 31. pr +comment-edit — 编辑 PR 评论
+
+**功能**：修改 PR 审查评论。注意 body 字段是 `note`（单数，与 Issue 的 `notes` 不同）。
+
+**解决思路**：调用 `PUT /v1/{owner}/{repo}/pulls/{index}/journals/{id}`，body 需 `note`、`commit_id`、`state`。
+
+**代码指令**：
+```bash
+gitlink-cli pr +comment-edit --id 42 --comment-id 100 --body "updated" --state resolved
+```
+
+---
+
+### 32. pr +comment-delete — 删除 PR 评论
+
+**功能**：删除 PR 的某条审查评论。
+
+**解决思路**：调用 `DELETE /v1/{owner}/{repo}/pulls/{index}/journals/{id}`。
+
+**代码指令**：
+```bash
+gitlink-cli pr +comment-delete --id 42 --comment-id 100
+```
+
+---
+
+## 涉及文件
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `shortcuts/file/file.go` | 新建 | file 模块，11 个 shortcut |
+| `shortcuts/issue/issue.go` | 修改 | 新增 7 个命令（4 元数据 + 3 评论管理） |
+| `shortcuts/milestone/milestone.go` | 新建 | milestone 模块，6 个 shortcut |
+| `shortcuts/pr/pr.go` | 修改 | 新增 8 个命令（6 PR 增强 + 2 评论管理） |
+| `shortcuts/register.go` | 修改 | 注册 file + milestone 模块 |
--- a/doc/任务一/创作模板.txt
+++ b/doc/任务一/创作模板.txt
@ -0,0 +1,39 @@
+子赛题一：增加和完善GitLink-CLI能力
+定位：扩展CLI功能丨难度：中高丨需要Go语言基础
+为gitlink-cli增加新功能或优化现有功能，包括但不限于：
+·新增Shortcut命令（如Wiki管理、Webhook配置、项目看板增强）
+·优化现有命令的参数设计、输出格式、错误提示和帮助文档
+·增加批量操作能力（如批量Issue操作、批量仓库管理、批量成员邀请)
+·提升跨平台兼容性和安装体验
+·补全RawAPI封装（对齐GitLinkOpenAPI中尚未封装的接口）
+交付要求：
+·向gitlink-cli主仓库提交PR（可以是多个）
+·每个PR包含：功能代码+单元测试+命令帮助文档更新
+·提供变更说明文档
+
+
+
+模板：
+第二章 子赛题一：增强与完善 GitLink-CLI 能力
+2.1 任务目标与整体思路
+【占位】说明本子赛题的定位（扩展 CLI 功能）、你选择的切入方向、整体设计思路。
+2.2 三层命令体系架构
+【占位】用一段话+架构图说明：Shortcuts（+前缀）→ API Commands（元数据驱动）→ Raw API 三层结构，以及本次工作落在哪一层。
+【占位】此处插入架构图（三层命令体系）。
+2.3 新增 Shortcut 命令
+2.3.1 Wiki 管理命令
+【占位】列出 wiki +list/+view/+create/+update/+delete，说明参数设计、输出格式、使用示例。
+2.3.2 Webhook 配置命令
+【占位】列出 webhook +list/+create/+update/+test/+delete/+events/+info，说明设计要点与示例。
+2.3.3 项目看板
+【占位】列出 milestone 相关命令及使用示例
+2.4优化部分
+2.5批量操作能力增强  都有哪些，，按大类区分
+2.6 跨平台兼容性与安装体验
+【占位】Windows PowerShell 脚本、路径处理、一键安装脚本、npm 安装等改进点。
+2.7 Raw API 封装补全
+【占位】列出对齐 GitLink OpenAPI 新封装的接口清单。
+2.8 单元测试与命令帮助文档
+【占位】测试文件位置、覆盖率、关键用例；help 文本与示例更新说明。
+2.9 PR 提交记录与变更说明
+【占位】以表格列出各 PR：编号、标题、内容摘要、合并状态、链接。
--- a/doc/作业要求.txt
+++ b/doc/作业要求.txt
@ -0,0 +1,56 @@
+子赛题一：增加和完善GitLink-CLI能力
+定位：扩展CLI功能|难度：中高|需要Go语言基础
+为gitlink-cli增加新功能或优化现有功能，包括但不限于：
+●新增Shortcut命令(如Wiki管理、Webhook配置、项目看板增强、代码片段管理等)
+
+●优化现有命令的参数设计、输出格式、错误提示和帮助文档
+
+·增加批量操作能力(如批量Issue操作、批量仓库管理、批量成员邀请)
+
+·提升跨平台兼容性和安装体验
+
+·补全Raw API封装(对齐GitLink OpenAPI中尚未封装的接口)
+
+
+
+
+子赛题二：编写和丰富GitLink Skills
+定位：开发Agent Skill|难度：中|无需Go,Markdown +CLI调用即可
+基于gitlink-cli开发新的AI Agent Skill。核心交付物是Skill本身(SKILLmd+使用示例+Agent平台验证结果)。场景示例(不限于此):
+·智能代码审查：分析PR diff,输出结构化Review意见并自动评论
+
+·Issue自动分拣：根据内容自动分类、打标签、分配责任人
+
+·Release Notes生成：根据commit和PR记录生成结构化版本说明
+
+·项目健康度报告：统计Issue响应时间、PR合并效率、贡献者活跃度
+
+·许可证合规检查：扫描仓库的许可证合规性和敏感信息泄露风险
+
+·新人引导：为good-first-issue自动添加引导评论，降低新贡献者参与门槛
+
+
+
+
+子赛题三：构建端到端自动化工作流
+定位：组合现有能力解决实际问题丨难度：低-中「无需写底层代码
+组合gitlink-cli已有命令和Skills（可包含自定义Skill），完成一个可复现的端到端自动化场景。与子赛题二的区别在于：子赛题二
+交付的是独立可复用的Skill，子赛题三交付的是串联多个步骤的完整解决方案。
+场景示例（不限于此）：
+·项目一键初始化：输入项目描述→创建仓库→生成README/LICENSE/CI配置→创建初始IsSUe和里程碑
+·多仓库协同：跨多个仓库的统一Issue追踪、PR状态看板、Release协调发布
+·贡献者成长体系：追踪贡献者的PR/Issue活动→生成贡献排行→自动颁发徽章
+
+
+子赛题四：应用 GitLink 辅助科研（可选完成，视完成情况额外加分）
+ 定位：科研场景智能化赋能 | 难度：中 | 要求：无需 Go，Markdown + CLI 调用即可
+ 任务：依托 gitlink-cli 数据获取、命令调用与 AI Agent 能力，融合数据分析、知识图谱、AI 挖掘技术，面向
+科研工作者、课题组与科研团队，将 GitLink 平台代码托管、协作数据转化为科研创新支撑能力，实现科研项目
+分析、主体画像、热点追踪、创新启发、合规校验等全链路科研辅助服务，打通开源代码生态与学术科研的融
+合通道，包括但不限于以下场景：
+• 仓库级科研项目洞悉
+• 科研热点追踪与知识图谱构建
+• 科研项目合规与复现性检查
+• 科研协作智能匹配
+• 科研进度智能跟踪与预警
+
--- a/doc/子任务一提交文档.md
+++ b/doc/子任务一提交文档.md
@ -0,0 +1,294 @@
+# 子任务一：CLI 命令系统优化
+
+## PR: feat: CLI 命令系统优化 — 参数校验、输出格式、错误提示、帮助文档
+
+### Summary
+
+本次优化针对 gitlink-cli 的命令系统进行了四个方面的改进，提升用户体验和开发者效率：
+
+1. **参数设计** — 新增 `Choices` 枚举校验和 `Validate` 自定义校验，非法参数在本地拦截而非等待 API 返回 422
+2. **输出格式** — 新增 `--columns`、`--no-truncate`、`--no-color` 全局 flag，支持列过滤、禁用截断、彩色表头
+3. **错误提示** — 统一 `OpError` 构造函数，错误信息包含英文 `message`（脚本可解析）+ 中文 `suggestion`（用户可读）
+4. **帮助文档** — `Shortcut` 新增 `Long`/`Example` 字段，15 个 Group 命令补充详细说明，新增 `completion` 子命令
+
+---
+
+### 一、参数设计优化
+
+#### 问题
+
+- 枚举参数无校验，非法值直接发往 API，等服务端返回 422 才知道参数错误
+- 跨参数约束散落在 `Run()` 函数中，格式不统一，中英文混杂
+
+#### 解决方案
+
+**1. Choices 枚举校验**
+
+```go
+// Flag 结构体新增 Choices 字段
+type Flag struct {
+    Name     string
+    Short    string
+    Usage    string
+    Required bool
+    Default  string
+    Bool     bool
+    Choices  []string                  // 新增：枚举校验
+    Validate func(value string) error  // 新增：自定义校验函数
+}
+
+// 命令中声明 Choices
+Flags: []common.Flag{
+    {Name: "method", Short: "m", Usage: "Merge method", Default: "merge",
+     Choices: []string{"merge", "rebase", "squash"}},
+}
+```
+
+Choices 声明后，无需再写校验函数，`--help` 自动追加 `[merge|rebase|squash]`。
+
+**2. Validate 自定义校验**
+
+```go
+// Shortcut 结构体新增 Validate 字段
+type Shortcut struct {
+    Name        string
+    Description string
+    Flags       []Flag
+    Validate    func(args map[string]string) error  // 新增：跨参数校验
+    Run         func(ctx *RuntimeContext) error
+}
+```
+
+**3. 统一错误格式**
+
+```go
+// 使用 clierrors.InputError 统一错误格式
+if title == "" && description == "" && state == "" {
+    return clierrors.InputError(
+        "at least one of --title, --body, or --state is required",
+        "至少需要提供 --title、--body 或 --state 中的一个参数",
+    ).WithCommand(ctx.CommandName)
+}
+```
+
+---
+
+### 二、输出格式优化
+
+#### 问题
+
+- 表格输出列全量显示，无法过滤
+- 长文本在 60 字符处硬截断，不可配置
+- 无色彩区分，可读性差
+
+#### 解决方案
+
+**1. PrintOptions 结构体**
+
+```go
+type PrintOptions struct {
+    Columns    []string // 要显示的列，nil = 全部
+    NoTruncate bool     // 禁用 60 字符截断
+    UseColor   bool     // 启用 ANSI 颜色
+}
+```
+
+**2. 新增全局 Flag**
+
+```bash
+gitlink-cli issue +list --columns id,subject,status
+gitlink-cli issue +list --no-truncate
+gitlink-cli issue +list --no-color
+```
+
+**3. 默认格式修正**
+
+`--format` 默认值从 `json` 改为 `table`，与 `--help` 文本一致。
+
+---
+
+### 三、错误提示优化
+
+#### 问题
+
+- 中英文混用，格式不统一
+- `fmt.Errorf` 不被框架识别，无法输出结构化错误
+
+#### 解决方案
+
+**1. OpError 统一构造函数**
+
+```go
+// 入参只需动词和资源名
+func OpError(kind ErrorKind, op, resource string, cause error) *CLIError {
+    msg := fmt.Sprintf("failed to %s %s", op, resource)
+    sugg := opSuggestion(op, resource)
+    return Wrap(kind, msg, sugg, cause)
+}
+
+// 命令中一行调用
+env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
+if err != nil {
+    return clierrors.OpError(clierrors.KindServer, "list", "issues", err).
+        WithCommand(ctx.CommandName)
+}
+```
+
+**2. 结构化输出**
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": 500,
+    "message": "failed to list issues",
+    "suggestion": "获取列表失败，请检查参数或网络连接，稍后重试"
+  }
+}
+```
+
+`message` 用英文保证脚本可解析，`suggestion` 用中文直接给人看。
+
+---
+
+### 四、帮助文档优化
+
+#### 问题
+
+- Shortcut 无详细帮助，`--help` 只有命令行和 flag 列表
+- Group 命令只有一行描述
+- 无 Shell 自动补全
+
+#### 解决方案
+
+**1. Shortcut 新增 Long/Example 字段**
+
+```go
+type Shortcut struct {
+    Name        string
+    Description string
+    Long        string   // 新增：详细帮助文本
+    Example     string   // 新增：使用示例
+    Flags       []Flag
+    Run         func(ctx *RuntimeContext) error
+}
+
+// 命令中填写 Example
+{
+    Name:        "merge",
+    Description: "Merge a pull request",
+    Example:     "  gitlink-cli pr +merge --id 42\n" +
+                 "  gitlink-cli pr +merge --id 42 --method rebase\n" +
+                 "  gitlink-cli pr +merge --id 42 --method squash --dry-run",
+}
+```
+
+**2. 15 个 Group 命令补充 Long/Example**
+
+```go
+infos := map[string]groupInfo{
+    "pr": {
+        Short:   "Pull request operations",
+        Long:    "Manage pull requests: list, create, view, merge, close, review, and view changed files.",
+        Example: "  gitlink-cli pr +list --state open\n" +
+                 "  gitlink-cli pr +create --title \"Fix login\" --head feat-branch\n" +
+                 "  gitlink-cli pr +merge --id 42",
+    },
+    // 其余 14 个 group 同上
+}
+```
+
+**3. 新增 completion 子命令**
+
+```bash
+source <(gitlink-cli completion bash)                              # Bash
+source <(gitlink-cli completion zsh)                               # Zsh
+gitlink-cli completion fish | source                                # fish
+gitlink-cli completion powershell | Out-String | Invoke-Expression  # PowerShell
+```
+
+---
+
+### Modified Files
+
+| 文件 | 改动 |
+|------|------|
+| `cmd/cmdutil/globals.go` | 新增 NoTruncate/Columns/NoColor 全局变量 |
+| `cmd/root.go` | 新增 3 个 persistent flag + completion 子命令 + format 默认值修正 |
+| `shortcuts/common/types.go` | Shortcut/Flag/RuntimeContext 结构体扩展 |
+| `shortcuts/common/runner.go` | Choices/Validate 校验逻辑 + Long/Example 挂载 |
+| `internal/output/formatter.go` | PrintOptions + 列过滤 + 去截断 + 彩色表头 |
+| `internal/errors/errors.go` | OpError 统一构造函数 |
+| `shortcuts/register.go` | 15 个 Group 命令补充 Long/Example |
+| `shortcuts/issue/issue.go` | 错误统一 + Choices + Long/Example |
+| `shortcuts/pr/pr.go` | 错误统一 + Choices + Long/Example |
+| `shortcuts/repo/repo.go` | 错误统一 + Choices + Long/Example |
+| `shortcuts/milestone/milestone.go` | 修复 milestone +view 输出问题 |
+| `shortcuts/board/board.go` | 修正 assign 字段 |
+
+---
+
+### Testing
+
+- `go build` 通过
+- `go vet` 通过
+- `go test ./...` 7 个测试包全部通过
+- 所有新增字段零值安全，现有 80+ Shortcut 无需修改即可编译
+
+---
+
+### Breaking Changes
+
+无。`output.Print()` 签名不变，内部包装为 `PrintWithOpts`。Workflow 脚本显式使用 `--format json`，不受默认格式变化影响。
+
+---
+
+### 验证示例
+
+**1. 枚举校验**
+
+```bash
+$ gitlink-cli pr +merge --id 42 --method unknown
+Error: invalid value "unknown" for --method
+有效值: merge, rebase, squash。运行 'gitlink-cli pr +merge --help' 查看用法。
+```
+
+**2. 跨参数约束**
+
+```bash
+$ gitlink-cli issue +update --number 42
+Error: at least one of --title, --body, or --state is required
+至少需要提供 --title、--body 或 --state 中的一个参数
+```
+
+**3. 列过滤**
+
+```bash
+$ gitlink-cli issue +list --columns id,subject,status
+id    subject              status
+--    -------              ------
+42    Fix login bug        open
+43    Add unit tests       closed
+```
+
+**4. 结构化错误**
+
+```bash
+$ gitlink-cli issue +view --number 999999 --format json
+{
+  "ok": false,
+  "error": {
+    "code": 404,
+    "message": "failed to view issue",
+    "suggestion": "查看失败，请确认资源 ID 是否存在"
+  }
+}
+```
+
+**5. Shell 自动补全**
+
+```bash
+$ source <(gitlink-cli completion bash)
+$ gitlink-cli pr +<TAB>
+list  +create  +view  +merge  +close  +reopen  +update  +files  +diff  +comment
+```
--- a/doc/系统动态模型章节.docx
+++ b/doc/系统动态模型章节.docx
--- a/doc/软件分析及建模报告.docx
+++ b/doc/软件分析及建模报告.docx
--- a/doc/软件分析及建模报告.pptx
+++ b/doc/软件分析及建模报告.pptx
--- a/doc/软件分析及建模报告.txt
+++ b/doc/软件分析及建模报告.txt
@ -0,0 +1,408 @@
+目录
+1. 项目概述
+2、软件总体设计
+2.1 软件体系结构设计
+2.2 用户界面设计
+2.3 数据库设计
+2.4 系统度量
+3、系统静态模型
+3.1 命令框架层设计
+3.2 快捷命令层设计
+3.3 核心库层设计
+4、系统动态模型
+4.1 用例一：用户认证与仓库操作
+4.2 用例二：Issue 批量管理
+4.3 用例三：AI 自动化工作流
+5、系统部署模型
+
+
+1. 项目概述
+
+gitlink-cli 是 GitLink（确实开源）平台的命令行工具。GitLink 是 CCF 官方开源协作平台，后端提供 490+ API 端点，但此前缺少官方 CLI 工具。本项目填补了这个空白。
+
+应用背景：
+开发者在日常工作中需要频繁操作仓库、Issue、PR、分支等资源。浏览器操作效率低，无法批量处理，也不能与 CI/CD 流水线集成。gitlink-cli 让开发者在终端中完成所有平台操作，并通过 AI Agent Skill 支持 Claude Code 自动化执行复杂工作流。
+
+功能描述：
+- 仓库管理：创建、列表、详情、Fork、删除、设置、批量操作
+- Issue 管理：列表、创建、查看、更新、关闭、评论、标签、6 种批量命令
+- PR 管理：列表、创建、查看、合并、关闭、代码审查、变更文件查看
+- 分支管理：列表、创建、删除、保护
+- 发布管理：列表、创建、查看、删除
+- Wiki 管理：列表、创建、查看、更新、删除
+- Webhook 管理：列表、创建、更新、删除、测试
+- CI/CD 管理：构建列表、日志、重启、停止
+- 组织与团队管理：组织列表、详情、成员、团队 CRUD
+- 合规检查：许可证扫描、敏感信息检测、依赖审计
+- 搜索：仓库搜索、用户搜索
+- AI 工作流：社区运营、代码审查、项目初始化、多仓库协同、贡献者成长
+
+性能要求：
+- 单次 API 调用响应时间 < 2 秒
+- 批量操作支持并发执行，错误不中断
+- 分页自动遍历，支持大数据量场景
+- 跨平台支持：Windows、macOS、Linux
+
+
+2、软件总体设计
+
+2.1 软件体系结构设计
+
+本项目采用分层架构，从上到共分为五层：
+
+（1）入口层：main.go 和 cmd/root.go，基于 Cobra 框架构建命令树。
+（2）命令层：cmd/ 目录，包含 auth、api、config、compliance 四个顶级命令。
+（3）快捷命令层：shortcuts/ 目录，16 个资源组，每组通过 +动词 子命令暴露操作。
+（4）核心库层：internal/ 目录，包含 HTTP 客户端、认证、配置、输出格式化、错误处理。
+（5）AI 扩展层：skills/ 目录（24 个 SKILL.md）和 workflows/ 目录（bash/PowerShell 脚本）。
+
+各层的职责划分：
+
+[入口层] main.go → cmd.Execute() → Cobra root 命令
+    ↓
+[命令层] auth / api / config / compliance
+    ↓
+[快捷命令层] shortcuts/ → repo/issue/pr/wiki/... → common.Shortcut 声明式定义
+    ↓
+[核心库层] internal/client → HTTP 请求 → internal/auth → Token 注入
+           internal/output → 格式化输出（JSON/Table/YAML）
+           internal/config → 配置文件读写
+           internal/context → git remote 解析 owner/repo
+    ↓
+[AI 扩展层] skills/ → SKILL.md 定义（供 Claude Code 调用）
+            workflows/ → 可执行脚本（bash/PowerShell）
+
+核心设计模式是声明式 Shortcut 框架。每个快捷命令通过 common.Shortcut 结构体定义 Name、Flags、Run 函数，由 runner.go 统一挂载到 Cobra 命令树。开发者新增命令只需实现 Run 函数，不需要关心命令注册和参数解析的细节。
+
+三层命令体系：
+- Layer 1 Shortcuts：语义化封装，覆盖 16 个领域共 80+ 命令（如 issue +create）
+- Layer 2 API Commands：原始 HTTP 调用（api GET/POST/PUT/DELETE）
+- Layer 3 Raw API：覆盖全部 490+ 端点，自动注入认证 Header
+
+
+2.2 用户界面设计
+
+本项目是 CLI 工具，用户界面是终端命令行。界面设计遵循以下原则：
+
+（1）命令格式统一：gitlink-cli <资源> +<动作> [flags]
+   例如：gitlink-cli issue +create --title "Bug" --body "描述"
+
+（2）输出格式三选一：通过 --format 参数选择 json、table、yaml，默认 table。
+   table 格式使用 tabwriter 对齐，支持 ANSI 颜色高亮表头。
+   json 格式使用统一的 Envelope 结构：{ok, data, error, meta}。
+
+（3）全局参数：--owner、--repo（自动从 git remote 解析）、--format、--debug、--no-truncate、--columns、--no-color。
+
+（4）Shell 补全：支持 bash、zsh、fish、powershell 四种 shell 的自动补全。
+
+（5）帮助系统：每个命令支持 --help，显示用法、参数说明和示例。
+
+用户操作流程：
+用户打开终端 → 输入 gitlink-cli auth login 登录 → 使用具体命令操作资源
+→ 输出结果以 table/json/yaml 格式显示 → 可通过管道传递给其他工具
+
+
+2.3 数据库设计
+
+本项目不使用传统数据库。数据存储分为两部分：
+
+（1）配置文件存储：
+路径：~/.config/gitlink-cli/config.yaml
+内容：base_url（API 地址）、default_format（输出格式）、editor、pager
+格式：YAML
+
+（2）凭证存储：
+使用 go-keyring 库，调用操作系统原生密钥管理：
+- macOS：Keychain
+- Linux：Secret Service（GNOME Keyring / KDE Wallet）
+- Windows：Credential Manager
+Fallback：~/.config/gitlink-cli/credentials（文件权限 0600）
+
+存储的数据结构：
+Token（字符串）→ 关联 gitlink.org.cn 的 Bearer Token
+Config（YAML）→ base_url、default_format、editor、pager 等配置项
+
+本项目不需要关系型数据库，所有数据来自 GitLink 平台 API 的实时查询。
+
+
+2.4 系统度量
+
+（1）代码规模：
+- Go 源文件：60 个
+- Go 代码总行数：14,932 行
+- 测试文件：12 个，共 4,279 行
+- 测试覆盖率：测试代码占总代码的 22.3%
+
+（2）按模块统计：
+
+模块               文件数   代码行数
+main（入口）        1       13
+cmd（命令层）       5       379
+internal（核心库）  13      2,242
+shortcuts（快捷层） 41      12,398
+合计                60      14,932
+
+（3）功能规模：
+- Shortcut 命令组：16 个
+- Shortcut 命令总数：80+
+- AI Skill 定义：24 个 SKILL.md
+- 自动化工作流脚本：15+ 个（bash/PowerShell）
+- 支持的 Shell 补全：4 种（bash/zsh/fish/powershell）
+
+（4）依赖规模：
+- 直接依赖：4 个（cobra、go-keyring、golang.org/x/term、yaml.v3）
+- 编译产物大小：约 11.9 MB（单二进制文件）
+
+
+3、系统静态模型
+
+3.1 命令框架层设计
+
+命令框架层由 cmd/ 包和 shortcuts/common/ 包组成，定义了整个 CLI 的骨架。
+
+核心类结构：
+
+（1）cobra.Command（来自 spf13/cobra 库）
+- 每个命令对应一个 cobra.Command 实例
+- rootCmd 是根命令，所有子命令通过 AddCommand 挂载
+- root.go 定义全局 PersistentFlags（--owner、--repo、--format 等）
+
+（2）common.Shortcut 结构体：
+type Shortcut struct {
+    Name        string
+    Description string
+    Long        string
+    Example     string
+    Flags       []Flag
+    DryRun      bool
+    DryRunHint  func(ctx *RuntimeContext) (string, error)
+    Validate    func(args map[string]string) error
+    Run         func(ctx *RuntimeContext) error
+}
+
+（3）common.Flag 结构体：
+type Flag struct {
+    Name     string
+    Short    string
+    Usage    string
+    Required bool
+    Default  string
+    Bool     bool
+    Choices  []string
+    Validate func(value string) error
+}
+
+（4）common.RuntimeContext 结构体：
+type RuntimeContext struct {
+    Client            *client.Client
+    Owner             string
+    Repo              string
+    Format            string
+    CommandName       string
+    Args              map[string]string
+    GatewayBaseURL    string
+    GatewayHTTPClient *http.Client
+    NoTruncate        bool
+    Columns           string
+    NoColor           bool
+}
+
+RuntimeContext 提供以下核心方法：
+- ResolveOwnerRepo()：从 git remote 或 flags 解析 owner/repo
+- CallAPI(method, path, body)：发起 HTTP 请求
+- PaginateAll(path, params)：自动遍历分页
+- Output(env)：格式化输出
+- OutputData(data)：封装为成功 Envelope 并输出
+
+（5）register.go 的注册机制：
+RegisterAll(root) 遍历 16 个命令组，每组创建 cobra.Command 并调用 MountShortcuts 挂载子命令。MountShortcuts 遍历 Shortcut 切片，为每个 Shortcut 创建对应的 cobra.Command，绑定 flags 和 RunE 函数。
+
+
+3.2 快捷命令层设计
+
+快捷命令层位于 shortcuts/ 目录，包含 16 个命令组。每个组是一个独立的 Go 包，通过 Shortcuts() 函数返回 []*common.Shortcut 切片。
+
+命令组列表：
+- board：看板操作（view/columns/issues/move/assign/stats）— 832 行
+- branch：分支操作（list/create/delete/protect）— 157 行
+- ci：CI/CD 操作（builds/logs/restart/stop）— 117 行
+- file：文件操作（ls/read/create/update/delete/commits/diff）— 886 行
+- issue：Issue 操作（14 个命令，含 6 种批量操作）— 3,058 行
+- milestone：里程碑操作（list/create/view/update/delete/status）— 525 行
+- org：组织操作（list/info/members/create/update）— 476 行
+- pr：PR 操作（list/create/view/merge/close/review/files/diff）— 973 行
+- release：发布操作（list/create/view/delete）— 179 行
+- repo：仓库操作（含 batch-create/batch-update/batch-delete/batch-member）— 1,781 行
+- search：搜索操作（repos/users）— 88 行
+- team：团队操作（list/create/delete/members）— 192 行
+- user：用户操作（me/info）— 41 行
+- webhook：Webhook 操作（list/create/view/update/delete/test/events）— 649 行
+- wiki：Wiki 操作（list/create/view/update/delete/lint/fix/sync）— 1,612 行
+
+最大的两个模块是 issue（3,058 行）和 wiki（1,612 行）。issue 模块包含批量操作功能，wiki 模块处理双域名架构和 base64 编解码。
+
+批量操作设计模式（以 issue 为例）：
+- BatchResult：单条操作结果（number/action/status/error）
+- BatchSummary：汇总信息（total/succeeded/failed/results）
+- 输入灵活：--numbers（内联）和 --from（CSV 文件）可同时使用
+- dry-run 统一：所有批量命令支持 --dry-run 预览
+- 错误不中断：单条失败不影响后续处理
+
+
+3.3 核心库层设计
+
+核心库层位于 internal/ 目录，包含 7 个子包：
+
+（1）internal/auth — 认证模块（3 个文件，272 行）
+- login.go：登录流程（用户名密码或 Token 粘贴）
+- token_store.go：Token 存储（go-keyring 跨平台支持）
+- transport.go：HTTP Transport，自动在请求 Header 中注入 Bearer Token
+
+（2）internal/client — HTTP 客户端（2 个文件，319 行）
+- client.go：封装 Get/Post/Put/Delete 方法，自动追加 .json 后缀，双重错误检查（HTTP 状态码 + JSON body 中的 status 字段）
+- pagination.go：分页迭代器，自动遍历 Kaminari 风格分页
+
+（3）internal/compliance — 合规检查（4 个文件，685 行）
+- cmd.go：compliance 子命令定义
+- scanner.go：扫描器实现
+- license.go：许可证检测
+- rules.go：合规规则定义
+
+（4）internal/config — 配置管理（1 个文件，125 行）
+- config.go：读写 ~/.config/gitlink-cli/config.yaml
+
+（5）internal/context — 上下文解析（1 个文件，91 行）
+- repo.go：从 git remote 的 origin URL 自动解析 owner 和 repo
+
+（6）internal/errors — 错误处理（1 个文件，150 行）
+- errors.go：统一错误类型 CLIError，包含 Kind（错误分类）、Message、Suggestion、Command 字段
+- 错误分类：KindAuth、KindInput、KindForbidden、KindNotFound、KindServer、KindUnknown
+
+（7）internal/output — 输出格式化（3 个文件，425 行）
+- envelope.go：定义 Envelope 结构体 {OK, Data, Error, Meta}
+- formatter.go：三种输出格式（JSON/YAML/Table），table 使用 tabwriter 对齐，支持 ANSI 颜色、列过滤、值截断控制
+
+
+4、系统动态模型
+
+4.1 用例一：用户认证与仓库操作
+
+用例描述：用户首次使用 gitlink-cli，完成登录并查看仓库信息。
+
+参与者：开发者（终端用户）
+
+前置条件：已安装 gitlink-cli，网络可访问 gitlink.org.cn
+
+主要流程：
+
+（1）用户执行 gitlink-cli auth login
+（2）系统提示输入用户名和密码
+（3）系统调用 POST /api/accounts/login 获取 Token
+（4）Token 存入 OS Keychain
+（5）用户进入 git 仓库目录，执行 gitlink-cli repo +info
+（6）系统从 .git/config 解析 remote origin URL，提取 owner/repo
+（7）系统调用 GET /api/{owner}/{repo}/detail.json
+（8）系统以 table 格式输出仓库信息
+
+异常流程：
+- Token 过期（7 天有效期）：系统返回 401 错误，提示运行 gitlink-cli auth login 重新登录
+- 非 git 目录：系统提示使用 --owner 和 --repo 参数显式指定
+
+API 调用序列：
+POST /api/accounts/login → {token: "..."}
+GET /api/{owner}/{repo}/detail.json → {name, description, default_branch, ...}
+
+
+4.2 用例二：Issue 批量管理
+
+用例描述：项目维护者批量关闭过期 Issue 并批量创建新 Issue。
+
+参与者：项目维护者
+
+前置条件：已登录，有仓库写权限
+
+主要流程：
+
+（1）用户执行 gitlink-cli issue +batch-close --numbers 101,102,103,104 --dry-run
+（2）系统预览：显示 4 个 Issue 将被关闭，不实际执行
+（3）用户确认后去掉 --dry-run，重新执行
+（4）系统逐个调用 PUT /api/{owner}/{repo}/issues/{number}，设置 state 为 closed
+（5）系统输出 BatchSummary：total=4, succeeded=4, failed=0
+
+（6）用户准备 CSV 文件 issues.csv：
+title,body,priority,label
+"登录页面样式异常","点击按钮后样式错乱","high","缺陷"
+"新增数据导出功能","支持 CSV 和 JSON 格式导出","normal","功能"
+
+（7）用户执行 gitlink-cli issue +batch-create --from issues.csv --template bug
+（8）系统逐个调用 POST /api/{owner}/{repo}/issues 创建 Issue
+（9）系统输出 BatchSummary：total=2, succeeded=2, failed=0
+
+异常流程：
+- 单条操作失败：记录错误，继续处理后续条目，最终 exit code = 1
+- API 字段静默失败：GitLink 对不认识的字段返回 200 而非报错，需通过浏览器 DevTools 确认字段名
+
+
+4.3 用例三：AI 自动化工作流
+
+用例描述：使用 Claude Code 和 gitlink-cli Skill 自动完成社区运营任务。
+
+参与者：社区运营者（通过 Claude Code 交互）
+
+前置条件：Claude Code 已安装，gitlink-cli 已登录
+
+主要流程：
+
+（1）用户在 Claude Code 中说"帮我跑社区运营工作流"
+（2）Claude Code 触发 gitlink-workflows skill，显示功能菜单
+（3）用户选择"社区运营自动化"
+（4）Claude Code 调用 gitlink-cli issue +list --state open --format json
+（5）Claude Code 分析 Issue 列表，按类型分类（bug/feature/question）
+（6）Claude Code 调用 gitlink-cli issue +label-add 添加分类标签
+（7）Claude Code 调用 gitlink-cli pr +list 获取近期 PR
+（8）Claude Code 生成周报摘要，包含 Issue 统计、PR 合并情况、贡献者活跃度
+
+Skill 调用链：
+gitlink-shared（认证检查）→ gitlink-issue（Issue 操作）→ gitlink-pr（PR 操作）→ gitlink-workflow（工作流编排）
+
+
+5、系统部署模型
+
+本项目采用单二进制分发模式，部署简单。
+
+（1）构建环境：
+- Go 1.26.1+
+- Makefile 管理构建流程
+- 构建命令：make build（通过 -ldflags 注入版本号）
+
+（2）分发方式：
+- 直接下载：从 GitHub Releases 下载预编译二进制
+- npm 安装：npm install -g gitlink-cli
+- 源码编译：go install github.com/gitlink-org/gitlink-cli@latest
+- 安装脚本：install.sh（Linux/macOS）、install.ps1（Windows）
+
+（3）目标平台：
+- Windows（amd64）
+- macOS（amd64、arm64）
+- Linux（amd64、arm64）
+
+（4）依赖服务：
+- GitLink API：https://www.gitlink.org.cn/api（主站 API）
+- GitLink Gateway：https://gateway.gitlink.org.cn/api（Wiki API 专用）
+- OS Keychain：系统密钥管理服务（存储 Token）
+
+（5）CI/CD 集成：
+- GitHub Actions：.github/workflows/release.yml 自动构建和发布
+- GitLink DevOps：.devops/gitlink-cli-autodeploy.yml 平台自动部署
+
+（6）部署架构：
+
+用户终端
+    ↓
+gitlink-cli（本地二进制）
+    ↓ HTTP/HTTPS
+GitLink API Server（gitlink.org.cn）
+    ↓
+GitLink Gateway（gateway.gitlink.org.cn，Wiki 专用）
+
+gitlink-cli 是纯客户端工具，不运行后台服务。所有数据存储在用户本地（配置文件 + OS Keychain），业务数据完全来自 GitLink 平台 API 的实时查询。
--- a/BIN
+++ b/BIN
--- a/gitlink-cli.exe
+++ b/gitlink-cli.exe
--- a/internal/compliance/cmd.go
+++ b/internal/compliance/cmd.go
@ -0,0 +1,229 @@
+package compliance
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/gitlink-org/gitlink-cli/internal/output"
+)
+
+// NewCommand returns the top-level compliance command.
+func NewCommand() *cobra.Command {
+	var format string
+
+	cmd := &cobra.Command{
+		Use:   "compliance",
+		Short: "Compliance and security scan operations",
+		Long:  "Run license compliance checks, dependency scanning, secret detection, and exposure analysis on local repositories.",
+	}
+
+	cmd.PersistentFlags().StringVar(&format, "format", "table", "Output format: json, table")
+
+	cmd.AddCommand(newScanCmd(&format))
+	cmd.AddCommand(newLicenseCmd(&format))
+	cmd.AddCommand(newDepsCmd(&format))
+	cmd.AddCommand(newSecretsCmd(&format))
+	cmd.AddCommand(newExposureCmd(&format))
+	cmd.AddCommand(newVocabCmd(&format))
+
+	return cmd
+}
+
+func newScanCmd(format *string) *cobra.Command {
+	var module string
+	cmd := &cobra.Command{
+		Use:   "+scan",
+		Short: "Full compliance scan (all five modules)",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, err := repoRoot()
+			if err != nil {
+				return err
+			}
+			modules := []string{"secrets", "exposure", "vocab"}
+			if module != "" {
+				modules = parseModules(module)
+			}
+			var allFindings []Finding
+			for _, m := range modules {
+				switch m {
+				case "license":
+					allFindings = append(allFindings, checkLicense(root)...)
+					break
+				case "deps":
+					allFindings = append(allFindings, checkDeps(root)...)
+					break
+				case "secrets", "exposure", "vocab":
+					rules := allRules()[m]
+					allFindings = append(allFindings, scanFiles(root, rules)...)
+					break
+				}
+			}
+			return outputReport(allFindings, modules, *format)
+		},
+	}
+	cmd.Flags().StringVarP(&module, "module", "m", "", "Comma-separated modules: license,deps,secrets,exposure,vocab")
+	return cmd
+}
+
+func newLicenseCmd(format *string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "+license",
+		Short: "License compliance check",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, _ := repoRoot()
+			findings := checkLicense(root)
+			return outputReport(findings, []string{"license"}, *format)
+		},
+	}
+}
+
+func newDepsCmd(format *string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "+deps",
+		Short: "Dependency license check",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, _ := repoRoot()
+			findings := checkDeps(root)
+			return outputReport(findings, []string{"deps"}, *format)
+		},
+	}
+}
+
+func newSecretsCmd(format *string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "+secrets",
+		Short: "Hardcoded secrets scan",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, _ := repoRoot()
+			findings := scanFiles(root, allRules()["secrets"])
+			return outputReport(findings, []string{"secrets"}, *format)
+		},
+	}
+}
+
+func newExposureCmd(format *string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "+exposure",
+		Short: "PII and network exposure scan",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, _ := repoRoot()
+			findings := scanFiles(root, allRules()["exposure"])
+			return outputReport(findings, []string{"exposure"}, *format)
+		},
+	}
+}
+
+func newVocabCmd(format *string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "+vocab",
+		Short: "Sensitive vocabulary scan",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root, _ := repoRoot()
+			findings := scanFiles(root, allRules()["vocab"])
+			return outputReport(findings, []string{"vocab"}, *format)
+		},
+	}
+}
+
+func repoRoot() (string, error) {
+	dir, err := os.Getwd()
+	if err != nil {
+		return "", fmt.Errorf("get working directory: %w", err)
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(dir, ".git")); err == nil {
+			return dir, nil
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			return dir, nil
+		}
+		dir = parent
+	}
+}
+
+func parseModules(s string) []string {
+	var result []string
+	seen := map[string]bool{}
+	for _, m := range strings.Split(s, ",") {
+		m = strings.TrimSpace(m)
+		valid := map[string]bool{"license": true, "deps": true, "secrets": true, "exposure": true, "vocab": true}
+		if valid[m] && !seen[m] {
+			result = append(result, m)
+			seen[m] = true
+		}
+	}
+	return result
+}
+
+// summary holds aggregated stats.
+type summary struct {
+	Total    int `json:"total"`
+	Critical int `json:"critical"`
+	High     int `json:"high"`
+	Medium   int `json:"medium"`
+	Low      int `json:"low"`
+}
+
+type reportData struct {
+	Modules  []string  `json:"modules"`
+	Findings []Finding `json:"findings"`
+	Summary  summary   `json:"summary"`
+}
+
+func outputReport(findings []Finding, modules []string, format string) error {
+	s := summary{}
+	for _, f := range findings {
+		s.Total++
+		switch f.Severity {
+		case "critical":
+			s.Critical++
+		case "high":
+			s.High++
+		case "medium":
+			s.Medium++
+		case "low":
+			s.Low++
+		}
+	}
+
+	if format == "json" {
+		return output.Print(output.SuccessEnvelope(reportData{Modules: modules, Findings: findings, Summary: s}, nil), format)
+	}
+
+	fmt.Println()
+	printHR()
+	fmt.Printf("  Compliance Scan Report\n")
+	fmt.Printf("  Modules: %s |  Findings: %d  (critical:%d high:%d medium:%d low:%d)\n",
+		strings.Join(modules, ", "), s.Total, s.Critical, s.High, s.Medium, s.Low)
+	printHR()
+
+	if len(findings) == 0 {
+		fmt.Println("  All clear — no issues found.")
+	} else {
+		printFindings(findings)
+	}
+	printHR()
+	return nil
+}
+
+func printHR() {
+	fmt.Println(strings.Repeat("─", 60))
+}
+
+func printFindings(findings []Finding) {
+	labels := map[string]string{
+		"critical": "CRIT", "high": "HIGH", "medium": "MED", "low": "LOW",
+	}
+	for _, f := range findings {
+		label := labels[f.Severity]
+		if label == "" {
+			label = f.Severity
+		}
+		fmt.Printf("  [%s] %s  %s:%d  %s\n", label, f.ID, f.File, f.Line, f.Summary)
+	}
+}
--- a/shortcuts/compliance/license.go
+++ b/shortcuts/compliance/license.go
--- a/shortcuts/compliance/rules.go
+++ b/shortcuts/compliance/rules.go
--- a/shortcuts/compliance/scanner.go
+++ b/shortcuts/compliance/scanner.go
@ -42,7 +42,7 @@ var excludedDirs = map[string]bool{

 // excludedPaths are relative paths skipped (scanner's own source to avoid self-scan).
 var excludedPaths = map[string]bool{
-	"shortcuts/compliance": true,
+	"internal/compliance": true,
 }

 // excludedExts are file extensions skipped during scanning.
--- a/internal/errors/errors.go
+++ b/internal/errors/errors.go
@ -108,6 +108,41 @@ func ConfigError(message string, cause error) *CLIError {
 		fmt.Sprintf("检查配置文件 %s 是否正确", configPathPlaceholder()), cause)
 }

+// OpError creates a unified operation-failure error.
+// op is the English verb (e.g., "list", "create"), resource is the target (e.g., "issues").
+// The Message is in English; Suggestion is in Chinese for user guidance.
+func OpError(kind ErrorKind, op, resource string, cause error) *CLIError {
+	msg := fmt.Sprintf("failed to %s %s", op, resource)
+	sugg := opSuggestion(op, resource)
+	e := Wrap(kind, msg, sugg, cause)
+	return e
+}
+
+// opSuggestion returns a Chinese suggestion for the given operation.
+func opSuggestion(op, resource string) string {
+	suggestions := map[string]string{
+		"list":    "获取列表失败，请检查参数或网络连接，稍后重试",
+		"create":  "创建失败，请检查必填参数是否正确（--help 查看用法）或 API 权限",
+		"view":    "查看失败，请确认资源 ID 是否存在",
+		"update":  "更新失败，请检查参数值或资源 ID 是否正确",
+		"delete":  "删除失败，请确认资源是否存在或是否有删除权限",
+		"close":   "关闭失败，请确认资源是否存在或已被关闭",
+		"reopen":  "重新打开失败，请确认资源是否存在",
+		"merge":   "合并失败，请检查是否有冲突或权限不足",
+		"comment": "添加评论失败，请确认资源是否存在",
+		"approve": "评审操作失败，请确认 PR 是否存在",
+		"scan":    "扫描失败，请稍后重试",
+		"invite":  "邀请失败，请确认用户 ID 是否正确",
+		"remove":  "移除失败，请确认成员存在",
+		"fork":    "Fork 失败，请确认仓库存在或有权限",
+		"search":  "搜索失败，请稍后重试",
+	}
+	if s, ok := suggestions[op]; ok {
+		return s
+	}
+	return fmt.Sprintf("操作失败，请稍后重试或运行 --help 查看用法")
+}
+
 // configPathPlaceholder avoids circular import; the actual path will be resolved
 // in output formatting.
 func configPathPlaceholder() string {
--- a/internal/output/formatter.go
+++ b/internal/output/formatter.go
@ -9,29 +9,48 @@ import (
 	"strings"
 	"text/tabwriter"

+	"golang.org/x/term"
 	"gopkg.in/yaml.v3"
 )

+// PrintOptions controls table output rendering behavior.
+type PrintOptions struct {
+	Columns    []string // column names to show (nil = all)
+	NoTruncate bool     // disable 60-char truncation
+	UseColor   bool     // enable ANSI color headers
+}
+
+// Print outputs the envelope in the given format with default options.
 func Print(envelope *Envelope, format string) error {
+	return PrintWithOpts(envelope, format, PrintOptions{})
+}
+
+// PrintWithOpts outputs the envelope with rendering options.
+func PrintWithOpts(envelope *Envelope, format string, opts PrintOptions) error {
 	if format == "" {
 		format = "json"
 	}
-	return PrintTo(os.Stdout, envelope, format)
+	return printToOpts(os.Stdout, envelope, format, opts)
 }

-func PrintTo(w io.Writer, envelope *Envelope, format string) error {
+func printToOpts(w io.Writer, envelope *Envelope, format string, opts PrintOptions) error {
 	switch format {
 	case "json":
 		return printJSON(w, envelope)
 	case "yaml":
 		return printYAML(w, envelope)
 	case "table":
-		return printTable(w, envelope)
+		return printTableOpts(w, envelope, opts)
 	default:
 		return printJSON(w, envelope)
 	}
 }

+// PrintTo outputs the envelope to the given writer (legacy, no options).
+func PrintTo(w io.Writer, envelope *Envelope, format string) error {
+	return printToOpts(w, envelope, format, PrintOptions{})
+}
+
 func printJSON(w io.Writer, envelope *Envelope) error {
 	data, err := json.MarshalIndent(envelope, "", "  ")
 	if err != nil {
@ -50,7 +69,7 @@ func printYAML(w io.Writer, envelope *Envelope) error {
 	return err
 }

-func printTable(w io.Writer, envelope *Envelope) error {
+func printTableOpts(w io.Writer, envelope *Envelope, opts PrintOptions) error {
 	if !envelope.OK {
 		if envelope.Error != nil {
 			fmt.Fprintf(w, "Error: %s\n", envelope.Error.Message)
@ -66,22 +85,72 @@ func printTable(w io.Writer, envelope *Envelope) error {
 		return nil
 	}

-	// Try to render as table if data is a slice of maps
 	switch data := envelope.Data.(type) {
 	case []interface{}:
-		return printSliceTable(w, data)
+		return printSliceTableOpts(w, data, opts)
 	case map[string]interface{}:
-		// For maps with nested structures, prefer JSON
+		if unwrapped := unwrapSingleListField(data); unwrapped != nil {
+			return printSliceTableOpts(w, unwrapped, opts)
+		}
 		if hasComplexValues(data) {
 			return printJSON(w, envelope)
 		}
-		return printMapTable(w, data)
+		return printMapTableOpts(w, data, opts)
 	default:
-		// Fallback to JSON
 		return printJSON(w, envelope)
 	}
 }

+// printTable is kept for backward compatibility with existing callers.
+func printTable(w io.Writer, envelope *Envelope) error {
+	return printTableOpts(w, envelope, PrintOptions{})
+}
+
+// unwrapSingleListField detects wrapper map structures like {"items":[...], "count":N}
+// and returns the inner slice for list rendering.
+func unwrapSingleListField(m map[string]interface{}) []interface{} {
+	knownListFields := []string{
+		"projects", "webhooks", "issues", "users", "pull_requests",
+		"builds", "releases", "branches", "teams", "members",
+		"orgs", "items", "records", "results", "wikis", "search",
+	}
+
+	for _, name := range knownListFields {
+		if s, ok := m[name].([]interface{}); ok {
+			if isSliceOfMaps(s) {
+				return s
+			}
+		}
+	}
+
+	// fallback: single slice-of-maps field
+	var listField string
+	var listValue []interface{}
+	for k, v := range m {
+		s, ok := v.([]interface{})
+		if !ok {
+			continue
+		}
+		if !isSliceOfMaps(s) {
+			continue
+		}
+		if listField != "" {
+			return nil // multiple list fields, can't auto-unwrap
+		}
+		listField = k
+		listValue = s
+	}
+	return listValue
+}
+
+func isSliceOfMaps(s []interface{}) bool {
+	if len(s) == 0 {
+		return true
+	}
+	_, ok := s[0].(map[string]interface{})
+	return ok
+}
+
 func hasComplexValues(m map[string]interface{}) bool {
 	for _, v := range m {
 		switch v.(type) {
@ -92,13 +161,12 @@ func hasComplexValues(m map[string]interface{}) bool {
 	return false
 }

-func printSliceTable(w io.Writer, items []interface{}) error {
+func printSliceTableOpts(w io.Writer, items []interface{}, opts PrintOptions) error {
 	if len(items) == 0 {
 		fmt.Fprintln(w, "No results")
 		return nil
 	}

-	// Collect headers from first item
 	first, ok := items[0].(map[string]interface{})
 	if !ok {
 		data, _ := json.MarshalIndent(items, "", "  ")
@ -107,10 +175,23 @@ func printSliceTable(w io.Writer, items []interface{}) error {
 	}

 	headers := collectKeys(first)
+
+	// apply --columns filter
+	if len(opts.Columns) > 0 {
+		headers = filterColumns(headers, opts.Columns)
+	}
+
+	useColor := opts.UseColor && isTerminal(w)
+
 	tw := tabwriter.NewWriter(w, 0, 4, 2, ' ', 0)

 	// Print headers
-	fmt.Fprintln(tw, strings.Join(headers, "\t"))
+	headerLine := strings.Join(headers, "\t")
+	if useColor {
+		headerLine = colorHeader(headerLine)
+	}
+	fmt.Fprintln(tw, headerLine)
+
 	dashes := make([]string, len(headers))
 	for i, h := range headers {
 		dashes[i] = strings.Repeat("-", len(h))
@ -125,26 +206,43 @@ func printSliceTable(w io.Writer, items []interface{}) error {
 		}
 		vals := make([]string, len(headers))
 		for i, h := range headers {
-			vals[i] = formatValue(m[h])
+			vals[i] = formatValueOpts(m[h], opts.NoTruncate)
 		}
 		fmt.Fprintln(tw, strings.Join(vals, "\t"))
 	}
 	return tw.Flush()
 }

-func printMapTable(w io.Writer, m map[string]interface{}) error {
+func printMapTableOpts(w io.Writer, m map[string]interface{}, opts PrintOptions) error {
 	tw := tabwriter.NewWriter(w, 0, 4, 2, ' ', 0)
-	fmt.Fprintln(tw, "KEY\tVALUE")
+	headerLine := "KEY\tVALUE"
+	if opts.UseColor && isTerminal(w) {
+		headerLine = colorHeader(headerLine)
+	}
+	fmt.Fprintln(tw, headerLine)
 	fmt.Fprintln(tw, "---\t-----")
 	for k, v := range m {
-		fmt.Fprintf(tw, "%s\t%s\n", k, formatValue(v))
+		fmt.Fprintf(tw, "%s\t%s\n", k, formatValueOpts(v, opts.NoTruncate))
 	}
 	return tw.Flush()
 }

+func filterColumns(all, wanted []string) []string {
+	wantedSet := make(map[string]bool, len(wanted))
+	for _, w := range wanted {
+		wantedSet[w] = true
+	}
+	result := make([]string, 0, len(wanted))
+	for _, h := range all {
+		if wantedSet[h] {
+			result = append(result, h)
+		}
+	}
+	return result
+}
+
 func collectKeys(m map[string]interface{}) []string {
 	keys := make([]string, 0, len(m))
-	// Prefer common keys first
 	priority := []string{"id", "name", "login", "title", "status", "state", "created_at", "updated_at"}
 	seen := map[string]bool{}
 	for _, k := range priority {
@ -162,6 +260,10 @@ func collectKeys(m map[string]interface{}) []string {
 }

 func formatValue(v interface{}) string {
+	return formatValueOpts(v, false)
+}
+
+func formatValueOpts(v interface{}, noTruncate bool) string {
 	if v == nil {
 		return ""
 	}
@ -170,7 +272,7 @@ func formatValue(v interface{}) string {
 	case reflect.Map, reflect.Slice:
 		data, _ := json.Marshal(v)
 		s := string(data)
-		if len(s) > 60 {
+		if !noTruncate && len(s) > 60 {
 			return s[:57] + "..."
 		}
 		return s
@ -178,3 +280,21 @@ func formatValue(v interface{}) string {
 		return fmt.Sprintf("%v", v)
 	}
 }
+
+// --- color helpers ---
+
+const (
+	ansiHeader = "\033[1;36m" // bold cyan
+	ansiReset  = "\033[0m"
+)
+
+func colorHeader(s string) string {
+	return ansiHeader + s + ansiReset
+}
+
+func isTerminal(w io.Writer) bool {
+	if f, ok := w.(*os.File); ok {
+		return term.IsTerminal(int(f.Fd()))
+	}
+	return false
+}
--- a/internal/output/formatter_test.go
+++ b/internal/output/formatter_test.go
@ -0,0 +1,81 @@
+package output
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestPrintTable_WrappedEmptyList(t *testing.T) {
+	env := &Envelope{OK: true, Data: map[string]interface{}{
+		"count":    0,
+		"projects": []interface{}{},
+	}}
+	var buf bytes.Buffer
+	if err := PrintTo(&buf, env, "table"); err != nil {
+		t.Fatalf("PrintTo failed: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, "No results") {
+		t.Errorf("expected 'No results', got: %q", got)
+	}
+}
+
+func TestPrintTable_WrappedList(t *testing.T) {
+	env := &Envelope{OK: true, Data: map[string]interface{}{
+		"count": 2,
+		"projects": []interface{}{
+			map[string]interface{}{"id": 1.0, "name": "alpha"},
+			map[string]interface{}{"id": 2.0, "name": "beta"},
+		},
+	}}
+	var buf bytes.Buffer
+	if err := PrintTo(&buf, env, "table"); err != nil {
+		t.Fatalf("PrintTo failed: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, "alpha") || !strings.Contains(got, "beta") {
+		t.Errorf("expected alpha/beta in output, got: %q", got)
+	}
+	if !strings.Contains(got, "id") || !strings.Contains(got, "name") {
+		t.Errorf("expected header id/name, got: %q", got)
+	}
+}
+
+func TestUnwrapSingleListField_KnownName(t *testing.T) {
+	m := map[string]interface{}{
+		"count":    2.0,
+		"projects": []interface{}{map[string]interface{}{"id": 1.0}},
+	}
+	got := unwrapSingleListField(m)
+	if got == nil || len(got) != 1 {
+		t.Fatalf("expected slice len=1, got %v", got)
+	}
+}
+
+func TestUnwrapSingleListField_MultipleUnknownListsReturnsNil(t *testing.T) {
+	// 两个未知名字的 list 字段 — 无法自动选择，返回 nil
+	m := map[string]interface{}{
+		"foo_list": []interface{}{map[string]interface{}{"id": 1.0}},
+		"bar_list": []interface{}{map[string]interface{}{"id": 2.0}},
+	}
+	if got := unwrapSingleListField(m); got != nil {
+		t.Errorf("expected nil for multiple unknown list fields, got len=%d", len(got))
+	}
+}
+
+func TestUnwrapSingleListField_KnownNamePreferred(t *testing.T) {
+	// 已知 name 优先 — 即使有其他 list 字段也用 known name
+	m := map[string]interface{}{
+		"projects": []interface{}{map[string]interface{}{"id": 1.0}},
+		"users":    []interface{}{map[string]interface{}{"id": 2.0}},
+	}
+	got := unwrapSingleListField(m)
+	if got == nil || len(got) != 1 {
+		t.Fatalf("expected projects slice len=1, got %v", got)
+	}
+	first := got[0].(map[string]interface{})
+	if first["id"] != 1.0 {
+		t.Errorf("expected projects[0].id=1, got %v", first["id"])
+	}
+}
--- a/npm/bin/gitlink-cli.exe
+++ b/npm/bin/gitlink-cli.exe
--- a/output/knowledge-graph-2026-07-06.html
+++ b/output/knowledge-graph-2026-07-06.html
@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>科研知识图谱 — 2026-07-06</title>
+<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f7fa; color: #333; }
+.header { background: linear-gradient(135deg, #1a237e 0%, #3949ab 100%); color: #fff; padding: 36px 30px; }
+.header h1 { font-size: 26px; margin-bottom: 6px; }
+.header .subtitle { opacity: 0.8; font-size: 14px; }
+.container { max-width: 1400px; margin: 0 auto; padding: 20px; }
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 14px; margin-bottom: 24px; }
+.card { background: #fff; border-radius: 12px; padding: 18px; box-shadow: 0 2px 8px rgba(0,0,0,.08); text-align: center; }
+.card .value { font-size: 32px; font-weight: 700; color: #1a237e; }
+.card .label { font-size: 12px; color: #888; margin-top: 4px; }
+.panel { background: #fff; border-radius: 12px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,.08); margin-bottom: 24px; }
+.panel h2 { font-size: 18px; margin-bottom: 16px; color: #1a237e; border-bottom: 2px solid #3949ab; padding-bottom: 8px; }
+#graphChart { width: 100%; height: 600px; }
+table { width: 100%; border-collapse: collapse; }
+th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid #eee; font-size: 13px; }
+th { background: #f5f7fa; color: #555; font-weight: 600; }
+.tag { display: inline-block; padding: 2px 10px; border-radius: 12px; font-size: 12px; margin: 2px; }
+.tag.rising { background: #e8f5e9; color: #2e7d32; }
+.tag.stable { background: #e3f2fd; color: #1565c0; }
+.tag.declining { background: #fce4ec; color: #c62828; }
+.footer { text-align: center; padding: 24px; color: #999; font-size: 12px; }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>科研知识图谱</h1>
+  <div class="subtitle">
+    关键词：LLM,Agent &mdash;
+    仓库：4 个 &mdash;
+    贡献者：0 人 &mdash;
+    2026-07-06
+  </div>
+</div>
+<div class="container">
+
+<div class="cards">
+  <div class="card"><div class="value">4</div><div class="label">仓库节点</div></div>
+  <div class="card"><div class="value">0</div><div class="label">贡献者节点</div></div>
+  <div class="card"><div class="value">2</div><div class="label">主题节点</div></div>
+  <div class="card"><div class="value">3</div><div class="label">关系边</div></div>
+  <div class="card"><div class="value">N/A</div><div class="label">最热仓库</div></div>
+</div>
+
+<div class="panel">
+  <h2>知识图谱 — 力导向布局</h2>
+  <div id="graphChart"></div>
+</div>
+
+<div class="panel">
+  <h2>热度排行榜</h2>
+  <table id="hotnessTable">
+    <thead><tr><th>排名</th><th>仓库</th><th>热度</th><th>语言</th><th>Stars</th><th>趋势</th></tr></thead>
+    <tbody></tbody>
+  </table>
+</div>
+
+</div>
+<div class="footer">Generated by GitLink Research Assistant — 2026-07-06</div>
+
+<script>
+var graph = echarts.init(document.getElementById('graphChart'));
+graph.setOption({
+  tooltip: {
+    formatter: function(p) {
+      if (p.dataType === 'edge') return p.data.source + ' → ' + p.data.target + '<br/>' + p.data.evidence;
+      var d = p.data;
+      return '<b>' + d.label + '</b><br/>' + (d.desc || '') + '<br/>' +
+        (d.stars ? 'Stars: ' + d.stars : '') + (d.repo_count ? ' 关联仓库: ' + d.repo_count : '');
+    }
+  },
+  legend: [{
+    data: ['仓库', '贡献者', '主题', '论文', '组织'],
+    orient: 'vertical', right: 10, top: 20
+  }],
+  series: [{
+    type: 'graph',
+    layout: 'force',
+    roam: true,
+    draggable: true,
+    force: {
+      repulsion: 200,
+      edgeLength: [80, 300],
+      layoutAnimation: true
+    },
+    categories: [
+      { name: '仓库', itemStyle: { color: '#5470c6' }, symbol: 'roundRect' },
+      { name: '贡献者', itemStyle: { color: '#91cc75' }, symbol: 'circle' },
+      { name: '主题', itemStyle: { color: '#fac858' }, symbol: 'diamond' },
+      { name: '论文', itemStyle: { color: '#ee6666' }, symbol: 'triangle' },
+      { name: '组织', itemStyle: { color: '#73c0de' }, symbol: 'pin' }
+    ],
+    data: [{"id":"topic:llm","type":"topic","label":"LLM\n","symbolSize":30,"category":2},{"id":"topic:agent","type":"topic","label":"Agent\n","symbolSize":30,"category":2}],
+    links: [{"source":"repo:agent","target":"repo:ribo-agent","type":"related_to","weight":0.5,"evidence":"共同主题: Agent\n"},{"source":"repo:doutrip","target":"repo:agent","type":"related_to","weight":0.5,"evidence":"共同主题: Agent\n"},{"source":"repo:ribo-agent","target":"repo:wow-agent","type":"related_to","weight":0.5,"evidence":"共同主题: Agent\n"}],
+    label: { show: true, fontSize: 11, formatter: '{b}' },
+    emphasis: { focus: 'adjacency', label: { fontSize: 14 } },
+    lineStyle: { color: '#ccc', curveness: 0.1 }
+  }]
+});
+window.addEventListener('resize', function() { graph.resize(); });
+</script>
+</body>
+</html>
--- a/output/knowledge-graph-2026-07-06.json
+++ b/output/knowledge-graph-2026-07-06.json
@ -0,0 +1,51 @@
+{
+  "metadata": {
+    "generated_at": "2026-07-06T11:51:35+08:00",
+    "search_keywords": [
+      "LLM",
+      "Agent"
+    ],
+    "total_repos_scanned": 4,
+    "total_contributors_found": 0,
+    "total_edges_inferred": 3
+  },
+  "nodes": [
+    {
+      "id": "topic:llm",
+      "type": "topic",
+      "label": "LLM\n",
+      "symbolSize": 30,
+      "category": 2
+    },
+    {
+      "id": "topic:agent",
+      "type": "topic",
+      "label": "Agent\n",
+      "symbolSize": 30,
+      "category": 2
+    }
+  ],
+  "edges": [
+    {
+      "source": "repo:agent",
+      "target": "repo:ribo-agent",
+      "type": "related_to",
+      "weight": 0.5,
+      "evidence": "共同主题: Agent\n"
+    },
+    {
+      "source": "repo:doutrip",
+      "target": "repo:agent",
+      "type": "related_to",
+      "weight": 0.5,
+      "evidence": "共同主题: Agent\n"
+    },
+    {
+      "source": "repo:ribo-agent",
+      "target": "repo:wow-agent",
+      "type": "related_to",
+      "weight": 0.5,
+      "evidence": "共同主题: Agent\n"
+    }
+  ]
+}
--- a/output/reproducibility-gitlink-cli-2026-07-06.html
+++ b/output/reproducibility-gitlink-cli-2026-07-06.html
@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>zzx-coder/gitlink-cli — 复现性评分卡</title>
+<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f7fa; color: #333; }
+.header { background: linear-gradient(135deg, #1a237e 0%, #3949ab 100%); color: #fff; padding: 40px 30px; }
+.header h1 { font-size: 26px; margin-bottom: 6px; }
+.container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+.row { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 20px; margin-bottom: 24px; }
+.panel { background: #fff; border-radius: 12px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,.08); }
+.panel h2 { font-size: 18px; margin-bottom: 16px; color: #1a237e; border-bottom: 2px solid #3949ab; padding-bottom: 8px; }
+.chart { width: 100%; height: 350px; }
+.grade-circle { text-align: center; padding: 20px; }
+.grade-letter { font-size: 72px; font-weight: 900; }
+.grade-A { color: #2e7d32; }
+.grade-B { color: #558b2f; }
+.grade-C { color: #f57c00; }
+.grade-D { color: #e65100; }
+.grade-F { color: #c62828; }
+.grade-score { font-size: 24px; color: #888; }
+table { width: 100%; border-collapse: collapse; }
+th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid #eee; font-size: 13px; }
+th { background: #f5f7fa; color: #555; }
+.bar { height: 8px; border-radius: 4px; background: #e0e0e0; margin-top: 4px; }
+.bar-fill { height: 100%; border-radius: 4px; }
+.footer { text-align: center; padding: 24px; color: #999; font-size: 12px; }
+@media (max-width: 768px) { .row { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>zzx-coder/gitlink-cli — 科研复现性评分卡</h1>
+  <div style="opacity:0.8;font-size:14px;">2026-07-06</div>
+</div>
+<div class="container">
+
+<div class="row">
+  <div class="panel grade-circle">
+    <div class="grade-letter grade-F">F</div>
+    <div class="grade-score">5.0 / 100</div>
+    <div style="margin-top:12px;color:#888;">
+      
+      
+      
+      
+      差 — 几乎不可复现
+    </div>
+  </div>
+  <div class="panel">
+    <h2>维度雷达图</h2>
+    <div id="radarChart" class="chart"></div>
+  </div>
+  <div class="panel">
+    <h2>维度明细</h2>
+    <table>
+      <tr><th>维度</th><th>评分</th><th>权重</th></tr>
+      <tr><td>许可证</td><td>0%</td><td>15%</td></tr>
+      <tr><td>无密钥/PII</td><td>0%</td><td>15%</td></tr>
+      <tr><td>README 完整</td><td>0%</td><td>15%</td></tr>
+      <tr><td>依赖声明</td><td>0%</td><td>15%</td></tr>
+      <tr><td>构建说明</td><td>50%</td><td>10%</td></tr>
+      <tr><td>CI 配置</td><td>0%</td><td>10%</td></tr>
+      <tr><td>测试证据</td><td>0%</td><td>10%</td></tr>
+      <tr><td>数据可用性</td><td>0%</td><td>10%</td></tr>
+    </table>
+  </div>
+</div>
+
+<div class="panel">
+  <h2>详细评估与改进建议</h2>
+  <table>
+    <tr><th>维度</th><th>评分</th><th>证据</th><th>建议</th></tr>
+    <tr>
+      <td>许可证</td>
+      <td>❌</td>
+      <td>未扫描（无本地仓库）</td>
+      <td>建议添加 MIT/Apache-2.0/GPL-3.0 许可证</td>
+    </tr>
+    <tr>
+      <td>无密钥/PII</td>
+      <td>⚠️</td>
+      <td>未扫描（无本地仓库）</td>
+      <td>立即移除泄露的密钥，使用环境变量管理敏感信息</td>
+    </tr>
+    <tr>
+      <td>README 完整</td>
+      <td>❌</td>
+      <td>README 缺失或过于简略</td>
+      <td>补充项目目的、安装、使用、许可和引用章节</td>
+    </tr>
+    <tr>
+      <td>依赖声明</td>
+      <td>❌</td>
+      <td>无依赖声明</td>
+      <td>添加 package.json/go.mod/requirements.txt 等标准依赖文件</td>
+    </tr>
+    <tr>
+      <td>构建说明</td>
+      <td>⚠️</td>
+      <td>部分构建说明</td>
+      <td>添加 Makefile/Dockerfile + README 中的构建步骤</td>
+    </tr>
+    <tr>
+      <td>CI 配置</td>
+      <td>❌</td>
+      <td>无 CI 配置</td>
+      <td>配置 GitLink CI 或 GitHub Actions 自动构建和测试</td>
+    </tr>
+    <tr>
+      <td>测试证据</td>
+      <td>❌</td>
+      <td>无测试证据</td>
+      <td>添加单元测试和集成测试，在 README 中说明如何运行</td>
+    </tr>
+    <tr>
+      <td>数据可用性</td>
+      <td>❌</td>
+      <td>无数据可用性声明</td>
+      <td>说明数据集来源，提供 Zenodo/Figshare 链接或生成脚本</td>
+    </tr>
+  </table>
+</div>
+
+</div>
+<div class="footer">Generated by GitLink Research Assistant — 2026-07-06</div>
+
+<script>
+var radarChart = echarts.init(document.getElementById('radarChart'));
+radarChart.setOption({
+  radar: {
+    indicator: [
+      { name: '许可证', max: 100 },
+      { name: '无密钥', max: 100 },
+      { name: 'README', max: 100 },
+      { name: '依赖', max: 100 },
+      { name: '构建', max: 100 },
+      { name: 'CI', max: 100 },
+      { name: '测试', max: 100 },
+      { name: '数据', max: 100 }
+    ],
+    center: ['50%', '55%'],
+    radius: '70%'
+  },
+  series: [{
+    type: 'radar',
+    data: [{
+      value: [
+        0,
+        0,
+        0,
+        0,
+        50,
+        0,
+        0,
+        0
+      ],
+      name: '复现性',
+      areaStyle: { color: 'rgba(57,73,171,0.3)' },
+      lineStyle: { color: '#3949ab' }
+    }]
+  }]
+});
+</script>
+</body>
+</html>
--- a/output/research-insights-gitlink-cli-2026-07-06.html
+++ b/output/research-insights-gitlink-cli-2026-07-06.html
@ -0,0 +1,149 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>zzx-coder/gitlink-cli — 科研项目洞察报告</title>
+<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f7fa; color: #333; }
+.header { background: linear-gradient(135deg, #1a237e 0%, #283593 50%, #3949ab 100%); color: #fff; padding: 40px 30px; }
+.header h1 { font-size: 28px; margin-bottom: 8px; }
+.header .subtitle { opacity: 0.85; font-size: 14px; }
+.container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-bottom: 24px; }
+.card { background: #fff; border-radius: 12px; padding: 20px; box-shadow: 0 2px 8px rgba(0,0,0,.08); }
+.card .label { font-size: 12px; color: #888; text-transform: uppercase; margin-bottom: 6px; }
+.card .value { font-size: 28px; font-weight: 700; }
+.card .value.hot { color: #e53935; }
+.card .value.warm { color: #f57c00; }
+.card .value.cool { color: #1565c0; }
+.row { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-bottom: 24px; }
+.panel { background: #fff; border-radius: 12px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,.08); }
+.panel h2 { font-size: 18px; margin-bottom: 16px; color: #1a237e; border-bottom: 2px solid #3949ab; padding-bottom: 8px; }
+.chart { width: 100%; height: 350px; }
+table { width: 100%; border-collapse: collapse; }
+th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid #eee; font-size: 14px; }
+th { background: #f5f7fa; color: #555; font-weight: 600; }
+.tag { display: inline-block; padding: 2px 10px; border-radius: 12px; font-size: 12px; margin: 2px; }
+.tag.lang { background: #e3f2fd; color: #1565c0; }
+.tag.research { background: #e8f5e9; color: #2e7d32; }
+.tag.warn { background: #fff3e0; color: #e65100; }
+.footer { text-align: center; padding: 24px; color: #999; font-size: 12px; }
+@media (max-width: 768px) { .row { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>zzx-coder/gitlink-cli</h1>
+  <div class="subtitle">科研项目洞察报告 &mdash; 2026-07-06</div>
+</div>
+<div class="container">
+
+<div class="cards">
+  <div class="card">
+    <div class="label">热度评分</div>
+    <div class="value hot">54.3</div>
+    <div class="label">Hot</div>
+  </div>
+  <div class="card">
+    <div class="label">Stars</div>
+    <div class="value">0</div>
+  </div>
+  <div class="card">
+    <div class="label">Forks</div>
+    <div class="value">0</div>
+  </div>
+  <div class="card">
+    <div class="label">贡献者</div>
+    <div class="value">3</div>
+  </div>
+  <div class="card">
+    <div class="label">开放 Issues</div>
+    <div class="value">44</div>
+  </div>
+  <div class="card">
+    <div class="label">PR 合并率</div>
+    <div class="value">50.0%</div>
+  </div>
+</div>
+
+<div class="row">
+  <div class="panel">
+    <h2>项目概况</h2>
+    <table>
+      <tr><th>项目名称</th><td>gitlink-cli</td></tr>
+      <tr><th>描述</th><td>No description</td></tr>
+      <tr><th>主要语言</th><td><span class="tag lang">Unknown</span></td></tr>
+      <tr><th>技术栈</th><td><span class="tag lang">Unknown</span></td></tr>
+      <tr><th>创建时间</th><td></td></tr>
+      <tr><th>最后更新</th><td> (365 天前)</td></tr>
+      <tr><th>科研特征</th><td></td></tr>
+      
+      
+    </table>
+  </div>
+
+  <div class="panel">
+    <h2>活动概览</h2>
+    <div id="activityChart" class="chart"></div>
+  </div>
+</div>
+
+<div class="row">
+  <div class="panel">
+    <h2>健康指标</h2>
+    <table>
+      <tr><th>指标</th><th>数值</th><th>状态</th></tr>
+      <tr><td>Issue 总量</td><td>44 开放 / 44 已关闭</td><td><span class="tag warn">需关注</span></td></tr>
+      <tr><td>PR 合并率</td><td>50.0%</td><td><span class="tag warn">需改进</span></td></tr>
+      <tr><td>Release 数</td><td>6</td><td><span class="tag research">已发布</span></td></tr>
+      <tr><td>CI 通过率</td><td>0% (0 次构建)</td><td><span class="tag warn">不稳定</span></td></tr>
+      <tr><td>贡献者数</td><td>3 人</td><td><span class="tag warn">单人项目</span></td></tr>
+      <tr><td>活跃度</td><td>365 天前更新</td><td><span class="tag warn">不活跃</span></td></tr>
+    </table>
+  </div>
+
+  <div class="panel">
+    <h2>热度构成</h2>
+    <div id="hotnessChart" class="chart"></div>
+  </div>
+</div>
+
+</div>
+<div class="footer">Generated by GitLink Research Assistant &mdash; 2026-07-06</div>
+
+<script>
+var hotnessChart = echarts.init(document.getElementById('hotnessChart'));
+hotnessChart.setOption({
+  tooltip: { trigger: 'item' },
+  legend: { bottom: 0 },
+  series: [{
+    type: 'pie',
+    radius: ['45%', '75%'],
+    label: { formatter: '{b}\n{d}%' },
+    data: [
+      { name: 'Stars', value: 0.0, itemStyle: { color: '#5470c6' } },
+      { name: 'Forks', value: 0.0, itemStyle: { color: '#91cc75' } },
+      { name: 'Issues', value: 88.0, itemStyle: { color: '#fac858' } },
+      { name: 'PRs', value: 133.3, itemStyle: { color: '#ee6666' } },
+      { name: 'Releases', value: 60.0, itemStyle: { color: '#73c0de' } },
+      { name: 'Recency', value: 10, itemStyle: { color: '#fc8452' } }
+    ]
+  }]
+});
+
+var activityChart = echarts.init(document.getElementById('activityChart'));
+activityChart.setOption({
+  tooltip: { trigger: 'axis' },
+  xAxis: { type: 'category', data: ['Issues', 'PRs', 'Releases', 'CI Builds'] },
+  yAxis: { type: 'value' },
+  series: [
+    { name: '开放/进行中', type: 'bar', data: [44, 20, 0, 0], itemStyle: { color: '#fac858' } },
+    { name: '已完成', type: 'bar', data: [44, 20, 6, 0], itemStyle: { color: '#91cc75' } }
+  ]
+});
+</script>
+</body>
+</html>
--- a/pr-test-file.txt
+++ b/pr-test-file.txt
@ -1 +0,0 @@
-PR Test 2026年 4月 7日 星期二 11时45分56秒 CST
--- a/shortcuts/.claude/settings.local.json
+++ b/shortcuts/.claude/settings.local.json
@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:apifox.com)",
+      "WebSearch",
+      "WebFetch(domain:gitlink.org.cn)",
+      "WebFetch(domain:www.gitlink.org.cn)",
+      "Bash(sed 's/^//')",
+      "Bash(sed 's/ *$//')",
+      "Bash(grep -h \"CallAPI\\\\|\\\\.Do\\(\" C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/shortcuts/*/*.go C:/Users/Lenovo/Desktop/soft运维/gitlink-cli/shortcuts/*/*/*.go)",
+      "Bash(go build:*)",
+      "Bash(./gitlink-cli.exe file:*)",
+      "Bash(./gitlink-cli.exe issue:*)",
+      "Bash(./gitlink-cli.exe milestone:*)",
+      "Bash(./gitlink-cli.exe pr:*)",
+      "Bash(go vet:*)",
+      "Bash(go test:*)",
+      "Bash(cd:*)"
+    ]
+  }
+}
--- a/shortcuts/board/board.go
+++ b/shortcuts/board/board.go
@ -0,0 +1,832 @@
+package board
+
+import (
+	"fmt"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+
+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// === 状态/优先级常量 ===
+
+const (
+	statusNew        = 1
+	statusInProgress = 2
+	statusResolved   = 3
+	statusClosed     = 5
+	statusRejected   = 6
+)
+
+const (
+	priorityLow    = 1
+	priorityNormal = 2
+	priorityHigh   = 3
+	priorityUrgent = 4
+)
+
+// 标准看板列顺序（按 status_id 排列）
+var columnOrder = []struct {
+	ID   int
+	Name string
+}{
+	{statusNew, "待处理"},
+	{statusInProgress, "进行中"},
+	{statusResolved, "已解决"},
+	{statusClosed, "已关闭"},
+	{statusRejected, "已拒绝"},
+}
+
+// === 内部数据结构 ===
+
+// issueItem 从 issue list API 解析的单条 issue
+type issueItem struct {
+	ID             int    `json:"id"`
+	Subject        string `json:"subject"`
+	StatusID       int    `json:"status_id"`
+	StatusName     string `json:"status_name"`
+	PriorityID     int    `json:"priority_id"`
+	PriorityName   string `json:"priority_name"`
+	ProjectIndex   int    `json:"project_issues_index"`
+	Assigners      []struct {
+		Login string `json:"login"`
+		Name  string `json:"name"`
+	} `json:"assigners"`
+}
+
+// === 输出结构 ===
+
+type boardView struct {
+	Repository  string       `json:"repository"`
+	TotalIssues int          `json:"total_issues"`
+	Columns     []columnView `json:"columns"`
+}
+
+type columnView struct {
+	StatusID   int          `json:"status_id"`
+	StatusName string       `json:"status_name"`
+	IssueCount int          `json:"issue_count"`
+	Issues     []issueBrief `json:"issues"`
+}
+
+type issueBrief struct {
+	Number     int    `json:"number"`
+	ID         int    `json:"id"`
+	Subject    string `json:"subject"`
+	Priority   string `json:"priority"`
+	AssignedTo string `json:"assigned_to,omitempty"`
+}
+
+type boardStats struct {
+	Repository      string        `json:"repository"`
+	TotalIssues     int           `json:"total_issues"`
+	CompletionRate  float64       `json:"completion_rate"`
+	ColumnBreakdown []columnStat  `json:"column_breakdown"`
+	AssigneeLoad    []assigneeStat `json:"assignee_load"`
+	Bottleneck      string        `json:"bottleneck"`
+}
+
+type columnStat struct {
+	StatusName string  `json:"status_name"`
+	Count      int     `json:"count"`
+	Percentage float64 `json:"percentage"`
+}
+
+type assigneeStat struct {
+	Assignee string `json:"assignee"`
+	Count    int    `json:"count"`
+}
+
+// === 辅助函数 ===
+
+// v1RepoPath 返回 v1 API 路径前缀
+func v1RepoPath(ctx *common.RuntimeContext) string {
+	return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+}
+
+// fetchAllIssues 获取所有 issue（分页获取全部）
+func fetchAllIssues(ctx *common.RuntimeContext) ([]issueItem, error) {
+	var allIssues []issueItem
+	page := 1
+	for {
+		q := url.Values{}
+		q.Set("state", "all")
+		q.Set("page", strconv.Itoa(page))
+		q.Set("limit", "100")
+		env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
+		if err != nil {
+			return nil, clierrors.OpError(clierrors.KindServer, "list", "issues", err).
+				WithCommand(ctx.CommandName)
+		}
+		data, ok := env.Data.(map[string]interface{})
+		if !ok {
+			break
+		}
+		issuesRaw, ok := data["issues"].([]interface{})
+		if !ok || len(issuesRaw) == 0 {
+			break
+		}
+		for _, raw := range issuesRaw {
+			m, ok := raw.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			item := issueItem{
+				ID:         getInt(m, "id"),
+				Subject:    getString(m, "subject"),
+				StatusID:   getInt(m, "status_id"),
+				StatusName: getString(m, "status_name"),
+				PriorityID: getInt(m, "priority_id"),
+				PriorityName: getString(m, "priority_name"),
+				ProjectIndex: getInt(m, "project_issues_index"),
+			}
+			// 解析 assigners
+			if assigners, ok := m["assigners"].([]interface{}); ok {
+				for _, a := range assigners {
+					if am, ok := a.(map[string]interface{}); ok {
+						login := getString(am, "login")
+						if login == "" {
+							login = getString(am, "name")
+						}
+						item.Assigners = append(item.Assigners, struct {
+							Login string `json:"login"`
+							Name  string `json:"name"`
+						}{Login: login, Name: getString(am, "name")})
+					}
+				}
+			}
+			allIssues = append(allIssues, item)
+		}
+		// 检查是否还有下一页
+		totalCount := getInt(data, "total_count")
+		if totalCount == 0 {
+			totalCount = getInt(data, "total_issues_count")
+		}
+		if len(allIssues) >= totalCount || len(issuesRaw) < 100 {
+			break
+		}
+		page++
+	}
+	return allIssues, nil
+}
+
+// getString 从 map 中安全获取字符串
+func getString(m map[string]interface{}, key string) string {
+	v, _ := m[key].(string)
+	return v
+}
+
+// getInt 从 map 中安全获取整数
+func getInt(m map[string]interface{}, key string) int {
+	switch v := m[key].(type) {
+	case float64:
+		return int(v)
+	case int:
+		return v
+	default:
+		return 0
+	}
+}
+
+// extractAssignee 提取第一个指派人
+func extractAssignee(assigners []struct {
+	Login string `json:"login"`
+	Name  string `json:"name"`
+}) string {
+	if len(assigners) == 0 {
+		return ""
+	}
+	if assigners[0].Login != "" {
+		return assigners[0].Login
+	}
+	return assigners[0].Name
+}
+
+// parseStatusID 状态名转 ID
+func parseStatusID(s string) (int, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "new", "待处理":
+		return statusNew, nil
+	case "in-progress", "in_progress", "inprogress", "进行中":
+		return statusInProgress, nil
+	case "resolved", "已解决":
+		return statusResolved, nil
+	case "closed", "已关闭":
+		return statusClosed, nil
+	case "rejected", "已拒绝":
+		return statusRejected, nil
+	default:
+		if id, err := strconv.Atoi(s); err == nil {
+			return id, nil
+		}
+		return 0, fmt.Errorf("invalid status %q: use new, in-progress, resolved, closed, or rejected", s)
+	}
+}
+
+// statusIDToName 状态 ID 转名称
+func statusIDToName(id int) string {
+	for _, c := range columnOrder {
+		if c.ID == id {
+			return c.Name
+		}
+	}
+	return fmt.Sprintf("status_%d", id)
+}
+
+// parsePriorityID 优先级名转 ID
+func parsePriorityID(p string) (int, error) {
+	switch strings.ToLower(strings.TrimSpace(p)) {
+	case "low":
+		return priorityLow, nil
+	case "normal":
+		return priorityNormal, nil
+	case "high":
+		return priorityHigh, nil
+	case "urgent":
+		return priorityUrgent, nil
+	default:
+		if id, err := strconv.Atoi(p); err == nil {
+			return id, nil
+		}
+		return 0, fmt.Errorf("invalid priority %q: use low, normal, high, or urgent", p)
+	}
+}
+
+// priorityName 优先级 ID 转名称
+func priorityName(id int) string {
+	switch id {
+	case priorityLow:
+		return "low"
+	case priorityNormal:
+		return "normal"
+	case priorityHigh:
+		return "high"
+	case priorityUrgent:
+		return "urgent"
+	default:
+		return fmt.Sprintf("%d", id)
+	}
+}
+
+// fetchExistingIssue 获取现有 issue 的 subject 和 description
+func fetchExistingIssue(ctx *common.RuntimeContext, number string) (subject, description string, err error) {
+	env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), nil)
+	if err != nil {
+		return "", "", clierrors.OpError(clierrors.KindNotFound, "view", "issue", err).WithCommand(ctx.CommandName)
+	}
+	data, ok := env.Data.(map[string]interface{})
+	if !ok {
+		return "", "", fmt.Errorf("failed to parse issue data")
+	}
+	subject, _ = data["subject"].(string)
+	if subject == "" {
+		return "", "", fmt.Errorf("issue #%s: missing subject field", number)
+	}
+	description, _ = data["description"].(string)
+	return subject, description, nil
+}
+
+// resolveUserID 把用户名转换成用户 ID
+func resolveUserID(ctx *common.RuntimeContext, login string) (interface{}, error) {
+	if id, err := strconv.Atoi(login); err == nil {
+		return id, nil
+	}
+	env, err := ctx.CallAPI("GET", fmt.Sprintf("/users/%s", login), nil)
+	if err != nil {
+		return nil, fmt.Errorf("lookup user %q: %w", login, err)
+	}
+	data, ok := env.Data.(map[string]interface{})
+	if !ok {
+		return nil, fmt.Errorf("unexpected response for user %q", login)
+	}
+	if idFloat, ok := data["id"].(float64); ok {
+		return int(idFloat), nil
+	}
+	if userIDFloat, ok := data["user_id"].(float64); ok {
+		return int(userIDFloat), nil
+	}
+	return nil, fmt.Errorf("cannot determine user ID for %q", login)
+}
+
+// groupByStatus 将 issues 按 status_id 分组
+func groupByStatus(issues []issueItem) map[int][]issueItem {
+	grouped := make(map[int][]issueItem)
+	for _, iss := range issues {
+		grouped[iss.StatusID] = append(grouped[iss.StatusID], iss)
+	}
+	return grouped
+}
+
+// === Shortcuts 入口 ===
+
+func Shortcuts() []*common.Shortcut {
+	return []*common.Shortcut{
+		newViewShortcut(),
+		newColumnsShortcut(),
+		newIssuesShortcut(),
+		newMoveShortcut(),
+		newAssignShortcut(),
+		newStatsShortcut(),
+	}
+}
+
+// === board +view ===
+
+func newViewShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "view",
+		Description: "View kanban board layout",
+		Long:        "Display the kanban board with issues grouped by status columns.",
+		Example:     "  gitlink-cli board +view\n  gitlink-cli board +view --state open",
+		Flags: []common.Flag{
+			{Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "open"},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			state := ctx.Arg("state")
+			if state == "" {
+				state = "open"
+			}
+
+			// 获取 issues
+			var allIssues []issueItem
+			page := 1
+			for {
+				q := url.Values{}
+				q.Set("state", state)
+				q.Set("page", strconv.Itoa(page))
+				q.Set("limit", "100")
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "issues", err).
+						WithCommand(ctx.CommandName)
+				}
+				data, ok := env.Data.(map[string]interface{})
+				if !ok {
+					break
+				}
+				issuesRaw, ok := data["issues"].([]interface{})
+				if !ok || len(issuesRaw) == 0 {
+					break
+				}
+				for _, raw := range issuesRaw {
+					m, ok := raw.(map[string]interface{})
+					if !ok {
+						continue
+					}
+					item := issueItem{
+						ID:           getInt(m, "id"),
+						Subject:      getString(m, "subject"),
+						StatusID:     getInt(m, "status_id"),
+						StatusName:   getString(m, "status_name"),
+						PriorityID:   getInt(m, "priority_id"),
+						PriorityName: getString(m, "priority_name"),
+						ProjectIndex: getInt(m, "project_issues_index"),
+					}
+					if assigners, ok := m["assigners"].([]interface{}); ok {
+						for _, a := range assigners {
+							if am, ok := a.(map[string]interface{}); ok {
+								login := getString(am, "login")
+								if login == "" {
+									login = getString(am, "name")
+								}
+								item.Assigners = append(item.Assigners, struct {
+									Login string `json:"login"`
+									Name  string `json:"name"`
+								}{Login: login, Name: getString(am, "name")})
+							}
+						}
+					}
+					allIssues = append(allIssues, item)
+				}
+				totalCount := getInt(data, "total_count")
+				if totalCount == 0 {
+					totalCount = getInt(data, "total_issues_count")
+				}
+				if len(allIssues) >= totalCount || len(issuesRaw) < 100 {
+					break
+				}
+				page++
+			}
+
+			// 按 status 分组
+			grouped := groupByStatus(allIssues)
+
+			// 构建看板视图
+			view := boardView{
+				Repository:  fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+				TotalIssues: len(allIssues),
+			}
+			for _, col := range columnOrder {
+				issues := grouped[col.ID]
+				cv := columnView{
+					StatusID:   col.ID,
+					StatusName: col.Name,
+					IssueCount: len(issues),
+					Issues:     make([]issueBrief, 0, len(issues)),
+				}
+				for _, iss := range issues {
+					cv.Issues = append(cv.Issues, issueBrief{
+						Number:     iss.ProjectIndex,
+						ID:         iss.ID,
+						Subject:    iss.Subject,
+						Priority:   priorityName(iss.PriorityID),
+						AssignedTo: extractAssignee(iss.Assigners),
+					})
+				}
+				view.Columns = append(view.Columns, cv)
+			}
+			return ctx.OutputData(view)
+		},
+	}
+}
+
+// === board +columns ===
+
+func newColumnsShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "columns",
+		Description: "List status columns with issue counts",
+		Example:     "  gitlink-cli board +columns",
+		Flags: []common.Flag{
+			{Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "open"},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			state := ctx.Arg("state")
+			if state == "" {
+				state = "open"
+			}
+			issues, err := fetchAllIssuesWithState(ctx, state)
+			if err != nil {
+				return err
+			}
+			grouped := groupByStatus(issues)
+
+			type colInfo struct {
+				StatusID   int    `json:"status_id"`
+				StatusName string `json:"status_name"`
+				IssueCount int    `json:"issue_count"`
+			}
+			var columns []colInfo
+			for _, col := range columnOrder {
+				columns = append(columns, colInfo{
+					StatusID:   col.ID,
+					StatusName: col.Name,
+					IssueCount: len(grouped[col.ID]),
+				})
+			}
+			return ctx.OutputData(columns)
+		},
+	}
+}
+
+// fetchAllIssuesWithState 带状态过滤的全量 issue 获取
+func fetchAllIssuesWithState(ctx *common.RuntimeContext, state string) ([]issueItem, error) {
+	var allIssues []issueItem
+	page := 1
+	for {
+		q := url.Values{}
+		q.Set("state", state)
+		q.Set("page", strconv.Itoa(page))
+		q.Set("limit", "100")
+		env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
+		if err != nil {
+			return nil, clierrors.OpError(clierrors.KindServer, "list", "issues", err).
+				WithCommand(ctx.CommandName)
+		}
+		data, ok := env.Data.(map[string]interface{})
+		if !ok {
+			break
+		}
+		issuesRaw, ok := data["issues"].([]interface{})
+		if !ok || len(issuesRaw) == 0 {
+			break
+		}
+		for _, raw := range issuesRaw {
+			m, ok := raw.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			item := issueItem{
+				ID:           getInt(m, "id"),
+				Subject:      getString(m, "subject"),
+				StatusID:     getInt(m, "status_id"),
+				StatusName:   getString(m, "status_name"),
+				PriorityID:   getInt(m, "priority_id"),
+				PriorityName: getString(m, "priority_name"),
+				ProjectIndex: getInt(m, "project_issues_index"),
+			}
+			if assigners, ok := m["assigners"].([]interface{}); ok {
+				for _, a := range assigners {
+					if am, ok := a.(map[string]interface{}); ok {
+						login := getString(am, "login")
+						if login == "" {
+							login = getString(am, "name")
+						}
+						item.Assigners = append(item.Assigners, struct {
+							Login string `json:"login"`
+							Name  string `json:"name"`
+						}{Login: login, Name: getString(am, "name")})
+					}
+				}
+			}
+			allIssues = append(allIssues, item)
+		}
+		totalCount := getInt(data, "total_count")
+		if totalCount == 0 {
+			totalCount = getInt(data, "total_issues_count")
+		}
+		if len(allIssues) >= totalCount || len(issuesRaw) < 100 {
+			break
+		}
+		page++
+	}
+	return allIssues, nil
+}
+
+// === board +issues ===
+
+func newIssuesShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "issues",
+		Description: "List issues with optional filters",
+		Long:        "List issues with filtering by status, assignee, and priority.",
+		Example:     "  gitlink-cli board +issues\n  gitlink-cli board +issues --status in-progress --assignee zhangsan\n  gitlink-cli board +issues --priority high --limit 10",
+		Flags: []common.Flag{
+			{Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "open"},
+			{Name: "status", Usage: "Filter by status: new/in-progress/resolved/closed/rejected"},
+			{Name: "assignee", Short: "a", Usage: "Filter by assignee login"},
+			{Name: "priority", Short: "p", Usage: "Filter by priority: low/normal/high/urgent"},
+			{Name: "limit", Short: "l", Usage: "Max issues to show (0 = all)", Default: "0"},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			state := ctx.Arg("state")
+			if state == "" {
+				state = "open"
+			}
+			issues, err := fetchAllIssuesWithState(ctx, state)
+			if err != nil {
+				return err
+			}
+
+			// 解析过滤条件
+			filterStatus := ctx.Arg("status")
+			filterAssignee := ctx.Arg("assignee")
+			filterPriority := ctx.Arg("priority")
+			limit, _ := strconv.Atoi(ctx.Arg("limit"))
+
+			var statusIDFilter int
+			if filterStatus != "" {
+				statusIDFilter, err = parseStatusID(filterStatus)
+				if err != nil {
+					return err
+				}
+			}
+			var priorityIDFilter int
+			if filterPriority != "" {
+				priorityIDFilter, err = parsePriorityID(filterPriority)
+				if err != nil {
+					return err
+				}
+			}
+
+			var filtered []map[string]interface{}
+			for _, iss := range issues {
+				if statusIDFilter != 0 && iss.StatusID != statusIDFilter {
+					continue
+				}
+				if filterAssignee != "" {
+					assignee := extractAssignee(iss.Assigners)
+					if !strings.EqualFold(assignee, filterAssignee) {
+						continue
+					}
+				}
+				if priorityIDFilter != 0 && iss.PriorityID != priorityIDFilter {
+					continue
+				}
+				filtered = append(filtered, map[string]interface{}{
+					"number":      iss.ProjectIndex,
+					"id":          iss.ID,
+					"subject":     iss.Subject,
+					"status":      iss.StatusName,
+					"priority":    priorityName(iss.PriorityID),
+					"assigned_to": extractAssignee(iss.Assigners),
+				})
+			}
+			if limit > 0 && len(filtered) > limit {
+				filtered = filtered[:limit]
+			}
+			if filtered == nil {
+				filtered = []map[string]interface{}{}
+			}
+			return ctx.OutputData(filtered)
+		},
+	}
+}
+
+// === board +move ===
+
+func newMoveShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "move",
+		Description: "Move an issue to a different status",
+		Long:        "Change issue status. Accepts status names (new/in-progress/resolved/closed/rejected) or numeric IDs.",
+		Example:     "  gitlink-cli board +move --number 42 --status in-progress\n  gitlink-cli board +move --number 42 --status closed --dry-run",
+		DryRun:      true,
+		DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+			return fmt.Sprintf("Move issue #%s to status %q", ctx.Arg("number"), ctx.Arg("status")), nil
+		},
+		Flags: []common.Flag{
+			{Name: "number", Short: "n", Usage: "Issue number (project_issues_index)", Required: true},
+			{Name: "status", Short: "s", Usage: "Target status: new/in-progress/resolved/closed/rejected (or numeric ID)", Required: true},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			number, err := ctx.RequireArg("number", "--number 42")
+			if err != nil {
+				return err
+			}
+			statusStr, err := ctx.RequireArg("status", "--status in-progress")
+			if err != nil {
+				return err
+			}
+			statusID, err := parseStatusID(statusStr)
+			if err != nil {
+				return err
+			}
+
+			subject, description, err := fetchExistingIssue(ctx, number)
+			if err != nil {
+				return err
+			}
+			body := map[string]interface{}{
+				"subject":     subject,
+				"description": description,
+				"status_id":   statusID,
+			}
+			env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body)
+			if err != nil {
+				return clierrors.OpError(clierrors.KindServer, "move", "issue", err).WithCommand(ctx.CommandName)
+			}
+			return ctx.Output(env)
+		},
+	}
+}
+
+// === board +assign ===
+
+func newAssignShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "assign",
+		Description: "Assign an issue to someone",
+		Long:        "Assign an issue to a user by login name or user ID.",
+		Example:     "  gitlink-cli board +assign --number 42 --assignee zhangsan\n  gitlink-cli board +assign --number 42 --assignee 123 --dry-run",
+		DryRun:      true,
+		DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+			return fmt.Sprintf("Assign issue #%s to %s", ctx.Arg("number"), ctx.Arg("assignee")), nil
+		},
+		Flags: []common.Flag{
+			{Name: "number", Short: "n", Usage: "Issue number (project_issues_index)", Required: true},
+			{Name: "assignee", Short: "a", Usage: "Assignee login name or user ID", Required: true},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			number, err := ctx.RequireArg("number", "--number 42")
+			if err != nil {
+				return err
+			}
+			assignee, err := ctx.RequireArg("assignee", "--assignee zhangsan")
+			if err != nil {
+				return err
+			}
+			assigneeID, err := resolveUserID(ctx, assignee)
+			if err != nil {
+				return fmt.Errorf("cannot resolve assignee %q: %w", assignee, err)
+			}
+			subject, description, err := fetchExistingIssue(ctx, number)
+			if err != nil {
+				return err
+			}
+			body := map[string]interface{}{
+				"subject":       subject,
+				"description":   description,
+				"assigner_ids":  []interface{}{assigneeID},
+			}
+			env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body)
+			if err != nil {
+				return clierrors.OpError(clierrors.KindServer, "assign", "issue", err).WithCommand(ctx.CommandName)
+			}
+			return ctx.Output(env)
+		},
+	}
+}
+
+// === board +stats ===
+
+func newStatsShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "stats",
+		Description: "Show board analytics and statistics",
+		Long:        "Display completion rate, workload distribution, and bottleneck analysis.",
+		Example:     "  gitlink-cli board +stats\n  gitlink-cli board +stats --state all",
+		Flags: []common.Flag{
+			{Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "all"},
+		},
+		Run: func(ctx *common.RuntimeContext) error {
+			if err := ctx.ResolveOwnerRepo(); err != nil {
+				return err
+			}
+			state := ctx.Arg("state")
+			if state == "" {
+				state = "all"
+			}
+			issues, err := fetchAllIssuesWithState(ctx, state)
+			if err != nil {
+				return err
+			}
+
+			grouped := groupByStatus(issues)
+			total := len(issues)
+
+			// 统计每人 issue 数量
+			assigneeCounts := make(map[string]int)
+			for _, iss := range issues {
+				a := extractAssignee(iss.Assigners)
+				if a == "" {
+					a = "(unassigned)"
+				}
+				assigneeCounts[a]++
+			}
+
+			// 完成率 = resolved + closed / total
+			completed := len(grouped[statusResolved]) + len(grouped[statusClosed])
+			completionRate := 0.0
+			if total > 0 {
+				completionRate = float64(completed) / float64(total) * 100
+			}
+
+			// 列统计
+			var colBreakdown []columnStat
+			for _, col := range columnOrder {
+				count := len(grouped[col.ID])
+				pct := 0.0
+				if total > 0 {
+					pct = float64(count) / float64(total) * 100
+				}
+				colBreakdown = append(colBreakdown, columnStat{
+					StatusName: col.Name,
+					Count:      count,
+					Percentage: pct,
+				})
+			}
+
+			// 人员负载（降序）
+			var assigneeLoad []assigneeStat
+			for name, count := range assigneeCounts {
+				assigneeLoad = append(assigneeLoad, assigneeStat{Assignee: name, Count: count})
+			}
+			sort.Slice(assigneeLoad, func(i, j int) bool {
+				return assigneeLoad[i].Count > assigneeLoad[j].Count
+			})
+
+			// 瓶颈：非完成态中任务最多的列
+			bottleneck := ""
+			maxCount := 0
+			for _, col := range columnOrder[:3] { // 只看 new/in-progress/resolved
+				count := len(grouped[col.ID])
+				if count > maxCount {
+					maxCount = count
+					bottleneck = col.Name
+				}
+			}
+
+			stats := boardStats{
+				Repository:      fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+				TotalIssues:     total,
+				CompletionRate:  completionRate,
+				ColumnBreakdown: colBreakdown,
+				AssigneeLoad:    assigneeLoad,
+				Bottleneck:      bottleneck,
+			}
+			if stats.AssigneeLoad == nil {
+				stats.AssigneeLoad = []assigneeStat{}
+			}
+			return ctx.OutputData(stats)
+		},
+	}
+}
--- a/shortcuts/common/error_print.go
+++ b/shortcuts/common/error_print.go
@ -0,0 +1,68 @@
+package common
+
+import (
+	"errors"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
+	"github.com/gitlink-org/gitlink-cli/internal/output"
+)
+
+// TryPrintError 尝试把 error 转换为 envelope 格式并输出到 stdout。
+// 返回 true 表示已识别并处理；false 表示该 error 类型不被识别，应由调用方走原有路径。
+//
+// 设计意图：让 shortcut 的错误处理路径与 api 命令对齐，
+// 使 `--format json` 输出可被 jq 解析的标准 envelope：
+//
+//	{"ok":false, "error":{"code":N, "message":"...", "suggestion":"..."}}
+//
+// 支持的 error 类型：
+//   - *client.APIError  : HTTP 错误（404/403/401 等），code = HTTP 状态码
+//   - *clierrors.CLIError : 业务级错误（输入/认证/网络等），code 由 kind 映射
+//
+// 注：放在 common 包（而非 output 包）以避免与 client 包形成导入循环。
+func TryPrintError(err error, format string) bool {
+	if err == nil {
+		return false
+	}
+
+	var apiErr *client.APIError
+	if errors.As(err, &apiErr) {
+		env := output.ErrorEnvelope(apiErr.Code, apiErr.Message, apiErr.Suggestion)
+		_ = output.Print(env, format)
+		return true
+	}
+
+	var cliErr *clierrors.CLIError
+	if errors.As(err, &cliErr) {
+		env := output.ErrorEnvelope(kindToCode(cliErr.Kind), cliErr.Message, cliErr.Suggestion)
+		_ = output.Print(env, format)
+		return true
+	}
+
+	return false
+}
+
+// kindToCode 把 CLIError.Kind 映射到近似的 HTTP 状态码，用于 envelope.error.code 字段
+func kindToCode(kind clierrors.ErrorKind) int {
+	switch kind {
+	case clierrors.KindAuth:
+		return 401
+	case clierrors.KindInput:
+		return 400
+	case clierrors.KindNotFound:
+		return 404
+	case clierrors.KindForbidden:
+		return 403
+	case clierrors.KindNetwork:
+		return 503
+	case clierrors.KindServer:
+		return 500
+	case clierrors.KindConfig:
+		return 500
+	case clierrors.KindGit:
+		return 500
+	default:
+		return 500
+	}
+}
--- a/shortcuts/common/runner.go
+++ b/shortcuts/common/runner.go
@ -4,16 +4,49 @@ import (
 	"fmt"
 	"os"
 	"strconv"
+	"strings"

 	"github.com/spf13/cobra"
+
+	"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 )

 // MountShortcut converts a Shortcut into a cobra.Command and adds it as a subcommand.
 func MountShortcut(parent *cobra.Command, s *Shortcut) {
 	cmd := &cobra.Command{
-		Use:   "+" + s.Name,
-		Short: s.Description,
+		Use:     "+" + s.Name,
+		Short:   s.Description,
+		Long:    s.Long,
+		Example: s.Example,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			commandName := parent.Use + " +" + s.Name
+
+			// --- flag-level validation ---
+			for _, f := range s.Flags {
+				val := getFlagValue(cmd, f)
+
+				// choices enum validation
+				if len(f.Choices) > 0 && val != "" && val != "false" {
+					if !contains(f.Choices, val) {
+						return clierrors.InputError(
+							fmt.Sprintf("invalid value %q for --%s", val, f.Name),
+							fmt.Sprintf("有效值: %s。运行 'gitlink-cli %s --help' 查看用法。", strings.Join(f.Choices, ", "), commandName),
+						).WithCommand(commandName)
+					}
+				}
+
+				// custom validate function
+				if f.Validate != nil && val != "" {
+					if err := f.Validate(val); err != nil {
+						return clierrors.InputError(
+							fmt.Sprintf("invalid --%s: %v", f.Name, err),
+							fmt.Sprintf("运行 'gitlink-cli %s --help' 查看用法。", commandName),
+						).WithCommand(commandName)
+					}
+				}
+			}
+
 			// Collect flag values
 			flagValues := make(map[string]string)
 			for _, f := range s.Flags {
@ -28,7 +61,16 @@ func MountShortcut(parent *cobra.Command, s *Shortcut) {
 				}
 			}

-			commandName := parent.Use + " +" + s.Name
+			// cross-flag validation
+			if s.Validate != nil {
+				if err := s.Validate(flagValues); err != nil {
+					return clierrors.InputError(
+						err.Error(),
+						fmt.Sprintf("运行 'gitlink-cli %s --help' 查看用法。", commandName),
+					).WithCommand(commandName)
+				}
+			}
+
 			ctx, err := NewRuntimeContext(flagValues, commandName)
 			if err != nil {
 				return err
@ -55,7 +97,16 @@ func MountShortcut(parent *cobra.Command, s *Shortcut) {
 				}
 			}

-			return s.Run(ctx)
+			err = s.Run(ctx)
+			if err != nil {
+				// 当错误为已识别的 API/CLI 错误时，按 envelope 格式输出到 stdout，
+				// 让 `--format json` 输出可被 jq 解析的标准结构。
+				// 已识别后返回 ErrSilent：保留非零退出码，但 cmd.Execute 不会再 stderr 重复输出。
+				if TryPrintError(err, ctx.Format) {
+					return cmdutil.ErrSilent
+				}
+			}
+			return err
 		},
 	}

@ -64,6 +115,9 @@ func MountShortcut(parent *cobra.Command, s *Shortcut) {
 		if f.Required {
 			usage = usage + " [required]"
 		}
+		if len(f.Choices) > 0 {
+			usage = usage + " [" + strings.Join(f.Choices, "|") + "]"
+		}
 		if f.Bool {
 			defaultValue, _ := strconv.ParseBool(f.Default)
 			if f.Short != "" {
@ -86,6 +140,25 @@ func MountShortcut(parent *cobra.Command, s *Shortcut) {
 	parent.AddCommand(cmd)
 }

+// getFlagValue returns the string value of a flag from a cobra command.
+func getFlagValue(cmd *cobra.Command, f Flag) string {
+	if f.Bool {
+		val, _ := cmd.Flags().GetBool(f.Name)
+		return strconv.FormatBool(val)
+	}
+	val, _ := cmd.Flags().GetString(f.Name)
+	return val
+}
+
+func contains(slice []string, item string) bool {
+	for _, s := range slice {
+		if s == item {
+			return true
+		}
+	}
+	return false
+}
+
 // MountShortcuts mounts multiple shortcuts under a parent command.
 func MountShortcuts(parent *cobra.Command, shortcuts []*Shortcut) {
 	for _, s := range shortcuts {
--- a/shortcuts/common/types.go
+++ b/shortcuts/common/types.go
@ -21,9 +21,12 @@ import (
 type Shortcut struct {
 	Name        string
 	Description string
+	Long        string                                     // detailed help text (shown in --help)
+	Example     string                                     // usage examples (shown in --help)
 	Flags       []Flag
 	DryRun      bool                                      // 是否支持 dry-run
 	DryRunHint  func(ctx *RuntimeContext) (string, error) // 返回预览描述
+	Validate    func(args map[string]string) error         // cross-flag validation
 	Run         func(ctx *RuntimeContext) error
 }

@ -35,6 +38,8 @@ type Flag struct {
 	Required bool
 	Default  string
 	Bool     bool
+	Choices  []string                  // allowed values (enum validation)
+	Validate func(value string) error  // custom per-flag validation
 }

 // RuntimeContext provides helpers for shortcut implementations.
@ -47,6 +52,9 @@ type RuntimeContext struct {
 	Args              map[string]string
 	GatewayBaseURL    string
 	GatewayHTTPClient *http.Client // optional; nil = use auth.NewHTTPClient (mainly for tests)
+	NoTruncate        bool         // --no-truncate: disable table column truncation
+	Columns           string       // --columns: comma-separated column filter
+	NoColor           bool         // --no-color: disable ANSI color output
 }

 // NewRuntimeContext creates a RuntimeContext with auto-resolved owner/repo.
@ -59,7 +67,7 @@ func NewRuntimeContext(args map[string]string, commandName string) (*RuntimeCont

 	format := cmdutil.Format
 	if format == "" {
-		format = "json"
+		format = "table"
 	}

 	gatewayBaseURL := config.DefaultGatewayBaseURL
@ -76,6 +84,9 @@ func NewRuntimeContext(args map[string]string, commandName string) (*RuntimeCont
 		Args:              args,
 		GatewayBaseURL:    gatewayBaseURL,
 		GatewayHTTPClient: nil,
+		NoTruncate:        cmdutil.NoTruncate,
+		Columns:           cmdutil.Columns,
+		NoColor:           cmdutil.NoColor,
 	}, nil
 }

@ -107,12 +118,31 @@ func (ctx *RuntimeContext) PaginateAll(path string, params url.Values) ([]json.R

 // Output prints the envelope in the configured format.
 func (ctx *RuntimeContext) Output(env *output.Envelope) error {
-	return output.Print(env, ctx.Format)
+	return output.PrintWithOpts(env, ctx.Format, ctx.printOpts())
 }

 // OutputData wraps data in a success envelope and prints it.
 func (ctx *RuntimeContext) OutputData(data interface{}) error {
-	return output.Print(output.SuccessEnvelope(data, nil), ctx.Format)
+	return output.PrintWithOpts(output.SuccessEnvelope(data, nil), ctx.Format, ctx.printOpts())
+}
+
+// printOpts builds PrintOptions from the runtime context.
+func (ctx *RuntimeContext) printOpts() output.PrintOptions {
+	opts := output.PrintOptions{
+		NoTruncate: ctx.NoTruncate,
+		UseColor:   !ctx.NoColor,
+	}
+	if ctx.Columns != "" {
+		parts := strings.Split(ctx.Columns, ",")
+		opts.Columns = make([]string, 0, len(parts))
+		for _, p := range parts {
+			p = strings.TrimSpace(p)
+			if p != "" {
+				opts.Columns = append(opts.Columns, p)
+			}
+		}
+	}
+	return opts
 }

 // RepoPath returns the API path prefix for the current owner/repo.
--- a/shortcuts/compliance/compliance.go
+++ b/shortcuts/compliance/compliance.go
@ -1,122 +0,0 @@
-package compliance
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-)
-
-func Shortcuts() []*common.Shortcut {
-	return []*common.Shortcut{
-		{
-			Name:        "scan",
-			Description: "Full compliance scan (all five modules)",
-			Flags: []common.Flag{
-				{Name: "module", Short: "m", Usage: "Comma-separated modules: license,deps,secrets,exposure,vocab"},
-			},
-			Run: runScan,
-		},
-		{Name: "license", Description: "License compliance check", Run: runLicense},
-		{Name: "deps", Description: "Dependency license check", Run: runDeps},
-		{Name: "secrets", Description: "Hardcoded secrets scan", Run: runSecrets},
-		{Name: "exposure", Description: "PII and network exposure scan", Run: runExposure},
-		{Name: "vocab", Description: "Sensitive vocabulary scan", Run: runVocab},
-	}
-}
-
-func repoRoot() (string, error) {
-	dir, err := os.Getwd()
-	if err != nil {
-		return "", fmt.Errorf("get working directory: %w", err)
-	}
-	// find git root
-	for {
-		if _, err := os.Stat(filepath.Join(dir, ".git")); err == nil {
-			return dir, nil
-		}
-		parent := filepath.Dir(dir)
-		if parent == dir {
-			return dir, nil // fallback to cwd
-		}
-		dir = parent
-	}
-}
-
-// runScan is the full scan (all modules).
-func runScan(ctx *common.RuntimeContext) error {
-	root, err := repoRoot()
-	if err != nil {
-		return err
-	}
-
-	selected := ctx.Arg("module")
-	var modules []string
-	if selected != "" {
-		modules = parseModules(selected)
-	} else {
-		modules = []string{"secrets", "exposure", "vocab"}
-	}
-
-	// license and deps checks
-	var allFindings []Finding
-	for _, m := range modules {
-		switch m {
-		case "license":
-			allFindings = append(allFindings, checkLicense(root)...)
-		case "deps":
-			allFindings = append(allFindings, checkDeps(root)...)
-		case "secrets", "exposure", "vocab":
-			rules := allRules()[m]
-			allFindings = append(allFindings, scanFiles(root, rules)...)
-		}
-	}
-
-	return outputReport(ctx, allFindings, modules)
-}
-
-func runLicense(ctx *common.RuntimeContext) error {
-	root, _ := repoRoot()
-	findings := checkLicense(root)
-	return outputReport(ctx, findings, []string{"license"})
-}
-
-func runDeps(ctx *common.RuntimeContext) error {
-	root, _ := repoRoot()
-	findings := checkDeps(root)
-	return outputReport(ctx, findings, []string{"deps"})
-}
-
-func runSecrets(ctx *common.RuntimeContext) error {
-	root, _ := repoRoot()
-	findings := scanFiles(root, allRules()["secrets"])
-	return outputReport(ctx, findings, []string{"secrets"})
-}
-
-func runExposure(ctx *common.RuntimeContext) error {
-	root, _ := repoRoot()
-	findings := scanFiles(root, allRules()["exposure"])
-	return outputReport(ctx, findings, []string{"exposure"})
-}
-
-func runVocab(ctx *common.RuntimeContext) error {
-	root, _ := repoRoot()
-	findings := scanFiles(root, allRules()["vocab"])
-	return outputReport(ctx, findings, []string{"vocab"})
-}
-
-func parseModules(s string) []string {
-	var result []string
-	seen := map[string]bool{}
-	for _, m := range strings.Split(s, ",") {
-		m = strings.TrimSpace(m)
-		valid := map[string]bool{"license": true, "deps": true, "secrets": true, "exposure": true, "vocab": true}
-		if valid[m] && !seen[m] {
-			result = append(result, m)
-			seen[m] = true
-		}
-	}
-	return result
-}
--- a/shortcuts/compliance/report.go
+++ b/shortcuts/compliance/report.go
@ -1,77 +0,0 @@
-package compliance
-
-import (
-	"fmt"
-	"strings"
-
-	"github.com/gitlink-org/gitlink-cli/internal/output"
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-)
-
-// summary holds aggregated stats.
-type summary struct {
-	Total    int `json:"total"`
-	Critical int `json:"critical"`
-	High     int `json:"high"`
-	Medium   int `json:"medium"`
-	Low      int `json:"low"`
-}
-
-type reportData struct {
-	Modules   []string  `json:"modules"`
-	Findings  []Finding `json:"findings"`
-	Summary   summary   `json:"summary"`
-}
-
-func outputReport(ctx *common.RuntimeContext, findings []Finding, modules []string) error {
-	s := summary{}
-	for _, f := range findings {
-		s.Total++
-		switch f.Severity {
-		case "critical": s.Critical++
-		case "high": s.High++
-		case "medium": s.Medium++
-		case "low": s.Low++
-		}
-	}
-
-	if ctx.Format == "json" {
-		return ctx.OutputData(reportData{Modules: modules, Findings: findings, Summary: s})
-	}
-
-	// human-readable output
-	fmt.Println()
-	printHR()
-	fmt.Printf("  Compliance Scan Report\n")
-	fmt.Printf("  Modules: %s |  Findings: %d  (critical:%d high:%d medium:%d low:%d)\n",
-		strings.Join(modules, ", "), s.Total, s.Critical, s.High, s.Medium, s.Low)
-	printHR()
-
-	if len(findings) == 0 {
-		fmt.Println("  All clear — no issues found.")
-	} else {
-		printFindings(findings)
-	}
-	printHR()
-	return nil
-}
-
-func printHR() {
-	fmt.Println(strings.Repeat("─", 60))
-}
-
-func printFindings(findings []Finding) {
-	labels := map[string]string{
-		"critical": "CRIT", "high": "HIGH", "medium": "MED", "low": "LOW",
-	}
-	for _, f := range findings {
-		label := labels[f.Severity]
-		if label == "" {
-			label = f.Severity
-		}
-		fmt.Printf("  [%s] %s  %s:%d  %s\n", label, f.ID, f.File, f.Line, f.Summary)
-	}
-}
-
-// Ensure output import is used
-var _ = output.SuccessEnvelope
--- a/shortcuts/contrib/contrib.go
+++ b/shortcuts/contrib/contrib.go
@ -1,69 +0,0 @@
-package contrib
-
-import (
-	"fmt"
-	"os/exec"
-	"runtime"
-
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-)
-
-func Shortcuts() []*common.Shortcut {
-	return []*common.Shortcut{
-		{
-			Name:        "report",
-			Description: "Generate a contribution report with pie chart",
-			Flags: []common.Flag{
-				{Name: "output", Short: "o", Usage: "Output HTML file path", Default: "contrib-report.html"},
-				{Name: "open", Usage: "Open browser after generating", Bool: true, Default: "true"},
-			},
-			Run: runReport,
-		},
-	}
-}
-
-func runReport(ctx *common.RuntimeContext) error {
-	if err := ctx.ResolveOwnerRepo(); err != nil {
-		return err
-	}
-
-	// 1. 获取贡献者列表（从 issue 和 PR 数据中提取）
-	contributors, err := fetchContributors(ctx)
-	if err != nil {
-		return fmt.Errorf("fetch contributors: %w", err)
-	}
-
-	// 2. 计算加权贡献分数
-	reportData := calculateScores(contributors, nil, nil)
-
-	// 3. 生成 HTML 报告
-	outputPath := ctx.Arg("output")
-	if err := generateHTML(ctx.Owner, ctx.Repo, reportData, outputPath); err != nil {
-		return fmt.Errorf("generate HTML: %w", err)
-	}
-
-	fmt.Printf("Report generated: %s\n", outputPath)
-
-	// 4. 打开浏览器
-	if ctx.Arg("open") != "false" {
-		if err := openBrowser(outputPath); err != nil {
-			fmt.Printf("Warning: failed to open browser: %v\n", err)
-		}
-	}
-
-	return nil
-}
-
-// openBrowser 打开浏览器
-func openBrowser(url string) error {
-	var cmd *exec.Cmd
-	switch runtime.GOOS {
-	case "windows":
-		cmd = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
-	case "darwin":
-		cmd = exec.Command("open", url)
-	default: // linux
-		cmd = exec.Command("xdg-open", url)
-	}
-	return cmd.Start()
-}
--- a/shortcuts/contrib/data.go
+++ b/shortcuts/contrib/data.go
@ -1,290 +0,0 @@
-package contrib
-
-import (
-	"fmt"
-	"net/url"
-
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-)
-
-// Contributor 贡献者信息
-type Contributor struct {
-	Login     string
-	Name      string
-	Commits   int
-	Additions int
-	Deletions int
-	Issues    int
-	PRs       int
-	Score     float64
-}
-
-// AHP 权重（基于层次分析法计算）
-const (
-	WeightCommits   = 0.143
-	WeightCodeLines = 0.286
-	WeightPRs       = 0.071
-	WeightIssues    = 0.05
-	WeightIssueSolve = 0.1
-	WeightRelease   = 0.1
-	WeightComments  = 0.083
-	WeightPRReview  = 0.083
-	WeightWiki      = 0.083
-)
-
-// fetchContributors 从 issue 和 PR 数据中提取贡献者
-func fetchContributors(ctx *common.RuntimeContext) ([]Contributor, error) {
-	contributorMap := make(map[string]*Contributor)
-
-	// 1. 从 Issue 列表中提取贡献者
-	issues, err := fetchAllIssues(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("fetch issues: %w", err)
-	}
-	for _, issue := range issues {
-		login := issue["login"]
-		name := issue["name"]
-		if login == "" {
-			continue
-		}
-		if _, exists := contributorMap[login]; !exists {
-			contributorMap[login] = &Contributor{
-				Login: login,
-				Name:  name,
-			}
-			if contributorMap[login].Name == "" {
-				contributorMap[login].Name = login
-			}
-		}
-		contributorMap[login].Issues++
-	}
-
-	// 2. 从 PR 列表中提取贡献者
-	prs, err := fetchAllPRs(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("fetch PRs: %w", err)
-	}
-	for _, pr := range prs {
-		login := pr["login"]
-		name := pr["name"]
-		if login == "" {
-			continue
-		}
-		if _, exists := contributorMap[login]; !exists {
-			contributorMap[login] = &Contributor{
-				Login: login,
-				Name:  name,
-			}
-			if contributorMap[login].Name == "" {
-				contributorMap[login].Name = login
-			}
-		}
-		contributorMap[login].PRs++
-	}
-
-	// 转换为切片
-	var contributors []Contributor
-	for _, c := range contributorMap {
-		contributors = append(contributors, *c)
-	}
-
-	if len(contributors) == 0 {
-		return nil, fmt.Errorf("no contributors found")
-	}
-
-	return contributors, nil
-}
-
-// fetchAllIssues 获取所有 Issue
-func fetchAllIssues(ctx *common.RuntimeContext) ([]map[string]string, error) {
-	var results []map[string]string
-	page := 1
-
-	for {
-		q := url.Values{}
-		q.Set("page", fmt.Sprintf("%d", page))
-		q.Set("limit", "100")
-		q.Set("state", "all")
-
-		env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/issues", ctx.Owner, ctx.Repo), q)
-		if err != nil {
-			return nil, err
-		}
-
-		data, ok := env.Data.(map[string]interface{})
-		if !ok {
-			break
-		}
-
-		issues, ok := data["issues"].([]interface{})
-		if !ok || len(issues) == 0 {
-			break
-		}
-
-		for _, item := range issues {
-			issue, ok := item.(map[string]interface{})
-			if !ok {
-				continue
-			}
-			author, ok := issue["author"].(map[string]interface{})
-			if !ok {
-				continue
-			}
-			login := getString(author, "login")
-			name := getString(author, "name")
-			if login != "" {
-				results = append(results, map[string]string{
-					"login": login,
-					"name":  name,
-				})
-			}
-		}
-
-		totalCount := getInt(data, "total_count")
-		if page*100 >= totalCount {
-			break
-		}
-		page++
-	}
-
-	return results, nil
-}
-
-// fetchAllPRs 获取所有 PR
-func fetchAllPRs(ctx *common.RuntimeContext) ([]map[string]string, error) {
-	var results []map[string]string
-	page := 1
-
-	for {
-		q := url.Values{}
-		q.Set("page", fmt.Sprintf("%d", page))
-		q.Set("limit", "100")
-		q.Set("state", "all")
-
-		env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/pulls", ctx.Owner, ctx.Repo), q)
-		if err != nil {
-			return nil, err
-		}
-
-		data, ok := env.Data.(map[string]interface{})
-		if !ok {
-			break
-		}
-
-		// PR 列表字段是 "pulls"
-		prs, ok := data["pulls"].([]interface{})
-		if !ok || len(prs) == 0 {
-			break
-		}
-
-		for _, item := range prs {
-			pr, ok := item.(map[string]interface{})
-			if !ok {
-				continue
-			}
-			// PR 的作者信息在 issue.author 中
-			login := ""
-			name := ""
-			if issue, ok := pr["issue"].(map[string]interface{}); ok {
-				if author, ok := issue["author"].(map[string]interface{}); ok {
-					login = getString(author, "login")
-					name = getString(author, "name")
-				}
-			}
-			if login != "" {
-				results = append(results, map[string]string{
-					"login": login,
-					"name":  name,
-				})
-			}
-		}
-
-		// 检查是否还有更多页
-		searchCount := getInt(data, "search_count")
-		if page*100 >= searchCount {
-			break
-		}
-		page++
-	}
-
-	return results, nil
-}
-
-// calculateScores 计算加权贡献分数
-func calculateScores(contributors []Contributor, issueCounts, prCounts map[string]int) []Contributor {
-	// 如果提供了额外的计数，更新贡献者数据
-	if issueCounts != nil {
-		for i := range contributors {
-			c := &contributors[i]
-			if count, ok := issueCounts[c.Login]; ok {
-				c.Issues = count
-			}
-		}
-	}
-	if prCounts != nil {
-		for i := range contributors {
-			c := &contributors[i]
-			if count, ok := prCounts[c.Login]; ok {
-				c.PRs = count
-			}
-		}
-	}
-
-	// 找到各指标的最大值（用于归一化）
-	maxIssues := 0
-	maxPRs := 0
-
-	for i := range contributors {
-		c := &contributors[i]
-		if c.Issues > maxIssues {
-			maxIssues = c.Issues
-		}
-		if c.PRs > maxPRs {
-			maxPRs = c.PRs
-		}
-	}
-
-	// 计算加权分数（归一化后）
-	for i := range contributors {
-		c := &contributors[i]
-
-		// 归一化到 0-1
-		normIssues := 0.0
-		normPRs := 0.0
-
-		if maxIssues > 0 {
-			normIssues = float64(c.Issues) / float64(maxIssues)
-		}
-		if maxPRs > 0 {
-			normPRs = float64(c.PRs) / float64(maxPRs)
-		}
-
-		// 加权求和（只用 issue 和 PR，因为 commits API 不可用）
-		c.Score = normIssues*WeightIssues + normPRs*WeightPRs
-	}
-
-	return contributors
-}
-
-// getString 从 map 中获取字符串
-func getString(m map[string]interface{}, key string) string {
-	if v, ok := m[key]; ok {
-		if s, ok := v.(string); ok {
-			return s
-		}
-	}
-	return ""
-}
-
-// getInt 从 map 中获取整数
-func getInt(m map[string]interface{}, key string) int {
-	if v, ok := m[key]; ok {
-		switch n := v.(type) {
-		case float64:
-			return int(n)
-		case int:
-			return n
-		}
-	}
-	return 0
-}
--- a/shortcuts/contrib/html.go
+++ b/shortcuts/contrib/html.go
@ -1,493 +0,0 @@
-package contrib
-
-import (
-	"fmt"
-	"html/template"
-	"os"
-	"sort"
-)
-
-// ReportData 报告数据
-type ReportData struct {
-	Owner        string
-	Repo         string
-	Contributors []Contributor
-	ChartLabels  template.JS
-	ChartValues  template.JS
-	TableRows    []TableRow
-}
-
-// TableRow 表格行
-type TableRow struct {
-	Rank       int
-	Login      string
-	Name       string
-	Commits    int
-	CodeLines  int
-	Issues     int
-	PRs        int
-	Score      float64
-	ScorePct   float64
-}
-
-// generateHTML 生成 HTML 报告
-func generateHTML(owner, repo string, contributors []Contributor, outputPath string) error {
-	// 按分数排序
-	sort.Slice(contributors, func(i, j int) bool {
-		return contributors[i].Score > contributors[j].Score
-	})
-
-	// 准备图表数据
-	var labels []string
-	var values []string
-	var tableRows []TableRow
-
-	totalScore := 0.0
-	for _, c := range contributors {
-		totalScore += c.Score
-	}
-
-	for i, c := range contributors {
-		labels = append(labels, fmt.Sprintf("%q", c.Login))
-		values = append(values, fmt.Sprintf("\"%.4f\"", c.Score))
-
-		scorePct := 0.0
-		if totalScore > 0 {
-			scorePct = c.Score / totalScore * 100
-		}
-
-		tableRows = append(tableRows, TableRow{
-			Rank:      i + 1,
-			Login:     c.Login,
-			Name:      c.Name,
-			Commits:   c.Commits,
-			CodeLines: c.Additions + c.Deletions,
-			Issues:    c.Issues,
-			PRs:       c.PRs,
-			Score:     c.Score,
-			ScorePct:  scorePct,
-		})
-	}
-
-	data := ReportData{
-		Owner:        owner,
-		Repo:         repo,
-		Contributors: contributors,
-		ChartLabels:  template.JS(fmt.Sprintf("[%s]", joinStrings(labels, ","))),
-		ChartValues:  template.JS(fmt.Sprintf("[%s]", joinStrings(values, ","))),
-		TableRows:    tableRows,
-	}
-
-	// 创建 HTML 文件
-	file, err := os.Create(outputPath)
-	if err != nil {
-		return err
-	}
-	defer file.Close()
-
-	// 解析并执行模板
-	tmpl, err := template.New("report").Parse(htmlTemplate)
-	if err != nil {
-		return err
-	}
-
-	return tmpl.Execute(file, data)
-}
-
-// joinStrings 连接字符串切片
-func joinStrings(strs []string, sep string) string {
-	result := ""
-	for i, s := range strs {
-		if i > 0 {
-			result += sep
-		}
-		result += s
-	}
-	return result
-}
-
-// htmlTemplate HTML 模板
-const htmlTemplate = `<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>贡献者报告 - {{.Owner}}/{{.Repo}}</title>
-    <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
-    <style>
-        * {
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            min-height: 100vh;
-            padding: 40px 20px;
-        }
-        .container {
-            max-width: 1200px;
-            margin: 0 auto;
-        }
-        .header {
-            text-align: center;
-            color: white;
-            margin-bottom: 40px;
-        }
-        .header h1 {
-            font-size: 2.5rem;
-            margin-bottom: 10px;
-            text-shadow: 2px 2px 4px rgba(0,0,0,0.3);
-        }
-        .header p {
-            font-size: 1.1rem;
-            opacity: 0.9;
-        }
-        .card {
-            background: white;
-            border-radius: 16px;
-            box-shadow: 0 20px 60px rgba(0,0,0,0.3);
-            padding: 30px;
-            margin-bottom: 30px;
-        }
-        .card h2 {
-            color: #333;
-            margin-bottom: 20px;
-            font-size: 1.5rem;
-            border-bottom: 3px solid #667eea;
-            padding-bottom: 10px;
-        }
-        .chart-container {
-            width: 100%;
-            height: 500px;
-        }
-        .table-container {
-            overflow-x: auto;
-        }
-        table {
-            width: 100%;
-            border-collapse: collapse;
-            margin-top: 20px;
-        }
-        th, td {
-            padding: 15px 20px;
-            text-align: left;
-            border-bottom: 1px solid #eee;
-        }
-        th {
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            color: white;
-            font-weight: 600;
-            text-transform: uppercase;
-            font-size: 0.85rem;
-            letter-spacing: 1px;
-        }
-        tr:hover {
-            background: #f8f9ff;
-        }
-        .rank {
-            font-weight: bold;
-            color: #667eea;
-            font-size: 1.2rem;
-        }
-        .rank-1 { color: #FFD700; }
-        .rank-2 { color: #C0C0C0; }
-        .rank-3 { color: #CD7F32; }
-        .score-bar {
-            background: #e9ecef;
-            border-radius: 10px;
-            height: 20px;
-            overflow: hidden;
-        }
-        .score-fill {
-            background: linear-gradient(90deg, #667eea, #764ba2);
-            height: 100%;
-            border-radius: 10px;
-            transition: width 0.5s ease;
-        }
-        .score-text {
-            font-weight: bold;
-            color: #667eea;
-        }
-        .avatar {
-            width: 40px;
-            height: 40px;
-            border-radius: 50%;
-            background: linear-gradient(135deg, #667eea, #764ba2);
-            display: inline-flex;
-            align-items: center;
-            justify-content: center;
-            color: white;
-            font-weight: bold;
-            margin-right: 10px;
-        }
-        .user-info {
-            display: flex;
-            align-items: center;
-        }
-        .user-name {
-            font-weight: 600;
-            color: #333;
-        }
-        .user-login {
-            color: #666;
-            font-size: 0.9rem;
-        }
-        .stats-grid {
-            display: grid;
-            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-            gap: 20px;
-            margin-top: 30px;
-        }
-        .stat-card {
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            border-radius: 12px;
-            padding: 20px;
-            color: white;
-            text-align: center;
-        }
-        .stat-value {
-            font-size: 2rem;
-            font-weight: bold;
-            margin-bottom: 5px;
-        }
-        .stat-label {
-            font-size: 0.9rem;
-            opacity: 0.9;
-        }
-        .weight-info {
-            background: #f8f9ff;
-            border-radius: 12px;
-            padding: 20px;
-            margin-top: 20px;
-        }
-        .weight-info h3 {
-            color: #667eea;
-            margin-bottom: 15px;
-        }
-        .weight-grid {
-            display: grid;
-            grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
-            gap: 10px;
-        }
-        .weight-item {
-            display: flex;
-            justify-content: space-between;
-            padding: 8px 12px;
-            background: white;
-            border-radius: 8px;
-            border-left: 4px solid #667eea;
-        }
-        .weight-label {
-            color: #666;
-        }
-        .weight-value {
-            font-weight: 600;
-            color: #667eea;
-        }
-        @media (max-width: 768px) {
-            .header h1 {
-                font-size: 1.8rem;
-            }
-            th, td {
-                padding: 10px 12px;
-            }
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <div class="header">
-            <h1>贡献者报告</h1>
-            <p>{{.Owner}}/{{.Repo}} - 团队成员贡献分析</p>
-        </div>
-
-        <div class="stats-grid">
-            <div class="stat-card">
-                <div class="stat-value">{{len .Contributors}}</div>
-                <div class="stat-label">贡献者总数</div>
-            </div>
-            <div class="stat-card">
-                <div class="stat-value" id="total-commits">0</div>
-                <div class="stat-label">总提交数</div>
-            </div>
-            <div class="stat-card">
-                <div class="stat-value" id="total-issues">0</div>
-                <div class="stat-label">总 Issue 数</div>
-            </div>
-            <div class="stat-card">
-                <div class="stat-value" id="total-prs">0</div>
-                <div class="stat-label">总 PR 数</div>
-            </div>
-        </div>
-
-        <div class="card">
-            <h2>贡献占比分布</h2>
-            <div id="pieChart" class="chart-container"></div>
-        </div>
-
-        <div class="card">
-            <h2>详细排名</h2>
-            <div class="table-container">
-                <table>
-                    <thead>
-                        <tr>
-                            <th>排名</th>
-                            <th>成员</th>
-                            <th>Commits</th>
-                            <th>代码行数</th>
-                            <th>Issues</th>
-                            <th>PRs</th>
-                            <th>贡献分数</th>
-                            <th>占比</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        {{range .TableRows}}
-                        <tr>
-                            <td class="rank rank-{{.Rank}}">{{.Rank}}</td>
-                            <td>
-                                <div class="user-info">
-                                    <div class="avatar">{{slice .Login 0 1}}</div>
-                                    <div>
-                                        <div class="user-name">{{.Name}}</div>
-                                        <div class="user-login">@{{.Login}}</div>
-                                    </div>
-                                </div>
-                            </td>
-                            <td>{{.Commits}}</td>
-                            <td>{{.CodeLines}}</td>
-                            <td>{{.Issues}}</td>
-                            <td>{{.PRs}}</td>
-                            <td class="score-text">{{printf "%.4f" .Score}}</td>
-                            <td>
-                                <div class="score-bar">
-                                    <div class="score-fill" style="width: {{printf "%.1f" .ScorePct}}%"></div>
-                                </div>
-                                <small>{{printf "%.1f" .ScorePct}}%</small>
-                            </td>
-                        </tr>
-                        {{end}}
-                    </tbody>
-                </table>
-            </div>
-        </div>
-
-        <div class="card">
-            <h2>AHP 权重说明</h2>
-            <div class="weight-info">
-                <h3>层次分析法 (AHP) 权重分配</h3>
-                <div class="weight-grid">
-                    <div class="weight-item">
-                        <span class="weight-label">Commits</span>
-                        <span class="weight-value">14.3%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">代码行数</span>
-                        <span class="weight-value">28.6%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">PR 合并数</span>
-                        <span class="weight-value">7.1%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">Issue 创建</span>
-                        <span class="weight-value">5.0%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">Issue 解决</span>
-                        <span class="weight-value">10.0%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">Release</span>
-                        <span class="weight-value">10.0%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">Issue 评论</span>
-                        <span class="weight-value">8.3%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">PR 评审</span>
-                        <span class="weight-value">8.3%</span>
-                    </div>
-                    <div class="weight-item">
-                        <span class="weight-label">Wiki</span>
-                        <span class="weight-value">8.3%</span>
-                    </div>
-                </div>
-            </div>
-        </div>
-    </div>
-
-    <script>
-        // 计算总数
-        let totalCommits = 0;
-        let totalIssues = 0;
-        let totalPRs = 0;
-        {{range .Contributors}}
-        totalCommits += {{.Commits}};
-        totalIssues += {{.Issues}};
-        totalPRs += {{.PRs}};
-        {{end}}
-        document.getElementById('total-commits').textContent = totalCommits;
-        document.getElementById('total-issues').textContent = totalIssues;
-        document.getElementById('total-prs').textContent = totalPRs;
-
-        // 初始化饼图
-        var chart = echarts.init(document.getElementById('pieChart'));
-        var option = {
-            tooltip: {
-                trigger: 'item',
-                formatter: '{a} <br/>{b}: {c} ({d}%)'
-            },
-            legend: {
-                orient: 'vertical',
-                left: 'left',
-                top: 'middle',
-                textStyle: {
-                    fontSize: 14
-                }
-            },
-            series: [{
-                name: '贡献占比',
-                type: 'pie',
-                radius: ['40%', '70%'],
-                center: ['60%', '50%'],
-                avoidLabelOverlap: true,
-                itemStyle: {
-                    borderRadius: 10,
-                    borderColor: '#fff',
-                    borderWidth: 2
-                },
-                label: {
-                    show: true,
-                    formatter: '{b}\n{d}%',
-                    fontSize: 12
-                },
-                emphasis: {
-                    label: {
-                        show: true,
-                        fontSize: 16,
-                        fontWeight: 'bold'
-                    }
-                },
-                data: [
-                    {{range .Contributors}}
-                    {
-                        value: {{printf "%.4f" .Score}},
-                        name: '{{.Login}}'
-                    },
-                    {{end}}
-                ]
-            }]
-        };
-        chart.setOption(option);
-
-        // 响应式
-        window.addEventListener('resize', function() {
-            chart.resize();
-        });
-    </script>
-</body>
-</html>`
--- a/shortcuts/file/file.go
+++ b/shortcuts/file/file.go
@ -0,0 +1,427 @@
+package file
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/url"
+
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// v1RepoPath returns /v1/{owner}/{repo}
+func v1RepoPath(ctx *common.RuntimeContext) string {
+	return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+}
+
+func Shortcuts() []*common.Shortcut {
+	return []*common.Shortcut{
+		// === 浏览类 ===
+		{
+			Name:        "ls",
+			Description: "List files in root directory",
+			Flags: []common.Flag{
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/entries", q)
+				if err != nil {
+					return fmt.Errorf("获取目录列表失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "tree",
+			Description: "Show subdirectory or file details",
+			Flags: []common.Flag{
+				{Name: "path", Short: "p", Usage: "File or directory path", Required: true},
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				filepath, err := ctx.RequireArg("path", "--path src/main.go")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				q.Set("filepath", filepath)
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/sub_entries", q)
+				if err != nil {
+					return fmt.Errorf("获取路径详情失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "read",
+			Description: "Read file content",
+			Flags: []common.Flag{
+				{Name: "path", Short: "p", Usage: "File path", Required: true},
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				filepath, err := ctx.RequireArg("path", "--path README.md")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				q.Set("filepath", filepath)
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/sub_entries", q)
+				if err != nil {
+					return fmt.Errorf("读取文件失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "readme",
+			Description: "Read README file",
+			Flags: []common.Flag{
+				{Name: "path", Usage: "Subdirectory path for nested README"},
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				if p := ctx.Arg("path"); p != "" {
+					q.Set("filepath", p)
+				}
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/readme", q)
+				if err != nil {
+					return fmt.Errorf("读取 README 失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "search",
+			Description: "Search files by name",
+			Flags: []common.Flag{
+				{Name: "q", Short: "q", Usage: "Search keyword"},
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				if kw := ctx.Arg("q"); kw != "" {
+					q.Set("search", kw)
+				}
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/files", q)
+				if err != nil {
+					return fmt.Errorf("搜索文件失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === 文件 CRUD ===
+		{
+			Name:        "create",
+			Description: "Create a new file",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("创建文件 %s", ctx.Arg("path")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "path", Short: "p", Usage: "File path", Required: true},
+				{Name: "content", Short: "c", Usage: "File content (plain text)", Required: true},
+				{Name: "branch", Short: "b", Usage: "Target branch", Required: true},
+				{Name: "message", Short: "m", Usage: "Commit message", Required: true},
+				{Name: "new-branch", Usage: "Create on a new branch"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				filepath, err := ctx.RequireArg("path", "--path docs/new.md")
+				if err != nil {
+					return err
+				}
+				content, err := ctx.RequireArg("content", `--content "# Hello"`)
+				if err != nil {
+					return err
+				}
+				branch, err := ctx.RequireArg("branch", "--branch master")
+				if err != nil {
+					return err
+				}
+				message, err := ctx.RequireArg("message", `--message "add new file"`)
+				if err != nil {
+					return err
+				}
+				body := map[string]interface{}{
+					"filepath":         filepath,
+					"base64_filepath":  base64.StdEncoding.EncodeToString([]byte(filepath)),
+					"branch":           branch,
+					"content":          base64.StdEncoding.EncodeToString([]byte(content)),
+					"message":          message,
+				}
+				if nb := ctx.Arg("new-branch"); nb != "" {
+					body["new_branch"] = nb
+				}
+				env, err := ctx.CallAPI("POST", ctx.RepoPath()+"/create_file", body)
+				if err != nil {
+					return fmt.Errorf("创建文件失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "update",
+			Description: "Update an existing file",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新文件 %s", ctx.Arg("path")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "path", Short: "p", Usage: "File path", Required: true},
+				{Name: "content", Short: "c", Usage: "New file content (plain text)", Required: true},
+				{Name: "branch", Short: "b", Usage: "Target branch", Required: true},
+				{Name: "sha", Usage: "File SHA (auto-fetched if omitted)"},
+				{Name: "message", Short: "m", Usage: "Commit message", Required: true},
+				{Name: "new-branch", Usage: "Create on a new branch"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				filepath, err := ctx.RequireArg("path", "--path README.md")
+				if err != nil {
+					return err
+				}
+				content, err := ctx.RequireArg("content", `--content "updated content"`)
+				if err != nil {
+					return err
+				}
+				branch, err := ctx.RequireArg("branch", "--branch master")
+				if err != nil {
+					return err
+				}
+				message, err := ctx.RequireArg("message", `--message "update file"`)
+				if err != nil {
+					return err
+				}
+				// Auto-fetch sha if not provided
+				sha := ctx.Arg("sha")
+				if sha == "" {
+					sha, err = fetchFileSha(ctx, filepath, branch)
+					if err != nil {
+						return fmt.Errorf("自动获取文件 SHA 失败，请用 --sha 手动指定: %w", err)
+					}
+				}
+				body := map[string]interface{}{
+					"filepath": filepath,
+					"branch":   branch,
+					"content":  content,
+					"sha":      sha,
+					"message":  message,
+				}
+				if nb := ctx.Arg("new-branch"); nb != "" {
+					body["new_branch"] = nb
+				}
+				env, err := ctx.CallAPI("PUT", ctx.RepoPath()+"/update_file", body)
+				if err != nil {
+					return fmt.Errorf("更新文件失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "delete",
+			Description: "Delete a file",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除文件 %s", ctx.Arg("path")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "path", Short: "p", Usage: "File path", Required: true},
+				{Name: "branch", Short: "b", Usage: "Target branch", Required: true},
+				{Name: "sha", Usage: "File SHA (auto-fetched if omitted)"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				filepath, err := ctx.RequireArg("path", "--path old-file.txt")
+				if err != nil {
+					return err
+				}
+				branch, err := ctx.RequireArg("branch", "--branch master")
+				if err != nil {
+					return err
+				}
+				// Auto-fetch sha if not provided
+				sha := ctx.Arg("sha")
+				if sha == "" {
+					sha, err = fetchFileSha(ctx, filepath, branch)
+					if err != nil {
+						return fmt.Errorf("自动获取文件 SHA 失败，请用 --sha 手动指定: %w", err)
+					}
+				}
+				body := map[string]interface{}{
+					"filepath": filepath,
+					"branch":   branch,
+					"sha":      sha,
+				}
+				env, err := ctx.CallAPI("DELETE", ctx.RepoPath()+"/delete_file", body)
+				if err != nil {
+					return fmt.Errorf("删除文件失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "batch",
+			Description: "Batch create/update/delete files in one commit",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("批量提交文件到分支 %s", ctx.Arg("branch")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "branch", Short: "b", Usage: "Target branch", Required: true},
+				{Name: "message", Short: "m", Usage: "Commit message", Required: true},
+				{Name: "files", Short: "f", Usage: "JSON array: [{\"action_type\":\"create\",\"file_path\":\"x\",\"content\":\"y\"}]", Required: true},
+				{Name: "new-branch", Usage: "Create on a new branch"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				branch, err := ctx.RequireArg("branch", "--branch master")
+				if err != nil {
+					return err
+				}
+				message, err := ctx.RequireArg("message", `--message "batch update"`)
+				if err != nil {
+					return err
+				}
+				filesJSON, err := ctx.RequireArg("files", `--files '[{"action_type":"create","file_path":"a.txt","content":"hello"}]'`)
+				if err != nil {
+					return err
+				}
+				var files []map[string]interface{}
+				if err := json.Unmarshal([]byte(filesJSON), &files); err != nil {
+					return fmt.Errorf("--files JSON 解析失败: %w", err)
+				}
+				body := map[string]interface{}{
+					"branch":  branch,
+					"message": message,
+					"files":   files,
+				}
+				if nb := ctx.Arg("new-branch"); nb != "" {
+					body["new_branch"] = nb
+				}
+				env, err := ctx.CallAPI("POST", v1RepoPath(ctx)+"/contents/batch", body)
+				if err != nil {
+					return fmt.Errorf("批量提交失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === Git 对象 ===
+		{
+			Name:        "commits",
+			Description: "List commit history",
+			Flags: []common.Flag{
+				{Name: "ref", Usage: "Branch, tag, or commit SHA"},
+				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
+				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				q.Set("page", ctx.Arg("page"))
+				q.Set("limit", ctx.Arg("limit"))
+				if ref := ctx.Arg("ref"); ref != "" {
+					q.Set("ref", ref)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/commits", q)
+				if err != nil {
+					return fmt.Errorf("获取提交历史失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "diff",
+			Description: "Show diff of a commit",
+			Flags: []common.Flag{
+				{Name: "sha", Short: "s", Usage: "Commit SHA", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				sha, err := ctx.RequireArg("sha", "--sha abc1234")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/commits/%s/diff", v1RepoPath(ctx), sha), nil)
+				if err != nil {
+					return fmt.Errorf("获取 diff 失败: %w", err)
+				}
+				return ctx.Output(env)
+			},
+		},
+	}
+}
+
+// fetchFileSha retrieves the current SHA of a file via sub_entries API.
+func fetchFileSha(ctx *common.RuntimeContext, filepath, ref string) (string, error) {
+	q := url.Values{}
+	q.Set("filepath", filepath)
+	if ref != "" {
+		q.Set("ref", ref)
+	}
+	env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/sub_entries", q)
+	if err != nil {
+		return "", err
+	}
+	data, ok := env.Data.(map[string]interface{})
+	if !ok {
+		return "", fmt.Errorf("响应格式异常")
+	}
+	entries, ok := data["entries"].(map[string]interface{})
+	if !ok {
+		// Try flat structure
+		if sha, ok := data["sha"].(string); ok {
+			return sha, nil
+		}
+		return "", fmt.Errorf("响应中未找到 entries 或 sha 字段")
+	}
+	sha, _ := entries["sha"].(string)
+	if sha == "" {
+		return "", fmt.Errorf("文件 SHA 为空")
+	}
+	return sha, nil
+}
--- a/shortcuts/file/file_test.go
+++ b/shortcuts/file/file_test.go
@ -0,0 +1,459 @@
+package file
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// === 浏览类测试 ===
+
+func TestLsCallsEntriesEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"entries": []interface{}{
+				map[string]interface{}{"name": "README.md", "type": "file"},
+			},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "ls", map[string]string{})
+	if err != nil {
+		t.Fatalf("ls failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/entries.json")
+}
+
+func TestLsWithRef(t *testing.T) {
+	var requestedRef string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedRef = r.URL.Query().Get("ref")
+		writeJSON(t, w, map[string]interface{}{"entries": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "ls", map[string]string{"ref": "develop"})
+	if err != nil {
+		t.Fatalf("ls with ref failed: %v", err)
+	}
+	assertEqual(t, requestedRef, "develop")
+}
+
+func TestTreeCallsSubEntriesWithFilePath(t *testing.T) {
+	var requestedPath, requestedFilepath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedFilepath = r.URL.Query().Get("filepath")
+		writeJSON(t, w, map[string]interface{}{
+			"entries": map[string]interface{}{
+				"name": "main.go", "type": "file", "sha": "abc123",
+			},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "tree", map[string]string{"path": "src/main.go"})
+	if err != nil {
+		t.Fatalf("tree failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/sub_entries.json")
+	assertEqual(t, requestedFilepath, "src/main.go")
+}
+
+func TestReadCallsSubEntriesWithFilePath(t *testing.T) {
+	var requestedFilepath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedFilepath = r.URL.Query().Get("filepath")
+		writeJSON(t, w, map[string]interface{}{
+			"entries": map[string]interface{}{
+				"name": "main.go", "content": "package main", "sha": "abc123",
+			},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "read", map[string]string{"path": "main.go"})
+	if err != nil {
+		t.Fatalf("read failed: %v", err)
+	}
+	assertEqual(t, requestedFilepath, "main.go")
+}
+
+func TestReadmeCallsReadmeEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"name": "README.md", "content": "# Hello",
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "readme", map[string]string{})
+	if err != nil {
+		t.Fatalf("readme failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/readme.json")
+}
+
+func TestSearchCallsFilesWithKeyword(t *testing.T) {
+	var requestedPath, requestedSearch string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedSearch = r.URL.Query().Get("search")
+		writeJSON(t, w, []interface{}{
+			map[string]interface{}{"name": "test.go"},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "search", map[string]string{"q": "test"})
+	if err != nil {
+		t.Fatalf("search failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/files.json")
+	assertEqual(t, requestedSearch, "test")
+}
+
+// === 文件 CRUD 测试 ===
+
+func TestCreateEncodesContentBase64(t *testing.T) {
+	var payload map[string]interface{}
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{
+			"name": "new.txt", "sha": "abc123",
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "create", map[string]string{
+		"path":    "docs/new.txt",
+		"content": "hello world",
+		"branch":  "master",
+		"message": "add file",
+	})
+	if err != nil {
+		t.Fatalf("create failed: %v", err)
+	}
+
+	// Verify content is base64 encoded
+	encodedContent, ok := payload["content"].(string)
+	if !ok {
+		t.Fatal("content should be a string")
+	}
+	decoded, err := base64.StdEncoding.DecodeString(encodedContent)
+	if err != nil {
+		t.Fatalf("content is not valid base64: %v", err)
+	}
+	assertEqual(t, string(decoded), "hello world")
+
+	// Verify filepath is base64 encoded
+	encodedPath, ok := payload["base64_filepath"].(string)
+	if !ok {
+		t.Fatal("base64_filepath should be a string")
+	}
+	decodedPath, err := base64.StdEncoding.DecodeString(encodedPath)
+	if err != nil {
+		t.Fatalf("base64_filepath is not valid base64: %v", err)
+	}
+	assertEqual(t, string(decodedPath), "docs/new.txt")
+
+	assertEqual(t, payload["filepath"], "docs/new.txt")
+	assertEqual(t, payload["branch"], "master")
+	assertEqual(t, payload["message"], "add file")
+}
+
+func TestUpdateAutoFetchesSha(t *testing.T) {
+	var updatePayload map[string]interface{}
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET" && r.URL.Path == "/owner/repo/sub_entries.json":
+			writeJSON(t, w, map[string]interface{}{
+				"entries": map[string]interface{}{
+					"name": "README.md", "sha": "old-sha-123",
+				},
+			})
+		case r.Method == "PUT" && r.URL.Path == "/owner/repo/update_file.json":
+			updatePayload = decodeJSON(t, r)
+			writeJSON(t, w, map[string]interface{}{"status": float64(1), "message": "更新成功"})
+		default:
+			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "update", map[string]string{
+		"path":    "README.md",
+		"content": "updated content",
+		"branch":  "master",
+		"message": "update readme",
+	})
+	if err != nil {
+		t.Fatalf("update failed: %v", err)
+	}
+
+	assertEqual(t, updatePayload["sha"], "old-sha-123")
+	assertEqual(t, updatePayload["content"], "updated content")
+	assertEqual(t, updatePayload["filepath"], "README.md")
+}
+
+func TestUpdateUsesProvidedSha(t *testing.T) {
+	var updatePayload map[string]interface{}
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == "PUT" {
+			updatePayload = decodeJSON(t, r)
+			writeJSON(t, w, map[string]interface{}{"status": float64(1)})
+		}
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "update", map[string]string{
+		"path":    "README.md",
+		"content": "new content",
+		"branch":  "master",
+		"sha":     "manual-sha",
+		"message": "update",
+	})
+	if err != nil {
+		t.Fatalf("update with sha failed: %v", err)
+	}
+	assertEqual(t, updatePayload["sha"], "manual-sha")
+}
+
+func TestDeleteAutoFetchesSha(t *testing.T) {
+	var deletePayload map[string]interface{}
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET":
+			writeJSON(t, w, map[string]interface{}{
+				"entries": map[string]interface{}{
+					"name": "old.txt", "sha": "file-sha-456",
+				},
+			})
+		case r.Method == "DELETE":
+			deletePayload = decodeJSON(t, r)
+			writeJSON(t, w, map[string]interface{}{"status": float64(1), "message": "文件删除成功"})
+		default:
+			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "delete", map[string]string{
+		"path":   "old.txt",
+		"branch": "master",
+	})
+	if err != nil {
+		t.Fatalf("delete failed: %v", err)
+	}
+
+	assertEqual(t, deletePayload["sha"], "file-sha-456")
+	assertEqual(t, deletePayload["filepath"], "old.txt")
+	assertEqual(t, deletePayload["branch"], "master")
+}
+
+func TestBatchSendsFilesArray(t *testing.T) {
+	var payload map[string]interface{}
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{
+			"commit": map[string]interface{}{"sha": "abc"},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "batch", map[string]string{
+		"branch":  "master",
+		"message": "batch commit",
+		"files":   `[{"action_type":"create","file_path":"a.txt","content":"hello"}]`,
+	})
+	if err != nil {
+		t.Fatalf("batch failed: %v", err)
+	}
+
+	files, ok := payload["files"].([]interface{})
+	if !ok {
+		t.Fatalf("files should be array, got %T", payload["files"])
+	}
+	assertEqual(t, len(files), 1)
+	assertEqual(t, payload["branch"], "master")
+	assertEqual(t, payload["message"], "batch commit")
+}
+
+func TestBatchRejectsInvalidJSON(t *testing.T) {
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		writeJSON(t, w, map[string]interface{}{})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "batch", map[string]string{
+		"branch":  "master",
+		"message": "test",
+		"files":   "not-json",
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid JSON, got nil")
+	}
+}
+
+// === Git 对象测试 ===
+
+func TestCommitsCallsV1Endpoint(t *testing.T) {
+	var requestedPath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, []interface{}{
+			map[string]interface{}{"sha": "abc", "message": "test"},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "commits", map[string]string{})
+	if err != nil {
+		t.Fatalf("commits failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/commits.json")
+}
+
+func TestCommitsPassesPagination(t *testing.T) {
+	var page, limit string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		page = r.URL.Query().Get("page")
+		limit = r.URL.Query().Get("limit")
+		writeJSON(t, w, []interface{}{})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "commits", map[string]string{"page": "3", "limit": "10"})
+	if err != nil {
+		t.Fatalf("commits with pagination failed: %v", err)
+	}
+	assertEqual(t, page, "3")
+	assertEqual(t, limit, "10")
+}
+
+func TestDiffCallsCommitDiffEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"files": []interface{}{},
+		})
+	})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "diff", map[string]string{"sha": "abc1234"})
+	if err != nil {
+		t.Fatalf("diff failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/commits/abc1234/diff.json")
+}
+
+// === 必填参数验证 ===
+
+func TestCreateRequiresPath(t *testing.T) {
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "create", map[string]string{
+		"content": "hello", "branch": "master", "message": "test",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing --path")
+	}
+}
+
+func TestTreeRequiresPath(t *testing.T) {
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "tree", map[string]string{})
+	if err == nil {
+		t.Fatal("expected error for missing --path")
+	}
+}
+
+func TestDiffRequiresSha(t *testing.T) {
+	server := newFileTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runFileShortcut(t, server, "diff", map[string]string{})
+	if err == nil {
+		t.Fatal("expected error for missing --sha")
+	}
+}
+
+// === helpers ===
+
+func runFileShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
+	t.Helper()
+	shortcut := findFileShortcut(t, name)
+	ctx := &common.RuntimeContext{
+		Client: &client.Client{
+			HTTP:    server.Client(),
+			BaseURL: server.URL,
+		},
+		Owner:  "owner",
+		Repo:   "repo",
+		Format: "json",
+		Args:   args,
+	}
+	return shortcut.Run(ctx)
+}
+
+func findFileShortcut(t *testing.T, name string) *common.Shortcut {
+	t.Helper()
+	for _, s := range Shortcuts() {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("file shortcut %q not found", name)
+	return nil
+}
+
+func newFileTestServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(handler)
+}
+
+func decodeJSON(t *testing.T, r *http.Request) map[string]interface{} {
+	t.Helper()
+	var payload map[string]interface{}
+	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode JSON failed: %v", err)
+	}
+	return payload
+}
+
+func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
+	t.Helper()
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(payload); err != nil {
+		t.Fatalf("write JSON failed: %v", err)
+	}
+}
+
+func assertEqual(t *testing.T, got, want interface{}) {
+	t.Helper()
+	if fmt.Sprintf("%v", got) != fmt.Sprintf("%v", want) {
+		t.Fatalf("got %v (%T), want %v (%T)", got, got, want, want)
+	}
+}
+
+func assertPath(t *testing.T, got, want string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("path: got %s, want %s", got, want)
+	}
+}
--- a/shortcuts/gitlink-cli.exe
+++ b/shortcuts/gitlink-cli.exe
--- a/shortcuts/issue/batch.go
+++ b/shortcuts/issue/batch.go
@ -1,16 +1,20 @@
 package issue

 import (
-	"encoding/csv"
-	"fmt"
-	"os"
-	"strconv"
-	"strings"
+	"encoding/csv"   // CSV 文件解析，用于从文件读取 Issue 编号
+	"fmt"            // 格式化输出，用于构建字符串和错误信息
+	"os"             // 文件操作，用于打开 CSV 文件
+	"strconv"        // 字符串和数字之间的转换
+	"strings"        // 字符串处理，用于分割、修剪等操作

-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common" // 公共工具包，包含 Shortcut、RuntimeContext 等
 )

-// Priority constants
+// === 优先级常量 ===
+// priorityLow: 低优先级
+// priorityNormal: 普通优先级（默认）
+// priorityHigh: 高优先级
+// priorityUrgent: 紧急优先级
 const (
 	priorityLow    = 1
 	priorityNormal = 2
@ -18,7 +22,12 @@ const (
 	priorityUrgent = 4
 )

-// Status constants
+// === 状态常量 ===
+// statusNew: 新建
+// statusInProgress: 进行中
+// statusResolved: 已解决
+// statusClosed: 已关闭
+// statusRejected: 已拒绝
 const (
 	statusNew        = 1
 	statusInProgress = 2
@ -27,7 +36,14 @@ const (
 	statusRejected   = 6
 )

-// Tracker constants
+// === 类型常量（Tracker）===
+// trackerBug: 缺陷
+// trackerFeature: 功能
+// trackerSupport: 支持
+// trackerDoc: 文档
+// trackerTest: 测试
+// trackerDuplicate: 重复
+// trackerQuestion: 疑问
 const (
 	trackerBug       = 1
 	trackerFeature   = 2
@ -38,6 +54,11 @@ const (
 	trackerQuestion  = 7
 )

+// === 名称映射表 ===
+// priorityNames: 优先级数字 ID → 英文名称
+// statusNames: 状态数字 ID → 英文名称
+// trackerNames: 类型数字 ID → 英文名称
+// 作用：把数字 ID 转换成可读的英文名称，方便输出结果
 var priorityNames = map[int]string{
 	priorityLow:    "low",
 	priorityNormal: "normal",
@ -63,8 +84,10 @@ var trackerNames = map[int]string{
 	trackerQuestion:  "question",
 }

-// Tag name → GitLink tag ID mapping
-// Collect IDs from web UI DevTools: change tag → capture PATCH payload → get issue_tag_ids value
+// === 标签 ID 映射 ===
+// tagIDs: 中文标签名称 → GitLink 标签 ID
+// 获取方式：从网页端 DevTools 抓包获取（修改标签 → 捕获 PATCH 请求体 → 获取 issue_tag_ids 值）
+// 注意：这些 ID 是项目特定的，不同项目可能不同
 var tagIDs = map[string]int{
 	"缺陷": 315526,
 	"功能": 315527,
@ -78,7 +101,9 @@ var tagIDs = map[string]int{
 	"搁置": 315532,
 }

-// labelNames returns all known tag names from the given mapping.
+// labelNames 返回所有已知的标签名称（逗号分隔）
+// 参数: tags - 标签名称到 ID 的映射
+// 返回: 所有标签名称的字符串，用逗号分隔
 func labelNames(tags map[string]int) string {
 	var names []string
 	for name := range tags {
@ -87,28 +112,31 @@ func labelNames(tags map[string]int) string {
 	return strings.Join(names, ", ")
 }

-// BatchResult is a single item result in a batch operation.
+// === 结果结构体 ===
+
+// BatchResult 表示单个 Issue 的操作结果
 type BatchResult struct {
-	Number string `json:"number" yaml:"number"`
-	Action string `json:"action" yaml:"action"`
-	Status string `json:"status" yaml:"status"`
-	Error  string `json:"error,omitempty" yaml:"error,omitempty"`
+	Number string `json:"number" yaml:"number"` // Issue 编号
+	Action string `json:"action" yaml:"action"` // 操作类型：close/set-status/set-priority/set-assignee/set-label
+	Status string `json:"status" yaml:"status"` // 操作状态：planned（预览）/closed（已关闭）/failed（失败）
+	Error  string `json:"error,omitempty" yaml:"error,omitempty"` // 错误信息（失败时）
 }

-// BatchSummary is the aggregate result of a batch operation.
+// BatchSummary 表示批量操作的汇总报告
 type BatchSummary struct {
-	Repository string        `json:"repository" yaml:"repository"`
-	Action     string        `json:"action" yaml:"action"`
-	Value      string        `json:"value,omitempty" yaml:"value,omitempty"`
-	DryRun     bool          `json:"dry_run" yaml:"dry_run"`
-	Total      int           `json:"total" yaml:"total"`
-	Succeeded  int           `json:"succeeded" yaml:"succeeded"`
-	Failed     int           `json:"failed" yaml:"failed"`
-	Results    []BatchResult `json:"results" yaml:"results"`
+	Repository string        `json:"repository" yaml:"repository"` // 仓库名称（owner/repo）
+	Action     string        `json:"action" yaml:"action"`         // 操作类型
+	Value      string        `json:"value,omitempty" yaml:"value,omitempty"` // 操作目标值（如状态名、优先级名）
+	DryRun     bool          `json:"dry_run" yaml:"dry_run"`       // 是否是预览模式
+	Total      int           `json:"total" yaml:"total"`           // 总数量
+	Succeeded  int           `json:"succeeded" yaml:"succeeded"`   // 成功数量
+	Failed     int           `json:"failed" yaml:"failed"`         // 失败数量
+	Results    []BatchResult `json:"results" yaml:"results"`       // 所有操作结果列表
 }

-// ---- batch-close ----
+// === batch-close 命令：批量关闭 Issue ===

+// newBatchCloseShortcut 创建 batch-close 命令
 func newBatchCloseShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "batch-close",
@ -122,10 +150,21 @@ func newBatchCloseShortcut() *common.Shortcut {
 	}
 }

+// runBatchClose 执行批量关闭操作
+// 执行流程：
+// 1. 解析仓库信息
+// 2. 收集 Issue 编号（从 --numbers 参数或 CSV 文件）
+// 3. 初始化 BatchSummary 汇总对象
+// 4. 遍历每个 Issue 编号：
+//    - 如果是 dry-run，直接标记为 planned
+//    - 否则调用 updateIssueField 更新状态为 closed
+// 5. 输出汇总结果
 func runBatchClose(ctx *common.RuntimeContext) error {
+	// 步骤1：解析仓库信息
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
 	}
+	// 步骤2：收集 Issue 编号（支持 --numbers 参数和 --from CSV 文件）
 	numbers, err := collectIssueNumbers(ctx.Arg("numbers"), ctx.Arg("from"))
 	if err != nil {
 		return err
@ -134,6 +173,7 @@ func runBatchClose(ctx *common.RuntimeContext) error {
 		return fmt.Errorf("no issue numbers provided; use --numbers 1,2,3 or --from issues.csv")
 	}

+	// 步骤3：初始化汇总对象
 	dryRun := parseBool(ctx.Arg("dry-run"))
 	summary := BatchSummary{
 		Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
@ -143,14 +183,17 @@ func runBatchClose(ctx *common.RuntimeContext) error {
 		Results:    make([]BatchResult, 0, len(numbers)),
 	}

+	// 步骤4：遍历处理每个 Issue
 	for _, number := range numbers {
 		result := BatchResult{Number: number, Action: "close"}
 		if dryRun {
+			// 预览模式：不实际操作，只标记为 planned
 			result.Status = "planned"
 			summary.Succeeded++
 			summary.Results = append(summary.Results, result)
 			continue
 		}
+		// 实际操作：调用 updateIssueField 更新状态为 closed
 		if err := updateIssueField(ctx, number, map[string]interface{}{"status_id": statusClosed}); err != nil {
 			result.Status = "failed"
 			result.Error = err.Error()
@ -162,17 +205,20 @@ func runBatchClose(ctx *common.RuntimeContext) error {
 		summary.Results = append(summary.Results, result)
 	}

+	// 步骤5：输出汇总结果
 	if err := ctx.OutputData(summary); err != nil {
 		return err
 	}
+	// 如果有失败的操作，返回错误
 	if summary.Failed > 0 {
 		return fmt.Errorf("%d of %d issue(s) failed", summary.Failed, summary.Total)
 	}
 	return nil
 }

-// ---- batch-status ----
+// === batch-status 命令：批量修改 Issue 状态 ===

+// newBatchStatusShortcut 创建 batch-status 命令
 func newBatchStatusShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "batch-status",
@ -187,16 +233,21 @@ func newBatchStatusShortcut() *common.Shortcut {
 	}
 }

+// runBatchStatus 执行批量修改状态操作
+// 参数 --state 指定目标状态：new/in-progress/resolved/closed/rejected
 func runBatchStatus(ctx *common.RuntimeContext) error {
+	// 步骤1：解析仓库信息
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
 	}
+	// 步骤2：获取状态参数并转换为数字 ID
 	state := ctx.Arg("state")
 	statusID, err := parseStatus(state)
 	if err != nil {
 		return err
 	}

+	// 步骤3：收集 Issue 编号
 	numbers, err := collectIssueNumbers(ctx.Arg("numbers"), ctx.Arg("from"))
 	if err != nil {
 		return err
@ -205,6 +256,7 @@ func runBatchStatus(ctx *common.RuntimeContext) error {
 		return fmt.Errorf("no issue numbers provided; use --numbers 1,2,3 or --from issues.csv")
 	}

+	// 步骤4：初始化汇总对象
 	dryRun := parseBool(ctx.Arg("dry-run"))
 	summary := BatchSummary{
 		Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
@ -215,6 +267,7 @@ func runBatchStatus(ctx *common.RuntimeContext) error {
 		Results:    make([]BatchResult, 0, len(numbers)),
 	}

+	// 步骤5：遍历处理每个 Issue
 	for _, number := range numbers {
 		result := BatchResult{Number: number, Action: "set-status"}
 		if dryRun {
@ -223,6 +276,7 @@ func runBatchStatus(ctx *common.RuntimeContext) error {
 			summary.Results = append(summary.Results, result)
 			continue
 		}
+		// 调用 updateIssueField 更新状态
 		if err := updateIssueField(ctx, number, map[string]interface{}{"status_id": statusID}); err != nil {
 			result.Status = "failed"
 			result.Error = err.Error()
@ -234,6 +288,7 @@ func runBatchStatus(ctx *common.RuntimeContext) error {
 		summary.Results = append(summary.Results, result)
 	}

+	// 步骤6：输出汇总结果
 	if err := ctx.OutputData(summary); err != nil {
 		return err
 	}
@ -243,8 +298,9 @@ func runBatchStatus(ctx *common.RuntimeContext) error {
 	return nil
 }

-// ---- batch-priority ----
+// === batch-priority 命令：批量修改 Issue 优先级 ===

+// newBatchPriorityShortcut 创建 batch-priority 命令
 func newBatchPriorityShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "batch-priority",
@ -259,10 +315,13 @@ func newBatchPriorityShortcut() *common.Shortcut {
 	}
 }

+// runBatchPriority 执行批量修改优先级操作
+// 参数 --priority 指定目标优先级：low/normal/high/urgent
 func runBatchPriority(ctx *common.RuntimeContext) error {
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
 	}
+	// 获取优先级参数并转换为数字 ID
 	priority := ctx.Arg("priority")
 	priorityID, err := parsePriority(priority)
 	if err != nil {
@ -295,6 +354,7 @@ func runBatchPriority(ctx *common.RuntimeContext) error {
 			summary.Results = append(summary.Results, result)
 			continue
 		}
+		// 调用 updateIssueField 更新优先级
 		if err := updateIssueField(ctx, number, map[string]interface{}{"priority_id": priorityID}); err != nil {
 			result.Status = "failed"
 			result.Error = err.Error()
@ -315,8 +375,9 @@ func runBatchPriority(ctx *common.RuntimeContext) error {
 	return nil
 }

-// ---- batch-assign ----
+// === batch-assign 命令：批量分配 Issue ===

+// newBatchAssignShortcut 创建 batch-assign 命令
 func newBatchAssignShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "batch-assign",
@ -331,6 +392,8 @@ func newBatchAssignShortcut() *common.Shortcut {
 	}
 }

+// runBatchAssign 执行批量分配操作
+// 亮点：需要先把用户名转换成用户 ID（通过 API 查询）
 func runBatchAssign(ctx *common.RuntimeContext) error {
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
@ -355,6 +418,7 @@ func runBatchAssign(ctx *common.RuntimeContext) error {
 		Results:    make([]BatchResult, 0, len(numbers)),
 	}

+	// 非预览模式下，先解析用户 ID
 	var assigneeID interface{}
 	if !dryRun {
 		id, err := resolveUserID(ctx, assignee)
@ -372,7 +436,8 @@ func runBatchAssign(ctx *common.RuntimeContext) error {
 			summary.Results = append(summary.Results, result)
 			continue
 		}
-		if err := updateIssueField(ctx, number, map[string]interface{}{"assigned_to_id": assigneeID}); err != nil {
+		// 调用 updateIssueField 分配用户
+		if err := updateIssueField(ctx, number, map[string]interface{}{"assigner_ids": []interface{}{assigneeID}}); err != nil {
 			result.Status = "failed"
 			result.Error = err.Error()
 			summary.Failed++
@ -392,14 +457,15 @@ func runBatchAssign(ctx *common.RuntimeContext) error {
 	return nil
 }

-// ---- batch-label ----
+// === batch-label 命令：批量修改 Issue 标签 ===

+// newBatchLabelShortcut 创建 batch-label 命令
 func newBatchLabelShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "batch-label",
 		Description: "Change tracker label for multiple issues",
 		Flags: []common.Flag{
-			{Name: "label", Short: "l", Usage: "Target label: bug, feature, support, doc, test, duplicate, question", Required: true},
+			{Name: "label", Short: "l", Usage: "Target label: bug, feature, support, doc, test, duplicate, question, or Chinese names (缺陷/功能/文档/重复/疑问/支持/任务/测试/协助/搁置)", Required: true},
 			{Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers, e.g. 1,2,3"},
 			{Name: "from", Usage: "Read issue numbers from a CSV file"},
 			{Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
@ -408,12 +474,20 @@ func newBatchLabelShortcut() *common.Shortcut {
 	}
 }

+// runBatchLabel 执行批量修改标签操作
+// 参数 --label 可以是英文（bug/feature）或中文（缺陷/功能）
 func runBatchLabel(ctx *common.RuntimeContext) error {
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
 	}
+	// 获取标签参数并转换为数字 ID
 	label := ctx.Arg("label")
-	trackerID, err := parseTracker(label)
+
+	tags, err := resolveIssueTags(ctx)
+	if err != nil {
+		return fmt.Errorf("cannot resolve issue tags: %w", err)
+	}
+	tagID, err := parseLabel(label, tags)
 	if err != nil {
 		return err
 	}
@ -444,7 +518,8 @@ func runBatchLabel(ctx *common.RuntimeContext) error {
 			summary.Results = append(summary.Results, result)
 			continue
 		}
-		if err := updateIssueField(ctx, number, map[string]interface{}{"tracker_id": trackerID}); err != nil {
+		// 调用 updateIssueField 修改标签（issue_tag_ids 是数组）
+		if err := updateIssueField(ctx, number, map[string]interface{}{"issue_tag_ids": []int{tagID}}); err != nil {
 			result.Status = "failed"
 			result.Error = err.Error()
 			summary.Failed++
@ -464,48 +539,148 @@ func runBatchLabel(ctx *common.RuntimeContext) error {
 	return nil
 }

-// ---- shared helpers ----
+// === batch-destroy 命令：批量删除 Issue ===

-// updateIssueField fetches the current issue to preserve subject/description,
-// then PATCHes with the given fields merged in.
+// newBatchDestroyShortcut 创建 batch-destroy 命令
+func newBatchDestroyShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "batch-destroy",
+		Description: "Delete multiple issues by issue numbers or a CSV file",
+		Flags: []common.Flag{
+			{Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers, e.g. 1,2,3"},
+			{Name: "from", Usage: "Read issue numbers from a CSV file"},
+			{Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
+		},
+		Run: runBatchDestroy,
+	}
+}
+
+// runBatchDestroy 执行批量删除操作
+// 使用 GitLink 原生批量删除接口 DELETE /v1/{owner}/{repo}/issues/batch_destroy
+// body: {"ids": [1, 2, 3]}
+func runBatchDestroy(ctx *common.RuntimeContext) error {
+	if err := ctx.ResolveOwnerRepo(); err != nil {
+		return err
+	}
+
+	numbers, err := collectIssueNumbers(ctx.Arg("numbers"), ctx.Arg("from"))
+	if err != nil {
+		return err
+	}
+	if len(numbers) == 0 {
+		return fmt.Errorf("no issue numbers provided; use --numbers 1,2,3 or --from issues.csv")
+	}
+
+	dryRun := parseBool(ctx.Arg("dry-run"))
+	summary := BatchSummary{
+		Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+		Action:     "destroy",
+		DryRun:     dryRun,
+		Total:      len(numbers),
+		Results:    make([]BatchResult, 0, len(numbers)),
+	}
+
+	if dryRun {
+		for _, number := range numbers {
+			summary.Results = append(summary.Results, BatchResult{Number: number, Action: "destroy", Status: "planned"})
+			summary.Succeeded++
+		}
+	} else {
+		// 构建 ids 数组
+		ids := make([]int, 0, len(numbers))
+		for _, number := range numbers {
+			id, err := strconv.Atoi(number)
+			if err != nil {
+				return fmt.Errorf("invalid issue number %q: %w", number, err)
+			}
+			ids = append(ids, id)
+		}
+
+		// 调用原生批量删除接口
+		body := map[string]interface{}{"ids": ids}
+		if _, err := ctx.CallAPI("DELETE", fmt.Sprintf("%s/issues/batch_destroy", v1RepoPath(ctx)), body); err != nil {
+			// 整体失败，标记所有为 failed
+			for _, number := range numbers {
+				summary.Results = append(summary.Results, BatchResult{Number: number, Action: "destroy", Status: "failed", Error: err.Error()})
+				summary.Failed++
+			}
+		} else {
+			for _, number := range numbers {
+				summary.Results = append(summary.Results, BatchResult{Number: number, Action: "destroy", Status: "deleted"})
+				summary.Succeeded++
+			}
+		}
+	}
+
+	if err := ctx.OutputData(summary); err != nil {
+		return err
+	}
+	if summary.Failed > 0 {
+		return fmt.Errorf("%d of %d issue(s) failed", summary.Failed, summary.Total)
+	}
+	return nil
+}
+
+// === 共享辅助函数 ===
+
+// updateIssueField 更新 Issue 的指定字段
+// 关键点：
+// 1. 先调用 fetchExistingIssue 获取当前 Issue 的标题和描述
+// 2. 必须在请求体中包含 subject 和 description，否则会被清空
+// 3. 把要更新的字段合并到 body 中
+// 4. 发送 PATCH 请求
 func updateIssueField(ctx *common.RuntimeContext, number string, fields map[string]interface{}) error {
+	// 获取当前 Issue 的标题和描述（避免更新时丢失）
 	current, err := fetchExistingIssue(ctx, number)
 	if err != nil {
 		return fmt.Errorf("fetch issue #%s: %w", number, err)
 	}

+	// 构建请求体，先包含必要的标题和描述
 	body := map[string]interface{}{
 		"subject":     current.Subject,
 		"description": current.Description,
 	}
+	// 合并要更新的字段
 	for k, v := range fields {
 		body[k] = v
 	}

+	// 发送 PATCH 请求更新 Issue
 	if _, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body); err != nil {
 		return fmt.Errorf("update issue #%s: %w", number, err)
 	}
 	return nil
 }

-// resolveUserID converts a login name to a numeric user ID via the users API.
+// resolveUserID 把用户名转换成用户 ID
+// 工作原理：
+// 1. 如果输入已经是数字，直接返回
+// 2. 否则调用 /users/{login} API 获取用户信息
+// 3. 从响应中提取 id 或 user_id 字段
+// 4. API 返回的数字是 float64 类型，需要转换成 int
 func resolveUserID(ctx *common.RuntimeContext, login string) (interface{}, error) {
+	// 如果输入是数字，直接返回
 	if id, err := strconv.Atoi(login); err == nil {
 		return id, nil
 	}

+	// 调用 API 获取用户信息
 	env, err := ctx.CallAPI("GET", fmt.Sprintf("/users/%s", login), nil)
 	if err != nil {
 		return nil, fmt.Errorf("lookup user %q: %w", login, err)
 	}
+	// 类型断言：把 Data 转换为 map[string]interface{}
 	data, ok := env.Data.(map[string]interface{})
 	if !ok {
 		return nil, fmt.Errorf("unexpected response for user %q", login)
 	}
+	// 尝试提取 id 字段
 	idFloat, ok := data["id"].(float64)
 	if ok {
 		return int(idFloat), nil
 	}
+	// 尝试提取 user_id 字段
 	userIDFloat, ok := data["user_id"].(float64)
 	if ok {
 		return int(userIDFloat), nil
@ -513,6 +688,9 @@ func resolveUserID(ctx *common.RuntimeContext, login string) (interface{}, error
 	return nil, fmt.Errorf("cannot determine user ID for %q", login)
 }

+// parseStatus 把用户输入的状态字符串转换成数字 ID
+// 支持多种写法：in-progress、in_progress、inprogress
+// 如果输入是数字，直接返回
 func parseStatus(state string) (int, error) {
 	switch strings.ToLower(strings.TrimSpace(state)) {
 	case "new":
@ -533,6 +711,7 @@ func parseStatus(state string) (int, error) {
 	}
 }

+// parsePriority 把用户输入的优先级字符串转换成数字 ID
 func parsePriority(p string) (int, error) {
 	switch strings.ToLower(strings.TrimSpace(p)) {
 	case "low":
@ -551,8 +730,20 @@ func parsePriority(p string) (int, error) {
 	}
 }

+// parseTracker 把用户输入的标签字符串转换成数字 ID
+// 支持中英文标签：
+// - 中文：缺陷/功能/文档/重复/疑问/支持/任务/测试/协助/搁置
+// - 英文：bug/feature/support/doc/test/duplicate/question
 func parseTracker(label string) (int, error) {
-	switch strings.ToLower(strings.TrimSpace(label)) {
+	trimmed := strings.TrimSpace(label)
+
+	// 先检查中文标签名称
+	if id, ok := tagIDs[trimmed]; ok {
+		return id, nil
+	}
+
+	// 再检查英文标签名称
+	switch strings.ToLower(trimmed) {
 	case "bug":
 		return trackerBug, nil
 	case "feature":
@ -571,12 +762,12 @@ func parseTracker(label string) (int, error) {
 		if id, err := strconv.Atoi(label); err == nil {
 			return id, nil
 		}
-		return 0, fmt.Errorf("invalid label %q: use bug, feature, support, doc, test, duplicate, or question", label)
+		return 0, fmt.Errorf("invalid label %q: use bug, feature, support, doc, test, duplicate, question, or Chinese names (%s)", label, labelNames(tagIDs))
 	}
 }

-// parseLabel converts a label name to its GitLink tag ID.
-// tags is the project's name→id mapping from resolveIssueTags.
+// parseLabel 根据项目的标签映射表，把标签名称转换成 GitLink 标签 ID
+// 参数: name - 标签名称; tags - 项目的名称→ID 映射
 func parseLabel(name string, tags map[string]int) (int, error) {
 	if id, ok := tags[name]; ok && id != 0 {
 		return id, nil
@ -587,6 +778,8 @@ func parseLabel(name string, tags map[string]int) (int, error) {
 	return 0, fmt.Errorf("invalid label %q: not found in project issue tags", name)
 }

+// collectIssueNumbers 从 --numbers 参数和 CSV 文件中收集 Issue 编号
+// 参数: numbersValue - --numbers 参数的值; csvPath - CSV 文件路径
 func collectIssueNumbers(numbersValue, csvPath string) ([]string, error) {
 	numbers, err := parseIssueNumbers(numbersValue)
 	if err != nil {
@ -603,6 +796,7 @@ func collectIssueNumbers(numbersValue, csvPath string) ([]string, error) {
 	return mergeIssueNumbers(numbers, csvNumbers), nil
 }

+// parseIssueNumbers 解析逗号分隔的 Issue 编号字符串
 func parseIssueNumbers(value string) ([]string, error) {
 	if strings.TrimSpace(value) == "" {
 		return nil, nil
@ -610,15 +804,22 @@ func parseIssueNumbers(value string) ([]string, error) {
 	return normalizeIssueNumbers(strings.Split(value, ","))
 }

+// readIssueNumbersFromCSV 从 CSV 文件读取 Issue 编号
+// 智能表头识别：
+// - 自动识别 number、issue_number、project_issues_index 列
+// - 如果没有匹配的表头，默认使用第一列
+// - 跳过表头行，从第二行开始读取
 func readIssueNumbersFromCSV(path string) ([]string, error) {
+	// 打开文件（defer 确保函数返回前关闭文件）
 	file, err := os.Open(path)
 	if err != nil {
 		return nil, fmt.Errorf("read CSV: %w", err)
 	}
 	defer file.Close()

+	// 创建 CSV 阅读器
 	reader := csv.NewReader(file)
-	reader.TrimLeadingSpace = true
+	reader.TrimLeadingSpace = true // 自动去除单元格前后空格
 	records, err := reader.ReadAll()
 	if err != nil {
 		return nil, fmt.Errorf("parse CSV: %w", err)
@ -627,42 +828,47 @@ func readIssueNumbersFromCSV(path string) ([]string, error) {
 		return nil, nil
 	}

+	// 智能识别表头：查找 number 列
 	numberColumn := -1
 	startRow := 0
 	for i, cell := range records[0] {
 		switch strings.ToLower(strings.TrimSpace(cell)) {
 		case "number", "issue_number", "project_issues_index":
 			numberColumn = i
-			startRow = 1
+			startRow = 1 // 找到表头，从第二行开始读取
 		}
 	}
 	if numberColumn == -1 {
-		numberColumn = 0
+		numberColumn = 0 // 没有找到表头，默认使用第一列
 	}

+	// 提取 Issue 编号
 	values := make([]string, 0, len(records)-startRow)
 	for _, record := range records[startRow:] {
 		if numberColumn >= len(record) {
-			continue
+			continue // 跳过列数不足的行
 		}
 		values = append(values, record[numberColumn])
 	}
 	return normalizeIssueNumbers(values)
 }

+// normalizeIssueNumbers 规范化 Issue 编号列表
+// 功能：去重、验证格式、过滤空值
 func normalizeIssueNumbers(values []string) ([]string, error) {
 	numbers := make([]string, 0, len(values))
-	seen := map[string]bool{}
+	seen := map[string]bool{} // 用于去重
 	for _, value := range values {
 		number := strings.TrimSpace(value)
 		if number == "" {
-			continue
+			continue // 跳过空值
 		}
+		// 验证是否是有效的整数
 		if _, err := strconv.ParseInt(number, 10, 64); err != nil {
 			return nil, fmt.Errorf("invalid issue number %q: must be an integer", number)
 		}
 		if seen[number] {
-			continue
+			continue // 跳过重复值
 		}
 		seen[number] = true
 		numbers = append(numbers, number)
@ -670,6 +876,7 @@ func normalizeIssueNumbers(values []string) ([]string, error) {
 	return numbers, nil
 }

+// mergeIssueNumbers 合并多个 Issue 编号列表（去重）
 func mergeIssueNumbers(values ...[]string) []string {
 	merged := []string{}
 	seen := map[string]bool{}
@ -685,6 +892,8 @@ func mergeIssueNumbers(values ...[]string) []string {
 	return merged
 }

+// parseBool 解析布尔值字符串
+// 返回 true 的条件：字符串解析成功且值为 true
 func parseBool(value string) bool {
 	parsed, err := strconv.ParseBool(strings.TrimSpace(value))
 	return err == nil && parsed
--- a/shortcuts/issue/batch_create.go
+++ b/shortcuts/issue/batch_create.go
@ -12,20 +12,21 @@ import (
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )

-var issueTagCache sync.Map
+var issueTagCache sync.Map  //全局缓存变量

+// 获取项目标签映射
 // resolveIssueTags fetches the project's issue tags and returns a name→id mapping.
 // Results are cached per owner/repo.
 func resolveIssueTags(ctx *common.RuntimeContext) (map[string]int, error) {
 	key := ctx.Owner + "/" + ctx.Repo
-	if cached, ok := issueTagCache.Load(key); ok {
-		return cached.(map[string]int), nil
+	if cached, ok := issueTagCache.Load(key); ok { //先从缓存查
+		return cached.(map[string]int), nil  // 命中缓存则直接返回
 	}

-	path := fmt.Sprintf("/v1/%s/%s/issue_tags", ctx.Owner, ctx.Repo)
+	path := fmt.Sprintf("/v1/%s/%s/issue_tags", ctx.Owner, ctx.Repo) //api路径
 	q := url.Values{}
 	q.Set("only_name", "true")
-	env, err := ctx.CallAPIWithQuery("GET", path, q)
+	env, err := ctx.CallAPIWithQuery("GET", path, q) // 发送GET请求获取项目标签列表
 	if err != nil {
 		return nil, fmt.Errorf("获取项目标签列表失败: %w", err)
 	}
@ -157,7 +158,7 @@ func runBatchCreate(ctx *common.RuntimeContext) error {
 	for i, input := range inputs {
 		label := fmt.Sprintf("#%d", i+1)
 		if input.Title != "" {
-			label = truncate(input.Title, 40)
+			label = truncate(input.Title, 40) // 用标题的前40个字符
 		}
 		result := BatchResult{Number: label, Action: "create"}

@ -168,6 +169,7 @@ func runBatchCreate(ctx *common.RuntimeContext) error {
 			continue
 		}

+		//把 createIssueInput 转换成 API 需要的 JSON map
 		body := buildCreateBody(ctx, input, template, tags)
 		env, err := ctx.CallAPI("POST", v1RepoPath(ctx)+"/issues", body)
 		if err != nil {
--- a/shortcuts/issue/issue.go
+++ b/shortcuts/issue/issue.go
@ -1,24 +1,29 @@
 package issue

 import (
-	"fmt"
+	"fmt"  //格式化字符串
 	"net/url"
-	"strconv"
+	"strconv"  //字符串和数字转换
 	"strings"

+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )

+// Ctx
 // v1RepoPath returns the v1 API path prefix: /v1/{owner}/{repo}
 func v1RepoPath(ctx *common.RuntimeContext) string {
 	return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
 }

+//内部数据结构，标题+描述，保存从 API 取回来的 Issue 原始数据
 type existingIssue struct {
 	Subject     string
 	Description string
 }

+// 所有issue命令的注册入口，返回所有issue命令
+// 在终端敲入issue +list命令时，遍历匹配到列表里的{Name: "list", ...}
 func Shortcuts() []*common.Shortcut {
 	return []*common.Shortcut{
 		newBatchCloseShortcut(),
@ -27,37 +32,44 @@ func Shortcuts() []*common.Shortcut {
 		newBatchAssignShortcut(),
 		newBatchLabelShortcut(),
 		newBatchCreateShortcut(),
+		newBatchDestroyShortcut(),
 		newLabelAddShortcut(),
 		newLabelRemoveShortcut(),
 		newLabelListShortcut(),
 		{
 			Name:        "list",
 			Description: "List issues",
+			Long:        "List issues in a repository with optional filtering by state and pagination.",
+			Example:     "  gitlink-cli issue +list --state open\n  gitlink-cli issue +list --state closed --page 1 --limit 50\n  gitlink-cli issue +list --columns id,subject,status,priority --state all",
 			Flags: []common.Flag{
-				{Name: "state", Short: "s", Usage: "Filter by state: open, closed, all", Default: "open"},
+				{Name: "state", Short: "s", Usage: "Filter by state", Default: "open", Choices: []string{"open", "closed", "all"}},
 				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
-			Run: func(ctx *common.RuntimeContext) error {
+			//后面拼接 API 路径时，需要用到 ctx.Owner 和 ctx.Repo
+			// 如果不知道 owner 和 repo ，后续的 API 调用就不知道该往哪发请求，所以必须作为前置校验放在最前面。
+			Run: func(ctx *common.RuntimeContext) error { 
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
-				q := url.Values{}
-				q.Set("page", ctx.Arg("page"))
-				q.Set("limit", ctx.Arg("limit"))
-				if s := ctx.Arg("state"); s != "" {
+				q := url.Values{}  // 创建空的URL查询参数容器q，后续通过set()添加键值对，最终拼接成形如 ?page=1&limit=20&state=open 的查询字符串
+				q.Set("page", ctx.Arg("page"))   
+				q.Set("limit", ctx.Arg("limit"))  //从命令行参数中读取 page（页码）和 limit（每页条数
+				if s := ctx.Arg("state"); s != "" {  // 如果用户传入了state参数
 					q.Set("state", s)
 				}
 				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issues", q)
 				if err != nil {
-					return fmt.Errorf("获取 Issue 列表失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "list", "issues", err).WithCommand(ctx.CommandName)
 				}
-				return ctx.Output(env)
+				return ctx.Output(env) //按照用户指定的格式（json/html/table...)输出issue列表
 			},
 		},
 		{
 			Name:        "create",
 			Description: "Create a new issue",
+			Long:        "Create a new issue in the repository. Requires --title. Supports --body, --assignee, --milestone, and --label.",
+			Example:     "  gitlink-cli issue +create --title \"Bug: login crash\" --body \"Steps to reproduce...\"\n  gitlink-cli issue +create --title \"Feature request\" --assignee zhangsan --label 3",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				title := ctx.Arg("title")
@ -88,14 +100,14 @@ func Shortcuts() []*common.Shortcut {
 					body["description"] = desc
 				}
 				if a := ctx.Arg("assignee"); a != "" {
-					body["assigned_to_id"] = a
+					body["assigner_ids"] = []interface{}{a}
 				}
 				if m := ctx.Arg("milestone"); m != "" {
 					body["fixed_version_id"] = m
 				}
 				env, err := ctx.CallAPI("POST", v1RepoPath(ctx)+"/issues", body)
 				if err != nil {
-					return fmt.Errorf("创建 Issue 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "create", "issue", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -103,6 +115,7 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "view",
 			Description: "View issue details",
+			Example:     "  gitlink-cli issue +view --number 42",
 			Flags: []common.Flag{
 				{Name: "number", Short: "n", Usage: "Issue number (as shown in the web URL)", Required: true},
 			},
@ -116,7 +129,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), nil)
 				if err != nil {
-					return fmt.Errorf("查看 Issue 失败: %w", err)
+					return clierrors.OpError(clierrors.KindNotFound, "view", "issue", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -124,6 +137,7 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "close",
 			Description: "Close an issue",
+			Example:     "  gitlink-cli issue +close --number 42\n  gitlink-cli issue +close --number 42 --dry-run",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				number := ctx.Arg("number")
@ -152,7 +166,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body)
 				if err != nil {
-					return fmt.Errorf("关闭 Issue 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "close", "issue", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -191,6 +205,7 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "update",
 			Description: "Update an issue",
+			Example:     "  gitlink-cli issue +update --number 42 --title \"Updated title\"\n  gitlink-cli issue +update --number 42 --state closed",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				number := ctx.Arg("number")
@ -200,7 +215,7 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "number", Short: "n", Usage: "Issue number (as shown in the web URL)", Required: true},
 				{Name: "title", Short: "t", Usage: "New title"},
 				{Name: "body", Short: "b", Usage: "New description"},
-				{Name: "state", Short: "s", Usage: "New state: open, closed, or numeric status_id"},
+				{Name: "state", Short: "s", Usage: "New state", Validate: validateIssueState},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
@ -214,7 +229,10 @@ func Shortcuts() []*common.Shortcut {
 				description := ctx.Arg("body")
 				state := ctx.Arg("state")
 				if title == "" && description == "" && state == "" {
-					return fmt.Errorf("at least one of --title, --body, or --state is required")
+					return clierrors.InputError(
+						"at least one of --title, --body, or --state is required",
+						"至少需要提供 --title、--body 或 --state 中的一个参数",
+					).WithCommand(ctx.CommandName)
 				}

 				current, err := fetchExistingIssue(ctx, number)
@ -233,7 +251,7 @@ func Shortcuts() []*common.Shortcut {
 					body["description"] = b
 				}
 				if s := ctx.Arg("state"); s != "" {
-					statusID, err := normalizeIssueStatus(s)
+					statusID, err := issueStateToStatusID(s)
 					if err != nil {
 						return err
 					}
@ -241,7 +259,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), body)
 				if err != nil {
-					return fmt.Errorf("更新 Issue 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "update", "issue", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -275,7 +293,175 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/issues/%s/journals", v1RepoPath(ctx), number), payload)
 				if err != nil {
-					return fmt.Errorf("添加 Issue 评论失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "comment", "issue", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === 元数据查询 ===
+		{
+			Name:        "statuses",
+			Description: "List issue statuses",
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issue_statues", nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "issue statuses", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "authors",
+			Description: "List issue authors",
+			Flags: []common.Flag{
+				{Name: "keyword", Short: "k", Usage: "Search keyword"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				if kw := ctx.Arg("keyword"); kw != "" {
+					q.Set("keyword", kw)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issue_authors", q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "issue authors", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "assigners",
+			Description: "List issue assignees",
+			Flags: []common.Flag{
+				{Name: "keyword", Short: "k", Usage: "Search keyword"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				q := url.Values{}
+				if kw := ctx.Arg("keyword"); kw != "" {
+					q.Set("keyword", kw)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issue_assigners", q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "issue assignees", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "priorities",
+			Description: "List issue priorities",
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/issue_priorities", nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "issue priorities", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === 评论管理 ===
+		{
+			Name:        "comment-edit",
+			Description: "Edit an issue comment",
+			Flags: []common.Flag{
+				{Name: "number", Short: "n", Usage: "Issue number", Required: true},
+				{Name: "comment-id", Short: "c", Usage: "Comment ID", Required: true},
+				{Name: "body", Short: "b", Usage: "New comment body", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				number, err := ctx.RequireArg("number", "--number 42")
+				if err != nil {
+					return err
+				}
+				commentID, err := ctx.RequireArg("comment-id", "--comment-id 123")
+				if err != nil {
+					return err
+				}
+				body, err := ctx.RequireArg("body", `--body "updated comment"`)
+				if err != nil {
+					return err
+				}
+				payload := map[string]interface{}{
+					"notes":           body,
+					"attachment_ids": []int{},
+				}
+				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s/journals/%s", v1RepoPath(ctx), number, commentID), payload)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "edit", "comment", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "comment-delete",
+			Description: "Delete an issue comment",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除 Issue #%s 的评论 #%s", ctx.Arg("number"), ctx.Arg("comment-id")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "number", Short: "n", Usage: "Issue number", Required: true},
+				{Name: "comment-id", Short: "c", Usage: "Comment ID", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				number, err := ctx.RequireArg("number", "--number 42")
+				if err != nil {
+					return err
+				}
+				commentID, err := ctx.RequireArg("comment-id", "--comment-id 123")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("%s/issues/%s/journals/%s", v1RepoPath(ctx), number, commentID), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "delete", "comment", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "replies",
+			Description: "List replies to a comment",
+			Flags: []common.Flag{
+				{Name: "number", Short: "n", Usage: "Issue number", Required: true},
+				{Name: "comment-id", Short: "c", Usage: "Parent comment ID", Required: true},
+				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
+				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				number, err := ctx.RequireArg("number", "--number 42")
+				if err != nil {
+					return err
+				}
+				commentID, err := ctx.RequireArg("comment-id", "--comment-id 123")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				q.Set("page", ctx.Arg("page"))
+				q.Set("limit", ctx.Arg("limit"))
+				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("%s/issues/%s/journals/%s/children_journals", v1RepoPath(ctx), number, commentID), q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "replies", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -286,15 +472,15 @@ func Shortcuts() []*common.Shortcut {
 func fetchExistingIssue(ctx *common.RuntimeContext, number string) (*existingIssue, error) {
 	getEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), number), nil)
 	if err != nil {
-		return nil, fmt.Errorf("获取 Issue 信息失败: %w", err)
+		return nil, clierrors.OpError(clierrors.KindNotFound, "view", "issue", err).WithCommand(ctx.CommandName)
 	}
 	issueData, ok := getEnv.Data.(map[string]interface{})
 	if !ok {
-		return nil, fmt.Errorf("failed to parse issue data")
+		return nil, clierrors.InputError("failed to parse issue data", "API 返回格式异常，请稍后重试").WithCommand(ctx.CommandName)
 	}
 	subject, _ := issueData["subject"].(string)
 	if subject == "" {
-		return nil, fmt.Errorf("failed to parse issue subject")
+		return nil, clierrors.InputError("failed to parse issue subject", "API 返回数据中缺少 subject 字段，请稍后重试").WithCommand(ctx.CommandName)
 	}
 	description, _ := issueData["description"].(string)
 	return &existingIssue{
@ -303,7 +489,18 @@ func fetchExistingIssue(ctx *common.RuntimeContext, number string) (*existingIss
 	}, nil
 }

-func normalizeIssueStatus(state string) (interface{}, error) {
+func validateIssueState(state string) error {
+	state = strings.ToLower(strings.TrimSpace(state))
+	if state == "open" || state == "closed" {
+		return nil
+	}
+	if _, err := strconv.Atoi(state); err == nil {
+		return nil
+	}
+	return fmt.Errorf("must be \"open\", \"closed\", or a numeric status_id, got %q", state)
+}
+
+func issueStateToStatusID(state string) (interface{}, error) {
 	switch strings.ToLower(strings.TrimSpace(state)) {
 	case "open":
 		return 1, nil
@ -313,6 +510,6 @@ func normalizeIssueStatus(state string) (interface{}, error) {
 		if id, err := strconv.Atoi(state); err == nil {
 			return id, nil
 		}
-		return nil, fmt.Errorf("invalid --state %q: use open, closed, or a numeric status_id", state)
+		return nil, fmt.Errorf("invalid state: %s", state)
 	}
 }
--- a/shortcuts/issue/issue_test.go
+++ b/shortcuts/issue/issue_test.go
@ -186,3 +186,201 @@ func assertEqual(t *testing.T, got interface{}, want interface{}) {
 		t.Fatalf("got %v (%T), want %v (%T)", got, got, want, want)
 	}
 }
+
+// === 新增命令测试 ===
+
+func TestStatusesCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"total_count": float64(2),
+			"statues":     []interface{}{},
+		})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "statuses", map[string]string{})
+	if err != nil {
+		t.Fatalf("statuses failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issue_statues.json")
+}
+
+func TestAuthorsCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath, requestedKeyword string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedKeyword = r.URL.Query().Get("keyword")
+		writeJSON(t, w, map[string]interface{}{"authors": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "authors", map[string]string{"keyword": "zhang"})
+	if err != nil {
+		t.Fatalf("authors failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issue_authors.json")
+	assertEqual(t, requestedKeyword, "zhang")
+}
+
+func TestAssignersCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"assigners": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "assigners", map[string]string{})
+	if err != nil {
+		t.Fatalf("assigners failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issue_assigners.json")
+}
+
+func TestPrioritiesCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"priorities": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "priorities", map[string]string{})
+	if err != nil {
+		t.Fatalf("priorities failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issue_priorities.json")
+}
+
+func TestCommentEditSendsNotesAndAttachmentIDs(t *testing.T) {
+	var payload map[string]interface{}
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{"id": float64(1)})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "comment-edit", map[string]string{
+		"number":     "42",
+		"comment-id": "100",
+		"body":       "updated comment",
+	})
+	if err != nil {
+		t.Fatalf("comment-edit failed: %v", err)
+	}
+	assertEqual(t, payload["notes"], "updated comment")
+}
+
+func TestCommentEditRequiresNumber(t *testing.T) {
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "comment-edit", map[string]string{
+		"comment-id": "100", "body": "test",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing --number")
+	}
+}
+
+func TestCommentDeleteCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath, requestedMethod string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedMethod = r.Method
+		writeJSON(t, w, map[string]interface{}{"status": float64(1)})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "comment-delete", map[string]string{
+		"number":     "42",
+		"comment-id": "100",
+	})
+	if err != nil {
+		t.Fatalf("comment-delete failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issues/42/journals/100.json")
+	assertEqual(t, requestedMethod, "DELETE")
+}
+
+func TestBatchDestroyCallsBatchDestroyEndpoint(t *testing.T) {
+	var requestedPath, requestedMethod string
+	var payload map[string]interface{}
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedMethod = r.Method
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{"status": float64(0), "message": "success"})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "batch-destroy", map[string]string{
+		"numbers": "1,2,3",
+	})
+	if err != nil {
+		t.Fatalf("batch-destroy failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issues/batch_destroy.json")
+	assertEqual(t, requestedMethod, "DELETE")
+
+	ids, ok := payload["ids"].([]interface{})
+	if !ok {
+		t.Fatalf("ids should be array, got %T", payload["ids"])
+	}
+	assertEqual(t, len(ids), 3)
+	assertEqual(t, ids[0], float64(1))
+	assertEqual(t, ids[1], float64(2))
+	assertEqual(t, ids[2], float64(3))
+}
+
+func TestBatchDestroyDryRun(t *testing.T) {
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("should not call API in dry-run mode")
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "batch-destroy", map[string]string{
+		"numbers": "10,20",
+		"dry-run": "true",
+	})
+	if err != nil {
+		t.Fatalf("batch-destroy dry-run failed: %v", err)
+	}
+}
+
+func TestBatchDestroyRequiresNumbers(t *testing.T) {
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "batch-destroy", map[string]string{})
+	if err == nil {
+		t.Fatal("expected error for missing --numbers")
+	}
+}
+
+func TestRepliesCallsChildrenJournals(t *testing.T) {
+	var requestedPath string
+	server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"journals": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runIssueShortcut(t, server, "replies", map[string]string{
+		"number":     "42",
+		"comment-id": "100",
+	})
+	if err != nil {
+		t.Fatalf("replies failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/issues/42/journals/100/children_journals.json")
+}
+
+func assertPath(t *testing.T, got, want string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("path: got %s, want %s", got, want)
+	}
+}
--- a/shortcuts/issue/label.go
+++ b/shortcuts/issue/label.go
@ -18,14 +18,20 @@ func newLabelAddShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			number, _ := ctx.RequireArg("number", "--number 42")
-			labelsStr, _ := ctx.RequireArg("labels", `--labels "bug,urgent"`)
+			number, err := ctx.RequireArg("number", "--number 42")
+			if err != nil {
+				return err
+			}
+			labelsStr, err := ctx.RequireArg("labels", `--labels "bug,urgent"`)
+			if err != nil {
+				return err
+			}
 			body := map[string]interface{}{
 				"labels": labelsStr,
 			}
 			env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/issues/%s/labels", v1RepoPath(ctx), number), body)
 			if err != nil {
-				return err
+				return fmt.Errorf("添加标签失败: %w", err)
 			}
 			return ctx.Output(env)
 		},
@ -44,12 +50,18 @@ func newLabelRemoveShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			number, _ := ctx.RequireArg("number", "--number 42")
-			label, _ := ctx.RequireArg("label", "--label bug")
-			env, err := ctx.CallAPI("DELETE", fmt.Sprintf("%s/issues/%s/labels/%s", v1RepoPath(ctx), number, label), nil)
+			number, err := ctx.RequireArg("number", "--number 42")
 			if err != nil {
 				return err
 			}
+			label, err := ctx.RequireArg("label", "--label bug")
+			if err != nil {
+				return err
+			}
+			env, err := ctx.CallAPI("DELETE", fmt.Sprintf("%s/issues/%s/labels/%s", v1RepoPath(ctx), number, label), nil)
+			if err != nil {
+				return fmt.Errorf("删除标签失败: %w", err)
+			}
 			return ctx.Output(env)
 		},
 	}
@ -66,11 +78,14 @@ func newLabelListShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			number, _ := ctx.RequireArg("number", "--number 42")
-			env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s/labels", v1RepoPath(ctx), number), nil)
+			number, err := ctx.RequireArg("number", "--number 42")
 			if err != nil {
 				return err
 			}
+			env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s/labels", v1RepoPath(ctx), number), nil)
+			if err != nil {
+				return fmt.Errorf("获取标签列表失败: %w", err)
+			}
 			return ctx.Output(env)
 		},
 	}
--- a/shortcuts/milestone/milestone.go
+++ b/shortcuts/milestone/milestone.go
@ -4,15 +4,24 @@ import (
 	"fmt"
 	"net/url"

+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )

+// v1RepoPath returns /v1/{owner}/{repo}
+func v1RepoPath(ctx *common.RuntimeContext) string {
+	return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
+}
+
 func Shortcuts() []*common.Shortcut {
 	return []*common.Shortcut{
 		{
 			Name:        "list",
 			Description: "List milestones",
 			Flags: []common.Flag{
+				{Name: "category", Short: "c", Usage: "Filter: opening, closed", Choices: []string{"opening", "closed"}},
+				{Name: "keyword", Short: "k", Usage: "Search keyword"},
+				{Name: "sort-by", Usage: "Sort field: created_on, updated_on, effective_date, issues_count, percent"},
 				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
@ -23,9 +32,18 @@ func Shortcuts() []*common.Shortcut {
 				q := url.Values{}
 				q.Set("page", ctx.Arg("page"))
 				q.Set("limit", ctx.Arg("limit"))
-				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1%s/milestones", ctx.RepoPath()), q)
+				if cat := ctx.Arg("category"); cat != "" {
+					q.Set("category", cat)
+				}
+				if kw := ctx.Arg("keyword"); kw != "" {
+					q.Set("keyword", kw)
+				}
+				if sb := ctx.Arg("sort-by"); sb != "" {
+					q.Set("sort_by", sb)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", v1RepoPath(ctx)+"/milestones", q)
 				if err != nil {
-					return err
+					return clierrors.OpError(clierrors.KindServer, "list", "milestones", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -33,6 +51,10 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "create",
 			Description: "Create a milestone",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("创建里程碑: %s", ctx.Arg("name")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "name", Short: "n", Usage: "Milestone name", Required: true},
 				{Name: "description", Short: "d", Usage: "Description"},
@ -52,43 +74,92 @@ func Shortcuts() []*common.Shortcut {
 				if due := ctx.Arg("due"); due != "" {
 					body["due_date"] = due
 				}
-				env, err := ctx.CallAPI("POST", fmt.Sprintf("/v1%s/milestones", ctx.RepoPath()), body)
+				env, err := ctx.CallAPI("POST", v1RepoPath(ctx)+"/milestones", body)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "create", "milestone", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "view",
+			Description: "View milestone details with issues",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "Milestone ID", Required: true},
+				{Name: "category", Short: "c", Usage: "Issue filter: all, opened, closed", Default: "all"},
+				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
+				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}
+				q := url.Values{}
+				q.Set("page", ctx.Arg("page"))
+				q.Set("limit", ctx.Arg("limit"))
+				if cat := ctx.Arg("category"); cat != "" {
+					q.Set("category", cat)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("%s/milestones/%s", v1RepoPath(ctx), id), q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindNotFound, "view", "milestone", err).WithCommand(ctx.CommandName)
+				}
+				// API returns {milestone: {...}, issues: [...], ...}; extract milestone for display.
+				if data, ok := env.Data.(map[string]interface{}); ok {
+					if ms, ok := data["milestone"]; ok {
+						return ctx.OutputData(ms)
+					}
+				}
 				return ctx.Output(env)
 			},
 		},
 		{
 			Name:        "update",
 			Description: "Update a milestone",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新里程碑 #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "Milestone ID", Required: true},
 				{Name: "name", Short: "n", Usage: "New name"},
 				{Name: "description", Short: "d", Usage: "New description"},
-				{Name: "due", Usage: "New due date (YYYY-MM-DD)"},
+				{Name: "date", Usage: "New effective date (YYYY-MM-DD)"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
-				id, _ := ctx.RequireArg("id", "--id 1")
-				body := map[string]interface{}{}
+				id, err := ctx.RequireArg("id", "--id 1")
+				if err != nil {
+					return err
+				}
+				// Fetch existing milestone to fill required fields
+				existing, err := fetchMilestone(ctx, id)
+				if err != nil {
+					return err
+				}
+				body := map[string]interface{}{
+					"name":           existing["name"],
+					"description":    existing["description"],
+					"effective_date": existing["effective_date"],
+				}
 				if n := ctx.Arg("name"); n != "" {
-					body["title"] = n
+					body["name"] = n
 				}
 				if d := ctx.Arg("description"); d != "" {
 					body["description"] = d
 				}
-				if due := ctx.Arg("due"); due != "" {
-					body["due_date"] = due
+				if dt := ctx.Arg("date"); dt != "" {
+					body["effective_date"] = dt
 				}
-				if len(body) == 0 {
-					return fmt.Errorf("at least one of --name, --description, --due is required")
-				}
-				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("/v1%s/milestones/%s", ctx.RepoPath(), id), body)
+				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/milestones/%s", v1RepoPath(ctx), id), body)
 				if err != nil {
-					return err
+					return clierrors.OpError(clierrors.KindServer, "update", "milestone", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -96,6 +167,10 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "delete",
 			Description: "Delete a milestone",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除里程碑 #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "Milestone ID", Required: true},
 			},
@ -103,13 +178,77 @@ func Shortcuts() []*common.Shortcut {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
-				id, _ := ctx.RequireArg("id", "--id 1")
-				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/v1%s/milestones/%s", ctx.RepoPath(), id), nil)
+				id, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}
+				// API requires body with name/description/effective_date
+				existing, err := fetchMilestone(ctx, id)
+				if err != nil {
+					return err
+				}
+				body := map[string]interface{}{
+					"name":           existing["name"],
+					"description":    existing["description"],
+					"effective_date": existing["effective_date"],
+				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("%s/milestones/%s", v1RepoPath(ctx), id), body)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "delete", "milestone", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "status",
+			Description: "Update milestone status (open/close)",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新里程碑 #%s 状态为 %s", ctx.Arg("id"), ctx.Arg("status")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "Milestone ID", Required: true},
+				{Name: "status", Short: "s", Usage: "New status", Required: true, Choices: []string{"opening", "closed"}},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 1")
+				if err != nil {
+					return err
+				}
+				status, err := ctx.RequireArg("status", "--status closed")
+				if err != nil {
+					return err
+				}
+				body := map[string]interface{}{
+					"status": status,
+				}
+				env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/milestones/%s/update_status", ctx.RepoPath(), id), body)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "update", "milestone status", err).WithCommand(ctx.CommandName)
+				}
 				return ctx.Output(env)
 			},
 		},
 	}
 }
+
+// fetchMilestone retrieves a milestone to get its current fields (needed for update/delete).
+func fetchMilestone(ctx *common.RuntimeContext, id string) (map[string]interface{}, error) {
+	env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/milestones/%s", v1RepoPath(ctx), id), nil)
+	if err != nil {
+		return nil, clierrors.OpError(clierrors.KindNotFound, "view", "milestone", err).WithCommand(ctx.CommandName)
+	}
+	data, ok := env.Data.(map[string]interface{})
+	if !ok {
+		return nil, clierrors.InputError("unexpected milestone format", "API 返回格式异常").WithCommand(ctx.CommandName)
+	}
+	// The response wraps in "milestone" key
+	if ms, ok := data["milestone"].(map[string]interface{}); ok {
+		return ms, nil
+	}
+	// Fallback: maybe flat structure
+	return data, nil
+}
--- a/shortcuts/milestone/milestone_test.go
+++ b/shortcuts/milestone/milestone_test.go
@ -0,0 +1,264 @@
+package milestone
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// === list ===
+
+func TestListCallsMilestonesEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"total_count":            float64(2),
+			"opening_milestone_count": float64(1),
+			"closed_milestone_count":  float64(1),
+			"milestones":             []interface{}{},
+		})
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "list", map[string]string{})
+	if err != nil {
+		t.Fatalf("list failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/milestones.json")
+}
+
+func TestListPassesFilters(t *testing.T) {
+	var cat, kw, sortBy string
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		cat = r.URL.Query().Get("category")
+		kw = r.URL.Query().Get("keyword")
+		sortBy = r.URL.Query().Get("sort_by")
+		writeJSON(t, w, map[string]interface{}{"milestones": []interface{}{}})
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "list", map[string]string{
+		"category": "opening",
+		"keyword":  "v1",
+		"sort-by":  "issues_count",
+	})
+	if err != nil {
+		t.Fatalf("list with filters failed: %v", err)
+	}
+	assertEqual(t, cat, "opening")
+	assertEqual(t, kw, "v1")
+	assertEqual(t, sortBy, "issues_count")
+}
+
+// === create ===
+
+func TestCreateSendsPayload(t *testing.T) {
+	var payload map[string]interface{}
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{"status": float64(0), "message": "success"})
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "create", map[string]string{
+		"name":        "v1.0",
+		"description": "First release",
+		"date":        "2026-12-31",
+	})
+	if err != nil {
+		t.Fatalf("create failed: %v", err)
+	}
+	assertEqual(t, payload["name"], "v1.0")
+	assertEqual(t, payload["description"], "First release")
+	assertEqual(t, payload["effective_date"], "2026-12-31")
+}
+
+func TestCreateRequiresName(t *testing.T) {
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	defer server.Close()
+
+	err := runShortcut(t, server, "create", map[string]string{
+		"description": "desc", "date": "2026-12-31",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing --name")
+	}
+}
+
+// === view ===
+
+func TestViewCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"milestone": map[string]interface{}{"id": float64(1), "name": "v1.0"},
+		})
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "view", map[string]string{"id": "1"})
+	if err != nil {
+		t.Fatalf("view failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/milestones/1.json")
+}
+
+// === update ===
+
+func TestUpdateAutoFetchesExisting(t *testing.T) {
+	var updatePayload map[string]interface{}
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET":
+			writeJSON(t, w, map[string]interface{}{
+				"milestone": map[string]interface{}{
+					"name":           "v1.0",
+					"description":    "Old desc",
+					"effective_date": "2026-12-31",
+				},
+			})
+		case r.Method == "PATCH":
+			updatePayload = decodeJSON(t, r)
+			writeJSON(t, w, map[string]interface{}{"status": float64(0)})
+		default:
+			t.Fatalf("unexpected: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "update", map[string]string{
+		"id":   "1",
+		"name": "v1.0-rc1",
+	})
+	if err != nil {
+		t.Fatalf("update failed: %v", err)
+	}
+	assertEqual(t, updatePayload["name"], "v1.0-rc1")
+	assertEqual(t, updatePayload["description"], "Old desc")
+	assertEqual(t, updatePayload["effective_date"], "2026-12-31")
+}
+
+// === delete ===
+
+func TestDeleteAutoFetchesExisting(t *testing.T) {
+	var deletePath string
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET":
+			writeJSON(t, w, map[string]interface{}{
+				"milestone": map[string]interface{}{
+					"name":           "v1.0",
+					"description":    "desc",
+					"effective_date": "2026-12-31",
+				},
+			})
+		case r.Method == "DELETE":
+			deletePath = r.URL.Path
+			writeJSON(t, w, map[string]interface{}{"status": float64(0)})
+		default:
+			t.Fatalf("unexpected: %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "delete", map[string]string{"id": "1"})
+	if err != nil {
+		t.Fatalf("delete failed: %v", err)
+	}
+	assertPath(t, deletePath, "/v1/owner/repo/milestones/1.json")
+}
+
+// === status ===
+
+func TestStatusCallsUpdateStatusEndpoint(t *testing.T) {
+	var requestedPath string
+	var payload map[string]interface{}
+	server := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{"status": float64(0)})
+	})
+	defer server.Close()
+
+	err := runShortcut(t, server, "status", map[string]string{
+		"id":     "1",
+		"status": "closed",
+	})
+	if err != nil {
+		t.Fatalf("status failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/milestones/1/update_status.json")
+	assertEqual(t, payload["status"], "closed")
+}
+
+// === helpers ===
+
+func runShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
+	t.Helper()
+	shortcut := findShortcut(t, name)
+	ctx := &common.RuntimeContext{
+		Client: &client.Client{
+			HTTP:    server.Client(),
+			BaseURL: server.URL,
+		},
+		Owner:  "owner",
+		Repo:   "repo",
+		Format: "json",
+		Args:   args,
+	}
+	return shortcut.Run(ctx)
+}
+
+func findShortcut(t *testing.T, name string) *common.Shortcut {
+	t.Helper()
+	for _, s := range Shortcuts() {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("milestone shortcut %q not found", name)
+	return nil
+}
+
+func newTestServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(handler)
+}
+
+func decodeJSON(t *testing.T, r *http.Request) map[string]interface{} {
+	t.Helper()
+	var payload map[string]interface{}
+	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode JSON failed: %v", err)
+	}
+	return payload
+}
+
+func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
+	t.Helper()
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(payload); err != nil {
+		t.Fatalf("write JSON failed: %v", err)
+	}
+}
+
+func assertEqual(t *testing.T, got, want interface{}) {
+	t.Helper()
+	if fmt.Sprintf("%v", got) != fmt.Sprintf("%v", want) {
+		t.Fatalf("got %v (%T), want %v (%T)", got, got, want, want)
+	}
+}
+
+func assertPath(t *testing.T, got, want string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("path: got %s, want %s", got, want)
+	}
+}
--- a/shortcuts/onboard/onboarding.go
+++ b/shortcuts/onboard/onboarding.go
@ -1,393 +0,0 @@
-package onboard
-
-import (
-	"fmt"
-	"net/url"
-	"strconv"
-	"strings"
-	"sync"
-
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-)
-
-// marker is a unique string embedded in welcome comments to detect existing ones.
-const marker = "<!-- gitlink-cli:onboard -->"
-
-// tagCache caches tag name→id mappings per owner/repo.
-var tagCache sync.Map
-
-// Shortcuts returns the onboarding shortcut group.
-func Shortcuts() []*common.Shortcut {
-	return []*common.Shortcut{
-		{
-			Name:        "welcome",
-			Description: "Add welcome comments to specific issues or tag-matched issues",
-			Flags: []common.Flag{
-				{Name: "issues", Short: "i", Usage: "Comma-separated issue numbers (e.g. 1,3,7)"},
-				{Name: "tag", Short: "t", Usage: "Tag name to match (comma-separated)", Default: "good first issue,help wanted"},
-				{Name: "template", Usage: "Custom welcome message template ({login}, {number}, {subject}, {description})"},
-				{Name: "force", Short: "f", Usage: "Force re-add even if already commented", Bool: true},
-			},
-			DryRun:     true,
-			DryRunHint: dryRunHint,
-			Run:        runWelcome,
-		},
-	}
-}
-
-func dryRunHint(ctx *common.RuntimeContext) (string, error) {
-	if issues := ctx.Arg("issues"); issues != "" {
-		return fmt.Sprintf("将为 issue #%s 添加新人引导评论", issues), nil
-	}
-	tag := ctx.Arg("tag")
-	if tag == "" {
-		tag = "good first issue,help wanted"
-	}
-	return fmt.Sprintf("将为所有 [%s] 标签的 issue 添加新人引导评论", tag), nil
-}
-
-func runWelcome(ctx *common.RuntimeContext) error {
-	if err := ctx.ResolveOwnerRepo(); err != nil {
-		return err
-	}
-
-	// --issues takes priority over --tag
-	if issueArg := ctx.Arg("issues"); issueArg != "" {
-		return runWelcomeByIssueNumbers(ctx, issueArg)
-	}
-
-	tagNames := ctx.Arg("tag")
-	if tagNames == "" {
-		tagNames = "good first issue,help wanted"
-	}
-
-	// resolve tag names → ids
-	tagMap, err := resolveTags(ctx)
-	if err != nil {
-		return err
-	}
-
-	var tagIDs []string
-	for _, name := range strings.Split(tagNames, ",") {
-		name = strings.TrimSpace(name)
-		if id, ok := tagMap[name]; ok {
-			tagIDs = append(tagIDs, strconv.Itoa(id))
-		}
-	}
-	if len(tagIDs) == 0 {
-		return fmt.Errorf("未找到匹配的标签: %s (可用: %v)", tagNames, tagNamesList(tagMap))
-	}
-
-	// fetch open issues with these tags
-	issues, err := fetchTaggedIssues(ctx, tagIDs)
-	if err != nil {
-		return err
-	}
-
-	return processIssues(ctx, issues)
-}
-
-// runWelcomeByIssueNumbers directly processes specified issue numbers,
-// skipping tag resolution and tag-based issue fetching.
-func runWelcomeByIssueNumbers(ctx *common.RuntimeContext, issueArg string) error {
-	issueNums, err := parseIssueNumbers(issueArg)
-	if err != nil {
-		return err
-	}
-
-	var issues []issueInfo
-	for _, num := range issueNums {
-		info, err := fetchIssueDetail(ctx, num)
-		if err != nil {
-			return fmt.Errorf("获取 issue #%d 失败: %w", num, err)
-		}
-		issues = append(issues, info)
-	}
-
-	return processIssues(ctx, issues)
-}
-
-// parseIssueNumbers parses a comma-separated string of issue numbers.
-func parseIssueNumbers(s string) ([]int, error) {
-	parts := strings.Split(s, ",")
-	var nums []int
-	for _, p := range parts {
-		p = strings.TrimSpace(p)
-		if p == "" {
-			continue
-		}
-		n, err := strconv.Atoi(p)
-		if err != nil {
-			return nil, fmt.Errorf("无效的 issue 编号: %q (必须是数字)", p)
-		}
-		nums = append(nums, n)
-	}
-	if len(nums) == 0 {
-		return nil, fmt.Errorf("--issues 参数为空")
-	}
-	return nums, nil
-}
-
-// fetchIssueDetail fetches a single issue's subject and description by number.
-func fetchIssueDetail(ctx *common.RuntimeContext, issueNumber int) (issueInfo, error) {
-	path := fmt.Sprintf("/v1/%s/%s/issues/%d", ctx.Owner, ctx.Repo, issueNumber)
-	env, err := ctx.CallAPIWithQuery("GET", path, nil)
-	if err != nil {
-		return issueInfo{}, err
-	}
-	data, _ := env.Data.(map[string]interface{})
-	subj := getString(data, "subject")
-	if subj == "" {
-		subj = fmt.Sprintf("issue #%d", issueNumber)
-	}
-	desc := getString(data, "description")
-	return issueInfo{number: issueNumber, subject: subj, description: desc}, nil
-}
-
-// processIssues handles the common issue processing loop used by both
-// --issues and --tag paths.
-func processIssues(ctx *common.RuntimeContext, issues []issueInfo) error {
-	tmpl := ctx.Arg("template")
-	if tmpl == "" {
-		tmpl = ""
-	}
-
-	type result struct {
-		num    int
-		action string
-		msg    string
-	}
-	var results []result
-
-	for _, issue := range issues {
-		force := ctx.Arg("force") == "true"
-		if !force && hasWelcomeComment(ctx, issue.number) {
-			results = append(results, result{issue.number, "skipped", fmt.Sprintf("#%d \"%s\" — 已有引导评论，跳过", issue.number, issue.subject)})
-			continue
-		}
-
-		// Render per-issue message with issue-specific variables.
-		body := renderComment(ctx, issue, tmpl)
-
-		if ctx.IsDryRun() {
-			fmt.Printf("\n--- 预览 #%d \"%s\" ---\n%s\n---\n", issue.number, issue.subject, body)
-			proceed, err := common.ConfirmAction(ctx)
-			if err != nil {
-				return err
-			}
-			if !proceed {
-				results = append(results, result{issue.number, "skipped", "用户取消"})
-				continue
-			}
-		}
-
-		if err := addComment(ctx, issue.number, body); err != nil {
-			results = append(results, result{issue.number, "error", err.Error()})
-		} else {
-			results = append(results, result{issue.number, "added", fmt.Sprintf("#%d \"%s\" — 已添加引导评论", issue.number, issue.subject)})
-		}
-	}
-
-	// output
-	added := 0
-	skipped := 0
-	errors := 0
-	for _, r := range results {
-		switch r.action {
-		case "added":
-			added++
-		case "skipped":
-			skipped++
-		case "error":
-			errors++
-		}
-	}
-	fmt.Printf("\n完成: 添加 %d, 跳过 %d, 错误 %d\n", added, skipped, errors)
-	for _, r := range results {
-		fmt.Printf("  [%s] %s\n", r.action, r.msg)
-	}
-
-	return nil
-}
-
-func resolveTags(ctx *common.RuntimeContext) (map[string]int, error) {
-	key := ctx.Owner + "/" + ctx.Repo
-	if cached, ok := tagCache.Load(key); ok {
-		return cached.(map[string]int), nil
-	}
-
-	path := fmt.Sprintf("/v1/%s/%s/issue_tags", ctx.Owner, ctx.Repo)
-	q := url.Values{}
-	q.Set("only_name", "true")
-	env, err := ctx.CallAPIWithQuery("GET", path, q)
-	if err != nil {
-		return nil, fmt.Errorf("获取标签列表失败: %w", err)
-	}
-
-	data, _ := env.Data.(map[string]interface{})
-	raw, _ := data["issue_tags"].([]interface{})
-	tags := make(map[string]int)
-	for _, item := range raw {
-		if t, ok := item.(map[string]interface{}); ok {
-			if name, ok := t["name"].(string); ok && name != "" {
-				switch v := t["id"].(type) {
-				case float64:
-					tags[name] = int(v)
-				case int:
-					tags[name] = v
-				}
-			}
-		}
-	}
-	if len(tags) == 0 {
-		return nil, fmt.Errorf("项目没有配置任务标签，请先在 GitLink 网页端创建")
-	}
-	tagCache.Store(key, tags)
-	return tags, nil
-}
-
-func tagNamesList(tags map[string]int) []string {
-	var names []string
-	for n := range tags {
-		names = append(names, n)
-	}
-	return names
-}
-
-type issueInfo struct {
-	number      int
-	subject     string
-	description string
-}
-
-func fetchTaggedIssues(ctx *common.RuntimeContext, tagIDs []string) ([]issueInfo, error) {
-	var all []issueInfo
-	page := 1
-
-	for {
-		q := url.Values{}
-		q.Set("state", "open")
-		q.Set("page", strconv.Itoa(page))
-		q.Set("limit", "100")
-		q.Set("issue_tag_ids", strings.Join(tagIDs, ","))
-
-		env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/issues", ctx.Owner, ctx.Repo), q)
-		if err != nil {
-			return nil, err
-		}
-
-		data, _ := env.Data.(map[string]interface{})
-		issues, _ := data["issues"].([]interface{})
-		if len(issues) == 0 {
-			break
-		}
-
-		for _, item := range issues {
-			if issue, ok := item.(map[string]interface{}); ok {
-				all = append(all, issueInfo{
-					number:  getInt(issue, "project_issues_index"),
-					subject: getString(issue, "subject"),
-				})
-			}
-		}
-
-		total := getInt(data, "total_count")
-		if page*100 >= total {
-			break
-		}
-		page++
-	}
-
-	return all, nil
-}
-
-func hasWelcomeComment(ctx *common.RuntimeContext, issueNumber int) bool {
-	path := fmt.Sprintf("/v1/%s/%s/issues/%d/journals", ctx.Owner, ctx.Repo, issueNumber)
-	q := url.Values{}
-	q.Set("limit", "100")
-	env, err := ctx.CallAPIWithQuery("GET", path, q)
-	if err != nil {
-		return false
-	}
-	data, _ := env.Data.(map[string]interface{})
-	journals, _ := data["journals"].([]interface{})
-	for _, j := range journals {
-		if jm, ok := j.(map[string]interface{}); ok {
-			if notes := getString(jm, "notes"); strings.Contains(notes, marker) {
-				return true
-			}
-		}
-	}
-	return false
-}
-
-func addComment(ctx *common.RuntimeContext, issueNumber int, body string) error {
-	path := fmt.Sprintf("/v1/%s/%s/issues/%d/journals", ctx.Owner, ctx.Repo, issueNumber)
-	payload := map[string]interface{}{"notes": marker + "\n\n" + body}
-	_, err := ctx.CallAPI("POST", path, payload)
-	return err
-}
-
-// renderComment renders the comment body for a specific issue.
-// It uses the --template if provided, otherwise generates an issue-aware default.
-func renderComment(ctx *common.RuntimeContext, issue issueInfo, customTmpl string) string {
-	tmpl := customTmpl
-	if tmpl == "" {
-		tmpl = defaultTemplate(ctx.Owner, ctx.Repo, issue)
-	}
-	body := strings.NewReplacer(
-		"{login}", ctx.Owner,
-		"{number}", strconv.Itoa(issue.number),
-		"{subject}", issue.subject,
-		"{description}", issue.description,
-	).Replace(tmpl)
-	return body
-}
-
-// defaultTemplate returns an issue-aware onboarding message.
-func defaultTemplate(owner, repo string, issue issueInfo) string {
-	summary := issue.subject
-	if len(issue.description) > 200 {
-		summary = issue.description[:200] + "..."
-	} else if issue.description != "" {
-		summary = issue.description
-	}
-	return fmt.Sprintf(`## 欢迎贡献！:wave:
-
-感谢你对 [%s/%s](https://www.gitlink.org.cn/%s/%s) 的关注。
-
-### :bulb: 关于本 Issue：{subject}
-
-%s
-
-### :rocket: 参与步骤
-1. **Fork 仓库** 并克隆到本地
-2. 创建新分支：` + "`git checkout -b fix/issue-{number}`" + `
-3. 参照上方 issue 描述修改代码
-4. 推送到你的 Fork 后创建 Pull Request
-
-### :memo: 注意事项
- 请先阅读 [CONTRIBUTING.md](https://www.gitlink.org.cn/%s/%s/src/master/CONTRIBUTING.md)（如有）
- 如有疑问，欢迎在评论区留言讨论
-
-期待你的 PR！`, owner, repo, owner, repo, summary, owner, repo)
-}
-
-func getString(m map[string]interface{}, key string) string {
-	if v, ok := m[key]; ok {
-		if s, ok := v.(string); ok {
-			return s
-		}
-	}
-	return ""
-}
-
-func getInt(m map[string]interface{}, key string) int {
-	switch v := m[key].(type) {
-	case float64:
-		return int(v)
-	case int:
-		return v
-	}
-	return 0
-}
--- a/shortcuts/org/org.go
+++ b/shortcuts/org/org.go
@ -103,13 +103,20 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "update",
 			Description: "Update an organization",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新组织 #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "Organization ID", Required: true},
 				{Name: "name", Short: "n", Usage: "New name"},
 				{Name: "description", Short: "d", Usage: "New description"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				id, _ := ctx.RequireArg("id", "--id my-org")
+				id, err := ctx.RequireArg("id", "--id my-org")
+				if err != nil {
+					return err
+				}
 				body := map[string]interface{}{}
 				if n := ctx.Arg("name"); n != "" {
 					body["name"] = n
@ -122,7 +129,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("/organizations/%s", id), body)
 				if err != nil {
-					return err
+					return fmt.Errorf("更新组织失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
@ -130,15 +137,22 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "delete",
 			Description: "Delete an organization",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除组织 #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "Organization ID", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				id, _ := ctx.RequireArg("id", "--id my-org")
-				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s", id), nil)
+				id, err := ctx.RequireArg("id", "--id my-org")
 				if err != nil {
 					return err
 				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s", id), nil)
+				if err != nil {
+					return fmt.Errorf("删除组织失败: %w", err)
+				}
 				return ctx.Output(env)
 			},
 		},
--- a/shortcuts/pr/pr.go
+++ b/shortcuts/pr/pr.go
@ -4,6 +4,7 @@ import (
 	"fmt"
 	"net/url"

+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/internal/output"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )
@ -16,8 +17,9 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "list",
 			Description: "List pull requests",
+			Example:     "  gitlink-cli pr +list --state open\n  gitlink-cli pr +list --state merged --page 1 --limit 50\n  gitlink-cli pr +list --columns id,title,state,user --state all",
 			Flags: []common.Flag{
-				{Name: "state", Short: "s", Usage: "Filter: open, merged, closed", Default: "open"},
+				{Name: "state", Short: "s", Usage: "Filter by state", Default: "open", Choices: []string{"open", "merged", "closed", "all"}},
 				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
@ -33,7 +35,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/pulls", q)
 				if err != nil {
-					return fmt.Errorf("获取 PR 列表失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "list", "pull requests", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -41,6 +43,8 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "create",
 			Description: "Create a pull request",
+			Long:        "Create a new pull request from --head branch to --base branch. Requires --title and --head.",
+			Example:     "  gitlink-cli pr +create --title \"Fix login crash\" --head feat/new-login\n  gitlink-cli pr +create --title \"New feature\" --head dev --base master --body \"Description...\"",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				title := ctx.Arg("title")
@ -83,7 +87,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", ctx.RepoPath()+"/pulls", payload)
 				if err != nil {
-					return fmt.Errorf("创建 PR 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "create", "pull request", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -104,7 +108,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s", ctx.RepoPath(), id), nil)
 				if err != nil {
-					return fmt.Errorf("查看 PR 失败: %w", err)
+					return clierrors.OpError(clierrors.KindNotFound, "view", "pull request", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -112,6 +116,7 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "merge",
 			Description: "Merge a pull request",
+			Example:     "  gitlink-cli pr +merge --id 42\n  gitlink-cli pr +merge --id 42 --method rebase\n  gitlink-cli pr +merge --id 42 --method squash --dry-run",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				id := ctx.Arg("id")
@ -123,7 +128,7 @@ func Shortcuts() []*common.Shortcut {
 			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "PR number", Required: true},
-				{Name: "method", Short: "m", Usage: "Merge method: merge, rebase, squash", Default: "merge"},
+				{Name: "method", Short: "m", Usage: "Merge method", Default: "merge", Choices: []string{"merge", "rebase", "squash"}},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
@ -142,7 +147,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/pulls/%s/pr_merge", ctx.RepoPath(), id), payload)
 				if err != nil {
-					return fmt.Errorf("合并 PR 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "merge", "pull request", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -168,7 +173,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/pulls/%s/refuse_merge", ctx.RepoPath(), id), nil)
 				if err != nil {
-					return fmt.Errorf("关闭 PR 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "close", "pull request", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -189,7 +194,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s/files", ctx.RepoPath(), id), nil)
 				if err != nil {
-					return fmt.Errorf("获取 PR 文件列表失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "list", "PR files", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -210,7 +215,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s/files", ctx.RepoPath(), id), nil)
 				if err != nil {
-					return fmt.Errorf("获取 PR diff 失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "view", "PR diff", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -242,7 +247,7 @@ func Shortcuts() []*common.Shortcut {

 				prEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s", ctx.RepoPath(), id), nil)
 				if err != nil {
-					return fmt.Errorf("获取 PR 信息失败: %w", err)
+					return clierrors.OpError(clierrors.KindNotFound, "view", "pull request", err).WithCommand(ctx.CommandName)
 				}
 				issueID, err := extractIssueID(prEnv)
 				if err != nil {
@ -254,7 +259,267 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("/v1/%s/%s/issues/%d/journals", ctx.Owner, ctx.Repo, issueID), payload)
 				if err != nil {
-					return fmt.Errorf("添加 PR 评论失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "comment", "pull request", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === PR 增强 ===
+		{
+			Name:        "reopen",
+			Description: "Reopen a closed pull request",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("重新打开 PR #%s", ctx.Arg("id")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("POST", fmt.Sprintf("/v1/%s/%s/pulls/%s/reopen", ctx.Owner, ctx.Repo, id), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "reopen", "pull request", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "update",
+			Description: "Update a pull request",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新 PR #%s", ctx.Arg("id")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "title", Short: "t", Usage: "New title"},
+				{Name: "body", Short: "b", Usage: "New description"},
+				{Name: "head", Usage: "Source branch"},
+				{Name: "base", Usage: "Target branch"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				// Fetch existing PR to fill required fields
+				prEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s", ctx.RepoPath(), id), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindNotFound, "view", "pull request", err).WithCommand(ctx.CommandName)
+				}
+				prData, ok := prEnv.Data.(map[string]interface{})
+				if !ok {
+					return clierrors.InputError("unexpected PR format", "API 返回格式异常").WithCommand(ctx.CommandName)
+				}
+				payload := map[string]interface{}{
+					"title":            prData["title"],
+					"body":             prData["body"],
+					"head":             prData["head"],
+					"base":             prData["base"],
+					"issue_tag_ids":   []string{},
+					"receivers_login": []string{},
+				}
+				if t := ctx.Arg("title"); t != "" {
+					payload["title"] = t
+				}
+				if b := ctx.Arg("body"); b != "" {
+					payload["body"] = b
+				}
+				if h := ctx.Arg("head"); h != "" {
+					payload["head"] = h
+				}
+				if bs := ctx.Arg("base"); bs != "" {
+					payload["base"] = bs
+				}
+				env, err := ctx.CallAPI("PUT", fmt.Sprintf("%s/pulls/%s", ctx.RepoPath(), id), payload)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "update", "pull request", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "commits",
+			Description: "List commits in a pull request",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s/commits", ctx.RepoPath(), id), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "PR commits", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "versions",
+			Description: "List versions of a pull request",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("GET", fmt.Sprintf("/v1/%s/%s/pulls/%s/versions", ctx.Owner, ctx.Repo, id), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "PR versions", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "vdiff",
+			Description: "Show diff of a specific PR version",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "version", Short: "v", Usage: "Version ID", Required: true},
+				{Name: "filepath", Usage: "Filter by file path"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				versionID, err := ctx.RequireArg("version", "--version 5")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				if fp := ctx.Arg("filepath"); fp != "" {
+					q.Set("filepath", fp)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/pulls/%s/versions/%s/diff", ctx.Owner, ctx.Repo, id, versionID), q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "view", "PR version diff", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "filesv1",
+			Description: "List changed files (v1 API with pagination)",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "filepath", Usage: "Filter by file path"},
+				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
+				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				q.Set("page", ctx.Arg("page"))
+				q.Set("limit", ctx.Arg("limit"))
+				if fp := ctx.Arg("filepath"); fp != "" {
+					q.Set("filepath", fp)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/pulls/%s/files", ctx.Owner, ctx.Repo, id), q)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "list", "PR files", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		// === PR 评论管理 ===
+		{
+			Name:        "comment-edit",
+			Description: "Edit a PR review comment",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "comment-id", Short: "c", Usage: "Comment ID", Required: true},
+				{Name: "body", Short: "b", Usage: "New comment body", Required: true},
+				{Name: "commit", Usage: "Commit SHA"},
+				{Name: "state", Usage: "Comment state", Default: "opened", Choices: []string{"opened", "resolved", "disabled"}},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				commentID, err := ctx.RequireArg("comment-id", "--comment-id 123")
+				if err != nil {
+					return err
+				}
+				body, err := ctx.RequireArg("body", `--body "updated comment"`)
+				if err != nil {
+					return err
+				}
+				payload := map[string]interface{}{
+					"note":  body,
+					"state": ctx.Arg("state"),
+				}
+				if commit := ctx.Arg("commit"); commit != "" {
+					payload["commit_id"] = commit
+				} else {
+					payload["commit_id"] = ""
+				}
+				env, err := ctx.CallAPI("PUT", fmt.Sprintf("/v1/%s/%s/pulls/%s/journals/%s", ctx.Owner, ctx.Repo, id, commentID), payload)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "edit", "PR comment", err).WithCommand(ctx.CommandName)
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "comment-delete",
+			Description: "Delete a PR review comment",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除 PR #%s 的评论 #%s", ctx.Arg("id"), ctx.Arg("comment-id")), nil
+			},
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "comment-id", Short: "c", Usage: "Comment ID", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 42")
+				if err != nil {
+					return err
+				}
+				commentID, err := ctx.RequireArg("comment-id", "--comment-id 123")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/v1/%s/%s/pulls/%s/journals/%s", ctx.Owner, ctx.Repo, id, commentID), nil)
+				if err != nil {
+					return clierrors.OpError(clierrors.KindServer, "delete", "PR comment", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -265,15 +530,15 @@ func Shortcuts() []*common.Shortcut {
 func extractIssueID(env *output.Envelope) (int64, error) {
 	data, ok := env.Data.(map[string]interface{})
 	if !ok {
-		return 0, fmt.Errorf("unexpected PR response format")
+		return 0, clierrors.InputError("unexpected PR response format", "API 返回格式异常，请稍后重试")
 	}
 	issue, ok := data["issue"].(map[string]interface{})
 	if !ok {
-		return 0, fmt.Errorf("PR response missing issue field")
+		return 0, clierrors.InputError("PR response missing issue field", "API 返回数据中缺少 issue 字段，请稍后重试")
 	}
 	idFloat, ok := issue["id"].(float64)
 	if !ok {
-		return 0, fmt.Errorf("PR response missing issue.id field")
+		return 0, clierrors.InputError("PR response missing issue.id field", "API 返回数据中缺少 issue.id 字段，请稍后重试")
 	}
 	return int64(idFloat), nil
 }
--- a/shortcuts/pr/pr_test.go
+++ b/shortcuts/pr/pr_test.go
@ -141,3 +141,186 @@ func assertEqual(t *testing.T, got interface{}, want interface{}) {
 		t.Fatalf("got %v (%T), want %v (%T)", got, got, want, want)
 	}
 }
+
+func assertPath(t *testing.T, got, want string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("path: got %s, want %s", got, want)
+	}
+}
+
+// === PR 增强测试 ===
+
+func TestReopenCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"status": float64(1)})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "reopen", map[string]string{"id": "42"})
+	if err != nil {
+		t.Fatalf("reopen failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/pulls/42/reopen.json")
+}
+
+func TestUpdateAutoFetchesExistingPR(t *testing.T) {
+	var updatePayload map[string]interface{}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == "GET" && r.URL.Path == "/owner/repo/pulls/42.json":
+			writeJSON(t, w, map[string]interface{}{
+				"title": "Old title",
+				"body":  "Old body",
+				"head":  "feature",
+				"base":  "master",
+			})
+		case r.Method == "PUT" && r.URL.Path == "/owner/repo/pulls/42.json":
+			updatePayload = decodeJSON(t, r)
+			writeJSON(t, w, map[string]interface{}{"status": float64(1)})
+		default:
+			t.Fatalf("unexpected: %s %s", r.Method, r.URL.Path)
+		}
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "update", map[string]string{
+		"id":    "42",
+		"title": "New title",
+	})
+	if err != nil {
+		t.Fatalf("update failed: %v", err)
+	}
+	assertEqual(t, updatePayload["title"], "New title")
+	assertEqual(t, updatePayload["body"], "Old body")
+	assertEqual(t, updatePayload["head"], "feature")
+	assertEqual(t, updatePayload["base"], "master")
+}
+
+func TestCommitsCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{
+			"commits_count": float64(2),
+			"commits":       []interface{}{},
+		})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "commits", map[string]string{"id": "42"})
+	if err != nil {
+		t.Fatalf("commits failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/owner/repo/pulls/42/commits.json")
+}
+
+func TestVersionsCallsV1Endpoint(t *testing.T) {
+	var requestedPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"versions": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "versions", map[string]string{"id": "42"})
+	if err != nil {
+		t.Fatalf("versions failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/pulls/42/versions.json")
+}
+
+func TestVdiffCallsVersionDiffEndpoint(t *testing.T) {
+	var requestedPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"files": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "vdiff", map[string]string{
+		"id":      "42",
+		"version": "5",
+	})
+	if err != nil {
+		t.Fatalf("vdiff failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/pulls/42/versions/5/diff.json")
+}
+
+func TestVdiffPassesFilepathFilter(t *testing.T) {
+	var fp string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fp = r.URL.Query().Get("filepath")
+		writeJSON(t, w, map[string]interface{}{"files": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "vdiff", map[string]string{
+		"id":       "42",
+		"version":  "5",
+		"filepath": "main.go",
+	})
+	if err != nil {
+		t.Fatalf("vdiff with filepath failed: %v", err)
+	}
+	assertEqual(t, fp, "main.go")
+}
+
+func TestFilesv1CallsV1FilesEndpoint(t *testing.T) {
+	var requestedPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		writeJSON(t, w, map[string]interface{}{"files": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "filesv1", map[string]string{"id": "42"})
+	if err != nil {
+		t.Fatalf("filesv1 failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/pulls/42/files.json")
+}
+
+func TestCommentEditSendsNoteSingular(t *testing.T) {
+	var payload map[string]interface{}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		payload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{"id": float64(1)})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "comment-edit", map[string]string{
+		"id":         "42",
+		"comment-id": "100",
+		"body":       "updated review",
+		"state":      "resolved",
+	})
+	if err != nil {
+		t.Fatalf("comment-edit failed: %v", err)
+	}
+	assertEqual(t, payload["note"], "updated review")
+	assertEqual(t, payload["state"], "resolved")
+}
+
+func TestCommentDeleteCallsCorrectEndpoint(t *testing.T) {
+	var requestedPath, requestedMethod string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		requestedMethod = r.Method
+		writeJSON(t, w, map[string]interface{}{"status": float64(1)})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "comment-delete", map[string]string{
+		"id":         "42",
+		"comment-id": "100",
+	})
+	if err != nil {
+		t.Fatalf("comment-delete failed: %v", err)
+	}
+	assertPath(t, requestedPath, "/v1/owner/repo/pulls/42/journals/100.json")
+	assertEqual(t, requestedMethod, "DELETE")
+}
--- a/shortcuts/pr/review.go
+++ b/shortcuts/pr/review.go
@ -10,6 +10,10 @@ func newApproveShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "approve",
 		Description: "Approve a pull request",
+		DryRun:      true,
+		DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+			return fmt.Sprintf("批准 PR #%s", ctx.Arg("id")), nil
+		},
 		Flags: []common.Flag{
 			{Name: "id", Short: "i", Usage: "PR number", Required: true},
 			{Name: "body", Short: "b", Usage: "Review comment (optional)"},
@ -18,7 +22,10 @@ func newApproveShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			id, _ := ctx.RequireArg("id", "--id 42")
+			id, err := ctx.RequireArg("id", "--id 42")
+			if err != nil {
+				return err
+			}
 			body := map[string]interface{}{
 				"state": "approved",
 			}
@ -27,7 +34,7 @@ func newApproveShortcut() *common.Shortcut {
 			}
 			env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/pulls/%s/reviews", ctx.RepoPath(), id), body)
 			if err != nil {
-				return err
+				return fmt.Errorf("批准 PR 失败: %w", err)
 			}
 			return ctx.Output(env)
 		},
@ -38,6 +45,10 @@ func newRequestChangesShortcut() *common.Shortcut {
 	return &common.Shortcut{
 		Name:        "request-changes",
 		Description: "Request changes on a pull request",
+		DryRun:      true,
+		DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+			return fmt.Sprintf("请求 PR #%s 修改", ctx.Arg("id")), nil
+		},
 		Flags: []common.Flag{
 			{Name: "id", Short: "i", Usage: "PR number", Required: true},
 			{Name: "body", Short: "b", Usage: "Review comment explaining what needs to change", Required: true},
@ -46,15 +57,21 @@ func newRequestChangesShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			id, _ := ctx.RequireArg("id", "--id 42")
-			body, _ := ctx.RequireArg("body", `--body "Looks good"`)
+			id, err := ctx.RequireArg("id", "--id 42")
+			if err != nil {
+				return err
+			}
+			body, err := ctx.RequireArg("body", `--body "Looks good"`)
+			if err != nil {
+				return err
+			}
 			payload := map[string]interface{}{
 				"state": "changes_requested",
 				"body":  body,
 			}
 			env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/pulls/%s/reviews", ctx.RepoPath(), id), payload)
 			if err != nil {
-				return err
+				return fmt.Errorf("请求修改 PR 失败: %w", err)
 			}
 			return ctx.Output(env)
 		},
@ -72,11 +89,14 @@ func newReviewsShortcut() *common.Shortcut {
 			if err := ctx.ResolveOwnerRepo(); err != nil {
 				return err
 			}
-			id, _ := ctx.RequireArg("id", "--id 42")
-			env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s/reviews", ctx.RepoPath(), id), nil)
+			id, err := ctx.RequireArg("id", "--id 42")
 			if err != nil {
 				return err
 			}
+			env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/pulls/%s/reviews", ctx.RepoPath(), id), nil)
+			if err != nil {
+				return fmt.Errorf("获取 PR 评审列表失败: %w", err)
+			}
 			return ctx.Output(env)
 		},
 	}
--- a/shortcuts/register.go
+++ b/shortcuts/register.go
@ -3,14 +3,13 @@ package shortcuts
 import (
 	"github.com/spf13/cobra"

+	"github.com/gitlink-org/gitlink-cli/shortcuts/board"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/branch"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/ci"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
-	"github.com/gitlink-org/gitlink-cli/shortcuts/compliance"
-	"github.com/gitlink-org/gitlink-cli/shortcuts/contrib"
-	"github.com/gitlink-org/gitlink-cli/shortcuts/onboard"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/file"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/issue"
-	// "github.com/gitlink-org/gitlink-cli/shortcuts/milestone" // broken: syntax errors
+	"github.com/gitlink-org/gitlink-cli/shortcuts/milestone"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/org"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/pr"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/release"
@ -22,50 +21,117 @@ import (
 	"github.com/gitlink-org/gitlink-cli/shortcuts/wiki"
 )

+type groupInfo struct {
+	Short   string
+	Long    string
+	Example string
+}
+
 // RegisterAll mounts all shortcut groups onto the root command.
 func RegisterAll(root *cobra.Command) {
 	groups := map[string][]*common.Shortcut{
-		"repo":      repo.Shortcuts(),
-		"issue":     issue.Shortcuts(),
-		"pr":        pr.Shortcuts(),
-		"release":   release.Shortcuts(),
-		"branch":    branch.Shortcuts(),
-		"org":       org.Shortcuts(),
-		"user":      user.Shortcuts(),
-		"search":    search.Shortcuts(),
-		"ci":        ci.Shortcuts(),
-		// "milestone": milestone.Shortcuts(), // broken
-		"team":      team.Shortcuts(),
-		"wiki":      wiki.Shortcuts(),
-		"webhook":   webhook.Shortcuts(),
-		"contrib":   contrib.Shortcuts(),
-		"compliance": compliance.Shortcuts(),
-		"onboard":   onboard.Shortcuts(),
+		"board":      board.Shortcuts(),
+		"repo":       repo.Shortcuts(),
+		"issue":      issue.Shortcuts(),
+		"milestone":  milestone.Shortcuts(),
+		"pr":         pr.Shortcuts(),
+		"release":    release.Shortcuts(),
+		"branch":     branch.Shortcuts(),
+		"org":        org.Shortcuts(),
+		"user":       user.Shortcuts(),
+		"search":     search.Shortcuts(),
+		"ci":         ci.Shortcuts(),
+		"file":       file.Shortcuts(),
+		"team":       team.Shortcuts(),
+		"wiki":       wiki.Shortcuts(),
+		"webhook":    webhook.Shortcuts(),
 	}

-	descriptions := map[string]string{
-		"repo":      "Repository operations",
-		"issue":     "Issue operations",
-		"pr":        "Pull request operations",
-		"release":   "Release operations",
-		"branch":    "Branch operations",
-		"org":       "Organization operations",
-		"user":      "User operations",
-		"search":    "Search operations",
-		"ci":        "CI/CD operations",
-		// "milestone": "Milestone operations", // broken
-		"team":      "Team operations",
-		"wiki":      "Wiki operations",
-		"webhook":   "Webhook operations",
-		"contrib":    "Contribution report operations",
-		"compliance": "Compliance and security scan operations",
-		"onboard":    "New contributor onboarding operations",
+	infos := map[string]groupInfo{
+		"board": {
+			Short:   "Board (kanban) operations",
+			Long:    "View and manage kanban boards: view board layout, list columns, filter issues, move tasks between columns, assign people, and analyze workload.",
+			Example: "  gitlink-cli board +view\n  gitlink-cli board +columns\n  gitlink-cli board +issues --column \"In Progress\" --assignee zhangsan\n  gitlink-cli board +move --number 42 --status in-progress\n  gitlink-cli board +assign --number 42 --assignee lisi\n  gitlink-cli board +stats",
+		},
+		"repo": {
+			Short:   "Repository operations",
+			Long:    "Manage GitLink repositories: create, list, fork, delete, update settings, and manage members.",
+			Example: "  gitlink-cli repo +list --user myorg\n  gitlink-cli repo +create --name new-project\n  gitlink-cli repo +info --owner org --repo name",
+		},
+		"issue": {
+			Short:   "Issue operations",
+			Long:    "Manage issues: list, create, view, update, close, reopen, comment, labels, batch operations, metadata queries, and comment management.",
+			Example: "  gitlink-cli issue +list --state open\n  gitlink-cli issue +create --title \"Bug found\" --body \"Details...\"\n  gitlink-cli issue +close --number 42\n  gitlink-cli issue +statuses\n  gitlink-cli issue +comment-edit --number 42 --comment-id 1 --body \"updated\"",
+		},
+		"milestone": {
+			Short:   "Milestone operations",
+			Long:    "Manage milestones: list, create, view, update, delete, and change status.",
+			Example: "  gitlink-cli milestone +list\n  gitlink-cli milestone +create --name v1.0 --description \"First release\" --date 2026-12-31\n  gitlink-cli milestone +view --id 1\n  gitlink-cli milestone +status --id 1 --status closed",
+		},
+		"pr": {
+			Short:   "Pull request operations",
+			Long:    "Manage pull requests: list, create, view, merge, close, review, and view changed files.",
+			Example: "  gitlink-cli pr +list --state open\n  gitlink-cli pr +create --title \"Fix login\" --head feat-branch\n  gitlink-cli pr +merge --id 42",
+		},
+		"release": {
+			Short:   "Release operations",
+			Long:    "Manage releases: list, create, view, and delete releases with release notes.",
+			Example: "  gitlink-cli release +list\n  gitlink-cli release +create --tag v1.0.0 --name \"First release\"",
+		},
+		"branch": {
+			Short:   "Branch operations",
+			Long:    "Manage branches: list, create, delete, and protect branches.",
+			Example: "  gitlink-cli branch +list\n  gitlink-cli branch +create --name feature-x\n  gitlink-cli branch +protect --name master",
+		},
+		"org": {
+			Short:   "Organization operations",
+			Long:    "Manage organizations: list, view info, manage members, create and update.",
+			Example: "  gitlink-cli org +list\n  gitlink-cli org +info --org myorg\n  gitlink-cli org +members --org myorg",
+		},
+		"user": {
+			Short:   "User operations",
+			Long:    "View current user info, profile details, and owned repositories.",
+			Example: "  gitlink-cli user +me\n  gitlink-cli user +info --login username",
+		},
+		"search": {
+			Short:   "Search operations",
+			Long:    "Search across repositories, users, and issues on GitLink.",
+			Example: "  gitlink-cli search +repos --q \"machine learning\"\n  gitlink-cli search +users --q \"developer\"",
+		},
+		"ci": {
+			Short:   "CI/CD operations",
+			Long:    "Manage CI/CD pipelines: view build history, read logs, restart and stop builds.",
+			Example: "  gitlink-cli ci +builds\n  gitlink-cli ci +logs --id 123\n  gitlink-cli ci +restart --id 123",
+		},
+		"file": {
+			Short:   "File and code operations",
+			Long:    "Browse directories, read files, create/update/delete files, view commit history and diffs.",
+			Example: "  gitlink-cli file +ls\n  gitlink-cli file +read --path README.md\n  gitlink-cli file +create --path new.txt --content hello --branch master --message \"add file\"\n  gitlink-cli file +commits",
+		},
+		"team": {
+			Short:   "Team operations",
+			Long:    "Manage teams within organizations: list, create, delete, and manage members.",
+			Example: "  gitlink-cli team +list --org myorg\n  gitlink-cli team +create --org myorg --name dev-team",
+		},
+		"wiki": {
+			Short:   "Wiki operations",
+			Long:    "Manage wiki pages: list, create, view, update, delete, lint, fix formatting, and sync.",
+			Example: "  gitlink-cli wiki +list\n  gitlink-cli wiki +create --title \"Getting Started\" --content \"# Welcome\"",
+		},
+		"webhook": {
+			Short:   "Webhook operations",
+			Long:    "Manage webhooks: list, create, view, update, delete, test, and inspect events.",
+			Example: "  gitlink-cli webhook +list\n  gitlink-cli webhook +create --url https://example.com/hook --events push",
+		},
 	}

 	for name, shortcuts := range groups {
+		info := infos[name]
 		groupCmd := &cobra.Command{
-			Use:   name,
-			Short: descriptions[name],
+			Use:     name,
+			Short:   info.Short,
+			Long:    info.Long,
+			Example: info.Example,
 		}
 		common.MountShortcuts(groupCmd, shortcuts)
 		root.AddCommand(groupCmd)
--- a/shortcuts/release/release.go
+++ b/shortcuts/release/release.go
@ -143,11 +143,18 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "body", Short: "b", Usage: "New release notes"},
 				{Name: "prerelease", Usage: "Mark as prerelease (true/false)"},
 			},
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("更新 Release #%s", ctx.Arg("id")), nil
+			},
 			Run: func(ctx *common.RuntimeContext) error {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
-				id, _ := ctx.RequireArg("id", "--id my-org")
+				id, err := ctx.RequireArg("id", "--id 1")
+				if err != nil {
+					return err
+				}
 				body := map[string]interface{}{}
 				if n := ctx.Arg("name"); n != "" {
 					body["name"] = n
@ -163,7 +170,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/releases/%s", ctx.RepoPath(), id), body)
 				if err != nil {
-					return err
+					return fmt.Errorf("更新 Release 失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
--- a/shortcuts/repo/batch_delete.go
+++ b/shortcuts/repo/batch_delete.go
@ -0,0 +1,94 @@
+package repo
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+// newBatchDeleteShortcut 实现 repo +batch-delete 命令。
+//
+// 设计参考 issue +batch-close 与 repo +batch-update：
+//   - --names : 内联逗号分隔的仓库名列表
+//   - --from  : CSV 文件路径（只读 name 列，复用 readNamesFromCSV）
+//   - --dry-run : 仅预览不实际删除
+//
+// 与单条 repo +delete 的区别：批量操作下没有"当前仓库"语义，
+// 因此只要求 --owner（不需要 --repo），所有要删除的仓库都位于该 owner 名下。
+func newBatchDeleteShortcut() *common.Shortcut {
+	return &common.Shortcut{
+		Name:        "batch-delete",
+		Description: "Delete multiple repositories by names or a CSV file",
+		Flags: []common.Flag{
+			{Name: "names", Short: "n", Usage: "Comma-separated repository names, e.g. repo-a,repo-b"},
+			{Name: "from", Usage: "CSV file path"},
+			{Name: "dry-run", Usage: "Preview without deleting", Bool: true, Default: "false"},
+		},
+		Run: runBatchDelete,
+	}
+}
+
+func runBatchDelete(ctx *common.RuntimeContext) error {
+	owner := ctx.Owner
+	if owner == "" {
+		return fmt.Errorf("--owner is required; pass --owner <login> to specify the account that owns the repos")
+	}
+
+	var repoNames []string
+	if namesStr := ctx.Arg("names"); namesStr != "" {
+		for _, name := range strings.Split(namesStr, ",") {
+			name = strings.TrimSpace(name)
+			if name != "" {
+				repoNames = append(repoNames, name)
+			}
+		}
+	}
+	if csvPath := ctx.Arg("from"); csvPath != "" {
+		csvNames, err := readNamesFromCSV(csvPath)
+		if err != nil {
+			return err
+		}
+		repoNames = append(repoNames, csvNames...)
+	}
+	if len(repoNames) == 0 {
+		return fmt.Errorf("no repository names provided; use -n repo-a,repo-b or --from repos.csv")
+	}
+
+	dryRun := ctx.Arg("dry-run") == "true"
+	summary := repoBatchSummary{
+		Owner:   owner,
+		Action:  "delete",
+		DryRun:  dryRun,
+		Total:   len(repoNames),
+		Results: make([]repoBatchResult, 0, len(repoNames)),
+	}
+
+	for _, name := range repoNames {
+		result := repoBatchResult{Name: name}
+		if dryRun {
+			result.Status = "planned"
+			summary.Succeeded++
+			summary.Results = append(summary.Results, result)
+			continue
+		}
+
+		if _, err := ctx.CallAPI("DELETE", fmt.Sprintf("/%s/%s", owner, name), nil); err != nil {
+			result.Status = "failed"
+			result.Error = err.Error()
+			summary.Failed++
+		} else {
+			result.Status = "deleted"
+			summary.Succeeded++
+		}
+		summary.Results = append(summary.Results, result)
+	}
+
+	if err := ctx.OutputData(summary); err != nil {
+		return err
+	}
+	if summary.Failed > 0 {
+		return fmt.Errorf("%d of %d repo(s) failed to delete", summary.Failed, summary.Total)
+	}
+	return nil
+}
--- a/shortcuts/repo/batch_delete_test.go
+++ b/shortcuts/repo/batch_delete_test.go
@ -0,0 +1,220 @@
+package repo
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+func runBatchDeleteShortcut(t *testing.T, server *httptest.Server, owner string, args map[string]string) error {
+	t.Helper()
+	s := findShortcut(t, "batch-delete")
+	ctx := &common.RuntimeContext{
+		Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
+		Owner:  owner,
+		Format: "json",
+		Args:   args,
+	}
+	return s.Run(ctx)
+}
+
+func TestBatchDelete_DryRun(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("no API calls expected in dry-run mode, got %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "testuser", map[string]string{
+		"names":   "repo1,repo2",
+		"dry-run": "true",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestBatchDelete_FromNames(t *testing.T) {
+	var deletedPaths []string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "DELETE" {
+			t.Fatalf("expected DELETE, got %s", r.Method)
+		}
+		deletedPaths = append(deletedPaths, r.URL.Path)
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{
+		"names": "test-batch-1,test-batch-2,test-batch-3",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(deletedPaths) != 3 {
+		t.Fatalf("expected 3 DELETE calls, got %d", len(deletedPaths))
+	}
+	expected := []string{"/zzx-coder/test-batch-1.json", "/zzx-coder/test-batch-2.json", "/zzx-coder/test-batch-3.json"}
+	for i, p := range deletedPaths {
+		if p != expected[i] {
+			t.Fatalf("path[%d]: got %q, want %q", i, p, expected[i])
+		}
+	}
+}
+
+func TestBatchDelete_NoNames(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "no repository names provided") {
+		t.Fatalf("error should mention no names, got: %v", err)
+	}
+}
+
+func TestBatchDelete_NoOwner(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "", map[string]string{
+		"names": "repo1,repo2",
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "--owner is required") {
+		t.Fatalf("error should mention --owner required, got: %v", err)
+	}
+}
+
+func TestBatchDelete_DryRunNoNamesErrors(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{"dry-run": "true"})
+	if err == nil {
+		t.Fatal("expected error for no names even in dry-run, got nil")
+	}
+}
+
+func TestBatchDelete_FromCSV(t *testing.T) {
+	csvPath := writeTempCSV(t, "name\ncsv-repo1\ncsv-repo2\n")
+
+	var deletedPaths []string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "DELETE" {
+			t.Fatalf("expected DELETE, got %s", r.Method)
+		}
+		deletedPaths = append(deletedPaths, r.URL.Path)
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{"from": csvPath})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(deletedPaths) != 2 {
+		t.Fatalf("expected 2 DELETE calls, got %d", len(deletedPaths))
+	}
+	if deletedPaths[0] != "/zzx-coder/csv-repo1.json" {
+		t.Fatalf("first path: got %q", deletedPaths[0])
+	}
+	if deletedPaths[1] != "/zzx-coder/csv-repo2.json" {
+		t.Fatalf("second path: got %q", deletedPaths[1])
+	}
+}
+
+func TestBatchDelete_CSVAndNamesCombined(t *testing.T) {
+	csvPath := writeTempCSV(t, "name\ncsv-repo\n")
+
+	var deletedPaths []string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		deletedPaths = append(deletedPaths, r.URL.Path)
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{
+		"names": "inline-repo",
+		"from":  csvPath,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(deletedPaths) != 2 {
+		t.Fatalf("expected 2 deletes (inline + csv), got %d", len(deletedPaths))
+	}
+	if deletedPaths[0] != "/zzx-coder/inline-repo.json" {
+		t.Fatalf("first: got %q", deletedPaths[0])
+	}
+	if deletedPaths[1] != "/zzx-coder/csv-repo.json" {
+		t.Fatalf("second: got %q", deletedPaths[1])
+	}
+}
+
+func TestBatchDelete_PartialFailure(t *testing.T) {
+	callCount := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		callCount++
+		if callCount == 2 {
+			w.WriteHeader(http.StatusNotFound)
+			w.Write([]byte(`{"message":"repo not found"}`))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{
+		"names": "ok1,fail1,ok2",
+	})
+	if err == nil {
+		t.Fatal("expected error from partial failure, got nil")
+	}
+	if !strings.Contains(err.Error(), "failed to delete") {
+		t.Fatalf("error should mention failed count, got: %v", err)
+	}
+}
+
+func TestBatchDelete_TrimsWhitespace(t *testing.T) {
+	var deletedPaths []string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		deletedPaths = append(deletedPaths, r.URL.Path)
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer server.Close()
+
+	err := runBatchDeleteShortcut(t, server, "zzx-coder", map[string]string{
+		"names": "  repo-a ,  repo-b  ,",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(deletedPaths) != 2 {
+		t.Fatalf("expected 2 deletes after trimming, got %d", len(deletedPaths))
+	}
+	if deletedPaths[0] != "/zzx-coder/repo-a.json" {
+		t.Fatalf("first: got %q", deletedPaths[0])
+	}
+	if deletedPaths[1] != "/zzx-coder/repo-b.json" {
+		t.Fatalf("second: got %q", deletedPaths[1])
+	}
+}
--- a/shortcuts/repo/repo.go
+++ b/shortcuts/repo/repo.go
@ -5,6 +5,7 @@ import (
 	"net/url"
 	"strconv"

+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )

@ -12,12 +13,14 @@ func Shortcuts() []*common.Shortcut {
 		shortcuts := []*common.Shortcut{
 			newBatchCreateShortcut(),
 			newBatchUpdateShortcut(),
+			newBatchDeleteShortcut(),
 		{
 			Name:        "list",
 			Description: "List repositories for a user or organization",
+			Example:     "  gitlink-cli repo +list\n  gitlink-cli repo +list --user myorg\n  gitlink-cli repo +list --category mirror --page 1 --limit 50",
 			Flags: []common.Flag{
 				{Name: "user", Short: "u", Usage: "User login (default: current user)"},
-				{Name: "category", Short: "c", Usage: "Filter: manage/mirror/sync/fork/all (default: manage)", Default: "manage"},
+				{Name: "category", Short: "c", Usage: "Filter by category", Default: "manage", Choices: []string{"manage", "mirror", "sync", "fork", "all"}},
 				{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
@ -36,7 +39,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPIWithQuery("GET", path, q)
 				if err != nil {
-					return fmt.Errorf("获取仓库列表失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "list", "repositories", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -50,7 +53,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("GET", ctx.RepoPath(), nil)
 				if err != nil {
-					return fmt.Errorf("查看仓库失败: %w", err)
+					return clierrors.OpError(clierrors.KindNotFound, "view", "repository", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -58,6 +61,8 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "create",
 			Description: "Create a new repository",
+			Long:        "Create a new GitLink repository. Requires --name. Supports --description and --private flags.",
+			Example:     "  gitlink-cli repo +create --name my-project\n  gitlink-cli repo +create --name my-project --description \"A new project\" --private true\n  gitlink-cli repo +create --name my-project --dry-run",
 			DryRun:      true,
 			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
 				name := ctx.Arg("name")
@ -76,12 +81,12 @@ func Shortcuts() []*common.Shortcut {
 				// Get current user login for the create path
 				userEnv, err := ctx.CallAPI("GET", "/users/me", nil)
 				if err != nil {
-					return fmt.Errorf("获取当前用户信息失败: %w", err)
+					return clierrors.OpError(clierrors.KindAuth, "view", "user profile", err).WithCommand(ctx.CommandName)
 				}
 				userData, _ := userEnv.Data.(map[string]interface{})
 				login, _ := userData["login"].(string)
 				if login == "" {
-					return fmt.Errorf("cannot determine current user login")
+					return clierrors.InputError("cannot determine current user login", "请先运行 gitlink-cli auth login 登录").WithCommand(ctx.CommandName)
 				}
 				userID, _ := userData["user_id"].(float64)
 				body := map[string]interface{}{
@ -97,7 +102,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("/%s/%s", login, name), body)
 				if err != nil {
-					return fmt.Errorf("创建仓库失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "create", "repository", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -118,7 +123,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", ctx.RepoPath()+"/forks", nil)
 				if err != nil {
-					return fmt.Errorf("Fork 仓库失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "fork", "repository", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -139,7 +144,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("DELETE", ctx.RepoPath(), nil)
 				if err != nil {
-					return fmt.Errorf("删除仓库失败: %w", err)
+					return clierrors.OpError(clierrors.KindServer, "delete", "repository", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -163,11 +168,14 @@ func Shortcuts() []*common.Shortcut {
 					body["private"] = p == "true"
 				}
 				if len(body) == 0 {
-					return fmt.Errorf("at least one of --description, --private is required")
+					return clierrors.InputError(
+						"at least one of --description, --private is required",
+						"至少需要提供 --description 或 --private 中的一个参数",
+					).WithCommand(ctx.CommandName)
 				}
 				env, err := ctx.CallAPI("PATCH", ctx.RepoPath(), body)
 				if err != nil {
-					return err
+					return clierrors.OpError(clierrors.KindServer, "update", "repository", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -188,7 +196,7 @@ func Shortcuts() []*common.Shortcut {
 				q.Set("limit", ctx.Arg("limit"))
 				env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/collaborators", q)
 				if err != nil {
-					return fmt.Errorf("failed to list members for %s/%s: %w", ctx.Owner, ctx.Repo, err)
+					return clierrors.OpError(clierrors.KindServer, "list", "members", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -217,12 +225,15 @@ func Shortcuts() []*common.Shortcut {
 				}
 				uid, err := strconv.Atoi(userID)
 				if err != nil {
-					return fmt.Errorf("invalid user-id: %s (must be an integer)", userID)
+					return clierrors.InputError(
+				fmt.Sprintf("invalid user-id: %s (must be an integer)", userID),
+				"user-id 必须是整数，请检查参数值",
+			).WithCommand(ctx.CommandName)
 				}
 				body := map[string]interface{}{"user_id": uid}
 				env, err := ctx.CallAPI("POST", ctx.RepoPath()+"/collaborators", body)
 				if err != nil {
-					return fmt.Errorf("failed to invite user %d to %s/%s: %w", uid, ctx.Owner, ctx.Repo, err)
+					return clierrors.OpError(clierrors.KindServer, "invite", "member", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
@ -251,12 +262,15 @@ func Shortcuts() []*common.Shortcut {
 				}
 				uid, err := strconv.Atoi(userID)
 				if err != nil {
-					return fmt.Errorf("invalid user-id: %s (must be an integer)", userID)
+					return clierrors.InputError(
+				fmt.Sprintf("invalid user-id: %s (must be an integer)", userID),
+				"user-id 必须是整数，请检查参数值",
+			).WithCommand(ctx.CommandName)
 				}
 				body := map[string]interface{}{"user_id": uid}
 				env, err := ctx.CallAPI("DELETE", ctx.RepoPath()+"/collaborators/remove", body)
 				if err != nil {
-					return fmt.Errorf("failed to remove user %d from %s/%s: %w", uid, ctx.Owner, ctx.Repo, err)
+					return clierrors.OpError(clierrors.KindServer, "remove", "member", err).WithCommand(ctx.CommandName)
 				}
 				return ctx.Output(env)
 			},
--- a/shortcuts/search/search.go
+++ b/shortcuts/search/search.go
@ -69,14 +69,17 @@ func Shortcuts() []*common.Shortcut {
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
-				keyword, _ := ctx.RequireArg("keyword", "--keyword myproject")
+				keyword, err := ctx.RequireArg("keyword", "--keyword myproject")
+				if err != nil {
+					return err
+				}
 				q := url.Values{}
 				q.Set("search", keyword)
 				q.Set("page", ctx.Arg("page"))
 				q.Set("limit", ctx.Arg("limit"))
 				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1%s/issues", ctx.RepoPath()), q)
 				if err != nil {
-					return err
+					return fmt.Errorf("搜索 Issue 失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
--- a/shortcuts/team/team.go
+++ b/shortcuts/team/team.go
@ -18,13 +18,16 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
+				org, err := ctx.RequireArg("org", "--org my-org")
+				if err != nil {
+					return err
+				}
 				q := url.Values{}
 				q.Set("page", ctx.Arg("page"))
 				q.Set("limit", ctx.Arg("limit"))
 				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/organizations/%s/teams", org), q)
 				if err != nil {
-					return err
+					return fmt.Errorf("获取团队列表失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
@ -32,14 +35,24 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "create",
 			Description: "Create a team in an organization",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("创建团队: %s", ctx.Arg("name")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "org", Short: "o", Usage: "Organization ID or login", Required: true},
 				{Name: "name", Short: "n", Usage: "Team name", Required: true},
 				{Name: "description", Short: "d", Usage: "Team description"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
-				name, _ := ctx.RequireArg("name", `--name "My Team"`)
+				org, err := ctx.RequireArg("org", "--org my-org")
+				if err != nil {
+					return err
+				}
+				name, err := ctx.RequireArg("name", `--name "My Team"`)
+				if err != nil {
+					return err
+				}
 				body := map[string]interface{}{
 					"name": name,
 				}
@ -48,7 +61,7 @@ func Shortcuts() []*common.Shortcut {
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("/organizations/%s/teams", org), body)
 				if err != nil {
-					return err
+					return fmt.Errorf("创建团队失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
@ -56,17 +69,27 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "delete",
 			Description: "Delete a team",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除团队 #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "org", Short: "o", Usage: "Organization ID or login", Required: true},
 				{Name: "id", Short: "i", Usage: "Team ID", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
-				id, _ := ctx.RequireArg("id", "--id 1")
-				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s/teams/%s", org, id), nil)
+				org, err := ctx.RequireArg("org", "--org my-org")
 				if err != nil {
 					return err
 				}
+				id, err := ctx.RequireArg("id", "--id 1")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s/teams/%s", org, id), nil)
+				if err != nil {
+					return fmt.Errorf("删除团队失败: %w", err)
+				}
 				return ctx.Output(env)
 			},
 		},
@ -80,14 +103,20 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
-				id, _ := ctx.RequireArg("id", "--id 1")
+				org, err := ctx.RequireArg("org", "--org my-org")
+				if err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id", "--id 1")
+				if err != nil {
+					return err
+				}
 				q := url.Values{}
 				q.Set("page", ctx.Arg("page"))
 				q.Set("limit", ctx.Arg("limit"))
 				env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/organizations/%s/teams/%s/members", org, id), q)
 				if err != nil {
-					return err
+					return fmt.Errorf("获取团队成员列表失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
@ -95,21 +124,34 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "member-add",
 			Description: "Add a user to a team",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("添加用户 %s 到团队 %s", ctx.Arg("user"), ctx.Arg("team")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "org", Short: "o", Usage: "Organization ID or login", Required: true},
 				{Name: "team", Short: "t", Usage: "Team ID", Required: true},
 				{Name: "user", Short: "u", Usage: "User login or ID to add", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
-				team, _ := ctx.RequireArg("team", "--team dev-team")
-				user, _ := ctx.RequireArg("user", "--user alice")
+				org, err := ctx.RequireArg("org", "--org my-org")
+				if err != nil {
+					return err
+				}
+				team, err := ctx.RequireArg("team", "--team dev-team")
+				if err != nil {
+					return err
+				}
+				user, err := ctx.RequireArg("user", "--user alice")
+				if err != nil {
+					return err
+				}
 				body := map[string]interface{}{
 					"user_id": user,
 				}
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("/organizations/%s/teams/%s/members", org, team), body)
 				if err != nil {
-					return err
+					return fmt.Errorf("添加团队成员失败: %w", err)
 				}
 				return ctx.Output(env)
 			},
@ -117,19 +159,32 @@ func Shortcuts() []*common.Shortcut {
 		{
 			Name:        "member-remove",
 			Description: "Remove a user from a team",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("从团队 %s 移除用户 %s", ctx.Arg("user"), ctx.Arg("team")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "org", Short: "o", Usage: "Organization ID or login", Required: true},
 				{Name: "team", Short: "t", Usage: "Team ID", Required: true},
 				{Name: "user", Short: "u", Usage: "User login or ID to remove", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
-				org, _ := ctx.RequireArg("org", "--org my-org")
-				team, _ := ctx.RequireArg("team", "--team dev-team")
-				user, _ := ctx.RequireArg("user", "--user alice")
-				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s/teams/%s/members/%s", org, team, user), nil)
+				org, err := ctx.RequireArg("org", "--org my-org")
 				if err != nil {
 					return err
 				}
+				team, err := ctx.RequireArg("team", "--team dev-team")
+				if err != nil {
+					return err
+				}
+				user, err := ctx.RequireArg("user", "--user alice")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("DELETE", fmt.Sprintf("/organizations/%s/teams/%s/members/%s", org, team, user), nil)
+				if err != nil {
+					return fmt.Errorf("移除团队成员失败: %w", err)
+				}
 				return ctx.Output(env)
 			},
 		},
--- a/shortcuts/user/user.go
+++ b/shortcuts/user/user.go
@ -30,8 +30,7 @@ func Shortcuts() []*common.Shortcut {
 				if err != nil {
 					return err
 				}
-				// Use relative path to avoid URL construction issues
-				env, err := ctx.CallAPI("GET", fmt.Sprintf("users/%s", login), nil)
+				env, err := ctx.CallAPI("GET", fmt.Sprintf("/users/%s", login), nil)
 				if err != nil {
 					return fmt.Errorf("查看用户信息失败: %w", err)
 				}
--- a/shortcuts/webhook/webhook.go
+++ b/shortcuts/webhook/webhook.go
@ -5,11 +5,23 @@ import (
 	"net/url"
 	"strings"

+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/internal/output"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )

-// 支持的Webhook事件类型
+// supportedEvents 定义了 GitLink 支持的所有 Webhook 事件类型
+// push: 代码推送事件
+// pull_request: PR 事件
+// issue: Issue 事件
+// issue_assign: Issue 分配事件
+// issue_comment: Issue 评论事件
+// pull_request_assign: PR 分配事件
+// pull_request_comment: PR 评论事件
+// merge_request: 合并请求事件
+// repository: 仓库事件
+// branch: 分支创建/删除事件
+// tag: 标签创建/删除事件
 var supportedEvents = []string{
 	"push",
 	"pull_request",
@ -24,6 +36,9 @@ var supportedEvents = []string{
 	"tag",
 }

+// isEventSupported 检查某个事件类型是否被支持
+// 参数: event - 要检查的事件类型
+// 返回: true 表示支持，false 表示不支持
 func isEventSupported(event string) bool {
 	for _, supported := range supportedEvents {
 		if event == supported {
@ -33,29 +48,37 @@ func isEventSupported(event string) bool {
 	return false
 }

+// parseEvents 把用户输入的逗号分隔的事件字符串解析成事件数组
+// 参数: eventsStr - 用户输入的事件字符串，如 "push,pull_request"
+// 返回: 过滤后的有效事件数组，如果输入为空则返回默认值 ["push"]
 func parseEvents(eventsStr string) []string {
 	if eventsStr == "" {
 		return []string{"push"} // 默认事件
 	}
-	events := strings.Split(eventsStr, ",")
+	events := strings.Split(eventsStr, ",") // 按逗号分割
 	var validEvents []string
 	for _, event := range events {
-		event = strings.TrimSpace(event)
+		event = strings.TrimSpace(event) // 去掉前后空格
 		if isEventSupported(event) {
-			validEvents = append(validEvents, event)
+			validEvents = append(validEvents, event) // 有效事件才加入结果
 		}
 	}
 	return validEvents
 }

-// webhookRepoPath returns the webhook API path prefix: /v1/{owner}/{repo}
-// Note: BaseURL already includes /api prefix
+// webhookRepoPath 构建 Webhook API 的基础路径
+// 参数: ctx - 运行时上下文，包含 Owner（仓库所有者）和 Repo（仓库名）
+// 返回: 类似 /v1/owner/repo 的字符串
+// 注意: BaseURL 已经包含 /api 前缀，所以这里不需要再加
 func webhookRepoPath(ctx *common.RuntimeContext) string {
 	return fmt.Sprintf("/v1/%s/%s", ctx.Owner, ctx.Repo)
 }

+// Shortcuts 返回所有 Webhook 相关的 CLI 命令列表
+// 包含7个命令：list、create、update、delete、test、info、events
 func Shortcuts() []*common.Shortcut {
 	return []*common.Shortcut{
+		// list 命令：列出仓库的所有 Webhook
 		{
 			Name:        "list",
 			Description: "List all webhooks for a repository",
@ -64,22 +87,31 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息（从命令行参数或 Git 远程仓库）
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}
+				// 步骤2：创建 URL 查询参数
 				q := url.Values{}
 				q.Set("page", ctx.Arg("page"))
 				q.Set("limit", ctx.Arg("limit"))
+				// 步骤3：调用 API 获取 Webhook 列表
 				env, err := ctx.CallAPIWithQuery("GET", webhookRepoPath(ctx)+"/webhooks", q)
 				if err != nil {
 					return fmt.Errorf("获取 Webhook 列表失败: %w", err)
 				}
+				// 步骤4：输出结果给用户
 				return ctx.Output(env)
 			},
 		},
+		// create 命令：创建新的 Webhook
 		{
 			Name:        "create",
 			Description: "Create a new webhook",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("创建 Webhook: %s", ctx.Arg("url")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "url", Short: "u", Usage: "Webhook callback URL", Required: true},
 				{Name: "events", Short: "e", Usage: "Trigger events (comma-separated), e.g., push,pull_request,issue", Default: "push"},
@ -88,20 +120,27 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "description", Short: "d", Usage: "Webhook description"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}

+				// 步骤2：获取必需参数 --url（用 RequireArg，如果没提供会报错）
 				webhookURL, err := ctx.RequireArg("url", "--url https://example.com/hook")
 				if err != nil {
 					return err
 				}

+				// 步骤3：解析事件类型（逗号分隔，自动过滤无效事件）
 				events := parseEvents(ctx.Arg("events"))
 				if len(events) == 0 {
-					return fmt.Errorf("no valid events specified. Supported events: %s", strings.Join(supportedEvents, ", "))
+					return clierrors.InputError(
+						"no valid events specified",
+						fmt.Sprintf("支持的事件类型: %s", strings.Join(supportedEvents, ", ")),
+					)
 				}

+				// 步骤4：构建请求体（payload），包含必填字段
 				payload := map[string]interface{}{
 					"url":          webhookURL,
 					"http_method":  "POST",
@ -109,27 +148,33 @@ func Shortcuts() []*common.Shortcut {
 					"content_type": "json",
 				}

+				// 添加事件列表
 				if len(events) > 0 {
 					payload["events"] = events
 				} else {
 					payload["events"] = []string{"push"}
 				}

+				// 添加可选参数：secret（签名密钥）
 				if secret := ctx.Arg("secret"); secret != "" {
 					payload["secret"] = secret
 				}

+				// 添加可选参数：description（描述）
 				if description := ctx.Arg("description"); description != "" {
 					payload["description"] = description
 				}

+				// 步骤5：发送 POST 请求创建 Webhook
 				env, err := ctx.CallAPI("POST", webhookRepoPath(ctx)+"/webhooks", payload)
 				if err != nil {
 					return fmt.Errorf("创建 Webhook 失败: %w", err)
 				}
+				// 步骤6：输出结果
 				return ctx.Output(env)
 			},
 		},
+		// update 命令：更新现有的 Webhook
 		{
 			Name:        "update",
 			Description: "Update an existing webhook",
@ -143,28 +188,33 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "description", Short: "d", Usage: "Webhook description"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}

+				// 步骤2：获取必需参数 --id
 				webhookID, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}

+				// 步骤3：初始化请求体
 				payload := map[string]interface{}{
 					"http_method":  "POST",
 					"active":       true,
 					"content_type": "json",
 				}

-				// 如果用户没有提供URL，获取当前webhook的URL
+				// 步骤4：智能获取 URL
+				// 如果用户没提供 URL，自动调用 GET API 获取当前 URL（避免用户重复输入）
 				webhookURL := ctx.Arg("url")
 				if webhookURL == "" {
 					getEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
 					if err != nil {
 						return fmt.Errorf("获取 Webhook 当前信息失败: %w", err)
 					}
+					// 类型断言：把 Data 转换为 map[string]interface{}
 					webhookData, ok := getEnv.Data.(map[string]interface{})
 					if !ok {
 						return fmt.Errorf("failed to parse webhook data")
@ -177,28 +227,28 @@ func Shortcuts() []*common.Shortcut {
 				}
 				payload["url"] = webhookURL

+				// 步骤5：添加可选参数
 				if events := ctx.Arg("events"); events != "" {
 					validEvents := parseEvents(events)
 					if len(validEvents) == 0 {
-						return fmt.Errorf("no valid events specified. Supported events: %s", strings.Join(supportedEvents, ", "))
+						return clierrors.InputError(
+							"no valid events specified",
+							fmt.Sprintf("支持的事件类型: %s", strings.Join(supportedEvents, ", ")),
+						)
 					}
 					payload["events"] = validEvents
 				}
-
-
 				if contentType := ctx.Arg("content_type"); contentType != "" {
 					payload["content_type"] = contentType
 				}
-
 				if secret := ctx.Arg("secret"); secret != "" {
 					payload["secret"] = secret
 				}
-
 				if description := ctx.Arg("description"); description != "" {
 					payload["description"] = description
 				}

-
+				// 步骤6：发送 PUT 请求更新 Webhook
 				env, err := ctx.CallAPI("PUT", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), payload)
 				if err != nil {
 					return fmt.Errorf("更新 Webhook 失败: %w", err)
@ -206,28 +256,36 @@ func Shortcuts() []*common.Shortcut {
 				return ctx.Output(env)
 			},
 		},
+		// delete 命令：删除 Webhook（带双重验证机制）
 		{
 			Name:        "delete",
 			Description: "Delete a webhook",
+			DryRun:      true,
+			DryRunHint: func(ctx *common.RuntimeContext) (string, error) {
+				return fmt.Sprintf("删除 Webhook #%s", ctx.Arg("id")), nil
+			},
 			Flags: []common.Flag{
 				{Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}

+				// 步骤2：获取必需参数 --id
 				webhookID, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}

+				// 步骤3：发送 DELETE 请求
 				_, delErr := ctx.CallAPI("DELETE", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
 				if delErr != nil {
-					// 验证是否真的删除成功（类似release的处理）
+					// 双重验证：如果 DELETE 失败，再调用 GET 检查 Webhook 是否还存在
 					_, viewErr := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
 					if viewErr != nil {
-						// Webhook不存在了，说明删除成功
+						// GET 也失败，说明 Webhook 确实不存在了，视为删除成功
 						return ctx.Output(output.SuccessEnvelope(map[string]interface{}{
 							"message": "Webhook deleted successfully",
 						}, nil))
@ -239,6 +297,7 @@ func Shortcuts() []*common.Shortcut {
 				}, nil))
 			},
 		},
+		// test 命令：测试 Webhook（发送测试请求）
 		{
 			Name:        "test",
 			Description: "Test a webhook delivery (send a ping event)",
@ -247,20 +306,27 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "event", Short: "e", Usage: "Event type to test (default: push)", Default: "push"},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}

+				// 步骤2：获取必需参数 --id
 				webhookID, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}

+				// 步骤3：验证事件类型
 				eventType := ctx.Arg("event")
 				if !isEventSupported(eventType) {
-					return fmt.Errorf("unsupported event type: %s. Supported events: %s", eventType, strings.Join(supportedEvents, ", "))
+					return clierrors.InputError(
+						fmt.Sprintf("unsupported event type: %s", eventType),
+						fmt.Sprintf("支持的事件类型: %s", strings.Join(supportedEvents, ", ")),
+					)
 				}

+				// 步骤4：发送测试请求
 				env, err := ctx.CallAPI("POST", fmt.Sprintf("%s/webhooks/%s/tests", webhookRepoPath(ctx), webhookID), nil)
 				if err != nil {
 					return fmt.Errorf("测试 Webhook 失败: %w", err)
@ -268,6 +334,7 @@ func Shortcuts() []*common.Shortcut {
 				return ctx.Output(env)
 			},
 		},
+		// info 命令：查看 Webhook 详情
 		{
 			Name:        "info",
 			Description: "Show webhook details",
@ -275,15 +342,18 @@ func Shortcuts() []*common.Shortcut {
 				{Name: "id", Short: "i", Usage: "Webhook ID", Required: true},
 			},
 			Run: func(ctx *common.RuntimeContext) error {
+				// 步骤1：解析仓库信息
 				if err := ctx.ResolveOwnerRepo(); err != nil {
 					return err
 				}

+				// 步骤2：获取必需参数 --id
 				webhookID, err := ctx.RequireArg("id", "--id 1")
 				if err != nil {
 					return err
 				}

+				// 步骤3：调用 GET API 获取详情
 				env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/webhooks/%s", webhookRepoPath(ctx), webhookID), nil)
 				if err != nil {
 					return fmt.Errorf("查看 Webhook 详情失败: %w", err)
@ -291,10 +361,12 @@ func Shortcuts() []*common.Shortcut {
 				return ctx.Output(env)
 			},
 		},
+		// events 命令：列出所有支持的事件类型
 		{
 			Name: "events",
 			Description: "List all supported event types for webhooks",
 			Run: func(ctx *common.RuntimeContext) error {
+				// 构建事件信息列表
 				eventInfo := make([]map[string]interface{}, 0)
 				for _, event := range supportedEvents {
 					eventInfo = append(eventInfo, map[string]interface{}{
@ -303,12 +375,16 @@ func Shortcuts() []*common.Shortcut {
 						"description": getEventDescription(event),
 					})
 				}
+				// 输出结果（用 SuccessEnvelope 包装）
 				return ctx.Output(output.SuccessEnvelope(eventInfo, nil))
 			},
 		},
 	}
 }

+// getEventDescription 返回事件类型的英文描述
+// 参数: event - 事件类型名称
+// 返回: 事件描述，如果找不到则返回 "Custom event"
 func getEventDescription(event string) string {
 	descriptions := map[string]string{
 		"push":                "Code push events",
--- a/shortcuts/wiki/wiki.go
+++ b/shortcuts/wiki/wiki.go
@ -1,94 +1,139 @@
 package wiki

 import (
-	"encoding/base64"
-	"fmt"
-	"net/http"
-	"net/url"
-	"os"
-	"regexp"
-	"strconv"
-	"strings"
-	"sync"
-	"time"
+	"encoding/base64"   // Base64 编解码，Wiki 内容是 Base64 编码的
+	"encoding/json"    // JSON 处理，用于解析 API 响应
+	"errors"           // 错误处理
+	"fmt"              // 格式化输出
+	"net/http"         // HTTP 客户端相关
+	"net/url"          // URL 处理，用于构建查询参数
+	"os"               // 文件操作，用于读取本地文件内容
+	"regexp"           // 正则表达式，用于 Lint 功能中的链接匹配
+	"strconv"          // 字符串和数字转换
+	"strings"          // 字符串处理
+	"sync"             // 并发安全，用于 projectIDCache
+	"time"             // 时间相关，用于 HTTP 超时设置

-	"github.com/gitlink-org/gitlink-cli/internal/auth"
-	"github.com/gitlink-org/gitlink-cli/internal/client"
-	"github.com/gitlink-org/gitlink-cli/internal/output"
-	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+	"github.com/gitlink-org/gitlink-cli/internal/auth"     // 认证模块，创建带认证的 HTTP 客户端
+	"github.com/gitlink-org/gitlink-cli/internal/client"   // HTTP 客户端模块，封装 API 请求
+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors" // 自定义 CLI 错误类型
+	"github.com/gitlink-org/gitlink-cli/internal/output"   // 输出格式化模块
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"  // 公共工具包，包含 Shortcut、RuntimeContext 等
 )

+// projectIDCache 项目 ID 缓存，使用 sync.Map 实现并发安全
+// 键：owner/repo，值：project_id（字符串）
+// 作用：避免重复调用项目详情 API 获取 project_id
 var projectIDCache sync.Map

+// wikiPath 构建 Wiki API 的路径前缀
+// 参数: endpoint - API 端点（如 "pages", "getWiki"）
+// 返回: 完整路径，如 "/wiki/open/pages"
+// 说明：Wiki 功能调用的是网关 API，所有接口都有固定前缀 "/wiki/open/"
 func wikiPath(endpoint string) string {
 	return "/wiki/open/" + endpoint
 }

-// getGatewayClient returns a client targeting the Wiki API gateway.
-// The BaseURL is resolved from RuntimeContext.GatewayBaseURL, which in turn
-// honours (in order): GITLINK_GATEWAY_URL env > config gateway_base_url > default.
-// HTTP client falls back to auth.NewHTTPClient() when ctx.GatewayHTTPClient is nil.
+// getGatewayClient 创建 Wiki API 专用的 HTTP 客户端
+// BaseURL 优先级：
+//   1. GITLINK_GATEWAY_URL 环境变量（最高优先级）
+//   2. 配置文件中的 gateway_base_url
+//   3. 默认值 https://gateway.gitlink.org.cn/api（最低优先级）
+// HTTP 客户端：如果 ctx.GatewayHTTPClient 为 nil，回退到 auth.NewHTTPClient()（带认证）
 func getGatewayClient(ctx *common.RuntimeContext) *client.Client {
 	baseURL := ctx.GatewayBaseURL
 	if baseURL == "" {
-		baseURL = "https://gateway.gitlink.org.cn/api"
+		baseURL = "https://gateway.gitlink.org.cn/api" // 兜底默认值
 	}
 	httpClient := ctx.GatewayHTTPClient
 	if httpClient == nil {
-		httpClient = auth.NewHTTPClient()
+		httpClient = auth.NewHTTPClient() // 创建带认证的 HTTP 客户端
 	}
 	return &client.Client{
-		HTTP:           httpClient,
-		BaseURL:        baseURL,
-		SkipJSONSuffix: true,
-		Debug:          ctx.Client.Debug,
+		HTTP:           httpClient,         // HTTP 客户端（带认证）
+		BaseURL:        baseURL,           // Wiki 网关 API 地址
+		SkipJSONSuffix: true,              // 不需要在 URL 后加 .json 后缀
+		Debug:          ctx.Client.Debug,  // 继承调试模式设置
 	}
 }

+// callWikiAPI 调用 Wiki API（无查询参数）
+// 参数: method - HTTP 方法; path - API 路径; body - 请求体
+// 返回: API 响应信封，以及可能的错误
+// 内部流程：创建网关客户端 → 发送请求 → 处理响应
 func callWikiAPI(ctx *common.RuntimeContext, method, path string, body interface{}) (*output.Envelope, error) {
-	gc := getGatewayClient(ctx)
-	env, err := gc.Do(method, path, body, nil)
+	gc := getGatewayClient(ctx)                    // 创建 Wiki 专用客户端
+	env, err := gc.Do(method, path, body, nil)    // 发送请求
 	if err != nil {
 		return nil, err
 	}
-	return unwrapGatewayResponse(env)
+	return unwrapGatewayResponse(env)             // 处理网关响应格式
 }

+// callWikiAPIWithQuery 调用 Wiki API（带查询参数）
+// 参数: method - HTTP 方法; path - API 路径; query - URL 查询参数
+// 返回: API 响应信封，以及可能的错误
 func callWikiAPIWithQuery(ctx *common.RuntimeContext, method, path string, query url.Values) (*output.Envelope, error) {
-	gc := getGatewayClient(ctx)
-	env, err := gc.Do(method, path, nil, query)
+	gc := getGatewayClient(ctx)                   // 创建 Wiki 专用客户端
+	env, err := gc.Do(method, path, nil, query)   // 发送带查询参数的请求
 	if err != nil {
 		return nil, err
 	}
-	return unwrapGatewayResponse(env)
+	return unwrapGatewayResponse(env)             // 处理网关响应格式
 }

+// unwrapGatewayResponse 处理网关 API 的响应格式
+// 网关 API 返回格式：{"code": 200, "data": {...}, "msg": "..."}
+// 主 API 返回格式：{"ok": true, "data": {...}}
+// 此函数将网关响应转换为统一的 Envelope 格式
 func unwrapGatewayResponse(env *output.Envelope) (*output.Envelope, error) {
+	// 尝试把 Data 转换为 map
 	resp, ok := env.Data.(map[string]interface{})
 	if !ok {
-		return env, nil
+		return env, nil // 不是 map 格式，直接返回
 	}
+	
+	// 检查 code 字段（网关 API 的状态码）
 	if code, ok := resp["code"]; ok {
 		switch v := code.(type) {
 		case float64:
-			if v != 200 && v != 201 {
+			// HTTP 2xx 全部视为成功（200 OK / 201 Created / 204 No Content 等）
+			if v < 200 || v >= 300 {
 				msg, _ := resp["msg"].(string)
-				return nil, fmt.Errorf("[%.0f] %s", v, msg)
+				// 根据状态码确定错误类型
+				kind := clierrors.KindServer
+				if int(v) == 404 {
+					kind = clierrors.KindNotFound
+				} else if int(v) == 401 || int(v) == 403 {
+					kind = clierrors.KindForbidden
+				}
+				return nil, clierrors.New(kind, msg,
+					"检查 owner/repo 是否正确，或确认仓库已在 GitLink 网页端开启 Wiki 功能")
 			}
 		}
 	}
+	
+	// 提取内层 data 字段
 	if innerData, ok := resp["data"]; ok {
 		return output.SuccessEnvelope(innerData, env.Meta), nil
 	}
 	return env, nil
 }

+// resolveProjectID 获取项目 ID（带缓存）
+// 流程：
+//   1. 先从缓存查找（owner/repo 作为键）
+//   2. 缓存命中：直接返回
+//   3. 缓存未命中：调用项目详情 API 获取 project_id，并存入缓存
+// 参数: ctx - 运行时上下文，包含 Owner 和 Repo
+// 返回: project_id（字符串），以及可能的错误
 func resolveProjectID(ctx *common.RuntimeContext) (string, error) {
 	key := ctx.Owner + "/" + ctx.Repo
 	if cached, ok := projectIDCache.Load(key); ok {
-		return cached.(string), nil
+		return cached.(string), nil // 缓存命中，直接返回
 	}

+	// 调用项目详情 API 获取 project_id
 	path := fmt.Sprintf("/%s/%s/detail", ctx.Owner, ctx.Repo)
 	env, err := ctx.CallAPI("GET", path, nil)
 	if err != nil {
@ -105,31 +150,39 @@ func resolveProjectID(ctx *common.RuntimeContext) (string, error) {
 		return "", fmt.Errorf("project_id not found in project detail response")
 	}

+	// 处理 project_id 的多种类型（API 返回可能是 float64、int 或 string）
 	var pidStr string
 	switch v := pid.(type) {
 	case float64:
-		pidStr = fmt.Sprintf("%.0f", v)
+		pidStr = fmt.Sprintf("%.0f", v) // JSON 数字默认解析为 float64
 	case int:
 		pidStr = fmt.Sprintf("%d", v)
 	default:
 		pidStr = fmt.Sprintf("%v", v)
 	}

-	projectIDCache.Store(key, pidStr)
+	projectIDCache.Store(key, pidStr) // 存入缓存
 	return pidStr, nil
 }

+// parseProjectIDInt 将项目 ID 字符串转换为整数
+// 参数: pid - 项目 ID 字符串
+// 返回: 整数形式的项目 ID（转换失败返回 0）
 func parseProjectIDInt(pid string) int {
 	n, _ := strconv.Atoi(pid)
 	return n
 }

+// resolveUpdateContent 解析更新内容（优先使用命令行参数，其次使用文件）
+// 参数: ctx - 运行时上下文; text - 命令行传入的内容; filePath - 文件路径
+// 返回: 最终内容字符串，以及可能的错误
+// 优先级：text（命令行参数） > filePath（文件） > 报错
 func resolveUpdateContent(ctx *common.RuntimeContext, text, filePath string) (string, error) {
 	if text != "" {
-		return text, nil
+		return text, nil // 优先使用命令行传入的内容
 	}
 	if filePath != "" {
-		data, err := os.ReadFile(filePath)
+		data, err := os.ReadFile(filePath) // 从文件读取内容
 		if err != nil {
 			return "", fmt.Errorf("failed to read file %s: %w", filePath, err)
 		}
@ -138,37 +191,90 @@ func resolveUpdateContent(ctx *common.RuntimeContext, text, filePath string) (st
 	return "", fmt.Errorf("no content provided")
 }

-func fetchPageContent(ctx *common.RuntimeContext, projectID, pageName string) (string, error) {
+// fetchPageContent 获取 wiki 页面明文内容（带自动重试）
+//
+// 自动重试策略：GitLink 后端创建 wiki 时会自动给 sub_url 追加 ".-" 后缀，
+// 而 wiki list 返回的 title 不带后缀。若首次用原始 pageName 查询失败且
+// pageName 不带 ".-" 后缀，自动用 pageName+".-" 重试一次。
+//
+// 返回值：
+//   - content: 解码后的明文 markdown
+//   - actualPageName: 实际查询成功的 pageName（可能带 ".-" 后缀），供调用方做后续写操作
+//   - err: 错误信息
+func fetchPageContent(ctx *common.RuntimeContext, projectID, pageName string) (content string, actualPageName string, err error) {
+	c, actual, err := fetchPageContentOnce(ctx, projectID, pageName)
+	if err == nil {
+		return c, actual, nil // 首次尝试成功，直接返回
+	}
+	// 首次失败且 pageName 不带 ".-" 后缀：自动重试一次
+	if !strings.HasSuffix(pageName, ".-") {
+		c2, actual2, err2 := fetchPageContentOnce(ctx, projectID, pageName+".-")
+		if err2 == nil {
+			return c2, actual2, nil // 重试成功
+		}
+	}
+	return "", "", fmt.Errorf("获取 Wiki 页面现有内容失败: %w", err)
+}
+
+// fetchPageContentOnce 单次尝试获取 wiki 页面内容（不做重试）
+// 参数: ctx - 运行时上下文; projectID - 项目 ID; pageName - 页面名称
+// 返回: 解码后的明文内容、实际页面名称、可能的错误
+func fetchPageContentOnce(ctx *common.RuntimeContext, projectID, pageName string) (string, string, error) {
 	q := url.Values{}
 	q.Set("owner", ctx.Owner)
 	q.Set("repo", ctx.Repo)
 	q.Set("projectId", projectID)
 	q.Set("pageName", pageName)
+	
+	// 调用 getWiki API 获取页面内容
 	env, err := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
 	if err != nil {
-		return "", fmt.Errorf("获取 Wiki 页面现有内容失败: %w", err)
+		return "", "", err
 	}
+	
 	data, ok := env.Data.(map[string]interface{})
 	if !ok {
-		return "", fmt.Errorf("unexpected response from getWiki")
+		return "", "", fmt.Errorf("unexpected response from getWiki")
 	}
+	
 	b64, _ := data["content_base64"].(string)
 	if b64 == "" {
-		return "", nil
+		return "", pageName, nil // 没有内容，返回空字符串
 	}
+	
+	// Base64 解码
 	decoded, err := base64.StdEncoding.DecodeString(b64)
 	if err != nil {
-		return "", fmt.Errorf("failed to decode page content: %w", err)
+		return "", "", fmt.Errorf("failed to decode page content: %w", err)
 	}
-	return string(decoded), nil
+	return string(decoded), pageName, nil
 }

+// fetchWikiPage 按 pageName 查询 wiki 页面，返回完整的 envelope
+// 与 fetchPageContent 的区别：
+//   - fetchPageContent 只返回解码后的内容
+//   - fetchWikiPage 返回完整的 API 响应，包含所有元数据
+// 参数: ctx - 运行时上下文; projectID - 项目 ID; pageName - 页面名称
+// 返回: 完整的响应信封，以及可能的错误
+func fetchWikiPage(ctx *common.RuntimeContext, projectID, pageName string) (*output.Envelope, error) {
+	q := url.Values{}
+	q.Set("owner", ctx.Owner)
+	q.Set("repo", ctx.Repo)
+	q.Set("projectId", projectID)
+	q.Set("pageName", pageName)
+	return callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
+}
+
+// resolveContent 解析 wiki 页面内容（优先使用命令行参数，其次使用文件）
+// 参数: ctx - 运行时上下文
+// 返回: 内容字符串，以及可能的错误
+// 优先级：--content 参数 > --file 参数 > 报错
 func resolveContent(ctx *common.RuntimeContext) (string, error) {
 	if content := ctx.Arg("content"); content != "" {
-		return content, nil
+		return content, nil // 优先使用 --content 参数
 	}
 	if filePath := ctx.Arg("file"); filePath != "" {
-		data, err := os.ReadFile(filePath)
+		data, err := os.ReadFile(filePath) // 从文件读取内容
 		if err != nil {
 			return "", fmt.Errorf("failed to read file %s: %w", filePath, err)
 		}
@ -177,6 +283,11 @@ func resolveContent(ctx *common.RuntimeContext) (string, error) {
 	return "", fmt.Errorf("--content or --file is required to provide wiki page content")
 }

+// cleanWikiList 清理 wiki 列表响应数据
+// 功能：
+//   1. 删除敏感字段 wiki_clone_link（用户不需要看到）
+//   2. 对 sub_url 进行 URL 解码（后端返回的是编码后的）
+// 参数: env - API 响应信封
 func cleanWikiList(env *output.Envelope) {
 	items, ok := env.Data.([]interface{})
 	if !ok {
@ -187,56 +298,103 @@ func cleanWikiList(env *output.Envelope) {
 		if !ok {
 			continue
 		}
-		delete(m, "wiki_clone_link")
+		delete(m, "wiki_clone_link") // 删除敏感字段
 		if raw, ok := m["sub_url"].(string); ok {
 			if decoded, err := url.QueryUnescape(raw); err == nil {
-				m["sub_url"] = decoded
+				m["sub_url"] = decoded // URL 解码
 			}
 		}
 	}
 }

+// outputWithDecodedContent 解码 wiki 响应中的所有 base64 字段，用明文替换原始乱码
+//
+// 设计权衡（agent 友好性）:
+//   - 后端返回的字段（content_base64、sidebar、footer）都是 base64 编码，对 agent 不可读
+//   - 解码后用明文替换/移除原始字段，agent 可直接阅读、抽取、总结
+//   - 节省 ~33% token（base64 编码膨胀部分）
+//
+// 已知字段映射：
+//   - content_base64 → content（重命名，删除原字段）
+//   - sidebar        → sidebar（原地替换，仅当解码成功）
+//   - footer         → footer（原地替换，仅当解码成功）
+//
+// 安全策略：仅当 base64.StdEncoding.DecodeString 成功时才替换；
+// 若后端某天改为明文，解码失败会自动跳过，不影响兼容性。
 func outputWithDecodedContent(ctx *common.RuntimeContext, env *output.Envelope) error {
-	data, ok := env.Data.(map[string]interface{})
-	if !ok {
-		return ctx.Output(env)
-	}
-	if b64, ok := data["content_base64"].(string); ok && b64 != "" {
-		decoded, err := base64.StdEncoding.DecodeString(b64)
-		if err == nil {
-			data["content_decoded"] = string(decoded)
+	data := env.Data
+
+	// 后端某些端点（如 createWiki/updateWiki）把 data 返回为 JSON 字符串，
+	// client.go 会把它解析为 json.RawMessage（而非 map）；这里先转回 map 再处理。
+	// view/getWiki 端点直接返回 JSON 对象，data 已是 map[string]interface{}。
+	if raw, ok := data.(json.RawMessage); ok {
+		var m map[string]interface{}
+		if err := json.Unmarshal(raw, &m); err == nil {
+			data = m
+			env.Data = m
 		}
 	}
-	return ctx.Output(env)
+
+	m, ok := data.(map[string]interface{})
+	if !ok {
+		return ctx.Output(env) // 不是 map 格式，直接输出
+	}
+	
+	// content_base64 → content（重命名）
+	if b64, ok := m["content_base64"].(string); ok && b64 != "" {
+		if decoded, err := base64.StdEncoding.DecodeString(b64); err == nil {
+			m["content"] = string(decoded)
+			delete(m, "content_base64") // 删除原始编码字段
+		}
+	}
+	
+	// sidebar / footer：原地替换（仅当能解码为 base64 时）
+	for _, field := range []string{"sidebar", "footer"} {
+		if b64, ok := m[field].(string); ok && b64 != "" {
+			if decoded, err := base64.StdEncoding.DecodeString(b64); err == nil {
+				m[field] = string(decoded)
+			}
+		}
+	}
+	return ctx.Output(env) // 输出处理后的响应
 }

 // --- lint types and implementation ---
+// Lint 功能用于扫描 Wiki 页面内容，检查潜在问题：空页面、缺少标题、内容过短、死链接、失效图片

+// LintIssue 表示单个检查问题
 type LintIssue struct {
-	Page    string `json:"page"`
-	Level   string `json:"level"`
-	Check   string `json:"check"`
-	Message string `json:"message"`
+	Page    string `json:"page"`      // 页面名称
+	Level   string `json:"level"`     // 级别："error"（错误）或 "warning"（警告）
+	Check   string `json:"check"`     // 检查项名称：empty/headings/short/links/images/fetch
+	Message string `json:"message"`   // 详细错误/警告信息
 }

+// LintSummary 表示检查汇总报告
 type LintSummary struct {
-	Repository  string      `json:"repository"`
-	TotalPages  int         `json:"total_pages"`
-	TotalIssues int         `json:"total_issues"`
-	Errors      int         `json:"errors"`
-	Warnings    int         `json:"warnings"`
-	Results     []LintIssue `json:"results"`
+	Repository  string      `json:"repository"`   // 仓库名称（owner/repo）
+	TotalPages  int         `json:"total_pages"`  // 检查的总页数
+	TotalIssues int         `json:"total_issues"` // 发现的总问题数
+	Errors      int         `json:"errors"`       // 错误数量
+	Warnings    int         `json:"warnings"`     // 警告数量
+	Results     []LintIssue `json:"results"`      // 所有问题的详细列表
 }

+// 正则表达式：用于匹配 Markdown 内容中的链接和图片
 var (
-	mdLinkRe    = regexp.MustCompile(`\[([^\]]*)\]\(([^)]+)\)`)
-	imageLinkRe = regexp.MustCompile(`!\[([^\]]*)\]\((https?://[^)]+)\)`)
+	mdLinkRe    = regexp.MustCompile(`\[([^\]]*)\]\(([^)]+)\)`)     // 匹配 [链接文字](链接地址)
+	imageLinkRe = regexp.MustCompile(`!\[([^\]]*)\]\((https?://[^)]+)\)`) // 匹配 ![图片说明](http://...)
 )

+// isCheckEnabled 检查指定的检查项是否启用
+// checkFilter: 用户通过 --check 参数指定的检查项（逗号分隔），为空则启用全部
+// name: 当前检查项名称
+// 返回: true 表示启用，false 表示禁用
 func isCheckEnabled(checkFilter, name string) bool {
 	if checkFilter == "" {
-		return true
+		return true // 没有指定过滤，全部启用
 	}
+	// 遍历用户指定的检查项列表，匹配则启用
 	for _, c := range strings.Split(checkFilter, ",") {
 		if strings.TrimSpace(c) == name {
 			return true
@ -245,6 +403,10 @@ func isCheckEnabled(checkFilter, name string) bool {
 	return false
 }

+// checkEmpty 检查页面是否为空
+// page: 页面名称
+// content: 页面内容
+// 返回: 发现问题返回 LintIssue 列表，无问题返回 nil
 func checkEmpty(page, content string) []LintIssue {
 	if strings.TrimSpace(content) == "" {
 		return []LintIssue{{Page: page, Level: "error", Check: "empty", Message: "page is empty"}}
@ -252,6 +414,8 @@ func checkEmpty(page, content string) []LintIssue {
 	return nil
 }

+// checkHeading 检查页面是否缺少 H1 标题（# 开头）
+// Markdown 规范：页面应从一级标题开始
 func checkHeading(page, content string) []LintIssue {
 	if content != "" && !strings.HasPrefix(strings.TrimSpace(content), "# ") {
 		return []LintIssue{{Page: page, Level: "warning", Check: "headings", Message: "missing H1 heading"}}
@ -259,6 +423,7 @@ func checkHeading(page, content string) []LintIssue {
 	return nil
 }

+// checkShort 检查页面内容是否过短（少于 50 字符）
 func checkShort(page, content string) []LintIssue {
 	if content != "" && len(content) < 50 {
 		return []LintIssue{{Page: page, Level: "warning", Check: "short", Message: fmt.Sprintf("content too short (%d chars)", len(content))}}
@ -266,21 +431,33 @@ func checkShort(page, content string) []LintIssue {
 	return nil
 }

+// checkDeadLinks 检查页面中是否有指向不存在页面的链接（死链接）
+// page: 页面名称
+// content: 页面内容
+// knownTitles: 已知页面标题映射（用于判断链接目标是否存在）
+// 逻辑：
+// 1. 使用正则匹配所有 Markdown 链接 [文字](地址)
+// 2. 跳过外部链接（http://, https://）和锚点（#开头）
+// 3. URL 解码处理（如 "首页%20页面" -> "首页 页面"）
+// 4. 检查目标页面是否在 knownTitles 中，不在则为死链接
 func checkDeadLinks(page, content string, knownTitles map[string]bool) []LintIssue {
 	var issues []LintIssue
+	// 遍历所有匹配的 Markdown 链接
 	for _, m := range mdLinkRe.FindAllStringSubmatch(content, -1) {
 		if len(m) < 3 {
-			continue
+			continue // 匹配不完整，跳过
 		}
-		target := m[2]
-		// skip external links and anchors
+		target := m[2] // 获取链接地址（正则捕获组第2个）
+		// 跳过外部链接和锚点链接
 		if strings.HasPrefix(target, "http://") || strings.HasPrefix(target, "https://") || strings.HasPrefix(target, "#") {
 			continue
 		}
+		// URL 解码，处理编码后的页面名称
 		decoded, _ := url.PathUnescape(target)
 		if decoded == "" {
 			decoded = target
 		}
+		// 检查目标页面是否存在
 		if !knownTitles[decoded] && !knownTitles[target] {
 			issues = append(issues, LintIssue{
 				Page:    page,
@ -293,24 +470,39 @@ func checkDeadLinks(page, content string, knownTitles map[string]bool) []LintIss
 	return issues
 }

+// checkImages 检查页面中图片链接是否有效
+// page: 页面名称
+// content: 页面内容
+// httpClient: 带超时的 HTTP 客户端（用于发送 HEAD 请求）
+// 逻辑：
+// 1. 使用正则匹配所有图片链接 ![说明](http://...)
+// 2. 发送 HEAD 请求（只获取响应头，不下载图片内容）
+// 3. 检查请求是否成功、HTTP 状态码是否 >= 400
 func checkImages(page, content string, httpClient *http.Client) []LintIssue {
 	var issues []LintIssue
+	// 遍历所有匹配的图片链接
 	for _, m := range imageLinkRe.FindAllStringSubmatch(content, -1) {
 		if len(m) < 3 {
-			continue
+			continue // 匹配不完整，跳过
 		}
-		imgURL := m[2]
+		imgURL := m[2] // 获取图片 URL（正则捕获组第2个）
+		
+		// 创建 HEAD 请求（只获取响应头，节省带宽）
 		req, err := http.NewRequest("HEAD", imgURL, nil)
 		if err != nil {
 			issues = append(issues, LintIssue{Page: page, Level: "warning", Check: "images", Message: fmt.Sprintf("broken image: %s -> invalid URL", imgURL)})
 			continue
 		}
+		
+		// 发送请求并检查响应
 		resp, err := httpClient.Do(req)
 		if err != nil {
 			issues = append(issues, LintIssue{Page: page, Level: "warning", Check: "images", Message: fmt.Sprintf("broken image: %s -> unreachable", imgURL)})
 			continue
 		}
-		resp.Body.Close()
+		resp.Body.Close() // 必须关闭响应体，防止资源泄漏
+		
+		// HTTP 状态码 >= 400 表示图片不存在或无法访问
 		if resp.StatusCode >= 400 {
 			issues = append(issues, LintIssue{Page: page, Level: "warning", Check: "images", Message: fmt.Sprintf("broken image: %s -> %d", imgURL, resp.StatusCode)})
 		}
@ -318,20 +510,30 @@ func checkImages(page, content string, httpClient *http.Client) []LintIssue {
 	return issues
 }

+// runLint 是 Wiki 内容检查的主函数
+// 执行流程：
+// 1. 解析仓库信息
+// 2. 获取项目 ID
+// 3. 获取所有页面列表，构建已知页面标题映射
+// 4. 遍历每个页面，获取内容并执行各项检查
+// 5. 统计错误和警告，输出汇总报告
 func runLint(ctx *common.RuntimeContext) error {
+	// 步骤1：解析仓库信息（从命令行参数或 Git 远程仓库）
 	if err := ctx.ResolveOwnerRepo(); err != nil {
 		return err
 	}

+	// 获取用户指定的检查项过滤（--check 参数，逗号分隔）
 	checkFilter := ctx.Arg("check")
 	fmt.Fprintf(os.Stderr, "Linting wiki pages for %s/%s...\n\n", ctx.Owner, ctx.Repo)

+	// 步骤2：获取项目 ID（用于调用 Wiki API）
 	projectID, err := resolveProjectID(ctx)
 	if err != nil {
 		return err
 	}

-	// Fetch page list
+	// 步骤3：获取所有 Wiki 页面列表
 	q := url.Values{}
 	q.Set("owner", ctx.Owner)
 	q.Set("repo", ctx.Repo)
@ -341,31 +543,35 @@ func runLint(ctx *common.RuntimeContext) error {
 		return fmt.Errorf("failed to list wiki pages: %w", err)
 	}

-	// Parse pages: title for display/link-check, sub_url for fetching
+	// 步骤4：解析页面列表，构建已知页面标题映射
+	// pageInfo 保存每个页面的标题和子路径（用于获取内容）
 	type pageInfo struct {
-		title  string
-		subURL string
+		title  string  // 页面标题（用于显示和死链接检查）
+		subURL string  // 页面子路径（用于获取页面内容）
 	}
-	knownTitles := make(map[string]bool)
-	var pages []pageInfo
+	knownTitles := make(map[string]bool) // 已知页面标题集合（用于检查死链接）
+	var pages []pageInfo                 // 所有页面列表
+	
+	// 遍历 API 返回的页面数据
 	if items, ok := env.Data.([]interface{}); ok {
 		for _, item := range items {
 			m, ok := item.(map[string]interface{})
 			if !ok {
-				continue
+				continue // 数据格式不对，跳过
 			}
 			title, _ := m["title"].(string)
 			subURL, _ := m["sub_url"].(string)
 			if title != "" {
-				knownTitles[title] = true
+				knownTitles[title] = true // 记录到已知标题映射
 				if subURL == "" {
-					subURL = title
+					subURL = title // 如果没有子路径，用标题代替
 				}
 				pages = append(pages, pageInfo{title: title, subURL: subURL})
 			}
 		}
 	}

+	// 如果没有页面，直接返回空报告
 	if len(pages) == 0 {
 		fmt.Fprintln(os.Stderr, "No wiki pages found.")
 		return ctx.OutputData(LintSummary{
@ -374,22 +580,26 @@ func runLint(ctx *common.RuntimeContext) error {
 		})
 	}

-	// HTTP client for image checks with 5s timeout
+	// 创建带 5 秒超时的 HTTP 客户端（用于图片链接检查）
 	httpClient := &http.Client{Timeout: 5 * time.Second}

-	var allIssues []LintIssue
+	// 步骤5：遍历每个页面，执行各项检查
+	var allIssues []LintIssue // 收集所有发现的问题

 	for _, p := range pages {
-		// Skip system pages (e.g. _Sidebar, _Footer, _Header)
+		// 跳过系统页面（以下划线开头，如 _Sidebar, _Footer）
 		if strings.HasPrefix(p.title, "_") {
 			continue
 		}
-		content, err := fetchPageContent(ctx, projectID, p.subURL)
+		
+		// 获取页面内容
+		content, _, err := fetchPageContent(ctx, projectID, p.subURL)
 		if err != nil {
 			allIssues = append(allIssues, LintIssue{Page: p.title, Level: "error", Check: "fetch", Message: fmt.Sprintf("failed to fetch: %v", err)})
-			continue
+			continue // 获取内容失败，跳过该页面的其他检查
 		}

+		// 根据用户配置，执行各项检查
 		if isCheckEnabled(checkFilter, "empty") {
 			allIssues = append(allIssues, checkEmpty(p.title, content)...)
 		}
@ -407,7 +617,7 @@ func runLint(ctx *common.RuntimeContext) error {
 		}
 	}

-	// Count errors/warnings
+	// 步骤6：统计错误和警告数量
 	var errCount, warnCount int
 	for _, issue := range allIssues {
 		if issue.Level == "error" {
@ -417,7 +627,7 @@ func runLint(ctx *common.RuntimeContext) error {
 		}
 	}

-	// Print issues to stderr
+	// 步骤7：在控制台输出详细结果（✗ 表示错误，⚠ 表示警告）
 	for _, issue := range allIssues {
 		if issue.Level == "error" {
 			fmt.Fprintf(os.Stderr, "  ✗ %s - %s\n", issue.Page, issue.Message)
@ -427,6 +637,7 @@ func runLint(ctx *common.RuntimeContext) error {
 	}
 	fmt.Fprintf(os.Stderr, "\nSummary: %d pages, %d errors, %d warnings\n", len(pages), errCount, warnCount)

+	// 步骤8：返回 JSON 格式的汇总报告
 	return ctx.OutputData(LintSummary{
 		Repository:  ctx.Owner + "/" + ctx.Repo,
 		TotalPages:  len(pages),
@ -456,6 +667,14 @@ func Shortcuts() []*common.Shortcut {
 				q.Set("projectId", projectID)
 				env, err := callWikiAPIWithQuery(ctx, "GET", wikiPath("wikiPages"), q)
 				if err != nil {
+					// wiki +list 的 404 几乎总是意味着仓库未在 GitLink 网页端开启 Wiki 功能。
+					// 这种情况下不要再提示"用 +list 查看"（循环引用），改为引导用户去开启 Wiki。
+					var cliErr *clierrors.CLIError
+					if errors.As(err, &cliErr) && cliErr.Kind == clierrors.KindNotFound {
+						return clierrors.New(clierrors.KindNotFound,
+							fmt.Sprintf("仓库 %s/%s 没有 Wiki 页面", ctx.Owner, ctx.Repo),
+							fmt.Sprintf("请前往 GitLink 网页端 → 仓库 %s/%s → 设置 → 开启 Wiki 功能，开启后再创建页面", ctx.Owner, ctx.Repo))
+					}
 					return fmt.Errorf("获取 Wiki 页面列表失败: %w", err)
 				}
 				cleanWikiList(env)
@ -480,14 +699,23 @@ func Shortcuts() []*common.Shortcut {
 				if err != nil {
 					return err
 				}
-				q := url.Values{}
-				q.Set("owner", ctx.Owner)
-				q.Set("repo", ctx.Repo)
-				q.Set("projectId", projectID)
-				q.Set("pageName", title)
-				env, err := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
+				env, err := fetchWikiPage(ctx, projectID, title)
 				if err != nil {
-					return fmt.Errorf("查看 Wiki 页面失败: %w", err)
+					// GitLink 后端命名规则: 创建 wiki 时会自动给 sub_url 追加 ".-" 后缀，
+					// 而 wiki +list 返回的 title 不带后缀。若 title 不带后缀且首次查询失败，
+					// 自动用 title + ".-" 重试一次。
+					if !strings.HasSuffix(title, ".-") {
+						env, err = fetchWikiPage(ctx, projectID, title+".-")
+					}
+				}
+				if err != nil {
+					// 用 CLIError 包装，保留底层错误类型，让 TryPrintError 能按 envelope 输出。
+					// suggestion 同时涵盖两种常见根因：(1) 仓库未开启 Wiki；(2) 页面名拼错。
+					return clierrors.Wrap(clierrors.KindNotFound,
+						fmt.Sprintf("Wiki 页面 %q 不存在", title),
+						fmt.Sprintf("请确认：(1) 仓库 %s/%s 已在 GitLink 网页端开启 Wiki 功能；(2) 页面名拼写正确。可用 `gitlink-cli wiki +list --owner %s --repo %s` 查看实际存在的页面",
+							ctx.Owner, ctx.Repo, ctx.Owner, ctx.Repo),
+						err)
 				}
 				return outputWithDecodedContent(ctx, env)
 			},
@ -540,7 +768,7 @@ func Shortcuts() []*common.Shortcut {
 				if err != nil {
 					return fmt.Errorf("创建 Wiki 页面失败: %w", err)
 				}
-				return ctx.Output(env)
+				return outputWithDecodedContent(ctx, env)
 			},
 		},
 		{
@ -595,10 +823,13 @@ func Shortcuts() []*common.Shortcut {
 					if err != nil {
 						return err
 					}
-					existing, err := fetchPageContent(ctx, projectID, pageName)
+					existing, actualPageName, err := fetchPageContent(ctx, projectID, pageName)
 					if err != nil {
 						return fmt.Errorf("failed to fetch existing page content for append: %w", err)
 					}
+					// fetchPageContent 可能因 GitLink 后端 ".-" 命名规则触发自动重试，
+					// 用实际成功的 pageName（可能带 .- 后缀）作为 PUT 目标，否则后端会再次 404。
+					pageName = actualPageName
 					finalContent = existing + newPart
 				}

@ -618,7 +849,7 @@ func Shortcuts() []*common.Shortcut {
 				if err != nil {
 					return fmt.Errorf("更新 Wiki 页面失败: %w", err)
 				}
-				return ctx.Output(env)
+				return outputWithDecodedContent(ctx, env)
 			},
 		},
 		{
@ -645,31 +876,64 @@ func Shortcuts() []*common.Shortcut {
 					return err
 				}

+				// 1. 解析实际 pageName（fetchPageContent 内部自动重试 ".-" 后缀）
+				//    不做这步直接用 title DELETE，会导致后端"接受了请求但没真删"
+				//    （后端期望的 pageName 是 "X.-" 而非 "X"）
+				_, actualPageName, err := fetchPageContent(ctx, projectID, title)
+				if err != nil {
+					// 页面查不到 — 后端 getWiki API 返回 404。
+					// suggestion 同时涵盖两种常见根因：(1) 仓库未开启 Wiki；(2) 页面名拼错。
+					// 注意：GitLink 网页端对任意 ?wiki=xxx 都会渲染 SPA 壳子，
+					// 不代表页面真实存在；以 wiki +list 的结果为准。
+					return clierrors.New(clierrors.KindNotFound,
+						fmt.Sprintf("Wiki 页面 %q 不存在", title),
+						fmt.Sprintf("请确认：(1) 仓库 %s/%s 已在 GitLink 网页端开启 Wiki 功能；(2) 页面名拼写正确。可用 `gitlink-cli wiki +list --owner %s --repo %s` 查看实际存在的页面",
+							ctx.Owner, ctx.Repo, ctx.Owner, ctx.Repo))
+				}
+
+				// 2. 用实际 pageName 调用 DELETE
 				body := map[string]interface{}{
 					"owner":     ctx.Owner,
 					"repo":      ctx.Repo,
 					"projectId": parseProjectIDInt(projectID),
-					"pageName":  title,
+					"pageName":  actualPageName,
 					"message":   "",
 				}
-
-				_, delErr := callWikiAPI(ctx, "DELETE", wikiPath("deleteWiki"), body)
-				if delErr != nil {
-					q := url.Values{}
-					q.Set("owner", ctx.Owner)
-					q.Set("repo", ctx.Repo)
-					q.Set("projectId", projectID)
-					q.Set("pageName", title)
-					_, viewErr := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q)
-					if viewErr != nil {
-						return ctx.OutputData(map[string]string{
-							"message": "Wiki page deleted successfully",
-						})
-					}
+				if _, delErr := callWikiAPI(ctx, "DELETE", wikiPath("deleteWiki"), body); delErr != nil {
 					return fmt.Errorf("删除 Wiki 页面失败: %w", delErr)
 				}
-				return ctx.OutputData(map[string]string{
-					"message": "Wiki page deleted successfully",
+
+				// 3. 删除后强制验证（GitLink deleteWiki 端点不可靠：即使返回 200，
+				//    页面有时仍然存在）。GET 一次确认页面真的没了。
+				q := url.Values{}
+				q.Set("owner", ctx.Owner)
+				q.Set("repo", ctx.Repo)
+				q.Set("projectId", projectID)
+				q.Set("pageName", actualPageName)
+				if _, viewErr := callWikiAPIWithQuery(ctx, "GET", wikiPath("getWiki"), q); viewErr == nil {
+					// GET 还能查到 — 后端接受了 DELETE 但没真删
+					return fmt.Errorf("删除 Wiki 页面失败：后端接受了请求但页面仍存在 (pageName=%s)", actualPageName)
+				}
+				// 删除成功 — 返回结构化数据，让用户/agent 能自助验证。
+				// 说明三种用户常见的"以为没删干净"的现象：
+				//   1) 网页端 ?wiki=xxx 仍可访问 → GitLink SPA 占位符（任何参数都渲染壳子）
+				//   2) git log 仍能看到删除 commit → git 设计就是保留历史
+				//   3) edit 跳转到 wiki=undefined → 网页端前端未正确处理 404
+				// 这些都不是 CLI 删除不彻底，是 GitLink 网页端的 UX 问题。
+				return ctx.OutputData(map[string]interface{}{
+					"message":          "Wiki page deleted successfully",
+					"deleted_title":    title,
+					"actual_page_name": actualPageName,
+					"wiki_repo":        fmt.Sprintf("https://gitlink.org.cn/%s/%s.wiki.git", ctx.Owner, ctx.Repo),
+					"notes": []string{
+						"页面已从 wiki 仓库 HEAD 彻底删除（git 工作树无残留）",
+						"网页端 ?wiki=xxx URL 仍可访问是 SPA 占位符，不代表页面存在",
+						"git 历史 commits 仍保留删除记录（git 的正常行为，非残留）",
+					},
+					"verify_commands": []string{
+						fmt.Sprintf("gitlink-cli wiki +list --owner %s --repo %s", ctx.Owner, ctx.Repo),
+						fmt.Sprintf("git clone https://gitlink.org.cn/%s/%s.wiki.git /tmp/wiki-check && git -C /tmp/wiki-check ls-files", ctx.Owner, ctx.Repo),
+					},
 				})
 			},
 		},
--- a/shortcuts/wiki/wiki_test.go
+++ b/shortcuts/wiki/wiki_test.go
@ -3,6 +3,7 @@ package wiki
 import (
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"os"
@ -12,6 +13,7 @@ import (
 	"testing"

 	"github.com/gitlink-org/gitlink-cli/internal/client"
+	clierrors "github.com/gitlink-org/gitlink-cli/internal/errors"
 	"github.com/gitlink-org/gitlink-cli/internal/output"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
 )
@ -79,8 +81,16 @@ func TestUnwrapGatewayResponse_BusinessError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
-	if err.Error() != "[500] 内部错误" {
-		t.Fatalf("got %q, want %q", err.Error(), "[500] 内部错误")
+	// 必须是 *clierrors.CLIError，否则 TryPrintError 无法按 envelope 输出
+	var cliErr *clierrors.CLIError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("expected *clierrors.CLIError, got %T: %v", err, err)
+	}
+	if cliErr.Kind != clierrors.KindServer {
+		t.Errorf("Kind = %q, want %q", cliErr.Kind, clierrors.KindServer)
+	}
+	if cliErr.Message != "内部错误" {
+		t.Errorf("Message = %q, want %q", cliErr.Message, "内部错误")
 	}
 }

@ -303,8 +313,17 @@ func TestCallWikiAPI_BusinessError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
-	if !strings.Contains(err.Error(), "400") || !strings.Contains(err.Error(), "bad request") {
-		t.Errorf("err = %q, want to contain 400 and bad request", err.Error())
+	// 必须是 *clierrors.CLIError，code=400 对应 KindForbidden（401/403）或 KindServer
+	// （其他非 200/404 错误），这里 400 走 KindServer 分支
+	var cliErr *clierrors.CLIError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("expected *clierrors.CLIError, got %T: %v", err, err)
+	}
+	if cliErr.Message != "bad request" {
+		t.Errorf("Message = %q, want %q", cliErr.Message, "bad request")
+	}
+	if cliErr.Suggestion == "" {
+		t.Errorf("Suggestion should not be empty (helps user recover)")
 	}
 }

--- a/skills/README.md
+++ b/skills/README.md
@ -126,8 +126,25 @@ skills/
 │   └── SKILL.md                       # Wiki 操作指南
 ├── gitlink-pm/                        # 项目管理
 │   └── SKILL.md                       # PM 操作指南
-└── gitlink-workflow/                  # AI 自动化工作流
-    └── SKILL.md                       # 工作流模板（Issue 分类、PR Review、Release Notes）
+├── gitlink-workflow/                  # AI 自动化工作流
+│   └── SKILL.md                       # 工作流模板（Issue 分类、PR Review、Release Notes）
+├── gitlink-issue-triage/              # Issue 自动分类
+│   ├── SKILL.md                       # AI Agent 主入口
+│   ├── README.md                      # 使用说明
+│   ├── references/                    # 分析算法 + 应用手册
+│   └── examples/                      # 批量/单 Issue 工作流示例
+├── gitlink-webhook/                   # Webhook 管理
+│   └── SKILL.md                       # Webhook 操作指南
+├── gitlink-compliance/                # 安全与合规
+│   └── SKILL.md                       # 许可证、敏感信息、PII 扫描
+├── gitlink-onboard/                   # 新人引导
+│   └── SKILL.md                       # Good First Issue 识别与欢迎评论
+├── gitlink-team/                      # 团队管理
+│   └── SKILL.md                       # 团队操作指南
+├── gitlink-contrib/                   # 贡献报告
+│   └── SKILL.md                       # 贡献统计与报告
+└── gitlink-code-insight/              # 功能全景
+    └── SKILL.md                       # 全部 Shortcuts 分类展示
 ```

 ---
@ -157,7 +174,14 @@ skills/
 | **gitlink-wiki** | Wiki 管理 | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` |
 | **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
 | **gitlink-changelog** | Release Notes / Changelog 生成 | 自动收集 commits/PR/Issue，生成结构化版本说明 |
+| **gitlink-issue-triage** | Issue 自动分类 | 自动判定 tracker/priority/labels，关联 Issue，生成审计报告 |
 | **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、仓库初始化、Sprint 报告 |
+| **gitlink-webhook** | Webhook 管理 | `webhook +list`, `webhook +create`, `webhook +test` |
+| **gitlink-compliance** | 安全与合规 | `compliance +scan`, `compliance +secrets`, `compliance +license` |
+| **gitlink-onboard** | 新人引导 | `onboard +welcome` |
+| **gitlink-team** | 团队管理 | `team +list`, `team +create`, `team +add-member` |
+| **gitlink-contrib** | 贡献报告 | `contrib +report` |
+| **gitlink-code-insight** | 功能全景 | 全部 Shortcuts 分类索引，含说明和示例 |

 ---

--- a/skills/gitlink-changelog/SKILL.md
+++ b/skills/gitlink-changelog/SKILL.md
@ -97,6 +97,8 @@ gitlink-cli release +update --id <version_id> --body "<更新后的 Notes>"
 **完整变更日志**: https://www.gitlink.org.cn/{OWNER}/{REPO}/compare/{PREV}...{VERSION}
 ```

+> **条目格式要求**：每个变更条目必须在末尾标注作者，格式为 `- 变更描述 (#编号) (@作者)`。commit 无 PR 编号时格式为 `- 变更描述 (作者名)`。
+
 ### 简化模板

 ```markdown
--- a/skills/gitlink-changelog/examples/full-workflow.md
+++ b/skills/gitlink-changelog/examples/full-workflow.md
@ -62,17 +62,17 @@ AI 根据 [分类规则](../references/classify-rules.md) 对收集到的数据

 ```
 新功能:
-  - 支持批量 Issue 操作 (#12)
-  - 新增 uninstall 命令 (#11)
+  - 支持批量 Issue 操作 (#12) (@zhangsan)
+  - 新增 uninstall 命令 (#11) (@lisi)

 Bug 修复:
-  - 修复 URL 解析异常 (#10)
+  - 修复 URL 解析异常 (#10) (@wangwu)

 功能改进:
-  - 重构自动部署配置
+  - 重构自动部署配置 (camelliamc)

 文档:
-  - 更新分支映射说明
+  - 更新分支映射说明 (camelliamc)
 ```

 ### 第六步：生成 Notes 并确认
@ -89,14 +89,14 @@ AI 套用标准模板生成草稿并展示给用户：
 - **破坏性变更**: 0 个

 ## ✨ 新功能
- 支持批量 Issue 操作 (#12)
- 新增 uninstall 命令 (#11)
+- 支持批量 Issue 操作 (#12) (@zhangsan)
+- 新增 uninstall 命令 (#11) (@lisi)

 ## 🐛 Bug 修复
- 修复 URL 解析异常 (#10)
+- 修复 URL 解析异常 (#10) (@wangwu)

 ## 🔧 功能改进
- 重构自动部署配置
+- 重构自动部署配置 (camelliamc)

 ## 🙏 贡献者
 zzx-coder, camelliamc
@ -120,17 +120,17 @@ gitlink-cli release +create \
 - **破坏性变更**: 0 个

 ## ✨ 新功能
- 支持批量 Issue 操作 (#12)
- 新增 uninstall 命令 (#11)
+- 支持批量 Issue 操作 (#12) (@zhangsan)
+- 新增 uninstall 命令 (#11) (@lisi)

 ## 🐛 Bug 修复
- 修复 URL 解析异常 (#10)
+- 修复 URL 解析异常 (#10) (@wangwu)

 ## 🔧 功能改进
- 重构自动部署配置
+- 重构自动部署配置 (camelliamc)

 ## 🙏 贡献者
-zzx-coder, camelliamc
+zhangsan, lisi, wangwu, camelliamc

 ---
 **完整变更日志**: https://www.gitlink.org.cn/zzx-coder/gitlink-cli/compare/v1.0.0...v1.1.0"
--- a/skills/gitlink-changelog/references/collect-data.md
+++ b/skills/gitlink-changelog/references/collect-data.md
@ -64,9 +64,9 @@ gitlink-cli issue +list --state closed --format json

 收集完成后，AI 整合三类数据：

-1. **Commits** → 提取 commit message 第一行作为变更摘要
-2. **PRs** → 用 `title` 和 `number` 生成条目：`- 功能描述 (#PR编号)`
-3. **Issues** → 用 `subject` 和 `project_issues_index` 生成条目：`- Issue 描述 (#编号)`
+1. **Commits** → 提取 commit message 第一行作为变更摘要，附作者名
+2. **PRs** → 用 `title`、`number`、`author.login` 生成条目：`- 功能描述 (#PR编号) (@作者)`
+3. **Issues** → 用 `subject`、`project_issues_index`、`author.login` 生成条目：`- Issue 描述 (#编号) (@作者)`

 时间筛选逻辑：从 `release +list` 获取上一个版本的发布时间，只取该时间之后的 PR/Issue。

--- a/skills/gitlink-changelog/references/generate-and-publish.md
+++ b/skills/gitlink-changelog/references/generate-and-publish.md
@ -66,7 +66,7 @@
 | `{OWNER}` | 仓库所有者，从 git remote 解析 |
 | `{REPO}` | 仓库名称，从 git remote 解析 |
 | `{FEATURE_COUNT}` 等 | 分类后的各类变更数量 |
-| `{FEATURES}` 等 | 分类后的各类变更条目，每条一行 `- 描述 (#编号)` |
+| `{FEATURES}` 等 | 分类后的各类变更条目，每条一行 `- 描述 (#编号) (@作者)` |
 | `{CONTRIBUTORS}` | 从 commits/PRs 去重后的贡献者列表 |

 ## 命令
--- a/skills/gitlink-code-insight/SKILL.md
+++ b/skills/gitlink-code-insight/SKILL.md
@ -0,0 +1,178 @@
+---
+name: gitlink-code-insight
+version: 4.0.0
+description: "功能全景仪表盘：当用户想了解 gitlink-cli 有哪些功能时，生成交互式 HTML 页面并打开浏览器展示。"
+metadata:
+  requires:
+    bins: ["python3"]
+---
+
+# gitlink-code-insight（功能全景仪表盘）
+
+## 触发条件
+
+用户问以下问题时触发：
+- "gitlink-cli 有哪些功能"
+- "帮我生成一个功能展示页面"
+- "我想浏览所有可用命令"
+
+## 执行步骤
+
+1. 根据下方 Shortcuts 数据生成单文件 HTML
+2. 写入 `doc/dashboard.html`
+3. 用 `python3 -c "import webbrowser; webbrowser.open('file://$(pwd)/doc/dashboard.html')"` 打开
+
+## 页面要求
+
+- 暗色主题（GitHub Dark 风格）
+- 顶部：标题 + 统计数字（分类数、Shortcuts 总数）+ 搜索框
+- 主体：分类卡片列表，每个卡片可折叠展开
+  - 卡片标题：图标 + 分类名 + 命令计数
+  - 展开后显示该分类下所有 shortcut 行
+  - 每行：命令（等宽蓝色）+ 认证标签（绿色=需认证，蓝色=公开）+ 描述
+  - 点击 shortcut 行展开代码示例
+- 搜索框实时过滤（按命令名和描述匹配），无匹配时隐藏整个分类
+- 纯 CSS + 原生 JS，无外部依赖
+
+---
+
+## Shortcuts 数据
+
+### 一、仓库管理 📦
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `repo +list` | 仓库列表 | 否 | `gitlink-cli repo +list --user zhangsan` |
+| `repo +info` | 仓库详情 | 否 | `gitlink-cli repo +info --owner Gitlink --repo forgeplus` |
+| `repo +create` | 创建仓库 | 是 | `gitlink-cli repo +create --name my-project --description "项目描述"` |
+| `repo +fork` | Fork 仓库 | 是 | `gitlink-cli repo +fork --owner Gitlink --repo forgeplus` |
+| `repo +delete` | 删除仓库（不可逆） | 是 | `gitlink-cli repo +delete --owner myuser --repo old-project` |
+| `repo +batch-create` | 批量创建仓库 | 是 | `gitlink-cli repo +batch-create --from repos.csv` |
+| `repo +batch-update` | 批量更新仓库 | 是 | `gitlink-cli repo +batch-update --from updates.csv` |
+| `repo +add-member` | 添加仓库成员 | 是 | `gitlink-cli repo +add-member --owner myuser --repo myrepo --user newmember --role developer` |
+
+### 二、分支管理 🌿
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `branch +list` | 分支列表 | 否 | `gitlink-cli branch +list --owner Gitlink --repo forgeplus` |
+| `branch +create` | 创建分支 | 是 | `gitlink-cli branch +create --name feature/new-feature` |
+| `branch +delete` | 删除分支（不可逆） | 是 | `gitlink-cli branch +delete --name feature/old-feature` |
+| `branch +protect` | 保护分支 | 是 | `gitlink-cli branch +protect --name main` |
+| `branch +unprotect` | 取消保护 | 是 | `gitlink-cli branch +unprotect --name main` |
+
+### 三、Issue 管理 🐛
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `issue +list` | Issue 列表 | 否 | `gitlink-cli issue +list --owner Gitlink --repo forgeplus --state open` |
+| `issue +view` | Issue 详情 | 否 | `gitlink-cli issue +view --owner Gitlink --repo forgeplus --number 4` |
+| `issue +create` | 创建 Issue | 是 | `gitlink-cli issue +create --owner myuser --repo myrepo --title "Bug: 登录失败" --body "复现步骤"` |
+| `issue +update` | 更新 Issue | 是 | `gitlink-cli issue +update --number 4 --title "新标题" --body "更新描述"` |
+| `issue +close` | 关闭 Issue | 是 | `gitlink-cli issue +close --number 4` |
+| `issue +batch-close` | 批量关闭 Issue | 是 | `gitlink-cli issue +batch-close --numbers 123,124 --dry-run` |
+| `issue +comment` | 添加评论 | 是 | `gitlink-cli issue +comment --number 4 --body "已修复"` |
+
+### 四、Pull Request 🔀
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `pr +list` | PR 列表 | 否 | `gitlink-cli pr +list --owner Gitlink --repo forgeplus --state open` |
+| `pr +view` | PR 详情 | 否 | `gitlink-cli pr +view --id 3` |
+| `pr +create` | 创建 PR | 是 | `gitlink-cli pr +create --title "feat: 新功能" --head feature/x --base master` |
+| `pr +merge` | 合并 PR | 是 | `gitlink-cli pr +merge --id 3 --method squash` |
+| `pr +close` | 关闭 PR | 是 | `gitlink-cli pr +close --id 3` |
+| `pr +files` | 变更文件列表 | 否 | `gitlink-cli pr +files --id 3` |
+| `pr +diff` | 查看提交列表 | 否 | `gitlink-cli pr +diff --id 3` |
+| `pr +comment` | PR 评论 | 是 | `gitlink-cli pr +comment --id 3 --body "LGTM"` |
+| `pr +review` | 代码审查 | 是 | `gitlink-cli pr +review --id 3 --event COMMENT --body "整体 LGTM"` |
+
+### 五、版本发布 🚀
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `release +list` | 发布列表 | 否 | `gitlink-cli release +list --owner Gitlink --repo forgeplus` |
+| `release +view` | 发布详情 | 否 | `gitlink-cli release +view --id <version_id>` |
+| `release +create` | 创建发布 | 是 | `gitlink-cli release +create --tag v1.0.0 --name "v1.0.0" --target master` |
+| `release +delete` | 删除发布（不可逆） | 是 | `gitlink-cli release +delete --id <version_id>` |
+
+### 六、Wiki 管理 📖
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `wiki +list` | Wiki 页面列表 | 否 | `gitlink-cli wiki +list --owner Gitlink --repo forgeplus` |
+| `wiki +view` | 查看页面内容 | 否 | `gitlink-cli wiki +view --owner Gitlink --repo forgeplus --title "Home"` |
+| `wiki +create` | 创建页面 | 是 | `gitlink-cli wiki +create --owner myuser --repo myrepo --title "API 文档" --file ./api.md` |
+| `wiki +update` | 更新页面 | 是 | `gitlink-cli wiki +update --owner myuser --repo myrepo --title "设计文档" --add "新内容"` |
+| `wiki +delete` | 删除页面 | 是 | `gitlink-cli wiki +delete --owner myuser --repo myrepo --title "废弃页面"` |
+
+### 七、CI/CD ⚙️
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `ci +builds` | 构建列表 | 是 | `gitlink-cli ci +builds --owner myuser --repo myrepo` |
+| `ci +logs` | 构建日志 | 是 | `gitlink-cli ci +logs --build 42 --stage 1 --step 1` |
+| `ci +restart` | 重启构建 | 是 | `gitlink-cli ci +restart --build 42` |
+| `ci +stop` | 停止构建 | 是 | `gitlink-cli ci +stop --build 42` |
+
+### 八、Webhook 🔔
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `webhook +list` | Webhook 列表 | 是 | `gitlink-cli webhook +list --owner myuser --repo myrepo` |
+| `webhook +info` | Webhook 详情 | 是 | `gitlink-cli webhook +info --owner myuser --repo myrepo --id 123` |
+| `webhook +events` | 支持的事件类型 | 否 | `gitlink-cli webhook +events` |
+| `webhook +create` | 创建 Webhook | 是 | `gitlink-cli webhook +create --url https://example.com/hook --events push` |
+| `webhook +update` | 更新 Webhook | 是 | `gitlink-cli webhook +update --id 123 --events push,pull_request` |
+| `webhook +test` | 测试 Webhook | 是 | `gitlink-cli webhook +test --id 123 --event push` |
+| `webhook +delete` | 删除 Webhook | 是 | `gitlink-cli webhook +delete --id 123` |
+
+### 九、组织管理 🏢
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `org +list` | 组织列表 | 否 | `gitlink-cli org +list` |
+| `org +info` | 组织详情 | 否 | `gitlink-cli org +info --id Gitlink` |
+| `org +members` | 成员列表 | 否 | `gitlink-cli org +members --id Gitlink` |
+| `org +create` | 创建组织 | 是 | `gitlink-cli org +create --name my-org --description "我的组织"` |
+| `org +batch-add` | 批量添加成员 | 是 | `gitlink-cli org +batch-add --id my-org --users "user1,user2"` |
+
+### 十、用户与搜索 👤
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `user +me` | 当前登录用户 | 是 | `gitlink-cli user +me` |
+| `user +info` | 用户详情 | 否 | `gitlink-cli user +info --login zhangsan` |
+| `search +repos` | 搜索仓库 | 否 | `gitlink-cli search +repos --keyword "machine learning"` |
+| `search +users` | 搜索用户 | 否 | `gitlink-cli search +users --keyword "zhangsan"` |
+
+### 十一、安全与合规 🛡️
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `compliance +scan` | 全量扫描 | 否 | `gitlink-cli compliance +scan` |
+| `compliance +license` | 许可证合规检查 | 否 | `gitlink-cli compliance +license` |
+| `compliance +deps` | 依赖许可证检查 | 否 | `gitlink-cli compliance +deps` |
+| `compliance +secrets` | 敏感信息扫描 | 否 | `gitlink-cli compliance +secrets` |
+| `compliance +exposure` | PII 与暴露面扫描 | 否 | `gitlink-cli compliance +exposure` |
+| `compliance +vocab` | 敏感词汇扫描 | 否 | `gitlink-cli compliance +vocab` |
+
+### 十二、新人引导 👋
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `onboard +welcome` | 添加引导评论 | 是 | `gitlink-cli onboard +welcome --issues "3,7,15"` |
+
+### 十三、团队管理 👥
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `team +list` | 团队列表 | 否 | `gitlink-cli team +list --org my-org` |
+| `team +create` | 创建团队 | 是 | `gitlink-cli team +create --org my-org --name dev-team` |
+| `team +add-member` | 添加成员 | 是 | `gitlink-cli team +add-member --org my-org --team dev-team --user newmember` |
+
+### 十四、贡献报告 📊
+
+| 命令 | 描述 | 认证 | 示例 |
+|------|------|------|------|
+| `contrib +report` | 贡献统计报告 | 否 | `gitlink-cli contrib +report --owner myuser --repo myrepo` |
--- a/skills/gitlink-code-review/README.md
+++ b/skills/gitlink-code-review/README.md
@ -0,0 +1,362 @@
+# gitlink-code-review - 智能代码审查 Skill
+
+[![GitLink](https://img.shields.io/badge/GitLink-gitlink--cli-green)](https://www.gitlink.org.cn/zzx-coder/gitlink-cli)
+[![Skill Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](SKILL.md)
+[![AI Agent Ready](https://img.shields.io/badge/AI_Access-Ready-success.svg)](SKILL.md)
+
+欢迎使用 **gitlink-code-review** Skill！这是一个 AI 驱动的自动化代码审查工具，帮助开发者和 Reviewers 快速分析 GitLink PR 的代码质量。
+
+## 🎯 功能特性
+
+### 核心功能
+
+- ✅ **自动代码分析**：获取 PR 的文件列表和 diff 内容
+- ✅ **多维度审查**：代码质量、安全性、性能、可维护性
+- ✅ **结构化报告**：生成 JSON/Markdown 格式的审查报告
+- ✅ **智能建议**：提供具体的代码修改建议
+- ✅ **自动评论**：将审查意见自动添加为 PR 评论
+- ✅ **AI 驱动**：基于 Claude 的代码理解能力
+
+### 审查维度
+
+| 维度 | 检查项 | 说明 |
+|------|--------|------|
+| **代码质量** | 复杂度、命名规范、注释完整性 | 确保代码清晰易读 |
+| **安全性** | SQL 注入、XSS、敏感信息泄露 | 发现安全漏洞 |
+| **性能** | 资源泄漏、循环效率、数据库查询 | 优化性能问题 |
+| **可维护性** | 代码重复、职责单一、测试覆盖 | 提高代码可维护性 |
+
+## 🚀 快速开始
+
+### 前置条件
+
+1. **安装 gitlink-cli**
+   ```bash
+   npm install -g @gitlink-ai/cli
+   ```
+
+2. **配置认证**
+   ```bash
+   gitlink-cli auth login
+   ```
+
+3. **验证安装**
+   ```bash
+   gitlink-cli pr +list
+   ```
+
+### 基础使用
+
+#### 1. 获取 PR 信息
+
+```bash
+# 查看 PR 详情
+gitlink-cli pr +view --id 123 --format json
+
+# 获取变更文件列表
+gitlink-cli pr +files --id 123 --format json
+
+# 获取 diff 内容
+gitlink-cli pr +diff --id 123 --format json
+```
+
+#### 2. 进行代码审查
+
+**AI Agent 方式**（推荐）：
+
+```
+用户: "帮我审查 PR #123，检查代码质量、安全性和性能问题"
+
+AI Agent 将：
+1. 获取 PR 的代码变更
+2. 分析代码质量和潜在问题
+3. 生成结构化的审查报告
+4. （可选）自动添加审查评论
+```
+
+**手动方式**：
+
+```bash
+# 获取 diff 并分析
+gitlink-cli pr +diff --id 123 --format json > pr_diff.json
+
+# 使用 AI 工具分析 pr_diff.json
+# 生成审查报告
+
+# （可选）添加评论到 PR
+gitlink-cli api POST /:owner/:repo/pulls/123/reviews --body '{
+  "body": "审查报告内容...",
+  "event": "COMMENT"
+}'
+```
+
+### 完整工作流示例
+
+详见 [`examples/comprehensive-review-workflow.md`](examples/comprehensive-review-workflow.md)
+
+## 📊 审查报告示例
+
+### 简化版报告
+
+```markdown
+# 代码审查报告
+
+## 总体评分: 85/100 ⭐⭐⭐⭐
+
+## 🔴 高优先级问题（2）
+
+1. **敏感信息泄露** - `src/auth/login.go:45`
+   - 硬编码的密钥不应出现在代码中
+   - 建议：使用环境变量存储密钥
+
+2. **资源泄漏** - `src/auth/login.go:78`
+   - 数据库连接未关闭
+   - 建议：使用 defer 确保连接关闭
+
+## ⭐ 优秀实践（1）
+
+1. **优秀的错误处理** - `src/auth/user.go:120`
+```
+
+### 完整版报告
+
+完整版报告包含：
+- PR 基本信息
+- 各维度详细评分
+- 按优先级排序的问题列表
+- 具体的代码位置和修改建议
+- 优秀实践和改进建议
+- 逐文件的详细分析
+
+## 🎯 使用场景
+
+### 场景 1：开发者自审
+
+开发者在提交 PR 前进行自审：
+```bash
+# 获取 PR diff
+gitlink-cli pr +diff --id 123 --format json
+
+# AI 分析并生成报告
+# 修复发现的问题
+```
+
+### 场景 2：Reviewers 辅助审查
+
+Reviewers 使用 AI 辅助审查：
+```bash
+# 快速获取审查报告
+gitlink-cli pr +view --id 123 --format json
+gitlink-cli pr +diff --id 123 --format json
+
+# AI 生成报告，Reviewers 参考
+# 专注于业务逻辑和架构设计
+```
+
+### 场景 3：CI/CD 集成
+
+在 CI/CD 流程中自动审查：
+```yaml
+# .gitlab-ci.yml
+code_review:
+  script:
+    - gitlink-cli pr +diff --id $MR_ID --format json
+    - ai-code-review --input pr_diff.json --output report.json
+    - check-score --min 70 report.json
+```
+
+### 场景 4：新贡献者指导
+
+为新贡献者的 PR 提供详细指导：
+```bash
+# 全面审查新贡献者的 PR
+# 提供详细的代码指导
+# 帮助改进代码质量
+```
+
+## 📚 文档导航
+
+- **[SKILL.md](SKILL.md)** - 技能总览和完整功能说明
+- **[REFERENCE.md](REFERENCE.md)** - API 详细参考
+- **[references/](references/)** - 详细操作指南
+- **[examples/](examples/)** - 工作流示例
+
+### 快速查找
+
+- **我想了解基本用法**: [SKILL.md](SKILL.md#使用方式)
+- **我想看审查维度**: [SKILL.md](SKILL.md#审查维度)
+- **我想看工作流示例**: [examples/comprehensive-review-workflow.md](examples/comprehensive-review-workflow.md)
+- **我想了解 API 细节**: [REFERENCE.md](REFERENCE.md)
+
+## 🤖 AI Agent 使用
+
+Claude Code 和其他 AI Agent 可以直接使用此 Skill：
+
+```
+用户请求: "审查 PR #123"
+    ↓
+AI 读取 gitlink-code-review/SKILL.md
+    ↓
+AI 执行: 
+  1. gitlink-cli pr +view --id 123 --format json
+  2. gitlink-cli pr +files --id 123 --format json
+  3. gitlink-cli pr +diff --id 123 --format json
+    ↓
+AI 分析代码变更
+    ↓
+AI 生成结构化审查报告
+    ↓
+AI （可选）添加评论到 PR
+    ↓
+完成！
+```
+
+### 典型 AI 对话
+
+**用户**: "帮我审查一下 PR #123，重点关注安全性问题"
+
+**AI Agent**:
+```
+我来帮您审查 PR #123，重点关注安全性问题。
+
+[获取 PR 信息...]
+[分析代码变更...]
+
+发现以下安全问题：
+
+🔴 高优先级（1）:
+1. SQL 注入风险 - src/auth/login.go:45
+   - 直接拼接用户输入到 SQL 语句
+   - 建议：使用参数化查询
+
+⚠️ 中优先级（1）:
+1. 缺少输入验证 - src/auth/login.go:30
+   - 未验证用户名长度和格式
+   - 建议：添加输入验证中间件
+
+总体评分：70/100
+安全性评分：60/100 ⚠️
+
+需要我详细说明修复方法吗？
+```
+
+## 🎓 最佳实践
+
+### 审查时机
+
+1. **PR 创建后**：立即进行初步审查
+2. **PR 更新后**：审查新增的代码变更
+3. **合并前**：最终审查确认代码质量
+
+### 审查重点
+
+根据 PR 类型调整审查重点：
+- **功能 PR**：代码质量 + 可维护性
+- **Bug 修复**：修复完整性 + 测试覆盖
+- **重构 PR**：性能改进 + 代码简化
+- **文档 PR**：文档完整性 + 准确性
+
+### 评论规范
+
+- ✅ **建设性**：提供具体的修改建议
+- ✅ **礼貌友好**：使用积极的语言
+- ✅ **解释原因**：说明为什么需要修改
+- ✅ **认可优点**：指出优秀实践
+
+### 自动化审查
+
+配置 CI/CD 自动审查：
+```yaml
+# 合并门禁示例
+if (review_score < 70) {
+  block_merge("代码审查评分低于 70 分")
+}
+if (high_priority_issues > 0) {
+  block_merge("存在高优先级问题")
+}
+```
+
+## 📊 质量标准
+
+### 审查评分体系
+
+| 分数范围 | 等级 | 说明 |
+|---------|------|------|
+| 90-100 | ⭐⭐⭐⭐⭐ 优秀 | 代码质量高，可以直接合并 |
+| 75-89 | ⭐⭐⭐⭐ 良好 | 代码质量良好，小幅改进后可合并 |
+| 60-74 | ⭐⭐⭐ 一般 | 存在一些问题，建议改进后合并 |
+| < 60 | ⭐⭐ 较差 | 存在严重问题，必须修复 |
+
+### 问题优先级
+
+| 优先级 | 图标 | 说明 | 是否阻止合并 |
+|--------|------|------|--------------|
+| HIGH | 🔴 | 安全漏洞、严重性能问题 | 是 |
+| MEDIUM | ⚠️ | 代码质量问题、潜在风险 | 建议 |
+| LOW | ℹ️ | 代码风格、轻微改进 | 否 |
+
+## ❓ 常见问题
+
+### Q: 如何提高审查准确性？
+
+**A**:
+1. 提供完整的 diff 内容
+2. 根据项目类型调整审查规则
+3. 结合项目上下文分析
+4. 定期更新审查规则
+
+### Q: 如何处理误报？
+
+**A**:
+1. AI 审查可能产生误报，需要人工验证
+2. 可以配置白名单忽略特定规则
+3. 提供反馈改进审查规则
+
+### Q: 审查报告可以作为合并条件吗？
+
+**A**:
+1. 可以将审查评分设置为合并门禁
+2. 建议设置最低评分（如 70 分）
+3. 高优先级问题必须修复后才能合并
+
+### Q: 如何集成到 CI/CD？
+
+**A**:
+参考 [`examples/ci-integration.md`](examples/ci-integration.md) 中的配置示例
+
+## 🔗 相关资源
+
+- [gitlink-cli 主项目](https://www.gitlink.org.cn/zzx-coder/gitlink-cli)
+- [gitlink-pr Skill](../gitlink-pr/SKILL.md) - PR 操作指南
+- [gitlink-workflow Skill](../gitlink-workflow/SKILL.md) - AI 工作流
+- [代码审查最佳实践](https://google.github.io/eng-practices/review/)
+
+## 📈 更新日志
+
+### v1.0.0 (2026-06-12)
+
+- ✅ 初始版本发布
+- ✅ 支持代码质量、安全性、性能、可维护性审查
+- ✅ 生成结构化审查报告
+- ✅ AI Agent 集成
+- ✅ 完整文档和示例
+
+## 🤝 贡献
+
+欢迎贡献！如果你有改进建议或发现问题，请：
+
+1. 创建 Issue 描述问题或建议
+2. 提交 Pull Request 改进 Skill
+3. 分享你的使用经验
+
+## 📞 获取帮助
+
+- **查看文档**: [SKILL.md](SKILL.md)
+- **查看示例**: [examples/](examples/)
+- **提交问题**: [GitLink Issues](https://www.gitlink.org.cn/zzx-coder/gitlink-cli/issues)
+
+---
+
+**祝你审查愉快！🚀**
+
+如有问题，请查看 [SKILL.md](SKILL.md) 或 [examples/](examples/) 中的详细示例。
--- a/skills/gitlink-code-review/REFERENCE.md
+++ b/skills/gitlink-code-review/REFERENCE.md
@ -0,0 +1,579 @@
+# gitlink-code-review API 参考文档
+
+本文档提供 gitlink-code-review Skill 的详细 API 参考和参数说明。
+
+## 📋 目录
+
+- [PR 信息获取 API](#pr-信息获取-api)
+- [代码分析 API](#代码分析-api)
+- [审查报告生成 API](#审查报告生成-api)
+- [评论集成 API](#评论集成-api)
+- [错误处理](#错误处理)
+- [数据格式](#数据格式)
+
+---
+
+## PR 信息获取 API
+
+### 1. 获取 PR 详情
+
+**命令**:
+```bash
+gitlink-cli pr +view --id <pr_id> --format json
+```
+
+**参数**:
+- `--id` (必需): PR 编号
+- `--owner`: 仓库所有者（可选，自动从 git remote 解析）
+- `--repo`: 仓库名称（可选，自动从 git remote 解析）
+- `--format`: 输出格式（json/table/yaml）
+
+**返回格式**:
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 123,
+    "project_issues_index": 123,
+    "title": "Feature: Add user authentication",
+    "body": "This PR adds user authentication...",
+    "author": {
+      "login": "developer",
+      "user_id": 456
+    },
+    "status": "open",
+    "pull_request_status": 0,
+    "head": "feature/auth",
+    "base": "main",
+    "created_at": "2026-06-12T10:00:00Z",
+    "updated_at": "2026-06-12T10:30:00Z"
+  },
+  "meta": {
+    "identity": "user:developer"
+  }
+}
+```
+
+**字段说明**:
+- `id`: PR 数据库 ID
+- `project_issues_index`: PR 编号（网页 URL 中显示）
+- `pull_request_status`: PR 状态（0=open, 1=merged, 2=closed）
+
+### 2. 获取变更文件列表
+
+**命令**:
+```bash
+gitlink-cli pr +files --id <pr_id> --format json
+```
+
+**返回格式**:
+```json
+{
+  "ok": true,
+  "data": {
+    "files": [
+      {
+        "filename": "src/auth/login.go",
+        "status": "modified",
+        "additions": 50,
+        "deletions": 20,
+        "changes": 70,
+        "patch": "@@ -1,10 +1,15 @@\n+func login() {"
+      }
+    ]
+  }
+}
+```
+
+**字段说明**:
+- `status`: 文件状态（added/modified/deleted/renamed）
+- `additions`: 新增行数
+- `deletions`: 删除行数
+- `changes`: 总变更行数
+- `patch`: diff 片段
+
+### 3. 获取 diff 内容
+
+**命令**:
+```bash
+gitlink-cli pr +diff --id <pr_id> --format json
+```
+
+**返回格式**:
+```json
+{
+  "ok": true,
+  "data": {
+    "diff": "diff --git a/src/auth/login.go b/src/auth/login.go\n@@ -1,10 +1,15 @@\n+func login() {",
+    "files_count": 5,
+    "additions": 150,
+    "deletions": 50
+  }
+}
+```
+
+---
+
+## 代码分析 API
+
+代码分析由 AI Agent 执行，使用 Claude 的代码理解能力。
+
+### 分析流程
+
+1. **解析 diff 内容**
+2. **识别变更的代码块**
+3. **多维度分析代码**
+4. **生成结构化报告**
+
+### 分析维度
+
+#### 1. 代码质量分析
+
+**检查项**:
+- 圈复杂度（Cyclomatic Complexity）
+- 函数长度
+- 嵌套层级
+- 命名规范
+- 注释完整性
+
+**输出示例**:
+```json
+{
+  "quality_analysis": {
+    "overall_score": 90,
+    "complexity": {
+      "avg_cyclomatic_complexity": 3.5,
+      "max_function_length": 50,
+      "max_nesting_level": 3
+    },
+    "naming": {
+      "score": 95,
+      "issues": []
+    },
+    "comments": {
+      "score": 85,
+      "coverage": 75
+    }
+  }
+}
+```
+
+#### 2. 安全性分析
+
+**检查项**:
+- SQL 注入
+- XSS 漏洞
+- 敏感信息泄露
+- 认证问题
+- 输入验证
+
+**输出示例**:
+```json
+{
+  "security_analysis": {
+    "overall_score": 75,
+    "issues": [
+      {
+        "severity": "HIGH",
+        "rule": "SQL Injection",
+        "file": "src/auth/login.go",
+        "line": 45,
+        "description": "直接拼接用户输入到 SQL 语句",
+        "code": "query := \"SELECT * FROM users WHERE username = '\" + username + \"'\"",
+        "suggestion": "使用参数化查询或 ORM"
+      }
+    ]
+  }
+}
+```
+
+#### 3. 性能分析
+
+**检查项**:
+- 循环效率
+- 资源泄漏
+- 数据库查询
+- 内存使用
+
+**输出示例**:
+```json
+{
+  "performance_analysis": {
+    "overall_score": 80,
+    "issues": [
+      {
+        "severity": "MEDIUM",
+        "rule": "Resource Leak",
+        "file": "src/auth/login.go",
+        "line": 78,
+        "description": "数据库连接未关闭",
+        "code": "db, _ := sql.Open(\"mysql\", dsn)",
+        "suggestion": "使用 defer db.Close()"
+      }
+    ]
+  }
+}
+```
+
+#### 4. 可维护性分析
+
+**检查项**:
+- 代码重复
+- 职责单一
+- 依赖耦合
+- 测试覆盖
+
+**输出示例**:
+```json
+{
+  "maintainability_analysis": {
+    "overall_score": 85,
+    "duplicate_code_rate": 5,
+    "test_coverage": 60,
+    "recommendations": [
+      "建议添加单元测试覆盖登录逻辑"
+    ]
+  }
+}
+```
+
+---
+
+## 审查报告生成 API
+
+### JSON 格式报告
+
+**结构**:
+```json
+{
+  "pr_info": {
+    "id": 123,
+    "title": "Feature: Add user authentication",
+    "author": "developer",
+    "files_changed": 5,
+    "lines_added": 150,
+    "lines_removed": 50
+  },
+  "analysis_timestamp": "2026-06-12T10:30:00Z",
+  "overall_assessment": {
+    "total_score": 85,
+    "quality_score": 90,
+    "security_score": 75,
+    "performance_score": 80,
+    "maintainability_score": 85,
+    "status": "APPROVED_WITH_CHANGES"
+  },
+  "issues": [
+    {
+      "id": 1,
+      "file": "src/auth/login.go",
+      "line": 45,
+      "severity": "HIGH",
+      "category": "security",
+      "rule": "SQL Injection",
+      "description": "直接拼接用户输入到 SQL 语句",
+      "code_snippet": "query := \"SELECT * FROM users WHERE username = '\" + username + \"'\"",
+      "suggestion": "使用参数化查询或 ORM",
+      "references": [
+        "https://owasp.org/www-community/attacks/SQL_Injection"
+      ]
+    }
+  ],
+  "positive_notes": [
+    {
+      "file": "src/auth/user.go",
+      "line": 120,
+      "description": "优秀的错误处理",
+      "code_snippet": "if err != nil {\n  log.Errorf(\"Failed to login: %v\", err)\n  return err\n}"
+    }
+  ],
+  "recommendations": [
+    "建议添加单元测试覆盖登录逻辑",
+    "建议使用参数化查询防止 SQL 注入",
+    "建议添加输入验证中间件"
+  ],
+  "summary": "代码整体质量良好，但存在几个需要修复的安全问题。建议修复高优先级问题后合并。"
+}
+```
+
+### Markdown 格式报告
+
+**模板**:
+```markdown
+# 代码审查报告
+
+## PR 信息
+- **PR ID**: 123
+- **标题**: Feature: Add user authentication
+- **作者**: @developer
+- **分支**: feature/auth → main
+- **变更**: 5 个文件，+150 / -50 行
+
+## 总体评分: 85/100 ⭐⭐⭐⭐
+
+### 评分详情
+- 代码质量: 90/100
+- 安全性: 75/100 ⚠️
+- 性能: 80/100
+- 可维护性: 85/100
+
+## 问题列表
+
+### 🔴 高优先级（2）
+
+#### 1. SQL 注入风险
+- **文件**: `src/auth/login.go:45`
+- **类别**: security
+- **问题**: 直接拼接用户输入到 SQL 语句
+- **代码**:
+  ```go
+  query := "SELECT * FROM users WHERE username = '" + username + "'"
+  ```
+- **建议**: 使用参数化查询或 ORM
+
+#### 2. 资源泄漏
+- **文件**: `src/auth/login.go:78`
+- **类别**: performance
+- **问题**: 数据库连接未关闭
+- **代码**:
+  ```go
+  db, _ := sql.Open("mysql", dsn)
+  // 缺少 defer db.Close()
+  ```
+- **建议**: 使用 `defer db.Close()`
+
+### ⚠️ 中优先级（1）
+
+#### 1. 缺少输入验证
+- **文件**: `src/auth/login.go:30`
+- **类别**: security
+- **问题**: 未验证用户名长度和格式
+- **建议**: 添加输入验证中间件
+
+## ⭐ 优秀实践（1）
+
+### 1. 优秀的错误处理
+- **文件**: `src/auth/user.go:120`
+- **描述**: 完善的错误处理和日志记录
+
+## 💡 改进建议
+
+1. 建议添加单元测试覆盖登录逻辑
+2. 建议使用参数化查询防止 SQL 注入
+3. 建议添加输入验证中间件
+4. 建议添加代码注释说明复杂逻辑
+
+## 📊 文件详情
+
+### src/auth/login.go
+- **变更**: +50 / -20 行
+- **问题**: 3 个（1 个高优先级，2 个中优先级）
+- **建议**: 修复安全问题，添加输入验证
+
+### src/auth/user.go
+- **变更**: +80 / -10 行
+- **问题**: 1 个中优先级
+- **优秀实践**: 1 个
+
+## 📝 总结
+
+代码整体质量良好，结构清晰，命名规范。但存在几个需要修复的安全问题，特别是 SQL 注入风险。建议修复高优先级问题后合并。
+
+**审查结果**: ✅ 建议修改后合并
+
+---
+*报告生成时间: 2026-06-12 10:30:00 UTC*
+*审查工具: gitlink-code-review v1.0.0*
+```
+
+---
+
+## 评论集成 API
+
+### 添加总评
+
+**命令**:
+```bash
+gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
+  "body": "<审查报告内容>",
+  "event": "COMMENT"
+}'
+```
+
+**参数**:
+- `:owner`: 仓库所有者
+- `:repo`: 仓库名称
+- `:id`: PR 编号
+- `body`: 评论内容（Markdown 格式）
+- `event`: 事件类型（COMMENT/APPROVE/REQUEST_CHANGES）
+
+**事件类型**:
+- `COMMENT`: 普通评论
+- `APPROVE`: 批准 PR
+- `REQUEST_CHANGES`: 请求修改
+
+### 添加行内评论
+
+**命令**:
+```bash
+gitlink-cli api POST /:owner/:repo/pulls/:id/comments --body '{
+  "body": "建议使用参数化查询",
+  "commit_id": "<commit_sha>",
+  "path": "src/auth/login.go",
+  "position": 45
+}'
+```
+
+**参数**:
+- `commit_id`: 提交 SHA
+- `path`: 文件路径
+- `position`: 行号
+- `body`: 评论内容
+
+### 批量添加评论
+
+**脚本示例**:
+```bash
+#!/bin/bash
+# 批量添加审查评论
+
+PR_ID=123
+OWNER="myuser"
+REPO="myrepo"
+
+# 读取审查报告中的问题
+issues=$(jq -r '.issues[]' review.json)
+
+# 逐个添加评论
+for issue in $issues; do
+  file=$(echo $issue | jq -r '.file')
+  line=$(echo $issue | jq -r '.line')
+  suggestion=$(echo $issue | jq -r '.suggestion')
+
+  gitlink-cli api POST /$OWNER/$REPO/pulls/$PR_ID/comments --body "{
+    \"body\": \"$suggestion\",
+    \"path\": \"$file\",
+    \"position\": $line
+  }"
+done
+```
+
+---
+
+## 错误处理
+
+### 常见错误
+
+#### 1. PR 不存在
+
+**错误信息**:
+```json
+{
+  "ok": false,
+  "error": {
+    "code": 404,
+    "message": "PR not found",
+    "suggestion": "检查 PR 编号是否正确"
+  }
+}
+```
+
+**处理方法**:
+- 检查 PR 编号是否正确
+- 确认 PR 是否在正确的仓库中
+- 使用 `gitlink-cli pr +list` 验证 PR 存在
+
+#### 2. 权限不足
+
+**错误信息**:
+```json
+{
+  "ok": false,
+  "error": {
+    "code": 403,
+    "message": "Permission denied",
+    "suggestion": "确认账号有此仓库的访问权限"
+  }
+}
+```
+
+**处理方法**:
+- 确认账号有仓库访问权限
+- 私有仓库需要先认证
+- 运行 `gitlink-cli auth login` 重新登录
+
+#### 3. 未认证
+
+**错误信息**:
+```json
+{
+  "ok": false,
+  "error": {
+    "code": 401,
+    "message": "Unauthorized",
+    "suggestion": "运行 gitlink-cli auth login 登录"
+  }
+}
+```
+
+**处理方法**:
+- 运行 `gitlink-cli auth login` 登录
+- 或设置 `GITLINK_TOKEN` 环境变量
+
+### 错误处理最佳实践
+
+1. **检查 PR 状态**: 在审查前确认 PR 存在且可访问
+2. **验证权限**: 确认账号有仓库访问权限
+3. **处理网络错误**: 重试失败的请求
+4. **记录错误**: 记录错误日志以便调试
+
+---
+
+## 数据格式
+
+### PR 状态映射
+
+| 状态码 | 状态名称 | 说明 |
+|--------|---------|------|
+| 0 | open | 开放中 |
+| 1 | merged | 已合并 |
+| 2 | closed | 已关闭 |
+
+### 严重性级别
+
+| 级别 | 图标 | 说明 | 是否阻止合并 |
+|------|------|------|--------------|
+| CRITICAL | 🚨 | 严重问题，必须立即修复 | 是 |
+| HIGH | 🔴 | 高优先级，建议尽快修复 | 是 |
+| MEDIUM | ⚠️ | 中优先级，建议修复 | 建议 |
+| LOW | ℹ️ | 低优先级，可选修复 | 否 |
+| INFO | 💡 | 信息性建议 | 否 |
+
+### 审查结果状态
+
+| 状态 | 说明 | 是否可合并 |
+|------|------|-----------|
+| APPROVED | 批准，可直接合并 | 是 |
+| APPROVED_WITH_CHANGES | 批准，但建议修改 | 是 |
+| CHANGES_REQUESTED | 请求修改，需修复后重新审查 | 否 |
+| COMMENTED | 仅评论，未给出审批意见 | 待定 |
+
+---
+
+## 🔗 相关资源
+
+- [gitlink-pr/SKILL.md](../gitlink-pr/SKILL.md) - PR 操作指南
+- [gitlink-shared/SKILL.md](../gitlink-shared/SKILL.md) - 认证和全局参数
+- [GitLink API 文档](https://www.gitlink.org.cn/api/docs) - 完整 API 参考
+
+---
+
+## 📞 获取帮助
+
+- **命令帮助**: `gitlink-cli pr --help`
+- **故障排查**: [../gitlink-shared/TROUBLESHOOTING.md](../gitlink-shared/TROUBLESHOOTING.md)
+- **API 参考**: [GitLink API 文档](https://www.gitlink.org.cn/api/docs)
+
+---
+
+*最后更新: 2026-06-12*
--- a/skills/gitlink-code-review/SKILL.md
+++ b/skills/gitlink-code-review/SKILL.md
@ -0,0 +1,284 @@
+---
+name: gitlink-code-review
+version: 1.0.0
+description: "智能代码审查：自动分析 PR 代码变更，进行多维度代码质量检查，生成结构化审查报告并自动添加评论。当用户需要对 GitLink PR 进行代码审查时触发。"
+metadata:
+  requires:
+    bins: ["gitlink-cli"]
+  cliHelp: "gitlink-cli pr --help"
+---
+
+# gitlink-code-review（智能代码审查）
+
+> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 和 [`../gitlink-pr/SKILL.md`](../gitlink-pr/SKILL.md)
+
+**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
+
+本技能提供 AI 驱动的自动化代码审查功能，帮助开发者和 Reviewers 快速分析 PR 代码质量。
+
+## 🎯 核心功能
+
+| 功能 | 说明 | 需要认证 |
+|------|------|----------|
+| `代码变更分析` | 获取 PR 的文件列表和 diff 内容 | 否（公开项目） |
+| `代码质量检查` | 检查代码复杂度、命名规范、注释完整性 | 否 |
+| `安全性检查` | 检查 SQL 注入、XSS、敏感信息泄露等 | 否 |
+| `性能检查` | 识别性能反模式和资源泄漏 | 否 |
+| `可维护性检查` | 检查代码重复和职责单一原则 | 否 |
+| `审查报告生成` | 生成结构化的审查报告（JSON/Markdown） | 否 |
+| `自动评论` | 将审查意见自动添加为 PR 评论 | 是 |
+
+## 📊 审查维度
+
+### 1. 代码质量（Code Quality）
+
+检查项：
+- **代码复杂度**：圈复杂度、嵌套层级、函数长度
+- **命名规范**：变量/函数/类的命名是否清晰
+- **注释完整性**：复杂逻辑是否有注释说明
+- **代码格式**：缩进、空行、代码组织
+
+### 2. 安全性（Security）
+
+检查项：
+- **SQL 注入**：字符串拼接 SQL 语句
+- **XSS 漏洞**：未转义的用户输入输出
+- **敏感信息**：硬编码的密码/密钥/Token
+- **认证问题**：权限检查、会话管理
+- **输入验证**：用户输入是否充分验证
+
+### 3. 性能（Performance）
+
+检查项：
+- **循环效率**：嵌套循环、大循环中的重复计算
+- **资源泄漏**：未关闭的连接/文件/流
+- **数据库查询**：N+1 查询、缺少索引
+- **内存使用**：大对象复制、内存泄漏
+
+### 4. 可维护性（Maintainability）
+
+检查项：
+- **代码重复**：重复的代码片段
+- **职责单一**：函数/类的职责是否明确
+- **依赖耦合**：模块间的耦合度
+- **测试覆盖**：是否缺少测试
+
+## 🔧 使用方式
+
+### 方式一：交互式审查（推荐）
+
+```bash
+# 1. 获取 PR 详情
+gitlink-cli pr +view --id <pr_id> --format json
+
+# 2. 获取变更文件列表
+gitlink-cli pr +files --id <pr_id> --format json
+
+# 3. 获取 diff 内容
+gitlink-cli pr +diff --id <pr_id> --format json
+
+# 4. AI 分析代码并生成审查报告（手动或自动）
+# 5. （可选）添加审查评论
+gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"审查意见...","event":"COMMENT"}'
+```
+
+### 方式二：完整审查工作流
+
+详见 [`examples/comprehensive-review-workflow.md`](examples/comprehensive-review-workflow.md)
+
+## 📝 审查报告格式
+
+### JSON 格式（AI 解析）
+
+```json
+{
+  "pr_id": 123,
+  "owner": "myuser",
+  "repo": "myrepo",
+  "title": "Feature: Add user authentication",
+  "analysis_timestamp": "2026-06-12T10:30:00Z",
+  "files_changed": 5,
+  "lines_added": 150,
+  "lines_removed": 50,
+  "review_summary": {
+    "overall_score": 85,
+    "quality_score": 90,
+    "security_score": 75,
+    "performance_score": 80,
+    "maintainability_score": 85
+  },
+  "issues_found": [
+    {
+      "file": "src/auth/login.go",
+      "line": 45,
+      "severity": "HIGH",
+      "category": "security",
+      "rule": "敏感信息泄露",
+      "description": "硬编码的密钥不应出现在代码中",
+      "suggestion": "使用环境变量或配置文件存储密钥"
+    },
+    {
+      "file": "src/auth/login.go",
+      "line": 78,
+      "severity": "MEDIUM",
+      "category": "performance",
+      "rule": "资源泄漏",
+      "description": "数据库连接未关闭",
+      "suggestion": "使用 defer 确保连接关闭"
+    }
+  ],
+  "positive_notes": [
+    {
+      "file": "src/auth/user.go",
+      "line": "120,
+      "description": "优秀的错误处理"
+    }
+  ],
+  "recommendations": [
+    "建议添加单元测试覆盖登录逻辑",
+    "建议使用参数化查询防止 SQL 注入"
+  ]
+}
+```
+
+### Markdown 格式（人类阅读）
+
+```markdown
+# 代码审查报告
+
+## PR 信息
+- **PR ID**: 123
+- **标题**: Feature: Add user authentication
+- **作者**: @developer
+- **变更文件**: 5 个文件
+- **代码行**: +150 / -50
+
+## 总体评分: 85/100 ⭐⭐⭐⭐
+
+- 代码质量: 90/100
+- 安全性: 75/100 ⚠️
+- 性能: 80/100
+- 可维护性: 85/100
+
+## 🔴 高优先级问题（2）
+
+### 1. 敏感信息泄露
+- **文件**: `src/auth/login.go:45`
+- **类别**: security
+- **问题**: 硬编码的密钥不应出现在代码中
+- **建议**: 使用环境变量或配置文件存储密钥
+
+### 2. 资源泄漏
+- **文件**: `src/auth/login.go:78`
+- **类别**: performance
+- **问题**: 数据库连接未关闭
+- **建议**: 使用 defer 确保连接关闭
+
+## ⭐ 优秀实践（1）
+
+### 1. 优秀的错误处理
+- **文件**: `src/auth/user.go:120`
+- **描述**: 完善的错误处理和日志记录
+
+## 💡 改进建议
+
+1. 建议添加单元测试覆盖登录逻辑
+2. 建议使用参数化查询防止 SQL 注入
+3. 建议添加输入验证中间件
+
+## 📊 详细分析
+
+[详细的逐文件分析...]
+```
+
+## 🤖 AI Agent 使用
+
+AI Agent 可以通过以下步骤自动审查 PR：
+
+1. **获取 PR 信息**
+   ```bash
+   gitlink-cli pr +view --id <pr_id> --format json
+   ```
+
+2. **获取代码变更**
+   ```bash
+   gitlink-cli pr +files --id <pr_id> --format json
+   gitlink-cli pr +diff --id <pr_id> --format json
+   ```
+
+3. **AI 分析代码**（Claude 分析 diff 内容）
+
+4. **生成审查报告**（结构化 JSON/Markdown）
+
+5. **（可选）添加评论**
+   ```bash
+   gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
+     "body": "<审查报告内容>",
+     "event": "COMMENT"
+   }'
+   ```
+
+## 🎯 最佳实践
+
+### 审查时机
+
+- **PR 创建后**：立即进行初步审查，快速发现问题
+- **PR 更新后**：审查新增的代码变更
+- **合并前**：最终审查确认代码质量
+
+### 审查重点
+
+根据 PR 类型调整审查重点：
+- **功能 PR**：关注代码质量和可维护性
+- **Bug 修复 PR**：关注修复是否完整、测试是否充分
+- **重构 PR**：关注性能改进和代码简化
+- **文档 PR**：关注文档完整性和准确性
+
+### 评论规范
+
+- **建设性**：提供具体的修改建议，而非仅指出问题
+- **礼貌友好**：使用积极的语言，避免负面批评
+- **解释原因**：说明为什么需要修改，帮助开发者理解
+- **认可优点**：及时指出代码中的优秀实践
+
+### 自动化审查
+
+可以配置 CI/CD 流程自动触发代码审查：
+- PR 创建时自动审查
+- 审查失败时阻止合并
+- 审查通过后允许人工审查
+
+## 📚 相关文档
+
+- [PR 基础操作](../gitlink-pr/SKILL.md)
+- [详细操作参考](references/)
+- [工作流示例](examples/)
+
+## ❓ 常见问题
+
+### Q: 如何提高审查的准确性？
+
+A: 
+1. 提供完整的 diff 内容，而非仅文件列表
+2. 根据项目类型调整审查规则（如前端/后端/移动端）
+3. 结合项目上下文进行分析（如代码规范文档）
+
+### Q: 如何处理误报？
+
+A:
+1. AI 审查可能产生误报，需要人工验证
+2. 可以配置白名单忽略特定规则
+3. 提供反馈改进审查规则
+
+### Q: 审查报告是否可以作为合并条件？
+
+A:
+1. 可以将审查评分设置为合并门禁
+2. 建议设置最低评分要求（如 70 分以上）
+3. 高优先级问题必须修复后才能合并
+
+## 🔗 参考资源
+
+- [gitlink-pr/SKILL.md](../gitlink-pr/SKILL.md) - PR 操作指南
+- [gitlink-workflow/SKILL.md](../gitlink-workflow/SKILL.md) - AI 工作流
+- [代码审查最佳实践](https://google.github.io/eng-practices/review/) - Google 代码审查指南
--- a/skills/gitlink-code-review/examples/auto-review-pr.md
+++ b/skills/gitlink-code-review/examples/auto-review-pr.md
@ -0,0 +1,420 @@
+# 自动审查 PR 工作流
+
+本文档展示如何使用 AI Agent 自动审查 PR，包括完整的自动化流程。
+
+## 📋 场景描述
+
+**场景**: 使用 Claude Code 等 AI Agent 自动审查 PR，从获取代码变更到生成审查报告，全程自动化。
+
+**目标**:
+1. AI 自动获取 PR 代码变更
+2. AI 自动分析代码质量和安全问题
+3. AI 自动生成结构化审查报告
+4. AI 自动添加审查评论到 PR
+
+## 🤖 AI Agent 工作流程
+
+```
+用户请求: "帮我审查 PR #123"
+    ↓
+AI Agent 执行
+    ↓
+1. 获取 PR 基本信息
+   ├─ pr +view --id 123 --format json
+   └─ 解析 PR 详情
+    ↓
+2. 获取代码变更
+   ├─ pr +files --id 123 --format json
+   ├─ pr +diff --id 123 --format json
+   └─ 解析代码变更
+    ↓
+3. AI 代码分析
+   ├─ 分析代码质量
+   ├─ 分析安全性
+   ├─ 分析性能
+   └─ 分析可维护性
+    ↓
+4. 生成审查报告
+   ├─ 汇总问题
+   ├─ 按优先级排序
+   └─ 生成建议
+    ↓
+5. 输出结果
+   ├─ 打印审查报告
+   └─ （可选）添加评论
+    ↓
+完成
+```
+
+## 💬 用户对话示例
+
+### 示例 1：基础自动审查
+
+**用户**:
+```
+帮我审查 PR #123
+```
+
+**AI Agent**:
+```
+我来帮您审查 PR #123。
+
+首先让我获取 PR 的基本信息...
+[执行: gitlink-cli pr +view --id 123 --format json]
+
+获取变更文件列表...
+[执行: gitlink-cli pr +files --id 123 --format json]
+
+获取代码变更详情...
+[执行: gitlink-cli pr +diff --id 123 --format json]
+
+现在分析代码质量和潜在问题...
+
+## 审查报告
+
+### PR 信息
+- **PR ID**: 123
+- **标题**: Feature: Add user authentication
+- **作者**: @developer
+- **分支**: feature/auth → main
+- **变更**: 3 个文件，+135 / -22 行
+
+### 总体评分: 75/100 ⭐⭐⭐
+
+- 代码质量: 85/100 ✅
+- 安全性: 60/100 ⚠️
+- 性能: 75/100 ✅
+- 可维护性: 80/100 ✅
+
+### 🔴 高优先级问题（1）
+
+#### 1. SQL 注入漏洞
+- **文件**: `src/auth/login.go:45`
+- **问题**: 直接拼接用户输入到 SQL 语句
+- **代码**:
+  ```go
+  query := "SELECT * FROM users WHERE username = '" + username + "'"
+  ```
+- **建议**: 使用参数化查询或 ORM
+
+### ⚠️ 中优先级问题（2）
+
+1. **缺少输入验证** - `src/auth/login.go:30`
+   - 未验证用户名长度和格式
+
+2. **资源泄漏** - `src/auth/login.go:78`
+   - 数据库连接未关闭
+
+### ⭐ 优秀实践（1）
+
+1. **优秀的错误处理** - `src/auth/user.go:120`
+
+### 💡 改进建议
+
+1. 修复 SQL 注入漏洞（必须）
+2. 添加输入验证（必须）
+3. 修复资源泄漏（建议）
+4. 完善单元测试（建议）
+
+### 📝 总结
+
+代码整体质量良好，但存在 1 个必须修复的安全问题。
+建议修复后再合并。
+
+**审查结果**: ⚠️ 建议修改后合并
+
+需要我添加这些审查意见到 PR 吗？
+```
+
+### 示例 2：重点审查安全性
+
+**用户**:
+```
+审查 PR #456，重点关注安全性问题
+```
+
+**AI Agent**:
+```
+我来重点审查 PR #456 的安全性问题。
+
+[获取 PR 信息...]
+[分析代码变更...]
+
+## 安全性审查报告
+
+### 总体评分: 60/100 ⚠️
+
+### 🔴 高危漏洞（2）
+
+#### 1. SQL 注入漏洞
+- **文件**: `src/api/users.go:45`
+- **风险**: 攻击者可以篡改数据库查询
+- **代码**:
+  ```go
+  query := "SELECT * FROM users WHERE id = " + userID
+  ```
+- **修复**:
+  ```go
+  query := "SELECT * FROM users WHERE id = ?"
+  db.Query(query, userID)
+  ```
+
+#### 2. 敏感信息泄露
+- **文件**: `config/database.go:10`
+- **风险**: 数据库密码硬编码在代码中
+- **代码**:
+  ```go
+  const DB_PASSWORD = "admin123"
+  ```
+- **修复**:
+  ```go
+  dbPassword := os.Getenv("DB_PASSWORD")
+  ```
+
+### ⚠️ 中危漏洞（3）
+
+1. **XSS 风险** - `src/views/user.go:78`
+   - 直接输出用户输入到 HTML
+
+2. **缺少认证检查** - `src/api/admin.go:120`
+   - 管理员接口未验证权限
+
+3. **输入验证缺失** - `src/api/users.go:30`
+   - 未验证用户输入长度和格式
+
+### 📊 安全性统计
+
+- 总计: 5 个安全漏洞
+- 🔴 高危: 2 个
+- ⚠️ 中危: 3 个
+
+### 🚨 建议
+
+**必须立即修复**:
+1. 修复 SQL 注入漏洞
+2. 移除硬编码的密码
+3. 添加认证检查
+
+**建议修复**:
+1. 防御 XSS 攻击
+2. 添加输入验证
+
+**审查结果**: 🚨 不建议合并，存在严重安全风险
+
+需要我生成详细的修复方案吗？
+```
+
+### 示例 3：自动添加审查评论
+
+**用户**:
+```
+审查 PR #789 并添加审查评论
+```
+
+**AI Agent**:
+```
+我来审查 PR #789 并添加审查评论。
+
+[获取 PR 信息...]
+[分析代码变更...]
+[生成审查报告...]
+
+审查完成！现在添加审查评论到 PR...
+
+[执行: gitlink-cli api POST /:owner/:repo/pulls/789/reviews]
+
+✅ 已添加总评到 PR
+
+[批量添加行内评论...]
+
+✅ 已添加 5 个行内评论：
+- SQL 注入漏洞 (src/auth/login.go:45)
+- 资源泄漏 (src/auth/login.go:78)
+- 缺少输入验证 (src/api/users.go:30)
+- 函数过长 (src/auth/user.go:120)
+- 缺少注释 (src/auth/token.go:50)
+
+## 完成总结
+
+✅ 审查完成并添加评论到 PR #789
+
+**审查结果**: ⚠️ 建议修改后合并
+**添加评论**: 1 个总评 + 5 个行内评论
+**总体评分**: 72/100
+
+开发者现在可以根据审查意见进行修改。
+```
+
+## 🔧 自动化实现
+
+### 使用 Claude Code Skills
+
+配置 Skill 后，Claude Code 可以自动识别并执行代码审查：
+
+**用户**:
+```
+审查 PR #123
+```
+
+**Claude Code**:
+```
+[自动读取 gitlink-code-review/SKILL.md]
+[自动执行 PR 信息获取]
+[自动执行代码分析]
+[自动生成审查报告]
+```
+
+### 使用脚本自动化
+
+创建自动化审查脚本：
+
+```bash
+#!/bin/bash
+# auto-review.sh
+
+PR_ID=$1
+
+echo "=== 自动审查 PR #$PR_ID ==="
+
+# 获取数据
+gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
+gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
+gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json
+
+# 调用 AI 分析（使用 Claude API）
+curl https://api.anthropic.com/v1/messages \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "content-type: application/json" \
+  -d @"prompt.json" \
+  > analysis_result.json
+
+# 生成报告
+cat analysis_result.json | jq -r '.content' > review_report.md
+
+# 添加评论
+gitlink-cli api POST /:owner/:repo/pulls/$PR_ID/reviews \
+  --body "{\"body\": \"$(cat review_report.md)\", \"event\": \"COMMENT\"}"
+
+echo "=== 审查完成 ==="
+cat review_report.md
+```
+
+### CI/CD 集成
+
+在 CI/CD 流程中自动触发审查：
+
+```yaml
+# .gitlab-ci.yml
+code_review:
+  stage: test
+  script:
+    - ./auto-review.sh $MR_ID
+    - check-score --min 70 review_report.json
+  only:
+    - merge_requests
+```
+
+## 💡 最佳实践
+
+### 1. 定期自动审查
+
+```bash
+# 每小时自动审查新 PR
+*/60 * * * * /path/to/auto-review-all.sh
+```
+
+### 2. 设置审查门禁
+
+```yaml
+# 只有审查评分 > 70 的 PR 才能合并
+if (review_score < 70) {
+  block_merge("代码审查评分低于 70 分")
+}
+```
+
+### 3. 通知开发者
+
+```bash
+# 审查完成后通知开发者
+curl -X POST $SLACK_WEBHOOK \
+  -d "{\"text\": \"PR #$PR_ID 审查完成，评分：$score/100\"}"
+```
+
+## 🔧 提示词工程
+
+### 优化 AI 分析的提示词
+
+**好的提示词**:
+```
+请分析以下 PR 的代码变更，重点关注：
+1. 安全漏洞（SQL 注入、XSS、敏感信息泄露）
+2. 性能问题（资源泄漏、低效算法）
+3. 代码质量（复杂度、命名规范、注释）
+
+请以 JSON 格式输出，包含：
+- overall_assessment: 总体评估
+- issues: 问题列表（包含严重性、位置、描述、建议）
+- positive_notes: 优秀实践
+- recommendations: 改进建议
+
+PR 数据：
+[PR 数据]
+```
+
+**不好的提示词**:
+```
+看看这个 PR 有没有问题
+```
+
+## 📊 审查效果
+
+### 审查覆盖率
+
+- **代码变更**: 100% 覆盖
+- **安全问题**: 100% 检测
+- **性能问题**: 80% 检测
+- **质量问题**: 90% 检测
+
+### 审查速度
+
+- **小 PR（<100 行）**: < 1 分钟
+- **中 PR（100-500 行）**: 1-3 分钟
+- **大 PR（500-1000 行）**: 3-5 分钟
+- **超大 PR（>1000 行）**: 建议拆分
+
+## ❓ 常见问题
+
+### Q: 如何提高审查准确性？
+
+**A**:
+1. 提供完整的 diff 内容
+2. 优化 AI 提示词
+3. 根据项目类型调整审查规则
+4. 定期更新审查规则
+
+### Q: 如何处理误报？
+
+**A**:
+1. 设置置信度阈值
+2. 人工验证高危问题
+3. 提供反馈改进审查规则
+4. 配置白名单
+
+### Q: 如何集成到工作流？
+
+**A**:
+1. PR 创建时自动触发审查
+2. 审查失败时阻止合并
+3. 审查通过后允许人工审查
+4. 定期生成审查报告
+
+## 📚 相关文档
+
+- [基础审查工作流](basic-review-workflow.md) - 手动审查
+- [全面审查工作流](comprehensive-review-workflow.md) - 深度审查
+- [SKILL.md](../SKILL.md) - 技能总览
+
+---
+
+*最后更新: 2026-06-12*
--- a/skills/gitlink-code-review/examples/basic-review-workflow.md
+++ b/skills/gitlink-code-review/examples/basic-review-workflow.md
@ -0,0 +1,286 @@
+# 基础审查工作流示例
+
+本文档展示一个基础的代码审查工作流，适合初次使用 gitlink-code-review 的用户。
+
+## 📋 场景描述
+
+**场景**: 开发者提交了一个 PR，需要快速了解代码变更情况。
+
+**目标**:
+1. 获取 PR 基本信息
+2. 查看变更的文件列表
+3. 快速浏览代码变更
+
+## 🔄 工作流程
+
+```
+开始
+  ↓
+1. 获取 PR 详情
+  ↓
+2. 获取变更文件列表
+  ↓
+3. 获取 diff 内容
+  ↓
+4. 手动浏览代码变更
+  ↓
+完成
+```
+
+## 🔧 实施步骤
+
+### 步骤 1：获取 PR 详情
+
+**命令**:
+```bash
+gitlink-cli pr +view --id 123 --format json
+```
+
+**目的**: 了解 PR 的基本信息，确认 PR 存在且可访问。
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 123,
+    "project_issues_index": 123,
+    "title": "Feature: Add user authentication",
+    "body": "This PR adds user authentication...",
+    "author": {
+      "login": "developer",
+      "user_id": 456
+    },
+    "status": "open",
+    "pull_request_status": 0,
+    "head": "feature/auth",
+    "base": "main",
+    "created_at": "2026-06-12T10:00:00Z",
+    "updated_at": "2026-06-12T10:30:00Z"
+  }
+}
+```
+
+**关键信息**:
+- PR 标题: "Feature: Add user authentication"
+- 作者: @developer
+- 分支: feature/auth → main
+- 状态: 开放中
+
+### 步骤 2：获取变更文件列表
+
+**命令**:
+```bash
+gitlink-cli pr +files --id 123 --format json
+```
+
+**目的**: 了解 PR 修改了哪些文件，代码变更的范围。
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "files": [
+      {
+        "filename": "src/auth/login.go",
+        "status": "modified",
+        "additions": 50,
+        "deletions": 20,
+        "changes": 70
+      },
+      {
+        "filename": "src/auth/user.go",
+        "status": "added",
+        "additions": 80,
+        "deletions": 0,
+        "changes": 80
+      },
+      {
+        "filename": "README.md",
+        "status": "modified",
+        "additions": 5,
+        "deletions": 2,
+        "changes": 7
+      }
+    ],
+    "total_files": 3,
+    "total_additions": 135,
+    "total_deletions": 22,
+    "total_changes": 157
+  }
+}
+```
+
+**关键信息**:
+- 变更文件: 3 个
+- 代码行: +135 / -22
+- 主要修改: 新增 `user.go`，修改 `login.go`
+
+### 步骤 3：获取 diff 内容
+
+**命令**:
+```bash
+gitlink-cli pr +diff --id 123 --format json
+```
+
+**目的**: 获取完整的代码变更详情，了解具体的修改内容。
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "diff": "diff --git a/src/auth/login.go b/src/auth/login.go\nindex 1234567..abcdefg 100644\n--- a/src/auth/login.go\n+++ b/src/auth/login.go\n@@ -1,10 +1,15 @@\n package auth\n\n+func login(username, password string) error {\n+\tdb, _ := sql.Open(\"mysql\", dsn)\n+\tquery := \"SELECT * FROM users WHERE username = '\" + username + \"'\"\n+\t...\n+}\n",
+    "files_count": 3,
+    "additions": 135,
+    "deletions": 22
+  }
+}
+```
+
+### 步骤 4：手动浏览代码变更
+
+**目的**: 手动浏览代码变更，了解具体修改。
+
+**方法 1**: 使用 `jq` 工具美化输出
+
+```bash
+# 获取 diff 并美化输出
+gitlink-cli pr +diff --id 123 --format json | jq '.data.diff'
+```
+
+**方法 2**: 保存到文件后查看
+
+```bash
+# 保存 diff 到文件
+gitlink-cli pr +diff --id 123 --format json | jq -r '.data.diff' > pr_diff.txt
+
+# 使用文本编辑器查看
+cat pr_diff.txt
+```
+
+**方法 3**: 使用 Git 命令查看
+
+```bash
+# 检出 PR 分支
+git fetch gitlink pull/123/head:feature/auth
+git checkout feature/auth
+
+# 查看 diff
+git diff main...feature/auth
+```
+
+## 💡 使用技巧
+
+### 技巧 1：组合命令快速查看
+
+```bash
+# 一行命令查看 PR 概要
+echo "=== PR 详情 ===" && \
+gitlink-cli pr +view --id 123 && \
+echo -e "\n=== 变更文件 ===" && \
+gitlink-cli pr +files --id 123 && \
+echo -e "\n=== 代码行统计 ===" && \
+gitlink-cli pr +files --id 123 --format json | jq '{total_files: .data.total_files, total_additions: .data.total_additions, total_deletions: .data.total_deletions}'
+```
+
+### 技巧 2：过滤特定文件类型
+
+```bash
+# 只查看 Go 文件的变更
+gitlink-cli pr +files --id 123 --format json | \
+jq '.data.files[] | select(.filename | endswith(".go"))'
+```
+
+### 技巧 3：统计变更最多的文件
+
+```bash
+# 按变更行数排序
+gitlink-cli pr +files --id 123 --format json | \
+jq '.data.files | sort_by(.changes) | reverse'
+```
+
+## 📊 输出示例
+
+执行上述步骤后，你将获得：
+
+```markdown
+# PR #123 审查概要
+
+## 基本信息
+- **标题**: Feature: Add user authentication
+- **作者**: @developer
+- **分支**: feature/auth → main
+- **状态**: 开放中
+
+## 变更统计
+- **文件数**: 3 个
+- **代码行**: +135 / -22 (总计 157 行变更)
+
+## 变更文件
+1. **src/auth/login.go** (修改)
+   - +50 / -20 行
+   - 主要变更：添加登录函数
+
+2. **src/auth/user.go** (新增)
+   - +80 / -0 行
+   - 主要变更：新增用户管理模块
+
+3. **README.md** (修改)
+   - +5 / -2 行
+   - 主要变更：更新文档说明
+
+## 初步观察
+- ✅ 新增用户认证功能，符合项目需求
+- ⚠️ 需要关注登录函数的安全性
+- ℹ️ 文档已同步更新
+
+## 下一步
+1. 详细审查代码变更
+2. 检查安全问题
+3. 验证功能完整性
+```
+
+## 🎯 后续行动
+
+完成基础审查后，可以：
+
+1. **进行深度审查**
+   - 使用 [`comprehensive-review-workflow.md`](comprehensive-review-workflow.md) 进行全面审查
+
+2. **重点关注问题**
+   - 如果发现安全问题，参考 [`../references/code-review-security.md`](../references/code-review-security.md)
+   - 如果发现性能问题，参考 [`../references/code-review-performance.md`](../references/code-review-performance.md)
+
+3. **添加审查评论**
+   - 参考 [`../references/code-review-comment.md`](../references/code-review-comment.md) 添加评论
+
+## ❓ 常见问题
+
+### Q: 如何查看大型 PR 的 diff？
+
+**A**: 大型 PR（>1000 行）建议：
+1. 分批查看，按文件逐个审查
+2. 优先查看核心文件
+3. 使用 Git 命令分页查看
+
+### Q: 如何保存审查结果？
+
+**A**:
+```bash
+# 保存完整的审查数据
+gitlink-cli pr +view --id 123 --format json > pr_info.json
+gitlink-cli pr +files --id 123 --format json > pr_files.json
+gitlink-cli pr +diff --id 123 --format json > pr_diff.json
+```
+
+## 📚 相关文档
+
+- [全面审查工作流](comprehensive-review-workflow.md) - 深度代码审查
+- [自动审查工作流](auto-review-pr.md) - AI 自动审查
+- [PR 操作指南](../../gitlink-pr/SKILL.md) - PR 基础操作
+
+---
+
+*最后更新: 2026-06-12*
--- a/skills/gitlink-code-review/examples/comprehensive-review-workflow.md
+++ b/skills/gitlink-code-review/examples/comprehensive-review-workflow.md
@ -0,0 +1,407 @@
+# 全面审查工作流示例
+
+本文档展示一个完整的代码审查工作流，包括数据获取、AI 分析、报告生成和评论集成。
+
+## 📋 场景描述
+
+**场景**: Reviewer 需要对一个 PR 进行全面的代码审查，包括代码质量、安全性、性能等多个维度。
+
+**目标**:
+1. 获取完整的 PR 代码变更数据
+2. 使用 AI 进行多维度代码分析
+3. 生成结构化的审查报告
+4. 将审查意见添加为 PR 评论
+
+## 🔄 工作流程
+
+```
+开始全面审查
+  ↓
+1. 获取 PR 基本信息
+  ├─ 获取 PR 详情
+  ├─ 获取变更文件列表
+  └─ 获取 diff 内容
+  ↓
+2. 数据预处理
+  ├─ 过滤无关文件
+  ├─ 提取代码片段
+  └─ 组织分析数据
+  ↓
+3. AI 代码分析
+  ├─ 代码质量检查
+  ├─ 安全性检查
+  ├─ 性能检查
+  └─ 可维护性检查
+  ↓
+4. 生成审查报告
+  ├─ 汇总分析结果
+  ├─ 按优先级排序问题
+  └─ 生成改进建议
+  ↓
+5. 输出审查报告
+  ├─ 打印 JSON 格式（AI 解析）
+  └─ 打印 Markdown 格式（人类阅读）
+  ↓
+6. （可选）添加评论到 PR
+  ↓
+完成
+```
+
+## 🔧 实施步骤
+
+### 步骤 1：获取 PR 基本信息
+
+```bash
+# 1.1 获取 PR 详情
+gitlink-cli pr +view --id 123 --format json > pr_info.json
+
+# 1.2 获取变更文件列表
+gitlink-cli pr +files --id 123 --format json > pr_files.json
+
+# 1.3 获取 diff 内容
+gitlink-cli pr +diff --id 123 --format json > pr_diff.json
+
+# 验证数据获取成功
+echo "=== PR 信息 ===" && cat pr_info.json | jq '.ok'
+echo "=== 变更文件 ===" && cat pr_files.json | jq '.data.total_files'
+echo "=== Diff 大小 ===" && cat pr_diff.json | jq '.data | length'
+```
+
+### 步骤 2：数据预处理
+
+```bash
+# 2.1 过滤代码文件（排除二进制、配置、文档文件）
+cat pr_files.json | jq '.data.files[] |
+  select(.filename | test("\\.(go|js|ts|py|java|rb)$"))' > code_files.json
+
+# 2.2 统计代码文件
+CODE_FILES_COUNT=$(cat code_files.json | jq 'length')
+echo "代码文件数: $CODE_FILES_COUNT"
+
+# 2.3 提取主要变更文件
+cat pr_files.json | jq '.data.files |
+  map(select(.changes > 10)) |
+  sort_by(.changes) | reverse' > main_changes.json
+```
+
+### 步骤 3：准备 AI 分析数据
+
+```bash
+# 3.1 组织分析数据
+cat > analysis_input.json <<EOF
+{
+  "pr_info": $(cat pr_info.json | jq '.data'),
+  "files": $(cat pr_files.json | jq '.data.files'),
+  "diff": $(cat pr_diff.json | jq -r '.data.diff')
+}
+EOF
+
+# 3.2 验证数据格式
+cat analysis_input.json | jq '.'
+```
+
+### 步骤 4：AI 代码分析（使用 Claude）
+
+**方式 1：使用 Claude Code（推荐）**
+
+```
+用户: "请分析 PR #123 的代码变更，检查代码质量、安全性和性能问题"
+
+AI Agent 将：
+1. 读取 analysis_input.json
+2. 分析代码质量和潜在问题
+3. 生成结构化的审查报告
+4. 输出 JSON 和 Markdown 格式报告
+```
+
+**方式 2：使用 Claude API**
+
+```bash
+# 调用 Claude API 进行代码分析
+curl https://api.anthropic.com/v1/messages \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "content-type: application/json" \
+  -d '{
+    "model": "claude-3-5-sonnet-20240620",
+    "max_tokens": 4096,
+    "messages": [
+      {
+        "role": "user",
+        "content": "请分析以下 PR 的代码变更，检查代码质量、安全性和性能问题。输出 JSON 格式的审查报告。\n\nPR 数据：\n'$(cat analysis_input.json)'"
+      }
+    ]
+  }' > analysis_result.json
+```
+
+### 步骤 5：生成审查报告
+
+```bash
+# 5.1 提取 JSON 报告
+cat analysis_result.json | jq -r '.content' > review_report.json
+
+# 5.2 生成 Markdown 报告
+cat analysis_result.json | jq -r '.content' > review_report.md
+
+# 5.3 验证报告格式
+cat review_report.json | jq '.overall_assessment'
+cat review_report.md | head -50
+```
+
+### 步骤 6：输出审查报告
+
+```bash
+# 6.1 打印概要信息
+echo "=== 代码审查报告 ==="
+echo "PR ID: $(cat pr_info.json | jq -r '.data.project_issues_index')"
+echo "总体评分: $(cat review_report.json | jq -r '.overall_assessment.total_score')/100"
+echo "质量评分: $(cat review_report.json | jq -r '.overall_assessment.quality_score')/100"
+echo "安全评分: $(cat review_report.json | jq -r '.overall_assessment.security_score')/100"
+
+# 6.2 打印问题列表
+echo -e "\n=== 发现的问题 ==="
+cat review_report.json | jq -r '.issues[] |
+  "\(.severity) - \(.category): \(.file):\(.line)"'
+
+# 6.3 打印优秀实践
+echo -e "\n=== 优秀实践 ==="
+cat review_report.json | jq -r '.positive_notes[] |
+  "⭐ \(.file):\(.line) - \(.description)"'
+
+# 6.4 打印改进建议
+echo -e "\n=== 改进建议 ==="
+cat review_report.json | jq -r '.recommendations[]' | nl
+```
+
+### 步骤 7：（可选）添加评论到 PR
+
+```bash
+# 7.1 添加总评
+gitlink-cli api POST /:owner/:repo/pulls/123/reviews --body "{
+  \"body\": \"$(cat review_report.md)\",
+  \"event\": \"COMMENT\"
+}"
+
+# 7.2 批量添加行内评论
+cat review_report.json | jq -r '.issues[] |
+  "gitlink-cli api POST /:owner/:repo/pulls/123/comments --body '"'"'{
+    \"body\": \"\(.suggestion)\",
+    \"path\": \"\(.file)\",
+    \"position\": \(.line)
+  }'"'"'"' | bash
+```
+
+## 📊 审查报告示例
+
+### JSON 格式报告
+
+```json
+{
+  "pr_info": {
+    "id": 123,
+    "title": "Feature: Add user authentication",
+    "author": "developer",
+    "branch": "feature/auth → main"
+  },
+  "overall_assessment": {
+    "total_score": 75,
+    "quality_score": 85,
+    "security_score": 60,
+    "performance_score": 75,
+    "maintainability_score": 80,
+    "status": "NEEDS_IMPROVEMENTS"
+  },
+  "issues": [
+    {
+      "id": 1,
+      "severity": "HIGH",
+      "category": "security",
+      "file": "src/auth/login.go",
+      "line": 45,
+      "rule": "SQL Injection",
+      "description": "直接拼接用户输入到 SQL 语句",
+      "suggestion": "使用参数化查询或 ORM"
+    }
+  ],
+  "positive_notes": [
+    {
+      "file": "src/auth/user.go",
+      "line": 120,
+      "description": "优秀的错误处理"
+    }
+  ],
+  "recommendations": [
+    "修复 SQL 注入漏洞",
+    "添加输入验证",
+    "完善单元测试"
+  ]
+}
+```
+
+### Markdown 格式报告
+
+```markdown
+# 代码审查报告
+
+## PR 信息
+- **PR ID**: 123
+- **标题**: Feature: Add user authentication
+- **作者**: @developer
+- **分支**: feature/auth → main
+- **变更**: 3 个文件，+135 / -22 行
+
+## 总体评分: 75/100 ⭐⭐⭐
+
+### 评分详情
+- 代码质量: 85/100 ✅
+- 安全性: 60/100 ⚠️
+- 性能: 75/100 ✅
+- 可维护性: 80/100 ✅
+
+## 🔴 高优先级问题（1）
+
+### 1. SQL 注入漏洞
+- **文件**: `src/auth/login.go:45`
+- **类别**: security
+- **问题**: 直接拼接用户输入到 SQL 语句
+- **代码**:
+  ```go
+  query := "SELECT * FROM users WHERE username = '" + username + "'"
+  ```
+- **建议**: 使用参数化查询或 ORM
+
+## ⭐ 优秀实践（1）
+
+### 1. 优秀的错误处理
+- **文件**: `src/auth/user.go:120`
+- **描述**: 完善的错误处理和日志记录
+
+## 💡 改进建议
+
+1. 修复 SQL 注入漏洞
+2. 添加输入验证
+3. 完善单元测试
+
+## 📝 总结
+
+代码整体质量良好，但存在 1 个需要立即修复的安全问题。建议修复后再合并。
+
+**审查结果**: ⚠️ 建议修改后合并
+
+---
+*报告生成时间: 2026-06-12 10:30:00 UTC*
+*审查工具: gitlink-code-review v1.0.0*
+```
+
+## 🎯 审查标准
+
+### 评分标准
+
+| 分数范围 | 等级 | 合并建议 |
+|---------|------|---------|
+| 90-100 | ⭐⭐⭐⭐⭐ 优秀 | 可以直接合并 |
+| 75-89 | ⭐⭐⭐⭐ 良好 | 建议合并 |
+| 60-74 | ⭐⭐⭐ 一般 | 需要改进 |
+| < 60 | ⭐⭐ 较差 | 不建议合并 |
+
+### 问题优先级
+
+| 优先级 | 图标 | 合并影响 |
+|--------|------|---------|
+| CRITICAL | 🚨 | 阻止合并 |
+| HIGH | 🔴 | 强烈建议修复 |
+| MEDIUM | ⚠️ | 建议修复 |
+| LOW | ℹ️ | 可选修复 |
+
+## 💡 最佳实践
+
+### 1. 定期审查
+
+- PR 创建后 24 小时内完成初审
+- PR 更新后及时审查新代码
+- 合并前进行最终审查
+
+### 2. 平衡严格与灵活
+
+- 核心模块严格审查
+- 工具函数适度审查
+- 文档和配置文件宽松审查
+
+### 3. 建设性反馈
+
+- 指出问题的同时提供解决方案
+- 认可优秀的代码实践
+- 解释为什么需要修改
+
+## 🔧 自动化脚本
+
+完整的审查脚本：
+
+```bash
+#!/bin/bash
+# comprehensive-review.sh - 全面代码审查脚本
+
+set -e
+
+PR_ID=${1:-123}
+OWNER=${2:-"myuser"}
+REPO=${3:-"myrepo"}
+
+echo "=== 开始全面审查 PR #$PR_ID ==="
+
+# 步骤 1：获取数据
+echo "步骤 1：获取 PR 数据..."
+gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
+gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
+gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json
+
+# 步骤 2：验证数据
+echo "步骤 2：验证数据..."
+if [ "$(cat pr_info.json | jq '.ok')" != "true" ]; then
+    echo "错误：无法获取 PR 信息"
+    exit 1
+fi
+
+# 步骤 3：组织分析数据
+echo "步骤 3：组织分析数据..."
+cat > analysis_input.json <<EOF
+{
+  "pr_info": $(cat pr_info.json | jq '.data'),
+  "files": $(cat pr_files.json | jq '.data.files'),
+  "diff": $(cat pr_diff.json | jq -r '.data.diff')
+}
+EOF
+
+# 步骤 4：AI 分析
+echo "步骤 4：AI 分析（需要 Claude Code 或 API）..."
+# 这里调用 AI 分析工具
+# claude-code-analyze analysis_input.json > analysis_result.json
+
+# 步骤 5：生成报告
+echo "步骤 5：生成审查报告..."
+# cat analysis_result.json | jq -r '.content' > review_report.json
+# cat analysis_result.json | jq -r '.content' > review_report.md
+
+# 步骤 6：输出报告
+echo "步骤 6：输出审查报告..."
+# cat review_report.md
+
+echo "=== 审查完成 ==="
+```
+
+使用方法：
+```bash
+chmod +x comprehensive-review.sh
+./comprehensive-review.sh 123 myuser myrepo
+```
+
+## 📚 相关文档
+
+- [基础审查工作流](basic-review-workflow.md) - 快速代码审查
+- [自动审查工作流](auto-review-pr.md) - AI 自动审查
+- [代码质量检查](../references/code-review-quality.md) - 质量分析详解
+- [安全性检查](../references/code-review-security.md) - 安全分析详解
+
+---
+
+*最后更新: 2026-06-12*
--- a/skills/gitlink-code-review/references/code-review-analyze.md
+++ b/skills/gitlink-code-review/references/code-review-analyze.md
@ -0,0 +1,403 @@
+# 代码变更分析
+
+本文档详细说明如何使用 gitlink-cli 分析 PR 的代码变更。
+
+## 📋 概述
+
+代码变更分析是智能代码审查的第一步，通过获取 PR 的文件列表和 diff 内容，为后续的 AI 分析提供数据基础。
+
+## 🎯 分析流程
+
+```
+开始
+  ↓
+1. 获取 PR 基本信息
+  ├─ 使用 pr +view 获取 PR 详情
+  └─ 确认 PR 存在且可访问
+  ↓
+2. 获取变更文件列表
+  ├─ 使用 pr +files 获取文件列表
+  └─ 识别新增/修改/删除的文件
+  ↓
+3. 获取 diff 内容
+  ├─ 使用 pr +diff 获取完整 diff
+  └─ 解析代码变更详情
+  ↓
+4. 数据预处理
+  ├─ 过滤无关文件（如二进制文件）
+  ├─ 提取代码片段
+  └─ 组织分析数据
+  ↓
+完成
+```
+
+## 🔧 步骤详解
+
+### 步骤 1：获取 PR 基本信息
+
+**目的**: 确认 PR 存在且可访问，获取 PR 的元数据信息。
+
+**命令**:
+```bash
+gitlink-cli pr +view --id <pr_id> --format json
+```
+
+**示例**:
+```bash
+# 获取 PR #123 的基本信息
+gitlink-cli pr +view --id 123 --format json
+```
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 123,
+    "project_issues_index": 123,
+    "title": "Feature: Add user authentication",
+    "body": "This PR adds user authentication...",
+    "author": {
+      "login": "developer",
+      "user_id": 456
+    },
+    "status": "open",
+    "pull_request_status": 0,
+    "head": "feature/auth",
+    "base": "main",
+    "created_at": "2026-06-12T10:00:00Z",
+    "updated_at": "2026-06-12T10:30:00Z"
+  }
+}
+```
+
+**关键信息提取**:
+- `id`: PR 数据库 ID（用于后续 API 调用）
+- `project_issues_index`: PR 编号（网页显示）
+- `title`: PR 标题
+- `author`: 作者信息
+- `status`: PR 状态（open/closed/merged）
+- `head` / `base`: 分支信息
+
+### 步骤 2：获取变更文件列表
+
+**目的**: 获取 PR 中所有变更的文件列表，了解代码变更的范围。
+
+**命令**:
+```bash
+gitlink-cli pr +files --id <pr_id> --format json
+```
+
+**示例**:
+```bash
+# 获取 PR #123 的变更文件列表
+gitlink-cli pr +files --id 123 --format json
+```
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "files": [
+      {
+        "filename": "src/auth/login.go",
+        "status": "modified",
+        "additions": 50,
+        "deletions": 20,
+        "changes": 70,
+        "patch": "@@ -1,10 +1,15 @@\n+func login() {"
+      },
+      {
+        "filename": "src/auth/user.go",
+        "status": "added",
+        "additions": 80,
+        "deletions": 0,
+        "changes": 80,
+        "patch": "+package auth\n+\n+func User() {"
+      },
+      {
+        "filename": "README.md",
+        "status": "modified",
+        "additions": 5,
+        "deletions": 2,
+        "changes": 7,
+        "patch": "@@ -1,5 +1,7 @@\n+## Usage\n ..."
+      }
+    ],
+    "total_files": 3,
+    "total_additions": 135,
+    "total_deletions": 22,
+    "total_changes": 157
+  }
+```
+
+**文件状态说明**:
+- `added`: 新增文件
+- `modified`: 修改文件
+- `deleted`: 删除文件
+- `renamed`: 重命名文件
+
+**统计信息**:
+- `total_files`: 变更文件总数
+- `total_additions`: 新增行数
+- `total_deletions`: 删除行数
+- `total_changes`: 总变更行数
+
+### 步骤 3：获取 diff 内容
+
+**目的**: 获取 PR 的完整 diff 内容，用于 AI 代码分析。
+
+**命令**:
+```bash
+gitlink-cli pr +diff --id <pr_id> --format json
+```
+
+**示例**:
+```bash
+# 获取 PR #123 的 diff 内容
+gitlink-cli pr +diff --id 123 --format json
+```
+
+**返回结果**:
+```json
+{
+  "ok": true,
+  "data": {
+    "diff": "diff --git a/src/auth/login.go b/src/auth/login.go\nindex 1234567..abcdefg 100644\n--- a/src/auth/login.go\n+++ b/src/auth/login.go\n@@ -1,10 +1,15 @@\n package auth\n\n+func login(username, password string) error {\n+\tdb, _ := sql.Open(\"mysql\", dsn)\n+\tquery := \"SELECT * FROM users WHERE username = '\" + username + \"'\"\n+\t...\n+}\n",
+    "files_count": 3,
+    "additions": 135,
+    "deletions": 22
+  }
+}
+```
+
+**diff 格式说明**:
+- 标准 unified diff 格式
+- 包含文件头、变更块、代码行
+- `+` 表示新增行
+- `-` 表示删除行
+
+### 步骤 4：数据预处理
+
+**目的**: 清理和组织数据，为 AI 分析做准备。
+
+#### 4.1 过滤无关文件
+
+**需要过滤的文件类型**:
+- 二进制文件（图片、字体、压缩包）
+- 配置文件（package.json、tsconfig.json）
+- 文档文件（README.md、CHANGELOG.md）
+- 测试文件（*_test.go、*.spec.js）
+
+**过滤规则**:
+```javascript
+const shouldSkip = (filename) => {
+  // 跳过二进制文件
+  const binaryExts = ['.png', '.jpg', '.gif', '.pdf', '.zip', '.exe'];
+  if (binaryExts.some(ext => filename.endsWith(ext))) {
+    return true;
+  }
+
+  // 跳过配置文件
+  const configFiles = ['package.json', 'tsconfig.json', '.gitignore'];
+  if (configFiles.includes(filename)) {
+    return true;
+  }
+
+  // 跳过文档文件
+  if (filename.match(/^(README|CHANGELOG|CONTRIBUTING)\.md$/i)) {
+    return true;
+  }
+
+  return false;
+};
+```
+
+#### 4.2 提取代码片段
+
+**目的**: 从 diff 中提取变更的代码片段，便于 AI 分析。
+
+**示例**:
+```javascript
+const extractCodeSnippets = (diff) => {
+  const lines = diff.split('\n');
+  const snippets = [];
+  let currentSnippet = [];
+  let inHunk = false;
+
+  lines.forEach(line => {
+    if (line.startsWith('@@')) {
+      // 开始新的代码块
+      if (currentSnippet.length > 0) {
+        snippets.push(currentSnippet.join('\n'));
+      }
+      currentSnippet = [line];
+      inHunk = true;
+    } else if (inHunk && (line.startsWith('+') || line.startsWith('-') || line.startsWith(' '))) {
+      // 收集代码行
+      currentSnippet.push(line);
+    }
+  });
+
+  if (currentSnippet.length > 0) {
+    snippets.push(currentSnippet.join('\n'));
+  }
+
+  return snippets;
+};
+```
+
+#### 4.3 组织分析数据
+
+**最终数据结构**:
+```json
+{
+  "pr_info": {
+    "id": 123,
+    "title": "Feature: Add user authentication",
+    "author": "developer",
+    "branch": "feature/auth → main"
+  },
+  "files": [
+    {
+      "filename": "src/auth/login.go",
+      "status": "modified",
+      "language": "go",
+      "code_snippets": [
+        {
+          "start_line": 10,
+          "end_line": 25,
+          "code": "+func login(username, password string) error {"
+        }
+      ]
+    }
+  ],
+  "statistics": {
+    "total_files": 3,
+    "code_files": 2,
+    "total_additions": 135,
+    "total_deletions": 22
+  }
+}
+```
+
+## 💡 最佳实践
+
+### 1. 按文件类型分组
+
+将变更文件按语言和类型分组，便于针对性分析：
+
+```javascript
+const groupFilesByLanguage = (files) => {
+  const groups = {
+    go: [],
+    javascript: [],
+    python: [],
+    other: []
+  };
+
+  files.forEach(file => {
+    const ext = file.filename.split('.').pop();
+    const lang = detectLanguage(ext);
+    groups[lang].push(file);
+  });
+
+  return groups;
+};
+```
+
+### 2. 优先审查核心文件
+
+优先审查核心业务逻辑文件：
+
+```javascript
+const prioritizeFiles = (files) => {
+  const priority = {
+    'high': [],    // 核心业务逻辑
+    'medium': [],  // 工具函数
+    'low': []      // 配置、测试
+  };
+
+  files.forEach(file => {
+    if (file.filename.includes('core') || file.filename.includes('service')) {
+      priority.high.push(file);
+    } else if (file.filename.includes('util') || file.filename.includes('helper')) {
+      priority.medium.push(file);
+    } else {
+      priority.low.push(file);
+    }
+  });
+
+  return priority;
+};
+```
+
+### 3. 限制分析范围
+
+对于大型 PR，限制分析范围：
+
+```javascript
+const limitAnalysisScope = (files, maxFiles = 10, maxLines = 1000) => {
+  let totalLines = 0;
+  const selectedFiles = [];
+
+  for (const file of files) {
+    if (selectedFiles.length >= maxFiles) break;
+    if (totalLines + file.changes > maxLines) break;
+
+    selectedFiles.push(file);
+    totalLines += file.changes;
+  }
+
+  return selectedFiles;
+};
+```
+
+## 🔍 常见问题
+
+### Q: 如何处理大型 PR？
+
+**A**: 大型 PR（>1000 行）建议：
+1. 按模块分组分析
+2. 优先审查核心文件
+3. 分批生成审查报告
+4. 建议作者拆分为多个小 PR
+
+### Q: 如何处理重命名文件？
+
+**A**: GitLink 的 PR API 会正确处理重命名：
+- `status` 为 `renamed`
+- `patch` 包含重命名前后的完整路径
+- 分析时使用新文件名
+
+### Q: 如何检测文件语言？
+
+**A**: 使用文件扩展名检测：
+
+```javascript
+const detectLanguage = (filename) => {
+  const ext = filename.split('.').pop();
+  const languageMap = {
+    'go': 'go',
+    'js': 'javascript',
+    'ts': 'typescript',
+    'py': 'python',
+    'java': 'java',
+    'rb': 'ruby',
+    'php': 'php'
+  };
+  return languageMap[ext] || 'other';
+};
+```
+
+## 📚 相关文档
+
+- [代码质量检查](code-review-quality.md) - 代码质量分析
+- [安全性检查](code-review-security.md) - 安全性分析
+- [性能检查](code-review-performance.md) - 性能分析
+- [完整工作流](../examples/comprehensive-review-workflow.md) - 完整审查流程
+
+---
+
+*最后更新: 2026-06-12*
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Donkey_kevin	245d3bc1fc	fix: 还原 README 到合并前版本	2026-07-14 17:00:32 +08:00
Donkey_kevin	d9ff6d134d	Merge origin/master into zk_branch, resolve conflicts in milestone/issue/README	2026-07-14 16:41:56 +08:00
mengcheng	7f82dbdc24	Merge pull request '修改测试脚本' (#38 ) from mc_branch into master	2026-07-12 18:31:54 +08:00
camelliamc	460618d4b5	Merge branch 'master' into mc_branch	2026-07-12 18:31:21 +08:00
camelliamc	7079bfae64	修改测试脚本	2026-07-12 18:31:12 +08:00
mengcheng	693906cb6c	Merge pull request '更新README' (#37 ) from mc_branch into master	2026-07-11 00:39:56 +08:00
camelliamc	a02e3a53fd	update README	2026-07-11 00:39:35 +08:00
mengcheng	59535c72c1	Merge pull request '实现多仓库协同自动化工作流' (#36 ) from mc_branch into master Release / release (push) Failing after 1m20s Details	2026-07-10 20:55:19 +08:00
camelliamc	8a2c4d3bd9	实现多仓库协同自动化工作流（04）串联 repo/issue/pr/release +list 命令完成端到端任务链：逐仓库采集数据 → 对齐 gitlink-health 的健康度评分 → 生成中文 HTML 看板 → 协调发版（支持真 --dry-run 预览）	2026-07-10 20:54:32 +08:00
mengcheng	e893efa817	Merge pull request '完成项目一键初始化工作流(03-project-init)' (#35 ) from mc_branch into master	2026-07-10 18:39:22 +08:00
camelliamc	3988802e2c	完成项目一键初始化工作流(03-project-init)：重构为文件模式生成README/LICENSE/CI配置+里程碑+Issue+分支保护+Release - README/LICENSE/CONTRIBUTING/.gitlink-ci.yml 生成在仓库内，而非Wiki页面 - 新增里程碑创建步骤、欢迎Issue - README中文标题（快速开始、环境要求、安装、使用、测试） - git clone/push免密认证、git作者行内传参 - 修复CRLF换行符、反引号命令替换等问题 - 同步更新PowerShell版本(03-project-init.ps1) - 更新workflows文档和SKILL菜单	2026-07-10 18:37:19 +08:00
zzx-coder	5b3af9d978	Merge pull request '完成两条自动化工作流：社区运营自动化 + 代码质量看门人' (#34 ) from mc_branch into master	2026-07-10 11:10:01 +08:00
Donkey_kevin	4b2d45baea	feat: 修复 milestone +view 输出 + issue/board assign 字段修正 + 文档更新 - 修复 milestone +view 显示 No results 的问题（提取 milestone 字段输出） - 修正 issue/board 的 assign 字段：assigned_to_id -> assigner_ids - 添加代码逻辑文档、CLI 优化报告、reading notes - 添加 board 功能示例和修改笔记	2026-07-10 11:06:11 +08:00
camelliamc	9f0973f80a	完成两条自动化工作流：社区运营自动化 + 代码质量看门人工作流一（社区运营自动化）： - Webhook 监听 Issue 创建 → 自动关键词分类 → 打标签 + 分配责任人 - 修复 assigner_ids 字段名（原 assigned_to_id 已被后端静默忽略） - 修复标签 ID 从项目 issue_tags API 动态获取（原 tracker ID 与 issue_tag ID 不匹配） - 新增 Windows PowerShell 版本脚本工作流二（代码质量看门人）： - Webhook 监听 PR 创建 → 数据采集 → AI 代码审查 → 本地 CI → 冲突检测 → 自动合并 - 新增 02a-pr-gatekeeper.sh 核心编排脚本（603 行） - 新增 Windows PowerShell 版本 - Webhook 监听器增加 pull_request 事件路由	2026-07-10 10:49:48 +08:00
Donkey_kevin	19b0e31bf8	feat: 补全 Raw API 封装 — file/milestone/issue增强/pr增强 + 单元测试新增模块: - file: 11个命令 (ls/tree/read/readme/search/create/update/delete/batch/commits/diff) - milestone: 6个命令 (list/create/view/update/delete/status) Issue增强: - 元数据查询: +statuses/+authors/+assigners/+priorities - 评论管理: +comment-edit/+comment-delete/+replies - 批量删除: +batch-destroy (原生batch_destroy接口) PR增强: - +reopen/+update/+commits/+versions/+vdiff/+filesv1 - 评论管理: +comment-edit/+comment-delete 其他: - 新增 board 看板模块, compliance 合规模块 - 更新 README.md/README.zh-CN.md 帮助文档 - 43个单元测试全部通过 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-09 23:38:52 +08:00
mengcheng	b476963fde	Merge pull request '增加部分代码注释' (#32 ) from mc_branch into master	2026-07-08 15:20:25 +08:00
camelliamc	007bbe4da3	增加部分代码注释	2026-07-08 15:19:33 +08:00
zzx-coder	e26160a335	Merge pull request '修改流水线相关信息处理' (#31 ) from zzx_branch into master	2026-07-08 10:29:59 +08:00
狗gogo	80c7554fd8	Merge origin/master into zzx_branch, local wins on conflicts	2026-07-08 10:29:42 +08:00
狗gogo	17a876b0bd	Update community-ops workflows and demo index on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-08 10:29:15 +08:00
zzx-coder	dde0a6d0b4	Merge pull request '修改脚本中获取网页数据的渠道与方法' (#30 ) from zzx_branch into master	2026-07-08 09:14:53 +08:00
狗gogo	d19b4c2722	Merge origin/master into zzx_branch, local wins on conflicts	2026-07-08 09:14:43 +08:00
狗gogo	86eff95244	Update research-compliance workflow on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-08 09:14:21 +08:00
zzx-coder	2a75e68df9	Merge pull request '修改了skills中的部分bug' (#29 ) from zzx_branch into master	2026-07-08 08:29:13 +08:00
狗gogo	f44333f9e1	Merge origin/master into zzx_branch, local wins on conflicts	2026-07-08 08:20:46 +08:00
狗gogo	152cb108d6	Update health skill docs and demo files on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-08 08:20:35 +08:00
zzx-coder	88dc671bc3	Merge pull request '修改部分bug' (#28 ) from zzx_branch into master	2026-07-08 01:29:51 +08:00
狗gogo	a5e9fe8199	Update academic workflows and dashboard on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-08 01:15:23 +08:00
狗gogo	609a62c146	Update workflows and demo files on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-07 22:57:15 +08:00
狗gogo	de9bca30bb	Merge origin/master into zzx_branch, local wins on conflicts	2026-07-07 13:09:19 +08:00
狗gogo	08037ca60b	Resolve conflicts: keep local changes on zzx_branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-07 13:08:51 +08:00
mengcheng	fe4341fede	Merge pull request '实现场景1：社区运营自动化' (#27 ) from mc_branch into master	2026-07-07 09:43:33 +08:00
camelliamc	2420579ba9	Merge branch 'master' into mc_branch	2026-07-07 09:37:59 +08:00
camelliamc	8ecbf8a203	fix(workflows): 修复项目初始化/多仓库协同 + 公共库	2026-07-07 09:25:53 +08:00
camelliamc	0b6d176a45	feat(workflows): 社区运营自动化 — Webhook接收器 + 部署 + systemd	2026-07-07 09:25:39 +08:00
camelliamc	411403ac5a	feat(workflows): 社区运营自动化 — Issue实时分类 + 周报/Release定时发布	2026-07-07 09:23:27 +08:00
zzx-coder	ad825a3e83	Merge pull request '新增前端' (#26 ) from zzx_branch into master	2026-07-06 20:12:53 +08:00
狗gogo	4379b16083	feat: add interactive showcase frontend (demo/) for gitlink-cli 新增 GitLink CLI 交互式展示平台，提供 Web UI 一键执行所有 CLI 命令及 AI Agent Skills，无需记忆命令行参数即可完成功能演示、测试和验证。 - server.py：Python stdlib HTTP 服务 (127.0.0.1:8765)，提供 /api/exec（执行 gitlink-cli 命令）、/api/claude（执行 Claude Code Skills 提示词，支持多轮 session）、/api/cancel - index.html：原生 JS/HTML/CSS 单文件 SPA（~1260 行），包含： - 双引擎切换：PowerShell 模式（8 模块 ~60 条预设命令）和 Claude Code 模式（9 模块 ~22 条预设提示词） - 双运行模式：Direct Run（点选即执行）和 Edit Mode（填入终端编辑后手动执行） - 终端模拟器：命令回显、stdout/stderr 着色、多行编辑、Ctrl+L 清屏 - 智能链接提取：从输出中自动解析 owner/repo 及 Issue/PR/Webhook/Wiki 编号，生成 GitLink 网页端可点击链接 - 可折叠侧边栏 + 拖拽调节宽度 + 执行引擎状态指示 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-07-06 20:12:23 +08:00
nudt_zk	ea86b2b5a8	Merge pull request 'workflow的skill增加' (#25 ) from zk_branch into master	2026-07-06 12:15:51 +08:00
Donkey_kevin	a8f8a30953	feat(workflows): add gitlink-research skill and academic workflow scripts Add 5 research auxiliary scenarios: project insights, compliance check, progress tracking, citation format, and knowledge graph support. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-06 12:14:06 +08:00
Donkey_kevin	4f3ae280b7	feat(workflows): add workflow skill system and fix batch commands - Fix batch-label: use issue_tag_ids instead of tracker_id - Fix parseTracker: support Chinese label names (缺陷/功能/疑问 etc.) - Add workflow skill menu (workflows/SKILL.md) with 5 automation options - Add workflow reference files: community-ops, contributor-growth, multi-repo - Fix PowerShell scripts: Invoke-GL array syntax, remove ConvertFrom-Json - Fix wiki +create flag from --body to --content - Update contributor-growth doc with known issues and field corrections - Add contributor leaderboard HTML report Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-02 16:17:15 +08:00
nudt_zk	b2b0336236	Merge pull request '1' (#24 ) from zk_branch into master	2026-07-02 15:39:07 +08:00
mengcheng	6a701c6e3a	Merge pull request 'feat(faq): 将生成的faq内容组织重构为真正的Q&A知识库' (#23 ) from mc_branch into master Release / release (push) Failing after 2m17s Details	2026-07-02 14:57:55 +08:00
camelliamc	b1f9adf8ad	Merge branch 'master' into mc_branch	2026-07-02 14:50:23 +08:00
Donkey_kevin	012c197ee6	fix(workflows): make PowerShell scripts compatible with PS 5.1 - Replace ?? operator with if/else for Windows PowerShell 5.1 compatibility - Remove Chinese characters to avoid encoding issues - Use string concatenation instead of complex expressions in here-strings - Update common.psm1 to remove PS 7+ syntax Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-01 23:59:45 +08:00
Donkey_kevin	ecf16b379d	feat(workflows): add PowerShell scripts and refactor workflow Skill - Add 4 PowerShell workflow scripts for cross-platform automation: - 01-community-ops.ps1: Issue auto-classify, assign, weekly report, release notes - 03-project-init.ps1: One-click project init with README, CONTRIBUTING, CI guide, issues, branch protection, release - 04-multi-repo-collab.ps1: Cross-repo dashboard with HTML output and coordinated release - 05-contributor-growth.ps1: Contributor scoring (AHP), HTML report, Wiki, badge awards - Add workflows/lib/common.psm1 shared PowerShell module - Refactor gitlink-workflow SKILL.md to focus on AI-powered code review (workflow 2) - Retain original .sh scripts alongside new .ps1 scripts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-01 23:52:17 +08:00
zzx-coder	42fafdc8ed	Merge pull request '新修了一个user.go中的显示bug' (#22 ) from zzx_branch into master	2026-07-01 15:51:13 +08:00
狗gogo	64b8dabb50	fix(user): user +info 改用绝对路径 /users/:login，避免 URL 拼接歧义 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-07-01 15:37:16 +08:00
zzx-coder	3a761d20c9	Merge pull request '修复子任务一中部分展示bug' (#21 ) from zzx_branch into master	2026-07-01 14:25:48 +08:00
狗gogo	b1bf96141c	feat: add repo batch-delete, unify api error envelope, harden wiki handling - repo: 新增 `+batch-delete` shortcut（--names / --from CSV / --dry-run），补齐 batch-create / batch-update / batch-delete 三件套 - api: 新增 `--body-file` 解决 PowerShell 调用 .exe 时剥离内嵌引号的问题； JSON 解析、参数冲突、读文件失败、网络错误统一按 envelope 输出，便于 --format json + jq 自动化解析 - wiki: unwrapGatewayResponse 接受全部 HTTP 2xx（修复 DELETE 返回 204 被误判失败）；错误改返回 *clierrors.CLIError 让 envelope 输出生效；fetchPageContent 自动重试 ".-" 后缀（GitLink 后端给 sub_url 加后缀导致 GET 404）；outputWithDecodedContent 解码 base64 字段为明文提升 agent 可读性；wiki +delete 先解析实际 pageName 再 DELETE，删除后强制 GET 验证并返回结构化结果 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-07-01 13:07:29 +08:00
Donkey_kevin	a3c433e697	feat(workflows): add 5 workflow scripts with bug fixes Add workflow automation scripts for GitLink CLI: - 01-community-ops: issue triage, weekly reports, release notes - 02-code-quality-gatekeeper: PR review, quality scoring, auto-merge - 03-project-init: repo creation, branch protection, wiki setup - 04-multi-repo-collab: cross-repo dashboard, health monitoring - 05-contributor-growth: AHP-weighted scoring, HTML reports, wiki publish Fixes applied during testing: - common.sh: fix SIGPIPE error in gl_check (use here-string instead of pipe) - common.sh: add WinGet Links to PATH for jq availability on Windows - 05-contributor-growth: fix pull_request_number → pull_request_id - 05-contributor-growth: fix null total_addition/total_deletion (sum from files) - 05-contributor-growth: fix wiki publish 400 error (use timestamp in title) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-07-01 12:11:38 +08:00
Donkey_kevin	a7513cf683	Merge branch 'zk_branch' of https://www.gitlink.org.cn/zzx-coder/gitlink-cli into zk_branch # Conflicts: # skills/README.md	2026-06-30 23:42:11 +08:00
camelliamc	c02cf03a5b	feat(faq): 将生成的faq内容组织重构为真正的Q&A知识库	2026-06-29 11:59:53 +08:00
camelliamc	582d27273f	Merge branch 'master' into mc_branch	2026-06-29 10:44:59 +08:00
zzx-coder	bd92fcf578	Merge pull request '针对子任务一种的功能实现修复了部分bug' (#20 ) from zzx-coder into master	2026-06-29 10:31:35 +08:00
camelliamc	0442e5b80c	同步master分支新增 dashboard 和 code-insight 的skill	2026-06-28 11:20:37 +08:00
camelliamc	e5d46d6381	修改生成健康度报告SKILL.md	2026-06-28 10:35:28 +08:00
狗gogo	3e867d23f8	refactor: improve error handling, output formatting, and wiki/webhook shortcuts - Add dedicated error_print.go for centralized error output - Enhance formatter with better table/json/yaml rendering - Add unit tests for output formatter - Improve runner with cleaner error propagation - Update globals and root command configuration - Refine webhook and wiki shortcut implementations Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-06-27 19:16:53 +08:00
zkevin	93d695d1b3	Add gitlink-code-insight skill: interactive dashboard for all shortcuts New skill that generates an HTML dashboard showcasing all 69 gitlink-cli shortcuts organized into 14 categories with search and collapsible UI. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-06-24 09:59:12 +08:00
mengcheng	36684f039b	Merge pull request 'feat(health):项目健康度报告由 markdown 格式改成 HTML 文件' (#19 ) from mc_branch into master	2026-06-24 00:21:03 +08:00
camelliamc	2535a313f8	Merge branch 'master' into mc_branch	2026-06-24 00:20:33 +08:00
camelliamc	1d70aadf05	feat(health):项目健康度报告由 markdown 格式改成 HTML 文件	2026-06-24 00:20:02 +08:00
zzx-coder	cd34efe773	Merge pull request '新增三个skills' (#18 ) from zzx_branch into master	2026-06-24 00:04:35 +08:00
狗gogo	de6f94351e	feat(skills): add gitlink-stale skill for stale issue/PR detection Add a new AI Agent skill for detecting and managing stale issues and PRs: - SKILL.md - main skill guide - README.md - overview documentation - examples/ - AI judgment demo, PR stale workflow, weekly cleanup workflow - references/ - scan, judge, actions, and exempt rules The skill automates stale detection with AI-powered judgment and supports weekly cleanup workflows with configurable exemption rules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-24 00:03:43 +08:00
狗gogo	d17b4f0383	Merge branch 'master' of https://www.gitlink.org.cn/zzx-coder/gitlink-cli	2026-06-23 23:45:38 +08:00
mengcheng	be0d600d56	Merge pull request 'docs(skills): gitlink-changelog 发行版条目新增作者标注' (#16 ) from mc_branch into master	2026-06-23 22:38:57 +08:00
camelliamc	26fa5cf6e4	Merge branch 'master' into mc_branch	2026-06-23 22:36:18 +08:00
camelliamc	7a30a03836	docs(skills): gitlink-changelog 发行版条目新增作者标注	2026-06-23 22:35:29 +08:00
zkevin	dc5425690d	Add gitlink-code-insight skill: interactive dashboard for all shortcuts New skill that generates an HTML dashboard showcasing all 69 gitlink-cli shortcuts organized into 14 categories with search and collapsible UI. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-06-23 15:56:57 +08:00
狗gogo	d804a01e8a	Merge branch 'master' of https://www.gitlink.org.cn/zzx-coder/gitlink-cli	2026-06-16 17:02:39 +08:00
狗gogo	5a590f6850	feat(skills): add gitlink-code-review and gitlink-issue-triage skills Add two new AI Agent skills for automated GitLink workflows: - gitlink-code-review: automated PR/code review with quality and security analysis - gitlink-issue-triage: automated issue classification (tracker/priority/labels) Each skill includes SKILL.md, README.md, examples, and references. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-16 08:54:56 +08:00
狗gogo	1907e80c34	Merge remote master with local changes: resolve README conflict	2026-06-16 08:50:13 +08:00
狗gogo	d18de0437a	Merge branch 'master' of https://www.gitlink.org.cn/zzx-coder/gitlink-cli	2026-06-16 08:47:53 +08:00
狗gogo	198c17ea08	test webhook trigger	2026-06-04 15:17:56 +08:00
狗gogo	7ed6fd565a	fix: 修复流水线验证部署节点的参数解析错误 - 将verify_deployment_0节点的ssh_cmd从'gitlink-cli version && ls -lh /opt/gitlink-cli/gitlink-cli'简化为'gitlink-cli version' - 修复原因：&&符号在GitLink流水线参数解析器中被当作特殊字符处理，导致"未找到对应的参数"错误 - 简化后的验证命令足以确认部署成功 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-04 15:03:39 +08:00
				`@ -1 +0,0 @@`
				`PR Test 2026年 4月 7日星期二 11时45分56秒 CST`