COBOL Code Refactor Assistant

这是一个运行在 Visual Studio Code 中的 COBOL 分析 MVP。它使用本地 TypeScript 规则分析当前活动的 IBM COBOL 固定格式源文件，通过 COBOL001 检测 PROCEDURE DIVISION 中的普通单目标 GO TO / GOTO（含下划线目标），通过 COBOL002 检查 IF 缺显式 END-IF、多余 END-IF 和孤立 ELSE，并可调用 DeepSeek 为已确认的检测结果生成辅助解释。

DeepSeek 不参与规则匹配；未配置 API 密钥时，本地分析和 VS Code 诊断仍可正常使用。本项目不会自动修改 COBOL 源代码。

截至 2026-09-09，MVP 最终确认单已记录柳超签署 OK；当前工作区的签署及最新证据尚待提交归档。验收时间线、指定交付包和离线回归结果见项目说明。

运行环境要求

项目	要求
操作系统	Windows、macOS 或 Linux
Visual Studio Code	1.80.0 或更高版本
Node.js	18.0.0 或更高版本；推荐使用当前 LTS 版本
npm	9 或更高版本
网络	仅使用 DeepSeek AI 解释时需要访问 DeepSeek API
COBOL 输入	IBM COBOL 固定格式，扩展名为 .cbl、.cob 或 .cobol

Node.js 和 npm 仅在从源码安装、构建或测试时需要。直接安装 VSIX 时，只需要符合要求的 VS Code。

安装步骤

方法一：安装已构建的 VSIX

请安装已验收的 0.2.0 VSIX：

项目	值
目标提交	4d8e3da1bb60326cfa405479a849c795b8c7188b
SHA-256	1226154BC7268E6C875BB5E3C51B90774AD4C530EDEA3C319AB51A6BF7CAFE93

该包与 releases/vscode-extension/2026-09-06/ 下同名包的哈希不同；安装已验收版本时以此路径和哈希为准。

在 VS Code 中安装：

1. 打开 Extensions（扩展）视图。
2. 点击视图右上角的 ...。
3. 选择 Install from VSIX...。
4. 进入 tests/acceptance/evidence/2026-09-06/，选择 cobol-analyzer-0.2.0.vsix。
5. 安装完成后重新加载或重启 VS Code。

也可以使用命令行：

Get-FileHash .\tests\acceptance\evidence\2026-09-06\cobol-analyzer-0.2.0.vsix -Algorithm SHA256
code --install-extension .\tests\acceptance\evidence\2026-09-06\cobol-analyzer-0.2.0.vsix

方法二：从源码安装依赖

在仓库根目录执行：

npm ci
npm run build

npm ci 会按照 package-lock.json 安装所有 npm workspaces 的锁定依赖；npm run build 会依次构建 contracts、COBOL 分析引擎、DeepSeek 客户端和 VS Code 扩展。

如果需要生成 VS Code 扩展的单文件 bundle 和 VSIX 安装包，请在仓库根目录执行：

node scripts/package-extension.mjs

该脚本会将 bundle、VSIX 及配套文件保存到 releases/vscode-extension/<打包日期>/。自行构建的包应单独记录哈希与验证结果，不自动继承上述包的验收结论。

运行方法

运行已安装的扩展

1. 在 VS Code 中打开一个 .cbl、.cob 或 .cobol 文件。
2. 扩展会在文件打开时自动分析；编辑后约 1.5 秒会再次分析。
3. 也可按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P），执行 Analyze Current COBOL File。
4. 在编辑器波浪线或 Problems 面板（Ctrl+Shift+M）中查看 COBOL001（warning）与 COBOL002（error）结果。
5. 若已配置 DeepSeek API 密钥，可在诊断位置打开灯泡菜单，并选择 Explain with DeepSeek。

可使用仓库中的正例快速验证：

samples/integration-test/positive/goto-simple.cbl

当前 MVP 仅分析当前打开的固定格式 COBOL 文件，不分析 COPYBOOK、不扫描整个工作区，也不自动修改代码。扩展还会跳过超过 5000 行或 250 KB 的文件。

支持的注释为第 7 列 *、/ 整行注释；*> 行内注释、条件编译指令、完整续行及同一 IF 内重复 ELSE 检查不在本期范围。COBOL002 的显式终止要求是项目检查规则，不是完整 COBOL 语法校验，兼容 END IF 写法。

编辑后旧诊断立即失效，请等待重新分析再请求解释。解释通过诊断灯泡的 Quick Fix 触发，校验文档版本；同一版本同一 Finding 加载期间不接受重复请求。

从源码调试运行

1. 使用 VS Code 打开仓库根目录。
2. 确认已执行 npm ci 和 npm run build。
3. 打开 Run and Debug（运行和调试）视图。
4. 选择 Run Extension，然后按 F5。
5. 在新打开的 Extension Development Host 窗口中打开 COBOL 文件并按上述方式运行分析。

构建和测试命令

# TypeScript 全量构建
npm run build

# TypeScript 类型检查
npm run typecheck

# 编译，并运行 contracts 及引擎、DeepSeek Mock、VS Code 三个组件的离线测试（不含真实 API smoke）
npm test

# 单独运行 DeepSeek Client 的确定性组件测试（已包含在 npm test 中，Mock 不访问真实 API）
node --test tests/deepseek-client/deepseek-client.test.js

# 运行进程内跨组件联调与独立 VS Code 契约测试
node --test tests/integration/layer3-e2e.test.js
node --test tests/integration/_ext/engine-contract.test.js tests/integration/_ext/deepseek-contract.test.js
npx vitest run --config tests/integration/vitest.config.ts

# 运行 smoke 测试；真实 DeepSeek 测试需要 API 密钥
npm run test:smoke

# 仅运行 VS Code 扩展的 Vitest 测试
npx vitest run --config tests/vscode-extension/vitest.config.ts

上述离线命令在 2026-09-09 共通过 347 项测试，0 失败、0 跳过；数量包含组件、进程内联调及补充契约测试。分项结果与实际执行命令见项目说明。真实 API 和 Extension Host 验收记录单独列示。

API 密钥配置说明

AI 解释功能优先使用 VS Code 侧边栏「DeepSeek API Key」面板保存的密钥（基于加密的 SecretStorage，按机器保存）；面板未保存密钥时才回退使用进程环境变量 DEEPSEEK_API_KEY。项目不会自动读取 .env 文件。若使用环境变量方式，设置变量后需要从该环境启动或彻底重启 VS Code；使用侧边栏面板方式在保存后即可生效，无需重启。

推荐原环境变量用户在活动栏 COBOL Analyzer → DeepSeek API Key 面板保存一次。SecretStorage 与 Workspace 无关，不随 Settings Sync 跨机器同步，更换机器后需重新配置。面板中长 Key 仅显示末 4 位，长度不超过 4 时全部掩码；输入框不回显旧 Key。Provider 读取失败时返回 INVALID_CONFIG，不回退环境变量。

Windows PowerShell：当前终端会话

$env:DEEPSEEK_API_KEY = "<你的 DeepSeek API Key>"
code --new-window .

关闭该 PowerShell 窗口后，临时变量即失效。如果 VS Code 已经在运行，建议先完全退出，再从已配置变量的终端启动。

Windows：持久写入当前用户环境变量

setx DEEPSEEK_API_KEY "<你的 DeepSeek API Key>"

执行后必须完全退出并重新启动 VS Code，新进程才能读取该变量。

macOS / Linux

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
code .

如需持久生效，可将 export 命令加入所用 Shell 的个人配置文件，然后重新启动终端和 VS Code。

DeepSeek 环境变量

环境变量	是否必填	默认值	说明
DEEPSEEK_API_KEY	未在面板保存时使用 AI 解释必填	无	DeepSeek API 密钥（面板未保存时作回退来源）
DEEPSEEK_BASE_URL	否	https://api.deepseek.com	API 基础地址；末尾 / 会被移除
DEEPSEEK_MODEL	否	deepseek-chat	调用的模型名称
DEEPSEEK_TIMEOUT_MS	否	30000	每次 HTTP 尝试的超时毫秒数，必须为正整数
DEEPSEEK_MAX_TOKENS	否	8192	正式可选配置，写入请求体 max_tokens，必须为正整数

请勿将真实 API Key 写入源代码、示例文件、日志或提交到 Git。侧边栏面板与环境变量均未配置密钥时，仅 Explain with DeepSeek 不可用，本地 COBOL 分析不受影响。

Timeout 和 Max Tokens 省略或为空白时使用默认值，非法值返回 INVALID_CONFIG。仅 EMPTY_RESPONSE 最多额外重试 2 次，总计最多 3 次 HTTP 请求；第三次仍为空时返回 EMPTY_RESPONSE，其他错误不重试。超时按每次尝试计算，连续空响应时默认总等待可能接近 90 秒；每次重试可能消耗外部 API 配额。以上均已纳入正式基线。

依赖清单

本项目使用 npm workspaces 管理四个包。

工作区包及运行时依赖

包	版本	作用	直接依赖
@cobol-analyzer/contracts	0.1.0	跨组件共享的 TypeScript 契约	无
@cobol-analyzer/cobol-engine	0.1.0	固定格式预处理、Tokenize、轻量解析及 COBOL001、COBOL002	@cobol-analyzer/contracts
@cobol-analyzer/deepseek-client	0.1.0	DeepSeek API 调用和响应校验	@cobol-analyzer/contracts
@cobol-analyzer/vscode-extension	0.2.0	VS Code 编辑器集成、诊断及 AI 解释展示；发布产物名为 cobol-analyzer	上述三个工作区包

除仓库内工作区包外，生产代码没有直接的第三方 npm 运行时依赖；DeepSeek 客户端使用运行环境提供的 fetch。

开发依赖

依赖	package.json 版本范围	锁定版本	用途
typescript	^5.9.3	5.9.3	TypeScript 编译和类型检查
@types/node	^26.2.0	26.2.0	Node.js 类型定义
@types/vscode	^1.80.0	1.125.0	VS Code Extension API 类型定义
esbuild	非直接依赖（由依赖树引入）	0.21.5	打包脚本使用的 VS Code 扩展 bundle 工具
vitest	^1.6.1	1.6.1	VS Code 扩展单元测试与独立契约测试

完整的传递依赖及校验信息以根目录 package-lock.json 为准。

项目结构

packages/
├── contracts/          # 共享外部接口
├── cobol-engine/       # 本地确定性 COBOL 分析
├── deepseek-client/    # DeepSeek API 客户端
└── vscode-extension/   # VS Code 扩展

samples/                # COBOL 测试样例
tests/                  # 自动测试、smoke 测试和测试资料
docs/                   # MVP 正式设计基线

正式 MVP 范围和组件边界请参阅：

• docs/MVP_COMMON.md
• docs/MVP_RULE_ENGINE.md
• docs/MVP_DEEPSEEK_CLIENT.md
• docs/MVP_VSCODE_EXTENSION.md

项目详细说明

有关项目背景、功能范围、系统架构、运行流程及当前状态等详细内容，请参考 项目说明。

最终验收步骤、证据记录和 OK/NG 签署位置请使用 MVP 真实验收计划。

代码覆盖率成果物见 2026-09-13 覆盖率报告：Node 组件行覆盖率 96.74%，VS Code 插件 93.13%；包含真实测试日志、HTML/LCOV/JSON 结果、采集命令及源码范围和排除项。历史结果保留在 覆盖率成果物索引，不增加覆盖率门槛。