5.2 KiB
5.2 KiB
Trellis 升级与项目状态多维审查
Goal
确认本项目 Trellis 与上游版本差异，制定可回滚的升级方案；同时从任务治理、代码与测试、文档事实源、仓库卫生、交付与运维等角度梳理当前项目状态，输出分级改进、优化和精简建议。
What I already know
- 当前分支为
main，审查开始时工作区干净。 - 当前没有正式 active task；旧的
05-31-hyinda-light-ops-greenfield仅来自 stale session fallback。 - 项目只启用 Codex 适配，Trellis 不自动提交。
- 非微小改动必须先给出方案并等待批准。
- 近期已经完成过多维系统审查和五人团队正式内用最小收口，需要优先复用结论，避免重复造文档。
Assumptions (temporary)
- “升级 Trellis”指升级当前项目内由 Trellis 管理的模板、脚本和 Codex 适配文件，不修改全局 npm 包源码。
- 本阶段只做只读审查、版本比对和方案设计；升级与冲突处理在用户批准后实施。
- 审查建议应区分立即处理、近期优化和可暂缓项，并明确收益、风险与验证方式。
Open Questions
- 待版本与模板漂移盘点后，只保留会实质影响升级范围的偏好问题。
Requirements (evolving)
- 识别已安装 Trellis 版本、项目记录版本和可用最新版。
- 识别 Trellis 管理文件的本地修改、模板漂移、潜在覆盖冲突和升级回滚点。
- 复核现有 task、spec、docs、代码结构、测试与质量门禁、仓库产物和交付流程。
- 复用既有事实源与历史审查，不轻易新建常驻文档。
- 输出按优先级排序、可执行且避免过度治理的改进建议。
Scope
- Trellis：全局 CLI 版本、项目模板版本、迁移、Codex hooks/agents/skills、task/spec/workflow/config 兼容性。
- 工程：服务端、前端、测试与发布门禁的当前可执行状态；本阶段不主动重构业务代码。
- 治理：task 生命周期、事实源状态、文档注册、历史 Issue 与 Trellis archive 的保留边界。
- 仓库：已跟踪与本地忽略产物、体积热点、可安全清理项和防复发规则。
- 交付：本地候选、部署、公网/真机/真实数据等状态边界是否仍准确。
Acceptance Criteria (evolving)
- 给出 Trellis 当前版本、目标版本、升级命令、冲突预案与验证清单。
- 给出项目现状摘要，并以证据路径支撑关键结论。
- 建议覆盖改进、优化、精简三个方向，并区分优先级。
- 在任何非微小修改前获得用户批准。
- 获批实施后通过 Trellis 治理、文档注册、核心前后端及
git diff --check等适用验证。
Acceptance Evidence
- Trellis CLI 与项目模板均已升级到 0.6.9；升级后 dry-run 不再产生 manifest 变化，仅识别五个预期本地定制文件。
- 项目实际 Python 3.9.2 已通过
.trellis/scripts与.codex/hooks全量编译检查；并修复 0.6.9task_context.py的嵌套多行 f-string 兼容问题。 - Trellis task 的 validate/current/list、governance、process contract、敏感扫描与功能矩阵通过。
- Prisma validate 通过；服务端 161 个测试文件、985/985 测试通过；前端 typecheck 与 production build 通过。
- 文档 registry 仅保留既有 22 项假阳性 warning，原因和后续独立治理建议已记录在 research，不作为本次升级失败项。
- 交付状态继续限定为
LOCAL_CANDIDATE_PASS；本任务未部署、未执行公网检查或真实数据操作。
Definition of Done (team quality bar)
- 适用的 lint、typecheck、测试与流程检查通过。
- 升级差异经过人工审阅，本地定制不被静默覆盖。
- 事实源或任务记录按需更新，不制造重复文档。
- 升级与审查改动形成中文提交并引用任务名。
Test Plan
- 升级前后分别运行
trellis update --dry-run，确认版本、迁移、新增文件、本地修改和用户数据保护行为。 - 运行 task validate、Trellis governance、文档 registry/process contract、敏感内容扫描和
git diff --check。 - 运行
bash scripts/check-minimal.sh，覆盖 Prisma validate、服务端全量 Vitest、前端 typecheck/build 和功能矩阵。 - 仅在修改业务代码或页面行为时追加聚焦服务端/Playwright；本轮默认不部署、不做公网或真实数据检查。
- 升级后复核 Codex hooks、active task 解析、
get_context.py和 task 生命周期基本命令。
Out of Scope (explicit)
- 公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款。
- 未经批准的大规模业务功能重构。
- 启用 Codex 之外的 AI 平台适配。
Technical Notes
- Trellis task：
.trellis/tasks/07-26-trellis-upgrade-project-audit/ - 工作流：
.trellis/workflow.md - Trellis 项目规约：
.trellis/spec/hyb-oa/ - 关键业务事实源：
docs/文档索引.md、docs/文档事实源状态矩阵.md、docs/Agent开发交付实践.md
Research References
research/current-state-audit.md：Trellis 0.6.9 升级预演、当前质量门禁、业务开放项、依赖、文档与仓库卫生审查结论。