Spaces:
Running
Running
| # Contributing to Virtual Kimi | |
| Thank you for your interest in contributing to Virtual Kimi! This document provides guidelines and information for contributors. | |
| ## Table of Contents | |
| - [Code of Conduct](#code-of-conduct) | |
| - [Getting Started](#getting-started) | |
| - [Development Setup](#development-setup) | |
| - [Contribution Guidelines](#contribution-guidelines) | |
| - [Project Structure](#project-structure) | |
| - [Coding Standards](#coding-standards) | |
| - [Testing](#testing) | |
| - [Pull Request Process](#pull-request-process) | |
| - [Issue Reporting](#issue-reporting) | |
| ## Code of Conduct | |
| We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and constructive in all interactions. | |
| ### Expected Behavior | |
| - Use welcoming and inclusive language | |
| - Be respectful of differing viewpoints and experiences | |
| - Gracefully accept constructive criticism | |
| - Focus on what is best for the community | |
| - Show empathy towards other community members | |
| ## Getting Started | |
| ### Prerequisites | |
| - Modern web browser (Chrome, Edge, Firefox recommended) | |
| - Basic knowledge of JavaScript, HTML, and CSS | |
| - Git for version control | |
| - Text editor or IDE of your choice | |
| ### First Contribution | |
| 1. Fork the repository | |
| 2. Clone your fork locally | |
| 3. Create a new branch for your feature/fix | |
| 4. Make your changes | |
| 5. Test thoroughly | |
| 6. Submit a pull request | |
| ## Development Setup | |
| ### Local Environment | |
| ```bash | |
| # Clone the repository | |
| git clone https://github.com/virtualkimi/virtual-kimi.git | |
| cd virtual-kimi | |
| # Open in browser | |
| # Option 1: Direct file access | |
| open index.html | |
| # Option 2: Local server (recommended) | |
| python -m http.server 8000 | |
| # Navigate to http://localhost:8000 | |
| ``` | |
| ### Development Tools | |
| - **Browser DevTools**: For debugging and testing | |
| - **Live Server**: For hot reload during development | |
| - **Lighthouse**: For performance auditing | |
| - **Accessibility tools**: For ensuring inclusive design | |
| ## Contribution Guidelines | |
| ### Types of Contributions | |
| - **Bug fixes**: Resolve existing issues | |
| - **Feature additions**: New functionality | |
| - **Performance improvements**: Optimization and efficiency | |
| - **Documentation**: Improve guides and comments | |
| - **Localization**: Translation and internationalization | |
| - **Plugin development**: Extend functionality | |
| - **Testing**: Add or improve test coverage | |
| ### Before You Start | |
| 1. Check existing issues and pull requests | |
| 2. Open an issue to discuss major changes | |
| 3. Ensure your idea aligns with the project goals | |
| 4. Consider the impact on existing functionality | |
| ## Project Structure | |
| ### Core Files | |
| ``` | |
| ├── index.html # Main application | |
| ├── kimi-script.js # Primary initialization | |
| ├── kimi-database.js # Data persistence | |
| ├── kimi-llm-manager.js # AI integration | |
| ├── kimi-emotion-system.js # Emotion analysis | |
| ├── kimi-memory-system.js # Memory management | |
| ├── kimi-voices.js # Speech synthesis | |
| ├── kimi-appearance.js # Theme management | |
| └── kimi-utils.js # Utility functions | |
| ``` | |
| ### Module Dependencies | |
| - **Core System**: Database → Security → Config | |
| - **AI System**: LLM Manager → Emotion System → Memory System | |
| - **UI System**: Appearance → Utils → Module functions | |
| - **Localization**: i18n → All user-facing modules | |
| ### Adding New Features | |
| #### New Memory Categories | |
| ```javascript | |
| // In kimi-memory-system.js | |
| const newCategory = { | |
| name: "custom_category", | |
| icon: "fas fa-custom-icon", | |
| keywords: ["keyword1", "keyword2"], | |
| confidence: 0.7 | |
| }; | |
| // Add to MEMORY_CATEGORIES constant | |
| ``` | |
| #### New Themes | |
| ```javascript | |
| // Create plugin in kimi-plugins/custom-theme/ | |
| // manifest.json | |
| { | |
| "name": "Custom Theme", | |
| "version": "1.0.0", | |
| "type": "theme", | |
| "style": "theme.css", | |
| "enabled": true | |
| } | |
| ``` | |
| #### New AI Models | |
| ```javascript | |
| // In kimi-llm-manager.js | |
| "custom/model-id": { | |
| name: "Custom Model", | |
| provider: "Custom Provider", | |
| type: "openrouter", | |
| contextWindow: 8000, | |
| pricing: { input: 0.1, output: 0.2 }, | |
| strengths: ["Custom", "Feature"] | |
| } | |
| ``` | |
| ## Coding Standards | |
| ### JavaScript Style | |
| - Use ES6+ features and modern syntax | |
| - Prefer `const` and `let` over `var` | |
| - Use meaningful variable and function names in English | |
| - Follow camelCase for variables and functions | |
| - Use PascalCase for classes and constructors | |
| ### Code Organization | |
| - Keep functions focused and single-purpose | |
| - Use async/await for asynchronous operations | |
| - Handle errors gracefully with try/catch blocks | |
| - Add JSDoc comments for complex functions | |
| - Group related functionality in modules | |
| ### Example Code Style | |
| ```javascript | |
| /** | |
| * Analyzes user input for emotional content and updates personality traits | |
| * @param {string} text - User input text | |
| * @param {string} emotion - Detected emotion type | |
| * @returns {Promise<Object>} Updated personality traits | |
| */ | |
| async function updatePersonalityFromEmotion(text, emotion) { | |
| try { | |
| // Validate input | |
| if (!text || typeof text !== "string") { | |
| throw new Error("Invalid input text"); | |
| } | |
| // Process emotion | |
| const traits = await this.processEmotionalContent(text, emotion); | |
| // Update database | |
| await this.db.setPersonalityBatch(traits); | |
| return traits; | |
| } catch (error) { | |
| console.error("Error updating personality:", error); | |
| throw error; | |
| } | |
| } | |
| ``` | |
| ### CSS Guidelines | |
| - Use CSS custom properties (variables) for theming | |
| - Follow BEM methodology for class naming | |
| - Ensure responsive design principles | |
| - Maintain accessibility standards | |
| - Use semantic HTML elements | |
| ### HTML Standards | |
| - Use semantic HTML5 elements | |
| - Include proper ARIA labels for accessibility | |
| - Ensure proper heading hierarchy | |
| - Add meaningful alt text for images | |
| - Validate markup regularly | |
| ## Testing | |
| ### Manual Testing Checklist | |
| - [ ] Application loads without errors | |
| - [ ] All core features function correctly | |
| - [ ] Voice recognition works (in supported browsers) | |
| - [ ] Memory system stores and retrieves data | |
| - [ ] Theme switching works properly | |
| - [ ] Responsive design on mobile devices | |
| - [ ] Cross-browser compatibility | |
| - [ ] Accessibility with keyboard navigation | |
| ### Browser Testing | |
| Test in the following browsers: | |
| - Chrome (latest 2 versions) | |
| - Edge (latest 2 versions) | |
| - Firefox (latest 2 versions) | |
| - Safari (latest version, if possible) | |
| ### Performance Testing | |
| - Check loading times | |
| - Monitor memory usage | |
| - Test with large conversation histories | |
| - Verify smooth animations | |
| - Ensure responsive UI interactions | |
| ## Pull Request Process | |
| ### Before Submitting | |
| 1. **Test thoroughly**: Ensure your changes work as expected | |
| 2. **Check compatibility**: Test across different browsers | |
| 3. **Update documentation**: Modify README.md if needed | |
| 4. **Clean up code**: Remove debugging code and comments | |
| 5. **Commit messages**: Use clear, descriptive commit messages | |
| ### PR Template | |
| ```markdown | |
| ## Description | |
| Brief description of changes made. | |
| ## Type of Change | |
| - [ ] Bug fix | |
| - [ ] New feature | |
| - [ ] Performance improvement | |
| - [ ] Documentation update | |
| - [ ] Other: **\_** | |
| ## Testing | |
| - [ ] Tested in Chrome | |
| - [ ] Tested in Edge | |
| - [ ] Tested in Firefox | |
| - [ ] Tested on mobile | |
| - [ ] No errors in console | |
| ## Screenshots (if applicable) | |
| Add screenshots of UI changes. | |
| ## Additional Notes | |
| Any additional context or considerations. | |
| ``` | |
| ### Review Process | |
| 1. Maintainers review code for quality and functionality | |
| 2. Feedback provided through PR comments | |
| 3. Make requested changes and push updates | |
| 4. Final approval and merge | |
| ## Issue Reporting | |
| ### Bug Reports | |
| Include the following information: | |
| - Browser and version | |
| - Operating system | |
| - Steps to reproduce | |
| - Expected behavior | |
| - Actual behavior | |
| - Console errors (if any) | |
| - Screenshots (if applicable) | |
| ### Feature Requests | |
| - Clear description of the feature | |
| - Use case and benefits | |
| - Possible implementation approach | |
| - Any relevant examples or mockups | |
| ### Issue Labels | |
| - `bug`: Something isn't working | |
| - `enhancement`: New feature or improvement | |
| - `documentation`: Documentation updates | |
| - `good first issue`: Good for newcomers | |
| - `help wanted`: Community assistance needed | |
| - `plugin`: Related to plugin system | |
| - `accessibility`: Accessibility improvements | |
| ## Development Tips | |
| ### Performance Optimization | |
| - Minimize DOM manipulations | |
| - Use event delegation for dynamic content | |
| - Implement proper cleanup for event listeners | |
| - Optimize database queries with batch operations | |
| ### Accessibility | |
| - Test with keyboard navigation | |
| - Verify screen reader compatibility | |
| - Ensure sufficient color contrast | |
| - Add appropriate ARIA labels | |
| ## Community | |
| ### Getting Help | |
| - Open an issue for technical questions | |
| - Check existing documentation first | |
| - Be specific about your problem or question | |
| ### Communication | |
| - Be respectful and professional | |
| - Provide context and details | |
| - Be patient with response times | |
| - Help others when possible | |
| Thank you for contributing to Virtual Kimi! Your efforts help create a better AI companion experience for everyone. | |