Public Project Brief

Forge Stack Code

本地优先的仓库智能理解与审查工作台。它把仓库导入、快照、静态分析、证据检索、Q&A、风险发现和 review pack 导出连成一个可追踪流程。

目标

让陌生仓库在 review、onboarding、风险判断和 agent handoff 前先变成可引用的上下文包。

当前状态

核心 MVP 已可用；Repository Overview、搜索、Q&A、Findings、Reports、运行健康面已打通。

运行形态

直接本地默认 SQLite；Compose/服务化路径已验证 PostgreSQL、Redis、Worker 迁移。

主流程

导入仓库

支持本地路径和公开 Git URL，记录来源、重复导入、快照策略和基础元数据。

创建快照

隔离工作区，按规则复制或克隆，生成文件树、hash、忽略规则和 source metadata。

分析证据

检测语言、入口、命令、文档、依赖、secret、SAST、符号和 import graph。

生成理解

用证据驱动 overview、架构模型、Q&A、onboarding、bug-fix、refactor 和 diligence brief。

导出审查包

输出 Markdown、JSON、manifest、review cards、report 和 agent handoff，可被后续流程复用。

能力边界

已实现

Repository Overview

汇总仓库用途、运行方式、目录结构、核心模块、数据流、依赖、关键文件和风险；缺少外部工具时保留明确降级状态。

部分支持

Architecture Model

从仓库证据生成架构模型、C4/4+1 视图、Mermaid/Structurizr DSL 和 GPT-image2 prompt；图像是展示物，模型 JSON 是事实源。

已实现

Review Workspace

仓库页面按 Review、Explore、Risks、Guides、Exports、Runs 组织；默认页先给 review 判断，再进入细节。

持续演进

Runtime Migration

直连本地保留 SQLite fallback；Compose 和 Postgres service profile 已验证 PostgreSQL、Redis、Worker、canary 和 rollback drill。

公开文档规则

一个入口

外网页只呈现这一个整理页，不再把目录树当作阅读入口。

四类事实源

内部仍按 project、modules、tasks、playbook 维护，分别服务项目定义、能力边界、任务验收和复用经验。

Archive 不公开

历史计划只留在仓库内部，不作为当前执行或对外阅读材料。

JSON 给机器

公开 JSON 只保留摘要和状态；完整内部索引继续由 repo 的 docs check 约束。