dsh-code-atlas: Code Graph and Cognitive Layer Indexing Plugin

Introduction¶

In the DSH ecosystem, every time an Agent starts a new session, it must first “sweep” through the repository to understand the project structure. This exploration cost of “not knowing what to read” is high and can easily lead to missing critical information. dsh-code-atlas is designed to solve this problem by building a verifiable repository map through static analysis.

Plugin Overview¶

This is a plugin that provides Agent with a repository map. It uses a tree-sitter WASM symbol index, a repository map ranked by importance, and a one-line F/R/A/S cognitive layer per file to perform code analysis with zero native compilation. The index is stored in <repo>/.dsh-code-atlas/index.json, which is derived data.

Installation and Enablement¶

The installation command is as follows:

dsh plugin --profile <你的 profile> add github:qlheric/dsh-code-atlas

The installation process automatically introduces two WASM dependencies: web-tree-sitter and tree-sitter-wasms. After installation, dsh must be restarted.

Note: The desktop desktop profile does not support the above command. You need to manually modify the dsh.profile.bundles configuration in package.json and install using pnpm.

Core Features¶

The plugin provides 5 tools, covering the full workflow from index building to symbol queries:

code_atlas_index: builds the index, supporting status and build modes.
code_atlas_map: views the repository map sorted by importance.
code_atlas_search: searches symbols.
code_atlas_symbols: views exported symbols.
code_atlas_fras: views hard constraints (the S in F/R/A/S).

F/R/A/S Cognitive Layer¶

The plugin generates a one-line summary for each file, covering four dimensions:

F (File / Responsibility): what the file is responsible for. It preferentially reads the leading comment (after removing markers); if no comment exists, it falls back to the primary exported symbols.
R (Relationship / Relation): dependencies and dependents. It parses import statements within the repository; unresolvable relative imports are listed separately, without throwing exceptions.
A (Access / Entry): what external entry points exist. It records exported symbols in the name@line format. The “export” determination rules differ by language (JS/TS uses export_statement, Go uses uppercase first letters, Rust uses pub, Python/Ruby/Bash uses names not starting with _, C/C++ uses non-static).
S (Safety / Hard Constraint): what must not be handled incorrectly. It identifies discipline keywords in comments (mandatory / prohibited / caution / IMPORTANT / NEVER) and dangerous patterns (eval, child_process, rm -rf, shell:true, hardcoded secrets, disabled TLS verification, 777 permissions).

Boundaries and Limitations¶

Call graph: not implemented yet; the R column currently only covers file-level dependencies.
Index strategy: the index is fully rebuilt, with a 512KB limit per file. Unrecognized file extensions are not indexed.
Nature of S: the S column provides candidates, not conclusions. It only indicates that “rules were written” or “dangerous patterns appeared”; specific judgment requires human review.
Scan scope: dot directories (such as .dsh_probe/) are not scanned by default, to avoid polluting the map.

Summary¶

dsh-code-atlas provides a structured code view for Agent through a zero-compilation approach. It does not rely on complicated compilation processes; instead, it augments regular expressions with a tree parser, making it suitable for scenarios that require quickly locating code logic and potential risks.