👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
feat: bootstrap computer-use research repo
Leo69b7960573d6
diff --git a/.gitignore b/.gitignorenew file mode 100644index 0000000..f32e31a--- /dev/null+++ b/.gitignore@@ -0,0 +1,2 @@+.idea/+.DS_Storediff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..12077ab--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,38 @@+# open-codex-computer-use++这个仓库是一个面向 Agent 协作开发的基础模板。++`AGENTS.md` 故意保持简短,只负责做导航,不负责塞满所有规则。仓库内的 `docs/` 才是本地知识的正式来源。++如果一次代码或流程变更会让某份文档过期,就在同一轮任务里顺手把它改掉。++## 每轮开始先读++- `docs/REPO_COLLAB_GUIDE.md`:仓库级协作、提交、文档同步与测试约定。+- `docs/ARCHITECTURE.md`:仓库整体结构和预期边界。+- `docs/design-docs/core-beliefs.md`:Agent-first 的工作原则和这个模板的设计出发点。++## 代码改完前要读++- `docs/HISTORY_GUIDE.md`:什么时候记 history、怎么命名、怎么脱敏。+- `docs/QUALITY_SCORE.md`:当前质量分层和主要短板。++## 按任务需要选读++- `docs/PLANS_GUIDE.md`:什么时候要写 execution plan,怎么维护。+- `docs/PRODUCT_SENSE.md`:产品价值、取舍方式和优先级判断。+- `docs/RELIABILITY.md`:运行稳定性、观测性和上线前的基本要求。+- `docs/SECURITY.md`:认证、数据处理、外部集成等安全默认约束。+- `docs/SUPPLY_CHAIN_SECURITY.md`:依赖、SBOM、制品 provenance 和仓库级供应链安全默认做法。+- `docs/CICD.md`:仓库的 CI/CD 骨架以及后续如何接入真实项目。+- `docs/FRONTEND.md`:如果仓库包含前端界面,这里记录对应规范。+- `CONTRIBUTING.md`:提 PR 前后的默认检查项和协作要求。+- `docs/releases/README.md`:如何维护面向用户的发布记录。+- `docs/references/README.md`:沉淀到仓库里的外部参考资料。++## 工作规则++- 优先选择小而清晰、对仓库和 Agent 都友好的抽象。+- prompt、规则、架构约束尽量都版本化落在仓库里。+- 复杂任务不要只靠聊天上下文,应该落 execution plan。+- 完成的代码变更要记到 `docs/histories/`。diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..627ccb6--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1 @@+<system-reminder>必须先阅读 AGENTS.md。</system-reminder>diff --git a/CODEOWNERS b/CODEOWNERSnew file mode 100644index 0000000..2846cf7--- /dev/null+++ b/CODEOWNERS@@ -0,0 +1,3 @@+# 基于这个模板创建新项目后,请替换成真实的代码所有者。++* @example-org/example-teamdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..2ea2232--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,23 @@+# 参与协作++这个仓库是为 Agent-first 开发准备的,但这些规则对人和 Agent 都一样适用。++## 基本协作方式++- 从 `AGENTS.md` 开始,再按任务类型去读对应文档。+- 仓库级知识要落在版本化文件里,不要只存在聊天记录、口头同步或工单评论里。+- 如果行为变了,就一起更新代码、文档、测试和 release/history 记录。+- 遇到跨度大、风险高、会分多轮推进的任务,先在 `docs/exec-plans/active/` 下建 execution plan。++## 发起 Pull Request 之前++- 运行 `make check-docs`。+- 如果本次改动涉及代码或仓库流程,补齐或更新对应 history。+- 如果变更对用户可感知,补齐 release note。+- 确认示例、脚本、说明文档和当前实现一致。++## Review 默认要求++- 优先拆成范围清晰的小 PR。+- 明确写出风险点、迁移影响和后续待办。+- 如果上下文复杂,直接链接对应 plan、spec 或 history,不要依赖评审者自己猜。diff --git a/LICENSE b/LICENSEnew file mode 100644index 0000000..c631b4e--- /dev/null+++ b/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Leo++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/Makefile b/Makefilenew file mode 100644index 0000000..a179603--- /dev/null+++ b/Makefile@@ -0,0 +1,29 @@+PROJECT ?=+SLUG ?=++.PHONY: init check-docs check-repo ci release-package new-history new-plan++init:+ @if [ -z "$(PROJECT)" ]; then echo "用法: make init PROJECT=项目名"; exit 1; fi+ ./scripts/init-project.sh "$(PROJECT)"++check-docs:+ ./scripts/check-docs.sh++check-repo:+ ./scripts/check-docs.sh+ ./scripts/check-repo-hygiene.sh++ci:+ ./scripts/ci.sh++release-package:+ ./scripts/release-package.sh++new-history:+ @if [ -z "$(SLUG)" ]; then echo "用法: make new-history SLUG=变更名"; exit 1; fi+ ./scripts/new-history.sh "$(SLUG)"++new-plan:+ @if [ -z "$(SLUG)" ]; then echo "用法: make new-plan SLUG=计划名"; exit 1; fi+ ./scripts/new-exec-plan.sh "$(SLUG)"diff --git a/README.md b/README.mdnew file mode 100644index 0000000..be14b13--- /dev/null+++ b/README.md@@ -0,0 +1,18 @@+# open-codex-computer-use++## 简介++一个面向 Agent 协作开发的基础仓库模板,可以用来启动任何你想做的产品或服务。++## 快速开始++直接 clone 或 fork 这个仓库,然后把它作为新项目的起点,继续往里搭你真正要做的产品、服务或平台能力即可。++## 许可证++[MIT](./LICENSE)++## 备注++这套方法主要来自我们自己的持续实践和整理,同时也吸收了 OpenAI 在 harness engineering 文章中的一部分思路,最后汇总成了这个模板:+https://openai.com/index/harness-engineering/diff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 0000000..0743fe1--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,15 @@+# 安全策略++## 漏洞反馈++如果发现疑似安全漏洞,不要直接提公开 issue。++请通过你们组织内部约定的私有安全通道反馈,并尽量附上:++- 影响范围和潜在风险。+- 复现步骤或 PoC。+- 已知的缓解方式或临时绕过方案。++## 适用范围++这个仓库本身只是一个基础模板。基于它创建的新项目,应该把这里替换成自己真实的安全联系人和响应流程。diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdnew file mode 100644index 0000000..4790ec3--- /dev/null+++ b/docs/ARCHITECTURE.md@@ -0,0 +1,25 @@+# 架构总览++这份文档用于描述仓库的顶层结构。下面这些内容是模板占位,等新项目真正落地后,应该尽快替换成真实架构。++## 预期的仓库结构++- `apps/`:可部署的应用、服务或入口。+- `packages/`:跨应用复用的库、契约和共享能力。+- `infra/`:部署、基础设施和环境定义。+- `scripts/`:仓库级自动化脚本,供人和 Agent 直接调用。+- `docs/`:仓库知识库,也是本地规则和上下文的正式来源。++## 边界建议++- 业务逻辑优先沉淀到可复用包里,不要一开始就散落在各个 app 中。+- 基础设施和运行编排要显式版本化,不要藏在手工操作里。+- 避免隐式跨包耦合;一旦仓库成形,就把允许的依赖方向写清楚。+- 只要架构有变化,就同步更新这份文档。++## 新项目需要补齐的内容++- 核心产品面和运行拓扑。+- 包分层与依赖边界。+- 数据流与存储模型。+- 可观测性方案和本地开发模式。diff --git a/docs/CICD.md b/docs/CICD.mdnew file mode 100644index 0000000..4d6b0f9--- /dev/null+++ b/docs/CICD.md@@ -0,0 +1,36 @@+# CI/CD 说明++这个模板自带一套不依赖具体语言栈的 CI/CD 骨架。++## 默认包含的内容++- `ci.yml`:仓库级检查,覆盖 docs、repo hygiene、Markdown 和 shell 脚本校验。+- `supply-chain-security.yml`:依赖变更检查、OSV 扫描、SBOM 生成和 Scorecard 分析。+- `release.yml`:手动触发的 release 流水线,用来打包仓库级制品、生成 provenance,并创建 GitHub Release。++## 设计原则++这套默认流水线的目标,是在项目真正成形前先把交付链路搭起来,而不是假装已经知道未来项目该怎么 build 和 deploy。++当新项目的技术栈确定后,你应该把 `scripts/release-package.sh` 里的占位打包逻辑替换成真实构建产物,而不是另起一套平行流程。++所有 GitHub Actions 都已经 pin 到 commit SHA。后续升级 action 时,也要继续保持这个约束。++## 推荐接入顺序++1. 保留 `ci.yml`,作为仓库的基础门禁。+2. 在 `scripts/ci.sh` 里继续叠加项目自己的验证命令。+3. 用真实构建产物替换 `scripts/release-package.sh`。+4. 技术栈和环境稳定后,再补具体的部署 job。+5. 即使交付方式变化,SBOM 和 provenance 这类供应链能力也建议保留。++## 默认 release 产物++当前 release 流水线会产出:++- `release-manifest.json`+- `repo-metadata.tgz`+- `sbom.spdx.json`+- 对 release artifact 生成的 GitHub artifact attestation++也就是说,即使项目还没进入真实部署阶段,这个模板也已经把“可追溯的制品封装”这一步准备好了。diff --git a/docs/DESIGN.md b/docs/DESIGN.mdnew file mode 100644index 0000000..d62778c--- /dev/null+++ b/docs/DESIGN.md@@ -0,0 +1,10 @@+# 设计原则++这份文档用于沉淀产品层面相对稳定的设计原则。++建议放的内容包括:++- 整体视觉原则和交互目标。+- 字体、颜色、间距和组件系统的选择。+- 无障碍与响应式设计要求。+- 什么场景该复用共享组件,什么场景可以例外。diff --git a/docs/FRONTEND.md b/docs/FRONTEND.mdnew file mode 100644index 0000000..cbab558--- /dev/null+++ b/docs/FRONTEND.md@@ -0,0 +1,11 @@+# 前端协作说明++当仓库里真正有前端界面时,再把这份文档补完整。++建议在这里维护:++- 本地启动、构建和联调方式。+- 浏览器驱动的验收流程。+- 共享组件边界。+- 设计系统、样式变量和 CSS 规范。+- 前端测试策略。diff --git a/docs/HISTORY_GUIDE.md b/docs/HISTORY_GUIDE.mdnew file mode 100644index 0000000..70c2adb--- /dev/null+++ b/docs/HISTORY_GUIDE.md@@ -0,0 +1,31 @@+# 代码变更历史记录规范++`docs/histories/` 用来记录已经完成的代码变更任务。纯问答、调研、分析类任务默认不需要记 history,除非最后确实改了仓库内容。++## 基本要求++- 每个完成的代码变更任务,都应该对应一份 history 文件,或补充到同一任务既有的 history 文件里。+- 用户原始诉求可以适当压缩,但要保留关键信息。+- 不要把敏感信息、本地路径、密钥或原始日志细节直接写进去。+- 同一个任务跨多轮推进时,继续维护同一个 history,不要重复建文件。++## 目录与命名++- 目录:`docs/histories/YYYY-MM/`+- 文件名:`YYYYMMDD-HHmm-task-slug.md`+- 模板:`docs/histories/template.md`++示例:++```text+docs/histories/+ 2026-04/+ 20260408-1430-bootstrap-template.md+```++## 应该写什么++- 用户诉求原文,或者压缩后的脱敏版本。+- 本次主要代码与文档改动。+- 设计动机,以及为什么这么做。+- 最关键的受影响文件。diff --git a/docs/PLANS_GUIDE.md b/docs/PLANS_GUIDE.mdnew file mode 100644index 0000000..a238ff6--- /dev/null+++ b/docs/PLANS_GUIDE.md@@ -0,0 +1,24 @@+# Execution Plan 使用说明++execution plan 适合用在那些超出单轮聊天上下文、需要多次推进或风险较高的任务上。++## 什么时候该建 plan++- 任务会跨多个 commit 或多轮工作推进。+- 这次改动会影响架构、协议、数据迁移或其他高风险区域。+- 完成任务依赖阶段性验证、回滚策略或关键决策留痕。+- 可能会有多个人或多个 Agent 在一段时间内共同推进。++## 存放位置++- 进行中的 plan 放在 `docs/exec-plans/active/`+- 已完成的 plan 移到 `docs/exec-plans/completed/`+- 复用模板在 `docs/exec-plans/templates/execution-plan.md`+- 暂不处理但值得保留的债务放到 `docs/exec-plans/tech-debt-tracker.md`++## 维护要求++- 写清目标、范围、约束、风险和验证方式。+- 推进过程和关键决定要落在仓库里,不要只存在聊天记录里。+- 状态变化要同步更新。+- 过期 plan 要及时关闭、归档或清理,保证 active 目录可信。diff --git a/docs/PRODUCT_SENSE.md b/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..34e2e00--- /dev/null+++ b/docs/PRODUCT_SENSE.md@@ -0,0 +1,10 @@+# 产品判断原则++把那些能帮助 Agent 做出更好产品取舍的长期原则沉淀在这里。++建议覆盖的内容:++- 核心用户是谁。+- 产品真正有价值的点是什么。+- 当前阶段更看重哪些质量维度:速度、可信度、灵活性、成本、体验等。+- 在早期交付和成熟运营两个阶段,判断标准分别是什么。diff --git a/docs/QUALITY_SCORE.md b/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..b2e19ba--- /dev/null+++ b/docs/QUALITY_SCORE.md@@ -0,0 +1,20 @@+# 质量评分++用这份文档按产品区域和架构层次记录当前质量水位,方便持续知道最薄弱的地方在哪。++## 建议的评分标准++- `A`:覆盖完整、行为稳定、文档清楚、运行风险低。+- `B`:整体可接受,但还有明确短板。+- `C`:能用,但需要针对性补强。+- `D`:脆弱、缺少规范,或很多行为尚未定义。++## 初始模板++| 区域 | 评分 | 原因 | 下一步 |+| --- | --- | --- | --- |+| 产品面 | D | 还没有真实产品定义。 | 先明确第一个用户路径和验收标准。 |+| 架构文档 | C | 有基础骨架,但还没替换成项目真实信息。 | 补齐 `docs/ARCHITECTURE.md`。 |+| 测试 | D | 还没有接入项目自己的测试。 | 先补一条最小 smoke path。 |+| 可观测性 | D | 还没有日志、指标、链路的约定。 | 明确本地和 CI 怎么访问观测数据。 |+| 安全 | C | 默认约束已经有了,但具体实现还没落地。 | 根据项目接入真实认证、密钥和依赖治理。 |diff --git a/docs/RELIABILITY.md b/docs/RELIABILITY.mdnew file mode 100644index 0000000..f605394--- /dev/null+++ b/docs/RELIABILITY.md@@ -0,0 +1,13 @@+# 稳定性与可运维性++这里用来定义项目的运行质量底线。++建议维护的内容包括:++- 启动、健康检查和基本可用性要求。+- 日志、指标、链路的采集和访问约定。+- timeout、retry、backoff 的默认策略。+- 本地和 CI 的关键路径验证方式。+- 常见故障、排查路径和恢复步骤。++CI/CD 流程结构和 release 自动化的默认方案,统一写在 `docs/CICD.md`。diff --git a/docs/REPO_COLLAB_GUIDE.md b/docs/REPO_COLLAB_GUIDE.mdnew file mode 100644index 0000000..b484a15--- /dev/null+++ b/docs/REPO_COLLAB_GUIDE.md@@ -0,0 +1,45 @@+# 仓库协作约定++这份文档定义的是一个 Agent-first 仓库的默认协作方式。真正和技术栈强相关的约束,建议拆到相邻专题文档里维护,不要把这里写成大杂烩。++## 开发原则++- 优先选择简单、清晰、可观测的方案,不要堆难以维护的复杂度。+- 以 Agent 可读、可执行为目标组织仓库;重要信息如果只存在聊天记录和脑子里,等于不存在。+- 代码、文档、测试、配置和发布记录要尽量同源更新。+- 如果 Agent 在同一类问题上反复失败,优先修环境、修脚手架、修规范,不要把“多试几次 prompt”当主方案。+- 每次修 bug,都顺手检查测试和文档是否该补强,尽量让同类问题只修一次。++## 文档纪律++- `AGENTS.md` 只做路由,不要在里面堆一大坨规则。+- `docs/` 是仓库级知识的正式来源。+- 行为一旦变化,对应文档就要在同一次改动里同步更新。+- 比起继续往大文档里堆内容,更推荐新增一份边界清楚的小文档。++## Git 与评审++- commit 尽量保持范围清晰、描述准确。+- 提交或发 PR 前,确认文档、示例、脚本和 history 是否已经反映最终状态。+- 复杂或高风险改动,先落一份 execution plan 到 `docs/exec-plans/`。+- 评审里尽量引用仓库内文件,不要依赖只有少数人知道的上下文。++## 测试与验证++- 每次有实质性代码变更,都应该让验证能力比改之前更强一点。+- 优先沉淀成仓库里可直接运行的命令和脚本。+- 如果项目包含 UI,要保证本地能独立启动、验证。+- 如果项目依赖 logs、metrics、traces,最好能提供本地或 CI 可用的访问路径。+- 即使项目还没接入真实业务构建链路,仓库级 CI 也应该先能跑起来。++## CI/CD 与交付方式++- CI 至少要守住仓库可读性和基础安全,不要等项目变大后再补。+- CD 骨架应该优先产出明确制品和 provenance,而不是过早假设部署目标。+- 未来接入真实技术栈时,优先在现有流水线上扩展,不要另起一套临时脚本把它绕开。++## 配置卫生++- 示例配置和实际默认值要尽量一致。+- 所有启动所需的环境变量和外部依赖都要写清楚。+- 不要让关键初始化步骤只存在 README 的角落里,能脚本化就脚本化。diff --git a/docs/SECURITY.md b/docs/SECURITY.mdnew file mode 100644index 0000000..09e368f--- /dev/null+++ b/docs/SECURITY.md@@ -0,0 +1,13 @@+# 安全默认约束++这份文档用于把安全默认值讲清楚,避免实现逐步演进时越走越散。++建议维护的内容:++- 认证与授权约束。+- 密钥和环境变量管理方式。+- 依赖治理与供应链安全要求。+- 数据分级、脱敏与保留策略。+- 对外 API、Webhook、文件上传和沙箱执行的规则。++仓库级的依赖、SBOM 和 provenance 默认能力,统一写在 `docs/SUPPLY_CHAIN_SECURITY.md`。diff --git a/docs/SUPPLY_CHAIN_SECURITY.md b/docs/SUPPLY_CHAIN_SECURITY.mdnew file mode 100644index 0000000..90173b2--- /dev/null+++ b/docs/SUPPLY_CHAIN_SECURITY.md@@ -0,0 +1,35 @@+# 供应链安全++这份文档定义模板默认采用的供应链安全做法。++## 默认控制项++- 在 Pull Request 上做依赖变更审查。+- 用 OSV 对仓库中的依赖声明和 lockfile 做漏洞扫描。+- 为 release 产物生成 SBOM。+- 为 release 产物生成 build provenance attestation。+- 用 OpenSSF Scorecard 做仓库级安全姿态分析。+- 所有 GitHub Actions 都固定到不可变的 commit SHA,而不是漂移的版本标签。++## 当前对应关系++- `actions/dependency-review-action`:阻止 PR 引入高风险依赖变更。+- `google/osv-scanner-action`:根据仓库里的依赖文件扫描已知漏洞。+- `anchore/sbom-action`:生成 SPDX 格式的 SBOM。+- `actions/attest-build-provenance`:为 release artifact 生成签名 provenance。+- `ossf/scorecard-action`:分析仓库级安全信号,例如工作流权限、分支保护等。+- `scripts/check-action-pinning.sh`:如果 workflow 里出现浮动 tag 而不是 SHA,直接让 CI 失败。++## 限制和前提++- Dependency Review 在 public repo 可以直接使用;private repo 通常需要 GitHub Advanced Security 或对应的代码安全能力。+- OSV 和 SBOM 的效果依赖仓库里存在可识别的依赖清单或 lockfile。+- 只有当 `scripts/release-package.sh` 真的代表项目的构建产物时,provenance 才真正有意义。+- Scorecard 的结果也依赖仓库本身是否开启了分支保护、工作流权限收敛等真实配置。++## 项目落地后建议继续做的事++- 锁定并提交项目真实依赖的 lockfile。+- 让构建过程尽量可重复、可验证。+- 如果条件允许,在部署链路里增加对 provenance 的校验。+- 把 attestation 校验继续下沉到部署平台或准入层。diff --git a/docs/design-docs/core-beliefs.md b/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..5f2e197--- /dev/null+++ b/docs/design-docs/core-beliefs.md@@ -0,0 +1,12 @@+# 核心理念++这些理念用于约束这个模板在项目早期的默认方向。++## Agent-First 的工作原则++- 人来定方向,Agent 负责执行和推进。+- 仓库内可追溯的知识,比私有上下文更重要。+- Agent 反复失败时,优先修脚手架和环境,不是继续加 prompt 压力。+- 短而稳定的入口文档,比越来越长的大 prompt 更可靠。+- 能变成机械检查的约束,就不要只停留在口头规范。+- 速度很重要,但无节制地堆积熵会迅速拖垮效率,所以要持续整理和收口。diff --git a/docs/design-docs/index.md b/docs/design-docs/index.mdnew file mode 100644index 0000000..20ff742--- /dev/null+++ b/docs/design-docs/index.md@@ -0,0 +1,13 @@+# 设计文档索引++用这个目录集中管理架构设计和产品设计文档。++建议约定:++- 一个主题一份文档。+- 每份文档写清当前状态和简短摘要。+- 关联引入它的 execution plan 或 spec。++## 初始文档++- `core-beliefs.md`diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.mdnew file mode 100644index 0000000..c136f70--- /dev/null+++ b/docs/exec-plans/README.md@@ -0,0 +1,8 @@+# Execution Plans++这个目录用于存放长期任务的执行计划。++- 进行中的计划放在 `active/`+- 已完成的计划移到 `completed/`+- 新计划从 `templates/execution-plan.md` 开始+- 暂时不做但需要持续跟踪的问题放到 `tech-debt-tracker.md`diff --git a/docs/exec-plans/active/.gitkeep b/docs/exec-plans/active/.gitkeepnew file mode 100644index 0000000..8b13789--- /dev/null+++ b/docs/exec-plans/active/.gitkeep@@ -0,0 +1 @@+diff --git a/docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.md b/docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.mdnew file mode 100644index 0000000..bf2bc4a--- /dev/null+++ b/docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.md@@ -0,0 +1,75 @@+# Open Source Computer Use Reverse Engineering++## 目标++为 `open-codex-computer-use` 沉淀一套可追溯的逆向分析资料,先把 `SkyComputerUseClient`、`Codex Computer Use.app`、两者之间的宿主依赖与运行时边界分析清楚,再据此设计一版可开源实现。++## 范围++- 包含:+ - 分析闭源 `Codex Computer Use.app` bundle 结构、标识、权限与运行时行为。+ - 分析 `SkyComputerUseClient` 的入口、MCP 暴露方式、宿主依赖与失败模式。+ - 把结论持续沉淀到仓库 `docs/` 下的独立目录。+- 不包含:+ - 当前阶段不开始实现开源版代码。+ - 当前阶段不承诺完全复刻官方私有协议或 UI。++## 背景++- 相关文档:+ - `docs/references/codex-computer-use-reverse-engineering/README.md`+ - `docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md`+ - `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+ - `docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md`+- 相关代码路径:+ - `~/.codex/plugins/cache/openai-bundled/computer-use/1.0.750/`+ - `~/.codex/config.toml`+- 已知约束:+ - 官方 bundle 为闭源二进制,只能通过 bundle 结构、符号、strings、配置与本机运行痕迹做逆向分析。+ - 当前 `SkyComputerUseClient mcp` 不能被任意外部 MCP client 稳定直连。++## 风险++- 风险:把 strings/符号里的能力误判成当前真的启用的功能。+- 缓解方式:所有文档都区分“已观察事实”和“推断”,并尽量附上本机证据来源。++- 风险:把 Inspector 连接失败简单归因于单一原因。+- 缓解方式:同时记录 direct launch、Inspector、analytics、crash report 四类证据,避免过度下结论。++- 风险:后续实现过早锁死到官方私有架构。+- 缓解方式:持续分离“官方实现细节”和“开源版真正需要的能力边界”。++## 里程碑++1. 调研与方案收敛。+2. 逆向分析 client / service / IPC / 权限模型。+3. 基于分析结果收敛开源版架构与实现范围。++## 验证方式++- 命令:+ - `plutil -p .../Info.plist`+ - `otool -L ...`+ - `strings ... | rg ...`+ - `sqlite3 ~/Library/Group\ Containers/.../Analytics.db ...`+ - `codesign -dvv ...`+- 手工检查:+ - 对照 Inspector 连接现象与本地 crash report。+ - 对照 `~/.codex/config.toml` 与 `.mcp.json` 的 transport 配置。+- 观测检查:+ - 关注 `Analytics.db` 中的 service/client launch 事件。+ - 关注 `~/Library/Logs/DiagnosticReports/` 中的 crash 记录。++## 进度记录++- [x] 里程碑 1+- [ ] 里程碑 2+- [ ] 里程碑 3++## 决策记录++- 2026-04-17:先把长期逆向分析结果沉淀到 `docs/references/codex-computer-use-reverse-engineering/`,而不是分散在聊天上下文里。这样后续实现开源版时可以直接引用仓库内文档。+- 2026-04-17:当前先不实现代码,先把 client / service / host dependency 的边界分析清楚,避免一开始就沿着错误假设实现。+- 2026-04-17:曾在仓库里临时初始化 `uv` 和 Python `mcp` 依赖,用最小 Python SDK 复现实验验证 `stdio` 连接行为,而不是继续依赖 Inspector。+- 2026-04-17:上述 Python / `uv` 复现实验完成后,不再把这套一次性探针和运行链路保留在仓库里;长期保留的是文档中的证据和结论。+- 2026-04-17:把插件打包结构、`turn-ended` notify 生命周期和主 app 分发形态单独拆成文档,不和 runtime 宿主依赖混写,方便后续直接映射成开源版的接口边界。diff --git a/docs/exec-plans/completed/.gitkeep b/docs/exec-plans/completed/.gitkeepnew file mode 100644index 0000000..8b13789--- /dev/null+++ b/docs/exec-plans/completed/.gitkeep@@ -0,0 +1 @@+diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..212caad--- /dev/null+++ b/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,6 @@+# 技术债追踪++这里记录那些暂时不阻塞当前任务、但已经值得留档的技术债。++| 日期 | 区域 | 债务描述 | 为什么会存在 | 计划中的后续动作 |+| --- | --- | --- | --- | --- |diff --git a/docs/exec-plans/templates/execution-plan.md b/docs/exec-plans/templates/execution-plan.mdnew file mode 100644index 0000000..90e4e04--- /dev/null+++ b/docs/exec-plans/templates/execution-plan.md@@ -0,0 +1,43 @@+# <执行计划标题>++## 目标++用一段话说明最终想达到的状态。++## 范围++- 包含:+- 不包含:++## 背景++- 相关文档:+- 相关代码路径:+- 已知约束:++## 风险++- 风险:+- 缓解方式:++## 里程碑++1. 调研与方案收敛。+2. 分阶段实现。+3. 验证、交付与收尾。++## 验证方式++- 命令:+- 手工检查:+- 观测检查:++## 进度记录++- [ ] 里程碑 1+- [ ] 里程碑 2+- [ ] 里程碑 3++## 决策记录++- YYYY-MM-DD:做了什么决定,为什么这么做,会带来什么影响。diff --git a/docs/generated/README.md b/docs/generated/README.mdnew file mode 100644index 0000000..bd9ede3--- /dev/null+++ b/docs/generated/README.md@@ -0,0 +1,5 @@+# 自动生成文档++这个目录用于存放自动生成的仓库知识,比如 schema 快照、API 索引、依赖清单等。++所有生成产物都应该能追溯到对应命令或脚本,并且最好是可重复生成的。diff --git a/docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md b/docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.mdnew file mode 100644index 0000000..79dcb2d--- /dev/null+++ b/docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md@@ -0,0 +1,389 @@+## [2026-04-17 11:56] | Task: 沉淀 computer-use 逆向分析基础++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 分析 `SkyComputerUseClient` 和 `Codex Computer Use.app`,并把结果按仓库规则持续落到 `docs/` 的独立目录里,后续再根据收集结果考虑实现开源版。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Execution Plan]**: 新建长期执行计划,明确先调研、后实现的推进方式。+- **[Research Docs]**: 新建独立逆向分析目录,记录 baseline architecture 和 runtime / host dependency 结论。+- **[Docs Index]**: 更新 `docs/references/README.md`,把这组分析资料纳入仓库索引。+- **[Probe Script]**: 新增最小 `stdio` probe 脚本,用来直接复现 `SkyComputerUseClient mcp` 在 pipe/stdin 模式下的启动与退出行为。++### 🧠 Design Intent (Why)+这项工作跨多轮且涉及闭源 bundle 逆向分析,不能把核心结论留在聊天上下文里。先把长期计划和独立分析目录建起来,后面每轮都能在同一组文档里累积证据、修正判断,再收敛到开源实现方案。++### 📁 Files Modified+- `scripts/probe-cua-stdio.js`+- `docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.md`+- `docs/references/README.md`+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md`+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:10] | Task: 用 Python MCP SDK 直接复现 computer-use 直连失败++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 不用 Inspector,直接 init 一下 uv,然后用 Python MCP SDK 自己写个最小 client 去试。++### 🛠 Changes Overview+**Scope:** `pyproject.toml`, `uv.lock`, `scripts/`, `docs/`++**Key Actions:**+- **[UV Bootstrap]**: 初始化仓库级 `uv` Python 项目骨架,并安装 `mcp` 依赖。+- **[Python Probe]**: 新增 `scripts/probe_cua_mcp_python.py`,使用 Python `mcp` SDK 的 `stdio_client + ClientSession.initialize()` 做最小直连实验。+- **[Runtime Evidence]**: 通过 Python SDK 复现 `initialize` 阶段的 `BrokenResourceError`,并确认系统侧同时生成新的 `Launch Constraint Violation` crash report。+- **[Docs Sync]**: 将 Python SDK 复现路径和结论补充进逆向分析文档与 execution plan。++### 🧠 Design Intent (Why)+Inspector 包了一层代理和前端交互,失败面太大。用官方 Python MCP SDK 直接复现之后,可以把问题压缩到最小:`stdio` 进程拉起成功,但一到 `initialize` 写入阶段就断管,同时系统记录 launch constraint kill。这个证据链比 Inspector 更干净,适合继续逆向。++### 📁 Files Modified+- `pyproject.toml`+- `uv.lock`+- `scripts/probe_cua_mcp_python.py`+- `docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.md`+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:18] | Task: 收敛 Codex 宿主 IPC 与 parent constraint 证据++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Parent Constraint]**: 通过存活进程父链和签名信息确认,能长期存活的 `SkyComputerUseClient mcp` 基本都挂在 OpenAI Team ID `2DC432GLL2` 的 Codex 宿主进程下面。+- **[Appserver IPC]**: 通过 `lsof` 和 strings 确认 `SkyComputerUseService` 会连接 `Codex.app` 持有的 `codex-ipc/ipc-501.sock` Unix socket。+- **[Host Integration]**: 补充 service 中关于 `CodexAppServerJSONRPCConnection`、auth cache/provider、plugin 安装和 notify hook 更新的实现痕迹。++### 🧠 Design Intent (Why)+到这一步,问题已经不只是“外部 stdio 拉不起官方 client”,而是“官方 computer-use 依赖一个私有的 Codex 宿主 IPC 层”。把这层关系写清楚之后,开源版可以更明确地选择:直接去掉私有宿主耦合,而不是误把它当成 computer-use 内核的必要组成。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md`+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:04] | Task: 补充 computer-use tools schema++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 基于现有的分析,继续分析 codex computer use 的所有 tools 的 name 和参数;并把工具定义的 schema 用 code block 结构化整理进文档,方便查看。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Tool Schemas]**: 在 baseline architecture 文档中补全 `computer-use` 当前公开的 9 个 tools,并为每个 tool 增加结构化 code block schema。+- **[Runtime Notes]**: 基于当前会话实际调用 `list_apps` 和 `get_app_state` 的结果,补充返回形态和使用语义。+- **[Compatibility Notes]**: 增加面向开源兼容层的接口层判断,说明 `get_app_state`、`element_index` 和坐标模式的角色边界。++### 🧠 Design Intent (Why)+前一轮文档只确认了 tool 名单,没有把参数面和调用语义整理成能直接拿来设计兼容层的格式。把 schema 结构化落到仓库里之后,后续做开源 MCP 复刻时可以直接从这份文档抽接口,而不需要再回聊天记录里找零散结论。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:34] | Task: 补充打包结构与 turn-ended 生命周期集成++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Packaging Layout]**: 新增独立文档,记录官方插件根目录、`.codex-plugin/plugin.json`、`.mcp.json` 和主 app 的分发结构。+- **[Lifecycle Hook]**: 结合 `SkyComputerUseClient --help`、`~/.codex/config.toml` 和 `Codex` 宿主 strings,确认 `turn-ended` 是挂在 legacy notify / `after_agent` 生命周期上的回调入口。+- **[Distribution Evidence]**: 补充 `LSUIElement`、Sparkle 更新源、内嵌 resource bundles、application group container 和 provisioning profile 的观察结果。++### 🧠 Design Intent (Why)+前面的文档已经把 runtime 宿主依赖写清了,但“这个插件是怎么被 Codex 看见的”和“`turn-ended` 到底属于哪条生命周期链”还没有独立沉淀。把这层接口面单独整理出来后,后续设计开源版时就能更清楚地区分哪些是 MCP 能力本体,哪些只是官方宿主集成方式。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:47] | Task: 收敛 client-service 内部 IPC 面++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Internal IPC]**: 新增独立文档,整理 `ComputerUseIPC*` 类型族,确认 client 和 service 之间还存在一层独立于 MCP 的本地协议。+- **[Request Families]**: 收敛 `ListAppsRequest`、`AppGetSkyshotRequest`、`AppPerformActionRequest`、`AppModifyRequest`、`CodexTurnEndedRequest`、`AppUsageRequest` 等 request 族。+- **[Security Boundary]**: 补充 `ComputerUseIPCSenderAuthorization`、`CodeSignature`、`Requirement` 等 sender auth 证据,并记录 service 的 active-client / idle-timeout 自回收语义。++### 🧠 Design Intent (Why)+到这一步,官方实现已经很明显不是“一个 MCP server 直接碰系统 API”,而是至少有一层内部 IPC 把 MCP client 和桌面 automation service 隔开。把这层协议栈单独落文档后,后续开源版就能更明确地决定是否保留这层分离,以及如果保留,应如何把 sender auth 和 skyshot 模型设计成透明、可实现的开源方案。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/internal-ipc-surface.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:56] | Task: 用真实 tool 调用补强内部 IPC transport 判断++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Live Runtime Check]**: 通过一次真实 `computer-use` 的 `get_app_state(Finder)` 调用拉起 service,再用 `lsof`/`pgrep` 复查进程和句柄。+- **[Transport Evidence]**: 确认 service 侧持久可见的 Unix socket 仍然只有连接 Codex 宿主的 `codex-ipc/ipc-501.sock`,没有观察到 client-service 常驻 Unix socket。+- **[Inference Tightening]**: 把 client-service transport 的判断进一步收紧到“更像 XPC、短连本地通道,或其他不可见 transport”,避免误写成普通本地 socket。++### 🧠 Design Intent (Why)+前一轮虽然已经从类型名里确认了 `ComputerUseIPC*` 协议族,但 transport 形式还只是猜测。补一条真实调用期的运行时反证后,可以更明确地排除“client 和 service 之间长期维持一条普通 Unix socket”这种过度简化的实现想象。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/internal-ipc-surface.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 13:03] | Task: 收敛 turn-ended payload wire shape 与 caller 限制++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Wire Shape]**: 通过官方 `openai/codex` 开源仓库里的 `codex-rs/hooks/src/legacy_notify.rs`,确认 `notify` / `after_agent` 历史兼容 payload 的精确 JSON 结构。+- **[Lifecycle Mapping]**: 将该 JSON wire shape 映射回 `SkyComputerUseClient turn-ended <payload>`,把原先“很可能”升级成带源码依据的结论。+- **[Action-Time Validation]**: 本机直接从外部 shell 执行 `turn-ended` 的合法和非法 payload,均观察到 `status=137` 与 `Launch Constraint Violation` crash report,确认它也不属于任意 caller 可调用的独立 CLI。++### 🧠 Design Intent (Why)+之前我们已经知道 `turn-ended` 属于 lifecycle 集成,但还差两块硬证据:一是 payload 到底长什么样,二是它是否能被外部 caller 当作通用命令直接使用。把这两点都钉住之后,后续开源版就能更明确地把“生命周期通知的结构”与“官方受信宿主限制”拆开处理。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md`+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 13:10] | Task: 收紧 previous-notify 的边界判断++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续分析。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Core Comparison]**: 对照官方 `openai/codex` 开源核心的 `config/mod.rs`、`hooks/legacy_notify.rs`、`hooks/registry.rs`,确认核心 `notify` 机制本身只认 argv + 尾部 JSON payload,没有 `previous-notify` 概念。+- **[Boundary Tightening]**: 将 `--previous-notify` 的判断从“可能是链式参数”收紧为“更可能是 `SkyComputerUseClient turn-ended` 自己引入的兼容包装参数,而非 Codex 核心 hook API”。+- **[Open Question Update]**: 把未决问题聚焦到“这个参数的具体编码格式”而不是“它是否属于核心 notify 机制”。++### 🧠 Design Intent (Why)+这一步的价值在于把“官方宿主自己的兼容包装”与“Codex 核心公开 hook 机制”拆开。后续做开源版时,就不会误以为 `previous-notify` 是必须兼容的 Codex 核心协议字段,而会把它当成官方插件接管 notify 配置时的一个私有迁移细节。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:41] | Task: 收敛权限 onboarding 与拖拽引导窗口线索++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 我发现在授权的时候会做一个窗口,让用户直接可以拖动 codex computer use.app 进去,而不需要自己去找。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Permission Evidence]**: 收敛 `Accessibility`、`Screen Recording`、`TCCDialogSystemPermission`、`permissionsWindow`、`permissionState` 等 strings,确认权限 gating 和权限窗口都属于主 service 的内建能力。+- **[Accessory UI Evidence]**: 补充 `SystemSettingsAccessoryWindow`、`SystemSettingsAccessoryTransitionOverlayWindow`、`ArrowWindow`、`SystemSettingsAccessoryWindowDragDelegate` 等命名,确认官方围绕 System Settings 做了自定义辅助 UI。+- **[Drag Flow Inference]**: 记录 `DraggableApplicationView`、`dragDelegate`、`dragContinuation`、`draggable` 等命名,并将其与用户观察到的“把 app 拖进去授权”体验对应起来。+- **[Docs Index]**: 新增独立权限 onboarding 文档,并更新逆向资料目录索引。++### 🧠 Design Intent (Why)+这条发现把官方体验从“只是检测 TCC 权限”推进到了“围绕 macOS 授权流程做了一层产品化引导”。对开源实现来说,这个差异很重要,因为它决定了首轮权限配置是否顺畅,也决定了我们后续是否要复刻一层 System Settings accessory window,而不只是弹一句提示文案。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/permission-onboarding.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:46] | Task: 提取 computer-use 的视觉资源样本++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 可以,你怎么扣视觉资源?你试试看?++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Asset Extraction]**: 使用 AppKit `Bundle.image(forResource:)` 直接从官方 bundle 中导出 `SoftwareCursor`、`HintArrow`、`CUAAppIcon_Assets/cursor`、`CUAAppIcon_Assets/cursor dark` 和 `menubar-cursor` 等资源为 PNG。+- **[Verification]**: 记录导出文件的尺寸、透明通道和哈希;确认 `Package_SlimCore.bundle` 与 `Package_ComputerUse.bundle` 中的 `SoftwareCursor` 导出后二进制一致。+- **[Asset Archive]**: 将导出的 PNG 归档到 `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/`,并新增资产索引说明。+- **[Doc Linking]**: 在软件光标和权限 onboarding 两份文档中补上对提取资源的直接链接,方便后续查看与比对。++### 🧠 Design Intent (Why)+前面的分析虽然已经能从 strings 和窗口行为推断软件光标、权限箭头这些 UI 存在,但直接把资源抠出来后,结论就从“命名层面可信”升级成了“已有可点击、可比对的实际视觉资产”。这对后续复刻开源版体验非常有帮助,因为可以直接参考尺寸、复用关系和大致视觉方向。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/assets/README.md`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor-dark.png`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor.png`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/hint-arrow.png`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/menubar-cursor.png`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-computeruse.png`+- `docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-slimcore.png`+- `docs/references/codex-computer-use-reverse-engineering/permission-onboarding.md`+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++### Follow-up+- 将 `software-cursor-overlay.md` 和 `permission-onboarding.md` 里指向导出 PNG 的绝对本机路径链接改成仓库内相对路径,避免文档依赖作者机器目录结构。++## [2026-04-17 12:32] | Task: 分析黄色虚拟鼠标 overlay 的实现线索++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 现在工具调用足够了。然后我发现实际在使用中,codex computer use 会显化出一个黄色的小鼠标样式(应该就是一个浮动的图片,体验超级好,这样可以不抢用户的鼠标,但是同时又模拟出一个鼠标的动画,这个你能探测分析到么?)++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Resource Evidence]**: 补查 `Codex Computer Use.app` 的 `Assets.car` 和 `strings`,确认主 app 里存在 `cursor`、`cursor dark`、`menubar-cursor` 等资源命名,以及 `cursorWindow`、`imageView`、`Start Bezier cursor animation` 等实现线索。+- **[Runtime Probe]**: 用 `CGWindowListCopyWindowInfo` 直接枚举运行时窗口,确认 `Codex Computer Use` 进程名下存在一个名字就是 `Software Cursor` 的独立窗口。+- **[Behavior Check]**: 在安全的 Finder 点击前后比对 `Software Cursor` 的窗口坐标,确认它会随工具动作移动,而不是静态资源或菜单栏装饰。+- **[Docs Index]**: 新增独立文档专门收敛黄色虚拟鼠标 overlay 的事实和推断,并更新逆向资料目录索引。++### 🧠 Design Intent (Why)+这个黄色小鼠标是官方体验里非常关键的一层产品细节。把它从“感觉上像一个浮动图片”收敛成“`SkyComputerUseService` 持有的独立 `Software Cursor` 窗口”之后,后续开源实现就能更明确地把输入注入和视觉反馈拆成两套机制,而不是误以为必须直接操纵系统真实光标。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:21] | Task: 补充 computer-use tool call 实测样本++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 你有尝试调用所有的工具了么?最好是都能调用几次(比如针对不同的 app 或动作),比如 3 次,然后把调用的请求和响应结果都保存到 docs 里某个目录下,用作未来的参考。++### 🛠 Changes Overview+**Scope:** `docs/`++**Key Actions:**+- **[Live Samples]**: 对 `computer-use` 的 9 个公开 tools 做了实测,尽量为每个 tool 保留至少 3 个样本。+- **[Request/Response Archive]**: 新增独立 samples 文档,按 tool 归档 request / response code block,并注明截图省略和响应节选策略。+- **[Boundary Notes]**: 额外记录了 `get_app_state` 的 `appNotFound` 和 safety denial 两类边界响应,以及 `drag` 的 no-op 倾向样本。+- **[Docs Index]**: 更新逆向分析目录索引,把这份实测文档纳入当前文档列表。++### 🧠 Design Intent (Why)+只知道 tool schema 还不够,真正做兼容层时还要知道运行时响应是“纯状态快照”还是“只返回 OK”,以及不同工具的稳定性差异。把真实 request / response 样本沉淀进仓库后,后续实现和回归验证都可以直接拿这份文档当基线,而不需要重复手工试探。++### 📁 Files Modified+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/tool-call-samples-2026-04-17.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`++## [2026-04-17 12:51] | Task: 清理一次性 probe 脚本和临时 Python/uv 配套++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 帮我清理一下这个一次性脚本和配套的东西吧,好像还为此初始化了uv,uv也不要了,这不是python的repo++### 🛠 Changes Overview+**Scope:** `scripts/`, `docs/`++**Key Actions:**+- **[Probe Cleanup]**: 删除一次性的 Node / Python `stdio` probe 脚本,不再把它们作为仓库长期资产保留。+- **[Python Chain Removal]**: 移除为该实验临时引入的 `uv` 项目骨架和 Python 依赖文件。+- **[Docs Reframe]**: 把逆向文档和执行计划里的相关表述改成“历史实验结论”,不再暗示仓库当前仍维护 Python / `uv` 入口。+- **[History Sync]**: 在同一份 history 中补记这次清理,保留研究轨迹但收掉一次性实现残留。++### 🧠 Design Intent (Why)+这些脚本和 `uv` 初始化只服务于一次性的最小复现实验,不属于仓库长期边界。把证据留在文档里、把临时运行链路从仓库里拿掉,可以避免后续读者误把这里当成一个需要维护 Python 环境的多语言仓库。++### 📁 Files Modified+- `scripts/probe-cua-stdio.js`+- `scripts/probe_cua_mcp_python.py`+- `pyproject.toml`+- `uv.lock`+- `docs/exec-plans/active/20260417-open-source-computer-use-reverse-engineering.md`+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`+- `docs/histories/2026-04/20260417-1156-open-source-computer-use-research-foundation.md`diff --git a/docs/histories/2026-04/20260417-1258-prepare-initial-commit.md b/docs/histories/2026-04/20260417-1258-prepare-initial-commit.mdnew file mode 100644index 0000000..22b105d--- /dev/null+++ b/docs/histories/2026-04/20260417-1258-prepare-initial-commit.md@@ -0,0 +1,23 @@+## [2026-04-17 12:58] | Task: 准备首个提交++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `GPT-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 提交下所有改动,并且不要提交 `.idea/`。++### 🛠 Changes Overview+**Scope:** 仓库根目录, `docs/`++**Key Actions:**+- **[Git Ignore]**: 在根目录新增 `.gitignore`,忽略 `.idea/` 和 `.DS_Store`。+- **[Commit Prep]**: 保持当前仓库不引入 `.github/workflows`,按用户要求直接准备首个提交。++### 🧠 Design Intent (Why)+用户当前目标是尽快把现有仓库内容落成首个提交,同时排除本地 IDE 和系统垃圾文件,避免把开发机状态误提交进仓库。++### 📁 Files Modified+- `.gitignore`+- `docs/histories/2026-04/20260417-1258-prepare-initial-commit.md`diff --git a/docs/histories/template.md b/docs/histories/template.mdnew file mode 100644index 0000000..0990da2--- /dev/null+++ b/docs/histories/template.md@@ -0,0 +1,23 @@+## [YYYY-MM-DD HH:mm] | Task: <简短的任务动词>++### 🤖 Execution Context+* **Agent ID**: `如实填写`+* **Base Model**: `如实填写`+* **Runtime**: `如实填写`++### 📥 User Query+> {用户Query原文,或者压缩后的脱敏版本}++### 🛠 Changes Overview+**Scope:** (标注受影响的包)++**Key Actions:**+- **[Action 1]**: 简洁说明改动点 (e.g., 实现xxx)+- **[Action 2]**: (e.g., 优化了xxx消息转换逻辑)++### 🧠 Design Intent (Why)+*简洁直击要点的说明为什么要这么改?*++### 📁 Files Modified+- `path/to/src/core/file.ts`+- `path/to/src/pages/index.tsx`diff --git a/docs/product-specs/index.md b/docs/product-specs/index.mdnew file mode 100644index 0000000..0f76aa1--- /dev/null+++ b/docs/product-specs/index.md@@ -0,0 +1,10 @@+# 产品规格索引++这个目录用于记录面向用户行为的功能定义和工作流说明。++建议约定:++- 一个功能或流程一份 spec。+- 从用户问题和可见结果写起,不要一上来就写实现。+- 写清验收标准和外部可观察到的变化。+- 关联对应的 execution plan、release note 和架构调整。diff --git a/docs/references/README.md b/docs/references/README.mdnew file mode 100644index 0000000..9c1ad3e--- /dev/null+++ b/docs/references/README.md@@ -0,0 +1,17 @@+# 外部参考资料++这个目录用于沉淀那些值得长期放进仓库、供 Agent 直接读取的外部参考材料。++适合放这里的内容包括:++- 团队会反复依赖的框架、部署或接入说明。+- 设计系统参考、API 使用约定。+- 对外标准、合作方协议或外部文档的简要整理版。+- 闭源依赖、第三方二进制或外部工具的逆向分析与整理结论。++不要把大段供应商文档原样塞进来。这里应该是经过筛选和整理后的资料。++## 当前目录++- `codex-computer-use-reverse-engineering/`+ - 官方 `Codex Computer Use.app` / `SkyComputerUseClient` 的持续逆向分析资料。diff --git a/docs/references/codex-computer-use-reverse-engineering/README.md b/docs/references/codex-computer-use-reverse-engineering/README.mdnew file mode 100644index 0000000..e9e27d0--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/README.md@@ -0,0 +1,28 @@+# Codex Computer Use Reverse Engineering++这个目录用于持续沉淀官方闭源 `Codex Computer Use.app` 和 `SkyComputerUseClient` 的逆向分析结果,目标是为 `open-codex-computer-use` 的开源实现提供可追溯输入,而不是把关键上下文留在聊天记录里。++## 当前文档++- `baseline-architecture.md`+ - 当前已确认的 bundle 结构、入口、标识、transport 和模块分层。+- `runtime-and-host-dependencies.md`+ - 当前已观察到的运行时行为、宿主依赖、Inspector 直连失败现象和共享状态线索。+- `packaging-and-lifecycle-integration.md`+ - 当前已确认的插件打包结构、主 app 分发形态、CLI surface、`turn-ended` 生命周期接入方式。+- `internal-ipc-surface.md`+ - 当前已确认的 client-service 内部 IPC 类型、sender authorization、skyshot 模型和 service 生命周期线索。+- `tool-call-samples-2026-04-17.md`+ - 2026-04-17 对 9 个公开 `computer-use` tools 的实测 request / response 样本。+- `software-cursor-overlay.md`+ - 对黄色虚拟鼠标 overlay 的资源、字符串和运行时窗口证据分析。+- `permission-onboarding.md`+ - 对 Accessibility / Screen Recording 权限引导和 System Settings accessory window 的分析。+- `assets/README.md`+ - 直接从官方 bundle 导出的可视资源归档,包括 `SoftwareCursor`、`HintArrow` 和 cursor icon 资产。++## 使用约定++- 优先写“已观察事实”,再写“推断”。+- 尽量注明证据来源,例如 bundle 文件、analytics、crash report、`strings`/`otool`/`codesign`。+- 如果后续结论推翻了旧判断,直接改文档,不保留过期说法。diff --git a/docs/references/codex-computer-use-reverse-engineering/assets/README.md b/docs/references/codex-computer-use-reverse-engineering/assets/README.mdnew file mode 100644index 0000000..79e702f--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/assets/README.md@@ -0,0 +1,24 @@+# Extracted Visual Assets++这个目录存放从官方 `Codex Computer Use.app` bundle 中直接导出的可视资源,用来支撑逆向分析文档里的视觉层结论。++## 当前归档++- `extracted-2026-04-17/hint-arrow.png`+ - 从 `Package_SlimCore.bundle` 导出的 `HintArrow` 资源,尺寸 `57x66`。+- `extracted-2026-04-17/software-cursor-slimcore.png`+ - 从 `Package_SlimCore.bundle` 导出的 `SoftwareCursor` 资源,尺寸 `200x230`。+- `extracted-2026-04-17/software-cursor-computeruse.png`+ - 从 `Package_ComputerUse.bundle` 导出的 `SoftwareCursor` 资源,尺寸 `200x230`;与 `SlimCore` 版本二进制一致。+- `extracted-2026-04-17/appicon-cursor.png`+ - 从主 app `Assets.car` 中导出的 `CUAAppIcon_Assets/cursor`,尺寸 `1024x1024`。+- `extracted-2026-04-17/appicon-cursor-dark.png`+ - 从主 app `Assets.car` 中导出的 `CUAAppIcon_Assets/cursor dark`,尺寸 `1024x1024`。+- `extracted-2026-04-17/menubar-cursor.png`+ - 从主 app bundle 导出的 `menubar-cursor`,尺寸 `19x17`。++## 说明++- 这些文件不是截图,而是直接从 bundle 资源加载并转存为 PNG。+- 当前导出方式基于 AppKit `Bundle.image(forResource:)`,适合提取已经命名的 asset。+- 权限 onboarding 的大部分 UI 仍然更像 SwiftUI / 窗口组合逻辑,而不是一组大量静态图片,因此目前能导出的“权限视觉资源”主要是 `HintArrow`。diff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor-dark.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor-dark.pngnew file mode 100644index 0000000..e10332aBinary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor-dark.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor.pngnew file mode 100644index 0000000..adf3155Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/hint-arrow.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/hint-arrow.pngnew file mode 100644index 0000000..7b72afbBinary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/hint-arrow.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/menubar-cursor.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/menubar-cursor.pngnew file mode 100644index 0000000..1e1e95eBinary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/menubar-cursor.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-computeruse.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-computeruse.pngnew file mode 100644index 0000000..7b0e0e1Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-computeruse.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-slimcore.png b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-slimcore.pngnew file mode 100644index 0000000..7b0e0e1Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-slimcore.png differdiff --git a/docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md b/docs/references/codex-computer-use-reverse-engineering/baseline-architecture.mdnew file mode 100644index 0000000..679f4a3--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md@@ -0,0 +1,354 @@+# Baseline Architecture++## 已观察事实++### 1. 组件拆分++当前官方 bundle 至少包含两层可执行组件:++- `Codex Computer Use.app`+ - 可执行文件:`SkyComputerUseService`+ - bundle identifier:`com.openai.sky.CUAService`+- `Codex Computer Use.app/Contents/SharedSupport/SkyComputerUseClient.app`+ - 可执行文件:`SkyComputerUseClient`+ - bundle identifier:`com.openai.sky.CUAService.cli`++这说明官方实现不是单一二进制,而是 service app 和 client app 分层。++### 2. Codex 当前如何接入++本机插件配置显示,Codex 不是直接调 service,而是通过内置 client 以 `stdio` 模式拉起 MCP server:++```json+{+ "mcpServers": {+ "computer-use": {+ "command": "./Codex Computer Use.app/Contents/SharedSupport/SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient",+ "args": ["mcp"],+ "cwd": "."+ }+ }+}+```++结合本机日志,当前集成方式可以确认是:++- server name:`computer-use`+- origin:`stdio`+- transport:`stdio`++### 3. client 的命令行入口++`SkyComputerUseClient --help` 显示它至少有两个子命令:++- `mcp`+ - 说明文字:`Runs the Computer Use client as an MCP server`+- `turn-ended`+ - 说明文字:`Handles a Codex turn-ended notification`++这说明 client 不只是 MCP 包装层,还显式参与了“turn 结束”这类会话生命周期事件。++本机 `~/.codex/config.toml` 里还能看到:++```toml+notify = ["/Users/.../SkyComputerUseClient", "turn-ended"]+```++这说明 Codex 在本机确实把 `turn-ended` 当作全局通知入口来调用,而不是一个未使用的调试命令。++### 4. service / client 共享安全边界++service 和 client 共享同一个 application group:++- `2DC432GLL2.com.openai.sky.CUAService`++两者 entitlement 中都出现:++- `com.apple.security.application-groups`+- `com.apple.security.automation.apple-events`++这说明它们属于同一安全边界,预计会共享持久化状态、权限状态或 IPC 配置。++### 5. service 二进制暴露出的能力面++`SkyComputerUseService` 中能稳定观察到以下能力模块:++- 权限与引导:+ - `CUAServicePermissionState`+ - `CUAServicePermissionsWindow`+ - `SystemSettingsAccessoryWindow`+- Accessibility / UI 树:+ - `AXNotificationObserver`+ - `SystemFocusedUIElementObserver`+ - `KeyWindowTracker`+ - `WindowOrderingObserver`+- 屏幕截图与窗口层:+ - `ScreenCaptureKit`+ - `SCScreenshotManager`+ - `SCShareableContent`+ - `WindowBoundsObserver`+- 输入与交互:+ - `EventTap`+ - `clickEventTap`+ - `keyboardEventTap`+ - `drag`+ - `scroll`+- 可视化层:+ - `ComputerUseCursor`+ - `FogCursorStyle`+ - `virtualCursor`+- MCP 支持:+ - `MCP/Server.swift`+ - `MCP/StdioTransport.swift`+ - `MCP/StatefulHTTPServerTransport.swift`+ - `MCP/StatelessHTTPServerTransport.swift`+ - `MCP/SSEClientTransport.swift`++### 6. 当前公开可见的 tools++strings 和运行时都指向同一组 tools:++- `list_apps`+- `get_app_state`+- `click`+- `perform_secondary_action`+- `scroll`+- `drag`+- `type_text`+- `press_key`+- `set_value`++### 7. 当前会话可见的 tool schema++下面这组 schema 以当前 Codex 会话真实暴露的 MCP tool 定义为准,并结合一次运行时调用结果补充使用语义。++#### `list_apps`++```json+{}+```++- 无参数。+- 返回当前机器上正在运行或近 14 天使用过的 app 列表。+- 返回文本中会包含 app 名、bundle identifier、`running` 状态、`last-used` 和 `uses`。++#### `get_app_state`++```json+{+ "app": "string"+}+```++- `app`:app 名或 bundle identifier。+- 作用是启动或复用 app use session,并返回当前主窗口状态。+- 运行时返回至少包含:+ - app 标识和 pid+ - 窗口层级和 accessibility tree+ - 每个 element 的索引号+ - element 的 role、value、description、`settable` 等属性+ - `Secondary Actions`+ - 当前窗口截图++#### `click`++```json+{+ "app": "string",+ "element_index": "string?",+ "x": "number?",+ "y": "number?",+ "click_count": "integer? = 1",+ "mouse_button": "\"left\" | \"right\" | \"middle\" ? = \"left\""+}+```++- `app`:目标 app。+- `element_index`:按 accessibility element 定位点击目标。+- `x` / `y`:按截图像素坐标点击目标。+- `click_count`:点击次数,默认 `1`,可用于 double-click 或 triple-click。+- `mouse_button`:鼠标按键,默认 `left`。+- 接口语义上,`element_index` 和 `x` / `y` 是两套寻址方式,通常应二选一。++#### `perform_secondary_action`++```json+{+ "app": "string",+ "element_index": "string",+ "action": "string"+}+```++- `app`:目标 app。+- `element_index`:目标 accessibility element。+- `action`:element 当前暴露的 secondary action 名称。+- `action` 不是固定枚举,必须来自 `get_app_state` 输出中的 `Secondary Actions`。++#### `scroll`++```json+{+ "app": "string",+ "direction": "string",+ "element_index": "string",+ "pages": "integer? = 1"+}+```++- `app`:目标 app。+- `direction`:工具说明约束为 `up` / `down` / `left` / `right`。+- `element_index`:必须是可滚动的 element。+- `pages`:滚动页数,默认 `1`。+- 这是 element-scoped scroll,不是全局屏幕滚动。++#### `drag`++```json+{+ "app": "string",+ "from_x": "number",+ "from_y": "number",+ "to_x": "number",+ "to_y": "number"+}+```++- `app`:目标 app。+- `from_x` / `from_y`:拖拽起点像素坐标。+- `to_x` / `to_y`:拖拽终点像素坐标。+- 当前公开接口里,拖拽只支持坐标,不支持 `element_index`。++#### `type_text`++```json+{+ "app": "string",+ "text": "string"+}+```++- `app`:目标 app。+- `text`:要输入的字面文本。+- 更适合普通文本录入,不负责表达快捷键语义。++#### `press_key`++```json+{+ "app": "string",+ "key": "string"+}+```++- `app`:目标 app。+- `key`:按键或组合键,采用 `xdotool key` 风格。+- 工具说明示例包括:+ - `a`+ - `Return`+ - `Tab`+ - `super+c`+ - `Up`+ - `KP_0`++#### `set_value`++```json+{+ "app": "string",+ "element_index": "string",+ "value": "string"+}+```++- `app`:目标 app。+- `element_index`:目标 settable element。+- `value`:要直接写入的值,当前 schema 中统一为字符串。+- 这是比 `type_text` 更语义化的输入方式,适合 search field、text field 等可直接赋值控件。++## 当前推断++### 1. 官方实现的最小分层++当前最合理的分层判断是:++- `SkyComputerUseService`+ - 权限管理、状态栏、窗口/光标 overlay、系统集成、Accessibility、截图、审批与会话状态+ - 还负责和 Codex appserver 的宿主 IPC、notify hook 和 plugin 生命周期集成+- `SkyComputerUseClient`+ - MCP 入口、turn 生命周期桥接、和 service 的本地通信++### 2. transport 能力和当前启用状态不是一回事++虽然 service / client 二进制中能看到 HTTP、SSE、network 相关 MCP transport 符号,但当前安装包的真实启用方式仍然只有 `stdio`。开源版设计时不能直接假设官方对外公开了 HTTP/SSE server。++补充一点:当前 Node MCP SDK 的 `stdio` framing 是 newline-delimited JSON,而不是 `Content-Length`。这意味着开源版如果要优先兼容主流 Node client,最直接的做法也是先把 JSON line `stdio` 路径打稳。++再补一层:官方实现里不只是“stdio 启一个本地 server”这么简单。`SkyComputerUseService` 还会主动连接 Codex 宿主维护的 `codex-ipc` Unix socket,并在里面处理 thread-end、auth 和 plugin 集成。这说明开源版如果没有官方宿主,也应该明确删掉这类私有 appserver 依赖,而不是半复制一个绑定宿主的结构。++### 3. 开源版不必复制官方的所有产品壳++从能力上看,真正必须复现的是:++- app 发现+- 窗口截图+- Accessibility 树读取+- 鼠标键盘动作+- 权限引导+- 会话状态和审批模型++### 4. 当前 tool 面是一个以 Accessibility tree 为中心的最小接口层++当前这组公开 tools 可以压缩成三层:++- 发现:+ - `list_apps`+- 读状态:+ - `get_app_state`+- 做动作:+ - `click`+ - `perform_secondary_action`+ - `scroll`+ - `drag`+ - `type_text`+ - `press_key`+ - `set_value`++这说明官方当前暴露的是一套很小的 automation kernel,而不是完整的桌面控制 API。++### 5. `element_index` 是第一公民,坐标只是补充定位方式++大部分交互类工具都围绕 `get_app_state` 产出的 accessibility tree 工作:++- `perform_secondary_action`+- `scroll`+- `set_value`+- `click` 的主要模式++只有少数动作明显是纯几何操作:++- `drag`+- `click` 的 `x` / `y` 模式++这意味着官方实现优先依赖 AX 语义定位,而不是把 screenshot 当主导航面。++### 6. 开源兼容层最好保留聚合型 `get_app_state`++当前公开接口没有单独的:++- `launch_app`+- `screenshot`+- `get_ax_tree`+- `wait`+- `hover`++而是把“必要时拉起 session + 读取窗口树 + 读取截图”合并到了 `get_app_state`。如果开源版目标之一是兼容现有 agent 使用习惯,保留这个聚合入口会更稳。++状态栏、虚拟光标、PIP 一类的产品壳可以晚于核心 automation path。++## 对开源版的直接启发++- MCP server 可以单独设计成公开、稳定、可被任意 client 拉起的入口,不必复用官方那种宿主绑定方式。+- service/client 的边界应该尽早显式化,否则后续很容易被私有宿主约束反噬。+- transport、权限、Automation 内核、UI/overlay 最好拆成独立模块,避免逆向时看到的多层耦合直接复制进开源实现。+- 开源版 schema 可以直接对齐这 9 个 tools 作为兼容层第一版,再在实现内部拆成 app discovery、AX snapshot、screen capture、input dispatcher 和 approval/session manager。diff --git a/docs/references/codex-computer-use-reverse-engineering/internal-ipc-surface.md b/docs/references/codex-computer-use-reverse-engineering/internal-ipc-surface.mdnew file mode 100644index 0000000..e4abb05--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/internal-ipc-surface.md@@ -0,0 +1,313 @@+# Internal IPC Surface++## 已观察事实++### 1. service 和 client 之间至少存在一套单独的 ComputerUse IPC 协议++在 `SkyComputerUseService` 和 `SkyComputerUseClient` 两个二进制里,都能稳定看到同一组类型名:++- `ComputerUseIPCClient`+- `ComputerUseIPCServer`+- `ComputerUseIPCRequest`+- `ComputerUseIPCEmptyResponse`+- `ComputerUseIPCApp`+- `ComputerUseIPCAppState`+- `ComputerUseIPCDiscoveredApp`++这说明除了:++- client 对外的 MCP 协议+- service 对 Codex appserver 的宿主 IPC++之外,官方实现内部还单独维护了一层 `ComputerUseIPC*` 协议,负责 client 和 service 之间的本地调用。++### 2. 内部 IPC request 类型已经可以从符号名里拼出一版能力表++当前在两个二进制里都能看到的 request 类型包括:++- `ComputerUseIPCListAppsRequest`+- `ComputerUseIPCAppStartRequest`+- `ComputerUseIPCAppModifyRequest`+- `ComputerUseIPCAppPerformActionRequest`+- `ComputerUseIPCAppGetSkyshotRequest`+- `ComputerUseIPCCodexTurnEndedRequest`+- `ComputerUseIPCAppUsageRequest`++再结合字段名和 MCP tool 行为,当前最稳妥的映射是:++- `ListAppsRequest`+ - 对应外部 `list_apps`+- `AppGetSkyshotRequest`+ - 对应外部 `get_app_state`+ - `Skyshot` 很像“截图 + AX tree + 结构化状态”的内部表示+- `AppPerformActionRequest`+ - 对应 `click` / `perform_secondary_action` / `set_value` / `scroll` / `drag` / `press_key` / `type_text`+- `AppModifyRequest`+ - 至少包含 `activate` / `deactivate`+- `CodexTurnEndedRequest`+ - 对应 `turn-ended` 生命周期回调++### 3. `get_app_state` 在内部大概率不是“直接返回 app state”,而是“取一份 skyshot”++当前 strings 中同时出现:++- `ComputerUseIPCAppState`+- `ComputerUseIPCSkyshot`+- `ComputerUseIPCSkyshotResult`+- `ComputerUseIPCAppGetSkyshotRequest`+- `SkyshotCapture`+- `RefetchableSkyshotAXTree`+- `SkyshotClassifier`++这说明官方实现内部更像是:++1. 先对目标 app 取一份 `Skyshot`+2. 再从 `Skyshot` 里构建截图、窗口和 AX tree+3. 最后由 client 组装成对 MCP 层暴露的 `get_app_state` 返回值++这里的关键点是:++- 外部 MCP API 叫 `get_app_state`+- 但内部的核心抽象更接近 `skyshot`++这对开源版是个重要提示:++- 如果要复刻官方行为,核心内部模型可能不该直接叫 `AppState`+- 更合理的是“截图采集结果 + AX 树 + 目标 app 元数据”的复合对象++### 4. action 执行内部统一走 `AppPerformActionRequest`++当前可见的字段和 coding keys 包括:++- `ComputerUseIPCAction`+- `ComputerUseIPCLocationSpecifier`+- `CoordinateCodingKeys`+- `ElementIDCodingKeys`+- `ClickCodingKeys`+- `PerformSecondaryActionCodingKeys`+- `SetValueCodingKeys`+- `ScrollCodingKeys`+- `DragCodingKeys`+- `PressKeyCodingKeys`+- `TypeCodingKeys`++同时还能看到字段名:++- `coordinate`+- `elementID`+- `action`+- `text`+- `mouseButton`+- `clickCount`++这说明内部 action 层大概率已经统一成:++- 一个 action 枚举+- 一个 location specifier+ - 坐标模式+ - 元素 ID 模式+- 若干具体 action payload++也就是说,外部 7 个动作型 tools 在内部未必是一组完全分离的方法,更像是同一条 `performAction` 通道上的不同变体。++### 5. app 生命周期内部和工具动作是分开的++当前还能看到:++- `ComputerUseIPCAppStartRequest`+- `ComputerUseIPCAppModifyRequest`+- `Modification`+- `ActivateCodingKeys`+- `DeactivateCodingKeys`+- `active`+- `currentApp`+- `isRunning`++这说明官方内部把下面两类操作拆开了:++- app 级生命周期+ - 启动+ - 激活+ - 取消激活+- UI action+ - click / type / scroll / drag / ...++这和外部 MCP 面不完全一致,因为外部当前没有公开:++- `activate_app`+- `deactivate_app`+- `start_app`++但 service 内部显然保留了这层能力。++### 6. sender authorization 是内部 IPC 的显式组成部分++`SkyComputerUseService` strings 里可见:++- `ComputerUseIPCSenderAuthorization`+- `ProcessIdentity`+- `CodeSignature`+- `Requirement`+- `SecurityError`+- `Sender process is not authenticated`++这说明 client-service 之间的内部 IPC 并不是“谁都能连上的本地 socket 调用”,而是显式校验发送方身份的。++结合前面已确认的事实:++- client 本身有 parent launch constraints+- 外部 `python3` / `node` caller 会被系统 kill++当前更合理的判断是:++- 发送方认证不仅发生在 macOS launch constraint 层+- service 自己的内部 IPC 层也有一层 sender authorization / code signature requirement 校验++### 7. system permission gating 也是内部 IPC request 的一部分++`SkyComputerUseService` strings 里还能看到:++- `ComputerUseIPCPermissionResult`+- `ComputerUseIPCRequestRequiringSystemPermissions`+- `ensureApplicationHasPermissions`+- `Failed to request access to permission: %@`+- `Failed to open System Settings for permission: %@`++这说明内部 IPC 请求里已经分化出一类:++- 需要系统权限的请求++也就是说,官方实现不是单纯在外层 UI 里判断“有没有 Accessibility / Screen Recording 权限”,而是把权限需求并入了内部 request pipeline。++### 8. service 会跟踪 active IPC client,并在为空时自杀++`SkyComputerUseService` strings 里直接有:++- `No active Computer Use IPC client processes; terminating service`+- `Codex Computer Use idle timeout reached; terminating service`++这说明 service 的生命周期不是长期 daemon,而是至少同时受两类条件控制:++- 是否还有活跃的 IPC client+- 是否触发 idle timeout++因此官方 service 更像:++- on-demand 启动+- 有使用时保活+- 无人连接或空闲超时后自回收++### 9. service 和 client 都弱链接了 `libswiftXPC`++`otool -L` 能看到:++- `libswiftXPC.dylib (weak)`++但目前还没有观察到:++- 明确的 mach service 名+- `launchd` 服务注册名+- 可直接枚举到的公开 XPC endpoint++所以当前只能确认:++- 两者具备使用 Swift XPC 的依赖条件++不能确认:++- 当前 `ComputerUseIPC*` 是否真的建立在 XPC 之上++### 10. app 使用行为和审批状态有独立对象++当前还能看到:++- `ComputerUseIPCAppUsageRequest`+- `AppApprovalStore`+- `sessionApprovedBundleIdentifiers`+- `approvedBundleIdentifiers`+- `bundleIdentifiersWithDeliveredInstructions`++这说明内部至少区分了三类状态:++- app 使用记录 / ranking+- session 级审批+- instruction 是否已经向某 app 投递过++这比“全局开一个 computer-use 权限开关”要细很多。++### 11. 在真实 tool 调用期间,仍然没有看到 client-service 之间的常驻 Unix socket++在实际调用一次 `get_app_state(Finder)` 之后,重新查看进程与句柄:++- `SkyComputerUseService`+ - 仍然只稳定持有一条 Unix socket+ - 对端是 `Codex.app` 的 `codex-ipc/ipc-501.sock`+- 多个存活的 `SkyComputerUseClient mcp`+ - 可见句柄基本只有:+ - stdio pipe 或 TTY+ - `Analytics.db`+ - 少量系统控制句柄+ - 没有观察到稳定的 client-service Unix socket++同时 service 还能看到:++- `No active Computer Use IPC client processes; terminating service`++所以当前更稳妥的结论是:++- service 会跟踪 active IPC client+- 但这个 client-service transport 至少不是一个容易通过 `lsof -U` 看到的常驻 Unix socket++这进一步支持以下几种可能性之一:++- XPC / NSXPC+- 每次请求短连、很快关闭的本地通道+- 其他由系统服务包装、不直接体现在普通 socket 句柄上的 transport++## 当前推断++### 1. 官方内部大概率是“三层协议栈”,而不是单一 MCP server++更符合现有证据的分层是:++1. Codex appserver IPC+ - service 和 Codex 宿主的私有 JSON-RPC / thread event 集成+2. ComputerUse IPC+ - client 和 service 之间的本地受信请求协议+3. MCP+ - client 对外暴露给 Codex agent runtime 的标准工具面++这解释了为什么:++- 外部看上去只是一条 `SkyComputerUseClient mcp`+- 但实际运行里还会出现 parent constraints、sender auth、service idle timeout、thread-ended cleanup++### 2. `get_app_state` 只是外部 API 名称,内部核心对象更像 `Skyshot`++开源版如果要追求结构清晰,内部最好也拆成:++- app targeting+- screenshot capture+- AX tree extraction+- app state serialization++而不是一上来就把所有逻辑耦合进一个 `get_app_state()` 函数里。++### 3. 公开 tools 比内部能力更保守++当前内部已可见但外部未公开的能力至少包括:++- app start+- app activate / deactivate+- app usage tracking++这说明官方公开的 9 个 tools 是一个更保守的产品化裁剪,不等于 service 的全部能力。++## 当前未决问题++- `ComputerUseIPC*` 这层最终到底走 XPC、NSXPC、私有 socket,还是别的本地 transport?+- `AppStartRequest` 在什么场景会被真正使用,是否只用于首个 app 会话建立?+- `AppUsageRequest` 是纯 analytics / ranking,还是也参与审批和安全策略?+- `Skyshot` 的精确定义是什么,是否包含屏幕截图、窗口元数据、AX 树和 URL 等全部上下文?+- sender authorization 的 requirement 是否直接绑定到 OpenAI Team ID,还是还有更细的 bundle / code requirement 约束?+- 如果不是 XPC,client-service 的本地 transport 为什么在真实调用期间仍然几乎不可见?diff --git a/docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md b/docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.mdnew file mode 100644index 0000000..15ee476--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/packaging-and-lifecycle-integration.md@@ -0,0 +1,440 @@+# Packaging And Lifecycle Integration++## 已观察事实++### 1. 官方 computer-use 插件根目录非常薄,只暴露一个 MCP server++`~/.codex/plugins/cache/openai-bundled/computer-use/1.0.750/` 当前可见内容主要只有:++- `.codex-plugin/plugin.json`+- `.mcp.json`+- `Codex Computer Use.app`+- `assets/app-icon.png`++没有观察到:++- `.app.json`+- `skills/`+- `hooks.json`++其中 `.mcp.json` 很直接:++```json+{+ "mcpServers": {+ "computer-use": {+ "command": "./Codex Computer Use.app/Contents/SharedSupport/SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient",+ "args": ["mcp"],+ "cwd": "."+ }+ }+}+```++这说明对 Codex 插件系统来说,官方 `computer-use` 当前主要是:++- 一个带 UI 元数据的插件包+- 一个通过嵌套 client app 暴露的本地 MCP server++不是“带 skills + app connector + hooks 的复合插件”。++### 2. plugin manifest 暴露的是产品界面信息,不是额外运行时能力++`.codex-plugin/plugin.json` 中可以确认:++- 名称:`computer-use`+- 版本:`1.0.750`+- `mcpServers` 指向 `./.mcp.json`+- `interface.displayName` 为 `Computer Use`+- `interface.brandColor` 为 `#0F172A`+- `interface.defaultPrompt` 内置了 3 个示例 prompt++没有观察到:++- 额外 app manifest 路由+- 额外 skills 注册+- 单独的 hook 文件++这进一步说明官方插件面向宿主暴露的核心集成面仍然是 `mcpServers`。++### 3. 主 app 是菜单栏 / 后台 app,并带自更新能力++`Codex Computer Use.app/Contents/Info.plist` 当前可确认:++- `CFBundleIdentifier = com.openai.sky.CUAService`+- `CFBundleExecutable = SkyComputerUseService`+- `LSUIElement = 1`+- `CFBundleVersion = 750`+- `LSMinimumSystemVersion = 15.0`++同时还能看到 Sparkle 更新字段:++- `SUFeedURL = https://oaisidekickupdates.blob.core.windows.net/mac/cua/alpha/appcast.xml`+- `SUPublicEDKey = 5Yw9jMXMH6O3mJZmpFuQT6ECfC3ZKBfVjWUVMNrElRo=`++这说明官方 service app 不是单纯临时 helper,而是:++- 作为一个独立 macOS app 分发+- 以菜单栏 / agent app 形态后台运行+- 可以通过 Sparkle 独立更新++### 4. bundle 内部有三组资源包,对应不同职责层++主 app 的 `Contents/Resources/` 下当前可见:++- `Package_ComputerUse.bundle`+- `Package_ComputerUseClient.bundle`+- `Package_SlimCore.bundle`++结合 strings,可得到较稳定的职责切分:++- `Package_ComputerUse.bundle`+ - 更偏 service 主体逻辑+ - 包含 `CodexAppServerThreadEventObserver`+ - 包含 `CodexAppServerAuthCache`+ - 包含 `CodexAppServerJSONRPCConnection`+- `Package_ComputerUseClient.bundle`+ - 更偏 MCP client / approval / tool 层+ - 包含 `ComputerUseMCPServer`+ - 包含 `AppApprovalStore`+ - 包含 `ComputerUseIPCClient`+- `Package_SlimCore.bundle`+ - 更偏基础设施与权限 UX+ - 包含 `SystemSettingsAccessCoordinator`+ - 包含 `SystemSettingsAccessoryWindow`+ - 包含 `SystemPermission` / `TCCDialogSystemPermission`++这里的结论仍然基于 strings,而不是源码级确认,但它已经足以支撑一个较清晰的三层划分:++- `ComputerUse`: 宿主集成和核心能力+- `ComputerUseClient`: MCP 暴露和审批状态+- `SlimCore`: 通用权限、系统设置引导和部分基础设施++### 5. `SkyComputerUseClient` 对外 CLI 只公开两个子命令++直接执行:++```text+SkyComputerUseClient --help+```++得到:++```text+USAGE: cua <subcommand>++SUBCOMMANDS:+ mcp+ turn-ended+```++继续查看:++```text+SkyComputerUseClient mcp --help+```++只有:++```text+USAGE: cua mcp+```++而:++```text+SkyComputerUseClient turn-ended --help+```++显示:++```text+USAGE: cua turn-ended [--previous-notify <previous-notify>] <payload>+```++这说明当前正式暴露的 CLI surface 很小:++- `mcp`+ - 启动本地 MCP server+- `turn-ended`+ - 处理 Codex turn 生命周期通知++### 6. client 二进制内嵌了完整 MCP transport 实现,但 CLI 没把它们公开出来++`SkyComputerUseClient` strings 中能看到:++- `mcp.transport.stdio`+- `mcp.transport.http.client`+- `mcp.transport.http.server.stateful`+- `mcp.transport.http.server.stateless`+- `mcp.transport.sse`+- `mcp.transport.in-memory`++以及对应日志:++- `HTTP transport connected`+- `Stateful HTTP server transport started`+- `Stateless HTTP server transport started`+- `Connecting to SSE endpoint`++但结合 `--help` 的结果,目前没有观察到任何 CLI 参数允许:++- 选择 HTTP transport+- 选择 SSE transport+- 打开一个外部可连的 HTTP server++因此当前更稳妥的判断是:++- 这些 transport 来自其内嵌 MCP SDK / 共享库能力+- 不是官方当前对外支持的连接方式++### 7. `turn-ended` 明确接在 Codex 的 legacy notify 生命周期上++本机 `~/.codex/config.toml` 当前包含:++```toml+notify = ["/Users/.../SkyComputerUseClient", "turn-ended"]+```++同时能观察到:++- `SkyComputerUseClient turn-ended --help`+ - 需要 `<payload>`+ - 可选 `--previous-notify`+- `SkyComputerUseService` strings+ - `onTurnEnded`+ - `Codex thread ended or stopped conversationID=%s`+ - `Failed to update Codex Computer Use notify hook: %@`+- `Codex` 宿主 strings+ - `hooks/src/legacy_notify.rs`+ - `legacy notify payload is only supported for after_agent`+ - `agent-turn-complete`+ - `thread-id`+ - `turn-id`+ - `cwd`+ - `client`+ - `input-messages`+ - `last-assistant-message`++这串证据合在一起已经比较明确:++- `turn-ended` 不是给外部用户手工调用的通用命令+- 它是 Codex 宿主在 `after_agent` / `agent-turn-complete` 阶段回调的 lifecycle hook+- `<payload>` 很可能就是 Codex legacy notify 体系下的 after-agent payload+- `--previous-notify` 则很像“保留并串联原有 notify hook”的迁移参数++再补一条来自官方 `codex` 开源源码的对照证据:++- `core/src/config/mod.rs`+ - `notify` 只是一个 argv 数组+- `hooks/src/legacy_notify.rs`+ - Codex 只会把 JSON payload 作为最后一个 argv 参数追加出去+- `hooks/src/registry.rs`+ - `legacy_notify_argv` 直接注册为 `after_agent` hook++开源核心里没有出现:++- `previous-notify`+- “链式 notifier”+- “包装旧 notify hook” 的通用机制++因此当前更强的推断是:++- `--previous-notify` 不是 Codex 核心 hook API 的一部分+- 它更可能是 `SkyComputerUseClient turn-ended` 自己额外引入的兼容参数+- 其目的很可能是:官方 computer-use 在接管 `notify` 配置时,把原有 notifier 通过 `--previous-notify` 保存下来,再由 client 在 turn 结束时选择性继续调用++### 8. `turn-ended` 的 payload 结构现在可以从官方 `codex` 开源源码直接确认++官方 `openai/codex` 仓库里的 `codex-rs/hooks/src/legacy_notify.rs` 当前实现是:++- `notify` 配置会在每次完成一轮 agent turn 后触发+- Codex 会把一个 JSON 字符串作为“最后一个 argv 参数”追加给 notifier+- 该 payload 仅适用于 `after_agent`++源码里的 `UserNotification::AgentTurnComplete` 当前字段为:++```json+{+ "type": "agent-turn-complete",+ "thread-id": "<string>",+ "turn-id": "<string>",+ "cwd": "<string>",+ "client": "<string|null>",+ "input-messages": ["<string>", "..."],+ "last-assistant-message": "<string|null>"+}+```++源码测试里给出的历史兼容 wire shape 也是:++```json+{+ "type": "agent-turn-complete",+ "thread-id": "b5f6c1c2-1111-2222-3333-444455556666",+ "turn-id": "12345",+ "cwd": "/Users/example/project",+ "client": "codex-tui",+ "input-messages": [+ "Rename `foo` to `bar` and update the callsites."+ ],+ "last-assistant-message": "Rename complete and verified `cargo build` succeeds."+}+```++因此现在已经可以把前面的“很可能”收紧成更明确的判断:++- `turn-ended <payload>` 的 `<payload>` 至少和 Codex 现行 `legacy_notify` 的 after-agent JSON wire shape 高度一致+- `type` 的值就是 `agent-turn-complete`+- 这条命令不是一般性的自由表单输入,而是宿主生命周期事件的结构化负载++### 9. 外部 shell 直接执行 `turn-ended` 也会被 launch constraint kill++本机直接执行以下两种命令:++- 合法 JSON payload+- 非法 JSON payload++两者都得到:++```text+status=137+```++也就是子进程收到 `SIGKILL`。++对应最新 crash report 中可见:++- `exception = SIGKILL (Code Signature Invalid)`+- `termination.namespace = CODESIGNING`+- `indicator = Launch Constraint Violation`++这说明从外部 shell 直接调用 `turn-ended` 时,进程在进入可观察的业务层 parse / validate 之前,就已经被系统以 launch constraint 杀掉了。++因此当前还不能通过外部 shell fuzzing 去区分:++- 这个命令是否先 parse payload+- parse 失败会不会给出用户态错误++因为 caller 还没被官方宿主信任链放行。++### 10. 共享 container 当前只看到 analytics,而没看到审批或 auth 主存储++当前 app group container:++- `~/Library/Group Containers/2DC432GLL2.com.openai.sky.CUAService/`++可见内容非常少:++- `.com.apple.containermanagerd.metadata.plist`+- `Library/Application Support/Software/Analytics.db`++目前没有在这个 container 里观察到:++- approvals 持久化文件+- auth token 文件+- 显式的 service/client 协调状态文件++这说明到目前为止更像是:++- analytics 确实走 app group 共享+- 审批、turn 生命周期、宿主状态更可能通过进程内或 IPC 传递++### 11. client 有 parent launch constraints,主 app 没观察到同级限制++`codesign -d -r- -vvvv SkyComputerUseClient.app` 可见:++- `Launch Constraints: Has Parent Launch Constraints`+- 资源里有 `SkyComputerUseClient_Parent.coderequirement`+- requirement 当前可读到 `team-identifier = 2DC432GLL2`++而主 app `Codex Computer Use.app` 的同类输出中,目前没看到相同的 parent launch constraint 行。++这和运行时现象一致:++- 外部 `python3` / `node` 直接 pipe 拉起 client 会触发 launch constraint kill+- 长期存活的 client 基本由 OpenAI 签名的 Codex 宿主拉起++### 12. provisioning profile 和实际 container/entitlement 呈现不完全一致++从 `embedded.provisionprofile` 中可读到:++- Team: `OpenAI OpCo, LLC`+- TeamIdentifier: `2DC432GLL2`+- `ProvisionsAllDevices = 1`+- `keychain-access-groups = ["2DC432GLL2.*"]`++同时还可读到 application groups:++- service profile:+ - `group.com.openai.sky.CUAService`+ - `2DC432GLL2.*`+- client profile:+ - `group.com.openai.sky.Service`+ - `group.com.openai.sky.CUAService`+ - `2DC432GLL2.*`++但 `codesign --entitlements :-` 输出里,当前签名 entitlements 呈现的是:++- `2DC432GLL2.com.openai.sky.CUAService`++再对照真实 group container,又看到:++- `~/Library/Group Containers/2DC432GLL2.com.openai.sky.CUAService/`++因此目前能确认的是:++- OpenAI 确实给这组 bundle 配了 application group / keychain group+- 真实可见 container 标识是 `2DC432GLL2.com.openai.sky.CUAService`++但还不能仅根据 provisioning profile 的文本展示,断言所有 group 名称在运行时的精确匹配关系。++## 当前推断++### 1. 官方发布物其实分成三层++更符合现有证据的分层是:++- 插件层+ - `.codex-plugin/plugin.json`+ - 面向 Codex 插件市场与 UI 呈现+- client 层+ - `SkyComputerUseClient mcp`+ - 面向 Codex MCP runtime+- service 层+ - `Codex Computer Use.app`+ - 面向 macOS 权限、桌面 automation 和宿主 lifecycle++开源版如果没有官方宿主,最应该复刻的是:++- client 对外 MCP contract+- service 对本地 automation 的最小能力++而不一定要复刻:++- Sparkle 更新+- 私有插件自安装+- legacy notify 链接法+- 私有 appserver socket++### 2. `turn-ended` 是开源版需要显式重设计的接口,而不是照抄++在官方体系里,`turn-ended` 是:++- 宿主生命周期集成的一部分+- 和 `notify` 配置、旧 hook 串联、per-turn 回收相关++开源版如果没有官方 Codex 宿主,应该把这层改成更透明的方案,例如:++- 显式的 `session/end` MCP 方法+- service 侧超时和清理策略+- 或纯客户端无状态实现++而不是要求用户再去配置一个私有语义的 `notify` hook。++## 当前未决问题++- `--previous-notify` 的精确值格式是什么?是原始命令字符串、argv 序列化结果,还是某种配置引用?+- `AppApprovalStore` 的真实持久化位置在哪里,为什么当前 app group container 里没有明显文件?+- `Package_SlimCore` 除权限 UX 外是否还承载了更多跨产品基础设施?+- client 二进制虽然带了 HTTP/SSE transport,但官方为什么没有公开这些入口,是产品选择还是宿主限制?diff --git a/docs/references/codex-computer-use-reverse-engineering/permission-onboarding.md b/docs/references/codex-computer-use-reverse-engineering/permission-onboarding.mdnew file mode 100644index 0000000..da63e22--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/permission-onboarding.md@@ -0,0 +1,189 @@+# Permission Onboarding++这个文档聚焦 Codex Computer Use 的系统权限引导体验,尤其是两类权限:++- `Accessibility`+- `Screen & System Audio Recording`++以及一个更具体的问题:它是否真的做了一个自定义窗口,引导用户把 `Codex Computer Use.app` 直接拖进授权区域,而不是只把用户丢到系统设置里自己找。++结论先写在前面:当前证据已经足够确认,官方实现不只是“检测权限然后打开 System Settings”。它内建了一套权限状态机和专门的 `SystemSettingsAccessoryWindow` 引导 UI;你看到的“可直接拖 app 进去”的体验,和二进制里出现的 `DraggableApplicationView`、`dragDelegate`、`ArrowWindow`、`TransitionOverlayWindow` 这些命名是高度一致的。++## 已观察事实++### 1. 权限 gating 是 service 内部的一等能力++`SkyComputerUseService` strings 里可见:++```text+ComputerUseIPCPermissionResult+ComputerUseIPCRequestRequiringSystemPermissions+ensureApplicationHasPermissions+Failed to request access to permission: %@+Failed to open System Settings for permission: %@+```++这说明权限不是外层随手做的前置检查,而是被并入了内部 request pipeline。++### 2. 官方明确跟踪两类核心权限++同一份 strings 里同时出现:++```text+accessibility+screenRecording+screen_recording+AccessibilityPermission+TCCDialogSystemPermission+Privacy_Accessibility+Privacy_ScreenCapture+```++结合此前真实 `System Settings` 样本里已经观察到的 `Screen & System Audio Recording` 页面,可以确认官方实现至少明确围绕:++- Accessibility+- Screen Recording / Screen & System Audio Recording++做权限 gating 和系统设置跳转。++### 3. 用户可见文案就是一套权限引导页,而不只是系统弹框++`SkyComputerUseService` 中可见一组连续的引导文案:++```text+Codex Computer Use needs these permissions to use apps on your Mac.+These permissions are only used when you ask Codex to perform tasks.+Allows Codex to access app interfaces+Codex uses screenshots to know where to click+COMPLETE IN SYSTEM SETTINGS+```++这说明主 app 里存在一层自己的权限说明界面。++### 4. 存在独立的权限窗口状态与回调++strings 里还能看到:++```text+permissionState+permissionsWindow+permissionsPending+permissionsNotGranted+onGrantAccessibility+onGrantScreenRecording+onOpenAccessibilitySettings+onOpenScreenRecordingSettings+```++这组命名已经不只是“去打开某个系统页”,而是说明它内部有:++- 权限窗口对象+- 权限状态机+- 分权限种类的 grant/open 回调++### 5. `SlimCore` 里有专门的 System Settings 引导窗口体系++当前已有的 strings 证据能直接看到:++```text+SystemSettingsAccessCoordinator+SystemSettingsAccessoryWindow+SystemSettingsAccessoryWindowView+SystemSettingsAccessoryWindowDragDelegate+SystemSettingsAccessoryTransitionOverlayWindow+SystemSettingsAccessoryTransitionOverlayReplicantWindow+SystemSettingsAccessoryTransitionBackground+ArrowWindow+```++这说明官方不是简单 `open x-apple.systempreferences:` 完事,而是围绕 System Settings 做了整套 accessory / overlay / transition UI。++### 6. “把 app 拖进去”的体验有直接命名证据++最关键的一组命名是:++```text+SystemSettingsAccessoryWindowView.DraggableApplicationView+dragDelegate+dragContinuation+draggable+ArrowWindow+```++这里的 `DraggableApplicationView` 几乎已经把实现意图写明白了:++- 会显示一个“可拖拽的应用视图”+- 配有 drag delegate+- 还有 arrow window 指示用户拖向目标区域++这和你观察到的“窗口里直接可以拖动 `Codex Computer Use.app` 进去,不需要自己去找 app”高度一致。++目前还能直接从 `Package_SlimCore.bundle` 导出一张和这套引导强相关的箭头资源:++- [hint-arrow.png](assets/extracted-2026-04-17/hint-arrow.png)++它对应的 asset 名就是 `HintArrow`,尺寸 `57x66`,与 `ArrowWindow` / `SystemSettingsAccessoryWindow` 这组命名非常吻合。++## 当前推断++### 1. 权限流程大概率分成两层++当前最合理的结构是:++- `SkyComputerUseService`+ - 检查权限状态+ - 决定当前缺哪项权限+ - 打开对应的 System Settings 页面+ - 管理 permission window 生命周期+- `SlimCore`+ - 提供具体的 accessory window / overlay / drag UI+ - 用箭头、过渡遮罩和 draggable app view 引导用户完成系统设置里的最后一步++### 2. 你看到的拖拽窗口更像官方自定义引导壳,不是系统原生默认界面++原因很直接:++- 系统设置本身不会暴露 `DraggableApplicationView` 这种命名给第三方 app。+- `ArrowWindow`、`TransitionOverlayWindow`、`permissionsWindow` 都属于官方 bundle 的内部符号。+- 文案 `COMPLETE IN SYSTEM SETTINGS` 暗示是“本 app 先解释,再把最后一步交给系统设置”。++所以更合理的解释是:++- 真实授权最终仍然发生在 macOS 的 TCC / System Settings 里;+- 但官方 app 在旁边叠加了一层辅助窗口,减少用户自己找入口、找 app、找拖拽目标的成本。++### 3. Accessibility 的拖拽引导证据比 Screen Recording 更强++从语义上看:++- `Accessibility` 页面本来就更符合“把 app 拖进允许列表”的交互。+- `Screen Recording` / `Screen & System Audio Recording` 常见的是切换条目或确认重新打开 app。++因此当前更强的推断是:++- `DraggableApplicationView` 这套交互至少服务于 Accessibility 授权;+- 是否也完全同样用于 Screen Recording,还需要额外动态观察才能百分百确认。++## 为什么这套体验很重要++这说明官方在产品层面并不满足于“把用户踢去系统设置自己想办法”。它专门补了一层:++- 权限解释+- 精准跳页+- 拖拽引导+- 回到 app 后的状态收敛++对开源实现来说,这个点很关键,因为它直接影响首轮授权成功率和用户挫败感。++## 还没完全确认的点++- 当前没有现场抓到权限 onboarding 窗口的运行时截图,因为本机此时权限已经授予。+- `DraggableApplicationView` 是否仅用于 Accessibility,还是也参与了 Screen Recording 引导,暂时仍是推断。+- 还没有从 `Assets.car` 中把这套权限 UI 的具体视觉资源完整提取出来。++## 对开源实现的启发++- 不要只做“检查失败就提示用户手动去系统设置”。+- 应该把权限流程单独建模成状态机,而不是散落在工具调用失败分支里。+- 最好提供面向具体系统页面的辅助窗口,尤其是 Accessibility 这种步骤多、路径深的授权流程。+- 把“打开系统设置”和“最后一步如何完成”拆开设计,体验会比纯文案提示好很多。diff --git a/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md b/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.mdnew file mode 100644index 0000000..868f8eb--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md@@ -0,0 +1,334 @@+# Runtime And Host Dependencies++## 已观察事实++### 1. `SkyComputerUseClient mcp` 不是任意外部 client 都能直连++在本机上直接执行:++```text+SkyComputerUseClient mcp+```++如果直接用一次性 shell 命令执行,它可能很快退出;但在 PTY 下保持 `stdin` 打开时,进程可以持续存活并等待输入。++这说明:++- `mcp` 子命令真实存在。+- 单看“一次性 shell 执行很快结束”不能直接推出宿主校验失败,其中有一部分只是 `stdin`/EOF 行为。++### 2. Inspector 直连的失败模式++用 MCP Inspector 以 `stdio` 方式拉起时,出现过两类失败:++- 参数填错时:+ - `spawn -y ENOENT`+ - 这是 Inspector 配置错误,不是 server 本身问题。+- 命令改对后:+ - Inspector 建好了 stdio client/server transport+ - 随后对方很快断开,Inspector 侧报 `write EPIPE`++`EPIPE` 在这里说明 child process 已经退出,Inspector 往其 stdin 写入初始化消息时管道已断。++### 3. 外部 pipe/stdin 拉起会触发 codesigning kill++在本机上分别用以下方式拉起:++- `node` 的 `child_process.spawn(..., stdio: ['pipe', 'pipe', 'pipe'])`+- `python3` 的 `subprocess.Popen(..., stdin=PIPE, stdout=PIPE, stderr=PIPE)`+- Python MCP SDK 的 `stdio_client(...)`++都能稳定复现:++- 子进程很快收到 `SIGKILL`+- 父进程侧看到 `Broken pipe` 或 `EPIPE`+- Python MCP SDK 路径上,`stdio_client` 先成功进入 `spawn`,但在 `ClientSession.initialize()` 写入阶段抛出 `anyio.BrokenResourceError`++与之对照:++- 在 PTY 下直接运行 `SkyComputerUseClient mcp`,进程可以常驻等待输入++这说明当前 bundle 至少区分了:++- 交互式终端拉起+- 外部进程经由 pipe/stdin 的自动化拉起++### 4. Inspector / Node / Python SDK 尝试都会留下 crash report++`~/Library/Logs/DiagnosticReports/` 中可见多份 `SkyComputerUseClient-2026-04-17-1142xx.ips`,这些 crash report 的共同特征是:++- `parentProc`: `node` 或 `python3`+- `exception`: `SIGKILL (Code Signature Invalid)`+- `termination.namespace`: `CODESIGNING`+- `indicator`: `Launch Constraint Violation`++目前只能确认:++- 某些通过外部自动化 caller 以 pipe/stdin 拉起的 client 进程会被系统以 launch constraint violation 杀掉。+- Python MCP SDK 的最小复现并没有绕过这个约束,它和 Node / Inspector 的根因一致。++目前还不能确认:++- 这是否是“外部 caller 无法直连”的唯一原因。++原因是 PTY 场景下 client 可以正常存活,而 crash report 主要和 pipe/stdin 自动化拉起路径绑定。++### 5. 能稳定存活的 client 都挂在 OpenAI 签名的 Codex 进程下面++当前机器上长期存活的 `SkyComputerUseClient mcp` 进程,其父进程主要有两类:++- `/Applications/Codex.app/Contents/Resources/codex app-server --analytics-default-enabled`+- Homebrew 安装的 `codex` 二进制:+ - `/opt/homebrew/lib/node_modules/@openai/codex/.../codex`++这两类父进程的共同点是:++- TeamIdentifier 都是 `2DC432GLL2`++与之对照:++- `python3` 作为父进程时,client 会因 `Launch Constraint Violation` 被系统 kill。++这进一步支持当前判断:++- parent launch constraint 很可能不是泛化意义上的“任意 shell/任意本地 caller”,而是要求父进程满足 OpenAI 自家的签名边界。++### 6. client 明确包含宿主 / 认证相关字符串++`SkyComputerUseClient` 的 strings 中可以直接看到:++- `Sender process is not authenticated`+- `Could not find Service app`+- `sessionApprovedBundleIdentifiers`+- `approvedBundleIdentifiers`+- `ComputerUseIPCClient`+- `ComputerUseIPCRequest`+- `ComputerUseIPCAppState`+- `ComputerUseIPCAppPerformActionRequest`++这些字符串说明 client 至少显式考虑了:++- 发送方身份认证+- service app 的定位+- 基于 session 的 app 审批状态+- 本地 IPC 请求模型++### 7. service 明确连接到 Codex appserver 的 Unix socket++当官方 `computer-use` tool 被真实调用并把 service 拉起后,可以直接观察到:++- `SkyComputerUseService` 打开了一个匿名 Unix socket FD+- 对端是 `Codex.app` 进程持有的:+ - `/var/folders/.../T/codex-ipc/ipc-501.sock`++本机 `lsof` 已确认:++- `SkyComputerUseService` 的 Unix socket peer 指向 `Codex.app`+- `Codex.app` 自身持有并监听 `codex-ipc/ipc-501.sock`++这是当前最直接的本地 IPC 证据之一。++### 8. service 二进制里已经明确出现 Codex appserver IPC 语义++`SkyComputerUseService` strings 中直接包含:++- `CodexAppServerThreadEventObserver`+- `CodexAppServerJSONRPCConnection`+- `CodexAppServerAuthCache`+- `CodexAppServerAuthProvider`+- `Connected to Codex appserver IPC socket at %s`+- `Failed to connect to Codex appserver IPC socket:`+- `Codex appserver IPC connection closed before a complete frame was read`+- `Codex thread ended or stopped conversationID=%s`++这说明 service 和 Codex 宿主之间不是松散关系,而是明确存在一个 appserver IPC / JSON-RPC 集成层。++### 9. service 里还能看到 plugin / notify hook 自安装痕迹++`SkyComputerUseService` strings 里还能看到:++- `Failed to update Codex Computer Use notify hook: %@`+- `Failed to install Codex Computer Use plugin: %@`+- `Skipping Codex Computer Use self-install for plugin-managed app.`+- `Couldn't find running Codex app, falling back to using Codex CLI in PATH via /usr/bin/env`+- `Found codex CLI executable in running Codex application at %{public}s`++这说明 service 至少承担了:++- 向 Codex 宿主安装 / 更新 plugin+- 更新 `turn-ended` notify hook+- 在 `Codex.app` 和 `codex` CLI 两种宿主之间做发现和回退++### 10. 官方 MCP stdio framing 是 JSON line++从本机 Inspector 附带的 `@modelcontextprotocol/sdk` 可以确认,当前 Node SDK 的 stdio transport 使用的是一行一个 JSON-RPC message:++```js+export function serializeMessage(message) {+ return JSON.stringify(message) + '\\n';+}+```++也就是说,当前官方 Node SDK 的 stdio MCP 不是 `Content-Length` framing,而是 newline-delimited JSON。++这条结论曾通过一次临时 Python 复现实验进一步钉住。实验路径是:++1. 用 Python `mcp` SDK 的 `stdio_client` 拉起 `SkyComputerUseClient mcp`+2. `stdio_client` 先成功进入 `spawn`+3. `ClientSession.initialize()` 写入时发生 `BrokenResourceError`+4. 系统侧生成新的 `SkyComputerUseClient-*.ips`,终止原因仍为 `Launch Constraint Violation`++后续清理仓库时,这个一次性 Python / `uv` 探针已经移除,因为该仓库不维护 Python 运行链路;这里保留的是实验结论,而不是当前可执行入口。++### 11. service / client 共享 application group++两者 entitlement 中都声明了同一个 application group:++- `2DC432GLL2.com.openai.sky.CUAService`++本机对应 group container 中当前可见内容包括:++- `~/Library/Group Containers/2DC432GLL2.com.openai.sky.CUAService/Library/Application Support/Software/Analytics.db`++### 12. shared analytics 能看到 launch 事件++`Analytics.db` 中已经观察到这些事件:++- `$set`+- `cua_service_launched`+- `computer_use_mcp_server_launched`+- `cua_service_idle_timeout_reached`++这说明:++- service 和 client 至少共享一套 analytics/持久化层。+- service 存在 idle timeout 概念,不是永久前台常驻工作模式。+- 至少这次 Python SDK 复现实验没有留下新的 `computer_use_mcp_server_launched` 事件,说明它可能在 client 完成自报启动前就已被系统 kill。++### 13. `turn-ended` 很可能走独立 IPC 请求++`SkyComputerUseClient` 的 strings 里能看到:++- `ComputerUseIPCCodexTurnEndedRequest`+- `ComputerUseCodexTurnEndedCommand`+- `CodexTurnEndedNotification`++再结合 `~/.codex/config.toml` 的:++```toml+notify = ["/Users/.../SkyComputerUseClient", "turn-ended"]+```++当前可以确认:++- `turn-ended` 不是无意义的占位命令。+- client 至少为“Codex 一轮结束”定义了单独的 IPC 请求模型。++### 14. client 自身带有 parent launch constraint++`codesign -d --verbose=5 SkyComputerUseClient.app` 能直接看到:++- `Launch Constraints:`+ - `Has Parent Launch Constraints`++同时 bundle 中还存在:++- `Contents/Resources/SkyComputerUseClient_Parent.coderequirement`++该文件当前是一个 plist,至少声明了:++- `team-identifier = 2DC432GLL2`++这说明外部 caller 受限并不是纯应用层策略,而是 bundle 签名 / launch constraint 的一部分。++### 15. 外部 shell 直接执行 `turn-ended` 也同样会触发 launch constraint kill++本机直接从 shell 执行:++- `SkyComputerUseClient turn-ended '<valid-json>'`+- `SkyComputerUseClient turn-ended '{bad-json}'`++两者都返回:++```text+status=137+```++同时最新 crash report 中可见:++- `exception`: `SIGKILL (Code Signature Invalid)`+- `termination.namespace`: `CODESIGNING`+- `indicator`: `Launch Constraint Violation`++这说明:++- 受限的不只是 `mcp` 子命令+- `turn-ended` 这个 lifecycle 子命令在外部 shell 场景下也走同一套受信 caller 限制++因此现在不能把 `turn-ended` 当成“对外可独立调用的调试入口”。++### 16. 目前还没有看到公开暴露的 socket / launchd service++当前检查结果里:++- 没发现 `SkyComputerUseService` 对外监听 TCP 端口。+- 没发现稳定可见的 Unix socket 暴露给外部 client。+- `launchctl print gui/<uid>/com.openai.sky.CUAService` 没找到同名公开 service。++这说明如果 client 和 service 之间存在本地通信,更可能是:++- 私有 XPC / app group / bundle 发现机制+- 或其他不直接暴露给任意外部进程的宿主内通信++## 当前推断++### 1. client 很可能不是独立产品边界,而是宿主绑定的桥接层++目前最符合证据的判断是:++- `SkyComputerUseClient` 负责把本地 computer-use 能力包装成 MCP+- 但它真正依赖 `Codex Computer Use.app` 或受信宿主上下文+- 因此它不像公开的通用 MCP server 那样允许任意外部 caller 直接复用++### 2. 外部直连失败至少有两层风险++当前观察到的风险至少有两类:++- macOS launch constraint 直接拦截外部自动化拉起+ - 证据:`CODESIGNING / Launch Constraint Violation`+ - 证据:`Has Parent Launch Constraints`+- 宿主集成层内部还依赖 Codex appserver / auth / plugin lifecycle+ - 证据:`CodexAppServerJSONRPCConnection`+ - 证据:`CodexAppServerAuthProvider`+ - 证据:`Connected to Codex appserver IPC socket at %s`+- 宿主认证 / service 定位失败+ - 证据:`Sender process is not authenticated`、`Could not find Service app`++这两类问题目前不能合并成一个根因。++### 3. 官方实现里存在“session 级 app 审批”++`sessionApprovedBundleIdentifiers` 这类字符串表明,官方实现不只是拿到系统级 Accessibility/Screen Recording 权限就全量控制所有 app,还维护了一层更细的 session 级审批状态。++对开源版来说,这是个重要产品边界:++- 是否允许某个 app 被 computer-use 控制+- 这个允许是一次性、会话级还是永久级++应该成为显式设计,而不是散落在代码里。++## 当前未决问题++- service 和 client 之间除 appserver socket 外,到底还使用 XPC、app group 文件协调,还是别的 IPC 机制?+- `SkyComputerUseClient_Parent.coderequirement` 里的 parent launch constraint 除 team identifier 外还有没有更细的约束来源?+- `turn-ended` 子命令除了会话清理,还会不会参与审批状态同步、idle timeout 刷新或后台 app 回收?+- `approvedBundleIdentifiers` 的持久化位置在哪里,是否只保存在进程内?+- 有没有办法通过受约束的父进程链、合法宿主 wrapper 或系统认可的启动方式绕过当前的 parent launch constraint?+- `codex-ipc/ipc-501.sock` 上跑的具体 JSON-RPC 方法和认证过程是什么?++## 下一批分析建议++- 如需继续复现实验,优先现写最小临时 stdio client,而不是依赖 Inspector 或把一次性探针长期留在仓库里。+- 继续查 service / client 的 XPC、mach service、bundle lookup、app group 读写痕迹。+- 针对 `turn-ended` 子命令补一轮 strings / 运行时分析。+- 对 analytics / preferences / group container 做更细的时间线比对,观察一次真实 Codex 会话会写入哪些审批和生命周期事件。diff --git a/docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md b/docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.mdnew file mode 100644index 0000000..631d762--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md@@ -0,0 +1,174 @@+# Software Cursor Overlay++这个文档聚焦一个很具体的问题:Codex Computer Use 在真实操作时显化出来的黄色小鼠标,是否是独立的软件光标 overlay,而不是直接抢占用户当前硬件鼠标。++结论先写在前面:从当前已经拿到的 bundle、字符串、资源名和运行时窗口证据看,这个黄色小鼠标基本可以确认是 `SkyComputerUseService` 自己持有的独立 `Software Cursor` 窗口。++## 已观察事实++### 1. 主宿主是一个无 Dock 图标的常驻 agent app++`Codex Computer Use.app/Contents/Info.plist` 可见:++```json+{+ "CFBundleExecutable": "SkyComputerUseService",+ "CFBundleIdentifier": "com.openai.sky.CUAService",+ "CFBundleName": "Codex Computer Use",+ "LSUIElement": 1+}+```++这里的 `LSUIElement = 1` 说明它是典型的 agent-style macOS app,更适合承载状态栏、浮层窗口和后台交互,而不是普通前台应用。++### 2. 主 app 资源里直接存在 cursor 相关资产++对主 app 的 `Assets.car` 做 `assetutil --info`,可以看到这些名字:++```text+Name: "CUAAppIcon_Assets/cursor"+Name: "CUAAppIcon_Assets/cursor dark"+Name: "menubar-cursor"+RenditionName: "menubar-cursor.svg"+```++这说明官方包里不仅有菜单栏图标资源,也有单独命名为 `cursor` / `cursor dark` 的图形资产。++进一步地,这些 asset 现在已经能直接导出为 PNG:++- [appicon-cursor.png](assets/extracted-2026-04-17/appicon-cursor.png)+- [appicon-cursor-dark.png](assets/extracted-2026-04-17/appicon-cursor-dark.png)+- [menubar-cursor.png](assets/extracted-2026-04-17/menubar-cursor.png)++另外,`Package_SlimCore.bundle` 和 `Package_ComputerUse.bundle` 中都能直接导出运行时用的小尺寸 `SoftwareCursor` 资源:++- [software-cursor-slimcore.png](assets/extracted-2026-04-17/software-cursor-slimcore.png)+- [software-cursor-computeruse.png](assets/extracted-2026-04-17/software-cursor-computeruse.png)++两份 `SoftwareCursor` 导出后的 PNG 二进制哈希一致,说明至少当前版本里它们引用的是同一张图。++### 3. `SkyComputerUseService` 字符串里出现了完整的光标窗口和动画线索++对 `SkyComputerUseService` 做 `strings`,能直接看到这些符号和日志文案:++```text+cursorWindow+imageView+imageLayer+cursorRadius+cursorScaleAnchorPoint+cursorMotionProgressAnimation+Moving mouse to %s+Start Bezier cursor animation (%{public}s).+Move cursor to (%f, %f) %s animation (%{public}s).+Signal cursor movement completion (%{public}s).+Enable the virtual cursor in Computer Use.+Detach the computer use cursor from the command palette.+```++这组证据比“有个 cursor 资源”更强,因为它已经落到了窗口对象、图层对象和运动动画对象这一层。++### 4. 运行时窗口清单里真的出现了 `Software Cursor`++在触发一次真实 `computer-use` 点击后,用 `CGWindowListCopyWindowInfo` 枚举窗口,能看到 `Codex Computer Use` 进程名下至少三个相关窗口:++```text+OwnerName: Codex Computer Use+WindowName: Software Cursor+Layer: 0+Bounds: X=1949 Y=696 Width=126 Height=126+IsOnscreen: 1+```++```text+OwnerName: Codex Computer Use+WindowName: Item-0+Layer: 25+Bounds: X=1804 Y=0 Width=21 Height=24+```++```text+OwnerName: Codex Computer Use+WindowName: ""+Layer: 25+Bounds: X=-754 Y=458 Width=41 Height=37+```++其中:++- `Item-0` 明显像菜单栏状态项窗口。+- 无标题 `41x37` 小窗长期藏在屏幕外,更像一个备用的内部 UI 容器。+- `Software Cursor` 是最关键的直接证据,名字已经把职责写出来了。++### 5. `Software Cursor` 会随着一次次工具动作改变位置++对 Finder 连续做两次安全点击后,再次枚举窗口,`Software Cursor` 的坐标发生了变化:++第一次:++```text+WindowName: Software Cursor+Bounds: X=1949 Y=696 Width=126 Height=126+```++第二次:++```text+WindowName: Software Cursor+Bounds: X=1949 Y=796 Width=126 Height=126+```++这说明它不是静态装饰,而是一个会被操作事件驱动移动的独立窗口。++## 当前推断++### 1. 黄色小鼠标是软件光标,不是系统硬件光标++当前最合理的解释是:++- 真正的系统事件仍然由 automation / event tap 路径发给目标 app。+- 用户看到的黄色小鼠标,是 `SkyComputerUseService` 自己渲染的一层“软件光标”。+- 这层软件光标单独运动、单独做动画,因此视觉上能模拟“鼠标在动”,但不需要真的抢走用户平时看到的系统箭头。++### 2. 它大概率是一个透明背景的小窗口,而不是注入目标 app 的子视图++原因有三点:++- 字符串里直接出现 `cursorWindow`。+- 运行时 `CGWindowList` 能枚举到命名明确的 `Software Cursor` 窗口。+- 这个窗口 owner 是 `Codex Computer Use`,而不是被控 app。++所以它更像一个由 service 维护的独立 overlay window,而不是 Finder / System Settings 之类 app 内部被插入了一块绘制层。++### 3. 黄色外观大概率来自 app 自带 cursor asset,而不是系统默认箭头重着色++这一点目前还是推断,但证据方向比较一致:++- `Assets.car` 里有专门的 `cursor` / `cursor dark` 资源。+- 二进制里同时出现 `imageView` / `imageLayer` / `imageForResource:` / `imageNamed:`。++这更像“加载自带图片资源并在窗口里渲染”,而不是直接拿系统箭头做系统级替换。++## 为什么这套体验不会抢用户鼠标++如果这个判断成立,那么体验上“看起来像有一个额外的小黄鼠标在代操作,但用户自己的真实鼠标仍然自由”就很好解释了:++- automation 层负责发真实点击和移动事件;+- overlay 层只负责给人看;+- 两者在视觉上对齐,但逻辑上分离。++这比直接操纵系统可见光标更稳,也更容易做出平滑路径、点击高亮和 delay 控制。++## 还没完全确认的点++- 还没有抓到一次动画进行中的连续窗口轨迹,目前只有离散位置点。+- 当前 `get_app_state` 返回的截图里通常看不到这个光标,推测截图采样路径和 overlay 合成路径并不完全相同,但这还需要单独验证。++## 对开源实现的启发++如果后续要做 `open-codex-computer-use` 的可用体验,这条发现很有价值:++- 可以把“真实输入注入”和“软件光标可视化”明确拆开。+- 软件光标可以做成独立 overlay window,而不是强依赖真实鼠标位置。+- 事件执行即使失败,overlay 也可以保持可观测,有利于调试和用户信任。+- 菜单栏状态项和软件光标都放在同一个 `LSUIElement` agent app 里,是一条已经被官方实现验证过的产品形态。diff --git a/docs/references/codex-computer-use-reverse-engineering/tool-call-samples-2026-04-17.md b/docs/references/codex-computer-use-reverse-engineering/tool-call-samples-2026-04-17.mdnew file mode 100644index 0000000..f412295--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/tool-call-samples-2026-04-17.md@@ -0,0 +1,744 @@+# Computer Use Tool Call Samples (2026-04-17)++这份文档记录 2026-04-17 在当前 Codex 会话里,对 `computer-use` MCP 的 9 个公开 tools 做的实测样本。++## 记录方式++- 样本来源:当前会话内的真实 MCP 调用结果。+- 目标:给后续开源兼容层实现保留“请求长什么样、响应大概长什么样”的仓库内参考。+- 文本策略:尽量保留原始响应格式;对特别长的 accessibility tree 只保留前缀和关键变化片段。+- 截图策略:`get_app_state`、`click`、`scroll`、`drag` 等调用都会在工具 UI 中附带截图;文档里只保留文本响应,不嵌入截图。+- 测试 app:`Finder`、`Activity Monitor`、`System Settings`。+- 安全边界:只选择了目录选择、搜索框输入、滚动、分隔条拖拽这类低风险动作,没有切换系统权限开关,也没有双击打开文件。++## `list_apps`++### Sample 1++Request++```json+{}+```++Response excerpt++```text+[{"type":"text","text":"Google Chrome — com.google.Chrome [running, last-used=2026-04-17, uses=20980]+PyCharm — com.jetbrains.pycharm [running, last-used=2026-04-17, uses=3444]+iTerm2 — com.googlecode.iterm2 [running, last-used=2026-04-17, uses=3178]+Sublime Text — com.sublimetext.4 [running, last-used=2026-04-17, uses=2023]+ChatGPT — com.openai.chat [running, last-used=2026-04-17, uses=661]+Finder — com.apple.finder [running, last-used=2026-04-17, uses=366]+...+Obsidian — md.obsidian [last-used=2026-04-08, uses=8]"}]+```++### Sample 2++Request++```json+{}+```++Response excerpt++```text+[{"type":"text","text":"Google Chrome — com.google.Chrome [running, last-used=2026-04-17, uses=20983]+PyCharm — com.jetbrains.pycharm [running, last-used=2026-04-17, uses=3447]+iTerm2 — com.googlecode.iterm2 [running, last-used=2026-04-17, uses=3179]+...+Obsidian — md.obsidian [last-used=2026-04-08, uses=8]"}]+```++### Sample 3++Request++```json+{}+```++Response excerpt++```text+[{"type":"text","text":"Google Chrome — com.google.Chrome [running, last-used=2026-04-17, uses=20983]+PyCharm — com.jetbrains.pycharm [running, last-used=2026-04-17, uses=3447]+iTerm2 — com.googlecode.iterm2 [running, last-used=2026-04-17, uses=3179]+...+Obsidian — md.obsidian [last-used=2026-04-08, uses=8]"}]+```++已观察到的返回形态:++```text+- 外层是 content array。+- 当前只返回一个 text block。+- text block 内部是多行纯文本,每行格式接近:+ App Name — bundle.id [running, last-used=YYYY-MM-DD, uses=N]+```++## `get_app_state`++### Sample 1++Request++```json+{+ "app": "Finder"+}+```++Response excerpt++```text+Computer Use state (CUA App Version: 750)+<app_state>+App=com.apple.finder (pid 1106)+Window: "open-codex-computer-use", App: Finder.+ 0 standard window open-codex-computer-use, ID: FinderWindow, Secondary Actions: Raise+ 1 split group+ 2 scroll area+ 3 outline sidebar+ 4 row (selectable, expanded) Value: Favorites, Secondary Actions: Collapse+ ...+ 25 scroll area+ 26 outline Description: list view, ID: ListView+ 68 row (selectable, collapsed) Secondary Actions: Expand+ 119 row (selectable, collapsed) Secondary Actions: Expand+ 130 row (selected)+...+</app_state>+```++### Sample 2++Request++```json+{+ "app": "Activity Monitor"+}+```++Response excerpt++```text+Computer Use state (CUA App Version: 750)+<app_state>+App=com.apple.ActivityMonitor (pid 988)+Window: "Activity Monitor", App: Activity Monitor.+ 0 standard window Activity Monitor – All Processes, Secondary Actions: Raise+ 1 scroll area Secondary Actions: Scroll Left, Scroll Right, Scroll Up, Scroll Down+ 2 outline Processes+ 3 row (selectable) OrbStack Helper+ 4 row (selectable) iTerm2+ ...+ 36 toolbar+ 41 Description: Categories, Help: Display processes in the category specified+ 42 radio button Description: CPU, Value: 1+ 43 radio button Description: Memory, Value: 0+ 47 search text field (settable, string)+ 48 button search+...+The focused UI element is 2 outline.+</app_state>+```++### Sample 3++Request++```json+{+ "app": "System Settings"+}+```++Response excerpt++```text+Computer Use state (CUA App Version: 750)+<app_state>+App=com.apple.systempreferences (pid 73431)+Window: "Screen & System Audio Recording", App: System Settings.+ 0 standard window Screen & System Audio Recording, ID: main, Secondary Actions: Raise+ 1 split group main, SidebarNavigationView+ 2 container+ 3 search text field (settable, string)+ 5 scroll area Secondary Actions: Scroll Up, Scroll Down+ 6 list Sidebar+ 34 row (selected) Privacy & Security+ 53 scroll area Secondary Actions: Cancel+ 54 heading Screen & System Audio Recording+ ...+ 63 row (selectable) Codex Computer Use+ 64 switch Value: on, ID: Codex Computer Use_Toggle+...+</app_state>+```++额外边界样本:++Request++```json+{+ "app": "iTerm2"+}+```++Response++```text+[{"type":"text","text":"appNotFound(\"iTerm2\")"}]+```++Request++```json+{+ "app": "com.googlecode.iterm2"+}+```++Response++```text+[{"type":"text","text":"Computer Use is not allowed to use the app 'com.googlecode.iterm2' for safety reasons."}]+```++## `click`++### Sample 1++Request++```json+{+ "app": "Finder",+ "element_index": "68"+}+```++Response excerpt++```text+68 row (selected, collapsed) Secondary Actions: Expand+ 69 cell (selected)+ 71 text field (selected, settable, string) ... Value: docs+...+164 list path+ 165 text ... Value: Macintosh HD Users leo projects github open-codex-computer-use docs+```++### Sample 2++Request++```json+{+ "app": "Finder",+ "element_index": "119"+}+```++Response excerpt++```text+119 row (selected, collapsed) Secondary Actions: Expand+ 120 cell (selected)+ 122 text field (selected, settable, string) ... Value: scripts+...+164 list path+ 165 text ... Value: Macintosh HD Users leo projects github open-codex-computer-use scripts+```++### Sample 3++Request++```json+{+ "app": "Activity Monitor",+ "element_index": "43"+}+```++Response excerpt++```text+34 Description: Categories, Help: Display processes in the category specified+ 35 radio button Description: CPU, Value: 0+ 36 radio button Description: Memory, Value: 1+ 37 radio button Description: Energy, Value: 0+...+The focused UI element is 2 outline.+```++## `perform_secondary_action`++### Sample 1++Request++```json+{+ "app": "Finder",+ "element_index": "68",+ "action": "Expand"+}+```++Response excerpt++```text+68 row (selectable, expanded) Secondary Actions: Collapse+ 69 cell+ 71 text field ... Value: docs+ 72 disclosure triangle 1+79 row (selectable)+80 row (selectable)+81 row (selectable, collapsed) Secondary Actions: Expand+...+```++### Sample 2++Request++```json+{+ "app": "Finder",+ "element_index": "68",+ "action": "Collapse"+}+```++Response excerpt++```text+68 row (selectable, collapsed) Secondary Actions: Expand+ 69 cell+ 71 text field ... Value: docs+ 72 disclosure triangle 0+```++### Sample 3++Request++```json+{+ "app": "Activity Monitor",+ "element_index": "0",+ "action": "Raise"+}+```++Response excerpt++```text+0 standard window Activity Monitor – All Processes, Secondary Actions: Raise+...+The focused UI element is 2 outline.+```++这个样本说明:++```text+部分 secondary action 是真正会改 UI 状态的动作(Expand / Collapse)。+也有一类更像窗口级命令(Raise),响应文本可能几乎不变。+```++## `scroll`++### Sample 1++Request++```json+{+ "app": "Activity Monitor",+ "element_index": "1",+ "direction": "down",+ "pages": 1+}+```++Response excerpt++```text+1 scroll area Secondary Actions: Scroll Up, Scroll Down+ 2 outline Processes+ 3 row (selectable) coreservicesd+ 4 row (selectable) corebrightnessd+ ...+25 scroll bar (settable, float) 0.1371493880660984+ 26 value indicator (settable, float) 0.1371493880660984+```++### Sample 2++Request++```json+{+ "app": "Activity Monitor",+ "element_index": "1",+ "direction": "up",+ "pages": 1+}+```++Response excerpt++```text+1 scroll area Secondary Actions: Scroll Up, Scroll Down+ 2 outline Processes+ 3 row (selectable) OrbStack Helper+ 4 row (selectable) iTerm2+ ...+22 scroll bar (settable, float) 0+ 23 value indicator (settable, float) 0+```++### Sample 3++Request++```json+{+ "app": "System Settings",+ "element_index": "5",+ "direction": "down",+ "pages": 1+}+```++Response excerpt++```text+5 scroll area Secondary Actions: Scroll Up, Scroll Down+ 6 list Sidebar+ 17 row (selectable) General+ 18 row (selectable) Accessibility+ ...+ 45 row (selectable) Printers & Scanners+46 scroll bar (settable, float) 0.9999999999999994+ 47 value indicator (settable, float) 0.9999999999999994+```++## `set_value`++### Sample 1++Request++```json+{+ "app": "Activity Monitor",+ "element_index": "40",+ "value": "codex"+}+```++Response excerpt++```text+3 row (selectable) codex+...+14 row (selectable) Codex Computer Use+...+38 search text field (settable, string) codex+ 39 button search+ 40 button cancel+```++### Sample 2++Request++```json+{+ "app": "System Settings",+ "element_index": "3",+ "value": "privacy"+}+```++Response excerpt++```text+Window: "Apple Account", App: System Settings.+...+3 search text field (settable, string) privacy+ 4 button Search+ 5 button cancel+6 scroll area Secondary Actions: Scroll Up, Scroll Down+ 7 list Sidebar+ 9 row (selectable) Privacy & Security+ 10 row (selectable) Allow applications to access Bluetooth+ ...+```++### Sample 3++Request++```json+{+ "app": "System Settings",+ "element_index": "3",+ "value": "screen"+}+```++Response excerpt++```text+Window: "Privacy & Security", App: System Settings.+...+3 search text field (settable, string) screen+ 4 button Search+ 5 button cancel+...+57 row (selectable) Privacy & Security+58 row (selectable) Allow applications to access the contents of your screen and audio through Remote Desktop+59 row (selectable) Allow applications to record your screen+```++## `press_key`++### Sample 1++Request++```json+{+ "app": "Activity Monitor",+ "key": "super+a"+}+```++Response excerpt++```text+38 search text field (settable, string) codex+...+Selected text: [codex]+```++### Sample 2++Request++```json+{+ "app": "Activity Monitor",+ "key": "super+a"+}+```++Response excerpt++```text+38 search text field (settable, string) Codex+...+Selected text: [Codex]+```++### Sample 3++Request++```json+{+ "app": "Activity Monitor",+ "key": "super+a"+}+```++Response excerpt++```text+27 search text field (settable, string) Computer Use+...+Selected text: [Computer Use]+```++## `type_text`++### Sample 1++Request++```json+{+ "app": "Activity Monitor",+ "text": "Codex"+}+```++Response excerpt++```text+38 search text field (settable, string) Codex+...+The focused UI element is 38 search text field.+```++### Sample 2++Request++```json+{+ "app": "Activity Monitor",+ "text": "Computer Use"+}+```++Response excerpt++```text+3 row (selectable) Codex Computer Use+...+27 search text field (settable, string) Computer Use+ 28 button search+ 29 button cancel+```++### Sample 3++Request++```json+{+ "app": "Activity Monitor",+ "text": "Helper"+}+```++Response excerpt++```text+2 outline Processes (showing 0-19 of 161 items)+ 3 row (selectable) OrbStack Helper+ 4 row (selectable) Figma Helper (Renderer)+ 5 row (selectable) Figma Helper (GPU)+ ...+38 search text field (settable, string) Helper+```++## `drag`++### Sample 1++Request++```json+{+ "app": "Finder",+ "from_x": 158,+ "from_y": 373,+ "to_x": 220,+ "to_y": 373+}+```++Response excerpt++```text+24 splitter (disabled, settable, float) 185+...+170 pop up button Description: list view, Value: as List+```++这个样本里,`Finder` 左侧 sidebar 被拉宽,splitter 的 float 从 `133` 变成了 `185`。++### Sample 2++Request++```json+{+ "app": "Finder",+ "from_x": 220,+ "from_y": 373,+ "to_x": 158,+ "to_y": 373+}+```++Response excerpt++```text+24 splitter (disabled, settable, float) 133+...+171 radio button Description: icon view, Value: 0+172 radio button Description: list view, Value: 1+```++### Sample 3++Request++```json+{+ "app": "System Settings",+ "from_x": 231,+ "from_y": 466,+ "to_x": 260,+ "to_y": 466+}+```++Response excerpt++```text+83 splitter (disabled, settable, float) 215+...+57 row (selected) Privacy & Security+```++这个样本返回正常,但从文本上看没有产生明显的 split value 变化,说明纯坐标拖拽对起点定位比较敏感。++额外 no-op 倾向样本:++Request++```json+{+ "app": "Activity Monitor",+ "from_x": 1145,+ "from_y": 111,+ "to_x": 1145,+ "to_y": 262+}+```++Response excerpt++```text+22 scroll bar (settable, float) 0+ 23 value indicator (settable, float) 0+...+38 search text field (settable, string) Helper+```++## 总结++从这轮实测可以先得到几个稳定结论:++```text+1. `list_apps` 是纯文本枚举接口,最简单。+2. `get_app_state` 是整个接口面的核心,会返回 element index、属性、secondary actions 和截图。+3. 大多数交互类工具在响应里都会把“最新的完整或近完整 UI 状态”再返回一遍,而不只是返回 `ok`。+4. `set_value` 比 `type_text` 更语义化,适合直接写 search/text field。+5. `press_key` 的响应里会带 `Selected text`,这对判断焦点和选区很有价值。+6. `drag` 只有坐标模式,没有 `element_index`,所以稳定性最依赖截图坐标选点。+7. app 名解析有边界:人类可读名不一定能直接命中,bundle id 也可能被安全策略拒绝。+```diff --git a/docs/releases/README.md b/docs/releases/README.mdnew file mode 100644index 0000000..57c6c3e--- /dev/null+++ b/docs/releases/README.md@@ -0,0 +1,17 @@+# 发布记录说明++`feature-release-notes.md` 用来记录对用户可感知的新功能、体验优化和重要修复。++## 规则++- 按月份分组,格式使用 `## YYYY-MM`+- 同一个月份里,最新内容插在最上面+- 先写用户价值,再写变更摘要+- 不要把纯内部重构和实现噪音塞进来++## 建议的列++- 日期+- 功能域+- 用户价值+- 变更摘要diff --git a/docs/releases/feature-release-notes.md b/docs/releases/feature-release-notes.mdnew file mode 100644index 0000000..3a59382--- /dev/null+++ b/docs/releases/feature-release-notes.md@@ -0,0 +1,7 @@+# 功能发布记录++## 2026-04++| 日期 | 功能域 | 用户价值 | 变更摘要 |+| --- | --- | --- | --- |+| 2026-04-08 | 模板仓库 | 提供了一套可直接用于新项目启动的 Agent-first 基础模板。 | 补齐了 AGENTS 入口、execution plan、history、release note、CI/CD 和供应链安全骨架。 |diff --git a/scripts/check-action-pinning.sh b/scripts/check-action-pinning.shnew file mode 100755index 0000000..d686423--- /dev/null+++ b/scripts/check-action-pinning.sh@@ -0,0 +1,21 @@+#!/usr/bin/env bash++set -euo pipefail++repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+failed=0++while IFS= read -r line; do+ file="${line%%:*}"+ content="${line#*:}"+ if [[ ! "${content}" =~ @[0-9a-f]{40}([[:space:]]|$) ]]; then+ echo "发现未固定 SHA 的 GitHub Action 引用: ${line}"+ failed=1+ fi+done < <(grep -RIn 'uses:' "${repo_root}/.github/workflows" || true)++if [[ "${failed}" -ne 0 ]]; then+ exit 1+fi++echo "GitHub Action 固定 SHA 检查通过"diff --git a/scripts/check-docs.sh b/scripts/check-docs.shnew file mode 100755index 0000000..d0073ee--- /dev/null+++ b/scripts/check-docs.sh@@ -0,0 +1,58 @@+#!/usr/bin/env bash++set -euo pipefail++repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"++required_files=(+ "AGENTS.md"+ "README.md"+ "CONTRIBUTING.md"+ "docs/REPO_COLLAB_GUIDE.md"+ "docs/HISTORY_GUIDE.md"+ "docs/PLANS_GUIDE.md"+ "docs/ARCHITECTURE.md"+ "docs/CICD.md"+ "docs/DESIGN.md"+ "docs/PRODUCT_SENSE.md"+ "docs/QUALITY_SCORE.md"+ "docs/RELIABILITY.md"+ "docs/SECURITY.md"+ "docs/SUPPLY_CHAIN_SECURITY.md"+ "docs/design-docs/core-beliefs.md"+ "docs/design-docs/index.md"+ "docs/product-specs/index.md"+ "docs/references/README.md"+ "docs/generated/README.md"+ "docs/exec-plans/templates/execution-plan.md"+ "docs/exec-plans/tech-debt-tracker.md"+ "docs/histories/template.md"+ "docs/releases/feature-release-notes.md"+)++missing=0++for path in "${required_files[@]}"; do+ if [[ ! -f "${repo_root}/${path}" ]]; then+ echo "缺少必要文件: ${path}"+ missing=1+ fi+done++for dir in docs/exec-plans/active docs/exec-plans/completed docs/histories; do+ if [[ ! -d "${repo_root}/${dir}" ]]; then+ echo "缺少必要目录: ${dir}"+ missing=1+ fi+done++if ! grep -q "docs/" "${repo_root}/AGENTS.md"; then+ echo "AGENTS.md 应明确指向 docs/,说明它是仓库知识的正式来源"+ missing=1+fi++if [[ "${missing}" -ne 0 ]]; then+ exit 1+fi++echo "文档骨架检查通过"diff --git a/scripts/check-repo-hygiene.sh b/scripts/check-repo-hygiene.shnew file mode 100755index 0000000..b3b2f61--- /dev/null+++ b/scripts/check-repo-hygiene.sh@@ -0,0 +1,51 @@+#!/usr/bin/env bash++set -euo pipefail++repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"++required_files=(+ ".gitignore"+ ".editorconfig"+ ".gitattributes"+ "CODEOWNERS"+ "CONTRIBUTING.md"+ "SECURITY.md"+ ".github/PULL_REQUEST_TEMPLATE.md"+ ".github/dependency-review-config.yml"+ ".github/ISSUE_TEMPLATE/bug_report.yml"+ ".github/ISSUE_TEMPLATE/feature_request.yml"+ ".github/ISSUE_TEMPLATE/config.yml"+ ".github/workflows/ci.yml"+ ".github/workflows/docs-check.yml"+ ".github/workflows/repo-hygiene.yml"+ ".github/workflows/release.yml"+ ".github/workflows/supply-chain-security.yml"+ ".markdownlint.json"+ "scripts/check-action-pinning.sh"+)++failed=0++for path in "${required_files[@]}"; do+ if [[ ! -f "${repo_root}/${path}" ]]; then+ echo "缺少必要文件: ${path}"+ failed=1+ fi+done++if grep -q $'\r' "${repo_root}/README.md"; then+ echo "README.md 含有 CRLF 换行"+ failed=1+fi++if ! grep -q "make check-docs" "${repo_root}/CONTRIBUTING.md"; then+ echo "CONTRIBUTING.md 应明确提到 make check-docs"+ failed=1+fi++if [[ "${failed}" -ne 0 ]]; then+ exit 1+fi++echo "仓库基础卫生检查通过"diff --git a/scripts/ci.sh b/scripts/ci.shnew file mode 100755index 0000000..a177e5f--- /dev/null+++ b/scripts/ci.sh@@ -0,0 +1,15 @@+#!/usr/bin/env bash++set -euo pipefail++repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"++"${repo_root}/scripts/check-docs.sh"+"${repo_root}/scripts/check-repo-hygiene.sh"+"${repo_root}/scripts/check-action-pinning.sh"++while IFS= read -r file; do+ bash -n "$file"+done < <(find "${repo_root}/scripts" -type f -name '*.sh' | sort)++echo "基础 CI 检查通过"diff --git a/scripts/init-project.sh b/scripts/init-project.shnew file mode 100755index 0000000..1aad4f2--- /dev/null+++ b/scripts/init-project.sh@@ -0,0 +1,18 @@+#!/usr/bin/env bash++set -euo pipefail++if [[ $# -ne 1 ]]; then+ echo "用法: $0 <项目名>" >&2+ exit 1+fi++project_name="$1"+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"++perl -0pi -e "s/open-codex-computer-use/${project_name}/g; s/harness-template/${project_name}/g" \+ "${repo_root}/README.md" \+ "${repo_root}/AGENTS.md"++echo "已将模板名称初始化为: ${project_name}"+echo "下一步建议: 补齐 docs/ARCHITECTURE.md 和 docs/product-specs/ 中的真实项目信息"diff --git a/scripts/new-exec-plan.sh b/scripts/new-exec-plan.shnew file mode 100755index 0000000..043fd2c--- /dev/null+++ b/scripts/new-exec-plan.sh@@ -0,0 +1,17 @@+#!/usr/bin/env bash++set -euo pipefail++if [[ $# -ne 1 ]]; then+ echo "用法: $0 <plan-slug>" >&2+ exit 1+fi++slug="$1"+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+date_prefix="$(date +%Y-%m-%d)"+target="${repo_root}/docs/exec-plans/active/${date_prefix}-${slug}.md"++cp "${repo_root}/docs/exec-plans/templates/execution-plan.md" "${target}"++echo "${target}"diff --git a/scripts/new-history.sh b/scripts/new-history.shnew file mode 100755index 0000000..62842c0--- /dev/null+++ b/scripts/new-history.sh@@ -0,0 +1,19 @@+#!/usr/bin/env bash++set -euo pipefail++if [[ $# -ne 1 ]]; then+ echo "用法: $0 <task-slug>" >&2+ exit 1+fi++slug="$1"+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+month_dir="${repo_root}/docs/histories/$(date +%Y-%m)"+timestamp="$(date +%Y%m%d-%H%M)"+target="${month_dir}/${timestamp}-${slug}.md"++mkdir -p "${month_dir}"+cp "${repo_root}/docs/histories/template.md" "${target}"++echo "${target}"diff --git a/scripts/release-package.sh b/scripts/release-package.shnew file mode 100755index 0000000..9199d21--- /dev/null+++ b/scripts/release-package.sh@@ -0,0 +1,25 @@+#!/usr/bin/env bash++set -euo pipefail++repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+dist_dir="${repo_root}/dist"++rm -rf "${dist_dir}"+mkdir -p "${dist_dir}"++cat > "${dist_dir}/release-manifest.json" <<EOF+{+ "repository": "${GITHUB_REPOSITORY:-local}",+ "git_sha": "${GITHUB_SHA:-$(git -C "${repo_root}" rev-parse HEAD 2>/dev/null || echo unknown)}",+ "generated_at_utc": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",+ "artifact": "repo-metadata.tgz",+ "note": "Replace scripts/release-package.sh with the real project build packaging when the stack is known."+}+EOF++tar -czf "${dist_dir}/repo-metadata.tgz" \+ -C "${repo_root}" \+ AGENTS.md README.md CONTRIBUTING.md LICENSE docs scripts .github Makefile++echo "${dist_dir}/repo-metadata.tgz"