Skip to content

fix(docs): 修 6 处指向不存在实体的文档硬伤——迁移文件名、ACP 审批链（Responder 在 edge-server 0 命中）、SDK 适配器注册事实（sdkAdapterIDs/IsSDKAdapter 0 命中）、run.error→run.failed、projectQueries 归属 Web，并把 known-flaky 自写的 300 行拆分阈值对齐门禁真实的 170（5 文件净 0 行） #2289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DeliciousBuding merged 3 commits into from
Sep 3, 2026
Merged

fix(docs): 修 6 处指向不存在实体的文档硬伤——迁移文件名、ACP 审批链（Responder 在 edge-server 0 命中）、SDK 适配器注册事实（sdkAdapterIDs/IsSDKAdapter 0 命中）、run.error→run.failed、projectQueries 归属 Web，并把 known-flaky 自写的 300 行拆分阈值对齐门禁真实的 170（5 文件净 0 行） #2289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b731184
fix(docs): 05-deployment 迁移死路径改为真实迁移文件（0062/0063 .up.sql）
DeliciousBuding Sep 3, 2026
80750e4
fix(docs): 修 3 处死实体引用——SDK 适配器注册事实、ACP 审批链、run.failed 事件名、projectQuer…
DeliciousBuding Sep 3, 2026
10541f2
fix(docs): known-flaky 行数预算 300→170 对齐 verify-doc-ssot 门禁
DeliciousBuding Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/architecture/03-runtime-adapters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ ACP 协议层**禁止手写 JSON-RPC loop**，必须用官方 Wrapper/适配层

- **协议边界**：100% 官方 adapter 二进制（claude-agent-acp / codex-acp / opencode 原生 ACP），Go runtime 用 `coder/acp-go-sdk` v0.13.5（Coder/Windsurf 厂维护，官方收录，从官方 schema 生成类型 + 自带 JSON-RPC 连接层）
- **runtime 共享层**：`acp/acp.go` `AcpAdapter`（SDK `acp.Client` 接口 9 方法自动分发）+ `acp/acp_events.go`（typed 映射 `acp.SessionUpdate` → `run.agent.*`）+ `acp/acp_client.go`（client skeleton）
- **审批链**：`request_permission` → `Responder` → `PermissionDecisionBroker`（复用既有 broker，零新协议）
- **审批链**：`session/request_permission` → `PermissionDecisionBroker`（`RequestPermission` 桥接，复用既有 broker，零新协议）
- **默认注册**：`claude-acp` / `codex-acp` / `opencode-acp` 默认注册（空 launcher 回退平台原生 `npx`/`opencode`）；`--agent-default` 与 `--runner-profile` 默认 cutover 到 `*-acp`。真跑验证需 `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` + npx registry 网络。进度与剩余项见 GitHub issues（ACP migration 跟踪）。

### CLI 执行模式
Expand All @@ -54,7 +54,7 @@ ACP 协议层**禁止手写 JSON-RPC loop**，必须用官方 Wrapper/适配层
- API key 通过环境变量注入（flag 值为 `env` 或空时从环境变量读取，否则直接使用 flag 值作为 key）
- 无外部 SDK 依赖，纯 `net/http`
- Key 缺失时 `Available=false`，不阻塞 Edge 启动
- 属于 `sdkAdapterIDs`，`IsSDKAdapter()` 返回 true
- 注册 ID 为 `anthropic-sdk` / `openai-sdk`，由 `cmd/agenthub-edge` 的 `registerSDKAdapters` 按 `--anthropic-sdk-path` / `--openai-sdk-path` 注册
- 重试机制：指数退避 + jitter（最大 3 次，1s/2s/4s (±25%)），匹配 `anthropic_sdk.go` 的 `doRequestWithRetry` 模式（v0.5.2+）

## Orchestrator Adapter
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/05-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ Hub 侧 code 交换端点固定为 `POST /client/auth/oidc/callback`，桌面/We
| `AGENTHUB_AUTH_FAIL_CLOSED` | 否（生产建议 `true`） | `AuthFailClosed()` | 见 §安全配置。 |
| `AGENTHUB_RATE_LIMIT_FAIL_OPEN` | 否（生产建议 `false`） | `RateLimitFailOpen()` | 见 §安全配置。 |

迁移自动执行意味着：升级到带新 `.up.sql` 的镜像时，容器一起新迁移。`hub-server/migrations/0062`、`0063` 等使用普通 `CREATE INDEX`/`CREATE UNIQUE INDEX`（非 `CONCURRENTLY`），在已堆积数据的表上会取 `ACCESS EXCLUSIVE` 锁；大表升级应在维护窗口执行（停服 → 跑迁移 → 起服），不要在流量高峰直接 `compose up`。详见 [../../CHANGELOG.md](../../CHANGELOG.md) v0.6.1 节的升级注意段。
迁移自动执行意味着：升级到带新 `.up.sql` 的镜像时，容器一起新迁移。`hub-server/migrations/` 下的 `0062_agent_team_runs_indexes.up.sql`、`0063_agent_run_events_unique_seq.up.sql` 使用普通 `CREATE INDEX`/`CREATE UNIQUE INDEX`（非 `CONCURRENTLY`），在已堆积数据的表上会取 `ACCESS EXCLUSIVE` 锁；大表升级应在维护窗口执行（停服 → 跑迁移 → 起服），不要在流量高峰直接 `compose up`。详见 [../../CHANGELOG.md](../../CHANGELOG.md) v0.6.1 节的升级注意段。

## 配置面索引（#2124 文档缺口补齐）

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/06-auth-identity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Desktop Tauri keyring/session
-> Hub REST API Authorization: Bearer <token>
```

所有 Desktop 的 Hub API 查询（`hubQueries.ts`、`sessionQueries.ts`、`documentQueries.ts`、`projectQueries.ts`）统一通过 `getToken` 回调注入 auth token，不硬编码 token 值。
所有 Desktop 的 Hub API 查询（`hubQueries.ts`、`sessionQueries.ts`、`documentQueries.ts`）统一通过 `getToken` 回调注入 auth token，不硬编码 token 值；`projectQueries.ts` 是 `app/web` 侧查询。

## 安全边界

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/11-protocol-capability-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Deprecated unprefixed aliases（`list_projects` 等）仅在 discovery 中标记
| Tool call / result | `run.agent.tool_call` / `run.agent.tool_result` events | ✅ 已支持 | payload schema 差异需 mapping |
| Message delta / streaming | `message.new` + transcript normalizer | ✅ 已支持 | AG-UI 增量格式需转换层 |
| State snapshot | REST snapshot endpoints + `system.gap` fallback | ⚠️ 部分 | AG-UI state sync 语义更丰富 |
| Run lifecycle | `run.started` / `run.finished` / `run.error` | ✅ 已支持 | — |
| Run lifecycle | `run.started` / `run.finished` / `run.failed` | ✅ 已支持 | — |
| Approval / human-in-the-loop | Hub approval broker + WS approval events | ✅ 已支持 | AG-UI 无内置审批；AgentHub 更强 |
| Multi-modal content | attachments + artifact system | ⚠️ 部分 | AG-UI content block 类型需对齐 |

Expand Down
2 changes: 1 addition & 1 deletion docs/governance/known-flaky.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,4 +164,4 @@ Go 车道 job ID 分工（登记「车道」字段时按此写，勿再写聚合

- 新登记走 PR，编号取现有最大编号 +1。
- 每次触碰本文件时顺带巡检活跃登记：已修复的归档、已到期的移除。
- 本文件超过 300 行时拆分处置历史到归档。
- 本文件超过 170 行（`scripts/verify/verify-doc-ssot.py` 行数预算）时拆分处置历史到归档。