tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-15 12:13:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: streamline READMEs and update project documentation

Browse Source 
- Streamline Features section (65% shorter, bullet points only)
- Remove redundant 'Why CCS' table column
- Fix 'Sub-Account' → 'Multiple Accounts' terminology
- Update tagline to highlight v3.0 multi-account capabilities
- Merge duplicate sections (Concurrent Sessions)
- Remove unrealistic usage examples
- Fix weird formatting and stray content
- Streamline Uninstall section with package managers grouped
- Create root-level CONTRIBUTING.md (GitHub standard)
- Remove duplicate docs/en/contributing.md and docs/vi/contributing.vi.md
- Update all README links to point to root CONTRIBUTING.md
- Refactor CLAUDE.md for v3.0 architecture
  - Update project overview to highlight multiple Claude accounts
  - Add v3.0 technical details (CLAUDE_CONFIG_DIR, profiles.json, instances/)
  - Remove redundant high-level flow (now in README)
  - Add Node.js code standards
  - Document two profile types (settings vs account-based)
  - Update testing requirements for v3.0

Total reduction: 46 lines across all READMEs
Cross-language consistency: EN/VI/JA fully synchronized
This commit is contained in:
kaitranntt committed 2025-11-09 17:11:58 -05:00
1 parent 7c93cadf95
commit 96701a4992
6 files changed
+519 -565
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+96 -70
View File
@@ -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 <path> [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 <profile>`. 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 <path> [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 <path> [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 <profile>` → 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<VERSION>`
6. Push to trigger GitHub Actions: `git push origin main && git push origin v<VERSION>`
## 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
docs/en/contributing.md → CONTRIBUTING.md
View File
File renamed without changes.
README.ja.md
+146 -100
View File
@@ -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を瞬時に切り替え。<br>
レート制限を回避し、継続的に作業。
[![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を使う理由は？
<div align="center">
| 機能 | メリット | 感情的価値 |
|---------|---------|-----------------|
| **即座の切り替え** | 1つのコマンド、ファイル編集不要 | 自信、コントロール |
| **ゼロダウンタイム** | ワークフローを中断しない | 信頼性、一貫性 |
| **スマート委譲** | タスクごとに適切なモデルを自動選択 | シンプルさ、容易さ |
| **コスト管理** | 必要な時だけ高価なモデルを使用 | 効率性、節約 |
| **クロスプラットフォーム** | macOS、Linux、Windowsで動作 | 柔軟性、移植性 |
| **信頼性** | 純粋なbash/PowerShell、依存関係なし | 信頼、安心 |
| 機能 | メリット |
|---------|---------|
| **アカウント分離** | 業務と個人を分離 |
| **コスト最適化** | 2-3つのProアカウント vs Max 5倍コスト |
| **即座の切り替え** | 1コマンド、ファイル編集不要 |
| **ゼロダウンタイム** | ワークフロー中断なし |
| **レート制限管理** | 制限時にアカウント切り替え |
| **クロスプラットフォーム** | macOS、Linux、Windows |
</div>
**ソリューション**:
```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 &lt;profile&gt; [args...]"]
end
subgraph "CCS処理"
CONFIG[~/.ccs/config.jsonを読み込み]
LOOKUP[プロファイル → 設定ファイルを検索]
VALIDATE[ファイル存在を検証]
subgraph "プロファイル検出エンジン"
DETECT[ProfileDetector]
PROFILE_CHECK{プロファイル存在?}
subgraph "プロファイルタイプ"
SETTINGS["Settings-based<br/>glm, kimi, default"]
ACCOUNT["Account-based<br/>work, personal, team"]
end
end
subgraph "Claude CLI"
EXEC[claude --settings file_path]
subgraph "CCSコア処理"
CONFIG["config.jsonと<br/>profiles.jsonを読み込み"]
subgraph "プロファイルハンドラー"
SETTINGS_MGR["SettingsManager<br/>→ --settings flag"]
INSTANCE_MGR["InstanceManager<br/>→ CLAUDE_CONFIG_DIR"]
end
end
subgraph "APIレスポンス"
API[Claude Sub または GLM API]
subgraph "Claude CLI実行"
CLAUDE_DETECT["Claude CLI検出<br/>CCS_CLAUDE_PATHサポート"]
subgraph "実行方法"
SETTINGS_EXEC["claude --settings &lt;path&gt;"]
INSTANCE_EXEC["CLAUDE_CONFIG_DIR=&lt;instance&gt; claude"]
end
end
CMD --> CONFIG
CONFIG --> LOOKUP
LOOKUP --> VALIDATE
VALIDATE --> EXEC
EXEC --> API
subgraph "APIレイヤー"
API["API Response<br/>Claude Sonnet 4.5<br/>GLM 4.6<br/>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/<profile>/`)
- **クロスプラットフォーム** - 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)をご覧ください。
---
README.md
+131 -120
View File
@@ -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.<br>
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?
<div align="center">
| 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 |
</div>
**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 <profile>]
flowchart TD
subgraph "User Input"
USER["User runs: ccs &lt;profile&gt; [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<br/>glm, kimi, default"]
ACCOUNT["Account-based<br/>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<br/>and profiles.json"]
subgraph "Profile Handlers"
SETTINGS_MGR["SettingsManager<br/>→ --settings flag"]
INSTANCE_MGR["InstanceManager<br/>→ CLAUDE_CONFIG_DIR"]
end
end
subgraph "Claude CLI Execution"
SETTINGS_EXEC[claude --settings <path>]
INSTANCE_EXEC[CLAUDE_CONFIG_DIR=<instance> claude]
CLAUDE_DETECT["Claude CLI Detection<br/>CCS_CLAUDE_PATH support"]
subgraph "Execution Methods"
SETTINGS_EXEC["claude --settings &lt;path&gt;"]
INSTANCE_EXEC["CLAUDE_CONFIG_DIR=&lt;instance&gt; claude"]
end
end
subgraph "API Response"
API[Claude/GLM/Kimi API]
subgraph "API Layer"
API["API Response<br/>Claude Sonnet 4.5<br/>GLM 4.6<br/>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/<profile>/`)
- **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/<profile>/`)
- **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.
---
README.vi.md
+146 -93
View File
@@ -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.<br>
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?
<div align="center">
| 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 |
</div>
**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 &lt;profile&gt; [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<br/>glm, kimi, default"]
ACCOUNT["Account-based<br/>work, personal, team"]
end
end
subgraph "Claude CLI"
EXEC[claude --settings file_path]
subgraph "Xử Lý Core CCS"
CONFIG["Đọc config.json<br/>và profiles.json"]
subgraph "Profile Handlers"
SETTINGS_MGR["SettingsManager<br/>→ --settings flag"]
INSTANCE_MGR["InstanceManager<br/>→ 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<br/>Hỗ trợ CCS_CLAUDE_PATH"]
subgraph "Phương Thức Thực Thi"
SETTINGS_EXEC["claude --settings &lt;path&gt;"]
INSTANCE_EXEC["CLAUDE_CONFIG_DIR=&lt;instance&gt; claude"]
end
end
CMD --> CONFIG
CONFIG --> LOOKUP
LOOKUP --> VALIDATE
VALIDATE --> EXEC
EXEC --> API
subgraph "API Layer"
API["API Response<br/>Claude Sonnet 4.5<br/>GLM 4.6<br/>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/<profile>/`)
- **Đ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.
---
docs/vi/contributing.vi.md
-182
View File
@@ -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.