Aurisper 文档管理器
一款 macOS 原生应用，用于管理 Aurisper 内部知识库文档。通过可视化界面简化 Git 操作，让非技术人员也能轻松更新和发布文档。
功能特性
- GitHub OAuth 登录 - 使用个人 GitHub 账号进行身份验证和文档同步
- 一键更新 - 自动 clone/pull 远程仓库
- 一键发布 - 自动 add/commit/push，commit message 包含操作者信息
- 文档浏览 - 树形结构展示 docs/ 目录下的所有 Markdown 文件
- 文档编辑 - 内置纯文本编辑器，支持快捷键保存
- 文件上传 - 拖拽上传，自动识别文件类型并放到对应目录
系统要求
- macOS 13.0 (Ventura) 或更高版本
- Git（系统自带或通过 Homebrew 安装）
- GitHub 账号（需要仓库访问权限）
安装使用
1. 获取应用
应用位于 build/Release/AurisperDocManager.app，双击即可运行。
或将其拖拽到 /Applications 文件夹进行安装。
2. 首次登录
┌─────────────────────────────────────────────────────────┐
│ │
│ 1. 启动应用 │
│ │ │
│ ▼ │
│ 2. GitHub OAuth 登录 │
│ （授权应用访问你的 GitHub 账号） │
│ │ │
│ ▼ │
│ 3. 进入主界面 │
│ │
└─────────────────────────────────────────────────────────┘
3. 日常使用
| 操作 | 说明 |
|---|---|
| 更新 | 点击工具栏「更新」按钮，拉取远程最新内容 |
| 编辑 | 在左侧边栏选择文档，右侧编辑器中修改内容 |
| 保存 | 按 ⌘S 或点击「保存」按钮，保存到本地 |
| 发布 | 点击「发布」按钮，输入提交说明，推送到远程 |
| 新建 | 点击「新建」按钮，创建新的 Markdown 文档 |
| 上传 | 点击「上传」按钮，拖拽或选择文件上传 |
整体架构
┌─────────────────────────────────────────────────────────────────────┐
│ Aurisper 文档管理器 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Views │ │ Managers │ │ Models │ │
│ │ │ │ │ │ │ │
│ │ LoginView │───▶│ AuthManager │───▶│ GitHubUser │ │
│ │ MainView │ │ │ │ GitResult │ │
│ │ SidebarView │───▶│ GitManager │───▶│ Document │ │
│ │ EditorView │ │ │ │ AppConfig │ │
│ │ FileUpload │───▶│ DocManager │ │ │ │
│ │ │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 外部服务 │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ GitHub │ │ 本地文件系统 │ │ │
│ │ │ OAuth │ │ │ │ │
│ │ │ API │ │ ~/aurisper-doc│ │ │
│ │ └───────────────┘ └───────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
模块说明
| 模块 | 文件 | 职责 |
|---|---|---|
| AuthManager | Managers/AuthManager.swift | 处理 GitHub OAuth 登录，管理用户凭证 |
| GitManager | Managers/GitManager.swift | 封装 Git 命令（clone/pull/push），处理仓库同步 |
| DocumentManager | Managers/DocumentManager.swift | 管理文档列表、读写文件、处理上传 |
| LoginView | Views/LoginView.swift | GitHub 登录界面 |
| MainView | Views/MainView.swift | 主界面，包含工具栏和布局 |
| SidebarView | Views/SidebarView.swift | 左侧文档树 |
| EditorView | Views/EditorView.swift | 右侧文本编辑器 |
| FileUploadView | Views/FileUploadView.swift | 文件上传弹窗 |
工作流程
文档更新流程
┌──────────────────────────────────────────────────────────────────┐
│ 更新流程 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 用户点击「更新」 │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 检查本地仓库 │ │
│ │ ~/aurisper-doc │ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ │ │
│ 不存在 存在 │
│ │ │ │
│ ▼ ▼ │
│ git clone git pull │
│ │ │ │
│ └─────┬─────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 刷新文档列表 │ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
文档发布流程
┌──────────────────────────────────────────────────────────────────┐
│ 发布流程 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 用户点击「发布」 │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 弹出提交说明窗口 │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 保存当前文档 │ （如有未保存的修改） │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ git add -A │ 添加所有更改 │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ git commit │ 提交说明 + 操作者信息 │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ git push │ 推送到 GitHub │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Cloudflare 自动 │ 约 2-3 分钟后网站更新 │
│ │ 构建部署 │ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
文件上传流程
┌──────────────────────────────────────────────────────────────────┐
│ 上传流程 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 用户拖拽/选择文件 │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 识别文件类型 │ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────┼─────┬─────────┬─────────┐ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ .md .pdf .html .png/.jpg 其他 │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ docs/ static/ static/ static/ 拒绝 │
│ pdf/ html/ img/ │
│ │ │ │ │ │
│ └─────┴─────┴─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 复制文件到目标 │ │
│ │ 目录 │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 显示上传结果 │ 包含引用路径提示 │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
安全说明
权限控制
本应用的安全性由 GitHub 仓库权限 保证：
| 操作 | 权限检查 |
|---|---|
| git clone/pull | GitHub 检查用户是否有仓库读取权限 |
| git push | GitHub 检查用户是否有仓库写入权限 |
如何管理用户权限
- 访问
https://github.com/Aurisper/aurisper-doc/settings/access - 点击 Add people 添加团队成员
- 选择权限级别：
- Read - 只能查看和下载文档
- Write - 可以编辑和发布文档
- Admin - 完全控制权限
目录结构
AurisperDocManager/
├── AurisperDocManager.xcodeproj # Xcode 项目文件
├── build/
│ └── Release/
│ └── AurisperDocManager.app # 编译后的应用
└── AurisperDocManager/
├── AurisperDocManagerApp.swift # 应用入口
├── ContentView.swift # 主视图路由
├── Info.plist # URL Scheme 配置
├── AurisperDocManager.entitlements
├── Assets.xcassets/ # 资源文件
├── Models/
│ └── Models.swift # 数据模型和配置
├── Managers/
│ ├── AuthManager.swift # GitHub OAuth 认证
│ ├── GitManager.swift # Git 操作
│ └── DocumentManager.swift # 文档管理
└── Views/
├── LoginView.swift # 登录界面
├── MainView.swift # 主界面
├── SidebarView.swift # 侧边栏
├── EditorView.swift # 编辑器
└── FileUploadView.swift # 文件上传
常见问题
Q: 点击「更新」后提示失败？
A: 检查以下几点：
- 确保已完成 GitHub OAuth 登录
- 确保网络连接正常
- 检查 GitHub 账号是否有仓库访问权限
Q: 发布后网站没有更新？
A: Cloudflare Pages 构建部署需要 2-3 分钟，请稍等后刷新网站。
Q: 如何切换 GitHub 账号？
A: 点击右上角用户菜单，选择「退出登录」，然后重新登录。
Q: 提示没有仓库权限？
A: 请联系管理员在 GitHub 仓库设置中添加你的账号为 Collaborator。
技术栈
- SwiftUI - 用户界面框架
- ASWebAuthenticationSession - GitHub OAuth 认证
- Process - 执行 Git 命令
- Keychain - 安全存储凭证
版本历史
-
v1.1 (2026-01-05) - 简化登录流程
- 移除 Zero Trust 登录，直接使用 GitHub OAuth
- 简化用户界面
-
v1.0 (2026-01-05) - 初始版本
- GitHub OAuth 登录
- 文档浏览、编辑、发布
- 文件上传自动分类
许可证
Copyright © 2026 Aurisper. All rights reserved.