TAPD Workbench

TAPD workbench brings TAPD (stories, tasks, and bugs) into Paseo.

The main screen has an aggregate tab that shows stories, tasks, and bugs side by side, plus one tab per type. The aggregate tab shows flat cards by default; a toolbar toggle enables collapsible status groups. A type tab shows a board whose columns are the workflow statuses of that type, with theme-aware status, type, and priority badges. Type boards show only populated status columns by default. The column picker retains every status and count; explicit saved selections can include empty columns, while Restore Default resumes automatic hiding. Six permanent dropdowns provide status scope (all / unfinished / done), iteration, updated-within (unlimited / 7 / 30 / 90 days), owner, creator, and priority. People are searchable single-selects with exact-nickname fallback; priority allows multiple selections without closing the menu. Filter changes apply immediately and all current choices stay visible, including saved choices no longer present in candidates. Bug severity uses a permanent multi-select dropdown; keyword, labels and applied advanced conditions also stay visible in the toolbar. Add Condition opens a field picker and value editor for specific workflow states by type and other TAPD fields. A filter combination can be saved as a reusable view, switched from the toolbar, updated in place, or set as the default. The built-in "Related to me" view matches items where you are the owner, creator, developer, participator, watcher, or commenter, and stories whose linked tasks involve you. Cards can be starred to pin them to the top.

Board loading uses a stale-while-revalidate cache on the daemon (90 seconds per filter combination, per-request TAPD responses cached 20 seconds, metadata up to 30 minutes). Within the TTL the board renders instantly; when expired, the last snapshot is shown immediately with a note ("showing data from N minutes ago, refreshing in the background") while the daemon refetches in the background, and the workbench polls every 3 seconds until fresh data arrives. The Refresh button bypasses the cache for a forced reload, and changing plugin settings clears all caches. A configurable auto-refresh (Settings → 看板, seconds; off by default, minimum 30, maximum 3600) makes the workbench send a forced board request on that cadence. Push and pull stay manual buttons; in addition, once a Git sync URL is configured, any settings change is auto-pushed as a sanitized backup about 10 seconds (trailing debounce) after the last change — silent when sync is unconfigured, on push failure, and a pull never re-triggers anything new (the pushed payload after a pull is identical, fine-grained no-op). Cross-project list queries fan out in parallel per project.

Opening an item uses a wider reading dialog (up to 1040px), with title/status and key properties first, then complete structured description, related items and recent comments. Headings, paragraphs, lists, quotes, links, code and tables retain their reading structure; wide tables scroll horizontally. Description and loaded comments are no longer silently clipped to 4000/800 characters; the existing latest-30-comments query limit remains. Scripts/styles are ignored. Description and comment images load automatically inline, preserving their aspect ratio within the reading width. Loading feedback, failure/retry controls, captions and a view-original link remain visible. Site-local /tfl/captures/ and /tfl/pictures/ PNG/JPEG/GIF/BMP images use the item’s actual configured project: the daemon sends the path to the configured API’s /files/get_image, then reads its HTTP(S) download URL once. API-issued download hosts and safe HTTP(S) redirects receive no Authorization or cookies. The configured API is trusted to issue the download destination; RPC callers cannot supply arbitrary download URLs. The daemon rejects non-image signatures and responses over 8 MiB, returns inline base64 image data over RPC, and writes nothing to disk. The client shares matching image reads and clears unused query data after 60 seconds; retry obtains a fresh download. Other validated HTTP(S) images still load directly in the client without configured TAPD credentials (normal browser cookies may apply). Other HTTP(S) links open only on explicit click and receive no configured TAPD credentials. Dialogs share bounded widths, spacing, themed controls, keyboard focus and Escape behavior. Detail actions show one foreground page, with return to the original reading position; edited creation/comment drafts require discard confirmation. Creation fields are grouped without hiding additional fields, preserving personal layout settings. Story details additionally list the tasks and bugs attached to the story (each capped at 200 rows, paginated 10 per page, with a "first 200 / N total" hint when the real count exceeds the cap), and task/bug details provide a jump back to the parent story. Board cards for tasks and bugs show #id on its own line under the title plus a parent-story chip; in the story detail window, hovering a child-list row title expands the full text inline (desktop); on touch devices, tapping a row simply opens the item.

Workflow features: dispatch an item to a coding agent by picking a repository and provider/model; the plugin creates a worktree workspace and starts an agent whose prompt contains the item snapshot. Dispatched workspaces and agents are tracked from the item and the card. The plugin can write a comment back to TAPD (plain text converted to HTML), change the item's workflow status through an anchored dropdown (selecting another value submits immediately; the current value does not write; failures retain the old displayed value and prompt a state check before another attempt), and create new stories, tasks, or bugs from the board. The story detail window additionally offers one-click creation of a task or bug under that story (TAPD story_id is written for the parent link, and the story's workspace is used so items never land in the wrong project). The mounted create form asks the TAPD fields-info endpoint per entity type for remaining writable fields (enum/user fields render as option chips or a nickname input; date-like fields — including custom fields whose label mentions 时间/日期 — open a self-drawn month calendar with yesterday/today/tomorrow shortcuts), defaults the owner to the current token user (resolved once per open via the TAPD users/info endpoint), and lets the user reorder or hide fields in a layout that is stored per entity type in plugin settings, so it is carried along by settings sync automatically.

An item can also be linked to an existing agent from its detail window. The editable prompt can be cleared to bind without sending. Cards and detail rows show live status, timestamp and the last turn outcome through the daemon event stream. Ordinary ended turns only update local state; they never post TAPD comments or advance business status. The legacy auto-report setting remains readable and syncable but has no effect. Deprecated event history cannot establish current-turn authorship, so the plugin leaves the summary empty, uses fixed safe failure text and directs users to the Agent conversation. Explicit stage comments use the existing authorized comment tool.

Agent sessions receive the TAPD connection variables (TAPD_TOKEN, TAPD_API_ENDPOINT, TAPD_SITE_URL, TAPD_WORKSPACE_IDS) when they are not already defined, so a linked agent can call the TAPD OpenAPI directly.

An attachment source lets you search TAPD items by keyword or ID while composing a prompt and attach a text snapshot (title, status, owner, link).

Settings → Config sync (Git) backs up the non-secret settings (views, favorites, board columns, item↔agent links, default dispatch repo/model, the ignored legacy auto-report value, and so on) to the user's own Git repository or restores them from it: enter a repository URL (HTTPS or SSH), an access token, and a branch, then use the Push / Pull buttons. The synced artifact is tapd-workbench-settings.json at the repository root; privacy-sensitive fields stay on the machine and are never written into it: the TAPD token, the Git token, the project IDs, and the local dispatch repo path; pulling does not overwrite the sync configuration itself. Pushing creates one commit from the current settings (skipped when nothing changed) and supports first push to an empty repository and falling back to the default branch when the requested branch is missing. Pulling takes the repository's latest file and overwrites the non-secret fields wholesale. Typical flow: configure the plugin normally and push once; after reinstalling or moving machines, fill in the connection and sync settings and pull to recover links and other data.

Connection and TAPD item data: the daemon reads and writes TAPD item data through the TAPD OpenAPI, using the token solely as the TAPD Authorization header. Credentials and project IDs come from the plugin settings screen, falling back to the daemon environment variables TAPD_TOKEN and TAPD_WORKSPACE_IDS. A token saved in the plugin settings is stored as plain JSON on the daemon host and is readable by the connected settings interface; prefer the environment variable when that is a concern. The TAPD API base URL (default https://api.tapd.cn) and the web link base (default https://www.tapd.cn) can be overridden per daemon with the TAPD_API_ENDPOINT and TAPD_SITE_URL environment variables. Reads cover every configured project; write operations (comments, status changes, item creation, controlled field edits) run only on explicit user action and target the item's actual project when known, falling back to the first configured TAPD project; ordinary Agent turns never write, including when old settings enabled auto-report. Agent dispatch goes through the Paseo SDK after confirmation in the dispatch dialog, and the item snapshot used as the agent prompt is sent to the selected agent provider. Conversation references and compact result summaries are stored locally as described below. Config sync also writes files: the daemon makes a shallow clone of the user-configured Git repository in the system temp directory, writes tapd-workbench-settings.json and pushes (or reads that file back), deleting the clone afterwards. In HTTPS mode the Git token travels to the configured Git host during clone/push, and the authenticated clone URL (token included) is stored in the temporary clone's .git/config until the clone is deleted; SSH mode performs no authentication. Error text never echoes the token, and pulling never replaces the locally configured sync destination (URL/branch) or any secret field. When the workbench opens, the plugin checks for updates by fetching the public registry record and the manifest at the pinned commit from GitHub (api.github.com, falling back to raw.githubusercontent.com); no credentials or user data are sent and the result is cached for an hour. Config sync adds exactly one more network destination: the Git repository the user configured in settings; in HTTPS mode the Git token is sent to that host during clone/push and briefly lives in the temporary clone's .git/config (deleted with the clone). Push and pull run only from the settings buttons, the payload is the sanitized settings JSON with tokens never echoed in errors, a pull cannot change the local sync destination or import secret fields, and a push aborts outright if the sanitized payload would still contain the TAPD or Git token text (credentials can never reach the repository through an accidental managed field). If the registry pins a newer version, the workbench shows a dismissible banner inviting the user to run the update command. Requires Paseo 0.13.2 or later. Known limits: commenter matching uses the 200 most recent comments; each board column shows at most 300 items; agent status and the last turn record live in daemon memory, so a daemon restart clears the last turn record (live status is re-read).

中文

TAPD 工作台把 TAPD（需求、任务、缺陷）带进 Paseo。

主界面有一个聚合页签，需求、任务、缺陷三栏并排展示，另有每种类型一个独立页签。聚合页签默认平铺卡片，不按状态分组；可通过工具栏「分组」按钮开启状态分组与折叠，已保存的个人选择继续保留。类型页签展示看板，列即该类型的工作流状态，状态、类型和优先级标签用主题色区分，卡片直接显示状态。单类型看板默认只显示当前结果中有单据的状态列；列选择器保留全部状态及数量，你可以显式选择空列，或恢复默认以自动隐藏空列。顶部常驻状态范围（全部 / 未结束 / 已结束）、迭代、更新时间（不限 / 近 7 天 / 近 30 天 / 近 90 天）、处理人、创建人、优先级六个下拉筛选，按窗口宽度换行。人员可搜索单选或使用准确昵称，优先级支持多选并保持菜单展开，选择即时生效；旧视图中未出现在候选里的选择仍可回显。缺陷严重程度使用常驻多选下拉，关键词、标签和已添加的高级条件直接显示在顶部，不再提供「更多筛选」入口；「添加条件」打开字段选择与值编辑器，可添加按类型区分的具体工作流状态及其他 TAPD 字段。一组过滤条件可保存为可复用视图，从工具栏切换、就地更新或设为默认。内置的「我相关的」视图匹配你是负责人、创建人、开发、参与、关注或评论过的单据，以及关联任务涉及你的需求。卡片可加星置顶。

看板加载走 daemon 侧的 stale-while-revalidate 缓存（每个过滤条件独立缓存 90 秒，单条 TAPD 请求缓存 20 秒，元数据最长 30 分钟）。90 秒内再进工作台直接渲染；过期后立刻显示上一次快照并在顶部提示「正在显示 N 分钟前的数据，后台刷新中…」，同时 daemon 后台重拉，工作台每 3 秒轮询直到新数据到达。「刷新」按钮绕过缓存强制重拉，修改插件设置会清空全部缓存；还可在 设置 → 看板 配置自动刷新间隔（秒），默认关闭、最小 30 秒、上限 3600，开启后工作台按该间隔定时发送强制刷新请求。推送/拉取保持手动按钮：此外一旦配置了 Git 同步地址，设置发生变更会在最后一次变更约 10 秒后（尾随去抖）自动推送一次脱敏备份——未配置或失败时静默；拉取合并导致的设置保存触发的自动推送内容与仓库一致，等价空操作。跨项目的列表请求已按项目并行发出。

打开单据会在详情浮窗中显示状态、负责人、创建人、迭代、描述与最近评论，并提供「在 TAPD 中打开」与「复制链接」操作。需求详情会额外读取该需求下挂的任务与缺陷（TAPD 的 task.story_id / bug.story_id，各限 200 条），在列表中展示标题、状态与处理人，列表每 10 条一页可翻页；真实总数超过上限时显示「前 200 / 共 N 条」截断提示。点击列表项可在浮窗内切换到对应单据详情（未提供宿主导航时退化为在浏览器打开）。任务与缺陷详情会解析所属需求（story_id）并提供跳回入口。需求详情的子单据读取失败不会阻塞需求详情本身。任务/缺陷看板卡片把 #id 独立展示在标题下一行，并显示「需求：所属需求」标识；需求详情下挂的子单据列表行标题悬停时在行内展开全文（桌面端），触屏设备直接点按打开单据。

详情浮窗的「关联任务」区按 Agent 名称显示每条关联（缺失时回退工作区标题，再回退 ID），并展示该 Agent 的实时状态与最近一次工作结果（见上文）。

工作流能力：选择仓库与 provider/model，可把单据派给一个编码 Agent；插件创建 worktree 工作区并启动一个提示词中包含单据快照的 Agent，派发的工作区与 Agent 可从单据和卡片追踪。插件可以把评论回写 TAPD（纯文本转 HTML）、变更单据工作流状态，并在看板上新建需求、任务或缺陷；需求详情浮窗另可一键创建挂在该需求下的任务/缺陷（自动写入 TAPD 的 story_id 关联，并沿用需求所在项目，避免多项目时挂错）。挂载表单按类型向 TAPD fields_info 接口取其余可写字段动态渲染（枚举/人员字段给选项 chip 或昵称输入，日期及「时间/日期」类自定义字段打开自绘月历并带昨天/今天/明天快捷项）；处理人默认当前 Token 用户（打开创建时经 TAPD users/info 解析一次）；字段顺序与隐藏布局按类型存于插件设置，随设置同步自动备份。

单据也可在详情浮窗关联已有 Agent。提示词可编辑后发送，也可清空只绑定；卡片与详情记录关联并显示实时状态、最近回合结果与时间。本地台账通过 daemon Agent 事件更新。普通 turn-ended 只更新本地状态，不写 TAPD 评论、不推进业务状态；旧 autoReportAgentResult 布尔值继续可读及同步但不生效，设置页说明阶段成果需显式授权评论。事件的 deprecated timeline 无法证明当前回合摘要归属，因此不提取摘要或原始错误；详情引导查看 Agent 会话。

Agent 会话在相关变量尚未定义时会收到 TAPD 连接变量（TAPD_TOKEN、TAPD_API_ENDPOINT、TAPD_SITE_URL、TAPD_WORKSPACE_IDS），从而可直接调用 TAPD OpenAPI。

附件源支持在撰写提示词时按关键词或 ID 搜索 TAPD 单据，并附上文本快照（标题、状态、负责人、链接）。

设置 → 配置同步（Git）可把非密配置（视图、收藏、看板列、单据关联记录、派活默认仓库与模型、旧自动回评兼容值等）备份到用户自己的 Git 仓库或从中恢复：填入仓库地址（HTTPS 或 SSH）、访问令牌与分支，按「推送 / 拉取」按钮执行。同步内容为仓库根目录的 tapd-workbench-settings.json；隐私字段不出本机、不写入该文件：TAPD Token、Git 令牌、项目 ID、派活仓库路径，且拉取也不会覆盖同步配置本身。推送用当前设置生成一次提交（无变更则跳过），支持空仓库首次推送与换分支（指定分支不存在时回退默认分支）；拉取取仓库最新文件并整体覆盖上述非密字段。常规流程：正常配置好插件并推送一次 → 重装/换机后填写连接信息与同步配置 → 点拉取找回关联等数据。

连接与数据：插件运行在 daemon 侧，只调用 TAPD OpenAPI，token 仅作为 TAPD Authorization 头使用。凭据与项目 ID 来自插件设置页，回退到 daemon 环境变量 TAPD_TOKEN 与 TAPD_WORKSPACE_IDS。保存在插件设置中的 token 以明文 JSON 存于 daemon 主机，可被已连接的设置界面读取；介意时请改用环境变量。TAPD API 基地址（默认 https://api.tapd.cn）与网页链接基地址（默认 https://www.tapd.cn）可在设置 → 连接中分别填写「API 地址」与「网页域名」，留空分别回退环境变量 TAPD_API_ENDPOINT、TAPD_SITE_URL 和上述默认值。地址需为完整 HTTP(S) URL，不接受账号、密码、查询参数或片段。测试连接使用当前草稿地址；保存后单据链接和新 Agent 会话使用这些配置（不覆盖 Agent 已有变量）。凭证只发送到配置的 API 地址，API 重定向会被拒绝；网页域名用于单据链接与正文相对地址解析，不用于 API 认证。两个地址不进入 Git 备份，也不能从备份覆盖本机配置。读取覆盖所有已配置项目；写操作（评论、状态变更、建单、受控字段更新）只在用户明确操作时执行，优先作用于单据实际所在项目（详情弹窗内的回写会携带该字段，无法确定时回退第一个配置的 TAPD 项目）；普通 Agent 回合结束不写入，即使旧设置已启用自动回评。派给 Agent 需在派发对话框中确认，经 Paseo SDK 执行，作为 Agent 提示词的单据快照会发送给所选的 agent provider。会话引用和短卡片摘要另存本机插件目录（见下文）；看板和完整单据读取结果只缓存在 daemon 内存，修改设置即清空。配置同步也会写文件：daemon 为用户配置的 Git 仓库在系统临时目录做浅克隆，写入 tapd-workbench-settings.json 后提交推送（或读取该文件返回），目录用完即删；HTTPS 模式下 Git 令牌会在克隆/推送时发送到该仓库服务器，并暂存于临时克隆目录的 .git/config（目录删除即清除），SSH 模式不涉及令牌；报错文本会抹去令牌，且拉取永远不会替换本机的同步目的地（地址/分支）或任何密钥字段。工作台打开时，插件会从 GitHub 拉取公开的 registry 记录与固定提交处的清单来做更新检查（api.github.com，失败时回退 raw.githubusercontent.com）；不附带凭据、不发送用户数据，结果缓存一小时。配置同步只再新增一个网络目的地：用户在设置中填写的 Git 仓库（HTTPS 模式下一次克隆/推送会把 Git 令牌发送到该仓库所在主机），推送/拉取仅由设置页按钮触发，内容为脱敏的设置 JSON，报错不回显令牌，拉取不会改变本机同步目的地、也不会导入密钥字段；且推送有硬性红线：若脱敏后的负载仍含 TAPD 或 Git 令牌字面值（如误抄进视图名/收藏），推送直接中止，令牌不可能经意外字段进入仓库。若 registry 固定了更新的版本，工作台会显示一个可关闭的横幅，提示运行更新命令。需要 Paseo 0.14.0-beta.1 或更新的兼容构建，稳定版 0.13.2 不支持。已知限制：评论人匹配只取最近 200 条评论；每个看板列最多显示 300 个单据；Agent 状态与结果台账保存在 daemon 内存，daemon 重启后最近一次结果会清空（实时状态会重新读取）。

状态范围按项目分别读取 TAPD /workflows/last_steps 的结束状态，用于筛选和卡片完成标识；高级状态条件与范围取交集，返回结果再次校验。接口不可用时回退标准终态和明确的完成标签，此时无法识别无完成含义的自定义终态标签。新增读取仅发送项目 ID 与单据类型到配置的 TAPD API 地址，沿用现有认证与缓存。

桌面设置弹窗最大宽度为 900px，并限制在当前窗口内，内容区可滚动。窄屏和原生客户端保留 Paseo 面板；桌面支持关闭按钮、遮罩及 Escape 关闭，焦点约束与恢复由 React Native Modal 提供。

状态、类型、优先级标签使用当前 Paseo 主题的语义色、边框和圆点区分，并保留可读文字。卡片直接显示状态，关闭分组时仍可辨认；自定义状态优先按显示标签与完成标识着色，不再硬编码项目专属状态编号。紧急 / P0 / P1 显示危险色，高 / P2 显示警告色，中 / P3 显示强调色，低和未知等级保持中性。此显示调整不新增数据读取或网络目的地。

人员筛选首次打开时，daemon 从各配置项目的 TAPD /workspaces/users 读取成员昵称（仅请求 user 字段，不读取姓名、邮箱或角色），合并去重后返回工作台；创建人与处理人共用候选读取。成员可能不包含已移出项目的历史人员，因此准确昵称输入始终保留。部分读取失败时保留已取得的成员，并提供错误提示与重试；不会把当前卡片名单当成完整人员候选。网络目的地仍为配置的 TAPD API 地址。

修改状态使用按钮下方菜单，候选从单据实际所属项目、对应类型的字段接口读取，不混用其他项目的状态。点击当前状态不写入，选中其他状态立即提交，期间阻止重复提交；失败保留原值和菜单并允许重试，成功后同步详情与看板。此操作沿用已有状态写入权限及目的地。

详情阅读与弹窗：桌面详情最大宽 1040px，正文行宽不超过 760px，标题、状态和关键属性在前，描述之后再展示关联信息及评论。描述与已读取评论保留完整文字和受支持的阅读结构，不再静默截成 4000 / 800 字；评论仍只读取现有最近 30 条。脚本、样式及嵌入内容被忽略，不执行原始 HTML。描述及评论中的图片自动内嵌显示，按阅读区域等比缩放，保留说明、查看原图、加载提示及失败重试。本站 /tfl/captures/、/tfl/pictures/ 下的 PNG/JPEG/GIF/BMP 图片按单据实际项目，从配置 API 的 /files/get_image 获取下载地址，再由 daemon 仅读取一次。下载目的地由受信任的配置 API 返回，RPC 调用方不能指定任意下载地址；下载及有限次安全 HTTP(S) 重定向均不附加 Authorization/Cookie。校验图片签名并限制 8 MiB，通过 RPC 返回 base64 内嵌图片，只驻留内存、不落盘；客户端共享相同图片读取，未使用的查询数据 60 秒后清除，失败重试获取新链接。其他安全 HTTP(S) 图片仍由客户端直接加载，不附加配置凭据，浏览器可能使用通常的站点 Cookie。其余 HTTP(S) 链接仅在点击时交给系统打开，不附带插件配置的 TAPD 凭据。Agent 提示词继续使用单独的纯文本快照与现有长度限制。弹窗共用标题、边距、圆角和按钮样式，详情、设置、表单与小型选择器分别限宽；窄屏单列，内容在窗内滚动。详情中的新建、评论、派发、绑定以单个前景操作页切换，返回保留原单据和阅读位置；新建或评论有未提交内容时确认放弃。新建表单分区并保留已保存的字段布局，图片请求目的地为配置 API 返回的下载主机及其安全重定向，或其他正文 HTTP(S) 图片地址；不新增配置迁移。

迭代下拉框与选中回显标注「当前迭代」：按客户端本地日期判断，今天在有效起止日期内（含首尾）且迭代未关闭；过去、未来或缺少有效日期的迭代仍可选择，但不标为当前。不会自动更改已选迭代或保存视图。

Iteration options and the selected summary mark current iterations using the client-local date within valid start/end dates (inclusive), excluding closed iterations. Past, future and undated iterations remain selectable; selections and saved views are preserved.

Agent tool data flow / Agent 工具数据流

The mainline session-open hook attaches the 19 tapd_* tools listed in README to each live agent session, preserving earlier tools and existing connection environment variables; history-only sessions are skipped. Published compatibility starts at 0.14.0-beta.1; stable 0.13.2 lacks the tool API. Development pins the beta SDK. A matching trusted mainline SDK can optionally be used for local development; no build/lifecycle script runs automatically and plugin settings are unchanged.

Agent tool inputs/results travel through Paseo's provider-supported MCP/native transport to the plugin process. TAPD item text, comments, member nicknames, configured project IDs and metadata returned by a tool become visible to the calling agent/provider. Calls use the latest local settings and the existing configured TAPD API only, with its existing Authorization header and redirect rejection; no new remote destination is added. Tools cannot set tokens or endpoints, return no settings/secrets, bound input JSON to 64 KB, suppress raw upstream errors and redact configured credentials in results. Partial failures retain an error marker; existing result limits/truncation and caches remain. Full item text is untrusted data and cannot authorize writes.

Write tools require the explicit configured project and confirmed: true after the agent presents the precise target/payload for user approval. This is a caller assertion, not a new human approval service or a bypass of provider/Paseo permission policy. Status/comment writes additionally read the item and reject a project mismatch; child creation checks the parent requirement. Status writes verify the project's options and skip the current value. No write is automatically retried. Cancellation is checked before execution and immediately before writes; an already-dispatched HTTP write may still complete, with the existing 20-second request timeout. Check state before retrying an ambiguous result. Configuration sync, plugin updates, image bytes and agent dispatch are not exposed as these tools. Dispatch UI behavior is unchanged; ordinary turn auto-reporting has been disabled. No additional files/media are written by tools.

主线 session-open 钩子向实际 Agent 会话注册 README 中的 19 个 tapd_* 工具，保留此前工具及已有连接变量，跳过 history。公开版本需要 0.14.0-beta.1 或更新的兼容构建；稳定版 0.13.2 不支持。开发固定 beta SDK，也可显式选择匹配的可信主线 SDK，不自动执行构建/安装脚本，不改插件配置。

输入和结果经 Paseo 的 MCP/native 传输到插件进程；返回的项目 ID、单据完整正文、评论、成员昵称及元数据会提供给调用 Agent 及其 provider。每次调用读取当前插件配置，只访问原配置 TAPD API，沿用认证与禁止 API 重定向，不新增远程目的地。工具不能覆写 Token 或地址，不返回设置/秘密；输入 JSON 限 64 KB，错误不回显原始响应，结果中的已配置凭据被抹去。部分失败保留错误标记，现有截断与缓存不变。TAPD 正文属于不可信业务数据，不能充当指令或写入授权。

建单、改状态、评论和单字段更新需要显式配置项目及 confirmed: true，由 Agent 先向用户展示准确目标及完整内容并取得批准；该参数只是调用方声明，不构成独立人工审批系统，仍遵从 Paseo/provider 权限。状态和评论先核对单据真实项目，子建单核对父需求；状态验证所属项目候选并跳过当前值。写入不自动重试，结果不明先读取确认。入口及真正写入前检查取消信号；已经发送的写入可能完成，仍受现有 20 秒请求超时限制。配置同步、插件升级、图片二进制和 Agent 派发不暴露为这些工具，现有派发界面保持原行为，普通回合自动回评已停用。工具不新增文件或媒体落盘。

工具输入上限按 UTF-8 字节计算。工具结果的 warnings 标注被现有容错读取吞掉的部分失败或搜索/迭代候选截断；不要把缺失候选或搜索空结果当作完整项目结论。评论在用户信息读取之后、HTTP 写入实际发出之前再次检查取消。

Tool inputs are bounded by UTF-8 byte length. Result warnings flag tolerated read failures and capped search/iteration results; absent candidates or empty searches do not establish an exhaustive project result. Cancellation is also checked at the HTTP write boundary, after comment-author lookup.

看板的读取警告随快照缓存（包括界面先加载及后台刷新），缓存命中不会丢失完整性提示。「我处理的」无法识别当前用户时直接报错，不扩大为全员查询。Board read warnings travel with cached snapshots, including UI-warmed results and background refreshes. If the current user cannot be resolved, a mine query fails rather than broadening to everyone.

Single-item tool queries also append a clickable result card to the calling conversation through the public Paseo timeline API. Card data contains only the item project, kind, ID, bounded title/status/owner, connection identifiers and generic completeness warnings; full descriptions, comment bodies and credentials are excluded. Timeline rows are presented by the daemon; the plugin separately retains compact records to recover them after restart. Opening the card explicitly reads current detail through the configured API after checking the recorded site/API identifiers and project, then uses the same detail/action pages as the workbench. No additional remote destination is introduced. A failed card append leaves the completed TAPD read successful with a presentation warning.

单张工具查询也会通过 Paseo 公开时间线接口，向调用所在对话追加可点击结果卡片。卡片只携带项目、类型、单号、有限长度的标题/状态/处理人、连接标识和通用的完整性提示，不包含完整正文、评论内容或凭据；时间线行由 daemon 展示，插件另存短记录，以便重启后重建。点击卡片才读取最新详情，服务端先核对记录的站点/API 标识及项目，始终只访问当前配置的 API；详情和操作页与工作台共用，不增加远程目的地。卡片追加失败时保留已完成的查询结果，并返回展示提示。

Conversation records use PASEO_HOME/plugin-data/tapd-workbench/conversations.json, defaulting to ~/.paseo/plugin-data/tapd-workbench/conversations.json. This independent plugin-owned store contains schema-validated host/agent ownership, connection identifiers, TAPD project/kind/item references, bounded title/status/owner summaries, card IDs and source replay progress. It excludes full descriptions, comments, image bytes, credentials and authenticated URLs; it is never exported by settings sync. Writes are serialized and replace the file atomically using a synced temporary file with owner-only permissions. Unchanged reads do not write. Unknown/corrupt records fail safely; incomplete temporary saves do not replace the last valid record.

The root contribution observes public Agent updates and polls the local conversation RPC every two seconds without reading TAPD. Composer actions open Agent-scoped list panels, and single/batch cards open the same reusable item panels. Cleanup releases subscriptions, timers, buttons and panels; late requests cannot recreate them. Focus validates recorded references against the current connection and project. Archive/restart retain records; only verified conversation deletion clears them, and recovery never replays TAPD tools.

会话记录使用上述独立本机目录和经过 schema 校验的 JSON，按主机/Agent 隔离，保存连接标识、项目/类型/单号、短标题/状态/处理人、卡片 ID 及来源重放进度，不保存正文、评论全文、图片、凭据或带认证的 URL，不进入 Git 配置同步。更新串行执行，以仅当前用户可读写的临时文件同步后原子替换；普通查询不反复写盘。损坏记录返回安全错误，未完成临时保存不替换上次有效记录。移除只影响会话入口，历史卡片保留，旧来源重放不会重新收录，新查询或主动打开可重新加入。会话关闭、重开、插件重载、daemon 重启及归档都保留，只有公开 SDK 精确查询确认 Agent 已删除才清理；断连、分页不可见、归档及运行时关闭都不会被当作删除。服务端首次公开上下文可用前存在观察间隔；客户端根贡献的初始本机 RPC 会启动对账，客户端离线时由首个工具或钩子启动，对账在入口展示前完成。恢复扫描分页历史并按稳定卡片 ID 补齐缺失展示，不会再次调用 TAPD 工具。

Ordinary user/assistant links are observed through public timeline subscriptions and paged history reads. Only exact configured site/project detail URLs are recognized; no TAPD request is made while collecting. Unread references contain only item identity; known compact summaries are reused. Message text is neither persisted nor transformed and native link behavior is unchanged. Tool, reasoning and plugin rows are excluded. Stable message IDs, or ordinary-message position within a turn when IDs are absent, identify source progress independently of timeline sequence/epoch replacement. Streaming completion, reconnect and replacement catch up history; archives, provider closure and teardown release live subscriptions. The next public RPC retries a failed live observation. Source progress suppresses old replay while new explicit messages can recollect removed items; no remote destination is added.

普通消息链接观察只读取 Paseo 公开时间线，按完整分页历史补取并订阅实时用户/Agent 消息；只识别配置域名及项目，未知项仅保存编号，不额外调用 TAPD。消息全文不落盘、不转换原消息、不拦截原链接；工具、推理和插件行均排除。来源使用稳定消息 ID，缺失时使用同轮普通消息序位，避免流式增长或时间线序号/epoch 变化重新收录。归档、运行时关闭及卸载观察器释放实时订阅；临时订阅失败由下次本机 RPC 重试。重放不恢复旧移除项；即使 API 地址改变，同一旧来源也保留原连接解释，新的明确消息才可按当前配置重新收录，不新增网络目的地。

tapd_search and tapd_board persist all returned bounded references and short summaries as batch records, without collecting the whole batch. Timeline rows contain shared connection identifiers, the first five summaries and completeness metadata, capped below the host's 64 KiB UTF-8 data limit. The schema-validated tapd.conversation.batch_page RPC pages the remaining stored summaries five at a time and checks host, agent, batch ownership and current configured connection/projects before returning data. Expanding is local only; selecting a recorded row explicitly collects it and opens the shared detail experience. No descriptions or search attachment bodies are copied into this store. Total (or unknown), returned count, partial failures, stale/cache time and truncation survive restoration; search project/type failures now produce safe completeness warnings instead of appearing as successful empty results. This adds no network destination and recovery never reruns the original query.

批量搜索和看板卡片默认五条，所有已返回摘要均保留并可通过本机分页访问；不自动收录整个批次。卡片保留总数未知、部分失败、缓存和截断信息，空查询与未取得结果分开提示。只有主动点击某张才更新会话入口并读取最新详情；分页和恢复不调用 TAPD。

Confirmed successful creation, comment and status tools also record a single-item operation card and collect the actual target into its calling conversation, including a target previously removed. Creation uses the returned item ID, approved project/title and supplied owner; unknown workflow fields stay unknown. Comment/status use the verified target snapshot, with the chosen status key/label for a successful change. Cards distinguish the operation snapshot from current detail. Comment text, descriptions and full item data are not copied into the local card store. No new destination or write permission is added.

A completed TAPD write remains successful even when a later cancellation, serialization/redaction, local save or timeline append fails. Its tool result provides a safe presentation warning, never an automatic write retry. Failed/ambiguous calls and cancellation before the POST produce no success card; unchanged status is a no-op without a mutation card. Reopening or restoring replays presentation only. The original exact-target confirmation, project/status/parent validation and write cancellation checks remain in force.

成功建单、评论和状态工具操作沿用单张卡片和会话收录流程，使用实际项目及已知摘要；卡片清楚显示操作结果和当时快照，详情始终点击读取。已成功写入不因后续取消、脱敏、保存或展示故障变成失败，返回安全的查询确认提示，不自动重复写入；失败、不确定、写入前取消及未改变状态不生成成功操作卡片。不保存正文和评论内容，不新增网络目的地或权限。

npm run test:daemon is an explicit acceptance command requiring a matching built mainline checkout in PASEO_MAIN_DIR. Its test-only driver starts owned real daemon subprocesses under a fresh temporary home, a fake provider and one stable loopback mock API; only explicitly confirmed mock writes are permitted. Client disconnect, plugin reload, separate-process recovery, alternate host identity, archive/user-prompt restore and exact deletion are checked through real MCP/public timeline/RPC boundaries. Recovery must not perform TAPD reads or replay writes. The runner allowlists inherited environment values, supplies only synthetic fixture credentials, suppresses raw runtime output and cleans up its own temporary data. No production data flow or additional runtime network destination is introduced by this optional test harness.

会话列表中的移除是本机整理操作，不依赖 TAPD 详情读取成功；旧连接校验失败时列表仍可移除。移除最后一项后列表显示空态并隐藏顶部入口，保留已打开的详情 tab。批量卡片在持久化和发布前整体检查凭据，包括零条结果的连接地址、警告及其他摘要元数据；展示失败不改变已完成查询或写入的结果。

会话入口使用 Progress 相同的公开 composer action → openPanel 导航：网页端在 Explorer 侧栏打开按 Agent 隔离的列表；原生手机端使用工作区 tab。单张和多张均先打开列表，选中后打开该单据独立详情 tab，重复打开复用。详情面板复用工作台详情与操作组件，按面板宽度排版；操作表单仍使用带未提交确认的弹窗。列表与详情由宿主面板持有，不挂在输入框图标或临时 popover 内。每张已收录单据按完整连接/项目/类型/单号注册稳定的 panel ID，以支持宿主恢复 tab；移除引用不强制关闭正在阅读的 tab，面板注册在插件卸载时释放。此变更不新增存储文件、配置迁移、网络目的地或 TAPD 写入权限。单张与批量结果卡片统一打开可复用的详情 tab，详情内的关联单据仍沿用当前详情内切换；没有工作区的 Agent 保留详情弹窗。

会话历史读取按 Agent 隔离故障：旧工作目录失效或单个历史不可读时保留重试，不阻塞其他会话的卡片和引用。首次历史扫描及列表等待补扫各最多等待 250ms，超出后继续后台扫描，已保存引用先返回，后续轮询补齐；不把不可访问的历史视为会话删除，不重复执行 TAPD 写入。

随插件提供 paseo-tapd skill，指导查询、接手绑定、阶段推进与验收；需要由目标 Agent provider 的技能发现机制加载，不由插件自动注入现有会话。工具新增 Agent/仓库/模型候选读取、静默绑定和派发：明确授权后可绑定当前或指定 Agent，或新建 worktree 与 Agent、保存关联后发送获批提示词。绑定不修改 TAPD 处理人和状态；派发会将提示词发送给选定 provider，并可能产生费用。部分失败返回已有资源 ID 和阶段，不自动重试或删除资源。

工具关联以原子文件保存在 daemon 本机 plugin-data/tapd-workbench/agent-links.json（相对 PASEO_HOME），包含单据类型/编号、实际 TAPD 项目、API 地址及 Paseo 工作区/Agent 引用，不保存凭据或任务提示词，不参与 Git 设置同步。界面每两秒通过本机 RPC 读取并合并旧关联，支持移除工具关联；旧设置记录保留。工具候选读取只访问 Paseo 本机 API，目标单据验证仅访问已配置 TAPD API；阶段评论通过显式授权的评论工具执行。不新增网络目的地。

会话卡片统一突出标题与状态，使用主题色边条、状态徽标和次要单号/处理人信息；批量条目和侧栏列表保持一致。此展示调整不新增数据读取、存储或网络访问。

会话列表新增搜索、类型计数筛选及紧凑的元信息布局。用户打开会话入口时自动读取列表内单据的标题、状态和处理人，也支持手动刷新，最多两张并发并逐批显示；这是对之前「点击单张才读取」规则的更新。正文、评论和关联单据继续仅在打开详情时读取，历史结果卡片不改写。摘要只访问当前配置的 TAPD API 和项目，更新原有本机引用，不恢复已移除项、不改变顺序、不新增存储位置或网络目的地；失败时保留原摘要并提示重试。后台本机轮询不会触发摘要请求。

会话卡片采用 13px 两行标题与紧凑结果说明；侧栏和批量列表按实际容器宽度（520px）切换单双列，单张结果最大宽度 380px。此布局调整不增加网络请求或改变收录与写入规则。

需求字段与写入恢复

新增 tapd.field_definitions、tapd.read_field、tapd.update_field RPC 及同名下划线 Agent 工具，输入/输出经共享 schema 约束。仅向已配置 API 的 /stories/get_fields_info、/stories 发送请求，项目须已配置、类型须为需求。发现返回实际 description/custom key、label、原始 html_type、readonly 三态及 supported；支持 text/input/textarea/rich_edit/rich_text，不将元数据只读标记当作账号授权证明。其他字段类型仅展示为不支持。

单字段读取显式请求目标列，不依赖丢弃自定义字段的旧详情投影；区分未返回、null 和空串，最多 50,000 字符，原始 HTML 和空白保持原样。读写数据若包含已配置凭据字面值则拒绝，避免脱敏后的旧值造成覆盖。更新要求 confirmed: true 和完整旧值，只 POST 项目、编号及一个目标字段；空串显式发送以请求清空。只读/未知可编辑性/旧值未返回/冲突均在 POST 前拒绝。旧值检查并非原子 CAS，检查与写入之间仍可能存在并发修改。

所有字段元数据和字段读取均 fresh，详情 RPC 支持 fresh、Agent 详情默认 fresh；fresh 绕过缓存和旧在途请求。已发送写入会失效缓存，旧请求不再填回旧缓存。收到成功响应后 fresh 回读，精确匹配才生成字段成功卡片；已接受但回读失败或不一致返回 accepted/unverified，不自动重试。传输层区分未发送、明确拒绝和未知结果，HTTP/业务错误只保留安全 code/status，不输出上游响应、info 或请求体；无法细分的业务拒绝保留为 api_rejected，不猜是权限还是工作流。创建响应成功却缺少编号也归未知，先查询核对。

字段正文及旧值不存入本机卡片或绑定记录，复用已有卡片恢复；恢复不重放写入。普通回合不再触发业务评论，故无该路径重复回评；显式评论并无服务端幂等键或 exactly-once 保证，结果未知先核对最近评论（最多 30 条），需要完整历史时使用已授权同平台页面。真实部署字段、权限及通知链未测试，见 验证与限制。

The controlled field RPCs/tools use only configured /stories/get_fields_info and /stories endpoints. Discovery retains actual keys, raw types and readonly true/false/unknown; only discovered description/custom text or rich-text fields are supported. Reads preserve original text, HTML, null and absent values. Confirmed writes compare the complete old value, POST only the target field with item/project IDs, preserve an explicit empty string, then read back fresh. This is not atomic conditional writing. Only an exact verified match creates a field-success card; accepted/unverified writes remain accepted. Safe errors distinguish not-sent, rejected and unknown without upstream response content. No field bodies are persisted, recovery reuses existing cards and never replays writes. Deployment keys, permissions, HTML normalization and clearing semantics remain unverified; the validation note records controlled tests and environment gaps.

This fork checks the hulkzzhou1/tapd-workbench registry record and its own source repository for updates; the community listing remains subject to registry review.

单据已有 Agent 关联时，详情隐藏「绑定 Agent」「派给 Agent」，解除关联后恢复；「关联任务」区块置于描述前，方便先查看负责处理的 Agent。