agent-fleet/openspec/changes/agent-fleet-platform/specs/receipt-protocol/spec.md at f60f028f96f783b30a4e92fdd35dac1104bb1caa

Zer4tul aabd52ed52 init: OpenSpec project scaffolding with proposal, design, specs, tasks

- 7 capabilities: agent-registry, task-router, receipt-protocol,
  forgejo-integration, matrix-chatops, agent-adapter, orchestrator-core
- Tech stack: Rust + axum + zigbuild (single binary)
- Forgejo as task source of truth
- Matrix as real-time ChatOps layer
- Adapter pattern for multi-agent type support

2026-05-11 14:37:43 +08:00

2.2 KiB

Raw Blame History

ADDED Requirements

Requirement: Structured receipt format

Agent 完成任务后 SHALL 回写结构化 receipt。Receipt 包含：task_id、agent_id、status（completed / failed / partial）、duration_seconds、summary、artifacts（PR URL、文件路径等）、error（失败时）。

Scenario: Successful task completion with PR

WHEN Agent 完成代码任务并创建了 PR #15
THEN Agent SHALL 提交 receipt：{status: "completed", artifacts: [{type: "pr", url: "https://forgejo.example/repo/pulls/15"}], summary: "..."}

Scenario: Partial completion

WHEN Agent 完成了部分工作但未能全部完成
THEN Agent SHALL 提交 receipt：{status: "partial", summary: "完成 3/5 个文件修改，test_auth.ts 超时", artifacts: [...]}

Requirement: Receipt delivery channels

Receipt SHALL 通过至少一个持久化渠道回写：Forgejo Issue comment（必须）+ Matrix 通知（可选）。

Scenario: Receipt written as Issue comment

WHEN Agent 提交 receipt
THEN Orchestrator SHALL 在对应 Issue 下创建结构化 comment，包含 status emoji + summary + artifact links

Scenario: Receipt triggers Matrix notification

WHEN Receipt 写入成功
THEN Orchestrator SHALL 向 Matrix 协同房间发送通知消息，包含任务状态和关键信息

Requirement: Receipt validation

Orchestrator SHALL 验证 receipt 中的 artifact 声明（如 PR 是否真实存在）。

Scenario: PR artifact validation

WHEN Receipt 声明创建了 PR #15
THEN Orchestrator SHALL 通过 Forgejo API 验证 PR #15 确实存在，若不存在 SHALL 将任务标记为 failed 并通知 Agent

Scenario: Comment artifact validation

WHEN Receipt 声明在某个文件中做了修改
THEN Orchestrator SHALL 验证对应 commit/PR 包含该修改

Requirement: No-trust policy

系统 SHALL NOT 仅凭 Agent 的文本输出判定任务完成。只有结构化 receipt + artifact 验证通过才算 completed。

Scenario: Agent says done without receipt

WHEN Agent 在 Matrix 发消息说"任务完成了"但未提交 receipt
THEN 任务 SHALL 保持 running 状态，超时后按 failed 处理

2.2 KiB Raw Blame History Unescape Escape