@tea-agent/loop-agent 0.1.0-fe-test.0

package/skills/analyze-product-requirements/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: analyze-product-requirements
+description: 面向采用 Product Analysis V4、frontend/backend 范围和 Web/Remote 接口分类的组织内部项目，先根据需求内容强制检索项目知识库，再探索代码库并据此澄清，将自然语言需求或现有需求文档整理为冻结的澄清前分析、逐题澄清记录和完整 Product Requirement，并按项目规范生成用户故事、输出规范与 Given/When/Then 验收标准。用于需求分析、需求澄清、PRD、后端分页契约或用户故事拆分；也适用于“帮我把这个需求写成 PRD”“这个需求怎么拆用户故事”“补一下验收标准”“分析下这个需求要做什么”这类请求。
+---
+
+# Analyze Product Requirements
+
+IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式文件运行 Product Analysis validator；首次校验返回 exit 0 时立即冻结。只要同源正式文件尚未通过校验，就视为未冻结草稿，当前或后续轮次都允许根据 validator 错误继续修正；校验通过后，其正文、frontmatter 和文件路径在当前 requirement 的整个生命周期内都不可变。冻结后的轮次禁止编辑、覆盖、追加、格式化、移动或删除该文件，也不得再次对该路径调用写工具。此冻结仅由本 skill 的提示词约束，不创建完整性 sidecar。澄清决策只能写入 `requirement-clarification.md`，并通过重新生成合并到 `product-requirement.md`。原始需求同样只读。
+
+本 skill 只定义需求，不分析完整代码依赖或生成实现代码。可对用户提供的仓库做定向事实搜索，但不得输出文件级影响分析。
+
+## 运行环境与外部能力
+
+- 必需：可读写当前项目文件，并能运行 Node.js `.mjs` 校验器。
+- 前置第三方 skill：`kb-design-assist`，用于根据需求内容检索项目知识库中的设计系统、业务规范、API 规范和其他项目约定。
+- 可选能力：隔离的只读代码侦察 agent。
+- 缺少隔离代码侦察 agent 时执行对应 fallback；`kb-design-assist` 为 `unavailable` 时必须先让用户选择“修复后重试”或“跳过知识库”，不得直接 fallback，也不得伪造知识库结果、代码证据或 agent 结果。
+- 调用第三方 skill 时使用当前宿主提供的原生 skill 加载机制，不假定具体命令或工具名称。
+
+## 输入与产物
+
+- 必填：自然语言需求或原始需求文档路径。
+- 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认 `both`。
+- 可选：代码仓库、知识库、历史需求、API 文档、设计系统/交互规范、业务规则、`project_root`、`requirement_id`。
+- 可选：`output_dir`，仅用于显式确认规范路径；若提供，必须等于 `<project-root>/docs/product-analysis/<requirement-id>`，不得指向其他位置。
+- 默认目录：`<project-root>/docs/product-analysis/<requirement-id>/`。
+- 固定产物：该目录内的 `product-analysis.md`、`requirement-clarification.md`、`product-requirement.md`。
+
+## Workflow
+
+- [ ] Step 0：确认输入与写入边界 ⛔ BLOCKING
+  - [ ] 原始需求必须足以识别业务目标；输入文件只读。
+  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时为 `both`，非法值或冲突的多个值必须停止。
+  - [ ] 在生成前明确回显“分析范围：frontend | backend | both”；三个产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
+  - [ ] 确定项目根：显式 `project_root` > 仓库根 > 当前项目根。
+  - [ ] 确定 requirement ID：显式值 > 需求标题 slug > `YYYYMMDD-<summary-slug>`；仅小写字母、数字和单连字符。
+  - [ ] 确定目录：默认 `<project-root>/docs/product-analysis/<requirement-id>`；显式 `output_dir` 若存在则必须与该路径相同。
+  - [ ] 用 `scripts/compute-source-identity.mjs` 计算原始需求身份：inline 输入将准确正文写入临时 UTF-8 文件后使用 `inline-source`；文件输入使用 `file-source`，其摘要同时绑定规范化真实路径与文件正文。不得自行拼接或伪造摘要。
+  - [ ] 创建目录，三个产物写入同一目录并使用同一 `requirement_id`；产物 frontmatter 不记录可由固定目录推导的项目根或来源路径。
+  - [ ] 输出路径不得与原始需求路径相同。
+  - [ ] 同源判定：同目录且已冻结 Product Analysis 的“原始需求身份”与本次计算值完全一致。不满足则停止，不得混写；需要更正时使用新的 `requirement_id` 与目录。
+  - [ ] 目标目录已有同源 `product-analysis.md` 时，先以只读方式运行 Product Analysis validator：通过则视为已冻结并跳过 Step 1；失败则视为未冻结草稿，继续 Step 1，按 validator 错误修正并重试。只有已通过校验的文件才禁止后续写入；不得把“文件已存在”本身当作冻结依据。
+  - [ ] 已有同源任务中，Product Analysis 未通过校验时继续 Step 1 修正草稿；已通过校验并冻结后只能继续更新 Clarification 和 Product Requirement。用户回答当前澄清问题即授权原子更新本流程创建的 pending 产物。覆盖 complete 产物、非本流程创建的文件或来源无法确认的文件前必须单独确认。如已冻结 Product Analysis 的内容需要更正，停止当前 requirement，使用新的 `requirement_id` 和目录重新开始。
+- [ ] Step 1：一次性生成并冻结 Product Analysis ⚠️ REQUIRED
+  - [ ] 读取 `references/product-analysis-schema.md`，按契约生成；字段、章节与状态枚举以该文件为准。
+  - [ ] 从原始需求提取业务目标、领域对象、角色、关键动作、状态/边界、权限、接口与分页线索，形成仅覆盖当前需求的知识库检索计划；不得先探索代码库再反推检索词。
+  - [ ] 首先读取并执行 `references/kb-integration.md`，按其状态机调用 `kb-design-assist`。每次新 requirement 都必须真实执行知识检索，不得因需求简单、未显式提到项目规范或模型判断“无需知识库”而跳过。
+  - [ ] 知识库状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才允许进入项目资料预扫描与常规代码探索；其余情况保持阻断。
+  - [ ] 知识库门禁通过后，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`：先枚举文件，再读取入口文档及与当前需求直接相关的内容；缺失目录记录 `not-found` 并继续，不做无边界加载。
+  - [ ] 然后读取并执行 `references/clarification-and-knowledge.md` 第 1 节，按需求问题和知识库结论定向探索代码库。当前宿主支持隔离的只读代码侦察 agent 时，优先委派限定范围的代码探索；不支持时由当前 agent 执行同等范围的定向搜索并只保留精简结果，不得阻断或扩大搜索范围。知识库结论不得替代代码落点证据。
+  - [ ] 汇总原始需求、`KB-FACT-*`、项目资料与 `CODE-FACT-*`，识别可查明事实、冲突、unknown 和必须由用户选择的目标行为；完成以上顺序后才生成待确认问题并进入 Step 2。
+  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。
+  - [ ] scope 包含 backend 且需求涉及接口/API 时，必须确认实现范围为 Web、Remote 或 Web + Remote；只写笼统“接口/API”视为待确认问题。不得依据知识库或代码现状替用户选择。
+  - [ ] 仅按 target 生成精简故事骨架和逐故事初步输出规范：`frontend` 只生成 `FE-US-*`，`backend` 只生成 `BE-US-*`，`both` 才生成两端。
+  - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。每个前端故事的同 ID 初步输出规范必须包含“页面路由”：独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
+  - [ ] “原始需求”必须记录 Step 0 计算的 `原始需求身份`；后续所有 Clarification 的“来源/澄清来源”记录相同的原始需求身份。
+  - [ ] 只要存在任一未确认的推断需求、产品问题或目标行为 unknown，就使用 `ready-for-clarification`。只有“推断需求”明确写 `- 无未确认的推断需求。` 且“待确认问题”明确写 `- 无待确认问题。` 时，才允许使用 `no-clarification-required`。
+  - [ ] 写入前完成全部分析内容。若判断无需澄清，先按 Step 2 直接询问用户是否需要补充；收到“无需补充”或补充内容并重新完成判断后再写入正式文件。
+  - [ ] 将完整分析写入正式 `<project-root>/docs/product-analysis/<requirement-id>/product-analysis.md`，此时标记为“已写入、未冻结”；不得创建空文件、占位文件或另一个候选版本。
+  - [ ] 立即对正式文件运行 `node <skill-root>/scripts/validate-product-analysis.mjs <product-analysis.md> --target <frontend|backend|both>`，target 使用 Step 0 的归一化值。校验失败时，根据明确错误重新生成并覆盖尚未冻结的正式文件，然后重新校验；执行中断后也可在下一轮继续修正同源未冻结草稿。未返回 exit 0 前禁止生成 Clarification 或进入 Step 2 的逐题决策澄清。上一条“无需澄清”场景的内容补充确认是正式写入前的唯一例外。
+  - [ ] 正式文件首次校验返回 exit 0 时，立即在当前执行上下文中把该路径标记为禁止写入并视为冻结；从该时刻起，当前及后续澄清轮次不得再调用写工具处理该路径。不得在校验通过与冻结之间修改、格式化或重新渲染文件。
+- [ ] Step 2：决策树访谈 ⚠️ REQUIRED
+  - [ ] 读取 `references/clarification-and-knowledge.md` 第 2 节（含回答复核）和 `references/requirement-clarification-schema.md`。
+  - [ ] 每轮先给推荐答案和理由，只问一个决策问题并等待回答；不得合并多个问题，也不得仅因用户已回答就标记 confirmed。
+  - [ ] 所有分支收敛后，必须汇总范围、规则、状态/边界、已确认的默认产品行为和非目标，并单独询问用户是否确认以上共同理解或需要补充/修正；未收到明确确认前保持 `pending`。用户补充或修正后重新收敛、重新汇总并再次请求确认。
+  - [ ] 仅当不存在任何未确认推断需求、产品问题或目标行为 unknown 时，才跳过决策问题访谈并直接询问用户是否还有内容需要补充；用户补充后重新判断，只有用户明确表示无需补充或确认继续后，才能生成 complete 产物。
+  - [ ] 本步只做访谈与回答复核，不执行合成规则；合成在 Step 4。
+- [ ] Step 3：记录 Requirement Clarification ⚠️ REQUIRED
+  - [ ] 每轮访谈后更新 Clarification：记录总澄清轮数，并为每个问题记录所属轮次、推荐答案、用户原始回答、最终决策、决策来源和目标位置；依赖和备选仅在适用时记录。
+  - [ ] 所有实际生成的 `Q-*` 都是产品决策，必须由用户确认；P0、P1 或 P2 只要未解决都保持 `pending`，不得通过默认假设完成需求。
+  - [ ] 用户确认共同理解后，在决策索引写入 `- 共同理解：已确认`，再进入 Step 4 将 Clarification/Product Requirement 标为 `complete`。
+- [ ] Step 4：重新生成 Product Requirement ⛔ BLOCKING
+  - [ ] 读取 `references/product-requirement-schema.md`、`references/acceptance-criteria.md` 和 `references/clarification-and-knowledge.md` 第 3 节；按契约与 AC 规则重新生成，不做字符串回写。
+  - [ ] 澄清进行中：每次合成后重写 `pending` Product Requirement，并保留“未决事项”；不得标为 `complete`。
+  - [ ] pending Clarification 与 pending Product Requirement 写入后，使用 `--allow-pending` 运行二者校验器；两者状态必须一致。`--allow-pending` 仅用于内部中间产物校验，不得用于最终交付或下游消费。
+  - [ ] 共同理解已确认后：生成 `complete` Product Requirement；Clarification 同步为 `complete`。
+  - [ ] 优先级：用户确认决策 > 原始明确需求 > 当前有效的知识库项目规范 > 模型推断；知识库/代码事实只用于理解项目规范与现状、发现冲突和辅助澄清，不得发明产品意图。
+  - [ ] 不得把 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库路径或代码符号原样写入 Product Requirement。
+  - [ ] 用户故事只描述角色/使用方、目标/能力、价值、入口/触发方式和 AC 引用；详细产品行为只写在同 ID 输出规范中，正式 AC 嵌入该输出规范。
+  - [ ] 逐个检查每个 `FE-US-*` 的同 ID 输出规范并写入“页面路由”，不得因多个故事共享页面而省略或合并该字段。独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
+  - [ ] target 为 `backend` 或 `both` 时，后端故事只定义 API 的业务能力、输入输出语义、权限和规则；触发方式写 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`。Web + Remote 表示同一能力需要两个接口；具体 Method+Path 及 DTO 留给依赖 skill。
+  - [ ] 后端分页：每页条数允许值按“原始需求/用户确认 > 有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他契约不得从知识库 API 文档自动带入。
+- [ ] Step 5：验证并交付 ⛔ BLOCKING
+  - [ ] 再次以只读方式向已冻结 Product Analysis 和 Product Requirement 校验器传入归一化 target，只运行三个当前产物校验器；Product Analysis 在 Step 1 已通过正式文件校验，本步不得因任何原因修改它。交付路径不得使用 `--allow-pending`。
+  - [ ] Requirement Clarification 校验器核对 Product Analysis/Clarification 的原始需求身份，以及三个产物的 requirement ID、analysis scope 和状态；冻结不做脚本校验。
+  - [ ] 只有所有命令返回 0 才能声明完成。本步只交付 complete V4 Product Requirement；下游 `analyze-product-dependencies` 首选消费该产物，其 `--target` 可为本次 `analysis_scope` 的子集。
+  - [ ] `test-validators.mjs` 仅在修改本 skill 的输出契约、schema、validator、artifact version、示例、forward-test contract，或发布/安装/回归验证时运行；普通需求分析不运行 validator matrix。
+
+完整格式示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
+
+## 完成规则
+
+- `no-clarification-required` 仍生成三个产物，但只适用于“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 的场景；Clarification 使用“澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
+- 需要澄清的 `complete` Clarification：全部分支 resolved，所有实际 `Q-*` 为 `confirmed/user`，决策索引含 `- 共同理解：已确认`，每个 `DEC-Q-*` 进入 Product Requirement 决策追溯。
+- Product Requirement 必须自包含；只描述目标产品行为，不得出现 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置或实现算法。
+- 不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
+
+## Anti-Patterns
+
+- 把首次写入正式 `product-analysis.md` 等同于冻结，未运行 validator 就进入澄清；或在 validator 非 0 时冻结错误版本。
+- 正式文件校验通过后、冻结前再次渲染或格式化；或冻结后以“修复校验问题”为由继续修改。
+- 回写、覆盖、格式化、移动或删除已冻结的 `product-analysis.md`。
+- 把 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库路径、`*Controller/*Service` 符号或“证据位置”写入 Product Requirement。
+- 未获用户明确确认（含共同理解确认）就把 Clarification/Product Requirement 标为 `complete`。
+- 无需澄清时未询问用户是否需要补充，或未收到明确的无需补充/继续确认就生成产物。
+- `kb-design-assist` 为 `unavailable` 时，未让用户选择修复或跳过就继续代码库降级或生成 complete 产物。
+- 在每个新 requirement 开始时跳过知识库、先探索代码库，或用“需求简单/未涉及项目规范”记录未执行状态。
+- 用默认假设消掉未解决的 P0/P1/P2。
+- 把推断需求、含糊需求、缺失产品行为、冲突或多种合理解释留在 Product Analysis 中，却不进入用户澄清。
+- 在 Product Analysis 写正式 `AC-*` 或 Given/When/Then。
+- 任何前端故事的同 ID Product Analysis 或 Product Requirement 输出规范缺少“页面路由”，或因共享页面而只在其中一个故事中填写。
+- 输入已给出分页允许值时，用知识库规范或默认 `10/20/50/100` 覆盖；或从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+- 生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或边界 case 章节。
+
+## 交付前自检
+
+声明完成前逐项确认，任一不满足不得交付：
+
+- [ ] 三个 V4 产物写入同一 `docs/product-analysis/<requirement-id>/`，共享同一 `requirement_id`，且不含可推导的项目根或来源路径 frontmatter。
+- [ ] 正式 `product-analysis.md` 已先写入并使用归一化 target 通过 Product Analysis validator；首次 exit 0 后立即冻结，且冻结前没有开始逐题澄清。
+- [ ] validator 首次通过并冻结后，没有再次对 `product-analysis.md` 调用任何写入、格式化、移动或删除工具，正文、frontmatter 和路径保持不变。
+- [ ] Product Analysis 与 Clarification 记录相同的原始需求身份。
+- [ ] `complete` 场景下所有实际 `Q-*` 均为 `confirmed/user`，无未确认的产品行为或默认假设。
+- [ ] 三个当前产物校验器全部返回 exit 0；任一非 0 都不算完成。
+
+## Validation
+
+把 `<skill-root>` 解析为本 `SKILL.md` 所在目录，全部参数使用绝对路径：
+
+```bash
+node <skill-root>/scripts/validate-product-analysis.mjs <product-analysis.md> --target <frontend|backend|both>
+node <skill-root>/scripts/validate-product-requirement.mjs <product-requirement.md> --target <frontend|backend|both>
+node <skill-root>/scripts/validate-requirement-clarification.mjs <product-analysis.md> <requirement-clarification.md> <product-requirement.md>
+```
+
+使用以下命令计算原始需求身份：
+
+```bash
+node <skill-root>/scripts/compute-source-identity.mjs inline-source <包含准确 inline 需求正文的临时文件>
+node <skill-root>/scripts/compute-source-identity.mjs file-source <原始需求文件>
+```
+
+需要澄清时，Clarification 与 Product Requirement 都为 `pending` 后才可对二者加 `--allow-pending`。该参数保持默认 fail-closed：不带参数时必须为 `complete`；下游和最终交付禁止使用。
+
+维护或发布时额外运行 `node <skill-root>/scripts/test-validators.mjs`。

package/skills/analyze-product-requirements/references/acceptance-criteria.md

@@ -0,0 +1,87 @@
+# 详细验收标准规则
+
+## 基本要求
+
+每条验收标准必须独立可执行、结果可观察，并使用 Given/When/Then。一个用户故事存在多个关键流程时，拆成多个 AC，不要把互不相关的行为塞入一条 AC。
+
+涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范冲突时先澄清目标行为。
+
+每条 AC 必须说明：
+
+1. Given：用户身份、权限、业务数据、系统状态和必要依赖。
+2. When：具体操作、请求、事件或任务触发。
+3. Then：明确的 UI、状态、字段值、状态码、数据变化或日志结果。
+4. 异常场景：空数据、错误输入、无权限、超时、依赖失败及恢复方式。
+5. 禁止行为：不得泄露、重复提交、产生脏数据、白屏或静默失败等。
+
+## 分段最低要求
+
+- Given：至少 1 个具体条目。
+- When：至少 1 个具体条目。
+- Then：至少 2 个可观察条目。
+- 异常场景：至少 1 个条目；每个条目必须同时写明具体触发条件和可观察处理结果。
+- 四段总计：至少 6 个条目。
+- Then 或异常场景：至少包含一个禁止行为、失败保护、保留、恢复、重试或兜底结果。
+
+不得在 AC 中使用“功能正常、应正常展示、展示正确、接口可用、数据正确、符合预期、妥善处理、合理处理”等模糊结果。
+不得用“无异常情况”“没有需要处理的异常场景”“无需处理失败”等表述代替异常处理结果。
+
+## 前端示例
+
+```md
+#### AC-FE-001 展示退款处理中状态
+
+Given：
+- 用户已登录且订单属于当前用户。
+- 订单存在退款记录，refundStatus 为 processing。
+
+When：
+- 用户从订单列表进入该订单详情页。
+
+Then：
+- 退款进度模块展示“退款处理中”。
+- 展示 currentStep 和格式化后的 updatedAt。
+- 请求完成后 loading 状态消失。
+- 页面不得展示其他订单的退款数据。
+
+异常场景：
+- 请求超时时展示失败提示和重试入口。
+- currentStep 缺失时展示“状态未知”，页面不得白屏。
+```
+
+## 后端示例
+
+输出规范与故事不得自行发明 HTTP 方法、路径或 DTO。AC 的 When/Then 使用可观察的业务触发与结果；仅当原始需求或用户澄清已明确给出方法/路径时，才可在 AC 中原样引用。
+
+```md
+#### AC-BE-001 返回退款处理中状态
+
+Given：
+- 请求用户已认证且拥有目标订单。
+- 退款记录状态为 processing。
+
+When：
+- 用户请求查询该订单的退款状态。
+
+Then：
+- 返回成功状态。
+- refundStatus 为 processing，failedReason 为 null。
+- currentStep 与退款记录一致，updatedAt 使用约定时间格式。
+- 响应不得包含内部错误堆栈或其他用户数据。
+
+异常场景：
+- 订单不存在时返回标准“资源不存在”错误结构。
+- 无权访问时返回标准“禁止访问”错误，且不得泄露订单详情。
+```
+
+## 不合格写法
+
+以下内容不能单独作为验收标准：
+
+- 功能正常。
+- 页面展示正确。
+- 接口可用。
+- 数据符合预期。
+- 异常情况正确处理。
+
+必须将“正常、正确、可用、符合预期”替换为可核对的具体结果。

package/skills/analyze-product-requirements/references/clarification-and-knowledge.md

@@ -0,0 +1,70 @@
+# 澄清、代码事实与合成规则
+
+## 1. 知识库与代码事实
+
+每个新 requirement 先从需求内容形成定向检索计划，再读取并执行 `kb-integration.md`，直接沿用其中的状态机、用户处置和降级边界。知识库门禁通过后才能预扫描项目资料和探索代码库；为核验实际实现而进行的代码搜索仍不得把代码现状冒充项目规范。
+
+项目资料预扫描的时机与顺序按 `kb-integration.md` 执行；命中内容不得替代真实代码证据。
+
+有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
+
+提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+
+scope 包含 backend 且涉及分页时：每页条数允许值以原始需求/用户确认为准；未说明时优先采用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才使用默认集合 `10`、`20`、`50`、`100`。不得把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动合并为产品需求。分析状态变量、空数据、loading、error、disabled 或兜底行为时，优先以当前有效知识库规范为项目规范来源，再核验仓库级指令、设计系统、共享组件和同类实现；未查明时写 unknown，不得用通用惯例冒充项目规范。
+
+unknown 按影响分流：会改变范围、权限、业务规则、用户可感知输出/状态/边界或验收结果时，提炼成目标行为的产品决策并进入澄清；只涉及代码位置、符号、实现方式、技术复用或证据缺失时，保留为 `CODE-FACT-*` unknown 并交给依赖分析，不向用户提问，也不进入 Product Requirement。不得询问用户“代码在哪里”；应询问用户希望产品表现为何。
+
+scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remote 属于必须由用户确认的产品范围。只写笼统“接口/API”时生成一个澄清问题；确认结果写入现有“触发方式”，不得新增接口形态字段。Web + Remote 表示同一能力需要两个 HTTP 接口。
+
+知识库、代码或需求之间冲突时：保留来源证据、生成澄清问题、用户裁决前不选边。过期、适用范围不明、互相冲突或无来源定位的知识结果按 unknown 处理。
+
+## 2. 决策树式访谈
+
+1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题。
+2. 标注分支依赖，从范围、权限、核心流程、数据语义等基础决策开始。
+3. 每轮只处理一个决策问题：先给推荐答案和理由，再提问并等待回答。任何两个待决子项都不得合并为一次提问。
+4. 收到回答后重新识别剩余推断、模糊点、缺失项、冲突和新引入的未定义产品内容；只要仍存在未确认产品问题或需求，就开启下一轮。
+5. 一次助手提问与用户回答记为一轮；轮数由未解决决策决定，不设置人为上限。
+6. 所有分支解决后，必须总结范围、规则、状态/边界、已确认的默认产品行为和非目标，并单独询问用户“是否确认以上共同理解，或是否需要补充/修正”。用户明确确认前保持 pending：可反复生成 pending Product Requirement（含“未决事项”），但不得标为 complete。
+7. 用户提出补充或修正时，将新内容纳入决策树，重新识别受影响分支与模糊点；收敛后必须重新输出完整的共同理解汇总并再次请求确认。只有用户明确确认当前汇总后，才能在 Clarification 决策索引写入 `- 共同理解：已确认` 并合成 complete Product Requirement。
+
+能从环境、知识库、代码或项目资料查明的是事实，必须按“需求驱动的知识库检索 → 项目资料预扫描 → 定向代码探索”的顺序先查证，不询问用户。完成事实查证后，需要在多个目标行为之间选择的产品决策才逐项交给用户确认。分页沿用第 1 节已确定的来源优先级。
+
+### 回答复核
+
+收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求或已有决策冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
+
+任一条件不满足时：
+
+- 保留用户原始回答，`最终决策` 写“未形成”并说明具体模糊点。
+- P0/P1 使用 `pending-blocking`；P2 可使用 `pending-non-blocking` 并记录未确认影响。任何级别未确认时都不得生成 complete Product Requirement。
+- 下一轮优先继续当前分支，明确指出上一轮回答仍不清晰的部分，并将问题收窄为可直接确认的决策点；不得原样重复问题或跳到其他分支。
+- 不得把模型推断、推荐答案或代码现状当作用户确认。
+
+当前问题明确后，再扫描全部推断需求、其他未解决问题和本次回答新引入的模糊点。只要内容属于产品需求或目标行为且尚未确认，就必须继续澄清；纯措辞、代码位置、符号、实现方式、技术复用和其他不构成产品需求的下游技术细节不消耗澄清轮次。
+
+问题等级：
+
+- P0：改变范围、权限、关键流程、数据语义或验收结果；必须由用户明确确认。
+- P1：可以推荐默认值，但必须经用户确认。
+- P2：可排到后续澄清轮次，但仍须用户确认后才能 complete；只要影响产品行为或验收就必须保持 pending。不影响产品行为的实现问题不属于 P2，按实现事实 unknown 处理。
+
+只有“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 时，才跳过决策问题访谈；冻结 Product Analysis 和生成正式产物前，仍须直接询问用户“当前需求无需进一步澄清，是否还有内容需要补充”。用户补充内容时，将其并入本次输入后重新判断；只要出现新的推断、含糊、缺失、冲突或多种合理解释，就转入逐题澄清。只有用户明确表示无需补充或确认继续，才能生成 `no-clarification-required` 的 Product Analysis、complete Clarification 和 complete Product Requirement。不得把模型判断的“没有问题”自动视为用户确认，也不得为这次补充确认伪造 `BR-*`、`Q-*` 或 `DEC-Q-*`。
+
+## 3. 合成规则
+
+Product Analysis 必须先写入正式路径，再对正式文件运行 validator；同源文件尚未通过校验时视为未冻结草稿，当前或后续轮次都可按错误继续修正，首次返回 exit 0 时立即冻结。冻结后不得回写，冻结只由 skill 提示词约束。Clarification 的“来源/澄清来源”记录相同的原始需求身份；`最终决策` 是合成最终需求的规范化事实；`目标位置` 指向需求范围、业务规则、故事、输出规范或 AC。
+
+三个产物必须写入同一 `<project-root>/docs/product-analysis/<requirement-id>/`。同目录来源使用相对路径，避免把个人机器绝对路径写入可交接产物。
+
+生成 Product Requirement 时：
+
+- 用户确认的推断转为正式需求。
+- 用户否定的推断删除或进入非目标。
+- 用户确认的推荐值或默认行为进入规则和故事，并保留用户决策来源。
+- 当前有效知识库规范可用于填补项目既定的状态、组件、文案、交互和分页允许值；合成时转换为产品语言，不保留 `KB-FACT-*`、知识库路径、搜索过程或纯实现规范名称。
+- 代码库事实只用于解释现状、识别冲突和支持澄清，不作为独立需求来源；未经用户确认且未被原始需求明确要求的代码现状不得进入 Product Requirement。
+- 需要合并的代码事实必须转换为目标产品语言，只保留用户可感知的行为、业务规则和验收结果；`CODE-FACT-*`、证据路径、代码符号、模块结构、数据表和实现过程继续留在 Product Analysis 或 Clarification。
+- 决策影响故事时重新生成故事与 AC，不只在决策列表堆积答案。
+- `DEC-Q-*` 在决策追溯中登记，并能定位到正式章节。
+- 无需澄清时不生成任何 `DEC-Q-*`，说明需求直接来源于原始需求。

package/skills/analyze-product-requirements/references/example.md

@@ -0,0 +1,104 @@
+# V4 无需澄清路径示例
+
+需求：登录用户在个人资料页修改昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+
+## Product Analysis 关键结构
+
+```md
+---
+artifact_version: "4.0"
+artifact_type: product-analysis
+requirement_id: profile-nickname
+analysis_scope: frontend
+analysis_status: no-clarification-required
+---
+
+## 1. 原始需求
+- 原始需求身份：inline:sha256:<64位小写十六进制摘要>
+- 正文：登录用户在个人资料页修改昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+
+## 4. 需求分析
+### 4.1 明确需求
+- 登录用户可以在个人资料页修改自己的昵称。
+### 4.2 推断需求
+- 无未确认的推断需求。
+### 4.3 待确认问题
+- 无待确认问题。
+- 理由：范围、权限、校验、失败恢复和非目标均已由原始需求明确。
+### 4.4 初步非目标
+- 不修改头像。
+
+## 6. 初步前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收关注点：合法值可保存；非法值不可提交；失败时保留输入
+
+## 7. 初步前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：保存失败时保留输入，不得静默失败
+```
+
+Product Analysis 不创建正式 AC；每个前端故事的同 ID 初步输出规范都填写页面路由。
+
+## 无需澄清记录
+
+生成以下产物前，先询问用户是否还有内容需要补充；用户明确回复无需补充后再冻结 Product Analysis。
+
+```md
+## 1. 澄清结论
+- 状态：no-clarification-required
+- 原因：范围、权限、数据语义和验收结果已经明确。
+- 内容补充：用户已确认无需补充
+## 2. 来源
+- Product Analysis：./product-analysis.md
+- 原始需求身份：inline:sha256:<与 Product Analysis 一致的摘要>
+## 3. 合并结果
+- Product Requirement 根据明确需求生成，无额外决策标记。
+```
+
+## Product Requirement 故事、规范与 AC
+
+```md
+## 5. 前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收标准：AC-FE-001
+
+## 6. 前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 页面路由：/account/profile
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+
+#### AC-FE-001 保存合法昵称
+Given：
+- 用户已登录并打开个人资料页。
+When：
+- 用户输入合法昵称并点击保存。
+Then：
+- 页面提交昵称修改请求。
+- 保存成功后展示新昵称。
+- 保存期间按钮保持 disabled。
+异常场景：
+- 保存失败时保留输入并提供重试入口。
+```
+
+故事与输出规范使用同一 ID；故事只引用 AC，AC 正文只在对应输出规范中出现一次。

package/skills/analyze-product-requirements/references/forward-test-cases.md

@@ -0,0 +1,144 @@
+# Forward-Test Cases
+
+在独立 agent 中逐个执行，不提供预期正文，只核对不变量。
+
+## Case 1：无需澄清
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=frontend`。
+需求：登录用户在个人资料页修改自己的昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+```
+
+核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
+
+## Case 2：需要逐题澄清
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=both`。
+需求：管理员可以导出用户数据。
+```
+
+核对：角色定义、导出范围、敏感字段、文件格式、有效期和失败行为中任何推断、含糊、缺失或多种合理解释都进入待确认问题；按实际决策树列出分支；每轮先推荐再只问一个决策问题；收到回答后重新扫描全部未确认产品内容；`clarification_rounds` 和问题轮次一致且不受人为上限约束；全部分支收敛后必须汇总范围、规则、状态/边界、已确认默认行为和非目标，并询问用户确认或补充；用户补充后重新收敛并再次汇总确认；明确确认前保持 pending；不得回写 Product Analysis。
+
+## Case 3：后端 API 业务需求
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
+需求：登录用户查询自己订单的退款状态，失败时看到可理解原因，内部错误不得泄露。
+```
+
+核对：必须先询问该接口实现为 Web、Remote 还是 Web + Remote；确认前保持 pending。确认后 BE 故事只保留能力、使用方、价值、明确的 `API（Web）|API（Remote）|API（Web + Remote）` 触发方式和 AC 引用；同 ID 输出规范明确输入输出语义、权限和规则；不虚构最终 URL、HTTP 方法、DTO 或代码落点。
+
+## Case 4：非 API 后端任务
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
+需求：每天归档 90 天前已完成通知，重复执行不得重复归档。
+```
+
+核对：触发方式明确为定时任务；包含批次、幂等、并发和失败恢复；不会把它误标为 API。
+
+## Case 5：回答仍然模糊
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=both`。
+需求：管理员可以导出用户数据。
+第一轮询问导出字段范围时，用户回答：敏感字段按实际情况处理。
+```
+
+核对：不得把该回答标记为 confirmed；保留原始回答，最终决策写“未形成”并说明无法确定的字段；当前分支保持 unresolved；下一轮继续当前分支并明确指出手机号、邮箱等字段仍未确定，给出可直接确认的推荐方案；不得跳到文件格式或导出入口。
+
+## Case 6：下一轮消除模糊
+
+```text
+沿用 Case 5。下一轮用户回答：导出邮箱，不导出手机号和身份证号。
+```
+
+核对：形成唯一字段规则并标记 confirmed；最终决策明确列出包含和排除字段；当前分支 resolved；重新扫描其他剩余问题和该回答新引入的模糊点；仅在仍会影响范围、规则、输出或验收时进入下一轮。
+
+## Case 7：代码事实不得泄漏到最终需求
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`，并提供一个仓库。
+需求：仅管理员可以导出用户数据。仓库中现有权限判断位于 src/auth/permission.ts，使用 role=admin。
+```
+
+核对：Product Analysis 可记录 `CODE-FACT-*`、证据路径和现状；Clarification 可引用该证据辅助判断，但不得把现状自动视为目标决策；Product Requirement 只写“仅管理员可以导出用户数据”等产品规则，不包含 `CODE-FACT-*`、`src/auth/permission.ts`、`role=admin`、代码符号、模块结构或当前实现过程。
+
+## Case 8：分页允许值来源
+
+```text
+显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
+A：需求明确 pageSize 为必填，但未给出允许值集合。
+B：需求明确 pageSize 允许值为 5、10、20。
+```
+
+知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 原样沿用 `5/10/20`，不得被知识库或默认集合覆盖。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+
+## Case 9：项目状态与空数据规范
+
+使用包含统一空状态组件、loading/error 枚举和同类列表页的仓库。核对：当前宿主支持隔离的只读代码侦察 agent 时优先委派探索；不支持时由当前 agent 执行同等范围的受限、定向搜索；Product Analysis 与 Product Requirement 使用项目真实状态名、共享空状态组件及恢复交互；不得用 generic `empty` 或自造文案替代项目规范。
+
+## Case 10：unknown 分流
+
+仓库中未定位到空数据规范，但需求要求定义空数据展示。核对：把目标空数据行为作为产品决策逐题澄清，不询问代码位置。若仅未定位到组件文件或状态枚举声明位置，则保留 `CODE-FACT-*` unknown 并交给依赖 skill，不进入澄清或 Product Requirement。
+
+## Case 11：所有实际问题都由用户确认
+
+使用包含推断需求和 P2 产品行为决策的需求。核对：每项推断需求都进入待确认问题并由用户逐题确认；用户确认前 Clarification 和 Product Requirement 保持 pending；不得生成 `default-confirmed` 或 `confirmed-default`；complete 时每个实际 `Q-*` 都为 `confirmed/user`。
+
+## Case 12：原始明确行为不伪造问题
+
+原始需求明确指定页面路由、权限和错误恢复方式。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认。
+
+## Case 13：页面路由
+
+分别使用独立页面、嵌入式抽屉以及两个共享同一页面的前端故事。核对：Product Analysis 和 Product Requirement 的每个前端故事输出规范都包含页面路由；独立页面写以 `/` 开头的目标 URL；抽屉写“`不适用；嵌入 /所属页面 页面`”；共享页面的两个故事分别填写同一路由，不得合并或省略；不得写路由配置文件、框架组件或 middleware。
+
+## Case 14：pending 与 complete 结构
+
+存在产品行为 unknown 时，pending Product Requirement 必须包含“未决事项”；全部确认后重新生成 complete 文档并删除该章节。两种状态都不得生成“默认假设”。
+
+## Case 15：普通执行验证范围
+
+核对普通需求分析只运行 Product Analysis、Requirement Clarification 和 Product Requirement 三个当前产物 validator，不运行 `test-validators.mjs`。
+
+## Case 16：知识库命中与证据边界
+
+使用需要空状态、错误语义和分页约定的需求，并让 `kb-design-assist` 返回可定位、当前有效的设计系统及分页规范。核对：先检索知识库再定向核验仓库；Product Analysis 记录 `executed-hit` 和结构完整的 `KB-FACT-*`；Product Requirement 使用规范化后的产品行为，但不包含 `KB-FACT-*`、知识库路径、搜索过程、Controller/Service/Entity/Response 等实现规范名称。
+
+## Case 17：知识库强制前置、未命中或不可用
+
+分别使用“看似不涉及项目规范”的简单需求、让 `kb-design-assist` 返回无结果，以及让调用失败。核对：简单需求仍先从需求提取检索词并真实调用知识库，不允许 `not-executed`；无结果记录 `executed-no-match`，在有仓库时降级为受限、定向的代码库规范搜索，无仓库时按 unknown 分流；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、探索代码库或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级。不得把“未执行”误写成“未命中”，也不得绕过确认门禁。
+
+## Case 18：知识库与需求冲突
+
+原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供一份与原始错误恢复行为冲突的设计规范。核对：分页沿用原始需求；用户可见行为冲突进入逐题澄清，用户裁决前保持 pending；不得静默采用知识库结果。
+
+## Case 19：Web + Remote 接口范围
+
+需求只写“实现订单列表接口”。核对：必须询问 Web、Remote 或两者；用户确认两者后写 `触发方式：API（Web + Remote）`，不新增接口形态字段，也不在 Product Requirement 中虚构 `/order/list` 或 `/remote/order/list`。
+
+## Case 20：项目资料预扫描
+
+知识库检索结束后提供包含 `ai_workspace/project-how-to`、`code-specification`、`project-business` 的仓库。核对：常规代码搜索前按固定顺序枚举并定向读取三个目录；目录缺失时记录 `not-found` 并继续；资料事实不能替代真实代码证据。
+
+## Case 20A：知识库、代码库与澄清顺序
+
+使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
+
+## Case 21：提示词冻结与来源身份
+
+分别使用 inline 与文件输入生成 Product Analysis。核对：inline 身份只绑定准确正文；file 身份同时绑定规范化真实路径与正文；Clarification 记录相同原始需求身份。完整内容先写入正式 `product-analysis.md`，随即以归一化 target 校验正式文件；首次失败时把同源正式文件保留为未冻结草稿，当前或后续轮次均可继续修正，首次返回 exit 0 后立即冻结并进入澄清。冻结后当前及后续轮次不得再次对正式路径调用写入、格式化、移动或删除工具；Step 5 只读复验。使用相同正文但不同文件路径继续任务时，同源判定必须停止。
+
+## Case 21A：正式文件校验通过后才冻结
+
+构造缺少必填章节或 target 不匹配的 Product Analysis。核对：完整内容先写入正式路径但保持未冻结；validator 非 0 时允许修正正式文件，且不得开始逐题澄清；执行中断后重新进入时，同源文件校验失败仍视为未冻结草稿并继续修正。首次返回 exit 0 后立即冻结并进入澄清，冻结后再次修改必须被流程拒绝。
+
+## Case 22：pending 状态一致性
+
+构造 `pending Clarification + pending Product Requirement`、`pending + complete`、`complete + pending` 三组。核对：第一组仅在显式 `--allow-pending` 时通过；后两组始终失败；最终交付与依赖 skill 不使用 `--allow-pending`。
+
+## Case 23：严格结构与全局唯一性
+
+分别向三个产物 frontmatter 注入 `source_path`，让两个故事复用同一个 AC ID，并把 complete Clarification 的“最终决策”改为“未形成”。核对：额外 frontmatter 字段、重复 AC ID 和未形成最终决策都被 validator 拒绝。

package/skills/analyze-product-requirements/references/kb-integration.md

@@ -0,0 +1,56 @@
+# kb-design-assist 接入契约
+
+每个新 requirement 完成输入识别后，必须先根据需求内容使用当前宿主原生的 skill 加载机制调用第三方 `kb-design-assist`，再预扫描项目资料和探索代码库。即使需求简单、未显式提到项目规范，或模型预判知识库可能没有结果，也不得跳过真实检索。
+
+## 调用输入
+
+先从原始需求提取业务目标、角色、领域对象、关键动作、状态/边界、权限、接口与分页线索，再向 `kb-design-assist` 提供：
+
+- 可识别的项目、产品或知识库范围；无法确定时使用当前项目上下文，不得臆造范围。
+- 已归一化的 `target`、相关故事、业务关键词、领域对象和待查问题。
+- 需要检索的规范类别；只查询与当前需求直接相关的内容，不做无边界扫描。
+- 返回要求：规范结论、文档标题与章节/定位、版本或生效状态、适用范围、置信度、冲突与未定位项。
+
+需求分析优先查询设计系统、交互/文案规范、用户可见状态枚举、共享状态组件、权限可见性、错误语义和分页允许值。Controller、Service、Entity、Response、Remote、Web API 或 `interfaces.md` 等纯实现规范仅用于判断当前问题是否属于下游技术设计，不得据此扩写产品需求。
+
+知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容作为项目资料事实记录，并按知识库、项目资料、代码现状之间的冲突规则处理。
+
+## 结果状态
+
+当前宿主可发现 `kb-design-assist` 时，使用宿主原生的 skill 加载机制调用。知识检索必须记录一种真实状态：
+
+- `executed-hit`：已执行并命中可定位、适用且有效的规范。
+- `executed-no-match`：已执行，但没有与当前问题相关的结果。
+- `unavailable`：`kb-design-assist` 未安装、不可发现、调用失败或无法访问目标知识库。
+
+未执行知识库检索属于流程违规，不得生成 Product Analysis。未执行时不得声称“未命中”；调用失败时不得模拟结果。`executed-no-match` 和 `unavailable` 均不得伪装为 `executed-hit`。
+
+状态为 `executed-no-match` 时直接触发降级：有仓库时执行受限、定向的代码库搜索，只查找与当前问题直接相关的规范或共享定义；没有仓库时按 unknown 分流。`executed-hit` 不触发规范降级，但仍必须探索代码库以核验现状。
+
+状态为 `unavailable` 时不得直接降级。立即停止后续知识查证与 complete 产物生成，向用户说明可观察到的失败原因，并单独询问选择：
+
+1. **修复后重试**：等待用户修复安装、发现、调用或访问问题，再重新调用 `kb-design-assist`；以重试后的真实结果状态继续流程。
+2. **跳过知识库**：仅在用户明确同意后，记录 `- 用户处置：已确认跳过知识库`，再执行与 `executed-no-match` 相同的受限、定向代码库降级；没有仓库时按 unknown 分流。
+
+用户未明确选择前保持阻断，不得自动重试、自动跳过、自动降级或把 `unavailable` 改写为其他状态。正常任务为定位当前实现而进行的代码核验不属于降级，但不得借此绕过该确认门禁或把代码现状冒充项目规范。
+
+## 事实与优先级
+
+每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
+
+产品行为来源优先级：
+
+1. 用户已确认决策。
+2. 原始需求明确内容。
+3. 当前有效且适用于本项目的知识库规范。
+4. 模型推断或通用兜底。
+
+知识库与用户决策、原始需求或另一份有效规范冲突时，保留证据并生成产品澄清问题，用户裁决前不得选边。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
+
+分页允许值遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
+
+## 产物边界
+
+- Product Analysis 的“知识库事实”记录检索状态及 `KB-FACT-*`；代码证据继续使用 `CODE-FACT-*`。
+- Requirement Clarification 可引用 `KB-FACT-*` 解释冲突或推荐理由。
+- Product Requirement 只能保留不含来源标识和技术证据的目标产品行为；不得出现 `KB-FACT-*`、知识库搜索过程、文档路径或实现规范名称。