Agentee · post-v1.0.0 · 17/06/2026

Dynamic Workflow + Share Output

Luồng & hướng triển khai: chuyển workflow hardcode thành engine động (markdown → JSON graph), output generic dùng chung & share giữa nhiều người. Minh hoạ bằng luồng proposal và luồng tạo báo cáo.

Engine: custom PG + BullMQ Format: markdown → graph Merge: partition + suggestion Phased, internal module

Tổng quan

Vấn đề: proposal flow đang hardcode 5 bước → không scale ra nhiều quy trình SME. Giải pháp: 1 engine generic + output dùng chung.

Bài toán: workflow + output

Layer: engine → output → collab

~80%

Collab đã build sẵn

Engine code đổi / thêm workflow

Ý tưởng cốt lõi

Một workflow = file markdown (người viết) → LLM compile + người duyệt → JSON graph (nodes/edges/conditions) cho engine chạy deterministic. Mọi workflow ghi output vào 1 container generic (JSONB + JSON Schema). Output đó share được giữa nhiều người qua per-user thread + suggestion. Proposal trở thành "workflow đầu tiên" chạy trên chính engine này.

Engine chạy một workflow thế nào

Vòng lặp: theo cursor → chạy node theo type → cập nhật state → đánh giá edges → node kế tiếp, tới khi hết.

Ctrl/Cmd + lăn chuột để zoom · kéo để pan · double-click để fit

ai_chat form approval automation output

4 loại node

Node type	Làm gì	Tái dùng từ
ai_chat	Turn hội thoại + extract typed slice vào state (2-pass)	Đúng cơ chế proposal hiện tại
form	Thu input có cấu trúc, validate bằng JSON Schema (ajv)	Mới (nhẹ)
approval	Tạo task cross-user, chờ duyệt, SLA/escalation	`proposal_tasks`
automation	Job nền: render file, gọi ERP… có retry	Export pipeline + ERP client

Markdown → JSON graph

Người/doanh nghiệp viết quy trình bằng markdown (dễ); LLM compile ra graph để engine enforce gate & branch deterministic. Markdown là lớp authoring, graph là lớp execution.

① Authoring — markdown (con người viết)

# Quy trình: Báo cáo tuần

## Bước 1 — Thu số liệu  (form)
- doanh thu, chi phí, số deal

## Bước 2 — Soạn các mục  (ai_chat)
- tóm tắt, phân tích, đề xuất

## Bước 3 — Duyệt nội bộ  (approval)
- người duyệt: manager

## Bước 4 — Xuất file  (automation)

② Execution — JSON graph (engine chạy)

{
  "slug": "weekly-report", "version": 1,
  "nodes": [
   {"id":"data_intake","type":"form"},
   {"id":"draft_sections","type":"ai_chat"},
   {"id":"internal_review","type":"approval",
     "assignRules":{"role":"manager"}},
   {"id":"compile_report","type":"automation"}
  ],
  "edges": [
   {"from":"internal_review","to":"compile_report",
     "when":"approved"},
   {"from":"internal_review","to":"draft_sections",
     "when":"rejected"}
  ]
}

Vì sao không để markdown chạy thẳng

Markdown thuần không enforce được gate/branch/state → LLM có thể bỏ bước. Compile ra graph giữ tính deterministic. Format authoring tái dùng đúng pattern SKILL.md (frontmatter + body) đã build trong Agent Skills runtime.

Ví dụ: Proposal = 1 workflow

5 bước proposal hiện tại được biểu diễn lại thành 1 definition. Toàn linear, node toàn ai_chat, bước cuối kèm automation render DOCX.

Ctrl/Cmd + lăn để zoom · kéo để pan

Migration an toàn

Engine chỉ thay phần cursor/transition; các satellite service (sections, suggestions, export, collaboration) vẫn đọc bảng cũ. Bật sau feature flag, chạy shadow tới khi parity rồi mới swap. proposalState tạm giữ nguyên ở proposal_workspaces để giảm blast radius.

Ví dụ: Tạo báo cáo = workflow khác

Cùng engine, định nghĩa khác: có node form, có approval gate quay vòng (reject → soạn lại), kết bằng automation. Chứng minh tính generic.

Ctrl/Cmd + lăn để zoom · kéo để pan

Đây là thước đo "generic" thật

Tạo workflow báo cáo từ 1 file markdown → review → activate → chạy end-to-end (kể cả duyệt cross-user) mà KHÔNG đổi 1 dòng engine code. Nếu làm được → engine generic thật; nếu phải sửa engine → chưa generic.

Share output giữa nhiều người

Output generic + chia sẻ: artifact dùng chung, conversation per-user, transcript share read-only, đóng góp qua handoff/suggestion.

Output: từ cố định → generic

Hiện tại — cố định

proposal_workspaces
  .proposalState JSONB
  // schema gắn cứng cho proposal

Hướng tới — generic

workflow_outputs
  instance_id, schema_ref,
  content JSONB
  // validate bằng JSON Schema
  // proposal HAY báo cáo đều dùng

Kiến trúc share: 1 artifact ↔ N session

Session A

owner A · agent as A

→

transcript
read-only

Session B

owner B · agent as B

OUTPUT / ARTIFACT dùng chung

content JSONB · lock_version serialize · suggestion accept/reject

Luồng share A → B

Ctrl/Cmd + lăn để zoom · kéo để pan

Vì sao per-user thread

B làm trong session riêng → agent luôn chạy bằng identity & ERP JWT của B → né leo thang quyền. Transcript của A chỉ read-only nên không có tool nào chạy "as A". Merge dùng partition + suggestion (đã build ~80%), không CRDT.

Hướng triển khai

Phased — các layer phụ thuộc nhau, không làm song song. Feature share ship độc lập được.

Layer	Nội dung	Trạng thái
L1 · Engine	Module nội bộ `packages/workflow-engine`: schema + JSON-graph interpreter + 4 node executor + markdown→graph compiler + approval queue. Validate bằng workflow báo cáo.	trên giấy
L2 · Output	Generalize `proposalState` + `proposal_sections` → `workflow_outputs` JSONB validate JSON Schema	semi-ready
L3 · Collab	Generalize partition-ownership + suggestion accept/reject cho mọi output	~80% built
Proposal mig.	Đưa proposal builder chạy trên engine sau feature flag (shadow → swap)	sau L1
Share feature	Per-user thread + read-only transcript + share gesture (ship độc lập)	cần relax unique index

Rủi ro cần canh

Engine: parity proposal với ~46 satellite service → engine chỉ giữ cursor/transition + feature flag + shadow run. Share: relax UNIQUE index uq_chat_sessions_active_proposal_erp có thể vỡ findOrCreateForChannel → audit canonical-session binding trước khi migrate. YAGNI: chưa npm package, chưa CRDT, chưa visual builder — graph-ready để hoãn rẻ.

Bước kế tiếp

Khi chốt: /ck:plan --tdd cho Layer 1 (engine) — kèm 2 report brainstorm 260617 + brainstorm 260610. Feature share có thể plan riêng, không chờ engine.