代码工具
AggRoot 的代码工具插件提供代码执行、验证、格式化、分析、重构等能力，集成了 CodeEngine 代码引擎和 ESLint 静态检查。
CodeExecute — 执行代码
在沙盒中执行 JavaScript 代码，用于运行测试、脚本或验证逻辑。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 否* | 要执行的 JavaScript 代码 |
| file | string | 否* | 要执行的文件路径（与 code 二选一） |
| timeout | number | 否 | 超时秒数（默认 30，最大 120） |
*code 和 file 至少提供一个。
功能特性
- 使用 Node.js 执行代码
- 超时自动终止进程（含子进程树清理）
- 输出限制 10000 字符，防止大量输出占用上下文
示例
// 执行代码片段
CodeExecute({"code": "const result = [1,2,3].map(x => x * 2); console.log(result);"})
// 执行文件
CodeExecute({"file": "test/unit.test.js", "timeout": 60})
// 验证逻辑
CodeExecute({"code": "function fib(n) { return n <= 1 ? n : fib(n-1) + fib(n-2); } console.log(fib(10));"})
注意事项
- 风险等级为 dangerous，执行前需确认
- 代码在独立进程中运行，可访问本地文件系统
- 不适合长时间运行的任务（最大 120 秒超时）
CodeValidate — 验证代码
使用 TypeScript 编译器（tsc --noEmit）进行类型检查，报告真实的类型错误。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 否* | 要验证的文件路径 |
| code | string | 否* | 要验证的代码字符串（与 path 二选一） |
*path 和 code 至少提供一个。
功能特性
- 使用项目中的
tsconfig.json配置 - 自动向上查找最近的
tsconfig.json - 支持代码字符串验证（临时写入文件后检查）
- 30 秒超时保护
- 输出过滤：优先显示目标文件相关的错误
示例
// 验证项目文件
CodeValidate({"path": "src/app.ts"})
// 验证代码片段
CodeValidate({"code": "const x: string = 123;"})
输出说明
- 验证通过：返回 "TypeScript validation passed — no type errors found"
- 验证失败：显示错误数量、警告数量及详细错误信息
CodeFormat — 格式化代码
格式化 TypeScript、JavaScript、JSON 等文件，内置缩进修复。
参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| path | string | 否* | — | 要格式化的文件路径 |
| code | string | 否* | — | 要格式化的代码字符串（与 path 二选一） |
| write | boolean | 否 | false | 是否将格式化结果写回文件 |
| indent | number | 否 | 2 | 缩进空格数 |
*path 和 code 至少提供一个。
示例
// 预览格式化结果（不写回）
CodeFormat({"path": "src/messy.ts"})
// 格式化并写回文件
CodeFormat({"path": "src/messy.ts", "write": true})
// 自定义缩进
CodeFormat({"path": "src/style.ts", "write": true, "indent": 4})
// 格式化代码字符串
CodeFormat({"code": "function test(){return 1;}"})
CodeAnalyze — 分析代码
深度分析代码文件，提取符号信息、依赖关系、ESLint 问题。
参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| path | string | 是 | — | 要分析的文件路径 |
| includeComplexity | boolean | 否 | true | 是否包含复杂度指标 |
分析结果
| 类别 | 说明 |
|---|---|
| 文件信息 | 行数、字符数 |
| 导入（Imports） | 导入的模块路径列表 |
| 导出（Exports） | 导出的符号列表 |
| 函数（Functions） | 函数名列表（使用 CodeEngine 提取） |
| 类（Classes） | 类名列表 |
| 问题（Issues） | ESLint 检测到的错误和警告 |
示例
// 分析文件
CodeAnalyze({"path": "src/domain/agent/aggregate.ts"})
// 不含复杂度分析
CodeAnalyze({"path": "src/utils.ts", "includeComplexity": false})
技巧
- 优先使用 CodeEngine 提取符号（更准确），不可用时回退到正则匹配
- ESLint 超时 30 秒后自动回退到简单检查（console.log、TODO/FIXME 等）
- 分析结果包含问题严重等级和规则名，便于定位修复
CodeRefactor — 重构代码
支持多种重构操作，集成 CodeEngine 语义感知重构。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| operation | string | 是 | 重构操作类型 |
| path | string | 是 | 目标文件路径 |
操作特定参数见下方各操作说明。
支持的操作
1. extract_function — 提取函数
| 附加参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startLine | number | 是 | 起始行号（0-based） |
| endLine | number | 是 | 结束行号（exclusive） |
| functionName | string | 是 | 新函数名 |
CodeRefactor({
"operation": "extract_function",
"path": "src/handler.ts",
"startLine": 10,
"endLine": 20,
"functionName": "processData"
})
2. rename — 重命名
| 附加参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| oldName | string | 是 | 当前名称 |
| newName | string | 是 | 新名称 |
| symbolKind | string | 否 | 符号类型过滤：function/class/variable/interface/type/all |
CodeRefactor({
"operation": "rename",
"path": "src/app.ts",
"oldName": "oldVar",
"newName": "newVar",
"symbolKind": "variable"
})
重命名逻辑：
- 优先使用 CodeEngine 语义重命名（跨文件安全）
- 回退到安全 Token 重命名（跳过注释和字符串中的匹配）
3. organize_imports — 整理导入
无需额外参数。自动排序 import 语句：第三方模块在前，相对路径在后，同组内按路径排序。
CodeRefactor({
"operation": "organize_imports",
"path": "src/app.ts"
})
4. add_import — 添加导入
| 附加参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| importPath | string | 是 | 导入路径 |
| importName | string | 否 | 导入的符号名 |
// 具名导入
CodeRefactor({
"operation": "add_import",
"path": "src/app.ts",
"importPath": "lodash",
"importName": "debounce"
})
// 副作用导入
CodeRefactor({
"operation": "add_import",
"path": "src/app.ts",
"importPath": "./polyfills"
})
5. remove_unused — 移除未使用的导入
无需额外参数。自动检测并移除文件中未被使用的 import 语句。
CodeRefactor({
"operation": "remove_unused",
"path": "src/app.ts"
})
辅助工具
CodeIndex — 索引项目
为项目目录建立代码索引，启用符号搜索和依赖分析。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | 项目根目录 |
| pattern | string | 否 | 文件 glob 模式（默认 **/*.{ts,tsx,js,jsx}） |
CodeIndex({"path": "/projects/my-app"})
CodeIndex({"path": "/projects/my-app", "pattern": "**/*.py"})
CodeStats — 代码统计
查看当前代码索引的统计信息。无需参数。
CodeStats({})
返回：文件数、符号数、引用数、导入/导出数、索引大小。
CodeDependencies — 依赖分析
分析指定文件的依赖关系和修改影响范围。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | 目标文件路径 |
CodeDependencies({"path": "src/core/engine.ts"})
返回：直接影响文件数、间接影响文件数、风险等级及因素。
工作流集成
代码工具与 WorkflowController 深度集成：
- 事务管理：写操作（Write/Edit/CodeRefactor/CodeFormat）自动纳入事务，失败自动回滚
- 检查点：关键操作后自动创建检查点，支持恢复
- 脏文件追踪：修改后自动标记文件为脏，CodeEngine 下次搜索时增量同步
- 模式检测：根据操作自动切换工作模式（Analysis → Refactor）