Skip to content

Commit 9e833e4

Browse files
committed
fix: sync template flow and doc sources
1 parent 4976619 commit 9e833e4

51 files changed

Lines changed: 528 additions & 214 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,18 @@ npx devcodex init
8484

8585
标准安装路径下,无需也不依赖 `@DevCodex`;`.github/agents/` 作为可选显式入口随 Copilot 端默认安装。`v1.9.0` 起,Hook 运行时也随 `init/update` 分发到 `.github/hooks/_runtime/`,不再要求目标项目从 `node_modules/@vextjs/devcodex/...` 读取 Hook 脚本。
8686

87+
## 正式需求与执行模板边界
88+
89+
当前仓库的正式需求信源是 `website/docs/versions/v1/<active-version>/requirements/`,版本内的 `index/design/plan/progress/decisions` 都以这里为准。
90+
91+
`prompts/*.prompt.md` 不是当前项目的正式需求入口,而是 CP1 / CP2 / CP3 的默认执行模板:它们负责约束 AI 如何生成需求概述、技术方案、实施计划与实施进度。若项目已经定义自定义 requirement 规范,则项目规范优先,prompt 只提供通用骨架。
92+
93+
默认职责边界如下:
94+
95+
- CP1:确认需求目标、用户交互、业务流程、验收结果与范围边界
96+
- CP2:确认实现流程、节点职责、公共契约、兼容性策略、边界问题与测试策略
97+
- CP3:确认实施顺序、里程碑、验证方式、风险与回滚
98+
8799
## 默认执行原则
88100

89101
- **意图优先**:当用户看起来切到新需求时,先基于上下文判断意图;只有意图不清晰时才用关键词辅助,而不是反过来。

‎RULES.md‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,20 +23,27 @@ DevCodex 同时支持两种加载路径,规则语义保持一致,由 IDE 决
2323
- **Instruction-Fallback**:Hooks 不可用时,继续依赖 instructions / skills 承载软约束
2424
- **当前首阶段实现**:Hook 运行时由 `init/update` 一并分发到 `.github/hooks/_runtime/`,不要求目标项目从 `node_modules/@vextjs/devcodex/...` 读取脚本
2525

26+
## 正式需求与执行模板边界
27+
28+
- **正式需求信源**:当前项目内的正式需求写在 `website/docs/versions/v1/<active-version>/requirements/`。
29+
- **执行模板职责**:`prompts/*.prompt.md` 负责约束 CP1 / CP2 / CP3 产物结构,是默认执行模板,不替代当前项目的正式 requirement 入口。
30+
- **项目规则优先**:如果项目已经定义自定义 requirement 规范,则项目规范优先,prompt 只提供通用骨架。
31+
- **阶段边界**:CP1 看需求目标、用户交互与业务结果;CP2 看实现流程、公共契约、兼容性与边界问题;CP3 看实施顺序、验证、风险与回滚。
32+
2633
## 意图路由
2734

28-
| 意图 | 路由工作流 | 授权 |
29-
|------|-----------|------|
30-
| 开发新功能 / 重构 / 优化 / 初始化 / 文档 | dev(8 子类型) | Free(部分子类型需 Pro)|
31-
| Bug 修复 / 报错 / 线上事故 / 安全漏洞 | fix(3 子类型) | Free(incident/security 需 Pro)|
32-
| 多轮分析(≥3轮)/ 技术调研 / 可行性评估 | analyze | Free |
33-
| 深度审查 / 全面体检 / 逐项检查 | audit(6 子类型) | Free(项目工程需 Pro)|
34-
| 规范文件自修复 | self-fix | Pro |
35-
| 恢复/继续上次中断任务 | resume | Pro |
36-
| 不匹配上述意图 | plan(兜底) | Pro |
37-
| 纯问答 / 解释 | chat(快速路径) | Free |
38-
39-
> *Tier 标签为规划中功能,当前全功能开放;未来接入服务端校验时生效,不影响当前使用。*
35+
| 意图 | 路由工作流 | 当前状态 |
36+
|------|-----------|----------|
37+
| 开发新功能 / 重构 / 优化 / 初始化 / 文档 | dev(8 子类型) | 当前全量开放 |
38+
| Bug 修复 / 报错 / 线上事故 / 安全漏洞 | fix(3 子类型) | 当前全量开放 |
39+
| 多轮分析(≥3轮)/ 技术调研 / 可行性评估 | analyze | 当前全量开放 |
40+
| 深度审查 / 全面体检 / 逐项检查 | audit(6 子类型) | 当前全量开放 |
41+
| 规范文件自修复 | self-fix | 当前全量开放 |
42+
| 恢复/继续上次中断任务 | resume | 当前全量开放 |
43+
| 不匹配上述意图 | plan(兜底) | 当前全量开放 |
44+
| 纯问答 / 解释 | chat(快速路径) | 当前全量开放 |
45+
46+
> *Tier 标签目前仅保留为未来规划信息。当前版本 `token-check` 只是授权占位,不对任何工作流或子类型做 tier 阻断。*
4047
4148
## 安全底线
4249

‎instructions/02-output-paths.instructions.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ applyTo: "**"
3636
│ │ │ └── 实施方案.md # 📎 头部须含反向引用:> 上级需求: [需求名](../../01-需求概述.md)
3737
│ │ └── <关联服务>/ # 每个关联服务独立子目录
3838
│ │ └── 实施方案.md
39-
│ ├── 04-实施计划.md # 🔴 强制
39+
│ ├── 04-实施计划.md # 🔴 强制(轻计划摘要 / 完整实施计划两档)
4040
│ ├── 05-实施进度.md # ⚠️ 条件(任务跨 2 轮以上会话且已存在 04-实施计划.md 时)
4141
│ ├── scripts/ # ⚠️ 条件(有辅助脚本时,可提交)
4242
│ │ └── <用途>.js / <用途>.sh # 数据迁移/数据填充等共享辅助脚本;默认禁止放业务逻辑或网络请求
@@ -66,9 +66,10 @@ applyTo: "**"
6666
| **scripts/ 触发条件** | 任务目录(requirements/<任务>/ 或 bugs/<任务>/)下有共享辅助脚本(数据迁移/数据填充/自动化验证等)时创建对应 `scripts/` 子目录;默认禁止放入业务逻辑或网络请求。`*-接口验证.cjs` 属规范强制产物,存放任务根目录(非 scripts/)|
6767
| **本地临时脚本豁免** | 仅本地执行、不会提交发布链路、无敏感信息的临时脚本/配置可放入任务目录 `.tmp/local-scripts/` 或保持未提交;允许直接使用局部常量和网络请求,但不得伪装成共享正式产物 |
6868
| **services/ 触发条件(跨服务)** | 需求涉及 ≥2 个服务时在 CP2 后创建;每个 `实施方案.md` 头部**必须**包含反向引用 `> 📎 上级需求:[需求名](../../01-需求概述.md)(入口服务:<服务名>)`;**禁止**各服务各自单独建 `requirements/<需求名>/` 目录(碎片化) |
69+
| **04-实施计划 计划层级** | 默认创建 `04-实施计划.md`;小到中型任务可使用“轻计划摘要”,高风险 / 多模块 / 接口或 Schema 变更 / 跨轮次任务使用“完整实施计划” |
6970
| **05-实施进度 触发条件** | 仅在任务跨 2 轮以上会话、存在明确阻塞或用户要求持续跟踪时创建,且前提是已存在 `04-实施计划.md` |
7071
| **禁止写入源码目录** | 脚本/测试/辅助文件严禁放入项目源码目录 |
71-
| **强制产物首轮完成** | 01/04 在首轮会话结束前必须创建;02-技术方案.md 和 实施方案/ 按条件触发;services/ 在 CP2 后按需创建 |
72+
| **强制产物首轮完成** | 01/04 在首轮会话结束前必须创建;其中 `04-实施计划.md` 可按轻计划摘要 / 完整实施计划两档落地;02-技术方案.md 和 实施方案/ 按条件触发;services/ 在 CP2 后按需创建 |
7273
| **需求归档(v1.9.3+)** | 已完成且不再活跃的需求目录下创建空文件 `.archived`;CP gate 扫描跳过含此标记的需求,避免历史需求全局阻断 dev 工作流 |
7374

7475
## 报告路径

‎instructions/10-dev.instructions.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,12 @@ CP1(需求确认)→ PR-1 内部自检 → CP2(方案确认)→ plan-rev
4848
| CP2 | 方案确认 | 🔴 必须 | 确认技术方案可行后再编码 |
4949
| CP3 | 实施计划确认 | 条件触发 | 确认任务拆分、顺序、依赖、验证和回滚后再开始逐文件执行;docs/init/plan-review 按子类型规则豁免并记录 N/A |
5050

51+
### CP 关注点边界
52+
53+
- **CP1**:重点确认需求目标、用户交互、业务流程、验收结果与范围边界;不提前展开实现时序、内部节点设计或接口细节。
54+
- **CP2**:重点确认实现流程、节点职责、公共契约、兼容性策略、边界问题与测试策略;已有公共接口、Schema、返回结构或错误码变更时,必须给出“现状契约 → 目标契约”差异说明。
55+
- **CP3**:只确认实施顺序、里程碑、验证方式、风险与回滚;不得重复需求正文、方案论证或兼容性主说明。
56+
5157
### CP 执行规则
5258

5359
1. **严格按序**:CP1 → CP2 → CP3,不得跳过中间步骤
@@ -106,6 +112,8 @@ CP1(需求确认)→ PR-1 内部自检 → CP2(方案确认)→ plan-rev
106112
- 技术选型与项目 profile 技术栈一致
107113
- 依赖可安装,无模糊"待定"步骤
108114
- 对已有代码的改动方案,必须逐行追踪新代码在原始执行路径中的实际插入位置,验证新逻辑不会被已有的提前 return/throw/break 跳过
115+
- 对已有公共接口、Schema、返回结构或错误码的变更,必须给出“现状契约 → 目标契约”差异说明
116+
- CP2 方案必须显式给出兼容性策略与边界问题清单,不能只散落在风险说明中
109117

110118
### PR-3 约束合规性 🔴
111119
- 无硬编码敏感信息(S02)

‎instructions/17-compliance.instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ applyTo: "**"
4141
- PC4 规范雷达:见 `18-spec-radar.instructions.md` §预检查输出格式(v1.9.4+ 含 G10 limit 截断恢复检测)
4242
- PC5 部署体状态(v1.9.4+):cwd 父链 .claude/.github/ ✅ 存在 / N/A 无父级 · 与源仓库同步 ✅ / ⚠️ [N 文件滞后] / N/A
4343
- PC6 工作区一致性(v1.9.4+):git 未提交变更 ✅ 无 / ⚠️ [N 文件 dirty] · 当前需求目录 [requirements/<X>/ / 无关联]
44+
- PC7 新会话首步 resume 强制检测(v1.9.4+,仅首条用户消息触发):✅ 已 Read tasks 文件 + 比对 SUMMARY 一致 / ⚠️ 数据不一致需 resume / N/A(非首条)
4445
```
4546

4647
> ⚠️ PC0 检查失败时(Profile 未加载)不得跳过 — 必须立即加载后才能继续,ENV_MODE 由 Profile 的 `config.json` 决定。

‎prompts/implementation-plan.prompt.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,15 @@ applyTo: .devcodex/requirements/**
99
> **触发**: dev 工作流 CP3 阶段
1010
> ⚠️ 本模板只承接任务拆分、实施顺序、前置依赖、验证方式与回滚策略,不重复需求背景或技术方案中的设计论证。
1111
12+
## 计划模式
13+
14+
| 模式 | 适用场景 | 必填内容 |
15+
|------|---------|---------|
16+
| 轻计划摘要 | 小到中型任务、单阶段收口、无高风险接口或 Schema 破坏性变更 | 总览、任务分解、实施顺序、验证方式、回滚摘要 |
17+
| 完整实施计划 | 高风险 / 多模块 / 接口或 Schema 变更 / 跨轮次实施 | 总览、任务分解、里程碑、风险点与回滚、验收清单 |
18+
19+
> ⚠️ `04-实施计划.md` 始终要创建,但不要求所有任务都套用同一重量级模板;小任务优先使用“轻计划摘要”,只有高风险或多阶段任务才展开为“完整实施计划”。
20+
1221
---
1322

1423
```markdown
@@ -17,12 +26,13 @@ applyTo: .devcodex/requirements/**
1726
> **版本**: v0.0.1
1827
> **日期**: YYYY-MM-DD
1928
> **关联方案**: [技术方案路径]
29+
> **计划模式**: 轻计划摘要 / 完整实施计划
2030
> **状态**: 计划中 / 执行中 / 已完成
2131
```
2232

2333
## §1 总览
2434

25-
> 一句话描述本次实施范围,强调“这次要怎么落地”,而不是重新解释“为什么这样设计”。
35+
> 一句话描述本次实施范围,强调“这次要怎么落地”,而不是重新解释“为什么这样设计”。轻计划摘要只保留最小顺序与验证信息;完整实施计划再展开里程碑与风险细节。
2636
2737
**预计工作量**:[X] 小时 / 天
2838
**风险等级**:🔴 高 / 🟡 中 / 💡 低
@@ -37,9 +47,9 @@ applyTo: .devcodex/requirements/**
3747
| T-02 | | T-01 | | | |
3848
| T-03 | | T-02 | | | |
3949

40-
## §3 里程碑
50+
## §3 里程碑 / 实施顺序
4151

42-
> 里程碑用于表达任务顺序和阶段性验收,不用于重新描述技术方案。
52+
> 完整实施计划使用里程碑表表达阶段性验收;轻计划摘要可改为“实施顺序”列表,但仍要说明任务先后与阶段完成点。
4353
4454
| 里程碑 | 包含任务 | 验收方式 |
4555
|--------|---------|---------|
@@ -48,7 +58,7 @@ applyTo: .devcodex/requirements/**
4858

4959
## §4 风险点与回滚
5060

51-
> 回滚要写到可执行粒度:失败后撤回什么、恢复到什么状态、如何确认已恢复。
61+
> 轻计划摘要至少要写出回滚摘要;完整实施计划应写到可执行粒度:失败后撤回什么、恢复到什么状态、如何确认已恢复。
5262
5363
| 任务 | 风险 | 回滚方案 |
5464
|------|------|---------|

‎scripts/test-validate-profile.js‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
#!/usr/bin/env node
2+
'use strict'
3+
4+
const assert = require('assert')
5+
const fs = require('fs')
6+
const os = require('os')
7+
const path = require('path')
8+
const { spawnSync } = require('child_process')
9+
10+
const ROOT = path.resolve(__dirname, '..')
11+
const SCRIPT = path.join(ROOT, 'scripts', 'validate-profile.js')
12+
const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
13+
const VERSION = pkg.version
14+
const PACKAGE_NAME = pkg.name
15+
const TEMP_ROOTS = []
16+
17+
function writeFile(root, relativePath, content) {
18+
const filePath = path.join(root, relativePath)
19+
fs.mkdirSync(path.dirname(filePath), { recursive: true })
20+
fs.writeFileSync(filePath, content)
21+
}
22+
23+
function createWorkspace(projectInfo) {
24+
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'devcodex-validate-profile-'))
25+
TEMP_ROOTS.push(root)
26+
27+
writeFile(root, 'package.json', JSON.stringify({ name: PACKAGE_NAME }, null, 2))
28+
writeFile(root, '.devcodex/profile/README.md', '# README\n')
29+
writeFile(root, '.devcodex/profile/02-架构约束.md', '# 02\n')
30+
writeFile(root, '.devcodex/profile/03-代码风格.md', '# 03\n')
31+
writeFile(root, '.devcodex/profile/config.json', JSON.stringify({
32+
mode: 'dev',
33+
agent: 'claude-code',
34+
pluginVersion: VERSION
35+
}, null, 2))
36+
writeFile(root, '.devcodex/profile/01-项目信息.md', projectInfo)
37+
38+
return root
39+
}
40+
41+
function runValidate(workspaceRoot) {
42+
return spawnSync(process.execPath, [SCRIPT], {
43+
cwd: workspaceRoot,
44+
encoding: 'utf8'
45+
})
46+
}
47+
48+
function legacyProjectInfo() {
49+
return [
50+
'# 01 — 项目信息',
51+
'',
52+
'| 项目 | 值 |',
53+
'|------|----|',
54+
`| **当前版本** | ${VERSION} |`,
55+
`| **当前阶段** | ${VERSION} |`,
56+
'',
57+
'```',
58+
'devcodex/skills/ → .github/skills/',
59+
'devcodex/instructions/ → .github/instructions/',
60+
'devcodex/prompts/ → .github/prompts/',
61+
'devcodex/data/ → .github/data/',
62+
'devcodex/instructions.md → .github/copilot-instructions.md',
63+
'devcodex/RULES.md → .github/RULES.md',
64+
'```',
65+
'',
66+
'> 说明:`devcodex/agents/` 仍保留在源码仓中,但不再作为目标项目默认分发路径。',
67+
'',
68+
'## 授权层级',
69+
'',
70+
'| 层级 | 功能范围 |',
71+
'|------|---------|',
72+
'| **Free** | dev |',
73+
'| **Pro** | self-fix |',
74+
''
75+
].join('\n')
76+
}
77+
78+
function currentProjectInfo() {
79+
return [
80+
'# 01 — 项目信息',
81+
'',
82+
'| 项目 | 值 |',
83+
'|------|----|',
84+
`| **当前版本** | ${VERSION} |`,
85+
`| **当前阶段** | ${VERSION} |`,
86+
'| **需求总览** | `website/docs/versions/v1/<active-version>/requirements/index.md` — 当前活跃版本的 P0/P1/P2 分层总览 |',
87+
'',
88+
'```',
89+
'devcodex/skills/ → .github/skills/',
90+
'devcodex/instructions/ → .github/instructions/',
91+
'devcodex/prompts/ → .github/prompts/',
92+
'devcodex/data/ → .github/data/',
93+
'devcodex/agents/ → .github/agents/(仅 Copilot 默认分发)',
94+
'devcodex/instructions.md → .github/copilot-instructions.md(Copilot)',
95+
'devcodex/RULES.md → .github/RULES.md',
96+
'```',
97+
'',
98+
'> 说明:`instructions.md` 是单源规范文件,安装时按平台 rename 到 `.github/copilot-instructions.md` 或 `CLAUDE.md`;`agents/` 当前仅在 Copilot 端默认分发,Claude Code 端仍通过 Skills 路由,不分发 agents。',
99+
'',
100+
'## 授权状态',
101+
'',
102+
'- 当前 `token-check` 仅为授权占位,不执行 tier 阻断。',
103+
'- 所有工作流和子类型当前全量开放。',
104+
''
105+
].join('\n')
106+
}
107+
108+
function main() {
109+
try {
110+
const legacyRoot = createWorkspace(legacyProjectInfo())
111+
const legacyResult = runValidate(legacyRoot)
112+
const legacyOutput = `${legacyResult.stdout}\n${legacyResult.stderr}`
113+
114+
assert.strictEqual(legacyResult.status, 2, legacyOutput)
115+
assert.match(legacyOutput, /legacy agents distribution wording/)
116+
assert.match(legacyOutput, /legacy Free\/Pro authorization tiers/)
117+
assert.match(legacyOutput, /current formal requirement entry/)
118+
119+
const currentRoot = createWorkspace(currentProjectInfo())
120+
const currentResult = runValidate(currentRoot)
121+
const currentOutput = `${currentResult.stdout}\n${currentResult.stderr}`
122+
123+
assert.strictEqual(currentResult.status, 0, currentOutput)
124+
console.log('\x1b[32m✓ validate-profile regression tests passed\x1b[0m')
125+
} finally {
126+
TEMP_ROOTS.forEach(root => fs.rmSync(root, { recursive: true, force: true }))
127+
}
128+
}
129+
130+
main()

‎scripts/validate-profile.js‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ const pluginVersion = (() => {
2626
return ''
2727
}
2828
})()
29+
const pluginPackageName = (() => {
30+
try {
31+
return JSON.parse(fs.readFileSync(path.join(PLUGIN_ROOT, 'package.json'), 'utf8')).name || ''
32+
} catch {
33+
return ''
34+
}
35+
})()
2936

3037
function err(msg) { errors.push(msg) }
3138
function warn(msg) { warnings.push(msg) }
@@ -53,6 +60,44 @@ function hasLegacyStageDraft(text) {
5360
/^\s*[-*]\s*阶段摘要[::]/m.test(text)
5461
}
5562

63+
function readJsonIfExists(filePath) {
64+
try {
65+
return JSON.parse(fs.readFileSync(filePath, 'utf8'))
66+
} catch {
67+
return null
68+
}
69+
}
70+
71+
function isSourceRepoProfileTarget() {
72+
if (path.resolve(cwd) === PLUGIN_ROOT) return true
73+
const cwdPackage = readJsonIfExists(path.join(cwd, 'package.json'))
74+
return !!(pluginPackageName && cwdPackage && cwdPackage.name === pluginPackageName)
75+
}
76+
77+
function hasCurrentAgentsDistribution(text) {
78+
return /devcodex\/agents\/\s*→\s*\.github\/agents\//.test(text) &&
79+
/(Copilot[^\n。]*默认分发|默认分发[^\n。]*Copilot)/.test(text) &&
80+
/(Claude Code[^\n。]*不分发|不分发[^\n。]*Claude Code)/.test(text)
81+
}
82+
83+
function checkProjectInfoSemantics(text) {
84+
if (/不再作为目标项目默认分发路径/.test(text)) {
85+
warn('[profile] 01-项目信息.md still contains legacy agents distribution wording')
86+
}
87+
if (!hasCurrentAgentsDistribution(text)) {
88+
warn('[profile] 01-项目信息.md missing current agents distribution truth')
89+
}
90+
if (/##\s*授权层级/m.test(text) || /\|\s*\*\*Free\*\*\s*\|/.test(text) || /\|\s*\*\*Pro\*\*\s*\|/.test(text)) {
91+
warn('[profile] 01-项目信息.md still contains legacy Free/Pro authorization tiers')
92+
}
93+
if (!/授权占位/.test(text) || !/全量开放/.test(text)) {
94+
warn('[profile] 01-项目信息.md missing current authorization placeholder truth')
95+
}
96+
if (!/website\/docs\/versions\/v1\/<active-version>\/requirements\//.test(text)) {
97+
warn('[profile] 01-项目信息.md missing current formal requirement entry')
98+
}
99+
}
100+
56101
if (!fs.existsSync(profileDir)) {
57102
console.log(`[profile] no .devcodex/profile/ in ${cwd} — skip (run \`devcodex profile init\` to bootstrap)`)
58103
process.exit(0)
@@ -85,6 +130,10 @@ if (pluginVersion && fs.existsSync(projectInfoPath)) {
85130
} else if (currentStageVersion !== pluginVersion) {
86131
warn(`[profile] 01-项目信息.md 当前阶段漂移: ${currentStageVersion} → ${pluginVersion}`)
87132
}
133+
134+
if (isSourceRepoProfileTarget()) {
135+
checkProjectInfoSemantics(projectInfo)
136+
}
88137
}
89138

90139
// config.json checks

0 commit comments

Comments
 (0)