--- name: deepmap description: | Provides repository-level knowledge (architecture, tech stack, implementation logic, project purpose, main features, optimization ideas) for analyzed repositories: {{AVAILABLE_REPOS}}. For questions about architecture, tech stack, implementation logic, project purpose, features, or optimization: prioritize DeepMap over local search. For questions about specific code facts: check local source first; if not available locally, use DeepMap. When the user explicitly references a code knowledge base (e.g., "project2" or "the auth-service repo"), MUST invoke DeepMap for that repository. DeepMap supplements repository-level code knowledge only; it does not have information beyond the analyzed repositories and cannot replace local source code as the source of exact code facts. --- # DeepMap Repository Context ## Core Principle DeepMap provides generated knowledge from analyzed Git repositories. For precise code facts, verify local source first. When local and DeepMap conflict, trust local. ## When To Use DeepMap Use DeepMap when the user asks about: - Project architecture, technical stack, module boundaries, or overall design. - How a feature, workflow, or business logic is implemented at repository level. - Why a module exists, what it is responsible for, or how it interacts with other modules. - Cross-repo behavior where the current repo depends on, calls, embeds, or coordinates with another analyzed repo. - A repo explicitly named by the user, such as "the auth-service repo" or "project-b". Do not use DeepMap by default when: - The user asks for an exact current code fact and the relevant local file is available. - The user asks to fix a local runtime error, compile error, failing test, or stack trace without needing architecture context. - The user asks to implement a straightforward local change and the needed context is already in the workspace. - No relevant analyzed repo can be found. ## Discovery Workflow 1. Call `GET /api/repos/list` to discover accessible analyzed repos. - Optionally pass `q` to filter by owner/repo, e.g. `q=tokfinity/auth`. - Use the `health` field to judge whether a repo has usable knowledge. 2. Select repos by evidence: exact user mention, dependency names, service names, import/package references, or README/docs references. 3. If the user is vague, start with the repo most related to the question. Do not query unrelated repos just because they are accessible. ## Query Strategy Use the lightest endpoint that can answer the question. | Need | macOS/Linux command | Windows command | What it does | |------|---------------------|-----------------|--------------| | Discover accessible repos | `scripts/deepmap.sh list` | `scripts/deepmap.ps1 list` | Calls `GET /api/repos/list`. | | Filter repos by owner/repo | `scripts/deepmap.sh list --q tokfinity/auth` | `scripts/deepmap.ps1 list --q tokfinity/auth` | Calls `GET /api/repos/list?q=...`. | | Natural-language retrieval | `scripts/deepmap.sh search --query --repo owner/repo` | `scripts/deepmap.ps1 search --query --repo owner/repo` | Calls `POST /api/repos/search`. | | Deep repo investigation | `scripts/deepmap.sh ask --query --repo owner/repo` | `scripts/deepmap.ps1 ask --query --repo owner/repo` | Calls `POST /api/repos/ask`. Use for single-repo deep synthesis; can also accept multiple `--repo` values for cross-repo synthesis. | Prefer `search` before `ask`. Use `ask` when the task requires synthesis across multiple files, modules, or repos. Do not manually implement ask polling; the script hides the async protocol and prints the final JSON. ## Configuration The helper script accepts config from stdin via `--config-stdin`, which is preferred for integrations that can avoid writing bearer tokens to disk. The legacy file flow remains supported: InfCode may pass a config path with `DEEPMAP_CONFIG_PATH`, and if that variable is absent the script falls back to `config.local.json` in the skill directory. ```json { "siteUrl": "https://deepmap.example.com", "token": "replace-with-deepmap-bearer-token", "repoMappings": [ { "localPath": "/path/to/local/project", "remoteRepo": "owner/repo" } ] } ``` Never print or hard-code the token in answers. `repoMappings` may be empty; explicit `--repo` arguments still work when the remote repo is known. When consuming script stdout, parse it line by line. Lines with `protocol: "infcode.deepmap.v1"` are protocol events for UI or executor handling, and the final non-protocol JSON line is the command result. During `ask`, the script emits an `ask_submitted` event containing `payload.task_id` immediately after the backend accepts the task; executors should use that id for best-effort cancellation before killing the local process. ## HTTP Contracts Use `siteUrl` from `config.local.json` as the DeepMap host and pass auth with `Authorization: Bearer {token}`. ### List accessible repos ```http GET /api/repos/list?q=tokfinity&limit=100&offset=0 Authorization: Bearer ``` Response includes a `health` object for each repo: ```json { "ok": true, "data": { "total": 1, "repos": [{ "owner": "tokfinity", "repo": "auth-service", "status": "ready", "health": { "index_status": "healthy", "wiki_indexed": true, "code_indexed": true, "coverage": { "files_with_docs": 120, "total_source_files": 500, "ratio": 0.24 }, "recommended_mode": "balanced" } }] } } ``` Use `q` for fuzzy filtering. It matches `owner/repo`, `owner`, or `repo` (case-insensitive). ### Search knowledge ```bash scripts/deepmap.sh search \ --query "JWT token 签发和验证流程" \ --repo tokfinity/project-x \ --limit 5 ``` Equivalent HTTP: ```http POST /api/repos/search Authorization: Bearer Content-Type: application/json { "query": "JWT token 签发和验证流程", "repos": ["tokfinity/project-x"], "limit": 5 } ``` Search supports multiple repos. Results include `repo`, `file_path`, `doc_type`, `start_line`, `end_line`, `snippet`, `score`, and `url`. Use these as citations. ### Ask investigation ```bash scripts/deepmap.sh ask \ --query "认证模块如何与订单服务交互？" \ --repo tokfinity/auth-service \ --repo tokfinity/order-service \ --mode balanced ``` Equivalent HTTP: ```http POST /api/repos/ask Authorization: Bearer Content-Type: application/json { "query": "认证模块如何与订单服务交互？", "repos": ["tokfinity/auth-service", "tokfinity/order-service"], "mode": "balanced" } ``` Behavior: - Each repo is investigated in parallel by a dedicated subagent. - Results are synthesized by a final LLM call to produce a cross-repo answer. - For a single repo this is equivalent to a normal single-repo investigation. Mode selection: - `balanced` (default): general architecture/implementation questions. - `deep`: heavy cross-module or cross-repo investigations. Avoid for lightweight tasks. - `fast`: quick lookups; prefer `search` for these. ### Poll ask status ```http GET /api/repos/ask/{task_id} Authorization: Bearer ``` The `deepmap.sh ask` command handles polling internally. Cancel an accepted ask task with: ```http POST /api/repos/ask/{task_id}/cancel Authorization: Bearer ``` ## Multi-Repo Rules - If the user explicitly names repo B, query repo B directly even if the local workspace is repo A. - If repo A depends on repo B and local source for B is absent, use DeepMap for B to understand the external behavior. - If repo A is associated with repo C but the task has no relation to C, do not query C. - For cross-repo questions, submit one `ask` task with all relevant `repos`. ## Evidence Rules When answering with DeepMap: - Cite repo and generated document path when available. - Include line ranges or URLs from `search`/`ask` citations when available. - State uncertainty when `health.index_status` is not `healthy`, coverage is low, or search returned keyword fallback. - For exact implementation claims, verify local source if the file exists in the current workspace. - If local code and DeepMap disagree, say so and prefer local code. ## Version Rules Knowledge endpoints accept optional `branch` and `commit`. - No `branch` or `commit`: use the latest generated commit on the repo HEAD branch. - Only `branch`: use the latest generated commit on that branch. - Only `commit`: use that commit snapshot. - Both: exact match for that branch and commit. Use explicit `branch`/`commit` when the user asks about a specific version, release, or historical behavior. Otherwise use defaults. ## Error Handling | Error | Meaning | Agent behavior | |-------|---------|----------------| | `unauthorized` | Auth token missing/expired | The script handles one silent refresh when available. If it still fails, ask the user to re-authenticate DeepMap. | | `forbidden` | User lacks permission | Explain permission issue; do not claim repo is absent. | | `repo_not_found` | Repo absent or inaccessible | Try `/list` for accessible repos; ask user to confirm repo if needed. | | `knowledge_not_ready` | Knowledge not generated | Do not use DeepMap for that repo; fall back to local/source docs. | | `task_limit_exceeded` | Too many ask tasks | Wait or use `search` instead. | | `server_error` | DeepMap service problem | Fall back to local analysis and mention DeepMap was unavailable. | ## Common Mistakes - Querying every accessible repo just because `/list` returns it. Select repos by relevance. - Using DeepMap to answer exact current-code questions without checking local files. - Treating generated knowledge as live. It may lag behind local branch or commit. - Calling `ask` for simple lookup questions that `search` can answer faster. - Ignoring citations. DeepMap answers should be grounded in repo/path/line evidence.