Skip to content

Commit 604d3bd

Browse files
committed
docs: polish README install truth and structure
Clarify source-first install vs npm, require new session after apply, move maintainer anchors, and keep user-facing skill verify / host Partial notes.
1 parent cf7d142 commit 604d3bd

1 file changed

Lines changed: 105 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,23 @@
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
4041
npm install -g .
4142
npm 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
7480
SKILL-LOAD-VERIFY-OK
7581
```
7682

77-
说明全局验证 skill 可读。
78-
**不会**强制在正文显示 `【DevCodex 技能】…` 元信息行;加载过程看宿主时间线即可。
83+
**不会**强制正文出现 `【DevCodex 技能】…` 元行;过程看宿主时间线即可。
7984

80-
CLI 等价:
85+
CLI:
8186

8287
```bash
8388
devcodex 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...>
110118
devcodex skill resolve <id...>
111119
devcodex skill match "<prompt>"
112120
devcodex skill intent "<prompt>" [--json]
113-
devcodex grok # Grok Full 入口(有边界)
121+
devcodex grok # Grok Full 入口(有边界)
114122
devcodex 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>
196223
npm install
197224
npm run test:stop-gate
198225
npm 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

Comments
 (0)