Galacean Script Agent

脚本代理会读取 Galacean 官方手册与脚本文档、检索 API 索引并定位源码，最终根据用户需求输出需求分析、实现步骤与脚本模板。核心入口是 generateScriptAgent，同时提供 CLI 及 MCP Server 两种使用方式。

功能亮点

• LLM 驱动编排：系统提示要求模型按「文档 → 源码 → 实现」三步执行，并维护已读取的文档/源码集合避免重复调用工具。
• 统一工具层：
  • get_documents：读取 assets/docs/** 中的手册与脚本文档。
  • search_source_code：基于 assets/api/*.json 的索引定位源码路径。
  • get_source_code：读取源码文件内容。
• 脚本产物：输出包含 features、docs、steps、scripts 的 JSON，对应功能模块、参考文档、实施步骤和脚本实现草案。
• 缓存与目录定位：FileReader 会缓存已读文件并可列举目录下的文件，避免磁盘 I/O 重复。

环境要求

• Node.js 18+
• 构建后运行需要以下环境变量或配置文件提供 Galacean AI 接口信息：
  • GALACEAN_AI_KEY
  • GALACEAN_AI_BASE_URL
  • GALACEAN_AI_MODEL

快速开始

npm install
npm run build
# 通过 CLI 生成脚本逻辑
GALACEAN_AI_KEY=xxx \
GALACEAN_AI_BASE_URL=https://example.com/v1 \
GALACEAN_AI_MODEL=glm-4.6 \
node dist/cjs/scripts/run-generate-script-agent.js \
  --requirement "点击屏幕时在点击处生成一个旋转的方块"

会在 outputs/final-config-*.json 写出最终 JSON 结果。

CLI

• 开发环境：npm run generate:tasks -- --requirement "..."（命令会先触发构建）。
• 产物：CommonJS 与 ESM 版本位于 dist/cjs/scripts/run-generate-script-agent.js 与 dist/esm/...。
• npm run build 自动为 CLI 入口增加执行权限。

MCP Server

npm run build
node dist/cjs/integrations/mcp/server.js

启动后可在支持 MCP 的客户端中列出工具并调用：

• get_documents
• search_source_code
• get_source_code
• （如需旧版分析）analyze_requirement

测试与开发

• 清理：npm run clean
• 构建：npm run build
• 单测：npm test（Vitest，当前无测试用例会快速退出）
• 调试 API 索引示例：

  node -e "const { ApiIndex } = require('./dist/cjs/services/ApiIndex.js'); console.log(ApiIndex.ins.search('PointerEventData', 5));"

目录结构概览

• src/agent/：脚本代理主流程（ScriptAgent.ts 等）
• src/pipeline/：脚本生成编排逻辑
• src/tools/：工具包装与对外导出
• src/services/：文档/索引等支撑服务
• src/utils/：共用工具函数
• src/integrations/mcp/：MCP Server 集成
• assets/：手册、脚本文档、API 索引、提示词等资源
• tests/：Vitest 目录（可按需补齐用例）

常见问题

• 工具重复调用：系统提示已要求模型自行去重，如需强制可以在业务层做二次校验。
• 找不到文档/源码：确认 assets/docs、assets/packages 以及 assets/api/*.json 是否完整同步。
• 缺少环境变量：generateScriptAgent 会显式抛错提醒缺失的 Galacean AI 配置。