quangdang46/scope

# scope ## 当前状态 该仓库目前实现了： - 一个包含 `scope-core`、`scope-cli` 和 `scope-mcp` 的 Rust workspace - 用于发现仓库根目录并创建 `.scope/index.db` 的引导逻辑 - SQLite 初始化、schema 版本跟踪，以及持久化的文件/导入/符号/符号边/变动/快照记录 - 针对 Rust、TS/JS、Python、Ruby 和 Go 文件类型的忽略感知型仓库扫描 - 针对 Rust 和 TS/JS 的导入、导出、符号、可见性和直接调用点的启发式语义提取 - 用于依赖、符号、影响、架构、报告/门禁、差异和模拟工作流的机器可读 CLI 命令 - 一个带有打包嵌入式 UI 的本地 HTTP `/api/*` server - 一个 stdio MCP 工具 server，将相同的核心存储/查询面暴露给外部客户端 - 基于 fixture 的黄金测试以及针对当前契约的 CLI 集成覆盖 该仓库**尚未**实现： - tree-sitter 或其他基于 AST 的解析 - 基于解析器的遍历和影响分析精度改进 - 针对 Python、Ruby 或 Go 的语义提取适配器（这些文件类型会被扫描，但尚未进行深度索引） - tsconfig 路径映射以及其他更丰富的模块解析场景 - 计划中的查询 REPL 人体工学功能，如历史记录、补全和保存查询工作流 ## 目标 在编辑文件之前，agent 应该能够询问： - 这个文件依赖什么？ - 什么依赖这个文件？ - 这里定义了哪些符号？ - 什么调用了这个符号？ - 更改的可能影响范围是什么？ `scope` 的构建旨在通过本地持久化索引而非重复的手动文件读取来回答这些问题。 ## 架构方向 预期的架构是： ``` 1. Bootstrap runtime state └── discover repo root └── create .scope/ └── open SQLite index 2. Index source files └── walk source files with ignore-aware scanning └── extract imports / exports / symbols / call sites from supported Rust and TS/JS files └── persist file, symbol, call-edge, and related analysis data 3. Query the graph └── deps / symbols / calls / callers / impact / explain / why / context work today └── report / gate / serve / MCP reuse the same core store queries └── richer resolution and precision improvements remain planned ``` 当前的代码库在 CLI、本地 HTTP server 和 stdio MCP wrapper 中拥有可工作的 stage-2 和 stage-3 切片，但解析器保真度和若干解析/精度功能仍不完整。 ## 当前技术栈 ### 目前已实现 | Crate | 用途 | |---|---| | `clap` | CLI 解析 | | `rusqlite` | 本地 SQLite 存储 | | `serde` / `serde_json` | 机器可读输出 | | `tracing` / `tracing-subscriber` | 日志记录 | | `thiserror` | 错误处理 | ### 计划中 / 尚未实现 | Crate / 能力 | 预期用途 | |---|---| | `tree-sitter` + grammars | 用更强大的语法支持提取替代启发式解析 | | graph traversal library | 支持传递依赖、影响和解释查询 | | multi-language adapters | 将索引扩展到当前以 Rust 为优先的实现之外 | ## Workspace 布局 ``` scope/ ├── crates/ │ ├── scope-cli/ # CLI entrypoint │ ├── scope-core/ # shared models, bootstrap, storage, query/report/serve logic │ └── scope-mcp/ # stdio MCP/JSON-RPC wrapper over scope-core └── .scope/ └── index.db # local SQLite index database ``` ## 命令面 当前的 CLI 暴露了这些命令家族： ``` scope index [PATH] scope deps [--reverse] [--transitive] [--depth N] scope symbols [--public-only] [--kind ...] scope calls [--transitive] scope callers [--transitive] scope impact --change-type scope explain [--to ...] [--depth N] scope why [--depth N] scope context --target ... --change-type <...> [--budget N] scope pack --change-type <...> --budget scope arch check | scope audit --capability | scope surface [diff] scope stability | risk | cochange | test-map | rename-plan | snapshot | diff-snapshot scope simulate extract ... | report | gate | unused | cycles | diff | tree | split | mirror | entry scope serve [--port 7777] [--no-ui] scope query [--expr ...] scope doctor [--fix] | benchmark [--fixture ...] [--iterations N] [--write-report] ``` 目前： - `scope index` 扫描受支持的文件，索引 Rust 和 TS/JS 提取内容，并刷新 `.scope/index.db` 中的依赖/调用边 - `scope deps`、`scope symbols`、`scope calls`、`scope callers`、`scope impact`、`scope explain`、`scope why`、`scope context` 和 `scope pack` 从 SQLite 支持的图返回结构化信封 - architecture、audit、surface、risk/stability/cochange、test-map、snapshot/diff、simulation、report/gate、unused/cycles、entry、tree/split/mirror、doctor 和 benchmark 命令目前均已接入 CLI - `scope serve` 通过带有打包嵌入式 UI 的 `/api/*` 端点暴露相同的核心分析 - `scope query` 支持单表达式执行和基于查询语言的基础交互式 REPL - `scope-mcp` 将核心操作暴露为由相同 store/query 层支持的 stdio MCP 工具 - `scope benchmark --write-report` 将 linehash 风格的 Markdown 摘要写入 `bench-results/benchmark.md` 以及一个带时间戳的 `bench-results/bench-YYYY-MM-DD-HH-MM-SS.md` 快照 ## Agent 使用模式 `scope` 旨在 agent 开始编辑代码之前回答仓库结构问题。 ### 编码 Agent 的推荐工作流 1. 针对你正在处理的仓库快照运行一次 `scope index .`。 2. 提出能够回答当前规划问题的最窄查询。 3. 当结果将被反馈到 agent 循环时，优先使用 `--compact` 以供机器消费。 4. 将结果视为静态证据，而非更改安全的证明。 5. 编辑后使用测试、构建和人工审查来验证更改。 ### 典型的编辑前问题 ``` scope deps src/lib.rs scope --compact symbols src/parser.rs --public-only scope --compact callers parser::parse scope --compact context --target parser::parse --change-type body --budget 400 scope pack parser::parse --change-type body --budget 400 ``` 像这样使用它们： - `deps` / `--reverse` 以理解直接的文件级耦合 - `symbols` 以在编辑前查看文件定义了什么 - `calls` / `callers` 以理解直接的符号级交互 - `impact` / `explain` / `why` / `context` 当你需要结构化的更改规划证据时 - `pack` 当你想要为 agent prompt 提供精简的纯文本交付物时 ### 输出预期 机器可读命令返回一个稳定的 JSON 信封： - `schema_version` — 下游工具的契约版本 - `command` — 产生结果的命令名称 - `status` — `ok`、`stub` 或 `error` - `data` — 特定命令的负载 - `warnings` — 非致命提示 默认输出是用于可读性的美化打印 JSON。 `--compact` 保持相同的顶级 JSON 契约，同时降低 token 成本： - 发出压缩后的 JSON 而非美化 JSON - 在可能的情况下从负载中修剪 null 和空的嵌套字段 - 保留必要的图事实，如路径、原因、确定性和命令元数据 紧凑模式旨在用于 agent 循环和传输效率，不适用于人类阅读终端输出。 ### 当前针对 Agent 的限制 - 语义提取目前在 Rust 和 TS/JS 方面最强；Python、Ruby 和 Go 目前仅限扫描 - 传递 `deps`、`calls` 和 `callers` 目前可用，但它们仍然是基于启发式提取和保守解析构建的静态近似值 - 解析和解析策略仍是启发式的，可能会遗漏特定语言的边缘情况 - TypeScript 模块解析是保守的，尚未覆盖 `tsconfig` 路径映射 - 查询 REPL 存在，但尚未实现计划中的历史记录/补全/保存-加载人体工学功能 - 结果是静态近似值，可能会遗漏动态行为 - `scope-mcp` 目前可用，但 CLI 仍然是最成熟的集成面 ## 示例当前输出 ### `scope index .` ``` { "schema_version": 1, "command": "index", "status": "ok", "data": { "repo_root": ".", "no_git": false, "watch": false, "database": { "path": ".scope/index.db", "schema_version": 1 } }, "warnings": [] } ``` ### `scope deps src/lib.rs` ``` { "schema_version": 1, "command": "deps", "status": "ok", "data": { "target": "src/lib.rs", "reverse": false, "transitive": false, "depth": null, "dependencies": [ { "path": "src/parser.rs", "kind": "import", "certainty": "exact" }, { "path": "src/resolver.rs", "kind": "import", "certainty": "exact" } ] }, "warnings": [] } ``` ## 数据模型方向 `scope-core` 已经为计划中的引擎定义了共享记录，包括： - 文件和解析状态 - 导入和导出 - 符号和可见性 - 调用点 - 依赖遍历记录 - 确定性级别，如 `exact`、`resolved`、`heuristic` 和 `dynamic` 该模型旨在支持机器优先的静态分析，而不暗示运行时保证。 ## 安装 该项目仍在积极开发中，尚未准备好作为完成的软件包进行宣传。 针对本地开发： ``` cargo run -p scope-cli -- --help cargo run -p scope-cli -- index . cargo run -p scope-cli -- --compact deps src/lib.rs cargo run -p scope-cli -- report cargo run -p scope-cli -- serve --port 7777 cargo run -p scope-mcp ``` ## 近期路线图 - 用基于解析器的逻辑取代启发式 Rust 和 TS/JS 提取 - 提高 `deps`、`calls` 和 `callers` 的传递遍历精度 - 持久化更丰富的诊断/导出数据并加强确定性报告 - 添加 Rust 和 TS/JS 之外的语义适配器，包括更好的 TypeScript 模块解析 - 通过历史记录、补全和保存查询工作流改进查询 REPL - 深化 MCP 打磨/覆盖范围，同时保持 JSON 契约对 agent 消费的稳定性 ## Scope 边界 `scope` 旨在提供**静态**依赖和影响洞察。 它不应被描述为： - 一个运行时行为预言机 - 更改安全的保证 - 测试、构建或人工审查的替代品 结果应被解释为具有明确确定性级别的结构化静态证据。 ## 预期的确定性模型 计划中的分析模型使用四个确定性级别： - `exact` — 直接由明确的语法或确定性的解析支持 - `resolved` — 得到仓库上下文的强力支持，但需要一些推理 - `heuristic` — 合理且有用，但不保证 - `dynamic` — 已知的盲点或未解决的动态行为 预期的规则是保守解析： - 宁可遗漏低置信度的边，也不 invent 一个错误的边 - 将 `exact` 保留给明确的证据 - 在结果中展示不确定性，而不是隐藏它 这对于影响分析尤为重要，因为在影响分析中，假阳性可能比不完整但诚实的结果更具破坏性。 ## 预期的盲点和限制 即使在引擎实现后，某些类别的行为仍应被视为不确定或仅被部分建模： - 动态导入 / 计算模块路径 - 反射和元编程 - 宏展开和生成的代码 - 无法静态解析的动态分发模式 - 需要尚未实现的适配器的特定框架约定 - 解析器无法完全解释的不受支持的语言或语法 `PLAN.md` 中的项目方向是明确标记这些案例，而不是假装完全理解它们。 ## 预期的故障处理原则 项目方向还包括几个重要的信任规则： - 不要静默丢弃解析问题；展示部分结果和诊断 - 当可能产生部分结果时，不要因不支持的语法而崩溃 - 当结果仅为静态近似值时，不要过度声称“完全影响” - 保持 JSON 输出机器可读，并随着契约的发展保持稳定

标签：AST解析, HTTP服务器, IP 地址批量处理, MCP, Rust, SQLite, 云安全监控, 代码可视化, 代码搜索, 依赖图, 变更影响分析, 可视化界面, 技术债管理, 本地代码库, 符号索引, 网络流量审计, 调用图, 软件供应链, 通知系统, 静态分析