dsh-bundle/dsh-bundle

一句话定位

把 HoloGram 的代码依赖分析引擎 + 3D 星图打包成一个 DeepSeek Harness bundle 插件：DSH 的 Agent 直接获得 35 个 MCP 图分析工具，DSH web 侧边栏底部出现"3D 星图"按钮，点开就能全屏看项目依赖图。

核心能力

• 注入 35 个 MCP 图分析工具（mcp__hologram__*），Agent 可直接调用，影响面、循环依赖、脆弱模块、引用追踪等查询一次拿到结构化事实
• DSH web 侧边栏底部注册"3D 星图"按钮（收起态显示 🌌 图标），点击全屏打开 Three.js 渲染的项目依赖星图
• 同源自托管 /hologram/ 路由（viewer 静态资源 + /hologram/api/graph 实时数据接口），不依赖任何独立开发端口
• 引擎单一进程双入口：MCP stdio（35 个工具）与 TCP 9777（viewer）跑在同一个进程里，共享同一份内存图
• 文件变更走 watcher 增量更新，依赖图始终保持新鲜，无需手动重扫
• 支持 ?refresh=1 强制全量重扫，或调用 MCP analyze_project 显式触发

技术实现

• 语言: TypeScript（host half 在 Node.js 运行；client half 在浏览器运行）
• 关键依赖: @deepseek-ai/cordis（cordis 运行时）、@deepseek-ai/dsh-mcp-client（MCP 连接桥）、@deepseek-ai/schemastery（配置 schema 校验）、three（viewer WebGL 渲染）
• 架构模式: DSH bundle 插件 + DSH client-plugin 双形态；cordis.patch.yml 注入 hologram-engine（解析二进制路径，提供 hologramEngine 服务）与 hologram-mcp（复用 DSH 自带的 dsh-mcp-client 经 stdio 拉起引擎）两行；dsh.client 字段声明 browser half 注入
• 入口文件: dsh-bundle/src/index.ts（host 半，cordis 插件 apply）、dsh-bundle/src/client/index.tsx（client 半，侧边栏 footer.action 槽注册）、dsh-bundle/cordis.patch.yml（cordis 行声明）

适用场景

DSH 用户在大中型代码库里做依赖分析、影响面评估、死代码检测、循环依赖排查时，传统做法是让 LLM 逐文件读源码去猜依赖关系——准确率低且 token 消耗巨大。HoloGram DSH 把 tree-sitter 静态分析预先算好的依赖图直接做成 MCP 工具，Agent 一次工具调用拿到结构化事实，单点查询省 70% 左右 token、全局分析省 90% 以上；同时侧边栏 3D 星图让用户能直观看到模块聚类与耦合关系。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:834063245-creator/HoloGram/dsh-bundle

配置项

配置写在 DSH profile 的 cordis.patch.yml 里（覆盖 hologram-engine 行的 config 字段），或写在 $DSH_HOME/cordis.patch.yml。

常见问题

Q: 这个插件支持哪些操作系统？

A: 目前仅 Windows x64 受支持。postinstall 脚本会从 GitHub Releases 下载 win32-x64 引擎二进制；如果当前平台不是 win32-x64，安装脚本会明确报错并中止，并提示"Linux/macOS 支持在路上"。引擎二进制本身也是 Windows 版的，Linux/macOS 路线尚未落地。

Q: 引擎和 3D 星图用的是同一份图数据吗？

A: 是的。引擎以 serve --project-root <root> --tcp 单进程双入口运行：stdio MCP（35 个工具）与 TCP 9777（viewer 后端）跑在同一个进程里，共享同一份内存图，watcher 增量更新同步生效。MCP 工具和 3D 星图读到的是同一份数据，不存在两份缓存不一致的问题。

Q: 是否需要手动配置要分析的项目路径？

A: 不需要。默认情况下引擎分析 DSH 进程的当前工作目录。3D 星图按钮被点击的瞬间会取"当前会话的工作区 cwd"作为 ?project= 参数，所以点开星图分析的就是当前会话正在编辑的项目。要固定分析某个特定路径才需要在 hologram-engine 行加 config.projectRoot: <路径>。

Q: 安装时报"unable to verify the first certificate"怎么办？

A: 这是企业自签 CA 环境下的常见 TLS 校验失败。可以设置 NODE_EXTRA_CA_CERTS=<你的根证书路径> 环境变量后重新安装；也可以绕开网络下载，在本地用 npm run pack:bin 把 engine/target/release/hologram-engine.exe 手工复制到包的 bin/ 后再 npm install --ignore-scripts。

Q: 安装后需要重启 DSH 吗？

A: 需要。引擎二进制与 host/client 包都装在 DSH profile 的 node_modules 里，DSH web 进程持有文件句柄（Windows 上 EPERM: rename），所以初次安装或本地更新后必须重启 dsh web，重启后侧边栏底部才会出现"3D 星图"按钮，MCP 工具才会进入 Agent 工具箱。

Q: 引擎二进制存放在哪里？

A: 包内的 bin/hologram-engine.exe（约 60MB）。postinstall 时从 GitHub Releases 下载到该路径（tag 与 npm 版本号一致）；本地开发则通过 npm run pack:bin 从主仓 engine/target/release/ 复制过来。

Q: onnxruntime.dll 是必需的吗？

A: 不是。缺失不影响 35 个 MCP 图分析工具与 3D 星图的核心功能，只影响可选的向量/语义搜索功能（MiniLM embedding）。如果不需要语义搜索功能，可以忽略这个文件。

Q: 如何卸载？

A: 在 DSH 中运行 dsh plugin --profile web remove @a834063245/hologram-dsh，然后重启 dsh web，侧边栏入口与 MCP 工具就会消失。

上手难度

入门 — 安装命令一行搞定，postinstall 自动拉取引擎二进制并放置，无需任何额外配置；3D 星图按钮点击即用，分析目标自动跟随当前会话工作区。

已知问题与限制

• 仅支持 Windows x64：postinstall 脚本只在 win32-x64 平台下载引擎二进制；其他平台直接报错中止（Linux/macOS 在路线图中）。来源：dsh-bundle/scripts/install.mjs:28-31, 60-62
• 安装时需要网络访问 GitHub Releases：引擎二进制不在 npm 包里（包保持 <1MB），安装时按版本号从 https://github.com/834063245-creator/HoloGram/releases/download/v<version>/hologram-engine-win32-x64.exe 下载。来源：dsh-bundle/scripts/install.mjs:33-54
• DSH web 运行中安装/更新会被 EPERM 拒绝：DSH 进程持有 node_modules 文件句柄，必须重启 dsh web 才能落位。来源：dsh-bundle/docs/phase2-dsh-integration.md:46-78
• file: 本地安装是复制语义：本地开发改了包源码后需要 remove + add 刷新本地副本，否则 dsh-bundle/README.md:91 注释提示 DSH profile 里的副本不会同步。
• enableWebRoutes: true 依赖 webServer 服务：在 headless profile（无 webServer 服务注入）下，/hologram 路由与 3D 星图按钮都不会注册，但 MCP 工具与 hologramEngine 服务仍可工作。来源：dsh-bundle/src/index.ts:25, 293-296, 326-331
• 3D 星图首次分析大项目较慢：viewer 在等引擎分析超过 120 秒会超时取消；用户可在 HUD 看到"分析超时（>120s）或已取消"提示。来源：dsh-bundle/viewer/main.ts:46, 73-77

HoloGram — 深空代码拓扑观测站：把代码库编译成可对话的 3D 依赖星图，并内置多 Agent 编码工作台

定位

HoloGram 把代码库解析成一张统一 IR 依赖图（节点 = 符号/函数/类/模块，边 = 调用/继承/读写/时序/数据流），通过 MCP 协议向 AI Agent 暴露 35 个默认图查询工具（注册表共 36 个 schema），并提供 Tauri 2 桌面应用（3D 星图 + 内置多 Agent 编码工作台）与 DeepSeek Harness（DSH）插件集成。

核心主张：依赖推理应当是确定性的，而不是猜的。

LLM 分析"改 A 会炸什么"时，靠逐文件读源码推测依赖——弱模型会漏，大项目会翻不动。HoloGram 用 tree-sitter 静态分析预先算好整张依赖图：Agent 一次工具调用拿到结构化事实（影响面、循环、脆弱模块、数据流路径），而不是源文件文本。单点查询省 ~70% token，全局分析省 90%+；省 token 是次要的，可靠性是主要的。

引擎是单文件二进制，本地运行、零配置、代码不出机器。它同时服务三种形态，共享同一份内存图与 watcher 增量更新：

• MCP 服务（hologram-engine serve）—— 接入 Claude Code / Cursor 等任意 MCP 客户端；
• 桌面应用（Tauri 2 壳）—— 3D 星图 + Monaco 编辑器 + 内置 Agent 工作台；
• DSH 插件（@a834063245/hologram-dsh）—— 引擎 + 星图打包进 DeepSeek Harness。

特性总览

快速开始

MCP 模式（推荐，1 分钟）

引擎随 Releases 发布（Windows / Linux），安装脚本一键完成。也可以把下面这段话直接发给你的 AI 编程工具，让它自己装：

请帮我安装 HoloGram MCP 服务。步骤：

1. 从 https://github.com/834063245-creator/HoloGram/releases 下载：
   - Windows: hologram-engine-windows-x64.zip
   - Linux:   hologram-engine-linux-x64.tar.gz
2. 解压后运行安装脚本：
   - Windows: 双击 install.cmd
   - Linux:   ./install.sh --user
3. 在当前 AI 编程工具的 MCP 配置中注册：
   - command: hologram-engine
   - args: serve
4. 重启 AI 编程工具，调 engine_status 验证

{
  "mcpServers": {
    "hologram": {
      "command": "hologram-engine",
      "args": ["serve"]
    }
  }
}

MCP 服务默认暴露 35 个工具；注册表里全部的 36 个 schema（含 legacy 的 symbol_history）可通过环境变量 HOLOGRAM_MCP_TOOLS=* 放开。

CLI

引擎自带一站式 CLI，复用与 MCP/桌面端完全相同的引擎逻辑：

hologram run --list                          # 列出所有工具
hologram run graph_summary .                 # 项目概览（节点/边/解析率）
hologram run trace_impact . --node_id src/main.rs:main   # 影响面
hologram run preflight_check . --files a.rs,b.rs         # 改前检查（exit code 表达结果）
hologram run detect_cycles .                 # 循环依赖
hologram run list_flows .                    # 执行流（按安全敏感度排序）
hologram serve --project-root . --tcp        # MCP stdio 服务（可同时开 TCP :9777）
hologram --stress <path> <iters>             # 压力测试 / 基准

桌面应用

Releases → 下载 .msi（Windows）→ 选项目 → 自动出图。桌面端与 MCP 模式共用同一个引擎进程与数据。

DeepSeek Harness 集成（hologram-dsh）

引擎 + 3D 星图打包为 DSH bundle 插件 @a834063245/hologram-dsh：

dsh plugin --profile web add @a834063245/hologram-dsh
dsh web
# 重启后：mcp__hologram__* 工具进工具箱 + 侧边栏「3D 星图」入口

• MCP 图分析工具直接注入 DSH agent（与桌面/MCP 模式同一引擎、同一份数据）
• 3D 星图：DSH web 侧边栏入口，全屏渲染项目依赖图（同源自托管，无独立端口）
• 单一数据生命周期：引擎单进程双入口（MCP stdio + TCP 9777），存量秒开 + watcher 增量更新
• 安装说明与数据模型见 dsh-bundle/README.md

图分析引擎

数据模型

• 节点（9 种）：Symbol（通用/未分类）· Function（函数/方法/构造）· Class（类/结构体/枚举）· Module（命名空间/包）· File（源文件模块）· Interface（接口/trait/类型别名）· Variable（变量/常量/字段）· Medium（存储/IO）· Temporal（异步/定时器）
• 边（12 种）：Imports · Calls · Inherits · Defines · Reads · Writes · Shares · Triggers · Awaits · Sequences · Usage · Throws
• 边属性：耦合深度 L1–L4、跨文件标记、时序延迟（秒）、lsp_resolved、is_synthesized（启发式合成边）、溯源 metadata

分析管线

文件发现 → 分批并行解析（200 文件/批，rayon）→ 串行合并（内存有界、无锁、线性）
→ 跨文件引用解析 → L1-L4 耦合分析 → 24 框架路由 → 动态分发/DI/反射/React JSX 合成边
→ 数据流合成（函数级读写 + 共享状态 + async trigger/await 链）→ 社区检测（Leiden/Louvain）
→ 落库（MemoryIndex CSR + SQLite/FTS5 + 语义向量索引）

• Engine 状态机：Uninitialized → Loading → Ready ↔ Analyzing → Error，panic 守卫，重新分析可抢占在途任务
• 增量更新：watcher（2s 防抖）只重解析变更文件并增量合图，失败自动回退全量；桌面端"保存即刷新"
• 存储：内存 CSR 索引（高并发读）+ SQLite WAL 持久化 + FTS5 全文 + usearch HNSW 语义向量（MiniLM ONNX 384 维 与 n-gram 双后端自动选择）
• 诚实标记：eval/动态代码标为不可达，动态 import 标为动态站点，跨语言调用（子进程/HTTP/FFI）以合成边标记运行时桥接点——不假装知道运行时才知道的事

语言支持

27 种 tree-sitter 语法静态链接；其中 18 族适配器有手工调校的查询式结构抽取（js/ts/tsx 一族、c/cpp 各一族）：

Python · JavaScript/TypeScript/TSX · Rust · Go · Java · C/C++ · C# · Ruby · PHP · Swift · Dart · Scala · Zig · Elixir · Lua · Bash · R

其余静态链接语言（OCaml · Haskell · Nix · HTML · CSS · YAML · Erlang）走 tree-sitter 通用兜底遍历；JSON 语法在代码中禁用（数据文件不产生图节点，不浪费解析）；Kotlin / Markdown / TOML 通过 .dll/.so 动态加载（grammars/），无需重新编译引擎即可扩展语言。

MCP 工具面（36 schema，默认 35）

每个工具返回结构化 JSON（不是源文件），并附带推荐的下一步工具；失败时返回带 guidance/fallback 的降级响应而非硬错误。

精确解析：LSP 与 SCIP

• LSP 管理器按需拉起 9 个原生语言服务器（rust-analyzer / gopls / pyright / typescript-language-server / clangd / jdtls / omnisharp / intelephense / kotlin-language-server），自研 JSON-RPC 帧协议（字节流定界、快速失败、死壳自愈），提供精确的调用解析 / 类型推断 / 接口实现 / 引用查询
• SCIP 导入（import_scip）：导入 SCIP 索引提升符号级引用精度，带自动钩子与诚实的跳过统计

内置 Agent 编码工作台

桌面应用内置完整的多 Agent 运行时（与 DSH 集成共用引擎数据）。改代码前先问图：graph(symbols → impact → preflight) 是工作流入口。

领域工具（13 个，旧细粒度名已淘汰）

模型可见面上只有 13 个高内聚领域工具，每个工具内部是 action 判别联合：

旧细粒度名（run_shell、write_file、git_*、search_symbols 等）保留在注册表但对模型隐藏，调用会被 retireRedirect 拦截并返回 [已淘汰] → 领域动作 重定向。新增工具必须 defineTool + zod v4（一个 schema 同时产出 JSON Schema / 运行时校验 / 类型化参数）。

Agent 运行时内核

• 声明式装配（agent-core-convergence Phase 6）：AgentBlueprint capability 表驱动装配——新增工具/hook 走 capability 组合，AgentConfig 冻结 31 字段不再扩张；capability 表序 = 工具面字节契约（保护 DeepSeek 前缀缓存与 effective 快照）
• 会话事件溯源（Phase 5）：session 变异只走 _appendMessage / _replaceSession / _retractSessionRange 三个入口，SessionLog 事件日志支撑差分对拍、回放与审计
• 生命周期内核（cordis-migration P0–P4）：vendored cordis 内核（src/cordis/，Context/Fiber/Service）——工作区级资源以 Workspace._fiber.ctx.effect() 登记（顺序敏感拆除组打包 DisposerBag 作单个 effect 保串行逆序）；Agent 挂身份 fiber（hologram/agent，DisposerBag 同步快通道契约保留）；子系统以 Service 挂树（样板 LspService）；epoch 代际防护永久保留（管逃逸所有权的在途回调，fiber 管所有权，两者不重叠）。切换/退出只调 fiber.dispose() + epoch bump（事故记录见 INVARIANTS.md #12）
• 流式执行：tool_use 完成即 dispatch（不等整条 stream），同轮只读工具并发执行；工具输出 50KB/2000 行截断；可重试错误指数退避（最多 3 次）；AbortSignal 贯穿，卡死工具不挂死循环
• token 治理：工具结果滚动折叠、成本模型驱动的 auto-compact（compactRatio 默认 0.55，压缩只作用于发送载荷，session 永为完整历史）

多 Agent 协作

• SubAgentPool：并发上限 5、队列 20、默认超时 30 分钟；fork（继承上下文）/ fresh（干净启动）两种模式；async spawn 完成后经 MessageBus 通知父 Agent
• 通信层：有界 inbox（100 条，满了 drop 防背压）、peek + ack、主题拓扑（Tree/Mesh/Star），消息持久化 .hologram/agents/{id}/inbox.json
• 共享状态板：TaskBoard（任务状态 / filesTouched / diff）与 DiscoveryBoard（探索发现，TTL 2h）——均按会话隔离，防跨会话串扰
• 隔离执行：子 Agent 的编辑在独立 git worktree 中运行（见下文"隔离"），agent_merge 进程内串行合并
• 模型可见的子 Agent ID：sub-{timestamp}-{random}；worktree ID：agent-{timestamp}-{random}

Plan 与 Goal 模式

• Plan 模式：只读探索 + 写计划文件，exit_plan_mode 提交方案（可带多选项）给用户审批；写约束由 planGate 在执行层拦截，工具 schema 跨模式恒定（保护前缀缓存）
• Goal 模式：持久化目标状态（.hologram/goals/{id}/，goal/session/index 三文件），跨会话恢复，与普通对话完全隔离；完成靠 goal_report 工具

记忆体系

LLM Provider 体系

• 模型目录：9 个静态 catalog JSON（anthropic 14 / openai 29 / moonshotai 10 / qwen 5 / deepseek 4 / glm 3 / minimax 3 / ollama 3 / opencode 2，共 73 个模型）+ 运行时 fetchModels() 拉取 /models 动态合并（静态目录同 ID 优先）
• 协议适配：统一 Provider trait 抹平 Anthropic Messages 与 OpenAI 兼容两大协议；流式 chunk 类型 Text / Reasoning / ToolCallStart / ToolCall / Usage / Done / Error
• thinking 档位：自动 / low / medium / high / max / off，wire 参数按厂商适配（Anthropic budget_tokens：4k/8k/16k/32k；DeepSeek reasoning_effort：high/max；OpenAI 官方 low/medium/high）
• 本地反向代理：壳侧起 loopback-only 的 HTTP 代理（127.0.0.1:14570）转发 LLM 请求并强加 CORS 头，绕开浏览器直连 API 的跨域限制，SSE 逐块透传
• 连接探针：ConnectionProbe 最小连通性验证（成功/失败/耗时），结果持久化
• 凭据：系统级加密存储（Windows DPAPI / macOS Keychain / Linux secret-tool），本地永不明文

一致性门禁

npm run verify:convergence（src-ui）：T0 静态断言（AgentConfig 冻结、session 变异入口、capability 序）+ 8 个 frozen baseline 对拍，任何变更破坏契约即失败。record 模式需显式 CONVERGENCE_RECORD=1，baseline 变更走审批（docs/plans/agent-core-convergence/baseline-change-request.md）。

Harness Engineering（桌面端）

约束治理

hologram.constraints.yaml 定义不可逾越的架构边界（L5 永远路由、L4 静默破溃默认路由、波及半径阈值、跨社区边容忍、黑白名单）；Agent 编辑文件前必须过 preflight_check，引擎按图拓扑计算波及半径/跨社区影响/L4 穿透决定放行或路由人工确认。前端另有内存 fileIndex 的 preflight hook（<0.1ms 零延迟），编辑前把 ⚠️ 警告注入工具结果顶部。

权限引擎

• 规则三来源合并：系统 / 项目（.hologram/permissions.json）/ 会话，裁决结果四态：Allow / Deny / Ask（danger 红卡）/ Passthrough；模式 Ask / Auto / Yolo（Yolo 不旁路 Deny，auto 白名单只放行编辑类工具）
• Bash 危险命令引擎：13 类危险模式（rm -rf /、curl|sh、eval/exec/source、sudo/su、写 /dev/*、git push -f main、mkfs、shutdown …）+ PowerShell 特判（Invoke-Expression、iwr|iex、FromBase64String）+ 管道解码检测与可疑命令启发式
• 路径规则对 worktree 自动 reverse-map 回主仓库逻辑路径；_agent_id 每次调用显式传递，杜绝并行子 Agent 身份串扰

沙箱（三层）

• OS 层：Windows Job Object（进程树随父死亡、64 进程 / 1 GiB 上限）；macOS sandbox-exec；Linux bubblewrap；shell 走捆绑 MSYS2 bash（vendor，标准 MSYS2 根布局 usr/bin + tmp），Windows 原生任务才用 pwsh
• 路径层：canonicalize + 符号链接/junction 检测，读写边界校验；边界外不静默拒绝，升级为 Ask 弹窗
• 受限文件系统：统一 I/O 包装（100 MiB 读写上限、30s 超时、3 次瞬态重试、原子写）

隔离（git worktree）

每个子 Agent 一个 git worktree add --detach 独立工作区：正反向路径映射、范围 cherry-pick 串行合并（清失败≠合并失败）、重启后孤儿 worktree 收养、大 diff（>8K 字符）溢写 .hologram/spill/ 回传；TTL 清理与合并队列由前端 agent 层纪律保证（见 AGENTS.md）。

审计

全部工具调用落 .hologram/audit.jsonl（allowed / denied / user_approved / user_denied），配合 project_timeline 工具按时间线回溯分析历史。

桌面端

3D 星图

• Three.js WebGL 渲染（ACES 色调映射 + UnrealBloom 辉光），每节点 3 个 draw call（Fresnel 内核 + 双层辉光），万节点级瞬时渲染
• GPU 布局：WebGPU WGSL 三趟力导向计算，设备不可用时优雅降级 CPU（布局参数锁定，勿改）
• 星系折叠导航：社区 → 星系 → 星座 → 子星团无限下钻，跨星系边流
• 图数据分页：get_graph_page 逐页拉取（12000/页），全量到齐原子换入单次渲染；watcher diff 增量渲染（无重布局、无相机重置）
• 交互：hover 屏幕空间拾取、点击详情、Alt 框选、B 键 Blast 波及半径、路径查找、Agent 工具执行透镜/轨迹/热点高亮、diff 绿红覆盖、legend 可点击过滤、聚焦相机飞行

编辑器

点节点即开源码：Monaco（懒加载，~5MB 不入初始 bundle）+ 原生 LSP（补全 / 悬停 / 定义 / 引用 / 诊断，诊断缓存按工作区隔离）；浮动标签页、拖拽缩放、Ctrl+S 保存、并排 Diff。

聊天与面板

• 虚拟列表聊天（万条消息流畅）：流式渲染、reasoning 块自动折叠、工具调用卡片、子 Agent 消息、Plan 审批卡、权限卡（PromptShelf）
• 工作台面板：简报（Check）/ 约束 / 数据流 / 设置（Provider/Agent/Display/Languages/About）/ 智能体 / 待办；左缘时间轴 HUD（commit/违规/简报脉冲点阵）
• 顶栏 CommandBar + Ctrl+K 命令面板、左右 DockRail 停靠轨、状态栏遥测（节点/边/星座统计）

视觉系统

全 UI 统一 --obs-* 设计 token（24 个，唯一定义于 src/app/tokens.css）：void/glass/line/brass/pass/warn/fail + 字体栈；自托管字体（Fraunces 展示 / JetBrains Mono 数据 / LXGW 文楷正文 / Noto Serif SC）；"墨与黄铜"视觉语言：铅笔=未定稿、墨水=已定稿、烫金=完成、朱砂=风险，全 UI 仅金/朱砂/墨绿三有彩色（见 docs/design/visual-language-ink-brass.md）。

状态管理

面板级状态走 createScopedStore 注册表（messages / session / panel / input 四件套 + chat-store 聚合），app 级单例走 shell/dock/overlay store；ui/events.ts 旧总线已冻结（存量 ~20 个 import，新代码禁 import）。Workspace 统一状态容器原子化切换（deactivate → open → 注入），DisposerBag + epoch 防旧项目串台。

架构

┌─────────────── src-ui (TypeScript) ─────────────────┐
│  React 19 · Three.js 星图 · Monaco · Agent 运行时    │
│  zustand stores · Workspace（vendored cordis fiber 树）│
└───────────────────────┬─────────────────────────────┘
                        │ typedRpc / typedListen（134 个方法，单一契约）
┌─────────────── src-tauri (Rust / Tauri 2) ──────────┐
│  权限引擎 · 三层沙箱 · worktree 隔离 · ResourceLedger │
│  LLM 反向代理 · 加密凭证 · 审计 · PTY · CDP 浏览器     │
└───────────────────────┬─────────────────────────────┘
                        │ TCP 127.0.0.1:9777
┌───────────────────────▼─────────────────────────────┐
│  engine (Rust，单二进制 hologram-engine)             │
│  tree-sitter AST → 并行管线 → 9 节点/12 边依赖图      │
│  MemoryIndex (CSR) + SQLite/FTS5 + 语义向量          │
│  36 MCP schema（默认 35）· stdio / CLI / TCP 三入口   │
└─────────────────────────────────────────────────────┘

架构决策（为什么引擎独立二进制、为什么权限在壳层、为什么 Agent 在前端、为什么用 worktree 隔离）见 ARCHITECTURE.md。

工程事实

• 测试（2026-08-17 实测）：引擎 697 用例（lib 669 + bin 27 + doc 1，696 passed / 1 ignored）· 壳 322 用例（bin 308 + 集成 14，全绿；pwsh 冒烟在无 pwsh 7 的环境自动跳过）· 前端 1201 用例 / 116 文件（1200 passed / 1 skipped；首次全量在并行构建环境下偶发 1 失败，重跑通过）
• 自举：HoloGram 用自己的引擎分析自己的代码库——当前图快照 18,119 节点 / 65,508 边（2026-08-17）
• 实测（Linux kernel 全量，历史基准）：全量分析 1,770s 全程跑完，RSS 646MB；快照写入 2.44GB / 56.3s
• 并行解析 200 文件/批，边去重 625×；增量更新由 watcher 驱动（保存即刷新）
• 三端独立验证：engine cargo test · src-tauri cargo test · src-ui vitest run；前端另有 npm run verify:convergence 契约门禁
• 已知盲区以"诚实标记"处理：eval/动态代码标记不可达、动态 import 标记动态站点，不假装知道运行时才知道的事

从源码构建

# 引擎（MCP / CLI / DSH 只需要这个；Linux / Windows 均可）
cd engine && cargo build --release

# 桌面应用（Windows；会自动先跑前端构建）
cd src-tauri && cargo tauri build

# DSH 插件（做本地开发用，见 dsh-bundle/README.md）
cd dsh-bundle && npm install --ignore-scripts && npm run pack:bin && npm run build && npm run build:client

开发

cd engine && cargo test        # 引擎用例
cd src-tauri && cargo test     # 壳用例（权限/生命周期/隔离）
cd src-ui && npx vitest run    # 前端用例
cd src-ui && npm run build     # tsc --noEmit + vite build
cd src-ui && npm run verify:convergence   # Agent 运行时契约门禁
cd src-ui && npx biome check --write <改动文件>   # 格式（全仓存量基线勿顺手清）

项目理解与工作纪律见 AGENTS.md（Codex）与 CLAUDE.md（内置 Agent）；提交流程见 CONTRIBUTING.md；文档总索引见 docs/README.md（docs/archive/ 为已竣工施工稿，勿作现状依据）。

许可

HoloGram © 2026 Wenbing Jing — MIT。第三方组件（tree-sitter 语法库、SQLite、USearch、onnxruntime、mimalloc 等）版权声明见 THIRD_PARTY_NOTICES.md；安全策略见 SECURITY.md。