storyai

Primero abre esto → docs/index.html

Al abrirlo en el navegador, los siete documentos se enlazan entre sí. Si quieres verlo todo en una sola página, usa docs/storyai-설계-통합.html. Si te interesa la interfaz, abre docs/07-UI목업.html — funciona de verdad.

Related MCP server: bible-ecrivain

Qué hay en esta carpeta

docs/     읽을 것.  설계 문서 7종 + 통합본
spec/     구현이 읽을 것.  온톨로지·툴·규칙·DDL (JSON + SQL)
build/    문서를 고칠 때.  parts/ 수정 후 build.py 실행
skills/   에이전트가 읽을 것.  집필·검수·설정집 3종
hooks/    자동 검사 트리거.  Claude Code / Codex 각각
AGENTS.md 에이전트 지침 단일 소스 ★ 양쪽 호스트가 읽음

manuscript/ api/ web/        ← 후속 단계에서 채웁니다
server/ bible/ store/        ← P0 조회 + P1 제안/커밋 구현

Documentos

Abre docs/index.html en el navegador. Los siete documentos se referencian entre sí.

Especificación legible por máquina

Es el objeto que describen los documentos y, a la vez, el archivo que la implementación lee directamente.

spec/ontology.json   노드 18종 · 간선 28종 · 태그 · 삼중 시간축 · 가시성 · 불변식
spec/tools.json      MCP 툴 15개 시그니처 · 예산 · 위험 등급 정책
spec/rules.json      진단 규칙 26개 (Tier 1 결정론 / Tier 2 LLM) · 전파 정책
spec/policy.json     P1 변경 위험 등급 · 잠금 · 캐스케이드 임계값
spec/schema.sql      DDL — 테이블 22 · 뷰 5 · 인덱스 18

Se aplica directamente con sqlite3 store/story.db < spec/schema.sql.

Paquetes de host

Funciona con un solo conjunto tanto en Claude Code como en Codex.

plugin.json                 agent-plugins 스키마 — Codex가 우선 인식
.claude-plugin/plugin.json  Claude Code 매니페스트 — Codex도 폴백으로 읽음
.mcp.json                   Claude Code용 프로젝트 MCP 설정
.codex/config.toml          Codex용 프로젝트 MCP 설정
AGENTS.md                   ★ 에이전트 지침 단일 소스. 양쪽이 읽음
CLAUDE.md                   AGENTS.md를 가리키는 한 줄
skills/                     Agent Skills 규격 6필드만 — 양쪽 + 46개 호스트
hooks/                      run-check.sh 를 양쪽 훅이 공통 호출

Verificación de la conexión MCP

El repositorio incluye tanto .mcp.json para Claude Code como .codex/config.toml para Codex. Al abrirlo por primera vez, confía en el proyecto, aprueba la ejecución de MCP y luego verifica el estado de la conexión.

claude mcp list
codex mcp list

Modificación de documentos

Los documentos son artefactos de compilación. Para cambiar el contenido, edita build/parts/*.part.html y:

python3 build/build.py

Los estilos comunes viven en un solo lugar, build/style.css, y se incrustan en cada documento durante la compilación — por eso cada documento es autónomo y se renderiza igual sin importar dónde se publique. La única dependencia es la biblioteca estándar de Python.

Estado de la implementación

P0 índice de solo lectura, P1 ruta de escritura, P2 presagios·diagnóstico, P3 extracción·búsqueda ya están implementados. Se ofrecen 14 herramientas MCP, y toda escritura pasa por el registro de propuestas y la detección de conflictos de read_set para aplicarse de forma atómica en un único carril de confirmación de SQLite. P3 impone un manifiesto de vinculación de ID explícito y spans de bytes UTF-8, y combina BM25 con los resultados locales de sqlite-vec mediante RRF.

Lo siguiente es P4 — UI. El desglose detallado sigue §P4 del plan de desarrollo.

Ejecución de desarrollo

Crea un entorno aislado con Python 3.12 o superior e instala las dependencias de desarrollo.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

El formato de los archivos de configuración sigue bible/README.md. El cargador solo lee los metadatos YAML explícitos; no adivina el contenido ni lo extrae automáticamente.

.venv/bin/python -m server.load_bible
.venv/bin/python -m server.consolidate
.venv/bin/python -m pytest
server/run-mcp.sh

La extracción de manuscritos usa como entrada los *.story.json que están junto a manuscript/**/*.md. El formato y el contrato de extracción con LLM están en prompts/v1/; ingest solo crea Propuestas y no hace confirmaciones automáticas.

El último comando es un servidor MCP stdio, así que es normal que se quede esperando en la terminal. Claude Code y Codex ejecutan el mismo punto de entrada server/run-mcp.sh a través de su configuración de proyecto respectiva.

Contrato de escritura P1

propose no modifica el grafo en vivo. Cada operación requiere una idem_key única de 8 caracteres o más, y read_set no puede estar vacío. Un ADD sin base en nodos existentes, como en la primera Session, pasa la graph_state.revision actual como { "node": "book", "rev": n }.

Los verbos admitidos son ADD · UPDATE · INVALIDATE · LINK · UNLINK. INVALIDATE y UNLINK no borran filas; cierran tx_to. commit(mode="dry_run") realiza la misma validación, cálculo de CID y Merkle que la ejecución real y luego revierte toda la transacción.

story://session/latest apunta al nodo Session más reciente. En las props de la Session hay que dejar sí o sí open_threads y next para que el siguiente host pueda continuar.

Contrato de presagios y continuidad P2

El props.status de una Promise solo avanza en el orden hypothetical → eligible → actualized, y el descarte intencional termina en prevented. eligible requiere T, y actualized requiere P. promises(status=["eligible"]) devuelve F–T–P, deudas, S-Eff y aproximaciones de delta-Coh.

La visibilidad de un Fact se registra estructurando en visible_to el viewer, learned_at y pathway. Las condiciones props.pre · post · forbid de una Scene tienen la forma subject, field, op, value, y los hechos dichos se registran como props.claims=[{"speaker": "character/…", "fact": "fact/…"}]. Solo usando esta estructura check puede determinar de forma reproducible en SQL el momento de conocimiento, las reglas del mundo y los conflictos de hechos.

Los ciclos de causes, contains, extends y la segunda arista focalizes por Scene se rechazan en la fase de propuesta. El resto de diagnósticos, incluidos los eventos inalcanzables, se verifican en el resultado de commit y con check.