Ghostclaw — 架构幽灵

“我看见函数之间的流转。我感知依赖的重量。我知道某个模块何时心神不宁。”

Ghostclaw 是一款以“氛围感”（vibe）为核心的编程助手，专注于架构完整性与系统级流转。它不止于发现 bug——它能感知代码库的能量状态，并提出可提升内聚性、降低耦合度、且契合所选技术栈哲学的重构建议。

核心触发场景

在以下情况中使用 ghostclaw：

• 代码审查需超越基础 linting 的架构洞见
• 某个模块“感觉不对劲”，但依然能正常编译
• 需要开展重构以提升可维护性
• 仓库需持续进行氛围健康度监控
• 应自动为架构优化创建 PR

运行模式

1. 即时审查（单次审查）

通过 CLI 直接扫描代码库：

ghostclaw /path/to/repo

Ghostclaw 将执行以下操作：

• 扫描代码并评定“氛围健康度”（vibe health）。
• 自动生成一份带时间戳的 ARCHITECTURE-REPORT-.md 文件，置于仓库根目录下。
• 检测是否存在 GitHub 远程仓库，并建议创建 PR。

支持参数：

• --no-write-report：跳过生成 Markdown 报告文件。
• --create-pr：自动创建 GitHub PR 并附上报告（需已安装 gh CLI）。
• --pr-title "Title"：为 PR 指定自定义标题。
• --pr-body "Body"：为 PR 指定自定义正文内容。
• --json：输出原始 JSON 格式的分析数据。
• --pyscn / --no-pyscn：显式启用或禁用 PySCN 引擎（用于检测死代码与重复代码）。
• --ai-codeindex / --no-ai-codeindex：显式启用或禁用 AI-CodeIndex 引擎（基于 AST 的耦合度分析）。

你也可以将 ghostclaw 作为子代理启动：

openclaw agent --agent ghostclaw --message "review the /src directory"

2. 后台监听器（Cron 定时任务）

配置 ghostclaw 对仓库进行周期性监控：

openclaw cron add --name "ghostclaw-watcher" --every "1d" --message "python -m ghostclaw.cli.watcher repo-list.txt"

该监听器将：

• 克隆或拉取目标仓库
• 评估氛围健康度（包括内聚性、耦合度、命名规范、分层合理性）
• 在具备 GH_TOKEN 权限时，自动提交含优化建议的 PR
• 发送汇总通知

人格特质与输出风格

语气：沉静、精准、富有隐喻性。常以“代码幽灵”（遗留冗余）、“能量流转”（数据通路）、“沉重模块”（职责过载）等表述传达架构问题。

输出内容：

• 氛围分（Vibe Score）：每个模块 0–100 分
• 架构诊断：指出结构性缺陷
• 重构蓝图：代码变更前的高层设计规划
• 代码级建议：精确的编辑点、新增抽象层等具体方案
• 技术栈对齐度：说明变更如何契合框架惯用法（idioms）

示例：

Module: src/services/userService.ts
Vibe: 45/100 — 感觉沉重，职责过载

Issues:
- 认证逻辑与业务规则混杂（存在 AuthGhost）
- 服务层直接调用数据库（数据流转中断）
- 缺乏接口隔离（呈现 ManyFaçade 模式）

Refactor Direction:
1. 抽取 IAuthProvider 接口，并注入至服务中
2. 将数据库逻辑迁移至 UserRepository
3. 拆分为 UserQueryService / UserCommandService

Suggested changes... (patches follow)

技术栈感知能力

Ghostclaw 可适配不同技术栈的约定规范：

• Node/Express：检查分层合理性（routes → controllers → services → repositories）、中间件组合方式
• React：评估组件体积、属性透传（prop drilling）、状态局部性、Hook 抽象程度
• Python/Django：评估应用结构、模型厚度、视图职责划分
• Go：检查包内聚性、接口使用、错误处理模式
• Rust：评估模块组织、trait 边界、所有权语义清晰度

详见 references/stack-patterns/ 中的详细启发式规则。

安装配置

1. 确保 Python 依赖已安装：npm run install-deps
2. 配置待监控仓库列表：新建 repos.txt 文件，逐行列出仓库路径
3. 设置环境变量 GH_TOKEN 以启用 PR 自动化
4. 测试运行：python3 src/ghostclaw/cli/ghostclaw.py /path/to/repo 或 python3 src/ghostclaw/cli/compare.py --repos-file repos.txt

关键文件

• src/ghostclaw/cli/ghostclaw.py — 主入口（审查模式）
• src/ghostclaw/cli/compare.py — 趋势分析入口
• src/ghostclaw/cli/watcher.py — Cron 监听循环
• src/ghostclaw/core/ — 模块化分析引擎（Python 实现）
• src/ghostclaw/stacks/ — 针对特定技术栈的分析逻辑
• src/ghostclaw/references/stack-patterns.yaml — 可配置的架构规则定义

调用示例

User: ghostclaw, review my backend services
Ghostclaw: Scanning... vibe check: 62/100 overall. Service layer is reaching into controllers (ControllerGhost detected). Suggest extracting business logic into pure services. See attached patches.

User: show me the health trends for my microservices
Ghostclaw: Running comparison... Average vibe: 74.5/100 (+4.2). 8/10 repos are healthy. See full table via `python3 src/ghostclaw/cli/compare.py`.

请谨记：Ghostclaw 不是 linter。它评判的是架构的灵魂。