dash-docset-search（破折号文档集搜索）

Dash Docset Search

Overview

Use this skill to search Dash content with a strict fallback order:

1. dash-mcp-server tools first
2. local Dash HTTP API second
3. Dash URL scheme and macOS Service guidance last

Use references/dash_mcp_tools.md, references/dash_http_api.md, and references/dash_url_and_service.md for exact details.

Automation Prompting

• Codex App automation fit: Strong. Suitable for recurring search and reporting workflows.
• Codex CLI automation fit: Strong. Suitable for non-interactive probe/search tasks with fallback handling.
• Use references/automation-prompts.md for Codex App and Codex CLI templates, placeholders, and output shapes.
• Keep install and generation actions out of this skill's automation prompts; hand off to $dash-docset-install-generate when needed.

Workflow

1) Establish access path

1. If Dash MCP tools are available, use them first.
2. If Dash MCP tools are unavailable, run:

- uv run python scripts/dash_api_probe.py

1. If probe indicates local API healthy, use /docsets/list, /search, and /docsets/enable_fts.
2. If local API is unavailable, provide dash:// and Service fallback guidance.

2) List installed docsets

• Preferred:

- list_installed_docsets

• HTTP fallback:

- GET {base_url}/docsets/list

Normalize and present:

• display name
• identifier
• platform
• full-text status

3) Search one or many docsets

• Preferred:

- search_documentation(query, docset_identifiers, search_snippets, max_results)

• HTTP fallback:

- GET /search?query=...&docset_identifiers=...

Rules:

• Use explicit identifiers from installed docsets.
• Disable snippet search if user asks for docset-only results.
• For multi-docset searches, pass comma-separated identifiers in one query.

4) Enable FTS when requested

• Preferred:

- enable_docset_fts(identifier)

• HTTP fallback:

- GET /docsets/enable_fts?identifier=...

Handle full_text_search status:

• enabled: continue searching
• disabled: enable then retry search
• indexing: explain indexing in progress
• not supported: skip FTS path

5) Missing docset recommendation

Use catalog snapshots and matcher:

1. uv run python scripts/dash_catalog_match.py --query "<text>"
2. classify top results into:

- built-in - user-contributed - cheatsheet

1. if no strong hit, suggest generator flow
2. suggest GitHub or Stack Overflow generation only as last resort

When installation or generation is needed, hand off to $dash-docset-install-generate.

Fallback Search Guidance

When no API path is usable, provide direct commands:

• AppleScript:

- open location "dash://?query={query}" - open location "dash://?query=python:{query}"

• Terminal:

- open "dash://?query={query}"

• macOS Service:

- select text, then Services > Look Up in Dash

Scripts

• scripts/dash_api_probe.py

- Probe local Dash API state and schema path availability.

• scripts/dash_catalog_refresh.py

- Refresh built-in, contributed, and cheatsheet snapshots.

• scripts/dash_catalog_match.py

- Rank candidate docsets and cheatsheets for a query.

• scripts/dash_url_search.py

- Launch dash:// query URLs.

• scripts/dash_url_install.py

- Confirm-first launcher for dash-install://.

References

• references/dash_mcp_tools.md
• references/dash_http_api.md
• references/dash_url_and_service.md
• references/automation-prompts.md
• references/catalog_built_in_docsets.json
• references/catalog_user_contrib_docsets.json
• references/catalog_cheatsheets.json

Optional Visual Troubleshooting

If Dash UI behavior needs visual confirmation, use the $screenshot skill if it is available in the user's environment.

Interactive Customization Flow

1. Load current effective customization settings first:

• uv run python scripts/customization_config.py effective

1. Ask targeted customization questions:

• Use references/customization-flow.md to drive knob-by-knob questions.
• Confirm desired behavior changes and safety constraints.

1. Map requested changes to implementation files:

• Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.

1. Persist durable customization state:

• Start from customization.template.yaml defaults.
• Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file>.
• Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml.
• Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME.

1. Report resulting effective configuration:

• Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
• If the user asks to remove customization state, run uv run python scripts/customization_config.py reset.

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.