[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81465":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":27,"discoverSource":28},81465,"agent-safety-oss","ratelworks\u002Fagent-safety-oss","ratelworks","건설현장의 법정 안전문서 작성을 더 빠르고 정확하게. 산안법·기준규칙·중처법·KOSHA Guide를 기반으로 안전관리자와 현장소장의 문서 작성과 검토를 돕는 오픈소스 도구입니다.",null,"TypeScript",33,4,31,1,0,2,3,45.3,"MIT License",false,"main",true,[],"2026-06-12 04:01:33","# agent-safety-oss\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg?branch=main)](https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss\u002Factions\u002Fworkflows\u002Fci.yml)\n[![CodeQL](https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss\u002Factions\u002Fworkflows\u002Fcodeql.yml\u002Fbadge.svg?branch=main)](https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss\u002Factions\u002Fworkflows\u002Fcodeql.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](.\u002FLICENSE)\n[![Node](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20.19-brightgreen)](https:\u002F\u002Fnodejs.org)\n[![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-1.x-purple)](https:\u002F\u002Fmodelcontextprotocol.io)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Frelease-v1.5.0-blue.svg)](.\u002FCHANGELOG.md)\n[![Tools](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP%20tools-92-orange.svg)](.\u002Fdocs\u002FIDENTITY.md)\n\n**건설현장의 법정 안전문서 작성을 더 빠르고 정확하게.** 산안법·기준규칙·중처법·KOSHA 기술지원규정(가이드)을 기반으로 안전관리자와 현장소장의 문서 작성과 검토를 돕는 오픈소스 도구입니다.\n\n[정체성](.\u002Fdocs\u002FIDENTITY.md) · [Claude Desktop 설정](.\u002Fdocs\u002FSETUP_CLAUDE_DESKTOP.md) · [Codex CLI 설정](.\u002Fdocs\u002FSETUP_CODEX.md) · [기술 상세 (운영 온톨로지)](.\u002Fdocs\u002FOPERATIONAL-ONTOLOGY.md)\n\n---\n\n## 한 눈에 — 안전관리자가 받는 가치\n\n> CLI(명령어 입력) 환경이 익숙하지 않아도 됩니다. AI 비서 (Claude Desktop · OpenAI Codex CLI) 가 본 도구를 호출해서 다음을 자동으로 해 줍니다.\n\n| 사용자가 하는 일 | AI 비서가 자동으로 해 주는 일 |\n|---|---|\n| \"**오늘 굴착 작업 TBM 만들어줘**\" 한 줄 요청 | 적용 KOSHA 가이드 5건 + 법령 6건 + 위험 3건 + 통제 16건 자동 발견 → 결재 가능한 초안 자동 작성 → 빠진 필수 항목 자동 검출 |\n| \"**추락 산재 발생 보고**\" 요청 | 산안법 §54·§57 등 법령 자동 인용 + 사고조사 기술지침 자동 인용 + 시간순 제출 순서 안내 |\n| \"**MSDS 비치대장**\" 요청 | 산안법 §114·§115 + KOSHA 화학물질 경고표지 가이드 + 보호구 자동 표시 |\n\n**작성 주체는 안전관리자, AI 비서는 옆에서 보조** (법적 판단·서명·제출 책임은 사람). 본 도구가 의무 문서를 자동 생성하더라도 결재 전 안전관리자 검토는 필수입니다.\n\n---\n\n## 무엇이 들어 있나\n\n| 영역 | 내용 |\n|---|---|\n| **\u003C!-- INV:DOCUMENTS_TOTAL -->19\u003C!-- \u002FINV:DOCUMENTS_TOTAL -->종 법정 안전관리 문서** | TBM · 작업계획서 · 위험성평가 · MSDS · 산재조사표 등 매일·매주·매월 작성하는 양식 |\n| **법령 \u003C!-- INV:LAW_BUNDLE_COUNT -->10\u003C!-- \u002FINV:LAW_BUNDLE_COUNT -->건 핵심 조문** | 산안법 · 시행령 · 시행규칙 · 기준규칙 · 중처법 · 위험성평가 고시 등 합계 \u003C!-- INV:LAW_ARTICLES -->76\u003C!-- \u002FINV:LAW_ARTICLES -->조 (전체 1,310조 중 건설안전 실무 핵심만 발췌. 전체 법령은 [법제처](https:\u002F\u002Fwww.law.go.kr) 직접 참조) |\n| **KOSHA 기술지원규정 (가이드) \u003C!-- INV:KOSHA_BODY -->1,039\u003C!-- \u002FINV:KOSHA_BODY -->건** | 한국산업안전보건공단 발행 기술지침 전체 본문 (인터넷 없이 즉시 검색·인용) |\n| **양식 \u003C!-- INV:FORMS_TOTAL -->132\u003C!-- \u002FINV:FORMS_TOTAL -->개** | 고용노동부·KOSHA 공식 HWP \u002F PDF \u002F XLSX 원본 + 자동 생성 Markdown 양식 |\n| **위험·통제 정보망** | 작업 → 위험요인 → 통제대책 → 법령 근거 → 문서 자동 연결 (\"의미 연결망\" — 자세히는 [기술 상세](.\u002Fdocs\u002FOPERATIONAL-ONTOLOGY.md)) |\n\n→ 위 자료들이 **서로 연결**되어 있어, \"굴착 작업\"이라는 한 단어만 알면 적용 법령·KOSHA 가이드·위험·통제·양식이 자동으로 따라옵니다.\n\n---\n\n## 어떻게 시작하나?\n\n| 사용자 환경 | 진입 경로 | 난이도 |\n|---|---|:---:|\n| **Claude Desktop \u002F OpenAI Codex CLI 이미 쓰는 분** (개발자 · IT 익숙) | 아래 \"5초 진입\" 카드 그대로 복사 → AI 비서가 본 도구 호출 | ⭐ 5초 |\n| **AI 비서가 뭔지 모르는 분** (안전관리자 · 현장소장) | [📖 Claude Desktop 설정 가이드](.\u002Fdocs\u002FSETUP_CLAUDE_DESKTOP.md) → 그림 따라하기 | ⭐⭐ 5분 |\n| **브라우저 폼만 쓰고 싶은 분** (CLI 안 익숙) | `npm install -g agent-safety-oss && agent-safety-oss serve` → 별도 viewer 실행 → 폼 화면에서 입력 → 본문 자동 생성 → MD 다운로드 (아래 \"A2UI 폼\" 섹션 참고) | ⭐⭐⭐ 10분 |\n\n---\n\n## 5초 진입 — Claude Desktop \u002F OpenAI Codex CLI 사용자\n\n> **\"AI 비서 도구 연결 표준\" (MCP) 을 지원하는 앱** (Claude Desktop · OpenAI Codex CLI) 의 설정 파일에 아래 한 블록을 추가하면 끝납니다. \u003C!-- INV:TOOLS_TOTAL -->92\u003C!-- \u002FINV:TOOLS_TOTAL -->개 도구가 모두 동작합니다 (\u003C!-- INV:TOOLS_KEYLESS -->85\u003C!-- \u002FINV:TOOLS_KEYLESS -->개는 인터넷 없이 동작, \u003C!-- INV:TOOLS_KEYREQ -->7\u003C!-- \u002FINV:TOOLS_KEYREQ -->개만 공공 OpenAPI 키 필요).\n\n### Claude Desktop (JSON 설정)\n\n설정 파일에 다음을 추가:\n```json\n{\n  \"mcpServers\": {\n    \"agent-safety-oss\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-safety-oss\", \"serve\"]\n    }\n  }\n}\n```\n\n설정 파일 위치:\n- **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n저장 후 Claude Desktop 을 완전 종료·재시작하면 도구 목록에 `agent-safety-oss` 가 보입니다.\n\n### OpenAI Codex CLI (TOML 설정)\n\n`~\u002F.codex\u002Fconfig.toml` 에 다음을 추가:\n```toml\n[mcp_servers.agent-safety-oss]\ncommand = \"npx\"\nargs = [\"-y\", \"agent-safety-oss\", \"serve\"]\n```\n\nCodex CLI 재시작 후 `codex mcp list` 로 등록 확인.\n\n자세한 안내:\n- [docs\u002FSETUP_CLAUDE_DESKTOP.md](.\u002Fdocs\u002FSETUP_CLAUDE_DESKTOP.md)\n- [docs\u002FSETUP_CODEX.md](.\u002Fdocs\u002FSETUP_CODEX.md)\n- 더 많은 예시: [examples\u002F](.\u002Fexamples\u002F)\n\n## 누구를 위한 것인가\n\n### 안전관리자\n\n- TBM, 위험성평가, 작업계획서, 작업허가서, MSDS 대장, 점검표, 사고보고서 초안을 만든다.\n- 법령, KOSHA Guide, 위험요인, 통제대책, 양식, 보존기간을 한 번에 확인한다.\n- LLM이 작성한 문서의 법령 인용, 필수 항목, 결재 가능 여부를 검수한다.\n- 사진 증빙, 안전 이슈, 개선조치, 운영 보고서를 로컬 기록으로 남긴다.\n\n### 현장소장\n\n- 오늘 작업의 위험, 필요한 보호구, 작업 전 조치, 작업허가 필요 여부를 빠르게 본다.\n- 사고 발생 시 보고 순서와 제출 문서를 시간순으로 확인한다.\n- 안전관리자가 부재하거나 겸임일 때도 최소한의 안전관리 문서 흐름을 놓치지 않는다.\n\n### 신규 담당자\n\n- 기존 담당자의 폴더 구조와 기억에 묶인 맥락을 `profile`, `drafts`, `documents`, `photos`, `issues`, `actions`, `reports`로 이어받는다.\n\n## 왜 필요한가\n\n건설 현장의 안전관리 자료는 보통 이렇게 흩어져 있습니다.\n\n```text\n법령 조문\nKOSHA Guide\n위험성평가표\nTBM 일지\n작업계획서\n작업허가서\nMSDS\n현장 사진\n개선조치\n보고서\n```\n\n자료는 존재하지만 서로 연결되지 않으면, 안전관리 품질은 시스템보다 담당자의 경험과 기억에 의존합니다. `agent-safety-oss`는 이 자료들을 다음 사슬로 연결합니다.\n\n```text\n작업 -> 위험요인 -> 통제대책 -> 법령 근거 -> 문서 -> 증빙 -> 개선조치 -> 보고\n```\n\nLLM은 이 그래프를 보고 문서를 작성하거나 설명할 수 있지만, 법령 근거를 임의로 만들지는 않습니다. 필수 항목이 비어 있으면 결재 불가 또는 보강 필요로 표시하고, 근거 없는 법적 표현은 검수 도구가 잡아냅니다.\n\n## 자동작성 흐름\n\n사용자는 자연어로 요청하고, Agent는 MCP 도구를 순서대로 호출합니다. 핵심은 문서를 바로 \"그럴듯하게\" 쓰는 것이 아니라, 그래프 컨텍스트를 먼저 조립하고, 초안을 만들고, 검수한 뒤 보관하는 것입니다.\n\n```mermaid\nflowchart LR\n  U[안전관리자 \u002F 현장소장] --> A[Claude Desktop \u002F Codex CLI]\n  A --> G[get_safety_document_guide]\n  A --> C[assemble_doc_context]\n  A --> P[get_site_profile]\n  G --> D[generate_safety_document]\n  C --> D\n  P --> D\n  D --> R[review_safety_document]\n  R -->|보강 필요| U\n  R -->|결재 가능| S[archive_safety_document]\n```\n\n자동작성은 다음 순서로 이해하면 됩니다.\n\n1. 사용자가 \"오늘 굴착 작업 TBM 만들어줘\"처럼 요청한다.\n2. Agent가 `get_safety_document_guide`로 양식 구조와 필수 항목을 확인한다.\n3. Agent가 `assemble_doc_context`로 법령, 위험요인, 통제대책, KOSHA Guide, 관련 문서를 가져온다.\n4. 등록된 현장 프로파일이 있으면 `get_site_profile` 결과로 사업장명, 현장명, 결재선을 채운다.\n5. `generate_safety_document`가 초안을 만든다.\n6. `review_safety_document`가 필수 항목, 법령 인용, 결재 가능 여부를 점검한다.\n7. 사용자가 보강하거나 승인하면 `archive_safety_document`로 로컬에 보관한다.\n\n예를 들어 TBM 요청은 내부적으로 이런 흐름이 됩니다.\n\n```text\n사용자:\n  오늘 4층 발코니 거푸집 양중 작업 TBM 만들어줘.\n\nAgent:\n  get_safety_document_guide({ docId: \"daily_tbm\" })\n  assemble_doc_context({ docId: \"daily_tbm\" })\n  get_site_profile()\n  generate_safety_document({ docId: \"daily_tbm\", draft: ... })\n  review_safety_document({ docId: \"daily_tbm\", draft: ... })\n\n결과:\n  TBM 초안\n  주요 위험요인\n  통제대책\n  필요 보호구\n  법령\u002FKOSHA 근거\n  미작성 필수 항목\n  결재 가능 여부\n```\n\n폼 UI와 함께 쓰는 경우에는 `render_a2ui_form`, `save_form_draft`, `load_form_draft`를 같이 사용합니다.\n\n```text\nrender_a2ui_form        docId 기반 입력 폼 생성\nsave_form_draft         Agent 또는 사용자가 입력한 값을 임시 저장\nload_form_draft         사용자가 수정한 값을 Agent가 다시 읽음\nsubmit_safety_document  A2UI 입력값을 실제 문서 생성 흐름으로 제출\ngenerate_safety_document\nreview_safety_document\narchive_safety_document\n```\n\n## 브라우저 입력 폼 — CLI 안 익숙해도 됨\n\n> **CLI(명령어 입력)가 익숙하지 않은 안전관리자·현장소장이 가장 편하게 쓰는 방법.** 브라우저 화면에 입력 양식이 뜨고, 법령 근거·KOSHA 가이드·위험요인·통제대책이 미리 채워져 있습니다. 빈 칸만 채우면 결재 가능한 문서가 자동 생성됩니다.\n\n설치 및 실행 (안전관리자가 한 번만):\n\n```bash\n# 1. Node.js 20.19+ 설치 (https:\u002F\u002Fnodejs.org)\n# 2. 본 도구 설치 + 빌드\nnpm install -g agent-safety-oss\ngit clone https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss.git\ncd agent-safety-oss\nnpm install && npm run build\n# 3. 브라우저 입력 폼 시작\nnpm run mcp:viewer\n# → 브라우저가 자동으로 http:\u002F\u002Flocalhost:5174 열림\n```\n\n브라우저에서 보이는 화면:\n\n1. **폼 종류 선택** (TBM 회의록 \u002F 굴착 작업계획서 \u002F 정기 위험성평가 \u002F MSDS 비치대장 등 \u003C!-- INV:DOCUMENTS_TOTAL -->19\u003C!-- \u002FINV:DOCUMENTS_TOTAL -->종)\n2. **자동 표시되는 영역** (그대로 결재 인용 가능):\n   - 적용 법령 조문 (산안법 \u002F 기준규칙 \u002F 위평고시 등) — 본문 그대로 발췌\n   - 적용 KOSHA 기술지원규정 (가이드) 평균 5건\n   - 위험요인 + 통제대책 + 필요 보호구\n3. **빈 칸 입력** — 작업일·작업명·참석자 등 사용자 입력 필요한 항목만 표시\n4. **본문 생성** 버튼 → 결재 가능한 문서 자동 작성\n5. **검수** → 빠진 필수 항목 \u002F 결재 가능 여부 \u002F 환각 차단 검증\n6. **MD 다운로드** 또는 LocalStorage 보관\n\n> PDF 출력이 필요하면 다운로드한 `.md` 를 [Pandoc](https:\u002F\u002Fpandoc.org\u002F) · 한글\u002F한컴오피스 · [Typora](https:\u002F\u002Ftypora.io\u002F) 등으로 변환합니다.\n\n> 이 폼은 [Google A2UI](https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fa2ui) (Agent-UI 표준) 기반으로 만들어졌습니다. 기술 상세는 [`docs\u002FOPERATIONAL-ONTOLOGY.md`](.\u002Fdocs\u002FOPERATIONAL-ONTOLOGY.md) 참조.\n\n## 빠른 시작\n\nNode.js 20.19 이상이 필요합니다. 아래 두 트랙 중 본인 환경에 맞는 것을 선택하세요.\n\n### Track A — Claude Desktop 사용자 (안전관리자·현장소장 권장)\n\n위 \"5초 진입\" 카드 참고. `npx` 가 자동으로 패키지를 받아 실행하므로 별도 설치 명령이 필요 없습니다.\n\n소스 빌드본을 직접 연결할 때는 다음처럼 지정합니다.\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-safety-oss\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fagent-safety-oss\u002Fbuild\u002Fcli.js\", \"serve\"]\n    }\n  }\n}\n```\n\n### Track B — 터미널 \u002F CI \u002F 개발자\n\n> **현재 상태**: v\u003C!-- INV:VERSION -->1.5.0\u003C!-- \u002FINV:VERSION --> npm publish 완료 (`npm view agent-safety-oss version` → `\u003C!-- INV:VERSION -->1.5.0\u003C!-- \u002FINV:VERSION -->`). 아래 두 경로 모두 동작합니다.\n\n```bash\n# 권장 — npm publish 본 (즉시 실행)\nnpx -y agent-safety-oss tools\nnpx -y agent-safety-oss serve\n# 또는 전역 설치\nnpm install -g agent-safety-oss\n\n# 소스 빌드 (개발자 \u002F fork)\ngit clone https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss.git\ncd agent-safety-oss\nnpm ci && npm run build\nnode build\u002Fcli.js tools\nnode build\u002Fcli.js serve\n```\n\nCLI 사용 예시는 [`examples\u002F`](.\u002Fexamples\u002F) 폴더의 `mcp-list-tools.sh`, `search-laws.sh`, `generate-tbm.sh` 참고.\n\n### 공공 데이터 연결 — 13 source 통합\n\n본 OSS 는 한국 공공 OpenAPI 와 portal 13 source 를 그래프 작성 보조에 통합합니다.\n\n**연결된 공공 데이터 source**:\n\n| Source | 영역 | 호출 도구 |\n|---|---|---|\n| KOSHA OneAPI 15121001 \u002F 15121008 | 재해사례 + 첨부 | `search_accident_cases` · `get_accident_case_attachments` |\n| KOSHA OneAPI 15133935 | 건설 사망사고 통계 | `search_construction_fatal_accidents` |\n| KOSHA OneAPI 15119137 | 전 업종 사망사고 | `search_all_fatal_accidents` |\n| KOSHA OneAPI 15139398 | 안전보건자료실 (외국인 13개국어) | `search_safety_materials` · `get_foreign_worker_resource_links` |\n| KOSHA OneAPI 15001197 | MSDS (화학물질안전) | `search_msds` |\n| KOSHA OneAPI 15139497 | 보호구 안전인증 (KCs) | `search_ppe_certification` |\n| KOSHA OneAPI 15123696 | 안전보건법령 스마트검색 (AI 유사어) | `search_safety_law_smart` |\n| KOSHA OneAPI 15144147 | KOSHA Guide PDF 다운로드 (현재 번들 \u003C!-- INV:KOSHA_BODY -->1,039\u003C!-- \u002FINV:KOSHA_BODY -->) | (offline 번들로 대체) |\n| KOSHA OneAPI 15087828 | 건설 공종 분류 (구조 분류) | `analyze_construction_work_risks` (fallback) |\n| KOSHA OneAPI 15116595 | 공종 ↔ KOSHA Guide 매핑 | `analyze_construction_work_risks` (fallback) |\n| KOSHA OneAPI 15140383 | SIF 아카이브 (사망 고위험요인) | `search_sif_archive` |\n| KOSHA portal24 | 안전보건자료실 8,976건 (OPS·동영상·교안) | `search_kosha_archive` · `list_kosha_archive_facets` · `get_kosha_archive_files` |\n| 법제처 OpenAPI (law.go.kr) | 안전관리 법령 10건 핵심 조문 발췌 (전문 아님) | (offline 번들 + 향후 동적 확장) |\n\n**키 없이 즉시 동작 — \u003C!-- INV:TOOLS_KEYLESS -->85\u003C!-- \u002FINV:TOOLS_KEYLESS -->개 도구**:\n- \u003C!-- INV:LAW_BUNDLE_COUNT -->10\u003C!-- \u002FINV:LAW_BUNDLE_COUNT --> 법령 본문 번들 검색 (`search_safety_laws`, `get_safety_law_article`, `list_core_safety_laws`)\n- \u003C!-- INV:KOSHA_BODY -->1,039\u003C!-- \u002FINV:KOSHA_BODY --> KOSHA Guide 본문 offline 조회 (`get_kosha_guide_md`)\n- 그래프 traversal (`assemble_doc_context`, `generate_safety_document`, `review_safety_document`)\n- 19종 법정문서 작성 보조 (위험성평가·작업계획서·TBM·MSDS·작업허가서 등)\n- 로컬 현장 기록 (사진·이슈·조치·보고)\n\n**키 필요 — \u003C!-- INV:TOOLS_KEYREQ -->7\u003C!-- \u002FINV:TOOLS_KEYREQ -->개 도구** (KOSHA OneAPI 실시간 호출):\n\n| 도구 | 영역 |\n|---|---|\n| `search_accident_cases` | 국내 재해사례 검색 |\n| `get_accident_case_attachments` | 재해사례 첨부 자료 |\n| `search_construction_fatal_accidents` | 건설 사망사고 |\n| `search_all_fatal_accidents` | 전 업종 사망사고 |\n| `search_safety_materials` | 안전보건자료 (외국인 자료 포함) |\n| `search_msds` | MSDS (화학물질) |\n| `search_ppe_certification` | 보호구 안전인증 |\n\n#### 키 발급 — 2 경로\n\n| 경로 | 방법 |\n|---|---|\n| **A. 라텔웍스 발행 키** | \u003Chttps:\u002F\u002Fratelworks.co.kr\u002Fagenthq\u002Fapi-key> 에서 무료 즉시 발급 (`ASF_xxxx_yyyy`). 단일 키로 7 도구 + KOSHA portal 호출 |\n| **B. 자체 data.go.kr 키** | data.go.kr 에서 KOSHA OpenAPI 즉시 신청·발급. `.env` 에 `DATA_GO_KR_KEY=...` 설정 |\n\n자세한 설정: `.env.example` + [docs\u002FSETUP_CLAUDE_DESKTOP.md](.\u002Fdocs\u002FSETUP_CLAUDE_DESKTOP.md).\n\n#### 향후 추가 가능 공공 데이터\n\n본 OSS 는 현재 12+ source 를 통합했으나, 다음 공공 데이터도 그래프 통합 후보입니다 (contributor 환영):\n\n- **법제처 OpenAPI** 동적 확장 (안전 외 인접 법령 — 산업안전기준에 관한 규칙 외)\n- **KOSHA-MS** 안전보건경영시스템 인증 사업장 명부\n- **KCs\u002FKCs Self** 안전인증·자율안전인증 통합 (현재 보호구만)\n- **고용노동부** 산업재해 통계연보 (분기·연도별 추이)\n- **국토교통부** 건설공사 안전관리 종합정보망 (CSI)\n- **환경부** 화학물질 정보 (PRTR · 유해성 등급)\n- **소방청** 위험물 안전관리 정보\n- **건설근로자공제회** 안전교육 이수 자료\n\n추가 요청은 [Issue](https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss\u002Fissues) 로 제안 가능.\n\n#### 키 등록 (A 경로)\n\n| 방법 | 동작 |\n|---|---|\n| 방법 1 — Claude 에 한국어로: \"라텔웍스에서 받은 AgentHQ 키 `ASF_xxxx` 를 등록해줘\" | `link_company_key` 도구가 호출되어 `~\u002F.agent-safety-oss\u002Fcompany-key.json` 저장 |\n| 방법 2 — 환경변수 | `AGENTHQ_API_KEY=ASF_xxxx` |\n\n## 실제 사용 예시\n\nClaude Desktop이나 Codex에서 자연어로 요청합니다.\n\n```text\n우리 현장은 30억, 상시 12명 건설현장이야.\n이번 달 작성해야 할 안전보건 문서와 보관기간을 정리해줘.\n```\n\n```text\n오늘 4층 발코니 거푸집 양중 작업 TBM 만들어줘.\n추락, 낙하물, 신호수 배치, 필요한 보호구까지 포함해줘.\n```\n\n```text\n신너 600을 도장 작업에 쓰는데 MSDS 비치대장 초안을 만들어줘.\n법령 근거, 교육, 게시 위치, 필요한 보호구도 같이 넣어줘.\n```\n\n```text\n중대재해가 발생했을 때 지금부터 어떤 보고를 몇 시간 안에 해야 하는지 알려줘.\n```\n\nAgent는 내부적으로 다음 도구들을 조합합니다.\n\n```text\nassess_my_obligations\nlist_safety_documents_by_cycle\nget_safety_document_guide\nassemble_doc_context\ngenerate_safety_document\nreview_safety_document\nverify_safety_basis\narchive_safety_document\n```\n\n## 현장 운영 흐름\n\n### 1. 현장 프로파일 등록\n\n한 번 등록하면 \u003C!-- INV:DOCUMENTS_TOTAL -->19\u003C!-- \u002FINV:DOCUMENTS_TOTAL -->종 법정문서 (\u003C!-- INV:DOCID_MASTER -->94\u003C!-- \u002FINV:DOCID_MASTER --> docId 마스터) 의 사업장명, 현장명, 대표자, 안전관리자, 현장소장, 결재선이 자동 채워집니다.\n\n```text\nregister_site\nregister_project\nregister_person\nregister_equipment\nregister_contractor\n```\n\n예시 요청:\n\n```text\n우리 회사 사업장 정보를 등록해줘.\n사업장명은 황룡건설, 대표자는 황한일이야.\n현장은 천안 신축현장, 공사금액은 30억, 상시근로자는 12명이야.\n안전관리자는 김안전, 현장소장은 이소장이야.\n```\n\n### 2. 의무 확인\n\n사업장 규모, 공사금액, 업종, 공사 단계에 따라 적용 문서와 마감, 보관기간을 확인합니다.\n\n```text\nassess_my_obligations\nlist_safety_documents_by_cycle\nlist_upcoming_duties\nquery_applicability\nget_submission_info\nget_retention_status\n```\n\n### 3. 문서 작성\n\n문서 하나를 만들 때 법령, 위험요인, 통제대책, KOSHA Guide, 관련 문서, 보존기간을 그래프에서 조립합니다.\n\n```text\nget_safety_document_guide\nassemble_doc_context\ngenerate_safety_document\nexport_drafted_document\nget_official_form\n```\n\n자동작성에서 가장 중요한 도구는 `assemble_doc_context`와 `generate_safety_document`의 조합입니다. 전자는 LLM이 추측하지 않도록 근거를 모으고, 후자는 그 근거를 결재 가능한 Markdown 문서로 합성합니다.\n\n### 4. 검수\n\n필수 항목 누락, 결재 가능 여부, 법령 인용 실존 여부, 근거 없는 법적 표현을 점검합니다.\n\n```text\nreview_safety_document\nverify_safety_basis\nquery_legal_basis\nquery_penalty\n```\n\n### 5. 사진, 이슈, 개선조치\n\n법정문서와 별개로 현장 운영 기록을 남깁니다.\n\n```text\nupload_photo_evidence\nregister_safety_issue\nrecord_corrective_action\ncomplete_action\ngenerate_safety_report\n```\n\n## 들어 있는 것\n\n- 패키지 버전: \u003C!-- INV:VERSION -->1.5.0\u003C!-- \u002FINV:VERSION -->\n- MCP 도구: \u003C!-- INV:TOOLS_TOTAL -->92\u003C!-- \u002FINV:TOOLS_TOTAL -->개 (keyless \u003C!-- INV:TOOLS_KEYLESS -->85\u003C!-- \u002FINV:TOOLS_KEYLESS --> · 키 필요 \u003C!-- INV:TOOLS_KEYREQ -->7\u003C!-- \u002FINV:TOOLS_KEYREQ --> · 라이선스 placeholder \u003C!-- INV:TOOLS_PLACEHOLDER -->2\u003C!-- \u002FINV:TOOLS_PLACEHOLDER -->)\n- 19종 법정 안전관리 문서: \u003C!-- INV:DOCUMENTS_TOTAL -->19\u003C!-- \u002FINV:DOCUMENTS_TOTAL --> (TBM·작업계획서·위험성평가·MSDS·산재조사표 등)\n- 법정의무 문서 마스터 (`legal-duty-master.json`): \u003C!-- INV:DOCID_MASTER -->94\u003C!-- \u002FINV:DOCID_MASTER --> docId (19종 + 사이클·범위·발주처별 변형)\n- 양식 인덱스 (`forms-map.json`): \u003C!-- INV:FORMS_TOTAL -->132\u003C!-- \u002FINV:FORMS_TOTAL --> formId — HWP \u003C!-- INV:FORMS_HWP -->14\u003C!-- \u002FINV:FORMS_HWP --> \u002F PDF \u003C!-- INV:FORMS_PDF -->23\u003C!-- \u002FINV:FORMS_PDF --> \u002F XLSX \u003C!-- INV:FORMS_XLSX -->1\u003C!-- \u002FINV:FORMS_XLSX --> (공식 양식) + 자동 생성 MD \u003C!-- INV:FORMS_MD -->94\u003C!-- \u002FINV:FORMS_MD -->개. HWP\u002FPDF\u002FXLSX 중 일부는 라이선스상 공식 다운로드 URL 안내로 대체.\n- 그래프 노드: 카테고리 1단계 \u003C!-- INV:GRAPH_TOPLEVEL -->2,212\u003C!-- \u002FINV:GRAPH_TOPLEVEL --> + KOSHA Guide 1,039 (서브디렉토리 포함 재귀) = 전체 **\u003C!-- INV:GRAPH_TOTAL -->3,369\u003C!-- \u002FINV:GRAPH_TOTAL -->** · 엣지 약 \u003C!-- INV:GRAPH_EDGES -->32,963\u003C!-- \u002FINV:GRAPH_EDGES --> (정확 카운트는 `npm run audit:strict`)\n- 핵심 작업\u002F위험\u002F통제: WorkActivity \u003C!-- INV:GRAPH_ACTIVITIES -->41\u003C!-- \u002FINV:GRAPH_ACTIVITIES --> \u002F Hazard \u003C!-- INV:GRAPH_HAZARDS -->38\u003C!-- \u002FINV:GRAPH_HAZARDS --> \u002F Control \u003C!-- INV:GRAPH_CONTROLS -->50\u003C!-- \u002FINV:GRAPH_CONTROLS -->\n- 법령 본문 번들: **\u003C!-- INV:LAW_BUNDLE_COUNT -->10\u003C!-- \u002FINV:LAW_BUNDLE_COUNT -->개 MD** — 산안법·시행령·시행규칙·기준규칙·중처법·중처법 시행령·위험성평가 고시·건진법·건진법 시행령·건진법 시행규칙 (합계 약 \u003C!-- INV:LAW_ARTICLES -->76\u003C!-- \u002FINV:LAW_ARTICLES -->조). 마지막 동기화: \u003C!-- INV:LAW_LAST_SYNC -->2026-05-18\u003C!-- \u002FINV:LAW_LAST_SYNC --> (`src\u002Fontology\u002Fsafety-laws\u002F*.md`)\n\n## (기술 상세) 온톨로지 설계 — 개발자·연구자용\n\n> 이 섹션부터는 **개발자·기술 연구자용 상세**입니다. 안전관리자·현장소장이 본 도구를 사용하는 데 이 내용을 알 필요는 없습니다.\n\n이 프로젝트는 세 계층 (Layer) 으로 안전 정보를 표현합니다.\n\n| 계층 | 역할 | 예 |\n|---|---|---|\n| Semantic Layer (의미 계층) | 안전관리 객체와 관계 정의 | Site, Project, WorkActivity, Hazard, Control, LegalArticle, SafetyDocument |\n| Kinetic Layer (실행 계층) | 그래프 객체에 대한 실행 가능한 MCP 도구 | `generate_safety_document`, `review_safety_document`, `register_safety_issue` |\n| Dynamic Layer (동적 계층) | LLM과 하네스의 상황 해석 + 도구 조합 | Claude Desktop, OpenAI Codex CLI |\n\n핵심 의미 사슬 (안전 정보 자동 연결):\n\n```text\nWorkActivity (작업)  →  Hazard (위험)  →  Control (통제대책)\nSafetyDocument (문서) →  LegalArticle (법령 조문)\nSafetyDocument        →  KOSHA Guide (가이드)\nPhotoEvidence (사진)  →  SafetyIssue (이슈) → CorrectiveAction (조치) → SafetyReport (보고)\n```\n\n채택 표준: JSON-LD 1.1, RDF\u002FOWL, SKOS, PROV-O, schema.org, ISO 45001. 런타임은 무거운 그래프 DB 없이 로컬 파일 + MCP 도구로 동작합니다. 자세한 운영 온톨로지 상세는 [`docs\u002FOPERATIONAL-ONTOLOGY.md`](.\u002Fdocs\u002FOPERATIONAL-ONTOLOGY.md), 핵심 객체 13종은 [`docs\u002FIDENTITY.md`](.\u002Fdocs\u002FIDENTITY.md) 참조.\n\n## 근거 등급\n\n| 근거 | 등급 | 문서에서의 의미 |\n|---|---|---|\n| 법령, 시행령, 시행규칙, 고시 | mandatory | 의무 판단과 제출 문서의 법적 근거 |\n| KOSHA Guide | recommended | 기술적 권고와 작업 방법 |\n| 재해사례, 안전보건자료, MSDS, 통계, 보호구 인증 | reference | 참고 자료와 교육 자료 |\n\nLLM이 \"의무\", \"반드시\", \"금지\", \"위반\" 같은 표현을 쓰면 `verify_safety_basis`가 법령 근거를 요구합니다.\n\n## 로컬 저장소\n\n사용자 데이터는 기본적으로 로컬에 저장됩니다.\n\n```text\n~\u002F.agent-safety-oss\u002F\n  profile.jsonld       사업장\u002F현장\u002F인원\u002F장비 프로파일\n  drafts\u002F              작성 중 초안\n  documents\u002F           보관 문서\n  photos\u002F              사진 증빙\n  issues\u002F              안전 이슈\n  actions\u002F             개선조치\n  reports\u002F             운영 보고서\n  traces\u002F              실행 추적\n```\n\n디렉터리는 `0o700`, 파일은 `0o600` 권한으로 생성됩니다.\n\n## 검증 상태\n\n최근 검증 결과:\n\n- 운영 온톨로지: 38\u002F38 통과\n- 그래프 추론: 5\u002F5 통과\n- 그래프 recall \u002F precision: 100% \u002F 100%\n- ISO 45001 카테고리 일관성: 100%\n- strict graph audit: 통과\n- 필드 워크플로우: 4\u002F4 시나리오, 29\u002F29 단계 통과\n- 실제 입력 반응성: 4\u002F4 시나리오 통과, 입력 문구 반영 S1 7\u002F7 · S2 7\u002F7 · S3 6\u002F6 · S4 6\u002F6\n- 현장 사용자 테스터: 안전관리자\u002F현장소장 수기 체크리스트와 피드백 양식 생성\n- 생성 문서 품질: 평균 8.65\u002F10\n- essence gate: 9\u002F9 통과\n- lightweight gate: 4\u002F4 통과\n\n검증 명령:\n\n```bash\nnpm run typecheck\nnpm run build\nnpm run ontology:operational\nnpm run mcp:test:graph\nnpm run mcp:test:real-input\nnpm run mcp:test:field-user\nnpm run audit:strict\nnpx tsx scripts\u002Ftest\u002Ffield-test-workflows.ts\nnpx tsx scripts\u002Fquality\u002Ffield-test-quality-eval.ts\n```\n\n## 현장 사용자 테스터\n\n실제 안전관리자나 현장소장이 생성 문서를 검토하듯 테스트하려면 다음 명령을 실행합니다.\n\n```bash\nnpm run mcp:test:field-user\n```\n\n결과는 `artifacts\u002Ftest-results\u002Ffield-user-tester\u002F`에 생성됩니다. 각 시나리오에는 실제 입력값, MCP 생성 문서, 자동 검토 결과, 수기 체크리스트, 피드백 양식이 함께 들어갑니다.\n\n```text\n01-input.json              실제 현장 입력\n02-generated.md            생성 문서\n03-review.txt              자동 검토 결과\n04-human-checklist.md      안전관리자\u002F현장소장 수기 체크리스트\n05-feedback-template.json  현장 피드백 기록 양식\n06-auto-evaluation.json    자동 판정 결과\n```\n\n테스터는 자동 통과 여부를 제공하지만, 최종 판단은 `04-human-checklist.md`의 수기 점수와 현장 피드백을 우선합니다.\n\n## 현재 한계\n\n- `safety_health_manager_appointment`는 19종 법정문서 중 CARV 추론 완성도 보강 대상으로 남아 있습니다.\n- `regular_risk_assessment`는 실제 입력 반영과 KRAS 결과표 작성은 통과하지만, 사용자 입력 `riskRows`에서 Hazard를 동적으로 역추론하는 깊이는 보강 대상입니다.\n- Site, Project, Contractor, WorkerRole은 런타임 프로파일 중심이며 정적 그래프 노드 물질화는 다음 단계입니다.\n- 사진 외 EvidenceType, 예를 들어 서명, 교육 참석, 제출 영수증, 점검 결과 증빙은 더 확장해야 합니다.\n- 최종 법적 판단, 서명, 제출 책임은 안전관리자와 사업장 책임자에게 있습니다.\n\n## 개발 환경\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fratelworks\u002Fagent-safety-oss.git\ncd agent-safety-oss\nnpm install\nnpm run build\nnpm run typecheck\nnpm run mcp:tools\n```\n\n## 제공 · 개발\n\n- **제공**: 황룡건설(주) 안전보건기획부 — 도메인 검증·현장 요구사항·시나리오 제공\n  - 대표자: 황한일 · 주소: 충청남도 아산시 염치읍 충무로431번길 9\n- **개발**: 주식회사 라텔웍스 (Ratelworks Inc.) — MCP 서버 설계·구현·오픈소스 유지. 공공 안전자료 접근성 개선. \u003Calphamale@ratelworks.co.kr>\n\n## 수상 이력\n\n- **2025.07** — 2025 AI·스마트 산업안전기술 우수사례 경진대회 **대상** (고용노동부장관상) · 황룡건설(주), 개발 ㈜라텔웍스\n- **2025.09** — 2025 위험성평가 우수사례 발표대회 **우수상** (대전지방고용노동청장상) · 황룡건설(주), 개발 ㈜라텔웍스\n- **2026.01** — 사이드임팩트 2025 AI 트랙 **우승** (브라이언임팩트재단) · ㈜라텔웍스\n\n## 라이선스\n\n- 코드: MIT\n- 법령 본문: 저작권법 제7조 비보호 저작물\n- KOSHA\u002F고용노동부 공개자료: 각 자료의 공공누리 조건 준수\n\n자세한 출처와 재사용 조건은 [NOTICE.md](.\u002FNOTICE.md)를 확인하십시오.\n","agent-safety-oss 是一个帮助建筑工地安全管理人员和现场负责人更快速准确地编写法定安全文档的开源工具。它基于韩国的安全生产法、标准规则、中处法以及KOSHA指南，通过AI助手（如Claude Desktop或OpenAI Codex CLI）自动发现适用的法规、风险和控制措施，并生成可审核的安全文件初稿。该项目采用TypeScript编写，支持多种使用场景，包括但不限于日常、每周、每月需要编写的TBM、作业计划书、危险性评估报告等。此外，即使对于不熟悉命令行环境的用户，也提供了简单的设置指南和浏览器表单界面，使得非技术人员也能轻松上手。","2026-06-11 04:05:11","CREATED_QUERY"]