MVP 功能分析

[SATA260]

PR 工作台 Agent MVP 功能分析

1. 文档定位

这是 PR 工作台 Agent 第一个测试版本的功能总览，用于确认 MVP 要验证的核心价值、用户场景和产品边界。

本文只描述功能、用户故事和关键行为约束，不展开技术实现、接口设计、数据结构、页面细节或开发排期。每个功能后续应单独拆分为详细需求文档。

2. MVP 要验证的核心价值

用户可以在一个本地 Web 工作台中：

• 本地查看、刷新和链接当前项目的 GitHub Issue 与 PR。
• 以任务为中心，将多个 Issue、PR、Agent 会话、Worktree 和 Git 改动组织在一起。
• 在任务中使用自有 Agent、本机 Codex 或 Claude；各 Agent 保留原有提示词和规则，CodeDock 只追加项目与任务上下文。
• 使用独立 Git Worktree 并行开展任务，并清楚看到每个 Worktree 的路径、分支、修改和占用状态。
• 让 Agent 修改代码或生成 Issue/PR 草稿；代码变更进入 Git 暂存区，草稿保存为本机状态，由用户手动 Commit、Push 或确认发布到 GitHub。
• 用可视化界面或 Agent 执行常用 Git 操作，并在 Agent 需要审批、执行失败或完成时及时处理。

MVP 的重点不是让 Agent 自动完成全部研发工作，也不是替代 GitHub。MVP 要验证的是：用户是否愿意通过一个任务工作台组织、观察和接管多个 Agent 任务，同时始终保留对本地提交和远端发布的最终控制权。

3. 核心概念与范围

• 项目：一个本地 Git 项目及其 GitHub 远端映射；同一项目可以聚合多个 Worktree。
• 工作分组：看板上的任务分组。一个分组内包含多个任务和多个 Agent 会话。
• 任务：看板卡片和研发工作的聚合对象。一个任务可关联多个 Issue、PR、会话和一个活动 Worktree；其中可指定一个主 Issue 或主 PR。
• Worktree：实际可写的本地目录。界面必须展示其完整路径、分支、修改状态和当前占用者。
• 会话与运行：会话是一个 Agent 的长期对话容器；一次用户发起的 Agent 执行是一次运行。
• GitHub 资源链接：Issue 或 PR 的原始链接及其本地同步内容。用户在对话中粘贴 GitHub 链接时，可将其解析并关联到当前会话或任务。
• 项目级 .codedock/：位于项目根目录，仅保存可随仓库提交和团队共享的规则、模板、共享提示词与 Commit 约定。
• 本机级 .codedock/：位于用户本机数据目录，例如 ~/.codedock/projects/<project-id>/，保存不应提交到仓库的任务、会话、运行日志、GitHub 同步快照、审批、变更归属和草稿。
• 本机草稿：Agent 生成的 Issue 或 PR 标题、正文等内容，保存在本机级 .codedock/ 中，供用户预览、编辑和确认发布；草稿不是已发布的 GitHub 内容，也不进入 Git 暂存区。

4. MVP 功能范围

功能一：Agent 会话与项目上下文

核心功能

• 用户可以直接和产品自有 Agent 对话，也可以在任务中选择本机 Codex 或 Claude。
• Agent 根据用户授权读取项目文件、Git 状态、任务信息和已同步的 GitHub 资源。
• Agent 可以查找信息、解释代码、理解当前项目状态、生成计划、分析 Issue 和 Review PR。
• 对话可以独立存在，也可以归属到一个任务；任务内允许存在多个不同 Agent 的会话。
• 用户可将预置提示词加入任意 Agent 的任务上下文；不得覆盖 Codex、Claude 或项目已有的系统提示词和规则文件。
• Agent 在启动时得到项目路径、Worktree 路径、关联资源、团队规范和用户补充组成的可预览上下文。

用户故事

用户发现一个模块的行为不明确，希望快速了解相关代码。他打开自有 Agent，询问“登录失败的错误处理在哪”，并粘贴一个相关 Issue 链接。Agent 搜索项目和已同步的 Issue 内容后给出文件位置、相关代码和判断依据。用户随后将这次对话加入一个任务，交给 Codex 继续修改。

MVP 边界

MVP 支持查询、计划、Review 和受控编码。Agent 不能绕过用户审批执行 Commit、Push、合并受保护分支或发布 GitHub 内容。

功能二：GitHub Issue、PR 与可链接上下文

核心功能

• 用户可以在本地工作台查看当前项目的 GitHub Issue、PR 列表、详情、评论和基本改动信息。
• 每条 Issue、PR 保留原始链接、状态、作者、标签、更新时间和最近同步时间；用户可以手动刷新远端内容。
• 用户可以从 Issue、PR 创建任务，也可以创建空任务后关联多个 Issue 和 PR，并指定一个主资源。
• 用户在 Agent 对话中粘贴 GitHub Issue 或 PR 链接时，系统识别链接并允许其关联到当前会话或任务。
• 任务启动 Agent 时，用户可以选择哪些关联资源进入本次上下文，避免自动加载所有远端内容。
• 用户可以让 Agent 基于 Issue、PR 和当前 Diff 生成计划、Review 结论、Issue 草稿或 PR 草稿。

用户故事

用户在本地工作台打开一个待处理 Issue，同时关联一个已存在的 PR 和一个依赖 Issue。他补充“先补测试，不要修改登录接口”，确认这三项远端内容进入任务上下文后，启动 Codex。用户无需在浏览器、终端和多个 Agent 窗口间复制内容。

MVP 边界

GitHub 内容在本地以最近一次同步结果展示，不能被视为实时事实。MVP 不允许 Agent 直接修改、关闭或发布远端 Issue、PR 和 Review；所有远端写入必须先生成本机草稿，再由用户确认发布。

功能三：任务看板、多 Agent 与状态处理

核心功能

• 看板由工作分组和任务卡片组成；一个分组可统一查看和处理多个任务、会话与待审批事项。
• 一个任务卡片可关联多个 GitHub 资源、多个会话、一个活动 Worktree、Agent 结果、测试结果和 Git 改动。
• 会话可以来自自有 Agent、Codex、Claude 或后续扩展的 Agent；卡片展示 Agent 类型、当前阶段、开始时间、修改范围和结果摘要。
• 用户可以在任务或分组中发起会话、暂停、继续、取消、接管或处理多个待审批请求。
• 任务卡片显示待处理、运行中、等待确认、需要提权、成功、失败和已取消等状态，并在重要状态变化时发送本机系统通知。
• 用户可以进入任务详情查看 Agent 过程、工具调用、Diff、测试结果、审批原因和后续操作。

用户故事

用户同时处理三个任务：让自有 Agent 分析方案，让 Codex 修改代码，让 Claude 检查测试。三个任务分别绑定不同 Worktree。用户通过一个工作分组看到谁正在修改、谁等待确认、哪些改动已暂存，并一次处理多个审批请求。

MVP 边界

MVP 验证任务、会话、审批和状态的关联关系，不要求解决复杂的跨任务依赖、团队成员协作、资源调度或自动任务分配。

功能四：Agent 受控修改与暂存变更

核心功能

• 用户从任务卡片选择 Agent 和 Worktree 后启动编码任务；Agent 使用已确认的任务上下文开展工作。
• Agent 可以按授予权限修改项目文件、运行测试和执行受控 Git 操作；用户可以实时查看过程、修改结果和测试结果。
• Agent 完成修改后，只将本次运行产生且可归属的文件变更加入该 Worktree 的 Git 暂存区。
• 任务详情展示未暂存和已暂存 Diff、涉及文件、测试结果与 Agent 修改摘要；用户可以取消暂存、编辑后重新暂存或拆分提交内容。
• 用户可以在 Git 工作台根据已暂存 Diff、关联 Issue 和 .codedock 规范生成 Commit Message 草稿。
• Agent 不得自动 Commit、Push、创建远端分支或发布 Issue、PR；这些操作由用户在明确确认后手动执行。

用户故事

用户确认任务上下文后，让 Codex 在一个功能 Worktree 中补测试并修复错误。Codex 完成后，修改文件已在暂存区，用户查看 Diff，取消一处不需要的变更，点击生成 Commit Message，编辑后手动 Commit 和 Push。

MVP 边界

暂存只针对本次 Agent 可归属的文件，不能等同于全量 git add，也不能将用户原有或其他任务产生的改动自动加入暂存区。Agent 对有风险的命令和扩展权限仍须等待用户审批。

功能五：Git 工作台（Worktree 与可视化操作）

核心功能

• 用户可以在同一项目中查看已有 Worktree、分支、完整路径、文件变更、暂存区、提交历史、远程状态和关联任务。
• 用户可以一键创建、选择、切换和安全清理 Worktree，并将其绑定到任务；项目下的 Worktree 在同一面板聚合展示。
• 启动写入型 Agent 时，系统检查 Worktree 占用。若已有写入型会话正在处理同一路径，提示用户继续已有会话、以只读方式启动，或创建新的 Worktree。
• 用户可通过界面或授权 Agent 完成暂存、取消暂存、Commit、分支切换、Pull、Push、Merge、Rebase 等常用 Git 操作。
• 系统展示操作影响、执行结果、失败原因和更新后的提交关系；对 Push、Merge、Rebase、Reset、删除分支和清理 Worktree 等操作要求确认。
• 任务卡片保留相关 Git 操作记录，用户可以回到任务理解某次改动、提交或失败的来源。

用户故事

用户准备让第二个 Agent 处理另一项需求。系统发现当前目录已有 Codex 正在写入，提示创建新 Worktree。用户创建后，两个任务在不同路径和分支中并行。完成后，他在 Git 工作台查看各自的暂存 Diff、生成 Commit Message、手动 Commit，再按确认的目标分支 Push。

MVP 边界

MVP 提供常用 Git 操作、清晰反馈和提交关系可视化，不自动解决冲突、不自动合并到受保护分支。Merge 与 Rebase 的动画演示、冲突预测和复杂资源冲突分析不纳入 MVP。

功能六：团队规范、草稿与显式发布

核心功能

• 项目级 .codedock/ 可维护团队共享的 Commit 提示词、Issue/PR 模板、提示词预置和规则配置，并随仓库版本化。
• 本机级 .codedock/ 保存用户私有的提示词预置、任务、会话、同步快照、审批、运行记录和草稿，按项目隔离但不写入项目目录。
• 系统兼容读取 AGENTS.md、CLAUDE.md 和 .github/ 模板；项目级 .codedock/ 中的规则作为补充上下文和检查依据。
• 用户可一键生成 Issue 草稿和 PR 草稿，并在本地预览、编辑和保存；Commit Message 生成由 Git 工作台提供。
• Issue/PR 草稿保存在本机级 .codedock/ 中，不进入 Git 暂存区；用户在确认目标仓库、源分支和目标分支后调用 GitHub CLI 发布。
• 创建 PR 时，用户必须确认目标仓库、源分支、目标分支、标题和正文；Agent 只能提出建议，不能替用户确定发布目标。

用户故事

用户完成一个任务后，Git 工作台根据已暂存 Diff、主 Issue 和团队规范生成 Commit Message，GitHub 集成根据模板生成 PR 草稿并保存到本机数据目录。用户编辑草稿，确认源分支和目标分支无误后，点击发布 PR，并由 GitHub CLI 执行远端创建。

MVP 边界

项目级 .codedock/ 与本机级 .codedock/ 是两个独立位置：前者只保存可共享配置，后者只保存用户本机状态。Git 暂存与 GitHub 远端发布也是两个独立步骤；Issue/PR 草稿不进入 Git 暂存区，发布远端内容不应在没有用户确认的情况下发生。令牌、模型账号和用户授权应使用系统密钥链或等价安全存储，不写入任一 .codedock/ 目录。

5. MVP 核心使用流程

打开项目并同步 GitHub Issue / PR
  -> 从 Issue / PR 创建任务，或在任务中关联多个 GitHub 链接
  -> 补充并确认本次 Agent 上下文
  -> 创建或选择未被写入型会话占用的 Worktree
  -> 启动 Codex、Claude 或自有 Agent 会话
  -> 在任务看板中观察运行、测试和审批状态
  -> 查看 Agent 产生并已暂存的 Diff
  -> 生成并确认 Commit Message，手动 Commit / Push
  -> 预览本地 Issue / PR 草稿，确认后手动发布 GitHub

自有 Agent 可以在流程的任何阶段参与：用户可以先用它理解 Issue，也可以用它生成计划、解释其他 Agent 的修改结果、Review PR 或解释当前 Git 状态。

6. MVP 成功判断

通过一次完整演示和试用，确认以下问题：

• 用户能否在不打开多个终端和网页的情况下查看、链接和引用多个 GitHub Issue、PR。
• 用户能否理解一个任务关联了哪些 GitHub 资源、会话、Worktree、Agent 改动和测试结果。
• 用户是否愿意从 GitHub 内容或对话链接启动任务，而不是手动复制任务描述。
• 用户能否在一个工作分组中管理多个 Agent 会话并及时处理审批、失败和完成提示。
• Worktree 占用提示和创建流程是否能明显降低并行 Agent 之间的目录干扰。
• Agent 修改是否只进入可追溯的暂存区，并让用户保留 Commit、Push 和远端发布的最终决定权。
• 团队是否能通过项目级 .codedock/ 的模板和提示词获得一致的 Commit、Issue 和 PR 产出，同时不把本机任务和草稿提交进仓库。
• 新手是否能借助 Git 工作台完成一次查看 Diff、暂存、Commit、Push 或创建 PR 的流程。