禅道 | Alephant Documentation

禅道连接器用于把已批准禅道实例中的需求、任务、缺陷和可选附件纳入艾维斯知识检索。它按管理员显式填写的项目 ID 和产品 ID 读取数据，不会扫描整个禅道实例。

适用场景

场景	建议
项目进展问答	通过项目 ID 索引需求和任务，让 Agent 回答研发状态和交付范围问题。
缺陷复盘	通过产品 ID 索引缺陷，结合状态、描述和处理记录进行检索。
需求追溯	同时配置项目 ID 和产品 ID，覆盖项目需求与产品需求。
附件检索	仅在附件内容已获批准且文件规模可控时启用。
私有化禅道	显式开启内网访问选项，并由部署方确认网络和安全边界。

禅道连接器以项目 ID 和产品 ID 作为范围。项目 ID 和产品 ID 各最多 100 个，必须为正整数，不能重复。

禅道内容	范围要求	索引行为
需求	项目 ID 或产品 ID	索引需求标题、描述、状态、创建时间、更新时间和操作记录中的评论。
任务	至少一个项目 ID	先读取项目执行，再索引执行下的任务。
缺陷	至少一个产品 ID	索引产品下的缺陷标题、描述、状态和操作记录。
附件	依附已启用内容对象	启用后将需求、任务或缺陷下的可解析附件作为子文档。

至少需要启用需求、任务、缺陷中的一种。若启用任务，必须填写项目 ID；若启用缺陷，必须填写产品 ID。当前连接器不索引用户权限、团队成员、工时、燃尽图、测试套件、发布、文档库或未列出的项目/产品。

允许不安全 HTTP 只能在已开启 允许内网地址 后使用，并且只应面向受控私有网络中的禅道实例。公网禅道应使用 HTTPS。

配置数据	获取方式
禅道站点地址	使用禅道实例根地址，公网部署建议使用 HTTPS；API 路径通常位于站点下的 `api.php`。可参考 RESTful API v1 配置使用与常见问题。
账号 / 密码 / Token 校验	使用专用账号密码换取 API Token。可参考禅道二次开发手册：获取 Token。
项目 ID	在禅道项目页面 URL 或项目列表中确认；也可调用获取项目列表（v2）校验。
产品 ID	在禅道产品页面 URL 或产品列表中确认；也可调用获取产品列表（v2）校验。
API 版本差异	私有化部署的禅道版本不同，API 路径和请求头大小写可能不同。升级或切换版本前先阅读 API v2.0 使用教程。

在管理后台打开连接器，选择禅道。先创建或选择禅道凭据，再填写实例地址、项目/产品范围和内容类型。

标准管理后台创建的禅道连接器使用轮询索引，并支持 checkpoint 续跑。同步会按已启用内容类型处理项目需求、项目执行/任务、产品需求和产品缺陷。

阶段	同步细节
范围校验	创建前会尝试读取目标项目或产品的第一页数据，验证账号和范围。
需求	从项目和/或产品读取需求详情，并解析描述与操作记录评论。
任务	从项目读取执行列表，再读取执行下的任务详情。
缺陷	从产品读取缺陷详情，并解析描述与操作记录评论。
附件	附件作为父对象的子文档处理；无法解析时记录单项失败。

连接器会对分页总数、重复对象和清单大小做保护，避免不稳定 API 分页造成重复或漏数。

禅道账号决定艾维斯能摄取哪些项目和产品内容，但连接器不会把禅道项目成员、角色、产品权限、字段权限或单对象权限同步到艾维斯。

艾维斯访问设置	含义
私有群组	只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于项目、客户和研发数据。
公开	所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅适用于可公开给这些用户的项目。
自动同步权限	禅道当前不支持此模式。

不同项目、产品、客户或保密等级应使用不同账号、连接器和艾维斯私有群组。

现象	优先检查项
站点地址校验失败	地址是否可从艾维斯后端访问，公网是否使用 HTTPS，内网地址是否已开启允许内网选项。
登录失败	账号和密码是否正确，账号是否可登录 API，密码是否被修改。
项目或产品找不到	ID 是否为正整数，账号是否能打开目标项目或产品。
启用任务但创建失败	是否填写了项目 ID；任务索引依赖项目执行列表。
启用缺陷但创建失败	是否填写了产品 ID；缺陷索引依赖产品范围。
附件没有进入索引	是否开启包含附件，附件下载是否可访问，文件类型和大小是否可解析。
未授权用户能搜到内容	调整艾维斯访问范围，或按项目/产品/受众拆分连接器。