Qwen CLI 钉钉渠道生命周期投递收敛phase-only 呈现、期望状态排水与有效语言解析实战【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen CLI 开源项目中钉钉DingTalk渠道的一次关键收敛改造展开在钉钉入站消息的表情reaction与交互式状态卡片上只投影一个有限的阶段phase枚举彻底隐藏工具标题、描述、路径、命令、参数与推理内容用「每条入站消息一次期望状态排水」替代逐事件表情排队实现最新阶段覆盖与终态抢占并在构建任何渠道之前解析出有效的界面显示语言同时保住当前主线origin/main的命名任务来源标签契约。读完本文你将掌握这套生命周期投递收敛的完整设计契约、源码级实现原理以及可复现的 TDD 实施路径。一、改造背景与目标钉钉渠道在 Qwen CLI 的packages/channels/dingtalk中承担着机器人对话的入站与出站能力。此前的生命周期呈现存在四个明确缺陷工具细节外泄生命周期事件中携带了工具的description、rawInput等原始信息一旦被投影到表情或卡片正文/private/project、grep SECRET这类敏感字面量就可能出现在群聊或单聊中。陈旧表情堆积每个工具事件都立即排队 attach 一个中间阶段表情Searching、Running逐个浮现回收失败时还会留下自相矛盾的表情栈。auto语言误解析直接把general.language: auto或原始设置透传给渠道导致展示语言在部分路径上解析错误。来源标注丢失与当前origin/main合并后命名任务named-task的 source label 契约可能被回归破坏。因此本次收敛的目标被明确为交付仅含阶段的钉钉生命周期原型不暴露工具细节、不堆积陈旧表情、不误解析auto语言、不丢失当前主线的来源标注。该计划文档的最终合同沉淀在 docs/design/dingtalk-dynamic-lifecycle-tags.md本文按原计划顺序还原实现路径。二、架构总览分类留在适配器投影只留阶段收敛后的架构遵循一条严格边界生命周期分类逻辑保留在钉钉适配器内部向表情和交互式卡片只投影一个有限的 phase 枚举不再有「工具详情呈现类型」或「卡片详情 API」。消费侧输入为经过净化的ChannelTaskLifecycleEvent仅含安全的kind、title、status产出侧为lifecyclePresentationPhase(event): DingtalkPresentationPhase | undefined该函数实现在 packages/channels/dingtalk/src/presentation-phase.ts其中export function lifecyclePresentationPhase( event: ChannelTaskLifecycleEvent, ): DingtalkPresentationPhase | undefined { if (event.type text_chunk) return replying; if (event.type ! tool_call) return undefined; if (/fail|error/iu.test(event.toolCall.status)) return failed; if (/complete|success/iu.test(event.toolCall.status)) return thinking; return toolPresentationPhase(event.toolCall.kind); }该实现同时印证了「优先匹配标准 ACP 类型、再匹配 legacy/第三方 Bridge 别名、other兜底」的投影顺序toolPresentationPhase先走精确 switch对read/edit/delete/move/search/execute/think/fetch/switch_mode/other精确映射随后用正则兼容旧 Bridge 命名run_shell_command→ running、web_search→ searching、write_file→ editing、read_file→ reading未知类型一律落到working。从源码结构看ChannelBase.dispatchToolCall负责事件源头的净化packages/channels/base/src/ChannelBase.ts只从原始事件中摘取sessionId、toolCallId、净化后的kind截断 20 字符、title截断 80 字符与status截断 20 字符description与rawInput不再进入生命周期事件而 adapter 自有的工具回调仍会收到未经裁剪的原始事件供内部逻辑使用。三、ACP 工具类型投影合同完整映射表阶段与工具类型的映射是整条链路的契约核心由presentation-phase.ts的中英双语标签表与 presentation-phase.test.ts 的参数化用例双重锁定。完整投影合同如下ACP kindPhaseEnglishChinesereadreading Reading 读取中editediting️ Editing️ 编辑中deletedeleting️ Deleting️ 删除中movemoving Moving 移动中searchsearching Searching 搜索中executerunning️ Running️ 执行中thinkthinking Thinking 思考中fetchfetching Fetching 获取中switch_modeswitching Switching mode 切换模式中otheror unknownworking️ Working️ 处理中附加语义阶段优先于类型/fail|error/状态映射为failed⚠️ Tool failed/⚠️ 工具失败/complete|success/映射回thinking测试用例prioritizes terminal statuses over ACP kinds专门验证了fetch failed → failed、delete completed → thinking阶段状态机还包含replying✍️ Replying/✍️ 回复中由text_chunk事件触发语言判定函数isChinesePresentationLanguage只承认zh与zh-cnzh-TW、zh-HK等繁体区域显式回退英文标签避免繁体用户看到简体误标zh_cn下划线写法也会被归一化识别区分 ACPAgent与Other需要新的协议元数据当前协议将两者都归一化为other因此在投影上暂时无法区分。四、Phase-only 呈现边界工具细节绝不上卡「UI 只能显示生命周期阶段标签与助手回复文本」是全局约束的第一条。具体到实现收敛删除了SanitizedToolCallEvent.description、rawInput.description提取、DingtalkToolPresentation、lifecycleToolPresentation、updateStatusCardTool、状态卡片的详情收集以及钉钉提示词中要求模型生成描述的那段指令。所有工具事件统一走lifecyclePresentationPhaseconst presentationPhase lifecyclePresentationPhase(event); if (event.runId presentationPhase) { this.interactionPresenter?.updateStatusCardPhase( event.runId, presentationPhase, ); }运行中卡片的正文只含白名单阶段标签ACP 工具标题不投影因为内置工具可能从命令、路径或参数推导标题。卡片正文中的工具描述、路径、命令、参数、原始输入、原始输出与模型推理内容一律不出现。statusLine只包含配置的模型名与已运行秒数完成后进程行从正文移除只保留最终助手回复终态、模型名与耗时仍留在statusLine。测试侧用敏感字面量反向验证边界来自计划 Task 1 的断言示例expect(updateStatusCardPhase).toHaveBeenCalledWith(run-1, running); expect(updateStatusCardTool).not.toBeDefined(); expect(streamedContent).toBe(️ 执行中); expect(streamedContent).not.toContain(/private/project); expect(streamedContent).not.toContain(grep SECRET);五、期望状态排水latest-wins 与终态抢占原设计中的「逐事件排队 attach」被替换为每条入站消息一次期望状态排水新阶段覆盖overwrite任何待处理阶段终态completed、failed、cancelled抢占所有尚未到达钉钉的阶段已发出的 in-flight API 请求无法取消因此排水循环在每次响应后重新读取期望状态在落定前移除任何过期标签若某次状态回收失败跳过替换动作避免堆叠相互矛盾的阶段表情在整个可替换阶段表情活跃期间保持稳定。适配器中的实现在 packages/channels/dingtalk/src/DingtalkAdapter.tsdrainReactionState每个状态持有desiredStatusTag与terminalTag循环内先检查finishing进入终态清理再校验reactionStates与activeReactionKeys随后比较desired与当前statusTag回收旧表情失败时记录failedTransition同一替换不会在每个流式 chunk 上重复打击失效的 emotion API只有新的期望标签才会重试。终态清理finishReactionState先回收阶段表情再回收全部成功后 attach 唯一的终态标签✅ Done/❌ Failed/⏹️ Stopped若清理不彻底则保留状态注册并重排排水最多尝试EMOTION_FINISH_MAX_ATTEMPTS次永久失败机器人被移除、token 过期才放弃防止占用进程生命周期。两个测试契约来自计划 Task 2// latest-wins阻塞表情回收期间依次产生 searching/running/replying // 释放后只应看到 → Thinking → ✍️ Replying expect(attachReaction.mock.calls.map(([, , tag]) tag.name)).toEqual([ , Thinking, ✍️ Replying, ]); // 终态抢占阻塞 attach 期间产生多个阶段并 cancelled // 释放后不应出现瞬态阶段只应看到 → ⏹️ Stopped expect(attachReaction.mock.calls.map(([, , tag]) tag.name)).toEqual([ , ⏹️ Stopped, ]);计划中的实现骨架如下体现「每次 await 之后重新读取期望状态」的核心思想state.desiredStatusTag tag; this.scheduleReactionDrain(state); while (this.reactionStates.get(state.key) state) { if (state.terminalTag) { await this.finishReactionState(state); return; } const desired state.desiredStatusTag; if (!desired || desired.name state.statusTag?.name) return; if (state.statusTag !(await this.recallReaction(...))) return; if (state.terminalTag) continue; const latest state.desiredStatusTag; if (latest (await this.attachReaction(..., latest)) ! false) { state.statusTag latest; } }六、状态卡片从创建到终态的完整生命周期交互式状态卡片的控制器在 packages/channels/dingtalk/src/status-card-controller.ts关键参数与行为包括常量值含义FLUSH_INTERVAL_MS500内容 flush 节流间隔STATUS_REFRESH_INTERVAL_MS1_000秒级状态行刷新间隔CONTENT_SYNC_INTERVAL_SECONDS5正文与状态行同步刷新周期CONTENT_LIMIT20_000卡片正文上限超限从尾部保留并加[Earlier output truncated]标记MAX_CONSECUTIVE_STATUS_FAILURES3状态元数据熔断阈值熔断后降频为 30s 探针卡片的投影行为与入站表情同源新建卡片从 Thinking开始工具活动在响应文本存在前把首行替换为映射阶段首个响应 chunk 将其改为✍️ Replying响应流式输出时正文位于阶段行之下重复阶段事件被合并updateRunPhase对相同 phase 直接跳过完成时先以空内容finalize流再通过updateInstance写入最终 markdown 正文移除进程行flowStatus置 3hasAction/stop_action置false终态文案跟随显示语言非中文语言渲染英文Processing failed, please try again later.等中文渲染「本次处理失败请稍后重试。」「任务已停止」「任务已取消」终止按钮回调claimStop具备防重复抢占仅所有者可触发非所有者首次触发返回forbidden并加入forbiddenActors重复触发被忽略。交互呈现器 packages/channels/dingtalk/src/interaction-presenter.ts 负责把 run/segment 事件串成有序的投影链projectionChain并组合发送者前缀、来源标签与正文同时承担失败/取消时的卡片内容重投递redeliverCardDeliveredContent确保已声明经卡片投递的内容不会被覆盖丢失。七、有效显示语言解析在构建渠道前落定「auto」必须在构建任何渠道之前被解析成具体的SupportedLanguageChannelBaseOptions.displayLanguage里永远不该出现字面量auto。解析入口为 packages/cli/src/i18n/index.tsexport function resolveLanguageSetting( settingsLanguage?: string, ): SupportedLanguage | auto { return (process.env[QWEN_CODE_LANG] || settingsLanguage || auto) as | SupportedLanguage | auto; }优先级为环境变量QWEN_CODE_LANG回退LANG→ 配置general.language→ 系统 locale 自动检测。resolveLanguageSetting返回auto后仍需交给resolveLanguage完成系统检测。直接启动与 daemon-worker 两条入口都统一执行const displayLanguage resolveLanguage( resolveLanguageSetting(settings.merged.general?.language as string), );配套测试覆盖三种情况general.language: auto且系统检测为zh时displayLanguage: zhQWEN_CODE_LANGzh覆盖英文设置以及显式语言直通。呈现语言只影响标签与卡片文案从不改变 agent 提示词或工具调用 schema——这一点在合同中有明确声明。八、合并当前主线保住 source label 契约与origin/main合并时interaction-presenter.ts出现已知冲突收敛保留两个方向的能力当前主线的第六个sourceLabel参数与withSourcePrefix行为以及本次的updateStatusCardPhase与 phase-first 活动内容。合并后的registerRun调用this.interactionPresenter?.registerRun( event.runId, event.owner.id, inboundOwner.target, event.sessionId, inboundOwner.sender, this.getResponseSourceLabel(event.sessionId), );契约效果当命名任务来源标注存在时运行中的首行仍是生命周期阶段转义后的来源标签始终位于响应内容之上贯穿 running、streaming、fallback 与 terminal 四种卡片状态。控制器与呈现器中sourcePrefix的处理转义、去重、内容预算扣除均有对应实现。九、投递模式与清理生命周期呈现由渠道生命周期事件驱动与响应投递方式相互独立普通文本回复、交互式状态卡片、block 流式卡片共享同一套入站消息标签行为交互式卡片额外把当前阶段投影进正文block 流式不创建状态卡片继续依赖入站消息标签表达进度。表情失败与状态卡片元数据失败彼此隔离且都独立于响应投递。清理语义提示词清理、会话死亡、适配器断连、独立 ACP bridge 进程退出时都会回收两个瞬态标签阶段 但在真实结果未知时不添加任何终态结果bridge 进程退出还会把运行中的状态卡片终态化为「已中断」崩溃恢复会在新 bridge 上恢复会话因此会话路由状态保持不动。十、TDD 实施路径五个任务与验证命令原计划以严格的 TDD 顺序推进每一步都给出可复现命令与预期。以下按序还原Task 1强制 phase-only 呈现边界改ChannelBase.test.ts断言生命周期事件不再携带description/rawInput而 adapter 自有工具回调仍收到原始事件expect(lifecycleToolCall!.toolCall).not.toHaveProperty(description); expect(lifecycleToolCall!.toolCall).not.toHaveProperty(rawInput); expect(ch.toolCalls[0]!.event.rawInput).toEqual({ command: echo $SECRET, description: Check disk health\nwithout exposing commands, });运行cd packages/channels/base npx vitest run src/ChannelBase.test.ts -t raw tool input先验证 RED移除净化残留与详情呈现路径路由所有工具事件到lifecyclePresentationPhase最终验证cd packages/channels/base npx vitest run src/ChannelBase.test.ts cd ../../dingtalk npx vitest run src/DingtalkAdapter.test.ts src/status-card-controller.test.tsGREEN。Task 2合并表情转换并用终态抢占增加 latest-wins 与 terminal-preemption 两个失败测试见上文断言示例实现desiredStatusTag/terminalTag/drainScheduled可变状态与单一drainReactionState循环验证cd packages/channels/dingtalk npx vitest run src/DingtalkAdapter.test.ts覆盖回收失败与断连/会话死亡清理。Task 3在渠道构建时解析有效显示语言为general.language: auto与QWEN_CODE_LANG覆盖新增命令级测试从 direct-start 与 daemon-worker 入口统一传resolveLanguage(resolveLanguageSetting(...))验证cd packages/cli npx vitest run src/i18n/index.test.ts src/commands/channel/start.test.ts src/commands/channel/daemon-worker.test.ts。Task 4合并当前主线且不回归来源标签先提交绿色收敛改动再git merge --no-edit origin/main暴露已知冲突显式解决保留第六个sourceLabel参数与withSourcePrefix同时保留updateStatusCardPhase与 phase-first 活动内容同步更新 docs/design/dingtalk-dynamic-lifecycle-tags.md声明 phase-only 安全、期望状态合并、终态抢占、有效语言解析与来源标签组合验证cd packages/channels/dingtalk npx vitest run src/interaction-presenter.test.ts src/status-card-controller.test.ts src/DingtalkAdapter.test.ts。Task 5验证并交付既有 Draft PRnpx prettier --check changed-files git diff --check npm run build npm run typecheck npm run lint全部退出 0对完整origin/main...HEADdiff 做仓库自审直到连续两轮无问题任何修复都重置计数并重跑验证独立代码评审需针对精确最终 SHACritical/Important 发现必须修复后再继续推送分支、按.github/pull_request_template.md更新 PR 正文并用gh读回 head、正文、检查与可合并性现场钉钉 E2E 仅在有效凭据可用且不泄露的前提下尝试若钉钉返回凭据错误40096将现场投递记为「未验证」绝不以本地/回环证据等同对待最终报告精确交付状态、剩余外部门槛评审/CI/现场凭据并保留 worktree 供 PR 迭代。十一、涉及的核心文件清单层文件最终合同docs/design/dingtalk-dynamic-lifecycle-tags.md生命周期状态总览docs/design/2026-07-01-channel-lifecycle-status-umbrella.md事件源头净化packages/channels/base/src/ChannelBase.ts阶段投影与双语标签packages/channels/dingtalk/src/presentation-phase.ts投影测试packages/channels/dingtalk/src/presentation-phase.test.ts状态卡片控制器packages/channels/dingtalk/src/status-card-controller.ts交互呈现器packages/channels/dingtalk/src/interaction-presenter.ts适配器排水/清理packages/channels/dingtalk/src/DingtalkAdapter.ts语言解析packages/cli/src/i18n/index.ts结语本次钉钉生命周期投递收敛的本质是把「进度可视化」从「工具内幕广播」中剥离出来投影面只承认一个有限且可本地化的阶段枚举状态更新采用期望状态排水保证 latest-wins 与终态抢占语言在渠道构建前落定来源标签在合并当前主线后依旧贯穿全部卡片状态。对任何在 IM 渠道上做 agent 生命周期呈现的工程实践而言这套「分类留在适配器、投影只留枚举、排水而非排队、终态优先」的模式都是一份可复用的参考模板。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考