enhance-cross-file

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

enhance-cross-file

Analyze cross-file semantic consistency across agents, skills, and workflows.

分析Agent、Skill与工作流（workflow）之间的跨文件语义一致性。

Parse Arguments

解析参数

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';

Purpose

用途

Detects issues that span multiple files - things single-file analysis misses:

Tools used in prompt body but not declared in frontmatter
Agent references that don't exist
Duplicate instructions across files (maintenance burden)
Contradictory rules (ALWAYS vs NEVER conflicts)
Orphaned agents not referenced by any workflow
Skill tool mismatches (allowed-tools vs actual usage)

检测跨多个文件的问题——这些问题是单文件分析无法发现的：

提示词正文中使用的工具未在frontmatter中声明
引用不存在的Agent
跨文件的重复指令（增加维护负担）
矛盾规则（ALWAYS与NEVER冲突）
未被任何工作流引用的孤立Agent
Skill工具不匹配（allowed-tools与实际使用情况不符）

Workflow

工作流程

Run Analyzer - Execute the JavaScript analyzer to get findings:

bash

node -e "const a = require('./lib/enhance/cross-file-analyzer.js'); console.log(JSON.stringify(a.analyze('.'), null, 2));"

For a specific path:

a.analyze('./plugins/enhance')

Parse Results - The analyzer returns JSON with
```
summary
```
and
```
findings
```
Report - Return findings grouped by category

The JavaScript analyzer (

lib/enhance/cross-file-analyzer.js

) implements all cross-file detection. The patterns below are reference documentation.

运行分析器 - 执行JavaScript分析器获取检测结果：

bash

node -e "const a = require('./lib/enhance/cross-file-analyzer.js'); console.log(JSON.stringify(a.analyze('.'), null, 2));"

针对特定路径：

a.analyze('./plugins/enhance')

解析结果 - 分析器返回包含
```
summary
```
和
```
findings
```
的JSON数据
生成报告 - 按类别分组返回检测结果

JavaScript分析器（

lib/enhance/cross-file-analyzer.js

）实现了所有跨文件检测逻辑。以下模式为参考文档。

Detection Patterns

检测模式

1. Tool Consistency (MEDIUM Certainty)

1. 工具一致性（中等确定性）

tool_not_in_allowed_list: Tool used in prompt body but not in frontmatter

tools:

list

yaml

undefined

tool_not_in_allowed_list：提示词正文中使用的工具未出现在frontmatter的

tools:

列表中

yaml

undefined

Frontmatter declares:

Frontmatter声明：

tools: Read, Grep

But body uses:

但正文使用了：

Use Write({ file_path: "/out" }) # <- Not declared!


**skill_tool_mismatch**: Skill's `allowed-tools` doesn't match actual tool usage in skill body

Use Write({ file_path: "/out" }) # <- 未声明！


**skill_tool_mismatch**：Skill的`allowed-tools`与正文中实际使用的工具不匹配

2. Workflow Consistency (MEDIUM Certainty)

2. 工作流一致性（中等确定性）

missing_workflow_agent:

subagent_type: "plugin:agent-name"

references non-existent agent

orphaned_prompt: Agent file exists but no workflow references it (may be entry point - check manually)

incomplete_phase_transition: Workflow phase mentions "Phase N" but no corresponding section

missing_workflow_agent：

subagent_type: "plugin:agent-name"

引用了不存在的Agent

orphaned_prompt：Agent文件存在但未被任何工作流引用（可能是入口点——需手动检查）

incomplete_phase_transition：工作流阶段提及"Phase N"但无对应章节

3. Instruction Consistency (MEDIUM Certainty)

3. 指令一致性（中等确定性）

duplicate_instructions: Same MUST/NEVER instruction in 3+ files (extract to shared location)

contradictory_rules: One file says "ALWAYS X" while another says "NEVER X"

duplicate_instructions：相同的MUST/NEVER指令出现在3个及以上文件中（建议提取到共享位置）

contradictory_rules：一个文件规定"ALWAYS X"而另一个文件规定"NEVER X"

Output Format

输出格式

markdown

undefined

markdown

undefined

Cross-File Analysis

跨文件分析结果

Files Analyzed: {agents} agents, {skills} skills, {commands} commands

分析文件数：{agents}个Agent，{skills}个Skill，{commands}个命令

Tool Consistency ({n})

工具一致性问题（{n}个）

Agent	Issue	Fix
exploration-agent	Uses Write but not in tools list	Add Write to frontmatter

Agent	问题	修复方案
exploration-agent	使用了Write工具但未在列表中声明	将Write添加到frontmatter

Workflow Issues ({n})

工作流问题（{n}个）

Source	Issue	Fix
workflow.md	References nonexistent agent	Check spelling or create agent

来源	问题	修复方案
workflow.md	引用了不存在的Agent	检查拼写或创建对应Agent

Instruction Consistency ({n})

指令一致性问题（{n}个）

Instruction	Files	Fix
"NEVER push --force"	4 files	Extract to CLAUDE.md

undefined

指令	涉及文件	修复方案
"NEVER push --force"	4个文件	提取到CLAUDE.md中

undefined

Constraints

约束条件

All patterns are MEDIUM certainty (require context)
No auto-fix (cross-file changes need human review)
Skip content inside
```
<bad-example>
```
,
```
<bad_example>
```
,
```
<badexample>
```
tags
Skip content inside code blocks with "bad" in info string
Entry point agents (orchestrator, validator, discoverer) are not orphaned

所有检测模式的确定性为中等（需结合上下文判断）
不支持自动修复（跨文件修改需人工审核）
跳过
```
<bad-example>
```
、
```
<bad_example>
```
、
```
<badexample>
```
标签内的内容
跳过信息字符串中包含"bad"的代码块内容
入口点Agent（编排器、验证器、发现器）不属于孤立Agent

Pattern Statistics

模式统计

Category	Patterns	Auto-Fixable
Tool Consistency	2	0
Workflow	3	0
Consistency	3	0
Total	8	0

类别	模式数量	支持自动修复
工具一致性	2	0
工作流	3	0
一致性	3	0
总计	8	0