From 0cbf7141c0851f816b0c8ad838682f5c1d9295eb Mon Sep 17 00:00:00 2001 From: AirCoding Date: Mon, 1 Jun 2026 15:27:47 +0800 Subject: [PATCH] =?UTF-8?q?Detailed=20design:=20add=20=C2=A723=20Reference?= =?UTF-8?q?=20Implementation=20Map?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the traceability gap where baselineV1 §2 / decisions-round-1..3 mandate reusing mature reference-project code, but the detailed design and class diagrams had消化d those references into own abstractions with zero explicit "consult X here" pointers — risking context-isolated implementers re-deriving renderers, diff engines, or skill formats from scratch. New §23 maps each DD component to its reference project, with an explicit reuse mode (npm-dep / fork/adapt / pattern / behavioral) and local path: - TUI → @opentui/* (npm-dep) + OpenCode patterns (pattern) - Provider → @opencode-ai/llm (fork/adapt) - Execution discipline → Claude Code (behavioral) - patch/test loop → OpenAI Codex (pattern, reference/openai-codex/) - Knowledge/ExperienceMiner → Hermes (pattern) - Skills → Anthropic Claude Skills (pattern, reference/anthropic-skills/) - Logging/HUD/PTY → asciinema/Atuin/claude-hud (pattern) - Message format → Claude Code blocks (behavioral) Reuse rules preserve §2 import direction and §18.6 invariants; reference internal models never leak across our boundaries (e.g. no OpenCode session state). Freeze declaration renumbered §23 → §24. Pure documentation; zero change to contracts, events, schema, or runtime semantics. Co-Authored-By: Claude Opus 4.8 --- .../architecture/system-detailed-design.md | 46 ++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/AirPlan/docs/architecture/system-detailed-design.md b/AirPlan/docs/architecture/system-detailed-design.md index d6dfac0..be6e492 100644 --- a/AirPlan/docs/architecture/system-detailed-design.md +++ b/AirPlan/docs/architecture/system-detailed-design.md @@ -2355,7 +2355,51 @@ classDiagram ArchitectureDesigner --> EventIngestor ``` -## 23. Design Freeze Declaration +## 23. Reference Implementation Map + +AirCoding is **self-owned, not a wrapper** (baselineV1 §1): the architecture and class +design above are AirCoding's own. This section records, per baselineV1 §2 and +`decisions-round-1/2/3`, **where an implementer should consult mature reference code** +instead of designing a component from scratch, and the **reuse mode** for each. This is a +guidance map, not a dependency contract — it never overrides §2 import direction or §18.6 +invariants. + +**Reuse modes:** + +- `npm-dep` — consume directly as a dependency; do not re-implement. +- `fork/adapt` — copy and adapt source into our package; keep our own boundaries. +- `pattern` — reference structure/patterns; implement independently. +- `behavioral` — match observable behavior/quality; no code lineage. + +| DD component | Reference project (baselineV1 §2) | Reuse mode | Notes / local path | +|---|---|---|---| +| §13.2 TUI (`TuiApp`, components) | OpenTUI (`@opentui/solid` `@opentui/core` `@opentui/keymap`) | `npm-dep` | D-002/D-048: direct dependency; do not build a renderer. Theme/dialog/toast/keymap/layout/spinner/border/markdown/code/diff rendering adapted from OpenCode UI patterns. | +| §13.2 TUI interaction layout | OpenCode TUI | `pattern` | D-048: reference visual/interaction patterns; **do not** reuse OpenCode SDK/sync/session business state. | +| §12 Provider (`ProviderManager`, `ProviderAdapter`, converters) | `@opencode-ai/llm` | `fork/adapt` | D-002 list: provider/model abstraction may be forked/adapted; output stays Anthropic-canonical (D-046). | +| §8.4 + §9.4 Execution discipline (read-before-edit, exact edit, verify-before-complete) | Claude Code CLI | `behavioral` | baselineV1 §2: quality benchmark only — edit safety, patch granularity, conflict handling, verification discipline. No code lineage. | +| §9.4 `fs.edit`/`fs.patch` + §15 patch/test execution loop | OpenAI Codex (`reference/openai-codex/`) | `pattern` | baselineV1 §2: shell/patch/test direct-execution loop, tool orchestration, wider tool surface. | +| §11.3 + §14 Knowledge / ExperienceMiner / Curator | Hermes Agent | `pattern` | D-024: Nudge Engine interval trigger (~10 turns/tool-calls), Curator dedup daemon, skill self-patch. | +| §11.3 + runtime-semantics §11 Skills (`SKILL.md`, `scripts/`/`references/`/`assets/`) | Anthropic Claude Skills (`reference/anthropic-skills/`) | `pattern` | D-058: SKILL.md frontmatter + directory layout + trigger/retrieval descriptions; SkillGenerator output format. | +| §16.2 Logging / HUD + future PTY capture | asciinema / Atuin / claude-hud | `pattern` | baselineV1 §2: PTY capture, command metadata/history indexing, HUD/statusline layout. | +| §3 Message format (Anthropic canonical content blocks) | Claude Code message model | `behavioral` | D-016: Text/Thinking/ToolUse/ToolResult blocks; canonical internal format. | + +**Rules for reference reuse:** + +1. `npm-dep` items (`@opentui/*`) are real dependencies — implementers must not re-implement + them; see `packages/tui` (code-view §7). +2. `fork/adapt` and `pattern` items: adapt into our own package layout (§2 import direction), + preserve our contracts (§3) and invariants (§18.6) verbatim. A reference's internal model + never leaks across our package boundaries — e.g. OpenCode session/sync state is **not** + adopted (D-048). +3. `behavioral` items contribute **no code**; they set a quality bar verified by tests/evidence. +4. License compliance for any copied/forked source is checked at the architecture gate before + merge. + +> **For context-isolated execution:** include the row(s) relevant to a subagent's slice in its +> working context. The intent is to stop a partial-context implementer from re-deriving a diff +> engine, TUI renderer, or skill format that a named reference already provides. + +## 24. Design Freeze Declaration **System Detailed Design is frozen as of 2026-06-01 (commit `2673e49` → this commit).**