npm - @maxiaochao/pi-toolkit - Versions diffs - 0.10.13 → 0.10.15 - Mend

@maxiaochao/pi-toolkit 0.10.13 → 0.10.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +8 -0
package/README.md +1 -1
package/package.json +1 -1
package/packages/worktree/CHANGELOG.md +4 -0
package/packages/worktree/extensions/worktree.ts +2 -2
package/packages/worktree/package.json +1 -1
package/packages/worktree/tests/extension.test.mjs +2 -2
package/skills/tapd/SKILL.md +65 -467
package/skills/tapd/references/attachment-download.md +46 -0
package/skills/tapd/scripts/extract-download-url.mjs +12 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,11 @@
+## 2026-10-09 - v0.10.15
+- redesign the TAPD skill around executable workflows, explicit workspace and JSON contracts, and safe attachment handling
+## 2026-10-09 - v0.10.14
+- bundle worktree v0.3.2: continue Agent tasks automatically after switching into a worktree
 ## 2026-10-09 - v0.10.13
 - bundle worktree v0.3.1: show a persistent in-conversation confirmation after switching worktrees

package/README.md CHANGED Viewed

@@ -87,7 +87,7 @@ bash scripts/install.sh
 | `pdlog` | Decompress and inspect Pudu `.pdlog` files |
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
 | `agent-team` | Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents |
-| `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
+| `tapd` | Investigate and operate on TAPD items with workspace, evidence, and safe-download guardrails |
 Package-specific skills, such as `pi-worktree`, are documented by their child package.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.13",
+  "version": "0.10.15",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/worktree/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,9 @@
 # Changelog
+## 2026-10-09 - v0.3.2
+- continue Agent tasks automatically after switching into a worktree
 ## 2026-10-09 - v0.3.1
 - show a persistent in-conversation confirmation after switching worktrees

package/packages/worktree/extensions/worktree.ts CHANGED Viewed

@@ -165,10 +165,10 @@ export default function worktreeExtension(pi: ExtensionAPI) {
             const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
             await next.sendMessage({
               customType: "worktree-switch",
-              content: `✓ 已进入 worktree：${prepared.path}\nBranch: ${prepared.branch}${dirtyNote}`,
+              content: `✓ 已进入 worktree：${prepared.path}\nBranch: ${prepared.branch}${dirtyNote}\n\n在worktree继续任务`,
               display: true,
               details: prepared,
-            }, { triggerTurn: false });
+            }, { triggerTurn: true, deliverAs: "followUp" });
           },
         });
       } catch (error) {

package/packages/worktree/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-worktree",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Git worktree CLI, Pi extension, and skill for isolated coding tasks.",
   "type": "module",
   "keywords": [

package/packages/worktree/tests/extension.test.mjs CHANGED Viewed

@@ -124,11 +124,11 @@ test("enter_worktree defers, forks the current session, and switches automatical
     assert.deepEqual(f.sessionMessages, [{
       message: {
         customType: "worktree-switch",
-        content: `✓ 已进入 worktree：${f.worktree}\nBranch: feature`,
+        content: `✓ 已进入 worktree：${f.worktree}\nBranch: feature\n\n在worktree继续任务`,
         display: true,
         details: { status: "created", path: f.worktree, branch: "feature", dirty: false },
       },
-      options: { triggerTurn: false },
+      options: { triggerTurn: true, deliverAs: "followUp" },
     }]);
   } finally {
     f.cleanup();

package/skills/tapd/SKILL.md CHANGED Viewed

@@ -1,499 +1,97 @@
 ---
 name: tapd
-description: TAPD操作，涉及需求，缺陷，任务，Wiki等。tapd.cn快捷查询：tapd url <url>
+description: 通过 tapd CLI 查询和操作 TAPD 中的需求、缺陷、任务和 Wiki。用户提供 tapd.cn 链接，或要求分析、查询、创建、更新 TAPD 条目及其评论、变更、附件和关联提交时使用。
 ---
-面向 AI Agent 的 TAPD 命令行工具。通过 `tapd` 命令与 TAPD 平台交互，所有输出针对最小 token 消耗优化。
+# TAPD
-## 安装
+常用功能直接按下列命令执行；只有低频功能、写操作参数或版本差异不明确时才查看帮助。
-```bash
-go install github.com/studyzy/tapd-ai-cli/cmd/tapd@latest
-```
+## 基础功能
-## 认证
+除 `tapd url`、认证和 `tapd workspace list` 外，以下命令都应携带目标 `--workspace-id=<id>`。`tapd workspace info` 读取当前 workspace，因此也需要已解析的 workspace；`tapd workspace switch <id>` 会修改当前目录配置。
-```bash
-# Access Token（推荐）
-export TAPD_ACCESS_TOKEN=<your_token>
+| 任务 | 命令 |
+|---|---|
+| 根据链接读取需求、缺陷、任务或 Wiki | `tapd url '<tapd-url>'` |
+| 查看当前/可用 workspace | `tapd workspace info` / `tapd workspace list` |
+| 查看单条需求、缺陷、任务或 Wiki | `tapd story show <id>` / `tapd bug show <id>` / `tapd task show <id>` / `tapd wiki show <id>` |
+| 查询需求、缺陷、任务或 Wiki | `tapd story list` / `tapd bug list` / `tapd task list` / `tapd wiki list` |
+| 查看评论 | `tapd comment list --entry-id=<id> --entry-type=<stories|bug|tasks|wiki>` |
+| 查看变更历史 | `tapd change list --entity-id=<id> --type=<story|bug|task>` |
+| 查看附件 | `tapd attachment list --entry-id=<id> --type=<story|bug|task>` |
+| 获取附件/内嵌图片下载描述 | `tapd attachment download --id=<attachment-id>` / `tapd image get --image-path=<path>` |
+| 查看需求关联缺陷/缺陷关联需求 | `tapd relation bugs --story-id=<id>` / `tapd bug related-stories --bug-id=<id>` |
+| 查看关联提交 | `tapd source list --object-id=<id> --type=<story|bug|task>` |
+| 获取工作项类型 ID | `tapd workitem-type list` |
+| 查询工作流状态与流转 | `tapd workflow status-map --system=<story|bug> --workitem-type-id=<id>` / `tapd workflow transitions --system=<story|bug> --workitem-type-id=<id>` |
+| 创建或更新条目 | `tapd <story|bug|task|wiki> create ...` / `tapd <story|bug|task|wiki> update <id> ...` |
+| 添加评论 | `tapd comment add --entry-id=<id> --entry-type=<stories|bug|tasks|wiki> --description='<text>'` |
-# 或交互式登录持久化凭据
-tapd auth login
-```
+常用全局参数：
-凭据优先级：CLI flags > 环境变量 > `./.tapd.json` > `~/.tapd.json`
+- `--workspace-id=<id>`：指定本次调用的 workspace；调查链接时优先显式传递。
+- `--json`：让详情命令输出 JSON，适合提取字段；列表通常已经输出 JSON。
+- `--no-comments`：读取详情时省略评论。
+- `--pretty`：仅供人工阅读；Agent 解析时不使用。
-## 高级过滤（--filter）
+列表命令可用 `--limit`、`--page`、`--order` 和实体特有字段缩小结果。仅在普通参数不能表达条件时使用 `--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<张三|李四>"
-```
+基础功能优先使用上表，不从完整命令树开始试错。出现以下情况时再查看帮助：
-### 支持的操作符
+1. 运行 `tapd <group> --help` 查看该组有哪些能力。
+2. 运行 `tapd <group> <command> --help` 确认低频参数或写操作的必填字段。
+3. 仅在不知道命令组名称或全局参数发生变化时运行 `tapd --help`。
-| 操作符 | 含义 | 示例 |
-|--------|------|------|
-| `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=<>已关闭` |
+不要通过缺省参数执行命令来探测语法；部分命令会使用默认值直接产生写操作。
-### 适用字段
+认证失败时按 CLI 提示配置凭据。不要把 token、临时下载 URL 或其他凭据写进仓库、日志或最终答复。
-- 标准字段（name/title/status/owner/created 等）
-- 自定义字段（custom_field_one、custom_field_two 等，用 `custom-field list --entity-type stories` 查看可用字段）
+## Workspace 契约
-`--filter` 与已有标志（`--status`、`--owner` 等）可组合使用，参数会合并传递给 API。
+`tapd url <url>` 会从 URL 解析 workspace 和条目，不需要预先配置 workspace。`tapd workspace list` 也不需要 workspace；`tapd workspace info` 和其他业务命令需要。每个独立的 `tapd` 进程都必须解析到目标 workspace：
-## 命令参考
+- 调查 URL 时，记录 URL 对应的 workspace ID，并在后续每条命令显式传 `--workspace-id=<id>`。
+- 只有用户明确要求持久切换项目时才运行 `tapd workspace switch <id>`；它会在当前目录写入 `.tapd.json`，切换目录后不能假设仍然生效。
+- 也可使用已配置的 `TAPD_WORKSPACE_ID`，但先确认它与目标 URL 一致。
-### url — 根据 TAPD URL 查询对应条目详情（支持需求、缺陷、任务、Wiki）
+一条命令成功不代表下一进程继承了 workspace。收到 `workspace_required` 时，根据目标 URL 或用户选择补齐 workspace 后重试。
-```bash
-tapd url <url>  # 根据 TAPD URL 查询对应条目详情（支持需求、缺陷、任务、Wiki）
-```
+## 调查 TAPD URL
-### story — 需求管理
+1. **识别条目**：运行 `tapd url '<url>'`，记录 workspace ID、实体类型、实体 ID、标题、状态和正文。
+2. **收集证据**：直接使用基础功能表中的命令，按实体类型检查详情及评论、变更历史、附件、正文或评论中的图片、关联需求/缺陷以及关联提交；每条命令显式传播 workspace ID。只有所需能力未列出、参数不明确或当前版本拒绝已记录语法时才查看叶级帮助。
+3. **读取附件**：先列出附件，再获取相关附件或图片的下载描述。下载前必须完整阅读 [附件与图片](references/attachment-download.md)。将下载后的文件交给当前环境可用的文件或图片读取能力；外部 OCR 仅在确认已安装时使用。没有可用的图片读取或 OCR 能力时明确报告阻塞，不能声称已检查图片内容。
+4. **定位代码**：从产品、版本、模块、时间、日志关键词和关联提交定位相关代码。把 TAPD 事实、代码事实和推断分开记录。
+5. **给出结论**：说明现象、影响范围、最可能原因及证据；证据不足时列出缺失日志、版本、附件或复现条件，不把推断写成事实。
-```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 — 任务管理
+## JSON 输出契约
-```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]  # 更新任务
-```
+- 使用 JSON 解析器解析 JSON；不要用 `sed`、`grep` 或正则假设键的排版。
+- `attachment download` 和 `image get` 返回 JSON 下载描述，不返回文件内容。使用本 Skill 的 `scripts/extract-download-url.mjs` 读取其中的 `download_url`；它必须存在且使用 `https://`。
+- 不确定输出结构时先保存并检查一次真实输出，或运行带 mock 数据的最小命令；不要编造字段层级。
-### 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 — 附件管理
+1. 读取当前条目和叶级 `--help`。
+2. 工作流状态先用 `tapd workitem-type list` 获取类型 ID，再用表中的 `tapd workflow` 命令查询，不猜状态值。
+3. 展示将修改的条目、字段和值；用户未明确授权写入时只给建议。
+4. 执行最小写操作，并立即重新读取目标条目验证服务端结果。
-```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>  # 上传附件
-```
-#### 安全下载附件
-`attachment download` 返回的是带短期授权 token 的临时 URL，不是附件内容。下载大附件时必须遵循以下流程：
-1. 先用 `attachment list` 记录附件文件名和预期大小；每次发起下载或续传前，重新执行 `attachment download` 获取新 URL。
-2. 下载到 `<文件名>.part`，使用 `curl --fail --location --retry 3`；HTTP 失败时立即停止，禁止把响应正文直接写入最终文件。
-3. 续传前检查 `.part` 开头不是 `token expire`、JSON/HTML 错误信息等文本响应。发现污染时删除 `.part` 并重新下载，不修补或继续追加。
-4. 使用新 URL 和 `curl -C -` 续传。已有部分长度为 N 时，只接受状态 `206` 且 `Content-Range` 从 N 开始；返回 `200`、范围不符或服务器不支持 Range 时，删除 `.part` 后从头下载。
-5. 下载完成后，文件大小必须等于 `attachment list` 的预期大小。ZIP 附件还必须通过 `unzip -t`；其他格式执行相应完整性检查。全部通过后才将 `.part` 重命名为最终文件。
-临时 URL 过期只需重新获取链接，不能据此判断 TAPD 原附件损坏。
-### 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  # 查看项目成员列表
-```
+批量、删除或不可逆操作必须先确认精确范围。完成标准是服务端读回结果符合预期，而不是命令仅返回成功。

package/skills/tapd/references/attachment-download.md ADDED Viewed

@@ -0,0 +1,46 @@
+# 附件与图片
+在下载 TAPD 附件或内嵌图片前完整执行本流程。`attachment download` 和 `image get` 返回带短期授权的 JSON 下载描述，不返回文件字节。
+## 取得下载 URL
+先通过 `attachment list` 记录附件 ID、文件名，以及响应实际提供的大小或校验信息。不要假设列表一定包含大小字段。
+每次开始新的下载尝试前重新获取下载描述。将本文件中的 `<skill-dir>` 替换为当前 TAPD Skill 所在目录，使用随 Skill 发布且经过回归测试的解析器提取并校验 `download_url`：
+```bash
+URL="$(
+  tapd attachment download --workspace-id="$WORKSPACE_ID" --id="$ATTACHMENT_ID" |
+  node <skill-dir>/scripts/extract-download-url.mjs
+)"
+```
+内嵌图片使用 `tapd image get --workspace-id="$WORKSPACE_ID" --image-path="$IMAGE_PATH"` 取得 JSON，再按同一规则读取 `download_url`。解析器只接受 HTTPS。不要输出或持久保存临时 URL。
+## 安全下载
+设置来自附件列表的目标文件名，并完整执行下载命令：
+```bash
+OUTPUT='<附件文件名>'
+PART="${OUTPUT}.part"
+if [ -e "$OUTPUT" ] || [ -e "$PART" ]; then
+  echo 'refusing to reuse an existing download path' >&2
+  exit 1
+fi
+curl --fail --location --retry 3 \
+  --proto '=https' --proto-redir '=https' \
+  --output "$PART" -- "$URL"
+test -s "$PART"
+```
+随后依次执行：
+1. HTTP 失败时停止，不把错误正文写入最终文件。
+2. 一次传输失败后，重新获取临时 URL。优先删除 `.part` 并从头下载，避免把过期 token 的响应或不匹配的文件片段拼进结果。
+3. 下载后检查 `.part` 非空，并结合附件列表中的文件名、类型和已知 TAPD 错误特征排除 `token expire` 等错误响应。JSON 或 HTML 本身可能就是合法附件，不能只凭格式判为污染。
+4. 响应若提供预期大小或校验和，必须匹配；未提供时明确不能完成该项校验，不得虚构预期大小。
+5. 按格式做完整性检查：ZIP 使用 `unzip -t "$PART"`，图片使用环境可用的格式识别/解码能力，其他格式使用对应检查。
+6. 全部检查通过后执行 `mv -- "$PART" "$OUTPUT"`。目标文件或 `.part` 已存在时必须在下载前失败，避免把旧文件误认为本次结果；任何检查失败都不得创建最终文件。
+本流程不续传失败的 `.part`；始终用新 URL 从头下载。临时 URL 过期仅表示需要重新获取链接，不能据此判断 TAPD 原附件损坏。

package/skills/tapd/scripts/extract-download-url.mjs ADDED Viewed

@@ -0,0 +1,12 @@
+let input = "";
+for await (const chunk of process.stdin) input += chunk;
+const value = JSON.parse(input).download_url;
+if (typeof value !== "string" || /[\u0000-\u001f\u007f]/u.test(value)) {
+  throw new Error("missing or invalid HTTPS download_url");
+}
+const url = new URL(value);
+if (url.protocol !== "https:" || !url.hostname || url.username || url.password) {
+  throw new Error("missing or invalid HTTPS download_url");
+}
+process.stdout.write(`${value}\n`);