#Jira 集成

Jira 集成用于把 Jira 里的项目、issue、epic、状态、评论和附件接入 HiFox。接入后，团队可以继续保留 Jira 中已有的工作流，同时把任务交给 HiFox 里的成员、Agent 或小队处理。

HiFox 里和 Jira 相关的能力主要分成两类：

• Jira 导入：把 Jira 里已有的 issue / epic 批量导入到 HiFox；
• Jira 同步：把一个 Jira 项目和一个 HiFox Space 绑定，让后续变更在两边同步。

如果你只是想把历史数据迁进 HiFox，从导入开始。
如果你还需要继续和 Jira 双向协作，应该配置 Jira 同步。

#Jira 集成能做什么？

Jira 集成可以帮助你：

• 把 Jira issue 导入为 HiFox 任务；
• 把 Jira epic 导入或同步为 HiFox 专项；
• 把 Jira project 绑定到一个 HiFox 空间；
• 保留 Jira issue 的标题、描述、状态、优先级、处理人、标签、评论、附件、关联关系等上下文；
• 将 Jira labels 导入为 HiFox 任务标签；
• 将 Jira issue links 同步为 HiFox 任务关联；
• 根据需要把 HiFox 中的任务更新写回 Jira。

这样，Jira 可以继续作为外部任务来源，HiFox 则成为成员和 Agent 执行、追踪、协作和 review 的地方。

如果目标空间已开启分拣台，同步新建的 Jira issue 会先进入待分拣。一次性导入历史数据仍按状态映射处理，不一定进入分拣台。GitHub 等其他来源同步过来的任务，详情里的来源和链接展示与 Jira 同步任务一致。

#连接 Jira 前需要准备什么？

连接 Jira 需要一个可以访问目标 Jira 项目的账号，以及对应令牌。

通常需要准备：

• Jira 主机名，例如 acme.atlassian.net；
• 邮箱或用户名；
• Jira Cloud 的 Atlassian API token；Jira Server / Data Center 的个人访问令牌，或用户名 & 密码；
• 目标 Jira project 的访问权限；
• 如果要自动安装 webhook，账号需要具备对应 Jira 实例和项目的管理权限。缺少管理权限时，按页面上的「配置 Webhook」交给管理员处理。

HiFox 会在连接时验证凭据。令牌只提交一次，会加密保存；接口不会把完整令牌返回给前端，只会显示尾号，方便你确认当前使用的是哪一个令牌。

#Jira 导入和 Jira 同步的区别

导入适合迁移历史数据。同步适合保留 Jira 作为外部协作入口，或者让已有 Jira 流程继续运行。

导入时也可以勾选「导入后与 Jira 保持双向同步」。系统会用本次向导里填写的 Jira 账号建立绑定，不必先离开向导单独绑一次。不勾就是一次性导入，之后仍可在「外部应用集成」补开。

#建立同步后再导入历史数据

单独建立 Jira 同步不会自动回放历史数据。如果先建立了同步关系，之后仍可以从 Jira 集成或导入历史入口发起该项目的历史导入；系统会复用已保存的连接，不要求再次粘贴 token。

再次导入时，默认跳过已经通过 Jira 来源识别到的任务，不会改变它们的任务编号或本地身份。只有明确打开覆盖导入并确认已有任务数量后，才会用 Jira 的可变字段刷新这些任务；覆盖仍在原任务上进行，不会创建重复任务。导入过程的进度、失败项、取消和回滚规则与普通 Jira 导入相同。

#导入 Jira 数据

Jira 导入位于设置里的导入流程。导入向导会引导你完成配置、检查、选择范围、映射状态、映射用户、选择导入选项和确认导入。

#1. 选择导入方式

Jira 有两种导入：

1. API 导入：用 Jira 主机名、账号和 token 读取 issue / epic。适合完整迁移，也是导入后继续同步的路径。
2. 文件导入：在设置的「导入与导出」里选 Jira，上传 CSV。向导会引导你映射列/字段，再导入到指定空间。

完整历史、评论、附件和持续同步仍建议用 API 导入。文件导入适合已经从 Jira 导出过 CSV、或暂时不便走 API 的情况。

请从 Jira 用 Issues → Export → CSV (all fields) 导出，并选择全部字段。映射步骤会要求把一列映射为标题；未映射字段可能导入为自定义字段。具体映射项以向导为准。

其它来源（Linear、TAPD、Asana 等）也走同一个「导入与导出」入口。TAPD 文件导入用的是官方 Excel（.xls / .xlsx），字段映射以各来源向导为准。TAPD 的 API 导入和双向同步见 TAPD 集成。

#2. 配置 Jira 连接信息

你需要填写：

• Jira 主机名；
• 邮箱或用户名；
• Jira Cloud 使用 API token；Jira Server / Data Center 可选择 个人访问令牌 或 用户名 & 密码；
• Jira project key；
• 可选 JQL；
• 目标 HiFox Space。导入目标选择器的第一项是 +创建新空间；选择后可以直接创建空间，创建完成会回到向导，并自动将新空间设为本次导入目标。

私有化 / Server / Data Center 才会出现 使用内网代理。云端 Jira 不显示这一项。识别为内网地址时，导入和绑定会使用内网代理电脑，不要再当成可以直连。导入和绑定选择的是电脑，不会再要你选 Runtime。列表里离线电脑可见但不可选，并提示该电脑已离线。选了某台电脑后，导入和双向同步都走这台电脑。代理不可用或鉴权失败时看页面报错，不要凭记忆对照错误码。

JQL 用于限制导入范围。例如你可以只导入某个组件、某个时间之后创建的 issue，或某一类 issue。

#3. 检查导入内容

HiFox 会先读取 Jira 数据并展示预览。

预览中通常会看到：

• 将导入多少 issue；
• 将导入多少 epic；
• 发现多少状态、标签、用户、任务类型和自定义字段；
• open issue 与 closed / done issue 的数量；
• 目标 Space 中是否已经存在同来源的 Jira issue。

这一步只检查，不会创建任务。

#4. 选择导入 open 还是 closed issue

你可以选择导入：

• open issue；
• closed / done issue；
• 两者都导入。

默认适合导入完整历史。如果你只想先迁移仍在进行中的工作，可以只导入 open issue。

#5. 映射状态

Jira 状态会映射到 HiFox 的 任务状态。

HiFox 会根据 Jira 状态名称和状态分类给出默认映射。你可以：

• 使用已有 HiFox 状态；
• 为某个 Jira 状态创建新的 HiFox 状态；
• 调整状态所属分类和顺序。

选择创建新状态时，选项会显示为 新建状态（来源平台状态名），其中括号内是 Jira 的原状态名称。

建议在导入前认真检查状态映射。状态映射会影响导入后任务在列表、看板、视图和 Agent 执行流程里的位置。

#6. 映射用户

Jira 导入会扫描 assignee、reporter 以及支持的用户类型自定义字段。

每个来源用户可以选择：

• 映射到已有 HiFox 成员；
• 用 Jira 用户邮箱邀请新成员；
• 导入为外部账号：保留来源身份作为任务处理人，不占成员名额；
• 不导入：明确跳过该用户，相关任务保持未分配。

没有处理过的用户默认导入为外部账号：已经按邮箱匹配到成员的保持匹配，之前保存过映射或跳过的沿用之前的决定。这样任务不会因为用户没映射而失去处理人，也不会把历史 Jira 用户批量变成组织成员。需要对方以成员身份继续协作时，再把他们映射为成员或邀请加入。

如果你选择用邮箱创建用户，HiFox 会创建或复用对应用户，并发送组织邀请。受邀人接受后，会加入导入目标 Space。

这一步会按来源平台的能力决定：来源平台不提供「快速获取用户列表」的能力时，向导会跳过这一步；当前凭据没有读取用户列表的权限时也会自动跳过，并在「导入选项」里说明已跳过用户映射，不会再长时间停在「正在获取用户…」。跳过后，成员会按邮箱自动关联，其余保留为外部账号。

#7. 选择导入选项

导入前可以选择一些额外选项：

• 导入后与 Jira 保持双向同步：可直接勾选，不再要求预先绑定。勾选后，系统会用本次向导里的 Jira 账号建立绑定。同步是双向的：Jira 改动会进来，HiFox 里的改动也会写回 Jira。只同步导入之后的新变动，不回放更早的历史。以后可在「外部应用集成」改成单向、暂停或解除。第 1 步如果选了内网代理电脑，同步绑定也走这台电脑，不会改成云端直连。想用另一套长期账号时，用向导里的「用其他账号」（Jira 地址保持本次导入的同一实例）；
• 导入 Sprint：导入 Jira Sprint 信息；
• 切换到 Jira Sprint 模式：当目标 Space 仍使用自动迭代模式时，可以切换为手动 Jira 模式；
• 添加 Migrated 标签：默认给导入的任务添加 Migrated 标签；
• 覆盖导入：重新导入时，用 Jira 中的数据覆盖已导入任务的可变字段。

如果不确定，建议先保留默认选项。Migrated 标签对后续筛选、检查和回滚都很有帮助。

#8. 查看导入进度

导入开始后，HiFox 会显示导入任务的进度，包括总数、已完成数量、跳过数量和失败项。

导入过程中可以取消。取消后，已经创建的任务会保留；如果需要清理，可以使用导入历史中的回滚能力。

导入完成后，可以进入目标 Space 查看导入任务。通常可以用 Migrated 标签筛选导入结果。

#导入会创建哪些 HiFox 数据？

导入 Jira issue 时，HiFox 会尽量保留 Jira 上下文。

常见结果包括：

• Jira issue → HiFox 任务；
• Jira epic → HiFox 专项；
• Jira issue type → HiFox 任务类型；
• Jira status → HiFox 任务状态 / 工作流状态；
• Jira labels → 目标 Space 的标签；
• Jira watchers → 任务关注者；
• Jira comments → 任务评论；
• Jira attachments → 任务附件；
• Jira issue links → 任务关联；
• Jira sub-task / parent 关系 → HiFox 子任务关系；
• Jira Sprint → HiFox 迭代相关数据。

导入的标签归属于目标 Space，避免影响其他 Space 的标签选择器。如果组织中已经存在同名标签，导入会复用该组织标签，不再创建同名的 Space 标签。

不是每个 Jira 字段都会一比一同步。Jira 中某些高度自定义或只在特定项目配置中存在的字段，可能会作为自定义字段导入，或在当前版本中被跳过。

#回滚导入

导入历史会记录每次 Jira 导入任务。

如果导入后发现范围选错、映射不合适，或目标 Space 不正确，可以在允许时间窗口内回滚导入。回滚会删除这次导入创建的任务和专项，并标记导入记录为已回滚。

注意：回滚只清理 HiFox 中这次导入产生的数据，不会删除 Jira 里的 issue 或 epic。

#外部账号

导入或同步遇到来源平台上无法对应到组织成员的用户时，HiFox 会自动创建外部账号来承接他们，而不是把任务留空或强迫你把所有人变成成员。

外部账号是一份来源身份：记录对方来自哪个平台、哪个实例、姓名或邮箱。它不是组织成员，不占成员名额，也不能登录 HiFox。导入时「导入为外部账号」是默认选项；同步发现的新用户同样会以外部账号进入。

外部账号在组织的 人员 → 外部账号 页签里统一管理：

• 按平台、实例和关联状态（已关联 / 未关联）筛选，或按姓名、邮箱、来源标识搜索；
• 把外部账号关联到组织成员。邮箱能唯一匹配、或本人在「第三方账号绑定」里验证过同一平台账号时会自动关联；手动关联的优先级最高；
• 关联后，HiFox 会自动补全该账号名下历史任务的处理人——只补仍然保留外部身份、没有被人手动改过的任务，人工指定的处理人不会被覆盖；
• 解除关联后，相关任务恢复显示外部账号身份。

成员列表也新增了 绑定账号 列，可以直接看到哪些成员关联了外部身份。

#配置 Jira 同步

Jira 同步位于外部应用集成中的 Jira 设置。

配置一般分两步：

1. 绑定 Jira 实例；
2. 创建 Jira project 与 HiFox Space 的同步链接。

#绑定 Jira 实例

在 Jira 集成页点击设置或管理，填写：

• 主机名；
• 邮箱或用户名；
• Jira Cloud 使用 API token；Jira Server / Data Center 可选择 个人访问令牌 或 用户名 & 密码。

绑定成功后，HiFox 会保存这个组织级 Jira 连接，并弹出引导：优先配置同步数据，其次导入数据。绑定本身不会自动完成同步或导入。可以选「稍后再说」。之后可以手动刷新 Jira 项目元数据。

组织 owner / admin 可以绑定、更新凭据、刷新项目列表或断开 Jira。

#创建 Jira 同步链接

一个同步链接会把一个 Jira project 绑定到一个 HiFox Space。

创建链接时需要选择：

• Jira project；
• HiFox Space；
• 同步方向；
• issue 状态和项目状态映射。

一个 Jira project 只能主动链接到一个 Space；但多个 Jira project 可以链接到同一个 Space。行尾箭头前会显示灰色的 同步配置，点开后从抽屉里打开这条同步的配置。需要你处理时，行下方会直接出现一条黄色提示条，写明要做什么并带上操作按钮，不必先展开。

#新建同步向导

Jira 集成页的 项目同步 卡片提供 新建同步，用一个向导完成链接创建：

1. 配置：选择 Jira 绑定、项目和目标 Space，以及同步方向（默认双向）；
2. 映射状态：核对 Jira 状态与 HiFox 状态的对应关系；
3. 映射用户：决定来源用户如何承接（映射成员、邀请或导入为外部账号）；
4. 导入选项：选择是否在建立同步后补导历史数据等；
5. 确认：核对摘要后创建。

私有化部署的 Jira 还可以在配置一步选择内网代理电脑，同步相关请求会经过这台电脑。

#同步配置详情页

打开某条同步的配置后，详情页分为三个页签：

• 同步设置：持续同步的开启与暂停、同步方向、历史数据补导；
• 用户映射：调整来源用户与组织成员的对应关系；
• 状态映射：调整状态对应关系。

页签里的改动需要保存才会生效；带着未保存的更改离开时会先确认。保存后，之后的导入和同步都会使用新配置。

#手动恢复 Webhook

如果自动安装失败，这条同步链接行的下方会直接出现黄色提示条，尾部的 配置 Webhook 可以打开一次性配置包。请把它交给 Jira 管理员：配置包包含回调 URL、产品品牌请求头 X-HiFox-Webhook-Secret、查询参数备选、所需事件和项目 JQL。关闭前请复制配置包；重新生成会立即使旧令牌失效。

管理员保存 Webhook 后，请修改已绑定 Jira 项目中的一个测试 issue。只有 HiFox 收到并成功处理该签名事件后，才会启用链接。如果状态显示“已收到回调，但处理失败”，请使用显示的时间和请求 ID 联系支持；这表示入站处理异常，而不是 Jira 权限问题。

Jira project 和 Space 在链接创建后不能直接改成另一个目标。如果选错，需要删除链接后重新创建。

#同步方向

Jira 同步支持两种方向：

如果团队仍把 Jira 作为主要入口，可以先使用 Jira → HiFox。
如果团队希望在 HiFox 中创建、拆分、分配任务，同时保持 Jira 更新，可以使用双向同步。

#会同步哪些字段？

当前 Jira 同步重点覆盖任务、专项和协作中最常用的字段。

常见同步内容包括：

• 标题 / summary；
• 描述；
• 优先级；
• 状态；
• 处理人；
• 标签；
• 截止日期；
• 预估；
• Jira epic 与 HiFox 专项；
• 评论；
• 附件；
• issue link / 任务关联。

状态同步依赖状态映射。如果某个 HiFox 状态没有映射到 Jira 状态，状态更新可能不会写回 Jira，并会在任务或专项的 Jira 同步状态中显示警告。

预估会根据 Space 的估算方式和 Jira 项目配置写入。Story Points 会写入 Jira 的 Story Points 字段；时间估算会写入 Jira original estimate，并使用 Jira 实例的工作日历换算工作日和小时。

截止日期按你在 HiFox 中选的那一天写回 Jira，不受时区影响。描述写回 Jira Cloud 时保留标题、粗体、列表、代码块、链接和表格；Jira 推回同样的内容时，不会改动你在 HiFox 中的写法。

任务类型和自定义字段不会写回 Jira。持续同步时，只有 Jira 这次变更确实改了它们，HiFox 中的值才会跟着变；Jira 只改了别的字段（例如标题或排序）时，你在 HiFox 中的修改会保留。完整规则见Jira、TAPD、禅道概念对照中的「持续同步时，本地修改什么时候会被覆盖」。

#个人 Jira 账号

组织级 Jira 绑定使用的是共享集成凭据，适合执行同步、创建 issue、更新字段和安装 webhook。

如果你希望从 HiFox 写到 Jira 的评论尽量以你自己的 Jira 身份发布，可以绑定个人 Jira 账号。

绑定个人 Jira 账号后：

• 你在 HiFox 中发布到 Jira 的评论，会优先使用你的个人 Jira 凭据；
• assignee、creator / reporter、project lead 等 Jira 身份字段可以更准确映射；
• 如果个人凭据失效，评论会回退为组织级集成账号发布。

个人 Jira 账号只影响你的身份映射和评论身份，不会断开或修改组织级 Jira 同步。

#在任务中查看 Jira 同步状态

已经和 Jira 同步的任务，会在任务详情里显示 Jira 同步信息。

常见状态包括：

• 已同步；
• 待同步；
• 同步警告；
• 同步错误；
• 远端已删除；
• 存在冲突。

如果同步失败，可以查看错误说明。部分失败可以重试，例如 Jira 必填字段、权限、状态映射或凭据问题修复后，再重新触发同步。

任务详情里也可以打开对应 Jira issue。需要停止单个任务和 Jira 的关系时，管理员可以断开该任务的 Jira 同步链接；断开不会删除 HiFox 任务或 Jira issue。

#断开 Jira 或删除同步链接

断开 Jira 实例会停用这个组织的 Jira 绑定，并停用相关 Jira project 与 Space 的同步链接。后续同步会停止。

删除某个同步链接，只会停止这个 Jira project 与 Space 之间的后续同步。

这两种操作都不会删除：

• Jira issue；
• Jira epic；
• HiFox 任务；
• HiFox 专项；
• 已经导入或同步过的评论和附件。

如果只是 Jira token 过期，建议更新凭据，而不是断开整个 Jira 集成。

#权限和安全

通常规则是：

• 组织 owner / admin 可以绑定 Jira、更新凭据、创建或删除同步链接；
• 普通成员可以查看已有 Jira 同步状态；
• 成员可以绑定自己的个人 Jira 账号；
• Jira token 会加密保存，完整 token 不会在接口中返回；
• Jira 导入时使用的临时凭据只用于本次导入流程，任务完成后不会作为普通可读配置展示。

建议为 Jira 集成准备权限合适的服务账号或管理员账号，并定期轮换 token。

#最佳实践

#先小范围导入

第一次迁移时，不建议直接导入整个 Jira 历史。可以先用 JQL 限制一个项目、一个组件或最近一批 issue，确认状态、用户、标签和任务类型映射符合预期后，再扩大范围。

#先检查状态映射

状态映射会影响看板、视图和同步写回。导入或创建同步链接前，建议先确认 Jira 状态和 HiFox 状态的含义一致。

#用 Migrated 标签验收导入结果

导入时保留 Migrated 标签，可以在任务列表里快速筛选这批任务，检查数量、状态、处理人、评论和附件是否符合预期。

#不确定时先用 Jira → HiFox

如果团队还没有决定是否在 HiFox 中创建 Jira issue，可以先使用 Jira → HiFox。等团队确认 HiFox 中的任务流程稳定后，再切换到双向同步。

#让 Agent 读取同步后的任务上下文

Jira 导入或同步后的任务会保留描述、评论、附件、标签和关联任务。把这些任务指派给 Agent 前，建议补充清楚目标和验收标准，让 Agent 不只是读取历史上下文，还知道下一步要做什么。

#常见问题

#Jira Cloud 和 Jira Server / Data Center 都支持吗？

支持。Jira Cloud 使用邮箱和 Atlassian API token。Jira Server / Data Center 可以选择 个人访问令牌，或使用 用户名 & 密码。自动安装 webhook 仍建议使用具备 Jira 管理权限的账号。

#导入会删除 Jira 里的 issue 吗？

不会。导入只在 HiFox 中创建任务、专项和相关数据，不会删除 Jira 数据。

#同步链接删除后，已有任务还在吗？

还在。删除同步链接只停止后续同步，不删除已经存在的 HiFox 任务或 Jira issue。

#为什么绑定成功后看不到 Jira project？

可能是账号没有访问项目的权限，或者项目元数据还没有刷新。可以在 Jira 集成页刷新 Jira 项目列表，并确认凭据账号能在 Jira 中浏览对应项目。

#为什么状态没有同步回 Jira？

通常是状态映射缺失、Jira 工作流不允许直接切换到目标状态，或 Jira 项目有必填字段 / workflow rule 拦截。先检查同步状态里的错误说明，再调整状态映射或 Jira 工作流配置。

#评论一定会同步到 Jira 吗？

不是。只有通过支持“发布到 Jira”的评论入口发布的顶层成员评论，才会写回 Jira。普通本地评论、回复和 Agent 评论会保留在 HiFox 任务中。

#附件会重复上传吗？

HiFox 会记录 Jira 附件的远端 ID，避免已从 Jira 拉取或已经上传过的附件再次上传。

#我应该用导入还是同步？

如果目标是一次性迁移历史数据，用导入。
如果目标是让 Jira 和 HiFox 在之后继续保持更新，用同步。
如果既要迁移历史，又要保持后续更新，在导入向导里直接勾选「导入后与 Jira 保持双向同步」即可；系统会用本次填写的账号建立绑定。

#Jira 同步故障排查

当任务或专项顶部出现 Jira 同步提示时，先看分类标题后面的原文（例如 no transition to status "进行中"），再按下表做对应操作。修复后，在任务或专项详情中重试同步。

#根据横幅原文选择操作

#Jira 权限或认证失败

这通常表示当前组织级 Jira 凭据、个人 Jira 凭据或账号权限不可用。

可以按顺序检查：

1. 在 Jira 集成页更新组织级 Jira token；
2. 确认该账号可以在 Jira 中浏览目标项目，并有创建或编辑 issue 的权限；
3. 如果失败发生在评论同步，确认评论发布者是否需要绑定或更新个人 Jira 账号；
4. 更新凭据后重试同步。

#未找到 Jira 条目

这通常表示 HiFox 中的同步任务仍在，但对应的 Jira issue 已被删除、移动、归档，或当前 Jira 账号已经无法访问。

可以按顺序检查：

1. 从任务详情打开 Jira issue，确认 Jira 中是否仍能访问；
2. 如果 issue 被误删或归档，先在 Jira 中恢复；
3. 如果只是权限变化，恢复集成账号对该项目或 issue 的访问权限；
4. 如果不再需要同步，断开这个任务和 Jira issue 的同步链接。

#Jira Epic 类型不可用

这通常发生在同步项目或 epic 时：目标 Jira 项目没有可用的 Epic issue type，或项目配置不允许创建 Epic。

可以按顺序检查：

1. 在 Jira 项目设置中确认 Epic 类型已启用；
2. 确认集成账号有创建 Epic 的权限；
3. 如果当前 Jira 项目不使用 Epic，改用单向同步或避免把 HiFox 专项写回为 Jira Epic；
4. 调整后重新触发同步。

#Jira 必填字段拦截了同步

这通常表示 Jira 项目的创建或编辑界面中有 HiFox 当前不会写入的必填字段，例如组件、版本、自定义字段或安全级别。

可以按顺序检查：

1. 查看 Jira 返回的具体字段错误；
2. 在 Jira 项目配置中移除这类字段的必填要求，或给字段设置默认值；
3. 确认该字段出现在 Jira 的创建或编辑界面中，且集成账号有权限写入；
4. 修复 Jira 配置后重试同步。

#Jira 工作流或字段约束拦截了同步

这是最常见的一类提示。分类标题相同，但后面的原文决定你该做什么。

#原文是 no transition to status "xx"

Jira 有这个状态，但当前 issue 不能从现在的状态一步转到它。常见原因：自定义工作流不能任意跳；多个 HiFox「进行中」类状态被自动映射到同一个 Jira 状态（例如把「开发中」写成「进行中」）。

按这个顺序处理：

1. 从任务详情打开 Jira issue，看当前状态和页面上实际能点的流转；
2. 打开 Space 的 Jira 同步链接，检查状态映射：HiFox「开发中」应映射到 Jira「开发中」，不要把所有进行中都指到「进行中」；
3. 确认目标 Jira 状态能从当前状态直接到达。如果必须经过中间状态，先在 Jira 里走完，或改映射；
4. 调整后重试同步。

#原文含 not mapped to a Jira issue status

这个 HiFox 状态没有映射。打开同步链接的状态映射，给它指定 Jira 状态，或明确设为不同步，然后重试。

#原文含 field cannot be set 或 unknown field

当前 Jira 界面或字段上下文不允许写这个字段。检查编辑界面、字段上下文和 issue type，修好后重试。

如果原文对不上上面三类，再按顺序检查：

1. 状态映射是否指向了正确的 Jira 状态；
2. Jira 工作流的 validator、condition、post function 是否限制了字段、角色或流转路径；
3. 调整 Jira 配置或状态映射后重试同步。

#Jira webhook 或项目范围需检查

这通常表示 Jira 到 HiFox 的后续更新没有进入同步链路，常见原因是 webhook JQL、项目范围或 Jira 项目绑定不匹配。

可以按顺序检查：

1. 确认 Jira project 已经和正确的 HiFox Space 建立同步链接；
2. 检查 Jira webhook 的 JQL 是否覆盖目标项目和 issue 范围；
3. 确认导入时使用的 JQL 只影响导入范围，不会自动限制后续同步 webhook；
4. 如果项目范围变更过，刷新 Jira 项目元数据或重新创建同步链接。

#正在显示按分类的默认状态映射

这通常表示 HiFox 暂时无法读取 Jira 的实时状态列表，只能根据 Jira 状态分类显示默认映射。

可以按顺序检查：

1. 更新或重新绑定 Jira 凭据；
2. 确认集成账号可以读取 Jira 项目状态和工作流信息；
3. 刷新 Jira 项目元数据；
4. 重新打开状态映射配置，选择准确的 Jira 状态。

#评论使用了集成账号

这通常表示当前成员没有可用的个人 Jira 账号，或个人 Jira 凭据失效。HiFox 会回退为组织级集成账号发布 Jira 评论。

可以按顺序检查：

1. 成员在个人设置中绑定或更新自己的 Jira 账号；
2. 确认个人 Jira 账号可以浏览并评论目标 issue；
3. 如果团队接受统一身份发布评论，也可以继续使用集成账号；
4. 重新发布需要同步到 Jira 的评论。

#Jira 附件同步需要关注

这通常表示附件上传或读取失败，常见原因包括附件过大、Jira 附件权限不足、Jira 项目禁用了附件，或网络请求失败。

可以按顺序检查：

1. 确认 Jira 项目允许上传附件；
2. 确认集成账号有读取和上传附件的权限；
3. 检查附件大小是否超过 Jira 或组织配置限制；
4. 删除或压缩异常附件后重试同步。

如果提示不是以上类型，而是泛化的“Jira 写入失败”，通常需要查看同步提示里的 Jira 原始错误，再按字段、权限、工作流或附件方向继续排查。