參考 / 能力與工具

能力與工具

Heddle 是 local-first 程式開發代理框架，面向真實工作區任務：檢查程式碼庫、進行有邊界的修改、驗證結果、保留 session，並讓 agent 工作可審查。

核心成果

檢查程式碼庫並解釋陌生程式碼庫

在 active workspace 內修改程式碼與文件

透過 build、test、shell command 與審查證據驗證變更

跨 multi-turn saved session 延續工作，而不是每次都從 stateless prompt 開始

從瀏覽器 control plane pin、rename、archive 與 restore session-list state

從瀏覽器 control plane 在本地專案工作區之間切換

透過 catalog-backed memory 學習持久工作區知識

設定使用者提供的 MCP servers，使用外部生態系工具

透過 approval、trace 與 current diff review 提供 operator oversight

透過 heartbeat scheduling 執行有邊界的自主工作

工作區工具

Heddle 會明確暴露工具，而不是把工作區存取藏在模糊的自動化後面。Tool call 會顯示在終端機、trace 或瀏覽器 review surface。

list_files          # Inspect directories
read_file           # Read known file paths
search_files        # Search repo text with ignore-aware behavior
edit_file           # Apply direct text edits
delete_file         # Delete files or directories intentionally
move_file           # Move or rename files and directories
run_shell_inspect   # Run bounded read-oriented shell commands
run_shell_mutate    # Run approval-gated shell mutations

外部與視覺脈絡

web_search: 由 provider-backed hosted search 提供，用於目前的外部 reference 或官方文件。
view_image: 檢查本地圖片，例如截圖、圖表與 browser-uploaded image path。
MCP integrations: 使用者設定的 Model Context Protocol servers，透過 Heddle approval 與 trace 暴露給 agent 使用。
@file mentions: prompt-level file reference，告訴 Heddle 要先檢查哪些檔案，而不是盲目把完整檔案貼進 prompt。
Direct shell: 在 chat 中用 ! 前綴執行命令；需要時會要求 approval。

Runtime features

.heddle/ 底下的 saved multi-turn session

Session list management，包含 create、switch、continue、rename、pin、unpin、archive 與 close flow

自動與手動 conversation compaction

substantial task 的 visible work plan

針對重複安全動作的 per-project remembered approval

Memory candidate recording 與 maintainer-backed catalog update

Chat 中 request-size aware 的 context tracking

長流程的 interrupt 與 resume support

Programmatic continuation 的 serializable checkpoint

Control-plane oversight

瀏覽器 control plane 加入 saved session browsing、right-click pin/rename/archive action 與 toast undo、即時 assistant 串流、工具進度、approval wait、工作區管理、Git-backed current diff review、trace-backed turn history、heartbeat task 管理與 memory status。Review view 是 read-only：Git 顯示目前改了什麼，trace 則說明選定 turn 如何走到那個結果。

目前限制

Heddle 是程式開發代理框架與工作區 runtime，不是通用自主系統。
Knowledge persistence 使用明確的本地 catalog，讓使用者可以審查 Heddle 學到了什麼。
Control-plane review surface 是唯讀，不是可編輯的 IDE-grade diff tool。
MCP server configuration 不會直接啟用 server；使用者仍然需要針對每個工作區選擇 active servers。
Web search 是 provider-backed，而不是 Heddle 內部維護的 crawler。
.git 與 .heddle 會避免被廣泛意外搜尋掃到，除非明確指定。