# workboard-studio

**Repository Path**: marching-ants_admin_admin/workboard-studio

## Basic Information

- **Project Name**: workboard-studio
- **Description**: 本地优先的 macOS / Windows 工作看板：任务看板、工时排期、灵感库、日常节奏与 AI 复盘。


- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 工作看板 · WorkBoard

**本地优先的桌面工作看板，把任务、排期、灵感和日常节奏放在同一个界面里。**

![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-000000)
[![Swift](https://img.shields.io/badge/Swift-5.9%2B-F05138?logo=swift&logoColor=white)](https://swift.org/)
![Version](https://img.shields.io/badge/version-1.0.0-blue)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)

A local-first work dashboard for macOS and Windows. No account, no cloud dependency — your data stays on your machine.

![工作看板总览](screenshots/dashboard-ai.png)

## 目录

- [简介](#简介)
- [功能特性](#功能特性)
- [界面预览](#界面预览)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [打包与发布](#打包与发布)
- [使用说明](#使用说明)
- [AI 配置](#ai-配置)
- [数据与备份](#数据与备份)
- [项目结构](#项目结构)
- [开发与测试](#开发与测试)
- [设计取舍](#设计取舍)
- [贡献](#贡献)
- [许可证](#许可证)

## 简介

工作看板是一个面向程序员、独立开发者和居家办公者的 Mac 桌面工具。

它解决的不是「记更多待办」，而是三个更具体的问题：

- 手头的事情现在到哪一步了？
- 按我的时间安排，每件事大概什么时候能做完？
- 工作、健身、内容创作和休息，能不能放进同一天？

界面使用原生 WebView 承载，外壳是 Swift + AppKit；数据保存为本地 JSON，不登录、不上传。

## 功能特性

### 看板

- 待办 / 进行中 / 阻塞 / 已完成四列看板
- 卡片拖拽切换状态
- 按优先级、风险、标签筛选
- 任务抽屉：预估工时、已投入、进度、截止日期、标签、描述和检查清单

### 排期与工时预测

- 按优先级和截止日期自动排序
- 根据每日可用工时，推算每个任务的预计完成时间
- 计算整体清空日期
- 展示未来 14 天的每日需求与超载风险
- 识别超期、临期和容量缺口

### 灵感库

- 程序员的点子和 side project 单独管理
- 灵感阶段：火花 / 调研 / 进行中 / 已发布
- 想法可一键转成任务，进入正式看板

### 日常节奏

- 把深度工作、健身、内容创作、复盘和睡眠排进一天
- 支持自定义作息、恢复推荐模板
- 习惯打卡：健身、小红书、公众号、深度工作
- 内容发布节奏与每周目标

### 节奏提醒

- 到点原生弹窗提醒
- 可选 macOS 中文语音播报
- 支持提前量、免打扰时段、语速和音量
- 每个时段可单独开关提醒

### AI 洞察

- 支持本地 Ollama 与 OpenAI 兼容接口
- 每天定时读取看板、作息和习惯，生成日报
- 输出风险预警、整体节奏评分和明日重点
- AI 完全可选，不启用也能使用全部基础功能

## 界面预览

| 看板 | 排期 |
| --- | --- |
| ![看板](screenshots/board.png) | ![排期](screenshots/schedule.png) |

| 日常节奏 | 灵感库 |
| --- | --- |
| ![日常节奏](screenshots/rhythm.png) | ![灵感库](screenshots/ideas.png) |

| AI 日报 | 总览 |
| --- | --- |
| ![AI 日报](screenshots/ai-report.png) | ![总览](screenshots/dashboard-ai.png) |

> 截图均使用 demo 数据。

## 技术栈

| 层 | 技术 |
| --- | --- |
| 桌面外壳 | Swift + AppKit |
| Web 容器 | WKWebView |
| 界面 | HTML / CSS / 原生 JavaScript（无构建步骤） |
| 数据存储 | 本地 JSON + 原子写入 + 自动备份 |
| AI | Ollama / OpenAI 兼容 API |
| 原生能力 | 文件面板、系统语音、菜单栏、通知式浮窗 |

架构非常简单：

```text
Web UI (HTML/CSS/JS)
        │  WKScriptMessageHandler
        ▼
Swift / AppKit 外壳
        │
        ▼
~/Library/Application Support/WorkBoardOpen/data.json
```

## 快速开始

### 环境要求

- macOS 13 或更高版本
- Xcode Command Line Tools
- 可选：Python 3（仅用于运行自测脚本）

```bash
xcode-select --install
```

### 构建

```bash
git clone <your-repo-url> workboard
cd workboard

chmod +x build.sh tools/*.sh
./build.sh

open "dist/工作看板.app"
```

构建脚本会完成：

1. 使用 `swiftc` 编译 Swift 外壳
2. 打包 `src/web` 静态资源
3. 生成 `.app` 结构
4. 执行 ad-hoc 签名
5. 输出到 `dist/`

### 安装提示

App 使用 ad-hoc 签名。复制到其他 Mac 后，如果被 Gatekeeper 拦截，可以右键选择「打开」，或执行：

```bash
xattr -dr com.apple.quarantine "/Applications/工作看板.app"
```

## 打包与发布

### macOS

当前 macOS 版使用现有的 Swift + WKWebView 外壳打包：

```bash
./build.sh
```

产物：

```text
dist/工作看板.app
```

生成可分发的 ZIP：

```bash
cd dist
ditto -c -k --sequesterRsrc --keepParent \
  "工作看板.app" \
  "工作看板-1.0.0-macOS.zip"
```

### 拖拽安装 DMG

生成带「拖到 Applications」安装界面的 DMG：

```bash
./tools/package-dmg.sh
```

如果还没有构建 App，可以一步完成：

```bash
./tools/package-dmg.sh --build
```

产物：

```text
dist/工作看板-1.0.0-macOS.dmg
```

DMG 打开后包含：

- `工作看板.app`
- `Applications` 快捷方式
- 可选的安装背景

用户把 App 拖进 Applications 即可完成安装。

脚本默认使用普通拖拽布局。如果希望额外写入背景图和图标位置，可以尝试：

```bash
./tools/package-dmg.sh --style
```

> `--style` 需要 macOS 的 Finder 自动化权限；如果系统不允许，脚本会自动退回普通拖拽布局，不影响安装。
>
> DMG 是磁盘镜像 + 拖拽安装，不是向导式安装器。如果需要「下一步 / 安装」向导，应使用 `.pkg`（`pkgbuild` + `productbuild`）。

App 使用 ad-hoc 签名。对外分发时，建议使用 Apple Developer 证书完成签名和公证，避免 Gatekeeper 拦截。

### Windows（Electron）

Windows 版使用 Electron + electron-builder，工程位于 `windows-electron/`。

构建环境：

- Node.js 20+
- npm
- 不需要 Visual Studio、Rust 或 WebView2（Electron 自带 Chromium）

在 macOS 或 Windows 上都可以构建 Windows 安装包：

```bash
cd windows-electron
npm install
npm run dist:win
```

> 如果项目放在 exFAT 移动硬盘上，Electron 依赖里的 framework symlink 可能无法解压；建议把 `windows-electron/` 复制到内置 APFS 磁盘（或临时目录）再执行 `npm install`。

产物：

```text
windows-electron/dist/工作看板-Setup-1.0.0.exe
```

本地已生成安装包：

```text
dist/工作看板-Setup-1.0.0.exe
```

如果需要先在本机调试 Electron 界面：

```bash
cd windows-electron
npm start
```

构建时会自动把 `src/web` 的静态资源同步到 `windows-electron/web`，并使用 `build/icon.ico` 作为 Windows 图标。

Windows 数据目录：

```text
%APPDATA%\工作看板\data.json
```

未做代码签名的安装包可能触发 SmartScreen「未知发布者」；正式发布建议使用代码签名证书。

### 跨平台版本号

发布前请同步以下位置：

- `windows-electron/package.json`
- `src/native/Info.plist`
- `src/web/js/core.js` 中的 `WB.VERSION`

建议统一使用 `MAJOR.MINOR.PATCH` 版本号，并在同一个发布版本中放入 macOS / Windows 产物。

### 签名说明

- macOS：ad-hoc 签名可直接本地使用；对外分发建议使用 Developer ID 签名并公证。
- Windows：未签名的安装包可能触发 SmartScreen「未知发布者」；正式发布可购买代码签名证书。

## 使用说明

打开 App 后，顶部有五个主视图：

| 视图 | 用途 |
| --- | --- |
| 总览 | 查看整体进度、工作量、负荷和 AI 洞察 |
| 看板 | 管理任务状态和优先级 |
| 排期 | 查看每个任务的预计完成时间和整体节奏 |
| 灵感 | 收集、推进和转化点子 |
| 日常 | 管理作息、习惯和内容发布 |

常用快捷键：

| 快捷键 | 功能 |
| --- | --- |
| `⌘N` | 新建任务 |
| `⌘F` | 聚焦搜索 |
| `⌘1` – `⌘5` | 切换视图 |
| `⇧⌘A` | 打开 AI 洞察 |
| `⇧⌘E` | 导出数据 |
| `⇧⌘I` | 导入数据 |
| `⇧⌘D` | 切换外观 |

## AI 配置

AI 功能是可选的。默认使用本机 Ollama：

```bash
# 安装 Ollama 后，拉取一个中文能力较好的模型
ollama pull qwen2.5:7b

# 启动服务
ollama serve
```

在「设置 → AI 设置」中确认：

- Provider：Ollama
- Endpoint：`http://127.0.0.1:11434`
- Model：`qwen2.5:7b`

也可以切换到任意 OpenAI 兼容接口，填写 Endpoint、模型名和 API Key。API Key 只保存在本机 JSON 数据中。

> 生成一份日报通常需要几十秒到几分钟，取决于本机模型和硬件。

## 数据与备份

macOS 数据目录：

```text
~/Library/Application Support/WorkBoardOpen/
├── data.json
└── data.backup.json
```

Windows Electron 数据目录：

```text
%APPDATA%\工作看板\
├── data.json
└── data.backup.json
```

- 每次保存都会先写临时文件，再原子替换
- 启动时自动备份上一份数据
- 设置中支持导出 / 导入 JSON
- 也可以通过环境变量指定数据文件，方便开发和测试：

```bash
WORKBOARD_DATA=/tmp/workboard-dev.json ./dist/工作看板.app/Contents/MacOS/WorkBoard
```

## 项目结构

```text
.
├── build.sh                    # 构建脚本
├── src/
│   ├── native/
│   │   ├── main.swift          # AppKit 外壳、菜单、存储桥、AI 请求、语音、节奏弹窗
│   │   └── Info.plist
│   └── web/
│       ├── index.html
│       ├── styles.css
│       └── js/
│           ├── core.js         # 数据模型、排期、预测、统计、存储桥
│           ├── ai.js           # 上下文、提示词、报告解析、自动调度
│           ├── reminder.js     # 节奏提醒、系统语音桥
│           ├── views.js        # 页面渲染
│           ├── app.js          # 交互、拖拽、自动保存、快捷键
│           └── selftest.js     # 端到端自测
├── windows-electron/           # Windows Electron 壳
│   ├── electron/                # main / preload / IPC 桥
│   ├── scripts/sync-web.js     # 同步 Web 资源
│   └── package.json            # Electron + electron-builder 配置
├── assets/                     # 应用图标和 DMG 背景
├── tools/
│   ├── snap.sh                 # 生成界面截图
│   ├── selftest.sh             # 运行自测
│   ├── package-dmg.sh          # 生成拖拽安装 DMG
│   ├── make_dmg_background.py  # 生成 DMG 背景
│   └── make_icon.py            # 生成图标资源
├── screenshots/                # README 截图
└── LICENSE
```

## 开发与测试

修改 `src/web` 下的静态资源后，重新执行构建即可看到变化：

```bash
./build.sh
```

运行内置端到端自测：

```bash
./tools/selftest.sh
```

自测使用临时数据目录，不会修改正式数据。

当前覆盖：

- 任务创建 / 编辑 / 删除 / 拖拽状态
- 搜索、筛选、排期计算
- 灵感创建与转任务
- 习惯打卡与作息编辑
- 节奏提醒设置与免打扰逻辑
- AI 配置、JSON 解析与提示词构建

共 **62 项检查**。

## 设计取舍

- **本地优先**：数据是用户自己的 JSON 文件，不依赖账号或云服务。
- **原生外壳 + Web UI**：比 Electron 更轻，界面迭代也不需要重新编译前端。
- **AI 是建议者**：只生成分析，不自动改任务、不自动执行操作。
- **估算是估算**：完成时间基于每日容量推算，不包含会议、临时插入等扰动。
- **单机单用户**：围绕一台 Mac 上的个人工作流设计，保持简单直接。

## 贡献

欢迎提交 Issue 和 Pull Request。

```bash
# 1. Fork 并创建分支
git checkout -b feat/your-feature

# 2. 提交改动
git commit -m "feat: add your feature"

# 3. 运行自测
./tools/selftest.sh

# 4. 发起 Pull Request
```

提交前请注意：

- 不要在截图、示例数据或测试中放入真实客户信息
- 保持 Web UI 使用原生 JavaScript，不引入构建步骤
- 新功能尽量附带对应的自测检查
- 较大的改动建议先开 Issue 讨论

## 许可证

本项目使用 [MIT License](LICENSE)。

---

如果这个项目对你有帮助，欢迎点一个 Star。