📖 使用手册
源码架构与结构分析 · Source & Structure

解剖一条防线:源码与功能

把 OpenArch 拆开看:源码部分解剖 42,396 行产品代码的分层骨架与结构信号, 功能部分清点命令面、机器契约、脚本引擎与治理闭环如何互相咬合。 每个数字都来自本仓库 openarch 自审与 Git 统计——不是估算,可复现。

对象 · openarch@0.1.4 · HEAD 62211855(2026-08-21 快照) 方法 · openarch context / review + git ls-files 逐层统计 结构 · 源码(分层 · 信号)+ 功能(全景 · 闭环 · 指标 · 理论)
"没有调查,没有发言权。"—— 《反对本本主义》,也是本报告的方法:先取事实,再作判断
概览

双轨解剖 源码侧是一条以 3,384 行纯函数 domain 为圆心的六边形防线—— 9 个可替换端口向外展开成 application(7,242 行)与 adapter(7,602 行),ESLint 锁死"adapter 不依赖 application"的边界; 功能侧由 15 个命令、5 份机器契约、3 个脚本引擎咬合成一条 "调查 → 防线 → 回扫 → 修复/校准 → 验证 → 沉淀"的治理闭环。 两轨在指标罗盘上会合:状态是基线,变化是信号。全部数值取自 HEAD 快照,重跑命令即得现势结论。

01 · 总体画像

用 openarch 跑自己,先拿到事实

来自 openarch context / review 的真实裁决与 git ls-files 统计(口径:tracked 的 .ts/.tsx/.go/.js/.mjs)。

PART Ⅰ · 源码

一条防线的骨架

分层是防腐的第一道结构防线:核心纯函数、合同可替换、边界由工具强制,而不是靠约定。

02 分层架构 · 03 结构信号
02 · 分层架构(源码)

以纯函数为圆心的六边形

依赖方向向内:CLI 与引擎子系统经 application 编排,application 只消费 port 合同,adapter 实现 port 并被 ESLint 禁止反向依赖 application。 光点沿辐条向圆心流动即依赖方向。悬停每一环查看职责与边界。

domain · 纯函数核心 3,384 行 port ×9 / application / adapter 外部消费者(cli · plugin · Go 服务) 悬停查看依据 →
层 / 组件行数职责边界规则
03 · 结构信号(源码)

高负担文件与契约候选

两类 report-only 信号,全部来自 openarch review 的真实输出: 结构候选解释指标策略(不自动形成 finding),定义面信号圈出"声明密集 + 规模大"的契约候选。 架构门禁 PASS、反模式 0 finding(WARN 与 async finding 已先后清除)——信号是调查线索,不是判罪。

局部负担(0–1,P95 归一化)
core cli plugin 点径 ∝ loc · 悬停查看 →

结构债 · 全绿之后,技术债仍在表上

哲学主张PASS 只是已声明策略未触发;不追求一次全绿,防线跟着主要矛盾走
审查事实门禁 PASS · 反模式 0 finding(WARN 与 async finding 已先后清除),但 Top-3 结构候选持续上榜(历史负载 579.0 / 266.5 / 73.9)

0.1.4 在本仓库上演了完整的一轮闭环:CRL WARN 2 由重构清除(c1cee7a6), 重构引入的 3 个 async-without-await 连同 4 个存量又被下一提交清零(62211855)—— 每次修复都被自己的规则当场验收。剩下的 diff / discover / docs 是成熟编排层大文件,作为显式技术债标注, 治理精力继续投向主要矛盾,而不是四处灭火。

证据 · openarch review(基线 2026-08-21 重扫,18 规则 0 finding)· c1cee7a6 清除 CRL WARN 2 · 62211855 清除 async-without-await ×7 · .openarch/config.yml 13 条已声明规则(双总体,校准=sealed)
PART Ⅱ · 功能

防线如何运转

功能不是功能清单的堆叠,而是闭环:命令采集事实,契约固定边界,脚本重建防线,指标路由验证强度。

04 功能全景 · 05 治理闭环 · 06 指标罗盘 · 07 理论落点
04 · 功能全景(功能)

八个位面的能力清点

每一项都对应可执行的命令与可复核的合同——没有一项是"规划中"。

05 · 治理闭环(功能)

六步一环,防线廉价可重建

这是 Skill 宪法里的最小闭环:每一步都有确定的命令入口与停止条件; 沉淀的经验回流为新一轮调查的输入——环闭合,腐化才不会在防线外绕行。

06 · 指标罗盘(功能)

状态是基线,变化是信号

三个指标各管一段:I_push 度量"这次改动推动多大的浪",CRL_state 度量"现在哪里负担最重",D_MR 度量"这次变更让负担变好还是变坏"。对数压缩让极端值不主导判断。

线性计数 n(归一化) log₂(n+1) 压缩后 信息论落地:inDegree 1 → 128 的压缩对比
07 · 理论落点

三大理论 → 源码与功能证据

哲学不写在标语里,写在可复核的载体上:每条理论都能指到命令、公式或防线。

理论实现载体证据