内容
<img src="docs/preview.jpg" alt="Luia 图：团队知识位于中心，项目工作围绕它展开，选中一个节点以显示其连接" width="100%">
# Luia
**设计团队的知识图谱**
设计团队积累知识的速度比他们整理知识的速度更快。团队在 3 月份同意的间距规则、测试效果不佳的轮播图模式、组件为何以一种方式而不是另一种方式构建。这些信息最终分散在文档、线程和人们的记忆中，当有人需要时，没有人能找到。
Luia 有两个部分：
- **MCP 服务器**，它与 Claude 连接。设计师和开发人员只需安装一次，从此 Claude 读取团队的约定，然后在做出新决定时将它们写入。
- **图形查看器**，它以空间方式呈现相同的知识，这样您可以看到决策如何连接，而不是滚动文件夹树。
两者都读取相同的纯 Markdown 文件夹。没有数据库，没有后端，也没有需要注册的服务，这意味着团队通过将该文件夹放入 git 中共享其知识。
## 安装 MCP 服务器
需要 [Node.js](https://nodejs.org) 20.19+ 或 22.12+。
```bash
git clone https://github.com/gustavocambareri/Luia_MCP.git
cd Luia_MCP
npm install
```
指向 Claude。`LUIA_KNOWLEDGE_DIR` 是团队的 Markdown 文件夹，可以放在任何地方：
```bash
claude mcp add luia --scope user \
--env LUIA_KNOWLEDGE_DIR="$HOME/luia-knowledge" \
-- node "$PWD/server/index.mjs"
```
验证它是否连接：
```bash
claude mcp list # luia: … - ✔ Connected
```
对于 Claude Desktop，请在 `claude_desktop_config.json` 中添加相同的内容：
```json
{
"mcpServers": {
"luia": {
"command": "node",
"args": ["/absolute/path/to/luia/server/index.mjs"],
"env": { "LUIA_KNOWLEDGE_DIR": "/absolute/path/to/your-knowledge" }
}
}
}
```
这就是整个设置过程。询问 Claude *"我们的间距规则是什么？"*，它会在回答之前搜索存储库。
### Claude 可以用它做什么
| 工具 | 当 Claude 需要时 |
| --- | --- |
| `search_knowledge` | 在回答有关团队如何设计或构建的问题之前 - 以便答案与您已经做出的决策相符 |
| `get_document` | 当搜索摘要看起来相关并且它需要完整规则时 |
| `record_decision` | 当您确定约定时，以便它在会话中存活下来 |
| `list_documents` | 查看团队已写下的所有内容 |
最重要的两个是 **搜索** 和 **记录**。搜索被描述为 Claude 在设计工作开始时调用它 - 没有人记得询问他们自己的约定。记录是一次调用，没有任何仪式，因为有摩擦的捕获步骤是不会发生的捕获步骤。
### 与团队一起使用
知识库是一个 Markdown 文件夹，因此共享它只是 git：
```bash
cd ~/luia-knowledge
git init && git add . && git commit -m "团队知识"
git remote add origin git@github.com:your-team/design-knowledge.git
git push -u origin main
```
团队成员克隆该存储库，并将他们自己的 `LUIA_KNOWLEDGE_DIR` 指向它。拉取以获取每个人的决策；推送以分享您自己的决策。决策以可读的差异形式出现，您可以像其他更改一样审查它们。
每个文档都是带有前置信息的纯 Markdown - 可手动编辑，无需工具：
```markdown
---
title: 间距系统
project: atlas # 可选；省略团队范围内的知识
author: your-name # 或 'team' 表示集体所有决策
tags: [spacing, layout]
created: 2026-03-09
---
8px 基本单位，4px 步长用于紧密 UI。
**原因：** 间隙比率比绝对值更有意义。
```
> [!TIP]
> 始终写 **原因**。没有理由的决策是团队在六周内重新审视的决策 - 而理由正是 Claude 将规则正确应用于您无法预料的情况的原因。
## 图形查看器
- **空间导航** - 一个 3D 力导向图，您可以平移、缩放和探索，具有手动合成的位置，以便布局有意呈现，而不是像毛球一样。
- **四种过滤方式** - 按范围、项目、作者或自由文本搜索标题、标签、描述和章节标题。
- **作者镜头** - 调暗除一个人贡献之外的所有内容，以查看谁拥有哪些知识，以及哪里形成了单点故障。
- **类型关系** - `foundation`、`reference` 和 `sibling` 边以不同的方式绘制，以便两个文档的关系一目了然。
- **可读内容** - 每个节点都带有完整的 Markdown、描述和章节大纲；单击任何节点以在图形中阅读它。
### 运行查看器
```bash
npm run dev
```
打开 Vite 打印的地址（通常为 `http://localhost:5173`），演示图立即加载。
```bash
npm run build # 生产构建到 dist/
npm run preview # 在本地提供该构建
npm run lint # eslint
```
> [!NOTE]
> 捆绑的图形 **完全是虚构的**。Meridian、Lumen、Atlas、Cadence、Harbor 和 Verso 是虚构的项目，每个项目中提到的所有人员也是虚构的。这里没有任何真实的客户端工作。
### 查看器数据格式
查看器读取 `src/data/graph-data.json`。用您自己的数据替换它，应用程序就是您的。
一个节点如下所示：
```json
{
"id": "projects/atlas/block-library",
"name": "Atlas — 区块库",
"slug": "block-library",
"scope": "project",
"project": "atlas",
"author": "your-name",
"tags": ["atlas", "blocks", "templates"],
"created": "Mon Mar 16 2026 01:00:00 GM",
"fileSize": 8200,
"description": "用于 Atlas 改版的可重用区块和页面模板。",
"body": "# Atlas — 区块库\n\n## 导航\n\n粘性头部…",
"sections": ["Atlas — 区块库", "导航"],
"connections": ["_team/design-system-patterns"]
}
```
一条边连接两个节点：
```json
{
"source": "_team/design-system-patterns",
"target": "projects/atlas/block-library",
"type": "reference",
"label": "informs",
"description": "团队模式在 Atlas 区块库中应用。"
}
```
完整形状在 [`src/lib/types.ts`](src/lib/types.ts) 中定义。
### 值得了解的字段
| 字段 | 它做什么 |
| --- | --- |
| `scope` | `team` 表示共享知识，`project` 表示项目工作。驱动颜色和分组。 |
| `project` | 当 `scope` 为 `project` 时必填。自动成为筛选芯片。 |
| `author` | 驱动作者镜头。使用 `team` 表示集体所有文档。 |
| `fileSize` | 控制节点半径。将您的值调整到大约 `2600–19500`，以保持尺寸差异。 |
| `body` | Markdown，在详细面板中渲染。 |
| `sections` | 标题列表，包含在搜索中。 |
| `type` | 边权重和曲率：`foundation` 跨越中心，`sibling` 紧贴周边。 |
### 添加项目
1. 将您的节点添加到 `graph-data.json`，并附上新的 `project` 值。
2. 在 [`src/lib/colors.ts`](src/lib/colors.ts) → `PROJECT_COLORS` 中为其添加颜色。如果没有颜色，它将默认为默认墨水色，与团队节点无法区分。
3. 可选地，在 [`src/components/graph3d/useForceLayout.ts`](src/components/graph3d/useForceLayout.ts) 中将节点放置在 `MANUAL_POSITIONS` 中。没有坐标的节点将自动定位，但手动放置节点可保持集群清晰。
筛选芯片直接从您的数据中读取项目列表，因此步骤 1 足以使其出现在 UI 中。
> [!TIP]
> 保持 `id` 值类似路径（`projects/<project>/<slug>`）。没有强制执行，但它保持文件可浏览，并使 `connections` 容易手写。
## 设计决策
在扩展它之前，有几个选择是刻意的，值得了解：
- **位置是作者定义的，而不是模拟的。** 纯粹的力布局在每次加载时都会漂移并埋葬结构。坐标位于 `useForceLayout.ts` 中，因此构图是稳定且有意的。
- **颜色是一种系统，而不是装饰。** `colors.ts` 中的每个色调都源自五色调色板，并调整为窄对比度带，因此没有项目比其他项目在视觉上更重。
- **大写标题，明确权重。** 类型规则在整个画布和面板中一致应用；如果您添加 UI，请显式设置 `fontWeight`，而不是继承它。
## 项目结构
```
server/ # MCP 服务器
├── index.mjs # 工具定义 + stdio 传输
└── knowledge.mjs # Markdown 存储：读取、写入、搜索
src/ # 图形查看器
├── data/graph-data.json # 演示内容 - 用您自己的内容替换
├── lib/
│ ├── types.ts # GraphNode、GraphEdge、GraphData
│ └── colors.ts # 调色板、范围/项目/作者颜色映射
├── hooks/useGraphData.ts # 过滤、搜索、选择状态
└── components/
├── FilterBar.tsx # 范围/项目/作者过滤器、搜索
├── DecisionLog.tsx # 每个节点的详细面板
└── graph3d/ # 3D 场景
├── useForceLayout.ts # 手动放置节点坐标
├── GraphNode3D.tsx # 节点 + 标签渲染
└── GraphEdge3D.tsx # 类型化、弯曲边
```
## 技术栈
[React 19](https://react.dev) · [TypeScript](https://www.typescriptlang.org) ·
[Vite](https://vite.dev) · [Three.js](https://threejs.org) 通过
[React Three Fiber](https://r3f.docs.pmnd.rs) ·
[Tailwind CSS](https://tailwindcss.com)
