Agent 主控台意見回饋

Agent 這邊也要有回饋的功能，需要能提交回饋，清單則是自己看到自己的回饋，這個資料回送到主系統，跟主系統的回饋整合在一起。 — 決策者原話（2026-11-09）

1.1 現況：回饋只能在主系統網頁送

主系統有一組完整的回饋功能：「系統回饋」頁可以新增（標題、類別、功能、內文、附件）、瀏覽、編輯、刪除；「我的回饋」頁只列自己送的；持有「檢視全部回饋」能力點的人（客服、PM）在「系統回饋」頁看得到所有人的。這整組程式碼在 FR-099 已經搬進 jedi-issue 套件，主專案裡沒有回饋相關的程式。DEV 現況有回饋 17 筆，類別標籤三種（建議、問題、其他），功能標籤十六種。

Agent 主控台什麼都沒有。使用者在主控台碰到問題，要另外開主系統網頁才能回報；主系統在雲端或機房，Agent 斷線時（客戶內網常態）連這條路都沒有。

1.2 Agent 已經有「本機先存、連上再補送」的機制，本案照抄

網路診斷與手動掃描的紀錄就是這樣回主系統的，整條路四步：

1. 本機先落地。結果寫進 Agent 的 SQLite，每筆帶「送達主系統了沒」三個欄位：送達時間、主系統給的編號、失敗原因。
2. 進待回傳佇列。同一個 SQLite 裡有一張 outbox，每筆待送的東西排一列；心跳每跳一次就看佇列有沒有東西要送。
3. 批次送主系統。主系統有一支專用端點收這類紀錄，一次最多五十筆，用「哪台 Agent＋Agent 端編號」去重，所以重送不會變兩筆。
4. 主控台顯示同步狀態。「執行紀錄」頁每列有「回傳主系統」欄，三種狀態：已送達、待回傳、回傳失敗；失敗的那列有「立即重試」。

本案的回饋走同一條路：多一張表、佇列多一種類型、主系統多一支端點、主控台多一頁，四樣都照既有形狀長，不另造管道。

1.3 主控台的登入身分就是主系統帳號

主控台能登入的人有三種。離線操作者（主系統管理員授權、用本機密碼登入）和 LDAP 登入的人，登入身分就是主系統的帳號名，因為名單是主系統下發的。所以回饋回到主系統可以直接掛在這個人名下，他登入主系統「我的回饋」就看得到。

第三種是本機管理員 local-admin，每台 Agent 一個、共用、救急用，主系統沒有對應的人。它的回饋怎麼處理見 D2。

1.4 附件留在 Agent 是現成的路

主系統今天就有「檔在 Agent、主系統只存參照」這種檔：證據檔的儲存設定選 Agent 時，主系統的 upload_files 只記一列參照（存哪台、Agent 端的檔案編號、SHA-256），DEV 有 186 筆是這樣。主系統要看檔時，用長輪詢指令叫 Agent 把檔送上來，下載走既有的簽票下載口。所以回饋附件不需要新的傳檔管道，只差 jedi-issue 建回饋時要能「掛既有的參照」而不是「上傳新檔」。

1.5 第一期只做提交與同步，原廠回覆第二期

決策者裁：先把 Agent 能提交做好，主系統對回饋的回覆、狀態流轉、通知都不在本期；但未來回饋會長成「原廠回覆」的 helpdesk 單，要預留。本期的預留只做不花錢的事：Agent 來的回饋在 jedi-issue 開在既有的 open 狀態（本期不做任何狀態操作），來源欄與對照表能回推送件人與 Agent。不預留回覆表、狀態機、通知欄位，那些是第二期自己的設計，現在猜會猜錯。

整案一句話：Agent 主控台多一頁回饋，本機先存、連上補送，主系統收到就建成正常回饋並標來源 Agent；兩邊都能改能刪，以較新的為準。

六批，每批決策者怎麼檢查：

1. 環境。主系統開發期改走四個套件的本機路徑（契約、jedi-issue、jedi-remote-agent、jedi-iam）。檢查：主系統起得來，印 jedi_issue.__file__ 是 .worktrees/ 底下。
2. 看得見的東西。Agent 主控台回饋頁（新增、清單、瀏覽，先不連主系統）；主系統回饋表加來源欄、清單吐來源；共用附件元件做好並先換進主系統回饋表單。檢查：主控台新增一筆，清單出現「待回傳」；主系統「系統回饋」頁多「來源」欄、既有回饋顯示「網頁」；主系統回饋表單的附件區變成一個拖放區、檔列在區內。
3. 接起來。主系統收單端點、Agent 補送、主控台前端與主系統前端接元件。檢查：主控台新增一筆，幾秒內變「已送達」；主系統「系統回饋」頁出現那筆，來源「Agent · 名稱」，建立人員是你；斷線新增一筆再連上，自動變「已送達」。
4. 改、刪、回拉。Agent 端可改可刪並同步；主系統改了 Agent 跟著變；衝突以較新者為準。檢查：Agent 改標題，主系統那筆標題變；主系統改內文，Agent 瀏覽那筆內文變；主系統刪，Agent 清單消失；Agent 離線改、主系統同時改、Agent 連回後顯示主系統版本。
5. 端到端驗收。在一台真的 Agent 上把上面全部跑一遍，含附件下載與本機管理員送件。
6. 結案。四套件發版、主系統改回釘版。

批 1 是所有人的前置；批 2 三個 repo 同時做；批 3 等批 2 合回；批 4 等批 3 的收單端點；批 5、6 依序。決策者功課：批 3 與批 4 驗收時要在一台真的 Agent 上斷線試。

下圖是「新增」這條路：使用者在主控台按儲存之後，到主系統回饋頁看得到那筆，中間經過 Agent 本機、待回傳佇列、主系統收單端點、jedi-issue 四站。看圖時注意兩個「立刻」：清單立刻出現（不等主系統），主系統建完立刻回 accepted（不等外部 issue 系統）。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant U as 使用者（主控台）
    participant A as Agent
    participant M as 主系統
    participant I as jedi-issue
    U->>A: 新增回饋（標題／類別／內文／附件）
    A->>A: 附件存本機 blob（與證據檔同一套）
    A->>A: feedbacks 落一筆＋ outbox 入列
    A-->>U: 清單立刻出現「待回傳」
    Note over A,M: 心跳 observer 觸發補送（斷線就等）
    A->>M: POST /agents/feedbacks（控制面通行證）
    M->>M: 驗送件人是這租戶的啟用使用者或 local-admin
    M->>M: 每個 Agent 附件建一筆 upload_files 參照
    M->>I: add_feedback（來源＝agent、附件用既有參照）
    I-->>M: 回饋編號
    M->>M: agent_feedbacks 對照表記一列
    M-->>A: accepted
    A-->>U: 清單變「已送達」

圖裡沒畫的兩件事：主系統拒收（格式不合、送件人不是這租戶的人）時回 rejected，Agent 把原因寫進那筆的失敗原因欄、不再重送，主控台顯示「回傳失敗」與原因；Agent 到主系統這段每筆都帶「Agent 端編號」，主系統以「哪台＋編號」去重，outbox 重送不會變兩筆。修改與刪除的流程見 D6。

八項全部定案（2026-11-09）。每項先寫定案，再寫為什麼、排除了什麼。

5.1 Agent 端：新模組 feedback

主控台規定不碰資料庫，所以不能塞在 console；放 scan 或 sync 語意不對。新開一個模組 guidant_agent/feedback/，依賴方向是 console → feedback → platform，透過 sync 的 outbox port 入列，不直接 import sync 的實作。

一張表 feedbacks：編號、標題、內文（TipTap 產的 HTML，與主系統同）、類別標籤編號與名稱（名稱一併存，離線拉不到標籤時清單還顯示得出來）、送件人、建立時間、更新時間、刪除時間、附件清單（JSON，每項有編號、檔名、大小、型別、存在哪邊）、主系統給的編號、主系統端更新時間、送達時間、失敗原因。

app 層三組函式。新增、修改、刪除：附件走 files 模組既有的 blob 存檔（與證據檔同一套、記在操作者名下），寫 feedbacks，入列 outbox 並標動作，同一筆的動作保序。清單與單筆：只回送件人等於登入身分的，非本人一律 404。套用主系統回拉：收到設定類「回饋現況」時，以主系統端更新時間較新者覆寫本機、已刪的標刪除時間。

outbox 加一種類型 feedback，列入永不丟棄（人寫的、筆數少）、保序（同一筆新增→修改→刪除照順序，前一筆沒送成後面不送）、可重送（主控台「待回傳」計數與「立即重試」看它）。批次送主系統，回 accepted 就結案、rejected 寫失敗原因、stale 寫「主系統已有較新版本」並請求拉一次設定。

主控台 API（掛在 console blueprint）：清單、單筆、新增、修改、刪除、刪單一附件、立即重試、類別選項。新增與修改收 multipart（一個 JSON 欄位加多個檔案欄位），與主系統 /feedback 端點同形狀；body 上限沿用主控台既有限制。

主控台前端（FE repo console/）：路由表加一項掛「作業」群組，不綁權限範圍。新增與瀏覽都是對話框，與主控台既有頁一致（日誌頁點列開完整訊息、執行紀錄點報告開預覽）。新增表單的欄位、順序、名稱、版面與主系統回饋表單完全相同：標題整行，類別與功能並排，內文用同一支 TipTap 編輯器，檔案上傳用 D7 的共用元件；「功能」固定「Agent 主控台」反灰。按鈕與標題用主系統既有字：「新增回饋」「瀏覽回饋」「編輯回饋」。回傳狀態欄與「立即重試」沿用執行紀錄頁的 i18n 鍵。文案全部依 i18n 既有用語重寫，不從雛形複製。

5.2 契約（jedi-agent-protocol）

加一條路徑常數 FEEDBACKS_PATH、動作列舉、每筆與每個附件的鍵名清單、批次上限 50；設定類清單加兩類：類別選項（D4）、這台送出的回饋現況（D6 回拉）。版號 0.5.3 升 0.6.0。

5.3 jedi-issue

四處改動。回饋表加來源、來源編號兩欄（migration 006）。建回饋與改回饋多收「既有附件參照清單」參數，有值時不走上傳、直接把參照掛到回饋上；建回饋另多收來源兩欄。歸屬檢查加一條例外：來源是 Agent 且建立人員是 local-admin 時，持有「檢視全部回饋」能力點的人視為擁有者（D2）。多一支查詢「某來源編號送出的全部回饋」給主系統回拉用。清單與明細的回應多吐來源兩欄，查詢條件多收來源篩選。版號 1.5.0 升 1.6.0。

刪除語意不改：主系統刪了回饋，jedi-issue 照舊硬刪，「已不存在」由主系統側對照表記刪除時間來告訴 Agent。

jedi-iam 另一處小改：建帳號時擋 local-admin（D2），版號升一個 patch。

5.4 主系統

收單端點 POST /agents/feedbacks，控制面通行證認證，放在主專案（它要同時用 jedi-remote-agent 的身分與 jedi-issue 的服務，橋接兩個套件的事放宿主，先例是 Agent 手動原始碼掃描的收單端點）。收單服務在 Agent 所屬租戶的機器身分下跑，每筆四步：

1. 驗送件人：是這租戶啟用使用者的帳號名，或 local-admin，放行；其餘拒收並回原因。
2. 依動作分派。修改先比 Agent 帶來的「它看到的主系統版本時間」與主系統那筆的更新時間，主系統較新就回「過期」；刪除走既有 delete_feedback。
3. 附件：每個 Agent 檔用既有 RemoteAgentAdapter 建參照的那段邏輯建一筆 upload_files（存哪台、Agent 端編號、SHA-256 用 Agent 報的、建立者是送件人）。那段邏輯現在是私有方法，抽成公開的 register_agent_blob()，收單與既有上傳共用，不複製。
4. 呼叫 jedi-issue 建或改回饋，標籤帶類別與「Agent 主控台」功能標籤，來源標 Agent；對照表 agent_feedbacks 記一列（哪台、Agent 端編號、主系統回饋編號、刪除時間），「哪台＋編號」唯一，撞到就當已收過。

對照表 agent_feedbacks 是 jedi-remote-agent 的 migration 014，RLS 與權限照 agent_local_runs。

來源欄顯示：主系統接 jedi-issue 的回應擴充掛點，來源是 Agent 的列補 Agent 名稱，建立人員是 local-admin 的補暱稱「本機管理員」。

設定通道加兩個 provider：類別選項（D4），這台送出的回饋現況（D6）。既有的「表一改就通知 Agent 來拉」機制加四張表的監看：回饋表、回饋附件對應表、回饋標籤對應表對到「回饋現況」，標籤表對到「類別選項」。

標籤 seed：一支主線 seed migration 補功能標籤「Agent 主控台」（D5）。

前端：「系統回饋」與「我的回饋」兩頁加「來源」欄與分段鈕篩選（全部、網頁、Agent）；編輯回饋表單來源為 Agent 時顯示一列提示，附件區換 D7 元件，附件下載走既有簽票下載。

5.5 安全邊界

收單端點只認通行證：租戶、Agent 由通行證解出，body 帶的任何身分欄位一律不採信。送件人必須是該租戶的啟用使用者，跨租戶的帳號名拒收，否則一台 Agent 可以替別租戶的人送回饋。附件的 SHA-256 由 Agent 自報，主系統記下但不當驗過，下載時既有的完整性檢查會對實際 bytes 重算比對、不符即拒。標題與內文長度上限沿用主系統表單，超長的拒收不截斷。Agent 端新增與修改走主控台 session 與來源網段限制，附件解析沿用 files 模組的檔頭檢查與大小上限。

5.6 雛形兩份檔：純畫面給 runner，旁白版給決策者

決策者點名前幾個 FR 的 runner 把雛形裡的註解、「本案新增」黃框、分場景確認鈕整套抄進正式版。根因是雛形把兩種東西寫在同一份檔。本案起雛形固定兩份：prototype/index.html 是終局畫面本身（真實文案、真實資料形狀、無黃框、無旁白、無 D 項編號），派工卡只給這份並寫明「文案依 i18n 既有用語重寫，不複製；雛形只定結構與資訊順序」；prototype/walkthrough.html 是審稿版（同畫面加標記與旁白，頂部一行「審稿版，不是實作依據」），由純畫面版注入產生，只在 design.md「決策者檢查法」欄引用。這條已寫進 big-feature-workflow skill、guidant-design-system skill、派工卡範本與 notion-card-templates.md 硬規則 8。

直接用的：Agent files 模組的 blob 存檔（回饋附件與證據檔同一套）；主系統從 Agent 取檔與簽票下載（附件下載）；jedi-issue 的回應擴充掛點（來源欄 enrich，這個掛點開了很久沒人接）；「Agent 名稱雙向以較新者為準」的衝突規則（D6 沿用）；jedi-issue 既有的 open 狀態（D8）。

加參數或加一段的：jedi-issue 的建回饋與改回饋（多收既有附件參照、來源兩欄）、回饋表（兩欄）、歸屬檢查（local-admin 例外）；主系統 RemoteAgentAdapter 的建參照邏輯（私有抽成公開，收單與上傳共用）；主系統設定通道（兩類）與表改動監看（四張表）；Agent outbox（一種類型）；jedi-iam 建帳號（保留字）；主系統回饋兩頁（一欄一篩選）與表單（換附件元件）。

新開的，但照既有形狀：Agent feedback 模組，照 local_runs 的表欄位與 app 函式簽名；主系統收單端點與服務，照手動原始碼掃描收單端點與 local_run_service.ingest 的身分、去重、回應形狀；主控台回饋頁，照「執行紀錄」頁的表格、同步狀態欄與重試；共用附件元件，拖放與型別檢查照 SourceFilePicker，多檔與既有檔清單是新寫。

批＝可同時開 session 做的一組；階段只是給 PM 看的分組。登記型共用檔（契約常數、outbox 類型、console 路由表、i18n）由該批最早那張卡一次掛齊，後面的卡只填自己的檔。十四張卡、六批：

同批不撞檔的理由：批 1 三張在不同 repo 或不同套件；批 2 三張各在不同 repo；批 3 的 M-1 與 M-3 同在 main 但 M-1 只改 jedi-issue 接線檔與 seed、M-3 不碰那兩處，A-2 與 M-2 同在 fe 但一個只碰 console/、一個只碰 src/views/feedback/；批 4 三張三個 repo，M-4 與 M-3 都動收單服務的刪除路徑所以分批。design.md 落地時用 cards.py 程式驗批。

主系統對回饋的回覆、狀態流轉不做、不回流（D8 第二期），回流的只有回饋本身的內容、附件、刪除。主系統網頁新增回饋的流程完全不動。從主系統補上傳的附件走租戶儲存設定，不送去 Agent。外部整合（GitLab、GitHub）的 issue 不帶 Agent 附件（拿不到 bytes）。不做「主系統看 Agent 回饋的同步狀態」，主系統收到才有那筆。不做欄位級合併，兩邊同時改以較新者整筆為準。附件新版元件只換回饋表單兩處，其他上傳區本期不動。

SPEC：docs/spec-site/current/ 回饋管理頁加「來源」欄與雙向同步說明；Agent 主控台 SPEC 加「意見回饋」頁。系統整合通訊說明：第 3 章端點總表加 POST /agents/feedbacks、設定類表加兩類、第 7 章資料表加 agent_feedbacks 與 Agent feedbacks。出貨基線重產（jedi-remote-agent 與 jedi-issue 各一支新 migration、主線 seed）。四套件發版紀錄寫進 Z-1 卡與 commit message。