Safety-first, evidence-backed repository analysis and bounded change-lifecycle plugin for DeepSeek Harness.
面向 DeepSeek Harness 的安全优先、证据驱动代码库分析与有界变更生命周期插件。
RepoAtlas helps an AI coding harness understand an unfamiliar repository, explain what is directly evidenced versus inferred, and inspect a proposed change through a bounded, auditable lifecycle. The default analysis path is read-only; any controlled action is explicit, approval-gated, and sandbox-aware.
Why RepoAtlas
Repository analysis should be useful without becoming an unbounded automation surface. RepoAtlas is designed around three principles:
Evidence before confidence — bounded file evidence, syntax-confirmed observations, and explicit partial or unknown states instead of invented certainty.
Read-only by default — repository analysis does not require Shell, network access, dependency installation, source-workspace writes, or Git push.
Lifecycle clarity — proposals, patch review, verification, commit, landing, recovery, and release readiness remain distinguishable states; an observation is never presented as an applied patch, commit, landing, or release.
What it provides
Evidence-backed repository understanding
Onboarding: technology stack, entry points, important directories, tests, configuration, and a recommended reading order.
Node.js 22 or newer for RepoAtlas development and local checks.
A compatible DeepSeek Harness checkout for running the plugin.
pnpm 11.7.0 and Node.js 24.x for the pinned real-Harness smoke contract.
Install from a source checkout
RepoAtlas is currently distributed as a source/plugin bundle. Clone both repositories, install the Harness dependencies, and add the local RepoAtlas checkout:
git clone https://github.com/zhenkun26/RepoAtlas.git
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd /absolute/path/to/deepseek-harness
pnpm install
pnpm dsh plugin --profile web add /absolute/path/to/RepoAtlas
pnpm dsh web
In the Harness Web UI, the plugin should appear as repo-atlas/harness. The plugin does not modify the Harness core; the bundle patch loads the adapter from this repository.
Run RepoAtlas locally
cd /absolute/path/to/RepoAtlas
npm ci
npm test
npm run demo
The demo and test suite run directly from the TypeScript source under the repository's Node.js toolchain. No global TypeScript installation is required.
These are separate states, not a promise that code has been generated, applied, committed, landed, released, or published. Any write-capable path requires the relevant explicit configuration, exact digest checks, active Goal/approval context, and the repository's sandbox and postcondition controls.
Safety model
Boundary
RepoAtlas behavior
Core analysis
Read-only repository inspection with path, content, budget, and sensitive-file policies.
Evidence and lifecycle state
Evidence cache, proposal registry, event history, and preflight/readiness assessment are session-only and detached.
Controlled actions
Opt-in only; fixed recipes, explicit approval, sandbox enforcement, and bounded redacted output are required.
Git lifecycle
Isolated-worktree operations are bounded and local; automatic merge conflict resolution, remote access, push, rollback, and cleanup are not provided.
Network and dependencies
The RepoAtlas runtime does not fetch repositories, call remote services, install dependencies, or upload code.
Failure behavior
Missing capabilities, denied approval, malformed input, budget exhaustion, and uncertain postconditions fail closed or remain explicitly partial.
cordis.patch.yml and the dsh.bundle package metadata define the supported Harness loading path.
package.json intentionally keeps private: true.
npm run verify:source-artifact is a local packed-install evaluation; it is not an npm publication and does not create an ordinary Node consumer import contract.
No compiled dist/ distribution is promised.
Git tags, GitHub Releases, and npm publication are separate release decisions. The current project documentation does not claim that an npm package exists.
The manual release process and release checklist distinguish candidate readiness from actual release state. A green preflight is advisory evidence; it does not create a tag, GitHub Release, npm publication, or deployment.
Direct core API
RepoAtlas can also be used directly from a source checkout:
Direct API usage still follows the same evidence, path, sensitive-content, and budget policies. Importing the raw .ts entry point from an installed node_modules package is not part of the current support contract.
Development and verification
npm ci
npm run typecheck
npm test
npm run lint
npm run verify:source-artifact
npm run validate:openspec
npm run verify:release-preflight
git diff --check
The release preflight is a local, read-only candidate check. It intentionally reports blocked when the worktree, OpenSpec state, release documents, or human release gates are not ready; it never performs a tag, release, publish, push, deployment, or cleanup operation.
Open-source governance
RepoAtlas is released under the MIT License. Reuse, modification, and redistribution are allowed when the MIT copyright notice, license text, and disclaimer are retained.
When publicly citing, integrating, documenting, or deriving from RepoAtlas, please identify RepoAtlas / 代码星图 and link to the canonical source repository: . This provenance request is maintained separately in NOTICE.md and does not add legal conditions to the MIT License.
