tracup-bug 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# Tracup 提单工具 · 安装与使用（给同事）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一句话：Tracup 免费版没有开放 API，这个工具用「浏览器登录态 + 网页同款接口」帮你建单。
+装好之后只有三个短命令，不用记路径、不用解压：`tracup login` / `tracup status` / `tracup create`；
+配合 AI agent（opencode / Claude）时，你只管说「把这个 bug 提到 Tracup」。
+
+> 实测结论：官方 Open Interface 是付费功能；「用邮件创建任务」实测不建单（且 msn/outlook
+> 邮箱自 2024-09 起发不出 SMTP）。别在这两条路上浪费时间。
+
+---
+
+## 一、安装（约 5 分钟，一次性）
+
+### 1. 装 Node.js（只做一次，以后不用管它是什么）
+
+到 https://nodejs.org 下载 LTS 版（绿色大按钮那个），一路「下一步」装完。
+装完不用做任何配置，回到这份文档继续第 2 步。
+
+> 检查：打开终端（macOS 叫「终端」，Windows 叫 PowerShell），输入 `node -v`，
+> 能显示版本号（如 `v22.x.x`）就是装好了。
+
+### 2. 装 tracup-bug（一条命令，依赖自动装好）
+
+```bash
+npm install -g tracup-bug
+```
+
+- 看到 `added N packages` 就是成功了。依赖是 npm 自动装的，**不用再跑别的安装脚本**。
+- 如果公司内网下不了 npm 公开包，找我要 `tracup-bug-1.0.0.tgz`，然后跑：
+  `npm install -g tracup-bug-1.0.0.tgz`（效果一样）。
+
+### 3. 登录一次（必须在你自己的电脑、自己的终端里跑）
+
+```bash
+tracup login
+```
+
+会弹出一个 Chrome 窗口，正常登录 Tracup（账密或扫码都行）。
+登录成功它自己检测到并关闭，终端打印 `✓ 登录态已保存`。
+
+- 登录态存在你电脑的 `~/.cache/tracup/profile`，**通常能用数周**，过期重跑一次 `tracup login`。
+- 这等价于你的 Tracup 会话：**别发给别人、别提交到 git**。
+- 如果电脑没有 Chrome：跑 `tracup-setup --install-browser`（多下载约 150MB，只需一次）。
+
+### 4. 验证安装
+
+```bash
+tracup status     # 应显示 ✓ 登录态有效
+tracup projects   # 列出你能看到的项目/类型/成员
+```
+
+两条都过，就可以建单了。`projects` 的输出留着，后面 `--project/--type/--module` 照抄里面的名字。
+
+### 5. （可选）设默认项目
+
+第一次跑建单时会自动生成 `~/.config/tracup/web.json`，改成你常用的即可，省得每次都传：
+
+```json
+{ "project": "你们的项目名", "type": "bug", "status": "新建", "priority": 0, "assignee": "" }
+```
+
+---
+
+## 二、日常使用
+
+### 方式 A：直接跟 AI 说（推荐）
+
+装好 skill 后，在任何项目里跟 agent 说人话就行：
+
+- 「把这个 bug 提到 Tracup」
+- 「提交缺陷：库存列表按物品视图数量显示为 0」
+- 「批量提 bug：……」（一条一条来，agent 会逐条建并汇总编号）
+
+agent 会自己走 `status → projects → dry-run → 真建` 流程。**首次让它建单时，建议盯一眼
+`--dry-run` 的报文**，确认项目/类型/优先级对了再放行。
+
+### 方式 B：自己敲命令
+
+```bash
+# 1. 先看一眼报文（dry-run 不建单）
+tracup create \
+  --title "库存列表按物品视图数量显示为 0" \
+  --body $'— 复现步骤 —\n1. 打开库存页\n2. 切到按物品\n\n— 期望 —\n显示 12\n\n— 实际 —\n显示 0' \
+  --project 你们的项目名 --type bug --priority 中 --dry-run
+
+# 2. 确认无误，去掉 --dry-run 真建（建议加 --json）
+tracup create --title "..." --body "..." --project 你们的项目名 --json
+# 成功输出：✓ 已创建：项目名 #1234 标题
+```
+
+常用参数：`--title`（必填） `--body` `--project` `--type` `--module` `--assignee`
+`--status` `--priority` `--dry-run` `--json`。
+
+### 优先级（只有三档，数字越大越低）
+
+| 写法 | 界面显示 |
+|---|---|
+| `0` / `无` | 无（不设优先级） |
+| `1` / `高` | 高 |
+| `2` / `中` | 中 |
+| `3` / `低` | 低 |
+
+- **没有「紧急」档**：说「紧急」时传 `--priority 高`，并在标题/正文写明紧急原因。
+- 别按 P0 的直觉传 `0`——`0` 是「无」，不是最高。
+
+### 建错了就删
+
+```bash
+tracup delete 1234          # 只回显，不真删
+tracup delete 1234 --yes    # 真删
+```
+
+**只能删自己建的测试单**，删别人的任务前必须先确认。
+
+---
+
+## 三、排错（按表查，不用猜）
+
+| 现象 | 怎么办 |
+|---|---|
+| `找不到 playwright` | 重装包：`npm install -g tracup-bug`（或重跑 tgz 那条） |
+| `浏览器启动失败` | 本机没 Chrome：跑 `tracup-setup --install-browser` |
+| `登录态已失效` | 在**自己的终端**重跑 `tracup login`（agent 弹不出有头浏览器） |
+| `项目里没有类型/模块/成员「xxx」` | 报错里会列出可选值，照抄；或先跑 `projects` 看 |
+| `找不到项目「xxx」` | 同上；或改 `~/.config/tracup/web.json` 的默认项目 |
+| HTTP 5xx / 超时 | Tracup 侧抖动，重试一次 |
+| 建单成功但 Tracup 改版后突然全失败 | 接口是前端内部 API，对方改版会失效；找我，我按 skill 维护章节重抓接口 |
+
+---
+
+## 四、安全（3 条红线）
+
+1. `~/.config/tracup/`、`~/.cache/tracup/` **永不进 git、不外发**（里面是你的登录会话）。
+2. `capture` 录制文件可能含账号密码，只放本机，用完即删。
+3. 别把 `--assignee` 指给别人来冒充建单；指派只写自己或空着。
+
+---
+
+### 给 AI 用的同事（opencode / Claude Code 用户）
+
+如果你同事也用 AI 写代码，把 skill 目录再放一份到固定位置即可：
+
+```bash
+# 解压 tracup-bug.zip 到 ~/.agents/skills/tracup-bug/（路径固定，别改），再补两个软链接：
+ln -sfn ~/.agents/skills/tracup-bug ~/.config/opencode/skills/tracup-bug
+ln -sfn ~/.agents/skills/tracup-bug ~/.claude/skills/tracup-bug
+```
+
+之后在任何项目里跟 AI 说「把这个 bug 提到 Tracup」就行。
+
+## 五、附：发给同事的话术模板（直接复制）
+
+> 下面这段是给你转发/发群用的，改括号里的内容即可。
+
+---
+
+**标题：Tracup 建单工具（5 分钟装好，以后跟 AI 说一句话就行）**
+
+背景：Tracup 免费版没有开放 API，邮件建单实测不可用。我这套是用浏览器登录态调网页同款接口，
+（项目）已验证可建单，字段比邮件全（优先级/负责人/模块都能带）。
+
+安装（一次性，约 5 分钟）：
+
+1. 装 Node.js：到 https://nodejs.org 下 LTS 版，一路下一步（装过可跳过，终端跑 `node -v` 能显示版本号就行）
+2. 终端跑 `npm install -g tracup-bug`（内网下不了找我拿 `tracup-bug-1.0.0.tgz`，跑 `npm install -g tracup-bug-1.0.0.tgz`）
+3. 终端跑 `tracup login`（弹浏览器，登录一次）
+4. 终端跑 `tracup status` 看到 `✓ 登录态有效` 即成功
+
+详细步骤见包里的 `README.md`。
+
+以后提 bug 两种方式：
+- 跟 AI 说：「把这个 bug 提到 Tracup：（粘贴现象/复现步骤）」（需先按文档第 2 步装 skill）
+- 或自己敲：`tracup create --title "…" --body "…" --project （你们的项目名） --dry-run` 先看报文，确认后去掉 `--dry-run` 真建。
+
+注意两点：
+- 优先级只有 高/中/低 三档（`--priority 高`），没有「紧急」档，`0` 是「无」不是最高。
+- 登录态能用数周，过期重跑一次 `login` 就行。
+
+有问题先看文档第三章排错表，还搞不定找我。
+
+---
+
+*工具版本：1.0.0（2026-11-05，浏览器通道 + npm 包 + `--project/--priority语义/delete`）。Tracup 改版导致失效时找我，我按 skill 维护章节重抓接口。*

package/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: tracup-bug
+description: "把 Bug / 缺陷提交到 Tracup。走持久化浏览器会话调用 Tracup 前端同款内部接口（Tracup 免费版无开放 API，且「邮件创建任务」实测不建单）。当用户说「把这个 bug 提到 Tracup」「提交缺陷」「记一条到 Tracup」「QA 提单」「批量提 bug」，或 QA 会话/复测结束需要建单时使用。不适用于 GitHub Issues / Jira / 飞书任务等其它跟踪器。"
+---
+
+# Tracup 提单
+
+## 通道现状（2026-11-05 实测，别再走弯路）
+
+| 通道 | 结论 |
+|---|---|
+| 官方开放接口（Open Interface） | ❌ 属 Enterprise 付费权益，免费版没有 |
+| 「用邮件创建任务」 | ❌ 项目开关有、地址正确，但从**项目成员绑定邮箱**手动发信也不建单；且该绑定邮箱若是 msn/outlook 个人账号，Microsoft 2024-09 起已关闭 SMTP 基本认证，只能 OAuth2 |
+| **浏览器会话调内部接口** | ✅ 已打通：`POST /api2/issue/create`（multipart） |
+
+工具：`~/.agents/skills/tracup-bug/bin/tracup_web.mjs`（Node + Playwright）。
+首次使用先跑一次 `bin/setup.mjs` 装依赖（只写 `~/.config/tracup`，不碰仓库、不需要 sudo）。
+
+```bash
+BIN=~/.agents/skills/tracup-bug/bin
+node $BIN/setup.mjs          # 首次：装 playwright-core（配合本机 Chrome，约 5MB）
+node $BIN/setup.mjs --install-browser  # 本机没装 Chrome 时才需要（下载 Chromium 约 150MB）
+```
+
+## Step 0 · 检查登录态（每次先跑）
+
+```bash
+BIN=~/.agents/skills/tracup-bug/bin
+node $BIN/tracup_web.mjs status
+```
+
+- 退出 0 → 继续。
+- 退出 2 → 登录态过期。**必须让用户在自己的终端里跑**（agent 起不了有头窗口）：
+
+  ```bash
+  node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs login
+  ```
+
+  登录态存在 `~/.cache/tracup/profile`（持久化浏览器用户目录），通常可维持数周。
+
+`status` 同时做自检：playwright 能否加载、本机 Chrome 是否可用、配置文件是否存在，一行一行打印，排错先看它。
+
+## Step 1 · 确认项目与字段名
+
+```bash
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs projects
+```
+
+会列出该账号下每个项目的 `id / 类型名 / 状态名 / 成员名`。
+**类型名、模块名、成员名写错会直接报错并给出可选值**，照提示改即可。
+
+默认项目取自 `~/.config/tracup/web.json` 的 `project`；临时换项目加 `--project 项目名` 即可，不用改配置。
+
+## Step 2 · 先 dry-run 看报文
+
+```bash
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs create \
+  --title "库存列表按物品视图数量显示为 0" \
+  --body $'— 复现步骤 —\n1. 打开库存页\n2. 切到按物品\n\n— 期望 —\n显示 12\n\n— 实际 —\n显示 0' \
+  --project smarterlab --type bug --priority 中 --module 采购 --assignee 周日 --dry-run
+```
+
+## Step 3 · 确认后真建
+
+去掉 `--dry-run`，建议加 `--json` 便于汇总：
+
+```bash
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs create --title "..." --body "..." --json
+```
+
+成功输出：`✓ 已创建：smarterlab #6599 标题` + `id / priority=1（高） / status / type`。
+
+## Step 4 · 建错了就删（可选）
+
+```bash
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs delete 6599          # 先只回显，不真删
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs delete 6599 --yes    # 真删
+```
+
+支持 `#6599` / `6599` / 32 位任务 id 三种写法（编号会先经 `issue/info` 解析成 id）。
+**删除前必须先跟用户确认**，别自作主张删别人建的任务。
+
+## 参数
+
+| 参数 | 说明 |
+|---|---|
+| `--title` | 必填。一句话写清「哪里 + 什么现象」，别用「bug」「问题」开头 |
+| `--body` | 多行纯文本，自动按行转成段落节点（Tracup 描述是富文本 JSON） |
+| `--project` | 项目名或 id；不传则用 `~/.config/tracup/web.json` 的 `project` |
+| `--priority` | **`0`=无 `1`=高 `2`=中 `3`=低**（也可直接写 `无/高/中/低`）。默认取配置文件的 `priority` |
+| `--type` | 项目类型名，默认 `bug` |
+| `--module` | 模块名，项目里没配就留空 |
+| `--assignee` | 成员名或邮箱，默认不指派 |
+| `--status` | 状态名，默认项目里 `markAsCreated` 的那个（通常「新建」） |
+| `--dry-run` | 只打印将提交的报文，不建单 |
+| `--json` | 机器可读输出 |
+
+### ⚠️ 优先级只有三档，且数字越大越低
+
+Tracup 前端词条原文（`label.priority1/2/3`）：**1=高(High)、2=中(Normal)、3=低(Low)**，`0` = 不设优先级。
+
+- **没有「紧急/最高/P0」**。用户说「紧急」时按 `高`(1) 提交，并在汇报里说明降级了。
+- **别按 P0 最紧急的直觉反着用**：`--priority 0` 不是最高，是「无」。
+- 想要「紧急」语义，正确做法是 `--priority 高` + 在标题/正文里写明紧急原因，不要自己造档位。
+
+默认值集中在 `~/.config/tracup/web.json`（`setup.mjs` 已生成一份，可直接改）：
+
+```json
+{ "project": "smarterlab", "type": "bug", "status": "新建", "priority": 0, "assignee": "" }
+```
+
+## 批量（QA 会话场景）
+
+一条 bug 一条命令，**不要合并**。逐条执行，收集每条的 `#编号`，最后汇总成表格给用户；
+某条失败就记下原因继续下一条，不要中断整批。
+
+## 铁律
+
+- **先 dry-run 再真建**；用户明确说「直接建」才跳过确认。
+- **一条 bug 一条任务**，合并会丢掉单条可跟踪性。
+- **别塞整段日志/diff**：正文放「现象 + 最小复现」，长内容截关键片段。
+- **不提交凭据**：`~/.config/tracup/`、`~/.cache/tracup/`（含登录 profile 与接口录制）永不进 git。
+- **建单前先看列表**：同一问题别建两条。
+- **删除只删自己建的测试单**，且先跑不带 `--yes` 的那次把目标回显给用户看。
+
+## 排错
+
+| 现象 | 处理 |
+|---|---|
+| `找不到 playwright` | 跑 `node ~/.agents/skills/tracup-bug/bin/setup.mjs` |
+| `浏览器启动失败` | 本机没 Chrome：跑 `setup.mjs --install-browser` |
+| `登录态可能已失效，请重跑 login` | agent 跑不了有头窗口，让用户在自己终端跑 `login` |
+| `项目里没有类型「xxx」` | 报错里会列可选值，照抄 |
+| `项目里没有模块「xxx」` | 该模块不存在，去掉 `--module` |
+| `项目里没有成员「xxx」` | 同上，去掉 `--assignee` |
+| `找不到项目「xxx」` | 报错里会列该账号下所有项目名，照抄；或改 `web.json` |
+| HTTP 5xx / timeout | Tracup 侧抖动，重试一次 |
+
+## 维护
+
+接口是对接 Tracup 前端内部 API，**对方改版会失效**。失效时按此流程重抓：
+
+```bash
+node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs capture --duration 120
+# 在打开窗口里手动建一条任务，然后看 ~/.cache/tracup/capture-*.jsonl 里 POST /api2/issue/create 的报文
+```
+
+`node ~/.agents/skills/tracup-bug/bin/tracup_web.mjs api GET /api2/<path>` 可复用登录态直接探接口。

package/bin/setup.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * tracup-bug 初始化：装依赖 + 落默认配置 + 自检
+ *
+ *   node setup.mjs                      # 装 playwright（轻量，用本机 Chrome）
+ *   node setup.mjs --install-browser    # 顺带下载 playwright 自带 Chromium（没装 Chrome 时用）
+ *   node setup.mjs --full               # 装完整 playwright（自动下载浏览器，最稳但最慢）
+ *
+ * 只写用户目录（~/.config/tracup），不碰仓库、不需要 sudo。
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "tracup");
+const RUNTIME_DIR = path.join(CONFIG_DIR, "runtime");
+const WEB_CONFIG_PATH = path.join(CONFIG_DIR, "web.json");
+const require = createRequire(import.meta.url);
+
+const args = new Set(process.argv.slice(2));
+const wantBrowser = args.has("--install-browser") || args.has("--full");
+const fullPlaywright = args.has("--full");
+
+function log(...xs) {
+  console.log(...xs);
+}
+
+function npmBin() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function run(cmd, cmdArgs, cwd) {
+  log(`$ ${cmd} ${cmdArgs.join(" ")}   (cwd=${cwd})`);
+  execFileSync(cmd, cmdArgs, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+}
+
+/** 已经能解析到 playwright 就跳过安装。 */
+function findPlaywright() {
+  const candidates = [
+    process.env.TRACUP_PLAYWRIGHT_DIR,
+    RUNTIME_DIR,
+    path.join(CONFIG_DIR, "node_modules"),
+  ].filter(Boolean);
+  for (const pkg of ["playwright", "playwright-core"]) {
+    for (const base of candidates) {
+      try {
+        return require.resolve(pkg, { paths: [base] });
+      } catch {
+        /* 下一个 */
+      }
+    }
+    try {
+      return require.resolve(pkg);
+    } catch {
+      /* 下一个包名 */
+    }
+  }
+  return null;
+}
+
+function writeDefaultConfig() {
+  if (fs.existsSync(WEB_CONFIG_PATH)) {
+    log(`· 已存在配置，保持不动：${WEB_CONFIG_PATH}`);
+    return;
+  }
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const defaults = {
+    project: "smarterlab",
+    type: "bug",
+    status: "新建",
+    priority: 0,
+    assignee: "",
+  };
+  fs.writeFileSync(WEB_CONFIG_PATH, JSON.stringify(defaults, null, 2) + "\n", "utf8");
+  log(`✓ 已写入默认配置：${WEB_CONFIG_PATH}`);
+}
+
+function main() {
+  log("=== tracup-bug 初始化 ===");
+  log(`node ${process.version} · ${process.platform}/${process.arch}`);
+  log("");
+
+  const existing = findPlaywright();
+  if (existing) {
+    log(`✓ 已找到 playwright：${existing}（跳过安装）`);
+  } else {
+    fs.mkdirSync(RUNTIME_DIR, { recursive: true });
+    const pkgPath = path.join(RUNTIME_DIR, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+      fs.writeFileSync(
+        pkgPath,
+        JSON.stringify({ name: "tracup-bug-runtime", private: true, version: "1.0.0" }, null, 2) + "\n",
+        "utf8"
+      );
+    }
+    // playwright-core 不带浏览器（~5MB，配合本机 Chrome 即可）；--full 用完整包
+    const pkg = fullPlaywright ? "playwright" : "playwright-core";
+    log(`\n安装 ${pkg} 到 ${RUNTIME_DIR} …`);
+    run(npmBin(), ["install", pkg, "--no-audit", "--no-fund"], RUNTIME_DIR);
+    const found = findPlaywright();
+    if (!found) {
+      log("\n✗ 装完仍解析不到 playwright，请把上面的 npm 报错发给我。");
+      process.exit(1);
+    }
+    log(`✓ playwright 就位：${found}`);
+  }
+
+  if (wantBrowser) {
+    log("\n下载 playwright 自带 Chromium（约 150MB，只需一次）…");
+    run(npmBin(), ["exec", "--yes", "--", "playwright", "install", "chromium"], RUNTIME_DIR);
+    log("✓ 浏览器就位");
+  } else {
+    log("\n· 未下载 Chromium：将使用本机 Google Chrome（macOS/Windows 一般都装了）");
+    log(`  若本机没有 Chrome，跑：node ${path.join(path.dirname(new URL(import.meta.url).pathname), "setup.mjs")} --install-browser`);
+  }
+
+  writeDefaultConfig();
+
+  log("\n=== 下一步：登录一次 ===");
+  log("必须在你自己的终端里跑（会弹出有头浏览器，agent 起不了窗口）：");
+  log(`  node ${path.join(path.dirname(new URL(import.meta.url).pathname), "tracup_web.mjs")} login`);
+  log("\n登录态存在 ~/.cache/tracup/profile，通常能用数周；过期重跑 login 即可。");
+}
+
+main();

package/bin/tracup_web.mjs

@@ -0,0 +1,590 @@
+#!/usr/bin/env node
+/**
+ * tracup-web —— 用真实浏览器操作 Tracup（免费版没有开放 API，只能走网页同款内部接口）
+ *
+ * 通道结论（2026-11 实测，别再重走）：
+ *   官方 Open Interface 属 Enterprise 付费权益 → 免费版没有
+ *   「用邮件创建任务」实测不建单（成员绑定邮箱手动发信也不建），且 msn/outlook
+ *   个人账号自 2024-09-16 起停用 SMTP 基本认证 → 邮件通道彻底放弃
+ *   ✅ 浏览器会话 + POST /api2/issue/create（前端自己用的接口，字段最全）
+ *
+ * 用法：node tracup_web.mjs <login|status|projects|create|delete|capture|api>
+ *   login     打开有头浏览器，你手动登录一次（登录态存 ~/.cache/tracup/profile，可用数周）
+ *   status    检查登录态 + 自检（playwright / 浏览器 / 配置是否就位）
+ *   projects  列出项目及其类型、状态、模块、成员名
+ *   create    建单（--title/--body/--priority/--type/--module/--assignee/--status/--dry-run/--json）
+ *   delete    删单（delete <编号|id> --yes）
+ *   capture   录制网页操作请求（接口改版时重新抓报文）
+ *   api       复用登录态直接探内部接口
+ *
+ * 依赖解析：不写死 node_modules 位置，依次尝试
+ *   $TRACUP_PLAYWRIGHT_DIR / ~/.config/tracup/runtime / 全局 npm / 脚本同级目录
+ * 浏览器：优先用 playwright 自带 chromium，没下载就自动退回本机 Chrome（channel: "chrome"）
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.resolve(__dirname, "..");
+const CONFIG_DIR = path.join(os.homedir(), ".config", "tracup");
+const RUNTIME_DIR = path.join(CONFIG_DIR, "runtime");
+const CACHE_DIR = path.join(os.homedir(), ".cache", "tracup");
+const PROFILE_DIR = path.join(CACHE_DIR, "profile");
+const WEB_CONFIG_PATH = path.join(CONFIG_DIR, "web.json");
+const APP_URL = "https://app.tracup.com/";
+const API_ORIGIN = "https://www.tracup.com";
+const LOGIN_HINT = /login|signin|sign-in|passport|auth/i;
+
+const require = createRequire(import.meta.url);
+
+/** 依次尝试若干位置加载 playwright（兼容全局安装、本地 runtime、仓内 node_modules）。 */
+function loadPlaywright() {
+  const candidates = [
+    process.env.TRACUP_PLAYWRIGHT_DIR,
+    RUNTIME_DIR,
+    path.join(CONFIG_DIR, "node_modules"),
+    SKILL_DIR,
+    process.cwd(),
+  ].filter(Boolean);
+
+  const tried = [];
+  // playwright（自带浏览器）与 playwright-core（配合本机 Chrome）都认
+  for (const pkg of ["playwright", "playwright-core"]) {
+    for (const base of candidates) {
+      try {
+        const resolved = require.resolve(pkg, { paths: [base] });
+        return { mod: require(resolved), from: resolved };
+      } catch (err) {
+        tried.push(`${pkg} @ ${base} (${err.code || err.message})`);
+      }
+    }
+    try {
+      return { mod: require(pkg), from: require.resolve(pkg) };
+    } catch { /* 下一个包名 */ }
+  }
+
+  throw new Error(
+    "找不到 playwright / playwright-core。请先跑一次初始化：\n" +
+      `  node ${path.join(SKILL_DIR, "bin", "setup.mjs")}\n` +
+      `已经试过这些位置：\n  - ${tried.join("\n  - ")}`
+  );
+}
+
+let _pw = null;
+function playwright() {
+  if (!_pw) _pw = loadPlaywright();
+  return _pw;
+}
+
+/** 有内置 chromium 就用；没下载过（常见于只装了 playwright-core）就退回本机 Chrome。 */
+async function launchBrowser(profileDir, opts) {
+  const { chromium } = playwright().mod;
+  fs.mkdirSync(profileDir, { recursive: true });
+  try {
+    return await chromium.launchPersistentContext(profileDir, opts);
+  } catch (err) {
+    const msg = String(err && err.message);
+    if (!/Executable doesn't exist|is not found|Failed to launch|browserType\.launch/i.test(msg)) throw err;
+    log("（未找到 playwright 自带 Chromium，改用本机 Chrome）");
+    return chromium.launchPersistentContext(profileDir, { ...opts, channel: "chrome" });
+  }
+}
+
+function log(...args) {
+  console.log(...args);
+}
+
+async function openContext({ headless }) {
+  return launchBrowser(PROFILE_DIR, {
+    headless,
+    viewport: { width: 1440, height: 900 },
+    acceptDownloads: true,
+    args: ["--disable-blink-features=AutomationControlled"],
+  });
+}
+
+function waitEnter(promptText) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(promptText, () => {
+      rl.close();
+      resolve("enter");
+    });
+  });
+}
+
+/** 轮询判断是否已进入应用（不是登录页且有会话 cookie）。 */
+async function waitForLogin(page, timeoutMs = 300000) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    await page.waitForTimeout(1500);
+    let url = "";
+    try {
+      url = page.url();
+    } catch {
+      continue;
+    }
+    if (!url || LOGIN_HINT.test(url.replace(APP_URL, ""))) continue;
+    const cookies = await page.context().cookies();
+    const hasSession = cookies.some((c) => c.value && c.value.length > 20 && !/^(1|0|true|false)$/i.test(c.value));
+    if (hasSession) return "auto";
+  }
+  return "timeout";
+}
+
+async function cmdLogin() {
+  const headless = process.env.TRACUP_WEB_HEADLESS === "1";
+  const ctx = await openContext({ headless });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+
+  log("浏览器已打开，请在窗口里完成 Tracup 登录（支持扫码/账密）。");
+  log("登录成功后会自动继续；也可以回到这里按回车。\n");
+
+  const result = process.stdin.isTTY
+    ? await Promise.race([waitForLogin(page), waitEnter("登录完成后按回车继续… ")])
+    : await waitForLogin(page);
+  if (result === "timeout") {
+    log("⚠️  5 分钟内没检测到登录态，已放弃。请重跑 login。");
+    await ctx.close();
+    process.exit(1);
+  }
+
+  await page.waitForTimeout(1000);
+  log(`✓ 登录态已保存到 ${PROFILE_DIR}`);
+  log(`  当前页面：${page.url()}`);
+  if (!headless) await ctx.close();
+  else await ctx.close();
+}
+
+/** 自检：依赖 / 配置 / 登录态。排错时先跑这个，比猜快。 */
+async function cmdStatus() {
+  let pw;
+  try {
+    pw = playwright();
+    log(`✓ playwright：${pw.from}`);
+  } catch (err) {
+    log(`✗ ${err.message}`);
+    process.exit(3);
+  }
+
+  log(
+    fs.existsSync(WEB_CONFIG_PATH)
+      ? `✓ 配置：${WEB_CONFIG_PATH}`
+      : `· 配置：${WEB_CONFIG_PATH} 不存在（会用内置默认：smarterlab / bug / 新建 / 无）`
+  );
+
+  let ctx;
+  try {
+    ctx = await openContext({ headless: true });
+  } catch (err) {
+    log(`✗ 浏览器启动失败：${err.message}`);
+    log(`  排错：node ${path.join(SKILL_DIR, "bin", "setup.mjs")} --install-browser`);
+    process.exit(3);
+  }
+
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+  await page.waitForTimeout(3000);
+  const url = page.url();
+  const ok = !LOGIN_HINT.test(url.replace(APP_URL, ""));
+  log(ok ? `✓ 登录态有效（${url}）` : `✗ 登录态已失效（${url}）`);
+  await ctx.close();
+
+  if (!ok) {
+    log(`\n请在你自己的终端里跑（会弹有头浏览器，agent 起不了窗口）：`);
+    log(`  node ${path.join(SKILL_DIR, "bin", "tracup_web.mjs")} login`);
+  }
+  process.exit(ok ? 0 : 2);
+}
+
+/**
+ * 录制请求：把你在网页上做操作时发出的 XHR/fetch 全量落盘，
+ * 用来反推「创建任务」的内部接口与报文格式（比抠 DOM 选择器稳得多）。
+ */
+async function cmdCapture(args) {
+  const out = args.out || path.join(CACHE_DIR, `capture-${Date.now()}.jsonl`);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const stream = fs.createWriteStream(out, { flags: "a" });
+
+  const ctx = await openContext({ headless: false });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+
+  const seen = new Set();
+  const record = (entry) => {
+    const key = `${entry.method} ${entry.url} ${entry.postData || ""}`;
+    if (seen.has(key) && entry.status === undefined) return;
+    if (entry.type !== "xhr" && entry.type !== "fetch") return;
+    stream.write(JSON.stringify(entry) + "\n");
+  };
+
+  ctx.on("request", (req) => {
+    const type = req.resourceType();
+    if (type !== "xhr" && type !== "fetch") return;
+    record({ ts: Date.now(), phase: "request", method: req.method(), url: req.url(), postData: req.postData() || null, type });
+  });
+  ctx.on("response", async (resp) => {
+    const req = resp.request();
+    const type = req.resourceType();
+    if (type !== "xhr" && type !== "fetch") return;
+    let body = null;
+    try {
+      const ct = resp.headers()["content-type"] || "";
+      if (ct.includes("json") && resp.status() < 400) body = (await resp.text()).slice(0, 4000);
+    } catch {
+      /* 响应体读取失败不影响录制 */
+    }
+    record({ ts: Date.now(), phase: "response", method: req.method(), url: req.url(), postData: req.postData() || null, status: resp.status(), body, type });
+  });
+
+  await page.goto(args.url || APP_URL, { waitUntil: "domcontentloaded" });
+  log(`开始录制 → ${out}`);
+  log("请在浏览器里完整地手动创建一条任务（标题随便写），完成后回来按回车停止。\n");
+  if (process.stdin.isTTY) {
+    await waitEnter("按回车停止录制… ");
+  } else {
+    const seconds = Number(args.duration || 180);
+    log(`（非交互模式，${seconds} 秒后自动停止）`);
+    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+  }
+  stream.end();
+  await ctx.close();
+  log(`✓ 录制完成：${out}`);
+}
+
+/**
+ * 通用接口调用：复用浏览器登录态直接打 Tracup 内部 API。
+ * 用于探查/调试（例如查项目下的状态、类型、优先级选项）。
+ */
+async function cmdApi(args) {
+  const method = (args._[1] || "GET").toUpperCase();
+  const rawPath = args._[2];
+  if (!rawPath) throw new Error("用法：node tracup_web.mjs api <METHOD> <path> [--form '{...}'] [--limit 2000]");
+  const url = rawPath.startsWith("http") ? rawPath : `https://www.tracup.com${rawPath}`;
+
+  const ctx = await openContext({ headless: true });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+  await page.waitForTimeout(2000);
+
+  let resp;
+  if (args.form) {
+    resp = await ctx.request.post(url, { multipart: JSON.parse(args.form) });
+  } else if (args.body) {
+    resp = await ctx.request.fetch(url, {
+      method,
+      headers: { "content-type": "application/json" },
+      data: args.body,
+    });
+  } else {
+    resp = await ctx.request.fetch(url, { method });
+  }
+
+  const text = await resp.text();
+  log(`HTTP ${resp.status()}`);
+  const limit = Number(args.limit || 2000);
+  log(text.length > limit ? text.slice(0, limit) + `\n…（共 ${text.length} 字符）` : text);
+  await ctx.close();
+  process.exit(resp.status() >= 400 ? 2 : 0);
+}
+
+/** 读取 web 配置（项目/类型/状态/默认负责人），缺省回退合理值。 */
+function loadWebConfig() {
+  const p = path.join(os.homedir(), ".config", "tracup", "web.json");
+  if (!fs.existsSync(p)) return { configPath: p, exists: false };
+  try {
+    return { ...JSON.parse(fs.readFileSync(p, "utf8")), configPath: p, exists: true };
+  } catch (err) {
+    throw new Error(`配置文件不是合法 JSON：${p}（${err.message}）`);
+  }
+}
+
+async function fetchWorkspace(ctx) {
+  const resp = await ctx.request.get("https://www.tracup.com/api2/workspace/config");
+  if (resp.status() !== 200) {
+    throw new Error(`拉取工作区失败（HTTP ${resp.status()}），登录态可能已失效，请重跑 login`);
+  }
+  return resp.json();
+}
+
+function pickProject(config, webConfig) {
+  const projects = (config.projects || []).filter((p) => !p.archived);
+  if (!projects.length) throw new Error("账号下没有可用项目");
+  const want = webConfig.project;
+  if (!want) return projects.find((p) => p.name === "smarterlab") || projects[0];
+  const hit = projects.find((p) => p.id === want || p.name === want);
+  if (!hit) {
+    throw new Error(
+      `找不到项目「${want}」，可用：${projects.map((p) => p.name).join(" / ")}`
+    );
+  }
+  return hit;
+}
+
+function pickByName(list, name, kind) {
+  if (!name) return null;
+  const hit = (list || []).find((x) => x.name === name || x.id === name);
+  if (!hit) {
+    throw new Error(`项目里没有${kind}「${name}」，可用：${(list || []).map((x) => x.name).join(" / ")}`);
+  }
+  return hit;
+}
+
+function pickMember(project, name) {
+  if (!name) return null;
+  const members = (project.members || []).filter((m) => !m.isQuit);
+  const hit = members.find((m) => m.name === name || m.email === name || m.id === name);
+  if (!hit) {
+    throw new Error(`项目里没有成员「${name}」，可用：${members.map((m) => m.name).join(" / ")}`);
+  }
+  return hit;
+}
+
+/** 纯文本 → Tracup 的富文本描述结构（Plate/Slate 风格段落数组）。 */
+function textToDescription(body) {
+  const text = String(body || "").replace(/\r\n/g, "\n").trim();
+  const lines = text ? text.split("\n") : [""];
+  return JSON.stringify(lines.map((line) => ({ type: "paragraph", children: [{ text: line }] })));
+}
+
+/**
+ * Tracup 优先级：数字 → 界面文案。
+ * 取自前端 bundle 的 zh-CN 词条（priority1/2/3 + 无）：
+ *   1 = 高 / High，2 = 中 / Normal，3 = 低 / Low，0 = 无（不设）
+ * 注意：数字越大优先级越低，别按「P0 最紧急」的直觉反着用。
+ */
+const PRIORITY_LABELS = { 0: "无", 1: "高", 2: "中", 3: "低" };
+const PRIORITY_ALIASES = {
+  "无": 0, none: 0,
+  "高": 1, high: 1, "紧急": 1, urgent: 1,
+  "中": 2, normal: 2, medium: 2, "普通": 2, "一般": 2,
+  "低": 3, low: 3,
+};
+
+function normalizePriority(raw) {
+  if (raw === undefined || raw === null || raw === "") return 0;
+  const s = String(raw).trim();
+  if (/^[0-3]$/.test(s)) return Number(s);
+  const key = s.toLowerCase();
+  const hit = PRIORITY_ALIASES[key] ?? PRIORITY_ALIASES[s];
+  if (hit !== undefined) {
+    if ((s === "紧急" || key === "urgent")) {
+      log("提示：Tracup 只有「高/中/低」三档，没有「紧急」，「紧急」按「高」提交。");
+    }
+    return hit;
+  }
+  throw new Error(`无效的优先级「${raw}」，可用：0/1/2/3 或 无/高/中/低（Tracup 只有三档，1=高 2=中 3=低）`);
+}
+
+async function cmdProjects() {
+  const ctx = await openContext({ headless: true });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+  const ws = await fetchWorkspace(ctx);
+  for (const p of ws.projects || []) {
+    if (p.archived) continue;
+    log(`\n● ${p.name}${p.mailboxActiveStatus ? "（邮件建单已开）" : ""}`);
+    log(`  id: ${p.id}`);
+    log(`  类型: ${(p.types || []).map((t) => t.name).join(" / ")}`);
+    log(`  状态: ${(p.status || []).map((s) => s.name + (s.markAsCreated ? "(默认)" : "")).join(" / ")}`);
+    log(`  成员: ${(p.members || []).filter((m) => !m.isQuit).map((m) => m.name).join(" / ")}`);
+  }
+  await ctx.close();
+}
+
+async function cmdCreate(args) {
+  const title = (args.title || "").trim();
+  if (!title) throw new Error("缺少 --title");
+  const webConfig = loadWebConfig();
+
+  const ctx = await openContext({ headless: true });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+
+  const ws = await fetchWorkspace(ctx);
+  const project = pickProject(ws, { ...webConfig, project: args.project || webConfig.project });
+
+  const status =
+    pickByName(project.status, args.status || webConfig.status, "状态") ||
+    (project.status || []).find((s) => s.markAsCreated) ||
+    (project.status || [])[0];
+  const type =
+    pickByName(project.types, args.type || webConfig.type || "bug", "类型") || (project.types || [])[0];
+  const module = pickByName(project.modules, args.module || webConfig.module, "模块");
+  const assignee = pickMember(project, args.assignee || webConfig.assignee);
+
+  const priority = normalizePriority(args.priority ?? webConfig.priority ?? 0);
+
+  const form = {
+    project: project.id,
+    "data[status]": status.id,
+    "data[title]": title,
+    "data[assignee]": assignee ? assignee.id : "",
+    "data[description]": textToDescription(args.body || ""),
+    "data[priority]": String(priority),
+    "data[type]": type.id,
+    "data[module]": module ? module.id : "",
+    "data[version]": "",
+    "data[started]": "0",
+    "data[deadline]": "0",
+    "data[mode]": "1",
+    "data[customField]": "{}",
+  };
+
+  if (args["dry-run"]) {
+    log(JSON.stringify({ project: project.name, projectId: project.id, form }, null, 2));
+    await ctx.close();
+    return;
+  }
+
+  const resp = await ctx.request.post("https://www.tracup.com/api2/issue/create", { multipart: form });
+  const text = await resp.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error(`接口返回非 JSON（HTTP ${resp.status()}）：${text.slice(0, 300)}`);
+  }
+  await ctx.close();
+
+  if (data.code !== undefined && data.code !== 0) {
+    throw new Error(`创建失败：${data.message || text.slice(0, 300)}`);
+  }
+  // 接口有时返回 {code:0,data:{...}} 信封，有时直接返回任务对象，两种都认
+  const task = data.data && data.data.id ? data.data : data.id ? data : null;
+  if (!task) throw new Error(`创建失败，响应里没有任务：${text.slice(0, 300)}`);
+  const taskPriority = task.priority ?? priority;
+  if (args.json) {
+    log(
+      JSON.stringify(
+        {
+          ok: true,
+          number: task.number,
+          id: task.id,
+          title: task.title,
+          project: project.name,
+          priority: taskPriority,
+          priorityLabel: PRIORITY_LABELS[taskPriority] ?? "",
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    log(`✓ 已创建：${project.name} #${task.number} ${task.title}`);
+    log(
+      `  id=${task.id}  priority=${taskPriority}（${PRIORITY_LABELS[taskPriority] ?? "未知"}）  status=${status.name}  type=${type.name}`
+    );
+  }
+}
+
+/**
+ * 删除任务：POST /api2/issue/delete，字段 project + id。
+ * 会真删（前端确认弹窗之后走的就是它），所以默认要求 --yes。
+ */
+async function cmdDelete(args) {
+  const idOrNumber = args.id || args._[1];
+  if (!idOrNumber) throw new Error("用法：node tracup_web.mjs delete <任务id或编号> [--project 名称] [--yes]");
+
+  const webConfig = loadWebConfig();
+  const ctx = await openContext({ headless: true });
+  const page = ctx.pages()[0] || (await ctx.newPage());
+  await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
+
+  const ws = await fetchWorkspace(ctx);
+  const project = pickProject(ws, { ...webConfig, project: args.project || webConfig.project });
+
+  // 允许传 #6597 / 6597 这样的编号，先按编号查到真实 id
+  let taskId = String(idOrNumber).replace(/^#/, "");
+  const isObjectId = /^[0-9a-f]{32}$/i.test(taskId);
+  if (!isObjectId) {
+    const r = await ctx.request.post("https://www.tracup.com/api2/issue/info", {
+      multipart: { project: project.id, id: taskId },
+    });
+    const body = await r.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw new Error(`按编号查询失败（HTTP ${r.status()}）：${body.slice(0, 200)}`);
+    }
+    if (parsed.code !== undefined && parsed.code !== 0) {
+      throw new Error(`按编号 ${taskId} 查询失败：${parsed.message || body.slice(0, 200)}`);
+    }
+    const hit = parsed.data || parsed;
+    if (!hit || !hit.id) throw new Error(`按编号 ${taskId} 没查到任务，请改用任务 id（32 位 hex）`);
+    taskId = hit.id;
+    log(`按编号解析：${project.name} #${hit.number ?? taskId} ${hit.title || ""} → id=${taskId}`);
+  }
+
+  if (!args.yes) {
+    log(`将要删除：${project.name} 中 id=${taskId}`);
+    log("确认无误后加 --yes 重跑。");
+    await ctx.close();
+    return;
+  }
+
+  const resp = await ctx.request.post("https://www.tracup.com/api2/issue/delete", {
+    multipart: { project: project.id, id: taskId },
+  });
+  const text = await resp.text();
+  await ctx.close();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error(`删除返回非 JSON（HTTP ${resp.status()}）：${text.slice(0, 200)}`);
+  }
+  if (data.code !== undefined && data.code !== 0) {
+    throw new Error(`删除失败：${data.message || text.slice(0, 200)}`);
+  }
+  log(`✓ 已删除：${project.name} id=${taskId}`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        args[key] = next;
+        i++;
+      } else args[key] = true;
+    } else args._.push(a);
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+
+const commands = {
+  login: cmdLogin,
+  status: cmdStatus,
+  capture: cmdCapture,
+  api: cmdApi,
+  projects: cmdProjects,
+  create: cmdCreate,
+  delete: cmdDelete,
+};
+
+if (!cmd || !commands[cmd]) {
+  log("用法：node tracup_web.mjs <login|status|projects|create|delete|capture|api>");
+  log("");
+  log("create 参数：--title（必填）--body --project --priority --type --module --assignee --status --dry-run --json");
+  log("优先级：0=无 1=高 2=中 3=低（也可直接写 无/高/中/低，Tracup 只有这三档）");
+  process.exit(1);
+}
+
+commands[cmd](args).catch((err) => {
+  console.error("[error]", err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "tracup-bug",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Tracup 缺陷提单 CLI（免费版无开放 API，走浏览器登录态调网页同款内部接口）",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "tracup": "./bin/tracup_web.mjs",
+    "tracup-setup": "./bin/setup.mjs"
+  },
+  "dependencies": {
+    "playwright-core": "^1.49.0"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "tracup",
+    "bug",
+    "issue",
+    "cli"
+  ],
+  "homepage": "https://www.tracup.com",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}