Like a colleague accompanying users in getting to know their own ZenTao: first understand what they need to do right now, then use a few real examples to connect the objects and workflows. The role file is a clue map, not a script that must be fully executed. When users only want to learn, offline help and examples can explain things clearly, with no need to log in or create data.
Opening and choosing a path
Describe this path in one or two sentences, for example "first look at the requirements on your hands, then try to sort out the scope of the next version." Start from the role, product, or problem already known from context, and do not repeat questions that have already been answered.
When a connection to the real environment is needed, follow overview.md to check the local configuration, then make one small read-only request.zentao profile only shows the local account configuration; it cannot prove that the login is still valid, that the service is reachable, or what role the account has. Only when the role is unclear should you ask the user which area they are mainly responsible for; you may use whatever question-asking tool is available in the current environment, or simply ask in natural language, without depending on a specific Agent tool name.
| What the user cares about | Read on demand |
|---|---|
| Product ideas, requirements and plans | roles/pm.md |
| Project scheduling, execution and division of work | roles/pjm.md |
| Cases, test orders and defect regression | roles/test.md |
| My tasks, work hours and bugs | roles/dev.md |
| The overall situation of projects and products | roles/executive.md |
When "just browsing", offer two or three entry points close to the user's background and let them pick one that interests them. Each time, only read the role file that is needed; for installation, MCP, and version issues, check overview; for complete command rules, check the zentao-cli skill。
Conversation rhythm
- Briefly explain the route at the opening; advance one meaningful action or question at a time, and do not read out the entire process as a task list.
- Explain using the user's business vocabulary, then add the necessary field names. For example, "this task is to be handed to whom, corresponding to
assignedTo”。 - Feedback should be specific: point out whether the requirement scenario is clear, what information is missing, and what the query explains. Avoid fixed praise, exaggerated colloquial language, and asking "do you want to continue" in every paragraph.
- Remember the selected account, scope, current progress, write authorization, and the IDs of created objects. When the user changes direction, switch accordingly, and do not require finishing the current route.
Practical operation rules
Scope and authorization: first reuse the product, project, execution, or demo area specified by the user. "Just try it" itself does not authorize modifying existing records; when a write is needed but the scope is unclear, explain the target object and the proposed changes clearly, then obtain authorization. Operations the user has explicitly requested or approved are executed directly, without repeated confirmation item by item. Processing in batches approved by the user is also fine; there is no requirement to write only one record at a time.
Business status: real tasks transition only when they have actually started or been completed; real bugs transition only when there is a basis for fixing, resolving, or regression. When only explaining the process, just show the commands; when a full lifecycle drill is needed, keep it within demo data the user has authorized, and do not fabricate actual work hours, fixes, or regression conclusions.
Commands and versions: first check as needed zentao <module> <action> --help 's parameters and minimum version.props is a returned object field and does not represent a writable field;my modules such as these require an explicit operation name. Business parameters take precedence with --key=value; use JSON for nested structures and arrays. In this document, <...> must all be replaced with actual values and must not be executed as-is.
Results and retries: continue based on the returned success/failure status and actual ID. When the return value is insufficient to confirm the result, use the detail or list query supported by that module to verify, then tell the user what it was changed to; some modules do not have get. For write requests that time out or return unclear results, first check the current state of the object, and do not blindly retry create, finish, resolve, or delete. When part of a batch fails, report only the items confirmed successful.
Lists and statistics: displaying one page of candidates is fine; when "all", "none", "total", "earliest/latest", or global sorting is needed, cover all pages within the agreed scope.--filter、--sort、--limit only processes the current page, and being empty after filtering does not mean subsequent pages are also empty. Continue paging by the server-side pager, then aggregate locally; when data is incomplete, clearly state the range that has been read. You cannot use --all instead of paging, nor treat mutually exclusive conditions within a single --filter as OR.
When errors occur, still provide viable paths forward
| Error | handling |
|---|---|
| E1001 / E1004 / E1006 | Credentials are missing, invalid, or there is no local account. Have the user run zentao loginin their own interactive terminal, and do not ask for or echo back passwords or Tokens. Environment variables that are already securely injected can be used as described in the overview. |
| E2001 / E2005 | The module or operation is not supported; check the local help and do not guess the interface. |
| E2002 | It may be an object ID, scope, or interface path issue; verify the request and the list, and do not immediately conclude that the object was deleted. |
| E2003 / E2004 / E2007 / E2009 | Check required fields, parameter types, or JSON according to the operation help. |
| E2006 | The current account does not have access. State the specific restricted scope, and you may switch to another object that you have permission to view; insufficient permission cannot be counted as zero records. |
| E2010 | The current ZenTao version does not support this operation. Check the minimum version, use the compatible query in the role file, or continue with an offline explanation. |
| E2011 / E2012 | The service version format or site configuration cannot be recognized; verify the service address and configuration response, and do not bypass the version check to continue writing. |
| E1002 / E5001 / E5002 | Address, connection, timeout, or certificate issue. Explain the actual point of failure and preserve the progress already made; for write requests, verify first as described above and then retry. |
Explain the actual impact and next steps to the user, rather than just restating the error code.
Switching and wrapping up
Respect "stop", "enough", and "switch to another one". At the end, use one or two sentences to review what was actually viewed, created, or modified, distinguishing commands that were only displayed from actions that were executed.
Retain data by default. Only when the user requests cleanup, list the demo objects created this time, their dependencies, and the deletion scope; execute within existing deletion authorization zentao <module> delete <id> --yes, and ask for confirmation again when that scope is not covered. Do not delete something just because its name looks like an example, and do not treat the end of a demo as a reason to close real tasks or Bugs.
References
- overview.md: object relationships, installation and login, MCP, offline help, and readiness checks
- zentao-cli skills: complete commands, secure credentials, data handling, and error handling rules
- zentao-cli repository