OpenPress

@openpress-comment

註解標記

行內審閱標記在原始碼中以 MDX 註解的形式存在。Workbench 會將其渲染為編號圖釘；agents 會使用 apply-comments 工作流程來處理它們。沒有外部的註解資料庫。

本文件說明如何在 OpenPress 文件中加入及處理行內註解。

透過 Workbench 加入註解（人類使用者）

如果您正在瀏覽預覽畫面，請按照以下步驟加入註解：

  1. 確保已啟動開發伺服器 (npm run dev)。
  2. 在瀏覽器中開啟預覽（例如 http://127.0.0.1:5173/workspace）。
  3. 從畫面的工具列中點擊開啟 Inspector。
  4. 點選您想標記的段落區塊（或區塊間的插入條），接著點擊 Add comment。
  5. 輸入您的註解文字，並按下 Cmd/Ctrl + Enter 送出。
  6. Workbench 會自動將註解標記寫入 MDX 原始碼並存檔。

透過編輯器手動加入註解（Agent）

如果您需要手動在 MDX 檔案中插入註解，請依照以下步驟：

  1. 開啟目標 MDX 檔案。
  2. 尋找需要標記的文字段落。
  3. 在該段落的後方插入標準的 MDX 註解格式。請確保包含唯一的 id 與建立時間 ts：
{/* @openpress-comment id="c-2026-05-28-unique-id" ts="2026-05-28T12:34:00Z" text="您的註解內容" author="作者名稱" */}

處理與移除註解

當您要解決一個註解時，請遵循以下步驟：

  1. 閱讀原始碼中的註解文字與上下文。
  2. 針對註解需求進行原始碼的修改。
  3. 確認修改已經正確套用後，刪除該行註解標記。
  4. 若註解內容不夠明確或無法執行，請保留該標記，或將其替換為詳細的 TODO 說明。
  5. 切勿直接跨檔案重複使用相同的 id。如果複製了段落，請為新的註解產生新的 id。