# TraceForge

**Repository Path**: xhy0302/traceforge

## Basic Information

- **Project Name**: TraceForge
- **Description**: 面向高校软件项目团队的 AI 原生可复现交付与证据链平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 溯智工坊 TraceForge

面向高校软件项目团队的多智能体可复现交付与证据链平台。它把需求、源代码、Git 提交、测试和验收材料关联起来，让每个 AI 结论都能追溯到具体证据。

## 技术架构

```text
React + TypeScript 前端
        │ /api（Vite 开发代理）
        ▼
Node.js 安全 API 层
        ├── Git 仓库解析与完整提交历史索引
        ├── 需求/源码/测试证据关联
        ├── 代码切分、本地/语义向量检索与 RAG
        ├── 五类只读仓库工具与可追踪 Agent 循环
        ├── 可审阅、可下载、需确认的 AI 修复补丁
        ├── 受确认保护的测试执行器
        └── 项目成员与审查结果持久化
                 │
                 ▼
       .traceforge-cache 本地数据层
```

- `src/`：React 页面、证据图谱、审查交互和 API 客户端。
- `server.mjs`、`server/`：只读仓库分析、Git 历史、向量索引、测试执行与本地持久化。
- `tests/`：Node 服务端测试和 Playwright 端到端验收。
- `docs/`：需求、技术设计、竞赛计划、环境配置和真实仓库验收记录。

## 团队信息

| 成员 | 角色 | 可核验贡献 |
| --- | --- | --- |
| 肖鸿宇（Gitee：`xhy0302`） | 项目负责人 / 全栈开发 | 产品方案、前后端实现、仓库分析、测试与文档；贡献记录见本仓库 Git 历史 |
| 周子轩（Gitee：zhou-zixuan7） | 测试评估与参赛交付负责人 | RAG 评测集与可重复脚本、安全专项和端到端验收、用户手册与答辩演示材料；贡献见本人 Git 提交 |

详细职责、交付物和当前贡献状态见 [`docs/team-contributions.md`](docs/team-contributions.md)。团队贡献以仓库提交、需求文档、测试记录和最终参赛材料为准，不虚构个人工作量。

## 已实现（真实可用）

- 通过 Windows 系统文件夹选择器或绝对路径直接导入本地项目，不要求上传 GitHub；也可克隆公开 GitHub/Gitee 仓库
- 真实读取 Git 分支、HEAD、完整提交历史、已跟踪与未跟踪文件；旧浅克隆会自动补全
- 从 README、docs、PRD、Markdown 自动提取需求线索
- 对源码、文档和测试执行带行号的重叠切分，建立 384 维本地代码向量索引
- 识别源码、测试文件、技术语言、TODO/FIXME、环境文件与疑似凭据模式
- 按每条需求分别关联源码、测试、提交和风险证据，并生成四维交付可信度评分
- 本地持久化最近的仓库索引，刷新后可继续工作
- 点击文件证据可查看仓库中的真实文本片段
- 在工作台按问题检索相关代码切片，返回文件路径、行号、类型和相似度
- 对真实仓库执行 RAG 问答，展示引用片段、行号、检索引擎和每一步工具调用轨迹
- 模型 Agent 可自主调用代码检索、文件读取、需求、Git 提交和项目指标工具；无模型时明确回退为本地工具编排
- 用户可在设置页自行连接 OpenAI、DeepSeek 或 OpenAI 兼容模型，连接前执行真实 API 验证
- 用户提供的密钥仅驻留本机服务进程内存，不进入浏览器存储、项目缓存、日志或 Git，重启后自动清除
- 可选接入兼容 Embeddings 的服务，分批建立持久化语义向量索引并优先执行语义检索
- 本地规则审查始终可用；配置兼容模型后增强审查结论
- 经用户明确确认后执行项目已有的 `test` / `test:*` 脚本，保存真实通过、失败或超时结果
- 导出包含评分、需求覆盖、测试结果和风险发现的 Markdown 审查报告
- 按项目维护本地团队成员名单，添加成员并分配开发、审查或只读角色
- 支持真实账号注册登录、邮箱邀请、项目级 RBAC 权限和 scrypt 密码哈希
- 通过 SSE 实时同步在线成员、角色变化、测试结果与语义索引状态
- 配置 Embedding 服务后可直接为现有项目构建、重建或移除语义索引
- 在审查页选择问题或输入目标，由 RAG 定位真实代码、模型生成 unified diff，并在服务端安全校验后预览、下载或确认应用
- 补丁应用前会校验 Git 工作区、文件内容版本、路径边界与敏感文件规则；只有负责人和开发成员可以写入，且不会自动提交 Git
- 设计稿与实际截图的浏览器端真实像素比较，并可导出 JSON 报告
- 响应式桌面、平板和移动端布局

真实远程仓库的切分与检索验收数据见 [`docs/rag-demo.md`](docs/rag-demo.md)；RAG、工具白名单、模型循环与配置说明见 [`docs/rag-agent.md`](docs/rag-agent.md)。

评测与参赛验收材料：

- [RAG 评测报告](docs/evaluation-report.md) 与 [24 条评测集](evaluation/rag-dataset.jsonl)
- [安全验收报告](docs/security-test-report.md)
- [端到端与用户验收报告](docs/uat-report.md)
- [用户操作手册](docs/user-guide.md)
- [6 分钟答辩演示脚本](docs/demo-script.md)

## 运行

```bash
cp .env.example .env
npm ci
npm run dev
```

浏览器打开 `http://127.0.0.1:5173`。

Windows PowerShell 请将复制命令换为 `Copy-Item .env.example .env`。Node.js、npm、Git 版本要求、环境变量表、固定依赖清单和故障排查见 [`docs/environment.md`](docs/environment.md)。

## 连接真实模型（可选）

在 `.env` 中填写兼容 Chat Completions 的服务：

```bash
AI_API_BASE=https://your-provider.example/v1
AI_API_KEY=your-server-side-key
AI_MODEL=your-model
AI_THINKING_MODE=
AI_EMBEDDING_API_BASE=https://your-embedding-provider.example/v1
AI_EMBEDDING_API_KEY=your-embedding-key
AI_EMBEDDING_MODEL=your-embedding-model
AI_EMBEDDING_DIMENSIONS=512
```

也可以直接在“项目设置 → 模型 Agent → 连接模型”中填写。界面填写的密钥只保存在当前本机服务进程内存，服务重启后清除；环境变量密钥仅由 `server.mjs` 读取。两种方式都不会把密钥写入浏览器打包产物或公开仓库。

## 使用主线

1. 首次打开页面时注册项目负责人账号；之后使用邮箱和密码登录。
2. 在导入窗口输入本地项目路径，或公开仓库 URL。
3. 等待索引完成，在工作台点击图谱节点查看真实文件、提交和风险。
4. 在“项目设置 → Git 提交记录”核验完整性状态并分页查看全部提交。
5. 在“项目设置 → Embedding 语义检索”为现有项目建立真实语义索引。
6. 通过顶部“团队成员”按邮箱邀请成员、分配角色并查看真实在线状态。
7. 通过“当前需求”切换每条需求的独立证据图谱，点击证据可查看真实文件片段。
8. 点击“RAG Agent”向仓库提问，核验回答引用、文件行号及工具执行轨迹。
9. 点击“运行真实审查”，生成基于当前仓库数据的结论与评分。
10. 在“真实仓库审查”中点击“自动修复代码”，审阅并下载补丁，勾选确认后再应用到工作区。
11. 确认信任项目后运行测试，检查 `git diff`，再由团队成员决定是否提交代码。
12. 进入“截图验收对比”，上传设计稿和实际页面截图，运行真实像素比较。

> 安全说明：仓库索引和 RAG 工具始终只读，默认不执行任何项目脚本。自动修复只对 Git 仓库生效，模型生成的补丁必须通过路径、类型、大小、敏感文件、工作区版本和 `git apply --check` 校验，并由负责人或开发成员明确确认后才能写入；系统不会自动提交或推送。只有用户在测试确认框中明确勾选信任后，系统才会运行所选 npm 测试脚本；脚本拥有当前用户权限，120 秒超时限制不等同于操作系统沙箱，请勿运行不可信项目。

> 团队说明：当前版本已提供账号登录、邮箱邀请、服务端角色校验和单节点 SSE 实时协作。生产环境横向扩容时仍需迁移到共享数据库、持久会话服务和分布式事件总线。

## 技术栈

React、TypeScript、Vite、原生 SVG 证据图谱、Node.js 安全 API 适配层。