契约自治实验档案 jeffkxt/lcrd-agent-figma-lite

lcrd‑agent‑figma‑lite

LCRD 契约式自治 Agent 实验・Figma‑Lite 轻量矢量编辑器

GitHub 仓库描述：LCRD 自治 Agent 实验：Figma‑Lite 矢量编辑器，完整原始 DSH 会话日志 V1.0‑V1.6，169 个测试用例零回归

项目概述

这不是普通 AI 一键生成的演示 Demo。
本项目是一套契约式自治 Agent 工程实证实验，产出一个浏览器直接运行的轻量矢量编辑器，同时完整留存每一轮 Agent 的原始执行证据。

实验模式说明

1. 人类只输出：问题现象 + 可自动化验证的验收标准，不提供实现思路、不写具体代码；
2. Agent 自主完成：读取源码、定位根因、增量修改、编写专项单元测试、执行全量回归、生成交付报告；
3. 全量日志归档：全部会话原始日志完整归档，无人工篡改、无事后润色，可供复现与审查；
4. 零回归约束：新增功能不得破坏历史功能，所有旧单元测试必须全部通过，强制零回归。

💡 成本说明：Token 开销绝大部分消耗在代码探测、边界案例处理、回归校验、报告归档，并非单纯生成代码文本；物料成本低廉，核心人力成本集中在定义问题与验收契约。

Agent 运行环境

本仓库整套契约式自治 Agent 实验，全部在以下环境中实际跑通，并依靠 LCRD 插件 作为执行护栏完成每一轮迭代：

| 组件 | 说明 |
| 大模型 | DeepSeek Flash V4 0813 版本（MAX 规格） |
| Agent 工具 | DeepSeek‑Harness（DSH），标准模式 |
| 执行护栏插件 | LCRD —— Limit‑Condition‑Restrict‑Detect（限制‑条件‑约束‑检测）硬隔离协议插件，运行在 DeepSeek‑Harness 之上，作为 DSH 的扩展插件生效 |

- LCRD 角色：在 Agent 每一次「读源码 → 定位根因 → 增量修改 → 编写专项测试 → 全量回归 → 生成报告」的自治闭环中，由 LCRD 插件做硬隔离式执行护栏——对修改范围、条件边界、约束合规、回归检测进行强制拦截与校验，是本项目能够实现「新增功能不破坏历史功能、169 个断言零回归」的关键机制。
- 各版本目录下的 log/（DeepSeek Harness 导出的原生会话日志）即为在该环境 + LCRD 护栏下产生的原始执行证据，未人工删减改写。

📌 本仓库的实验结论（契约式自治、零回归、原始日志可复现）均基于上述 DeepSeek Flash V4 0813 MAX + DeepSeek‑Harness 标准模式 + LCRD 插件 环境得出；在其他模型 / Agent 工具链上复现，结果可能不同。

运行方式

无需编译、无需依赖安装。
直接双击打开 FigmaV1.6/index.html，浏览器即可开箱使用，内置演示画布。

执行全套回归测试（Node.js环境）
cd FigmaV1.6
node tests/run-tests.mjs
node tests/drag-tests.mjs
node tests/pen-boolean-tests.mjs
node tests/pen-handle-tests.mjs
node tests/style-grid-svg-tests.mjs
node tests/vector-dblclick-tests.mjs

当前版本状态：V1.6

✅ 冻结迭代，暂缓 V1.7 开发；V1.7 需求契约已留存，等待后续开启。

V1.6 已实现能力

- 画布：无限画布，滚轮以光标缩放 5%‑2000%，空格 / 中键平移画布；自适应点阵网格吸附（G 快捷键切换）
- 基础工具：选择、矩形、椭圆、文本、画笔、钢笔贝塞尔曲线
- 钢笔工具：拖拽生成手柄、手柄持久化、手柄拖拽编辑、闭合轮廓、双击线段加锚、双击锚点删锚，退化路径安全守卫
- 布尔运算：合并、减去顶层、相交、排除，支持孔洞多轮廓，操作支持撤销重做
- 描边系统：strokeDash虚线、strokeCap端点、strokeJoin连接；属性面板配置；JSON/localStorage 持久化
- 导出：选中图形导出标准 SVG，支持贝塞尔、虚线、填充奇偶规则、文本
- 数据持久化：防抖自动 localStorage 保存，JSON 导入导出画布文档
- 历史栈：撤销 / 重做完整覆盖绝大多数编辑操作
- 测试：共 6 套测试套件，合计 169 条断言全部通过，零回归

V1.6 已知限制

1. 双击插入锚点不会重参数化原始贝塞尔曲线，行为对齐 Figma 原生表现；
2. 网格开关属于视图状态，不会序列化存入文档 JSON；
3. 文本描边仅数据字段与 SVG 导出生效，属性面板暂未开放控件；
4. 暂未实现：框选多选、Z 轴层级、复制粘贴、填充规则 UI 面板（规划 V1.7）。

快捷键一览

| 按键 | 功能 |
| V | 选择工具 |
| R | 矩形工具 |
| E | 椭圆工具 |
| T | 文本工具 |
| B | 画笔工具 |
| G | 网格吸附开关 |
| 空格 + 拖拽 / 鼠标中键 | 平移画布 |
| 鼠标滚轮 | 以光标为中心缩放画布 |
| Ctrl+Z | 撤销 |
| Ctrl+Y / Ctrl+Shift+Z | 重做 |

仓库目录结构

lcrd‑agent‑figma‑lite/
├── LICENSE
├── CITATION.cff
├── FigmaV1.0/ # V1.0 完整自包含产物 + dsh‑full‑logs原始会话日志 ├── FigmaV1.1/ # V1.1 完整自包含产物 + dsh‑full‑logs原始会话日志 ├── FigmaV1.2/ # V1.2 完整自包含产物 + dsh‑full‑logs原始会话日志 ├── FigmaV1.3/ # V1.3 拖拽漂移bug根治 ├── FigmaV1.4/ # V1.4 钢笔+布尔运算 ├── FigmaV1.5/ # V1.5 贝塞尔手柄修复 ├── FigmaV1.6/ # ✅ 当前稳定版本 │ ├── app.js │ ├── index.html │ ├── tests/ # 全部单元测试套件 │ ├── docs/ # 版本交付报告 │ └── dsh‑full‑logs/ # DSH原始完整会话日志（未人工修改，部分zip归档） └── whole‑process‑notes/ ├── total‑token‑stat.md # 各轮迭代token消耗统计表 ├── paradigm‑summary.md # 契约式自治工程范式总结 └── pitfall‑record.md # 踩坑记录（jsdom仿真欺骗性、LCRD工具校验问题等）

📌 重要说明：
- 每一个 FigmaVx.x 文件夹自闭环独立可复现，内含该版本源码、测试、交付总结、DSH 原始会话日志。
- dsh‑full‑logs 为 DeepSeek Harness 导出原生会话，没有人工删减改写；日志体量较大，部分轮次使用 zip 归档。
- 阅读建议：先看对应版本内 docs/report.md 交付总结，再按需查阅完整原始日志。

各轮迭代简要记录

| 版本 | Token 消耗 | 任务简述 | 结果 |
| V1.0 | 1700 万 | 搭建完整编辑器脚手架：无限画布、基础工具、图层、撤销重做、JSON 存储 | ✅ 成功 |
| V1.1 | 760 万 | 基础拖拽交互修复 | ⚠️ 未完成，迭代到 V1.2 |
| V1.2 | 520 万 | 拖拽交互专项修复 | ⚠️ 未完成，迭代到 V1.3 |
| V1.3 | 2270 万 | 根治 pointermove 事件累加导致拖拽漂移；揭示 jsdom 仿真环境欺骗性 | ✅ 成功 |
| V1.4 | 2400 万 | 实现钢笔工具、布尔矢量运算，带面积独立断言验证 | ✅ 成功 |
| V1.5 | 1230 万 | 修复钢笔首锚贝塞尔手柄无法持久保存、选中不渲染手柄问题 | ✅ 成功 |
| V1.6 | 2760 万 | 描边样式、网格吸附、SVG 导出、双击锚点鲁棒边界处理，169 个断言全绿 | ✅ 成功 |

📊 Token 统计说明：包含文件读写、探针调试、多次回归测试、报告生成，不是纯代码生成 Token。

实验反思

1. 仿真环境局限性：jsdom 等仿真测试环境的行为会与真实浏览器存在差异，部分 bug 只有真实浏览器才暴露，单靠 jsdom 会掩盖问题；
2. 契约是核心成本：自治 Agent 的成本不在代码生成，而在完备的验收契约、单元测试回归底座；契约模糊会直接造成 Agent 行为漂移；
3. 日志价值大于产物：原始会话日志价值远高于最终产物，可以观察 Agent 规划、犯错、排错、修复的完整思考链路。

声明

⚠️ 本项目属于工程原型实验，不建议直接用于生产环境。
DSH 原始会话日志仅用于研究自治 Agent 行为，不代表模型最佳实践。

许可证

MIT License

引用

如果你的研究、文章引用该项目，请使用仓库内 CITATION.cff。

Issue 模板

本仓库为契约式自治 Agent 工程实验原型，欢迎提交以下类型的 Issue：

- 🐛 Bug 报告：描述复现步骤与预期行为
- 💡 范式讨论：关于契约式自治 Agent 工程方法的探讨
- 📊 实验复现：尝试复现实验过程并记录发现

注意：本项目目前处于 V1.6 冻结状态，新功能需求请标记为 future-consideration。