opc/soft_quay

Fork 0

Files

T

ilaandClaude Fable 5 0184595ccc

Harness governance / validate (push) Has been cancelled

Details

Add harness coding docs for SoftBox (Go + Gio dual-build)

Initialize the full harness coding document set from the
harness_coding_docs template, customized for the SoftBox project:

- Vision, requirements, tech stack (modern Go 1.25 + Gio v0.10.1;
  Win7 legacy Go 1.20.14 + Gio v0.6.0), architecture, coding rules
- Protocol contracts (signed catalog, package protocol v1, Ed25519
  license, events, CLI) and Gio view structure
- Roadmap Phase 0-6 with 20 suggested tasks; T-001 (monorepo
  skeleton) filed and ready to claim
- Agent entry points (AGENTS.md, docs/00-ai-start-here.md),
  context manifest, governance scripts and tests
- Merge Go gitignore with harness rules; keep go.work tracked

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-16 14:33:54 +08:00

5.3 KiB

Raw Blame History

Gitea MCP 接入

可选增强：让 agent 通过 Gitea 读取共享文档、Issue、分支和 PR。Git checkout 仍是本地编辑与离线降级入口，MCP 不取代 Git。

适用边界

Gitea Git 仓库保存版本化文档和代码。
Gitea Issue / PR 保存实时协调状态。
Gitea MCP 提供受控的远端读取和写入工具。
AGENTS.md、docs/00-ai-start-here.md 等最小启动文件仍保留在项目 checkout 中。

私有配置

从根目录 gitea.env.example 复制一份到 $HOME/.codex/gitea.env，替换示例值。也可用 GITEA_ENV_FILE 指向其他本机私有路径：

GITEA_URL=【Gitea 实例根地址，不含 /api/v1】
GITEA_TOKEN=【最小权限 Personal Access Token】

# 启用远端协调审计时设置；不是秘密：
GITEA_DISPATCHER_LOGIN=【唯一 dispatcher 的 Gitea 登录名】

# 仅当团队明确接受 HTTP 下 Token 明文传输风险时设置：
GITEA_ALLOW_INSECURE_HTTP=1

# 仅当该实例必须绕过本机代理直连时设置：
GITEA_DIRECT=1

规则：

不把 gitea.env、Token、Authorization header、私有实例地址提交到仓库或粘贴到 Issue。
Token 一旦出现在聊天、日志或提交历史中，立即撤销并轮换。
推荐 HTTPS；如果项目长期使用 HTTP，必须在项目安全决策中记录风险接受人、网络边界和轮换策略。
GITEA_URL 填实例根地址；gitea-mcp 会自动追加 /api/v1。

Codex 配置

复制 ../scripts/gitea-mcp.ps1 到稳定的本机路径，然后在全局 ~/.codex/config.toml 或可信项目的 .codex/config.toml 注册：

[mcp_servers.gitea]
command = "pwsh.exe"
args = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "【gitea-mcp.ps1 的绝对路径】"]
default_tools_approval_mode = "writes"
startup_timeout_sec = 30
tool_timeout_sec = 60

包装脚本固定使用 gitea-mcp==0.5.1，避免 uvx 自动升级造成协议或工具集合漂移。升级版本时先在独立分支验证 initialize、tools/list 和一条只读 API，再更新版本号。

工具审批

默认策略：

自动允许只读：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。
破坏性动作再次确认：merge_pr、关闭 Issue、覆盖文件、批量操作。

如果 Codex 版本支持 enabled_tools / disabled_tools，应再用 allowlist 收窄工具，而不是只依靠提示词。

本地验证

只检查文件格式，不连接 Gitea、不显示 Token：

./scripts/gitea-mcp.ps1 -CheckConfig

连接预检：

./scripts/gitea-mcp.ps1 doctor

预检至少确认：实例可达、Token 有效、当前用户正确、MCP 版本固定。失败时查看系统临时目录中的 gitea-mcp-<PID>.stderr.log；日志不得复制 Token 或敏感正文。

降级规则

Gitea / MCP 不可用：允许继续已领取任务的本地工作，不允许领取新任务或猜测远端状态。
恢复连接后：先拉取默认分支并重新读取任务 Issue，再提交或更新状态。
MCP 读取结果与本地 checkout 冲突：以明确记录的提交 SHA 为比较基准，不静默覆盖本地未提交改动。

按需读取

启用 agent-context.json 后，agent 不用通过 MCP 全量读取 docs/：

获取默认分支头 SHA 作为 context_ref。
读取清单和 bootstrap.always_read。
按本轮任务类型读取对应 routes。
保存 read_file 返回的文件 SHA；同一会话内 SHA 未变化时复用内容。

Gitea 中的文件与本地 docs/ 是同一 Git 工件的远端与 checkout，不要再创建第三份人工同步副本。

Issue / PR 协调

多 agent 协作时遵循 gitea-collaboration.md：

任务文件保存规格和长期证据，Issue 保存实时状态，PR 保存评审与合并决策。
领取互斥依赖 dispatcher 串行分配；claims/T-<编号> 是防御性标记，assignee、status/doing 和读回仅作状态确认。
MVP 由单一 dispatcher 串行分配任务并检查 write_paths，每个 worker 使用 agent/<agent-id>/T-<编号> 和独立 worktree；每任务 claim 只解决同任务重复领取，不单独保证跨任务路径互斥。
MCP 可创建 claim / 工作分支，但当前没有创建标签或删除分支工具。标签用 python scripts/setup_gitea_labels.py --repo 【owner/repo】 --apply 幂等初始化；过期 claim 由维护者通过 UI 或受控 REST 人工回收。

治理检查

离线检查不需要 Token，可放进 Gitea Actions：

python -m unittest discover -s tests -p "test_*.py"
python scripts/validate_harness_governance.py

远端一致性检查单独运行，严格只读：

python scripts/audit_gitea_coordination.py --repo 【owner/repo】 --dispatcher 【Gitea登录名】

远端审计区分“不一致”（退出码 1）和配置 / 网络 / 权限失败（退出码 2），并验证 dispatcher 评论身份、任务依赖和过期 claim；--dispatcher 可由非敏感环境变量 GITEA_DISPATCHER_LOGIN 代替。它不会更新标签、关闭 Issue、合并 PR 或删除分支。

5.3 KiB Raw Blame History Unescape Escape