kuroco-admin-api

Kuroco Admin API 技能

概要

使用 kuroco-admin CLI 操作 Kuroco 管理 API（admin_api）的技能。

admin_api 的 5 种模式:

• whoami: 获取会话信息 — 返回 member_id、name、group_ids
• discover: 探索可用的模块和控制器
• schema: 获取控制器/服务的请求和响应架构
• advise: 用自然语言描述想要完成的操作，AI 会回答应调用的 API 和步骤
• 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 次工具调用）:

1. Bash: 检查认证（kuroco-admin whoami --json）
2. Bash: 了解 API 结构（kuroco-admin discover --json 或 kuroco-admin advise "やりたいこと" --json）— 如果本技能中的示例等已确定 mt/ct，可省略
3. （写入时） Bash: 获取架构（kuroco-admin help topics/topics_edit --json。如果需要 ext_col，请使用 Step 3 中的 exec --param action=schema 形式）
4. Bash: 执行 API（kuroco-admin exec ...）

advise 最有效率。 只需用自然语言描述想要完成的操作，AI 就会回答应调用的 API、步骤和参数。如果 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 结构

省略条件: 如果根据本技能中的示例或过去的执行结果已确定目标 mt/ct，可省略此步骤（不要重复执行不必要的 discover/advise）。

根据目的选择以下 3 种方法之一:

方法 A: advise（AI 辅助，推荐）

用自然语言描述想要完成的操作，AI 会回答应调用的 API 和步骤:

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（推荐）	AI 根据想要完成的操作建议 API 步骤（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 --mt topics --ct topics_edit --param action=schema --param topics_group_id=99 --json

注意:

• 省略 topics_group_id 时，只会返回通用字段（不包含 ext_col）
• 指定 topics_group_id 后，可获取区块编辑器和扩展字段的字段名（例如 ext_1、ext_14）、类型及必填标记
• list 类控制器（如 topics_list）会返回空架构，因此请指定用于写入的控制器（topics_edit）
• 获取架构的 ct 和执行操作的 ct 可能不同。对于 Topics，已确定“获取架构 = topics_edit，执行 INSERT/UPDATE/DELETE = topics_edit_api”。其他模块用于执行操作的 ct 请通过 discover / advise 的结果确认
• 可通过响应中的 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。

参数	说明	示例
mt	模块名（小写）	topics、member、inquiry
ct	控制器名	topics_list、topics_edit、member_list

# ショートハンド形式（推奨）
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 を指定（action=schema 等のメタ情報取得は対象外）。対応エンドポイントではサーバー側フィルタリング、非対応でも無視されるだけなので常に指定して問題ない。

keyword の挙動: デフォルトではタイトル（subject）・本文・カテゴリ・拡張項目を対象とした部分一致検索。スペース区切りは AND 検索、英数字の大文字小文字は区別しない。対象カラムは target_col_for_keyword で絞り込み可能（詳細: kuroco-docs reference/keyword-search-types.md）。

パラメータ挙動の確認: 上記以外でパラメータの正確な挙動が本スキルに記載されていない場合は kuroco-admin help <mt>/<ct> --json で定義を確認する。

クォート規約: シェルに解釈されうる値（[]・スペース・日本語等のマルチバイト値）を含む --param は "key=value" 全体をダブルクォートで囲む。

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":"[email protected]","subject":"件名"}' --json

重要なルール

ルール	説明
--json フラグ	AI agent からの呼び出しでは常に --json を指定（例外: --dry-run はプレビュー出力のため --json 不要）
GET配列パラメータ	--param "topics_group_id[]=1" のように [] suffix必須
POST配列パラメータ	--data 内でネイティブJSON配列（例: {"topics_group_id": [1]}）
件数制限	レスポンスが大きい場合は --param cnt=N で制限
columns指定	--columns col1,col2 でレスポンスカラムを最小限にする
変更操作の確認	INSERT/UPDATE/DELETEは実行前にユーザーに確認すること
未確定値の解決	依頼のスコープに含まれるが依頼内容から値を決められないフィールドは、必須か否かによらず、推測やデフォルトで埋めず、フィールド名・型・候補値を提示してユーザーに確認
dry-run活用	書き込み操作の前に --dry-run でリクエスト内容を確認

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

---

レスポンス構造

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

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

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

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

リストレスポンスのキー

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

ct	レスポンスのリストキー
topics_list	data.topics_list
topics_group_list	data.topics_group_list
member_list	data.member_list

ページネーション

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

---

エラーハンドリング

Exit Codes

Code	意味	対処
0	成功	—
1	一般エラー（INVALID_PARAM, NETWORK_ERROR, API_ERROR）	エラーメッセージ確認、パラメータ修正
2	認証エラー（AUTH_ERROR, SESSION_EXPIRED, LOGIN_REQUIRED）	kuroco-admin login で再ログイン

詳細は 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レスポンスのファイル保存はユーザー同意必須 — 個人情報を含む可能性

---

アンチパターン

やりがち	問題	推奨
--json を付けずに実行	人間向けフォーマットでパースしにくい	AI agentでは常に --json
--columns を指定せずにGET	レスポンスが巨大	常に --columns を指定
exit code を確認しない	認証切れに気づかない	exit code 2 なら再ログイン
schema なしで書き込み	必須フィールド漏れ	help でスキーマ確認後に実行
--verbose 出力をログに残す	Cookie値が漏洩する	デバッグ時のみ使用、出力は共有しない
model/method 形式でAPI指定	HTMLが返却される場合がある	必ず mt/ct 形式を使用

---

並列実行

独立した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

---

他スキルとの連携

スキル	用途	使い分け
/kuroco-admin-mcp	Admin MCP（管理MCPサーバー）への接続・ツール利用	AIエージェントからの管理操作の推奨手段。MCPクライアント（Claude Desktop / claude.ai / Claude Code 等）から接続
/kuroco-api-content	フロントエンドAPI設計・認証パターン、コンテンツCRUDパターン	エンドユーザー向けAPI
/kuroco-frontend-integration	Nuxt.js/Next.js統合、AI自動デプロイ	フロントエンド実装
/kuroco-docs	Kurocoドキュメント参照	公式ドキュメント検索

本スキルはCLI経由のadmin_api実行に特化。 AIエージェントからの管理操作にはAdmin MCP（/kuroco-admin-mcp）が推奨。本スキルはMCP接続を構成できない環境やBashスクリプトへの組み込み向けの代替手段。フロントエンドAPI（*.g.kuroco.app）の操作には上記の関連スキルを使用。