Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (76 loc) · 9.86 KB

AGENTS.md

File metadata and controls

97 lines (76 loc) · 9.86 KB
Raw

AGENTS.md

本文件适用于 taskmgr-rs 全仓库。目标是可信、响应流畅的经典 Windows 任务管理器；保持原生 Win32 布局、交互和菜单，除非用户明确要求改变。

工作方式与边界

  • 依据用户当前请求与已确认上下文完成端到端工作，包括实现、相关验证和修复由本次改动造成的问题。已授权范围内的本地修改、构建和测试无需逐步再次确认。
  • 先读取任务直接涉及的模块、调用者和测试；仅在涉及相关边界时扩展阅读，不要求每次修改前通读仓库或所有文档。
  • 通过检查代码和环境解决可发现的问题。仅在答案会实质改变需求、兼容性或影响范围时询问用户；常规实现选择自行判断并说明必要假设。
  • 用户的新补充是对当前任务的调整；保留已完成工作，继续到约定完成标准，不能以第一版实现或单次编译代替交付。
  • 遵守运行环境的指令层级和权限。仓库指南不能覆盖用户的明确范围；如某条指南导致停工、请求确认或偏离任务，指出具体条款和原因，不扩大解释。
  • 只修改任务所需内容，保留他人未提交改动；禁止破坏性重置和覆盖。仅在任务明确要求时 commit、push、创建 PR 或发布。
  • 只有运行环境允许且独立子任务能改善结果时使用并行协作；避免重叠编辑，主执行者负责整合和复核，不以子任务完成代替最终验收。
  • 沟通以结果、证据和剩余事项为主，简洁清楚；失败和未验证项如实说明。

工具链与定位入口

  • Rust 版本、组件和目标以 rust-toolchain.toml、Cargo.toml 和 Cargo.lock 为准。不得顺便升级依赖或追逐最新版本；确需升级时说明理由并同步锁文件。
  • 程序式 Win32 调用用 windows-sys；COM/Direct2D 用 windows。优先官方 API；新增依赖需说明现有工具为何不足及许可证影响。
  • 支持范围与实测证据见 兼容性矩阵。变更平台接口时读取它；新增兼容路径必须有明确状态和测试，不能用静默 fallback 掩盖失败。
  • 构建、诊断与资源操作参见 README；仅在相关任务中读取具体章节。
入口 职责
src/app/ 组合根、消息循环、长期控制器、页面与菜单生命周期
src/infrastructure/ 有界 worker、句柄 RAII、FFI、错误与诊断
src/system/ CPU/内存采样、拓扑、稳定进程身份
src/pages/ 各页快照、模型、绘制与交互；进程操作集中在 processes/actions
src/ui/、localization/ 控件、图表、资源 ID 与全部语言文案
src/config/options.rs 注册表二进制配置、校验与迁移
build.rs、build_support/ 本地化生成、资源清单与图像构建

依赖从组合层到页面，再到基础设施；基础模块不能依赖具体页面或 App。只有独立生命周期、跨页不变量或可独立演进的职责需要拆模块，不按类型数量拆文件。

进程身份、线程与快照

  • 跨枚举保存的进程使用 ProcIdentity { pid, creation_time_100ns }。CPU delta、缓存、选择和“转到进程”不能只使用 PID。
  • 结束进程/树、修改优先级/亲和性、调试、打开文件位置前，用 open_process_for_identity 重新校验身份并请求最小权限。身份未知时禁用危险操作，不能退回 PID-only 路径。
  • 窗口操作同时验证 HWND、线程 ID 和进程身份；会话操作验证会话身份。结束树先验证并打开目标，再执行，部分失败必须如实报告。
  • UI 线程只做消息分发、轻量提交、布局和绘制。进程、token、WTS、IP Helper、图标及系统查询在持久后台 worker 执行。
  • 使用 SingleFlightWorker 的有界通道和 pending 合并，不每 tick 建线程。来源状态、generation 与乱序校验由所属页面负责。
  • worker 构造候选快照，必要查询成功后原子提交；全局失败保留上一轮可信快照与错误，不清空列表、不在 UI 线程补采样。行级失败保留其它行并通过 row_error 报告。
  • 丢弃过期或页面销毁后的结果；worker 有序停止，不能访问已销毁窗口。
  • 架构判断区分主机、目标进程和观察者架构；非 WOW64 不等于原生。缓存成功的架构结果，不把未知或不可访问当成原生。

资源、FFI 与错误

  • 拥有的 HANDLE、图标、位图、DC、菜单、ImageList、COM 等资源必须有唯一所有者和对应释放路径，优先 RAII；系统借用对象不得释放。
  • GDI 对象删除前恢复原选择；BeginDraw/EndDraw 和 DC 获取/释放成对。主窗口借用页面菜单，销毁前先解绑。
  • 新资源先完整创建再替换旧资源；初始化中途失败自动清理。资源随所属页面、窗口或 worker 生命周期释放，不每次刷新重建。
  • unsafe 保持局部，说明非显然的指针寿命、缓冲区对齐/长度、线程和所有权前提；不能靠 transmute、伪造生命周期、宽泛 allow 或全局可变状态绕过约束。
  • FFI 长度和转换兼顾 32/64 位及符号范围；区分 NULL、INVALID_HANDLE_VALUE 和各 API 特有失败值。异步通知传稳定 ID 或拥有的数据。
  • Win32 失败后立即读取 GetLastError，仅在 API 定义使用它时读取；零错误码转为明确通用错误。HRESULT、NTSTATUS、Win32 和 PDH 保持各自错误域。
  • 未知、失败、过期与真实零值必须区分。合理降级在类型、状态或 UI 中可见，不能伪造成功或把旧结果标为新数据。
  • 后台重复错误去重，用户操作失败即时反馈。不得丢弃诊断原因，或添加无限重试、隐式休眠、未经证明的备用 API 链。

数值、缓存与界面

  • 内存、commit、工作集和网络字节使用 u64；百分比跨乘法用 u128。计数器 delta 处理首次采样、回退、重置、溢出和零间隔，失败不推进基线。
  • processor group 操作必须 group-aware；无法表达的亲和性限制明确报告。饱和运算只用于具有明确语义的显示边界。
  • 性能修改应由测量或复杂度证据支持，优先移除 UI 阻塞、重复查询和全量重建；不要混入无关优化。
  • 历史用 ring buffer，大列表用虚拟 ListView，只格式化活动列、重绘可见变更。缓存明确 key、所有者与失效条件；避免额外共享锁及无界增长。
  • 切页先准备目标页面和菜单再切换，失败保留旧页；刷新保持身份有效的选择、焦点与滚动位置。预热不抢焦点或弹操作对话框。
  • 新文案进入 TextKey 和全部 locale TOML；修改名称同步排序键和相关文本。新菜单项具备唯一资源 ID、命令路由、状态与帮助文本，分隔线显式建模。

配置、资源与源码维护

  • Options 是 #[repr(C)] 注册表二进制结构；未经迁移不得重排、删除或改变字段类型。读取先校验大小、类型、范围、列集合、窗口矩形及 flags。
  • 进程列包含唯一主列、无重复项、合法 sentinel 和宽度；配置规范化集中且可测试。
  • 编辑本地化键源和 TOML，不改 OUT_DIR 生成文件。图像源只用 PNG/BMP，提供 README 要求的全部尺寸；禁止构建时缩放或猜测替代尺寸。
  • ICO 只由构建管线生成到 OUT_DIR，最终 EXE 嵌入标准图标资源。资源变更同步清单、ID、重建触发和资源测试；构建错误明确终止。
  • 新建或结构性重构的手写源码使用现有横幅格式，注明职责、仓库相对路径、实际日期/环境和作者；Codex 写作署名 OpenAI Codex。Rust 再用模块文档说明不变量和生命周期。
  • 普通局部修改不刷新文件头，不为补头制造无关 diff。环境与版本必须实测，Windows 记录构建号；配置、图像和生成文件使用原生格式。
  • 不提交 target、artifacts、dist、临时日志或 IDE 状态。

验证与完成标准

测试按本次变更风险选择，不为纯文案、可逆低风险改动添加镜像实现的测试。架构识别、身份校验、计数器、配置和 FFI 解析等逻辑应覆盖真实边界及失败路径。

代码变更先运行相关测试，再完成以下检查一次；后续仅因新变更、失败或未解决疑点重跑受影响检查。纯文档修改检查事实、链接与 diff 即可。

cargo fmt --all -- --check
cargo check --all-targets --locked
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo build --release --locked
git diff --check
  • 涉及架构的变更显式指定并检查 i686、x86_64、aarch64 Windows MSVC 目标。正常 release 可用 scripts/release-clean.ps1，不默认启用 nightly/build-std。
  • 运行会创建进程、窗口、文件或修改配置的测试前，确认目标是受控测试对象。既有授权覆盖测试与相关失败修复，不扩大到用户业务进程或生产服务。
  • 用户要求真实运行时，在约定 Windows 环境启动最终构建、检查受影响界面和操作、修复问题后再验收。UI/资源变更按影响验证刷新、切页、选择、退出及句柄生命周期。
  • 无法执行的检查记录原因、已做的替代验证和剩余风险；区分编译证据、自动测试、真实运行与 UI 证据。不得把交叉编译或虚拟机测试写成所有设备已验证。
  • 完成意味着请求的真实路径已解决，身份/线程/资源/错误不变量保持，必要检查通过，文档与本地化同步，最终 diff 聚焦；发现受环境阻碍的验收项应明确标注。

本文件按 OpenAI 的 Astra 工程建议与模型指导整理：减少重复约束，按需读取，以适当验证和完成标准驱动持续执行。