ewancy requirement-kb-creator / 需求知识库创建
调用原则
当用户目标明确是“建立/创建/生成需求知识库”时使用本 Skill。知识库可以来自禅道，也可以来自本地文件、截图、原型、会议记录或用户直接描述；不要把触发条件限定为禅道。若用户只是要求写 PRD、设计需求、整理方案、查询资料或回答待确认问题，不得自动新建正式知识库。
中文说明：本 Skill 的核心目标是在用户明确要求建立知识库时，把分散的需求事实沉淀成可复用、可追溯的 需求知识库.md，作为后续 PRD、原型、禅道需求变更和验收口径的事实来源。
硬性门禁：新建知识库前必须先查禅道历史需求，除非用户明确说“不查禅道/只按本地资料/跳过禅道”。如果未完成禅道检索、未复用已有有效检索记录、也没有记录检索失败原因，不得生成知识库文件。
中文说明：即使用户只给一句口头需求，也不能直接建立“轻量知识库”并写“禅道暂无”。正确做法是先按功能点关键词查禅道；查不到写“已查未命中”，查不了写“检索失败原因”，这样后续 PRD 才能知道历史口径是否可靠。
适用输入：
- 用户口令：
帮我建立知识库、创建知识库、生成需求知识库、基于这些文档建立知识库、把这个需求沉淀成知识库。 - 禅道来源：
taskID=41603、storyID=7945、bugID、禅道任务/需求/缺陷 URL。 - 本地来源：Markdown、Word、PDF、Excel、CSV、截图、HTML 原型、已有 PRD、会议纪要、用户粘贴的需求规则。
- 混合来源：禅道 + 本地补充文档/截图/原型一起建库。
不适用输入：
- 已有知识库，需要同步新规则：使用
$requirement-kb-updater。 - 从知识库写正式 PRD：使用
$requirement-prd-writer。 - 制作 HTML 交互原型：使用
$html-interactive-prototype。
新建授权门禁
中文说明：正式知识库只能在用户明确要求建立/创建/生成/沉淀知识库时落盘。PRD 编写前置、需求设计、问题确认、方案确认、禅道查询等流程不能自动新建正式知识库。
允许新建正式知识库的表达包括：
建立知识库、创建知识库、生成需求知识库、沉淀知识库。把这些资料整理成 xxx需求知识库.md。- 用户在你询问“是否建立知识库”后明确回复“确认/可以/建立”。
未授权时的处理：
- 可以读取资料、查询禅道、整理“知识库草稿/拟沉淀规则/来源摘要”。
- 如果需要落文件，只能写到草稿文件，文件名必须包含
待确认或草稿，不得命名为正式...需求知识库.md。 - 不得把草稿当作 PRD 的正式关联知识库；PRD 中只能说明“知识库待建立/用户尚未授权建立”。
推荐口令
$requirement-kb-creator 帮我建立知识库，资料在 ./xxx需求/帮我建立知识库，基于 taskID=41603 和这个本地 PRD创建知识库：读取这些截图和会议纪要，整理成 xxx需求知识库.md从禅道 storyID=xxx 生成 xxx 的需求知识库.md
工作流程
识别来源与范围
- 先判断来源类型：禅道、本地文件、用户粘贴文本，或混合来源。
- 如果用户没有给路径或 ID，优先在当前需求目录查找相关 PRD、
*需求*.md、*知识库*.md、截图、原型文件；只有无法判断功能点或候选过多时才询问。 - 确认本轮用户有明确“建立/创建/生成/沉淀知识库”的写入授权；没有授权时只能输出草稿或建议，不生成正式知识库。
- 明确知识库名称、功能点归属和输出目录；默认放到需求专属目录。
禅道历史需求检索（建库默认必做，除非用户明确不查禅道）
- 创建新知识库时，即使用户只给了功能点名称或口头需求，也要先按当前项目约定检查禅道历史需求；不要直接写“禅道任务/需求/缺陷 ID：暂无”。
- 如果是其他技能（例如
$requirement-prd-writer）为了写 PRD 而需要知识库，不得自动触发正式建库；必须先取得用户明确“建立/创建知识库”的授权。已获授权后才完整执行本步骤。 - 先检查当前工作区是否已有同功能点知识库、PRD 或
禅道历史需求检索记录/关联任务/记录/需求来源等章节；若其中已经记录过相同关键词、产品、检索日期和命中 story/task/bug ID，本轮可复用记录，不必重复全量查询。 - 已有记录不足时，必须实际使用
zentaoCLI/MCP 做检索；先运行zentao whoami验证登录态，再用功能点名、模块名、同义词、渠道/端名称、用户本轮关键词检索历史需求。常用方式：zentao stories list --product <productID> --page <n> --limit <n> --json分页后本地按标题关键词过滤；必要时补查bugs、tasks或用户指定项目/执行。 - 若不确定产品 ID，先用
zentao products list --json查询产品列表，并结合用户上下文、当前工作区、历史知识库中的产品/模块记录确定候选产品；仍无法判断时，按最可能的 1-3 个候选产品检索并把选择依据写入检索摘要。 - 检索关键词至少包含：功能点主名称、用户原始需求关键词、常见同义词/简称；例如“五福合成活动”还应尝试“五福”“合成”“卡片”“卡片类型”等。
- 默认产品按工作区说明或用户上下文确定；例如 AI客服/AI伴侣需求默认优先查
AI伴侣 productID=11，用户指定其他产品时以用户为准。 - 命中结果要区分“直接相关”和“间接相关”：直接相关必须写入
需求来源或关联任务/记录；间接相关可写为参考，不要把未确认的历史规则强行合并为本次需求。 - 命中疑似相关需求时，必须读取详情后再决定是否沉淀规则；优先用
zentao story get --id <id> --json、zentao task get --id <id> --json、zentao bug get --id <id> --json。 - 每次检索都要在知识库中记录可复用的检索摘要：检索日期、产品/项目、检索命令或检索方式、关键词、命中 ID 与标题、已展开读取详情的 ID、未展开原因。中文说明：这样后续同功能点建库或写 PRD 时可以先复用已查记录，避免重复拉取禅道全量列表。
- 若禅道不可用、未登录、无权限或网络失败，知识库不得写“无关联需求”；应写“禅道检索失败/未完成”，并记录失败原因、已尝试命令和对完整性的影响。除非用户确认继续，否则检索失败时不要生成正式知识库；如用户要求先继续，只能生成标记为“待补禅道检索”的临时知识库。
读取禅道材料（如有）
- 优先使用
zentaoCLI/MCP：zentao task get --id <id> --json、zentao story get --id <id> --json或对应 bug 命令。 - 如果未登录，使用或询问
ZENTAO_URL、ZENTAO_ACCOUNT、ZENTAO_PASSWORD。 - 保存原始 JSON 到
/tmp，不要把账号密码、token、cookie 写入任何产物。 - 提取主任务/需求、子任务、
desc、spec、verify、customDemandSpec、selfTest、备注/动态。 - 禅道来源必须结合图片/附件处理：如果
desc、spec、verify、customDemandSpec、备注/动态中包含<img>、文件链接、fileID、{123.png}或原型链接，必须下载或打开附件并识别图片内容；不能只读取文字后把图片承载的信息写成待确认。 - 可用
scripts/extract_zentao_assets.py提取图片 URL、fileID、{123.png}图片占位；没有脚本时，用正则从 HTML 中提取m=file&f=read、fileID=、img src等链接，并保存附件到需求目录或/tmp后识别。 - 对禅道截图要识别页面入口、菜单层级、筛选条件、表格字段、按钮、弹窗、红框/箭头标注、字段说明、验收提示和异常态；把确定内容沉淀到正文和验收标准，把无法识别或图片缺失的内容才写入待确认。
- 如果附件无法下载、无权限访问或图片损坏，在知识库的“图片与附件识别摘要”和“待确认问题”中说明具体 story/task/bug ID、fileID、失败原因和缺失影响。
- 优先使用
读取本地材料（如有）
- Markdown/文本：直接读取并抽取背景、目标、规则、验收、待确认点。
- Word/PDF/Excel/CSV：使用可用工具提取文字、表格和图片；保留来源文件名与关键页/表信息。
- HTML 原型：读取页面文案、控件、交互脚本和状态分支，不要只总结视觉。
- 截图/图片：识别图片中的文字、表格、编号、箭头、UI 状态、字段说明；不确定内容写入
待确认问题。
合并与去重
- 按“事实来源优先级”合并：用户本轮明确口径 > 最新本地文档/PRD > 禅道最新描述/备注 > 历史材料。
- 同一规则多处出现时保留一条清晰规则，并在“需求来源”或“关联任务/记录”中保留来源线索。
- 冲突内容不要自行裁决；列入
待确认问题，注明冲突来源。
生成知识库（仅限已授权新建）
- 参考
references/knowledge-base-template.md。 - 默认文件名：
<需求名>需求知识库.md或<需求名>的需求知识库.md。 - 默认不要写
数据与接口/接口与数据字段章节，除非用户明确要求。 - 每条关键规则要可追溯到来源；无来源但来自用户口述时写“用户本轮补充”。
需求来源中必须准确写禅道历史检索结果：有命中写 ID；未命中写“已按 <关键词> 检索，未命中直接相关需求”；检索失败写失败原因，不要写成“无”。关联任务/记录中保留可复用检索摘要，便于后续判断哪些禅道历史已查过；建议表格包含检索日期、产品/项目、关键词、命中结果、已读取详情、处理结论。- 如果用户明确要求跳过禅道，
需求来源和关联任务/记录必须写明“用户确认不查禅道”，不能留空。
- 参考
校验
- 文件存在且非空。
- 不包含密码、token、cookie、cookie header、临时登录态。
- 章节编号连续。
- 用户给出的关键材料都已覆盖；截图/附件识别摘要覆盖所有关键图片。
- 新建知识库必须能回答“是否查过禅道历史需求”：已查且命中、已查未命中、复用既有检索记录、或检索失败原因四选一；不能留空或默认暂无。
- 新建知识库必须能回答“查了哪些关键词、哪些产品/项目、是否读取详情、为什么判定相关/不相关”；缺少这些检索摘要时不得交付。
- 如果禅道检索失败但用户未确认继续，停止建库并先反馈失败原因；不要为了完成任务而生成来源不完整的知识库。
- 如果来源包含禅道任务/需求/缺陷，必须校验禅道正文中的图片/附件是否已提取、下载/打开、识别并落入知识库；不能在未处理附件的情况下声称“基于禅道建立完成”。
- 关键规则在
核心需求概述或对应业务章节中有落点，并在验收标准中有可测试项。
来源处理细则
- 只有禅道 ID/URL：读取禅道并建库；必须同步处理禅道图片/附件/原型链接，图片里能确认的字段和规则要写入正文与验收标准；无法读取附件时说明缺失附件并列入待确认。
- 只有本地文件/目录：扫描用户指定路径或当前需求目录，同时按功能点关键词检查禅道历史需求；用户明确说“不查禅道/只按本地文件”时才跳过禅道检索，并在来源中记录该口径。
- 禅道 + 本地资料：先读禅道，再读本地补充；本地新口径与禅道冲突时以用户最新明确说明为准，否则列待确认。
- 只有用户口述：只有用户明确要求建立知识库时，才可以建立轻量知识库；否则只输出拟沉淀规则和待确认问题。已授权建库时仍要按功能点关键词检查禅道历史需求；来源中同时标注“用户本轮描述”和“禅道历史检索结果”，并把不确定边界写入待确认。
输出约定
最终回复只汇报：
- 生成的知识库绝对路径；如果未获授权，只说明未生成正式知识库，并给出草稿/拟沉淀摘要。
- 使用的来源类型和关键来源文件/ID。
- 识别图片/附件数量。
- 待确认点数量。
- 校验结果：章节编号是否连续、是否无敏感信息、是否默认未加入接口章节。