# integrity-verification

**Repository Path**: sun-tingzhen/integrity-verification

## Basic Information

- **Project Name**: integrity-verification
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Integrity verification（かんぜんせいけんしょう）

## 功能

- 启动后检查 GitHub 登录状态
- 支持在登录后自动拉取 Copilot token 与模型列表
- 支持手动刷新模型
- 支持选择当前 Copilot 模型
- 支持通过输入框发送一条最小聊天请求
- 状态栏展示 GitHub 登录状态、Copilot 可用性和当前模型
- 状态面板展示账号、模型与诊断信息
- 输出面板显示请求结果与必要诊断信息

## 工作原理

### 1. GitHub 登录
插件通过 VS Code 内置的 authentication provider 获取 GitHub session：

- `vscode.authentication.getSession('github', ['read:user'], ...)`

### 2. Copilot token 交换
拿到 GitHub session 后，插件会调用：

- `https://api.github.com/copilot_internal/v2/token`

用当前 GitHub 登录态换取 Copilot 的临时访问 token。

### 3. 自动拉取模型
拿到 Copilot token 后，插件会优先根据 token 返回的 endpoint 自动请求：

- `GET /models`
- 必要时回退 `GET /models/session`

从而获取当前账号实际可用的模型列表。

### 4. 发送聊天
发送聊天时，插件会：

1. 确认 GitHub 已登录
2. 确认 Copilot token 仍然有效
3. 确认模型列表已存在
4. 自动恢复上次选择的模型，若没有则选默认候选
5. 发送 `POST /chat/completions`，必要时回退 `/v1/chat/completions`

## 目录结构

```text
integrity-verification/                 # 项目根目录
├── package.json                        # VS Code 扩展清单、命令、脚本与依赖声明
├── tsconfig.json                       # TypeScript 编译配置
├── src/                                # 所有核心源码目录
│   ├── extension.ts                    # 扩展极薄入口，只负责 activate / deactivate
│   ├── app/                            # 应用编排层
│   │   └── extensionController.ts      # 统一管理命令注册、状态刷新与功能调度
│   ├── config/                         # 常量与配置读取
│   │   ├── constants.ts                # 命令 ID、产品名、Key 前缀等固定常量
│   │   └── settings.ts                 # 读取 VS Code 配置项
│   ├── errors/                         # 自定义错误类型
│   │   └── copilotRequestError.ts      # Copilot HTTP 请求异常定义
│   ├── features/                       # 按功能拆分的业务模块
│   │   ├── auth/                       # 认证相关功能
│   │   │   └── authCommandService.ts   # 管理登录、切换账号、启动登录提示等命令
│   │   ├── chat/                       # 聊天命令功能
│   │   │   └── chatCommandService.ts   # 管理聊天发送、聊天请求执行与错误处理
│   │   ├── models/                     # 模型管理功能
│   │   │   └── modelCommandService.ts  # 管理模型选择、清除与刷新命令
│   │   ├── status/                     # 状态栏相关功能
│   │   │   ├── statusBarPresenter.ts   # 负责状态栏文本与提示展示
│   │   │   └── statusCommandService.ts # 管理状态查看命令
│   │   └── status-panel/               # 状态面板功能
│   │       ├── statusPanelController.ts      # 管理 Webview 生命周期与模块编排
│   │       ├── statusPanelMessageHandler.ts  # 处理 Webview 发回的消息与动作分发
│   │       ├── statusPanelStateBuilder.ts    # 构建状态面板前端状态
│   │       └── statusPanelTypes.ts           # 定义状态面板消息、回调与上下文类型
│   ├── logging/                        # 日志能力封装
│   │   └── outputLogger.ts             # Output 面板日志输出封装
│   ├── services/                       # 服务层，处理外部交互与核心业务
│   │   ├── copilotService.ts           # Copilot token、模型、聊天、诊断核心逻辑
│   │   ├── githubSessionService.ts     # GitHub 登录会话获取与切换
│   │   └── http.ts                     # HTTP / JSON 请求基础能力
│   ├── storage/                        # 存储层，封装 state / secrets 读写
│   │   └── copilotStore.ts             # 模型、错误、token 状态存储
│   ├── types/                          # 共享类型定义
│   │   └── copilot.ts                  # Copilot、状态面板、请求返回等类型
│   ├── ui/                             # 前端页面资源目录
│   │   └── status-panel/               # 状态面板页面资源
│   │       ├── index.css               # 状态面板样式文件
│   │       ├── index.html              # 状态面板 HTML 模板
│   │       └── index.js                # 状态面板前端交互脚本
│   └── utils/                          # 通用工具函数
│       ├── errors.ts                   # 错误文本提取与错误描述格式化
│       ├── format.ts                   # 时间、token、URL 等格式化工具
│       ├── progress.ts                 # VS Code 进度提示封装
│       └── security.ts                 # Webview nonce 等安全辅助函数
└── assets/                             # 静态资源目录
    └── icon.png                        # 扩展图标
```

## 分层架构说明

### 1. 入口层
- `src/extension.ts`
  - 只负责 VS Code 扩展生命周期入口：`activate` / `deactivate`
- `src/app/extensionController.ts`
  - 负责依赖装配、命令注册、会话监听、状态刷新和模块编排
  - 现在更像 orchestrator，而不是具体业务实现层

### 2. Feature 层
按功能把命令逻辑拆开，避免所有行为都堆在一个 controller 中：

- `features/auth/`
  - 登录、切换账号、启动提示登录
- `features/models/`
  - 模型选择、模型刷新、清空模型选择
- `features/chat/`
  - 输入框发起聊天、执行聊天请求、聊天错误处理
- `features/status/`
  - 查看状态、状态栏展示
- `features/status-panel/`
  - 管理状态面板 Webview，以及前后端消息通信
  - 内部继续拆成：
    - `statusPanelController.ts`：只负责生命周期与编排
    - `statusPanelMessageHandler.ts`：处理前端消息分发
    - `statusPanelStateBuilder.ts`：构建前端状态对象
    - `statusPanelTypes.ts`：统一消息与回调类型定义

### 3. Service 层
- `services/githubSessionService.ts`
  - 负责 GitHub 登录态获取与切换
  - `requireSession()`：用于显式登录或底层必须继续执行的场景，会主动要求创建 session
  - `getSessionOrPromptSignIn()`：用于刷新、查看状态、选择模型等普通交互，先静默获取 session，缺失时再提示登录
- `services/copilotService.ts`
  - 负责 Copilot token、模型、聊天、诊断等核心逻辑
- `services/http.ts`
  - 负责底层 HTTP / JSON 请求

### 4. Storage 层
- `storage/copilotStore.ts`
  - 统一封装 `globalState`、`secrets`
  - 负责模型缓存、错误信息、token 状态持久化

### 5. UI 层
- `src/ui/status-panel/index.html`
- `src/ui/status-panel/index.css`
- `src/ui/status-panel/index.js`

这部分统一存放状态面板前端页面资源。

### 6. Utils / Config / Types / Logging 层
- `config/`：常量与配置读取
- `types/`：共享类型定义
- `utils/`：格式化、错误处理、进度、nonce 等通用能力
- `logging/`：输出面板日志封装
- `errors/`：自定义错误类型

## 关键调用链说明

### 1. 扩展启动链路
1. VS Code 调用 `src/extension.ts` 中的 `activate(context)`
2. 创建 `ExtensionController`
3. `ExtensionController.activate()` 注册命令、监听 GitHub session 变化
4. 调用 `refreshState()` 初始化状态栏与状态面板状态

### 2. 登录与模型同步链路
1. 用户触发 `Sign In`
2. `ExtensionController` 把命令转发给 `AuthCommandService`
3. `AuthCommandService` 调用 `GitHubSessionService` 获取 GitHub session
4. 调用 `CopilotService.ensureModels()` 刷新 token 与模型
5. 更新状态栏，并同步状态面板状态

### 3. 聊天请求链路
1. 用户通过输入框命令发起请求
2. `ChatCommandService` 调用 `performChatRequest()`
3. `CopilotService` 确保模型可用、token 有效
4. `CopilotService.requestChat()` 调用 Copilot 聊天接口
5. 返回响应后写入 Output 面板

### 4. 状态面板通信链路
1. `StatusPanelController` 创建 Webview
2. `renderWebviewTemplate()` 加载 `src/ui/status-panel/` 下的页面资源
3. 前端通过 `postMessage` 把 `refreshModels` / `selectModel` / `switchAccount` 等消息发回扩展端
4. `StatusPanelMessageHandler` 负责把消息分发到对应动作
5. `StatusPanelStateBuilder` 负责生成前端最新状态
6. 扩展端再通过 `postState()` 把最新状态推回前端页面

## 命令映射表

| VS Code Command ID | 命令标题 | 实际入口模块 | 主要方法 |
|---|---|---|---|
| `integrityVerification.signIn` | Sign In | `features/auth/authCommandService.ts` | `signIn()` |
| `integrityVerification.switchAccount` | Switch Account | `features/auth/authCommandService.ts` | `switchAccount()` |
| `integrityVerification.showStatus` | Show Status | `features/status/statusCommandService.ts` | `showStatus()` |
| `integrityVerification.selectModel` | Select Model | `features/models/modelCommandService.ts` | `selectModel()` |
| `integrityVerification.clearModelSelection` | Clear Model Selection | `features/models/modelCommandService.ts` | `clearModelSelection()` |
| `integrityVerification.refreshModels` | Refresh Models | `features/models/modelCommandService.ts` | `refreshModels()` |
| `integrityVerification.sendChat` | Send Chat | `features/chat/chatCommandService.ts` | `sendChat()` |

### 命令注册位置
所有命令的注册入口统一保留在：

- `src/app/extensionController.ts`

这样做的目的是：

1. **命令注册统一收口**：便于快速查看扩展暴露了哪些命令
2. **业务逻辑按功能下沉**：具体实现放到 `features/`，避免 controller 继续膨胀
3. **后续扩展更容易**：新增命令时，只需要在 controller 中注册，再指向对应 feature service

## 配置项

- `integrityVerification.promptForLoginOnStartup`
  - 启动时无 GitHub 会话是否提示登录，默认 `true`
- `integrityVerification.forceModelRefreshOnStartup`
  - 启动时是否自动刷新 Copilot token 和模型列表，默认 `true`
- `integrityVerification.copilotApiOverride`
  - 可选调试配置；若填写则强制覆盖自动发现到的 Copilot API 基址
- `integrityVerification.enableVerboseLogs`
  - 是否在输出面板中打印更详细的同步日志，默认 `false`
- `integrityVerification.autoShowOutputOnChat`
  - 聊天成功后是否自动显示输出面板，默认 `false`

## 本地运行

### 1. 安装依赖

```bash
cd integrity-verification
npm install
```

### 2. 编译插件

```bash
npm run compile
```

### 3. 在 VS Code 中调试

1. 用 VS Code 打开 `integrity-verification/`
2. 按 `F5`
3. 在新的 Extension Development Host 窗口里等待插件激活
4. 如果未登录 GitHub，会弹出提示
5. 点击 **登录 GitHub**
6. 登录成功后插件会自动尝试同步 Copilot token 和模型
7. 运行 **Show Status** 查看状态面板
8. 使用 **Send Chat** 通过输入框发送消息
9. 响应会输出到 VS Code 输出面板：`Integrity verification（かんぜんせいけんしょう）`

## 像正式插件一样安装

### 方式一：打包成 `.vsix` 后安装

```bash
cd integrity-verification
npm install
npm run package
```

执行后会在当前目录生成类似下面的文件：

```text
integrity-verification-0.0.1.vsix
```

然后在 VS Code 中安装：

1. 打开扩展视图
2. 点击右上角 `...`
3. 选择 **Install from VSIX...**
4. 选择生成的 `.vsix` 文件
5. 安装完成后重载 VS Code

### 方式二：命令行安装

如果你本机的 `code` 命令可用，也可以直接执行：

```bash
code --install-extension integrity-verification-0.0.1.vsix
```

安装后可用下面命令验证：

```bash
code --list-extensions | grep integrity-verification
```

## 可用命令

- `Integrity verification（かんぜんせいけんしょう）: Sign In`
- `Integrity verification（かんぜんせいけんしょう）: Show Status`
- `Integrity verification（かんぜんせいけんしょう）: Switch Account`
- `Integrity verification（かんぜんせいけんしょう）: Refresh Models`
- `Integrity verification（かんぜんせいけんしょう）: Select Model`
- `Integrity verification（かんぜんせいけんしょう）: Send Chat`
- `Integrity verification（かんぜんせいけんしょう）: Clear Model Selection`

## 状态说明

### 登录成功但没有模型
如果 GitHub 登录成功后仍然没有模型，通常意味着：

- 当前 GitHub 账号没有开通 Copilot 订阅
- GitHub token 可以登录，但无权访问 Copilot 接口
- Copilot 内部接口当前拒绝返回模型列表

这时状态栏通常会显示类似：

- `<账号> · No Copilot`

并且 **Show Status** 会给出最近一次错误。

### 切换账号与右上角账户菜单
当前插件复用的是 **VS Code 内置 GitHub provider**，不是插件自己实现的独立账户系统，因此：

- 现在保留了 `Switch Account`
- `Switch Account` 会重新触发 VS Code 的 GitHub 账号选择流程

需要注意：

- 普通扩展不能像原生 GitHub 账户那样，直接在你截图那个账户列表里插入一条固定的“插件账户状态行”
- 如果要真正像原生账户项那样显示在那里，需要后续单独实现自定义 `AuthenticationProvider` 架构

### 为什么现在全部改成 TypeScript
当前项目已经收口为纯 TypeScript 结构：

- VS Code 扩展入口只保留在 `src/extension.ts`
- 业务编排放在 `src/app/extensionController.ts`
- Copilot / GitHub 会话、模型、聊天等逻辑拆分到 `services/`、`storage/`、`features/`
- 状态面板前端资源统一放在 `src/ui/status-panel/`

这样更适合后续继续扩展多页面 UI、样式拆分和生产级维护。

## 注意事项

- GitHub 登录成功不代表一定拥有 Copilot 订阅
- Copilot 相关接口是运行时依赖，可能随官方实现变化而变化
- 某些模型或账号类型可能返回不同 endpoint；插件会优先使用 token 返回的 endpoint 信息
- `copilot-nes-xtab` 之类特殊模型可能需要走不同基础域名，当前实现已做基础兼容
- 当前 `homepage` / `repository` / `bugs` 使用的是占位地址，正式发布前请替换成你自己的真实仓库地址