From c9942e9ffaf139a1ab148e2eea87e8712a4f9412 Mon Sep 17 00:00:00 2001 From: Andrew Beal Date: Sun, 9 Nov 2025 19:59:41 +0000 Subject: [PATCH] feat: add comprehensive help modal with guide and troubleshooting content - Add detailed plugin guide covering modes, references, and instructions - Add troubleshooting section with API key and rate limit solutions - Add privacy documentation explaining data storage and exclusions - Make "User Instructions" text clickable to open help modal - Support opening help modal to specific topic via initialTopic prop - Add internal link handling to navigate from help modal to vault files - Update About section with GitHub link and contribution info --- Components/UserInstruction.svelte | 12 ++- Enums/Copy.ts | 138 ++++++++++++++++++++++++++++-- Modals/HelpModal.ts | 8 +- Modals/HelpModalSvelte.svelte | 88 ++++++++++++------- 4 files changed, 208 insertions(+), 38 deletions(-) diff --git a/Components/UserInstruction.svelte b/Components/UserInstruction.svelte index 88e7629..904d2bf 100644 --- a/Components/UserInstruction.svelte +++ b/Components/UserInstruction.svelte @@ -2,6 +2,7 @@ import { Copy } from "Enums/Copy"; import { Path } from "Enums/Path"; import type AIAgentPlugin from "main"; + import { HelpModal } from "Modals/HelpModal"; import { basename } from "path-browserify"; import { Resolve } from "Services/DependencyService"; import type { FileSystemService } from "Services/FileSystemService"; @@ -123,6 +124,11 @@ } }); } + + function openHelpModal() { + const modal = Resolve(Services.HelpModal); + modal.open(2); + }
@@ -133,7 +139,11 @@
{Copy.UserInstructions1} - + {Copy.UserInstructions2} {Copy.UserInstructions3} diff --git a/Enums/Copy.ts b/Enums/Copy.ts index 33114cb..4bbad72 100644 --- a/Enums/Copy.ts +++ b/Enums/Copy.ts @@ -58,18 +58,146 @@ export enum Copy { // Help Modal Copy HelpModalAboutTitle = "About", - HelpModalAboutContent = `### About AI Agent + HelpModalAboutContent = `#### About AI Agent -**AI Agent** brings the power of Claude, Gemini, and OpenAI directly into your Obsidian vault with intelligent note management capabilities.`, +This plugin was originally created for a friend who found it useful, so I have decided to release it to the Obsidian community. + +If you find any issues, please feel free to raise them on GitHub:`, HelpModalGuideTitle = "Plugin Guide", - HelpModalGuideContent = "", + HelpModalGuideContent = `#### How to Use AI Agent + +##### Getting Started +1. **Add an API Key**: Go to Settings and add at least one API key (Claude, Gemini, or OpenAI) +2. **Select a Model**: Choose your preferred AI model from the dropdown +3. **Open the Chat**: Click the sparkles icon in the sidebar to start chatting + +##### Operating Modes + +**Read-Only Mode (Default)** - The AI can safely explore your vault: +- Search through your notes +- Read file contents +- List directory structures +- Cannot modify anything + +**Agent Mode** - Toggle when you need the AI to make changes: +- Create new notes +- Edit existing content +- Delete or move files +- Rename files + +##### Reference System + +Quickly provide context to the AI: + +- **@filename** - Reference specific files +- **#tag** - Reference all notes with a tag +- **/folder** - Reference entire directories + +The autocomplete dropdown supports keyboard navigation. + +##### Custom Instructions + +Customize AI behavior for specific workflows: + +1. Create markdown files in **AI Agent/User Instructions/** +2. Click the "User Instructions" button in chat +3. Select your instruction set +4. The AI follows these instructions for all interactions + +See [Example Template](#/page/AI%20Agent%2FUser%20Instructions%2FEXAMPLE_INSTRUCTIONS) for help getting started.`, HelpModalTroubleshootTitle = "Troubleshooting", - HelpModalTroubleshootContent = "", + HelpModalTroubleshootContent = `#### Common Issues & Solutions + +##### API Key Issues + +**Problem**: "Invalid API key" or authentication errors + +**Solutions**: +- Verify your API key is correct (copy fresh from provider console) +- Check you've added the key for the correct provider +- Ensure no extra spaces when pasting +- API keys are provider-specific - Claude keys only work with Claude models + +##### Error Code 429: Rate Limit Exceeded + +This error means you've made too many API requests in a given time period. This is separate from your token usage limits. + +**How to resolve:** +- Wait for your rate limit to reset (see provider-specific details below) +- Lower the context settings in the plugin settings to reduce request frequency +- Understand that rate limits typically increase automatically as you use the API more + +###### Claude +- **Wait time:** A few hours +- **Long-term solution:** Rate limits increase significantly after reaching cumulative spending thresholds +- [Claude Rate Limits Documentation](https://docs.claude.com/en/api/rate-limits) + +###### OpenAI +- **Wait time:** A few minutes to an hour +- **Long-term solution:** Rate limits automatically increase as you progress through usage tiers with higher spending +- [OpenAI Rate Limits Documentation](https://platform.openai.com/docs/guides/rate-limits) + +###### Gemini +- **Wait time:** A few minutes (per-minute limits) or until midnight Pacific Time (daily quotas) +- **Long-term solution:** Enable billing to move from free tier to paid tier for significantly higher limits. Paid tier limits increase automatically with cumulative Google Cloud spending +- [Gemini API Rate Limits Documentation](https://ai.google.dev/gemini-api/docs/rate-limits)`, HelpModalPrivacyTitle = "Privacy", - HelpModalPrivacyContent = "", + HelpModalPrivacyContent = `#### Privacy & Security + +##### Data Storage + +**Everything stays local** - This plugin does NOT send data to any third-party services except the AI providers you choose. It also doesn't collect any telemetry data and you can review the full source code on GitHub. + +**What's stored locally**: +- API keys (stored in your vault's plugin settings) +- Conversation history (stored in \`AI Agent/Conversations/\`) +- Custom instructions (stored in \`AI Agent/User Instructions/\`) +- Plugin settings (stored in \`.obsidian/plugins/ai-agent-plugin/\`) + +##### API Communication + +**Direct connections only** - The plugin communicates directly with your chosen AI provider: + +- **Claude**: Anthropic's API +- **Gemini**: Google's API +- **OpenAI**: OpenAI's API + +**What gets sent**: +- Your messages and referenced file contents +- Conversation context (for continuity) +- File names and directory structures (when AI searches) + +**What does NOT get sent**: +- Files excluded in settings +- Other plugins' data +- Your vault structure (unless explicitly requested) +- API keys to anyone except the respective provider + +##### File Exclusions + +**Protect sensitive information** using glob patterns in settings: + +**Examples**: +- \`private/**\` - Exclude entire directories +- \`*.secret.md\` - Exclude specific file patterns +- \`journal/personal/**\` - Exclude nested directories +- \`.obsidian/workspace.json\` - Exclude specific files + +**How exclusions work**: +- Excluded files are completely invisible to the AI +- The AI cannot read, search, modify, or even list excluded files +- Exclusions apply to All operations + +##### AI Provider Policies + +Each AI provider has their own data policies: + +- [Anthropic (Claude)](https://www.anthropic.com/privacy) +- [Google (Gemini)](https://policies.google.com/privacy) +- [OpenAI (ChatGPT)](https://openai.com/privacy/)`, // SVG Icons GitHubIconPath = "M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z", diff --git a/Modals/HelpModal.ts b/Modals/HelpModal.ts index a811401..d692f44 100644 --- a/Modals/HelpModal.ts +++ b/Modals/HelpModal.ts @@ -24,11 +24,17 @@ export class HelpModal extends Modal { this.component = mount(HelpModalSvelte, { target: contentEl, props: { - onClose: () => this.close() + onClose: () => this.close(), + initialTopic: (this as any).initialTopic } }); } + public open(initialTopic?: number): void { + (this as any).initialTopic = initialTopic; + super.open(); + } + onClose() { if (this.component) { unmount(this.component); diff --git a/Modals/HelpModalSvelte.svelte b/Modals/HelpModalSvelte.svelte index 920e72f..924e3d1 100644 --- a/Modals/HelpModalSvelte.svelte +++ b/Modals/HelpModalSvelte.svelte @@ -1,20 +1,25 @@ @@ -144,39 +176,33 @@ Plugin version: {plugin.manifest.version}
-
+
{#if content !== ""}
{@html content} {#if selectedTopic === 1} -
-

Links

- -
-

Created with ❤️ for the Obsidian community

+ + + + + View on GitHub + +
+ If you enjoy using the plugin or find it useful and want to contribute, you can buy me a Coffee using the link below: +
+ + ☕ + Buy me a coffee + +

Thanks for using the AI Agent plugin!

{/if}
{/if} @@ -337,7 +363,7 @@ height: 100%; border-radius: var(--radius-m); background-color: var(--alt-background-primary); - padding: 0 var(--size-4-2) var(--size-4-2) var(--size-4-6); + padding: 0 var(--size-4-2) var(--size-4-2) var(--size-4-3); overflow-y: auto; }