需要 Bun 1.3+ 和 Git。
FastCAS SDK 固定在仓库内的 packages/fastcas-sdk，来源为 FastR-D/FastCAS 的 sdk/typescript，版本提交 676d49b18f700c009f1f491280a93de7da294836。本地使用 TypeScript 源码导出并适配严格可选属性检查；无需克隆相邻的 FastCAS 仓库或预先构建 SDK。更新 SDK 时应同步检查上游接口和身份认证契约测试。
bun install
pnpm run dev打开 http://localhost:3002（Vite 前端代理 API）。pnpm run dev 自动进入专用开发管理员 Admin (开发)，可查看全部项目，并通过 /admin 查看平台全局信息。
pnpm run main 启动相同的前后端开发服务，但使用正常登录流程并强制开启服务端认证；开发管理员的令牌在此模式下无效。两个命令使用相同的数据目录。首次运行 main 且没有正式管理员时，需要设置 FASTWRITE_BOOTSTRAP_ADMIN_EMAIL 和 FASTWRITE_BOOTSTRAP_ADMIN_PASSWORD（至少 12 位），之后使用该账号登录；开发管理员不计作正式管理员，也没有可用于正常登录的默认密码。
工作区 PDF 预览使用服务器 LaTeX 编译，需要安装 latexmk 或 pdflatex 以及论文使用的 TeX 包。启用 FASTWRITE_SERVER_AUTH=true 时强制使用 Linux bubblewrap 沙箱，宿主机必须允许其创建隔离命名空间；缺少沙箱会拒绝编译。Windows 本地开发如需在开启鉴权的情况下编译，应把服务部署到具备这些依赖的 Linux/WSL 环境。单人、受信任的本地模式可使用宿主编译，但不会加载项目的 latexmk 配置或启用 shell escape。
选定 venue 的 LaTeX 模板首次成功获取后会缓存到 FASTWRITE_DATA_DIR/templates/（未配置时为默认数据目录）；后续初始化直接使用本地缓存，不会重复下载。
bun install
bun run build
bun start可通过 FASTWRITE_PORT 修改端口，通过 FASTWRITE_DATA_DIR 指定 Workspace 数据目录。
设置 FASTWRITE_SERVER_AUTH=true 后，Harness 状态与 MCP 目录查询需要登录；共享 CLI 的原始会话、运行记录、事件、审批及全局 Harness 配置修改仅允许平台管理员访问。项目内 AI 操作继续遵循项目权限，指定项目的 MCP 审计需要该项目的 Harness 使用权限，全局审计仅限管理员。原始 Harness WebSocket 使用与 HTTP 相同的 Authorization: Bearer ... 或 X-FastWrite-Session 请求头认证，不接受 URL 中的登录令牌；连接在握手、历史回放、每次事件推送及定时检查时校验权限。浏览器原生 WebSocket 无法设置这些请求头，浏览器客户端可使用已认证的 HTTP 事件接口。
启用 FASTWRITE_SERVER_AUTH=true 时，若数据库没有有效管理员，必须同时设置 FASTWRITE_BOOTSTRAP_ADMIN_EMAIL 和 FASTWRITE_BOOTSTRAP_ADMIN_PASSWORD（自行生成至少 12 位的唯一密码），否则服务拒绝启动。没有默认管理员账号或密码；公开注册始终创建普通用户。初始化成功后可以移除这两个变量，已有管理员可正常登录。修改初始化变量不会重置已有账号密码；升级前已使用旧版默认账号的部署需单独轮换该账号密码。
原始 Claude Harness 已内置 CLI 执行桥接，无需注入 SDK 才能发送消息。它要求 Claude Code 2.1.286 或更新版本，支持文本流、会话恢复和取消；使用 --bare 并关闭工具、MCP 和项目配置自动加载。此模式需要按 Claude 的提供商要求配置凭据（如 ANTHROPIC_API_KEY），不使用订阅登录。审批、自动加载技能及 MCP 能力会报告为不支持；需要这些能力时可注入完整的 ClaudeSdkBridge。CLI 参数与事件格式参考 Claude 官方程序化调用文档。FastWrite 写作 API 的 FASTWRITE_HARNESS_* 配置与原始 CLI 凭据是分别配置的。
当前运行时由单个服务进程处理任务队列和邮件；不要设置 FASTWRITE_JOB_WORKER_MODE=external 或另外启动 worker:jobs / worker:mail。这些入口现在会明确拒绝启动，避免独立进程使用过期 JSON 快照覆盖数据。PostgreSQL mirror/cutover 配置仍使用本地队列快照，不代表已经支持分布式 worker。每个数据目录仅运行一个服务；检测到其他写入者时会拒绝保存过期状态。若进程被强制终止留下 database.json.write.lock，先停止使用此目录的全部进程，再移除该锁文件并重启。
写作质量接口：POST /api/projects/:projectId/writing-checks 执行确定性检查；GET /api/projects/:projectId/argument-graph 获取论证关系；POST /api/projects/:projectId/adversarial-memo 生成仅供参考的对抗预检意见。Claim 侧栏支持 stale claim 的 reanchor；Agent 生成候选会校验 Writing Guard 与 evidence dependencies；Review 报告会显示各 pass 的完成、失败或跳过状态。评测可运行 bun run writing:eval。
IDE 的“参考论文”侧栏支持添加或拖放 PDF、包含 TeX/PDF 的 ZIP（上传上限 30 MB）。多入口压缩包需要选择主文件；解析后可按全文、章节、PDF 页码或原文选段设置参考范围，并选择借鉴结构、段落、论述或表达。保存后，写作区会显示参考标签；侧栏可指定当前选区、章节、文件或整篇论文作为写作目标。Draft/Continue/Agent 和 Revise 使用参考写法，超过局部精修长度限制的当前章节会交给限定章节范围的 Agent，结果继续通过原有 ChangeSet 审核；Completion 只读取已缓存的精简写法，可先点击“准备写作参考”。扫描 PDF 无文本时需要提供有文字层的 PDF 或 TeX 源码；首版不提供 OCR 或 TAR/RAR 导入。
参考材料保存在 FASTWRITE_DATA_DIR/projects/<projectId>/reference-papers/，与正文 workspace/ 分开，避免进入正文编译、GitHub 同步、Paper Memory 或事实证据。备份项目文件时需复制整个项目目录，包括参考材料；现有 JSON 数据库备份不包含原始文件或解析文件。普通论文 ZIP 导出仍只包含正文工作区。验证参考功能可运行 bun test apps/server/src/references、bun run references:eval 和构建后的 bun run e2e:references。配置真实模型后，bun run references:eval -- --live 会使用合成论文验证真实模型的参考写作链路。
先让Agent解决 BUG.md中问题，解决了的移到BUG-done.md。 等待期间，去测试功能，将Bug记录到BUG-new，等完成再继续下一轮Bug修改。
数据库备份恢复必须停服执行，在线恢复接口返回 409 offline_restore_required。源码目录中运行：
bun run backup:restore -- --data-dir /absolute/path/to/paperdata --file /absolute/path/to/backup.json --confirm replace-database对象存储备份可把 --file 换成 --object-key backups/backup-name.json，并提供部署时相同的 FASTWRITE_OBJECT_STORE_* 配置。命令校验备份格式和当前 schema，保存恢复前的安全副本，再替换数据库；完成后重新启动服务。JSON 备份仅包含数据库，项目文件需另外备份并放回匹配的数据目录。服务和恢复命令使用 .fastwrite-process.lock 互斥；若被强制终止留下锁文件，须确认该目录的全部进程已停止后再移除。旧版本备份应先使用匹配版本恢复，再按升级流程迁移。
bun run package:app
./app-bin/fastwrite该命令生成可直接发布的单个 app-bin/fastwrite。Web 静态资源嵌入该二进制；外置的 app-bin/skills/ 和 app-bin/paperdata/ 与二进制并列，后者保存 Workspace、导入和编译缓存，重新打包不会删除它。根目录存在 .env 时会在首次打包时复制至 app-bin/.env，否则生成 .env.example；二进制会自动加载同级 .env。浏览器打开二进制输出的地址即可正常测试和编辑 Paper。
.github/workflows/ci.yml 会在 push 和 pull request 时自动运行类型检查、单元测试、构建和浏览器 E2E。推送与根 package.json 版本一致的标签（例如 v0.1.0）会触发 .github/workflows/release.yml，在完整测试通过后创建 GitHub Release，并发布 Linux x64、Windows x64、macOS Intel 和 macOS Apple Silicon 安装包。macOS 包当前未进行 Apple Developer 签名或 notarization，首次运行可能出现 Gatekeeper 提示。
在 .env 设置 FASTWRITE_HARNESS=codex 或 claude，并配置 FASTWRITE_HARNESS_API_KEY、可选的 FASTWRITE_HARNESS_BASE_URL、FASTWRITE_HARNESS_MODEL、FASTWRITE_HARNESS_WIRE_API 和 FASTWRITE_HARNESS_TIMEOUT_MS，即可为全部 AI 工作流配置统一 Harness。Project Settings 也可运行时配置这些 Harness 参数；API key 只保存在内存中且不会回传。Agent 规划、普通 AI 操作以及 /draft、/continue、/revise 的完整文件生成默认超时均为 300 秒，可用 FASTWRITE_HARNESS_TIMEOUT_MS 覆盖（最大 600 秒）。导入私有 GitHub Repository 时设置 FASTWRITE_GITHUB_TOKEN。
验证 .env 中的真实 LLM 配置：
bun run llm:smoke