企业官网建设流程全解析

Loushang 是一个 Python 编写的 AI 原生编码 Agent 框架，支持多模型 LLM 编排、有状态会话与工具治理。除了常见的读写文件、执行命令等基础工具外，它内置了两项容易被忽略的高级能力：LSP 语义检索（让 Agent 真正"看懂"代码符号与定义）和导入图分析（对整个仓库做确定性的依赖关系、循环依赖与架构边界检查）。本文带你快速了解这两项隐藏能力如何工作、何时使用以及如何启用。

上图是 Loushang 的目标架构总览，注意紫色的 "Agent + AI + admitted tools" 区域——Agent 的每一次工具调用都要经过策略与能力门控。LSP 与导入图分析正是挂载在这条工具链上的两个可选能力（Capability）。

🧭 为什么需要这两项高级工具

对新手来说，最直观的疑问是：Agent 不是已经会 grep 了吗？

• 文本搜索（grep/find）只能匹配字符串，分不清同名函数、别名和注释；
• LSP 语义检索走的是语言服务器，能精确回答"这个符号在哪定义、被谁引用、实现了哪个接口"；
• 导入图分析则站在仓库层面，回答"模块 A 是否循环依赖 B"、"哪个模块是热点"这类架构问题。

两者互补：一个向下钻到符号级，一个向上俯瞰依赖网。相关设计文档可参考 Coding LSP 规范 与 Coding Arch 架构说明。

🔍 LSP 语义检索：两个工具四种查询

LSP（Language Server Protocol）是 IDE 智能提示背后的协议。Loushang 的 lsp 包 把语言服务器包装成两个有界（bounded）工具，防止返回结果撑爆上下文：

inspect_symbol支持 4 种查询模式（定义在 tools.py 第 42-47 行）：

• definition：跳转到符号定义处
• references：查找所有引用位置
• hover：获取类型签名与文档说明
• implementation：查找接口的实现类

如何启用 LSP 语义检索

LSP 能力默认on_demand，语言服务器按需惰性启动，不占常驻内存（由 supervisor.py 中的运行时监督器统一管理）。只需启动时声明：

loushang --capability coding.lsp=always

它会探测本机已安装的 Pyright、TypeScript Language Server、rust-analyzer、gopls、clangd 等服务器；缺失时其他工具照常工作，Loushang 不会自动安装任何包。会话内还可以用/lsp status查看服务器生命周期统计，用/lsp stop <server-id> <root>优雅关停某个服务器。

💡 实战提示：当你问 Agent"这个函数的调用方有哪些"时，references查询比全文搜索准确得多——注释里的同名文字不会被误报。

🕸️ 导入图分析：仓库级依赖全景图

coding.arch能力把整个源码树解析成一张确定性的导入依赖图，核心实现在 import_graph.py 的query_import_graph中。它对每条依赖保留源码证据（哪个文件第几行），并按类别区分eager（模块加载即执行）、typing（仅类型注解）、deferred、lazy_export（惰性导出），这让"类型导入造成的循环"与"真运行期循环"能被区分开。

支持 6 种查询，按需取数而非一次性返回整图：

不启动 Agent 也能用：独立 CLI 模式

这是最容易被忽略的用法——导入图分析完全不依赖 LLM。在仓库根目录直接运行：

uv run python -m loushang.coding.arch src/loushang \ --package-prefix loushang --query summary --pretty

常用组合参数：

• --query cycles：只列循环依赖
• --query path --source loushang.coding.lsp --target loushang.harness：查依赖链
• --granularity subsystem：按子系统（顶层包）聚合，看大图
• --deny "src.*=tests.*" --fail-on-violations：作为 CI 架构门禁，违规时退出码为 1（完整参数见 cli.py）

结果带版本化文件级缓存，重复扫描秒级返回；缓存损坏会自动降级为重新扫描，而不是污染结论。

🛠️ 新手三步上手

1. 获取项目：git clone https://gitcode.com/gh_mirrors/lo/loushang，并用uv sync准备环境；
2. 开启语义检索：以loushang --capability coding.lsp=always启动，在会话里让 Agent 解释某个函数，观察它调用inspect_symbol而非 grep；
3. 跑一次架构体检：对任意 Python 项目执行上面的 CLI 命令，把cycles和hotspots的结果拿给 Agent 讨论重构方案。

在交互式会话中启用coding.arch的方式类似：loushang --capability coding.arch=always，之后 Agent 就能调用 inspect_import_graph 工具。两种能力都可以disabled关闭，或保持on_demand由 Agent 自行按需触发。

⚖️ 语义检索 vs 导入图分析：怎么选

更多细节可查阅官方用户指南、LSP 组件边界与Arch 系统上下文。

📌小结：LSP 语义检索让 Agent 从"读文本"升级为"读语义"，导入图分析则把架构治理变成一条可重复执行的确定性命令。两者都遵循 Loushang 的"有界结果 + 能力门控"设计哲学——这也是它作为工具治理型 Agent 框架的核心特征。