# paper-agent **Repository Path**: mzb329/paper-agent ## Basic Information - **Project Name**: paper-agent - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-29 - **Last Updated**: 2026-10-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Graduation Agent Workbench (毕业设计 Agent 工作台) 托管**长期 Claude Code 主会话**的毕业设计管理工作台。1 个项目 = 1 个逻辑 Claude Code 主会话。 Workbench 负责项目管理、会话生命周期、工作区、进度、3 个人工 Gate、日志、文件、Git 检查点、队列/并发、恢复、交付；规划、编码、测试、搜索、Docker、论文、DOCX、PPT、最终 QA 由 Claude Code 自己完成。 ## 核心模型 ``` ┌──────────────────────────────────────────────────────────────────┐ │ Workbench（本仓库） │ │ ├─ API (NestJS) — REST + 鉴权 + 审计 + 文件接口 │ │ ├─ Worker (BullMQ) — 每个 job = 一个 claude -p 回合 │ │ ├─ Recovery — 60s 扫描陈旧回合 → RECOVER_SESSION │ │ ├─ Gates — ARCHITECTURE/CODE/FINAL 三个人工 Gate │ │ ├─ wbctl CLI — 机器可读控制协议 (control.json/control.env)│ │ └─ Web (Next.js) — 仪表盘 / 项目详情 / Gate 评审 / 管理 │ │ │ │ 每项目工作区: CLAUDE.md + PROJECT/PROGRESS/DECISIONS/RESEARCH.md │ │ + SOURCES.json + .claude/settings.json + hooks + .git │ │ + input/source/thesis/figures/ppt/tests/artifacts/delivery │ └──────────────────────────────────────────────────────────────────┘ │ claude -p --session-id …（host 或 docker 隔离） ▼ Claude Code 长期主 Agent（规划/Subagent/编码/搜索/论文/交付） ``` ## 快速开始（开发）前置：Node 22+、pnpm 11、PostgreSQL、Redis、S3 兼容对象存储（MinIO/s3rver）、Claude Code CLI、Docker（可选）。 ```bash cp .env.example .env # 填 JWT_SECRET / DATABASE_URL / 凭据 pnpm install docker-compose up -d postgres redis s3 # 或用本地 PostgreSQL/Redis/MinIO pnpm db:migrate && pnpm db:seed pnpm build # 构建 API + wbctl pnpm run install:wbctl # wbctl 全局可用（Claude 在项目内调用） pnpm dev:api & pnpm dev:worker # 或 node apps/api/dist/main.js + dist/worker.js pnpm dev:web # Next.js :3000 ``` 登录：`admin@workbench.local`（管理员）与 `member@workbench.local`（成员）。密码**必须**来自 `.env` 的 `SEED_ADMIN_PASSWORD` / `SEED_MEMBER_PASSWORD`——系统在缺失或使用默认值时拒绝启动（fail-fast），请勿沿用示例中的占位密码。 ## 一键启停 / 预览网址 / 测试账号（生产）平台（API :4000 + Worker + Web :3000）可用 `platform.sh` 一键管理，进程由 `.workbench-data/run/*.pid` 追踪： ```bash ./platform.sh start # 生产模式启动全部（需先 pnpm build） ./platform.sh start --dev # 开发模式（nest watch / next dev） ./platform.sh stop # 停止全部（逆序 web→worker→api，端口兜底清残留） ./platform.sh restart # 重启全部 ./platform.sh status # 进程状态 + 健康检查 + 预览网址 + 测试账号密码 ``` **预览网址** | 服务 | 地址 | |------|------| | 管理台 Web | http://localhost:3000 | | API 健康检查 | http://localhost:4000/api/health | | 项目列表 API | http://localhost:4000/api/projects（需要 Bearer token） | **测试账号**（管理员 + 成员，密码实时打印在 `./platform.sh status` 里，来源为 `.env` 的 `SEED_ADMIN_PASSWORD` / `SEED_MEMBER_PASSWORD`——明文不写入仓库）： | 账号 | 角色 | 密码 | |------|------|------| | `admin@workbench.local` | ADMIN（最高权限） | 见 `.env` 的 `SEED_ADMIN_PASSWORD` / `./platform.sh status` | | `member@workbench.local` | MEMBER | 见 `.env` 的 `SEED_MEMBER_PASSWORD` / `./platform.sh status` | 日志：`/tmp/gaw-api.log`、`/tmp/gaw-worker.log`、`/tmp/gaw-web.log`。 ## Web 界面功能：运行预览 / 启停 / 账号管理 **运行预览（页面内打开交付系统）**——项目详情页「运行预览」tab： - 交付系统运行后**自动检测 Web 端口并自动打开预览**（无需手动输入地址）；也可手动填写保存 `previewUrl`（仅 http/https，协议白名单在 API 校验）。 - iframe 直接预览，支持「新窗口打开」和刷新。 - 「启动 / 停止」按钮控制交付系统自身的 docker compose 栈：Workbench 在项目工作区的 `delivery/` 里发现 compose 文件，对它执行 `docker compose start/stop`（argv 传参、不拼 shell；MAINTAINER+ 权限；全程审计 `project.runtime.start/stop`）。 - 容器列表实时显示状态/健康/端口；**演示账号/初始登录信息自动从交付文档提取展示**（带复制）。需要 MAINTAINER 及以上权限。 **账号信息管理**——系统管理页（仅 ADMIN）：新建用户、改角色、**重置密码**、**启用/停用**账号（不能停用自己），列表显示账号创建时间。 ## 共享环境池所有毕设系统共用一套数据中间件与 LLM 接入（单例），不再一套系统一套中间件： - **数据中间件单例**：MySQL `gaw-mysql`(:3306) / PostgreSQL `gaw-postgres`(:5432) / Redis `gaw-redis`(:6379) / S3(:9000)。 - **LLM 接入单例**：`base_url` / `api_key` / `model_name` 三件套统一由环境池提供，全项目共用一把 key。 - **每项目逻辑隔离**：独立库 `db_` + 独立账号 + Redis 逻辑库，互不影响。统一用 `scripts/env-pool.sh` 管理（幂等，凭据不写入仓库、明文见 `.env` 与环境池文件）： ```bash ./scripts/env-pool.sh up # 启动共享栈 ./scripts/env-pool.sh status # 共享栈健康 + 各项目配额 ./scripts/env-pool.sh grant # 建库建号 + 生成凭据文件 ./scripts/env-pool.sh init-db [data.sql...] # 初始化共享库 ./scripts/env-pool.sh down # 停止共享栈（保留数据卷） ``` 凭据在 `.workbench-data/env-pool/.env`（已 gitignore）。 **新项目自动注入池纪律（scaffold）**：新建项目的脚手架模板自动注入「共享环境池」硬规则——数据库连 `host.docker.internal` 共享实例、compose 用 `docker compose --env-file <环境池文件> up -d` 注入凭据。**交付系统禁止自带中间件容器、禁止硬编码密码/key、禁止自选端口、禁止给密钥写可预测的兜底默认值** （compose 用 `${VAR:?}` 强制注入，配置文件里的默认值兜底同样禁止）；需要新中间件能力先由环境池统一提供。详见 [docs/ENV-POOL.md](docs/ENV-POOL.md)。 ## 一段典型流程 1. 在 Web 新建毕设项目 → 创建工作区 + git init + RUN_PROJECT 入队 2. Worker 拉起 `claude -p`（固定 `--session-id`）→ 流式事件 → 原始日志持久化 3. Claude 维护状态文件，联网调研写入 RESEARCH.md / SOURCES.json，关键节点 commit 4. 完成阶段目标 → `wbctl gate request architecture|code|final` → **停止等人工** 5. 人工在 Web 评审 Gate（批准/需修改/驳回）→ GATE_APPROVAL 回合 **resume 同一会话** 6. …直到 3 个 Gate 全批 → 最终交付 ZIP → COMPLETED ## 完成定义（Workbench 校验，非 Claude 声称） 3 个 Gate 全部 APPROVED + FINAL-QA.md 无 BLOCKER + delivery/ + 交付 ZIP 成功 + Git 检查点 + 原始日志 + RESEARCH.md/SOURCES.json（文件与索引）+ 交付物 + 无 secrets 进 Git。全部由 `completion.service` 逐项校验。 ## 目录 ``` apps/api NestJS API + BullMQ worker + 恢复 + 评审门 + 完成校验 apps/web Next.js 16 + Tailwind 4 管理台 packages/wbctl 机器可读控制 CLI（Claude 侧调用） docker Dockerfile.api / .web / .claude（隔离容器镜像） docs RESEARCH.md / SOURCES.json / 官方文档存档 ``` ## 文档 - [ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构与数据模型 - [CI.md](docs/CI.md) — CI 配置现状（Gitee 上如何启用、GitHub 迁回零改动） - [CLAUDE-RUNNER.md](docs/CLAUDE-RUNNER.md) — Claude 会话/回合/恢复机制 - [DEVELOPMENT.md](docs/DEVELOPMENT.md) — 开发指南 - [DEPLOYMENT.md](docs/DEPLOYMENT.md) — 部署 - [SECURITY.md](docs/SECURITY.md) — 安全设计（secrets 脱敏、路径防护、hook 策略） - [docs/RESEARCH.md](docs/RESEARCH.md) + [docs/SOURCES.json](docs/SOURCES.json) — 工程调研 ## 明确不做（边界）不实现/复用 DSH；不重新实现 Claude Code 的 Agent/Tool/Subagent/harness/模型路由；不维护 30+ 状态机（状态少而清晰）。Claude Code 负责一切 Agent 能力。