VN One Person Company

Hệ điều hành AI cho Công ty 1 Người Việt Nam. Bạn là CEO duy nhất — 12+ phòng ban AI agents họp bàn debate, ra quyết định, sinh báo cáo + tài liệu .docx/.xlsx tuân thủ luật VN. Chạy qua Claude Desktop hoặc Claude Code subscription, không cần Anthropic API key.

Solo founder Việt Nam đang vận hành công ty 1 người (hoặc 2-3 người tinh gọn) muốn:

• 🏢 Có đủ 12+ phòng ban "ảo" (Pháp chế, Tài chính, Marketing, Vận hành, ...) như công ty 100 người
• ⚖️ Quyết định dựa trên debate đa chiều thay vì chỉ 1 góc nhìn của mình
• 📄 Sinh tài liệu tuân thủ luật VN (Luật DN 2020, BLLĐ 2019, NĐ 15/2018 VSATTP, NĐ 13/2023 PDPA, ...)
• 🧠 Mọi quyết định + tài liệu lưu Obsidian + Git — single source of truth, không lạc giữa Notion/Drive/Excel
• 💰 Không trả $20-100/tháng cho 5 SaaS (Notion AI, ChatGPT, Claude API, ...). Plugin chạy qua Claude Desktop hoặc Claude Code subscription duy nhất.

→ Bạn không cần thuê CFO, CMO, COO. Plugin là họ.

┌────────────────────────────────────────────────────────────────┐
│  CEO chat trong Claude Desktop / Code                           │
│              ↓                                                  │
│  vn_run(brief) → Router phân loại → Đọc Brain DN              │
│              ↓                                                  │
│  Phát hiện gap → Hỏi clarification (có cite Brain)            │
│              ↓                                                  │
│  vn_meeting → Live research (luật, đối thủ, benchmark)        │
│              ↓                                                  │
│  Họp 12 phòng ban → Pro/Con debate → 3 góc nhìn perspective  │
│              ↓                                                  │
│  Synthesizer + Translator (CEO-friendly) + Citation validator │
│              ↓                                                  │
│  vn_approve → Execution plan structured                        │
│              ↓                                                  │
│  vn_execute → Render .docx/.xlsx → 03-Outputs/                │
│              ↓                                                  │
│  Auto-commit Git private repo (Obsidian vault)                │
└────────────────────────────────────────────────────────────────┘

• Engine debate: Python 3.11+ + LangGraph (adapt từ TradingAgents, rename neutral)
• Knowledge base: 192 template tiếng Việt + 12 phòng ban core + 3 industry pack
• Storage: Obsidian Markdown + Git private (mỗi DN 1 vault)
• LLM: MCP sampling qua Claude Desktop / Claude Code (subscription) — KHÔNG cần API key Anthropic
• Search: Tavily (free tier 1000 req/tháng) cho luật/đối thủ/web

# Clone repo
git clone https://github.com/<owner>/<repo>.git
cd <repo>

# Tạo venv
python -m venv .venv
.venv\Scripts\activate     # Windows
# source .venv/bin/activate  # macOS/Linux

# Install
pip install -e .

Chọn 1 trong 2 client tuỳ bạn dùng:

A) Claude Desktop (GUI app)

vn-os install-mcp
# Restart Claude Desktop hoàn toàn (Quit từ taskbar → mở lại)
# Click tab "</> Code" ở góc trên bên phải

B) Claude Code (CLI / terminal)

bash adapters/claude-code/install.sh
# Tự động: cài skill `vn-business-os` + register MCP vào ~/.claude.json

Hoặc thủ công:

vn-os install-mcp --target claude-code

💡 Windows dùng Claude Code: chạy install.sh qua Git Bash hoặc WSL. Hoặc dùng lệnh thủ công ở trên. Chi tiết xem adapters/claude-code/README.md.

Trong Claude Desktop / Claude Code chat:

Setup vault cho công ty XYZ tại đường dẫn F:/work/xyz-vault.
Cài pack F&B. TAVILY_API_KEY của tôi: tvly-xxx (lấy free tại tavily.com).

Claude tự động gọi MCP tool vn_onboard để tạo vault scaffold + cài pack + lưu key vào <vault>/.env (gitignored).

# Claude Desktop
vn-os install-mcp --vault "F:/work/xyz-vault"
# Restart Claude Desktop lần nữa

# Claude Code
vn-os install-mcp --vault "F:/work/xyz-vault" --target claude-code
# Restart Claude Code session

CEO mở <vault>/00-Brain/ trong Obsidian, điền:

• strategy.md — tầm nhìn, sứ mệnh, ICP, mục tiêu năm
• products.md — bảng sản phẩm/dịch vụ + giá + margin
• budget.md — ngân sách năm + phân bổ phòng ban
• headcount.md — phòng nào active, gap chuyên môn
• state.md — giai đoạn DN (seed/growth/...), runway

Trong Claude Desktop / Claude Code chat:

Tôi muốn làm chiến dịch quảng cáo Tết cho sản phẩm A.
Tham khảo budget hiện tại + tham vấn pháp lý.

Plugin sẽ:

1. Phân loại task → COMPLEX (3-5 phòng debate)
2. Đọc Brain → phát hiện gap (cần ngân sách marketing cụ thể?)
3. Hỏi CEO 3-5 câu clarification
4. Research luật quảng cáo VN + đối thủ
5. Họp pro/con + 3 perspective (Growth/Cautious/Balanced)
6. Sinh 07-decision-report.md (CEO duyệt)
7. Sinh 08-execution-plan.md + render .docx/.xlsx

Edit <vault>/.vncoderc:

vault_path: F:/work/xyz-vault
packs: [fnb]
version: "0.1.0"

# Translator scope (P1.6)
# off | final_only (default) | all_intermediate
translator_mode: final_only

meeting:
  max_debate_rounds: 2
  max_perspective_rounds: 1
  use_checkpointer: false  # P1.4 opt-in crash recovery

llm:
  primary: claude-sonnet-4-6

python -m pytest tests/ -q
# 261 passed, 1 skipped

• docs/getting-started.md — cài đặt + onboard chi tiết
• docs/install-claude-code.md — cài Claude Code bước-bước + kịch bản tương tác (cho học viên)
• docs/user-guide.md — flow 5 stage + ví dụ
• docs/configuration.md — .vncoderc, packs, BYOT
• docs/troubleshooting.md — lỗi thường gặp
• docs/architecture.md — kiến trúc + RULES + extensibility
• CONTRIBUTING.md — đóng góp code

PR welcome. Đặc biệt cần:

• Pack mới: Real Estate, Healthcare, Education, Beauty
• Translation: thêm thuật ngữ VN→EN trong glossary
• Test coverage: real-LLM E2E

Xem CONTRIBUTING.md.

Apache License 2.0 — © 2026 VN Business OS Contributors

Xem LICENSE cho full text và NOTICE cho attribution chi tiết.

Apache 2.0 cho phép sử dụng commercial + modify + redistribute, đồng thời bảo vệ tên/logo "VN Business OS" khỏi bị fork dùng quảng cáo sản phẩm khác (Section 6) và đảm bảo người fork phải ghi rõ các thay đổi đã làm.

Credits (đã chi tiết trong NOTICE):

• 192 template tiếng Việt trong templates-vn/ adapted from business-builder.plugin
• Engine debate pattern adapted from TradingAgents (Apache 2.0)
• Role definitions reference from agency-agents