Kanban — Cộng tác hồ sơ đa tác nhân

Muốn xem hướng dẫn chi tiết? Đọc Hướng dẫn Kanban — bốn câu chuyện của người dùng (nhà phát triển solo, canh tác đội tàu, quy trình vai trò với thử lại, ngắt mạch) cùng với ảnh chụp màn hình bảng điều khiển của mỗi câu chuyện. Trang này là tài liệu tham khảo; hướng dẫn là câu chuyện.

Hermes Kanban là một bảng nhiệm vụ lâu bền, được chia sẻ trên tất cả hồ sơ Hermes của bạn, cho phép nhiều đặc vụ được nêu tên cộng tác trong công việc mà không có các nhóm đại lý phụ mỏng manh trong quá trình. Mỗi tác vụ là một hàng trong ~/.hermes/kanban.db; mỗi lần chuyển giao là một hàng mà ai cũng có thể đọc và viết; mỗi công nhân là một quy trình hệ điều hành đầy đủ với bản sắc riêng.

Hai bề mặt: mô hình nói chuyện qua công cụ, bạn nói chuyện qua CLI

Bảng có hai cửa trước, cả hai đều được hỗ trợ bởi cùng một ~/.hermes/kanban.db:

• Đại lý điều khiển bảng thông qua bộ công cụ kanban_* chuyên dụng — kanban_show, kanban_list, kanban_complete, kanban_block, kanban_heartbeat, kanban_comment, kanban_create, kanban_link, kanban_unblock. Bộ điều phối sinh ra mỗi công nhân với những công cụ này đã có trong lược đồ của nó; hồ sơ người điều phối cũng có thể kích hoạt bộ công cụ kanban một cách rõ ràng. Mô hình này đọc và định tuyến các tác vụ bằng cách gọi trực tiếp các công cụ, không phải bằng cách gọi hermes kanban. Xem Cách nhân viên tương tác với hội đồng quản trị bên dưới.
• Bạn (và các tập lệnh và cron) điều khiển bảng thông qua hermes kanban … trên CLI, /kanban … dưới dạng lệnh gạch chéo hoặc bảng điều khiển. Những thứ này dành cho con người và tự động hóa - những nơi không có mô hình gọi công cụ đằng sau chúng.

Cả hai bề mặt đều định tuyến qua cùng một lớp kanban_db, do đó, quá trình đọc sẽ thấy chế độ xem nhất quán và quá trình ghi không thể bị trôi. Phần còn lại của trang này hiển thị các ví dụ CLI vì chúng dễ sao chép-dán, nhưng mỗi động từ CLI đều có lệnh gọi công cụ tương đương mà mô hình sử dụng.

Đây là hình dạng bao gồm khối lượng công việc delegate_task không thể:

• Phân loại nghiên cứu — nhà nghiên cứu song song + nhà phân tích + nhà văn, con người trong vòng lặp.
• Các hoạt động đã lên lịch — các bản tóm tắt định kỳ hàng ngày giúp xây dựng nhật ký trong nhiều tuần.
• Cặp song sinh kỹ thuật số — trợ lý được đặt tên liên tục (inbox-triage, ops-review) tích lũy bộ nhớ theo thời gian.
• Quy trình kỹ thuật — phân rã → triển khai trong các cây công việc song song → xem xét → lặp lại → PR.
• Công việc nhóm — một chuyên gia quản lý N đối tượng (50 tài khoản xã hội, 12 dịch vụ được giám sát).

Để biết cơ sở lý luận đầy đủ về thiết kế, phân tích so sánh với Cline Kanban / Paperclip / NanoClaw / Google Gemini Enterprise và tám mẫu cộng tác chuẩn, hãy xem docs/hermes-kanban-v1-spec.pdf trong kho lưu trữ.

Kanban so với delegate_task

Chúng trông giống nhau; chúng không giống nhau nguyên thủy.

	delegate_task	Kanban
Shape	RPC call (fork → join)	Durable message queue + state machine
Parent	Blocks until child returns	Fire-and-forget after create
Child identity	Anonymous subagent	Named profile with persistent memory
Resumability	None — failed = failed	Block → unblock → re-run; crash → reclaim
Human in the loop	Not supported	Comment / unblock at any point
Agents per task	One call = one subagent	N agents over task's life (retry, review, follow-up)
Audit trail	Lost on context compression	Durable rows in SQLite forever
Coordination	Hierarchical (caller → callee)	Peer — any profile reads/writes any task

Phân biệt một câu: delegate_task là lệnh gọi hàm; Kanban là một hàng đợi công việc trong đó mỗi lần chuyển giao là một hàng mà bất kỳ hồ sơ nào (hoặc con người) đều có thể xem và chỉnh sửa.

Sử dụng delegate_task khi tác nhân mẹ cần một câu trả lời lý luận ngắn gọn trước khi tiếp tục, không có sự tham gia của con người, kết quả sẽ quay trở lại ngữ cảnh của tác nhân mẹ.

Sử dụng Kanban khi công việc vượt qua ranh giới của tổng đài viên, cần tiếp tục khởi động lại, có thể cần ý kiến ​​đóng góp của con người, có thể được một vai trò khác đảm nhận hoặc cần được khám phá sau khi thực hiện xong.

Chúng cùng tồn tại: một nhân viên Kanban có thể gọi delegate_task nội bộ trong quá trình chạy.

Khái niệm cốt lõi

• Board — a standalone queue of tasks with its own SQLite DB, workspaces directory, and dispatcher loop. A single install can have many boards (e.g. one per project, repo, or domain); see Boards (multi-project) below. Single-project users stay on the default board and never see the word "board" outside this docs section.
• Task — a row with title, optional body, one assignee (a profile name), status (triage | todo | ready | running | blocked | done | archived), optional tenant namespace, optional idempotency key (dedup for retried automation).
• Link — task_links row recording a parent → child dependency. The dispatcher promotes todo → ready when all parents are done.
• Comment — the inter-agent protocol. Agents and humans append comments; when a worker is (re-)spawned it reads the full comment thread as part of its context.
• Workspace — the directory a worker operates in. Three kinds:
  • scratch (default) — fresh tmp dir under ~/.hermes/kanban/workspaces/<id>/ (or ~/.hermes/kanban/boards/<slug>/workspaces/<id>/ on non-default boards).
  • dir:<path> — an existing shared directory (Obsidian vault, mail ops dir, per-account folder). Must be an absolute path. Relative paths like dir:../tenants/foo/ are rejected at dispatch because they'd resolve against whatever CWD the dispatcher happens to be in, which is ambiguous and a confused-deputy escape vector. The path is otherwise trusted — it's your box, your filesystem, the worker runs with your uid. This is the trusted-local-user threat model; kanban is single-host by design.
  • worktree — a git worktree under .worktrees/<id>/ for coding tasks. Worker-side git worktree add creates it.
• Dispatcher — a long-lived loop that, every N seconds (default 60): reclaims stale claims, reclaims crashed workers (PID gone but TTL not yet expired), promotes ready tasks, atomically claims, spawns assigned profiles. Runs inside the gateway by default (kanban.dispatch_in_gateway: true). One dispatcher sweeps all boards per tick; workers are spawned with HERMES_KANBAN_BOARD pinned so they can't see other boards. After kanban.failure_limit consecutive spawn failures on the same task (default: 2) the dispatcher auto-blocks it with the last error as the reason — prevents thrashing on tasks whose profile doesn't exist, workspace can't mount, etc.
• Tenant — optional string namespace within a board. One specialist fleet can serve multiple businesses (--tenant business-a) with data isolation by workspace path and memory key prefix. Tenants are a soft filter; boards are the hard isolation boundary.

Bảng (đa dự án)

Các bảng cho phép bạn tách biệt các luồng công việc không liên quan - mỗi luồng cho mỗi dự án, repo, hoặc miền — vào các hàng đợi bị cô lập. Một bản cài đặt mới có chính xác một bảng được gọi là default (DB tại ~/.hermes/kanban.db để tương thích ngược). Người dùng chỉ muốn một luồng công việc không bao giờ cần biết về bảng; tính năng được chọn tham gia.

Cách ly trên mỗi bảng là tuyệt đối:

• Phân tách cơ sở dữ liệu SQLite trên mỗi bảng (~/.hermes/kanban/boards/<slug>/kanban.db).
• Tách biệt các thư mục workspaces/ và logs/.
• Công nhân sinh ra cho một nhiệm vụ chỉ xem nhiệm vụ của hội đồng quản trị của họ — người điều phối đặt HERMES_KANBAN_BOARD trong env con và mọi Công cụ kanban_* mà nhân viên có quyền truy cập để đọc nó.
• Không cho phép liên kết các tác vụ giữa các bảng (giữ cho lược đồ đơn giản; nếu bạn thực sự cần các tài liệu tham khảo liên dự án, sử dụng các đề cập bằng văn bản tự do và xem xét chúng lên theo id theo cách thủ công).

Quản lý bảng từ CLI

# See what's on disk. Fresh installs show only "default".
hermes kanban boards list

# Create a new board.
hermes kanban boards create atm10-server \
    --name "ATM10 Server" \
    --description "Minecraft modded server ops" \
    --icon 🎮 \
    --switch                   # optional: make it the active board

# Operate on a specific board without switching.
hermes kanban --board atm10-server list
hermes kanban --board atm10-server create "Restart ATM server" --assignee ops

# Change which board is "current" for subsequent calls.
hermes kanban boards switch atm10-server
hermes kanban boards show             # who's active right now?

# Rename the display name (the slug is immutable — it's the directory name).
hermes kanban boards rename atm10-server "ATM10 (Prod)"

# Archive (default) — moves the board's dir to boards/_archived/<slug>-<ts>/.
# Recoverable by moving the dir back.
hermes kanban boards rm atm10-server

# Xóa cứng — `rm -rf` thư mục bảng. Không có sự phục hồi.
bảng Hermes Kanban rm atm10-server --delete

Lệnh giải quyết của Hội đồng quản trị (ưu tiên cao nhất trước):

1. Rõ ràng --board <slug> trong lệnh gọi CLI.
2. HERMES_KANBAN_BOARD env var (do người điều phối đặt khi sinh ra một công nhân, vì vậy công nhân không thể nhìn thấy các bảng khác).
3. ~/.hermes/kanban/current — con sên vẫn tồn tại bởi hermes kanban bảng chuyển đổi.
4. mặc định.

Sên được xác thực: chữ và số viết thường + dấu gạch ngang + dấu gạch dưới, 1-64 ký tự, phải bắt đầu bằng chữ và số. Đầu vào viết hoa được tự động viết xuống. Mọi thứ khác (dấu gạch chéo, dấu cách, dấu chấm, ..) đều bị từ chối ở lớp CLI nên các thủ thuật truyền tải đường dẫn không thể đặt tên cho một bảng.

Quản lý bảng từ bảng điều khiển

``bảng điều khiển Hermes→ Tab Kanban hiển thị trình chuyển bảng ở trên cùng ngay vì có nhiều hơn một bảng tồn tại (hoặc bất kỳ bảng nào cũng có nhiệm vụ). Người dùng bảng đơn chỉ thấy một nút+ Bảng mới` nhỏ; bộ chuyển đổi được ẩn cho đến khi nó vấn đề.

• Bảng thả xuống — chọn bảng đang hoạt động. Lựa chọn của bạn được lưu vào localStorage của trình duyệt để nó tồn tại trong suốt quá trình tải lại mà không cần chuyển con trỏ hiện tại của CLI ra khỏi thiết bị đầu cuối mà bạn đã để lại mở.
• + Bảng mới — mở một phương thức yêu cầu sên, tên hiển thị, mô tả và biểu tượng. Tùy chọn tự động chuyển sang bảng mới.
• Lưu trữ — chỉ hiển thị trên các bảng không phải mặc định. Xác nhận rồi di chuyển thư mục bảng tới boards/_archived/.

Tất cả các điểm cuối API của trang tổng quan đều chấp nhận ?board=<slug> cho phạm vi bảng. các sự kiện WebSocket được ghim vào bảng tại thời điểm kết nối; chuyển đổi giao diện người dùng mở một WS mới trên bảng mới.

Bắt đầu nhanh

Các lệnh bên dưới là bạn (con người) thiết lập bảng và tạo nhiệm vụ. Sau khi một nhiệm vụ được giao, người điều phối sẽ tạo hồ sơ được giao với tư cách là một nhân viên và từ đó mô hình điều khiển nhiệm vụ đó thông qua lệnh gọi công cụ kanban_*, chứ không phải lệnh CLI — xem Cách nhân viên tương tác với bảng.

# 1. Create the board (you)
hermes kanban init

# 2. Start the gateway (hosts the embedded dispatcher)
hermes gateway start

# 3. Create a task (you — or an orchestrator agent via kanban_create)
hermes kanban create "research AI funding landscape" --assignee researcher

# 4. Watch activity live (you)
hermes kanban watch

#5. Xem bảng (bạn)
danh sách kanban của Hermes
số liệu thống kê của Hermes Kanban

Khi người điều phối chọn t_abcd và hiển thị hồ sơ nhà nghiên cứu, điều đầu tiên mà mô hình của công nhân thực hiện là gọi kanban_show() để đọc nhiệm vụ của nó. Nó không chạy hermes kanban show t_abcd.

Bộ điều phối nhúng cổng (mặc định)

Bộ điều phối chạy bên trong quy trình cổng. Không có gì để cài đặt, không dịch vụ riêng biệt để quản lý - nếu cổng hoạt động, các tác vụ đã sẵn sàng sẽ được chọn tăng ở tích tắc tiếp theo (60 giây theo mặc định).

# config.yaml
kanban:
  dispatch_in_gateway: true        # default
  dispatch_interval_seconds: 60    # default

Ghi đè cờ cấu hình khi chạy thông qua HERMES_KANBAN_DISPATCH_IN_GATEWAY=0 để gỡ lỗi. Áp dụng giám sát cổng tiêu chuẩn: chạy hermes Gateway start trực tiếp hoặc kết nối cổng dưới dạng đơn vị người dùng systemd (xem phần tài liệu cổng). Không có cổng đang chạy, các tác vụ sẵn sàng vẫn ở nguyên vị trí cho đến khi một cái xuất hiện — ``hermes kanban create` cảnh báo về điều này khi sáng tạo thời gian.

Việc chạy hermes kanban daemon như một quy trình riêng biệt không được dùng nữa; sử dụng cổng. Nếu bạn thực sự không thể chạy cổng (máy chủ không đầu chính sách cấm các dịch vụ tồn tại lâu dài, v.v.) cửa thoát hiểm --force giữ daemon độc lập cũ vẫn tồn tại trong một chu kỳ phát hành nhưng chạy cả hai một bộ điều phối được nhúng vào cổng VÀ một trình nền độc lập tương tự kanban.db gây ra các cuộc đua xác nhận quyền sở hữu và không được hỗ trợ.

Tạo tạm thời (dành cho tự động hóa / webhook)

# First call creates the task. Any subsequent call with the same key
# returns the existing task id instead of duplicating.
hermes kanban create "nightly ops review" \
    --assignee ops \
    --idempotency-key "nightly-ops-$(date -u +%Y-%m-%d)" \
    --json

Động từ CLI hàng loạt

Tất cả các động từ vòng đời chấp nhận nhiều id để bạn có thể dọn dẹp một loạt trong một lệnh:

hermes kanban complete t_abc t_def t_hij --result "batch wrap"
hermes kanban archive  t_abc t_def t_hij
hermes kanban unblock  t_abc t_def
hermes kanban block    t_abc "need input" --ids t_def t_hij

Cách người lao động tương tác với hội đồng quản trị

Workers không bỏ ra hermes kanban. Khi người điều phối sinh ra một worker, nó đặt HERMES_KANBAN_TASK=t_abcd trong env của con và env var đó sẽ bật bộ công cụ kanban chuyên dụng trong lược đồ của mô hình. Bộ công cụ tương tự cũng có sẵn cho các cấu hình bộ điều phối kích hoạt kanban trong cấu hình bộ công cụ của chúng. Các công cụ này đọc và thay đổi bảng trực tiếp thông qua lớp kanban_db của Python, giống như CLI. Một nhân viên đang chạy gọi những thứ này giống như bất kỳ công cụ nào khác; nó không bao giờ nhìn thấy hoặc cần CLI hermes kanban.

Tool	Purpose	Required params
kanban_show	Read the current task (title, body, prior attempts, parent handoffs, comments, full pre-formatted worker_context). Defaults to the env's task id.	—
kanban_list	List task summaries with filters for assignee, status, tenant, archived visibility, and limit. Intended for orchestrators discovering board work.	—
kanban_complete	Finish with summary + metadata structured handoff.	at least one of summary / result
kanban_block	Escalate for human input with a reason.	reason
kanban_heartbeat	Signal liveness during long operations. Pure side-effect.	—
kanban_comment	Append a durable note to the task thread.	task_id, body
kanban_create	(Orchestrators) fan out into child tasks with an assignee, optional parents, skills, etc.	title, assignee
kanban_link	(Orchestrators) add a parent_id → child_id dependency edge after the fact.	parent_id, child_id
kanban_unblock	(Orchestrators) move a blocked task back to ready.	task_id

Một lượt công nhân điển hình trông như sau:

# Model's tool calls, in order:
kanban_show()                                     # no args — uses HERMES_KANBAN_TASK
# (model reads the returned worker_context, does the work via terminal/file tools)
kanban_heartbeat(note="halfway through — 4 of 8 files transformed")
# (more work)
kanban_complete(
    summary="migrated limiter.py to token-bucket; added 14 tests, all pass",
    metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
)

Thay vào đó, một công nhân dàn nhạc quạt ra:

kanban_show()
kanban_create(
    title="research ICP funding 2024-2026",
    assignee="researcher-a",
    body="focus on seed + series A, North America, AI-adjacent",
)
# → returns {"task_id": "t_r1", ...}
kanban_create(title="research ICP funding — EU angle", assignee="researcher-b", body="…")
# → returns {"task_id": "t_r2", ...}
kanban_create(
    title="synthesize findings into launch brief",
    assignee="writer",
    parents=["t_r1", "t_r2"],                     # promotes to ready when both complete
    body="one-pager, 300 words, neutral tone",
)
kanban_complete(summary="decomposed into 2 research tasks + 1 writer; linked dependencies")

Các công cụ "(Người điều phối)" — kanban_list, kanban_create, kanban_link, kanban_unblock và kanban_comment về các nhiệm vụ nước ngoài — có sẵn thông qua cùng một bộ công cụ; quy ước (được thực thi bởi kỹ năng kanban-người điều phối) là hồ sơ công nhân không phân tán hoặc định tuyến công việc không liên quan và hồ sơ người điều phối không thực hiện công việc triển khai. Các công nhân do người điều phối sinh ra vẫn có phạm vi nhiệm vụ cho các hoạt động phá hoại trong vòng đời và không thể thay đổi các nhiệm vụ không liên quan.

Tại sao lại sử dụng công cụ thay vì pháo kích vào hermes kanban

Ba lý do:

1. Tính di động của phần cuối. Các trình chạy có công cụ đầu cuối trỏ đến phần phụ trợ từ xa (Docker / Modal / Singularity / SSH) sẽ chạy hermes kanban Complete bên trong vùng chứa, trong đó hermes chưa được cài đặt và ~/.hermes/kanban.db chưa được gắn kết. Các công cụ kanban chạy trong quy trình Python của chính tác nhân và luôn đạt ~/.hermes/kanban.db bất kể phần phụ trợ của thiết bị đầu cuối.
2. Không có tính dễ vỡ của trích dẫn shell. Truyền --metadata '{"files": [...]}' thông qua shlex + argparse là một khẩu súng ngắn tiềm ẩn. Công cụ có cấu trúc lập luận bỏ qua nó hoàn toàn.
3. Lỗi tốt hơn. Kết quả của công cụ có cấu trúc JSON mà mô hình có thể suy luận, chứ không phải các chuỗi tiêu chuẩn mà nó phải phân tích cú pháp.

Không có dấu vết lược đồ trên các phiên thông thường. Phiên hermes chat thông thường không có công cụ kanban_* nào trong lược đồ của nó. check_fn trên mỗi công cụ chỉ trả về True khi HERMES_KANBAN_TASK được đặt, điều này chỉ xảy ra khi người điều phối tạo ra quy trình này. Không có công cụ cồng kềnh nào dành cho người dùng không bao giờ chạm vào Kanban.

Các kỹ năng kanban-worker và kanban-orchestrator dạy cho mô hình nên gọi công cụ nào khi nào và theo thứ tự nào.

Bằng chứng chuyển giao được đề xuất

kanban_complete(summary=..., siêu dữ liệu={...}) được cố ý linh hoạt: phần tóm tắt là phần kết thúc mà con người có thể đọc được và siêu dữ liệu là bản chuyển giao có thể đọc được bằng máy mà các đại lý, người đánh giá hoặc bảng thông tin phía dưới có thể tái sử dụng mà không cần cạo văn xuôi.

Đối với các nhiệm vụ kỹ thuật và đánh giá, hãy ưu tiên hình dạng siêu dữ liệu tùy chọn này:

{
  "changed_files": ["path/to/file.py"],
  "verification": ["pytest tests/hermes_cli/test_kanban_db.py -q"],
  "dependencies": ["parent task id or external issue, if any"],
  "blocked_reason": null,
  "retry_notes": "what failed before, if this was a retry",
  "residual_risk": ["what was not tested or still needs human review"]
}

Các khóa này là quy ước, không phải là yêu cầu của lược đồ. Tài sản hữu ích là rằng mọi công nhân đều để lại đủ bằng chứng cho người đọc tiếp theo trả lời bốn hỏi nhanh:

1. Điều gì đã thay đổi?
2. Nó được xác minh như thế nào?
3. Điều gì có thể bỏ chặn hoặc thử lại nếu thất bại?
4. Rủi ro nào vẫn được cố tình bỏ ngỏ?

Giữ bí mật, nhật ký thô, mã thông báo, tài liệu OAuth và bản ghi không liên quan ra khỏi siêu dữ liệu. Thay vào đó hãy lưu trữ các con trỏ và tóm tắt. Nếu một tác vụ không có tập tin hoặc kiểm tra, hãy nói rõ ràng như vậy trong phần tóm tắt và sử dụng siêu dữ liệu để làm bằng chứng cho thấy có tồn tại, chẳng hạn như URL nguồn, id vấn đề hoặc các bước xem xét thủ công.

Tay nghề của công nhân

Bất kỳ hồ sơ nào có thể thực hiện các nhiệm vụ kanban đều phải tải kỹ năng kanban-worker. Nó dạy cho nhân viên toàn bộ vòng đời trong các lệnh gọi công cụ chứ không phải các lệnh CLI:

1. Khi xuất hiện, hãy gọi kanban_show() để đọc tiêu đề + nội dung + chuyển giao gốc + các lần thử trước + chuỗi nhận xét đầy đủ.
2. cd $HERMES_KANBAN_WORKSPACE (thông qua công cụ đầu cuối) và thực hiện công việc ở đó.
3. Gọi kanban_heartbeat(note="...") vài phút một lần trong thời gian dài hoạt động.
4. Hoàn thành bằng kanban_complete(summary="...", siêu dữ liệu={...}) hoặc kanban_block(reason="...") nếu bị kẹt.

kanban-worker là một kỹ năng đi kèm, được đồng bộ hóa vào mọi hồ sơ trong quá trình cài đặt và cập nhật — không có bước cài đặt Trung tâm kỹ năng riêng biệt. Xác minh nó có mặt trong bất kỳ hồ sơ nào bạn sử dụng cho nhân viên Kanban (nhà nghiên cứu, nhà văn, ops, v.v.):

hermes -p <your-worker-profile> skills list | grep kanban-worker

Nếu bản sao đi kèm bị thiếu, hãy khôi phục nó cho cấu hình đó:

hermes -p <your-worker-profile> skills reset kanban-worker --restore

Người điều phối cũng tự động chuyển --skills kanban-worker khi sinh ra mọi công nhân, do đó, công nhân luôn có sẵn thư viện mẫu ngay cả khi cấu hình kỹ năng mặc định của hồ sơ không bao gồm nó.

Ghim các kỹ năng bổ sung vào một nhiệm vụ cụ thể

Đôi khi, một nhiệm vụ đơn lẻ cần bối cảnh chuyên môn mà hồ sơ người được giao không có theo mặc định — một công việc dịch thuật cần kỹ năng dịch, một nhiệm vụ đánh giá cần github-code-review, kiểm tra bảo mật cần security-pr-audit. Thay vì liên tục chỉnh sửa hồ sơ của người được giao, hãy gắn các kỹ năng trực tiếp vào nhiệm vụ.

Từ một tác nhân điều phối (trường hợp thông thường — một tác nhân định tuyến công việc này sang một tác nhân khác), hãy sử dụng mảng skills của công cụ kanban_create:

kanban_create(
    title="translate README to Japanese",
    assignee="linguist",
    skills=["translation"],
)

kanban_create(
    title="luồng xác thực kiểm tra",
    người được chuyển nhượng="người đánh giá",
    kỹ năng=["security-pr-audit", "github-code-review"],
)

Từ con người (CLI / lệnh gạch chéo), lặp lại --skill cho mỗi người:

hermes kanban create "translate README to Japanese" \
    --assignee linguist \
    --skill translation

hermes kanban tạo "luồng xác thực kiểm toán" \
    --người được phân công đánh giá \
    --skill security-pr-audit \
    --skill github-code-review

Từ trang tổng quan, nhập các kỹ năng được phân tách bằng dấu phẩy vào trường skills của biểu mẫu tạo nội tuyến.

Những kỹ năng này bổ sung cho kanban-worker tích hợp sẵn — trình điều phối phát ra một cờ --skills <name> cho mỗi cờ (và cho cờ tích hợp sẵn), do đó, nhân viên sinh ra với tất cả các kỹ năng đó đã được tải. Tên kỹ năng phải khớp với các kỹ năng thực sự được cài đặt trong hồ sơ của người được giao (chạy danh sách kỹ năng hermes để xem những gì có sẵn); không có cài đặt thời gian chạy.

###Kỹ năng dàn nhạc

Người điều phối hoạt động tốt không tự mình thực hiện công việc. Nó phân tách mục tiêu của người dùng thành các nhiệm vụ, liên kết chúng, gán từng nhiệm vụ cho một trong các hồ sơ bạn đã thiết lập và lùi lại. Kỹ năng kanban-orchestrator mã hóa điều này dưới dạng các mẫu lệnh gọi công cụ: quy tắc chống cám dỗ, lời nhắc khám phá hồ sơ Bước 0 (người điều phối âm thầm thất bại với tên người được giao không xác định, vì vậy người điều phối phải nối mọi thẻ vào các hồ sơ thực sự tồn tại trên máy của bạn) và một playbook phân rã có khóa trên kanban_create / kanban_link / kanban_comment.

Đến lượt người điều phối kinh điển (hai nhà nghiên cứu song song giao cho một nhà văn):

# Goal from user: "draft a launch post on the ICP funding landscape"
kanban_create(title="research ICP funding, NA angle",  assignee="researcher-a", body="…")  # → t_r1
kanban_create(title="research ICP funding, EU angle",  assignee="researcher-b", body="…")  # → t_r2
kanban_create(
    title="synthesize ICP funding research into launch post draft",
    assignee="writer",
    parents=["t_r1", "t_r2"],        # promoted to 'ready' when both researchers complete
    body="one-pager, neutral tone, cite sources inline",
)                                     # → t_w1
# Optional: add cross-cutting deps discovered later without re-creating tasks
kanban_link(parent_id="t_r1", child_id="t_followup")
kanban_complete(
    summary="decomposed into 2 parallel research tasks → 1 synthesis task; writer starts when both researchers finish",
)

kanban-orchestrator là một kỹ năng đi kèm. Nó được đồng bộ hóa vào từng hồ sơ trong cài đặt và cập nhật nên không có bước cài đặt Skills Hub riêng biệt. Xác minh nó là có trong hồ sơ người điều phối nhạc của bạn:

hermes -p orchestrator skills list | grep kanban-orchestrator

Nếu bản sao đi kèm bị thiếu, hãy khôi phục nó cho cấu hình đó:

hermes -p orchestrator skills reset kanban-orchestrator --restore

Để có kết quả tốt nhất, hãy ghép nối nó với một cấu hình có bộ công cụ được giới hạn trong các hoạt động trên bo mạch (kanban, gateway, memory) để người điều phối thực sự không thể thực thi các tác vụ triển khai ngay cả khi nó cố gắng.

Trang tổng quan (GUI)

Lệnh /kanban CLI và dấu gạch chéo là đủ để chạy bảng một cách dễ dàng, nhưng bảng trực quan thường là giao diện phù hợp cho con người trong vòng lặp: phân loại, giám sát nhiều hồ sơ, đọc chuỗi nhận xét và kéo thẻ giữa các cột. Hermes cung cấp tính năng này dưới dạng plugin bảng điều khiển đi kèm tại plugins/kanban/ — không phải tính năng cốt lõi, không phải dịch vụ riêng biệt — theo mô hình được trình bày trong Mở rộng bảng điều khiển.

Mở nó bằng:

hermes kanban init      # one-time: create kanban.db if not already present
hermes dashboard        # "Kanban" tab appears in the nav, after "Skills"

Những gì plugin mang lại cho bạn

• A Kanban tab showing one column per status: triage, todo, ready, running, blocked, done (plus archived when the toggle is on).
  • triage is the parking column for rough ideas a specifier is expected to flesh out. Tasks created with hermes kanban create --triage (or via the Triage column's inline create) land here and the dispatcher leaves them alone until a human or specifier promotes them to todo / ready. Run hermes kanban specify <id> to have the auxiliary LLM expand a triage task into a concrete spec (title + body with goal, approach, acceptance criteria) and promote it to todo in one shot; --all sweeps every triage task at once. Configure which model runs the specifier under auxiliary.triage_specifier in config.yaml.
• Cards show the task id, title, priority badge, tenant tag, assigned profile, comment/link counts, a progress pill (N/M children done when the task has dependents), and "created N ago". A per-card checkbox enables multi-select.
• Per-profile lanes inside Running — toolbar checkbox toggles sub-grouping of the Running column by assignee.
• Live updates via WebSocket — the plugin tails the append-only task_events table on a short poll interval; the board reflects changes the instant any profile (CLI, gateway, or another dashboard tab) acts. Reloads are debounced so a burst of events triggers a single refetch.
• Drag-drop cards between columns to change status. The drop sends PATCH /api/plugins/kanban/tasks/:id which routes through the same kanban_db code the CLI uses — the three surfaces can never drift. Moves into destructive statuses (done, archived, blocked) prompt for confirmation. Touch devices use a pointer-based fallback so the board is usable from a tablet.
• Inline create — click + on any column header to type a title, assignee, priority, and (optionally) a parent task from a dropdown over every existing task. Creating from the Triage column automatically parks the new task in triage.
• Multi-select with bulk actions — shift/ctrl-click a card or tick its checkbox to add it to the selection. A bulk action bar appears at the top with batch status transitions, archive, and reassign (by profile dropdown, or "(unassign)"). Destructive batches confirm first. Per-id partial failures are reported without aborting the rest.
• Click a card (without shift/ctrl) to open a side drawer (Escape or click-outside closes) with:
  • Editable title — click the heading to rename.
  • Editable assignee / priority — click the meta row to rewrite.
  • Editable description — markdown-rendered by default (headings, bold, italic, inline code, fenced code, http(s) / mailto: links, bullet lists), with an "edit" button that swaps in a textarea. Markdown rendering is a tiny, XSS-safe renderer — every substitution runs on HTML-escaped input, only http(s) / mailto: links pass through, and target="_blank" + rel="noopener noreferrer" are always set.
  • Dependency editor — chip list of parents and children, each with an × to unlink, plus dropdowns over every other task to add a new parent or child. Cycle attempts are rejected server-side with a clear message.
  • Status action row (→ triage / → ready / → running / block / unblock / complete / archive) with confirm prompts for destructive transitions. For cards in the Triage column the row also exposes a ✨ Specify button that calls the auxiliary LLM (auxiliary.triage_specifier in config.yaml) to expand the one-liner into a concrete spec (title + body with goal, approach, acceptance criteria) and promote the task to todo. The same behaviour is reachable from the CLI (hermes kanban specify <id> / --all), from any gateway platform (/kanban specify <id>), and programmatically via POST /api/plugins/kanban/tasks/:id/specify.
  • Result section (also markdown-rendered), comment thread with Enter-to-submit, the last 20 events.
• Toolbar filters — free-text search, tenant dropdown (defaults to dashboard.kanban.default_tenant from config.yaml), assignee dropdown, "show archived" toggle, "lanes by profile" toggle, and a Nudge dispatcher button so you don't have to wait for the next 60 s tick.

Về mặt trực quan, mục tiêu là bố cục Tuyến tính / Kết hợp quen thuộc: chủ đề tối, tiêu đề cột có số lượng, dấu chấm trạng thái có màu, khối thuốc dành cho mức độ ưu tiên và đối tượng thuê. Plugin này chỉ đọc các biến thể CSS của chủ đề (--color-*, --radius, --font-mono, ...), do đó, nó sẽ tự động thay đổi giao diện với bất kỳ chủ đề trang tổng quan nào đang hoạt động.

Ngành kiến ​​​​trúc

GUI hoàn toàn là một lớp đọc qua-DB + ghi qua-kanban_db không có logic miền riêng:

┌────────────────────────┐      WebSocket (tails task_events)
│   React SPA (plugin)   │ ◀──────────────────────────────────┐
│   HTML5 drag-and-drop  │                                    │
└──────────┬─────────────┘                                    │
           │ REST over fetchJSON                              │
           ▼                                                  │
┌────────────────────────┐     writes call kanban_db.*        │
│  FastAPI router        │     directly — same code path      │
│  plugins/kanban/       │     the CLI /kanban verbs use      │
│  dashboard/plugin_api.py                                    │
└──────────┬─────────────┘                                    │
           │                                                  │
           ▼                                                  │
┌────────────────────────┐                                    │
│  ~/.hermes/kanban.db   │ ───── append task_events ──────────┘
│  (WAL, shared)         │
└────────────────────────┘

Bề mặt REST

Tất cả các tuyến được gắn trong /api/plugins/kanban/ và được bảo vệ bằng mã thông báo phiên tạm thời của bảng điều khiển:

Method	Path	Purpose
GET	/board?tenant=<name>&include_archived=…	Full board grouped by status column, plus tenants + assignees for filter dropdowns
GET	/tasks/:id	Task + comments + events + links
POST	/tasks	Create (wraps kanban_db.create_task, accepts triage: bool and parents: [id, …])
PATCH	/tasks/:id	Status / assignee / priority / title / body / result
POST	/tasks/bulk	Apply the same patch (status / archive / assignee / priority) to every id in ids. Per-id failures reported without aborting siblings
POST	/tasks/:id/comments	Append a comment
POST	/tasks/:id/specify	Run the triage specifier — auxiliary LLM fleshes out the task body and promotes it from triage to todo. Returns {ok, task_id, reason, new_title}; ok=false with a human-readable reason on "not in triage" / no aux client / LLM error is a 200, not a 4xx
POST	/links	Add a dependency (parent_id → child_id)
DELETE	/links?parent_id=…&child_id=…	Remove a dependency
POST	/dispatch?max=…&dry_run=…	Nudge the dispatcher — skip the 60 s wait
GET	/config	Read dashboard.kanban preferences from config.yaml — default_tenant, lane_by_profile, include_archived_by_default, render_markdown
WS	/events?since=<event_id>	Live stream of task_events rows

Mỗi trình xử lý là một trình bao bọc mỏng — plugin có ~700 dòng Python (bộ định tuyến + đuôi WebSocket + bộ xử lý hàng loạt + trình đọc cấu hình) và không thêm logic nghiệp vụ mới. Một trình trợ giúp _conn() nhỏ tự động khởi tạo kanban.db trong mỗi lần đọc và ghi, do đó, bản cài đặt mới sẽ hoạt động cho dù người dùng mở bảng thông tin trước, nhấn trực tiếp vào REST API hay chạy hermes kanban init.

Cấu hình bảng điều khiển

Bất kỳ khóa nào trong số này dưới dashboard.kanban trong ~/.hermes/config.yaml đều thay đổi mặc định của tab — plugin đọc chúng vào lúc tải thông qua GET /config:

dashboard:
  kanban:
    default_tenant: acme              # preselects the tenant filter
    lane_by_profile: true             # default for the "lanes by profile" toggle
    include_archived_by_default: false
    render_markdown: true             # set false for plain <pre> rendering

Mỗi phím là tùy chọn và quay trở lại mặc định được hiển thị.

###Mô hình bảo mật

Phần mềm trung gian xác thực HTTP của trang tổng quan bỏ qua rõ ràng /api/plugins/ — các tuyến plugin không được xác thực theo thiết kế vì trang tổng quan liên kết với localhost theo mặc định. Điều đó có nghĩa là bề mặt Kanban REST có thể truy cập được từ bất kỳ tiến trình nào trên máy chủ.

WebSocket thực hiện thêm một bước: nó yêu cầu mã thông báo phiên tạm thời của trang tổng quan dưới dạng tham số truy vấn ?token=… (trình duyệt không thể đặt Ủy quyền trên yêu cầu nâng cấp), khớp với mẫu được sử dụng bởi cầu nối PTY trong trình duyệt.

Nếu bạn chạy bảng điều khiển hermes --host 0.0.0.0, mọi tuyến plugin — bao gồm cả kanban — đều có thể truy cập được từ mạng. Đừng làm điều đó trên máy chủ dùng chung. Bảng chứa nội dung nhiệm vụ, nhận xét và đường dẫn không gian làm việc; kẻ tấn công tiếp cận các tuyến đường này sẽ có quyền truy cập đọc vào toàn bộ bề mặt cộng tác của bạn và cũng có thể tạo/chỉ định lại/lưu trữ các tác vụ.

Các tác vụ trong ~/.hermes/kanban.db có mục đích không xác định cấu hình (đó là nguyên tắc phối hợp). Nếu bạn mở bảng thông tin bằng hermes -p <profile> bảng thông tin, bảng vẫn hiển thị các tác vụ được tạo bởi bất kỳ hồ sơ nào khác trên máy chủ. Cùng một người dùng sở hữu tất cả hồ sơ, nhưng điều này cần biết nếu nhiều cá tính cùng tồn tại.

Cập nhật trực tiếp

task_events là một bảng SQLite chỉ nối thêm với một id đơn điệu. Điểm cuối WebSocket giữ id sự kiện được nhìn thấy lần cuối của mỗi khách hàng và đẩy các hàng mới khi chúng hạ cánh. Khi một loạt sự kiện xuất hiện, giao diện người dùng sẽ tải lại điểm cuối của bảng (rất rẻ) — đơn giản và chính xác hơn việc cố gắng vá trạng thái cục bộ khỏi mọi loại sự kiện. Chế độ WAL có nghĩa là vòng lặp đọc không bao giờ chặn các giao dịch yêu cầu BEGIN NGAY LẬP TỨC của người điều phối.

Mở rộng nó

Plugin sử dụng hợp đồng plugin trang tổng quan Hermes tiêu chuẩn — xem Mở rộng trang tổng quan để biết tham chiếu tệp kê khai đầy đủ, vị trí shell, vị trí trong phạm vi trang và SDK plugin. Các cột bổ sung, chrome thẻ tùy chỉnh, bố cục được lọc theo đối tượng thuê hoặc các thay thế tab.override đầy đủ đều có thể biểu thị được mà không cần phân tách plugin này.

Để tắt mà không xóa: thêm dashboard.plugins.kanban.enabled: false vào config.yaml (hoặc xóa plugins/kanban/dashboard/manifest.json).

Ranh giới phạm vi

GUI mỏng một cách có chủ ý. Mọi thứ mà plugin thực hiện đều có thể truy cập được từ CLI; plugin chỉ mang lại sự thoải mái cho con người. Tự động chỉ định, ngân sách, cổng quản trị và chế độ xem biểu đồ tổ chức vẫn là không gian của người dùng — cấu hình bộ định tuyến, plugin khác hoặc sử dụng lại tools/approval.py — chính xác như được liệt kê trong phần ngoài phạm vi của thông số thiết kế.

Tham chiếu lệnh CLI

Đây là bề mặt bạn (hoặc tập lệnh, cron, bảng điều khiển) sử dụng để điều khiển bảng. Các công nhân chạy bên trong bộ điều phối sử dụng kanban_* bề mặt công cụ cho các hoạt động giống nhau — CLI ở đây và các công cụ ở đó đều định tuyến qua kanban_db, vì vậy hai bề mặt phù hợp với nhau về mặt xây dựng.

hermes kanban init                                     # create kanban.db + print daemon hint
hermes kanban create "<title>" [--body ...] [--assignee <profile>]
                                [--parent <id>]... [--tenant <name>]
                                [--workspace scratch|worktree|dir:<path>]
                                [--priority N] [--triage] [--idempotency-key KEY]
                                [--max-runtime 30m|2h|1d|<seconds>]
                                [--skill <name>]...
                                [--json]
hermes kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived] [--json]
hermes kanban show <id> [--json]
hermes kanban assign <id> <profile>                    # or 'none' to unassign
hermes kanban link <parent_id> <child_id>
hermes kanban unlink <parent_id> <child_id>
hermes kanban claim <id> [--ttl SECONDS]
hermes kanban comment <id> "<text>" [--author NAME]

# Bulk verbs — accept multiple ids:
hermes kanban complete <id>... [--result "..."]
hermes kanban block <id> "<reason>" [--ids <id>...]
hermes kanban unblock <id>...
hermes kanban archive <id>...

hermes kanban tail <id>                                # follow a single task's event stream
hermes kanban watch [--assignee P] [--tenant T]        # live stream ALL events to the terminal
        [--kinds completed,blocked,…] [--interval SECS]
hermes kanban heartbeat <id> [--note "..."]            # worker liveness signal for long ops
hermes kanban runs <id> [--json]                       # attempt history (one row per run)
hermes kanban assignees [--json]                       # profiles on disk + per-assignee task counts
hermes kanban dispatch [--dry-run] [--max N]           # one-shot pass
        [--failure-limit N] [--json]
hermes kanban daemon --force                           # DEPRECATED — standalone dispatcher (use `hermes gateway start` instead)
        [--failure-limit N] [--pidfile PATH] [-v]
hermes kanban stats [--json]                           # per-status + per-assignee counts
hermes kanban log <id> [--tail BYTES]                  # worker log from ~/.hermes/kanban/logs/
hermes kanban notify-subscribe <id>                    # gateway bridge hook (used by /kanban in the gateway)
        --platform <name> --chat-id <id> [--thread-id <id>] [--user-id <id>]
hermes kanban notify-list [<id>] [--json]
hermes kanban notify-unsubscribe <id>
        --platform <name> --chat-id <id> [--thread-id <id>]
hermes kanban context <id>                             # what a worker sees
hermes kanban specify [<id> | --all] [--tenant T]      # flesh out a triage-column idea
        [--author NAME] [--json]                       #   into a full spec and promote to todo
hermes kanban gc [--event-retention-days N]            # workspaces + old events + old logs
        [--log-retention-days N]

Tất cả các lệnh cũng có sẵn dưới dạng lệnh gạch chéo trong CLI tương tác và trong cổng nhắn tin (xem /kanban gạch chéo lệnh bên dưới).

/kanban lệnh gạch chéo

Mọi động từ hermes kanban <action> cũng có thể truy cập được dưới dạng /kanban <action> — từ bên trong phiên hermes chat tương tác và từ bất kỳ nền tảng cổng nào (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Matter Extreme, email, SMS). Cả hai bề mặt đều gọi cùng một điểm vào hermes_cli.kanban.run_slash() sử dụng lại cây argparse hermes kanban, do đó, bề mặt đối số, cờ và định dạng đầu ra giống hệt nhau trên CLI, /kanban và hermes kanban. Bạn không cần phải rời khỏi cuộc trò chuyện để điều khiển bảng.

/kanban list
/kanban show t_abcd
/kanban create "write launch post" --assignee writer --parent t_research
/kanban comment t_abcd "looks good, ship it"
/kanban unblock t_abcd
/kanban dispatch --max 3
/kanban specify t_abcd                  # flesh out a triage one-liner into a real spec
/kanban specify --all --tenant engineering  # sweep every triage task in one tenant

Trích dẫn các đối số nhiều từ giống như cách bạn làm trên shell — run_slash phân tích phần còn lại của dòng bằng shlex.split, vì vậy "..." và '...' đều hoạt động.

Cách sử dụng giữa chừng: /kanban bỏ qua bộ bảo vệ tác nhân đang chạy

Cổng thường xếp hàng đợi các lệnh gạch chéo và tin nhắn của người dùng trong khi nhân viên vẫn đang suy nghĩ — đó là điều ngăn bạn vô tình bắt đầu lượt thứ hai trong khi lượt đầu tiên đang bay. /kanban được miễn trừ khỏi biện pháp bảo vệ này. Bảng tồn tại ở ~/.hermes/kanban.db, không ở trạng thái của tác nhân đang chạy, vì vậy đọc (list, show, context, tail, watch, stats, runs) và ghi (comment, unblock, block, sign, archive, create, link, …) đều được thực hiện ngay lập tức, thậm chí là giữa lượt.

Đây là toàn bộ ý nghĩa của sự tách biệt:

• Một nhân viên chặn máy ngang hàng → bạn gửi /kanban bỏ chặn t_abcd từ điện thoại của bạn và người điều phối sẽ chọn máy ngang hàng ở tích tắc tiếp theo. Worker bị chặn không bị gián đoạn - nó chỉ ngừng bị chặn.
• Bạn phát hiện ra một thẻ cần bối cảnh của con người → /kanban comment t_xyz "use the 2026, not 2025" nằm trên chuỗi tác vụ và lần chạy tiếp theo của tác vụ đó sẽ đọc nó trong kanban_show().
• Bạn muốn biết nhóm của mình đang làm gì mà không cần dừng người điều phối → /kanban list --mine hoặc /kanban stats kiểm tra bảng mà không cần chạm vào cuộc trò chuyện chính của bạn.

Tự động đăng ký trên /kanban create (chỉ cổng)

Khi bạn tạo một tác vụ từ cổng với /kanban create "...", cuộc trò chuyện ban đầu (nền tảng + id trò chuyện + id luồng) sẽ tự động được đăng ký với các sự kiện đầu cuối của tác vụ đó (đã hoàn thành, bị chặn, gave_up, bị lỗi, timed_out). Bạn sẽ nhận được một tin nhắn trở lại cho mỗi sự kiện đầu cuối — bao gồm dòng đầu tiên trong bản tóm tắt kết quả của nhân viên trên đã hoàn thành — mà không cần phải thăm dò ý kiến ​​hoặc ghi nhớ id nhiệm vụ.

you> /kanban create "transcribe today's podcast" --assignee transcriber
bot> Created t_9fc1a3  (ready, assignee=transcriber)
     (subscribed — you'll be notified when t_9fc1a3 completes or blocks)

… ~8 minutes later …

bot> ✓ t_9fc1a3 được người ghi lại hoàn thành
     chép lại 42 phút, lưu vào podcast/2026-05-04.md

Các đăng ký sẽ tự động xóa sau khi tác vụ đạt đến mức hoàn thành hoặc được lưu trữ. Nếu bạn tạo tập lệnh bằng --json (đầu ra của máy), tính năng tự động đăng ký sẽ bị bỏ qua — giả định là người gọi theo tập lệnh muốn quản lý đăng ký một cách rõ ràng thông qua /kanban notification-subscribe.

Cắt ngắn đầu ra trong tin nhắn

Nền tảng cổng có giới hạn độ dài tin nhắn thực tế. Nếu /kanban list, /kanban show hoặc /kanban tail tạo ra hơn ~3800 ký tự đầu ra, thì phản hồi sẽ bị cắt bớt bằng chân trang … (cắt ngắn; sử dụng \hermes kanban …` trong thiết bị đầu cuối của bạn để có đầu ra đầy đủ)`. Bề mặt CLI không có nắp như vậy.

Tự động hoàn thành

Trong CLI tương tác, gõ /kanban và nhấn Tab để duyệt qua danh sách lệnh con tích hợp sẵn (list, ls, show, create, sign, link, unlink, claim, comment, complete, block, unblock, archive, tail, dispatch, context, init, gc). Các động từ còn lại được liệt kê trong tham chiếu CLI ở trên (watch, stats, runs, log, người được giao, heartbeat, notify-subscribe, notify-list, notify-unsubscribe, daemon) cũng hoạt động — chúng chỉ chưa có trong danh sách gợi ý tự động hoàn thành.

Các mẫu cộng tác

Bảng hỗ trợ tám mẫu này mà không cần bất kỳ mẫu nguyên gốc mới nào:

Pattern	Shape	Example
P1 Fan-out	N siblings, same role	"research 5 angles in parallel"
P2 Pipeline	role chain: scout → editor → writer	daily brief assembly
P3 Voting / quorum	N siblings + 1 aggregator	3 researchers → 1 reviewer picks
P4 Long-running journal	same profile + shared dir + cron	Obsidian vault
P5 Human-in-the-loop	worker blocks → user comments → unblock	ambiguous decisions
P6 @mention	inline routing from prose	@reviewer look at this
P7 Thread-scoped workspace	/kanban here in a thread	per-project gateway threads
P8 Fleet farming	one profile, N subjects	50 social accounts
P9 Triage specifier	rough idea → triage → hermes kanban specify expands body → todo	"turn this one-liner into a spec'd task"

Để biết các ví dụ hoạt động của từng loại, hãy xem docs/hermes-kanban-v1-spec.pdf.

Sử dụng nhiều người thuê

Khi một nhóm chuyên gia phục vụ nhiều doanh nghiệp, hãy gắn thẻ từng nhiệm vụ với một đối tượng thuê:

hermes kanban create "monthly report" \
    --assignee researcher \
    --tenant business-a \
    --workspace dir:~/tenants/business-a/data/

Công nhân nhận được $HERMES_TENANT và không gian tên mà bộ nhớ của họ ghi theo tiền tố. Bảng, người điều phối và định nghĩa hồ sơ đều được chia sẻ; chỉ có dữ liệu được xác định phạm vi.

Thông báo cổng

Khi bạn chạy /kanban create … từ cổng (Telegram, Discord, Slack, v.v.), cuộc trò chuyện ban đầu sẽ tự động được đăng ký nhận tác vụ mới. Trình thông báo nền của cổng thăm dò task_events cứ sau vài giây và gửi một tin nhắn cho mỗi sự kiện đầu cuối (completed, blocked, gave_up, crashed, timed_out) cho cuộc trò chuyện đó. Các tác vụ đã hoàn thành cũng gửi dòng đầu tiên trong --result của nhân viên để bạn xem kết quả mà không cần phải /kanban show.

Bạn có thể quản lý đăng ký một cách rõ ràng từ CLI — hữu ích khi tập lệnh/công việc định kỳ muốn thông báo một cuộc trò chuyện không bắt nguồn từ đó:

hermes kanban notify-subscribe t_abcd \
    --platform telegram --chat-id 12345678 --thread-id 7
hermes kanban notify-list
hermes kanban notify-unsubscribe t_abcd \
    --platform telegram --chat-id 12345678 --thread-id 7

Một đăng ký sẽ tự động xóa khi tác vụ đạt đến mức ``hoàn thànhhoặcđược lưu trữ`; không cần dọn dẹp.

Chạy - một hàng cho mỗi lần thử

Nhiệm vụ là một đơn vị công việc hợp lý; run là một nỗ lực để thực hiện nó. Khi người điều phối xác nhận một tác vụ đã sẵn sàng, nó sẽ tạo một hàng trong task_runs và trỏ tasks.current_run_id vào đó. Khi nỗ lực đó kết thúc — đã hoàn thành, bị chặn, bị lỗi, hết thời gian chờ, không thành công, được lấy lại — hàng chạy sẽ đóng lại với kết quả và con trỏ của nhiệm vụ sẽ bị xóa. Một tác vụ được thực hiện ba lần sẽ có ba hàng task_runs.

Tại sao lại có hai bảng thay vì chỉ thay đổi nhiệm vụ: bạn cần lịch sử lần thử đầy đủ cho các lần khám nghiệm trong thế giới thực ("lần thử thứ hai của người đánh giá phải phê duyệt, lần thứ ba được hợp nhất") và bạn cần một nơi sạch sẽ để treo siêu dữ liệu cho mỗi lần thử — tệp nào đã thay đổi, thử nghiệm nào đã chạy, phát hiện nào người đánh giá đã ghi lại. Đó là những sự thật đang diễn ra, không phải sự thật về nhiệm vụ.

Các cuộc chạy cũng là nơi bàn giao có cấu trúc tồn tại. Khi một công nhân hoàn thành một nhiệm vụ (thông qua kanban_complete(...)), nó có thể vượt qua:

• tóm tắt (thông số công cụ) / --tóm tắt (CLI) — bàn giao của con người; tiếp tục chạy trốn; trẻ em ở hạ lưu nhìn thấy nó trong build_worker_context của chúng.
• siêu dữ liệu (thông số công cụ) / --metadata (CLI) — lệnh JSON dạng tự do đang chạy; trẻ em thấy nó được đăng nhiều kỳ cùng với bản tóm tắt.
• result (tool param) / --result (CLI) — dòng nhật ký ngắn nằm trên hàng tác vụ (trường kế thừa, được giữ để tương thích ngược).

Trẻ em ở hạ lưu đọc bản tóm tắt + siêu dữ liệu của lần chạy gần đây nhất cho mỗi phụ huynh. Nhân viên thử lại đọc các lần thử trước đó trong nhiệm vụ của chính họ (kết quả, tóm tắt, lỗi) để họ không lặp lại đường dẫn đã thất bại.

# What a worker actually does — a tool call, from inside the agent loop:
kanban_complete(
    summary="implemented token bucket, keys on user_id with IP fallback, all tests pass",
    metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
    result="rate limiter shipped",
)

Bạn có thể truy cập cùng một bước chuyển giao từ CLI khi bạn (con người) cần hoàn thành một nhiệm vụ mà nhân viên không thể thực hiện - ví dụ: một nhiệm vụ đã bị bỏ dở hoặc một nhiệm vụ bạn đã đánh dấu là thực hiện thủ công từ trang tổng quan:

hermes kanban complete t_abcd \
    --result "rate limiter shipped" \
    --summary "implemented token bucket, keys on user_id with IP fallback, all tests pass" \
    --metadata '{"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}'

# Xem lại lịch sử thử của một tác vụ đã thử lại:
Hermes Kanban chạy t_abcd
# # HỒ SƠ KẾT QUẢ ĐÃ BẮT ĐẦU
# 1 công nhân bị chặn 12s 2026-04-27 14:02
# → BLOCKED: cần quyết định về khóa giới hạn tỷ lệ
#2 công nhân hoàn thành 8m 2026-04-27 15:18
# → nhóm mã thông báo đã triển khai, các khóa trên user_id với dự phòng IP

Các lần chạy được hiển thị trên bảng thông tin (phần Lịch sử chạy trong ngăn kéo, một hàng màu cho mỗi lần thử) và trên API REST (GET /api/plugins/kanban/tasks/:id trả về mảng runs[]). PATCH /api/plugins/kanban/tasks/:id với {status: "done", tóm tắt, siêu dữ liệu} chuyển tiếp cả hai đến kernel, do đó, nút "đánh dấu xong" của trang tổng quan tương đương với CLI. Các hàng task_events mang run_id mà chúng thuộc về để giao diện người dùng có thể nhóm chúng theo lần thử và sự kiện completed nhúng bản tóm tắt dòng đầu tiên vào tải trọng của nó (giới hạn ở 400 ký tự) để trình thông báo cổng có thể hiển thị chuyển giao có cấu trúc mà không cần thực hiện chuyển giao khứ hồi SQL thứ hai.

Cảnh báo đóng hàng loạt. ``hermes kanban Complete a b c --summary Xbị từ chối — chuyển giao có cấu trúc được thực hiện trong mỗi lần chạy, vì vậy việc sao chép và dán cùng một bản tóm tắt vào N tác vụ hầu như luôn sai. Đóng hàng loạt *không có*--summary/--metadata` 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".

Các lần chạy được lấy lại từ các thay đổi trạng thái. Nếu bạn kéo một tác vụ đang chạy ra khỏi đang chạy trong bảng thông tin (quay lại sẵn sàng hoặc thẳng tới việc cần làm) hoặc lưu trữ một tác vụ vẫn đang chạy, quá trình chạy trong máy bay sẽ đóng lại với outcome='reclaimed' thay vì bị mồ côi. Hàng task_runs luôn ở trạng thái cuối khi tasks.current_run_id là NULL và ngược lại — giá trị bất biến đó giữ trên CLI, bảng điều khiển, bộ điều phối và trình thông báo.

Chạy tổng hợp cho các lần hoàn thành chưa bao giờ được xác nhận. Việc hoàn thành hoặc chặn một nhiệm vụ chưa bao giờ được xác nhận (ví dụ: một người đóng một nhiệm vụ sẵn sàng từ trang tổng quan bằng một bản tóm tắt hoặc người dùng CLI chạy hermes kanban Complete <ready-task> --summary X) sẽ hủy bỏ quá trình chuyển giao. Thay vào đó, kernel chèn một hàng chạy có thời lượng bằng 0 (started_at == kết thúc_at) mang theo tóm tắt / siêu dữ liệu / lý do để lịch sử thử vẫn hoàn tất. run_id của sự kiện completed / blocked trỏ vào hàng đó.

Làm mới ngăn trực tiếp. Khi luồng sự kiện WebSocket của trang tổng quan báo cáo các sự kiện mới cho tác vụ mà người dùng hiện đang xem, ngăn sẽ tự tải lại (thông qua bộ đếm sự kiện trên mỗi tác vụ được xâu chuỗi vào danh sách phụ thuộc useEffect của nó). Việc đóng và mở lại không còn cần thiết để xem hàng mới hoặc kết quả cập nhật của lượt chạy.

Khả năng tương thích về phía trước

Hai cột có thể rỗng trên tác vụ được dành riêng cho định tuyến quy trình làm việc v2: workflow_template_id (tác vụ này thuộc về mẫu nào) và current_step_key (bước nào trong mẫu đó đang hoạt động). Nhân v1 bỏ qua chúng để định tuyến nhưng cho phép khách hàng viết chúng, do đó bản phát hành v2 có thể thêm bộ máy định tuyến mà không cần di chuyển lược đồ khác.

Tham chiếu sự kiện

Mỗi quá trình chuyển đổi sẽ thêm một hàng vào task_events. Mỗi hàng mang một run_id tùy chọn để giao diện người dùng có thể nhóm các sự kiện theo lần thử. Các loại nhóm thành ba cụm để việc lọc rất dễ dàng (hermes kanban watch --kinds Completed,gave_up,timed_out):

Vòng đời (điều đã thay đổi về nhiệm vụ dưới dạng đơn vị logic):

Kind	Payload	When
created	{assignee, status, parents, tenant}	Task inserted. run_id is NULL.
promoted	—	todo → ready because all parents hit done. run_id is NULL.
claimed	{lock, expires, run_id}	Dispatcher atomically claimed a ready task for spawn.
completed	{result_len, summary?}	Worker wrote --result / --summary and task hit done. summary is the first-line handoff (400-char cap); full version lives on the run row. If complete_task is called on a never-claimed task with handoff fields, a zero-duration run is synthesized so run_id still points at something.
blocked	{reason}	Worker or human flipped the task to blocked. Synthesizes a zero-duration run when called on a never-claimed task with --reason.
unblocked	—	blocked → ready, either manually or via /unblock. run_id is NULL.
archived	—	Hidden from the default board. If the task was still running, carries the run_id of the run that was reclaimed as a side effect.

Chỉnh sửa (những thay đổi do con người thực hiện không phải là chuyển đổi):

Kind	Payload	When
assigned	{assignee}	Assignee changed (including unassignment).
edited	{fields}	Title or body updated.
reprioritized	{priority}	Priority changed.
status	{status}	Dashboard drag-drop wrote a status directly (e.g. todo → ready). Carries the run_id of the run that was reclaimed when dragging off running; otherwise run_id is NULL.

Đo từ xa của nhân viên (về quá trình thực thi, không phải về nhiệm vụ logic):

Kind	Payload	When
spawned	{pid}	Dispatcher successfully started a worker process.
heartbeat	{note?}	Worker called hermes kanban heartbeat $TASK to signal liveness during long operations.
reclaimed	{stale_lock}	Claim TTL expired without a completion; task goes back to ready.
crashed	{pid, claimer}	Worker PID no longer alive but TTL hadn't expired yet.
timed_out	{pid, elapsed_seconds, limit_seconds, sigkill}	max_runtime_seconds exceeded; dispatcher SIGTERM'd (then SIGKILL'd after 5 s grace) and re-queued.
spawn_failed	{error, failures}	One spawn attempt failed (missing PATH, workspace unmountable, …). Counter increments; task returns to ready for retry.
gave_up	{failures, error}	Circuit breaker fired after N consecutive spawn_failed. Task auto-blocks with the last error. Default N = 5; override via --failure-limit.

hermes kanban tail <id> hiển thị những thông tin này cho một tác vụ duy nhất. hermes kanban watch phát trực tiếp chúng trên toàn bảng.

Ngoài phạm vi

Kanban cố tình là một máy chủ duy nhất. ~/.hermes/kanban.db là một tệp SQLite cục bộ và bộ điều phối sẽ sinh ra các nhân viên trên cùng một máy. Việc chạy một bảng chia sẻ trên hai máy chủ không được hỗ trợ — không có nguyên tắc phối hợp nào cho "nhân viên X trên máy chủ A, nhân viên Y trên máy chủ B" và đường dẫn phát hiện sự cố giả định PID là máy chủ cục bộ. Nếu bạn cần nhiều máy chủ, hãy chạy một bảng độc lập cho mỗi máy chủ và sử dụng delegate_task/hàng đợi tin nhắn để kết nối chúng.

Thông số thiết kế

Thiết kế hoàn chỉnh — kiến ​​trúc, tính chính xác đồng thời, so sánh với các hệ thống khác, kế hoạch triển khai, rủi ro, câu hỏi mở — nằm trong docs/hermes-kanban-v1-spec.pdf. Hãy đọc điều đó trước khi nộp bất kỳ PR thay đổi hành vi nào.