`/``/``，保持章节层级。
- Markdown 列表转为 `- ` 或有序列表；不要把列表符号作为纯文本展示。
- Markdown 表格转为 `
`；表头用 ``，内容用 ` `，保留单元格文本和行内代码。
- 行内代码、字段名、枚举值转为 ``，方便识别配置项和状态值。
- 注意事项 `verify` 可用段落展示，但也不能用整段 `` 包裹。
- 如果提交后发现 `spec` 里仍有 `` 或 Markdown 表格原文 `| --- |`，必须立即用 `zentao-story-change` 技能重新同步格式。
### 图片转 HTML 规则
中文说明：PRD 本地评审版可以使用 Markdown 图片语法；提交禅道时默认按“禅道正文直接显示图片”处理：上传图片附件，读取禅道附件 `webPath`，并写入 `![]()
`。图片附件会出现在附件列表中，这是当前禅道正文显示图片的必要条件。
- 默认提交时，如果 PRD 中存在页面截图/流程图且图片文件可访问，则上传图片附件并在禅道正文直接显示。
- 图片正文显示流程：先上传页面截图/流程图等图片附件，再从 `zentao story get --id --json` 的 `files[].webPath` 获取直连地址。
- 将 Markdown 图片 `` 转成 HTML，例如：`
`。
- 不要用 `![]()
` 包裹正文图片：当前禅道编辑器会把图片外层链接强制改成 `/data/upload/...`，该地址可能因 `application/octet-stream` 导致点击下载。如需查看大图，在图片下方提供 `m=file&f=download&fileID=&mouse=left` 预览链接。
- 如果当前禅道接口无法在提交前拿到可访问图片地址，先上传图片附件，再二次回写正文；只有确实无法取得 `webPath` 时，才降级为“查看禅道附件 <图片文件名>”，并在最终回复说明。
- 禁止把 `/Users/...`、`C:\...`、`file://...`、`localhost`、`127.0.0.1` 等本地路径写入禅道正文。
## 附件清理规则
中文说明：禅道正文需要显示图片时，图片必须作为附件存在；但旧版需求源文件、旧截图、重复上传的图片、已不再被正文引用的附件会干扰评审，提交或变更后必须清理。
- 提交前先定义本次应保留附件清单：最新 `.md` 需求源文件、配套 `.html/.htm` 交互原型附件、正文 `![]()
` 正在引用的图片、用户明确要求保留的 PDF/其他补充附件。
- 默认删除旧版同名/同类型附件：旧 `需求说明源文件-vX`、旧截图 `*-vX`、重复上传但未被正文引用的图片、历史调试附件。
- 不删除与本次需求无关且无法判断用途的附件；如无法确认是否可删，先向用户确认。
- 删除附件必须在最终正文回写后执行，避免误删正文仍在引用的图片。
- 删除方式优先使用禅道文件删除接口：`/index.php?m=file&f=delete&fileID=&confirm=yes`；删除后重新读取 story，确认附件列表只保留应保留项。
- 默认正文显示图片；被正文 `
` 或“点击查看大图”链接引用的图片附件必须保留，不能为了附件列表简洁删除正在展示的图片。
- 最终回复需说明附件清理结果：保留了哪些类型附件，删除了哪些旧版/重复附件；如无权限删除，说明未完成原因。
## 需求文档附件引用规则
写入禅道的 `spec` 不允许出现本机文件路径或仅本机可访问的原型地址。
中文说明：本地 PRD 可以保存绝对路径方便当前电脑打开，但提交到禅道后，研发/测试无法访问 `/Users/...`、`C:\...`、`file://...` 这类路径。因此禅道正文中统一写“查看禅道附件”。附件默认上传需求说明 `.md` 源文件；如有配套 HTML 原型，直接上传 `.html/.htm` 原文件，不再打包成 ZIP。
- 提交前确认需求说明 `.md` 文件是最新版本，并把它作为禅道附件上传；如已有旧版 `.md` 附件，本次提交完成后清理旧版，只保留最新源文件。
- 禅道正文中的文档引用写成：`需求文档：查看禅道附件 <需求说明>.md`。
- 如有配套 HTML 原型，禅道正文中的原型引用写成：`交互原型：查看禅道附件 <原型文件名>.html`；不要写本机绝对路径、`file://` 或本地 HTTP 地址。
- 如果正文有“交互流程图”“客户端原型”“后台原型”等本地 HTML 路径说明，提交前默认改成查看禅道附件中的 `.html/.htm` 原型；本地图片路径仍按图片规则上传并回写 `![]()
` 或改成查看附件。
- 禁止把 HTML 原型压缩成 ZIP 上传；除非用户明确要求 zip，否则必须直接上传 `.html/.htm` 文件。
- 提交到禅道前清理 `spec` 中的本地路径模式：`/Users/`、`/home/`、`C:\`、`file://`、`localhost`、`127.0.0.1`。
- 如果提交后发现禅道正文仍包含本机路径，必须立即变更需求正文并重新上传最新 `.md` 附件。
## 注意事项标准模板
提交或更新需求时，禅道“注意事项”必须结合需求按以下模板填写：
```text
【影响范围】是否会影响到需求中没提到的关联页面，或旧数据和逻辑
【需求边界】本次需求改动边界说明，仅改动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` 直连地址回写 `![]()
`。
- 提交前本地自检 `spec.html`：不能包含 `/Users/`、`/home/`、`C:\`、`file://`、`localhost`、`127.0.0.1`、`| --- |`、``。
### 2. 发现禅道 ID
- 用 `zentao products list --json` 查询产品 ID。
- 用 `zentao projects list --json` 查询项目 ID。
- 用 `zentao executions list --json` 查询版本/执行 ID。
- 用产品模块页面或禅道页面 HTML 确认模块 ID；如果 CLI 不提供模块列表，可读取创建/编辑页的 `
`，保持章节层级。
- Markdown 列表转为 `- ` 或有序列表；不要把列表符号作为纯文本展示。
- Markdown 表格转为 `
`；表头用 ``，内容用 ` `，保留单元格文本和行内代码。
- 行内代码、字段名、枚举值转为 ``，方便识别配置项和状态值。
- 注意事项 `verify` 可用段落展示，但也不能用整段 `` 包裹。
- 如果提交后发现 `spec` 里仍有 `` 或 Markdown 表格原文 `| --- |`，必须立即用 `zentao-story-change` 技能重新同步格式。
### 图片转 HTML 规则
中文说明：PRD 本地评审版可以使用 Markdown 图片语法；提交禅道时默认按“禅道正文直接显示图片”处理：上传图片附件，读取禅道附件 `webPath`，并写入 `![]()
`。图片附件会出现在附件列表中，这是当前禅道正文显示图片的必要条件。
- 默认提交时，如果 PRD 中存在页面截图/流程图且图片文件可访问，则上传图片附件并在禅道正文直接显示。
- 图片正文显示流程：先上传页面截图/流程图等图片附件，再从 `zentao story get --id --json` 的 `files[].webPath` 获取直连地址。
- 将 Markdown 图片 `` 转成 HTML，例如：`
`。
- 不要用 `![]()
` 包裹正文图片：当前禅道编辑器会把图片外层链接强制改成 `/data/upload/...`，该地址可能因 `application/octet-stream` 导致点击下载。如需查看大图，在图片下方提供 `m=file&f=download&fileID=&mouse=left` 预览链接。
- 如果当前禅道接口无法在提交前拿到可访问图片地址，先上传图片附件，再二次回写正文；只有确实无法取得 `webPath` 时，才降级为“查看禅道附件 <图片文件名>”，并在最终回复说明。
- 禁止把 `/Users/...`、`C:\...`、`file://...`、`localhost`、`127.0.0.1` 等本地路径写入禅道正文。
## 附件清理规则
中文说明：禅道正文需要显示图片时，图片必须作为附件存在；但旧版需求源文件、旧截图、重复上传的图片、已不再被正文引用的附件会干扰评审，提交或变更后必须清理。
- 提交前先定义本次应保留附件清单：最新 `.md` 需求源文件、配套 `.html/.htm` 交互原型附件、正文 `![]()
` 正在引用的图片、用户明确要求保留的 PDF/其他补充附件。
- 默认删除旧版同名/同类型附件：旧 `需求说明源文件-vX`、旧截图 `*-vX`、重复上传但未被正文引用的图片、历史调试附件。
- 不删除与本次需求无关且无法判断用途的附件；如无法确认是否可删，先向用户确认。
- 删除附件必须在最终正文回写后执行，避免误删正文仍在引用的图片。
- 删除方式优先使用禅道文件删除接口：`/index.php?m=file&f=delete&fileID=&confirm=yes`；删除后重新读取 story，确认附件列表只保留应保留项。
- 默认正文显示图片；被正文 `` 或“点击查看大图”链接引用的图片附件必须保留，不能为了附件列表简洁删除正在展示的图片。
- 最终回复需说明附件清理结果：保留了哪些类型附件，删除了哪些旧版/重复附件；如无权限删除，说明未完成原因。
## 需求文档附件引用规则
写入禅道的 `spec` 不允许出现本机文件路径或仅本机可访问的原型地址。
中文说明：本地 PRD 可以保存绝对路径方便当前电脑打开，但提交到禅道后，研发/测试无法访问 `/Users/...`、`C:\...`、`file://...` 这类路径。因此禅道正文中统一写“查看禅道附件”。附件默认上传需求说明 `.md` 源文件；如有配套 HTML 原型，直接上传 `.html/.htm` 原文件，不再打包成 ZIP。
- 提交前确认需求说明 `.md` 文件是最新版本，并把它作为禅道附件上传；如已有旧版 `.md` 附件，本次提交完成后清理旧版，只保留最新源文件。
- 禅道正文中的文档引用写成：`需求文档：查看禅道附件 <需求说明>.md`。
- 如有配套 HTML 原型，禅道正文中的原型引用写成：`交互原型：查看禅道附件 <原型文件名>.html`；不要写本机绝对路径、`file://` 或本地 HTTP 地址。
- 如果正文有“交互流程图”“客户端原型”“后台原型”等本地 HTML 路径说明，提交前默认改成查看禅道附件中的 `.html/.htm` 原型；本地图片路径仍按图片规则上传并回写 `![]()
` 或改成查看附件。
- 禁止把 HTML 原型压缩成 ZIP 上传；除非用户明确要求 zip，否则必须直接上传 `.html/.htm` 文件。
- 提交到禅道前清理 `spec` 中的本地路径模式：`/Users/`、`/home/`、`C:\`、`file://`、`localhost`、`127.0.0.1`。
- 如果提交后发现禅道正文仍包含本机路径，必须立即变更需求正文并重新上传最新 `.md` 附件。
## 注意事项标准模板
提交或更新需求时，禅道“注意事项”必须结合需求按以下模板填写：
```text
【影响范围】是否会影响到需求中没提到的关联页面，或旧数据和逻辑
【需求边界】本次需求改动边界说明，仅改动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` 直连地址回写 `![]()
`。
- 提交前本地自检 `spec.html`：不能包含 `/Users/`、`/home/`、`C:\`、`file://`、`localhost`、`127.0.0.1`、`| --- |`、``。
### 2. 发现禅道 ID
- 用 `zentao products list --json` 查询产品 ID。
- 用 `zentao projects list --json` 查询项目 ID。
- 用 `zentao executions list --json` 查询版本/执行 ID。
- 用产品模块页面或禅道页面 HTML 确认模块 ID；如果 CLI 不提供模块列表，可读取创建/编辑页的 `
| `，内容用 ` | `，保留单元格文本和行内代码。
- 行内代码、字段名、枚举值转为 ``，方便识别配置项和状态值。
- 注意事项 `verify` 可用段落展示，但也不能用整段 ` |
|---|