内容
# OKF-Todo
> **0.1 版本 - 正在开发中**。预计会有不完整的特性以及用户界面变更。如果需要，数据库将会被迁移到最新版本。
一个开源、离线的待办事项应用，适用于开发者和支持者，基于 SQLite，支持开放知识格式（OKF）和 MCP。
[](docs/images/okf-todo-task-workspace.png)
<sub>数据由 Codex 直接创建。</sub>
## AI 优先数据
OKF-Todo 设计用于帮助 AI 编码工具将非结构化工作转换为实用的产物。给 Codex、Claude Code 或其他兼容的工具一个客户的电子邮件线程、支持记录、会议笔记、诊断输出或类似的源材料，并要求它准备一个内部任务、调查计划、客户回复、移交、状态更新或其他有用的产物。
该应用程序不依赖于 AI。它也可以作为一个传统的桌面待办事项应用，您可以完全通过用户界面创建、组织、更新和完成任务。不需要托管帐户，您的数据保留在本地。
对于 AI 辅助工作，建议的工作流程是 **草稿、审查、保存、验证**：要求工具分析源材料而不做任何更改，审查其提议，明确批准任何任务创建或更新，然后读取保存的结果。[OKF 用户指南](docs/help/okf-layer.md) 和 [MCP 用户指南](docs/help/mcp-server.md) 提供了完整的示例和可重用的提示。
AI 工具可以通过多种方式与 OKF-Todo 配合：
- **[OKF 引导访问](docs/help/okf-layer.md)：** 为工具提供关于 OKF-Todo 概念、模式、关系、完整性规则和生命周期惯例的结构化上下文。OKF 提供知识和导航；它本身不授予对任务数据或执行更新的访问权限。
- **[MCP 服务器](docs/help/mcp-server.md)：** 让兼容的工具通过结构化工具列出、读取、创建和更新任务，并检查其时间线。
- **[CLI 命令](docs/okf/todo-database/references/application-command-interface.md)：** 让人员、脚本和代理从终端执行应用程序命令。
- **直接 SQLite 访问：** 让用户、脚本或工具在具有文件访问权限的情况下直接读写本地数据库。
- **桌面界面：** 完全手动地使用每个任务管理功能，无需 AI 工具。
桌面界面、CLI 和 MCP 服务器使用相同的应用程序服务，因此它们的一致性应用验证、生命周期规则和自动任务历史记录。直接 SQLite 写入也是可能的，但它们绕过了这些服务；因此，调用者负责保持数据完整性并记录任何所需的历史记录。
[OKF](docs/help/okf-layer.md) 和 [MCP](docs/help/mcp-server.md) Markdown 指南也是离线应用程序帮助的来源。桌面版本复制并本地渲染它们，因此存储库和应用程序指导保持同步。
## 即将推出
计划中的改进：
- 根据屏幕分辨率计算初始编辑器高度。
- 可能的灵感来自 MS To Do：列表、标志和星星。
- Mac 和 Linux 的安装程序。
它设计用于处理通常在正式系统之间的工作：生产错误、支持案例、部署检查、调查、想法、笔记、请求和后续任务。该应用程序在本地运行，不需要帐户或云服务，并将任务、历史记录、图像和附件一起存储在一个 SQLite 数据库中。
## 产品亮点
- 仅需标题和任务类型即可快速捕获任务。
- 活动、紧急、等待、逾期、已完成和所有任务视图。
- 支持 HTML 和 Markdown 的富文本编辑器。
- 在任务正文中粘贴、拖放或选择图像。
- 优先级、截止日期、等待目标、标签和可选的源引用。
- 任务列表中显示进度的检查清单。
- 文件附件存储在 SQLite 数据库中。
- 任务之间的键入关系。
- 评论和自动更改历史的综合时间线。
- 可编辑的任务类型、优先级和状态。
- 浅色和深色配色方案，带有灵活的桌面布局。
- 从应用程序内完成数据库备份。
- 离线应用程序帮助，用于使用 OKF 层和可选的 MCP 服务器。
## Windows 安装程序
Windows 用户可以使用以下方法安装独立应用程序：
[OKF-Todo 0.1 Windows x64 安装程序](https://github.com/dalby-md/OKF-Todo/releases/latest/download/Okf-Todo-0.1-win-x64-setup.exe)。
安装程序包括桌面应用程序和 OKF 上下文层。安装 MCP 服务器作为用户选择提供，默认情况下已选中。
**您不需要成为本地管理员即可安装此程序。**
## 截图
[浏览 OKF-Todo 截图库](docs/images/promotional/README.md)，查看工作区、任务工作流、离线帮助、首选项、备份和暗色模式。所有截图都使用虚构的演示数据。
# IT 专业人员部分
### 数据库文件
数据库存储在操作系统的本地应用程序数据目录下：
| 平台 | 典型数据库路径 |
| --- | --- |
| Windows | `%LOCALAPPDATA%\Okf-Todo\okf-todo.db` |
| macOS | `~/Library/Application Support/Okf-Todo/okf-todo.db` |
| Linux | `$XDG_DATA_HOME/Okf-Todo/okf-todo.db`，或当 `XDG_DATA_HOME` 未设置或相对时为 `~/.local/share/Okf-Todo/okf-todo.db` |
除非您故意要删除所有应用程序数据，否则请勿删除此文件。
### 需求
当前 alpha 版本从源代码运行。您需要：
- Windows 10 或更高版本，macOS 10.15 或更高版本，或当前的 Linux 桌面发行版。
- 如果您想使用 dotnet 构建器和运行器，则应使用 [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)。
- Photino 使用的平台 Webview：Windows 上的 WebView2，macOS 上的系统 WebKit 视图，Linux 上的 GTK/WebKit。
Windows 是 0.1 版本的主要测试平台。应用程序架构和 Photino shell 是跨平台的，但 macOS 和 Linux 的打包和验证仍在进行中。
### 运行应用程序
克隆存储库，切换到其根目录，然后使用您的 shell 运行应用程序：
对于 Bash：
```bash
git clone https://github.com/dalby-md/OKF-Todo.git
cd OKF-Todo
dotnet restore
dotnet run --project ./Okf-Todo/Okf-Todo.csproj
```
对于 Windows 命令提示符：
```cmd
git clone https://github.com/dalby-md/OKF-Todo.git
cd OKF-Todo
dotnet restore
dotnet run --project .\Okf-Todo\Okf-Todo.csproj
```
所有后续的 `dotnet` 命令都假定当前目录是存储库根目录。
在首次启动时，OKF-Todo 会自动创建其数据库和初始查找值。不需要设置向导或帐户。
在后续版本中，待处理的 EF Core 迁移将在应用程序读取或写入任务数据之前自动应用。
### 连接 MCP 客户端
在存储库根目录中构建 MCP 服务器：
```powershell
dotnet build .\Okf-Todo.Mcp\Okf-Todo.Mcp.csproj -c Release
```
然后配置 MCP 客户端以启动内置的 stdio 服务器。例如：
```json
{
"mcpServers": {
"okf-todo": {
"command": "dotnet",
"args": [
"C:\\git\\Okf-Todo\\Okf-Todo.Mcp\\bin\\Release\\net8.0\\Okf-Todo.Mcp.dll"
]
}
}
}
```
调整您的签出所需的绝对 DLL 路径。默认情况下，服务器使用与桌面应用程序相同的平台特定数据库。它公开了这些工具：
| 工具 | 用途 |
| --- | --- |
| `task_list` | 按视图列出任务。 |
| `task_get` | 读取一个任务。 |
| `task_create` | 通过共享的应用程序命令服务创建任务。 |
| `task_update` | 通过共享的应用程序命令服务替换任务的可编辑字段。 |
| `task_get_timeline` | 读取评论和自动任务历史记录。 |
`task_update` 对可编辑字段具有完全替换语义。首先调用 `task_get`，并包含必须保留的每个值；省略的非必需字段将被清除。
对于开发或隔离测试，使用不同的数据库启动服务器：
```powershell
dotnet run --project .\Okf-Todo.Mcp\Okf-Todo.Mcp.csproj -- --database-path C:\temp\okf-todo-mcp.db
```
MCP 协议使用标准输出。服务器和框架日志写入标准错误流，以免破坏协议流。
### 备份和还原数据
打开 **设置**，然后选择 **备份数据库**。在原生保存对话框中选择一个目标。应用程序在替换选定的目标之前创建并验证完整的 SQLite 备份。
备份包括任务、正文图像、附件、查找、标签、关系、评论、检查清单和历史记录。界面首选项（如布局和配色方案）单独存储，不包括在内。
在 0.1 版本中，还原是手动的：
1. 关闭 OKF-Todo。
2. 保留当前数据库的副本（如果需要）。
3. 用备份文件替换特定于平台的 `Okf-Todo/okf-todo.db` 文件，列于“开始使用”部分。
4. 再次启动 OKF-Todo。
在运行的应用程序替换活动数据库时，请勿执行此操作。
## 数据和隐私
OKF-Todo 是一个单用户、本地优先的应用程序。它没有身份验证、云同步、应用程序遥测或外部任务系统集成。应用程序数据保留在本地 SQLite 数据库中，除非您自己创建备份或保存附件副本。
## 当前限制
0.1 版本是一个 alpha 版本，旨在用于评估和个人使用：
- Windows、macOS 和 Linux 可以从源代码运行；Windows 目前接收最多的测试。
- Windows 安装程序可以从存储库构建。自动更新和 macOS/Linux 软件包尚不可用。
- 没有云同步或多用户协作。
- 不支持数据库降级；在安装旧应用程序版本之前，请备份数据库。
- 还原是手动的文件替换操作。
- 与电子邮件、ServiceDesk、Teams 和 Azure DevOps 的深度集成不包含在内。
在评估 alpha 版本时，请定期使用应用程序内的备份命令。
## 开发
生成解决方案：
```powershell
dotnet build -c Release
```
运行测试套件：
```powershell
dotnet test .\Okf-Todo.Tests\Okf-Todo.Tests.csproj -c Release
```
还原存储库本地 EF Core 工具，并在更改物理模型后添加迁移：
```powershell
dotnet tool restore
dotnet tool run dotnet-ef migrations add <MigrationName> --project .\Okf-Todo\Okf-Todo.csproj --startup-project .\Okf-Todo\Okf-Todo.csproj --output-dir Migrations
```
将生成的迁移和模型快照与模型更改一起提交。应用程序在启动时自动应用待处理的迁移。
产品和架构文档可在 [`docs`](docs/) 目录中找到。
### 构建 Windows 安装程序
Windows 安装程序是一个自包含的 `win-x64` Inno Setup 包。它始终安装 GUI 和 OKF 上下文图。**安装 MCP 服务器** 作为安装程序组件呈现，默认情况下已选中。
安装 Inno Setup 7（或兼容的 Inno Setup 6），然后从存储库根目录运行：
```powershell
.\installer\build-installer.ps1 -Version 0.1.0
```
或从 Windows cmd：
```cmd
installer\build-installer.cmd -Version 0.1.0
```
安装程序被写入：
```text
artifacts\installer\Okf-Todo-0.1.0-win-x64-setup.exe
```
要发布、合并和验证暂存负载而不编译设置可执行文件：
```powershell
.\installer\build-installer.ps1 -Version 0.1.0 -SkipInstallerCompile
```
强制性有效载荷被分段到 `artifacts\installer\staging\core` 下；可选的 MCP 服务器及其隔离的运行时被分段到 `artifacts\installer\staging\mcp` 下；安装的 OKF 包被分段到 `artifacts\installer\staging\okf` 下。
对于签名的生产版本，请提供 Windows SDK `signtool.exe`、证书指纹和可选的 RFC 3161 时间戳 URL：
```powershell
.\installer\build-installer.ps1 -Version 0.1.0 `
-SignToolPath 'C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe' `
-CertificateThumbprint '<certificate-thumbprint>'
```
构建在打包之前签名 GUI 可执行文件和 MCP 可执行文件，然后签名生成的设置可执行文件。普通的开发版本仍然是未签名的。
要构建并发布下一个 alpha 版本，请安装并验证 GitHub CLI，然后运行：
```powershell
gh auth login
.\installer\update_release_exe.ps1
```
不带参数时，脚本会找到最高的现有 `v<major>.<minor>.<patch>-alpha` 版本，递增其补丁号，构建该版本，复制它到稳定的 `<major>.<minor>` 资产名称，创建新版本，并将其标记为 GitHub 的最新版本。例如，`v0.1.4-alpha` 产生 `v0.1.5-alpha`，构建 `Okf-Todo-0.1.5-win-x64-setup.exe`，并将其上传为 `Okf-Todo-0.1-win-x64-setup.exe`。
标签和标题标识版本为 alpha，但 GitHub 版本故意不标记为预发布版本。GitHub 排除预发布版本不包括在 `/releases/latest` 中，因此将其标记为预发布版本会破坏此处使用的稳定安装程序 URL。
在必要时覆盖计算出的标签：
```powershell
.\installer\update_release_exe.ps1 -Tag v0.1.8-alpha
```
使用显式标签预览派生的版本、资产名称和稳定 URL，而无需构建或联系 GitHub：
```powershell
.\installer\update_release_exe.ps1 -Tag v0.1.8-alpha -WhatIf
```
仅使用 `publish-github-release.ps1` 进行替代的基于版本的非 alpha 版本工作流。不要为同一个安装程序运行两个发布脚本。
## AI 工具
OKF-Todo 使用 Codex 构建，但不绑定于 Codex。它使用 AGENTS.md 和技能以及其他跨平台设计。
