platform-request

平台需求

你为这款应用的所有者工作（对方是领域专家，而非开发者）。 他们提出的一些需求不是由你来实现的：平台（Boring 库、hub、VM、模型和连接器）必须先做出改变。此时，你的工作不是想方设法绕过限制，而是向平台团队提交一份足够完整的问题报告，让他们无需再次联系对方就能完成构建。

这项技能的产出是本仓库中的一个 GitHub 问题，标签为 kind:platform（问题模板 .github/ISSUE_TEMPLATE/platform.yml）。平台维护者及其编码 Agent 会阅读它。所有必要信息都必须包含在其中。

适用情况

• docs/CAPABILITIES.md 将该需求列在“目前无法实现”下。
• 改动需要涉及 vendor/、deploy/、.github/、server/src/auth.ts，新增模型提供商、连接到其他系统、调度器或电子邮件。
• 某项功能出现故障，经过两次认真尝试（每次都测试一个假设）仍找不到原因，或者平台的行为与文档不符。
• 改动需要超过一天，或涉及安全或个人数据。

对于你能在这里实现的产品改动，不要提交平台需求：直接实现（使用技能 boring-app-template、 build-app）。如果不确定，请查看 docs/CAPABILITIES.md 和 gh issue list --label kind:platform --state all（该需求可能已经有人提出，或已经解决）。

1. 访谈对方（最重要的一步）

维护者没有参与之前的对话。趁对方还在，现在补全背景信息。用他们的语言平实地交谈，一次问一个问题；绝不要告知还剩几个问题。只要回答不再会改变问题报告，就停止提问。

1. 用他们自己的话说明需求：他们想做什么，为什么是现在。
2. 三个真实情况（不是假设）：对每个情况，了解是什么触发了需求、当时他们手头有什么、做了什么、作出了什么决定、哪里出错或花了时间、结果如何。如果有任何情况是想象的，要明确说明并请他们提供一个真实情况。 删除所有可识别真实人物的信息（患者、客户、同事）：更改姓名、出生日期、标识符；保留案例的整体情况。
3. 目前的做法及其代价：他们如何在没有该功能的情况下处理（耗时、错误、使用其他工具），以及这种情况发生得有多频繁。
4. 决定性时刻：当他们迟到或承受压力时，会在什么时候放弃当前做法，转而采取什么行动？只问一次；这个问题能说明哪些环节必须自动完成，哪些可以继续手动处理。
5. 完成后的样子：功能正常时，他们会看到什么、做什么。将其整理为他们认可的“应用应当……”条目。
6. 限制：什么事绝不能发生（数据外泄、未经他们同意就修改文档、产生费用），以及需求有多紧急（阻碍工作、每周都会遇到的痛点、锦上添花）。

2. 收集证据

• 你尝试过什么：命令、错误文本、verify 证据 （network-summary --since-mark、console --errors、截图）和运行记录（ verify api /api/runs）。只能使用虚构数据。
• 版本：git rev-parse --short HEAD、vendor/boring/SOURCE.json 中的库提交，以及当前部署的版本（在 hub 上运行 list_app_tools，参见 docs/CAPABILITIES.md；或查看 /healthz 中的版本）。
• docs/CAPABILITIES.md 中阻止该需求的具体条目，或与平台行为相矛盾的文档。
• 当前最接近的可行方案（“最近似方案”列），以及你是否已实现该方案。

3. 当需求需要可视化时，制作原型

一张图就能说明三个段落也说不清的事。选择最简单的可行方案：

• 文本线框图（问题报告中必须包含）：在代码块中绘制方框并标注。

• HTML 原型：制作一个包含虚构数据的独立文件，再生成它的 PNG：

  node scripts/mock-shot.mjs docs/requests/<slug>/mock.html docs/requests/<slug>/mock.png
  

  在 request/<slug> 分支上提交两者（绝不要提交到 main），推送分支，并在问题报告中链接这些文件（https://github.com/<owner>/<repo>/blob/request/<slug>/docs/requests/<slug>/mock.png）。

• 如果改动涉及现有屏幕，则在原型旁附上当前页面的截图（verify screenshot）。

4. 起草、展示、提交

1. 根据 issue-template.md（与此文件位于同一目录）编写问题正文，并保存到 .verify/request-<slug>.md。填写所有部分；不要省略任何部分，无法确定时填写 “unknown”，并说明谁可以确认。

2. 用对方的语言向其展示标题、摘要和验收条目，并询问这些内容是否符合他们的需求。反复修改，直到对方确认。提交问题会让其他人看到：未获对方确认，绝不要提交。

3. 提交：

   gh issue create --label kind:platform --title "<the need, in a few words>" --body-file .verify/request-<slug>.md
   

4. 告知对方链接、后续安排（平台团队会对其进行分流），以及他们目前可以采取的措施（最接近的临时解决方案）。

5. 不要留下未完成的改动：撤销你未完成的临时解决方案，或完成它并在问题中说明。

禁止事项

• 不要在问题、模型图或证据中加入真实个人数据。应用之外的人和 Agent 也会阅读问题。
• 不要为了给自己“解围”而修改 vendor/、deploy/、.github/ 或身份验证。
• 不要在未进行访谈的情况下提交问题：“对方想要 X”，却没有具体情境、验收标准和证据，最终只会让对方回来回答问题。