---
title: "Agent 主控台意見回饋 — 需求討論稿 (FR-192)"
brand: "Guidant AI · **FR-192** Agent 主控台意見回饋"
eyebrow: "FR-192 · 需求討論稿 · 2026-11-09（v4：D1～D8 全定案，整份改寫為文字）"
h1: "Agent 主控台意見回饋"
subtitle: "在 Agent 主控台新增、瀏覽、修改、刪除自己的回饋；與主系統的回饋是同一份資料，兩邊都能改"
lede: "客戶的人多半在 **Agent 主控台**上操作，碰到問題沒地方講——回饋只能在主系統網頁送，Agent 離線時連主系統都開不了。本案在主控台加一頁「意見回饋」：**離線也能用、連上自動同步、只看得到自己的**；主系統收到後就是一筆正常回饋，與網頁送的同一張表、同一頁，多一欄「來源」分得出是哪台 Agent 送來的。附件留在 Agent，主系統只記參照，與證據檔同一套。**兩邊都能改能刪，以較新的為準。**"
chips: [
  {text: "D1～D8 全定案（2026-11-09）", kind: ok},
  {text: "第一期只做提交與同步；原廠回覆第二期", kind: accent},
  {text: "前作：FR-099（回饋進 jedi-issue）、FR-166（主控台）、FR-181（長輪詢）", kind: accent},
  {text: "雛形：prototype/index.html（純畫面）＋ walkthrough.html（審稿旁白版）", kind: accent}
]
footer: "FR-192 · Agent 主控台意見回饋 — 需求討論稿 · 2026-11-09 v4 · 現況數字來源：DEV 本機 DB 唯讀查詢（public.labels、public.issues、public.feedback_issues、public.upload_files）"
---

## 需求背景 {#why nav="背景"}

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

### 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。不預留回覆表、狀態機、通知欄位，那些是第二期自己的設計，現在猜會猜錯。

## 分工概述（30 秒版） {#overview nav="概述"}

**整案一句話**：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 上斷線試。

## 端到端流程 {#flow nav="流程"}

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

```{.mermaid cap="圖 1 — 一筆回饋從主控台新增到主系統看得到。主系統拒收時 Agent 會留在佇列並在主控台標「回傳失敗」。"}
%%{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。

## 決策 {#decisions nav="決策"}

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

::: {.callout .decided}
**D1 「來源」兩欄放在 jedi-issue 的回饋表；Agent 名稱由主系統補**

`feedback_issues` 加兩欄：來源（網頁或 Agent）、來源編號（Agent 的 uid）。清單與明細吐這兩欄，主系統吐清單時再把 Agent 的 uid 翻成名稱，Agent 改名後清單跟著變。

為什麼放套件：「這筆從哪個管道來」是回饋本身的屬性，將來若有第二個管道（例如 CLI）也用同一欄。Agent 名稱不進套件，因為 jedi-issue 不該認識 Agent。

排除「全放主系統側對照表、套件不動」：清單端點要跨套件 join，而 jedi-issue 既有的回應擴充掛點目前是空殼沒人接，接起來比加兩欄還重。
:::

::: {.callout .decided}
**D2 本機管理員的帳號名 `local-admin` 不改；主系統建立人員欄直接存它，由持有「檢視全部回饋」的人代管**

決策者問「`local-admin` 能不能改」。探過：技術上能改，但不划算。這個名字不只是 Agent 的一個常數，每台已出貨 Agent 的本機密碼雜湊在 SQLite 裡就是以它當主鍵存的，改名要配一支 Agent 端 migration 搬列。主系統端也認這個字串：有人用本機管理員登入時寄信通知租戶管理員、離線登入政策頁查「最近一次本機管理員登入」，都是拿它去撈歷史稽核事件，改名後舊事件對不上。主系統目前沒有叫這個名字的使用者，建帳號也沒有保留字檢查。

定案三件事：不改名；Agent 來的回饋建立人員直接存 `local-admin`，畫面上「來源是 Agent 且建立人員是 `local-admin`」就翻成「本機管理員」；主系統把 `local-admin` 列為保留帳號名（jedi-iam 建帳號時擋），避免日後真有人取這個名字、「我的回饋」混進 Agent 本機管理員送的東西。

連帶（D6 雙向後浮現）：本機管理員送的回饋在主系統沒有「本人」，照既有「只有送件人能改」會變成沒人能改。定案：這類回饋由持有「檢視全部回饋」能力點的人（客服、PM）可改可刪，jedi-issue 的歸屬檢查加一條例外。

排除「每台 Agent 自動建一個主系統帳號」：會製造大量不能登入的幽靈帳號，角色、授權席次、稽核都要跟著排除。
:::

::: {.callout .decided}
**D3 Agent 端清單「自己的」用登入身分比對送件人；本機管理員看到的是這台所有用它送出的**

共用帳號本來就分不出人；只剩它能登入時，看不到剛送的會以為沒送成。排除「本機管理員什麼都看不到」。
:::

::: {.callout .decided}
**D4 類別下拉的選項由主系統設定通道下發，不寫死**

設定通道多一類，把三個類別標籤（編號與名稱）下發給 Agent；離線用上次拉到的；沒拉過時下拉為空、「新增回饋」反灰並提示「尚未從主系統取得類別」。

排除「Agent 寫死三個名稱、主系統收單時按名稱對編號」：管理員改標籤名就對不上，也違反「下拉選單不寫死在程式」鐵則。代價是設定通道多一類，但那是既有掛點（主系統加一個 provider、Agent 加一個套用者）。
:::

::: {.callout .decided}
**D5 「功能」下拉多一個選項「Agent 主控台」，Agent 來的回饋自動填它**

白話：主系統回饋表單有一個必填下拉叫「功能」，選的是「這則回饋在講產品的哪個功能」，現在有十六個選項。Agent 送來的回饋一定是在講 Agent 主控台，所以在那個清單多加一個選項「Agent 主控台」，Agent 送來的自動填這個，使用者在主控台不用選、表單上反灰顯示。

不加的話，那筆在主系統打開編輯時「功能」是空的，存不了。做法是一支 seed migration 補一筆功能標籤，編號固定寫在常數讓收單端點帶。
:::

::: {.callout .decided}
**D6 雙向同步：Agent 端可改可刪，主系統端也可改可刪，兩邊互相看得到；衝突以較新者為準**

決策者裁「要雙向，我在 Agent 發了，在主系統也要能改我的回饋」。主系統端本來就能改能刪（只有送件人能動），這條本來就成立；要補的是 Agent 端可改可刪並同步到主系統，以及主系統改了 Agent 跟著變。

**Agent 到主系統（改、刪）**：走與新增同一條待回傳佇列。每筆多帶一個動作欄位（新增、修改、刪除）與更新時間；同一筆的動作照入列順序送，新增沒送成前不送修改。主系統收到修改就呼叫既有的 `update_feedback`、刪除呼叫既有的 `delete_feedback`，身分用送件人的帳號，所以既有的歸屬檢查照常通過。修改可以加附件（Agent 新檔，主系統建參照）、拿掉附件（走既有刪附件）。

**主系統到 Agent（改、刪、加附件）**：走設定通道加一類「這台 Agent 送出的全部回饋現況」（標題、內文、類別、附件清單、更新時間、是否已刪），版本用內容雜湊。主系統只要有人改了回饋相關的表，既有的「設定一改就通知 Agent 來拉」機制會叫 Agent 來拉，Agent 拿到就覆寫本機那幾筆。這是既有掛點，不開新通道。主系統刪了，Agent 那筆標已刪、清單不列。主系統補上傳的新附件存在租戶儲存不在 Agent，Agent 清單列出檔名但標「存於主系統」、不可預覽。

**兩邊同時改**：以較新的為準，整筆覆蓋，不做欄位級合併。與既有「Agent 名稱雙向改名以較新者為準」同一條規則。Agent 送修改時帶它看到的主系統版本時間；主系統那筆比它新就拒收並回「過期」，Agent 收到後標「主系統已有較新版本」並在下一次拉取覆寫，使用者在 Agent 重新改一次即可。

排除三種：Agent 端鎖住不能改（前一版建議，決策者裁不合理）；Agent 端改主系統時即時打 API（離線不能用）；主系統每次改都推一條指令到 Agent（回饋內容走指令通道會變成第二個佇列，設定通道本來就是做「主系統有新狀態、Agent 來拉」的）。
:::

::: {.callout .decided}
**D7 附件區改成一個拖放區，抽成共用元件，主控台與主系統回饋表單都換上**

現況主系統回饋表單的附件區有兩個區、四種樣式：上方兩顆按鈕，空白時一個大虛線框加雲朵圖示，選了檔每檔一張大卡帶綠勾「準備上傳」，下方另一區「已上傳的檔案」每檔又一張卡帶三顆圓鈕。決策者原話「主系統的設計有點舊，特別是附件的地方，順便調整一下」。

新版：一個拖放區，既有檔與待上傳檔同一清單，每檔一列（圖示、檔名、大小、「存於 Agent」標籤），hover 才出動作（預覽、下載、移除），區底一行「拖放檔案到這裡，或選擇檔案 · 單檔 20 MB 以內」，空的時候整區只剩那一行。抽成 FE 共用元件，放主站 `src/components/`；主控台的 build 本來就能吃主站元件。本期只換回饋表單兩處，證據附件等其他上傳區不動。雛形的新增回饋對話框與主系統編輯回饋分頁就是這個樣子。
:::

::: {.callout .decided}
**D8 原廠回覆（helpdesk）本期不碰，只確認既有欄位夠用**

決策者裁「先都不管」。Agent 來的回饋開在 jedi-issue 既有的 `open` 狀態；來源欄與對照表能回推送件人與 Agent。回覆表、狀態機、通知、Agent 端看回覆，全部第二期開案。排除「本期先建空的回覆表與狀態欄」：沒人寫沒人讀，等第二期設計定了八成要改。
:::

## 詳細設計 {#design nav="詳細設計"}

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

## 現況接入點：什麼能直接用、什麼要改、什麼是新的 {#inventory nav="現況盤點"}

**直接用的**：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`，多檔與既有檔清單是新寫。

## 拆棒 {#breakdown nav="拆棒"}

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

| 批 | 卡 | Repo | 做什麼 | 依賴 |
|---|---|---|---|---|
| 1 | E-1 環境卡 | main | 主系統開發期改走四套件本機路徑（指 `.worktrees/<母卡號>/`），`assume-unchanged`，驗 import 路徑 | — |
| 1 | P-1 契約 | jedi-packages | jedi-agent-protocol 加路徑、動作、鍵名、兩個設定類；0.6.0 | — |
| 1 | P-2 保留帳號名 | jedi-packages | jedi-iam 建帳號擋 `local-admin`；patch | — |
| 2 | A-1 Agent 新增與清單 | agent | 新模組 `feedback`（表、新增／清單／單筆、console API）、outbox 類型與保序、類別選項套用者 | P-1 |
| 2 | I-1 jedi-issue | jedi-packages | 兩欄、建改回饋參數、歸屬例外、來源查詢、清單吐來源與篩選；1.6.0 | — |
| 2 | F-1 共用附件元件 | fe | `AttachmentDropList.vue` 與 i18n，先換進主系統回饋表單 | — |
| 3 | M-1 來源欄顯示 | main | 接回應擴充掛點補 Agent 名與「本機管理員」；功能標籤 seed | I-1 |
| 3 | M-3 收單端點 | main | `POST /agents/feedbacks`、收單服務（新增／修改／刪除、過期判定）、`register_agent_blob()` 抽出、類別選項 provider；jedi-remote-agent migration 014 | A-1、I-1 |
| 3 | A-2 主控台前端 | fe | `Feedback.vue`、路由、i18n，用 F-1 元件，打 A-1 端點 | F-1、A-1 |
| 3 | M-2 主系統前端 | fe | 兩頁加來源欄與篩選；表單來源提示列 | F-1、I-1 |
| 4 | A-3 Agent 改刪與回拉 | agent | `feedback` 模組修改／刪除、console PUT／DELETE、回饋現況套用者（較新者覆寫、已刪、過期處理） | A-1、M-3 |
| 4 | M-4 主系統回拉 | main | 回饋現況 provider、四張表監看、對照表刪除時間回寫 | M-3、I-1 |
| 4 | A-4 主控台前端改刪 | fe | 瀏覽對話框加編輯／刪除、存於主系統附件標示、過期提示 | A-2 |
| 5 | V-1 端到端驗收 | main | 真 Agent 全流程（見概述批 5） | A-3、M-4、A-4、M-2 |
| 6 | Z-1 結案 | jedi-packages → main | 四套件發版推 Nexus；主系統改回釘版、取消 assume-unchanged；回報出貨基線待重產 | V-1 |

同批不撞檔的理由：批 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` 程式驗批。

## 不做什麼 {#scope-out nav="不做"}

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

## 收尾待辦 {#closing nav="收尾待辦"}

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。