Skip to content

Commit db8205f

Browse files
committed
feat: add idempotent controlled run creation
1 parent 9551071 commit db8205f

58 files changed

Lines changed: 3116 additions & 186 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 43 additions & 23 deletions
Large diffs are not rendered by default.

‎cmd/cyberagent-desktop/main_windows.go‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ type webView2RuntimeProbe struct {
4242

4343
type desktopOptions struct {
4444
profileControl bool
45+
runCreation bool
4546
version bool
4647
}
4748

@@ -164,14 +165,17 @@ func parseDesktopOptions(args []string) (desktopOptions, error) {
164165
fs.SetOutput(os.Stderr)
165166
profileControl := fs.Bool("enable-profile-control", false,
166167
"enable only the non-authorizing Run execution-profile control")
168+
runCreation := fs.Bool("enable-run-creation", false,
169+
"enable idempotent workspace-bound Run creation")
167170
version := fs.Bool("version", false, "print version and exit")
168171
if err := fs.Parse(args); err != nil {
169172
return desktopOptions{}, err
170173
}
171174
if fs.NArg() != 0 {
172175
return desktopOptions{}, errors.New("cyberagent-desktop accepts no positional arguments")
173176
}
174-
return desktopOptions{profileControl: *profileControl, version: *version}, nil
177+
return desktopOptions{profileControl: *profileControl, runCreation: *runCreation,
178+
version: *version}, nil
175179
}
176180

177181
func runDesktop(config desktopOptions) error {
@@ -191,7 +195,7 @@ func runDesktop(config desktopOptions) error {
191195
return err
192196
}
193197
controlToken := ""
194-
if config.profileControl {
198+
if config.profileControl || config.runCreation {
195199
controlToken, err = httpapi.GenerateAccessToken()
196200
if err != nil {
197201
return err
@@ -201,6 +205,7 @@ func runDesktop(config desktopOptions) error {
201205
databasePath := filepath.Join(app.DefaultHome(), "cyberagent.db")
202206
controlPlane, err := desktop.OpenControlPlane(desktop.ControlPlaneConfig{
203207
DatabasePath: databasePath, ReadToken: readToken, ControlToken: controlToken,
208+
RunControlEnabled: config.profileControl, RunCreationEnabled: config.runCreation,
204209
AppVersion: app.Version, UIHandler: bundle,
205210
})
206211
if err != nil {
@@ -214,6 +219,7 @@ func runDesktop(config desktopOptions) error {
214219
bridge, err := desktop.NewDesktopBridge(desktop.DesktopBridgeConfig{
215220
ContextProvider: lifecycle.Context, FilePicker: nativeSkillPackagePicker{},
216221
ReadToken: readToken, ControlToken: controlToken, APIVersion: httpapi.Version,
222+
RunControlEnabled: config.profileControl, RunCreationEnabled: config.runCreation,
217223
AppVersion: app.Version, UIDigest: bundle.Digest(), Selector: selector, PreviewBridge: preview,
218224
})
219225
if err != nil {

‎cmd/cyberagent-desktop/main_windows_test.go‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,16 +30,23 @@ func TestDesktopOptionsDefaultToReadOnlyAndRequireExplicitProfileControl(t *test
3030
if err != nil {
3131
t.Fatal(err)
3232
}
33-
if defaults.profileControl || defaults.version {
33+
if defaults.profileControl || defaults.runCreation || defaults.version {
3434
t.Fatalf("unexpected defaults: %#v", defaults)
3535
}
3636
enabled, err := parseDesktopOptions([]string{"--enable-profile-control"})
3737
if err != nil {
3838
t.Fatal(err)
3939
}
40-
if !enabled.profileControl || enabled.version {
40+
if !enabled.profileControl || enabled.runCreation || enabled.version {
4141
t.Fatalf("profile control was not explicit: %#v", enabled)
4242
}
43+
creation, err := parseDesktopOptions([]string{"--enable-run-creation"})
44+
if err != nil {
45+
t.Fatal(err)
46+
}
47+
if creation.profileControl || !creation.runCreation || creation.version {
48+
t.Fatalf("Run creation was not independently explicit: %#v", creation)
49+
}
4350
if _, err := parseDesktopOptions([]string{"unexpected"}); err == nil {
4451
t.Fatal("desktop positional argument was accepted")
4552
}

‎docs/DESKTOP_PLAN.md‎

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# CyberAgent Workbench Desktop Plan
22

3-
状态:非 schema Desktop D0-A 与 D0-B 自动化核心已完成。Wails v2.13.0 Windows 只读壳、嵌入式 React bundle、进程内 Go API、同库恢复、高水位事件续传、WebView2 失败关闭、内存令牌、原生 `.zip` 对话框和路径隔离 Skill 预览已经通过测试与 Windows 11 实机复核;Windows 10 实机矩阵、安装包、正式便携发行、注册表、自启动、更新和高权限执行仍未实现。
3+
状态:Desktop D0-A、D0-B 与 schema-v72 D1-R1 自动化核心已完成。Wails v2.13.0 Windows 壳、嵌入式 React bundle、进程内 Go API、同库恢复、高水位事件续传、WebView2 失败关闭、内存令牌、原生 `.zip` 对话框、路径隔离 Skill 预览和显式 capability 下的受控 Run 创建已经通过完整本地发布门;Windows 10 实机矩阵、Session/Plan/审批/Diff/Skill mutation、安装包、正式便携发行、注册表、自启动、更新和高权限执行仍未实现。
44

55
## 目标
66

@@ -13,7 +13,7 @@
1313
- TypeScript 业务操作继续使用 Go 拥有的 HTTP/OpenAPI 契约;普通 Web 保留 SSE,Windows Desktop 因 Wails v2 AssetServer 不支持流式响应而使用同一事件表、同一 Run-bound 高水位 cursor 的 `run-event-poll.v1`。桌面绑定只处理内存启动材料和受控文件选择,不建立第二套业务 API。
1414
- Electron 不作为默认方案,避免 Node 成为并行高权限控制面。Tauri 不作为默认方案,避免 Rust 从确定性分析工具变成桌面主控。
1515
- 桌面端不直接读取 API key,不直接控制 Docker/Shell,不实现 Scope 或文件权限判断,也不在 Local Storage、前端日志或注册表保存凭证。
16-
- CLI、TUI、Web 和 Desktop 必须投影同一 Run/Event/Approval 状态;关闭窗口不得隐式取消后台 Run。D0-A/D0-B 只读取已有状态,不取得 Run execution lease。
16+
- CLI、TUI、Web 和 Desktop 必须投影同一 Run/Event/Approval 状态;关闭窗口不得隐式取消后台 Run。D0-A/D0-B 只读取已有状态,D1-R1 只创建关闭的 Run 图;两者都不取得 Run execution lease。
1717

1818
## 目标布局
1919

@@ -33,18 +33,18 @@
3333
- `desktop_skill_package_preview.v1` 只返回有界风险元数据,排除路径、文件名、正文、Manifest description/content path/content digest,并固定安装、命令、网络、Provider、工具和能力授权为 false。
3434
- D0-A 已把该边界接入 Wails 原生对话框和 React 只读预览。渲染层仍不能提交路径、文件字节或安装请求,也不会因预览创建数据库事实或 Run 事件;ADR 0033 与 ADR 0034 分别记录路径隔离和桌面壳边界。
3535

36-
## D0-A/D0-B 当前实现
36+
## D0-A/D0-B/D1-R1 当前实现
3737

38-
- `cmd/cyberagent-desktop` 只在 Windows `desktop,wv2runtime.error` build tags 下编译,production 构建再增加 `production`;默认 read-only,显式 `--enable-profile-control` 也只开放 schema v64 已审计的非授权档位选择。
38+
- `cmd/cyberagent-desktop` 只在 Windows `desktop,wv2runtime.error` build tags 下编译,production 构建再增加 `production`;默认 read-only。显式 `--enable-profile-control` 只开放 schema v64 非授权档位选择,显式 `--enable-run-creation` 只开放 schema v72 受控 Run 创建;两项 capability 独立,creation-only 不能访问取消/档位 route。
3939
- `web/dist` 以 compile-time embed 进入二进制;Go 在启动前验证 index、内容哈希资源、类型、数量、单项/总大小并复制为不可变内存快照。
4040
- Wails AssetServer 直接调用现有 `httpapi.API` Handler,不监听 TCP 端口;同一 Go 层继续负责 Bearer、Host、CSP、Policy、SQLite 和 DTO。
4141
- Renderer 绑定面只有 `Bootstrap`、`SelectSkillPackage`、`PreviewSkillPackage` 三个方法。进程、Shell、Docker、Skill 安装和 renderer path input 权限全部固定为 false。
42-
- read/control token 每次进程启动随机生成,只驻留内存,不写 Local Storage、SQLite、日志、命令输出或注册表;两者不得相同。
42+
- read/control token 每次进程启动随机生成,只驻留内存,不写 Local Storage、SQLite、日志、命令输出或注册表;两者不得相同。只有至少一个显式 control capability 开启时才生成 control token。
4343
- 单实例、窗口恢复、禁用 WebView 文件拖放/默认右键菜单、renderer code integrity、路径隔离错误和 bounded startup dialog 已接入。
4444
- `desktop.ControlPlane` 与 `desktop.Lifecycle` 固定同库 API 所有权、幂等关闭、崩溃重开、第二实例让位和停止后永久静默;第二实例参数与工作目录不会进入主实例。
4545
- Desktop 通过 `GET /api/v1/runs/{run_id}/events/poll` 消费与 SSE 相同的真实事件 frame/cursor;React 最多在内存保留 16 个 Run、每个 500 帧,不写浏览器存储。
4646
- WebView2 `94.0.992.31` 以上只读预检发生在 bundle/数据库之前;失败时不下载、不安装、不打开 URL。进程内适配器只接受精确 `http://wails.localhost`,外部链接、表单和 popup 在 Desktop renderer 中被阻止。
47-
- secure production-tag 二进制已经在隔离 schema-v71 home 通过 Windows 11 强制结束/重开与第二实例实机烟测;主工作台、Skill modal 与原生 `.zip` 对话框也已通过视觉复核。
47+
- secure production-tag 二进制已经在隔离数据目录通过 Windows 11 强制结束/重开与第二实例实机烟测;主工作台、Skill modal 与原生 `.zip` 对话框也已通过视觉复核。D1-R1 的 Run 创建 route、能力分离和 React 对话框由自动化覆盖,正式发布前仍需随最终二进制复跑完整 Windows 10/11 人工矩阵。
4848

4949
本地构建:
5050

@@ -54,6 +54,17 @@ powershell -ExecutionPolicy Bypass -File scripts/build-desktop.ps1
5454

5555
输出位于 `build/desktop/cyberagent-desktop.exe`,默认不开放 control token。该文件是未签名开发/便携测试产物,不是正式发行包。机器需要 Windows 10/11 和 WebView2 Evergreen Runtime `94.0.992.31` 或更新版本;缺失时应用只给出本机指导,不会隐式安装。测试其他数据目录时,可在启动前设置 `CYBERAGENT_HOME`;桌面渲染层无法读取或更改这个路径。
5656

57+
显式启用受控 Run 创建:
58+
59+
```powershell
60+
.\build\desktop\cyberagent-desktop.exe --enable-run-creation
61+
62+
# 可与非授权档位选择共同启用。
63+
.\build\desktop\cyberagent-desktop.exe --enable-run-creation --enable-profile-control
64+
```
65+
66+
创建只接受已注册 Workspace,并固定默认预算、禁用网络/目标和 `preview/noop` 执行档位;它不会自动发送 Session 消息、调用模型、取得 execution lease 或启动进程。
67+
5768
## 分阶段交付
5869

5970
### D0:桌面基础验证(自动化核心完成,Windows 10 实机待补)
@@ -68,10 +79,13 @@ powershell -ExecutionPolicy Bypass -File scripts/build-desktop.ps1
6879

6980
### D1:日常工作台(产品可用度约 65-70%)
7081

71-
- 增加由 Go API 驱动的 Run 创建、Session 对话、Plan 选择、引导队列、审批、Diff 审查和 Skill 管理。
72-
- 所有 mutation 使用独立 control token、Origin/Host 校验、幂等 operation key 和 typed errors。
73-
- 在首个 mutation 上继续复核 CLI/Desktop 并发、窗口重开、后台 Run、幂等重放与断线续传,不复用 D0 的只读结论替代写路径审计。
74-
- Code 与 Cyber 保持不同 Skill 目录和风险呈现;桌面切换不改变 Run 内不可变模式。
82+
- [x] D1-R1 / schema v72:Go API 受控创建 Mission/Run/Session,严格注册 Workspace、Scope、默认预算、幂等 operation、事务事件和关闭 execution profile;React 可选择 Workspace/Profile/Surface/Phase 并在成功后刷新、选中新 Run。
83+
- [x] D1-R1 capability 与 `--enable-profile-control` 独立;creation-only token 不能访问旧控制 route,Wails native bridge 不增加方法。
84+
- [x] D1-R1 完整门禁通过全仓普通/race、普通/secure-Desktop 检查、45 项前端测试、确定性契约、生产构建、依赖/隐私/Markdown 扫描和隔离 CLI smoke;没有已知未解决高/中风险。
85+
- [ ] D1-S1:增加 Run-bound Session 对话与操作者引导提交,复用 RunSupervisor、队列、预算、Policy、脱敏和事件语义。
86+
- [ ] 随后的独立切片增加 Plan 选择/阶段切换、审批、Diff 审查和 Skill 管理;每类 mutation 分别做状态、幂等、权限与重启审计。
87+
- [ ] 所有 mutation 使用独立 control token、Origin/Host 校验、幂等 operation key 和 typed errors;CLI/Desktop 并发、窗口重开、后台 Run、重放与断线续传不得只沿用 D0 结论。
88+
- [ ] Code 与 Cyber 保持不同 Skill 目录和风险呈现;桌面切换不改变 Run 内不可变模式。
7589

7690
### D2:Windows Beta 分发(产品可用度约 75-80%)
7791

@@ -97,8 +111,8 @@ powershell -ExecutionPolicy Bypass -File scripts/build-desktop.ps1
97111

98112
- Windows 自动化覆盖启动前置条件、关闭/恢复、同库续传和 renderer 边界;Windows 11 x64 已实机验证,Windows 10 x64 仍是正式发行前必过矩阵。
99113
- 渲染进程无法绕过 Go API 访问 Shell、Docker、密钥或工作区外文件。
100-
- CLI 与 Desktop 同时运行时,SQLite 不损坏、operation 重放不分叉、Run lease 不被窗口生命周期偷取。
114+
- CLI 与 Desktop 同时运行时,SQLite 不损坏、operation 重放不分叉、Run lease 不被窗口生命周期或 Run 创建偷取。
101115
- 安装、升级和卸载不会静默删除 Workspace、数据库、凭证或用户创建文件。
102116
- 未签名开发产物不得伪装成正式发布;正式包必须有可核验签名和哈希。
103117

104-
ADR 0034 与 ADR 0035 分别记录 D0-A 可见只读壳和 D0-B 生命周期/事件续传加固。Wails 使用 MIT 许可证;D2 生成任何可分发 ZIP/MSIX 前必须把 Wails 及其他运行时依赖的许可证/notice、SBOM 和哈希一起打包。
118+
ADR 0034、ADR 0035 与 ADR 0036 分别记录 D0-A 可见壳、D0-B 生命周期/事件续传加固和 D1-R1 受控 Run 创建。Wails 使用 MIT 许可证;D2 生成任何可分发 ZIP/MSIX 前必须把 Wails 及其他运行时依赖的许可证/notice、SBOM 和哈希一起打包。

‎docs/PROGRESS_BOOK.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -836,10 +836,22 @@ secure Desktop 构建必须显式使用 `desktop,production,wv2runtime.error`。
836836

837837
双指标更新为架构完成度约 98%(V2 约 99%)、完整产品可用度约 53-57%、通用 Coding Agent 约 47%、Cyber 自动化约 20%。下一推荐切片为 Desktop D1-R1:先增加 Go-owned Run 创建与自动 Session 绑定的窄 control route,不调用模型、不扩展 Wails native bridge;Session message/steering 作为随后独立审计。边界见 ADR 0035。
838838

839+
schema v72 / Desktop D1-R1 幂等受控 Run 创建切片已完成实现,任务 ID 为 `P9-Idempotent-Controlled-Run-Creation-v72-D1R1`。Go 新增不可变 `run_creation.v1` operation 账本,只持久化域分隔幂等键摘要、请求指纹和 Mission/Run/Session/Workspace 身份。Application 仅接受已注册 Workspace、1-4096 UTF-8 字节目标和规范 Profile/Surface/Phase,并在一个 immediate SQLite 事务中创建脱敏 Mission、交互式 created Run、活动 Session、revision-one mode、`preview/noop` execution profile、root Agent、精确初始事件及 operation。网络固定 disabled、目标为空、预算固定默认值、model route 固定等于 Profile;SQL trigger 独立复核整条绑定并拒绝 operation 更新/删除。
840+
841+
HTTP 新增 distinct-control `POST /api/v1/runs` 和 read-bearer `GET /api/v1/workspaces`。写入口要求恰好一个 `Idempotency-Key`、严格 Content-Type、零 query、有界 body、无未知/重复字段和无尾随 JSON;相同 key/语义跨重启和跨连接收敛到原对象,不同意图冲突。Workspace DTO 只含 ID、名称和创建时间,不公开 root path。OpenAPI 更新为 28 个 path、65 个 schema、25 个 GET 与 4 个 control POST。
842+
843+
Desktop 新增独立 `--enable-run-creation`,与 `--enable-profile-control` 分别控制 capability;creation-only token 不能访问取消或档位 route,Wails 原生 bridge 仍精确保持三个方法。React 新增 New Run 对话框、Workspace/Profile/Surface/Phase 选择、内存内不确定失败 key 重放、UTF-8 字节预检、请求-响应 Workspace/Profile/模式复核、默认预算/关闭权限校验、Run/Session 刷新与新 Run 选中。token 与 operation key 不进入 URL、Local Storage 或 Session Storage。
844+
845+
切片审计发现并修复多类健壮性问题:creation-only control token 与旧取消/档位 capability 完全拆分;重放会重新计算已存图请求指纹并验证完整初态;历史 schema 夹具先移除 v72 trigger 再拆旧 profile 表,避免降级测试失败和 SQLite 文件锁;v72 trigger 进一步锁定初始 updated_at、root 状态和四条事件总数;HTTP 在 Go JSON 解码前拒绝非法 UTF-8,并改用窄 Store 契约而不继承无关 Run transition 权限;Domain 多字段错误顺序固定;React 同时绑定请求 Goal/Workspace、初始 Run/Session 状态、Mode Profile/Surface/Phase/revision/policy、默认预算和关闭权限,并按 Go 的 4096 UTF-8 字节上限预检多字节目标。当前未调用真实 Provider、Agent-controlled Shell/宿主进程、Docker、Skill 安装钩子或外部网络,也未取得 execution lease。边界见 ADR 0036。
846+
847+
v72 最终本地发布门通过:全仓普通/race 分别 271.5 秒/257.9 秒;普通与 secure-Desktop 测试、vet、零告警 staticcheck、module verify/tidy diff、双路径零可达漏洞 govulncheck、严格 TypeScript、14 个文件 45 项前端测试、Vite 与 Windows production build、零漏洞 npm audit、OpenAPI/TypeScript 双次生成哈希一致、63 份 Markdown/86 条相对链接、凭据/运行产物/生产 `exec.Command`/乱码/diff 扫描和隔离 schema-v72 CLI smoke 均为绿色。一次与四项分析并行的 Desktop-tag 测试只触发 244 秒外层超时且没有失败输出,独立重跑在 267.2 秒明确通过;该编排超时不计为产品失败。当前没有已知未解决高/中风险;烟测根位于系统临时目录并等待正常回收,无需人工操作。
848+
849+
双指标更新为架构完成度约 98%(V2 约 99%)、完整产品可用度约 55-59%、通用 Coding Agent 约 49%、Cyber 自动化约 20%。下一推荐切片为 Desktop D1-S1:复用既有 RunSupervisor、持久化引导队列、预算、Policy、脱敏、operation key 和事件语义,增加现有 Run-bound Session 的 Go-owned message/steering mutation;继续不建立 Desktop-only 执行路径,不启动进程。
850+
839851
## 八、仓库同步与恢复约定
840852

841853
规范远程仓库:`https://github.com/Qiyuanqiii/CTF-CyberAgent-Workbench`。
842854

843855
每次完成一个开发切片后,依次执行功能复核、测试、代码与安全审计、项目记忆更新、Git 提交和 GitHub 推送。当前仓库直接开发并推送 `main`;除非用户明确要求,不创建功能分支或 PR。
844856

845-
长对话恢复时依次阅读:`README.md`、`docs/PROJECT_MEMORY.md`、`docs/PROJECT_STATUS.md`、本文件、`docs/TASK_BOOK.md`、`docs/http-api.md`、`docs/errors.md`,再按序阅读 `docs/adr/0001-*.md` 到 `docs/adr/0035-desktop-lifecycle-and-event-resumption.md`。
857+
长对话恢复时依次阅读:`README.md`、`docs/PROJECT_MEMORY.md`、`docs/PROJECT_STATUS.md`、本文件、`docs/TASK_BOOK.md`、`docs/http-api.md`、`docs/errors.md`,再按序阅读 `docs/adr/0001-*.md` 到 `docs/adr/0036-idempotent-controlled-run-creation.md`。

0 commit comments

Comments
 (0)