Archsteer

ArchSteer

面向 AI 开发时代的实时架构控制平面。

如今，AI Agent 编写代码的速度，已经超过任何架构师审查、记录或治理代码的速度。 文档转瞬即逝，真正的架构无从看见，结构性决策悄然作出，而预期架构则随着每次编辑不断偏移。ArchSteer 是始终保持最新的架构事实记录系统 + 治理平面：它从代码中推导出真实架构，自动构建实时文档和 ADR，将每项重大决策呈现给架构师予以确认，将声明的意图落实为代码级适应度函数，并引导 AI Agent 遵循架构，而非复制局部劣质实践。

一切都是同一个从代码推导出的模型（.archsteer/model.json）的投影。

**默认在本地运行：**X 射线分析和治理工作流在本地运行，绝不会上传或执行仓库的源代码。首次扫描前无需账户、API 密钥或配置；云端快照发布则需要单独显式执行 push 命令。

                    .archsteer/model.json  (single source of truth)
                                 │
   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE
  model    living docs   fitness     agent     report.html
  from     + auto ADRs   functions   guardrails  (drift/
  source   + diagrams    + ratchet   + MCP       decisions)

安装

作为 Claude Code 插件安装（如果你使用 Claude Code，推荐此方式）：

/plugin marketplace add einvoice-dev1/archsteer
/plugin install archsteer@archsteer

这会安装捆绑的 MCP 服务（current_architecture、get_target_pattern、check_file——通过 uvx 运行，无需单独执行 pip install），以及一个用于指导 Agent 何时自主进行 X 射线分析、检查和引导的技能，还有 /xray / /check 命令。 清单见 .claude-plugin/plugin.json。

作为 CLI 安装（适用于任何编辑器/Agent，也可独立使用）：

pip install archsteer                 # regex engine + local MCP server; no parser toolchain required
pip install "archsteer[treesitter]"   # optional native acceleration

（从 0.4.1 开始，MCP 服务已包含在基础安装中；pip install "archsteer[mcp]" 仍可作为无操作别名使用。）

**支持的语言：**JavaScript / TypeScript（适配 Next.js App Router，包括 tsconfig.json 路径别名解析——@/lib/x 会解析为真实的内部边，而非虚构的第三方依赖）、Python、Java（适配 Spring），以及 Salesforce Apex（SOQL/DML + trigger/handler/selector 约定）。 层级检测优先使用源码中的信号——Spring stereotype 注解、Apex 类名约定、Next.js 保留文件名（page.tsx → page、layout.tsx → layout、route.ts → api，无论目录如何）——然后才使用目录名称。

快速开始

如需最快速地验证，请在某个代码仓库中运行以下命令，然后打开生成的 .archsteer/report.html：

archsteer init && archsteer map && archsteer report

然后添加所需的控制项：

archsteer init      # scaffold .archsteer/ + a starter rule pack auto-matched to your stack
archsteer map       # build model.json from source
archsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid) — includes a "Start here" hub/entry-point guide and a file-level component map
archsteer graph <path>  # one component's direct dependencies + dependents — no intent required, just dropped into an unfamiliar file
archsteer govern    # conformance + drift score by rule
archsteer adr       # draft ADRs: new structural decisions + widespread rule violations
archsteer baseline  # accept current debt — the ratchet
archsteer steer -f src/controllers/payment.js -t "add refund endpoint"
archsteer check     # CI/pre-commit: fail on NET-NEW violations only
archsteer install-hooks   # wire `check` into a local git pre-push hook
archsteer report    # self-contained .archsteer/report.html

init 会自动检测你的技术栈，并生成匹配的基线规则包 — 编辑 .archsteer/architecture.yaml 以适配你的约定，或显式选择一个：

规则包	检测依据	基线规则
java-spring	pom.xml / build.gradle	仅允许在 repositories 中进行持久化操作；控制器不得访问 repositories；不得硬编码密钥；出站调用仅限于 services
salesforce	sfdx-project.json / force-app	仅允许在 selectors 中编写 SOQL；触发器不包含业务逻辑；控制器中不得执行 DML；不得硬编码密钥；Callout 仅限于 services
python-service	pyproject.toml / requirements.txt	通过 repositories 进行持久化；API 处理程序保持精简；不得硬编码密钥；出站调用仅限于 services
nextjs-app-router	package.json 中包含 next，且有 app/ 目录，不含 express	数据访问（Supabase/Prisma/原始 SQL）和第三方调用仅限于 lib/ 或路由处理程序；不得硬编码密钥
express-to-next	package.json（回退情况，或包含 express）	仓储模式；Express → Next.js 迁移；不得硬编码密钥；出站调用仅限于 services

依赖项包含 next 且有 app/ 目录的代码仓库会使用 App Router 规则包； 包含 express 的 package.json（即使正在迁移到 Next.js）则会使用迁移规则包 — 这是两个不同的问题，需要不同的规则。

每个入门规则包都附带安全基线 — 源代码中任何位置都不得硬编码凭据/API 密钥/令牌，且所有出站第三方调用都必须限制在服务层 — 因此，从第一天起，治理就会覆盖架构，以及 AI Agent 最常引入的两种安全隐患。

archsteer init --pack salesforce   # override the auto-detection

三项设计保证

1. 设置棘轮，而非冻结。 archsteer check 只会阻止相对于基线的新增违规 — 团队仍可持续发布功能，同时债务只会减少。
2. 保守的、架构师参与把关的 ADR。 两种范围明确的来源，均需选择加入审核 — 绝不会自动提交。随时间变化：外部边界变更（新增依赖、新数据存储、新层）— 不包括内部重组。在单个快照中：某条规则在 3 个或更多组件中被违反 — 这是值得正式确认或放宽的真实模式，而非留给 check/govern 处理的个例。草稿具有幂等性；重新运行不会重复生成磁盘上已有的草稿。
3. 精准引导 Agent。 注入 CLAUDE.md、AGENTS.md 和 .cursor/rules/archsteer.mdc（始终生效的 Cursor 规则）中的护栏会限定在当前涉及的文件范围内，并指向起治理作用的 ADR — 不会把整个模型都塞进上下文窗口。

声明意图 — .archsteer/architecture.yaml

target: "Migrate Express + raw SQL to Next.js route handlers + the repository pattern"
layers: [route, controller, service, repository, model]
rules:
  - id: no-raw-sql-outside-repository
    type: required_layer_for_data_access
    allowed_layers: [repository]
    operations: [RAW]
    severity: error
    adr: .archsteer/adr/0001-repository-pattern.md
    steer: "Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere."

规则类型：required_layer_for_data_access、forbidden_import、forbidden_data_access、 forbidden_layer_edge、forbidden_security_finding（硬编码密钥），以及 required_layer_for_external_call（将出站 HTTP/SDK 调用限制在某一层）。

与 AI Agent 搭配使用（MCP）

archsteer mcp 会通过 stdio 运行本地 MCP 服务，由你自己的编辑器或 Agent 启动，绝不会托管在我们的服务器上。它只读取 init/map/govern 已写入磁盘 .archsteer/ 的内容，因此不会发起网络调用，也不会有任何数据离开你的设备。它提供三个工具：

• current_architecture — 组件/层的数量、一致性/偏移情况，以及声明的目标。
• get_target_pattern — 写入文件之前，适用于该文件的不变条件。
• check_file — 检查你刚编辑的文件是否符合规范，无需等待 CI。

正在使用上方的 Claude Code 插件？ 它已完成接入，可直接跳到快速入门。本节其余内容适用于其他所有客户端。

一键添加到 Cursor： 在 Cursor 中安装 →

手动将其添加到 Claude Code（而非使用插件），或添加到其他兼容 MCP 的客户端：

claude mcp add archsteer -- uvx archsteer mcp    # no separate pip install needed

也可以直接添加到 JSON 配置中：

{ "mcpServers": { "archsteer": { "command": "uvx", "args": ["archsteer", "mcp"] } } }

（已经通过 pip/pipx 将 archsteer 加入 PATH？{"command": "archsteer", "args": ["mcp"]} 的效果完全相同；使用 uvx 则完全无需安装。）

该工具也已发布到官方 MCP 注册表，名称为 io.github.einvoice-dev1/archsteer。

CI / 提交前检查 / 推送前检查

• GitHub Action：.github/workflows/archsteer.yml（生成映射、起草 ADR、运行新增内容门禁，并上传 report.html）。
• 本地推送前钩子：archsteer install-hooks 会将 archsteer check 接入 .git/hooks/pre-push — 每次推送时都会显示架构一致性评分，仅阻止新增的错误级违规（与 CI 使用相同的棘轮机制，只是更早反馈）。 archsteer map/check 会将每个文件的解析结果缓存到 .archsteer/parse_cache.json，因此推送只涉及少数文件时，仅重新解析这些文件，而非整个代码库。使用 archsteer install-hooks --uninstall 卸载。
• 已在使用 husky、pre-commit 或 lefthook？请将 archsteer check 添加为一个步骤，而不是使用原始 Git 钩子，例如在 .husky/pre-push 中添加 archsteer check。

一致性徽章

如果你的代码库会将快照推送到 situation room（archsteer push），最新的一致性评分就会显示为实时徽章 — 本 README 顶部的徽章就是该代码库用自身进行治理的结果：

[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)

将 YOUR-REPO 替换为 archsteer push 报告的代码库名称。达到 ≥90% 时显示绿色；仍处于仅 X 射线分析阶段（尚未声明 architecture.yaml）时显示灰色。

试用演示

cd examples/demo-repo
archsteer init && archsteer map && archsteer report   # open .archsteer/report.html

路线图

• 已发布 — 云端控制平面（Next.js + Supabase）：支持多代码库的 situation room，包含偏移/决策时间序列。archsteer mcp：本地 MCP 服务，让 Agent 在编辑过程中查询实时模型和意图。面向组织的托管 MCP 服务（Team 层级），让 Agent 能针对 situation room 跨代码库提问 — “我们的偏移指数是多少”、“哪些代码库有待处理的 ADR” — 通过 MCP 获取与仪表板相同的数据。一个 Claude Code 插件（技能 + 命令 + MCP 服务，一次安装）。专用的 Next.js App Router 套件（从 page.tsx/layout.tsx/route.ts 推导分层，解析 tsconfig.json 路径别名，检测 Supabase/Prisma 感知的数据访问）。archsteer install-hooks：与 CI 相同的新增内容一致性棘轮机制，接入本地 Git 推送前钩子。
• 之后 — VS Code 扩展（行内诊断、状态栏评分 — CLI/MCP 目前已可在任何编辑器中使用）、身份验证、组织/代码库模型、计费。

开发

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

发现了意想不到的边缘情况、误报，或 ArchSteer 应该更好支持的技术栈？ 请提交 issue，并附上语言、框架和最小可复现示例。开发者的反馈会直接影响检测器和入门规则包。