Easyuseaide project delivery readiness

项目最低交付准备

目标是让个人或小型项目从“在作者机器上能运行”提升到“新环境可以启动、主要错误可以定位、数据变更可以恢复、发布失败可以回退”。

本 Skill 提供最低交付基线，不建设完整企业平台。只实现项目真实需要的部分，不为了形式增加容器、云服务、数据库、CI 供应商或日志平台。

如果已有框架负责单次任务的测试、完成验证、代码评审或分支收尾，让它继续作为该阶段的主流程。本 Skill 复用其证据，只补齐项目级启动、CI、配置、数据、日志、发布和回滚缺口，不重新执行一套任务收尾流程。

强制首尾动作

加载本 Skill 后，先运行只读检查器，再开始修改：

python3 <本-Skill-目录>/scripts/check_delivery_baseline.py <项目根目录>

交付前再次运行同一检查器，并报告命令、退出码、失败项、证据等级和人工门禁。检查器仍有失败、恢复演练等人工门禁未完成或核心验收未验证时，只能使用“实现完成，交付验证未完成”。不得以已经创建文档、运行普通测试或拥有 Skill 文件为由跳过首尾检查。

1. 适用边界

适用于：

• 项目准备长期维护、公开分享或交给其他人运行；
• 项目需要基础 CI；
• 项目开始使用数据库、文件存储或其他持久化数据；
• 项目准备发布、部署或建立可回滚版本；
• 项目缺少配置隔离、启动说明或可定位错误的日志；
• 用户明确要求检查或补齐交付准备度。

不机械应用于：

• 明确准备丢弃的实验；
• 不保存数据、无需共享的一次性脚本；
• 用户只要求分析且未授权写入；
• 已有成熟交付体系且本次任务与它无关的项目。

生产环境、高风险迁移、真实数据恢复和实际发布仍需要明确授权。本 Skill 可以准备方案和文件，但不会把“准备完成”解释成允许部署或操作真实数据。

2. 先确认项目事实

修改前检查：

• 项目语言、运行时、包管理器和锁文件；
• 当前安装、启动、测试、停止和清理方式；
• 是否已有 README、CI、容器、部署脚本和运行文档；
• 配置从哪里读取，哪些值属于 Secret；
• 是否存在数据库、上传文件、对象存储或本地状态；
• 数据库迁移工具和 Schema 权威来源；
• 当前日志方式和主要故障入口；
• 发布目标、版本方式和现有回滚能力。

优先沿用项目已有命令和工具。不确定时标记待确认，不凭文件名猜测可用命令。

先给出缺口清单和计划；如果会新增依赖、修改数据结构、接触真实凭据或改变发布方式，先确认再实施。

检查器不会读取 .env、数据库、日志、data/ 和常见构建目录。它把结果分成四种证据等级：

• verified：检查器取得了可重复的执行或版本控制证据；
• structure：文件或配置存在，但不表示已经运行；
• unverified：需要真实执行、远端结果或人工演练；
• failure：最低门禁不满足。

PASS 仍可能只是 structure，必须同时阅读证据等级。检查器不能证明全部功能正确，也不能替代人工判断；将结果作为缺口清单的输入，逐项确认适用性。检查器返回失败时，不得通过删除检测项、降低规则或虚构“不适用”来获得通过。

环境没有 python3 时，可以使用已经存在的等价 Python 3 启动命令。没有 Python 3 时不为运行检查器擅自安装依赖；按检查器列出的同一组项目逐项人工复核，并在交付中明确说明自动门禁未运行。

3. 可重复启动

为项目建立一条最短、可重复的本地路径，至少说明：

1. 支持的操作系统或运行环境；
2. 运行时和关键工具版本；
3. 使用锁文件安装依赖的命令；
4. 首次初始化命令；
5. 启动命令；
6. 验证启动成功的方法；
7. 停止和安全清理方法；
8. 常见启动失败的定位入口。

命令应与项目真实配置一致。README、项目规则和 CI 不维护三套不同命令。

可行时在干净的临时环境、容器或新克隆中验证；无法使用干净环境时，明确说明只验证了当前工作区。

不要把真实 Secret、生产配置或私人数据写进启动示例。清理命令不得默认删除用户数据。

4. 配置与密钥隔离

区分：

• 可以进入代码的稳定默认值；
• 普通环境配置；
• Secret；
• 运行时产生的数据。

最低要求：

• 提供安全的 .env.example 或等价配置示例，只包含变量名、说明和匿名值；
• 确认真实 .env、本地凭据和运行数据被版本控制忽略；
• 应用启动时校验必要配置，错误只说明缺少的变量名，不输出变量值；
• 本地、CI 和部署环境使用各自的配置来源；
• 日志、异常和测试夹具不包含真实 Token、密码、连接串或个人数据；
• 安装脚本、健康检查、自检、机器可解析输出和 Agent 回复不返回 Secret 值，只返回安全引用或由目标系统的 Secret 机制传递；
• 不把经过截短或轻微修改的真实凭据当成示例；
• 不使用 cat、head、tail、echo、字符串切片或 Shell 调试模式输出 Secret 文件或变量；
• 只用存在性、权限、路径和不可逆指纹验证 Secret，不把值写入终端、日志或对话。

根据项目情况读取 assets/templates/env.example 并改写为真实变量集合，不机械保留无关示例项。

5. 数据备份与迁移

项目没有持久化数据时，记录“不适用”及依据，不引入数据库或备份系统。

项目存在持久化数据时：

1. 列出数据源、Schema 权威来源和需要备份的内容；
2. 明确备份命令、输出位置、权限、加密需求和保留策略；
3. 备份文件名包含日期、版本或可追踪标识；
4. 备份完成后验证文件非空、格式可读并记录校验信息；
5. 提供恢复步骤，并在隔离环境进行至少一次恢复验证，记录日期、命令、结果和核心数据检查；
6. 迁移同时验证空库初始化和从上一支持版本升级；
7. 说明应用与迁移的执行顺序；
8. 优先使用向前修复或扩展—迁移—收缩，避免直接破坏旧数据；
9. 无法安全回滚的迁移必须明确标注，并在执行前备份和确认。

SQLite、PostgreSQL、MySQL、文件目录和对象存储需要不同方式。使用项目实际技术的官方工具，不用文件复制冒充数据库一致性备份。

根据项目情况读取：

• assets/templates/docs/runbooks/backup-and-restore.md
• easyuseaide-dependency-research Skill（需要确认工具或版本行为时）

6. 最基础的错误日志

日志的目标是让维护者回答“哪里失败、处理什么、影响什么、下一步看哪里”，不是记录所有内部数据。

最低要求：

• 启动成功和启动失败有明确日志；
• 未处理异常、后台任务失败和外部依赖失败不会静默消失；
• 使用一致的时间、级别、事件名称和消息；
• 请求型或异步项目在可行时包含 request_id、correlation_id 或任务 ID；
• 错误日志包含必要上下文，但不记录 Secret、认证头、完整连接串和敏感 Payload；
• 面向用户的错误响应不暴露堆栈和内部实现；
• 日志级别可以配置，但默认配置足以定位主要错误；
• 测试至少触发一个预期失败，确认日志存在且已脱敏。

对于简单 CLI，清晰写入标准错误流并返回非零退出码即可，不强制引入结构化日志依赖。

7. 基础 CI

只在项目确实使用的代码托管或 CI 平台上创建配置。不要默认所有项目都使用 GitHub。

基础 CI 至少应：

1. 在干净环境检出代码；
2. 使用锁文件和受支持运行时安装依赖；
3. 执行与本地一致的快速验证命令；
4. 至少运行项目已有的 lint、类型检查和测试中适用的部分；
5. 对需要数据库或服务的测试使用隔离测试实例；
6. 不访问生产环境和真实数据；
7. 使用最小 Token 权限；
8. 不向来自不可信代码的流程暴露 Secret；
9. 固定第三方步骤或 Action 到当前已核验的不可变版本；需要填写 Commit SHA 时查询官方来源，不编造；
10. 失败时保留足以定位问题的输出，不把绿色状态当成功能完整证明。

CI 不应执行部署，除非用户另外授权并明确设计发布流程。

根据项目情况读取 assets/templates/ci-checklist.md。涉及当前平台语法和版本时，使用 easyuseaide-dependency-research Skill 查询官方文档。

8. Agent、Skill 与 MCP 接入（适用时）

如果项目交付物包含供其他 Agent 使用的 Skill、MCP、插件、Agent API、消息机器人或自动化入口，主要用户旅程通常不是 Web 页面。必须先按 PRD 的主要使用渠道验证真实接入，再把次要界面完成视为项目完成。

最低门禁：

1. Skill 或插件的 metadata、frontmatter、目录结构和相对资产路径可被目标工具严格解析；
2. 使用目标 IDE 或 Agent 的真实发现机制确认资产已加载，文件存在不等于已发现；
3. 用一个命中触发条件的只读场景证明 Skill 正文实际加载，而不只列出名称；
4. 配置和凭据只通过目标系统支持的 Secret 引用传递，不写入 Skill、日志或回复；
5. 必要的 helper、SDK 或协议客户端能够在目标运行环境真实调用，版本与官方文档匹配；
6. 重启或新会话后仍能发现和调用；
7. 重复触发、超时、部分失败和重试不会产生重复副作用或不一致状态；
8. 至少完成一次主要用户旅程的真实端到端验证，并记录日期、工具与模型版本、输入、结果和安全的证据位置；
9. 无法访问真实外部系统时明确写“集成未验证”，不得用 Mock、Web 演示或静态文件替代。

按需读取 assets/templates/agent-integration-checklist.md。项目不包含此类交付物时明确标记“不适用”。

9. 发布与回滚说明

建立可执行但不会自动发布的说明：

• 版本、提交和目标环境等执行输入的来源；
• 发布前需要通过的本地与 CI 门禁；
• 配置、Secret 和数据备份要求；
• 应用与数据库迁移顺序；
• 发布命令或操作；
• 发布成功的健康检查和核心行为验证；
• 停止扩散的条件；
• 回滚触发条件、责任人和步骤；
• 代码回滚后数据库是否仍兼容；
• 无法回滚的数据副作用怎样恢复或向前修复；
• 发布后需要观察的日志和错误。

实际推送、创建 Release、修改部署环境或操作真实数据需要单独的明确授权。

Runbook 只保存跨版本稳定的步骤、条件和恢复方法。不得在 Runbook 中保存当前版本、最新 Tag、Release 是否已创建、本次 CI 结果、最后发布日期或某次发布的勾选状态；这些动态事实只维护在 docs/project-status.md。发布后只更新这个状态文件和必要的外部 Release 记录，不在多个文档中复制同一当前状态。

根据项目情况读取 assets/templates/docs/runbooks/release-and-rollback.md。

10. 运行说明

根据项目规模，创建或更新一份最小运行说明。优先使用现有文档体系；没有合适位置时参考：

• assets/templates/docs/operations.md
• assets/templates/docs/runbooks/backup-and-restore.md
• assets/templates/docs/runbooks/release-and-rollback.md

删除不适用章节，不留下看似完整的空占位。README 只保留快速入口，并链接到详细运行说明，避免重复维护命令和规则。

11. 验证顺序

按成本和风险验证：

1. 从项目文档执行安装和启动命令；
2. 验证健康检查、CLI 输出或最小核心操作；
3. 运行 CI 将执行的同一组本地命令，并在可访问远端时记录真实 CI 结果；
4. 让缺少必要配置的启动安全失败，确认没有泄密；
5. 触发一个预期错误，检查日志和退出状态；
6. 存在持久化数据时，在隔离环境验证备份与恢复；
7. 验证迁移的空库路径和上一版本升级路径；
8. 项目包含 Agent、Skill、MCP、插件或消息入口时，验证真实发现、触发、重启持久性和主要用户旅程；
9. 对发布和回滚执行不影响真实环境的演练或逐步核对。

完成前再次运行 scripts/check_delivery_baseline.py。只有检查器没有失败、所有适用人工门禁均已验证、核心用户验收没有未完成项时，才能使用“交付门禁通过”。如果实现已经结束但仍有 Docker、干净环境、恢复、迁移、真实集成或回滚未验证，应明确写为“实现完成，交付验证未完成”。

没有实际执行的步骤必须列入“尚未验证”，不得写成已通过。

12. 交付报告

说明：

• 建立了哪些能力；
• 修改了哪些文件；
• 可重复启动的实际命令和结果；
• CI 配置及本地等价命令；
• 配置与 Secret 的来源和边界；
• 数据备份、恢复和迁移验证结果；
• 错误日志验证结果；
• Agent、Skill、MCP 或消息入口的发现、触发和真实端到端结果，或不适用依据；
• 发布与回滚说明位置；
• 尚未验证内容和剩余风险；
• 哪些实际发布、部署或真实数据操作没有执行。
• 检查器的实际命令、结果和经过人工确认的不适用项。