This commit is contained in:
oss-sync
@@ -620,6 +620,41 @@ grep -n "a2a_delegations\|a2a_skills" src/db/repository.ts
|
||||
|
||||
---
|
||||
|
||||
## 16. OSS リリース（`scripts/oss-sync.sh --push`）を実行するとき
|
||||
|
||||
- **スクリーンショットの目視確認（必須）**: `docs/screenshots/*.png` はバイナリのため、release gate（`oss/forbidden.txt` の正規表現スキャン）では**描画内容を検査できない**。スクリーンショットを更新した場合は、push 前に各画像を開いて以下が写り込んでいないか目視で確認する
|
||||
- 内部ホスト名・URL（Gitea / 社内サービスのアドレスバー等）
|
||||
- 実在のタスクタイトル・会話内容・ファイル名
|
||||
- ユーザー名・メールアドレス・組織名
|
||||
- 資格情報やトークンの断片（設定画面のマスク漏れ）
|
||||
- 撮り直しの手順は README スクリーンショット刷新時のレシピ（隔離 worktree + シードデータ）に従い、実データ環境のキャプチャをそのまま使わない
|
||||
|
||||
---
|
||||
|
||||
## 17. 承認パーク型 META ツール（RequestTool / RequestPackage）を追加・変更する場合
|
||||
|
||||
エージェントが「これが欲しい」と申告 → 人が承認 → ジョブ再開、という停車型ツールの配線点。RequestPackage（PR3）は RequestTool を全面ミラーしている。片方だけ直すと不整合になるので、両方を並べて確認すること。
|
||||
|
||||
**対象ファイル（RequestPackage を例に）:**
|
||||
- `src/engine/tools/package-request.ts` — ツール本体（`TOOL_DEFS` + `executeTool`）。バリデーションは `engine/python-packages.ts` の `parseAndValidateSpec` / `assertNotShadowing` を再利用
|
||||
- `src/engine/tools/core.ts` — `ToolContext` に park フラグ（`pendingPackageApproval`）+ recorder（`recordPackageRequest`）+ 補助状態（`installedPackages` / `declinedPackages`）
|
||||
- `src/engine/tools/index.ts` — module loader / `Object.assign(allDefs, ...)` / **`META_TOOLS` 配列（2 箇所）** / dispatch 分岐
|
||||
- `src/engine/tools/tool-categories.ts` — `META_TOOLS` Set にツール名を追加
|
||||
- `src/engine/agent-loop/pending-states.ts` — `buildPackageApprovalWaitResult`（park → `next:'WAITING_HUMAN_PACKAGE_REQUEST'`）
|
||||
- `src/engine/agent-loop.ts` — import + `buildToolApprovalWaitResult` の隣で呼ぶ
|
||||
- `src/engine/piece-runner.ts` — `WAITING_HUMAN_PACKAGE_REQUEST` sentinel 分岐（waiting_human park）+ **2 つの PieceRunOptions interface** に recorder/補助状態を追加 + ctx 構築で piece/movement を注入
|
||||
- `src/worker.ts` — recorder を task/job/space にバインド（feature enabled かつ space 解決可のときのみ）+ waiting_human 分岐で **`wait_reason='package_request'` を永続化**（忘れると resume がマッチせず永久停止）
|
||||
- **DB（三重ミラー）**: `src/db/schema.sql` / `src/db/migrate.ts` / `src/db/repositories/schema.ts`（`package_requests` テーブル）+ `src/db/repositories/tool-requests.ts`（record/get/list/decide/revert/listDeclined + 型 + rowMapper）+ `src/db/repositories/jobs.ts`（`resumePackageRequestJob` + `createJobIfNoPending` の承認ポーズ判定）。実装は `repositories/*` に置き、`src/db/repository.ts` ファサードに委譲メソッドを足す（`repository.ts` は肥大分割済みの薄いファサード）
|
||||
- `src/bridge/local-tasks-package-requests-api.ts` — GET 一覧（view 権限）+ POST decide（**task write 権限＝ owner/admin/space editor のみ**、エージェント自己承認不可）。承認時のインストールは `space-python-packages-service.ts` の共有パスを通す
|
||||
- `src/bridge/local-tasks-api.ts` — ルート登録 + `LocalTasksApiOptions` に config アクセサ / `server.ts` で配線
|
||||
- `ui/src/components/chat/PackageRequestApproval.tsx` + `ChatPane.tsx` + `ui/src/api/tasks.ts` + i18n `chat.json`（ja/en）
|
||||
- `docs/tools/requestpackage.md`（ReadToolDoc）+ ヘルプ + changelog
|
||||
|
||||
**なぜ必要か:**
|
||||
停車系は「ジョブ停車＝ワーカー解放」で成り立つ（ツール内同期ブロックはデッドロック）。sentinel（`WAITING_HUMAN_*`）は tool → pending-states → agent-loop → piece-runner → **worker（wait_reason 永続化）** の全経路が揃って初めて機能する。承認 API は必ず write 権限ゲートを通し、インストールは共有サービス（bwrap 必須 fail-closed / wheels のみ / 固定 index / shadowing 拒否）経由に限定する。
|
||||
|
||||
---
|
||||
|
||||
## 自動検知の可能性
|
||||
|
||||
- **ツールモジュール登録漏れ**: `index.ts` と `tools-api.ts` のモジュール一覧を比較するスクリプトで CI チェック可能
|
||||
|
||||
Reference in New Issue
Block a user