104 lines
8.2 KiB
Markdown
104 lines
8.2 KiB
Markdown
# SearchWorkspaceTasks
|
||
|
||
同じワークスペース（スペース）内の**他タスク**の会話を横断検索する META ツール（全 piece で常時利用可能）。`SearchTaskConversation` が現在タスクの会話だけを検索するのに対し、こちらは「同じスペースの他タスクで前に何を頼まれたか／どう進めたか」を思い出すための対になるツール。**全文は返さない** — ヒットの一覧（抜粋）だけを返す。前後の全文が必要なら `around_ref` で辿る。
|
||
|
||
## スコープ
|
||
|
||
- 検索対象は**同じスペースの他タスクのみ**。タスクの状態（実行中／完了／中断など）は問わない
|
||
- 呼び出し元がそのスペースの owner またはメンバーであることを前提に、DB クエリ自体がスペース境界で絞り込む。他スペースのタスクには物理的に到達できない
|
||
- no-auth（サインインしていない owner に紐づかない）実行や subtask 実行では、このツール自体が利用できない文脈になる。その場合はエラーではなく「このコンテキストでは利用できません」という案内文を返す
|
||
|
||
## 索引される内容（検索でヒットするテキスト）
|
||
|
||
検索結果の抜粋は、コメント本文そのものではなく**索引用に正規化・墨消しされたテキスト**。索引されるのは次のみ:
|
||
|
||
- ユーザーの依頼・割り込み（request / interjection）
|
||
- エージェントの成果・確認（result / ask）、handoff
|
||
- エージェントの思考（progress の thinking）
|
||
- movement の要約（progress の summary）
|
||
- ツール実行は**ツール名のみ**（例: `tool: WebFetch`）。引数の値やツールの実行結果は一切索引されない
|
||
- 添付ファイルは**ファイル名のみ**を本文末尾に追記して索引する（中身は索引しない）
|
||
|
||
上記に当てはまらない種別（通常の comment、interjection_ack、未知の progress type など）は索引されない＝検索にヒットしない。
|
||
|
||
## パラメータ
|
||
|
||
`query` と `around_ref` はどちらか一方のみ指定する（排他・両方またはどちらも未指定はエラー）。
|
||
|
||
| 名前 | 必須 | 説明 |
|
||
|------|------|------|
|
||
| `query` | ○（`around_ref` と排他） | 検索キーワード。1 語または少数の語を推奨 |
|
||
| `match_mode` | | 複数語の一致方法。`any`（既定）はいずれかの語、`all` はすべての語を含む結果に限定 |
|
||
| `around_ref` | ○（`query` と排他） | `"comment:<id>"` 形式。指定した comment の前後を読む |
|
||
| `context` | | 各ヒットに付す前後コメント件数（grep -C 相当）。既定 0、最大 5 |
|
||
| `limit` | | 最大ヒット件数。既定 10、最大 30（`query` モードのみ） |
|
||
| `kind` | | コメント種別で絞り込む（request/comment/interjection/result/ask/progress/handoff） |
|
||
| `author` | | 発言者で絞り込む |
|
||
| `task_id` | | 特定タスク ID に絞り込む |
|
||
|
||
出力の ref は `task:<id>` / `comment:<id>` の形式。
|
||
|
||
## 検索マッチング
|
||
|
||
日本語も含めた部分一致検索を trigram tokenize の FTS5 インデックスで行う。**3 文字未満の語は trigram で MATCH できないため、そのような語が含まれるクエリは自動的に LIKE（部分一致）にフォールバックする**（挙動は同じだが遅い）。
|
||
|
||
1 語または少数のキーワードで検索する。複数語の既定は `match_mode: "any"` で、いずれかの語を含むコメントを対象に、FTS5 の関連度順で返す。`ログイン 認証` なら「ログイン」だけ、または「認証」だけを含むコメントも候補になり、両方を強く含むコメントほど上位になりやすい。すべての語を含むコメントだけに絞る場合は `match_mode: "all"` を指定する（語順・位置は問わない）。各語は内部で個別に引用してから OR または AND で結合するため、`AND`/`OR`/`NEAR`/`*`/`"` などが語に混ざっても FTS5 演算子としては解釈されない。
|
||
|
||
短い語を含むため LIKE にフォールバックした場合も、`any` は OR、`all` は AND として一致する。LIKE 経路では関連度を計算できないため、結果は新しいコメント順になる。
|
||
|
||
SQLite のビルドが FTS5 に対応していない環境では、検索機能自体が使えない旨のメッセージを返す（エラーにはしない）。
|
||
|
||
## ドリルダウン（`around_ref`）と検索結果の違い
|
||
|
||
**検索結果の抜粋は索引用に墨消しされた要約だが、`around_ref`（および `context` 指定時に付随する前後コメント）は対象コメントの生の本文をそのまま返す。** 同じスペースのメンバーはもともと製品 UI 上でその兄弟タスクの全文を読めるため、同じ信頼境界の中で全文を返すことは越権にならない。つまり「検索は軽量で墨消しされた概観、ドリルダウンは同じ信頼境界内でのフル情報」という設計。
|
||
|
||
## 出力例
|
||
|
||
```md
|
||
## Workspace Task Search Results (query: "認証", 2 hit(s))
|
||
|
||
- task:12 "ログイン画面の改修" / comment:88 user/request 2026-06-20T10:00:00Z
|
||
…既存の認証フローは変更しないでください…
|
||
|
||
- task:12 "ログイン画面の改修" / comment:95 agent/result 2026-06-20T11:30:00Z
|
||
…認証まわりは touch せず、UI だけ差し替えました…
|
||
|
||
前後の文脈をさらに確認するには around_ref: "comment:<id>" を指定してください。
|
||
```
|
||
|
||
```md
|
||
## Workspace Task Search — task:12 "ログイン画面の改修" (comment:88 前後 2 件)
|
||
|
||
- comment:86 user/comment 2026-06-20T09:55:00Z
|
||
質問なんですが、既存の認証部分は今回のスコープに入りますか？
|
||
- comment:88 user/request 2026-06-20T10:00:00Z ←
|
||
既存の認証フローは変更しないでください。UI 差し替えのみでお願いします。
|
||
- comment:90 agent/progress 2026-06-20T10:02:00Z
|
||
了解しました。認証ロジックには触れずに進めます。
|
||
```
|
||
|
||
## 使いどころ
|
||
|
||
- 同じスペースの別タスクで、この件についてすでに依頼・決定が交わされていないか確認する
|
||
- ユーザーに「前にどう言いましたっけ」と聞き直す前に、まず自分で探す
|
||
- 過去タスクの成果物・進め方を参考にする（他タスクの ID や作業内容が分かれば `task_id` で絞り込める）
|
||
|
||
ヒットで判明した恒久的な事実（制約・判断）は `MissionUpdate` の `user_constraints` / `decisions` に pin しておくと、以降の movement でも見失わない。
|
||
|
||
## 関連ツール
|
||
|
||
- `SearchTaskConversation` / `ReadTaskConversation` — 現在タスク自身の会話（コメント＋transcript）を検索・閲覧する。他タスクへは到達できない。こちらは同じスペースの他タスクを横断検索する対
|
||
|
||
## ListWorkspaceTasks（一覧の相棒ツール）
|
||
|
||
内容の検索ではなく「同じワークスペースにどんなタスクがあるか」を俯瞰したいときは `ListWorkspaceTasks` を使う。
|
||
|
||
- `ListWorkspaceTasks({})` — 他タスクを新しい順に一覧（ID・状態・タイトル・piece・最終更新）。既定 20 件、`limit` で最大 50 件
|
||
- `ListWorkspaceTasks({ state: "open" })` — 進行中のみ / `"closed"` — 完了のみ
|
||
- スコープは SearchWorkspaceTasks と同一（同じスペースのみ・現在のタスクは除外）
|
||
- 一覧で目星をつけたら `SearchWorkspaceTasks({ query: "...", task_id: <id> })` で中身を検索する使い方が典型
|
||
|
||
## 0 件時の複合句自動分割（2026-07-24）
|
||
|
||
スペースを含まない日本語の複合句（例: `満月の周期の計算`）は 1 語＝フレーズ完全一致として扱われ、構成語が索引にあっても 0 件になることがある。`match_mode: "any"`（既定）で 0 件だった場合、助詞・句読点で分割した語群（例: `満月 周期 計算`）による再検索が自動で 1 回走り、結果の先頭に分割再検索した旨の注記が付く。最初からスペース区切りの単語で query を書けばこのフォールバックは不要。
|