Overview

The plugin ecosystem of DeepSeek Harness (DSH) is dedicated to extending agent capabilities through plugins. In agent development, maintaining architectural consistency is a common pain point: code changes can easily cause design documents or architecture diagrams to become outdated, and manual synchronization is costly. dsh-normify targets this scenario and provides a complete closed-loop solution from data modeling and validation to visualization.

What Is It

dsh-normify is a DeepSeek Harness plugin maintained by yan-mc. Its core positioning is a “normalized framework diagram builder,” aiming to describe the entire project as a “human- and AI-readable” fractal module tree.

The plugin splits functionality into three audience-oriented aspects:
* For AI: Provides the normify-gen skill and 31 normify_* tools. This toolchain supports a workflow of building the graph first and coding later, and updating the graph alongside coding, so the model first establishes the structural tree and then implements modules one by one.
* For Engine: Executes zero-tolerance validation and deterministic compilation. This includes L1 validation on write, whole-project L2 validation, and a final L3 frozen receipt for the produced artifact.
* For Humans: Outputs a single-file interactive architecture diagram (normify.html). It has zero external dependencies, opens with a double-click, and supports layer-by-layer drill-down, direct API connection arrows, and deep links.

Core Features

1. Data Model: Fractal Structure

The plugin uses a fractal module tree structure to implement a zero-redundancy data model. The entire database is composed of countless structurally identical “basic modules,” and each module corresponds to a Markdown file. The data model stores only the parent relationship; children are derived through an index, avoiding data inconsistency. API information is stored only once at leaf nodes, with indexes generated at compile time. Path-style IDs combined with immutable UIDs ensure that the AI can accurately locate modules.

2. Three-Layer Validation Mechanism

The plugin guarantees data consistency through three layers of validation:
* L1 (validation on write): Checks required fields, ID syntax, UID, parent consistency, and other items on every write.
* L2 (whole-project validation): Uses normify_validate to check global uniqueness, file-to-ID mapping, leaf/non-leaf rules, API key uniqueness, dependency targets, and architecture rules.
* L3 (frozen receipt): Executed via normify_build; if any error exists, no artifact is produced. Once produced, the artifact is SHA-256 frozen and recorded in receipt.json.

3. Accompanying Development Process

The plugin provides a complete accompanying development process to keep code and architecture diagrams synchronized:
1. Use change_open to start a change.
2. Use brief and check to confirm the goal.
3. Use module_batch(state=planned) to batch-create modules in the planned state.
4. Perform code implementation.
5. Use module_refresh(activate) to activate modules.
6. Use change_close to finalize; this step mandates 0 errors.

4. Single-File Interactive Architecture Diagram

The generated normify.html is a dependency-free single file. It supports layer-by-layer drill-down, search, outline view, and Chinese-English switching. Its core highlight is “direct API connection arrows”: the arrows can be anchored to specific API lines instead of merely landing at box edges. In addition, it supports deep links, zooming, hover highlighting, and light/dark themes.

5. Enforcement of Architecture Rules

Architecture rules are defined in policy.yml, including dependency direction, forbidden dependencies, acyclicity, depth limits, cross-tree dependency policies, and naming conventions. normify_validate and normify_build enforce these rules; violations prevent passing.

Installation and Activation

The official documentation does not provide specific installation commands. The plugin is located in the DSH plugin directory. Please find and install it via the SkillHub directory page.

Typical Usage

1. Initialize Project

Use the normify_project_init tool to create the project directory and default architecture rules.

2. Development Change Workflow

Perform accompanying development according to the following steps:

change_open → brief → check → module_batch(state=planned) → 【写代码】
→ module_refresh(activate) → change_close(0 error 强制)

3. Detect Drift and Repair

When code changes cause the architecture diagram data to diverge from the actual state, use normify_sync to detect drift and locate affected modules.

4. Retrieve Tool Parameters

Use normify_help topic:tool:<工具名> to retrieve the parameter tree for a specified tool so that the AI can invoke tools correctly.

Use Cases and Notes

  • Applicable scenarios: Suitable for agent development projects that require strictly structured documentation and architecture constraints. The plugin enforces architecture rules to prevent code from diverging from design.
  • Notes: The plugin runs with the current DSH process permissions. change_close requires 0 errors to close. Architecture rules (such as dependency direction, naming, cycles, etc.) must be strictly followed. The plugin uses the MIT license and has zero external dependencies.

Short Summary

dsh-normify addresses the disconnection between architecture diagrams and code in agent development through a fractal module tree, three-layer validation, and an accompanying development process. It provides complete infrastructure from data modeling to visualization, suitable for engineering scenarios with high requirements for code structure.

  • Directory page: https://www.skillhub.cn/plugins/yan-mc/dsh-normify
  • GitHub: https://github.com/yan-mc/dsh-normify