一位Karo（管理者）协调7位Ashigaru（工作者）+1位Gunshi（战略家）——真实会话，无模拟数据。

快速入门

要求： tmux、bash 4+，至少具备以下之一：Claude Code / Codex / Copilot / Kimi

git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh          # 一次性设置：配置、依赖项、MCP
bash shutsujin_departure.sh  # 启动所有代理

在Shogun面板中输入一条命令：

“构建一个用于用户认证的REST API”

Shogun将任务委派给Karo，Karo再将其分解后交由7位Ashigaru并行执行。你只需观察仪表盘即可。就这么简单。

想深入了解吗？ 本README的其余部分将介绍架构、配置、内存设计以及多CLI的设置方法。

这是什么？

multi-agent-shogun 是一个系统，能够同时运行多个AI编码CLI实例，并像日本封建军队一样对它们进行协调。支持 Claude Code、OpenAI Codex、GitHub Copilot 和 Kimi Code。

为什么使用它？

• 一条命令即可启动7个AI工作者和1个战略家并行执行
• 无需等待——任务在后台运行时，你可以立即下达下一条指令
• AI会在不同会话间记住你的偏好（Memory MCP）
• 实时进度显示在仪表盘上

        您（上様 / 主人）
             │
             ▼  下达命令
      ┌─────────────┐
      │   SHOGUN    │  ← 接收您的命令，立即进行委派
      └──────┬──────┘
             │  YAML + tmux
      ┌──────▼──────┐
      │    KARO     │  ← 将任务分发给工作者
      └──────┬──────┘
             │
    ┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐
    │1│2│3│4│5│6│7│ GUNSHI │  ← 7位工作者 + 1位战略家
    └─┴─┴─┴─┴─┴─┴─┴────────┘
       ASHIGARU      軍師

为什么是“Shogun”？

大多数多智能体框架都会在协调过程中消耗API调用额度。而Shogun则不会。

它的独特之处

零协调开销 —— 代理之间通过磁盘上的YAML文件进行通信。唯一的API调用仅用于实际工作，而非调度协调。运行8个代理，只需为8个代理的工作付费。

完全透明 —— 每个代理都在可见的tmux面板中运行。每条指令、每份报告和每个决策都以纯文本YAML文件的形式存在，你可以阅读、比较差异并进行版本控制。没有任何黑箱。

经过实战检验的层级结构 —— Shogun → Karo → Ashigaru的指挥链从设计上避免了冲突：清晰的责任归属、每个代理专属的文件、事件驱动的通信机制，无需轮询。

为什么选择CLI（而不是API）？

大多数AI编码工具按调用次数收费。通过API运行8个Opus级别的代理，每小时的成本可能高达100美元以上。而CLI订阅则颠覆了这一模式：

“尽情地使用AI吧” —— 有了固定费率的CLI订阅，你可以毫不犹豫地部署8个代理。无论它们运行1小时还是24小时，成本都是一样的。再也不必在“足够好”和“彻底”之间做出选择——只需运行更多的代理即可。

多 CLI 支持

Shogun 并不局限于单一厂商。该系统支持 4 种 CLI 工具，每种都有其独特的优势：

统一的指令构建系统会从共享模板生成特定于 CLI 的指令文件：

instructions/
├── common/              # 共享规则（所有 CLI）
├── cli_specific/        # CLI 特定的工具描述
│   ├── claude_tools.md  # Claude Code 工具与功能
│   └── copilot_tools.md # GitHub Copilot CLI 工具与功能
└── roles/               # 角色定义（shogun、karo、ashigaru）
    ↓ build
CLAUDE.md / AGENTS.md / copilot-instructions.md  ← 按每个 CLI 生成

只有一个事实来源，无需同步偏差。只需更改一次规则，所有 CLI 都会自动更新。

自下而上的技能发现

这是其他框架所不具备的功能。

当 Ashigaru 执行任务时，他们会自动识别可重用的模式，并将其作为技能候选提交。Karo 会将这些提案汇总到 dashboard.md 中，然后由你——即“领主”——决定哪些技能可以晋升为永久技能。

Ashigaru 完成一项任务
    ↓
注意到：“我在不同项目中已经完成了这个模式 3 次”
    ↓
以 YAML 格式报告：  skill_candidate:
                     found: true
                     name: "api-endpoint-scaffold"
                     reason: "在 3 个项目中都使用了相同的 REST 脚手架模式"
    ↓
出现在 dashboard.md → 你批准 → 技能被创建在 .claude/commands/
    ↓
任何代理现在都可以调用 /api-endpoint-scaffold

技能是从实际工作中有机生长出来的，而不是基于预定义的模板库。你的技能集合将成为你自身工作流的反映。

快速入门

Windows (WSL2)

cd /mnt/c/tools/multi-agent-shogun
./first_setup.sh

./shutsujin_departure.sh

仅首次：认证

在运行 first_setup.sh 后，需执行以下命令进行一次性认证：

# 1. 应用 PATH 变更
source ~/.bashrc

# 2. OAuth 登录 + 绕过权限审批（一条命令）
claude --dangerously-skip-permissions
#    → 浏览器打开 → 使用 Anthropic 账户登录 → 返回 CLI
#    → 出现“绕过权限”提示 → 选择“是，我接受”（↓至选项 2，Enter）
#    → 输入 /exit 退出

这会将凭据保存到 ~/.claude/ — 以后无需再次操作。

日常启动

打开一个 Ubuntu 终端（WSL），并运行：

cd /mnt/c/tools/multi-agent-shogun
./shutsujin_departure.sh

📱 移动访问 — 专用 Android 应用程序（推荐）

通过专用的 Android 伴侣应用，您可以在手机上监控并指挥 10 个 AI 代理。

注意： 目前仅支持 Android。暂无 iOS 版本——因为开发者本人没有 iPhone。如有需求，请在 Issue 中提出。欢迎提交 PR！

设置

先决条件：

• Shogun 系统正在 WSL2 上运行（或 Linux 服务器）
• SSH 服务器已启动（sudo service ssh start）
• 手机和服务器处于同一网络（局域网或 Tailscale）

步骤：

1. 安装 APK

   1. 在手机上下载 android/release/multi-agent-shogun.apk（在 GitHub 上打开文件 → “下载原始文件”）
   2. 点击下载通知 → “安装”
   3. 如果出现“未知来源”警告 → 进入“设置” → 为浏览器启用“允许从此来源安装” → 返回 → “安装”
   4. 完成后 → “打开”

2. 配置 SSH（设置标签页）

   字段	示例	描述
   SSH 主机	100.xxx.xxx.xxx	服务器 IP 地址（例如 Tailscale IP）
   SSH 端口	22	通常为 22
   SSH 用户	your_username	SSH 登录用户名
   SSH 密钥路径	/data/data/.../id_ed25519	手机上的私钥路径 (*1)
   SSH 密码	****	如果没有密钥可用，则使用密码
   项目路径	/mnt/c/tools/multi-agent-shogun	服务器端的项目目录
   Shogun 会话	shogun	Shogun 的 tmux 会话名称
   代理会话	multiagent	代理的 tmux 会话名称

   *1 将您的私钥传输到手机，或使用密码认证

3. 保存 → 切换到 Shogun 标签页 → 自动连接

使用 Tailscale（随时随地连接）：

# 服务器端（WSL2）
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscaled &
sudo tailscale up --authkey tskey-auth-XXXXXXXXXXXX
sudo service ssh start

在手机上安装 Tailscale 应用程序，使用相同的账户登录，并将显示的 Tailscale IP 地址作为应用程序中的 SSH 主机。

使用 ntfy 通知：

请参阅 ntfy 设置部分，了解 Karo 在任务完成后发送的推送通知。

# 1. 克隆
git clone https://github.com/yohey-w/multi-agent-shogun.git ~/multi-agent-shogun
cd ~/multi-agent-shogun

# 2. 将脚本设为可执行
chmod +x *.sh

# 3. 运行首次设置
./first_setup.sh

cd ~/multi-agent-shogun
./shutsujin_departure.sh

wsl --install

设置完成后

无论你选择哪种方式，都会自动启动 10 个 AI 代理：

创建了两个 tmux 会话：

• shogun——在这里连接以发出命令
• multiagent——Karo、Ashigaru 和 Gunshi 在后台运行

工作原理

第一步：连接到 Shogun

运行 shutsujin_departure.sh 后，所有代理会自动加载他们的指令并准备就绪。

打开一个新的终端并连接：

tmux attach-session -t shogun

第二步：下达你的第一个命令

Shogun 已经初始化完毕——只需下达一个命令：

研究前 5 名 JavaScript 框架，并创建一个比较表格

Shogun 将会：

1. 将任务写入 YAML 文件
2. 通知 Karo（管理员）
3. 立即返回控制权给你——无需等待！

与此同时，Karo 会将任务分配给 Ashigaru 工人并行执行。

第三步：查看进度

在编辑器中打开 dashboard.md，即可实时查看状态：

## 进行中
| 工人 | 任务 | 状态 |
|--------|------|--------|
| Ashigaru 1 | 研究 React | 运行中 |
| Ashigaru 2 | 研究 Vue | 运行中 |
| Ashigaru 3 | 研究 Angular | 完成 |

详细流程

你： “研究前 5 名 MCP 服务器，并创建一个比较表格”

Shogun 将任务写入 queue/shogun_to_karo.yaml 文件，并唤醒 Karo。控制权立即返回给你。

Karo 将任务分解为子任务：

所有 5 名 Ashigaru 同时进行研究。你可以实时观察他们的工作：

结果会随着任务的完成而出现在 dashboard.md 中。

主要特点

⚡ 1. 并行执行

一条命令最多会启动8个并行任务：

你：“研究5台MCP服务器”
→ 5名足轻同时开始研究
→ 结果在几分钟内就能出来，而不是几小时

🔄 2. 非阻塞工作流

幕府将军会立即委派任务，并将控制权交还给你：

你：下达命令 → 幕府将军：委派任务 → 你：立刻下达下一个命令
                                       ↓
                       工作人员：在后台执行
                                       ↓
                       仪表盘：显示结果

无需等待长时间的任务完成。

🧠 3. 跨会话记忆（Memory MCP）

你的AI会记住你的偏好设定：

会话1：告诉它“我更喜欢简单的方法”
            → 保存到Memory MCP

会话2：AI启动时加载记忆
            → 不再建议复杂的解决方案

📡 4. 事件驱动通信（零轮询）

代理之间通过写入YAML文件进行通信——就像传递纸条一样。没有轮询循环，也没有浪费的API调用。

家老想要唤醒足轻3号：

步骤1：写消息          步骤2：唤醒代理
┌──────────────────────┐           ┌──────────────────────────┐
│ inbox_write.sh       │           │ inbox_watcher.sh         │
│                      │           │                          │
│ 将完整消息写入      │  文件     │ 检测文件变化           │
│ ashigaru3.yaml中    │──改变──▶│ （inotifywait，而非轮询）│
│ 使用flock避免竞态   │           │                          │
└──────────────────────┘           │ 通过以下方式唤醒代理： │
                                   │  1. 自我监听（跳过）    │
                                   │  2. tmux send-keys       │
                                   │     （仅发送简短提示）   │
                                   └──────────────────────────┘

步骤3：代理读取自己的收件箱
┌──────────────────────────────────┐
│ 足轻3号读取ashigaru3.yaml        │
│ → 发现未读消息                   │
│ → 处理这些消息                   │
│ → 标记为已读                     │
└──────────────────────────────────┘

唤醒机制的工作原理：

代理自我监听（ASW）阶段——控制系统使用tmux send-keys提示的激进程度：

阶段2使用空闲标志文件（/tmp/shogun_idle_{agent}）来区分忙碌与空闲的代理。停止钩子会在回合边界创建或移除该标志。这样可以在代理积极工作时避免提示干扰，同时仍能唤醒空闲的代理。

为什么不能完全消除提示？ Claude Code的停止钩子只在回合结束时触发。一个空闲的代理（坐在提示符前）并没有回合结束，因此没有钩子来触发收件箱检查。未来如果有一个支持idle_prompt阻塞的Notification钩子，或者定期的定时器钩子，就可以解决这个问题。

在config/settings.yaml中配置：

asw_phase: 2   # 推荐用于Claude Code设置

或者直接在scripts/inbox_watcher.sh中设置默认值（ASW_PHASE变量）。更改后需重启inbox_watcher进程。

3阶段升级（v3.2）——如果代理没有响应：

关键设计选择：

• 消息内容绝不会通过tmux发送——只会发送一个简短的“你有邮件”提示。代理自己读取文件。这样可以避免字符乱码和传输卡顿。
• 空闲时CPU占用为0%——inotifywait会阻塞在内核事件上（而不是轮询循环）。消息之间CPU使用率为0%。
• 保证送达——如果文件写入成功，消息就一定在那里。不会有消息丢失，也不需要重试。

📊 5. 代理状态检查

只需一条命令，即可立即查看哪些代理正在忙碌或空闲：

# 项目模式：包含任务/收件箱信息的完整状态
bash scripts/agent_status.sh

# 独立模式：适用于任何tmux会话
bash scripts/agent_status.sh --session mysession --lang en

项目模式输出：

代理      CLI     窗格      任务ID                                    状态     收件箱
---------- ------- --------- ------------------------------------------ ---------- -----
karo       claude  待机中    ---                                        ---        0
ashigaru1  codex   运行中    subtask_042a_research                      分配       0
ashigaru2  codex   待机中    subtask_042b_review                        完成       0
gunshi     claude  运行中    subtask_042c_analysis                      分配       0

独立模式输出（无需项目配置）：

窗格                           状态      代理ID
------------------------------ ---------- ----------
multiagent:agents.0            IDLE       karo
multiagent:agents.1            BUSY       ashigaru1
multiagent:agents.8            BUSY       gunshi

检测功能同时适用于Claude Code和Codex CLI，通过检查每个tmux窗格底部5行中的CLI特定提示符/旋转图标模式来实现。检测逻辑位于lib/agent_status.sh中——你可以在自己的脚本中引用它：

source lib/agent_status.sh
agent_is_busy_check "multiagent:agents.3" && echo "busy" || echo "idle"

📸 6. 截图集成

VSCode的Claude Code扩展允许你粘贴截图来解释问题。这个CLI系统也提供了相同的功能：

# 在config/settings.yaml中设置你的截图文件夹
screenshot:
  path: "/mnt/c/Users/YourName/Pictures/Screenshots"

# 只需告诉将军：
你：“查看最新的截图”
你：“看看最近的两张截图”
→ AI会立即读取并分析你的屏幕截图

Windows 小贴士： 按下 Win + Shift + S 即可截屏。在 settings.yaml 中设置保存路径，实现无缝集成。

使用场景：

• 以可视化方式说明 UI 错误
• 展示错误信息
• 对比前后状态

📁 7. 上下文管理（4层架构）

通过四层上下文系统实现高效的知识共享：

持久化代理记忆 (memory/MEMORY.md)

Shogun 在每次会话开始时都会读取 memory/MEMORY.md 文件。其中包含主公的偏好、经验教训以及跨会话的知识——由 Shogun 编写，也由 Shogun 阅读。

┌─────────────────────────────────────────────────────────────┐
│                    Git 仓库                          │
│                                                              │
│  ┌─────────────────────┐   ┌──────────────────────────┐    │
│  │  multi-agent-shogun │   │      shogun-private        │    │
│  │       (公开的 OSS)  │   │   (您的私有仓库)      │    │
│  │                     │   │                            │    │
│  │ scripts/            │   │ projects/client.yaml  ←──┐ │    │
│  │ instructions/       │   │ context/my-notes.md   ←──┤ │    │
│  │ lib/                │   │ queue/shogun_to_karo.yaml │ │    │
│  │ memory/             │   │ memory/MEMORY.md      ←──┘ │    │
│  │  ├─ MEMORY.md.sample│   │ config/settings.yaml       │    │
│  │  └─ MEMORY.md  ─────┼───┼── 同一文件，在此处跟踪  │    │
│  │     (gitignored)    │   │                            │    │
│  └─────────────────────┘   └──────────────────────────┘    │
│         ↑ 任何人都可以 fork        ↑ 您的数据，您的仓库      │
└─────────────────────────────────────────────────────────────┘

工作原理： memory/MEMORY.md 文件与 OSS 仓库位于同一工作目录中，但被排除在 OSS 的 .gitignore 列表之外（白名单机制）。您可以通过裸仓库技术将其单独存储在私有仓库中：

# 一次性设置（已由 first_setup.sh 完成）
git init --bare ~/.shogun-private.git
alias privategit='git --git-dir=$HOME/.shogun-private.git --work-tree=/path/to/multi-agent-shogun'
privategit remote add origin https://github.com/YOU/shogun-private.git

# 日常使用
privategit add -f memory/MEMORY.md projects/my-client.yaml
privategit commit -m "更新记忆"
privategit push

OSS 的 .gitignore 使用 白名单策略（默认排除所有内容，然后显式允许 OSS 文件）。因此，像 memory/MEMORY.md 这样的私有文件会自动被排除，无需额外的 .gitignore 条目——只需不要将它们加入白名单即可。

这种设计实现了：

• 任何足轻都可以参与任何项目
• 上下文可在不同代理之间持续传递
• 清晰的责任划分
• 知识可在不同会话间保留

/clear 协议（成本优化）

随着代理工作的进行，其会话上下文（第4层）会不断增长，从而增加 API 成本。执行 /clear 命令可以清除会话内存并重置费用。而第1至第3层的内容则以文件形式持久保存，因此不会丢失。

执行 /clear 后的恢复成本：约6,800个token（相比v1版本提升了42%——CLAUDE.md的YAML转换以及仅使用英文指令使token成本降低了70%）。

1. CLAUDE.md（自动加载）→识别自身为Shogun系统的一部分
2. tmux display-message -t "$TMUX_PANE" -p '#{@agent_id}' → 确定自身的编号
3. 读取记忆MCP → 恢复主公的偏好（约700个token）
4. 读取任务YAML → 获取下一个任务（约800个token）

关键在于：设计出哪些内容不需要加载，才能真正实现成本节约。

通用上下文模板

所有项目都采用相同的7部分模板：

这一统一格式能够：

• 让任何代理快速上手
• 在所有项目中实现一致的信息管理
• 方便足轻之间的交接

📱 8. 手机通知（ntfy）

手机与Shogun之间的双向通信——无需SSH、无需Tailscale、无需服务器。

📱 您（在床上）          🏯 Shogun
    │                          │
    │  “研究React 19”     │
    ├─────────────────────────►│
    │    （ntfy消息）        │  → 委托给Karo → 足轻开始工作
    │                          │
    │  “✅ cmd_042完成”   │
    │◄─────────────────────────┤
    │    （推送通知）   │

设置：

1. 在 config/settings.yaml 中添加 ntfy_topic: "shogun-yourname"
2. 在手机上安装 ntfy app，并订阅相同的主题
3. shutsujin_departure.sh 会自动启动监听器——无需额外步骤

通知示例：

免费使用，无需注册账户，也不需要维护服务器。使用的是 ntfy.sh——一个开源的推送通知服务。

⚠️ 安全性： 您的主题名称就是您的密码。任何知道该名称的人都可以阅读您的通知并向您的Shogun发送消息。请务必选择一个难以猜测的名称，并且切勿公开分享（例如在截图、博客文章或GitHub提交中）。

验证是否正常工作：

privategit status

向您的手机发送一条测试通知

bash scripts/ntfy.sh "来自Shogun的测试通知 🏯"

如果您的手机收到了通知，那么一切就绪。如果没有收到，请检查：
- `config/settings.yaml` 中已设置 `ntfy_topic`（非空且无额外引号）
- 手机上的 ntfy 应用已订阅 **完全相同的主题名称**
- 您的手机已连接互联网，并且 ntfy 通知功能已开启

**通过手机发送命令：**

1. 打开手机上的 ntfy 应用
2. 点击您已订阅的主题
3. 输入一条消息（例如：`Research React 19 best practices`），然后发送
4. `ntfy_listener.sh` 接收到该消息后，会将其写入 `queue/ntfy_inbox.yaml`，并唤醒 Shogun
5. Shogun 读取该消息，并按照正常的 Karo → Ashigaru 流程进行处理

您发送的任何文本都会变成一条命令。您可以像与 Shogun 对话一样直接书写，无需使用特殊语法。

**手动启动监听器**（如果您没有使用 `shutsujin_departure.sh`）：

```bash
# 在后台启动监听器
nohup bash scripts/ntfy_listener.sh &>/dev/null &

# 检查是否正在运行
pgrep -f ntfy_listener.sh

# 查看监听器日志（stderr 输出）
bash scripts/ntfy_listener.sh  # 前台运行以查看日志

如果连接断开，监听器会自动重新连接。shutsujin_departure.sh 会在部署时自动启动它——只有在您跳过了部署脚本的情况下才需要手动启动。

故障排除：

实际通知截图：

左图：双向手机 ↔ Shogun 通信 · 右图：来自 Ashigaru 的实时进度报告

左图：命令完成通知 · 右图：8个 Ashigaru 并行完成

注：截图中显示的主题名称仅为示例。请使用您自己唯一的主题名称。

SayTask 通知

基于行为心理学的动力机制，通过您的通知流来激励您：

• 连续打卡追踪：连续完成天数会记录在 saytask/streaks.yaml 中——保持连续性可以利用损失规避心理来维持动力
• 吃掉那只青蛙 🐸：当天最困难的任务会被标记为“青蛙”。完成它会触发特别的庆祝通知
• 每日进度：今天已完成 12/12 项任务——可视化完成反馈强化了 Arbeitslust 效果（对正在进行的工作的喜悦）

🖼️ 9. 窗格边框任务显示

每个 tmux 窗格的边框上都会直接显示当前代理的任务：

┌ ashigaru1 Sonnet+T VF 要求 ──┬ ashigaru3 Opus+T API 研究 ──────┐
│                                      │                                     │
│  正在处理 SayTask 要求     │  正在研究 REST API 模式      │
│                                      │                                     │
├ ashigaru2 Sonnet ───────────────────┼ ashigaru4 Spark DB 模式设计 ───┤
│                                      │                                     │
│  (空闲 — 等待分配)     │  正在设计数据库模式          │
│                                      │                                     │
└──────────────────────────────────────┴─────────────────────────────────────┘

• 工作中：ashigaru1 Sonnet+T VF 要求——显示代理名称、模型（带有思考指示器）以及任务摘要
• 空闲中：ashigaru2 Sonnet——仅显示模型名称，无任务
• 显示名称：Sonnet、Opus、Haiku、Codex、Spark——+T 后缀表示启用了扩展思考功能
• 由 Karo 在分配或完成任务时自动更新
• 眺望所有 9 个窗格，即可立即了解谁在做什么

🔊 10. 呐喊模式（战斗口号）

当一个 Ashigaru 完成任务时，它会在 tmux 窗格中喊出一句个性化的战斗口号——这是提醒您军队正在努力工作的视觉信号。

┌ ashigaru1 (Sonnet) ──────────┬ ashigaru2 (Sonnet) ──────────┐
│                               │                               │
│  ⚔️ 足軽1号、先陣切った！     │  🔥 足軽2号、二番槍の意地！   │
│  八刃一志！                   │  八刃一志！                   │
│  ❯                            │  ❯                            │
└───────────────────────────────┴───────────────────────────────┘

工作原理：

Karo 会在每个任务 YAML 文件中写入一个 echo_message 字段。当所有工作完成后（包括报告和收件箱通知），Ashigaru 会将 echo 作为其 最后一步操作 来执行。这条消息会一直显示在 ❯ 提示符上方。

# 在任务 YAML 中（由 Karo 编写）
task:
  task_id: subtask_001
  description: "创建对比表格"
  echo_message: "🔥 足軽1号、先陣を切って参る！八刃一志！"

呐喊模式是默认设置。 若要关闭（以节省 echo 调用的 API 令牌）：

./shutsujin_departure.sh --silent    # 不喊口号
./shutsujin_departure.sh             # 默认：启用呐喊模式（喊口号）

静音模式会将 DISPLAY_MODE=silent 设置为 tmux 环境变量。Karo 在编写任务 YAML 时会检查此变量，并省略 echo_message 字段。

🗣️ SayTask — 专为讨厌任务管理的人打造的任务管理工具

什么是 SayTask？

专为讨厌任务管理的人设计的任务管理工具。只需对着手机说话即可。

用语言编码，而非氛围编码。 把您的任务说出来，AI 就会帮您整理好。无需打字，无需打开应用，没有任何摩擦。

• 目标用户：那些曾经安装过 Todoist，但三天后就再也没打开过的人
• 您的敌人不是其他应用——而是什么都不做。真正的竞争对象是无所作为，而不是另一个生产力工具
• 零界面。零打字。零打开应用。只需开口说话

"您的敌人不是其他应用——而是什么都不做。"

工作原理

1. 安装 ntfy 应用（免费，无需账号）
2. 对手机说：“明天看牙医”，“发票周五到期”
3. AI 自动整理 → 早晨通知：“这是你今天的一天安排”

 🗣️ “买牛奶，明天看牙医，发票周五到期”
       │
       ▼
 ┌──────────────────┐
 │  ntfy → Shogun   │  AI 自动分类、解析日期、设定优先级
 └────────┬─────────┘
          │
          ▼
 ┌──────────────────┐
 │   tasks.yaml     │  结构化存储（本地，数据永不离开你的设备）
 └────────┬─────────┘
          │
          ▼
 📱 早晨通知：
    “今日：🐸 发票到期 · 🦷 下午3点看牙医 · 🛒 购买牛奶”

使用前/后对比

使用前 (v1)	使用后 (v2)
原始任务清单	干净、有序的每日总结

注：截图中显示的主题名称仅为示例。请使用您自己唯一的主题名称。

使用场景

• 🛏️ 在床上：“明天得提交报告”——在忘记之前就记录下来，无需翻找笔记本
• 🚗 开车时：“别忘了给客户A的报价单”——免提操作，眼睛始终盯着路面
• 💻 工作间隙：“哦，得去买牛奶”——立即记录，保持工作流畅
• 🌅 醒来时：今天的任务已出现在通知中——无需打开应用，无需查看收件箱
• 🐸 吃掉那只青蛙：AI 每天早上会为你挑选最难的任务——你可以选择忽略它，也可以先完成它

常见问题解答

问：这和其它任务管理应用有什么不同？ 答：你完全不需要打开任何应用。只需说话即可。零摩擦。大多数任务管理应用之所以失败，是因为人们不再去打开它们。SayTask 则彻底省去了这一步。

问：我可以在没有完整 Shogun 系统的情况下使用 SayTask 吗？ 答：SayTask 是 Shogun 的一个功能。Shogun 本身也是一个独立的多智能体开发平台——你可以在同一个系统中同时获得这两种能力。

问：那只青蛙 🐸 是什么？ 答：每天早上，AI 会为你挑选最困难的任务——也就是你最想回避的任务。你可以选择先完成它（即“吃掉那只青蛙”的方法），也可以选择忽略。由你决定。

问：它是免费的吗？ 答：一切都是免费且开源的。ntfy 也是免费的。无需账号、无需服务器、无需订阅。

问：我的数据存储在哪里？ 答：数据存储在你本地的 YAML 文件中。没有任何数据会被发送到云端。你的任务永远不会离开你的设备。

问：如果我说一些模糊的话，比如“那个工作上的事”怎么办？ 答：AI 会尽力对其进行分类和安排。你随时可以稍后再进行调整——但关键在于，在想法消失之前将其捕捉下来。

SayTask 与 cmd 流水线对比

Shogun 拥有两个互补的任务系统：

SayTask 负责个人生产力（捕捉 → 安排 → 提醒）。cmd 流水线则负责复杂的工作（研究、代码、多步骤任务）。两者共享连续打卡功能——完成任一类任务都会计入你的每日打卡数。

模型设置

思考控制：在 config/settings.yaml 中为每个智能体设置 thinking: true/false。当 thinking: false 时，该智能体会以 MAX_THINKING_TOKENS=0 开始，从而禁用扩展思考功能。当启用思考功能时，面板边框会显示 +T 后缀（例如 Sonnet+T、Opus+T）。

实时模型切换：使用 /shogun-model-switch 可以更改任意智能体的 CLI 类型、模型或思考设置，而无需重启整个系统。详情请参阅技能部分。

系统根据认知复杂度在两个层面进行任务路由：智能体路由（L1–L3 由 Ashigaru 处理，L4–L6 由 Gunshi 处理）以及 Ashigaru 内部的模型路由，通过 capability_tiers 实现（详见动态模型路由部分）。

布鲁姆认知分类法 → 智能体路由

任务依据布鲁姆认知分类法进行划分，并被路由到相应的智能体，而非模型：

Karo 会为每个子任务分配一个布鲁姆层次，并将其路由到合适的智能体。L1–L3 的任务会交给 Ashigaru 并行执行；L4–L6 的任务则会交由 Gunshi 进行更深入的分析。对于简单的 L4 任务（如小型代码审查），如果 Karo 认为合适，仍可交由 Ashigaru 处理。

任务依赖关系（blockedBy）

任务可以通过 blockedBy 声明对其他任务的依赖关系：

# queue/tasks/ashigaru2.yaml
task:
  task_id: subtask_010b
  blockedBy: ["subtask_010a"]  # 等待 ashigaru1 的任务完成
  description: "集成由 subtask_010a 构建的 API 客户端"

当阻塞任务完成后，Karo 会自动解除依赖任务的阻塞状态，并将其分配给可用的 Ashigaru。这样可以避免空等，实现依赖工作的高效流水线处理。

动态模型路由（capability_tiers）

除了代理级别的路由之外，您还可以在 Ashigaru 层级内配置模型级别的路由。在 config/settings.yaml 中定义一个 capability_tiers 表，将每个模型映射到其最大 Bloom 级别：

capability_tiers:
  gpt-5.3-codex-spark:
    max_bloom: 3       # 仅限 L1–L3：快速、高容量任务
    cost_group: chatgpt_pro
  gpt-5.3-codex:
    max_bloom: 4       # L1–L4：增加分析和调试功能
    cost_group: chatgpt_pro
  claude-sonnet-4-6:
    max_bloom: 5       # L1–L5：增加设计评估功能
    cost_group: claude_max
  claude-opus-4-6:
    max_bloom: 6       # L1–L6：支持新型架构与战略规划
    cost_group: claude_max

cost_group 字段将每个模型与您的订阅计划关联起来，从而避免系统将任务路由到您订阅计划未涵盖的模型。

有两个内置技能可以帮助您进行配置：

设置完成后，请运行 /shogun-bloom-config 来生成最适合您的 capability_tiers 配置。

哲学

“不要盲目执行任务。始终牢记‘最快×最佳输出’。”

Shogun 系统建立在五个核心原则之上：

这些原则已在文档中详细说明：docs/philosophy.md

设计哲学

为什么采用层级结构（Shogun → Karo → Ashigaru）？

1. 即时响应：Shogun 会立即委派任务，并将控制权交还给您。
2. 并行执行：Karo 会同时将任务分发给多个 Ashigaru。
3. 单一职责：每个角色分工明确，不会产生混淆。
4. 可扩展性：增加更多 Ashigaru 不会影响整体结构。
5. 故障隔离：一个 Ashigaru 出现故障不会影响其他 Ashigaru。
6. 统一报告：只有 Shogun 会与您沟通，确保信息井然有序。

为什么使用信箱系统？

为什么不直接使用代理之间的消息传递，而是采用文件方式呢？

代理标识 (@agent_id)

每个窗格都设有 @agent_id tmux 用户选项（例如 karo、ashigaru1）。虽然 pane_index 会在窗格重新排列时发生变化，但 @agent_id 是在启动时由 shutsujin_departure.sh 设置的，且永远不会改变。

代理自我识别：

tmux display-message -t "$TMUX_PANE" -p '#{@agent_id}'

其中 -t "$TMUX_PANE" 是必需的。如果省略，则会返回当前焦点窗格的值，从而导致错误识别。

模型名称存储为 @model_name，当前任务摘要存储为 @current_task——两者都会显示在 pane-border-format 中。即使 Claude Code 覆盖了窗格标题，这些用户选项仍会保留。

为什么只有 Karo 更新 dashboard.md？

1. 单一写入者：通过限制更新权限至一个代理，避免冲突。
2. 信息汇总：Karo 会接收所有 Ashigaru 的报告，因此掌握全局情况。
3. 一致性：所有更新都经过统一的质量审核。
4. 不打断工作：如果由 Shogun 更新，可能会打断主人的操作。

技能

系统默认不包含任何技能。技能是在实际操作过程中自然产生的——您只需从 dashboard.md 中发现并批准合适的候选技能即可。

调用技能的方式是输入 /技能名。只需告诉 Shogun：“运行 /技能名”。

内置技能（已提交至仓库）

技能随仓库一起提供，位于 skills/ 目录下。它们是领域无关的实用工具，对任何用户都很有用：

这些工具可以帮助您配置和操作系统。而针对个人工作流程的技能，则会通过自下而上的发现过程自然成长。

技能哲学

1. 个人技能不会提交到仓库

.claude/commands/ 中的技能出于设计目的被排除在版本控制之外：

• 每位用户的 workflow 都不同。
• 不应强加通用技能，而应让每位用户根据自身需求逐步构建自己的技能体系。

2. 技能的发现过程

Ashigaru 在工作中注意到某种模式
    ↓
出现在 dashboard.md 的“技能候选”部分
    ↓
您（主人）审查该提案
    ↓
若批准，则指示 Karo 创建该技能

技能完全由用户驱动。如果由系统自动创建，将会导致技能膨胀，难以管理——只保留真正有用的技能即可。

MCP 设置指南

MCP（Model Context Protocol）服务器可以扩展 Claude 的功能。以下是设置步骤：

什么是 MCP？

MCP 服务器可以让 Claude 访问外部工具：

• Notion MCP → 读取和写入 Notion 页面
• GitHub MCP → 创建 PR、管理问题
• Memory MCP → 在会话之间持久化记忆

安装 MCP 服务器

使用以下命令添加 MCP 服务器：

# 1. Notion - 连接到您的 Notion 工作区
claude mcp add notion -e NOTION_TOKEN=your_token_here -- npx -y @notionhq/notion-mcp-server

# 2. Playwright - 浏览器自动化
claude mcp add playwright -- npx @playwright/mcp@latest
# 注意：请先运行 `npx playwright install chromium`

# 3. GitHub - 仓库操作
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_pat_here -- npx -y @modelcontextprotocol/server-github

# 4. 顺序思维 - 针对复杂问题的逐步推理
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

# 5. 内存 - 跨会话长期记忆（推荐！）
# ✅ 由 first_setup.sh 自动配置
# 如需手动重新配置：
claude mcp add memory -e MEMORY_FILE_PATH="$PWD/memory/shogun_memory.jsonl" -- npx -y @modelcontextprotocol/server-memory

验证安装

claude mcp list

所有服务器都应显示“已连接”状态。

现实世界用例

该系统可以管理所有白领工作，而不仅仅是代码相关任务。项目可以存储在你文件系统的任何位置。

示例 1：研究冲刺

你：“调研前五名 AI 编程助手，并进行比较”

发生过程：
1. 将军委派给卡罗
2. 卡罗分配：
   - 步兵 1：调研 GitHub Copilot
   - 步兵 2：调研 Cursor
   - 步兵 3：调研 Claude Code
   - 步兵 4：调研 Codeium
   - 步兵 5：调研 Amazon CodeWhisperer
3. 所有 5 名步兵同时开展调研
4. 结果汇总到 dashboard.md 文件中

示例 2：PoC 准备

你：“为这个 Notion 页面上的项目准备一个 PoC：[URL]”

发生过程：
1. 卡罗通过 MCP 获取 Notion 内容
2. 步兵 2 列出需要验证的事项
3. 步兵 3 探究技术可行性
4. 步兵 4 拟定 PoC 计划
5. 所有结果汇总到 dashboard.md 文件中——会议准备工作完成

配置

语言

# config/settings.yaml
language: ja   # 仅使用武士日语
language: en   # 使用武士日语 + 英文翻译

截图集成

# config/settings.yaml
screenshot:
  path: "/mnt/c/Users/YourName/Pictures/Screenshots"

只需告诉将军“查看最新的截图”，它就会读取你的屏幕截图以获取视觉上下文。（在 Windows 上使用 Win+Shift+S 快捷键。）

ntfy（手机通知）

# config/settings.yaml
ntfy_topic: "shogun-yourname"

在手机上的 ntfy 应用中订阅相同的主题。监听器会随 shutsujin_departure.sh 自动启动。

ntfy 认证（自托管服务器）

公共的 ntfy.sh 实例无需认证——上述设置即为全部所需。

如果你运行的是启用了访问控制的自托管 ntfy 服务器，则需要配置认证：

# 1. 复制示例配置文件
cp config/ntfy_auth.env.sample config/ntfy_auth.env

# 2. 使用你的凭据编辑（选择一种方式）

优先级：令牌 > 基本 > 无。若两者均未设置，则不会发送认证头信息（向后兼容）。

config/ntfy_auth.env 文件不会被提交到 Git 中。详细信息请参阅 config/ntfy_auth.env.sample。

进阶

┌─────────────────────────────────────────────────────────────────────┐
│                    首次设置（仅需运行一次）                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  install.bat (Windows)                                              │
│      │                                                              │
│      ├── 检查并指导 WSL2 的安装                              │
│      └── 检查并指导 Ubuntu 的安装                            │
│                                                                     │
│  first_setup.sh (在 Ubuntu/WSL 中手动运行)                        │
│      │                                                              │
│      ├── 检查并安装 tmux                                         │
│      ├── 检查并安装 Node.js v20+（通过 nvm）                      │
│      ├── 检查并安装 Claude Code CLI（原生版本）                   │
│      │       ※ 如果检测到 npm 版本，则建议迁移                   │
│      └── 配置 Memory MCP 服务器                                │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                    每日启动（每天运行）                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  shutsujin_departure.sh                                             │
│      │                                                              │
│      ├──▶ 创建 tmux 会话                                          │
│      │         • “shogun” 会话（1 个窗格）                          │
│      │         • “multiagent” 会话（9 个窗格，3x3 格式）          │
│      │                                                              │
│      ├──▶ 重置队列文件和仪表板                                   │
│      │                                                              │
│      └──▶ 在所有代理上启动 Claude Code                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

# 默认：完整启动（tmux 会话 + 启动 Claude Code）
./shutsujin_departure.sh

# 仅设置会话（不启动 Claude Code）
./shutsujin_departure.sh -s
./shutsujin_departure.sh --setup-only

# 清理任务队列（保留命令历史）
./shutsujin_departure.sh -c
./shutsujin_departure.sh --clean

# 战斗阵型：所有步兵启用 Opus（最大能力，成本较高）
./shutsujin_departure.sh -k
./shutsujin_departure.sh --kessen

# 默音模式：关闭战斗口号（节省 echo 调用的 API 令牌）
./shutsujin_departure.sh -S
./shutsujin_departure.sh --silent

# 完整启动 + 打开 Windows Terminal 标签页
./shutsujin_departure.sh -t
./shutsujin_departure.sh --terminal

# 将军仅中继模式：禁用将军的思考（节省成本）
./shutsujin_departure.sh --shogun-no-thinking

# 显示帮助
./shutsujin_departure.sh -h
./shutsujin_departure.sh --help

./shutsujin_departure.sh          # 启动所有组件
tmux attach-session -t shogun     # 连接并下达指令

./shutsujin_departure.sh -s       # 仅创建会话

# 手动在特定代理上启动 Claude Code
tmux send-keys -t shogun:0 'claude --dangerously-skip-permissions' Enter
tmux send-keys -t multiagent:0.0 'claude --dangerously-skip-permissions' Enter

# 杀死现有会话
tmux kill-session -t shogun
tmux kill-session -t multiagent

# 重新启动
./shutsujin_departure.sh

alias csst='cd /mnt/c/tools/multi-agent-shogun && ./shutsujin_departure.sh'
alias css='tmux attach-session -t shogun'      # 连接到 Shogun
alias csm='tmux attach-session -t multiagent'  # 连接到 Karo + Ashigaru

文件结构

multi-agent-shogun/
│
│  ┌──────────────── 设置脚本 ────────────────────┐
├── install.bat               # Windows: 首次设置
├── first_setup.sh            # Ubuntu/Mac: 首次设置
├── shutsujin_departure.sh    # 每日部署（自动加载指令）
│  └──────────────────────────────────────────────────┘
│
├── instructions/             # 代理行为定义
│   ├── shogun.md             # Shogun 指令
│   ├── karo.md               # Karo 指令
│   ├── ashigaru.md           # Ashigaru 指令
│   ├── gunshi.md             # Gunshi（战略家）指令
│   └── cli_specific/         # CLI 特定工具描述
│       ├── claude_tools.md   # Claude Code 工具与功能
│       └── copilot_tools.md  # GitHub Copilot CLI 工具与功能
│
├── lib/
│   ├── agent_status.sh       # 共享的繁忙/空闲检测（Claude Code + Codex）
│   ├── cli_adapter.sh        # 多 CLI 适配器（Claude/Codex/Copilot/Kimi）
│   └── ntfy_auth.sh          # ntfy 认证辅助工具
│
├── scripts/                  # 实用脚本
│   ├── agent_status.sh       # 显示所有代理的繁忙/空闲状态
│   ├── inbox_write.sh        # 将消息写入代理收件箱
│   ├── inbox_watcher.sh      # 使用 inotifywait 监控收件箱变化
│   ├── switch_cli.sh         # 实时切换 CLI/模型（/exit → 重新启动）
│   ├── ntfy.sh               # 向手机发送推送通知
│   └── ntfy_listener.sh      # 流式接收来自手机的消息
│
├── config/
│   ├── settings.yaml         # 语言、ntfy 等设置
│   ├── ntfy_auth.env.sample  # 自托管 ntfy 认证模板
│   └── projects.yaml         # 项目注册表
│
├── projects/                 # 项目详细信息（不包含在 git 中，包含机密信息）
│   └── <project_id>.yaml    # 每个项目的完整信息（客户、任务、Notion 链接等）
│
├── queue/                    # 通信文件
│   ├── shogun_to_karo.yaml   # Shogun → Karo 命令
│   ├── ntfy_inbox.yaml       # 来自手机的传入消息（ntfy）
│   ├── inbox/                # 每个代理的收件箱文件
│   │   ├── shogun.yaml       # 发送给 Shogun 的消息
│   │   ├── karo.yaml         # 发送给 Karo 的消息
│   │   └── ashigaru{1-8}.yaml # 发送给每个 Ashigaru 的消息
│   ├── tasks/                # 每个工人的任务文件
│   └── reports/              # 工人报告
│
├── saytask/                  # 基于行为心理学的激励机制
│   └── streaks.yaml          # 连续记录和每日进度
│
├── templates/                # 报告和上下文模板
│   ├── integ_base.md         # 整合：基础模板
│   ├── integ_fact.md         # 整合：事实调查
│   ├── integ_proposal.md     # 整合：提案
│   ├── integ_code.md         # 整合：代码审查
│   ├── integ_analysis.md     # 整合：分析
│   └── context_template.md   # 通用的七部分项目背景
│
├── skills/                   # 可重用技能（已提交到仓库）
│   ├── skill-creator/        # 技能创建模板
│   ├── shogun-agent-status/  # 代理状态显示
│   ├── shogun-model-list/    # 模型能力参考
│   ├── shogun-bloom-config/  # Bloom 层级配置
│   ├── shogun-model-switch/  # 实时 CLI/模型切换
│   └── shogun-readme-sync/   # README 同步
│
├── memory/                   # 内存 MCP 持久化存储
├── dashboard.md              # 实时状态板
└── CLAUDE.md                 # 系统指令（自动加载）

项目管理

该系统不仅管理自身的开发，还管理 所有白领任务。项目文件夹可以位于此仓库之外。

工作原理

config/projects.yaml          # 项目列表（仅包含 ID、名称、路径和状态）
projects/<project_id>.yaml    # 每个项目的完整详细信息

• config/projects.yaml：一个简要的项目列表
• projects/<id>.yaml：完整的项目详情（客户信息、合同、任务、相关文件、Notion 页面等）
• 项目文件（源代码、文档等）存储在 path 指定的外部文件夹中
• projects/ 不包含在 git 中（包含机密的客户信息）

示例

# config/projects.yaml
projects:
  - id: client_x
    name: "Client X Consulting"
    path: "/mnt/c/Consulting/client_x"
    status: active

# projects/client_x.yaml
id: client_x
client:
  name: "Client X"
  company: "X Corporation"
contract:
  fee: "monthly"
current_tasks:
  - id: task_001
    name: "系统架构评审"
    status: in_progress

这种分离方式使得 Shogun 系统能够在多个外部项目之间进行协调，同时将项目细节排除在版本控制之外。

故障排除

# 重新运行 first_setup.sh
./first_setup.sh

# 如果检测到 npm 版本：
# ⚠️ 检测到 Claude Code CLI 的 npm 版本（已正式弃用）
# 是否安装原生版本？[Y/n]:

# 选择 Y 后，卸载 npm 版本：
npm uninstall -g @anthropic-ai/claude-code

ToolSearch("select:mcp__memory__read_graph")
mcp__memory__read_graph()

tmux attach-session -t multiagent

# 按 Ctrl+B 再按 0-8 切换窗格

# 方法 1：直接在窗格中运行 claude
claude --model opus --dangerously-skip-permissions

# 方法 2：Karo 通过 respawn-pane 强制重启（同时解决嵌套问题）
tmux respawn-pane -t shogun:0.0 -k 'claude --model opus --dangerously-skip-permissions'

tmux 快速参考

鼠标支持

first_setup.sh 会自动在 ~/.tmux.conf 中配置 set -g mouse on，从而启用直观的鼠标控制：

即使您不熟悉键盘快捷键，也可以仅使用鼠标切换、滚动和调整窗格大小。

v3.5 新功能 — 动态模型路由

为不同任务选择合适的模型——无需重启任何代理。 Sonnet 4.6 在 SWE-bench 上与 Opus 的差距缩小到仅 1.2pp（79.6% vs 80.8%），这使得基于任务的模型路由首次变得实用且经济高效。

• Bloom 动态模型路由 — config/settings.yaml 中的 capability_tiers 将每个模型与其 Bloom 上限对应起来。L1–L3 → Spark（1000+ tok/s），L4 → Sonnet 4.6，L5 → Sonnet 4.6 + 扩展思考，L6 → Opus（仅用于真正新颖的设计）。路由无需重启代理——系统会根据模型能力找到合适的空闲代理。
• Sonnet 4.6 成为新标准 — SWE-bench 得分为 79.6%，仅比 Opus 4.6 低 1.2pp。Gunshi 已将默认模型从 Opus 更改为 Sonnet 4.6。所有 Ashigaru 默认使用 Sonnet 4.6。只需更改一行 YAML 文件，无需重启。
• /shogun-model-list 技能 — 完整参考表：所有 CLI 工具 × 模型 × 订阅 × Bloom 最大级别。针对 Sonnet 4.6 和 Spark 的定位进行了更新。
• /shogun-bloom-config 技能 — 交互式配置工具：回答关于您的订阅的两个问题→即可获得可直接粘贴的 capability_tiers YAML。

v3.3.2 新功能 — GPT-5.3-Codex-Spark 支持

新模型，相同 YAML。 在任何 Codex 代理的 settings.yaml 中添加 model: gpt-5.3-codex-spark。

• Codex --model 标志支持 — build_cli_command() 现在会通过 --model 将 settings.yaml 中的模型配置传递给 Codex CLI。支持 gpt-5.3-codex-spark 以及未来的所有 Codex 模型。
• 独立速率限制 — Spark 使用自己的速率限制配额，与 GPT-5.3-Codex 无关。可以在不同的 Ashigaru 中并行运行这两种模型，以 将有效吞吐量提高一倍。
• 启动显示 — shutsujin_departure.sh 现在会显示实际的模型名称（例如 codex/gpt-5.3-codex-spark），而不是通用的努力等级。

v3.0 新功能 — 多 CLI

Shogun 不再仅限于 Claude。 可以在一个团队中混合搭配 4 种 AI 编码 CLI。

• 多 CLI 作为一级架构 — lib/cli_adapter.sh 会根据代理动态选择 CLI。只需更改 settings.yaml 中的一行，即可在 Claude Code、Codex、Copilot 或 Kimi 之间切换任何工作进程。
• OpenAI Codex CLI 集成 — GPT-5.3-codex 配合 --dangerously-bypass-approvals-and-sandbox 实现真正的自主执行。--no-alt-screen 使代理活动在 tmux 中可见。
• CLI 绕过标志发现 — --full-auto 并非完全自动（实际上是 -a on-request）。已记录下所有 4 种 CLI 的正确标志。
• 混合架构 — 指挥层（Shogun + Karo）仍使用 Claude Code，以便实现 Memory MCP 和邮箱集成。工作层（Ashigaru）则与 CLI 无关。
• 社区贡献的 CLI 适配器 — 感谢 @yuto-ts（cli_adapter.sh）、@circlemouth（Codex 支持）、@koba6316（任务路由）。

贡献

欢迎提交问题和拉取请求。

• Bug 报告：请开一个包含复现步骤的问题
• 功能建议：请先发起讨论
• 技能：技能设计为个人专属，因此不包含在本仓库中

致谢

基于 Akira-Papa 的 Claude-Code-Communication。

许可证

MIT

multi-agent-shogun 快速上手指南

multi-agent-shogun 是一个受日本封建军队层级启发的多智能体编排系统。它允许你通过简单的自然语言指令，并行调度多达 10 个 AI 编码助手（如 Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code），实现零协调开销的高效开发。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统:
  • Linux / macOS: 原生支持。
  • Windows: 必须安装 WSL2 (Ubuntu)。
• 核心依赖:
  • tmux (终端复用器)
  • bash 4.0 或更高版本
  • git
• AI 工具 (至少安装其中一个):
  • Claude Code (推荐，功能最全)
  • OpenAI Codex CLI
  • GitHub Copilot CLI
  • Kimi Code CLI
• 网络环境: 由于涉及多个 AI 服务的 API 调用，请确保网络通畅。国内用户建议使用稳定的代理工具或加速方案。

安装步骤

1. 克隆项目

打开终端，运行以下命令下载源码：

git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun

2. 初始化配置

运行一次性设置脚本，该脚本会自动检查依赖、配置环境变量并设置 MCP (Model Context Protocol)：

bash first_setup.sh

注意 (首次使用): 如果你使用的是 Claude Code，设置完成后需要运行一次认证命令：

source ~/.bashrc
claude --dangerously-skip-permissions

按提示在浏览器中登录 Anthropic 账号，并在终端确认授权 ("Yes, I accept")，最后输入 /exit 退出。

3. 启动系统

运行出征脚本，系统将自动启动所有配置的 Agent（包括 1 个指挥官 Karo, 7 个执行者 Ashigaru, 1 个军师 Gunshi）：

bash shutsujin_departure.sh

启动后，你将看到一个基于 tmux 的分屏仪表盘，实时显示各个智能体的工作状态。

基本使用

系统启动后，所有操作均在 Shogun pane (通常位于顶部或显著位置) 中进行。

下达指令

直接在 Shogun 面板中输入自然语言指令。无需编写复杂的 Prompt 或 JSON 配置。

示例：

"Build a REST API for user authentication" (构建一个用于用户认证的 REST API)

工作流程

1. 接收: Shogun 接收你的指令。
2. 分解: Karo (管理者) 自动将大任务拆解为多个子任务。
3. 执行: 7 个 Ashigaru (工作者) 并行执行子任务，Gunshi (军师) 提供策略支持。
4. 监控: 你可以在仪表盘中实时看到每个 Agent 的输出日志和进度。
5. 完成: 任务结束后，代码将直接生成在你的项目目录中。

移动端控制 (可选)

如果你需要在手机上监控或下达指令，该项目提供了专用的 Android App：

1. 确保服务器端已开启 SSH (sudo service ssh start)。
2. 在手机安装 android/release/multi-agent-shogun.apk。
3. 在 App 设置中配置 SSH 连接信息（IP、端口、密钥/密码、项目路径）。
4. 即可通过手机语音或文字远程控制 AI 军团。

现在，像封建领主一样指挥你的 AI 大军吧！