> 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. # TAPD > 配置 TAPD 连接器，将需求、任务、缺陷和附件索引限制在明确批准的项目空间内。 TAPD 连接器用于把已批准 TAPD 项目空间中的需求、任务、缺陷和可选附件纳入艾维斯知识检索。它只读取管理员显式填写的项目空间 ID，不会扫描整个企业，也不提供 WPS 入口。 ## 适用场景 | 场景 | 建议 | | ------- | ----------------------------- | | 需求与缺陷问答 | 按 TAPD 项目空间创建连接器，并启用需求、任务、缺陷。 | | 项目复盘 | 将需求描述、任务状态、缺陷描述和评论沉淀为检索上下文。 | | 附件检索 | 仅在附件内容已获批准且文件规模可控时启用。 | | 多项目治理 | 按业务线或客户拆分连接器，避免一个 API 账号覆盖过宽。 | | 增量同步验证 | 用边界时间附近的对象测试修改时间窗口，避免遗漏或重复。 | ## 当前索引内容 TAPD 连接器以一个或多个 `workspace_id` 作为范围。最多 100 个项目空间 ID，必须为正整数，不能重复。 | TAPD 内容 | 索引行为 | | ------- | --------------------------------------------- | | 需求 | 启用**包含需求**后，索引需求标题、描述、状态、负责人、创建人、创建时间和更新时间。 | | 任务 | 启用**包含任务**后，索引任务标题、描述、状态、负责人、创建人、创建时间和更新时间。 | | 缺陷 | 启用**包含缺陷**后，索引缺陷标题、描述、状态、当前处理人、报告人、创建时间和更新时间。 | | 附件 | 启用**包含附件**后，连接器会读取已启用内容对象下的附件，并将可解析附件作为子文档。 | 至少需要启用需求、任务、缺陷中的一种。当前连接器不索引项目成员权限、迭代统计、工时、看板配置、报表、流程设置或企业下未列出的其他项目。 ## 前置条件 * 已准备 TAPD API 用户名和 API 密码。不要使用没有 API 权限的普通登录密码。 * 已确认 API 账号能读取目标项目空间下需要索引的需求、任务、缺陷和附件接口。 * 已整理目标项目空间 ID，例如 TAPD 项目 URL 中的数字空间 ID。 * 已决定是否索引附件；附件会增加同步耗时、存储和解析失败概率。 * 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。 * 网络策略允许艾维斯后端访问 `api.tapd.cn`。 ## 配置数据获取入口 | 配置数据 | 获取方式 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API 用户名 / API 密码 | 在 TAPD 公司管理的开放平台配置中查看 `api_user` 与 `api_password`。可参考 [TAPD 开放平台：API 配置指引](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/API%E9%85%8D%E7%BD%AE%E6%8C%87%E5%BC%95.html)。 | | 项目空间 ID `workspace_id` | 在 TAPD 项目空间左上角项目名称处查看项目 ID，或调用 [获取项目信息](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/workspace/get_workspace_info.html) 验证。可先阅读 [使用必读](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/%E4%BD%BF%E7%94%A8%E5%BF%85%E8%AF%BB.html)。 | | 需求字段与可读性 | 用目标 `workspace_id` 调用 [获取需求](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/story/get_stories.html) 验证 API 账号是否能读取。 | | 任务字段与可读性 | 用目标 `workspace_id` 调用 [获取任务](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/task/get_tasks.html) 验证。 | | 缺陷字段与可读性 | 用目标 `workspace_id` 调用 [获取缺陷](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/bug/get_bugs.html) 验证。 | ## 在艾维斯中配置 在管理后台打开**连接器**，选择 **TAPD**。先创建或选择 TAPD 凭据，再填写项目空间与内容类型。 | 字段 | 填写方式 | 说明 | | ------- | --------------------- | -------------------- | | API 用户名 | TAPD 提供的 API 用户名 | 用于访问 TAPD Open API。 | | API 密码 | TAPD API 密码 | 保存后通常不会明文展示。 | | 项目空间 ID | 每行一个正整数，例如 `20000001` | 只索引列出的项目空间，最多 100 个。 | | 包含需求 | 默认开启 | 读取需求标题、描述和状态等字段。 | | 包含任务 | 默认开启 | 读取任务标题、描述和状态等字段。 | | 包含缺陷 | 默认开启 | 读取缺陷标题、描述和状态等字段。 | | 包含附件 | 默认开启 | 读取已启用对象下的可解析附件。 | 建议先用一个测试项目空间和少量内容类型完成验证，再扩大范围。 ## 同步行为 标准管理后台创建的 TAPD 连接器使用轮询索引，并支持 checkpoint 续跑。同步会按项目空间处理，每个空间内按已启用内容类型依次处理需求、任务和缺陷。 | 阶段 | 同步细节 | | ---- | ------------------------------------------ | | 清单构建 | 按页读取同步时间窗口内修改过的对象，并按修改时间和 ID 形成稳定顺序。 | | 正文解析 | 将 TAPD HTML 描述转换为可检索文本，同时保留状态、负责人和创建人等元数据。 | | 附件 | 附件作为父对象的子文档处理；单个对象最多处理 1000 个附件。 | | 增量 | 对象修改后会以稳定 ID 更新，不应产生重复文档。 | ## 权限边界 TAPD API 账号决定艾维斯能摄取哪些项目内容，但连接器不会把 TAPD 项目成员、角色、字段权限或单个对象权限同步到艾维斯。 | 艾维斯访问设置 | 含义 | | ------- | ------------------------------------------- | | 私有群组 | 只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于项目、客户和研发数据。 | | 公开 | 所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅适用于可公开给这些用户的项目。 | | 自动同步权限 | TAPD 当前不支持此模式。 | 对于不同客户、项目组或保密等级，应使用不同 TAPD API 账号、连接器和艾维斯私有群组。 ## 验证 1. 用一个测试项目空间创建连接器，确认凭据和空间 ID 校验通过。 2. 搜索一条已知需求、任务和缺陷的标题与描述关键词。 3. 启用附件时，上传一个小型文本附件并确认可被检索。 4. 修改一条测试对象，等待下一轮同步，确认搜索结果更新且没有重复文档。 5. 搜索未列出的项目空间内容，确认不会返回结果。 6. 使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。 ## 常见问题排查 | 现象 | 优先检查项 | | ------------- | --------------------------------------- | | 认证失败 | API 用户名和 API 密码是否正确，账号是否仍有 API 权限。 | | 项目空间校验失败 | `workspace_id` 是否为正整数，API 账号是否能读取该项目空间。 | | 某类对象为空 | 对应的需求、任务或缺陷开关是否开启，API 账号是否具备该接口权限。 | | 附件没有进入索引 | 是否开启**包含附件**，附件接口权限是否可用，文件类型和大小是否可解析。 | | 增量结果缺失 | 对象更新时间是否落在同步窗口内，是否需要重新运行完整同步进行对账。 | | 搜索结果包含不该公开的项目 | 调整艾维斯访问范围，或按项目/受众拆分连接器。 | ## 安全与维护建议 * 使用专用 TAPD API 账号，不复用个人高权限账号。 * 定期复核项目空间列表、内容类型、附件开关、API 账号负责人和艾维斯访问群组。 * 附件体量较大时，先在测试环境测量解析耗时和失败率。 * API 密码疑似泄露时，立即更换并更新艾维斯凭据。 * 项目结束后，停用连接器或移除不再需要的项目空间 ID。 ## 官方参考 * [TAPD 开放平台：API 配置指引](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/API%E9%85%8D%E7%BD%AE%E6%8C%87%E5%BC%95.html) * [TAPD 开放平台：获取需求](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/story/get_stories.html) * [TAPD 开放平台：获取任务](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/task/get_tasks.html) * [TAPD 开放平台：获取缺陷](https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/api_reference/bug/get_bugs.html) ## 相关页面 * [连接器与索引](/aivis/knowledge/connectors) * [索引设置](/aivis/knowledge/index-settings) * [用户、群组与角色](/aivis/governance/users-and-groups)