Web 应用 — 远程访问，零安装​

UnDercontrol 的 Web 端基于 Vite + React + TypeScript 构建，是整个平台的基础界面。打开浏览器即可访问，无需安装任何软件。

核心能力：

• 完整的任务、预算、支出管理
• Tiptap 富文本编辑器（代码块、Mermaid 图表、表格、清单）
• AI 聊天集成（支持 Claude、OpenAI 等多种 Provider）
• SSE 实时通知，多标签页同步更新
• 响应式设计，移动端同样可用
• 中英双语界面

Web 端同时也是 Electron 桌面端的渲染层——同一套代码，零重复。

典型场景

• 出门在外，用手机浏览器快速查看任务进展、审批支出
• 团队成员无需安装任何软件，打开链接即可协作
• 作为所有客户端的数据汇聚点——CLI 推送的文档、桌面端创建的任务、扩展剪藏的网页，全部在 Web 端统一查看和管理

Electron 桌面端 — 离线优先，本地数据​

桌面端不仅仅是把 Web 应用套了一层壳。它内嵌了完整的 Go 后端和 SQLite 数据库，开箱即用，无需配置服务器。

内嵌后端架构

• 应用启动时自动拉起 Go 后端进程
• 动态端口分配，避免冲突
• 数据存储在 ~/Library/Application Support/UnDercontrol/（macOS）
• 完全离线可用——断网也不影响使用

远程后端模式

• 桌面端同样支持配置连接远程服务器，与 Web 端共享同一个数据源
• 在设置中切换 API 地址即可，无需重装

Daemon 模式

• 后台守护进程，通过 SSE 监听任务队列
• 接收并自动执行远程派发的任务——非常适合与 AI Agent 配合使用

桌面专属功能

• 系统托盘（Windows）— 最小化到托盘，快速访问
• .md 文件关联 — 双击 Markdown 文件直接在 UnDercontrol 中打开
• 多窗口编辑 — 同时打开多个编辑器窗口、任务窗口、便签窗口
• 工作区管理 — 本地终端窗口，执行命令

构建目标

• macOS — DMG 安装包，Universal Binary（x64 + ARM64）
• Windows — NSIS 安装包（x64）
• Linux — AppImage（x64）

典型场景

• 飞机上、高铁上没有网络，照常创建任务、编辑文档，联网后自动同步
• 在家用桌面端连接公司服务器，和 Web 端看到的数据完全一致
• 通过 Daemon 接收远程派发的 AI 任务，本地机器自动执行

CLI 工具 — kubectl 风格，AI Agent 友好​

ud CLI 是为开发者和自动化场景设计的终端工具，采用 kubectl 风格的动词-资源命令体系。

交互式 TUI

直接运行 ud 进入全屏 TUI 界面，用键盘浏览和管理任务。

一行命令完成操作

ud get task                          # 列出任务
ud describe task abc123              # 查看详情
ud apply -f task.md                  # 从文件创建/更新
ud task query "status:todo tag:api"  # 查询过滤
ud task nl "上周完成的任务"            # 自然语言查询

AI Agent 集成

ud prompt <skill-name> 输出技能文档，让 AI Agent（Claude Code、Codex、OpenCode 等）学会使用 ud CLI 操作任务。结构化的命令输出和 Markdown 格式的输入，天然适合 AI Agent 读写。

典型场景

• CI/CD Pipeline 中自动将发布说明推送到 ud，团队在 Web 端直接查看，不用翻 Git log
• 代码仓库里的技术文档（架构设计、API 规范、运维手册）通过脚本同步到 ud，非开发人员也能在 Web 端阅读，不用访问代码仓库
• AI Agent 在编码过程中自动将进度、决策记录写入任务笔记，团队实时可见
• 运维脚本定期采集巡检结果，ud apply 写入任务，形成可追溯的运维日志

Chrome 扩展 — 一键剪藏​

Chrome 扩展让你把任何网页变成 UnDercontrol 中的任务。

• 一键保存 — 捕获完整网页快照（HTML + 所有嵌入资源）
• Markdown 提取 — 自动提取页面正文为干净的 Markdown
• 离线模式 — 无需登录，直接保存到本地磁盘
• 远程模式 — 登录后直接创建为 UnDercontrol 任务，快照作为附件上传

典型场景

• 调研竞品时，一键保存产品页面为任务，稍后在 Web 端整理对比
• 看到一篇技术文章，剪藏为 Markdown 存入 ud，团队共享阅读
• 收到客户反馈的网页截图，直接剪藏为 Bug 任务，附带完整上下文

SSE 实时同步​

所有连接到同一后端的客户端——无论是 Web 标签页、桌面应用还是另一台设备——通过 SSE（Server-Sent Events）实时同步。

• 任务状态变更、新评论、附件上传，所有事件实时推送
• Daemon SSE Hub 专门用于向桌面端 Daemon 派发命令
• 工作区会话状态在桌面端和后端之间自动协调

同一套代码，一致的体验​

UnDercontrol 的多平台策略不是"每个平台写一套"，而是：

• Web 应用是唯一的前端代码库
• Electron 直接加载 Web 构建产物，零代码重复
• CLI 共享同一套 API 和数据模型
• Chrome 扩展使用相同的 API 端点

不止于此——开放的 API 让你构建任何你想要的客户端。

更多可能 — 自定义客户端​

四种官方客户端之外，UnDercontrol 开放了完整的 RESTful API。在个人设置中生成 API Key，配合 Swagger 文档，你可以用任何语言构建自己的客户端——Python 脚本、自动化 Bot、内部工具集成，甚至是你自己的移动端 App。

• API Key 认证 — 在 Profile → API Key 中生成，Bearer Token 方式调用
• 权限范围可控 — 按模块（任务、支出、预算、文件、AI）独立授权
• Swagger 文档 — https://your-server/swagger/index.html 查看所有端点
• X-UD-Channel 审计 — 自定义 Channel 标识，追踪每个请求来源
• CI/CD 友好 — 环境变量配置，无缝接入自动化流水线

典型场景

• 用 Python 写一个 Slack Bot，团队在 Slack 中 /task 即可创建和查询 ud 任务
• 内部管理后台通过 API 将工单系统与 ud 打通，双向同步状态
• 移动端原生 App 调用相同 API，实现手机端的个性化体验
• 监控系统告警自动创建 ud 任务，附带上下文信息，值班人员在 Web 端处理

不同的场景，选择最适合的工具形态——数据始终同步，体验始终一致。

在 UnDercontrol 中，Task（任务） 是信息的核心载体。如果你用过 Jira，可以把它理解为 Issue；如果你用过 Obsidian，可以把它理解为一篇 Note。Task 的本质是一段绑定了状态的主体内容，围绕它有一系列一等公民属性（标题、标签、链接关系等），同时支持无限的自定义元数据字段（键值对），让你可以将任何信息附加其上。通过笔记（Notes）机制，Task 还能不断演进——记录进展、讨论和决策，随时间沉淀为完整的知识上下文。

而这篇文章要讲的，是 UnDercontrol 中所有文本输入场景共享的富文本能力。说"任务"，但不只是任务——无论是任务描述、笔记、支出备注还是账户说明，都使用同一套 Markdown 编辑器。你在任务里用到的代码块、Mermaid 图表、表格、清单，在笔记和其他场景中同样可用。

所见即所得 — 基于 Tiptap 3 的 Markdown 编辑器​

UnDercontrol 的编辑器基于 Tiptap 3 构建。你可以直接用 Markdown 语法书写，也可以通过可视化工具栏操作——编辑器实时渲染，所写即所见。不需要在"编辑模式"和"预览模式"之间来回切换，输入的内容即最终呈现的样子。

同时，编辑器也支持切换到源码模式（Source Mode），直接查看和编辑原始 Markdown 代码——对于习惯纯文本编辑或需要精确控制格式的用户，随时可以在所见即所得和 Raw Markdown 之间自由切换。

斜杠命令 — 无需离开键盘即可排版​

在任意位置输入 /，即可打开命令菜单。从这里可以插入标题、代码块、表格、Mermaid 图表、清单等——全程无需使用鼠标。

斜杠菜单支持：

• 标题（H1–H5）用于文档结构
• 任务列表，带有可交互的复选框
• 代码块，支持语言选择和语法高亮
• Mermaid 图表，用于流程图、时序图等
• 表格，支持完整的单元格编辑
• 引用块、分割线和图片

语法高亮代码块​

直接将代码粘贴到任务中。编辑器支持 100+ 种编程语言的语法高亮——从 TypeScript、Go 到 SQL、YAML。

代码块配有语言选择下拉框和一键复制按钮。无论是记录 API 接口还是保存常用的 Shell 命令，代码都保持清晰可读。

Mermaid 图表 — 在任务中直接可视化架构​

最强大的功能之一：在任务描述中直接嵌入 Mermaid 图表。通过斜杠菜单插入 Mermaid 块，编写图表语法，即可实时渲染。

支持的图表类型包括：

• 流程图 — 系统架构、决策树
• 时序图 — API 交互流程、认证握手
• 类图 — 数据模型、实体关系
• 状态图 — 工作流状态、生命周期追踪

图表查看器支持全屏预览、SVG 下载，以及自动深色/浅色主题切换。

结构化数据表格​

需要记录状态码、对比指标或追踪功能矩阵？插入表格后可直接编辑单元格。通过右键菜单添加或删除行列、切换表头行、合并单元格。

真正可用的清单​

任务列表渲染为可交互的复选框。在渲染视图中直接勾选完成项——无需切换到编辑模式。非常适合追踪子步骤、验收标准或部署清单。

图片与附件 — 告别 Obsidian 式的资源管理噩梦​

如果你用过 Obsidian 管理带图片的笔记，一定经历过这些痛苦：图片散落在本地文件夹里，路径一变就全部裂图；换一台设备打开，附件全都找不到；多端同步时冲突不断，不知道哪个版本是对的。本质问题是——Obsidian 把资源管理交给了文件系统，而文件系统天然不擅长跨设备同步。

UnDercontrol 从根本上解决了这个问题。所有图片和附件通过 resource:// 协议统一管理，上传即入库，不依赖任何本地路径。无论你在 Web、桌面端还是分享链接中查看，图片始终可用——因为资源跟随数据库走，而不是跟随文件系统。

此外，UnDercontrol 还提供了本地文件夹的双向同步能力，可以将本地目录中的文件与服务端资源库保持同步。这个功能的细节我们会在后续的博文中专门介绍。

图片大小调整

插入的图片支持三档大小预设，编辑模式下悬停即可切换：

• 小（25%） — 缩略图，适合行内展示
• 中（50%） — 适中尺寸
• 大（100%） — 全宽展示

尺寸信息以 Obsidian 兼容格式存储（![描述|s](resource://id)），点击图片可全屏预览。

Draw.io 图表 — 内置可视化绘图​

UnDercontrol 内置 Draw.io 编辑器，支持 .drawio 和 .drawio.png 格式。上传或创建 Draw.io 文件后，可直接在应用内打开编辑——无需安装任何桌面软件。编辑完成后保存为 PNG（内嵌 XML 源数据），既可渲染预览，也可随时重新编辑。

同样得益于 resource:// 协议，Draw.io 图表作为资源统一管理，不存在本地路径依赖或同步丢失的问题。

AI 驱动的文本操作​

选中任务描述中的任意文本，即可显示气泡菜单。除了标准排版（加粗、斜体、删除线），还有 AI 驱动的操作：

• 润色 — 重写选中文本，提升表达清晰度
• 翻译 — 即时翻译为其他语言
• 对话 — 针对选中内容提出问题

实体链接 — 像 Wiki 一样连接任务​

在描述中直接链接到其他任务、笔记、支出、预算和账户，使用 task://、note:// 等自定义协议。链接渲染为可点击的引用——点击即可跳转到关联的实体。

切换到源码模式可以看到原始 markdown——每个链接使用自定义协议，如 [API Integration Guide](task://189571b0-...)：

这将你的任务描述转变为一个互联的 Wiki，上下文在相关项目之间自然流转。

CLI + AI Agent — 让 AI 帮你写内容​

因为 Markdown 是纯文本，它天然适合与 AI Agent 协作。通过 ud CLI，你可以让 Claude Code、Codex、OpenCode 等终端 AI 工具直接读取、撰写和更新任务内容：

• 总结归纳 — 让 AI 读取一组任务，自动生成周报或迭代回顾
• 提炼重构 — 把零散的笔记整理成结构化的文档
• 分类打标 — 根据内容自动添加标签和分类
• 批量创建 — 从会议纪要或需求文档一键生成多个任务

内容通过管道直接写入：

cat <<'EOF' | ud apply -f -
---
title: API Integration Guide
status: in-progress
tags: [api, backend]
---
## Authentication Flow

1. Client sends credentials to `/auth/login`
2. Server returns JWT token
3. Include in `Authorization: Bearer <token>` header
EOF

AI 生成的 Markdown 与手写的 Markdown 在 Web、桌面、分享视图中的渲染效果完全一致。你的内容始终保持可移植、可版本控制。

UnDercontrol 的 Markdown 支持意味着你的任务可以承载任意深度的技术细节——而无需离开跟踪工作进展的工具。代码块、图表、表格和清单与任务状态、截止日期和协作上下文共存。

立即尝试——创建一个任务，输入 / 看看有什么可能。

这就是远程工作区。它在云端任务管理器和本地开发环境之间架起了一座桥梁，让 UnDercontrol 成为 AI 编程代理的远程控制器。

问题所在​

大多数任务管理工具完全运行在浏览器里，而你的代码在本地机器上。当你想让 AI 代理帮忙处理某件事时，你得切换到终端、粘贴上下文、盯着过程、最后手动更新任务状态。任务追踪器和执行环境是两个完全割裂的世界。

远程工作区消除了这个距离。你的任务描述变成了可执行指令，你的浏览器变成了控制面板，你的机器负责执行。

工作原理​

架构由四个部分组成：

1. Electron 桌面应用 — 运行在你的机器上，充当守护进程。当你在工作区页面注册设备时，应用通过 Server-Sent Events（SSE）连接到 UnDercontrol 服务器，等待接收指令。

2. 服务器 — 在 Web 界面和守护进程之间中转命令，持久化会话状态、备注和状态更新。

3. 守护进程核心 — Electron 渲染进程中的"大脑"。它持有认证令牌，管理 SSE 连接，驱动所有 API 调用。当工作区会话启动时，它将初始化事件转发给 Electron 主进程。

4. AI 代理 — 由 Electron 主进程在伪终端中生成的编程工具（如 Claude Code）。它读取任务、完成工作，并通过任务备注报告进度。

设置步骤​

打开 UnDercontrol 桌面应用，导航到工作区页面，点击注册此设备——应用会自动检测你的机器名称和平台。就这么简单。你的机器现在是一个守护进程，已连接并准备就绪。

Electron 应用在后台处理一切：守护进程注册、SSE 连接、心跳和重连。不需要任何终端命令。

要让 AI 代理工作，你需要在机器上安装 Claude Code：

npm install -g @anthropic-ai/claude-code

触发会话​

设备注册并上线后，在 Web 界面（或桌面应用本身）打开任意任务，点击操作栏中的地球图标。你会看到已连接的守护进程列表——选择一个，会话即刻开始。

守护进程收到初始化事件后，Electron 主进程在 PTY 窗口中生成 AI 代理。接下来一切自动进行：

1. 代理读取任务描述和备注
2. 规划并执行工作
3. 进度备注实时出现在任务页面上
4. 完成后更新任务状态

实时观察​

这是最让人满足的部分。当代理在你的机器上运行时，你在浏览器里实时看到它的进度。

备注随着代理的工作不断涌入：它在读什么、改了什么、提交了哪些文件。你得到了整个会话的运行日志，而完全不需要碰终端。

会话面板显示：

• 状态 — 运行中、规划中、等待输入、空闲或已停止
• 持续时间 — 会话已运行多长时间
• 守护进程信息 — 哪台机器在执行
• 备注流 — 代理的实时更新

交互控制​

远程工作区不是「发射后不管」的模式。你可以在代理运行时与它交互：

• 发送指令 — 输入额外的上下文或在任务中途调整代理的方向
• 截图 — 捕获工作区的当前状态
• 中断 — 发送 Ctrl+C 信号暂停执行
• 停止 — 完全结束会话

还有一个提示词系统。把常用的指令保存为模板，一键应用。如果你在 UnDercontrol 中设置了技能（Skills），也可以引用它们——把技能内容直接传递给代理。

工作区仪表盘​

工作区页面提供所有活动会话和已连接守护进程的全局视图。

每个会话卡片显示它正在处理的任务、哪个守护进程在运行、已运行多长时间以及最新的备注。守护进程列出了在线/离线状态、机器名称、平台和共享权限。

你可以直接在这个页面注册设备——一键上线。

安全机制​

远程运行 AI 代理自然会引发安全顾虑。远程工作区通过分层黑名单系统来应对：

内置保护：

• bash、sh、zsh 等工具被禁止作为实现工具——代理通过受控接口运行，而不是原始 shell
• 破坏性命令（rm -rf、mkfs、dd）在守护进程层被阻止

自定义配置： 在 ~/.config/ud/workspace-blacklist.yml 放置 YAML 文件来定义你自己的规则：

blocked_tools:
  - bash
  - sh
allowed_tools:
  - claude
blocked_commands:
  - "rm -rf"
  - "mkfs"

守护进程还需要正确的身份验证——Electron 应用使用你已登录的会话令牌，没有你的凭据就无法进行未授权访问。

共享守护进程​

在团队场景中，你可以将守护进程共享给你的组。设置共享权限后，团队成员可以在你的机器上触发工作区会话——这对共享构建服务器或专用 CI 机器很有用。

共享通过守护进程的权限控制：只读权限让其他人查看守护进程状态，读写权限则允许他们发起会话。

为什么这很重要​

大多数开发者工具将任务管理和代码执行视为独立的事情。你在一个应用里计划，在另一个应用里执行，然后通过复制粘贴和上下文切换来手动弥合差距。

远程工作区将它们合并。你的任务描述就是指令。你的浏览器就是控制面板。工作在你的机器上发生，使用你的工具，在你的环境中——你只是不需要在终端里才能启动它。

对于个人开发者，这意味着更少的上下文切换。写任务、触发代理、审查输出——全在同一个界面。对于团队，这意味着一个共享的工作队列，机器可以接手并执行，同时对正在发生的事情具有完全的可见性。

架构还意味着你不会被锁定在任何特定的 AI 工具上。今天它与 Claude Code 配合使用；明天它可以与任何在终端中运行的代理配合。协议很简单：接收任务、完成工作、报告进度。

开始使用​

1. 下载 UnDercontrol 桌面应用
2. 安装 Claude Code：npm install -g @anthropic-ai/claude-code
3. 打开工作区页面，点击注册此设备
4. 打开任意任务，点击地球图标，选择你的守护进程

查看文档了解完整的设置指南，包括安全配置和故障排查。

UnDercontrol 的任务分享功能解决了这个问题。生成一个公开链接，给出一个短访问码，对方就能查看这个任务的所有内容——描述、笔记、附件，完整呈现——不需要注册账号，也不需要碰你的密码。

工作原理​

在任何任务详情页，点击分享图标打开分享对话框。你会得到两样东西：

1. 直接链接 ——一个完整的 URL，打开后是干净的只读视图
2. 访问码 ——一个短字母数字代码（比如 QJVOFL），在分享码页面输入即可访问

访问码是为不方便发送链接的场景设计的——比如电话里告诉对方、写在白板上、或在长链接会被截断的聊天工具里使用。

控制分享内容​

不是每个任务都需要相同的分享方式。分享对话框提供两个控制选项：

过期时间：选择链接的有效期。从 1 小时（快速查看）到 7 天（持续协作）再到永不过期（永久参考链接），灵活选择。

附件权限：默认情况下，附件会被列出但不可下载。如果你希望查看者能下载任务附件，打开"允许下载附件"开关。

你可以为同一个任务创建多个分享链接，使用不同的设置——比如一个 1 小时链接用于快速审查，一个 7 天链接用于协作。

查看者的体验​

当别人打开分享链接时，他们会看到一个干净、专注的任务视图：

• 标题和状态，带有熟悉的状态图标
• 标签，提供上下文
• 完整的 Markdown 描述，包含所有格式、表格和图片
• 笔记，按最近更新排序，完整渲染
• 附件（如果链接允许，可以下载）
• 关联项目，作为参考展示
• 二维码，方便手机端快速分享
• 过期倒计时，让查看者知道链接还有多久有效

页面是独立的。没有导航栏，没有登录提示，没有应用外壳。只有内容本身。

访问码——模拟世界的桥梁​

访问码功能值得单独介绍。打开分享页面（/share），输入代码，就会自动跳转到分享的任务。

这在以下场景特别有用：

• 演示文稿：把代码放在幻灯片上，让观众自行查看参考资料
• 电话沟通："查看任务代码 QJVOFL" 比念一个 60 字符的 URL 简单多了
• 线下场景：写在便利贴或白板上

管理分享链接​

回到分享对话框，你可以看到某个任务的所有活跃链接。每个条目显示：

• 访问码和截断的 token
• 是否启用了附件下载（回形针图标）
• 过期时间（相对时间）

点击删除按钮即可立即撤销任何链接。之后任何人尝试访问该链接都会看到错误提示。

技术实现​

分享基于 token 机制。每个分享链接都有一个唯一 token，映射到对应的任务。公开端点（/share/todolist/:token）不需要任何认证——这是一个真正的公开路由。Markdown 描述中嵌入的资源（图片、图表）也通过分享 token 解析，因此内联图片可以正确显示，而不会暴露你的存储凭证。

访问码是一个独立实体，映射到 token，提供额外的访问路径而不影响安全性。代码使用大写字母和数字，便于阅读。

使用场景​

以下是任务分享功能大显身手的几个场景：

• 跨团队交接：把需求文档分享给组织外的人
• 客户更新：向客户发送项目状态，无需给他们应用访问权限
• 会前准备：通过访问码分享会议议程
• 知识共享：创建永久链接指向参考文档或操作手册
• 快速审查：生成 1 小时链接进行同事快速评审

核心理念是：不是每条信息都需要藏在登录墙后面。有时候你只需要快速、无摩擦地给别人看一样东西。

任务分享功能现已在 UnDercontrol 中可用。打开任何任务，点击分享，试试看。

四个层级​

心智模型是这样的：每个过滤层级缩小上一层级传递的结果。把它想象成一个管道。

第 1 层：看板范围（私有 vs 共享）→ 第 2 层：范围标签（看板级标签过滤）→ 第 3 层：列查询（每列的匹配条件）→ 第 4 层：临时筛选（工具栏中的搜索、标签、指派人）

让我们逐一了解。

第 1 层：看板范围——谁能看到什么​

这是隐式层。创建看板时，你在私有和共享之间选择。

• 私有看板显示你有权访问的所有任务——你自己的任务加上别人分享给你的任务。这意味着来自多个人的任务可以出现在同一个看板上，让你在一个地方看到所有与你相关的内容。只有你能看到这个看板及其排列方式。
• 共享看板绑定到一个群组。看板只显示属于该群组的任务，群组中的每个人都可以根据权限查看和操作。

你不需要将其配置为"过滤器"——它内建在看板的身份中。但它是决定哪些任务有资格被显示的第一道关卡。

私有看板的模式在多人分别向你分享任务时特别有用。不需要在不同来源之间跳转，你可以在一个看板视图中看到所有内容——自己的工作和队友、协作者或上级分享过来的任务并列呈现。

第 2 层：范围标签——缩窄看板的焦点​

这是真正强大的地方。每个看板都可以设置范围标签（也称为默认标签）——一组标签，作为整个看板的持久过滤器。

当你在看板上设置范围标签时：

1. 只有拥有所有指定标签的任务才会出现在看板上
2. 在看板上创建的新任务会自动获得这些标签，因此从一开始就匹配过滤器

例如，设置了范围标签 sprint-1 的"Sprint 1"看板只会显示带有 sprint-1 标签的任务。你的"所有任务"视图可能显示 40 多个跨所有迭代的任务，但 Sprint 1 看板只显示当前相关的 8 个。

这在设置 → 编辑看板详情 → 范围标签中配置。

关键洞察：范围标签创建了任务池上的命名持久视图。你可以有一个"前端"看板（范围标签：frontend）、一个"Sprint 2"看板（范围标签：sprint-2），它们都从相同的任务中提取。更改任务的标签，它会自动出现在或消失于相关看板中。

第 3 层：列查询——将任务分流到泳道​

在每个看板内，每一列都有自己的匹配条件——一个决定哪些任务落入该列的查询。

最常见的模式是按状态过滤：

• 待办列：Status = 'todo'
• 进行中列：Status = 'in-progress'
• 已完成列：Status = 'done'

但列可以使用任何字段和运算符。你可以创建一个 tags CONTAINS 'urgent' 的列，或 cf.priority >= '3'，或用 AND/OR 逻辑组合多个条件。

强大之处在于：列还有自动动作。当你把任务拖入一列时，其条件会自动应用。将任务拖入"已完成"，状态变为 done。将其拖入按 tags CONTAINS 'reviewed' 过滤的列，标签会自动添加。看板替你处理簿记工作。

第 4 层：临时看板筛选——实时精炼​

顶部工具栏提供三种实时筛选，叠加在所有其他层级之上：

• 搜索：在搜索栏输入，按任务标题跨所有列过滤
• 标签：点击标签按钮选择一个或多个标签——只有拥有所有选定标签的任务才会出现
• 指派人：按任务指派人过滤

这些筛选是临时的——它们不会永久修改看板。关闭标签页就消失了。但它们是 URL 持久化的：筛选状态编码在 URL 查询参数中，如 ?tags=backend&search=API。

这意味着你可以收藏一个筛选视图，或将 URL 分享给队友，展示你正在查看的确切任务子集。

层级如何组合​

以下是一个具体示例，展示四个层级如何协同工作：

1. 看板范围：你打开私有的"Sprint 1"看板
2. 范围标签：看板有范围标签 sprint-1，从 40 多个任务缩窄到 8 个
3. 列查询："进行中"列显示 status = 'in-progress'，缩窄到 3 个任务
4. 临时筛选：你在搜索栏输入"API"，缩窄到 1 个任务——"更新 API 文档"

每个层级独立运作。你可以更改任何一层而不影响其他层。切换范围标签，列仍然正常工作。应用搜索筛选，列查询保持不变。

实用模式​

迭代规划：为每个迭代创建一个看板，以迭代标签作为范围标签。所有迭代共享相同的任务，但每个看板只显示其迭代的内容。

横切视图："前端"看板和"后端"看板都可以显示 Sprint 1 和 Sprint 2 的任务——它们只是使用不同的范围标签。标记为 frontend + sprint-1 的任务同时出现在前端看板和 Sprint 1 看板上。

快速分类：在站会期间使用临时筛选聚焦到特定领域。按指派人筛选查看每个人在做什么，然后清除筛选查看全貌。

复杂列：不使用简单的状态列，创建像"阻塞的后端任务"（status = 'in-progress' AND tags CONTAINS 'blocked' AND tags CONTAINS 'backend'）这样的列，实现专门的工作流视图。

筛选即控制​

这种分层方法遵循 UnDercontrol 的核心设计原则之一：筛选即控制。你不是在菜单中导航来管理什么出现在哪里。看板的范围标签、每列的查询、工具栏的搜索和标签徽章都是可见的、交互式的、可直接编辑的。你可以确切地看到什么在过滤你的视图，并通过一次点击来更改它。

URL 持久化的临时筛选更进一步——你的当前视图状态始终可分享、可收藏，将一次短暂的搜索变成可复用的链接。

问题在于，这些提示词要么藏在你脑子里，要么贴在便利贴上，要么埋在一个没人记得打开的 Notion 文档里。UnDercontrol 的技能系统就是为了解决这个问题。

什么是技能？​

技能是存储在 UnDercontrol 中的具名、可复用提示词模板。每个技能都有一个 slug（例如 refactor-ts、daily-standup、pr-review），一段 markdown 正文，并归属于某个群组。最后这一点很重要——技能的作用域是群组级别的，团队可以共享同一套提示词库，而不需要每个人各自维护一份副本。

你可以通过 Web 界面创建和编辑技能，通过 CLI 管理技能，也可以通过 YAML 文件以声明式方式应用技能。markdown 内容支持各种提示词结构：指令、变量、多步骤工作流，满足你的任何使用场景。

创建技能​

在 Web 编辑器中，创建技能就像写一篇笔记一样简单。给它起个名字、设定一个 slug，然后在 markdown 编辑器里写好提示词内容。保存之后，群组内的所有人立即可以使用。

通过 CLI，你可以像应用任务一样应用技能定义——使用带 YAML frontmatter 的 markdown 文件：

ud apply skill -f pr-review.md

文件格式大致如下：

---
name: pr-review
description: PR Review Checklist
tags:
  - ai
  - development
---

Review the following pull request diff and provide feedback on:
- Logic correctness
- Error handling
- Test coverage
- Naming and readability

这让技能具备了可移植性。你可以将它们纳入 dotfiles 仓库，和其他配置一起做版本管理，然后用一条命令部署到新的 UnDercontrol 实例。

使用技能——ud prompt 命令​

技能真正的价值体现在使用方式上。ud prompt 命令通过 slug 获取技能内容，并将其输出到 stdout。之后你可以将它管道传递到任何地方。

想把技能传入 Claude Code？

claude-code $(ud prompt pr-review)

想在管道中与其他命令组合使用？

ud prompt pr-review | pbcopy

因为输出的就是标准的 stdout，ud prompt 可以与任何从 stdin 读取内容的工具配合使用——Claude Code、其他本地 AI 代理、shell 管道，一切都取决于你的工作流。UnDercontrol 不试图掌控 AI 层，它只是帮你管理好提示词，让你不必为此操心。

内置系统技能​

UnDercontrol 内置了系统技能，在首次启动时自动创建。这些技能是只读的——不会被意外覆盖——既是实用的默认工具，也是了解技能结构的好范例。例如，ud-cli 系统技能提供了 CLI 命令结构的完整参考，使 AI 代理可以直接使用它来操作你的任务。

系统技能在 Web 界面中以锁图标标识，与你的自定义技能并列显示。你可以像调用自定义技能一样，通过 slug 引用它们。

长期管理技能​

技能是 UnDercontrol 中的一等资源，通过 Web 界面和 CLI 均支持完整的增删改查操作。

• ud get skills — 列出群组中的所有技能
• ud describe skill <id> — 查看某个技能的完整内容
• ud delete skill <id> — 删除不再需要的技能
• ud apply skill -f skills/ — 一次性应用整个目录下的技能定义

Web 编辑器适合快速编辑和浏览现有技能，CLI 则更适合自动化、批量更新，以及将提示词库作为代码来管理。

为什么这很重要​

技能背后的理念很简单：好用的提示词值得保留。将它们存储在一个自托管、群组作用域的系统中，意味着它们不会因为某人离职而消失，不会淹没在聊天记录里，也不需要每个人独立摸索出同样的工作流。

这也保护了你的提示词隐私。由于 UnDercontrol 是自托管的，你的提示词库——其中往往沉淀着组织知识、内部流程和特定领域的上下文——始终存放在你自己的基础设施上。

立即开始​

技能功能今天就可以在 UnDercontrol 中使用。如果你已经在运行实例，可以在侧边栏中找到技能页面。如果你是首次部署，自托管指南可以帮助你在大约十分钟内完成部署。

阅读文档或部署自己的实例即可开始。

5秒导航卡顿​

影响最大的修复是看板导航的性能回退——从看板点击任务后，UI会冻结长达5秒。

根本原因很微妙。之前的一个优化提前预加载了 TaskDetail 代码块，让 React.lazy() 立即解析。听起来应该更快，但实际效果相反：没有了短暂的 Suspense 暂停，React 会同步提交路由变更。这意味着要在一帧内卸载整个看板——数百个可排序的项目、拖拽上下文——然后新页面才能开始挂载。

使用标准的懒加载，首次导航会触发短暂的 Suspense 边界。React Router 使用 transition 保持旧页面可见，清理在后台非阻塞地进行。后续导航直接使用缓存的代码块。

修复方案：恢复标准的 React.lazy()，让框架做它该做的事。

后端：修复任务详情的 N+1 查询​

GET /todolist/:id 接口有两个问题：

1. 重复查询 —— enrichItem() 调用 loadRelatedData() 获取笔记和分享链接，但 GetByIDEnriched() 已经加载了这些关联数据。每个请求多跑了2个冗余查询。

2. 关联任务的 N+1 —— 每个关联任务都在循环中单独获取。一个有5个关联任务的任务意味着5条独立的 SELECT 语句。

修复后，任务详情请求总共只需4次查询（主记录 + 笔记 + 分享链接 + 一次批量 WHERE id IN (...) 获取关联任务），之前至少需要7次以上。

使用 IntersectionObserver 延迟加载笔记编辑器​

UnDercontrol 中的任务可以有很多笔记，每个笔记都使用 TipTap 富文本编辑器渲染。每个 TipTap 实例都会创建 DOM 节点、事件监听器和扩展链——一次性初始化10个编辑器的开销很可观。

现在只有前2个笔记立即渲染编辑器。其余的显示轻量级占位符，直到滚动到距视口200px以内才加载。对于有10个笔记的任务，这避免了预先初始化8个编辑器实例。

切换编辑模式不再闪烁​

将笔记从阅读模式切换到编辑模式时，之前会出现短暂的白色闪烁。原因有二：

• TipTap 默认行为会等一帧再渲染内容
• 资源 URL（resource://...）在设置任何内容之前就开始解析，所以编辑器在异步解析完成前是空的

修复方案：在编辑器上设置 immediatelyRender: true，先同步加载原始 markdown 内容。资源图片在后台解析——你立刻看到文字，图片稍后填充。如果内容中完全没有 resource:// URL，则直接跳过处理步骤。

编辑器工具栏修复​

几个较小但恼人的编辑器问题也得到了解决：

• 水平滚动时工具栏冻结 —— 格式化工具栏使用 fixed 定位，向右滚动时停留在 x=0。改为 sticky 定位，随容器滚动。
• 切换按钮滚出视野 —— 长笔记中，编辑/预览切换按钮会滚出可见区域。现在固定在 sticky 操作栏中。
• 移动端操作栏被遮挡 —— 移动端编辑器操作栏被浮动聊天按钮遮住。调高位置以避开遮挡。

中国大陆下载镜像​

对于中国大陆用户，从默认CDN（Cloudflare R2）下载桌面应用可能很慢或不稳定。我们在下载对话框中添加了「中国大陆下载」按钮，从 Bitiful（国内CDN）拉取安装包。下载指标会追踪使用了哪个镜像，方便我们监控使用情况。

发布流程现在会自动将构建产物上传到 R2 和 Bitiful 两个渠道，并清理 Bitiful 上的旧版本（保留最新2个）以管理存储空间。

这些改动已在 v0.65.2 中发布。如果你是自部署用户，拉取最新镜像即可。

最重要的是，你依然在私有化部署的环境中运行。启用多人协作流程，不需要把数据交给任何第三方服务。

群组的工作原理​

UnDercontrol 中的群组是一个共享工作空间。可以把它理解为一个容器，容纳需要共同查看或处理同一内容的人。常见的使用场景包括：家庭成员共同追踪开支预算、小团队协调项目任务，或者两个人共同分摊生活费用。

创建一个群组只需要几秒钟：填写名称、添加描述，你就成为群组的所有者。之后，你可以生成邀请链接，邀请其他人加入。

邀请链接有一定的灵活性。你可以设置有效期，让链接在一天或一周后自动失效——在添加临时协作者时非常实用。你也可以随时撤销任意链接。这是个小细节，但当你在意谁能访问你的工作空间时，它就变得很重要。

基于角色的权限管理​

成员加入群组后，角色决定了他们能做什么。群组层面有三种角色：

• 所有者（Owner） — 对群组拥有完全控制权，包括成员管理、设置以及所有共享内容
• 管理员（Admin） — 可以管理成员和邀请链接，访问所有共享内容
• 成员（Member） — 可以根据每个条目设置的权限级别查看和操作共享资源

除群组角色外，UnDercontrol 还有系统级别的角色：Admin、User 和 Visitor。如果你为小型组织运行一个私有化实例，可以创建自定义角色，为任务、支出、预算、文件等模块分配特定的权限组合。这种级别的访问控制通常只在企业级工具中才有，而在你自己运行的私有化应用中同样可以实现。

以合适的权限共享任务​

将任务共享给群组时，你可以选择权限级别：只读或读写。

只读模式适用于你希望他人了解任务进展但不允许其修改的场景——例如，管理者查看任务列表，或者伴侣需要了解日程安排但不应意外编辑内容。

读写共享则实现了真正的协同工作。群组成员可以更新任务、勾选事项，与你并肩推进。共享任务会出现在每位成员的任务列表中，不会有任何内容被埋没。

附加到共享任务的文件，群组成员可以自动访问，无需单独的文件共享步骤。只要你在任务中附上了 PDF 或图片，所有有权限的人都能看到它。

看板与共享工作流​

共享看板与群组系统直接集成。创建共享看板时，系统会在后台自动创建一个对应的群组。看板创建者成为群组管理员，协作者以成员身份加入。这意味着团队的工作流程始终绑定在一套完整的权限模型上，而不是一个任何人都能偶然访问的开放链接。

实用建议​

在创建第一个群组之前，有几点值得了解：

目前每个用户同一时间只能属于一个群组，因此请提前规划工作空间的结构。如果你同时协调一个工作项目和一个家庭预算，相关人员需要选择加入哪个群组——或者你在同一个群组下通过清晰的任务命名规范来区分两类内容。

从一开始就使用有描述性的群组名称。"家庭预算 2026"或"后端团队 Q2"在三个月后仍然一目了然，远胜于"我的群组"这类含糊的名字。

在邀请临时协作者时，务必为邀请链接设置有效期。这只需要额外两秒钟，却省去了日后手动撤销链接的麻烦。

定期检查成员列表。人员会变动，项目会结束，生活情况也会改变。保持成员列表的及时更新，是任何共享工作空间的基本维护习惯。

立即开始​

如果你已经有一个正在运行的私有化实例，前往"群组"页面创建你的第一个群组。如果你还没有搭建 UnDercontrol，私有化部署指南提供了完整的配置流程——使用 Docker 可以在一小时内完成部署。

协作功能文档涵盖了每项功能的详细说明，包括完整的权限系统，以及群组与预算、资源模块之间的交互方式。

这种实时同步听起来简单，但一旦考虑到重连、离线状态以及长连接的资源开销，复杂度就会迅速上升。以下是 UnDercontrol 的处理方式。

为什么选择 Server-Sent Events​

WebSocket 是实时功能的常见选择，但它有额外的开销——双向连接、自定义协议处理，以及两端更高的实现复杂度。在 UnDercontrol 中，数据更新的流向几乎完全是单向的：服务端向客户端推送变更。这与 Server-Sent Events（SSE）完美契合。SSE 是所有现代浏览器内置支持的标准 HTTP 机制。

SSE 基于普通 HTTP 实现持久连接，浏览器规范内置自动重连能力，除了运行实例所用的 Go 后端外，不需要任何额外基础设施。这让自托管模式保持简洁。

工作原理​

打开 UnDercontrol 时，前端会向后端建立一条 SSE 连接。你的会话被注册到一个按用户维护的连接中枢——该结构追踪你账户下所有活跃连接，涵盖各个标签页、设备以及 Electron 桌面应用。当数据发生变化（任务被更新、支出被记录、文件被重命名），后端会向内部异步事件总线发布一个事件，该事件随即广播到你用户 ID 下注册的所有连接。

这意味着你在手机上记录一笔支出，浏览器标签页会在毫秒内感知到。无需轮询，无需手动刷新。

连接的生命周期经过精心管理。连接最长保持 30 分钟，到期后会自动重连。这可以防止长时间运行的实例出现资源泄漏，同时与有自身超时规则的负载均衡器和反向代理友好兼容。如果连接因任何原因断开——网络抖动、设备休眠唤醒、代理超时——客户端会使用指数退避策略自动重连。初始延迟较短，随后逐步增加，避免短暂离线的设备在恢复上线时瞬间冲击服务器。

客户端的智能缓存更新​

收到事件是一回事，知道如何处理又是另一回事。UnDercontrol 并不会在 SSE 事件到达时盲目地重新拉取全量数据。前端采用差量缓存更新策略：识别哪些内容发生了变化，在本地 Zustand store 中找到对应条目，仅更新该条记录。

例如，某个任务的状态从"进行中"变为"已完成"，事件只携带该任务的最新状态。客户端将其合并到现有缓存中，列表以新状态重新渲染，其余内容保持不变。

这让界面保持流畅，避免了那种因频繁全量请求而带来的突兀刷新感。

乐观更新与服务端协调​

SSE 与 UnDercontrol 的乐观更新模型协同工作。本地做出变更时，界面立即响应——无需等待，无需加载动画。写入操作在后台发送到服务端。成功后，服务端发布一个 SSE 事件，传播到你的其他客户端。若操作失败，本地状态回滚，并显示错误提示。

最终效果是：主设备感觉即时响应，其他设备保持一致。服务端是唯一的数据来源，SSE 是让各端与之保持同步的机制。

你能直接感受到的好处​

在两个浏览器标签页中打开同一个 UnDercontrol 实例，在其中一个标签页做出修改，另一个标签页无需任何操作即可看到变更。当你在一块屏幕上查看预算概览、在另一块屏幕上记录交易时，这一特性尤为实用。

Electron 桌面应用同样参与这套同步机制。通过 CLI 或 Chrome 扩展所做的变更，也会通过 SSE 传播到当前打开的所有端。整个多平台体验的基础，正是这一层同步机制的可靠运行。

亲自体验​

这一切运行在你自己的硬件上。没有云依赖，没有第三方同步服务，数据始终在你的掌控之中。SSE 端点是标准 UnDercontrol 后端的一部分。

如果你还没有部署 UnDercontrol，自部署指南介绍了如何在几分钟内通过 Docker 完成启动。如果你已经在运行实例，同步功能已经处于激活状态——打开第二个标签页，亲眼看看效果。

部署说明和配置选项请参阅文档。

kubectl 风格的命令，因为它好用​

CLI 使用与 kubectl 相同的动词-资源模式，这种模式让无数工程师觉得上手自然。你可以 get、describe、apply 和 delete 资源，无需建立新的心智模型。

# 列出所有任务
ud get task

# 查看任务完整详情（支持短 ID 前缀）
ud describe task 3de9f82b

# 从 markdown 文件创建或更新任务
ud apply -f task.md

# 删除任务
ud delete task abc123

apply 命令值得重点介绍。你的任务就是一个带有 YAML frontmatter 的 markdown 文件。如果文件中有 id 字段，则更新已有任务；没有 id，则新建任务。这使得批量更新、脚本化工作流以及版本控制的任务定义变得简单直接。

echo '---
title: Write release notes
status: in-progress
tags:
  - release
deadline: 2026-04-10
---

Draft the changelog and update the docs site.' | ud apply -f -

真正能过滤的查询语法​

ud task query 提供了一种类 SQL 的过滤语言，用于查询你的任务。当任务数量多到"翻列表"不再是可行策略时，它就派上用场了。

# 本周截止的任务
ud task query "deadline BETWEEN 'today' AND '+7d'"

# 标记为 urgent 的进行中任务
ud task query "(status = 'todo' OR status = 'in-progress') AND tags = 'urgent'"

# 标题搜索
ud task query "title ILIKE '%api%'"

如果你不想考虑语法，ud task nlquery 支持直接输入自然语言，并通过 AI 将其转译为查询：

ud task nlquery "show me overdue tasks"
ud task nlquery "tasks tagged with work that are not done"

两个命令都支持 --sort、--order 和 --limit 参数，便于分页和排序，可以干净地组合进脚本或 shell 别名中。

用笔记记录进度​

每个任务都支持笔记——简短的自由格式条目，充当持续更新的进度日志。这对于记录你实际做了什么很有用，而不只是最终状态。

ud task note add 3de9f82b "Finished the backend changes, opening PR now"
ud task note ls 3de9f82b

笔记也让 CLI 天然适合 AI 智能体工作流。智能体可以从计划文件创建任务，在每个步骤追加进度笔记，最后标记任务完成——全程无需打开浏览器。团队的其他成员可以在 UnDercontrol Web 界面或桌面应用中看到完整的历史记录。这种交接方式轻量、实用，真正跑得通。

需要可视化时，用交互式 TUI​

不带任何参数运行 ud，会打开终端 UI——一个支持键盘操作的看板式界面，带有 vim 风格的按键绑定。

文件选择器是个亮点。按 f，在当前目录中模糊搜索 markdown 文件，它就会变成一个任务——第一行作为标题，其余内容作为描述。如果你习惯在项目仓库中用 markdown 记笔记，并想把它们纳入任务追踪，这个功能非常实用。

多上下文支持多个服务器​

如果你在多个环境中自托管 UnDercontrol——个人、工作、测试实例——上下文系统的处理方式与 kubectl 完全相同。

ud config set-context work --api-url https://ud.company.com
ud login --context work

# 单次命令使用不同上下文
UD_CONTEXT=personal ud get task

配置文件位于 ~/.config/ud/config.yaml。你也可以完全通过环境变量（UD_API_URL、UD_API_KEY、UD_TOKEN）驱动 CLI，无需修改配置文件，在 CI 流水线中同样可用。

快速开始​

通过 npm、Homebrew 或一行 curl 命令安装：

npm install -g @oatnil/ud
# 或
brew install oatnil-top/ud/ud
# 或
curl -fsSL https://get.oatnil.com/ud | bash

然后指向你的 UnDercontrol 实例：

ud login

完整的命令参考——包括文件附件、多上下文认证和高级查询语法——请查阅 CLI Reference 文档。如果你还没有运行 UnDercontrol，自托管指南 介绍了如何在几分钟内用 Docker 启动一个服务器。

什么是 Context​

ud 中的 context 是一个具名配置，包含：API 端点、凭据（交互式登录的会话 token 或静态 API key），以及显示用户名。Context 存储在本地的 ~/.config/ud/config.yaml 中，不会被发送到任何地方。

一个典型的 context 列表：

$ ud config get-contexts
CURRENT  NAME      API URL                           USER
*        personal  https://ud.home.example.com       me@example.com
         work      https://ud.corp.example.com       me@corp.com
         local     http://localhost:4000              admin@oatnil.com

星号标记当前激活的 context。你执行的每一条 ud 命令都会使用该 context，除非主动覆盖。

创建你的第一个 Context​

最快的方式是通过登录创建，-n 参数一步完成命名：

# 登录并创建具名 context
ud login --api-url https://ud.home.example.com -n personal

# 再添加一个工作用的
ud login --api-url https://ud.corp.example.com -n work

系统会提示输入用户名和密码，完成认证后将 token 保存到对应 context。如果需要为 CI/CD 或无界面环境配置 context，使用 config set-context 配合 API key：

ud config set-context ci --api-url https://ud.corp.example.com --api-key ak_xxxxx

在 UnDercontrol Web 界面的 Settings 中生成 API key，运行时无需浏览器交互。

切换 Context​

切换当前 context：

ud config use-context work

就这样。接下来执行的 ud get task 或 ud describe task 都会访问工作服务器。切回来同样简单：

ud config use-context personal

在 TUI 中，命令模式下输入 :ctx 可打开交互式 context 选择器——方向键导航，Enter 确认。和 kubectx 一样的操作习惯。

临时覆盖​

有时只想为某一条命令指定实例，而不想永久切换。--context 参数和环境变量可以做到：

# 为单条命令使用指定 context
ud --context work get task

# 或通过环境变量
UD_CONTEXT=work ud get task

# 直接指向任意端点，无需预先创建 context
UD_API_URL=http://localhost:4000 UD_API_KEY=dev-key ud get task

优先级顺序：--context 参数 > UD_CONTEXT 环境变量 > 配置文件中的 current-context。这使得脚本可以明确指定目标实例，不依赖机器上当前激活的 context。

各 Context 独立认证​

每个 context 维护独立的认证状态，互不影响。工作 context 的 token 过期了，只需重新登录该 context：

ud login --context work

个人和本地 context 完全不受影响。

查看配置​

# 显示当前激活的 context
ud config current-context

# 列出所有 context
ud config get-contexts

# 查看完整配置（token 会被脱敏）
ud config view

管理 Context​

# 重命名 context
ud config rename-context old-name new-name

# 删除不再需要的 context
ud config delete-context staging

如果删除了当前激活的 context，ud 会自动切换到第一个可用的 context。

对自托管用户的意义​

UnDercontrol 的核心理念是：你的数据属于你自己。自托管是第一优先级的使用方式。context 系统正是这一理念的体现——它假设你可能同时运行多个实例，希望无缝切换，并在不牺牲安全性的前提下实现自动化。

无论你是管理个人实例、家庭服务器和工作部署，还是在本地开发和生产环境之间并行工作，context 都能提供清晰的心智模型和统一的 CLI 操作界面。

开始使用​

通过 Homebrew 安装 ud CLI（brew install oatnil/ud/ud）或从发布页面下载二进制文件。创建你的第一个 context：

ud login --api-url https://your-instance.example.com -n myserver

完整文档：CLI 认证与 Context。

本文介绍 UnDercontrol 内置的查询系统：一套类 SQL 语法，可在 Web 界面、CLI、自定义视图、看板以及已保存查询中统一使用。一旦上手，你会发现自己几乎每天都在用它。

查询语法​

这套语法在设计上与 SQL WHERE 子句非常接近。如果你写过数据库查询，会立刻感到熟悉；如果没有，基础部分大约五分钟就能掌握。

一个简单的查询如下：

status = 'todo' AND deadline <= 'today'

这会找出所有状态为待办、且截止日期在今天或更早的任务——也就是已逾期的待办项。

你可以在此基础上加入标签、文本搜索、日期范围和自定义字段：

(deadline <= 'today' OR tags = 'urgent') AND status != 'done' AND status != 'archived'

这是一个可靠的"当前需要处理"查询。将它保存为已保存查询（下文详述），就有了一个一键直达的紧急任务列表。

日期时间表达式​

语法中较为实用的一部分是相对日期支持。你不需要写死具体日期，而是使用 '-7d'、'+1w' 或直接写 'today' 这样的表达式。

-- 过去一周内创建的任务
created_at >= '-7d'

-- 未来一个月内到期
deadline BETWEEN 'today' AND '+1m'

-- 今天有更新
updated_at >= 'today'

支持的时间单位包括天（d）、周（w）、月（m）和年（y），+ 表示未来，- 表示过去。当你需要固定日期时，2025-06-01 这样的标准 ISO 8601 格式同样适用。

文本搜索与自定义字段​

文本搜索使用 LIKE（区分大小写）和 ILIKE（不区分大小写），以 % 作为通配符：

title ILIKE '%api%'

自定义字段需加上 cf. 前缀：

cf.priority > 3 AND cf.department = 'engineering'

自定义字段根据其类型支持完整的比较运算符——数字、文本、下拉选项、复选框和用户引用均可使用。

自然语言查询​

熟悉语法后，手写查询其实很快。但如果你更倾向于直接描述需求，AI 集成功能可以自动完成转换。

在 Web 界面中，打开任务页面的 AI Chat 面板，输入类似"显示带有 work 标签的逾期任务"，AI 会自动生成结构化查询并执行。

在 CLI 中，使用 ud task nlquery：

ud task nlquery "tasks I need to finish this week"
ud task nlquery "high priority engineering items with no deadline"

如果想少打几个字，nl 别名同样有效。此功能需要配置 AI 提供商，但一旦设置完成，它能处理相当自然的描述方式。

已保存查询​

这是查询系统真正在日常使用中发挥价值的地方。已保存查询允许你为任意查询命名并存储，之后只需在侧边栏点击一下即可执行。

以下几个查询值得立即配置：

你可以将常用查询置顶，通过拖拽调整顺序，并随时编辑。点击已保存查询后，结果会在当前页面内展开，无需跳转。

在 CLI 中使用查询​

CLI 通过 ud task query 支持相同的查询语法：

ud task query "status = 'todo'" --sort deadline --order asc
ud task query "(status = 'todo' OR status = 'in-progress') AND tags = 'work'"

分页（--page、--limit）和排序（--sort、--order）参数均可使用。这使得将查询结果导入其他工具或在 shell 脚本中调用查询变得非常方便。

开始使用​

完整的查询语法参考文档请见查询语法文档，包含所有运算符、日期时间表达式格式，以及一套可直接复用和改写的实用示例。

如果你还没有部署 UnDercontrol，自托管指南介绍了如何通过 Docker 完成部署。你的数据始终保存在自己的基础设施上——这正是它的核心价值所在。

下面介绍资源管理系统在实际使用中的工作方式。

按你的工作习惯上传​

将文件导入 UnDercontrol 不应该每次都要打开文件选择器绕一圈。目前支持三种主要上传方式：

拖放上传 — 打开资源页面，或在任务、支出的附件面板中，直接将文件拖入即可。支持单文件和批量上传。

剪贴板粘贴 — 按下 Ctrl+V，剪贴板中的文件会立即上传。这对截图尤其方便。对着收据或界面 bug 截个图，切换到 UnDercontrol，粘贴。无需先保存到磁盘。

CLI 上传 — 如果你习惯在终端工作，ud CLI 可以直接处理上传：

ud upload resource ./receipt.png --entity-type expense --entity-id exp-456

这在自动化工作流中很有用，比如将导出的报告自动附加到每月预算审查任务中。

一次附加，随处引用​

同一个资源可以关联到多个条目。如果有一份合同 PDF 同时与某个预算和某个任务相关，你可以将它分别附加到两者——无需重复文件，也无需翻找文件夹。当任务标记为完成后，可以取消该文件与任务的关联，同时保留它与预算的附加关系。

检查器面板会清晰显示某个文件附加到了哪些条目，让你随时掌握文件的引用情况。

快速找到所需文件​

资源页面提供所有已上传文件的完整概览，并内置筛选功能。你可以按文件类型、附加的实体类型（任务、支出、预算、账户）或日期范围进行筛选。对于图片，图库视图会显示缩略图，让你无需逐一打开便能快速浏览一批收据或截图。

检查器还会显示照片的 EXIF 元数据——如果你需要确认照片的拍摄时间或地点，这非常实用。

存储：本地或 S3​

由于 UnDercontrol 是自托管的，你可以完全掌控文件的存储位置。默认使用本地磁盘存储，对于运行在家庭服务器或 VPS 上的个人使用场景完全够用。对于更大规模的部署或远程访问需求，可以配置兼容 S3 的对象存储——AWS S3、Backblaze B2、MinIO，用你已有的方案即可。

关键一点：你的文件不会经过任何第三方服务，直接从浏览器传输到你自己的服务器。

存储限制可自行配置。普通用户默认获得 1 GB 空间，单文件上限 10 MB。管理员则不受限制。

内置 Drawio 图表​

如果你的工作流程涉及系统图、流程图或架构草图，UnDercontrol 内置了 drawio 支持。你可以直接在应用内创建和编辑图表，无需导出为 PNG，也无需切换到其他工具再重新上传。图表文件作为资源附加在对应的任务或笔记上。

AI 识别图片内容​

对于收据和文档扫描件，AI 集成功能值得了解。你可以打开一张图片资源，让 AI 从中提取信息——比如收据上的明细条目、扫描表格中的文字。这与支出追踪工作流天然契合：拍一张收据照片，附加到支出条目，让 AI 自动提取金额和商家名称。

日常使用场景​

举一个实际的例子：你在追踪一个自由职业项目。有一个"审查客户合同"的任务，你将合同 PDF 附加到该任务。随后，你为项目采购的软件记录了一笔支出，并将发票附加到该支出条目。这两个文件都会出现在资源页面中——你可以按实体类型筛选，只查看支出附件，也可以一起查看，对整个项目进行完整的文件审计。

所有内容集中在一处，无需外部文件托管，也无需翻找邮件记录。

开始使用​

如果你已经在运行 UnDercontrol，资源页面可以在主导航中找到。如果你正在评估是否自托管，部署指南 涵盖了实例搭建的全部流程，包括存储配置。

资源管理文档 提供了 CLI 命令、存储配置和实体附加选项的完整参考。

UnDercontrol 从一开始就是为了彻底避免这种情况而设计的。它支持自托管，意味着你在自己掌控的基础设施上运行它，数据存放在你指定的地方。

用 Docker Compose 几分钟内完成部署​

对大多数人来说，Docker Compose 是最快的启动方式。一个 docker-compose.yml 文件就能拉取后端和前端镜像，将它们连接起来，几分钟内就能在你的服务器或本地机器上运行 UnDercontrol。

一个最简配置大致如下：一个将数据目录挂载为卷的后端服务、一个指向它的前端服务，以及可选的 Caddy 或 Nginx 反向代理。对于单用户或小家庭部署来说，这就是全部了。不需要托管云账户，不需要第三方服务的 API 密钥，数据不会离开你的网络。

Docker 镜像设计得轻量且行为可预期。它不会回连服务器，初次拉取后无需网络连接，所有内容都存储在你配置的路径下。

面向团队和进阶用户的 Kubernetes 部署​

如果你在使用 Kubernetes 搭建家庭实验室，或者希望获得正式编排带来的可靠性，UnDercontrol 同样提供了 Kubernetes 清单文件。你可以使用标准的 Deployment 和 Service、用于数据持久化的 PersistentVolumeClaim，以及用于环境配置的 ConfigMap。

这对于为小型团队——家庭、朋友群组、小公司——部署 UnDercontrol 尤为实用。你可以设置合理的资源限制、滚动更新，并在需要时独立扩展后端。Kubernetes 还让添加 Ingress 规则、TLS 终止和命名空间级别的隔离变得非常简单。

SQLite 还是 PostgreSQL——按需选择​

UnDercontrol 在数据库选择上给了你充分的灵活性。对于单用户或少量用户的场景，SQLite 是默认选项，而且表现非常出色。无需管理数据库服务器，无需配置连接池，备份就是复制一个文件那么简单。在这种场景下，SQLite 的能力出乎意料地强，运维负担几乎为零。

当你需要更多能力时——并发用户、大规模数据集、与现有数据库基础设施集成——切换到 PostgreSQL 只需修改环境变量并运行迁移。两种后端的 Schema 完全一致，不需要重新设计任何东西，只需将应用指向你的 Postgres 实例即可。

这种灵活性很重要，因为你的需求会随时间变化。从 SQLite 起步、之后再迁移是一条官方支持的路径，而不是事后才想到的补丁。

数据完全自主意味着什么​

自托管意味着你的任务、财务记录、上传的文件以及 AI 对话历史，全部存储在你掌控的存储介质上。想迁移到其他服务器，只需复制数据目录并更新部署配置。想备份所有内容，备份那个目录就行。即使你决定彻底停用 UnDercontrol，数据依然在那里，格式可读。

不需要注销账户，不需要提交工单，不需要等待期。数据属于你，因为它从一开始就在你的机器上。

这也意味着你控制着访问权限。在私有网络或 VPN 后面运行 UnDercontrol，你的财务数据就不会触及公共互联网，除非你主动将其路由出去。对于追踪详细预算或敏感个人信息的用户来说，这绝非小事。

无供应商锁定，由设计保证​

后端 API 有完整文档，且对外开放。CLI 使用 kubectl 风格的命令，与 Web 应用调用的是同一套 API。你可以编写脚本调用它、与其他工具集成，或者构建自己的客户端。任务和笔记的格式设计上注重可移植性。

我们的目标始终是：让你持续使用它，是因为它真的有用——而不是因为迁移走的代价太高、懒得折腾。

开始使用​

部署指南详细介绍了 Docker Compose 配置、Kubernetes 清单、数据库配置以及备份策略。如果你有一台服务器或闲置的机器，今天就能跑起来一个可用实例。

查阅自托管文档开始部署，或者在 GitHub 上提 Issue，如果配置过程中有任何地方不符合预期。

UnDercontrol 的 AI 助手正是为了消除这种摩擦而设计的。下面介绍它在实际使用中的具体表现。

拍张收据，跳过表单​

最直接实用的 AI 功能是收据扫描。新建支出时，你可以上传一张照片——拖拽、从剪贴板粘贴或选择文件均可。AI 会读取图片，自动提取金额、货币、商家名称、日期，并给出一个建议分类。

它能处理揉皱的收据、倾斜的角度和不同格式的小票，表现相当稳定。有一个实用技巧值得记住：光线比摆放角度更重要。在充足光线下拍摄的清晰照片，几乎都能正确解析；而在昏暗餐厅里拍的模糊照片，则很可能识别失败。

你也可以一次批量上传多张收据，非常适合出差回来或积压了一周账单的情况。

文字输入，快速记账​

并不是每笔支出都有收据。对于这类情况，直接用自然语言描述就好：

• "面馆吃午饭，18 美元"
• "从机场打车回家，34 欧元"
• "Figma 月订阅，15 美元"

AI 会将描述解析成填好各字段的结构化支出记录，比逐个点选表单快得多，在手机上尤其明显。

同样的方式也适用于任务。不需要填写任务表单，直接描述要做的事：

• "跟会计确认一季度税务的后续事宜"
• "在周五之前给 Sarah 买生日礼物"
• "调研自托管备份方案"

UnDercontrol 会根据描述生成结构化任务，包括标题、可推断的相关标签以及描述内容。你检查一遍，改掉不准确的地方，保存即可。

自然语言查询​

当系统中积累了一定数量的任务和支出后，你可以用日常语言直接提问。比如"显示逾期任务"或"本周有什么待办"，这些问题会被转化为查询条件并返回匹配结果。这不是什么魔法——对于简单直接的问题效果最好——但它确实省去了记忆 UnDercontrol 查询语法的麻烦。

Apple Shortcuts 集成​

在 iOS 和 macOS 上，UnDercontrol 提供了 Apple Shortcuts，可以将 AI 功能接入系统的分享菜单和快捷指令自动化。实际好处就是：在设备上任意位置，一键即可完成录入。

最实用的一个快捷指令：用相机拍一张照片，运行该指令，收据就会作为支出记录保存下来，全程无需打开 app。你也可以分享文字内容——复制的邮件片段、一条消息、一条备忘录——直接从中创建任务。

快捷指令可在你的 UnDercontrol 实例的订阅/下载页面获取。

自带 AI 服务商​

UnDercontrol 不绑定任何单一 AI 后端。你可以接入自己的 API key，来源可以是 OpenAI、Anthropic，或任何兼容 OpenAI 接口的服务。如果你希望所有计算都在本地完成、不依赖任何外部 API，也可以通过 Ollama 或 LM Studio 接入本地模型。

配置过程很简单：进入个人资料设置，找到 AI Providers 部分，添加服务商和 API key，选择模型，测试连接。你可以添加多个服务商并设置优先级，列表中第一个可用的服务商会被实际调用。

如果你运行的是多人共享的 UnDercontrol 实例，管理员还可以配置系统级服务商，供所有用户使用——对于家庭服务器或小型团队来说非常方便。

使用注意事项​

AI 提取的准确率很高，但并非完美。保存之前，务必快速检查一下解析结果，尤其是金额和日期字段。如果收据上的合计金额在视觉上与小计行很接近，解析器可能会混淆。花两秒钟确认一下，远比事后追查一笔记错的账要省力得多。

对于文字输入，描述越具体，结果越准确。"咖啡"比"登机前在机场喝的咖啡，6.50 美元"更难分类。

开始使用​

如果你已经在运行 UnDercontrol，前往个人资料设置，添加一个 AI 服务商。下次记录支出时，试着上传一张收据——工作流上的差异会立刻显现出来。

如果你还没有部署 UnDercontrol，自托管指南涵盖了从 Docker 部署到配置的全部内容：UnDercontrol 文档。

下面来看看 UnDercontrol 的预算追踪功能在实际使用中是如何运作的。

创建真正符合实际的预算​

在 UnDercontrol 中创建预算，从基本信息开始：名称、初始金额、开始日期和周期频率。支持按周、按月、按季度或按年——选择最符合你日常思维习惯的方式即可。

但真正的强大之处在于预算计划。UnDercontrol 不会把你锁定在一个固定金额里，而是允许你随时添加新的计划。比如你年初设定了每月 500 美元的餐饮预算，到了三月物价上涨，需要调整为 650 美元，直接添加一个更新金额的新计划即可。系统会自动处理计算逻辑——根据每个计划的生效时间段来汇总金额——历史数据保持准确，当前视图也始终是最新状态。

一次性调整可以覆盖周期计划无法处理的情况：收到意外退款、项目奖金分配、修正数据录入错误……每笔调整都会记录金额、日期和可选的备注说明。几个月后对账时，你会庆幸当初留下了那些备注。

记录消费并关联到预算​

在 UnDercontrol 中，消费记录是一等公民。添加一笔支出时，你可以将其关联到某个具体的预算。这个关联关系正是"预算 vs 实际"视图的数据基础——支出金额会汇总到该预算的已花费总额中，并显示在对应预算的账目明细里。

这种设计也允许存在不关联任何预算的支出记录，这是有意为之的。并非每笔交易都需要立刻分类。你可以先记下来，之后再回来关联，等到合适的时机处理即可。

预算详情页将所有信息整合在一起：顶部概览区一目了然地展示总分配额、已花费金额和剩余余额；支出趋势图则以 7 天、30 天或 90 天为维度，将实际支出与预算线并排呈现。如果你在追踪月度餐饮预算，图表显示在第 22 天就已突破分配上限，这个信号足够清晰，无需任何心算。

多账户支持与全局视图​

UnDercontrol 的账户系统支持同时追踪多个资金来源——活期账户、储蓄账户、独立的业务账户，无论你的财务结构如何都能适配。预算账户会汇入整体可用余额，因此在规划新预算时，你看到的是真实数字，而不是凭空估算。

当你管理小团队或家庭财务时，这一功能尤为实用。协作系统允许你与其他用户共享预算，多人可以同时向同一个预算记录支出，并看到相同的实时汇总数据。不再需要来回发送电子表格，也不用手动合并两套独立的记录系统。

轻松掌握支出，无需繁琐操作​

预算列表页的设计让你可以一眼掌握全局：进度条、已花费和剩余金额，以及汇总所有预算总额的侧边栏。搜索功能帮助你快速定位特定预算。"显示隐藏项"开关则适用于那些想归档但不想删除的预算。

隐私模式值得一提：开启后，界面上所有金额数字都会被隐藏。在会议中共享屏幕时非常实用——你不需要向同事解释自己的餐饮预算。

在数据导出与可移植性方面，UnDercontrol 支持将消费历史以结构化格式导出。由于是自托管部署，你还可以直接访问底层数据库，随时执行自定义查询或将数据接入其他工具。

自托管，由你做主​

上述所有功能都运行在你自己的服务器上。你的财务数据不会经过任何第三方的基础设施。备份策略、访问权限、数据保留周期——一切都由你决定。对于那些在第三方应用里输入银行流水时感到不安的人来说，这一点至关重要。

如果你想开始上手，自部署指南 提供了使用 Docker 搭建 UnDercontrol 的完整流程。预算功能文档 则详细介绍了每项功能，包括预算总额的计算方式以及如何有效使用调整记录。

创建你的第一个预算，关联几笔支出，一周后再来看看。支出趋势图告诉你的，会比任何电子表格都多。

看板是视图，而非数据孤岛​

在了解其他内容之前，这一点值得先搞清楚。在 UnderControl 中，看板是任务系统之上的一层可视化界面。当你把一张卡片从"待办"拖到"进行中"时，你不只是在移动看板上的一张卡——你是在更新该任务的状态。这个变更会立即反映在任务列表、CLI 查询结果以及所有其他地方。不存在同步问题，因为始终只有一个数据来源。

这意味着你可以在看板视图和列表视图之间自由切换，完全不用担心数据不一致。

快速上手：全部任务看板​

每个账户都内置了一个"全部任务"看板。打开它，你会看到所有任务按六个列排列：待办、进行中、待定、已搁置、已完成和已归档。这个看板无法删除，且始终显示在最前面。

这是一个很好的起点。把一个任务从"待办"拖到"进行中"，状态会立即更新。这就是基本的操作逻辑——卡片的位置决定任务状态，而非反过来。

基于查询条件的自定义列​

真正有意思的地方在于你创建自己的看板时。每一列都由一个过滤条件定义——本质上是一个查询，决定哪些任务属于这一列。"被阻塞"列可以过滤出打了 blocked 标签的任务，"本周到期"列可以按截止日期过滤。列不只是一个标签，而是一个实时查询。

当你为列配置操作后，移动卡片就变成了一个触发器。把任务拖入"已完成"列，它会自动标记为完成；把任务移入"待审核"列，可以一次性完成打标签和指派操作。你来定义拖入某一列意味着什么，看板负责处理后续的数据更新。

这对多步骤工作流非常实用。如果你的流程是草稿 -> 审核 -> 待发布 -> 完成，你可以完整地建模这个流程——每次列间转换都会对底层任务数据做出正确的变更。

私有看板与共享看板​

私有看板只对你可见。你可以按需创建任意数量——为某个副业项目创建一个，为每周计划创建一个，为家装项目创建一个。它们都从你的完整任务池中拉取数据，并通过你配置的列条件进行过滤。

共享看板的工作方式有所不同。当你把看板共享给一个群组时，该看板只显示属于该群组的任务。群组中的每个人都可以看到这个看板，并根据各自的权限移动卡片。这是一个清晰的模型：看板的数据范围由群组决定，访问权限通过群组成员身份控制。

这让共享看板对小团队来说非常实用。为一个两三人的团队搭建一个迭代看板，让所有人都能看到哪些任务在进行、哪些被阻塞，配置简单，也不需要任何额外工具。

几种值得尝试的工作流模式​

如果你还不确定如何规划看板结构，以下几种方式效果都不错：

基于状态的看板与默认设置类似——待办、进行中、已完成。结构简单、维护成本低，适合个人使用。

基于时间的看板使用积压、本周、今日、已完成这样的列结构。过滤条件基于截止日期或自定义字段，而非任务状态。把任务拖入"今日"列可以自动更新优先级字段。

带共享访问的项目看板利用群组功能将任务范围限定在特定项目内。列的划分对应团队实际的工作流阶段，所有人在同一个看板上协作。

所有内容保持连通​

由于看板构建在与 UnderControl 其他功能相同的任务和标签系统之上，它能与其他功能自然地组合使用。你在任务过滤器中使用的标签同样可以作为列的条件。你为项目创建的自定义字段可以驱动列的归属，并通过列操作自动更新。看板不是一个独立模块，而是任务系统的可视化呈现。

如果你想了解它如何融入整体配置，看板文档详细介绍了列配置、自动操作和共享功能。如果你还没有运行 UnderControl，自托管部署指南可以帮你在一小时内完成搭建——你的数据始终保存在自己的基础设施上。

Here's a practical walkthrough of how the task system works.

Six Statuses That Actually Mean Something​

Tasks in UnderControl move through six statuses: Todo, In Progress, Pending, Done, Stale, and Archived.

The distinction between Pending and Stale is one I find genuinely useful. Pending means you're deliberately waiting — on a reply, a dependency, a decision. Stale means the task just hasn't been touched in a while. That difference matters when you're doing a weekly review and trying to figure out what to act on versus what to clean up.

Pick the View That Matches Your Mental Model​

Different work calls for different views. UnderControl gives you seven:

• List — The default. Fast, filterable, keyboard-friendly.
• Kanban — Drag cards between status columns. Good for sprint-style work.
• Calendar — Tasks plotted by deadline. Useful before a busy week.
• Tree — Hierarchical view of parent and child tasks. Great for projects with nested sub-tasks.
• Graph — A node-link diagram of all your bidirectional task relationships. Looks cool, but also genuinely useful for spotting how things connect.
• Mindmap — Freeform brainstorming layout.
• Trash — Review and restore deleted tasks.

Switching between views doesn't change your data — it's the same tasks, just rendered differently. The Graph view in particular is worth trying if you use linked tasks heavily.

Bidirectional Linking​

You can link any two tasks together, and the connection is bidirectional — follow it from either side. Over time, this turns your task list into something closer to a knowledge graph. The Graph view is where this becomes visible: nodes are tasks, edges are links, and you can see clusters form around related work.

Derived tasks (parent-child relationships) work differently. When you create a task from an existing one, the child inherits context from the parent and links back to it automatically. This is the right pattern for breaking down a large project into concrete steps.

Markdown Notes with Edit History​

Every task has a notes section. Notes support full markdown — headers, code blocks, lists, links. More importantly, every note keeps a full edit history. If you wrote something, changed your mind, and want to go back, you can revert to any previous version.

I use notes for things like decision logs, blockers, and meeting summaries attached to a task. It keeps everything in one place instead of scattered across documents and chat threads.

Filtering and Queries​

The quick filters cover the common cases: filter by status, tags, or deadline range (overdue, today, this week, and so on). For more specific needs, there's a structured query language:

status = 'pending' AND tag:work = 'true'

If you don't want to write the query yourself, the AI assistant accepts plain English — something like "show me overdue tasks tagged with client work" — and translates it into a filter.

File Attachments and Sharing​

Attach any file to a task — images, PDFs, diagrams, exported reports. The attachments live on your server, under your control.

For sharing, you can generate a public link to a specific task with an optional expiration date. Or share with a group and set whether they get read or read-write access.

The CLI Is a First-Class Interface​

If you work in a terminal, ud gives you the full task API from the command line:

ud task list
ud task create "Review Q2 metrics"
ud task done <id>
ud task query "status = 'todo' AND deadline < '2026-05-01'"
ud task apply -f task.md

The apply command is particularly useful — you can write a task in a markdown file and push it to UnderControl, which fits nicely into scripting and automation workflows. The CLI follows kubectl-style conventions, so if you spend time in Kubernetes or similar tools, the patterns feel familiar.

Recurring Tasks and Check-ins​

For repeating work, recurring tasks generate new task instances on a schedule — daily standups, weekly reviews, monthly reports. You can use presets or write a custom CRON expression.

Check-ins are a lighter-weight alternative for habit tracking: each check-in increments a counter and records a timestamp, giving you a simple log of consistency without the overhead of a full task lifecycle.

Try It Yourself​

All of this runs on your own infrastructure. No data leaves your server, no subscriptions, no vendor lock-in.

The full task management documentation is at undercontrol.dev/docs/tasks, and the self-hosting guide covers deployment with Docker or the prebuilt binaries. If you run into anything, the GitHub repo is the right place to file issues or ask questions.