22
33> AI 开发规范注入器 — 默认五宿主:Copilot / Claude Code / Codex / Gemini / Grok(Hook-First / Instruction-Fallback)
44
5- [ ![ npm] ( https://img.shields.io/badge/ npm-%40vextjs%2Fdevcodex-blue )] ( https://github. com/vextjs /devcodex )
5+ [ ![ npm] ( https://img.shields.io/npm/v/@devcodex/devcodex.svg )] ( https://www.npmjs. com/package/@devcodex /devcodex )
66[ ![ License] ( https://img.shields.io/badge/license-AGPL--3.0-green )] ( LICENSE )
77
88## DevCodex 是什么?
@@ -114,31 +114,29 @@ DevCodex 通过 npm 全局安装把 Copilot、Claude Code、Codex、Gemini CLI
114114
115115| 通道 | 当前状态 | 用途 |
116116| ---| ---| ---|
117- | GitHub Packages | ✅ v1.15.3 | 当前唯一发布通道;安装需要 GitHub Packages ` read:packages ` 认证 |
117+ | npmjs | 待发布 v1.15.3 | 新 canonical 发布通道;发布后可直接安装 |
118+ | GitHub Packages | 历史包 ` @devcodex-labs/devcodex@1.15.3 ` | 组织改名后转移的历史兼容包;不作为新安装主路径 |
118119
1191201 . 确认 CLI 运行时(文档站维护另需 Node ` ^20.19.0 || >=22.12.0 ` ):
120121
121122``` bash
122123node --version # CLI 需要 Node.js >=18
123124```
124125
125- 2 . 配置 GitHub Packages registry 与认证 :
126+ 2 . 安装 CLI :
126127
127- ``` ini
128- @vextjs:registry =https://npm.pkg.github.com
129- //npm.pkg.github.com/:_authToken =${NODE_AUTH_TOKEN}
128+ ``` bash
129+ npm install -g @devcodex/devcodex
130130```
131131
132- 当前 shell 的 ` NODE_AUTH_TOKEN ` 需使用具备 ` read:packages ` 的 GitHub PAT。
133-
134- 3 . 本地验证当前 global-only 候选:
132+ 3 . 本地验证当前候选:
135133
136134``` bash
137135npm pack
138- npm install -g ./vextjs -devcodex-1.15.3.tgz
136+ npm install -g ./devcodex -devcodex-1.15.3.tgz
139137```
140138
141- 发布后的正式入口为 ` npm install -g devcodex ` ;本阶段只验证本地 tarball 和 CLI 行为,不验证 npm 包名 owner、 registry、 dist-tag 或版本唯一性。
139+ 发布后的正式入口为 ` npm install -g @ devcodex/devcodex ` ;本阶段只验证本地 tarball 和 CLI 行为,不验证 registry dist-tag 或版本唯一性。
142140
1431414 . 在目标工作区初始化 ` .devcodex ` 并验证:
144142
@@ -153,38 +151,21 @@ devcodex status
153151
154152## 安装
155153
156- 以下是当前 v1.15.3 的完整安装说明。当前版本仅发布到 GitHub Packages,安装需要读取认证。
157-
158- ### 1. 配置 GitHub Packages
159-
160- ``` bash
161- # 创建 .npmrc(推荐使用环境变量注入 GitHub PAT,避免把 token 写入仓库或本地文件)
162- echo " @vextjs:registry=https://npm.pkg.github.com" >> .npmrc
163- echo " //npm.pkg.github.com/:_authToken=\$ {NODE_AUTH_TOKEN}" >> .npmrc
164- ```
165-
166- ``` bash
167- # 当前 shell 注入 PAT(需具备 read:packages;发布时还需 write:packages)
168- export NODE_AUTH_TOKEN=YOUR_GITHUB_PAT
169- ```
170-
171- 这里的环境变量仅用于 GitHub Packages 认证流程,不代表项目里的普通配置默认都应 env 化;未明确要求 env 时,AI 不得主动把明文或硬编码改成 env、` secretRef ` 、secret manager 或 ` config.local.json ` 。
172-
173- > v1.15.3 未发布到 npmjs;缺少上述 registry 或读取认证时,安装不会自动回退到其他通道。
154+ 以下是当前 v1.15.3 的完整安装说明。新 canonical 包名为 ` @devcodex/devcodex ` ,发布目标为 npmjs。
174155
175- ### 2 . 安装并初始化
156+ ### 1 . 安装并初始化
176157
177158``` bash
178159npm pack
179- npm install -g ./vextjs -devcodex-1.15.3.tgz # 本地候选:安装 CLI 并自动配置五宿主用户级 adapter
160+ npm install -g ./devcodex -devcodex-1.15.3.tgz # 本地候选:安装 CLI 并自动配置五宿主用户级 adapter
180161devcodex init # 只初始化当前 workspace 的 .devcodex
181162devcodex status
182163```
183164
184165发布后的命令语义:
185166
186167``` bash
187- npm install -g devcodex # 安装全局 CLI,并由 postinstall 配置五宿主用户级 adapter
168+ npm install -g @devcodex/ devcodex # 安装全局 CLI,并由 postinstall 配置五宿主用户级 adapter
188169npm update -g devcodex # 升级全局包,并由 postinstall 刷新五宿主用户级 adapter
189170npm install devcodex # 仅加入当前项目依赖;不配置宿主,并提示必须使用 -g
190171```
@@ -327,8 +308,8 @@ Phase 1 采用“薄 Rule + `host-capability-routing` Skill + 三份 V1 契约/
327308| ------| ------|
328309| ` devcodex global-adapters apply ` | ** 源码维护者日常(R1a)** :从当前包根刷新用户级五宿主 adapter;支持 ` --dry-run ` / ` --json ` ;不 pack、不 publish |
329310| ` npm install -g . ` | ** 本地旁路(R1b)** :全局安装当前目录并走 postinstall 刷新 adapter |
330- | ` npm pack ` + ` npm install -g ./vextjs -devcodex-*.tgz ` | ** 预发冒烟(R2)** :接近真实 tarball 安装面 |
331- | ` npm install -g devcodex ` | ** 已发布(R3)** :安装全局 CLI;` postinstall ` 自动刷新全局宿主 adapter |
311+ | ` npm pack ` + ` npm install -g ./devcodex -devcodex-*.tgz ` | ** 预发冒烟(R2)** :接近真实 tarball 安装面 |
312+ | ` npm install -g @devcodex/ devcodex ` | ** 已发布(R3)** :安装全局 CLI;` postinstall ` 自动刷新全局宿主 adapter |
332313| ` npm update -g devcodex ` | ** 已发布(R3)** :升级全局包并 ` postinstall ` 刷新 adapter |
333314| ` npm install devcodex ` | 仅安装到当前项目依赖;` postinstall ` 不写宿主配置并提示必须使用 ` -g ` |
334315| ` devcodex update ` | ** workspace only(R4)** :只刷新当前 ` .devcodex ` 运行态,不写用户级宿主配置 |
@@ -500,7 +481,7 @@ AO-3 默认轻注入必须在 Shadow green 后单独确认,并继续受 `full-
500481
501482``` bash
502483# 克隆仓库
503- git clone https://github.com/vextjs /devcodex.git
484+ git clone https://github.com/devcodex-labs /devcodex.git
504485cd devcodex
505486```
506487
@@ -601,7 +582,7 @@ README / 用户使用文档当前补充四类专项 Skill:`user-manual-authori
601582| ** OpenAI Codex app/CLI** | 用户级 ` .codex/AGENTS.md ` 、hooks、config 与 ` .agents/skills/ ` | ⚠️ isolated direct probe;阻断输出按事件契约分级 | ⚠️ Hook + 文本确认 | ✅ 用户级 MCP managed block | 🟢 Direct probe |
602583| ** ChatGPT 普通对话** | 不读取本地工作区 ` AGENTS.md ` / ` .agents/ ` / ` .codex/ ` ;可手工粘贴规则 | ❌ | ⚠️ 文本 | ❌ | 🔴 Unsupported |
603584
604- > ** 安装命令** :` npm install -g devcodex ` 安装 CLI 并配置五宿主用户级 adapter;` npm update -g devcodex ` 升级并刷新。当前候选用本地 tarball验证 ,不代表 npm registry 已发布。
585+ > ** 安装命令** :` npm install -g @ devcodex/devcodex ` 安装 CLI 并配置五宿主用户级 adapter;` npm update -g @ devcodex/devcodex ` 升级并刷新。当前候选用本地 tarball 验证 ,不代表 npm registry 已发布。
605586>
606587> ** Grok 全局插件** :plugin source、配置和稳定 runtime 均位于用户级 Grok 根;` devcodex grok ` 从当前 cwd 发现 workspace ` .devcodex ` ,不依赖工作区 ` .grok ` 或 ` AGENTS.md ` 。` doctor/status ` 读取全局 receipt;工作区旧插件只报告为 legacy。
607588>
@@ -672,7 +653,7 @@ DevCodex Hook runtime 不再把所有拦截都等同为“停止”。拦截会
672653 - 维护 DevCodex 源仓或 workspace-namespace 时,运行 ` node scripts/validate-all-profiles.js --workspace <workspace-root> ` 校验所有 Profile;发布前需要严格处理 warning 时追加 ` --strict-warnings `
6736543 . ** Codex / Copilot 想用 MCP**
674655 - 先确认宿主本身是否支持本地 MCP
675- - ** Codex** :重新执行 ` npm install -g devcodex ` (首次/修复)或 ` npm update -g devcodex ` (升级),再重启 Codex。用户其它 ` mcp_servers ` 会保留
656+ - ** Codex** :重新执行 ` npm install -g @ devcodex/devcodex ` (首次/修复)或 ` npm update -g @devcodex/ devcodex ` (升级),再重启 Codex。用户其它 ` mcp_servers ` 会保留
676657 - ** Copilot CLI** :同一全局安装/升级会维护 ` ~/.copilot/mcp-config.json ` 的 DevCodex managed servers,并保留用户其它 servers;重启 Copilot CLI 后用 ` devcodex doctor ` 核对原生 CLI 状态
677658 - ** Copilot IDE** :不继承 Copilot CLI 的用户级 Hooks/MCP 就绪结论,仍按目标 IDE 自身能力验证
678659 - Claude 使用用户级 MCP 配置,不要求工作区 ` .mcp.json `
@@ -698,7 +679,7 @@ DevCodex Hook runtime 不再把所有拦截都等同为“停止”。拦截会
698679 - ` CheckpointValidationResultV1 ` 分开记录 response-time 与 post-execution;PostToolUse/PreCompact 或缺失证据不能让 post-execution 通过,只有实际 Stop terminal evidence 才能完成
699680 - ` devcodex trace show|replay --state <lifecycle-state.json> --json ` 可检查当前 turn 的 sequence/duplicate/terminal;replay 只读且不会执行 payload
700681 - 工具或 Agent 仍持有有效长租约时不会按 120/300 秒误判;任何恢复都不得自动重放未知副作用的写操作
701- - gray sidecar 可执行 ` npm run check:turn-liveness -- --state <lifecycle-state.json> --json ` ;安装包消费者可直接运行 ` node node_modules/@vextjs /devcodex/scripts/check-turn-liveness.js --state <lifecycle-state.json> --json `
682+ - gray sidecar 可执行 ` npm run check:turn-liveness -- --state <lifecycle-state.json> --json ` ;安装包消费者可直接运行 ` node node_modules/@devcodex /devcodex/scripts/check-turn-liveness.js --state <lifecycle-state.json> --json `
702683 - sidecar 只做一次读取和分类,不 watch、不写状态、不唤醒宿主、不重放操作、不控制进程;输出 ` sidecar-observed ` 不能冒充 ` host-native-verified `
703684
704685## IDE 兼容性
0 commit comments