Files

T

yuxuanhui 91861565bb feat: add frontend development guidelines and structure documentation

- Introduced API guidelines for interface contracts and request handling.
- Added design tokens usage guidelines for consistent styling across the project.
- Established DTO guidelines for defining request parameters and response data types.
- Created frontend structure guidelines to clarify directory organization and code placement rules.
- Compiled a comprehensive frontend development guideline document covering various aspects of the development process.
- Implemented quality guidelines to ensure code maintainability and adherence to best practices.

2026-07-25 22:20:25 +08:00

4.2 KiB

Raw Permalink Blame History

id, title, created, updated, status, scope, category, confidence, last_verified, promotion_target, projects, tags

title

created

updated

status

scope

云端运行时不要依赖 process.cwd() 推断项目根目录

Trigger

本地测试能读到配置或资源，但部署到云端后同一流程表现为配置缺失、鉴权未执行、文件不存在、资源路径 404，且日志里只看到后续业务失败。

Context

一次 Playwright 云端测试排查中，测试进程能访问目标页面，但前置鉴权没有执行，页面最终停留在登录页。最初怀疑是 cookie/sessionStorage 写入失败、Chrome 限制或跨域问题。后来通过运行时证据确认：fixture 已经执行，但没有读到项目 auth 配置。

关键差异是云端 Playwright 进程的 process.cwd() 是应用包目录，而项目文件和 .evaluator/projects/<id>.json 在另一个工作目录。代码用 process.cwd() 推断项目根目录，导致读取了错误位置的配置文件。

Evidence

2026-06-26/27，evaluator-agent 云端测试排查。
运行时 auth-setup 证据显示：projectIdPresent=true，但 authConfigured=false，authApplied=false。
临时深度诊断曾显示运行时尝试读取 /app/.evaluator/projects/<project-id>.json，但实际项目产物位于 /workspace/project/...。
修复提交：ee1e9b0 Fix Playwright project root resolution for auth config。
相关文件：
- packages/core/src/evaluator/run.ts：启动 Playwright 时传入 EVALUATOR_PROJECT_ROOT=projectRoot。
- packages/playwright/src/fixtures/ai-test.ts：fixture 读取配置时使用 EVALUATOR_PROJECT_ROOT || process.cwd()。
- .trellis/spec/frontend/run-analysis-contracts.md：记录云端 cwd 与项目根目录可能不同的契约。
清理提交：8547bd1 chore: remove temporary auth debug diagnostics，保留稳定布尔证据，删除过细路径/配置探测字段。

Root cause

已验证原因：云端运行进程的 cwd 不等于项目根目录。配置读取逻辑把 process.cwd() 当作项目根，导致读取错误路径，表现为配置不存在。

推断：类似问题也可能发生在测试报告、静态资源、项目级配置、凭证文件、生成产物、fixture 初始化、CLI 子进程中，只要代码通过 cwd 隐式推导项目根。

Preferred action

对需要部署到云端或由子进程执行的代码：

显式传递项目根目录，例如 PROJECT_ROOT / EVALUATOR_PROJECT_ROOT，而不是在下游模块里直接信任 process.cwd()。
子进程启动处负责设置这个 env；fixture、worker、CLI helper 只读取显式根目录并保留 process.cwd() 作为本地直跑 fallback。
在运行产物里记录低风险、结构化的健康检查字段，例如 projectIdPresent、authConfigured、authApplied，用于远程确认流程是否执行。
临时深度诊断可以短期记录路径、config existence 等字段定位问题，但修复后应清理，避免长期暴露内部部署结构。
把这个约束写成项目契约或测试，防止以后又退回 cwd 推断。

Boundaries

本地单进程脚本、一次性维护脚本、明确从仓库根执行的工具可以使用 process.cwd()，但要把这个前提写清楚。
不要把密码、token、cookie 值、请求 body/header 值写入诊断产物。
路径诊断是否保留要看用户场景：短期排查可以详细，长期产品化证据应收敛到必要布尔状态和可操作错误摘要。

Failed approaches

先排查 cookie/sessionStorage、CORS、Chrome flags 和页面 JS 错误，虽然有价值，但没有直接回答“fixture 是否读到配置”。
临时把 configPath、configFilePresent、projectRoot 等字段加入运行时证据能快速定位问题，但不适合作为长期默认产物。
不推荐把配置复制到云端 cwd 对应目录；这会形成两份配置，后续 UI、测试和服务端可能读到不同来源。

Promotion record

Not promoted.

4.2 KiB Raw Permalink Blame History Unescape Escape