# ShipGate：项目章程

## 决策

ShipGate 是面向个人开发者的合并前交付助手，服务于经常使用编程 Agent 并发布代码的开发者。产品原定先进行客户验证，再投入实现；当前本地 CLI 已按明确授权进入 M1 实现阶段，但后续试点、GitHub 集成与商业化仍须通过本章的验证门槛。

## 问题

编程 Agent 能在很短时间内产生大规模改动，但开发者仍需要自行确认：改动是否涉及数据库迁移、密钥、鉴权、公开 API、依赖或未验证路径。现有工具能报告 lint 和测试结果，却不能给出一份可审阅的明确答案：发生了什么变化、哪些内容已验证、还需要开发者亲自决定什么。

初始问题不是缺少又一个代码扫描器，而是在创建或合并 PR 的决策时刻缺少全局态势感知。

## 目标用户

第一批用户是独立开发者或 2-5 人产品团队，他们：

- 每周至少使用一次 Codex、Claude Code、DSH、Cursor 或类似编程 Agent；
- 通过 GitHub 发布 Web 产品或客户项目；
- 自己承担错误合并的后果；
- 已具备至少基础测试或构建命令。

验证用户应当在过去一个月合并过至少三个 Agent 辅助的 PR，并能讨论一次近期需要额外检查或曾引发回归的改动。

v0.1 不面向强监管企业；其采购、身份与审批流程属于另一类产品问题。

## 待完成任务

核心任务是："在发布一项 Agent 辅助改动前，帮助我重建改了什么、我拥有哪些证据，以及还有哪些决定必须由我做出。"

支持性任务：

- 生成两分钟内可审阅的紧凑记录；
- 不依赖 Agent 声称某项检查已通过；
- 不上传源码也能显示高风险文件类别；
- 将同一份记录复用在 PR 或后续发布问题排查中。

## 产品假设

若 ShipGate 能在两分钟内将编程 Agent 的 diff 变成简洁、可信的合并前收据，活跃的独立开发者会在重要 PR 前重复使用它，并为特定技术栈检查和 GitHub 工作流集成付费。

| 假设 | 验证证据 |
| --- | --- |
| 问题出现得足够频繁 | 12 名访谈对象中至少 8 人能在未被引导的情况下描述近期的审阅缺口。 |
| 确定性收据能改善决策 | 5 次真实 PR 回放中至少 3 次发现遗漏的关注点或验证步骤。 |
| 工作流足以重复使用 | 至少 3 名原型用户一周内生成超过两次收据，中位审阅时长低于两分钟。 |
| 存在付费边界 | 至少 2 名用户接受某项具名 Pro 能力的价格，而非只表示“想法有用”。 |

## MVP

ShipGate 接收 Git 比较范围和明确提供的验证结果，输出：

1. 针对变更路径与 Git 元数据的确定性风险摘要；
2. 已通过、失败或未运行的验证清单；
3. 需要人工决策的短列表；
4. 可用于 PR 描述或后续发布关联的可携带 Release Receipt。

首批风险包括数据库迁移、配置或环境改动、认证/授权、公开 API、依赖改动与文件删除。v0.1 只依赖路径和 Git 状态，不进行源码语义解释。

第一个界面是本地 CLI：读取仓库及调用方提供的检查证据，在本地写入 JSON 和 Markdown 工件，不发起网络请求。

## 非目标

- 不声称代码正确；
- v0.1 不自动执行任意 shell 命令；
- 默认不阻止合并；
- 不进行源码语义审查、漏洞扫描或密钥扫描；
- 不管理团队审批、SSO、审计留存或生产部署；
- 不要求托管账户。

## 产品原则

- **证据先于断言：** 记录观察到的 Git 事实和调用方提供的退出状态；将意图和摘要标记为未经验证的文本。
- **确定性核心：** 相同的规范化输入和规则版本必须得到相同 finding 与风险级别。
- **每项结果可解释：** finding 必须列出规则、命中证据、严重度和需要人工回答的问题。
- **默认本地：** 除非用户显式配置集成，源码路径和收据都留在本地。
- **默认建议性：** finding 用于提示，阻断行为必须由项目策略或 CI 标志显式开启。
- **无需 Agent 也可用：** Agent adapter 只是可选的输入收集器，不属于 evaluator。

## 定价假设

| 层级 | 提供内容 | 初始价格测试 |
| --- | --- | --- |
| Free | 本地收据生成与通用规则。 | 免费 |
| Pro | GitHub PR 检查、自定义规则、技术栈规则包、可共享交付模板。 | 一次性 RMB 69 或 RMB 19/月 |

首轮价格实验优先测试一次性购买。只有当 ShipGate 产生持续的云端或 GitHub 价值后，订阅才成立。访谈中必须将价格与具体能力和付费时点绑定，例如“愿意为 GitHub 检查加 Next.js 规则包支付 RMB 69”。

## 验证计划

### V0：访谈与样本收集

访谈 12 名目标开发者。在介绍 ShipGate 前，请对方逐步复盘一个近期已合并的 Agent 辅助 PR；收集五个代表性 PR，或其脱敏后的变更清单与实际测试记录。

每次访谈记录：Agent 改动的频次/规模、当前合并前流程、最近遗漏风险或验证、重建改动所花时间、信任与不信任的证据、路径/命令/意图的敏感性，以及相邻开发工具支出。不得把“听起来有用”这类引导后的认同计入验证证据。

### V1：人工收据回放

对五个真实改动，按 v0.1 规则人工生成 Markdown 收据，计时并让用户说出其决策过程。记录哪些 finding 有用、冗余或误报；哪些风险被遗漏；验证区是否改变信心；是否愿意附到 PR；以及拒绝暴露给 GitHub 或分析系统的字段。

只有当参与者无需访谈者解释，便能基于收据说出下一步行动或明确接受风险时，一次回放才算成功。

### V2：礼宾式原型

向五位开发者提供一个免安装或低安装成本的原型：接收变更文件清单和检查结果，在真实工作中使用一周。仅收集本地生成记录或简短使用日记，不要求上传源码。

跟踪生成次数、重复使用、审阅时长、按规则归类的忽略 finding、附加到 PR 的收据以及遗漏验证项；一周后进行 20 分钟复盘。

### 验证门槛

后续开发或扩展仅在同时满足下列条件时推进：

- 5 位开发者同意在真实仓库安装本地 CLI；
- 至少 3 位一周内使用收据超过两次；
- 至少 2 位同意为具体 Pro 能力或付费抢先体验付费；
- 收据审阅中位时长少于两分钟；
- 至少 60% 的回放收据包含用户认定可行动的 finding 或遗漏检查；
- 任一默认规则在至少十次命中中，误报忽略率均不超过 30%。

若重复使用失败，先改进调用方式和输出，不增加规则；若可行动性失败，收窄目标技术栈或规则；若重复使用成功但无人付费，保持 CLI 免费并测试 GitHub 集成或规则包。若少于五名受访者独立描述该问题，或收据持续只是重复现有 PR 模板而不改变决策，则停止项目。

## 成功指标

上线后的北极星指标是每周活跃仓库数，其中“活跃”要求至少有一份收据被审阅：finding 被解决或接受，或收据附到了 PR。

- 收据生成成功率及中位生成时长；
- 收据附加到 PR 的比例；
- 含可行动风险 finding 的收据比例；
- 按项目与技术栈划分的遗漏验证率；
- 按规则及规则版本划分的误报忽略率；
- 四周留存仓库数；
- GitHub 集成或规则包上线后的付费转化。

不以原始收据数量为优化目标；无人审阅的自动生成没有产品价值。

## 风险与应对

| 风险 | 早期信号 | 应对 |
| --- | --- | --- |
| 通用路径规则噪声过大 | 忽略率高，用户跳过风险区。 | 收窄默认规则、展示命中证据、将技术栈规则移入可选规则包。 |
| 提供检查证据增加摩擦 | 用户不提供检查或放弃生成。 | 保持小型且有文档的 JSON 输入，待本地契约稳定后再接 CI。 |
| 用户将收据误当审批 | 用户要求“可安全合并”的保证。 | 使用基于证据的措辞，将未决人工决定置顶。 |
| 免费 CLI 没有付费路径 | 使用强但无付费意愿。 | 先验证 GitHub 工作流和具名技术栈包，不急于建设托管基础设施。 |
| 收据泄露仓库信息 | 用户拒绝附到 PR 或分析系统。 | 默认本地存储，支持路径脱敏，定义最小同步投影。 |

## 后续开发前的决策

- 根据验证证据选择首个规则包：Next.js、Supabase 或 Stripe 集成；
- 由目标用户的安装摩擦确认 Node.js 20+ 与 TypeScript 分发方式；
- 冻结与 Release Sentinel 共享的 Release Receipt v1 字段；
- 依据原型反馈决定默认 CI 退出策略；本地模式始终保持建议性。