Introduction¶
In the pluggable ecosystem of DeepSeek Harness (DSH), enabling an AI coding agent to accurately understand an unfamiliar codebase and maintain strict boundary control while reviewing changes is a common requirement in development. dsh-repo-atlas is a plugin designed for this purpose. It helps agents analyze repositories based on evidence and review change proposals within a bounded lifecycle.
What This Is¶
dsh-repo-atlas is a DeepSeek Harness plugin maintained by zhenkun26. It aims to address the lack of structured evidence in codebase understanding and the lack of lifecycle management in change review. By providing evidence-first conclusions and bounded operational policies, the plugin enables AI agents to safely take over repositories and review changes.
Core Features¶
Repository Analysis¶
The plugin scans confirmed workspaces, following path, content, sensitive-file, and budget constraints. It generates structured evidence, Markdown reports, architecture observations, and a recommended reading order. Specifically, it includes:
* Onboarding analysis: identifies the tech stack, entry points, important directories, tests, and configuration, and provides a recommended reading order.
* Evidence-first conclusions: distinguishes file-supported observations from textual inferences and explicitly preserves partial or unknown states.
* Bounded syntax confirmation: confirms selected imports, declarations, and relationships without executing repository code.
* Session incremental reuse: reuses compatible evidence only within the current Harness session.
Change Proposals and Lifecycle¶
The plugin tracks change flows limited to the current session, including:
* Defining explicit goals and intent.
* Reviewing, exporting, and validating bounded patches.
* Checking live worktree state, commit readiness, landing relationships, recovery guidance, and release readiness.
* Managing isolated commits, landing preflight, recovery guidance, and release preflight.
Safety Boundaries¶
To ensure safety, the plugin runs in read-only mode by default and strictly limits the scope of operations:
* Read-only by default: paths are read-only by default; it does not silently generate or apply patches, commits, merges, landing, pushes, publishing, dependency installation, network access, or code upload.
* Controlled actions: controlled actions are disabled by default. Enabling them requires a fixed recipe, explicit approval, sandbox enforcement, and bounded redacted output.
* Session state: evidence cache, proposal registry, event history, and preflight evaluation are limited to the current session and returned as detached observations.
* Git lifecycle: isolated local operations are bounded; automatic conflict resolution, remote access, rollback, and push are not provided.
Installation and Enablement¶
Loading this plugin requires a compatible DeepSeek Harness checkout. Installation steps are as follows:
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm run build
cd /absolute/path/to/deepseek-harness
pnpm install
pnpm dsh plugin --profile web add /absolute/path/to/dsh-repo-atlas
pnpm dsh web
Look for dsh-repo-atlas/harness in the plugin list in the Harness Web UI.
Local Checks¶
Local development and checks require Node.js 22 or higher. Developers can run the following commands to validate code quality:
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm test
npm run typecheck
npm run lint
npm run build
Maintainers can run the full repository gate:
npm run validate:openspec
npm run verify:release-preflight
git diff --check
Use Cases and Notes¶
This plugin is suitable for scenarios that require structured repository takeover and controlled change review in AI agent environments. When using it, note the following:
* The plugin runs with the current DSH process permissions. Check the source code and license (MIT) before installation.
* Controlled actions are disabled by default. If enabling them, you must configure a fixed recipe, explicit approval, and sandbox checks.
* The plugin only provides status observations and recommendations; it does not execute code generation, commits, or publishing operations.