truecourse-ai/truecourse

AI 架构与代码智能平台

为人类和 AI 代理构建 —— 面向开发者的 Web UI，面向自动化的 CLI。

TrueCourse 分析您的代码库架构和代码，检测传统 linter 遗漏的违规行为 —— 循环依赖、层级违规、死模块、竞态条件、安全反模式等。它结合静态分析与 AI 审查，呈现发现的问题并提供修复建议。 一切均在您的本地机器上运行。支持 Claude Code（无需 API 密钥）或您自己的 API 密钥。您的代码永远不会离开您的环境。

## 为人类和 AI 代理构建 TrueCourse 设计了两种界面： - **Web UI** —— 交互式依赖图、带有违规标记的内联代码查看器、跨服务流追踪、数据库 ER 图、分析仪表板以及差异模式。专为希望可视地探索和理解代码库的开发者构建。 - **CLI** —— 从终端分析仓库、列出违规并运行差异检查。专为需要结构化输出的 AI 编码代理、CI 流水线和自动化工作流构建。 两种界面共享相同的分析引擎和数据库 —— 通过代理运行 `analyze`，在 UI 中查看结果。 ## 检测内容 ### 架构与模块分析 - 服务和模块之间的 **循环依赖** - **层级违规**，例如数据层调用 API 层、跳过服务层等 - **上帝模块**，包含过多导出或职责 - **死模块**，未被使用且应删除 - 服务或模块之间因过度交叉依赖导致的 **紧耦合** - **数据库问题**，例如缺少索引、绕过 ORM 的原生 SQL、架构问题 ### 代码智能 TrueCourse 不仅限于架构 —— 它审查您的实际源代码，以发现基于 AST 的 linter 无法检测的语义问题： - **错误处理** —— 吞没错误的 catch 块、无上下文重新抛出或返回误导性的成功值 - **竞态条件** —— 跨异步边界的共享可变状态、check-then-act 模式 - **误导性命名** —— 名称与行为不匹配的函数（会变更状态的 `validate`、会删除的 `getUser`） - **死代码** —— 不可达代码、永远为真/假的条件、已赋值但从未读取的变量 - **安全反模式** —— 用于 token 的 `Math.random()`、禁用的 TLS、使用动态输入的 `eval()`、未经清理的 `innerHTML` - **资源泄漏** —— 打开后未清理的文件句柄、连接或事件监听器 - **不一致的返回** —— 函数在不同分支返回不同类型 代码违规会在代码查看器中以内联方式显示，并带有严重性标记、高亮范围和修复建议。确定性规则（空 catch、console.log、硬编码机密、魔术数字、显式 `any`、SQL 注入）通过 AST 访问者运行；语义规则通过 LLM 运行。 ### 跨服务流追踪 TrueCourse 自动检测跨服务边界的请求流 —— HTTP 调用、路由处理程序和内部方法链 —— 并将其可视化为端到端追踪。每个流显示涉及的服务、模块和方法链，当路径上存在违规时显示严重性指示器。 ### 数据库分析 数据库通过 ORM 使用情况（Prisma、Drizzle、SQLAlchemy、TypeORM、Knex 等）自动检测，并作为节点显示在依赖图中。点击数据库节点可查看完整的 ER 图，其中包含表、列、类型和关系。LLM 规则检查缺少外键、缺少索引、命名不一致和架构问题。 ### 分析仪表板 通过图表跟踪违规趋势，显示代码库健康状况在多次分析中的演变。按严重性、类别和规则的细分有助于识别重复出现的模式。代码热点突出显示违规最多的文件。 ### Git 差异模式 - **新增与已解决** —— 查看未提交的更改引入或修复了哪些违规 - **受影响节点** —— 图形会使未受影响的节点变暗，高亮显示受影响的服务/模块/方法 ## 快速开始 ``` cd /path/to/your/repo npx truecourse analyze ``` 首次运行时，服务器会自动启动，设置向导将配置您的 LLM 提供商： - **Claude Code CLI**（推荐）—— 使用您的 Claude Code 订阅，无需 API 密钥 - **Anthropic API** —— 需要 Anthropic API 密钥 - **OpenAI API** —— 需要 OpenAI API 密钥 嵌入式 PostgreSQL 数据库会自动创建，无需 Docker 或外部数据库。 违规信息会打印在您的终端中，Web UI 会自动打开，显示交互式依赖图和高亮的违规项。 ## CLI 命令 ``` npx truecourse # Runs setup + starts the server ``` 或者您可以逐个运行： ``` npx truecourse setup # Configure LLM provider npx truecourse start # Start the server ``` 服务器运行后，`cd` 进入任意仓库并执行： ``` npx truecourse add # Register repo without analyzing npx truecourse analyze # Analyze current repo, show violations npx truecourse analyze --code-review # Analyze with LLM code review (off by default) npx truecourse analyze --no-llm # Deterministic checks only, skip all LLM calls npx truecourse analyze --diff # Show new/resolved violations from uncommitted changes npx truecourse list # Show violations from latest analysis npx truecourse list --diff # Show saved diff check results ``` ## 前置条件 - Node.js >= 20 - 以下之一： - 已安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI（推荐，无需 API 密钥） - Anthropic 或 OpenAI API 密钥 无需数据库设置，无需 Docker。一切均在本地开箱即用。 ## 开发环境设置 如果您想贡献或从源代码运行： ``` git clone https://github.com/yourusername/truecourse.git cd truecourse pnpm install cp .env.example .env # 使用你的 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 编辑 .env pnpm dev ``` ## Claude Code 技能 TrueCourse 包含 [Claude Code 技能](https://docs.anthropic.com/en/docs/claude-code/skills)，让您可以在 Claude Code 内以对话方式运行分析。 当您使用 `npx truecourse add` 注册仓库时，系统会提示您安装 Claude Code 技能。接受后会将技能文件复制到项目中的 `.claude/skills/truecourse/` 目录。 ### 可用技能 | 技能 | 触发词 | 功能 | |---|---|---| | `/truecourse-analyze` | "analyze this repo", "run a diff check" | 运行 `truecourse analyze` 或 `analyze --diff` 并汇总结果 | | `/truecourse-list` | "show violations", "list issues" | 运行 `truecourse list` 或 `list --diff` 以显示完整的违规详情 | | `/truecourse-fix` | "fix violations", "apply fixes" | 列出可修复的违规，让您选择要修复的项，应用更改 | ## 分析规则 TrueCourse 附带三种类型的规则： - **确定性规则** —— 通过 AST 访问者以编程方式检查（层级违规、循环依赖、死模块、空 catch 等） - **LLM 架构规则** —— 传递给 LLM 以进行更深入的架构、数据库和模块检查，并提供修复建议 - **LLM 代码规则** —— 源文件分批发送给 LLM 进行语义代码审查（错误处理、竞态条件、魔术数字、安全性等）。在启用代码审查时运行（`--code-review` 标志或 UI 中的“Analyze with code review”） 所有规则均可在 Web UI 的 **Rules** 标签页中查看。自定义规则生成是即将推出的功能。 ## 语言支持 | 语言 | 状态 | |---|---| | JavaScript / TypeScript | 支持 | | Python | 支持 | | C# | 计划中 | | Go | 计划中 | | Rust | 计划中 | | PHP | 计划中 | ## 遥测 TrueCourse 收集匿名使用数据，以帮助我们了解采用情况并改进产品。遥测功能**默认启用**，可随时禁用。 ### 收集内容 - 事件类型（`analyze` 或 `diff-check`） - 工具版本 - 检测到的语言（例如 TypeScript、Python） - 文件数量范围（分桶：1-50、50-200 等） - 服务数量 - 分析持续时间范围（分桶） - 操作系统和架构（例如 `darwin-arm64`） - 随机匿名会话 ID（不与用户身份关联） ### 不收集内容 - 源代码、文件路径、仓库名称或 git URL - 违规详情、规则结果或 LLM 输出 - IP 地址、用户身份或机器主机名 ### 退出 ``` npx truecourse telemetry disable # Disable telemetry npx truecourse telemetry enable # Re-enable telemetry npx truecourse telemetry status # Check current status ``` 遥测在 CI 环境（`CI=true`）中自动禁用，也可以通过设置 `TRUECOURSE_TELEMETRY=0` 来禁用。 数据发送至 [PostHog](https://posthog.com) 进行聚合。 ## 许可证 MIT

标签：AI, Claude Code, CLI, DNS解析, MITM代理, TCP SYN 扫描, Web UI, WiFi技术, 云安全监控, 人工智能, 代码分析, 代码可视化, 代码审查, 代码智能, 依赖图, 凭证管理, 分层违规, 威胁情报, 安全反模式, 开发者工具, 开源项目, 循环依赖, 技术债务, 数据库ER图, 本地运行, 架构分析, 死代码, 用户模式Hook绕过, 网络安全, 网络调试, 自动化, 自动化payload嵌入, 自动化代码审查, 自动化攻击, 逆向工具, 重构, 隐私保护, 静态分析