harness-boundary

Harness 工程边界约束

概述

本文档定义了 tauri-km 项目的工程边界约束系统，用于确保 Agent 在执行任务时遵循一致的工程规范，防止执行偏差。

边界层级

第一层：上下文装配

Agent 接收的上下文按以下优先级组装：

1. AGENTS.md — 项目级工程规则（最高优先级）
2. Skill 文件 — 领域知识和操作规范
3. Prompt 模板 — 任务执行和审查模板
4. 代码注释 — 行级上下文

第二层：工具治理

前端工具

工具	风险等级	审批要求
useStateExtend	低	无需审批
useCacheValue	低	无需审批
LogOrErrorSet	低	无需审批
Tauri invoke	中	需确认命令存在
DOM 操作	高	仅限 get_real_dom_text

Rust 端工具

工具	风险等级	审批要求
headless_chrome	高	需超时机制
reqwest	中	需通过 Tauri HTTP 插件
文件系统	高	限制在应用目录
spawn_blocking	低	标准用法

第三层：安全边界

代码安全

• 禁止硬编码敏感信息（access_token、密码等）
• 禁止绕过 Tauri 权限系统
• 禁止在生产代码中使用 console.log
• 禁止使用 any 类型

运行时安全

• 浏览器操作必须有超时机制
• 文件操作限制在 km-temp 和应用数据目录
• 网络请求通过 Tauri HTTP 插件代理
• 数据库操作使用参数化查询

数据安全

• 配置文件不提交版本控制
• Cookie 数据加密存储
• 错误日志脱敏处理

第四层：反馈机制

错误反馈

错误发生 → LogOrErrorSet 记录 → 前端展示 → Agent 诊断

状态反馈

操作开始 → Loading 状态 → 操作完成 → 结果展示

日志反馈

关键操作 → push_web_log → RenderLogs 组件展示

第五层：熵管理

规则维护

• AGENTS.md 每月审查一次
• Skill 文件随业务变更同步更新
• Prompt 模板根据使用反馈迭代

代码质量

• 定期运行 pnpm lint 检查代码规范
• 定期运行 pnpm ts:check 检查类型安全
• 新增功能必须有对应的类型定义

边界违规处理

严重违规（阻断执行）

• 使用 any 类型且无注释说明
• 硬编码敏感信息
• 绕过 Tauri 权限系统
• 浏览器操作无超时

中等违规（警告提示）

• 未使用 LogOrErrorSet 记录错误
• 未在 lib.rs 注册新命令
• 未遵循 UnoCSS 样式规范
• 组件内定义子组件

轻微违规（建议改进）

• 代码注释不足
• 函数过长（>100行）
• 命名不符合规范
• 未使用路径别名

变更影响评估矩阵

影响范围评估

变更类型	前端影响	Rust 端影响	数据库影响	配置影响
新增页面组件	✅	❌	❌	❌
修改业务逻辑	✅	❌	❌	❌
新增 Tauri 命令	✅	✅	❌	❌
修改 Tauri 命令	✅	✅	❌	❌
数据库表结构变更	✅	✅	✅	❌
配置文件格式变更	✅	❌	❌	✅
新增依赖	✅	✅	❌	❌

风险等级

• 低风险: 修改 UI 样式、添加日志、优化代码结构、更新注释
• 中风险: 修改业务逻辑、新增前端组件、修改错误处理、更新依赖版本
• 高风险: 修改 Tauri 命令接口、数据库表结构变更、修改安全相关代码、修改浏览器自动化逻辑
• 极高风险: 修改权限配置、修改认证流程、修改数据加密方式、修改网络请求代理

同步变更检查

变更场景	需要同步变更的内容
新增 Tauri 命令	lib.rs 注册 + 前端 invoke 调用
修改 Tauri 命令参数	lib.rs + 前端调用处
新增数据库字段	表结构 + 数据模型 + 读写逻辑
修改配置格式	配置文件 + 读取逻辑 + 类型定义
新增页面	路由自动发现 + 布局集成

常见变更场景

场景 1: 新增 Amazon 解析字段

1. 修改 amazon_action/utils.ts 添加解析函数
2. 修改 amazon_product 表添加字段
3. 修改 CDatabase 子类的字段映射
4. 修改比对引擎添加新字段比较
5. 更新前端展示组件

场景 2: 新增 Shopify 操作

1. 在 shopify_mod.rs 添加新命令
2. 在 lib.rs 注册命令
3. 在 ShopifyStoreAction 添加前端调用
4. 添加错误处理和日志记录
5. 更新 UI 操作入口

场景 3: 修改比对逻辑

1. 修改 compare.ts 比对算法
2. 确认影响的比对维度
3. 更新比对结果类型（如需要）
4. 测试各种边界场景
5. 更新相关文档