170 lines
9.8 KiB
HTML
170 lines
9.8 KiB
HTML
<h2>Tool Layer</h2>
|
|
<p class="subtitle">Four Plugin Tools, Their Contracts & the OpenClaw Interaction Protocol</p>
|
|
|
|
<div class="section">
|
|
<h3>Tool 1: obsidian_rag_search</h3>
|
|
<div class="mockup">
|
|
<div class="mockup-header">Primary semantic search tool</div>
|
|
<div class="mockup-body" style="font-family: monospace; font-size: 12px; padding: 16px; display: flex; gap: 20px; flex-wrap: wrap;">
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">PARAMETERS</div>
|
|
<div style="color: #eee;">query <span style="color: #e94560;">(required)</span> string</div>
|
|
<div style="color: #888; margin-left: 16px;">Natural language question</div>
|
|
<div style="color: #eee;">max_results <span style="color: #888;">(opt)</span> int, default 5</div>
|
|
<div style="color: #888; margin-left: 16px;">Max chunks to return (1-50)</div>
|
|
<div style="color: #eee;">directory_filter <span style="color: #888;">(opt)</span> string[]</div>
|
|
<div style="color: #888; margin-left: 16px;">Limit to subdirs e.g. ["Journal"]</div>
|
|
<div style="color: #eee;">date_range <span style="color: #888;">(opt)</span> {from, to}</div>
|
|
<div style="color: #888; margin-left: 16px;">ISO 8601 dates</div>
|
|
<div style="color: #eee;">tags <span style="color: #888;">(opt)</span> string[]</div>
|
|
<div style="color: #888; margin-left: 16px;">Filter by hashtags</div>
|
|
</div>
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">RESPONSE data</div>
|
|
<div style="color: #eee;">results: [{</div>
|
|
<div style="color: #eee; margin-left: 12px;">chunk_text: string</div>
|
|
<div style="color: #eee; margin-left: 12px;">score: number (0-1)</div>
|
|
<div style="color: #eee; margin-left: 12px;">source_file: string</div>
|
|
<div style="color: #eee; margin-left: 12px;">section: string | null</div>
|
|
<div style="color: #eee; margin-left: 12px;">date: string | null</div>
|
|
<div style="color: #eee; margin-left: 12px;">tags: string[]</div>
|
|
<div style="color: #eee; margin-left: 12px;">chunk_index: number</div>
|
|
<div style="color: #eee;">}]</div>
|
|
<div style="color: #eee; margin-top: 6px;">sensitive_detected: boolean</div>
|
|
<div style="color: #888; margin-left: 12px;">If true, agent should confirm before display</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section" style="margin-top: 16px;">
|
|
<h3>Tool 2: obsidian_rag_index</h3>
|
|
<div class="mockup">
|
|
<div class="mockup-header">Trigger indexing from within OpenClaw</div>
|
|
<div class="mockup-body" style="font-family: monospace; font-size: 12px; padding: 16px; display: flex; gap: 20px; flex-wrap: wrap;">
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">PARAMETERS</div>
|
|
<div style="color: #eee;">mode <span style="color: #e94560;">(required)</span> enum</div>
|
|
<div style="color: #888; margin-left: 16px;">"full" | "sync" | "reindex"</div>
|
|
<div style="color: #eee;">full: initial index of entire vault</div>
|
|
<div style="color: #eee;">sync: incremental (mtime diff only)</div>
|
|
<div style="color: #eee;">reindex: nuke + rebuild from scratch</div>
|
|
</div>
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">RESPONSE data</div>
|
|
<div style="color: #eee;">indexed_files: number</div>
|
|
<div style="color: #eee;">total_chunks: number</div>
|
|
<div style="color: #eee;">duration_ms: number</div>
|
|
<div style="color: #eee;">errors: [{file, message}]</div>
|
|
<div style="color: #888; margin-top: 8px;">Long-running: returns immediately with</div>
|
|
<div style="color: #888;">job_id, agent polls via status tool</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section" style="margin-top: 16px;">
|
|
<h3>Tool 3: obsidian_rag_status</h3>
|
|
<div class="mockup">
|
|
<div class="mockup-header">Index health and sync state</div>
|
|
<div class="mockup-body" style="font-family: monospace; font-size: 12px; padding: 16px; display: flex; gap: 20px; flex-wrap: wrap;">
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">PARAMETERS</div>
|
|
<div style="color: #888;">(none — always returns current state)</div>
|
|
</div>
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">RESPONSE data</div>
|
|
<div style="color: #eee;">plugin_health: "healthy"|"degraded"|"unavailable"</div>
|
|
<div style="color: #eee;">total_docs: number</div>
|
|
<div style="color: #eee;">total_chunks: number</div>
|
|
<div style="color: #eee;">last_sync: string (ISO 8601)</div>
|
|
<div style="color: #eee;">unindexed_files: number</div>
|
|
<div style="color: #eee;">ollama_status: "up" | "down"</div>
|
|
<div style="color: #eee;">active_job: {id, mode, progress} | null</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section" style="margin-top: 16px;">
|
|
<h3>Tool 4: obsidian_rag_memory_store</h3>
|
|
<div class="mockup">
|
|
<div class="mockup-header">Commit facts to OpenClaw memory for faster retrieval</div>
|
|
<div class="mockup-body" style="font-family: monospace; font-size: 12px; padding: 16px; display: flex; gap: 20px; flex-wrap: wrap;">
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">PARAMETERS</div>
|
|
<div style="color: #eee;">key <span style="color: #e94560;">(required)</span> string</div>
|
|
<div style="color: #888; margin-left: 16px;">Identifier for the fact</div>
|
|
<div style="color: #eee;">value <span style="color: #e94560;">(required)</span> string</div>
|
|
<div style="color: #888; margin-left: 16px;">The fact to remember</div>
|
|
<div style="color: #eee;">source <span style="color: #e94560;">(required)</span> string</div>
|
|
<div style="color: #888; margin-left: 16px;">Source file path in vault</div>
|
|
</div>
|
|
<div style="flex: 1; min-width: 240px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 6px;">RESPONSE data</div>
|
|
<div style="color: #eee;">stored: boolean</div>
|
|
<div style="color: #eee;">key: string (echoed back)</div>
|
|
<div style="color: #888; margin-top: 8px;">Auto-suggest: When search results</div>
|
|
<div style="color: #888;">match financial/health/commitment</div>
|
|
<div style="color: #888;">patterns, plugin flags</div>
|
|
<div style="color: #888;">sensitive_detected=true and includes</div>
|
|
<div style="color: #888;">memory_suggestion with key/value</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section" style="margin-top: 20px;">
|
|
<h3>OpenClaw Interaction Protocol</h3>
|
|
<div class="mockup">
|
|
<div class="mockup-header">How the agent decides which tool to use and when</div>
|
|
<div class="mockup-body" style="font-family: monospace; font-size: 12px; padding: 16px;">
|
|
<div style="color: #53a8b6; font-weight: bold; margin-bottom: 8px;">INTENT → TOOL MAPPING</div>
|
|
<table style="width: 100%; border-collapse: collapse; color: #eee;">
|
|
<thead>
|
|
<tr style="border-bottom: 2px solid #53a8b6;">
|
|
<th style="text-align: left; padding: 6px;">User Intent Pattern</th>
|
|
<th style="text-align: left; padding: 6px;">Tool</th>
|
|
<th style="text-align: left; padding: 6px;">Agent Behavior</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr style="border-bottom: 1px solid #333;">
|
|
<td style="padding: 6px;">"What did I write about X?"<br>"How was my Y in Z?"</td>
|
|
<td style="padding: 6px; color: #f0a500;">search</td>
|
|
<td style="padding: 6px;">Query vault, synthesize answer from chunks</td>
|
|
</tr>
|
|
<tr style="border-bottom: 1px solid #333;">
|
|
<td style="padding: 6px;">"Index my vault"<br>"Update the search index"</td>
|
|
<td style="padding: 6px; color: #f0a500;">index</td>
|
|
<td style="padding: 6px;">Choose mode (sync default, full on no index), poll status</td>
|
|
</tr>
|
|
<tr style="border-bottom: 1px solid #333;">
|
|
<td style="padding: 6px;">"Is the index up to date?"<br>"How many docs are indexed?"</td>
|
|
<td style="padding: 6px; color: #f0a500;">status</td>
|
|
<td style="padding: 6px;">Report health, suggest index if stale</td>
|
|
</tr>
|
|
<tr style="border-bottom: 1px solid #333;">
|
|
<td style="padding: 6px;">"Remember this"<br>Auto-suggest after search</td>
|
|
<td style="padding: 6px; color: #f0a500;">memory_store</td>
|
|
<td style="padding: 6px;">Confirm with user, store key+value+source</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<div style="color: #53a8b6; font-weight: bold; margin-top: 16px; margin-bottom: 8px;">PROTOCOL SEQUENCE</div>
|
|
<div style="color: #eee; line-height: 1.8;">
|
|
<div>1. Agent receives user query with vault-related intent</div>
|
|
<div>2. Agent calls <span style="color: #f0a500;">obsidian_rag_status</span> (if first interaction or >5min since last check)</div>
|
|
<div style="margin-left: 24px; color: #888;">→ Skips if status already cached and healthy</div>
|
|
<div>3. If unavailable → agent suggests running <span style="color: #f0a500;">obsidian_rag_index</span> (mode: "full")</div>
|
|
<div>4. If degraded → agent warns user but proceeds with search</div>
|
|
<div>5. Agent calls <span style="color: #f0a500;">obsidian_rag_search</span> with appropriate filters</div>
|
|
<div>6. If <span style="color: #f0a500;">sensitive_detected=true</span> → agent confirms before displaying</div>
|
|
<div>7. Agent synthesizes answer from chunks + existing knowledge</div>
|
|
<div>8. If memory_suggestion present → agent asks if user wants to store</div>
|
|
<div style="margin-left: 24px; color: #888;">→ User confirms → <span style="color: #f0a500;">obsidian_rag_memory_store</span></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div> |