@geekbeer/minion 3.25.0 → 3.26.0

package/docs/api-reference.md

@@ -117,6 +117,7 @@ curl http://localhost:8080/api/terminal/wsl/status \
 ### Files
 
 Files are stored in `~/files/`. Max upload size: 50MB.
+**バイナリ成果物（PDF、画像、ZIP等）はここに配置する。** ユーザーがHQダッシュボードからダウンロードできる。
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -1448,3 +1449,55 @@ Response:
 
 ローカルエージェントの `/api/project-memories` は上記 HQ API へのプロキシ。
 詳細なリクエスト/レスポンス仕様はローカル API セクションの「Project Memories」を参照。
+
+### Notes (HQ, プロジェクトノート)
+
+プロジェクトに紐づくノート。**テキストベースの成果物（レポート、調査結果、要約等）はノートに保存すること。**
+ノートはHQダッシュボードでユーザーが即座に閲覧・編集・検索でき、バージョン管理もされる。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/projects/:projectId/notes` | プロジェクトのノート一覧。Query: `?status=active&include_content=true` |
+| POST | `/api/minion/projects/:projectId/notes` | ノートを作成しプロジェクトにリンク |
+| GET | `/api/minion/projects/:projectId/notes/:noteId` | ノート詳細（全文含む） |
+| PATCH | `/api/minion/projects/:projectId/notes/:noteId` | ノートを更新（内容変更時にバージョン自動作成） |
+| GET | `/api/minion/projects/:projectId/notes/search?q=keyword` | ノートを全文検索 |
+
+POST `/api/minion/projects/:projectId/notes` body:
+```json
+{
+  "title": "調査レポート: ユーザー行動分析",
+  "content": "## 概要\n..."
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | ノートのタイトル |
+| `content` | string | No | ノートの本文（Markdown） |
+
+PATCH `/api/minion/projects/:projectId/notes/:noteId` body:
+```json
+{
+  "title": "更新されたタイトル",
+  "content": "更新された本文",
+  "change_summary": "データを追加"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | No | 新しいタイトル |
+| `content` | string | No | 新しい本文 |
+| `change_summary` | string | No | 変更の要約（バージョン履歴に記録） |
+
+#### hq CLI ラッパー
+
+```bash
+hq note create <project_id> --title "タイトル" --content "本文"
+hq note create <project_id> --title "タイトル" --file /tmp/report.md
+hq note update <project_id> <note_id> --content "更新内容" --change-summary "修正理由"
+hq note list <project_id>
+hq note get <project_id> <note_id>
+hq note search <project_id> "キーワード"
+```

package/linux/bin/hq

@@ -17,6 +17,13 @@
 #   hq fetch dag-workflow <id>            - Get DAG workflow details (graph, version)
 #   hq fetch dag-execution <id>           - Get DAG execution details (nodes, status)
 #   hq list workspaces                    - List workspaces this minion belongs to
+#   hq note create <project_id> --title "Title" --content "Body" [--file path]
+#                                         - Create a note linked to the project
+#   hq note update <project_id> <note_id> --content "Body" [--title "Title"] [--file path] [--change-summary "summary"]
+#                                         - Update an existing note
+#   hq note list <project_id>             - List notes in the project
+#   hq note get <project_id> <note_id>    - Get a single note with full content
+#   hq note search <project_id> <query>   - Search notes in the project
 #   hq create dag-workflow <body.json>    - Create a DAG workflow (PM only). Body: {project_id, name, graph?, ...}
 #   hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only). Body: {graph?, content?, ...}
 #   hq publish dag-workflow <id>          - Publish the draft as a new version (PM only, validated)
@@ -146,6 +153,11 @@ print_usage() {
   echo "  hq fetch dag-workflow <id>            - Get DAG workflow details" >&2
   echo "  hq fetch dag-execution <id>           - Get DAG execution details" >&2
   echo "  hq list workspaces                    - List workspaces this minion belongs to" >&2
+  echo "  hq note create <project_id> --title \"Title\" --content \"Body\" [--file path]" >&2
+  echo "  hq note update <project_id> <note_id> --content \"Body\" [--title \"Title\"] [--file path]" >&2
+  echo "  hq note list <project_id>             - List notes in the project" >&2
+  echo "  hq note get <project_id> <note_id>    - Get a single note" >&2
+  echo "  hq note search <project_id> <query>   - Search notes in the project" >&2
   echo "  hq create dag-workflow <body.json>    - Create a DAG workflow (PM only)" >&2
   echo "  hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only)" >&2
   echo "  hq publish dag-workflow <id>          - Publish the draft as a new version (PM only)" >&2
@@ -270,6 +282,168 @@ case "${1:-}" in
     esac
     ;;
 
+  note)
+    action="${2:-}"
+    case "$action" in
+      create)
+        project_id="${3:-}"
+        if [ -z "$project_id" ]; then
+          echo "Usage: hq note create <project_id> --title \"Title\" --content \"Body\" [--file path]" >&2
+          exit 1
+        fi
+        shift 3
+        note_title=""
+        note_content=""
+        note_file=""
+        while [ $# -gt 0 ]; do
+          case "$1" in
+            --title) note_title="$2"; shift 2 ;;
+            --content) note_content="$2"; shift 2 ;;
+            --file) note_file="$2"; shift 2 ;;
+            *) echo "Unknown option: $1" >&2; exit 1 ;;
+          esac
+        done
+        if [ -z "$note_title" ]; then
+          echo "Error: --title is required" >&2
+          exit 1
+        fi
+        if [ -n "$note_file" ]; then
+          if [ ! -f "$note_file" ]; then
+            echo "Error: file not found: $note_file" >&2
+            exit 1
+          fi
+          note_content=$(cat "$note_file")
+        fi
+        if [ -z "$note_content" ]; then
+          echo "Error: --content or --file is required" >&2
+          exit 1
+        fi
+        # Build JSON body using jq or python3
+        if command -v jq &>/dev/null; then
+          body=$(jq -n --arg t "$note_title" --arg c "$note_content" '{title: $t, content: $c}')
+        elif command -v python3 &>/dev/null; then
+          body=$(python3 -c "import json,sys; print(json.dumps({'title': sys.argv[1], 'content': sys.argv[2]}))" "$note_title" "$note_content")
+        else
+          echo "Error: jq or python3 is required to build JSON" >&2
+          exit 1
+        fi
+        tmpfile=$(mktemp)
+        echo "$body" > "$tmpfile"
+        send_json_request POST "$BASE_URL/projects/$project_id/notes" "$tmpfile"
+        rm -f "$tmpfile"
+        ;;
+      update)
+        project_id="${3:-}"
+        note_id="${4:-}"
+        if [ -z "$project_id" ] || [ -z "$note_id" ]; then
+          echo "Usage: hq note update <project_id> <note_id> --content \"Body\" [--title \"Title\"] [--file path] [--change-summary \"summary\"]" >&2
+          exit 1
+        fi
+        shift 4
+        note_title=""
+        note_content=""
+        note_file=""
+        change_summary=""
+        while [ $# -gt 0 ]; do
+          case "$1" in
+            --title) note_title="$2"; shift 2 ;;
+            --content) note_content="$2"; shift 2 ;;
+            --file) note_file="$2"; shift 2 ;;
+            --change-summary) change_summary="$2"; shift 2 ;;
+            *) echo "Unknown option: $1" >&2; exit 1 ;;
+          esac
+        done
+        if [ -n "$note_file" ]; then
+          if [ ! -f "$note_file" ]; then
+            echo "Error: file not found: $note_file" >&2
+            exit 1
+          fi
+          note_content=$(cat "$note_file")
+        fi
+        if [ -z "$note_content" ] && [ -z "$note_title" ]; then
+          echo "Error: at least --content, --file, or --title is required" >&2
+          exit 1
+        fi
+        # Build JSON body
+        if command -v jq &>/dev/null; then
+          body="{}"
+          [ -n "$note_title" ] && body=$(echo "$body" | jq --arg t "$note_title" '. + {title: $t}')
+          [ -n "$note_content" ] && body=$(echo "$body" | jq --arg c "$note_content" '. + {content: $c}')
+          [ -n "$change_summary" ] && body=$(echo "$body" | jq --arg s "$change_summary" '. + {change_summary: $s}')
+        elif command -v python3 &>/dev/null; then
+          body=$(python3 -c "
+import json, sys
+d = {}
+if sys.argv[1]: d['title'] = sys.argv[1]
+if sys.argv[2]: d['content'] = sys.argv[2]
+if sys.argv[3]: d['change_summary'] = sys.argv[3]
+print(json.dumps(d))
+" "$note_title" "$note_content" "$change_summary")
+        else
+          echo "Error: jq or python3 is required to build JSON" >&2
+          exit 1
+        fi
+        tmpfile=$(mktemp)
+        echo "$body" > "$tmpfile"
+        # Use PATCH for update
+        response=$(curl -s -w "\n%{http_code}" -X PATCH \
+          -H "Authorization: Bearer $API_TOKEN" \
+          -H "Content-Type: application/json" \
+          --data-binary "@$tmpfile" \
+          "$BASE_URL/projects/$project_id/notes/$note_id")
+        rm -f "$tmpfile"
+        http_code=$(echo "$response" | tail -1)
+        body_out=$(echo "$response" | sed '$d')
+        if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+          echo "$body_out" | format_json
+        else
+          echo "Error: HQ API returned HTTP $http_code" >&2
+          echo "$body_out" >&2
+          exit 1
+        fi
+        ;;
+      list)
+        project_id="${3:-}"
+        if [ -z "$project_id" ]; then
+          echo "Usage: hq note list <project_id>" >&2
+          exit 1
+        fi
+        fetch_resource "$BASE_URL/projects/$project_id/notes?include_content=false"
+        ;;
+      get)
+        project_id="${3:-}"
+        note_id="${4:-}"
+        if [ -z "$project_id" ] || [ -z "$note_id" ]; then
+          echo "Usage: hq note get <project_id> <note_id>" >&2
+          exit 1
+        fi
+        fetch_resource "$BASE_URL/projects/$project_id/notes/$note_id"
+        ;;
+      search)
+        project_id="${3:-}"
+        query="${4:-}"
+        if [ -z "$project_id" ] || [ -z "$query" ]; then
+          echo "Usage: hq note search <project_id> <query>" >&2
+          exit 1
+        fi
+        # URL-encode the query
+        if command -v jq &>/dev/null; then
+          encoded=$(printf '%s' "$query" | jq -sRr @uri)
+        elif command -v python3 &>/dev/null; then
+          encoded=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$query")
+        else
+          encoded="$query"
+        fi
+        fetch_resource "$BASE_URL/projects/$project_id/notes/search?q=$encoded"
+        ;;
+      *)
+        echo "Unknown note action: $action" >&2
+        echo "Usage: hq note {create|update|list|get|search} ..." >&2
+        exit 1
+        ;;
+    esac
+    ;;
+
   *)
     print_usage
     exit 1

package/linux/routes/chat.js

@@ -337,6 +337,22 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
     )
   }
 
+  // File output guidance — always inject on new sessions
+  if (!sessionId) {
+    parts.push(
+      '[ファイル出力ルール]',
+      '成果物の保存先は以下のルールに従うこと。`/home/minion/` 直下にファイルを保存しないこと。',
+      '',
+      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"`',
+      '- **バイナリファイル**（PDF、画像、ZIP等）→ `~/files/` に配置（ユーザーがHQからダウンロード可能）',
+      '- **一時ファイル** → `/tmp/` に配置（作業後に削除）',
+      '',
+      'プロジェクトコンテキストがない場合、テキスト成果物はローカルメモリ（`POST /api/memory`）に保存する。',
+      '詳細は `~/.minion/rules/core.md` の「File Output Rules」セクションを参照。',
+      ''
+    )
+  }
+
   if (context) {
     switch (context.type) {
       case 'skill':

package/package.json

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

package/rules/core.md

@@ -307,6 +307,62 @@ API詳細は `~/.minion/docs/api-reference.md` の「Todos」セクションを
 - **ブロッカーが解決したらスレッドを `resolve` する。** 放置しない。
 - **解決策をプロジェクトメモリーに保存する。** 同じブロッカーに再度遭遇する他のミニオンの助けになる。
 
+## File Output Rules (ファイル出力ルール)
+
+成果物の保存先は以下のルールに従うこと。**`/home/minion/` 直下にファイルを保存してはならない。** ユーザーがHQダッシュボードからアクセスできない場所にファイルを置いても意味がない。
+
+### 保存先の判断基準
+
+| 出力タイプ | 保存先 | 理由 |
+|-----------|--------|------|
+| テキスト（レポート、調査結果、要約、分析結果等） | **ノート** (`hq note create`) | HQダッシュボードで即閲覧・編集・検索可能。バージョン管理もされる |
+| バイナリ（PDF、画像、ZIP、Excel等） | **`~/files/`** | Files API経由でユーザーがダウンロード可能 |
+| コード・設定ファイル | **ワークスペース内の適切なディレクトリ** | プロジェクトのリポジトリやワークスペースに配置 |
+| 一時ファイル（中間データ、一時スクリプト等） | **`/tmp/`** | ユーザーに見せる必要なし。作業後に削除 |
+
+### ノートへの保存 (`hq note` コマンド)
+
+テキストベースの成果物は原則ノートに保存する。ノートはプロジェクトに紐づき、HQダッシュボードで閲覧できる。
+
+```bash
+# ノートを作成（プロジェクトに紐づけ）
+hq note create <project_id> --title "レポートタイトル" --content "本文..."
+
+# 長い内容はファイルから読み込む
+hq note create <project_id> --title "調査結果" --file /tmp/report.md
+
+# 既存ノートを更新
+hq note update <project_id> <note_id> --content "更新された内容"
+
+# ノート一覧を確認
+hq note list <project_id>
+
+# ノート内容を取得
+hq note get <project_id> <note_id>
+
+# ノートを検索
+hq note search <project_id> "キーワード"
+```
+
+### `~/files/` への保存
+
+バイナリファイルやユーザーがダウンロードする必要があるファイルは `~/files/` に配置する。
+
+```bash
+# ファイルを保存（~/files/ 配下に自動配置）
+cp /tmp/output.pdf ~/files/output.pdf
+
+# サブディレクトリで整理も可能
+mkdir -p ~/files/reports/2026-04
+cp /tmp/report.pdf ~/files/reports/2026-04/report.pdf
+```
+
+### プロジェクトコンテキストがない場合
+
+チャットやルーティンなど、プロジェクトに紐づかない作業の場合：
+- テキスト成果物 → ローカルメモリ (`POST /api/memory`) に保存
+- バイナリファイル → `~/files/` に保存
+
 ## Documentation
 
 API仕様やタスク手順の詳細は以下を参照:

package/win/routes/chat.js

@@ -400,6 +400,22 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
     )
   }
 
+  // File output guidance — always inject on new sessions
+  if (!sessionId) {
+    parts.push(
+      '[ファイル出力ルール]',
+      '成果物の保存先は以下のルールに従うこと。`/home/minion/` 直下にファイルを保存しないこと。',
+      '',
+      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"`',
+      '- **バイナリファイル**（PDF、画像、ZIP等）→ `~/files/` に配置（ユーザーがHQからダウンロード可能）',
+      '- **一時ファイル** → `/tmp/` に配置（作業後に削除）',
+      '',
+      'プロジェクトコンテキストがない場合、テキスト成果物はローカルメモリ（`POST /api/memory`）に保存する。',
+      '詳細は `~/.minion/rules/core.md` の「File Output Rules」セクションを参照。',
+      ''
+    )
+  }
+
   if (context) {
     switch (context.type) {
       case 'skill':