원챗 AI-OS 완전판 설치 매뉴얼 (중앙코어 A방식 + 답+화면 동기화)

이 문서 하나만 읽으면, 다른 AI가 자기 사이트에 "원챗 AI-OS"를 설치할 수 있습니다.
실제 운영 코드(aihos.kiam.kr 중앙코어 + mct.kiam.kr 첫 연결)를 기준으로 작성했습니다.
버전: 1.0 · 2026-07-09 · 아리

0. 한 줄 요약

"채팅으로 시스템을 움직이는 로봇 비서(AI-OS)" 를, 두뇌는 중앙 한 곳(aihos)에 두고 사이트는 링크로 연결해서 설치한다.
중앙을 고치면 연결된 모든 사이트가 자동으로 바뀐다. 사이트는 "자기 도구(손발)"만 정의한다.

1. 큰 그림 (아키텍처)

                      🧠 중앙 두뇌 (aihos.kiam.kr) — 여기만 고치면 전 사이트 자동
    ┌──────────────────────────────────────────────────────────┐
    │  /aios-core.js   클라 엔진 (도킹위젯 · 실행기 · 답화면동기화)   │
    │  /api/os         오케스트레이터 (DeepSeek function-calling ·   │
    │                  멀티턴 루프 · 확인게이트 · 답화면동기화)       │
    │  aihosdb.sites   사이트별 열쇠 · 도구스키마 · page_map · 프롬프트│
    └───────────────┬──────────────────────────────────────────┘
        링크 연결(복사X)│  ┌── 사람 로그인은 각 사이트에서 (중앙 회원가입 없음)
    ┌───────────────┴──────────────┬───────────────── … 100개 사이트
  사이트 A                        사이트 B
  · <script src=aihos/aios-core.js>  (엔진 = 중앙에서 로드)
  · window.AIOS_SITE_CONFIG          (열쇠 · onNavigate · commands)
  · POST /aios/exec                  (손발 = 자기 DB에서 데이터 실행)

두 층으로 나눠 이해하기 (가장 중요한 원칙)

엔진(두뇌)은 공용 — 어느 사이트나 똑같음. 중앙(aihos)에 한 벌. 고치면 전부 반영.
도구(손발)는 사이트별 — 사이트마다 메뉴·데이터·기능이 다름. 각 사이트가 자기 것 소유.
비유: Windows(엔진)는 어느 PC에나 깔리지만, 각 PC의 프로그램(도구)은 다르다.

신원(인증) 두 종류

신원	어디서	무엇
👤 사람 회원	각 사이트	사이트가 이미 쓰는 로그인(세션/토큰) 그대로. 중앙은 회원가입 없음
🏠 사이트 열쇠	aihosdb에 1회 등록	`site_id` + `api_key`. 등록된 사이트만 중앙 두뇌 사용 가능

2. 중앙코어 구성 (이미 구축됨 · 참고용)

새 사이트를 연결할 때는 중앙을 건드리지 않는다. 아래는 중앙이 어떻게 생겼는지 이해용.

서버: bigserver /var/www/webapp/aihos, DB aihosdb(MariaDB), vhost aihos.kiam.kr (Apache+php-fpm, nginx 금지)
DeepSeek: deepseek-v4-flash, base https://api.deepseek.com/v1 (키는 중앙 config)
파일:
public/aios-core.js — 클라 엔진 (CORS 허용, 사이트가 <script src>로 로드)
public/api/os.php — 오케스트레이터 (/api/os로 rewrite)
includes/config.php — DB·DeepSeek 설정
DB 테이블:
sites(site_id, name, api_key, exec_url, exec_secret, tools_schema, page_map, system_prompt, active)
core_versions(version, channel, notes) — 버전/롤백
usage_log — 사용 기록

3. 새 사이트 연결 — 3단계

① 사이트 조사 (도구 목록 뽑기) ★ 사이트마다 다름

그 사이트에서 AI가 할 수 있는 일을 뽑아 도구로 정의한다. 3종류로 분류:

x_exec	뜻	실행 위치	예시
`client`	화면 조작	브라우저(사이트)	`navigate`(메뉴 이동), `open_external`, `highlight`
`server`	데이터 조회	사이트 서버(exec)	`find_resource`, `get_overview`, `list_resource`, `get_detail`
`write`	데이터 변경	사이트 서버(exec, 확인게이트 후)	`create_`, `update_`

조사 체크리스트:
- [ ] 이 사이트의 메뉴/화면 목록은? → navigate의 page enum + 각 화면 키
- [ ] 무엇을 조회할 수 있나(목록·검색·상세·통계)? → server 도구
- [ ] 무엇을 만들거나 바꿀 수 있나? → write 도구 (확인게이트 필수)
- [ ] 어떤 답변이 어떤 화면과 연결되나? → page_map (답+화면 동기화)

② aihosdb에 등록 (사이트 열쇠 발급)

중앙 DB sites에 이 사이트를 등록한다. api_key는 랜덤 발급. (PHP 등록 스크립트 §7-A)

넣을 것:
- site_id (예: mct, shop), name
- api_key (랜덤 32~48자 hex — 사이트 열쇠)
- exec_url (사이트의 도구 실행 엔드포인트. 같은 서버면 http://127.0.0.1:포트/aios/exec)
- exec_secret (중앙↔사이트 공유 비밀)
- tools_schema (§7-B의 도구 배열 JSON — 각 function에 x_exec 표시)
- page_map (§답+화면 동기화)
- system_prompt (사이트 성격 + 답+화면 동기화 지시)

③ 사이트에 배선 (2가지)

(가) 프론트: 엔진 로드 + 설정 — 로그인된 화면에 아래를 넣는다.

<script>
window.AIOS_SITE_CONFIG = {
  site_id:  'mysite',
  api_key:  'aihosdb에서_발급받은_열쇠',
  api_url:  'https://aihos.kiam.kr/api/os',   // 중앙 두뇌
  title:    '원챗 AI-OS',
  getToken: function(){ return localStorage.getItem('내사이트_세션토큰') || ''; }, // 사용자 식별
  onNavigate:  function(page){ /* 이 사이트의 화면 이동 함수 */ mySiteGoTo(page); },
  canNavigate: function(page){ return true; },  // (선택) 권한 체크
  commands: [ /* 명령 예시 100선 — 사이트별 (§7-C 틀) */ ],
};
</script>
<script src="https://aihos.kiam.kr/aios-core.js"></script>  <!-- 엔진 = 중앙에서 -->

→ 우하단 🤖 버튼 → 클릭 시 우측 도킹 패널. 📋로 명령 100선. 끝.

(나) 백엔드: 도구 실행 엔드포인트(exec) — server/write 도구를 자기 DB로 실행.

POST {exec_url}
헤더:  X-AIOS-SECRET: {exec_secret}
본문:  { "tool":"find_resource", "args":{...}, "user_token":"사용자세션토큰" }

동작:
  1) X-AIOS-SECRET 검증 (아니면 403)
  2) user_token으로 로그인 사용자 식별 (테넌트/권한 스코프)
  3) tool/args로 자기 DB 조회·변경 실행
  4) 반환:
     - 조회(server): { ...데이터... }  (AI가 이 데이터로 답변 생성)
     - 변경(write) : { "msg":"완료 메시지", "actions":[{"name":"navigate","args":{"page":"..."}}] }

(구현 예시 §7-D)

★ 답 + 화면 동기화 (핵심 기능)

"AI가 답을 하면서, 그 답이 있는 화면도 같이 열어준다."

동작: 조회·검색·설명 답변 시 → 그 데이터/주제와 관련된 화면으로 navigate를 자동 추가.

2중으로 보장:
1. 서버 안전망(page_map) — 중앙 os.php가 server 도구 실행 후, page_map을 보고 관련 화면으로 자동 이동. AI가 깜빡해도 보장.
2. AI 유도(system_prompt) — "데이터든 개념설명이든 관련 화면으로 navigate 먼저" 지시.

page_map 형식 (aihosdb.sites.page_map, JSON):

{
  "tool:get_overview": "dashboard",     // 특정 도구 → 화면
  "type:salesperson":  "org",           // find/get_detail의 type → 화면
  "type:account":      "customerhub",
  "type:lead":         "customerhub",
  "default":           "customerhub"    // 그 외 조회 기본 화면
}

→ 사이트마다 자기 표를 가진다. 코드 수정 없이 표만 고치면 규칙이 바뀐다.

system_prompt 예시 문구 (반드시 포함):

- ★답변+화면 동기화(중요): 데이터 조회든 개념 설명이든 특정 주제로 답할 때는
  그 주제 화면으로 navigate를 먼저 호출한 뒤 설명하세요. '○○가 뭐야?' 같은 개념
  질문도 예외 없이 관련 화면으로 이동. (매핑은 사이트 화면에 맞게)
- 오직 '무엇을 할 수 있어?' 같은 사용법 질문만 이동 없이 답합니다.

★ 쓰기 확인게이트 (안전장치)

write 도구는 즉시 실행하지 않는다. 중앙이 자동 처리:
1. AI가 write 도구 호출 → 중앙이 HMAC 서명 토큰(만료 300초) 발급 → {say:"…실행할까요?", confirm:{token}}
2. 위젯이 [✅ 실행]/[취소] 버튼 표시
3. [실행] → 중앙에 {confirm_token, decision:"approve"} → 토큰·사이트 검증 후 사이트 exec로 실제 실행
4. [취소] → 아무것도 안 함

→ 사이트는 write 실행 코드만 exec에 두면 되고, 확인 절차는 중앙이 알아서 한다.

★ mimicry 방지 (반드시 지킬 것)

대화 이력(history)을 중앙에 보내지 않는다. 각 명령을 독립 처리한다.
- 이유: 이전 "…이동했습니다" 같은 assistant 텍스트가 쌓이면, DeepSeek이 그걸 흉내내어 도구 호출을 생략하고 말로만 답하는 버그가 있다(실제 겪음). 어떤 반복 텍스트든 유발한다.
- 그래서 aios-core.js는 history를 빈 배열로 보낸다. 맥락이 필요하면 사용자가 대상을 명시.

4. 검증 (설치 후 필수)

각 유형을 실제로 던져 확인:
- [ ] 이동: "○○ 화면 열어줘" → 왼쪽 화면이 실제로 바뀜 (navigate 동작)
- [ ] 조회+동기화: "○○ 몇 개야?" → 답변 + 관련 화면 자동 이동
- [ ] 검색+상세: "△△ 정보 알려줘" → find → get_detail → 실데이터 요약
- [ ] 쓰기: "○○ 만들어줘" → [실행]/[취소] 버튼 → [실행] 시에만 실제 생성
- [ ] 일반/개념: "○○가 뭐야?" → 설명 + 관련 화면 이동
- [ ] 권한/보안: 미등록 사이트 403, exec secret 없으면 403, write는 확인 없이 실행 안 됨

권장: Playwright(헤드리스 브라우저)로 위 시나리오를 실제 클릭·입력해 자동 검증하면 확실하다.
DNS 전파 전이면 --host-resolver-rules=MAP aihos.kiam.kr {중앙IP} 로 지정.

5. 중앙 업데이트 / 롤백

엔진(aios-core.js)·오케스트레이터(os.php)를 중앙에서 고치면 → 연결된 전 사이트 자동 반영.
core_versions에 버전 기록. 문제 시 이전 파일로 롤백(백업 필수).
사이트별 도구/화면 규칙만 바꾸려면 → 그 사이트의 sites 행(tools_schema·page_map)만 수정. 코드 배포 불필요.

6. 자주 겪는 함정 (실전 교훈)

DeepSeek base는 /v1 — .../v1/chat/completions. 빠뜨리면 응답 없음.
빈 properties:{} 함수 — PHP json_decode→encode가 {}를 []로 바꿔 DeepSeek 400. → tools 스키마는 원본 JSON 문자열 그대로 payload에 넣는다.
CORS — os.php는 Access-Control-Allow-Origin: * + OPTIONS 204. aios-core.js도 CORS 허용.
exec의 사용자 스코프 — user_token으로 사용자를 세팅해야 테넌트/권한이 맞는다.
답화면동기화 navigate 중복 — AI가 직접 navigate를 부르면 서버 자동추가는 건너뛴다(중복 방지).
php-fpm opcache — config 상수 바꾸면 systemctl reload php8.0-fpm.

7. 복붙 템플릿

7-A. 사이트 등록 스크립트 (PHP, 중앙에서 1회 실행)

<?php
require '/var/www/webapp/aihos/includes/config.php';
$tools = [ /* §7-B */ ];
$page_map = [ 'tool:get_overview'=>'dashboard', /* … 사이트별 */ ];
$system = "당신은 '이 사이트' AI-OS 비서입니다. … (답화면동기화 문구 포함)";
$api_key = bin2hex(random_bytes(24));
aihos_db()->prepare("INSERT INTO sites(site_id,name,api_key,exec_url,exec_secret,tools_schema,page_map,system_prompt,active)
  VALUES(?,?,?,?,?,?,?,?,1) ON DUPLICATE KEY UPDATE api_key=VALUES(api_key),exec_url=VALUES(exec_url),
  exec_secret=VALUES(exec_secret),tools_schema=VALUES(tools_schema),page_map=VALUES(page_map),
  system_prompt=VALUES(system_prompt),active=1")
  ->execute(['mysite','내사이트',$api_key,'http://127.0.0.1:PORT/aios/exec','내exec비밀',
    json_encode($tools,JSON_UNESCAPED_UNICODE), json_encode($page_map,JSON_UNESCAPED_UNICODE), $system]);
echo "api_key=$api_key\n";   // 이 값을 프론트 config에 넣는다

7-B. 도구 스키마 (OpenAI function-calling + x_exec)

[
  {"type":"function","function":{
    "name":"navigate","x_exec":"client",
    "description":"메뉴/화면 이동. 각 page 키의 의미를 여기 적는다.",
    "parameters":{"type":"object","properties":{
      "page":{"type":"string","enum":["dashboard","목록","상세", "..."]}},"required":["page"]}}},
  {"type":"function","function":{
    "name":"get_overview","x_exec":"server","description":"핵심 통계.",
    "parameters":{"type":"object","properties":{}}}},
  {"type":"function","function":{
    "name":"find_resource","x_exec":"server","description":"이름/키워드로 찾기.",
    "parameters":{"type":"object","properties":{
      "query":{"type":"string"},"type":{"type":"string","enum":["종류1","종류2"]}},"required":["query"]}}},
  {"type":"function","function":{
    "name":"get_detail","x_exec":"server","description":"항목 상세.",
    "parameters":{"type":"object","properties":{
      "type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"]}}},
  {"type":"function","function":{
    "name":"list_resource","x_exec":"server","description":"목록.",
    "parameters":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"]}}},
  {"type":"function","function":{
    "name":"create_item","x_exec":"write","x_confirm":"새 항목을 생성합니다",
    "description":"생성(확인 후 실행).",
    "parameters":{"type":"object","properties":{"필드":{"type":"string"}}}}}
]

⚠️ get_overview처럼 인자 없는 함수는 "properties":{} (빈 객체) — 중앙이 원본 JSON을 그대로 넘기므로 안전.

7-C. 명령 예시 100선 틀 (프론트 config.commands)

commands: [
  { cat:'현황·요약', icon:'📊', items:['오늘 현황 요약','○○ 몇 개야?', ...] },
  { cat:'화면 이동', icon:'🧭', items:['대시보드 보여줘','○○ 화면 열어줘', ...] },
  { cat:'찾기·상세', icon:'🔍', items:['△△ 정보 알려줘', ...] },
  { cat:'목록·개수', icon:'📋', items:['○○ 목록', ...] },
  { cat:'필터·검색', icon:'🔎', items:['□□만 보여줘', ...] },
  { cat:'만들기(확인)', icon:'➕', items:['○○ 만들어줘', ...] },
  { cat:'분석·성과', icon:'🏆', items:['○○ 분석', ...] },
  { cat:'도움말', icon:'💡', items:['너 뭐 할 수 있어?', ...] },
]

7-D. exec 엔드포인트 (사이트 서버 · PHP/파이썬 등 무관, 개념)

POST /aios/exec  (X-AIOS-SECRET 헤더 검증)
  body: {tool, args, user_token}
  u = 세션토큰(user_token)으로 사용자 조회   # 테넌트/권한 스코프
  switch(tool):
    'get_overview'  -> return { counts... }
    'find_resource' -> return { results:[{type,id,label}...] }
    'get_detail'    -> return { detail:{...} }
    'list_resource' -> return { items:[...] }
    'create_item'   -> 실제 INSERT
                       return { msg:"생성했어요 (#id)", actions:[{name:'navigate',args:{page:'목록화면'}}] }

8. 실전 사례 — mct.kiam.kr (첫 연결, 검증 완료)

site_id: mct · 도구 6종(navigate=client / get_overview·find_resource·get_detail·list_resource=server / create_lead=write)
page_map: 영업자→org, 리드·거래처·기회→customerhub, 전체현황→dashboard
exec: mctbiz Flask /aios/exec (X-AIOS-SECRET, biz_token으로 사용자 식별, 테넌트 스코프)
프론트: SPA에 AIOS_SITE_CONFIG(onNavigate=SPA navigate) + aios-core.js 로드
검증: Playwright로 이동·조회+동기화·쓰기확인·개념설명 전부 PASS
효과: mct는 두뇌·위젯 코드를 안 갖고 "열쇠+손발"만. 중앙 고치면 자동 반영.

9. 새 사이트 연결 요약 체크리스트

[ ] 1. 사이트 조사 → 도구 목록(client/server/write) + 화면 키 + page_map 정리
[ ] 2. aihosdb.sites 등록 (api_key 발급) — §7-A
[ ] 3. 프론트: AIOS_SITE_CONFIG + <script aios-core.js> — §3-가
[ ] 4. 백엔드: /aios/exec 엔드포인트 (X-AIOS-SECRET, user_token 스코프) — §3-나
[ ] 5. 검증: 이동/조회+동기화/검색상세/쓰기확인/개념 전부 — §4
[ ] 6. (선택) Playwright 자동검증

→ 이 6단계면 어느 사이트든 원챗 AI-OS(답+화면 동기화 포함)가 설치된다.
→ 중앙은 건드리지 않는다. 중앙을 고치면 이 사이트도 자동으로 좋아진다.

문서 버전 1.0 · 2026-07-09 · 원챗 AI-OS 중앙코어(aihos.kiam.kr) 기준