LogicStamp/logicstamp-context

LogicStamp Context 是一个 CLI 工具，它将 TypeScript 代码库编译成确定性的、可对比的架构合约和依赖关系图——这是 AI 编码工作流的紧凑、结构化事实来源。 监视模式。严格的、可审计的差异。实时破坏性变更检测。基于 AST 的合约提取。 **包含一个 MCP server。适用于 Claude、Cursor、Copilot Chat 以及任何兼容 MCP 的 agent。**

📑 目录

- [问题所在](#the-problem) - [快速开始](#quick-start) - [为什么选择结构化上下文？](#why-structured-context) - [功能特性](#-features) - [监视模式](#watch-mode) - [工作原理](#how-it-works) - [MCP Server](#mcp-server) - [输出示例](#example-output) - [安装](#installation) - [安全性](#security) - [使用方法](#usage) - [框架支持](#framework-support) - [文档](#documentation) - [已知限制](#known-limitations) - [环境要求](#requirements) - [需要帮助？](#need-help) - [许可证](#license)

## 问题所在 AI 编码助手会读取您的源代码——但它们不理解其结构。 它们会产生 props 幻觉，遗漏依赖关系，并且无法检测破坏性变更何时影响消费者。 示例：您的 `Button` 接受 `variant` 和 `disabled`，但 AI 建议使用 `isLoading`，因为它在别处见过该模式。如果没有结构化合约，就没有可靠的事实来源。 **LogicStamp Context** 将 TypeScript 编译成确定性的架构合约和依赖关系图——这是您的系统的机器可读表示，AI 工具可以使用它来代替解析原始实现代码。 这些合约： - 与您的代码保持同步（监视模式自动重新生成） - 暴露接口（props、hooks、API）而没有实现噪音 - 是确定性的、可对比的且可审计的 - 能够早期检测架构漂移和破坏性变更  *示例工作流：`stamp context --strict-watch` 生成上下文包，MCP 驱动的助手使用它来解释组件架构（此处显示为 ThemeContext）。* **相同的代码 ⇒ 相同的上下文输出。** 合约是可对比的，因此您可以检测漂移和破坏性变更。 ``` TypeScript Code → Compilation → Deterministic Contracts → AI Assistant (.ts/.tsx) (ts-morph) (context.json bundles) (Claude, Cursor) ``` ## 快速开始 **在 30 秒内试用（无需安装）：** ``` npx logicstamp-context context ``` 扫描您的代码库并写入 `context.json` 文件以及供 AI 工具使用的 `context_main.json`。 **您将获得：** - 📁 `context.json` 文件 - 每个包含组件的文件夹一个，保留您的目录结构 - 📋 `context_main.json` - 包含项目概览和文件夹元数据的索引文件 **对于完整的设置（推荐）：** ``` npm install -g logicstamp-context stamp init # sets up .gitignore, scans for secrets stamp context ``` 📋 **有关详细的设置说明，请参阅 [入门指南](https://logicstamp.dev/docs/getting-started)。** ## 为什么选择结构化上下文？ | 没有 LogicStamp Context | 有 LogicStamp Context | |-------------------|-----------------| | AI 解析 200 行实现代码以推断组件的接口 | AI 读取 20 行的接口合约 | | Props/hooks 是推断出来的（通常是错误的） | Props/hooks 是明确且经过验证的 | | 无法知道上下文是否过时 | 监视模式实时捕获变更 | | 不同的提示词 = 不同的理解 | 确定性：相同的代码 = 相同的合约 | | 手动上下文收集：“这是我的 Button 组件...” | 结构化合约：AI 自动理解架构 | **关键见解：** AI 助手不需要您的实现——它们需要您的*接口*。LogicStamp Context 提取重要内容并丢弃噪音。 ### “结构化”意味着什么 与其将原始源代码发送给 AI： ``` // Raw: AI must parse and infer export const Button = ({ variant = 'primary', disabled, onClick, children }) => { const [isHovered, setIsHovered] = useState(false); // ... 150 more lines of implementation } ``` LogicStamp Context 生成： ``` { "kind": "react:component", "interface": { "props": { "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }, "disabled": { "type": "boolean" }, "onClick": { "type": "function", "signature": "() => void" } } }, "composition": { "hooks": ["useState"], "components": ["./Icon"] } } ``` 预解析的。分类的。稳定的。AI 读取的是合约，而不是实现。 ## ⚡ 功能特性 **核心：** - **确定性合约** - 相同的输入 = 相同的输出，可在版本控制中审计 - **监视模式** - 文件更改时通过增量重建自动重新生成 - **破坏性变更检测** - 严格监视模式实时捕获已移除的 props、事件、函数 - **MCP 就绪** - AI agent 通过标准化 MCP 接口消费上下文 **分析：** - React/Next.js/Vue 组件提取（props、hooks、state、deps） - 后端 API 提取（Express.js、NestJS 路由和控制器） - 依赖关系图（处理循环依赖） - 样式元数据提取（Tailwind、SCSS、MUI、shadcn） - Next.js App Router 检测（客户端/服务端、layouts、pages） **开发者体验：** - 与您的项目结构匹配的按文件夹包 - 准确的 token 估算（GPT/Claude） - 安全至上：自动秘密检测和清理 - 零配置 - 合理的默认值，开箱即用 ## 监视模式

*严格监视模式实战：检测违规并在解决后清除。* 对于开发，运行监视模式以在您编码时保持上下文新鲜： ``` stamp context --watch # regenerate on changes stamp context --strict-watch # also detect breaking changes (implies --watch) ``` 严格监视捕获影响消费者的破坏性变更： | 违规 | 示例 | |-----------|---------| | `breaking_change_prop_removed` | 从 Button 移除了 `disabled` prop | | `breaking_change_event_removed` | 移除了 `onSubmit` 回调 | | `breaking_change_function_removed` | 删除了导出的 `formatDate()` | | `contract_removed` | 删除了整个组件 | **错误与警告：** 违规按严重程度分类： **❌ 错误** 表示将影响消费者的破坏性变更（移除了 props、事件、函数或整个合约）。 **⚠️ 警告** 表示不太严重的变更（类型签名变更、移除了内部 state）。违规被实时跟踪并在解决后自动清除。 **会话状态跟踪：** 严格监视模式显示一个会话状态块，显示累积统计信息： - **检测到的错误/警告**：会话期间检测到的总违规数 - **已解决**：所有违规被完全解决的次数 - **活动**：当前活动违规的数量 状态块仅在违规更改时出现（而不是在每次文件更改时），保持终端输出整洁。  *显示违规和会话状态的示例终端输出。* ### 一次性比较 将重新生成的上下文与现有文件进行比较： ``` stamp context compare # detect changes stamp context compare --approve # update (like jest -u) ``` 用于在提交前审查更改或验证上下文是否最新。 ## 工作原理 编译流程： 1. **扫描** - 发现所有 `.ts` 和 `.tsx` 源文件 2. **解析** - 通过 `ts-morph` 使用 TypeScript 编译器 API 构建 AST（抽象语法树） 3. **提取** - 编译包含 props、hooks、state、签名的合约 4. **图谱** - 解析依赖关系 5. **发出** - 每个文件夹输出 `context.json` 包 6. **索引** - 生成包含元数据和统计信息的 `context_main.json` **为什么基于 AST 的编译很重要：** LogicStamp 利用完整的 TypeScript 编译器（通过 ts-morph）进行确定性的、类型感知的合约提取。Prop 类型、hooks 和组合模式在结构上被解析——而不是从文本或检索中推断。 一个命令。无需构建步骤。

📋 LogicStamp Context 是什么（不是什么）

**LogicStamp Context 是：** ✅ **上下文编译器** - 使用 TypeScript 编译器 API（通过 ts-morph）将源代码编译成确定性的架构合约。 ✅ **确定性的** - 相同的输入总是产生相同的输出。合约是可审计和可对比的。 ✅ **本地执行** - 完全在您的机器上运行（无云服务，无网络调用）。 ✅ **框架感知** - 理解 React、Next.js、Vue、Express 和 NestJS 模式并提取相关元数据。 ✅ **非强制性** - 描述存在的内容，而不强制执行模式或架构决策。 **LogicStamp Context 不是：** ❌ **代码生成器** - 它从不写入或修改您的源代码。 ❌ **文档生成器** - 它生成结构化合约，而不是文档。 ❌ **构建或运行时工具** - 它从静态源代码编译合约；它不执行或打包您的应用程序。 ❌ **Linter、格式化程序或测试框架** - 它不检查代码质量或运行测试。 ❌ **AI 行为控制器** - 它提供结构化上下文；它不改变 AI 响应。 ❌ **阅读代码的替代品** - 它加速理解而不取代工程判断。

## MCP 服务器 对于支持 MCP 的 AI 助手（Claude Desktop、Cursor 等）： ``` npm install -g logicstamp-mcp ``` 然后配置您的 AI 助手以使用 LogicStamp MCP Server。 📋 **有关设置说明，请参阅 [MCP 入门指南](https://logicstamp.dev/docs/mcp/getting-started)**。 ## 输出示例 LogicStamp Context 生成按文件夹组织的结构化 JSON 包： ``` { "type": "LogicStampBundle", "entryId": "src/components/Button.tsx", "graph": { "nodes": [ { "entryId": "src/components/Button.tsx", "contract": { "kind": "react:component", "interface": { "props": { "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }, "onClick": { "type": "function", "signature": "() => void" } } }, "composition": { "hooks": ["useState"], "components": ["./Icon"] } } } ], "edges": [["src/components/Button.tsx", "./Icon"]] } } ``` 📋 **有关完整的格式文档，请参阅 [docs/schema.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/schema.md)**。 ## 安装 ``` npm install -g logicstamp-context ``` 安装后，`stamp` 命令将全局可用。 ## 安全性 **自动秘密保护** LogicStamp Context 保护生成的上下文中的敏感数据： - **默认安全扫描** - `stamp init` 在编译上下文之前扫描源文件（`.ts`、`.tsx`、`.js`、`.jsx`）和 `.json` 文件中的硬编码秘密 - **自动清理** - 检测到的秘密在输出中被替换为 `"PRIVATE_DATA"` - **手动排除** - 使用 `stamp ignore ` 通过 `.stampignore` 排除文件 - **默认安全** - 仅包含元数据。凭据仅出现在 `--include-code full` 模式下 🔒 **有关完整的安全文档，请参阅 [SECURITY.md](https://github.com/LogicStamp/logicstamp-context/blob/main/SECURITY.md)**。 ## 使用方法

💻 CLI 使用参考

``` stamp --version # Show version stamp --help # Show help stamp init [path] # Initialize project (security scan by default) stamp ignore # Add to .stampignore stamp context [path] # Generate context bundles stamp context style [path] # Generate with style metadata (lean mode by default) stamp context style --style-mode full # Generate with full style details (verbose) stamp context --watch # Watch mode stamp context --strict-watch # Watch with breaking change detection (--watch optional) stamp context compare # Detect changes vs existing context stamp context validate [file] # Validate context files stamp context clean [path] # Remove generated files ``` ### 常用选项 | Option | 描述 | |--------|-------------| | `--depth ` | 依赖遍历深度（默认值：2） | | `--include-code ` | 代码包含：`none\|header\|full`（默认值：header） | | `--include-style` | 提取样式元数据（Tailwind、SCSS、动画） | | `--format ` | 输出格式：`json\|pretty\|ndjson\|toon`（默认值：json） | | `--max-nodes ` | 每个包的最大节点数（默认值：100） | | `--profile

` | 预设：`llm-chat`, `llm-safe`, `ci-strict`, `watch-fast` | | `--compare-modes` | 显示所有模式的 token 成本比较 | | `--stats` | 输出带有 token 估算的 JSON 统计信息 | | `--out ` | 输出目录 | | `--quiet` | 抑制详细输出 | | `--strict-missing` | 如果发现任何缺失的依赖项，则以错误退出（CI 友好） | | `--debug` | 显示详细的哈希信息（监视模式） | | `--log-file` | 将变更日志写入 `.logicstamp/`（监视模式） |

📋 **有关完整参考，请参阅 [docs/cli/commands.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/commands.md)**。 ## 框架支持 | Framework | 支持级别 | 提取内容 | |-----------|--------------|------------------| | **React** | Full | Components, hooks, props, styles | | **Next.js** | Full | App Router roles, segment paths, metadata | | **Vue 3** | Partial | Composition API (TS/TSX only, not .vue SFC) | | **Express.js** | Full | Routes, middleware, API signatures | | **NestJS** | Full | Controllers, decorators, API signatures | | **UI Libraries** | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS, Chakra, Ant Design (component usage, props, composition; not raw CSS) | ## 文档 **完整文档位于 [logicstamp.dev/docs](https://logicstamp.dev/docs)** - [入门指南](https://logicstamp.dev/docs/getting-started) - [使用指南](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/usage.md) - [Monorepo 支持](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/monorepo.md) - [输出 Schema](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/schema.md) - [UIF 合约](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/uif_contracts.md) - [监视模式](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/watch.md) - [故障排除](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/usage.md#troubleshooting) ## 已知限制 LogicStamp Context 处于测试阶段。某些边缘情况未完全支持。 📋 **有关完整列表，请参阅 [docs/limitations.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/limitations.md)**。 ## 环境要求 - Node.js >= 20 - TypeScript 代码库（React、Next.js、Vue (TS/TSX)、Express 或 NestJS） ## 需要帮助？ - **Issues** - [github.com/LogicStamp/logicstamp-context/issues](https://github.com/LogicStamp/logicstamp-context/issues) - **Roadmap** - [logicstamp.dev/roadmap](https://logicstamp.dev/roadmap) ## 许可证 [MIT](LICENSE)

品牌与署名

LogicStamp Fox 吉祥物和相关品牌资产版权归 © 2025 Amit Levi 所有。未经许可，这些资产不得用于第三方品牌推广。

贡献

欢迎提交 Issues 和 PR！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 本项目遵循 [行为准则](CODE_OF_CONDUCT.md)。

**链接：** [网站](https://logicstamp.dev) · [GitHub](https://github.com/LogicStamp/logicstamp-context) · [MCP Server](https://github.com/LogicStamp/logicstamp-mcp) · [更新日志](https://github.com/LogicStamp/logicstamp-context/blob/main/CHANGELOG.md)

标签：AI编程, Claude, Copilot, Cursor, CVE检测, Express, LLM辅助开发, MCP Server, MITM代理, NestJS, React, Syscalls, TypeScript, Vue, 上下文编译器, 云安全监控, 代码分析, 代码变更检测, 依赖图, 凭证管理, 威胁情报, 安全插件, 开发者工具, 文件系统扫描, 文档结构分析, 架构契约, 自动化payload嵌入, 自动化攻击, 软件架构, 静态分析