# obsidian_project

**Repository Path**: yeyuting-shenone/obsidian_project

## Basic Information

- **Project Name**: obsidian_project
- **Description**: 用于项目管理与进度跟踪的 Obsidian 插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Obsidian Projects（Obsidian 项目管理插件）

**Obsidian Projects** 是一款为 Obsidian 打造的本地项目管理与甘特图（Gantt Chart）插件。插件基于 [dhtmlx-gantt](https://dhtmlx.com/docs/products/dhtmlxGantt/) 深度定制，支持树形层级任务（WBS）、自动进度汇总与自动排程、灵活的工作日/节假日配置，以及 Excel / Microsoft Project XML（MSPDI）/ HTML 等多种导入导出能力，帮助你在 Obsidian 里获得接近 Microsoft Project 的专业体验。

> 说明：本仓库 README 已合并并扩展《Obsidian Projects 插件使用手册》内容，方便在一个入口完成安装、上手与功能查阅。

---

## 目录

- [核心特性](#核心特性)
- [下载与安装](#下载与安装)
- [快速入门](#快速入门)
- [核心功能使用指南](#核心功能使用指南)
- [插件设置（Settings）](#插件设置settings)
- [快捷键与常用操作](#快捷键与常用操作)
- [导入与导出说明](#导入与导出说明)
- [历史版本与回滚](#历史版本与回滚)
- [常见问题（FAQ）](#常见问题faq)
- [本地开发](#本地开发)
- [贡献](#贡献)

---

## 核心特性

- **交互式甘特图引擎**
  - 拖拽调整任务周期（时长）、拖动更改进度、拖拽创建任务依赖连线（Finish-to-Start 等）。
  - 自动排程（Auto-scheduling）：当依赖/父子任务发生变化时，相关任务将自动顺延与重新计算。
  - 左侧任务列表分栏支持宽度拖拽与一键收起/展开，适配不同屏幕尺寸。
- **树形任务结构与 WBS**
  - 无限层级任务嵌套（父任务/子任务），自动生成并显示 WBS 序号（如 1.1.1）。
  - 父任务进度由子任务进度按权重自动汇总计算，避免“越权”手动修改导致数据失真。
- **本地历史版本管理与撤销/重做**
  - 自动保留操作历史（默认 50 份，可配置），每份带操作描述与时间戳的 JSON 备份。
  - 可视化历史版本面板，支持预览并一键无损回滚到任意节点（并自动清理后续脏数据）。
  - 支持原生撤销/重做快捷键：`Cmd/Ctrl + Z`、`Cmd+Shift+Z / Ctrl+Y`。
- **高性能搜索与过滤**
  - 支持按任务名称或负责人全局搜索；命中后自动展开父级路径，保持树形结构可读。
- **灵活的工作日与节假日系统（中国本土化）**
  - 内置 5 天双休、6 天单休、大小周等工作日模式。
  - 提供可视化日历弹窗，可标记法定节假日与调休补班。
- **导入与导出**
  - Excel 导入（提供标准模板），支持 WBS、负责人、进度、依赖等复杂关系。
  - Project XML（MSPDI .xml）导入/导出：与 Microsoft Project 离线互通（当前覆盖任务/层级/依赖）。
  - HTML 脱机预览：一键导出可交互的 HTML 页面，便于分享给未安装 Obsidian 的同事查看进度。
- **深色模式原生适配**
  - 兼容 Obsidian Light / Dark 主题，随系统无缝切换。

---

## 下载与安装

由于本插件可能尚未上架 Obsidian 官方社区商店，请使用手动方式安装。

### 1) 获取插件文件

你需要获取构建后的插件运行文件，通常至少包含：

- `main.js`（核心代码）
- `manifest.json`（插件配置）
- `styles.css` / `custom.css`（样式文件，视项目配置而定）

获取方式二选一：

1. **下载 Release**：在仓库 Release 页面下载已打包版本（推荐）。
2. **源码构建**：克隆本仓库并执行 `npm run build` 生成构建产物。

### 2) 放置到 Obsidian 插件目录

1. 打开你的 Obsidian 仓库（Vault）所在的本地文件夹。
2. 进入 `.obsidian/plugins/`（如不存在请手动创建）。
3. 在 `plugins` 下新建文件夹，例如：
   - `obsidian-projects/`（推荐）
4. 将 `main.js`、`manifest.json`、样式文件复制到该目录中。

最终路径示例：

```
你的仓库路径/.obsidian/plugins/obsidian-projects/
  ├─ main.js
  ├─ manifest.json
  └─ styles.css
```

### 3) 在 Obsidian 中启用插件

1. 打开 Obsidian → 左下角齿轮进入 **设置（Settings）**。
2. 进入 **第三方插件（Community plugins）**：
   - 关闭 **安全模式（Safe mode）**（如提示风险请确认）。
3. 在已安装插件列表中找到 **Obsidian Projects** 并开启。

---

## 快速入门

### 打开项目视图

插件启用后，可通过以下任一方式打开项目面板：

1. **侧边栏图标（Ribbon）**：点击左侧边栏 📅“打开 Obsidian Projects” 图标。
2. **命令面板**：`Cmd/Ctrl + P` → 搜索并执行 `Open Projects View`。

### 界面概览

打开视图后通常分为三块区域：

1. **顶部工具栏**：导入/导出、历史版本、搜索、视图切换（日/周）、回到今天等。
2. **左侧任务表格**：WBS、名称、负责人、起止时间、时长、进度等字段；支持拖拽列宽与收起/展开。
3. **右侧甘特图**：时间轴与任务条展示；支持今天高亮线、周末/节假日灰色背景等。

---

## 核心功能使用指南

### 1) 任务管理与编辑

- **创建任务**
  - 空白项目：点击界面提示的“+ 创建新任务”。
  - 已有任务：在左侧表格末尾点击 `+` 新增任务。
- **编辑任务详情**
  - 在右侧甘特图 **双击任务条** 打开任务编辑面板。
  - 你可以按“持续时间”自动计算结束时间，或切换到“手动选择结束时间”进行精确控制。
- **修改进度**
  - 在左侧表格中 **双击“进度”** 单元格输入 0~100。
  - 注意：**父任务进度由子任务自动汇总**，通常不可直接手动修改。

### 2) 拖拽排期与任务依赖连线

- **调整时长**：拖拽任务条左右边缘，缩短/延长任务周期。
- **移动任务**：拖拽任务条中间区域，整体平移排期。
- **建立依赖关系**
  - 鼠标悬停任务条两端出现圆点，拖拽圆点到另一任务条起点/终点以建立依赖（如 Finish-to-Start）。
  - 当前置任务变化时，后置任务会自动顺延（自动排程）。

### 3) 工作日与节假日配置

为保证“持续时间/自动排程”更符合真实工作节奏，可在设置中配置工作日模式与法定节假日/调休：

1. Obsidian → 设置 → 第三方插件 → **Obsidian Projects**
2. 配置：
   - 工作日模式：5 天双休 / 6 天单休 / 大小周
   - 节假日与调休：打开可视化日历，点击日期标记
     - 红色：法定节假日（休息）
     - 绿色：调休补班（上班）

### 4) 搜索与定位

- 使用顶部搜索框按 **任务名称** 或 **负责人** 搜索。
- 命中时会自动展开父级路径，便于在树形结构中定位。

---

## 插件设置（Settings）

在 Obsidian 设置面板中，你可以按需调整：

- **数据文件路径**：甘特图数据存放的本地 JSON 文件路径（默认可能为仓库根目录下的 `obsidian_projects_data.json`，以实际设置项为准）。
- **工作日模式**：`5days`（双休）、`6days`（单休）或 `big_small_weeks`（大小周）。
- **大小周规则**：配置“单周休息/双周上班”或反之。
- **节假日与调休配置**：打开可视化日历，点选日期进行标记。
- **最大历史版本数**：历史版本面板中最多保留的版本数量（默认 50，可配置）。

---

## 快捷键与常用操作

- **撤销（Undo）**：`Ctrl + Z` / `Cmd + Z`
- **重做（Redo）**：`Ctrl + Y` / `Cmd + Shift + Z`
- **编辑进度**：左侧表格 **双击“进度”** 单元格直接输入百分比
- **任务详情**：右侧甘特图 **双击任务条** 打开详情面板
- **连线依赖**：拖拽任务条两端圆点连接到目标任务

---

## 导入与导出说明

顶部工具栏提供导入/导出能力（具体按钮名称以界面为准）：

- **导入**
  - Excel：下载标准模板 → 填写后导入（支持 WBS、负责人、进度、依赖等）。
  - Project XML（MSPDI .xml）：离线导入 Microsoft Project 的 XML 文件（当前覆盖任务/层级/依赖）。
- **导出**
  - HTML 脱机预览：导出独立可交互的 HTML 文件，适合对外分享与汇报。
    - 常见文件名格式示例：`你的仓库名_Preview_YYYYMMDD.html`
  - Excel / Project XML：将当前任务与依赖导出为 Excel 或 MSPDI .xml（覆盖范围同上）。

---

## 历史版本与回滚

插件会自动保存操作快照（默认保留最近 50 份）：

- **撤销/重做**：可用系统级快捷键对拖拽/修改进行回退。
- **历史版本面板**：查看每次操作记录与时间戳；如误操作，可选择某个版本点击“恢复到此版本”进行无损回滚。

---

## 常见问题（FAQ）

**Q：为什么我修改了子任务的时间，父任务的时间自己变了？**  
A：这是自动排程逻辑。父任务作为“容器”，其开始/结束时间会自动对齐其下属最早开始与最晚结束的子任务。

**Q：左侧任务列表太宽，遮挡甘特图怎么办？**  
A：拖拽表格与甘特图之间的分割线调整宽度；或点击分割线中间的 `◀/▶` 按钮收起/展开左侧区域。

**Q：导出的 HTML 文件名是什么格式？**  
A：通常会带上导出日期（例如 `VaultName_Preview_20240520.html`），便于版本管理与存档。

---

## 本地开发

```bash
# 1. 安装依赖
npm install

# 2. 编译并开启热重载
npm run dev

# 3. 构建生产版本
npm run build
```

---

## 贡献

欢迎提交 Issue / PR 来改进功能、修复问题或补充文档：

1. Fork 本仓库并创建分支
2. 提交改动并确保构建通过
3. 发起 Pull Request，并在描述中说明变更原因与使用方式