Zentao Requirement Submit

禅道需求提交流程

使用原则

• 优先使用 zentao CLI/MCP；如果 CLI 能力不足，再使用禅道 REST API 或传统表单接口 curl 补齐。
• 不使用 Playwright，除非用户明确要求浏览器自动化；提交禅道需求默认走 CLI/API/表单。
• 不在最终回复、Markdown、日志摘要中暴露账号、密码、Token、Cookie。
• 提交前先查重：同项目、同版本、同模块下如已有明显同名/同主题需求，优先更新已有需求，不重复创建。
• 所有写入禅道的内容必须来自用户给定内容、本地需求文档、知识库或已确认材料；不要臆造未确认的业务规则。
• 先用 API/CLI 完成“可结构化写入”的部分，再用禅道表单补齐附件、图片内嵌、指派和执行关联；不要假设 CLI 一次创建能写入所有字段。

触发口令

用户出现以下表达时使用本技能：

• “提交到禅道”“把需求提到禅道”“创建禅道需求”
• “项目 xxx，版本 xxx，需求来源 xxx，指派给 xxx”
• “需求文档作为附件上传”“把 .md 需求说明上传到禅道”
• “更新禅道需求注意事项/验收标准/需求描述”
• “把这份需求文档提交到禅道需求”

输入收集

执行前从用户消息和当前目录收集以下信息；缺失但可推断时直接推断并在最终回复说明：

• 需求正文：优先使用本地 PRD/需求说明 .md；没有文件时使用用户消息整理。
• 禅道对象：产品/项目名称、版本/执行名称、模块、需求来源、指派人。
• 附件：默认上传最新需求说明 .md 源文件；如当前功能点目录存在配套 .html/.htm 交互原型，默认作为普通 HTML 附件直接上传，不压缩成 ZIP；如 PRD 有页面截图，默认要求禅道正文直接显示图片，需要上传图片附件并使用禅道附件 webPath 写入 <img>；知识库、PDF 等其他补充材料不上传，除非用户明确要求。提交/变更后需清理旧版、重复或正文不再引用的附件。
• 注意事项模板：若用户未另给模板，按本技能的标准模板填写。
• 目标行为：创建新需求、更新已有需求、补充附件、关联版本/执行、更新注意事项等。

标准字段映射

• 需求标题：用需求文档标题或用户明确标题；保持短、可搜索。
• 所属产品/项目：按用户名称查询 ID，例如“平台部”。
• 版本：通常对应禅道执行/迭代，而不一定是产品计划；按执行名称或版本号查询，例如 V2.15.0（0513）。
• 需求来源：客户=source=customer；内部=partner；运维=operation。
• 模块：例如“版本需求”需要映射为产品模块 ID。
• 指派给：优先使用账号，如“陈远”通常为 cheny；必须通过用户列表或页面选项确认。
• 需求描述：写入 spec。
• 注意事项：写入 verify。
• 需求背景：如禅道有 customDemandSpec 字段，可写入背景；没有明确内容时留空。

需求正文格式要求

提交到禅道的 spec 必须保持 PRD 的阅读结构，不能为了省事把整份 Markdown 包在 <pre> 中。

中文说明：禅道详情页面向产品、研发、测试阅读，表格、标题和列表需要按原结构展示；尤其“改动范围”“验收标准”“版本记录”等 Markdown 表格必须转成真实 HTML 表格。

• Markdown 标题转为 <h1>/<h2>/<h3>，保持章节层级。
• Markdown 列表转为 <ul><li> 或有序列表；不要把列表符号作为纯文本展示。
• Markdown 表格转为 <table><thead><tbody>；表头用 <th>，内容用 <td>，保留单元格文本和行内代码。
• 行内代码、字段名、枚举值转为 <code>，方便识别配置项和状态值。
• 注意事项 verify 可用段落展示，但也不能用整段 <pre> 包裹。
• 如果提交后发现 spec 里仍有 <pre> 或 Markdown 表格原文 | --- |，必须立即用 zentao-story-change 技能重新同步格式。

图片转 HTML 规则

中文说明：PRD 本地评审版可以使用 Markdown 图片语法；提交禅道时默认按“禅道正文直接显示图片”处理：上传图片附件，读取禅道附件 webPath，并写入 <img>。图片附件会出现在附件列表中，这是当前禅道正文显示图片的必要条件。

• 默认提交时，如果 PRD 中存在页面截图/流程图且图片文件可访问，则上传图片附件并在禅道正文直接显示。
• 图片正文显示流程：先上传页面截图/流程图等图片附件，再从 zentao story get --id <id> --json 的 files[].webPath 获取直连地址。
• 将 Markdown 图片 ![说明](本地路径.png) 转成 HTML，例如：<p><img src="https://<禅道域名><webPath>" alt="说明" style="max-width:100%;" /></p>。
• 不要用 <a><img /></a> 包裹正文图片：当前禅道编辑器会把图片外层链接强制改成 /data/upload/...，该地址可能因 application/octet-stream 导致点击下载。如需查看大图，在图片下方提供 m=file&f=download&fileID=<fileID>&mouse=left 预览链接。
• 如果当前禅道接口无法在提交前拿到可访问图片地址，先上传图片附件，再二次回写正文；只有确实无法取得 webPath 时，才降级为“查看禅道附件 <图片文件名>”，并在最终回复说明。
• 禁止把 /Users/...、C:\...、file://...、localhost、127.0.0.1 等本地路径写入禅道正文。

附件清理规则

中文说明：禅道正文需要显示图片时，图片必须作为附件存在；但旧版需求源文件、旧截图、重复上传的图片、已不再被正文引用的附件会干扰评审，提交或变更后必须清理。

• 提交前先定义本次应保留附件清单：最新 .md 需求源文件、配套 .html/.htm 交互原型附件、正文 <img> 正在引用的图片、用户明确要求保留的 PDF/其他补充附件。
• 默认删除旧版同名/同类型附件：旧 需求说明源文件-vX、旧截图 *-vX、重复上传但未被正文引用的图片、历史调试附件。
• 不删除与本次需求无关且无法判断用途的附件；如无法确认是否可删，先向用户确认。
• 删除附件必须在最终正文回写后执行，避免误删正文仍在引用的图片。
• 删除方式优先使用禅道文件删除接口：/index.php?m=file&f=delete&fileID=<id>&confirm=yes；删除后重新读取 story，确认附件列表只保留应保留项。
• 默认正文显示图片；被正文 <img src=...> 或“点击查看大图”链接引用的图片附件必须保留，不能为了附件列表简洁删除正在展示的图片。
• 最终回复需说明附件清理结果：保留了哪些类型附件，删除了哪些旧版/重复附件；如无权限删除，说明未完成原因。

需求文档附件引用规则

写入禅道的 spec 不允许出现本机文件路径或仅本机可访问的原型地址。

中文说明：本地 PRD 可以保存绝对路径方便当前电脑打开，但提交到禅道后，研发/测试无法访问 /Users/...、C:\...、file://... 这类路径。因此禅道正文中统一写“查看禅道附件”。附件默认上传需求说明 .md 源文件；如有配套 HTML 原型，直接上传 .html/.htm 原文件，不再打包成 ZIP。

• 提交前确认需求说明 .md 文件是最新版本，并把它作为禅道附件上传；如已有旧版 .md 附件，本次提交完成后清理旧版，只保留最新源文件。
• 禅道正文中的文档引用写成：需求文档：查看禅道附件 <需求说明>.md。
• 如有配套 HTML 原型，禅道正文中的原型引用写成：交互原型：查看禅道附件 <原型文件名>.html；不要写本机绝对路径、file:// 或本地 HTTP 地址。
• 如果正文有“交互流程图”“客户端原型”“后台原型”等本地 HTML 路径说明，提交前默认改成查看禅道附件中的 .html/.htm 原型；本地图片路径仍按图片规则上传并回写 <img> 或改成查看附件。
• 禁止把 HTML 原型压缩成 ZIP 上传；除非用户明确要求 zip，否则必须直接上传 .html/.htm 文件。
• 提交到禅道前清理 spec 中的本地路径模式：/Users/、/home/、C:\、file://、localhost、127.0.0.1。
• 如果提交后发现禅道正文仍包含本机路径，必须立即变更需求正文并重新上传最新 .md 附件。

注意事项标准模板

提交或更新需求时，禅道“注意事项”必须结合需求按以下模板填写：

【影响范围】是否会影响到需求中没提到的关联页面，或旧数据和逻辑
【需求边界】本次需求改动边界说明，仅改动xxx部分，xxx不涉及
【是否存在新旧版本兼容问题】是、否
【是否需要性能测试】是、否
【是否需要脚本】是、否

填写要求：

• 影响范围：写清会影响的后台配置页、前端页面、关联入口、历史数据和旧逻辑。
• 需求边界：写清“仅改动哪些部分”和“不涉及哪些部分”。
• 兼容问题：只要影响旧配置、历史数据、旧展示逻辑或接口字段，就填“是”并说明兼容点；否则填“否”。
• 性能测试：涉及大数据量、列表查询、批处理、高频接口、视频加载性能时填“是”；纯显隐/配置校验通常填“否”。
• 脚本：涉及数据迁移、字段初始化、历史数据修复时填“是”；仅新增可选配置通常填“否”。

提交流程

1. 校验登录与本地文件

• 运行 zentao whoami 确认当前账号。
• 用 ls/rg --files 确认 PRD、知识库、需求说明 .md、配套 .html/.htm 原型和补充附件路径存在。
• 默认查找当前功能点目录下与本需求配套的 .html/.htm 原型文件；如存在则直接作为禅道附件上传，不压缩、不改名为 zip。
• 如 PRD 中包含本地原型路径，提交禅道前替换为“交互原型：查看禅道附件 <原型文件名>.html”；如是图片路径则按图片附件规则处理。
• 确认将要上传的 .md 和 .html/.htm 附件文件名与正文引用一致。

1.1 生成禅道提交包

中文说明：提交前先在本地生成一个“禅道提交包”，避免边提交边改正文导致图片、附件和正文不一致。

• 在功能点目录下生成 dist/zentao_submit/，放入：
  • 转换后的 spec.html。
  • 转换后的 verify.html。
  • PRD 源文件 .md（作为默认禅道附件）。
  • 配套 .html/.htm 交互原型文件（作为默认禅道附件，直接上传原文件，不压缩成 ZIP）。
  • PRD 中用于正文展示的页面截图/流程图图片附件；其他补充附件仍需用户明确要求。
• Markdown PRD 转 HTML 时：
  • 标题、列表、表格必须转为真实 HTML。
  • 本地文档引用统一写“查看禅道附件 <需求说明>.md”；本地 HTML 原型引用统一写“查看禅道附件 <原型文件名>.html”，不再引用或生成原型 ZIP。
  • 图片默认作为禅道正文展示资源上传；先临时写“查看禅道附件 <图片文件名>”，上传后用 webPath 直连地址回写 <img>。
• 提交前本地自检 spec.html：不能包含 /Users/、/home/、C:\、file://、localhost、127.0.0.1、| --- |、<pre>。

2. 发现禅道 ID

• 用 zentao products list --json 查询产品 ID。
• 用 zentao projects list --json 查询项目 ID。
• 用 zentao executions list --json 查询版本/执行 ID。
• 用产品模块页面或禅道页面 HTML 确认模块 ID；如果 CLI 不提供模块列表，可读取创建/编辑页的 <select name='module'>。
• 用 zentao users list --json 或编辑页选项确认指派账号。

3. 查重

• 查询目标产品/执行下的已有需求列表。
• 标题高度相似、同一模块、同一版本、同一需求主题时，不新建；改为更新已有 story。
• 查重结果不确定时，保守创建前先向用户说明或选择最明显的目标。

4. 创建或更新需求

优先用 REST/CLI 创建 story：

• 产品 ID、模块 ID、标题、来源、类别、优先级、需求描述、注意事项都要写入。
• 如果接口提示“类别不能为空”，补充 category=feature 后再创建。
• 需求描述写入前必须先把 Markdown 转成 HTML；标题、列表、表格和图片都必须是真实 HTML 结构，表格使用 <table>，图片使用 <img> 或“查看禅道附件”，不要把 PRD 作为纯文本或 <pre> 写入。
• 写入 spec 前必须清理本地原型路径；禅道正文只保留“查看禅道附件”的 .md 文档引用、.html/.htm 原型附件引用，以及通过 webPath 写入的图片 <img>。
• 创建后如果 story 是草稿或未指派，用编辑表单补齐 status=active、assignedTo=<account>、keywords 等。
• 禅道接口不支持某字段时，读取对应编辑页，用传统表单接口提交。

表单提交要点：

• 读取编辑或变更页，提取 uid/kuid、lastEditedDate、现有 spec。
• 提交时加 Referer；缺少 Referer 可能只返回页面而不保存。
• 读取禅道传统页面时优先用登录页 /index.php?m=user&f=login 获取会话；部分部署没有 /user-login.html。
• 请求编辑、变更、关联页时带 X-Requested-With: XMLHttpRequest，否则可能跳到首页壳页面或 open= 跳转，拿不到真实表单。
• 如果只更新“注意事项”，保留现有 spec，只替换 verify。
• 保存成功通常返回 保存成功、parent.location 或跳转到 story view。
• 创建后若状态仍是草稿，可调用 story review/assign 接口或表单：先评审通过使 status=active，再指派目标账号。

5. 上传附件

• 默认上传需求说明 .md 源文件作为需求附件。
• 默认上传当前功能点目录下与本需求配套的 .html/.htm 交互原型，必须直接上传 HTML 原文件，不压缩成 ZIP。若存在多个 HTML，优先上传文件名与需求/原型语义最匹配的文件；无法判断时先向用户确认。
• 截图、流程图、PDF、知识库等补充材料只有在用户明确要求上传时，才作为独立附件上传；但正文需要显示的截图/流程图仍按图片内嵌规则上传。
• 优先在 story 变更页或编辑页上传附件，使用字段：labels[] 和 files[]。
• 上传后用 zentao story get --id <id> --json 核对 files 不为空，确认附件标题和扩展名正确；如存在旧版或重复附件，按“附件清理规则”删除。
• 如果 /api.php/v1/files 上传返回通用 error，不要反复尝试同一接口；改用 story 变更页 multipart/form-data 上传，字段为 labels[] 与 files[]。
• 上传 PRD 源文件时，禅道可能把 .md 识别为 .txt，只要附件内容和标题正确即可在最终说明中提示。上传 HTML 原型时需确认附件标题保留 .html/.htm 文件名；如禅道识别扩展名异常但文件标题正确，最终回复中说明。

5.1 图片内嵌回写

中文说明：提交/变更需求默认要求禅道正文直接显示图片。先上传图片附件，再用禅道文件 webPath 直连地址回写到 spec，避免本地路径、临时地址或下载链接影响预览。

• 上传截图后，从 zentao story get --id <id> --json 的 files 中取得图片 webPath。
• 将正文里的“查看禅道附件 <图片文件名>”替换为：
  • <img src="https://<禅道域名><webPath>" alt="<说明>" style="max-width:100%;" />
• 如果需要查看大图，不要让 <a> 直接包裹 <img>；改为在图片下方提供“点击查看大图”链接，链接使用 https://<禅道域名>/index.php?m=file&f=download&fileID=<fileID>&mouse=left。
• 优先通过 story 变更页表单回写含 <img> 的 spec；部分 REST 更新可能清洗或不保留图片标签。
• 回写后再次读取 story，确认 spec 中存在 <img>，且不包含 zentaosid、本机路径或临时地址；确认正文引用的图片附件仍保留，未引用的旧截图已清理。

6. 关联项目/版本/执行

• 进入目标执行的关联需求页：execution linkStory。
• 找到目标 story 的 stories[] checkbox 和 products[storyID] hidden 字段。
• POST stories[]=<storyID> 和 products[<storyID>]=<productID> 到 m=execution&f=linkStory&execution=<executionID>。
• 复核 story 的 executions 包含目标执行 ID，动作记录包含 linked2execution。
• 如果用户给的是“版本号”，优先匹配进行中的执行/迭代；产品计划为空时不要阻塞，可直接关联执行。

7. 最终复核

必须复核以下项后再回复用户：

• id/title/status 正确，状态不是草稿，除非用户明确要求草稿。
• product/module/source/category/pri 符合用户要求。
• assignedTo 为目标账号。
• executions 包含目标版本/执行。
• files 默认只保留本次最新需求说明 .md 附件、配套 .html/.htm 原型附件，以及正文正在引用的最新图片附件；旧版、重复、未引用附件需删除。
• verify 已按注意事项标准模板填写。
• spec 格式正确：标题/列表/表格/图片为 HTML 结构，Markdown 表格没有退化为纯文本，Markdown 图片没有保留本地路径。
• spec 不包含本机路径或临时服务地址，例如 /Users/、file://、localhost、127.0.0.1；本地文档引用应指向 .md 禅道附件，本地 HTML 原型引用应指向 .html/.htm 禅道附件。
• 复核 spec 中 <img> 数量与核心截图数量一致，图片显示使用禅道附件 webPath；查看大图链接必须使用 mouse=left 预览地址；复核正文中不应存在 <a><img> 结构，避免禅道改写成 /data/upload 下载链接。
• 附件列表已清理：无旧版重复需求源文件、无旧版重复 HTML 原型、无未引用旧截图；正文显示图片所依赖的图片附件和本次配套 HTML 原型附件除外。
• 最终回复只给结果、链接、关键字段、附件清理结果和未完成项；不要输出密码、Token、Cookie。

常见问题处理

• CLI 创建后字段未生效：用编辑页表单补齐指派、状态、关键词等字段。

• 附件上传失败：优先确认 .md 文件存在且文件名正确；如接口上传失败，改从变更页上传。

• 附件列表有旧文件/重复文件：先确认正文当前引用的 fileID/webPath，再用 m=file&f=delete&fileID=<id>&confirm=yes 删除未引用的旧版附件，删除后重新读取 story 复核。

• 关联执行 API 空响应：改用 execution linkStory 页面表单提交。

• 传统页面拿到首页而不是表单：登录和读取页面时补 X-Requested-With: XMLHttpRequest，并检查响应标题是否为“编辑/变更/关联需求”，不是则不要提交。

• 创建后仍是草稿：执行评审通过或变更页保存，使状态变为 active，再执行指派和版本关联。

• REST 回写图片不生效：改用 story 变更页提交 spec，保存后用 zentao story get 校验 <img> 是否存在。

• 注意事项被覆盖：重新读取最新变更页，保留最新 spec，只替换 verify。

• 正文格式退化为纯文本：不要接受 <pre> 包裹的 PRD；用 Markdown-to-HTML 转换后重新提交，复核 <table> 存在且 | --- | 不存在。

• 禅道正文出现本地原型路径：把路径替换为“查看禅道附件 <原型文件名>.html”，重新提交正文并上传最新 .md 与配套 .html/.htm 附件。

• 需求已激活后编辑页没有文件控件：使用“变更”页上传附件。

• HTML 原型被压缩成 ZIP：这是错误提交方式；删除错误 ZIP 附件，直接上传 .html/.htm 原文件，并把正文引用改成“查看禅道附件 <原型文件名>.html”。

• 版本名称像日期或版本号：优先匹配执行/迭代，不要误填到过期产品计划。

• 已验证：当前禅道正文会清洗 data:image/png;base64，因此不能通过 base64 内嵌来规避图片附件；只要正文要显示图片，就需要图片存在于禅道可访问文件中（通常会出现在附件列表）。

• 已验证：background-size: contain 可能被禅道清洗，背景图方式容易裁切；如要完整缩略显示，优先使用 <img width="520" style="width:520px;height:auto;" /> 等比例缩略图，并在下方提供 mouse=left 预览链接。