DevCodex — 意图驱动的 AI Coding 工作流运行时

让 AI 编程从一次性聊天，变成可验证、可续接的工程流程。

DevCodex 是面向 Codex、Claude Code、GitHub Copilot、Gemini CLI、Grok 和 Cursor 的意图驱动 AI Coding 工作流运行时。它先识别任务目的、目标项目和风险，再按需加载项目 Profile、上下文、记忆和专业 Skill，并把确认、执行、验证、报告与任务续接组织成一套共享工作流模型。

本地优先、文件支撑的控制层与六宿主适配包，把项目上下文、专业 Skill、确认、验证和报告闭环带入多个 AI Coding 宿主。作为工作流运行时和宿主适配包，它协调工程流程，不托管模型。

• 按任务意图选择工作流、上下文与专业 Skill
• 把需求、确认、实现、验证、报告和续接形成可追踪闭环
• 在六个 AI Coding 宿主间保持一致流程，同时诚实保留能力差异

npm install -g devcodex
cd <你的项目根目录>
devcodex init
devcodex status

安装或更新后，请完全退出旧会话，再从目标项目打开宿主的新会话。

DevCodex 不是什么

• 它不是模型网关，不代理或托管模型调用。
• 它不是通用 Agent 框架，也不是多 Agent 编排器。
• 它不替代业务框架、GitHub CI、安全审计或人工评审。
• 它不保证六个宿主拥有完全相同的 Hook、MCP、插件、权限或生命周期事件。

“本地优先”表示工作流状态、Profile、报告、记忆和工作区 Skill 以本地文件保存；模型执行和数据处理仍遵循所选 AI Coding 宿主的规则。

目录

• 为什么需要 DevCodex？
• 5 分钟开始
• 安装会改变什么
• 工作流、Skill 与宿主边界
• 常见任务怎么说
• 常见问题与排错
• 更新
• 卸载
• 添加自己的 Skill
• 边界
• 许可证

完整用户文档：DevCodex Docs。

为什么需要 DevCodex？

真实工程任务往往跨文件、跨轮次、跨宿主：新会话缺少项目背景，长任务容易断层，项目规范难复用，验证也容易被一句“完成了”替代。

DevCodex 把意图识别、按需上下文、专业 Skill、确认边界、验证、报告和续接放进同一条流程，让 AI 在明确项目与证据范围内工作。

DevCodex 解决什么问题？

核心特色

它如何工作？

用户请求
  → 判断任务意图与项目边界
  → 读取必要上下文和记忆
  → 加载匹配的内置 Skill 或工作区 Skill
  → 执行开发 / 修复 / 分析 / 审计
  → 验证、报告并写入可续接状态

用户仍然用自然语言提出任务；底层强制能力取决于当前宿主可用的 Hook、MCP、插件和权限。

适合谁？

• 同时使用一个或多个受支持 AI Coding 宿主的开发者。
• 经常处理跨文件、跨轮次、需要验证的工程任务的人。
• 希望项目规则、发布流程和团队检查清单可复用的人。

5 分钟开始

系统要求

• Node.js >=18.17.0
• npm
• 至少一个受支持宿主

node -v
npm -v
npm install -g devcodex
devcodex --version

安装前请确认 registry 上的版本；如果 registry 上的版本不是文档对应版本，不要把本地源码版本当作已经发布。

进入项目或多项目 workspace 的真实根目录：

cd <你的项目根目录>
devcodex init
devcodex status
devcodex doctor

devcodex init 创建 .devcodex/ 运行态；安装生命周期中刷新用户级宿主适配，但安装本身不修改业务源码。更新后必须重新打开宿主的新会话，已打开的会话不会中途换版本。

Grok 推荐使用 Grok Full 入口：

devcodex grok

普通 grok 是 Partial 兼容入口。Cursor 本地 IDE / CLI 为 Beta；Cursor Cloud Agent 保持 Partial / UNVERIFIED。

第一个任务可以直接写：

分析当前项目最应该先改进的三个问题。只分析，不修改文件。

更多步骤见快速开始。

安装会改变什么

项目 Profile

普通单项目只需 devcodex init。多项目 workspace 的子项目需要独立 Profile 时，从 workspace 根预览并初始化：

devcodex init --profile <项目相对路径> --dry-run
devcodex init --profile <项目相对路径>

目标必须真实且唯一；预览不写入，正式执行只补缺失基线，不覆盖已编辑内容。详见配置。

首次信任提示

首次打开新会话时，宿主可能要求允许 DevCodex 管理的 Hook、MCP、插件或本地命令。只允许 DevCodex-managed 项；若拒绝，依赖这些能力的流程不会完整。

第一次直接用自然语言即可：

阅读这个仓库，修复当前失败的 GitHub CI，并运行相关测试。

自动推进：@devcodex-auto

正式入口是 @devcodex-auto；@rocky 是默认兼容快捷别名。自动推进只在明确范围内连续工作，不扩大删除、发布或越过项目范围的权限。

项目配置可以替换默认快捷别名：

{
  "extensions": {
    "devcodex": {
      "autoAliases": ["@team-auto"]
    }
  }
}

extensions.devcodex.autoAliases 为非空数组时替换 @rocky；省略时保留默认值；空数组 [] 关闭默认快捷别名，但不会改名 @devcodex-auto。

工作流、Skill 与宿主边界

六个主工作流面向日常任务，两个高级工作流只用于治理或兜底：

plan 是阶段或能力，不是第九个 canonical workflow。

当前机器事实为 86 个 Skill（83 active + 3 gray）；公开摘要使用 80+。Workflow、Domain、Delivery & Governance 和 Workspace 四类 Skill 按任务与阶段渐进加载。

Rules / AGENTS.md 提供约束，Skills 提供专业流程，MCP 提供结构化工具与数据访问；三者由 DevCodex 协调，不构成简单替代关系。详见工作流、Skill和宿主边界。

常见任务怎么说

请求最好同时说明目标、范围、约束、验证和是否提交：

分析当前架构风险，给出证据和优先级。只分析，不修改文件。

为当前 API 增加幂等支持。先整理需求，确认后实施并运行相关测试。

复现支付回调重复入账，定位根因，检查同类路径并修复。

继续<任务名>任务

@devcodex-auto 修复失败的 CI，验证通过后提交。

只有明确写出 push、tag、GitHub Release 和 npm publish，才把对应发布动作纳入任务范围。更多示例见常见任务。

常见问题与排错

安装最新版后，为什么没有需求概况、PC0~PC7 或 CP 流程？

在目标项目运行：

devcodex status
devcodex doctor --json
devcodex global-adapters apply

然后完全退出宿主并新建会话。adapter=not-ready、contract=failed 或 host kernel not installed 表示受管入口未就绪；native=unverified 只表示缺少原生回放证据，不等于 adapter 失败。

Grok 能看到 Skill 或 MCP，但没有完整上下文怎么办？

使用 devcodex grok。普通 grok 是 Partial；catalog 或路由决定不等于正文已加载，StageLoadReceiptV1 才是阶段正文成功回执。Grok ParserError、Hook 双来源与恢复步骤见宿主边界。

Cursor 已安装 DevCodex，但为什么没有流程或 SkillRoute？

检查 devcodex doctor --json 和 agent --version。受管 Hook 位于 ~/.cursor/hooks.json；Cursor Cloud Agent 不加载用户级 Hook，不能继承本地 Beta 结论。命令碰撞与 IDE / CLI / Headless 差异见宿主边界。

“帮我审批”时反复重新连接，是否必须开启完全访问？

不需要永久开启 Full access。node runtime BLOCK / sandbox-exec-denied 表示 Node launcher 被当前沙箱拒绝；GLOBAL_HOST_TARGET_UNVERIFIED 表示对应用户级宿主目录当前不可读。先按最小范围批准并重跑 devcodex doctor，不要把完全访问当作默认修复。

完整的 adapter、contract、native、sandbox、临时目录与运行态排查见故障排查和限制与边界。

更新

npm update -g devcodex
devcodex --version
devcodex global-adapters apply

更新后重新打开宿主的新会话。

卸载

先预览，再显式清理 DevCodex 管理的六宿主资产，最后卸载 npm 包：

devcodex uninstall --dry-run
devcodex uninstall --apply
npm uninstall -g devcodex

用户自己的配置、指令和 Hook 会保留；若受管资产被修改或所有权无法验证，清理会失败关闭。不要先卸载 npm 包，否则安全清理命令会先消失。

运行态与临时产物检查

devcodex runtime status
devcodex runtime prune --dry-run
devcodex tmp status --json
devcodex tmp maintain --project=<project> --partition=runs

清理类命令默认只预览；实际操作必须显式 --apply 和完整 scope。MemoryCursorV1、MemoryFileTransactionReceiptV1、WorkspaceTempManifestV2 与 NextActionEnvelopeV1 等高级协议见限制与边界。

生效方式

DevCodex 分为用户 HOME 下的宿主适配层与项目 / workspace 的 .devcodex/ 运行态。内置 Skill 随 npm 包安装；工作区 Skill 由项目提供。

多项目 workspace 的典型结构和恢复路径见配置与故障排查。

添加自己的 Skill

在项目或 workspace 根创建：

<你的项目根目录>/
  .devcodex/
    workspace/
      skills/
        <id>/
          SKILL.md
          intent.json

稳定路径是 <你的项目根目录>/.devcodex/workspace/skills/<id>/SKILL.md。SKILL.md 写目标、步骤、输入输出和边界；intent.json 写可验证的触发语义。完整示例见Skill 参考。

与宿主原生 Skill 共存

DevCodex 不扫描、复制、合并、覆盖或删除这些用户资产。Codex、Claude Code 等宿主自己的 Skill、项目指令和个人配置继续按宿主规则生效。

需要六宿主共享时使用 DevCodex 工作区 Skill；只服务单一宿主时继续使用该宿主原生机制。

边界

• DevCodex 不替代业务框架、GitHub CI、安全审计或人工评审。
• 宿主能力、权限与生命周期事件不同，不能互相继承验证结论。
• 安装不会把用户级宿主配置写进业务 workspace；项目侧只保存 .devcodex/ 运行态。
• 工作区 Skill 只影响其所在项目或 workspace。
• 更多限制见限制与边界。

许可证

AGPL-3.0