@nbtca/prompt 1.0.1 → 1.0.4

package/CHANGELOG.md

@@ -1,164 +1,77 @@
-# NBTCA Prompt - UI 重构完成 ✨
-
-## 🎨 设计更新
-
-### 1. 新的标语
-- ✅ 更换为英文标语：**"To be at the intersection of technology and liberal arts."**
-- ✅ 移除居中显示，采用左对齐布局
-
-### 2. 渐变彩色效果
-- ✅ 使用 `gradient-string` 实现蓝色主调渐变
-- ✅ 颜色方案：深蓝 (#1e3a8a) → 天蓝 (#0ea5e9) → 青色 (#06b6d4)
-- ✅ 添加动画效果，启动时标语会有流动的渐变动画（0.8秒）
-- ✅ ASCII Logo 也使用蓝色渐变渲染
-
-### 3. 极简 UI设计
-- ✅ 参考 Claude Code CLI 的简洁风格
-- ✅ 移除冗余装饰元素
-- ✅ 统一使用 dim 样式营造层次感
-- ✅ 更清晰的信息结构
-
-### 4. Vim 键位支持
-- ✅ 支持 `j` 向下导航
-- ✅ 支持 `k` 向上导航
-- ✅ 支持 `g` 跳到顶部
-- ✅ 支持 `G` (Shift+g) 跳到底部
-- ✅ 同时保留标准的 `↑` `↓` 箭头键
-- ✅ 通过拦截 stdin 的 keypress 事件实现，无需修改 Inquirer
-
-## ⚡ 性能优化
-
-### 启动速度优化
-- ✅ 动画时长优化：从 1.5秒 降至 0.8秒
-- ✅ 动画帧数优化：从 15帧 降至 8帧
-- ✅ 渐变预计算：避免重复创建渐变对象
-- ✅ 移除未使用的代码和文件
-
-### 代码精简
-- ✅ 删除 `DATA_MANAGEMENT.md` 无用文档
-- ✅ 删除测试文件
-- ✅ 删除临时文档
-- ✅ 简化 UI 组件，移除未使用的函数
-
-## 📦 依赖更新
-
-新增依赖：
-```json
-{
-  "gradient-string": "^3.0.0",
-  "@types/gradient-string": "^1.1.6",
-  "@inquirer/prompts": "^8.0.3"
-}
-```
-
-## 🚀 使用方法
-
-```bash
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-
-# 运行
-npm start
-
-# 或者直接使用 npx（未来发布后）
-npx @nbtca/prompt
-```
-
-## 🎯 界面预览
-
-```
-[ASCII Art Logo 以蓝色渐变显示]
-
-To be at the intersection of technology and liberal arts.
-[流动的蓝色渐变动画 - 0.8秒]
-
-v1.0.0
-
-  ↑↓ / jk 导航  •  ⏎ 选择  •  g 顶部  •  G 底部
-
-› 选择功能
-  近期活动  查看最近30天的社团活动
-❯ 维修服务  电脑维修、软件安装
-  知识库    技术文档、教程资源
-  官方网站  访问NBTCA主页
-  GitHub    开源项目与代码
-  关于      项目信息与帮助
-
-  退出
-```
-
-## ✨ 亮点特性
-
-1. **真正的 Vim 键位** - j/k/g/G 完整支持，对 vim 用户极其友好
-2. **视觉吸引力** - 蓝色渐变动画让启动时更有科技感
-3. **快速启动** - 优化后动画仅需0.8秒，不影响使用体验
-4. **现代简洁** - 参考行业标杆 Claude Code 的设计语言
-5. **清晰易读** - 统一的层次结构和配色方案
-
-## 📝 技术细节
-
-### Vim 键位实现
-```typescript
-// 通过拦截 stdin 的 keypress 事件来实现
-export function enableVimKeys() {
-  const stdin = process.stdin;
-  const originalEmit = stdin.emit.bind(stdin);
-
-  (stdin.emit as any) = function (event: string, ...args: any[]) {
-    if (event === 'keypress') {
-      const [, key] = args;
-
-      // j -> down, k -> up, g -> home, G -> end
-      if (key.name === 'j') return originalEmit('keypress', null, { name: 'down' });
-      if (key.name === 'k') return originalEmit('keypress', null, { name: 'up' });
-      if (key.name === 'g' && !key.shift) return originalEmit('keypress', null, { name: 'home' });
-      if (key.name === 'g' && key.shift) return originalEmit('keypress', null, { name: 'end' });
-    }
-    return originalEmit(event, ...args);
-  };
-}
-```
-
-### 渐变实现
-```typescript
-// 创建蓝色主调渐变
-const blueGradient = gradient([
-  { color: '#1e3a8a', pos: 0 },    // 深蓝
-  { color: '#0ea5e9', pos: 0.5 },  // 天蓝
-  { color: '#06b6d4', pos: 1 }     // 青色
-]);
-
-// 应用到文本
-console.log(blueGradient('To be at the intersection of technology and liberal arts.'));
-```
-
-### 动画循环
-```typescript
-// 使用3种颜色组合创造流动效果
-const gradients = [
-  gradient('#1e3a8a', '#0ea5e9', '#06b6d4'),
-  gradient('#0ea5e9', '#06b6d4', '#1e3a8a'),
-  gradient('#06b6d4', '#1e3a8a', '#0ea5e9'),
-];
-
-// 循环显示 8 帧，每帧 100ms
-for (let i = 0; i < 8; i++) {
-  const frameGradient = gradients[i % 3];
-  process.stdout.write('\r' + frameGradient(text));
-  await delay(100);
-}
-```
-
-## 🔧 后续优化建议
-
-1. ✨ 添加 `--no-animation` 参数跳过动画
-2. 🎨 支持自定义主题色
-3. ⚡ 考虑懒加载非必要模块
-4. 📦 使用 esbuild 打包减小体积
-
----
-
-**最佳实践**：现代 CLI 工具应该兼顾美观性和性能，0.8秒的动画是一个很好的平衡点，既不会让用户感到等待，又能提供愉悦的视觉体验。同时，真正的 Vim 键位支持让工具对开发者更加友好。
+# CHANGELOG
+
+## [1.0.2] - 2025-11-27
+
+### Added
+- **Terminal Documentation Viewer**: Browse and read Markdown documentation from nbtca/documents repository directly in terminal
+  - GitHub API integration for fetching directory structure and file contents
+  - Recursive directory navigation with [DIR] and [MD] indicators
+  - VitePress syntax cleaning (frontmatter, containers, [[toc]], HTML comments)
+  - Terminal Markdown rendering using marked-terminal
+  - Browser fallback on network errors or user preference
+  - Retry mechanism for failed network requests
+
+### Changed
+- **ASCII-Only Interface**: Removed all emoji icons for maximum terminal compatibility
+  - Replaced emoji with ASCII symbols: [*], [?], [x], [..], [DIR], [MD], [ <], [ ^], [ *]
+  - Works on all terminal emulators, SSH sessions, tmux, and legacy systems
+  - Follows Unix/Linux terminal conventions
+  - Professional, minimalist design
+
+### Improved
+- **Terminal UX Enhancements**:
+  - Added keybinding hints to main menu: "Navigation: j/k or ↑/↓ | Jump: g/G | Quit: q or Ctrl+C"
+  - Added ESC key infrastructure for future back navigation and operation cancellation
+  - Standardized navigation symbols across all menus
+  - Better vim-keys.ts documentation with clearer comments
+
+### Fixed
+- **Development Workflow**: Fixed `pnpm run dev` auto-restart issue
+  - Split dev command: `dev` (no watch, for interactive CLI) and `dev:watch` (with watch mode)
+  - Proper exit behavior for interactive CLI testing
+
+### Documentation
+- Added DEVELOPMENT.md: Comprehensive development guide with workflows, testing methods, and common issues
+- Added TERMINAL_UX.md: Terminal UX improvements and compatibility documentation
+- Updated README.md: Professional, concise documentation without decorative elements
+
+### Technical Details
+- Enhanced docs.ts with GitHub repository integration
+- Improved menu.ts with ASCII symbols and keybinding hints
+- Enhanced vim-keys.ts with ESC support and better documentation
+- Better package.json scripts for development workflow
+
+## [1.0.1] - 2025-11-21
+
+### Added
+- New English tagline with smooth blue gradient animation
+- Full Vim keybindings support (j/k/g/G/q)
+- Minimalist UI design inspired by Claude Code CLI
+
+### Improved
+- Smoother gradient animation (24 frames, 1.2s duration)
+- Removed keyboard instruction text for cleaner interface
+- Blue color scheme throughout (deep blue → sky blue → cyan)
+
+### Changed
+- q key now exits the application
+- Removed Chinese tagline
+- Simplified menu layout
+
+### Removed
+- Unused DATA_MANAGEMENT.md documentation
+
+### Dependencies
+- Updated gradient-string to ^3.0.0
+- Updated @inquirer/prompts to ^8.0.3
+
+## [1.0.0] - 2025-11-21
+
+### Added
+- Initial release of NBTCA Prompt CLI tool
+- Interactive terminal menu system
+- Event calendar integration
+- Repair service information
+- Knowledge base access
+- Quick links to official website and GitHub
+- About section with project information

package/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 渲染美观
+- [ ] 错误处理友好
+- [ ] 导航流畅