Kuroco Admin Api

Kuroco Admin API Skill

概要

Kuroco管理API（admin_api）を kuroco-admin CLIで操作するスキル。

admin_apiの5つのモード:

• whoami: セッション情報の取得 — member_id, name, group_ids を返す
• discover: 利用可能なモジュール・コントローラの探索
• schema: コントローラ/サービスのリクエスト・レスポンススキーマ取得
• advise: 自然言語でやりたいことを伝えると、呼ぶべきAPIと手順をAIが回答
• execute: APIの実行（GET/POST） — --columnsでレスポンスカラム選択可能

認証方式: kuroco-admin login でセッションCookieを ~/.kuroco-admin/cookies.txt に永続化。以降のコマンドは自動的にCookieを送信。

前提条件:

• Bun ランタイムがインストール済み
• kuroco-admin CLI がビルド済みまたはPATHに追加済み
• kuroco-admin login --url <管理画面URL> でログイン済み
• すべての操作はログイン中ユーザーの権限で実行される

最小操作フロー（読み取り: 2-3回、書き込み: 3-4回の tool call）:

1. Bash: 認証チェック（kuroco-admin whoami --json）

2. Bash: API構造把握（kuroco-admin discover --json または kuroco-admin advise "やりたいこと" --json）

3. （書き込み時） Bash: スキーマ取得（kuroco-admin help topics/topics_edit --json）

4. Bash: API実行（kuroco-admin exec ...）

>

advise が最も効率的。 やりたいことを自然言語で伝えるだけで、呼ぶべきAPI・手順・パラメータをAIが回答する。mt/ctが不明な場合はまず advise を使う。

---

セットアップ

インストール

# CLI ソースディレクトリ
cd /path/to/admin_cli

# ビルド（スタンドアロンバイナリ）
bun build --compile kuroco-admin.ts --outfile kuroco-admin

# PATHに追加（任意）
cp kuroco-admin /usr/local/bin/

ログイン

kuroco-admin login --url https://example.g.kuroco-mng.app
# → メールアドレスとパスワードを対話的に入力
# → ~/.kuroco-admin/config.json と cookies.txt が保存される

---

操作フロー

すべてのAPI操作はこのフローに従うこと。

Step 1: 認証チェック

kuroco-admin whoami --json

• 成功（exit 0） → {"success":true,"data":{"member_id":...}} が返る → Step 2 へ
• 失敗（exit 2） → セッション切れ。kuroco-admin login --url <URL> で再ログイン

Step 2: API構造把握

目的に応じて3つの方法を使い分ける:

方法A: advise（AI支援、推奨）

やりたいことを自然言語で伝えると、呼ぶべきAPIと手順をAIが回答:

kuroco-admin advise "記事を新しく作成したい" --json

レスポンスの steps にmt/ct/http_method/mode/endpointが含まれる。endpoint と api_spec はシステム自動生成（ハルシネーションなし）。summary, description, body_example はAI生成。

方法B: discover（モジュール・コントローラ一覧）

# 全モジュール一覧
kuroco-admin discover --json

# 特定モジュールのコントローラ一覧
kuroco-admin discover --mt topics --json

方法C: help（スキーマ取得）

特定コントローラのリクエスト/レスポンススキーマ:

kuroco-admin help topics/topics_edit --json

使い分け:

| 方法 | 用途 |

|------|------|

| advise（推奨） | やりたいことからAPI手順をAIが提案（mt/ctが不明な場合） |

| discover | プログラム的にモジュール/コントローラを列挙 |

| help | 特定コントローラのフィールド定義・型・必須項目を確認 |

Step 3: スキーマ取得（書き込み操作では必須）

書き込み操作（INSERT/UPDATE）では必ずスキーマを取得してフィールド構造を確認:

kuroco-admin help topics/topics_edit --json

レスポンスはJSON Schema形式。data.request.properties にフィールド定義、data.request.required に必須フィールドが格納される。

ext_colを含むスキーマが必要な場合:

help コマンドでは topics_group_id を指定できないため、exec で直接取得:

kuroco-admin exec --param MODE=schema --mt topics --ct topics_edit --param topics_group_id=99 --json

注意:

- topics_group_id を省略すると汎用フィールドのみ（ext_colが含まれない）

- topics_group_id を指定するとブロックエディタ・拡張項目のフィールド名（ext_1, ext_14 等）、型、必須フラグが取得できる

- list系コントローラ（topics_list等）はスキーマが空を返すため、書き込み用コントローラ（topics_edit）を指定すること

- レスポンスの x-kuroco-type でフィールドの種類（wysiwyg, json, checkbox, file 等）がわかる

Step 4: API実行

認証確認・構造把握が完了したら、API実行パターンに従ってAPIを実行する。

Step 5: 認証失敗・セッション切れ対応

exit code 2（AUTH_ERROR / SESSION_EXPIRED / LOGIN_REQUIRED）が返った場合: 1. ユーザーに再ログインが必要な旨を伝える 2. kuroco-admin login --url <URL> を実行 3. ログイン後に再度操作

複数ステップの操作中に認証エラーが発生した場合: 1. 即座に操作を停止 2. どこまで成功したかをユーザーに報告 3. 再ログインを案内 4. 再認証後、未完了の操作から再開

---

API実行パターン

パラメータ形式

kuroco-admin exec では module/controller のショートハンド形式、または --mt/--ct 個別指定が使える。

# ショートハンド形式（推奨）
kuroco-admin exec topics/topics_list --json

# 個別指定
kuroco-admin exec --mt topics --ct topics_list --json

注意: model/method 形式は使用しないこと。HTMLが返却される場合がある。必ず mt/ct 形式を使用する。

GETリクエスト（一覧取得・検索）

# 基本的な一覧取得（columns + cnt で最小限のレスポンス）
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param cnt=10 \
  --columns topics_id,subject,ymd \
  --json

# 検索・フィルタリング
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param keyword=検索語 \
  --param cnt=20 \
  --columns topics_id,subject \
  --json

# ページネーション
kuroco-admin exec topics/topics_list \
  --param "topics_group_id[]=1" \
  --param pageID=2 \
  --param cnt=20 \
  --json

columns原則: GETリクエストでは常に --columns を指定。対応エンドポイントではサーバー側フィルタリング、非対応でも無視されるだけなので常に指定して問題ない。

POSTリクエスト（作成・更新・削除）

# 新規作成（INSERT）
kuroco-admin exec topics/topics_edit_api \
  --MODE INSERT \
  --data '{"subject":"タイトル","contents":"本文","topics_group_id":1}' \
  --json

# 更新（UPDATE）
kuroco-admin exec topics/topics_edit_api \
  --MODE UPDATE \
  --data '{"topics_id":123,"subject":"更新後タイトル"}' \
  --json

# 削除（DELETE）
kuroco-admin exec topics/topics_edit_api \
  --MODE DELETE \
  --data '{"topics_id":123}' \
  --json

dry-run（プレビュー）

実行前にリクエスト内容を確認:

kuroco-admin exec topics/topics_edit_api \
  --MODE INSERT \
  --data '{"subject":"テスト"}' \
  --dry-run

サービス呼び出し

コントローラ（小文字開始）とサービス（大文字開始）を自動判別:

# コントローラ: 小文字開始
kuroco-admin exec topics/topics_list --json

# サービス: 大文字開始（PHP側で自動検出）
kuroco-admin exec Email/send --data '{"to":"user@example.com","subject":"件名"}' --json

重要なルール

詳細は references/cli-commands.md を参照

---

レスポンス構造

成功レスポンス（--json）

{
  "success": true,
  "data": { ... },
  "errors": []
}

エラーレスポンス（--json）

{
  "success": false,
  "data": null,
  "errors": [{ "code": "API_ERROR", "message": "..." }]
}

リストレスポンスのキー

レスポンス内のリスト配列のキーは ct に対応:

ページネーション

{
  "pageInfo": {
    "totalCnt": 150,
    "perPage": 20,
    "totalPageCnt": 8,
    "pageNo": 1
  }
}

---

エラーハンドリング

Exit Codes

詳細は references/error-handling.md を参照

---

モジュール関係マップ

主要な親子関係。親のIDが子の操作に必須:

TopicsGroup → Topics         (topics_group_id 必須)
MemberGroup → Member         (group_id 必須)
InquiryForm → InquiryMessage (inquiry_id 必須)
TagCategory → Tag            (tag_category_id 必須)

操作前に親のlistで利用可能なグループを確認:

kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json

詳細は references/api-discovery.md を参照

---

セキュリティ注意事項

• Cookie値を表示・ログ出力しないこと — ~/.kuroco-admin/cookies.txt はmode 0o600で保護
• `--verbose` の出力をユーザーに見せない — HTTPヘッダーにCookie値が含まれる
• 変更操作は必ずユーザー確認後に実行 — INSERT/UPDATE/DELETEは取り消しが困難
• `--dry-run` を活用 — 書き込み前にリクエスト内容をプレビュー
• APIレスポンスのファイル保存はユーザー同意必須 — 個人情報を含む可能性

---

アンチパターン

---

並列実行

独立したAPI呼び出しは複数の Bash tool call を同時に発行して並列実行可能:

# 別々のBash tool callで同時発行
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json
kuroco-admin exec member/member_group_list --columns group_id,group_nm --json

---

他スキルとの連携

本スキルはCLI経由のadmin_api実行に特化。 フロントエンドAPI（*.g.kuroco.app）の操作には上記の関連スキルを使用。

API探索パターン

探索の3つの方法

1. advise: AI支援（推奨）

やりたいことを自然言語で伝えると、呼ぶべきAPIと手順をAIが回答:

kuroco-admin advise "記事を新しく作成したい" --json

レスポンスの steps にmt/ct/http_method/mode/endpointが含まれる。

• endpoint, api_spec → システム自動生成（正確、ハルシネーションなし）
• summary, description, body_example → AI生成

2. discover: モジュール/コントローラ一覧

# 全体概要
kuroco-admin discover --json

# 特定モジュールの詳細
kuroco-admin discover --mt topics --json

レスポンス構造:

{
  "modules": [
    {
      "mt": "topics",
      "controllers": [
        { "ct": "topics_list", "url": "..." },
        { "ct": "topics_edit", "url": "..." }
      ]
    }
  ],
  "services": [...]
}

3. help: フィールドスキーマ

kuroco-admin help topics/topics_edit --json

JSON Schema形式で data.request.properties にフィールド定義、data.request.required に必須フィールドを返す。

ext_colを含むスキーマが必要な場合:

kuroco-admin exec --param MODE=schema --mt topics --ct topics_edit --param topics_group_id=99 --json

---

使い分け

---

モジュール関係マップ

主要な親子関係。親のIDが子の操作に必須:

TopicsGroup → Topics         (topics_group_id 必須)
MemberGroup → Member         (group_id 必須)
InquiryForm → InquiryMessage (inquiry_id 必須)
TagCategory → Tag            (tag_category_id 必須)

親の一覧を先に確認:

kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json

操作のコツ:

• Topics操作前にTopicsGroupのlistで利用可能なグループを確認
• Member操作前にMemberGroupで所属グループを確認
• 不明な場合はdiscoverまたはadviseで必須パラメータを確認

---

ページネーション

# 1ページ目
kuroco-admin exec topics/topics_list --param "topics_group_id[]=1" --param cnt=20 --param pageID=1 --json

# 2ページ目
kuroco-admin exec topics/topics_list --param "topics_group_id[]=1" --param cnt=20 --param pageID=2 --json

レスポンスの pageInfo:

{
  "totalCnt": 150,
  "perPage": 20,
  "totalPageCnt": 8,
  "pageNo": 1
}

---

並列実行

独立したAPI呼び出しは複数の Bash tool call を同時に発行して並列実行可能:

# 別々のBash tool callで同時発行
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json
kuroco-admin exec member/member_group_list --columns group_id,group_nm --json

CLI コマンドリファレンス

グローバルオプション

---

login

認証してセッションを保存。

kuroco-admin login --url https://example.g.kuroco-mng.app

オプション:

• --url <url> (必須): Kuroco管理画面のURL

動作: 1. メールアドレスとパスワードを対話的に入力 2. /management/login/login/ にPOST 3. セッションCookieを ~/.kuroco-admin/cookies.txt に保存（mode 0o600） 4. 設定を ~/.kuroco-admin/config.json に保存（mode 0o600） 5. whoami で認証を確認

---

whoami

現在のセッション情報を表示。

kuroco-admin whoami --json

レスポンス:

{
  "success": true,
  "data": {
    "member_id": 123,
    "name1": "太郎",
    "name2": "山田",
    "group_ids": [1, 2],
    "expiresAt": "2026-03-05T00:00:00+09:00",
    "status": "ok"
  },
  "errors": []
}

---

discover

利用可能なモジュール・コントローラ・サービスを一覧。

# 全モジュール
kuroco-admin discover --json

# 特定モジュールのみ
kuroco-admin discover --mt topics --json

オプション:

• --mt <module> (任意): モジュールでフィルタ

レスポンス:

{
  "success": true,
  "data": {
    "modules": [
      {
        "mt": "topics",
        "controllers": [
          { "ct": "topics_list", "url": "..." },
          { "ct": "topics_edit", "url": "..." }
        ]
      }
    ],
    "services": [...]
  },
  "errors": []
}

---

help (schema)

コントローラ/サービスのスキーマ取得。

# コントローラのスキーマ
kuroco-admin help topics/topics_edit --json

# サービスのスキーマ
kuroco-admin help Email/send --json

引数:

• [target]: module/controller 形式（例: topics/topics_edit）。大文字開始の Model/method 形式（例: Email/send）はサービスのスキーマ取得に使用。

注意: exec でのAPI実行では常に mt/ct 形式（小文字）を使用すること。model/method 形式はHTMLが返却される場合がある。help（スキーマ取得）ではどちらの形式も安全に使用可能。

レスポンス: JSON Schema形式で data.request.properties にフィールド定義、data.request.required に必須フィールドが含まれる。

ext_colを含むスキーマ:

help コマンドは追加パラメータを受け付けないため、ext_colが必要な場合は exec で代用:

kuroco-admin exec --param MODE=schema --mt topics --ct topics_edit --param topics_group_id=99 --json

---

exec

APIを実行。

# GET（ショートハンド）
kuroco-admin exec topics/topics_list --json --columns topics_id,subject

# GET（個別指定）
kuroco-admin exec --mt topics --ct topics_list --param cnt=10 --json

# POST（作成）
kuroco-admin exec topics/topics_edit_api --MODE INSERT --data '{"subject":"新規"}' --json

# dry-run
kuroco-admin exec topics/topics_edit_api --MODE INSERT --data '{"subject":"テスト"}' --dry-run

オプション:

HTTPメソッド自動判定:

• --MODE または --data 指定 → POST
• それ以外 → GET

target形式の自動判別:

• 小文字開始 → コントローラ（例: topics/topics_list）
• 大文字開始 → サービス（例: Email/send、PHP側で自動検出）

---

advise

やりたいことからAPI手順をAIが提案。

kuroco-admin advise "記事を新しく作成したい" --json

引数:

• <query> (必須): 自然言語でやりたいこと

レスポンスの `steps`:

---

設定ファイル

エラーハンドリング・復旧

Exit Codes

エラーレスポンス形式（--json）

{
  "success": false,
  "data": null,
  "errors": [
    { "code": "API_ERROR", "message": "Server returned 500" }
  ]
}

---

エラー別対処

Exit Code 2: 認証エラー

# セッション確認
kuroco-admin whoami --json
# → exit code 2 → 再ログイン

kuroco-admin login --url https://example.g.kuroco-mng.app

復旧手順: 1. 操作を即座に停止 2. ユーザーにセッション切れを報告（どこまで成功したか） 3. kuroco-admin login --url <URL> で再ログイン 4. kuroco-admin whoami --json で認証を確認 5. 未完了の操作から再開

Exit Code 1: パラメータエラー（INVALID_PARAM / API_ERROR 400）

1. エラーメッセージを確認 2. kuroco-admin help module/controller --json でスキーマ確認 3. パラメータを修正して再実行

よくある原因:

• GET配列パラメータに [] が付いていない（topics_group_id → topics_group_id[]）
• 必須パラメータの欠落（topics_group_id等）
• 型の不一致（文字列を送るべきところに数値など）

Exit Code 1: ネットワークエラー（NETWORK_ERROR）

1. kuroco-admin whoami --json で接続を確認 2. baseURLが正しいか確認（~/.kuroco-admin/config.json） 3. 1回だけ再試行

Exit Code 1: サーバーエラー（API_ERROR 500）

1. リクエスト内容が正しいか確認（--dry-run でプレビュー） 2. 1回のみ再試行 3. 再現する場合はユーザーに報告

---

APIバリデーションエラー

400エラーのレスポンスボディ:

{
  "errors": [
    {"field": "subject", "message": "This field is required"},
    {"field": "topics_group_id", "message": "Invalid value"}
  ]
}

---

レスポンス構造の確認

リストのプロパティ名が不明な場合、--json 出力のトップレベルキーを確認:

原則: プロパティ名を推測せず、レスポンスのキーを確認してから操作する。

---

リトライ方針

---

複数ステップ操作での復旧

途中でエラーが発生した場合: 1. 即座に操作を停止 2. どこまで成功したかをユーザーに報告 3. 認証エラーなら再ログインを案内 4. 再認証後、未完了の操作から再開

---

デバッグ

--verbose フラグでHTTPリクエスト/レスポンスの詳細をstderrに出力:

kuroco-admin exec topics/topics_list --param cnt=1 --json --verbose

注意: --verbose の出力にはCookie値が含まれる。デバッグ時のみ使用し、出力をユーザーと共有しないこと。