WorkGraph

WorkGraph 对用户选定的工作区建立索引，而不会移动或上传其中的文件。它构建一个分层的 Portfolio -> Area -> Project -> Artifact 图谱，通过本地浏览器、CLI 和只读 MCP 服务器对外提供访问，并可选择生成 Obsidian 导航层。

它最初是一个个人 vibe-coding 工具，用于在大型混合研究与工程工作区中导航。公开版本移除了特定机器的假设，同时保留了原版工具中真正有用的工作流：快速的跨项目发现、明确的来源追溯，以及源文件、可重建索引和精选记忆之间的严格分离。

功能特性

• 逐层下钻地图： 从整个组合视图下钻到领域、项目、文档、概念、工具或工作流。

• 本地搜索： 基于 SQLite FTS 对项目元数据和选定的文本文件进行搜索。

• 可解释的链接： 区分显式路径引用与低置信度的共享概念建议。

• 只读 MCP： 让 Codex、Kimi、Reasonix 或其他 MCP 客户端查询项目上下文和可复用的既有工作成果。

• 可选的 Obsidian 层： 在不复制工作区的前提下生成导航页面、概念索引、记忆镜像和 Canvas。

• 隐私控制： 将整个顶层领域标记为仅元数据，并从被索引的文本中隐去常见的凭据模式。

• 无托管服务： Web UI 仅绑定回环地址并使用内置的前端资源；运行时索引不需要网络或模型 API。

Related MCP server: code-graph

快速开始

Windows 安装程序

从 Releases 下载最新的源码压缩包，解压后运行：

.\scripts\Install-WorkGraph.ps1 -WorkRoot "D:\MyWorkspace" -Start

可选集成是显式进行的：

.\scripts\Install-WorkGraph.ps1 `
  -WorkRoot "D:\MyWorkspace" `
  -ObsidianVault "$HOME\Documents\My Vault" `
  -SensitiveArea Personal,Finance `
  -ConfigureClients `
  -Start

安装程序会创建项目本地的 .venv，写入 config/workgraph.json，构建首个索引，并可选择注册 MCP 服务器。修改前会先备份已有的客户端文件。

手动安装

uv venv .venv
uv pip install --python .\.venv\Scripts\python.exe -e .
.\.venv\Scripts\python.exe -m workgraph.cli init --work-root "D:\MyWorkspace"
.\.venv\Scripts\python.exe -m workgraph.cli refresh
.\.venv\Scripts\python.exe -m workgraph.cli serve

打开 http://127.0.0.1:8765/。在 macOS 或 Linux 上，使用 .venv/bin/python 配合相同的模块命令。

工作区模型

默认约定将第一级目录视为领域，第二级视为项目：

MyWorkspace/
├── Research/
│   ├── ClimateModel/
│   └── KnowledgeGraph/
├── Engineering/
│   ├── RobotArm/
│   └── CFDStudy/
└── Writing/
    └── OpenSourceGuide/

更深或混合的布局可以通过 project_layout.area_depths 和 project_layout.group_depths 来描述。参见 config/workgraph.example.json 和合成的 examples/demo-workspace。

日常命令

.\scripts\Refresh-WorkGraph.ps1
.\scripts\Start-WorkGraph.ps1 -Open
.\scripts\Status-WorkGraph.ps1
.\scripts\Stop-WorkGraph.ps1

.\.venv\Scripts\python.exe -m workgraph.cli search "finite element OCR"
.\.venv\Scripts\python.exe -m workgraph.cli context "ClimateModel"
.\.venv\Scripts\python.exe -m workgraph.cli related "KnowledgeGraph"
.\.venv\Scripts\python.exe -m workgraph.cli reuse "document rendering"

MCP 工具

work_map、project_context、related_projects、find_reuse、work_search 和 graph_stats 均为只读。自动注册目前面向 Windows 上的 Codex、Kimi Code/Kimi Work 和 Reasonix：

.\.venv\Scripts\python.exe -m workgraph.cli configure-clients

对于其他客户端，请注册以下 stdio 命令：

<absolute path to python> -m workgraph.mcp --config <absolute path to workgraph.json>

信任边界

• 工作区始终是事实来源；WorkGraph 从不移动或删除源文件。

• SQLite 数据库和生成的 Obsidian 页面是可丢弃的索引。

• 敏感领域仅暴露文件名和聚合元数据，其内容不会被索引。

• 生成的文件夹（如 .git、.venv、node_modules 和构建缓存）会被排除在语义分析之外。

• 二进制办公文件、PDF、模型和媒体文件在 v0.1 中仅作为元数据处理。

• related_to 边是发现提示，而非证据。在依赖某个结论之前，请先追溯源路径。

在对机密材料建立索引之前，请阅读完整的隐私模型。

开发

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m compileall -q src tests

WorkGraph 仅依赖运行时标准库。Cytoscape.js 和 Lucide 为离线 UI 内置，其声明见 THIRD_PARTY_NOTICES.md。

开发是人工主导、AI 辅助的。维护者负责架构决策、隐私边界、验证、发布以及所有被接受的变更；生成的代码与任何其他贡献一样接受相同的审查和测试要求。

欢迎通过聚焦的 issue 和 pull request 参与贡献。参见 CONTRIBUTING.md、SECURITY.md 和路线图。

许可证

Apache License 2.0。参见 LICENSE。