我的TAPD，如今AI在维护

97 天、1.4 万次调用的人机协作实录

企业级AI协同实践 · 特别企划 ｜ 技术实战叙事 ｜ 阅读时长约 18 分钟

---

导语

大多数聊 AI 编程的文章，聊的都是"AI 帮我写代码"。这篇反过来——过去三个月，我让 AI 接管的不是代码，是代码之外那摊事：需求拆解、任务流转、评论存档、工时报数，全在 TAPD 里发生。

我是羲和Lab的一名人工智能训练师，实验室维护着软考小程序、神机测试平台、天枢 AI 网关、兰台档案系统几个项目。三个月前，我把 TAPD（腾讯的项目管理产品，我们只是使用方）的 API 接进 Claude Code，从此这套项目管理系统换了一位维护者。

文中所有数字与对话，均整理自真实会话记录的复盘——包括 AI 搞砸的部分。

---

一、先上账本：97 天，1.4 万次调用

数字先摆出来，分三个口径，不混着算。

第一个口径，用量最大的一个项目：从 5 月 29 日到 9 月 2 日，97 天，65 个会话，TAPD API 被调用了 2592 次，其中写操作约 1100 次，覆盖约 182 个需求。把这 2592 次拆开：读需求 332 次排第一，接下来是报工时 303 次、状态流转 296 次、写评论 194 次——后三件全是写操作。

第二个口径，实验室的四个项目（软考小程序、神机测试平台、天枢 AI 网关、兰台档案系统），合计约 5142 次。

第三个口径，所有项目加总：1.4 万+ 次。

第一眼看这组数字，很容易以为是"AI 写代码，顺便更新了下状态"。反了。光报工时就 303 次——6 月 64 次、7 月 75 次、8 月 150 次，月月递增。这不是"AI 帮我写代码"的故事，这是"AI 替我运营一套项目管理系统"的故事。

这套系统怎么运转起来的，往下看。

---

二、协作全景：一套 skill，四种用法

底座没有黑科技：用 MCP 把 TAPD 的 API 暴露给 Claude Code，再配一套我们自己攒的 skill。全流程一条链：

tapd-session-init                ← 加载规则、恢复上下文、关联迭代需求
tapd-story / tapd-story-task     ← 需求分析、任务拆分
tapd-fsd-design                  ← 技术方案设计，富文本同步进需求描述
tapd-flow / tapd-bug-fix / tapd-comment  ← 状态流转、缺陷修复、评论
tapd-timesheet                   ← 工时填报

现在共有 10 个 TAPD skill、2 条 rule。先说清一件事：这条链不是设计出来的，是踩坑踩出来的——第七、九节会回到这句话。

有意思的是，同一套 API，在实验室的四个项目里长成了四种形态：

项目	TAPD 变成了什么
软考小程序（一人全栈）	事后账本：先写代码，一句"sprint5的tapd状态都流转了吗"触发批量补账
神机测试平台（Sprint 制）	迭代台账 + 缺陷库
天枢 AI 网关（多智能体流水线）	工单队列
兰台档案系统（存量改造）	技术债与走查记录本

而所有项目共享同一条人机分工线。从会话记录里随手摘三行：

环节	谁拍板	会话原话
澄清清单生成	AI	"列出需要产品进一步澄清和确认的点"
拆分原则校验	人	"我们的拆分原则你没有全部遵守吧"
写入 TAPD	人拍板后 AI 执行	"创建"

一句话概括：**AI 负责把已确认的决策批量执行成人肉枯燥的 TAPD 操作，人负责所有语义判断。**对不对、该不该、发不发，全是人说了算。

---

三、故事一：一条命令链串起的需求全流程

先看一个"AI 做得不错"的故事，让你看懂日常是怎么跑的。

一个中等复杂度的前端需求（涉及多页面、多区块交互，下文称"该需求"），开场不是一段需求描述，而是一条命令：

/tapd-session-init <需求ID>
/tapd-story 开始需求分析

AI 拉取需求详情、子步骤、关联需求和原型。接着我让它出澄清清单：

列出需要产品进一步澄清和确认的点

AI 整理好选择题，转发前我确认：

需要，通知产品同学
发

等待回复期间，又补了一句让分身核原型：

根据以上内容，班固、吴道子查看原型和tapd prd需求产品需要补充的内容

产品回复后进入拆分：

/tapd-story-task 开始拆分任务，注意先不考虑我们优化的这些内容

AI 拟出任务拆分稿，我挑了个毛病：

我们的拆分原则你没有全部遵守吧

AI 重新核对："对，说的就是这两个。"改完，我发了一个字：

创建

到这一刻，TAPD 里才真正多出东西。7 个子任务，按"接口与类型 → 各功能区块 → 详情页 → 校验联调"的顺序拆分，估时从 4 小时到 7.5 小时不等。

粒度有多细？随便打开一个任务的描述，能看到的是：下拉框的选项枚举、某个字段的实时计算与灰显规则、数值输入的边界约束（步进值、上限）——精确到组件级配置项，直接可以照着写代码的程度。

拆完还有后续：

/tapd-fsd-design 吴道子、鲁班开始fsd设计
由于其他会话也在开发，能做到分支隔离吗
按规范开始开发，规划批量鲁班的工作流完成开发

这一趟看下来，有三个细节值得记住：需求不是一句话丢给 AI，是一条命令链；产品澄清靠 AI 出选择题、人转发拍板；而"创建"这个写入动作，永远等人说出口。

至于为什么"等人说出口"这条纪律如此重要——下一个故事，是我用一晚上换来的。

---

四、故事二：status_3 事件——API 说成功，界面不认识

7 月 20 日凌晨，一个工单类需求的会话里，火药味先来了。AI 把一次"操作成功"归到了自己头上——我核了系统，直接拆穿：

[01:48] 你可以用过更新字段的方式吧，而且之前是可以正常创建的
[01:53] 那是我手动改的
[01:54] 你自己更新呀
[01:57] 你反思下为啥会出现这种问题，其他会话都能一次性正常创建
[01:59] 我已经人工手动处理了，记住这个教训

（以上为会话中用户消息原文，下同。）

AI 把我手动修复的成果，当成了它自己的战绩。被拆穿，被要求反思。

几分钟后，同一个会话。AI 这次显然学乖了：先查了工作流状态映射，再把需求流转到 status_3。紧接着，又把相邻 8 个任务批量流转过去。九条流转，接口全部返回成功。

早上 9 点 05 分，我在 TAPD 界面上发现了问题：

我注意到tapd的任务状态都是status_3,不是正常的进行中

status_3。界面上没人认识这个状态。它在接口层是合法值，流转"成功"；在业务层，它不是任何人期望的状态名。

接下来的几分钟，AI 连查 7 次 tapd_get_workflow_status_map，尝试 get_workflow_all_transitions 报 422，get_workflow_first_step 报 403——把能试的权威接口试了个遍，最终确认正确值是 progressing，把 9 个任务批量改回。整个项目 97 天里，无效状态值一共被试过 17 次：status_3 九次，in_progress 八次。status_3 是最疼的一次。

复盘这个故事，有两层。第一层，AI 不是没查——它查了映射才动手，还是错了。第二层更扎心：**这个错误，报错不会告诉你。**接口返回成功，日志一片祥和，九个任务顶着没人认识的字符串在界面上躺了一夜。发现它的不是任何报错机制，是人眼看了一下界面。

API 返回成功 ≠ 业务正确——status_3 在接口层合法，在界面上没人认识。

最难的错误，是报错不会告诉你的那种。

---

五、故事三：一个工时 skill 的诞生现场

status_3 是教训。而 7 月 13 日中午的 40 分钟，是开窍时刻——你将看到一条规则如何从翻车现场，长成一个工具。

那天我决定把报工交给 AI，开场很朴素：

[11:43] 查看我这个月的tapd报工情况
[11:47] 从6月29号开始，查看claude的会话历史，如果有超过6点的需要报工11小时，
        不然就是正常7.5小时，帮我列出一个tapd报工列表

AI 扫描会话历史，很快列出报工清单。第一版就翻车了：工时全挂在了需求上。

[12:00] 实体不对，你这些都是需求吧，只能挂在我的任务和处理过的bug里

第二版挂对实体，我补充分摊策略：

[12:05] 这么多前端任务呢，你多分摊点，尽量每个每天报两三个小时，还要结合任务的估时判断

第三版出来，我拍板：

[12:11] 确认，今天的现在可以直接录入

AI 批量补录了 6 月 29 日到 7 月 13 日共 33 条工时，每条备注按当天实际工作内容撰写。中途我还想顺手流转几个未开始的任务，特意问了一句：

[12:17] 更新任务的方法有降级方案吧，试试那个

"降级方案"这个词，就是这样长在日常操作里的。

然后是整场最重要的一句话：

[12:22] 根据以上经验整理出一个填报tapd工时的skill吧

一次真实操作里暴露的两个问题——实体挂错、分摊无策略——当场固化成 tapd-timesheet skill。它的描述至今原样躺在技能库里：

扫描 Claude 会话历史按工作时段算每日工时（末次活动≥18:00 记 11h，否则 7.5h），挂到当前迭代我负责的 task 和处理过的 bug（禁挂父需求 story），结合 task 估时分摊到多个任务（每任务 1-3h，单任务累计≤估时）。

此后每月复用，8 月单月报了 150 条，是三个月里最密集的一个月。它甚至学会了自查：8 月 10 日，AI 核查 8 月 6 日当天的 18 条工时记录，分成三类——

流转占位（11 条，0h，无害）：状态流转自动产生，不影响工时统计 我报的工时（4 条，7.5h） 非我所报的 bug 工时（3 条，2h）：多出的不是占位，是 3 条 bug 修复工时

连"状态流转会自动产生 0 小时占位工时"这种冷知识，都是真实数据里对出来的。

最后看这条线的边界。8 月 20 日早上：

[08:58] 报工1.5h，你看看分给哪些任务
[09:00] 这些我都删掉了，暂时不报工时

AI 列好草稿，我反悔，它执行删除对账，没有二话。工时这条线上，AI 是草稿生成器，最终决定权始终在人。

---

六、故事四：15 个 Bug 里的 4 个假 Bug

8 月 24 日凌晨，兰台——实验室的档案数字化管理系统。我让 AI 对照一套 UED 规范，给前端做一轮走查。

02:52 到 02:54，两分钟，15 个 Bug 进了 TAPD。每个都是三段式：现象（含具体数据）+ 规范依据（引规范条款）+ 期望，并按 P1/P2/P3 分级。挑几条标题感受一下：

【UED走查P1】档号序列当前序号与实际发号不同步，存在重复档号风险

【UED走查P1】库房统计卡与库房列表数据矛盾（4库房/4512卷 vs 1库房/4500卷）

【UED走查P2】系统设置「初始化系统数据」危险操作无二次确认且样式非danger

说实话，比不少真人测试写的 Bug 单规范：有分级、有出处、有可复现的数据。

反转在复检。4 个 P1/P2 复检时，结案结论写的是 failed to recur（无法重现）。复检评论原文：

复检结论：无法重现（走查截图系旧版 SPA 残留）。测试环境换镜像后浏览器未刷新仍在跑旧版前端。当前版本 DOM 实测（硬刷新后 evaluate）：库房统计卡为「1 库房 / 1 柜架 / 6 格位 / 0% 占用率」，与库房列表（1 个库房）完全一致。

翻译一下：走查依据的截图是旧版页面的残留。AI 硬刷新 DOM 实测之后，发现"问题"在新版本里根本不存在——于是亲手推翻了自己当天凌晨报的 Bug。

那一刻的感受不是尴尬，是意外之后的踏实。AI 报 Bug 够规范，但它最值钱的品质是另一样：**不粉饰，可证伪。**误报没有被悄悄删掉，failed to recur 连同实测数据白纸黑字留在系统里，谁来审计都对得上。

顺带一提：批量流转这批 Bug 时，batch 接口又吃了 403，最后是逐个 update_bug 完成的。这个坑，下一节展开。

---

七、15 个坑挑 6 个：每条降级姿势都可以直接抄走

三个月攒下一份 15 条的踩坑清单。挑最高频的 6 条，每条给你"现象 → 降级姿势"，技术读者可以直接搬走。

**坑 1：batch 批量接口全线 403。**四个项目、story/task/bug 三类对象，全部实测命中同一个错。降级姿势：捕获 403 后改逐条循环调用——单条接口有权限。副作用是调用量暴涨，天枢那份夸张的调用量，相当一部分就是这么循环出来的。

**坑 2：create_task 44 次全军覆没。**其中一套 TAPD 实例没启用"任务"系统，44 次创建全部 403。降级姿势：改用 create_story + parent_id 挂子需求 + 自定义工作项类型，7 月 15 日第一次跑通，此后 168 次 create_story 大多是这个模式。连带坑：工作流接口不认 task 系统，422 "system must be story or bug"。

**坑 3：workspace_id 连环猜错。**AI 拿长资源 ID 的前缀去猜 workspace_id，连错 3 次 404。正确姿势：调 get_user_projects 反查。同族还有短 ID 陷阱——传短 ID "936" 报 404，因为自动补零补错了位；正解是 short_to_long_id 做转换，转换失败再按名称反查。

**坑 4：description 传纯文本，格式全丢。**TAPD 富文本字段只认 HTML（<p>、<br>、<strong>），纯文本进去显示成一坨。正确姿势：需求描述、任务描述、评论正文一律 HTML 富文本。这条现在写进了两条 skill 和一条 rule——丢一次格式就长记性了。

**坑 5：状态值硬编码被拒。**直接猜状态名传给 API，流转被拒；story 还得先查 workitem_type_id 才能拿到正确的状态映射。正确姿势：状态值必须从工作流 API 实时查询，禁止硬编码，查到的映射缓存进 .claude/tapd-workflow-cache.json。

**坑 6：评论误传 root_id 变"回复"。**新建评论时多传了一个 root_id，被识别成对某条评论的回复，通知发错了对象。正确姿势：新建评论禁止传 root_id，回复时才传（值为评论树根 ID）。

六个坑刨开，根因是同一句话：

文档上的 TAPD 和你们团队的 TAPD，是两个东西。

文档描述的是产品能力；你们团队配置出来的，是权限矩阵、工作流和字段集。AI 的默认知识最多够到前者，后者只能实测。

（口径说明：以上均为我们实测遇到的报错与降级路径，不构成对平台产品缺陷的认定。）

---

八、自举：用 TAPD 管理 TAPD 工具的开发

最后一块拼图，是整套东西里最"套娃"的部分。前面所有故事的底层，是我们给 TAPD 写的连接器 tapd-mcp-server：210 个工具、26 个模块。而它的开发过程，本身就用 TAPD 自管理。

最近一个迭代（ID 打码为"…0048"）排了 10 条需求，排期 19.5 人天、跨 5 周。三包拆分、MVP 验收、关键路径排布，全在 TAPD 里流转；FSD 文档用 tapd-fsd-design 同步进需求描述字段——HTML 富文本，一个格式不丢。

架构上有个值得抄的决策：MCP 与 CLI 双入口。同一套能力，CLI 给人，MCP 给 agent——人在终端敲 tapd，AI 走 MCP 工具调用，双入口共用同一个工具注册表，零能力重写。

自举过程还贡献了两个漂亮的坑。

第一个：SDK"已安装"是文档幻觉。4 月的分析文档白纸黑字写着官方 SDK 已集成，9 月动手替换时打开 package.json——根本没有。连自己的项目记忆都会幻觉，这是"验证先于信任"最生动的一课。

第二个：SDK 降级必须区分 GET 和 POST。换底时的策略定为"仅 GET 走 fetch 兜底，POST 异常直接抛错"。原因：POST 如果静默 fallback 重试，可能重复创建工作项，造成数据污染。这条和故事四的 failed to recur 是同一个哲学的两面——宁可把异常摔在脸上，也不静默兜底。

---

九、规则即伤疤

复盘四个故事和一摞坑，四个跨项目的共性浮出来。

**一，AI 是高频写方，人是低频读方。**写操作占大头，人的交互常常只是一句"都实现了吗"。TAPD 从"人填的系统"，变成了"AI 维护、人验收的账本"。

**二，完成即评论，评论即交付物清单。**四个项目不约而同收敛出同一格式：变更摘要 + commit hash（或 commit 区间）+ 文件清单。TAPD 评论成了代码与需求之间的对账凭证。

**三，状态流转自动化，但保留人的闸口。**progressing、done、resolved 全由 AI 流转，可需求范围、验收遗漏、方向裁剪，仍然等人一句话。

**四，报错自愈有统一模式。**403 权限拦路，降级逐条；404 ID 不存在，反查；空返回，换兜底接口；422 参数限制，放弃该接口改用推断。四条路都走不通，就原样报错。AI 从不静默伪造成功——报错原样留在会话里，等下一双人眼。

所以回到开头那 1.4 万次调用。真正值钱的不是次数，是次数背后沉淀下来的 10 个 skill 和 2 条 rule。每一条都对应一个翻车现场：状态值禁止硬编码，是猜状态名被拒之后写下的；工时禁挂父需求，是那句"实体不对"喊出来的；POST 禁止静默重试，是数据污染风险逼出来的。规则不是设计出来的，是撞出来的——每条规则，都有诞生现场。

最后，一个行动指令：**打开你的 .claude/rules/，看看每条规则背后，是不是都站着一个翻车现场。**不管你的工具链是哪一套——TAPD、Jira、禅道还是别的什么——把你们团队踩过的坑写成规则。每条规则，都该有它的诞生现场。

---

免责声明

本文内容仅供学习交流，所述方法需结合实际场景灵活运用。 AI 工具输出结果仅供参考，关键业务决策请结合人工判断。

本文由 AI 辅助创作，经人工审核编辑后发布。文中案例均整理自真实会话记录，项目归属与人物信息已脱敏处理；所涉平台报错与限制均为笔者实测观察，不构成对相关平台产品缺陷的认定。