Quy trinh tac nhan du an can tach mat phang dieu khien va thuc thi cuc bo
Cac he thong tac nhan du an thuong bi mo ta nhu mot dong viec don gian: may chu gui nhiem vu, runtime cuc bo chay cong cu, roi tra ket qua. Cach mo ta do che khuat nhung bang chung can co de mot nhom tin rang dung tac nhan, dung phien ban ky nang, dung dau vao da duoc phe duyet, va dung ket qua da quay lai dung hien vat. Bai bao nay nghien cuu hai kho ma nguon bo sung cho nhau: nk304 lam mat phang dieu khien du an, con personal-work-agent lam mat phang thuc thi cuc bo. Bang chung tu mo hinh, dich vu, schema, tai lieu, kiem thu va cac nguon ngoai cho thay kien truc dung khong nen dua vao socket truc tiep hay log cuc bo rieng le. Dong gop cua bai la Workflow Control Ledger gom sau chang: dinh nghia tac nhan, tiep nhan ky nang curated, quan sat cai dat, rang buoc dau vao da phe duyet, tao case thuc thi cuc bo, va callback ket qua. Mo hinh nay lam ro diem manh hien co, dong thoi gioi han yeu sach khi test pending-sync dang bi chan va khi integrityHash chua duoc xac minh trong duong cai dat.
Gioi thieu
Khi mot nen tang du an muon dung tac nhan AI tren may nguoi dung, cau hoi kien truc khong chi la ket noi duoc khong . He thong phai biet dinh nghia tac nhan nao dang co hieu luc, bo ky nang nao duoc phe duyet, runtime cuc bo nao da cai dung phien ban, hien vat dau vao nao da duoc duyet, va ket qua nao quay lai dung workflow. Tai lieu nk304 ghi ro rang nk304 giu project agents, curated skill metadata, workflow stages, workflow runs, artifacts, per-user local install state va context reads, trong khi personal-work-agent van la local execution plane [[cite:nkProjectDoc]].
Ben local, tai lieu Project Agent Runtime mo ta mot runtime luu ProjectAgentDefinition, cai dat curated skills, xu ly project_workflow_stage_execute va bao cao trang thai cai dat/ket qua ve nk304 [[cite:pwaRuntimeDoc]]. Day la mot thiet ke split-plane: cloud control plane dieu phoi trang thai chia se, local execution plane giu quyen truy cap file, cong cu va moi truong rieng cua nguoi dung. Tu goc nhin local-first, su hien dien cua cloud khong tu dong lam mat gia tri cuc bo; van de la bang chung nao cho thay local runtime that su dang thuc thi dung ranh gioi [[cite:localFirst]].
Cau hoi nghien cuu cua bai bao la: mot workflow project-agent nen tach control, install-state, artifact approval va local execution evidence giua hosted workspace va user-local agent runtime nhu the nao? Dong gop la Workflow Control Ledger gom sau chang. Khac voi mot paper truoc ve outbound authenticated local-agent channels [[cite:graphOutbound]], bai nay khong tap trung vao zero-inbound transport. Khac voi ledger handoff trong workspace da tac nhan [[cite:graphHandoff]], bai nay thu hep vao lifecycle cua project workflow: tu dinh nghia den callback ket qua.
Thong diep trung tam la: workflow tac nhan du an khong nen duoc chung minh bang so lan emit socket, so trang thai local, hay so endpoint. No can mot chuoi bang chung lien ket dinh nghia, acquisition, install observation, input approval, local case, va result callback. Neu mot chang yeu, claim cong khai phai dung lai o chang do.
Phuong phap
Phuong thuc nghien cuu la conceptual synthesis dua tren inspect workspace. Toi doc tai lieu du an, model SQLModel, enum, TypeScript shared contracts, service logic, endpoint, local agent model, onboarding sync, pending sync, review push, document pipeline, sync payload models va HMAC helper. Toi cung chay mot bo test cuc hep lien quan den onboarding va document pipeline; bon test pass, nhung hai test pending-sync duoc chon khong collect duoc vi import OutboundMessage khong ton tai trong checkout hien tai [[cite:pwaFocusedRun,pwaBlockedRun]].
Graph research duoc dung de tranh lap de tai va tim ngu canh. Ket qua gan nhat gom mot paper ve outbound local-agent transport va mot paper ve handoff traceability [[cite:graphOutbound,graphHandoff]]. Cac nguon ngoai chi duoc dung lam khung dien giai: SQLite cho local embedded state [[cite:sqliteUses]], Socket.IO cho gioi han cua live delivery [[cite:socketDelivery]], Git clone/checkout cho curated skill acquisition [[cite:gitClone,gitCheckout]], NIST/OWASP cho claim governance va agent risk [[cite:nistAI,nistSSDF,owaspLLM]], W3C PROV cho cach noi entity-activity-agent thanh provenance graph [[cite:w3cProv]].
Moi khang dinh chinh duoc gan vao claim ledger. Khang dinh fact phai dua vao source da doc day du hoac computation/test record. Khang dinh inference duoc danh dau ro la suy luan tu nhieu nguon. Equation 1 tom tat nguyen tac calib claim: gia tri claim cong khai bang chang yeu nhat da duoc xac minh trong chuoi workflow.
Claim workflow = min(D definition , A acquisition , O observation , I input , C case , R result )
Bang chung tu mat phang dieu khien
nk304 co mot data model ro cho project-agent workflow. Model ProjectCuratedSkill luu skill id, source type, source URI, version, pinned revision, integrity hash va capabilities. ProjectAgent luu role, execution mode, fixed prompt, pinned/allowed skill ids, default engine/model va version. ProjectAgentMemberInstallation gan mot project agent voi user va local installation id, kem status, installed version, applied prompt hash, applied skill-set hash, last error va last synced time [[cite:nkProjectModels]].
Workflow khong ket thuc o agent definition. ProjectWorkflowStage, ProjectWorkflowRun, ProjectWorkflowArtifact, ProjectWorkflowArtifactRevision va ProjectWorkflowArtifactRevisionComment tao mot duong audit cho artifact. Artifact co approval_status, freshness_status, revision, lineage_root_revision_id va lineage_snapshot_json; revision co source_type agent hoac user_edit [[cite:nkProjectModels]]. Dieu nay quan trong vi output cua agent khong tu dong tro thanh dau vao cua chang sau: no tro thanh artifact pending cho toi khi duoc approve.
Enum state cung co hinh dang phu hop voi claim ledger: installation co not_installed, pending, installed, failed, stale; workflow run co draft, waiting_installation, running, waiting_approval, completed, failed; artifact co pending/approved va current/stale [[cite:nkProjectEnums]]. TypeScript shared contract dua cac truong nay len web client, nen UI va service client co chung ngon ngu voi server [[cite:nkSharedTypes]].
Service layer la noi split-plane duoc hien thuc. request_project_agent_install_update tao hai onboarding items rieng: project_agent_definition_sync va project_agent_install_update_requested. Ca hai deu mang desiredVersion, desiredPromptHash, desiredSkillSetHash; install item con mang danh sach skills voi sourceType, sourceUri, pinnedRevision, integrityHash va version [[cite:nkProjectService]]. Install route sau do emit hai item nay qua agent-local onboarding channel [[cite:nkProjectEndpoint]].
Bang chung tu mat phang thuc thi cuc bo
personal-work-agent co bang ProjectAgentDefinition de luu workspace_id, target_installation_id, project_id, project_agent_id, shared/fixed prompt, pinned/allowed skill ids, desired version/hash va observed install status/hash [[cite:pwaModels]]. Tai lieu runtime nhan manh rang du lieu nay tach khoi personal chat settings nhu agent_character [[cite:pwaRuntimeDoc]].
Onboarding sync service xu ly definition sync bang cach tao hoac cap nhat ProjectAgentDefinition va ghi audit event. Install/update chi chap nhan skill object co sourceType git_repo, sourceUri va skillId hop le; skillId khong duoc chua slash, backslash hay bat dau bang dau cham, va resolved destination phai nam trong skill root. Sau do service clone hoac pull repo va checkout pinnedRevision neu co [[cite:pwaOnboarding]]. Mot run pytest hep ngay 2026-06-29 xac minh curated git_repo install update, non-curated source rejection va startup install snapshot push deu pass [[cite:pwaFocusedRun]].
Ranh gioi nay van chua phai supply-chain proof day du. Server model va install payload mang integrityHash [[cite:nkProjectModels,nkProjectService]], nhung code cai dat local duoc inspect chi clone/pull va checkout pinned revision, khong thay buoc verify integrityHash [[cite:pwaOnboarding]]. Vi vay paper chi claim curated source va pinned checkout boundary, khong claim integrity verification hoan tat. Day la vi du ve claim calibration theo NIST SSDF va OWASP LLM risk framing [[cite:nistSSDF,owaspLLM]].
Pending execution path chuyen project_workflow_stage_execute thanh local project-workflow case trong source [[cite:pwaPending]]. Tuy nhien, khi toi thu collect hai test lien quan, pytest dung o collection vi test_agent_pending_sync import OutboundMessage khong ton tai trong db.models [[cite:pwaBlockedRun]]. Do do, phan pending-sync duoc viet nhu source-inspected behavior va test-intended behavior, khong phai passing verification. Nguoc lai, document pipeline result push da duoc test va pass: prompt gom instruction va input documents, callback payload mang targetInstallationId, boardId, stageId, artifactKind, contentText, requestingUserId va localCaseId [[cite:pwaDocumentPipeline,pwaFocusedRun]].
Ket qua: Workflow Control Ledger
Tu hai mat phang, ledger co sau chang. Chang 1 la definition : server tao project agent voi role, prompt, skill ids va version. Chang 2 la curated acquisition : server chi gui skill curated; local chi nhan git_repo hop le va clone/pull/checkout. Chang 3 la install observation : local cap nhat observed install status/hash va day snapshot ve server. Chang 4 la approved input : server chi dua cac artifact approved/current truoc stage hien tai vao input documents. Chang 5 la local execution case : pending item tao case cuc bo va queue thuc thi. Chang 6 la result callback : local result quay lai artifact kind va stage dung de server upsert/phe duyet tiep [[cite:nkProjectService,pwaOnboarding,pwaPending,pwaReviewPush,pwaDocumentPipeline]].
Ledger nay khong phai checklist trang tri. No ngan ba loi dien giai. Thu nhat, socket emit khong dong nghia voi workflow proof; Socket.IO delivery semantics khien ta phai tach live delivery khoi durable artifact [[cite:socketDelivery]]. Thu hai, local log khong du de nhom lam viec tin workflow chung; approval, freshness va lineage can nam trong control plane [[cite:nkProjectModels]]. Thu ba, cloud state khong du de thuc thi file/tool cuc bo; local execution plane can installation id, HMAC-signed transport va case/result path [[cite:pwaHmac,pwaReviewPush]].
Thao luan
Ket qua chinh la kien truc project-agent nen duoc noi bang ngon ngu stage-specific. Thay vi noi agent da cai dat , he thong nen noi: definition version X da sync, skill-set hash Y duoc yeu cau, local installation Z bao cao installed voi applied hash Y, va last_error rong. Thay vi noi agent da xu ly stage , he thong nen noi: cac input artifact A/B da approved/current, pending item P tao local case C, callback R tao artifact kind K cho stage S. Cung mot logic, W3C PROV cho thay workflow co the duoc xem nhu entities, activities va agents noi voi nhau [[cite:w3cProv]].
Dieu nay cung lam ro phan con yeu. Neu pending-sync tests khong collect, mot paper nghiem tuc khong nen viet la pending-sync duoc test pass. Neu integrityHash duoc luu nhung local install routine chua verify hash, khong nen viet la supply-chain integrity da duoc bao dam. Neu Socket.IO day event, khong nen viet la durable proof. NIST AI RMF ung ho cach noi nay: AI system risk can duoc govern, map, measure va manage, khong chi gan nhan tu dong hoa [[cite:nistAI]].
So voi local-first software, thiet ke nay khong phai offline-first day du. No van can hosted workflow state, agent-local onboarding va callback endpoint. Nhung no giu mot diem cuc bo quan trong: nhung viec can file, cong cu, token va moi truong nguoi dung duoc thuc thi trong runtime local, trong khi workspace chung chi nam giu dinh nghia, approval va provenance. SQLite la lua chon hop ly cho mot local application state store o quy mo nay, mien la khong bi hieu nham thanh distributed coordination layer [[cite:sqliteUses]].
Vi the, ledger nay co gia tri thuc dung cho dashboard, audit log, UI copy va test design. Dashboard nen hien chang nao yeu nhat. Audit log nen noi project agent definition item, install item, pending item, local case va artifact revision. UI nen phan biet pending install, stale install, waiting approval va completed. Test design nen phu hop voi ledger: neu mot chang khong co test pass, claim san pham phai thap hon.
Gioi han va cong viec tiep theo
Gioi han lon nhat la nghien cuu source-grounded, khong phai production telemetry. Toi khong chay toan bo nk304, khong thuc hien workflow end-to-end qua web, khong test Socket.IO agent-local channel, va khong verify server callback endpoint bang deployment that. Vi vay, claim ve structure va mot phan local tests manh hon claim ve reliability san xuat.
Gioi han thu hai la pending-sync verification. Source va test file the hien y dinh tao case rieng cho project_workflow_stage_execute va khong reuse case cu, nhung collection hien bi chan boi import OutboundMessage [[cite:pwaBlockedRun]]. Cong viec tiep theo la sua import/test fixture, chay lai nhom test pending-sync, roi cap nhat ledger tu source-inspected sang test-verified cho chang local case.
Gioi han thu ba la supply-chain boundary. Git clone va checkout la primitive can thiet [[cite:gitClone,gitCheckout]], nhung curated skill integrity nen co buoc verify hash hoac signature neu integrityHash da la field chinh sach. NIST SSDF va OWASP LLM Top 10 deu la ly do de khong de agentic skill install vuot qua chinh sach ma khong co bang chung [[cite:nistSSDF,owaspLLM]].
Ket luan
Project-agent workflows can tach mat phang dieu khien va thuc thi cuc bo. nk304 co bang chung tot cho shared definition, install state, workflow artifacts, approval, freshness va lineage. personal-work-agent co bang chung cho local desired/observed state, curated git_repo install boundary, callback payload va HMAC-signed transport. Hai phan nay chi tro thanh mot workflow dang tin khi duoc noi bang ledger, khong phai bang socket event rieng le hay local log rieng le.
Workflow Control Ledger de xuat sau chang: definition, acquisition, observation, input, case, callback. Moi chang co bang chung toi thieu va claim cong khai rieng. Neu chang nao chua duoc xac minh, claim dung lai o do. Nguyen tac nay giup cac he thong tac nhan du an vua tan dung duoc runtime cuc bo, vua giu duoc control va provenance cua workspace chung.