@geekbeer/minion 3.57.0 → 3.58.0

package/docs/api-reference.md

@@ -504,7 +504,7 @@ POST `/api/threads` body (プロジェクト紐づきディスカッション):
 | `thread_type` | string | No | `help`（デフォルト）or `discussion` |
 | `title` | string | Yes | スレッドの要約 |
 | `content` | string | Yes | スレッド本文（thread_messagesの最初のメッセージとして保存） |
-| `mentions` | string[] | No | メンション対象。形式: `role:engineer`, `role:pm`, `minion:<minion_id>`, `user` |
+| `mentions` | string[] | No | メンション対象。形式: `user:<auth_user_id>` (個別指名・推奨), `role:engineer`, `role:pm`, `role:accountant`, `minion:<minion_id>`, `user` (誰でも良い場合のフォールバック) |
 | `context` | object | No | 任意のメタデータ（category, urgency, dag_execution_id等） |
 
 **プロジェクト紐づけの使い分け:**
@@ -520,7 +520,11 @@ POST `/api/threads` body (プロジェクト紐づきディスカッション):
 - メンションされたミニオンは優先的にスレッドを評価する
 - メンションがない場合、全チームメンバーがLLMで関連性を判定してから参加
 - トークン消費を抑えるため、当事者が明確な場合はメンションを推奨
-- ミニオンが自力で解決できない場合、`@user` メンション付きで返信して人間に助けを求める
+
+**人間へのメンション (重要):**
+1. **個別指名 `user:<auth_user_id>`** を最優先で使う。`/api/minion/me/project/:id/members` または `/api/minion/workspaces/:id/members` で人間メンバーの `user_id` を引いてから指定する。同名 `display_name` が複数いるワークスペースでも誤通知しない
+2. **`role:pm` / `role:engineer` / `role:accountant`** はプロジェクトの該当ロール全員に届く（プロジェクト紐づきスレッドのみ）
+3. **`user` (generic)** はプロジェクトメンバーの人間全員に届く。プロジェクト紐づきでないワークスペーススレッドでは workspace_members 全員。「誰でも良い」場合のフォールバック扱いで、原則 1 か 2 を先に検討する
 
 POST `/api/threads/:id/messages` body:
 ```json
@@ -811,6 +815,46 @@ Response:
 
 `role` is one of `"pm"` (project manager), `"engineer"`, or `"accountant"`.
 
+### Project Members
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/me/project/[id]/members` | プロジェクトのメンバー一覧（ミニオン+人間） |
+
+Response:
+```json
+{
+  "minions": [
+    { "minion_id": "uuid", "name": "Mary", "status": "online", "role": "pm", "joined_at": "..." }
+  ],
+  "humans": [
+    { "user_id": "uuid", "display_name": "yunoda", "email": "yunoda@example.com", "role": "engineer", "joined_at": "..." }
+  ]
+}
+```
+
+スレッドに `user:<auth_user_id>` で個別指名する前に、このエンドポイントで `user_id` を引いてくる。`display_name` が重複するワークスペースで誤通知を避けるため、ミニオンは必ず `email` または既知の `user_id` で当人を特定すること。`role` はプロジェクトロール (`pm` / `engineer` / `accountant`)。
+
+### Workspace Members
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/[id]/members` | ワークスペースのメンバー一覧（人間+ミニオン） |
+
+Response:
+```json
+{
+  "humans": [
+    { "user_id": "uuid", "display_name": "yunoda", "email": "yunoda@example.com", "role": "owner", "joined_at": "..." }
+  ],
+  "minions": [
+    { "minion_id": "uuid", "name": "Mary", "status": "online", "joined_at": "..." }
+  ]
+}
+```
+
+プロジェクト紐づきがないワークスペーススレッド（朝作業ルーティンのブロッカー報告など）でメンション先を引きたいときに使う。`role` はワークスペースロール (`owner` / `admin` / `member`)。
+
 ### Project Context
 
 | Method | Endpoint | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.57.0",
+  "version": "3.58.0",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/roles/engineer.md

@@ -28,7 +28,9 @@
 
 1. **まずプロジェクトメモリーを検索** — `GET /api/project-memories?project_id=...&search=キーワード` で過去の知見を確認
 2. **自己解決不可なら即ヘルプスレッドを起票** — `POST /api/threads` で `thread_type: "help"` を作成。`attempted_resolution` に試したことを記載
-3. **人間にしか解決できない問題は `mentions: ["user"]` で即エスカレーション** — 認証コード、パスワード、外部承認など
+3. **人間にしか解決できない問題は即エスカレーション** — 認証コード、パスワード、外部承認など
+   - 当事者が特定できる場合は **`GET /api/minion/me/project/<project_id>/members` で `user_id` を引いて `mentions: ["user:<auth_user_id>"]` で個別指名** (display_name 重複時の誤通知を避けるため)
+   - 誰でも対応可能な問題なら `mentions: ["user"]` (generic)
 4. **解決後はスレッドを resolve し、知見をプロジェクトメモリーに保存**
 
 **スキルを失敗終了させる前に、必ずヘルプスレッドでエスカレーションすること。**

package/roles/pm.md

@@ -48,14 +48,18 @@ PMとして、ブロッカーの解決を主導する責務がある:
 
 ### 自分がブロッカーに遭遇した場合
 1. **プロジェクトメモリーを検索** — 過去の知見で解決できないか確認
-2. **自己解決不可なら `mentions: ["user"]` でヘルプスレッドを起票** — PMが解決できない問題は人間にエスカレーション
+2. **自己解決不可ならヘルプスレッドを起票** — PMが解決できない問題は人間にエスカレーション
+   - 特定の人にしか分からない問題なら **`GET /api/minion/me/project/<project_id>/members` で `user_id` を引いて `mentions: ["user:<auth_user_id>"]` で個別指名**
+   - 誰でも良い性質の問題なら `mentions: ["user"]` (generic)
 3. **解決後はスレッドを resolve し、知見をプロジェクトメモリーに保存**
 
 ### エンジニアからのヘルプスレッドに対応する場合
 1. **thread_watcher が自動で通知するので、`role:pm` 宛のスレッドに回答する**
-2. **自分で解決できない場合は `@user` メンション付きで人間にエスカレーション**
+2. **自分で解決できない場合は人間にエスカレーション** — 当事者が特定できるなら個別指名 (`user:<auth_user_id>`)、不明なら `user` (generic)
 3. **解決策が汎用的なら、プロジェクトメモリーへの保存を促す**
 
+display_name はワークスペース内で一意とは限らない。同名問題を避けるため、**generic `user` より個別指名 (`user:<id>`) を優先する**こと。`user_id` の取得方法は `~/.minion/docs/api-reference.md` の「Project Members / Workspace Members」セクションを参照。
+
 詳細は `~/.minion/rules/core.md` の「Blocker Handling」セクションを参照。
 
 ## Routine (従来方式)

package/rules/core.md

@@ -322,7 +322,8 @@ API詳細は `~/.minion/docs/api-reference.md` の「Todos」セクションを
      "thread_type": "help",
      "title": "問題の要約（1行）",
      "content": "状況の詳細説明",
-     "mentions": ["role:pm"],
+     "mentions": ["user:<auth_user_id>"],  // 特定の人に聞くなら個別指名 (推奨)
+                                            // 誰でも良いなら ["user"] / ["role:pm"] 等
      "context": {
        "category": "auth|environment|external-service|information|approval",
        "attempted_resolution": "試行した内容"
@@ -336,7 +337,7 @@ API詳細は `~/.minion/docs/api-reference.md` の「Todos」セクションを
      "thread_type": "help",
      "title": "問題の要約（1行）",
      "content": "状況の詳細説明",
-     "mentions": ["user"],
+     "mentions": ["user:<auth_user_id>"],  // 個別指名 (推奨)。誰でも良いなら ["user"]
      "context": {
        "category": "auth|environment|external-service|information|approval",
        "attempted_resolution": "試行した内容"
@@ -366,18 +367,25 @@ API詳細は `~/.minion/docs/api-reference.md` の「Todos」セクションを
 
 ### メンションの使い分け
 
-| 状況 | メンション |
-|------|-----------|
-| PMに判断を仰ぐ | `["role:pm"]` |
-| エンジニアの知見が必要 | `["role:engineer"]` |
-| 特定ミニオンに聞く | `["minion:<minion_id>"]` |
-| 人間の介入が必要（認証コード、承認等） | `["user"]` |
-| チーム全体に共有 | `[]`（メンションなし） |
+| 状況 | メンション | 備考 |
+|------|-----------|------|
+| 特定の人間を指名（推奨） | `["user:<auth_user_id>"]` | 事前に Members API で `user_id` を解決すること |
+| PMに判断を仰ぐ | `["role:pm"]` | プロジェクト紐づきスレッドのみ有効 |
+| エンジニアの知見が必要 | `["role:engineer"]` | プロジェクト紐づきスレッドのみ有効 |
+| 特定ミニオンに聞く | `["minion:<minion_id>"]` | |
+| 誰でも良いから人間に聞く | `["user"]` | プロジェクト紐づきならプロジェクト人間メンバー、紐づきがなければワークスペース人間メンバー全員 |
+| チーム全体に共有 | `[]`（メンションなし） | |
+
+**人間メンバーの user_id 解決:**
+- プロジェクト紐づきスレッド: `GET /api/minion/me/project/<project_id>/members` で `humans[].user_id` を取得
+- ワークスペーススレッド: `GET /api/minion/workspaces/<workspace_id>/members` で `humans[].user_id` を取得
+
+display_name が同じユーザーが同一ワークスペースに複数いる可能性があるため、原則として個別指名 (`user:<id>`) を優先する。「誰でも良い」場合のみ generic `user` を使う。
 
 ### 重要なルール
 
 - **スレッド起票時は `attempted_resolution` を必ず含める。** 何を試したか不明だと、回答者が同じことを提案してしまう。
-- **人間にしか解決できない問題（認証コード入力、外部サービスのパスワード等）は即 `@user` メンション**で起票する。自己解決を試みて時間を浪費しないこと。
+- **人間にしか解決できない問題（認証コード入力、外部サービスのパスワード等）は即メンション付き** で起票する。自己解決を試みて時間を浪費しないこと。特定の人にしか分からないことなら個別指名 (`user:<id>`)、誰でも良い性質の問題なら `user`(generic) を使う。
 - **ブロッカーが解決したらスレッドを `resolve` する。** 放置しない。
 - **解決策をプロジェクトメモリーに保存する。** 同じブロッカーに再度遭遇する他のミニオンの助けになる。