KnowMesh / 知络

Public Launch Candidate / 公开发布候选准备中

KnowMesh 仍是 0.1.0-alpha，但仓库正在按公开发布候选标准收口：README、公开样例、Issue/PR 模板、Security、OpenAPI、release gate、CI、CodeQL、Scorecard 和 artifact checksum 都必须能被外部贡献者复核。分享预览图位于 assets/social/knowmesh-social-preview.png。

Public Beta 之前还会固定首次使用路径、浏览器样例流、Integration Examples 合约、Expert / Provider lifecycle 和 release evidence。扩展阶段按 official -> certified -> community -> experimental 标注，避免贡献者误把实验入口当成稳定 API。

KnowMesh 不是“上传文件然后问模型”的 RAG demo，也不是另一个向量库 UI。它把源文件夹当作长期知识资产来编译：抽取页面、块、结构、chunk、引用、质量状态、版本和 Query Runtime 契约，让知识库能被检查、维护、回滚和集成。

它适合你，如果你关心：

• RAG 答案必须追溯到源文件、页码、章节或结构锚点。
• 文档持续更新后，需要差异、局部重跑、版本和回滚，而不是全量重建。
• 多个知识库要隔离 setup、任务、日志、反馈、版本和生成资产。
• 本地状态必须可靠，刷新页面、换端口、重启服务都不能丢。
• 行业知识库需要领域结构。K12 教材是 KnowMesh 的第一个 Expert 场景。

普通 RAG 原型能很快回答“看起来像对”的问题，但真正上线时会遇到更硬的需求：答案证据在哪里，低置信内容怎么复核，源文件变更后怎么局部更新，版本能不能回滚，外部应用能不能走同一套查询契约。

1. 选择或创建一个知识库。
2. 扫描源文件夹，识别 PDF、Office、WPS、图片、扫描件和风险文件。
3. 把源材料写入 workspace.sqlite 和每个知识库独立的 catalog.sqlite，大文件保留在 artifacts。
4. 运行质量门禁：review 队列、评测、引用校验、低置信内容处理。
5. 发布可回滚的知识版本，并生成 sidecar / index 供检索和集成。
6. Query Runtime 基于证据回答，返回引用、检查项和反馈入口。

当前仓库处于 Alpha。普通用户从本地 Web Console 开始，维护者可以先用无密钥 demo 检查本地环境。

# Windows
.\knowmesh.cmd start
launcher\knowmesh.cmd start

# macOS / Linux
./knowmesh start
launcher/knowmesh start

启动器会优先寻找 Node.js 24+。如果缺失，会准备私有 Node 运行时，不会修改系统 PATH。

npm install
node ./src/cli/knowmesh.mjs start
npm run doctor
npm run demo:plan

KnowMesh 默认启动一个本地服务：http://127.0.0.1:7457。本地 smoke 和 demo 检查不会上传文件、调用 OCR、调用 embedding，也不会写入向量索引。

想快速理解 KnowMesh 的实际边界，可以先看 examples/public-samples：

• general-docs：虚构运维手册，用来验证 Query Runtime、引用、拒答、反馈、包预览和版本 manifest。
• operations-handbook：非 K12 Expert SDK 样例，用制度、流程、复核节奏、回滚规则和证据要求验证扩展合同。
• k12-synthetic：合成的小学五年级数学样例，用来验证 K12 Expert 结构和范围，不包含真实教材内容。

这些样例无密钥、不上传、不调用 OCR、不调用 embedding、不写向量索引、不创建云资源。

K12 不是 KnowMesh 的全部定位，而是第一个能证明 Expert 机制价值的强化场景。教材不是普通 PDF：它有目录、单元、课文、词表、公式、练习、页码和跨册范围，查询也必须严格拒绝越界学科、越界教材和无证据问题。

KnowMesh Expert - K12 目标是把教材资料编译成结构化知识资产：

• 语文：课文、作者、注释、词表、课后题、口语交际、习作。
• 数学：概念、例题、公式、图形、条件、步骤、练习和答案解析。
• 英语：Unit、Lesson、Words、Sentences、Dialogue、Phonics。
• 科学：实验目的、材料、步骤、观察和结论。
• 引用：可定位到教材、页码、章节或结构锚点。

项目不会捆绑教材内容。模板只提供处理策略，用户必须使用自有或已授权资料。

KnowMesh 仍处于 0.1.0-alpha 阶段，方向和底座已经成形，但还不是稳定商业版本。

已经完成的基础：

• SQLite-first workspace 和 per-KB catalog。
• K12 一次性迁移保留。
• 多知识库隔离和 scoped routes。
• 任务 checkpoint、日志、暂停、重试、恢复。
• Query Runtime 统一控制台测试和集成 API。
• Expert 注册表、K12 schema、对象关系契约和 95% TOC / 100% 越界拒答门槛。
• 文档维护、反馈 review、版本记录、诊断导出。
• release smoke、artifact install smoke、package boundary gate。
• 0.5.0 Provider Adapters release evidence：provider manifests、parser/OCR boundary、embedding/vector boundary、provider diagnostics browser proof、no-cloud public path 和 package asset review。
• 0.6.0 Integration SDK release evidence：endpointManifestReadiness、sdkClientProof、examplesDriftProof、integrationSafetyProof、providerAwareNoCloudProof 和 integrationPackageAssetReview。
• 0.7.0 Consumer Integration Proof release evidence：installedSdkConsumerProof、livePublicSampleSdkProof、integrationRecipeProof、privacyBoundaryAuditProof、providerAwareNoCloudConsumerProof 和 consumerPackageAssetReview。
• 0.8.0 Operator Workflow Proof release evidence：sourceIntakeProof、executionRecoveryProof、maintenanceTargetedRerunProof、versionRollbackProof、operatorBrowserWorkflow、operatorPrivacyAuditProof 和 operatorPackageAssetReview。
• 0.9.0 First-Run Usability Proof release evidence：firstRunLaunchProof、guidedSetupProof、buildRecoveryProof、firstQuestionProof、maintenanceNextActionProof、firstRunBrowserWorkflow 和 firstRunPackageAssetReview。
• 1.0.0 Usable Product Proof release evidence：usableLaunchReliabilityProof、usableDocumentIntakeProof、usableWebConsoleWorkflowProof、usableDurableDataPackageProof、usableBrowserWorkflow、usablePrivacyProof 和 usableProductPackageAssetReview。
• Windows / Ubuntu CI on Node.js 24。
• CodeQL、OpenSSF Scorecard、secret scanning、push protection 和私密漏洞报告。
• main 分支保护要求 Ubuntu / Windows CI、PR review 和会话解决。

接下来优先推进：

• 更完整的 Query Runtime 可用性。
• Expert 插件边界和作者文档。
• 更强的本地解析 / OCR provider 适配。
• 更深入的下游框架适配和真实应用集成反馈。

完整路线见 ROADMAP.md。

npm test
npm run smoke:release
npm run smoke:usable-product
npm run smoke:first-run-usability
npm run smoke:operator-workflow
npm run smoke:sdk-consumer
npm run smoke:live-sdk
npm run smoke:artifact
npm run verify:package-boundary
npm run verify:integration-privacy
npm run doctor
npm run demo:plan

assets/brand/             Logo and brand assets
assets/readme/            README visual assets
assets/social/            Repository social preview assets
configs/                  Reusable configuration templates
docs/                     Documentation and current design authority
examples/local-demo/      Credential-free local example
examples/public-samples/  Public launch-candidate samples
examples/textbook-cn-k12/ K12 Aliyun example config
launcher/                 Node-independent user launchers
schemas/                  JSON schemas
scripts/                  Release and package verification scripts
src/cli/                  Local command entry
src/core/                 Core planning and template logic
src/experts/              Expert templates and schemas
src/local-service/        Local HTTP service and APIs
src/web-console/          Local Web Console

• 文档中心
• 快速入门
• 架构概览
• K12 Expert
• Expert Authoring Kit
• Query Runtime API
• Operator Workflow Proof
• First-Run Usability Proof
• Usable Product Proof
• 应用集成指南
• Integration Examples
• Provider 适配器
• Community Backlog
• Release Operations
• Architecture Overview
• Roadmap
• 项目地图
• Good First Issues
• 当前设计
• Operations Runbook
• Public Samples
• Release Candidate Evidence
• Changelog
• Contributing
• Security Policy

docs/current-design.md 是唯一现行设计权威。README 和其他文档只做入口、说明和操作指导。

欢迎关注、试用、提 issue、补文档、讨论 Expert 场景或 provider 适配。请先阅读 CONTRIBUTING.md。

安全问题请按 SECURITY.md 私下报告，不要在公开 issue 中包含漏洞细节、密钥、文档正文、日志或本地路径。

建议仓库 Topics：knowledge-base, rag, retrieval-augmented-generation, local-first, document-ai, document-intelligence, sqlite, sqlite-first, vector-search, citations, auditable-ai, knowledge-graph, education, k12, textbook, aliyun, dashscope, nodejs, web-console, open-source。

MIT. See LICENSE.