Skip to content

README.vi.md

Latest commit

 

History

History
167 lines (112 loc) · 8.06 KB

README.vi.md

File metadata and controls

167 lines (112 loc) · 8.06 KB
Raw

English

HOANGSA

Hệ thống context engineering cho Claude Code

License: MIT Claude Code Built with Rust

HOANGSA là hệ thống context engineering cho Claude Code giải quyết một vấn đề căn bản: chất lượng output của Claude giảm dần khi context window bị lấp đầy. Giải pháp mang tính cấu trúc — HOANGSA chia công việc thành các task riêng biệt, mỗi task chạy trong context window mới với chỉ những file thực sự cần thiết. Orchestrator không viết code; nó dispatch các worker có context giới hạn và tổng hợp kết quả.

Cài đặt

Hai bước: 1) cài binaries (chung cho mọi harness), 2) nối harness bạn dùng.

Bước 1 — binaries

curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh

Installer tải sẵn binary native vào ~/.hoangsa/bin/ — không cần Node, không cần npm, không cần cargo. Nền tảng: darwin-arm64 (Apple Silicon), linux-x64, linux-arm64.

Flags: --global (mặc định), --local, --dry-run, --no-embed (bỏ pre-download weights fastembed; sẽ tải lazy khi dùng lần đầu).

Bước 2 — nối harness

Claude Code — installer ở bước 1 đã nối sẵn (MCP + hooks + templates). Chạy lại tay khi cần:

hoangsa-cli install --global   # hoặc --local cho một project
hsp init                       # tuỳ chọn: hook nén output

Codex CLI / Codex Desktop — desktop app dùng chung config với CLI:

hoangsa-cli install --global --harness codex

Ghi hooks vào ~/.codex/hooks.json (kèm hsp nếu có), MCP vào ~/.codex/config.toml, skills + lệnh /hoangsa:* vào ~/.agents/skills/hoangsa/, workflows vào ~/.codex/hoangsa/. Archive + thống kê token tự đọc ~/.codex/sessions/. Sau đó mở Codex, chạy /hooks một lần để approve — Codex không chạy hook chưa được trust.

Claude Cowork / Claude Desktop:

hoangsa-cli install --harness cowork

Đăng ký memory MCP vào claude_desktop_config.json (bridge vào VM của Cowork) — xong restart Claude Desktop. Muốn có lệnh /hoangsa:* + skills thì cài plugin: /plugin marketplace add unknown-studio-dev/hoangsa. Lưu ý: hooks/gates không chạy được trong VM của Cowork.

Chỉ cài plugin (không cần binaries) — /plugin marketplace add unknown-studio-dev/hoangsa cho ngay bộ lệnh workflow, agents, skills trên Claude Code/Cowork; nhưng memory, gates và hsp vẫn cần bước 1.

Gỡ cài đặt

Chạy scripts/uninstall.sh --global (hoặc --local) từ bản checkout của repo. Thêm --purge để xoá luôn ~/.hoangsa (templates + memory data).

Bắt đầu nhanh

Yêu cầu: Claude Code CLI.

curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh
/hoangsa:init        # Khởi tạo project — phát hiện codebase, cài đặt preferences
/hoangsa:menu        # Thiết kế task đầu tiên → DESIGN-SPEC + TEST-SPEC

Sau /hoangsa:menu, chạy /hoangsa:prepare để lập kế hoạch, rồi /hoangsa:cook để thực thi.

Lệnh

Quy trình cốt lõi

Lệnh Mô tả
/hoangsa:brainstorm Khám phá ý tưởng mơ hồ → BRAINSTORM.md (đưa vào menu)
/hoangsa:menu Thiết kế — phỏng vấn → DESIGN-SPEC + TEST-SPEC
/hoangsa:prepare Lập kế hoạch — specs → DAG task thực thi (plan.json)
/hoangsa:cook Thực thi — từng wave, context mới cho mỗi worker task
/hoangsa:taste Kiểm tra — chạy acceptance tests từng task
/hoangsa:plate Commit — stage + tạo conventional commit message
/hoangsa:ship Ship — review code + bảo mật, rồi push hoặc tạo PR
/hoangsa:serve Đồng bộ — sync hai chiều với task manager được kết nối
/hoangsa:fix Hotfix — truy vết root cause xuyên tầng + fix gọn
/hoangsa:audit Audit — quét codebase 8 chiều (bảo mật, debt, coverage…)
/hoangsa:research Research — phân tích codebase + nghiên cứu → RESEARCH.md

Tiện ích

Lệnh Mô tả
/hoangsa:rule Rules — thêm, gỡ, hoặc liệt kê các rule enforce cho project
/hoangsa:addon Addons — liệt kê, thêm, hoặc gỡ addon worker rules theo framework
/hoangsa:init Khởi tạo — phát hiện codebase, cấu hình preferences, thiết lập lần đầu
/hoangsa:check Trạng thái — hiển thị tiến độ session và các task đang chờ
/hoangsa:index Index — xây dựng lại đồ thị code intelligence hoangsa-memory
/hoangsa:update Cập nhật — nâng cấp HOANGSA lên phiên bản mới nhất
/hoangsa:help Trợ giúp — hiển thị tất cả lệnh có sẵn

Memory & Code Intelligence

HOANGSA đi kèm hoangsa-memory — MCP server chạy local, cung cấp cho Claude bộ nhớ lâu dài (facts, lessons, preferences) và hiểu biết về code graph (impact analysis, symbol context, change detection) qua nhiều session.

  • Tự động cài bởi installer: binary đặt tại ~/.hoangsa/bin/, MCP server được đăng ký trong .mcp.json của project.
  • State theo từng project nằm trong ~/.hoangsa/memory/projects/<slug>/ (MEMORY.md, LESSONS.md, USER.md + index).
  • Hooks cài vào settings Claude Code: pre-edit rule enforcement, pre-edit lesson recall, post-tool event logging, và PreCompact / SessionEnd archive ingest để recall nội dung hội thoại.
  • Archive search (lịch sử hội thoại đầy đủ) dùng fastembed vector store in-process — không cần sidecar. Installer pre-download multilingual-e5-small weights (~4xx MB) vào ~/.hoangsa/cache/fastembed/; dùng --no-embed để bỏ qua và tải lazy khi dùng lần đầu.

Reindex thủ công: /hoangsa:index hoặc ~/.hoangsa/bin/hoangsa-memory --json index .

Cấu hình

Config nằm trong .hoangsa/config.json. Quản lý bằng /hoangsa:init hoặc hoangsa-cli pref set.

Preferences

Khóa Giá trị Mô tả
lang en, vi Ngôn ngữ cho output
spec_lang en, vi Ngôn ngữ cho specs được tạo ra
tech_stack array Tech stack của project
review_style strict, balanced, light, whole_document Mức độ kỹ lưỡng review code
interaction_level minimal, quick, standard, detailed Mức độ orchestrator hỏi
auto_taste true, false Tự động chạy tests sau cook
auto_plate true, false Tự động commit sau cook
auto_serve true, false Tự động sync lên task manager

Model Profiles

Chọn profile (quality / balanced / budget) để kiểm soát model ở mỗi trong 8 vai trò. Chuyển đổi bằng /hoangsa:init hoặc sửa profile trong config.json.

Vai trò quality balanced budget
researcher opus sonnet haiku
designer opus opus sonnet
planner opus sonnet haiku
orchestrator opus opus haiku
worker opus sonnet haiku
reviewer opus sonnet haiku
tester sonnet haiku haiku
committer sonnet haiku haiku

Alias fable (Claude Fable 5 — tier trên opus, giá ~2× opus) không thuộc profile nào. Route theo từng role qua model_overrides trong config.json, ví dụ { "model_overrides": { "designer": "fable" } }.

Giấy phép

MIT — Copyright (c) 2026 Zan

Tác giả: Zan — @pirumu

English