dsh-normify

<a href="./README_EN.md">English</a> · <strong>简体中文</strong>

<h1 align="center">Normify · 归一化框架图构建器</h1> <p align="center"><b>把整个项目描述成一棵"人机共读"的分形模块树：AI 负责分析与创作，确定性引擎负责校验、编译与渲染 —— 点开任意模块，就是一张更精细的子图。</b></p>

---

0. 一句话

Normify 是 DeepSeek Harness（DSH）插件，也是一套写给 AI 用的开发流程：

• 给 AI 的：normify-gen 技能 + 31 个 normify_* 工具 —— 让模型把仓库分析成模块树结构数据， 并在后续开发中先建图后编程、伴随编程改图（计划态建树 → 逐个实现 → 关单收尾）。
• 给引擎的：零容忍校验（L1 写时 / L2 全项目 / L3 冻结）+ 确定性编译（tree.json 等四件产物，SHA-256 冻结）
  • 渲染数据（renders/，决定"每一层怎么画"）。
• 给人的：单文件交互式架构图（normify.html）—— 逐层下钻、悬停看介绍、一键中英切换、深链接、 多树、API 直连箭头、跨层聚合、缩放与搜索。零依赖，双击即开。

它不是"生成一张图就结束"的工具：结构数据与代码互为契约，每次改动都能被 normify_sync 检出漂移， 并以 normify_change_close（0 error 强制）收尾，让"代码 → 架构图"永远同步。

<br>_{<b>引擎层</b>：14 个模块、API 直连箭头（箭头锚定到具体 API 行）、带标签的子系统依赖、跨层聚合虚线}

1. 它解决什么问题

痛点	Normify 的做法
架构图一画完就过期	结构数据是可校验的源数据：normify_sync 按 fingerprint 检出漂移，normify_change_close 强制 0 error 收尾
图太粗，看不出接口契约	粒度到单一功能单元，API 写在叶子上，箭头可锚定到具体 API（from_api/to_api）
AI 改代码时"看不见全局"	normify_brief 给出目标模块契约、影响面（谁依赖我）、规则约束与验收清单
设计先写代码后补文档，必然漂移	计划态先建树（state: planned）→ 实现后 normify_module_refresh(activate) 自动转 active
结构规范靠人自觉	policy.yml 架构规则（依赖方向 / 禁依赖 / 无环 / 深度 / 跨树 / 命名）由 validate 强制执行
大仓库一次生成太重	增量再生成：只重建受影响子树，layouts_to_review 点名要复核的层

2. 核心特性

2.1 数据模型：分形 + 零冗余

• 唯一元素：整个数据库由无数个结构完全相同的基本模块构成（每个模块 = 一个 Markdown 文件）。
• 只存 parent：单方向引用，children 由索引导出 —— 不会出现"父子各说各话"。
• API 只在叶子存一次：聚合、统计、索引全部是编译期派生数据（tree.json / api-index.json）。
• 两类边：containment（树边，导航骨架）+ dependency（箭头，可跨子树、跨树，按 kind 着色）。
• 路径式 id + 不变 uid：AI 沿 id 逐层定位（类二分查找）；uid 在改名/移动时保持不变，git diff 稳定。
• 深度不设上限（0.5.0 起）：想有多细就拆多细，深度不再成为"合并模块"的理由。

2.2 三层校验，fail-closed

层	时机	内容
L1	每次写入	必填字段、id 文法、uid、parent 一致性、双语长度、source/apis/deps 形状、state/replacement
L2	normify_validate	全项目：唯一性、文件↔id 映射、叶子/非叶子规则、API 键唯一、依赖目标、环、渲染数据交叉校验、架构规则、变更日志、（可选）仓库证据（source 存在性 + 指纹一致）
L3	normify_build	任何 error 都不产出产物；产出即 SHA-256 冻结进 receipt.json

每条诊断都带 severity / code / message / subject / evidence / supportedFixes —— AI 可自行修复。

2.3 渲染器：单文件、可下钻、API 直连

• 单文件 HTML（内联 CSS/JS，零外部依赖、零遥测），双击即开，可直接归档/发人。
• 逐层下钻 + 面包屑 + 搜索（模块名/API）+ 大纲视图 + API 浏览器。
• API 直连：叶子框内展示 API 明细行，箭头锚定到具体 API 行的端口；同一 API 行上的多条边自动扇形分离。
• 跨层依赖聚合为虚线 ×N（默认隐藏，工具栏或 ?agg=1 开启，悬停看明细）。
• 深链接：#module=<id>、#api=<rpc:key>、#view=outline、?lang=zh|en、?agg=1；缩放 / 悬停高亮 / 明暗主题。
• 几何自检：仓库自带 check-geometry.mjs，逐层断言"线不出界 / 不贴框 / 不穿框 / 不压线"。

2.4 伴随开发：先建图后编程

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

• 计划态：源码还不存在也能先建树（fingerprint: pending），validate 放行；
• 禁止假激活：源码没落地就 activate 直接被拒；
• 收尾即闭环：change_close 会刷新指纹 → 校验（0 error 强制）→ 编译（可选渲染）→ 标记 verified， 任何一步失败都不关闭，变更保持原状态；
• 改图随代码：normify_sync 用 git diff + 未跟踪文件定位受影响模块与指纹漂移，module_patch 跟随更新。

2.5 架构规则先行（policy.yml）

规则	作用
dependency-direction	层顺序即允许的依赖方向（如 plugin → tools → engine），可控制同层是否允许
forbid-dependency	禁止某些 from → to 的依赖（可按 kind / state 过滤）
acyclic	依赖图禁止成环（可含跨树）
max-depth	id 段数上限（可选：不写就是不限，0.5.0 起默认不限）
cross-tree	跨树依赖策略：forbid / allow / require-to-api
naming	作用域内 id 段的命名正则

…