Skip to content

OPEN_SOURCE_READINESS.md

Latest commit

 

History

History
138 lines (93 loc) · 6.79 KB

OPEN_SOURCE_READINESS.md

File metadata and controls

138 lines (93 loc) · 6.79 KB
Raw

Open Source Readiness

Public Positioning

Codex-叉叉 is for Windows users who want:

  • Codex Desktop to start with Simplified Chinese UI defaults.
  • A guided way to configure Wokey, OpenRouter, or any OpenAI-compatible relay.
  • Browser, Chrome, and Computer Use local capabilities to be visible and usable in domestic API Key workflows without relying on VPN for local capability setup.

Credential Policy

  • Wokey preset: includes an intentional public test key for first-run validation.
  • Custom/OpenRouter presets: no bundled private API key.
  • User API keys: only written to the user's local Codex config after backup and merge.
  • Build hosts: keep IPs, users, SSH aliases, RDP endpoints, passwords, private keys, and private runbooks out of the public repo.
  • docs/ is treated as local/internal material and is ignored by git.
  • skills/ is treated as local/internal workflow material and is ignored by git. It may hold private authoring and review skills, but those process files are not part of the public release.

Release Boundary

Source code can be public. Release artifacts need a separate maintainer decision because the Windows installer is built from a user-supplied official Codex app copy and resource-level patches.

Mandatory Maintainer Push Check

Stop before every local git push: maintainer pushes must use the checked wrapper, not the machine's default GitHub identity.

Do not run a plain git push origin main from a workstation.

Required one-time local setup:

git config --local codex-zh.githubSshKey /absolute/path/to/maintainer/github/key

This must stay repository-local. Use git config --local so the value is written to this checkout's .git/config only. Do not use git config --global for repository-specific GitHub accounts, SSH keys, or author identities, because global config affects other repositories on the same workstation.

If the GitHub login account is not the repository owner, also configure:

git config --local codex-zh.githubAccount expected-github-account

Repository-specific commit author identity should also be local-only:

git config --local user.name "expected-github-account"
git config --local user.email "github-noreply-email@example.com"

These local author settings take precedence inside this repository but do not change other projects. Other repositories should keep their own local identities or the user's global Git identity.

Required local check:

npm run push:check

Required push command for main:

npm run push:maintainer -- origin main

Required push command for release tags:

npm run push:maintainer -- origin v0.1.2

After pushing, confirm remote sync:

git rev-parse HEAD
git ls-remote origin refs/heads/main

The two SHAs must match for main pushes. gh auth status alone is not enough because the GitHub CLI token and the SSH identity can belong to different accounts. The GitHub Actions workflow may push README release-link updates with github-actions[bot]; this rule is for local maintainer pushes.

GitHub Release Packaging

GitHub Actions can build the Windows installer automatically after a version tag is pushed or a GitHub Release is published. The workflow is .github/workflows/release.yml.

Release copy is user-facing and must be Simplified Chinese by default. GitHub Release notes must describe user-visible features and fixes, not build status. The workflow generates Release notes from the matching CHANGELOG.md section such as ## v0.1.2; missing or non-Chinese bullets should block the release. Technical names such as ChatGPT.exe, Codex.exe, provider IDs, commands, versions, and file names may remain English.

Repository secrets for automatic release builds:

Secret Required Purpose
CODEX_WINDOWS_APP_ZIP_URL Yes Private or public URL to the pinned official Windows ChatGPT/Codex .zip or .msix archive.
CODEX_WINDOWS_APP_ZIP_SHA256 Legacy fallback SHA-256 of the source archive. release-sources.json is authoritative unless a workflow input explicitly overrides it.
CODEX_WINDOWS_APP_LABEL Recommended Installer filename label, for example ChatGPT-26.715.31925.

Windows 打包目前是显式开启项：只有仓库变量 CODEX_ZH_BUILD_WINDOWS=true 时才运行。待 CODEX_WINDOWS_APP_ZIP_URL 切换到 release-sources.json 所锁定的新版 ChatGPT Windows 归档后再开启；macOS arm64/x64 发布不依赖此项。

The source archive must contain a folder with:

  • ChatGPT.exe (current) or Codex.exe (legacy fallback)
  • resources/app.asar

Do not default release builds to winget install ChatGPT -s msstore. That command installs the current Microsoft Store version, so a Store update can silently change the upstream ChatGPT version used by Codex-叉叉. Codex-叉叉 releases must build from the exact desktop version and SHA-256 pinned in release-sources.json; CI also verifies the version inside resources/app.asar.

When v* tag is pushed or a release is published, the workflow:

  1. Runs npm test.
  2. Installs Inno Setup on the Windows runner.
  3. Downloads and verifies the pinned official ChatGPT/Codex app archive and embedded desktop version.
  4. Builds the staged Codex-叉叉 app.
  5. Builds the Inno Setup installer and .sha256 file.
  6. Installs the generated installer silently and runs codex doctor.
  7. Creates the GitHub Release when the trigger was a version tag push.
  8. Uploads the installer and checksum back to the GitHub Release assets.

The workflow can also be run manually with workflow_dispatch. Manual URL input should only be used for public URLs; use repository secrets for private signed URLs.

Typical release command:

git tag v0.1.1
npm run push:maintainer -- origin v0.1.1

Before publishing a release:

  • Run npm test.
  • Run npm run logs:check.
  • Add a Chinese CHANGELOG.md section for the version being tagged.
  • Confirm the release packaging workflow can access the pinned official Codex app source zip and matching SHA-256.
  • Verify codex.exe doctor --summary --ascii --no-color returns 0 fail.
  • Verify Simplified Chinese defaults.
  • Verify Wokey public test key can complete a minimal request.
  • Verify custom relay setup with a private test key, without logging the key.
  • Verify Browser, Chrome, and Computer Use entries are visible and installable.
  • Generate SHA-256 metadata for the installer.

CodexPlusPlus Comparison Note

CodexPlusPlus describes itself as an external launcher and does not appear to rewrite app.asar or official Codex install files in the checked source. It does, however, heavily patch Codex runtime behavior through CDP-injected JavaScript and writes Codex config/state files for relay and plugin workflows. The accurate distinction is file-level patching versus runtime behavior patching, not "patch" versus "no patch".