PARTHA

工程智能平台

将代码仓库转化为可操作的工程智能。
理解系统，评估变更影响，并充满信心地做出工程决策。

快速开始 · 核心能力 · 架构 · 文档 · 贡献

## 为什么需要 PARTHA 现代软件系统失败并非因为工程师缺乏文件，而是因为代码仓库的知识是碎片化的。 系统架构存在于代码路径、依赖清单、框架约定、部署文件、API 路由、测试、文档以及团队的本地记忆中。随着代码仓库的增长，团队会不断重复相同的问题： - 这个系统从哪里启动？ - 哪些模块负责哪些职责？ - 哪些依赖最重要？ - 新贡献者应该首先阅读哪些文件？ - 对于下一次变更，此架构意味着什么？ - 技术债务在哪里？有什么证据支持？ - AI 如何在不对原始文件进行猜测的情况下回答问题？ PARTHA 的存在是为了将软件代码仓库转化为可复用的工程知识。 核心理念很简单： PARTHA 不是 AI 聊天机器人、代码仓库摘要工具或文档生成器。这些只是表面功能。该平台是一个构建在 Repository Intelligence 之上的工程智能系统。 ## 愿景 PARTHA 的长期发展方向是工程决策智能。 ``` flowchart LR A[Repository Intelligence] --> B[Architecture Intelligence] B --> C[Engineering Intelligence] C --> D[Software Change Intelligence] D --> E[Engineering Decision Intelligence] ``` 目前，PARTHA 专注于基础层面：导入代码仓库、提取可复用的仓库事实、生成架构/依赖/审查/文档视图、导出报告，以及将 AI 提供商建立在代码仓库上下文之上。 我们的目标不是取代工程师。目标是让工程上下文变得可见、一致且可审查。 ## 核心能力 PARTHA 是围绕工程能力而非单个界面来组织的。 | 能力 | 当前实现 | 状态 | | --- | --- | --- | | Repository Intelligence | 导入上传的压缩包或公共 GitHub 代码仓库，构建文件树、元数据、发现事实、源文件智能、模块、依赖项以及序列化的知识图谱。 | 已实现 / 扩展中 | | Architecture Intelligence | 基于 repository intelligence 构建架构模型，包括模块、层次结构、关系、摘要、请求流提示以及前端图谱探索。 | 已启发式实现 | | Dependency Intelligence | 通过 Repository Intelligence Engine 读取依赖清单，并返回依赖清单/图谱响应。尚未实现漏洞和过时检查。 | 部分实现 | | Documentation Intelligence | 根据代码仓库事实、架构、依赖、部署、环境和贡献信号生成 Markdown 或 HTML 文档。 | 已实现 / 基础版 | | Engineering Reviews | 根据 repository intelligence 生成启发式发现、类别评分、有证据支持的受影响文件/模块以及路线图建议。 | 已启发式实现 | | AI Workspace | 允许已配置的 AI 提供商根据结构化的代码仓库上下文回答与仓库相关的问题。提供商不直接解析代码仓库。 | 已实现 | | Reports and Exports | 通过共享的报告 pipeline 将工程审查、文档、架构和依赖项导出为 JSON、Markdown、HTML 或 PDF。 | 已实现 | | Platform Foundation | 提供 Docker Compose、CI、发布工作流、健康/就绪状态检查、请求 ID、指标、结构化日志和环境验证。 | 基线已实现 | PARTHA 有意避免在更深层次的功能出现之前就声称已经具备。变更影响分析、更丰富的语义图谱、漏洞扫描、身份验证以及多用户部署控制均属于路线图项目。 ## 系统概述 ``` flowchart TD Repo[Repository
Upload or GitHub import] Parser[Repository Parser
file tree + metadata] RIE[Repository Intelligence Engine
facts + modules + dependencies + graph] Models[Knowledge Models
architecture + dependencies + review + docs] AI[AI Workspace
provider-grounded context] Reports[Engineering Outputs
UI views + exports + reports] Repo --> Parser Parser --> RIE RIE --> Models Models --> Reports RIE --> AI AI --> Reports ``` Repository Intelligence 是事实的来源。下游功能会使用它；它们不应独立重新解析代码仓库。 ## 架构 PARTHA 是一个包含 React 前端和 FastAPI 后端的 monorepo。 ``` flowchart LR UI[Frontend
React + Vite + TypeScript] API[REST API
FastAPI] Services[Application Services] Intelligence[Repository Intelligence Engine] Storage[(SQLite / PostgreSQL
Local Storage)] AI[AI Provider Layer] Reports[Report Export Pipeline] UI --> API API --> Services Services --> Intelligence Services --> Reports Services --> AI Intelligence --> Storage Reports --> UI AI --> UI ``` ### 子系统 | 子系统 | 职责 | | --- | --- | | Frontend | App shell、代码仓库仪表板、上传/导入、资源管理器、架构图、依赖视图、审查工作区、文档工作区、AI 工作区、设置以及导出操作。 | | Backend API | 针对代码仓库、分析、文档、导出、AI、健康状态、就绪状态和指标的稳定 HTTP 边界。 | | Repository Service | 导入代码仓库，存储记录，暴露文件树和安全的文件预览访问。 | | Repository Intelligence Engine | 根据解析器输出和源文件构建可复用的代码仓库事实。 | | Architecture Service | 将 repository intelligence 转换为架构图响应模型。 | | Dependency Service | 将 repository intelligence 依赖项转换为依赖图响应模型。 | | Documentation Service | 根据现有的 repository intelligence 和分析输出生成文档。 | | Engineering Review Service | 根据 repository intelligence 生成启发式发现、评分和路线图建议。 | | AI Layer | 构建结构化的代码仓库上下文、prompt bundle 以及与提供商无关的编排。 | | Provider Layer | 专为 OpenAI、Anthropic、Gemini、OpenRouter 和 Ollama 提供的独立提供商实现。 | | Export Pipeline | 使用 `ReportDocument` 作为中间表示，并渲染 JSON、Markdown、HTML 或 PDF。 | | Storage | 本地开发默认使用 SQLite，Docker Compose 环境下使用 PostgreSQL，并使用本地文件系统存储代码仓库/上传内容。 | | Platform Foundation | CI、Docker Compose 验证、发布工作流、健康/就绪状态、请求 ID、指标和结构化日志。 | ### AI 架构边界 AI 提供商是 Repository Intelligence 的消费者，而不是生产者。 ``` flowchart TD RIE[Repository Intelligence] Context[Repository Context Builder] Prompt[Prompt Builder] Orchestrator[AI Orchestrator] Factory[Provider Factory] Providers[OpenAI / Anthropic / Gemini / OpenRouter / Ollama] RIE --> Context Context --> Prompt Prompt --> Orchestrator Orchestrator --> Factory Factory --> Providers ``` 提供商实现负责处理 HTTP 请求、身份验证、响应解析和错误标准化。它们不会读取代码仓库文件或重建分析。 ### 导出架构边界 ``` flowchart LR Route[Export Route] --> Service[ExportService] Service --> Data[Existing Analysis / Documentation Output] Data --> Document[ReportDocument] Document --> Renderers[Markdown / HTML / PDF] Data --> Json[JSON Export] ``` 导出 pipeline 使用现有的分析输出。它不会重新分析代码仓库。 ## 代码仓库工作流 ``` sequenceDiagram participant User participant UI as Frontend participant API as FastAPI participant Repo as Repository Service participant RIE as Repository Intelligence Engine participant Views as Intelligence Consumers User->>UI: Upload archive or import GitHub URL UI->>API: POST /repositories/upload or /repositories/github API->>Repo: Store repository and parse file tree Repo->>RIE: Build repository intelligence RIE-->>Repo: Persist intelligence in repository metadata UI->>API: POST /analysis/{id}/start API->>Views: Build architecture/dependencies/review/docs Views-->>UI: Engineering intelligence surfaces ``` ## 截图 等公开演示 UI 准备好后将添加截图。 | 界面 | 占位符 | | --- | --- | | Repository Dashboard | 上传并检查代码仓库。 | | Architecture Intelligence | 探索模块、层次结构、关系和请求流提示。 | | Engineering Review | 审查发现、评分、证据和路线图建议。 | | AI Workspace | 通过已配置的提供商提出基于代码仓库的问题。 | | Reports | 导出架构、依赖项、文档和审查产物。 | ## 快速开始 ### 前置条件 | 工具 | 版本 | | --- | --- | | Node.js | 推荐使用 22 或更高版本 | | npm | 随 Node.js 捆绑提供 | | Python | 3.12 或 3.13 | | Docker | 基于 Compose 的 PostgreSQL/Redis 工作流所需 | | Git | 导入 GitHub 代码仓库所需 | ### 克隆并安装 ``` git clone https://github.com/Second-Origin/PARTHA.git cd PARTHA npm ci --prefix apps/frontend cd apps/backend python3.13 -m venv .venv source .venv/bin/activate pip install -e . cd ../.. ``` ### 配置环境 ``` cp .env.example .env cp apps/frontend/.env.example apps/frontend/.env cp apps/backend/.env.example apps/backend/.env ``` 后端本地示例使用 SQLite 和本地文件系统存储，因此直接在本地启动无需 PostgreSQL 或 Redis 即可运行。Docker Compose 会注入特定于容器的 PostgreSQL、Redis 和存储值。 ### 在本地运行 ``` npm run dev:backend npm run dev:frontend ``` 打开： - frontend: `http://localhost:5173` - backend 文档: `http://localhost:8000/docs` - 就绪状态: `http://localhost:8000/ready` - 指标: `http://localhost:8000/metrics` ## 本地开发 常用命令： ``` npm run dev:frontend npm run dev:backend npm run lint:frontend npm run build:frontend npm run test:backend npm run build ``` 如果存在 `apps/backend/.venv`，后端辅助脚本会优先使用它，否则回退到使用 `python`。 ## Docker 验证 Docker Compose 配置： ``` npm run docker:config ``` 运行带有运行时就绪状态验证的 Compose： ``` npm run docker:validate ``` 为本地基础设施启动 Compose 技术栈： ``` npm run docker:up ``` Compose 技术栈运行： | 服务 | 端口 | | --- | --- | | API | `8000` | | PostgreSQL | `5432` | | Redis | `6379` | 使用 `npm run dev:frontend` 单独运行前端。 ## 技术决策 PARTHA 使用实用且可检查的工具，而不是不透明的基础设施。 | 决策 | 原因 | | --- | --- | | React + Vite + TypeScript | 快速的本地迭代、类型化的前端契约，以及清晰的 app/feature/shared 结构。 | | FastAPI + Pydantic | 显式的请求/响应 schema、OpenAPI 生成，以及直接的服务边界。 | | SQLAlchemy + Alembic | 可在 SQLite 本地开发和 PostgreSQL 支持的部署之间实现可移植的持久化。 | | Repository Intelligence Engine | 集中管理代码仓库事实，以免架构、文档、审查、导出和 AI 出现偏差。 | | Tree-sitter foundation | 在保留启发式回退的同时，为更深层次的语言感知提取提供路径。 | | Provider abstraction | 保持 AI 编排与提供商无关，并防止提供商解析代码仓库。 | | ReportDocument pipeline | 将报告构建与渲染分离，以便安全地添加新的导出格式。 | | Docker Compose | 提供可重现的本地后端基础设施，无需做出生产托管决策。 | ## 项目结构 ``` PARTHA/ ├── apps/ │ ├── backend/ FastAPI backend │ └── frontend/ React frontend ├── docs/ │ ├── architecture/ System and subsystem architecture docs │ ├── assets/ Public README and brand assets │ ├── audit/ Engineering audit records │ ├── brand/ Visual identity guidance │ ├── operations/ Deployment, observability, release, dependencies │ └── product/ Product/public-face audits ├── packages/ Reserved for future shared packages ├── scripts/ Local workflow helpers ├── docker-compose.yml Local API/PostgreSQL/Redis stack ├── package.json Root workspace scripts └── CONTRIBUTING.md Contributor guide ``` 后端职责： | 路径 | 职责 | | --- | --- | | `app/api/` | 路由和依赖注入。 | | `app/services/` | 应用服务。 | | `app/intelligence/` | Repository Intelligence Engine 和模型。 | | `app/analysis/` | 架构建模。 | | `app/graph/` | 依赖图构建。 | | `app/review/` | 生成工程审查。 | | `app/ai/` | AI 编排、上下文、prompt 和提供商。 | | `app/reports/` | 报告文档模型、构建器、渲染器、导出服务。 | | `app/storage/` | 本地代码仓库/上传存储。 | 前端职责： | 路径 | 职责 | | --- | --- | | `src/app/` | App shell、路由、页面和全局 store。 | | `src/features/` | 特定领域的 hook、状态和组件。 | | `src/shared/` | 可复用的 UI、API 客户端、配置、hook、类型和工具。 | | `src/styles/` | 全局样式和设计 token。 | ## 文档 从这里开始： | 文档 | 用途 | | --- | --- | | `docs/README.md` | 文档索引。 | | `docs/product/PUBLIC_FACE_AUDIT.md` | 针对此次公开形象重新设计的代码仓库、文档和定位审计。 | | `docs/brand/VISUAL_IDENTITY.md` | 视觉形象、颜色、logo、图表和文档风格。 | | `docs/architecture/REPOSITORY_INTELLIGENCE_ENGINE.md` | Repository Intelligence Engine 架构和边界。 | | `docs/architecture/AI_ARCHITECTURE.md` | AI 架构、Provider Layer、上下文和 prompt 流程。 | | `docs/operations/production-deployment.md` | 生产部署基线和操作限制。 | | `docs/operations/observability.md` | 请求 ID、日志、脱敏、指标、就绪状态。 | | `docs/operations/release-management.md` | 版本控制和发布工作流。 | | `docs/operations/dependency-management.md` | 依赖维护策略。 | ## 路线图 ### 当前里程碑 目前正在构建 Repository Intelligence 和工程智能的基础： - 代码仓库摄取和安全的文件预览； - 可复用的 repository intelligence； - 架构/依赖/审查/文档消费者； - 建立在代码仓库上下文基础上的 AI 提供商集成； - 报告导出； - 用于本地和受控部署的操作基线。 ### 未来里程碑 | 里程碑 | 方向 | | --- | --- | | 更丰富的 Repository Intelligence | 更深层次的符号提取、关系检测、持久化的图谱产物以及语言感知分析。 | | 软件变更智能 | 影响分析、受影响的模块、感知依赖的变更规划以及审查辅助。 | | 工程决策智能 | 基于架构、依赖项、风险、所有权和代码仓库历史的决策支持。 | | 生产级多用户平台 | 身份验证、授权、团队、保留策略、密钥管理、审计追踪以及托管部署控制。 | ### 当前的非目标 PARTHA 尚未提供公共的多用户 SaaS 控制、漏洞扫描、深度的语义变更影响分析或完整的 OpenTelemetry 追踪。 ## 贡献 PARTHA 欢迎那些能够保留 Repository Intelligence 边界的、专注的工程贡献。 从以下内容开始： - `CONTRIBUTING.md` 了解设置、分支策略、issue 工作流、Pull Request 流程、测试和文档标准。 - `docs/architecture/REPOSITORY_INTELLIGENCE_ENGINE.md` 在更改分析之前阅读。 - `docs/architecture/AI_ARCHITECTURE.md` 在更改 AI 行为之前阅读。 核心规则： ## 项目标识 PARTHA 是公开的产品名称。 内部的全称是： 这个全称解释了项目的起源，但公开品牌应保持简单：**PARTHA — 工程智能平台**。 ## 许可证 PARTHA 采用 Apache License 2.0 授权。 有关完整的许可证文本，请参阅 [LICENSE](LICENSE) 文件。

标签：AI辅助推理, DInvoke, WebSocket, 代码可视化, 代码库分析, 依赖分析, 工程智能, 技术债管理, 搜索引擎查询, 架构分析, 测试用例, 版权保护, 自动化攻击, 逆向工具