docket

Docket

你使用的每个 AI 工具都能写入的同一份清单——Claude Code、Codex、Cursor、 Warp——覆盖所有项目，趁工作还不值得开工单时记录下来。本地优先、 可自托管，无需 SaaS 账户。

_{观看一分钟演示 · 下载 mp4}

快速开始

你需要： Node.js 18+ 和至少一个 MCP 宿主——Claude Code、Codex、 Cursor、Windsurf、Claude Desktop、Zed 或 Warp。

npx -y @pasichdev/docket setup

这会配置它在这台机器上找到的所有宿主，并在结束时告知你配置了哪些宿主。然后重启你的 Agent 并让它*"添加一个待办事项：买牛奶"*——它就会显示在 **http://localhost:8787**，这是一个在 Agent 连接时自动启动的仪表板。

只想使用 Claude Code，不想让内容写入其他地方？ claude mcp add docket -- npx -y @pasichdev/docket 只会配置这一部分。 其他宿主请见：支持的宿主。

npm install -g @pasichdev/docket        # the hook runs a command, so it needs one on PATH
docket hook install                     # then: docket hook doctor

为什么

会话中途冒出的想法值得记录，却不值得走繁琐流程：Notion 模板、GitLab 问题格式，或一个还得凭空编造的工单 ID。因此，它如今往往转瞬即逝。Docket 是所有这些流程之下的那一层——工作可以像 Agent 输入文字一样快速地从任何工具、任何项目中记录到这里，并在时机成熟时转入 Notion/GitLab/Obsidian。

没有其他人占据这个空间，而这并非偶然：Anthropic 不会让 Claude Code 与 Cursor 集成，Cursor 也不会让它与 Codex 集成。每个供应商都在优化自己的封闭循环。工具之间的空间在结构上就不属于任何人。

一个列表，多个项目

Docket 会自动将每个条目归入捕获它时所在的项目——根据 Agent 运行位置的 Git 远程仓库解析。你无需手动输入，Agent 也不必记住项目。

~/work/backend      claude-code, codex   ─┐
~/side/tracker      claude-code          ─┼──▶  docket  ──▶  one list, three scopes
~/side/notes        codex, warp          ─┘

• 在 ~/work/backend 中，todo_list 显示的是该项目的未完成条目，而不是三个项目的所有条目——每项仅占一行，简洁明了。
• Web 仪表板提供工作区切换器，并显示每个项目的未完成条目数。
• 没有项目上下文的条目会归入未分类，并始终保持可见，绝不会靠猜测归类。

使用 Git 远程仓库而非路径，意味着同一个仓库在笔记本上克隆到 ~/src/backend、在台式机上克隆到 /work/backend，仍属于同一个工作区——这正是同步功能存在的意义。完整的解析顺序和 .docket.json 覆盖设置见：docs/workspaces.md。

_{使用 node docs/assets/demo-seed.mjs 重新生成这些图片——该脚本会构建图片中展示的工作区，因此它们始终反映真实的仪表板，而非摆拍效果。}

从 2.x 升级

如果你已有条目，请在升级前阅读此部分。

3.0 首次运行时会自动将你的存储从数据格式 v7 迁移到 v8。迁移本身是安全的，风险不在这里。风险在于之后降级。

docket 2.3.1 会按自身的 v7 格式写入存储：它不认识 v8 新增的字段，因此重新安装后首次写入时，就会悄无声息地从每个条目中删除这些字段。不会报错，而之后再次升级时，系统会分配新的序列号，这些序列号将不再与配对设备上的序列号对应。2.3.1 已发布，无法修补，因此 3.0 只能通过保留迁移前存储的副本来防范：

~/.docket/todos.v7-pre-upgrade.enc

该副本会在首次写入 v8 数据前保存一次，此后不会覆盖。创建副本时，升级过程会打印其路径。

要退回 2.x，请先恢复副本：

docket restore --from-v7                     # puts the v7 store back; moves the v8 one aside
npm install -g @pasichdev/[email protected]

请按此顺序操作。restore --from-v7 不会删除任何内容——你的 v8 存储会被另行改名保留，因此之后仍可再次升级回来。

如果你还想要一份可移植副本，可以在升级前运行 docket backup ./pre-v3.backup，生成一份包含你的身份信息和配对设备的备份。

衔接，而非取代

Docket 有意不让工作永久停留在这里。它是工作最初落脚的地方，此时还没人知道这件事是否值得建工单。大多数条目都不值得，会被手动关闭；其余的则会进一步转化。

sourceUrl 是双向衔接的桥梁。只要某个条目对应一个带有 URL 的内容——GitLab issue、Notion 页面、Obsidian 分享链接、Slack 讨论串或 GitHub PR——就设置它，卡片上会显示一个可点击的链接，直接跳回原处。

为什么不直接用 GitHub Issues？ 因为创建 issue 需要拟定一个面向受众的标题、选择一个仓库，还要维护标签——而且当你在另一个项目中思考到一半时，Cursor 会话无法替你创建 issue。Docket 只需一句话，无论你当前打开的是哪个工具。等条目确认有价值后，再将它转成 issue，sourceUrl 会记住它的去向。

支持的宿主

任何 MCP 宿主都适用——各处使用的工具完全相同：

{
  "mcpServers": {
    "docket": { "command": "npx", "args": ["-y", "@pasichdev/docket"] }
  }
}

{
  "context_servers": {
    "docket": { "command": { "env": {}, "path": "npx", "args": ["-y", "@pasichdev/docket"] } }
  }
}

唯一的钩子

Claude Code 还会获得一个 SessionStart 钩子，也只有这一个：

docket hook install      # writes .claude/settings.json (--global for user-wide)
docket hook doctor       # proves it fires, and reports measured latency
docket hook uninstall    # removes only the entries docket owns

会话开始时，它会注入该项目中打开的条目——内容精简， 最多 7 条，总计不超过 120 个令牌。项目中没有打开任何内容时， 则完全不注入任何内容。它的唯一作用是保持上下文连续：你回到 终端时，之前的对话已经在那里。

不想要它？ export DOCKET_HOOKS=off 可立即禁用，无需 编辑任何配置或卸载任何内容。docket hook doctor 会测量真实的往返 耗时；如果慢到足以让人察觉，它会告知你。

它始终采用故障开放策略。 服务未运行、请求超时、响应格式错误、 DOCKET_HOOKS=off——这些情况都会以状态码 0 退出，且不打印任何内容。 如果工具本身出故障就会拖累会话，这种工具最终会被卸载，那样它就 帮不到任何人。docket hook doctor 会实际运行已配置的命令，并报告 会话实际会看到什么，因此从未触发的钩子会清晰可见，而不只是悄无声息。

没有 PreToolUse，不进行阻止，也不支持其他宿主——此版本中， 该钩子的唯一作用是保持上下文连续，而非执行管控。

面向非 Claude Code Agent 的使用指南

这些工具在任何地方都能使用；但使用指南以 Claude Code 插件的形式提供。 对于其他 Agent，请将 skills/docket/SKILL.md （--- 前置内容之后的所有内容）复制到 Agent 会读取的文件中—— Codex 使用 AGENTS.md，Cursor 使用 .cursor/rules/docket.mdc， Windsurf 使用 .windsurfrules，Claude Desktop 使用 CLAUDE.md， Warp 则使用其自定义指令设置。

/plugin marketplace add pasichDev/docket
/plugin install docket@docket

工具

完整的字段和工作流参考：skills/docket/SKILL.md。

摘要

让你的 Agent “生成摘要”（或 “зроби дайджест”）。docket:digest 技能会读取你的合并请求、拉取请求、Notion 工单、本地提交和 docket 项目，在信息源处检查每项的状态，并发布结果—— 作为仪表板的主页：哪些事项需要你处理、哪些已交付、哪些正在审核、哪些受阻；每项都链接回其所在位置，并且只需点击一下即可将其转为任务。

Docket 从不持有 GitLab、GitHub 或 Notion 凭据：Agent 使用已有的 CLI 和 MCP 服务读取这些信息，Docket 只保留它写入的内容——本地模式下存放在这台机器上（并同步到已配对的设备），自托管模式下存放在 Docket 服务上，供每个客户端共享。Agent 能访问的其他任何内容——通过 MCP 服务访问的 Jira、Linear 或 Sentry、Obsidian 保管库、项目的文档文件夹——都可以添加为信息源；摘要也可以拆分成工作、学习和个人项目等分组。要读取的内容因机器而异，保存在 ~/.config/docket/digest.json 中（由 docket:digest-setup 技能写入）；摘要本身会同步到已配对的设备。详情见：docs/digests.md。

• 自上次摘要以来的变化会在发布时计算——新增项目、状态变化、已移除的项目——而不是依赖 Agent 的记忆。
• **负责人：**每个项目都可以指定负责人（你、队友或 Agent）；按人员查看会将摘要整理成每人编号的后续步骤。
• **重要事项详述：**常规项目保持一行；受阻、失败或过期的项目会附上 Agent 对实际原因和后续步骤的分析。
• **按编号交接：**告诉任意 Agent “处理第 7 项”——digest_take 会提供简要说明，并以该 Agent 的名义认领一项任务；完成后，它会说明原因并关闭任务。
• 已查看会隐藏某个项目，直到其状态发生变化；标记会在设备间同步。
• **由你塑造：**分组、人员、预设（“工作摘要”、“每周摘要”）、环境检查、通过 MCP 获取的邮件和聊天、每日运行——技能还会记录简短备注，追踪你反复纠正的内容。

CLI

docket list [-w <project>] [--all]          What's open, scoped like the MCP default
docket workspaces                           Projects, with open counts and last activity
docket sessions                             Agent sessions open right now, and where
docket stats | export | import              Inspection and round-tripping
docket hook install | uninstall | doctor    Claude Code SessionStart hook
docket serve | pair | devices | status      Self-hosted server & devices
docket backend use <url> | localize         Switch deployment mode
docket backup <file> | restore <file>       Encrypted full-device backup
docket web                                  Ensure the Web UI is running
docket check-update | update                Version management

docket help 会输出规范且始终保持最新的列表。完整参考： docs/cli.md。

部署模式

两种模式都通过同一个软件包安装，并提供相同的 MCP 工具。完整的自托管设置指南，以及它有意不做的事情： docs/self-hosting.md。

**P2P 同步自 v3.0 起已弃用。**它仍然可用，本次发布也不会移除任何内容——但其 15 秒的拉取间隔意味着，通过 P2P 同步时的认领仅供参考，因此无法提供原子性保证。自托管模式是受支持的多机器方案。请参阅 docs/p2p-sync.md。

Web UI

实时读写仪表板——Local Mode 下默认为 http://localhost:8787（可通过 DOCKET_WEB_PORT 覆盖），或 Self-hosted Mode 下使用 Docket Server 自身的 URL。主页（/）会在任务列表旁一目了然地显示最新的摘要；任务列表本身位于 /tasks。工作区切换器会显示各项目的打开任务数；还提供活动会话面板、浅色／深色主题、搜索、排序、行内编辑、撤销删除和响应式移动端布局。

在 Local Mode 下，服务会自行启动：如果尚无服务在监听，第一个连接的 MCP 客户端会在后台分离启动它。更新通过服务器发送事件（/api/events）实时推送，无需轮询。

要从 LAN 上的其他设备（手机、平板电脑）打开仪表板，必须先在主机上明确批准查看者门控——参见安全性。

安全性

Docket 有四种独立的威胁模型（加密的本地存储、P2P 同步、LAN 查看者门控，以及自托管客户端／服务端流量）——其中一种模型的保障不适用于其他模型。基本信息如下：

• 静态数据：todos.json.enc 和 history.json.enc 使用本地生成的密钥进行 AES-256-GCM 加密——可防止意外泄露，但无法防范拥有你自己用户账户读取权限的人。
• P2P 同步：X25519 ECDH + HKDF 派生的成对密钥、带重放保护的 HMAC 签名请求，以及 AES-256-GCM 加密响应。
• LAN 查看者门控：除主机外的任何浏览器都必须先获得人工明确批准，才能打开仪表板；本地流量本身使用的是普通 HTTP，而非 TLS（这是有记录的权衡，并非疏忽）。
• 自托管模式：每台设备使用带时间戳和 nonce 重放保护的 HMAC 签名。服务端不会针对其自身运营者进行端到端加密。
• 更新：每个版本都会发布带有 Sigstore 支持的 npm 来源证明，可通过 npm audit signatures 验证。

完整威胁模型、具体加密原语和限制： docs/security.md。

数据与加密

权威数据在 Local Mode 下存储于本机（~/.docket），或在 Self-hosted Mode 下存储于 Docket Server——无论哪种方式，数据都位于你控制的基础设施上，绝不会存储在托管账户中。

• todos.json.enc — 存储库，使用 AES-256-GCM 加密
• history.json.enc — 完整审计日志，独立于存储库的写入路径保存
• digests.json.enc — 摘要，使用 AES-256-GCM 加密，并具有独立的同步游标
• key — 本地生成的 256 位密钥，权限为 chmod 600
• device.json — 本机的 ID、名称和 X25519 身份密钥对
• peers.json.enc — 已配对的 P2P 设备及其派生的同步密钥
• sessions.json — 当前打开的 Agent 会话（明文，仅限本地，绝不同步；其中保存进程元数据，而非内容）

设置 DOCKET_DATA_DIR 可更改目录位置；启动时如果发现现有存储库，会拒绝在不提示的情况下将数据拆分到不同位置，而不是自行猜测。

备份与更新

docket backup <file> 会将整个数据目录打包为一个受密码保护的文件（AES-256-GCM，密钥由 scrypt 派生）；docket restore 会将其恢复，先将磁盘上现有数据重命名移开，而不是直接覆盖。

docket check-update   # read-only — reports current vs. latest
docket update         # checks, confirms, installs, self-tests, rolls back on failure

测试

npm test

运行完整的 node:test 测试套件——同步传递与分页、真实竞争情况下的跨进程文件锁、工作区解析与作用域、会话注册表、面向 Agent 的令牌预算，以及钩子的故障开放行为。

许可证

MIT — 参见 LICENSE。