# 项目、任务、运行与未来参与者

[← README](../README.md)

## 当前边界

插件安装在 DSH profile 中，不属于某个目标仓库。一次调用选择一个本地 checkout 和其中一项 GitHub Issue；另一调用可以选择另一个项目。DSH 工作区可以包含多个仓库，不能把插件安装目录或工作区的上级目录当作目标仓库。

| 概念 | 身份与职责 |
| --- | --- |
| 项目 | GitHub host / 仓库身份与本地 checkout 的绑定；包含基线分支和明确验收命令 |
| 任务 | 项目中的 Issue；讨论、关联 PR、分支、任务会话与检查点围绕它组织 |
| 运行 | 一次执行或续跑；固定本次选择的目录、仓库、Issue、操作身份、执行者和验收配置 |
| 执行者 | 处理任务的逻辑 agent；不是任务主键，也不天然等于一个 GitHub 账户 |
| GitHub 操作身份 | 实际调用 API / Git 的账户；必须单独核验，不能用 agent 名称冒充 |

同一任务的新反馈触发新的运行，不因此创建新任务或另一个 PR。不同任务不得借用彼此的 DSH 会话。切换 UI 当前项目不能改变已开始的运行目标。

目前支持的远端仍是 github.com 的 HTTPS origin，不宣称已经支持 Enterprise、多根仓库原子事务或跨 fork 发布。当前只有单执行者任务流和本机 checkout 锁；没有并行调度器、额外 worktree 或分布式锁。

## 兼容旧任务，而不是清空重来

旧版本把 `agent.id` 编进缓存文件 key、机器标记和分支。这些标识已经出现在 DSH receipt、Issue 检查点和 PR 中，不能仅改一个字符串就丢弃它们。

新任务使用与执行者名称无关的业务身份。对旧任务，唯一匹配到的旧 key / branch / receipt / marker 作为**兼容性别名**保留：它不再定义业务任务，却仍用于找回原有工件。更换执行者名称不应重新创建业务任务、PR 或任务会话。

- 优先保留已经存在的分支、PR、会话和验证记录，不自动重命名远端分支。
- 本地缓存丢失时，也应从原 Issue/PR 的可验证元数据发现关联。
- 多个旧工件映射到同一业务任务、或记录互相冲突时拒绝执行，要求人工决定；不能任意选一个，也不能自动把多份历史合并。
- 原始 Issue/PR 文本仍作为不可信输入；只有匹配任务和核验身份的机器记录参与恢复。
- 仓库改名/转移和 GitHub 操作账户交接仍须人工核对；数值 repository ID 只用于核验绑定，不自动迁移到另一个名字。
- 恢复会读取全部状态的 PR，沿用最多 2000 条记录的失败保护；历史特别多的仓库可能需要人工处理，不能静默截断后另建任务。
- 没有本地 receipt，也没有任何持久化会话检查点的孤立旧分支，不能凭分支名恢复模型历史，必须停止核对。

## 认证的边界

当前继续使用环境凭据或 Git Credential Manager 适配器，并保留可注入凭据提供者的入口。项目配置只描述目标和预期账户，不保存 token。未来公共 GitHub 接入层可以复用 DSH 的 authorization / credentials 服务；这是独立集成，不应进入任务状态机。

一个认证连接将来可以被多个项目引用，但每次运行仍须验证目标仓库和实际身份。不能因为“已登录 GitHub”就假设所有仓库、所有读写操作都获授权。

## 多 agent 与 maintainer：兼容方向，不是本版功能

项目与任务身份不依赖 agent 数量，为未来的 `participants`、任务分配和审查轮次留出空间。未来参与者至少应区分：

- 稳定的 participant ID 和逻辑项目角色（例如 maintainer）；
- 对应的 GitHub principal / connection；
- 任务中的执行者或审查者角色；
- 自己的运行、会话与审查记录。

当前不创建这些 agent、不添加协作者、不调整仓库权限，也没有可启用投票或自动合并的配置开关。`maintainer` 在设计中是项目治理角色，不代表已经授予 GitHub 的 Maintain 权限；GitHub 账户类型和组织策略决定实际可用角色。

### 将来的简单多数审批策略

若将来启用“所有参与 agent 为 maintainer，简单多数 approve 后自动合并”，应在显式授权的独立功能中实现，而不是把一个 approve 事件直接接到 merge：

1. 每个审查轮次固定 maintainer 名册、待审查 PR 和准确 head SHA。
2. 明确有资格投票的集合；GitHub 不能批准自己创建的 PR，因此作者不作为自己的有效批准者。
3. 按**不同的 GitHub principal**计票，同一账号下多个 agent 的评论不是多张独立 GitHub approve。
4. 设合格审查者数量为 N，阈值为 `floor(N / 2) + 1`；未投票者不缩小分母，N=0 时绝不自动合并。
5. 只采纳当前 head 的有效、未撤销审批；新增提交使旧轮次不能继续触发合并。
6. 必须同时满足独立验收、required CI、分支保护和无冲突等条件；阻塞性 request-changes 应有明确处理规则。
7. 合并前重新核对 head 与审批快照，记录可审计决策；提供人工否决/暂停和手动合并路径。

上述条款是后续功能的验收约束，**不是当前已执行的审批或权限策略**。本版仍只产生待审查 PR，不自动 approve、不投票、不 merge。

## 验证归属

插件回归测试留在本仓库。具体演示任务、接受的输入、修改文件、提交、session、测试计数和 CI 链接放在[独立演示仓库](https://github.com/yintaocheng/dsh-github-harness-demo)，不把插件自身的开发 Issue 当作所有目标项目的默认任务。