v0.4 计划

状态： @yangyus8/emotile@0.3.0 发布后的 release candidate。 主题： Release automation and integration readiness。

目标

让 Emotile 的发布更安全，让下游集成更容易。

v0.4 应把 v0.3 已形成的集成表面推进到可发布、可复查、可接入的状态： 手动发布自动化、可重复的发布前检查、清晰的发布分工文档，以及 Agent 集成指南。 这些工作不应把 Emotile 绑定到某个具体平台运行时。

范围

1. 手动 npm 和 GitHub release workflow

   • 新增用于正式发布的手动 GitHub Actions workflow。
   • 要求输入 version，例如 0.4.0。
   • 不从 push 到 main 自动发布。
   • 不自动提升 package version。
   • 检查 package.json version 和 CHANGELOG.md 与输入版本一致。
   • 发布前运行完整质量门禁。
   • 优先支持 npm Trusted Publishing / OIDC。
   • 在 Trusted Publishing 尚未配置时，允许使用有文档说明的 NPM_TOKEN + provenance fallback。
   • 只在检查通过后创建 vX.Y.Z git tag 和 GitHub Release。
   • release notes 优先从 CHANGELOG.md 提取。
   • 使用最小 GitHub Actions 权限，并显式区分 contents 和 id-token scope。

2. Release preflight checks

   • 新增不执行发布的 release preflight workflow 或脚本。
   • 支持在 pull request 和手动触发下运行。
   • 检查 version metadata、changelog entry、typecheck、tests、build、docs build、package dry run、CLI smoke test 和 library import smoke test。
   • 不发布 npm，不创建 GitHub Release，不创建 tag。

3. 发布流程文档

   • 文档化 Architect 和 Builder 的职责边界。
   • 包含 release checklist、失败处理、重试规则、Trusted Publishing 配置和 token fallback。
   • 明确 Builder 可以准备发布自动化，但只有 Architect 可以触发正式 release。

4. Agent 集成准备指南

   • 展示 Agent 如何使用导出的 JSON Schema 生成 EmotileExpression。
   • 文档化推荐链路：validate、repair、normalize、render、theme、SVG。
   • 包含最小 TypeScript 示例。
   • 保持运行时中立，不做 OpenClaw / Hermes 深度耦合。

建议构建顺序

1. Release preflight checks。
2. 手动 release workflow。
3. 发布流程文档。
4. Agent 集成准备指南。

Preflight 应先完成，这样正式 release workflow 可以复用或对齐同一组检查。 发布文档应在 workflow 完成后更新，以便描述真实命令和失败模式。

Issue 策略

• 不为 v0.4 创建长期 planning issue。
• open issue 只保留 Builder-ready 任务。
• 每个实现 issue 必须包含 goal、non-goals、acceptance criteria、suggested files 和 testing expectations。
• 不让 Builder 直接做 runtime 架构决策。
• 如果要引入 semantic-release、Changesets 或类似 release manager，必须先写出与手动 workflow 的对比理由。

非目标

• 桌宠运行时。
• Tauri runtime。
• Godot runtime。
• Canvas runtime。
• PNG / GIF export。
• 预设表情目录。
• OpenClaw / Hermes 深度耦合。
• 从 push 到 main 自动发布。
• 自动 bump version。
• 未先写对比理由就引入 semantic-release 或 Changesets。
• Expression format 变更。
• Renderer 架构变更。

验收主题

• Release 是手动、可审计、可重复的。
• Release checks 可以在任何 publish、tag 或 GitHub Release 副作用发生前失败。
• npm 发布优先使用短期 OIDC 凭据，而不是长期 token。
• Builder 能实现清晰限定的自动化和文档任务，而不决定 Emotile 的 runtime 方向。
• 集成指南使用现有 v0.3 public surface，并保持平台无关。

参考

• npm Trusted Publishing：https://docs.npmjs.com/trusted-publishers/
• npm provenance：https://docs.npmjs.com/generating-provenance-statements/
• GitHub Actions workflow syntax：https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
• GitHub CLI release creation：https://cli.github.com/manual/gh_release_create