diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..d667cda --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,258 @@ +# 开发指南 + +## 🚀 快速开始 + +### 安装依赖 + +```bash +pnpm install +``` + +## 🧪 本地测试方法 + +### ✅ 方法 1: 快速测试(推荐) + +```bash +pnpm run dev +``` + +- ✅ 直接运行 TypeScript 源码 +- ✅ 不会自动重启 +- ✅ 适合交互式 CLI 测试 +- ✅ 程序退出后命令才结束 +- ✅ 可以正常使用 Ctrl+C 退出 + +**使用场景**: 日常开发和功能测试 + +### 📦 方法 2: 生产环境测试 + +```bash +# 步骤 1: 构建 +pnpm run build + +# 步骤 2: 运行 +pnpm start +``` + +- ✅ 测试编译后的代码 +- ✅ 最接近生产环境 +- ⚠️ 修改代码后需要重新构建 + +**使用场景**: 发布前最终测试 + +### 🔗 方法 3: 全局命令测试 + +```bash +# 步骤 1: 构建并链接到全局 +pnpm run build +npm link + +# 步骤 2: 在任何目录测试 +nbtca + +# 步骤 3: 测试完成后清理 +npm unlink -g @nbtca/prompt +``` + +**使用场景**: 测试全局安装体验 + +### ⚠️ 方法 4: 监听模式(不推荐用于交互式测试) + +```bash +pnpm run dev:watch +``` + +- ⚠️ 文件变化时自动重启 +- ❌ 不适合交互式 CLI 测试 +- ❌ 会频繁中断交互 +- ✅ 仅适合纯函数/工具类开发 + +**使用场景**: 仅用于调试非交互式代码 + +## 🎯 测试新功能(知识库模块) + +### 测试步骤 + +1. **启动程序** + ```bash + pnpm run dev + ``` + +2. **选择 "知识库" 选项** + - 使用方向键或 Vim 键位 (j/k) 导航 + - 按 Enter 确认 + +3. **浏览文档分类** + - 📚 教程 (Tutorial) + - 🔧 维修日 + - 🎉 相关活动举办 + - 📋 流程文档 (Process) + - 🛠️ 维修相关 (Repair) + - 📦 归档文档 (Archived) + - 📖 README + +4. **测试功能点** + - [ ] 进入目录 + - [ ] 返回上级目录 + - [ ] 查看 Markdown 文件 + - [ ] 终端渲染是否正常 + - [ ] 在浏览器中打开 + - [ ] 网络错误处理 + +### 预期行为 + +✅ **正常流程**: +1. 从 GitHub 获取文档列表 +2. 显示目录树 +3. 选择文件后在终端渲染 Markdown +4. 提供返回或浏览器打开选项 + +✅ **错误处理**: +1. GitHub API 失败时提示重试 +2. 文件加载失败时建议浏览器打开 +3. 网络超时友好提示 + +## 🔧 常见问题 + +### Q1: 为什么 `pnpm run dev` 比 `pnpm run dev:watch` 好? + +**A**: 对于交互式 CLI 应用: + +- `pnpm run dev` (tsx src/index.ts) + - ✅ 运行一次,等待程序退出 + - ✅ 用户可以正常交互 + - ✅ Ctrl+C 正常工作 + +- `pnpm run dev:watch` (tsx watch src/index.ts) + - ❌ 监听文件变化,自动重启 + - ❌ 用户操作会被中断 + - ❌ Ctrl+C 只能退出 tsx,不能优雅退出程序 + +### Q2: 如何退出正在运行的程序? + +**A**: +- **正常退出**: 在菜单中选择 "退出" 选项 +- **强制退出**: 按 `Ctrl+C` +- 如果卡住: 按 `Ctrl+C` 两次 + +### Q3: 修改代码后看不到变化? + +**A**: 取决于你的测试方法: +- `pnpm run dev`: 重新运行命令即可 +- `pnpm start`: 需要先 `pnpm run build` +- `npm link`: 需要 `pnpm run build` 后重新测试 + +### Q4: TypeScript 编译错误怎么办? + +**A**: +```bash +# 检查类型错误 +pnpm run build + +# 如果有错误,根据提示修复 +# 常见错误: +# - 导入路径缺少 .js 后缀 +# - 类型定义不匹配 +# - 未使用的变量 +``` + +## 📝 开发工作流 + +### 日常开发 + +```bash +# 1. 修改代码 +vim src/features/docs.ts + +# 2. 测试 +pnpm run dev + +# 3. 重复 1-2 直到功能完成 +``` + +### 提交前检查 + +```bash +# 1. 确保构建通过 +pnpm run build + +# 2. 测试编译后的代码 +pnpm start + +# 3. 提交 +git add . +git commit -m "feat: add terminal docs viewer" +``` + +### 发布前测试 + +```bash +# 1. 构建 +pnpm run build + +# 2. 全局测试 +npm link +nbtca + +# 3. 清理 +npm unlink -g @nbtca/prompt +``` + +## 🎨 代码规范 + +- 使用 TypeScript 严格模式 +- 函数添加 JSDoc 注释 +- 导入模块使用 `.js` 后缀(即使是 `.ts` 文件) +- 保持代码简洁,避免过度抽象 + +## 📂 项目结构 + +``` +src/ +├── config/ # 配置常量 +│ ├── data.ts # URL、应用信息 +│ └── theme.ts # 颜色主题 +│ +├── core/ # 核心功能 +│ ├── logo.ts # Logo 显示 +│ ├── menu.ts # 主菜单 +│ ├── ui.ts # UI 组件 +│ └── vim-keys.ts # Vim 键位支持 +│ +├── features/ # 功能模块 +│ ├── calendar.ts # 活动日历 +│ ├── docs.ts # 知识库 ⭐ 新功能 +│ ├── repair.ts # 维修服务 +│ └── website.ts # 网站访问 +│ +├── logo/ # Logo 资源 +├── index.ts # 入口 +├── main.ts # 主逻辑 +└── types.ts # 类型定义 +``` + +## 🌟 新功能说明 + +### 知识库终端查看器 + +**文件**: `src/features/docs.ts` + +**核心功能**: +1. `fetchGitHubDirectory()` - 从 GitHub API 获取目录 +2. `fetchGitHubRawContent()` - 获取文件原始内容 +3. `browseDirectory()` - 交互式目录浏览 +4. `viewMarkdownFile()` - 终端渲染 Markdown +5. `showDocsMenu()` - 主菜单入口 + +**依赖**: +- `axios` - HTTP 请求 +- `marked` + `marked-terminal` - Markdown 渲染 +- `inquirer` - 交互式选择 +- `chalk` - 终端颜色 + +**测试要点**: +- [ ] GitHub API 正常调用 +- [ ] 目录树正确显示 +- [ ] Markdown 渲染美观 +- [ ] 错误处理友好 +- [ ] 导航流畅 diff --git a/README.md b/README.md index 133a6e3..29aa97e 100644 --- a/README.md +++ b/README.md @@ -1,272 +1,231 @@ # NBTCA Prompt -
+Terminal-based information system for NingboTech Computer Association. [![npm version](https://img.shields.io/npm/v/@nbtca/prompt)](https://www.npmjs.com/package/@nbtca/prompt) -[![npm downloads](https://img.shields.io/npm/dm/@nbtca/prompt)](https://www.npmjs.com/package/@nbtca/prompt) -[![Node.js Version](https://img.shields.io/node/v/@nbtca/prompt)](https://nodejs.org) -[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/) [![License](https://img.shields.io/npm/l/@nbtca/prompt)](LICENSE) -**极简优雅的浙大宁波理工学院计算机协会命令行工具** +## Overview -[安装](#-安装) • [使用](#-使用) • [功能](#-核心功能) • [开发](#-开发) +NBTCA Prompt is a minimalist command-line interface tool designed for the Computer Association of Zhejiang University Ningbo Institute of Technology. It provides quick access to association resources, events, and documentation directly from the terminal. -
+## Features ---- - -## ✨ 特性 - -- 🚀 **极简设计** - 移除冗余,专注核心功能 -- ⚡ **即时启动** - 无加载动画,快速响应 -- 🎨 **智能UI** - Logo和文档查看支持优雅降级 -- 📦 **TypeScript** - 完整类型安全,严格模式 -- 🔧 **模块化** - 清晰的架构,易于维护 -- 🌐 **现代化** - ES2022、async/await、ES Modules - -## 🎯 核心功能 - -### 📅 近期活动 -从 ICS 日历获取并展示社团未来30天的活动安排 +- View upcoming association events (30-day calendar) +- Access repair service information +- Browse technical documentation from terminal +- Quick links to official website and GitHub +- Minimalist design with maximum terminal compatibility -### 🔧 维修服务 -快速访问 NBTCA 电脑维修和软件安装服务 +## Installation -### 📚 知识库 -在终端查看技术文档(Markdown 渲染),失败时自动打开浏览器 - -### 🌐 官方网站 -一键访问 NBTCA 主页和 GitHub 组织 - -### ℹ️ 关于 -查看项目信息、版本号和功能特性 - -## 📦 安装 - -### 全局安装(推荐) +### Global Installation ```bash npm install -g @nbtca/prompt ``` -### 使用 npx(无需安装) +### Using npx (No Installation Required) ```bash npx @nbtca/prompt ``` -## 🚀 使用 +## Usage -安装后,使用以下命令之一启动: +Run the program with: ```bash -nbtca # 简短命令 -nbtca-welcome # 完整命令 +nbtca ``` -### 界面预览 +Navigate using arrow keys or Vim bindings (j/k/g/G). -``` -███╗ ██╗██████╗ ████████╗ ██████╗ █████╗ -████╗ ██║██╔══██╗╚══██╔══╝██╔════╝██╔══██╗ -██╔██╗ ██║██████╔╝ ██║ ██║ ███████║ -██║╚██╗██║██╔══██╗ ██║ ██║ ██╔══██║ -██║ ╚████║██████╔╝ ██║ ╚██████╗██║ ██║ -╚═╝ ╚═══╝╚═════╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ - - 浙大宁波理工学院计算机协会 - -──────────────── Prompt v1.0.0 ──────────────── - -? 请选择功能: -❯ › 近期活动 查看最近30天的社团活动 - › 维修服务 电脑维修、软件安装 - › 知识库 技术文档、教程资源 - › 官方网站 访问NBTCA主页 - › GitHub 开源项目与代码 - › 关于 项目信息与帮助 - ─────────────────────────────────────── - › 退出 -``` +## Development -## 🏗️ 项目架构 +### Prerequisites -``` -src/ -├── config/ # 配置文件 -│ ├── data.ts # URL和应用信息常量 -│ └── theme.ts # 颜色主题定义 -│ -├── core/ # 核心模块 -│ ├── logo.ts # 智能Logo显示(iTerm2图片 → ASCII降级) -│ ├── menu.ts # 主菜单系统 -│ └── ui.ts # UI组件库 -│ -├── features/ # 功能模块 -│ ├── calendar.ts # ICS日历集成 -│ ├── docs.ts # 知识库终端查看 -│ ├── repair.ts # 维修服务访问 -│ └── website.ts # 官网和GitHub访问 -│ -├── logo/ -│ ├── logo.txt # iTerm2图片格式 -│ └── ascii-logo.txt # ASCII艺术字 -│ -├── index.ts # 程序入口 -├── main.ts # 主逻辑 -└── types.ts # TypeScript类型定义 -``` +- Node.js >= 16.0.0 -## 🛠️ 技术栈 +### Setup -### 核心依赖 +```bash +git clone https://github.com/nbtca/prompt.git +cd prompt +pnpm install +``` -| 包名 | 用途 | -|------|------| -| `axios` | HTTP请求(获取日历和文档) | -| `ical.js` | ICS日历解析 | -| `marked` + `marked-terminal` | Markdown终端渲染 | -| `chalk` | 终端颜色输出 | -| `inquirer` | 交互式菜单 | -| `open` | 打开浏览器 | +### Development Workflow -### 开发依赖 +#### Quick Testing (Recommended) -- **TypeScript 5.3+** - 严格类型检查 -- **tsx** - TypeScript执行和热重载 -- **@types/\*** - 类型定义 +```bash +pnpm run dev +``` -## 💻 开发 +Runs TypeScript source directly without auto-restart. Exit with menu option or Ctrl+C. -### 克隆仓库 +#### Watch Mode (File Changes) ```bash -git clone https://github.com/nbtca/prompt.git -cd prompt +pnpm run dev:watch ``` -### 安装依赖 +Auto-restarts on file changes. Not recommended for interactive testing. + +#### Production Build ```bash -npm install +pnpm run build +pnpm start ``` -### 开发模式(带热重载) +### Available Commands ```bash -npm run dev +pnpm run dev # Run TypeScript source directly +pnpm run dev:watch # Run with file watching +pnpm run build # Compile TypeScript to JavaScript +pnpm start # Run compiled code +pnpm run clean # Remove dist directory ``` -### 构建 +## Project Structure -```bash -npm run build +``` +src/ +├── config/ # Configuration constants +│ ├── data.ts # URLs and app info +│ └── theme.ts # Color themes +├── core/ # Core functionality +│ ├── logo.ts # Logo display logic +│ ├── menu.ts # Main menu system +│ ├── ui.ts # UI components +│ └── vim-keys.ts # Vim key bindings +├── features/ # Feature modules +│ ├── calendar.ts # Event calendar +│ ├── docs.ts # Documentation viewer +│ ├── repair.ts # Repair service +│ └── website.ts # Website links +└── main.ts # Application entry point ``` -构建产物将输出到 `dist/` 目录。 +## Technology Stack -### 本地测试 +### Core Dependencies -```bash -npm start -``` +- axios - HTTP requests +- ical.js - ICS calendar parsing +- marked + marked-terminal - Markdown rendering +- chalk - Terminal colors +- inquirer - Interactive prompts +- open - Browser integration -## 📊 系统要求 +### Development Dependencies -- **Node.js**: >= 16.0.0 -- **操作系统**: Windows, macOS, Linux -- **终端**: 支持 ANSI 转义序列 +- TypeScript 5.3+ +- tsx - TypeScript execution +- @types/* - Type definitions -推荐使用现代终端: -- macOS: iTerm2, Terminal.app -- Windows: Windows Terminal, PowerShell -- Linux: GNOME Terminal, Konsole +## Documentation Viewer -## 🎨 设计理念 +The knowledge base viewer features: -### 极简主义 +- Direct GitHub repository access +- VitePress syntax cleaning +- Terminal Markdown rendering +- Browser fallback option +- Directory tree navigation -- ❌ 移除所有不必要的动画和装饰 -- ✅ 保留核心功能,优化用户体验 -- 📊 代码量减少 65%(从 4,966 行到 1,760 行) +### Supported Formats -### 优雅降级 +- Standard Markdown +- VitePress frontmatter (auto-removed) +- VitePress containers (auto-converted) +- Table of contents (placeholder in terminal) -- **Logo显示**: iTerm2 图片 → ASCII 艺术字 → 纯文本 -- **文档查看**: 终端 Markdown 渲染 → 浏览器打开 -- **错误处理**: 友好提示,永不崩溃 +## Terminal Compatibility -### 类型安全 +Designed for maximum compatibility with: -- 全项目 TypeScript 严格模式 -- 完整的接口和类型定义 -- 编译时错误捕获 +- Modern terminals (iTerm2, Windows Terminal, GNOME Terminal) +- Legacy terminals (xterm, Terminal.app) +- SSH sessions +- Screen/tmux multiplexers -## 📝 更新日志 +ASCII-based UI elements ensure rendering on any terminal emulator. -### v1.0.0 (2025-11-21) +## System Requirements -**重大变更**: -- 🔄 完整 TypeScript 重构 -- 🎨 极简 UI 重新设计 -- 📦 包名更改为 `@nbtca/prompt` -- 📉 代码量减少 65% +- Node.js: >= 16.0.0 +- OS: Windows, macOS, Linux +- Terminal: ANSI escape sequence support -**新功能**: -- 📅 ICS 日历集成(从 ical.nbtca.space 获取活动) -- 📚 终端 Markdown 渲染器(查看知识库文档) -- 🎯 智能 Logo 显示(支持降级) -- 🚀 即时启动(移除所有加载动画) +## Common Issues -**技术改进**: -- TypeScript 5.3+ 严格模式 -- ES2022 模块系统 -- 模块化架构(core/, features/, config/) -- 改进的 CI/CD(多版本测试,npm provenance) +### Q: Auto-restart when using `pnpm run dev:watch`? -### v2.3.1 及更早版本 +A: This is expected behavior. Use `pnpm run dev` for interactive testing. -见 [CHANGELOG](https://github.com/nbtca/prompt/releases) 了解历史版本。 +### Q: How to exit the program? -## 🤝 贡献 +A: Select the Exit option from menu, or press Ctrl+C. -欢迎贡献代码!请遵循以下步骤: +### Q: Changes not reflected? -1. Fork 本仓库 -2. 创建特性分支 (`git checkout -b feature/amazing-feature`) -3. 提交更改 (`git commit -m 'Add amazing feature'`) -4. 推送到分支 (`git push origin feature/amazing-feature`) -5. 创建 Pull Request +A: If using `pnpm start`, rebuild with `pnpm run build` first. -### 开发规范 +## Contributing -- 使用 TypeScript 严格模式 -- 遵循现有代码风格 -- 添加适当的注释 -- 确保构建通过 (`npm run build`) +Contributions are welcome. Please follow these guidelines: -## 📄 许可证 +1. Fork the repository +2. Create a feature branch +3. Follow existing code style +4. Add appropriate comments +5. Ensure build passes +6. Submit pull request -[MIT License](LICENSE) +### Code Standards -## 📞 联系我们 +- Use TypeScript strict mode +- Add JSDoc comments for functions +- Use .js extension in imports (even for .ts files) +- Keep code simple and readable -- 🌐 **官网**: https://nbtca.space -- 📧 **邮箱**: contact@nbtca.space -- 🐙 **GitHub**: https://github.com/nbtca -- 📦 **NPM**: https://www.npmjs.com/package/@nbtca/prompt +## License -## 🙏 致谢 +MIT License - See LICENSE file for details -感谢所有为 NBTCA Prompt 做出贡献的开发者! +## Contact ---- +- Website: https://nbtca.space +- Email: contact@nbtca.space +- GitHub: https://github.com/nbtca +- NPM: https://www.npmjs.com/package/@nbtca/prompt + +## Changelog -
+### v1.0.1 (2025-11-27) -**[⬆ 回到顶部](#nbtca-prompt)** +- Added terminal documentation viewer +- Removed emoji icons for better compatibility +- Improved Markdown rendering +- Added VitePress syntax cleaning +- Enhanced directory navigation + +### v1.0.0 (2025-11-21) -Made with ❤️ by [NBTCA](https://nbtca.space) +- Complete TypeScript rewrite +- Minimalist UI redesign +- ICS calendar integration +- Terminal Markdown renderer +- Smart logo display with fallback + +## Acknowledgments + +Built with focus on simplicity and terminal compatibility. + +--- -
+Made by [NBTCA](https://nbtca.space) diff --git a/TERMINAL_UX.md b/TERMINAL_UX.md new file mode 100644 index 0000000..a76211f --- /dev/null +++ b/TERMINAL_UX.md @@ -0,0 +1,184 @@ +# Terminal UX Improvements + +## Summary + +All changes align with standard Linux/Unix terminal conventions for better user experience and consistency. + +## Changes Made + +### 1. Standardized Navigation Symbols + +**Before**: +``` +[📁] emoji icons +[<-] inconsistent arrows +[ ] empty brackets +``` + +**After**: +``` +[..] - Up to parent directory (Unix convention) +[ <] - Back/Previous +[ ^] - Return to main menu +[ *] - Special action (open in browser) +[DIR] - Directory indicator +[MD] - Markdown file indicator +[ ?] - Help/About +[ x] - Exit +``` + +**Rationale**: ASCII-only symbols ensure maximum terminal compatibility and follow Unix conventions (e.g., `..` for parent directory). + +### 2. Added Keybinding Hints + +**Main Menu**: +``` +Navigation: j/k or ↑/↓ | Jump: g/G | Quit: q or Ctrl+C +``` + +**Location**: Displayed above main menu for visibility + +**Rationale**: Users should know available shortcuts without reading documentation. + +### 3. ESC Key Support + +**Implementation**: ESC key now properly passed through to menus + +**Expected Behavior** (future enhancement): +- ESC in submenus = go back one level +- ESC in main menu = exit application + +**Current State**: Infrastructure added, full implementation needs inquirer customization + +**Rationale**: ESC is standard cancel/back key in Unix terminals. + +### 4. Improved Documentation + +**Added Descriptions**: +- Knowledge Base menu now shows purpose +- Comments in code clarified + +**Rationale**: Self-documenting UI reduces user confusion. + +## Navigation Symbol Reference + +``` +Symbol | Meaning | Unix Standard +--------|--------------------------|--------------- +[..] | Parent directory | Yes (cd ..) +[DIR] | Directory entry | Common +[MD] | Markdown file | N/A +[ <] | Go back/previous | No (custom) +[ ^] | Go to top/main menu | No (custom) +[ *] | Special action | No (custom) +[ ?] | Help/Information | Common (man ?) +[ x] | Exit/Quit | No (custom) +``` + +## Keybinding Reference + +``` +Key | Action | Standard +--------|----------------------|---------- +↑/↓ | Navigate up/down | Yes +j/k | Navigate up/down | Vim +g | Jump to first | Vim +G | Jump to last | Vim +q | Quit application | Vim/less/man +ESC | Cancel/Go back | Yes +Ctrl+C | Force quit | Yes +Enter | Select/Confirm | Yes +``` + +## Comparison with Common Unix Tools + +### less/more +- j/k navigation: ✓ Supported +- g/G jump: ✓ Supported +- q quit: ✓ Supported +- ESC: Usually not used + +### man +- j/k navigation: ✓ Supported +- g/G jump: ✓ Supported +- q quit: ✓ Supported +- h for help: Not implemented (use [?] menu item) + +### vim +- j/k navigation: ✓ Supported +- g/G jump: ✓ Supported +- q quit: ✓ Supported +- ESC: ✓ Infrastructure added + +### fzf (fuzzy finder) +- j/k navigation: ✓ Supported +- Ctrl+C quit: ✓ Supported +- ESC cancel: ✓ Infrastructure added + +## Implementation Details + +### vim-keys.ts +- Maps j/k to arrow keys +- Maps g/G to home/end +- Maps q to Ctrl+C +- Passes ESC through for menu handling + +### menu.ts +- Shows keybinding hints before menu +- Standardized symbol usage +- Consistent formatting + +### docs.ts +- Uses [..] for parent directory (Unix standard) +- Uses [ ^] for main menu (clear intent) +- Uses [ <] for back navigation +- Added descriptive subtitle + +## Terminal Compatibility + +All symbols tested and work correctly on: +- iTerm2 (macOS) +- Terminal.app (macOS) +- GNOME Terminal (Linux) +- Windows Terminal +- PuTTY (SSH) +- tmux/screen multiplexers + +## Future Enhancements + +1. **Context-aware q key**: Currently q always exits. Consider: + - q in submenu = go back + - Q (shift) = force quit + +2. **ESC back navigation**: Full implementation requires: + - Custom inquirer plugin or wrapper + - State management for menu stack + +3. **Help overlay**: F1 or ? key for: + - Show all keybindings + - Context-sensitive help + +4. **Breadcrumb trail**: Show current location: + ``` + Main > Docs > Tutorial > Getting Started + ``` + +5. **Operation cancellation**: Allow Ctrl+C during: + - Network requests + - File loading + - Long operations + +## Migration Notes + +### Breaking Changes +None. All changes are additive or improve existing behavior. + +### User-Facing Changes +- New keybinding hints displayed +- Updated navigation symbols (more intuitive) +- ESC key now recognized (infrastructure) + +### Developer Notes +- ESC handling requires inquirer extension for full functionality +- Current implementation provides foundation +- Symbol constants could be extracted to config diff --git a/package.json b/package.json index 3a5005e..8898874 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,8 @@ }, "scripts": { "start": "node dist/index.js", - "dev": "tsx watch src/index.ts", + "dev": "tsx src/index.ts", + "dev:watch": "tsx watch src/index.ts", "build": "tsc", "postbuild": "mkdir -p dist/logo && cp src/logo/logo.txt dist/logo/ && cp src/logo/ascii-logo.txt dist/logo/", "clean": "rm -rf dist",