ArchView

저장소 하나에 '모듈 간 의존성'을 그려주는 아키텍처 다이어그램 —— 토폴로지는 전부 tree-sitter 정적 분석에서 나오고, LLM은 각 노드에 한 줄짜리 요약을 쓰는 일만 맡습니다. 같은 그림을 MCP를 통해 IDE의 agent에 노출합니다.

단일 머신, 로컬, 127.0.0.1에만 바인딩. 기본 중국어 인터페이스.

📦 직접 다운로드 (Windows, Node 설치 불필요, clone 불필요)

⬇ ArchView_0.1.0_x64-setup.exe · 35 MB · Windows 10/11 x64

설치 후 더블클릭하면 독립 창이 하나 뜨고, 그 안에 웹 버전 그 패널이 있습니다. Node와 CodeGraph가 내장되어 있고, %LOCALAPPDATA%\ArchView에 설치되며, 관리자 권한이 필요 없습니다.

사용법: 한 문단을 AI에게 복사해 붙여넣고, 몇 가지 질문에 답하면 됩니다.

소프트웨어를 열면 패널이 비어 있고, 위에 복사 가능한 프롬프트가 있습니다 (이번 실행의 실제 포트와 token 포함). 그걸 프로젝트를 편집 중인 AI에 붙여넣으세요 —— Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI 모두 가능하며, 스스로 자신이 누구인지 알아냅니다. 그러면 AI는:

1. 이미 실행 중인 이 창에 연결합니다 (clone하거나 새로 설치하지 않음)

2. 자신이 어떤 호스트인지 인식하고 MCP를 설정합니다 (설정을 건드리기 전에 먼저 물어봄)

3. 작업 공간에서 후보 프로젝트를 재귀적으로 찾습니다 —— 폴더 하나에 여러 저장소/하위 프로젝트가 있는 게 일반적이므로, 목록을 보여주고 어느 것을 연결할지 묻습니다 (전부 연결할지도 포함)

4. 등록 + 인덱스 생성 + 그래프 생성 (인덱스가 없으면 스스로 만들며, 큰 저장소는 몇 분 걸림)

5. 그다음 지금 시맨틱 요약을 작성할지 묻습니다 (그 단계는 token을 많이 소모하므로 반드시 물어봐야 함)

몇 가지 질문에 답하면 창에 그래프가 나타날 때까지 기다리면 됩니다. 방법은 CONNECT-FOR-AI.md에 있습니다 (소프트웨어 안의 그 프롬프트가 이 파일을 가리킴). 실제 포트와 token이 포함된 실시간 버전은 런타임의 /onboarding.md에 있습니다.

AI가 개입하는 게 싫으세요? 패널 아래 폼에 절대 경로를 입력해도 됩니다 —— 등록 후 '데이터 재구축'을 클릭하면 인덱스가 자동으로 생성됩니다.

⚠️ 코드 서명이 없어서 첫 실행 시 SmartScreen이 한 번 막습니다 ('추가 정보' → '그래도 실행').

Related MCP server: SGraph MCP Server

또는 CLI 버전 설치

npm i -g archview                 # 四个命令进 PATH：archview / archview-serve / archview-mcp / archview-skill
archview init d:/code/my-repo && archview build && archview serve --open

npx archview init .               # 不装，试一次就走

npm에 게시됨: archview. pnpm 불필요, clone 불필요, build 불필요, 유일한 하드 요구사항은 Node ≥ 22.5 (node:sqlite). 최초 npm i 시 CodeGraph의 플랫폼 하위 패키지가 함께 내려옵니다 (Windows x64는 248.7 MB, node.exe와 네이티브 모듈 포함) —— 이는 의도된 것이며, 일부러 패키지에 넣지 않았습니다 (넣으면 모든 플랫폼 사용자가 여섯 개를 전부 다운로드해야 하므로).

세 가지 경로 선택:

세 가지는 동일한 작업 공간 레지스트리를 공유합니다 (~/.archview/workspaces.json), 그래서 아무렇게나 섞어 써도 같은 프로젝트들이 보입니다. 데스크톱 버전 상세는 Windows 독립 창 버전 참조.

🚀 AI가 소스에서 설치하도록 하기

CLI 버전(CI, 스크립트, MCP 연동)을 원하거나 코드를 수정하고 싶다면 —— 이 작업 전체를 AI에 맡길 수 있습니다.

아래 전체 문단을 복사해서, 웹을 읽고 명령을 실행할 수 있는 AI 어시스턴트(Kiro / Cursor / Claude Code / Codex …)에 붙여넣고, <내 프로젝트 경로>를 분석할 저장소로 바꾸세요:

帮我装 ArchView 并把我的项目接进去。

仓库：https://github.com/LZZLHY/archview
安装剧本（先读这个，它是给你写的）：https://raw.githubusercontent.com/LZZLHY/archview/main/SETUP-FOR-AI.md

我的项目在：<我的项目路径>

照剧本走：环境体检 → clone → pnpm install + pnpm build → archview init 我的项目 → archview build → 起服务。
剧本里标了「决策点」的地方问我一下再决定（尤其是装到哪、要不要改我的 AI 宿主配置、要不要现在开始写摘要）。
最后把带 token 的面板 URL 给我。

스크립트(SETUP-FOR-AI.md)의 각 단계에는 '이 단계가 성공했는지 어떻게 아는지'가 있고, '흔한 실패와 대책' 섹션도 있습니다. AI가 clone하기 전에 raw URL로 읽을 수 있도록 설계되었습니다.

직접 하기: 제 5절로 건너뛰면, 다섯 단계 명령을 복사-붙여넣기로 실행할 수 있습니다. 또는 한 줄로 처음 두 단계를 처리:

# Windows PowerShell（先 clone，再跑仓库里的脚本）
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

# macOS / Linux
bash scripts/setup.sh

볼 가치가 있는지 먼저 판단하려면: 제 3절(왜 존재하는가)과 제 10절(알려진 제한 / 누가 쓰면 안 되는가).

1. 무엇을 해결하는가

혼자서 9개 ohpm 모듈로 된 HarmonyOS 앱을 작성 중이라고 가정해 봅시다 (이것이 이 프로젝트의 시작 계기입니다). 두 가지가 필요합니다:

1. 자기 자신을 위해: 클릭하고, 드릴다운하고, 'entry가 어떤 HAR에 의존하는지, commons를 누가 쓰는지' 볼 수 있는 그래프;

2. agent를 위해: Cursor / Kiro / Claude Code의 어시스턴트가 프로젝트 구조를 정확히 알고, 더 이상 grep으로 추측하지 않게.

기존 도구들은 각각 절반씩 부족합니다:

ArchView는 양쪽을 연결합니다: CodeGraph가 사실을 내고, UA 패널이 인터페이스를 내고, LLM은 시맨틱만 보충합니다.

⚠️ 먼저 보세요: 모듈 수는 저장소 형태에 따라 달라집니다

'모듈 간 의존성' 그래프의 전제는 여러 모듈입니다. 모듈은 우리가 추측하는 것이 아니라 저장소의 사실에서 파생됩니다 (철칙 1), 그래서 저장소 형태에 따라 결과가 다릅니다:

archview build는 매번 모듈이 어떻게 나왔는지 한 줄 출력합니다. 예:

模块策略 pathDepth —— 未命中工程化模块声明（…），退化到路径深度切分；
  按路径首段只得到 1 个模块（src），已自动下钻到第 2 层，切出 4 个模块：src、src/api、src/core、src/utils

archview status와 패널 목록 페이지도 같은 문장을 보여줍니다. 모듈이 왜 이렇게 나뉘는지 이해가 안 될 때 먼저 이것을 보세요.

⚠️ 직관에 반하는 점: modules.labels는 이미 인식된 모듈의 표시 이름과 설명만 바꿀 수 있고, 모듈을 정의할 수는 없습니다. 존재하지 않는 key를 넣어도 모듈이 생기지 않습니다 (build가 이에 대해 경고를 냅니다). '모듈을 어떻게 나눌지'를 바꾸려면 modules.strategy / modules.pathDepth를 바꾸세요.

⚠️ 저장소에 큰 디렉터리(빌드 산출물, 사전 컴파일된 바이너리, 컨테이너 컨텍스트)가 있다면 먼저 codegraph.json을 작성하세요

이것은 서로 다른 두 스위치이고 작용 지점이 다릅니다. 처음 쓰는 사람은 거의 모두 밟는 함정입니다:

codegraph.json은 CodeGraph의 설정 파일이지 우리 것이 아닙니다 —— ArchView는 절대 생성하지도 수정하지도 않습니다, 그래서 아무도 대신 작성해 주지 않고, 우리가 덮어쓰지도 않습니다. 형태는 이렇게 간단합니다:

{ "exclude": ["prebuilt/", "docker/output/", ".tmp-build/", "third_party/"] }

작성 후 .codegraph/를 삭제하고 다시 구축하세요 (exclude가 적용되려면 인덱스를 다시 만들어야 함).

이번 실측 수치도 이렇게 나온 것입니다 —— 같은 HarmonyOS 저장소 (281개 .ets), 유일한 차이는 이 파일의 유무입니다:

마지막 칸은 과장이 아닙니다: graph.json은 JSON.stringify로 저장되는데, V8의 문자열 상한이 약 512 MiB라서 초과하면 Invalid string length가 던져집니다. 그래서 이제 두 가지 차단이 있고, 둘 다 codegraph.json을 지목합니다: 인덱스 파일 수가 너무 크면 그래프를 만들기 전에 경고 한 줄을 냅니다 (4분을 헛으로 기다리지 않게), 그래프가 정말 한도를 넘으면 명시적으로 쓰기를 거부하고 위의 JSON을 제시합니다.

2. 두 MIT 프로젝트의 융합체, 여기서 숨기지 않음

둘 다 MIT. 서명과 파일별 출처는 NOTICE, 이 프로젝트 자체 라이선스는 LICENSE.

3. 왜 독자적으로 존재할 가치가 있는가: LLM은 절대 토폴로지를 쓰지 않음

이것이 이 프로젝트의 유일한 기술적 근거이자, 유일하게 타협을 허용하지 않는 규칙입니다:

노드와 엣지는 오직 CodeGraph의 tree-sitter 출력에서만 파생될 수 있습니다. LLM/agent는 summary와 tags만 제공할 수 있고, 절대 노드를 쓰지 않고, 엣지를 쓰지 않고, 모듈 구분을 쓰지 않습니다.

차이는 매우 구체적입니다. 토폴로지를 LLM이 생성하는 프로젝트는 반드시 수많은 패치 스크립트를 더 작성해 뒷수습을 해야 합니다: 맞지 않는 ID 정규화, 존재하지 않는 노드를 가리키는 dangling 엣지 버리기, 방향이 뒤집힌 엣지 뒤집기. 이런 스크립트 자체가 '구조를 신뢰할 수 없다'는 증거입니다. ArchView에는 그런 것이 필요 없습니다 —— 엣지가 존재하는 이유는 tree-sitter가 소스 코드에서 그 참조를 실제로 파싱했기 때문입니다.

수반되는 세 가지 규칙(커버리지, layer 커버리지, 파일 수준 엣지 상향)과 모든 구현 제약은 CONTRACT.md에 있습니다. MCP의 도구 면에는 그래프를 쓰는 도구가 존재하지 않습니다.

4. 필요 사항

CodeGraph를 전역 설치할 필요는 없습니다: packages/core의 일반 npm 의존성이고, archview init이 node_modules에서 bin을 해석해 대신 호출합니다 (항상 DO_NOT_TRACK=1과 CODEGRAPH_NO_UPDATE_CHECK=1을 붙임).

릴리스 상태: 두 형태 모두 출시됨

npm 버전은 완전히 깨끗한 임시 디렉터리에서 실제로 설치·실행되었습니다 (로컬 tarball이 아니라 registry에서 받음): npm i archview 8.8초 → archview init이 실제로 CodeGraph를 호출해 인덱스 생성 → archview build로 그래프 생성 (단일 패키지 레이아웃이 자동으로 2개 모듈로 드릴다운) → archview-serve로 서비스 시작, 그래프 엔드포인트와 연결 엔드포인트 모두 200, prompt는 @archview/skill이 렌더링하고 내장 폴백이 아님, 두 zod의 alias 격리가 적용됨 (mcp 3.25.76 / core 3.24.1).

@archview/core 같은 이름은 절대 npm에 올라가지 않습니다: 저장소 내부 workspace 패키지 이름이고 (여섯 개 패키지의 package.json 모두 private: true), 게시되는 것은 archview 하나뿐입니다. 그러므로 MCP 설정에 npx -y @archview/mcp를 쓰지 말고 (그 패키지 이름은 존재하지 않음), npx -y -p archview archview-mcp를 쓰거나, 설치된 archview-mcp bin을 직접 쓰세요 —— 가장 좋은 방법은 로컬에 실제 존재하는 mcp.js 절대 경로를 가리키는 것입니다 (패널과 GET /api/onboarding이 그 경로를 제공).

새 버전을 릴리스할 사람 (npm login 필요, 또는 ~/.npmrc에 publish 권한이 있는 token 필요; npm은 이제 기본적으로 2FA를 요구하므로 인터랙티브 릴리스는 --otp=<6자리 코드>를 추가해야 함):

pnpm run npm:publish     # = 先 build 六个包 → 组装 npm-package/ → npm publish

무엇이 나갈지만 보려면:

pnpm run npm:pack                        # 产出 npm-package/archview-<版本>.tgz
npm publish ./npm-package --dry-run      # 逐条清单，不落地

조립기는 scripts/build-npm-package.mjs이고, 파일 헤더에 '왜 단일 패키지인가' '왜 bundler를 안 쓰는가' 그리고 네 가지 가드(dist 누락 / dist가 src보다 오래됨 / 버전 번호 불일치 / 산출물 자체 검증 실패 → 모두 패키징 거부, 빈 패키지나 낡은 코드가 나가지 않음)가 명시되어 있습니다.

여전히 소스에서 설치할 수 있음(제 5절): 코드를 수정하고 싶거나, 수락 테스트 스크립트를 실행하고 싶거나, pnpm --filter로 특정 패키지만 빌드하고 싶다면, 모두 소스 경로를 사용한다. 그 경로는 Node ≥ 22.5 및 pnpm이 필요하며, 처음에는 pnpm install + pnpm build를 한 번 기다려야 한다(이 머신에서 실측: 새 클론 install 5.0초, build 17.1초, 전체流程 25.6초; pnpm store가 차가운 머신에서는 몇 분이 정상). 업데이트는 git pull + 다시 build(dist/는 gitignore되어 있으므로 pull은 소스만 바꾸고 산출물은 바꾸지 않는다).

skill 설치 프로그램은 MCP 설정을 작성할 때 "이 머신에 실제로 존재하는 파일 우선"으로 처리한다: npm 설치 형태에서는 node_modules/archview/packages/mcp/dist/bin/mcp.js를 가리키고, 소스 형태에서는 packages/mcp/dist/bin/mcp.js를 가리키며, 양쪽 모두 얻을 수 없을 때만 npx -y -p archview archview-mcp로 폴백하고 그 요구 사항은 패키지가 게시되어야 한다는 설명을 문구에 포함한다. command는 현재 프로세스의 node 절대 경로를 사용하며, 맨몸의 "node"가 아니다: 데스크톱 버전은 런타임을 내장하고 사용자가 Node를 설치할 것을 요구하지 않지만, 맨몸의 "node"는 호스트의 PATH에 의존한다(없을 수도 있고, 18일 수도 있으며, nvm에 의해 전환될 수도 있다).

Windows 독립 창 버전(설치 패키지)

명령줄 외에도 자체 창이 있는 Windows 소프트웨어가 있다 — desktop/, Tauri 2 셸. 이미 게시됨, 직접 다운로드:

⬇ ArchView_0.1.0_x64-setup.exe (35 MB, Windows 10/11 x64, %LOCALAPPDATA% 설치, UAC 불필요)

직접 빌드할 수도 있다:

cd desktop
npm install              # 只装 @tauri-apps/cli 一个本机开发工具
npm run build            # 产出 ArchView_<版本>_x64-setup.exe（~35 MB）

(Rust 툴체인 필요: rustup + MSVC. npm run build는 먼저 scripts/stage-resources.mjs를 실행하여 npm 단일 패키지와 프로덕션 의존성을 bundle.resources에 배치하며, 그 단계에서 어떤 단계라도 실패하면 빌드가 중단된다 — 그래서 "누락된 것이 있는 설치 패키지"를 만들 수 없다.)

브라우저 버전과 별개의 것이 아니다: 창 안에 설치된 것은 packages/web/dist라는 그 SPA이며, 셸은 동일한 packages/server를 spawn하고 종료 시 정리하는 역할만 하며, Rust 쪽에는 서비스 로직이 한 줄도 없다(CONTRACT.md 제 9절이 이 조항을 하드 제약으로 고정했다). 따라서 패널, CLI, MCP, 데스크톱 버전은 같은 일에 대해 같은 숫자를 제공한다.

설치된 소프트웨어는 Node와 CodeGraph를 내장하며, 사용자 머신에는 아무것도 먼저 설치할 필요가 없다:

설치 후 사용법은 "창 열기 → 목록 페이지에서 저장소의 절대 경로 입력 → 재구축 클릭 → 그림 보기"이며, 터미널을 만질 필요가 전혀 없다. 인덱스가 없으면 재구축 시 자동으로 codegraph init을 대신 실행한다(계약 제 6절) — 정직하게 말하면 지금 여기서 "먼저 archview init을 실행하세요"라고 답하는 것은 창만 있는 사용자가 실행할 수 없는 명령이다.

아직 하지 않은 두 가지를 분명히 말한다: 코드 서명 없음(첫 실행 시 SmartScreen이 한 번 차단하며, "추가 정보 → 그래도 실행"을 선택), Windows x64만 지원(패키징 스크립트가 현재 플랫폼에 따라 CodeGraph의 플랫폼 하위 패키지를 가져오므로, 크로스 플랫폼은 각 대상 플랫폼에서 각각 빌드해야 한다). 자세한 내용은 desktop/README.md 참조.

플랫폼 현황(모든 플랫폼을 테스트했다고 기대하지 말 것)

• Windows — 주요 개발 및 검증 플랫폼. 이 README의 명령과 출력은 모두 Windows 11(build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2에서 실제 실행한 것이다. skill 설치는 junction을 사용하며 관리자 권한이 필요 없다. 포트 점유 확인: netstat -ano | findstr :7420.

• macOS / Linux — 코드의 모든 플랫폼 관련 분기는 작성되어 있지만(브라우저 열기는 open/xdg-open 사용, skill 설치는 symlink로 폴백), 이 두 플랫폼에서 체계적으로 수락 테스트를 실행하지 않았다. 문제가 발생하면 issue를 열어 주세요. "공식 지원"으로 간주하지 말 것.

• 실행 시 ExperimentalWarning: SQLite is an experimental feature라는 한 줄이 표시된다. 이는 Node가 node:sqlite에 대해 표시하는 일반적인 알림이며, 오류가 아니다.

5. 시작하기: 코드 가져오기부터 그림 보기까지

다섯 단계. 각 단계마다 어디서 실행하는지, 실행 후 어떤 일이 일어나는지, 성공했는지 어떻게 아는지를 명확히 적었다.

이 다섯 단계를 직접 밟고 싶지 않다면? 맨 앞의 프롬프트를 AI 어시스턴트에게 붙여 넣으면, SETUP-FOR-AI.md에 따라 처음 세 단계를 완료할 것이다.

1단계: 코드 가져오기

npm에는 아직 없다(제 4절 참조: 패키지는 이미 빌드되었지만 아직 publish되지 않음). 따라서 첫 단계는 저장소를 로컬 머신으로 가져오는 것이다. 게시 후에는 이 절 전체를 건너뛸 수 있다 — npm i -g archview 후 바로 3단계(archview init)부터 시작하면 된다. 네 가지 경로 중 하나를 선택:

A. git clone(권장) — 이후 git pull로 업데이트할 수 있다.

# Windows PowerShell
git clone --branch main --single-branch https://github.com/LZZLHY/archview.git "$env:USERPROFILE\archview"
cd "$env:USERPROFILE\archview"

# macOS / Linux
git clone --branch main --single-branch https://github.com/LZZLHY/archview.git "$HOME/archview"
cd "$HOME/archview"

B. zip 다운로드(git이 없을 때) — 대가: 이후 업데이트는 다시 다운로드하여 덮어써야 한다.

# Windows PowerShell
Invoke-WebRequest https://github.com/LZZLHY/archview/archive/refs/heads/main.zip -OutFile "$env:TEMP\archview.zip"
Expand-Archive "$env:TEMP\archview.zip" -DestinationPath "$env:TEMP\av" -Force
Move-Item "$env:TEMP\av\archview-main" "$env:USERPROFILE\archview"

# macOS / Linux
curl -L https://github.com/LZZLHY/archview/archive/refs/heads/main.zip -o /tmp/archview.zip
unzip -q /tmp/archview.zip -d /tmp/av && mv /tmp/av/archview-main "$HOME/archview"

압축 해제된 디렉터리 이름은 archview-main이며, 이름을 바꿔야 한다(위 두 명령이 이미 대신 바꿔 주었다).

C. gh repo clone(GitHub CLI 설치 시)

gh repo clone LZZLHY/archview "$HOME/archview"

D. 원클릭 스크립트(1, 2단계를 함께 완료) — 코드 가져오기 + pnpm install + pnpm build + 다시 pnpm install 한 번(bin 링크 보완) + 자체 점검. 먼저 A/B/C로 코드를 가져온 후:

# Windows PowerShell。-ExecutionPolicy Bypass 只影响这一次调用，不改系统策略
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -Dir D:\tools\archview -Ref main

# macOS / Linux
bash scripts/setup.sh
bash scripts/setup.sh --dir /opt/archview --ref main

아직 clone하지 않았고 클라우드에서 직접 스크립트를 가져오려면, 먼저 다운로드하여 확인한 후 실행하고, 원격 스크립트를 무작정 파이프로 실행하지 말 것:

irm https://raw.githubusercontent.com/LZZLHY/archview/main/scripts/setup.ps1 -OutFile "$env:TEMP\av-setup.ps1"
Get-Content "$env:TEMP\av-setup.ps1" -TotalCount 60     # 看一眼
powershell -ExecutionPolicy Bypass -File "$env:TEMP\av-setup.ps1"

curl -fsSL https://raw.githubusercontent.com/LZZLHY/archview/main/scripts/setup.sh -o /tmp/av-setup.sh
less /tmp/av-setup.sh                                   # 看一眼
bash /tmp/av-setup.sh

스크립트 매개변수: -Dir/--dir <경로>(기본 ~/archview), -Ref/--ref <브랜치 또는 tag>, -SkipBuild/--skip-build, -Help/--help. 세 가지 동작 보장: 디렉터리가 이미 존재하고 archview 저장소인 경우 → git pull + 다시 build, 중복 clone하지 않음; 이미 존재하지만 archview 저장소가 아닌 경우 → 오류로 종료, 해당 디렉터리는 한 바이트도 건드리지 않음; 사전 점검 실패 → 맨몸의 exit 1 대신 실행 가능한 다음 단계를 제공. 의도적으로 archview init과 서비스 시작을 하지 않는다 — 그것은 사용자 자신의 저장소와 상주 프로세스에 관한 것이므로, 사용자 또는 사용자의 AI가 명시적으로 결정해야 한다.

성공했는지 어떻게 아는가: 설치 디렉터리에 package.json이 존재하고 그 name이 archview인지 확인. git으로 가져온 경우 git rev-parse --short HEAD로 sha를 볼 수도 있다.

경로에 공백이 없도록 주의 — 사용할 수는 있지만, 이후 모든 명령의 경로 매개변수에 따옴표를 붙여야 한다.

2단계: 의존성 설치 + 빌드

저장소 루트(즉, 1단계에서 생성된 디렉터리, 예: ~/archview)에서:

pnpm install
pnpm build

실행 후 일어나는 일: 여섯 개 패키지가 각각 컴파일된다. 다섯 개 node 패키지는 tsc로 dist/를 만들고, packages/web은 Vite로 packages/web/dist/를 만든다(패널 프론트엔드 산출물, 서비스가 이걸로 페이지를 가진다).

성공했는지 어떻게 아는가: packages/cli/dist/bin/archview.js와 packages/web/dist/index.html이 모두 존재하고, 아래 명령이 도움말을 출력할 수 있는지 확인:

pnpm archview --help

pnpm install 최초 실행 시 WARN Failed to create bin at ... ENOENT가 한 줄씩 출력된다. 네 개 패키지의 bin이 모두 dist/를 가리키는데, 최초 install 시 dist/가 아직 존재하지 않으므로 pnpm이 node_modules/.bin/의 링크를 만들 수 없다(최근 GitHub에서 새 클론 실측 13개; 이전 실행에서는 12개 — 개수는 pnpm 버전과 store 레이아웃에 따라 약간 변하므로, 개수를 판단 기준으로 삼지 말 것, 이런 WARN이 보이면 정상으로 간주). 무해하다: 아래 모든 명령은 저장소 루트의 npm script pnpm archview(동일: node packages/cli/dist/bin/archview.js)를 사용하며, bin 링크에 의존하지 않는다. 실제 archview / archview-skill 명령을 얻으려면: pnpm build 후 pnpm install을 한 번 더 실행하면 이번에는 링크가 생성되고, 이후 pnpm exec archview --version과 pnpm exec archview-skill …을 사용할 수 있다. 원클릭 스크립트(scripts/setup.ps1 / setup.sh)를 사용했다면 이 단계는 이미 대신 처리된 것(build 후 install을 한 번 더 실행하고, 그 자리에서 archview-skill 링크가 있는지 검증) — 이것이 없으면 문서의 모든 pnpm exec archview-skill … 명령이 not recognized / Command "archview-skill" not found를 보고한다. 의도적으로 prepare 스크립트로 자동 컴파일을 추가하지 않았다 — 의존성만 설치하려는 경우(CI 캐시, 문서만 수정)에 Vite 전체 빌드를 기다리도록 강요해서는 안 되기 때문이다.

⚠️ typecheck는 build 이후에 실행해야 한다

pnpm -r run build       # 先这个
pnpm -r run typecheck   # 再这个

반대로 하면 반드시 실패하며, TS2307: Cannot find module '@archview/core'(또는 그 subpath, 예: '@archview/core/themes') or its corresponding type declarations가 출력된다. 이유는 패키지 간 타입이 각 패키지의 package.json의 exports → dist/*.d.ts를 거치는데, dist/는 gitignore되어 있기 때문이다: build하지 않으면 .d.ts가 없다. 저장소에는 TS project references도 없고, 타입을 src로 되돌리는 path alias도 없으므로, 이것은 설정 누락이 아니라 기존 속성이다 — 처음 보는 사람은 반드시 부딪히므로 순서를 기억하면 된다.

같은 메커니즘이 일상 개발에서도 문제를 일으킨다: 누군가 어떤 패키지의 src/에 새 export subpath를 추가하면, 다른 패키지는 그 패키지가 다시 build되기 전까지 typecheck를 통과하지 못한다. TS2307이 보이면 먼저 "build를 해야 하나"를 생각할 것.

3단계: 분석할 첫 번째 저장소 연결

여전히 ArchView 저장소 루트에 있다. 경로를 자신의 저장소로 바꾼다:

pnpm archview init d:/code/my-repo

실행 후 일어나는 일(다섯 단계, 각 단계는 멱등이며, 반복 실행은 현재 상태를 알려줄 뿐):

1. 환경 점검(Node 버전, 디렉터리 존재, git 저장소 여부)

2. 사용자 저장소에 CodeGraph 인덱스 .codegraph/codegraph.db 생성(이미 있으면 건너뜀)

3. .archview/config.json 작성(이미 있으면 덮어쓰지 않음; --force-config일 때만 다시 씀), 그리고 oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod에 따라 모듈 골격 자동 사전 채움

4. 멱등하게 사용자 저장소의 .gitignore에 마커가 있는 블록을 추가(자세한 내용은 제 7절)

5. archview/workspaces.json(작업공간 레지스트리)에 등록

성공했는지 어떻게 아는가: 마지막에 작업공간 id와 다음 단계 명령이 출력된다. 실제 실행 출력(이번에는 ArchView 자체 소스 복사본을 분석 대상 저장소로 사용):

[2/5] CodeGraph 索引（结构事实的唯一来源，铁律 1）
  → codegraph init "…/selfcopy"（大仓可能要几分钟，超时 1800s）
      *  Indexed 160 files
      •  2,142 nodes, 6,797 edges in 1.4s
  ✓ 索引建好了（exit 0，2.5s）-> …/selfcopy/.codegraph
[3/5] .archview/config.json
  ✓ 已写入：…/selfcopy/.archview/config.json
      模块识别：npmWorkspaces —— 自动识别命中 pnpm-workspace.yaml / package.json workspaces，6 个模块
[5/5] 登记进 workspaces.json
  ✓ 已登记：selfcopy -> …/selfcopy

接入完成。下一步：
  archview build selfcopy           # 建面板数据（codegraph sync + 建图 + 简报）
  archview serve --open             # 起服务（127.0.0.1:7420），打开列表页
  archview status selfcopy          # 随时看索引/图/摘要覆盖率/漂移

일반 옵션: --id <id>(URL에 들어가며, [a-z0-9][a-z0-9_-]*만 허용), --name "표시 이름", --skip-index, --telemetry-off, --json(기계 판독 가능: 작업공간 id, 구성/gitignore 동작, 모듈 식별 결과, 다음 단계 명령; 다섯 단계 진행 상황은 log 필드에). 전체 목록: pnpm archview init --help.

4단계: 패널 데이터 구축

pnpm archview build            # 只登记了一个工作区时可以不带 id
pnpm archview build my-repo    # 多个工作区时说清是哪个

실행 후 일어나는 일: codegraph sync(인덱스를 디스크에 맞춤) → 그래프 구축 → .archview/graph.json과 meta.json 작성 → .archview/briefs/*.json 생성(LLM용 구조 브리핑) → .gitignore 블록을 한 번 더 확인.

성공했는지 어떻게 아는가: 각 단계 앞에 ✓가 있고, 끝에 노드/엣지/모듈과 요약 커버리지가 제공된다. 이번 실제 실행:

  ✓ codegraph sync             319 ms  exit 0
  ✓ buildGraph                  72 ms  981 节点 / 3851 边 / 7 layer
  ✓ writeGraph                   6 ms
  ✓ writeMeta                    1 ms
  ✓ buildAllBriefs               3 ms  7 份简报
  ✓ ensureGitignoreBlock         0 ms  unchanged

  节点 981  边 3851（文件级 734）  文件节点 158  模块 7
  摘要 已应用 0  覆盖率 0.0%（分母＝文件节点＋框架组件）

커버리지 0%는 정상적인 첫 번째 결과다 — 의미 요약은 agent가 작성해야 하며, 제 6절 참조.

경고가 있을 때(요약이 실수로 하위 디렉터리에 넣어져 한 개도 읽히지 않음, config.json 검증 실패로 전체 폴백, modules.labels의 key가 어떤 모듈과도 일치하지 않음) build는 그것들을 따로 모아 다시 출력하고 수정 방법을 제공한다. 경고는 실패가 아니다, 그래프는 실제로 구축되었지만, 그런 것들은 적용되지 않았다.

스크립트/agent에서 결과를 파싱하려면 --json을 사용하라(--quiet보다 훨씬 유용: 완전한 RebuildResult를 제공한다 — steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide, 패널의 POST api/rebuild, MCP의 archview_rebuild와 동일한 객체):

pnpm archview build my-repo --json

언제든 실제 상태를 재확인:

pnpm archview status           # 不带 id 就把注册表里所有工作区各打一段
pnpm archview status my-repo --json

status의 숫자는 목록 페이지, MCP의 archview_status와 같은 함수에서 온다 — 서로 다른 두 커버리지가 나타나지 않는다.

5단계: 서비스 시작하여 그림 보기

pnpm archview serve --open

실행 후 일어나는 일: 하나의 프로세스, 하나의 포트가 모든 등록된 작업공간을 서비스한다. 기본 127.0.0.1:7420; 점유 시 자동으로 위로 찾는다(최대 20개), 명시적으로 --port를 주면 바꾸지 않고 점유 시 실패. 시작 시 일회성 session token을 출력하며, 모든 api/*가 그것을 검증한다.

성공했는지 어떻게 아는가: 배너가 다음과 같다(이번 실제 실행, token은 잘림):

  ArchView 服务已启动    127.0.0.1:7420（只绑本机）
  注册表                 …\workspaces.json
  工作区                 selfcopy
  面板产物               …\packages\web\dist
  🔑  http://127.0.0.1:7420/?token=be5fea76…27d1
  所有 api/* 都要带这个 token（?token= 或 x-archview-token 头）。token 每次启动随机生成，进程重启会换。
  Ctrl-C 停止。（进程重启会换 token。）

--token <사용자 지정 문자열>을 주면 마지막 두 줄이 "token은 --token으로 지정, 재시작해도 변하지 않음"으로 바뀌고 커밋하지 말라는 알림이 추가된다 — 문구는 "명시적으로 --token을 주었는지"에 따라 분기되므로, token을 고정한 사람이 적용되지 않았다고 생각하지 않도록 한다.

"패널 산출물" 줄은 실제로 존재하는 packages/web/dist를 가리켜야 한다 — 프론트엔드를 빌드하지 않으면 목록 페이지에 패널 프론트엔드가 빌드되지 않음이 명시적으로 표시되며, 이때 pnpm --filter @archview/web build를 실행한다.

목록 페이지의 각 작업공간은 카드 하나이며, 네 개 버튼: 패널 열기 / 데이터 재구축 / agent 프롬프트 복사 / 드리프트 상세.

이번 서비스 실측(모두 token 포함):

세 가지 호출 방식, 아무거나 선택

위의 모든 명령은 pnpm archview …(저장소 루트의 npm script)로 작성되어 있는데, 최초 install 후 즉시 사용 가능하고 bin 링크에 의존하지 않기 때문이다. 다른 두 가지 동등한 작성법:

# ① 直接跑 node，连 pnpm 都不要（脚本化、给 AI 用最省事）
node packages/cli/dist/bin/archview.js --help        # 总览
node packages/cli/dist/bin/archview.js init --help   # 每个子命令都有 --help
node packages/server/dist/bin/serve.js --port 7500   # 只起服务，跟 archview serve 是同一个 startServer
                                                    # 注意它没有 --help：给任何参数都直接起服务并常驻

# ② 真正的 archview 命令 —— 需要 bin 链接，也就是 build 之后再 install 一次
pnpm install                    # 这次不会再刷 ENOENT WARN，链接会建好（一键脚本已代你做过）
pnpm exec archview --version
pnpm exec archview-skill --help

②는 이 저장소 안에서만 유효하다(bin 링크가 저장소의 node_modules/.bin/에 있음). 이 네 개 명령을 전역 PATH에 넣으려면 npm 경로(npm i -g archview)를 사용해야 하는데, 지금은 아직 publish되지 않았다 — 제 4절 참조.

6. agent가 의미를 채우게 하기

그래프가 구축된 후 노드는 있지만, 각 노드의 summary는 아직 결정적 폴백 문장(docstring / 시그니처에서 합성 / <이름> — <경로>의 <kind>)뿐이다. 그것을 사람이 읽을 수 있는 말로 바꾸는 것은 agent의 몫이다.

설치 없는 경로(먼저 이것 사용)

1. 목록 페이지에서 agent 프롬프트 복사 클릭(GET /w/<id>/api/prompt와 동일).

2. 프롬프트를 해당 저장소를 편집 중인 AI에게 붙여 넣기. 프롬프트는 매우 짧으며, 주로 작업공간의 <workspace>/.archview/AGENT-GUIDE.md를 가리키는 역할 — 로컬 파일이므로 어떤 도구든 읽을 수 있다.

3. AGENT-GUIDE.md는 한 번 생성해야 한다(build는 자동으로 생성하지 않음):

   pnpm archview skill guide --workspace d:/code/my-repo --write

   이번 실제 실행에서 22 KB(22185 바이트)를 작성했으며, 열 개 절: 철칙, 이 작업공간의 현재 모습, 구체적으로 어떤 요약이 누락되었는지(nodeId별로 하나씩 나열), 만료된 요약, 사용자 입력(구조 브리핑 경로), 감지된 언어에 따라 선택된 지침, 출력 형식과 제출 방식, 재구축 트리거 + 읽기 전용으로 현재 상태 확인하는 엔드포인트, 전달 전 자체 점검 목록, 보고 형식. 프롬프트에도 이 명령이 포함되어 있어 agent가 스스로 실행한다.

   한 번 생성하면 더 이상 신경 쓸 필요 없다: 이후 매번 재구축(패널 버튼 / archview build / POST api/rebuild / MCP archview_rebuild) 시 전체가 다시 작성된다(계약 제 2절이 요구하므로 gitignore에 있다). 재구축의 steps에서 writeAgentGuide 단계가 실행되었는지 볼 수 있다. 반대로, 파일이 없을 때 재구축이 대신 생성하지 않는다 — 사용자가 요청하지 않은 파일을 작업공간에 넣지 않는다.

4. agent는 가이드에 따라 .archview/summaries/<분할>.json에 요약을 쓴다. 분할 이름 = 모듈 key의 /를 _로 바꾼 것(모듈 packages/core → packages_core.json). 이 디렉터리는 평평하며, 하위 디렉터리에 쓴 요약은 한 개도 읽히지 않는다(경고는 발생하지만, 그 라운드의 작업은 헛수고).

5. 재구축: pnpm archview build, 또는 목록 페이지에서 "데이터 재구축" 클릭, 또는 agent가 직접 POST /w/<id>/api/rebuild?token=….

6. 패널에 의미가 나타나고, status의 커버리지가 올라간다.

요약 제출에는 서버 측 가드레일이 있다(기본값은 packages/core/src/limits.ts): 각 항목 30–140자, 태그 ≤6개이고 각각 ≤16자, 단일 배치 ≤200개(초과 시 전체 배치 거부, 한 개도 디스크에 쓰지 않으며, 잘리지 않음), 추가로 "빈말 단어 목록"이 "관련 로직을 담당하여 처리" 같은 헛소리를 차단한다. 임계값과 단어 목록의 실체는 하나뿐이며, @archview/core에 있다: MCP는 그것으로 집행하고, skill은 동일한 것으로 가이드를 작성한다 — 설명서와 집행자가 불일치하지 않도록(역사적으로 이 버그가 있었다).

⚠️ 가드레일은 MCP 제출 경로에서만 자동 집행된다. 위 4단계처럼 요약 분할 파일을 직접 쓸 때는 아무것도 검사하지 않는다(잘못 써도 오류가 보고되지 않고 조용히 패널에 들어간다). 따라서 파일을 직접 쓴 후 자체 점검을 한 번 실행하며, 판단 기준은 MCP와 완전히 동일한 코드(@archview/core의 checkSummaryItem):

pnpm exec archview-skill check-summaries --workspace d:/code/my-repo

# 报 "archview-skill not found" 就是 bin 链接还没建（build 之后没再 install 过）。
# 两条出路，任选一条：
pnpm install                                     # 补上链接，之后上面那条就能用
node packages/skill/dist/bin/skill.js check-summaries --workspace d:/code/my-repo   # 不依赖链接

항목별로 고아 nodeId, 길이 초과, tags 개수/길이/결정적 태그와의 충돌, 빈말 적중, hash가 현재 content_hash와 같은지, 추가로 summaries/ 아래에 하위 디렉터리가 있는지, 분할 JSON이 유효한지 보고; 불합격 항목이 있으면 종료 코드가 0이 아님. AGENT-GUIDE의 방식 A 단락과 자체 점검 목록이 모두 그것을 가리킨다.

고급 경로: skill + MCP 설치

token을 더 절약하고(소스를 끝까지 읽을 필요 없이 구조 브리핑만 읽으면 됨), 제출 시 구조화된 검증이 있다.

pnpm archview skill hosts                    # 支持哪些宿主与各自的路径依据
pnpm archview skill install kiro --dry-run   # 先看它要动哪些文件（什么都不写）
pnpm archview skill install kiro             # 真装
pnpm archview skill verify                   # 语言/框架指导自检

실측: skill hosts가 7개의 확인된 호스트(kiro, claude, cursor, codex, opencode, gemini, copilot CLI)와 명확히 지원하지 않는 목록을 나열한다(경로가 플랫폼/버전에 따라 변하고 재현 검증이 불가능한 것은 추측하지 않으며, /skill/download로 수동 배치). skill verify 실측 "언어 지침 38개, 프레임워크 지침 10개, 모두 존재, 비자리표시자, 모두 업스트림 표기와 ArchView 개조 단락 포함".

Kiro 우선: skill은 ~/.kiro/skills/archview에 설치, agent 정의는 ~/.kiro/agents/archview.json, MCP는 ~/.kiro/settings/mcp.json에 작성. 설치 프로그램은 병합하되 덮어쓰지 않는다(mcpServers.archview 하나의 키만 건드림), 기존 파일을 다시 쓰기 전에 .bak-<타임스탬프>를 남기고, Windows는 symlink가 아닌 junction을 사용한다. --dry-run은 쓸 내용을 원문 그대로 출력하며(실측: 한 바이트도 쓰지 않음), --home <dir>으로 HOME을 다른 곳으로 지정해 시험할 수 있다.

MCP 구성은 skill을 설치하지 않고 직접 복사할 수도 있다: AGENT-GUIDE.md와 api/prompt의 meta.mcp.snippet에 바로 붙여 넣을 수 있는 조각이 포함되어 있으며, 같은 저장소에 이미 빌드된 packages/mcp/dist/bin/mcp.js를 가리킨다.

여섯 개 MCP 도구, 읽기 전용 + 요약 제출, 그래프를 쓰는 도구는 전혀 없음:

어떤 호스트든 skill 패키지를 직접 다운로드할 수 있다: GET /skill/download(tar.gz), 또는 GET /skill/*로 단일 파일을 평문으로 열람(예: /skill/SKILL.md).

7. 데이터 위치 / 무엇을 git에 커밋해야 하는가

이 절이 머신을 바꾼 후에도 요약이 남아 있는지를 결정한다. 데이터는 모두 분석 대상 저장소에 있으며, ArchView 저장소에 있지 않다:

<你的仓库>/
  .codegraph/            CodeGraph 索引（SQLite，外部工具的，我们只读）   → 不提交
  codegraph.json         CodeGraph 的排除清单，可选、手写                 → 写了就提交（团队共享口径）
  .archview/
    config.json          语言、模块策略与标签、边阈值、输出语言           → **提交**
    summaries/*.json     LLM 摘要，按模块分片                             → **提交**（这是资产）
    graph.json           派生图，面板的数据源                             → 不提交
    meta.json            content_hash 快照（漂移检测的依据）              → 不提交
    briefs/*.json        给 LLM 的结构简报                                → 不提交
    AGENT-GUIDE.md       给 agent 的操作说明（每次生成整份重写，含时间戳）→ 不提交

판단 기준은 단 하나: 사람과 LLM이 모은 것은 커밋하고, 도구가 다시 계산할 수 있는 것은 커밋하지 않는다.

• summaries/는 수백 개의 사람/LLM이 작성한 중국어 요약으로, 재생성하려면 실제 비용이 드는 토큰이 필요하다. 코드와 함께 이동한다 — 머신을 바꾸고, 사람을 바꾸고, 에이전트를 바꿔도 그대로 남아 있다.

• config.json은 팀이「모듈을 어떻게 나눌지, 엣지 임계값을 얼마로 할지, 어떤 언어로 출력할지」에 대해 합의한 내용이다.

• 나머지는 모두 archview build가 10초 안에 다시 계산할 수 있다. AGENT-GUIDE.md는 특히 커밋하면 안 된다: 재빌드할 때마다 전체를 다시 쓰고 타임스탬프가 붙기 때문에, 커밋하면 충돌만 만들 뿐이다.

archview init와 매번 rebuild는 멱등적으로 당신 저장소의 .gitignore에 이 블록을 추가한다(마커로 식별하므로 반복 실행해도 중복 추가되지 않고, 기존 줄도 건드리지 않는다):

# >>> archview >>>
.codegraph/
.archview/graph.json
.archview/meta.json
.archview/briefs/
.archview/AGENT-GUIDE.md
# .archview/summaries/ 与 .archview/config.json 故意不忽略——它们要提交
# <<< archview <<<

ArchView 저장소 자체의 .gitignore

이 저장소의 .gitignore는 node_modules/, dist/(다섯 패키지의 tsc 산출물과 packages/web의 Vite 산출물이 이름이 같아서 한 줄로 커버), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/와 *.db*, *.log, .env*, 에디터 디렉터리, 그리고 **workspaces.json**을 제외한다.

workspaces.json은 워크스페이스 레지스트리로, 내용은 이 머신의 절대 경로(d:/code/my-repo)이며 머신마다 다르다 — 그래서 새로 클론한 저장소에서는 이 테이블이 반드시 비어 있다. 이것은 결함이 아니라 설계다. archview init로 직접 만들면 된다.

8. 인수 테스트 스크립트

다섯 개의 스크립트와 한 벌의 단위 테스트를 합쳐 150여 개의 단언이 있다. 대부분은「서비스 시작 → 테스트 → 종료」방식이라 상주 프로세스를 남기지 않고, 검사 대상 워크스페이스에 대한 쓰기는 되돌릴 수 있다.

공통 전제 조건은 단 하나: pnpm build. 프로토콜 계층의 세 스크립트(packages/server/scripts/acceptance.mjs, packages/mcp/scripts/acceptance.mjs, final-check.mjs)는 --workspace를 주지 않으면 일회용 fixture 워크스페이스를 직접 만든다 — 워크스페이스를 준비할 필요가 전혀 없다. 낯선 환경에서 클론한 뒤 바로 node final-check.mjs를 실행하면 된다. 오직 packages/core/scripts/selfcheck.mjs만 여전히 실제 워크스페이스 디렉터리를 반드시 줘야 한다.

아래「실측」열에는 두 벌의 숫자가 있다: fixture 모드(기본값, 아래 참조)와 --workspace <id>로 실제 워크스페이스를 대상으로 한 값. ArkTS 전용 단언은 fixture와 ArkTS가 아닌 워크스페이스에서는 명시적으로「건너뜀 / 해당 없음」으로 표시되며, 실패로 간주하지 않는다.

「건너뜀」과「실패」의 경계: 해당 검사의 전제 조건이 이 워크스페이스에서 성립하지 않을 때만 건너뛴다(그래프에 .ets 노드가 없음 → ArkTS 하이라이트를 검사할 수 없음; layer가 1개뿐 → 모듈 간 연결선이 성립할 수 없음). 다중 모듈 워크스페이스에서 모듈 간 연결선이 없으면 진짜 버그이며, 그대로 실패로 보고한다(먼저「철칙 4 파일 수준 엣지」가 0인지 확인하라 — 상위 집계가 없으면 모듈 개요 연결선도 없다).

기본 경로는 사용자 데이터를 한 바이트도 건드리지 않는다

프로토콜 계층 인수 테스트에는 두 가지 모드가 있고, 경계는 --workspace 유무다:

• --workspace를 주지 않음(기본값): 스크립트가 os.tmpdir() 안에 일회용 fixture 저장소를 직접 만든다(scripts/lib/fixture-workspace.mjs: pnpm-workspace.yaml + 4개 패키지, 패키지 간 깊은 경로의 실제 크로스 모듈 import, class/function/interface를 포함한 10여 개의 .ts, git init + 커밋 1회, 가드레일에 맞춰 작성된 요약이 분할마다 ≥ 2개), CodeGraph 인덱스를 돌리고 그래프를 두 번 만들고, 자체 임시 레지스트리에 등록한 뒤 실행이 끝나면 삭제한다. 당신의 저장소, 당신의 요약, 저장소 루트의 workspaces.json은 한 바이트도 건드리지 않는다. fixture를 남겨두고 싶다면: --keep-fixture.

• --workspace <id>를 줌: 그 실제 워크스페이스에서 실행하며, 시작 전에 박스로 이번에 무엇을 쓸지 눈에 띄게 알려준다. mcp 쪽은 해당 워크스페이스의 .archview/에 쓴다(요약 하나를 옮겨서 갭을 만들고, graph.json을 수정하고, rebuild를 실제로 한 번 실행). 백업 / 파일별 sha256 검증 / 먼저 복사 후 rename / 종료 시 비교, 가드레일이 하나도 빠지지 않는다.

왜 기본값을 fixture로 바꿨는가. 「일부러 스텁 데이터를 쓰지 않고, 실제 숫자여야 가치가 있다」는 이유는 packages/core/scripts/selfcheck.mjs에만 성립한다 — 이 스크립트는 builder가 실제 코드에서 보이는 의미론을 검증한다(2253개의 auto-corrected 경고도 실제 데이터에서만 드러났다). 반면 server / mcp의 인수 테스트는 엔드포인트 동작과 도구 프로토콜을 검증하므로, 작은 저장소를 직접 만드는 것으로 충분하다. 그러나 대가는 실제였다: 이 스크립트들은 요약 항목을 삭제하고, graph.json을 수정하고, rebuild를 실제로 실행한다. 이전 두 차례의 수정(복원 로직 수정, 「레지스트리 첫 번째 항목」 기본 폴백 제거, 백업 검증 추가)은 모두 근본 원인을 건드리지 않았다 — 기본 대상이 사용자의 실제 저장소인 한, 안전은 언제나「모든 백업 코드가 틀리지 않았다」에만 의존하며, 사고(한 번의 restore()가 워크스페이스의 재생 불가능한 사람 작성 요약 308개를 조용히 삭제했는데도 스크립트가 PASS 복원 완료라고 보고)가 이미 이 가정이 성립하지 않음을 증명했다.

rebuild의 쓰기 범위는 .archview/보다 한 겹 더 넓어서, 백업 목록도 함께 따라간다. ensureGitignoreBlock은 **워크스페이스 루트의 .gitignore**를 건드린다(덮어쓰기 전 원문은 .gitignore.archview-bak에 남는다). 그래서 mcp 인수 테스트의 백업 목록은 이제 워크스페이스 루트 기준으로 해석한다: .archview/graph.json, .archview/meta.json, .archview/briefs, .archview/summaries, .archview/AGENT-GUIDE.md, .gitignore, .gitignore.archview-bak. 백업 → 파일별 sha256 검증 → 복원 → 종료 시 비교, 이 두 루트 파일은 .archview/와 같은 경로를 거친다. (이전에는 목록이 .archview/ 기준으로 해석되어, 한 번의 --workspace 인수 테스트가 사용자의 .gitignore를 수정했는데도 가드레일이 전혀 몰랐다 — .archview/만 봤기 때문이다.) server 쪽 스크립트도 --workspace 모드에서 이 두 파일에 백업 / 복원 / 바이트 단위 비교를 추가했다.

목록 밖에서 유일하게 쓰이는 것은 .codegraph/codegraph.db다(codegraph sync가 수정한다): 일부러 복원하지 않는다 — 수십에서 수백 MB의 재생 가능한 인덱스를 백업에 복사하는 비용이 이득보다 훨씬 크다.

관리 블록 안의 줄은 더 이상 조용히 지워지지 않는다. 블록의 의미는 전체 교체이므로, # >>> archview >>>와 # <<< archview <<< 사이에 쓴 사용자 규칙은 이전에는 다음 rebuild 때 사라졌다. 이제 ensureGitignoreBlock은 블록 안에 자신이 생성한 줄이 아닌 것이 있으면 쓰기를 거부(refused)하고, 줄 번호와 원문을 rebuild 로그, archview status, 목록 페이지와 archview_status의 warnings에 보고하며, 한 바이트도 건드리지 않는다. 자신의 규칙은 블록 밖에 써라.

실행 전에 환경 변수 잔여물부터 정리하라

# PowerShell
Remove-Item Env:ARCHVIEW_ACCEPT_WS,Env:ARCHVIEW_WORKSPACES,Env:ARCHVIEW_MCP_WS,Env:ARCHVIEW_CHECK_WS -ErrorAction SilentlyContinue

# bash / zsh
unset ARCHVIEW_ACCEPT_WS ARCHVIEW_WORKSPACES ARCHVIEW_MCP_WS ARCHVIEW_CHECK_WS

ARCHVIEW_WORKSPACES가 바꾸는 것은 어느 레지스트리를 읽을지이고, ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS가 바꾸는 것은 어느 워크스페이스를 테스트할지다. 이것들이 셸에 한 번 남아 있으면, 「코드를 안 바꿨는데 인수 테스트 숫자가 달라졌다」는 가장 시간 낭비가 큰 착각이 생긴다 — 이미 다른 저장소를 테스트하고 있기 때문이다. 같은 원리가 명령줄에도 적용된다: archview init|build|status --workspaces <file>로 레지스트리를 명시적으로 지정할 수 있으니, 다중 레지스트리를 병렬로 쓸 때는 모든 명령에 적어 두는 것을 권장한다. 환경 변수로 상태를 기억하지 말라.

세 가지 함정, 겪어봐야 안다:

• selfcheck.mjs는 종료할 때 archview/.tmp/ 전체를 삭제한다(--keep을 주지 않으면), 자기 하위 디렉터리만이 아니라. .tmp/ 아래에 보관하고 싶은 것을 두지 말라.

• 프로토콜 계층 스크립트 세 개를 그냥 실행하면 이제 fixture를 직접 만들며, exit 1하지 않는다. 이전 버전은「--workspace를 안 주면 사용법을 출력하고 종료」였고, 지금은「안 주면 일회용 fixture 사용」이다. 그래서 node packages/mcp/scripts/acceptance.mjs를 바로 실행해도 통과한다 — 대상은 os.tmpdir() 안에 직접 만든 저장소이지, 당신의 저장소가 아니다.

• MCP 인수 테스트의「기존 분할에 쓸 때는 먼저 병합 후 쓰기」단언은, 선택된 분할에 갭 외에 다른 항목이 있어야 한다. 스크립트는 파일명 정렬 순서로 file 노드를 포함한 첫 번째 분할을 골라 갭을 만드는데, 그 분할에 요약이 정확히 하나뿐이면(예: 파일 하나뿐인 _other 모듈), 갭을 만든 뒤 분할이 비어서 이 단언이 성립할 수 없고 36/37 하나가 실패로 보고된다. fixture는 그래서 의도적으로 모든 file 노드에 요약을 쓴다(분할마다 ≥ 2개, 생성기에 하드 단언으로 지켜짐). 실제 워크스페이스에서 이 실패가 나오면 코드 문제가 아니라 워크스페이스 형태 문제다: 요약을 좀 더 충실히 쓰거나, 첫 번째 분할이 다중 파일 모듈에 대응하도록 하면 된다.

• --workspace 모드의「멱등 재구축」단언은 워크스페이스의 graph.json이 소스 코드와 동기화되어 있어야 한다. 단언은 재구축 전후의 노드 수를 비교한다; 해당 저장소가 마지막 archview build 이후 소스 코드를 수정했다면, 재구축은 당연히 다른 노드 수를 낸다(실측: 어떤 워크스페이스는 8972 → 8969, 소스에서 파일 하나가 빠졌기 때문), 36/37 하나가 실패로 보고된다. 이것은 워크스페이스 상태 문제다: 먼저 archview build를 한 번 실행한 뒤 인수 테스트를 돌려라. fixture 모드에는 이 문제가 없다(그래프를 방금 만들었기 때문).

9. 실측 숫자(출처 포함)

숫자는 저장소 내용에 따라 변하므로, 각 항목마다 어느 저장소인지, 언제인지, 어떤 기준인지 명시한다.

A. ArchView가 자기 자신을 분석(이번에는 이 README를 쓰기 위해 재실행; 분석 대상은 ArchView 소스 코드의 사본이며, node_modules/, dist/, .tmp/ 제외; Windows 11 / Node 22.20.0 / pnpm 10.28.2):

숫자는 소스 코드 변경에 따라 흔들린다: 같은 기준을 이전의 더 이른 소스 코드 버전에서 돌리면 899 노드 / 6 모듈 / 618 파일 수준 엣지 / 6쌍 모듈 사이 148개 집계 엣지가 나온다. 차이는 전부 소스 코드 자체가 커진 데서 오는 것이지, 기준이 바뀐 것이 아니다 — 그러니 이 숫자들을 기준값으로 단언하지 말고, 단언하려면 인수 테스트 스크립트를 돌려라.

B. AMCL(작성자 머신의 HarmonyOS / ArkTS 애플리케이션, ohpm 다중 모듈) — 이 숫자들은 읽기 전용으로 관측한 것이다(이미 만들어진 graph.json을 읽었고, 재구축하지 않음): 8972 노드 / 27864 엣지 / 11 모듈 / 파일 수준 엣지 3216 / 요약 308개(커버리지 308 / 682, 그중 프레임워크 컴포넌트 71), 모듈 전략 ohpm. 더 이른 버전에서 같은 기준은 4277 노드 / 16124 엣지 / 10 모듈 / 요약 304 — 차이는 전부 그 애플리케이션 자체가 커진 데서 온다. packages/core/src/limits.ts의 요약 길이 구간(40–80자)은 바로 이 사람 작성 요약들에서 측정한 것이다: min 36 / p50 57 / p95 78 / max 108자.

C. 인수 테스트용 일회용 fixture 저장소(scripts/lib/fixture-workspace.mjs가 만들고 바로 지우므로, 이 숫자는 매번 같아서 기준값으로 쓸 수 있다): 4개 pnpm 패키지 / 13개 .ts / 20개 파일 → CodeGraph 인덱스 0.8s → 49 노드 / 150 엣지 / 4 모듈 / 파일 수준 엣지 43 / 요약 13개(커버리지 13/13), 모듈 전략 npmWorkspaces, 모듈 개요 6쌍 모듈 사이 26개 집계 엣지, gitCommitHash는 진짜다(git init + 커밋 1회). 디렉터리 생성부터 그래프 준비까지 약 2.0s.

10. 알려진 제한 / 누가 쓰지 말아야 하는가

정직한 목록. 과장하지 않는다.

• 단일 머신 도구이며, 다중 사용자 모델이 없습니다. 127.0.0.1에만 바인딩되고, 인증은 프로세스 수준의 일회성 세션 토큰 하나뿐입니다. 계정도, 역할도, 감사(audit)도 없습니다. 외부 네트워크에 노출하지 말고, 팀 서비스로 배포하지도 마세요.

• 동시 재구축은 상호 배타적이지만, 락을 얻지 못하면 대기하지 않고 바로 실패합니다. 세 개의 진입점(패널 / archview build / MCP의 archview_rebuild)은 동일한 파일 락 .archview/.rebuild.lock을 사용합니다. 두 번째 요청은 즉시 "다른 프로세스가 재구축 중입니다(pid X, Y부터 시작)"라는 메시지를 받고, HTTP 계층에서는 409를 반환합니다. 일부러 대기시키지 않습니다. 대기시키면 브라우저가 계속 로딩 상태가 되고, 두 번의 전체 codegraph sync를 연속으로 실행해도 당신에게 가치가 없기 때문입니다. 교착 상태 자가 치유는 두 가지입니다 — 같은 머신에서 락을 보유한 프로세스가 더 이상 없거나, 30분이 초과된 경우입니다. 락은 재구축만 보호합니다. "재구축하는 동안 누군가 수동으로 summaries/를 수정하는" 상황은 다루지 않으며, 그런 경우 마지막으로 디스크에 쓴 것이 우선합니다.

• 디스크 쓰기는 원자적입니다(같은 디렉터리의 임시 파일 + rename). graph.json / meta.json / briefs/ / 요약 샤드 / config.json / 레지스트리를 덮어씁니다. 정전이나 강제 종료로 인해 반쯤 쓰인 파일이 남지 않습니다. 요약 샤드에는 두 가지 추가 안전장치가 있습니다. 이전 내용을 읽을 수 없으면 덮어쓰기를 거부하고, 항목 수는 증가하거나 동일할 때만 허용합니다(자세한 내용은 CONTRACT.md 5절 참조).

• /skill/download와 /skill/*는 토큰을 검증하지 않지만, 읽을 수 있는 것은 화이트리스트로 제한됩니다. 이들은 패키지와 함께 배포되는 skill 문서(SKILL.md, languages/*.md, frameworks/*.md)를 반환하며, 원래 어떤 agent 호스트든 직접 가져갈 수 있도록 의도된 것이므로 일부러 접근 제어를 두지 않았습니다. 탐색 가능한 컬렉션 == 패키지와 함께 배포되는 컬렉션이며, 둘은 동일한 디렉터리 순회를 공유합니다. 그 순회는 node_modules / dist / .git을 제외하고 실제 파일만 수용하므로 — 심볼릭 링크는 모두 컬렉션에 포함되지 않습니다. 이 부분은 보완된 것입니다. 기존 구현은 ".. 금지 + 접두사 검사"만 수행하여 전통적인 경로 탐색은 막았지만, pnpm이 packages/skill/node_modules/@archview/core에 배치한 packages/core를 가리키는 링크(링크의 텍스트 경로는 skill 디렉터리의 하위 경로이므로 접두사 검사를 통과함)는 막지 못했습니다. 실제 테스트에서 GET /skill/node_modules/@archview/core/src/builder.ts가 200과 25KB의 소스 코드를 반환했습니다 — 이는 더 이상 "토큰 없는 트레이드오프"가 아니라, 인증 없는 임의 파일 읽기입니다. 당신의 코드를 읽을 수 있는 엔드포인트(api/graph.json, api/file, api/rebuild …)는 모두 토큰을 검증합니다.

• 요약 품질은 전적으로 당신의 agent와 당신이 부여한 예산에 달려 있습니다. ArchView는 "토폴로지가 진짜다"와 "빈말을 쓰지 않는다"만 보장하며, 요약이 잘 쓰여질 것이라고는 보장하지 않습니다. 안전장치는 빈말 어휘 목록에 있는 헛소리는 막을 수 있지만, "맞지만 쓸모없는" 한 문장은 막을 수 없습니다.

• HarmonyOS / ArkTS가 유일하게 충분히 검증된 시나리오입니다. ohpm 모듈 인식, ArkUI 컴포넌트 트리 두 홉 접기, .ets 하이라이트는 모두 실제 ArkTS 프로젝트에서 다듬어졌습니다. 다른 언어는 구조 계층 검증(인덱싱 가능, 그래프 생성 가능, 모듈 인식 가능, 패널 렌더링 가능)만 수행했으며, 특화된 프레임워크 추론은 없고, 언어 가이드도 문서 수준의 자체 점검만 수행했습니다.

• Windows에서만 체계적으로 인수 테스트를 실행했습니다. macOS / Linux 플랫폼 분기는 작성되었지만 테스트되지 않았습니다.

• "아무 저장소나 한 번에 이해하는" 도구가 아닙니다. 처음 init할 때 대형 저장소는 몇 분이 걸릴 수 있고(CodeGraph 인덱스), 요약은 agent가 여러 라운드를 실행해야 합니다. 장기적으로 유지 관리할 프로젝트에 적합하며, 10분 만에 낯선 저장소를 훑어보는 용도에는 적합하지 않습니다.

• 모듈 개요의 layer 간 엣지는 무방향입니다. vendored된 aggregateLayerEdges는 A→B와 B→A를 병합합니다. 방향 정보는 드릴다운 뷰에 여전히 존재합니다.

• "패키지 루트 barrel"을 통한 크로스 패키지 import는 해석되지 않으므로, 모듈 개요에서 엣지가 누락될 수 있습니다. CodeGraph는 깊은 경로의 크로스 패키지 참조(import … from '../../server/src/rebuild.js' 같은)는 해석할 수 있지만, import { startServer } from '@archview/server' — 즉 패키지 진입점을 가리키고 package.json의 exports가 다시 구현 파일로 전달하는 형태 — 는 대상 심볼을 해석하지 못하므로 이 의존성은 그래프에 들어가지 않습니다. 이 저장소 자체가 예입니다. packages/cli/src/commands/serve.ts는 barrel을 사용하며, 브리프의 importsFrom에 server가 없습니다. build.ts는 깊은 경로를 사용하며 해석됩니다. 모듈 개요에서 확실히 존재한다고 믿는 엣지가 하나 누락된 것을 보면, 먼저 이 원인을 의심하세요(브리프에서 해당 파일의 importsFrom을 확인하세요. 비어 있거나 대상이 없으면 그것이 원인입니다). 이는 상위 CodeGraph의 해석 능력 경계이며, 구성 가능한 항목이 아닙니다. 우리는 일부러 builder에서 패키지 이름으로 이 엣지를 추측하여 보완하지 않습니다 — 추측된 토폴로지는 LLM이 토폴로지를 쓰는 또 다른 형태이며, 철칙 1을 위반합니다. 정말로 그래프에서 그것을 보고 싶다면, 해당 import를 깊은 경로로 변경하거나(또는 CodeGraph가 지원할 때까지 기다리세요).

• 엣지는 confidence / resolvedBy로 필터링됩니다(기본 임계값 0.7, heuristic은 버림). 필터링하지 않으면 이름만으로 우연히 만들어진 가짜 모듈 의존성이 나타날 수 있습니다(실제로 confidence: 0.3의 fuzzy 엣지가 존재함). 반대로, 필터링된 진짜 의존성도 보이지 않게 됩니다.

• CodeGraph 원격 측정은 기본적으로 켜져 있지만, 우리가 대신 호출할 때는 항상 DO_NOT_TRACK=1과 CODEGRAPH_NO_UPDATE_CHECK=1을 포함합니다(runCodegraph에 작성되어 있으며, 선택 사항이 아닙니다). 전역 스위치도 끄려면: pnpm archview init … --telemetry-off.

• 소스 코드 탐색 엔드포인트에는 하드 제한이 있습니다. /w/<id>/api/file은 그래프에 나타난 filePath만 허용하고(화이트리스트), ..와 절대 경로를 거부하며, 최대 1MB, 바이너리를 거부합니다.

11. 아키텍처와 패키지 구조

archview/
  package.json            pnpm workspace 根（scripts: build / typecheck / selfcheck / archview）
  LICENSE  NOTICE  README.md  CONTRACT.md
  AGENTS.md               仓库根路牌（多个 agent 工具会自动读它）：装 → SETUP-FOR-AI，改代码 → CONTRACT
  SETUP-FOR-AI.md         给 AI 的一次性安装剧本（阶段 + 成功判据 + 决策点 + 失败对策）
  scripts/setup.ps1       一键准备（Windows）：取代码 + install + build + 补 bin 链接 + 自检。幂等，不碰你的仓库
  scripts/setup.sh        同上（macOS / Linux；只做过 bash -n 语法检查，未在真实 Unix 上跑过）
  workspaces.json         工作区注册表（本机绝对路径，不提交）
  final-check.mjs         整体验收（起→测→停）
  packages/
    core/     图模型与校验（vendored UA schema）、CodeGraph 读取、builder(CG→图)、
              模块策略、框架 deriver、结构简报、.archview/ 布局与选择性 gitignore、
              提交护栏阈值与空话词表（唯一真身）
    web/      vendored 改造的 dashboard。按 /w/<id>/api/* 取数，中文默认开
    server/   单端口服务：工作区列表页 + 每工作区的面板与只读 API + rebuild
              bin: packages/server/dist/bin/serve.js   (archview-serve)
    mcp/      MCP server（stdio）。六个工具，只读 + 提交摘要
              bin: packages/mcp/dist/bin/mcp.js        (archview-mcp)
    skill/    SKILL.md 顶层提示词、38 份语言指导 + 10 份框架指导、
              AGENT-GUIDE.md 生成器、多宿主安装器
              bin: packages/skill/dist/bin/skill.js    (archview-skill)
    cli/      统一入口：init | build | serve | status | skill
              bin: packages/cli/dist/bin/archview.js   (archview)

"여섯 개 패키지"와 pnpm install이 출력하는 Scope: all 7 workspace projects는 같은 것을 말합니다. packages/ 아래에는 실제로 여섯 개 패키지가 있습니다. 일곱 번째는 저장소 루트 자체(archview)입니다. pnpm은 워크스페이스 루트도 하나의 project로 간주합니다. 자체 package.json과 scripts가 있기 때문입니다. 루트 project는 dist/를 생성하지 않고, 배포하지도 않습니다 — 단지 pnpm build / pnpm typecheck / pnpm archview 같은 script만 담당합니다. 7을 보고 뭔가 더 설치된 것으로 오해하지 마세요.

cli는 어떤 로직도 다시 구현하지 않습니다. build는 server의 rebuildOnce를 호출하고, status는 inspectWorkspace를 호출하며, serve는 startServer를 호출하고, skill은 archview-skill에 그대로 전달합니다. 이유는 패널, MCP, 명령줄이 같은 일에 대해 같은 숫자를 반환해야 하기 때문입니다 — 커버리지 같은 지표가 두 출처를 가지면, 두 숫자는 반드시 갈라집니다.

데이터 흐름을 한 문장으로:

你的源码 ──tree-sitter──▶ .codegraph/codegraph.db ──builder──▶ .archview/graph.json ──▶ 面板 / MCP
                                                        ▲
                            .archview/summaries/*.json ──┘  （只贡献 summary 与 tags）
                                     ▲
                        你的 LLM agent ┘（读 .archview/briefs/*.json，不读源码）

12. 라이선스와 감사

ArchView 자체는 MIT입니다(LICENSE). 그것은 또한 같은 MIT인 두 프로젝트 위에 서 있습니다.

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. 패널, 그래프 스키마, 검증기, skill, 언어/프레임워크 가이드가 모두 여기서 왔습니다. 우리는 전체를 vendor하고 개조했으며, 각 vendored 파일의 머리에는 상위 경로와 무엇을 변경했는지가 적혀 있습니다.

• CodeGraph — MIT, © Colby McHenry. 모든 구조적 사실의 출처입니다. vendor하지 않았습니다. 우리는 배포된 npm 패키지에 의존하며, SQLite 인덱스만 읽고, 그 bin을 호출합니다.

파일별 출처와 두 프로젝트의 전체 저작권 표기는 NOTICE에 있습니다. 이 프로젝트가 유용하다면, 먼저 위 두 저장소에 별을 눌러주세요 — ArchView는 단지 그것들을 연결했을 뿐입니다.

13. 뭔가 바꾸고 싶다면

먼저 CONTRACT.md를 읽으세요(AGENTS.md는 agent를 위한 한 페이지 요약이며, 같은 곳을 가리킵니다). 그것은 하드 제약의 기반이지, 스타일 가이드가 아닙니다 — 네 가지 철칙(LLM이 토폴로지를 쓰지 않음 / summary 비어 있지 않음 / layer가 모든 파일 노드를 덮음 / 파일 수준 엣지는 반드시 상위로 롤업), 동결된 노드 ID 체계, 그래프 스키마, 모듈 전략, 서비스 엔드포인트 표, MCP 도구 표면, 모두가 거기에 있으며, 각각 "왜"와 "위반하면 어떤 일이 발생하는지"가 적혀 있습니다. 그 중 하나라도 위반하는 것은 설계 오류입니다.

특히 두 곳을 주의하세요.

• 노드 ID 체계는 동결되어 있습니다. 요약 파일은 노드 ID를 키로 사용하므로, ID를 바꾸는 것은 모든 사람의 기존 요약 자산을 무효화하는 것과 같습니다.

• 그래프 스키마는 vendored된 UA 스키마와 완전히 일치하며, 더하거나 빼지 않습니다. 패널은 그대로 가져온 것이므로, 스키마가 바뀌면 패널도 바꿔야 합니다. 비공개 정보는 노드의 passthrough 필드를 통해 전달됩니다(엣지는 passthrough가 아니며, 추가 필드는 조용히 제거되므로 의존하지 마세요).

수정 후 최소한 다음을 실행하세요:

pnpm -r run build                      # 一定在 typecheck 之前
pnpm -r run typecheck
pnpm --filter @archview/server run test
node packages/core/scripts/selfcheck.mjs --workspace <你的工作区目录>   # 只有这个必须给真实工作区
node packages/server/scripts/acceptance.mjs                    # 不给 --workspace = 自建一次性 fixture
node packages/mcp/scripts/acceptance.mjs                       # 同上；给了 --workspace 它才会写那个工作区
node final-check.mjs                                           # 同上；只读

실행 전에 먼저 ARCHVIEW_* 환경 변수 잔여물을 제거하세요(8절에서 두 셸의 명령을 제공했습니다). 그렇지 않으면 다른 저장소를 테스트하고 있을 수 있습니다.