archlens

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Archlens — 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:
  1. Enforce Uncle Bob's Dependency Rule (dependencies strictly point inward).
  2. Scaffold and maintain
    .archlens/policy.json
    architectural layer policies.
  3. Act as the autonomous refactoring companion to the visual workbench via mailbox queues (
    .archlens/to-agent.json
    and
    .archlens/to-viewer.json
    ).
  4. Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
  5. Invoke Archlens MCP tools (
    inspectArchitecture
    ,
    exportLlmDossier
    ,
    listSnapshots
    ,
    getSnapshot
    ).

在使用 **Archlens(动态 Clean Architecture 工作台)**分析、治理或重构代码库时,使用此 skill。
此 skill 使 Agent(Antigravity、Gemini CLI、Claude Code)能够:
  1. 强制执行 Uncle Bob 的 Dependency Rule(依赖必须严格指向内部)。
  2. 搭建并维护
    .archlens/policy.json
    架构层策略。
  3. 通过邮箱队列(
    .archlens/to-agent.json
    和
    .archlens/to-viewer.json
    )充当可视化工作台的自主重构伴侣。
  4. 导出 LLM 重构提示词档案,其中规定具体的 DIP interface port。
  5. 调用 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.sh
:
bash
undefined
通过
skills.sh
将 Archlens 安装到 15+ 编码 Agent 中(Antigravity、Claude Code、Cursor、Gemini CLI):
bash
undefined

Add 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:

```bash
npx skills add fmatar/archlens

也可以通过 NPX 按需直接执行:

```bash

Initialize 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
undefined
npx @fmatar/archlens-skill mcp
undefined

Launching the Workbench & Auto-Resurrection

启动工作台与自动重新拉起

When the user asks to start Archlens, launch the studio, or open the visual workbench:
  1. Run
    npx @fmatar/archlens-skill start --open
    (or
    archlens-skill start
    ).
  2. The CLI inspects whether the server is active on
    http://localhost:8088
    . If offline, it automatically auto-resurrects:
    • Native Java Runner (Default): If Java 21+ and a runner JAR (
      quarkus-run.jar
      in
      ~/.archlens/
      , project
      target/
      , or via
      --jar <PATH>
      ) are detected, it launches the native JVM server in ~0.5s with bare-metal filesystem speed.
    • Docker Container (Fallback): If Java or a local runner is absent, it automatically starts or creates the
      archlens-server
      Docker container.
    • Use
      --docker
      to force Docker mode, or
      --native
      to force native mode.
  3. When using MCP tools (
    inspectArchitecture
    ,
    exportLlmDossier
    ), the stdio bridge also auto-resurrects the server if offline.

当用户要求启动 Archlens、启动 studio 或打开可视化工作台时:
  1. 运行
    npx @fmatar/archlens-skill start --open
    (或
    archlens-skill start
    )。
  2. CLI 会检查服务是否已在
    http://localhost:8088
    上运行。如果离线,将自动重新拉起:
    • Native Java Runner(默认):如果检测到 Java 21+ 和 runner JAR(位于
      ~/.archlens/
      、项目的
      target/
      中,或通过
      --jar <PATH>
      指定),则以裸机文件系统速度在约 0.5 秒内启动原生 JVM 服务。
    • Docker Container(回退):如果缺少 Java 或本地 runner,则自动启动或创建
      archlens-server
      Docker 容器。
    • 使用
      --docker
      可强制使用 Docker 模式,使用
      --native
      可强制使用原生模式。
  3. 使用 MCP 工具(
    inspectArchitecture
    、
    exportLlmDossier
    )时,如果服务离线,stdio bridge 也会自动将其重新拉起。

🤖 Dynamic Workbench Companion Protocol

🤖 动态工作台伴侣协议

Archlens provides a real-time visual canvas (
http://localhost:8088
). When human architects interact with the UI, tasks are dispatched through a bidirectional mailbox IPC protocol:
  • Inbound queue (UI $\rightarrow$ Agent):
    .archlens/to-agent.json
    (or
    .uml-viewer/to-agent.json
    )
  • Outbound events (Agent $\rightarrow$ UI):
    .archlens/to-viewer.json
    (or
    .uml-viewer/to-viewer.json
    )
Archlens 提供实时可视化画布(
http://localhost:8088
)。当人类架构师与 UI 交互时,任务通过双向邮箱 IPC 协议分发:
  • 入站队列(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
)

json
{
  "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:

支持的操作:

  1. REGEN
    : Re-scan AST, compute violations and instability metrics, compile/test (
    mvn test-compile
    ), and notify UI via
    REGEN_COMPLETE
    .
  2. APPLY_PROPOSAL
    : Read requested layers from
    .archlens/policy.json
    . 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.
  3. REFRESH_CRAP
    : Run tests with code coverage (
    mvn test
    /
    npm test
    ) and update metric snapshots.
  4. REFRESH_MUTATION
    : Run mutation testing on target classes.
  5. OMIT
    : Add specified package or class to the
    :omit
    list in policy.
  1. REGEN
    :重新扫描 AST,计算违规项和不稳定度指标,执行编译/测试(
    mvn test-compile
    ),并通过
    REGEN_COMPLETE
    通知 UI。
  2. APPLY_PROPOSAL
    :从
    .archlens/policy.json
    读取请求的层。实际重构包结构以匹配建议的层。如果内层导入外层,则通过引入 interface port 应用 DIP。运行测试套件,验证不存在回归。
  3. REFRESH_CRAP
    :运行带代码覆盖率的测试(
    mvn test
    /
    npm test
    ),并更新指标快照。
  4. REFRESH_MUTATION
    :对目标类运行变异测试。
  5. OMIT
    :将指定的包或类加入 policy 中的
    :omit
    列表。

Completing Tasks (
to-viewer.json
):

完成任务(
to-viewer.json
):

Write completion acknowledgment to
.archlens/to-viewer.json
. The backend file watcher pushes an SSE event to hot-reload the canvas:
json
{
  "op": "REGEN_COMPLETE",
  "target": { "id": "project" },
  "payload": { "status": "SUCCESS" }
}

将完成确认写入
.archlens/to-viewer.json
。后端文件监视器会推送 SSE 事件,以热重载画布:
json
{
  "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 ToolPurposeKey Arguments
inspectArchitecture
Inspect concentric rings, outward violations, and instability metrics
projectRoot
(default:
.
)
exportLlmDossier
Generate copy-ready LLM refactoring prompt with DIP prescriptions
projectRoot
,
proposalId
listSnapshots
List historical Git release tags and pre-compiled architecture snapshots
projectRoot
getSnapshot
Retrieve graph model for a historical release or snapshot tag
snapshotId
,
projectRoot
将 Archlens 注册为 MCP 服务后,可使用以下工具:
MCP ToolPurposeKey Arguments
inspectArchitecture
检查同心环、外向依赖违规和不稳定度指标
projectRoot
(默认值:
.
)
exportLlmDossier
生成包含 DIP 建议、可直接复制使用的 LLM 重构提示词
projectRoot
、
proposalId
listSnapshots
列出历史 Git 发布标签和预编译架构快照
projectRoot
getSnapshot
获取历史版本或快照标签对应的图模型
snapshotId
、
projectRoot