@xgent-ai/skills 0.3.0 → 0.4.0

package/skills/portal-micro-app/SKILL.md

@@ -1,21 +1,14 @@
 ---
 name: portal-micro-app
-description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型 App，iframe + @xgent/portal-sdk，即 apps/*-app）。凡任务涉及新建一个 App 前端、给某 App 加页面/导航项/Dashboard Widget、SDK 握手/getToken/callService、consent 授权屏、或 iframe 内的 UI 异常（弹窗无效/菜单点不动/主题/路由同步/全屏/剪贴板）时，务必先用本 skill——即使用户没提"微应用"三个字。Use when building or changing any micro-app frontend embedded in the portal (apps/*-app), the portal SDK handshake, navItems, dashboard widgets, or iframe-specific UI issues.'
+description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型 App，iframe + @xgent/portal-sdk，独立前端项目）。凡任务涉及新建一个 App 前端、给某 App 加页面/导航项/Dashboard Widget、SDK 握手/getToken/callService、consent 授权屏、或 iframe 内的 UI 异常（弹窗无效/菜单点不动/主题/路由同步/全屏/剪贴板）时，务必先用本 skill——即使用户没提"微应用"三个字。Use when building or changing any micro-app frontend embedded in the portal, the portal SDK handshake, navItems, dashboard widgets, or iframe-specific UI issues.'
 ---
 
 # portal-micro-app · 嵌入式微应用（iframe + SDK）开发
 
-微应用是被 Portal 以沙箱 iframe 嵌入的普通 Web 页面：**不自己实现登录、不持有 App Secret**，身份由宿主经 postMessage 握手注入。本文件是工作流与红线；具体契约按需读 `references/`（为本 skill 提炼的自包含参考，可整目录拷到任何 repo 使用；权威源是门户仓库 `docs/SSO与App开发指引.md`，冲突以门户仓库为准）。
+微应用是被 Portal 以沙箱 iframe 嵌入的普通 Web 页面：**不自己实现登录、不持有 App Secret**，身份由宿主经 postMessage 握手注入。本文件是工作流与红线；具体契约按需读 `references/`（可整目录拷到任何 App repo 使用）。
 
 
-> **路径约定（先读这条，能省一次白找）**：本 skill 里出现的 `apps/…` `packages/…` `docs/…`
-> `deploy/…` 这类路径**都在门户仓**。在 App 自己的 repo 里它们**不存在** —— 它们标注的是
-> 「门户侧要做什么」或某段内容的出处，**不是让你去打开的文件**。找不到不是配置错误：
-> 别去创建、别去全局搜、别把它当缺失依赖报出来。你需要的一切都在本 skill 的
-> `references/`（自包含）。若你正在门户仓里工作，那这些路径就是可以直接打开的真实文件。
->
-> ⚠️ 一个例外：`/apps/<key>/`（带前导斜杠）是**线上 URL 路径**——微应用产物的挂载点，
-> 与仓内的 `apps/<key>-app/` 目录无关，别混。
+`/apps/<key>/` 是线上前端挂载 URL；本文的 `references/` 相对于本 skill 目录。
 
 ## 按任务读参考
 
@@ -25,27 +18,23 @@ description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型
 | 声明导航、scope、ACL、Widget、依赖 | [references/manifest-and-acl.md](references/manifest-and-acl.md) |
 | 调 Open API / Widget 推送 / 通知 / 内容 / 计划任务 / 审计 / 错误码 | [references/open-api-and-extensions.md](references/open-api-and-extensions.md) |
 
-门户 monorepo 内工作时的活教材：`apps/sample-app/src/main.ts`（SDK 每个能力的端到端演示）、`apps/spms-app`（重业务）、`packages/portal-sdk`（SDK 源码）。外部项目没有这些路径，以 references 为准。
+## 新建一个 micro App 前端的最小闭环
 
-## 新建一个 micro App 前端的最小闭环（门户 monorepo 内）
+1. 在 App 自己的仓库新建 Vite + React 前端，配置固定空闲端口并开启 `strictPort`，避免自动换端口后加载错应用。
+2. 安装下述公开分发的 SDK/UI 包，按本地 [SDK 参考](references/sdk-reference.md) 接入握手与路由。
+3. 在自己的 `app.manifest.json` 声明 `navItems` / `scopes` / `aclManifest` / `dashboard.widgets`；租户管理员不能代填开发者声明。
+4. Vite `base` 设为 `/apps/<key>/`，构建 `dist/`，用 `xgent-app-release` skill 的 `publish --dist` / `publish --manifest` 提交；涉及治理字段等待审批，按本次 proposal 的交付状态核对结果。
+5. 本地联调用 `portal-dev-setup` 的一盒环境。生产优先 `sdk.callService` 与同源托管；需要开发 CORS 白名单时交平台管理员处理。
+6. 在真实浏览器从宿主进入并走通主路径、路由往返与权限边界；不以构建通过代替 UI 验证。
 
-1. 新建 `apps/<key>-app`（Vite + React，复制最接近的现有 app 骨架），包名 `@xgent/<key>-app`，端口取当前空闲的 53xx（看根 `package.json` 的 `dev:all` 已占端口）。
-2. 挂进根 `package.json` 的 `dev:all`（concurrently 一把起齐）。**绝不**单独叠跑 `dev:<key>`——Vite 端口被占会自增抢相邻端口，导致别的 App iframe 加载错页面。
-3. 清单声明：`navItems` / `scopes` / `aclManifest` / `dashboard.widgets` 只能由应用自身声明（`apps/api/src/modules/acl/manifests.ts` + `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS`），租户管理员不能手填。改完重新 `db:seed` 或走清单同步更新。
-4. dev 直连 Open API 需 CORS：把 app 源加进 api 的 CORS 白名单 env；生产优先 `sdk.callService`/同源托管，前端完全不碰跨域。
-5. UI 开发遵守 CLAUDE.md 强制两步：设计用 `impeccable` skill，验证用 Chrome extension 真浏览器走通主路径。
-
-**你的 App 不在门户 monorepo 里（代码在自己的 repo）** ⇒ 上面 1–3 步一条都不适用：没有
-`apps/<key>-app` 目录、没有 `dev:all`、清单也不在 `LISTING_DEFS` 里。你的闭环是另一条：
-vite `base` 设成 `/apps/<key>/` → build 出 `dist/` → 用 `xgent-app-release` skill 的
-`publish --dist` 交上去（清单同理走 `publish --manifest`，你 repo 里那份 `app.manifest.json`
-就是唯一事实源）；想在真门户里先看一眼，把 `dist` 绝对路径挂进一盒（`portal-external-app`
-skill 的 `references/registration-and-onebox.md` §4）。**本文件其余部分（SDK 硬规则、consent、
-iframe 坑、设计红线、三份 references）与你在哪个 repo 无关，照用。**
+`@xgent/portal-sdk` / `@xgent/portal-ui` / `@xgent/shared` 在你的 repo 里**照常作为 npm 依赖安装**，
+来源是平台的私有包仓（公共 npm 上没有，直接 `bun add` 会 E404）。配法见 `xgent-app-release`
+skill 的「第 0 步」。仓里还没有 `.xgent-registry.env` ⇒ 停下，请开发者先去门户「开发者应用」生成
+配置文件。**不许 vendor**：不把 SDK 的产物或源码拷进仓，也不用 `file:` / `link:` / tar 依赖顶替。
 
 ## SDK 硬规则
 
-- 私有页面从 `const sdk = createPortalClient(); const init = await sdk.ready();` 开始。SDK 0.4.0 支持 iframe 与同源 standalone 共用自举；声明 `openModes` 后从 `/open/<key>` 进入。顶层必须处理 `ready()` typed error 和 `onContextChanged()`，失效时卸载私有视图与应用缓存，并提供显式 `openGate()`；不要自动跳登录。匿名页可不调用 `ready()`。生产从 `/apps/<key>/` 推导 key，开发的 appKey/host/apiBase 来自构建配置，不能读 URL 配认证主机。详见门户 SDK README 与 SSO §5.9。
+- 私有页面从 `const sdk = createPortalClient(); const init = await sdk.ready();` 开始。SDK 0.4.0 支持 iframe 与同源 standalone 共用自举；声明 `openModes` 后从 `/open/<key>` 进入。顶层必须处理 `ready()` typed error 和 `onContextChanged()`，失效时卸载私有视图与应用缓存，并提供显式 `openGate()`；不要自动跳登录。匿名页可不调用 `ready()`。生产从 `/apps/<key>/` 推导 key，开发的 appKey/host/apiBase 来自构建配置，不能读 URL 配认证主机。详见 [SDK 参考](references/sdk-reference.md)。
 - `sdk.getToken()` 自动缓存、到期前 30s 续签——**不要**自己存 TDT、不要写 localStorage。
 - 用户长期凭证由本 App 后端委托门户签发。前端只将新建/迁移响应保存在当前一次性展示组件；不要用 Query/Mutation 缓存保存含 secret/token 的响应。关闭后清除，复制失败提供选中文本和重试。门户集中管理入口是 `/me?tab=keys`；App 保留项目/能力/路由配置、旧密钥停用与远端撤销重试。
 - 全局平台管理员不在 TDT JWT / `InitPayload` 里；`sdk.acl.bypass` 和 `sdk.userinfo().role` 只表示当前租户。前端即使拿到 session-only `/auth/me.isPlatformAdmin` 也只能做展示，不能转发给后端授权；跨租户后端只认 TDT 自省返回的 `isPlatformAdmin`。
@@ -53,7 +42,7 @@ iframe 坑、设计红线、三份 references）与你在哪个 repo 无关，
 - 权限：`sdk.acl.can(pid)` / `sdk.acl.scope(pid)` 只做**隐藏按钮/入口**的 UX 门；真正拦截靠后端。前端判过 ≠ 安全。
 - 路由：内部路由变化调 `sdk.routeSync(path)` 同步到 `?r=`；同时**必须**订阅 `sdk.onRoute` 处理宿主推回的路由（浏览器后退、同 App 多导航项切换）。只写单向 routeSync 会出现"同一 App 两个菜单点了不切换"的 bug。二级详情页把完整路径（如 `/items/<id>`）routeSync 出去，刷新/分享才能还原。
 - 版头面包屑：调 `sdk.setBreadcrumbs(crumbs)` 上报页面层级（宿主最左恒为「应用图标 + 应用名」= 应用首页，你报的是其后那几级；首页推 `[]`，每次是整条 trail 的**全量覆盖**）。四条规矩：① 挂在**视图驱动的 effect** 上，**不要**散在各个 `routeSync()` 调用点——宿主发起的路由变化只走 `onRoute`，挂错的症状是"侧栏切页后面包屑空着"；② `onRoute("")`（空路由）必须落到首页视图，版头最左那一级靠它工作；③ 标签要异步查询才知道时**宁可少一级**，不推 id 占位、不推"加载中…"，数据回来再整条覆盖（`FR-12` 这种展示 key 可以推，内部 UUID 不可以）；④ `label` 用**自己当前的语言**解析好（宿主不翻译），切语言在 `onLocale` 里重推。上限 6 级 / label 120 字符 / route 512 字符且必须 `/` 开头（不得以 `//` 开头），超限被静默截断；末级不带 `route`。
-- **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。回归门 `apps/api/scripts/verify-app-chrome.ts`。
+- **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。浏览器验收时检查版头与 App 内容没有重复标题。
 - **帮助页入口 `helpEntry`**：清单里声明一个可空字符串，版头工具条最右侧（全屏与刷新的**左边**）就多一枚帮助按钮；不声明就不出按钮。两种形态：`"/help"` = App 内路由（宿主置 `?r=`，不离开门户，**自动档**）、`"https://docs.example.com"` = 外站文档（新标签 + `noopener`，**走治理审核**，因为门户版头等于替这个域名背书）。`/…` 与 crumb `route` 同一条规则；外站必须 https（`http://` 连回环也拒）、无 fragment。它是**安装期快照**，改了要 bump 自己的 `version`；**租户不可覆盖**（想指向自家知识库去知识库 App 建条目）。门户不托管、不渲染、不翻译帮助正文。
 - **低频入口放版头、不占侧栏**：帮助中心 / 接入指引这类低频页别长期占着侧栏一个位置 —— 用 `helpEntry` 挂到版头，并把这一级显式推进面包屑。
 - 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；高度用 `sdk.resize`；未保存更改 `sdk.setDirty(true)` 让宿主拦离开。
@@ -76,7 +65,8 @@ iframe 坑、设计红线、三份 references）与你在哪个 repo 无关，
 - **不自建**「设置」页/导航（租户配置走平台应用配置页）、**不自建**审计页（写 `POST /api/v1/audit`）。
 - **不做**「同步通讯录」：成员选择一律用 `@xgent/portal-ui` 的 `UserPicker` 按需 curated。
 - 列表页服务端分页，复用 `Page<T>` 契约与现有 helpers。
-- 复用 `packages/portal-ui` 已有组件再造新轮子。
+- 复用 `@xgent/portal-ui` 已有组件再造新轮子。
+- **页面铺满客户区，上限 1600**：iframe 就是客户区（14" 笔记本上约 1272px，App 自带侧栏再减 ~200px）。页面框架写 `mx-auto w-full max-w-[1600px]` + 页边距，**不要**把整页收成 `max-w-3xl` / `max-w-[880px]` 居中——笔记本上会左右各空 150–200px。窄只加在内容块上且**左对齐**：表单 / 设置列 ≤ 720px、Markdown 文档列 ≤ 880px、段落正文 ≤ 72ch；多个设置分区 `lg:` 并排两栏、卡片网格 `xl:` 加一列。允许居中窄列的只有：对话流（≤ 800px）、多步向导、授权 / 无权限卡片、空状态、纸面预览、弹窗 / 抽屉。
 
 ## 完成标准
 

package/skills/portal-micro-app/references/manifest-and-acl.md

@@ -1,12 +1,12 @@
 # Manifest 与 ACL 声明（微应用视角）
 
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §4/§13.2（2026-07）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 
 ## 1. 模型：开发者字段快照
 
 Manifest 的权威载体是一条**市场清单（marketplace listing）**。安装 = 把开发者字段快照复制进该租户的 `apps` 行；清单升级后租户「同步更新」重拷开发者字段（运营字段不动）。`listingKey` 就是 TDT 的 `aud`，不可改。
 
-⚠️ **ACL Manifest 和 navItems 只能由应用自身声明**（代码注册表 / 市场清单），租户管理员不能在注册表单手填。门户 monorepo 内的声明位置：ACL → `apps/api/src/modules/acl/manifests.ts`；listing → `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS`；改完重新 seed / 发布清单 / 租户同步更新。
+⚠️ **ACL Manifest 和 navItems 只能由应用自身声明**（自己的 `app.manifest.json`），租户管理员不能在注册表单手填。修改后提交完整清单发布提案，按治理要求审批，并核对已安装租户的同步结果。
 
 ## 2. 微应用相关的开发者字段
 
@@ -25,13 +25,19 @@ Manifest 的权威载体是一条**市场清单（marketplace listing）**。安
 | `extPoints` | 仅 `settings.section` |
 | `dependencies` | 依赖的其他清单（安装按拓扑序补装；卸载被依赖会拦截） |
 | `exchangeTargets` | 经令牌交换读取哪些 App（安装时自动建交换白名单 + consent 共授） |
-| `embedCsp.connectSrc` | 同源托管下的额外 connect-src（如直传对象存储） |
+| `embedCsp` | 托管前端的精确来源声明；开发版本支持 connectSrc/scriptSrc/styleSrc/fontSrc/imgSrc/mediaSrc，须正式发布并启用 strict/v2 后使用，旧门户只支持 connectSrc |
 | `tdtTtl` | TDT 有效期秒数，60–86400，默认 3600 |
 
 运营字段（租户管理员设，非 Manifest）：`visibility` / `showInCenter` / `pinned` / `enabledNavItemIds` / `webhookUrl` / `allowExchange` / `exchangeWhitelist`。
 
 ## 3. ACL Manifest schema
 
+匿名页面可以位于 `/apps/<key>/…`，不应在该路由先强制 SDK 登录；数据授权仍归 App。
+后端直出 HTML 可以正式使用 `/svc/<key>/…`，但其 cookie Path、表单、资源、fetch、
+Location 和受保护预览必须适配外部 base。独立域名复用 `publicEntrypoints` + Sites，
+声明本身不创建门户根级路径。详见 portal-external-app 的公开入口参考；发布与 CSP
+实际验收见 xgent-app-release。改 listingKey 是身份/资源迁移，不是显示名修改。
+
 ```ts
 interface AclManifest {
   version: string;          // reconcile 基准
@@ -77,3 +83,15 @@ interface AclAction {
 - Shell 经 `GET /api/apps/nav` 聚合可见应用的已启用项；点击打开 `/app/:appKey?r=<path>`，SDK 握手时 `init.route` 就是这个 path。
 - `navItems[].id` 绑定 `AclPage.navItemId` 后，侧栏按用户 ACL 隐藏无权入口——但应用前端仍要 `sdk.acl` 做 UX 门、后端仍做安全门。
 - 约定：`id` 应用内稳定（改 id = 删旧菜单加新菜单，租户启用状态受影响）；`path` 用应用内部路由（`/` 开头）；`icon` 用 Portal 支持的图标名。
+
+## CSP 与发布确认的版本边界
+
+新增扩展能力尚未因本文更新而上线；strict 默认关闭，需平台盘点来源并受控启用 v2。六类来源
+使用 HTTPS origin（connectSrc 另允许 WSS 及原样 `blob:`/`data:`），禁止通配、路径、凭据和 unsafe-inline/unsafe-eval；
+platformSources 仅 scriptSrc/styleSrc/fontSrc/connectSrc 可声明 ["jsCdn"]，跟随平台 CDN。
+省略整个 embedCsp 沿用，null 清空，对象是完整替换；来源增删均治理，排序去重不算变更。
+
+新版 delivery 追踪本次 proposalId 的审批、清单/产物、后端和网关四阶段。纯前端 backend 为
+not_applicable 仍须等网关；unknown 不当成功，superseded 表示目标被后续取代。旧门户无 delivery
+不能确认网关。CSP 只扩展本 App 的 /apps 前端，不更改门户壳、沙箱或 /svc 后端公开页策略；
+公开数据授权与真实浏览器主路径仍需单独验证。

package/skills/portal-micro-app/references/open-api-and-extensions.md

@@ -1,6 +1,6 @@
 # Open API 与扩展点（微应用视角）
 
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §8/§13/附录 B（2026-07）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 
 ## 1. 统一响应信封
 

package/skills/portal-micro-app/references/sdk-reference.md

@@ -1,6 +1,6 @@
 # SDK 与令牌参考（微应用视角）
 
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §5/§7.4/§8.1/§10（2026-08）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 
 ## 1. 握手与令牌注入
 

package/skills/prd/SKILL.md

@@ -1,23 +1,35 @@
 ---
 name: prd
-description: 以资深产品经理视角把一个想法/诉求梳理成可被 SPMS 生命周期管理的需求——项目级「概述/目标/非目标」+ 逐条 FR/NFR（含可断言的验收标准与测试用例种子），产出 PRD 文档并写入 SPMS，作为 dev-plan 的前置输入。凡用户要求「写 PRD / 写需求文档 / 梳理需求 / 拆需求 / 提需求 / 需求评审 / 把这个想法变成需求 / 录入需求」，或给出一段业务诉求并期望先把「做什么、为什么、怎样算做完」定清楚时，务必使用本 skill——即使用户没说「PRD」三个字。正文按终局全景写,分期交付建议只在末尾一次给出并逐条标明终验期,避免把阶段交付误记为整条需求已完成。Use whenever the user wants requirements written, clarified, decomposed, or filed into SPMS (FR/NFR) before any implementation planning happens; the body states the full target scope, and a final section proposes delivery phases carrying each requirement's final-acceptance phase.
+description: 撰写或优化 PRD，将业务想法转为清晰的产品目标、FR/NFR、用户场景预期状态与 UAT 验收条件，可录入 SPMS。在用户约束内推演创新性、先进性、可用性、便捷体验、美观 UI 与 AI 赋能，以 SMAR 检查需求，末尾给出分期及终验期。用户要求写需求文档、梳理或拆分需求、产品需求设计、修改 PRD 或录入需求时使用。仅评审既有 PRD 优先使用 review-prd；具体技术实现属于 dev-plan，测试方法与 TC 用例属于 test-plan。
 ---
 
 # prd · 面向 SPMS 生命周期的需求撰写
 
+仅评审既有 PRD 并产出问题/报告时使用 `review-prd`；从零撰写或按已确认意见修改需求使用本 skill，写作中的自检仍按下述质量门执行。
+
 ## 你的角色与这份文档的命运
 
-你是**资深产品经理**。你的产出有两个去处,缺一不可:
+你是**资深产品经理与产品设计者**。先在用户约束内把产品推演充分,再把选择写成可交付、可验收的需求,不只转录功能清单。你的产出有两个去处:
 
-- **SPMS**(事实源):项目下的 `FR-N` / `NFR-N` 条目,带验收标准与测试用例种子。它们会进产品待办、排迭代、被拆成 Issue、被 Agent 领取修复、最终 `shipped`——**整条生命周期都挂在你写的这几条上**。
+- **SPMS**(事实源):项目下的 `FR-N` / `NFR-N` 条目,带可断言的验收标准与场景预期状态。它们会进产品待办、排迭代、被拆成 Issue、被 Agent 领取修复、最终 `shipped`——**整条生命周期都挂在你写的这几条上**。用户只要文档或工具不可用时,如实交付未录入的文档。
 - **PRD 文档**(工作稿):`docs/PRD-<代号>.md`,评审的载体,也是下一步 `dev-plan` skill 的输入。
 
-**两条边界红线,任何情况下不越:**
+**三条内容边界:**
 
-- **内容边界——PRD 回答 what / why / 怎样算做完,不回答 how。** 技术方案、数据模型、端点设计、里程碑拆分全部属于 `dev-plan`;PRD 里出现「新建 xx 表」「加 xx 端点」「用 xx 库」就是越界——除非那是**用户给定的约束**(那就写进「约束与前提」,并注明来源是用户原话)。
+- **产品与实现——PRD 回答 what / why / 怎样算做完。** 用户旅程、信息层级、交互反馈、视觉要求与 AI 的产品行为要设计清楚;技术方案、数据模型、端点设计、算法/模型选型、技术里程碑拆分属于 `dev-plan`。用户给定或已核实的平台技术约束写进「约束与前提」并标来源,不能据此自行扩写实现方案。即使用户要技术框架 / PoC PRD,也先写清要证明的假设、对外能力与成立判据,具体架构仍由开发计划承接。
+- **验收与测试——UAT 写不同用户场景下预期到达的状态及通过条件。** 前置条件、用户意图/业务动作、可观察结果、失败/降级状态属于 PRD;操作脚本、测试数据生成、探针、故障注入、测试工具及 TC 创建属于 `test-plan`。若评测台本身是用户要求的产品能力,定义它应提供什么报告、判定与证据,不展开用于验收该评测台的测试方案。
 - **时间边界——正文写终局,分期只在末尾。** §0–§6 用**全局视角**描述这块能力**做完之后**应该是什么样:目标写终局结果,需求条目写完整能力,一条都不许因为「这期做不完」提前砍掉或写小。**分期是交付节奏的建议,不是需求的裁剪**——所有期次安排收在最后一节(§7),等全局盘完之后一次给出。写正文时脑子里冒出「本期先只做…」,那句话属于 §7,不属于 §1/§3。
 
-**一切失败模式的根源:写下了无法验收、无人拍板、或与现状冲突的需求。** 每条需求都要能回答「谁在什么条件下做什么 → 系统必须怎样(带数字)」;答不上来就标为开放问题,不许用漂亮话糊过去。
+每条需求都要能回答「谁在什么条件下做什么 → 应到达什么状态、满足什么判据」。数值阈值、明确枚举、存在/不存在、相等/不变都可断言;不为凑数字制造无依据的承诺。答不上来就标为开放问题,不许用漂亮话糊过去。
+
+## 产品推演与 SMAR 质量门
+
+新建、整体优化或评审 PRD 时读 [references/product-quality.md](references/product-quality.md);窄幅修订只使用相关规则。该参考覆盖六个设计维度、AI 价值与边界、SMAR、UAT 状态写法和反向评审。
+
+- **先推演再收敛**:创新性、先进性、可用性、便捷的用户体验、美观的 UI、AI 赋能六个维度都要考虑。沿主用户旅程寻找在约束内更好的产品形态,比较有实质差异的选择,把高价值且合理的改进落实为 FR/NFR、体验要求和验收条件;不适用的维度说明理由,不机械加功能。
+- **极致落在用户价值上**:减少用户判断、重复输入和无价值步骤,兼顾首次使用、日常使用与失败恢复。AI 能改善发现、理解、创作或决策时应主动提出并设计;写清用户控制、质量判据和不可用时的产品状态,不只加一个聊天框。
+- **SMAR**:Specific（对象/场景/边界明确）、Measurable（结果可判断）、Actionable（用户或授权主体可完成明确动作）、Reasonable（价值、质量、成本和依赖在约束内合理）。不用 Time-bound 制造开发日期;以分期建议表达交付顺序。性能时延、超时、数据有效期和指标观察窗口仍是有效的产品判据。
+- **范围由用户约束确定**:终局是这份 PRD 能力范围内的终局。PoC、明确不做的功能与系列中其他 PRD 的范围都要尊重;新提案在澄清阶段展示价值与取舍,确认后成文,不借创新扩张范围。
 
 > **路径约定**:本 skill 可整目录拷到任何 repo 使用——面向所有用 SPMS(研发项目管理)App 管理需求的团队。skill 自带的 `references/` 永远可读;正文里凡属 SPMS 平台行为的陈述(字段、枚举、渲染规则、错误码)是**平台契约**,在平台侧核实过,不需要你读到平台源码来复核。文末「本仓库(xgent-ai-portal)默认值」一节**只在门户仓内工作时适用**——装到其他 repo 时忽略它,那些路径在你的 repo 里不存在,不要去找、不要去建。`evals/` 目录(若存在)是门户仓内部的回归夹具,skill 运行期从不读它,分发时不携带。
 
@@ -25,19 +37,21 @@ description: 以资深产品经理视角把一个想法/诉求梳理成可被 SP
 
 ```
 0. 锚定生命周期位置  → 定位真实 project;读 SPMS 现状、领域语言与既有约束
-1. Grilling 需求澄清 → 建决策树;校准术语;用场景压测;按 frontier 分轮问
+1. 产品推演与澄清   → 六维设计 + SMAR;建决策树;用场景压测;按 frontier 分轮问
 2. 查重与现状核对    → pms_search + 平台现状:这条已经存在吗?已经能做了吗?
 3. 定范围            → **终局**目标 / 非目标(逐条给去向) / 优先级分档 / 依赖前置
-4. 逐条成文          → 每条 FR/NFR 按**完整能力**写:背景 → 行为 → 验收标准 → 影响面
-5. 分期交付建议      → 盘全局(本 PRD 新建 + 既有 key)切期次;每条标终验期
-6. 写入 SPMS         → 确认后 requirement_create(draft) + TC 种子 + 跨期终验声明 → 回填真实 key
+4. 逐条成文          → 完整 FR/NFR + 体验要求 + UAT 预期状态与判据
+5. 分期交付建议      → 全局切期次;每条标终验期;每期计划建议 5–8 个 Milestone
+6. 写入 SPMS         → 确认后 requirement_create(draft) + 跨期终验声明 → 回填真实 key
 7. 落盘与交接        → docs/PRD-<代号>.md + 人工补字段清单 + 交给 dev-plan
 ```
 
-除非用户明确只要「先聊聊思路」,完整走全部八步。步骤 2 绝不可跳过——**`*_create` 不幂等**,不查重就是在制造重复需求。
+按用户授权完成对应步骤;只要文档时不要求 SPMS 写入。写库前步骤 2 绝不可跳过——**需求 `*_create` 不幂等**,不查重就是在制造重复需求。
 
 ## 第 0 步:锚定生命周期位置
 
+**文档模式**:用户只要文档或 SPMS 工具不可用时,用已有简报、代码和文档定位产品范围,执行可做的现状核对,跳过 SPMS 调用与项目写入。未知项目/key 明确标未核实,新需求用 `WORK-F1` / `WORK-N1` 等工作号,不虚构实体;有落库需求且工具可用时执行下面的项目定位。
+
 SPMS 的生命周期是 `产品线 → 产品 → 版本(Release) → 项目 → 迭代 → Issue`。**需求挂在项目上**,所以先把项目钉死:
 
 1. `project_list` → 令牌白名单内的项目;`project_get(projectId)` → 成员名册(memberId 供后续指派)、迭代列表、需求/Issue/用例计数,以及**基本信息七段全量**(`summary` 概述 / `background` 背景 / `personas` 用户与场景 / `goal` 目标 / `nonGoals` 非目标 / `constraints` 约束与前提 / `openQuestions` 开放问题)。
@@ -57,7 +71,7 @@ SPMS 的生命周期是 `产品线 → 产品 → 版本(Release) → 项目 →
    | **开放问题** | `openQuestions` | §5.2 非阻塞开放问题 | **一行一条;无则 `null`** |
 
    ⚠️ 三个列表字段的每行**不要带 `-` / `*` / `1.` 前缀**——Web 端会当正文清洗掉,自己加等于白写。
-   ⚠️ `openQuestions` 只回写非阻塞项,每行格式 `Q1 [非阻塞] 问题;默认及理由;负责人;截止时间`;无则传 `null`。阻塞问题未解时不回写项目基本信息。
+   ⚠️ `openQuestions` 只回写非阻塞项,每行格式 `Q1 [非阻塞] 问题;默认及理由;负责人;解决节点`;节点用「进入哪期计划前」等,已有外部截止日期则保留;无则传 `null`。阻塞问题未解时不回写项目基本信息。
    ⚠️ 名称/状态/负责人/团队/版本等治理字段**不在** `project_update` 范围内(混进去只会被忽略),要改仍走 Web。
 
 ## 第 1 步:Grilling 需求发现与澄清(产品经理的活)
@@ -65,9 +79,9 @@ SPMS 的生命周期是 `产品线 → 产品 → 版本(Release) → 项目 →
 **Grilling 是本 skill 内置、自包含的对话协议。** 直接执行下述规则,不调用或依赖任何外部 skill。
 
 1. **逐条编号 R1…Rn**。它是**原始诉求追踪号**,创建前也暂作工作号;真实 requirement key 仍要等创建时分配(见第 6 步)。用户一句话里常藏着多条需求,拆开;这张清单贯穿全程,最终每条都要有下场。创建后 `R#` 只保留在「承接」与原始诉求追踪表中,不再作为需求编号。
-2. **拆分粒度**:一条需求 = **一个用户可感知的能力**,能被 3–10 个 Issue 实现,且能独立验收。太大(「做一个管理后台」)拆开;太小(「按钮改成蓝色」)合并或降级为 Issue——**不是所有诉求都该成为需求**,该是 Issue 的就说清楚它是 Issue。
+2. **拆分粒度**:一条需求 = **一个用户可感知、能独立验收的能力**;不在 PRD 阶段估算 Issue 数来决定粒度。太大(「做一个管理后台」)拆开;太小(「按钮改成蓝色」)合并或降级为 Issue——**不是所有诉求都该成为需求**,该是 Issue 的就说清楚它是 Issue。
 3. 每条至少回答:**谁**(角色/租户内的哪类用户)在**什么场景**下要做什么、**为什么现在做**、**不做会怎样**。
-4. **把需求沟通映射成决策树,不是静态问卷。** 树根是本期要改变的用户/业务结果;每个决策向下连接依赖它的决策。至少检查用户与权限边界、领域实体/状态语义、范围边界、验收口径、优先级/时限、依赖/降级策略,但只展开这次需求真正需要的分支,不把类目当通用清单生搬。
+4. **把需求沟通映射成决策树,不是静态问卷。** 树根是本 PRD 要改变的用户/业务结果;先按六个维度推演产品选择,再让每个决策向下连接依赖它的决策。检查用户与权限边界、领域实体/状态语义、范围边界、体验与 AI 取舍、验收口径、优先级/交付先后、依赖/降级策略,但只展开这次需求真正需要的分支,不把类目当通用清单生搬。
 5. **对话中即时校准领域语言。** 用户用词与既有规范词冲突时,当场指出差异;出现「账号」「状态」「任务」这类含义过载的词时,给出精确候选词并让用户拍板。已确定的项目特有概念记入 PRD 「领域语言」;通用软件词不记。用户对概念/状态的描述与代码或现状不一致时,先核对事实,再把「沿用现状语义还是显式改变」放进决策树。
 6. **按轮处理 frontier。** `frontier` = 前置决策已定、现在就能回答的全部问题。每轮要问完当前整个 frontier;答案依赖本轮另一个未决问题的,留到下一轮,不迫使用户在假设上作答。用 AskUserQuestion(若当前环境可用;否则直接提问),每题编号并给出**你的推荐答案及取舍理由**,然后停下等用户回答:
 
@@ -77,16 +91,16 @@ SPMS 的生命周期是 `产品线 → 产品 → 版本(Release) → 项目 →
    ```
 
 7. **事实是你的作业,决策才是用户的作业。** 能从 SPMS、代码、文档、工具或环境里查到的,先自己查,不拿去问用户。某个事实还在核对时,只暂停它下游的问题;其余 frontier 照常推进。用户已明确回答或现状已确定的不重问。
-8. **用具体业务场景压测语义与边界。** 当关键角色、实体关系或状态变化还显得抽象时,主动构造 2–4 个高信息量的场景,按「给定角色/数据/状态 → 执行动作 → 应出现的业务结果」询问。优先挑能暴露权限/租户边界、空数据、重复/超限、不允许状态或前置未就绪的例子;只问与本需求有关的,不做机械全枚举。确认后编为 `S1…Sn`,成为验收标准和 TC 种子的上游。
+8. **用具体业务场景压测语义与边界。** 当关键角色、实体关系或状态变化还显得抽象时,主动构造 2–4 个高信息量的场景,按「给定角色/数据/状态 → 业务动作 → 预期状态与判据」询问。优先挑能暴露权限/租户边界、空数据、重复/超限、不允许状态、AI 低质量或前置未就绪的例子;只问与本需求有关的,不做机械全枚举。确认后编为 `S1…Sn`,成为验收标准和 UAT 状态表的上游,不在这里设计测试步骤。
 9. **每轮答案都会重塑决策树。** 记录已定决策及理由,重算 frontier,再问下一轮;不固守最初问题清单。含糊处**不许自行补全成「看起来合理」的需求**。
-10. **把未解项分成阻塞与非阻塞两类。** 会改变用户/权限、范围、FR/NFR 类型、业务语义或验收标准的是**阻塞问题**,必须留在决策树的 frontier,不能靠默认值越过。只有「任何答案都不改变需求含义与验收」的才是**非阻塞问题**;它可从 frontier 移出,但必须记录当前默认及理由、负责人和截止时间。
+10. **把未解项分成阻塞与非阻塞两类。** 会改变用户/权限、范围、FR/NFR 类型、业务语义或验收标准的是**阻塞问题**,必须留在决策树的 frontier,不能靠默认值越过。只有「任何答案都不改变需求含义与验收」的才是**非阻塞问题**;它可从 frontier 移出,但必须记录当前默认及理由、负责人和解决节点。
 11. **共同理解是进入成文的闸口。** 只有阻塞 frontier 为空——所有分支已访问,没有被默默假设的产品决策——才把「规范词 / 已定决策 / 范围 / 场景 / 验收口径 / 非阻塞开放问题」摘要给用户,请其明确确认。确认后进入 **synthesis 模式**:只综合已有对话与查证结果,不重问、不另起一轮泛化访谈;只有成文时发现真实矛盾或新的阻塞决策,才回到对应分支并在解决后重新确认。确认前可继续事实核对,但不定稿、不更新项目基本信息、不写 SPMS;无法交互时也不得用默认值跨过阻塞问题。
 
 ## 第 2 步:查重与现状核对
 
 本步的查证**不必等需求澄清完全结束才开始**:某个 frontier 问题依赖现状事实时,先执行相应核对,再决定还有没有需要用户拍板的分支。共同理解确认后,再用下面的全量口径做最终查重与现状结论。
 
-1. **SPMS 查重**(红线):逐条 R# 跑 `pms_search(keyword)`(跨需求/Issue/用例,**上限 50 条**,用具体词别用泛词)+ `requirement_list(projectId)` 翻页看全量。命中已有需求 → 改成 `requirement_update` 补充,而不是新建一条并行的。
+1. **SPMS 查重**(写库红线):逐条 R# 跑 `pms_search(keyword)`(跨需求/Issue/用例,**上限 50 条**,用具体词别用泛词)+ `requirement_list(projectId)` 翻页看全量。命中已有需求 → 改成 `requirement_update` 补充,而不是新建一条并行的。文档模式仍核对已有 PRD/代码,未执行的 SPMS 查重明确标未核实,不得宣称「SPMS 无同类」。
 2. **现状核对**:这个能力是不是已经有了?读宿主 repo 的代码、`CLAUDE.md`、领域词汇/相关决策记录(若有)、文档目录(接入指引与既有 PRD)、历史开发计划、memory 索引。**发现需求与现实冲突(用户以为存在的能力其实没有,或以为没有的其实已经有),或用户用词与既有领域语言/决策约束冲突——如实呈现,把事实与需要拍板的产品决策分开,不要顺着错误假设写下去。**
 3. 结论落一张表,每条 R# 只有四种下场:
 
@@ -101,7 +115,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 
 **只有第 1 步的阻塞 frontier 已清空且共同理解已获用户确认,才进入本步。**
 
-- **目标**:这块能力**做完之后**要达成的**结果**(终局、可度量),不是要做的功能列表,也不是「首期做到哪」。3-5 条封顶。
+- **目标**:这块能力**做完之后**要达成的**结果**(终局、满足 SMAR),不是要做的功能列表,也不是「首期做到哪」。3-5 条封顶;标清验收门槛、观察指标与 PoC 基线,不把建议值冒充现状或已验证的效果。
 - **非目标**:逐条列出并**给去向**。⚠️ **去向里不许出现「二期 / 后期再做」**——那是分期,不是非目标。凡属于这块能力终局蓝图之内的,一律写成 FR/NFR 进 §3,再到第 5 步排到靠后的期次去;非目标只留**真的不在这份 PRD 能力边界内**的东西(另立项 / 属于别的产品域 / 明确永远不做及理由 / 依赖的底座本身另立项)。**产品经理一半的价值在这张表上**——评审时会被问「那 X 呢」的,都要提前出现在这里。
 - **优先级分档**:本系统里 `priority`(紧急度) 与 `importance`(重要度) **正交**,别混为一谈;两个 MCP 都能写,**两个都要给**。
 - **依赖与前置**:依赖别的 App / 平台底座的,写明「未就绪则本条降级为 X / 推迟到 Y」,不要写成无条件承诺。
@@ -112,21 +126,21 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 
 1. **成文是 synthesis,不是第二次访谈。** 只综合已确认对话、现状查证与非阻塞默认;不重问已回答的问题,不在写作时偷偷发明新范围。若发现矛盾或新阻塞项,精确回到第 1 步的对应分支。
 2. **先从用户视角写清问题,再写期望变化。** 问题陈述要说现在谁被什么阻碍、造成什么影响;不要把待做功能换个语序当成问题。
-3. **一条需求写它的完整能力,不写「本期版本」。** 需求是产品事实,不随交付节奏伸缩——验收标准要覆盖这条能力**做完**该有的全部断言。「边界」一栏只写**永久**不含什么(范围边界);「这期先不做」是分期边界,属于 §7,写进条目就会造出一条永远验收不了的半截需求。粒度仍按「一个用户可感知的能力」定,**不按期次切碎**:一条需求横跨两期是正常的,第 5 步会给它标终验期。
-4. **验收标准落在最高的可观察业务边界。** 每条 = 谁在什么条件下做什么 → 系统必须怎样,**带数字**;优先断言用户或外部系统真能观察到的结果,不断言内部模块、表、函数或调用次数。写不出可断言形式的,回第 1 步。
+3. **一条需求写它的完整能力,不写「本期版本」。** 需求是产品事实,不随交付节奏伸缩——验收标准要覆盖本 PRD 范围内这条能力**做完**该有的全部断言。「边界」写这份 PRD 的能力不含什么,可以指向已明确分工的其他 PRD,不等于整个产品永不做;「这期先不做」是分期边界,属于 §7。粒度仍按「一个用户可感知的能力」定,**不按期次切碎**:一条需求横跨两期是正常的,第 5 步会给它标终验期。
+4. **验收标准落在最高的可观察业务边界。** 每条 = 谁在什么条件下做什么 → 预期状态与通过判据。可用阈值、枚举、集合、相等/不变或明确的是/否;量化指标带作用域、规模/负载、分母/窗口等必要口径。优先断言用户或外部系统真能观察到的结果,不断言内部模块、表、函数或调用次数,不写测试过程。写不出可断言形式的,回第 1 步。
 5. **验收标准的物理格式(平台前端契约,别用 markdown)**:SPMS 把 `acceptanceCriteria` 按 `\n` 切行、trim、丢空行,渲染成圆点列表。**展示端一个字符都不剥**(剥 `- * • 1. 1)` 前缀只发生在 Web 编辑器保存时),所以经 MCP 写进去的前缀会**原样显示**。因此——**一行一条;不要写 `-`/`*`/`1.` 前缀(会显示成「• - xxx」);不要空行分段;不要表格/加粗/嵌套。** 唯一例外是跨期需求的 `[P1] ` 期次前缀(第 6 步),方括号不在剥离表里,写进去就是它。
 6. **PRD 正文(`description`)是完整 markdown**(markdown-it 渲染,标题/列表/表格/代码块都可以)。图片只支持 `![](xgent-attachment:<id>)` 引用且 MCP 无上传面 → **正文里不要放外链图**。
-7. **NFR 必须带 `category` + 数值**。「系统要快」不是 NFR;「列表 p95 < 300ms @ 1 万行」才是。六档质量属性见 `references/spms-mapping.md`。
-8. **平台硬约束是 NFR 的常客**,该写就写进去:多租户隔离、三语 i18n、列表服务端分页、业务错误一律 200、席位/计量口径、ACL 可见性。别默认「大家都知道」。
+7. **NFR 必须带 `category` + 作用域 + 可判断的质量门槛**。性能/容量用数值与条件,安全/易用性也可用明确状态或不变量;不把「安全」「美观」当判据。六档质量属性见 `references/spms-mapping.md`。
+8. **体验与 AI 要成为需求,平台硬约束也要有落点**。信息层级、主路径便捷性、视觉一致性、关键状态及适用的 AI 能力,写入相关 FR/NFR 并给验收条件,不只放在愿景里。多租户隔离、三语 i18n、列表服务端分页、业务错误、席位/计量口径、ACL 可见性等按宿主实际约束写,不默认「大家都知道」。
 9. **只持久化有价值的产品决策。** 会改变范围、领域语义或验收,或未来读者很可能重新争论的,记入「产品决策记录」:结论、未选方案、理由、影响需求。不把每轮问答都抄进去;模块/接口/架构/表结构等实现决策仍属于 dev-plan/架构决策,不进 PRD。
-10. **建立全链路可追溯关系**:原始诉求 → 问题/目标 → `S#` 场景 → FR/NFR → 验收标准 → TC 种子。每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键场景有验收标准覆盖,每条 FR 的验收标准至少有一个 TC 种子落点;有空白单元格就不算定稿。
-11. **不写实现方案**(见开头红线)。
+10. **建立全链路可追溯关系**:原始诉求 → 问题/目标 → `S#` 场景 → FR/NFR → 验收标准 → `UAT-#` 预期状态。每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键用户场景有明确状态与验收覆盖;有空白单元格就不算定稿。UAT 不要求 TC 已存在,由 test-plan 后续建立「验收/UAT → TC」映射。
+11. **不写实现方案或测试方法**(见开头边界)。
 
 ## 第 5 步:分期交付建议(全局盘完之后才做)
 
 到这一步,PRD 正文(§0–§6)已经是一张**终局蓝图**。现在才第一次考虑「先上哪些、后上哪些」。**分期只改变交付顺序,不改变需求集合**——不许在这一步删需求、砍验收标准,或把一条需求改小;发现某条确实不该做,回第 3 步把它挪进非目标并给去向,而不是在分期表里让它消失。
 
-1. **盘的是全局,不只是这份 PRD 新写的那几条。** 一张分期表要同时收进三类需求,每条都用**真实 key** 指名并标出来源(既有 key 来自第 2 步的查重结果,必须是真查到的):
+1. **盘的是全局,不只是这份 PRD 新写的那几条。** 一张分期表要同时收进三类需求,既有需求用**真实 key**,未录入的新需求先用工作号并在创建后回填,逐条标出来源(既有 key 来自第 2 步的查重结果,必须是真查到的):
    - **本 PRD 新建**——第 6 步创建后回填的 `FR-N` / `NFR-N`;
    - **既有需求·本次更新**——第 2 步命中的那些:只说明**本期要动它的哪几行验收**,不重述正文,更不新建一条并行的;若本次改变了它的终验期,在说明里点出来。
    - **既有需求·只作前置**——不属于本 PRD、但某一期必须等它先上才有意义的 key(别的 PRD / 别的项目)。写清依赖方向,**它们不归本 PRD 排期**,只出现在前置列。
@@ -135,7 +149,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 4. **每条需求都要落在分期表里,并标出「终验期」**——终验期 = **整条需求算完成**的那一期:
    - **单期需求**:终验期就是它唯一那一期。
    - **跨期需求**(验收标准分散在两期以上):终验期 = **最后一期**,必须显式标出,并逐期写清「这期完成的是第几行验收」。跨期是正常的,**不要为了让每条都落在单期而把需求切碎**——粒度由「一个用户可感知的能力」决定,不由期次决定。
-5. **分期是建议,期次边界不等于计划边界。** 一期落成 dev-plan 的一份计划、一份计划里的几个里程碑、还是与别的 PRD 的需求合并成一份计划,由 dev-plan 按技术依赖判断。PRD 只给**产品侧信号**:优先级分档、依赖前置、哪几条必须同期上线才有意义、哪条的终验不能提前。
+5. **用分期承接 SMAR,不凭空指定开发日期。** 每期开发计划尽量控制在 **5–8 个 Milestone**;因同一用户流程/交付连续性不宜拆开时可到 **9–10 个**,必须说明连续性理由,**最多 10 个**。超过则建议拆成更多期;小范围可少于 5 个,不为凑数增任务。PRD 只给每期价值、覆盖范围、前置和计划规模建议,不预先编排 M1…Mn、实现任务或工期。具体拆解与数量由 dev-plan 核实,超出预算时反馈分期调整,保留完整需求与终验关系。
 6. **分期表定稿后回填两处并保持一致**:§3 每个条目的「分期」行、§7 的期次总览 / 分期矩阵 / 跨期终验登记。条目那一行是要抄进 SPMS `description` 的那份——**SPMS 里的读者看不到 PRD**,两处漂了就等于界面在说谎。
 
 ## 第 6 步:写入 SPMS
@@ -145,7 +159,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 1. **`type` 必须先定死**。key 前缀在**创建时**按 `type` 分配(`functional`→`FR-N`,`non_functional`→`NFR-N`),序列是**租户级**的(不是项目级,所以编号跨项目连续)。**之后再改 `type`,key 不会跟着改**(平台契约)——建完再改就是永久错配。
 2. **`status` 一律 `draft`**。评审转 `reviewing`、批准转 `approved` 是**人**的动作,不是 Agent 该按的按钮(同 MCP「终态留给人」的既有姿势)。
 3. **建完立刻回填真实 key**:把 `R1 → FR-37` 写回 PRD 文档的追踪表**和 §7 的分期矩阵 / 跨期终验登记表**(第 5 步用工作号排的期,这时换成真实 key)。之后凡是指代需求实体/标题都一律用真实 key;`R#` 只作为原始诉求来源标识,仅出现在「承接」和 §6.1。
-4. **每条 FR 至少种 1 条 TC**:`testcase_create(projectId, title, requirementKey='FR-37', steps, expected)`,`status=draft`、`result` 默认 `untested`。验收标准里那条最难的,就是 TC 的 `expected`——**种不出 TC 的验收标准,基本可以断定是假的**,回第 4 步改。
+4. **PRD 不创建 TC**。把关键用户场景、预期状态与验收条件随需求正文写入;若该需求已有 TC,只记录真实关联供 test-plan 查重承接,不补写步骤、不因缺 TC 阻止 PRD 定稿。用户同时要求测试计划时,在 PRD 成文后另按 test-plan 展开。
 5. **跨期需求必须在 SPMS 里自带终验声明。** PRD 文档在 SPMS 之外,而按下「转已上线」的人看的是**需求抽屉**。三处一起写,缺一处这条需求就会在某个界面上说谎:
    - **`description` 开头**固定一段(正文是 markdown,引用块会正常渲染):
 
@@ -157,7 +171,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
    - **「待人工补」清单里的「版本(release)」挂终验期那一版**,不挂首期——`releaseId` 是单值字段,挂首期会让版本报表把整条需求算成那一版已交付。
 6. **知道那个会被误点的按钮长什么样(平台行为)。** 需求抽屉里,只要**该需求已关联的 Issue 全部完成**、且状态落在交付段(开发中 / 已提交 / 可测试),就会浮出一条绿色提示条,一键把需求转「已上线」。跨期需求首期只挂了首期的 Issue,**首期一完工这个按钮就亮了**——这就是「阶段交付被误记为整条需求完成」的具体发生方式。而需求侧**没有**「已上线」之后的第二个终态,点下去那一下**就是**需求级验收(还会通知需求作者)。所以终验声明必须写在需求正文里,让点按钮的人先看见。
    ⚠️ Agent 侧本来就写不到终态(`shipped` / `rejected` 会被拒:`FINAL_STATE_FORBIDDEN`)——这一条不是给你按的,是要你**把话写到他会看到的地方**。
-7. **`importance`(重要度)、`ownerId`(负责人)、`dueDate`(截止日期)三个字段 MCP 可写**,`create` 与 `update` 都收——建单时就一并给,不要再推给人去 Web 一条条点。`ownerId` 取 `project_get` 成员名册的 `memberId`(只收本租户未撤销成员),`dueDate` 是 ISO 8601;两者传 `null` 清除。
+7. **`importance`(重要度)、`ownerId`(负责人)、`dueDate`(截止日期)三个字段 MCP 可写**,`create` 与 `update` 都收。重要度必给,负责人已明确则写;**日期仅在用户或外部约束已明确时填写,不为了 SMART 的 T 自动造日期**。`ownerId` 取 `project_get` 成员名册的 `memberId`(只收本租户未撤销成员),`dueDate` 是 ISO 8601;两者传 `null` 清除,更新时未要求清除则保留原值。
    **仍然写不到、必须人工在 Web 补的**(平台契约,核对过 MCP 面的 inputSchema):`release`(版本——跨期需求挂**终验期**那一版)、附件。排期与点数属于规划期(`sprint_plan_items`),**不在 PRD 阶段做**。这些要单列一张「待人工补」清单交付。
 8. **失败就如实说**:`CAPABILITY_REQUIRED`(令牌无 write)、`PROJECT_NOT_ALLOWED`(项目不在白名单)、需求写闸要求 `requirement.manage` 或本项目 Lead——报出缺什么、怎么补,**不要绕道**(比如改去建 Issue)。
 9. **没有 MCP 令牌 / 工具不可用时不要假装写入**:产出文档 + 一份「照此在 Web 逐条建单」的清单(字段逐个给值),并明说未写入。
@@ -167,28 +181,32 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 1. **落盘** `docs/PRD-<代号>.md`(循宿主 repo 的文档目录惯例)。代号按**能力域**取(讲清这份 PRD 覆盖什么),**不必与 dev-plan 的代号对齐**——PRD 与开发计划是**多对多**:一份 PRD 可拆成多份计划,多份 PRD 的需求也常被合并进同一份计划。**唯一的关联键是 `FR-N`/`NFR-N` key,不是文件名。** 目标文件已存在时先确认再覆盖。
 2. **自检**(逐项过,不过的回去改):
    - R1…Rn 逐条有下场(新建 key / 更新 key / 已可用 / 显式排除并给去向),**一条都没吞**;
-   - 每条 FR 的验收标准 ≥1 条且**每条都能断言**;每条 NFR 有 `category` + 数值;
+   - 六维推演有实质取舍与需求落点,产品满足 SMAR;适用的 UX/UI 与 AI 能力没有停在口号,范围仍在用户约束内;
+   - 每条 FR 的验收标准 ≥1 条且**每条都能断言**;每条 NFR 有 `category` + 作用域 + 质量门槛;
    - 非目标表覆盖了所有「评审会被问到」的相邻功能,且**没有一条去向写着「二期 / 后期再做」**(那类应已成为 FR/NFR 并排进 §7 的靠后期次);
    - §0–§6 全篇按终局写,没有「本期先只做…」混进目标 / 行为 / 边界;
    - **每条需求(含本次更新的既有 key)在 §7 分期矩阵里都有一行,且都标了终验期**;跨期的另在 §7.3 登记,并在 SPMS 里三处齐:`description` 终验块 + `acceptanceCriteria` 逐行 `[P#]` 前缀 + 版本挂终验期;
    - §3 每个条目的「分期」行与 §7 分期矩阵逐字一致;分期表引用的既有 key 都是第 2 步真查到的;
-   - 每期都能说清「哪个角色多了什么以前做不到的事」,不是按技术栈切的;
+   - 每期都能说清「哪个角色多了什么以前做不到的事」,不是按技术栈切的;承接计划建议 5–8 个 Milestone,9–10 个有连续性理由,无超过 10 个的建议;
    - 项目特有概念使用同一套规范词,没有未解的重载词/状态语义冲突;
-   - 关键场景已压测业务边界,「原始诉求 → 目标/场景 → FR/NFR → 验收标准 → TC」追踪表无空白单元格;
+   - 关键场景已压测业务边界,「原始诉求 → 目标/场景 → FR/NFR → 验收标准 → UAT 预期状态」追踪表无空白单元格;相关的成功、空数据、拒绝、取消、失败恢复及 AI 降级状态有清晰判据;
    - 会影响范围/语义/验收的已定产品决策都留了结论与理由,没有混入实现决策;
-   - 全篇没有实现方案(表结构/端点/库选型/里程碑);
-   - 文档里凡是指代需求实体的都是回填后的真实 FR/NFR key;`R#` 只在「承接」与 §6.1 作原始诉求来源标识;
+   - 全篇没有自行设计的实现方案(表结构/端点/库选型/技术里程碑)或测试方法(脚本/工具/注入步骤);产品交互、已有约束与验收条件未被误删;
+   - 已录入需求用回填后的真实 FR/NFR key,未录入新需求明确标工作号;`R#` 只在「承接」与 §6.1 作原始诉求来源标识;
    - 引用的代码路径/既有能力都是本次真读过的(同 dev-plan 的「不虚构核实」)。
-   - 阻塞 frontier 已清空,共同理解已获用户确认;仅剩的非阻塞开放问题都有默认/理由/负责人/截止时间。否则只能作为草稿,且未写入 SPMS。
-3. **汇报**给用户时,除了文档路径,单独列出:① **非阻塞开放问题**及默认/负责人/截止时间(若尚有阻塞问题,必须明说文档仅是草稿且未落库);② 调查中发现的、与用户假设**冲突的事实**;③ 你砍掉/推迟的范围(让用户有机会否决);④ **已写入 SPMS 的 key 清单**(FR/NFR/TC)与本次回写的**项目基本信息段**(照第 0 步第 5 条的表);⑤ **待人工补**的字段(版本,以及评审后的状态流转——重要度/负责人/截止日期你自己写,别列进这张清单);⑥ **分期建议**:每期交付什么用户价值、覆盖哪些 key,并**逐条点名跨期需求的终验期**——「FR-38 首期完成后仍停在交付段,不得转已上线」这句话要出现在汇报里,不能只躺在文档里。
+   - 阻塞 frontier 已清空,共同理解已获用户确认;仅剩的非阻塞开放问题都有默认/理由/负责人/解决节点。否则只能作为草稿,且未写入 SPMS。
+3. **汇报**给用户时,除了文档路径,单独列出:① **非阻塞开放问题**及默认/负责人/解决节点(若尚有阻塞问题,必须明说文档仅是草稿且未落库);② 调查中发现的、与用户假设**冲突的事实**;③ 你砍掉/推迟的范围(让用户有机会否决);④ **已写入 SPMS 的 key 清单**(FR/NFR)与本次回写的**项目基本信息段**(照第 0 步第 5 条的表);⑤ **待人工补**的字段(版本,以及评审后的状态流转——MCP 可写字段不列进这张清单);⑥ **分期建议**:每期交付什么用户价值、覆盖哪些 key、承接计划的 Milestone 预算及例外理由,并**逐条点名跨期需求的终验期**——「FR-38 首期完成后仍停在交付段,不得转已上线」这句话要出现在汇报里,不能只躺在文档里。
 4. **交给 dev-plan(PRD 与计划是多对多,没有固定映射)**:交接的单位是 **`FR-N`/`NFR-N` key 的集合**,不是整份文档——一份 PRD 可拆给多份计划,一份计划也可以捞起好几份 PRD 里的需求合并做。计划取它覆盖的那组 key 当 dev-plan 第 1 步的 `R1..Rn`,计划结尾的「需求 → 设计映射」表逐条指回 SPMS 实体。SPMS 侧的落点是 `plan_create(projectId, title, requirementKeys=[...])` → `PLAN-N`,正文写回走 `plan_update({content})`——`requirementKeys` 就是这层多对多关系的实体。
    ⚠️ **一个 `PLAN-N` 只能挂同一项目的需求**:`requirementKeys` 里出现别的项目的 key 会被拒(报 `LIFECYCLE_MISMATCH`,平台契约)。跨项目的需求要合并做,只能一个项目一份计划,或先把需求迁到同一项目。
    ⚠️ **终验期必须随 key 一起交出去**:一份只覆盖 P1 的计划,里程碑全绿也**不代表**其中的跨期需求可以置「已上线」。交接说明里逐条写清「本计划完成后 FR-38 仍停在交付段,终验在 P2」——否则计划验收那一刻就会有人去点那个按钮。
-   **怎么分组是 dev-plan 的判断**(技术依赖、里程碑、可交付性);PRD 的 §7 分期给的是**产品侧信号**(优先级分档、依赖前置、哪几条必须同期上线才有意义、哪条终验不能提前),标注**供参考、非约束**——**唯独终验期不是建议**,那是需求何时算完成的事实。
+   **怎么拆解是 dev-plan 的判断**(技术依赖、里程碑、可交付性);PRD 的 §7 分期给的是**产品侧信号**与**每期 5–8 个、连续性例外最多 10 个 Milestone 的计划规模要求**,不是技术任务表。调整期次时同步更新验收分配和终验声明,不能仅在计划中悄悄提前终验。
+   **交给 test-plan**:同一组需求 key + 逐行验收标准 + UAT 场景预期状态 + 外部前置;由它选择测试方法、补齐数据/步骤/工具、查重并创建 TC。PRD 可在尚无 TC 时独立成立。
 
 ## 红线(任何情况下不违反)
 
 - **不写实现方案。** how 是 dev-plan 的活;PRD 越界一次,后面就会有两份互相打架的设计。
+- **不把 UAT 写成测试计划。** PRD 定场景预期状态与清晰的验收条件;怎么测及 TC 创建交给 test-plan。
+- **不以创新为由越过约束,也不只转录用户清单。** 六维推演要落实可验收的用户价值,用 SMAR 收敛。
 - **不虚构验收。** 写不出可断言形式的就标开放问题,不许用「体验流畅」「性能良好」占位。
 - **不把分期当成需求裁剪。** 正文按终局全景写;交付节奏只出现在 §7,不许倒过来用「这期做不完」删需求、砍验收标准或把需求写小。非目标的去向里不许写「二期」。
 - **不把阶段交付记成整条需求完成。** 跨期需求的终验期要在 PRD、需求 `description`、验收标准前缀三处都写明;「已上线」是整条需求的验收,不是某一期的完工。
@@ -205,8 +223,8 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 
 **仅当你就在 xgent-ai-portal 门户仓内工作时适用;装在其他 repo 的忽略本节(下述路径在你的 repo 里不存在)。**
 
-- **SPMS 接入**:MCP 工具 `mcp__xgent-pms__*`(`project_list`/`project_get`/`project_update`/`pms_search`/`requirement_*`/`testcase_*`/`plan_*`)。契约与错误码见 `docs/pms-mcp.md`;字段/枚举/写面缺口速查见 `references/spms-mapping.md`。
+- **SPMS 接入**:MCP 工具 `mcp__xgent-pms__*`(`project_list`/`project_get`/`project_update`/`pms_search`/`requirement_*`)。契约与错误码见 `docs/pms-mcp.md`;字段/枚举/写面缺口速查见 `references/spms-mapping.md`。
 - **文档落盘**:PRD → `docs/PRD-<大写代号>.md`(代号按能力域取);下游开发计划 → `goal/<大写代号>.md`(dev-plan skill,模板 `goal/PLAN-TEMPLATE.md`)。**两侧代号互不绑定**——PRD : 计划是**多对多**(既拆也合),靠 `FR-N`/`NFR-N` key 串联(SPMS 侧即 `plan_create(requirementKeys)`,同项目内)。
 - **平台硬约束**(需求侧口径,该进 NFR 就进):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`;列表服务端分页 `Page<T>`;三语 i18n(zh-CN/en/zh-TW);字典表 `sort` 规范;前端两步法(`impeccable` 设计 + 真浏览器验证)。
 - **已知坑来源**:当前 agent 提供的本项目记忆(若有,先看 `MEMORY.md` 索引)、根 `CLAUDE.md`、`goal/*-PROGRESS.md`。
-- **下游**:PRD 定稿后接 `dev-plan` skill 出开发计划,再由计划拆 Issue 进迭代。
+- **下游**:PRD 定稿后接 `dev-plan` skill 出开发计划,再由计划拆 Issue 进迭代;接 `test-plan` skill 将场景状态与验收条件展开为测试用例。