npm package: @mai0313/coding-cli-helper
Description: This tool supports installation and configuration for **Claude Code**, **OpenAI Codex**, and **Claude Code Router**
Author: Wei Lee
Latest version: 5.23.0

<div align="center" markdown="1">

# Coding CLI Helper 安裝指南

[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/)
[![npm version](https://img.shields.io/npm/v/@mai0313/coding-cli-helper?logo=npm&style=flat-square&color=CB3837)](https://www.npmjs.com/package/@mai0313/coding-cli-helper)
[![npm downloads](https://img.shields.io/npm/dt/@mai0313/coding-cli-helper?logo=npm&style=flat-square)](https://www.npmjs.com/package/@mai0313/coding-cli-helper)
[![tests](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/actions/workflows/test.yml/badge.svg)](.github/workflows/test.yml)
[![code-quality](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/actions/workflows/code-quality-check.yml/badge.svg)](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/actions/workflows/code-quality-check.yml)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/tree/master?tab=License-1-ov-file)
[![PRs](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/pulls)
[![contributors](https://img.shields.io/github/contributors/Mai0313/go_template.svg)](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/graphs/contributors)

</div>

[English](README.md) | 繁體中文 | [简体中文](README.zh-CN.md)

## 概述

此工具支援安裝和配置 **Claude Code**、**OpenAI Codex** 和 **Claude Code Router** 等強大的 AI 驅動命令列介面，適用於 Windows、macOS 和 Linux 系統。本指南將幫助您使用自動化安裝程式快速設定這些 CLI 工具，並提供域名專屬的最佳化配置。

> **注意**：本教學中的截圖為 Windows 環境，但 macOS 和 Linux 的操作流程基本相同，因為這是一個命令列工具。

---

## 快速安裝

> **SWRD Linux 使用者須知**：SWRD 環境下的 Linux 系統已預安裝 Claude Code 和 Codex。Claude Code 可直接使用，Codex 需透過本腳本進行安裝配置，會自動設定 config.toml 檔案。其他系統使用者仍需手動安裝。

### Linux/macOS

**僅安裝：**

```bash
curl -fsSLk https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/raw/branch/main/scripts/install.sh | bash
```

### Windows

**僅安裝：**

```powershell
powershell -ExecutionPolicy ByPass -c "[System.Net.ServicePointManager]::ServerCertificateValidationCallback={$true}; irm https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/raw/branch/main/scripts/install.ps1 | iex"
```

> **Windows 使用者重要提示**：使用工具前，您需要：
>
> 1. 提交[申請單](https://workflow.mediatek.inc/portal/?openform&apid=444&workID=%25257Bpr%25257D7KGECefqaE0FL%25252Bs%25252BATdMG%25252Bgw4L%25252FdU%25252FgMn7lwgPjWmPBXSS4xJ7TEns5W1ao3T4fm)請 IT 協助打開 git-bash 防火牆
> 2. 審批通過後，請自行安裝 git-bash 後使用 Claude Code 和 Codex
>
> **注意**：Linux 和 macOS 使用者無需此操作。

安裝程式會自動：

- 偵測您的平台和架構
- 下載最新版本
- 安裝執行檔並設定 PATH
- 設定必要的權限
- （可選）執行設定來配置 Claude Code、Codex 和 Claude Code Router
- 設定域名專屬的 OTEL 遙測功能（適用於 SWRD 和 MPD 環境）

> **注意**：安裝後請重新啟動終端機以套用 PATH 變更。

---

## 手動安裝步驟

### 步驟 1：下載安裝包

前往發佈頁面下載對應您作業系統的安裝包：
🔗 **[AI 程式碼助手發佈頁面](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/releases/latest)**

### 步驟 2：解壓縮檔案

將下載的 zip 檔案解壓縮到容易存取的位置，建議選擇可以輕鬆從終端機或命令提示字元開啟的資料夾。

![解壓縮範例](images/unzip.jpeg)

### 步驟 3：設定安裝選項

安裝程式啟動後，您會看到主選單, 請選擇需要的功能

![安裝程式主選單](images/installer_menu1.png)

![下載中](images/installing.png)

> ⏳ **請耐心等候**：此步驟包含 Node.js v22、Claude Code CLI、Codex CLI 和 Claude Code Router 的下載與安裝，可能需要幾分鐘時間（共 6 個步驟）。

> 💡 **安裝輸出顯示**：安裝程式現在會在每個步驟下方以較淡的顏色即時顯示命令輸出，讓您更容易監控安裝進度和診斷問題。輸出最多顯示 50 行，即使步驟完成後也會保持可見。如需查看完整的輸出歷史記錄，請按 'D' 鍵。

### 步驟 4：完成安裝

安裝成功後會顯示完成畫面：

![安裝完成](images/after_installed.png)

### 完成 開始使用

1. **開啟新的終端機/命令提示字元**（重要：需要新視窗才能載入環境變數）

2. **執行 Claude Code**：

   ```bash
   claude
   ```

![Claude Code CLI](images/claude_code.png)

### 添加 Plugin

啟動 Claude Code 後，您可以透過添加 plugin 來擴展功能：

1. **啟動 Claude Code**：

   ```bash
   claude
   ```

2. **使用 `/plugin` 指令添加 plugin**：

   ```
   /plugin
   ```

   ![add_marketplace](images/add_marketplace.png)

   **或者：使用直接指令一步完成 plugin 安裝**：

   ```
   /plugin marketplace add git@git.mediatek.inc:IT-GAIA/claude-code.git
   ```

3. **透過 `Gitea` 連結添加 plugin**（如果使用互動模式）：

   ```
   git@git.mediatek.inc:IT-GAIA/claude-code.git
   ```

   ![add_gitea_link](images/add_gitea_link.png)

4. **完成**
   ![plugin_done](images/plugin_done.png)

詳情可參考
🔗 **[Claude Code Plugin](https://docs.claude.com/zh-TW/docs/claude-code/plugins)**
🔗 **[Claude Code Plugin Marketplace](https://docs.claude.com/zh-TW/docs/claude-code/plugin-marketplaces)**

---

## 系統需求

| 項目         | 需求                                           |
| ------------ | ---------------------------------------------- |
| **作業系統** | Windows 11+、macOS 10.15+、或現代 Linux 發行版 |
| **Node.js**  | v22 或更新版本（安裝程式會自動處理）           |
| **網路連線** | 需要連線以下載套件和進行認證                   |
| **權限**     | 一般使用者權限即可（無需管理員權限）           |

---

## 域名專屬功能

安裝程式會根據您的網路域名自動設定不同的功能：

### OA 域名

- 標準 Claude Code 和 Codex 安裝
- 使用 Stop hook 進行對話分析
- 預設 npm registry，失敗時自動切換至聯發科鏡像站

### SWRD 域名

- 包含 Claude Code Router 安裝
- 啟用 OTEL 遙測功能，端點：`https://mtklm-swrd.mediatek.inc/claude-code-otel`
- 自動透過 MTKID 進行使用者追蹤
- 使用域名專屬的 npm registry 鏡像站

### MPD 域名

- 包含 Claude Code Router 安裝
- 啟用 OTEL 遙測功能，端點：`https://mtklm-mpd.mediatek.inc/claude-code-otel`
- 自動透過 MTKID 進行使用者追蹤
- 使用域名專屬的 npm registry 鏡像站

> **注意**：安裝程式會透過網路連線檢查自動偵測您的域名。如有需要，您可以使用 `--domain` 參數手動指定域名。

---

## 疑難排解

### ❌ 「claude: command not found」錯誤

**解決方法：**

1. **重新開啟終端機**：關閉目前的終端機並開啟新的，讓 PATH 環境變數生效

2. **檢查 PATH 設定**：確認 npm 的全域 bin 目錄已加入 PATH

   ```bash
   # 檢查 npm 全域目錄
   npm config get prefix
   ```

### 🔧 Node.js 安裝問題

#### macOS/Linux

- 安裝程式會在 Debian/Ubuntu 系統上自動嘗試使用 NodeSource 22.x
- 如果自動安裝失敗，請手動安裝：
  1. 前往 [Node.js 官網](https://nodejs.org/) 下載 v22+ 版本
  2. 安裝完成後重新執行安裝程式

#### Windows

- 安裝程式會使用內建的 Node.js 安裝包
- 自動安裝至 `%USERPROFILE%\.cchelper\nodejs`
- 如有問題，請確認該目錄的權限設定

### 🔐 認證問題

**常見問題與解決方法：**

1. **GAISF Token 設定失敗**

   - 檢查 MediaTek 網路連線
   - 確認安裝程式在建置時有正確嵌入服務 JWT（OA_JWT / SWRD_JWT）
   - 手動開啟 GAISF 登入頁面取得 Token

2. **API 連線問題**

   - 確認防火牆設定
   - 檢查公司網路政策
   - 聯繫 IT 部門確認網路存取權限

3. **Codex API Key 過期**

   當您的 Codex API key 過期時，需要透過以下指令更新：

   ```bash
   ~/.cchelper/coding-cli-helper update
   ~/.cchelper/coding-cli-helper setup
   ```

   **SWRD Linux 使用者**：也可以使用預安裝的輔助工具：

   ```bash
   /etc/claude-code/coding-cli-helper setup
   ```

   > **注意**：未來 API key 將延長至半年更新一次。

### 🍎 macOS 安全驗證錯誤

**問題**：macOS 顯示「無法驗證開發者」或「惡意軟體」警告，無法執行安裝程式。

**解決方法**：

- 前往 **系統設定** > **隱私權與安全性** > **安全性**
- 點擊被阻擋安裝程式訊息旁的 **「強制允許」**
- 重新執行安裝程式

### 🔄 重新安裝

如果遇到嚴重問題，可以完全重新安裝：

```bash
# Windows
rmdir /s "%USERPROFILE%\.claude"

# macOS/Linux
rm -rf ~/.claude
```

### 📋 安裝和可用性問題

**問：Claude Code / Codex 目前安裝範圍是哪裡？**

答：Claude Code / Codex 目前在 SWRD 的 Linux 上是預設安裝的，但由於 Codex 的使用方式不同，所以如果需要使用 Codex，依然要透過此腳本設定 Config；OA、MPD 用戶請手動安裝。

**問：如果 SWRD 下的 Linux 機器沒有 claude / codex 要怎麼辦？**

答：可以聯繫 `Jason-YS Peng` 協助安裝。

**問：Windows 使用 Claude Code / Codex 為何會一直報錯？**

答：兩個工具官方都建議使用 Linux / MacOS，有可能是 Claude Code / Codex 一直嘗試使用 powershell 指令，可以嘗試請他使用 `apply_patch` 之類的內建工具來修改檔案。

---

## 支援

如遇到任何問題或需要協助，請使用我們的問題追蹤系統：

🔗 **[尋求協助](https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/issues/new/choose)**

尋求協助時，問題模板會引導您提供：

- 網路環境（OA / SWRD / MPD）
- 作業系統（Windows / MacOS / Linux）
- Git-bash 安裝狀態（Windows 使用者）
- 錯誤截圖（如有）
- 系統檢查輸出 `~/.cchelper/coding-cli-helper check --text`

直接聯繫：

- **ds906659** <ds_wei-cheng.lee@mai0313.com>

## 參考資源

- 📖 **Claude Code 官方文件**：[https://docs.anthropic.com/zh-TW/docs/claude-code](https://docs.anthropic.com/zh-TW/docs/claude-code)
- ⚙️ **設定說明**：[https://docs.anthropic.com/zh-TW/docs/claude-code/settings](https://docs.anthropic.com/zh-TW/docs/claude-code/settings)

---

# Coding CLI Helper 功能

Coding CLI Helper 內建了分析功能，協助您了解開發活動模式。分析工具可以解析來自 Claude Code 和 Codex 的對話記錄，自動偵測來源類型並提供檔案操作、程式碼異動和開發模式的洞察。

### 使用方法

分析工具可以直接處理來自 Claude Code 和 Codex 的記錄檔案，或透過 stdin 輸入。工具會自動偵測來源格式並套用適當的分析方法：

```bash
# 使用 stdin 模式 (For Claude Code)
echo "{'transcript_path': './examples/test_conversation.jsonl'}" | coding-cli-helper analysis

# 使用 arg 模式 (For Codex)
coding-cli-helper analysis --codex "{'type': 'agent-turn-complete', 'turn-id': '1'}"

# 直接指定檔案路徑分析
coding-cli-helper analysis --path examples/test_conversation.jsonl
coding-cli-helper analysis --path examples/test_conversation_oai.jsonl

# 將分析結果儲存為 JSON 檔案
coding-cli-helper analysis --path examples/test_conversation.jsonl --output examples/analysis_claude_code.json
coding-cli-helper analysis --path examples/test_conversation_oai.jsonl --output examples/analysis_codex.json

# 自訂 o11y 端點（可選）
echo "{'transcript_path': './examples/test_conversation.jsonl'}" | coding-cli-helper analysis --o11y_base_url https://tma.mediatek.inc/api/logs
```

**支援格式：**

- **Claude Code**：包含 `parentUuid` 欄位的 JSONL 記錄檔
- **Codex**：來自 Codex 對話的 JSONL 記錄檔（自動偵測）

### 分析參數

| 參數                       | 說明                                                                       |
| -------------------------- | -------------------------------------------------------------------------- |
| `--log`                    | 將偵錯日誌寫入 helper 日誌目錄                                             |
| `-h, --help`               | 顯示分析命令說明                                                           |
| `--o11y_base_url <string>` | o11y API 端點基底 URL（預設 `https://gaia.mediatek.inc/o11y/upload_locs`） |
| `--output <string>`        | 將分析結果儲存為 JSON 檔（可選）                                           |
| `--path <string>`          | 指定要分析的 JSONL 檔案路徑（stdin 的替代）                                |

### 全域參數

| 參數                | 說明                                      |
| ------------------- | ----------------------------------------- |
| `--domain <string>` | 手動指定域（oa/swrd/mpd）以跳過連通性檢查 |

### 重要檔案說明

| 檔案/目錄                        | 用途                                             |
| -------------------------------- | ------------------------------------------------ |
| `~/.claude/settings.json`        | 主要設定檔，包含 API 設定和使用者偏好            |
| `~/.cchelper/nodejs/`            | Windows 專用：內建的 Node.js 安裝目錄            |
| `~/.cchelper/coding-cli-helper`  | 主要輔助程式安裝位置                             |
| `~/.local/bin/coding-cli-helper` | 輔助程式的符號連結，便於命令列存取 (Linux/macOS) |

> **注意**：在 Linux 和 macOS 上，安裝程式會自動在 `~/.local/bin` 建立符號連結以便於存取。請確保 `~/.local/bin` 在您的 PATH 中。

---

## 輔助指令（Helper Commands）

常用 `coding-cli-helper` 指令速查表：

### 核心指令

| 指令                        | 說明                                            |
| --------------------------- | ----------------------------------------------- |
| `coding-cli-helper`         | 未指定指令時執行安裝程式 TUI（互動式選單）      |
| `coding-cli-helper help`    | 顯示說明與子指令列表                            |
| `coding-cli-helper version` | 顯示版本、建置時間、提交、Go 版本（樣式化輸出） |
| `coding-cli-helper update`  | 自我更新輔助程式二進位檔至最新版本              |
| `coding-cli-helper check`   | 列印解析後的重要路徑，用於故障排除              |

### 配置指令

| 指令                             | 說明                            |
| -------------------------------- | ------------------------------- |
| `coding-cli-helper setup`        | 設定 Claude Code 和 Codex 配置  |
| `coding-cli-helper key`          | 列印 GAISF token（若可用）      |
| `coding-cli-helper switch`       | 更新配置檔案（標準模式）        |
| `coding-cli-helper switch --oss` | 更新配置檔案並套用 OSS 簡化設定 |

### 分析指令

| 指令                                                                                | 說明                                         |
| ----------------------------------------------------------------------------------- | -------------------------------------------- |
| `coding-cli-helper analysis --path <file>`                                          | 從指定的 JSONL 檔案分析對話記錄              |
| `coding-cli-helper analysis --codex '{"type":"agent-turn-complete","turn-id":"1"}'` | 處理 Codex CLI 事件輸入                      |
| `echo '{"transcript_path":"./file.jsonl"}' \| coding-cli-helper analysis`           | 透過 stdin 分析記錄（Claude Code 模式）      |
| `coding-cli-helper usage`                                                           | 計算所有工作階段的使用統計（互動式表格檢視） |
| `coding-cli-helper usage --json`                                                    | 計算使用統計並輸出原始 JSON                  |

### 指令選項

#### version 指令

- `--text` - 以純文字格式輸出
- `--json` - 以 JSON 格式輸出

#### check 指令

- `--text` - 以純文字格式輸出
- `--json` - 以 JSON 格式輸出

#### setup 指令

- `--claude` - 僅安裝 Claude Code（包含 Node.js 和配置）
- `--codex` - 僅安裝 Codex（包含 Node.js 和配置）
- `--all` - 同時安裝 Claude Code 和 Codex（包含 Node.js 和配置）
- 無標誌：僅設定配置

#### switch 指令

- `--oss` - 使用 OSS 簡化配置（先更新所有設定，再套用 OSS 配置）
- 無標誌：僅執行標準配置更新

#### analysis 指令

- `--path <string>` - 指定要分析的 JSONL 檔案路徑
- `--output <string>` - 將分析結果儲存為 JSON 檔
- `--o11y_base_url <string>` - o11y API 端點基底 URL（預設：`https://gaia.mediatek.inc/o11y/upload_locs`）
- `--codex <string>` - 處理 Codex CLI 事件輸入（JSON 格式）
- `--log` - 將偵錯日誌寫入 helper 日誌目錄

#### usage 指令

- `--json` - 輸出原始 JSON 而不是互動式表格檢視

#### 全域選項

- `--domain <string>` - 手動指定域（oa/swrd/mpd）以跳過連通性檢查
- `--setup-folder <string>` - 覆寫 .codex 和 .claude 目錄的安裝路徑
- `--help` - 顯示說明資訊