前言¶
DeepSeek Harness（DSH）的插件生态致力于通过插件扩展智能体的能力。在智能体开发中，维护架构一致性是一个常见痛点：代码变更容易导致设计文档或架构图失效，人工同步成本高。dsh-normify 针对这一场景，提供了一套从数据建模、校验到可视化的完整闭环方案。
这是什么¶
dsh-normify 是一个 DeepSeek Harness 插件，由 yan-mc 维护。它的核心定位是“归一化框架图构建器”，旨在将整个项目描述成一棵“人机共读”的分形模块树。
插件将功能拆分为三个面向对象：
* 面向 AI：提供 normify-gen 技能以及 31 个 normify_* 工具。这套工具链支持“先建图后编程、伴随编程改图”的流程，让模型先建立结构树，再进行逐个模块的实现。
* 面向引擎：执行零容忍校验和确定性编译。包括写时的 L1 校验、全项目的 L2 校验以及最终产出的 L3 冻结回执。
* 面向人：输出一个单文件交互式架构图（normify.html）。它零外部依赖，双击即开，支持逐层下钻、API 直连箭头以及深链接。
核心特性¶
1. 数据模型：分形结构¶
插件使用分形模块树结构，实现零冗余数据模型。整个数据库由无数个结构相同的“基本模块”构成，每个模块对应一个 Markdown 文件。数据模型只存储 parent 关系，children 通过索引导出，避免数据不一致。API 信息只在叶子节点存储一次，编译期生成索引。路径式 ID 配合不变 UID，确保 AI 能准确定位模块。
2. 三层校验机制¶
插件通过三层校验保证数据一致性：
* L1（写时校验）：每次写入时检查必填字段、ID 文法、UID、Parent 一致性等。
* L2（全项目校验）：通过 normify_validate 检查全局唯一性、文件与 ID 映射、叶子/非叶子规则、API 键唯一性、依赖目标以及架构规则。
* L3（冻结回执）：通过 normify_build 执行，任何 error 都不产出产物，产出即进行 SHA-256 冻结并记录在 receipt.json 中。
3. 伴随开发流程¶
插件提供了一套完整的伴随开发流程，确保代码与架构图同步：
1. 使用 change_open 开启变更。
2. 使用 brief 和 check 确认目标。
3. 使用 module_batch(state=planned) 批量建立计划态模块。
4. 执行代码编写。
5. 使用 module_refresh(activate) 激活模块。
6. 使用 change_close 收尾，该步骤强制要求 0 error。
4. 单文件交互式架构图¶
生成的 normify.html 是一个零依赖的单文件。它支持逐层下钻、搜索、大纲视图以及中英切换。其核心亮点是“API 直连箭头”，箭头可以锚定到具体的 API 行，而不是仅仅落在框边。此外，支持深链接、缩放、悬停高亮以及明暗主题。
5. 架构规则强制执行¶
通过 policy.yml 定义架构规则，包括依赖方向、禁止依赖、无环、深度限制、跨树依赖策略以及命名规范。normify_validate 和 normify_build 会强制执行这些规则，违规时无法通过。
安装与启用¶
官方资料未提供具体的安装命令。该插件位于 DSH 插件目录，请通过 SkillHub 目录页面进行查找和安装。
典型用法¶
1. 初始化项目¶
使用 normify_project_init 工具建立项目目录和默认架构规则。
2. 开发变更流程¶
按照以下步骤进行伴随开发：
change_open → brief → check → module_batch(state=planned) → 【写代码】
→ module_refresh(activate) → change_close(0 error 强制)
3. 检测漂移与修复¶
当代码变更导致架构图数据与实际不符时，使用 normify_sync 检出漂移，并定位受影响的模块。
4. 获取工具参数¶
使用 normify_help topic:tool:<工具名> 获取指定工具的参数树，以便 AI 正确调用工具。
适用场景与注意¶
- 适用场景：适合需要严格结构化文档和架构约束的智能体开发项目。插件通过强制执行架构规则，防止代码与设计偏离。
- 注意：该插件以当前 DSH 进程权限运行。
change_close强制要求 0 error 收尾。架构规则（如依赖方向、命名、环等）必须严格遵守。插件采用 MIT 许可证，零外部依赖。
短结尾¶
dsh-normify 通过分形模块树、三层校验和伴随开发流程，解决了智能体开发中架构图与代码脱节的问题。它提供了一个从数据建模到可视化的完整基础设施，适合对代码结构有较高要求的工程场景。
- 目录页：https://www.skillhub.cn/plugins/yan-mc/dsh-normify
- GitHub：https://github.com/yan-mc/dsh-normify
