語言EN繁
首頁
文件
主要功能 / 自訂代理

自訂代理

自訂代理讓你為特定回合選擇 Heddle 應該使用的角色：問問題、寫程式、審查變更，或執行專案定義的專門代理。

自訂代理是什麼

自訂代理是一個具名的執行設定檔。它不會取代 Heddle 的預設系統提示詞；它會附加角色專屬指令，並為已送出的回合帶上工具、核准與執行設定。

Heddle 的快速模式也建立在同一個基礎上：Ask 是唯讀的檢查代理，Code 是預設的程式開發代理，Review 是唯讀的審查代理。使用者可以在同一個已儲存工作階段內切換，因為代理選擇是以回合為範圍，不是以整個工作階段為範圍。

這讓團隊可以實際定義 Repo Reviewer、Docs Writer、Release Operator、Incident Investigator 等角色，而不需要為每一種工作流程建立一個獨立產品介面。

設定檔控制哪些內容

提示詞附錄

附加在 Heddle 一般系統指令後面的額外指令。

工具設定

該回合中模型可以看見哪些工具，例如一般程式開發工具或唯讀檢查工具。

核准設定

該回合要互動式核准、保持唯讀，或使用可信任的自動核准行為。

執行預設值

選用預設值，例如 maxSteps、模型或推理強度。

內建模式

Ask

檢查工作區並回答問題，不進行變更。

Code

使用一般 Heddle 程式開發設定進行實作。

Review

審查程式碼與差異，但不套用修正。

定義放在哪裡

自訂代理定義是包含 YAML frontmatter 區塊的 Markdown 檔案。專案代理會隨程式碼庫分享；使用者代理放在你的使用者目錄。

.agents/agents/<agent-id>/AGENT.md     # Project agents
~/.agents/agents/<agent-id>/AGENT.md   # User agents

建立代理

在 .agents/agents/repo-reviewer/AGENT.md 建立專案定義：

---
schemaVersion: 1
id: repo-reviewer
name: Repo Reviewer
description: Review repository changes without applying fixes.
modeAlias: review
runtime:
  maxSteps: 80
tools:
  preset: inspect
approval:
  preset: read_only
---

You are a repository review agent.

Prioritize correctness, reliability, missing tests, and maintainability.
Lead with actionable findings grounded in file paths, diffs, command output, or trace evidence.
Do not edit files or run mutation commands.

使用代理

在瀏覽器控制平面中，開啟 Settings -> Agents 來建立或檢視專案代理。
在聊天中，打開輸入框的加號選單，選擇上傳圖片、權限模式、代理或語意漂移。在代理底下，為下一個提示選擇 Ask、Code、Review 或自訂代理。
一次性的終端機使用方式是在 heddle ask 傳入 --agent <id> 或 --mode ask|code|review。

CLI 範例

heddle ask --agent repo-reviewer "Review the current workspace changes"
heddle ask --mode ask "Explain this repository"
heddle ask --mode review "Review the current diff"

安全模型

自訂代理不會繞過 Heddle 政策。工具可見性會由執行時的工具設定過濾；敏感動作仍會經過核准設定與 Heddle 的核准機制。唯讀代理應使用檢查工具設定與唯讀核准設定；程式開發代理可以使用一般工具，搭配互動式核准或可信任的自動核准。

自訂代理與 Agent Skills 的差異

Agent Skills 是代理在相關情境中可以載入的可重用指令與資源。自訂代理則是選擇該回合的角色。當自訂代理的工具設定包含 read_agent_skill 時，它仍然可以使用已啟用的 Agent Skills。

相關文件