55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# ReadUserAgents / UpdateUserAgents
|
||
|
||
ユーザーごとの常時指示書 `AGENTS.md` を読み書きするツール。`AGENTS.md` は各タスクのシステムプロンプトに自動注入される「このユーザーが常に守ってほしいこと」を書いた個人ファイル。memory（`UpdateUserMemory`）が事実の断片を貯めるのに対し、`AGENTS.md` は振る舞いの方針そのもの。
|
||
|
||
両ツールは META_TOOL（常時利用可能）。piece の `allowed_tools` に書かなくても使える。per-user 機能なので、認証済みユーザーのコンテキスト（`ctx.userId`）が必要。
|
||
|
||
## ReadUserAgents
|
||
|
||
引数なし。現在の `AGENTS.md` 全文を切り詰めずに返す。**編集前に必ず呼ぶこと** — `replace` は原文と完全一致する文字列が必要で、システムプロンプトへの注入版は 64KB で切り詰められている場合があるため。
|
||
|
||
ファイルが無い／空のときは、その旨と「`append` で新規作成できる」案内を返す（エラーではない）。
|
||
|
||
## UpdateUserAgents
|
||
|
||
`AGENTS.md` を 2 モードで編集する。書き込み前に旧版を `trash/agents-history/AGENTS.md.{timestamp}.bak` に自動退避（直近 10 件を保持）。事故時はそこから復元できる。
|
||
|
||
### パラメータ
|
||
|
||
| 名前 | 必須 | 説明 |
|
||
|---|---|---|
|
||
| `mode` | ○ | `"replace"` または `"append"` |
|
||
| `old_text` | replace時○ | 置換対象の既存文字列。**ちょうど 1 回だけ**一致する必要がある |
|
||
| `new_text` | ○ | replace の置換後テキスト／append で末尾に足すテキスト |
|
||
|
||
### mode="replace"
|
||
|
||
`old_text` を `new_text` に置き換える。コアの `Edit` ツールと同じ「一意一致」セマンティクス。
|
||
|
||
- 0 回一致 → エラー（`ReadUserAgents` で原文を確認するよう促す）
|
||
- 2 回以上一致 → エラー（前後の文脈を含めて一意にするよう促す）
|
||
- ファイルが空 → エラー（`append` を案内）
|
||
|
||
`new_text` 内の `$&` や `$1` は特殊扱いされない（リテラルとして入る）。
|
||
|
||
### mode="append"
|
||
|
||
`new_text` を末尾に追記する。既存末尾の空行を整理し、空行 1 行を挟んで足す。ファイルが空なら `new_text` がそのまま新規ファイルになる。
|
||
|
||
### 制限・エラー
|
||
|
||
- 結果が 64KB を超えると `writeUserAgentsMd` が拒否（`AGENTS.md exceeds 65536 bytes`）
|
||
- `ctx.userId` が無い（認証なし）→ エラー
|
||
- 監査ログ `user_agents_updated`（mode / バイト数 / スナップショット有無）を記録
|
||
|
||
## 典型フロー
|
||
|
||
1. `ReadUserAgents` で現在の内容を取得
|
||
2. ユーザー依頼に応じて `UpdateUserAgents({ mode: "replace", old_text: "...", new_text: "..." })` または `mode: "append"`
|
||
3. 戻り値でバイト数とスナップショット退避を確認
|
||
|
||
## 関連
|
||
|
||
- `UpdateUserMemory` / `ReadUserMemory` — 事実の断片を貯める個人 memory（`docs/tools` の該当 doc 参照）
|
||
- UI からの編集は Settings 経由（HTTP `GET/PUT/DELETE /agents-md`）
|