devcodex

模型和宿主负责推理、写代码与执行工具；DevCodex 以任务意图为起点，负责判断要完成什么、作用于哪个项目、该读取什么、加载哪些专业能力、按什么工程流程推进，以及怎样证明真正完成。

意图驱动 · 6 个 AI Coding 宿主 · 8 条任务工作流 · 80+ 专业 Skill · 项目上下文与记忆 · Sticky Auto 自动推进 · 长任务恢复 · 跨会话续接 · 证据化完成 · 受控自我进化

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

安装或更新后保留原任务。宿主提供连接重载时，刷新 DevCodex 连接并核对当前加载版本；没有该能力时，保存检查点、继续可执行工作，方便时重载宿主。安装成功不代表已有连接已经加载新版，无需为更新另建任务。

第一个任务可以直接这样说：

分析当前项目最值得优先解决的三个问题。
先说明读取范围和证据，只分析，不修改文件。

目录

• 为什么需要 DevCodex？
• 安装后，你能解决什么？
• 什么时候直接使用宿主，什么时候用 DevCodex？
• 5 分钟开始
• 安装会改变什么
• 工作流、Skill 与宿主边界
• 常见任务怎么说
• 常见问题与排错
• 更新
• 卸载
• 边界
• 文档
• 贡献
• 社区
• 许可证

---

为什么需要 DevCodex？

模型越来越会写代码，但真实工程任务仍然经常失败在代码生成之外：

• 新会话不了解项目，每次都要重新解释背景；
• 需求还没有说清楚，AI 就开始修改文件；
• 长任务跨文件、跨阶段后容易偏离目标；
• 会话中断后，只能依靠旧聊天摘要猜测做到哪里；
• 通用模型缺少当前问题需要的专业工程方法；
• 简单任务和高风险任务被用同一种方式处理；
• 一句“已经完成”没有测试、证据和剩余风险；
• 同样的问题反复出现，却没有沉淀成下一次可复用的能力；
• 切换 Codex、Claude Code 或 Cursor 后，项目工作方式又要重新维护一套。

DevCodex 补上的，就是 AI Coding 与真实软件工程之间缺少的这一层。

只依赖当前 AI Coding 会话	加上 DevCodex
背景主要留在聊天窗口	项目上下文、任务状态、报告和记忆跟随项目保存
容易拿到需求就直接编码	先判断目标、项目、范围、风险和是否允许修改
主要依赖模型的通用能力	根据任务和阶段加载对应的专业 Skill
长任务中断后从头分析	从任务身份、检查点、确认状态和剩余项继续
大项目每轮重复读取	可按变化范围和影响关系做增量分析与复证
“代码写完”等于“任务完成”	测试、构建、报告、证据和剩余风险共同收口
项目经验散落在对话里	重复问题可形成受控进化候选和项目 Skill
每个工具单独维护规则	六个宿主复用同一套项目工程方法

意图驱动：你只需要说目标，DevCodex 决定怎样工作

DevCodex 不要求用户先学习工作流名称，也不会看到某个关键词就机械套用固定 Prompt。它会先把你真正想得到的结果结构化，再让这份结构化意图驱动后面的项目识别、上下文、Skill、流程、Auto/确认、执行和验证。下游组件不能各自重新解释原始文本。

它会同时判断：

• 最终需要的是结论、代码修改、问题修复、系统审查，还是继续历史任务；
• 请求作用于哪个项目，允许处理哪些目录、模块和业务范围；
• 当前任务的风险有多高，是否允许修改文件；
• 需要读取哪些 Profile、相关源码、历史记忆和验证证据；
• 当前阶段应该加载哪些专业 Skill；
• 哪些节点需要用户确认，哪些可以由 Auto 持续推进；
• 应该运行哪些验证，以及什么条件下才能宣布完成。

你的请求	DevCodex 识别后的工程路径
“分析测试为什么失败，不要修改”	进入只读分析，说明读取范围、证据与未验证部分
“复现并修复这个失败用例”	进入修复流程，先复现、定位根因，再修改和回归
“为支付回调增加幂等”	进入开发流程，先明确需求、方案、范围与验收
“审查当前支付链路的风险”	进入证据审查，不默认修改文件
“继续支付回调幂等任务”	定位原任务，复核当前状态后从准确断点续接
“这个设计是否合理？”	先判断只需要分析建议，还是最终需要落地修改

意图不是一次性的分类标签，而是整条工程链的控制起点：

用户目标
→ 任务类型
→ 目标项目、范围与风险
→ 上下文与记忆
→ 专业 Skill
→ 工作流与确认方式
→ 验证和完成标准

当用户目标发生变化，例如从“只分析”变成“按方案实施”、从单项目扩大到整个 workspace，或临时增加提交与发布要求，DevCodex 会重新结构化意图，再统一刷新工作流、上下文、权限和验证边界。范围变化或短时凭据过期本身不会直接变成一次用户确认。

Auto 只负责在已经识别的意图和已授权范围内持续推进，不会绕过意图判断，也不会把只读分析自动变成代码修改。

从需求到交付的完整闭环

flowchart LR
    A[说出目标] --> B[识别任务意图]
    B --> C[判断项目、范围与风险]
    C --> D[读取上下文与记忆]
    D --> E[加载当前专业 Skill]
    E --> F[明确需求、方案与验收]
    F --> G{确认或 Auto 推进}
    G --> H[执行修改]
    H --> I[测试、构建与检查]
    I --> J[报告证据与剩余风险]
    J --> K[保存任务状态与续接点]
    K --> L{是否发现可复用经验}
    L -- 否 --> M[任务完成]
    L -- 是 --> N[生成受控进化候选]
    N --> M

DevCodex 不是在开始前多塞一段 Prompt，而是持续管理任务从理解、执行到验证和交接的全过程。

同一个模型，为什么会表现得更聪明？

DevCodex 不改变模型参数。它通过四件事提升 AI 在真实项目中的有效表现：

1. 给出正确目标：先判断最终要结论、修复、功能、审查还是续接；
2. 提供正确资料：只读取当前任务需要的项目规范、源码、记忆和证据；
3. 调用正确能力：在当前阶段加载对应的专业 Skill，而不是一次性塞入全部规则；
4. 获得真实反馈：测试、构建、命令结果、代码差异和审查证据会继续影响后续判断。

简单任务可以走更短路径；涉及公共契约、数据、安全、多模块或发布风险时，会自动提高复审和验证强度。是否需要确认只由当前结构化意图与动作授权决定，风险标签、复审器和验证器不能自行要求确认。流程仪式、技术方案深度与验证范围分别判断，不再用一个模糊的“简单/复杂”标签同时控制三者：当前任务中用户明确说法优先，其次才是项目配置、基于项目事实的智能识别和保守回退。入口先初判，读取项目后再二次判断，并在 PC8～PC10 写清流程/方案、验证范围与预计耗时、后续阶段和当前是否需要用户动作。

Profile 可配置 extensions.devcodex.workflowRouting.mode 为 adaptive（默认）、simple 或 standard，并用 showPlan 控制展示密度；该配置只提供流程仪式默认值，不能降低公共契约、状态恢复、package 或发布等强制义务。入口 PC0 同时显示已安装包、当前 runtime 与源码候选的版本关系，避免“版本号相同”被误报为运行内容完全一致。

产物打开按实际呈现面而不是仅按宿主名称决定。Codex Desktop 输出真实的本地文件链接；VS Code、Zed、JetBrains 可输出对应打开命令；未知或未验证界面直接给可复制绝对路径。系统只有在打开动作执行且回读成功时才会写“已打开”，renderer 选中、命令生成或链接渲染本身不冒充打开成功。

Auto 自动推进：一次授权，持续完成整条工程链

普通模式下，DevCodex 会在需求、方案和实施计划等关键节点等待确认。需要让 AI 在已授权范围内持续推进时，可以显式进入 Auto：

@devcodex-auto 完成支付回调幂等修复。
先复现和确认根因，再完成方案、修改、相关回归、报告与任务收口；
不要扩大到删除、push 或发布。

Auto 不会跳过工程流程，而是自动通过适用的流程确认，并继续执行后面的分析、实施、验证、报告和状态保存：

• 有效入口先结构化为 executionDecision=enable-auto；正式任务建立后由任务级 Auto 持续承接，不依赖短时 receipt 或会话 TTL，不需要每个阶段反复回复“继续”；
• 需求、方案、实施计划、测试、证据和报告仍然会生成，不会因为自动推进而消失；
• 可恢复失败最多自动重试 2 次；实际修改范围扩大、证据过期或验证失败时会停止当前动作、重新结构化意图并在原授权仍适用时继续，不会机械切回确认；
• 删除、项目外写入、危险操作、push、Tag、Release 和发布不会因为进入 Auto 自动获得授权；
• 不同宿主对 Hook、权限和自动放行的支持不同；能力不足时停止对应动作并明确提示，不会覆盖结构化 Auto 决定。

正式入口是 @devcodex-auto，默认快捷别名是 @rocky。可用 退出 auto、关闭自动模式 或 切回确认模式 退出；正式任务在恢复时按任务 identity 和结构化意图续接，不能仅因新会话或短时凭据过期撤销任务级授权。

Auto 的价值不是“跳过步骤”，而是让已经明确目标和边界的任务不再被机械确认打断，同时继续保留验证、证据和安全底线。

在 Profile 的 config.json 中设置：

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

非空数组会替换默认快捷别名 @rocky；空数组 [] 会关闭默认快捷别名。正式入口 @devcodex-auto 不会被重命名。

---

安装后，你能解决什么？

1. 跨会话恢复：任务不再困在旧聊天窗口里

DevCodex 的续接不是“读一段旧会话摘要，然后继续猜”。

对正式任务，它会持续保存可恢复的工程状态，包括：

• 任务身份和原始目标；
• 已确认范围、非目标和验收标准；
• 当前工作流与所处阶段；
• 已完成步骤、未完成步骤和停止位置；
• 修改过的文件与关键决策；
• 已运行的验证、结果和证据；
• 剩余风险、阻塞项和下一步；
• 原任务已经获得和没有获得的权限。

新会话收到：

继续支付回调幂等修复任务。

会先完成以下恢复过程：

flowchart LR
    A[按任务名定位原任务] --> B[读取报告、记忆与检查点]
    B --> C[复核当前分支、文件和项目状态]
    C --> D{旧证据仍然新鲜吗}
    D -- 是 --> E[恢复原工作流与剩余步骤]
    D -- 否 --> F[标记过期或冲突并重新结构化意图]
    E --> G[从准确断点继续]
    F --> G

恢复后仍然遵守原来的边界：原任务只读，续接后仍然只读；原任务没有 push 或发布权限，换会话后也不会自动获得。

正式任务本身不会因为等待、关机、断网、宿主退出或版本升级而过期。会短期过期的是 fenced owner——它只是防止两个会话同时写同一任务的写入租约，默认空闲租期为 5 分钟；租约过期或 accepted Stop 主动释放后，任务身份、概况、CP 确认、报告、记忆与检查点仍保留。新会话可发送 继续 <准确任务名>，DevCodex 会在服务端重新核对项目根、TaskIdentityV2、概况、CP 摘要、旧 turn/operation 状态并执行单赢家 CAS，成功后同时生成新的 admission generation 与 owner generation，无需重写任务或重复确认同一 CP。

如果旧 owner 仍有效、旧工具操作尚未收口、任务真相发生漂移、任务已经终态，或另一个会话先完成接管，恢复会失败关闭并返回可执行的 typed next step（等待租约、完成/对账旧操作、修复漂移、显式 reopen，或读取赢家），不会把“拒绝接管”误报成“任务已丢失”。

这带来几个实际结果：

• 不需要重新粘贴几十轮旧对话；
• 不会把相似任务错误地串在一起；
• 不会因为换会话就忘记已经确认的范围；
• 当前代码已经变化时，不会直接沿用过期方案；
• 可以把未完成任务交给新的会话继续；
• 在支持的宿主之间，也可以基于同一项目中的任务文件、报告和证据接力。

跨宿主接力复用的是项目工程状态，不是无条件搬运某个宿主的完整聊天会话。Hooks、MCP、权限和自动化强度仍取决于目标宿主。

• 恢复状态按正式任务保存，而不是每次 Hook 或工具事件都生成一份完整快照；
• 每个任务使用稳定检查点，写入失败时保留上一份有效状态；
• 已形成安全断点的任务可以收敛为更小的恢复记录；
• 已结束任务退出活跃恢复区，不持续制造无意义状态；
• 状态存储按字节进行容量保护，达到压力边界时不会静默删除活跃任务；
• 普通只读事件不会不断写入完整任务状态。

这些机制让跨会话恢复适合真正的长任务，而不是只适合短对话演示。

完整案例见跨会话续接。

2. 项目 Profile、上下文、记忆与可复用项目知识

Profile 可以理解为 AI 使用当前项目时的工程说明书。 它记录项目结构、技术栈、构建与测试命令、代码风格、架构边界、发布方式、功能清单和用户契约，让 AI 不必每次都从目录和 package.json 重新猜测项目规则。

devcodex init 生成的是一份有证据的 Profile 初稿和模板，不是自动完成的最终事实。初始化后应让 AI 继续读取真实源码、脚本、CI、文档、配置和发布流程，把模板补充成当前项目可依赖的工程基线；无法从项目证明的内容必须保留为 unverified，不能编造。

Profile 也不是永久正确的缓存。项目级分析和审查会把 Profile 声明与当前代码、配置和运行证据重新对账；发现漂移时，以当前可验证事实为准，并把 Profile 修订作为后续任务。

没有完整 Profile 时，DevCodex 仍可以读取当前文件并处理有限任务，但会失去可靠的项目级工程基线：status / doctor 会显示 missing 或 partial，运行模式使用更保守的 prod 默认（这里只表示保守规则模式，不代表自动部署到生产），无法确认的项目事实保持未验证，依赖构建、测试、发布或架构边界的任务可能要求补充信息、降级或停止。多项目 workspace 中，如果目标项目的 Profile 根整体缺失，会返回 PROFILE_MISSING，而不是误用另一个项目的 Profile。

DevCodex 把三类信息分开处理：

类型	解决什么问题
项目说明	项目怎样构建、测试、发布，目录、技术栈和安全边界是什么
当前上下文	这次任务真正需要读取哪些代码、文档、配置和证据
任务记忆	已确认什么、做过什么、验证过什么、还剩什么

在大型、多轮项目分析中，还可以把已经验证的稳定事实、文件关系和影响范围形成可复用的项目知识：

• 文件没有变化且证据仍然有效时，不必每轮重新分析；
• 文件变化后，只让变化文件及其依赖、消费者、配置和测试范围失效；
• 分析目标变化但代码没变时，只补充新的分析视角；
• 快照、文件身份或抽样复证不一致时，自动退回完整读取；
• 大项目可以分批交付结果，而不是长时间无输出后一次性给出总结。

这不是“缓存一段自然语言总结”，而是带来源、范围、新鲜度和失效条件的项目认知。

3. 意图变化时，流程与权限会重新判断

意图识别不是任务开始时的一次性标签。用户补充范围、改变最终目标、切换项目，或从“只分析”改为“按方案实施”时，DevCodex 会重新判断：

• 当前应继续原工作流，还是切换到开发、修复、分析、审查或续接；
• 是否需要读取新的项目上下文和记忆；
• 是否需要增加或移除专业 Skill；
• 原来的只读、修改、提交和发布权限是否仍然成立；
• 既有计划、证据和验证范围是否已经过期。

这避免 AI 因为第一轮判断已经完成，就在用户目标改变后继续沿用旧流程、旧上下文或旧权限。

4. 80+ 专业 Skill 按需加入

DevCodex 内置 80+ 专业 Skill，覆盖：

• 需求澄清、产品策略、验收与技术方案；
• 前端、交互、设计系统和可访问性；
• 后端、领域建模、API、数据与分布式系统；
• 安全、隐私、外部集成和威胁建模；
• Bug 复现、根因、回归范围、测试与审查；
• 性能、生产就绪、SRE、发布与文档同步；
• 上下文、记忆、宿主能力、Skill 生命周期和工程治理。

Skill 只在匹配当前任务和阶段时加载。看到仓库中存在某个 Skill，不等于它已经被全部送进模型。

项目还可以添加自己的 Skill，把业务规则、团队规范、架构约束、常见问题和验证方式变成 AI 可重复使用的工程能力。

5. 从需求到验证，不允许任务静默跑偏

新功能会从目标、范围、非目标和验收开始；复杂任务还会形成方案、实施顺序、验证和回滚策略。

执行过程中如果实际范围明显扩大、出现新的公共契约或高风险操作，DevCodex 会暂停并回到确认阶段，而不是把临时发现悄悄扩写成新的需求。

6. 证据化完成：不是 AI 说完成，而是有证据地完成

完成需要回答：

• 修改了什么；
• 为什么这样修改；
• 执行了哪些测试、构建或检查；
• 命令结果是什么；
• 哪些范围已经验证；
• 哪些范围没有验证；
• 还剩什么风险；
• 下一步是否需要提交、推送或发布。

没运行的验证不能写成已通过；测试成功也不能自动获得提交或发布授权。

7. 受控自我进化：让项目经验逐步变成资产

当某类问题反复出现、流程经常返工，或现有 Skill 无法覆盖时，DevCodex 可以：

重复问题 / 返工 / 新经验
        ↓
识别能力缺口和根因
        ↓
生成 Skill、规则、Prompt 或验证方案候选
        ↓
小范围试运行和效果验证
        ↓
人工审查与批准
        ↓
沉淀为工作区或项目能力

候选默认不会直接进入实际工作流，也不会自动覆盖当前规则或发布。只有目标明确、证据充分、目的地正确并获得授权后，才会晋级为可用能力；无效或有害的改进可以拒绝、回滚或退役。

这不是让 AI 随意修改自己，而是让经过验证的工程经验能够安全积累。

进化候选怎样真正变成 Skill？

重复问题或返工证据
        ↓
写入 evolution/candidates 候选区
        ↓
判断应沉淀到 workspace、单个项目还是上游包
        ↓
补齐适用场景、反例、验证和回滚证据
        ↓
人工批准晋级
        ↓
生成 SKILL.md + intent.json 到活动目录
        ↓
用自然语言正反例测试路由，失败则修订或回退

关键边界：

• 候选区不是活动 Skill 目录，候选生成后不会自动参与任务路由；
• 默认优先沉淀为 workspace Skill，只有明确依赖单一项目时才进入项目级 Skill；
• 修改 DevCodex 上游内置 Skill 需要维护者单独授权，不能由普通项目自动写回发行包；
• 只有候选、目标位置、验证证据和晋级授权全部成立，AI 才能生成最终 SKILL.md 与 intent.json；
• 生成后还要用正例、反例和真实自然语言请求验证“何时应该加载、何时不应该加载”。

devcodex init 只负责准备隔离目录，不会把每次对话自动转成 Skill：

.devcodex/workspace/evolution/candidates/   候选
.devcodex/workspace/evolution/evidence/     问题、试运行与效果证据
.devcodex/workspace/evolution/decisions/    目标、审批与晋级决定

批准后的活动目标由复用范围决定：

目标	活动目录	约束
workspace Skill	.devcodex/workspace/skills/<id>/	默认选择，同一 workspace 复用
project Skill	.devcodex/<project>/skills/<id>/	必须有项目专属证据
DevCodex 上游 Skill	content/skills/<id>/	必须有维护者明确授权，并重新走发布流程

当前公开 CLI 没有“一键把候选直接变成活动 Skill”的命令。晋级由受控 AI 工作流完成：先形成并批准目标决定，再由 workspace-skill-author 生成 SKILL.md 与 intent.json，最后执行正反例和自然语言路由验证。

可以直接这样要求：

审查当前 workspace 的进化候选，找出与支付回调重复处理相关的候选。
先判断它应该沉淀为 workspace Skill 还是项目 Skill，列出证据、适用场景、反例、验证和回滚方案。
未经我批准不要晋级；我确认后，再生成 SKILL.md 与 intent.json，并用自然语言正反例测试路由。

没有历史候选时，也可以直接创建项目自己的 Skill：

为当前 workspace 创建 payment-webhook-reliability Skill。
它用于支付回调幂等、签名校验、状态机、重复通知和补偿检查；
请同时生成适用场景、正反例和验证步骤，并用自然语言测试一次路由。

8. 六个 AI Coding 宿主复用同一套工程方式

DevCodex 当前面向：

Codex · Claude Code · GitHub Copilot · Gemini CLI · Grok · Cursor

项目上下文、任务记忆、专业 Skill、确认边界、验证和报告尽量保持一致；同时根据宿主实际支持的 Hook、MCP、插件、权限和生命周期事件选择可执行路径。

缺少某种宿主能力时，DevCodex 会降级、提示或保持未验证，而不是假装六个工具完全相同。

9. 上下文复用，但不以错误复用换速度

当任务、会话、项目、上下文版本和正文身份完全一致，并且已确认正文已经送达时，DevCodex 可以复用轻量描述，避免重复传输同一大段内容。

任一身份或内容发生变化，就恢复完整读取。这样既减少无意义重复，又不会因为错误缓存让 AI 在过期上下文上继续工作。

10. 多任务可以判断是否安全并行