Kanban — Cộng tác hồ sơ đa tác nhân`> Bạn muốn xem hướng dẫn? Đọc Kanban tutorial - 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 từng 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

:

• Các đại lý điều khiển bo mạch 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ó; cấu hình 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 chuyển sang `Hermes kanban

. Xem How workers interact with the board 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ẽ nhìn 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 | |---|---|---| | Hình dạng | Cuộc gọi RPC (rẽ nhánh → tham gia) | Hàng đợi tin nhắn bền bỉ + máy trạng thái | | Phụ huynh | Chặn cho đến khi trẻ quay lại | Bắn và quên sau create ` | | Danh tính trẻ em | Đại lý phụ ẩn danh | Hồ sơ được đặt tên với bộ nhớ liên tục | | Khả năng tiếp tục | Không có - thất bại = thất bại | Chặn → bỏ chặn → chạy lại; tai nạn → đòi lại | | Con người trong vòng lặp | Không được hỗ trợ | Bình luận/bỏ chặn bất cứ lúc nào | | Đại lý theo nhiệm vụ | Một cuộc gọi = một đại lý phụ | N tác nhân trong suốt vòng đời của nhiệm vụ (thử lại, đánh giá, theo dõi) | | Đường mòn kiểm toán | Bị mất khi nén ngữ cảnh | Các hàng bền vững trong SQLite mãi mãi | | Phối hợp | Phân cấp (người gọi → callee) | Ngang hàng — mọi hồ sơ đều đọc/ghi bất kỳ tác vụ nào |

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 gốc 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 bối cảnh của tác nhân gốc.

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 — một hàng tác vụ độc lập với cơ sở dữ liệu SQLite, không gian làm việc riêng

thư mục và vòng lặp điều phối. Một lần cài đặt có thể có nhiều bảng (ví dụ: một cái cho mỗi dự án, kho lưu trữ hoặc tên miền); xem Boards (multi-project) bên dưới. Người dùng một dự án vẫn ở trên bảng default và không bao giờ nhìn thấy từ "board" bên ngoài phần tài liệu này.

• Nhiệm vụ — một hàng có tiêu đề, nội dung tùy chọn, một người được chuyển giao (tên hồ sơ), trạng thái ( `triage | todo | ready | running | blocked | done | archived

), không gian tên đối tượng thuê tùy chọn, khóa bình thường tùy chọn (khấu trừ để tự động hóa thử lại).

• Liên kết — Hàng task_links ghi lại phần phụ thuộc gốc → phần phụ thuộc con. Người điều phối khuyến mãi todo → ready khi tất cả phụ huynh đều là `done

.

• Nhận xét — giao thức giữa các tác nhân. Đại lý và con người thêm ý kiến; khi một công nhân được sinh ra (tái), nó sẽ đọc toàn bộ chuỗi nhận xét như một phần ngữ cảnh của nó.

• Không gian làm việc — thư mục mà nhân viên thao tác trong đó. Ba loại:

scratch (mặc định) — thư mục tmp mới trong

~/.Hermes/kanban/workspaces/<id/ ` (hoặc

~/.Hermes/kanban/boards/<slug/workspaces/<id/ trên các bảng không mặc định). **Đã xóa khi nhiệm vụ hoàn thành** — vết xước là tạm thời theo thiết kế, vì vậy thư mục sẽ bị xóa ngay khi nhân viên (hoặc Hermes kanban complete <id

) đánh dấu nhiệm vụ đã hoàn thành. Nếu bạn muốn giữ lại đầu ra của nhân viên, hãy sử dụng worktree: hoặc dir:<path thay thế. Lần đầu tiên một không gian làm việc sơ sài được tạo trong quá trình cài đặt, bộ điều phối sẽ ghi lại cảnh báo và phát ra sự kiện tip_scratch_workspace trên tác vụ (hiển thị qua `Hermes kanban show <id

).

dir:<path — một thư mục dùng chung hiện có (Hầm Obsidian, thư mục hoạt động thư, thư mục trên mỗi tài khoản). Phải là đường dẫn tuyệt đối. Các đường dẫn tương đối như dir:../tenants/foo/ bị từ chối khi gửi đi vì chúng sẽ giải quyết bất kỳ CWD nào mà người điều phối tình cờ có mặt, điều này không rõ ràng và là vectơ thoát cấp phó nhầm lẫn. Đường dẫn được tin cậy — đó là hộp của bạn, hệ thống tệp của bạn, nhân viên chạy với uid của bạn. Đây là mô hình mối đe dọa người dùng cục bộ đáng tin cậy; Kanban được thiết kế là một máy chủ duy nhất. Giữ nguyên khi hoàn thành.

worktree — một cây công việc git trong

.worktrees/<id/ cho các tác vụ mã hóa. Sử dụng worktree:<path để ghim đường dẫn đích chính xác. git worktree add ` phía công nhân tạo ra nó, sử dụng

--branch ` khi được cung cấp. Giữ nguyên khi hoàn thành.

• Người điều phối — một vòng lặp tồn tại lâu dài, cứ sau N giây (mặc định là 60): lấy lại các xác nhận quyền sở hữu cũ, lấy lại các công nhân bị lỗi (PID đã biến mất nhưng TTL chưa hết hạn), thúc đẩy các nhiệm vụ đã sẵn sàng, xác nhận nguyên tử, tạo ra các hồ sơ được chỉ định. Chạy bên trong cổng theo mặc định ( `kanban.dispatch_in_gateway: true

). Một người điều phối quét tất cả các bảng trên mỗi tích tắc; công nhân được sinh ra với Hermes_KANBAN_BOARD được ghim để họ không thể nhìn thấy các bảng khác. Sau khi kanban.failure_limit xuất hiện lỗi liên tiếp trên cùng một tác vụ (mặc định: 2), bộ điều phối sẽ tự động chặn tác vụ đó với lý do là lỗi cuối cùng — ngăn chặn việc xử lý các tác vụ có hồ sơ không tồn tại, không gian làm việc không thể gắn kết, v.v.

• Tenant — không gian tên chuỗi tùy chọn trong một bảng. Một nhóm chuyên gia có thể phục vụ nhiều doanh nghiệp (

--tenant business-a

) với khả năng cách ly dữ liệu theo đường dẫn không gian làm việc và tiền tố khóa bộ nhớ. Người thuê nhà là một bộ lọc mềm; bảng là ranh giới cách ly cứng.

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:

• DB SQLite riêng biệt trên mỗi bảng (

~/.Hermes/kanban/boards/<slug/kanban.db

).

• Tách riêng 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 môi trường 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

# Hard delete — 
`rm -rf
` the board dir. No recovery.
Hermes kanban boards 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. 
`default

.Sên được xác thực: chữ và số viết thường + dấu gạch nối + 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``Hermes dashboard
` → 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 

+ New board
` 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ỏ 
`current
` của CLI ra khỏi terminal 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 
`default

. Xác nhận rồi di chuyển
  bảng hướng dẫn 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
` để xác định 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 ra 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 [How workers interact with the board](#how-workers-interact-with-the-board).

``` bash

# 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. See the board (you)
Hermes kanban list
Hermes kanban stats

`
``Khi người điều phối nhận 
`t_abcd
` và tạo ra hồ sơ 
`researcher

, đ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).

``` yaml

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

`
``Ghi đè cờ cấu hình khi chạy 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). Nếu không có cổng đang chạy, các tác vụ 
`ready
` vẫn giữ 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 tạo
thời gian.

Việc chạy 
`Hermes kanban daemon
` dưới dạng 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)

``` bash

# 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:

``` bash
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ị`**Worker không chi ra 
`Hermes kanban

.** Khi bộ điều phối sinh ra một worker, nó đặt 
`Hermes_KANBAN_TASK=t_abcd
` trong env của con và var env đó 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 Python 
`kanban_db

, 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 
`Hermes kanban
` CLI.| Công cụ | Mục đích | Thông số bắt buộc |
|---|---|---|
| 
`kanban_show
` | Đọc tác vụ hiện tại (tiêu đề, nội dung, các lần thử trước, chuyển giao gốc, nhận xét, 
`worker_context
` được định dạng trước đầy đủ). Mặc định là id nhiệm vụ của env. | — |
| 
`kanban_list
` | Liệt kê các bản tóm tắt tác vụ với các bộ lọc cho 
`assignee

, 
`status

, 
`tenant

, khả năng hiển thị và giới hạn được lưu trữ. Dành cho người điều phối dàn nhạc khám phá công việc trên bảng. | — |
| 
`kanban_complete
` | Kết thúc với chuyển giao có cấu trúc 
`summary

 + 
`metadata

. | ít nhất một trong 
`summary
` / 
`result
` |
| 
`kanban_block
` | Nâng cao ý kiến ​​đầu vào của con người với 
`reason

. | 
`reason
` |
| 
`kanban_heartbeat
` | Tín hiệu sống động trong thời gian dài hoạt động. Tác dụng phụ thuần túy. | — |
| 
`kanban_comment
` | Nối một ghi chú bền vững vào chuỗi nhiệm vụ. |

task_id

, 
`body
` |
| 
`kanban_create
` | (Người điều phối) thực hiện các nhiệm vụ con với 
`assignee

, 
`parents
` tùy chọn, 
`skills

, v.v. | 
`title

, 
`assignee
` |
| 
`kanban_link
` | (Người dàn nhạc) thêm cạnh phụ thuộc 
`parent_id → child_id
` sau khi thực tế. | 
`parent_id

, 
`child_id
` |
| 
`kanban_unblock
` | (Người điều phối) di chuyển tác vụ bị chặn trở lại 
`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 dàn nhạc)" — 
`kanban_list

, 
`kanban_create

, 
`kanban_link

, 
`kanban_unblock
` và 
`kanban_comment
` về các tác 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-orchestrator

) là hồ sơ công nhân không phân bổ 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ì shell vào 
`Hermes kanban
``Ba lý do:
1. **Tính di động của phần cuối.** Các nhân viên 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, nơi 
`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ể chương trình phụ trợ đầu cuối.
2. **Không có tính dễ vỡ của trích dẫn shell.** Việc chuyển 

--metadata '\{"files": [...]}'
` 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 bình 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ó trừ khi cấu hình hoạt động kích hoạt rõ ràng bộ công cụ 
`kanban
` cho công việc của người điều phối. Nhân viên thực hiện nhiệm vụ do người điều phối sinh ra sẽ nhận được các công cụ trong phạm vi nhiệm vụ vì 
`Hermes_KANBAN_TASK
` đã được đặt; cấu hình bộ điều phối có được bề mặt định tuyến rộng hơn thông qua config. 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
` hướng dẫn 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=..., metadata=\{...})
` có chủ ý 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à 
`metadata
` là phần kết thúc
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:

``` json
{
  "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
`metadata

. 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êu rõ điều đó trong 
`summary
` và sử dụng 
`metadata
` để 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ânBất kỳ hồ sơ nào có thể thực hiện các tác 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 tại đó.
3. Gọi 
`kanban_heartbeat(note="...")
` vài phút một lần trong thời gian dài hoạt động. **Nếu công việc của bạn có thể kéo dài hơn 1 giờ, hãy gọi 
`kanban_heartbeat
` ít nhất mỗi giờ một lần** — người điều phối sẽ xác nhận lại các nhiệm vụ đã chạy qua 
`kanban.dispatch_stale_timeout_seconds
` (mặc định là 4 giờ) mà không có nhịp tim trong một giờ qua, với giả định rằng nhân viên đã gặp sự cố mà không dọn dẹp. Việc lấy lại là vô hại (nhiệm vụ sẽ quay trở lại 
`ready
` để gửi lại mà không có dấu tích của bộ đếm lỗi) nhưng bạn sẽ mất tiến trình của lần chạy hiện tại.
4. Hoàn thành với 
`kanban_complete(summary="...", metadata=\{...})
` hoặc 
`kanban_block(reason="...")
` nếu bị kẹt.

Cuộc gọi 
`kanban_complete
` / 
`kanban_block
` cuối cùng đó là một phần của công nhân
giao thức. Nếu tiến trình công nhân thoát ra với trạng thái 0 trong khi tác vụ vẫn đang được thực hiện
`running

, người điều phối coi đó là vi phạm giao thức, phát ra một
Sự kiện 
`protocol_violation
` và thay vào đó tự động chặn tác vụ ở lần đánh dấu tiếp theo
hồi sinh nó vào cùng một vòng lặp. Điều này thường có nghĩa là mô hình đã viết một
câu trả lời bằng văn bản thuần túy và thoát ra mà không sử dụng bề mặt công cụ Kanban.

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à sử dụng.
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 (
`researcher

, 
`writer

, 
`ops

,
v.v.):

``` bash
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 đó:

`bash
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, vì vậy, 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 
`translation

, một nhiệm vụ đánh giá cần 
`GitHub-code-review

, một công việc 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ừ tác nhân điều phối** (trường hợp thông thường - tác nhân định tuyến tác nhân này đến tác nhân khác), hãy sử dụng mảng 
`kanban_create
` của công cụ 
`skills

:

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

kanban_create(
    title="audit auth flow",
    assignee="reviewer",
    skills=["security-pr-audit", "GitHub-code-review"],
)

`
``**Từ con người (lệnh CLI / gạch chéo)**, lặp lại 

--skill
` cho mỗi người:

``` bash
Hermes kanban create "translate README to Japanese" \

    --assignee linguist \
    --skill translation

Hermes kanban create "audit auth flow" \
    --assignee reviewer \
    --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 — người điều phối phát ra một cờ 

--skills <name
` cho mỗi (và cho cờ tích hợp sẵn), do đó, nhân viên sinh ra khi tất cả chú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 trên hồ sơ của người được chuyển nhượng (chạy 
`Hermes skills list
` để 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 chuyển nhượng không xác định, vì vậy người điều phối phải căn cứ mọi thẻ trong các cấu hình 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:

``` bash
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 đó:

`bash
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 của bảng (
`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 gạch chéo và lệnh gạch chéo 

/kanban
` là đủ để chạy bảng mà không cần đầu, 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 [Extending the Dashboard](./extending-the-dashboard).

Mở nó bằng:

`bash
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- Tab **Kanban** hiển thị một cột cho mỗi trạng thái: 
`triage

, 
`todo

, 
`ready

, 
`running

, 
`blocked

, 
`done
` (cộng với 
`archived
` khi nút chuyển đổi được bật).

  - 
`triage
` là cột đỗ cho những ý tưởng thô. Theo mặc định (
`kanban.auto_decompose: true

), trình điều phối tự động chạy **trình giải mã** đối với các nhiệm vụ được đưa ra ở đây — hồ sơ người điều phối đọc ý tưởng sơ bộ, xem danh sách hồ sơ của bạn (có mô tả) và chuyển nhiệm vụ đó thành một biểu đồ nhỏ gồm các nhiệm vụ con được chuyển đến các chuyên gia phù hợp nhất. Nhiệm vụ ban đầu vẫn tồn tại với tư cách là nhiệm vụ gốc của mọi đứa trẻ nên người điều phối thức dậy để đánh giá mức độ hoàn thành khi mọi thứ kết thúc. Lật viên thuốc **Orchestration: Auto/Manual** ở đầu trang (hoặc đặt 
`kanban.auto_decompose: false

) để chuyển sang chế độ thủ công, trong đó các nhiệm vụ được phân loại vẫn được giữ nguyên cho đến khi bạn nhấp vào **⚗ Phân tách** trên thẻ hoặc chạy 
`Hermes kanban decompose <id

. Đối với các nhiệm vụ không cần phân bổ (hoặc đối với các thiết lập không có cấu hình người điều phối), nút **✨ Chỉ định** sẽ thực hiện viết lại thông số kỹ thuật cho một nhiệm vụ (tiêu đề + nội dung với mục tiêu, cách tiếp cận, tiêu chí chấp nhận) thông qua cùng một máy móc LLM. Xem [Auto vs Manual orchestration](#auto-vs-manual-orchestration) bên dưới.
- Thẻ hiển thị id nhiệm vụ, tiêu đề, huy hiệu ưu tiên, thẻ đối tượng thuê, hồ sơ được giao, số lượng nhận xét/liên kết, **thuốc tiến độ** (
`N/M
` trẻ em thực hiện khi nhiệm vụ có người phụ thuộc) và "đã tạo N trước". Hộp kiểm trên mỗi thẻ cho phép chọn nhiều.
- **Làn đường trên mỗi hồ sơ bên trong Đang chạy** — hộp kiểm trên thanh công cụ bật tắt việc phân nhóm phụ cột Đang chạy theo người được giao.
- **Cập nhật trực tiếp qua WebSocket** — plugin theo sau bảng 
`task_events
` chỉ gắn thêm trong khoảng thời gian thăm dò ngắn; bảng phản ánh các thay đổi ngay lập tức khi bất kỳ cấu hình nào (CLI, cổng hoặc tab trang tổng quan khác) hoạt động. Các lần tải lại sẽ bị hủy bỏ nên một loạt sự kiện sẽ kích hoạt một lần tải lại.
- **Kéo-thả** thẻ giữa các cột để thay đổi trạng thái. Việc thả sẽ gửi 
`PATCH /API/plugins/kanban/tasks/:id
` đi qua cùng một mã 
`kanban_db
` mà CLI sử dụng — ba bề mặt không bao giờ có thể trôi đi. Chuyển sang trạng thái hủy diệt (
`done

, 
`archived

, 
`blocked

) để xác nhận. Các thiết bị cảm ứng sử dụng phương pháp dự phòng dựa trên con trỏ để có thể sử dụng bảng từ máy tính bảng.
- **Tạo nội tuyến** — nhấp vào 

+
` trên bất kỳ tiêu đề cột nào để nhập tiêu đề, người được giao, mức độ ưu tiên và (tùy chọn) nhiệm vụ chính từ danh sách thả xuống trên mọi nhiệm vụ hiện có. Nhấn Enter để tạo tác vụ, Shift+Enter để chèn dòng mới vào trường tiêu đề hoặc Escape để hủy. Việc tạo từ cột Phân loại sẽ tự động đưa nhiệm vụ mới vào phân loại.
- **Chọn nhiều thao tác hàng loạt** — shift/ctrl-nhấp vào thẻ hoặc đánh dấu vào hộp kiểm của thẻ đó để thêm thẻ đó vào vùng chọn. Một thanh hành động hàng loạt xuất hiện ở trên cùng với các chuyển đổi trạng thái hàng loạt, lưu trữ và gán lại (bằng cách thả xuống hồ sơ hoặc "(bỏ gán)"). Lô phá hủy xác nhận đầu tiên. Lỗi một phần trên mỗi id được báo cáo mà không hủy bỏ phần còn lại.
- **CLIck một thẻ** (không cần shift/ctrl) để mở ngăn phụ (Escape hoặc CLIck-outside đóng) bằng:
  - **Tiêu đề có thể chỉnh sửa** — nhấp vào tiêu đề để đổi tên.
  - **Người được chuyển nhượng / mức độ ưu tiên có thể chỉnh sửa** — nhấp vào hàng meta để viết lại.
  - **Mô tả có thể chỉnh sửa** — được hiển thị theo mặc định (tiêu đề, in đậm, in nghiêng, mã nội tuyến, mã có rào chắn, liên kết 
`http(s)
` / 
`mailto:

, danh sách dấu đầu dòng), với nút "chỉnh sửa" có thể hoán đổi trong vùng văn bản. Kết xuất Markdown là một trình kết xuất nhỏ, an toàn XSS — mọi thay thế đều chạy trên đầu vào thoát HTML, chỉ các liên kết 
`http(s)
` / 
`mailto:
` đi qua và 
`target="_blank"

 + 
`rel="noopener noreferrer"
` luôn được đặt.
  - **Trình chỉnh sửa phụ thuộc** — danh sách chip cha mẹ và con cái, mỗi chip có 

×
` để hủy liên kết, cùng với danh sách thả xuống đối với mọi nhiệm vụ khác để thêm cha mẹ hoặc con mới. Các lần thử theo chu kỳ bị từ chối phía máy chủ với một thông báo rõ ràng.- **Hàng hành động trạng thái** (→ phân loại / → sẵn sàng / → chạy / chặn / bỏ chặn / hoàn thành / lưu trữ) với lời nhắc xác nhận về các chuyển đổi mang tính hủy diệt. Đối với các thẻ trong cột **Triage**, hàng cũng hiển thị hai hành động do LLM điều khiển: **⚗ Phân tách** chuyển nhiệm vụ thành biểu đồ gồm các nhiệm vụ con được định tuyến đến hồ sơ chuyên gia theo mô tả (đường dẫn do người điều phối điều khiển) và **✨ Specify** thực hiện viết lại thông số một nhiệm vụ. Phân tách quay trở lại quảng cáo theo kiểu chỉ định khi LLM quyết định rằng nhiệm vụ không được hưởng lợi từ việc phân xuất riêng, vì vậy đây là một tập hợp lớn nghiêm ngặt. Cả hai đều có thể truy cập được từ CLI (
`Hermes kanban decompose <id
` / 
`specify <id
` / 

--all

), từ bất kỳ nền tảng cổng nào (

/kanban decompose <id

) và theo chương trình thông qua 
`POST /API/plugins/kanban/tasks/:id/decompose
` và 

…/specify

. Định cấu hình các mô hình trong 
`auxiliary.kanban_decomposer
` và 
`auxiliary.triage_specifier
` trong 
`config.yaml

.
  - Phần kết quả (cũng được hiển thị đánh dấu), chuỗi nhận xét với Enter-to-submit, 20 sự kiện gần nhất.
- **Bộ lọc thanh công cụ** — tìm kiếm văn bản tự do, danh sách thả xuống của đối tượng thuê (mặc định là 
`dashboard.kanban.default_tenant
` từ 
`config.yaml

), danh sách thả xuống của người được giao, chuyển đổi "hiển thị đã lưu trữ", chuyển đổi "làn đường theo hồ sơ" và nút **Điều phối di chuyển** để bạn không phải đợi tích tắc 60 giây tiếp theo.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 chỉ đọc các biến thể CSS 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.

### Điều phối tự động và thủ công

Bảng Kanban có hai cách để xử lý tác vụ bạn thả vào cột Phân loại:

**Tự động (mặc định)** — 
`kanban.auto_decompose: true

. Bộ điều phối được nhúng vào cổng chạy **bộ giải mã** trên mỗi đánh dấu, được giới hạn bởi 
`kanban.auto_decompose_per_tick
` (3 tác vụ mặc định cho mỗi đánh dấu) để tải hàng loạt nhiệm vụ phân loại không làm tiêu tốn quá nhiều LLM phụ trợ. Trình phân tích đọc ý tưởng sơ bộ, xem hồ sơ đã cài đặt của bạn + mô tả của chúng và yêu cầu LLM tạo biểu đồ tác vụ JSON: nhiệm vụ nào sẽ xuất hiện, họ sẽ thực hiện nhiệm vụ nào và phụ thuộc vào nhiệm vụ nào. Nhiệm vụ phân loại ban đầu trở thành nhiệm vụ gốc của mỗi lá trong biểu đồ, do đó, nhiệm vụ này vẫn tồn tại cho đến khi toàn bộ biểu đồ hoàn thành — và sau đó được thăng hạng trở lại 
`ready
` để người được giao (hồ sơ người điều phối) có thể đánh giá mức độ hoàn thành và thêm nhiều nhiệm vụ hơn nếu công việc chưa hoàn thành. Đây là quy trình "bỏ một câu, bỏ đi".

**Hướng dẫn sử dụng** — 
`kanban.auto_decompose: false

. Nhiệm vụ phân loại vẫn được phân loại cho đến khi bạn hành động. Nhấp vào nút **⚗ Phân tách** trên thẻ, chạy 
`Hermes kanban decompose <id
` (hoặc 

--all

) hoặc sử dụng 

/kanban decompose <id
` từ một cuộc trò chuyện. Điều này phù hợp với hành vi tiền phân hủy của bảng, hữu ích khi bạn muốn toàn quyền kiểm soát những gì chạy khi nào.

Lật giữa hai chế độ từ viên thuốc **Dàn nhạc: Tự động/Thủ công** ở đầu trang kanban (ngọc lục bảo = Tự động, màu xám tắt tiếng = Thủ công) hoặc bằng cách chỉnh sửa trực tiếp 
`config.yaml

. Cả hai chế độ đều cùng tồn tại với 
`Hermes kanban specify
` — chế độ này vẫn có sẵn dưới dạng ghi lại thông số kỹ thuật một tác vụ khi bạn không muốn phân xuất.

Các quyết định định tuyến của trình phân tách phụ thuộc vào mô tả hồ sơ, là nhãn nguyên thủy cho mỗi hồ sơ mà bạn đặt với 
`Hermes profile create --description "..."

, 
`Hermes profile describe <name --text "..."

, 
`Hermes profile describe <name --auto
` (LLM-được tạo từ các kỹ năng + mô hình đã cài đặt của hồ sơ) hoặc trình chỉnh sửa theo hồ sơ của trang tổng quan trong bảng **Cài đặt điều phối** mở rộng. Những hồ sơ không có mô tả vẫn xuất hiện trong danh sách — chúng có thể định tuyến theo tên, chỉ là kém chính xác hơn. Bộ phân tách KHÔNG BAO GIỜ thực hiện một tác vụ con với 
`assignee=None

: khi LLM chọn một cấu hình không xác định, tác vụ con đó sẽ được chuyển đến 
`kanban.default_assignee
` (hoặc cấu hình mặc định hoạt động nếu điều đó không được đặt).

Các nút cấu hình (tất cả đều thuộc 
`kanban:
` trong 

~/.Hermes/config.yaml

):

| Chìa khóa | Mặc định | Mục đích |
|---|---|---|
| 
`auto_decompose
` | 
`true
` | Bộ điều phối tự động chạy bộ phân tích mỗi tích tắc. |
| 
`auto_decompose_per_tick
` | 
`3
` | Giới hạn số lần phân tách trên mỗi tích tắc của người điều phối. Vượt quá trì hoãn cho đánh dấu tiếp theo. |
| 
`orchestrator_profile
` | 

""
` | Hồ sơ sở hữu sự phân hủy. Trống = quay lại cấu hình mặc định đang hoạt động. |
| 
`default_assignee
` | 

""
` | Nơi nhiệm vụ con kết thúc khi LLM chọn một hồ sơ không xác định. Trống = quay lại mặc định hoạt động. |

Và hai khe LLM phụ:

| Chìa khóa | Mục đích |
|---|---|
| 
`auxiliary.kanban_decomposer
` | Mô hình tạo biểu đồ nhiệm vụ (được gọi bởi Decompose). Đặt 
`provider

/
`model
` để ghi đè mô hình trò chuyện chính. |
| 
`auxiliary.profile_describer
` | Mô hình tự động tạo mô tả hồ sơ (được gọi bởi 
`Hermes profile describe --auto

). |

### 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:`<!-- ascii-guard-ignore -->

`

┌────────────────────────┐      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)         │
└────────────────────────┘

`

<!-- ascii-guard-ignore-end -->

### Bề mặt REST

Tất cả các tuyến đường đượ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 trang tổng quan:| Phương pháp | Đường dẫn | Mục đích |
|---|---|---|
| 
`GET
` | 

/board?tenant=<name&include_archived=…
` | Bảng đầy đủ được nhóm theo cột trạng thái, cộng với người thuê + người được chuyển nhượng cho danh sách thả xuống bộ lọc |
| 
`GET
` | 

/tasks/:id
` | Nhiệm vụ + bình luận + sự kiện + liên kết |
| 
`POST
` | 

/tasks
` | Tạo (bọc 
`kanban_db.create_task

, chấp nhận 
`triage: bool
` và 
`parents: [id, …]

) |
| 
`PATCH
` | 

/tasks/:id
` | Trạng thái / người được chuyển nhượng / ưu tiên / chức danh / nội dung / kết quả |
| 
`POST
` | 

/tasks/bulk
` | Áp dụng cùng một bản vá (trạng thái / lưu trữ / người được chuyển nhượng / mức độ ưu tiên) cho mọi id trong 
`ids

. Lỗi trên mỗi id được báo cáo mà không hủy bỏ anh chị em |
| 
`POST
` | 

/tasks/:id/comments
` | Thêm một bình luận |
| 
`POST
` | 

/tasks/:id/specify
` | Chạy trình xác định phân loại - LLM phụ trợ bổ sung nội dung tác vụ và thúc đẩy nó từ 
`triage
` lên 
`todo

. Trả về 

\{ok, task_id, reason, new_title}

; 
`ok=false
` với lý do con người có thể đọc được là "không có trong phân loại" / không có máy khách aux / Lỗi LLM là 200, không phải 4xx |
| 
`POST
` | 

/tasks/:id/decompose
` | Chạy trình phân tách kanban - LLM phụ trợ tạo ra một biểu đồ nhiệm vụ và trình trợ giúp tạo ra các phần tử con + liên kết gốc + lật 
`triage → todo

. Trả về 

\{ok, task_id, reason, fanout, child_ids, new_title}

. Quy ước 200 lỗi LLM tương tự như 

/specify

. |
| 
`GET
` | 

/profiles
` | Liệt kê các hồ sơ đã cài đặt cùng với mô tả của chúng (được sử dụng bởi trình chỉnh sửa mô tả hồ sơ của trang tổng quan và bộ chọn điều phối). |
| 
`PATCH
` | 

/profiles/:name
` | Đặt hoặc xóa mô tả của hồ sơ (do người dùng tạo - 
`description_auto: false

). Trả về 

\{ok, profile, description}

. |
| 
`POST
` | 

/profiles/:name/describe-auto
` | Tạo mô tả cho hồ sơ thông qua 
`auxiliary.profile_describer

. Kiên trì với 
`description_auto: true
` để bảng điều khiển có thể hiển thị huy hiệu "đánh giá". |
| 
`GET
` | 

/orchestration
` | Đọc cài đặt điều phối kanban (
`orchestrator_profile

, 
`default_assignee

, 
`auto_decompose

) cùng với các giá trị hiệu quả *đã giải quyết* sau khi dự phòng. |
| 
`PUT
` | 

/orchestration
` | Cập nhật một hoặc nhiều trong số ba phím phối hợp trong 
`config.yaml

. Xác thực rằng tên hồ sơ không trống thực sự tồn tại. |
| 
`POST
` | 

/links
` | Thêm phần phụ thuộc (
`parent_id
` → 
`child_id

) |
| 
`DELETE
` | 

/links?parent_id=…&child_id=…
` | Xóa phần phụ thuộc |
| 
`POST
` | 

/dispatch?max=…&dry_run=…
` | Đẩy người điều phối — bỏ qua 60 giây chờ đợi |
| 
`GET
` | 

/config
` | Đọc các tùy chọn 
`dashboard.kanban
` từ 
`config.yaml
` — 
`default_tenant

, 
`lane_by_profile

, 
`include_archived_by_default

, 
`render_markdown
` |
| 
`WS
` | 

/events?since=<event_id
` | Phát trực tiếp các hàng 
`task_events
` |

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
` trên 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 API REST 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 trong 
`dashboard.kanban
` trong 

~/.Hermes/config.yaml
` đều thay đổi mặc định của tab — plugin sẽ đọc chúng khi tải thông qua 
`GET /config

:

``` yaml
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 [explicitly skips XPROTECTX342XPROTECTX](./extending-the-dashboard#backend-API-routes) — 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 làm tham số truy vấn 

?token=…
` (trình duyệt không thể đặt 
`Authorization
` theo 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 
`Hermes dashboard --host 0.0.0.0

, mọi tuyến plugin — bao gồm 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 nhiệm 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 dashboard

, bảng vẫn hiển thị các tác vụ được tạo bởi bất kỳ cấu hình 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à bảng SQLite chỉ nối thêm với 
`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 IMMEDIATE
` của người điều phối.

### Mở rộng nó

Plugin sử dụng hợp đồng plugin bảng điều khiển Hermes tiêu chuẩn - xem [Extending the Dashboard](./extending-the-dashboard) để biết tham chiếu bảng 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 sơ đồ 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ông nhân chạy bên trong bộ điều phối sử dụng 
`kanban_*
` [tool surface](#how-workers-interact-with-the-board) 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|worktree:<path|dir:<path]
                                [--branch <name]
                                [--priority N] [--triage] [--idempotency-key KEY]
                                [--max-runtime 30m|2h|1d|<seconds]
                                [--max-retries N]
                                [--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 [XPROTECTX358XPROTECTX slash command](#kanban-slash-command) bên dưới).
--max-retries
` là chức năng ghi đè ngắt mạch theo nhiệm vụ dành cho người điều phối. 

--max-retries 1
` chặn tác vụ trong lần thử không thành công đầu tiên, trong khi 

--max-retries 3
` cho phép thử lại hai lần và chặn ở lần thử thứ ba. Bỏ qua nó để sử dụng 
`kanban.failure_limit
` từ 
`config.yaml

, sau đó là mặc định tích hợp.

## Lệnh gạch chéo 

/kanban
` {#kanban-slash-command}

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, Mattermost, 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 thực hiện trên một shell - 
`run_slash
` phân tích phần còn lại của dòng bằng 
`shlex.split

, vì vậy cả 

"..."
` và 

'...'
` đều hoạt động.

### Mức sử dụng giữa chừng: 

/kanban
` bỏ qua trình 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
` rõ ràng được miễn khỏi phần bảo vệ này.** Bảng hoạt động ở 

~/.Hermes/kanban.db

, không ở trạng thái của tác nhân đang chạy, vì vậy có nội dung là (
`list

, 
`show

, 
`context

, 
`tail

, 
`watch

, 
`stats

, 
`runs

) và ghi (
`comment

, 
`unblock

, 
`block

, 
`assign

, 
`archive

, 
`create

, 
`link

, …) tất cả đều được thực hiện ngay lập tức, thậm chí ở 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 unblock t_abcd
` từ điện thoại của mình 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 một thẻ cần bối cảnh của con người → 

/kanban comment t_xyz "use the 2026 schema, not 2025"
` sẽ xuất hiện 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 bằng 

/kanban create "…"

, cuộc trò chuyện ban đầu (nền tảng + id trò chuyện + id chuỗi) sẽ tự động được đăng ký với các sự kiện đầu cuối của tác vụ đó (
`completed

, 
`blocked

, 
`gave_up

, 
`crashed

, 
`timed_out

). Bạn sẽ nhận lại một tin nhắn 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 
`completed
` — 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 completed by transcriber
     transcribed 42 minutes, saved to podcast/2026-05-04.md

`
``Đăng ký tự động xóa sau khi tác vụ đạt đến 
`done
` hoặc 
`archived

. 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 notify-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 

… (truncated; use \
`Hermes kanban …\
` in your terminal for full output)

. Bề mặt CLI không có nắp như vậy.

### Tự động hoàn thành

Trong CLI tương tác, nhập 

/kanban 
` và nhấn Tab để duyệt qua danh sách lệnh phụ tích hợp sẵn (
`list

, 
`ls

, 
`show

, 
`create

, 
`assign

, 
`link

, 
`unlink

, 
`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 tài liệu tham khảo CLI ở trên (
`watch

, 
`stats

, 
`runs

, 
`log

, 
`assignees

, 
`heartbeat

, 
`notify-subscribe

, 
`notify-list

, 
`notify-unsubscribe

, 
`daemon

) cũng hoạt động — chỉ là chúng 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:

| Mẫu | Hình dáng | Ví dụ |
|---|---|---|
| **Quạt ra P1** | N anh chị em, cùng vai trò | "nghiên cứu 5 góc song song" |
| **Đường ống P2** | chuỗi vai trò: trinh sát → biên tập viên → nhà văn | họp ngắn gọn hàng ngày |
| **P3 Bỏ phiếu / số đại biểu** | N anh chị em + 1 tập hợp | 3 nhà nghiên cứu → 1 người đánh giá chọn |
| **P4 Tạp chí dài** | cùng một hồ sơ + chia sẻ thư mục + cron | Hầm Obsidian |
| **P5 Con người trong vòng lặp** | khối công nhân → nhận xét của người dùng → bỏ chặn | quyết định mơ hồ |
| **P6 

@mention

** | định tuyến nội tuyến từ văn xuôi |

@reviewer look at this
` |
| **P7 Không gian làm việc trong phạm vi luồng** |

/kanban here
` trong một chủ đề | chủ đề cổng cho mỗi dự án |
| **P8 Nuôi theo hạm đội** | một hồ sơ, N đối tượng | 50 tài khoản xã hội |
| **Công cụ xác định phân loại P9** | ý tưởng thô → 
`triage
` → 
`Hermes kanban specify
` mở rộng cơ thể → 
`todo
` | "biến câu nói này thành một nhiệm vụ cụ thể" |

Để 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ê:

``` bash
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à vùng 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ổngKhi 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

) tới cuộc trò chuyện đó. Các tác vụ đã hoàn thành cũng gửi dòng đầu tiên 

--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ừ đó:

``` bash
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

`
``Đăng ký sẽ tự động xóa sau khi tác vụ đạt đến 
`done
` hoặc 
`archived

; 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 yêu cầu 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 
`outcome
` và con trỏ của nhiệm vụ sẽ xóa. Tác vụ được thử ba lần 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:
- 
`summary
` (thông số công cụ) / 

--summary
` (CLI) — chuyể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.
- 
`metadata
` (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
` (thông số công cụ) / 

--result
` (CLI) — dòng nhật ký ngắn nằm trên hàng nhiệm vụ (trường kế thừa, được giữ lại để so sánh 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:

``` bash
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}'

# Review the attempt history on a retried task:
Hermes kanban runs t_abcd
#   #  OUTCOME       PROFILE           ELAPSED  STARTED
#   1  blocked       worker               12s  2026-04-27 14:02
#        → BLOCKED: need decision on rate-limit key
#   2  completed     worker                8m   2026-04-27 15:18
#        → implemented token bucket, keys on user_id with IP fallback

`
``Các lần chạy được hiển thị trên bảng điều khiển (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", summary, metadata}
` chuyển tiếp cả hai đến hạt nhân, 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 bằng cách thử và sự kiện 
`completed
` nhúng bản tóm tắt dòng đầu tiên vào trọng tải 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 đi khứ hồi SQL thứ hai.

**Thông báo đóng hàng loạt.** 
`Hermes kanban complete a b c --summary X
` bị từ chối — chuyển giao có cấu trúc được thực hiện trong mỗi lần chạy, do đó, việc sao chép 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 đối với 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 
`running
` trong bảng điều khiển (quay lại 
`ready
` hoặc thẳng tới 
`todo

) hoặc lưu trữ một tác vụ vẫn đang chạy, quá trình chạy trên 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 — bất biến đó giữ trên CLI, bảng thông tin, bộ điều phối và trình thông báo.**Chạy tổng hợp cho những 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ụ 
`ready
` từ trang tổng quan bằng một bản tóm tắt hoặc một 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 đó, hạt nhân chèn một hàng chạy có thời lượng bằng 0 (
`started_at == ended_at

) mang theo tóm tắt/siêu dữ liệu/lý do để lịch sử thử vẫn hoàn tất. 
`completed
` / 
`blocked
` của sự kiện 
`run_id
` 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

). 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 
`tasks
` được dành riêng cho định tuyến quy trình làm việc v2: 
`workflow_template_id
` (mẫu mà tác vụ này thuộc về) 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 để UI có thể nhóm các sự kiện bằng cách thử. Nhóm các loại thành ba cụm nên 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):

| Loại | Tải trọng | Khi nào |
|---|---|---|
| 
`created
` | 

\{assignee, status, parents, tenant}
` | Đã chèn tác vụ. 
`run_id
` là 
`NULL

. |
| 
`promoted
` | — |

todo → ready
` vì tất cả phụ huynh đều đánh 
`done

. 
`run_id
` là 
`NULL

. |
| 
`claimed
` | 

\{lock, expires, run_id}
` | Người điều phối đã xác nhận nguyên tắc nhiệm vụ 
`ready
` để sinh sản. |
| 
`completed
` | 

\{result_len, summary?}
` | Công nhân đã viết 

--result
` / 

--summary
` và nhiệm vụ nhấn 
`done

. 
`summary
` là chuyển giao dòng đầu tiên (giới hạn 400 ký tự); phiên bản đầy đủ tồn tại trên hàng chạy. Nếu 
`complete_task
` được gọi trong một nhiệm vụ chưa bao giờ được xác nhận với các trường chuyển giao, thì quá trình chạy có thời lượng bằng 0 sẽ được tổng hợp để 
`run_id
` vẫn trỏ vào thứ gì đó. |
| 
`blocked
` | 

\{reason}
` | Công nhân hoặc con người chuyển nhiệm vụ sang 
`blocked

. Tổng hợp quá trình chạy có thời lượng bằng 0 khi được gọi trên một tác vụ chưa từng được xác nhận với 

--reason

. |
| 
`unblocked
` | — |

blocked → ready

, theo cách thủ công hoặc thông qua 

/unblock

. 
`run_id
` là 
`NULL

. |
| 
`archived
` | — | Ẩn khỏi bảng mặc định. Nếu tác vụ vẫn đang chạy, hãy mang 
`run_id
` của lần chạy đã được thu hồi dưới dạng tác dụng phụ. |`**Chỉnh sửa** (những thay đổi do con người thực hiện không phải là chuyển đổi):

| Loại | Tải trọng | Khi nào |
|---|---|---|
| 
`assigned
` | 

\{assignee}
` | Người được chuyển nhượng đã thay đổi (bao gồm cả việc hủy chuyển nhượng). |
| 
`edited
` | 

\{fields}
` | Đã cập nhật tiêu đề hoặc nội dung. |
| 
`reprioritiZed
` | 

\{priority}
` | Ưu tiên đã thay đổi. |
| 
`status
` | 

\{status}
` | Kéo thả bảng điều khiển đã viết trạng thái trực tiếp (ví dụ: 
`todo → ready

). Mang 
`run_id
` của lần chạy đã được thu hồi khi kéo 
`running

; nếu không thì 
`run_id
` là 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):| Loại | Tải trọng | Khi nào |
|---|---|---|
| 
`spawned
` | 

\{pid}
` | Người điều phối đã khởi động thành công quy trình công nhân. |
| 
`heartbeat
` | 

\{note?}
` | Công nhân gọi 
`Hermes kanban heartbeat $TASK
` để báo hiệu sự hoạt động trong thời gian dài hoạt động. |
| 
`reclaimed
` | 

\{stale_lock}
` | Yêu cầu TTL đã hết hạn mà không hoàn thành; nhiệm vụ quay trở lại 
`ready

. |
| 
`crashed
` | 

\{pid, claimer}
` | Công nhân PID không còn sống nhưng TTL vẫn chưa hết hạn. |
| 
`timed_out
` | 

\{pid, elapsed_seconds, limit_seconds, sigkill}
` | Đã vượt quá 
`max_runtime_seconds

; người điều phối SIGTERM'd (sau đó là SIGKILL'd sau 5 giây) và xếp hàng lại. |
| 
`stale
` | 

\{elapsed_seconds, last_heartbeat_at, heartbeat_age_seconds, timeout_seconds, pid, terminated}
` | Tác vụ chạy lâu hơn 
`kanban.dispatch_stale_timeout_seconds
` (mặc định 4 giờ) VÀ không có 
`kanban_heartbeat
` nào đến trong giờ qua. Bộ điều phối SIGTERM đã chọn nhân viên lưu trữ cục bộ (nếu có), đặt lại tác vụ thành 
`ready
` để gửi lại. KHÔNG đánh dấu vào bộ đếm lỗi (cũ là phát hiện sự vắng mặt của người điều phối, không phải lỗi của nhân viên). Công nhân vận hành trong thời gian dài nên gọi 
`kanban_heartbeat
` ít nhất mỗi giờ một lần để tránh điều này. |
| 
`respawn_guarded
` | 

\{reason}
` | Người điều phối đã từ chối thực hiện lại nhiệm vụ đã sẵn sàng này trong tích tắc này. Lý do: 
`blocker_auth
` (lỗi lần cuối là lỗi hạn ngạch/auth/429 — đợi cửa sổ tốc độ đặt lại), 
`recent_success
` (lần chạy hoàn tất diễn ra trong giờ qua — chờ xem xét trước khi chạy lại), 
`active_pr
` (URL GitHub PR xuất hiện trong nhận xét gần đây — nhân viên trước đó đã mở PR). Nhiệm vụ vẫn ở 
`ready

; tích tắc tiếp theo sẽ có cơ hội sinh sản khác. Nếu tình trạng cơ bản vẫn tiếp diễn, bộ ngắt mạch 
`consecutive_failures
` thông thường sẽ tự động chặn thông qua 
`gave_up
` sau lỗi 
`failure_limit

. |
| 
`spawn_failed
` | 

\{error, failures}
` | Một lần sinh sản không thành công (thiếu PATH, không thể đếm được không gian làm việc,…). Số lượt truy cập tăng; nhiệm vụ quay trở lại 
`ready
` để thử lại. |
| 
`protocol_violation
` | 

\{pid, claimer, exit_code}
` | Worker đã thoát thành công trong khi tác vụ vẫn là 
`running

, thường là do nó trả lời mà không gọi 
`kanban_complete
` hoặc 
`kanban_block

. Bộ điều phối cũng phát ra 
`gave_up
` và tự động chặn ngay lập tức thay vì thử lại. |
| 
`gave_up
` | 

\{failures, effective_limit, limit_source, error}
` | Bộ ngắt mạch kích hoạt sau N lần thử không thành công liên tiếp. Tự động chặn tác vụ với lỗi cuối cùng. Giới hạn hiệu quả được giải quyết dưới dạng nhiệm vụ 
`max_retries

, sau đó là bộ điều phối 
`failure_limit
` / 
`kanban.failure_limit

, sau đó là mặc định tích hợp. |``Hermes kanban tail <id
` hiển thị những thông tin này cho một tác vụ. 
`Hermes kanban watch
` truyền phát chúng trên toàn bo mạch.

## 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 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ở — có 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.