From 0396d6c477cb9a5e43f868e7bb4e7acf6d1e45d3 Mon Sep 17 00:00:00 2001 From: Lingjie Feng Date: Wed, 10 Apr 2024 16:14:15 -0400 Subject: [PATCH 1/6] feat: added troubleshooting guide --- README.md | 4 ++++ TROUBLESHOOTING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/README.md b/README.md index 62894dd..9597819 100755 --- a/README.md +++ b/README.md @@ -59,6 +59,10 @@ When loading the extension, you will need to load the `dist` folder created by t - Add support for sharing workflows & knowledge with others - Create wikipedia-like knowledge base where users can work together to create knowledge that can improve the WebWand's performance +## Troubleshooting + +Check out our [Troubleshooting Guide](TROUBLESHOOTING.md) for help with common problems and solutions. + ## Contributing Interested in contributing to WebWand? We'd love your help! Check out our [Contribution Guide](CONTRIBUTING.md) for guidelines on how to contribute, report bugs, suggest enhancements, and more. diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..ded4cef --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,52 @@ +# Troubleshooting Guide for WebWand + +This guide aims to help you diagnose and resolve common problems you might encounter. If you're still facing difficulties after following these steps, please reach out to us through our [GitHub Issues](https://github.com/normal-computing/web-wand/issues). + + +## Common Issues and Solutions + +### Extension Not Loading + +**Symptom**: The WebWand extension doesn't appear in your browser or won't load. + +**Solutions**: +1. **Check Browser Compatibility**: Ensure your browser is compatible with WebWand. Currently, WebWand supports Chrome. +2. **Developer Mode**: Verify that `Developer mode` is enabled in `chrome://extensions/` +3. **Correct Folder**: Make sure you've loaded the extension from the `dist` folder after building WebWand. +4. **Conflict with Other Extensions**: Disable other extensions to identify if there's a conflict causing the issue. + +### API Key Problems + +**Symptom**: Issues related to the OpenAI API key, such as authentication errors or features not working due to key issues. e.g. 404 The model `gpt-4-vision-preview` does not exist or you do not have access to it. + +**Solutions**: +1. **Verify API Key**: Make sure you entered a valid OpenAI API key. +2. **API Key Permissions**: Ensure that your OpenAI API key has the necessary permissions for the tasks you're trying to perform. +3. **Regenerate API Key**: If you suspect your API key might have been compromised or isn't working for an unknown reason, consider regenerating a new key from the [OpenAI API dashboard](https://platform.openai.com/account/api-keys). + +### Dom Actions Problems + +**Symptom**: WebWand did not perform dom actions properly. + +**Solutions**: +1. **No Background Running**: Currently WebWand does not support running in background. If you open a new tab or navigating away from the website that webwand is working on, some actions may fail. + +### Custom Knowledge Base Problems + +**Symptom**: After adding a custom knowledge, WebWand crashed or did not perform corresponding to the new knowledge about the active tab. + +**Solutions**: +1. **Knowledge Entry Validation**: Currently Webwand only supports basic entry validation of custom knowledge. Make sure you entered correct host name and correct regular expressions if using custom URL Matching Pattern. + +### Voice mode Problems + +**Symptom**: Webwand did not capture my speech. + +**Solutions**: +1. **Check Microphone Access**: Check if Webwand has microphone access to the browser. When you turn on the voice mode in settings, the microphone access dialog should popup on the browser, please select "allow". +2. **Manually Allow Microphone Access**: If the dialog didn't popup, right click the webwand icon in the extensions group and select "View Web Permissions", then select "Allow" for Microphone. + + +## Reporting New Issues + +If you encounter a problem not covered in this guide, please help us by reporting it. Provide as much detail as possible, including steps to reproduce the issue, browser version, and any error messages you receive. Your reports are invaluable in helping us improve WebWand. \ No newline at end of file From 6c6dc80afefe7e8c90254d640bdbf0ed90522b93 Mon Sep 17 00:00:00 2001 From: Lingjie Feng Date: Wed, 10 Apr 2024 16:19:24 -0400 Subject: [PATCH 2/6] fix: update doc --- TROUBLESHOOTING.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index ded4cef..53b43c6 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -10,41 +10,41 @@ This guide aims to help you diagnose and resolve common problems you might encou **Symptom**: The WebWand extension doesn't appear in your browser or won't load. **Solutions**: -1. **Check Browser Compatibility**: Ensure your browser is compatible with WebWand. Currently, WebWand supports Chrome. -2. **Developer Mode**: Verify that `Developer mode` is enabled in `chrome://extensions/` -3. **Correct Folder**: Make sure you've loaded the extension from the `dist` folder after building WebWand. -4. **Conflict with Other Extensions**: Disable other extensions to identify if there's a conflict causing the issue. +1. Ensure your browser is compatible with WebWand. Currently, WebWand supports Chrome. +2. Verify that `Developer mode` is enabled in `chrome://extensions/` +3. Make sure you've loaded the extension from the `dist` folder after building WebWand. +4. Disable other extensions to identify if there's a conflict causing the issue. ### API Key Problems **Symptom**: Issues related to the OpenAI API key, such as authentication errors or features not working due to key issues. e.g. 404 The model `gpt-4-vision-preview` does not exist or you do not have access to it. **Solutions**: -1. **Verify API Key**: Make sure you entered a valid OpenAI API key. -2. **API Key Permissions**: Ensure that your OpenAI API key has the necessary permissions for the tasks you're trying to perform. -3. **Regenerate API Key**: If you suspect your API key might have been compromised or isn't working for an unknown reason, consider regenerating a new key from the [OpenAI API dashboard](https://platform.openai.com/account/api-keys). +1. Make sure you entered a valid OpenAI API key. +2. Ensure that your OpenAI API key has the necessary permissions. +3. If you suspect your API key might have been compromised or isn't working for an unknown reason, consider regenerating a new key from the [OpenAI API dashboard](https://platform.openai.com/account/api-keys). ### Dom Actions Problems **Symptom**: WebWand did not perform dom actions properly. **Solutions**: -1. **No Background Running**: Currently WebWand does not support running in background. If you open a new tab or navigating away from the website that webwand is working on, some actions may fail. +1. Currently WebWand does not support running in background. If you open a new tab or navigating away from the website that webwand is working on, some actions may fail. Please stay on the website where you exectute WebWand. ### Custom Knowledge Base Problems **Symptom**: After adding a custom knowledge, WebWand crashed or did not perform corresponding to the new knowledge about the active tab. **Solutions**: -1. **Knowledge Entry Validation**: Currently Webwand only supports basic entry validation of custom knowledge. Make sure you entered correct host name and correct regular expressions if using custom URL Matching Pattern. +1. Currently Webwand only supports basic entry validation of custom knowledge. Make sure you entered correct host name and correct regular expressions if using custom URL Matching Pattern. ### Voice mode Problems -**Symptom**: Webwand did not capture my speech. +**Symptom**: Webwand did not capture the speech. **Solutions**: -1. **Check Microphone Access**: Check if Webwand has microphone access to the browser. When you turn on the voice mode in settings, the microphone access dialog should popup on the browser, please select "allow". -2. **Manually Allow Microphone Access**: If the dialog didn't popup, right click the webwand icon in the extensions group and select "View Web Permissions", then select "Allow" for Microphone. +1. Check if Webwand has microphone access to the browser. When you turn on the voice mode in settings, the microphone access dialog should popup on the browser, please select "allow". +2. If the dialog didn't popup, right click the webwand icon in the extensions group and select "View Web Permissions". Then select "Allow" for Microphone. ## Reporting New Issues From e331d7acca58a9a9885297049449c3ddfa42f308 Mon Sep 17 00:00:00 2001 From: Lingjie Feng Date: Wed, 10 Apr 2024 17:06:04 -0400 Subject: [PATCH 3/6] feat: updated readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 9597819..4784f03 100755 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ Check out our [Troubleshooting Guide](TROUBLESHOOTING.md) for help with common p Interested in contributing to WebWand? We'd love your help! Check out our [Contribution Guide](CONTRIBUTING.md) for guidelines on how to contribute, report bugs, suggest enhancements, and more. +We encourage everyone in the community to add new knowledge to the "Prior Knowledge Augmentation" system. Check out the default knowledge file ["db.json"](src/helpers/knowledge). + ## Credits - WebWand's image annotation method was inspired by Microsoft's [UFO paper](https://arxiv.org/abs/2402.07939). From fc8e3b353558ffadae9fd78db5528db4946a3907 Mon Sep 17 00:00:00 2001 From: Lingjie Feng Date: Wed, 10 Apr 2024 17:07:05 -0400 Subject: [PATCH 4/6] fix: update link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4784f03..938c15f 100755 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Check out our [Troubleshooting Guide](TROUBLESHOOTING.md) for help with common p Interested in contributing to WebWand? We'd love your help! Check out our [Contribution Guide](CONTRIBUTING.md) for guidelines on how to contribute, report bugs, suggest enhancements, and more. -We encourage everyone in the community to add new knowledge to the "Prior Knowledge Augmentation" system. Check out the default knowledge file ["db.json"](src/helpers/knowledge). +We encourage everyone in the community to add new knowledge to the "Prior Knowledge Augmentation" system. Check out the default knowledge file ["db.json"](src/helpers/knowledge/db.json). ## Credits From e50ff5e457cd042e68be5ccf6d4f2043d8031054 Mon Sep 17 00:00:00 2001 From: Lingjie <125778696+lynchee-owo@users.noreply.github.com> Date: Wed, 10 Apr 2024 18:59:48 -0400 Subject: [PATCH 5/6] Update README.md Co-authored-by: Mengdi Chen --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 938c15f..10d7ac5 100755 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ When loading the extension, you will need to load the `dist` folder created by t ## Troubleshooting -Check out our [Troubleshooting Guide](TROUBLESHOOTING.md) for help with common problems and solutions. +Check out our [Troubleshooting Guide](TROUBLESHOOTING.md) for help with common problems. ## Contributing From a4b28e73e6af32c0b413c754ad8d6ee234539fe5 Mon Sep 17 00:00:00 2001 From: Lingjie Feng Date: Thu, 11 Apr 2024 10:38:24 -0400 Subject: [PATCH 6/6] fix: updated troubleshooting --- TROUBLESHOOTING.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 53b43c6..614522b 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -12,39 +12,38 @@ This guide aims to help you diagnose and resolve common problems you might encou **Solutions**: 1. Ensure your browser is compatible with WebWand. Currently, WebWand supports Chrome. 2. Verify that `Developer mode` is enabled in `chrome://extensions/` -3. Make sure you've loaded the extension from the `dist` folder after building WebWand. -4. Disable other extensions to identify if there's a conflict causing the issue. +3. (Only when you are building it from source) Make sure you've loaded the extension from the `dist` folder. +4. Restart your browser as this can resolve many loading issues. ### API Key Problems -**Symptom**: Issues related to the OpenAI API key, such as authentication errors or features not working due to key issues. e.g. 404 The model `gpt-4-vision-preview` does not exist or you do not have access to it. +**Symptom**: Issues related to the OpenAI API key, such as authentication errors or features not working due to key issues. e.g., 404 The model `gpt-4-vision-preview` does not exist or you do not have access to it. **Solutions**: -1. Make sure you entered a valid OpenAI API key. -2. Ensure that your OpenAI API key has the necessary permissions. -3. If you suspect your API key might have been compromised or isn't working for an unknown reason, consider regenerating a new key from the [OpenAI API dashboard](https://platform.openai.com/account/api-keys). +1. Make sure you entered a valid OpenAI API key. Note that keys can expire, so verify if yours is still active. +2. Ensure that your OpenAI API key has the necessary permissions. Visit https://platform.openai.com/playground/chat to check your permissions. Lack of credits can also restrict access to certain models. ### Dom Actions Problems **Symptom**: WebWand did not perform dom actions properly. **Solutions**: -1. Currently WebWand does not support running in background. If you open a new tab or navigating away from the website that webwand is working on, some actions may fail. Please stay on the website where you exectute WebWand. +1. Currently, WebWand does not support running in the background. If you open a new tab or navigate away from the website that WebWand is working on, some actions may fail. Please stay on the website where you execute WebWand. ### Custom Knowledge Base Problems -**Symptom**: After adding a custom knowledge, WebWand crashed or did not perform corresponding to the new knowledge about the active tab. +**Symptom**: After adding custom knowledge, WebWand crashed or did not perform according to the new knowledge about the active tab. **Solutions**: -1. Currently Webwand only supports basic entry validation of custom knowledge. Make sure you entered correct host name and correct regular expressions if using custom URL Matching Pattern. +1. Currently, WebWand only supports basic entry validation for custom knowledge. Make sure you entered the correct host name and correct regular expressions if using a custom URL Matching Pattern. -### Voice mode Problems +### Voice Mode Problems -**Symptom**: Webwand did not capture the speech. +**Symptom**: WebWand did not capture speech. **Solutions**: -1. Check if Webwand has microphone access to the browser. When you turn on the voice mode in settings, the microphone access dialog should popup on the browser, please select "allow". -2. If the dialog didn't popup, right click the webwand icon in the extensions group and select "View Web Permissions". Then select "Allow" for Microphone. +1. Check if WebWand has microphone access in the browser. When you turn on the voice mode in settings, the microphone access dialog should pop up in the browser; please select "allow". +2. If the dialog didn't pop up, right-click the WebWand icon in the extensions group and select "View Web Permissions". Then select "Allow" for Microphone. ## Reporting New Issues