From 3e2693794546774296cc2b2019f8c0cc1d0e1ec7 Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Wed, 12 Nov 2025 13:15:18 -0500 Subject: [PATCH] docs: update README files with GLMT sections and translations - Move GLMT section to proper position in English README - Add missing npm badge to Vietnamese README - Add GLMT and Architecture sections to all translations - Update configuration examples with glmt profile - Add Windows Developer Mode support documentation - Fix documentation links across all language versions --- README.ja.md | 107 +++++++++++++++++++++++++++++++++++++++----- README.md | 92 +++++++++++++++----------------------- README.vi.md | 122 ++++++++++++++++++++++++++++++++++++++++++++------- 3 files changed, 237 insertions(+), 84 deletions(-) diff --git a/README.ja.md b/README.ja.md index 423bed29..d5a6d461 100644 --- a/README.ja.md +++ b/README.ja.md @@ -75,6 +75,7 @@ irm ccs.kaitran.ca/install | iex { "profiles": { "glm": "~/.ccs/glm.settings.json", + "glmt": "~/.ccs/glmt.settings.json", "kimi": "~/.ccs/kimi.settings.json", "default": "~/.claude/settings.json" } @@ -92,23 +93,37 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows **詳細な設定手順については、[トラブルシューティングガイド](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location)を参照してください。** +### Windowsシンボリックリンクサポート（開発者モード） + +**Windowsユーザー**: 本物のシンボリックリンクで高速な動作と即時同期を得るために開発者モードを有効にしてください： + +1. **設定** → **プライバシーとセキュリティ** → **開発者向け** を開く +2. **開発者モード** を有効にする +3. CCSを再インストール: `npm install -g @kaitranntt/ccs` + +**開発者モードなし**: CCSは自動的にディレクトリコピーにフォールバック（動作しますが、プロファイル間の即時同期はありません） + --- ### 最初の切り替え -> **⚠️ 重要**: GLMまたはKimiプロファイルを使用する前に、対応する設定ファイルでAPIキーを更新する必要があります： +> **⚠️ 重要**: GLM、GLMT、Kimiプロファイルを使用する前に、設定ファイルでAPIキーを更新してください： > - **GLM**: `~/.ccs/glm.settings.json`を編集してGLM APIキーを追加 +> - **GLMT**: `~/.ccs/glmt.settings.json`を編集してZ.AI APIキーを追加（coding planが必要） > - **Kimi**: `~/.ccs/kimi.settings.json`を編集してKimi APIキーを追加 ```bash -# Claudeサブスクリプションを使用（デフォルト）で高レベルの計画 -ccs "マイクロサービスアーキテクチャの実装計画を立てて" +# Claudeサブスクリプション（デフォルト） +ccs "マイクロサービスアーキテクチャの計画" -# GLMに切り替えてコスト最適化されたタスクを実行 -ccs glm "シンプルなREST APIを作成して" +# GLMに切り替え（コスト最適化） +ccs glm "REST APIを作成" -# Kimiに切り替えて思考能力を活用 -ccs kimi "適切なエラーハンドリングで統合テストを書いて" +# GLM with thinkingモード +ccs glmt "アルゴリズム問題を解決" + +# Kimi for Coding +ccs kimi "統合テストを作成" ``` --- @@ -218,6 +233,73 @@ flowchart TD --- +## Architecture + +### Profile Types + +**Settings-based**: GLM, GLMT, Kimi, default +- Uses `--settings` flag pointing to config files +- GLMT: Embedded proxy for thinking mode support + +**Account-based**: work, personal, team +- Uses `CLAUDE_CONFIG_DIR` for isolated instances +- Create with `ccs auth create ` + +### Shared Data (v3.1) + +Commands and skills symlinked from `~/.ccs/shared/` - no duplication across profiles. + +``` +~/.ccs/ +├── shared/ # Shared across all profiles +│ ├── agents/ +│ ├── commands/ +│ └── skills/ +├── instances/ # Profile-specific data +│ └── work/ +│ ├── agents@ → shared/agents/ +│ ├── commands@ → shared/commands/ +│ ├── skills@ → shared/skills/ +│ ├── settings.json # API keys, credentials +│ └── sessions/ # Conversation history +│ └── ... +``` + +**Shared**: commands/, skills/, agents/ +**Profile-specific**: settings.json, sessions/, todolists/, logs/ + +**[i] Windows**: Copies dirs if symlinks unavailable (enable Developer Mode for true symlinks) + +--- + +## GLM with Thinking (GLMT) + +> **[!] 警告：本番環境未対応** +> +> **GLMTは実験的で広範なデバッグが必要です**： +> - ストリーミングとツールサポートはまだ開発中 +> - 予期せぬエラー、タイムアウト、不完全な応答が発生する可能性 +> - 頻繁なデバッグと手動介入が必要 +> - **重要なワークフローや本番使用には推奨されません** +> +> **GLM Thinkingの代替案**: **CCR hustle**と**BedollaのTransformer**（ZaiTransformer）を通じて、より安定した実装を検討してください。 +> +> **[!] 重要**: GLMTはnpmインストールが必要です（`npm install -g @kaitranntt/ccs`）。ネイティブシェルバージョンでは利用できません（Node.js HTTPサーバーが必要）。 + +### GLM vs GLMT + +| 機能 | GLM (`ccs glm`) | GLMT (`ccs glmt`) | +|-----|-----------------|-------------------| +| **エンドポイント** | Anthropic互換 | OpenAI互換 | +| **思考** | なし | 実験的（reasoning_content） | +| **ツールサポート** | 基本的 | **不安定（v3.5+）** | +| **MCPツール** | 制限あり | **バグあり（v3.5+）** | +| **ストリーミング** | 安定 | **実験的（v3.4+）** | +| **TTFB** | <500ms | <500ms（時々）、2-10秒+（頻繁） | +| **使用例** | 信頼性の高い作業 | **デバッグ実験のみ** | + +--- + ## ⚡ 機能 - **即座の切り替え** - `ccs glm`でGLMに切り替え、設定編集不要 @@ -232,10 +314,11 @@ flowchart TD ## 💻 使用例 ```bash -ccs # Claudeサブスクリプションを使用（デフォルト） -ccs glm # GLMフォールバックを使用 -ccs kimi # Kimi for Codingを使用 -ccs --version # CCSバージョンとインストール場所を表示 +ccs # Claudeサブスクリプション（デフォルト） +ccs glm # GLM（thinkingなし） +ccs glmt # GLM with thinking +ccs kimi # Kimi for Coding +ccs --version # バージョン表示 ``` ### 同時セッション (Multi-Account) @@ -299,6 +382,8 @@ irm ccs.kaitran.ca/uninstall | iex - [インストールガイド](./docs/en/installation.md) - [設定](./docs/en/configuration.md) - [使用例](./docs/en/usage.md) +- [System Architecture](./docs/system-architecture.md) +- [GLMT Control Mechanisms](./docs/glmt-controls.md) - [トラブルシューティング](./docs/en/troubleshooting.md) - [コントリビューション](./CONTRIBUTING.md) diff --git a/README.md b/README.md index 2bda6434..007955e4 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,42 @@ Commands and skills symlinked from `~/.ccs/shared/` - no duplication across prof --- +## Usage Examples + +### Basic Switching +```bash +ccs # Claude subscription (default) +ccs glm # GLM (no thinking) +ccs glmt # GLM with thinking +ccs kimi # Kimi for Coding +ccs --version # Show version +``` + +### Multi-Account Setup +```bash +# Create accounts +ccs auth create work +ccs auth create personal + +# Terminal 1 +ccs work "implement feature" + +# Terminal 2 (concurrent) +ccs personal "review code" +``` + +### Custom Claude CLI Path + +Non-standard installation location: +```bash +export CCS_CLAUDE_PATH="/path/to/claude" # Unix +$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows +``` + +See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) + +--- + ## GLM with Thinking (GLMT) > **[!] WARNING: NOT PRODUCTION READY** @@ -346,62 +382,6 @@ cat ~/.ccs/logs/*response-openai.json | jq '.choices[0].message.reasoning_conten --- -## Usage Examples - -### Basic Switching -```bash -ccs # Claude subscription (default) -ccs glm # GLM (no thinking) -ccs glmt # GLM with thinking -ccs kimi # Kimi for Coding -ccs --version # Show version -``` - -### Multi-Account Setup -```bash -# Create accounts -ccs auth create work -ccs auth create personal - -# Terminal 1 -ccs work "implement feature" - -# Terminal 2 (concurrent) -ccs personal "review code" -``` - -### Custom Claude CLI Path - -Non-standard installation location: -```bash -export CCS_CLAUDE_PATH="/path/to/claude" # Unix -$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows -``` - -See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) - ---- - -## Configuration - -Auto-created during installation via npm postinstall script. - -**~/.ccs/config.json**: -```json -{ - "profiles": { - "glm": "~/.ccs/glm.settings.json", - "glmt": "~/.ccs/glmt.settings.json", - "kimi": "~/.ccs/kimi.settings.json", - "default": "~/.claude/settings.json" - } -} -``` - -Complete guide: [docs/en/configuration.md](./docs/en/configuration.md) - ---- - ## Uninstall **Package Managers** diff --git a/README.vi.md b/README.vi.md index 482ee03e..0a93693d 100644 --- a/README.vi.md +++ b/README.vi.md @@ -12,6 +12,7 @@ Ngừng hitting rate limits. Làm việc liên tục. [![License](https://img.shields.io/badge/license-MIT-C15F3C?style=for-the-badge)](LICENSE) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=for-the-badge)]() +[![npm](https://img.shields.io/npm/v/@kaitranntt/ccs?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@kaitranntt/ccs) [![PoweredBy](https://img.shields.io/badge/PoweredBy-ClaudeKit-C15F3C?style=for-the-badge)](https://claudekit.cc?ref=HMNKXOHN) **Ngôn ngữ**: [English](README.md) | [Tiếng Việt](README.vi.md) | [日本語](README.ja.md) @@ -74,6 +75,8 @@ irm ccs.kaitran.ca/install | iex { "profiles": { "glm": "~/.ccs/glm.settings.json", + "glmt": "~/.ccs/glmt.settings.json", + "kimi": "~/.ccs/kimi.settings.json", "default": "~/.claude/settings.json" } } @@ -90,23 +93,37 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows **Xem [Hướng dẫn Khắc phục Sự cố](./docs/vi/troubleshooting.vi.md#claude-cli-ở-vị-trí-không-chuẩn) để biết chi tiết cài đặt.** +### Hỗ Trợ Symlink Windows (Chế Độ Nhà Phát Triển) + +**Người dùng Windows**: Bật Chế độ Nhà phát triển để có symlink thực sự (hiệu suất tốt hơn, đồng bộ hóa tức thì): + +1. Mở **Settings** → **Privacy & Security** → **For developers** +2. Bật **Developer Mode** +3. Cài đặt lại CCS: `npm install -g @kaitranntt/ccs` + +**Nếu không có Chế độ Nhà phát triển**: CCS tự động chuyển sang sao chép thư mục (hoạt động nhưng không đồng bộ tức thì trên các profile). + --- ### Lần Chuyển Đổi Đầu Tiên -> **⚠️ Quan trọng**: Trước khi dùng profile GLM hay Kimi, bạn cần cập nhật API key trong file settings tương ứng: -> - **GLM**: Chỉnh sửa `~/.ccs/glm.settings.json` và thêm GLM API key của bạn -> - **Kimi**: Chỉnh sửa `~/.ccs/kimi.settings.json` và thêm Kimi API key của bạn +> **⚠️ Quan trọng**: Trước khi dùng GLM, GLMT hay Kimi profile, cập nhật API key trong file settings: +> - **GLM**: Chỉnh sửa `~/.ccs/glm.settings.json` và thêm GLM API key +> - **GLMT**: Chỉnh sửa `~/.ccs/glmt.settings.json` và thêm Z.AI API key (yêu cầu coding plan) +> - **Kimi**: Chỉnh sửa `~/.ccs/kimi.settings.json` và thêm Kimi API key ```bash -# Dùng Claude subscription (mặc định) cho lập trình cấp cao -ccs "Lên kế hoạch triển khai kiến trúc microservices" +# Claude subscription mặc định +ccs "Lên kế hoạch kiến trúc microservices" -# Chuyển sang GLM cho tác vụ tối ưu chi phí -ccs glm "Tạo REST API đơn giản" +# Chuyển sang GLM (tối ưu chi phí) +ccs glm "Tạo REST API" -# Chuyển sang Kimi để sử dụng khả năng thinking -ccs kimi "Viết integration tests với xử lý lỗi phù hợp" +# GLM với thinking mode +ccs glmt "Giải quyết bài toán thuật toán" + +# Kimi cho lập trình +ccs kimi "Viết integration tests" ``` --- @@ -216,6 +233,73 @@ flowchart TD --- +## Architecture + +### Profile Types + +**Settings-based**: GLM, GLMT, Kimi, default +- Uses `--settings` flag pointing to config files +- GLMT: Embedded proxy for thinking mode support + +**Account-based**: work, personal, team +- Uses `CLAUDE_CONFIG_DIR` for isolated instances +- Create with `ccs auth create ` + +### Shared Data (v3.1) + +Commands and skills symlinked from `~/.ccs/shared/` - no duplication across profiles. + +``` +~/.ccs/ +├── shared/ # Shared across all profiles +│ ├── agents/ +│ ├── commands/ +│ └── skills/ +├── instances/ # Profile-specific data +│ └── work/ +│ ├── agents@ → shared/agents/ +│ ├── commands@ → shared/commands/ +│ ├── skills@ → shared/skills/ +│ ├── settings.json # API keys, credentials +│ └── sessions/ # Conversation history +│ └── ... +``` + +**Shared**: commands/, skills/, agents/ +**Profile-specific**: settings.json, sessions/, todolists/, logs/ + +**[i] Windows**: Copies dirs if symlinks unavailable (enable Developer Mode for true symlinks) + +--- + +## GLM with Thinking (GLMT) + +> **[!] CẢNH BÁO: CHƯA SẴN SÀNG SẢN XUẤT** +> +> **GLMT là thử nghiệm và yêu cầu gỡ lỗi sâu rộng**: +> - Streaming và hỗ trợ công cụ vẫn đang phát triển +> - Có thể gặp lỗi, timeout, hoặc phản hồi không đầy đủ +> - Yêu cầu gỡ lỗi thường xuyên và can thiệp thủ công +> - **Không khuyến nghị cho quy trình quan trọng hoặc sử dụng sản xuất** +> +> **Phương án thay thế cho GLM Thinking**: Cân nhắc trải qua **CCR hustle** với **Transformer của Bedolla** (ZaiTransformer) để có triển khai ổn định hơn. +> +> **[!] Quan trọng**: GLMT yêu cầu cài đặt npm (`npm install -g @kaitranntt/ccs`). Không có trong phiên bản shell gốc (yêu cầu Node.js HTTP server). + +### GLM vs GLMT + +| Tính năng | GLM (`ccs glm`) | GLMT (`ccs glmt`) | +|-----------|-----------------|-------------------| +| **Endpoint** | Tương thích Anthropic | Tương thích OpenAI | +| **Thinking** | Không | Thử nghiệm (reasoning_content) | +| **Tool Support** | Cơ bản | **Không ổn định (v3.5+)** | +| **MCP Tools** | Giới hạn | **Lỗi (v3.5+)** | +| **Streaming** | Ổn định | **Thử nghiệm (v3.4+)** | +| **TTFB** | <500ms | <500ms (đôi khi), 2-10s+ (thường xuyên) | +| **Use Case** | Công việc đáng tin cậy | **Chỉ thử nghiệm gỡ lỗi** | + +--- + ## ⚡ Tính Năng - **Chuyển Đổi Ngay Lập Tức** - `ccs glm` chuyển sang GLM, không cần sửa config @@ -230,9 +314,11 @@ flowchart TD ## 💻 Ví Dụ Sử Dụng ```bash -ccs # Dùng Claude subscription (mặc định) -ccs glm # Dùng GLM fallback -ccs --version # Hiển thị phiên bản CCS và vị trí cài đặt +ccs # Claude subscription (mặc định) +ccs glm # GLM (không thinking) +ccs glmt # GLM với thinking +ccs kimi # Kimi cho Coding +ccs --version # Hiển thị phiên bản ``` ### Phiên Đồng Thời (Multi-Account) @@ -293,10 +379,12 @@ irm ccs.kaitran.ca/uninstall | iex ## 📖 Tài Liệu **Tài liệu đầy đủ trong [docs/](./docs/)**: -- [Hướng dẫn Cài đặt](./docs/installation.md) -- [Cấu hình](./docs/configuration.md) -- [Ví dụ Sử dụng](./docs/usage.md) -- [Khắc phục Sự cố](./docs/troubleshooting.md) +- [Hướng dẫn Cài đặt](./docs/en/installation.md) +- [Cấu hình](./docs/en/configuration.md) +- [Ví dụ Sử dụng](./docs/en/usage.md) +- [System Architecture](./docs/system-architecture.md) +- [GLMT Control Mechanisms](./docs/glmt-controls.md) +- [Khắc phục Sự cố](./docs/en/troubleshooting.md) - [Đóng góp](./CONTRIBUTING.md) --- @@ -317,6 +405,6 @@ CCS được cấp phép theo [Giấy phép MIT](LICENSE). **Được tạo với ❤️ cho những lập trình viên hay hết rate limit** -[⭐ Star repo này](https://github.com/kaitranntt/ccs) | [🐛 Báo cáo vấn đề](https://github.com/kaitranntt/ccs/issues) | [📖 Đọc tài liệu](./docs/) +[⭐ Star repo này](https://github.com/kaitranntt/ccs) | [🐛 Báo cáo vấn đề](https://github.com/kaitranntt/ccs/issues) | [📖 Đọc tài liệu](./docs/en/)