@maxiaochao/pi-toolkit 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-24 - v0.7.2
+
+- bundle the calldiff skill (copied verbatim from tanishqkancharla/calldiff, MIT, pinned to a main commit since upstream has no release tags) for call-stack diffs across git commits; the previous v0.7.1 tarball was briefly unavailable on the registry right after publish and is now served normally
+
+## 2026-09-24 - v0.7.1
+
+- bundle the herdr skill (copied verbatim from herdrdev/herdr v0.9.1, Apache-2.0) for driving the Herdr terminal multiplexer from inside a pane; move the tapd CLI skill from .claude/skills into skills/ so it ships with the package
+
 ## 2026-09-23 - v0.7.0
 
 - bundle the pi-worktree skill documenting the CLI for agents (the isolation loop, and which commands need an interactive terminal); fix pi-worktree: the .gitignore check tested a path form that never matched the directory-only .worktrees/ pattern, so the rule was re-appended on the first run in every repo and that self-inflicted edit then triggered the uncommitted-changes prompt

package/README.md

@@ -85,6 +85,12 @@ The bundled `show-me` skill (derived from [humanlayer/skills](https://github.com
 
 The bundled `pdlog` skill decompresses and reads Pudu `.pdlog` proprietary log files, which are binary gibberish when opened directly. It ships a self-contained `ppmd` decompressor (`skills/pdlog/tools/ppmd`, Linux x86-64) and triggers automatically on `.pdlog` files, Pudu logs, ppmd decompression, or logs that open as binary gibberish.
 
+The bundled `herdr` skill (copied verbatim from [herdrdev/herdr](https://github.com/herdrdev/herdr) at tag `v0.9.1`, Apache-2.0) drives Herdr, a terminal multiplexer for coding agents: inspecting workspaces, tabs, and panes, starting and prompting other agents, running commands in background panes without stealing focus, reading pane output, and waiting on agent lifecycle states. It activates only when you explicitly mention Herdr, and only when the agent itself runs inside a Herdr pane (`HERDR_ENV=1`); outside a pane it refuses to control the session and stops.
+
+The bundled `tapd` skill documents the third-party `tapd` CLI ([studyzy/tapd-ai-cli](https://github.com/studyzy/tapd-ai-cli)) for TAPD: requirements, defects, tasks, iterations, wikis, comments, attachments, timesheets, and workflow status maps, including the `--filter` advanced query syntax. It is the CLI's own command reference, so refresh the file with `tapd skill init` when the CLI changes.
+
+The bundled `calldiff` skill (copied verbatim from [tanishqkancharla/calldiff](https://github.com/tanishqkancharla/calldiff), MIT, pinned to a `main` commit because upstream has no release tags) teaches call-stack diffs across git commits: `diff` shows which callees appeared, disappeared, or moved under an entrypoint, `tree` prints one call tree, and `reach` finds call paths between two symbols, all with `--entry`/`--file` entrypoint selection, `--locs` source locations, and `--format json` for agents.
+
 ## Tiny Subagent
 
 The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [

package/skills/calldiff/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanishq Kancharla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/calldiff/NOTICE

@@ -0,0 +1,19 @@
+calldiff Skill
+
+This directory is copied verbatim from the calldiff repository:
+https://github.com/tanishqkancharla/calldiff
+skills/calldiff/SKILL.md at commit 2086f6e4e9ed3c410bba7c94ca3dde77791b1956 (main)
+
+The upstream repository is licensed under the MIT License. A copy of that
+license is included in LICENSE.
+
+Upstream publishes no release tags, so this file is pinned to a main commit
+instead of a tag. The CLI can also write its own copy with `calldiff skills
+add` (to ~/.agents/skills/calldiff/SKILL.md), but that generated file is terser
+than the committed one — it leaves the --entry/--file descriptions empty and
+says 22 languages — so pi-toolkit ships the committed file.
+
+To refresh, copy skills/calldiff/SKILL.md and LICENSE from a newer upstream
+commit and update the commit above. The bundled commands were smoke-tested
+against calldiff 0.5.0 (`diff`, `tree`, `reach`, `--entry`, `--file`,
+`--maxDepth`/`--max-depth`, `--locs`, `--format json`).

package/skills/calldiff/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: calldiff
+description: Diff call stacks across git commits — like git diff, but for who-calls-whom. Shows which callees appeared, disappeared, or moved under an entrypoint across 23 languages (diff, tree, and reach). Use for agentic code review when call flow changed and line diffs bury the shape of the change.
+requires_bin: calldiff
+command: calldiff
+---
+
+# calldiff diff
+
+Diff call stacks between two git trees
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `from` | `string` | no | Before ref (default: HEAD) |
+| `to` | `string` | no | After ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+| `--from` | `string` |  | Left / "before" tree |
+| `--to` | `string` |  | Right / "after" tree |
+
+## Examples
+
+```sh
+# HEAD vs working tree
+calldiff diff
+
+# One ref vs working tree
+calldiff diff main
+
+# Two commits / branches
+calldiff diff abc123 def456
+
+# Force entrypoints
+calldiff diff main feature --entry createAgentSession
+
+# File expands to that file's exports
+calldiff diff main feature --file src/routes.ts
+```
+
+> Semantics match git diff: no refs → HEAD vs worktree; one ref → that vs worktree; two refs → compare those trees.
+
+---
+
+# calldiff reach
+
+Find all call paths from an entrypoint to a target symbol
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ref` | `string` | no | Git ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--to` | `string` |  | Target symbol to reach (functionName or ClassName.method) |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+
+## Examples
+
+```sh
+# Paths in the working tree
+calldiff reach --entry runCheckout --to sendEmail
+
+# Paths at a commit, limited to a directory
+calldiff reach HEAD examples/checkout --entry runCheckout --to sendEmail
+
+# Paths from every export in a file
+calldiff reach --file packages/api/src/flow.ts --to notify
+```
+
+---
+
+# calldiff tree
+
+View a call tree (no diff) for one or more entrypoints
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ref` | `string` | no | Git ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+
+## Examples
+
+```sh
+# Tree from working tree
+calldiff tree --entry createAgentSession
+
+# Tree from a commit
+calldiff tree HEAD --entry PiService.createAgentSession
+
+# Every export in a file
+calldiff tree --file packages/api/src/routes.ts
+```

package/skills/herdr/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/herdr/NOTICE

@@ -0,0 +1,12 @@
+Herdr Skill
+
+This directory is copied verbatim from the Herdr repository:
+https://github.com/herdrdev/herdr (skills/herdr/SKILL.md, tag v0.9.1)
+
+The upstream repository is licensed under Apache License 2.0. A copy of that
+license is included in LICENSE.
+
+pi-toolkit ships the file unchanged, so the installed skill always matches the
+stable Herdr release it was taken from. Upstream updates SKILL.md only on stable
+releases; to refresh it, copy skills/herdr/SKILL.md and LICENSE from a newer
+Herdr tag and update the tag above.

package/skills/herdr/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: herdr
+description: "Control Herdr, a terminal multiplexer for coding agents. Use only when the user explicitly mentions Herdr or asks to use Herdr to inspect or control panes, tabs, workspaces, commands, or another agent. Do not use merely because a task could benefit from a background terminal, delegation, or parallel work. Requires HERDR_ENV=1."
+---
+
+# Herdr
+
+Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI.
+
+Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
+
+```bash
+test "${HERDR_ENV:-}" = 1
+```
+
+If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.
+
+When the check passes, the `herdr` binary in `PATH` talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.
+
+## Learn the current CLI
+
+The installed binary is the authority for command syntax. Start with:
+
+```bash
+herdr --help
+```
+
+Then print the relevant command group by running the group without a subcommand:
+
+```bash
+herdr agent
+herdr pane
+herdr workspace
+herdr tab
+herdr worktree
+herdr terminal
+herdr notification
+herdr integration
+herdr session
+herdr machine
+```
+
+Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute.
+
+Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
+
+## Understand layout, panes, and agents
+
+Choose the primitive that matches the job:
+
+- Workspace, tab, and pane topology organize terminal locations.
+- Pane commands control raw terminals, shells, tests, servers, input, and output.
+- Agent commands control the recognized coding agent currently occupying a pane.
+
+A pane exists whether or not it contains an agent. `agent start` requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret `idle`, `working`, `blocked`, `done`, and `unknown` lifecycle states.
+
+Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced.
+
+`idle` and `done` both mean the agent is ready for input. The CLI/API uses the server's seen state to distinguish them; explicit focus commands mark the target seen, while reads do not. Each TUI client tracks viewed completions independently, so its Done badge can differ from the CLI or another client's badge. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently; it does not prove completion.
+
+## Use IDs and caller context
+
+Public IDs are opaque stable handles:
+
+- workspace: `w1`
+- tab: `w1:t1`
+- pane: `w1:p1`
+
+Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name. The old value is reported as `.result.move_result.previous_pane_id`; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target.
+
+Herdr injects the caller's context into each managed pane:
+
+```bash
+printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
+```
+
+Prefer `--current` when a pane command should target the calling pane. An omitted `pane split` target uses the calling pane when `HERDR_PANE_ID` is available, otherwise the focused pane. Other commands may use the UI-focused pane, which can belong to the user or another client.
+
+Discover live state with:
+
+```bash
+herdr workspace list
+herdr tab list --workspace "$HERDR_WORKSPACE_ID"
+herdr pane current --current
+herdr pane list --workspace "$HERDR_WORKSPACE_ID"
+herdr agent list
+```
+
+Creation responses expose the IDs to use next. `workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
+
+IDs and live agent names are scoped to one server. Two saved SSH machines can both have `w1:p1` or an agent named `reviewer`. Selecting a machine in the TUI does not retarget commands running in your pane: without `--machine`, they still use the inherited session and socket context.
+
+To control a saved SSH machine, use the same global prefix for discovery and every later command:
+
+```bash
+herdr --machine <label-or-id> agent list
+herdr --machine <label-or-id> pane list
+herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000
+```
+
+The selector must be an enabled saved profile ID or a unique, case-sensitive label, not an arbitrary SSH hostname. Commands use that profile's remote session without an open TUI. Do not combine `--machine` with `--session` or `--remote`. Discover IDs on that machine; inherited local IDs and `--current` do not identify remote panes.
+
+Both installations must support machine API forwarding, and the remote server must already be running and API-compatible. Forwarding never installs, starts, or restarts a server and never falls back to Local. Local configuration, session management, installation commands, and interactive attachment are not forwarded. Remote worktree paths must be absolute, `~`, or start with `~/`; plugin link paths must be absolute. A connection failure does not prove a mutation was not applied: inspect remote state before retrying.
+
+`herdr machine list` lists saved connection profiles, not a cross-machine pane inventory; add `--json` for scripts. Only add, remove, enable, or disable profiles when the user asks. Removing a profile disconnects the client but does not stop remote sessions. Adding a machine uses the remote default session unless `--remote-session` is explicitly supplied. Setup asks before stopping an incompatible server and defaults to No; do not approve replacement without the user's consent. Experimental handoff is not part of `machine add`.
+
+## Start and coordinate an agent
+
+Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.
+
+Honor a direction requested by the user. Otherwise inspect the caller pane:
+
+```bash
+herdr pane layout --pane "$HERDR_PANE_ID"
+```
+
+Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory:
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+```
+
+Replace `right` with `down` when appropriate. Read the new pane ID from `.result.pane.pane_id`.
+
+An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name:
+
+```bash
+herdr agent start reviewer --kind codex --pane <returned-pane-id>
+```
+
+Use the kind requested by the user. Run `herdr agent` to inspect the installed kind list and options. Pass native agent arguments only after `--`:
+
+```bash
+herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
+```
+
+A successful `agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. If the agent is blocked during startup, the command returns `agent_not_ready` immediately but keeps the name available for `agent read` and `agent send-keys`. Wait until the agent becomes idle before prompting it. Startup defaults to a 30-second timeout.
+
+Submit work through the agent surface:
+
+```bash
+herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
+```
+
+`agent prompt` honors the pane's live bracketed-paste mode and sends text followed by encoded Enter as one ordered submission. It reports successful submission only after both have been written; that alone does not prove the agent started a turn. For Codex on Windows, Herdr sends a paste boundary before Enter so submission does not depend on prompt size. It rejects an agent already waiting at an approval or question dialog with `agent_blocked` before sending any input. Inspect the blocked UI and ask the user before answering it. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
+
+With `--wait`, a prompt sent from a non-working state must produce observed `working` or `blocked` activity. After submission, Herdr waits up to five seconds for that activity; unrelated `idle`, `done`, or session changes do not satisfy this gate. It returns `agent_prompt_stalled` if no activity is observed, or `timeout` if the caller's timeout expires first. The caller timeout includes submission time. Without a timeout, the settled-state wait is indefinite after activity is observed. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
+
+Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input:
+
+```bash
+herdr agent wait reviewer --until blocked --timeout 120000
+```
+
+Without `--until`, standalone `agent wait` uses the same settled-state defaults as `agent prompt --wait`.
+
+Use logical keys for interactive agent UI controls:
+
+```bash
+herdr agent send-keys reviewer esc
+herdr agent send-keys reviewer ctrl+c
+```
+
+Herdr validates all keys before writing any bytes. Read the result through the resolved agent:
+
+```bash
+herdr agent get reviewer
+herdr agent read reviewer --source recent-unwrapped --lines 120
+```
+
+If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before deciding what input to send. A timeout or stalled response does not prove the prompt was never delivered; do not blindly submit it again. Use the pane surface only when raw terminal control is intentional.
+
+## Run an ordinary command in another pane
+
+Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+```
+
+Read the new pane ID from `.result.pane.pane_id`, then run and inspect the command:
+
+```bash
+herdr pane run <returned-pane-id> "just test"
+herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
+herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
+```
+
+`pane run` atomically sends command text and Enter. `pane wait-output` searches the selected snapshot immediately, so output that already exists can match. Use `--match <text>` for a literal substring or `--regex <pattern>` for a Rust regular expression. Omitting `--timeout` allows an indefinite wait.
+
+Use the read source that matches the task:
+
+- `visible`: the currently rendered viewport.
+- `recent`: recent rendered output, including soft wraps.
+- `recent-unwrapped`: recent output with soft wraps joined; prefer it for logs and transcripts.
+- `detection`: the plain-text bottom-buffer snapshot used for agent detection.
+
+Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text.
+
+`--lines` asks Herdr for more rows from the pane's available screen and host scrollback. Alternate-screen rows do not enter ordinary host scrollback. For supported idle agents, Herdr can collect application-owned history and restore the viewport afterward, but not every application or response can be recovered this way.
+
+If a larger recent read still does not reveal the completed response, ask the agent to write it as Markdown in a temporary directory and reply only with the file path, then read that file on the same machine. Use this only as a fallback; do not request file output in the initial prompt.
+
+## Safety and coordination rules
+
+- Use `--no-focus` for background work unless the user asked to switch context.
+- Use `--current`, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane.
+- Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
+- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked. `workspace close --group` closes the primary workspace and its linked worktree workspaces; never add it merely to bypass `workspace_group_close_required`.
+- Use `--trust-repository` only after the user has verified the repository. It grants per-request Git trust; it is not a routine retry for a failed worktree command.
+- Client and server versions can differ after an update. Check `herdr status` before relying on new server features. A missing method is not permission to stop or upgrade a server.
+- Never run `herdr server stop` from an active session unless the user explicitly intends to stop the server and its pane processes.
+- Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
+- CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.

package/skills/tapd/SKILL.md

@@ -0,0 +1,487 @@
+---
+name: tapd
+description: TAPD操作，涉及需求，缺陷，任务，Wiki等。tapd.cn快捷查询：tapd url <url>
+---
+
+面向 AI Agent 的 TAPD 命令行工具。通过 `tapd` 命令与 TAPD 平台交互，所有输出针对最小 token 消耗优化。
+
+## 安装
+
+```bash
+go install github.com/studyzy/tapd-ai-cli/cmd/tapd@latest
+```
+
+## 认证
+
+```bash
+# Access Token（推荐）
+export TAPD_ACCESS_TOKEN=<your_token>
+
+# 或交互式登录持久化凭据
+tapd auth login
+```
+
+凭据优先级：CLI flags > 环境变量 > `./.tapd.json` > `~/.tapd.json`
+
+## 高级过滤（--filter）
+
+所有 `list` 命令均支持 `--filter` 标志，可重复使用，直接透传 TAPD OpenAPI 的高级查询语法：
+
+```bash
+tapd story list --filter "name=LIKE<登录>" --filter "status=EQ<已实现>"
+tapd bug list --filter "created=>2024-01-01" --filter "custom_field_one=EQ<高优先级>"
+tapd task list --filter "owner=USER_OR<张三|李四>"
+```
+
+### 支持的操作符
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `LIKE<value>` | 模糊匹配 | `name=LIKE<登录>` |
+| `EQ<value>` | 精确匹配 | `status=EQ<已实现>` |
+| `NOT_EQ<value>` | 不等于 | `status=NOT_EQ<已关闭>` |
+| `LIKE_OR<v1\|v2>` | 模糊匹配多个值（OR） | `name=LIKE_OR<登录\|注册>` |
+| `CONTAINS<v1\|v2>` | 包含所有值（AND） | `label=CONTAINS<前端\|高优>` |
+| `CONTAINS_OR<v1\|v2\|v3>` | 包含任一值（OR） | `status=CONTAINS_OR<开发中\|测试中>` |
+| `USER_OR<u1\|u2>` | 多人查询（OR） | `owner=USER_OR<张三\|李四>` |
+| `>` / `<` | 大于/小于（时间/数值） | `created=>2024-01-01` |
+| `~` | 时间范围 | `created=2024-01-01~2024-12-31` |
+| `\|` | 多值 OR | `status=开发中\|测试中` |
+| `<>` | 不等于（简写） | `status=<>已关闭` |
+
+### 适用字段
+
+- 标准字段（name/title/status/owner/created 等）
+- 自定义字段（custom_field_one、custom_field_two 等，用 `custom-field list --entity-type stories` 查看可用字段）
+
+`--filter` 与已有标志（`--status`、`--owner` 等）可组合使用，参数会合并传递给 API。
+
+## 命令参考
+
+### url — 根据 TAPD URL 查询对应条目详情（支持需求、缺陷、任务、Wiki）
+
+```bash
+tapd url <url>  # 根据 TAPD URL 查询对应条目详情（支持需求、缺陷、任务、Wiki）
+```
+
+### story — 需求管理
+
+```bash
+tapd story count [--status=<用 workflow status-map 查询可用值>]  # 查询需求数量
+tapd story create [--begin=<格式：2006-01-02>] [--category-id] [--cc] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--developer] [--due=<格式：2006-01-02>] [--iteration-id] [--label=<多个以竖线分隔>] --name=<必需> [--owner] [--parent-id=<创建子需求时使用>] [--priority=<High/Middle/Low/Nice To Have>]  # 创建需求
+tapd story list [--category-id] [--fields=<逗号分隔，如 "id,name,status,module">] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--iteration-id] [--label] [--limit=10] [--name] [--order=<如 "created desc">] [--owner] [--page=1] [--priority] [--status=<用 workflow status-map 查询可用值>]  # 查询需求列表
+tapd story show <story_id>  # 查看需求详情
+tapd story todo [--limit=10] [--page=1]  # 查询当前用户待办需求
+tapd story update <story_id> [--begin=<格式：2006-01-02>] [--category-id] [--cc] [--current-user] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--developer] [--due=<格式：2006-01-02>] [--iteration-id] [--label=<多个以竖线分隔>] [--name] [--owner] [--priority=<High/Middle/Low/Nice To Have>] [--status=<用 workflow status-map 查询可用值>]  # 更新需求
+```
+
+### comment — 评论管理
+
+```bash
+tapd comment add [--author=<可选，默认使用当前登录用户>] [--description=<text>|--file=<path>|stdin] --entry-id=<必需> --entry-type=<stories|bug|bug_remark|tasks|wiki> [--reply-id=<可选>]  # 添加评论
+tapd comment count [--entry-id] [--entry-type=<stories|bug|bug_remark|tasks|wiki>]  # 查询评论数量
+tapd comment list [--author] [--entry-id] [--entry-type=<stories|bug|bug_remark|tasks|wiki>] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--order=<如 created desc>] [--page=1]  # 查询评论列表
+tapd comment update <comment_id> [--description=<text>|--file=<path>|stdin]  # 更新评论
+```
+
+### task — 任务管理
+
+```bash
+tapd task count [--status=<open/progressing/done>]  # 查询任务数量
+tapd task create [--begin=<格式：2006-01-02>] [--cc] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--due=<格式：2006-01-02>] [--effort] [--iteration-id] [--label=<多个以竖线分隔>] --name=<必需> [--owner] [--priority=<High/Middle/Low/Nice To Have>] [--story-id]  # 创建任务
+tapd task list [--fields=<逗号分隔，如 "id,name,status,module">] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--iteration-id] [--label] [--limit=10] [--name] [--order=<如 "created desc">] [--owner] [--page=1] [--priority] [--status=<open/progressing/done>] [--story-id]  # 查询任务列表
+tapd task show <task_id>  # 查看任务详情
+tapd task todo [--limit=10] [--page=1]  # 查询当前用户待办任务
+tapd task update <task_id> [--begin=<格式：2006-01-02>] [--cc] [--current-user] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--due=<格式：2006-01-02>] [--effort] [--iteration-id] [--label=<多个以竖线分隔>] [--name] [--owner] [--priority=<High/Middle/Low/Nice To Have>] [--status=<open/progressing/done>] [--story-id]  # 更新任务
+```
+
+### bug — 缺陷管理
+
+```bash
+tapd bug count [--status=<用 workflow status-map 查询可用值>]  # 查询缺陷数量
+tapd bug create [--begin=<格式：2006-01-02>] [--cc] [--current-owner] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--due=<格式：2006-01-02>] [--iteration-id] [--label=<多个以竖线分隔>] [--module] [--priority=<urgent/high/medium/low/insignificant>] [--severity=<fatal/serious/normal/prompt/advice>] --title=<必需>  # 创建缺陷
+tapd bug list [--fields=<逗号分隔，如 "id,title,status,module">] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--iteration-id] [--label] [--limit=10] [--module] [--order=<如 "created desc">] [--owner] [--page=1] [--priority=<urgent/high/medium/low/insignificant>] [--reporter] [--severity=<fatal/serious/normal/prompt/advice>] [--status=<用 workflow status-map 查询可用值>] [--title]  # 查询缺陷列表
+tapd bug show <bug_id>  # 查看缺陷详情
+tapd bug todo [--limit=10] [--page=1]  # 查询当前用户待办缺陷
+tapd bug update <bug_id> [--begin=<格式：2006-01-02>] [--cc] [--current-user] [--custom-field=<可重复，格式：key=value>] [--description=<text>|--file=<path>|stdin] [--due=<格式：2006-01-02>] [--label=<多个以竖线分隔>] [--module] [--owner=<current_owner>] [--priority=<urgent/high/medium/low/insignificant>] [--resolution] [--severity=<fatal/serious/normal/prompt/advice>] [--status=<用 workflow status-map 查询可用值>] [--title]  # 更新缺陷
+```
+
+### attachment — 附件管理
+
+```bash
+tapd attachment list --entry-id=<必需> [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--page=1] [--type=<story|bug|task>]  # 查询条目的附件列表
+```
+
+### auth — 认证管理
+
+```bash
+tapd auth login [--local]  # 登录并持久化凭据到配置文件
+```
+
+### category — 需求分类管理
+
+```bash
+tapd category list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--name=<支持模糊匹配，如 %搜索词%>]  # 查询需求分类列表
+```
+
+### commit-msg — 源码提交关键字管理
+
+```bash
+tapd commit-msg get --object-id=<必需> [--type=<story|task|bug>]  # 获取源码提交关键字（用于关联 git commit 到 TAPD 条目）
+```
+
+### custom-field — 自定义字段管理
+
+```bash
+tapd custom-field list --entity-type=<stories|tasks|iterations|tcases> [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>]  # 获取自定义字段配置
+```
+
+### image — 图片管理
+
+```bash
+tapd image get --image-path=<必需，从条目描述中获取>  # 获取图片下载链接
+```
+
+### iteration — 迭代管理
+
+```bash
+tapd iteration count [--status=<open/done>]  # 查询迭代数量
+tapd iteration create --creator=<必需> [--description] --enddate=<必需，格式：2006-01-02> [--label=<多个以竖线分隔>] --name=<必需> [--parent-id] --startdate=<必需，格式：2006-01-02> [--status=<open/done，默认 open>]  # 创建迭代
+tapd iteration list [--creator] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--name] [--order=<如 "created desc">] [--page=1] [--status=<open/done>]  # 查询迭代列表
+tapd iteration update <iteration_id> --current-user=<必需> [--description] [--enddate=<格式：2006-01-02>] [--name] [--startdate=<格式：2006-01-02>] [--status=<open/done>]  # 更新迭代
+```
+
+### qiwei — 企业微信消息管理
+
+```bash
+tapd qiwei send --msg=<Markdown 格式> --webhook=<必需，也可通过 BOT_URL 环境变量设置>  # 发送消息到企业微信群（通过机器人 Webhook）
+```
+
+### relation — 关联关系管理
+
+```bash
+tapd relation bugs --story-id=<必需>  # 查询需求关联的缺陷
+tapd relation create --source-id=<必需> --source-type=<story|bug|task> --target-id=<必需> --target-type=<story|bug|task>  # 创建实体关联关系
+```
+
+### release — 发布计划管理
+
+```bash
+tapd release list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>]  # 查询发布计划列表
+```
+
+### skill — AI Coding 工具 Skill 管理
+
+```bash
+tapd skill init  # 为 AI Coding 工具生成 TAPD CLI 的 SKILL.md
+```
+
+### story-field — 需求字段信息
+
+```bash
+tapd story-field info  # 获取需求字段及候选值
+tapd story-field label  # 获取需求字段中英文名
+```
+
+### tcase — 测试用例管理
+
+```bash
+tapd tcase batch-create --tcases=<必需>  # 批量创建测试用例
+tapd tcase create [--creator] [--expectation] [--id=<有值时为更新，无值时为创建>] --name=<创建时必需> [--precondition] [--priority=<high/medium/low>] [--status=<updating|abandon|normal>] [--steps] [--type=<functional/performance/other>]  # 创建或更新测试用例
+tapd tcase list [--creator] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--page=1] [--priority=<high/medium/low>] [--status=<updating|abandon|normal>]  # 查询测试用例列表
+```
+
+### timesheet — 花费工时管理
+
+```bash
+tapd timesheet add --entity-id=<必需> --entity-type=<story|task|bug> [--memo=<可选>] [--owner=<可选，默认当前用户>] [--spentdate=<可选>] [--timeremain=<可选>] --timespent=<必需>  # 填写花费工时
+tapd timesheet list [--entity-id] [--entity-type=<story|task|bug>] [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--owner] [--page=1]  # 查询花费工时列表
+tapd timesheet update <timesheet_id> [--memo] [--timeremain] [--timespent]  # 更新花费工时
+```
+
+### wiki — Wiki 文档管理
+
+```bash
+tapd wiki create [--content=<Markdown 格式>] --creator=<必需> [--file] --name=<必需> [--note] [--parent-wiki-id]  # 创建 Wiki 文档
+tapd wiki list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--name] [--page=1]  # 查询 Wiki 文档列表
+tapd wiki show <wiki_id>  # 查看 Wiki 文档详情
+tapd wiki update <wiki_id> [--content=<Markdown 格式>] [--file] [--name] [--note] [--parent-wiki-id]  # 更新 Wiki 文档
+```
+
+### workflow — 工作流状态管理
+
+```bash
+tapd workflow last-steps --system=<story|bug> [--workitem-type-id]  # 获取结束状态
+tapd workflow status-map --system=<story|bug> --workitem-type-id=<必需>  # 获取状态中英文映射
+tapd workflow transitions --system=<story|bug> --workitem-type-id=<必需>  # 获取状态流转规则
+```
+
+### workitem-type — 需求类别管理
+
+```bash
+tapd workitem-type list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=30] [--name] [--page=1]  # 获取需求类别列表
+```
+
+### workspace — 工作区管理
+
+```bash
+tapd workspace info  # 查看当前工作区详情
+tapd workspace list  # 列出参与的项目
+tapd workspace switch <workspace_id>  # 切换当前工作区（写入当前目录 .tapd.json）
+```
+
+### story — 需求管理
+
+```bash
+tapd story batch-update [--current-user] --ids=<逗号分隔> [--owner] [--priority] [--status]  # 批量更新需求
+tapd story copy <story_id> [--current-user]  # 复制需求
+tapd story link add --story-id=<必需> --target-id=<必需>  # 创建需求关联关系
+tapd story link list --story-id=<必需>  # 查询需求关联关系
+tapd story link remove --story-id=<必需> --target-id=<必需>  # 解除需求关联关系
+tapd story removed [--limit=<默认 30，最大 200>] [--page]  # 查询回收站中的需求
+tapd story template list [--workitem-type-id]  # 查询需求模板列表
+tapd story time-relation delete --current-user=<必需> --related-id=<必需> --story-id=<必需>  # 删除需求前后置关系
+tapd story time-relation list --story-id=<必需>  # 查询需求前后置关系
+```
+
+### task — 任务管理
+
+```bash
+tapd task batch-update [--current-user] --ids=<逗号分隔> [--owner] [--status]  # 批量更新任务
+tapd task removed [--limit=<默认 30，最大 200>] [--page]  # 查询回收站中的任务
+```
+
+### bug — 缺陷管理
+
+```bash
+tapd bug batch-update [--current-user] --ids=<逗号分隔> [--owner] [--status]  # 批量更新缺陷
+tapd bug copy <bug_id> [--current-user]  # 复制缺陷
+tapd bug link add --bug-id=<必需> --target-bug-ids=<多个以逗号分隔>  # 创建缺陷关联关系
+tapd bug link list --bug-id=<必需>  # 查询缺陷关联关系
+tapd bug link remove --bug-id=<必需> --link-ids=<多个以逗号分隔>  # 取消缺陷关联关系
+tapd bug related-stories --bug-id=<必需>  # 查询缺陷关联的需求
+tapd bug removed [--limit=<默认 30，最大 200>] [--page]  # 查询回收站中的缺陷
+tapd bug template list  # 查询缺陷模板列表
+```
+
+### app-version — 版本管理
+
+```bash
+tapd app-version count  # 查询版本数量
+tapd app-version create --creator=<必需> [--description] --name=<必需>  # 创建版本
+tapd app-version list [--limit=30] [--name] [--page=1] [--status=<Closed/Unclosed>]  # 查询版本列表
+tapd app-version update <version_id> [--description] --modifier=<必需> [--name]  # 更新版本
+```
+
+### attachment — 附件管理
+
+```bash
+tapd attachment download --id=<必需>  # 获取附件下载链接
+tapd attachment upload --custom-field=<必需> --entry-id=<必需> --file=<必需> --type=<如 story_custom_field>  # 上传附件
+```
+
+### baseline — 基线管理
+
+```bash
+tapd baseline count  # 查询基线数量
+tapd baseline create [--description] [--name] [--version-id]  # 创建基线
+tapd baseline list [--limit=30] [--name] [--page=1]  # 查询基线列表
+tapd baseline update <baseline_id> [--description] [--name]  # 更新基线
+```
+
+### category — 需求分类管理
+
+```bash
+tapd category count  # 查询需求分类数量
+tapd category create [--description] --name=<必需> [--parent-id]  # 创建需求分类
+tapd category update <category_id> [--description] [--name]  # 更新需求分类
+```
+
+### change — 变更历史管理
+
+```bash
+tapd change count [--entity-id] --type=<story|bug|task>  # 查询变更数量
+tapd change list --entity-id=<迭代变更时必需> [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--page=1] --type=<story|bug|task|iteration>  # 查询变更历史
+```
+
+### feature — 特性管理
+
+```bash
+tapd feature count  # 查询特性数量
+tapd feature create [--description] --name=<必需>  # 创建特性
+tapd feature list [--limit=30] [--name] [--page=1]  # 查询特性列表
+tapd feature update <feature_id> [--description] [--name] [--owner]  # 更新特性
+```
+
+### image — 图片管理
+
+```bash
+tapd image upload --custom-field=<必需> --entry-id=<必需> --file=<必需，≤15MB>  # 以 base64 方式上传图片
+```
+
+### iteration — 迭代管理
+
+```bash
+tapd iteration lock <iteration_id> [--lock-types=<__ALL_STORY__/__ALL_BUG__，多个以逗号分隔>]  # 锁定迭代
+tapd iteration unlock <iteration_id>  # 解锁迭代
+```
+
+### label — 标签管理
+
+```bash
+tapd label add [--color=<1|2|3|4>] --name=<必需，不能包含英文竖线>  # 创建标签
+tapd label count [--name=<支持模糊匹配>]  # 查询标签数量
+tapd label list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=<最大 200>] [--name=<支持模糊匹配>] [--page=1]  # 查询标签列表
+tapd label update <label_id> [--color=<1|2|3|4>]  # 更新标签
+```
+
+### launch — 发布评审管理
+
+```bash
+tapd launch count [--creator] [--id] [--release-type] [--status=<initial/auditing/signing/sign_completed/finished；初始化/评审中/待签发/签发结束/发布结束>] [--title]  # 查询发布评审数量
+tapd launch create [--alias-field=[]] [--archived-by] [--baseline] [--cc] [--creator=<默认当前用户>] [--custom-field=[]] [--release-model] [--release-type] [--roadmap-version] [--signed-by] --template-id=<必需> [--title] [--version-type]  # 创建发布评审
+tapd launch fields  # 查询发布评审自定义字段配置
+tapd launch list [--creator] [--fields=<逗号分隔>] [--id] [--limit=10] [--page=1] [--release-type] [--status=<initial/auditing/signing/sign_completed/finished；初始化/评审中/待签发/签发结束/发布结束>] [--title]  # 查询发布评审列表
+tapd launch logs --id=<必需>  # 查询发布评审活动日志
+tapd launch templates  # 查询发布评审模板
+tapd launch update <launch_form_id> [--alias-field=[]] [--archived-by] [--baseline] [--cc] [--change-notifier] [--change-type] [--custom-field=[]] [--release-comment] [--release-model] [--release-result=<release_success/release_fail>] [--release-type] [--remark] [--roadmap-version] [--signed-by] [--signer-comment] [--status=<initial/auditing/signing/sign_completed/finished；初始化/评审中/待签发/签发结束/发布结束>] [--title] [--version-type]  # 更新发布评审
+```
+
+### module — 模块管理
+
+```bash
+tapd module count  # 查询模块数量
+tapd module create [--description] --name=<必需> [--owner]  # 创建模块
+tapd module list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=30] [--name] [--page=1]  # 查询模块列表
+tapd module update <module_id> [--description] [--name] [--owner]  # 更新模块
+```
+
+### release — 发布计划管理
+
+```bash
+tapd release count  # 查询发布计划数量
+tapd release create [--description] --enddate=<格式：2006-01-02> --name=<必需> --startdate=<格式：2006-01-02>  # 创建发布计划
+tapd release update <release_id> [--enddate=<格式：2006-01-02>] [--name] [--startdate=<格式：2006-01-02>] [--status]  # 更新发布计划
+```
+
+### report — 项目报告管理
+
+```bash
+tapd report list [--limit=30] [--page=1]  # 查询项目报告列表
+```
+
+### source — 源码提交关联管理
+
+```bash
+tapd source add [--author] [--commit-id] [--commit-time] [--commit-url] [--files=<逗号分隔>] --message=<必需> [--repo] [--repo-id] [--web-url]  # 保存 Commit 提交数据
+tapd source list --object-id=<必需> --type=<必需>  # 获取 GIT 关联提交数据
+tapd source objects --commit-id=<必需，支持逗号分隔多个> --type=<必需>  # 获取指定 commit 关联的 TAPD 业务对象
+```
+
+### tcase — 测试用例管理
+
+```bash
+tapd tcase update <tcase_id> [--expectation] [--name] [--precondition] [--priority=<high/medium/low>] [--status=<updating|abandon|normal>] [--steps]  # 更新测试用例
+```
+
+### test-plan — 测试计划管理
+
+```bash
+tapd test-plan bugs --id=<必需>  # 查询测试计划关联的缺陷
+tapd test-plan count [--status]  # 查询测试计划数量
+tapd test-plan create [--description] [--end-date] [--iteration-id] --name=<必需> [--owner] [--start-date]  # 创建测试计划
+tapd test-plan list [--filter=<可重复，格式：field=OP<value>，支持 LIKE/EQ/CONTAINS 等 OpenAPI 特殊查询语法>] [--limit=10] [--name] [--page=1] [--status]  # 查询测试计划列表
+tapd test-plan progress --id=<必需>  # 查询测试计划执行进度
+tapd test-plan tcases --id=<必需> [--limit=30] [--page=1]  # 查询测试计划关联的测试用例
+tapd test-plan update <test_plan_id> [--description] [--name] [--owner] [--status]  # 更新测试计划
+```
+
+### testx — TAPD testx 模块（用例/计划/报告/设计）
+
+```bash
+tapd testx case batch-bind-bug --case-uid=<必填> [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 批量关联 Bug
+tapd testx case batch-create [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 批量创建用例
+tapd testx case batch-unbind-bug --case-uid=<必填> [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 批量解绑 Bug
+tapd testx case batch-update [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 批量更新用例
+tapd testx case create [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 创建用例
+tapd testx case folder-create [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 创建用例目录
+tapd testx case folder-update [--data=<用于填充 body 字段>] --folder-uid=<必填> --repo-uid=<必填> --repo-version-uid=<必填>  # 更新用例目录
+tapd testx case list-bug --case-uid=<必填> [--data=<用于填充 body 字段>] [--handler] [--limit] [--name] [--offset] [--priority] --repo-uid=<必填> --repo-version-uid=<必填> [--status]  # 用例关联缺陷列表
+tapd testx case list-execution --case-uid=<必填> [--data=<用于填充 body 字段>] [--limit] [--offset] [--ordering] --repo-uid=<必填> --repo-version-uid=<必填>  # 用例执行记录
+tapd testx case list-history --case-uid=<必填> [--data=<用于填充 body 字段>] [--limit] [--offset] --repo-uid=<必填> --repo-version-uid=<必填>  # 用例变更历史
+tapd testx case list-review --case-uid=<必填> [--data=<用于填充 body 字段>] [--is-last-review] [--limit] [--main-uid] [--offset] --repo-uid=<必填> --repo-version-uid=<必填> [--source] [--source-kind] [--source-uid]  # 用例评审记录
+tapd testx case list-template [--data=<用于填充 body 字段>]  # 用例模板列表
+tapd testx case repo-create [--data=<用于填充 body 字段>]  # 创建用例仓库
+tapd testx case repo-get [--data=<用于填充 body 字段>] --repo-uid=<必填>  # 获取用例仓库
+tapd testx case repo-list [--data=<用于填充 body 字段>] [--limit] [--offset] [--reverse] [--search]  # 获取用例仓库列表
+tapd testx case repo-update [--data=<用于填充 body 字段>] --repo-uid=<必填>  # 更新用例仓库
+tapd testx case search [--data=<用于填充 body 字段>] [--limit] [--offset] --repo-uid=<必填> --repo-version-uid=<必填>  # 搜索用例
+tapd testx case update --case-uid=<必填> [--data=<用于填充 body 字段>] --repo-uid=<必填> --repo-version-uid=<必填>  # 更新用例
+tapd testx design list-labels [--design-uid] [--kind] [--name]  # 测试设计标签
+tapd testx design list-stat [--data=<用于填充 body 字段>]  # 测试设计统计
+tapd testx design search [--data=<用于填充 body 字段>]  # 搜索测试设计
+tapd testx plan batch-archive [--data=<用于填充 body 字段>]  # 批量归档计划
+tapd testx plan batch-update-case [--data=<用于填充 body 字段>] --plan-uid=<必填>  # 批量更新计划用例
+tapd testx plan bind-bug [--data=<用于填充 body 字段>] --plan-uid=<必填>  # 计划用例批量关联缺陷
+tapd testx plan bug-statistics [--data=<用于填充 body 字段>]  # 计划关联缺陷统计
+tapd testx plan create [--data=<用于填充 body 字段>]  # 创建计划
+tapd testx plan folder-children [--data=<用于填充 body 字段>] [--item-type] [--name] [--plan-archive] [--plan-states=<可重复>] --uid=<必填> [--with-ancestor] [--with-descendant]  # 获取目录子信息
+tapd testx plan folder-create [--data=<用于填充 body 字段>]  # 创建计划目录
+tapd testx plan folder-update [--data=<用于填充 body 字段>] --folder-uid=<必填>  # 更新计划目录
+tapd testx plan get [--data=<用于填充 body 字段>] --uid=<必填> [--with-detail] [--with-statistic]  # 获取计划详情
+tapd testx plan list [--data=<用于填充 body 字段>] --folder-uid=<必填>  # 目录下计划列表
+tapd testx plan list-bugs [--bug-id] [--data=<用于填充 body 字段>] [--limit] [--offset] --plan-uid=<必填> [--related-types=<多个用逗号分隔>] [--status] [--summary]  # 计划关联缺陷列表
+tapd testx plan list-case-events --case-uid=<必填> [--data=<用于填充 body 字段>] [--limit] [--offset] --plan-uid=<必填>  # 计划下用例事件
+tapd testx plan list-case-issues --case-uid=<必填> [--data=<用于填充 body 字段>] --issue-type=<必填> [--limit] [--offset] --plan-uid=<必填>  # 计划下用例关联缺陷
+tapd testx plan list-cases [--data=<用于填充 body 字段>] --uid=<必填>  # 计划下用例列表
+tapd testx plan list-history [--data=<用于填充 body 字段>] [--limit] [--offset] --plan-uid=<必填>  # 计划变更历史
+tapd testx plan list-stories [--data=<用于填充 body 字段>] [--limit] [--offset] --plan-uid=<必填>  # 计划关联需求列表
+tapd testx plan list-templates [--data=<用于填充 body 字段>] [--limit] [--offset]  # 计划模板列表
+tapd testx plan statistics [--data=<用于填充 body 字段>]  # 计划统计信息
+tapd testx plan unbind-bug --case-uid=<必填> [--data=<用于填充 body 字段>] --issue-uid=<必填> --plan-uid=<必填>  # 移除计划用例关联缺陷
+tapd testx plan update [--data=<用于填充 body 字段>] --uid=<必填>  # 更新计划
+tapd testx plan update-target-scope [--data=<用于填充 body 字段>] --uid=<必填>  # 更新计划范围目标
+tapd testx report get --uid=<必填>  # 报告详情
+tapd testx report get-data --report-uid=<必填> --template-uid=<必填>  # 报告详情数据
+tapd testx report list [--creators=<逗号分隔>] [--end-at] [--limit] [--offset] [--plan-uids=<逗号分隔>] [--search] [--source] [--sources=<逗号分隔>] [--start-at] [--template-uid] [--with-associated]  # 报告列表
+tapd testx report list-templates [--limit] [--offset]  # 报告模板列表
+```
+
+### timesheet — 花费工时管理
+
+```bash
+tapd timesheet count [--entity-id] [--entity-type=<story|task|bug>] [--owner]  # 查询花费工时数量
+tapd timesheet delete --cost-ids=<多个以逗号分隔> --entity-id=<必需> --entity-type=<story|task|bug>  # 删除花费工时
+```
+
+### user — 用户信息管理
+
+```bash
+tapd user info  # 获取当前用户信息
+tapd user views [--type=<目前只支持 story>]  # 获取用户视图列表
+```
+
+### wiki — Wiki 文档管理
+
+```bash
+tapd wiki count  # 查询 Wiki 文档数量
+```
+
+### workflow — 工作流状态管理
+
+```bash
+tapd workflow first-step --system=<story|bug> [--workitem-type-id]  # 获取工作流起始状态
+tapd workflow list --system=<story|bug> [--workitem-type-id]  # 获取工作流列表
+```
+
+### workspace — 工作区管理
+
+```bash
+tapd workspace documents [--limit=<默认 30，最大 200>] [--page]  # 获取项目文档列表
+tapd workspace members add --nick=<必需> [--role-ids=<逗号分隔>]  # 添加项目成员
+tapd workspace roles  # 查看用户组 ID 对照关系
+tapd workspace settings --type=<必需，如 is_enabled_story_category / workspace_metrology>  # 获取项目配置开关
+tapd workspace sub-workspaces  # 获取子项目信息
+tapd workspace users  # 查看项目成员列表
+```
+