[ggnnggez]

Summary

Adds an extension developer manual under harness/extensions/, in English and Chinese, covering the deerflow-extension-api 0.2.1 contract, the version on 2.1.x-dev. The manual is scoped to 0.2.1 so this PR can be cherry-picked to 2.1.x-dev for the 2.1 release.

Full-stack plugins (#5647, #5685) and request-scoped run evidence (#5727) exist only on main, so they are documented in the stacked follow-up #5775, which brings the manual up to 0.2.3.

Chapter	Covers
Extensions (index)	When to write an extension vs a tool, MCP server, skill, or extensions.middlewares; the seven contribution kinds; loading; failure and trust model; versioning
Quick Start	Build, unit-test, install, configure, and remove a working extension end to end
Runtime Model	Load sequence, API version rules, scopes and ExtensionData, fail-open and cancellation rules, diagnostics
Middleware Contributions	The five placements and where each lands today, scope, ordering, observe-only wrap hooks, failure isolation, task state
Lifecycle and Observers	Task lifecycle, system model calls, agent assembly and fingerprint, context compaction
Services and Routes	Service lifecycle, router rejection rules and their log messages, auth, resolve_principal / require_admin
Run Evidence	The global service reader, cursor semantics, deletions, redaction, store differences
Operating Extensions	Extension manager CLI with real output, accepted sources, upgrade and rollback, Docker, Helm, recovery
Troubleshooting	Indexed by the exact log and error strings
Reference	Every public name in the 0.2.1 contract and the version history, 0.1.0 (#4636) to 0.2.1 (#5405)

Also fixes stale descriptions found along the way:

• The root AGENTS.md said the reference extension demonstrates "all" contribution kinds; it demonstrates five.
• deerflow/extensions/AGENTS.md said run-evidence metadata is "secret-redacted"; only the legacy auth_token key is removed.

CHANGELOG entries are added in both languages.

Verification

• Every example was run against the real host (uv run --frozen): the loader, create_app() with TestClient (auth on and off), the notify functions, the real run and event stores, and the extension CLI against a throwaway project root. Quoted log lines, error messages, and status codes are copied from that output.
• The middleware placement table was measured by inserting probes into the real lead-agent and subagent stacks.
• The Quick Start package was built as a standalone project; its tests pass and it loads through load_extensions with no diagnostics.
• EN/ZH parity: same headings and code fences on every page; code blocks are copied from the English pages by script.
• All 20 pages compile with @mdx-js/mdx; prettier and pre-commit hooks pass; scripts/check_agent_guidance.py reports 0 errors.
• Applied the full diff to upstream/2.1.x-dev: it applies cleanly, check_agent_guidance.py reports 0 errors there, and every /docs/... link and linked repository path in the manual exists in the 2.1 tree.

Notes for reviewers

The manual documents current behavior. Writing it surfaced these likely code issues, which the pages describe as-is; happy to file them as separate issues:

1. Inline system-model observers have no timeout: goal.py, title_middleware.py, and summarization_middleware.py call observe_system_model_call without timeout=, so a slow observer stalls the run path (lifecycle hooks have a 3 s budget).
2. ExtensionService.start() has no timeout (extensions/gateway.py); a hung service blocks Gateway startup. stop() is bounded at 30 s.
3. Memory-backend run-evidence cursors from before a restart return empty pages instead of raising InvalidRunEvidenceCursor.
4. make extension-upgrade fails when the entry-point target changes (manager.py matches the record by use).
5. A subagent-scoped TOOL_RAW contribution logs a "fell back to a secondary anchor" warning on every subagent build, although the fallback still meets the guarantee.
6. Smaller: TaskInfo.resumed is never True; the subagent task store scope_id differs from TaskInfo.task_id; the version-mismatch hint suggests a pip install the host can't follow.

Plugin-specific findings are listed in #5775.

The Reference chapter's version history must be updated by hand when the contract changes.

[willem-bd]

Static review against the documented deerflow-extension-api 0.2.1 host behavior. I found one authentication mismatch in the new route guidance.

[willem-bd]

[P2] Do not advertise PAT access to contributed routes

PATs never reach an extension-contributed path under the current host policy. AuthMiddleware authenticates the token and then calls is_pat_allowed_route(), whose allowlist only enumerates built-in thread/project/run routes; /api/ext-status/* therefore returns 403 {"detail":"PAT credentials are not permitted on this route"} before this handler. This also makes the PAT-specific principal paragraph and /reset response below inaccurate (and the Chinese page mirrors it). Please document contributed routes as rejecting PAT credentials, or add an explicit PAT policy for extension routes before promising token access.