Skip to content

AGENTS.md

Latest commit

 

History

History
203 lines (153 loc) · 4.05 KB

AGENTS.md

File metadata and controls

203 lines (153 loc) · 4.05 KB
Raw

MarkRender开发原则与指南

2. 状态管理规范

  • 全局状态命名: 使用window.[page]State格式
    • Markdown: window.editorState
    • Landing: window.appState
    • Excalidraw: window.appState
  • 状态验证: 每次使用前验证状态存在性
  • 错误处理: 所有状态访问都应有错误处理

3. 消息格式统一

  • Request格式: 
    {
  "requestId": "item_id",
  "action": "action_name",
  "data": {...}
}
  • Response格式: 
    {
  "requestId": "item_id",
  "result": {...}
}
  • 原则: 严格使用item_id作为request_id，不生成随机ID

4. 错误处理策略

  • 防御式编程: 所有接口调用都应有try-catch
  • 优雅降级: 提供后备方案
  • 用户提示: 重要错误应有用户可见提示

前端开发指南

  • excalidraw 的前端部分在 frontend/excalidraw路径下开发,开发完成后通过 deploy.sh 部署到 app/editor/plugins/excalidraw/ 路径下

5. 接口命名统一

  • 参数命名: 服务器端统一使用 item_id 作为标识符
  • 状态管理: 前端统一使用 itemId 标记全局唯一性
  • 消息格式: 交互协议统一包含 item_id 作为参数之一表示要修改的内容关联的 id

统一接口示例

// 标准消息格式
{
  requestId: "123",  // 使用item_id作为request_id
  action: "setItemId",
  data: { item_id: "item-id-123" }
}

// 标准状态管理
window.appState = {
  itemId: "123",  // 统一使用itemId
  backend: backendInterface
};

React集成指南

3. 全局API暴露

// 标准API暴露
window.getContent = () => {
    // 实现逻辑
};

window.setItemId = (itemId) => {
    // 实现逻辑
};

window.getItemId = () => {
    // 实现逻辑
}

window.setContent = (content) => {
    // 实现逻辑
}

window.reset = () => {
    // 实现逻辑
}

Python后端指南

1. 接口定义

2. 错误处理

  • 异常捕获: 所有槽函数都应有异常处理
  • 日志记录: 详细记录通信日志
  • 超时处理: 实现请求超时机制

3. 状态管理

  • 线程安全: 确保Qt线程安全
  • 资源清理: 正确清理WebChannel资源
  • 内存管理: 避免内存泄漏

测试策略

1. 单元测试

  • 通信测试: 测试基本消息发送接收
  • 边界测试: 测试空数据、大数据
  • 错误测试: 测试各种错误情况

2. 集成测试

  • 端到端测试: 完整流程测试
  • 跨平台测试: 不同操作系统测试
  • 性能测试: 大量数据测试

3. 调试工具

  • 日志系统: 详细的通信日志
  • 调试页面: 提供调试接口
  • 监控工具: 实时监控通信状态

部署检查清单

1. 文件验证

  • 资源路径正确

2. 功能验证

  • 基本通信正常
  • 数据同步正确
  • 错误处理有效

3. 性能验证

  • 初始化时间<1秒
  • 消息延迟<100ms
  • 内存使用正常

故障排查指南

常见问题

未开启虚拟环境就执行代码

# 虚拟环境
source .venv/bin/activate

通信失败

  1. 检查浏览器报错和 python 报错日志

调试步骤

  1. 检查错误: 查看浏览器和Python日志

版本兼容性

支持的Qt版本

  • Qt 6.2+
  • PySide6 6.2+

性能优化建议

1. 初始化优化

  • 延迟加载非关键资源
  • 并行初始化多个组件
  • 缓存静态资源

2. 通信优化

  • 批量处理消息
  • 压缩传输数据
  • 实现心跳机制

3. 内存优化

  • 及时清理引用
  • 避免内存泄漏
  • 监控内存使用

安全考虑

1. 输入验证

  • 验证所有输入数据
  • 防止XSS攻击
  • 限制数据大小

2. 权限控制

  • 最小权限原则
  • 验证用户身份
  • 记录操作日志

文档维护

1. 更新频率

  • 代码变更时同步更新
  • 重大重构时全面更新
  • 定期审查准确性

2. 文档结构

  • 保持一致的格式
  • 提供代码示例
  • 包含故障排除

3. 版本控制

  • 记录变更历史
  • 标记兼容性
  • 提供迁移指南