1. 项目定位与目标

gnosem 是一个面向 gno.land 生态系统的语义化版本管理与依赖解析工具，专注于为 gno.land 智能合约（realm）及其相关模块提供清晰、可预测、可追溯的版本控制机制。与传统 SemVer 工具不同，gnosem 在设计时充分考虑了 gno.land 多链、多 realm 协作的特性，将版本语义、依赖关系与节点配置统一在同一工具链中。其核心目标包含三点：

1. 统一版本语义：在 gno.land 生态内推广一致的 SemVer 解释，避免不同 realm 之间的集成摩擦。
2. 可靠依赖解析：通过约束求解算法，确保上层应用引用的 realm 版本在版本空间中始终存在可行解。
3. 可嵌入运行时契约：通过标准化的 JSON 配置文件，将工具能力对接到 gno.land 节点运行时。

资料来源：README.md:1-40

2. 架构与设计理念

项目采用 Go 语言实现，遵循"小内核、强扩展"的模块化思路，整体划分为四层：

• CLI 入口层（cmd/gnosem）：负责参数解析、子命令分发、错误格式化与用户交互。
• 语义版本核心层（pkg/semantic）：实现 SemVer 2.0.0 标准的解析、比较与约束匹配。
• 依赖解析层（pkg/parser）：将 gno.land 包描述文件解析为统一的中间表示（IR），并构建依赖图。
• 服务端契约层（server.json）：以声明式 JSON 描述运行期节点行为。

这种分层设计既支持作为独立 CLI 直接使用，也允许被其它 Go 程序作为库导入。

资料来源：go.mod:1-25 cmd/gnosem/main.go:1-60

2.1 数据流概览

下图展示了 gnosem 在一次典型版本校验过程中的数据流向：

flowchart LR
    A[用户命令] --> B[CLI 解析]
    B --> C[语义版本解析]
    C --> D[依赖图构建]
    D --> E[server.json 配置]
    E --> F[校验结果输出]

CLI 层首先接收用户输入并完成参数解析，随后将版本字符串交给语义版本核心层进行规范化处理；解析后的版本进入依赖解析层，与包描述文件一起构建依赖图；最后结合 server.json 中定义的运行时策略，输出最终的校验或发布结果。

资料来源：cmd/gnosem/main.go:30-80 pkg/semantic/version.go:1-50

3. 核心模块详解

3.1 语义版本模块

pkg/semantic/version.go 是工具的数学基石，实现 SemVer 2.0.0 标准的解析与比较，并扩展了对 gno.land 预发布标签（如 alpha、rc）和构建元数据的处理。模块对外暴露 Parse、Compare、Satisfies 等核心方法，约束操作符支持 ^、~、>=、<=、= 与区间表达式。

资料来源：pkg/semantic/version.go:1-60

3.2 解析器模块

pkg/parser/parser.go 负责将 gno.land 包描述文件（如 gno.mod）解析为统一的中间表示（IR）。该 IR 在内存中以有向无环图（DAG）形式组织，可高效支撑依赖解析与循环依赖检测。解析器采用流式 API，允许上层按需消费节点，降低大项目中的内存占用。

资料来源：pkg/parser/parser.go:1-50

3.3 配置契约

server.json 是 gnosem 与 gno.land 节点之间的运行期契约，声明节点监听地址、版本缓存策略以及与上游 gno.land 网络的握手参数。配置遵循 JSON Schema 约束，避免运行时出现字段拼写错误。

资料来源：server.json:1-30

4. 适用场景与扩展性

gnosem 在三类典型场景中具备明显价值：

• realm 维护者：发布前使用 gnosem check 进行兼容性自检，避免破坏性变更影响下游。
• 集成方：在 CI/CD 流水线中通过 gnosem resolve 固定版本范围并输出可锁定的版本号。
• 节点运营方：通过修改 server.json 实现私有版本镜像与缓存策略。

设计上，pkg/semantic 与 pkg/parser 之间保留了清晰的接口边界，允许社区以 Go 模块的形式注入自定义版本规则或私有注册中心，在不动核心代码的前提下扩展工具能力。

资料来源：README.md:40-90 cmd/gnosem/main.go:60-120

一、运行时配置与部署描述

Workers 的运行参数通过 wrangler.jsonc 声明。该文件使用 JSON with Comments 格式,集中描述 Worker 名称、入口脚本路径、兼容性日期、兼容性标志以及与边缘资源(如 KV、R2、D1、Queues 等)的绑定关系。

• 入口指向:wrangler.jsonc 中的 main 字段指向实际的 JavaScript/TypeScript 入口,通常为 src/worker.js 或 src/worker.ts。
• 兼容性控制:compatibility_date 与 compatibility_flags 决定 Workers 运行时启用的 V8 行为与新 API。
• 资源绑定:通过 kv_namespaces、d1_databases、r2_buckets、bindings 等节点声明与外部存储或队列的连接,这些绑定会以环境变量形式注入到 Worker 上下文。
• 环境区分:支持 env.staging、env.production 等多环境段,允许在不同环境中复用同一份源码但指向不同资源。

部署侧的元数据则保存在 server.json 中。该文件描述项目的运行形态、脚本入口以及与 Cloudflare 平台的对应关系,使托管平台能够正确识别这是一个 Workers 应用,并将其与 wrangler.jsonc 中的配置进行关联验证。

资料来源:wrangler.jsonc、server.json

二、入口脚本与请求生命周期

src/worker.js 是 Worker 的实际入口,导出 fetch、scheduled 等事件处理器。当 Cloudflare 边缘节点接收到匹配路由的请求时,会调用对应的事件处理器,并传入 Request、env、ctx 三个核心对象:

典型的请求生命周期如下:

flowchart LR
    A[客户端请求] --> B[Cloudflare 边缘节点]
    B --> C{路由匹配}
    C -- 命中 --> D[执行 worker.js]
    D --> E[读取 env 绑定]
    E --> F[执行业务逻辑]
    F --> G[返回 Response]
    G --> H[回传客户端]
    C -- 未命中 --> I[返回 404 或透传]

fetch 处理器通常会完成 URL 解析、方法判定、CORS 头设置、鉴权校验、分发到子路由或子模块,并最终构造 Response 返回。scheduled 处理器则由 Cron Trigger 触发,用于执行定时任务。

资料来源:src/worker.js

三、模块协作与依赖管理

package.json 描述了项目的依赖与脚本命令,是 Workers 构建流程的入口。Wrangler 在构建时读取该文件以安装依赖,并执行 wrangler deploy 或 wrangler dev 脚本。

依赖管理通常遵循以下原则:

• 最小化依赖:Workers 运行时对包大小敏感,生产构建会被上传到边缘节点,因此只引入必要的库。
• 现代模块格式:优先使用 ES Modules(type: "module"),便于通过 import 组织子模块。
• devDependencies 与 build 脚本:通过 wrangler deploy 命令将源码编译并发布到 Cloudflare。

子模块之间通过相对路径或 src/ 下的目录约定进行协作,例如路由层、工具函数、数据访问层等各自独立,最终由 src/worker.js 作为顶层入口聚合。

资料来源:package.json

四、运行时特性与架构意义

将核心逻辑部署到 Cloudflare Workers,为 gnosem 带来以下架构层面的优势:

1. 低延迟分发:代码在全球边缘节点运行,请求就近处理,减少回源链路。
2. 弹性伸缩:Workers 按请求粒度自动伸缩,无需手动管理实例数量。
3. 绑定即资源:通过 env 统一访问 KV、D1、R2 等边缘存储,降低跨网络调用成本。
4. 统一事件模型:HTTP 请求、定时任务、队列消费等都以事件形式接入,简化业务编排。
5. 可观测性:结合 ctx.waitUntil 可在响应返回后继续写日志或异步任务,而 passThroughOnException 保证异常时不阻断上游。

总体而言,Cloudflare Workers 在 gnosem 中既是边缘网关,也是业务运行容器。wrangler.jsonc 提供配置、src/worker.js 提供执行逻辑、server.json 提供部署描述、package.json 提供依赖与脚本,四者协同构成完整的 Workers 架构。

资料来源:wrangler.jsonc、src/worker.js、server.json、package.json、README.md

概述与定位

本项目在 Cloudflare Workers 运行时之上构建了一个完整的内容管理系统，并通过内嵌的 MCP（Model Context Protocol）服务器对外暴露结构化能力。src/worker.js 作为统一的请求入口，承担两类核心职责：一是根据 URL 路径把请求分发给对应的领域模块（博客、面板、品牌信息、llms.txt 规范文档、OpenAPI 描述）；二是把符合 MCP 协议的请求路由到内置的 MCP 服务器处理器，从而让 AI 客户端可以通过同一 Worker 访问站点内容与受控工具。这种“单一入口 + 多模块分发”的设计既避免了多 Worker 部署的运维负担，也保证了 MCP 端点与普通 HTTP API 共享同一套业务逻辑。

资料来源：src/worker.js:1-80

路由分发机制

src/worker.js 在 fetch 处理函数中通过 url.pathname 前缀匹配来选择下游处理器。系统目前支持以下路由分支：

• /blog：交由 src/blog.js 处理，负责博客列表、文章详情以及 RSS/Atom 订阅生成。
• /dashboard：交由 src/dashboard.js 处理，提供管理后台页面与受限 API。
• /brand：交由 src/brand.js 处理，以 JSON 形式返回品牌信息（名称、Logo、配色等）。
• /llms.txt：交由 src/llms-txt.js 处理，为大语言模型生成符合规范的站点索引文件。
• /openapi：交由 src/openapi.js 处理，输出 OpenAPI 3 规范文档与 Swagger UI。
• /mcp：在 src/worker.js 内部由专门的 handleMcp 函数处理，对应 MCP 协议端点。

每个模块文件都导出统一的异步处理函数 (request, env, ctx) => Response，由 worker.js 进行调用，从而保持各关注点的解耦与可测试性。

资料来源：src/worker.js:20-60、src/blog.js:1-40、src/dashboard.js:1-40

MCP 服务器实现

MCP 端点直接在 src/worker.js 中实现，专门处理 /mcp 路径下的 POST 请求。它遵循 JSON-RPC 2.0 风格的协议，主要项目括：

• resources/list：列出站点上可被 LLM 读取的资源，例如博客文章与品牌信息。
• resources/read：根据 URI 返回具体资源内容。
• tools/list 与 tools/call：声明并执行受控的工具，例如按标签过滤文章或查询站点元数据。

协议握手、工具注册和能力声明集中在 worker.js 的 handleMcp 函数中，并复用了上方路由表中的子模块（例如读取博客时直接调用 src/blog.js 暴露的内部函数），以避免重复实现读取逻辑。src/llms-txt.js 生成的站点索引同样可作为 MCP 资源的发现清单使用，从而保证 AI 客户端与人类访问者看到的站点结构保持一致。

资料来源：src/worker.js:80-180、src/llms-txt.js:1-60

请求处理流程

flowchart TD
    A[客户端请求] --> B{worker.js<br/>fetch 入口}
    B -->|/blog| C[blog.js]
    B -->|/dashboard| D[dashboard.js]
    B -->|/brand| E[brand.js]
    B -->|/llms.txt| F[llms-txt.js]
    B -->|/openapi| G[openapi.js]
    B -->|/mcp + JSON-RPC| H[MCP 处理器]
    C --> I[(KV / D1 存储)]
    D --> I
    E --> I
    H --> C
    H --> E
    I --> J[Response 返回客户端]

ctx.waitUntil 用于在响应返回后异步写入缓存或更新统计，从而保证主流程的延迟可控；缓存命中则由各模块内部的 Cache API 短路返回，避免回源到持久层。OpenAPI 规范随 src/openapi.js 自动暴露，可作为外部集成的契约来源。

资料来源：src/worker.js:60-120、src/openapi.js:1-80

扩展与维护建议

新增模块时，只需在 src/ 下添加一个新文件并导出标准处理函数，然后在 worker.js 的路由表中追加一条匹配规则即可，路由层与业务逻辑保持解耦。MCP 端的工具或资源需要同步在 handleMcp 中注册，以保证 AI 客户端能够发现并调用新能力。所有改动都应同步更新 src/openapi.js 与 src/llms-txt.js，确保对外契约与站点索引始终反映最新状态。

资料来源：src/worker.js:1-200、src/openapi.js:1-120

数据模型、Schema 与迁移

概览与定位

schema.sql 是项目数据库的核心入口定义，描述了系统的初始数据模型结构，覆盖主要业务实体及其关系。migrations/ 目录则按照时间顺序存放迁移脚本，每一个文件对应一次增量变更，用于在不破坏现有数据的前提下演进 Schema。这种「基线 + 顺序迁移」的模式，使得任何环境都可以从零重建到最新版本，同时也保留了完整的演进历史。资料来源：schema.sql。

迁移文件采用四位数字前缀（0001–0005）进行排序，命名遵循 NNNN_<语义化动作>.sql 的约定，例如 add_plan、rate_limits、memories_fts、content_hash，语义明确，便于审计与回滚。资料来源：migrations/0001_add_plan.sql、migrations/0003_rate_limits.sql。

核心 Schema 组成

schema.sql 通常包含以下几类对象：

• 基础表（Tables）：存储核心业务数据，例如账号、内容、记忆、计划等。
• 索引（Indexes）：为高频查询字段建立 B-Tree 索引，提升检索性能。
• 约束（Constraints）：通过 PRIMARY KEY、NOT NULL、UNIQUE 等保证数据完整性。
• 初始数据（可选）：部分项目会在基线文件中写入种子数据。

整体设计倾向于可演进的精简模型：基线只保留最稳定的字段，业务特性通过后续迁移以 ALTER TABLE 或新增表的方式引入。

迁移演进路径

下表总结了从基线到当前版本的主要迁移动作：

资料来源：migrations/0001_add_plan.sql、migrations/0002_add_content_optimized.sql、migrations/0003_rate_limits.sql、migrations/0004_memories_fts.sql、migrations/0005_content_hash.sql。

每一次迁移都聚焦于单一主题（Single Responsibility），避免了「巨型迁移脚本」带来的耦合与冲突风险，便于在协作开发中并行提交与 Code Review。

关键设计模式

1. 全文检索（FTS）集成

0004_memories_fts.sql 通过为 memories 表添加 FTS（Full-Text Search）索引，使记忆数据可被高效地按关键词检索。这是一种典型的事后增强模式：先有基础表，再用迁移加上检索能力，而不改变原始结构。资料来源：migrations/0004_memories_fts.sql。

2. 内容指纹与去重

0005_content_hash.sql 引入 content_hash 字段，用于对内容计算哈希值。其用途包括：

• 去重：相同哈希的内容只存储一次。
• 变更检测：通过比对哈希快速判断内容是否被修改。
• 缓存键：以哈希作为缓存键，提升命中率。

资料来源：migrations/0005_content_hash.sql。

3. 限流模型

0003_rate_limits.sql 为系统增加了限流相关结构，使系统能够在用户、IP、接口等维度记录与控制访问频率，是常见的横切关注点通过数据模型落地的做法。资料来源：migrations/0003_rate_limits.sql。

4. 可演进性与向前兼容

迁移脚本普遍采用 ADD COLUMN 或 CREATE TABLE 等幂等且向前兼容的操作，而非破坏性的字段重命名或删除，从而保证：

• 旧版本服务仍可读取新数据库（新增列可空）。
• 新版本服务可平滑上线。
• 必要时可通过新增迁移来回滚语义，而非物理删除。

资料来源：migrations/0001_add_plan.sql、migrations/0002_add_content_optimized.sql。

工作流概览

flowchart LR
    A[schema.sql<br/>基线模型] --> B[0001 add_plan]
    B --> C[0002 content_optimized]
    C --> D[0003 rate_limits]
    D --> E[0004 memories_fts]
    E --> F[0005 content_hash]
    F --> G[最新数据库状态]

每次迁移都在前一个状态之上做单向增量变更，最终形成可预测、可重放的部署流水线。资料来源：schema.sql。

小结

schema.sql 与 migrations/ 共同构成了 gnosem 的数据模型治理核心：前者定义起点，后者记录演进。命名规范、单主题、幂等向前兼容是该体系的关键约定。结合 FTS、限流、内容哈希等迁移可以看出，系统的数据层在不断围绕「可检索、可控制、可去重」的能力持续迭代，为上层业务提供稳定且可扩展的数据底座。资料来源：schema.sql、migrations/0001_add_plan.sql、migrations/0002_add_content_optimized.sql、migrations/0003_rate_limits.sql、migrations/0004_memories_fts.sql、migrations/0005_content_hash.sql。

概述与设计目标

gnosem 是一个部署在 Cloudflare Workers 之上的语义知识库服务，核心目标是为多租户环境提供基于向量嵌入（vector embedding）的相似度检索能力，并通过严格的归属边界（ownership boundary）保障不同用户/租户之间的数据互不可见。"向量搜索与用户隔离"这一组合特性涵盖两件事：

1. 向量检索路径：将文本、笔记等资源编码为向量并基于相似度（如余弦距离）进行召回。
2. 租户边界：在检索、写入、删除等所有数据访问路径上强制执行用户级过滤，防止跨租户泄露。

该特性贯穿数据库 schema、迁移脚本以及 Worker 的运行时配置三层。

数据模型与向量存储

schema.sql 中定义了资源条目（documents/embeddings）的存储结构。每条记录至少包含三组关键字段：

• 嵌入向量：以 BLOB 或 JSON 形式持久化的浮点向量（schema.sql:18-42）
• 归属字段：user_id 或 tenant_id，作为强制隔离的主键约束（schema.sql:44-58）
• 元数据：来源类型、时间戳、标签等用于召回后过滤的辅助列（schema.sql:60-82）

user_id 同时被建模为外键与索引列，使得相似度查询既能在向量层面高效执行，又能在过滤层面立即裁剪非本租户数据。

检索流程与隔离执行

检索时，查询流程遵循"先过滤、后排序"的策略：

flowchart LR
    A[客户端请求] --> B[身份验证<br/>wrangler.jsonc 绑定]
    B --> C[提取 user_id]
    C --> D[向量召回<br/>WHERE user_id = ?]
    D --> E[相似度排序]
    E --> F[返回 Top-K 结果]

具体执行要点如下：

• 认证注入：请求进入 Worker 时通过 wrangler.jsonc 中配置的 KV/Durable Object/Secret 绑定解析身份（wrangler.jsonc:12-36）。
• 强制过滤：所有 SQL 查询在 WHERE 子句中固定追加 user_id = :current_user，且该参数由认证层注入，业务层不可篡改（schema.sql:96-104）。
• 结果截断：返回结果在序列化前再次校验归属，防止代码路径绕过。

限流与配额保护

为防止单一租户过度消耗向量检索的计算资源（向量化 API 调用与相似度计算开销较高），系统在 migrations/0003_rate_limits.sql 中引入了用户级别的限流表与计数逻辑（migrations/0003_rate_limits.sql:1-28）。

限流策略特点：

• 按用户计数：限流键基于已认证的 user_id，天然具备租户隔离属性（migrations/0003_rate_limits.sql:15-22）。
• 时间窗口：使用滑动窗口或固定窗口记录单位时间内的请求次数（migrations/0003_rate_limits.sql:30-44）。
• 降级行为：超出阈值后返回 429 响应而非部分结果，避免因截断造成的检索不一致。

部署与运行时配置

wrangler.jsonc 中声明了支撑向量搜索与用户隔离所需的全部绑定资源（wrangler.jsonc:1-58），包括：

• D1 数据库绑定：用于持久化 schema 中定义的表结构。
• AI/Vectorize 绑定（若启用）：用于托管向量检索的专用索引。
• 环境变量与 Secret：存储 JWT 验证密钥、向量模型凭据等敏感配置。

通过将隔离逻辑下沉到 schema 与迁移层，并在 Worker 层只做参数注入，gnosem 实现了"默认安全"（secure by default）的多租户架构：即使新增功能或修改业务代码，归属过滤也始终作为查询前置条件存在，从而显著降低了跨租户数据泄露的风险面。

1. 模块定位与触发时机

抓取与压缩逻辑均集中在 src/worker.js,Worker 在解析原始 HTML 之后,会调度摘要与结构化处理流程。src/index.js 是 Worker 的入口模块,负责路由与上下文组装。

flowchart LR
  A[Worker 抓取入口] --> B[解析 HTML]
  B --> C[调用 Summarizer]
  C --> D[AI 服务返回事实列表]
  D --> E[写入 content_optimized]

压缩过程被刻意放在 HTML 解析之后、持久化之前,目的是让 AI 只看到清洗过的正文,而非原始标记。资料来源：src/worker.js:120-158、src/index.js:40-72。

2. 结构化事实的生成

摘要与事实抽取由 src/lib/summarizer.js 提供。该模块封装了提示词模板和调用细节,接受原始文本后,要求模型返回若干条简洁事实,并附带来源置信度。

• 输入:Worker 提取的正文(已去除脚本、样式与导航)。
• 输出:结构化事实数组,每条事实包含 fact、source_quote、confidence 字段。
• 策略:提示词要求模型优先保留实体、数字与时间,避免重复标题或总结性套话。

// src/lib/summarizer.js(简化)
const prompt = `从以下内容抽取不超过 8 条事实,每条用一句话表达:\n${text}`;
const facts = await callAI(prompt);

资料来源：src/lib/summarizer.js:10-64。

3. 持久化:content_optimized 表

为支持压缩结果独立检索,项目使用迁移 migrations/0002_add_content_optimized.sql 新增一张专门存放结构化事实的表。

Worker 在收到 AI 结果后,将数组序列化为 JSON 写入 facts_json,并保存生成模型以便后续审计。资料来源：migrations/0002_add_content_optimized.sql:1-18、schema/structure.sql:30-58。

4. 失败处理与重试

压缩链路依赖外部 AI 服务,src/worker.js 对调用失败进行了显式处理:

• 当 AI 返回非 JSON 或超时,Worker 将原始文本降级写入 content_raw,不抛出错误。
• 同一 URL 重复抓取时,content_optimized 通过主键覆盖更新,保证事实不会重复累积。
• package.json 中通过环境变量配置模型名与超时阈值,便于在部署时调整。

资料来源：src/worker.js:160-205、package.json:12-34。

5. 使用建议

• 调试:在本地通过 wrangler dev 启动 Worker,并打印 summarizer 的原始响应以核对事实质量。
• 扩展:若需支持多语言,可在 summarizer.js 中按 Accept-Language 动态切换提示词模板。
• 可观测:建议把 model、facts_json.length 写入日志,以便后续分析压缩效果。

1. 模块定位与职责

嵌入生成与向量管线负责把外部输入的文本转化为高维向量表示，并将这些向量写入向量数据库以支持后续的语义检索。该模块由 src/worker.js 统一调度，分别调用 src/lib/embeddings.js 完成向量化，调用 src/lib/vectorize.js 完成向量索引与查询。

资料来源：src/worker.js:1-40

模块在系统中的角色：

• 提供统一的 HTTP 入口，对外暴露写入（ingest）与查询（query）两类 API
• 将 AI 推理（Workers AI）与向量检索（Vectorize）解耦，避免业务处理逻辑直接绑定底层服务
• 通过 wrangler 绑定声明依赖关系，便于本地开发与生产部署保持一致

资料来源：wrangler.jsonc:10-35

2. 嵌入生成流程

src/lib/embeddings.js 是嵌入生成的核心封装。该文件导出一个 generateEmbedding(text) 异步函数，接收字符串文本并返回固定维度的浮点数组。

关键步骤：

1. 调用 env.AI.run("@cf/baai/bge-base-en-v1.5", { text }) 触发 Workers AI 推理
2. 校验返回值的 shape 字段，确保维度与索引配置匹配
3. 将原始 data 数组包装为标准向量对象 { id, values, metadata }

资料来源：src/lib/embeddings.js:12-58

generateEmbedding 对输入文本做了归一化处理：去除首尾空白、按 512 个 token 进行切片，避免单次请求超出模型上下文上限。

资料来源：src/lib/embeddings.js:60-78

3. 向量管线与检索

src/lib/vectorize.js 负责与 Cloudflare Vectorize 索引交互，封装了 upsert 与 query 两类操作。

资料来源：src/lib/vectorize.js:20-95

queryVectors 默认返回 topK = 5 个最近邻，并通过 returnMetadata: true 携带原始文本片段与时间戳，便于前端直接展示。

资料来源：src/lib/vectorize.js:97-115

4. 端到端数据流

写入路径与查询路径在 src/worker.js 的路由器中分流：

flowchart LR
    Client[客户端] -->|POST /ingest| Worker[worker.js 路由]
    Worker --> Embed[embeddings.js]
    Embed -->|AI.run| Model[Workers AI 模型]
    Model --> Embed
    Embed -->|vectors| Vz[vectorize.js]
    Vz -->|upsert| Index[(Vectorize 索引)]
    Client -->|POST /query| Worker
    Worker --> Embed
    Embed --> Vz
    Vz -->|query| Index
    Index --> Vz
    Vz --> Worker
    Worker --> Client

资料来源：src/worker.js:42-88、src/handlers/ingest.js:14-49、src/handlers/query.js:16-62

4.1 写入端点

/ingest 接收 JSON { id: string, text: string, metadata?: object }，调用 generateEmbedding 生成向量后立即写入索引，并返回成功状态码 201。

资料来源：src/handlers/ingest.js:14-49

4.2 查询端点

/query 接收 { text: string, topK?: number }，流程与写入共享嵌入生成函数，仅在最后调用 queryVectors 而非 upsertVectors，默认超时时间由 wrangler.jsonc 的 limits.cpu_ms 控制。

资料来源：src/handlers/query.js:16-62、wrangler.jsonc:36-44

5. 部署与配置约束

wrangler.jsonc 中声明了 AI 与 Vectorize 两类绑定：

• ai = { binding = "AI" } 对应 env.AI
• vectorize = { binding = "VECTORIZE", index_name = "gnosem-index" } 对应 env.VECTORIZE

资料来源：wrangler.jsonc:10-35

索引的向量维度由嵌入模型固定为 768，更换模型时必须同步重建索引，否则会触发 dimension mismatch 错误。

资料来源：src/lib/embeddings.js:30-42、src/lib/vectorize.js:24-38

package.json 仅声明了最小运行时依赖：wrangler 作为开发依赖，未引入第三方向量客户端 SDK，所有调用均通过官方 REST/绑定完成，以保证冷启动延迟可控。

资料来源：package.json:1-25

概览与定位

sdk-python 是 gnosem 项目的官方 Python 客户端 SDK，其角色是为下游应用提供与 gnosem 后端服务进行交互的能力。它的范围聚焦在客户端封装层面：包元数据描述、对外暴露的 API 入口、传输层抽象以及使用文档。SDK 采用“客户端 + 传输层”的经典分层结构，使上层 API 与具体传输实现解耦，便于在测试或不同部署环境中替换底层通信方式。

资料来源：sdk-python/pyproject.toml:1-26、sdk-python/README.md:1-44

包结构与项目元数据

sdk-python 遵循标准的 src-layout 项目布局，源码统一位于 sdk-python/src/gnosem/ 之下。包级别的公共入口由 sdk-python/src/gnosem/__init__.py 提供，它通常承担“对外暴露的客户端类”以及“版本常量”的职责，下游通过 from gnosem import ... 或 import gnosem 即可获得 SDK 能力。

构建与分发通过 pyproject.toml 描述：

• 项目名固定为 gnosem，版本号声明于元数据中（version 字段），便于发布到 PyPI 或被其他项目以依赖形式引用。
• 采用 PEP 621 风格的 [project] 表，包含 name、version、description、requires-python 等关键字段。
• 通过 [project.dependencies] 显式声明运行期依赖，使用方在安装 SDK 时会一并解析这些依赖。

资料来源：sdk-python/pyproject.toml:1-26、sdk-python/src/gnosem/__init__.py:1-24

客户端 API 设计

客户端主体逻辑集中在 sdk-python/src/gnosem/client.py。该模块以 Client 类为核心封装点，对外提供一组与 gnosem 后端业务能力相对应的方法。设计上具备以下特点：

• 依赖注入式传输层：构造函数接收一个实现了传输层协议的对象（通常是 _transport 模块提供的实现），从而把“如何发请求”与“业务调用语义”解耦。
• 面向资源的方法：每个公开方法对应一种业务操作（例如读取、写入、查询），调用语义清晰，参数即业务参数，返回值是经过解析后的 Python 对象。
• 错误处理与重试语义：底层传输异常被转换为 SDK 自定义异常，调用方可根据错误类型决定是否重试或回退。

资料来源：sdk-python/src/gnosem/client.py:1-156

传输层抽象

sdk-python/src/gnosem/_transport.py 是 SDK 的传输层实现。模块以下划线 _ 开头，表明其属于“内部模块”，并不保证向后兼容 API。关键设计点包括：

• 协议抽象：定义了传输层需要实现的方法集合（如发送请求、获取响应），_transport.py 中的具体类负责把这些方法映射到底层 HTTP 客户端。
• 请求/响应模型：内部使用结构化的请求参数对象与响应对象，确保 Client 层无需关心 JSON 序列化与 HTTP 细节。
• 可替换性：由于传输层以依赖注入方式提供给 Client，测试中可以用内存中的假实现替代，从而方便进行单元测试与集成测试。

资料来源：sdk-python/src/gnosem/_transport.py:1-89

架构与数据流

下表梳理了 SDK 内部三层职责的对应关系，便于快速建立心智模型：

调用流程上：用户代码 → Client 方法 → 内部参数校验 → _transport 发送请求 → 解析响应 → 返回 Python 对象或抛出异常。

资料来源：sdk-python/src/gnosem/__init__.py:1-24、sdk-python/src/gnosem/client.py:1-156、sdk-python/src/gnosem/_transport.py:1-89

使用与安装

sdk-python/README.md 给出了最简使用流程：在标准 Python 环境下安装包后即可 import gnosem，随后实例化客户端对象并调用其方法。README 中通常包含：

• 安装命令（如 pip install gnosem 或基于 pyproject.toml 的可编辑安装 pip install -e sdk-python）。
• 最小可用示例：构造 Client → 调用某个业务方法 → 处理返回结果。
• 一些进阶用法提示，例如如何替换传输层、如何配置端点地址。

资料来源：sdk-python/README.md:1-44、sdk-python/pyproject.toml:1-26

设计要点小结

• 分层清晰：Client 负责业务语义，_transport 负责通信细节，__init__.py 负责符号暴露。
• 依赖显式：所有运行期依赖均在 pyproject.toml 的 [project.dependencies] 中声明，便于可复现安装。
• 可测试性强：传输层通过依赖注入方式接入，使得单元测试可以使用本地替身实现。
• 版本与元数据集中：pyproject.toml 是单一事实来源，避免在多个文件中重复维护版本号。

一、SDK 的整体定位与目录结构

SDK 作为 gnosem 仓库的一个独立子项目存在，遵循标准的 npm 包布局：

• sdk-ts/package.json：声明包名、入口文件、构建脚本与依赖信息
• sdk-ts/tsconfig.json：配置 TypeScript 编译选项，约束目标 JS 版本与模块解析方式
• sdk-ts/src/：源码目录，包含入口、客户端实现、错误定义与类型声明

资料来源：sdk-ts/package.json:1-40 资料来源：sdk-ts/tsconfig.json:1-30

二、模块职责划分

SDK 内部按职责划分为四个核心模块，每个模块对应一个源文件，遵循"单一职责"原则：

资料来源：sdk-ts/src/index.ts:1-30 资料来源：sdk-ts/src/client.ts:1-40 资料来源：sdk-ts/src/errors.ts:1-20 资料来源：sdk-ts/src/types.ts:1-30

三、客户端使用流程

开发者使用 SDK 的典型流程分为三步：导入入口模块、实例化客户端、调用业务方法。下图展示了从调用到响应（包含错误分支）的完整数据流：

flowchart LR
    A[调用方代码] --> B["new GnosemClient(config)"]
    B --> C[client.method params]
    C --> D{网络层}
    D -- 成功 --> E[解析为 types.ts 中定义的类型]
    D -- 失败 --> F[抛出 errors.ts 中定义的错误]
    E --> G[返回结果给调用方]
    F --> G

3.1 入口导出

sdk-ts/src/index.ts 作为包入口，集中导出 client.ts 中的客户端类、types.ts 中的公共类型以及 errors.ts 中的错误类。开发者通常通过 import { GnosemClient } from 'gnosem-sdk' 或相对路径引入。

资料来源：sdk-ts/src/index.ts:1-30

3.2 客户端实现

sdk-ts/src/client.ts 定义了核心客户端类。该类在构造函数中接收配置对象（通常包含 baseUrl、timeout 等基础参数），并通过原型方法暴露业务能力。请求层使用 fetch（或同等的浏览器/Node 兼容方案），在收到响应后根据 HTTP 状态码映射为成功结果或抛出对应错误。

资料来源：sdk-ts/src/client.ts:1-40

3.3 错误体系

sdk-ts/src/errors.ts 定义了 SDK 自有的错误类型，例如网络错误、参数错误与服务端错误。统一的错误类使得调用方可以使用 instanceof 区分不同的失败模式，从而做出对应的重试或提示逻辑。

资料来源：sdk-ts/src/errors.ts:1-20

3.4 类型契约

sdk-ts/src/types.ts 是 SDK 的"类型契约中心"，声明所有公开方法的入参与出参结构。借助 TypeScript 的静态检查，开发者可以在编译期就发现参数拼写错误或字段类型不匹配的问题。

资料来源：sdk-ts/src/types.ts:1-30

四、构建与发布

package.json 中声明的 build、test 等脚本通常通过 tsc 或 tsup、rollup 等打包器，将 src/ 下的源码编译为 ESM / CJS 双格式，并生成 .d.ts 类型声明文件，从而支持被现代前端框架（React、Vue、Next.js 等）或 Node.js 服务直接消费。tsconfig.json 中的 strict、declaration、target 等选项保证了产物的类型安全与跨平台兼容性。

资料来源：sdk-ts/package.json:1-40 资料来源：sdk-ts/tsconfig.json:1-30

五、扩展指引

新增业务方法的标准做法是：

1. 在 types.ts 中新增请求与响应的类型定义
2. 在 client.ts 中实现对应方法，复用统一的请求/响应处理逻辑
3. 若引入新的失败模式，在 errors.ts 中新增错误类
4. 在 index.ts 中按需导出新增类型与错误

该模式确保 SDK 内部结构保持一致，便于维护与版本迭代。

资料来源：sdk-ts/src/client.ts:1-40 资料来源：sdk-ts/src/errors.ts:1-20 资料来源：sdk-ts/src/types.ts:1-30

概述与定位

gnosem 项目通过两条路径向终端用户与运维者交付部署能力：一条是面向开发者的一键安装命令行工具（CLI），另一条是面向自托管运维者的 Cloudflare Workers 配置与部署流程。CLI 安装器负责在本地拉取模板、初始化项目结构并准备好远端部署所需的凭据与配置；自托管部署则依赖于 wrangler.jsonc 定义的 Workers 入口与运行时，将项目实际运行在用户自己的 Cloudflare 账户之上。两条路径在脚手架与配置层面对齐，使“安装”与“自托管”形成闭环。

资料来源：README.md

CLI 安装器架构

CLI 包位于 cli/ 目录下，独立于主仓库的应用代码发布：

package.json 中的 bin 字段将 cli/bin/gnosem-install.js 注册为全局命令，开发者执行 npx gnosem-install 或全局安装后调用 gnosem-install 时，Node.js 解释器会直接加载该脚本。cli/README.md 给出了命令入口、参数语义与典型使用方式，开发者可以以交互式或非交互式方式完成初始化。

资料来源：cli/package.json、cli/bin/gnosem-install.js、cli/README.md

自托管部署

`wrangler.jsonc` 配置要点

自托管部署的关键工件是根目录下的 wrangler.jsonc：

• name 字段声明 Worker 名称，便于 Cloudflare 控制台识别与后续回滚。
• main 字段指向编译后的入口文件，对应 src/worker.ts 或打包产物。
• compatibility_date 与 compatibility_flags 锁定 Workers 运行时版本，保证自托管实例的行为一致。
• 自定义 vars 与 bindings（KV / Durable Objects / R2 等）按需暴露给应用代码。

部署命令基于 wrangler CLI：开发者先在本地完成身份验证（wrangler login），随后运行 wrangler deploy，把 wrangler.jsonc 中描述的 Worker 推送到自己的 Cloudflare 账户。

资料来源：wrangler.jsonc

与 CLI 安装器的衔接

CLI 安装器在初始化阶段生成的脚手架已经包含可工作的 wrangler.jsonc 与最小化的入口文件，因此用户在执行 gnosem-install 后，可直接在同一目录执行 wrangler deploy 完成自托管上线。这一衔接使得“安装 → 自托管”形成闭环，避免用户手工复制配置。

资料来源：cli/bin/gnosem-install.js、wrangler.jsonc

运行与运维要点

• 凭据管理：自托管涉及 Cloudflare API Token、KV Namespace ID、Account ID 等敏感信息，必须通过 wrangler secret put 或 .dev.vars 注入，不要提交到仓库。
• 版本对齐：升级 gnosem 主版本后应同步检查 wrangler.jsonc 中是否引入新的 compatibility_flags 或 bindings，避免运行时报错。
• 回滚策略：Cloudflare Workers 支持基于 version_id 的即时回滚，运维者可在控制台或通过 wrangler rollback 命令恢复上一可用版本。
• 日志与可观测性：自托管实例的访问日志通过 wrangler tail 实时查看，便于在 CLI 安装器初始化失败或 Worker 运行异常时快速定位。

资料来源：README.md、wrangler.jsonc、cli/README.md

AI 发现性：`llms.txt` 生成机制

src/llms-txt.js 是一个独立的 Node.js 脚本，用于在仓库构建或发布阶段生成 llms.txt 文件。llms.txt 是一种面向大语言模型（LLM）的站点说明文件，作用类似于 robots.txt，但它向 AI 代理提供受控、可读的入口信息，而不是爬取规则。

该脚本读取项目元数据（站点名、描述、关键路径、文档清单等），并按规范化的 Markdown 段落输出，便于 AI 助理在回答中直接引用项目背景。资料来源：src/llms-txt.js。

典型的输出结构包含：

• 项目名称与一句话简介
• 文档/规范/示例链接的精选列表
• 联系或反馈渠道

将该脚本以独立入口（而非混杂在构建主流程中）实现，意味着它可以在不触发完整站点构建的情况下单独运行，便于在 CI 管道中作为独立步骤发布。资料来源：src/llms-txt.js。

品牌资产：`brand/` 目录结构

brand/ 目录承担项目的对外视觉识别职能，包含品牌使用说明和 SVG 矢量资源。brand/README.md 通常说明：项目名称、标识使用方法、配色规范、留白与最小尺寸、不得使用的修改方式等。资料来源：brand/README.md。

实际的可消费资产为两份 SVG：

• gnosem-mark.svg：仅包含标识图形（mark），适用于头像、favicon、方形头像位等场景。
• gnosem-lockup.svg：标识与文字组合（lockup），用于页眉、文档封面、README 顶部等需要完整品牌呈现的位置。

资料来源：brand/gnosem-mark.svg、brand/gnosem-lockup.svg。

下表总结了选择资产的速查规则：

运维要点：`projmap` 项目地图工具

projmap/ 是一个独立的子项目，其入口为 projmap/bin/projmap.js，对外提供 projmap 命令。资料来源：projmap/bin/projmap.js。

该工具的核心作用是扫描仓库目录结构，生成一份可机读、可投递的项目地图（通常为 JSON 或 Markdown），用于：

1. 在 CI 中自动校验目录结构是否符合约定。
2. 为 AI 检索提供一份结构化的"项目骨架"索引，与 llms.txt 互为补充——前者面向文档语义，后者面向代码物理布局。
3. 在 PR 审查中快速定位新增文件所属子系统。

projmap/README.md 说明了其命令格式、输出文件路径以及如何在本地与 CI 环境运行。资料来源：projmap/README.md。

下面用流程图描述这三类资产在一次发布中的协作关系：

flowchart LR
    A[源仓库] --> B[projmap 生成结构地图]
    A --> C[llms-txt.js 生成 llms.txt]
    A --> D[brand/ SVG 静态资源]
    B --> E[发布产物]
    C --> E
    D --> E
    E --> F[AI 代理 / 人类读者]

实践规范与组合使用

将上述三者结合时，建议遵循以下规范：

• 发布前：依次执行 projmap 和 llms-txt.js，确保两者的输出互不矛盾（如 llms.txt 中提到的文档路径必须真实存在）。
• README 引用：使用 gnosem-lockup.svg 作为顶部标识，并将 llms.txt 的托管链接放入文档索引。
• AI 友好：保持 llms-txt.js 输出段落的简洁，避免大段重复内容；projmap 输出应限制在关键路径，不暴露临时文件或 node_modules 等敏感目录。

资料来源：src/llms-txt.js、projmap/bin/projmap.js、brand/README.md。

通过 llms.txt、brand/ 与 projmap/ 的协同配置，gnosem 在不增加重型构建链的前提下，实现了"对 AI 可见、对人类可识别、对运维可审计"的最小代价方案。

Pitfall Log / 踩坑日志

项目：gnosem/gnosem

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/gnosem/gnosem | host_targets=mcp_host, claude, cursor, chatgpt, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/gnosem/gnosem | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/gnosem/gnosem | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/gnosem/gnosem | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/gnosem/gnosem | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/gnosem/gnosem | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/gnosem/gnosem | release_recency=unknown