mutsumi 命令未找到
Section titled “mutsumi 命令未找到”确保 ~/.local/bin 在你的 PATH 中：
export PATH="$HOME/.local/bin:$PATH"将上面这行添加到你的 shell 配置文件中以持久化：
- Bash:
~/.bashrc - Zsh:
~/.zshrc - Fish:
~/.config/fish/config.fish（使用set -gx PATH $HOME/.local/bin $PATH）
需要预先安装 Python 吗？
Section titled “需要预先安装 Python 吗？”使用 uv tool install 时不需要。uv 会自动管理隔离的 Python 环境。
支持 Windows 吗？
Section titled “支持 Windows 吗？”Mutsumi 原生支持 Windows、macOS 和 Linux。Windows 用户可以直接用 Windows Terminal 分屏，无需 WSL。如果你更喜欢 tmux 的会话管理，也可以选择通过 WSL 使用。
如何升级到最新版本？
Section titled “如何升级到最新版本？”uv tool install --force git+https://github.com/ywh555hhh/Mutsumi.gitTUI 相关
Section titled “TUI 相关”TUI 显示 “Nothing here yet” 但 mutsumi.json 有任务
Section titled “TUI 显示 “Nothing here yet” 但 mutsumi.json 有任务”检查你在哪个标签页上 — 任务按 scope 过滤。按 1 查看 Today，2 查看 Week，3 查看 Month，4 查看 Inbox。
如果任务没有 scope 字段也没有 due_date，它们会出现在 Inbox 标签中。
Agent 修改后 TUI 没有更新
Section titled “Agent 修改后 TUI 没有更新”- 确保 Agent 写入的是 Mutsumi 正在监视的同一个
mutsumi.json路径 - 运行
mutsumi validate检查 JSON 是否有效 - 确认 Agent 写入的是完整文件而非部分内容
TUI 显示错误横幅
Section titled “TUI 显示错误横幅”这通常意味着 mutsumi.json 格式有误。TUI 会保留上次有效状态的任务列表。运行以下命令查看详细错误：
mutsumi validate终端显示乱码
Section titled “终端显示乱码”确保你的终端支持 Unicode 并使用支持的字体。推荐使用：
- iTerm2 (macOS)
- Alacritty
- Kitty
- WezTerm
如何退出 Mutsumi？
Section titled “如何退出 Mutsumi？”- vim 预设：按 q
- emacs 预设：按 Ctrl+q
- arrow 预设：按 q
主题/快捷键配置不生效
Section titled “主题/快捷键配置不生效”- 运行
mutsumi config --show确认配置已加载 - 确认配置文件路径：
mutsumi config --path - 检查 TOML 语法是否正确
配置文件在哪里？
Section titled “配置文件在哪里？”mutsumi config --path通常在：
- Linux:
~/.mutsumi/config.toml - macOS:
~/.mutsumi/config.toml或~/Library/Application Support/mutsumi/config.toml
可以不用配置文件吗？
Section titled “可以不用配置文件吗？”可以。Mutsumi 在没有配置文件时使用合理的默认值正常工作：
- 主题：
monochrome-zen - 快捷键：
arrows - 语言：
en
Agent 集成相关
Section titled “Agent 集成相关”Mutsumi 支持哪些 Agent？
Section titled “Mutsumi 支持哪些 Agent？”Mutsumi 是 Agent 无关的。任何能读写 JSON 的程序都可以作为 Controller：
| Agent | 集成方式 |
|---|---|
| Claude Code | mutsumi setup --agent claude-code |
| Codex CLI | mutsumi setup --agent codex-cli |
| Gemini CLI | mutsumi setup --agent gemini-cli |
| 其他 Agent | mutsumi setup --agent custom |
Agent 写入后 mutsumi.json 格式错误怎么办？
Section titled “Agent 写入后 mutsumi.json 格式错误怎么办？”Mutsumi 会显示错误横幅但不会崩溃，保留上次有效的任务列表。建议在 Agent 提示中加入自愈指令：
写入 mutsumi.json 后，检查 ~/.local/share/mutsumi/error.log是否有 Schema 校验错误。如有错误，修复后重新写入。多个 Agent 同时写入会冲突吗？
Section titled “多个 Agent 同时写入会冲突吗？”极少发生。Mutsumi 使用 Last Write Wins 策略。由于 Agent 写入通常间隔秒到分钟，实际冲突概率极低。建议 Agent 每次写入前先读取最新文件。
mutsumi.json 在哪里？
Section titled “mutsumi.json 在哪里？”默认在当前工作目录下。你也可以用 --path 指定路径：
mutsumi --path /path/to/mutsumi.jsonMutsumi 会删除我的自定义字段吗？
Section titled “Mutsumi 会删除我的自定义字段吗？”绝不会。 这是 Mutsumi 的核心承诺。任何 Mutsumi 不认识的字段都会被原样保留，永远不会被删除或修改。
如何备份任务数据？
Section titled “如何备份任务数据？”mutsumi.json 是纯文本 JSON 文件，天然 Git 友好。推荐：
# 加入 Git 版本管理git add mutsumi.jsongit commit -m "backup tasks"任务 ID 用什么格式？
Section titled “任务 ID 用什么格式？”默认使用 UUIDv7 — 按时间排序的全局唯一标识符。也可配置为 ULID 或自增数字。
Mutsumi 会消耗很多资源吗？
Section titled “Mutsumi 会消耗很多资源吗？”不会。Mutsumi 是轻量级终端应用：
- 内存占用通常 < 50MB
- CPU 近乎为零（只在文件变更时做少量工作）
- 无网络请求、无后台同步
能处理多少任务？
Section titled “能处理多少任务？”对于日常使用（几十到几百个任务），性能没有任何问题。mutsumi.json 是全量加载的，如果超过数千个任务，考虑归档已完成的任务。