# 功能与配置层级

Forge 不依赖编码 Agent 或外部插件也能使用。先完成核心工作流，再按实际任务启用集成能力。

## 核心功能

默认本地配置包含：

- 用稳定 `repoId`、`checkoutId` 注册和选择仓库；
- 有边界的仓库读取与上下文聚合；
- 五个首选 ChatGPT facade：`rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work`，以及固定、可修复的默认 MCP 工具面；
- Direct Edit：路径限制、SHA 前置条件、多 revision、savepoint、diff、检查和回滚；
- 可恢复的 Issue → Task → Run 状态与执行证据；
- 命名检查，而不是向远端开放任意 shell；
- 本地 Controller UI 和追加式活动/证据记录；
- Controller Home 运行态隔离；
- 多仓库显式路由；
- 发布门禁、tracked-file 卫生检查和公共导出。

## 可选能力

| 集成 | 增加的能力 | 需要的环境 |
| --- | --- | --- |
| Codex / Claude | 处理超出 Direct Edit 范围的复杂实现 | 安装并登录对应 CLI，显式开启 dev runner。 |
| GitHub | Issue/Project 同步、PR、云端 Agent | 已认证的 `gh` 和仓库权限。 |
| Tailscale / Cloudflare | 为 ChatGPT MCP 提供稳定 HTTPS 地址 | 隧道客户端及对应账号/域名。 |
| Browser | Playwright 浏览、截图和证据 | 浏览器 binary 与允许访问的域名。 |
| CodeGraph | 代码关系和影响范围导航 | CodeGraph CLI；Windows 原生暂不自动配置。 |
| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。OAuth Client ID 是非秘密受管配置；refresh token 与导入的 client secret 保存到平台凭据存储。Forge 在凭据存储存在 `client_secret` 时发送它，否则尝试 public-client/PKCE 路径；具体 OAuth client 是否强制要求 secret，以实时 provider 响应为准。仅保存了 refresh token 或配置了尚未验证的 access token，不等于 Gmail 已可用；只有实际 provider 调用成功才标记 live-ready。若 Google 返回 `invalid_request: client_secret is missing`，优先将与当前 OAuth Client ID 匹配的密钥恢复到 macOS Keychain；若旧密钥无法找回，则在唯一受管配置中改用专用 OAuth Client ID，将对应密钥存入 Keychain，再重新授权。不同 OAuth client 之间不能复用原 refresh token。macOS Keychain 是唯一凭据权威，不得跨进程长期缓存 refresh token 或 client secret；受管 OAuth Client ID 修改后，应重启同版本运行进程以重新载入环境配置，无需切换 Runtime 版本。 |
| Schedule / Finding | 受监督的周期检查和候选发现 | Canonical Forge Runtime 持续运行，真实动作仍受策略控制。 |

## 工具暴露

默认 `advanced` 暴露固定、可修复且不超过 128 个工具的 schema；`core` 是同一 schema 的兼容别名。`full` 会暴露全部历史定义，只用于旧集成或深度兼容诊断。五个工作流 facade 位于强类型原子工具和内部 handler 之上，capability 元数据按领域对现有能力分组。当前 MCP transport 尚不支持会话内动态加载领域 schema，因此分组不会删除或隐藏这些强类型工具。

## 如何选择执行方式

- 小而明确的修改优先 Direct Edit。
- 需要跨会话、存在依赖或需要正式证据时使用持久 Task。
- 只有调查或实现范围确实较大时才委派 Agent。
- 接受结果前运行命名检查并审查 diff。

## 授权边界

读取和本地有界检查可以自动执行；仓库写入、破坏性清理、外部副作用、远程 Git、GitHub 变更、邮件动作和发布仍需策略授权。连接 ChatGPT 不代表获得任意 shell 或任意文件系统权限。