# Task Kanban + Review 改造方案设计

## 文档状态

本文最初是 task 改造 proposal；自 2026-04-13 起，正式生效的 canonical spec 已独立收敛为：

- `specs/task/board.md`

本文保留为设计背景与推导过程，不再单独定义当前生效行为。

当前 canonical 约束仍以这些文档为准：

- `SPECS.md`
- `specs/task/board.md`
- `specs/collaboration/collaboration.md`
- `specs/identity/identity.md`
- `docs/architecture-spec.md`
- `docs/tech_design.md`

如需看当前 shipped implementation / compat surface，请优先读：

- `docs/tech_design.md`

## 1. 背景与问题诊断

当前 task 机制已经满足了最小 ownership 语义：

- channel-bound task board
- exclusive claim
- `todo -> in_progress -> in_review -> done`
- `/task` 可从聊天进入结构化 task

但它仍然过于粗糙，主要问题集中在三类。

### 1.1 Kanban 体验不成立

当前更像“任务列表”，不像真正的 task board：

- UI 以 list 为主，不是 board-first 视图
- `todo + claimed` 这种状态在当前列表里语义不直观
- 没有 Ready / Doing / Review 这些明确执行面
- 没有 blocked / stale / needs review 等高信号视图
- card 信息太薄，缺少 reviewer、review 状态、artifact、更新时间等执行信号

### 1.2 Agents 用起来太粗

当前 agent 工具链只有：

- `list/create/claim/unclaim/update_status`

这导致 agent 在真实执行中会遇到几个问题：

- 收到 `/task @agent` 时，本质还是靠系统消息文本理解任务
- 缺少 `task_get` 这种完整 task detail 读取能力
- 缺少 task-native 的 progress checkpoint / artifact / block / review request 写入能力
- 缺少 subtask / split 支持
- 缺少“我现在该 review 什么 / 我被建议处理什么”的一等视图

### 1.3 人类 review 体验太弱

当前 “review” 基本只等于：

- task 被移到 `in_review`
- 某个 channel member 再把它点成 `done`

这远远不够，因为它没有一等化这些事实：

- review request 是谁发起的
- reviewer 是谁
- review evidence 是什么
- reviewer 看的 diff / artifact / thread context 在哪里
- review 结果是 approve 还是 request changes
- review comment 和 decision history 如何沉淀

结果就是：

- review 行为主要散落在聊天里
- task board 只看到一个 `in_review`
- 人类 reviewer 缺少稳定、低认知负担的 review 面板

## 2. 目标

这次改造的目标有三条。

### 2.1 做成真正可用的 task kanban

要求：

- 默认就是 board-first，而不是 list-first
- 一眼能看出 backlog、ready、doing、review、done
- card 自带足够的执行信息
- 支持 reviewer / blocked / stale / suggested 等关键过滤

### 2.2 让 agents 把 task 当成主工作流

要求：

- agent 收到 task 时拿到结构化 task context，而不是只靠消息文本
- agent 可以 task-native 地记录进度、阻塞、artifact、review request
- agent 可以从 task detail 直接知道 acceptance criteria 和 review expectation
- agent 能自然地 split task，而不是把拆分完全散在聊天里

### 2.3 让 human review 成为一等体验

要求：

- review request 是一等对象
- review evidence 是一等对象
- reviewer queue 是一等视图
- approve / request changes / reassign reviewer 是明确动作
- review 历史可审计、可回看

## 3. 非目标

为避免方案失焦，本轮明确不做这些事：

- 不把 task 变成 workspace-global object
- 不取消 exclusive claim
- 不把聊天系统重做成 issue tracker comments
- 不让 `/task` 变成复杂命令语言
- 不做大爆炸式 status machine 重写

这轮改造应该是“把当前 task 机制做精”，不是再造一套完全不同的协作系统。

## 4. 设计原则

### 4.1 保留 channel-bound ownership

task 继续保持 channel-bound。

- channel 是 ownership 边界
- thread 是局部上下文边界
- review 是 task 的一个结构化阶段，不是另起一个对象宇宙

### 4.2 保留 exclusive claim，但补齐 reviewer 维度

执行 owner 继续保持唯一，避免 agent 重复开工。

但要新增 reviewer 维度：

- `claimedBy` 回答“谁在做”
- `reviewer` 回答“谁来审”

二者不应混在一起。

### 4.3 Kanban column 尽量从稳定状态派生，而不是制造新状态爆炸

当前 progress state 已经足够清晰。

因此推荐：

- 尽量保留 `todo / in_progress / in_review / done`
- Kanban column 从 `status + claim + blocked + review metadata` 派生

这样能显著改善 UX，同时避免服务端状态机复杂度暴涨。

### 4.4 review 单独一等化，而不是继续塞进聊天

task 的 review 不能继续只靠：

- `in_review`
- 频道里几句零散聊天

review 需要最少具备：

- request
- reviewer
- evidence
- decision
- history

### 4.5 task 变化默认仍然 task-native，不自动污染聊天

当前“task 变更不自动发消息”的大方向是对的，应该保留。

但应允许在关键节点显式同步到 thread / channel，例如：

- 发起 review request
- review 结论沉淀
- human 希望把结论广播到 thread

默认 quiet，必要时 explicit announce。

## 5. 目标产品模型

## 5.1 Board 视图：从 list 升级为真正的 kanban

默认 board columns：

- `Backlog`
  - `todo` 且未 claim
- `Ready`
  - `todo` 且已 claim
- `In Progress`
  - `in_progress`
- `In Review`
  - `in_review`
- `Done`
  - `done`

额外规则：

- `blocked` 不作为单独 progress status，而是 card overlay / badge
- `changes requested` 不必强行创造新 progress status，可作为 review outcome 附加在重新回到 `in_progress` 的 card 上

这样有两个好处：

1. 第一阶段甚至可以不改核心状态机，只改 board 语义
2. `todo + claimed` 终于有了自然的视觉归宿，即 `Ready`

### 5.1.1 Card 信息密度

task card 至少补齐：

- title
- task number
- status badge
- owner / claimer
- reviewer
- suggested assignee
- source thread
- blocked badge
- review badge
- artifact count
- last activity time

当前 card 只有 title + status + claimed/suggested/source thread，远远不够支撑 kanban。

### 5.1.2 常用 filters

board 右上角最少支持这些 filters：

- `Mine`
- `Suggested to me`
- `Needs Review`
- `Blocked`
- `Stale`
- `Created by me`

第二层可支持：

- reviewer
- owner
- kind
- priority

### 5.1.3 Grouping 与 secondary views

除默认 board 外，再补两个 secondary views：

- `Review Queue`
  - 面向 reviewer，看“哪些 task 等我审”
- `My Work`
  - 面向执行者，看“我 claim 的 + 建议我处理的 + 我发起 review 的”

这两个视图对 human reviewer 和 agents 都非常重要。

## 5.2 Task detail：从“薄卡片”升级为“执行中心”

新增 task detail drawer / panel，默认包含 5 个 tab：

- `Overview`
- `Context`
- `Activity`
- `Review`
- `Artifacts`

### 5.2.1 Overview

用于展示和编辑任务本体：

- title
- description / goal
- acceptance criteria
- review checklist
- owner
- reviewer
- suggested assignee
- priority
- kind
- blocked reason

这里有一个关键改造：

当前 task 基本只有 title。
未来 task 至少需要支持：

- `description`
- `acceptance criteria`
- `review checklist`

否则 agent 不知道“完成到什么程度算 done”，reviewer 也不知道“要按什么标准审”。

### 5.2.2 Context

用于收敛任务上下文：

- source thread
- linked task thread
- pinned messages
- relevant URLs
- workspace files / docs refs

设计上推荐：

- 每个 task 最终都有一个 primary thread ref
- 来自 thread `/task` 时，默认沿用该 thread
- 从 channel 直接建 task 时，可后续显式创建 / 绑定 task thread

这样 task 的执行讨论和 review 讨论都能稳定收口，不再散在频道主线。

### 5.2.3 Activity

新增 task-native activity timeline，而不是只靠聊天回放。

典型 event：

- created
- claimed
- unclaimed
- status changed
- blocked / unblocked
- reviewer assigned
- review requested
- review approved
- review changes requested
- artifact added
- checklist updated

Activity timeline 的目标不是替代聊天，而是形成 task 自己的低噪音审计面。

### 5.2.4 Review

Review tab 要成为 human reviewer 的主工作面，至少有：

- 当前 review request
- reviewer
- review summary
- decision actions
- review comments
- 历史 review 记录

### 5.2.5 Artifacts

Artifacts tab 用于挂 review evidence，典型包括：

- linked thread / message
- URL
- attachment
- workspace file
- agent output target
- branch compare target
- command/test summary

## 5.3 Review model：把 review 从“一个状态”升级为“一等对象”

推荐新增 `task_review_requests` 领域对象。

### 5.3.1 为什么要单独一等化

`in_review` 只能表达“这件事正在等 review”。
它表达不了：

- reviewer 是谁
- review 看什么
- review request 是谁发起的
- 是第一次 review 还是返工后的第二次 review
- 上次 decision 是 approve 还是 changes requested

因此 review 必须是一等对象。

### 5.3.2 最小 review request 结构

建议字段：

- `task_id`
- `requested_by_ref`
- `reviewer_ref`
- `status`
  - `requested`
  - `approved`
  - `changes_requested`
  - `cancelled`
  - `superseded`
- `summary_md`
- `questions_md`
- `decision_md`
- `requested_at`
- `decided_at`
- `review_target_type`
- `review_target_payload`

其中 `review_target_*` 用来表达 reviewer 应该看什么。

典型 review target：

- `agent_output_working_tree`
- `agent_output_branch_compare`
- `task_artifact_set`
- `thread_only`

### 5.3.3 Review 决策语义

当前推荐：

- `request review`
  - task 进入 `in_review`
  - 生成新的 review request
- `approve`
  - 当前 review request 标记为 `approved`
  - task 从 `in_review -> done`
- `request changes`
  - 当前 review request 标记为 `changes_requested`
  - task 回到 `in_progress`
  - 保留 review history，不丢失上一次 review context

这比“reviewer 直接把 task 改成 done 或聊天里说两句”要清晰得多。

## 6. 面向 agents 的改造

## 6.1 收到 task 时给 agent 结构化 task packet

当前 `/task @agent ...` 对 agent 来说本质还是一条 system message。
这对 agent 太粗了。

建议改为：

- channel 中仍然保留 system message，满足 human audit
- 同时给被通知 agent 一份结构化 task packet sidecar

最小 packet：

- `taskId`
- `taskNumber`
- `channelId`
- `channelRef`
- `title`
- `description`
- `acceptanceCriteria`
- `reviewChecklist`
- `reviewer`
- `suggestedToYou`
- `sourceThreadRef`
- `primaryThreadRef`

这样 agent 不需要从系统消息文案里反解析任务。

## 6.2 增加 task-native tools，而不只是一组粗粒度动作

建议 native tool surface 最少补到：

- `task_list`
- `task_get`
- `task_create`
- `task_claim`
- `task_unclaim`
- `task_update`
- `task_add_artifact`
- `task_add_checkpoint`
- `task_block`
- `task_unblock`
- `task_request_review`
- `task_create_subtasks`

其中最关键的不是多，而是补齐三个能力：

1. 读取完整 task detail
2. 写入结构化执行痕迹
3. 发起结构化 review request

### 6.2.1 `task_get` 必须是一等能力

当前缺少 `task_get`，是 agent 体验粗糙的核心原因之一。

`task_get(task_ref)` 应返回：

- task metadata
- overview fields
- checklist
- review state
- linked thread refs
- artifacts
- recent activity

这会成为 agent 开工前的默认入口。

### 6.2.2 `task_add_checkpoint`

很多 agent progress update 不应该都变成聊天消息。

因此建议引入：

- `task_add_checkpoint`

用来记录：

- 当前做了什么
- 下一步做什么
- 发现了什么风险

这既能沉淀 activity timeline，也能让 human 在 task 内快速判断进展。

### 6.2.3 `task_add_artifact`

agent 执行结果最需要结构化落地的是 artifact。

典型 artifact：

- diff / compare target
- test result summary
- command output summary
- relevant file paths
- docs URL
- thread / message ref

agent 不必每次都把这些内容塞进主频道消息。

### 6.2.4 `task_request_review`

agent 完成后不应只做两件事：

- 更新 `in_review`
- 发一句“请 review”

而应能提交结构化 review request：

- review summary
- artifacts
- reviewer
- open questions
- risk notes

这样 human reviewer 才有一个真正可 review 的对象。

## 6.3 保留 exclusive claim，但增加 subtask 能力

agent 最常见的一个真实需求是拆分工作。

建议给 tasks 增加可选：

- `parent_task_id`

并支持同 board 内的一层 subtask 关系。

这样 agent 可以：

- 把大任务拆为几个子任务
- 仍然保持每个执行项的 exclusive claim
- human 在 board 上看到 parent 的完成进度

这比让 agent 在聊天里说“我拆成三件事了”更稳定。

## 7. 面向 human review 的改造

## 7.1 Review Queue 视图

新增 reviewer-first 视图：

- `Needs Review`
- `Requested by me`
- `Changes Requested`
- `Approved recently`

每张 review card 至少显示：

- task title
- owner
- reviewer
- review requested at
- review age
- artifact count
- 是否 blocked

目标是让 reviewer 能像处理 PR queue 一样处理 task review queue。

## 7.2 Review workspace

Review 面板不应只看到 task title。

它应能看到：

- review summary
- acceptance criteria
- checklist
- linked thread
- artifacts
- diff / compare
- previous review decisions

### 7.2.1 复用现有 Agent Review 能力

仓库里已经有现成的 agent output review 能力：

- `web/src/agentteam/workspace/AgentReviewPanel.tsx`

本次改造建议不要重新发明 diff viewer，而是把它变成 task review 的一个 review target viewer：

- 当 artifact / review target 指向某个 agent output compare 时
- task review 面板直接嵌入或跳转到同一个 review component

这样人类 reviewer 就可以在 task review 内直接看：

- working tree review
- branch compare review
- explicit comparison mode

而不是 task 和 agent review 两套体验完全割裂。

## 7.3 Approve / Request Changes / Reassign Reviewer

Review 面板应至少提供：

- `Approve`
- `Request Changes`
- `Reassign Reviewer`
- `Mark as not reviewable yet`

其中：

- `Approve` 结束当前 review request，并推动 task 到 `done`
- `Request Changes` 结束当前 review request，并把 task 拉回 `in_progress`
- `Reassign Reviewer` 不应要求重新建 task

## 7.4 Review checklist

review checklist 和 acceptance criteria 不应只是 description 里的一段文字。

建议一等化为 checklist items，可用于：

- human 创建任务时填写
- agent 自己勾选已满足项
- reviewer 对照审查

这能显著减少“我以为做完了，但 reviewer 说不是这个标准”的来回。

## 8. 数据模型建议

## 8.1 `tasks` 表扩展

建议增加：

- `description_md`
- `kind`
- `priority`
- `reviewer_ref`
- `blocked_reason`
- `blocked_at`
- `primary_thread_parent_channel_id`
- `primary_thread_parent_message_id`
- `last_activity_at`
- `parent_task_id`

注意：

- `blocked` 建议用 flag / reason 表达，不作为新的 progress status
- `reviewer_ref` 与 `claimed_by_ref` 是两个独立角色

## 8.2 `task_checklist_items`

建议新增结构化 checklist 表：

- `id`
- `task_id`
- `kind`
  - `acceptance`
  - `review`
- `body`
- `sort_order`
- `completed_by_ref`
- `completed_at`

## 8.3 `task_artifacts`

建议新增 artifact 表：

- `id`
- `task_id`
- `kind`
- `label`
- `payload_json`
- `created_by_ref`
- `created_at`

典型 `kind`：

- `thread_ref`
- `message_ref`
- `url`
- `workspace_file`
- `agent_review_target`
- `attachment`
- `test_summary`

## 8.4 `task_review_requests`

见第 5.3 节。

## 8.5 `task_events`

建议新增 append-only event log：

- `id`
- `task_id`
- `event_type`
- `actor_ref`
- `payload_json`
- `created_at`

这会成为 task activity timeline 的基础，也能降低“task 细节全靠 reconstruct 聊天历史”的复杂度。

## 9. API 演进建议

## 9.1 保持 canonical surface 稳定

当前稳定边界：

- Human Task：`/api/v1/workspaces/:workspaceId/channels/:channelId/tasks*`
- Agent Task：`/api/v1/workspaces/:workspaceId/agents/:agentId/runtime/tasks*`
- websocket `task:*`

这是 architecture-spec 的硬约束，不应被后续 UX 改造打破。

## 9.2 渐进新增 endpoints / fields

第一阶段建议新增而不是替换：

- task payload 新字段
- `PATCH /api/v1/workspaces/:workspaceId/tasks/:taskId`
  - 更新 description / reviewer / blocked / priority / kind
- `GET /api/v1/workspaces/:workspaceId/tasks/:taskId`
  - 返回完整 task detail
- `POST /api/v1/workspaces/:workspaceId/tasks/:taskId/checkpoints`
- `POST /api/v1/workspaces/:workspaceId/tasks/:taskId/artifacts`
- `POST /api/v1/workspaces/:workspaceId/tasks/:taskId/reviews`
- `POST /api/v1/workspaces/:workspaceId/tasks/:taskId/reviews/:reviewId/approve`
- `POST /api/v1/workspaces/:workspaceId/tasks/:taskId/reviews/:reviewId/request-changes`

Agent 侧则对应新增 native tools。

## 9.3 `/task` 保持轻量

不建议把 `/task` 扩展成一门复杂命令语言。

推荐策略：

- `/task` 继续做 quick create
- richer metadata 主要在 task detail 内补充
- `/task @agent ...` 继续只解决“创建 + suggestion + notify”

这样可避免命令解析复杂度失控。

## 10. UX 分阶段改造方案

## Phase 1：Board-first Kanban + Task Detail

目标：

- 不大改状态机
- 先把 task board 做成真正好用的 kanban

交付：

- board columns：Backlog / Ready / In Progress / In Review / Done
- blocked / reviewer / last activity 等 card 信息
- task detail drawer
- description / acceptance criteria / review checklist
- reviewer 字段
- source thread / primary thread 可见化

这一阶段完成后，即使不做 review object，体验也会比现在提升一大截。

## Phase 2：Agent-native task process

目标：

- 让 agent 真正以 task 为主要执行对象，而不是 message-first + task-second

交付：

- `task_get`
- `task_add_checkpoint`
- `task_add_artifact`
- `task_block`
- `task_create_subtasks`
- `/task @agent` structured task packet
- My Work / Suggested to me 视图

## Phase 3：Review-first workflow

目标：

- 让 `in_review` 从“状态”变成“完整 review 面”

交付：

- `task_review_requests`
- Review Queue 视图
- review summary / decision / history
- Approve / Request Changes / Reassign Reviewer
- 与 `AgentReviewPanel` 的 artifact/diff 集成

## Phase 4：服务与工具收口

目标：

- 把新 task-native 能力收口到未来 `agentteam-task` native service / native skill 上

交付：

- 补 native task skill manifest
- compat tools 继续保留 alias
- 新增 review/artifact/checkpoint endpoints 的 capability 化

## 11. 为什么这个方案合适

这个方案的关键优点是：

### 11.1 它不推翻当前最有价值的部分

保留：

- channel-bound
- exclusive claim
- claim-before-work
- `/task` 结构化入口

这些都是当前机制里真正正确的部分。

### 11.2 它优先补“看起来像 kanban，但本质上也更适合执行”的部分

不是只换 UI，而是同时补：

- column model
- task detail
- activity
- review

这样 UX 和 domain model 是一起变好的。

### 11.3 它把 agent 和 human review 都纳入同一个 task-native flow

当前最大的问题不是 task 不存在，而是：

- agent 在 task 上信息不足
- human 在 review 上信息不足

这套方案正好同时解决两端。

### 11.4 它能渐进落地

最重要的一点是：

- Phase 1 就能先明显改善 board 体验
- 不需要一开始就把 review object、native skill、service split 全部做完

这比“先重做整个 task domain 再说”更稳。

## 12. 仍待决策的问题

建议在正式立项前明确这些问题：

- reviewer 是否只允许 human，还是允许 agent 先做 internal review
- blocked 是纯 flag，还是需要更重的 workflow 语义
- subtask 是否只做一层 parent-child，还是允许更深层级
- direct task create 是否要在 UI 上强制补 description / acceptance criteria
- review approve 后 `done` 是否继续保持终态

我的建议是：

- reviewer 先只做 human
- blocked 先做 flag，不做新 status
- subtask 先只做一层
- direct create 不强制，但强提示补全
- `done` 先保持终态

这样第一版最稳，也最符合当前系统的简洁方向。

## 13. 外接 Kanban / Issue 服务整合设计

除了把 AgentTeam 自己的 task board 做精之外，还需要考虑一个更实际的问题：

- 很多团队已经在用 Jira、ONES、Linear、Trello 或其它外部任务系统
- AgentTeam 不能假设所有团队愿意把 planning / roadmap / issue tracking 全部迁进来
- 但如果 AgentTeam 完全不接外部系统，agent workflow 和 human review 又会和真实项目管理脱节

因此，AgentTeam 的 task management 需要支持“外接 task provider”。

## 13.1 先明确目标：不是简单 iframe，而是 task federation

这里要解决的不是“把外部看板嵌到页面里”。

真正要解决的是：

- human 在 AgentTeam 里能看到外部 issue 的关键信息
- agent 能围绕这些 issue 执行、claim、review、沉淀 artifact
- 外部系统状态变化能回流到 AgentTeam
- AgentTeam 内部执行进度也能在需要时回写到外部系统

这本质上是：

- `AgentTeam task domain`
- 与 `external issue/kanban domain`

之间的 federation / sync 问题。

## 13.2 设计原则：AgentTeam 继续拥有“协作执行面”，外部系统可拥有“项目管理面”

推荐把两者职责拆开，而不是强行让其中一边吞掉另一边。

建议默认职责划分：

- 外部系统更适合拥有：
  - roadmap / epic / sprint / release
  - 跨团队 backlog
  - estimate / story points
  - org-level reporting
- AgentTeam 更适合拥有：
  - channel-bound ownership
  - agent claim
  - task-native context thread
  - artifacts / checkpoints
  - review request / approval history

也就是说：

- 外部系统是 planning source
- AgentTeam 是 execution + collaboration source

当然，部分字段可以双向同步，但不应假设“所有字段都双向强一致”。

## 13.3 三种整合模式

建议支持三种 integration mode，而不是只做一种。

### 13.3.1 Link 模式

最轻量模式：

- AgentTeam task 仍然是本地 task
- 只是额外挂一个 external issue link

典型使用：

- human 在 AgentTeam 建 task
- 任务详情里关联 Jira `PROJ-123` 或 ONES card
- AgentTeam 保留自己的 owner / review / artifact / thread
- 外部系统只作为 planning 或 reporting backlink

适合：

- 想低成本接入
- 不需要强同步
- 只希望“AgentTeam task 能指向外部 issue”

### 13.3.2 Mirror 模式

中间模式：

- 外部 issue 被投影成 AgentTeam task card
- AgentTeam 保留一个本地投影对象
- card 上明确标记 `backed by Jira` / `backed by ONES`

典型语义：

- 外部 issue 的标题、优先级、外部状态、外部 assignee 可同步进来
- AgentTeam 本地新增：
  - claim
  - review
  - artifacts
  - checkpoints
  - task thread

适合：

- 团队继续在 Jira / ONES 做主 backlog
- 但希望在 AgentTeam 里完成 agent execution 与 review

### 13.3.3 Proxy / Managed 模式

最重模式：

- human 或 agent 在 AgentTeam 创建 task
- AgentTeam 同步在外部系统创建 issue
- 之后通过映射持续双向同步

适合：

- 团队希望“以 AgentTeam 为操作入口”
- 但又必须把 issue 反映到 Jira / ONES 中给公司流程消费

### 13.3.4 推荐默认策略

建议默认优先级：

1. 先做 `Link`
2. 再做 `Mirror`
3. 最后再做 `Proxy / Managed`

原因很简单：

- `Link` 成本低，立刻能用
- `Mirror` 才真正解决 agent / review 与外部 issue 脱节的问题
- `Proxy` 最复杂，容易引入字段 ownership 冲突和双写问题

## 13.4 AgentTeam 内部对象模型建议

推荐不要把 `tasks` 表直接改造成“外部 issue 的扁平复制品”。

更合理的做法是增加一层“external backing”模型。

### 13.4.1 新增 `task_external_links`

建议表：

- `id`
- `task_id`
- `provider_kind`
  - `jira`
  - `ones`
  - `linear`
  - ...
- `connection_id`
- `external_object_type`
  - `issue`
  - `card`
  - `subtask`
  - `sprint_item`
- `external_ref`
  - 如 `PROJ-123`
- `external_id`
  - provider 内部稳定 id
- `sync_mode`
  - `link`
  - `mirror`
  - `managed`
- `field_ownership_policy`
  - JSON
- `created_at`
- `updated_at`

一条 task 可以先只连一个主要 external backing。
将来如有必要可允许多个 link，但 v1 建议先只支持一个 primary external backing。

### 13.4.2 新增 `external_task_snapshots`

建议表：

- `id`
- `task_external_link_id`
- `snapshot_version`
- `payload_json`
- `fetched_at`

作用：

- 保留最近一次外部对象快照
- 用于 UI 快速展示
- 用于 sync diff 与故障排查

### 13.4.3 新增 `task_sync_runs`

建议表：

- `id`
- `connection_id`
- `provider_kind`
- `direction`
  - `inbound`
  - `outbound`
- `status`
- `summary_json`
- `started_at`
- `finished_at`

作用：

- debug webhook / poll / cli sync
- 给 admin 和开发者排查同步错误

## 13.5 字段 ownership：必须是逐字段定义，而不是“谁都能改”

外部整合最容易翻车的地方就是：

- AgentTeam 改了 title
- Jira 也改了 title
- 到底谁赢

所以必须定义 field ownership policy。

### 13.5.1 推荐默认 ownership

对于 `mirror` 模式，建议默认：

- 外部拥有：
  - external status
  - external assignee
  - priority
  - estimate
  - labels
  - sprint / milestone
- AgentTeam 拥有：
  - `claimedBy`
  - reviewer
  - blocked reason
  - checkpoints
  - artifacts
  - review requests
  - primary thread / source thread
- 可配置双向或主从同步：
  - title
  - description
  - local kanban projection column

### 13.5.2 两套状态不要强行合并成一套

Jira / ONES 往往有自定义 workflow。
AgentTeam 不应该要求它们都映射成完全相同的状态机。

更合理做法：

- 外部状态单独保留：`externalStatus`
- AgentTeam 内部状态继续保留：`todo / in_progress / in_review / done`
- board column 主要由 AgentTeam status 派生
- card 上额外展示 external status badge

也就是说：

- `AgentTeam status` = 执行协作状态
- `external status` = 外部项目管理状态

只有在 workspace 明确配置 field mapping 时，才允许做自动映射。

### 13.5.3 外部状态映射表

若团队确实需要同步状态，建议配置：

- `external_status_mapping`

例如：

- Jira `To Do` -> AgentTeam `todo`
- Jira `In Progress` -> AgentTeam `in_progress`
- Jira `In Review` -> AgentTeam `in_review`
- Jira `Done` -> AgentTeam `done`

但这必须是 connection/project scoped 配置，不应硬编码。

## 13.6 安装与连接模型：建议复用 App / Service Install 思路

仓库里已经有一套比较成熟的安装/连接模型：

- `service`
- `service_installation`
- `app installation`
- `app connection`

外接 task provider 很适合复用这个思想。

### 13.6.1 推荐模型

对 Jira / ONES 这类 provider，建议有两层：

- `provider installation`
  - 代表某 workspace 安装了 `jira` 或 `ones` integration
- `provider connection`
  - 代表一个具体外部 account / project / org 连接

这与现有 app spec 里的：

- one installation
- many connections

是同一种模式。

### 13.6.2 为什么这很重要

因为一个 workspace 很可能会：

- 接一个 Jira cloud site
- 再接多个 project
- 或者接一个 ONES workspace 但同步多个 board

不能把这些都塞进一个模糊的“jira enabled = true”开关里。

## 13.7 两条整合路线：App identity 与 Task provider capability

这里建议把“消息身份”和“任务同步能力”分开建模。

### 13.7.1 App identity

如果希望在聊天里有：

- `@jira`
- `@ones`

这种 service member，可以复用 App system：

- 安装后有 service member
- 可以发消息
- 可以接外部 webhook
- 可以把外部事件推回 thread

### 13.7.2 Task provider capability

但仅有 App identity 不够，因为 task integration 还需要：

- 创建 / 更新 AgentTeam task projection
- 写入 external link
- 更新 external snapshot
- 执行 field sync

这属于 task-domain capability，不只是“发一条消息”。

因此更合理的是：

- `@jira` / `@ones` 负责消息与事件身份
- task provider adapter 负责 task federation

二者可以由同一个实现提供，但模型上应分开。

## 13.8 ONES / Jira provider adapter contract

AgentTeam 内部建议定义一个稳定的 task provider adapter contract，而不是在 core/task 里到处写 provider-specific 逻辑。

最小 adapter 能力：

- `ListProjects()`
- `ListBoards(projectRef)`
- `SearchIssues(query)`
- `GetIssue(externalRef)`
- `CreateIssue(input)`
- `UpdateIssue(externalRef, patch)`
- `TransitionIssue(externalRef, transition)`
- `AddComment(externalRef, comment)`
- `ListChangedIssues(sinceCursor)`
- `ResolveWebhook(payload)`

这样：

- Jira adapter 用 Jira API 实现
- ONES adapter 可以用 ONES API 或 `ones-cli` 实现

AgentTeam 上层不关心 transport 细节。

## 13.9 `ones-cli` 怎么接入

你提到一个很实际的场景：

- 我们有一个 ONES kanban 服务
- 已经有 `ones-cli`

这时最重要的结论是：

- AgentTeam 不应该把 `ones-cli` 直接散落在 web handler 里随处 shell out

更合理的做法是做一个 `ONES provider adapter`，CLI 只是 adapter 的 transport 之一。

### 13.9.1 不推荐的做法

不推荐：

- `internal/appapi/handlers_tasks.go` 里直接 `exec ones-cli ...`
- agent tool 直接依赖 CLI 输出格式
- core server 在请求热路径里同步 shell 外部 CLI 并解析文本

这样会导致：

- 鉴权边界混乱
- 错误语义混乱
- CLI 升级容易把服务打坏
- 很难做 webhook / poll / idempotency / retry

### 13.9.2 推荐做法

推荐把 `ones-cli` 封装到一个独立 provider runtime 里。

例如：

- `agentteam-task-provider-ones`

它对 AgentTeam 暴露稳定 adapter contract，对 ONES 侧用：

- `ones-cli`
- 或未来换成 ONES HTTP API

都可以。

这样 transport 可替换，但 AgentTeam 的 provider contract 不变。

### 13.9.3 CLI adapter 的运行方式

`ones-cli` 适合放在：

- background sync worker
- manual import/export job
- provider-side runtime

而不是放在用户请求热路径的核心 handler 里。

推荐支持三种触发：

- webhook 触发同步
- 定时 poll 触发同步
- human 手动点击 `Sync now`

对于没有 webhook 的系统，CLI poll 是可以接受的。

### 13.9.4 CLI adapter 的 contract

如果 `ones-cli` 支持 JSON 输出，最好统一要求 adapter 只解析 JSON。

例如 provider runtime 内部包装这些命令：

- `ones-cli issue get --json`
- `ones-cli issue list --json`
- `ones-cli issue update --json`
- `ones-cli issue comment --json`

然后 provider runtime 再把这些结果转成 AgentTeam 内部统一对象：

- `ExternalIssue`
- `ExternalIssuePatch`
- `ExternalIssueComment`

这样 CLI 只是 transport driver，不会污染 task domain。

### 13.9.5 凭证与安全

若通过 CLI 接入，凭证管理也要明确。

建议：

- AgentTeam 只保存 connection 元数据与 sync config
- provider runtime 自己管理 CLI 登录态 / token
- 或通过 connection-scoped encrypted credential 下发给 runtime

不要让：

- web server 直接依赖某台机器上的全局 CLI 登录态

否则多 workspace / 多 connection 场景会非常混乱。

## 13.10 用户和 agent 在集成场景中的工作流

### 13.10.1 Human 工作流

推荐支持这些入口：

- `Import from Jira / ONES`
  - 把外部 issue 拉成 AgentTeam task projection
- `Link external issue`
  - 给已有 task 挂一个外部 issue
- `Create external issue`
  - 把 AgentTeam task 推成外部 issue

task detail 中新增 `External` 区块：

- provider
- external ref
- sync mode
- last synced at
- sync health
- open in provider
- sync now

### 13.10.2 Agent 工作流

agent 在 task detail 中应能读到：

- external ref
- external title/status
- external URL
- sync policy

并在合适时使用：

- `task_add_artifact(kind=external_link)`
- `task_sync_external(...)`
- `task_push_review_summary_to_external(...)`

但默认不建议让 agent 随意双向同步所有字段。
应只允许 agent 操作被授权的 mapped fields，例如：

- push comment
- push status
- attach review summary

## 13.11 Review 与外部系统如何联动

外部系统通常也有自己的 review / approval / workflow 语义。

AgentTeam 不应试图把它们全部吞并。

推荐策略：

- AgentTeam review 仍然是本地一等对象
- review conclusion 可选择性同步到外部系统

典型同步方式：

- `Approve`
  - 在 Jira / ONES issue 下发一条 structured comment
  - 可选地 transition 外部状态
- `Request Changes`
  - 外部 issue 加 comment
  - 可选地改回某个 mapped external status

但：

- review comments
- artifacts
- compare target
- acceptance checklist

仍建议以 AgentTeam 为主，因为这些更贴近 agent execution 语境。

## 13.12 推荐的 phased rollout

### Phase A：External link

先支持：

- Link Jira / ONES issue
- card 上显示 external ref + status
- task detail 可打开 provider 页面

这是最低成本、最容易落地的一步。

### Phase B：Mirror import

再支持：

- 从外部 backlog / search 导入 issue 成 AgentTeam card
- 保留 AgentTeam 本地 claim / review / artifacts
- 外部状态只做 snapshot 展示

### Phase C：Selective sync

再支持：

- 部分字段回写
- 状态 mapping
- comment / review summary 同步

### Phase D：Managed mode

最后才支持：

- 从 AgentTeam 创建外部 issue
- 更完整的双向字段同步

## 13.13 最终建议

如果要把“接 Jira / ONES”这件事做好，我建议最终定调为：

1. `AgentTeam task` 继续是执行与 review 的核心对象
2. `external issue` 通过 link/mirror/managed 三种模式接进来
3. provider integration 复用 installation + connection 思路
4. provider adapter 走稳定 contract，CLI 只是 transport，不是 domain contract
5. `ones-cli` 应封装进独立 provider runtime，而不是直接散落在 core hot path

这样做的最大好处是：

- 既不会把 AgentTeam task 变成 Jira 的廉价镜像
- 也不会让 AgentTeam 和外部项目管理系统完全割裂

这才比较像一个长期可维护的 task federation 方案。