DevCodex — AI-powered development workflow rules for Copilot, Claude Code, Codex, Gemini CLI and Grok
DevCodex 是面向 AI 编程宿主的工作流运行时和宿主适配包。它通过一个 npm 全局包，把上下文、记忆、80+ 内置 Skill、报告与验证闭环接入 Codex、Claude Code、GitHub Copilot、Gemini CLI 和 Grok，让不同宿主在同一个项目里按更一致的开发流程协作。
如果你经常遇到 AI 新会话忘记项目背景、长任务中途断线、不同宿主规则不一致、修复过程没有记录、验证结果说不清这些问题，DevCodex 的目标就是把“随口聊天式开发”变成有上下文、有流程、有记录、可继续的 AI 编程协作。
npm install -g devcodex
devcodex --version
安装或更新后，先在目标项目或工作区完成下方初始化与状态检查，再完全退出并重新打开宿主的新会话。
DevCodex 不替代业务框架、GitHub CI、安全审计或人工评审。它也不接管 Codex、Claude Code 等宿主原有的个人 Skill、项目指令或配置文件。
AI 编程真正难的通常不是让模型写一段代码，而是让它在真实项目里稳定完成一个任务：
DevCodex 把这些能力组合成一个本地工作流入口：先理解当前任务，再按需读取上下文和记忆，选择合适的 Skill 与工作流，最后把关键过程、验证和结果沉淀下来。
| 问题 | DevCodex 怎么处理 | 用户得到什么 |
|---|---|---|
| 每次都要重新解释项目背景 | 按任务意图读取必要的项目上下文、历史记忆和相关源码 | 少重复说明，AI 更快进入有效状态 |
| 长任务和新会话容易断 | 把任务过程写入报告和文件记忆 | 后续会话可以围绕真实记录继续 |
| 多个 AI 宿主规则不一致 | 一个 npm 包刷新五个宿主的用户级适配 | 切换宿主时保留同一套工作流习惯 |
| 只有 prompt，没有执行闭环 | 开发、修复、分析、审计等任务都有过程、边界和验证记录 | 更容易复盘，也更容易发现“假完成” |
| 项目私有流程难复用 | 支持在项目里添加工作区 Skill | 你的流程、检查清单和团队约定可被五宿主共享 |
| 特色 | 说明 |
|---|---|
| 五宿主一个入口 | 支持 Codex、Claude Code、GitHub Copilot、Gemini CLI 和 Grok。不同宿主的 Hook、指令和插件能力不完全相同；DevCodex 会按宿主能力使用可用执行方式。 |
| 上下文按需进入会话 | 不把所有资料一股脑塞给 AI，而是根据当前任务选择必要的项目资料、记忆和源码线索。 |
| 文件记忆与长任务恢复 | 将关键过程写入当前项目的报告和记忆，减少“上一轮做到哪了”的断层。 |
| 长会话稳定性 | 当前任务提示保持有界，历史运行态不会随对话轮次无限注入；同一会话中的项目绑定会持续保留。 |
| 80+ 内置 Skill | 覆盖开发、修复、审计、发布、文档、架构、质量、安全、SRE、平台生态、产品与体验等专业场景。 |
| 报告与验证闭环 | 任务结束时沉淀结果、验证命令和剩余风险，让交付不是只靠一句“完成了”。 |
| 用户语言一致 | 回复、报告标题和面向用户的产物内容默认跟随当前用户消息；稳定命令、配置键、协议字段和默认文件名保持英文，便于跨语言兼容。 |
| 工作区 Skill | 用户可以在项目下添加自己的 Skill，让项目流程跨五宿主复用。 |
| 本地优先 | 安装包刷新本地用户级宿主适配；普通使用不需要启动额外后台服务。 |
| 原生资产共存 | DevCodex 不扫描、复制、合并、覆盖或删除这些用户资产。宿主自己的 Skill、项目指令和个人配置继续按原宿主规则生效。 |
你仍然在熟悉的宿主里用自然语言发起请求。DevCodex 在新会话中按用户请求的意图进入开发、修复、分析、审计等流程，并按需加载内置 Skill 或工作区 Skill。
用户请求
→ 判断任务意图
→ 读取必要上下文和记忆
→ 加载匹配的内置 Skill 或工作区 Skill
→ 执行开发 / 修复 / 分析 / 审计等流程
→ 输出结果、验证和报告
→ 写入记忆，方便后续会话继续
这里描述的是用户能感知的流程；不同宿主底层能力不同，DevCodex 会按当前宿主可用能力执行或回退。
>=18.17.0先确认本机是否已有 Node.js 和 npm：
node -v
npm -v
如果命令不存在，安装 Node.js LTS：
安装后重新打开终端，再确认：
node -v
npm -v
如果 Node.js 版本低于 18，请先升级 Node.js。
npm 模块名称是 devcodex，不带组织 scope。
安装前建议确认 npm registry 上的版本与本文档对应；如果 registry 上的版本不是当前文档对应版本，不要把下面命令当作当前版本安装。
npm install -g devcodex
devcodex --version
然后进入你要使用的项目或工作区根目录，初始化 DevCodex 运行态：
cd <你的项目或工作区根目录>
devcodex init
如果你使用的是 D:\Worker 这类多项目 workspace，建议在 workspace 根目录执行一次 devcodex init，而不是分别在子项目里猜目录。DevCodex 会创建 .devcodex/layout.json、.devcodex/workspace/ 和一份不会覆盖已有内容的 workspace Profile 基线；后续子项目的报告、记忆会按项目名稳定落到 .devcodex/<project>/，项目 Profile 缺失时回退到 workspace 层。
安装和初始化完成后，重新打开 Codex、Claude Code、GitHub Copilot、Gemini CLI 或 Grok 的新会话。
普通单项目只需执行 devcodex init，无需再运行 Profile 命令。多项目 workspace 中，如果某个子项目需要独立于 workspace 基线的 Profile，可在 workspace 根目录按项目名初始化：
devcodex init --profile api
api 必须能唯一匹配 workspace 中已经存在的项目目录；.devcodex 尚不存在并不影响首次执行。如果多个项目使用相同末段名称，请改用从 workspace 根目录开始的相对名称，例如 apps/api。DevCodex 只从真实项目目录解析目标，不会把旧运行记录或构建产物误认成项目；目标不存在或不唯一时会直接报错，并且不会创建 .devcodex。
需要先确认目标和计划路径时，可加 --dry-run：
devcodex init --profile api --dry-run
这个预览不会创建目录、Profile、备份或运行态文件。确认后去掉 --dry-run 即可；正式执行会根据项目已有的包、测试、构建与公开接口选择合适的 Profile 档位，并且只生成缺失文件，不覆盖已经编辑过的内容。
devcodex update 只刷新运行态，不会自动创建、升级或降级 Profile。需要手动预览或指定档位时，才使用高级命令 devcodex profile plan / devcodex profile init。
第一次在宿主里打开新会话时，宿主可能会提示是否信任或允许 DevCodex 管理的 Hooks、MCP、插件或本地命令。请允许 DevCodex-managed 项，然后重新打开一个新会话。
不同宿主的提示形式不完全一样：
| 宿主 | 可能看到的提示 | 建议 |
|---|---|---|
| Codex | Hooks、commands、MCP server、trust / allow | 允许 DevCodex-managed 配置 |
| Claude Code | settings、hooks、MCP 或本地命令确认 | 允许 DevCodex-managed 配置 |
| GitHub Copilot | MCP、工具或命令确认 | 允许 DevCodex-managed 配置 |
| Gemini CLI | settings、hooks 或命令确认 | 允许 DevCodex-managed 配置 |
| Grok | plugin、workspace 或本地命令确认 | 允许 DevCodex-managed 配置 |
如果拒绝这些提示，DevCodex 仍可能通过普通指令语义生效，但依赖 Hook、MCP 或插件的能力不会完整。DevCodex 只要求信任它自己管理的配置，不要求接管宿主原生 Skill、个人配置或业务项目指令。
在新的宿主会话里，直接用自然语言发起任务即可，例如：
分析当前项目，告诉我最应该先改进的三个问题。
阅读这个仓库，帮我修复当前失败的 GitHub CI。
DevCodex 会按任务意图选择流程和 Skill。普通使用者不需要手动配置内置 Skill。
@rocky如果你希望 DevCodex 在明确任务范围内自动继续执行，可以在请求里带上 @rocky：
@rocky 阅读当前项目，修复失败的 CI，完成后提交。
@rocky 是全局默认 @rocky 自动推进别名。进入自动推进后，DevCodex 会在当前会话里尽量连续完成需求、实现、验证、报告等步骤；如果你想退出，直接说“退出 auto”或“exit auto mode”即可。
自动推进不等于无限授权：删除文件、不可逆操作、越过项目范围、需要外部确认的发布动作等仍会遵守 DevCodex 的安全边界。当前只有 Hook 支持且白名单路径提供 runtime 级硬保证；在只依赖指令回退的宿主中，DevCodex 会尽量按语义继续推进，但不承诺完全等价的自动放行。
如果你想改成自己的别名，在项目根目录创建或修改：
<你的项目根目录>/.devcodex/workspace/profile/config.json
示例：
{
"extensions": {
"devcodex": {
"autoAliases": ["@team-auto"]
}
}
}
extensions.devcodex.autoAliases 用于替换全局默认别名；省略该字段表示继续使用默认 @rocky，设置为空数组 [] 表示关闭默认自动推进别名。
你不需要记住工作流名称、Skill 名或内部阶段。直接说明任务目标即可；为了减少来回确认，推荐把请求写成：
是否自动推进 + 目标或问题 + 范围与约束 + 验证要求 + 是否提交、推送或发布
分析当前项目的主要问题，按优先级给出建议。只分析，不修改文件。
分析当前项目，整理“用户登录限流”需求，列出目标、范围、用户流程、验收标准和影响，先给我确认，不要修改源码。
确认需求后可以继续说：
确认，按刚才的需求实施，完成后运行相关测试并提交。
检查支付回调偶发重复入账的问题，复现并定位根因，给出影响范围和修复方案。只诊断，不修改文件。
@rocky 修复当前失败的 GitHub CI，检查是否还有同类问题，运行完整验证，完成后提交。
从用户体验、架构、兼容性、测试和发布风险审查当前实现，只报告有证据的问题，不修改文件。
继续<任务名>任务
例如：
继续用户登录限流任务
提交、push、tag、GitHub Release 和 npm publish 都属于独立动作。需要发布时请直接写明：
@rocky 完成修复和全部验证后提交并推送 main，发布新的 patch 版本到 npm 和 GitHub Release，再用线上包重新安装验证。
几个实用技巧：
@rocky 只负责在已授权范围内自动推进，不会扩大删除、越界访问或发布权限。这通常不是版本缺少流程，而是以下某一层尚未就绪：npm 包、用户级宿主适配器、当前 workspace 运行态，或者宿主新会话加载。
先进入真正要使用 DevCodex 的项目或 workspace 根目录，再检查状态：
cd <你的项目或 workspace 根目录>
devcodex status
按输出处理：
devcodex status 输出 | 含义与处理 |
|---|---|
Codex 显示 adapter=not-ready 或 contract=failed | 用户级 Codex 适配器未通过合同检查。完全退出 Codex Desktop 或 CLI 会话，然后执行下方的适配器刷新命令。 |
.devcodex not initialized 或 Profile missing | 只表示当前终端所在目录没有 workspace 运行态。先确认目录正确；只有该目录确实是目标项目或 workspace 根时才执行 devcodex init。 |
Codex 为 adapter=ready; contract=passed，且 .devcodex present、Profile complete | 安装与 workspace 已就绪。完全退出并重新打开宿主，在同一项目目录新建任务；不要继续使用修复前已经打开的旧任务。 |
native=unverified | 只表示对应宿主的原生 CLI 探针未验证。若你使用的是 Codex Desktop，且 adapter/contract 已通过，这不是工作流阻断。 |
workspace 显示 host kernel not installed | 当前版本的宿主入口安装在用户 HOME，不要求项目目录再保存一套宿主文件；只要上方用户级 adapter/contract 已通过，这不是故障。 |
修复用户级适配器：
devcodex global-adapters apply
devcodex status
初始化正确的项目或 workspace：
devcodex init
devcodex status
devcodex status 只检查当前目录。若你在用户 HOME 中运行它，看到 .devcodex not initialized 或 Profile missing，并不能说明另一个项目目录未初始化；除非 HOME 本身就是目标 workspace，否则不要在那里执行 devcodex init。
devcodex update 只刷新 workspace 运行态，不能替代 devcodex global-adapters apply 修复用户级适配器。Codex 会在每次新任务开始时构建一次指令链，因此适配器修复后必须新建任务，已打开的任务不会中途重新加载。参见 OpenAI Codex 的 AGENTS.md 官方说明。
如果刷新后仍然失败，再运行：
devcodex doctor --json
Windows 使用 Scoop、NVM 或多套 Node.js 时，还应确认 devcodex 与 npm 全局目录属于同一套 Node.js：
Get-Command devcodex
npm root -g
不需要永久开启 Full access。“帮我审批”仍受 workspace 沙箱约束；它只决定符合条件的越界动作如何审批，不会自动扩大文件系统或可执行文件范围。先运行：
Get-Command node
node --version
devcodex doctor
devcodex doctor --json
重点看两类诊断：
| 诊断 | 含义与恢复 |
|---|---|
node runtime BLOCK (... reason=sandbox-exec-denied) | ambient Node launcher 在 DevCodex JavaScript 启动前被沙箱拒绝，Hook 此时无法自我恢复。对该 launcher 做一次明确审批，或改用路径稳定、可受信任的系统 Node，然后重跑 devcodex doctor。Volta、NVM、FNM、asdf 等 shim 更新物理路径后可能需要重新批准。 |
某个宿主为 unverified，JSON 含 GLOBAL_HOST_TARGET_UNVERIFIED / sandbox-read-denied | 只表示该用户级宿主目录在当前沙箱中不可读；其他宿主仍会继续检查。批准读取该目录后重试即可，不代表必须给整个 Codex 完全访问权限。 |
如果界面只显示 Skill Route blocked 或一个待执行 nextCall，它表达的是工作流仍有待办，不足以证明是权限问题；BUDGET_BLOCKED 则表示当前路由预算耗尽且没有可执行恢复动作，同样不是权限证据。REBIND_SEMANTIC_DRIFT 表示刷新后的任务语义已经改变，旧路由会立即退役且不再重试；下一条真实用户消息会建立新路由。新版本会把可见恢复信息压缩为当前精确动作或 typed 状态，完整 NextActionEnvelopeV1 只保留在结构化机器字段中；不会自动重放修改性操作。
若更新后仍看到整段原始 envelope 或旧的重复提醒，通常是旧任务仍绑定启动时运行态。执行：
npm update -g devcodex
devcodex global-adapters apply
devcodex doctor
然后完全关闭旧任务并新建任务。完全访问可以作为短时诊断对照，但不是默认修复方案。
npm update -g devcodex
devcodex --version
更新完成后，重新打开宿主的新会话。更新不会强制中断已经打开的会话，也不会让它在任务中途切换版本；让当前会话自然结束，新会话会使用更新后的 DevCodex。
npm uninstall -g devcodex
需要排查空间占用或旧电脑遗留的运行态时，可以查看各类状态的负责人、文件数、体积和最后使用时间：
devcodex runtime status
devcodex runtime prune --dry-run
清理命令默认只预览。确认列表后使用 devcodex runtime prune --apply；它只清理达到保留期限的原子写入临时文件，不会自动删除锁文件、当前任务状态或无法识别的文件。
安装或更新 DevCodex 后，npm 会在安装生命周期中刷新用户级宿主适配。已打开的宿主会话会继续使用它启动时已经加载的版本，不会被更新过程强制终止；更新后的配置由新会话读取，因此完成安装或更新后请重新打开一个新会话。
DevCodex 内置 Skill 随安装包一起提供。普通使用者不需要手动配置内置 Skill；新会话开始后，DevCodex 会按请求意图自动选择需要的 Skill。
DevCodex 分两层生效：
| 层 | 位置 | 用途 |
|---|---|---|
| 用户级宿主适配 | 用户 HOME 下的 Codex、Claude Code、GitHub Copilot、Gemini CLI、Grok 配置目录 | 让五个宿主知道 DevCodex 的入口、指令、Hook、MCP 或插件配置 |
| 工作区运行态 | 当前项目或 workspace 根目录下的 .devcodex/ | 保存当前项目的 Profile、报告、记忆、任务状态和工作区 Skill |
单项目时，运行态通常在：
<项目根目录>/.devcodex/
多项目 workspace 推荐在 workspace 根目录执行 devcodex init。初始化后，运行态通常是：
<workspace根目录>/.devcodex/
layout.json
workspace/
profile/ # init 自动创建：workspace 级 Profile 基线
.runtime-state/ # DevCodex 管理的派生状态；不要手动编辑
skills/ # 按需创建：workspace Skill
<project>/
profile/ # 按需创建：项目 overlay
reports/
.memory/
这样你在 <workspace根目录>/<project> 中开启会话时，DevCodex 有一个清晰、可验证的目录基线，不会把报告、记忆或 Profile 写到不稳定的 legacy 位置。
如果你希望为某个项目增加自己的流程、检查清单或团队约定，可以创建 DevCodex 工作区 Skill。
这里的 Skill 属于 DevCodex 工作区层，不是某个宿主的原生 Skill。新会话开始后，DevCodex 会读取它，并可在 Codex、Claude Code、GitHub Copilot、Gemini CLI 和 Grok 中按意图触发。
单项目时，可以放在项目根目录：
<你的项目根目录>/
.devcodex/
workspace/
skills/
<id>/
SKILL.md
intent.json
多项目 workspace 时，请放在 workspace 根目录：
<workspace根目录>/
.devcodex/
workspace/
skills/
<id>/
SKILL.md
intent.json
例如：
my-app/
.devcodex/
workspace/
skills/
release-check/
SKILL.md
intent.json
SKILL.md：
---
name: release-check
description: >
当用户准备发布版本、检查 changelog、tag、npm publish 或 GitHub release 时使用。
---
# release-check
## 步骤
1. 检查版本号、变更记录和发布分支。
2. 运行项目约定的测试与打包命令。
3. 输出发布前风险和下一步。
intent.json：
{
"schemaVersion": "SkillIntentV1",
"skillId": "release-check",
"intents": [
{
"id": "release",
"label": "发布检查",
"include": ["发布", "release", "tag", "npm"]
}
],
"examples": {
"positive": ["帮我发版前检查", "准备 npm publish"],
"negative": ["修复登录 bug", "解释这个函数"]
},
"summary": "发布前检查版本、changelog、tag、测试、打包和发布风险。"
}
新建或修改后，重新打开会话，或在后续请求中自然触发相关意图。
Codex、Claude Code 等宿主自己的项目指令、个人 Skill 和配置文件继续按宿主原有规则生效。
DevCodex 不扫描、复制、合并、覆盖或删除这些用户资产。即使名称相同，宿主原生 Skill 也不视为 DevCodex 所有。
如果希望五个宿主通过 DevCodex 使用同一套能力，写 DevCodex 工作区 Skill：
<你的项目根目录>/.devcodex/workspace/skills/<id>/SKILL.md
多项目 workspace 时，把上面的 <你的项目根目录> 换成 workspace 根目录。
如果只希望某个宿主单独使用，继续使用该宿主自己的 Skill 或指令机制。
DevCodex 会尽量按当前宿主支持的方式输出报告、记忆和产物链接：宿主支持点击时给出可点击链接，不支持时给出可复制路径。
如果你在宿主日志或调试输出中看到 profile_load、invoke 等字样，通常表示 DevCodex 正在通过本地工具读取项目 Profile 或调用本地能力；普通使用者不需要手动执行这些内部动作。
.codex/、.claude/、.gemini/、.grok/、.agents/ 或宿主项目指令文件写进业务 workspace；宿主适配写在用户 HOME，workspace 侧只保留 .devcodex/ 运行态。FAQs
DevCodex — cross-host AI coding engineering harness for Codex, Claude Code, GitHub Copilot, Gemini CLI, Grok, and Cursor
The npm package devcodex receives a total of 250 weekly downloads. As such, devcodex popularity was classified as not popular.
We found that devcodex demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Socket found 16 malicious Firefox extensions designed to steal crypto wallet recovery phrases and private keys using cloned Rabby and OKX interfaces.
Product
Socket now scans VS Code extensions, giving teams early detection of risky behaviors, hidden capabilities, and supply chain threats in developer tools.
Research
/Security News
Socket uncovered two malicious VS Code themes in a GlassWorm-linked cluster with thousands of installs across VS Code Marketplace and Open VSX.