Skip to content

feat: local 任務源去 am 化 — inbox 預設路徑與 ticket 契約歸屬 (CH-009)#10

Merged
dccoding1118 merged 1 commit into
mainfrom
feat/local-ticket-contract
Jul 17, 2026
Merged

feat: local 任務源去 am 化 — inbox 預設路徑與 ticket 契約歸屬 (CH-009)#10
dccoding1118 merged 1 commit into
mainfrom
feat/local-ticket-contract

Conversation

@dccoding1118

Copy link
Copy Markdown
Owner

摘要

local 任務源原本以 am 為隱含前提:預設 inbox 寫死 ~/.am/tickets、ticket schema 記為「欄位由 am 定義」。本 PR 把預設落點與 schema 契約收回 gogents 自己——預設 inbox 改為 <全域家目錄根>/tickets(隨 GOGENTS_HOME 隔離),ticket 契約升格為 gogents 的本機任務源契約(R11 為真相源),am 降為其中一種 producer。

變更單:docs/changes/change-local-ticket-contract.md(CH-009)。

改動內容

  • internal/source/local.go:inbox 預設值改由 foundation.GlobalHome() 推導成 <GlobalHome>/tickets;顯式 source.path 行為不變(僅展開開頭 ~/)。
  • internal/source/local.goTaskContent.Author 由固定字串 am 改為 local(標示來源型別,不再指名 producer);認領規則的註解改為 producer 中立表述。
  • internal/foundation/config.gosource.path 預設值註解同步。
  • R11(主要落點):ticket 契約表新增「擁有者」欄,明確 id/worker/goal/context/verify 屬 producer、result/updated_at 屬 gogents、status 共同;「其他任何欄位」不讀不寫、回寫時原樣保留。
  • R01/R02/requirement.md/D01/D07/design-plan.md/unit-tests.md:預設路徑、前置檢查、模組邊界、行為契約與測試規格一併收斂到新預設。
  • README/AGENTS:只更新 inbox 路徑事實(整體定位重寫屬 CH-010)。
  • 新增 TestExpandTicketDir(D07-05a):覆蓋預設值、顯式路徑、~/ 展開三條解析路徑。

影響範圍與風險

  • am 不受影響:am 一律以絕對路徑寫入 runtime.yamlsource.path(CH-006 §3.3 盤點確認),走不到本次改動的 fallback。本 PR 未動 am。
  • 顯式設定 source.path 的既有 runtime 行為不變——只有「省略 source.path 且倚賴 ~/.am/tickets 預設值」的 runtime 需改為顯式指定該路徑。
  • ticket 檔格式與回寫語義不變(status/result/updated_at 的寫入、原子寫入、保留未知欄位皆同)。
  • github_issue 來源、task store、狀態機、執行流程皆未觸碰。

備註 / 待辦

本 PR 有兩個我自行判斷的決策,請一併審核:

  1. inbox 不自動建立:預設值現在落在 gogents 自己的家目錄下,論理可以代建,但維持 probe「不存在即拒啟」。理由是 inbox 由 producer 擁有,代建會讓 source.path 打錯字時 daemon 靜默空轉,而非啟動當下就報錯。已寫進 R11/D07/CH-009 §3.1。
  2. R11 的 processing_started 表述:原文件寫「(可選)標記進入執行」,但程式一直是 no-op;本次把文件改成對齊程式的 no-op。

README/AGENTS/R01–R12 的整體定位重寫(拔除「am 的執行面」定位)、LICENSE、release pipeline 留給 CH-010。

驗收方式(請你手動驗證)

1. 預設 inbox 隨 GOGENTS_HOME

go test ./internal/source/ -run TestExpandTicketDir -v

預期:三個 subtest 全 PASS——""$GOGENTS_HOME/tickets/srv/tickets 原樣、~/inbox$HOME/inbox

2. 端到端:省略 source.path 時 daemon 讀新預設路徑

export GOGENTS_HOME=$(mktemp -d)
mkdir -p "$GOGENTS_HOME/tickets"
go build -o bin/gogents ./cmd/gogents
bin/gogents runtime create demo --workspace /tmp/ch009-demo

編輯 /tmp/ch009-demo/.gogents/runtime.yaml,把 source 改成 type: localfilter.label: backend並且不要寫 pathproject.repo.url 填一個你有權限的 repo。接著放一張 ticket:

cat > "$GOGENTS_HOME/tickets/t-1.yaml" <<'YAML'
id: t-1
worker: backend
status: queued
goal: Say hello
context: Create hello.txt containing "hi".
mission: m-1
depends_on: []
YAML
bin/gogents start --workspace /tmp/ch009-demo

預期:daemon 通過 preflight 並認領 t-1(不再抱怨 ~/.am/tickets 不存在)。任務終態後檢查 $GOGENTS_HOME/tickets/t-1.yamlstatusdone/failed、有 resultupdated_at 已更新,而 mission / depends_on 原樣保留。

3. inbox 不存在時拒啟且不代建

export GOGENTS_HOME=$(mktemp -d)   # 不建 tickets/
bin/gogents start --workspace /tmp/ch009-demo

預期:啟動即失敗,錯誤訊息指出 ticket inbox 不存在/不可讀;且 $GOGENTS_HOME/tickets 不會被建出來(ls "$GOGENTS_HOME" 看不到 tickets)。

4. 回歸

go build ./... && go vet ./... && go test ./...

預期:全數通過。

…ct (CH-009)

Default the local source inbox to <GlobalHome>/tickets instead of the
hardcoded ~/.am/tickets, so it follows GOGENTS_HOME isolation and no longer
points at a third-party tool's directory. Promote the ticket schema to
gogents' own contract (R11), with am demoted to one of several producers.

- internal/source/local.go: resolve the default inbox via foundation.GlobalHome();
  TaskContent.Author is now "local" rather than "am".
- Producer-neutral claim rule: only status == queued is claimed; every other
  value leaves dispatch timing to the producer.
- docs: R11 gains a field-ownership column; R01/R02/D01/D07, requirement.md,
  unit-tests.md, design-plan.md, README and AGENTS converged on the new default.
- Add TestExpandTicketDir (D07-05a) covering default, explicit and ~/ paths.

am is unaffected: it always writes an absolute source.path, so it never hits
the fallback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@dccoding1118
dccoding1118 merged commit 43c9b9b into main Jul 17, 2026
@dccoding1118
dccoding1118 deleted the feat/local-ticket-contract branch July 17, 2026 07:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant