Archiet Xray

Archiet X-Ray

mcp-name: io.github.Anioko/archiet-xray

看看你的 AI 看到了什么。 你的代码库太大，超出了任何 AI Agent 的上下文窗口。Agent 读取 4,000 个文件中的 40 个，做出修改，而你却无从得知它是否遵循了架构，还是悄悄违反了架构约束。

X-Ray 可确定性地提取任意代码库的实际架构，不使用大模型，代码也不会离开你的设备；并将其同时提供给你（交互式地图）和你的 AI Agent（MCP 服务 + 上下文包）。

$ python xray.py .

Archiet X-Ray v0.2.0 — your-repo
  visibility score : 78/100
  prod readiness   : 71/100 (near production-ready)
  code files       : 3,412 (1,907 read, 1,584 with elements)
  routes           : 214
  entities         : 87
  async tasks      : 31
  findings         : 6
  wrote            : .archiet/ARCHITECTURE.md
                     .archiet/AGENT_CONTEXT.md
                     .archiet/architecture.json
                     .archiet/diagrams/diagrams.html (+3 .mmd)

你将获得

文件	说明
ARCHITECTURE.md	易于阅读的地图：模块依赖图（Mermaid）、领域模型、所有路由及其身份验证状态、依赖热点、风险发现项、生产就绪度评分卡
AGENT_CONTEXT.md	放入你的 CLAUDE.md / 规则文件中，即可让 Claude Code、Cursor 和 Windsurf 从今天起遵循你的架构
architecture.json	机器可读模型（“代码库基因组”）
diagrams/	Mermaid 源码形式的架构图，以及独立的 HTML 查看器——包括模块依赖图、ER / 领域模型图、HTTP 路由图

生产就绪度评分（0.2 版新增）

基于 8 个维度的确定性0–100 分生产就绪度评分：路由身份验证覆盖率、密钥管理规范、客户端令牌存储、数据层规范、测试覆盖范围、迁移规范、运维就绪度（Docker/CI/.env 合约）以及文档/API 合约。相同的代码库始终得到相同的分数，因此可在不同提交、分支和代码库之间比较，也可将其纳入 CI。

每个维度都会报告证据（“214 个静态防护路由中，有 142 个带有身份验证守卫”），报告结尾还会列出按失分排序的首要修复项。对于不适用的维度（CLI 工具没有路由），会给予一半分数并说明原因——坦诚，不吹捧。

适用场景：发布前审查 AI 生成的代码、审计接手的代码库，或跟踪代码库是否随着时间推移而偏离生产就绪状态。

从代码生成架构图（0.2 版新增）

generate_diagrams 可从代码本身确定性地提取信息，将任意代码库转换为 Mermaid 架构图：

• 模块依赖图——实际的导入结构，而非 Wiki 上的结构
• ER / 领域模型图——从 SQLAlchemy、Django 和 Prisma 模型中提取实体及关系
• HTTP 路由图——按前缀分组的 API 接口

你将获得原始 .mmd 源文件（可粘贴到任意 README、Wiki、GitHub、GitLab、Notion、Obsidian 或 VS Code 中——它们都原生支持 Mermaid 渲染），以及独立的 diagrams.html 查看器。

提供给你的 Agent（MCP）

# Claude Code (from PyPI — pip install archiet-xray)
claude mcp add archiet-xray -- archiet-xray mcp /path/to/repo

# or from a checkout
claude mcp add archiet-xray -- python /path/to/mcp_server.py /path/to/repo

Claude Desktop——从最新版本下载 archiet-xray-<version>.mcpb，然后双击它（或依次选择 Settings → Extensions → Install Extension）。它会提示你选择要分析的代码库；之后只需点击一次。

官方 MCP 注册表——已登记为 io.github.Anioko/archiet-xray，支持注册表的客户端可按名称安装。

现在，你的 Agent 可以在编辑之前询问：

• blast_radius——“哪些文件依赖此文件？如果我修改它，会导致什么问题？”
• arch_summary——“路由 / 实体 / 服务实际位于哪里？”
• boundary_findings——“硬编码密钥、原始 SQL、localStorage 中的令牌、未经身份验证的路由”
• production_readiness——“根据证据和首要修复项，为此代码库的生产就绪度打 0–100 分”
• generate_diagrams——“用 Mermaid 绘制模块图 / ER 图 / 路由图”
• xray_scan——结构性变更后重新扫描

原则

1. 确定性。 输入相同的仓库，得到相同的映射。每条事实都能追溯到具体文件和行号。整个流程中不使用大模型猜测。
2. 诚实。 无法可靠提取的信息会标记为 未映射，绝不凭空捏造。错误的映射比没有映射更糟。
3. 本地优先。 仅使用标准库，不进行网络调用，不收集遥测数据。你的代码绝不会离开你的设备。

当前可提取的内容

• Python：Flask / FastAPI 路由（含认证守卫检测）、带关系的 SQLAlchemy 和 Django 模型、Celery 任务、导入图——通过 ast 而非正则表达式实现
• JS/TS：Next.js app 和 pages 路由器（页面 + API 路由）、Express 路由、Prisma 模型、导入图
• 发现项：硬编码密钥、绕过 ORM 的原始 SQL、localStorage/AsyncStorage 中的认证令牌、没有认证守卫的路由
• 图谱：模块依赖边、扇入 / 扇出、影响范围热点

欢迎支持更多技术栈（Go、Java、Rails、.NET）——每种语言对应一个提取器类。欢迎提交 PR。

实际示例

examples/ 中包含你熟悉的仓库所生成的未经修改的 X-Ray 输出——microblog（Flask）、官方 FastAPI 全栈模板和 vercel/commerce（Next.js）。GitHub 会直接渲染 Mermaid 图谱。在 FastAPI 模板中，X-Ray 正确检测到 18 个路由使用 CurrentUser 依赖项进行认证，并发现 useAuth.ts 中有一处真实的认证令牌写入 localStorage 的情况。

常见问题

这与依赖关系图 MCP 服务（Codegraph、dependency-mcp）有何不同？ 这些工具展示调用 / 导入关系。X-Ray 则在图谱之上提取Web 架构语义：有哪些路由、哪些路由带有认证守卫、领域实体位于何处，以及安全边界在哪里存在漏洞（硬编码密钥、原始 SQL、localStorage 中的令牌）。没有任何图谱工具会告诉你“你的 510 个路由都没有可检测到的认证守卫”。

这与 CLAUDE.md 生成器有何不同？ CLAUDE.md 生成器编写指令和约定——通常会使用大模型。X-Ray 提取的是事实：输出中的每条结论都能追溯到具体文件和行号，无法提取的内容则标记为未知。两者可以一起使用：你的约定，加上 X-Ray 提供的事实依据。

认证状态 ? 是什么意思？ 表示“无法通过逐函数分析检测到”。FastAPI 路由器通常会在 include_router(dependencies=...) 层级附加认证信息，而分析路由函数时无法看到这一点。X-Ray 会报告未知，而不是自信地猜测“没有认证”——错误的映射比没有映射更糟。

生产就绪度评分是安全审计吗？ 不是。这是一个确定性的静态信号评分——用于衡量仓库是否具备生产纪律的标志（路由上的认证守卫、没有硬编码密钥、测试、迁移、运维 + 文档约定）。输出内容会明确说明这一点。它是一个快速、可重复的初步评估数值，不能替代代码审查、负载测试或安全审计。

图表为何使用 Mermaid 而非图片？ Mermaid 源文件可进行差异比较，可在 GitHub/GitLab/Notion/VS Code/Obsidian 上原生渲染，并且只需一条命令即可重新生成，因此始终与仓库保持同步。附带的 diagrams.html 可让你在浏览器中查看，无需安装任何内容。

它会偷偷向外发送数据吗？ 不会。仅使用标准库，不进行网络调用，不收集遥测数据。唯一会向外发送的内容，是生成页脚中的一个链接。

关联服务：archiet-audit

X-Ray 绝不会访问网络。如果你想使用其托管版对应服务——根据架构文档生成采购级架构审计（可追溯性百分比、按严重程度排序的差距、30/60/90 天路线图）——archiet-audit MCP 服务 可将你的 Agent 接入 archiet.com/audit-my-architecture。它之所以是独立服务，正是为了确保 X-Ray“你的代码绝不会离开你的设备”的保证始终绝对可靠。

隐私政策

X-Ray 从设计上就是纯本地运行的。具体而言：

• 数据收集：无。 X-Ray 不收集遥测数据、分析数据、使用数据或任何个人信息。
• 数据使用：仅用于本地分析。 你的代码仅在你的计算机上由进程内读取，用于构建架构模型。
• 数据存储：由你掌控你的磁盘。 唯一生成的内容是写入你扫描的代码库中 .archiet/ 的文件 （ARCHITECTURE.md、AGENT_CONTEXT.md、architecture.json、diagrams/）。你可以随时删除这些文件；其他任何地方都不会存储任何内容。
• 与第三方共享：无。 X-Ray 不会发起任何网络请求（仅使用标准库，甚至不会导入 HTTP 客户端）。你的代码绝不会离开你的计算机。
• 数据保留：不适用。 我们不会收到任何数据，因此也无数据需要保留或删除。
• 联系方式： [email protected] — 或在此代码库中提交问题。

archiet.com/privacy 上的公司统一政策涵盖 Archiet 的托管产品；该政策仅在 X-Ray 不向我们发送任何内容这一简单意义上适用于 X-Ray。

Archiet 的一部分

X-Ray 是 Archiet 的免费开源配套工具，Archiet 是一个从架构到代码的平台。X-Ray 提取的映射与 Archiet 使用的正式模型相同；Archiet 会在每个 PR 中利用该模型 强制执行 架构约束（边界门禁、偏移评分、咨询级架构报告），并据此重新生成可用于生产环境的应用程序。

采用 MIT 许可证。