Wu Shenglin

# Nhiệm vụ: Tạo Thanh trạng thái Chuyên nghiệp dành cho Nhà phát triển trên Claude Code

## Vai trò

Bạn là một lập trình viên hệ thống đang xây dựng một kịch bản (script) thanh trạng thái được tối ưu hóa cao cho Claude Code.

## Sản phẩm Bàn giao (Deliverable)

Một script Python gói gọn trong một tệp duy nhất (`~/.claude/statusline.py`) hiển thị các thông tin quan trọng đối với nhà phát triển trên dòng trạng thái của Claude Code.

## Đặc tả Đầu vào

Đọc dữ liệu JSON từ luồng đầu vào chuẩn (stdin) với cấu trúc sau:

```json
{
  "model": {"display_name": "Opus|Sonnet|Haiku"},
  "workspace": {"current_dir": "/path/to/workspace", "project_dir": "/path/to/project"},
  "output_style": {"name": "explanatory|default|concise"},
  "cost": {
    "total_cost_usd": 0.0,
    "total_duration_ms": 0,
    "total_api_duration_ms": 0,
    "total_lines_added": 0,
    "total_lines_removed": 0
  }
}

```

## Yêu cầu Đầu ra

### Định dạng

* In ra luồng đầu ra chuẩn (stdout) ĐÚNG MỘT dòng duy nhất
* Sử dụng mã màu ANSI 256-color: \033[38;5;Nm với bảng màu được tối ưu hóa để đạt độ tương phản cao
* Cắt ngắn thông minh: Độ rộng văn bản hiển thị ≤ 80 ký tự (các mã thoát ANSI KHÔNG được tính vào giới hạn này)
* Sử dụng các ký hiệu unicode: ● (sạch - clean), + (đã thêm - added), ~ (đã sửa đổi - modified)
* Bảng màu: cam 208, xanh dương 33, xanh lá 154, vàng 229, đỏ 196, xám 245 (đã được kiểm nghiệm hiển thị tốt trên cả nền terminal tối và sáng)

### Kiến trúc Thông tin (Thứ tự Ưu tiên từ Trái sang Phải)

1. Cốt lõi (Core): Tên mô hình (màu cam)
2. Ngữ cảnh (Context): Tên cơ sở (basename) của thư mục dự án (màu xanh dương)
3. Trạng thái Git (Git Status):
* Tên nhánh (màu xanh lá)
* Sạch (Clean): ● (màu xám mờ)
* Đã sửa đổi (Modified): ~N (màu vàng, N = số lượng tệp)
* Đã thêm (Added): +N (màu vàng, N = số lượng tệp)


4. Siêu dữ liệu (Metadata - màu xám mờ):
* Các tệp chưa commit: !N (màu đỏ, N = số lượng đếm được từ lệnh git status --porcelain)
* Tỷ lệ thời gian API: A:N% (N = api_duration / total_duration * 100)



### Ví dụ Đầu ra

\033[38;5;208mOpus\033[0m \033[38;5;33mIsaacLab\033[0m \033[38;5;154mmain\033[0m \033[38;5;245m●\033[0m \033[38;5;245mA:12%\033[0m

## Ràng buộc Kỹ thuật

### Hiệu năng (QUAN TRỌNG)

* Thời gian thực thi: < 100ms (được gọi mỗi 300ms một lần)
* Lưu trữ bộ nhớ đệm (Cache persistence): Lưu bộ nhớ đệm trạng thái Git trong tệp /tmp/claude_statusline_cache.json (script sẽ thoát ngay sau mỗi lần chạy, do đó bộ nhớ đệm phải được lưu bền vững trên ổ đĩa)
* Thời gian sống của bộ nhớ đệm (Cache TTL): Chỉ làm mới số lượng tệp Git khi tuổi của bộ nhớ đệm > 5 giây HOẶC thời gian sửa đổi (mtime) của tệp .git/index thay đổi
* Tối ưu hóa logic Git:
* Tên nhánh: Đọc trực tiếp tệp .git/HEAD (không tạo tiến trình con subprocess)
* Số lượng tệp: CHỈ gọi subprocess.run(['git', 'status', '--porcelain']) khi bộ nhớ đệm hết hạn


* Chỉ sử dụng thư viện chuẩn: Không dùng các gói phụ thuộc bên ngoài (chỉ sử dụng sys, json, os, pathlib, subprocess, time)

### Xử lý Lỗi

* Lỗi phân tích cú pháp JSON → trả về chuỗi rỗng ""
* Thiếu trường dữ liệu → bỏ qua phần thông tin đó (không được làm sập chương trình)
* Không tìm thấy thư mục Git → bỏ qua hoàn toàn phần thông tin Git
* Bất kỳ ngoại lệ (exception) nào xảy ra → trả về chuỗi rỗng ""

## Cấu trúc Mã nguồn

* Một tệp duy nhất, < 100 dòng mã
* Xử lý bảng mã UTF-8 chuẩn xác để xuất các ký tự unicode ổn định
* Tối đa một hàm cho mỗi mối quan tâm (phân tích cú pháp, git, định dạng chuỗi)
* Bắt buộc có gợi ý kiểu dữ liệu (type hints) cho tất cả các hàm
* Có chuỗi tài liệu (docstring) cho từng hàm để giải thích mục đích của hàm đó

## Các Bước Tích hợp

1. Lưu script vào đường dẫn ~/.claude/statusline.py
2. Chạy lệnh chmod +x ~/.claude/statusline.py
3. Thêm cấu hình vào tệp ~/.claude/settings.json:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.py",
    "padding": 0
  }
}

```

4. Kiểm thử thủ công: echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/tmp"}}' | ~/.claude/statusline.py

## Danh sách Kiểm tra Xác minh

* Script thực thi mà không cần thư viện phụ thuộc bên ngoài (ngoại trừ lệnh gọi git status --porcelain duy nhất khi làm mới bộ nhớ đệm)
* Độ rộng văn bản hiển thị ≤ 80 ký tự (đã loại trừ các mã màu ANSI khỏi phép tính độ dài)
* Màu sắc hiển thị chính xác trên cả nền terminal tối và sáng
* Thời gian thực thi < 100ms trong không gian làm việc thông thường (các lần gọi dùng bộ nhớ đệm phải đạt < 20ms)
* Xử lý êm đẹp trường hợp thư mục không phải là kho lưu trữ Git
* Tệp bộ nhớ đệm được tạo trong /tmp và tuân thủ đúng thời gian sống TTL
* Số lượng tệp Git được làm mới ngay khi thời gian sửa đổi (mtime) của .git/index thay đổi hoặc sau khi 5 giây trôi qua

## Ngữ cảnh cho các Quyết định Thiết kế

Đây là thanh trạng thái theo phong cách "nhà phát triển chuyên nghiệp". Nó ưu tiên:

* Thông tin Git chi tiết giúp nhận biết nhanh trạng thái khi chuyển nhánh
* Giám sát hiệu quả gọi API để phát triển phần mềm có kiểm soát chi phí
* Mật độ thị giác cao nhằm truyền tải lượng thông tin tối đa trên mỗi ký tự