@soddong/agentic-domain-document

@soddong/agentic-domain-document는 Agentic Platform의 문서 도메인 패키지입니다.

이 패키지는 Document, TOC Node, Content, Typed Block을 관리하기 위한 하위 도메인 패키지입니다. artifact-standard, artifact, methodology, knowledge 계열 패키지는 이 패키지를 참조해서 문서 구조와 본문 block을 사용할 수 있습니다.

Adoc은 이 패키지가 관리하는 Agentic Document의 공식 약칭입니다. Adoc은 Document/Node/Content/Block 기반으로 저장되며, Adoc Tree와 Adoc Markdown Projection으로 조회할 수 있습니다.

현재 범위

Iteration 1에서는 문서 도메인 SQLite schema baseline과 최소 Repository/Service/Validator API를 제공합니다.

| 구분 | 상태 | | --- | --- | | 패키지 skeleton | 포함 | | 기본 문서 | 포함 | | build/typecheck | 포함 | | pack dry-run | 포함 | | Document DB migration | 포함 | | Repository/Service/Validator | 포함 | | Document Reader | 포함 | | Adoc Markdown Projection | 기본 조회용 projection 포함, list/table/figure/diagram/callout 복원 포함 | | Markdown Import | 기본 전체 문서/챕터 import 포함, table/figure caption binding 포함 | | Public wrapper API | 포함 | | Document Agent contribution | 포함 | | CLI | 1차 구현 제외, 전체 lifecycle 검토 대상 | | Adapter | 1차 구현 제외, 전체 lifecycle 검토 대상 |

도메인 책임

@soddong/agentic-domain-document
  - Document
  - TOC Node
  - Content
  - Typed Block
  - Document validation
  - Document fixture
  - Document repository/service
  - Document reader/query
  - Markdown import
  - Document migration/schema docs
  - Document Agent manifest/instruction contribution

제외 범위

| 제외 항목 | 담당 후보 | | --- | --- | | Artifact | @soddong/agentic-domain-artifact | | Artifact Standard | @soddong/agentic-domain-artifact-standard | | Knowledge | agentic-domain-knowledge | | Methodology | @soddong/agentic-domain-methodology | | Render | agentic-support-render 후보 | | Agent Routing | runtime/router 계열 |

DB 명명 기준

| 구분 | 기준 | | --- | --- | | logical schema | document | | SQLite table prefix | document_ | | PostgreSQL mapping | document.*, 단 실제 적용은 향후 별도 프로세스 |

초기 테이블:

document_code_groups
document_codes
document_node_taxonomies
document_node_taxonomy_levels
document_documents
document_nodes
document_contents
document_blocks
document_annotations
document_revisions
document_change_events
document_versions

개발 검증

npm run build --workspace @soddong/agentic-domain-document
npm run typecheck --workspace @soddong/agentic-domain-document
npm run dev:test:agentic-domain-document
npm pack --workspace @soddong/agentic-domain-document --dry-run --cache /private/tmp/agentic-npm-cache

기본 API 예시

import { createDocumentService } from "@soddong/agentic-domain-document";

const service = createDocumentService({
  databasePath: ".agentic/platform.sqlite"
});

try {
  const document = service.createDocument({
    title: "요구사항 정의서",
    documentTypeCode: "default",
    taxonomyCode: "default"
  });

  const chapter = service.createNode({
    documentId: document.documentId,
    nodeLevel: 1,
    title: "개요"
  });

  const content = service.ensureContent(chapter.nodeId);
  service.addBlock({
    contentId: content.contentId,
    blockTypeCode: "paragraph",
    contentText: "문서 본문을 작성합니다."
  });

  const validation = service.validateDocument(document.documentId);
  console.log(validation.valid);
} finally {
  service.close();
}

Import Profile

@soddong/agentic-domain-document는 외부 Artifact Standard가 제공하는 문서 작성 기준을 직접 하드코딩하지 않습니다. 대신 DocumentImportProfile contract와 DefaultMarkdownImportProfile을 제공하고, Markdown importer가 optional profile을 입력으로 받습니다.

import {
  DefaultMarkdownImportProfile,
  createDocumentMarkdownImporter
} from "@soddong/agentic-domain-document";

const importer = createDocumentMarkdownImporter({
  databasePath: ".agentic/platform.sqlite"
});

try {
  const result = importer.importMarkdownDocument({
    title: "문서 제목",
    markdown,
    profile: DefaultMarkdownImportProfile
  });

  console.log(result.document.documentId);
} finally {
  importer.close();
}

artifact-standard 같은 외부 모듈은 DocumentImportProfile 형식에 맞는 profile을 제공하고, consumer 또는 integration layer가 이를 document importer에 전달합니다.

Adoc 조회 API 예시

Adoc 조회는 직접 SQL보다 DocumentReader public API를 우선 사용합니다.

import { createDocumentReader } from "@soddong/agentic-domain-document";

const reader = createDocumentReader({
  databasePath: ".agentic/platform.sqlite"
});

try {
  const latest = reader.getLatestDocument({
    documentTypeCode: "architecture_specification"
  });

  if (latest !== undefined) {
    const tree = reader.getDocumentTree(latest.documentId);
    const blocks = reader.findBlocks(latest.documentId, {
      contains: "Contract API"
    });
    const markdown = reader.toMarkdown(latest.documentId);

    console.log(tree.length);
    console.log(blocks.length);
    console.log(markdown);
  }
} finally {
  reader.close();
}

toMarkdown()은 본격 렌더링 엔진이 아니라 Adoc을 사람이 읽기 쉽게 보여주기 위한 기본 Markdown Projection입니다. Projection은 조회용 파생물이며 원천이 아닙니다. Markdown 파일 저장, checksum, stale 검증, PDF/PPTX/HTML 렌더링은 후속 @soddong/agentic-capability-render 책임입니다.

기본 Markdown Projection은 paragraph, quote, list, code, table, figure, diagram, callout block을 Markdown으로 복원합니다. list는 listStyleCode에 따라 bullet 또는 number 목록으로 출력하고, table은 columns와 rows를 Markdown table로 출력합니다. figure는 image reference와 visible caption으로 출력하며, diagram은 mermaid/plantuml source block을 fenced code block으로 출력합니다. 구조형 callout은 title과 paragraph/list/table body block을 blockquote 형태로 출력합니다.

Adoc Markdown Import 예시

Adoc 작성의 1차 import 대상은 Markdown입니다. 전체 문서 생성과 기존 문서에 대한 챕터 append를 지원합니다.

import { createDocumentMarkdownImporter } from "@soddong/agentic-domain-document";

const importer = createDocumentMarkdownImporter({
  databasePath: ".agentic/platform.sqlite"
});

try {
  const document = importer.importMarkdownDocument({
    title: "아키텍처 명세서",
    documentTypeCode: "architecture_specification",
    taxonomyCode: "architecture_specification",
    markdown,
    sourcePath: "chapters/chapter-01.md",
    policy: {
      validateAfterImport: true
    }
  });

  importer.importMarkdownChapter({
    documentId: document.document.documentId,
    markdown: chapterMarkdown,
    sourcePath: "chapters/chapter-02.md",
    policy: {
      validateAfterImport: true
    }
  });
} finally {
  importer.close();
}

Markdown Import는 draft Adoc 생성과 챕터 append를 위한 작성 진입점입니다. PDF/PPTX/HTML import, BlockFlow YAML import, merge/reconcile은 1차 범위에서 제외합니다.

Markdown Import는 다음 기본 구조화를 수행합니다.

- Markdown heading -> Document Node
- paragraph, quote, list, code -> Typed Block
- bullet/number Markdown list -> `listStyleCode`가 포함된 list block
- Markdown table -> table block
- `표 N. 제목 - 요약` + table -> caption이 결합된 table block
- Markdown image -> figure block
- image alt와 visible `그림 N. 제목 - 요약` caption -> caption이 결합된 figure block
- mermaid/plantuml fenced code -> diagram block

Document Agent Contribution

@soddong/agentic-domain-document는 문서 작성 agent가 사용할 manifest와 resource index를 제공합니다. 이 contribution은 @soddong/agentic-capability-agent-client의 공통 계약을 따르며, runtime/router가 설치된 패키지의 agent 기여분을 일관되게 등록하고 선택할 수 있게 합니다.

Agent manifest, routing, capability, resource index, instruction, guide, example, validation rule, source mapping은 TypeScript inline 문자열이 아니라 package root의 agent/ 리소스를 원천으로 관리합니다.

@soddong/agentic-domain-document/
  agent/
    agent.manifest.json
    routing.json
    resource-index.json
    resource-selection.json
    capabilities/
      document-authoring.json
      document-block.json
      document-toc.json
      document-validation.json
    instructions/
      00-runtime-behavior.md
      10-scope-and-boundary.md
      20-task-procedures.md
      30-must-and-must-not.md
    guides/
      10-document-authoring-guide.md
      20-domain-boundary-guide.md
      30-authoring-policy-guide.md
      40-toc-authoring-guide.md
      50-content-block-guide.md
      51-paragraph-authoring-guide.md
      52-table-authoring-guide.md
      53-diagram-figure-authoring-guide.md
      70-korean-writing-style-guide.md
    validation/
      document-validation-rules.md
    examples/
      examples.md
      document-quality-examples.md
    sources/
      reference-mapping.md

import { documentAgentContribution } from "@soddong/agentic-domain-document";

console.log(documentAgentContribution.manifest.agentId);
console.log(documentAgentContribution.resourceIndex?.instructions[0].path);

resource index는 다음 리소스를 구분해 제공합니다.

| 순서 | 구분 | 내용 | | --- | --- | | 1 | instructions | Agent가 반드시 따르는 작동 규칙 | | 2 | guides | 작성 품질을 높이는 상세 기준 | | 3 | examples | 좋은/나쁜 결과 예시와 payload 예시 | | 4 | validationRules | 기계적으로 검증할 수 있는 기준 | | 5 | sources | 규칙의 출처와 반영 근거 |

resourceGroups.order는 위 분류 간 적용 순서를 나타내고, 각 리소스의 priority는 같은 분류 안에서의 파일 적용 순서를 나타냅니다.

resource-selection.json은 사용자 요청에 따라 위 resource 중 어떤 묶음을 agent context에 포함할지 정의합니다. 예를 들어 “표 컬럼 헤더를 설계해줘” 요청은 공통 instruction, authoring guide, Korean writing guide, content block guide, table guide, quality example, validation rule을 함께 선택합니다.

import {
  assembleDocumentAgentContext,
  documentAgentContribution,
  documentResourceSelectionRules,
  selectDocumentAgentResources
} from "@soddong/agentic-domain-document";
import { selectAgentResources } from "@soddong/agentic-capability-agent-client";

const bundle = selectAgentResources(documentAgentContribution, {
  requestText: "표 컬럼 헤더를 설계해줘"
});

console.log(documentResourceSelectionRules.length);
console.log(bundle.bundleType);
console.log(bundle.resourceIds);

const documentBundle = selectDocumentAgentResources("표 컬럼 헤더를 설계해줘");
const context = assembleDocumentAgentContext("표 컬럼 헤더를 설계해줘");

console.log(documentBundle.bundleType);
console.log(context.contentText);

Korean writing guide는 문체 요청에만 쓰는 부가 guide가 아니라 문서 작성, 수정, 검토의 baseline guide로 취급합니다. Source mapping은 평상시 작성 context에는 항상 포함하지 않고, 출처 확인이나 규칙 보완 요청에서 선택합니다.

문서

| 문서 | 내용 | | --- | --- | | docs/usage.md | 사용 기준 | | docs/configuration.md | 설정 책임 | | docs/build.md | 구축 담당자 빌드/검증 | | docs/publishing.md | publish 절차 | | docs/delivery.md | 운영환경 전달 기준 | | docs/operations.md | 운영환경 설치/검증 | | docs/schema/migrations.md | migration 계획 | | docs/validation-rules.md | validator rule 설명 |