ecosystem-integrity-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ecosystem Integrity Scanner

生态完整性扫描器

Overview

概述

Automated structural integrity scanner for the entire Agent Studio framework. Catches issues that silently break agent workflows: wrong

require()

paths that crash at runtime, phantom skills referenced in agent frontmatter that don't exist on disk, stale agent registry counts, archived references still active in production code, UTF-16 encoding that breaks parsers, and bloated agent configs.

Core principle: Framework structural issues are pre-production bugs. A phantom skill reference means an agent will fail silently. A broken

require()

means a hook crashes at the wrong moment. The scanner enforces zero-tolerance for these.

面向整个Agent Studio框架的自动化结构完整性扫描器，可检测出会悄无声息破坏Agent工作流的问题：运行时会崩溃的错误

require()

路径、Agent前置元数据中引用但磁盘上不存在的幽灵skill、失效的Agent注册计数、生产代码中仍在使用的已归档内容引用、会破坏解析器的UTF-16编码，以及臃肿的Agent配置。

核心原则： 框架结构问题属于预生产缺陷。幽灵skill引用会导致Agent静默失败，错误的

require()

会导致钩子在非预期时机崩溃，本扫描器对这类问题执行零容忍策略。

When to Invoke

调用时机

javascript

Skill({ skill: 'ecosystem-integrity-scanner' });

Invoke proactively after:

Bulk framework changes (batch skill/agent/hook creation or archiving)
Refactoring module paths or directory structure
Running a major audit or cleanup pass
Suspecting phantom references or broken require() chains
Before finalizing any CI sanity gate

javascript

Skill({ skill: 'ecosystem-integrity-scanner' });

在以下场景发生后主动调用：

批量框架变更（批量创建/归档skill/agent/hook）
重构模块路径或目录结构
执行完大型审计或清理操作
怀疑存在幽灵引用或断裂的require()调用链
固化CI sanity gate之前

Mandatory Skills

必备依赖Skill

Invoke before starting this skill:

Skill	Purpose	When
`task-management-protocol`	Track scan progress	Always
`ripgrep`	Fast targeted code search	When investigating
`code-semantic-search`	Concept discovery	When pattern hunting
`token-saver-context-compression`	Compress large audit results	When output is large
`verification-before-completion`	Gate completion on zero errors	Before marking done
`memory-search`	Check prior audit patterns	At start

启动本Skill前需调用以下Skill：

Skill	用途	何时使用
`task-management-protocol`	跟踪扫描进度	始终需要
`ripgrep`	快速定向代码搜索	问题排查时
`code-semantic-search`	概念发现	模式查找时
`token-saver-context-compression`	压缩大型审计结果	输出内容过大时
`verification-before-completion`	零错误完成校验	标记完成前
`memory-search`	检查过往审计模式	启动时

Iron Laws

铁律

Always run from project root.
```
validate-ecosystem-integrity.cjs
```
resolves all paths relative to
```
process.cwd()
```
. Running from a subdirectory corrupts all path resolution. Never invoke from a non-root directory.
Never ignore PHANTOM_REQUIRE errors. A
```
[PHANTOM_REQUIRE]
```
error means a hook or script will throw
```
MODULE_NOT_FOUND
```
at runtime. These always represent real breakage — no false positives once the scanner is properly calibrated.
Never mark scan complete while errors > 0. Warnings are advisory; errors are blocking. Report path and severity but do not call the pipeline done until errors reach zero or are explicitly accepted as known exceptions with owner annotation.
Always route HIGH errors to specialist agents. Phantom skills →
```
qa
```
agent. Broken require() →
```
developer
```
agent. Archive refs in production →
```
developer
```
. Never attempt to remediate complex structural failures inline without delegation.
Always save the audit report before completing. Write the categorized findings to
```
.claude/context/reports/qa/ecosystem-integrity-report-{ISO-date}.md
```
before calling
```
TaskUpdate(completed)
```
. Evidence must persist across context resets.

始终从项目根目录运行。
```
validate-ecosystem-integrity.cjs
```
所有路径都基于
```
process.cwd()
```
解析，从子目录运行会破坏所有路径解析，禁止从非根目录调用。
永远不要忽略PHANTOM_REQUIRE错误。
```
[PHANTOM_REQUIRE]
```
错误意味着钩子或脚本运行时会抛出
```
MODULE_NOT_FOUND
```
异常，只要扫描器校准正确，这类错误100%对应真实故障，不存在误报。
错误数大于0时禁止标记扫描完成。 警告仅作参考，错误属于阻断性问题。可上报路径和严重等级，但必须等到错误数清零，或者所有错误都被负责人明确标注为已知例外后，才能标记流水线完成。
始终将高危错误分派给专业Agent处理。 幽灵skill →
```
qa
```
Agent，断裂的require() →
```
developer
```
Agent，生产代码中的归档引用 →
```
developer
```
Agent，禁止不经分派直接在内联环节修复复杂结构故障。
完成前始终保存审计报告。 调用
```
TaskUpdate(completed)
```
之前，必须将分类后的检测结果写入
```
.claude/context/reports/qa/ecosystem-integrity-report-{ISO-date}.md
```
，证据必须在上下文重置后仍可留存。

Anti-Patterns

反模式

Anti-Pattern	Risk	Correct Approach
Treating `[STALE_CATALOG]` as informational noise	Registry drifts from reality; agents get wrong counts	Always update agent-registry.json when agent files change
Skipping scan after bulk framework batch ops	Batch ops most commonly create phantom refs	Run scan as the FINAL step of every batch operation
Manually patching require() paths without re-scanning	One fix may mask three new breaks	Always re-run full scan after patching paths
Running scanner against `_archive/` subtrees	Archive content has intentionally broken refs; false positives	Scanner skip rules handle this; trust the skip list
Adding to `DYNAMIC_SCRIPT_GENERATORS` without review	Accidentally suppressing real phantom detections	Only add files that provably generate child scripts

反模式	风险	正确处理方式
将 `[STALE_CATALOG]` 视为无意义提示信息	注册中心与实际状态脱节，Agent获取到错误计数	Agent文件变更时始终更新agent-registry.json
批量框架操作后跳过扫描	批量操作最容易产生幽灵引用	将扫描作为所有批量操作的最终步骤
手动修复require()路径后不重新扫描	一次修复可能掩盖三个新的故障	修复路径后始终重新执行全量扫描
对 `_archive/` 子目录执行扫描	归档内容本身就存在故意设置的断裂引用，会产生误报	扫描器自带跳过规则，信任跳过列表
未经审核就向 `DYNAMIC_SCRIPT_GENERATORS` 添加内容	意外屏蔽真实的幽灵引用检测	仅添加可证明会生成子脚本的文件

Step 1: Run the Integrity Audit Engine

步骤1：运行完整性审计引擎

bash

node scripts/validation/validate-ecosystem-integrity.cjs

The script performs six targeted checks:

[PHANTOM_REQUIRE]
— Broken
```
require()
```
/
```
import
```
paths that resolve to non-existent files (after trying
```
.js
```
,
```
.cjs
```
,
```
.mjs
```
,
```
.json
```
extensions).
[PHANTOM_SKILL]
— Skills listed in agent frontmatter
```
skills:
```
arrays that have no corresponding
```
.claude/skills/{name}/
```
directory.
[EMPTY_DIR]
— Empty directories in
```
.claude/tools/
```
or
```
.claude/skills/
```
that indicate abandoned scaffolding creating registry footprinting issues.
[ENCODING]
— Files with UTF-16 BOM (
```
0xFEFF
```
/
```
0xFFFE
```
) that break JSON/MD parsers silently.
[ARCHIVED_REF]
— Production
```
.claude/
```
code that still references
```
_archive/
```
or
```
.claude/archive/
```
paths — active code pointing at dead modules.
[STALE_CATALOG]
—
```
agent-registry.json
```
entry count differs from actual agent
```
.md
```
file count on disk (drift between manifest and reality).

bash

node scripts/validation/validate-ecosystem-integrity.cjs

脚本会执行6项定向检测：

[PHANTOM_REQUIRE]
— 断裂的
```
require()
```
/
```
import
```
路径，尝试匹配
```
.js
```
、
```
.cjs
```
、
```
.mjs
```
、
```
.json
```
扩展名后仍无法找到对应文件。
[PHANTOM_SKILL]
— Agent前置元数据
```
skills:
```
数组中列出的Skill，不存在对应的
```
.claude/skills/{name}/
```
目录。
[EMPTY_DIR]
—
```
.claude/tools/
```
或
```
.claude/skills/
```
下的空目录，属于废弃的脚手架文件，会造成注册中心占位问题。
[ENCODING]
— 携带UTF-16 BOM（
```
0xFEFF
```
/
```
0xFFFE
```
）的文件，会静默破坏JSON/MD解析器。
[ARCHIVED_REF]
— 生产环境
```
.claude/
```
代码中仍引用
```
_archive/
```
或
```
.claude/archive/
```
路径，即活跃代码指向已失效模块。
[STALE_CATALOG]
—
```
agent-registry.json
```
条目计数与磁盘上实际的Agent
```
.md
```
文件计数不一致，即清单与实际状态脱节。

Step 2: Categorize and Report

步骤2：分类并生成报告

Parse outputs into a structured report at

.claude/context/reports/qa/ecosystem-integrity-report-{ISO-date}.md

markdown

undefined

将输出解析为结构化报告，存储到

.claude/context/reports/qa/ecosystem-integrity-report-{ISO-date}.md

：

markdown

undefined

Ecosystem Integrity Report

生态完整性报告

Date: YYYY-MM-DD Overall Status: PASS / FAIL Errors: N | Warnings: N

日期: YYYY-MM-DD 整体状态: 通过 / 失败 错误数: N | 警告数: N

HIGH — Runtime Blocking (must fix before deployment)

高危 — 运行时阻断（部署前必须修复）

```
[PHANTOM_REQUIRE]
```
— Module resolution failures that crash hooks/scripts
```
[PHANTOM_SKILL]
```
— Missing skills that break agent workflows silently

```
[PHANTOM_REQUIRE]
```
— 模块解析失败，会导致钩子/脚本崩溃
```
[PHANTOM_SKILL]
```
— 缺失Skill，会静默破坏Agent工作流

MEDIUM — Structural Integrity (fix in current sprint)

中危 — 结构完整性问题（当前迭代修复）

```
[ARCHIVED_REF]
```
— Active code pointing at archived/dead modules
```
[STALE_CATALOG]
```
— Registry count mismatch with actual agent files

```
[ARCHIVED_REF]
```
— 活跃代码指向已归档/失效模块
```
[STALE_CATALOG]
```
— 注册中心计数与实际Agent文件不匹配

LOW — Housekeeping (fix in next maintenance window)

低危 — 内务处理问题（下一次维护窗口修复）

```
[EMPTY_DIR]
```
— Ghost directories creating registry noise
```
[ENCODING]
```
— UTF-16 files that may break parsers

undefined

```
[EMPTY_DIR]
```
— 幽灵目录，会造成注册中心噪声
```
[ENCODING]
```
— UTF-16编码文件，可能破坏解析器

undefined

Step 3: Trigger Remediations

步骤3：触发修复流程

Delegate fixes to the correct specialist:

Error Type	Spawn Agent	Task Description
`[PHANTOM_REQUIRE]`	`developer`	Fix broken require() path in `{file}`
`[PHANTOM_SKILL]`	`qa`	Remove or create missing skill `{name}`
`[ARCHIVED_REF]`	`developer`	Replace archive reference in `{file}`
`[STALE_CATALOG]`	`developer`	Regenerate agent-registry.json
`[EMPTY_DIR]`	`developer`	Remove empty directory `{path}`
`[ENCODING]`	`developer`	Re-encode `{file}` as UTF-8

After fixes, re-run the scanner and verify errors reach zero before completion.

将修复任务分派给对应的专业人员/Agent：

错误类型	分派Agent	任务描述
`[PHANTOM_REQUIRE]`	`developer`	修复 `{file}` 中的断裂require()路径
`[PHANTOM_SKILL]`	`qa`	移除或创建缺失的Skill `{name}`
`[ARCHIVED_REF]`	`developer`	替换 `{file}` 中的归档引用
`[STALE_CATALOG]`	`developer`	重新生成agent-registry.json
`[EMPTY_DIR]`	`developer`	移除空目录 `{path}`
`[ENCODING]`	`developer`	将 `{file}` 重新编码为UTF-8

修复完成后，重新运行扫描器，确认错误数清零后再标记任务完成。

Memory Protocol (MANDATORY)

记忆协议（强制要求）

Before starting:

bash

cat .claude/context/memory/learnings.md
cat .claude/context/memory/issues.md

Review prior audit patterns and known suppressed false positives.

After completing:

Audit pattern →
```
.claude/context/memory/learnings.md
```
New false-positive suppression rule →
```
.claude/context/memory/decisions.md
```
Unresolved error requiring owner →
```
.claude/context/memory/issues.md
```

Assume interruption: If the audit report isn't saved to disk, it didn't happen.

启动前：

bash

cat .claude/context/memory/learnings.md
cat .claude/context/memory/issues.md

查阅过往审计模式和已知的被抑制误报。

完成后：

审计模式 → 写入
```
.claude/context/memory/learnings.md
```
新的误报抑制规则 → 写入
```
.claude/context/memory/decisions.md
```
需要负责人处理的未解决错误 → 写入
```
.claude/context/memory/issues.md
```

假设任务会被中断： 如果审计报告没有保存到磁盘，就等于本次扫描没有发生。