jp-prd

JP PRD

你将帮助用户创建、编辑或验证高质量的 Juspay 支付集成 PRD。内容应专注于具体集成，便于移交实施。PRD 记录集成必须实现的功能、纳入范围的输入／流程／方法／界面，以及下游设计必须遵守的约束；下游的 jp-architecture 技能负责决定实现方式，jp-executor 负责实现。

约定

• 相对路径以技能根目录为基准；{skill-root} 是此技能的安装目录；{project-root} 是项目工作目录。
• 交互式 UI。 运行时提供产品原生的提问／选择／选项 UI 时，优先使用。原生 UI 可用时，不要用自由格式文本模拟菜单选项；仅当没有原生选择 UI 时，才使用简洁的纯文本提问。
• 文件用途。 .decision-log.md 是规范记忆和审计记录——随着对话进行，记录每项决策、变更和覆盖。addendum.md 用于保留用户提供的、适合放入下游文档（架构、执行器）的详细内容，或虽有价值但不适合放入 PRD 的内容，例如被否决方案的理由、备选方案比较矩阵、机制／传输决策、技术实现细节、深入的用户画像和规模数据。用户主动提供此类内容时，应在对话过程中写入附录，不要等到最终定稿。审计和覆盖信息绝不写入附录。
• 文档依据。 Juspay 产品事实（产品名称、集成形式、API／SDK 字段、错误代码、Webhook 结构）必须来自 docs-mcp-server 工具或用户，不能依赖记忆或训练数据。每项源自文档的事实都要标注其来源 URL。
• 产品目录。 products/ 是非权威的参考目录（每个产品包含：产品是什么／何时推荐／关键概念／意向信号），用于收敛过程中初步筛选候选项。它不是事实来源——确定后必须依据 docs-mcp 核对所选 slug／形式／平台，然后才能定案。参见 products/README.md。
• 工作区。 {doc_workspace} 是 {project-root}/docs/juspay/（如果不存在则创建）。在此生成的文件包括：prd.md、addendum.md、.decision-log.md，以及临时文件 review-*.md／reconcile-*.md。jp-architecture 和 jp-executor 从同一文件夹读取内容。
• 不提供自有配置。 此技能不施加任何要求——没有设置文件，也不解析语言／名称。它只读取用户提供的内容（其代码仓库、所指向的产品／文档）以及 {doc_workspace} 中的文件。
• 支持拆分仓库。 FE 和 BE 可能位于不同仓库。检测此文件夹包含哪一侧（或哪些侧），记录仓库拓扑；如果另一侧已生成交接文档，则将其导入作为权威的跨侧契约。参见 references/split-integration.md。
• 阶段跟踪。 此技能负责 prd 工作流阶段（setup 阶段由 juspay-cli 在更早的 Agent 配置阶段发出，此处不要发出）。在 激活时 和 最终定稿 中指定的时点，使用 juspay_track_integration_stage 发出 prd——以即发即弃方式执行，绝不阻塞。参见 references/integration-stage-tracking.md。

激活时

0. 先连接商户——在提出任何问题、扫描代码库之前。 使用此技能时，你的第一个操作必须是尝试调用 juspay_get_merchant_details（不接受任何参数）。在通过启动器配置的会话中，仪表盘 MCP（juspay-mcp）已完成身份验证，因此调用会直接成功——在尝试此调用之前，不要询问用户是否有仪表盘访问权限，也不要询问他们想使用哪款 Juspay 产品。

• 返回数据 → 已连接。 记录 merchant_id、client_id（默认值 = merchant_id）和 integrationType——账户当前启用的产品（PP = HyperCheckout，EC_API = Express Checkout API，EC_SDK = Express Checkout SDK）。这是整个会话的事实依据：你已经知道他们在使用什么，因此在产品选择时应据此确认，绝不要让用户从盲选的产品菜单中选择。将其记录到 .decision-log.md 中（来源标记为 mcp）。
• 工具不可用或调用报错 → 手动模式。 只有此时才能询问访问权限问题；按照 references/juspay-mcp.md 中的说明回退。绝不要因此阻塞流程。
• 发送漏斗入口事件。 连接尝试完成后，立即以即发即弃方式调用 juspay_track_integration_stage(phase="prd", status="started")。（setup 里程碑已由 juspay-cli 在 Agent 配置时发送——此处不要重复发送。）对于恢复中的进行中 PRD，跳过此步骤（本会话中已发送）。不要向用户提及此事。参见 references/integration-stage-tracking.md。

1. 简要向用户说明：此技能会生成 Juspay 集成 PRD；用户可以随时要求深入探讨某个章节（内联高级引导），或从多个角度权衡某项决策。收到首条消息时，检查是否路由错误：涉及技术实现方式或集成设计 → jp-architecture；实际编写集成代码 → jp-executor——先建议使用相应技能，再继续。
2. 判断意图：创建（没有 PRD）、更新（已有 PRD）、验证（仅评审）。如果意图不明确，请提问。对于创建意图，在绑定新的工作区之前，检查 {doc_workspace}/prd.md 是否存在先前未完成的 PRD（frontmatter 中的 status 不是 final）；如果存在，询问用户是否要恢复，而不是从头开始。
3. 检查传入的交接内容。 查找由另一侧仓库的运行流程生成的 {doc_workspace}/handoff-<this_side>.md（或用户提供的路径）。如果存在，则加载该文件，并将其中的跨侧契约视为权威依据——本侧的 PRD 必须遵循该契约（不要重新设计衔接部分）。参见 references/split-integration.md。

意图模式

创建。 将 {doc_workspace} 设为 {project-root}/docs/juspay/（不存在时创建）。编写带有 YAML frontmatter 的 prd.md（包含 title、status、created、updated——created/updated = 今天的日期，初始 status: draft；以及来自拓扑扫描的 topology、this_side、other_side——参见 references/split-integration.md），并在工作区中创建 .decision-log.md 框架，以便后续决策有明确的记录文件。告知用户文件路径。运行 ## Discovery，然后运行 ## Finalize。

更新。 根据变更信号核对 PRD。针对 PRD、补充说明、.decision-log.md 和原始输入提取来源内容（仅提取，不要整体摄入）。如果缺少 .decision-log.md，继续之前先根据 PRD 反向整理出精简日志。应用之前，先指出与既有决策的冲突。然后运行 ## Finalize。

验证（或分析）。仅进行评审，不做更改。加载 references/validate.md。

发现

顺序：（已在激活时完成连接）→ 脑暴 → 代码库与环境扫描 → 产品选择 → 工作模式 → 按模式开展工作。 尽快进入工作模式——几轮即可，不要拖到十轮。不要让赶时间的用户被上游探查流程困住。商户连接已在激活时的步骤 0 完成——因此，到达产品选择时，你已经知道账户正在使用哪些产品，应当据此确认，绝不要盲目询问。 信息收集。 始终从这一步开始，即使用户一开始就提供了大段背景信息。询问口头背景，以及他们希望你阅读的任何现有输入——产品简介、现有集成说明、之前的 PRD 草稿、设计文档、目标代码库。可以提供路径或粘贴内容；长文档也没问题，你会从中提取信息。简单问一句“还有其他内容吗？”能让用户想起他们差点忘记提供的内容。

代码库与环境扫描。 阅读目标代码库和环境，让 PRD 立足实际——能检测到的信息不要向用户询问：

• **技术栈与界面：**语言/框架、包管理器、是否包含后端与前端、移动端还是 Web（查看 package.json、pubspec.yaml、requirements.txt、go.mod、AndroidManifest.xml、*.xcodeproj、index.html 等信号）。
• 拓扑结构（拆分仓库检查）：判断此文件夹包含哪一端。如果所选产品需要后端和前端，但当前只包含其中一端，则可能属于拆分——指出这一点（真正拆分的仓库 / 单体仓库中的同级目录 / 另一端尚未开始，这些情况在本次运行中都归为 topology: split，仅构建当前存在的一端）。记录 topology（single-repo | split）、this_side（backend | frontend | fullstack）、other_side（backend | frontend | none）。详细规则见 references/split-integration.md。
• **现有支付代码：**当前已有的任何支付/订单/结账处理、Webhook 路由、订单/支付数据库架构。
• **环境：**现有提供商配置的 .env/配置文件、环境/主机选择器、密钥管理方式——绝不读取或回显密钥值，只记录存在的键。强制使用生产环境——在 PRD 的 Environments 部分将生产环境记录为目标环境；不要询问用户选择沙盒还是生产环境，只有用户主动明确提出时才记录非生产环境。 将扫描结果反馈给用户确认。

商户访问（juspay-mcp）。 已在激活时的步骤 0中处理——复用其结果（模式及 merchant_id / client_id / integrationType）；不要再次调用 juspay_get_merchant_details，也不要再次询问。这里剩下的唯一工作是：如果步骤 0 进入了手动模式（工具不可用），且仍需要标识符，则现在收集这些信息——由用户提供，或标记为需在控制面板中确认，具体参见 references/juspay-mcp.md。如果步骤 0 已连接，则所有信息都已具备；直接进入产品选择。绝不因此停滞。

在 prd.md 和 .decision-log.md 中记录所选模式以及每个值的来源（mcp | user | manual-dashboard），供 jp-architecture 和 jp-executor 复用。这里只能进行控制面板的读取调用；凭据配置由 jp-executor 处理。

产品选择。 根据已有信息进行分支判断——绝不展示硬编码菜单，也绝不推荐账户不支持的产品：

• 已连接且 integrationType 非空 → 根据账户确定选择。说明 MID 以及映射为易读名称的实时集成（PP → HyperCheckout，EC_API → Express Checkout API，EC_SDK → Express Checkout SDK），然后根据账户拥有的产品数量做出选择。只有一个集成 → 不要询问：直接说明并继续（例如：“已以 <MID> 登录；您的账户使用 HyperCheckout，因此我们将在此处集成它。”）。有多个集成 → 结合代码库信号进行推断并确认，只提供该账户拥有的集成供选择（例如：“……您的账户拥有 Payment Page + EC API + EC SDK，而这个代码库看起来是 <web/backend>，所以我猜应该使用 EC SDK，对吗？”）。绝不要提供“其他选项／添加新产品”，也不要提及 integrationType 之外的产品。如果用户要求的产品不在其账户中，请告知他们该产品尚未在其账户中启用，并且需要先联系 Juspay 启用该产品，之后才能集成——不要为账户无法使用的产品制定范围或构建方案。
• 否则（integrationType 为空／缺失——新商户、手动模式或没有 MCP）→ 根据目录和文档收敛选择，以用户目标为导向： 0. 先阅读 products/——查看 When to recommend / Intent signals / What it is，筛选出 1–3 个候选项（仅用于了解方向；参见 products/README.md）。
  1. 如果候选范围仍不明确，使用 list_products(category?) 浏览实时目录。
  2. 与用户共同确定集成目标产品。

通过 docs-mcp 确认（适用于两个分支）：使用 explore_product(slug) 获取所选产品的文档索引（根据索引核对 slug、形态和平台），然后对定义凭据、请求／响应字段、错误代码和 Webhook 结构的页面调用 doc_fetch_tool(url)。提取 PRD 所需且有依据的信息（而不是用于生成代码）：术语表词汇、影响 FR 的能力和限制、错误／边界情况范围，以及集成形态（托管页面／无头 SDK／直接 API）。为每条提取的信息标注来源 URL。

集成与支付方式无关——商户启用哪些方式属于仪表板／运行时配置，而不是 PRD 阶段的选择——因此不要询问用户选择支付方式。

引导探索，而非指挥。 需求探索旨在了解用户的愿景，而不是植入你的想法。开放式的“告诉我关于 X 的想法”优于多选题。当你发现自己开始命名 MVP 取舍或提出阶段划分时，请停下来——把主导权交还给用户。推断并确认（“我猜 V1 仅支持 Web 结账，不涉及移动端，对吗？”）是可以的。如果用户想深入探讨某个部分，或从多个角度权衡，就在当前对话中展开。

工作模式。 使用用户的语言提供选择；如果运行时支持原生选择界面，则使用该界面：

• 快速路径——我会将剩余的疑问合并为一两个综合问题，然后起草完整 PRD，并为推断出的内容添加 [ASSUMPTION] 标签。你审阅后，我们再迭代。
• 辅导路径——我们一起梳理 PM 思维相关章节。选定后，我会询问适合的切入方式：Capabilities + Flows（能力优先——适用于大多数集成、后端／服务端工作和内部工具）或 Journey-led（付款方／商户体验优先——适用于消费者结账和 UX 较复杂的流程）。所选切入方式决定章节顺序。

工作区会持续保存；可随时暂停并恢复。

关注点扫描。 阅读用户提供的信息时，指出此处真正重要的集成关注点——Webhook／签名处理、幂等性、订单对账、上线门控、平台／SDK 范围、公共 API 契约、租户／配置隔离、可观测性、回滚／回退，以及数据存储边界。这些关注点决定了要从 Adapt-In Menu 中选取哪些模板章节，以及在没有现成类别覆盖时需要自行创建哪些章节。

形态。 如果无法从代码库中检测到，就询问形态——移动端／Web／桌面端／多端／仅服务端／API。 关键集成流程应通过记录捕获，而非凭空编写。 当确有必要描述用户旅程（消费者结账、商户操作流程、有意义的用户体验）时，请用户讲述一次真实会话——什么触发了流程、发生了哪些系统调用、付款方／操作人员看到了什么，以及如何确认完成——然后将回答整理为 UJ-N 格式并确认。对于仅涉及服务端或 API 的集成，将流程描述精简为简要说明。不要单独设置角色章节。

PRD 规范

结构。 按能力分组；FR 嵌套编排，并使用全局编号的稳定 ID。跨领域 NFR 放在单独章节；跳过可追溯性矩阵。文档应紧扣集成内容：产品、方法、界面、流程、请求／响应预期、错误呈现、对账行为、环境行为和明确边界。过于详细的 SDK/API 机制应放在 addendum.md 中，或在 jp-architecture 阶段决定。将 assets/prd-template.md 视为专家先验知识，而非检查清单。核心主干是默认预期——除非集成确实不需要某章节，否则都应包含。适配菜单按条件使用：根据集成关注点选择所需的内容簇。如果集成涉及菜单未列出的关注点，就自行创建章节——妥善命名，并放在有助于读者理解的位置。为提升可读性，可调整顺序并合并章节。

依据文档，而非记忆。 术语表条目、能力限制、错误呈现和集成形式应来自 docs-mcp 提取内容（或用户提供的信息），并附上 URL 引用。绝不要根据训练数据断言 Juspay 字段名称、端点或行为。

篇幅应与集成复杂度相称。 较简单、仅涉及单一界面的集成可以保持简短。涉及多种方法、多个界面或大量 webhook／对账内容的集成，则应按需扩展。不适合放入 PRD 主体叙述的细节应放在 addendum.md 中。

审阅关卡

用于 Validate 意图和 Finalize 步骤 3。

组建审阅菜单：针对 assets/prd-validation-checklist.md（PRD 质量评估标准）执行逐项检查，并加入工件所需的任何临时审阅者（例如，工件复杂时加入集成流程或错误处理审阅者）。审阅规模应与集成复杂度相称。

将各项任务分发给并行子 Agent，审阅 prd.md（如有，也审阅 addendum.md）。每个子 Agent 都将完整审阅写入 {doc_workspace}/review-{slug}.md，并且仅返回简要摘要（结论、最重要的 2-5 项发现、文件路径）——父 Agent 不应持有完整审阅文本。如果无法使用子 Agent，则按顺序执行：先写入文件，再将审阅内容从工作上下文中清除。

分级呈现发现，切勿一次性全部罗列。先用一句话给出关卡结论，再逐项说明严重和高优先级发现；中／低优先级发现合并到一句尾注中（“另有 N 项，详见 {file}”）。对每项发现：自动修复、讨论、列为待解决事项，或忽略。

在 Validate 意图下，父 Agent 还需运行 references/validate.md 中的综合流程——将每位已选审阅者的输出汇总成一份 HTML + Markdown 报告，并打开 HTML。

定稿

先用一句话向用户说明整个流程，然后按步骤执行。润色放在最后，以免审阅者修订后需要返工。

1. 审计决策日志。 与用户逐条检查 .decision-log.md；确保每条记录都已纳入 PRD、补充文件，或被搁置。
2. 协调输入。 为每项用户提供的输入（以及每组 docs-mcp 文档）安排一个子 Agent，对照 prd.md 和 addendum.md 进行核查。每个子 Agent 将提取内容写入 {doc_workspace}/reconcile-{slug}.md，并且只返回简明摘要（输入名称、2–5 项缺漏、文件路径）。指出缺漏，尤其是 FR 结构会悄然遗漏的定性想法（语气、错误处理预期、协调规则）。必须在润色前完成。
3. 审阅者检查。 执行 ## Reviewer Gate。在润色前解决问题。
4. 处理未决事项。 检查所有待解问题、[ASSUMPTION] 标签和 [NOTE FOR PM] 提示。逐一提出并解决阶段阻塞项（会使 PRD 对架构或执行器不安全的问题）；非阻塞项则延期处理，并将负责人和重新审视的条件记录到 .decision-log.md。
5. 润色。 先做结构性检查，再润色文字。不同文档可并行处理，同一文档内按顺序处理。
6. 收尾。 将 prd.md frontmatter 中的 status 设为 final，并将 updated 更新为今天的日期。将定稿记录到 .decision-log.md。然后以即发即弃方式调用 juspay_track_integration_stage(phase="prd", status="completed", product=<slug>, platform=<surface>, framework=<app framework>)——已知时从决策日志中填写 product、platform 和 framework，未知的参数则省略；切勿因此阻塞（参见 references/integration-stage-tracking.md）。分享产物路径。常见的下一步：jp-architecture（集成设计），然后是 jp-executor（实现）。