GITHUB_WIKI_SETUP - cso1z/Feishu-MCP GitHub Wiki

GitHub Wiki 设置指南（使用 Git 子模块）

本指南说明如何将项目文档推送到 GitHub Wiki，使用 Git 子模块管理 Wiki 仓库。

📦 子模块说明

本项目使用 Git 子模块将 GitHub Wiki 仓库 (https://github.com/cso1z/Feishu-MCP.wiki.git) 作为项目的一部分管理，位于 doc/wiki-repo 目录。

优势

✅ 版本控制：Wiki 内容作为项目的一部分进行版本管理
✅ 同步便捷：可以直接在项目中编辑 Wiki 源文件，然后同步到 GitHub Wiki
✅ 协作友好：团队成员克隆项目时自动获取 Wiki 内容

🚀 快速开始

1. 初始化子模块（首次使用）

如果刚克隆项目，需要初始化子模块：

# 如果克隆时没有使用 --recurse-submodules
git submodule init
git submodule update

# 或者一次性克隆（推荐）
git clone --recurse-submodules https://github.com/cso1z/Feishu-MCP.git

2. 编辑 Wiki 文档

直接编辑 doc/wiki-repo/ 目录下的文件！

# 编辑任意 Wiki 文件
code doc/wiki-repo/架构设计.md
code doc/wiki-repo/Home.md

3. 提交并推送

# 进入子模块目录
cd doc/wiki-repo

# 检查更改
git status

# 提交更改
git add .
git commit -m "docs: 更新 Wiki 文档"
git push origin master

# 返回主项目（可选）
cd ../..
git add doc/wiki-repo
git commit -m "docs: 更新 Wiki 子模块引用"
git push origin main

📁 目录结构

Feishu-MCP/
├── doc/
│   ├── wiki-repo/              # Git 子模块（直接编辑这里！）
│   │   ├── Home.md              # Wiki 主页
│   │   ├── _Sidebar.md          # Wiki 侧边栏
│   │   ├── _Footer.md           # Wiki 页脚
│   │   ├── 架构设计.md          # 架构设计文档
│   │   ├── 核心模块详解.md      # 核心模块详解
│   │   ├── 认证与授权机制.md    # 认证与授权机制
│   │   ├── 开发者指南.md        # 开发者指南
│   │   ├── API-参考文档.md      # API 参考文档
│   │   ├── 最佳实践.md          # 最佳实践
│   │   ├── MCP-协议实现.md      # MCP 协议实现
│   │   └── ...                  # 其他 Wiki 文档
│   │
│   ├── feishu_doc.md           # API 接口文档（独立文件）
│   ├── MCP服务实现分享.md      # 分享文档（独立文件）
│   └── feishu-handler.ts       # 代码文件（独立文件）

🔄 工作流程

直接编辑 doc/wiki-repo/ 目录下的文件即可！

编辑 Wiki 文件：

code doc/wiki-repo/架构设计.md
# 或
code doc/wiki-repo/Home.md

检查更改：
```
cd doc/wiki-repo
git status
```

提交并推送：

git add .
git commit -m "docs: 更新架构设计"
git push origin master

📋 注意事项

链接格式：使用 [页面名](页面名) 而不是 [文本](./文件.md)
文件名：不支持空格，使用连字符（如 API-参考文档.md）
编码：确保文件使用 UTF-8 编码

📝 GitHub Wiki 链接格式

Wiki 内部链接

# 标准格式：使用 Markdown 链接
[页面名](页面名)

# 带自定义显示文本
[链接文本](页面名)

# 带锚点的链接
[页面名](页面名#章节名)

外部链接

# 指向主仓库
[README](https://github.com/cso1z/Feishu-MCP#readme)

# 指向仓库中的文件
[配置文件](https://github.com/cso1z/Feishu-MCP/blob/main/FEISHU_CONFIG.md)

⚠️ 注意事项

直接编辑 Wiki 文件
- 现在可以直接编辑 doc/wiki-repo/ 目录下的文件
- 编辑完成后提交并推送到 GitHub Wiki
文件名限制
- GitHub Wiki 不支持文件名中的空格
- 使用连字符：API-参考文档.md（不是 API 参考文档.md）
链接格式
- 使用标准 Markdown 链接格式：[页面名](页面名)
- 不需要文件扩展名：[架构设计](架构设计)（不是 [架构设计](架构设计.md)）
提交顺序
- 先提交子模块的更改并推送
- 再提交主项目的子模块引用更新（可选）

🔧 子仓库操作详解

更新子仓库代码（从远程拉取最新更改）

有两种方式更新子仓库：

方法一：在子仓库目录中更新（推荐）

# 进入子仓库目录
cd doc/wiki-repo

# 拉取最新更改
git pull origin master

# 或者使用 fetch + merge
git fetch origin
git merge origin/master

方法二：从主项目更新

# 在主项目根目录执行
git submodule update --remote --merge doc/wiki-repo

# 或者更新所有子模块
git submodule update --remote --merge

推送子仓库代码（提交并推送本地更改）

完整流程

# 1. 进入子仓库目录
cd doc/wiki-repo

# 2. 查看更改状态
git status

# 3. 添加更改的文件
git add .

# 4. 提交更改
git commit -m "docs: 更新 Wiki 文档"

# 5. 推送到远程仓库
git push origin master

快速推送（如果有未提交的更改）

cd doc/wiki-repo
git add . && git commit -m "docs: 更新文档" && git push origin master

更新主项目的子模块引用（可选）

推送子仓库后，如果希望主项目也记录这个更新：

# 返回主项目根目录
cd ../..

# 添加子模块引用更改
git add doc/wiki-repo

# 提交引用更新
git commit -m "docs: 更新 Wiki 子模块引用"

# 推送主项目（可选）
git push origin main

其他常用命令

# 查看子模块状态
git submodule status

# 查看子仓库的提交历史
cd doc/wiki-repo
git log --oneline

# 查看子仓库的远程信息
cd doc/wiki-repo
git remote -v

# 查看子仓库分支
cd doc/wiki-repo
git branch -a

🐛 故障排查

子模块显示为空

# 初始化并更新
git submodule init
git submodule update

子模块未更新

# 强制更新
git submodule update --remote --merge --force

# 或者在子仓库中强制拉取
cd doc/wiki-repo
git fetch origin
git reset --hard origin/master

推送失败（权限问题）

# 检查远程仓库地址
cd doc/wiki-repo
git remote -v

# 如果地址不对，更新远程地址
git remote set-url origin https://github.com/cso1z/Feishu-MCP.wiki.git

# 使用 HTTPS 推送（需要输入 GitHub 凭证）
git push origin master

# 或使用 SSH（如果配置了 SSH 密钥）
git remote set-url origin [email protected]:cso1z/Feishu-MCP.wiki.git
git push origin master

子仓库有未提交的更改，无法更新

# 查看未提交的更改
cd doc/wiki-repo
git status

# 选择方案：
# 1. 提交更改后再更新
git add . && git commit -m "docs: 保存当前更改"
git pull origin master

# 2. 暂存更改后更新
git stash
git pull origin master
git stash pop

# 3. 放弃更改后更新（谨慎使用）
git reset --hard HEAD
git pull origin master

Wiki 仓库不存在

在 GitHub 仓库设置中启用 Wiki
创建第一个页面（任意内容）
初始化子模块：git submodule add https://github.com/cso1z/Feishu-MCP.wiki.git doc/wiki-repo

权限问题

确保你有仓库的写权限才能推送 Wiki 更改。

📚 相关文档

子模块使用指南 - 详细的 Git 子模块操作说明
Wiki 源文件 README - Wiki 文件结构和使用说明

提示：所有 Wiki 文档都在 doc/wiki-repo/ 目录中直接编辑和管理，保持简洁高效。