98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# SearchNotes / ReadNote / WriteNote
|
||
|
||
ユーザーの共有 knowledge notes（`data/users/{userId}/notes/{folder}/{file}.md`）を扱う 3 ツール。
|
||
ファイルは YAML frontmatter + Markdown 本文で構成され、DB の `note_index` (FTS5 対応) に mirror される。
|
||
|
||
## SearchNotes
|
||
|
||
購読中（`note_subscriptions` に `mode=search` または `mode=inject`、`enabled=1` の行がある）の note を FTS5 全文検索する。
|
||
|
||
### 引数
|
||
|
||
| フィールド | 型 | 必須 | 説明 |
|
||
|---|---|---|---|
|
||
| `query` | string | 必須 | 検索クエリ。ツール内部でフレーズ検索として扱われる |
|
||
| `folder` | string | 省略可 | 特定フォルダーのみに絞り込む |
|
||
| `limit` | integer | 省略可 | 最大取得件数（デフォルト 10、上限 100） |
|
||
|
||
### 戻り値
|
||
|
||
マッチした note のリスト（`owner_id/folder/file_name: title`）。
|
||
続いて `ReadNote` で全文を取得できる。
|
||
|
||
### FTS5 クエリの注意
|
||
|
||
クエリはフレーズ検索として自動エスケープされる。`kubernetes pod` → `"kubernetes pod"` に変換。
|
||
AND / OR 演算子を使いたい場合は複数回呼び出して結果を手動合算すること。
|
||
|
||
---
|
||
|
||
## ReadNote
|
||
|
||
特定の note の全文（frontmatter + 本文）を取得。可視性チェックあり。
|
||
|
||
### 引数
|
||
|
||
| フィールド | 型 | 必須 | 説明 |
|
||
|---|---|---|---|
|
||
| `owner_id` | string | 必須 | note の所有者 user ID |
|
||
| `folder` | string | 必須 | フォルダー名 |
|
||
| `file_name` | string | 必須 | ファイル名（例: `foo.md`） |
|
||
|
||
### 可視性ルール
|
||
|
||
- 自分の note（owner_id が自分）: 常に読める
|
||
- `visibility: public` の note: 全ユーザーが読める
|
||
- `visibility: org` の note: `scope_org_id` が自分の所属 org に含まれる場合のみ読める
|
||
- `visibility: private` の他人の note: 読めない（isError: true）
|
||
|
||
---
|
||
|
||
## WriteNote
|
||
|
||
自分の `notes/{folder}/{file}.md` を作成または更新する。
|
||
|
||
### 引数
|
||
|
||
| フィールド | 型 | 必須 | 説明 |
|
||
|---|---|---|---|
|
||
| `folder` | string | 必須 | フォルダー名（`[a-zA-Z0-9._-]` のみ） |
|
||
| `file_name` | string | 必須 | ファイル名（`.md` で終わる） |
|
||
| `content` | string | 必須 | YAML frontmatter を含む完全な Markdown 内容 |
|
||
|
||
### Frontmatter フィールド
|
||
|
||
```yaml
|
||
---
|
||
title: "Note のタイトル（省略可）"
|
||
visibility: public # private | org | public
|
||
scope_org_id: "org-id" # visibility=org の場合に必須（自分の所属 org の ID）
|
||
mode_hint: search # search | inject（省略可）
|
||
tags:
|
||
- kubernetes
|
||
- security
|
||
---
|
||
```
|
||
|
||
- `visibility` は必須。省略すると `private` として扱われる
|
||
- `visibility: org` の場合、`scope_org_id` は自分の所属 org の ID でなければならない
|
||
- `mode_hint: inject` にすると、購読者の system prompt に自動注入される
|
||
- フォルダーとファイル名は固定の 2 階層（`notes/<folder>/<file>.md`）
|
||
|
||
### 書き込み後の動作
|
||
|
||
- DB の `note_index` + FTS5 テーブルを即座に更新
|
||
- 同フォルダーへの self subscription がなければ自動作成（`mode=search`、`enabled=1`）
|
||
- エラー時は `isError: true` を返す（バリデーションエラーや権限エラー）
|
||
|
||
---
|
||
|
||
## 使い分け
|
||
|
||
| 場面 | ツール |
|
||
|---|---|
|
||
| 「CVE 対象?」「〜の設定は?」など知識検索 | `SearchNotes("CVE")` |
|
||
| 検索結果の 1 件の詳細を読む | `ReadNote` |
|
||
| スケジュールタスクで取得した情報をチームと共有 | `WriteNote`（`visibility: org`） |
|
||
| 自分用のメモ・ログを残す | `WriteNote`（`visibility: private`） |
|