blackwell-systems/knowing

自适应代码智能引擎。自动观察自身图密度并调整检索策略。38种边类型、28个MCP工具、263个等价类、加密证明。规模越大越智能，而非越笨拙。 你的架构图显示服务A调用服务B。你能证明吗？ **knowing 可以。** 它构建所提取代码关系的内容寻址图，将其快照为关联到git提交的Merkle树，并生成可离线验证的加密证明。Agent 用其进行排序上下文。安全团队用于审计。平台团队用于将代码与生产追踪进行比对。 每次使用它都会优化。当代码变更时，陈旧知识自动过期。 ``` brew install blackwell-systems/tap/knowing ``` ``` { "mcpServers": { "knowing": { "command": "knowing", "args": ["mcp", "--watch"] } } } ``` 就这些。MCP 服务器在首次启动时自动索引你的仓库。无需模型下载，无需 API 密钥。你的 Agent 现在拥有排序上下文、爆炸半径、测试范围以及隐式噪声降低，可在活动会话中改进结果。 **验证其工作：** 询问你的 Agent："使用 context_for_task 工具查找与[你已知代码中存在的某个内容]相关的符号。" 你将看到来自你代码库的带有分数和文件路径的排序符号。如果结果为空，仓库仍在索引中（首次启动需 10-30 秒）。如果结果不相关，请参阅[故障排除](docs/guide/cli.md#troubleshooting)。 | 你想做… | 从这里开始 | |---|---| | 为你的 AI Agent 提供图排序上下文 | [MCP 设置](#mcp-integration) | | 从 CLI 探索图 | [CLI 用法](#path-b-cli-usage-explore-the-graph-yourself) | | 理解检索机制 | [简介](docs/guide/introduction.md) | | 使用加密证明进行审计 | [审计与合规](docs/guide/audit-compliance.md) | ## 三大功能，同一架构 knowing 是在同一基础（内容寻址图与分层 Merkle 树）上构建的三款产品： **1. AI Agent 的上下文引擎** 一次调用返回任务最相关的符号，按图中介中心性、新近度和学习到的有用性排序，并根据你的 Token 预算打包。当关键字匹配失败时，263 个框架等价类可弥合词汇差距。工具调用减少 47%，Token 减少 84%。结果随反馈而改进。 **2. 合规审计原语** 每个图状态都是一个关联到 git 提交的 Merkle 根。`knowing prove` 生成关系存在过的加密证明。`knowing verify` 离线验证。`knowing fsck` 在 98ms 内验证整个图。供应链检测可提取凭据访问、进程派生和网络外泄边，以标记结构可疑的代码。 **3. 自学习噪声降低** Agent 返回但从未使用的符号将在后续查询中被降级。代码变更时，反馈自动过期（通过包 Merkle 根验证）。系统在活动会话中变得更加精确。这就是 knowing 所围绕的特性。 **这些并非独立功能。** 它们是内容寻址的结构性结果：使上下文可缓存的同一哈希也使其可验证，而使陈旧性可检测的同一 Merkle 根也使陈旧反馈过期。 ## 它能回答什么 **为你的 Agent：** - "我正在修改这个函数。什么会出问题？"（调用者、测试、路由、仓库间的爆炸半径） - "给我 50,000 Token 的任务上下文。"（基于图排序，而非 grep 搜索） - "应该运行哪些测试？"（调用图遍历，98% 精确率） **为你的平台团队：** - "这个路由在生产中是否被使用？"（静态分析 + OTel 运行时追踪） - "在某个特定快照时，服务图是怎样的？"（快照链，每个根关联到一个 git 提交） **为你的安全团队：** - "证明服务 A 在此提交调用服务 B。"（Merkle 证明，可离线验证） - "证明此依赖不存在。"（通过排序叶子的缺席证明） - "生成合规报告。"（`knowing audit -proofs`，一条命令） - "此包是否读取凭据并派生进程？"（`knowing audit-supply-chain --scan-all`） ## 数据 | 指标 | 结果 | |---|---:| | 跨系统检索 | **P@10=0.278 冷启动**（308 个任务，16 个仓库，8 种语言） | | 与竞品对比 | 3.20x codegraph（19K 星）、5.05x GitNexus、5.35x Gortex、18.5x grep | | 等价类 | 263 个概念桥接任务词汇与代码符号（+57% P@10） | | 噪声降低 | 经过 3 轮隐式反馈后 P@10 提升 +5.9%（Django） | | 节省工具调用 | 减少 47%（一次上下文调用替代重复的 grep+读取） | | 节省 Token | 减少 84%（GCF 有线格式） | | 重复查询速度 | 快 93 倍（Merkle 键控子图缓存） | | Merkle 差异 | 在 100K 边时比全边扫描快 517 倍 | | 测试范围 | 98% 精确率，82% 召回率 | | 图完整性检查 | 98ms（24,936 条边） | | 证明生成 | 生成 72μs，验证 1.2μs | | 反馈过期 | 代码变更时 100% 过期，11% 开销 | | 索引吞吐量 | 15 个仓库（8 种语言）约 54 秒 | | 语言覆盖率 | 13/15 仓库通过（Go、Python、TS、Rust、Java、C#、Ruby、多语言） | | 边类型 | 38 种（包括供应链：reads_env、executes_process） | 所有基准均可复现。跨系统基准测试（P@10=0.278）使用 16 个仓库，锁定于确切提交，并附有[语料清单](bench/cross-system/corpus/MANIFEST.yaml)和[设置脚本](bench/cross-system/corpus/corpus-setup.sh)，可从零完整复现。详见 [METHODOLOGY.md](bench/cross-system/METHODOLOGY.md) 中的协议细节。 ## 快速开始 ### 路径 A：MCP 服务器（推荐用于 AI Agent） ``` # 1. 安装 brew install blackwell-systems/tap/knowing # 或者：npm install -g @blackwell-systems/knowing # 或者：pip install knowing # 或者：go install github.com/blackwell-systems/knowing/cmd/knowing@latest # 2. 添加到您的 agent 配置（.mcp.json、Claude Code 设置等） # 请参阅下面的“MCP Integration”以获取配置块。 # 服务器会在首次启动时自动索引您的仓库。完成。 ``` ### 路径 B：CLI 用法（自行探索图） ``` # 1. 安装（同上） brew install blackwell-systems/tap/knowing # 2. 索引您的仓库 knowing add . # 3. 验证索引是否工作 knowing stats # 您应该看到节点和边的数量。一个健康的 TypeScript 仓库，有 50K LOC， # 通常会产生 2K-10K 个节点和 5K-30K 条边。如果您看到的边很少， # 提取器可能没有找到您的代码（请检查下面的语言支持）。 # 4. 获取任务上下文 knowing context -task "refactor auth middleware" -format gcf # 5. 检查图完整性 knowing fsck ``` ### 验证你的设置 索引后，运行以下命令以确认一切正常： ``` # 显示节点/边数量、仓库、快照 knowing stats # 搜索您知道存在于代码中的符号 knowing query "MyKnownFunction" # 检查图完整性（应报告 0 个错误） knowing fsck # 如果结果看起来错误，请检查图是否过时 knowing stale ``` 如果 `knowing stats` 显示零个节点或非常少的边，请参阅下面的[故障排除](docs/guide/cli.md#troubleshooting)。 ### 更多 CLI 命令 ``` # 查找受影响的测试 knowing test-scope -files internal/auth/middleware.go # 解释为什么某个符号排名如此 knowing why -task "refactor auth" -symbol "SessionHandler" # 证明存在关系（cryptographic Merkle proof） knowing prove -source "AuthService" -target "SessionStore" # 离线验证（无需数据库） knowing verify proof.json # 检查图是否过时（CI gate：如果过时则退出码为 1） knowing stale # 供应链审计（扫描所有文件以查找可疑模式） knowing audit-supply-chain --scan-all # 删除仓库（移除所有数据：节点、边、快照、反馈） knowing remove ./path/to/repo ``` 完整命令参考，请参见 [CLI 参考](docs/guide/cli.md)。 ### MCP 集成 将 MCP 服务器添加到你的 Agent 中。配置在所有环境中均相同；仅文件路径。 | Agent | 配置文件 | |-------|-------------| | **Claude Code** | `.mcp.json`（项目根目录）或 `~/.claude/mcp.json`（全局） | | **Cursor** | `.cursor/mcp.json` | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **VS Code**（Copilot、Continue、Cline、Roo） | `.vscode/mcp.json` | | **Zed** | `~/.config/zed/settings.json` 中的 `"context_servers"` | | **Codex**（OpenAI） | `codex.json` 或 `--mcp-config` 标志 | | **JetBrains** | 设置 > 工具 > MCP 服务器 | ``` { "mcpServers": { "knowing": { "command": "knowing", "args": ["mcp", "--watch"], "transport": "stdio" } } } ``` `--watch` 标志在文件变更时重新索引。你的 Agent 始终查询最新数据。无需手动 `knowing index` 或指定数据库路径：MCP 服务器在首次启动时自动索引 git 仓库，并将其注册到名单中以备后续会话。 默认情况下嵌入关闭（在冷启动基准测试中确认为中性）。若要实验，请使用 `--embeddings` 启用。图结构和等价类承担检索质量。 **你的 Agent 获得什么：** 关键工具是 `context_for_task`。当你的 Agent 调用它并传入任务描述时，knowing 返回按 Token 预算打包的排序相关代码符号。这替代了 grep-读取循环。其他有用工具：`blast_radius`（如果我更改此内容会出什么问题？）、`test_scope`（要运行哪些测试？）、`explain_symbol`（为什么该符号在此处排这么高？）。查看 [MCP 工具参考](docs/guide/mcp-tools.md)了解全部 28 个工具。 **验证它是否有效：** 1. 与你的 Agent 开始会话 2. 询问："使用 context_for_task 工具查找与[代码中的特定内容]相关的符号" 3. 你将看到来自你代码库的带有分数和文件路径的排序符号 如果结果为空：仓库可能仍在索引中（首次启动需 10-30 秒）。如果结果不相关：请在任务描述中使用具体的符号名称（例如，"查找 `AuthMiddleware` 处理器"，而非"查找认证代码"）。你也可以从 CLI 验证： ``` knowing stats # should show nodes and edges knowing query "MyFunc" # should find symbols you recognize ``` 对于 HTTP 传输（多 Agent、守护进程模式）： ``` knowing serve -addr :8100 . ``` ``` { "mcpServers": { "knowing": { "url": "http://localhost:8100", "transport": "streamable-http" } } } ``` ## 为什么这有效 **Git 对文件进行版本控制。knowing 对代码理解进行版本控制。** 整个系统建立在一个理念之上：内容寻址的身份。每个符号、关系和快照都使用 SHA-256 哈希。这一选择为你带来： - **免费检测陈旧性。** 文件变更 = 新哈希 = 无需扫描即可知道陈旧边。 - **免费缓存。** 相同包根 = 相同结果。未变化查询的速度提升 93 倍。 - **免费完整性。** 验证所有存储哈希和快照链连续性。98ms。 - **免费历史记录。** 每个快照都是关联到 git 提交的 Merkle 根。遍历链。 - **免费反馈过期。** 反馈存储包 Merkle 根。代码变更 = 根变更 = 旧反馈不可见。 - **免费证明。** 从叶子到根的 Merkle 路径是一个自包含的加密证明。 | | Git | knowing | |---|---|---| | 版本控制对象 | 文件内容 | 代码关系及其含义 | | 存储单位 | blob | 节点 + 边 + 来源 + 置信度 | | 身份 | `sha256(内容)` | `sha256("node\0" + 仓库 + 包 + 名称 + 种类)` | | 快照 | blob 树 | 分层 Merkle：仓库 -> 包 -> 边类型 -> 叶子 | | 差异 | 哪些行发生变化 | 哪些包发生变化、什么出问题、什么是新增的 | | 历史 | 代码看起来像什么 | 代码库对自身的理解 | ## 工作原理 ``` +------------------------------------------------------------------+ | knowing daemon | +----------------+------------------------+--------------------------+ | Indexer | Graph Store | MCP Server | | | | | | 23 extractors | Content-addressed | 28 tools + 8 resources | | tree-sitter | SQLite + Merkle tree | stdio / HTTP (1.8s index)| | LSP + SCIP | 38 edge types | GCF / GCB / JSON | | OTel traces | Subgraph cache (93x) | PackRoot dedup (99%) | | | Embedding vector cache | Embedding re-ranker | | | Community detection | Supply chain audit | +----------------+------------------------+--------------------------+ ``` 两个层面： - **执行层：** 索引仓库、提取符号和关系、摄入追踪、存储快照。 - **智能层：** 从存储的图计算爆炸半径、上下文包、测试范围、反馈、社区。 边界很重要：智能层功能读取图并产生衍生结果。它们不能破坏图事实。糟糕的排序会产生糟糕的建议；不能使证明失效。 ## 能力 ### 语言与格式 | 语言/格式 | 提取器 | 框架/模式检测 | |---|---|---| | Go | tree-sitter + `go/packages` + SCIP | net/http、gin、echo、chi、gorilla/mux | | TypeScript/JavaScript | tree-sitter | Express.js、Fastify、Hono、NestJS、Next.js | | Python | tree-sitter | Flask、FastAPI、Django | | Rust | tree-sitter | Actix、Axum、Rocket | | Java | tree-sitter | Spring 注解 | | C# | tree-sitter | ASP.NET 属性 | | Protocol Buffers | tree-sitter | service、message、enum、RPC 声明 | | Terraform（HCL） | tree-sitter | resource、data、module、variable 声明 | | SQL | tree-sitter | tables、views、functions、procedures、FK 边 | | Kubernetes YAML | yaml.v3 | deployments、services、configmaps、label-selector 边 | | CloudFormation/SAM | yaml.v3 | resources、!Ref/!GetAtt/!Sub 交叉引用 | | Docker Compose | yaml.v3 | services、ports、networks、depends_on 链接 | | GitHub Actions | yaml.v3 | workflows、jobs、steps、action 引用 | | Serverless Framework | yaml.v3 | functions、events、resource 引用 | | CSS/SCSS | tree-sitter | selectors、custom properties、var() 依赖 | | 事件/消息队列模式 | 多语言 | Kafka、NATS、SQS、RabbitMQ 发布/订阅 | | OpenAPI/JSON Schema | json/yaml | endpoints、models、$ref 解析 | | Dockerfile | 解析器 | FROM 基础镜像、COPY --from 多阶段依赖、EXPOSE 端口 | | Makefile | 解析器 | 目标依赖、include 指令、变量引用 | | Helm Charts | yaml.v3 | chart 依赖、模板引用、values 注入 | | GitLab CI | yaml.v3 | job needs、extends 模板、include 文件、artifacts | | package.json（npm） | json | dependencies、devDependencies、peerDependencies、scripts | | GraphQL | 解析器 | 类型定义、字段类型引用、接口实现 | | Ruby | tree-sitter | classes、modules、method 定义、require 边 | | .env 文件 | 解析器 | 环境变量声明、跨文件引用 | 所有提取器按文件通过多分派触发；结果合并。Tree-sitter 生成置信度为 0.7（`ast_inferred`）的边；`go/packages` 和 SCIP 生成置信度为 0.95-1.0（`ast_resolved`、`scip_resolved`）的边。 ### MCP 工具 | 工具 | 用途 | |---|---| | `index_repo`、`graph_query`、`repo_graph` | 构建和检查图 | | `cross_repo_callers`、`blast_radius`、`trace_dataflow`、`flow_between` | 理解影响和路径 | | `snapshot_diff`、`semantic_diff`、`pr_impact``stale_edges` | 比较图状态和审查变更 | | `runtime_traffic`、`dead_routes`、`trace_stats` | 查询运行时观察到的关系 | | `context_for_task`、`context_for_files`、`context_for_pr`、`explain_symbol` | Agent 的排序上下文 | | `ownership`、`ownership_query`、`test_scope`、`communities`、`plan_turn`、`feedback` | 路由工作、查询代码所有者/作者、选择测试、改进排序 | | `prove`、`prove_absent`、`fsck` | 加密证明、缺席证明、完整性验证 | | `untrack_repo` | 驱逐仓库的所有数据（节点、边、文件、快照、反馈、任务记忆、图注释） | MCP 提示：`refactor_safely`、`review_pr`、`investigate_dead_code`。 ### MCP 资源 8 个只读资源，用于 Agent 在不进行工具调用时了解方向： | 资源 | 返回内容 | |---|---| | `knowing://report` | 图大小、top kinds、热点计数、快照年龄 | | `knowing://schema` | 节点种类、边类型、来源层级、哈希格式 | | `knowing://stats` | 按仓库、种类和边类型的计数 | | `knowing://repos` | 所有跟踪的仓库及其计数和最后索引时间 | | `knowing://session` | 上下文调用、服务符号、缓存命中/未命中、运行时间 | | `knowing://index-health` | 健康/陈旧/损坏状态、完整性检查 | | `knowing://communities` | 社区列表，含凝聚力和 Merkle 根 | | `knowing://community/{id}` | 单个社区详情（资源模板） | ## 有线格式 | 格式 | 用途 | 相比 JSON 的节省 | |---|---|---| | **GCF**（图紧凑格式） | LLM 消费：面向行、位置字段 | Token 减少 84% | | **GCB**（图紧凑二进制） | 服务传输和缓存：varint、长度前缀 | 字节减少 74% | | **JSON** | 人工调试、通用消费者 | 基准 | GCF 使用 `|` 分隔的字段和本地 ID（`$1 -> $3`）替代重复的限定名称。LLM 可解析，同时将更多图上下文装入相同的 Token 预算。会话状态去重将重复符号减少 47%。 ## 当前边界 - 静态爆炸半径跟随 `calls` 边；其他边类型提供上下文，而非遍历。 - 运行时工具需要 OpenTelemetry 追踪摄入；没有追踪则无观察。 - LSP 增强：Go、TypeScript、Python、Rust、Java、C#。根据项目标记自动检测。其他语言回退到 tree-sitter。 - 默认情况下嵌入关闭（在冷启动基准测试中确认为中性，会话 23）。使用 `--embeddings` 选择加入。 ## 文档 | 文档 | 内容 | |---|---| | [简介](docs/guide/introduction.md) | 工作原理、检索管道说明、5 分钟演练 | | [架构](docs/architecture/) | 系统设计、模式、内容寻址、守护进程模型 | | [功能](docs/guide/features.md) | 实现清单、入口点、限制 | | [审计与合规](docs/guide/audit-compliance.md) | Merkle 证明、fsck、快照链、CI 门控 | | [CLI 参考](docs/guide/cli.md) | 命令、标志、示例、[故障排除](docs/guide/cli.md#troubleshooting) | | [MCP 工具](docs/guide/mcp-tools.md) | 工具模式、参数、返回格式 | | [边类型](docs/architecture/edge-types.md) | 关系语义和来源 | | [上下文打包](docs/architecture/context-packing.md) | RWR、HITS、排序、Token 预算 | | [嵌入重排序器](docs/architecture/embedding-reranker.md) | 本地推理、向量缓存、延迟剖面 | | [运行时追踪](docs/operations/runtime-traces.md) | OTel 摄入和运行时置信度 | | [有线格式](docs/architecture/wire-formats.md) | GCF、GCB、JSON 格式和基准测试 | | [路线图](docs/roadmap.md) | 已完成工作流和下一优先级 | | [基准测试](bench/README.md) | 可复现的值基准测试及性能合同 | | [研究](docs/research/content-addressing-as-computation-primitive.md) | knowing 所基于的论文：内容寻址作为计算原语（[DOI: 10.5281/zenodo.20342255](https://zenodo.org/records/20342255)） | | [钩子](hooks/README.md) | Claude Code 钩子集成 | ## 许可 MIT

标签：EVTX分析, Git集成, JS文件枚举, MCP协议, Merkle树, SOC Prime, 上下文排序, 代码关系提取, 代码分析, 代码智能, 元数据管理, 内容寻址, 凭证管理, 加密证明, 可视化界面, 开发工具, 影响范围分析, 日志审计, 智能引擎, 测试范围, 自动化payload嵌入, 自动适应, 逆向工具, 验证工具