# task_guard_agent **Repository Path**: being_xyk/task_guard_agent ## Basic Information - **Project Name**: task_guard_agent - **Description**: TaskGuard 是一个 Windows 桌面 GUI 应用,用 Electron 包装,用于监控长时运行进程的日志进度与系统资源指标。 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-06-28 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TaskGuard v2 TaskGuard 是面向 Coding Agent 的 Windows 本地进程监视工具,由 Skill、CLI、常驻服务和本地前端组成。一个监视任务可接入多个已有进程和多个独立日志源,提供资源指标、日志与事件。TaskGuard 不负责启动被监视软件。 ## 使用 将完整发布包 `taskguard-windows` 复制到所用 Agent 的用户级 Skill 目录。发布包包含便携 Python 和运行依赖;仓库中的源码目录不是完整发布包。安装与更新细节见 `.agents/skills/taskguard-windows/references/installation.md`。 要求 Agent 监视已有进程时,Agent 会启动前端并给出地址,查询已有任务和系统进程,等待用户确认一个或多个进程及可选日志路径后开始监视。也可以在前端多选。进程与日志不要求对应;日志分别查看,无日志时仍可查看指标。 成员与日志源均可手动增减;移除成员不结束进程,最后一个成员移除后保留空任务。同一进程身份只能属于一个监视任务,同名新进程不会自动加入。 前端仅提供移除监视,不提供结束进程操作。创建任务的名称默认使用搜索词,可自行修改;在任务中添加进程时默认优先搜索该任务运行成员的进程名称,取不到时回退任务名称。选中进程后行内按钮与确认区清单均提供「移除」;已加入当前任务的进程显示为选中且不可重复选择,已被其他任务监视的进程弱化禁选。软件重启后可在原任务内手动补加,日志配置与退出记录保留。日志源默认显示简短名称,悬停可查看完整路径。 停止监视只停止采集并保留历史;停止进程只结束选定的已加入成员,不递归结束未加入的子进程,须由用户明确要求。 ## 分析归属 TaskGuard 只提供可验证事实:任务与成员状态、采样指标、事件诊断包和按来源的有界日志。产品不调用任何 LLM,不提供模型配置、智能摘要或服务端定时总结。 异常或“最近发生了什么”由调用方 Agent 在提问时分析:Agent 先读 `status` 与 `events`,再按明确来源读取有界日志,由自身模型解释。跨轮次关注使用事件游标增量收取,避免重复总结旧事件。未来若增加聚合,只允许只读、确定性的 digest,不改变这一边界。 ## 工程结构 - `.agents/skills/taskguard-windows/`:Skill、CLI、服务和前端源码,也是发布包来源。 - `Document/`:需求、架构、设计和变更记录。 - `SourceCode/`:供测试使用的独立模拟软件。 - `test/` 与 `scripts/`:自动化测试、质量检查和打包。 开发运行需要 Windows、Python 3.11 和项目 `.venv`。依赖安装与架构细节见 `Document/plan-integration.md`;工程约束和工作流入口见 `AGENTS.md`。 开发环境打开界面使用以下入口,服务与数据位于项目 `.taskguard/`: ```powershell .\.agents\skills\taskguard-windows\scripts\dev.ps1 ui ``` 正式需求见 `Document/spec.md`,交互设计见 `Document/ux/design.md`,已归档变更从 `Document/archive/INDEX.md` 检索。 当前数据与接口设计见 `Document/changes/design-0001.md`,模块职责见 `Document/plan-runtime.md`。`watch_tasks` 保存任务容器,`task_members` 保存进程身份与独立状态,`task_log_sources` 保存独立日志来源。旧任务迁移保留 task_id 与历史事件。 ```text Watch Task ├─ Process Member × 0..N → PID + process_start_time └─ Log Source × 0..N → path + source_id + cursor ``` 接入时保存首帧指标;后续采样与成员操作不等待 Windows 通知发送。任务状态区分运行中、部分结束、部分异常、已结束、无监视进程和已停止监视;未知退出原因不等同于崩溃。 日志文件修改时间独立轮询,任务查询使用缓存,避免外部日志 I/O 拖慢指标查询。前端连接恢复时重新同步任务与事件,忽略晚到的旧请求结果;接入成功后立即打开返回的任务详情,后台同步列表。 ## 验证 ```powershell .\.venv\Scripts\python.exe -m pytest test -q .\.venv\Scripts\python.exe scripts\build_skill.py --check .\.venv\Scripts\python.exe scripts\quality.py .\.venv\Scripts\python.exe scripts\acceptance.py ``` Windows 集成测试需要独占 TaskGuard 单实例锁,各验证命令须串行执行。已有服务运行时,先安排监视空档并停止服务;测试结束后恢复服务并核对既有任务。完整发布包及离线验收命令见 `Document/plan-integration.md`。 多进程接入与独立日志源:重复使用 `attach --pid` 和 `--log`,通过 `member-add/member-remove` 与 `source-add/source-remove` 管理。TaskGuard 不启动被监视程序;多日志时通过 `logs --source` 分别查看。结束进程需要 `stop --confirm`。 新会话实际验收入口见 `Document/S5-acceptance.md`。测试设施独立启动模拟软件,再调用公共 CLI 接入;长时场景由测试负责结束,不使用产品 launch。