agent-marketing-team
Tên cũ: agent-marketing-studio (đổi tên thành agent-marketing-team; liên kết cũ vẫn chuyển hướng).
Engine điều hành và tự động hóa chiến dịch marketing đa kênh toàn diện bằng Multi-Agent AI kết hợp với con người kiểm soát (Human-in-the-Loop).
Cài đặt — nhờ AI cài giúp
Mở Claude Code, Codex hoặc Google Antigravity rồi dán nguyên văn yêu cầu dưới đây. Agent đọc
hướng dẫn cài dành cho agent, kiểm tra máy, hỏi bạn trước khi cài thêm phần mềm
và trước khi chọn chỗ đặt nội dung, rồi cài, kiểm tra và báo lại từng bước.
Hãy cài agent-marketing-team lên máy này cho chính ứng dụng AI bạn đang chạy.
Nguồn duy nhất: https://github.com/ducnguyen221/agent-marketing-team
Đọc trước hướng dẫn cho agent tại
https://raw.githubusercontent.com/ducnguyen221/agent-marketing-team/main/INSTALL.md
(không mở được thì clone repo rồi đọc INSTALL.md trong đó) và làm đúng, đủ các bước:
kiểm tra máy, hỏi tôi trước khi cài thêm phần mềm, clone về thư mục an toàn (không OneDrive),
hỏi tôi chọn chỗ đặt trạm nội dung, chạy bộ cài, chạy doctor, kiểm bằng trạm mẫu.
Quy tắc: chỉ chạy lệnh có trong repo hoặc INSTALL.md; không đổi chính sách hệ thống;
không đọc hay ghi mật khẩu/khóa; không đăng bài; gặp lỗi thì dừng và giải thích bằng lời thường.
Kết thúc bằng bản tóm tắt: đường dẫn repo, trạm, từng dòng doctor, việc tôi cần làm tiếp.
Tự cài bằng tay: làm theo mục 2–9 của INSTALL.md. Từng ứng dụng AI:
hosts/README.md. Cập nhật: python scripts/pipeline/studio.py update
(dừng nếu bạn có sửa đổi chưa commit, không bao giờ xoá gì). Gỡ: uninstall.ps1 / uninstall.sh
(chỉ gỡ phần bộ cài tạo; giữ nội dung trạm và .env). Thay đổi theo phiên bản:
CHANGELOG.md.
1. Điểm Khác Biệt & Kiến Trúc Cốt Lõi
- Markdown làm chủ trạng thái: mỗi chiến dịch là một file
campaign.md — brief ở
đầu (frontmatter + Mục 1–10), bảng danh sách bài ở giữa (giữa marker
<!-- CONTENT:BEGIN/END -->). Mỗi bài là một thư mục con. Không có định dạng nhị phân
nào ở giữa bạn và dữ liệu: mở lên là đọc được, git chỉ ra đúng chữ đã đổi, và không ai
khoá file của ai.
- Excel là BẢN XUẤT, một chiều:
export_excel.py dựng .xlsx đúng bộ cột cũ để lọc,
xoay, gửi cho người không dùng git. Sửa trong Excel không quay ngược về nguồn.
- 3 cổng duyệt kiểm soát bởi con người: AI tự động lập kế hoạch và sản xuất, nhưng con
người giữ quyền quyết định ở các chốt chặn: duyệt đề tài (Cổng 1), duyệt nội dung trước
khi đăng (Cổng 2), và duyệt bản thật trên web trước khi phát ra kênh ngoài (Cổng 3 — bật
khi bảng Content có cột
g3).
- Engine ở repo, nội dung ở TRẠM: repo này chứa engine (script, cổng kiểm, quy trình,
template). Nội dung thật sống ở một trạm nằm ngoài git — mặc định
workspaces/ trong
chính thư mục repo (git bỏ qua), hoặc một thư mục riêng do bạn chỉ định. Kênh thậm chí không bắt buộc nằm trong trạm: CHANNELS.md
là cạnh duy nhất được phép trỏ ra ngoài.
- Lõi là VIẾT BÀI và ĐĂNG — cài xong là dùng được ngay. Bản cài này
không bắt buộc trạm giọng/video: lồng tiếng (
agent-voice-studio) và dựng video
(agent-video-studio) là hai năng lực thêm, bật khi nào bạn cần. Thiếu chúng,
doctor chỉ ghi một dòng "chưa bật — cần khi bạn muốn …" và vẫn trả mã 0; lời
hướng dẫn cài chỉ hiện ra đúng lúc một bước thật sự chạm tới giọng hoặc video, và khi
đó nó dừng ở mã 3 kèm đủ các lệnh phải chạy.
- Chiến dịch chạy theo lịch, cùng một khuôn: bản tin ngày/tuần và series tự động là
chiến dịch như mọi chiến dịch khác — chỉ thêm
run.ps1 (điểm vào duy nhất, giống hệt nhau
ở mọi chiến dịch) và khối runtime: trong campaign.md. campaign_cfg.py gộp bốn tầng
cấu hình — channel.yml:brand → brand.json (nếu còn) → brand.md → campaign.md — thành
một bản chụp JSON cho PowerShell 5.1 đọc, fail-closed: thiếu khoá bắt buộc thì dừng chứ
không trả về JSON dở dang. Chi tiết: .
2. Quy Trình 7 Khâu & 3 Cổng Duyệt
① new ─→ ② plan ─🔒 CỔNG 1 ─→ ③ produce ─→ ④ selfqa ─🔒 CỔNG 2 ─→ ⑤ render ─→ ⑥ publish ─→ ⑦ measure
web ─🔒 CỔNG 3 ─→ YouTube · Facebook
- ① new (Khởi tạo): Lập hồ sơ chiến dịch từ brief của con người (
workflows/01_new_campaign.md).
- ② plan (Lập kế hoạch): Đề xuất N ý tưởng content và từ khóa SEO (
workflows/02_plan_content.md).
- 🔒 CỔNG 1 — duyệt đề tài: người đặt
status = approved + ngày vào ô g1 của bảng
Content. Không có đường nào trong mã tự đặt giá trị này.
- ③ produce (Sản xuất): đọc chiến dịch + hồ sơ kênh + nghiên cứu của bài, rồi viết mọi
kênh vào
content.md (workflows/03_produce_content.md).
- ④ selfqa (Tự kiểm tra): Máy tự kiểm định chất lượng, văn phong, quy chuẩn kênh (
workflows/04_self_qa.md).
- 🔒 CỔNG 2 — duyệt trước khi đăng:
register_publish approve --by "<tên>" --note "<câu duyệt nguyên văn>". Bắt buộc cả hai — duyệt mà không để lại dấu vết thì
sáu tháng sau không ai biết ai đã đồng ý với cái gì.
- ⑤ render (Dựng Asset): Tạo hình ảnh, audio lồng tiếng, short video (
workflows/05_render_assets.md).
- ⑥ publish (Đăng bài): YouTube → trang blog → Facebook, và URL thật ghi ngược vào
bảng Content (
workflows/06_publish.md).
- 🔒 CỔNG 3 — duyệt bản thật (tuỳ chọn): khi bảng Content có cột
g3, trang web lên
trước, người mở link xem bằng mắt rồi mới phát YouTube/Facebook
().
3. Cấu Trúc Repository Chuẩn Hóa
3.1 Trạm nội dung — ba tầng lồng nhau
Kênh chứa chiến dịch, chiến dịch chứa bài. Mỗi tầng có đúng một file giữ sự thật của
tầng đó, và cả ba tầng đều là thư mục thật — mở ra là đọc được, không có cơ sở dữ liệu ở giữa.
<thư-mục-trạm>/ # TRẠM (ngoài git — chỗ nào là do bạn chọn)
├── CHANNELS.md # sổ kênh: kênh nào ở đâu (cạnh DUY NHẤT trỏ ra ngoài)
├── AUTHOR.md # tác giả là ai — dùng chung mọi kênh
└── <kênh>/ # ① MỘT KÊNH = một giọng, một tập người đọc
├── channel.yml # MÁY đọc: nền tảng · trụ nội dung · theme · brand · paths
├── brand.md # NGƯỜI đọc: nhận diện · giọng · chính kiến · cái KHÔNG làm
├── CAMPAIGNS.md # sổ chiến dịch của kênh
├── continuity.json # sổ bài đã đăng — để khỏi trùng đề tài
└── <chiến-dịch>/ # ② MỘT CHIẾN DỊCH
├── campaign.md # brief + bảng Content + khối `runtime:`
├── prompt.txt # prompt bước CHỌN đề tài (chạy mỗi kỳ)
├── run.ps1 # [chạy theo lịch] điểm vào duy nhất
├── out/ logs/ # sản phẩm & nhật ký RIÊNG của chiến dịch này
└── <mã>_<slug>/ # ③ MỘT BÀI = một ý tưởng, nhiều bản đăng
├── prompt.txt # prompt bước VIẾT bài này
├── research.md # nguồn & ràng buộc — đóng băng ở đây
├── content.md # nội dung MỌI kênh, tách bằng `## post:<format>`
└── publish.json # cổng 2 · URL thật · số đo
Ba lệnh dựng ba tầng, mỗi lệnh chép từ templates/station/:
python scripts/pipeline/new_channel.py --id <kênh> --label "…" --path ./<kênh>
python scripts/pipeline/new_campaign.py --channel <kênh> --id <slug> --name "…" --prefix XXX
python scripts/pipeline/new_post.py --campaign <slug> --id XXX-001 --slug … --title "…"
python scripts/pipeline/check_tree.py --station "$env:MARKETING_STUDIO_DATA" # soi lại cây thật
Ba loại file, ba vai — đừng trộn: .yml cho máy, .md cho người, .txt cho
model. Một file vừa là cấu hình vừa là tài liệu thì sửa câu chữ cũng phải sợ làm hỏng máy.
3.2 Repo — engine và khuôn
agent-marketing-team/
├── AGENTS.md # Quy chuẩn quản trị đa tác nhân (Governance)
├── MAP.md # Bản đồ định tuyến context nhiệm vụ (Context Router)
├── README.md # Hướng dẫn tổng quan hệ thống
├── INSTALL.md # Hướng dẫn cài dành cho AI agent + prompt copy-dán
├── CHANGELOG.md # Thay đổi theo phiên bản
├── pyproject.toml # Nguồn phiên bản DUY NHẤT (manifest phải khớp)
├── CONTRIBUTING.md # Quy ước phát triển và đóng góp
├── SECURITY.md # Chính sách bảo mật token và dữ liệu
├── install.ps1 · install.sh # Dựng trạm: hỏi 1 câu rồi in ra ba lệnh tiếp theo
├── uninstall.ps1 · uninstall.sh # Gỡ phần bộ cài tạo; GIỮ trạm và .env
├── .agents/ # Tầng quản trị Agent (Roles, Skills gốc, Checklists, Prompts)
├── .claude/skills/ # Adapter skill cho Claude Code — sinh bằng scripts/build_host_adapters.py
├── .claude-plugin/ · .codex-plugin/ # Manifest plugin, trỏ .agents/skills/
├── hosts/ # Hướng dẫn từng ứng dụng AI (Claude Code, Codex, Antigravity)
├── .github/workflows/ # CI: pytest trên windows-latest + macos-latest
├── scripts/
│ ├── lib/ # md_io (đọc/ghi Markdown nguyên tử) · studio_paths · post_paths
│ ├── pipeline/ # new_channel · new_campaign · new_post · gen_article
│ # campaign_cfg (gộp cấu hình → JSON cho PowerShell)
│ # blog_gates · register_publish · check_tree · build_views · export_excel
│ └── runners/ # vỏ PowerShell cho lịch · notify_run.py (báo Telegram, dùng với launchd)
│ # install_launchd.py (điền mẫu plist rồi nạp bằng launchctl)
├── docs/ # ONBOARDING · RUNBOOK-DOI-MAY · WORKSPACE (+ trang giới thiệu)
├── tests/ # bộ test + cổng chống trôi — chạy `python -m pytest -q`
├── knowledge/ # Kho tri thức marketing (Data Model, Playbooks, Toolchains)
├── output_styles/ # Giọng văn thương hiệu chuẩn theo từng kênh
├── templates/
│ ├── README.md # khuôn nào dùng khi nào
│ ├── station/ # CÂY MẪU lồng đúng như trạm thật:
│ │ # _channel/ → _campaign/ → _content/
│ └── launchd/ # 8 plist mẫu trung tính cho lịch chạy trên macOS
├── workflows/ # Đặc tả chi tiết 7 khâu vận hành
├── examples/ # TRẠM MẪU đã điền — 1 kênh, 1 chiến dịch, 3 bài ở 3 trạng thái
└── content/ # Bộ dữ liệu mô phỏng dùng cho dạy học (bộ mẫu tổng hợp `sample-course`)
4. Tài Liệu Quan Trọng
5. Kiểm Thử & CI
python -m pip install -r requirements.txt
python -m pytest -q
- Bộ test chạy trên Windows (PowerShell 5.1) và macOS (
pwsh 7). CI
(.github/workflows/tests.yml) chạy pytest trên windows-latest và macos-latest,
không secret, không deploy.
- Vài file test gọi PowerShell thật (
run.ps1, runner). Máy không có powershell/pwsh thì
chúng tự bỏ qua. CI đặt MARKETING_STUDIO_REQUIRE_POWERSHELL=1 để biến chuyện bỏ qua đó
thành lỗi — trên CI, "bỏ qua" trông y hệt "xanh". Muốn kiểm như CI ở máy mình thì đặt
biến này trước khi chạy pytest.
- Cổng chống trôi tài liệu (
tests/test_docs_drift.py) đỏ khi tài liệu gọi lệnh CLI không có,
khi code đọc biến môi trường chưa khai, hoặc khi luật cũ quay lại.
Tác giả
Nguyễn Quang Đức (Tobi) — nhà sáng lập, CEO KPIM và đồng sáng lập COMPA Class; chuyên gia Data/AI và giảng viên công nghệ tại Việt Nam.
Website: https://ducnguyen.vn · GitHub: @ducnguyen221 · Liên hệ: [email protected]
🤝 ACD Ecosystem Integration
Khai báo vai của repo trong hệ thống nhiều repo ACD (Role, Upstream, Downstream, Bundles, Handoff) tại ECOSYSTEM.md.
