# PKMX

本地优先的 Markdown 笔记应用，内置独立的项目 Issue 管理。**笔记与 Issue 数据完全分离**：笔记是仓库里的 `.md` 文件，Issue 保存在 `.pkmx/issues.json`，互不混杂。

MIT License · Tauri 2 · React 19 · Vite 8 · TypeScript 6 · Tailwind CSS 4 · shadcn/ui (radix) · zustand · sonner · Rust (notify · tantivy)

## 运行与构建

```bash
npm install
npm run dev          # 浏览器开发（内存仓库，不碰磁盘）
npm run tauri dev    # 桌面壳（首次编译 Rust 较慢）
npm run tauri build  # 打包：exe + NSIS 安装包（约 2.6 MiB）
```

- **浏览器模式**：数据在内存（无磁盘权限，空仓库起步），刷新即重置。
- **桌面模式**：首次启动选择文件夹作为仓库（之后自动记住）。仓库是普通文件夹，应用只读写其中的 Markdown/YAML/附件与 `.pkmx/` 内的 Issue 数据。
- **MCP 模式**：`pkmx.exe --mcp --vault <目录>` 直接作为 MCP stdio 服务器运行（见下）。

## 数据模型

笔记是纯粹的 Markdown 文件：

```md
---
date: 2026-10-19     # 可选，每日笔记
---

# 标题取自第一个 H1（与文件名解耦）

正文：[[双链]]、- [ ] 勾选项（可一键转为 Issue）、**加粗**、
> [!note] 提示、代码块、![](attachments/x.png) 粘贴图片。
```

Issue 独立保存在 `<仓库>/.pkmx/issues.json`：

```json
{
  "version": 1,
  "issues": [
    {
      "id": "iss_...",
      "title": "修复登录超时",
      "body": "复现步骤与验收标准…",
      "status": "Doing",
      "priority": "High",
      "due": "2026-10-31",
      "created": "2026-10-19",
      "updated": "2026-10-19"
    }
  ]
}
```

状态：`Todo` / `Doing` / `Blocked` / `Done`；优先级：`Low` / `Normal` / `High` / `Urgent`。改为 Done 自动记录完成日期并归档。

特殊文件：`.pkmx/issues.json` Issue 存储 · `.pkmx/legacy-backup/` 旧任务迁移备份 · `views/*.yml` 保存视图（筛选 Issue） · `attachments/` 附件 · `YYYY-MM-DD.md` 每日笔记。

旧版本中「带 `status` frontmatter 的笔记」会在首次加载时自动迁移为 Issue：先写 JSON，再把原文件备份到 `.pkmx/legacy-backup/` 并从笔记目录删除。

## 功能

- **笔记**：文件夹树 / 阅读·源码双模式（源码=整文件直编 + `[[` 补全）/ 属性条 / 大纲·反向链接 / 重命名·删除·移动·新建 / 粘贴图片落盘 / 全文搜索（Ctrl+F，桌面模式走 Rust 侧扫描）/ 快速打开（Ctrl+P）/ 阅读模式选中文字一键转双链
- **文件夹**：右键新建子文件夹 / 重命名（磁盘目录整体改名，里面文件一并跟随）/ 递归删除（二次确认，含办公文档与附件）/ 在资源管理器中打开；空目录不落盘，新建时写一篇同名占位笔记
- **Issue 管理**：独立 JSON 存储 / Issue 看板（待办 · 进行中 · 受阻分列，拖拽改状态，状态筛选，列内新建，右键完成后自动归档）/ 已归档任务（已完成 Issue，按归档日期区间筛选）/ 工作报告（日报 / 周报 / 月报，仅统计已完成 Issue，渲染为文档并可复制 Markdown）/ 保存视图（UI 新建，存 views/）/ Issue 编辑器（状态、优先级、截止日期、Markdown 描述、自动保存）/ 笔记勾选项一键转 Issue / 旧任务自动迁移并备份
- **日志**：笔记菜单「今日笔记」按需创建，自动聚合到期与完成的 Issue，可固化进正文
- **捕获**：Ctrl+N 一句话记笔记；也可直接创建 Issue
- **同步**：桌面模式监听文件变化，外部编辑器/agent 对笔记与 `.pkmx/issues.json` 的改动实时反映；**多仓库同时加载**（顶栏「仓库管理」、文件树的「打开文件夹…」或直接拖入文件夹，把其他仓库合并进文件树，独立监听、独立读写）
- **默认文档地址**：设置 → 通用 指定新建笔记与快速捕获的落脚目录（仓库内相对路径，留空即根目录；不影响 Issue 存储）
- **窗口**：无边框自定义标题栏（顶栏左侧「仓库管理 / 新建笔记」，可拖拽、双击最大化、最小化/最大化/关闭）
- **主题**：昼白 / 夜墨

## MCP（AI 访问仓库）

```json
{ "mcpServers": { "pkmx": {
    "command": "D:\\path\\pkmx.exe",
    "args": ["--mcp", "--vault", "D:\\path\\vault"] } } }
```

笔记工具：`search_notes` / `get_note`（含毫秒级 mtime）/ `create_note` / `update_note`（mtime 守卫防读改写竞争）/ `append_to_note` / `delete_note`（可选 mtime 守卫）。Issue 工具：`list_issues` / `get_issue` / `create_issue` / `update_issue` / `delete_issue`（独立 JSON，mtime 守卫），`create_task` 为兼容别名。视图工具：`list_views` / `get_view` / `run_view`（执行视图，返回匹配 Issue）/ `create_view` / `update_view` / `delete_view`。笔记、Issue、视图权限可在设置中分组开关。详见 [agent-docs/AGENTS.md](agent-docs/AGENTS.md)。

## 结构

```
src/lib/      types / dates / frontmatter / markdown / vault(仓库抽象) / office / themes
src/store.ts  zustand 全局状态、写盘、文件监听、领域逻辑
src/components/ Titlebar / Sidebar+FileTree / Editor / DocView / IssueBoard / IssueView /
               Views(已归档·保存视图) / WorkReport / SearchView / CaptureDialog /
               QuickOpen / PromptDialog / SettingsView / VaultDialog / VaultGate / Chips / Statusbar
src-tauri/src/lib.rs  文件命令 + notify 监听 + tantivy 搜索 + --mcp stdio 服务器
```

手动测试脚本在 `scripts/`：`test-sheet-clamp.ts`、`test-office.mjs`、`test-mcp.mjs`、`test-mcp-perms.mjs`（后两者需已打包的 `pkmx.exe`）。

设计文档：[note-app-design.md](note-app-design.md)（v3）· 交互原型：[prototype/index.html](prototype/index.html)

## 许可证

[MIT](LICENSE)