Shingan 是一个基于 Go 语言的 AI Agent 工作流静态分析工具，能够在执行前检测无限循环、不可达节点、错误处理缺失、成本爆炸、PII 泄露路径等潜在问题。

Shingan：AI Agent 工作流静态分析器\n\n## 背景：AI Agent 编排的风险与挑战\n\n随着大语言模型（LLM）能力的不断提升，AI Agent 编排框架如 LangGraph、CrewAI、n8n、Google ADK 等已经成为构建复杂 AI 应用的标配工具。这些框架允许开发者将多个 LLM 调用、工具执行、条件判断组合成自动化的工作流。\n\n然而，这种强大能力也带来了新的风险：\n\n- 无限循环：Agent 在特定条件下可能陷入无限循环，导致资源耗尽\n- 成本爆炸：未经优化的工作流可能产生意外的昂贵 LLM 调用\n- PII 泄露：敏感信息可能在不经意间被传递到外部服务\n- 不可达节点：部分逻辑分支永远不会被执行，形成死代码\n- 错误处理缺失：关键操作失败时缺乏适当的回退机制\n\n与传统软件不同，AI Agent 一旦开始执行就难以中断。外部 API 调用、浏览器自动化、代码执行等操作都会产生不可逆的副作用。因此，在部署前捕获这些潜在问题至关重要。\n\n## Shingan 简介\n\nShingan（写轮眼）是一个基于 Go 语言开发的 AI Agent 工作流静态分析工具。它能够在工作流执行前检测出多种潜在问题，包括无限循环、不可达节点、缺失的错误处理器、成本失控、冗余 LLM 调用、提示注入风险点和 PII 泄露路径。\n\n项目名称"Shingan"取自《火影忍者》中的瞳术，象征着洞察和预见能力——这正是该工具的核心价值所在。\n\n## 核心设计理念\n\n### 洋葱架构（Onion Architecture）\n\nShingan 采用洋葱架构设计，依赖关系严格向内流动：\n\n\n┌─────────────────────────────────────────────┐\n│ cmd/ DI wiring + entry points │\n│ ┌───────────────────────────────────────┐ │\n│ │ infrastructure/ concrete adapters │ │\n│ │ ┌─────────────────────────────────┐ │ │\n│ │ │ application/ use cases │ │ │\n│ │ │ ┌───────────────────────────┐ │ │ │\n│ │ │ │ domain/ zero external dep │ │ │ │\n│ │ │ └───────────────────────────┘ │ │ │\n│ │ └─────────────────────────────────┘ │ │\n│ └───────────────────────────────────────┘ │\n└─────────────────────────────────────────────┘\n\n\n各层职责：\n\n| 层级 | 职责 | 允许的依赖 |\n|------|------|-----------|\n| domain/ | WorkflowGraph、规则、实体定义 | 仅标准库 |\n| application/ | AnalysisOrchestrator、接口定义 | domain/ |\n| infrastructure/ | 解析器、报告器、工厂实现 | application/、domain/ |\n| cmd/ | CLI、依赖注入 | infrastructure/ |\n\n### 工厂模式（Factory Pattern）\n\nShingan 在三个关键点使用工厂模式：\n\n1. AnalyzerFactory：注册和创建分析规则\n2. ParserFactory：根据输入格式切换解析器\n3. ReporterFactory：根据输出格式切换报告器\n\n这种设计使得 Shingan 可以轻松扩展支持新的工作流框架和输出格式。\n\n## 支持的工作流框架\n\nShingan 支持多种主流工作流框架：\n\n- LangGraph（Python）：LangChain 的图编排框架\n- ADK-Go（Go）：Google 的 Agent Development Kit\n- n8n：可视化工作流自动化平台\n- 自定义 JSON DSL：通用的 JSON 格式工作流定义\n\n所有这些框架都被抽象为统一的中间表示（IR）：有向图，节点和边。这种抽象使得分析规则可以跨框架复用。\n\n## 核心检测规则\n\nShingan 实现了 20+ 条分析规则，覆盖多个风险维度：\n\n### 1. 循环检测（cycle_detection）\n\n检测非循环节点之间的循环，以及 LoopAgent 内部的循环。严重程度：Critical，置信度：1.0（确定性检测）。\n\n### 2. 循环守卫（loop_guard）\n\n检查 LoopAgent 是否设置了 MaxIterations。未设置的循环可能导致无限执行。严重程度：Critical。\n\n### 3. 不可达节点（unreachable_node）\n\n检测从入口节点无法到达的 LLM/Tool 节点。这些代码永远不会执行。严重程度：Warning。\n\n### 4. 错误处理器检查（error_handler_checker）\n\n检查外部 I/O 节点后是否缺少错误处理。严重程度：Critical，置信度：0.8（启发式）。\n\n### 5. 成本估算（cost_estimation）\n\n检测循环内的昂贵 LLM 模型调用，以及昂贵模型用于简单任务的情况。严重程度：Warning，置信度：0.7（价格会变动）。\n\n### 6. 冗余 LLM 调用（redundant_llm_call）\n\n检测相同（prompt_template, model）的重复调用。严重程度：Warning，置信度：0.9（精确匹配）。\n\n### 7. PII 泄露扫描（pii_leak_scanner）\n\n检测从 RAG/PII 源到外部出口的路径，且没有人工审核节点。严重程度：Warning。\n\n### 8. 密钥暴露扫描（secret_exposure_scanner）\n\n检测 Node.Config 中硬编码的 API 密钥和密钥。严重程度：Critical。\n\n### 9. 最大并行分支（max_parallel_branches）\n\n检测单个节点的扇出（出边数量）是否超过阈值。严重程度：Critical/Warning/Info。\n\n### 10. 废弃模型（deprecated_model）\n\n检测已关闭或即将废弃的 LLM 模型名称（OpenAI / Anthropic / Google）。严重程度：Critical。\n\n## 使用方式\n\n### 通过 npm 使用\n\nbash\n# 一次性运行\nnpx shingan-lint analyze --format=langgraph ./agents/\n\n# 项目级安装\npnpm add -D shingan-lint\npnpm exec shingan analyze --since main\n\n# 全局安装\nnpm install -g shingan-lint\nshingan analyze --input ./testdata/buggy.json\n\n\n### 通过 Go 安装\n\nbash\ngo install github.com/hatyibei/shingan/cmd/shingan@latest\n\n\n### 通过 Docker 使用\n\nbash\ndocker pull ghcr.io/hatyibei/shingan:latest\ndocker run --rm -v \"$(pwd)\":/work ghcr.io/hatyibei/shingan analyze --input /work/buggy.json\n\n\n## 输出格式\n\nShingan 支持多种输出格式：\n\n- Markdown：人类可读的报告格式\n- SARIF：标准化的静态分析结果格式，可集成到 CI/CD\n- JSON：机器可解析的详细结果\n\n## CI/CD 集成\n\nShingan 可以无缝集成到 GitHub Actions：\n\nyaml\n- name: Shingan check\n run: shingan analyze --format adk-go --input ./agents/\n\n\n退出码定义：\n- 0：仅信息或清洁\n- 1：存在警告\n- 2：至少一个严重问题\n\n## 实际检测示例\n\n项目提供了三个真实示例，展示 Shingan 的检测能力：\n\n### 示例 1：无限循环\n\ngo\n// infinite_loop.go\nloopagent.New(loopagent.Config{AgentConfig: agent.Config{SubAgents: ...}})\n// 未设置 MaxIterations\n\n\n检测结果：cycle_detection，Critical，退出码 2\n\n### 示例 2：不可达节点\n\ngo\n// unreachable.go\norphan_analyzer not wired into the orchestrator's SubAgents\n\n\n检测结果：unreachable_node，Warning，退出码 1\n\n### 示例 3：缺失错误处理\n\ngo\n// missing_handler.go\nplanner calls browser_search but has no conditional branch for failure\n\n\n检测结果：error_handler_checker（Critical: loop_guard + Warning: error_handler_checker），退出码 2\n\n## 与现有工具的比较\n\n| 工具 | 检测时机 | 检测范围 | 框架支持 |\n|------|---------|---------|---------|\n| Shingan | 部署前（静态） | 结构、逻辑、安全 | LangGraph, ADK-Go, n8n, JSON |\n| FlowLint | 部署前 | 结构 | n8n 专用 |\n| LangSmith | 运行时 | 性能、追踪 | LangChain 生态 |\n\nShingan 的独特价值在于它填补了"设计时缺陷检测"的空白。FlowLint 仅支持 n8n，LangSmith 专注于运行时可观测性——两者都不在部署前检查工作流结构。\n\n## 技术亮点\n\n### ADK-Go SDK 支持\n\nShingan 对 Google ADK-Go SDK v1.1.0 提供了深度支持：\n\n- 支持 loopagent.New() 构造模式\n- 通过 AST 检测 LlmAgent / SequentialAgent / LoopAgent 的 New() 模式\n- 解析 functiontool.New 注册的工具节点\n- 使用 go/types 读取泛型参数，推断 Tool 类别\n- 检测 LLM→Tool 模式中的条件分支缺失\n\n### 多平台支持\n\nShingan 通过 npm 包装器提供跨平台支持：\n\n- Linux（amd64, arm64）\n- macOS（amd64, arm64）\n- Windows（amd64, arm64）\n\nnpm 包的 postinstall 步骤会自动下载对应平台的 Go 二进制文件，验证 SHA-256 校验和，并缓存到 ~/.cache/shingan-lint/。\n\n## 项目意义\n\n### 成本保护\n\nAI Agent 的每次执行都可能产生真实的 API 费用。Shingan 在部署前捕获潜在的成本爆炸风险，帮助团队避免意外的账单。\n\n### 安全保障\n\nPII 泄露和密钥暴露是 AI 应用面临的严重安全威胁。Shingan 的静态分析能够在代码提交前发现这些问题。\n\n### 质量提升\n\n不可达节点和缺失错误处理会降低工作流的可靠性。Shingan 帮助开发者构建更健壮的 Agent 系统。\n\n### 开发效率\n\n通过 CI/CD 集成，Shingan 可以在代码审查阶段自动发现问题，减少人工 review 的负担。\n\n## 局限性与注意事项\n\n1. 静态分析限制：某些问题只能在运行时被发现\n2. 框架版本：需要持续跟进各框架的 API 变化\n3. 误报可能：启发式规则可能产生误报，需要人工确认\n4. 配置复杂度：复杂项目可能需要详细的配置\n\n## 结语\n\nShingan 代表了 AI Agent 开发工具链的重要一环。随着 Agent 编排变得越来越普遍，部署前的静态分析将成为标准实践。Shingan 通过其跨框架支持、丰富的检测规则和灵活的集成方式，为这一领域提供了有价值的开源解决方案。\n\n对于正在构建 AI Agent 应用的团队来说，Shingan 是一个值得考虑的代码质量门禁工具。

Shingan：AI Agent 工作流静态分析器\n\n背景：AI Agent 编排的风险与挑战\n\n随着大语言模型（LLM）能力的不断提升，AI Agent 编排框架如 LangGraph、CrewAI、n8n、Google ADK 等已经成为构建复杂 AI 应用的标配工具。这些框架允许开发者将多个 LLM 调用、工具执行、条件判断组合成自动化的工作流。\n\n然而，这种强大能力也带来了新的风险：\n\n- 无限循环：Agent 在特定条件下可能陷入无限循环，导致资源耗尽\n- 成本爆炸：未经优化的工作流可能产生意外的昂贵 LLM 调用\n- PII 泄露：敏感信息可能在不经意间被传递到外部服务\n- 不可达节点：部分逻辑分支永远不会被执行，形成死代码\n- 错误处理缺失：关键操作失败时缺乏适当的回退机制\n\n与传统软件不同，AI Agent 一旦开始执行就难以中断。外部 API 调用、浏览器自动化、代码执行等操作都会产生不可逆的副作用。因此，在部署前捕获这些潜在问题至关重要。\n\nShingan 简介\n\nShingan（写轮眼）是一个基于 Go 语言开发的 AI Agent 工作流静态分析工具。它能够在工作流执行前检测出多种潜在问题，包括无限循环、不可达节点、缺失的错误处理器、成本失控、冗余 LLM 调用、提示注入风险点和 PII 泄露路径。\n\n项目名称"Shingan"取自《火影忍者》中的瞳术，象征着洞察和预见能力——这正是该工具的核心价值所在。\n\n核心设计理念\n\n洋葱架构（Onion Architecture）\n\nShingan 采用洋葱架构设计，依赖关系严格向内流动：\n\n\n┌─────────────────────────────────────────────┐\n│ cmd/ DI wiring + entry points │\n│ ┌───────────────────────────────────────┐ │\n│ │ infrastructure/ concrete adapters │ │\n│ │ ┌─────────────────────────────────┐ │ │\n│ │ │ application/ use cases │ │ │\n│ │ │ ┌───────────────────────────┐ │ │ │\n│ │ │ │ domain/ zero external dep │ │ │ │\n│ │ │ └───────────────────────────┘ │ │ │\n│ │ └─────────────────────────────────┘ │ │\n│ └───────────────────────────────────────┘ │\n└─────────────────────────────────────────────┘\n\n\n各层职责：\n\n| 层级 | 职责 | 允许的依赖 |\n|------|------|-----------|\n| domain/ | WorkflowGraph、规则、实体定义 | 仅标准库 |\n| application/ | AnalysisOrchestrator、接口定义 | domain/ |\n| infrastructure/ | 解析器、报告器、工厂实现 | application/、domain/ |\n| cmd/ | CLI、依赖注入 | infrastructure/ |\n\n工厂模式（Factory Pattern）\n\nShingan 在三个关键点使用工厂模式：\n\n1. AnalyzerFactory：注册和创建分析规则\n2. ParserFactory：根据输入格式切换解析器\n3. ReporterFactory：根据输出格式切换报告器\n\n这种设计使得 Shingan 可以轻松扩展支持新的工作流框架和输出格式。\n\n支持的工作流框架\n\nShingan 支持多种主流工作流框架：\n\n- LangGraph（Python）：LangChain 的图编排框架\n- ADK-Go（Go）：Google 的 Agent Development Kit\n- n8n：可视化工作流自动化平台\n- 自定义 JSON DSL：通用的 JSON 格式工作流定义\n\n所有这些框架都被抽象为统一的中间表示（IR）：有向图，节点和边。这种抽象使得分析规则可以跨框架复用。\n\n核心检测规则\n\nShingan 实现了 20+ 条分析规则，覆盖多个风险维度：\n\n1. 循环检测（cycle_detection）\n\n检测非循环节点之间的循环，以及 LoopAgent 内部的循环。严重程度：Critical，置信度：1.0（确定性检测）。\n\n2. 循环守卫（loop_guard）\n\n检查 LoopAgent 是否设置了 MaxIterations。未设置的循环可能导致无限执行。严重程度：Critical。\n\n3. 不可达节点（unreachable_node）\n\n检测从入口节点无法到达的 LLM/Tool 节点。这些代码永远不会执行。严重程度：Warning。\n\n4. 错误处理器检查（error_handler_checker）\n\n检查外部 I/O 节点后是否缺少错误处理。严重程度：Critical，置信度：0.8（启发式）。\n\n5. 成本估算（cost_estimation）\n\n检测循环内的昂贵 LLM 模型调用，以及昂贵模型用于简单任务的情况。严重程度：Warning，置信度：0.7（价格会变动）。\n\n6. 冗余 LLM 调用（redundant_llm_call）\n\n检测相同（prompt_template, model）的重复调用。严重程度：Warning，置信度：0.9（精确匹配）。\n\n7. PII 泄露扫描（pii_leak_scanner）\n\n检测从 RAG/PII 源到外部出口的路径，且没有人工审核节点。严重程度：Warning。\n\n8. 密钥暴露扫描（secret_exposure_scanner）\n\n检测 Node.Config 中硬编码的 API 密钥和密钥。严重程度：Critical。\n\n9. 最大并行分支（max_parallel_branches）\n\n检测单个节点的扇出（出边数量）是否超过阈值。严重程度：Critical/Warning/Info。\n\n10. 废弃模型（deprecated_model）\n\n检测已关闭或即将废弃的 LLM 模型名称（OpenAI / Anthropic / Google）。严重程度：Critical。\n\n使用方式\n\n通过 npm 使用\n\nbash\n一次性运行\nnpx shingan-lint analyze --format=langgraph ./agents/\n\n项目级安装\npnpm add -D shingan-lint\npnpm exec shingan analyze --since main\n\n全局安装\nnpm install -g shingan-lint\nshingan analyze --input ./testdata/buggy.json\n\n\n通过 Go 安装\n\nbash\ngo install github.com/hatyibei/shingan/cmd/shingan@latest\n\n\n通过 Docker 使用\n\nbash\ndocker pull ghcr.io/hatyibei/shingan:latest\ndocker run --rm -v \"$(pwd)\":/work ghcr.io/hatyibei/shingan analyze --input /work/buggy.json\n\n\n输出格式\n\nShingan 支持多种输出格式：\n\n- Markdown：人类可读的报告格式\n- SARIF：标准化的静态分析结果格式，可集成到 CI/CD\n- JSON：机器可解析的详细结果\n\nCI/CD 集成\n\nShingan 可以无缝集成到 GitHub Actions：\n\nyaml\n- name: Shingan check\n run: shingan analyze --format adk-go --input ./agents/\n\n\n退出码定义：\n- 0：仅信息或清洁\n- 1：存在警告\n- 2：至少一个严重问题\n\n实际检测示例\n\n项目提供了三个真实示例，展示 Shingan 的检测能力：\n\n示例 1：无限循环\n\ngo\n// infinite_loop.go\nloopagent.New(loopagent.Config{AgentConfig: agent.Config{SubAgents: ...}})\n// 未设置 MaxIterations\n\n\n检测结果：cycle_detection，Critical，退出码 2\n\n示例 2：不可达节点\n\ngo\n// unreachable.go\norphan_analyzer not wired into the orchestrator's SubAgents\n\n\n检测结果：unreachable_node，Warning，退出码 1\n\n示例 3：缺失错误处理\n\ngo\n// missing_handler.go\nplanner calls browser_search but has no conditional branch for failure\n\n\n检测结果：error_handler_checker（Critical: loop_guard + Warning: error_handler_checker），退出码 2\n\n与现有工具的比较\n\n| 工具 | 检测时机 | 检测范围 | 框架支持 |\n|------|---------|---------|---------|\n| Shingan | 部署前（静态） | 结构、逻辑、安全 | LangGraph, ADK-Go, n8n, JSON |\n| FlowLint | 部署前 | 结构 | n8n 专用 |\n| LangSmith | 运行时 | 性能、追踪 | LangChain 生态 |\n\nShingan 的独特价值在于它填补了"设计时缺陷检测"的空白。FlowLint 仅支持 n8n，LangSmith 专注于运行时可观测性——两者都不在部署前检查工作流结构。\n\n技术亮点\n\nADK-Go SDK 支持\n\nShingan 对 Google ADK-Go SDK v1.1.0 提供了深度支持：\n\n- 支持 loopagent.New() 构造模式\n- 通过 AST 检测 LlmAgent / SequentialAgent / LoopAgent 的 New() 模式\n- 解析 functiontool.New 注册的工具节点\n- 使用 go/types 读取泛型参数，推断 Tool 类别\n- 检测 LLM→Tool 模式中的条件分支缺失\n\n多平台支持\n\nShingan 通过 npm 包装器提供跨平台支持：\n\n- Linux（amd64, arm64）\n- macOS（amd64, arm64）\n- Windows（amd64, arm64）\n\nnpm 包的 postinstall 步骤会自动下载对应平台的 Go 二进制文件，验证 SHA-256 校验和，并缓存到 ~/.cache/shingan-lint/。\n\n项目意义\n\n成本保护\n\nAI Agent 的每次执行都可能产生真实的 API 费用。Shingan 在部署前捕获潜在的成本爆炸风险，帮助团队避免意外的账单。\n\n安全保障\n\nPII 泄露和密钥暴露是 AI 应用面临的严重安全威胁。Shingan 的静态分析能够在代码提交前发现这些问题。\n\n质量提升\n\n不可达节点和缺失错误处理会降低工作流的可靠性。Shingan 帮助开发者构建更健壮的 Agent 系统。\n\n开发效率\n\n通过 CI/CD 集成，Shingan 可以在代码审查阶段自动发现问题，减少人工 review 的负担。\n\n局限性与注意事项\n\n1. 静态分析限制：某些问题只能在运行时被发现\n2. 框架版本：需要持续跟进各框架的 API 变化\n3. 误报可能：启发式规则可能产生误报，需要人工确认\n4. 配置复杂度：复杂项目可能需要详细的配置\n\n结语\n\nShingan 代表了 AI Agent 开发工具链的重要一环。随着 Agent 编排变得越来越普遍，部署前的静态分析将成为标准实践。Shingan 通过其跨框架支持、丰富的检测规则和灵活的集成方式，为这一领域提供了有价值的开源解决方案。\n\n对于正在构建 AI Agent 应用的团队来说，Shingan 是一个值得考虑的代码质量门禁工具。