storyai

先打开这个 → docs/index.html

用浏览器打开后，七份文档会通过链接互相连接。 想在一页里全部看完，就看 docs/storyai-설계-통합.html。 想看界面，就看 docs/07-UI목업.html —— 实际可运行。

Related MCP server: bible-ecrivain

这个文件夹里有什么

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 제안/커밋 구현

文档

用浏览器打开 docs/index.html。七份文档互相引用。

机器可读规格

这是文档所描述的对象，也是实现直接读取的文件。

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

用 sqlite3 store/story.db < spec/schema.sql 即可直接应用。

宿主包

在 Claude Code 和 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 를 양쪽 훅이 공통 호출

MCP 连接确认

仓库中同时包含 Claude Code 用的 .mcp.json 和 Codex 用的 .codex/config.toml。 首次打开时，请信任项目并批准 MCP 执行，然后确认连接状态。

claude mcp list
codex mcp list

文档修改

文档是构建产物。要修改内容，请修改 build/parts/*.part.html，然后：

python3 build/build.py

公共样式集中在 build/style.css 一处，构建时会被内联到每份文档中—— 因此每份文档都是自包含的，放到任何地方都能原样渲染。 依赖只有 Python 标准库。

实现现状

P0 只读索引、P1 写入路径、P2 复线·诊断、P3 提取·搜索已经实现。 提供 14 个 MCP 工具，所有写入都经过提案记录和 read_set 冲突判定，在单一 SQLite 提交通道中原子化应用。P3 强制使用显式 ID binding manifest 和 UTF-8 byte span，并将 BM25 与本地 sqlite-vec 结果通过 RRF 融合。

接下来是 P4 — UI。详细分解请参照 开发计划书 §P4。

开发运行

在 Python 3.12 及以上版本中创建隔离环境并安装开发依赖。

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

配置集文件格式遵循 bible/README.md。加载器只读取明确声明的 YAML 元数据，不会猜测内容或自动提取。

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

原稿提取使用 manuscript/**/*.md 旁边的 *.story.json 作为输入。格式和 LLM 提取契约位于 prompts/v1/ 中，ingest 只创建 Proposal， 不会自动提交。

最后一条命令是 stdio MCP 服务器，因此在终端中等待是正常现象。Claude Code 和 Codex 各自通过项目配置运行同一个 server/run-mcp.sh 入口点。

P1 写入契约

propose 不会改变 live 图。每个 op 都需要 8 个字符以上的唯一 idem_key， 且 read_set 不能为空。像最初的 Session 那样没有既有节点依据的 ADD，会将当前 graph_state.revision 以 { "node": "book", "rev": n } 形式传递。

支持的 verb 为 ADD · UPDATE · INVALIDATE · LINK · UNLINK。INVALIDATE 和 UNLINK 不会删除行，而是关闭 tx_to。commit(mode="dry_run") 会执行与真实 提交相同的验证·CID·Merkle 计算，然后回滚整个事务。

story://session/latest 指向最近的 Session 节点。Session 的 props 中必须保留 open_threads 和 next，以便下一个宿主接续。

P2 复线·连续性契约

Promise 的 props.status 只能按 hypothetical → eligible → actualized 的顺序推进， 有意废弃以 prevented 结束。eligible 需要 T，actualized 需要 P。 promises(status=["eligible"]) 返回 F–T–P 与债务、S-Eff、delta-Coh 近似值。

Fact 的可见性通过 visible_to 结构化记录 viewer、learned_at、pathway。Scene 的 props.pre · post · forbid 条件采用 subject、field、op、value 形式，发言事实通过 props.claims=[{"speaker": "character/…", "fact": "fact/…"}] 记录。只有使用这种 结构，check 才能以 SQL 可复现的方式判定认知时点·世界规则·事实冲突。

causes、contains、extends 的循环以及每个 Scene 的第二条 focalizes 边会在 提案阶段被拒绝。包含不可达事件在内的其余诊断，可通过 commit 结果和 check 确认。