From 7e00a58579d4f71f69a86981617949eb0604fd22 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 29 Aug 2025 14:24:56 +0000
Subject: [PATCH 1/5] Initial plan


From f2709c098243122342306f7489309c2fda0789b0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 29 Aug 2025 14:40:35 +0000
Subject: [PATCH 2/5] Create comprehensive GitHub Copilot instructions file

Added .github/copilot-instructions.md with complete development guidelines including:
- Project setup and requirements (Node.js 20+, PNPM)
- Development workflow and validation scenarios
- Comprehensive PR review patterns and best practices
- React Bootstrap component usage standards
- GitHub API integration with mobx-github
- Internationalization requirements
- Code quality and architecture guidelines
- Troubleshooting guide and common issues

Incorporates all key patterns from PR review analysis and follows
the reference structure from ActivityHub-PWA project.
---
 .github/copilot-instructions.md | 335 ++++++++++++++++++++++++++++++++
 .husky/pre-commit               |   2 +-
 2 files changed, 336 insertions(+), 1 deletion(-)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..5aeac8f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,335 @@
+# Open Source Bazaar - GitHub Copilot Instructions
+
+Open Source Bazaar 是一个基于 Next.js 15、TypeScript、React Bootstrap 和 MobX 构建的开源项目展示平台。它包含许可证过滤器、Wiki 知识库、志愿者展示、Lark 集成等功能。
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Critical Requirements
+
+⚠️ **MANDATORY NODE.JS VERSION**: This project requires **Node.js >=20**. The build works on Node.js 20+ but may have warnings.
+
+- Check Node.js version: `node --version`
+- Development and linting commands work on Node.js 20+
+- Use **PNPM** as package manager, not npm or yarn
+
+## Working Effectively
+
+### Initial Setup (REQUIRED for all development)
+
+1. **Install global pnpm**: `npm install -g pnpm`
+2. **Install dependencies**: `pnpm install` -- takes 1-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
+3. **Verify setup**: `pnpm --version` (should be 10.x+)
+
+**Important**: If you see "node_modules missing" error, you MUST run `pnpm install` first before any other commands.
+
+### Development Workflow (FULLY VALIDATED)
+
+- **Start development server**: `pnpm dev` -- starts in 5-15 seconds on http://localhost:3000
+- **Run linting**: `pnpm lint` -- takes 15 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
+- **Run tests**: `pnpm test` -- runs lint-staged + lint, takes 15 seconds. Set timeout to 2+ minutes.
+
+### Build Process
+
+- **Production build**: `pnpm build` -- works on Node.js 20+ (estimated 30s-2 minutes)
+  - NEVER CANCEL. Set timeout to 5+ minutes.
+- **Static export**: Available but not commonly used in development
+
+## Validation Scenarios
+
+After making ANY changes, ALWAYS validate by running through these scenarios:
+
+### Manual Testing Requirements
+
+1. **Start development server**: `pnpm dev` and verify it starts without errors
+2. **Navigate to homepage**: Visit http://localhost:3000 and verify page loads with navigation menu
+3. **Test core pages**:
+   - License filter: http://localhost:3000/license-filter (interactive license selection tool)
+   - Wiki pages: http://localhost:3000/wiki (policy documents from GitHub)
+   - Volunteer page: http://localhost:3000/volunteer (contributor showcase)
+   - Projects: http://localhost:3000/project (GitHub repository listings)
+4. **Test API endpoints**: Verify GitHub API integrations work
+5. **Check responsive design**: Test mobile/desktop layouts with React Bootstrap components
+6. **Verify i18n functionality**: Check Chinese/English language switching works
+
+### Pre-commit Validation
+
+ALWAYS run before committing changes:
+
+```bash
+pnpm lint     # Fix linting issues automatically
+pnpm test     # Runs linting + staged file checks
+```
+
+## Key Project Structure
+
+### Important Directories
+
+- `pages/` - Next.js pages and API routes
+- `components/` - Reusable React components with Bootstrap styling
+- `models/` - MobX stores and data models
+- `translation/` - i18n language files (zh-CN, en-US, zh-TW)
+- `styles/` - CSS and styling files
+- `public/` - Static assets
+
+### Configuration Files
+
+- `package.json` - Dependencies and scripts
+- `next.config.ts` - Next.js configuration with MDX support
+- `tsconfig.json` - TypeScript configuration
+- `eslint.config.ts` - ESLint configuration
+- `babel.config.js` - Babel configuration
+
+### Key Dependencies
+
+- **Next.js 15** - React framework
+- **React Bootstrap 2.10** - UI component library
+- **MobX 6.13** - State management
+- **mobx-github 0.4** - GitHub API integration
+- **mobx-i18n 0.7** - Internationalization
+- **license-filter 0.2** - License filtering functionality
+- **marked 16.2** - Markdown processing
+
+## Development Standards and Best Practices
+
+Based on comprehensive PR review analysis, follow these critical development standards:
+
+### Architecture and Code Organization
+
+#### Component and Import Standards
+
+- **ALWAYS use React Bootstrap components** instead of custom HTML elements
+- Use `<Button>`, `<Badge>`, `<Breadcrumb>`, `<Card>`, `<Container>` from 'react-bootstrap'
+- Import from existing configured clients: use `githubClient` from `models/Base.ts`
+- Use utilities from established libraries: `treeFrom` from 'web-utility'
+- Import `'./Base'` in model files for proper configuration
+
+#### Data and API Integration
+
+- Use **GitHub API** with ContentModel from mobx-github for content management
+- Use configured `githubClient` from `models/Base.ts` for authenticated API calls
+- **Base64 decode** content from GitHub API responses: `atob(item.content)`
+- Replace filesystem reading with GitHub Contents API calls
+- Use `ContentModel('owner', 'repo')` pattern for repository content access
+
+#### Error Handling and Static Generation
+
+- **Natural error throwing** for static generation - let errors bubble up to catch build issues
+- Don't catch errors in `getStaticProps` unless specifically handling them
+- Ensure build passes before pushing - resolve issues at compile time
+
+### UI/UX Standards
+
+#### Component Usage Patterns
+
+```typescript
+// ✅ Correct - use React Bootstrap components
+import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap';
+
+<Button variant="outline-primary" size="sm" href={url} target="_blank">
+  {t('edit_on_github')}
+</Button>
+
+<Badge bg="secondary">{label}</Badge>
+
+// ❌ Wrong - custom HTML elements
+<a href={url} className="btn btn-outline-primary">Edit</a>
+<span className="badge bg-secondary">{label}</span>
+```
+
+#### Semantic HTML Structure
+
+- Use ordered lists (`<ol>`) for countable items, unordered lists (`<ul>`) for navigation
+- Apply proper semantic structure: `<article>`, `<header>`, `<section>`
+- Use `list-unstyled` class for first-level lists to remove default styling
+
+### Code Quality Standards
+
+#### Modern ECMAScript Features
+
+```typescript
+// ✅ Correct - use optional chaining
+node.parent_path?.split('/')
+node.children?.length > 0
+
+// ✅ Correct - let TypeScript infer types when possible
+const renderTree = (nodes: WikiNode[], level = 0) => (
+  // No need for explicit return type annotation
+)
+
+// ❌ Wrong - verbose type annotations where inference works
+const renderTree = (nodes: WikiNode[], level = 0): React.ReactElement => (
+```
+
+#### Import and Type Management
+
+```typescript
+// ✅ Correct - import from established sources
+import { ContentModel } from 'mobx-github';
+import { treeFrom } from 'web-utility';
+import './Base'; // For configuration
+
+// ✅ Correct - minimal exports
+export const policyContentStore = new ContentModel('fpsig', 'open-source-policy');
+
+// ❌ Wrong - unnecessary custom implementations
+// Don't create new GitHub API clients when configured ones exist
+```
+
+### Translation and Internationalization
+
+#### Critical Translation Requirements
+
+- **ALL user-facing text** MUST be translated using i18n system
+- This includes button text, labels, error messages, placeholder text, and dynamic content
+- Use the `t()` function from I18nContext for all translations
+
+#### Translation Patterns
+
+```typescript
+// ✅ Correct - all text translated
+const { t } = useContext(I18nContext);
+
+<p>{t('no_docs_available')}</p>
+<Button>{t('contribute_content')}</Button>
+alert(t('operation_successful'));
+
+// ❌ Wrong - hardcoded text
+<p>暂无政策文档</p>
+<Button>贡献内容</Button>
+alert('操作成功');
+```
+
+#### Translation Key Management
+
+- Use generic terms unless specifically scoped: `t('knowledge_base')` not `t('policy_documents')`
+- Add translation keys to ALL language files: `zh-CN.ts`, `en-US.ts`, `zh-TW.ts`
+- Remove unused translation keys when replacing with generic ones
+
+### Data Modeling and Content Management
+
+#### Content Model Patterns
+
+```typescript
+// ✅ Correct - use ContentModel with configured client
+import { ContentModel } from 'mobx-github';
+import './Base'; // Ensures githubClient configuration
+
+export const policyContentStore = new ContentModel('fpsig', 'open-source-policy');
+
+// Content processing with proper Base64 decoding
+const content = item.content ? atob(item.content) : '';
+```
+
+#### Tree Structure and Navigation
+
+```typescript
+// ✅ Correct - use treeFrom utility for hierarchical data
+import { treeFrom } from 'web-utility';
+
+const tree = treeFrom(nodes, 'path', 'parent_path', 'children');
+```
+
+### GitHub Integration Standards
+
+#### API Usage Patterns
+
+- Use `ContentModel` for repository content access
+- Always decode Base64 content: `atob(item.content)`
+- Import configured `githubClient` from `models/Base.ts`
+- Follow the pattern: `new ContentModel('owner', 'repository')`
+
+#### Authentication and Rate Limiting
+
+- GitHub API authentication is configured in `models/Base.ts`
+- Use the configured client to avoid rate limiting and authentication issues
+- Don't create separate GitHub API instances
+
+### Build and Development Process
+
+#### Pre-commit Standards
+
+1. **Run linting**: `pnpm lint` to auto-fix formatting
+2. **Check build**: Ensure `pnpm build` passes
+3. **Validate translations**: Verify all text is properly translated
+4. **Remove unused code**: Clean up unused imports and translation keys
+
+#### Code Review Compliance
+
+- **Follow exact code suggestions** from reviews when provided
+- Use **minimal approach** - only include explicitly requested functionality
+- **Don't add extra features** not specified in requirements
+- **Address reviewer feedback completely** before requesting re-review
+
+## Common Commands Reference
+
+### Package Management
+
+```bash
+pnpm install          # Install dependencies (1-3 minutes)
+pnpm --version        # Check pnpm version
+```
+
+### Development
+
+```bash
+pnpm dev             # Start development server (5-15s)
+pnpm build           # Production build (30s-2min)
+pnpm start           # Start production server
+```
+
+### Code Quality
+
+```bash
+pnpm lint            # Run ESLint with auto-fix (15s)
+pnpm test            # Run tests (lint-staged + lint, 15s)
+```
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Build and Development Issues
+
+- **"Unsupported engine" warnings**: Expected on Node.js <22, development still works
+- **Build hangs**: Never cancel builds - they may take several minutes, set appropriate timeouts
+- **Missing dependencies**: Always run `pnpm install` first
+
+#### Component and Styling Issues
+
+- **Custom HTML not working**: Replace with React Bootstrap components
+- **Translation not showing**: Ensure all text uses `t()` function and keys exist in all language files
+- **GitHub API errors**: Verify you're using configured `githubClient` from `models/Base.ts`
+
+#### Data and Content Issues
+
+- **Base64 content errors**: Use `atob(item.content)` to decode GitHub API responses
+- **Missing content**: Check ContentModel configuration and repository access
+- **Tree structure problems**: Use `treeFrom()` utility from web-utility
+
+### Development Environment Setup
+
+- Clear browser cache if components don't render properly
+- Restart development server after major configuration changes
+- Verify all translation files are updated when adding new keys
+
+## Project-Specific Patterns
+
+### Wiki System Architecture
+
+- Uses GitHub ContentModel to access policy documents from `fpsig/open-source-policy` repository
+- Renders markdown content with front-matter metadata
+- Supports hierarchical document structure with breadcrumb navigation
+
+### License Filter Integration
+
+- Interactive multi-step license selection process
+- Uses `license-filter` package for license recommendation logic
+- Supports multiple languages with comprehensive i18n coverage
+
+### Volunteer Management
+
+- Displays GitHub organization contributors
+- Integrates with OSS Insight widgets for contributor analytics
+- Uses GitHub API for real-time contributor data
+
+Always prioritize these project-specific standards over generic Next.js or React guidance when working in this specific codebase.
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 255814b..38cd9e8 100644
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +1 @@
-npm test
+pnpm test

From f8a49e7f722d714ea3bf44c9233f24a574c94f76 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 29 Aug 2025 18:23:36 +0000
Subject: [PATCH 3/5] Address PR feedback: translate to English, fix package
 manager refs, update dependency names

Co-authored-by: TechQuery <19969570+TechQuery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 16 ++++++++--------
 .husky/pre-commit               |  2 +-
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5aeac8f..d193839 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,6 +1,6 @@
 # Open Source Bazaar - GitHub Copilot Instructions
 
-Open Source Bazaar 是一个基于 Next.js 15、TypeScript、React Bootstrap 和 MobX 构建的开源项目展示平台。它包含许可证过滤器、Wiki 知识库、志愿者展示、Lark 集成等功能。
+Open Source Bazaar is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. It includes license filters, Wiki knowledge base, volunteer showcase, Lark integration, and other features.
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
@@ -10,7 +10,7 @@ Always reference these instructions first and fallback to search or bash command
 
 - Check Node.js version: `node --version`
 - Development and linting commands work on Node.js 20+
-- Use **PNPM** as package manager, not npm or yarn
+- Use **PNPM** as package manager, not NPM or Yarn
 
 ## Working Effectively
 
@@ -57,7 +57,7 @@ ALWAYS run before committing changes:
 
 ```bash
 pnpm lint     # Fix linting issues automatically
-pnpm test     # Runs linting + staged file checks
+npm test     # Runs linting + staged file checks
 ```
 
 ## Key Project Structure
@@ -84,10 +84,10 @@ pnpm test     # Runs linting + staged file checks
 - **Next.js 15** - React framework
 - **React Bootstrap 2.10** - UI component library
 - **MobX 6.13** - State management
-- **mobx-github 0.4** - GitHub API integration
-- **mobx-i18n 0.7** - Internationalization
-- **license-filter 0.2** - License filtering functionality
-- **marked 16.2** - Markdown processing
+- **MobX-GitHub 0.4** - GitHub API integration
+- **MobX-i18n 0.7** - Internationalization
+- **License-Filter 0.2** - License filtering functionality
+- **Marked 16.2** - Markdown processing
 
 ## Development Standards and Best Practices
 
@@ -100,7 +100,7 @@ Based on comprehensive PR review analysis, follow these critical development sta
 - **ALWAYS use React Bootstrap components** instead of custom HTML elements
 - Use `<Button>`, `<Badge>`, `<Breadcrumb>`, `<Card>`, `<Container>` from 'react-bootstrap'
 - Import from existing configured clients: use `githubClient` from `models/Base.ts`
-- Use utilities from established libraries: `treeFrom` from 'web-utility'
+- Use utilities from established libraries: 'web-utility'
 - Import `'./Base'` in model files for proper configuration
 
 #### Data and API Integration
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 38cd9e8..255814b 100644
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +1 @@
-pnpm test
+npm test

From a9c5b0ab154a338994c1190285f59621967d612c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 29 Aug 2025 18:41:01 +0000
Subject: [PATCH 4/5] Changes before error encountered

Co-authored-by: TechQuery <19969570+TechQuery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 20 --------------------
 1 file changed, 20 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index d193839..8ed1a5d 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -56,7 +56,6 @@ After making ANY changes, ALWAYS validate by running through these scenarios:
 ALWAYS run before committing changes:
 
 ```bash
-pnpm lint     # Fix linting issues automatically
 npm test     # Runs linting + staged file checks
 ```
 
@@ -98,25 +97,9 @@ Based on comprehensive PR review analysis, follow these critical development sta
 #### Component and Import Standards
 
 - **ALWAYS use React Bootstrap components** instead of custom HTML elements
-- Use `<Button>`, `<Badge>`, `<Breadcrumb>`, `<Card>`, `<Container>` from 'react-bootstrap'
-- Import from existing configured clients: use `githubClient` from `models/Base.ts`
 - Use utilities from established libraries: 'web-utility'
 - Import `'./Base'` in model files for proper configuration
 
-#### Data and API Integration
-
-- Use **GitHub API** with ContentModel from mobx-github for content management
-- Use configured `githubClient` from `models/Base.ts` for authenticated API calls
-- **Base64 decode** content from GitHub API responses: `atob(item.content)`
-- Replace filesystem reading with GitHub Contents API calls
-- Use `ContentModel('owner', 'repo')` pattern for repository content access
-
-#### Error Handling and Static Generation
-
-- **Natural error throwing** for static generation - let errors bubble up to catch build issues
-- Don't catch errors in `getStaticProps` unless specifically handling them
-- Ensure build passes before pushing - resolve issues at compile time
-
 ### UI/UX Standards
 
 #### Component Usage Patterns
@@ -233,10 +216,7 @@ const tree = treeFrom(nodes, 'path', 'parent_path', 'children');
 
 #### API Usage Patterns
 
-- Use `ContentModel` for repository content access
-- Always decode Base64 content: `atob(item.content)`
 - Import configured `githubClient` from `models/Base.ts`
-- Follow the pattern: `new ContentModel('owner', 'repository')`
 
 #### Authentication and Rate Limiting
 

From 09b1d351996a6cc3974e317d1251661fa996e612 Mon Sep 17 00:00:00 2001
From: TechQuery <shiy2008@gmail.com>
Date: Sat, 30 Aug 2025 07:00:22 +0800
Subject: [PATCH 5/5] [refactor] summarize Example codes of Copilot instruction

---
 .github/copilot-instructions.md | 74 +++++++++------------------------
 1 file changed, 20 insertions(+), 54 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 8ed1a5d..2024642 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -100,6 +100,11 @@ Based on comprehensive PR review analysis, follow these critical development sta
 - Use utilities from established libraries: 'web-utility'
 - Import `'./Base'` in model files for proper configuration
 
+#### Error Handling and Static Generation
+
+- **Natural error throwing** for static generation - let errors bubble up to catch build issues
+- Ensure build passes before pushing - resolve issues at compile time
+
 ### UI/UX Standards
 
 #### Component Usage Patterns
@@ -129,34 +134,16 @@ import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap';
 
 #### Modern ECMAScript Features
 
-```typescript
-// ✅ Correct - use optional chaining
-node.parent_path?.split('/')
-node.children?.length > 0
-
-// ✅ Correct - let TypeScript infer types when possible
-const renderTree = (nodes: WikiNode[], level = 0) => (
-  // No need for explicit return type annotation
-)
-
-// ❌ Wrong - verbose type annotations where inference works
-const renderTree = (nodes: WikiNode[], level = 0): React.ReactElement => (
-```
+- Use optional chaining and modern JavaScript features
+- Let TypeScript infer types when possible to avoid verbose annotations
+- Use modern ECMAScript patterns for cleaner, more maintainable code
 
 #### Import and Type Management
 
-```typescript
-// ✅ Correct - import from established sources
-import { ContentModel } from 'mobx-github';
-import { treeFrom } from 'web-utility';
-import './Base'; // For configuration
-
-// ✅ Correct - minimal exports
-export const policyContentStore = new ContentModel('fpsig', 'open-source-policy');
-
-// ❌ Wrong - unnecessary custom implementations
-// Don't create new GitHub API clients when configured ones exist
-```
+- Import from established sources: ContentModel from mobx-github, utilities from web-utility
+- Import configuration files where needed: `'./Base'` for GitHub client setup
+- Use minimal exports and avoid unnecessary custom implementations
+- Use configured clients rather than creating new ones
 
 ### Translation and Internationalization
 
@@ -168,19 +155,9 @@ export const policyContentStore = new ContentModel('fpsig', 'open-source-policy'
 
 #### Translation Patterns
 
-```typescript
-// ✅ Correct - all text translated
-const { t } = useContext(I18nContext);
-
-<p>{t('no_docs_available')}</p>
-<Button>{t('contribute_content')}</Button>
-alert(t('operation_successful'));
-
-// ❌ Wrong - hardcoded text
-<p>暂无政策文档</p>
-<Button>贡献内容</Button>
-alert('操作成功');
-```
+- Use the `t()` function from I18nContext for all user-facing text
+- Translate all button text, labels, error messages, and dynamic content
+- Avoid hardcoded text in any language
 
 #### Translation Key Management
 
@@ -192,25 +169,14 @@ alert('操作成功');
 
 #### Content Model Patterns
 
-```typescript
-// ✅ Correct - use ContentModel with configured client
-import { ContentModel } from 'mobx-github';
-import './Base'; // Ensures githubClient configuration
-
-export const policyContentStore = new ContentModel('fpsig', 'open-source-policy');
-
-// Content processing with proper Base64 decoding
-const content = item.content ? atob(item.content) : '';
-```
+- Use ContentModel with configured client from mobx-github
+- Import configuration via `'./Base'` to ensure proper GitHub client setup
+- Handle Base64 content decoding when processing GitHub API responses
 
 #### Tree Structure and Navigation
 
-```typescript
-// ✅ Correct - use treeFrom utility for hierarchical data
-import { treeFrom } from 'web-utility';
-
-const tree = treeFrom(nodes, 'path', 'parent_path', 'children');
-```
+- Use `treeFrom` utility from web-utility for hierarchical data structures
+- Follow established patterns for tree node organization and navigation
 
 ### GitHub Integration Standards