**语言 / Language:** [中文](./README-zh.md) | [English](./README.md)
# AIS – Context-Aware Error-Analysis Learning Assistant
<div align="center">
[📖 Installation Guide](#installation) · [🌏 Official Docs](https://kangvcar.github.io/ais) · [🎞️ Feature Demo (Mainland China)](https://www.bilibili.com/video/BV1wDvwzDEEz) · [✨ Interactive Demo](https://app.arcade.software/share/hZWhYIC7dsD7Ed1GPv0G)
<a href="https://www.producthunt.com/products/ais?embed=true&utm_source=badge-featured&utm_medium=badge&utm_source=badge-ais" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1009557&theme=light&t=1756203101298" alt="AIS - Smart terminal AI assistant for instant error analysis | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
[](https://www.youtube.com/watch?v=T8Q-y2BdFlw "This AI Terminal Assistant Just Changed How I Debug Code Forever | AIS Demo")
</div>
## Overview
Through a deep shell-integration architecture, AIS achieves multi-dimensional context awareness and intelligent error analysis. It automatically collects execution-environment information and pinpoints issues precisely; inside the terminal it provides context-based solutions and structured learning guidance. This eliminates the usual search hopping and blind trial-and-error in traditional error handling, significantly improving both problem-solving efficiency and the speed of skill accumulation.
### 🌟 Core Features
#### 🔍 Intelligent Error Analysis
* **Automatic detection** – Automatically analyzes the cause when a command fails
* **Context awareness** – Combines current directory, Git status, project type, and other environment info
* **Personalized suggestions** – Offers targeted solutions based on the user’s skill level
* **Safety levels** – Every suggestion is labeled with a risk level to keep operations safe
#### 📚 Intelligent Learning System
* **Interactive teaching** – Explains the “why,” not just the “how”
* **Topic learning** – Dive into focused topics like Git, Docker, and Vim
* **Progressive content** – Adjusts depth according to user level
* **Practice-oriented** – Provides runnable command examples and best practices
#### 🎯 Intelligent Context Awareness
* **Environment-aware Q\&A** – `ais ask` delivers precise answers based on the current system environment
* **Three-level context collection** – Configurable information-collection levels: minimal/standard/detailed
* **System status analysis** – Automatically detects hardware configuration, network status, and running services
* **Project-type recognition** – Intelligently identifies tech stacks using Git status and project files
#### 🔌 Strong Integrations
* **Shell integration** – Automatic error capture for Bash and Zsh
* **Multi-AI support** – Compatible with OpenAI, Ollama, Claude, and more
* **Privacy protection** – Local data storage; sensitive information is automatically filtered
* **Cross-platform** – Supports Linux and macOS
---
## <a id="installation"></a>📦 Installation
### System Requirements
* **Python**: 3.9+ (3.11+ recommended)
* **Operating Systems**: Linux, macOS
* **Network**: Required to download dependencies and access AI services
* **Disk Space**: At least 100 MB free space
### ⚡ One-Click Install (Recommended)
```bash
# Smart install – automatically detects the environment and chooses the best method
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash
# Mainland China users can use the Gitee mirror (faster and more stable)
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash
```
**The install script will automatically:**
* 🔍 Detect the current environment (personal/team/container)
* 🎯 Choose the best installation method (pipx per-user/system-wide/containerized)
* 📦 Install pipx and AIS
* 🔧 Configure shell integration
* ✓ Run a health check
### 🗑️ One-Click Uninstall
```bash
# Smart uninstall – automatically detects how AIS was installed and cleans it completely
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/uninstall.sh | bash
# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/uninstall.sh | bash
```
**The uninstall script will automatically:**
* 🔍 Detect how AIS was installed (pipx per-user/system-wide)
* 🗑️ Uninstall the AIS package and dependencies
* 🧹 Clean shell-integration configuration
* 📁 Let you choose to keep or delete user data
* ✓ Verify that uninstallation is complete
### 🎯 Installation by Scenario
<details>
<summary><b>🐳 Docker Container (Recommended – zero configuration)</b></summary>
```bash
# Run the latest version directly
docker run -it --rm kangvcar/ais:latest
# Or use it interactively
docker run -it --rm -v $(pwd):/workspace kangvcar/ais:latest bash
# Use Docker Compose (recommended for persistent configuration)
curl -O https://raw.githubusercontent.com/kangvcar/ais/main/docker-compose.yml
docker-compose up -d ais
docker-compose exec ais bash
```
**Advantages**: Zero-config startup, environment isolation, cross-platform consistency, ARM64 supported
</details>
<details>
<summary><b>👨💻 Individual Developer (Python environment)</b></summary>
```bash
# Per-user install (safest)
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --user
# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --user
# Or install manually
pipx install ais-terminal
ais setup
# HTML report visualization is now included by default
```
**Advantages**: Maximum safety, isolated virtual environment, no sudo required
</details>
<details>
<summary><b>🏢 Team/Enterprise Environment</b></summary>
```bash
# System-wide installation (available to all users)
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --system
# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --system
```
**Advantages**: Available to all users, maintains safety isolation, centralized management and updates
</details>
<details>
<summary><b>🐳 Container/Cloud Environment</b></summary>
```bash
# Dockerized installation
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/docker-install.sh | bash
# Or run directly
docker run -it --rm ais:latest
```
**Advantages**: Environment consistency, rapid deployment, easy scaling, full isolation
</details>
<details>
<summary><b>🔧 Developers/Contributors</b></summary>
```bash
# Install from source
git clone https://github.com/kangvcar/ais.git
cd ais
pipx install -e .
# Or use a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,html]" # Includes dev and HTML visualization dependencies
```
**Advantages**: Live edits, complete dev toolchain, easy debugging
</details>
### ✓ Verify Installation
```bash
# Check version
ais --version
# Test basic functionality
ais ask "Hello, AIS!"
# Test automatic error analysis (enter a command with an intentional typo)
mkdirr /tmp/test
```
---
## <a id="quickstart"></a>🚀 Quick Start
### Basic Configuration
```bash
# View current configuration
ais config
# Set context-collection level
ais config --set context_level=detailed
```
### Core Feature Walkthrough
#### 💬 Environment-Aware Q\&A
```bash
# Environment-aware Q&A based on the current system
ais ask "What is my system configuration like? How is the hardware performance?"
ais ask "Is my network connection normal? Any security suggestions?"
ais ask "Given my current project type, how can I optimize performance?"
# Traditional technical Q&A (still supported)
ais ask "How do I check system memory usage?"
ais ask "How do Docker containers mount directories?"
ais ask "How do I resolve Git merge conflicts?"
# Configure context-collection level
ais config --set context_level=minimal # Basic information
ais config --set context_level=standard # Standard information
ais config --set context_level=detailed # Full information
```
#### 📖 Topic Learning
```bash
ais learn git # Learn Git version control
ais learn docker # Learn containerization
ais learn vim # Learn the text editor
ais learn ssh # Learn remote access
```
#### 🔍 Intelligent Error Analysis
```bash
# These erroneous commands will automatically trigger AI analysis
pytho --version # Spelling error
ls /not/exist # Path does not exist
git statuss # Command error
```
#### 📊 Learning Growth Report
```bash
ais report # Generate a text-format learning report
ais report --html # Generate an HTML visualization report
ais report --html -o my_report.html --open # Generate and open the HTML report
# History management
ais history # View recent command history
ais history --limit 20 # Show 20 command records
ais history 3 # View detailed analysis of record #3
```
---
## 📚 Detailed Features
### Environment-Aware Q\&A – `ais ask`
Intelligent Q\&A based on the current system environment, automatically sensing hardware configuration, network status, project type, and more:
```bash
# 🖥️ System environment-aware Q&A
ais ask "How is my system performance? Do I need to optimize?"
ais ask "Are my currently open ports secure?"
ais ask "What is the status of my network connection?"
# 🚀 Project environment-aware Q&A
ais ask "What type of project is this? How do I install dependencies?"
ais ask "Given the current Git status, how should I commit?"
ais ask "How do I optimize this Python project in my current environment?"
# 📚 Traditional technical Q&A (still supported)
ais ask "What does Linux file permission 755 mean?"
ais ask "How can I optimize Python script performance?"
ais ask "What are the steps to configure Nginx as a reverse proxy?"
# ⚙️ Context-level configuration
ais config --set context_level=minimal # Basics: system info, Git, project type
ais config --set context_level=standard # Standard: + file list, command history
ais config --set context_level=detailed # Detailed: + network, permissions, services
# 📋 View detailed help
ais ask --help-detail
```
**New highlights**:
* 🧠 **Smart context collection**: Automatically detects CPU, memory, network, and service status
* 🎯 **Environment-aware answers**: Targeted advice based on actual system configuration
* ⚡ **Three configurable tiers**: From lightweight to detailed, fit for different scenarios
* 🔒 **Privacy**: Sensitive info is auto-filtered; protected directories are skipped
### Learning Growth Report – `ais report`
Generate a detailed, personalized learning-growth analysis report in text or visual HTML:
```bash
# 📊 Text report (default)
ais report
# 📈 HTML visualization report (recommended)
ais report --html
ais report --html -o custom_report.html
ais report --html --open # Automatically open in the browser after generation
# 📋 View detailed help
ais report --help
```
#### 🌟 HTML Visualization Features
**6 professional chart types**:
* 📈 **Error trend chart**: 30-day error trend to show progress
* 🎯 **Skill assessment radar**: Visualize multi-dimensional skill levels
* ⏰ **Time heatmap**: Distribution over time to find learning patterns
* 📊 **Command frequency**: Rank most error-prone commands for focus
* 🔍 **Error-type distribution**: Pie chart of error patterns for targeted fixes
* 📈 **Learning-progress trend**: Dual-axis view of error reduction and skill growth
**Modern UX**:
* 🎨 **Responsive design**: Great on desktop, tablet, and mobile
* 🖱️ **Interactive charts**: Hover tooltips, zooming, and drill-down
* 💡 **AI insights**: Personalized analysis and improvement tips
* 🌐 **Browser-friendly**: Works in modern browsers; no plugins needed
**Flexible options**:
```bash
# Custom output filename
ais report --html -o "2024-Learning-Report.html"
# Open in a browser after generation
ais report --html --open
# Combine options
ais report --html -o weekly_progress.html --open
```
**Data security**:
* 📊 All data generated locally; nothing uploaded to the cloud
* 🔒 Sensitive information is auto-filtered
* 📁 Supports offline viewing and sharing
### Knowledge Learning – `ais learn`
Systematic learning for command-line tools and concepts:
```bash
ais learn # List all available topics
ais learn git # Complete Git tutorial
ais learn docker # In-depth containerization
ais learn linux # Linux system-administration basics
```
### Managing AI Providers
Supports multiple AI providers with easy switching:
```bash
# List available providers
ais provider-list
# Add a local Ollama provider
ais provider-add ollama \
--url http://localhost:11434/v1/chat/completions \
--model llama3
# Switch provider
ais provider-use ollama
```
### Shell-Integration Configuration
AIS supports automatic error analysis; shell integration is required:
```bash
# Automatic configuration
ais setup
# Test whether the integration works
ais test-integration
```
---
## ⚙️ Advanced Configuration
### Smart Context-Collection Settings
Independently control context collection for error analysis and for `ask` Q\&A:
```bash
# Context level for error analysis (automatic analysis feature)
ais config --set context_level=minimal # Basic information
ais config --set context_level=standard # Standard information (default)
ais config --set context_level=detailed # Detailed information
# Context level for ask Q&A (new)
ais config --set ask.context_level=minimal # System basics
ais config --set ask.context_level=standard # + project and Git information
ais config --set ask.context_level=detailed # + network, permissions, services
# Control automatic analysis
ais config --set auto_analysis=true # Enable automatic analysis
ais config --set auto_analysis=false # Disable automatic analysis
# View current configuration
ais config
```
**Context-collection details**:
| Level | Included in error analysis | Included in ask Q\&A |
| ------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------- |
| **minimal** | Command, exit code, directory, user | System info, CPU/memory, network reachability, listening ports, running services |
| **standard** | + File list, Git status, command history | + Project type, Git details, file list |
| **detailed** | + System info, environment variables, full directory | + Permission info, detailed network status, full environment |
### Privacy and Security
AIS takes privacy and data security seriously:
* **Local storage** – All data stored in a local SQLite database
* **Sensitive-info filtering** – Passwords, keys, and similar are filtered automatically
* **Configurable context levels** – You control the scope of information collection
* **Open source and transparent** – Fully open source; code is publicly available
---
## 🆕 Latest Feature Highlights
### 📊 HTML Visualization Report System (v2.5.2)
AIS now supports professional HTML visualization reports, turning dry data into clear, attractive charts:
#### 🎨 **Modern visualization design**
```bash
$ ais report --html --open
# Automatically generates an HTML report containing:
📈 Error trend analysis – a clear 30-day learning-progress trajectory
🎯 Skill assessment radar – multi-dimensional skill levels at a glance
⏰ Time-distribution heatmap – discover your best learning hours
📊 Command frequency statistics – identify where to focus
🔍 Error-type analysis – tackle common problems precisely
📈 Learning-progress trend – quantify skill growth
```
#### 💻 **Interactive user experience**
* **Responsive design**: Perfect on desktop, tablet, and phone
* **Interactive charts**: Hover details, zoom, explore data
* **AI insights**: Personalized meaning behind each chart
* **One-click sharing**: Generates a static HTML you can share easily
#### 🔧 **Flexible configuration options**
```bash
# Quick generate and view
ais report --html --open
# Custom filename
ais report --html -o "My-Skills-Growth-Report.html"
# Use cases
ais report --html -o weekly_report.html # Weekly report
ais report --html -o monthly_review.html # Monthly review
ais report --html -o skill_assessment.html # Skill assessment
```
### 🧠 Intelligent Context-Awareness System (v2.4.0)
AIS can now sense your system environment and provide precise, real-world advice:
#### 📊 **System-status awareness**
```bash
$ ais ask "How is my system configured?"
# AI will analyze and answer:
✓ OS: Ubuntu 24.04.2 LTS
✓ CPU: 4-core Intel Xeon Platinum
✓ Memory: 7.1 G total, 3.5 G used, 3.6 G available
✓ Disk: 40 G total, 4.1 G used (11%)
✓ Network: Reachable (ping 8.8.8.8)
```
#### 🔐 **Security-status analysis**
```bash
$ ais ask "Which ports are open on my system? Are they secure?"
# AI will assess port security and provide suggestions:
✓ SSH (22): Secure; recommend key-based authentication
✓ DNS (53): Beware DNS amplification risk
✓ Other ports: Concrete hardening suggestions provided
```
#### 🚀 **Project optimization suggestions**
```bash
$ ais ask "Given my environment, how do I optimize this Python project?"
# AI will combine system configuration with project type to propose optimizations:
✓ Use 4 CPU cores for parallelism (multiprocessing)
✓ Tune data-processing strategy based on memory
✓ Adjust remote API calls according to network status
```
#### ⚙️ **Flexible levels**
* **Minimal**: System basics + network status + running services
* **Standard**: + Project type + Git status + file list
* **Detailed**: + Permission info + detailed network + full environment
---
## 🏗️ Project Structure
```
ais/
├── src/ais/ # Main source code
│ ├── cli/ # CLI modules
│ │ ├── main.py # CLI entry point
│ │ └── interactive.py # Interactive menu
│ ├── core/ # Core modules
│ │ ├── ai.py # AI interaction
│ │ ├── config.py # Configuration management
│ │ ├── context.py # Context collection
│ │ └── database.py # Database operations
│ ├── ui/ # User interface
│ │ └── panels.py # Display panels
│ └── utils/ # Utilities
├── scripts/ # Install and deployment scripts
├── tests/ # Tests
├── docs/ # Documentation
└── pyproject.toml # Project configuration
```
### Core Modules
* **CLI module** (`src/ais/cli/`): Command-line interface and interactive UI
* **Core module** (`src/ais/core/`): AI integration, configuration, context collection, database operations
* **UI module** (`src/ais/ui/`): Rich-based display panels and formatting
---
---
## 🧪 Development and Testing
### Development Environment Setup
```bash
# Clone the repository
git clone https://github.com/kangvcar/ais.git
cd ais
# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dev build and dependencies
pip install -e ".[dev]"
# Set up pre-commit
pre-commit install
```
### Run Tests
```bash
# Run all tests
python -m pytest tests/ -v
# Coverage
python -m pytest --cov=ais tests/
# Code quality checks
source .venv/bin/activate && black src/ tests/
source .venv/bin/activate && flake8 src/ tests/ --max-line-length=100
```
---
## <a id="contributing"></a>🤝 Contributing
We welcome all forms of contribution!
### How to Get Involved
1. **Fork** this repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a **Pull Request**
### Development Guidelines
* Follow the [PEP 8](https://pep8.org/) style guide
* Add tests for new features
* Update relevant documentation
* Write clear commit messages
### Code Quality
Ensure your code meets project standards:
```bash
# Auto-format code
source .venv/bin/activate && autopep8 --in-place --aggressive --aggressive --max-line-length=100 src/ tests/ -r
# Run all quality checks
python -m pytest tests/ -v
source .venv/bin/activate && black src/ tests/
source .venv/bin/activate && flake8 src/ tests/ --max-line-length=100
```
---
## 🆘 Getting Help
### Self-Serve Resources
```bash
# Test system integration
ais test-integration
# Show version
ais --version
# Show all help
ais help-all
```
### Community Support
* 📚 [Full Documentation](docs/)
* 💬 [GitHub Discussions](https://github.com/kangvcar/ais/discussions) – Q\&A and conversations
* 🐛 [GitHub Issues](https://github.com/kangvcar/ais/issues) – Bug reports
* 📧 [Email Support](mailto:ais@example.com) – Contact directly
### Reporting Issues
When reporting an issue, please provide:
* Your operating system and version
* Python version (`python3 --version`)
* AIS version (`ais --version`)
* Installation method (pipx/Docker/source)
* Full error message
* Reproduction steps
---
## 📝 License
This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
---
## 🎉 Acknowledgments
Thanks to all the developers who contributed to this project!
### Tech Stack
* **Python 3.9+** – Core language
* **Click** – CLI framework
* **Rich** – Terminal UI and formatting
* **SQLModel** – Database ORM
* **httpx** – HTTP client
* **Plotly** – Interactive charting (HTML reports)
* **NumPy** – Numerical computing support (for visualization)
* **pytest** – Testing framework
---
<div align="center">
**🎉 Let AI be your terminal companion and make command-line learning simple and fun!**
If you find AIS helpful, please give us a ⭐️!
[](https://github.com/kangvcar/ais/stargazers)
[](https://github.com/kangvcar/ais/network/members)
[Back to top](#ais-%E2%80%93-context%E2%80%91aware-error%E2%80%91analysis-learning-assistant)
</div>
---
Raw data
{
"_id": null,
"home_page": null,
"name": "ais-terminal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "AIS Team <ais@example.com>",
"keywords": "ai, assistant, automation, cli, error-analysis, shell, terminal",
"author": null,
"author_email": "AIS Team <ais@example.com>",
"download_url": "https://files.pythonhosted.org/packages/b9/48/bcfd769df713161a700eafe5f83d73634e3af979fc083fd9386cd8a8e6d3/ais_terminal-3.3.1.tar.gz",
"platform": null,
"description": "**\u8bed\u8a00 / Language:** [\u4e2d\u6587](./README-zh.md) | [English](./README.md)\n\n\n# AIS \u2013 Context-Aware Error-Analysis Learning Assistant\n\n<div align=\"center\">\n\n\n\n[\ud83d\udcd6 Installation Guide](#installation) \u00b7 [\ud83c\udf0f Official Docs](https://kangvcar.github.io/ais) \u00b7 [\ud83c\udf9e\ufe0f Feature Demo (Mainland China)](https://www.bilibili.com/video/BV1wDvwzDEEz) \u00b7 [\u2728 Interactive Demo](https://app.arcade.software/share/hZWhYIC7dsD7Ed1GPv0G)\n\n<a href=\"https://www.producthunt.com/products/ais?embed=true&utm_source=badge-featured&utm_medium=badge&utm_source=badge-ais\" target=\"_blank\"><img src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1009557&theme=light&t=1756203101298\" alt=\"AIS - Smart terminal AI assistant for instant error analysis | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /></a>\n\n[](https://www.youtube.com/watch?v=T8Q-y2BdFlw \"This AI Terminal Assistant Just Changed How I Debug Code Forever | AIS Demo\")\n\n</div>\n\n## Overview\n\nThrough a deep shell-integration architecture, AIS achieves multi-dimensional context awareness and intelligent error analysis. It automatically collects execution-environment information and pinpoints issues precisely; inside the terminal it provides context-based solutions and structured learning guidance. This eliminates the usual search hopping and blind trial-and-error in traditional error handling, significantly improving both problem-solving efficiency and the speed of skill accumulation.\n\n### \ud83c\udf1f Core Features\n\n#### \ud83d\udd0d Intelligent Error Analysis\n\n* **Automatic detection** \u2013 Automatically analyzes the cause when a command fails\n* **Context awareness** \u2013 Combines current directory, Git status, project type, and other environment info\n* **Personalized suggestions** \u2013 Offers targeted solutions based on the user\u2019s skill level\n* **Safety levels** \u2013 Every suggestion is labeled with a risk level to keep operations safe\n\n#### \ud83d\udcda Intelligent Learning System\n\n* **Interactive teaching** \u2013 Explains the \u201cwhy,\u201d not just the \u201chow\u201d\n* **Topic learning** \u2013 Dive into focused topics like Git, Docker, and Vim\n* **Progressive content** \u2013 Adjusts depth according to user level\n* **Practice-oriented** \u2013 Provides runnable command examples and best practices\n\n#### \ud83c\udfaf Intelligent Context Awareness\n\n* **Environment-aware Q\\&A** \u2013 `ais ask` delivers precise answers based on the current system environment\n* **Three-level context collection** \u2013 Configurable information-collection levels: minimal/standard/detailed\n* **System status analysis** \u2013 Automatically detects hardware configuration, network status, and running services\n* **Project-type recognition** \u2013 Intelligently identifies tech stacks using Git status and project files\n\n#### \ud83d\udd0c Strong Integrations\n\n* **Shell integration** \u2013 Automatic error capture for Bash and Zsh\n* **Multi-AI support** \u2013 Compatible with OpenAI, Ollama, Claude, and more\n* **Privacy protection** \u2013 Local data storage; sensitive information is automatically filtered\n* **Cross-platform** \u2013 Supports Linux and macOS\n\n---\n\n## <a id=\"installation\"></a>\ud83d\udce6 Installation\n\n### System Requirements\n\n* **Python**: 3.9+ (3.11+ recommended)\n* **Operating Systems**: Linux, macOS\n* **Network**: Required to download dependencies and access AI services\n* **Disk Space**: At least 100 MB free space\n\n### \u26a1 One-Click Install (Recommended)\n\n```bash\n# Smart install \u2013 automatically detects the environment and chooses the best method\ncurl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash\n\n# Mainland China users can use the Gitee mirror (faster and more stable)\ncurl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash\n```\n\n**The install script will automatically:**\n\n* \ud83d\udd0d Detect the current environment (personal/team/container)\n* \ud83c\udfaf Choose the best installation method (pipx per-user/system-wide/containerized)\n* \ud83d\udce6 Install pipx and AIS\n* \ud83d\udd27 Configure shell integration\n* \u2713 Run a health check\n\n### \ud83d\uddd1\ufe0f One-Click Uninstall\n\n```bash\n# Smart uninstall \u2013 automatically detects how AIS was installed and cleans it completely\ncurl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/uninstall.sh | bash\n\n# Mainland China users can use the Gitee mirror\ncurl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/uninstall.sh | bash\n```\n\n**The uninstall script will automatically:**\n\n* \ud83d\udd0d Detect how AIS was installed (pipx per-user/system-wide)\n* \ud83d\uddd1\ufe0f Uninstall the AIS package and dependencies\n* \ud83e\uddf9 Clean shell-integration configuration\n* \ud83d\udcc1 Let you choose to keep or delete user data\n* \u2713 Verify that uninstallation is complete\n\n### \ud83c\udfaf Installation by Scenario\n\n<details>\n<summary><b>\ud83d\udc33 Docker Container (Recommended \u2013 zero configuration)</b></summary>\n\n```bash\n# Run the latest version directly\ndocker run -it --rm kangvcar/ais:latest\n\n# Or use it interactively\ndocker run -it --rm -v $(pwd):/workspace kangvcar/ais:latest bash\n\n# Use Docker Compose (recommended for persistent configuration)\ncurl -O https://raw.githubusercontent.com/kangvcar/ais/main/docker-compose.yml\ndocker-compose up -d ais\ndocker-compose exec ais bash\n```\n\n**Advantages**: Zero-config startup, environment isolation, cross-platform consistency, ARM64 supported\n\n</details>\n\n<details>\n<summary><b>\ud83d\udc68\u200d\ud83d\udcbb Individual Developer (Python environment)</b></summary>\n\n```bash\n# Per-user install (safest)\ncurl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --user\n\n# Mainland China users can use the Gitee mirror\ncurl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --user\n\n# Or install manually\npipx install ais-terminal\nais setup\n\n# HTML report visualization is now included by default\n```\n\n**Advantages**: Maximum safety, isolated virtual environment, no sudo required\n\n</details>\n\n<details>\n<summary><b>\ud83c\udfe2 Team/Enterprise Environment</b></summary>\n\n```bash\n# System-wide installation (available to all users)\ncurl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --system\n\n# Mainland China users can use the Gitee mirror\ncurl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --system\n```\n\n**Advantages**: Available to all users, maintains safety isolation, centralized management and updates\n\n</details>\n\n<details>\n<summary><b>\ud83d\udc33 Container/Cloud Environment</b></summary>\n\n```bash\n# Dockerized installation\ncurl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/docker-install.sh | bash\n\n# Or run directly\ndocker run -it --rm ais:latest\n```\n\n**Advantages**: Environment consistency, rapid deployment, easy scaling, full isolation\n\n</details>\n\n<details>\n<summary><b>\ud83d\udd27 Developers/Contributors</b></summary>\n\n```bash\n# Install from source\ngit clone https://github.com/kangvcar/ais.git\ncd ais\npipx install -e .\n\n# Or use a virtual environment\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev,html]\" # Includes dev and HTML visualization dependencies\n```\n\n**Advantages**: Live edits, complete dev toolchain, easy debugging\n\n</details>\n\n### \u2713 Verify Installation\n\n```bash\n# Check version\nais --version\n\n# Test basic functionality\nais ask \"Hello, AIS!\"\n\n# Test automatic error analysis (enter a command with an intentional typo)\nmkdirr /tmp/test\n```\n\n---\n\n## <a id=\"quickstart\"></a>\ud83d\ude80 Quick Start\n\n### Basic Configuration\n\n```bash\n# View current configuration\nais config\n\n# Set context-collection level\nais config --set context_level=detailed\n```\n\n### Core Feature Walkthrough\n\n#### \ud83d\udcac Environment-Aware Q\\&A\n\n```bash\n# Environment-aware Q&A based on the current system\nais ask \"What is my system configuration like? How is the hardware performance?\"\nais ask \"Is my network connection normal? Any security suggestions?\"\nais ask \"Given my current project type, how can I optimize performance?\"\n\n# Traditional technical Q&A (still supported)\nais ask \"How do I check system memory usage?\"\nais ask \"How do Docker containers mount directories?\"\nais ask \"How do I resolve Git merge conflicts?\"\n\n# Configure context-collection level\nais config --set context_level=minimal # Basic information\nais config --set context_level=standard # Standard information \nais config --set context_level=detailed # Full information\n```\n\n#### \ud83d\udcd6 Topic Learning\n\n```bash\nais learn git # Learn Git version control\nais learn docker # Learn containerization\nais learn vim # Learn the text editor\nais learn ssh # Learn remote access\n```\n\n#### \ud83d\udd0d Intelligent Error Analysis\n\n```bash\n# These erroneous commands will automatically trigger AI analysis\npytho --version # Spelling error\nls /not/exist # Path does not exist\ngit statuss # Command error\n```\n\n#### \ud83d\udcca Learning Growth Report\n\n```bash\nais report # Generate a text-format learning report\nais report --html # Generate an HTML visualization report\nais report --html -o my_report.html --open # Generate and open the HTML report\n\n# History management\nais history # View recent command history\nais history --limit 20 # Show 20 command records\nais history 3 # View detailed analysis of record #3\n```\n\n---\n\n## \ud83d\udcda Detailed Features\n\n### Environment-Aware Q\\&A \u2013 `ais ask`\n\nIntelligent Q\\&A based on the current system environment, automatically sensing hardware configuration, network status, project type, and more:\n\n```bash\n# \ud83d\udda5\ufe0f System environment-aware Q&A\nais ask \"How is my system performance? Do I need to optimize?\"\nais ask \"Are my currently open ports secure?\"\nais ask \"What is the status of my network connection?\"\n\n# \ud83d\ude80 Project environment-aware Q&A \nais ask \"What type of project is this? How do I install dependencies?\"\nais ask \"Given the current Git status, how should I commit?\"\nais ask \"How do I optimize this Python project in my current environment?\"\n\n# \ud83d\udcda Traditional technical Q&A (still supported)\nais ask \"What does Linux file permission 755 mean?\"\nais ask \"How can I optimize Python script performance?\"\nais ask \"What are the steps to configure Nginx as a reverse proxy?\"\n\n# \u2699\ufe0f Context-level configuration\nais config --set context_level=minimal # Basics: system info, Git, project type\nais config --set context_level=standard # Standard: + file list, command history\nais config --set context_level=detailed # Detailed: + network, permissions, services\n\n# \ud83d\udccb View detailed help\nais ask --help-detail\n```\n\n**New highlights**:\n\n* \ud83e\udde0 **Smart context collection**: Automatically detects CPU, memory, network, and service status\n* \ud83c\udfaf **Environment-aware answers**: Targeted advice based on actual system configuration\n* \u26a1 **Three configurable tiers**: From lightweight to detailed, fit for different scenarios\n* \ud83d\udd12 **Privacy**: Sensitive info is auto-filtered; protected directories are skipped\n\n### Learning Growth Report \u2013 `ais report`\n\nGenerate a detailed, personalized learning-growth analysis report in text or visual HTML:\n\n```bash\n# \ud83d\udcca Text report (default)\nais report\n\n# \ud83d\udcc8 HTML visualization report (recommended)\nais report --html\nais report --html -o custom_report.html\nais report --html --open # Automatically open in the browser after generation\n\n# \ud83d\udccb View detailed help\nais report --help\n```\n\n#### \ud83c\udf1f HTML Visualization Features\n\n**6 professional chart types**:\n\n* \ud83d\udcc8 **Error trend chart**: 30-day error trend to show progress\n* \ud83c\udfaf **Skill assessment radar**: Visualize multi-dimensional skill levels\n* \u23f0 **Time heatmap**: Distribution over time to find learning patterns\n* \ud83d\udcca **Command frequency**: Rank most error-prone commands for focus\n* \ud83d\udd0d **Error-type distribution**: Pie chart of error patterns for targeted fixes\n* \ud83d\udcc8 **Learning-progress trend**: Dual-axis view of error reduction and skill growth\n\n**Modern UX**:\n\n* \ud83c\udfa8 **Responsive design**: Great on desktop, tablet, and mobile\n* \ud83d\uddb1\ufe0f **Interactive charts**: Hover tooltips, zooming, and drill-down\n* \ud83d\udca1 **AI insights**: Personalized analysis and improvement tips\n* \ud83c\udf10 **Browser-friendly**: Works in modern browsers; no plugins needed\n\n**Flexible options**:\n\n```bash\n# Custom output filename\nais report --html -o \"2024-Learning-Report.html\"\n\n# Open in a browser after generation\nais report --html --open\n\n# Combine options\nais report --html -o weekly_progress.html --open\n```\n\n**Data security**:\n\n* \ud83d\udcca All data generated locally; nothing uploaded to the cloud\n* \ud83d\udd12 Sensitive information is auto-filtered\n* \ud83d\udcc1 Supports offline viewing and sharing\n\n### Knowledge Learning \u2013 `ais learn`\n\nSystematic learning for command-line tools and concepts:\n\n```bash\nais learn # List all available topics\nais learn git # Complete Git tutorial\nais learn docker # In-depth containerization\nais learn linux # Linux system-administration basics\n```\n\n### Managing AI Providers\n\nSupports multiple AI providers with easy switching:\n\n```bash\n# List available providers\nais provider-list\n\n# Add a local Ollama provider\nais provider-add ollama \\\n --url http://localhost:11434/v1/chat/completions \\\n --model llama3\n\n# Switch provider\nais provider-use ollama\n```\n\n### Shell-Integration Configuration\n\nAIS supports automatic error analysis; shell integration is required:\n\n```bash\n# Automatic configuration\nais setup\n\n# Test whether the integration works\nais test-integration\n```\n\n---\n\n## \u2699\ufe0f Advanced Configuration\n\n### Smart Context-Collection Settings\n\nIndependently control context collection for error analysis and for `ask` Q\\&A:\n\n```bash\n# Context level for error analysis (automatic analysis feature)\nais config --set context_level=minimal # Basic information\nais config --set context_level=standard # Standard information (default)\nais config --set context_level=detailed # Detailed information\n\n# Context level for ask Q&A (new)\nais config --set ask.context_level=minimal # System basics\nais config --set ask.context_level=standard # + project and Git information\nais config --set ask.context_level=detailed # + network, permissions, services\n\n# Control automatic analysis\nais config --set auto_analysis=true # Enable automatic analysis\nais config --set auto_analysis=false # Disable automatic analysis\n\n# View current configuration\nais config\n```\n\n**Context-collection details**:\n\n| Level | Included in error analysis | Included in ask Q\\&A |\n| ------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------- |\n| **minimal** | Command, exit code, directory, user | System info, CPU/memory, network reachability, listening ports, running services |\n| **standard** | + File list, Git status, command history | + Project type, Git details, file list |\n| **detailed** | + System info, environment variables, full directory | + Permission info, detailed network status, full environment |\n\n### Privacy and Security\n\nAIS takes privacy and data security seriously:\n\n* **Local storage** \u2013 All data stored in a local SQLite database\n* **Sensitive-info filtering** \u2013 Passwords, keys, and similar are filtered automatically\n* **Configurable context levels** \u2013 You control the scope of information collection\n* **Open source and transparent** \u2013 Fully open source; code is publicly available\n\n---\n\n## \ud83c\udd95 Latest Feature Highlights\n\n### \ud83d\udcca HTML Visualization Report System (v2.5.2)\n\nAIS now supports professional HTML visualization reports, turning dry data into clear, attractive charts:\n\n#### \ud83c\udfa8 **Modern visualization design**\n\n```bash\n$ ais report --html --open\n\n# Automatically generates an HTML report containing:\n\ud83d\udcc8 Error trend analysis \u2013 a clear 30-day learning-progress trajectory\n\ud83c\udfaf Skill assessment radar \u2013 multi-dimensional skill levels at a glance \n\u23f0 Time-distribution heatmap \u2013 discover your best learning hours\n\ud83d\udcca Command frequency statistics \u2013 identify where to focus\n\ud83d\udd0d Error-type analysis \u2013 tackle common problems precisely\n\ud83d\udcc8 Learning-progress trend \u2013 quantify skill growth\n```\n\n#### \ud83d\udcbb **Interactive user experience**\n\n* **Responsive design**: Perfect on desktop, tablet, and phone\n* **Interactive charts**: Hover details, zoom, explore data\n* **AI insights**: Personalized meaning behind each chart\n* **One-click sharing**: Generates a static HTML you can share easily\n\n#### \ud83d\udd27 **Flexible configuration options**\n\n```bash\n# Quick generate and view\nais report --html --open\n\n# Custom filename\nais report --html -o \"My-Skills-Growth-Report.html\"\n\n# Use cases\nais report --html -o weekly_report.html # Weekly report\nais report --html -o monthly_review.html # Monthly review\nais report --html -o skill_assessment.html # Skill assessment\n```\n\n### \ud83e\udde0 Intelligent Context-Awareness System (v2.4.0)\n\nAIS can now sense your system environment and provide precise, real-world advice:\n\n#### \ud83d\udcca **System-status awareness**\n\n```bash\n$ ais ask \"How is my system configured?\"\n\n# AI will analyze and answer:\n\u2713 OS: Ubuntu 24.04.2 LTS\n\u2713 CPU: 4-core Intel Xeon Platinum \n\u2713 Memory: 7.1 G total, 3.5 G used, 3.6 G available\n\u2713 Disk: 40 G total, 4.1 G used (11%)\n\u2713 Network: Reachable (ping 8.8.8.8)\n```\n\n#### \ud83d\udd10 **Security-status analysis**\n\n```bash\n$ ais ask \"Which ports are open on my system? Are they secure?\"\n\n# AI will assess port security and provide suggestions:\n\u2713 SSH (22): Secure; recommend key-based authentication\n\u2713 DNS (53): Beware DNS amplification risk\n\u2713 Other ports: Concrete hardening suggestions provided\n```\n\n#### \ud83d\ude80 **Project optimization suggestions**\n\n```bash\n$ ais ask \"Given my environment, how do I optimize this Python project?\"\n\n# AI will combine system configuration with project type to propose optimizations:\n\u2713 Use 4 CPU cores for parallelism (multiprocessing)\n\u2713 Tune data-processing strategy based on memory\n\u2713 Adjust remote API calls according to network status\n```\n\n#### \u2699\ufe0f **Flexible levels**\n\n* **Minimal**: System basics + network status + running services\n* **Standard**: + Project type + Git status + file list\n* **Detailed**: + Permission info + detailed network + full environment\n\n---\n\n## \ud83c\udfd7\ufe0f Project Structure\n\n```\nais/\n\u251c\u2500\u2500 src/ais/ # Main source code\n\u2502 \u251c\u2500\u2500 cli/ # CLI modules\n\u2502 \u2502 \u251c\u2500\u2500 main.py # CLI entry point\n\u2502 \u2502 \u2514\u2500\u2500 interactive.py # Interactive menu\n\u2502 \u251c\u2500\u2500 core/ # Core modules\n\u2502 \u2502 \u251c\u2500\u2500 ai.py # AI interaction\n\u2502 \u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u2502 \u251c\u2500\u2500 context.py # Context collection\n\u2502 \u2502 \u2514\u2500\u2500 database.py # Database operations\n\u2502 \u251c\u2500\u2500 ui/ # User interface\n\u2502 \u2502 \u2514\u2500\u2500 panels.py # Display panels\n\u2502 \u2514\u2500\u2500 utils/ # Utilities\n\u251c\u2500\u2500 scripts/ # Install and deployment scripts\n\u251c\u2500\u2500 tests/ # Tests\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 pyproject.toml # Project configuration\n```\n\n### Core Modules\n\n* **CLI module** (`src/ais/cli/`): Command-line interface and interactive UI\n* **Core module** (`src/ais/core/`): AI integration, configuration, context collection, database operations\n* **UI module** (`src/ais/ui/`): Rich-based display panels and formatting\n\n---\n\n---\n\n## \ud83e\uddea Development and Testing\n\n### Development Environment Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kangvcar/ais.git\ncd ais\n\n# Create a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install dev build and dependencies\npip install -e \".[dev]\"\n\n# Set up pre-commit\npre-commit install\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npython -m pytest tests/ -v\n\n# Coverage\npython -m pytest --cov=ais tests/\n\n# Code quality checks\nsource .venv/bin/activate && black src/ tests/\nsource .venv/bin/activate && flake8 src/ tests/ --max-line-length=100\n```\n\n---\n\n## <a id=\"contributing\"></a>\ud83e\udd1d Contributing\n\nWe welcome all forms of contribution!\n\n### How to Get Involved\n\n1. **Fork** this repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a **Pull Request**\n\n### Development Guidelines\n\n* Follow the [PEP 8](https://pep8.org/) style guide\n* Add tests for new features\n* Update relevant documentation\n* Write clear commit messages\n\n### Code Quality\n\nEnsure your code meets project standards:\n\n```bash\n# Auto-format code\nsource .venv/bin/activate && autopep8 --in-place --aggressive --aggressive --max-line-length=100 src/ tests/ -r\n\n# Run all quality checks\npython -m pytest tests/ -v\nsource .venv/bin/activate && black src/ tests/\nsource .venv/bin/activate && flake8 src/ tests/ --max-line-length=100\n```\n\n---\n\n## \ud83c\udd98 Getting Help\n\n### Self-Serve Resources\n\n```bash\n# Test system integration\nais test-integration\n\n# Show version\nais --version\n\n# Show all help\nais help-all\n```\n\n### Community Support\n\n* \ud83d\udcda [Full Documentation](docs/)\n* \ud83d\udcac [GitHub Discussions](https://github.com/kangvcar/ais/discussions) \u2013 Q\\&A and conversations\n* \ud83d\udc1b [GitHub Issues](https://github.com/kangvcar/ais/issues) \u2013 Bug reports\n* \ud83d\udce7 [Email Support](mailto:ais@example.com) \u2013 Contact directly\n\n### Reporting Issues\n\nWhen reporting an issue, please provide:\n\n* Your operating system and version\n* Python version (`python3 --version`)\n* AIS version (`ais --version`)\n* Installation method (pipx/Docker/source)\n* Full error message\n* Reproduction steps\n\n---\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License \u2013 see the [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83c\udf89 Acknowledgments\n\nThanks to all the developers who contributed to this project!\n\n### Tech Stack\n\n* **Python 3.9+** \u2013 Core language\n* **Click** \u2013 CLI framework\n* **Rich** \u2013 Terminal UI and formatting\n* **SQLModel** \u2013 Database ORM\n* **httpx** \u2013 HTTP client\n* **Plotly** \u2013 Interactive charting (HTML reports)\n* **NumPy** \u2013 Numerical computing support (for visualization)\n* **pytest** \u2013 Testing framework\n\n---\n\n<div align=\"center\">\n\n**\ud83c\udf89 Let AI be your terminal companion and make command-line learning simple and fun!**\n\nIf you find AIS helpful, please give us a \u2b50\ufe0f!\n\n[](https://github.com/kangvcar/ais/stargazers)\n[](https://github.com/kangvcar/ais/network/members)\n\n[Back to top](#ais-%E2%80%93-context%E2%80%91aware-error%E2%80%91analysis-learning-assistant)\n\n</div>\n\n---",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u4e0a\u4e0b\u6587\u611f\u77e5\u7684\u9519\u8bef\u5206\u6790\u5b66\u4e60\u52a9\u624b - \u8ba9\u6bcf\u6b21\u62a5\u9519\u90fd\u662f\u6210\u957f",
"version": "3.3.1",
"project_urls": {
"Changelog": "https://github.com/kangvcar/ais/blob/main/docs/CHANGELOG.md",
"Documentation": "https://github.com/kangvcar/ais/blob/main/docs/README.md",
"Homepage": "https://github.com/kangvcar/ais",
"Issues": "https://github.com/kangvcar/ais/issues",
"Repository": "https://github.com/kangvcar/ais"
},
"split_keywords": [
"ai",
" assistant",
" automation",
" cli",
" error-analysis",
" shell",
" terminal"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "665cb19c8af05a08e37dc399c170e61961be0de4475aaa90ca63bc690238ae36",
"md5": "3f3702fda4c083ab6a9410bf8d8bb07c",
"sha256": "82140cef19b471a3000ac872355a5b39a63e0a9794f30ab1bb70b768035f61d8"
},
"downloads": -1,
"filename": "ais_terminal-3.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f3702fda4c083ab6a9410bf8d8bb07c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 79367,
"upload_time": "2025-08-30T03:50:53",
"upload_time_iso_8601": "2025-08-30T03:50:53.690340Z",
"url": "https://files.pythonhosted.org/packages/66/5c/b19c8af05a08e37dc399c170e61961be0de4475aaa90ca63bc690238ae36/ais_terminal-3.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b948bcfd769df713161a700eafe5f83d73634e3af979fc083fd9386cd8a8e6d3",
"md5": "61553e3b761bd3bed0b3ba32e16a849b",
"sha256": "6c16894b9f95b2af9d8087b6f8eca64a8e6a2368bcda89358029cb723c55130f"
},
"downloads": -1,
"filename": "ais_terminal-3.3.1.tar.gz",
"has_sig": false,
"md5_digest": "61553e3b761bd3bed0b3ba32e16a849b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1494809,
"upload_time": "2025-08-30T03:50:55",
"upload_time_iso_8601": "2025-08-30T03:50:55.144559Z",
"url": "https://files.pythonhosted.org/packages/b9/48/bcfd769df713161a700eafe5f83d73634e3af979fc083fd9386cd8a8e6d3/ais_terminal-3.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 03:50:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kangvcar",
"github_project": "ais",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ais-terminal"
}
JSON
