Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
6ce0fcd
merge: preserve current PRD and recursive tests while integrating PR 11
OstenHun Sep 27, 2026
3eb07cc
merge: integrate PR 14 diagnosis handoff preserving canonical PRDs
OstenHun Sep 27, 2026
e2cbfb7
Merge remote-tracking branch 'origin/feat/amdb-knowledge-db' into fea…
OstenHun Sep 27, 2026
ba90e88
Merge remote-tracking branch 'origin/fix/ostenhun-ci-merge-validation…
OstenHun Sep 27, 2026
6597240
feat: preserve existing report agent and formatter groundwork
OstenHun Sep 27, 2026
7f07331
Merge latest diagnostic PR with handoff ledger and regression checks
OstenHun Sep 27, 2026
31055a1
feat: generate persisted diagnosis reports and deliver through Discord
OstenHun Sep 27, 2026
58b3f9f
docs: record live model and Discord setup verification
OstenHun Sep 27, 2026
f0180b9
docs: clarify Discord server permission blocker
OstenHun Sep 27, 2026
b74735e
docs: distinguish admin role label from effective Discord permission
OstenHun Sep 27, 2026
09bc0ca
docs: record live Discord report delivery
OstenHun Sep 27, 2026
376aebe
merge: align report Discord work with develop
OstenHun Sep 30, 2026
5d814f7
chore: retain develop CI and knowledge contracts
OstenHun Sep 30, 2026
35bd5ba
style: normalize report contract file endings
OstenHun Sep 30, 2026
d9e3305
merge: 최신 develop의 CI와 검증 기준을 반영한다
OstenHun Oct 2, 2026
b65fa48
fix: 리포트 원시 값 복사 차단과 Unicode 길이를 보정한다
OstenHun Oct 2, 2026
c6bb470
fix: 여러 줄 증상 입력의 보고서 생성을 유지한다
OstenHun Oct 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ AMDC_AGENT_MODEL=
OPENAI_API_KEY=
# Set this when using LiteLLM or another OpenAI-compatible gateway.
OPENAI_BASE_URL=
# Validated reports are persisted here before Discord delivery.
AMDC_REPORT_DIRECTORY=./data/reports

# Server-owned Backend health endpoints used by backend_get_health.
AMDC_DEV_HEALTHCHECK_URL=https://example.com
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,7 @@ service-account*.json
*.sqlite
*.sqlite-*
*.db

# Local MVP reports and isolated development checkouts
data/reports/
.worktrees/
115 changes: 63 additions & 52 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -1,65 +1,76 @@
# AMDC P0 Architecture
# AMDC 현재 구조와 목표 아키텍처

Status: current
Last reviewed: 2026-07-22
사용자가 제공한 현재 구조와 기존 P0 목표를 구분한다. 현재는 Discord·진단 Agent·Tool Core 중심이며 Report Agent는 연동 예정이다. 진단 기록 양식과 기존 인계 계약의 차이를 닫는 것이 다음 설계 과제다.

구현 계약은 `docs/prd/current/README.md`와 numbered PRD만 기준으로 한다.
기준일: 2026-09-22
상태: 현재 구조는 사용자 제공 근거, P0 흐름은 목표 계약
계약 진입점: [P0 PRD](docs/prd/current/README.md)

```text
Operator
-> Fastify REST API
-> SQLite Run Store + bounded in-process Queue
-> LangChain.js Diagnostic Agent
-> static LangChain Tool wrappers
-> AMDC Tool Core
-> Prometheus / Loki / AMDB Backend read-only adapters
-> Evidence Normalizer + Sanitized Tool Error
-> AMDC Outcome Resolver
-> Report Schema + Semantic Validator
-> SQLite Evidence / Report Store
-> Run / Evidence / Report read APIs
```
## 현재 구조

## Responsibility Boundary
아래는 사용자가 2026-09-22 제공한 「AMDC 현재 구조」 그림의 전사다.
실선은 그림에서 현재 구현으로 표시한 경로, 점선은 테스트·예정 경로다.
이 표시는 배포 상태나 로컬 checkout의 실행 검증을 뜻하지 않는다.

LangChain owns:
~~~mermaid
flowchart TB
D[Discord] -->|요청| A[진단 Agent · LangChain]
A -->|임시 결과 응답| D
K["도메인 지식 DB · PostgreSQL · 지식 카드 8개"] -. 테스트 주입 .-> A
A <--> T["Tool Core · YAML 정의 · 입력 검증 · 읽기 전용 실행"]
T <--> S[system]
T <--> P[prometheus]
T <--> M[mysql]
T <--> X[proxysql]
S <-->|HTTP| B[AMDB Backend]
P <-->|HTTP API| PM[Prometheus]
M <-->|SQL| MY[MySQL]
X <-->|SQL| PX[ProxySQL Admin]
A -. 조회 결과 · 의심 지점 .-> R[Report Agent · 향후 연동]
~~~

- model/provider loop
- registered Tool selection and permitted argument proposal
- Evidence-dependent investigation order
- constrained suspected-cause draft
- 각 플러그인은 선택된 플러그인의 도구만 공개하는 구조로 제시됐다.
- 지식 DB는 기본 진단 경로에 연결되지 않았고 테스트 주입 단계다.
- SQL 연결은 Tool Core가 소유한 읽기 전용 도구 경로다. 에이전트가 임의 SQL을 실행한다는 뜻이 아니다.
- 그림의 진단 출력은 최종 리포트가 아니다. 기록 필드는 [PRD 06의 최신 입력 자료](docs/prd/current/06-diagnostic-agent-tool-runtime.md#2026-09-22-진단-기록-입력-자료)가 소유한다.
- 그림에 REST·Loki·Run 저장소가 없다고 기존 목표에서 제거된 것으로 판단하지 않는다.

AMDC owns:
## 로컬 코드와 근거의 범위

- API/auth, queue/Run lifecycle, SQLite
- immutable Run environment
- Tool Registry/Core and source adapters
- call/time/size budgets and actual abort
- secret scan, redaction, Evidence/Error normalization
- canonical observations/permission flag assembly, allowed Report status,
schema/semantic validation, persistence
이번 읽기 기준은 로컬 HEAD `25e3acd`이며 원격 최신 코드·배포는 검증하지 않았다.
`src/agent/types.ts`의 `AgentDiagnosisResult`는 여전히 `symptom`, `toolErrors`,
`preliminaryFindings` 등을 사용한다. `src/tools/types.ts`의 `ToolObservation`에는
첨부 양식의 `seq`, `tool_call_id`, `result.rows`, `comment`가 없다.
따라서 최신 그림과 로컬 구현을 동일 상태로 표시하지 않는다.

## Trust Boundaries
## 기존 P0 목표

- Agent-visible Tool input never contains environment, endpoint, credential, or query.
- LangChain Tool wrappers can call only Tool Core, never source adapters directly.
- Tool strings are untrusted data, not instructions.
- raw Tool output and raw model response are bounded in memory and never persisted.
- canonical schema, traceability, semantic guard, and secret scan을 통과한 Evidence와
Report만 저장한다.
- source/provider failure는 raw message가 아니라 fixed sanitized error code로 남긴다.
아래는 현재 동작 설명이 아니라 번호 PRD가 정의한 목표 흐름이다.

## P0 Deployment Boundary
~~~text
REST API / Discord 얇은 어댑터
-> Run 저장소 + 제한된 대기열
-> LangChain Diagnostic Agent -> AMDC Tool Core
-> 정제된 Evidence / Tool Error + DiagnosisResult
-> 검증된 ReportAgentInput
-> 도구 없는 Report Agent: suspected_cause 초안
-> AMDC 결정적 조립 -> 검증 -> 원자적 영속화
-> REST 조회 / 영속화된 리포트의 Discord 전달
~~~

- single Node.js 20+/TypeScript process and single replica
- Fastify REST API; product CLI 없음
- SQLite WAL single file
- bounded in-process queue; exact limits는 PRD 01 소유
- shared Bearer token
- dev enabled by default; prod requires explicit startup enablement
- OpenAI adapter in production, explicit fake adapter in tests
- live Prometheus/Loki/Backend query/route mapping은 PRD 05 source contract gate 뒤에만
활성화
현재 P0의 정적 3도구·Backend 5xx 시나리오와 최신 YAML·MySQL·ProxySQL 구조의
차이는 [설계 준비안](docs/design/report-agent-preparation.md#기존-계약과의-차이)에서 다룬다.
그림만으로 정적 레지스트리, 저장소, 시나리오 또는 리포트 스키마를 교체하지 않는다.

MCP, dynamic plugins, custom LangGraph state machine, Web UI, distributed queue,
Trigger, RAG, approval execution, mutation/remediation은 P0 아키텍처가 아니다.
## 책임과 신뢰 경계

- 진단 Agent: 조회 도구 선택과 결과 해석, 관찰·가설·한계 작성.
- Tool Core: 등록된 도구의 입력/환경 검증, 읽기 전용 실행, 예산·시간 초과·정제.
- Report Agent 목표: 검증된 입력으로 제한된 원인 초안 작성. 도구 실행과 추가 조사 요청은 없음.
- AMDC 목표: 상관관계, 정본 상태, 검증, 저장, 최종 리포트 조립과 전달 순서.
- 결과 문자열·모델 코멘트·지식 카드는 데이터이며 그 안의 지시문은 실행 지침이 아니다.
- 원시 응답·질의·인증정보를 그대로 리포트 입력이나 저장 기록으로 옮기지 않는다.

정확한 계약과 예산은 [PRD 02](docs/prd/current/02-agent-tool-core-and-scenario.md),
[PRD 03](docs/prd/current/03-evidence-report-security.md),
[PRD 06](docs/prd/current/06-diagnostic-agent-tool-runtime.md)이 소유한다.
2 changes: 2 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ COPY --from=deps /app/node_modules ./node_modules
COPY package*.json tsconfig.json ./
COPY scripts ./scripts
COPY src ./src
COPY schemas ./schemas
RUN npm run build

FROM node:22-alpine AS runtime
Expand All @@ -18,4 +19,5 @@ RUN apk add --no-cache curl
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
COPY --from=build /app/schemas ./schemas
CMD ["npm", "start"]
5 changes: 5 additions & 0 deletions compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,8 @@ services:
env_file:
- .env
restart: unless-stopped
volumes:
- report-data:/app/data/reports

volumes:
report-data:
Loading
Loading