zentao-shared

zentao-cli 共通ルール

このスキルでは、zentao-cli を使って ZenTao リソースを操作する方法と、注意事項を説明します。

設定の初期化

自動セットアップの手順

ユーザーが設定していない場合、または認証に失敗した場合：

1. 設定状態を確認する

   zentao-cli auth status
   

   ZEN_AUTH_FAILED または ZEN_CONFIG_INVALID が返された場合は、未設定または設定が無効です。

2. ユーザーに設定情報と保存先を尋ねる

   保存先がグローバルか現在のプロジェクトか、必ず明確に確認してください。

   ユーザーに以下の情報を尋ねてください：

   • ZenTao サービスの URL（例：http://172.168.80.30:8001/zentao）
   • ZenTao アカウント
   • ZenTao パスワード
   • 保存先：グローバル（~/.zentao-cli/config.toml）または現在のプロジェクト（.zentao-cli/config.toml）？

   ⚠️ 重要：保存先についてユーザーの明確な回答を得てから、設定コマンドを実行してください。ユーザーが選択していない状態で、グローバル設定をデフォルトとして使用することは禁止されています。

3. 設定を実行する

   グローバルに保存：

   zentao-cli config set -g url "用户提供的地址"
   zentao-cli auth login -g --account 账号 --password 密码
   

   現在のプロジェクトに保存：

   zentao-cli config set url "用户提供的地址"
   zentao-cli auth login --account 账号 --password 密码
   

   注意：config set で設定できるのは url、token、product_id、project_id のみです。アカウントとパスワードを直接設定することはできません。2 段階で設定する必要があります。まず URL を設定し、次に auth login でアカウントとパスワードを使って token を取得します。

4. 設定が成功したことを確認する

   zentao-cli auth status
   

クイックチェック

# 检查认证状态
zentao-cli auth status

# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN

Token の取得（手動）

1. ZenTao の Web インターフェースにログインします
2. 個人設定 → API Token に進みます
3. 新しい Token を生成します
4. ZENTAO_TOKEN 環境変数に設定します

環境変数の説明

変数	必須	説明
ZENTAO_URL	はい	ZenTao サーバーの URL。例：https://zentao.example.com
ZENTAO_TOKEN	はい	認証に使用する API Token
ZENTAO_PRODUCT_ID	いいえ	デフォルトの製品 ID
ZENTAO_PROJECT_ID	いいえ	デフォルトのプロジェクト ID

認証

Token ベースの認証

ZenTao は Token を使用して認証します。Token は ZENTAO_TOKEN 環境変数を通じて渡されます。

# 验证认证状态
zentao-cli auth status

エラーレスポンス形式：

{
  "status": "error",
  "error": {
    "code": "ZEN_AUTH_FAILED",
    "message": "Invalid token or token expired",
    "hint": "Verify ZENTAO_TOKEN is correct"
  }
}

よくあるエラーコード

Code	Description	Resolution
ZEN_AUTH_FAILED	Token が無効または期限切れです	ZENTAO_TOKEN が正しいか確認します
ZEN_NOT_FOUND	リソースが存在しません	ID を確認して再試行します
ZEN_CONFIG_INVALID	設定が無効です	ZENTAO_URL と ZENTAO_TOKEN を確認します
ZEN_API_ERROR	ZenTao API がエラーを返しました	サーバーの状態を確認するか、しばらくしてから再試行します
ZEN_PARAM_MISSING	必須パラメーターが不足しています	すべての必須パラメーターを指定します

権限不足への対処

権限に関するエラーが発生した場合：

1. 現在のユーザーのロールを確認します（ZenTao では通常、admin、leader、member のいずれかです）
2. Token に、そのリソースを操作するために必要な権限があることを確認します
3. 管理者の場合は、そのユーザーが該当するプロジェクト／製品に正しく割り当てられていることを確認します

設定の優先順位

CLI パラメーターの優先順位は、上から順に高くなります：

1. コマンドラインパラメーター（--product、--project など）
2. 環境変数（ZENTAO_PRODUCT_ID、ZENTAO_PROJECT_ID）
3. デフォルト設定

# 命令行参数优先级最高
zentao-cli task list --project 5  # 使用 --project 参数

# 环境变量作为默认值
export ZENTAO_PROJECT_ID=5
zentao-cli task list              # 使用环境变量

# 默认值兜底
zentao-cli task list              # 使用配置中的默认值

共通オプション

オプション	説明
--format	出力形式：json、pretty、table、ndjson、csv
--product	製品 ID でフィルタリング
--project	プロジェクト ID でフィルタリング
--status	ステータスで絞り込み

出力形式

# JSON 输出（默认，用于脚本）
zentao-cli story list --product 1 --format json

# Pretty 打印输出（默认，用于终端）
zentao-cli story list --product 1 --format pretty

# 表格输出
zentao-cli story list --product 1 --format table

更新の確認

zentao-cli コマンドを実行した後、新しいバージョンが検出されると、JSON 出力に _notice.update フィールド（message、command などを含む）が追加されます。

出力に _notice.update が表示された場合、現在のリクエストを完了した後に通知し、更新を提案してください：

1. 現在のバージョンと最新バージョンを伝えます
2. 次のコマンドの実行を提案します：

   npm update -g zentao-cli && npx skills add zentao/cli -g -y
   

3. 最新の Skills を読み込むため、AI エージェントを終了して再度開くようユーザーに伝えます

ルール：更新通知を黙って無視してはいけません。現在のタスクに更新が関係しない場合も、ユーザーのリクエストを完了した後に通知してください。

セキュリティルール

• 秘密情報（token、appSecret）を平文でターミナルに出力しないでください。
• 書き込み／削除操作の前に、必ずユーザーの意図を確認してください。
• --dry-run を使って、危険なリクエストを事前に確認してください。