HoloGram

这是什么

兰台是 Windows 桌面 Agent 工作台（Tauri 2 壳 + TypeScript / React 19 前端）：一套完整的多 Agent 运行时。

仓库里住着两个产品面：工作台（src-ui/ + src-tauri/）与引擎（engine/ 及 hologram-* crate）。

快速开始

1. 装（Windows）：Releases 下载安装包 （.exe）→ 启动。从源码：仓库根 build.cmd（会先跑前端构建）。

卸载：设置 → 应用 → 兰台 → 卸载，确认页有「删除应用程序数据」勾选框（缺省不勾）。 勾上则一并清除用户级数据：~/.lantai（设置 / 全局记忆 / 技能 / 插件与其数据 / 老会话备份）、 改名老位 ~/.hologram，以及 %APPDATA%/%LOCALAPPDATA% 下的兰台目录（窗口状态、WebView2 缓存、加密的 API Key）。不勾 = 一个字节都不删，重装后原样继续（应用内自动更新走的也是这条 卸载路径，永不删数据）。工作区目录里的 {项目}/.lantai（会话正文、附图、画布布局）属于你的 项目文件，卸载器不会动它；脚本化完全卸载（GUI 勾选框的等价物）： uninstall.exe /S /PURGE-DATA（不带 /PURGE-DATA 的静默卸载不删任何数据）。 早先的旧 .msi 安装（2026-09-26 起不再提供 .msi）没有这条通路：先跑一次安装目录里的 lantai.exe --purge-user-data 再卸载即可——装新版的 .exe 时安装器也会自动接管旧 MSI 安装。

2. 进工作区：首次启动落在案卷首页——新建工作区（默认建在 ~/Documents/兰台/<名字>），或指定一个 已有目录：一个工作区就是一张纸。

3. 落笔：

• 输入框写下你要它做的事，回车即成第一卷（输入 / 出案卷命令）。
• **侧边栏「案卷」**管本工作区的卷：＋另起一卷 · F2 改名 · C 合卷（收起，数据保留）· 删除。
• 左缘书脊列出摊开的卷：点击定位、拖动落位、hover 合卷。书脊与侧边栏互斥两态（侧栏展开时书脊退场）。
• 权限卡在危险动作前弹出；Ask（默认）/ Auto（仅编辑类）/ Yolo 三档随时可切（详见护栏）。

想用图谱引擎：设置 → MCP →「随包图谱引擎」→ 勾选「启用随包图谱引擎」→ 下次打开工作区生效 （每工作区按各自的根起一个引擎进程，离开工作区即停）。

界面范式：一张会生长的纸

聊天界面把工作压成一条等权消息流：只能往下滚，多任务只能多开窗，想回到昨天那件事得靠搜索。 纸壳 · 注疏案卷换掉的是容器本身——会话是一个空间，不是一条流。

• 一个工作区 = 一张纸：多卷（会话）摊在同一片纸上，可对照、可追溯——平行的几件事靠「多卷 同屏」表达，而不是切窗口（运行中的卷还能同时跑，只是不能合卷）。左缘书脊一卷一脊、当前卷「抽出 一半」；合卷 = 离席但存盘，随时重新摊开。
• 位置即记忆：任意一块能钉成纸条留在纸边，也能拖到流区 / 纸条区落位；摊开集、纸条、落位全 落盘（.lantai/canvas*.json）——重启回到昨天摆好的案头，版面不用重建。
• 距离即粒度：平移无边界、缩放 0.35–2.4 档；拉远时正文退成行影、整卷成为一眼可辨的纹路（鸟瞰）， 拉近才是字（精读），右缘小地图给全部摊开卷的鸟瞰。
• 注疏层级取代等权气泡：不同来源有不同文体——来文（你的问话，手迹位）· 正文（AI 的答，居中 主角）· 夹注（思考）· 脚注（工具调用）· 抄录（diff）· 程文（程序执行）· 拟策（审批卡）· 贴黄（通知）· 错因（回合错误）——扫一眼就知道谁在说话、哪句是结论；在来文里写【关键词】，纸面 即渲染成朱砂圈点（人的批改）。块类型是开放面：内置 + Agent 资产 kind + 插件贡献。
• 回合有呼吸：流式输出按读包 / 写包 / 验证包 / 提交成族，不是等距瀑布；零摊开卷时是案头—— 退匣直书 + 最近几卷的签条架，落笔即另起一卷。

纸底 + 矿物墨色（朱砂＝人 / 石青＝机 / 石墨＝夹注 / 墨＝正文），自托管字体两枚（正文 MiSans 可变字体 + 机读位 Noto Sans Mono CJK SC 等宽，均随包不依赖系统安装）；版式契约见 docs/design/lantai-design-spec.md，视觉决定账本见 docs/plans/paper-shell/taste-ledger.md。

内置 Agent 工作台

工具面

模型只见一批高内聚域工具，每个域以 action 作首参——fs(read|write|edit|…)、 shell(run|output|wait|kill)、git(status|diff|commit|…)……；会话级另有 Skill、plan、通信族、 code_execution 执行原语（程序体在 Web Worker 沙箱里跑，可嵌套调用全部可见工具）。旧细粒度工具名已 淘汰，误调会被拦成「[已淘汰] → 域动作」。事实源 = 生成物 docs/agents/model-tool-contract.md；跨文档标量（字段数 / 域数 / 契约版本等）见 docs/facts.generated.md，本文不复述。

运行时

工具行 / prompt 段 / capability 三层装配面的表序是字节契约，由 npm run verify:convergence 双轨钉死；会话变异只走 _appendMessage / _replaceSession / _retractSessionRange 三个入口（SessionLog 支撑差分对拍、回放与审计）。规则见 CLAUDE.md · CONVENTIONS.md · INVARIANTS.md。

多 Agent

子 Agent 池（fork 继承上下文 / fresh 干净启动）+ 有界 inbox + 按会话隔离的 TaskBoard / DiscoveryBoard + git worktree 隔离执行（git worktree add --detach，cherry-pick 串行合并、孤儿收养、 TTL 清理）。

Plan / Goal

Plan 模式只读探索 + 写计划文件，交你审批后离开，写约束由 planGateCheck 在执行层拦截； Goal 模式把目标状态持久化在 .lantai/goals/{id}/，跨会话恢复。

记忆与 Provider

事件溯源会话记忆 · 项目记忆（.lantai/memory/*.md）· 技能 （.lantai/skills/<name>/SKILL.md，装完即用不必重启）；多厂商 Provider（Anthropic / OpenAI 兼容 / DeepSeek 等，清单可运行时拉取）+ loopback 反向代理（绕开 WebView 跨域）+ 系统级加密凭据（Windows DPAPI / macOS Keychain / Linux Secret Service）。

护栏

权限引擎合流系统 / 项目 / 会话规则，裁决 Allow / Deny / Ask / Passthrough（后者 = 该工具 自检无意见，中央闸按规则面放行、不弹窗），Yolo 不旁路 Deny；危险命令表拦 rm -rf /、curl | sh、 eval / source、sudo、git push --force main 等并对 PowerShell 特判；三层沙箱（OS 层 Windows Job Object / macOS sandbox-exec / Linux bubblewrap——发布主力是 Windows，另两者依赖系统自带沙箱程序；shell 默认走捆绑 MSYS2 bash · 路径层越界升 Ask · I/O 层读写上限、超时、重试、原子写）；经权限闸的调用落 .lantai/audit.jsonl（pty / lsp 等无闸能力口不在其中，code_execution 嵌套调用落 session-log）。

插件系统

出厂态没有任何一行硬编码特权：全部贡献行（含第一方）都可被 roster patch / preset 禁用、覆盖、锚定； 另有 manifest.mcpServers（挂外部 MCP server，零插件代码）与 manifest.activation（惰性激活：登记 ≠ 激活，按引用计数起停）。贡献通道与可换后端清单以生成物 docs/agents/service-catalog.md 为准。

• 最短路径：一个 manifest.json + 一个自包含 ESM 模块（动态 import 装载，无包管理器、无 import map） → PLUGINS.md 照着写，最快 15 分钟跑通；最小示例 examples/plugins/hello/。
• 权限与信任（如实声明）：manifest 声明 → 装载期授予门禁（一票否决）→ Rust 命令咽喉逐调用强制； 插件是本机全信任代码——不签名、不沙箱。
• 契约：docs/plugins/README.md · 组合层与 preset docs/composition/README.md · 三方发布 docs/user/develop/publishing-plugins.md。

配套引擎 HoloGram

与兰台的关系

引擎是独立进程（Rust 单二进制 hologram-engine）。壳只做二进制位置的只读探测 （engine_assets.rs；LANTAI_ENGINE_EXE 可覆盖），不链接任何引擎 crate；启用后由前端经受治进程通道拉起 （bundled-engine.ts → mcp-bridge.ts 的 ServerGovernor：懒启动 / 崩溃退避重启 / 空闲回收 / 进程树终止 → Rust protocol_bridge.rs stdio）。一进程一根（同根幂等、异根拒绝）、离开工作区即停；引擎数据落 工作区根 .hologram/，与兰台的 .lantai/ 分居。手动接法见 docs/engine-as-external-mcp.md。

它能做什么

把代码库静态解析成依赖图，让「改 A 会炸什么」变成确定性图查询，而不是让模型逐文件读 源码去猜：tree-sitter 语法静态链接 + 运行时 .dll / .so 动态加载；分批并行解析 → 跨文件引用 → L1–L4 耦合 → 框架路由 → 合成边 → 社区检测 → 落库（内存 CSR + SQLite / FTS5 + 语义向量，向量后端不可用时降级 n-gram）。分析后按项目语言异步预热原生 LSP，查询按需调用（调用解析 / 类型推断 / 实现 / 引用）；可 导入 SCIP 索引（只消费 index.scip，不代跑索引器）；watcher 增量合图、失败回退全量。循环 / 脆弱模块 / 架构盲点 / 执行流 / 数据流均为查询期能力（不随建图预计算）。诚实标记：eval 与动态代码标为不可达、 动态 import 标为动态站点；结果引用了索引后又被改过的文件时带新鲜度横幅。能力面与工具清单见 ARCHITECTURE.md §5–§6 与生成物 docs/agents/engine-plugin-contract.md。

三种消费形态

① 桌面应用内——设置 → MCP →「随包图谱引擎」（默认关）；② 任意 MCP 客户端——引擎就是 标准 stdio MCP server，复制仓库根 .mcp.json.example 为项目级 .mcp.json（用户级用 claude mcp add --scope user）；③ DSH 插件包 @a834063245/hologram-dsh——薄发布 适配层（不自带产品资产），Windows x64，装后重启 dsh web，图查询工具进 agent 工具箱 （mcp__hologram__*）。原先随包的 3D 星图已随主仓图谱渲染内核退役拆除，包内只发引擎 + MCP 工具面。

引擎 CLI

预编译产物——每个 v* tag 的 Releases 附件，解包后二进制与 grammars/ 同级（后者是 kotlin / markdown / toml 三个动态语法，引擎按 二进制同级目录自动加载）：

Intel Mac 没有预编译产物，走下面的源码构建（或 arm64 产物 + Rosetta）。浏览器下载的 macOS 二进制 未签名，被 Gatekeeper 拦下时 xattr -d com.apple.quarantine hologram-engine 解。

从源码构建（三平台均可）：

cd engine && cargo build --release

hologram-engine run --list                          # 列出全部工具（两列文本）
hologram-engine run <工具> [项目根] [--key value]     # 一次性执行：结构化 JSON 出参，退出码表达结果
hologram-engine serve --project-root <项目根>         # MCP stdio 服务（加 --tcp 同时开 TCP 数据面）

免编译扩展（不改 Rust）

扩展目录（HOLOGRAM_PLUGIN_DIR，缺省 <项目根>/plugins）放 manifest 即可 声明新语言（扩展名表 + 查询式）、新框架（路由候选）、新工具（schema + 复用既有 handler）； 装载情况经 engine_status.extensions 可见，单个 manifest 失败不阻断启动。示例见 examples/engine-plugins/。

架构与目录

src-ui/     (TypeScript)  React 19 · 注疏案卷纸壳 · Agent 运行时 · 组合层 · Provider 体系
src-tauri/  (Rust)        Tauri 2 壳 · 权限引擎 · 沙箱 · worktree 隔离 · 审计 · 凭据 · 受治进程
engine/     (Rust)        独立二进制：解析 → 图构建 → 分析 → 存储 → stdio MCP / CLI / TCP

前端与壳走单一契约的 typed RPC（生成物 docs/agents/frontend-rpc-contract.md）；壳与引擎无进程内依赖。 分层、数据流与关键决策见 ARCHITECTURE.md；四条最高架构约定见 docs/adr/project-constitution.md。

文档地图

开发与门禁

dev.cmd                                  # 开发窗：Vite HMR @127.0.0.1:1420，改前端保存即生效
build.cmd                                # 桌面安装包（等价 cd src-tauri && cargo tauri build）

cd engine && cargo test                  # 引擎用例
cd src-tauri && cargo test               # 壳用例（权限 / 生命周期 / 隔离）
cd src-ui && npx vitest run              # 前端用例（本机跑前先 $env:NODE_ENV='test'）
cd src-ui && npm run build               # tsc --noEmit + vite build
cd src-ui && npm run verify:convergence  # Agent 运行时契约门禁（standard + minimal 双轨）
cd src-ui && npm run doc-check           # 文档面门禁

门禁不过不 commit。 基线数字会漂移，以重新实测为准（基线值与运行纪律见 CONVENTIONS.md §3）。提交流程见 CONTRIBUTING.md；开工前必读 CLAUDE.md（唯一权威规则文件）与 AGENTS.md（薄指针）。

许可

兰台（Lantai）© 2026 Wenbing Jing — MIT。第三方组件版权声明见 THIRD_PARTY_NOTICES.md；安全策略见 SECURITY.md。