范智鹏
96750467d9
- AGENTS.md：命令表/四层架构/文件结构/命令前缀与项目现状对齐（08-26 tests 迁移、compile:test 等） - docs/2026-08-27-implementation-timeline.md：基于 gittea git 全量历史回溯 40 条提交的 Phase 1-6 时间线（北京时间口径） - _AI_USAGE_LOG.md：补充本轮相关日志记录
104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# 开发范式：Stage-Driven Agent Development (SDAD)
|
||
|
||
## 阶段流程（必须严格遵守，不可跳过或合并）
|
||
① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证
|
||
|
||
## 强制规则
|
||
- 阶段顺序不可调换，每个阶段完成后才进入下一阶段
|
||
- Stage ④ 人类审批是必经门，未通过不得进入编码
|
||
- 编码过程中发现方案有遗漏/矛盾，先暂停提问，不自作主张
|
||
|
||
## 日志规则（自动执行）
|
||
每次创建或修改代码文件后，在项目根目录的 `_AI_USAGE_LOG.md` 中追加一条记录，必须包含以下字段：
|
||
- **日期时间**：文件修改时间（用 `Get-Item LastWriteTime` 或 `Get-Date` 获取），不可乱填或估算
|
||
- **范式步骤**：当前已完成的阶段累积链（如 `① 用户提出 → ② 需求澄清`），按实际执行顺序
|
||
- **修改摘要**：简要描述改了什么
|
||
- **中间产物**：AI 交互过程中被淘汰的草稿或过程稿，包括但不限于：先给了伪代码后改正式实现、输出了多个方案选了其中一个、调试时生成的废弃代码版本、类型试错（如先用 `typeof import()` 后改 `interface`）、先改文件 A 后发现不够又改了文件 B
|
||
- **涉及文件**：文件路径列表
|
||
- **使用模型**：当前使用的模型名
|
||
|
||
**排除项**：打包工程（生产打包 VSIX，`npm run package-prod` / `vsce package`）不需要记录
|
||
|
||
## 阶段执行指引
|
||
- Stage ① @用户提出：load skill stage-1-propose
|
||
- Stage ② @需求澄清：load skill stage-2-clarify
|
||
- Stage ③ @方案设计：load skill stage-3-design
|
||
- Stage ④ @人类审批：load skill stage-4-approve
|
||
- Stage ⑤ @编码实现：load skill stage-5-implement
|
||
- Stage ⑥ @审查验证：load skill stage-6-verify
|
||
|
||
---
|
||
|
||
# 项目：vscode-code-reviewer
|
||
|
||
VSCode 代码审查与规范检查一体化插件。
|
||
|
||
## 开发者命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `npm run compile` | TypeScript 编译（tsc -p ./）+ 拷贝 webview JS（scripts/copy-webview-js.mjs） |
|
||
| `npm run compile:test` | 测试编译（tsc -p ./tsconfig.test.json） |
|
||
| `npm run watch` | tsc watch 模式 |
|
||
| `npm run lint` | ESLint 检查 `src/`（eslint src） |
|
||
| `npm test` | 测试编译 → 运行测试（compile:test && vscode-test） |
|
||
| `npm run package-prod` | 生产打包 VSIX（scripts/package-prod.mjs） |
|
||
| F5 (VSCode) | 启动 Extension Dev Host |
|
||
|
||
测试运行器：`@vscode/test-cli`，配置在 `.vscode-test.mjs`，测试文件匹配 `out/tests/**/*.test.js`（测试源码位于根目录 `tests/`）。
|
||
|
||
验证顺序：`lint → compile → npm test`（`npm test` 内部执行 `compile:test` + `vscode-test`）。
|
||
|
||
## 架构
|
||
|
||
四层架构，见 `docs/superpowers/specs/2026-07-10-code-reviewer-design.md`：
|
||
|
||
```
|
||
UI 层 — Webview 审查/设置面板（src/panel、src/views）+ Inline Diagnostic + Code Action
|
||
核心层 — Orchestrator（编排器）+ Merger（合并）+ AI 审查引擎（src/ai）
|
||
适配层 — Linter 适配器（统一 LinterAdapter 接口，src/adapters/adapter.ts）
|
||
基础层 — 配置管理（src/config）/ 规则管理（src/rules）/ 报告导出（src/utils/report.ts）
|
||
```
|
||
|
||
所有 linter 统一实现 `LinterAdapter` 接口（定义在 `src/adapters/adapter.ts`），通过 Orchestrator 调度，结果合并后通过 Webview 面板展示。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
src/
|
||
├── extension.ts # 入口：activate/deactivate
|
||
├── activation/ # 注册命令、视图、CodeAction
|
||
├── adapters/ # LinterAdapter 接口 + 5 个 linter 适配器（ESLint/Stylelint/SQLFluff/PMD/JSP）
|
||
├── ai/ # AI 审查引擎 + Provider 框架（providers/）
|
||
├── orchestrator/ # 编排器：调度适配器、聚合结果
|
||
├── merger/ # 结果合并（静态诊断 + AI 翻译配对）
|
||
├── fix/ # 修复链路（fixEngine/aiFixEngine/customFixEngine/fixPreview/fixPending 等）
|
||
├── rules/ # 规则管理（builtin-rules、转换器/导入/导出/过滤/预览）
|
||
├── scope/ # 方法级审查（method-extractor、status-cache）
|
||
├── panel/ # 审查/设置 Webview 面板
|
||
├── views/ # TreeView/CodeLens Provider + webview JS
|
||
├── config/ # 配置管理（ai/linter/fixer/secret）
|
||
├── diagnostics/ # Inline Diagnostic 标记
|
||
├── i18n/ # 多语言消息
|
||
├── jsp/ # JSP 源码提取
|
||
├── services/ # auxClasspath 等辅助服务
|
||
├── types.ts + types/ # 公共类型
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
命令 ID 前缀统一为 `codeReviewer.`（如 `codeReviewer.review`）。
|
||
|
||
## 代码规范
|
||
|
||
- 变量/函数：camelCase，类：PascalCase
|
||
- 导入风格：ESM（import/export）
|
||
- 不加注释
|
||
- 异步用 async/await
|
||
- ESLint 配置：`eslint.config.mjs`（typescript-eslint parser）
|
||
|
||
## 设计文档
|
||
|
||
设计 spec 存放路径：`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
|
||
编码须严格遵循已批准的 spec，不得自作主张。
|
||
非 spec 文档（如时间线、复盘类文档）放根目录 `docs/`。
|