READMESource: main@2f3010dd
ArcVista · 观界
本地优先的架构观测台：接入一个 Git 仓库，自动生成可下钻的系统架构图、安全架构守护清单、业务知识图谱、复杂度与测试覆盖度，并支持对比不同分支之间的架构漂移与风险。
零第三方依赖，只用 Node 22 内置的 node:http + node:sqlite，数据保存在本机 SQLite；内置 6 套可切换皮肤。
为什么做它
大多数代码质量工具只告诉你"哪里有问题"，但很少回答系统级的四个问题：
- 这个系统现在长什么样（分层、边界、服务之间的真实调用与数据依赖）；
- 它有哪些架构守护（认证、授权、注入防护、扫描规则、CI 门禁），这些规则是否可追溯；
- 它的业务知识如何组织（业务域、能力、实体、事件、主流程）；
- 换一个分支之后，架构、守护规则、依赖、复杂度和覆盖率发生了什么变化，是否存在风险。
ArcVista 把这些问题做成一个可以直接下钻的看板，而不是一堆静态报告。
作为 DSH 插件
当前仓库根目录就是一个标准 DSH Bundle，包名 dsh-arcvista。安装到 DSH profile 后，DSH 左侧会出现 ArcVista 观界 入口，点击即可在工作区内打开完整的 ArcVista 页面。
- 不需要单独启动 Node 服务：ArcVista 的 API 和静态页面由 DSH Host 插件直接挂载在
/arcvista路径下； - 不需要配置模型：分析使用 DSH 当前选择的默认模型（例如
deepseek-flash），模型调用通过 DSH 的llm服务完成；设置页不提供模型配置； - 数据仍保存在本机：默认写在
~/.dsh/arcvista/（SQLite、备份和仓库镜像），不会写进node_modules； - 面板顶部显示运行状态，右上角可以刷新或在独立浏览器窗口打开；
- 主题跟随 DSH 的浅色 / 深色模式（映射到
daylight/obsidian），内嵌页面隐藏了 ArcVista 原来的左侧栏； - 插件随 DSH 启动而加载，无需手动维护端口或进程。
安装
从 GitHub 安装（推荐，固定 Commit 更安全）：
dsh plugin --profile web add https://github.com/yonking305/arc-vista.git
发布到 npm 后也可以直接安装：
dsh plugin --profile web add dsh-arcvista
本地开发：
dsh plugin --profile web add /absolute/path/to/arc-vista
发布与商店
- 发布包名：
dsh-arcvista - 仓库：https://github.com/yonking305/arc-vista
- 当前声明兼容 DSH：
0.2.0-rc.2
插件 Host 代码更新后需要重启一次 DSH 才会加载新模块；只改页面样式 / 前端逻辑时刷新页面即可。
权限与数据
这个插件会在 DSH Host 进程里执行以下操作，安装前请确认：
- 用
git克隆 / 拉取被观测仓库，读取工作区文件，生成静态分析结果； - 在 DSH profile 的
arcvista/下写 SQLite、备份和任务状态； - 通过 DSH 的
llm服务调用当前默认模型做语义增强； - 在 DSH Web 服务器注册
/arcvista路由，用于面板和 API。
不包含 install / prepare 等生命周期脚本，不修改 DSH 核心，不占用 @deepseek-ai/* 命名空间。
快速开始
要求：Node.js >= 22.5（使用内置 node:sqlite），本机安装 git。
cd arc-vista
npm start
打开 http://127.0.0.1:4321，点击「新建观测目标」，填入：
- 产品名称；
- Git 仓库地址（支持
https:///ssh:///git@/ 本地绝对路径）； - 可选分支与描述。
创建后会先在后台克隆 / 拉取仓库，完成后进入产品的「分支分析清单」：勾选要分析的分支（可多选）后开始分析，任务会按队列依次执行，全部分析完成后进入看板。
不需要
npm install：项目没有任何运行时依赖。第一次分析需要能访问仓库地址。
皮肤
内置 6 套皮肤，左下角的调色盘按钮即可切换，也可以在产品设置页里预览选择：
| 皮肤 | 风格 |
|---|---|
| 深空观测（默认） | 墨蓝底 + 琥珀信号灯，夜航观测台气质 |
| 蓝图档案 | 深蓝工程图纸 + 电光青标注 |
| 纸本手记 | 暖纸 + 朱砂批注，浅色，适合白天阅读与投屏 |
| 午夜霓虹 | 洋红 + 电光蓝，高对比机房霓虹 |
| 苔原深林 | 墨绿 + 黄铜，低饱和长时段观色 |
| 日光实验室 | 冷灰 + 信号橙，浅色、干净、适合截图归档 |
皮肤只改变界面配色，不影响任何分析结果；选择保存在浏览器 localStorage，刷新与重新打开都会保留。架构图、知识图谱、图表和绘制的颜色都通过主题变量驱动，切换时无需重新分析或刷新页面。
功能
0. 仓库准备与分支分析清单
- 新建产品后先显示克隆 / 拉取进度，完成后自动刷新出分支清单；
- 每个分支显示最新提交、是否已分析、分析中 / 排队中 / 上次失败等状态；
- 可勾选多个未分析分支批量开始，任务按队列依次执行；
- 已分析分支可以直接「查看看板」或「重新分析」；
- 全部分析完成后自动进入看板，也可以随时从看板右上角「分析分支」打开清单。
1. 系统架构图（可下钻）
- 由仓库结构、构建清单、网关路由、Feign 声明、编排配置与依赖推断生成的分层架构图：客户端 → 接入层 → 服务层 → 数据层 → 基础设施 / 外部系统。
- 拖拽平移、滚轮缩放、节点悬停高亮依赖链路；点击节点打开节点详情（指标、复杂度驱动、上下游依赖、下钻入口）。
- 下钻分析：进入单个模块的内部结构（按 Controller / Service / Domain / DTO / 事件 / 配置等职责聚合的依赖子图）、关键流程、对外接口、调用方/被依赖方、数据组件、模块风险与改进建议；支持继续追问该模块。
- 模型由 DSH 统一提供，架构的命名、业务职责、外部系统与连接会基于代码证据做语义增强；没有模型时启发式结果同样完整可用。
2. 安全架构守护
- 19 类守护族：身份认证、授权/RBAC、输入校验、注入防护、传输加密、CORS、CSRF、限流、SAST、依赖扫描、密钥扫描、硬编码密钥、审计日志、依赖锁定、容器安全、安全响应头、安全测试等。
- 每项守护给出
enforced / partial / missing状态、规则清单、证据文件与行号、改进建议。 - 解析
semgrep、ESLint 安全规则、CodeQL、SonarQube、gitleaks、Dependabot、Renovate、Snyk、Trivy、Dockerfile、lockfile、Spring Security / JWT / MyBatis / helmet / express-rate-limit 等真实配置。 - 规则清单是可 diff 的：分支对比会逐条列出新增和移除的规则。
3. 业务知识图谱
- 业务域来自服务边界；能力来自 Controller 聚合；实体来自领域模型；事件来自 Kafka / RabbitMQ 主题与监听器；数据组件来自依赖与编排配置；参与者来自客户端入口。
- 卡片式业务域泳道：业务能力、领域实体、事件、数据组件、参与者分别用不同类型卡片呈现；接口与领域实体默认收起避免过密，可在筛选器中展开。
- 普通滚动只滚动页面，
Ctrl/⌘ + 滚轮或工具条缩放；点击节点查看业务含义，并从业务域下钻到对应代码模块。 - 模型由 DSH 统一提供，自动补充业务语义、业务能力、主业务流程（如"下单 → 支付 → 扣减库存 → 发货签收"）与跨域事实。
4. 复杂度
- 系统复杂度评分 + 模块级矩阵：LOC、文件数、平均/最大文件行数、分支密度、扇入/扇出、Git 变更频率。
- 识别复杂度热点、给出可执行的治理建议；前端 CSS/SCSS 等样式文件不计入复杂度评分。
- 雷达图展示系统形态（规模、文件粒度、耦合、变更热度、测试缺口）。
5. 测试覆盖
- 优先解析真实覆盖率产物：
coverage/coverage-summary.json、lcov.info、JaCoCojacoco.xml、Coberturacoverage.xml、.nyc_output。 - 没有产物时使用明确标注的估算值（测试/源码 LOC 比、测试文件比、用例数、零测试模块），并在界面和风险条目中说明局限。
- 展示测试用例数、测试文件、模块覆盖、未覆盖模块与大文件、测试缺口清单。
6. 分支对比与风险判断
选择任意两个快照（通常来自两个分支）进行对比：
- 结论：整体改善 / 基本稳定 / 需要关注 / 存在风险，附质量变化分与增量风险分。
- 指标变化：安全分、守护规则数、系统复杂度、行覆盖率、测试用例数、代码规模、模块数、依赖数、业务 API 数、风险代码模式。
- 安全守护 diff：新增/移除守护、状态变化、规则集逐条增删。
- 依赖 diff：新增/移除依赖、版本升级（major 标记）、降级。
- 复杂度 / 覆盖率 diff：模块级升降排名、新增未测试文件、测试用例减少。
- 架构与业务 diff：架构节点增减、业务域/实体/接口/事件变化。
- 风险清单：只把本次变更引入的风险计入结论；目标分支的历史高危单独列为"存量风险"，避免把老问题算到新分支头上。
模型
作为 DSH 插件运行时，分析始终使用 DSH 当前选择的默认模型（例如 deepseek-flash），不需要在 ArcVista 里配置 Base URL、模型名或 API Key。
模型用于：架构图的业务命名、分层语义与外部系统补全；业务知识图谱的业务域/能力/流程；架构风险与治理建议；模块下钻的职责说明与追问回答。
没有可用模型时，架构、依赖、安全守护、复杂度、覆盖率与知识图谱仍由静态分析引擎完整生成，风险规则照常运行。
工作方式
Git 仓库 ──► 本地镜像（bare）──► 按提交检出 worktree
│
┌─────────────────────────────┼──────────────────────────────┐
▼ ▼ ▼
文件/模块/依赖图 安全守护扫描 覆盖率产物解析
│ │ │
├──────────────┬──────────────┴──────────────┬───────────────┤
▼ ▼ ▼ ▼
架构模型 知识图谱 复杂度 风险规则
└──────────────┴──────────► 可选 LLM 语义增强 ◄─────────────┘
│
▼
快照（SQLite）+ 分支 diff
- 仓库以 bare mirror 形式缓存在
data/repos/，按提交创建临时 worktree，分析完成后只保留最近用到的 worktree；不会修改你的仓库。 - 每次分析生成一个不可变快照，包含完整分析 JSON、指标摘要、提交信息与引擎信息。
- 分支对比基于快照计算，不依赖实时重分析。
Git 超时与断点续传
大仓库首次克隆可能很慢。克隆、拉取与检出遇到超时或网络错误会自动重试（默认共 4 次，退避等待 2s / 4s / 6s）：
- 克隆中断时会保留已经下载的数据，下一次尝试自动改为
git fetch断点续传，而不是从头再克隆； - 记录每次重试的原因与次数，可在任务日志中看到（"克隆失败（操作超时），2.0s 后自动重试（第 2/4 次）"）；
- 网络长时间不可用导致最终失败时，任务卡片会提示可点「重试分析」继续续传，已下载的镜像不会丢弃；
- 克隆、拉取、检出的超时时间与重试次数都可以用下方环境变量调整，例如大仓库可以调大
ARCVISTA_GIT_CLONE_TIMEOUT_MS。
数据、备份与隐私
- DSH 插件模式下，所有数据保存在
~/.dsh/arcvista/arcvista.db（SQLite）；独立 CLI 模式使用data/。 - 仓库镜像与检出代码在数据目录的
repos/、worktrees/，可随时删除，重新分析会重建。 - 自动备份：启动时、每次分析完成以及删除产品前，会把 SQLite 快照写入数据目录的
backups/（默认保留 12 份，文件权限 600；可用ARCVISTA_BACKUP_DIR修改位置，ARCVISTA_BACKUP_KEEP修改保留数量）。 - 自动恢复：如果数据目录里的
arcvista.db缺失或无法打开，启动时会自动从最近一份包含产品的备份恢复，并在启动日志和设置页提示恢复来源。 - 设置页「当前状态」可以看到数据目录、备份目录和最近备份时间，也可以点「立即备份数据」手动备份。
- 仓库镜像体积可能较大；备份只包含数据库（产品、快照、设置），不会重复备份仓库镜像。
- 模型调用通过 DSH 的
llm服务完成，ArcVista 不保存 API Key；分析时只把仓库证据摘要（模块、依赖、路由、配置、指标等，不含完整源码）发送给 DSH 当前模型。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT |
4321 |
服务端口 |
HOST |
127.0.0.1 |
监听地址 |
ARCVISTA_DATA |
./data |
数据目录 |
ARCVISTA_BACKUP_DIR |
./backups（data 的同级目录） |
数据库自动备份目录 |
ARCVISTA_BACKUP_KEEP |
12 |
备份保留份数 |
ARCVISTA_NO_AUTO_RESTORE |
— | 设为 1 时禁止数据库缺失时自动恢复 |
ARCVISTA_GIT_RETRIES |
4 |
克隆/拉取/检出失败时的总尝试次数 |
ARCVISTA_GIT_RETRY_DELAY_MS |
2000 |
Git 重试的基础退避时间（毫秒） |
ARCVISTA_GIT_CLONE_TIMEOUT_MS |
900000 |
单次克隆超时（默认 15 分钟） |
ARCVISTA_GIT_FETCH_TIMEOUT_MS |
300000 |
单次拉取超时（默认 5 分钟） |
ARCVISTA_GIT_WORKTREE_TIMEOUT_MS |
300000 |
单次检出超时（默认 5 分钟） |
ARCVISTA_DEBUG |
— | 打印异常堆栈 |
API 一览
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/products |
产品列表（含最新快照与任务状态） |
POST |
/api/products |
创建产品并自动开始分析 |
GET |
/api/products/:id |
产品详情、快照、分支、任务 |
POST |
/api/products/:id/analyze |
分析分支（branch、force） |
GET |
/api/products/:id/snapshots/:sid |
快照完整分析结果 |
POST |
/api/products/:id/modules/analyze |
模块下钻（异步任务） |
GET |
/api/products/:id/compare |
分支/快照对比 |
GET |
/api/jobs/:id |
任务进度与日志 |
目录结构
arcvista/
├── server.js # HTTP 服务与 API 路由
├── lib/
│ ├── analyze/ # 静态分析引擎
│ │ ├── walk.js # 文件扫描（排除构建产物/依赖目录）
│ │ ├── modules.js # 模块边界识别
│ │ ├── graph.js # 导入/依赖图
│ │ ├── deps.js # 构建清单依赖解析（npm/maven/gradle/pip/go）
│ │ ├── security.js # 安全架构守护
│ │ ├── coverage.js # 覆盖率产物解析与估算
│ │ ├── complexity.js # 复杂度
│ │ ├── architecture.js # 架构模型
│ │ ├── knowledge.js # 业务知识图谱
│ │ ├── evidence.js # 路由/实体/事件/Feign/编排证据抽取
│ │ ├── enrich.js # LLM 语义增强与启发式风险
│ │ ├── drilldown.js # 模块下钻
│ │ └── index.js # 分析编排
│ ├── diff.js # 快照对比与风险规则
│ ├── git.js # mirror / worktree / 分支 / churn
│ ├── db.js # SQLite
│ ├── jobs.js # 后台任务
│ ├── llm.js # OpenAI 兼容客户端
│ └── http.js # 极小 HTTP 框架
├── public/ # 零构建前端（原生 ES Modules + SVG）
│ ├── css/
│ └── js/
├── docs/
│ ├── analyzer-contract.md # 内部分析器契约
│ └── screenshots/
├── tests/ # node:test 冒烟测试
└── data/ # 运行时生成（gitignore）
开发与测试
npm test # 使用 node:test 运行分析器与 diff 的冒烟测试
npm run dev # node --watch 热重启
前端是原生 ES Modules + SVG，没有构建步骤；修改 public/ 后刷新即可。
已知边界
- 覆盖率优先使用仓库中的真实产物；没有产物时是估算值，只能用于判断覆盖明显偏低或缺失，不能当作真实覆盖率。
- 安全守护与风险模式是启发式识别，结论会附证据路径，但仍建议人工复核。
- 架构中的服务间调用来自网关路由、Feign 声明、导入关系与配置推断；运行期的动态调用（如反射、消息路由）可能无法完全还原。
- 仓库扫描有文件数与单文件大小上限（默认 2 万文件 / 1.2MB），超大 monorepo 可调整
scanRepo参数。 - 私有仓库需要本机 git 凭据（SSH key 或 credential helper）可用。
- 分支对比的语义依赖守护规则 ID、模块路径、API 路径的稳定性；大范围重命名会被视为删除 + 新增。
- LLM 增强需要网络与模型费用；失败会自动回退到启发式分析并在快照中记录提示。
与 Archify 的关系
架构图能力借鉴了 Archify 的分层表达与交互思路（分层、边界、图例、下钻），但 ArcVista 把它放进了持续观测的产品看板：仓库即数据源、快照可对比、结论可追溯，并增加了安全守护、知识图谱、复杂度、覆盖率与分支风险判断。
License
MIT
No comments yet. Be the first to write one.