kanban-tutorial

#Hướng dẫn sử dụng Kanban

Hướng dẫn về bốn trường hợp sử dụng mà hệ thống Hermes Kanban được thiết kế cho, với bảng điều khiển mở trong trình duyệt. Nếu bạn chưa đọc Tổng quan về Kanban, hãy bắt đầu từ đó — điều này giả định rằng bạn biết nhiệm vụ, hoạt động, người được giao và người điều phối là gì.

Cài đặt

hermes kanban init           # optional; first `hermes kanban <anything>` auto-inits
hermes dashboard             # opens http://127.0.0.1:9119 in your browser
# click Kanban in the left nav

Bảng điều khiển là nơi thoải mái nhất để bạn xem hệ thống. Nhân viên đại lý mà người điều phối sinh ra không bao giờ nhìn thấy bảng thông tin hoặc CLI — họ điều khiển bảng thông qua một kanban_* bộ công cụ (kanban_show, kanban_list, kanban_complete, kanban_block, kanban_heartbeat, kanban_comment, kanban_create, kanban_link, kanban_unblock). Tất cả ba bề mặt — bảng điều khiển, CLI, công cụ nhân viên — định tuyến thông qua cùng một SQLite DB trên mỗi bảng (~/.hermes/kanban.db cho bảng mặc định, ~/.hermes/kanban/boards/<slug>/kanban.db cho bất kỳ bảng nào bạn tạo sau này), do đó, mỗi bảng đều nhất quán cho dù thay đổi đến từ phía nào của hàng rào.

Hướng dẫn này sử dụng bảng mặc định xuyên suốt. Nếu bạn muốn có nhiều hàng đợi riêng biệt (mỗi hàng đợi cho mỗi dự án / repo / miền), hãy xem Bảng (đa dự án) trong phần tổng quan — áp dụng cùng một luồng CLI / bảng điều khiển / công nhân cho mỗi bảng và nhân viên thực tế không thể nhìn thấy nhiệm vụ trên các bảng khác.

Trong suốt hướng dẫn, các khối mã có nhãn bash là các lệnh bạn chạy. Các khối mã có nhãn # lệnh gọi công cụ của công nhân là những gì mà mô hình của công nhân được sinh ra phát ra dưới dạng lệnh gọi công cụ — được hiển thị ở đây để bạn có thể thấy vòng lặp từ đầu đến cuối chứ không phải vì bạn đã từng tự mình chạy chúng.

Sơ lược về bảng

Sáu cột, từ trái sang phải:

• Xử lý — những ý tưởng thô, người xác định sẽ xác định thông số kỹ thuật trước khi bất kỳ ai thực hiện chúng. Nhấp vào nút ✨ Chỉ định trên bất kỳ thẻ phân loại nào (hoặc chạy hermes kanban chỉ định <id> / /kanban chỉ định <id> từ một cuộc trò chuyện) để LLM phụ trợ biến một dòng thành thông số kỹ thuật đầy đủ (mục tiêu, cách tiếp cận, tiêu chí chấp nhận) và quảng bá nó thành việc cần làm chỉ trong một lần. Định cấu hình mô hình nào chạy mô hình đó trong auxiliary.triage_specifier trong config.yaml.
• Todo — đã tạo nhưng đang chờ phụ thuộc hoặc chưa được chỉ định.
• Sẵn sàng — đã được chỉ định và chờ người điều phối yêu cầu.
• Đang tiến hành — một nhân viên đang tích cực thực hiện nhiệm vụ. Khi bật "Làn đường theo hồ sơ" (mặc định), cột này sẽ nhóm con theo người được giao để bạn có thể xem nhanh từng công nhân đang làm gì.
• Bị chặn — một công nhân đã yêu cầu sự can thiệp của con người hoặc cầu dao bị ngắt.
• Xong — đã hoàn thành.

Thanh trên cùng có các bộ lọc để tìm kiếm, đối tượng thuê và người được chuyển nhượng, cùng với nút chuyển đổi Làn đường theo hồ sơ và nút Điều phối viên di chuyển chạy một dấu kiểm điều phối ngay bây giờ thay vì chờ khoảng thời gian tiếp theo của daemon. Nhấp vào bất kỳ thẻ nào sẽ mở ngăn kéo của nó ở bên phải.

###Chế độ xem phẳng

Nếu các làn đường trong hồ sơ ồn ào, hãy tắt "Làn đường theo hồ sơ" và cột Đang tiến hành sẽ thu gọn thành một danh sách phẳng duy nhất được sắp xếp theo thời gian xác nhận:

Câu chuyện 1 — Nhà phát triển solo vận chuyển một tính năng

Bạn đang xây dựng một tính năng. Quy trình cổ điển: thiết kế lược đồ, triển khai API, viết bài kiểm thử. Ba nhiệm vụ với sự phụ thuộc của cha mẹ→con cái.

SCHEMA=$(hermes kanban create "Design auth schema" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --body "Design the user/session/token schema for the auth module." \
    --json | jq -r .id)

API=$(hermes kanban create "Implement auth API endpoints" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --parent $SCHEMA \
    --body "POST /register, POST /login, POST /refresh, POST /logout." \
    --json | jq -r .id)

hermes kanban tạo "Viết bài kiểm tra tích hợp xác thực" \
    --signee qa-dev --tenant auth-project --priority 2 \
    --parent $API \
    --body "Che đường dẫn hạnh phúc, sai mật khẩu, mã thông báo đã hết hạn, làm mới đồng thời."

Bởi vì API có SCHEMA là cha mẹ và tests có API là cha mẹ nên chỉ SCHema bắt đầu bằng sẵn sàng. Hai đứa còn lại ngồi làm việc 'todo` cho đến khi bố mẹ chúng hoàn thành. Đây là công cụ thúc đẩy sự phụ thuộc đang thực hiện công việc của mình - sẽ không có nhân viên nào khác tiếp tục viết bài kiểm tra cho đến khi có API để kiểm tra.

Ở dấu tích của bộ điều phối tiếp theo (theo mặc định là 60 giây hoặc ngay lập tức nếu bạn nhấn Bộ điều phối Nudge), hồ sơ backend-dev sẽ xuất hiện dưới dạng một nhân viên có HERMES_KANBAN_TASK=$SCHEMA trong env của nó. Đây là vòng lặp gọi công cụ của nhân viên trông như thế nào từ bên trong tác nhân:

# worker tool calls — NOT commands you run
kanban_show()
# → returns title, body, worker_context, parents, prior attempts, comments

# (worker reads worker_context, uses terminal/file tools to design the schema,
#  write migrations, run its own checks, commit — the real work happens here)

kanban_heartbeat(note="schema drafted, writing migrations now")

kanban_complete(
    tóm tắt="người dùng(id, email, pw_hash), phiên(id, user_id, jti, experis_at); "
            "làm mới mã thông báo được lưu trữ dưới dạng phiên có loại='refresh'",
    siêu dữ liệu={
        "changed_files": ["migrations/001_users.sql", "migrations/002_sessions.sql"],
        "quyết định": ["bcrypt để băm", "JWT cho mã thông báo phiên",
                      "Làm mới 7 ngày, truy cập 15 phút"],
    },
)

kanban_show mặc định task_id thành $HERMES_KANBAN_TASK, vì vậy nhân viên không cần biết id của chính mình. kanban_complete ghi tóm tắt + siêu dữ liệu vào hàng task_runs hiện tại, đóng lần chạy đó và chuyển nhiệm vụ sang done — tất cả chỉ trong một bước nhảy nguyên tử thông qua kanban_db.

Khi SCHEMA chạm vào xong, công cụ phụ thuộc sẽ tự động chuyển API thành sẵn sàng. Khi bắt đầu, nhân viên API sẽ gọi kanban_show() và xem bản tóm tắt và siêu dữ liệu của SCHEMA được đính kèm với bản chuyển giao gốc — để nó biết các quyết định lược đồ mà không cần đọc lại tài liệu thiết kế dài.

Nhấp vào nhiệm vụ lược đồ đã hoàn thành trên bảng và ngăn kéo hiển thị mọi thứ:

Phần Lịch sử chạy ở phía dưới là phần bổ sung quan trọng. Một lần thử: kết quả đã hoàn thành, nhân viên @backend-dev, thời lượng, dấu thời gian và bản tóm tắt bàn giao đầy đủ. Blob siêu dữ liệu (changed_files, quyết định) cũng được lưu trữ trong quá trình chạy và hiển thị cho bất kỳ nhân viên hạ nguồn nào đọc phần gốc này.

Bạn có thể kiểm tra cùng một dữ liệu từ thiết bị đầu cuối của mình bất kỳ lúc nào — những lệnh này bạn đang nhìn vào bảng chứ không phải nhân viên:

hermes kanban show $SCHEMA
hermes kanban runs $SCHEMA
# #  OUTCOME       PROFILE       ELAPSED  STARTED
# 1  completed     backend-dev        0s  2026-04-27 19:34
#     → users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); refresh tokens ...

Câu chuyện 2 — Nuôi theo đội tàu

Bạn có ba công nhân (người phiên dịch, người phiên dịch, người viết quảng cáo) và một đống nhiệm vụ độc lập. Bạn muốn cả ba hoạt động song song và đạt được tiến bộ rõ ràng. Đây là trường hợp sử dụng kanban đơn giản nhất và là trường hợp được thiết kế ban đầu tối ưu hóa.

Tạo tác phẩm:

for lang in Spanish French German; do
    hermes kanban create "Translate homepage to $lang" \
        --assignee translator --tenant content-ops
done
for i in 1 2 3 4 5; do
    hermes kanban create "Transcribe Q3 customer call #$i" \
        --assignee transcriber --tenant content-ops
done
for sku in 1001 1002 1003 1004; do
    hermes kanban create "Generate product description: SKU-$sku" \
        --assignee copywriter --tenant content-ops
done

Khởi động cổng và bỏ đi - nó lưu trữ bộ điều phối được nhúng thực hiện cả ba nhiệm vụ của hồ sơ chuyên gia trên cùng một kanban.db:

hermes gateway start

Bây giờ hãy lọc bảng thành content-ops (hoặc chỉ tìm kiếm "Phiên âm") và bạn nhận được điều này:

Hai bản ghi đã xong, một bản đang chạy, hai bản sẵn sàng chờ người điều phối tiếp theo đánh dấu. Cột Đang tiến hành được nhóm theo hồ sơ (mặc định là "Làn đường theo hồ sơ") để bạn có thể xem nhiệm vụ đang hoạt động của từng nhân viên mà không cần quét danh sách hỗn hợp. Người điều phối sẽ thúc đẩy tác vụ sẵn sàng tiếp theo lên chạy ngay khi tác vụ hiện tại hoàn thành. Với ba daemon hoạt động song song trên ba nhóm được chỉ định, toàn bộ hàng đợi nội dung sẽ thoát ra mà không cần thêm sự can thiệp của con người.

Mọi điều mà Câu chuyện 1 nói về chuyển giao có cấu trúc vẫn áp dụng ở đây. Một nhân viên dịch thuật hoàn thành cuộc gọi sẽ phát ra kanban_complete(summary="transated 4 pages, stylematched marketing voice", metadata={"duration_seconds": 720, "tokens_used": 2100}) — hữu ích cho việc phân tích và cho bất kỳ nhiệm vụ tiếp theo nào phụ thuộc vào nhiệm vụ này.

Câu chuyện 3 — Quy trình phân chia vai trò với việc thử lại

Đây là nơi Kanban kiếm được lợi nhuận từ danh sách TODO cố định. Một PM viết một thông số kỹ thuật. Một kỹ sư thực hiện nó. Người đánh giá từ chối lần thử đầu tiên. Người kỹ sư thử lại với những thay đổi. Người đánh giá phê duyệt.

Chế độ xem trang tổng quan, được lọc theo auth-project:

Chuỗi ba giai đoạn hiển thị cùng một lúc: Thông số: quy trình đặt lại mật khẩu (XONG, chiều), Thực hiện quy trình đặt lại mật khẩu (XONG, backend-dev), Xem lại PR đặt lại mật khẩu (SẴN SÀNG, người đánh giá). Mỗi cái có cha mẹ màu xanh lá cây ở dưới cùng và con cái là phần phụ thuộc.

Điều thú vị là nhiệm vụ triển khai vì nó đã bị chặn và thử lại. Đây là vũ đạo đầy đủ của ba tác nhân, được hiển thị khi công cụ gọi mà mô hình của mỗi công nhân thực hiện:

# --- PM worker spawns on $SPEC and writes the acceptance criteria ---
# worker tool calls
kanban_show()
kanban_complete(
    summary="spec approved; POST /forgot-password sends email, "
            "GET /reset/:token renders form, POST /reset applies new password",
    metadata={"acceptance": [
        "expired token returns 410",
        "reused last-3 password returns 400 with message",
        "successful reset invalidates all active sessions",
    ]},
)
# → $SPEC is done; $IMPL auto-promotes from todo to ready

# --- Công nhân kỹ sư sinh ra trên $IMPL (lần thử đầu tiên) ---
# cuộc gọi công cụ công nhân
kanban_show() # đọc siêu dữ liệu chấp nhận + tóm tắt của $SPEC trong worker_context
# (kỹ sư viết code, chạy test, mở PR)
# Phản hồi của người đánh giá đến — kỹ sư quyết định mối lo ngại là hợp lệ và chặn
kanban_block(
    lý do="Đánh giá: thiếu kiểm tra độ mạnh mật khẩu, liên kết đặt lại không có "
           "dùng một lần (có thể phát lại trong vòng 30 phút)",
)
# → $IMPL chuyển tiếp sang bị chặn; lượt chạy 1 kết thúc với kết quả = 'bị chặn'

Bây giờ bạn (con người hoặc một hồ sơ người đánh giá riêng biệt) đọc lý do chặn, quyết định hướng khắc phục rõ ràng và bỏ chặn từ nút "Bỏ chặn" của trang tổng quan — hoặc từ lệnh CLI / gạch chéo:

hermes kanban unblock $IMPL
# or from a chat: /kanban unblock $IMPL

Người điều phối thăng cấp $IMPL trở lại trạng thái sẵn sàng và ở tích tắc tiếp theo, sẽ hồi sinh nhân viên backend-dev. Lần sinh sản thứ hai này là lần chạy mới với cùng một nhiệm vụ:

# --- Engineer worker spawns on $IMPL (second attempt) ---
# worker tool calls
kanban_show()
# → worker_context now includes the run 1 block reason, so this worker knows
#   which two things to fix instead of re-reading the whole spec
# (engineer adds zxcvbn check, makes reset tokens single-use, re-runs tests)
kanban_complete(
    summary="added zxcvbn strength check, reset tokens are now single-use "
            "(stored + deleted on success)",
    metadata={
        "changed_files": [
            "auth/reset.py",
            "auth/tests/test_reset.py",
            "migrations/003_single_use_reset_tokens.sql",
        ],
        "tests_run": 11,
        "review_iteration": 2,
    },
)

Bấm vào nhiệm vụ thực hiện. Ngăn kéo hiển thị hai lần thử:

• Chạy 1 — bị chặn bởi @backend-dev. Phản hồi đánh giá nằm ngay dưới kết quả: "thiếu kiểm tra độ mạnh mật khẩu, liên kết đặt lại không sử dụng một lần (có thể phát lại trong vòng 30 phút)".
• Chạy 2 — hoàn thành bởi @backend-dev. Tóm tắt mới, siêu dữ liệu mới.

Mỗi lần chạy là một hàng trong task_runs có kết quả, tóm tắt và siêu dữ liệu riêng. Lịch sử thử lại không phải là một ý tưởng khái niệm được xếp chồng lên trên nhiệm vụ "trạng thái mới nhất" — đó là cách trình bày chính. Khi một nhân viên thử lại mở tác vụ, build_worker_context hiển thị cho nó những lần thử trước đó, để nhân viên vượt qua thứ hai biết lý do tại sao lần vượt qua đầu tiên bị chặn và giải quyết những phát hiện cụ thể đó thay vì chạy lại từ đầu.

Người đánh giá chọn tiếp theo. Khi họ mở Xem lại PR đặt lại mật khẩu, họ thấy:

Liên kết gốc là việc thực hiện hoàn thành. Khi nhân viên của người đánh giá xuất hiện trên Xem lại PR đặt lại mật khẩu và gọi kanban_show(), worker_context được trả về bao gồm siêu dữ liệu + tóm tắt chạy gần đây nhất của cha mẹ — vì vậy người đánh giá đọc "kiểm tra độ mạnh zxcvbn đã thêm, mã đặt lại hiện chỉ dùng một lần" và có trong tay danh sách các tệp đã thay đổi trước khi xem xét điểm khác biệt.

Câu chuyện 4 — Cầu dao và khắc phục sự cố

Công nhân thực sự thất bại. Thiếu thông tin xác thực, lỗi OOM, lỗi mạng tạm thời. Bộ điều phối có hai tuyến phòng thủ: một bộ ngắt mạch tự động chặn sau N lần thất bại liên tiếp để bo mạch không bị hỏng vĩnh viễn và phát hiện sự cố để khôi phục một nhiệm vụ mà PID nhân viên của nó đã biến mất trước khi TTL của nó hết hạn.

Bộ ngắt mạch — hư hỏng vĩnh viễn

Tác vụ triển khai không thể sinh ra nhân viên của nó vì AWS_ACCESS_KEY_ID không được đặt trong môi trường của cấu hình:

hermes kanban create "Deploy to staging (missing creds)" \
    --assignee deploy-bot --tenant ops

Người điều phối cố gắng sinh ra công nhân. Sinh sản không thành công (RuntimeError: AWS_ACCESS_KEY_ID chưa được đặt). Người điều phối đưa ra yêu cầu, tăng bộ đếm lỗi và thử lại lần đánh dấu tiếp theo. Sau ba lần thất bại liên tiếp (mặc định là failure_limit), mạch sẽ ngắt: tác vụ chuyển sang bị chặn với kết quả là give_up. Không cần thử lại nữa cho đến khi có người mở chặn nó.

Bấm vào tác vụ bị chặn:

Ba lần chạy, tất cả đều có cùng một lỗi trên trường error. Hai cái đầu tiên là spawn_failed (có thể thử lại), cái thứ ba là gave_up (terminal). Nhật ký sự kiện ở trên hiển thị trình tự đầy đủ: được tạo → đã xác nhận → spawn_failed → đã xác nhận → spawn_failed → đã xác nhận → đã cho_up.

Trên thiết bị đầu cuối:

hermes kanban runs t_ef5d
# #   OUTCOME        PROFILE        ELAPSED  STARTED
# 1   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 2   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 3   gave_up        deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env

Nếu Telegram / Discord / Slack được kết nối, một thông báo cổng sẽ kích hoạt sự kiện give_up để bạn biết về việc ngừng hoạt động mà không cần phải kiểm tra bảng.

Khắc phục sự cố — công nhân chết giữa chuyến bay

Đôi khi quá trình sinh sản thành công nhưng quy trình công nhân lại chết sau đó - segfault, OOM, systemctl stop. Người điều phối thăm dò kill(pid, 0) và phát hiện pid chết; yêu cầu hủy bỏ, nhiệm vụ quay trở lại sẵn sàng và dấu tích tiếp theo sẽ giao nó cho một nhân viên mới.

Ví dụ trong dữ liệu hạt giống là một quá trình di chuyển sắp hết bộ nhớ:

# Worker claims, starts scanning 2.4M rows, OOM kills it at ~2.3M
# Dispatcher detects dead pid, releases claim, increments attempt counter
# Retry with a chunked strategy succeeds

Ngăn kéo hiển thị toàn bộ lịch sử hai lần thử:

Chạy 1 — bị lỗi, với lỗi OOM kill ở hàng 2.3M (process 99999 gone). Chạy 2 — hoàn thành, với "chiến lược": "được chia nhỏ với LIMIT + WHERE id > Last_id" trong siêu dữ liệu của nó. Nhân viên thử lại đã nhìn thấy sự cố của lần chạy 1 trong bối cảnh của nó và chọn một chiến lược an toàn hơn; siêu dữ liệu giúp người quan sát trong tương lai (hoặc người viết kết quả khám nghiệm tử thi) thấy rõ điều gì đã thay đổi.

Chuyển giao có cấu trúc - tại sao tóm tắt và siêu dữ liệu lại quan trọng

Trong mỗi câu chuyện ở trên, nhân viên gọi kanban_complete(summary=..., metadata=...) ở cuối. Đó không phải là trang trí — đó là kênh chuyển giao chính giữa các giai đoạn của quy trình làm việc.

Khi một nhân viên thực hiện nhiệm vụ B được sinh ra và gọi kanban_show(), worker_context nó nhận được bao gồm:

• lần thử trước của B (các lần chạy trước: kết quả, tóm tắt, lỗi, siêu dữ liệu) để nhân viên thử lại không lặp lại đường dẫn thất bại.
• Kết quả nhiệm vụ cấp trên — đối với mỗi cấp trên, siêu dữ liệu và tóm tắt của lần chạy đã hoàn thành gần đây nhất — để nhân viên cấp dưới biết lý do và cách thực hiện công việc cấp trên.

Điều này thay thế điệu nhảy "đào bới các nhận xét và kết quả công việc" đang gây khó khăn cho các hệ thống kanban phẳng. Một PM viết các tiêu chí chấp nhận trong siêu dữ liệu của thông số kỹ thuật và nhân viên của kỹ sư sẽ nhìn thấy chúng theo cấu trúc trong bản chuyển giao gốc. Một kỹ sư ghi lại những bài kiểm tra mà họ đã chạy và số lượng đã vượt qua, đồng thời nhân viên của người đánh giá sẽ có danh sách đó trong tay trước khi mở một phần khác biệt.

Bảo vệ đóng hàng loạt tồn tại vì dữ liệu này được thực hiện trên mỗi lần chạy. hermes kanban Complete a b c --summary X (bạn, từ CLI) bị từ chối — việc sao chép và dán cùng một bản tóm tắt vào ba nhiệm vụ hầu như luôn sai. Đóng hàng loạt mà không có cờ chuyển giao vẫn hoạt động trong trường hợp phổ biến "Tôi đã hoàn thành một đống nhiệm vụ quản trị viên". Bề mặt công cụ hoàn toàn không để lộ một biến thể lớn nào; kanban_complete luôn thực hiện một nhiệm vụ tại một thời điểm vì lý do tương tự.

Kiểm tra tác vụ hiện đang chạy

Để hoàn thiện - đây là ngăn kéo của một nhiệm vụ vẫn đang được thực hiện (việc triển khai API từ Câu chuyện 1, được backend-dev xác nhận nhưng chưa hoàn thành):

Trạng thái là Đang chạy. Lần chạy đang hoạt động xuất hiện trong phần Lịch sử lần chạy với kết quả là hoạt động và không có kết thúc_at. Nếu nhân viên này chết hoặc hết thời gian chờ, người điều phối sẽ đóng lượt chạy này với kết quả phù hợp và mở một lượt mới cho yêu cầu tiếp theo — hàng thử sẽ không bao giờ biến mất.

Các bước tiếp theo

• Tổng quan về Kanban — mô hình dữ liệu đầy đủ, từ vựng sự kiện và tài liệu tham khảo CLI.
• hermes kanban --help — mọi tiểu ban, mọi lá cờ.
• đồng hồ hermes kanban --kinds đã hoàn thành,give_up,timed_out — phát trực tiếp các sự kiện cuối cùng trên toàn bộ diễn đàn.
• hermes kanban notification-subscribe <task> --platform telegram --chat-id <id> — nhận ping cổng khi một tác vụ cụ thể kết thúc.