docs: establish Codex alignment roadmap

.github/workflows/ci.yml

@@ -3,8 +3,8 @@ name: CI
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
+  # Stacked PRs target feature branches; every PR still needs the same gates.
+  pull_request: {}
 
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
@@ -77,13 +77,18 @@ jobs:
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v6
-      - name: Verify required docs exist
+      - name: Verify current documentation
+        run: node scripts/check-docs.mjs
+
+  desktop-rust:
+    name: Desktop Rust check + test
+    runs-on: macos-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+      - name: Show Rust toolchain
+        run: rustc --version && cargo --version
+      - name: Check and test Tauri backend
         run: |
-          for f in README.md CONTRIBUTING.md SECURITY.md \
-                   docs/DEVELOPMENT_PLAN.md docs/VISUAL_DESIGN.html \
-                   docs/design/sandbox-plan-worktree.md \
-                   docs/design/plugin-security.md \
-                   docs/design/effort-levels.md; do
-            test -f "$f" || { echo "MISSING: $f"; exit 1; }
-          done
-          echo "All M0 docs present"
+          cargo check --manifest-path apps/desktop/src-tauri/Cargo.toml --locked
+          cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked

AGENTS.md

@@ -0,0 +1,67 @@
+# DeepCode repository guidance
+
+## North star
+
+DeepCode is a DeepSeek-powered coding agent with CLI, Tauri desktop, VS Code,
+and LSP surfaces. The active modernization plan is
+[`docs/CODEX_ALIGNMENT_PLAN.md`](docs/CODEX_ALIGNMENT_PLAN.md). It supersedes
+the original milestone plan for new architecture decisions.
+
+## Layout
+
+- `packages/core`: provider, agent loop, tools, config, sessions, sandbox,
+  hooks, MCP, skills, plugins, tasks, and worktrees.
+- `packages/shared-ui`: cross-client types only.
+- `apps/cli`: interactive and headless CLI.
+- `apps/desktop`: React/Vite renderer plus the Rust/Tauri backend in
+  `src-tauri`.
+- `apps/lsp` and `apps/vscode`: editor integrations.
+- `scripts`: release and repository checks.
+- `docs`: current plans plus historical design snapshots.
+
+Do not edit generated `dist/`, `target/`, release artifacts, or lockfiles unless
+the task requires it.
+
+## Setup and verification
+
+Use Node 22 and pnpm 9.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm test
+pnpm build
+pnpm docs:check
+cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml
+```
+
+Run the smallest relevant package test while iterating, then the full relevant
+gate before handing off. Changes to the Rust backend require `cargo fmt --check`
+and `cargo test`. Changes to sandbox, permissions, credentials, plugins, hooks,
+or process execution require focused adversarial tests.
+
+## Engineering constraints
+
+- Preserve existing user changes and backward-compatible CLI behavior unless a
+  migration is explicitly documented.
+- All tool execution must pass through one explicit permission policy. Never
+  make safety depend on a host remembering to pass an optional argument.
+- Do not expose DeepSeek credentials to a renderer or webview. Treat the VS Code
+  extension host and its webview as different trust boundaries.
+- Cancellation is complete only when providers, child process groups, pending
+  approvals, and subsequent writes have stopped.
+- Do not force-delete worktree branches or discard unmerged user work.
+- Keep legacy session files read-only during migrations; prefer format
+  detection and dual-read/single-write adapters.
+- Keep provider-specific behavior behind provider capabilities. Do not claim
+  exact Codex or Claude parity when DeepSeek constraints differ.
+- New public behavior needs tests and user-facing documentation in the same PR.
+
+## Definition of done
+
+A change is done when its behavior is tested at the correct boundary, relevant
+quality gates pass, security and migration consequences are documented, and the
+diff contains no unrelated generated or user-owned changes. For architecture
+work, update the alignment plan or an ADR with the decision and rollback path.

CONTRIBUTING.md

@@ -1,14 +1,14 @@
 # Contributing to DeepCode
 
-感谢你对 DeepCode 感兴趣。DeepCode 是 Claude Code 的 DeepSeek 版 —— 完整复刻 Claude Code 全部能力，底层 LLM 切换到 DeepSeek。
+感谢你对 DeepCode 感兴趣。DeepCode 是一个由 DeepSeek 驱动的本地 coding agent，正在收敛 CLI、桌面端和编辑器端的运行时语义。
 
 > 在写代码前请先读：
 >
-> 1. [`docs/DEVELOPMENT_PLAN.md`](docs/DEVELOPMENT_PLAN.md) — 整体开发方案 v0.5
-> 2. [`docs/VISUAL_DESIGN.html`](docs/VISUAL_DESIGN.html) — 视觉设计 v0.4（11 屏 mockup）
-> 3. [`docs/design/sandbox-plan-worktree.md`](docs/design/sandbox-plan-worktree.md) — sandbox × plan mode × worktree 三者关系
-> 4. [`docs/design/plugin-security.md`](docs/design/plugin-security.md) — plugin 安全模型
-> 5. [`docs/design/effort-levels.md`](docs/design/effort-levels.md) — effort levels 到 DeepSeek 的参数映射
+> 1. [`AGENTS.md`](AGENTS.md) — 仓库操作、验证与安全约束
+> 2. [`docs/CODEX_ALIGNMENT_PLAN.md`](docs/CODEX_ALIGNMENT_PLAN.md) — 当前架构与 PR 路线
+> 3. [`docs/DEVELOPMENT_PLAN.md`](docs/DEVELOPMENT_PLAN.md) — 原始里程碑历史快照
+> 4. [`docs/design/sandbox-plan-worktree.md`](docs/design/sandbox-plan-worktree.md) — sandbox × plan mode × worktree 三者关系
+> 5. [`docs/design/plugin-security.md`](docs/design/plugin-security.md) — plugin 安全模型
 
 ## 项目结构
 
@@ -21,7 +21,7 @@ deepcode/
 │   └── shared-ui/          # CLI 与桌面客户端共享类型
 ├── apps/
 │   ├── cli/                # @deepcode/cli — npm 包，命令 `deepcode`
-│   └── desktop/            # Mac 客户端（Electron + React）
+│   └── desktop/            # Mac 客户端（Tauri 2 + Rust + React）
 ├── docs/
 │   ├── DEVELOPMENT_PLAN.md
 │   ├── VISUAL_DESIGN.html
@@ -36,7 +36,7 @@ deepcode/
 
 ### 必需
 
-- Node.js ≥ 20（推荐 LTS）
+- Node.js ≥ 22
 - pnpm ≥ 9
 - Git ≥ 2.30
 - ripgrep（CLI Grep 工具依赖）
@@ -55,6 +55,8 @@ cd deepcode
 pnpm install
 pnpm typecheck
 pnpm build
+pnpm test
+pnpm docs:check
 ```
 
 ## 工作流
@@ -70,8 +72,7 @@ pnpm build
 ```bash
 git checkout -b feat/<topic>
 # ... write code ...
-pnpm test         # 跑单测
-pnpm test:e2e     # 跑集成测试（需 DEEPSEEK_API_KEY）
+pnpm test
 pnpm lint
 pnpm typecheck
 ```
@@ -141,21 +142,13 @@ pnpm --filter @deepcode/core test    # 单包
 
 使用 vitest。test 文件 `*.test.ts` 与源码并列。
 
-### 集成测试
+### 集成与真实 provider 测试
 
-```bash
-pnpm test:e2e
-```
-
-需要 `DEEPSEEK_API_KEY` 环境变量。CI 自动注入；本地开发需要在 `.env.local` 里设。
+默认测试不请求 DeepSeek API。真实 provider 用例位于 `packages/core/src/providers/deepseek.live.test.ts`，只有显式提供测试凭证并按测试文件说明启用时才运行；不要把凭证写入仓库或测试日志。
 
 ### 安全测试（M3.5 起强制）
 
-```bash
-pnpm test:security
-```
-
-跑 `docs/design/sandbox-plan-worktree.md` §7 + `docs/design/plugin-security.md` §9 的全部测试。每个改 `packages/core/src/sandbox/` 或 `packages/core/src/plugins/` 的 PR 必须跑。
+安全测试属于 `@deepcode/core` 测试套件。每个修改 `packages/core/src/sandbox/`、permissions、credentials、hooks、process execution 或 plugins 的 PR 必须运行 core 全套测试和对应的 focused test files；Linux kernel sandbox 集成测试还需要 bwrap/slirp4netns 与 CI 中的 opt-in 环境。
 
 ## 代码风格
 

MORNING_REPORT.md

@@ -1,5 +1,7 @@
 # 进度汇报 — 第七轮 "继续推进 to completion"
 
+> **历史快照（2026-05）**：本文件保留当时的交接记录，不代表当前能力、测试数或发布状态。当前方向与事实基线见 [`docs/CODEX_ALIGNMENT_PLAN.md`](docs/CODEX_ALIGNMENT_PLAN.md)，实时验证以 CI 为准。
+
 > 持续覆盖。前六轮内容见 git 历史。
 
 ## TL;DR

README.md

@@ -2,24 +2,23 @@
 
 # DeepCode
 
-**Claude Code 的 DeepSeek 版** —— 完整复刻 Claude Code 全部能力，底层 LLM 切换到 **DeepSeek**
+**面向真实代码库的 DeepSeek coding agent** —— CLI、macOS 桌面端与编辑器接入共享一个持续演进的核心
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-549%20passing-brightgreen.svg)](.github/workflows/ci.yml)
-[![v1 scope](https://img.shields.io/badge/v1%20scope-~98%25-brightgreen.svg)](MORNING_REPORT.md)
+[![CI](https://github.com/oratis/deepcode/actions/workflows/ci.yml/badge.svg)](https://github.com/oratis/deepcode/actions/workflows/ci.yml)
 
 </div>
 
 ---
 
 ## 这是什么
 
-如果你在用 **Claude Code** 但希望底层模型用 **DeepSeek** 而不是 Claude，DeepCode 就是为你做的。
+DeepCode 让 DeepSeek 可以在本地代码库中执行读取、编辑、命令、审阅、MCP 和可恢复会话工作。项目最初以 Claude Code 兼容为目标，现在正转向经过验证的 Codex 式运行模型：统一任务生命周期、可靠中断、清晰权限边界和跨客户端一致行为。
 
-- ✅ **完整对齐** Claude Code 的全部能力：工具调用 / MCP / 子代理 / hooks / skills / plugins / sandbox / checkpointing / 输出风格 / 5 档 effort levels
-- ✅ **四种形态**：Node.js CLI · Mac 客户端 · VS Code 扩展 · LSP bridge (Neovim/Emacs/Sublime)
-- ✅ **零迁移成本**：settings.json / hooks / MCP servers / skills / agents 与 Claude Code 1:1 对齐。见 [docs/MIGRATION_FROM_CLAUDE_CODE.md](docs/MIGRATION_FROM_CLAUDE_CODE.md)
-- ✅ **同安全保证**：sandbox-exec (macOS) + bwrap (Linux) + ed25519 marketplace signatures + DNS proxy + pipeline analysis ([docs/security-model.md](docs/security-model.md))
+- **已可用**：Node.js CLI、Tauri macOS 客户端、核心工具、MCP、hooks、skills、plugins、sandbox、sessions、background tasks 与 voice input。
+- **在收敛**：VS Code/LSP、统一权限、真实取消、thread/turn/item 协议与跨客户端恢复。
+- **兼容优先**：继续读取既有 `settings.json`、`DEEPCODE.md`、`AGENTS.md` 和 Claude 风格扩展资产，但不以未经验证的“1:1 parity”作为安全或完成度承诺。
+- **设计路线**：完整审查、正反方审议和分阶段 PR 见 [Codex alignment plan](docs/CODEX_ALIGNMENT_PLAN.md)。
 
 ## 快速上手
 
@@ -38,30 +37,11 @@ deepcode --model deepseek-reasoner --effort high
 
 Mac 客户端（v1 即将发布）：拖入 Applications → 首启完成 onboarding。
 
-## 完成度
+## 当前工程基线
 
-```
-M0  设计骨架            ████████████████████ 100%
-M1  内核 MVP            ████████████████████ 100%
-M2  CLI MVP             ████████████████████ 100%
-M3  modes/hooks/memory  ████████████████████ 100%
-M3c MCP/compact/etc.    ████████████████████ 100%
-M3c-rest                ████████████████████ 100%
-M3.5 sandbox            ████████████████████ 100%
-M4  skills/agents/style ████████████████████ 100%
-M5  plugins manifest    ████████████████████ 100%
-M5.1 plugin subprocess  ████████████████████ 100%
-M5.2 marketplace        ████████████████████ 100%
-M6  Mac client          ██████████████████░░  90% (UI 11 屏 + IPC 协议完，等装 Electron binary)
-M7  file panel + rewind ████░░░░░░░░░░░░░░░░  20% (UI 骨架；Monaco 等 binary)
-M8  polish              ████████████████████ 100%
-M9  release pipeline    ██████████████████░░  90%
-v1.1  VS Code/JetBrains █████░░░░░░░░░░░░░░░  25% (VS Code 骨架 + LSP 骨架)
-```
-
-**549 个测试通过 · CI ubuntu + macOS 双矩阵绿色**。
+主分支执行 typecheck、lint、format、Vitest、TypeScript build，并在 CI 中覆盖 macOS/Linux；Tauri Rust backend 也纳入单独检查。不要从 README 中读取静态测试总数，当前结果以 [CI](https://github.com/oratis/deepcode/actions/workflows/ci.yml) 为准。
 
-详细汇报：[MORNING_REPORT.md](MORNING_REPORT.md)
+已知架构差距和处理顺序记录在 [docs/CODEX_ALIGNMENT_PLAN.md](docs/CODEX_ALIGNMENT_PLAN.md)。[MORNING_REPORT.md](MORNING_REPORT.md) 是早期历史快照，不再表示当前进度。
 
 ## 文档地图
 
@@ -79,6 +59,7 @@ v1.1  VS Code/JetBrains █████░░░░░░░░░░░░░
 
 | 文件                                                                         | 内容                                                |
 | ---------------------------------------------------------------------------- | --------------------------------------------------- |
+| [docs/CODEX_ALIGNMENT_PLAN.md](docs/CODEX_ALIGNMENT_PLAN.md)                 | 当前整体改造计划、审计证据、正反方审议与 PR 路线    |
 | [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)                         | 整体开发方案 v0.5（1500+ 行 / §3 模块 / §6 里程碑） |
 | [docs/VISUAL_DESIGN.html](docs/VISUAL_DESIGN.html)                           | 视觉设计 v0.4（11 屏 mockup）                       |
 | [docs/security-model.md](docs/security-model.md)                             | 威胁模型 + 防御层 + 攻击向量测试 + 已知缺口         |
@@ -95,7 +76,7 @@ packages/
   shared-ui/     # @deepcode/shared-ui — types shared between CLI + Mac client + VS Code
 apps/
   cli/           # deepcode-cli — Node.js CLI (npm publishable)
-  desktop/       # @deepcode/desktop — Electron Mac client
+  desktop/       # @deepcode/desktop — Tauri 2 + React Mac client
   vscode/        # @deepcode/vscode — VS Code extension (v1.1)
   lsp/           # @deepcode/lsp — LSP bridge for Neovim/Emacs/Sublime (v1.1)
 docs/
@@ -113,7 +94,8 @@ scripts/
 
 ## 致谢
 
-- **Anthropic** 的 [Claude Code](https://github.com/anthropics/claude-code) —— 对齐基准
+- **OpenAI Codex** —— 当前运行模型与客户端架构的重要公开参考
+- **Anthropic Claude Code** —— 早期兼容设计的重要参考
 - **DeepSeek** —— 模型与 API
 - **MCP** 生态 —— Model Context Protocol 协议
 

docs/BEHAVIOR_PARITY.md

@@ -1,5 +1,7 @@
 # Behavior Parity — DeepCode vs Claude Code
 
+> **历史快照（Claude 兼容矩阵）**：本文件记录既有兼容目标，不再作为当前完成度或安全保证。当前事实、已知分叉与 Codex 对齐路线见 [`CODEX_ALIGNMENT_PLAN.md`](CODEX_ALIGNMENT_PLAN.md)。
+
 > This document tracks where DeepCode's behavior **aligns with**, **deviates from**, or **deliberately enhances** Claude Code. It grows alongside the codebase. Last updated reflects what main contains.
 
 Legend: `✅` matches · `🟡` matches with caveats · `🔄` deferred · `⚠️` deliberately differs · `🆕` DeepCode-only addition