archlens
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseArchlens — Clean Architecture Governance & Workbench Companion
Archlens — Clean Architecture 治理与工作台伴侣
Use this skill when analyzing, governing, or refactoring codebases using Archlens (Dynamic Clean Architecture Workbench).
This skill equips agents (Antigravity, Gemini CLI, Claude Code) to:
- Enforce Uncle Bob's Dependency Rule (dependencies strictly point inward).
- Scaffold and maintain architectural layer policies.
.archlens/policy.json - Act as the autonomous refactoring companion to the visual workbench via mailbox queues (and
.archlens/to-agent.json)..archlens/to-viewer.json - Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
- Invoke Archlens MCP tools (,
inspectArchitecture,exportLlmDossier,listSnapshots).getSnapshot
在使用 **Archlens(动态 Clean Architecture 工作台)**分析、治理或重构代码库时,使用此 skill。
此 skill 使 Agent(Antigravity、Gemini CLI、Claude Code)能够:
- 强制执行 Uncle Bob 的 Dependency Rule(依赖必须严格指向内部)。
- 搭建并维护 架构层策略。
.archlens/policy.json - 通过邮箱队列(和
.archlens/to-agent.json)充当可视化工作台的自主重构伴侣。.archlens/to-viewer.json - 导出 LLM 重构提示词档案,其中规定具体的 DIP interface port。
- 调用 Archlens MCP 工具(、
inspectArchitecture、exportLlmDossier、listSnapshots)。getSnapshot
🏛️ Clean Architecture Concentric Layer Hierarchy
🏛️ Clean Architecture 同心层层级
Archlens models codebases as concentric circular rings. Source code dependencies (imports, inheritance, calls) MUST point strictly inward:
[Level 3: Infrastructure / Web / DB / CLI]
│
▼
[Level 2: Adapters / Controllers / Presenters / Gateways]
│
▼
[Level 1: Application / Use Cases / Ports]
│
▼
[Level 0: Domain Core / Entities / Value Objects]- Level 0 (Domain Core): Pure business entities, primitives, domain logic. Zero outward imports or dependencies on frameworks, databases, or UI.
- Level 1 (Application): Use cases, interaction orchestrators, domain ports. Depends only on Domain Core (Level 0).
- Level 2 (Adapters): HTTP controllers, presenters, REST resources, repository implementations. Translates between external formats and application models.
- Level 3 (Infrastructure): Web frameworks, databases, persistence drivers, third-party libraries, CLI entrypoints, configuration.
[!IMPORTANT] Dependency Inversion Principle (DIP): When an inner layer (e.g. Domain or Application) needs a service provided by an outer layer (e.g. Database or External API), declare an interface port in the inner layer. Implement the interface in the outer layer (Adapter), and inject it.
Archlens 将代码库建模为同心圆环。源代码依赖(导入、继承和调用)必须严格指向内部:
[Level 3: Infrastructure / Web / DB / CLI]
│
▼
[Level 2: Adapters / Controllers / Presenters / Gateways]
│
▼
[Level 1: Application / Use Cases / Ports]
│
▼
[Level 0: Domain Core / Entities / Value Objects]- Level 0(Domain Core):纯业务实体、基元类型和领域逻辑。不得向外部导入任何内容,也不得依赖框架、数据库或 UI。
- Level 1(Application):Use Case、交互编排器和 Domain Port。仅依赖 Domain Core(Level 0)。
- Level 2(Adapters):HTTP Controller、Presenter、REST Resource 和 Repository 实现。在外部格式与应用模型之间进行转换。
- Level 3(Infrastructure):Web 框架、数据库、持久化驱动、第三方库、CLI 入口点和配置。
[!IMPORTANT] Dependency Inversion Principle (DIP):当内层(例如 Domain 或 Application)需要由外层(例如 Database 或 External API)提供的服务时,应在内层声明一个 interface port。在外层(Adapter)中实现该接口并进行注入。
⚡ CLI & Quickstart Commands
⚡ CLI 与快速入门命令
Install Archlens across 15+ coding agents (Antigravity, Claude Code, Cursor, Gemini CLI) via :
skills.shbash
undefined通过 将 Archlens 安装到 15+ 编码 Agent 中(Antigravity、Claude Code、Cursor、Gemini CLI):
skills.shbash
undefinedAdd Archlens to your active agent skills library:
Add Archlens to your active agent skills library:
npx skills add fmatar/archlens
Or execute directly on demand via NPX:
```bashnpx skills add fmatar/archlens
也可以通过 NPX 按需直接执行:
```bashInitialize Clean Architecture policy in target project:
Initialize Clean Architecture policy in target project:
npx @fmatar/archlens-skill --path . --yes
npx @fmatar/archlens-skill --path . --yes
Launch Workbench container (auto-resurrects on demand if stopped or killed):
Launch Workbench container (auto-resurrects on demand if stopped or killed):
npx @fmatar/archlens-skill start --open
npx @fmatar/archlens-skill start --open
Export Clean Architecture LLM Refactoring Prompt Dossier:
Export Clean Architecture LLM Refactoring Prompt Dossier:
npx @fmatar/archlens-skill prompt --path .
npx @fmatar/archlens-skill prompt --path .
Copy LLM refactoring prompt directly to system clipboard:
Copy LLM refactoring prompt directly to system clipboard:
npx @fmatar/archlens-skill prompt --path . --copy
npx @fmatar/archlens-skill prompt --path . --copy
Synchronize policy with newly added packages:
Synchronize policy with newly added packages:
npx @fmatar/archlens-skill update --path .
npx @fmatar/archlens-skill update --path .
Migrate legacy .uml-viewer configuration to modern .archlens layout:
Migrate legacy .uml-viewer configuration to modern .archlens layout:
npx @fmatar/archlens-skill upgrade --path .
npx @fmatar/archlens-skill upgrade --path .
Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
npx @fmatar/archlens-skill --mcp
npx @fmatar/archlens-skill --mcp
Launch Model Context Protocol (MCP) stdio server:
Launch Model Context Protocol (MCP) stdio server:
npx @fmatar/archlens-skill mcp
undefinednpx @fmatar/archlens-skill mcp
undefinedLaunching the Workbench & Auto-Resurrection
启动工作台与自动重新拉起
When the user asks to start Archlens, launch the studio, or open the visual workbench:
- Run (or
npx @fmatar/archlens-skill start --open).archlens-skill start - The CLI inspects whether the server is active on . If offline, it automatically auto-resurrects:
http://localhost:8088- Native Java Runner (Default): If Java 21+ and a runner JAR (in
quarkus-run.jar, project~/.archlens/, or viatarget/) are detected, it launches the native JVM server in ~0.5s with bare-metal filesystem speed.--jar <PATH> - Docker Container (Fallback): If Java or a local runner is absent, it automatically starts or creates the Docker container.
archlens-server - Use to force Docker mode, or
--dockerto force native mode.--native
- Native Java Runner (Default): If Java 21+ and a runner JAR (
- When using MCP tools (,
inspectArchitecture), the stdio bridge also auto-resurrects the server if offline.exportLlmDossier
当用户要求启动 Archlens、启动 studio 或打开可视化工作台时:
- 运行 (或
npx @fmatar/archlens-skill start --open)。archlens-skill start - CLI 会检查服务是否已在 上运行。如果离线,将自动重新拉起:
http://localhost:8088- Native Java Runner(默认):如果检测到 Java 21+ 和 runner JAR(位于 、项目的
~/.archlens/中,或通过target/指定),则以裸机文件系统速度在约 0.5 秒内启动原生 JVM 服务。--jar <PATH> - Docker Container(回退):如果缺少 Java 或本地 runner,则自动启动或创建 Docker 容器。
archlens-server - 使用 可强制使用 Docker 模式,使用
--docker可强制使用原生模式。--native
- Native Java Runner(默认):如果检测到 Java 21+ 和 runner JAR(位于
- 使用 MCP 工具(、
inspectArchitecture)时,如果服务离线,stdio bridge 也会自动将其重新拉起。exportLlmDossier
🤖 Dynamic Workbench Companion Protocol
🤖 动态工作台伴侣协议
Archlens provides a real-time visual canvas (). When human architects interact with the UI, tasks are dispatched through a bidirectional mailbox IPC protocol:
http://localhost:8088- Inbound queue (UI $\rightarrow$ Agent): (or
.archlens/to-agent.json).uml-viewer/to-agent.json - Outbound events (Agent $\rightarrow$ UI): (or
.archlens/to-viewer.json).uml-viewer/to-viewer.json
Archlens 提供实时可视化画布()。当人类架构师与 UI 交互时,任务通过双向邮箱 IPC 协议分发:
http://localhost:8088- 入站队列(UI $\rightarrow$ Agent):(或
.archlens/to-agent.json).uml-viewer/to-agent.json - 出站事件(Agent $\rightarrow$ UI):(或
.archlens/to-viewer.json).uml-viewer/to-viewer.json
Mailbox Format (to-agent.json
)
to-agent.json邮箱格式(to-agent.json
)
to-agent.jsonjson
{
"nextId": 2,
"queue": [
{
"id": 1,
"op": "REGEN",
"target": { "id": "project" },
"payload": {}
}
]
}json
{
"nextId": 2,
"queue": [
{
"id": 1,
"op": "REGEN",
"target": { "id": "project" },
"payload": {}
}
]
}Supported Operations:
支持的操作:
- : Re-scan AST, compute violations and instability metrics, compile/test (
REGEN), and notify UI viamvn test-compile.REGEN_COMPLETE - : Read requested layers from
APPLY_PROPOSAL. Physically restructure packages to match proposed layers. Where inner layers import outer layers, apply DIP by introducing interface ports. Run test suite to verify zero regressions..archlens/policy.json - : Run tests with code coverage (
REFRESH_CRAP/mvn test) and update metric snapshots.npm test - : Run mutation testing on target classes.
REFRESH_MUTATION - : Add specified package or class to the
OMITlist in policy.:omit
- :重新扫描 AST,计算违规项和不稳定度指标,执行编译/测试(
REGEN),并通过mvn test-compile通知 UI。REGEN_COMPLETE - :从
APPLY_PROPOSAL读取请求的层。实际重构包结构以匹配建议的层。如果内层导入外层,则通过引入 interface port 应用 DIP。运行测试套件,验证不存在回归。.archlens/policy.json - :运行带代码覆盖率的测试(
REFRESH_CRAP/mvn test),并更新指标快照。npm test - :对目标类运行变异测试。
REFRESH_MUTATION - :将指定的包或类加入 policy 中的
OMIT列表。:omit
Completing Tasks (to-viewer.json
):
to-viewer.json完成任务(to-viewer.json
):
to-viewer.jsonWrite completion acknowledgment to . The backend file watcher pushes an SSE event to hot-reload the canvas:
.archlens/to-viewer.jsonjson
{
"op": "REGEN_COMPLETE",
"target": { "id": "project" },
"payload": { "status": "SUCCESS" }
}将完成确认写入 。后端文件监视器会推送 SSE 事件,以热重载画布:
.archlens/to-viewer.jsonjson
{
"op": "REGEN_COMPLETE",
"target": { "id": "project" },
"payload": { "status": "SUCCESS" }
}🛠️ MCP Tool Suite Reference
🛠️ MCP 工具套件参考
When Archlens is registered as an MCP server, use the following tools:
| MCP Tool | Purpose | Key Arguments |
|---|---|---|
| Inspect concentric rings, outward violations, and instability metrics | |
| Generate copy-ready LLM refactoring prompt with DIP prescriptions | |
| List historical Git release tags and pre-compiled architecture snapshots | |
| Retrieve graph model for a historical release or snapshot tag | |
将 Archlens 注册为 MCP 服务后,可使用以下工具:
| MCP Tool | Purpose | Key Arguments |
|---|---|---|
| 检查同心环、外向依赖违规和不稳定度指标 | |
| 生成包含 DIP 建议、可直接复制使用的 LLM 重构提示词 | |
| 列出历史 Git 发布标签和预编译架构快照 | |
| 获取历史版本或快照标签对应的图模型 | |