architectos

---

严格的产品准则：ArchitectOS 绝不会直接修改用户代码；它只会进行分析、解释、计算影响并生成可执行的重构计划。代码修改由 AI Agent 或开发者执行。

---

⚡ 快速入门与核心命令

# 1. Initialize and review repository
npx architectos

# 2. High-level repository health, security & UI review (with optional CI threshold)
architectos review
architectos review --threshold 80

# 3. Component deep-dive (supports --why, --ui, --dead, --duplication, --taint)
architectos analyze toolbar.tsx
architectos analyze toolbar.tsx --why
architectos analyze --ui
architectos analyze --dead
architectos analyze --duplication
architectos analyze --taint auth.controller.ts

# 4. View historical score timeline and trend
architectos history

# 5. Cross-graph downstream change impact & risk rating
architectos impact auth.ts

# 6. Structured refactoring migration plan
architectos plan toolbar.tsx

# 7. Symbol resolver & natural language architecture query
architectos resolve WorkspaceRepository
architectos resolve "Where is tenant isolation enforced?"

# 8. Native MCP server gateway & live watcher
architectos watch
architectos mcp

---

🏛️ ArchitectOS 工作流

architectos review               # High-level health & problem breakdown (--threshold 80)
      ↓
architectos analyze <target>     # Deep-dive (--why, --ui, --dead, --duplication, --taint)
      ↓
architectos impact <target>      # Cross-graph downstream change risk
      ↓
architectos plan <target>        # Step-by-step refactoring migration plan
      ↓
architectos resolve <symbol>     # Hallucination shield & symbol resolver
      ↓
architectos history              # Historical score timeline & trend tracking
      ↓
AI Agent / Developer executes refactor

---

🎯 引擎精度与准确性功能

• 映射至 25 种 CWE 的 SAST 引擎：高精度规则涵盖 SQLi、XSS、RCE、ReDoS、原型污染、NoSQLi、开放重定向、不安全反序列化和弱加密。
• 上下文感知噪声过滤器：自动抑制测试代码块（describe/it）、JSDoc 注释、无效条件分支中的误报，以及检测到已知净化器（DOMPurify、escapeHtml）时的误报。
• 多文件污点追踪引擎：跨多文件导入图，追踪不可信用户输入（HTTP req.body/searchParams）直至危险的执行接收点。
• 代码重复扫描器：基于词元指纹的 Jaccard 相似度引擎，可检测单体仓库各软件包中的复制粘贴代码块。
• 框架入口白名单：消除 Next.js（GET、POST、generateMetadata、middleware）、Remix、Vitest 和 CLI 入口的误报。
• Tarjan SCC 循环检测：以数学上可靠的方式检测复杂单体仓库中的循环依赖。
• 评分透明公开：SCORING.md 中完整记录了公式和扣分规则。

---

🧪 真实场景基准验证（v1.2.1 引擎细分评分）

ArchitectOS 经历了实战检验，并在多个主要开源代码库中用于自身项目治理，各项子指标评分公开透明：

代码仓库	文件数	总分	架构	安全	质量	AI	UI	扫描速度	重点关注领域
excalidraw/excalidraw	520+	88/100	92	84	90	94	80	<18ms	Canvas 组件拆分
calcom/cal.com	1,400+	84/100	80	88	82	90	80	<45ms	预约服务层隔离
shadcn/ui	120+	96/100	98	95	96	95	96	<8ms	UI 组件原语边界
cgseyhan/architectos	51	100/100	100	100	100	100	不适用	<19ms	原生可自托管 AST 治理

注意：纯 CLI / 后端代码仓库（例如 architectos）不包含 UI 架构评分。

---

🤖 原生 MCP 服务集成

将 ArchitectOS 添加到 Claude Code、Cursor 或 Codex 的 MCP 配置中：

{
  "mcpServers": {
    "architectos": {
      "command": "npx",
      "args": ["-y", "architectos", "mcp"]
    }
  }
}

已注册的 MCP 工具

• architectos_review：代码仓库健康状况与问题细分。
• architectos_why：耦合根因分析。
• architectos_impact：多语言变更影响计算器。
• architectos_plan：分步骤迁移重构计划。
• architectos_resolve：符号解析器与幻觉防护。
• architectos_dead：未使用导出与僵尸代码检测器。
• architectos_ui：框架无关的 UI 组件组合与边界审查。
• architectos_remember：存储持久化的架构防护规则。

---

📄 许可证

MIT 许可证 © 2026 ArchitectOS 作者