zhongwei/gh-ce-dot-net-ce-claude-marketplace-plugins-ace

Files

Zhongwei Li d03c46038c Initial commit

2025-11-29 18:08:19 +08:00

4.4 KiB

Raw Permalink Blame History

description

description
Semantic search for ACE patterns using natural language query

ACE Semantic Search

Search for relevant patterns using natural language query instead of retrieving all patterns.

What This Does

Uses semantic search to find only the most relevant patterns matching your query, reducing context usage by 50-80%.

Instructions for Claude

When the user runs /ace-search <query>, use the Bash tool to call ce-ace CLI:

#!/usr/bin/env bash
set -euo pipefail

# Check ce-ace is available
if ! command -v ce-ace >/dev/null 2>&1; then
  echo "❌ ce-ace CLI not found in PATH"
  echo ""
  echo "Installation:"
  echo "  npm install -g @ace-sdk/cli"
  echo ""
  exit 1
fi

# Get context from .claude/settings.json and export as env vars
export ACE_ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
export ACE_PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")

if [ -z "$ACE_ORG_ID" ] || [ -z "$ACE_PROJECT_ID" ]; then
  echo "❌ No .claude/settings.json found or missing orgId/projectId"
  echo "Run /ace-configure to set up ACE"
  exit 1
fi

# Call ce-ace search - CLI reads org/project from env vars automatically
# Threshold comes from server config (ce-ace tune show) - don't override!
ce-ace search "$*"

Parameters

query (required): Natural language description passed as command argument
- Examples: "authentication patterns", "async debugging tips", "database connection pooling best practices"
--threshold: Similarity threshold (optional, overrides server config)
- Default: Uses server config from ce-ace tune show
- Range: 0.0 - 1.0 (higher = stricter matching)
- Only specify if you want to override project's default
--json: Return JSON format for programmatic use

Note: To limit number of results, use jq for filtering:

ce-ace search "query" --json | jq '.patterns[:5]'  # First 5 results

The --limit flag is not supported by ce-ace CLI. Use --top-k via server config (/ace-tune) instead.

Example Usage

/ace-search JWT authentication best practices
→ Calls: ce-ace search "JWT authentication best practices"
→ Uses: Server config threshold (e.g., 0.45)

/ace-search async test failures debugging
→ Calls: ce-ace search "async test failures debugging"

# Override threshold if needed:
/ace-search "JWT auth" --threshold 0.7
→ Calls: ce-ace search "JWT auth" --threshold 0.7

When to Use This

✅ Use /ace-search when:

You have a specific implementation question
You're debugging a specific type of problem
You know what domain/topic you need help with
You want to minimize context usage

❌ Don't use when:

You need comprehensive architectural overview
You're working on multi-domain tasks
You want to see all patterns in a section

For those cases, use /ace-patterns instead.

Output Format

The tool returns JSON with matching patterns and metadata (v3.8.0+):

{
  "patterns": [
    {
      "content": "Pattern description with context",
      "helpful": 8,
      "harmful": 0,
      "confidence": 0.92,
      "section": "strategies_and_hard_rules",
      "similarity": 0.87
    }
  ],
  "query": "your search query",
  "count": 10,
  "metadata": {
    "tokens_in_response": 2400,
    "tokens_saved_vs_full_playbook": 27600,
    "efficiency_gain": "92%",
    "full_playbook_size": 30000
  }
}

Patterns are sorted by semantic similarity to your query.

Metadata field (v3.8.0+): Provides token efficiency metrics. Omitted if include_metadata=false.

Performance Impact

Before (full playbook):

Retrieves: ALL patterns in section
Token usage: ~10,000-15,000 tokens (measured via metadata)
Time: 100-300ms

After (semantic search with metadata):

Retrieves: Top 10 relevant patterns only
Token usage: ~2,400 tokens (confirmed via metadata)
Time: 150-400ms
50-92% token reduction (exact savings shown in metadata.efficiency_gain)

After (semantic search without metadata):

Token usage: ~2,000-2,200 tokens
Time: 140-390ms (~10ms faster)
85-92% token reduction

Metadata overhead: Adds ~5-10ms response time + ~200-400 tokens for efficiency metrics

4.4 KiB Raw Permalink Blame History