diff --git a/CLAUDE.md b/CLAUDE.md index d9300c01..9e299699 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -CCS (Claude Code Switch) is a lightweight CLI wrapper enabling instant profile switching between Claude Sonnet 4.5 and GLM 4.6 models. The tool delegates to the official Claude CLI via the `--settings` flag, supporting both Unix-like systems (bash) and Windows (PowerShell). +CCS (Claude Code Switch) is a lightweight CLI wrapper enabling instant switching between **multiple Claude subscription accounts** (work, personal, team) and alternative models (GLM 4.6, Kimi for Coding). Built on v3.0 login-per-profile architecture where each profile is an isolated Claude instance. **Primary Installation Methods** (highest priority): - **npm Package** (recommended): `npm install -g @kaitranntt/ccs` (cross-platform) @@ -14,10 +14,10 @@ CCS (Claude Code Switch) is a lightweight CLI wrapper enabling instant profile s ## Core Design Principles **YAGNI** (You Aren't Gonna Need It): No features "just in case" -**KISS** (Keep It Simple): Simple bash/PowerShell, no complexity +**KISS** (Keep It Simple): Simple bash/PowerShell/Node.js, no complexity **DRY** (Don't Repeat Yourself): One source of truth (config.json) -The tool does ONE thing: map profile names to Claude settings files. Never add features that violate these principles. +The tool does ONE thing: enable instant switching between Claude accounts and alternative models. Never add features that violate these principles. ## Key Constraints @@ -34,22 +34,22 @@ The tool does ONE thing: map profile names to Claude settings files. Never add f ## Architecture -**Core Flow** (common to both npm and traditional install): -``` -User: ccs [profile] [claude-args] - ↓ -Read ~/.ccs/config.json - ↓ -Lookup profile → settings file path - ↓ -Validate settings file exists - ↓ -Execute: claude --settings [args] -``` +### v3.0 Key Features -**Implementation Variants**: -- **npm package**: Pure Node.js (bin/ccs.js) using child_process.spawn -- **Traditional install**: Platform-specific bash (lib/ccs) or PowerShell (lib/ccs.ps1) +**Login-Per-Profile Model**: Each profile is an isolated Claude instance where users login directly via `ccs auth create `. No credential copying, no vault encryption. + +**Two Profile Types**: +1. **Settings-based** (models): GLM, Kimi, default - uses `--settings` flag +2. **Account-based** (Claude accounts): work, personal, team - uses `CLAUDE_CONFIG_DIR` + +**Concurrent Sessions**: Multiple profiles can run simultaneously in different terminals via isolated config directories. + +### Implementation Variants + +**npm package**: Pure Node.js (bin/ccs.js) using child_process.spawn +**Traditional install**: Platform-specific bash (lib/ccs) or PowerShell (lib/ccs.ps1) + +### File Structure **Key Files**: - `package.json`: npm package manifest with bin field configuration and postinstall script @@ -61,48 +61,6 @@ Execute: claude --settings [args] - `VERSION`: Single source of truth for version (format: MAJOR.MINOR.PATCH) - `.claude/`: Commands and skills for Claude Code integration -**npm Package Architecture** (Pure Node.js): -``` -npm install -g @kaitranntt/ccs - ↓ -npm runs postinstall: scripts/postinstall.js - ├─ Create ~/.ccs/ directory - ├─ Create config.json (if missing) - └─ Create glm.settings.json (if missing) - ↓ -npm creates ccs command (symlink to bin/ccs.js) - ↓ -User: ccs [profile] [claude-args] - ↓ -bin/ccs.js (pure Node.js, cross-platform): - ├─ Parse arguments and detect profile - ├─ Read ~/.ccs/config.json (via config-manager.js) - ├─ Get settings path for profile - ├─ Detect claude CLI location (via claude-detector.js) - └─ spawn('claude', ['--settings', settingsPath, ...args]) -``` - -**Traditional Installer Architecture** (Bash/PowerShell): -``` -curl -fsSL ccs.kaitran.ca/install | bash # or irm install | iex - ↓ -installers/install.sh (or install.ps1) - ├─ Create ~/.ccs/ directory - ├─ Copy lib/ccs (or lib/ccs.ps1) - ├─ Create config.json - ├─ Create glm.settings.json - └─ Create symlink ~/.local/bin/ccs → ~/.ccs/ccs - ↓ -User: ccs [profile] [claude-args] - ↓ -lib/ccs (bash) or lib/ccs.ps1 (PowerShell): - ├─ Read ~/.ccs/config.json (jq or ConvertFrom-Json) - ├─ Get settings path for profile - └─ exec claude --settings [args] -``` - -**Installation Creates**: - **Executable Locations**: - macOS / Linux: `~/.local/bin/ccs` (symlink to `~/.ccs/ccs`) - Windows: `%USERPROFILE%\.ccs\ccs.ps1` @@ -111,9 +69,15 @@ lib/ccs (bash) or lib/ccs.ps1 (PowerShell): ``` ~/.ccs/ ├── ccs # Main executable (or ccs.ps1 on Windows) -├── config.json # Profile mappings +├── config.json # Settings-based profile mappings +├── profiles.json # Account-based profile registry (v3.0) +├── instances/ # Isolated Claude instances (v3.0) +│ ├── work/ # Each profile gets own directory +│ ├── personal/ +│ └── team/ ├── config.json.backup # Single backup (overwrites on each install) ├── glm.settings.json # GLM profile template +├── kimi.settings.json # Kimi profile template ├── VERSION # Version file copy ├── uninstall.sh # Uninstaller (or ccs-uninstall.ps1 on Windows) └── .claude/ # Claude Code integration @@ -121,6 +85,36 @@ lib/ccs (bash) or lib/ccs.ps1 (PowerShell): └── skills/ccs-delegation/ ``` +### v3.0 Technical Implementation + +**Account-Based Profiles** (v3.0): +```bash +# Create profile (opens Claude CLI for login) +ccs auth create work + +# Creates ~/.ccs/instances/work/ with: +# - settings.json (Claude's config) +# - session files +# - todo lists +# - logs + +# Usage: Set CLAUDE_CONFIG_DIR before spawning Claude CLI +CLAUDE_CONFIG_DIR=~/.ccs/instances/work claude [args] +``` + +**Settings-Based Profiles** (legacy, still supported): +```bash +# Usage: Pass --settings flag to Claude CLI +claude --settings ~/.ccs/glm.settings.json [args] +``` + +**Profile Detection Logic**: +1. Check if profile exists in `profiles.json` (account-based) +2. If yes → use `CLAUDE_CONFIG_DIR` method +3. If no → check `config.json` (settings-based) +4. If yes → use `--settings` method +5. If no → show error with available profiles + ## Development Commands ### Version Management @@ -153,11 +147,11 @@ cat VERSION ./ccs glm --help # Test npm package locally -npm pack # Creates kai-ccs-X.Y.Z.tgz -npm install -g kai-ccs-X.Y.Z.tgz # Test installation +npm pack # Creates @kaitranntt-ccs-X.Y.Z.tgz +npm install -g @kaitranntt-ccs-X.Y.Z.tgz # Test installation ccs --version # Verify it works npm uninstall -g @kaitranntt/ccs # Cleanup -rm kai-ccs-X.Y.Z.tgz # Remove tarball +rm @kaitranntt-ccs-X.Y.Z.tgz # Remove tarball # Clean test environment rm -rf ~/.ccs @@ -206,6 +200,12 @@ npm publish --access public # Publish to npm registry - Native JSON parsing via `ConvertFrom-Json` / `ConvertTo-Json` - No external dependencies required +### Node.js (npm package) +- Compatibility: Node.js 14+ +- Use `child_process.spawn` for Claude CLI execution +- Handle SIGINT/SIGTERM for graceful shutdown +- Cross-platform path handling with `path` module + ### Version Synchronization When changing version, update ALL three locations: 1. `VERSION` file @@ -221,7 +221,7 @@ The `ccs` wrapper uses smart detection: - No args OR first arg starts with `-` → use default profile - First arg doesn't start with `-` → treat as profile name - Special flags handled BEFORE profile detection: `--version`, `-v`, `--help`, `-h` -- WIP: `--install` / `--uninstall` flags disabled pending .claude/ integration testing +- `ccs auth create ` → create new account-based profile ### Installation Modes - **Git mode**: Running from cloned repository (symlinks executables) @@ -252,18 +252,42 @@ Install scripts must be safe to run multiple times: All values must be strings (not booleans/objects) to prevent PowerShell crashes. +### v3.0 Profile Files + +**profiles.json** (account-based profiles): +```json +{ + "profiles": { + "work": "~/.ccs/instances/work", + "personal": "~/.ccs/instances/personal", + "team": "~/.ccs/instances/team" + } +} +``` + +**config.json** (settings-based profiles): +```json +{ + "profiles": { + "glm": "~/.ccs/glm.settings.json", + "kimi": "~/.ccs/kimi.settings.json", + "default": "~/.claude/settings.json" + } +} +``` + ## Common Tasks ### Adding a New Feature 1. Verify it aligns with YAGNI/KISS/DRY principles -2. Implement for both bash and PowerShell +2. Implement for both bash/PowerShell and Node.js if applicable 3. Test on all platforms (macOS, Linux, Windows) 4. Update tests in `tests/edge-cases.sh` and `tests/edge-cases.ps1` -5. Update relevant documentation in `docs/` +5. Update CONTRIBUTING.md if it affects contributors ### Fixing Bugs 1. Add test case reproducing the bug -2. Fix in both bash and PowerShell versions +2. Fix in both bash/PowerShell and Node.js versions 3. Verify fix doesn't break existing tests 4. Test on all supported platforms @@ -273,6 +297,7 @@ All values must be strings (not booleans/objects) to prevent PowerShell crashes. 3. Test installation from both git and standalone modes 4. Run full edge case test suite 5. Commit and tag: `git tag v` +6. Push to trigger GitHub Actions: `git push origin main && git push origin v` ## Testing Requirements @@ -291,6 +316,8 @@ Before any PR, verify: - [ ] Shell reload instructions shown correctly - [ ] PATH not duplicated on multiple installs - [ ] Manual PATH setup instructions clear if auto fails +- [ ] v3.0 concurrent sessions work correctly +- [ ] Instance isolation works (no cross-profile contamination) ## Integration with Claude Code @@ -298,11 +325,10 @@ The `.claude/` folder contains: - `/ccs` command: Meta-command for delegating tasks to different models - `ccs-delegation` skill: Intelligent task delegation patterns -**WIP**: Installation via `ccs --install` disabled pending .claude/ integration testing - ## Error Handling Philosophy - Validate early, fail fast with clear error messages - Show available options when user makes mistake - Suggest recovery steps (e.g., restore from backup) - Never leave system in broken state +- For v3.0 profiles: Guide users through `ccs auth create` if profile missing diff --git a/docs/en/contributing.md b/CONTRIBUTING.md similarity index 100% rename from docs/en/contributing.md rename to CONTRIBUTING.md diff --git a/README.ja.md b/README.ja.md index e096ddbf..423bed29 100644 --- a/README.ja.md +++ b/README.ja.md @@ -4,9 +4,10 @@ ![CCS Logo](docs/assets/ccs-logo-medium.png) -**1つのコマンドで、ダウンタイムなし、タスクごとに最適なモデルを選択** +**1コマンド、ダウンタイムなし、複数アカウント** -Claude Sonnet 4.5、GLM 4.6、Kimi for Coding を瞬時に切り替え。レート制限を回避し、コストを最適化。 +複数のClaudeアカウント、GLM、Kimiを瞬時に切り替え。
+レート制限を回避し、継続的に作業。 [![License](https://img.shields.io/badge/license-MIT-C15F3C?style=for-the-badge)](LICENSE) @@ -38,7 +39,18 @@ claude /login npm install -g @kaitranntt/ccs ``` -npm、yarn、pnpm、bunパッケージマネージャーと互換性があります。 +主要なパッケージマネージャーすべてに対応: + +```bash +# yarn +yarn global add @kaitranntt/ccs + +# pnpm(ディスク使用量70%削減) +pnpm add -g @kaitranntt/ccs + +# bun(30倍高速) +bun add -g @kaitranntt/ccs +``` #### オプション2: 直接インストール(従来型) @@ -52,41 +64,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -### 最初の切り替え - -```bash -# Claudeサブスクリプションを使用(デフォルト) -ccs "このアーキテクチャ設計をレビューして" - -# GLMに切り替えてコスト最適化されたタスクを実行 -ccs glm "シンプルなREST APIを作成して" - -# Kimiに切り替えて別のオプションを使用 -ccs kimi "統合テストを書いて" - -# 切り替えが戻されるまで、以降のすべてのコマンドでGLMを使用 -ccs glm -ccs "この問題をデバッグして" -ccs "ユニットテストを書いて" -``` - -#### パッケージマネージャーオプション - -主要なパッケージマネージャーすべてに対応: - -```bash -# npm(デフォルト) -npm install -g @kaitranntt/ccs - -# yarn -yarn global add @kaitranntt/ccs - -# pnpm(ディスク使用量70%削減) -pnpm add -g @kaitranntt/ccs - -# bun(30倍高速) -bun add -g @kaitranntt/ccs -``` +> **💡 パフォーマンス**: 従来型インストールはNode.jsルーティングをバイパスし起動が高速ですが、デプロイ自動化が容易なためnpm更新を優先します。 ### 設定(自動作成) @@ -116,88 +94,137 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows --- +### 最初の切り替え + +> **⚠️ 重要**: GLMまたはKimiプロファイルを使用する前に、対応する設定ファイルでAPIキーを更新する必要があります: +> - **GLM**: `~/.ccs/glm.settings.json`を編集してGLM APIキーを追加 +> - **Kimi**: `~/.ccs/kimi.settings.json`を編集してKimi APIキーを追加 + +```bash +# Claudeサブスクリプションを使用(デフォルト)で高レベルの計画 +ccs "マイクロサービスアーキテクチャの実装計画を立てて" + +# GLMに切り替えてコスト最適化されたタスクを実行 +ccs glm "シンプルなREST APIを作成して" + +# Kimiに切り替えて思考能力を活用 +ccs kimi "適切なエラーハンドリングで統合テストを書いて" +``` + +--- + ## 日常の開発者の課題 -Claudeサブスクリプション、GLM Coding Plan、Kimi for Codingを持っている場合、毎日3つのシナリオが発生します: +開発者は日々多くのサブスクリプションシナリオに直面します: -1. **レート制限に達する**: Claudeがプロジェクト途中で停止 → 手動で`~/.claude/settings.json`を編集 -2. **コストの無駄**: 単純なタスクに高価なClaudeを使用 → GLMやKimiで十分 -3. **モデル選択**: タスクごとに異なるモデルの強みを活用 → 手動切り替え +1. **アカウント分離**: 会社のClaudeアカウントと個人のClaude → 業務と個人のコンテキストを手動で切り替える必要 +2. **レート制限**: Claudeがプロジェクト途中で停止 → 手動で`~/.claude/settings.json`を編集 +3. **コスト管理**: 2-3つのProサブスクリプション(月$20) vs Claude Maxの5倍コスト(月$100)→ Pro階層が実用的な上限 +4. **モデル選択**: タスクごとに異なるモデルの強みを活用 → 手動切り替え -手動切り替えはフローを中断します。**CCSはこれを瞬時に解決します**。 +手動コンテキスト切り替えはワークフローを中断します。**CCSがシームレスに管理します**。 ## 手動切り替えではなくCCSを使う理由は?
-| 機能 | メリット | 感情的価値 | -|---------|---------|-----------------| -| **即座の切り替え** | 1つのコマンド、ファイル編集不要 | 自信、コントロール | -| **ゼロダウンタイム** | ワークフローを中断しない | 信頼性、一貫性 | -| **スマート委譲** | タスクごとに適切なモデルを自動選択 | シンプルさ、容易さ | -| **コスト管理** | 必要な時だけ高価なモデルを使用 | 効率性、節約 | -| **クロスプラットフォーム** | macOS、Linux、Windowsで動作 | 柔軟性、移植性 | -| **信頼性** | 純粋なbash/PowerShell、依存関係なし | 信頼、安心 | +| 機能 | メリット | +|---------|---------| +| **アカウント分離** | 業務と個人を分離 | +| **コスト最適化** | 2-3つのProアカウント vs Max 5倍コスト | +| **即座の切り替え** | 1コマンド、ファイル編集不要 | +| **ゼロダウンタイム** | ワークフロー中断なし | +| **レート制限管理** | 制限時にアカウント切り替え | +| **クロスプラットフォーム** | macOS、Linux、Windows |
**ソリューション**: ```bash -ccs # Claudeサブスクリプションを使用(デフォルト) -ccs glm # GLMフォールバックに切り替え -ccs kimi # Kimi for Codingに切り替え +ccs work # 会社のClaudeアカウントを使用 +ccs personal # 個人Claudeアカウントに切り替え +ccs glm # コスト効率の良いタスク用にGLMに切り替え +ccs kimi # 代替オプション用にKimiに切り替え # レート制限に達した?即座に切り替え: -ccs glm # GLMで作業を続行 -# またはKimiに切り替え: -ccs kimi # Kimiで作業を続行 +ccs glm # GLMで作業を続行 +# 別の会社アカウントが必要? +ccs work-2 # 2番目の会社アカウントに切り替え ``` -1つのコマンド。ダウンタイムなし。ファイル編集不要。適切なモデル、適切なタスク。 - --- ## 🏗️ アーキテクチャ概要 +**v3.0 Login-Per-Profileモデル**: 各プロファイルは独立したClaudeインスタンスで、ユーザーが直接ログインします。資格情報のコピーやvault暗号化は不要です。 + ```mermaid -graph LR - subgraph "ユーザーコマンド" - CMD[ccs glm] +flowchart TD + subgraph "ユーザー入力" + USER["ユーザー実行: ccs <profile> [args...]"] end - subgraph "CCS処理" - CONFIG[~/.ccs/config.jsonを読み込み] - LOOKUP[プロファイル → 設定ファイルを検索] - VALIDATE[ファイル存在を検証] + subgraph "プロファイル検出エンジン" + DETECT[ProfileDetector] + PROFILE_CHECK{プロファイル存在?} + + subgraph "プロファイルタイプ" + SETTINGS["Settings-based
glm, kimi, default"] + ACCOUNT["Account-based
work, personal, team"] + end end - subgraph "Claude CLI" - EXEC[claude --settings file_path] + subgraph "CCSコア処理" + CONFIG["config.jsonと
profiles.jsonを読み込み"] + + subgraph "プロファイルハンドラー" + SETTINGS_MGR["SettingsManager
→ --settings flag"] + INSTANCE_MGR["InstanceManager
→ CLAUDE_CONFIG_DIR"] + end end - subgraph "APIレスポンス" - API[Claude Sub または GLM API] + subgraph "Claude CLI実行" + CLAUDE_DETECT["Claude CLI検出
CCS_CLAUDE_PATHサポート"] + + subgraph "実行方法" + SETTINGS_EXEC["claude --settings <path>"] + INSTANCE_EXEC["CLAUDE_CONFIG_DIR=<instance> claude"] + end end - CMD --> CONFIG - CONFIG --> LOOKUP - LOOKUP --> VALIDATE - VALIDATE --> EXEC - EXEC --> API + subgraph "APIレイヤー" + API["API Response
Claude Sonnet 4.5
GLM 4.6
Kimi K2 Thinking"] + end + + %% Flow connections + USER --> DETECT + DETECT --> PROFILE_CHECK + PROFILE_CHECK -->|はい| SETTINGS + PROFILE_CHECK -->|はい| ACCOUNT + + SETTINGS --> CONFIG + ACCOUNT --> CONFIG + + CONFIG --> SETTINGS_MGR + CONFIG --> INSTANCE_MGR + + SETTINGS_MGR --> SETTINGS_EXEC + INSTANCE_MGR --> INSTANCE_EXEC + + SETTINGS_EXEC --> CLAUDE_DETECT + INSTANCE_EXEC --> CLAUDE_DETECT + + CLAUDE_DETECT --> API ``` --- ## ⚡ 機能 -### 即座のプロファイル切り替え -- **1つのコマンド**: `ccs glm`でGLMに切り替え、`ccs`でClaudeサブスクリプションを使用 - 設定ファイルの編集不要 -- **スマート検出**: タスクごとに適切なモデルを自動使用 -- **永続的**: 再度変更されるまで切り替えは有効 - -### ワークフロー中断なし -- **ダウンタイムなし**: コマンド間で即座に切り替え -- **コンテキスト保持**: ワークフローは中断されない -- **シームレスな統合**: ネイティブのClaude CLIと全く同じように動作 +- **即座の切り替え** - `ccs glm`でGLMに切り替え、設定編集不要 +- **同時セッション** - 複数のプロファイルを異なるターミナルで同時実行 +- **独立したインスタンス** - 各プロファイルが独自の設定を保持 (`~/.ccs/instances//`) +- **クロスプラットフォーム** - macOS、Linux、Windows - 同一動作 +- **ダウンタイムなし** - 即座に切り替え、ワークフロー中断なし --- @@ -211,32 +238,51 @@ ccs kimi # Kimi for Codingを使用 ccs --version # CCSバージョンとインストール場所を表示 ``` +### 同時セッション (Multi-Account) +```bash +# 複数のClaudeアカウントを作成 +ccs auth create work # 業務用アカウント +ccs auth create personal # 個人用アカウント +ccs auth create team # チーム用アカウント + +# ターミナル1 - 業務用アカウント +ccs work "implement feature" + +# ターミナル2 - 個人用アカウント(同時実行) +ccs personal "review code" +``` + --- -### 🗑️ 公式アンインストール +### 🗑️ アンインストール -**CCSを完全に削除する推奨方法:** +**パッケージマネージャー** +```bash +# npm +npm uninstall -g @kaitranntt/ccs -**macOS / Linux**: +# yarn +yarn global remove @kaitranntt/ccs + +# pnpm +pnpm remove -g @kaitranntt/ccs + +# bun +bun remove -g @kaitranntt/ccs +``` + +**公式アンインストーラー** + +**macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/uninstall | bash ``` -**Windows PowerShell**: +**Windows PowerShell** ```powershell irm ccs.kaitran.ca/uninstall | iex ``` -> 💡 **公式アンインストーラーを使用する理由は?** -> - すべてのCCSファイルと設定を削除 -> - PATH変更をクリーンアップ -> - Claude CLIコマンド/スキルを削除 -> - テスト済みのエッジケースに対応 - -**代替方法**(公式アンインストーラーが失敗した場合): -- **npm**: `npm uninstall -g @kaitranntt/ccs` -- **手動**: [トラブルシューティングガイド](./docs/en/troubleshooting.md#manual-uninstall)を参照 - --- ## 🎯 哲学 @@ -254,13 +300,13 @@ irm ccs.kaitran.ca/uninstall | iex - [設定](./docs/en/configuration.md) - [使用例](./docs/en/usage.md) - [トラブルシューティング](./docs/en/troubleshooting.md) -- [コントリビューション](./docs/en/contributing.md) +- [コントリビューション](./CONTRIBUTING.md) --- ## 🤝 コントリビューション -コントリビューションを歓迎します!詳細については[コントリビューションガイド](./docs/en/contributing.md)をご覧ください。 +コントリビューションを歓迎します!詳細については[コントリビューションガイド](./CONTRIBUTING.md)をご覧ください。 --- diff --git a/README.md b/README.md index 405a0b24..6e13cd31 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,10 @@ ![CCS Logo](docs/assets/ccs-logo-medium.png) -**One command, zero downtime, right model for each task** +**One command, zero downtime, multiple accounts** -Switch between Claude Sonnet 4.5, GLM 4.6, and Kimi for Coding instantly. Stop hitting rate limits. Start optimizing costs. +Switch between multiple Claude accounts, GLM, and Kimi instantly.
+Stop hitting rate limits. Keep working continuously. [![License](https://img.shields.io/badge/license-MIT-C15F3C?style=for-the-badge)](LICENSE) @@ -38,7 +39,18 @@ claude /login npm install -g @kaitranntt/ccs ``` -Compatible with npm, yarn, pnpm, and bun package managers. +All major package managers are supported: + +```bash +# yarn +yarn global add @kaitranntt/ccs + +# pnpm (70% less disk space) +pnpm add -g @kaitranntt/ccs + +# bun (30x faster) +bun add -g @kaitranntt/ccs +``` #### Option 2: Direct Install (Traditional) @@ -52,41 +64,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -### Your First Switch - -```bash -# Use Claude subscription (default) -ccs "Review this architecture design" - -# Switch to GLM for cost-optimized tasks -ccs glm "Create a simple REST API" - -# Switch to Kimi for alternative option -ccs kimi "Write integration tests" - -# Use GLM for all subsequent commands until switched back -ccs glm -ccs "Debug this issue" -ccs "Write unit tests" -``` - -#### Package Manager Options - -All major package managers are supported: - -```bash -# npm (default) -npm install -g @kaitranntt/ccs - -# yarn -yarn global add @kaitranntt/ccs - -# pnpm (70% less disk space) -pnpm add -g @kaitranntt/ccs - -# bun (30x faster) -bun add -g @kaitranntt/ccs -``` +> **💡 Performance Tip**: Traditional installs bypass Node.js routing for faster startup, but I prioritize npm updates due to easier deployment automation. ### Configuration (Auto-created) @@ -116,107 +94,137 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows --- +### Your First Switch + +> **⚠️ Important**: Before using GLM or Kimi profiles, you need to update your API keys in their respective settings files: +> - **GLM**: Edit `~/.ccs/glm.settings.json` and add your GLM API key +> - **Kimi**: Edit `~/.ccs/kimi.settings.json` and add your Kimi API key + +```bash +# Use Claude subscription (default) for high-level planning +ccs "Plan the implementation of a microservices architecture" + +# Switch to GLM for cost-optimized tasks +ccs glm "Create a simple REST API" + +# Switch to Kimi for its thinking capabilities +ccs kimi "Write integration tests with proper error handling" +``` + +--- + ## The Daily Developer Pain Point -You have Claude subscription, GLM Coding Plan, and Kimi for Coding. Three scenarios happen every day: +Developers face multiple subscription scenarios daily: -1. **Rate Limits Hit**: Claude stops mid-project → you manually edit `~/.claude/settings.json` -2. **Cost Waste**: Simple tasks use expensive Claude → GLM or Kimi would work fine -3. **Model Choice**: Different tasks benefit from different model strengths → manual switching +1. **Account Separation**: Company Claude account vs personal Claude → you must manually switch contexts to keep work and personal separate +2. **Rate Limits Hit**: Claude stops mid-project → you manually edit `~/.claude/settings.json` +3. **Cost Management**: 2-3 Pro subscriptions ($20/month each) vs Claude Max at 5x cost ($100/month) → Pro tier is the practical ceiling for most developers +4. **Model Choice**: Different tasks benefit from different model strengths → manual switching -Manual switching breaks your flow. **CCS fixes it instantly**. +Manual context switching breaks your workflow. **CCS manages it seamlessly**. ## Why CCS Instead of Manual Switching?
-| Feature | Benefit | Emotional Value | -|---------|---------|-----------------| -| **Instant Switching** | One command, no file editing | Confidence, control | -| **Zero Downtime** | Never interrupt your workflow | Reliability, consistency | -| **Smart Delegation** | Right model for each task automatically | Simplicity, ease | -| **Cost Control** | Use expensive models only when needed | Efficiency, savings | -| **Cross-Platform** | Works on macOS, Linux, Windows | Flexibility, portability | -| **Reliable** | Pure bash/PowerShell, zero dependencies | Trust, peace of mind | +| Feature | Benefit | +|---------|---------| +| **Account Isolation** | Keep work separate from personal | +| **Cost Optimization** | 2-3 Pro accounts vs Max at 5x cost | +| **Instant Switching** | One command, no file editing | +| **Zero Downtime** | Never interrupt workflow | +| **Rate Limit Management** | Switch accounts when limits hit | +| **Cross-Platform** | macOS, Linux, Windows |
**The Solution**: ```bash -ccs # Use Claude subscription (default) -ccs glm # Switch to GLM fallback -ccs kimi # Switch to Kimi for Coding +ccs work # Use company Claude account +ccs personal # Switch to personal Claude account +ccs glm # Switch to GLM for cost-effective tasks +ccs kimi # Switch to Kimi for alternative option # Hit rate limit? Switch instantly: -ccs glm # Continue working with GLM -# Or switch to Kimi: -ccs kimi # Continue working with Kimi +ccs glm # Continue working with GLM +# Need different company account? +ccs work-2 # Switch to second company account ``` -One command. Zero downtime. No file editing. Right model, right task. - --- -## 🏗️ Architecture Overview (v3.0 Simplified) +## 🏗️ Architecture Overview **v3.0 Login-Per-Profile Model**: Each profile is an isolated Claude instance where users login directly. No credential copying or vault encryption. ```mermaid -graph LR - subgraph "User Command" - CMD[ccs ] +flowchart TD + subgraph "User Input" + USER["User runs: ccs <profile> [args...]"] end - subgraph "Profile Detection" + subgraph "Profile Detection Engine" DETECT[ProfileDetector] - SETTINGS[Settings-based: glm, kimi] - ACCOUNT[Account-based: work, personal] + PROFILE_CHECK{Profile exists?} + + subgraph "Profile Types" + SETTINGS["Settings-based
glm, kimi, default"] + ACCOUNT["Account-based
work, personal, team"] + end end - subgraph "CCS Processing" - CONFIG[Read config.json/profiles.json] - INSTANCE[InstanceManager: lazy directory init] + subgraph "CCS Core Processing" + CONFIG["Read config.json
and profiles.json"] + + subgraph "Profile Handlers" + SETTINGS_MGR["SettingsManager
→ --settings flag"] + INSTANCE_MGR["InstanceManager
→ CLAUDE_CONFIG_DIR"] + end end subgraph "Claude CLI Execution" - SETTINGS_EXEC[claude --settings ] - INSTANCE_EXEC[CLAUDE_CONFIG_DIR= claude] + CLAUDE_DETECT["Claude CLI Detection
CCS_CLAUDE_PATH support"] + + subgraph "Execution Methods" + SETTINGS_EXEC["claude --settings <path>"] + INSTANCE_EXEC["CLAUDE_CONFIG_DIR=<instance> claude"] + end end - subgraph "API Response" - API[Claude/GLM/Kimi API] + subgraph "API Layer" + API["API Response
Claude Sonnet 4.5
GLM 4.6
Kimi K2 Thinking"] end - CMD --> DETECT - DETECT --> SETTINGS - DETECT --> ACCOUNT + %% Flow connections + USER --> DETECT + DETECT --> PROFILE_CHECK + PROFILE_CHECK -->|Yes| SETTINGS + PROFILE_CHECK -->|Yes| ACCOUNT + SETTINGS --> CONFIG - ACCOUNT --> INSTANCE - SETTINGS --> SETTINGS_EXEC - ACCOUNT --> INSTANCE_EXEC - SETTINGS_EXEC --> API - INSTANCE_EXEC --> API + ACCOUNT --> CONFIG + + CONFIG --> SETTINGS_MGR + CONFIG --> INSTANCE_MGR + + SETTINGS_MGR --> SETTINGS_EXEC + INSTANCE_MGR --> INSTANCE_EXEC + + SETTINGS_EXEC --> CLAUDE_DETECT + INSTANCE_EXEC --> CLAUDE_DETECT + + CLAUDE_DETECT --> API ``` --- ## ⚡ Features -### Instant Profile Switching -- **One Command**: `ccs glm` to switch to GLM, `ccs` to use Claude subscription - no config file editing -- **Smart Detection**: Automatically uses right model for each task -- **Persistent**: Switch stays active until changed again - -### Concurrent Sessions (All Platforms) -- **Multiple Profiles Simultaneously**: Run `ccs work` and `ccs personal` in different terminals concurrently -- **Isolated Instances**: Each profile gets own config directory (`~/.ccs/instances//`) -- **Independent Sessions**: Separate login, chat sessions, todos, logs per profile -- **Platform Parity**: Works identically on macOS, Linux, and Windows via `CLAUDE_CONFIG_DIR` -- **Backward Compatible**: Existing settings profiles (glm, kimi) work unchanged - -### Zero Workflow Interruption -- **No Downtime**: Switching happens instantly between commands -- **Context Preservation**: Your workflow remains uninterrupted -- **Seamless Integration**: Works exactly like native Claude CLI +- **Instant Switching** - `ccs glm` switches to GLM, no config editing +- **Concurrent Sessions** - Run multiple profiles simultaneously in different terminals +- **Isolated Instances** - Each profile gets own config (`~/.ccs/instances//`) +- **Cross-Platform** - macOS, Linux, Windows - identical behavior +- **Zero Downtime** - Switch instantly, no workflow interruption --- @@ -233,46 +241,49 @@ ccs --version # Show CCS version and install location ### Concurrent Sessions (Multi-Account) ```bash -# First time: Create profile and login -ccs auth create work # Opens Claude, prompts for login -ccs auth create personal # Opens Claude, prompts for login +# Create multiple Claude accounts +ccs auth create work # Company account +ccs auth create personal # Personal account +ccs auth create team # Team account # Terminal 1 - Work account ccs work "implement feature" -# Terminal 2 - Personal account (concurrent) +# Terminal 2 - Personal account (runs concurrently) ccs personal "review code" - -# Both run simultaneously with isolated logins/sessions -# Works on all platforms: macOS, Linux, Windows ``` --- -### 🗑️ Official Uninstall +### 🗑️ Uninstall -**The recommended way to completely remove CCS:** +**Package Managers** +```bash +# npm +npm uninstall -g @kaitranntt/ccs -**macOS / Linux**: +# yarn +yarn global remove @kaitranntt/ccs + +# pnpm +pnpm remove -g @kaitranntt/ccs + +# bun +bun remove -g @kaitranntt/ccs +``` + +**Official Uninstaller** + +**macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/uninstall | bash ``` -**Windows PowerShell**: +**Windows PowerShell** ```powershell irm ccs.kaitran.ca/uninstall | iex ``` -> 💡 **Why use the official uninstaller?** -> - Removes all CCS files and configurations -> - Cleans up PATH modifications -> - Removes Claude CLI commands/skills -> - Handles edge cases we've tested - -**Alternative methods** (if official uninstaller fails): -- **npm**: `npm uninstall -g @kaitranntt/ccs` -- **Manual**: See [troubleshooting guide](./docs/en/troubleshooting.md#manual-uninstall) - --- ## 🎯 Philosophy @@ -290,13 +301,13 @@ irm ccs.kaitran.ca/uninstall | iex - [Configuration](./docs/en/configuration.md) - [Usage Examples](./docs/en/usage.md) - [Troubleshooting](./docs/en/troubleshooting.md) -- [Contributing](./docs/en/contributing.md) +- [Contributing](./CONTRIBUTING.md) --- ## 🤝 Contributing -We welcome contributions! Please see our [Contributing Guide](./docs/en/contributing.md) for details. +We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. --- diff --git a/README.vi.md b/README.vi.md index 7d04d16d..482ee03e 100644 --- a/README.vi.md +++ b/README.vi.md @@ -4,9 +4,10 @@ ![CCS Logo](docs/assets/ccs-logo-medium.png) -**Một lệnh, không downtime, đúng model cho từng tác vụ** +**Một lệnh, không downtime, nhiều tài khoản** -Chuyển đổi giữa Claude Sonnet 4.5 và GLM 4.6 ngay lập tức. Ngừng hitting rate limits. Bắt đầu tối ưu chi phí. +Chuyển đổi giữa nhiều tài khoản Claude, GLM, và Kimi ngay lập tức.
+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) @@ -37,7 +38,18 @@ claude /login npm install -g @kaitranntt/ccs ``` -Tương thích với các trình quản lý package npm, yarn, pnpm, và bun. +Tất cả các trình quản lý package chính đều được hỗ trợ: + +```bash +# yarn +yarn global add @kaitranntt/ccs + +# pnpm (ít hơn 70% dung lượng đĩa) +pnpm add -g @kaitranntt/ccs + +# bun (nhanh hơn 30x) +bun add -g @kaitranntt/ccs +``` #### Option 2: Cài Đặt Trực Tiếp (Truyền thống) @@ -51,38 +63,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -### Lần Chuyển Đổi Đầu Tiên - -```bash -# Dùng Claude subscription (mặc định) -ccs "Review thiết kế kiến trúc này" - -# Chuyển sang GLM cho tác vụ tối ưu chi phí -ccs glm "Tạo REST API đơn giản" - -# Dùng GLM cho tất cả lệnh tiếp theo cho đến khi chuyển lại -ccs glm -ccs "Debug issue này" -ccs "Viết unit tests" -``` - -#### Package Manager Options - -Tất cả các trình quản lý package chính đều được hỗ trợ: - -```bash -# npm (mặc định) -npm install -g @kaitranntt/ccs - -# yarn -yarn global add @kaitranntt/ccs - -# pnpm (ít hơn 70% dung lượng đĩa) -pnpm add -g @kaitranntt/ccs - -# bun (nhanh hơn 30x) -bun add -g @kaitranntt/ccs -``` +> **💡 Mẹo hiệu năng**: Cài truyền thống bỏ qua Node.js routing để khởi động nhanh hơn, nhưng tôi ưu tiên cập nhật npm do triển khai dễ dàng hơn. ### Cấu Hình (Tự Tạo) @@ -111,84 +92,137 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows --- +### 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 + +```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" + +# 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 Kimi để sử dụng khả năng thinking +ccs kimi "Viết integration tests với xử lý lỗi phù hợp" +``` + +--- + ## Điểm Đau Hàng Ngày Của Lập Trình Viên -Bạn có cả Claude subscription và GLM Coding Plan. Hai tình huống xảy ra hàng ngày: +Lập trình viên đối mặt nhiều kịch bản subscription hàng ngày: -1. **Hết Rate Limit**: Claude dừng giữa chừng project → bạn phải tự tay sửa `~/.claude/settings.json` -2. **Lãng Phí Chi Phí**: Tác vụ đơn giản dùng Claude đắt tiền → GLM cũng làm tốt +1. **Phân Tách Account**: Tài khoản Claude công ty vs Claude cá nhân → bạn phải tự chuyển context để giữ công việc và cá nhân riêng biệt +2. **Hết Rate Limit**: Claude dừng giữa chừng project → bạn phải tự tay sửa `~/.claude/settings.json` +3. **Quản Lý Chi Phí**: 2-3 subscriptions Pro ($20/tháng) vs Claude Max với chi phí 5x ($100/tháng) → Tier Pro là ngưỡng thực tế cho hầu hết lập trình viên +4. **Lựa Chọn Model**: Tác vụ khác nhau hưởng lợi từ thế mạnh model khác nhau → chuyển đổi thủ công -Chuyển đổi thủ công làm gián đoạn workflow của bạn. **CCS khắc phục ngay lập tức**. +Chuyển đổi context thủ công làm gián đoạn workflow. **CCS quản lý liền mạch**. ## Tại Sao CCS Thay Vì Chuyển Đổi Thủ Công?
-| Tính năng | Lợi ích | Giá trị cảm xúc | -|-----------|---------|-----------------| -| **Chuyển đổi tức thì** | Một lệnh, không sửa file | Tự tin, kiểm soát | -| **Không downtime** | Không bao giờ gián đoạn workflow | Đáng tin cậy, nhất quán | -| **Delegation thông minh** | Đúng model cho từng tác vụ tự động | Đơn giản, dễ dàng | -| **Kiểm soát chi phí** | Dùng model đắt tiền chỉ khi cần | Hiệu quả, tiết kiệm | -| **Đa nền tảng** | Hoạt động trên macOS, Linux, Windows | Linh hoạt, di động | -| **Đáng tin cậy** | Bash/PowerShell thuần, không dependencies | Tin tưởng, an tâm | +| Tính năng | Lợi ích | +|-----------|---------| +| **Phân Cách Account** | Giữ công việc riêng với cá nhân | +| **Tối Ưu Chi Phí** | 2-3 account Pro vs Max 5x chi phí | +| **Chuyển Đổi Tức Thì** | Một lệnh, không sửa file | +| **Không Downtime** | Không gián đoạn workflow | +| **Quản Lý Rate Limit** | Chuyển account khi hết limit | +| **Đa Nền Tảng** | macOS, Linux, Windows |
**Giải pháp**: ```bash -ccs # Dùng Claude subscription (mặc định) -ccs glm # Chuyển sang GLM fallback +ccs cong-ty # Dùng account Claude công ty +ccs ca-nhan # Chuyển sang account Claude cá nhân +ccs glm # Chuyển sang GLM cho tác vụ tối ưu chi phí +ccs kimi # Chuyển sang Kimi cho lựa chọn thay thế # Hết rate limit? Chuyển ngay: -ccs glm # Tiếp tục làm việc với GLM +ccs glm # Tiếp tục làm việc với GLM +# Cần account công ty khác? +ccs cong-ty-2 # Chuyển sang account công ty thứ hai ``` -Một lệnh. Không downtime. Không phải sửa file. Đúng model, đúng việc. - --- ## 🏗️ Tổng Quan Kiến Trúc +**v3.0 Mô hình Login-Per-Profile**: Mỗi profile là một Claude instance riêng biệt nơi người dùng đăng nhập trực tiếp. Không cần sao chép credentials hay vault encryption. + ```mermaid -graph LR - subgraph "Lệnh Người Dùng" - CMD[ccs glm] +flowchart TD + subgraph "Người Dùng Input" + USER["User chạy: ccs <profile> [args...]"] end - subgraph "Xử Lý CCS" - CONFIG[Đọc ~/.ccs/config.json] - LOOKUP[Tìm profile → file settings] - VALIDATE[Kiểm tra file tồn tại] + subgraph "Engine Phát Hiện Profile" + DETECT[ProfileDetector] + PROFILE_CHECK{Profile tồn tại?} + + subgraph "Loại Profile" + SETTINGS["Settings-based
glm, kimi, default"] + ACCOUNT["Account-based
work, personal, team"] + end end - subgraph "Claude CLI" - EXEC[claude --settings file_path] + subgraph "Xử Lý Core CCS" + CONFIG["Đọc config.json
và profiles.json"] + + subgraph "Profile Handlers" + SETTINGS_MGR["SettingsManager
→ --settings flag"] + INSTANCE_MGR["InstanceManager
→ CLAUDE_CONFIG_DIR"] + end end - subgraph "Phản Hồi API" - API[Claude hoặc GLM API] + subgraph "Thực Thi Claude CLI" + CLAUDE_DETECT["Claude CLI Detection
Hỗ trợ CCS_CLAUDE_PATH"] + + subgraph "Phương Thức Thực Thi" + SETTINGS_EXEC["claude --settings <path>"] + INSTANCE_EXEC["CLAUDE_CONFIG_DIR=<instance> claude"] + end end - CMD --> CONFIG - CONFIG --> LOOKUP - LOOKUP --> VALIDATE - VALIDATE --> EXEC - EXEC --> API + subgraph "API Layer" + API["API Response
Claude Sonnet 4.5
GLM 4.6
Kimi K2 Thinking"] + end + + %% Flow connections + USER --> DETECT + DETECT --> PROFILE_CHECK + PROFILE_CHECK -->|Có| SETTINGS + PROFILE_CHECK -->|Có| ACCOUNT + + SETTINGS --> CONFIG + ACCOUNT --> CONFIG + + CONFIG --> SETTINGS_MGR + CONFIG --> INSTANCE_MGR + + SETTINGS_MGR --> SETTINGS_EXEC + INSTANCE_MGR --> INSTANCE_EXEC + + SETTINGS_EXEC --> CLAUDE_DETECT + INSTANCE_EXEC --> CLAUDE_DETECT + + CLAUDE_DETECT --> API ``` --- ## ⚡ Tính Năng -### Chuyển Profile Ngay Lập Tức -- **Một Lệnh**: `ccs glm` để chuyển sang GLM, `ccs` để dùng Claude subscription - không cần sửa file config -- **Phát Hiện Thông Minh**: Tự động dùng đúng model cho từng tác vụ -- **Liên Tục**: Chuyển đổi hoạt động cho đến khi thay đổi lại - -### Không Gián Đoạn Workflow -- **Không Downtime**: Chuyển đổi xảy ra ngay lập tức giữa các lệnh -- **Bảo Toàn Context**: Workflow của bạn không bị gián đoạn -- **Tích Hợp Liền Mạch**: Hoạt động chính xác như Claude CLI native +- **Chuyển Đổi Ngay Lập Tức** - `ccs glm` chuyển sang GLM, không cần sửa config +- **Phiên Đồng Thời** - Chạy nhiều profile cùng lúc ở các terminal khác nhau +- **Instance Riêng Biệt** - Mỗi profile có config riêng (`~/.ccs/instances//`) +- **Đa Nền Tảng** - macOS, Linux, Windows - hoạt động giống nhau +- **Không Downtime** - Chuyển đổi ngay lập tức, không gián đoạn workflow --- @@ -201,32 +235,51 @@ ccs glm # Dùng GLM fallback ccs --version # Hiển thị phiên bản CCS và vị trí cài đặt ``` +### Phiên Đồng Thời (Multi-Account) +```bash +# Tạo nhiều tài khoản Claude +ccs auth create cong-ty # Tài khoản công ty +ccs auth create ca-nhan # Tài khoản cá nhân +ccs auth create team # Tài khoản team + +# Terminal 1 - Tài khoản công ty +ccs cong-ty "implement feature" + +# Terminal 2 - Tài khoản cá nhân (chạy đồng thời) +ccs ca-nhan "review code" +``` + --- -### 🗑️ Gỡ Cài Đặt Chính Thức +### 🗑️ Gỡ Cài Đặt -**Cách được khuyến nghị để gỡ bỏ hoàn toàn CCS:** +**Package Managers** +```bash +# npm +npm uninstall -g @kaitranntt/ccs -**macOS / Linux**: +# yarn +yarn global remove @kaitranntt/ccs + +# pnpm +pnpm remove -g @kaitranntt/ccs + +# bun +bun remove -g @kaitranntt/ccs +``` + +**Uninstaller Chính Thức** + +**macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/uninstall | bash ``` -**Windows PowerShell**: +**Windows PowerShell** ```powershell irm ccs.kaitran.ca/uninstall | iex ``` -> 💡 **Tại sao dùng uninstaller chính thức?** -> - Gỡ bỏ tất cả file và cấu hình CCS -> - Dọn dẹp PATH modifications -> - Gỡ bỏ commands/skills Claude CLI -> - Xử lý các trường hợp đặc biệt đã test - -**Phương pháp thay thế** (nếu uninstaller chính thức thất bại): -- **npm**: `npm uninstall -g @kaitranntt/ccs` -- **Thủ công**: Xem [hướng dẫn khắc phục](./docs/vi/troubleshooting.vi.md#gỡ-cài-đặt-thủ-công) - --- ## 🎯 Triết Lý @@ -244,13 +297,13 @@ irm ccs.kaitran.ca/uninstall | iex - [Cấu hình](./docs/configuration.md) - [Ví dụ Sử dụng](./docs/usage.md) - [Khắc phục Sự cố](./docs/troubleshooting.md) -- [Đóng góp](./docs/contributing.md) +- [Đóng góp](./CONTRIBUTING.md) --- ## 🤝 Đóng Góp -Chúng tôi chào mừng đóng góp! Vui lòng xem [Hướng dẫn Đóng góp](./docs/contributing.md) để biết chi tiết. +Chúng tôi chào mừng đóng góp! Vui lòng xem [Hướng dẫn Đóng góp](./CONTRIBUTING.md) để biết chi tiết. --- diff --git a/docs/vi/contributing.vi.md b/docs/vi/contributing.vi.md deleted file mode 100644 index b58ac6c9..00000000 --- a/docs/vi/contributing.vi.md +++ /dev/null @@ -1,182 +0,0 @@ -# Hướng Dẫn Đóng Góp CCS - -## Nguyên Tắc Phát Triển - -### Triết Lý - -CCS tuân theo các nguyên tắc cốt lõi sau: - -- **YAGNI**: Không có tính năng "phòng hờ" -- **KISS**: Bash đơn giản, không phức tạp -- **DRY**: Một nguồn chân lý duy nhất (config) - -Công cụ này chỉ LÀM MỘT việc tốt: ánh xạ tên profile đến file settings. - -### Tiêu Chuẩn Code - -#### Yêu Cầu Tương Thích - -- **Unix**: tương thích bash 3.2+ -- **Windows**: tương thích PowerShell 5.1+ -- **Dependencies**: Chỉ jq (Unix) hoặc PowerShell có sẵn (Windows) - -#### Phong Cách Code - -**Bash (Unix)**: -- Sử dụng shebang `#!/usr/bin/env bash` -- Quote variables: `"$VAR"` không phải `$VAR` -- Sử dụng `[[ ]]` cho tests, không phải `[ ]` -- Tuân theo mẫu thụt lề và đặt tên hiện có - -**PowerShell (Windows)**: -- Sử dụng `CmdletBinding` và xử lý parameter đúng cách -- Tuân theo quy ước động-tên của PowerShell -- Sử dụng xử lý lỗi đúng cách với `try/catch` -- Duy trì tương thích với PowerShell 5.1+ - -### Kiểm Thử - -#### Kiểm Thử Nền Tảng - -Kiểm tra trên tất cả nền tảng trước khi gửi PR: -- macOS (bash) -- Linux (bash) -- Windows (PowerShell, CMD, Git Bash) - -#### Kịch Bản Kiểm Thử - -1. **Chức năng cơ bản**: - ```bash - ccs # Nên dùng profile mặc định - ccs glm # Nên dùng profile GLM - ccs --version # Nên hiển thị phiên bản - ``` - -2. **Với arguments**: - ```bash - ccs glm --help - ccs /plan "test" - ``` - -3. **Xử lý lỗi**: - ```bash - ccs invalid-profile # Nên hiển thị lỗi - ccs --invalid-flag # Nên chuyển cho Claude - ``` - -### Quy Trình Gửi - -#### Trước Khi Gửi - -1. Fork repository -2. Tạo feature branch: `git checkout -b feature-name` -3. Thực hiện thay đổi của bạn -4. Kiểm tra trên tất cả nền tảng -5. Đảm bảo các tests hiện có passes - -#### Yêu Cầu Pull Request - -- Mô tả rõ ràng các thay đổi -- Hướng dẫn kiểm thử nếu có -- Link đến các issues liên quan -- Tuân theo kiểu commit message hiện có - -#### Kiểu Commit Message - -``` -type(scope): description - -[optional body] - -[optional footer] -``` - -Ví dụ: -``` -fix(installer): handle git worktree detection -feat(config): support custom config location -docs(readme): update installation instructions -``` - -### Thiết Lập Phát Triển - -#### Phát Triển Địa Phương - -```bash -# Clone fork của bạn -git clone https://github.com/yourusername/ccs.git -cd ccs - -# Tạo feature branch -git checkout -b your-feature-name - -# Thực hiện thay đổi -# Kiểm tra địa phương với ./ccs - -# Chạy tests -./test.sh # nếu có -``` - -#### Kiểm Thử Installer - -```bash -# Kiểm thử installer Unix -./installers/install.sh - -# Kiểm thử installer Windows (trong PowerShell) -.\installers\install.ps1 -``` - -### Lĩnh Vực Đóng Góp - -#### Tính Năng Mong Muốn - -1. **Hỗ trợ profile bổ sung**: - - Validation profile tùy chỉnh - - Lối tắt chuyển profile - -2. **Xử lý lỗi nâng cao**: - - Thông báo lỗi tốt hơn - - Gợi ý khôi phục - -3. **Tài liệu**: - - Nhiều ví dụ hơn - - Hướng dẫn tích hợp - -#### Sửa Lỗi - -- Vấn đề installer trên các nền tảng khác nhau -- Edge cases trong parsing config -- Tương thích riêng của Windows - -### Quy Trình Review - -1. **Kiểm tra tự động**: - - Validation cú pháp - - Tests chức năng cơ bản - -2. **Review thủ công**: - - Chất lượng và phong cách code - - Tương thích nền tảng - - Phù hợp với triết lý - -3. **Kiểm thử**: - - Xác nhận đa nền tảng - - Kiểm thử tích hợp - -### Cộng Đồng - -#### Nhận Trợ Giúp - -- GitHub Issues: Báo lỗi hoặc yêu cầu tính năng -- Discussions: Hỏi câu hỏi hoặc chia sẻ ý tưởng - -#### Quy Tắc Ứng Xử - -Hãy tôn trọng, mang tính xây dựng, và tập trung vào triết lý đơn giản và đáng tin cậy của dự án. - ---- - -**Cảm ơn bạn đã đóng góp cho CCS!** - -Hãy nhớ: Giữ nó đơn giản, kiểm thử kỹ lưỡng, và trung thành với triết lý YAGNI/KISS/DRY. \ No newline at end of file