API Contracts & Extensions
AI Translation Notice
This page is synced from the primary Chinese guide (接口与扩展契约). Refer to the Chinese version if any detail is ambiguous.
All external integrations and agents must interact through the HTTP API and read-only CLI hooks — never edit decisions.db or decisions/metadata.json directly.
Security Boundaries & Capability Limits
- Loopback isolation:
is_loopback_hostpermitslocalhostand loopback IPv4/IPv6 addresses only.send_headrejects symlinks escapingweb/. - Cross-site & payload defense: Mutating requests enforce
Host,Origin(loopback or empty), andSec-Fetch-Site(blockscross-site), requireContent-Type: application/json, rejectTransfer-Encoding, require a singleContent-Length, cap payloads at10 MiB(10sread timeout), and cap Git invocations at30s. - Portable topic IDs (
validate_portable_id): Allows 1–128 chars[a-zA-Z0-9_-]; rejects traversal segments, Windows reserved names (CON,PRN,AUX,NUL,COM1–COM9,LPT1–LPT9), and case-insensitive alias collisions. - Non-authorizing labels:
accepted,verified, andagent-questionradio selections are ledger data only — the server never executes tests, runs builds, or grants shell execution rights.
HTTP REST API Reference
Read-Only Endpoints (GET)
| Endpoint | Query Params | Purpose |
|---|---|---|
/ | — | 302 redirect to /dashboard.html |
/api/config | — | Returns resolved config dictionary |
/api/status | — | Returns project_name, absolute paths, Git readiness, and consistency digest |
/api/topics | — | Returns topic_scope-filtered topic list, capabilities, settled_decisions, open_questions, changelog, config |
/api/topic/<id> | — | Returns full topic detail, version, content, discussion, and recent revisions (reachable even if filtered out by topic_scope) |
/api/git/log | limit, offset, topic_id | Returns Git commit log, SQLite revisions, and current_revision |
/api/agent/context | module, path, topic_id, format=json|markdown | Returns 5 context buckets; explicit unknown topic_id errors instead of returning empty |
/api/recovery/check | — | Compares Markdown digests against SQLite topics and metadata.json |
Protected Write Endpoints (POST)
Topic mutations accept expected_version / request_id in JSON body or via X-Expected-Version / X-Request-Id headers.
| Endpoint | Key Payload Fields | Behavior |
|---|---|---|
/api/topic/create | id, title, optional content_override, 3-axis fields, request_id | Creates topic Markdown, SQLite row, and initial revision |
/api/topic/<id>/save | expected_version (required when topic exists), request_id, new_user_opinion, new_agent_reply, edit_latest_round, 3-axis fields, commit_message | Appends round or amends latest round (edit_latest_round: true); replays identically for matching request_id + payload |
/api/topic/<id>/restore | rev_id, expected_version (required for live topic), author, reason, request_id | Restores single topic snapshot (traces TOPIC_REMOVE -> prior_rev_id when deleted) |
/api/topic/<id>/verify | expected_version, impl_commit (non-empty), verifier, test_summary, mark_verified (bool), request_id | Records caller-supplied verification metadata without executing tests |
/api/topic/<id>/delete | expected_version, optional author, reason, request_id | Moves .md to .archived_rollback/, deletes topics row, writes TOPIC_REMOVE revision for undo |
/api/rollback | rev_id, expected_revision (required from /api/git/log) | Full-ledger rollback (428 if missing, 409 on revision drift) |
/api/recovery/rebuild | — | Rebuilds topics and metadata.json from decisions/*.md while preserving revisions (409 on guarded drift) |
/api/backup | — | Creates hot SQLite backup via Backup API |
Common errors: 400 validation/round-trip fence failure, 403 forbidden origin/host, 404 not found, 409 version_conflict / idempotency_conflict / revision_conflict, 428 missing expected_version or expected_revision.
Orthogonal 3-Axis & Idempotency Contracts
workflow_state:pending,discussing,decided,deferred,superseded.decision_outcome:"",accepted,partially_accepted(first switch requires non-empty user opinion stating scope; grouped underpending_requirements),rejected(requires non-emptyrejection_reason).implementation_state:not_started,in_progress,implemented,verified.- Save & retry discipline: Persist the exact
request.jsonbefore POSTing. On timeout, retry the exact savedrequest_id,expected_version, and payload — never bumpexpected_versionor allocate a newrequest_idaftersave_statussucceeded even ifgit_statusskipped/failed. - Latest-round amendment: Use
edit_latest_round: trueonly when the user explicitly requests fixing the latest round; pass only the amended field (new_user_opinionornew_agent_reply) so the other stays intact and prior snapshots stay preserved.
Agent Hooks (core.agent_hooks) & agent-question
The repository never auto-installs global agent hooks or Git hooks. Host tools or developers run core.agent_hooks explicitly:
python3 -m core.agent_hooks --config /path/to/dashboard.config.json before-task --module 存储层
python3 -m core.agent_hooks --config /path/to/dashboard.config.json after-write --topic adr-storage --receipt /path/to/receipt.json- Loopback HTTP only (
--urloverrides address while still checking data path parity via/api/status); proxies and redirects disabled. - Exit code
0means ledger consistency/receipt check passed (still checkgit_committedexplicitly); exit code2emits structured JSON error onstderr.after-writedoes not verifydelete_topicarchive or full-ledger rollback. - Stdlib retry pattern: Fetch
GET /api/topic/<id>, persistrequest.jsonoutside tracked public files, POST to/api/topic/<id>/save, and savereceipt.json. agent-questionJSON fence: Place inside the latestnew_agent_replywith 1questionstring and 2–8 unique options (strings or{ "label", "description" }). Enclose docs/examples in longer outer backticks so they never activate radio controls; UI has no pre-selected default and never mutates 3-axis state automatically.
Extension Troubleshooting
| Condition | Action |
|---|---|
| Server offline or config mismatch | Verify --config, port, and running instance; never fall back to blind writes on default port |
428 version_required | Read /api/topic/<id> or /api/git/log first before constructing a write |
409 conflict | Re-read latest state, compare drafts manually, then submit with a fresh request_id |
400 round-trip validation error | Close unclosed Markdown fences or wrap literal discussion-header examples in outer fences |
git_status != "committed" | Report git_status honestly; ledger save and Git commit are distinct phases |