diff --git a/docs/shared/gitee-cli-guide.md b/docs/shared/gitee-cli-guide.md
new file mode 100644
index 0000000..5a88e04
--- /dev/null
+++ b/docs/shared/gitee-cli-guide.md
@@ -0,0 +1,150 @@
+---
+title: "Gitee CLI 使用指南"
+description: "码云命令行工具，对标 GitHub CLI，四队共用"
+author: 小橘 🍊
+date: 2026-04-01
+---
+
+# Gitee CLI 使用指南
+
+码云（Gitee）命令行工具，对标 GitHub CLI (`gh`)，让 agent 和人类都能在终端里管理 Gitee 仓库。
+
+**仓库**: [shazhou-ww/gitee-cli](https://github.com/shazhou-ww/gitee-cli)
+
+## 安装
+
+```bash
+git clone https://github.com/shazhou-ww/gitee-cli.git
+cd gitee-cli && npm install && npm run build
+npm link  # 全局可用
+```
+
+## 认证
+
+### 方式一：环境变量（推荐给 agent）
+
+```bash
+export GITEE_TOKEN="your-personal-access-token"
+```
+
+### 方式二：交互式登录
+
+```bash
+gitee auth login
+```
+
+Token 缓存到 `~/.config/gitee-cli/config.json`。
+
+### 获取 Token
+
+1. 打开 [Gitee Personal Access Tokens](https://gitee.com/profile/personal_access_tokens)
+2. 创建 token，勾选 `projects`、`pull_requests`、`issues`、`notes`
+3. 复制 token
+
+### 验证
+
+```bash
+gitee auth status
+# ✓ Authenticated as ww-shazhou (Wei Wei)
+```
+
+## 命令速查
+
+### 仓库
+
+```bash
+gitee repo list                          # 列出所有仓库
+gitee repo view mitsein/mitsein          # 查看仓库详情
+gitee repo create my-project             # 创建仓库
+gitee repo create my-project --private   # 创建私有仓库
+gitee repo clone mitsein/mitsein         # clone 仓库
+gitee repo delete owner/repo             # 删除仓库（需确认）
+```
+
+### Issue
+
+```bash
+gitee issue list --repo mitsein/mitsein                    # 列出 issues
+gitee issue list --repo mitsein/mitsein --state closed     # 已关闭的
+gitee issue create --repo mitsein/mitsein --title "Bug"    # 创建 issue
+gitee issue view IHWYFN --repo mitsein/mitsein             # 查看详情
+gitee issue close IHWYFN --repo mitsein/mitsein            # 关闭 issue
+gitee issue comment IHWYFN --repo mitsein/mitsein --body "已修复"  # 评论
+```
+
+!!! note "Gitee Issue 编号"
+    Gitee 的 issue 编号是字母+数字格式（如 `IHWYFN`），不是纯数字。
+
+### Pull Request
+
+```bash
+gitee pr list --repo mitsein/mitsein                        # 列出 PR
+gitee pr create --repo mitsein/mitsein --title "feat: xxx" --head feature-branch
+gitee pr view 1 --repo mitsein/mitsein                      # 查看详情
+gitee pr merge 1 --repo mitsein/mitsein                     # 合并
+gitee pr close 1 --repo mitsein/mitsein                     # 关闭
+```
+
+### Release
+
+```bash
+gitee release list --repo mitsein/mitsein
+gitee release create --repo mitsein/mitsein --tag v1.0.0 --name "v1.0.0"
+```
+
+### 组织
+
+```bash
+gitee org list
+```
+
+### 裸 API 调用（兜底）
+
+```bash
+gitee api GET /v5/user                    # 获取当前用户
+gitee api GET /v5/emojis                  # 不需要认证的 API
+gitee api POST /v5/repos/owner/repo/issues --field title="Bug"
+```
+
+## 常用选项
+
+| 选项 | 说明 |
+|---|---|
+| `--json` | 输出原始 JSON（方便 agent 解析） |
+| `--page <n>` | 分页页码 |
+| `--per-page <n>` | 每页条数（默认 20） |
+| `--repo <owner/repo>` | 指定仓库（在 gitee 仓库目录内可省略，自动检测） |
+
+## 自动检测仓库
+
+在 Gitee 仓库目录内执行命令时，`--repo` 可以省略：
+
+```bash
+cd ~/mitsein  # 这是一个 gitee.com 的 git 仓库
+gitee issue list  # 自动检测为 mitsein/mitsein
+```
+
+支持 HTTPS 和 SSH 两种 remote 格式。
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `GITEE_TOKEN` | Personal Access Token（优先级高于 config 文件） |
+
+## 与 GitHub CLI 对比
+
+| 操作 | GitHub CLI | Gitee CLI |
+|---|---|---|
+| 认证 | `gh auth login` | `gitee auth login` |
+| 列出仓库 | `gh repo list` | `gitee repo list` |
+| 查看 issue | `gh issue view 1` | `gitee issue view IHWYFN --repo owner/repo` |
+| 创建 PR | `gh pr create` | `gitee pr create --head branch` |
+| 裸 API | `gh api /repos/...` | `gitee api GET /v5/repos/...` |
+
+主要区别：Gitee 的 issue 编号是字母格式，且 `--repo` 需要显式指定（除非在仓库目录内）。
+
+## 参考
+
+- [Gitee API v5 文档](https://gitee.com/api/v5/swagger)
+- [GitHub 仓库](https://github.com/shazhou-ww/gitee-cli)
diff --git a/mkdocs.yml b/mkdocs.yml
index 237f141..19cff07 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -105,6 +105,7 @@ nav:
           - systemd 重启策略: shared/systemd-service-restart-policy.md
           - 从 Windows 到 WSL 迁移: shared/windows-to-wsl-migration.md
       - 工具与 API:
+          - Gitee CLI 使用指南: shared/gitee-cli-guide.md
           - 语音转文字配置: shared/speech-to-text.md
           - SiliconFlow 图片生成: shared/siliconflow-image-gen.md
           - TTS 语音功能: shared/tts-guide.md