Skip to content

Commit 8508045

Browse files
rockyshi1993Copilot
rockyshi1993
and
Copilot
committed
feat: v0.0.2 — dev/prod mode, compliance overhaul, memory 4-col format, project profile
- Add dev/prod mode switch via .devcodex/profile/config.json - compliance/SKILL.md: PC1~PC3 pre-check independent of FC/SC in dev mode; add §0 mode guard - 17-compliance.instructions.md: clarify pre-check runs before intent in dev mode - 12-audit.instructions.md: 🔴 issues with all 3 validations passed → directly trigger self-fix - agents/devcodex.agent.md: sync audit self-fix trigger rule; add violation-query routing - memory/SKILL.md: upgrade dialog log from 3-col to 4-col format (add 👤 user message column) - FC1 constraint updated: 📨 field must be 4-col table - .devcodex/profile/: add project profile (01-项目信息 / 02-架构约束 / 03-代码风格 / config.json) - .devcodex/reports/: add analysis and requirements reports - tools/sync-dev.ps1: one-click sync script to MySelf workspace - .gitignore: exclude .github/ (local install target) and .devcodex/.memory/ - index.js: fix UTF-8 BOM issue - plugin.json: bump version to 0.0.2 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 9611468 commit 8508045

32 files changed

Lines changed: 801 additions & 65 deletions

‎.devcodex/profile/01-项目信息.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# 01 — 项目信息
2+
3+
## 基本信息
4+
5+
| 项目 | DevCodex |
6+
|------|----------|
7+
| **npm 包名** | `@vextjs/devcodex` |
8+
| **当前版本** | 0.0.2 |
9+
| **许可证** | AGPL-3.0-or-later |
10+
| **仓库地址** | https://github.com/vextjs/devcodex |
11+
| **官网** | https://devcodex.dev |
12+
| **Issues** | https://github.com/vextjs/devcodex/issues |
13+
14+
## 技术栈
15+
16+
| 分类 | 技术 | 说明 |
17+
|------|------|------|
18+
| **运行时** | Node.js ≥ 18 | CLI 运行环境 |
19+
| **语言** | JavaScript（CJS） | 无 TypeScript，无编译步骤 |
20+
| **包管理** | npm | 使用 `npm link` 本地开发 |
21+
| **Node 版本管理** | Volta | 项目已锁定版本 |
22+
| **CLI 框架** | 原生（无框架） | `process.argv` 手动解析 |
23+
| **文件操作** | `fs`、`path`（内置模块） | 无第三方依赖 |
24+
| **Dev 依赖** | `canvas ^3.2.3` | 资产图片生成用 |
25+
26+
## 产品定位
27+
28+
DevCodex 是"AI 开发规范注入器"：
29+
30+
1. **核心产物**：`.github/agents/`、`.github/skills/`、`.github/instructions/` 等 Markdown 规范文件
31+
2. **安装器**：`index.js` CLI，将规范文件复制到目标项目
32+
3. **目标用户**：使用 GitHub Copilot Agent 的开发团队
33+
34+
## 版本策略
35+
36+
| 类型 | 规则 |
37+
|------|------|
38+
| **MAJOR**（x.0.0） | 工作流或架构破坏性变更 |
39+
| **MINOR**（0.x.0） | 新增工作流、新增 Skill、新增指令集 |
40+
| **PATCH**（0.0.x） | Bug 修复、文字修正、工具改进 |
41+
42+
- `CHANGELOG.md` 记录所有版本变更
43+
- `changelogs/vX.Y.Z.md` 存放详细变更日志
44+
- `plugin.json` 中的 `version` 字段必须与 `package.json` 保持同步
45+
46+
## 当前开发模式
47+
48+
> **状态：本地开发模式**（npm link 激活）
49+
50+
```
51+
e:\MySelf\devcodex\ ← 源码目录（修改在这里）
52+
↓ devcodex update（同步命令）
53+
e:\MySelf\.github\ ← 已安装到 MySelf 工作区
54+
```
55+
56+
### 开发工作流
57+
58+
```bash
59+
# 第一次初始化（已完成，无需重复）
60+
cd e:\MySelf\devcodex
61+
npm link # 将 devcodex 命令链接到全局
62+
63+
# 日常开发循环
64+
# 1. 在 e:\MySelf\devcodex\ 修改规范文件（agents/skills/instructions 等）
65+
# 2. 同步到 MySelf 工作区（必须执行）
66+
cd e:\MySelf
67+
devcodex update # 同步到 E:\MySelf\.github\（Agent 读取来源）
68+
69+
# 3. 同步到 MySelf 的 .devcodex\（实时验证效果用）
70+
# 将 devcodex 项目的 profile/config 同步到 MySelf 工作区的 .devcodex\
71+
xcopy /E /Y e:\MySelf\devcodex\.devcodex\profile\ e:\MySelf\.devcodex\profile\
72+
73+
# 4. 新建 Chat 会话（Ctrl+N）验证最新规范是否生效
74+
# 无需重启 VS Code，新会话会重新加载 .github\ 下的所有文件
75+
76+
# 验证安装状态
77+
devcodex status
78+
```
79+
80+
### 关键路径对应关系
81+
82+
| 源码位置 | 安装后位置 | 说明 |
83+
|---------|-----------|------|
84+
| `devcodex/agents/` | `.github/agents/` | Agent 定义文件 |
85+
| `devcodex/skills/` | `.github/skills/` | Skill 文件 |
86+
| `devcodex/instructions/` | `.github/instructions/` | 全局指令 |
87+
| `devcodex/prompts/` | `.github/prompts/` | Prompt 模板 |
88+
| `devcodex/hooks/` | `.github/hooks/` | Agent Hooks |
89+
90+
> ⚠️ **每次修改规范文件后都必须执行 `devcodex update`**，否则 VS Code 中的 DevCodex Agent 读取的仍是旧版本。修改后重新开启一个 Chat 会话让 VS Code 重新加载文件。
91+
92+
## 发布流程
93+
94+
```bash
95+
# 1. 更新版本
96+
npm version patch|minor|major
97+
98+
# 2. 更新 plugin.json version 字段（手动同步）
99+
100+
# 3. 运行审计工具
101+
node tools/v5-full-audit.js
102+
103+
# 4. 发布
104+
npm publish --access restricted
105+
```
106+
107+
## 授权层级
108+
109+
| 层级 | 说明 |
110+
|------|------|
111+
| **Free** | dev（非高级子类型）、fix-default、analyze、audit（非 audit-project）、chat |
112+
| **Pro** | database / optimization / scenario-test / incident / fix-security / audit-project / self-fix / resume / plan |

‎.devcodex/profile/02-架构约束.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# 02 — 架构约束
2+
3+
## 顶层目录结构
4+
5+
```
6+
devcodex/
7+
├── agents/ # Agent 定义文件（.agent.md）
8+
│ └── devcodex.agent.md # 唯一 Agent，含全工作流路由
9+
├── skills/ # Skill 文件（按领域分组）
10+
│ ├── core/ # 核心技术技能（compliance/memory/report/...）
11+
│ ├── routing/ # 路由技能（intent/load-profile/...）
12+
│ ├── dev/ # 开发工作流技能
13+
│ ├── fix/ # 修复工作流技能
14+
│ ├── audit/ # 审计工作流技能
15+
│ ├── analyze/ # 分析工作流技能
16+
│ ├── self-fix/ # 规范自修复技能
17+
│ ├── cross/ # 跨工作流共用技能（api-verification/document-sync/...）
18+
│ └── token/ # Token 权限验证技能
19+
├── instructions/ # 全局 Instructions（按优先级编号）
20+
│ └── 00- ~ 17-*.instructions.md
21+
├── prompts/ # Prompt 模板文件（.prompt.md）
22+
├── hooks/ # Agent Hooks（devcodex-hooks.json）
23+
├── auth/ # 授权相关
24+
├── commercial/ # 商业化相关
25+
├── data/ # 运行时数据（violations/pending-fixes/gap-registry）
26+
├── tools/ # 内部工具（审计/迁移脚本，不发布到 npm）
27+
├── assets/ # 品牌资产（icon/banner/screenshot）
28+
├── .devcodex/ # 本项目自身的 DevCodex 产物
29+
│ ├── profile/ # 项目规范（本目录）
30+
│ └── .memory/ # AI 记忆（.gitignore 排除）
31+
├── index.js # CLI 入口（init/update/status）
32+
├── package.json
33+
├── plugin.json # DevCodex 插件元数据
34+
└── RULES.md # 顶层规则说明
35+
```
36+
37+
## 模块职责边界
38+
39+
| 模块 | 职责 | 禁止 |
40+
|------|------|------|
41+
| `agents/` | 路由入口，调用 Skill | 直接实现业务逻辑 |
42+
| `skills/` | 具体执行能力 | 调用其他 Skill（除非明确声明）|
43+
| `instructions/` | 全局约束注入 | 工作流特定的逻辑 |
44+
| `prompts/` | 用户交互模板 | 包含执行代码或逻辑 |
45+
| `index.js` | 文件复制安装器 | 业务逻辑、网络请求 |
46+
| `tools/` | 开发期工具 | 被 CLI 或 Agent 调用 |
47+
48+
## CLI 安装器流程
49+
50+
```
51+
devcodex init [--force] [--dry-run]
52+
↓
53+
扫描 SOURCES 数组（agents/skills/instructions/prompts/hooks/...）
54+
↓
55+
确定目标目录（.github/）
56+
↓
57+
逐文件复制（dry-run 模式仅输出计划）
58+
↓
59+
输出统计（已安装/已跳过/已更新）
60+
```
61+
62+
`devcodex update` = `devcodex init --force`（强制覆盖）
63+
64+
## Skill 文件规范
65+
66+
每个 Skill 必须包含：
67+
68+
```markdown
69+
---
70+
name: <skill-name>
71+
description: <简要描述>
72+
---
73+
# Skill 标题
74+
...
75+
```
76+
77+
- 文件名：`SKILL.md`
78+
- 路径：`skills/<domain>/<skill-name>/SKILL.md`
79+
- `name` 字段必须与目录名完全一致
80+
81+
## Instructions 编号规则
82+
83+
| 编号范围 | 类别 |
84+
|---------|------|
85+
| 00-09 | 安全与通用（全局注入） |
86+
| 10-12 | 工作流规则（dev/fix/analyze/audit/self-fix）|
87+
| 13-17 | 产物规则（report/memory/output-paths/compliance）|
88+
89+
## 关键约束
90+
91+
- ⛔ 禁止在 `index.js` 中硬编码业务逻辑（只做文件复制）
92+
- ⛔ 禁止修改 `tools/migrate-*.js` 以外的工具为可发布文件
93+
- ⛔ `plugin.json` 的 `version` 必须始终与 `package.json` 同步
94+
- ⚠️ 修改任何规范文件后，必须同步运行 `devcodex update` 推送到工作区

‎.devcodex/profile/03-代码风格.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# 03 — 代码风格
2+
3+
## JavaScript（index.js / tools/）
4+
5+
### 基础规范
6+
7+
| 项目 | 规范 |
8+
|------|------|
9+
| **缩进** | 2 个空格 |
10+
| **引号** | 单引号（`'`） |
11+
| **分号** | 无分号 |
12+
| **模块系统** | CommonJS（`require`/`module.exports`） |
13+
| **行尾换行** | 文件末尾保留一个空行 |
14+
| **最大行长** | 120 字符（软限制） |
15+
16+
### 命名约定
17+
18+
| 类型 | 风格 | 示例 |
19+
|------|------|------|
20+
| 变量/函数 | camelCase | `copyFile`, `targetDir` |
21+
| 常量 | UPPER_SNAKE | `SOURCES`, `DEFAULT_TARGET` |
22+
| 文件名（JS）| kebab-case | `v5-full-audit.js` |
23+
24+
### 注释规范
25+
26+
- 只在需要解释"为什么"时添加注释，不注释显而易见的逻辑
27+
- 顶部保留 shebang（`#!/usr/bin/env node`）
28+
- 函数级注释使用单行 `//`，不用 JSDoc（项目无 TypeScript）
29+
30+
### 错误处理
31+
32+
```js
33+
// ✅ 正确：输出到 stderr，exit code 非零
34+
console.error('Error:', err.message)
35+
process.exit(1)
36+
37+
// ❌ 错误：静默失败或 throw 到顶层
38+
throw err
39+
```
40+
41+
## Markdown 规范文件（agents/skills/instructions/prompts/）
42+
43+
### Frontmatter
44+
45+
```yaml
46+
---
47+
name: skill-name # 必须与目录名一致（Skill 文件）
48+
description: 简短描述 # 不超过 50 字
49+
applyTo: "**" # Instructions 专用
50+
---
51+
```
52+
53+
### 内容规范
54+
55+
- 标题层级：从 `##` 开始（`#` 留给文件标题）
56+
- 表格：必须包含表头，列对齐
57+
- 代码块：必须标注语言（```js / ```yaml / ```bash）
58+
- 列表：优先使用 `-`，嵌套最多 2 级
59+
- 新建 `.md` 文件不超过 500 行（C13 约束）
60+
- 文件末尾保留一个空行
61+
62+
### 文件命名
63+
64+
| 目录 | 命名规则 | 示例 |
65+
|------|---------|------|
66+
| `skills/<domain>/<name>/` | 目录名 kebab-case，文件名 `SKILL.md` | `dev-default/SKILL.md` |
67+
| `instructions/` | `NN-<kebab-name>.instructions.md` | `10-dev.instructions.md` |
68+
| `prompts/` | `<kebab-name>.prompt.md` | `requirement.prompt.md` |
69+
| `agents/` | `<kebab-name>.agent.md` | `devcodex.agent.md` |
70+
71+
## 禁止事项
72+
73+
| 禁止 | 原因 |
74+
|------|------|
75+
| 硬编码 API Key / Token / 密码 | S02 安全底线 |
76+
| 整文件覆盖现有 `.md` | S04 安全底线，必须增量编辑 |
77+
| `console.log` 混入 `stderr` 流程输出 | 会干扰 CI 捕获 |
78+
| 在 `index.js` 中使用第三方模块 | 保持零依赖 CLI |
79+
| `tools/migrate-*.js` 以外工具调用网络 | 离线安装场景 |
80+
| Markdown 文件使用 `Set-Content`/`sed -i` 修改 | C09 — 破坏 UTF-8 编码 |
81+
82+
## 版本控制
83+
84+
- `CHANGELOG.md`：顶层简要记录，每个 MINOR/MAJOR 版本一行
85+
- `changelogs/vX.Y.Z.md`：详细变更，每个版本独立文件
86+
- `PATCH` 版本追加到最近 MINOR 的 changelogs 文件
87+
- commit 信息格式：`type(scope): 简短描述`（中英文均可）
88+
89+
## 本地开发验证流程
90+
91+
```bash
92+
# 1. 安装
93+
cd e:\MySelf\devcodex
94+
npm link
95+
96+
# 2. 在任意工作区验证
97+
cd e:\MySelf
98+
devcodex status
99+
devcodex init --dry-run
100+
devcodex update
101+
102+
# 3. 运行审计工具
103+
node tools/v5-full-audit.js
104+
```

‎.devcodex/profile/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# DevCodex 项目 Profile
2+
3+
> **创建时间**: 2026-04-04
4+
> **最后更新**: 2026-04-04
5+
> **维护者**: Rocky <rocky@vextjs.com>
6+
7+
## 项目概述
8+
9+
DevCodex 是一个 GitHub Copilot Agent Plugin，通过 `npx devcodex init` 将结构化开发规范（工作流/Skill/Instructions）安装到任意项目，让 AI 助手按标准化流程辅助开发、修复、审计和分析。
10+
11+
## Profile 文件索引
12+
13+
| 文件 | 内容 | 状态 |
14+
|------|------|:----:|
15+
| `01-项目信息.md` | 技术栈、仓库地址、版本策略 | ✅ |
16+
| `02-架构约束.md` | 目录结构、模块边界、CLI 流程 | ✅ |
17+
| `03-代码风格.md` | JS 规范、Markdown 格式、禁止事项 | ✅ |
18+
19+
## 快速参考
20+
21+
**技术栈**：Node.js 18+，纯 JS，无编译步骤
22+
**包管理器**：npm
23+
**分发方式**：npm package（`@vextjs/devcodex`）
24+
**核心能力**：CLI（`devcodex init/update/status`）+ Agent `.md` 文件集合
25+
**测试方式**：`npm link` 本地验证
26+
**CI/CD**：GitHub Actions（待配置）
27+
28+
## 注意事项
29+
30+
> - DevCodex 本身是"元工具"：安装的规范文件（.md）就是产品，JS 代码只是安装器
31+
> - 修改规范文件后必须运行 `devcodex update` 同步到工作区 `.github/`
32+
> - `.devcodex/.memory/` 已加入 `.gitignore`，不提交
33+
> - `tools/migrate-*.js` 内部迁移脚本不发布（`.npmignore` 排除）

‎.devcodex/profile/config.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"mode": "dev",
3+
"_comment": "mode: dev=开发模式（轻量合规，跳过 FC1/FC2/SC/RC/CP 强制等待）; prod=生产模式（全量合规）。文件不存在时默认 prod。"
4+
}

0 commit comments

Comments
 (0)