Introduction

When developing or debugging agents with DeepSeek Harness (DSH), quickly understanding the structure of an unfamiliar codebase is a fundamental requirement. Traditional approaches rely on reading files manually or organizing information by hand, which is inefficient and can easily miss important details. The arch-doc plugin in the DSH ecosystem uses a “scanner extracts facts + template filling” approach to automatically generate architecture documents that include module responsibilities, dependencies, and entry points.

Plugin Overview

arch-doc is a DSH skill plugin maintained by duyanta123. Its core purpose is to analyze a codebase and generate structured architecture documentation. The plugin extracts hard facts (such as languages, directories, dependencies, and entry points), combines them with LLM-based template filling, and outputs documentation covering the project type, module division, dependencies, and how to run the project.

  • License: MIT
  • Repository: https://github.com/duyanta123/arch-doc
  • Plugin Page: https://www.skillhub.cn/plugins/duyanta123/arch-doc

Core Features

The plugin mainly performs the following tasks:

  1. Hard Fact Extraction: Identify the languages used by the project, the directory structure, internal and external dependencies, and entry points.
  2. Project Detection: Determine the project type (e.g., CLI/Web/Worker), build system, and repository type (monolithic/multi-module).
  3. Module Analysis: Determine how modules are divided and the responsibility of each module.
  4. Entry Point Identification: Detect whether the application runs as a CLI, web service, worker, scheduler, or library.
  5. Visual Output: Generate module dependency diagrams in Mermaid format.
  6. Structured Data: Output machine-readable analysis results in JSON format.

Installation and Activation

Installing the plugin requires the official commands. Note that although the GitHub repository is named arch-doc, the npm package name is changed to dsh-arch-doc according to the reverse package-name rule.

1. Install as a DSH Plugin

It is recommended to install a specific version using the DSH plugin manager:

dsh plugin --profile web add "github:duyanta123/arch-doc#v0.1.4"

2. Install as an npm Package

You can also install it directly via npm:

npm install dsh-arch-doc

After installation, restart the corresponding profile to load the plugin.

Typical Usage

After installation, you can invoke the skill in DSH using natural-language instructions, or run the standalone script directly.

1. Use as a DSH Skill

Issue an instruction in the conversation to ask the agent to analyze the codebase at the specified path:

Use arch-doc to analyze /path/to/repo

The agent performs the scan, extracts facts, and generates the documentation.

2. Run as a Standalone CLI

The plugin provides a standalone Node.js script that supports step-by-step execution or full scanning.

Run a full scan:

node scripts/arch-profile.mjs <repo_path> --all

Run specific tasks step by step:

# 仅探测项目类型
node scripts/arch-profile.mjs <repo_path> --probe

# 仅扫描目录和模块职责
node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3

# 仅提取依赖关系
node scripts/arch-profile.mjs <repo_path> --deps

# 仅检测入口点
node scripts/arch-profile.mjs <repo_path> --entry

Common parameters:

  • --max-depth <N>: Limit the directory scan depth (1-10); defaults to 3.
  • --language <L>: Specify a language hint (python/javascript/typescript/go/java/generic).
  • --include-dirs / --exclude-dirs: Specify directories to include or exclude from analysis.

Use Cases and Notes

Use Cases

  • Quickly onboard to legacy systems: Generate an architecture overview quickly when taking over a new project.
  • Hybrid-stack project analysis: Identify dependencies among modules written in different languages.
  • Documentation automation: Maintain project documentation and ensure it stays in sync with the code structure.

Caveats

  1. Security boundaries:

    • The scanning process is read-only. It does not execute code in the target repository and does not write to the source code.
    • The scanner itself has zero dependencies, does not spawn child processes, and does not access the network.
    • Output is limited to the docs/ directory under the target repository and generates three files.

  2. Mermaid rendering limitations:
    Generated Mermaid diagram files (.mmd) may fail to render in a browser when opened via the file:// protocol. It is recommended to use a local editor such as Typora, or paste the source into an online tool such as mermaid.live to view them.

  3. Hybrid-stack projects:
    For projects containing multiple languages, the plugin determines the primary language based on build-file priority (for example, in a Go+Node project, go.mod has higher priority than JS configuration files).

Short Conclusion

As a lightweight, zero-dependency architecture analysis tool, arch-doc separates scanning logic from documentation generation logic, providing DSH agents with reliable codebase comprehension. Its structured documentation and dependency diagrams significantly lower the barrier to understanding a codebase.