skycurtain/structrail-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 优化开发规则与项目介绍文档的表述

Browse Source 
- 移除关于禁止修改源代码的临时限制说明，该限制已不再适用
- 统一并优化多处中文标点与空格的格式，使文档更整洁
- 调整项目介绍中关于协议设计的表述，使其更清晰准确
- 合并`tracer-type.md`中的分隔线，使列表结构更紧凑
This commit is contained in:
skycurtain
2026-03-02 21:06:36 +08:00
parent 19d4b97669
commit 2dfc4ced67
3 changed files with 5 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.trae/rules/development-rules.md
View File

@@ -1,7 +1,6 @@
# 开发规则 # 开发规则
- **严禁主动修改任何项目源代码文件（如 .ts, .js, .c, .h 等）。当前工作仅限于文档编写（.md）和方案讨论。所有代码示例仅能在对话中展示，不得写入文件。** - 在设计协议和API时，我们需要考虑API的移植性，尤其需要特别关注C语言，因为C语言的语法表达力不算强。当然，各类主流的编程语言都需要纳入考虑范围，包括但不限于：
- 在考虑API的移植性时，需要特别考虑C语言，当然，各类主流的编程语言要需要纳入考虑范围，包括但不限于：
- C++ - C++
- Java - Java
- C# - C#

6
.trae/rules/project-introduction.md
View File

@@ -6,10 +6,10 @@
基于上述设想，我肯定无法接受从编译技术的角度去适配每一种编程语言(例如代码插桩甚至改造编译器)，因为这会导致平台的开发变得非常复杂，维护成本也会非常高。因此我的想法是设计一套语言无关的协议，用来描述各种数据结构的变化(跟踪器)，因此这套协议会定义需要支持的数据结构类型，以及每一种数据结构类型需要支持的操作指令，并且我倾向于将指令设计得更加“底层”一些，类似于“原语”的概念。 基于上述设想，我肯定无法接受从编译技术的角度去适配每一种编程语言(例如代码插桩甚至改造编译器)，因为这会导致平台的开发变得非常复杂，维护成本也会非常高。因此我的想法是设计一套语言无关的协议，用来描述各种数据结构的变化(跟踪器)，因此这套协议会定义需要支持的数据结构类型，以及每一种数据结构类型需要支持的操作指令，并且我倾向于将指令设计得更加“底层”一些，类似于“原语”的概念。
> 例如针对顺序表结构，我可能会定义 pick(获取元素)、drop(取消获取)、patch(修改元素) 指令来替代 swap(交换元素) 操作，因为交换两个元素的本质就是 获取元素 + 修改元素，而我在其中添加 drop 指令的目的则是使可视化过程更加具体，例如 pick 指令会将其选定的元素高亮，那么 drop 指令就可以取消该元素的高亮行为。 > 例如针对顺序表结构，我可能会定义pick(获取元素)、drop(取消获取)、patch(修改元素)指令来替代swap(交换元素)操作，因为交换两个元素的本质就是获取元素+修改元素，而我在其中添加rop指令的目的则是使可视化过程更加具体，例如pick指令会将其选定的元素高亮，那么drop指令就可以取消该元素的高亮行为。
我们会先选取一种编程语言(例如 TypeScript)来实现这套协议，在实现的过程中，需要考虑到未来将添加其他编程语言的支持，因此需要考虑到不同编程语言之间的差异，例如语法/类型系统差异，进而反过来优化这套协议，以使其能够更好地支持不同的编程语言，这是一个双向的过程。 我们会先选取一种编程语言(例如TypeScript)来实现这套协议，在实现的过程中，需要考虑到未来将添加其他编程语言的支持，因此需要考虑到不同编程语言之间的差异，例如语法/类型系统差异，进而反过来优化这套协议，以使其能够更好地支持不同的编程语言，这是一个双向的过程。
当我们实现了这套协议后，就形成了一套 SDK，用户可以在平台中标记想要记录的数据结构(注册跟踪器)，并调用 SDK 提供的 API 来记录数据结构的变化，当代码被编译运行后，就能够自然地获取数据结构的变化过程(序列化为 JSON)。 当我们实现了这套协议后，就形成了一套SDK，用户可以在平台中标记想要记录的数据结构(注册跟踪器)，并调用SDK提供的API来记录数据结构的变化，当代码被编译运行后，就能够自然地获取数据结构的变化过程(序列化为JSON)。
所以本项目的最终目标就是设计这一套语言无关的协议，并在多个主流编程语言上实现该协议。 所以本项目的最终目标就是设计这一套语言无关的协议，并在多个主流编程语言上实现该协议。

5
.trae/rules/tracer-type.md
View File

@@ -1,6 +1,6 @@
## Tracer 是什么？ ## Tracer 是什么？
Tracer 代表一个数据结构变化的跟踪器，用户可以通过调用 Tracer 提供的 API 来记录数据结构的变化。每当用户想要记录一个数据结构的变化时，就需要创建一个对应的 Tracer。这种将数据结构变化的记录留给用户的设计，使得用户可以在算法的实现中灵活地记录数据结构的变化，从而降低对原有算法代码逻辑的侵入性，同时也在一定程度上提高了可视化效果的灵活度，用户可以自由控制记录数据结构变化的时机。 Tracer代表一个数据结构变化的跟踪器，用户可以通过调用Tracer提供的API来记录数据结构的变化。每当用户想要记录一个数据结构的变化时，就需要创建一个对应的Tracer。这种将数据结构变化的记录留给用户的设计，使得用户可以在算法的实现中灵活地记录数据结构的变化，从而降低对原有算法代码逻辑的侵入性，同时也在一定程度上提高了可视化效果的灵活度，用户可以自由控制记录数据结构变化的时机。
## Tracer 类型 ## Tracer 类型
@@ -12,8 +12,5 @@ Tracer 代表一个数据结构变化的跟踪器，用户可以通过调用 Tra
- LinkTracer: 链表 - LinkTracer: 链表
- TreeTracer: 树 - TreeTracer: 树
- GraphTracer: 图 - GraphTracer: 图
---
- LogTracer: 日志 - LogTracer: 日志
- ControlTracer: 控制 - ControlTracer: 控制