工作流 SOP

最终效果

一个快捷键呼出你的指挥中心。左边是 AI Agent，右边是实时任务看板。Agent 写任务，看板秒更新。零切换、零打断。

 Win+~  /  Ctrl+~  (下拉终端)
┌──────────────────────────────┬──────────────────┐
│                              │                  │
│  AI Agent (opencode/claude)  │   Mutsumi TUI    │
│                              │                  │
│  > "给 auth 重构加 3 个任务" │  ┌─────────────┐ │
│                              │  │ [* Main]     │ │
│  正在写入 mutsumi.json...    │  │ * 修复登录   │ │
│                              │  │ * 加 OAuth   │ │
│                              │  │ * 写测试     │ │
│                              │  └─────────────┘ │
└──────────────────────────────┴──────────────────┘

前置依赖

工具	用途	安装
终端模拟器	下拉（雷神）模式	Windows Terminal / iTerm2 / Yakuake
tmux（可选）	分屏、会话持久化	apt install tmux / brew install tmux（Windows 用 Terminal 内置分屏）
uv	Python 包管理	curl -LsSf https://astral.sh/uv/install.sh | sh
Mutsumi	任务看板 TUI	uv tool install git+https://github.com/ywh555hhh/Mutsumi
AI Agent	向 mutsumi.json 写任务	opencode / Claude Code / aider / Codex CLI

各平台搭建

Windows

第 1 步：Windows Terminal + 雷神模式

Windows Terminal 内置「雷神模式」（Quake Mode）—— 按全局快捷键，终端从屏幕顶部滑下，按 Quake 游戏经典方式呈现。

1. 从 Microsoft Store 安装 Windows Terminal
2. 打开设置 → 操作 → 添加：

{ "command": { "action": "quakeMode" }, "keys": "win+`" }

现在 Win+` 可以全局切换下拉终端。

第 2 步：安装工具

Mutsumi 原生支持 Windows，不需要 WSL。

# uv（Python 管理器）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Mutsumi
uv tool install git+https://github.com/ywh555hhh/Mutsumi

# AI Agent（选一个）
uv tool install opencode    # 或：npm install -g @anthropic-ai/claude-code

第 3 步：分屏

Windows Terminal 自带分屏功能，不需要 tmux：

• Alt+Shift+D — 自动分屏（复制当前 pane）
• Alt+Shift+= — 垂直分屏
• Alt+Shift+- — 水平分屏
• Alt+方向键 — 切换 pane

操作流程：

1. 打开项目目录
2. Alt+Shift+= 垂直分屏
3. 右侧 pane 输入 mutsumi
4. Alt+← 切回左侧，启动你的 Agent

想用 tmux？

如果你更喜欢 tmux 的会话管理，可以通过 WSL 使用：wsl --install -d Ubuntu，然后在 WSL 内按 Linux 的步骤操作。但这不是必须的。

搞定！首次运行 mutsumi 时，内置的引导向导会带你完成语言、键绑定、主题、工作区模式和 Agent 集成配置 —— 不需要手动 init 或 setup。

macOS

第 1 步：iTerm2 热键窗口

1. 安装 iTerm2
2. Preferences → Keys → Hotkey → 勾选 “Show/hide all windows with a system-wide hotkey”
3. 设置热键为 Ctrl+`

替代方案：Ghostty 配置 quick-terminal-hotkey。

第 2 步：tmux

brew install tmux

第 3 步：安装工具

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Mutsumi
uv tool install git+https://github.com/ywh555hhh/Mutsumi

# AI Agent
uv tool install opencode    # 或：npm install -g @anthropic-ai/claude-code

首次运行 mutsumi 会自动进入引导向导 —— 不需要手动 init 或 setup。

Linux

第 1 步：下拉终端

主流 Linux 桌面都有下拉终端方案：

桌面环境	工具	快捷键
KDE	Yakuake	F12
GNOME	ddterm	F12
通用	Guake	F12
通用	Tilix（Quake 模式）	可配置

第 2 步：tmux

sudo apt install tmux    # Debian/Ubuntu
sudo pacman -S tmux      # Arch
sudo dnf install tmux    # Fedora

第 3 步：安装工具

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install git+https://github.com/ywh555hhh/Mutsumi
uv tool install opencode

首次运行 mutsumi 会自动进入引导向导 —— 不需要手动 init 或 setup。

一键启动脚本

保存为 ~/.local/bin/mu（或 $PATH 中的任意位置）：

bash / zsh

#!/usr/bin/env bash
# mu — 启动 Mutsumi 开发环境
# 用法：mu [项目目录] [agent 命令]
#   mu                          → 当前目录，默认 agent
#   mu ~/projects/saas-app      → 指定项目
#   mu . claude                 → 当前目录，Claude Code

set -euo pipefail

PROJECT_DIR="${1:-.}"
AGENT_CMD="${2:-opencode}"
SESSION="mu-$(basename "$PROJECT_DIR")"
MUTSUMI_WIDTH="${MUTSUMI_WIDTH:-35}"

cd "$PROJECT_DIR"

# 如果会话已存在，直接 attach
if tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux attach -t "$SESSION"
  exit 0
fi

# 新会话：左边 agent，右边 mutsumi
tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR"
tmux split-window -h -p "$MUTSUMI_WIDTH" -t "$SESSION" "mutsumi"
tmux select-pane -t "$SESSION:0.0"

# 在左 pane 启动 agent
if [ "$AGENT_CMD" != "shell" ]; then
  tmux send-keys -t "$SESSION:0.0" "$AGENT_CMD" Enter
fi

tmux attach -t "$SESSION"

fish

#!/usr/bin/env fish
# mu — 启动 Mutsumi 开发环境

set PROJECT_DIR (realpath (test -n "$argv[1]"; and echo $argv[1]; or echo .))
set AGENT_CMD (test -n "$argv[2]"; and echo $argv[2]; or echo opencode)
set SESSION "mu-"(basename $PROJECT_DIR)
set MUTSUMI_WIDTH (test -n "$MUTSUMI_WIDTH"; and echo $MUTSUMI_WIDTH; or echo 35)

cd $PROJECT_DIR

if tmux has-session -t $SESSION 2>/dev/null
  tmux attach -t $SESSION
  exit 0
end

tmux new-session -d -s $SESSION -c $PROJECT_DIR
tmux split-window -h -p $MUTSUMI_WIDTH -t $SESSION "mutsumi"
tmux select-pane -t "$SESSION:0.0"

if test "$AGENT_CMD" != shell
  tmux send-keys -t "$SESSION:0.0" $AGENT_CMD Enter
end

tmux attach -t $SESSION

PowerShell

# mu.ps1 — Windows 原生启动脚本
# 放到 PATH 中或固定到开始菜单

param(
  [string]$ProjectDir = ".",
  [string]$Agent = "opencode"
)

Push-Location (Resolve-Path $ProjectDir).Path

# 用 Windows Terminal 分屏：右侧启动 mutsumi
wt -w 0 sp -V --size 0.35 mutsumi

# 左侧启动 agent
if ($Agent -ne "shell") {
  & $Agent
}

添加执行权限：

chmod +x ~/.local/bin/mu

日常使用

1. 按快捷键 — Win+</kbd> / <kbd>Ctrl+ / F12 — 终端从顶部滑下

2. 启动 — 在项目目录输入 mu（或 mu ~/projects/my-app）

3. 工作 — 在左侧和 AI Agent 对话，右侧看板实时更新任务

4. 完成任务 — 在 Mutsumi 中点击复选框或按 x 标记完成

5. 切换项目 — mu ~/projects/other-app 打开新的 tmux 会话；用 Ctrl-b s 在会话间切换

6. 分离 — Ctrl-b d 分离会话，后台保持运行。随时用 mu 回来

7. 收起 — 再按快捷键隐藏终端

多项目布局

进阶用户可以同时管理多个项目：

 tmux 会话：
  mu-saas-app     →  opencode  |  mutsumi (saas-app/mutsumi.json)
  mu-oshigrid     →  claude    |  mutsumi (oshigrid/mutsumi.json)
  mu-personal     →  shell     |  mutsumi (~/.mutsumi/mutsumi.json)

 Ctrl-b s → 会话选择器 → 秒切

配合 Multi-Source Hub，Main 仪表盘可以聚合所有项目一览。

Agent 兼容性

启动脚本兼容所有终端 AI Agent：

mu . opencode     # OpenCode
mu . claude       # Claude Code
mu . aider        # Aider
mu . codex        # Codex CLI
mu . shell        # 不启动 agent，纯 shell

所有 Agent 使用同一套协议：读 mutsumi.json → 修改任务 → 写回。详见 Agent 集成。

提示

进阶技巧：把 mu 加到 shell 启动脚本，或绑定到 tmux 快捷键：

# ~/.tmux.conf — Ctrl-b M 打开项目选择
bind M command-prompt -p "Project:" "run-shell '~/.local/bin/mu %1'"

常见问题

问题	解决方法
mu: command not found	把 ~/.local/bin 加到 $PATH
tmux 分屏太窄	export MUTSUMI_WIDTH=40 或用 Ctrl-b → 调整
Agent 没写 mutsumi.json	运行 mutsumi setup --agent <name> 或通过 mutsumi init 重新引导
雷神模式不工作	检查终端快捷键设置；某些桌面环境会抢占按键