# damocles

**Repository Path**: chldu/damocles

## Basic Information

- **Project Name**: damocles
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Damocles

本地单人任务看板：按周期管理待办，支持项目归类、附件与回收站。双击便携包即可后台运行，浏览器打开本地网页使用。

## 功能

- **看板**：四列工作流（待办 / 进行中 / 待验收 / 已关闭），可按项目或优先级划分泳道；拖拽或 `Alt+←/→` 流转，抽屉内编辑与附件
- **上帝视图**：跨周期筛选、分组、批量操作与回收站
- **周期 / 项目**：手动创建周期（周日起点），系统 Backlog；项目可归档
- **设置**：端口、主题、备份 / 导出导入 JSON、打开数据目录、退出服务
- **便携运行**：单文件 `damocles.exe`，数据落在同目录 `data/`，托盘打开页面或退出

## 界面预览

| 看板 | 上帝视图 | 设置 |
| --- | --- | --- |
| ![看板](docs/screenshots/board.png) | ![上帝视图](docs/screenshots/overview.png) | ![设置](docs/screenshots/settings.png) |

## 下载与使用

1. 下载或本地生成 `damocles-portable-vX.Y.Z.zip`（本地：`pnpm package` → `build/`）
2. 解压到任意目录，双击 `damocles.exe`
3. 浏览器会打开 `http://127.0.0.1:7377`（端口被占用时自动顺延）
4. 托盘图标可再次打开页面或退出；也可在设置页点击「退出服务」

常用参数：

```text
damocles.exe --port 7377 --data-dir D:\path\to\data
damocles.exe --foreground --no-tray --no-open --verbose
damocles.exe --help
```

### 从源码开发

要求：Node.js ≥ 24.14、pnpm 10。

```bash
pnpm install
pnpm dev          # 前端 + API
pnpm verify       # typecheck + unit + lint + e2e
pnpm package      # Windows：产出 build/damocles.exe 与版本化 zip
```

## 数据目录

默认位于 **exe 同级的 `data/`**（可用 `--data-dir` 覆盖）：

```text
data/
  damocles.db          SQLite 主库
  attachments/         任务附件（按任务隔离）
  backups/             启动自动备份，保留最近 5 份
  logs/                运行日志
  damocles.lock        单实例锁（pid + port）
```

整目录复制即可迁移到另一台机器；导入 JSON 前会自动再做一次备份。

## 版本号策略

采用 [SemVer](https://semver.org/)：`MAJOR.MINOR.PATCH`。

| 来源 | 用途 |
| --- | --- |
| `packages/shared` 的 `APP_VERSION` | 运行时 `/api/health`、设置页「关于」、CLI `--version` |
| 根目录 `package.json` 的 `version` | 与 `APP_VERSION` **必须一致**；打包脚本据此命名产物 |
| Git tag `vX.Y.Z` | 发布标记，与上述版本一致 |
| `build/damocles-portable-vX.Y.Z.zip` | 便携分发产物 |

- **MAJOR**：不兼容的数据模型或 API 变更
- **MINOR**：向后兼容的功能
- **PATCH**：缺陷修复与文档

发版清单：对齐版本号 → 更新 `CHANGELOG.md` → `pnpm verify` → `pnpm package` → 提交 → `git tag vX.Y.Z`。

## 常见问题

### Windows SmartScreen / 杀毒提示

当前构建未做代码签名。若提示「已阻止」：选 **更多信息 → 仍要运行**。也可将解压目录加入杀毒软件排除列表。

### 端口被占用

默认 `7377`。若被占用，服务会向后探测最多 10 个端口，实际地址写在 `data/damocles.lock` 与日志中。可用 `--port` 指定；设置页也可改端口（需重启服务）。

### 如何备份 / 迁移

- **整目录**：退出服务后复制整个 `data/` 文件夹
- **设置页**：立即备份、导出 JSON；导入支持 `merge` / `replace`（导入前自动备份）
- 迁移到新机器：解压同版本 portable → 用旧 `data/` 覆盖新目录下的 `data/` → 启动

### 已经有一个实例在跑

单实例锁生效时，再次启动会打开已有实例的浏览器页面并退出（退出码 0）。若进程残留可删 `data/damocles.lock` 后重试，或先托盘退出。

### 界面打不开

用 `damocles.exe --foreground --no-tray --verbose` 看控制台日志；确认防火墙未拦本机回环；检查 `data/logs/`。

## 技术说明

SvelteKit（`adapter-static` SPA）+ Hono + Node 内置 `node:sqlite`，Windows 上经 Node SEA 打成单文件。UI 样式基于 [ak-ui](https://ak-ui.yyj.moe/guide/) CSS（非官方项目，与鹰角网络无关）。

规格与里程碑见 `docs/damocles-spec.md`、`docs/damocles-implementation-plan.md`。

## 许可

见仓库内许可证文件（若有）；ak-ui 按其上游许可使用。