tsubaiso ti-local-automation — ローカル API スクリプティング（任意 API 操作の機構）
標準 MCP ツールで届かない PSA/IMA 操作を、AI がローカルで生成したスクリプトが、本人権限内の Salesforce API を直接呼んで行う能力スキル。ファイル添付＋公開リンク発行は同梱レシピの一つ。
原則: 大きなデータ（ファイルのバイト列等）を AI の会話に載せない（パス／ディスク経由でスクリプトが直接読む）。書込は承認・ドライランを通す。認証・接続は再実装せず ti-rollout の本人接続（api スコープ ECA）を使う。
前提（認証・接続）
- 本人権限内の api スコープ OAuth トークン（専用 ECA・ローカル本人認証）を使う。準備・認証の手順は ti-rollout
references/api-eca-setup.mdが持つ（本スキルでは再掲しない）。トークンは OS キーチェーンに保管。 - できることは常に本人が Salesforce でできる範囲に限られる（越権しない）。
このスキルが持つもの・持たないもの
| 持つ（任意 API 操作の機構） | 持たない（委譲先） |
|---|---|
| ローカルスクリプトによる REST/Tooling/Bulk/Composite/バイナリ操作 | 認証・接続の準備＝ti-rollout |
| ファイル添付＋公開リンク発行レシピ（ContentVersion/ContentDistribution） | 業務データ一括移行の型・機構＝ti-data-load |
| 大容量/バイナリを壊さず授受（会話を経由しない） | メタデータ定義の配備＝ti-metadata |
| — | 書込前の構造ゲート・型・API 名＝ti-reference |
発火点（いつ・何を読む/呼ぶ）
| チェックポイント | 読む／呼ぶ |
|---|---|
| そのセッションで最初に TI のスキルを使う瞬間（依頼の内容を問わず・1 セッション 1 回） | ti-core references/version-freshness.md（同梱の版と公開されている最新版を照合） |
| 製品の操作手順・可否・理由を書こうとした瞬間／製品そのもの（コード・フロー・項目ヘルプ・パッケージのメタデータ）を読もうとした瞬間／実測と期待の食い違いを不具合と書こうとした瞬間／作業の対象範囲を自分で数え上げようとした瞬間 | ti-core references/knowledge-lookup.md（推測で挙動を組み立てず、ナレッジを引く） |
| org へ書き込む直前（作成・更新・添付・Bulk・Composite） | ti-core references/safety-gate.md（承認ドラフト提示・ドライラン→人が承認） |
| 書込前の構造ゲート・API 名・型が要る瞬間 | ti-reference references/write-index.md |
| 認証・接続が未準備 | ti-rollout（本人接続の準備・api スコープ ECA） |
| 大量の業務データ投入・移行 | ti-data-load（型と機構） |
| API 呼び出しのラッパ・ヘルパを書く／書き換える瞬間 | 本スキル §失敗を握りつぶさない |
| 同じ依頼が繰り返し来た／大量件数を頼まれた／スクリプトにするか AI が直接やるか迷う瞬間 | ti-core references/automation-decision.md（いつスクリプト化するかの判断。本スキルは書き方だけを持つ） |
| 繰り返し詰まる摩擦／機能不足を検知 | ti-core references/feedback.md |
レシピ
- ファイル添付＋公開リンク: 商談等へ ContentVersion をマルチパートで添付（
FirstPublishLocationIdで対象レコードへ紐付け）→ ContentDistribution で公開リンク（パスワードなし・期限指定）発行 → URL 返却。ファイル本体は会話に載せずパス／ディスク経由（実証済み・15MB 破損なし）。公開リンクはパスワードなしなら URL を知る誰でもアクセス可になるため、発行時の safety-gate 承認ドラフトに**公開範囲（URL を知る誰でも／期限）**を明記し、必要ならパスワード付き・短期限を選ぶ。 - ライブラリの特定フォルダへ配置:
FirstPublishLocationIdにライブラリ（ContentWorkspace）を指定してアップロード（フォルダ ID の直指定は本番で受け付けられないことがある）→ 生成されたContentFolderMemberのParentContentFolderIdを目的フォルダ（ContentFolder）へ更新して移動。パスワード付き・無期限等は ContentDistribution のPreferencesPasswordRequired／PreferencesExpiresで指定（本番実証済み）。 - （順次追加）一括更新（Bulk/upsert のうち移行に当たらない稼働後の少量〜中量）、Composite での複数レコード一括作成、独自 Apex REST 呼び出し 等。
失敗を握りつぶさない [REQUIRED]
API 呼び出しは失敗を既定で例外にする。エラーを戻り値へ畳んで返すヘルパを書くと、呼び出し側がそれを捨てられるようになり、製品が返した理由を読まないまま挙動を推測する経路ができる。
| # | 何を | どう |
|---|---|---|
| 1 | HTTP 4xx / 5xx | 例外にする。本文（message / errorCode / fields）をそのまま添える |
| 2 | invocable アクションの isSuccess: false |
HTTP は 200 で返るので別に見る。errors[].message を添えて例外にする |
| 3 | composite / Bulk の部分失敗 | 全体が 200 でも子が失敗する。1 件でも失敗したら例外にする |
呼び出し結果を受け取らない書き方をしない。 戻り値を変数に入れずに呼ぶ、受け取って参照しない、のどちらも上の 3 つを無効化する。
作成・更新が通らなかったことは、製品が経路を止めた合図であり、多くの場合その理由も一緒に返っている。読まずに次のフラグを当てにいくと、原因を製品側だと解釈した誤った断定が残る。
顧客レシピの作成・配布（標準/顧客固有の2層）
ベータとして先行提供している機能です。 記述が変わることがあります。扱いは ti-core の
references/beta-status.mdを参照してください。ベータなのは本節が扱う顧客レシピの作成・配布だけで、ローカルスクリプトによる API 操作そのものは正式提供です。
本スキルは土台（レシピ実行の型＋認証＋safety-gate）を提供する。汎用の標準レシピは本スキル（Tsubaiso Intelligence Skill＝ツバイソ標準の配布物）に置く。顧客業務固有のレシピはツバイソ標準の配布物に入れず、顧客が自社プラグイン（別リポジトリ／別マーケットプレイス）に置いて社内配布する（ツバイソ標準の定期更新との衝突を避けるため）。
顧客レシピの作り方（作成・配布キット）:
- 自社プラグインを用意する（Cowork のプラグイン作成。作成手順はクライアント側の公式ドキュメントに従う）。
- レシピを書く: 確定論的スクリプト＋使い方＋safety-gate 注記。認証は本スキルが使う ECA（
ti-rolloutの本人接続・api スコープ）を再利用する（新設不要。ECA の構成正本はti-rollout references/api-eca-setup.md）。 - 検証 org で確認（ドライラン・本人権限内）。
- レビュー承認（誰がレシピを足せるかを顧客側で決める＝顧客の管理者/開発担当が承認する）。
- 自社プラグインとして社内配布 → 各ユーザーの AI が利用。
統制は 3 ゲートが層をまたいで効く: 実行＝ECA 権限セット（保有者のみ・本人権限内・フェイルクローズ）／作成＝レビュー承認／書込＝safety-gate。L1（本スキル・標準）と L2（顧客固有）はリポジトリを分離し、参照は L2→L1 の一方向のみとする（L1 が L2 を参照しないため、ツバイソ標準の更新が顧客レシピに引きずられない）。
原則
- 本人権限内・最小権限。書込は承認・ドライラン。削除は既定で行わない。
- 大きなデータを AI の会話に通さない（パス／ディスク経由でスクリプトが直接扱う）。
- 認証・機構の重複を作らない（接続＝ti-rollout、型＝ti-reference、移行＝ti-data-load へ委譲）。本スキルは「任意 API を叩く機構」に徹する。
- 利用者向け出力の規律は ti-core
references/output-discipline.mdが正本（業務語へ翻訳し、レコードはリンク化する。鍵値も出さない）。本スキルへ書き写さず、レコードを示す出力を書く直前に読む。