Agent Sandbox Registry

agent-sandbox

Decision: Template Catalog Single Source of Truth (awesome-templates)

无中文版

.agents/notes/implemented/architecture/2026-09-29-template-catalog-single-source-of-truth.md

Decision: Template Catalog Single Source of Truth (awesome-templates)

Status: implemented Proposed: 2026-09-29 Implemented: 2026-09-29

Problem

Template content, the machine-readable index (awesome-templates.yaml), and the publishing story were duplicated between this repository and the dedicated alibaba-agent-sandbox/awesome-templates repository, with a "extract the folder later via git subtree push" plan that never happened. Consequences:

  1. Drift by construction. The two copies diverged: the qwen-code parameter contract (max_turns → max_session_turns, default 100) and legacy template fields (base / system_packages) were fixed on one side but not the other; node-web/Dockerfile missed EXPOSE 9000.
  2. Users got stale content. A template catalog shipped inside the SDK can only refresh with an SDK release; community templates could not be discovered until a new version shipped.
  3. The root awesome-templates.yaml was never the real index. It lived in this repo but nothing installed from it; abx template search had no remote source, and bare-name installs had no resolution path.
  4. Test split was unclear. tests/test_templates/ validated a 10-template collection that was also being validated (differently) in the other repo.

Audit: task 184 (repository/reference drift audit). The Qwen rename contract is fixed by ADR 2026-09-29 (qwen-code Session-Turns Parameter Unification) and must not be reverted.

Decision

Make alibaba-agent-sandbox/awesome-templates the single source of truth (SSOT) for official & community template content, the index, releases, and CI. This repository keeps no publishable template collection.

Source-of-truth repository

This repository — index client and fixture only

API Design

# agent_sandbox/utils/template_index.py
DEFAULT_INDEX_URL: str            # raw.githubusercontent.com/.../awesome-templates.yaml
INDEX_CACHE_DIR: Path             # ~/.abx/index
INDEX_SCHEMA_VERSION = 1
INDEX_MAX_AGE_SECONDS = 3600

@dataclass(frozen=True)
class TemplateIndexEntry:
    name: str; repo: str; description: str = ""; path: str | None = None
    ref: str | None = None; tags: tuple[str, ...] = ()
    author: str = ""; capabilities: tuple[str, ...] = ()
    status: str = "community"
    @property
    def github_slug(self) -> str: ...   # owner/repo
    @property
    def install_ref(self) -> str: ...   # owner/repo//path@ref

@dataclass
class TemplateIndex:
    schema_version: int; entries: list[TemplateIndexEntry]
    source_url: str; stale: bool = False; notice: str = ""
    fetched_at: float | None = None
    def find(self, name: str) -> TemplateIndexEntry | None: ...
    def filter(self, query: str, *, tag=None, status=None) -> list[TemplateIndexEntry]: ...

def parse_index(text: str, *, source_url: str = "") -> TemplateIndex: ...
def read_cached_index(cache_dir: Path | None = None) -> TemplateIndex | None: ...
async def fetch_index(url=None, *, token=None, force=False,
                      cache_dir=None) -> TemplateIndex: ...

Alternatives considered

Dependencies

Test Strategy

Files changed

Evidence

Full snapshot: .agents/evidence/verify/2026-09-29-template-ssot-verification.md.

Consequences

Acceptance criteria