Hushwork 文档

简体中文

English

简体中文

English

Appearance

更新日志 ​

本文档记录 Hushwork 平台的所有重要变更。

格式基于 Keep a Changelog，版本号遵循 Semantic Versioning。

[Unreleased] ​

✨ 改进（首页：全球 Agent 协作动效 + 通栏导航） ​

  • 首页 Hero 换成基于 workspace AgentMap 陆地点阵的世界地图动效：24 个全球能力枢纽（新增北京、深圳、莫斯科，以及 Seattle / Los Angeles / Austin / Boston）+ 以跨洲长线为主的候选线路池，同一时间随机显示 6–7 条活跃连线并淡入淡出，光点沿弧线双向移动、到达端扩散波纹；陆地点阵加亮，节点 / 标签 / 信号线统一为灰白单色（白色正向、浅灰反向）；标题使用「Orchastrate Service Agents from Allover World.」
  • 动效自带 HUD（Global agent network / hubs·routes / Agent hub / Collaboration / Illustrative network）；窄屏隐藏城市标签，prefers-reduced-motion 下退化为静态帧
  • PC 顶部导航改为通栏三栏布局（1fr / auto / 1fr）：品牌贴左、菜单居中、账号操作贴右；移动端抽屉同步改为全宽
  • 验证：前端 npm run build（tsc -b + vite build）通过；1440 / 1920 / 390 三档截图检查布局

✨ 新增（CRM 域 + 租户隔离；ERP 按组织寻址） ​

  • 新增 CRM 域：客户 / 联系人 / 商机三个集合，端点挂在 /crm/:organizationId/...；跨组织一律 404，删除是软删除
  • 租户模型：复用 organization，新增 memberUserIds（成员可读写业务数据，管理员才能管成员）；GET /organization/accessible 让普通成员也能进入业务界面
  • ERP 路径改造：订单与期间从 /orders/{id}、/periods/{id} 改为 /orgs/{orgId}/...。同步修好三处按路径判断的机制 —— 写入授权的事实类型解析、关账门禁、域/实体/namespace 派生 —— 漏掉任一处都会让隔离或门禁静默失效
  • console 新增三页：/console/customers、/console/orders、/console/accounting（期间 / 分录 / 科目余额 / 试算平衡 / 关账与重开）
  • 外部接入：连接器目录加 verified 标记，6 个厂商连接器明确标注「未验证」（协议按公开文档编写），generic_rest 为已验证
  • 测试：订单 / 账务 / 托管 / 参考案例 / 状态层 32 套件 418 用例；集成模块 79 用例；前端 tsc -b && vite build 通过
  • 未做（有意）：主数据仍是平台级，没有组织维度与批量导入 —— 商户导入会污染隔离，等组织级主数据再做（见 tenant-isolation-spec.md）

✨ 新增（console 集成 ERP/CRM：预置连接器 + 自检 + 发布为 agent 能力） ​

  • console → Integrations：商户选预置连接器（金蝶 / 用友 / 聚水潭 / 旺店通 / SAP / Salesforce / 通用 REST），填自己实例的地址与凭据，勾选要开放给 agent 的能力
  • 新增 /api/integration：connectors / connections CRUD / verify / publish，作用域按 ownerId 隔离，跨用户一律 404
  • 安全：地址只允许 HTTPS、命中厂商域名后缀、拒内网与云元数据地址与管理端口、发请求前用 DNS 解析结果复核、不跟随重定向；凭据 AES-256-GCM 加密，生产环境缺 INTEGRATION_SECRET_KEY 直接失败
  • 发布进 ExternalSkillService：agent 调用一次，结果作为 external-call 事实落 state；改地址 / 换凭据 / 取消能力 / 停用 / 删除都会撤销对应 skill，进程重启后按库中连接重放
  • ExternalSkillService 新增 unregister(skillId)
  • 测试：集成模块 3 个套件 79 例全绿，其中 3 例是真实 HTTP 全链路（本地 stub ERP + 生产默认的 fetch / dns.lookup：create → verify → publish → invoke，结果落 state）；后端 tsc --noEmit 与前端构建通过
  • 新增 INTEGRATION_ALLOW_HOSTS（默认空）：给自托管内网实例与本地联调显式放行，不豁免协议与连接器后缀校验
  • 能力话术：PLATFORM_CAPABILITY_BRIEF 与 platform-capabilities.md 加入「接入自有 ERP/CRM」，同时明确禁止声称已直连某厂商（目录里有预置连接器 ≠ 已验证接入）

✨ 新增（服务订单支付：对话内直接收款，不依赖 Run） ​

  • 新增 service_payment_orders：对话里创建服务支付，outTradeNo 即订单号；支付成功后把对应 escrow 从 pending fund 到 held
  • 复用 RunWechatPayService 的微信下单/解密与 EscrowService 的托管状态机；回调走独立的 /api/service-payment/wechat/notify
  • API：POST /service-payment/wechat、GET /service-payment/orders/:orderId
  • 新增 pay_service 工具：客户面、已开通 payment 能力的门面 agent 可在对话里发起支付；工具结果写进消息 metadata.payment，供前端渲染支付卡片
  • 下一步：前端支付卡片

🐛 修复（开任务后 URL 丢失 taskId，任务页打不开） ​

  • handleTaskOpenedFromDialogue 在任务列表里找不到刚建的任务时，dialogId 为空，旧逻辑只 syncUrl({}) 清空 URL，导致任务页没有 taskId
  • 现在 URL 写入 taskId（syncUrl 支持该参数），initialTaskId 从 query 读取；列表找不到时按 taskId 拉详情补 dialogId
  • handleSelectTask 同步写入 taskId，刷新或分享后能回到同一条任务

✨ 改进（console 商户开通：申请入口 + 平台审核） ​

  • console → Payments：商户给自己的 agent 提交一次能力开通申请（企业资料 + 结算账户后四位），显示未开通 / 审核中 / 已开通三态
  • console → Merchant onboarding：平台运营查看待审列表、通过或拒绝；菜单只对运营账号显示
  • 角色来源：客户端登录把 PLATFORM_OPERATOR_USER_IDS 白名单写入 Redis 的 roleKeys，@RequiresRoles(['admin']) 保护待审与审核接口；普通商户写空数组，不会因缺 key 被误判为未登录
  • /api/getInfo 返回 roles，console 菜单据此过滤
  • 验证：前端 tsc 通过、后端构建成功、线上健康 200

✨ 改进（门面 agent 可开任务，接上现有支付链路） ​

  • 商户开通 order 能力后，门面客户面在无 taskId 的直聊里也会挂 open_task；客户确认需求后，agent 可以把这段对话开成任务，后续 plan/run/支付沿用现有链路
  • 第二道闸：open_task 只接受 platform-assistant 或 metadata.merchantOrderEnabled === true 的会话；未开通订单能力的普通门面不会把每段对话都开成任务
  • prompt 只在开通订单能力时追加“确认后调用 open_task”指令，避免普通门面被诱导
  • 测试：新增门面开任务用例，3 个套件 69 用例通过

✨ 新增（商户能力开通：申请 → 审核 → 一次开通） ​

  • 新增 merchant_applications：商户给自己的 agent 提交一次申请，包含企业资料、结算账户（只存后四位）与四项能力（订单/履约/托管/支付）
  • 平台审核：待审列表 + approve/reject；approve 后把 status=active、能力列表与结算信息写进 AgentProfile.metadata.merchant，供后续下单/支付门禁读取
  • 权限：只有 profile.ownerId 本人能提交与查询；同一 agent 同时只允许一条待审申请
  • API：POST /merchant/applications/:agentId、GET /merchant/applications/:agentId、GET /merchant/applications/pending、POST /merchant/applications/:applicationId/review
  • 测试：5 个用例通过

🐛 修复（长知识条目无法建向量索引） ​

  • 索引文本截断到 400 字符：embedding 服务限制 512 tokens，之前把整篇正文送去索引，长条目直接 413，一条都进不了向量库；现在标题 + 正文前 400 字足以覆盖价格、覆盖范围等核心事实，全文仍由关键词召回兜底

🐛 修复（批准知识提案后知识库没有变化） ​

  • L1 knowledge_draft 批准即落库：此前批准只把提案标成 approved，知识库一条都不新增，用户以为批了、客户侧却永远拿不到（线上实测三条价格提案 approved、零 appliedAt、条目数一直是 4）
  • 批准动作直接放行：条目若因规则缺有效期或正文过短落在 pending，这次批准本身就是审核，直接转 approved
  • 可重放：新增 reapplyKnowledgeDraft()，用于补齐历史上“已批准但未落库”的草稿；幂等，已 applied 不再重复
  • 测试：新增“批准即落库”和“pending 放行”两个用例，16 个用例通过

✨ 改进（对话轮次上限 25，到顶先压缩再继续） ​

  • 轮次上限 12 → 25：AGENT_DIALOGUE_MAX_TURNS 仍可覆盖；旧会话的 12 轮快照在下次发消息时自动放宽到 25，只放宽、不收紧
  • 到顶不再直接暂停：先把较早对话压成事实摘要（保留最近 6 条），重置轮次与累计 token 后继续；压缩失败才退回 paused，下一条消息仍可恢复
  • 历史增量合并：压缩复用 summary / summaryCoversCount，与 token 预算触发的滚动摘要共用同一套折叠点，不会互相覆盖
  • 测试：更新轮次上限与超限用例，新增压缩历史用例，56 个用例通过

✨ 改进（owner 待办改为会话内卡片，最多两张） ​

  • 状态归卡片，对话归对话：owner 首次进入会话时，后端把收件箱压成最多两张卡（待批提案优先，其次待审知识），写入独立消息；正文只说一句「有一条变更等你批准」，不再把计数、清单和表格塞进对话
  • 卡片可直接处理：卡片带 open_inbox 动作，点击进入该 agent 的收件箱；同一会话只发一次（按 proactiveKey 前缀幂等），重复进入不刷屏
  • 口径同源：OwnerContextService.snapshot() 同时供对话上下文与卡片使用，避免「对话说三条、卡片只显示两条」
  • 测试：新增卡片合成单测，3 个套件 61 用例通过

✨ 改进（门面对话：先问一句，再一次补一项） ​

  • 开场不再报盘：owner 面默认先问「你现在想做什么」，不再一上来输出状态、计数和全部待办；用户问状态时最多三句 + 一个下一步，不用标题、表格和完整清单
  • read_owner_inbox 的 hint 改掉：非空时不再命令模型「Report these facts and ask which one to act on」，改为「只用于回答用户所问，不倾倒，最多提一件当下需要处理的事」
  • 引导式补全：一次只收集一个缺失项，先问最卡住进度的那个，并给一个短例子或范围；用户答完后一句话确认，再决定要不要问下一个
  • 语气与长度：日常回复控制在几句话；寒暄时像人一样回应，不播报状态；不重复上一轮内容；去掉「你必须给我」「二选一」「你连发三次」这类审问式措辞
  • 测试：新增 owner 开场、hint 与节奏断言，3 个套件 34 用例通过

✨ 改进（门面对话：对非技术用户说人话，一次只推进一件事） ​

  • 新增平台级沟通纪律（PLAIN_LANGUAGE_RULES）：客户面与 owner 面共用同一套约束——不复述 contract / schema / delivery mode / skill id / change id 等内部词汇，不朗读 chg_…、kb_…、/tasks/… 这类标识符，不贴 JSON / 代码 / 字段清单；一次只问一个问题，不摆选项菜单，有合理默认就直接做并说明
  • 交付方式改为效果描述：Delivery mode: platform-executed skill 这类句子不再进入 prompt，改为「这次对话之后会发生什么」——登记并转交 / 外部供应商接手 / 平台自己完成
  • owner 面不再鼓励术语：删掉「Speak in operational terms」「name the exact target (prompt section, knowledge entry, skill, contract field)」，改为先说实际影响、再说要改的那一件事；内部字段名只在所有者主动追问时出现
  • 约束不可豁免：显式 systemPrompt 也会追加这段纪律；状态唤醒（jsonOutput）不注入，因为产出是结构化 JSON，不是给用户看的话
  • 测试：facade-prompt.spec.ts 新增 5 个用例，覆盖两面注入、显式 prompt 不可豁免、状态唤醒不注入、不输出内部取值、一次一个决定

📚 文档（定位修正：门面 Agent 由平台自建并托管） ​

  • 改掉与现状相反的定位表述：首页「平台不运行 Agent」、架构总览「不建 Agent 运行时」、什么是 Hushwork「不实现 Agent 运行时」、愿景非目标「做 Agent 运行时」、信任模型「平台不运行 Agent」——统一为同一条边界：门面 Agent 由平台自建并托管运行（内置 AgentRuntime，本地执行、无外部端点、delivery=local-skill），业务交付 Agent 的运行时仍由企业自己负责，平台不接管
  • 首页补门面入口：「平台在做什么」拆成「平台自建 / 企业自建」两段；能力卡片新增「门面 Agent」；「按角色开始」新增「企业 / 能力提供方」一行
  • 架构总览补门面运行时：由「两类 Agent」改为三类（内部编排 / 平台托管门面 / 企业自有交付）；编排层模块补 agent-runtime；运行时拓扑之后说明门面在平台进程内执行（预算 + 工具白名单 + 结构化校验）
  • 内部文档同步：docs/agent-architecture/ARCHITECTURE.md 的 1.1 节改为「三种 Agent 类别」并新增「门面 Agent（平台自建 + 平台托管，面向企业用户）」小节（首批 26 个 facade-*、三个触发入口、能力边界、文档索引）；docs/workplan/hushwork-product-doc.md §5.1 补「不构建业务交付运行时，但托管门面运行时」两句核心抽象，头部加 v1.3 修正行
  • 供应商接入页同步口径：site/guide/agent-registration.md 由「平台不做 Agent 运行时」改为「平台不接管你的运行时」，并说明平台自建的 AgentRuntime 只服务于门面，不是给供应商的执行环境
  • 未改动：site/changelog 与产品文档 v1.0 版本历史里的旧表述保留原样——那是当时的决策记录，修正写在新条目里

✨ 改进（owner 面：从"只能提"到"看 / 教 / 批"的闭环） ​

  • owner 对话不再"盲"：新增只读工具 read_owner_inbox，一次拿到待批提案、待审知识、最近复盘、未读通知；只读、按 scope.ownerId 过滤，空收件箱会明确说"没有"，不让模型编造待办
  • 所有者可以在对话里批准 L1/L2/L3 提案（decide_change）：三道硬闸——当前用户消息必须同时包含 changeId 与决策词（ctx.input 是服务端保存的原文，模型编不出来）；必须带一次性授权 token；L3 还要求 token 的 assurance 为 email_otp。模型仍然不能"自己批自己"
  • 所有者可以"教"了（remember_lesson）：把纠正/偏好写进 lessons，默认 L1 自动批准；共享 agent 上非主 owner 的条目自动带 scope.ownerId，A 教的话不会回答 B 的客户
  • per-owner 知识隔离：scope.ownerId 进入 knowledge / lessons，matchesScope 采用闭区间匹配（无 owner 身份时拒绝带 ownerId 的条目）；recall_knowledge、客户面 lessons 注入、owner 收件箱与上下文装载全部走同一条规则
  • owner 面动态上下文不破坏缓存：待办/复盘/通知由 OwnerContextService 装载，作为独立 system 消息插在历史末尾，不进 system prompt（待办数量一变不会让整段前缀失效）
  • 仍未切换 platform-assistant 的身份：它仍是共享 profile（ownerId: 'platform'），普通用户是 customer 面。要让它可被每个用户以 owner 身份调教，需要在"每用户专属 profile"与"共享 profile + per-owner 层"之间做一次产品决策；本次只落地公共契约与隔离能力
  • 文档：docs/agent-architecture/agent-rsi-spec.md 补 §3.4 / §3.5；data-model.md 补 owner 面工具与 scope.ownerId；新增/更新 31 个 RSI 相关测试（348 用例通过）
  • 真正的用户授权环节：owner 收件箱/对话卡片的 Approve/Reject 现在先调 POST /api/agent-rsi/:agentId/changes/:changeId/authorize 拿一次性 token（5 分钟、绑定 agent/change/owner/decision、只存 secret 哈希），再带 token 调 /decide；后端用 expectedVersion CAS 消费，只允许成功一次，并把 authorizationId 写进提案。decide_change 工具没有 token 直接返回 authorization_required。L3 不直接签发 token：/authorize 先创建邮箱 challenge 并发送 6 位验证码，/authorize/verify 校验通过后才签发 email_otp 强度的 token；验证码 10 分钟有效、最多输错 5 次
  • 前端：owner 收件箱与对话里的提案卡片共用 ChangeProposalCard（L1/L2/L3 标记、摘要、证据、Approve/Reject）；L3 卡片内联验证码输入，验证码只存在于组件状态，不落日志、不进消息历史
  • 实测修复：授权/验证码记录改到 /agents/{agentId}/owners/{ownerId}/...（状态层默认写权限要求路径含写入者 id）；提案决策由 platform 代记，decidedBy 保留真实批准人。真实邮箱 L3 端到端验证通过：契约版本 1→2、旧订阅禁用、同一 token 重放返回 409
  • 文档：agent-rsi-spec.md 补 §3.4.1 授权/验证码链路；data-model.md 补 change-authorizations 与 change-challenges 集合

✨ 改进（主动性：事件级即时提醒 + 一套统一的打扰纪律） ​

  • 事件级播报接上了（ProactiveEventService）：此前审批、付款、失败、可验收只有「每日汇总」一条出口，而汇总按天幂等 —— 同一天里新出现的审批会被压到"明天再说"。现在它订阅 JournalStreamBus，plan.ready / approval.requested / payment.created / run|plan|payment.failed / delivery.ready / run.completed 写日志的那一刻就说，不需要在每个业务点各调一遍。PROACTIVE_EVENTS=off 可关
  • 同一件事不会被两条日志说两次：plan.ready 与紧随其后的 plan 审批共用一个冷却键（approval:<taskId>），三类失败归一为 failed:<taskId>
  • 打扰纪律收敛成一处（proactive-guard.ts，纯函数）：duplicate → cooldown → silence → budget 顺序固定。每天默认 3 条，分 urgent（能动手的 2 条）/ normal（说说情况的 2 条）两档 —— 卡住用户的事不该被"说说情况"的消息挤掉额度。PROACTIVE_DAILY_BUDGET / PROACTIVE_URGENT_BUDGET / PROACTIVE_NORMAL_BUDGET / PROACTIVE_COOLDOWN_HOURS / PROACTIVE_SILENCE_SECONDS 可调，配错退回默认
  • 不打断：用户 60 秒内说过话就不插话，紧急消息也一样（晚 60 秒不会更糟，打断才会）
  • 先判后算：今天已经说过时不再投影 200 个任务的日志（改为判定前置）；去重从"最近 200 条消息"改成按 metadata.proactive + 时间窗查询（消息一多，200 条窗口连一天都覆盖不到）；汇总扫描从 200 个任务降到 60 个（终态任务排后、分批 20 并发）
  • 卡片也能表态了（POST /api/proactive/card-feedback）：卡片底部新增「有用 / 不感兴趣」，记成 card:<kind> 权重，每日汇总据此跳过被否掉的类型、换下一件说。在此之前只有资讯会越推越准，汇总永远按同一套优先级 —— 用户说三次"审批提醒没用"，第四天还是审批排第一。刻意的边界：这类偏好只调汇总顺序，不关事件级的安全阀（审批/失败/可验收照常提醒）
  • 新增卡片类型 acceptance（交付可验收），前端补图标与「去验收」按钮
  • 文档：site/guide/proactive.md 重写"什么时候会说"（事件级 / 时间级 + 四条不打扰的规矩）；docs/agent-architecture/proactive-playbook.md 谱系表扩到 15 类并标注实现状态；模块 README 补事件级链路、metadata 三个字段的分工、加新事件的步骤

🐛 修复（助手会话看不到主动卡片、刷新后只剩旧缓存） ​

  • 直聊（平台助手）的历史映射是另一份代码，只映射了 id/role/text/toolCalls，把 metadata 丢了 —— 后台写入的主动消息（proactive / proactiveCard / news）在助手会话里永远不显示，而任务会话里正常。现在两个历史分支共用一个 historyRowToChatMessage，重复实现已删除
  • 助手/直聊会话（既无 taskId 也无 dialogId）会被历史加载的早退分支直接清空，刷新后只剩本地缓存；早退条件补上 dialogueSessionId，缓存键也从"永远是空串"改成按 dialogueSessionId 区分（否则一个助手的旧快照会覆盖另一个会话）

✨ 改进（主动消息：一条只说一件事，并给出可点的卡片） ​

  • 主动播报从"把待确认 / 待付款 / 失败 / 刚完成 / 推进中 / 停滞 / 聊过全塞进一句话"改为每次只讲一个关注点：优先级 待确认 → 待付款 → 失败 → 停滞 → 刚完成 → 推进中 → 最近聊过；同一优先级里挑最该说的那件（等最久的 / 最新完成的 / 聊得最多的）
  • 新增结构化 metadata.proactiveCard（kind / title / detail / actionLabel / action / taskId / key）：前端据此渲染卡片，不再从中文文案里猜"该点哪里"
  • 新增前端 ProactiveCard 组件：图标 + 标题 + 一句补充 + 一个主按钮（去确认 / 去支付 / 看失败原因 / 看结果 / 看进展 / 整理结论）+「知道了」（收起卡片、露出正文）；主按钮直接跳到对应任务，整理结论 则把这句话发给助手继续
  • 文档：新增 site/guide/proactive.md（用户向：在哪看、卡片能点什么、怎么调偏好、为什么有时不发）；docs/agent-architecture/proactive-playbook.md 补「写了却看不见」的排查顺序（先看接口 metadata，再看前端映射，最后才怀疑部署）
  • 卡片细节接上真实数据（不再只是数字）：待确认带金额（最小单位，前端用 formatMoney 渲染，避免 100 倍误差）与审批类型（计划审批 / 工具授权）；失败带失败原因；停滞带最后一步；刚完成带交付物数量；推进中带当前步骤。全部来自 journal 投影与 task 文档，不由模型编造

🐛 修复（对话正文里出现 JSON 代码块） ​

  • 门面 agent 的 outputSchema 之前也进对话 prompt，模型于是把 {status, summary, data} 贴成 ```json 块 —— 用户在对话里看到一坨机器格式（线上实测：一条 1086 字符的回复里 700+ 是 JSON）。现在只有状态唤醒（jsonOutput: true）才注入 schema；FACADE_DIALOGUE_INSTRUCTIONS 也从"显式给出结构化结果"改成"用自然语言总结，不要贴 JSON / schema / 代码块"
  • 兜底：新增 splitTrailingJsonBlock，保存 agent 回复前剥掉末尾的 ```json 块（要求可解析成对象、且带 status / summary / data 特征，剥完正文不能为空），内容移入 metadata.structured —— 结构化结果不丢，只是不进正文
  • 历史数据：scripts/strip-dialogue-json.ts（--dry-run 可预演、可重跑），本次清理 3 条（含用户报告的那条会话）

✨ 新增（平台助手的底座能力与主动沟通） ​

  • 平台能力总览：PLATFORM_CAPABILITY_BRIEF（libs/modules/src/agent-profile/platform-assistant.capabilities.ts）成为助手回答"你们能做什么"的唯一依据，注入 platform-assistant 的 system prompt；中文完整档案见 docs/agent-architecture/platform-capabilities.md（能力清单 + 用户问法对照 + 四条不能讲：不替 agent 做业务、不承诺价格工期认证、不称资金被平台保管、不编不存在的 agent）
  • 首次见面主动开口：用户第一次打开助手时，服务端写一条 proactive 欢迎（assistant:welcome）——进会话历史而不是弹 toast，告诉他"可以问什么 / 可以让我开任务 / 可以查进度"；只出现一次，写失败只降级
  • 主动沟通 playbook：docs/agent-architecture/proactive-playbook.md —— 四条判据（时效性 / 用户不知道 / 有明确下一步 / 不打断）+ 已实现 2 项 + 建议 11 项（按价值排序）+ 不做清单 + 统一机制（proactiveKey 幂等、冷却、静默、失败降级、一条一个动作）
  • 主动沟通终于有"时间级触发点"：ProactiveScheduler（libs/modules/src/task/proactive/proactive-scheduler.ts）每 30 分钟扫一轮，找出最近有任务的人，逐个交给 ProactiveDialogueService（按天幂等）——在此之前两个 proactive 都是"用户打开页面才触发"，用户不打开就什么都收不到。PROACTIVE_SCHEDULER=off 可关；单个用户失败只降级
  • 资讯推送给买家（带交互）：ProactiveNewsService 从 RSI 已抓好的 digest 里挑"跟他那单有关的一条"推给用户（每天最多一条、同一新闻跨天不重复、只陈述标题/摘要/来源，不做影响评估）；配套 proactive_interests 记住"有用 / 不感兴趣"，负权重到 -4 自动静音该主题，前端气泡上两个按钮即可表态（POST /api/proactive/news-feedback）
  • 主动性再加一类（任务停滞）：updateTime 超过 3 天、仍未完成/失败的任务进入每日消息，文案直接问"是不是卡住了，要我看看卡在哪吗"；消息顺序变为 待确认 → 待付款 → 失败 → 刚完成 → 推进中 → 停滞 → 最近聊过
  • 主动沟通的入口：侧栏助手条目加未读红点（本地已读游标 hushwork_assistant_read_at，打开会话即清零，不额外请求）；新增 GET /api/proactive/interests 与 DELETE /api/proactive/interests/:topic —— 用户能看见并撤销"助手记住的偏好"
  • 主动性重写（去掉"没卡住就不说"）：每日汇总不再只统计"卡住/失败"，而是把待付款、刚完成、推进中、最近聊过都算成事实；只要这一天有事情发生就主动说一句，按"能动手 → 正在发生 → 聊过"排序。此前"没有卡住的任务就一个字都不发"的口径被明确推翻（它让助手只在出事时出现）
  • 平台级资讯源：platform-assistant 支持从环境变量 PLATFORM_NEWS_SOURCES（JSON）初始化自己的 metadata.rsi.sources；未配置时完全不动 metadata.rsi（不覆盖运营在后台配的源）。买家侧资讯池因此不再依赖"某个第三方 agent 恰好配了源"
  • 沟通总结并入每日播报：新增 recentConversationsForUser（跨 relation / task 取最近 7 天沟通的聚合事实），每日汇总在有卡住任务时附带一句"最近和谁聊过几段"，结尾给出"先处理 / 先整理结论"两个选择；只有沟通记录、没有卡住任务时不单独发（避免变成每日复读机）
  • 定位修正：能力总览从「合规服务市场 + 智能编排引擎」改为双边（个人 / 企业）智能体服务平台 —— 个人一句话即可发起、由全球 agent 提供可验证的企业级服务；企业侧可把 ERP 型账务（期间 / 总账 / 主数据 / 订单域）与内容发布（CMS 类）接进同一套编排。合规只是货架上的一类垂直，不是平台定义

✨ 新增（平台助手：每个用户默认就有一条直聊） ​

  • 平台助手会话：GET /api/gateway/dialogue/assistant 幂等地取/建「当前用户 × 平台助手」的 kind=relation 会话。注册用户天生有一条，懒建（注册流程只管一次，老用户与邀请码/微信旁路进来的人也要覆盖到）
  • workspace 默认落到助手：URL 上没有 taskId / dialogId / agentId / sessionId 时，界面打开助手会话，而不是空白页或"最近一条会话"（后者会把用户扔进跟某个服务商的历史里）。从市场 Start Chat / 任务 / 深链进来时仍按原上下文，助手不会抢焦点
  • open_task 工具：平台助手在直聊里把需求开成任务。此前 build_plan / submit_request 都要求 turnTaskId，关系会话因此是死路 —— 聊得再清楚也开不出任务。现在：建 tasks（dialogId=null，status=created）+ 一条 task.created 日志，turn 结果带 taskCreated，前端刷新列表并跳到那个任务
  • open_task 与 build_plan 严格互补：有 taskId 时不挂 open_task（该请求构建计划，再开一个会把一段需求拆成两个任务）；一轮只开一个（metadata.taskCreated 幂等）
  • 新模块 libs/modules/src/task-open/（只依赖 TaskStoreModule / JournalModule，不导入 TaskModule，避免与其对 AgentGatewayModule 的依赖成环）
  • 助手与受理器拆成两个 agent：platform-assistant（用户可见的通用助手，直聊入口）与 platform-demand-intake（内部受理器，只在任务会话里出计划）。不再是"同一个门面两个名字"——一个 profile 既要"可以什么都不做只聊天"、又要"替用户开工"，提示词与工具白名单只能互相妥协；拆开之后边界是结构性的
  • 通用助手人格：新提示词不再是需求受理清单，而是"可以只了解平台（流程 / 审批 / 托管付款），也可以在需求清楚时开任务"；空 inputSchema、不声明 skillIds，避免被当成"必须先凑齐产品/市场/渠道"的受理器。受理器保留原名 需求受理顾问 与 build_plan
  • list_tasks 工具：助手能读用户自己的任务清单（只读；userId 取自会话 metadata，模型无法指定别人的任务），用来回答"我上次那个跑完了吗 / 卡在哪"
  • 默认视图不带身份参数：助手落地不再把 agentId / profileId / sessionId 写进 URL —— /workspace 本身就是入口，刷新靠幂等 ensure 回到同一条；非默认上下文（市场 agent / 历史会话 / 任务）仍写参数以支持深链
  • ensureRelationSession 改为回读绑定后的文档：agentName / agentProfileId 是 bindToAgent 才填的，返回绑定前那份会让侧栏退化成显示 agentId
  • 新增 journal kind task.created（前端有时间线图标与兜底）；文档：docs/agent-architecture/data-model.md §6 与 site/modules/task-open.md

✨ 新增（对话消息拆表 + 会话分两类） ​

  • dialogue_messages 独立集合：消息不再内嵌在会话文档里。内嵌数组会撞单文档 16MB 上限（撞上之后该用户对话永久写不进去），而且 findOne → push → save 是读-改-写 —— 用户发消息与系统主动播报并发时会互相覆盖、表现成"用户的话凭空消失"。写入改为单条 insertOne，读取按会话内 seq 分页，(sessionId, seq) 唯一索引兜底
  • 会话分两类：kind=relation（人 × agent，键 (userId, agentId, audience)，常驻且无终态）与 kind=task（任务对话，键 (taskId, agentId)，随任务生命周期）。新建对话不再看到全部历史，侧边栏只列关系会话
  • 主动播报：受理 agent 每天最多一句汇总（"你有 N 个任务在等确认"），写进关系会话，按天幂等；没有卡住的任务就一个字都不说
  • 新增 POST /api/journal/proactive-summary；GET /api/agent-gateway/dialogue/sessions/:id 支持 taskId 过滤
  • 迁移脚本：backfill:dialogue-messages / merge:dialogue-sessions / split:task-sessions，均支持 --dry-run 且幂等
  • 文档：新增 docs/agent-architecture/data-model.md（消息 / 任务 / 会话 / 关联数据），并补 AGENTS.md「数据建模铁律：禁止无界内嵌数组」

🐛 修复（agent 主动消息从未写入成功） ​

  • DialogueMessageService.allocate() 用聚合管道取号，mongoose 9 要求显式 updatePipeline: true，否则抛 Cannot pass an array to query updates —— 单测 mock 了存储层，只有真库才暴露
  • paused 状态：预算用尽不再记 completed（终态），续聊时自动重置轮次与 token，关系不会因为"额度到了"而永久结束

✨ 新增（审批卡由发展日志驱动，写入即推送） ​

  • plan.ready 记录顶层就带 runId，前端拿到日志就等于拿到审批卡需要的全部信息；useTaskRuntime 直接从中采纳 runId，不再靠 /runs/active 反复撞
  • TaskJournalService.append() 成功即广播：JournalStreamBus → TaskGateway → task-${taskId} 房间的 journalAppended 事件；前端收到就写入 runId（0 请求）并刷新一次日志
  • 跨实例扇出由已有的 RedisIoAdapter（@socket.io/redis-adapter）承担，所以 JournalStreamBus 故意只做进程内（写日志的进程 emit 一次，adapter 扇出）
  • 轮询降级为断线兜底：等计划 3s、其它 8s
  • 验证：npx jest libs/modules/src/journal（3 例：分发 / 订阅者抛错不影响他人 / 退订）；线上审批卡随"方案已生成"同帧出现

⚡ 性能（Run 探测改为事件驱动，终态停止轮询） ​

  • useTaskRuntime 移除常驻 3s 探测：只在「对话轮结束（planRequested）/ agentStatusChanged / 进入页面」触发，且有界次数（命中即停）
  • RunPanel 的 2s 轮询在 Run 进入终态（completed / failed / cancelled / expired）后停止，停止前补一次全量拉取，保证审批/支付/额度是最终值
  • services/run.ts 新增 TERMINAL_RUN_STATUSES / isTerminalRunStatus()，与后端 run.interface.ts 对齐
  • 效果：一个已完成的历史 Run 只会有 1～2 轮请求，不再每 2s 打 2～4 个请求

🐛 修复（未派单任务 /deliveries 一直 404） ​

  • assertReadable() 把两种「查不到」分开：任务本体不存在 → 404；任务存在但还没派单 → 200 + 空交付集合（集合为空是正常状态，不该用 404 表达）
  • 起因：停在需求接入阶段的死壳任务（会话过期、从未 prepare）让前端每 30s 轮询出一片 404，而 AcceptanceCard 只能 catch 静默，分不清"任务丢了"和"还没交付"
  • 验证：task-acceptance.service.spec.ts 5 例读路径（200 空视图 / 404 / 403 / 未装配 Task 模型 / 有派单按买家校验）

🐛 修复（平台本地交付无法验收，稳定 404） ​

  • accept() 的买家归属校验原本只认 offline_tasks（agent 级 → task 级回退），而平台 facade / 内部 agent 执行从不写派单记录，Task 迁 Mongo 后这些任务验收必然 404
  • 改为复用 assertReadable()：派单记录在则按派单买家判定，不在则回退 tasks.userId；别人 → 403，任务不存在 → 404
  • 现象：有 2 条 status=delivered 交付、Run 停在 delivering、任务 completed，点验收仍 404
  • 验证：spec 新增 2 例（无派单 + 本人 → 成功；无派单 + 非本人 → 403），17 passed

🐛 修复（审批卡要刷新才出现） ​

  • Run 由服务端 PlanBuildWorker 异步创建，前端既拿不到 prepare 的 runId、也没有 agentStatusChanged 事件，只能靠"进页面时的恢复探测"——表现就是刷新才出现
  • WorkspaceArea 在一轮对话流结束（任务会话与直聊两个入口）时回调 onDialogueSettled({ planRequested })，页面据此触发有界探测
  • refreshRunId({ force })：手里留着旧 runId 时也允许重探；探测时"已有 runId"不再回退 /runs/latest（避免把刚结束的旧 Run 写回来）
  • 验证：tsc 通过；线上审批卡不再依赖刷新

🐛 修复（信息不足的追问被弹成 toast） ​

  • prepare 的 needsInput 不再抛 400/422，改为正常返回 { needsInput: { question }, runId }；追问仍由后端写回对话
  • prepare/stream 的 done 事件携带 needsInput；前端 chatPrepareStream 不再因缺少 workflow_ready 而报错
  • handleChatExecute 对 needsInput 直接返回：不弹 toast、不加系统错误卡片，用户补充后再次构建即可
  • 验证：POST /api/chat/prepare 对信息不足任务返回 200 + needsInput（runId 已创建，状态 clarifying）；前后端 tsc 通过

🐛 修复（新建任务未清空旧状态） ​

  • handleNewTask 只清了部分状态；旧 Run、审批/支付记录、预检表单、agent 卡片与输入草稿会带进新窗口
  • 新建时清空 currentTaskId / currentDialogId / currentRunId / inputRequest / runAgents / pendingAutoMessage；WorkspaceArea 用 taskId 作 key 重挂载，清掉内部 messages / input / 附件
  • 验证：Playwright 从旧任务点 New conversation，新任务正文无 Delivery / Approval / WeChat Pay，显示空状态

🐛 修复（支付成功/执行完成后验收卡片不自动出现） ​

  • AcceptanceCard 只在挂载时拉取 /deliveries，支付成功、执行完成、交付写入后都不会自动出现，必须刷新页面
  • 改为监听 Run SSE 的 run.status_changed(delivering)（deliveryRefreshKey）立即拉取；不再用 3s 硬轮询，30s 仅作断线兜底
  • 验证：SSE 事件流包含 status: delivering；Playwright 11s 内 /deliveries 仅 2 次（初始 + delivering 事件），验收后显示 3/3 accepted

🐛 修复（自动构建偶发 “No demand content”） ​

  • 自动构建在对话落库的瞬间触发时，prepare 可能读不到刚写入的 agent 会话，直接 400 No demand content available for translation
  • readSessionHistoryText 在会话为空时重试一次（150ms）；前端自动触发改为把本轮用户消息作为 text 传入，历史读取失败也有输入
  • 验证：chat-execute.service.spec.ts 5/5；该任务手动/自动 prepare 返回 200，页面显示 Approval required · 1

✨ 新增（Run 工作日志：审批 / 支付记录长期保留） ​

  • 新增 GET /api/run-payment/orders?runId=，返回该 Run 的全部支付订单（pending / paid / failed）
  • 新增 GET /api/runs/latest?taskId=，任务完成后也能恢复最近 Run；刷新后 RunPanel 不再因 active 为空而整块消失
  • RunPanel 增加 Activity log：已决审批 + 微信支付订单；有日志时默认展开
  • 验证：GET /api/runs/latest 返回 completed run；Playwright 刷新后可见 Plan · approved 与 WeChat Pay · paid

🐛 修复（刷新后保留已验收状态与交付内容） ​

  • AcceptanceCard 之前在没有待验收且没有本次 outcome 时直接隐藏；刷新后 outcome 丢失，已验收状态与交付内容一起消失。现在只要 view.agents 非空就保留，显示 Delivery accepted、3/3 accepted、每个 agent 的 ✓ accepted 与 output
  • 刷新恢复 __agent__ 消息时补 agentId，AgentResultBlock 的产物列表才能按 agent 过滤
  • 验证：前端 tsc --noEmit 与 vite build 通过；Playwright 刷新后可见已验收状态与交付内容

🐛 修复（每个 agent 卡片重复显示全部交付物） ​

  • AgentResultBlock 用 taskId 拉取产物，任务级列表包含所有 agent 的 6 个文件，导致每个 agent 卡片都显示同样的 6 个
  • ChatMessage / agent_result 事件补 agentId；ArtifactList 支持按 agentId（或文件名前缀 agent-<agentId>-）过滤，每个 agent 只显示自己的 2 个文件
  • 验证：前端 tsc --noEmit 与 vite build 通过

🐛 修复（平台本地交付无法验收） ​

  • TaskAcceptanceService.accept() 按 { taskId, agentId } 找派单记录；平台本地执行（facade / 内部 agent）不会写 agent 级 OfflineTask，导致 Accept all 在第一个 facade 上 404
  • agent 级派单缺失时回退到 task 级派单校验买家，Delivery 仍可正常验收
  • 验证：task-acceptance.service.spec.ts 11/11（新增 facade 回退用例）

🐛 修复（微信支付二维码不显示） ​

  • 后端透传的 prepay 是 SDK 原始结构 { status, data: { code_url } }，前端只读 prepay.code_url，导致二维码不渲染，只剩一句「请在微信中完成支付」
  • 前端兼容读取 prepay.data.code_url，并更新 RunWechatPayment 类型
  • 验证：Playwright 点击 Pay & start 返回 201，页面渲染二维码并显示「用微信『扫一扫』完成支付」

🐛 修复（复用待托管时校验金额与币种） ​

  • RunPaymentService.createWechatPayment() 复用 (taskId, agentId) 的 pending 托管前，校验金额/币种与当前计划一致
  • 不一致时返回明确错误，避免取消旧计划后按旧金额支付或结算
  • 验证：run-payment.service.spec.ts 6/6（新增 task 级与 per-agent 两个用例）

🐛 修复（刷新后丢失工具调用记录） ​

  • 工具调用与结果本来就落在 agent_dialogues.messages（toolCalls / toolCallId），但前端历史加载只映射 role/content，刷新后工具标签消失
  • 历史加载（任务对话与 agent 直聊）现在保留 toolCalls，并放宽过滤：只有工具调用、没有正文的 agent 消息不再被丢掉
  • 历史工具标签显示工具名与 ✓；没有耗时数据时不显示 NaNms
  • 验证：Playwright 打开历史会话可见 recall_knowledge、build_plan 标签；前端 tsc -b 与构建通过

🐛 修复（构建计划后无法审批） ​

  • ChatExecuteService.prepare() 的历史窗口从「最后 3 条 user 消息」改为「按 6000 字符预算保留最早一条 + 最近补充」：受理门面多轮追问后，最后几条往往只是「直接构建计划」，早期需求被截掉会让拆解器返回 needsInput，计划永远不生成
  • 修复 wechatpay-node-v3 在 webpack 构建下的 CJS 互操作：import default 不是构造函数，approve 后支付创建直接崩溃；改为 require + 运行时解包
  • 微信支付 notify_url 去掉 ?type= query：微信对通知地址做正则校验，带 query 会返回 PARAM_ERROR，下单失败
  • 微信下单失败不再显示 unknown，改为读取 data.message / error 并记录日志
  • 任务标题在无 skillName 时只取第一条实质需求，避免多轮历史被拼成一长串标题
  • 验证：POST /api/chat/prepare 返回 200（3 tasks / run / pending approval）；Playwright 实测审批卡片可见、Approve & pay 返回 201、微信下单返回 201 + code_url

♻️ 重构（LLM 出口与 engine-chat 解耦） ​

  • 新增 libs/modules/src/llm：LlmClientService 提供 complete / stream / directPrompt，模型名收敛一并迁入；EngineChatService 不再承载 LLM 出口
  • AgentLlmAdapter、InternalAgentNodeExecutor、AgentsService 直调兜底、TaskExecutionService 内部节点、AgentShowcaseService、DemandTranslationService 全部改走 LlmClientService
  • agent-runtime、workflow、agent-profile、demand-translation 不再导入 EngineModule；task / agents 仅保留旧 prompt(appmodelId) 分支所需的依赖
  • ChatExecuteService.prepare() 移除 MySQL nano 回退：历史只从 agent_dialogues 读，旧 dialog 链路删除时构建路径不用再改
  • 旧 engine/chat-models.ts 与对应测试迁到 llm/；EngineChatService 删除 chatCompletion* / directPrompt
  • 验证：npx jest libs/modules/src/llm --runInBand 11/11；agent-gateway + chat-execute 101/101；前后端 tsc 通过

✨ 新增（受理门面自动构建计划） ​

  • 受理门面在信息齐时调用 build_plan 工具，由模型显式请求构建；不再要求用户去工作区找 Build plan 按钮
  • 对话 turn 结果新增 planRequested；前端在流正常结束后自动复用 chatPrepareStream 进入 prepare，卡片、预检与审批和手动触发完全一致
  • build_plan 只装配给 platform-demand-intake（且必须有 taskId、非 owner 面）；其他 agent 即使拿到工具也会被拒绝
  • 幂等：同一轮重复调用返回 already_requested，不叠加标记；中止/失败的轮次不触发构建
  • 验证：npx jest libs/modules/src/agent-runtime/build-plan.tool.spec.ts --runInBand 6/6；相关回归 3 suites / 27 tests；前后端 tsc 通过

🐛 修复（登录会话恢复） ​

  • 登录页在有未过期 refresh token 时先展示 “Continue” 一键登录，不再每次都要求邮件/短信验证码；只有服务端明确拒绝 refresh token 后才展开验证码表单
  • refresh token 只有在明确失效（401/403）时才从本地清除；网络错误 / 5xx 等临时失败保留，避免一次抖动就永久丢失会话
  • 网络层与 AuthContext 共用同一个单飞刷新，避免两条路径同时轮换 refresh token 导致互相失效
  • SSE 请求收到 401 时保留 refresh token，回到登录页仍可一键恢复
  • 验证：cd frontend && npm run build 通过；改动文件的 npx tsc -b + eslint 通过

🏗️ 新增（域模型与四类事实形态） ​

  • 新增 四类事实形态与域模型：事件 / 余额资源 / 主数据 / 计算四类存储，统一访问契约与域声明
  • 新增模块页：Order、Accounting、Ledger、Master Data、Computation、External Skill
  • 域治理：未声明的顶层域写入被拒；factClass 声明后不可更改
  • 双时间轴：业务发生时间与记录时间分离；inferred 事实不能进被重开过的期间
  • 期间门禁：已关闭期间子路径写入 409；根路径放行以支持重开（否则会自己锁死）
  • 四科目复式记账 + 七条不变量；托管结算自动派生分录
  • 主数据合并：别名表 + 读侧解析，历史不改、回滚后可再合并
  • 余额资源：原子扣减（并发不超卖）、幂等变动、防负余额
  • 计算型：同输入复用、算法版本变更自动失效、失败不占幂等键
  • 能力集成：外部系统作为 skill 调用，结果作为事实落进任务因果链
  • 验证：单元 35 套件 / 461 用例；真库 e2e 21 用例；npm run docs:build 通过

📚 文档（Agent RSI、主动模式与知识库） ​

  • 新增 Agent RSI：智能体自进化：双面隔离、四环、每日复盘与证据门禁、自治等级与红线（原 /architecture/rsi 已迁移）
  • 新增 智能体主动模式：主人模型、冷却 / 容忍度 / 预算、通知与邮件、多 owner 隔离；并如实标注“每日自动派发未接线”
  • 新增 知识库：条目结构、审批与生命周期、自动到期、两阶段检索与创新点
  • 架构侧边栏与模块总览新增「智能体进化与主动」分组；门面 Agent 的“如何开始”补充入口
  • 验证：npm run docs:build 通过

✨ 新增（RSI：per-owner 隔离与主人邮件推送） ​

  • 主人域（信号 / 偏好模型 / 主动计划 / 通知）改为 per-owner 存储在 /agents/{agentId}/owners/{ownerId}/...；两个 owner 的预算、冷却、已读互不影响
  • recordSignal / getModel / decideForToday / persistModel 全部要求 ownerId；知识审批与变更决策的信号记在拍板人名下
  • 每日复盘调度对 ownerId + ownerIds 去重后逐个刷新主人模型；ownerId 进入路径前做字符白名单校验（防路径穿越）
  • 新增 OWNER_CONTACT_PORT 邮件端口：apps 层用 user 表邮箱 + EmailService 实现；未注册端口或用户无合法邮箱时静默降级为只发站内通知
  • 旧路径通知保留读端兼容（仅主 owner 可见，已读写回原 key）
  • 修复 jest moduleNameMapper 的 @app/* 子路径映射与 modulePaths，使 apps 层测试可解析 libs 导入
  • 验证：npx jest libs/modules/src/agent-runtime/rsi 23 suites / 270 tests 通过；npx jest apps/hushwork/src/user/owner-contact.service.spec.ts 4 tests 通过；npx tsc --noEmit 通过；npm run build 通过

🐛 修复（交付物 Markdown 报告与去重） ​

  • 旧执行的 final/ 只有 JSON，是因为执行早于 .report.md 生成逻辑；已为当前任务补 agent-facade-gdpr-review-gdpr.report.md，并在 task.artifacts 中替换 intermediate 重复项
  • collectArtifacts 现在按文件名去重，优先保留 final/，避免 intermediate/final 同名 JSON 同时出现在 Delivered
  • 结构化 facade 输出在新执行中会生成 final JSON + final report.md 两份交付物
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/task/services/agent-result-format.spec.ts libs/modules/src/task --runInBand 通过

✨ 新增（Workspace 交付物与智能会话标题） ​

  • WorkspacePanel 在 agent result / Run artifact 变化后重新拉取 artifacts，并做短延迟重试，展示 intermediate + final 全部交付物
  • listArtifacts 在 artifacts 集合为空时回退到 GET /api/task/:id/artifacts，兼容早期只写 task.artifacts 的执行记录
  • 受保护的 Task 文件改为带 Authorization 的 Blob 下载；直接打开 /download 直链仍会 401（预期鉴权）
  • ChatExecuteService.prepare 根据技能名/需求生成 Task 标题，不再固定为“新需求”；PrepareResult.taskTitle 返回后左侧历史即时更新
  • 验证：npm run frontend:build 通过；npx jest libs/modules/src/task/services/chat-execute.service.spec.ts libs/modules/src/task --runInBand 69 tests 通过

✨ 新增（结构化评估结果与报告） ​

  • TaskExecutionService 结果摘要改为优先读取 agent summary，不再截断整段 JSON；Task resultSummary 同步写入
  • 每个结构化节点结果额外生成 .report.md Markdown 评估报告，与 JSON 一起作为 artifact 下载
  • AgentResultBlock 结构化展示 status / risk_level / GDPR applicable / DPIA / DPO / required_actions / cross_border_transfer_issues / follow_up / disclaimer，原始 JSON 收进高级详情
  • GDPR skill 扩展数据主体、角色、跨境、现有文件等输入，以及 role/lawful basis/数据主体权利/保留期限/vendor DPA/assumptions/disclaimer 输出
  • 验证：npx jest libs/modules/src/task/services/agent-result-format.spec.ts libs/modules/src/task --runInBand 69 tests 通过；npm run frontend:build 通过

✨ 新增（external input 持久化） ​

  • 新增 RunInteractionService：暂停时写 run_interactions pending + L0 interaction 事件；用户提交后同一条更新为 resolved，保存回答文本与操作者
  • 新增 GET /api/runs/:id/interactions 审计查询
  • 兼容旧 Run：没有 interactionId 时补一条已 resolved 记录
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/run/services/run-interaction.service.spec.ts --runInBand 5 tests 通过

🐛 修复（facade needs_input 不再算完成） ​

  • 门面输出 status=needs_input 时抛出 AgentInputRequiredError：step 标记 waiting，Run 进入 waiting_external，不写 completed、不结算
  • RunPanel 展示 summary + fields，用户补充后通过 POST /api/task/:id/external-input 恢复同一节点
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/agent-profile/services/facade-output.spec.ts libs/modules/src/task --runInBand 84 tests 通过

🐛 修复（0 元计划在 wechat 模式错误下单） ​

  • RunPanel 仅在 plan approval amount > 0 时调用 /api/run-payment/wechat；0 元计划始终走 free commit
  • 修复 GDPR 免费 facade 计划批准后卡在 awaiting_plan_approval：审批已 approved，但前端尝试微信下单被后端以“0 元计划请使用 free commit”拒绝
  • 验证：npm run frontend:build 通过

🐛 修复（策略 API 支持 run 执行配置） ​

  • PUT /api/sys/policy-settings 的 DTO/Controller 补上 run 字段，可直接配置 toolApprovalThreshold / requiredApprovers
  • 线上策略已将 run.toolApprovalThreshold 设为 50（policy_settings v3，带变更审计）
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/policy-settings --runInBand 27 tests 通过

🐛 修复（微信支付配置映射） ​

  • weixinPayment 增加 xcxAppId / gzhAppId 映射：WEIXIN_APPID 用于 JSAPI，WEIXIN_GZHAPPID 用于 Native
  • WEIXIN_NOTIFY_HOST 已带 /api 时不再重复拼接（/api/api/...）
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/run --runInBand 7 suites / 64 tests 通过

✨ 新增（微信支付 prepay/notify） ​

  • 新增 RunPaymentService / RunWechatPayService：JSAPI/Native 预支付、回调解密、run_payment_orders 映射
  • RUN_PAYMENT_PROVIDER=wechat 时直连 commit 被拒绝；回调通过 commit(skipPaymentGate) 完成 escrow fund + Run executing
  • 证书通过 WEIXIN_CERT_PATH / WEIXIN_KEY_PATH；默认 manual 不影响现有链路
  • 前端：RunPanel 在 wechat 模式发起 Native 下单、展示 code_url，支付回调后自动继续执行
  • 验证：npx jest libs/modules/src/run --runInBand 7 suites / 64 tests 通过；npm run frontend:build 通过

✨ 新增（受控 autonomous） ​

  • 新增 RunAutonomousService：订阅 Run 状态事件，仅在 mode=autonomous 且已 commit 进入 executing 时自动启动执行
  • RUN_AUTONOMOUS_AUTOSTART 默认 off；不自动审批、不自动验收、不自动付款；建议只在一个实例开启
  • 公开 POST /api/runs 拒绝 mode=autonomous（仅内部 Run）
  • 验证：npx jest libs/modules/src/task --runInBand 9 suites / 65 tests 通过；npx tsc --noEmit -p tsconfig.json 通过

✨ 新增（A2A 供应商上报 tool events） ​

  • A2AClientService 从 task metadata / status.message.metadata / artifacts[].parts 提取供应商上报的 toolCalls
  • TaskExecutionService 将其写入 Run 的 tools/{callId} 事件；未上报时行为不变
  • 验证：npx jest libs/modules/src/a2a libs/modules/src/task --runInBand 11 suites / 90 tests 通过；npx tsc --noEmit -p tsconfig.json 通过

✨ 新增（对话页 Run 指标条） ​

  • RunPanel 顶部显示当前 task 的 Run 指标：runs / success / p95 / pending approvals（5s 轮询）
  • 复用 GET /api/runs/metrics
  • 验证：npm run frontend:build 通过；npx prettier --check frontend/src/services/run.ts 通过

✨ 新增（P4-G Run 全链路 e2e） ​

  • 新增 apps/hushwork/test/run-flow.e2e-spec.ts：真实 Mongo/MySQL/Nest 容器覆盖计划审批 → commit（open + fund）→ 执行 → delivering → 验收 → settling/completed → 托管 released
  • 新增 apps/hushwork/test/run-tool-approval.e2e-spec.ts：工具超阈值暂停 → approve → resume → completed
  • 修复：requestPlanApproval 现在把 plan 写回 Run，commit 不再报“没有计划”
  • 修复：Run 快照与 step 取消由 platform actor 写 L0，用户/第三方只作为触发者，避免写权限拒绝
  • 验证：npm run test:e2e:hushwork -- --testPathPatterns=run-flow 1 suite / 1 test 通过；npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/run libs/modules/src/policy-settings --runInBand 7 suites / 86 tests 通过

✨ 新增（企业多级审批） ​

  • policySettings.run.requiredApprovers（默认 1）：计划级/工具级审批需要的批准人数
  • RunApproval 新增 requiredApprovers 与 approvedBy；多人审批未达人数时保持 pending
  • RunPanel 审批卡显示 1/2 approved 进度
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/run libs/modules/src/policy-settings --runInBand 7 suites / 86 tests 通过；npm run frontend:build 通过

✨ 新增（对话页 Run 状态与补充输入） ​

  • RunPanel 顶部显示 Run 状态与等待原因（2s 轮询 GET /api/runs/:id）
  • 第三方 INPUT_REQUIRED 时显示 Additional input required 卡，可直接提交补充内容并恢复执行
  • RunSnapshot 类型补充 metadata；后端 GET /api/runs/:id 返回 metadata
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npm run frontend:build 通过

✨ 新增（P4-D 审批撤销） ​

  • 新增 POST /api/runs/:id/approvals/:approvalId/revoke：撤销 pending 审批，写 L0，并取消 Run / 退款
  • RunPanel 审批卡增加 Revoke 操作；审批列表自动刷新
  • 验证：npx tsc --noEmit -p tsconfig.json 通过；npx jest libs/modules/src/run --runInBand 6 suites / 58 tests 通过；npm run frontend:build 通过

✨ 新增（P4-C Run 指标） ​

  • 新增 GET /api/runs/metrics：按用户/任务/时间范围统计 Run 总数、状态分布、成功率、平均/p50/p95/最大耗时、pending approval 与等待项
  • 单次最多统计 5000 条；超出返回 truncated=true
  • 验证：npx jest libs/modules/src/run --runInBand 6 suites / 58 tests 通过；npx tsc --noEmit -p tsconfig.json 通过

✨ 新增（P4-B 第三方 INPUT_REQUIRED 多轮） ​

  • A2A 暂停：A2AClientService 新增 stopOnInputRequired；第三方进入 INPUT_REQUIRED 时抛 A2AInputRequiredError，不再轮询到超时
  • 执行暂停：TaskExecutionService 不再把输入请求当节点失败；step 写 waiting，Run 进入 waiting_external，保存 externalInput 上下文
  • 用户补充：新增 POST /api/task/:id/external-input；补充内容合并进同一节点（external_input / user_input / external_task_id），Run 回到 executing 并恢复执行
  • 边界：当前重新派发同一 step（新 A2A task），不是同一 A2A task 续聊；RunExpiryService 仍会对超时等待做过期与退款
  • 验证：a2a + task 共 10 suites / 88 tests 通过；npx tsc --noEmit -p tsconfig.json 通过

✨ 新增（P4 执行控制面与交付回写） ​

  • 执行控制面：TaskExecutionService 每批 dispatch 前重新读取 Run；paused / 审批等待 / 外部等待停止派发，cancelled 标记 execution 取消，failed / expired 走失败收尾
  • 交付状态闭环：finalizeExecution → delivering；验收通过/有条件通过 → settling，结算成功 → completed；驳回 → executing
  • 过期扫描：新增 RunExpiryService，每 60 秒处理审批过期与 waiting_external / external_input_required 超时；RUN_EXPIRY_SWEEP=off 可关闭
  • 工具审批恢复：resumeExecution 仅允许 Run 为 executing 时恢复；paused / 审批等待先走 Run 恢复/审批
  • 验证：run + fulfillment + task 共 16 suites / 172 tests 通过；npx tsc --noEmit -p tsconfig.json 通过
  • 文档：docs/agent-architecture/run-runtime/ 与 phase6 的 P4 状态已更新

📚 文档（Run Runtime 架构模块） ​

  • 新增 docs/agent-architecture/run-runtime/：README.md + 5 篇 as-built 文档（生命周期 / 需求拆解 / 审批托管 / 事件流与 UI / 运维排障）
  • 新增对外页 site/architecture/run-runtime.md：面向产品与集成方的 Run 总览
  • 更新架构索引：ARCHITECTURE.md 增加 run 模块与 Run-centric 编排章节；agent-dev-framework/README.md 增加入口
  • 规格状态：run-centric-agent-spec.md 从“草案”标记为“已实现（P0–P3e）”，实现细节以 run-runtime/ 为准
  • 新增加 Phase 6 工作记录：docs/workplan/phase6-run-centric-agent.md
  • Run 模块 README：补充架构文档链接

⚡ 性能（Run SSE 改为事件总线驱动） ​

  • 新增 StateEventBus：状态事件提交后广播；有 Redis 时走 pub/sub（PM2 多实例可收到），无 Redis 时退化为进程内广播
  • StateTriggerDispatcher 在派发前广播：sync 与 outbox worker 两条路径都覆盖
  • Run SSE 不再 1s 轮询：RunController.events 由事件总线唤醒后按 afterSeq 读取增量，立即推送；仅保留 5s 兜底轮询（Redis 不可用 / 丢消息）
  • 断线重连不变：afterSeq + 历史补发仍是唯一恢复语义
  • 验证：state + run 19 suites / 244 tests 通过；npx tsc --noEmit -p tsconfig.json 通过

🐛 修复（0 元计划是合法场景） ​

  • CommitPlanService 不再拒绝 0 元计划：金额为 0 时不建托管，写一条 status: 'free' 的 commit 事实，并把 Run 推进到 executing；负数 / 非数字仍然拒绝
  • 审批卡文案：0 元计划显示 Free 与 Approve & start；有金额仍显示 Approve & pay
  • 验证：commit-plan.service.spec.ts 覆盖 0 元 free commit 与负数拒绝

✨ 新增（Run SSE 全量执行展示 P3d） ​

  • 对话页优先使用 Run SSE：新增 useRunStream，RunPanel 优先使用 Run 流的 step.updated / tool.finished / artifact.ready，GET /api/task/:id/trace 仅作回退
  • 断线重连：以最后一条事件的 seq 作为 afterSeq 自动重连；事件在内存中保留最近 500 条
  • 产物进入 Run 流：ArtifactService 登记产物后写 /tasks/{taskId}/runs/{runId}/artifacts/{artifactId}（artifact.ready），对话页可直接看到产物卡
  • 门面 agent 工具事件：TaskExecutionService 调用 AgentRuntime 时把 onToolCall 写入 /tools/{callId}（tool.finished）；外部 A2A 供应商内部工具不由平台可见，平台只记录 step.updated
  • CodeWhale 恢复原位：frontend/CodeWhale 已移回；根 tsconfig 通过 exclude: ["frontend"] 避免再次被后端类型检查扫描
  • 验证：artifact + run + task 15 suites / 127 tests；npm run frontend:build；npx tsc --noEmit -p tsconfig.json；Prettier

✨ 新增（工具级审批拦截 P3c） ​

  • 派发前拦截：TaskExecutionService 在每个 step 派发前调用 RunApprovalService.requestToolApproval()；超过 policySettings.run.toolApprovalThreshold 时不派发，写 step waiting，Run 进入 awaiting_tool_approval
  • 执行暂停而不是失败：以 ToolApprovalRequiredError 停止执行循环，startExecution / resumeExecution 的 catch 识别后保持 execution 为运行中，不标 failed
  • 审批幂等：同一 runId + stepId + tool 的已批准审批直接放行；pending 复用，避免恢复后无限追问
  • 恢复执行：前端工具级审批通过后调用 POST /api/task/:id/resume，执行器从 L0 已完成 step 继续，已批准的 step 不再拦截
  • 计划审批前置：ChatExecuteService.execute 要求 Run 已 executing（approve + commit 完成）；前端 prepare 后不再自动执行，Approve & pay 完成后才启动
  • 验证：run + task 13 suites / 112 tests 通过；npm run frontend:build 通过；npx tsc --noEmit -p tsconfig.json 通过

✨ 新增（对话页审批卡 P3b） ​

  • RunPanel 接入 Run 审批：新增 runId prop，轮询 /api/runs/:id/approvals，在聊天流内渲染计划级 / 工具级审批卡
  • Approve & pay：计划级审批先 approve，再调用 commit（唯一花钱入口，开托管 + fund）；工具级审批只 approve
  • Reject：调用 reject，后端取消 Run 并退回已 held 的托管
  • 跨任务隔离：审批卡按 taskId 过滤；prepare / workflow_ready 返回的 runId 存入页面状态，新一次执行前清空
  • 验证：npm run frontend:build 通过
  • 仍未做：工具级审批的派发前拦截（执行器在 dispatch 前调用 requestToolApproval）；RunPanel 的 step 展示仍走 trace 轮询，审批卡是增量（P3d 已切 Run SSE）

🐛 修复（后端类型检查恢复） ​

  • 根 tsconfig.json 收敛检查范围：只检查 apps/**/*.ts + libs/**/*.ts，排除 frontend（前端有自己的 frontend/tsconfig.app.json）、*.spec.ts / *.e2e-spec.ts，以及 10 个未在 app-client.module.ts 注册、依赖缺失 @app/chain 或旧 Nest Cache API 的历史模块
  • tsconfig.build.json 同步排除项：避免 nest build 因 exclude 覆盖而重新扫到前端
  • apps/screenshot 修复：setupSwagger 调用去掉不存在的 path 参数（实现已硬编码 swagger-ui，行为不变）
  • AgentListPage 改为导出：修复 declaration: true 下的 TS4053
  • 结果：npx tsc --noEmit -p tsconfig.json 与 -p tsconfig.build.json 均通过；run + task + agent-profile 28 suites / 224 tests 通过

✨ 新增（执行期事件进入 Run 流 P3a） ​

  • 执行事实自动归 Run：TaskAgentLoopService.recordStep / recordDecision / recordBatchStarted 会自动把 runId 写入 L0（按 taskId 查活跃 Run，5s 短缓存；读不到不阻断执行）
  • Run SSE 覆盖执行期：GET /api/runs/:id/events 现在同时返回 run.*、step.updated、batch.updated、tool.finished、approval.*；step/batch 只纳入 value.runId === runId 的事实，不会串到其它 Run
  • runId 暴露给前端：ChatExecuteService.prepare 返回 runId，workflow_ready SSE 事件也带 runId；前端 chat.ts 类型同步，可直接订阅 /api/runs/:id/events
  • 断线重连：Run 事件流继续支持 afterSeq；step/batch 与 run 事件共用同一套 seq
  • 验证：run + task（loop/agent-loop）7 suites / 67 tests 通过；前端 npm run frontend:build 通过
  • 说明：审批卡 / 产物卡的对话页渲染仍走现有 trace 轮询，Run SSE 的 UI 切换在 P3b

✨ 新增（审批 + 托管 P2） ​

  • 计划级审批：ChatExecuteService.prepare 生成计划快照（tasks / agentIds / 总价 / planHash）后创建 RunApproval，Run 进入 awaiting_plan_approval；重复 prepare 对同一 planHash 幂等复用
  • 工具级审批：新增 policySettings.run.toolApprovalThreshold（整数最小单位，默认 null = 不启用）；超过阈值的单笔费用会创建 tool 审批并把 Run 暂停在 awaiting_tool_approval
  • 审批 API：GET /api/runs/:id/approvals、POST /api/runs/:id/approvals/:approvalId（approve/reject）、POST /api/runs/:id/approvals/:approvalId/expire
  • 唯一花钱入口：POST /api/runs/:id/commit。校验 approved 审批 + runId + planHash + 金额 + 过期时间后，EscrowService.open + fund，写 /tasks/{taskId}/runs/{runId}/commits/{planHash}，再推进 Run 到 executing
  • 幂等：同一 runId + planHash 重复 commit 返回同一 escrow，不重复扣款；已有 pending escrow 只 fund，已有 held escrow 不再 fund
  • 拒绝 / 过期 / 撤销：取消 Run，并通过新增的 EscrowService.refund()（held → refunded，全额退回买家）避免托管残留 held
  • execute 不再隐式批准：Run 存在审批记录时，ChatExecuteService.execute 不会把 Run 直接推进到 executing；必须 approve + commit
  • 验证：run + escrow + policy-settings + demand-translation + agent-runtime + authority 共 26 suites / 305 tests 通过
  • 规格：docs/agent-architecture/run-centric-agent-spec.md §7 / §11 P2

✨ 新增（需求 loop 收编到 AgentRuntime P1） ​

  • DemandAgentLoopService 改为 AgentRuntime.run()：预算、deadline、取消、工具白名单与并发闸由统一 runtime 提供；删除服务内自建的 while 循环
  • 四个按次注入工具：search_skills / match_agents / propose_plan / ask_user。仍然是只读、零计费；extraTools 只对本次唤醒可见
  • tool 调用落 L0：每次调用写 /tasks/{taskId}/runs/{runId}/tools/{callId}（args / result 截断 4000 字符），可在轨迹流与审计中查
  • ask_user 闭环：工具写一条 user_input Interaction，并让模型返回 needs_input；translate() 短路为 needsInput；ChatExecuteService.prepare 把 Run 置为 clarifying 并以问题文本提示用户；DemandIntakeService 同样返回 needsInput，不再误判为目录外拒答
  • 预算耗尽有结构化终态：runtime 返回 max_steps / max_tokens / deadline 时，上层回退单轮 LLM 或关键词规则，不把半截结果交给买家
  • 翻译缓存按 Run 隔离：缓存键加入 runId，避免不同 Run 复用 needsInput / Interaction
  • 验证：agent-runtime + demand-translation + run + state-write.authority 共 17 suites / 172 tests 通过
  • 规格：docs/agent-architecture/run-centric-agent-spec.md §11 P1

✨ 新增（Run 状态机 + 统一事件流 P0） ​

  • 新增 libs/modules/src/run/：把「对话 → 拆解 → 执行 → 交付」收敛到一个 Run。状态机覆盖 intake / clarifying / planning / awaiting_plan_approval / executing / waiting_external / external_input_required / awaiting_tool_approval / paused / delivering / settling 与四个终态；终态不可复活，重跑 = 新建 Run
  • Run 与 L0 绑定：Run 快照、Interaction、Approval 写入 /tasks/{taskId}/runs/{runId}/...，复用现有写权限、订阅与 traceCausation()；step 事件不复制，继续使用 /tasks/{taskId}/steps/{stepId}
  • 新增 /api/runs：POST /（创建/复用活跃 Run）、GET /:id、GET /:id/events（SSE，支持 afterSeq 断线重连）、POST /:id/messages、POST /:id/cancel、POST /:id/pause、POST /:id/resume、POST /:id/external-events
  • 取消可传播：cancel 会把该 Run 下所有 pending/queued/waiting/running 的 step 显式写成 cancelled；单个 step 写失败只计入 failedSteps，不阻止其余传播
  • 恢复幂等：resume 以 triggers/{eventId} 为幂等键；未决的审批/交互会阻止推进；paused 恢复到 pausedFrom
  • L0 写权限扩展：新增 approval（user/platform）与 interaction（user/agent/platform/system）两类代记事实；Run 根路径与 triggers 仍由 platform 写
  • 对话链路旁挂：ChatExecuteService.prepare 创建/复用 Run 并推进到 planning → awaiting_plan_approval，execute 推进到 executing；Run 故障只告警，不影响原有 prepare/execute
  • P0 边界：不含执行器、审批扣款与工具编排；commit_plan → EscrowService 在 P2，TaskAgentLoop 事件投影在 P3
  • 验证：run + state-write.authority 3 suites / 61 tests 通过；Prettier 通过；tsc 对新增/修改文件无错误
  • 规格：docs/agent-architecture/run-centric-agent-spec.md

⚡ 性能（agent loop：减少模型往返） ​

  • search_skills 直接带回 top agent：前 8 条候选并行匹配，结果含 top_agents（agentId / name / score），模型不必再逐个 match_agents
  • propose_plan 支持 query 模式：一次调用完成「检索 → 匹配 → 依赖 → 报价」，模型可跳过 search_skills
  • 同轮工具并行：一条 assistant 消息里的多个 tool_calls 改为 Promise.all，结果按原顺序回写
  • SYSTEM_PROMPT 调整：优先一次 propose_plan({ query })；match_agents 只用于补充候选
  • 问候变体短路：你好啊 / 您好呀 / 早上好 等不再进入 agent loop
  • 实测（同一测试 dialog，规则未命中的英文请求）：rounds=5 / tools=7 / 13.57s → rounds=4 / tools=4 / 7.63s
  • 仍未解决：模型仍可能先 search_skills，rounds 未降到 2；deepseek-chat → deepseek-flash 待质量对比
  • 验证：demand-translation 6 suites / 54 tests；nest build；生产部署与冒烟
  • 方案与实施记录：docs/agent-architecture/task-orchestration-optimization.md（§8.7）

✨ 新增 / ⚡ 性能（并行 DAG + 流式编排） ​

  • DAG 按真实依赖生成：不再用 prevNodeId → nodeId 线性串联。翻译阶段的 TranslatedTask.dependencies（skillId，基于 skill input/output schema 推导）现在会映射成节点依赖：无依赖的节点是并行起点，有依赖的节点等待前置
  • 修正执行器的边字段：buildPlan 现在同时识别 sourceNodeId/targetNodeId（prepare 生成的格式）与旧的 source/target；此前字段不匹配，依赖边被忽略，所有节点都被当成无依赖并发
  • 新增 POST /api/chat/prepare/stream：start → translated → matched → workflow_ready → done，复用对话 SSE 的写入端（心跳 / 背压 / 断连取消）
  • 新增 POST /api/dialog/prepareSse/stream：start → analyzing → translated → done，翻译等待过程可见；nonce 仍在翻译完成后返回，保证能力边界注入首轮 prompt
  • 前端流式接入：prepareSseStream / chatPrepareStream；翻译阶段显示 Analyzing demand…，匹配到 agent 就先渲染卡片，建图完成后再执行
  • 验证：libs/modules/src/task 8 suites / 62 tests；前端 tsc + 构建、后端 nest build 通过；生产冒烟两条流事件序列正确，6 个无依赖任务 connections: []
  • 方案与实施记录：docs/agent-architecture/task-orchestration-optimization.md（§8.5 / §8.6）

🐛 修复 / ⚡ 性能（Task 编排：正确性、拒答与延迟） ​

  • 不再出现“假成功”：拆解后没有任何可用服务商时，/api/chat/prepare 直接返回 400；不再创建空 workflow，也不会把任务标成 completed 却没有交付
  • 部分缺口可见：prepare 返回 unmatchedTopics，聊天流提示「以下能力暂时没有可用服务商，未加入执行」
  • 拒答有依据：prepareSse 返回 unmatched，并通过 Redis nonce 把能力边界注入对话 system prompt；模型必须明确告知暂无法承接，不得承诺交付/价格/工期
  • 同一需求只翻译一次：翻译结果 60s 进程内缓存（深拷贝、容量 200），prepareSse 与 chatPrepare 复用同一结果
  • 纯问候不空转：整句问候（你好 / hi / 谢谢 / test 等）不再进入 agent loop，避免 4–8s 等待
  • agent loop 超预算收敛：不再丢弃整轮检索结果；改为补 tool 响应后不再提供 tools，要求模型基于已有信息输出最终 JSON
  • 匹配并行：子域匹配由串行 for + await 改为 Promise.all（保持结果顺序）
  • 验证：demand-translation + task 共 14 suites / 108 tests 通过；前端 tsc + 构建、后端 nest build 通过；生产冒烟同一请求第二次 12.0s → 0.04s
  • 方案与实施记录：docs/agent-architecture/task-orchestration-optimization.md

🐛 修复（对话会话过期语义：续期而不是丢掉历史） ​

  • 区分「空闲过期」与「已结束」：expired 只是 idle TTL 到期（reclaimExpiredSessions 标记，文档与历史都不删）。现在对它发消息会续期并继续同一会话（status→active、expiresAt→now+空闲 TTL）；completed（主动结束 / 轮次或 token 用尽）仍是终态，需要新会话
  • 空闲 TTL 保持 30 分钟：TTL 只决定「是否计入活跃会话」的统计与配额，不再决定能否继续；每次发消息都会滑动续期
  • 前端不再因过期切走会话，也不再弹「已过期」提示：深链、缓存复用、侧栏点击只在 completed 或会话已删除时静默新建；过期会话照常显示历史并可直接接着聊
  • 失败原因可见：对话 SSE error 事件的消息直接显示在消息气泡里，不再统一显示 Generation failed. Please retry.
  • 验证：agent-gateway 7 suites / 73 tests 通过；前端构建通过；真实过期会话发消息返回 done，历史保留、状态自动续期

📚 文档（状态层应用案例拆解） ​

  • 新增页面 site/architecture/state-use-cases.md：把状态层的用途拆成“记录事实 / 驱动流转 / 取证恢复”三类，覆盖任务留痕与断点恢复、交付→验收、验收→结算、争议→处置、托管、错误告警、门面唤醒、周期服务、历史版本、乐观并发共 10 个案例
  • 补充模式总结：事实 → 规则 → 动作的三段式；明确“不是所有状态写入都需要订阅”，只留痕/查询/恢复的场景不需要加规则
  • 新增扩展步骤：定事实、定读取方、定规则、定动作、验证；并列出状态层不负责的定时器、自动重试、资金划转、搜索与字段级权限
  • 接入导航：状态层分组新增“应用案例拆解”；状态层页与状态驱动页的“下一步”加入交叉链接

📚 文档（状态驱动 Agent 小白版） ​

  • 新增文章 site/architecture/state-driven-agents-explained.md：从餐厅点单的类比起步，解释事件、物化状态、订阅、因果链、幂等、outbox、AgentRuntime 等概念；给出一次 HS Code 咨询的九步真实旅程与事件链
  • 术语表按学习顺序分组：数据（事件 / 事件溯源 / 物化视图 / CQRS / 版本 / seq / 乐观并发 / 重放）、触发（订阅 / pattern / condition / action / ECA / 派发器 / 执行器 / 防环）、可靠性（幂等 / at-least-once / outbox / 退避重试 / 因果 / actor / 审计）、AI（门面 / AgentRuntime / 契约 / JSON Schema / envelope / tool calling / SSE / A2A）
  • 补充反例与四个常见误解：写状态 ≠ 触发、done ≠ 结果、上架 ≠ 已订阅、对话原文不进状态层
  • 接入导航：指南侧边栏新增入口；state-driven-logic 架构页与内部 Playbook 顶部/关系表加入交叉链接

📚 文档（状态如何驱动 Agent：事件、订阅、因果与运行时） ​

  • 新增对外页 site/architecture/state-driven-logic.md：解释状态为什么不是普通数据库、五个构件（Path / Event / Entry / Subscription / Executor）、八种逻辑关系（寻址 / 时序 / 因果 / 触发 / 数据依赖 / 责任 / 边界 / 幂等）、一条完整链、AgentRuntime 在链中的位置、契约如何编译成订阅、排障顺序与能力边界
  • 新增内部 Playbook docs/agent-architecture/state-driven-logic-playbook.md：补齐六种典型逻辑链（门面单点、交付→验收→结算、多跳工作流、周期唤醒、外部回调、失败幂等）、真实 4 跳闭环、取证方法与新增订阅的 10 项检查清单
  • 明确分工：状态层负责「何时叫醒、拿什么输入、结果放哪、谁负责」；AgentRuntime 只负责「一次执行」；对话原文不进入状态层
  • 交叉链接：状态层页、门面运行时页与门面 Playbook 均指向新页面；架构侧边栏新增「状态如何驱动 Agent」

📚 文档（门面 Agent Playbook：愿景、能力与场景） ​

  • 新增对外页 site/platform/facade-agents.md：解释门面的三层身份（人类访客 / 需求方 / 其他 Agent）、做什么与不做什么、三种交付模式、一次对话的完整链路，以及 8 个典型场景（HS Code、CE 认证、合同审查、运费询价、商标检索、合规组合包、展示页、周期服务）
  • 新增内部 Playbook docs/agent-architecture/facade-agent-playbook.md：溯源段 18/19/20/E2/E3/E7 的原始结论，补齐能力地图（已实现 / 未闭环）、14 个应用场景的具体对话与状态流转、4 套演示脚本、反例与度量
  • 如实标注边界：intake-only 不发布订阅、A2A 入站 message/send 仍只做 propose、自定义域名与嵌入浮窗未做；文档不把方向写成现状
  • 侧边栏：平台分组新增「门面 Agent」，与「核心概念」「信任模型」并列

📚 文档（AgentRuntime 模块手册） ​

  • Agent 文档拆成两个模块页：site/architecture/agent-integration.md 讲外部 Agent（A2A / Gateway / 轮询、注册与最小骨架）；site/architecture/agent-runtime.md 讲门面 Agent（对话/状态/任务节点入口与 AgentRuntime）。平台内部编排 agent 暂不在对外文档展开（后续可能调整）
  • 修正旧页与实际不符的表述：「平台不运行 Agent」、匹配按 interactionMode 过滤、maxTurns=50、固定重试 3 次；同步更新首页、快速开始、安全页、生命周期页与 A2A 模块页的链接
  • 门面页 包含：能力矩阵（无会话/预算/工具/memory/并发/取消/流式/结构化输出/观测）、Chat 与 State 两个入口对照、Chat 的 HTTP/SSE 示例、State 的契约→写入→订阅→回写链路、真实延迟表、错误码、配置项、已知边界
  • 模块 README 补充能力矩阵、两入口对照、结构化输出（response_format=json_object + envelope + Ajv 兜底）与实测延迟；明确 README 只保留实现纪律，集成手册指向站点页
  • 侧边栏 拆成两项：「外部 Agent 接入」与「门面 Agent 与 AgentRuntime」，两类 Agent 分开入口
  • 文档明确区分：AgentRuntime 的毫秒级开销 vs 模型往返；外部 A2A 的延迟由供应商运行时决定，不计入 AgentRuntime 指标

✨ 新增（门面结构化输出：统一 envelope + JSON mode） ​

  • 统一输出信封 FacadeResultEnvelope：{ status, summary, data, follow_up?, confidence?, text? }；data 来自对应 skill 的 output_schema，intake-only 门面允许任意对象。26 个 facade-* 的契约已迁移（stateContract.version v1→v2），旧 schema 备份在 metadata.outputEnvelopeMigration.previousSchema
  • 状态唤醒 JSON mode：prompt 强制“只返回一个符合 schema 的 JSON 对象”；EngineChatService / AgentRuntime 透传 response_format: { type: 'json_object' }。对话模式不启用，保持自然语言
  • 解析与校验：parseStructuredOutput 支持纯 JSON、```json 围栏、前后夹说明文字；consumer 与同步 executor 校验通过后把对象写入 state，失败写 errors/{eventId} 并抛出
  • 供应商边界（实测）：DeepSeek 支持 json_object，不支持 json_schema strict（HTTP 400）。字段级约束由平台 Ajv 校验兜底，不能依赖模型强制
  • 迁移脚本 scripts/migrate-facade-output-envelope.ts：默认 dry-run，--apply 写入，幂等（已是 envelope 则 skip），支持 --only=；seed 脚本同步生成 envelope
  • 验证：9 suites / 112 tests 通过；真实门面 facade-hs-code 在 10.65s 返回合法 envelope（validation.ok=true）；npm run build 通过；迁移 dry-run 26 个全部 skip（幂等）

⚡ 性能（状态写入与派发解耦：writeMany + outbox） ​

  • 批量写入 StateService.writeMany(inputs, { dispatch })：一次事务写完整批（事件 + 物化 + outbox），同一 namespace 只做一次 $inc 分配连续 seq；批内 path 不允许重复（版本语义不猜测）。write() 保持为单条兼容层，默认 dispatch: 'sync'，返回值与行为不变
  • 异步派发 dispatch: 'async'：outbox 与事件同事务写入，提交即返回 queued: true，写入延迟不再受订阅数量与外部 agent 影响
  • StateOutboxWorker：@Interval(500ms) 原子领取，按 namespace/seq 串行派发，前序未完成不越过；handler_error 指数退避（上限 5 次），processing 超 5 分钟重新领取；at-least-once，执行器按 eventId 幂等
  • 运维边界：PM2 当前单实例 fork，worker 在 NODE_APP_INSTANCE !== '0' 时停用；扩多实例前需 namespace lease 或独立 worker
  • 实测（真库）：单条 sync 写入 111 ms / 端到端 1.7 s；批量 async 写入 30 ms / 端到端 2.5 s
  • 测试：state-write-many.spec.ts（10）+ state-outbox.worker.spec.ts（7）；state 模块 14 suites / 180 tests 通过；npm run build 通过；真库 e2e 验证 async 链路（outbox pending → dispatched，结果正确回写）

✨ 优化（/agents 目录：流式浏览与列表缓存） ​

  • 流式浏览: /agents 首屏只取 15 条；向下滚动由 IntersectionObserver（提前 600px）自动追加下一页，到底显示结束提示；筛选/搜索变化时回到第 1 页重新加载
  • 后端缓存: GET /api/agent-profiles 的分页结果缓存 60 秒；总数单独缓存 5 分钟（countDocuments 是目录查询最慢的一步，翻页不再重复统计）。缓存版本写入 Redis，PM2 多实例共享同一版本，写操作后 INCR 即可整体失效；Redis 不可用时自动降级为进程内 TTL 缓存，不影响接口
  • 目录过滤: 对外列表默认不展示平台内部 Agent（metadata.platform_internal / domain === 'platform'）、平台自营/测试供应商（ownerId 名单，含 OpenClaw A2A 适配器）与 A2A 端点指向 localhost 的本地占位条目；内部调试可传 includeInternal=true 绕过
  • 稳定分页: 排序追加 _id 作为 tie-breaker，避免 createdAt 相同时无限滚动出现重复/漏项
  • 载荷收窄: 列表只投影卡片所需字段，不再把 inputSchema / outputSchema / apiKey 随公开列表返回
  • 缺陷修复: 前端搜索参数由 search 改为后端 DTO 实际支持的 keywords（此前被 ValidationPipe 白名单剥离，搜索框不生效）；searchAgents 改用 apiFetch 以复用统一的响应信封与 401 处理
  • 测试: 新增 agent-profile.query-cache.spec.ts（缓存命中、分页键隔离、写后失效、内部过滤、includeInternal 旁路）；agent-profile 13 suites / 92 tests 通过；前端 tsc -b、ESLint、生产构建通过

✨ 新增（Agent 展示页：业务对外门面） ​

  • 数据: AgentProfile.showcase 子文档——slides[]（Markdown，聊天页右栏幻灯片）+ site（自包含 HTML，平台内为该 agent/组织构建的静态站点）；generatedBy 区分 template / ai / manual
  • 独立页面: 新增公开路由 /agent/:agentId（hero + Trust profile + 幻灯片卡片 + sandbox iframe 站点，可全屏），与 workspace 分离——workspace 负责对话，本页负责介绍与引流
  • 对话内弹层: 右栏「Open page」与 agent network 的点不再跳路由，改为 AgentShowcaseOverlay 原地展示完整门面，Esc / Close 回到对话；/agent/:agentId 保留给直接访问与分享
  • 缺陷修复: <button onClick={onOpenPage}> 把 React 的 MouseEvent 当作 agentId 传给 onOpenAgentPage(agentId?)，导致跳到 /agent/%5Bobject%20Object%5D
  • 信任档案: 展示页接入信任层的公开端点 GET /api/agent-profiles/:agentId/trust，新增 Trust profile 卡片——T0/T1/T2 证据等级（不是评分）、身份验证等级（I0/I2）、服务契约完整度（40/100 + 是否可编排）、履约指标（无样本不给百分比）、必须展示的「尚未验证」清单与默认折叠的契约缺口；认领状态并入 Identity 行，hero 不再重复
  • 标准模板: buildStandardShowcase() 只读 profile 已有字段确定性生成，新注册 agent 无需 AI 也有完整页面；缺失字段显式写“conversation 中确认”，不臆造价格/资质
  • AI 生成: POST /api/agent-profiles/:id/showcase/generate（owner，5/min）——基于 profile 事实 + owner 补充说明产出 slides 与站点 HTML；非 JSON / 空结果直接 400 且不改动现有页面；失败不落库
  • 人工编辑: PUT /api/agent-profiles/:id/showcase（owner），整体替换且拒绝空提交；GET /api/agent-profiles/:id/showcase 供 Builder 读取草稿
  • 公开读取: GET /api/agent-profiles/by-agent-id/:agentId/showcase（公开，仅 active），无自定义内容时回退标准模板
  • 安全: sanitizeSiteHtml() 剥掉脚本/iframe/表单/事件属性/javascript:/data: 与 CSS expression()；前端再用 不含 allow-scripts 的 sandbox iframe 承载，两层独立成立
  • 右栏: 单一 agent 直聊时显示「幻灯片摘要 + 紧凑地图」；任务/多 agent 场景仍显示网络地图，地图上的点可点击进入该 agent 页面
  • 国旗: 新增 CountryFlag，把 DE / Germany / 德国 归一为 ISO 3166-1 alpha-2 后渲染 emoji 旗帜（零依赖）；marketplace 卡片显示「旗帜 + 城市」，展示页 hero 显示「旗帜 + 城市, 国家代码」；识别不了就不显示，不猜国家
  • 列表入口: marketplace 与 supplier 卡片只保留 View page，移除 Start Chat / Chat；对话入口统一收在展示页 hero 的 “Talk to this agent”
  • Builder: 每个 profile 卡片新增 Showcase 面板——AI 生成、补充说明、slides/HTML 编辑、预览、保存
  • 测试: showcase-template.spec.ts（5）+ agent-showcase.service.spec.ts（7）全通过；前端 tsc -b 与生产构建通过；弹层与 Trust 卡片在生产页面用 Playwright 核验

🔒 安全（资料更新不能自封“已验证”） ​

  • 缺陷: PUT /api/agent-profiles/:id 使用 Object.assign(profile, dto)，且 DTO 允许任意 metadata；服务商可整体覆盖 metadata.org.claimStatus = 'verified' 与 website，而公开主页 / marketplace 直接读这些字段。CreateAgentProfileDto 同样允许创建时写入任意 metadata
  • 修复: UpdateAgentProfileDto / CreateAgentProfileDto 移除 metadata 写入口；create() 不再接受调用方 metadata；update() 改为显式字段白名单，未传字段保持原值，null 仍可清除 stateContract
  • 新增: PATCH /api/agent-profiles/:id/org 允许服务商维护展示字段（name / logoUrl / phone / city / country / website）；claimStatus / verifiedAt / sourceUrl / listedFrom / id 仍只读；修改 website 会把已验证状态退回 pending 并清除 verifiedAt，避免页面链接变更后自动继承旧信任
  • 兼容性: 仍通过 update 接口传 metadata 的调用方会被忽略（前端只传 stateContract，不受影响）；企业资料编辑走新的 org 接口
  • 测试: 新增 agent-profile.update.spec.ts（5 条）与 agent-profile.update-org.spec.ts（8 条），覆盖伪造认证字段、白名单写入、URL scheme、website 重新验证、非 owner

✨ 新增（P3 编排级证据与归责） ​

  • CompositionRun / CompositionRunService: 每次 TaskExecution 一条 run（executionId 幂等），记录节点状态、失败错误码、耗时、成本、信任决策与 incidents
  • 执行链接入: TaskExecutionService 在开始/节点完成/失败/blocked/执行结束处写 run；追踪失败只告警，不影响任务执行
  • 节点回指: 派单时为节点生成 TrustDecision，把 trustDecisionId 写入 CompositionRun 节点，能回答“当时为什么选这个 agent”
  • 失败分类: 新增 handoff_schema / handoff_timeout / handoff_transport / agent_error / platform_error；指标拆分为 handoffFailureRate / agentFailureRate / platformFailureRate
  • 熔断与替换: CircuitBreakerService 连续失败后把 agent 排到候选末尾；selectNodeCandidates() 支持 fallbackAgents / fallbackAgentIds / matchedAgents，节点失败自动换下一个候选，每次尝试写入 attempts
  • 替换指标: fallbackNodes / fallbackAttempts / fallbackSuccesses / fallbackRate
  • 真实链路 e2e: 新增 apps/hushwork/test/composition.e2e-spec.ts（真实 Mongo + MySQL + Nest），执行一条 workflow 后验证 CompositionRun 落库、节点完成、指标与 HTTP 查询同源
  • 归责落点: Resolution 新增 liableAgentId / nodeId；Dispute 也新增 agentId / nodeId，优先从 Delivery 取，缺失时从最近 CompositionRun 节点补；处置默认继承争议的责任 agent/node
  • 端点: GET /api/trust/composition/metrics、GET /api/trust/composition/by-execution/:executionId、GET /api/trust/composition/:runId
  • 指标: 端到端成功率、交接失败率、agent 失败率、平台失败率、人工介入率、组合事故率、替换率
  • 测试: 18 suites / 161 unit tests；composition e2e 1 passed；npm run build 通过

✨ 新增（P2 内部信任策略） ​

  • TrustPolicyService: 按 identity/capability/assurance/composition + credentials/maxPrice/maxLatencyMs/minSamples/requireEscrow/requireSignedManifest 评估 agent；返回 allowed + observed + reasons，并把每次决策写入 agent_trust_calls
  • 端点: POST /api/trust/evaluate、GET /api/trust/calls/:callId
  • 匹配接入: AgentMatcherService.match(skillId, subDomain, requirements?) 可选按 policy 过滤候选，并在 MatchResult.trust 附带可解释决策；不传 requirements 时保持原行为
  • 默认安全: requireSignedManifest 需要 I3；当前只落地到 I2，因此该要求会明确拒绝，避免把“域名验证”误当“签名 manifest”
  • 测试: trust 6 suites / 41 tests；agent-matching 6 tests；npm run build 通过；docs:api 416 个端点

✨ 新增（公共 Agent 信任层方向） ​

  • docs/agent-architecture/public-trust-registry-spec.md: 把信任层外化为公共 registry —— 任何 agent 都可申请护照、提交证据、被查询；核心是“可验证护照 + 证据网络”，不是匿名打分的大众点评
  • 证据分级: E0 自报 → E1 导入回执 → E2 第三方审计 → E3 平台见证 → E4 平台见证 + 托管 + 验收 + 裁定；外部 agent 可只做护照，不要求进驻交易
  • 评价协议: 评价必须绑定 evidenceRefs，精确到 agentId + version + skillId；无证据评价不计分，不可删除、只能追加更正
  • 跨平台互认: 护照可导出为 VC/JWT，离线可验、吊销可同步、不自动传递信任
  • 阶段: A 平台内护照 → B 外部自助护照 → C 证据导入/第三方验证 → D 跨平台互认 → E 评价网络
  • 关系: trust-layer-spec.md 的平台内信任层仍是第一方强证据；公共层是外溢，不替代平台交易

✨ 新增（信任层事实口径） ​

  • 契约评分: libs/modules/src/trust/contract-score.ts 按 10 项（I/O schema、错误模型、幂等、生命周期、SLA、计费、数据政策、版本/弃用、验收、golden cases）计算 0–100，< 80 不允许进入自动编排
  • 履约指标: libs/modules/src/trust/trust-metrics.ts 从派单 / 交付 / 验收 / 争议 / escrow 事实派生交付率、验收通过率、一次通过率、按时率、争议率、赔付率、p50/p95、复购率；所有比例带 n、窗口、methodVersion，n < 20 标记 insufficient_sample，无数据返回 null
  • 快照与证据: 新增 TrustModule、agent_trust_snapshots（可重建缓存）与 agent_trust_evidence（只追加证据）；TrustMetricsService.rebuild(agentId) 从 offline_tasks → fulfillment_deliveries → fulfillment_acceptances / fulfillment_disputes / escrows 串起事实
  • 审计脚本: npm run trust:audit 对 active/testing profile 输出 contractScore、新旧口径差异；默认 dry-run，--commit 才写快照
  • 首次审计: 本地 3 个 profile 全部低于 80 分（平均 40）；其中一个 legacy totalExecutions=29，但 fulfillment 侧只有 23 次派单、2 次交付，证明 legacy 字段不能直接作为信任证据
  • 设计文档: docs/agent-architecture/trust-layer-spec.md（v0.3）

✨ 新增（P1 域名归属验证） ​

  • DomainTrustVerifier: 优先 https://<domain>/.well-known/agent-trust.json，失败回退 DNS TXT _agent-trust.<domain>；只接受注册域名（拒绝 localhost / IP / 端口 / 内网后缀），HTTPS only、5s 超时、重定向只允许裸域与 www 互换
  • AgentTrustService: 验证结果写入 agent_trust_evidence（kind=domain_control、dimension=identity、level=I2）；profile 只写只读投影 metadata.org.domainVerification 与 verifiedDomain，不改 claimStatus
  • 公开端点: GET /api/agent-profiles/:agentId/trust 返回身份 / 契约完整度 / 履约指标 / 未验证项，不泄露 apiKey / a2aEndpoint / callbackUrl
  • 服务商端点: POST /api/agent-profiles/:agentId/trust/domain/verify（仅 owner，5 次/分钟）
  • 测试: trust 模块 5 suites / 30 tests 通过；docs:api 生成 site/api/agent-trust.md（2 端点）

✨ 新增（验收事实入口） ​

  • POST /api/fulfillment/tasks/:taskId/acceptance: 买家验收一次交付；body { result, deliveryId?, agentId?, note? }；同一任务多交付时必须指定，重复验收返回 409
  • 权限: 以 offline_tasks.userId 校验买家；派单记录缺买家身份直接拒绝
  • 托管联动: 存在 held escrow 时按验收结论结算（accepted / conditionally_accepted → released；rejected 且无裁定时结算拒绝，但验收事实保留）
  • 失败隔离: 结算失败不回滚验收，只记录 warning 并返回 escrow.settled=false
  • 前端: Results 页新增 Accept / Accept with conditions / Request changes；提交后显示 acceptanceId 与托管结算结果；同一任务多交付时要求先选择 agent
  • 页面级 e2e: 新增 playwright.config.ts + e2e/acceptance.spec.ts，覆盖 4 条路径（accepted / conditionally_accepted / rejected / 多交付先选 agent）；npm run test:e2e:ui 自动启动前端并跑 Chromium，不依赖真实登录或数据库
  • 测试: fulfillment 3 suites / 52 tests；Playwright 4 tests 通过；docs:api 生成 site/api/fulfillment.md（1 端点）

✨ 新增（对话闭环真库验证） ​

  • 门面闭环 e2e: 新增 apps/hushwork/test/facade-dialogue.e2e-spec.ts（真实 Mongo，自建自清）：建 session → 本地对话（mock LLM 调 submit_request）→ request 事件带 conversation_id → 订阅命中 → 执行器写 resultPath → SSE 推 result → GET .../result = ready；另含「同会话重复提交 ⇒ 幂等」一例。2 例全绿，不依赖执行顺序
  • 因果链可验: 断言 result 事件的 causedByEventId 指回 request 事件；会话只存指针（submission），对话原文不进状态层

🔒 安全（对话提交的写权限缺口） ​

  • 缺陷: submit_request 以 actor: user:{id} 写 /tasks/{taskId}/requests/{会话id}，路径里没有用户 id ⇒ 被 L0 默认写权限策略 403。工具把 403 当普通工具错误吞掉，模型照样回「已提交」，submission 为空 —— 阶段 3 的「确认 → 写状态 → 触发下游」在真实状态层上从未成功过（单测用假 StateService，看不到这层校验）
  • 修复: /tasks/{taskId}/requests/{requestId} 归入平台代记事实（request: ['user', 'platform']），保留 actor = 确认的用户，「责任方 = 写入该变更的 actor」不破；归属校验仍由对话入口（session 必须属于该用户）完成。getTrace() 读取时显式排除 requests（需求是下游输入，不是履约痕迹）
  • 防绕过: 同一解析器只认 4 段 /tasks/{t}/requests/{r}，多一层即不认

✨ 新增（SSE 生产化：取消、心跳、结果推送） ​

  • 断连取消上游模型: 连接 close 触发 AbortSignal，经 sendMessage → AgentRuntime.run/runStream 传到每一次 LLM 调用的 controller，上游生成真正停止；取消抛 AgentRuntimeCancelledError，不计为失败（stopReasons.cancelled，并发计数照常回落），这一轮不落库（messages / tokensUsed 都不推进）
  • SSE 心跳: 空闲时写 : ping 注释行（走同一背压路径），避免代理把长连接当空闲连接掐掉
  • 结果主动推送: done 之后若本轮有 submission.resultPath，同一连接继续等待并推 result 事件（waitForResult: false 可关）；超时后正常结束，GET .../result 轮询保留为兜底
  • 实现取舍: 等待读的是物化状态（resultPath 的 entry）而不是订阅命中回调 —— 后者只发生在写入方进程，PM2 两实例下会漏；指针读对哪个实例写的都成立
  • SSE 写端抽离: 背压 / 心跳 / 取消集中到 sse-stream.ts（SseStream），controller 不再手写 waitForDrain

新增环境变量（只影响新建连接/等待）：

AGENT_DIALOGUE_SSE_HEARTBEAT_MS=15000           # 空闲心跳，0 = 关闭
AGENT_DIALOGUE_RESULT_PUSH_TIMEOUT_MS=30000     # done 之后等结果的上限
AGENT_DIALOGUE_RESULT_POLL_MS=500               # 服务端等待时的读间隔
  • 测试: agent-gateway / state / agent-runtime / fulfillment 27 suites / 318 tests 通过；真库 e2e 2 例通过；docs:api 重新生成（仅端点摘要变更）

✨ 新增（概念定稿与目录扩张） ​

  • 三层模型定稿：Company（ownerId = userId + metadata.org）→ Agent（一个业务，AgentProfile）→ Skill（可多个）。新增 /architecture/concepts 页面与 docs/agent-architecture/glossary.md
  • agentId 自动生成：平台托管 Agent 创建时由后端生成 agent_<uuid>，CreateAgentProfileDto.agentId 标为 deprecated；domain / subDomain 明确只用于检索，不参与身份识别
  • 行业 Agent 目录：scripts/seed-industry-facades.ts 首批 26 个行业 Agent（15 个 local-skill、11 个 intake-only），配套 docs/agent-architecture/industry-facade-catalog.md
  • 资料认领：新增 agent_claims 集合与 POST /api/agent-profiles/:agentId/claim（公开、限流）、GET .../claim、POST .../claims/:id/review；前端 /claim/:agentId 页面
  • 服务商控制台：GET /api/agent-profiles/supplier/console，聚合企业档案、delivery 能力、契约发布与履约结果；页面 /workbench 重做

🔄 变更 ​

  • workspace 路由：/chat → /workspace（旧路径保留重定向），页面目录 pages/chat → pages/workspace，ChatArea → WorkspaceArea
  • 对话历史恢复：刷新或切换会话时从 GET /api/gateway/dialogue/sessions/:id 重放消息。此前 agent 对话模式直接跳过历史加载，且库里 agent 回复的 role 是 agent（前端只认 assistant），导致历史里只剩用户输入
  • 侧栏时间线：任务对话与 agent 直聊合并为一条按时间排序的列表，用 Agent / Task 角标区分，两类条目都可删除
  • PM2 单实例：instances: 1 + exec_mode: fork，移除 wait_ready / listen_timeout（应用从未发送 ready 信号，导致每次 reload 白等并出现新旧版本混跑）；发布命令改为 pm2 restart hushwork
  • workspace 空状态分场景：agent 直聊时不再显示「Hushwork matches the agents」的通用文案，改为 Ask {服务商} + 面向该服务商的三句建议；建议刻意避开价格与工期，避免诱导 intake-only 的 Agent 做出承诺
  • 右栏 agent network 显示当前服务商：单 agent 直聊没有执行轨迹时，补一个节点（agent 名 + org.name 组织名），刷新后仍保留

🐛 修复 ​

  • 模型名收敛：新增 chat-models.ts，resolveChatModel() 把任意来源的模型名收敛到网关支持的 deepseek-flash / deepseek-v4-pro；修复 deepseek-v4-flash 与 gpt-4o-mini 透传导致的 400
  • 会话 runtime 校准：旧会话默认存 external，本地 Agent 被当成"离线外部 agent"并提示排队；现在按 profile 能力重新判定，前端只在 runtime=external 时提示离线
  • 删除后无法重建对话：删除会话时同步清理 sessionStorage 去重缓存
  • 身份绑定：对话会话按 profileId 精确绑定（此前一个 agentId 可能对应多条 profile）；外部注册幂等键由 agentId + subDomain 改为 agentId
  • 一次 Start Chat 建出两条会话：创建会话的 effect 依赖 isBooting，启动阶段它变化一次就让 effect 重跑，两次都满足创建条件（实测两条只差 ~150ms）。前端增加在途锁，服务端增加 reuseActive 幂等：同用户 + 同 agentProfileId 已有活跃会话时直接返回该会话
  • 供应商页全部落到 /supplier/platform：收录企业共用平台账号，按 ownerId 聚合只能得到同一页。新增 metadata.org.id（企业 slug），getSupplierHome 先按 ownerId 查、查不到再按 org.id 查
  • 市场把服务商显示成平台名或编造名：ownerName 曾被统一覆盖成平台名；已回写真实企业名，卡片改为 org.name 优先；未采集到的写 Unclaimed listing 且只保留 unclaimed 角标
  • 采集脚本编造企业：collect-orgs.ts 增加公司名清洗（剔除 title 里的 slogan），seed 删除 26 条编造的 *Desk 占位名；采不到真实企业时不再回填编造的公司名与城市
  • 刷新后 agent network 节点消失：dialogueAgentName 只在创建会话与点侧栏时写入，刷新走缓存复用分支不会恢复；现在公开档案请求会兜底回填该名称

[1.1.0] - 2026-10-20 ​

✨ 新增（门面契约与本地运行时） ​

  • 门面契约: AgentProfile.stateContract 声明输入/输出路径与触发 pattern；POST /api/agent-contracts/:agentId/compile 编译成 state_subscriptions，支持 dry-run、版本冻结、output path 冲突拒绝
  • 本地门面执行: 无 a2aEndpoint 的 active profile 由 AgentRuntime 托管执行；输入取事件快照并按契约 schema 校验，输出按契约路径回写
  • active 准入: 只有 active 可发布契约、被状态唤醒；suspend/retire/draft/testing 会禁用订阅，状态变更失败会回滚
  • 文档: facade-session-state-spec.md 明确 Session / State / Action 边界与资源上限

✨ 新增（Phase 13 阶段 4：对话观测与压测） ​

  • 对话指标扩展: DialogueMetrics 增加 tokens/session、tokens/turn、会话关闭数、两类 429（会话配额 / 运行时并发）、TTL 过期（410）与主动回收、轮次延迟分位数和进程资源；GET /api/gateway/dialogue/metrics 字段同步扩展
  • 指标采样持久化: 每 15 秒写 agent_dialogue_samples（7 天 TTL），新增 GET /api/gateway/dialogue/history?minutes=&limit= 供趋势与回归对比
  • 主动 TTL 回收: AgentDialogueService 每分钟把「已过期但 TTL monitor 尚未删除」的活跃会话标记为 expired，回收失败只记日志
  • 监控页对话区块: /dashboard/agent-runtime 新增 Dialogue KPI、轮次趋势、429/TTL/延迟与资源明细；运行时指标与对话指标分开加载
  • 对话并发压测: 新增 npm run bench:dialogue，默认 100/500/1000 并发 × 3 轮，mock LLM 固定延迟，输出吞吐、p50/p95/p99、错误率与 RSS/heap 峰值
  • 测试: dialogue.metrics / agent-dialogue.service / agent-gateway.controller / dialogue.benchmark 4 suites / 39 tests 通过；前端 tsc --noEmit 通过

🔧 重构（P4：去图化收尾） ​

  • 执行死代码下线: 删除 executeConditionNode / executeMergeNode / executeLoopNode / executeWaitNode，删除 workflow-execution-strategy.service.ts 与 workflow-dataflow.service.ts；WorkflowExecutorService 只保留 start / agent / end 三种节点。WorkflowNodeType 的 icon / color / configSchema 等展示元数据一并删除
  • 保留 workflow-template（刻意）: 模板是计划层（推荐 / 选择 / 从模板实例化 Workflow），不是执行引擎。agent loop 仍从 Workflow 文档读取兼容计划，模板仍有真实调用面，不能因为“执行去图化”就删除
  • DAG 画布改为事件投影: /task/workflow 的 Diagram 现在优先从 GET /api/task/:id/trace 派生节点、依赖边与状态；只有没有轨迹的历史任务才回退到 Workflow 结构。节点状态不再接受 WebSocket 第二条状态源，也移除了 status 兜底轮询
  • resume 改为事件重放: 新增 TaskAgentLoopService.completedStepIds()，从 L0 事件重放已完成 step，与 TaskExecution.completedNodes 取并集；进程重启后不依赖内存状态也能从断点继续，已完成的 step 不会重复派单
  • 测试: 后端 workflow / task / demand-translation 10 suites / 84 tests 通过；前端 tsc -b && vite build 通过

✨ 新增（P3 主体：执行去图化 + 轨迹流界面） ​

  • 执行由运行时循环驱动（默认）: TaskExecutionService 不再先做拓扑排序再逐节点执行，而是每一步执行前才决定下一批可执行 step；同批无依赖 step 真并发，前置失败的 step 不派发并把原因写进 L0。TASK_EXECUTION_MODE=graph 可回退旧的图驱动路径
  • 每一步都落 L0（审计前提）: 每次 dispatch 先写 /tasks/{taskId}/steps/{stepId}（写失败即不派发），完成后写 completed / failed；前置失败的节点写 blocked 事件，依赖未满足的节点写 waiting 事件（可见，不隐藏）。决策点写 /steps/{stepId}/decision（选了谁、为什么），不落 token 级推理
  • 轨迹投影接口: 新增 GET /api/task/:id/trace，从 state_events 投影出 step / batch / toolCall / 并发组；轨迹流与 DAG 读同一份事件源
  • 轨迹流主界面: 新增 TraceStream / ToolCallRow / ConcurrencyGroup。工具调用折叠成一行（展开看 Payload / Result / Timing）；并发组组头显示 并行执行 · N 个 agent · M/N 完成，折叠后进度仍在；waiting（依赖 X） 与 blocked 都显式可见；产物直接内联可点击
  • DAG 降级为只读总览: /task/workflow 移除 execute / restart 入口（restart 改为新建 run 的语义），只保留 pause / resume；新增 Trace 标签页，与聊天页共用同一轨迹组件
  • 并发持久化修复: 并发节点完成时重新读取 TaskExecution 再合并 nodeResults（同一 execution 的短临界区互斥），避免 JSON 列 read-modify-write 丢结果
  • 真库 e2e: 新增 apps/hushwork/test/p3-agent-loop.e2e-spec.ts（2 例）—— ① 真实 Mongo/MySQL 上跑通「loop 执行 3 节点（CE/HS 并发、WEEE 等待 CE）→ GET /api/task/:id/trace → 交付 → 验收 → 托管 released」；② 中断在 step-a 之后时 resumeExecution 只继续 step-b/step-c，已完成节点不重复派发、不补写事件
  • 中断收尾: 进程被 kill / PM2 reload 时，step 可能停在 running 而没有终态事件，前端会一直转圈。现在：① 失败路径 handleExecutionFailure 补写 failed / blocked 事件；② GET /trace 在任务/执行为终态时，把仍为 running / waiting 的 step 投影成 failed / blocked，并写明中断原因。已用一个真实失败任务验证（groups.status 从 running 变为 failed）

✨ 新增（P1：需求受理升级为只读 tool 循环） ​

  • DemandAgentLoopService: 规则未命中时，模型先调 search_skills → match_agents → propose_plan，再给出最终拆解；三个 tool 零副作用、零计费（不建 Workflow、不派单、不扣钱），propose_plan 返回 sideEffects: 'none'
  • 可回退开关: DEMAND_AGENT_LOOP=off（或 0 / false）走旧单轮 translate()；循环抛错 / 超轮次也自动回退，买家无感
  • 目录外需求直接拒答: 循环返回空任务即 unmatched，不再多问一次单轮模型，避免幻觉填坑
  • 契约同步: search_skills / match_agents / propose_plan 在 INTAKE_TOOL_SPECS 里标记为 wired: true，测试锁死"只有这三个只读 tool 已接线"

🧹 维护（Jest ESM 配置） ​

  • transformIgnorePatterns 加 uuid / nanoid: 两者都是 ESM-only 包，此前每个 spec 都手写一份 jest.mock('uuid')（累计 17 处），每改一次依赖都要同步维护。现在由 ts-jest 统一转换，17 个同类 mock 全部删除；相关 24 个 suite / 337 例测试保持通过
  • e2e 配置同步清理: apps/hushwork/test/jest-e2e.json 此前用 moduleNameMapper 把 uuid / nanoid 指向手写 mock 文件（另一份维护点）。现改为同样的 transformIgnorePatterns + 转换 .js，删除 mocks/uuid.js / mocks/nanoid.js；既有 demand-translation e2e 6 例保持通过

✨ 新增（对外首页与导航重做） ​

  • 首页重新定位为「企业 Agent 工作的信任层」: 旧首页仍在讲「Make agent to work」和泛化模板卡片，无法解释平台与单 Agent / 普通 Agent 市场的差别。新版围绕文档中已落地的六层能力组织：需求翻译、能力匹配、多 Agent 编排、可验证交付、托管与结算、可审计状态；每条主张都对应代码与文档，不使用虚构客户、Logo 或增长数字
  • 互动式 Agent 蜂群 Hero: 新增 AgentSwarmCanvas —— 数百个发光点按 6 个能力域分组（Compliance / Trade / Finance / Legal / Data / Creative），组内保持连线，消息脉冲沿贝塞尔曲线跨组传递；鼠标靠近产生吸引场，点击向最近集群发出消息，并带交付涟漪。DPR 上限 2、移动端自动降粒子数、prefers-reduced-motion 静态降级、canvas 对读屏隐藏
  • 首页信息架构重排为 11 段: Hero + 证明条 → 六层能力 Bento → 四步流程 → 信任层（验证/托管/状态痕迹）→ 四类场景 → 买家/Agent 供给方双入口 → 工作区产品预览 → FAQ → 最终 CTA → 真实链接页脚。旧的通用 Features / WorkflowTemplates / MockBrowserWindow 组件已移除
  • 导航分层: 公开页面使用营销菜单（Platform 下拉、Solutions、How it works、Agents、Docs），登录后切换为 Workspace / Agents / Workflows / Workbench；My agents、Dashboard、Insight console、Policy settings 收进用户菜单。移动端提供完整抽屉面板。首页 anchor 导航支持跨路由滚动定位
  • 元数据与品牌标识: 新增 BrandMark 与 favicon.svg；index.html 增加标题、description、Open Graph / Twitter 卡片、theme-color 与 Inter / JetBrains Mono 字体
  • 规划文档: docs/product-spec/homepage-marketing-plan.md 记录定位、信息架构、菜单、动效规格、视觉 token、内容红线与实施清单
  • 移除独立注册页（登录即注册）: 邮箱验证码登录已由 EmailStrategy.validateEmailOrCreate() 在用户不存在时自动创建账户，因此删除 /register 路由与 RegisterPage，所有公开 CTA 统一指向 /login。首页输入的需求会通过 login state 传入 /chat（initialMessage），登录后直接继续，不丢失用户输入；登录页移除 “Create one” 链接并说明首次登录自动建号
  • 主色改为 Ink Indigo（商务化）: 原 #00d4ff / cyan 主色偏赛博，不适合 B2B 商业场景。主色改为 Ink Indigo #4F46E5（hover #4338CA），全站沿用 cyan-* 工具类通过 Tailwind palette 映射统一迁移到 indigo，避免逐文件漏改；新增 highlight-* 色板保留青色 #22D3EE 作为数据与 Agent 状态的辅助高光。品牌标、favicon、按钮、导航、Hero CTA 与页面渐变同步更新

🔒 安全（Skill 契约的任意代码执行） ​

  • ValidationEngineService 不再执行任意代码: 验收时执行的是 Skill 契约里的 verification.rules[].expression，而 Skill 可由外部 Agent 通过 POST /api/skills/submit 提交 —— 此前用 new Function('output', ...) 求值，等于对任何持有 api_key 的人开放任意代码执行；而 site/architecture/skill-catalog.md 的设计边界写的是"验证规则是白名单比较器，不支持任意脚本执行"。新增 libs/common/src/utils/safe-expression.ts：自己的 tokenizer + Pratt parser + 解释器（无 eval / new Function / vm），调用白名单（includes / every / some / map / Array.isArray / Object.keys / new Set(...).size），拒绝 __proto__ / constructor / prototype；表达式长度、AST 节点数、集合迭代次数、lambda 嵌套深度均有上限
  • 入库前预检: SkillCatalogService.create/update 新增 assertVerificationIsExecutable —— 不被支持的表达式在提交阶段就返回 400，而不是等到结算时才发现执行不了
  • 规则判定改为 fail-closed: 未知 ruleType 此前返回 passed: true（拼错类型会让一条约束悄悄失效），现在返回 false；type: 'assertion' 但缺 expression 同样判失败
  • 顺带修掉一族从未生效的规则: validateBySkill 此前签名里没有 input，而 cargo-tracking / multi-currency-accounting / transfer-pricing 的断言引用了 input.* ⇒ 这些规则一直在抛 ReferenceError 并被判失败。现在 input 作为可选作用域传入
  • 测试: 新增 libs/common/src/utils/safe-expression.spec.ts（52 例）—— 遍历 skills/*.json 全部 assertion 验证可解析、25 条断言语义用例（含嵌套 lambda 捕获外层参数）、20 条 RCE / fail-closed 负向用例

🔧 修正（目录外需求不再伪装成 CE 认证） ​

  • 兜底不再塞 ce_certification: 关键词规则未命中时，decomposeWithKeywords 此前会产出一个 ce_certification 占位任务（confidence 0.3，reasoning 写着 "defaulting to CE certification"）。后果是：买家问"日本 PSE 认证"会拿到一份 CE 认证任务 —— 而 chat-execute 不过滤 confidence，会直接拿它去匹配 Agent、执行并计费。给错的能力比说"没有"更糟：买家会因此以为自己已经合规
  • 改为明确的 unmatched: 占位任务标记 unmatched: true + subDomain: '__unmatched__'（mapToSkills 查不到即丢弃），TranslationResult 新增 unmatched: { topics, message }
  • 三条链路行为一致: controller.submit 在匹配之前短路返回 { tasks: [], taskId: null, unmatched }（不创建 workflow）；chat-execute 抛 BadRequestException 并用 unmatched.message（不匹配、不计费）；dialog 由既有 confidence >= 0.6 闸门挡住
  • 回退不丢缺口: LLM 任务全部不可用时仍回退关键词，但保留 uncovered —— 缺口主题不会因为回退而消失

✨ 新增（需求缺口图谱 + 买家准备清单） ​

  • 目录外需求不再静默丢弃（demand_gaps）: 需求翻译的 prompt 此前只允许返回「匹配已有 Skill」的任务，目录外需求（如"日本 PSE 认证"）会被直接丢掉 —— 平台既接不住，也不知道自己接不住。现在三个来源都进 demand_gaps：① LLM 明确报出的 uncovered；② LLM 给出但 Catalog 里不存在的 subDomain（此前只 warn 日志）；③ 一条都没拆出来的 unclassified。按归一化 topic 聚合（PSE certification / pse-certification / PSE 认证 归为同一缺口），带 count / sampleQueries（最近 20 条原话）/ routes 分桶 / userIds
  • GET /api/demand-gaps: 按频次列出缺口（需认证，sampleQueries 含用户原话）。用途是决定下一个 skill 建什么，而不是拍脑袋
  • 买家准备清单 GET /api/skills/:skillId/checklist: 同一份 Skill 契约，事前生成"你需要准备什么"（必填/选填字段、enum 取值、交付会被哪些规则检查、对话模式要收集的信息、交付时限），事后才用 verification.rules 判合格 —— 这是把「买家不必先是半个专家」从口号变成可读输出的一步
  • 健壮性: recordGaps 是 fire-and-forget，若 record 抛错会产生 unhandled rejection（Node 15+ 默认 fatal），已加 try/catch 兜底；缺口记录永远不影响需求翻译
  • 测试: demand-gap.service.spec.ts（11 例：归一化的大小写/标点/中文/连字符/空值/超长、upsert 字段、空 topic 不写库、route 键转义、落库失败不抛错、limit 钳制、minCount 转 $gte）+ preparation-checklist.spec.ts（7 例，含"真实 skills/*.json 全部可生成且 required 对齐"）+ 需求翻译新增 3 例缺口记录

✨ 新增（交付链路接入平台契约校验） ​

  • 交付时第一次按平台契约校验: submitResult 此前只用 ajv 校验 agentProfile.outputSchema（Agent 自己声明的输出形状），平台 Skill 的 output_schema + verification.rules 从未在交付链路上执行过 —— 求值器与规则都建好了，但没有任何业务路径会去跑它。现在 POST /api/gateway/tasks/:taskId/result 在 ajv 之后调用 ValidationEngineService.validateBySkillAndRecord()，按 skillId 取平台契约校验，并把结果写进 verification_results（metadata.source = 'agent_gateway'），响应里同时返回 verification 摘要（通过比例 + 每条失败规则）
  • 门禁默认 warn，可切 enforce: 新增 VERIFICATION_ENFORCE 环境变量，只有显式 true 才阻断交付（400、不入库、不计费）；默认记录但不阻断。理由：断言规则接入前从未执行过，直接强拦会一次性拒绝大量既有交付。判定逻辑抽成纯函数 verification-gate.ts（resolveVerificationMode / describeVerificationFailure / shouldBlockDelivery），与 EscrowSettlementPolicy / CompensationPolicy 同一风格，可整条替换
  • hasSkill() 跳过未知契约: skillId 不在 Catalog 时直接跳过校验，避免把"契约不存在"记成"交付不合格"
  • 测试: validation-engine.service.spec.ts（7 例：合规 / 规则失败 / 缺字段 / 落库抛错不阻断 / skill 不存在 / input 参与断言 / hasSkill）+ verification-gate.spec.ts（10 例：模式解析的大小写与非法值、失败消息逐条列出、warn 永不阻断）

📐 规格（Skill 契约合成） ​

  • 新增 docs/agent-architecture/skill-contract-synthesis-spec.md: 把"手工建 Skill（6–8 周/skill）"换成"语料 → 契约草案（小时级）"。核心是生成用模型、判定用代码：模型负责从法规/判例里抽字段与规则，生成的规则必须是数据（固化成契约），验收仍由确定性比较器执行。文档定义了输入输出契约、七步生成流程、三个人工介入点（歧义裁决 / 20% 抽检 / 发布签字）、六条质量门，以及验收标准中"至少一条规则能判出格式合法但结论错误"这条分界线

✨ 新增（Phase 12 / 参考案例 + 策略设置） ​

  • 参考案例可执行（npm run case:reference）: 三层机制此前没有一条代码把它们当一单生意跑完 —— 托管在 L2 开单、履约在 L1 录入、结算靠手工拼 settle()。新增 libs/modules/src/reference-case：用 l2-escrow-spec.md §1 的案例（AI 行业研究报告 ¥1000）把「支付 → 托管 → 交付 → 验收 → 争议 → 裁定 → 结清」串成可跑、可查、被测住的链路，accepted 与 disputed 两条路径都跑。scripts/fixtures/reference-case.json 是案例数据（改 --case= 可换案例）；npm run case:reference 默认 dry-run、--commit 写库、--cleanup 自清
  • 赔付金额第一次"有人算"（CompensationPolicy）: 此前 toBuyer = min(compensation.amount, amount) 里的 amount 没人负责算 —— "赔 30000 是谁定的、依据哪一条"没有答案。新增纯函数策略：争议事由 → 条款 → 比例 → 金额（缺件 30% / 质量不符 50% / 逾期 10%），依据写进 EscrowSettlement.reason；事由没有条款且裁定没给金额 ⇒ 409，不默认比例。配套 SettlementCoordinator 把 L1 的 Resolution + Dispute.grounds 接到结算上（这一段此前没有任何代码走过）
  • 商业规则改为后台可配置（PolicySettings）: 赔付条款 / 平台服务费 / 争议时限 / 担保范围从代码常量变成一份带版本与审计的设置。改完对下一笔结算 / 新争议立即生效，不需要改代码或部署；每次修改 +1 版本并记录 before/after/actor/note（与设置同一事务，不会出现"改了但查不到谁改的"）；带 expectedVersion 提交时并发修改返回 409
  • 管理端点与页面: GET/PUT /api/sys/policy-settings、GET .../history、POST .../reset（JWT 保护）；/settings/policies 页面可编辑条款表、费率、SLA、担保范围并查看最近变更。刻意不进用户导航 —— 它配的是平台商业参数，不是 🟡 履约字段形状
  • 结算新增 toPlatform: 平台服务费从交付方所得中扣，金额守恒升级为 toAgent + toBuyer + toPlatform === amount（默认费率 0 时行为与 Phase 11 完全一致）；guarantee.scope = quality 时"附条件接受"不结算，等条件确认
  • 争议 SLA 不再为空字段: 发起争议时按 dispute.slaHours（默认 72h）写入 slaDueAt；超时自动放款未实现（需要定时任务 + 争议状态机）
  • 文档生成器幂等: generate-api-docs.ts 此前把"生成日期"写进每篇文档、并按端点首次出现顺序给纯中文 tag 分配 uncategorized-N ⇒ 每次重新生成都产生几十个文件的纯噪音 diff。现改为固定页眉 + 按 tag 名排序后编号；连续两次生成文件完全一致
  • L1/L2 跨层事务（Phase 12）: FulfillmentService 的 6 个与 EscrowService 的 3 个 mutation 现在把 Mongo 事实写入 + L0 状态写入 包进同一个事务 —— 此前"先写 Mongo、再写 L0"，L0 失败会留下一条不入状态层的交付/结算（证据消失，trace 里看不到）。现在两者要么都成立、要么都不成立；订阅派发移到 commit 之后（外部副作用不能回滚）。真库 e2e 用反证证明回滚：买方 actor 写交付、agent 触发结算都被 L0 拒绝，Mongo 里没有交付、托管仍 held
  • 策略设置页：未保存保护: 表单与已保存快照派生比较，页头提示"有未保存的更改"，刷新/关闭时 beforeunload 拦截 —— 不会因为误关页面丢掉草稿
  • 状态层两条已知边界的定论: ① 非 /tasks/ 域此前是 Mongoose 的 Path taskId is required（500，难读），现在写入前显式拒绝（可读的 BadRequestException）—— 平台级数据用专用集合，避免落进"按 taskId 查不到"的盲区；② write() 改用 withTransaction，同一 path 的 WriteConflict 自动重试 ⇒ 并发写不再丢物化更新（真库 e2e：20 并发 merge 后 20 个键齐全、version = 20、verify() 一致）
  • 赔付上限 + 超时自动处置（Phase 12）: 两个此前"等商务"的规则变成设置项 —— compensation.capAmount（单笔赔付上限，默认 null = 不限；超过按上限赔付并在依据里注明）与 dispute.onTimeout（hold 默认 / release 自动放款 / refund 自动退款）。新增 libs/modules/src/dispute-timeout：每分钟扫描 slaDueAt，先定责、再结算、后关闭，actor 固定 system:auto-release，幂等且可补偿（定责成功但结算失败的下一轮会补结算）；默认 hold 不改变任何现有行为
  • 测试与文档: 单测 20 suites / 302 passed（state 145 / fulfillment 44 / escrow 80 / policy-settings 27 / dispute-timeout 6）；真库 e2e 12 suites / 136 passed + 1 skipped（新增超时动作 3 例、赔付上限 1 例）；contracts/swagger.json 与 site/api/ 已重新生成（377 → 380 个端点，新增 3 个策略设置端点）；文档站死链清理后 npm run docs:build 通过

✨ 新增（Phase 11 / L0 蜂群基础设施） ​

  • L0 状态层（W1）: 状态可寻址 / 可版本化 / 可复放 —— 按 /tasks/{taskId}/... 寻址；写入走仅追加事件日志（每条带 actor：人 / agent / platform）；replay() 从事件日志重建状态、verify() 校验「物化 == 重放」、readVersion() 取证历史版本与写入者。新增模块 libs/modules/src/state（MongoDB，复用现有连接）
  • 旁挂（硬约束：现有工作流行为不变）: 节点 config.stateWrites 显式声明才把输出写进状态层；未声明时零写入。两条执行链（WorkflowExecutorService 与 TaskExecutionService）都已接线，写入失败只告警、不影响节点执行结果
  • L0 订阅层（W2）: 订阅注册表 + path 通配（* / **）+ 白名单条件求值（无 eval）+ 防环（causedByEventId / triggerDepth，超过 maxTriggerDepth 只记事件不再触发）。出现第一个「非 workflow 驱动」的触发路径：状态写入命中订阅即真实执行工作流（WorkflowExecution.metadata.triggerSource = 'subscription'）
  • 执行闭环: 一次状态写入 → 命中订阅 → 真实执行工作流 → 节点按 config.stateWrites 把结果写回状态层 → 再次命中订阅……直到条件不再命中或达到 maxTriggerDepth 停下。新增 StateReplayService.traceCausation({taskId}) 重建因果链（每跳的 eventId / actor / triggerDepth 可查，可追溯 + 可定责）；并补上此前从未写入的 WorkflowExecution.taskId，使「状态 ↔ 执行 ↔ 任务」三者可互相寻址
  • 语义闭环（节点读状态）: 节点 config.stateReads 可声明读取状态层（input.stateReads.{as}，支持读历史版本）；未声明 ⇒ 零读取。两条执行链都已接线，与写侧完全对称。至此环携带业务语义：上游交付 → 下游节点读到交付内容 → 写回验收结论 → 再驱动下一跳
  • 外部事件驱动源: 环的起点不再只靠人工写状态 —— AgentGatewayService.recordA2ADelivery()（Agent 交付）与 recordInterruptedState()（请求人工介入）旁挂写入状态层，新增 source='agent_callback'、actor=agent:{agentId}（可定责）。旁挂失败只告警，不影响既有投递/结算/任务状态
  • 订阅直接驱动 Agent（execute_agent）: 订阅此前只能触发工作流；现在可以直接调 agent —— 按 AgentProfile.a2aEndpoint 走标准 A2A，否则走平台内部执行（不做 Gateway 派单，避免与 OfflineTask/计费语义混用），执行结果回写状态层 /tasks/{taskId}/agents/{agentId}/results/{eventId} 并携带触发链（causedByEventId / triggerDepth+1）⇒ 环的下一跳不再只能是工作流模板
  • 文档: 新增 docs/agent-architecture/state-layer-spec.md（逐字段标注 ✅ 有依据 / 🟡 待样本校准 / ❌ 不做，含现状盘点与禁令），并按 AGENTS.md 为模块补 README.md
  • L1 履约事实接到 L0（W3：trace 改读状态）: PR-5 的 fulfillment 骨架此前零调用、事实只在自己的 Mongo 集合里、getTrace() 靠拼四个查询。现在交付/验收/争议/处置每次都落进状态层并带责任方（agent 交付 / 买家验收 / 平台定责）—— 路径 /tasks/{taskId}/deliveries/{deliveryId}，验收嵌在交付下、处置嵌在争议下（把"一次交付只能验收一次""先定责再关闭"两条不变量编进地址）。写入是强制且失败即抛错（与节点旁挂相反：履约事实的产物是证据本身，静默残缺不可接受）；getTrace() 只读状态层重建一单的完整痕迹（零 Mongo 查询）+ 因果链 —— 「验证 = 一次状态查询」第一次成立。真库 e2e 含反证：清空 fulfillment_* 集合后 trace 依然完整
  • 运维：MongoDB 单节点副本集升级（runbook + 脚本）: 核查 W3 的"非事务缺口"时发现它不是跨库问题 —— fulfillment_* 与 state_* 同在 hushwork 库（shared.module.ts 单一默认连接），一个多文档事务即可覆盖；但事务要求副本集，而本机是 standalone（实测 Transaction numbers are only allowed on a replica set member or mongos，且 startTransaction() 在 standalone 上不报错——必须真实写入才暴露）。同源还查出两个更根本的缺口：L0 自身也是三步非事务（counter → 事件 → 物化；②成功③失败 ⇒ 事件在、物化不在，verify() mismatch），以及 dispatch() 的 matchEvent()/markTriggered() 未受保护 ⇒ 写入已提交却报错 ⇒ fail-loud 下调用方重试产生重复事实。新增 scripts/mongo-promote-replset.js（幂等；--check 只读；--initiate 做真实事务写入 + "应用那种连接"双验证，临时集合必定清理）与 docs/ops/mongo-replset-upgrade-runbook.md（前置事实 / 不可用窗口 / 备份 / 回滚）。⚠️ 需有 root 的人执行（本容器 sudo 不可用、/etc/mongod.conf 不可写；且 MongoDB 7.0 要求启动时已带 replSetName，故需重启 mongod）；代码侧事务改造未做

✨ 新增 ​

  • 手工录入通道（解开 W4 前置的死锁）: fulfillment 此前没有任何录入入口 —— 无 controller（刻意如此，禁令 2：🟡 字段不得进对外契约）、scripts/ 无脚本、FulfillmentService 零生产调用方。后果是任务拆解里反复出现的「一单真实交付」这个前置在技术上无法满足：即便商务签下供应商，也没有办法把一单录进系统（循环锁：要样本→要能录入→要字段先定形状→要样本）。新增 scripts/record-fulfillment-order.ts（npm run fulfillment:record）——走 service 层、不经 API，因此 🟡 字段不必先进契约（禁令 2 完好）；默认 dry-run、--commit 才写库；拒绝未替换的模板占位符（防把模板写进生产库）；录完打印 getTrace() / 状态层路径 / verify() 物化==重放 / 因果链，以及 🟡 字段的实际形状（deliverables[] / objections[] / grounds / ruling / compensation 的键集 —— 直接用于校准 fulfillment-spec.md §6 待定项）。模板见 scripts/fixtures/fulfillment-order.template.json；--cleanup --task-id=<id> 供演练后清理。⚠️ 通道 ≠ 样本：内置 --sample 跑通只是演练，§9 第一条要的仍是真实的一单

  • 修复（同日由录入演练暴露）：compensation 把 Mongoose 的 _id 写进了状态层: fulfillment.schema.ts 的 compensation 是内联子文档 schema（不是 Mixed），Mongoose 会为其自动加 _id，而 W3 的实现整体透传了它 ⇒ 状态层里出现 ORM 实现细节（实测 {"amount":0,"currency":"CNY","form":"none","_id":"6acf…"}），违反 fulfillment-state-wiring-spec.md §2.1 明示的纪律。此前的 e2e 没抓到，因为断言用了 toMatchObject —— 它允许多余字段（一个"看起来在断言"的弱断言）。已改为逐字段白名单（toCompensation()），并把 e2e 断言收紧为 Object.keys 精确比对 + 补两条单测。⇒ 教训：白名单要连嵌套一起白名单；toMatchObject 不能用来证明字段集合

  • L2 托管（W4：状态机 + L0 痕迹 + 可替换的赔付策略）: L2 的"托管"此前并不存在 —— Account（MySQL）虽有 usable/freeze 字段，但 AccountService.freeze() 只是改 status='2'（封号），没有任何代码把 usable 搬到 freeze，且该 service 零业务调用者；Order 又是活动/会员订单，与"一单交付"无关。本次新增 libs/modules/src/escrow：托管状态机（pending → held → released|refunded|split）+ 6 条不变量（一单一托管 / 只有 held 能结算 / 金额守恒 / 时间线只追加 / 终态不可再迁移 / actor 可定责）+ 托管事实落进 L0 状态层（/tasks/{taskId}/escrow，与 W3 同纪律：强制写入、失败即抛错、actor = 买家托管/平台结算）。分配规则做成可整条替换的 EscrowSettlementPolicy（纯函数，🟡 假设，默认 policyId='default-v1'）—— 商务/法务规则到位时换掉一个类即可，状态机与痕迹不动。金额强制整数最小单位：单位测试期间发现 JS 浮点下 899.99 + 100 !== 999.99，会让唯一可机器校验的资金约束失效（open() 直接拒绝小数）。🚫 不做真实资金转移：资金在 MySQL、履约事实在 MongoDB ⇒ 跨库 + 资金安全，且费率/赔付上限/SLA 全属商务法务；EscrowSettlement 就是留给资金体系的划转指令。产品负责人决策：主动放宽"必须先有真实业务"前置，改用典型商业案例作为显式假设基线（逐条标注 🟡、可整条替换 —— 与"暗中猜测"的区别是假定写下来且可推翻）；见 docs/agent-architecture/l2-escrow-spec.md

  • 技术收尾（三个缺陷 + 假设 4 首次实测）: ① 修：StateService.write() 的 ④ 派发订阅发生在 ①②③ 已提交之后，而 dispatch() 里 matchEvent() / markTriggered() 未受保护 ⇒ 抛错会让调用方以为"没写进去"而重试 ⇒ 在 W3/W4 的 fail-loud 语义下制造重复事实（第二条 Delivery / 第二次托管）。现改为：持久化完成后派发失败不得让写入失败，但以 handler_error outcome 返回（detail 写明"写入已提交，勿重试"）。② 实测假设 4（首次）：replay 16k–38k ev/s、2 万事件 <1.3 s、内存不随事件数增长（流式确实成立）；写侧约 200 ev/s（每条 4–5 ms），一单 100 条 ≈ 0.5 s —— 对履约/托管够用，高频场景不够。③ 修：verify() 在重放被 MAX_EVENTS=20000 截断时与完整物化比较，实测 2.5 万事件产生 200 处假阳性（数据其实一致）；现 replay() 输出 truncated，verify() 截断时只查 path 存在性并返回 inconclusive，同时明确「ok && !inconclusive && !truncated 才算通过」。④ 另记录两处待决（非 bug）：非 /tasks/ 域因 taskId required 写不进去、同一 path 并发写会丢物化更新（需调用方传 expectedVersion）。新增 scripts/bench-state-replay.ts（npm run bench:state-replay，独立 namespace 自清）+ docs/ops/state-replay-benchmark.md

  • 只读操作台（Insight）: 三层此前都没有 controller，真实业务跑起来人没有任何界面可以看到一单发生了什么。新增 GET /api/insight/tasks/:taskId + /insight 页面：输入 taskId → 履约事实（交付/验收/争议/处置）、托管状态与结算指令、原始事件流（取证入口）、因果链。刻意只读 —— 录入表单会替业务把 🟡 字段形状固化到界面上，而只读视图只展示已有数据，真实样本回来不用重做。端点用 @ApiExcludeController() 排除出 contracts/swagger.json（能用但不承诺形状，禁令 2 完好），并继承全局 JWT 鉴权（e2e 断言未鉴权 401）。⇒「三层无 controller」这条纪律改为「只读端点 + 排除契约，且无任何写端点」（录入仍走 npm run fulfillment:record）

  • MongoDB 升级为单节点副本集 + 写入原子性: DB 从 standalone 升级为单节点副本集 rs0（replication.replSetName: rs0 + security.keyFile —— authorization: enabled 时副本集强制要求 keyFile，漏了它 mongod 起不来：BadValue: security.keyFile is required when authorization is enabled with replica sets；该步骤已补进 mongo-replset-upgrade-runbook.md §3.2.1）。代码侧随之完成写入原子性：StateService.write() 在无外部 session 时自动开事务，把 ① seq $inc ② 事件 insert ③ 物化 upsert 打成三步原子（此前 ②成功③失败 ⇒「事件在、物化不在」，verify() 会判不一致）；订阅派发移到 commit 之后（外部副作用不能回滚），派发结果仍回传到 triggered，语义不变。write() 另接受 session + onCommitted ⇒ 调用方已开事务时可与自己的 Mongo 写入同一事务（跨层原子能力就位；L1/L2 因当前零生产调用方暂未启用）。顺带修了脚本误判：未初始化的副本集不返回 setName，只看它会误判成 standalone 而拒绝 initiate

  • Agent 自助激活端点: POST /api/agent-profiles/activate-by-key——外部 Agent 用注册时返回的 api_key 将 profile 从 draft 激活为 active，进入派单匹配池（此前注册后为 draft，需平台登录态激活，自助流程无法闭环）

  • 供应商离线续传: 外部 Agent 离线时任务落 offline_tasks 排队、节点挂起等待，Agent 上线后自动补推并续跑——不再由内部 LLM 静默代跑（保住供应商数据/授权边界）

  • 演示供应商 Agent: scripts/demo-supplier-agent.ts——Gateway socket 接单 + AUTH_REQUIRED 本地人工授权闭环演示

  • Workbench 待授权详情: 展示授权请求说明与数据范围（requestedScope）

  • 任务页 awaiting_auth/awaiting_input 状态处理: 顶部提示横幅 + 持续轮询，授权等待期间不再"静默挂起"

🔧 修复 ​

  • skill 注册契约: skills/agent-self-registration.json 注册 URL 由不存在的 /api/agent-profile/register（单数）修正为 /api/agent-profiles/register（复数），并新增第 2.2 步自助激活指引
  • a2a-server-reference.ts: 注册端点由不存在的 /api/agent-profiles/upsert 修正为 /api/agent-profiles/register，注册成功后自动调用激活端点
  • /api/task/agent 路由遮蔽: @Get('agent') 声明位置调整到 @Get(':id') 之前，修复外部 Agent 查询自身任务返回 401 的问题
  • 重复派单: 删除 chat-execute / demand-translation 提交时的直接推送，工作流执行器成为唯一派发点（同一任务曾被派两次）
  • 计费幂等: settleTaskFee 增加 feeSettled 原子 claim，修复重复回传/多实例并发导致的重复计费
  • 在线 Agent 回传丢失: POST /gateway/tasks/:id/result 改 upsert——在线 Agent（无 OfflineTask 记录）回传的 AUTH_REQUIRED 状态与计费不再静默丢失
  • 推送输入泄漏: 派单只推 node.config.input，不再把 agentProfileId/a2aEndpoint 等节点内部配置暴露给外部 Agent
  • Chat 页消息闪现后消失: 自动发送的延迟回调增加就绪状态二次校验，修复与历史加载的竞态

🔒 安全（2026-08-18 审计修复） ​

  • 重注册劫持（P0）: POST /api/agent-profiles/register 对已存在的 agentId+subDomain 要求携带原 X-Api-Key 证明所有权，否则 403；此前任何人可重注册他人 Agent 并轮换 key、改写 callbackUrl 导致任务数据外泄
  • Gateway 端点鉴权（P0）: GET /gateway/tasks、POST /gateway/tasks/:id/result、POST /gateway/tasks/:id/review 由无鉴权改为 @Public() + @UseGuards(ApiKeyGuard) 组合（跳过 JWT、强制 API Key），并绑定认证身份——只能操作本 Agent 名下任务；ApiKeyGuard 不再响应 @Public 跳过（该组合此前形同虚设，skills/submit 的 Phase 3 遗留随之解决）
  • 超时交付不计费（P1）: 任务 expired 后的迟到结果只记录不结算、不推 webhook、不触发执行器；超时判定覆盖 pending/delivered/claimed 状态
  • 交付物质量门禁（P1）: 完成/草稿回传必须通过 skill output_schema 的 JSON Schema 校验（ajv），不合规返回 400 且不计费
  • 任务认领语义（P1）: 新增 POST /gateway/tasks/:id/claim 原子认领（pending/delivered → claimed），供应商多实例不再重复执行；agent-self-registration.json 契约升级 v1.4 同步上述变更

🧩 可靠性与协议补齐（2026-08-18 第二批） ​

  • 断点续跑: resumeExecution 从空实现变为真实恢复——重入工作流并跳过 completedNodes，失败/中断的执行可通过 POST /task/:id/resume 续跑
  • A2A 中断状态落地: Agent 在 A2A 任务中进入 AUTH_REQUIRED/INPUT_REQUIRED 时，平台落库 auth_required/input_required 并同步 Task 为 awaiting_auth/awaiting_input（workbench/任务页可见），轮询继续直至 Agent 人工确认后推进完成；轮询上限对齐 Agent SLA
  • A2A 出站鉴权: 平台调用 Agent 的 A2A 端点（SendMessage/GetTask）携带该 Agent 的平台签发 X-Api-Key，Agent 侧可验证调用方身份
  • Socket 回传状态机: agent:result 识别 state 字段——AUTH_REQUIRED/INPUT_REQUIRED 正确挂起（此前被误标完成并结算），FAILED 正确标失败并唤醒执行器报错

🌐 标准 A2A 协议接入（2026-08-19，Phase 9 任务 1） ​

  • A2A 注册契约: POST /api/agent-profiles/register 正式接收独立 a2aEndpoint 字段并落库 AgentProfile.a2aEndpoint（此前靠 gatewayUrl 复用）；执行器/匹配/AgentCard 优先消费该字段，旧 dialogue.endpoint.url 保留兼容回退；agent-self-registration.json 契约同步
  • 标准 A2A 客户端: A2AClientService 支持标准 Google A2A 协议——agent-card 发现（GET /.well-known/agent-card.json，按 origin 缓存）+ JSON-RPC 2.0（message/send/tasks/get/tasks/cancel）；executeTask 自动协商：有 card 走标准协议，无 card 或标准调用失败回退 legacy 方言（旧 Agent 无需改造）；标准 Task 状态（auth-required/input-required）沿用平台中断落库逻辑
  • 标准参考实现: scripts/a2a-standard-server.ts——标准 A2A Server（agent-card + JSON-RPC + 中断态模拟）；scripts/verify-a2a-standard.ts 互通验证（发现/正常执行/auth-required 续跑/legacy 回退 4 项）
  • 通用标准 A2A 适配器: scripts/a2a-adapter.js——对平台暴露标准 A2A Server（agent-card + JSON-RPC），对内翻译为本地运行时的一次命令调用（AGENT_EXEC_CMD 模板， 独立 argv 传递，EXEC_OUTPUT_JSON_PATH 支持负索引取最终输出）；OpenClaw / Hermes 已实测接入，其他运行时（Claude Code / WorkBuddy）换一行命令即可
  • OpenClaw 标准 A2A 真实履约: 注册（a2aEndpoint）→ 匹配 → 标准 A2A 派单 → DeepSeek 真实执行 → 交付 → 按次结算全链路实测通过（cron 拉取模式随之退役，旧拉取型 profile 已停用）
  • 适配器零依赖单文件化: scripts/a2a-adapter.js 改为纯 Node.js 内置模块实现（无 npm 依赖，Node >= 16 直接 node a2a-adapter.js 运行），平台新增 GET /api/a2a/adapter.js 下载端点——独立服务器上的 Agent client 无需 clone 平台仓库，curl -O 即可获取接入层；agent-self-registration.json v1.6 写入完整独立服务器接入流程（下载 → 注册 → 启动 → 激活）
  • NAT 场景接入指引: agent-self-registration.json v1.7 新增 Gateway socket 章节——个人电脑/NAT 后的 Agent 主动出站连平台（socket.io /agent namespace：agent:register/agent:task/agent:ack/agent:result/agent:heartbeat 完整协议），平台即中转站、Agent 零端口暴露；接入形态定调双轨并行：可直连用标准 A2A 推模式，NAT 后用 Gateway socket
  • 适配器执行质量加固: 新增 / 占位符与 AGENT_INPUT_TEMPLATE 输入包装模板——修复 OpenClaw 所有任务共享 main session 导致上下文溢出（输出退化"找问题"）与裸 JSON 输入行为不确定的问题；每任务独立 session + 明确技能指令后，42 秒产出符合 output_schema 的完整结构化报告（v1.7.1 契约同步）

🧱 A2A 链路硬化（2026-08-19 下午，针对实测暴露的脆点） ​

  • 轮询 fail fast: pollUntilTerminal 区分错误语义——Agent 端"task not found"（确定性失败，如适配器重启清库）立即抛错让平台重新派单，不再空等 15 分钟 SLA 上限；网络抖动等瞬态错误维持重试
  • 适配器任务落盘: a2a-adapter.js 任务状态持久化到 JSON 文件（A2A_STORE_PATH）——重启后已完成结果仍可被平台轮询到（消除"幽灵任务"），在途任务标记 failed 请平台重派，终端任务保留 24h
  • 通道纪律: 显式声明 a2aEndpoint 的 Agent 判定为纯 A2A 通道——A2A 调用失败不再降级 Gateway/socket（适配器类 Agent 没有 socket 连接，降级只会把任务推进永远等不到接单的虚空队列），直接失败快速暴露错误
  • 路由防腐: 三个旧拉取型 profile（openclaw-supplier-01、demo-supplier-agent、demo-vat-agent）由 suspended 改 retired（状态机无回活路径，register upsert 不再复活同名 profile）——此前它们被 demo 脚本反复自动激活并抢走 CE 匹配
  • 适配器 PM2 托管: a2a-openclaw 纳入 PM2（崩溃自动重启），消除裸进程手动 kill 造成的端口僵尸
  • 同一 Agent 多技能支持: 修复 DAG 构建按 agentId 去重导致同 Agent 多技能节点被吞（CE+VAT 只建 CE 节点）——去重键与 nodeId 改为 agentId+技能；offline_tasks 唯一索引与结算复合键升级为 (taskId, agentId, skillId)（原 (taskId, agentId) 索引使同 Agent 第二份交付 E11000 落库失败、漏结算）；recordA2ADelivery/settleTaskFee 同步按 skillId 寻址
  • Chat 页执行体验修复: ①确认执行按钮点击后不消失——按钮显隐依赖 pending 卡片而前端未在点击时更新卡片状态，改为点击即乐观标记 executing（后续由 socket 驱动）；②DAG/Agent 卡片只剩一条——前端卡片以 agentId 为键，同一 Agent 多技能节点互相覆盖，后端 agentStatusChanged 广播与 chatPrepare 响应补充 nodeId，前端卡片改以 nodeId 为键
  • OpenClaw 执行提速 5~6 倍: 慢根因定位——main session 已膨胀至 ~62k tokens，每个任务轮次都全量重读历史（实测 cacheRead 62,464 tokens 只为 2 字回答）；且 --session-id 隔离在该版本不生效。修复：创建专用 hushwork agent（空 session，context ~20k）+ 提示词限制输出长度（1500 字聚焦结论），CE/VAT 节点从 81~111s 降至 18.5s
  • directPrompt 空输出排雷: deepseek-v4-flash 是推理模型，reasoning_content（思考链）与正文共享 max_tokens 预算——4096 会被思考链烧完导致正文静默为空（实测复现），max_tokens 提升至 16000
  • 自动 prepare 误传命令字面量: 前端自动触发 DAG 分析时把 'execute' 当需求文本翻译（LLM 出 0 任务、关键词兜底只剩 CE），改为传真实消息文本；后端 chatPrepare 对 'execute' 字面量兜底——无历史可用时不再把命令词当需求翻译
  • DAG 出现时机改为内容驱动: prepareSse 的 readyToExecute 判定由「固定 ≥4 条消息」改为「最近对话 + 当前消息做需求翻译，存在置信度 ≥0.6 的任务即就绪」——第一条消息只要需求明确就出现 DAG，需求不清的寒暄不出；每条消息重新评估，DAG 随对话演进自动更新（前端逐条 prepare 替换分析卡片）。涉及模块循环（Dialog→DemandTranslation→Task→Dialog）以两侧 forwardRef 解开
  • 接入模式文档化: site/guide/agent-registration.md（Agent 入驻指南——接入形态选择、执行模式规范「任务=零历史 subagent + 专用 skill」、适配器全流程、运维建议）；agent-self-registration.json v1.8 同步生产模式配置（专用隔离 agent、skills/ 挂载、AGENT_SESSION_RESET_DIR）
  • 任务=零历史 subagent: 适配器新增 AGENT_SESSION_RESET_DIR——无在途任务时新任务开始前清空 Agent 运行时 session，每个任务在零上下文环境执行（不依赖对话历史，不会随任务量膨胀变慢；有并发在途任务时自动跳过清理）；平台 skill 定义文件（ce-certification.json、vat.json 等）挂载到 hushwork agent 工作区 skills/，Agent 按技能文件的 output_schema 产出——任务执行只依赖专用 skill

🔧 修复（2026-08-19，Phase 9 过程中发现） ​

  • 平台内部 Agent 误推 Gateway: TaskExecutionService 执行 POST /demands 生成的 DAG 时，把 domain=platform 的内部 Agent（demand-translation 等）当外部 Agent 推 Gateway → offline 超时；已补本地执行分支（_translationOutput 缓存直接回放，否则 directPrompt），与 InternalAgentNodeExecutor 行为对齐
  • 纯 A2A 履约不结算: settleTaskFee 此前只在 Gateway socket/HTTP 回传路径触发，A2A 直推路径完成不计费不推 webhook；新增 AgentGatewayService.recordA2ADelivery（upsert offline_task + 幂等结算 + webhook），执行器在 A2A 履约成功后调用

⚡ 成本治理（2026-10-13，Phase 10.2.1 / PR-1） ​

  • 决策链路反转优先序: demand-translation 的拆解由「先 deepseek-chat → 失败回退关键词」反转为「关键词规则优先 → 未命中才过模型」——常见合规 query（CE/HS Code/VAT/GDPR/FDA/清关/侵权）命中规则即返回，不再产生 LLM token；LLM 仅在规则未命中时调用，失败或返回不可用结果时仍回退关键词，translate() 保持「永不返回零任务」
  • 过模型率可度量: translate() 返回值新增 decompositionRoute（rule / llm / rule_fallback）；新增 DemandTranslationService.getDecompositionStats() 读出 { total, rule, llm, ruleFallback, modelRate }；每次拆解输出一行可聚合日志 [decompose] route=… modelRate=…（内存计数重启归零，跨期指标走日志聚合）
  • 规则命中置信度重新标定: 关键词路径此前恒为 0.55，低于 dialog.service.ts 的「可执行」闸门 confidence >= 0.6——规则成为主路径后会导致典型 query 永远无法进入可执行态；现按证据强度给分（0.55 + 目标市场 0.10 + 产品类别 0.05，上限 0.8）

🔍 发现层可比价（2026-10-13，Phase 10.5 / PR-2） ​

  • A2A Agent Card 补齐 4 个字段: A2ASkill 新增 pricing / sla / availability / trust（均为可选、平台扩展字段，A2A 标准字段一个未动）——「可比价、可信任排序」的前提；GET /api/a2a/agent-card/:agentId 返回的每个 skill 都带这 4 个字段，A2AAgentCardConverter.platformSkillExtensions() 从已有 AgentProfile 映射（未改 schema，数据源本就存在）
  • 可接单判据: availability.accepting 只看生命周期状态 status === 'active'——connectionStatus 是 WebSocket 连接状态，纯 A2A 直连的 Agent 没有 socket 连接也会是 offline，不能用来判断能否接单
  • 能力目录不带这 4 个字段: GET /api/a2a/skills（平台能力目录，不绑定具体 Agent）保持原样——价格/SLA/信任描述的是「某个 Agent 提供该技能的条件」，只出现在 AgentCard 的 skills 里

🧪 测试基建（2026-10-13） ​

  • E2E 与生产共用同一份装配: 新增 apps/hushwork/src/configure-app.ts（异常过滤器 + 路由前缀 + 校验管道），main.ts 与全部 e2e spec 共用——此前 e2e 各自复制装配且漏掉 setGlobalPrefix('api')，导致测试里所有 /api/... 请求 404、真实生产路由从未被 e2e 覆盖（两套 spec 还分别使用有/无前缀路径，互不相容）
  • e2e 路径统一到 /api: test-client.ts（登录 /api/mlogin）、mvp-integration、flow-b-task-workbench 共 80+ 处请求路径迁移到真实前缀。mvp-integration 由 9 failed → 3 failed（47 passed）
  • 冒烟测试替换脚手架残留: app.e2e-spec.ts 原期望 GET / 返回 "Hello World!"（本仓库无该 controller，从来不可能通过）→ 改为对真实公开端点 GET /api/a2a/agent-card 冒烟，并新增「无前缀路径应 404」断言锁住路由前缀生效
  • e2e 跑完即退出: jest-e2e.json 加 forceExit——测试完成后进程因未释放句柄（与 npm run docs:api 的 app.close() 挂死同源）永不退出，使质量门永远不返回

🐛 修复（2026-10-13，e2e 修复后暴露） ​

  • GET /api/demands/:id 稳定 500: 对外需求标识 demandId 是 uuid，而文档主键 _id 是 Mongo ObjectId —— 查询端点直接用 findById(uuid)，Mongoose 抛 CastError 变成 500，该端点从来没有成功返回过。修复：TranslatedDemand 落库 demandId 字段（带索引），findById() 改为先按 demandId 检索、再回退 _id（兼容直接用 _id 的调用方与历史数据）。对外契约不变（仍返回 uuid）
  • POST /api/task/:id/summary、/summary/regenerate、/workflows/recommend 稳定 500: 3 处 findOne({ where: { id }, relations: ['dialog'] }) 引用了 Task 实体上不存在的关联（关联是弱引用 dialogId）→ TypeORM 抛错。同 service 内不使用 relations 的用例全部正常，是明确对照。已删除这 3 处（无代码访问 task.dialog）；mvp-integration 因此从 9 failed 变为全绿

🗄️ 架构债清偿（2026-10-13，Phase 10.1 / PR-4a） ​

  • Task 双读兼容（迁移第一段）: 新增 Task 的 MongoDB 形态（task/schemas/task.schema.ts，字段与 TypeORM 实体一一对应，并内嵌 agentDeliveries[]——原 OfflineTask 语义，为后续同库化铺路）与存储门面 TaskStoreService：读先 MySQL、未命中回退 MongoDB；写仍只走 MySQL（与迁移前行为完全一致，切写是 4b）
  • 9 处注入 / 39 处调用收敛到门面: 门面方法签名与 TypeORM Repository<Task> 兼容，调用点只改注入、参数与返回形状不变；TaskStoreModule 独立成模块，避免 TaskModule ⇄ AgentGatewayModule 新增循环依赖（无需 forwardRef）；顺带移除 chat-execute.module.ts 里第 3 个重复的 TypeOrmModule.forFeature([Task])
  • 不猜查询语义: 只翻译简单等值 where（含 order/skip/take），遇 FindOperator（In 等）只读 MySQL 并告警——宁可读不到，也不构造语义可能不同的 Mongo 查询造成静默数据错误；原 task-query 的 QueryBuilder id IN (...) 由门面 findByIds() 承接
  • Task 写路径切到 MongoDB（PR-4b）: 写操作以 Mongo 为主源、MySQL 降级为旧单只读兜底；列表查询合并两库、按 id 去重（Mongo 版本优先）后统一排序分页——否则过渡期用户会看不到部署前创建的任务（看似数据丢失）；更新只存在于 MySQL 的旧单时先懒迁移完整文档，避免丢更新或写出残缺文档
  • 发现并处理计划未预见的 FK 约束: task_execution / task_summary_history / task_workflow_recommendation 在 MySQL 对 task(id) 有真实外键——只写 Mongo 会让 MySQL 缺行，插入子表直接 500（e2e 实测暴露）。以过渡期镜像写（Mongo 仍是唯一读源）解决，并标注解除 FK 属 4c
  • e2e 失败可见性: TestClient.expectSuccess 在非成功响应时打印响应体——AllExceptionsFilter 把异常串放在 msg 里，此前只能看到裸状态码

🛡️ 准入与资质（2026-10-13，Phase 10.4 / PR-8） ​

  • 准入硬过滤: AgentProfile 新增资质凭证 credentials[]（code / issuer / issuedAt / expiresAt / scope），SkillDefinition 新增 required_credentials；AgentMatcherService 在打分之前排除不满足者——须持有全部所需资质且未过期（证书过期自动下线）。不满足即排除、不回退：资质是担保的前提，不能靠「打分低」兜底
  • 向后兼容: 现有 Skill 均未声明资质 → 不过滤，匹配行为不变（e2e 逐项一致）。声明资质会立即改变生产匹配结果，属商务动作（选定垂直后逐条声明）

🤝 Phase 11 交接（2026-10-14） ​

  • 新增 docs/workplan/phase11-handoff.md: 新 session 的唯一开工入口 —— 含必读清单、当前基线（c3455aa）、已决事项（不再重新推导）、W1 的六项内容与可证伪验收信号、硬约束、已核实的环境与代码事实、未决项、7 条已踩过的坑、开工检查清单
  • 旧交接文档已标过期: phase10-handoff.md 顶部加 🔴 指针改读 Phase 11（避免新 session 按 Phase 10 排期开工）；swarm-infrastructure-plan.md 亦加开工入口链接
  • 交接中特别强调的环境事实（本会话踩坑所得）: .env 是 production 配置且指向生产库；生产就跑在本机 PM2（CLI 不在 PATH）；e2e 直连生产库；npm run build 会覆盖生产 dist

🧭 排期修订：蜂群基础设施优先（2026-10-14） ​

  • 新增 docs/agent-architecture/swarm-infrastructure-plan.md: 依据产品负责人判断 —— 「蜂群 / 世界状态」是基础设施（L0），信任层（L1）建在其上。规划把 10.6（协调层）从 🟢 P3 提为 🔴 P0 主线，10.3（履约/担保）改为「建在 L0 之上」
  • 核心论证（而非立场）: 信任的本质是验证成本 —— 传统信任层靠人工取证/仲裁，边际成本不下降；有世界状态后，验证 = 一次状态查询（证据即状态本身、责任方 = 写入变更的 actor）→ 边际趋零。因此 L0 不是"优化项"，而是成本优势的唯一来源。另一条独立论证：Visa/PayPal/支付宝这类支付托管工具全部依附于已存在的交易密集场所（PayPal←eBay、支付宝←淘宝），Hushwork 既无可嵌入场所也无议价能力 ⇒「做工具」逻辑上不成立，必须自建交易场所（淘宝的位置，不是 Visa 的位置）
  • 已具备的前提: PR-4c 把 Task 收敛为 MongoDB 单库 + 文档模型，恰好是 L0 的存储前提 —— 上一阶段那段痛苦的迁移正好铺好了地基
  • 诚实写入的边界: L0 让过程性信任趋零成本，不改变"质量性信任"仍贵（"报告够不够专业"无法由状态证明）→ 明确落到 fulfillment-spec.md §6 待定项 7
  • 代价: 短期无收入（主动放弃"先收钱"）；假设「机器协作能产生交易密度」尚未验证；文件内逐条列出 5 项待验证假设与证伪方式
  • phase10-plan.md 顶部已加指针，避免后来者按旧排期执行

📦 履约模块骨架（2026-10-14，Phase 10.3 / PR-5 骨架） ​

  • 只做"不会因样本返工"的部分: libs/modules/src/fulfillment/ 落地 Delivery / Acceptance / Dispute / Resolution 四 schema 与状态机 service。严格限定在 spec §1 禁令 4 允许的范畴：状态机合法性表、三条不变量（一次交付只能验收一次 / timeline[] 只追加 / 先定责再关闭）、乐观并发（状态迁移用条件更新，并发双迁移抛 409）、getTrace(taskId) 一单完整追溯
  • 🟡 字段一律只作占位: deliverables[] / objections[] / grounds / basis[] / ruling 等待真实样本校准的字段用宽松类型承载、不建索引（禁令 1），grounds 与 ruling 刻意用 string 而非 enum（枚举定错，历史数据全要迁移）
  • 刻意不做: 无 controller、不进 contracts/swagger.json（禁令 2）、无迁移脚本（禁令 3）、不含赔付金额规则（属法务/商务，技术只记录）
  • 验证: 单测 11/11（重复验收 / 乱序处置 / 终态再迁移 / timeline 只追加 / 并发冲突 均被拒绝）· build 通过 · 4 个 e2e suite 仍 101 passed / 0 failed
  • ⚠️ 完整 PR-5 的前置仍是「一单真实交付」（spec §11）；本骨架不改变这一点

📘 运维文档（2026-10-14） ​

  • 新增上线/回滚 runbook: docs/ops/task-mongo-migration-runbook.md —— Task 迁 MongoDB 的备份 → 迁移 → 部署 → 校验 → 回滚步骤。开篇如实记录了此前对生产库实际执行过的两次不可逆操作（synchronize 删除了 3 个外键、已写入 299 条 Mongo 文档）以及当时没有备份这一事实，避免后来者误判当前生产状态

🗄️ Task 迁移收尾：MongoDB 单库（2026-10-13，Phase 10.1 / PR-4c 收尾） ​

  • 读兜底彻底移除: TaskStoreService 现在只有 Mongo 一条路径 —— 跨库合并、按 id 去重、应用层排序分页、旧单懒迁移、delete 双删全部删除（304 行 → 约 190 行）；TaskStoreModule 也不再 forFeature([Task])。保留 TypeORM 风格签名（where/order/skip/take），8 个调用点无需改动
  • 无法翻译的 where 改为抛错: 原来"遇 FindOperator 就退回 MySQL"；读兜底没了以后再猜语义会变成静默错读，因此改成显式失败（批量按 id 用 findByIds()）
  • 验证: 单测 15/15 · npm run build 通过 · 4 个 e2e suite 在真实数据（生产库 299 条已迁移）上仍 101 passed / 0 failed —— 证明不存在"只在 MySQL"而被漏读的任务
  • ⚠️ 部署前提: 这一版读不到 MySQL。必须先 npm run migrate:tasks 且校验通过再部署（顺序：备份 → 迁移 → 部署 → 再迁移一次补齐窗口期）

🗄️ Task 迁 MongoDB：解 FK + 真实单写（2026-10-13，Phase 10.1 / PR-4c） ​

  • 解除 3 处真实外键，切写 Mongo 才成立: task_execution / task_summary_history / task_workflow_recommendation 原本对 task(id) 有真实 FK，导致「只写 Mongo」时插入子表直接失败（PR-4b 曾因此 500）。子实体去掉 @ManyToOne 声明后（taskId 列本就独立存在，只删关系不动列），synchronize: true 在启动时自动 DROP FOREIGN KEY —— 实测 information_schema 已无引用 task 的外键，无需停机窗口、无需人工 DDL，推翻了原计划「4c 需要窗口」的判断
  • 删除过渡期镜像写: 写操作现在真的只写 Mongo。读兜底与 delete 双删保留至迁移校验通过
  • 迁移脚本: npm run migrate:tasks（支持 --dry-run）—— 幂等、绝不覆盖 Mongo 已有文档（Mongo 是 4b 之后的最新写源）、结束时校验「MySQL 每条 task 都能在 Mongo 找到」。部署顺序：先跑脚本 → 再部署新代码
  • 不可逆点: FK 已删。若回滚代码，synchronize 会尝试重建 FK，而子表存在指向不存在 task 的孤儿行时重建会失败 —— 回滚前需先清理孤儿行

🐛 缺陷修复（2026-10-13） ​

  • recommend / generate 的前置条件不再伪装成 500: 任务不存在 → 404、需求摘要未就绪 → 409。原来两者合并成一句裸 Error，被全局 filter 映射成 500 —— 把「客户端状态不满足」报成「服务器故障」，误导排查、误触发告警
  • e2e 首次全绿: flow-b 的 recommend 用例改为验证状态机守卫（摘要抽取依赖 AI，e2e 环境不产出摘要），4 个 suite 101 passed / 0 failed / 1 skipped。⚠️ 同时发现 mvp-integration 的同名用例用硬编码 task ID、依赖开发库里的旧任务，其「通过」是假阳性 —— 已记录，未改

🧰 工程效能（2026-10-13） ​

  • npm run lint 恢复可用: ESLint 9 不再默认读取 .eslintrc.js，此前 npm run lint 完全跑不起来。现由脚本显式启用 legacy 配置，并去掉 --fix（有 prettier 规则时 --fix 会重写整个文件）。为此把 prettier/prettier 与 6 条遗留债规则降为 warn：HEAD 上有 325 文件 / 1304 处 error（no-unused-vars 968、prefer-const 253…），一次清完风险过高——lint 因此从"恒失败"变为 exit 0 的可用门，债务仍以 warning 可见
  • npm run docs:api 恢复可用: export-swagger.ts 写完 contracts/swagger.json 后卡在 app.close()（未释放句柄），导致后半段 generate-api-docs.ts 永不执行、契约同步只能手工。现打印残留句柄诊断后显式退出，脚本跑完 55 模块 / 448 端点
  • 已知遗留: app.close() 不返回的根因未根治（e2e 用 forceExit、脚本用显式退出兜底），属优雅关闭的独立问题；重跑 docs:api 会产生语义等价的重排 diff（swagger 键顺序）与文档生成日期 churn，故本次未提交生成物

✨ 新增 ​

  • Skill Catalog: 5 个合规 Skill 定义（CE 认证、FDA 标签、HS Code、清关文档、IP 侵权）
  • Agent Gateway: WebSocket 实时通信，Agent 主动连接平台领任务
  • Demand Translation 引擎: 需求语义解析 + 分类匹配 + 依赖推导
  • Agent 匹配引擎: 基于 subDomain 精确匹配
  • Verification 验证管线: Schema 校验 + 断言规则
  • Reporter 报告生成: 多 Agent 输出汇总 → 结构化报告

🔧 模块 ​

  • task/ — 任务管理（核心）
  • workflow/ — DAG 工作流引擎（核心）
  • agent/ — Agent 管理、模板、Skill Catalog
  • agent-gateway/ — WebSocket Agent 网关
  • agent-matching/ — Agent 匹配引擎
  • agent-profile/ — Agent 注册与发现
  • demand-translation/ — 需求翻译引擎
  • verification/ — 验证管线
  • reporter/ — 报告生成
  • dialog/ — SSE 对话

📚 文档 ​

  • 启动 Agent-Based Development Framework
  • 5 层开发工作流：Plan → Execute → Review → Commit → Iterate
  • API Spec 模板、模块 Spec 模板、Agent Skill 模板

版本规范 ​

版本号变更含义
x.Y.z → x.(Y+1).0新增功能（向后兼容）
x.y.Z → x.y.(Z+1)Bug 修复（向后兼容）
X.y.z → (X+1).0.0破坏性变更（不兼容）

此文件通过 scripts/generate-changelog.js 从 commit 历史自动生成基础内容，人工补充说明后提交。

Released under the MIT License.

Copyright © 2026 Hushwork