opc/harness_coding_docs
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

设计并落地基于 Gitea 的 Harness Coding 多 Agent 共享上下文与任务协作 #1

New Issue
Open
opened 2026-07-14 11:41:48 +08:00 by ila · 1 comment
ila commented 2026-07-14 11:41:48 +08:00
Owner
Copy Link
Copy Source

背景与问题

后续 harness coding 会采用多 Agent 并行工作。当前入口规则、技术约束、架构、任务和状态文档由每个 Agent 从本地反复读取，主要问题不是“文件在本地”，而是缺少统一的远端事实源、按需读取索引和并发领取协议：

  • 不同 Agent 可能基于不同提交或未提交文件工作，形成上下文漂移。
  • 每轮全量读取文档浪费上下文，且无法判断哪些文档与当前任务相关。
  • 任务规格、领取状态、执行记录和当前快照容易重复维护或互相覆盖。
  • 直接把所有入口文档移出本地会让 Agent 在 Gitea/MCP 不可用时无法启动。
  • Gitea Issue、仓库文档和本地工作区如果都维护同一份状态，会产生新的双写冲突。

方案结论

采用“四层事实源 + MCP 访问层”架构：

本地工作区是可编辑执行缓存；Gitea Git 仓库是版本化共享事实源；Gitea Issue/PR 是实时协调面；Gitea MCP 是 Agent 的受控访问适配层。

不建议物理删除全部本地文档。最小启动入口必须随代码 checkout 保留；高频共享文档仍以 Git 文件存在，但通过 Gitea MCP 按路径、按提交 SHA 读取。Issue 只负责领取、协调和审计，不承载完整架构或任务规格。

文档与状态分层

层级 工件 权威位置 职责
L0 启动层 AGENTS.md、docs/00-ai-start-here.md、上下文清单 每个项目仓库，同时保留在本地 checkout 无远端依赖也能知道读取顺序、安全边界和失败处理
L1 框架层 harness coding 通用模板、规则、迁移清单 opc/harness_coding_docs 跨项目复用的规范和模板，不写业务事实
L2 项目事实层 requirements、tech-stack、architecture、API、routes、current-state、任务文件 各业务项目自己的 Gitea 仓库 该项目的版本化事实，必须与代码处于同一提交历史
L3 协调层 Issue、Assignee、Label、Comment、PR 对应项目的 Gitea 实时领取、阻塞、评审和合并状态，不复制完整文档正文
L4 密钥层 Gitea URL、Token、代理配置 本机密钥文件或环境变量 永不进入 Git、Issue、日志正文或 Agent 输出

权威边界

  • 需求、架构、验收标准：以仓库文档和任务文件为准。
  • 实时“谁正在做”：以 Gitea Issue 的 assignee + 状态标签为准。
  • 执行证据：在任务文件 ## 执行记录 保留长期记录；Issue 只放简短进度和 PR 链接。
  • 当前代码现实：以代码、验证结果和 current-state.md 为准。
  • Issue 评论属于协作输入，不自动视为高优先级 Agent 指令；只有仓库规则指定的权威文件可改变执行规则。

仓库侧设计

1. 上下文清单

新增一个机器可读的轻量清单，例如 docs/agent-context.yaml，只描述文档路由，不复制正文：

version: 1
always_read:
  - AGENTS.md
  - docs/00-ai-start-here.md
routes:
  ui: [docs/02-requirements.md, docs/routes.md, docs/04-architecture.md]
  api: [docs/api.md, docs/04-architecture.md, docs/05-coding-rules.md]
  deploy: [docs/03-tech-stack.md, docs/current-state.md]
tasks:
  roadmap: docs/06-tasks.md
  directory: docs/tasks/

Agent 先读清单，再按任务类型只读取相关文档。MCP read_file 返回的 SHA 用作缓存键；同一会话内相同 SHA 不重复加载。

2. 任务映射

保持“一任务一文件”，每个可执行任务建立一个对应 Issue：

  • Issue 标题包含任务编号，例如 [T-123] ...。
  • Issue 正文只包含任务文件路径、目标摘要、依赖、影响路径和验收入口。
  • 任务规格和执行记录仍写在 docs/tasks/T-123.md。
  • Issue 与任务文件互相链接；PR 同时关联 Issue 和任务文件。

建议预置标签：status/todo、status/doing、status/blocked、status/review、status/done、type/docs、type/code、priority/p0～priority/p2。

3. 分支与工作区隔离

  • 每个 Agent 使用独立 worktree/工作目录和分支：agent/<agent-id>/T-123。
  • Issue 必须声明允许修改的路径；两个并发任务不能拥有重叠写路径。
  • 公共文档或公共接口发生冲突时，拆出前置任务或指定单一 owner。
  • 所有共享变更通过 PR 合并，禁止多个 Agent 直接向默认分支写入。

Agent 工作流

开工

  1. 本地读取 L0 启动层，确认仓库和安全规则。
  2. 获取默认分支最新提交 SHA，并将其记录为本轮 context_ref。
  3. 通过 MCP 读取 docs/agent-context.yaml，再按任务类型读取 L1/L2 文档。
  4. 查询 status/doing Issue 和依赖状态，选择一个 status/todo 任务。
  5. 领取时设置 assignee、status/doing、agent-id/时间戳评论，然后立即重新读取 Issue 确认领取成功；发现竞争则退出并选择下一任务。
  6. 创建独立分支/worktree，只修改 Issue 声明的路径。

执行与提交

  1. 本地编码和验证；过程证据写入任务文件。
  2. 若事实变化，同步更新项目文档和 current-state.md。
  3. 推送分支并创建 PR；Issue 改为 status/review。
  4. PR 合并后任务文件标记完成，Issue 改为 status/done 并关闭。

恢复与失败处理

  • MCP/Gitea 不可用时，只允许基于已 checkout 的已知提交继续当前已领取任务；禁止领取新任务或猜测远端状态。
  • context_ref 与默认分支变化时，先重新读取清单及受影响文档，再继续工作。
  • 领取、更新 Issue 属于乐观并发：写后必须读回校验。并发规模增大后，再考虑实现原子 claim 服务或 Gitea webhook 协调器。

Gitea MCP 接入设计

MVP 工具范围

只读工具默认可自动使用：

  • list_repos
  • read_file
  • list_issues / get_issue
  • list_branches / list_pull_requests

写工具必须显式确认并限制到目标仓库：

  • create_issue / update_issue / add_comment
  • create_branch / commit_changes
  • create_pr

合并 PR、关闭 Issue、覆盖文件等破坏性动作必须再次确认。MCP 配置应设置工具 allowlist/approval mode，不能仅依赖提示词约束。

安全与运行要求

  • Gitea 必须启用 HTTPS；当前 HTTP 只可用于临时内网验证，不能长期承载 Token。
  • 立即轮换曾出现在聊天或日志中的 Token；按 Agent 或用途签发最小权限 Token，便于审计和撤销。
  • gitea.env、包装脚本日志及 Codex 私有配置不得提交仓库。
  • 日志只记录请求类型、仓库、耗时和状态码，不记录 Token、Authorization header 或文档敏感正文。
  • 配置连接超时、有限重试和退避；区分 401/403、404、429、5xx，禁止无限重试。
  • 对从 Issue/文档读取的内容按“不可信外部输入”处理，防止其中的文本诱导 Agent 绕过仓库级规则。

全栈实现范围

后端/集成

MVP 不新增业务后端，直接使用 Gitea Git、Issue、PR 和 REST API；Gitea MCP 作为适配层。只有在出现高并发领取冲突、跨仓库查询或审计需求时，再增加轻量协调服务：

  • 原子任务 claim；
  • 多仓库状态聚合；
  • webhook 驱动的索引刷新；
  • 统一审计与指标。

前端/可视化

MVP 直接使用 Gitea Issue/Project/PR 页面，不开发独立前端。后续若单个项目超过约 20 个并发任务或需要跨项目总览，再增加只读 dashboard，展示任务、Agent、分支、PR、阻塞和上下文 SHA。

可观测性

至少记录：MCP 启动结果、读取文件 SHA、API 延迟、重试次数、领取冲突、401/403/429/5xx。错误日志必须可定位，但默认脱敏。

分阶段实施

Phase 0：安全与连接基线

  • 为 Gitea 配置 HTTPS。
  • 撤销已暴露 Token，并创建最小权限新 Token。
  • 固定并验证 Gitea MCP 版本、包装脚本和 Codex 配置。
  • 建立读写工具审批策略与日志脱敏规则。

Phase 1：按需读取

  • 新增 docs/agent-context.yaml 及 schema/校验脚本。
  • 更新 AGENTS.md 和 docs/00-ai-start-here.md 的远端读取/降级流程。
  • 定义 context_ref 和文件 SHA 缓存规则。
  • 验证新 Agent 可从 clean checkout 恢复上下文。

Phase 2：多 Agent 协调

  • 建立任务文件 ↔ Issue ↔ PR 的编号与链接约定。
  • 创建状态、类型和优先级标签。
  • 实现领取后读回校验、独立 worktree/分支和写路径声明。
  • 用两个 Agent 并行执行两个不重叠的样例任务。

Phase 3：自动化与治理

  • 增加导航链接、上下文清单、敏感信息和任务状态一致性检查。
  • 增加过期 status/doing 检测与人工回收流程。
  • 评估 webhook/协调服务和跨项目 dashboard，确有需求再实现。

验收标准

  • 新 Agent 从 clean checkout 出发，只读 L0 + 清单路由的相关文档即可领取任务，不需要全量加载全部文档。
  • 同一轮使用统一 context_ref；文件 SHA 未变化时不重复获取正文。
  • 两个 Agent 能在独立 worktree/分支并行完成不重叠任务，Issue、任务文件和 PR 状态一致。
  • 两个 Agent 同时领取同一任务时，最多一个通过读回校验，另一个安全退出。
  • Gitea/MCP 中断时不会误领新任务或覆盖远端状态，本地已领取任务可按降级规则继续。
  • 框架模板保留在 opc/harness_coding_docs，业务项目事实留在各自仓库，没有跨项目复制导致的双重事实源。
  • MCP 只读操作可正常读取仓库、Issue 和指定文档；写操作均受审批策略约束。
  • 仓库、Issue、PR、日志中均不存在 Token、密码或 Authorization 信息。
  • 导航、任务文件、Issue、PR 和实际路径引用一致，并有自动检查结果作为证据。

非目标

  • 本阶段不开发独立任务管理前端。
  • 不把业务项目文档集中复制进 harness 模板仓库。
  • 不用 Issue 正文取代版本化的需求、架构和任务文件。
  • 不追求完全离线的跨 Agent 实时协调；离线仅支持继续已领取任务。
## 背景与问题 后续 harness coding 会采用多 Agent 并行工作。当前入口规则、技术约束、架构、任务和状态文档由每个 Agent 从本地反复读取，主要问题不是“文件在本地”，而是缺少统一的远端事实源、按需读取索引和并发领取协议： - 不同 Agent 可能基于不同提交或未提交文件工作，形成上下文漂移。 - 每轮全量读取文档浪费上下文，且无法判断哪些文档与当前任务相关。 - 任务规格、领取状态、执行记录和当前快照容易重复维护或互相覆盖。 - 直接把所有入口文档移出本地会让 Agent 在 Gitea/MCP 不可用时无法启动。 - Gitea Issue、仓库文档和本地工作区如果都维护同一份状态，会产生新的双写冲突。 ## 方案结论 采用“四层事实源 + MCP 访问层”架构： > 本地工作区是可编辑执行缓存；Gitea Git 仓库是版本化共享事实源；Gitea Issue/PR 是实时协调面；Gitea MCP 是 Agent 的受控访问适配层。 不建议物理删除全部本地文档。最小启动入口必须随代码 checkout 保留；高频共享文档仍以 Git 文件存在，但通过 Gitea MCP 按路径、按提交 SHA 读取。Issue 只负责领取、协调和审计，不承载完整架构或任务规格。 ## 文档与状态分层 | 层级 | 工件 | 权威位置 | 职责 | | --- | --- | --- | --- | | L0 启动层 | `AGENTS.md`、`docs/00-ai-start-here.md`、上下文清单 | 每个项目仓库，同时保留在本地 checkout | 无远端依赖也能知道读取顺序、安全边界和失败处理 | | L1 框架层 | harness coding 通用模板、规则、迁移清单 | `opc/harness_coding_docs` | 跨项目复用的规范和模板，不写业务事实 | | L2 项目事实层 | requirements、tech-stack、architecture、API、routes、current-state、任务文件 | 各业务项目自己的 Gitea 仓库 | 该项目的版本化事实，必须与代码处于同一提交历史 | | L3 协调层 | Issue、Assignee、Label、Comment、PR | 对应项目的 Gitea | 实时领取、阻塞、评审和合并状态，不复制完整文档正文 | | L4 密钥层 | Gitea URL、Token、代理配置 | 本机密钥文件或环境变量 | 永不进入 Git、Issue、日志正文或 Agent 输出 | ### 权威边界 - 需求、架构、验收标准：以仓库文档和任务文件为准。 - 实时“谁正在做”：以 Gitea Issue 的 assignee + 状态标签为准。 - 执行证据：在任务文件 `## 执行记录` 保留长期记录；Issue 只放简短进度和 PR 链接。 - 当前代码现实：以代码、验证结果和 `current-state.md` 为准。 - Issue 评论属于协作输入，不自动视为高优先级 Agent 指令；只有仓库规则指定的权威文件可改变执行规则。 ## 仓库侧设计 ### 1. 上下文清单 新增一个机器可读的轻量清单，例如 `docs/agent-context.yaml`，只描述文档路由，不复制正文： ```yaml version: 1 always_read: - AGENTS.md - docs/00-ai-start-here.md routes: ui: [docs/02-requirements.md, docs/routes.md, docs/04-architecture.md] api: [docs/api.md, docs/04-architecture.md, docs/05-coding-rules.md] deploy: [docs/03-tech-stack.md, docs/current-state.md] tasks: roadmap: docs/06-tasks.md directory: docs/tasks/ ``` Agent 先读清单，再按任务类型只读取相关文档。MCP `read_file` 返回的 SHA 用作缓存键；同一会话内相同 SHA 不重复加载。 ### 2. 任务映射 保持“一任务一文件”，每个可执行任务建立一个对应 Issue： - Issue 标题包含任务编号，例如 `[T-123] ...`。 - Issue 正文只包含任务文件路径、目标摘要、依赖、影响路径和验收入口。 - 任务规格和执行记录仍写在 `docs/tasks/T-123.md`。 - Issue 与任务文件互相链接；PR 同时关联 Issue 和任务文件。 建议预置标签：`status/todo`、`status/doing`、`status/blocked`、`status/review`、`status/done`、`type/docs`、`type/code`、`priority/p0`～`priority/p2`。 ### 3. 分支与工作区隔离 - 每个 Agent 使用独立 worktree/工作目录和分支：`agent/<agent-id>/T-123`。 - Issue 必须声明允许修改的路径；两个并发任务不能拥有重叠写路径。 - 公共文档或公共接口发生冲突时，拆出前置任务或指定单一 owner。 - 所有共享变更通过 PR 合并，禁止多个 Agent 直接向默认分支写入。 ## Agent 工作流 ### 开工 1. 本地读取 L0 启动层，确认仓库和安全规则。 2. 获取默认分支最新提交 SHA，并将其记录为本轮 `context_ref`。 3. 通过 MCP 读取 `docs/agent-context.yaml`，再按任务类型读取 L1/L2 文档。 4. 查询 `status/doing` Issue 和依赖状态，选择一个 `status/todo` 任务。 5. 领取时设置 assignee、`status/doing`、`agent-id`/时间戳评论，然后立即重新读取 Issue 确认领取成功；发现竞争则退出并选择下一任务。 6. 创建独立分支/worktree，只修改 Issue 声明的路径。 ### 执行与提交 1. 本地编码和验证；过程证据写入任务文件。 2. 若事实变化，同步更新项目文档和 `current-state.md`。 3. 推送分支并创建 PR；Issue 改为 `status/review`。 4. PR 合并后任务文件标记完成，Issue 改为 `status/done` 并关闭。 ### 恢复与失败处理 - MCP/Gitea 不可用时，只允许基于已 checkout 的已知提交继续当前已领取任务；禁止领取新任务或猜测远端状态。 - `context_ref` 与默认分支变化时，先重新读取清单及受影响文档，再继续工作。 - 领取、更新 Issue 属于乐观并发：写后必须读回校验。并发规模增大后，再考虑实现原子 claim 服务或 Gitea webhook 协调器。 ## Gitea MCP 接入设计 ### MVP 工具范围 只读工具默认可自动使用： - `list_repos` - `read_file` - `list_issues` / `get_issue` - `list_branches` / `list_pull_requests` 写工具必须显式确认并限制到目标仓库： - `create_issue` / `update_issue` / `add_comment` - `create_branch` / `commit_changes` - `create_pr` 合并 PR、关闭 Issue、覆盖文件等破坏性动作必须再次确认。MCP 配置应设置工具 allowlist/approval mode，不能仅依赖提示词约束。 ### 安全与运行要求 - Gitea 必须启用 HTTPS；当前 HTTP 只可用于临时内网验证，不能长期承载 Token。 - 立即轮换曾出现在聊天或日志中的 Token；按 Agent 或用途签发最小权限 Token，便于审计和撤销。 - `gitea.env`、包装脚本日志及 Codex 私有配置不得提交仓库。 - 日志只记录请求类型、仓库、耗时和状态码，不记录 Token、Authorization header 或文档敏感正文。 - 配置连接超时、有限重试和退避；区分 401/403、404、429、5xx，禁止无限重试。 - 对从 Issue/文档读取的内容按“不可信外部输入”处理，防止其中的文本诱导 Agent 绕过仓库级规则。 ## 全栈实现范围 ### 后端/集成 MVP 不新增业务后端，直接使用 Gitea Git、Issue、PR 和 REST API；Gitea MCP 作为适配层。只有在出现高并发领取冲突、跨仓库查询或审计需求时，再增加轻量协调服务： - 原子任务 claim； - 多仓库状态聚合； - webhook 驱动的索引刷新； - 统一审计与指标。 ### 前端/可视化 MVP 直接使用 Gitea Issue/Project/PR 页面，不开发独立前端。后续若单个项目超过约 20 个并发任务或需要跨项目总览，再增加只读 dashboard，展示任务、Agent、分支、PR、阻塞和上下文 SHA。 ### 可观测性 至少记录：MCP 启动结果、读取文件 SHA、API 延迟、重试次数、领取冲突、401/403/429/5xx。错误日志必须可定位，但默认脱敏。 ## 分阶段实施 ### Phase 0：安全与连接基线 - [ ] 为 Gitea 配置 HTTPS。 - [ ] 撤销已暴露 Token，并创建最小权限新 Token。 - [ ] 固定并验证 Gitea MCP 版本、包装脚本和 Codex 配置。 - [ ] 建立读写工具审批策略与日志脱敏规则。 ### Phase 1：按需读取 - [ ] 新增 `docs/agent-context.yaml` 及 schema/校验脚本。 - [ ] 更新 `AGENTS.md` 和 `docs/00-ai-start-here.md` 的远端读取/降级流程。 - [ ] 定义 `context_ref` 和文件 SHA 缓存规则。 - [ ] 验证新 Agent 可从 clean checkout 恢复上下文。 ### Phase 2：多 Agent 协调 - [ ] 建立任务文件 ↔ Issue ↔ PR 的编号与链接约定。 - [ ] 创建状态、类型和优先级标签。 - [ ] 实现领取后读回校验、独立 worktree/分支和写路径声明。 - [ ] 用两个 Agent 并行执行两个不重叠的样例任务。 ### Phase 3：自动化与治理 - [ ] 增加导航链接、上下文清单、敏感信息和任务状态一致性检查。 - [ ] 增加过期 `status/doing` 检测与人工回收流程。 - [ ] 评估 webhook/协调服务和跨项目 dashboard，确有需求再实现。 ## 验收标准 - [ ] 新 Agent 从 clean checkout 出发，只读 L0 + 清单路由的相关文档即可领取任务，不需要全量加载全部文档。 - [ ] 同一轮使用统一 `context_ref`；文件 SHA 未变化时不重复获取正文。 - [ ] 两个 Agent 能在独立 worktree/分支并行完成不重叠任务，Issue、任务文件和 PR 状态一致。 - [ ] 两个 Agent 同时领取同一任务时，最多一个通过读回校验，另一个安全退出。 - [ ] Gitea/MCP 中断时不会误领新任务或覆盖远端状态，本地已领取任务可按降级规则继续。 - [ ] 框架模板保留在 `opc/harness_coding_docs`，业务项目事实留在各自仓库，没有跨项目复制导致的双重事实源。 - [ ] MCP 只读操作可正常读取仓库、Issue 和指定文档；写操作均受审批策略约束。 - [ ] 仓库、Issue、PR、日志中均不存在 Token、密码或 Authorization 信息。 - [ ] 导航、任务文件、Issue、PR 和实际路径引用一致，并有自动检查结果作为证据。 ## 非目标 - 本阶段不开发独立任务管理前端。 - 不把业务项目文档集中复制进 harness 模板仓库。 - 不用 Issue 正文取代版本化的需求、架构和任务文件。 - 不追求完全离线的跨 Agent 实时协调；离线仅支持继续已领取任务。
ila changed title from �������ĵ�Ǩ���� Gitea��֧�� Harness Coding �� Agent ����Э�� to 将共享文档迁移至 Gitea，支持 Harness Coding 多 Agent 并行协作 2026-07-14 11:42:26 +08:00
ila changed title from 将共享文档迁移至 Gitea，支持 Harness Coding 多 Agent 并行协作 to 设计并落地基于 Gitea 的 Harness Coding 多 Agent 共享上下文与任务协作 2026-07-14 11:50:05 +08:00
ila commented 2026-07-14 13:08:14 +08:00
Author
Owner
Copy Link
Copy Source

Phase 0～3 落地结果（2026-07-14）

实现分支：feat/gitea-multi-agent-context

  • Phase 0 — 56fb3a7：Gitea MCP 安全与连接基线；固定 gitea-mcp==0.5.1，私有 env、直连 / NO_PROXY、显式 HTTP 风险开关与断连降级。
  • Phase 1 — 94ff8b7：增加 JSON 上下文清单、JSON Schema、任务路由式读取与零第三方依赖校验。
  • Phase 2 — 0a09dea：增加 Issue / 任务文件 / PR 映射、11 个 exclusive 协作标签、单 dispatcher 分配、claim / 工作分支和写路径协议。
  • Phase 3 — 1d3428a：增加离线治理、只读远端审计、竞态 smoke、Gitea Actions 工作流和 16 项标准库回归测试。

已确认的设计决策

  • 按当前项目决定继续使用 HTTP；Token 已轮换并只从本机私有配置读取。连接必须显式设置 GITEA_ALLOW_INSECURE_HTTP=1，仓库、Issue 和日志中不保存 Token。
  • 版本化文档仍保存在 Git 的 docs/ 中；Gitea 读取的是同一份 Git 工件，不维护第三份人工同步副本。
  • 上下文清单采用 JSON + JSON Schema，避免额外 YAML 依赖并使离线校验确定。
  • 并���互斥来自唯一 dispatcher 串行分配；claims/T-* 只是防御性标记，不宣称普通 create-branch API 是线性化锁。
  • CLAIM / RENEWAL 只接受配置的 dispatcher Gitea 账号发布，且会核对 allocated_by、依赖、租期、分支、PR、任务文件与写路径。

验证证据

  • python scripts/validate_agent_context.py：通过（6 个任务路由、20 个有效路径）。
  • python -m unittest discover -s tests -p "test_*.py"：16 项通过。
  • python scripts/validate_harness_governance.py：通过。
  • Python 编译、git diff --check、文件清单检查：通过。
  • 远端标签 dry-run：11 个标签全部 unchanged。
  • 远端协调只读审计：通过；当前 0 个 kind/task Issue。
  • 目标 Gitea 1.25.5 的并发 branch smoke 实际返回 201 + 500，而不是文档期望的 201 + 409；临时 probe 分支已安全清理。这进一步确认不能把 create-branch 当作原子锁。
  • Gitea Actions run #4 已由 Phase 3 push 创建，但当前为 queued，job 尚未分配 runner；因此目前只记录本地校验通过，不宣称 CI 已跑绿。

合并注意

该功能分支从本地 main（795a852）创建；创建时本地 main 已比 origin/main（7912113）多 6 个既有提交。因此当前分支相对 origin/main 不只包含本 Issue 的 4 个阶段提交，合并前需确认那 6 个既有提交是否也应进入远端主线。

## Phase 0～3 落地结果（2026-07-14） 实现分支：feat/gitea-multi-agent-context - Phase 0 — 56fb3a7：Gitea MCP 安全与连接基线；固定 gitea-mcp==0.5.1，私有 env、直连 / NO_PROXY、显式 HTTP 风险开关与断连降级。 - Phase 1 — 94ff8b7：增加 JSON 上下文清单、JSON Schema、任务路由式读取与零第三方依赖校验。 - Phase 2 — 0a09dea：增加 Issue / 任务文件 / PR 映射、11 个 exclusive 协作标签、单 dispatcher 分配、claim / 工作分支和写路径协议。 - Phase 3 — 1d3428a：增加离线治理、只读远端审计、竞态 smoke、Gitea Actions 工作流和 16 项标准库回归测试。 ### 已确认的设计决策 - 按当前项目决定继续使用 HTTP；Token 已轮换并只从本机私有配置读取。连接必须显式设置 GITEA_ALLOW_INSECURE_HTTP=1，仓库、Issue 和日志中不保存 Token。 - 版本化文档仍保存在 Git 的 docs/ 中；Gitea 读取的是同一份 Git 工件，不维护第三份人工同步副本。 - 上下文清单采用 JSON + JSON Schema，避免额外 YAML 依赖并使离线校验确定。 - 并���互斥来自唯一 dispatcher 串行分配；claims/T-* 只是防御性标记，不宣称普通 create-branch API 是线性化锁。 - CLAIM / RENEWAL 只接受配置的 dispatcher Gitea 账号发布，且会核对 allocated_by、依赖、租期、分支、PR、任务文件与写路径。 ### 验证证据 - python scripts/validate_agent_context.py：通过（6 个任务路由、20 个有效路径）。 - python -m unittest discover -s tests -p "test_*.py"：16 项通过。 - python scripts/validate_harness_governance.py：通过。 - Python 编译、git diff --check、文件清单检查：通过。 - 远端标签 dry-run：11 个标签全部 unchanged。 - 远端协调只读审计：通过；当前 0 个 kind/task Issue。 - 目标 Gitea 1.25.5 的并发 branch smoke 实际返回 201 + 500，而不是文档期望的 201 + 409；临时 probe 分支已安全清理。这进一步确认不能把 create-branch 当作原子锁。 - Gitea Actions run #4 已由 Phase 3 push 创建，但当前为 queued，job 尚未分配 runner；因此目前只记录本地校验通过，不宣称 CI 已跑绿。 ### 合并注意 该功能分支从本地 main（795a852）创建；创建时本地 main 已比 origin/main（7912113）多 6 个既有提交。因此当前分支相对 origin/main 不只包含本 Issue 的 4 个阶段提交，合并前需确认那 6 个既有提交是否也应进入远端主线。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
kind/task
Harness Coding task
priority
p0
Highest priority
priority
p1
High priority
priority
p2
Normal priority
status
blocked
Blocked; claim retained
status
doing
Claimed and in progress
status
done
Merged and completed
status
review
Pull request under review
status
todo
Ready to claim
type
code
Code or automation change
type
docs
Documentation change
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: opc/harness_coding_docs#1