基于 Vue 3 和 Vite+ 的 CC98 论坛前端。
| 开发者类型 | 需要自行准备 | 说明 |
|---|---|---|
| 普通开发者 | Vite+ 的 vp CLI |
进入仓库后执行 vp install，其余项目工具由仓库管理 |
| 真实接口验证者 | 浙江大学校园网或代理、CC98 账号 | 账号写入 .cc98-credentials.local；普通构建和离线测试不需要 |
| 并行或自动化开发者 | Worktrunk；按需安装浏览器运行环境 | Worktrunk 用于多 worktree；浏览器环境运行 vp exec agent-browser install |
| 部署维护者 | Vercel 项目权限；按需安装 Vercel CLI | 普通开发者不需要；生产域名维护还需要相应 DNS 权限 |
安装依赖并启动开发环境：
vp install
vp run dev需要隔离开发时，当前 Agent 运行：
wt switch --create <type>/<short-desc> --base=@ --no-cd --format json分支名按任务意图选择 feature/、fix/、docs/ 等前缀，具体约定见 docs/collaborating.md，不要使用 Agent 或工具名作为固定前缀。Worktrunk 会返回新 worktree 的 path。Agent 之后必须把所有命令的工作目录和文件编辑路径切到该目录，并用 git branch --show-current、git rev-parse --show-toplevel 确认位置。不要使用 -x codex，它会启动另一个 Codex 进程，无法切换当前任务。
新 worktree 从已提交的 HEAD 创建，不包含当前目录尚未提交的改动。任务依赖这些改动时，应继续使用当前目录，不能直接创建 worktree。Worktrunk 会按 .config/wt.toml 复制 .worktreeinclude 中声明的本地文件，再运行 vp install --frozen-lockfile --prefer-offline。
本地登录文件约定如下，均已被 Git 忽略：
# .cc98-credentials.local
CC98_USERNAME=example
CC98_PASSWORD=example浏览器自动化和 API 登录探测共用这份账号密码。API 探测会在运行时获取短期 access token，进程结束后直接丢弃，不需要另外维护 token 文件。普通环境检查不读取或打印凭证。
vp run dev # 通过 portless 启动当前 worktree
vp run preview # 构建并预览生产产物
vp run docs:dev # 启动用户文档站
vp run docs:preview # 构建并预览用户文档站
vp run ready # format + lint + typecheck + test + build测试站部署在 Vercel，项目根目录保持为仓库根目录。Vercel 会按 vercel.json 构建主站及其传递依赖，并发布 apps/website/dist。主站源码、静态资源、API 契约源码、UBB 或相关构建配置发生变化时才会部署；测试、探测数据、生成文档和 README 等非构建输入不会触发主站部署。Vue Router 使用 history 模式，所有未命中静态文件的请求都会回退到 index.html。
用户文档使用独立的 Vercel 项目 cc98-docs，根目录是 apps/docs。只有文档内容、文档站配置、静态资源或相关依赖发生变化时才部署文档站。PR 会生成文档预览，main 分支发布到 https://cc98-docs.vercel.app。
两个项目都通过 ignoreCommand 对比当前提交和该分支上一次成功部署的提交，跳过无关变更。共享 lockfile 或 workspace 依赖配置发生变化时，会分别比较主站和文档站的依赖图，只部署实际受影响的项目。
Vercel CLI、skill 和账号授权是维护者本地工具，不属于 workspace 依赖。普通协作者只需使用仓库中的 vercel.json；有项目权限的维护者可以自行使用 Vercel CLI、MCP 或控制台管理部署和域名。CLI 生成的 .vercel/ 只保存本地项目关联，不提交到仓库。
生产域名为 cc98.shellraining.xyz。在 Vercel 项目中添加该域名后，按控制台给出的目标值配置 CNAME。项目会从浏览器直接访问 CC98 API、OpenID 和 SignalR 服务，测试用户仍需具备相应的校园网访问条件，相关服务也需要允许该域名发起跨域请求。
查询当前 worktree 的稳定地址：
PORTLESS_PORT=1355 PORTLESS_HTTPS=0 PORTLESS_SYNC_HOSTS=0 vp exec portless get cc98主 worktree 默认为：
http://cc98.localhost:1355分支 worktree 使用 http://<branch>.cc98.localhost:1355。所有 worktree 都运行 vp run dev，portless 会分配应用端口并注册对应域名。端口代理使用普通 HTTP 和高位端口，不需要管理员授权或本地 CA。
vp run preview 会先执行全量构建，再用 Vite Preview 启动生产产物。主 worktree 使用 http://cc98-preview.localhost:1355，分支 worktree 使用 http://<branch>.cc98-preview.localhost:1355，可以和 dev server 同时运行。
环境异常时直接使用各工具的标准诊断命令：
vp env current
vp env which node
vp env which pnpm
vp exec agent-browser doctor
PORTLESS_PORT=1355 PORTLESS_HTTPS=0 PORTLESS_SYNC_HOSTS=0 vp exec portless doctor
wt config show
wt list
vp exec -F @cc98/api apifox --help