prisma-next-feedback

Prisma Next — 反馈（错误报告、功能请求、团队问答）

编辑数据契约。其余交给 Prisma 处理。

此技能是能力缺口路由模式的终点。当用户希望填补缺口时，其他所有 Prisma Next 技能中标为Prisma Next 目前还不支持的功能的条目都会引导至此；对于诸如 “这是个错误”、“提交问题”、“功能请求”、“我可以向团队咨询这个问题吗？”、“我该如何将 X 与 Prisma Next 集成？” 等提示，此技能也会直接触发。

此技能的任务是选择正确的渠道——GitHub issue 或 Discord——然后生成一份结构清晰且适合公开发布的问题正文（不含机密或专有架构），供框架团队处理；或者提供 Prisma Discord 的直接链接，以便用户进行实时问答。未经用户明确确认，绝不会向 GitHub 提交内容。

规范渠道：

• GitHub Issues（错误 + 具体的功能请求）：https://github.com/prisma/prisma-next/issues/new/choose
• Prisma Discord（问答、设计反馈、直接联系团队——包括扩展作者）：https://pris.ly/discord

何时使用

• 其他 prisma-next-* 技能中的能力缺口条目已触发，且用户表示 “是的，提交功能请求”。
• 用户说 “这是个错误”、“提交这个”、“报告这个问题”、“针对 PN 提交 issue”、“发送反馈”、“这应该是个功能”。
• 用户描述了意料之外的行为——错误的退出码、与实际情况不符的错误消息、与运行时行为不符的类型签名、规划器拒绝了看起来安全的迁移——并希望让框架团队了解此事。
• 用户询问 “我可以向 Prisma 团队咨询这个问题吗？”、“我能在哪里联系团队？”、“这是执行 X 的预期方式吗？”、“我该如何将 <my extension / my tool> 与 PN 集成？”，或提出任何其他开放式问答或设计反馈问题——包括扩展作者询问集成问题。

何时不使用

• 用户想在自己的代码中自行修复错误。修复方法属于其他技能（调试 / 契约 / 迁移 / 查询 / 运行时 / 构建）。先转到相应的技能；只有用户明确希望框架以不同方式运行时，才转到反馈流程。
• 用户想升级 Prisma Next（错误可能已经修复）→ 使用 prisma-next-upgrade 技能（需单独安装）；此技能会将其列为升级前检查。
• 用户的问题已由此技能组中的某个工作流技能涵盖（“如何添加列？” → prisma-next-contract；“正确的查询接口是什么？” → prisma-next-queries）。应转到工作流技能，而不是联系团队——加载该技能并回答问题，只有当 Agent 无法解答时，才升级到 Discord。

核心概念

• 三个渠道，一个决策。 GitHub Issues（Bug 和具体的功能请求）、Prisma Discord（问答、设计反馈、直接联系团队），或另一个集群内技能（当问题最后发现是工作流问题，而不是需要交接给团队的问题时）。该技能的第一步是选择渠道；之后的一切都由此决定。
• 公开内容。 GitHub issue 和 Discord 消息都对全世界公开可见，并会存档。正文 / 消息中不得包含 DATABASE_URL 字符串、内部公司架构片段、示例行中的客户数据，或任何用户不会公开分享的其他内容。Agent 在提交任一类型的内容之前都会先进行脱敏。
• Bug、功能请求还是问题。 Bug 指“文档所述的功能表现异常”。功能请求 指“我想要一个目前不存在的功能”。问题 指“我想和某人讨论 X，或者我不确定这到底是不是 Bug”。许多能力缺口会归为功能请求；许多扩展作者提出的问题则属于一般问题。
• 框架团队需要复现（仅限 issue）。 没有复现步骤的 Bug 报告更难处理。只要可行，Agent 都会提供一个最小复现示例，供团队在本地重新运行——最好是对 examples/prisma-next-demo 做一处小修改，因为团队已经检出了该示例。Discord 问答不要求提供完整复现；通常只需一小段代码和问题描述即可。

工作流

1. 选择渠道

用户想把某件事交给团队处理。应使用哪个渠道？

满足以下任一条件时，使用 GitHub Issue：

• 用户描述了一个具体 Bug（Bug 与功能请求的区分见下文的 分类）。
• 用户提出了具体的功能请求——例如一个命名明确的功能、一种特定的 API 形式或一个具体的 CLI 标志——并希望将其列入待办事项。
• 另一个 prisma-next-* 技能中的能力缺口条目将用户引导至此，提出功能请求。

满足以下任一条件时，使用 Prisma Discord（https://pris.ly/discord）：

• 用户提出开放式问题——“这是执行 X 的预期方式吗？”、“你会如何处理 Y？”、“我遇到了奇怪的行为，但不确定这是不是 Bug。”
• 用户希望在提交功能请求之前获得设计反馈——“我们正在考虑构建一个实现 X 的自定义中间件，这符合该框架的发展方向吗？”
• 用户是扩展作者，提出了需要与团队来回讨论的集成问题（对等依赖协调、破坏性变更的时间安排、新的扩展接口）。
• 用户明确表示想联系团队——“我可以就此询问团队吗？”、“有没有地方可以和 Prisma 交流？”、“扩展作者在哪里和团队讨论问题？”

满足以下任一条件时，依次使用两个渠道：

• 用户既报告了一个 Bug，又提出了相关的功能请求——分别提交两个 GitHub issue，不要将两者混在同一个 issue 中。
• 用户想先讨论设计，再提交功能请求——先在 Discord 上讨论，确定方案后再提交 issue。

2. 分类（仅限 issue 流程）

用户要提交 GitHub issue。它属于 Bug 还是功能请求？

满足以下任一条件时，属于 Bug：

• 有文档说明的 CLI 命令返回了错误的退出码。
• 错误信封中的 fix 字段具有误导性或不正确。
• 已发布的 TypeScript 签名与运行时行为不符。
• 规划器拒绝了本应有效的迁移（或接受了本不应有效的迁移）。
• 合约生成产出了无法在运行时加载的制品。
• 其他任何文档所述功能行为不正确的情况。

满足以下任一条件时，属于 功能请求：

• 用户想要一个目前不存在的功能（大多数 PN 目前还不能做什么 条目都属于此类）。
• 用户想要更好的错误消息、额外的 CLI 标志、新的中间件、额外的打包工具插件等。

如果两者兼有——既有 Bug，用户又想要相关功能——请分别提交两个 issue。把两者混在一起会增加框架团队分类处理的难度。

3. 收集最少的正文信息（仅限问题路径）

适用于任意一种类型：

• Prisma Next 版本：pnpm ls @prisma-next/postgres（或 @prisma-next/mongo）。如果项目使用了目标包，该版本就是规范版本。
• Node 版本：node -v。
• 包管理器：pnpm / npm / yarn / bun / deno。
• 操作系统：提供 darwin / linux / win32 以及版本字符串即可。

对于错误报告，还需提供：

• 出问题的确切命令（例如 prisma-next migration plan --name add-email）。
• 完整输出；如果涉及结构化错误封装，还需包含 -v。请隐藏 DATABASE_URL 和其他机密信息。
• 能够复现问题的最小 src/prisma/contract.prisma / src/prisma/contract.ts 片段。删除无关模型。如果用户的 contract 中原有模型和字段名称不会泄露敏感信息，请保留原名称——忠实的片段比重新命名后的版本更便于框架团队（以及日后的问题读者）分析。只有当原名称会泄露机密领域信息（产品名称、内部代号、客户标识符、受监管数据字段名称）时，才将其改为中性占位符（User、Post、Tag）。
• 复现步骤，使用编号列表。
• 预期行为——一句话。
• 实际行为——一句话，并附上相关输出行。
• 解决方法（如有）——一句话。

对于功能请求，还需提供：

• 期望的 API 或行为——一段文字。尽可能说明具体形式（CLI 标志、配置字段、中间件导出、插件 API）。
• 当前在哪些地方存在缺口——是哪项技能中的 PN 目前尚不支持什么 条目引出了该请求，或用户尝试完成的工作流是什么。
• 当前的解决方法（如有）——一句话（用户正在遵循的技能正文可能已对此有所说明）。

4. 渲染正文

此仓库提供 GitHub Issue Forms（.github/ISSUE_TEMPLATE/bug_report.yml 和 feature_request.yml）。用户打开 https://github.com/prisma/prisma-next/issues/new/choose 后，选择匹配的模板并填写表单字段；技能会以相同的结构生成正文，使其与表单字段一一对应（并且即使不使用表单，gh issue create --body-file 也能生成可解析的内容）。

错误报告正文格式（字段名称与 .github/ISSUE_TEMPLATE/bug_report.yml 一致）：

## Package and version

<e.g. @prisma-next/[email protected]>

## What happened?

<one-sentence summary plus the relevant output line, secrets redacted>

## What did you expect to happen?

<one sentence>

## Minimal reproduction

1. <step one>
2. <step two>
3. <step three>

```ts
// schema.psl excerpt + the query / command that fails
```

## Environment

- Node: <version>
- OS: <darwin/linux/win32> <version>
- Package manager: <pnpm/npm/yarn/bun/deno> <version>
- Database: <Postgres / Mongo> <version>

## Additional context

<optional — link to source skill's capability-gap entry, related
issue number, partner extension involved>

功能请求正文格式（字段名称与 .github/ISSUE_TEMPLATE/feature_request.yml 一致）：

## What problem are you trying to solve?

<paragraph — the use case or pain point this would address>

## Proposed solution

```ts
// imagined usage of the API / behaviour you'd want
```

## Alternatives considered

<sentence or two — what you tried with the current API and why it didn't work>

## Scope and impact

<which package(s) this would touch; target-specific implications>

5. 标题（仅限问题路径）

• 错误：bug(<area>): <one-line summary>——例如 bug(cli): migration plan exits 0 when there is no diff。
• 功能请求：feat(<area>): <one-line summary>——例如 feat(build): first-party Next.js plugin for contract emit。

区域对应技能集群：cli、contract、migration、query、runtime、build、error、docs。

6. 提请用户确认（仅限问题路径）

**绝不自动提交。**Agent 会向用户展示渲染后的标题和正文，并询问：“看起来可以提交了。要提交到 GitHub 吗？” 只有在用户明确批准后才会提交。

7. 提交（仅限 issue 路径）

首选方式。分两步：

1. 将渲染后的正文写入临时文件。 使用文件写入工具（与在磁盘上创建其他文件时使用的工具相同），将正文写入例如 wip/pn-issue-body.md 或 /tmp/pn-issue-body.md。正文内容仅为此工作流第 4 步生成的 Markdown，不要添加外层 shell 引号，也不要使用 heredoc。

2. 让 gh 引用该文件。 运行：

   gh issue create \
     --repo prisma/prisma-next \
     --title "<title>" \
     --body-file <path-from-step-1>
   

反面示例（不要这样做）： 通过 --body "$(cat <<EOF …)" 或 --body-file <(cat <<EOF …) 内联正文。当 Agent 原样复用模板并插入正文时，这些单行命令会可靠地将字面量 cat <<'EOF' / EOF 标记泄漏到 issue 正文中。务必先将正文写入实际文件，再传入文件路径。

如果未安装 gh：在浏览器中打开预填的新建 issue URL：

https://github.com/prisma/prisma-next/issues/new/choose

……并告知用户粘贴渲染后的正文。Agent 可以通过 pbcopy（macOS）、xclip（Linux）将正文复制到剪贴板，也可以直接在聊天中打印，供用户复制。

8. 转到 Discord（问答／设计反馈／直接联系团队路径）

如果第 1 步选择了 Discord 频道（步骤 2–7 不适用）：

1. 提供链接。 向用户提供官方邀请链接：https://pris.ly/discord。建议选择适合问题的频道：
   • 常规用法／问答 → 公共 #help 或 #prisma-next 频道（频道名称会变化；邀请页面会列出当前频道）。
   • 扩展作者／合作集成／重大变更协调相关问题 → 公共的扩展作者频道，或用户加入服务器后直接联系维护者。
2. 协助起草开场消息。 Prisma 的 Discord 支持搜索；措辞清晰的开场消息能更快获得更有用的答复。Agent 起草一条简短消息，包含：
   • 一句话概述用户想要完成的事情。
   • Prisma Next 版本（pnpm ls @prisma-next/postgres 或等效命令）。
   • 相关的简短代码片段（PSL 摘录、查询、配置文件）——按 GitHub issue 正文相同的方式删去敏感信息（不包含 DATABASE_URL，也不包含客户的 schema 名称）。
   • 用户希望得到解答的具体问题。
3. 不要自动发布。 Agent 将起草的消息提供给用户——“这是你可以粘贴到 Discord 的开场消息；发送前要调整一下吗？”——由用户决定是原样粘贴、编辑，还是换一种表述方式。
4. 如实说明预期。 Discord 是实时沟通渠道，回复视情况而定。无论如何，Bug 和具体的功能请求都应提交到 GitHub（使用 issue 路径）；Discord 用于展开讨论，直到得出“是的，这是个 Bug，提交 issue 吧”或“是的，这应该作为一项功能，提交 issue 吧”的结论。

9. 后续跟进

• Issue 路径：将 issue URL 记录在用户的项目笔记中（如果项目有 wip/ 目录，也可以记录在那里），以便后续升级或相关工作时参考。如果 Bug 是 Prisma Next 旧版本导致的症状，建议用户运行 prisma-next-upgrade（单独安装的升级技能）——许多 Bug 已在较新版本中修复。
• Discord 路径：如果 Discord 上的讨论逐渐明确为具体 Bug 或具体功能请求，请返回此技能的第 1 步并提交 issue（Discord 讨论串会作为 issue 正文中的 备注／问题出现位置 参考）。

常见陷阱

1. 未经确认就自动提交。 始终先展示正文。面向公众的内容归用户所有，而不是 Agent。
2. 将 DATABASE_URL 或其他机密粘贴到正文中。 务必彻底脱敏。替换为 postgresql://USER:PASS@HOST/DB 占位符。
3. 粘贴客户的机密域架构。 如果原始模型和字段名称会泄露机密信息（产品代号、客户标识符、受监管数据字段），请在将正文发布到公开问题中之前，先将其改为中性占位符。否则，保留原始名称——忠实摘录比重新改写名称更便于框架团队分析。过度改名本身也会影响可读性。
4. 将文档问题作为 Bug 提交。 文档问题应提交到其他技能中，或发布到 GitHub Discussion（如果仓库启用了该功能）。Bug 指的是功能表现异常。
5. 在一个问题中混合 Bug 和功能请求。 请分别提交。混合问题难以分类处理，也难以关闭。
6. 提交时未注明版本。 只说“我在使用 Prisma Next，它坏了”，却不提供版本，会让问题排查变得毫无头绪。版本是最容易收集的上下文信息；务必包含。

Prisma Next 目前尚不支持的功能

• 产品内反馈渠道。 没有 prisma-next feedback CLI 命令。GitHub Issues 页面是标准反馈渠道。如果你希望添加 CLI 端反馈命令，请通过此技能提交功能请求。

参考文件

• https://github.com/prisma/prisma-next/issues/new/choose — 标准提交渠道。
• https://cli.github.com/manual/gh_issue_create — gh 命令参考。

检查清单

• 已分类为 Bug 或功能请求（不要在一个问题中同时提交两者）。
• 已提供环境信息：PN 版本、Node、包管理器、操作系统。
• 复现步骤精简、安全公开且不含机密信息。
• 架构片段在安全的情况下使用原始名称；仅在原始名称会泄露机密领域细节时，才改用中性占位符。
• 标题符合 Conventional Commits 格式（bug(area): … / feat(area): …）。
• 提交前已向用户展示正文以供确认。
• 已通过 gh issue create（首选）或预填的新建问题 URL 提交。
• 已记录问题 URL，供日后参考。
• 如果 Bug 可能已在较新版本中修复，建议使用 prisma-next-upgrade。