mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-05-18 21:30:48 +08:00
parallel optimization groundwork
This commit is contained in:
64
docs/optimization/01-docs-encoding-cleanup.md
Normal file
64
docs/optimization/01-docs-encoding-cleanup.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# 01 文档与编码清理
|
||||
|
||||
## 背景
|
||||
|
||||
当前 README、配置示例和部分源码输出中的中文在 PowerShell 中显示为乱码。乱码会影响新用户理解，也容易扩散到日志、WebUI、示例配置和后续文档。
|
||||
|
||||
## 目标
|
||||
|
||||
- 确认仓库文本文件统一使用 UTF-8。
|
||||
- 修复 README、配置示例、CLI 输出、Agent 通知文案中的乱码中文。
|
||||
- 保持文档内容准确，不顺手改变代码行为。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- `README.md`
|
||||
- `README_EN.md`
|
||||
- `config.example.json`
|
||||
- `cmd/*.go` 中用户可见输出
|
||||
- `pkg/agent/*.go` 中用户可见中文通知
|
||||
- `workspace/*.md`
|
||||
- `workspace/skills/**/SKILL.md`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- Provider 协议逻辑
|
||||
- Gateway 生命周期逻辑
|
||||
- 工具执行逻辑
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 扫描乱码：
|
||||
|
||||
```bash
|
||||
rg "<22>|锛|鈹|闈|鎴|涓|乧|乀|銆" README.md README_EN.md config.example.json cmd pkg workspace
|
||||
```
|
||||
|
||||
2. 判断每处乱码原始含义，优先从上下文、英文 README、测试断言和代码行为恢复。
|
||||
3. 修复文档和用户可见字符串。
|
||||
4. 如修改测试断言中的字符串，同步更新相关测试。
|
||||
5. 确认所有 Markdown 文件可读，代码能编译。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `README.md` 中文可正常阅读。
|
||||
- `config.example.json` 中文注释/示例文字不再乱码。
|
||||
- CLI/Gateway 关键启动输出不再乱码。
|
||||
- `rg` 扫描不再出现明显历史乱码片段。
|
||||
- `go test ./...` 通过。
|
||||
|
||||
## 测试建议
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go run ./cmd version
|
||||
go run ./cmd --debug version
|
||||
```
|
||||
|
||||
如果终端仍显示异常，确认终端编码和文件编码，而不是继续盲改文本。
|
||||
|
||||
## 并行注意
|
||||
|
||||
该任务可能触碰很多文件，但应只做文本修复。避免和结构重构任务互相覆盖同一段逻辑。
|
||||
114
docs/optimization/02-gateway-structure-split.md
Normal file
114
docs/optimization/02-gateway-structure-split.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 02 Gateway 结构拆分
|
||||
|
||||
## 背景
|
||||
|
||||
`cmd/cmd_gateway.go` 当前同时承担 gateway 命令解析、服务注册、runtime 组装、热重载、API handler 注入、channel 生命周期、cron/heartbeat/sentinel 编排、bootstrap 初始化等职责。文件过大，后续修改容易产生回归。
|
||||
|
||||
## 目标
|
||||
|
||||
在不改变行为的前提下拆分 Gateway 代码结构，让每类职责有清晰文件边界。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- `cmd/cmd_gateway.go`
|
||||
- 新增 `cmd/gateway_runtime.go`
|
||||
- 新增 `cmd/gateway_reload.go`
|
||||
- 新增 `cmd/gateway_services.go`
|
||||
- 新增 `cmd/gateway_bootstrap.go`
|
||||
|
||||
可选文件：
|
||||
|
||||
- `cmd/reload_windows.go`
|
||||
- `cmd/reload_unix.go`
|
||||
- `cmd/signals_windows.go`
|
||||
- `cmd/signals_unix.go`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- `pkg/api/server.go`
|
||||
- `pkg/agent/*`
|
||||
- `pkg/providers/*`
|
||||
- `pkg/channels/*`
|
||||
|
||||
## 建议拆分
|
||||
|
||||
### `cmd/cmd_gateway.go`
|
||||
|
||||
保留命令入口和高层流程：
|
||||
|
||||
- 参数分发。
|
||||
- `gateway run/start/stop/restart/status` 分支。
|
||||
- 前台 run 的主流程骨架。
|
||||
|
||||
### `cmd/gateway_runtime.go`
|
||||
|
||||
放运行时组装：
|
||||
|
||||
- `buildGatewayRuntime`
|
||||
- `bindAgentLoopHandlers`
|
||||
- `configureCronServiceRuntime`
|
||||
- `buildHeartbeatService`
|
||||
- `dispatchCronJob`
|
||||
- `normalizeCronTargetChatID`
|
||||
|
||||
### `cmd/gateway_reload.go`
|
||||
|
||||
放热重载：
|
||||
|
||||
- config fingerprint。
|
||||
- config watcher。
|
||||
- reload trigger。
|
||||
- runtimeSame 判断。
|
||||
- reload 后重新绑定 API handler、channel、sentinel。
|
||||
|
||||
### `cmd/gateway_services.go`
|
||||
|
||||
放系统服务注册/控制：
|
||||
|
||||
- Linux systemd。
|
||||
- macOS launchd。
|
||||
- Windows scheduled task。
|
||||
- PID file stop。
|
||||
|
||||
### `cmd/gateway_bootstrap.go`
|
||||
|
||||
放启动辅助任务：
|
||||
|
||||
- startup compaction check。
|
||||
- bootstrap init。
|
||||
- maximum permission policy。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 行为不变，命令仍可用：
|
||||
|
||||
```bash
|
||||
go run ./cmd gateway run --config ./config.json
|
||||
go run ./cmd gateway status --config ./config.json
|
||||
```
|
||||
|
||||
- `go test ./...` 通过。
|
||||
- `cmd/cmd_gateway.go` 明显变薄，职责聚焦于命令入口。
|
||||
- 新文件命名和函数归属清晰。
|
||||
- 没有引入循环依赖或跨 package 重构。
|
||||
|
||||
## 测试建议
|
||||
|
||||
```bash
|
||||
go test ./cmd ./pkg/api ./pkg/channels ./pkg/agent
|
||||
go test ./...
|
||||
```
|
||||
|
||||
如果有本地配置，可额外手动验证：
|
||||
|
||||
```bash
|
||||
go run ./cmd gateway run --config ./config.json
|
||||
```
|
||||
|
||||
启动后修改配置文件，观察热重载日志是否仍正常。
|
||||
|
||||
## 并行注意
|
||||
|
||||
本任务应避免改 API 路由和 Provider 行为。若 API 文档任务并行进行，它只读 `pkg/api/server.go`，双方冲突较小。
|
||||
111
docs/optimization/03-provider-layer-modularization.md
Normal file
111
docs/optimization/03-provider-layer-modularization.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 03 Provider 层模块化
|
||||
|
||||
## 背景
|
||||
|
||||
`pkg/providers/http_provider.go` 当前聚合了通用 HTTP provider、Responses API、OpenAI-compatible Chat、Codex/Qwen/Kimi 兼容逻辑、OAuth runtime 状态、请求构造、响应解析和部分持久化状态逻辑。文件复杂度偏高，继续新增 Provider 会越来越难。
|
||||
|
||||
## 目标
|
||||
|
||||
在保持现有行为和测试通过的前提下，把 Provider 层按职责拆开，降低单文件复杂度。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- `pkg/providers/http_provider.go`
|
||||
- `pkg/providers/oauth.go`
|
||||
- `pkg/providers/*_provider.go`
|
||||
- 新增若干 provider 内部文件
|
||||
|
||||
建议新增文件：
|
||||
|
||||
- `pkg/providers/provider_registry.go`
|
||||
- `pkg/providers/responses_adapter.go`
|
||||
- `pkg/providers/openai_compat_adapter.go`
|
||||
- `pkg/providers/provider_runtime.go`
|
||||
- `pkg/providers/provider_request_options.go`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- `pkg/agent/*`
|
||||
- `pkg/tools/*`
|
||||
- `cmd/*`
|
||||
- `pkg/api/*`
|
||||
|
||||
## 建议拆分
|
||||
|
||||
### Provider 注册与路由
|
||||
|
||||
移动到 `provider_registry.go`：
|
||||
|
||||
- `CreateProvider`
|
||||
- `CreateProviderByName`
|
||||
- `normalizeProviderRouteName`
|
||||
- `getProviderConfigByName`
|
||||
- provider alias / route 相关逻辑
|
||||
|
||||
### Responses API 适配
|
||||
|
||||
移动到 `responses_adapter.go`：
|
||||
|
||||
- Responses request body 构造。
|
||||
- Responses input item 转换。
|
||||
- Responses tools 转换。
|
||||
- Responses response 解析。
|
||||
- Responses compact summary。
|
||||
|
||||
### OpenAI-compatible Chat 适配
|
||||
|
||||
移动到 `openai_compat_adapter.go`：
|
||||
|
||||
- chat completions request body 构造。
|
||||
- multimodal message 转换。
|
||||
- function call 转换。
|
||||
- Qwen/Kimi 兼容 chat 格式相关公共逻辑。
|
||||
|
||||
### Provider runtime 状态
|
||||
|
||||
移动到 `provider_runtime.go`：
|
||||
|
||||
- runtime state 结构。
|
||||
- history 持久化。
|
||||
- health score。
|
||||
- recent hits/errors/changes。
|
||||
- candidate order。
|
||||
|
||||
### 请求选项与通用解析
|
||||
|
||||
移动到 `provider_request_options.go`：
|
||||
|
||||
- `rawOption`
|
||||
- `stringOption`
|
||||
- `mapOption`
|
||||
- `stringSliceOption`
|
||||
- `int64FromOption`
|
||||
- `float64FromOption`
|
||||
- 其他 request option helper。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `go test ./pkg/providers` 通过。
|
||||
- `go test ./...` 通过。
|
||||
- Provider 对外接口不变。
|
||||
- 现有配置文件无需迁移。
|
||||
- `http_provider.go` 明显缩小，并聚焦 `HTTPProvider` 本体。
|
||||
- 没有改变已有 provider 的请求格式，除非测试明确覆盖并更新说明。
|
||||
|
||||
## 测试建议
|
||||
|
||||
重点跑：
|
||||
|
||||
```bash
|
||||
go test ./pkg/providers -count=1
|
||||
go test ./pkg/agent ./pkg/api ./cmd -count=1
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Provider 层已有大量请求构造测试。拆分时应优先保持测试不动，让测试证明行为未变。
|
||||
|
||||
## 并行注意
|
||||
|
||||
该任务风险较高，建议不要和“新增 Provider”或“AgentLoop 工具调用逻辑改动”同时修改同一分支。若必须并行，先完成纯移动，再做行为改动。
|
||||
101
docs/optimization/04-tool-bootstrap-refactor.md
Normal file
101
docs/optimization/04-tool-bootstrap-refactor.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 04 工具注册架构优化
|
||||
|
||||
## 背景
|
||||
|
||||
`agent.NewAgentLoop()` 直接注册大量工具，包括文件、shell、web、MCP、message、spawn、sessions、memory、parallel、browser、camera、system_info 等。工具注册逻辑和 AgentLoop 初始化耦合较深，也让子 Agent 可见性、默认工具集、可选工具集的边界不够清晰。
|
||||
|
||||
## 目标
|
||||
|
||||
抽出工具启动/注册逻辑，让 AgentLoop 只负责调用工具构建器，而不是直接知道每个工具的创建细节。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- `pkg/agent/loop.go`
|
||||
- `pkg/tools/registry.go`
|
||||
- 新增 `pkg/tools/bootstrap.go`
|
||||
- 新增 `pkg/tools/bootstrap_options.go`
|
||||
|
||||
可选文件：
|
||||
|
||||
- `pkg/tools/tool_allowlist_groups.go`
|
||||
- `pkg/tools/subagent*.go`
|
||||
- `pkg/tools/mcp.go`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- `pkg/providers/*`
|
||||
- `pkg/api/*`
|
||||
- `cmd/*`
|
||||
|
||||
## 建议设计
|
||||
|
||||
新增一个工具构建入口，例如：
|
||||
|
||||
```go
|
||||
type BootstrapOptions struct {
|
||||
Config *config.Config
|
||||
Workspace string
|
||||
MessageBus *bus.MessageBus
|
||||
CronService *cron.CronService
|
||||
Provider providers.LLMProvider
|
||||
ProcessManager *ProcessManager
|
||||
}
|
||||
|
||||
type BootstrapResult struct {
|
||||
Registry *ToolRegistry
|
||||
ProcessManager *ProcessManager
|
||||
SubagentManager *SubagentManager
|
||||
SubagentRouter *SubagentRouter
|
||||
}
|
||||
|
||||
func BootstrapDefaultTools(ctx context.Context, opts BootstrapOptions) (*BootstrapResult, error)
|
||||
```
|
||||
|
||||
AgentLoop 中保留：
|
||||
|
||||
- session manager 初始化。
|
||||
- context builder 初始化。
|
||||
- provider fallback chain。
|
||||
- subagent run func 注入。
|
||||
|
||||
工具构建器负责：
|
||||
|
||||
- 创建并注册基础工具。
|
||||
- 根据 config 注册 cron/remind。
|
||||
- 根据 config 注册 MCP 和远端工具。
|
||||
- 创建 subagent manager/router。
|
||||
- 注册 tool catalog 需要的 metadata。
|
||||
|
||||
## 子 Agent 可见性
|
||||
|
||||
保持现有行为：
|
||||
|
||||
- 主 Agent 默认看见全部注册工具。
|
||||
- 子 Agent 由 profile allowlist 限制。
|
||||
- `skill_exec` 仍为隐式允许工具。
|
||||
- `parallel` 内部 call 仍需要逐项校验 allowlist。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `agent.NewAgentLoop()` 更短，工具注册细节迁移出去。
|
||||
- 工具列表和原来保持一致。
|
||||
- MCP discovery 行为保持一致。
|
||||
- subagent spawn/profile/sessions 工具仍正常注册。
|
||||
- `go test ./pkg/agent ./pkg/tools` 通过。
|
||||
- `go test ./...` 通过。
|
||||
|
||||
## 测试建议
|
||||
|
||||
```bash
|
||||
go test ./pkg/tools -count=1
|
||||
go test ./pkg/agent -count=1
|
||||
go test ./...
|
||||
```
|
||||
|
||||
建议新增一个测试断言默认工具集名称，避免重构时漏注册工具。
|
||||
|
||||
## 并行注意
|
||||
|
||||
该任务会修改 `pkg/agent/loop.go`，应避免和 AgentLoop 行为改动并行落同一分支。它不应修改 Provider 或 Gateway。
|
||||
120
docs/optimization/05-gateway-api-docs.md
Normal file
120
docs/optimization/05-gateway-api-docs.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 05 Gateway API 文档
|
||||
|
||||
## 背景
|
||||
|
||||
Gateway 暴露了较多 WebUI/API endpoint，但目前主要靠 `pkg/api/server.go` 阅读理解。对前端、集成方和测试编写者来说，需要一份稳定的 API 文档。
|
||||
|
||||
## 目标
|
||||
|
||||
新增 Gateway API 文档，说明认证方式、核心接口、请求/响应样例、错误约定和常见调用场景。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- 新增 `docs/API.md`
|
||||
- 可选更新 `README.md` 或 `docs/PROJECT_OVERVIEW.md` 增加链接
|
||||
|
||||
参考文件：
|
||||
|
||||
- `pkg/api/server.go`
|
||||
- `cmd/cmd_gateway.go`
|
||||
- `config.example.json`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- API handler 行为
|
||||
- Gateway runtime 行为
|
||||
- 前端资源或 WebUI 逻辑
|
||||
|
||||
## 文档建议结构
|
||||
|
||||
```text
|
||||
# Gateway API
|
||||
|
||||
## 认证
|
||||
## 基础 URL
|
||||
## 健康检查
|
||||
## Chat
|
||||
## Chat History
|
||||
## Live Chat / SSE
|
||||
## Events
|
||||
## Config
|
||||
## Provider OAuth
|
||||
## Provider Models / Runtime
|
||||
## Weixin Login
|
||||
## Upload
|
||||
## Cron
|
||||
## Skills
|
||||
## Sessions
|
||||
## Memory
|
||||
## Workspace File
|
||||
## Tools
|
||||
## MCP Install
|
||||
## Logs
|
||||
## 错误响应
|
||||
```
|
||||
|
||||
## 需要覆盖的接口
|
||||
|
||||
从当前代码至少覆盖：
|
||||
|
||||
```text
|
||||
GET /health
|
||||
* /api/config
|
||||
* /api/chat
|
||||
* /api/chat/history
|
||||
* /api/chat/live
|
||||
* /api/events/live
|
||||
* /api/version
|
||||
* /api/provider/oauth/start
|
||||
* /api/provider/oauth/complete
|
||||
* /api/provider/oauth/import
|
||||
* /api/provider/oauth/accounts
|
||||
* /api/provider/models
|
||||
* /api/provider/runtime
|
||||
* /api/weixin/status
|
||||
* /api/weixin/login/start
|
||||
* /api/weixin/login/cancel
|
||||
GET /api/weixin/qr.svg
|
||||
* /api/weixin/accounts/remove
|
||||
* /api/weixin/accounts/default
|
||||
* /api/upload
|
||||
* /api/cron
|
||||
* /api/skills
|
||||
* /api/sessions
|
||||
* /api/memory
|
||||
* /api/workspace_file
|
||||
* /api/tool_allowlist_groups
|
||||
* /api/tools
|
||||
* /api/mcp/install
|
||||
* /api/logs/live
|
||||
* /api/logs/recent
|
||||
```
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 新增 `docs/API.md`。
|
||||
- 每个核心接口至少有用途、方法、认证、主要参数、响应示例。
|
||||
- 文档说明 gateway token 的传递方式。
|
||||
- 文档中明确哪些接口用于 SSE/live。
|
||||
- 文档不声称尚不存在的行为。
|
||||
- 纯文档任务无需修改源码。
|
||||
|
||||
## 测试建议
|
||||
|
||||
纯文档任务可不跑全量测试。建议至少用代码核对路由：
|
||||
|
||||
```bash
|
||||
rg "HandleFunc|SetProtectedRoute" pkg/api/server.go
|
||||
```
|
||||
|
||||
如果顺手补了 API 测试，则运行：
|
||||
|
||||
```bash
|
||||
go test ./pkg/api
|
||||
```
|
||||
|
||||
## 并行注意
|
||||
|
||||
本任务只写文档，适合和 Gateway 拆分并行执行。若 Gateway 拆分改动路由注册位置，最终合并时再核对一次 API 文档。
|
||||
93
docs/optimization/06-runtime-service-tests.md
Normal file
93
docs/optimization/06-runtime-service-tests.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 06 Cron / Heartbeat / Sentinel 测试
|
||||
|
||||
## 背景
|
||||
|
||||
当前测试覆盖面较广，但长期运行服务相关模块还有明显空白，尤其是：
|
||||
|
||||
- `pkg/cron`
|
||||
- `pkg/heartbeat`
|
||||
- `pkg/sentinel`
|
||||
|
||||
这些模块负责定时任务、心跳和健康巡检，是常驻 Gateway 的可靠性基础。
|
||||
|
||||
## 目标
|
||||
|
||||
补充运行时服务测试，覆盖调度、持久化、失败退避、生命周期启停和巡检结果。
|
||||
|
||||
## 建议改动范围
|
||||
|
||||
主要文件：
|
||||
|
||||
- 新增 `pkg/cron/service_test.go`
|
||||
- 新增 `pkg/heartbeat/service_test.go`
|
||||
- 新增 `pkg/sentinel/service_test.go`
|
||||
|
||||
可选文件：
|
||||
|
||||
- `pkg/lifecycle/loop_runner_test.go`
|
||||
|
||||
尽量避免修改：
|
||||
|
||||
- `cmd/cmd_gateway.go`
|
||||
- `pkg/agent/*`
|
||||
- `pkg/providers/*`
|
||||
|
||||
如果为了可测试性需要小改生产代码，应保持非常小的改动，例如注入 clock、缩短 sleep、暴露只读状态。
|
||||
|
||||
## Cron 测试建议
|
||||
|
||||
覆盖：
|
||||
|
||||
- `AddJob` 后写入 store。
|
||||
- `ListJobs(includeDisabled)` 行为。
|
||||
- `EnableJob` 启停。
|
||||
- `UpdateJob` 修改 schedule/message。
|
||||
- cron expr 计算 next run。
|
||||
- 失败后 backoff 和 consecutive failure。
|
||||
- `MaxWorkers` 限制并发。
|
||||
- 一次性任务 `DeleteAfterRun`。
|
||||
- store 损坏或空文件时的行为。
|
||||
|
||||
## Heartbeat 测试建议
|
||||
|
||||
覆盖：
|
||||
|
||||
- disabled 时 `Start()` 不触发 heartbeat。
|
||||
- enabled 时按 interval 调用回调。
|
||||
- `Stop()` 后不再触发。
|
||||
- `buildPrompt()` 使用自定义 prompt template。
|
||||
- 空 Markdown 判断。
|
||||
- ack token 提取。
|
||||
|
||||
## Sentinel 测试建议
|
||||
|
||||
覆盖：
|
||||
|
||||
- config 文件不存在/损坏时返回问题。
|
||||
- memory 目录缺失时行为。
|
||||
- logs 目录/文件检查。
|
||||
- channel health check 汇总。
|
||||
- alert callback 被调用。
|
||||
- disabled 时不启动或不告警。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 新增三个模块的测试文件。
|
||||
- 测试稳定，不依赖真实网络、真实外部平台或长时间 sleep。
|
||||
- `go test ./pkg/cron ./pkg/heartbeat ./pkg/sentinel` 通过。
|
||||
- `go test ./...` 通过。
|
||||
|
||||
## 测试建议
|
||||
|
||||
```bash
|
||||
go test ./pkg/cron -count=1
|
||||
go test ./pkg/heartbeat -count=1
|
||||
go test ./pkg/sentinel -count=1
|
||||
go test ./...
|
||||
```
|
||||
|
||||
如果某个服务当前不易测试，优先做最小可测试性改造，而不是写依赖时间运气的测试。
|
||||
|
||||
## 并行注意
|
||||
|
||||
该任务大多新增测试文件，和结构重构冲突较小。若 Gateway 拆分同时进行，避免在本任务中修改 `cmd/`。
|
||||
47
docs/optimization/README.md
Normal file
47
docs/optimization/README.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# ClawGo 并行优化任务拆分
|
||||
|
||||
本文档把当前值得优化的方向拆成可并行执行的工作包。每个工作包都有相对独立的文件范围、交付物和验收标准，便于多人或多个 agent 同时推进。
|
||||
|
||||
## 工作包总览
|
||||
|
||||
| 编号 | 任务 | 主要目标 | 建议并行性 |
|
||||
| --- | --- | --- | --- |
|
||||
| 01 | 文档与编码清理 | 统一中文文档/示例/输出文本编码，提升可读性 | 可独立执行 |
|
||||
| 02 | Gateway 结构拆分 | 拆薄 `cmd/cmd_gateway.go`，降低维护成本 | 可独立执行 |
|
||||
| 03 | Provider 层模块化 | 拆分 Provider 协议、OAuth、runtime 状态逻辑 | 可独立执行，但需谨慎 |
|
||||
| 04 | 工具注册架构优化 | 抽出工具启动器，清晰区分默认工具、可选工具、子 Agent 可见性 | 可独立执行 |
|
||||
| 05 | Gateway API 文档 | 补充 API 认证、接口、请求响应样例 | 可独立执行 |
|
||||
| 06 | Cron / Heartbeat / Sentinel 测试 | 补长期运行服务测试覆盖 | 可独立执行 |
|
||||
|
||||
## 推荐并行顺序
|
||||
|
||||
可以第一批同时启动：
|
||||
|
||||
- `01-docs-encoding-cleanup.md`
|
||||
- `02-gateway-structure-split.md`
|
||||
- `05-gateway-api-docs.md`
|
||||
- `06-runtime-service-tests.md`
|
||||
|
||||
第二批建议在第一批基本稳定后启动：
|
||||
|
||||
- `03-provider-layer-modularization.md`
|
||||
- `04-tool-bootstrap-refactor.md`
|
||||
|
||||
原因是 Provider 和工具注册都靠近 AgentLoop 核心，改动面更大，最好避开 Gateway 大拆分和文档编码清理的高频改动期。
|
||||
|
||||
## 并行开发约定
|
||||
|
||||
- 每个任务尽量只改自己文档中列出的主要文件。
|
||||
- 如果必须跨任务修改同一文件，先在 PR/提交说明中明确说明原因。
|
||||
- 不要顺手重构不在任务范围内的模块。
|
||||
- 每个任务完成后至少运行 `go test ./...`，纯文档任务除外。
|
||||
- 涉及行为变更时，优先补就近单元测试。
|
||||
|
||||
## 任务文件
|
||||
|
||||
- [01 文档与编码清理](./01-docs-encoding-cleanup.md)
|
||||
- [02 Gateway 结构拆分](./02-gateway-structure-split.md)
|
||||
- [03 Provider 层模块化](./03-provider-layer-modularization.md)
|
||||
- [04 工具注册架构优化](./04-tool-bootstrap-refactor.md)
|
||||
- [05 Gateway API 文档](./05-gateway-api-docs.md)
|
||||
- [06 Cron / Heartbeat / Sentinel 测试](./06-runtime-service-tests.md)
|
||||
Reference in New Issue
Block a user