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)

运行与构建

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 服务器运行（见下）。

Related MCP server: Obsidian MCP Server

数据模型

笔记是纯粹的 Markdown 文件：

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

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

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

Issue 独立保存在 <仓库>/.pkmx/issues.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 访问仓库）

{ "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。

结构

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（v3）· 交互原型：prototype/index.html

许可证

MIT