编写的代码中必须包含大量注释。一切变量和函数必须指出它的作用，特别的，对于函数必须在声明附近注释写明传递参数的作用、函数体的作用以及返回内容的含义。平均每10行左右就应该有一个注释解释这些代码做了什么。注释尽量完备。
整个图标库在H:\Project\Ksword5.1\Ksword5.1\Ksword5.1\Resource\Icon。你需要尽量使用里面合适的图标来展现按键，而不是所有按键都写字上去。鼠标悬停还需展示按键的功能。此外，你需要负责把他包含到qrc中。懒得的话直接包含整个文件夹都可以。
# KswordARK 开发规范（日志系统）

> 本文档描述 `Framework.h` 日志系统的调用方式与语法规范。  
> 适用范围：Windows 平台下的 KswordARK/Ksword5.1 工程。

---

## 1. 基本接入方式

```cpp
// 1) 所有业务代码统一包含 Framework.h。
#include "Framework.h"
```

---

## 2. 日志语法（必须遵守）

### 2.1 每条日志必须先创建并传入 `kLogEvent`

```cpp
{
    // kLogEvent 的作用：生成并携带本次事件 GUID（不可修改）。
    kLogEvent tmpEvent;

    // info 为全局日志流对象；eol 会自动携带文件/行号/函数并提交日志。
    info << tmpEvent << "现在输出一些文字" << eol;
}
```

### 2.2 错误级别示例（自动附带位置信息）

```cpp
{
    // err/fatal 在控制台会追加 (File, Line, FunctionSignature) 信息。
    kLogEvent tmpEvent;
    err << tmpEvent << "现在输出一些文字" << eol;
}
```

### 2.3 可用日志流对象

- `dbg`：Debug
- `info`：Info
- `warn`：Warn
- `err`：Error
- `fatal`：Fatal

> 备注：为了避免与 Qt `QObject::event(...)` 命名冲突，日志事件类型统一使用 `kLogEvent`，不要在 Qt 类成员函数中使用裸 `event` 作为类型名。

---

## 3. eol 宏规范

- `eol` 是日志结束标记，必须作为一次日志表达式的结束部分。
- `eol` 自动采集：
  - `__FILE__`
  - `__LINE__`
  - `__FUNCTION__`
  - `__FUNCSIG__`（MSVC 下完整函数签名）
- 若没有 `eol`，日志不会提交到控制台与日志管理器。

---

## 4. 日志管理器规范

全局日志管理器对象：

```cpp
extern kEventEntry KswordARKEventEntry;
```

### 4.1 API 说明

- `void add(kEvent)`：追加一条日志（框架内部自动调用，业务层通常不手动调）。
- `void clear()`：清空全部日志。
- `bool Save(std::string path)`：导出全部日志到文件（TSV：`\t` 分隔字段，`\n` 分隔行）。
- `std::vector<kEvent> Track(GUID)`：按 GUID 返回关联日志。
- `std::vector<kEvent> Snapshot()`：返回全部日志快照。
- `std::size_t Revision()`：返回日志版本号（用于 UI 增量刷新）。

### 4.2 导出内容字段顺序

1. 等级（Level）  
2. 时间（Time）  
3. GUID  
4. 内容（Content）  
5. 文件（File）  
6. 函数（Function）

---

## 5. 图形界面日志面板规范

- “日志输出”Dock 使用 `LogDockWidget`。
- 功能包括：
  - 等级筛选（Debug/Info/Warn/Error/Fatal）
  - 右键复制单元格/复制行/跟踪事件
  - 追踪状态下右键变为“取消追踪”
  - 导出日志 / 清空日志（双确认）/ 复制可见
  - 保持滚动到底端

---

## 6. 代码风格要求（本模块）

- 新增日志代码必须保持“kLogEvent + 流式 + eol”调用格式。
- 业务日志建议优先 `info/warn/err`，避免滥用 `fatal`。
- 涉及并发输出必须通过框架提供对象，不得直接多线程写 `std::cout`。

---

## 7. 进度条管理规范（kProgress）

全局进度管理器对象：

```cpp
extern kProgress kPro;
```

### 7.1 新增任务

```cpp
// add 返回 PID（后续 set/UI 都依赖该 PID）。
int pid = kPro.add("任务1", "步骤1");
```

### 7.2 更新步骤与进度

```cpp
// progress 既支持 0~1（如 0.70f），也支持 0~100（如 70.0f）。
kPro.set(pid, "步骤2", 0, 70.0f);  // 显示 70%
```

> 约定：当 `progress` 归一化后等于 `1.0f` 时，该任务卡片会从“当前操作”列表隐藏。

### 7.3 阻塞式按钮选择

```cpp
// 返回值从 1 开始，对应点击了第几个选项按钮；取消返回 0。
int choice = kPro.UI(pid, "请选择你的操作", "选项A", "选项B", "选项C");
```

> `UI(...)` 弹窗期间会临时隐藏该任务的进度条，选择完成后自动恢复显示。

---

## 8. Ksword Win32 工具封装规范（进程模块）

### 8.1 目录与命名空间约定

- 根目录提供统一入口头文件：`Ksword.h`
- 具体实现放在：`ksword/` 递归目录
- 命名空间统一使用小写前缀：`ks::...`
- 每一级命名空间目录必须有同名头文件逐级向上包含，例如：
  - `ksword/process/process.h`
  - `ksword/ksword.h`（包含 `process.h`、`string.h`）
  - `Ksword.h`（包含 `ksword/ksword.h`）

### 8.2 Framework 入口规则

- `Framework.h` 必须包含 `Ksword.h`，作为全项目统一入口。
- 项目源码文件（`.h/.cpp`）统一优先包含 `Framework.h`，避免跨模块直接散乱引入系统头。

### 8.3 调用示例

```cpp
#include "Framework.h"

// 1) 按策略枚举进程
std::vector<ks::process::ProcessRecord> processList =
    ks::process::EnumerateProcesses(ks::process::ProcessEnumStrategy::Auto);

// 2) 获取某 PID 的路径
std::string imagePath = ks::process::QueryProcessPathByPid(1234);

// 3) 操作进程（示例：挂起）
std::string detail;
bool ok = ks::process::SuspendProcess(1234, &detail);
```

### 8.4 ProcessDock 交互规范

- 进程列表刷新必须走异步任务（线程池），禁止阻塞 UI 线程。
- 进程 identity 使用：`PID + creationTime100ns`。
- 若 identity 相同，则复用上一轮静态详情（路径、签名、命令行、用户等），性能计数器除外。
- 新增进程行高亮绿色；退出进程保留一轮并高亮灰色。
