knowledge-lattice
企业知识层（通用平台，领域无关——首个落地场景为税务）：提供两类能力——文档知识（制度、口径、手册的权限内检索）和业务语义（术语识别、业务对象及其关联）。以单一服务、单一 MCP server 的形式提供给 Agent，供数为主、人工检索为辅。
名字释义：lattice（晶格）——知识单元（chunk）按结构有序排列成格；格子是本体，检索是在格上寻位。文档上架是晶体生长，索引是晶格结构，可重建、可演化。并入业务语义层后，"lattice"同时描述文档知识 + 业务对象关系图这种有结构的知识网络，名字比以前更贴切（#35 §4.1）。
知识层定位（2026-10-18 D23 修订，取代 2026-10-16「双层分立」口径）：文档知识层与业务语义层（术语 + 业务对象的类型化对象图）同服务归一——术语层原定的独立 glossary-agent MCP server 部署形态取消，并入本系统
core/semantic/模块（requirements.md D17/D23）；glossary-agent（lab 仓） 转为调研与设计沉淀，其结论是 semantic 模块的设计输入。
文档地图
| 文档 / 目录 | 角色 |
|---|---|
| docs/requirements.md | 需求正文（FR / NFR / D 编号源头——先读这份） |
| docs/design.md | 方案设计（架构 / DDL / ACL 编译 / MCP 契约 / §8 里程碑分解） |
| docs/TEST-CASES.md | 验收用例展开层：design §9 冻结 T / T-S 编号展开 + 模块 TC-* 用例 + §六里程碑验收对照表；活文档 |
| docs/known-gaps.md | 已预见问题登记（G-n）：对策之后仍残留的缺口与规格开放点；活文档 |
| prototype/index.html | 交互原型（浏览器直接打开、mock 数据）：信息结构与 UI 风格双基准 |
| RUNBOOK.md | 运维手册（重嵌入蓝绿 / 审计分区回溯 / 双方言迁移注意）；运行侧活文档 |
| AGENTS.md | 工作规范（冻结纪律 / 分层纪律 / 工具链 / 多 Agent 工作流与提交约定） |
benchmarks/ |
实验 / 压测脚本与报告归档（report-*.md，结论回写 known-gaps 或正文） |
eval/ |
评测语料（corpus.jsonl）与黄金集（golden.jsonl） |
| lab 仓 | 调研基础：enterprise-rag 调研（22 仓源码级调研 + 四厂商第一方实践）、glossary-agent（术语层调研沉淀） |
版本口径：需求 / 设计两正文随实现勘误高频升版，具体版本号与变更史以各文档头部为准，本 README 不复述；里程碑完成态以 TEST-CASES §六对照表 为准。设计冻结纪律：docs/ 需求与设计正文仅在决策变化时修改（决策变更走 issue + D 编号），实现问题走测试用例与 issue；TEST-CASES / known-gaps / RUNBOOK 为活文档、随实现回写。拆仓前的设计评审 issue（#31~#42）均在 lab 仓，本文链接为绝对地址。
一句话定位
私有化部署的轻量知识层服务：单进程 + 存储后端双实现（SQLite 默认，零中间件 / PostgreSQL+pgvector 可选——D24），嵌入与重排经 OpenAI 兼容 API（D12 修订）、无 GPU 可跑；文档知识——多组织 → 多知识库 → 文档（维度 ACL） 三层结构；业务语义（D23，M2-S 起）——概念/系统名词/场景/模板/模板字段/报表项/表/列组成的类型化对象图（源端事实每日从业务系统同步——REST 或 MCP 传输均可，人工内容 Git YAML 覆盖层，不做 GraphRAG、不引入图数据库）。两者通过同一个 MCP server（docs 组 + semantic 组工具）给 deepagents 供数（代人检索、按数据维度过滤权限、术语识别与对象关系展开），并提供上传与检索测试页面。
项目状态
POC 阶段，独立仓库演进——2026-10-28 自 lab 仓拆仓。
- M0a / M0b / M1 已交付（完成态与证据指针见 TEST-CASES §六对照表；M1 里程碑达成宣告待 TC-UI 手动走查执行）。
- 下一步 M2：业务语义层并行轨道（M2-S1~S3）；M2 之前 agent 侧以「同 schema 的 Git YAML + 本地 AC 自动机」过渡。
- 仍开放的待决项（requirements §9）：待决-1（真实样例语料与业务问题）、待决-2（企业 SSO 协议与 token 属性）、待决-3（agent 侧 token 换取 / 可信子系统）；待决-5（网关 rerank 能力）与待决-6（公司 PG 16 + pgvector 0.8.x）已关闭。
仓库结构
src/knowledge_lattice/
├── app.py # FastAPI 入口（create_app 工厂：路由 + MCP 挂载 + 静态页壳 + 指纹探针）
├── config.py / log.py
├── core/docs/ # 文档域业务（ingest / chunking / retrieve / acl / quality / credentials…）
├── core/semantic/ # 业务语义域（D23 并入，M2-S 起）——与 core/docs 包级互斥
├── store/ # StorageBackend 协议 + sqlite/ postgres/ 双方言包（迁移 / FTS / 向量 / ACL 渲染 / 审计）
├── adapters/ # 外置依赖适配（embedder / reranker / parser_docling / tokenizer / breaker…）
├── api/ # REST 端点（upload / documents / tasks / search / quality / admin）
├── mcp/ # MCP server（docs + semantic 两组工具）
├── web/ # 前端薄壳（原生 HTML/JS/CSS + i18n.js 中英双语——FR-8，无构建链）
└── worker/ # 任务子进程（任务循环 + IPC 唤醒；M2 子进程化，当前占位）
tests/ # 按模块前缀命名（acl_/ing_/fts_/emb_/e2e_/pg_…），双后端参数化（[pg] 条目）
分层纪律（core 不写方言 SQL、core 两包互斥）与模块边界的权威定义见 design §3，速览见 AGENTS.md。
快速开始
前置：Python 3.11+（本仓以 .python-version 钉版本，开发 = 部署同版本——G-11）与 uv。
uv sync # 安装依赖（uv.lock 锁定、必须提交）
cp .env.example .env # 按需启用嵌入网关 / PG DSN（sqlite 默认无需设置）
uv run uvicorn "knowledge_lattice.app:create_app" --factory # 起在 http://127.0.0.1:8000
- 页面壳
http://127.0.0.1:8000/：上传与检索测试页（中/英双语切换） - REST API 文档
http://127.0.0.1:8000/docs；MCP 端点/mcp - 开发 JWT：dev 环境下
POST /api/dev/token签发（生产 404）
测试：
uv run pytest # sqlite 默认后端，无需容器（TC-UI 手动走查组带 manual 标记、默认跳过）
# 全量门禁（双后端 + 常规/python -O 双模式，skip=失败——不建 CI，本地承接）：
docker start lattice-pg
export LATTICE_PG_DSN=postgresql://postgres:lattice@localhost:5432/lattice
scripts/test_gate.sh
TC-UI 手动走查步骤见 tests/test_ui_01_manual.py 文件头。