Decision：项目蓝图新建与整份归档

状态：implemented 类型：feature Owner：backend/package/yuxi/services/project_blueprint_service.py 日期：2026-09-27 关联 Feature：项目蓝图 Workdir 事实源

问题

项目工作台的新建入口调用整体替换接口，同名文件可被覆盖，且没有明确的新建结果。旧蓝图一直留在当前列表，项目演进后缺少可翻阅的历史位置。默认 Dashboard 直接展示 Markdown 原文，项目概览难以阅读。

决策

新建入口补全缺失的 .md 后缀，在页面上只显示文档名。后端独占创建文件，同名返回 409。创建成功后回读并选中该文档，使正文可以立即编辑。Dashboard 通过既有 Markdown 预览组件显示蓝图正文。

项目工作台将旧蓝图按整份文档归档。归档文件仍在同一 Project Workdir 的 .yuanlei/blueprint/archive/ 中，归档名称包含原名、UTC 时间和随机标识。Linux Workdir 使用不可覆盖的原子重命名；内核不支持时显式失败。当前列表只显示未归档蓝图；历史列表按归档时间展示，归档正文只读。归档文件可以从 Workdir 被 Agent 或其他文件工具访问，因此页面只读不是文件系统级不可变保证。

项目归属校验继续在蓝图用例执行；文件操作继续经 Workdir capability。目录被文件或链接占用时返回冲突，缺失文档返回 404。并发写入替换同名文件时，归档移动的是原子重命名发生瞬间占据该名称的普通文件。现有 PUT 仍承担 Agent 与人的整体替换写入，沿用原有并发语义。

替代方案

• 每次保存都生成历史版本：会增加大量快照与版本选择语义；当前需求只要求保留整份旧蓝图。
• 将归档正文另存数据库：会制造第二事实源，与蓝图 Workdir 约定冲突。
• 只在前端隐藏旧蓝图：文件仍混在当前目录，Agent 和后续页面无法区分当前与历史。

后果

当前蓝图和历史蓝图可分别浏览；归档不等于删除，原文件内容保留。相同原名可以在归档后重新创建新文档。归档不是逐次编辑版本，保存期间仍遵循整体替换语义。默认 Dashboard 与工作台链接采用统一的无下划线视觉样式。

验证

真实 PostgreSQL、Workdir 与 HTTP 集成测试覆盖创建、同名冲突不覆盖正文、整份归档、历史回读及跨用户拒绝；前端名称逻辑单测、lint、unit、build 与真实页面检查；工程契约和文档构建。