> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 禅道

> 配置禅道连接器，将需求、任务、缺陷和附件索引限制在明确批准的项目或产品范围内。

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

## 适用场景

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

## 当前索引内容

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

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

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

## 前置条件

* 已确认禅道实例地址。公网或标准部署建议使用 HTTPS。
* 已准备专用禅道账号和密码，且该账号能读取目标项目、产品、需求、任务、缺陷和附件。
* 已整理目标项目 ID 和产品 ID。
* 如果禅道部署在内网，已由部署方确认艾维斯后端可以访问该地址，并决定是否允许内网 HTTP。
* 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。

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

## 配置数据获取入口

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

## 在艾维斯中配置

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

| 字段         | 填写方式                            | 说明                        |
| ---------- | ------------------------------- | ------------------------- |
| 禅道站点地址     | 例如 `https://zentao.example.com` | 可填写站点根地址；连接器会规范化到 API 地址。 |
| 账号         | 专用只读账号                          | 用于登录禅道 API。               |
| 密码         | 账号密码                            | 保存后通常不会明文展示。              |
| 项目 ID      | 每行一个正整数                         | 用于项目需求和任务；启用任务时必填。        |
| 产品 ID      | 每行一个正整数                         | 用于产品需求和缺陷；启用缺陷时必填。        |
| 包含需求       | 默认开启                            | 读取项目需求和/或产品需求。            |
| 包含任务       | 默认开启                            | 读取项目执行下的任务。               |
| 包含缺陷       | 默认开启                            | 读取产品下的缺陷。                 |
| 包含附件       | 默认关闭                            | 将可解析附件作为子文档。              |
| 允许内网地址     | 默认关闭                            | 仅用于已批准的私有化禅道部署。           |
| 允许不安全 HTTP | 默认关闭                            | 只有在允许内网地址后才可使用。           |

## 同步行为

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

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

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

## 权限边界

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

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

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

## 验证

1. 用一个测试项目 ID 或产品 ID 创建连接器，确认登录和范围校验通过。
2. 搜索已知需求、任务和缺陷的标题、描述关键词和状态。
3. 启用附件时，上传一个小型可解析附件并确认可被检索。
4. 搜索未列出的项目或产品，确认不会返回结果。
5. 使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。
6. 修改一条测试对象后等待下一轮同步，确认增量更新可被检索。

## 常见问题排查

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

## 安全与维护建议

* 使用专用只读账号，不复用管理员账号。
* 只在受控私有网络中启用内网地址或不安全 HTTP。
* 定期复核项目 ID、产品 ID、内容类型、附件开关、账号负责人和艾维斯访问群组。
* 账号密码疑似泄露时，立即更换并更新艾维斯凭据。
* 项目或产品结束后，停用连接器或移除不再需要的范围。

## 官方参考

* [禅道二次开发手册：RESTful API v1 配置使用与常见问题](https://www.zentao.net/book/api/1397.html?fullScreen=zentao)
* [禅道二次开发手册：获取 Token](https://www.zentao.net/book/api/664.html?fullScreen=zentao)
* [禅道二次开发手册：API v2.0 使用教程](https://www.zentao.net/book/api/2309.html?fullScreen=zentao)

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)
* [用户、群组与角色](/aivis/governance/users-and-groups)