ZenTao AI Assistant (zentao-mcp-agent)

When to use this skill

当你（大语言模型）需要代替用户在禅道中查阅待办、分配任务、填报工时或操作任务状态机时，请必须启用此扩展包提供的 Tool 集合。依托我们的 MVC+RESTful 混动底层架构，你可以基于用户授权，越过繁杂的分页与项目界面，进行事项的统筹处理。

💡 AI 最佳实践指引 (For LLM AI)

作为 AI Assistant，当用户提出下述意图时，请严格按照指引调用底层提供的 4 大 Tool 工具：

1. 全视界地盘拉取 (Global Dashboard)

• 触发意图：用户询问**“看看张三手头有什么活”、“最近哪些线上 Bug 延期了”**。
• 调用动作：调用 getDashboard。
• 参数指南：通过 type（task/bug/story）切换类型，通过 status（doing, wait, done）过滤状态。
  • ✅ my tasks / my bugs / my stories：查询当前登录用户的待办，完全可用。
  • ✅ --assign <他人>：支持跨人员查看官方指派视角，适合主管查岗或交叉核对。
  • ✅ manage --users <成员列表>：管理视角聚合查询，适合主管查看单人或团队当前任务池。

1.1 管理聚合视角补充规则 (Management Dashboard)

• 触发意图：用户说**“帮我看张三今天要盯哪些任务”、“把我们组这几个人的任务、需求、Bug 汇总出来”**。
• 调用动作：优先调用 manage 对应的管理聚合能力。
• 参数指南：
  • --users 支持账号、中文名、多人逗号分隔。
  • --type 支持 tasks/stories/bugs/all。
  • 默认口径为 当前未完成项 + 当日完成/关闭项；若用户指定时间窗口，再追加 --date-from 与 --date-to。
  • --status 支持逗号分隔，如 doing,wait。
  • --deadline-from、--deadline-to 可用于筛选临期任务；--overdue-only 可用于只看已延期项。
  • 管理视角中的状态是跨类型语义映射，不是简单字面匹配：例如 doing,wait,done 会自动覆盖任务、需求、Bug 各自对应的待处理/已完成状态。
  • --team-name <团队名> 可直接复用本地缓存的团队成员列表，适合固定小组的日常巡检。
  • 输出中的“总计”会严格跟随当前 --type 查询口径，并额外展示过滤条件，避免将定向查询误读为全量统计。
  • my tasks --assign <账号> 与 manage --users <成员> 不可混为一谈：前者是官方指派地盘，后者是管理汇总视角。
  • 输出展示优先使用中文友好字段，方便用户直接阅读，也便于大模型后续做晨报、周报和催办摘要。

2. 对话式任务派发 (Chat-to-Task)

• 触发意图：用户说**“把网关排查的活儿发给李四，给半天时间”**，但未指明具体项目或迭代时。
• 调用动作：组合调用 getProjects -> getActiveExecutions -> (若无当期迭代则调用 createExecution) -> 最后发起 createTask。
• 参数指南：务必先明确当前的迭代/执行 execId。如不确定，先查询项目列表及其下挂载的近期执行。如有必要跨月，可智能创建一个当月的新冲刺。派单时，可以直接传入真实的中文 name、assignee 和工时 estimate（默认2小时）。底层已内置自动修补禅道必填项和账号映射转换。若是“从需求拆分任务”，可直接传 storyId + projectId；CLI 会优先复用当月执行，若不存在则复制上个执行配置后自动创建。
• 补充约定：创建任务时可直接传 pri 和 desc；若未传 pri，默认按 3 级优先级创建。

3. 一句话快捷报工 (Seamless Effort Logging)

• 触发意图：用户说**“给 10452 任务登记 2 个小时的内容撰写工时”**。
• 调用动作：调用 addEstimate。
• 参数指南：必须带有精确的 taskId、耗时 consumed 以及备注 work。本接口底座已修复了禅道坑爹的报工幽灵丢失漏洞，直接确保工时准确入库！

4. 极简状态流转 (State Machine Control)

• 触发意图：用户说**“那个 Bug 修完了，状态转给测试组长张三”**。
• 调用动作：按实体类型调用 updateTask、updateStory、updateBug 工具组合。
• 检索补充：若用户只给了任务名称而没有给 taskId，可先调用 findTasksByName 在当前账号、指定成员或团队范围内检索任务，拿到准确 ID 后再继续状态流转或报工。

5. 智能链接提取 (Smart Link Resolver)

• 触发意图：用户在群聊或对话中甩出一条任意掺杂着链接的文本（如 **“帮我看看这个任务什么情况：http://zentao.yourcompany.com/task-view-123.html”**）。
• 调用动作：提取包含网址在内的整段内容传给底层解析封装。你可以依此瞬间掌握该链接指向的任务/缺陷/需求等一切核心骨干状态。

6.