ommukhlis-spec/lynkmesh-open

# LynkMesh LynkMesh 是一个实验性的开放核心项目，旨在为真实的软件系统构建确定性的代码理解层。 现代 AI 能够阅读源代码，但在将软件系统视为相互连接且不断演进的架构来理解方面仍然存在困难。LynkMesh 探索了一种图优先的方法：它不将代码库视为孤立的文件、数据块或 embeddings，而是将其建模为语义图，包含明确的关系、遍历边界、置信度信号以及架构感知检索。 其长期目标是为 AI 原生的软件工程系统提供可靠的语义基底。 ## 为什么需要 LynkMesh 大多数 AI 编程工具严重依赖于： - 大型上下文窗口 - 文件分块 - 向量搜索 - 启发式检索 - 重复的仓库扫描 这些方法很有用，但当系统需要以下功能时，它们通常会失效： - 确定性的依赖感知 - 架构级推理 - 影响分析 - 请求流理解 - 大型代码库导航 - 持久的项目记忆 - 为 AI 代理提供安全的上下文选择 LynkMesh 的存在是为了在原始源代码和 AI 推理之间探索一个缺失的基础设施层。 ``` Codebase ↓ Ingestion ↓ Intermediate Representation (IR) ↓ Semantic Graph ↓ Query / Reasoning Layer ↓ Context Compilation ↓ AI Agents ``` ## LynkMesh 是什么 LynkMesh 是： - 面向代码库的语义图引擎 - 确定性的代码推理基础 - 面向 AI 代理的本地优先上下文层 - 实验性的 MCP-ready 基础设施层 - 架构感知检索的基础 LynkMesh 不是： - 聊天机器人封装器 - 向量数据库 - 通用的代码摘要工具 - 托管的 SaaS 仪表板 - 生产就绪的自主编程代理 ## 开放核心模型 LynkMesh 正作为一个开放核心项目进行开发。 ### 社区版 公共仓库专注于本地优先的核心部分： - 确定性的图标识 - 图序列化基础 - 摄取 pipeline - 解析器编排 - IR 标准化 - 图构建 - 语义契约 - 符号/类型注册基础 - 基础分析和推理层 - 本地 MCP 集成基础 - 实验性的面向 PHP 的静态分析 社区版旨在帮助开发者和 AI 代理在本地检查、推理并从代码库中检索结构化上下文。 ### Pro / 私有运行时 高级运行时功能可能会作为私有或商业层单独开发，包括： - 增量 diff 运行时 - 持久化图缓存运行时 - 大型仓库优化 - 高级语义缓存 - 团队/工作区图记忆 - 托管 MCP server - 云端仓库连接器 - 多项目索引 - 高级框架感知分析 - 企业审计/安全控制 这种边界既保持了公共核心的实用性，又为可持续的商业开发保留了空间。 ## 当前状态 LynkMesh 目前处于早期 alpha 阶段。 该项目可用于研究、实验和内部开发，但公共 API 仍在不断演进中。 当前重点： - 确定性的图基础 - 图版本控制和序列化 - 语义契约 - 查询层稳定化 - 本地 MCP 暴露 - 面向 AI 的上下文检索 - PHP 优先的静态分析探索 预计会有破坏性变更。 ## 文档 LynkMesh 目前是用于 AI 辅助代码理解的确定性上下文协议的早期验证/研究预览版。它尚未达到生产就绪状态。 ### 第一次接触 LynkMesh？从这里开始 - [5 分钟体验 LynkMesh](docs/try_in_5_minutes.md) — 最短的公开安全入门路径。 - [演示脚本](docs/demo_script.md) — 走完整个演示故事并检查输出。 - [支持矩阵](docs/support_matrix.md) — 目前支持、实验性或不支持的内容。 - [公开 FAQ](docs/public_faq.md) — 解答早期用户和评论者的常见问题。 ### 参考 - [LynkMesh 协议](docs/lynkmesh_protocol.md) — 问题、确定性 pipeline 以及隐私模型。 - [快速入门](docs/quickstart.md) — 前置条件、验证/冒烟测试工作流程以及高级 MCP 用法。 - [案例研究模板](docs/case_study_template.md) — 用于分析示例的可重用、脱敏格式。 - [MeshContext MCP 发布说明 (v4.4.1)](docs/mcp_mesh_context_release_notes_v4.4.1.md) — 当前的 MCP 能力元数据和保证。 ### AI 代理工作流 - [代理审查工作流](docs/agent_review_workflow.md) — 目标用例：基于图上下文证据的 AI 辅助代码审查。 - [公开 alpha 标准](docs/public_alpha_criteria.md) — LynkMesh 从早期 alpha 过渡到公开 alpha / 开发者预览版之前所需的标准。 ### 发布状态 LynkMesh 处于早期验证/研究预览阶段，尚未生产就绪。 - [公开发布说明 (v0.1)](docs/public_release_notes_v0.1.md) — 发布状态、包含内容以及局限性。 - [GitHub 公共主页草稿](docs/github_public_profile.md) — 建议的对外描述和发布文案。 ## 公开证据包 LynkMesh 现在包含一个公开安全的“前后对比”证据包，用于审查确定性的图产物如何为 AI 辅助代码理解工作流提供基础。 - [evals/before_after/](evals/before_after/) 定义了可重复的评估基准、措辞规则、指标 schema 以及公开安全指南。 - [evals/before_after/runs/mini_auth_shop_php_001/](evals/before_after/runs/mini_auth_shop_php_001/) 是第一个提交的 fixture 级别的运行记录，包括确定性的 CLI 产物、前后对比记录、屏幕截图以及保守的比较总结。 - 该证据包是一个早期验证基准，并非基准测试证明。它不声称 LynkMesh 能让 AI 模型变得更聪明，也不应将其视为生产就绪的性能证据。 使用此证据包来检查 LynkMesh 向 AI 代理暴露了什么：确定性的、脱敏的图证据和上下文产物，而不包含原始的私有源代码。 ## 定位 LynkMesh 是面向 AI 编程代理的确定性 MeshContext 证据协议 — 不仅仅是一个仓库索引器。 阅读公开定位说明：[docs/positioning.md](docs/positioning.md)。 ## 当前语言支持 应将 LynkMesh 视为分层语言支持： ``` Core graph engine = language-agnostic Ingestion / parser = language-specific Framework understanding = framework-specific ``` 当前实际支持情况： | 语言 | 状态 | 备注 | |---|---|---| | PHP | 部分 / 早期 alpha | 文件扫描、面向命名空间/类的解析、依赖图基础 | | Laravel 风格的 PHP | 实验性 | 正在探索某些架构模式，但尚未完全对框架魔法进行建模 | | 其他语言 | 官方不支持 | 稍后可能支持基本的文件清单，但不保证语义图的准确性 | 不应将不支持的语言视为完全可分析的。LynkMesh 应报告不支持或降级行为，而不是假装理解它无法可靠解析的代码。 ## MCP 集成 LynkMesh 旨在通过 Model Context Protocol (MCP) 向 AI 代理开放。 预期的 MCP 模型是本地优先的： ``` MCP Client / AI Client ↓ Local MCP Server ↓ LynkMesh Core ↓ Local Codebase ``` 这允许 AI 代理使用 LynkMesh，而无需将源代码上传到托管服务。 早期的 MCP 工具可能包括： - `ping` - `get_status` - `get_capabilities` - `scan_project` - `get_project_summary` - `build_graph` - `get_graph_summary` - `analyze_impact` - `trace_dependencies` MCP 支持是实验性的，并将随着公共接口的稳定而演进。 ## 架构概述 ``` lynkmesh/ ├── ingestion/ │ ├── file scanning │ ├── language loading │ ├── parser orchestration │ └── IR normalization │ ├── graph/ │ ├── graph building │ ├── call resolution │ ├── graph enrichment │ ├── graph mapping │ └── validation │ ├── core/ │ ├── graph core │ ├── graph versioning │ ├── graph serialization │ ├── IR models │ ├── symbol registry │ └── type registry │ ├── semantic/contracts/ │ ├── confidence semantics │ ├── resolution contracts │ ├── edge semantics │ ├── provenance │ └── telemetry │ ├── analysis/ │ ├── architecture analysis │ ├── flow analysis │ ├── impact analysis │ └── semantic reasoning │ ├── query/ │ ├── query planning │ ├── query execution │ └── unified query abstraction │ ├── reasoning/ │ ├── graph reasoning │ └── chain execution │ ├── pipeline/ │ └── orchestration layer │ ├── exporters/ │ └── experimental export interfaces │ └── test/ ├── unit tests ├── integration tests └── semantic contract tests ``` ## 核心原则 ### 确定性 LynkMesh 优先考虑确定性的图标识、稳定的序列化和可复现的推理边界。 AI 系统可能会产生幻觉。基础设施不应如此。 ### 语义图优于原始文件 目标不仅是检索文件，而是理解实体之间的关系： - 文件 - 符号 - 类 - 方法 - 依赖项 - 调用 - 语义边界 - 架构边界 ### 默认本地优先 社区版旨在本地运行。除非用户明确选择托管工作流，否则源代码应保留在开发者的机器上。 ### 面向 AI 的上下文 LynkMesh 是为 AI 消费而设计的。输出应该是结构化的、有作用域的，并且足够明确，以便代理能够安全地在其上进行推理。 ### 诚实的能力报告 如果不支持某种语言、框架或运行时行为，LynkMesh 应该明确说明。 ## 当前的公开能力 公共核心目前专注于： - 文件扫描基础 - 解析器编排 - IR 标准化 - 图构建 - 图版本标识 - 确定性的序列化基础 - 符号注册表 - 类型注册表 - 语义契约 - 置信度语义 - 来源追踪 - 遥测契约 - 基础架构和推理层 - 实验性查询抽象 在此阶段，有意将高级增量运行时和持久化缓存内部组件排除在公共社区版之外。 ## 局限性 LynkMesh 尚未达到生产就绪状态。 已知局限性： - 公共 API 不稳定 - MCP 接口仍在演进 - PHP 支持不完整 - 非 PHP 语言官方不支持 - 框架魔法尚未完全建模 - 运行时行为未完全推断 - 导出器仍不完整 - 查询 API 仍处于实验阶段 - 大型仓库优化尚未公开 请将 LynkMesh 作为研究基础设施和早期 alpha 工具来使用。 ## 安装 打包工作仍在稳定中。 目前，请从源码使用此仓库： ``` git clone https://github.com/ommukhlis-spec/lynkmesh-open.git cd lynkmesh-open python -m pip install -U pip python -m pip install "mcp[cli]" ``` 随着公共 CLI 和 MCP 入口点的稳定，将添加额外的依赖项和打包说明。 ## 开发 从仓库根目录运行测试： ``` python -m pytest ``` 运行特定的测试模块： ``` python -m pytest test/unit/core/test_graph_version.py -v ``` 某些模块是实验性的，可能会快速发生变化。 ## 建议的用例 LynkMesh 社区版目前最适合用于： - AI 辅助的代码库探索 - 语义图实验 - 本地 MCP 工具实验 - 确定性的图标识研究 - 架构感知检索原型 - 面向 PHP 的静态分析探索 - 为 AI 代码智能系统构建基础 目前尚不适用于： - 生产环境 CI 强制执行 - 企业依赖治理 - 完整的运行时追踪 - 通用的多语言分析 - 完全自动化的重构工作流 ## 路线图 ### 阶段 1 — 语义基础 - 摄取 pipeline - 解析器编排 - IR 标准化 - 图构建 - 符号/类型注册表 ### 阶段 2 — 确定性图核心 - 图标识 - 图版本控制 - 语义契约 - 置信度/来源/遥测 - 确定性序列化 ### 阶段 3 — MCP + 查询层 - 本地 MCP server - 能力报告 - 图摘要工具 - 项目扫描工具 - 有作用域的查询 API - 面向 AI 的上下文检索 ### 阶段 4 — 上下文编译器 - 上下文排序 - 语义邻域检索 - 影响感知扩展 - token 感知上下文选择 - AI-ready 的解释 payload ### 阶段 5 — 高级运行时 高级运行时功能可能会在私有或商业层中开发： - 增量 diff 引擎 - 持久化图缓存 - 大型仓库图优化 - 托管 MCP - 团队图记忆 - 云端仓库集成 ## 仓库规范 公共仓库有意排除了： - 本地 AI 客户端设置 - 私有诊断 - 本地基准测试项目路径 - 调试产物 - 生成的图缓存 - 实验性的私有运行时模块 如果您在公共仓库中发现敏感或特定于机器的产物，请提交一个 issue。 ## 贡献 LynkMesh 仍处于早期阶段。欢迎贡献，但架构演进很快。 适合贡献的领域： - 文档 - 测试 - 解析器 fixtures - 小的 bug 修复 - 语义契约改进 - MCP 工具接口反馈 - 支持语言的能力报告 在进行较大的架构更改之前，请先提交一个 issue 或发起讨论。 ## 安全与隐私 LynkMesh 社区版旨在本地运行。 默认情况下，该项目不应上传源代码。任何未来的托管或远程工作流都应是显式的、经许可的，并单独记录。 不要提交： - `.env` - 本地 Claude 设置 - 私有项目路径 - 生成的图转储 - 调试追踪 - API keys - 本地缓存数据库 ## 许可证 LynkMesh 社区版计划在 Apache License 2.0 下发布。 商业、托管或 Pro 运行时组件可能会根据不同的条款单独分发。 在生产环境中使用kMesh 之前，请确认本仓库中当前的许可证文件。 ## 作者 作为一项独立的语义基础设施研究项目构建，旨在实现面向确定性的 AI 代码智能。 ## 项目理念 AI 代理需要的不仅仅是更大的上下文窗口。 它们需要稳定的语义基础设施。 LynkMesh 正是试图构建这一层的尝试。 ## 公共 CLI 快速入门 LynkMesh 提供了一个本地优先的公共 CLI，用于从本地项目生成确定性的、衍生自静态分析的产物。 此工作流是研究预览版/早期验证。它尚未达到生产就绪状态，不能证明运行时行为，并且生成的产物中不嵌入 LLM 推理。 ### 命令 ``` python -m lynkmesh doctor python -m lynkmesh report /path/to/project --pretty > report.json python -m lynkmesh pack /path/to/project --profile compact --pretty > ai-pack.json python -m lynkmesh benchmark /path/to/project --profiles compact --pretty > benchmark.json ``` Windows: ``` python -m lynkmesh doctor python -m lynkmesh report "C:\path\to\project" --pretty > report.json python -m lynkmesh pack "C:\path\to\project" --profile compact --pretty > ai-pack.json python -m lynkmesh benchmark "C:\path\to\project" --profiles compact --pretty > benchmark.json ``` ### 产物类型 - **MeshContext 报告**：确定性的项目图事实和保守的架构上下文。 - **AI 上下文包**：面向 AI 助手的紧凑、平衡或扩展的上下文包。 - **Token 基准测试**：用于报告和包配置文件的确定性 token 估算/校准。 可用的配置文件： - `compact` - `balanced` - `expanded` 默认配置文件：`compact`。 对于基准测试的多配置文件输出，请使用： ``` python -m lynkmesh benchmark /path/to/project --profiles compact,balanced,expanded --pretty ``` ### stdout 和 stderr 对于成功的 `report`、`pack` 和 `benchmark` 命令： - stdout 是有效的 JSON。 - stderr 包含进度、警告和诊断信息。 - 使用 `>` 重定向 stdout 以保存产物。 验证 JSON： ``` python -m json.tool report.json > /dev/null ``` Windows: ``` python -m json.tool report.json > nul ``` ### 隐私和限制 公共 CLI 是本地优先的，不会执行网络访问。生成的 payload 在打印前会通过安全检查，但它们仍可能包含项目名称、符号、结构信息以及衍生自代码的元数据。如果源项目是私有的，请避免公开分享生成的 JSON。 静态分析可能不完整。动态调度和运行时行为可能不完整。Entrypoints、热点和风险候选者是确定性的候选对象，而不是已确认的缺陷。

标签：AI辅助编程, SOC Prime, 上下文协议, 云安全监控, 代码理解, 安全规则引擎, 开发工具, 语义图谱, 逆向工具, 静态分析