![\"npm](\"https://img.shields.io/npm/v/devcodex\")
\n ![\"AGPL-3.0\"](\"https://img.shields.io/badge/license-AGPL--3.0-green\"){kind=icon}
\n ![\"Node.js](\"https://img.shields.io/badge/Node.js-%3E%3D18.17.0-brightgreen\"){kind=icon}
=18.17.0\" />\n ![\"6](\"https://img.shields.io/badge/AI_Coding_Hosts-6-blue\"){kind=icon}
\n ![\"80+](\"https://img.shields.io/badge/Professional_Skills-80%2B-blueviolet\"){kind=icon}
\n\n 意图驱动的跨宿主 AI Coding 工程化 Harness\n
\n\n\n 让 AI Coding 不只是生成代码，而是从需求开始，持续把工程任务做完。\n
\n\n\n 识别意图 · 读取项目 · 调用专业 Skill · 确认边界 · 自动推进 · 执行修改 · 验证结果 · 保存进度 · 跨会话续接 · 受控进化\n
\n\n\n
\n 完整文档\n ·\n 5 分钟开始\n ·\n 跨会话续接案例\n ·\n 反馈问题\n
\n\n\n 快速开始\n ·\n 常见任务\n ·\n 排错\n ·\n 更新\n ·\n 卸载\n
\n\n> **模型和宿主负责推理、写代码与执行工具；DevCodex 以任务意图为起点，负责判断要完成什么、作用于哪个项目、该读取什么、加载哪些专业能力、按什么工程流程推进，以及怎样证明真正完成。**\n\n**意图驱动 · 6 个 AI Coding 宿主 · 8 条任务工作流 · 80+ 专业 Skill · 项目上下文与记忆 · Sticky Auto 自动推进 · 长任务恢复 · 跨会话续接 · 证据化完成 · 受控自我进化**\n\n```bash\nnpm install -g devcodex\ncd <你的项目根目录>\ndevcodex init\ndevcodex status\n```\n\n安装或更新后保留原任务。宿主提供连接重载时，刷新 DevCodex 连接并核对当前加载版本；没有该能力时，保存检查点、继续可执行工作，方便时重载宿主。安装成功不代表已有连接已经加载新版，无需为更新另建任务。\n\n第一个任务可以直接这样说：\n\n```text\n分析当前项目最值得优先解决的三个问题。\n先说明读取范围和证据，只分析，不修改文件。\n```\n\n## 目录\n\n- [为什么需要 DevCodex？](#为什么需要-devcodex)\n- [安装后，你能解决什么？](#安装后你能解决什么)\n- [什么时候直接使用宿主，什么时候用 DevCodex？](#什么时候直接使用宿主什么时候用-devcodex)\n- [5 分钟开始](#5-分钟开始)\n- [安装会改变什么](#安装会改变什么)\n- [工作流、Skill 与宿主边界](#工作流skill-与宿主边界)\n- [常见任务怎么说](#常见任务怎么说)\n- [常见问题与排错](#常见问题与排错)\n- [更新](#更新)\n- [卸载](#卸载)\n- [边界](#边界)\n- [文档](#文档)\n- [贡献](#贡献)\n- [社区](#社区)\n- [许可证](#许可证)\n\n---\n\n## 为什么需要 DevCodex？\n\n模型越来越会写代码，但真实工程任务仍然经常失败在代码生成之外：\n\n- 新会话不了解项目，每次都要重新解释背景；\n- 需求还没有说清楚，AI 就开始修改文件；\n- 长任务跨文件、跨阶段后容易偏离目标；\n- 会话中断后，只能依靠旧聊天摘要猜测做到哪里；\n- 通用模型缺少当前问题需要的专业工程方法；\n- 简单任务和高风险任务被用同一种方式处理；\n- 一句“已经完成”没有测试、证据和剩余风险；\n- 同样的问题反复出现，却没有沉淀成下一次可复用的能力；\n- 切换 Codex、Claude Code 或 Cursor 后，项目工作方式又要重新维护一套。\n\nDevCodex 补上的，就是 AI Coding 与真实软件工程之间缺少的这一层。\n\n| 只依赖当前 AI Coding 会话 | 加上 DevCodex |\n|---|---|\n| 背景主要留在聊天窗口 | 项目上下文、任务状态、报告和记忆跟随项目保存 |\n| 容易拿到需求就直接编码 | 先判断目标、项目、范围、风险和是否允许修改 |\n| 主要依赖模型的通用能力 | 根据任务和阶段加载对应的专业 Skill |\n| 长任务中断后从头分析 | 从任务身份、检查点、确认状态和剩余项继续 |\n| 大项目每轮重复读取 | 可按变化范围和影响关系做增量分析与复证 |\n| “代码写完”等于“任务完成” | 测试、构建、报告、证据和剩余风险共同收口 |\n| 项目经验散落在对话里 | 重复问题可形成受控进化候选和项目 Skill |\n| 每个工具单独维护规则 | 六个宿主复用同一套项目工程方法 |\n\n### 意图驱动：你只需要说目标，DevCodex 决定怎样工作\n\nDevCodex 不要求用户先学习工作流名称，也不会看到某个关键词就机械套用固定 Prompt。它会先把你真正想得到的结果结构化，再让这份结构化意图驱动后面的项目识别、上下文、Skill、流程、Auto/确认、执行和验证。下游组件不能各自重新解释原始文本。\n\n它会同时判断：\n\n- 最终需要的是结论、代码修改、问题修复、系统审查，还是继续历史任务；\n- 请求作用于哪个项目，允许处理哪些目录、模块和业务范围；\n- 当前任务的风险有多高，是否允许修改文件；\n- 需要读取哪些 Profile、相关源码、历史记忆和验证证据；\n- 当前阶段应该加载哪些专业 Skill；\n- 哪些节点需要用户确认，哪些可以由 Auto 持续推进；\n- 应该运行哪些验证，以及什么条件下才能宣布完成。\n\n| 你的请求 | DevCodex 识别后的工程路径 |\n|---|---|\n| “分析测试为什么失败，不要修改” | 进入只读分析，说明读取范围、证据与未验证部分 |\n| “复现并修复这个失败用例” | 进入修复流程，先复现、定位根因，再修改和回归 |\n| “为支付回调增加幂等” | 进入开发流程，先明确需求、方案、范围与验收 |\n| “审查当前支付链路的风险” | 进入证据审查，不默认修改文件 |\n| “继续支付回调幂等任务” | 定位原任务，复核当前状态后从准确断点续接 |\n| “这个设计是否合理？” | 先判断只需要分析建议，还是最终需要落地修改 |\n\n意图不是一次性的分类标签，而是整条工程链的控制起点：\n\n```text\n用户目标\n→ 任务类型\n→ 目标项目、范围与风险\n→ 上下文与记忆\n→ 专业 Skill\n→ 工作流与确认方式\n→ 验证和完成标准\n```\n\n当用户目标发生变化，例如从“只分析”变成“按方案实施”、从单项目扩大到整个 workspace，或临时增加提交与发布要求，DevCodex 会重新结构化意图，再统一刷新工作流、上下文、权限和验证边界。范围变化或短时凭据过期本身不会直接变成一次用户确认。\n\n> Auto 只负责在已经识别的意图和已授权范围内持续推进，不会绕过意图判断，也不会把只读分析自动变成代码修改。\n\n### 从需求到交付的完整闭环\n\n```mermaid\nflowchart LR\n A[说出目标] --> B[识别任务意图]\n B --> C[判断项目、范围与风险]\n C --> D[读取上下文与记忆]\n D --> E[加载当前专业 Skill]\n E --> F[明确需求、方案与验收]\n F --> G{确认或 Auto 推进}\n G --> H[执行修改]\n H --> I[测试、构建与检查]\n I --> J[报告证据与剩余风险]\n J --> K[保存任务状态与续接点]\n K --> L{是否发现可复用经验}\n L -- 否 --> M[任务完成]\n L -- 是 --> N[生成受控进化候选]\n N --> M\n```\n\nDevCodex 不是在开始前多塞一段 Prompt，而是持续管理任务从理解、执行到验证和交接的全过程。\n\n### 同一个模型，为什么会表现得更聪明？\n\nDevCodex 不改变模型参数。它通过四件事提升 AI 在真实项目中的有效表现：\n\n1. **给出正确目标**：先判断最终要结论、修复、功能、审查还是续接；\n2. **提供正确资料**：只读取当前任务需要的项目规范、源码、记忆和证据；\n3. **调用正确能力**：在当前阶段加载对应的专业 Skill，而不是一次性塞入全部规则；\n4. **获得真实反馈**：测试、构建、命令结果、代码差异和审查证据会继续影响后续判断。\n\n简单任务可以走更短路径；涉及公共契约、数据、安全、多模块或发布风险时，会自动提高复审和验证强度。是否需要确认只由当前结构化意图与动作授权决定，风险标签、复审器和验证器不能自行要求确认。流程仪式、技术方案深度与验证范围分别判断，不再用一个模糊的“简单/复杂”标签同时控制三者：当前任务中用户明确说法优先，其次才是项目配置、基于项目事实的智能识别和保守回退。入口先初判，读取项目后再二次判断，并在 PC8～PC10 写清流程/方案、验证范围与预计耗时、后续阶段和当前是否需要用户动作。\n\nProfile 可配置 `extensions.devcodex.workflowRouting.mode` 为 `adaptive`（默认）、`simple` 或 `standard`，并用 `showPlan` 控制展示密度；该配置只提供流程仪式默认值，不能降低公共契约、状态恢复、package 或发布等强制义务。入口 PC0 同时显示已安装包、当前 runtime 与源码候选的版本关系，避免“版本号相同”被误报为运行内容完全一致。\n\n产物打开按实际呈现面而不是仅按宿主名称决定。Codex Desktop 输出真实的本地文件链接；VS Code、Zed、JetBrains 可输出对应打开命令；未知或未验证界面直接给可复制绝对路径。系统只有在打开动作执行且回读成功时才会写“已打开”，renderer 选中、命令生成或链接渲染本身不冒充打开成功。\n\n### Auto 自动推进：一次授权，持续完成整条工程链\n\n普通模式下，DevCodex 会在需求、方案和实施计划等关键节点等待确认。需要让 AI 在已授权范围内持续推进时，可以显式进入 Auto：\n\n```text\n@devcodex-auto 完成支付回调幂等修复。\n先复现和确认根因，再完成方案、修改、相关回归、报告与任务收口；\n不要扩大到删除、push 或发布。\n```\n\nAuto 不会跳过工程流程，而是**自动通过适用的流程确认，并继续执行后面的分析、实施、验证、报告和状态保存**：\n\n- 有效入口先结构化为 `executionDecision=enable-auto`；正式任务建立后由任务级 Auto 持续承接，不依赖短时 receipt 或会话 TTL，不需要每个阶段反复回复“继续”；\n- 需求、方案、实施计划、测试、证据和报告仍然会生成，不会因为自动推进而消失；\n- 可恢复失败最多自动重试 2 次；实际修改范围扩大、证据过期或验证失败时会停止当前动作、重新结构化意图并在原授权仍适用时继续，不会机械切回确认；\n- 删除、项目外写入、危险操作、push、Tag、Release 和发布不会因为进入 Auto 自动获得授权；\n- 不同宿主对 Hook、权限和自动放行的支持不同；能力不足时停止对应动作并明确提示，不会覆盖结构化 Auto 决定。\n\n正式入口是 `@devcodex-auto`，默认快捷别名是 `@rocky`。可用 `退出 auto`、`关闭自动模式` 或 `切回确认模式` 退出；正式任务在恢复时按任务 identity 和结构化意图续接，不能仅因新会话或短时凭据过期撤销任务级授权。\n\n> Auto 的价值不是“跳过步骤”，而是让已经明确目标和边界的任务不再被机械确认打断，同时继续保留验证、证据和安全底线。\n\n