33> 把可执行的 AI 开发流程装进 Copilot / Claude Code / Codex / Gemini / ** Grok**
44> ** 用户级全局 adapter** + 工作区 ` .devcodex ` 运行态 · Hook 优先 · Instruction 回退
55
6- [ ![ npm] ( https://img.shields.io/npm/v/devcodex.svg )] ( https://www.npmjs.com/package/devcodex )
76[ ![ License] ( https://img.shields.io/badge/license-AGPL--3.0-green )] ( LICENSE )
87
8+ > ** 安装真相(请先读)**
9+ > - ** 当前主路径** :从源码根 ` npm install -g . ` + ` npm run global-adapters:apply ` (未发版或要最新时用这个)。
10+ > - ** npm 公开包** ` npm install -g devcodex ` :仅当你确认 registry 上的版本与本文档/源码一致时再使用;** 不要** 假设 npm 上一定是本仓库最新提交。
11+ > - 历史包名 ` @vextjs/devcodex ` 请卸载,避免 PATH 指到旧 CLI。
12+
913---
1014
1115## DevCodex 是什么?
1216
13- DevCodex 通过 ** npm 全局安装 ** (或源码 ` npm install -g . ` ) 把五宿主的配置、Hooks、Skills 与指令投影写到各 AI 宿主的** 用户级目录** ;你的业务仓库里只需要工作区运行态 ** ` .devcodex/ ` ** 。
17+ DevCodex 把五宿主的配置、Hooks、Skills 与指令投影写到各 AI 宿主的** 用户级目录** ;业务仓库里主要保留工作区运行态 ** ` .devcodex/ ` ** 。
1418
1519它帮助 AI:
1620
1721- 按意图走 ` dev ` / ` fix ` / ` analyze ` / ` audit ` 等流程
18- - 在支持 Hooks 的宿主上拦截危险命令、补全收口检查
22+ - 在支持 Hooks 的宿主上拦截危险命令、做收口检查
1923- 把报告与会话记忆落到工作区,而不是只留在聊天窗口
2024
2125** 不是** 通用聊天机器人,也不是替代你的业务框架。
@@ -24,60 +28,61 @@ DevCodex 通过 **npm 全局安装**(或源码 `npm install -g .`)把五宿
2428
2529## 5 分钟开始
2630
27- ### 1. 安装
31+ ### 1. 环境
2832
29- ** 已发布到 npm 时:**
33+ - ** Node.js** :建议 ` >=18 ` (维护者本地文档站另需 ` ^20.19 || >=22.12 ` ,见下文)
34+ - 装完或刷新 adapter 后,请在宿主里 ** 新开一轮会话**
3035
31- ``` bash
32- npm install -g devcodex
33- ```
36+ ### 2. 安装(推荐:源码全局)
3437
35- ** 当前若以源码为准(未发版或需最新): **
38+ 在 ** 本仓库源码根 ** (含 ` package.json ` / ` skills/ ` 的目录):
3639
3740``` bash
38- git clone < 本仓库>
39- cd devcodex
4041npm install -g .
4142npm run global-adapters:apply
43+ devcodex --version
44+ devcodex doctor
4245```
4346
44- > Windows + Volta:若 PATH 上仍是旧包 ` @vextjs/devcodex ` ,请先 ` npm uninstall -g @vextjs/devcodex ` 再装。
45-
46- 验证:
47+ Windows + Volta 若仍指向旧包:
4748
4849``` bash
49- devcodex --version
50- devcodex doctor
50+ npm uninstall -g @vextjs/devcodex
51+ npm install -g .
5152```
5253
53- ### 2. 打开业务项目
54+ ** 仅当 npm 上版本可信时: **
5455
55- 在业务仓库根目录(或 monorepo 工作区根):
56+ ``` bash
57+ npm install -g devcodex
58+ ```
59+
60+ ### 3. 打开业务项目
5661
5762``` bash
58- devcodex init # 仅初始化工作区 .devcodex(不写全局宿主)
63+ cd < 你的业务仓库根>
64+ devcodex init # 只初始化工作区 .devcodex,不写全局宿主
5965```
6066
61- 然后在 ** 已配置好的宿主 ** ( Codex / Claude / Copilot / Gemini / Grok)中打开该目录开始对话 。
67+ 再在 Codex / Claude / Copilot / Gemini / Grok 中打开该目录对话 。
6268
63- ### 3 . 验证技能是否加载(可选)
69+ ### 4 . 验证技能是否加载(可选)
6470
65- 对话中发送 :
71+ 对话发送 :
6672
6773``` text
6874验证技能加载
6975```
7076
71- 期望回复中出现固定句 :
77+ 期望用户可见固定句 :
7278
7379``` text
7480SKILL-LOAD-VERIFY-OK
7581```
7682
77- 说明全局验证 skill 可读。
78- ** 不会** 强制在正文显示 ` 【DevCodex 技能】… ` 元信息行;加载过程看宿主时间线即可。
83+ ** 不会** 强制正文出现 ` 【DevCodex 技能】… ` 元行;过程看宿主时间线即可。
7984
80- CLI 等价 :
85+ CLI:
8186
8287``` bash
8388devcodex skill intent " 验证技能加载" --json
@@ -86,17 +91,20 @@ devcodex skill resolve skill-load-verify
8691
8792---
8893
89- ## 安装与刷新(重要 )
94+ ## 安装与刷新(必读 )
9095
9196| 命令 | 作用 |
9297| ------| ------|
93- | ` npm install -g devcodex ` | 全局安装;postinstall 可刷新用户级宿主 adapter |
94- | ` npm install -g . ` | 从** 源码根** 装全局(未发版时的主路径) |
95- | ` npm run global-adapters:apply ` | 用当前包根刷新五宿主用户级配置(不发版) |
96- | ` devcodex init ` / ` devcodex update ` | ** 只** 管当前工作区 ` .devcodex ` ,** 不** 写全局宿主 |
97- | ` devcodex status ` / ` doctor ` | 诊断安装与宿主就绪度 |
98+ | ` npm install -g . ` | ** 源码全局安装** (未发版/最新主路径) |
99+ | ` npm run global-adapters:apply ` | 用当前包根刷新** 用户级五宿主** (改 hooks/MCP 后必跑) |
100+ | ` npm install -g devcodex ` | 仅 registry 版本可信时使用 |
101+ | ` devcodex init ` / ` update ` | ** 只** 管当前工作区 ` .devcodex ` ,** 不** 写全局宿主 |
102+ | ` devcodex status ` / ` doctor ` | 诊断安装与宿主就绪 |
103+
104+ 规则:** 改宿主配置 → ` global-adapters apply ` ;改业务工作区 → ` init ` /` update ` 。**
105+ ` .devcodex ` 始终在项目/工作区,不会装进 npm global prefix。
98106
99- ` .devcodex ` ** 不会 ** 装到 npm global prefix;始终在你的项目/工作区里 。
107+ ` apply ` 时还可能合并写入 VS Code 用户级 ` mcp.json ` (memory/profile MCP,若路径存在) 。
100108
101109---
102110
@@ -110,7 +118,7 @@ devcodex skill plan <id...>
110118devcodex skill resolve < id...>
111119devcodex skill match " <prompt>"
112120devcodex skill intent " <prompt>" [--json]
113- devcodex grok # Grok Full 入口(有边界)
121+ devcodex grok # Grok Full 入口(有边界)
114122devcodex profile plan| init
115123```
116124
@@ -123,13 +131,15 @@ devcodex profile plan|init
123131``` text
124132<workspace>/
125133 .devcodex/
126- layout.json # workspace-namespace
127- workspace/ # 工作区级入口、 skills、DEVCODEX.md
128- <project>/ # 项目命名空间: profile / reports / .memory / requirements
134+ layout.json # workspace-namespace
135+ workspace/ # 工作区 skills、DEVCODEX.md
136+ <project>/ # profile / reports / .memory / requirements
129137```
130138
131- - ** 工作区 skill** :` .devcodex/workspace/skills/<id>/SKILL.md ` (W 优先)
132- - ** 全局 skill(hidden)** :` ~/.agents/devcodex/skills/<id>/ ` (UI 菜单可能不显示,仍可 resolve/加载)
139+ | 类型 | 路径 |
140+ | ------| ------|
141+ | 工作区 skill(W 优先) | ` .devcodex/workspace/skills/<id>/SKILL.md ` |
142+ | 全局 skill(hidden) | ` ~/.agents/devcodex/skills/<id>/ ` (菜单可能不显示,仍可加载) |
133143
134144---
135145
@@ -138,88 +148,91 @@ devcodex profile plan|init
138148| 宿主 | 大致能力 |
139149| ------| ----------|
140150| Claude Code / Codex / Copilot CLI 等 | Hook 较完整时可硬拦危险命令、Stop 收口 |
141- | ** Grok** | ** Partial** :UserPromptSubmit ** 不能** 可靠注入上下文;依赖模型读 skill + 条件 Stop |
151+ | ** Grok** | ** Partial** :UserPromptSubmit ** 不能** 可靠注入;靠读 skill + 条件 Stop |
142152| 仅 Instruction 的 surface | 语义约束,不保证硬拦 |
143153
144- 不要把 「adapter 已安装」理解成 「五宿主能力完全一致」。
154+ 「adapter 已安装」≠ 「五宿主能力完全一致」。
145155
146156---
147157
148- ## 语言策略(诚实声明 )
158+ ## 语言策略(约定,非绝对保证 )
149159
150- | 项 | 当前约定 |
151- | ----| ---------- |
152- | ** 对话回复** | 跟随用户语言 |
153- | ** 工作区过程产物文件名** | 默认 ** 中文** 标准名(如 ` 00-需求概况.md ` ) |
154- | ** 完整多语言 i18n / 中英产物双文件名** | ** 未承诺 ** 本阶段交付 |
160+ | 项 | 约定 |
161+ | ----| ------|
162+ | 对话回复 | ** 目标 ** 跟随用户语言 |
163+ | 工作区过程产物文件名 | 默认 ** 中文** 标准名(如 ` 00-需求概况.md ` ) |
164+ | 完整多语言 i18n / 中英产物双文件名 | ** 本阶段未承诺 ** |
155165
156166---
157167
158- ## 默认执行原则(用户能感知的)
168+ ## 你能感知到的默认行为
169+
170+ - ** 确认优先** :大改动、发版、危险命令前应得到确认(Auto 另有白名单边界)
171+ - ** 危险命令** :可被 Hook 拦截
172+ - ** 入口检查** :实质任务前尽量有 PC0~PC7(视宿主能力)
173+ - ** 报告与记忆** :非闲聊任务写入工作区
174+
175+ Gate/探针编号是维护者资产,日常使用不必背。
176+
177+ ---
178+
179+ ## 技能加载
180+
181+ 1 . 最终回复 ** 不强制** 技能元行
182+ 2 . 过程侧可用「正在加载 ` <id> ` 技能」
183+ 3 . ** 不要** List ` ~/.grok/skills ` 等主目录 skill 树(会暴露本机路径);只读单个已知 ` SKILL.md `
184+ 4 . 验证:对话「验证技能加载」或上文 CLI
185+
186+ ---
159187
160- - ** 确认优先** :大改动、发版、危险命令前应得到你的确认(Auto 模式另有白名单边界)
161- - ** 危险命令** :可被 Hook 拦截(如 ` rm -rf ` 根路径等)
162- - ** 入口检查** :实质任务前可见 PC0~PC7 状态块(宿主能力允许时)
163- - ** 报告与记忆** :非闲聊任务会写入工作区报告 / 会话记忆
188+ ## 架构一览
164189
165- 细节 Gate 名与探针编号是维护者资产;** 日常使用不必背** 。
190+ ``` text
191+ npm 全局包 / 源码 install -g
192+ → 用户级:宿主 hooks / instructions / skills 投影 / VS Code mcp.json(apply)
193+ → 工作区:.devcodex(profile、reports、memory、requirements、workspace skills)
194+ → 运行时:hooks/_runtime/lifecycle.cjs + MCP memory/profile
195+ ```
166196
167197---
168198
169- ## 技能加载说明
199+ ## 边界
170200
171- 1 . ** 最终回复 ** 不强制技能元行。
172- 2 . ** 过程时间线 ** 可出现「正在加载 & lt ; id & gt ; 技能」。
173- 3 . 不要 List ` ~/.grok/skills ` 等用户主目录 skill 树(会暴露本机路径);只读单个已知 ` SKILL.md ` 。
174- 4 . 验证:对话「验证技能加载」或见上文 CLI。
201+ - 默认 ** safety-only ** :危险命令硬拦;流程项多为提醒, ** strict ** 才全面升级阻断
202+ - ** 不 ** 替代业务 CI、安全审计与人工评审
203+ - Grok 等存在 ** Partial ** 上限
204+ - 敏感信息:以项目与你的要求为准;未禁止时不强制脱敏
175205
176206---
177207
178208## 文档与仓库边界
179209
180- | 内容 | 在哪里 |
181- | ------| -------- |
182- | ** 用户文档** | 本 ** README** (公开仓主入口) |
183- | ** 维护者文档站** ` website/ ` | ** 不进入公开 Git 默认跟踪 ** 、** 不进 npm 包 ** ;本机可保留完整拷贝 |
184- | 变更未发布说明 | ` changelogs/unreleased.md ` |
210+ | 内容 | 位置 |
211+ | ------| ------|
212+ | ** 用户文档** | 本 README(公开仓主入口) |
213+ | ** 维护者文档站** ` website/ ` | ** 默认不进公开 Git 跟踪 ** 、** 不进 npm** ;本机可保留完整拷贝(见 ` website/README.md ` ) |
214+ | 未发布变更 | ` changelogs/unreleased.md ` |
185215| 已发布说明 | ` changelogs/releases/ ` |
186216
187- npm 包 ` files ` 字段** 不包含** ` website/ ` 。
188-
189217---
190218
191219## 本地开发(贡献者)
192220
193221``` bash
194- git clone < repo>
195- cd devcodex
222+ cd < devcodex-source-root>
196223npm install
197224npm run test:stop-gate
198225npm run test:docs-surface-inventory
199- npm run global-adapters:apply # 刷新本机五宿主
226+ npm run global-adapters:apply
200227```
201228
202- 维护者若需文档站:在已有完整 ` website/ ` 的本机目录执行 ` cd website && npm install && npm run dev ` (Rspress;Node ` ^20.19 || >=22.12 ` )。
203-
204- ---
229+ 维护者文档站(需本机已有完整 ` website/ ` ):
205230
206- ## 架构一览
207-
208- ``` text
209- npm 全局包 / 源码 install -g
210- → 用户级:各宿主 hooks / instructions / skills 投影 / VS Code mcp.json(apply 时)
211- → 工作区:.devcodex(profile、reports、memory、requirements、workspace skills)
212- → 运行时:hooks/_runtime/lifecycle.cjs + MCP memory/profile
231+ ``` bash
232+ cd website && npm install && npm run dev
213233```
214234
215- ---
216-
217- ## 边界声明
218-
219- - 默认 ** safety-only** :危险命令硬拦;流程类多为提醒,** strict** 才全面升级阻断。
220- - ** 不** 替代业务项目的 CI、安全审计与人工评审。
221- - Grok 等宿主存在 ** Partial** 能力上限,见上文矩阵。
222- - 敏感信息策略以项目与用户要求为准;未禁止时不强制脱敏。
235+ Node:` ^20.19 || >=22.12 ` (仅文档站)。
223236
224237---
225238
@@ -232,13 +245,11 @@ npm 全局包 / 源码 install -g
232245## 用户可见交付与链接兼容
233246
234247用户可见交付物应带可定位路径(工作区相对路径优先);宿主证据不足时用 portable 链接,不假装全宿主可点。
235- MCP 侧常见入口含 ` profile_load ` ;工作流技能按意图 ** invoke** (按需读取,非整库预载)。
236-
237- 用户侧文档 review 聚合见 skill ` audit-user-manual ` (文档站/README/quick start 路径审查)。
238- 规范侧防 prompt 长 Gate 清单回流:` PromptLongGateListDriftProbe ` (V75)。
248+ MCP 侧常见入口含 ` profile_load ` ;工作流技能按意图 ** invoke** (按需读取,非整库预载)。
249+ 用户侧文档 review 聚合见 skill ` audit-user-manual ` 。
250+ 规范侧:` PromptLongGateListDriftProbe ` (V75)。
239251
240- ## 维护者备注(非用户路径)
252+ ## 维护者备注
241253
242- - 公开仓策略:** website 内容默认不跟踪** (仅 ` website/README.md ` 指针)。
243- - 过程关账 ECR 示例:工作区 ` .devcodex/devcodex/reports/requirements/… ` (运行态,默认不进本包)。
244- - 未发布变更见 ` changelogs/unreleased.md ` 。
254+ - 公开仓:` website/* ` 忽略,仅跟踪 ` website/README.md ` 指针。
255+ - 过程 ECR 等常在工作区 ` .devcodex/ ` (运行态,默认不进本 npm 包)。
0 commit comments