← 返回周目标完成情况

目标一阶段 1:范围与接口确认

本会话后续范围调整:用户建议、代理评估采纳:模型预审本期不做,3.4b留后续;确定性格式/附件/权限校验和用户验收保留。正文已移除本期模型预审字段、状态及展示要求;旧原型中的预审仅留为历史演示,不构成本期实现依据。常规开发测试使用假模型、fake A2A及假CS,不新增真实模型调用或ndclaw实例启动;任务5才执行明确范围的真实联调。当前范围以目标一任务清单D3及第八节为准。

日期:2026-10-12。状态:任务 1 评审稿,1012 晚会后正文修订;任务 1 尚未整体确认。本稿形成范围、最小持久化、状态与契约草案;任务 2 最小真实接入已经完成。本会话未新发真实专家请求。除标「已定」「代码事实」外,本文均为实施提案。本期交互以 master ba865ab82d1168cb7e409a608da8344a11b70a6f 的连贯原型为基准,未覆盖的异常与下游入口仍待补齐,不另做一套工作间。

依据:协作技术方案、ndclaw 对接报告、开发基线。验收草案、外部核查证据及阶段 2 进入条件在配套交接稿。

任务状态更新(2026-10-12):用户确认任务 2 最小真实接入已完成,任务 1 尚未完成。本稿对应任务 1.1 的设计草案;实测契约回填和决定项确认分别归入 1.2、1.3。当前状态与进入条件以目标一开发任务清单为准。下文代码/外部状态是本稿初次核查时的事实,不代表任务 2 完成后的现状;实际差异待 1.2 回填,不能据本次任务登记自动批准实现。

1012 晚会正文已对齐:本期只做用户直接与专家交互;代答、模式切换、五轮自动续答移下一期,不建对应字段/接口。本会话采纳用户建议,模型预审本期不做;用户验收及事实回收独立保留。工作间已补入 master,卡片、团团指路和“等你”入口统一进入同一执行。逐章映射、会议原文行号及尚缺的交互见晚会与原型对照。该表为任务 1.4 对照稿,不代替 D1~D6 裁定。

1. 范围和实施边界

已定方向:团团负责能力匹配和项目推进,外部专家执行专业任务;首个平台 ndclaw;本期用户直接交互,团团代答留下一期;花钱、对外发布、改目标或验收标准、换人、结项由用户确认。平台不代用户对外发帖、不在团团进程执行外部代码。

目标一后续实现的最小闭环:已确认任务计划 → 依据能力筛候选 → 选择并派单 → 同任务多轮协作 → 回收文本和文件 → 用户验收 → 上游结果进入下游任务书。组织身份、权限、幂等、未知发送结果、取消和失败去处属于这个闭环。

本轮产出只有设计与场景草案。不建表、不改 OpenAPI、不导入专家、不复制配置、不运行真实模型、不向专家发送消息或创建实例、不改原型目录、不修 PR #13 的历史门禁问题、不提交或推送。后续仍以 feature/tuantuan-agent-execution 交付到 develop;本树 HEAD=2d428d190a601b1e5f69ba00d760b7caf7c73438,临时依赖 PR #13,不能把它视为已合并。

不包含:其他执行平台、付费交易与结算、后台无人值守委派、项目事实变更的自动传播、同任务并行多个执行方、完整任务图增删改运营层、直播全场景包的全量实现。本周在新 UI 跑通一个案例,具体案例和终点由 D6 固定;直播定位→主题策划仅是草案样例,九专家属于目标二原方案,不据此自动承诺本周上齐,也不能把少数专家通过报为九个完成。原型的小红书剧本不要求本周做小红书专属实现。能力标签与输入/输出 schema 使用最小模板配置,不以搭建通用插件框架为前提。

2. 已有能力与缺口:以固定提交代码为准

已有代码 本轮核对事实 后续用法
apps/api/app/tuantuan/models.py 的 Project / ProjectRun assistant_projects 保存摘要、对话、tasks JSONB;assistant_runs 只管 message/start 保留计划存储,不拆迁全量任务表;沿用项目所有者、版本和短事务模式
apps/api/app/tuantuan/schemas.py 的 ProjectTask 任务已有 UUID、描述、交付要求、验收标准、依赖和顺序;没有能力标签、执行状态或执行方 为新计划加可选模板标识/能力要求;旧任务不可凭标题猜专家
apps/api/app/tuantuan/states.py、router.py 项目仅 clarifying/ready/planned;planned 后不能继续既有澄清请求;/me/projects/{id}/start 明确不指派不执行 不把原开工接口变成派单;专家消息用新执行接口;不宣称已有团团运营工具
apps/api/app/identity/dependencies.py CurrentUser 有 uc_subject,无组织类型;Fake 身份最终也存 uc_issuer='uc' 组织资格须来自可信证据,不能按 issuer、账号格式或管理员角色推断
apps/api/app/identity/uc_profile.py 已有 BTS 令牌缓存、请求签名,但 UC 资料请求带 sdp-app-id 复用签名算法和缓存,隔离 ndclaw 的请求头;域间只通过公开服务接口
apps/api/app/files/service.py 有 CS 上传、签名下载;普通 attachment 的读取对登录用户开放 加私有执行附件用途和所有者校验;不能直接复用普通附件访问策略
apps/api/app/tasks/、deliveries/ 交易任务及依赖 claim 的交付链 不承载项目任务和免费专家结果;本闭环不生成交易记录
apps/web/src/features/projects/ 已有项目列表、摘要确认和只读计划;项目 SSE 类型是 text_delta/project/done/error 增量引入独立执行客户端和读模型,不改现有项目事件含义

代码定位:tuantuan/models.py:25、41、schemas.py:132、runs.py:129、151、states.py:6、router.py:88、service.py:37、95(以上在 apps/api/app/);identity/dependencies.py:3、28、files/service.py:459、identity/uc_profile.py:269(同前缀);前端 apps/web/src/features/projects/ProjectPage.tsx:157、ProjectTaskPlan.tsx:31。

上表描述本工作树固定起点,不是最新 develop 的完整能力。PR #14 已于 2026-10-12 合入 develop(fdd68e985da085bf036160c714a8f0cdac77358a),已有 apps/api/app/executors/ndclaw.py 的 NdclawClient 和冒烟脚本;本轮只读核对了合并记录与代码,没有同步分支或重跑真实请求。执行持久化、工作间应用、事实和交付解析仍需后续实现。真实接入证据层级见配套交接稿 §2。

3. 最小数据结构与迁移

3.1 保留计划,新增五张执行域表

本期不迁移 mode、auto_reply_count,不为下一期提前建模式切换 API;本期也不建模型预审字段、状态、调用或意见面板;确定性校验与用户验收足以串通当前闭环。所有 ID 用 UUID,时间用带时区时间;状态字符串配数据库 CHECK,关系配外键。以下字段是实施最低要求,不是已落库字段。

表/聚合 最小字段与约束 用途
executors id, provider='ndclaw', agent_ref, name, capabilities JSONB, enabled, channel_type, action_types JSONB, pricing_status, fixed_price nullable, revision, catalog_checked_at;唯一 (provider, agent_ref);仅接 mkt-;未知价格不得自动转成 0 ndclaw 目录只提供身份信息,能力、通道和价格由经确认的我方登记补齐;不对目录所有专家自动开放 (2026-10-13 林炜修订:本期目录同步入库即免费启用、能力取名片标签,目录消失即停用,见专家目录同步与通用模板)
executions id, project_id FK, task_id, executor_id FK nullable, actor_kind(agent/self), status, revision, context_id nullable, task_snapshot JSONB, executor_snapshot JSONB, brief_snapshot JSONB, result_revision, result JSONB nullable, acceptance JSONB nullable, failure JSONB nullable, rework_count, active_token, lease_until, created_at, updated_at 一条执行只属于一个项目任务、一个执行方;快照固定任务标准、能力、费用政策与上游事实版本;context_id 不跨执行共享
execution_turns id, execution_id FK, ordinal, operation, idempotency_key, request_hash, outbound_message_id, remote_task_id nullable, status, send_started_at, terminal_at, failure JSONB nullable, response_snapshot JSONB nullable;唯一 (execution_id, idempotency_key)、(execution_id, ordinal)、outbound_message_id 每轮独立记账;status=prepared/sending/remote_running/reconciling/completed/failed/cancelled;轮次完成不表示业务完成
execution_messages id, execution_id FK, turn_id FK nullable, seq, role(user/expert/system), text, file_ids JSONB, event_metadata JSONB nullable, created_at;唯一 (execution_id, seq),单轮最终专家回复只能入库一次 可恢复的完整对话与操作审计;增量帧不是最终交付;报告处理与验收也留 system 记录;本期不产生团团代答消息
project_facts id, project_id FK, source_execution_id FK, source_task_id, result_revision, key, value JSONB, version, accepted_by FK users, accepted_at;唯一 (source_execution_id, result_revision, key)、(project_id, source_task_id, key, version) 只存用户验收通过的结果;追加版本,不覆盖出处;下游任务书记录取了哪些 fact ID/version

对原四表提案的明确偏离:增加 execution_turns,因为 contextId 属执行而 taskId 属一轮;只在执行表存最后一个远端 ID 无法恢复历史发送和幂等。未采用把轮次日志塞进消息 JSON 的方案,避免让展示消息同时承担网络提交状态机。

executions.task_id 指向 JSONB 中的 ProjectTask.id,不是数据库外键。服务写入前锁项目行,验证任务属于该项目、项目为 planned 且未归档;任务计划本轮不支持删除/重写,后续实现任务图编辑必须加活动执行保护。数据库为 (project_id, task_id) 加「未 failed/cancelled」部分唯一索引,覆盖 completed:已完成任务不能再次派单;重做需要另案的显式任务版本。失败执行若仍持有未对账轮次或租约,不能新建执行。

同一执行最多一条活动轮次,数据库部分唯一索引覆盖 prepared/sending/remote_running/reconciling;事务领取后先提交再出网,不能持有数据库锁等待 600 秒。所有异步写回校验 fencing token 和期望版本;租约到期仅允许接管查回,不允许重发。

3.2 与现有表的最小衔接

3.3 迁移策略

在当时 Alembic 最新 head 上追加迁移;本树 head 为 0013_assistant_project_archive,同步 PR #13 后重新核对,不能预写死 0014。先建登记和执行、轮次、消息、事实的外键与索引,再扩文件用途。迁移不出网、不导入真实专家、不重写旧项目任务、不写凭据。降级先检查新表是否有业务数据,有则拒绝静默丢弃;空库可按依赖逆序删除。验证空库升级、含旧项目的升级、唯一约束并发、失败回滚和旧计划可读。

4. 状态机与失败恢复

4.1 业务执行与远端轮次分离

执行状态 进入条件 允许下一步
dispatching 派单中 短事务创建执行和首轮,持久化任务书 首个远端事件→running;无法确定发送结果→reconciling;确定拒绝→failed
running 进行中 专家一轮运行 经 GetTask 查明:普通回复→waiting_user;等待线下块→waiting_offline;上报块→reported;有效交付→awaiting_acceptance;远端确定失败→failed
waiting_user 等回复 没有交付;缺字段/块歧义亦在此,附格式问题 用户在工作间新消息→running;取消;本期不自动续答
waiting_offline 等线下 已验证等待线下块,记录动作要求 用户确认完成并补充结果→running;仅超时不冒充完成
reported 已上报 做不了、缺信息或上游矛盾 展示原因并由用户直接补信息→running;涉及五类事→用户决定;用户自行做/换专家先结束旧执行,本期团团不代答上报
awaiting_acceptance 待验收 文本、附件可用性及确定性检查结果已呈现 用户接受→completed;退回并带意见→running;取消;格式不完整不能进入此状态
reconciling 结果待查 网络中断、超时或旧 worker 失联,发送可能已成功 有 remote_task_id 时只 GetTask;查到终态按上述分流;没有 ID/查不到保留待查,不自动重发
cancel_requested 取消待确认 用户要求停止活动远端轮次 CancelTask 后 GetTask 确认;远端 canceled→cancelled,远端 failed→failed;远端 completed 时不自动续话,按正文解析为 waiting_user/waiting_offline/reported 或 awaiting_acceptance,显示取消未抢先生效;仅取消 RPC/查询失败或远端仍活动时保持待确认
failed 失败 远端明确失败或确定未发出的本地失败 仅当前最新执行可显式重试,创建新轮次并保留同一 context;已有替代执行则拒绝重试旧执行;换人需用户确认后新执行;不重用已失败的消息键
completed 已完成 用户接受当前 result_revision,事务写入事实 只读;不再接受发送、退回或取消
cancelled 已取消 确认未发送,或确认远端已终止 只读;用户明确重新派单才建新执行

适用于非终态的取消:无活动轮次时可直接本地 cancelled;已出网时进入 cancel_requested。交付回收与验收/取消并发通过 revision 和 token 判旧,旧回收回包不能复活执行。任何终态不能被迟到 SSE 覆盖。项目归档在存在非终态执行时拒绝,归档不是取消;读取历史仍可,所有新执行写操作拒绝归档项目。归档与派单均先锁项目行,避免检查后穿透。

原方案「任一状态→失败/已取消」和「超时进失败可重试」在此收紧:未知不是失败,取消请求不是取消成功。此为避免外部副作用重复的技术修订,需连同原方案差异评审。

原型的 offline 待办可与问答/返工并存,而本表 waiting_offline 表示整个执行暂停,两者不是已确认的一一映射。D4/D5 需确定是否允许边执行边等线下;若允许,另建执行中的待办字段与完成操作,不能用本表互斥状态丢掉仍可回答专家的能力。原型任务书动态取当前上游 delivery,也不能替代本稿的“已验事实+派单快照”规则。这两项属于已发现的业务交互差异,详见晚会与原型对照。

4.2 幂等、断线与直接交互

每个写接口要求 Idempotency-Key,同作用域同键同正文返回已有执行/轮次结果,不再外发;同键不同正文 422。统一复用 common/idempotency.py 与已有 idempotency_keys 表,按当前全用户键约束记录包含资源 ID 和操作名的 endpoint,请求 hash 包含正文与路径资源;小回执只存 execution_id、turn_id、操作接受版本,不存 SSE 全文。派单创建前、取消、查回、验收都使用该回执,轮次键再保障发送层唯一。在同一短事务中保存业务占位及回执后才出网,回执 completed 表示请求已接受,不表示远端完成;进程在出网前崩溃留下 prepared 轮次,租约到期后 reconcile 可用新 token 将其记为确定未发送的 failed(local_not_sent),再由用户显式 retry 开新轮;原 worker 必须原子领取 sending 并校验 token 后才可出网。sending 之后只能查回,不能据 send_started_at 的本地时间推断对方没收到。处理顺序为认证及资源归属→同键回放→新动作的归档/状态/版本校验;回放返回已有关联资源的当前快照,不再触发动作,避免旧版本重复请求被误判冲突。每次新动作校验项目/执行版本,过期 409。多个 worker 或标签页只能一方领取发送权;前端禁用按钮不能替代数据库约束。

首轮的 messageId 在出网前持久化。收到 contextId/taskId 第一时间提交;业务内容只从 GetTask.artifacts[].parts[].text 确认。续话保留 contextId,不带上轮 taskId。PR #14 已实现首轮不传 contextId、续话传同一 contextId;远端是否按 messageId 去重、是否支持调用方预建 contextId 仍无本轮证据;不声称 exactly-once。已发送但 ID 未落库时永久保留未知证据,需人工查远端或在知晓重复风险后另行处理,常规「重试」不可绕过。

与 1009 方案一致,首版一轮转发由当前请求驱动,SSE 很快先返回持久化后的执行快照,再等外部回复;不是后台队列。本期没有代答循环;页面离开后已外发的轮次可能继续在远端运行;回来先读快照,再显式 reconcile。服务重启时同样查回。GET 快照不会偷偷启动模型或发送消息。

用户在活动轮次中发消息得到 409 并保留输入,不能静默丢弃或并发发送。快捷回复仅生成普通用户消息,经同样的幂等和版本校验;不假定 A2A 会提供结构化选项,可用经审定模板给候选文案,无法可靠识别问题时始终保留自由输入。本期不调用 assist_execution 自动回答专家,上报问题也交给用户。下一期如恢复代答,要按“外层跟团团沟通、工作间看过程”的晚会方向重新设计,不能直接启用旧切换按钮。

5. 前后端接口与 ndclaw 边界

5.1 我方 HTTP 契约草案

路径沿用现有 /me/projects 风格(不是 OpenAPI 已存在路由)。每个路由实施时必须有中文 summary/description、字段说明、响应模型、错误响应、成功失败示例;由 OpenAPI 生成前端客户端。所有路径先校验本人项目、任务与执行的关联;越权及不存在统一 404。

方法与路径 输入 输出/约束
GET /me/projects/{p}/tasks/{t}/executors 无可信身份参数 {project_revision, task_id, candidates:[{id, revision, name, capabilities, price_status, eligible_reason}], unavailable_reasons};不暴露凭据,缺组织证据返回不可用原因
POST /me/projects/{p}/tasks/{t}/executions {executor_id, expected_project_revision, expected_executor_revision}+幂等键 SSE execution(含执行/轮次 ID)→进度→最终快照;服务端重算候选并验证任务输入、上游已验事实、资格和费用政策,再出网
GET /me/projects/{p}/tasks/{t}/executions 无 执行历史与当前执行摘要;失败重试仍可追溯
GET /me/projects/{p}/executions/{e} 无 ExecutionDetail:状态、revision、任务书摘要、交付、确定性检查结果、错误及 allowed_actions
GET /me/projects/{p}/executions/{e}/messages after_seq、上限 100 的 limit 按 seq 升序的已落库消息和 next cursor;恢复分页不触发发送
POST /me/projects/{p}/executions/{e}/messages {text, file_ids, expected_revision}+幂等键 一轮 SSE;拒绝非等待状态、活动轮次和越权文件
POST /me/projects/{p}/executions/{e}/reconcile {expected_revision}+幂等键 查现有 remote task 后的快照;无 taskId 返回待查说明;不 SendMessage
POST /me/projects/{p}/executions/{e}/cancel {expected_revision, reason}+幂等键 cancelled 或 cancel_requested 快照;不能伪报成功
POST /me/projects/{p}/executions/{e}/retry {expected_revision}+新幂等键 仅确定失败的轮次可重试;新 messageId/轮次,沿用 context;reconciling 拒绝
POST /me/projects/{p}/executions/{e}/review {decision:accept/rework, result_revision, expected_revision, comment}+幂等键 SSE:accept 原子写事实并完成后发快照与 done;rework 留原版交付、次数加一,将意见作为本请求的新轮次消息并流式返回;两次不合格提供换人/调整建议但不自动换人

此处 /review 专指用户接受/退回,不代表模型预审;本期验收不依赖模型配置。任务书预览由候选/执行读模型提供,不以浏览器拼装为依据。ExecutionDetail 的 allowed_actions 来自同一个状态判断函数;前端仍须处理服务器拒绝,不能把读模型当授权凭据。project_revision 用于派单和事实写入;工作间消息只推进 execution revision,避免每句对话使全项目冲突。

上报、专家问题与交付通过执行读模型和 system 消息供项目页显示;右侧团团栏负责提示“去工作间回答/验收”,不代用户回答专家、不在两个页面各建一套提交入口。本期不新建代答 runner,也不借用 planned 后禁止澄清的旧项目消息端点。

用户本人兜底采用同一任务的新执行记录(actor_kind=self,executor_id=null,无远端 context),待用户确认退出旧专家后创建;内部入口 choose_self(task),用户 submit_self_result(execution, result, file_ids) 后同样验收写事实。拟定 POST /me/projects/{p}/tasks/{t}/self-executions 输入 {expected_project_revision, previous_execution_id, reason},返回新执行快照;POST /me/projects/{p}/executions/{e}/result 输入 {expected_revision, deliverable, file_ids},返回待验收快照,两者均要求幂等键。前者只接受旧执行已终止且带用户确认的任务,后者只接受本人的 self 执行;首轮直接选择本人时 previous_execution_id 可空。此兜底范围仍须随规格确认;不复用交易 delivery,也不能把「改由本人」算任务完成。更换专家必须带用户确认记录并引用旧 execution,旧轮次仍未知时不得启动新的专家。调整/删除任务仍交后续任务图能力,当前只给明确建议,不提供假按钮。

SSE 新事件独立于 ProjectEvent:execution 已提交快照、text_delta 展示增量、message 已存档消息、done 本请求结束、error 可操作错误;每帧包含 execution_id/turn_id,落库消息带 seq。done 不等于完成验收;断线后以 GET 为准,不将增量重放拼接成重复消息。鉴权和版本错误须在发 SSE 头之前返回正常 HTTP 错误;流内错误附最后可恢复 ID。

错误码最低集合:401 unauthorized;404 project_not_found/execution_not_found;409 version_conflict/execution_busy/execution_state_conflict/project_archived/executor_unavailable/account_eligibility_unknown/dependencies_unaccepted/dispatch_policy_unconfirmed/remote_outcome_unknown/result_changed;422 idempotency_key_reused/invalid_delivery/invalid_attachment;503 ndclaw_not_configured/ndclaw_unavailable。远端 401/403 作为适配配置或授权失败,不误导用户重新登录;只返回脱敏说明和 trace_id。

5.2 适配器契约

复用 PR #14 的具体 NdclawClient(已实现),不再另建 NdclawAdapter 或多平台注册工厂。当前代码签名为 list_agents(user_id, *, include_market=True)、send(user_id, agent_ref, text, context_id=None)、get_turn(user_id, agent_ref, task_id)、cancel(user_id, agent_ref, task_id);返回 Expert/Frame/Turn,Turn.state 去掉 TASK_STATE_ 后为大写。下列是执行服务拟用的语义边界,不是要重新实现第二个客户端:

list_agents(*, uc_subject: str) -> list[AgentDescriptor]
send(*, agent_ref: str, uc_subject: str, message_id: str,
     context_id: str | None, text: str) -> AsyncIterator[RemoteEvent]
get_turn(*, agent_ref: str, uc_subject: str, task_id: str) -> RemoteTurn
cancel(*, agent_ref: str, uc_subject: str, task_id: str) -> RemoteTurn

AgentDescriptor 只承载目录实际返回字段,不能假定 A2A 目录提供标签或价目;RemoteEvent 归一化 context_id/task_id、文本增量与远端状态;RemoteTurn 带远端原始状态、artifacts 文本和脱敏错误。未知状态按不可自动推进处理,不能默认 completed。逐字段 wire schema 复用 PR #14 代码并在任务 1.2 对照原始回执建立 golden fixtures,不把这里的 Python 签名当对方 JSON-RPC schema。当前 send 在函数内生成随机 messageId,尚不能接收预存的 outbound_message_id;任务 3.2 要以向后兼容可选参数补齐这个接缝,才满足 §4.2 的出网前落库。不是远端幂等已有保证。(2026-10-13 林炜修订:实测列表无标签,名片 skills[].tags 有标签、无价目,见专家目录同步与通用模板)

协议项 冻结到测试的要求
地址与版本 https://agent-hub.aiae.ndhy.com,A2A 1.0;POST /a2a/experts/{agentRef}/rpc;方法名 SendStreamingMessage/GetTask/CancelTask,不是小写形式
目录 GET /a2a/experts?include_market=true;只导入确认的市场专家;目录可读不证明发送/取消授权 (2026-10-13 林炜修订:本期全部市场专家开放,见专家目录同步与通用模板)
鉴权 BTS 令牌缓存,每请求重新签名和 nonce;Userid 来自项目所有者可信 UC 身份;A2A-Version: 1.0;不得透传浏览器头或任何 sdp-*;签名使用实际 Host
多轮 第一轮取得 contextId;后续每轮新 messageId,同一 contextId,不带旧 taskId;每轮分别保存远端 taskId
内容与结果 仅文本;文件经我方 CS 签名链接置于正文前;结果取 artifacts 文本,不能把 status.message=done 当交付正文
等待与重试 read timeout ≥600 秒,网关 idle timeout >40 秒;状态提示承接 40~60 秒冷启动;网络失败不自动重试 send;GetTask 的只读重试有次数与总时限
禁用路径 不申请/唤醒实例,不取 wsUrl,不直连文件/技能/渠道接口;发送本身可能创建实例;复用任务 2 已有授权,业务闭环新增调用若超出原范围再补确认

PR #14 已有配置 NDCLAW_A2A_BASE_URL、NDCLAW_READ_TIMEOUT_SECONDS(默认 600);沿用其名称,不再新增同义超时项。业务层配置最小增量(提案):NDCLAW_A2A_ENABLED 默认 false、NDCLAW_VERIFIED_ORG_UC_IDS(仅核实试点名单)、NDCLAW_RESULT_CS_HOSTS(经过验证的下载域名)。复用已有 BTS 和 CS 凭据字段;费用政策保存在登记/执行快照,未确认禁止真实发送。真实适配器不接受 Fake 请求,即使 UC subject 恰好在名单里;只有 tests 显式注入的 fake adapter 可绕过真实接入前置。

5.3 交付块、附件和项目事实

交付沿用 交付/上报/等待线下 三种 fenced JSON。每条最终回复只允许一个可处理块;多个矛盾块、非法 JSON、未知 schema、超长内容都保存原文并给格式问题,不执行块内指令。任务模板指定字段 schema;定位示例要求 positioning 和 persona_type 非空,主题策划从验收事实读取这两项。模型输出不能指定 owner、状态、执行方或 fact 主键。

有效交付保存 {status:'done', deliverable, self_check, open_issues, downstream_hints, attachments};完整性与真实性分开:结构校验后直接进入用户验收流程,self_check.met=true 不是用户接受。每次补交产生新 result_revision,旧版本保留在对应轮次 response_snapshot;验收携带版本,防退回后的旧页面误验收。本期不显示模型质量意见或“预审通过”标签,不调用模型为用户验收背书;专家 self_check 只作为专家自述,格式/附件检查不证明业务质量。

原方案的「收尾话术→团团提取交付」建议本轮不自动生效:可以生成待用户检查的候选交付,不能直接完成或写事实;明确列为待确认偏离。没有块按普通对话,做不了按上报,缺附件按结果问题,均有下一步。(2026-10-13 林炜修订:本期启用。快速解析拿不到有效块且远端已完成时,团团用模型把回复整理为「需要你回答」(只展示问题与阻塞)或候选交付(通用模板以摘要为成果正文,完整原文另存为私有 .md 附件,先只提供下载);仍须用户验收,原文保留,模型不可用时退回原行为。见专家目录同步与通用模板。)

文件转存由执行域调用文件域公开服务:仅允许经验证的 CS HTTPS 域名,检查重定向后的目标、解析 IP、大小和 MIME,禁止内网/本机地址与任意下载;不把我方 BTS 头发给远端下载链接。成功后以私有 file_id 替换临时链接。失败保留可读文本、附件失败原因和补交动作;必需附件未转存则验收返回 409,不允许把失效链接写成已验事实。外部原链接仅作受限诊断数据,日志、普通读模型不输出带签名查询参数。具体 CS 域名、有效期和下载鉴权目前未验真,不能自行虚构允许域名。

用户接受时在一个事务中:锁项目/执行→验证身份、result_revision、状态与必需附件→写唯一事实版本→记录 acceptance→completed。重复接受返回同结果;失败全部回滚。下游派单仅取明确依赖任务已验收的事实,保存 fact IDs/version 快照;不可偷取尚未验收或被退回结果。原任务验收标准不会由专家输出修改。

5.4 连贯原型到应用的接口补充(1012 晚会后)

入口已定、URL 提案:画布上已派给外部专家的卡片、右侧团团栏“去工作间回答/验收”和“等你”清单,统一定位 {project_id, task_id, execution_id}。应用路由沿用实际 /projects/$projectId,建议以 task/execution/tab 查询参数恢复工作间;具体 Router 声明在 UI 切片落实。未派单或非外部专家仍进入任务详情。工作间占画布工作面,保留项目头与团团栏;不会导航成另一套独立产品页面。

工作间三页签:专家对话(有 seq 的消息、自由输入及可选快捷回复)、任务书(服务端派单快照)、交付记录(所有交付版本、附件、用户验收/退回)。文件和验收只在工作间展示/操作;团团栏只指路。ExecutionDetail 补 task_title、executor_name、status_label、attention_reason、rework_count及已有 allowed_actions。文件下载仍走私有权限检查,不直接给原始专家签名 URL。

新增 GET /me/projects/{p}/execution-summary,返回本人项目所有任务的 {task_id, execution_id|null, executor_kind, status|null, display_status, status_label, attention_reason|null, entry:task_detail/workroom, revision, allowed_actions} 和按任务去重的 counts:{running, waiting_reply, awaiting_acceptance, execution_needs_attention};没有执行的任务也保留一项,避免列表空洞。此聚合避免画布每张卡分别查询;不能读取他人项目。状态未映射时显示“状态待核对”及查回入口,不当完成。页面刷新或工作间操作结束后重新取聚合;无需本期新建跨页通知/消息中心。

执行状态 卡片业务状态/视觉参考 入口与最低可操作反馈
无执行 未开始/白卡 任务详情,查看候选;生成计划不等于已派单
dispatching / running 进行中/绿色转圈;分别写专家准备中、进行中,rework_count 可提示返工中 已派外部专家进工作间;在途不能发第二轮
waiting_user 等你回复/橙色介入提示 工作间对话,提交后恢复运行
waiting_offline / reported 等你处理/橙色+明确线下动作或做不了原因 工作间说明及用户处理入口,不能只用“等你”掩盖原因
awaiting_acceptance 等你验收/橙色介入提示 交付记录或当前交付区,验收/退回
reconciling / cancel_requested 等你处理/文字写结果待查或取消待确认 查回及原因;禁用重发和换人;不映射成“搁置”终态
completed 已完成/已验收文字 历史只读;事实版本可查
failed / cancelled 搁置,并保留失败/已取消具体文字 明确失败允许显式重试;已取消只读及按政策重新派单

进度条是业务展示投影,不能把等待回复、返工、待查都压成线性“进行中”。颜色只辅助,文字和可用操作必须一致。这些 counts 是执行域接口提案,不是原型已有的全部项目统计。原型画布“进行中”包含派出/运行/返工;项目头“等你”还累计待确认、提议、问题和线下待办,一个任务可贡献多件待办。execution_needs_attention 只表示按任务去重的执行待处理数,不能替换项目头“等你”总数;全项目待办聚合由上游运行层负责,D5 需明确展示口径。

交付记录不能仅显示最后一版:新增 GET /me/projects/{p}/executions/{e}/deliveries?before_revision=&limit=(limit 上限 50),返回 {items:[{result_revision, turn_id, submitted_at, deliverable, file_ids, file_status, user_decision, comment}], next_cursor}。来源为已存轮次 response_snapshot 和验收审计,不新增第六张表。尚无交付返回空列表,不制造假历史。每版内容均校验本人权限;用户验收仍提交精确 result_revision。

计划生成→开工派单接缝:现有 /start 只生成计划,继续保留。原型的“确认开工/应用派出”触发当前已选候选的 executions POST;这次点击就是该派单授权,不再强迫用户进入工作间后点第二次“启动”。多任务开工提议、依赖任务排队与自动派出是否纳入当前切片仍由 D5/D6 确认;在未明确任务集合和授权范围时,不能因 Project.status=planned 就批量调用专家。最小版仅发送已确认且上游已验收的任务;其余显示“等前置成果”,在前置验收后重新展示可派单动作。若要原型中的一键派出多任务和自动排队,则先补持久化授权快照、队列及重试契约,不以浏览器循环发送代替设计。

交付历史的存储约束:execution_messages.event_metadata 由服务端构造,至少包含 {event_type, result_revision, actor_user_id, decision, comment}。事件类型为 result_submitted/accepted/rework_requested,非验收事件的 decision 可空;时间及执行编号使用消息行字段。验收/退回与状态变更在同一事务写入对应 result_revision 的事件。历史接口按版本关联这些事件,不解析自由文本,也不只读 executions.acceptance 的最新快照。self 执行没有远端轮次,每次 /result 在 result_submitted 事件中追加不可变 {deliverable, file_ids, submitted_at} 快照;补交递增 result_revision,不覆盖旧快照。专家结果仍从 turn.response_snapshot 读取,两种来源返回同一历史契约,客户端不得指定审计 actor。

完整计划编辑/应用/撤回虽是原型已定方向,但目前 Project.tasks JSONB 不具备它们;这是上游产品能力的跨目标交接,不能说本期目标一顺带已有,也不能断言全产品本期都不做。相关实现前必须确认 task_revision、改过的任务书是否需要用户重新授权,以及已发出的远端任务不可随本地撤回而假装未发生。

6. 涉及路径、验证与待定事项

后续预计新建 apps/api/app/executors/README.md、该目录的 models.py、schemas.py、states.py、service.py、router.py、delivery.py 及本域测试;按职责必要时拆轮次服务,不先铺空文件。修改 tuantuan/schemas.py 与计划生成/输出校验、项目归档保护、common/config.py、main.py 路由注册、文件域私有用途、身份依赖的真假身份信息。ndclaw.py 和 identity.uc_profile.service_token 复用 PR #14 已有实现,现阶段不再规划另抽 common/bts.py。前端按连贯原型在 projects 功能接入工作间和任务卡读模型;未演示的异常/下游部分先补原型并确认,再实施对应入口。

新增 fake A2A、契约 fixtures、集成和业务场景时同步 tools/ci/affected.toml、apps/acceptance/AC.md、INDEX.md。单元覆盖匹配、解析、状态、幂等与签名;真实 PostgreSQL 集成验证约束与事务;浏览器验证派单→续话→验收→下游和权限失败。业务状态及服务加变异测试,遵守仓库 100%/三层 300%/变异 ≥80%,不新增豁免。目标一涉及外部接入、权限、状态机,实施按大档收口;本轮纯文档只做文档验证,不宣称产品门禁通过。

需确认/与原方案差异 推荐 影响
D3 模型预审(本会话已收口) 本期不做;保留确定性检查与用户验收 3.4b 后置,不是本期前置;以后结合任务书、相关已验事实和评估样例另定,不预埋流程
专家免费、模型与容器由谁承担 未确认前 pricing_status=unconfirmed,禁止真实自动派单;确认演示政策后保存快照 「可以先用」不能自动等于免费;项目预算是文本,当前无数值扣费能力 (2026-10-13 林炜修订:本期按免费政策登记,见专家目录同步与通用模板)
组织账号权威来源 试点用核实账号名单+真实 UC,后续权威字段替换 先复用任务 2 的身份/授权证据,只补业务准入尚缺部分;不以假登录代替
五表取代四表、增加结果待查/取消待确认 采用本稿,保留逐轮副作用记录 必须先于持久化/发送实现确认,不靠前端兜住重复派单
收尾话术兜底不自动验收 仅产出待用户核实候选 少误判;提示词未改专家需人工协作
上报后的完整任务调整能力未落地 先给出换人/本人做/调整建议,前两者按本稿闭环;图编辑另排 不把原方案里“团团处理”当已有工具;后续平台执行闭环不冒充完整运营层
工作间及异常交互 已补的 master 故事线为基准;缺失分支先补同一原型 §5.4 给入口/读模型;原型未包含下游和完整异常,不据此删除它们
本周单案例与终点 推荐直播电商,具体任务链由 D6 固定 不将原型八章全部能力或九专家全部上架默认为本周目标一范围

后续平台执行闭环的 E2E 顺序与剩余前置见配套交接稿;最小真实接入不重复开工。规格未决不改写为已批准,进入实现前按该稿的最小确认项逐项收口。

本会话预审范围决定的理由

采纳用户“预审涉及项目上下文,本期也不做”的建议。本期优先验证专家输入、产出与用户验收能否闭环;没有验证过的模型意见会增加上下文拼装、版本对齐、误判处理和评估范围,收益尚无证据。保留交付格式、必需附件、私有权限、来源与版本的程序校验,但不把这些称为业务质量预审。后续预审未必需要完整项目聊天或完整项目记忆,可先评估“任务书+验收标准+相关已验上游事实+当前交付”的最小上下文;这是恢复该能力的候选方案,不是本期隐含实现项。