dsh-normify

English · 简体中文

Normify · 归一化框架图构建器

把整个项目描述成一棵"人机共读"的分形模块树：AI 负责分析与创作，确定性引擎负责校验、编译与渲染 —— 点开任意模块，就是一张更精细的子图。 0. 一句话

Normify 是 DeepSeek Harness（DSH）插件，也是一套写给 AI 用的开发流程： 给 AI 的：normify-gen 技能 + 7 个原语工具（normify_project / read / write / check / build / render / change，按 op 分派；旧 31 个工具名可经 legacyTools 过渡）—— 让模型把仓库分析成模块树结构数据， 并在后续开发中先建图后编程、伴随编程改图（计划态建树 → 逐个实现 → 关单收尾）。 给引擎的：零容忍校验（L1 写时 / L2 全项目 / L3 冻结）+ 确定性编译（tree.json 等五件产物 + receipt.sha256 回执自证链） 渲染数据（renders/，决定"每一层怎么画"）。 给人的：单文件交互式架构图（normify.html）—— 逐层下钻、悬停看介绍、一键中英切换、深链接、 多树、API 直连箭头、跨层聚合、缩放与搜索。零依赖，双击即开。 它不是"生成一张图就结束"的工具：结构数据与代码互为契约，每次改动都能被 normify_check{op:"drift"} 检出漂移， 并以 normify_change{op:"close"}（0 error 强制）收尾，让"代码 → 架构图"永远同步。

引擎层 ：14 个模块、API 直连箭头（箭头锚定到具体 API 行）、带标签的子系统依赖、跨层聚合虚线 1. 它解决什么问题 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 每条诊断都带 severity / code / message / subject / evidence / supportedFixes —— AI 可自行修复。 2.3 渲染器：单文件、可下钻、API 直连 单文件 HTML（内联 CSS/JS，零外部依赖、零遥测），双击即开，可直接归档/发人。 逐层下钻 + 面包屑 + 搜索（模块名/API）+ 大纲视图 + API 浏览器。 API 直连：叶子框内展示 API 明细行，箭头锚定到具体 API 行的端口；同一 API 行上的多条边自动扇形分离。 跨层依赖聚合为虚线 ×N（默认隐藏，工具栏或 ?agg=1 开启，悬停看明细）。 深链接：#module= 、#api= 、#view=outline、?lang=zh|en、?agg=1；缩放 / 悬停高亮 / 明暗主题。 几何自检：渲染器内置逐层几何断言思路（线不出界 / 不贴框 / 不穿框 / 不压线）；早期用于校验截图的独立脚本未随仓库分发。 2.4 伴随开发：先建图后编程 计划态：源码还不存在也能先建树（fingerprint: pending），normify_check{op:"validate"} 放行； 禁止假激活：源码没落地就 activate / close 直接被拒； 收尾即闭环：change{op:"close"} 会刷新指纹 → 校验（0 error 强制）→ 编译（可选渲染）→ 标记 verified， 任何一步失败都不关闭，变更保持原状态； 改图随代码：normify_check{op:"drift&q

第二轮 A/B 换了题目（表格公式引擎 + CLI，同一份规范、隐藏黑盒 88 项、外加差分模糊测试）。 两组最终 B 88/88、A 87/88（差异只有一条 §5.2 语义）；这一版修的是工具侧新暴露的 4 个坑： mode:"patch" 的静默 no-op 被拦下：原来 items:[{patch:{id, tags:[...]}}]（少一层包装）会返回 ok:true, count:1 却一个字段都没改——最危险的"假成功"。现在直接报 args/invalid-patch， evidence 里给出收到的键与正确形状 {patch:{id, patch:{...}}}；单模块 normify_module_patch 传空补丁 同样报 args/empty-patch（只给 expect_updated_at 也不再静默通过）。 normify_module_refresh 不再强依赖 git：repoRoot 不是 git 仓库时，以前直接失败 （实测中 AI 只能 git init 才能激活模块）；现改为降级并给 refresh/git-unavailable 警告。 change_open 的 acceptance 报错具体化：以前把 {zh,en} 写进 acceptance 只有一句笼统报错； 现在明确写出"第 N 条不是非空字符串（收到 …）：验收标准只接受纯字符串"，并提示双语描述写进 title/intent。 normify_help 支持 topic:"tool: "：tools 主题现在每个工具都带必填/可选摘要， 新主题可按需打印完整参数树（类型 / 描述 / 必填，由注册表实时生成、与运行时校验同源）。 实测里 AI 为确认 mode=p