ZenTao AI Assistant (zentao-mcp-agent)

When to use this skill

When you (a large language model) need to act on behalf of users to view to-dos, assign tasks, log work hours, or operate task state machines in ZenTao, you must enable the Tool set provided by this extension package. Relying on our MVC+RESTful hybrid underlying architecture, you can, based on user authorization, bypass complicated pagination and project interfaces to carry out overall management of matters.

💡 AI Best Practice Guidelines (For LLM AI)

As an AI Assistant, when users express the following intents, please strictly follow the guidelines to call the 4 major Tools provided by the underlying layer:

1. Global Dashboard Pull

Trigger Intent: Users ask "What tasks does Zhang San have on hand?", "Which online bugs have been delayed recently?".
Call Action: Call
```
getDashboard
```
.
Parameter Guide: Switch types via
```
type
```
(task/bug/story), filter status via
```
status
```
(doing, wait, done).
- ✅
```
my tasks / my bugs / my stories
```
  : Queries the to-dos of the currently logged-in user, fully available.
- ✅
```
--assign <other user>
```
  : Supports cross-user viewing of official assignment perspectives, suitable for supervisors to check work or cross-verify.
- ✅
```
manage --users <member list>
```
  : Aggregated query from a management perspective, suitable for supervisors to view the current task pool of an individual or team.

1.1 Supplementary Rules for Management Aggregation View

Trigger Intent: Users say "Help me check which tasks Zhang San needs to oversee today", "Summarize the tasks, requirements, and bugs of our team members".
Call Action: Prioritize calling the management aggregation capability corresponding to
```
manage
```
.
Parameter Guide:
- ```
--users
```
  supports account numbers, Chinese names, and multiple users separated by commas.
- ```
--type
```
  supports
```
tasks/stories/bugs/all
```
  .
- The default scope is current unfinished items + items completed/closed today; if the user specifies a time window, append
```
--date-from
```
  and
```
--date-to
```
  .
- ```
--status
```
  supports comma separation, such as
```
doing,wait
```
  .
- ```
--deadline-from
```
  and
```
--deadline-to
```
  can be used to filter tasks due soon;
```
--overdue-only
```
  can be used to view only overdue items.
- The status in the management perspective is cross-type semantic mapping, not simple literal matching: for example,
```
doing,wait,done
```
  will automatically cover the corresponding pending/completed statuses of tasks, requirements, and bugs.
- ```
--team-name <team name>
```
  can directly reuse the locally cached team member list, suitable for daily patrols of fixed teams.
- The "total" in the output will strictly follow the current
```
--type
```
  query scope, and additional filter conditions will be displayed to avoid misinterpreting targeted queries as full statistics.
- ```
my tasks --assign <account>
```
  and
```
manage --users <member>
```
  are not the same: the former is the official assignment scope, while the latter is the management aggregation perspective.
- The output prioritizes using Chinese-friendly fields for direct user reading, and also facilitates the large model to generate morning reports, weekly reports, and follow-up summaries later.

2. Chat-to-Task Assignment

Trigger Intent: Users say "Assign the gateway troubleshooting task to Li Si, give him half a day" without specifying the specific project or iteration.
Call Action: Combine calls
```
getProjects
```
->
```
getActiveExecutions
```
-> (call
```
createExecution
```
if there is no current iteration) -> finally initiate
```
createTask
```
.
Parameter Guide: Be sure to clarify the current iteration/execution
```
execId
```
first. If unsure, query the project list and its recently attached executions first. If necessary to cross months, intelligently create a new sprint for the current month. When assigning tasks, you can directly pass in the real Chinese
```
name
```
,
```
assignee
```
, and estimated hours
```
estimate
```
(default 2 hours). The underlying layer has built-in automatic patching of ZenTao required fields and account mapping conversion. If it is "split tasks from requirements", you can directly pass
```
storyId + projectId
```
; the CLI will prioritize reusing the current month's execution, and if it does not exist, it will copy the previous execution configuration and create it automatically.
Supplementary Agreement: You can directly pass
```
pri
```
and
```
desc
```
when creating a task; if
```
pri
```
is not passed, it will be created with priority level
```
3
```
by default.

3. Seamless Effort Logging

Trigger Intent: Users say "Log 2 hours of content writing work for task 10452".
Call Action: Call
```
addEstimate
```
.
Parameter Guide: Must include the exact
```
taskId
```
, consumed time
```
consumed
```
, and remark
```
work
```
. This interface base has fixed ZenTao's annoying effort logging ghost loss vulnerability, directly ensuring accurate work hour storage!

4. Minimalist State Transition

Trigger Intent: Users say "That bug has been fixed, transfer the status to test team leader Zhang San".
Call Action: Call the tool combination
```
updateTask
```
,
```
updateStory
```
,
```
updateBug
```
according to the entity type.
Supplementary Retrieval: If the user only provides the task name but not the
```
taskId
```
, you can first call
```
findTasksByName
```
to retrieve the task within the current account, specified member, or team scope, and then proceed with state transition or effort logging after obtaining the accurate ID.

5. Smart Link Resolver

Trigger Intent: Users send a piece of text with any mixed links in group chats or conversations (such as "Help me check the status of this task: http://zentao.yourcompany.com/task-view-123.html").
Call Action: Pass the entire segment including the URL to the underlying layer for parsing and encapsulation. You can instantly grasp all core statuses of the task/defect/requirement pointed to by the link.

6. Workload Radar Before Assignment

Trigger Intent: Before assigning a new task, users ask "How many tasks does Li Si currently have, and how many hours of work are left?" or "Help me see who is more available between Zhang San and Li Si".
Call Action: Call the underlying
```
getMemberLoad
```
, pass in one or more member accounts/Chinese names, pull their ongoing tasks and remaining work hours concurrently, and report uniformly.
Important Principle: This is purely reference data, and should not automatically block or reject assignment operations. Present the data to the user and let the user decide whether to continue assigning.
Team Cache Supplement: If the user has saved a team alias, you can prioritize using
```
--team-name
```
to reuse the team member list.
Scope Supplement: This capability has reused the management perspective base, and the output will explicitly indicate whether it is a task or a bug.
Display Supplement: The output should include the number of unfinished
```
P1
```
tasks, the average progress of tasks, and the individual progress percentage of each task to help users quickly judge the quality of team workload.

7. Stagnant Tasks Patrol

Trigger Intent: Users ask "What tasks has Zhang San not been working on for a long time" or "Help me check if there are any tasks in the team that have been unattended for more than a week".
Call Action: Extract the target member list and stagnation day threshold (default 3 days), call
```
getStagnantTasks
```
to return a list of stagnant documents sorted by stagnation duration.

8. Morning Standup Radar

Trigger Intent: Users say "Help me generate today's morning standup report" or "See what urgent matters the team has today" and provide the team member list.
Call Action: Call
```
getMorningCheck
```
, pass in the team member list, and return three types of lists:
```
overdue
```
(already overdue),
```
dueSoon
```
(due today or tomorrow),
```
highPriority
```
(high-priority pending).
Output Requirements: Present the three types of data in a clear and concise format, use emojis to distinguish risk levels (🔴 Overdue / 🟡 Due Soon / 🟠 High Priority), so that users can directly forward the morning standup report.
Team Cache Supplement: Fixed teams can first establish an alias through
```
team save
```
, and directly use
```
--team-name
```
for subsequent morning standups.
Scope Supplement: This capability has reused the management perspective base, and the warning list will explicitly distinguish between tasks, requirements, and bugs.
Filter Supplement: Requirements without deadlines are not included in the morning standup warning by default to avoid misjudging low-time-sensitive matters as morning standup risks.
Parameter Supplement: Supports adjusting the high-priority threshold for morning standup attention via
```
--pri-max
```
, for example, passing
```
1
```
only retains
```
P1
```
items; the output also displays coarse-grained progress percentages to facilitate quick judgment of progress.

9. Automated Weekly Synthesis

Trigger Intent: Users say "Help me generate this week's weekly report materials", "Summarize the key items delivered by the team this week" and provide the team member list or team name.
Call Action: Call
```
getWeeklySynthesis
```
, pass in the team member list and time window, and return two types of core lists:
```
stories
```
(high-priority requirement delivery) and
```
bugs
```
(major defect fixes), along with member-level delivery summaries.
Output Requirements: Prioritize displaying the statistical scope, this week's deadline window,
```
total delivery / high-priority delivery / pending tasks this week
```
and member delivery summaries; only when the user explicitly needs itemized lists, supplement the details of tasks, requirements, and bugs.
Team Cache Supplement: Fixed teams prioritize establishing an alias through
```
team save
```
, and directly reuse
```
--team-name
```
for weekly reports.
Parameter Supplement: Supports
```
--date-from
```
and
```
--date-to
```
to customize the statistical window, supports
```
--pri-max
```
to converge to higher-value delivery items; the bug severity level follows this threshold by default, and
```
--severity-max
```
is only retained as a compatible supplementary parameter.
View Supplement: Supports
```
--view summary|full
```
, defaults to
```
summary
```
. When the user only needs to provide draft materials to the large model, use the default value directly; when the user explicitly needs itemized lists, switch to
```
full
```
.
Week Window Supplement: The weekly report will automatically recognize Monday to Sunday according to the natural week; even if queried on Thursday, Friday, or Saturday, it will automatically include tasks that are due this weekend but not yet completed.

💻 Environment & Security Notes

⚠️ Usage Notice: This is a restricted mainstream large model end-bridging application. To ensure your operational compliance, this extension will not perform any risk tuning or system tampering without authorization.

1. Installation & Dependency Introduction

If you need to use or verify this tool in the local command line, you can install it globally or load it as an extension:

bash

# 全局安装 CLI 工具
npm install -g @chenish/zentao-mcp-agent

# 或者通过 npx 挂载大模型工具 (如平台需要)
npx skills add @chenish/zentao-mcp-agent

As an environment dependency base, authorization authentication must be performed for the first use:

bash

zentao-cli login --url "https://xxxxx.com/zentao" --account "<账号>" --pwd "<密码>"

2. Full Command Line Call Examples

This plugin has encapsulated the extremely complex ZenTao API and routing into a minimalist command set, which can be used as a daily CLI:

🔥 My Dashboard

bash

# 基础：默认拉取指派给我的待办任务
zentao-cli my tasks
# 分类：拉取指派给我的缺陷清单
zentao-cli my bugs
# 分类：拉取指派给我的需求清单 (聚合：一键获取我名下的业务需求)
zentao-cli my stories
# 管理视角：跨权限查看张三地盘上的所有任务 (查岗：跨项目查阅张三的任务列表)
zentao-cli my tasks --assign 张三
# 精准过滤：查看张三目前正在进行中的任务 (过滤：精确提取张三进行中的代办)
zentao-cli my tasks --assign 张三 --status doing
# 管理聚合视角：汇总张三当前相关的任务、需求、缺陷
zentao-cli manage --users 张三
# 管理聚合视角：只看团队成员当前任务池
zentao-cli manage --users 张三,李四 --type tasks
# 管理聚合视角：只看单人的缺陷
zentao-cli manage --users 张三 --type bugs
# 管理聚合视角：只看进行中的任务
zentao-cli manage --users 张三 --type tasks --status doing
# 管理聚合视角：同时看进行中与待开始任务
zentao-cli manage --users 张三 --type tasks --status doing,wait
# 团队缓存视角：直接按团队名查询
zentao-cli manage --team-name "规划组"
# 时间窗管理视角：补入指定日期内完成/关闭的任务
zentao-cli manage --users 张三,李四 --date-from 2026-03-12 --date-to 2026-03-12
# 临期任务视角：筛出周末前到期任务
zentao-cli manage --users 张三,李四 --type tasks --deadline-to 2026-03-16
# 风险视角：只看已延期任务
zentao-cli manage --users 张三,李四 --type tasks --overdue-only
# 团队缓存管理
zentao-cli team save --name "规划组" --users "张三,李四,王五"
zentao-cli team list
zentao-cli team show --name "规划组"
zentao-cli team delete --name "规划组"
# 团队缓存晨会：只看 P1 高优事项
zentao-cli morning-check --team-name "规划组" --pri-max 1
# 团队缓存负荷：查看 P1 数量与任务进度
zentao-cli load --team-name "规划组"
# 团队缓存周报：输出本周高优需求与重大缺陷修复
zentao-cli weekly-synthesis --team-name "规划组"
# 自定义时间窗周报
zentao-cli weekly-synthesis --team-name "规划组" --date-from 2026-03-09 --date-to 2026-03-13 --pri-max 1
# 摘要模式周报：仅输出统计与重点摘要
zentao-cli weekly-synthesis --team-name "规划组" --view summary
# 详情模式周报：输出完整任务、需求、Bug 清单
zentao-cli weekly-synthesis --team-name "规划组" --view full

🔥 Chat-to-Task & Execution Autonomy

bash

# 列出活跃中的项目总库 (新增能力)
zentao-cli projects
# 获取某项目下活跃的冲刺/迭代 ID 列表 (历史意图示例，当前 CLI 参数请使用 --projectId)
zentao-cli executions --project 577
# 获取某项目下活跃的冲刺/迭代 ID 列表 (当前 CLI 参数)
zentao-cli executions --projectId 577
# 仅看进行中的迭代
zentao-cli executions --projectId 577 --status doing
# 当期无迭代时：自动新建一个默认7天的本月新冲刺阶段
zentao-cli execution create --projectId 577 --name "2026年3月常规迭代"
# 显式指定起止日期创建迭代
zentao-cli execution create --projectId 577 --name "2026年3月常规迭代" --begin "2026-03-17" --end "2026-03-24"
# 指定工作日天数
zentao-cli execution create --projectId 577 --name "2026年3月常规迭代" --days 6
# 瞬时派单：时间与工时全部由底层静默注入默认值
zentao-cli task create --execId 123 --name "网关熔断排查" --assign "张三"
# 带优先级与描述派单
zentao-cli task create --execId 123 --name "网关熔断排查" --assign "张三" --pri 2 --desc "补充任务描述"
# 精细派单：明确指定 8 小时预估工时和特定截止日期
zentao-cli task create --execId 123 --name "全量压测" --assign "李四" --estimate 8 --deadline "2026-03-20"
# 指定预估工时，截止日期走默认值
zentao-cli task create --execId 123 --name "接口联调" --assign "张三" --estimate 4
# 从需求拆分任务：自动复用当月执行，必要时复制上个执行后建任务
zentao-cli task create --storyId 12072 --projectId 281 --name "数据库改造脚本适配" --assign "张三" --estimate 8 --pri 2
# 从需求拆分任务：显式指定执行模板与新执行名称
zentao-cli task create --storyId 12072 --projectId 281 --templateExecId 5825 --executionName "2026年03月常规迭代" --name "数据库改造脚本适配" --assign "张三" --desc "从需求拆分的研发任务"

🔥 State Machine Control

bash

# 状态扭转：仅将任务状态标记为已完成
zentao-cli task update --taskId 123 --status done
# 先按名称找任务 ID
zentao-cli task find --name "网关排查"
# 在指定成员范围内按名称找任务
zentao-cli task find --name "接口联调" --owner zhangsan,lisi
# 在团队缓存范围内按名称找任务
zentao-cli task find --name "接口联调" --team-name "规划组"
# 启动任务：切换为进行中
zentao-cli task update --taskId 123 --status doing --comment "开始处理"
# 关闭任务：验证完成后关闭
zentao-cli task update --taskId 123 --status closed --comment "验证通过，执行关闭"
# 任务转交：仅将任务丢给张三处理
zentao-cli task update --taskId 123 --assign 张三
# 复合协同：完成、转交、加备注一气呵成
zentao-cli task update --taskId 123 --status done --assign 张三 --comment "代码已提交，转交测试验证"
# 关闭需求：将需求直接关闭
zentao-cli story update --storyId 12072 --status closed --comment "需求已验收完成"
# 激活需求：将已关闭需求重新激活
zentao-cli story update --storyId 14526 --status active --comment "重新激活继续推进"
# 转交需求：将需求交给张三继续跟进
zentao-cli story update --storyId 12072 --assign 张三 --comment "转交继续跟进"
# 解决缺陷：将 Bug 标记为已解决
zentao-cli bug update --bugId 11071 --status done --comment "缺陷已修复完成"
# 关闭缺陷：验证通过后关闭 Bug
zentao-cli bug update --bugId 11071 --status closed --comment "验证通过，关闭缺陷"
# 重开缺陷：继续跟踪处理
zentao-cli bug update --bugId 11071 --status active --comment "重新激活继续跟踪"
# 转交缺陷：将 Bug 交给张三继续跟进
zentao-cli bug update --bugId 11071 --assign 张三 --comment "转交继续跟进"

🔥 Seamless Effort Logging

bash

# 极简报工：给 69704 任务快速登记 2 小时消耗
zentao-cli task effort --taskId 69704 --consumed 2
# 详尽报工：登记耗时并追加详细的研发日志
zentao-cli task effort --taskId 69704 --consumed 2.5 --desc "完成了核心业务逻辑的编写"

当前
task effort
CLI 已稳定支持
--taskId + --consumed
，可选
--desc
；仅写说明不填耗时仍属于后续增强目标。

Current Known Limitations

The form of
```
task effort --taskId <id> --desc "..."
```
which only writes remarks without filling in consumed time will not stably save remarks in the page history in the current ZenTao environment.
```
story update --storyId <id> --status active
```
has not yet taken effect stably in the current ZenTao environment, and the requirement activation link is still to be investigated later.

🤝 Welcome to Submit Requirements and Collaborate

If you have any new expectations for this plugin, or hope that the community will help you add more customized and automated function interfaces for the ZenTao system, we are very willing and happy to expand the functions for everyone! Welcome to submit your Issue requirements or bug reports to the GitHub Repository at any time.

zentao

NPX Install

Tags

SKILL.md Content (Chinese)

ZenTao AI Assistant (zentao-mcp-agent)

When to use this skill

💡 AI Best Practice Guidelines (For LLM AI)

1. Global Dashboard Pull

1.1 Supplementary Rules for Management Aggregation View

2. Chat-to-Task Assignment

3. Seamless Effort Logging

4. Minimalist State Transition

5. Smart Link Resolver

6. Workload Radar Before Assignment

7. Stagnant Tasks Patrol

8. Morning Standup Radar

9. Automated Weekly Synthesis

💻 Environment & Security Notes

1. Installation & Dependency Introduction

2. Full Command Line Call Examples

🤝 Welcome to Submit Requirements and Collaborate