| name | ship |
| version | 1.0.0 |
| description | GAS 扩展交付流水线。审查代码质量 → TypeCheck → 构建 → E2E 验证 → 提交 → 推送 → 打包 VSIX。触发方式：用户提及 "/ship"、"交付"、"提交推送"、"打包发布"、"ship it"、"发版" 等关键词时激活。 |
GAS Extension Ship
一站式交付：审查 → 构建 → 验证 → 提交 → 推送 → (可选)打包 VSIX。
命令格式
/ship [options]
| 参数 | 说明 | 默认值 |
|---|
--skip-e2e | 跳过 Playwright E2E 验证 | 不设置 |
--skip-push | 仅 commit，不 push | 不设置 |
--vsix | 构建后打包 VSIX 安装包 | 不设置 |
--message "<msg>" | 自定义 commit message | 自动生成 |
执行流程
Phase 1: Review（审查清单）
在提交前执行全部质量检查。任何 ❌ 项都阻断流程。
1.1 代码质量
cd packages/vscode-adapter
npx tsc --noEmit
pnpm build
cd packages/core
npx tsc --noEmit
pnpm test
1.2 模式扫描
对 git diff --name-only 变更的 .ts 文件（排除 .test.ts、.d.ts），检查：
| 模式 | 严重性 | 说明 |
|---|
console.log | ❌ | 使用 VS Code OutputChannel 替代 |
any 类型 | ❌ | 必须有明确类型（eslint-disable 注释除外） |
非空断言 ! | ⚠️ | 尽量用 optional chaining 或 guard |
TODO / FIXME | ⚠️ | 确认是否应修复再提交 |
| 硬编码密钥/token | ❌ | 使用 SecretStorage |
1.3 本地敏感信息过滤
在进入 commit 前，扫描 staged 文件内容，阻断以下信息进入仓库：
| 模式 | 严重性 | 说明 |
|---|
| 用户主目录绝对路径 | ❌ | 如 C:\\Users\\<name>、/Users/<name>、/home/<name> |
| 工作区/临时目录绝对路径 | ❌ | 如项目本机绝对路径、AppData、Temp、.codex、.ssh |
| 本地凭据/认证产物 | ❌ | 如 auth.json、cookie、session、refresh token、access token |
| 私有 API Key / Secret | ❌ | 如 sk-、ghp_、Bearer 、OPENAI_API_KEY= |
| 私有服务地址/账号 | ⚠️ | 仅本机可访问的 host、邮箱、用户名，需确认是否应脱敏 |
命中任一 ❌ → 停止 ship，先脱敏、改成占位符、或改为通过 SecretStorage / 环境变量读取。
1.4 ESM 格式验证
检查 esbuild.mjs 中 format 是否为 'esm'。如果是 'cjs' → ❌ 阻断（扩展无法加载）。
1.5 E2E 验证（除非 --skip-e2e）
cd packages/vscode-adapter
pnpm test:agent
启动 VS Code Insiders，执行 smoke test，截图验证。
如果 smoke test 失败 → ❌ 阻断。
1.6 输出审查报告
## 审查报告
| 检查项 | 结果 |
|--------|------|
| tsc --noEmit (vscode-adapter) | ✅ / ❌ |
| tsc --noEmit (core) | ✅ / ❌ |
| pnpm build | ✅ / ❌ |
| pnpm test (core) | ✅ / ❌ |
| console.log | ✅ 无 / ❌ N处 |
| any 类型 | ✅ 无 / ❌ N处 |
| 本地敏感信息 | ✅ 无 / ❌ N处 |
| ESM format | ✅ / ❌ |
| E2E smoke test | ✅ / ⚠️ 跳过 / ❌ 失败 |
| .omm/ 架构文档 | ✅ 已更新 / ⚠️ 无需更新 |
有 ❌ → 停止流程，输出修复建议。
Phase 1.5: Architecture Docs（架构文档更新）
使用 oh-my-mermaid 保持 .omm/ 架构文档与代码同步。
判断是否需要更新
检查 git diff --name-only 变更文件，如果包含以下路径则必须更新：
| 变更路径 | 影响的 omm 视角 |
|---|
packages/*/src/**/*.ts（非 .test.ts） | overall-architecture |
packages/*/package.json | overall-architecture（依赖关系可能变化） |
新增/删除 packages/*/src/ 目录 | overall-architecture + extension-points |
packages/*/src/events/** | data-flow |
packages/*/src/session/** | data-flow |
packages/*/src/capabilities/** | extension-points |
packages/*/src/runtime/** | extension-points |
如果变更文件仅涉及测试、文档、配置文件（.mdc、.md、.json 非 package.json），跳过此步骤。
更新方式
对受影响的视角，读取变更文件的新内容，更新对应节点的 description.md 和 diagram.mmd。
规则：
- 仅更新受变更影响的节点，不要重写未变化的节点
- 新增包/模块时，在对应视角创建新的子元素（创建目录 + description.md）
- 删除包/模块时，删除对应的
.omm/ 子目录
- element ID 使用英文 kebab-case，描述内容使用中文
- 图表标签格式：
节点名称\n文件路径
- 每条边必须有标签：
A -->|"关系说明"| B
Phase 2: Commit（提交）
2.1 查看变更
git status
git diff --stat
git log --oneline -5
2.2 生成 Commit Message
分析 git diff --staged（或 git diff），按 Conventional Commits 生成：
<type>[scope]: <description>
| Type | 用途 |
|---|
feat | 新功能 |
fix | 修复 bug |
docs | 仅文档 |
refactor | 重构（无功能变化） |
test | 测试相关 |
build | 构建/依赖 |
chore | 杂项 |
2.3 暂存并提交
git add -A
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>
<optional body>
EOF
)"
安全检查：提交前扫描 staged 文件，绝不提交：
.env、*.key、credentials.json- 包含
sk-、token、secret 字面值的文件
- 包含本机绝对路径、用户目录、
.codex / .ssh / auth.json / cookie / session 凭据的文件
Phase 3: Push（推送）
除非 --skip-push：
git push origin <当前分支>
如果 push 失败（权限/冲突），输出诊断但不重试。
Phase 4: Package（可选，--vsix 时执行）
cd packages/vscode-adapter
pnpm package:vsix
输出 VSIX 文件路径和大小。
Phase 5: 最终摘要
## Ship 完成
- 提交: <hash> <message>
- 分支: <branch> → origin/<branch>
- 变更: N files changed, +insertions, -deletions
- E2E: ✅ 通过 / ⚠️ 跳过
- VSIX: <path> (<size>) / 未打包
Finish Work（预提交检查清单）
如果只想执行审查不提交，使用 /finish-work：
清单
PR 创建（/create-pr）
提交推送后需要创建 PR 时：
git push -u origin HEAD
gh pr create --title "<type>[scope]: <description>" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points>
## Test plan
- [ ] `tsc --noEmit` passes
- [ ] `pnpm build` succeeds
- [ ] `pnpm test` passes
- [ ] `pnpm test:agent` screenshots verified
## Screenshots
<attach relevant dist/screenshots/*.png>
EOF
)"
安全规则
- 绝不
git push --force（除非用户明确要求且不在 main/master）
- 绝不 提交含密钥的文件
- 绝不 修改 git config
- 绝不 使用
--no-verify 跳过 hooks
- 如 pre-commit hook 失败，修复后创建 新提交，不 amend
- 合并冲突时 绝不 自动解决
与其他命令的关系
开发流程:
编码 → 测试 → /ship → (可选 /create-pr)
│
┌────────────┼───────────┬──────────────┬─────────────┬──────────┐
↓ ↓ ↓ ↓ ↓ ↓
Phase 1 Phase 1.5 Phase 2 Phase 3 Phase 4 Phase 5
Review Arch Docs Commit Push Package Summary
├ tsc omm write Conventional origin/br VSIX
├ build 增量更新 Commits
├ test .omm/
├ patterns
└ E2E smoke
| 命令 | 职责 |
|---|
/finish-work | 仅审查清单（被 /ship Phase 1 调用） |
/ship | 审查 + 提交 + 推送 + (可选)打包（本命令） |
/create-pr | 推送后创建 GitHub PR |
/qa run | 单次场景 E2E 测试 |
/qa-loop | 测试→修复→回归循环 |
