Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

feat: bootstrap computer-use research repo

Leo69b7960573d6
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f32e31a
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+.idea/
+.DS_Store
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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.md
new file mode 100644
index 0000000..627ccb6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+<system-reminder>必须先阅读 AGENTS.md。</system-reminder>
diff --git a/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 0000000..2846cf7
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1,3 @@
+# 基于这个模板创建新项目后,请替换成真实的代码所有者。
+
+* @example-org/example-team
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 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/LICENSE
new file mode 100644
index 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/Makefile
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 0000000..0743fe1
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,15 @@
+# 安全策略
+
+## 漏洞反馈
+
+如果发现疑似安全漏洞,不要直接提公开 issue。
+
+请通过你们组织内部约定的私有安全通道反馈,并尽量附上:
+
+- 影响范围和潜在风险。
+- 复现步骤或 PoC。
+- 已知的缓解方式或临时绕过方案。
+
+## 适用范围
+
+这个仓库本身只是一个基础模板。基于它创建的新项目,应该把这里替换成自己真实的安全联系人和响应流程。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 0000000..d62778c
--- /dev/null
+++ b/docs/DESIGN.md
@@ -0,0 +1,10 @@
+# 设计原则
+
+这份文档用于沉淀产品层面相对稳定的设计原则。
+
+建议放的内容包括:
+
+- 整体视觉原则和交互目标。
+- 字体、颜色、间距和组件系统的选择。
+- 无障碍与响应式设计要求。
+- 什么场景该复用共享组件,什么场景可以例外。
diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md
new file mode 100644
index 0000000..cbab558
--- /dev/null
+++ b/docs/FRONTEND.md
@@ -0,0 +1,11 @@
+# 前端协作说明
+
+当仓库里真正有前端界面时,再把这份文档补完整。
+
+建议在这里维护:
+
+- 本地启动、构建和联调方式。
+- 浏览器驱动的验收流程。
+- 共享组件边界。
+- 设计系统、样式变量和 CSS 规范。
+- 前端测试策略。
diff --git a/docs/HISTORY_GUIDE.md b/docs/HISTORY_GUIDE.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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/.gitkeep
new file mode 100644
index 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.md
new file mode 100644
index 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/.gitkeep
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.png
new file mode 100644
index 0000000..e10332a
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor-dark.png differ
diff --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.png
new file mode 100644
index 0000000..adf3155
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/appicon-cursor.png differ
diff --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.png
new file mode 100644
index 0000000..7b72afb
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/hint-arrow.png differ
diff --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.png
new file mode 100644
index 0000000..1e1e95e
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/menubar-cursor.png differ
diff --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.png
new file mode 100644
index 0000000..7b0e0e1
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-computeruse.png differ
diff --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.png
new file mode 100644
index 0000000..7b0e0e1
Binary files /dev/null and b/docs/references/codex-computer-use-reverse-engineering/assets/extracted-2026-04-17/software-cursor-slimcore.png differ
diff --git a/docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md b/docs/references/codex-computer-use-reverse-engineering/baseline-architecture.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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.sh
new file mode 100755
index 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"