This commit is contained in:
QiuSW
@@ -0,0 +1,119 @@
|
||||
# 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`](../gitea.env.example) 复制一份到 `$HOME/.codex/gitea.env`，替换示例值。也可用 `GITEA_ENV_FILE` 指向其他本机私有路径：
|
||||
|
||||
```text
|
||||
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`](../scripts/gitea-mcp.ps1) 到稳定的本机路径，然后在全局 `~/.codex/config.toml` 或可信项目的 `.codex/config.toml` 注册：
|
||||
|
||||
```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：
|
||||
|
||||
```powershell
|
||||
./scripts/gitea-mcp.ps1 -CheckConfig
|
||||
```
|
||||
|
||||
连接预检：
|
||||
|
||||
```powershell
|
||||
./scripts/gitea-mcp.ps1 doctor
|
||||
```
|
||||
|
||||
预检至少确认：实例可达、Token 有效、当前用户正确、MCP 版本固定。失败时查看系统临时目录中的 `gitea-mcp-<PID>.stderr.log`；日志不得复制 Token 或敏感正文。
|
||||
|
||||
## 降级规则
|
||||
|
||||
- Gitea / MCP 不可用：允许继续已领取任务的本地工作，不允许领取新任务或猜测远端状态。
|
||||
- 恢复连接后：先拉取默认分支并重新读取任务 Issue，再提交或更新状态。
|
||||
- MCP 读取结果与本地 checkout 冲突：以明确记录的提交 SHA 为比较基准，不静默覆盖本地未提交改动。
|
||||
|
||||
## 按需读取
|
||||
|
||||
启用 [`agent-context.json`](agent-context.json) 后，agent 不用通过 MCP 全量读取 `docs/`：
|
||||
|
||||
1. 获取默认分支头 SHA 作为 `context_ref`。
|
||||
2. 读取清单和 `bootstrap.always_read`。
|
||||
3. 按本轮任务类型读取对应 `routes`。
|
||||
4. 保存 `read_file` 返回的文件 SHA；同一会话内 SHA 未变化时复用内容。
|
||||
|
||||
Gitea 中的文件与本地 `docs/` 是同一 Git 工件的远端与 checkout，不要再创建第三份人工同步副本。
|
||||
|
||||
## Issue / PR 协调
|
||||
|
||||
多 agent 协作时遵循 [`gitea-collaboration.md`](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 opc/yovision --apply` 幂等初始化；过期 claim 由维护者通过 UI 或受控 REST 人工回收。
|
||||
|
||||
## 治理检查
|
||||
|
||||
离线检查不需要 Token，可放进 Gitea Actions：
|
||||
|
||||
```powershell
|
||||
python -m unittest discover -s tests -p "test_*.py"
|
||||
python scripts/validate_harness_governance.py
|
||||
```
|
||||
|
||||
远端一致性检查单独运行，严格只读：
|
||||
|
||||
```powershell
|
||||
python scripts/audit_gitea_coordination.py --repo opc/yovision --dispatcher ila
|
||||
```
|
||||
|
||||
远端审计区分“不一致”（退出码 1）和配置 / 网络 / 权限失败（退出码 2），并验证 dispatcher 评论身份、任务依赖和过期 claim；`--dispatcher` 可由非敏感环境变量 `GITEA_DISPATCHER_LOGIN` 代替。它不会更新标签、关闭 Issue、合并 PR 或删除分支。
|
||||
Reference in New Issue
Block a user