定位与核心目标

ShapeLex 的核心目标是将大型语言模型（LLM）应用中的上下文与长文本转换为可控的本地记忆资源，避免敏感数据外发到远端压缩服务。该项目并非通用压缩工具，而是一个具备以下特性的领域专用层：

• 本地优先：所有压缩、展开、统计操作均在本地 Node.js 进程中完成，不依赖外部网络 资料来源：README.md:1-40。
• 会话级遥测：每个会话累积统计压缩比、字节节省与启发式估算值，便于在调用方侧观察开销 资料来源：CHANGELOG.md:1-30。
• 校验一致性：通过校验和（checksum）比对源文件，源文件变更后自动使旧句柄失效，防止脏读 资料来源：CHANGELOG.md:1-30。

系统组成与模块划分

ShapeLex 的代码组织围绕"压缩句柄（handle）"这一中心概念展开。系统主要由以下几部分组成：

• CLI 入口层：负责解析命令行参数、读取输入文件并调用核心压缩 API 资料来源：package.json:1-40。
• 核心压缩引擎：实现文本压缩、展开、统计的算法路径，并在内部维护 per-session 计数 资料来源：docs/architecture.md:1-60。
• 工作空间绑定层：通过 shapelex_compress_text.sourcePath 等配置项，将压缩数据绑定到特定工作目录，避免跨工程误用 资料来源：CHANGELOG.md:1-30。

下表展示了一次典型调用中的关键参数与对应行为：

工作流程

ShapeLex 在一次完整的"压缩—存储—展开"循环中，遵循以下步骤：

1. 调用方通过 CLI 或 API 提交待压缩文本，并可附带上 sourcePath。
2. 引擎计算源内容校验和，并执行压缩，生成带元数据的句柄。
3. 句柄与当前工作空间绑定，会话统计累加本次字节数。
4. 后续展开时引擎重新校验源文件；若源文件已变更，则拒绝使用旧句柄，确保展开结果与原始输入严格一致。

该流程强调"安全回放"而非"高性能压缩"，因此在设计上偏向可观测与可验证，而不是追求极限压缩率。

版本演进与现状

根据发布记录，ShapeLex 已从最初的原型演化为 v0.5.0 版本，定位为"更安全、更低开销的本地记忆层"。在 0.5.0 中，项目新增了累积会话遥测、显式启发式估算标签、工作空间绑定压缩以及校验和校验的展开路径，同时移除了若干不再维护的早期入口 资料来源：CHANGELOG.md:1-30。安全策略方面，项目在 SECURITY.md 中声明了本地处理优先、不上传用户数据的原则，并提供了漏洞报告通道 资料来源：SECURITY.md:1-40。

适用场景与限制

ShapeLex 适合以下场景：

• 在本地开发或自托管环境中，需要为 LLM 调用维护长上下文快照。
• 需要在多轮会话中持久化压缩文本，并希望获得压缩比与字节节省的可观测指标。
• 出于合规或隐私要求，必须避免将文本发送给远端压缩服务。

同时需注意以下限制：项目仍处于 0.x 阶段，API 与句柄格式可能在后续版本中调整；压缩算法针对文本与对话上下文优化，并非通用归档工具；当源文件在工作空间之外被修改时，校验和校验可能无法覆盖全部篡改路径 资料来源：docs/QUICKSTART.md:1-60。

概述

ShapeLex 作为本地内存压缩层，向 AI 工具（代理、IDE 助手、对话客户端）暴露一对原子化能力：shapelex_compress_text 与 shapelex_expand_text。所谓"AI 工具集成配置"，即外部工具如何声明、寻址并调用这两个工具，以及如何把会话级的压缩统计、路径约束与校验语义嵌入到工具上下文中的过程。资料来源：README.md:1-40 描述 ShapeLex 作为一个低开销、安全的本地内存层设计目标；CHANGELOG.md:1-20 列出 v0.5.0 中关于 sourcePath 路径约束与 checksum 校验的关键变更。

工具声明与环境准备

MCP 风格的工具注册

ShapeLex 推荐以 MCP（Model Context Protocol）兼容的方式向宿主 AI 工具声明工具。AGENT_SETUP_PROMPT.md 给出了一份可直接复制的提示词模板，用于把压缩与恢复工具暴露给大模型。资料来源：docs/AGENT_SETUP_PROMPT.md:1-40 提供了完整声明示例，列出了 shapelex_compress_text、shapelex_expand_text 两个工具的参数与返回值描述。

工作区与路径约束

v0.5.0 起，压缩结果支持绑定到具体源文件路径，避免在多会话、多项目场景下出现"句柄漂移"。当调用 shapelex_compress_text.sourcePath 时，必须传入一个落在当前 AI 工具工作区之内的相对或绝对路径；调用方有责任拒绝任何逃逸出工作区根目录的路径。资料来源：CHANGELOG.md:1-15 明确指出 "workspace-bound file-backed compression through shapelex_compress_text.sourcePath"。

调用语义

压缩调用

shapelex_compress_text(text: string, sourcePath?: string) -> { handle: string }

调用完成后返回一个 handle（句柄），AI 工具应将其作为键保存于会话上下文中。资料来源：docs/USAGE.md:1-40 描述了基本调用流程；中文与西语版本保持一致语义，可在 docs/USAGE.es.md:1-40 交叉验证。

恢复与失效

shapelex_expand_text(handle) 在恢复时会对源文件做 checksum 校验；若绑定 sourcePath 的文件被修改，则返回失效错误并拒绝重建。资料来源：CHANGELOG.md:1-15 描述 "checksum-verified expansion so changed source files invalidate stale handles"。AI 工具应据此提示用户"句柄已失效，需重新压缩"。

集成流程示意

sequenceDiagram
    participant Agent as AI 工具
    participant SL as ShapeLex
    Agent->>SL: compress_text(text, sourcePath)
    SL-->>Agent: handle
    Note over Agent: 在上下文记录 handle
    Agent->>SL: expand_text(handle)
    SL->>SL: 校验 sourcePath checksum
    SL-->>Agent: 原文（若失效则报错）

上图为典型集成流程。资料来源：docs/USAGE.md:1-40 配合 docs/AGENT_SETUP_PROMPT.md:1-40 共同印证。

配置清单

资料来源：README.md:1-40 概述了 ShapeLex 的目标边界；CHANGELOG.md:1-15 解释了 sourcePath 的引入动机。

注意事项

• 所有压缩为启发式估计，统计标签会显式标注；AI 工具不应将压缩率视为精确指标。资料来源：CHANGELOG.md:1-10。
• 句柄仅在本地内存中持久化，跨进程或跨设备共享不被支持。
• 当 sourcePath 文件被改动后，应重新执行压缩，避免读到陈旧内容。

一、总体设计目标

ShapeLex 0.5.0 在早期原型基础上，重塑为一个"更安全、开销更低的本地记忆层"。整体架构围绕以下三个原则展开：

• 本地优先：压缩与存储均在本地进程内完成，避免外部依赖。
• 工作区绑定：通过 shapelex_compress_text.sourcePath 将文件级压缩与具体工作目录绑定，防止跨上下文误用。
• 可验证失效：当源文件内容变化时，校验和机制会让过期句柄自动失效，避免使用陈旧压缩结果。

资料来源：src/shaxelex.ts:1-40 bin/shapelex-mcp.js:1-30

二、运行时与进程边界

ShapeLex 以 MCP 服务器的形式对外暴露能力。运行时分两层进程结构：

CLI 层负责把执行环境切换到 MCP 模式，注册工具列表与初始化参数，然后调用服务器层的启动逻辑。版本号则在编译期由 src/version.ts 注入，供握手阶段返回给客户端。

资料来源：bin/shaxelex-mcp.js:10-60 src/mcp-server.ts:1-50 src/version.ts:1-20

三、核心模块与依赖关系

flowchart TD
    Client[MCP 客户端] --> CLI[bin/shapelex-mcp.js]
    CLI --> Server[src/mcp-server.ts]
    Server --> Core[src/shapelex.ts<br/>核心压缩与展开]
    Core --> Storage[src/storage/index.ts<br/>持久化后端]
    Core --> Fingerprint[src/fingerprint/index.ts<br/>校验与失效]
    Storage --> Disk[(本地存储)]
    Fingerprint -.校验源文件.-> Disk

• 核心模块（src/shapelex.ts）：实现 shapelex_compress_text / shapelex_expand_text 等工具方法的算法与启发式估算逻辑。
• 存储模块（src/storage/index.ts）：抽象底层持久化路径，对外提供统一读写接口，便于在不同本地后端之间替换。
• 指纹模块（src/fingerprint/index.ts）：负责源文件校验、内容摘要与失效判定，确保 expand 调用返回最新数据。
• 服务器模块（src/mcp-server.ts）：将上述模块包装为 MCP 工具，并管理会话级遥测。
• 入口脚本（bin/shapelex-mcp.js）：作为 npm 可执行入口，承载 CLI 启动与进程派发。

资料来源：src/shaxelex.ts:40-120 src/storage/index.ts:1-60 src/fingerprint/index.ts:1-50

四、数据流与生命周期

一次典型的 compress → expand 调用按以下顺序流转：

1. 客户端调用：MCP 客户端发起 shapelex_compress_text，可携带 sourcePath 指定源文件。
2. 服务器分发：src/mcp-server.ts 接收请求，解析参数并校验工作区绑定。
3. 压缩处理：src/shapelex.ts 应用启发式估算，产出压缩句柄并累积会话遥测（标注为启发式估算器）。
4. 持久化：src/storage/index.ts 把句柄写入本地后端，记录路径与元数据。
5. 指纹登记：src/fingerprint/index.ts 计算源文件校验和并与句柄关联。
6. 后续展开：客户端调用 shapelex_expand_text 时，服务器先比对校验和——若源文件变化，则判定句柄失效并要求重压缩。

这一闭环既保证了压缩的复用率，也避免了在源文件被修改后返回错误内容。

资料来源：src/mcp-server.ts:60-140 src/shaxelex.ts:120-200 src/storage/index.ts:60-110 src/fingerprint/index.ts:50-100

五、安全与开销优化（v0.5.0）

为响应社区对"原型阶段风险与冗余"的反馈，0.5.0 在架构层面引入：

• 会话级压缩遥测：累计每会话压缩量，并显式标记为启发式估算结果，便于客户端校准期望。
• 工作区绑定：sourcePath 成为压缩必要字段，使句柄无法在无关目录中被误用。
• 校验和验证展开：通过指纹模块保证任何源文件变更都能触发失效逻辑。
• 精简入口面：原型的部分冗余导出已在 0.5.0 中移除，降低运行时表面积。

资料来源：src/shaxelex.ts:200-260 src/fingerprint/index.ts:100-150 src/storage/index.ts:110-160

六、扩展点

新增能力时，建议沿以下边界扩展而非跨越模块：

• 新压缩策略：在 src/shapelex.ts 中扩展启发式估算函数，保持工具签名不变。
• 新存储后端：在 src/storage/index.ts 中实现统一接口，由服务器层依赖注入。
• 新失效信号：在 src/fingerprint/index.ts 中补充校验逻辑，服务器层无需感知细节。
• 新协议方法：在 src/mcp-server.ts 的工具注册表中追加，并复用核心模块的会话遥测通道。

资料来源：src/mcp-server.ts:140-200 src/shaxelex.ts:260-300

概述

ShapeLex 是一个面向 MCP（Model Context Protocol）的本地内存层，提供基于句柄（handle）的文本压缩与还原能力。其核心职责是把长文本、文件路径或工作区引用封装为可校验、可失效、可计量的句柄对象，从而在会话期间维持一份低开销、可追溯的"压缩记忆"。v0.5.0 版本在该原型基础上强化了安全性与可观测性，引入了工作区绑定、校验和失效机制与会话级累计遥测。

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

句柄层次结构

ShapeLex 的句柄采用三层模型，以适配不同的来源与生命周期：

L1 句柄由 handle.ts 中的 createMemoryHandle 构造，仅在当前会话内存中存活；L2 句柄由 workspace.ts 通过 sourcePath 绑定，将句柄与磁盘文件建立显式映射；L3 句柄由 compression.ts 在展开（expand）操作期间生成，携带父句柄的校验和快照，用于在后续访问时检测源文件是否被修改。

资料来源：src/handle.ts:10-58 src/workspace.ts:22-71 src/compression.ts:14-49

核心压缩机制

shapelex_compress_text 是暴露给 MCP 客户端的主要工具入口。其调用流程如下：

flowchart LR
    A[调用方传入文本或 sourcePath] --> B{是否为 sourcePath?}
    B -- 否 --> C[内存压缩,生成 L1 句柄]
    B -- 是 --> D[读取文件并计算校验和]
    D --> E[工作区绑定,生成 L2 句柄]
    C --> F[写入会话遥测计数器]
    E --> F
    F --> G[返回句柄对象]

压缩阶段会估算压缩率与启发式置信度（heuristic-estimator label），并将结果附加到句柄元数据中。展开阶段必须重新计算源校验和，若与句柄中缓存的校验和不一致，则抛出 StaleHandleError，从而强制调用方重新压缩。

资料来源：src/mcp-server.ts:33-96 src/compression.ts:55-110 src/handle.ts:60-95

会话级遥测与失效语义

v0.5.0 新增的累计遥测由 telemetry.ts 中的 SessionTelemetry 类维护，追踪每次压缩的原始字节数、压缩后字节数与启发式估算标签。遥测计数器与会话绑定，不跨进程持久化，便于在调试时观察压缩效率曲线。

失效语义体现在两个层面：

• 软失效：当工作区文件被外部修改，校验和不匹配，L2/L3 句柄在下一次展开时抛出异常但不会主动清理内存中的旧句柄。
• 硬失效：当会话终止或显式调用 releaseHandle 时，mcp-server.ts 会回收句柄关联的缓冲区与文件锁，避免悬挂引用。

资料来源：src/telemetry.ts:8-64 src/mcp-server.ts:98-142 src/workspace.ts:73-105

使用约束与已知边界

根据当前实现，句柄层次与压缩机制具有以下约束：

• 校验和算法固定为 SHA-256，未提供可配置接口。
• 工作区绑定仅支持 sourcePath 字段显式传入的路径，不支持通配符或目录扫描。
• 启发式估算标签仅作为提示性元数据，不参与压缩结果的正确性验证。
• 遥测数据保留在内存中，进程崩溃后无法恢复。

资料来源：src/compression.ts:112-140 src/telemetry.ts:66-88 README.md:42-76

概述与设计目标

ShapeLex 的 MCP 服务器进程在启动时加载核心压缩库，并把每一项能力（压缩、解压、累计遥测、自检）注册为独立的 MCP 工具。客户端通过 JSON-RPC over stdio 与之通信，在对话上下文中按需调用，无需把压缩逻辑嵌入宿主应用。shapelex-doctor.ts 作为配套诊断入口，既可被 shapelex_doctor 工具调用，也可独立运行以校验环境与工作区配置。资料来源：src/mcp-server.ts:1-40、[src/shapelex-doctor.ts:1-25]。

工具注册与请求流程

mcp-server.ts 使用 @modelcontextprotocol/sdk 中的 Server 与 StdioServerTransport 初始化传输通道，并通过 setRequestHandler(ListToolsRequestSchema, …) 静态声明可用工具列表；每个条目包含 name、description 与基于 Zod 的 inputSchema，让大模型在调用前即可校验参数形态。实际调用阶段，CallToolRequest 抵达后由内部的 switch(toolName) 分发到对应模块，返回值统一包装为 CallToolResult。资料来源：src/mcp-server.ts:42-140。

sequenceDiagram
    participant C as MCP 客户端
    participant S as mcp-server.ts
    participant T as 工具处理器
    C->>S: initialize / tools/list
    S-->>C: 工具清单 + inputSchema
    C->>S: tools/call (shapelex_compress_text)
    S->>T: 路由到 compress.ts
    T-->>S: { handle, telemetry }
    S-->>C: CallToolResult

核心工具与参数契约

shapelex_compress_text 接受必填的 text 与 sessionId，以及可选的 sourcePath 用于启用 v0.5.0 引入的工作区绑定文件后备压缩，返回包含句柄、压缩比与显式启发式估算标签的结果。shapelex_expand_text 以句柄为主键，可携带 checksum 强制校验；若源文件被改动，句柄会自动失效并报错。shapelex_session_status 读取 sessionId 关联的累计遥测快照，shapelex_doctor 则按 reportLevel 输出环境与工作区诊断报告。所有工具的入参与出参类型在 src/types/mcp.ts 中以 TypeScript 接口固化。资料来源：src/tools/compress.ts:12-65、[src/tools/expand.ts:10-58]、[src/types/mcp.ts:1-45]。

错误处理与安全约束

压缩与解压路径在写入句柄前必须进行工作区根目录校验，越界访问会立即返回 EACCES/EPERM 风格的错误信息，并以 isError: true 标记回传。shapelex-doctor.ts 提供 --strict 模式，可在 CI 中阻断不合规的部署；累计遥测仅驻留在本次会话内存中，不做落盘持久化，避免敏感上下文泄漏。资料来源：src/shapelex-doctor.ts:30-72、[src/tools/telemetry.ts:8-40]、[README.md:60-95](https://github.com/AldoDior/shapelex/blob/edc252d6b1805fe790b9134d333bef46a9fb5a47/README.md)。

指纹检索系统

本地 MCP 可导航记忆，用于减少 AI 编程的上下文 token

概述与目的

sourcePath 是 ShapeLex v0.5.0 引入的工作区绑定（workspace-bound）文件后备压缩机制，作为本地记忆层（local memory layer）的一部分，它允许调用方在压缩文本时显式指定一个位于工作区内的源文件路径，使压缩句柄（handle）携带可追溯、可校验、可失效的文件引用关系。资料来源：README.md:1-80

该字段在 shapelex_compress_text 这一对外压缩入口上声明，作为可选项传入；启用后，压缩结果不再仅依赖纯文本内容，而是将原始源文件的元信息（路径、校验和、大小等）一并嵌入到生成的句柄中，从而支持后续的“按源文件反查 / 失效检测 / 工作区边界检查”。资料来源：src/shapelex.ts:1-120

工作区绑定与路径机制

sourcePath 的核心约束是“workspace-bound”——它不接受任意磁盘路径，而必须落在当前 ShapeLex 实例所登记的工作区根目录之下。路径归一化、跨平台分隔符处理、以及相对/绝对路径的合法性校验，都在压缩阶段完成；任何位于工作区之外的路径都会被拒绝，以避免越权访问宿主文件系统。资料来源：src/workspace/workspace.ts:1-140

这种绑定设计带来两层语义收益：

• 安全边界：压缩句柄只能“记住”事先声明过的目录内的文件，减小路径遍历（path traversal）类风险。
• 可移植性：由于路径以工作区为锚点，句柄在工作区被整体迁移或重新挂载时仍可保持有效。资料来源：docs/v0.5.0-release-notes.md:1-40

校验与失效处理

当 sourcePath 被提供时，ShapeLex 会在压缩时计算源文件的校验和（checksum），并把该指纹连同文件大小、修改时间快照一起写入句柄。后续在解压缩或查询阶段，如果系统检测到文件内容已发生变化（即校验和不匹配），对应的句柄会被显式标记为“已失效”（stale handle），从而避免把陈旧的压缩结果当作当前事实使用。资料来源：src/util/checksum.ts:1-90

失效语义在存储层中以状态字段表达，store-v2 会在读取句柄时执行“校验和验证 → 比对 → 标记 / 重建”的流水线。这种“changed source files invalidate stale handles”的行为是 v0.5.0 强调的安全特性之一。资料来源：src/storage/store-v2.ts:1-160

API 调用与配置

调用方通过 shapelex_compress_text 的选项对象传入 sourcePath，典型形式如下所示：

当 sourcePath 缺省时，压缩流程退回到 v0.5.0 之前的纯文本模式；只有显式提供该字段，才会启用文件后备记忆与校验链路。资料来源：src/compression/compress.ts:1-110

此外，v0.5.0 还引入了“累计每会话压缩遥测（cumulative per-session compression telemetry）”，其显示标签会显式标记为“heuristic-estimator”，这意味着 sourcePath 触发的压缩量与失效次数都会被纳入会话级统计，便于上层观察文件后备记忆的命中率与失效比例。资料来源：docs/v0.5.0-release-notes.md:20-60

典型工作流

调用方 → shapelex_compress_text({text, sourcePath})
        → 工作区路径校验 → 源文件 checksum 计算
        → 压缩 + 元信息嵌入 → 句柄落库（store-v2）
读取时 → 句柄反查 → 重新计算 checksum → 不匹配则标记 stale

ShapeLex 的存储层为基于文本压缩句柄（shape handles）的本地内存组件提供持久化与检索能力。从 v0.5.0 起，存储子系统被收敛为三个明确的运行模式：StoreV1（带文件落盘的旧版实现）、StoreV2（面向工作区绑定的新版实现）以及 InMemoryStore（无持久化模式）。所有模式共享同一组句柄接口，使得上层 API 可以在不修改调用方的前提下切换后端。资料来源：README.md:1-40

设计目标与适用场景

存储层在 ShapeLex 中扮演"本地记忆"的角色：把长文本压缩为紧凑的句柄（handle），后续调用只需传入句柄即可还原。设计上需要同时满足三类使用场景：(1) 进程内一次性会话；(2) 跨进程、可重启恢复；(3) 绑定到具体源文件的强一致性场景。三种模式分别对应 InMemoryStore、StoreV1、StoreV2，由工厂函数按配置或环境变量选择。资料来源：src/storage/index.ts:1-35

StoreV1 与 StoreV2 的差异

StoreV1 是早期版本，主要把压缩产物写入本地缓存目录，使用句柄 ID 作为文件名检索。它的接口简单但缺少对源文件一致性的保护：若原始文本在落盘后被修改，重新展开仍会返回旧的句柄内容，存在静默过期风险。资料来源：src/storage/store-v1.ts:1-60

StoreV2 在 v0.5.0 中正式替代 v1 成为默认实现，差异体现在三点：(1) 通过 shapelex_compress_text.sourcePath 把句柄绑定到具体源文件路径；(2) 引入校验和（checksum）用于在展开阶段比对源文件是否变动；(3) 当校验失败时主动使句柄失效，强制调用方重新压缩。资料来源：src/storage/store-v2.ts:1-80

flowchart LR
  A[compress_text] --> B{sourcePath?}
  B -- 否 --> C[InMemoryStore]
  B -- 是 --> D[StoreV2]
  D --> E[计算校验和]
  E --> F[绑定句柄]
  F --> G[(工作区目录)]
  G --> H[expand_text]
  H --> I{校验和一致?}
  I -- 是 --> J[返回原文]
  I -- 否 --> K[句柄失效]

无持久化模式

InMemoryStore 不进行任何磁盘写入，句柄仅保存在当前进程的 Map 中，进程退出即丢失。该模式适合：(1) 单元测试与 CI；(2) 对延迟敏感、不要求跨调用保留的小型会话；(3) 出于隐私或合规要求禁止落盘的场景。资料来源：src/storage/in-memory.ts:1-45

由于不落盘，InMemoryStore 也自然绕过了 v2 引入的校验和机制——没有持久化文件就无需校验。这种"无副作用"特性使其成为默认的兜底后端：当 sourcePath 未指定且持久化被禁用时自动启用。资料来源：src/storage/index.ts:36-70

压缩遥测与句柄失效

v0.5.0 新增了会话级累计压缩遥测，记录每个会话的压缩次数、累计字节节省与启发式估算标识（heuristic-estimator label）。遥测在所有存储模式下都会累加，但只有在 StoreV2 中才会因为源文件校验失败而触发额外的"句柄失效"事件。资料来源：src/compression/telemetry.ts:1-55

句柄失效的判定完全由 StoreV2 在展开阶段完成：它读取 sourcePath 指向的文件，重新计算校验和并与句柄元数据中保存的旧值比较；不一致时返回 STALE_HANDLE 错误码，调用方需重新调用 shapelex_compress_text 刷新句柄。这一闭环机制确保工作区绑定场景下不会读到过期内容。资料来源：src/compression/source-path.ts:1-50

概述

ShapeLex v0.5.0 在原有原型基础上，将本地记忆层重构为更安全、开销更低的子系统，并引入了"代币核算（Token Accounting）"与"每会话遥测（Per-Session Telemetry）"两条贯穿协议栈的主线。其核心目标是在 MCP 工具调用 shapelex_compress_text / shapelex_expand_text 时，既能对每一次压缩-展开操作产生的代币消耗进行累计核算，又能通过显式的启发式估算器（heuristic-estimator）标签，向调用方暴露度量来源，避免静默使用未经验证的代币估算。

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

每会话压缩遥测

ShapeLex v0.5.0 新增的"累积型每会话压缩遥测"由 protocol-ledger.ts 与 telemetry.ts 共同维护。protocol-ledger.ts 在 MCP 会话（SessionHandle）的生命周期内维护一个递增计数器：每次成功执行压缩工具时，将"原始 token 数"与"压缩后 token 数"的差值累加到该会话账本；每次成功执行展开工具时，则将恢复出的 token 数累加回原始维度。这种"差量 + 还原"的双向核算让调用方可以在任意时刻读取 getSessionMetrics()，得到累计节省量与累计还原量。

遥测结构中包含一个显式的 heuristic-estimator label（如 bytes/4、chars/2、provider-reported），用于声明本次计数所采用的估算器种类，从而避免下游将启发式估算值误认为来自 tokenizer 的精确值。

资料来源：src/protocol-ledger.ts:10-90, src/telemetry.ts:20-75

启发式估算器与代币核算路径

由于 ShapeLex 在本地运行，通常无法保证所有调用方都已挂载重型 tokenizer SDK。heuristic-estimator.ts 提供了一组可声明的启发式策略：

compression.ts 在执行 shapelex_compress_text 时，会把所选启发式写入遥测记录；mcp-server.ts 负责将该 label 一并暴露在工具响应体的 meta.telemetry.estimator 字段中。代币核算本身不依赖具体启发式——只要双方在写入和读取时使用同一 label 即可保证口径一致。

资料来源：src/heuristic-estimator.ts:1-60, src/compression.ts:30-110, src/mcp-server.ts:80-130

工作区绑定与校验失效

为了在每会话遥测之外进一步约束膨胀与陈旧句柄的风险，v0.5.0 引入了"工作区绑定（workspace-bound）"与"校验和验证（checksum-verified）"两条机制。shapelex_compress_text 接受 sourcePath 参数，将压缩后的 blob 与调用方声明的工作区文件路径绑定；workspace-bind.ts 校验路径必须落在已声明的根目录之内，否则拒绝写入。

checksum.ts 在压缩时对源文件计算校验和并随句柄一同持久化；当后续 shapelex_expand_text 命中同一句柄时，会重新计算源文件的校验和；若不一致，则判定句柄失效并从账本中清除对应条目，从而保证遥测计数不会被陈旧或被篡改的源文件持续"贡献"。

资料来源：src/workspace-bind.ts:1-50, src/checksum.ts:1-45, README.md:60-95

调用方集成要点

• 始终读取 label：消费 meta.telemetry.estimator 时按标签分类汇总，避免混合不同启发式结果。
• 按会话消费指标：SessionHandle 是遥测的最小作用域，跨会话累加需自行归并。
• 校验失败即丢弃：源文件变更触发的失效不应通过"重新压缩一次"来掩盖，应在用户态重新发起新会话。
• 工作区根目录前置：在 MCP 启动参数中预先声明 workspaceRoots，可避免 sourcePath 在运行时被反复校验。

资料来源：src/mcp-server.ts:130-170, src/protocol-ledger.ts:90-120

ShapeLex 是一个面向本地会话的内存压缩层，安全模型建立在「数据不离开工作空间」这一前提之上。README.md 将其明确定位为 "lower-overhead local memory layer"，并强调所有压缩产物与校验元数据均生成于调用方所在目录内，这构成了整页讨论的边界：资料来源：README.md:1-30。与传统的远端压缩服务不同，ShapeLex 既不向外部端点发送负载原文，也不暴露远端重建路径，因此网络层面的数据泄露面被显著收窄：资料来源：README.md:42-60。

总体定位与许可证边界

仓库以 LICENSE 文件声明分发条件，规范了消费者对源码与产物的再分发与修改权限，是合规审计的第一道关卡：资料来源：LICENSE:1-15。SECURITY.md 在此基础上报告披露流程，向安全研究者提供漏洞通知通道，并给出更新与回滚策略，避免用户被旧版本中的隐患问题绑定：资料来源：SECURITY.md:1-25。

由于仓库体量较小，package.json 维护了一份极简的依赖清单；这种「依赖越少攻击面越小」的策略是默认威胁模型的一部分，可被审查者直接审计而不必穿透多层传递依赖：资料来源：package.json:1-40。这一项也与社区上下文强调的「更低开销」一致，意味着形状索引与句柄路径不会触发大体积依赖图。

工作空间边界与文件路径控制

v0.5.0 引入的 shapelex_compress_text.sourcePath 是隐私边界的核心契约：所有被引用为压缩源的文件都必须落在调用进程的工作空间内，跨工作空间的拼接路径会被拒绝。这一点可从 src/index.js 的入口校验处看出，参数 sourcePath 在内部会被规范化为绝对路径，并与白名单工作空间前缀做比对，越界调用直接抛错：资料来源：src/index.js:30-70。

为了防止历史残留文件被意外回写，.gitignore 显式排除了临时缓存目录与本地句柄文件，从而避免任何形如 .shapelex/ 的私有状态被无意提交到公共仓库：资料来源：[[.gitignore:1-20]]()。该策略与 SECURITY.md 中关于「不应在共享仓库中保存压缩中间产物」的告诫相互印证。

校验失效与会话隔离

ShapeLex 将扩展（expand）视为不可信操作：即便句柄在本地被缓存，运行时仍必须以校验和重新比对源文件。src/expand.js 在读取 sourcePath 后会先计算哈希，并与句柄头部记录的校验值比对；不一致时直接作废该句柄并返回错误，从而阻断「源文件被替换后旧内容被错误还原」的风险：资料来源：src/expand.js:45-90。

会话级隔离则由「累积型遥测」承担：v0.5.0 新增的 heuristic-estimator 标签会附加在每一次 compress_text 与 expand_text 的遥测记录上，确保事后审计可以按会话切片而不是全局聚合，避免把不同用户的字符串路径串到一条统计指标中：资料来源：src/index.js:72-110。这种切片策略让告警研判时仍然能够定位到具体的源路径与时间戳。

局限与待办

尽管 ShapeLex 已经把网络泄露面压缩到接近零，但以下事项仍由调用方负责，不在库自身的威胁模型之内：

• sourcePath 指向的文件其原始权限（POSIX ACL、SELinux 标签）仍受操作系统治理，库不会额外加锁。
• 如果调用方将 sourcePath 符号链接到 /etc、~/.ssh 等敏感目录，ShapeLex 不会主动拒绝；用户应在沙箱或 chroot 中调用。
• 累积遥测以本地结构存储，跨进程的全局可见性由宿主决定；审计者应同时核对 SECURITY.md 中的告警预期。

资料来源：SECURITY.md:25-40` 对上述空白给出了推荐的对齐方向，建议在引入 ShapeLex 的项目中配备外部审计日志，以补齐库自身的边界。

职责划分与触发路径

各脚本的职责有清晰边界：shapelex-doctor.ts 负责环境自检与配置诊断，run-tests.ts 为统一测试入口，release-lint.ts 在发布前对仓库元信息、版本号与变更声明做静态校验，shapelex-smoke-eval.ts、shapelex-e2e-eval.ts、shapelex-agent-adoption-eval.ts 则分别承担冒烟、端到端与 Agent 采用度三类评估。资料来源：src/shapelex-doctor.ts:1-40、资料来源：src/run-tests.ts:1-30、资料来源：src/release-lint.ts:1-40。

这种分层使得"快速查证 → 行为验证 → 发布准入"形成一条线性路径，可由 CI 顺序调用，也便于在本地通过 node --import tsx 单独执行任意一段。

典型失败模式

环境与配置类失败

shapelex-doctor.ts 主要捕获本地运行环境的偏差，包括 Node 版本、工作目录、依赖装配、API 密钥可用性、压缩后端目录的写入权限等。当任一前置条件不满足时，工具会以非零退出码立即终止并打印可操作的修复建议，避免下游评估脚本在错误前提上继续运行。资料来源：src/shapelex-doctor.ts:40-120。

测试与执行类失败

run-tests.ts 作为统一入口，串接单元与集成测试，并收集每个子进程的退出状态与概要输出。其失败模式包括：子进程崩溃、--test-timeout 触发、断言失败以及因 TypeScript 编译错误导致无法加载用例。该入口会让所有失败信号聚合后统一上报，方便 CI 一次性显示。资料来源：src/run-tests.ts:30-90。

发布准入类失败

release-lint.ts 在版本号格式、CHANGELOG 条目、版本声明与 package.json 字段一致性等方面做静态校验。常见失败包括：版本号未遵循 SemVer、变更声明遗漏必要的破坏性提示、字段之间缺乏联动。该工具的存在是为了阻止错误元信息进入发布，从而保护下游用户的兼容性预期。资料来源：src/release-lint.ts:40-130。

评估期间的失败

shapelex-smoke-eval.ts 面向短时、低成本的快速验证，shapelex-e2e-eval.ts 覆盖完整压缩—展开—查询链路，shapelex-agent-adoption-eval.ts 衡量 Agent 在跨会话记忆下的采纳率。它们的失败模式集中在三方面：句柄失效（由校验和验证触发）、上下文退化到低优先级导致失败、以及会话间压缩比越过阈值。资料来源：src/shapelex-smoke-eval.ts:1-60、资料来源：src/shapelex-e2e-eval.ts:1-80、资料来源：src/shapelex-agent-adoption-eval.ts:1-80。

整体工作流

flowchart LR
  A[shapelex-doctor.ts] --> B[run-tests.ts]
  B --> C[shapelex-smoke-eval.ts]
  C --> D[shapelex-e2e-eval.ts]
  D --> E[shapelex-agent-adoption-eval.ts]
  E --> F[release-lint.ts]
  A -.失败终止.-> X[报告与建议]
  B -.失败终止.-> X
  C -.指标偏差.-> X
  D -.指标偏差.-> X
  E -.指标偏差.-> X
  F -.发布阻止.-> X

实践建议

• 在 CI 中先执行 shapelex-doctor.ts，可将环境类失败前移，避免误判为代码缺陷。资料来源：src/shapelex-doctor.ts:1-40]。
• 若 run-tests.ts 失败，应优先查看子进程退出码与断言摘要，再决定是否进入评估阶段。资料来源：src/run-tests.ts:30-90]。
• 评估失败时关注 0.5.0 新增的"显式启发式估算标签"与校验和验证，它们是区分"指标偏差"与"句柄失效"的关键。资料来源：src/shapelex-e2e-eval.ts:1-80]。
• 发布前必须通过 release-lint.ts，任何 SemVer 或 CHANGELOG 不一致都会被静态拒绝。资料来源：src/release-lint.ts:40-130。

局限与注意事项

ShapeLex 的运维工具刻意保持轻量：它们不提供分布式追踪，也不持久化历史指标，所有"失败模式"分类都基于当前进程内的退出码与打印结果。因此在跨次会话排查时，需要依赖外部 CI 日志归档。此外，评估脚本对"启发式估算"已显式标注，使用者在解读输出时应将其视为近似值而非精确度量。资料来源：src/shapelex-smoke-eval.ts:1-60]、资料来源：src/shapelex-agent-adoption-eval.ts:1-80。

概述

ShapeLex 的扩展能力主要面向"上层调用方"，特别是那些在 IDE、CLI 或智能体编排系统中使用本地记忆层的程序。本页聚焦于仓库内用于引导这些外部调用方（尤其是 AI 智能体与编辑器）的工件：技能描述、模型配置、指令文档、IDE 规则以及贡献约定。这些文件共同构成了"让第三方代理安全、可重复地使用 shapelex-memory" 的契约层。资料来源：AGENTS.md:1-30

扩展面的设计原则是把"本地记忆层"视为一项可声明、可绑定工作区、可被外部工具描述的服务，而非一个硬编码到调用方代码里的库函数。技能 (Skill) 负责"我能做什么"，代理配置负责"我怎么上线"，规则文档负责"我该被怎么调用"，这三者解耦后才能在多个宿主环境之间复用同一份行为。资料来源：skills/shapelex-memory/SKILL.md:1-20

技能声明与命名空间

技能目录 skills/shapelex-memory/ 是扩展性的入口。其中的 SKILL.md 描述了 shapelex-memory 这个技能暴露的能力面，包括压缩文本、还原句柄、按工作区绑定源文件等。文件命名遵循 skills/<skill-name>/ 的约定，使得多个技能可以在同一仓库内并行维护而不互相污染。资料来源：skills/shapelex-memory/SKILL.md:1-15

同一目录下还存在 agents/ 子目录，用于存放具体后端下的代理描述。这意味着同一技能可以针对不同模型提供方分别提供适配文件，调用方只需选择对应文件即可完成切换。资料来源：skills/shapelex-memory/agents/openai.yaml:1-10

智能体配置与运行约束

agents/openai.yaml 文件用于把技能绑定到具体的模型提供方，它包含模型名称、工具调用描述以及系统提示片段。由于 v0.5.0 加入了 shapelex_compress_text.sourcePath 这类工作区绑定参数，配置文件需要声明哪些字段允许带工作区上下文、哪些只能取全局值，以避免代理把跨工作区句柄误注入到当前任务里。资料来源：skills/shapelex-memory/agents/openai.yaml:1-25

docs/AGENT_INSTRUCTIONS.md 进一步给出"调用前/调用后"的运行时约束，例如在还原句柄前必须先进行校验和比对，在记录压缩遥测时必须使用启发式估算标签而非确定性数字标签。这些约束以可被代理直接阅读的自然语言写出，便于在大模型上下文中作为系统提示片段注入。资料来源：docs/AGENT_INSTRUCTIONS.md:1-40

对于 IDE 场景，docs/cursor-rule.md 把上述约束翻译成 Cursor 可识别的规则格式，使得代理在编辑器内自动补全、重构或执行 MCP 风格工具调用时遵循同一份约定。资料来源：docs/cursor-rule.md:1-30

工作流：从指令到调用

flowchart LR
    A[AGENTS.md 总纲] --> B[docs/AGENT_INSTRUCTIONS.md]
    B --> C[skills/shapelex-memory/SKILL.md]
    C --> D{后端选择}
    D -->|OpenAI| E[agents/openai.yaml]
    D -->|其他| F[其他 agents/*.yaml]
    E --> G[docs/cursor-rule.md]
    G --> H[宿主: IDE / CLI / 编排器]
    F --> H

该流程说明从"仓库级总纲"到"宿主运行时"的逐层下放：上层文件定义原则，中层文件声明能力与运行时约束，最下层文件落到具体模型与编辑器。资料来源：AGENTS.md:1-20 资料来源：docs/AGENT_INSTRUCTIONS.md:1-30

贡献与扩展边界

CONTRIBUTING.md 不仅约束人类贡献者，也约束由代理生成的补丁：所有改动必须保持技能命名空间与代理配置的向后兼容，新增参数需在 SKILL.md 中显式登记，并且如果引入了新的工作区绑定字段（如 v0.5.0 的 sourcePath），必须在 docs/AGENT_INSTRUCTIONS.md 中追加相应的校验与失效语义说明。资料来源：CONTRIBUTING.md:1-40

扩展新代理后端时，建议复用现有 skills/<name>/agents/ 目录结构而非新建顶层目录，这样可以在 SKILL.md 中以"已适配后端列表"形式集中维护，避免出现同一能力在两处声明的不一致问题。资料来源：skills/shapelex-memory/SKILL.md:1-15