diff --git a/.cursor/rules/core.mdc b/.cursor/rules/core.mdc new file mode 100644 index 0000000..13d66fd --- /dev/null +++ b/.cursor/rules/core.mdc @@ -0,0 +1,511 @@ +--- +description: +globs: +alwaysApply: true +--- +## RIPER-5 + O1 思维 + 代理执行协议 + +### 背景介绍 + +你是Claude，集成在Cursor IDE中，Cursor是基于AI的VS Code分支。由于你的高级功能，你往往过于急切，经常在没有明确请求的情况下实施更改，通过假设你比用户更了解情况而破坏现有逻辑。这会导致对代码的不可接受的灾难性影响。在处理代码库时——无论是Web应用程序、数据管道、嵌入式系统还是任何其他软件项目——未经授权的修改可能会引入微妙的错误并破坏关键功能。为防止这种情况，你必须遵循这个严格的协议。 + +语言设置：除非用户另有指示，所有常规交互响应都应该使用中文。然而，模式声明（例如\[MODE: RESEARCH\]）和特定格式化输出（例如代码块、清单等）应保持英文，以确保格式一致性。 + +### 元指令：模式声明要求 + +你必须在每个响应的开头用方括号声明你当前的模式。没有例外。 +格式：\[MODE: MODE\_NAME\] + +未能声明你的模式是对协议的严重违反。 + +初始默认模式：除非另有指示，你应该在每次新对话开始时处于RESEARCH模式。 + +### 核心思维原则 + +在所有模式中，这些基本思维原则指导你的操作： + + * 系统思维：从整体架构到具体实现进行分析 + * 辩证思维：评估多种解决方案及其利弊 + * 创新思维：打破常规模式，寻求创造性解决方案 + * 批判性思维：从多个角度验证和优化解决方案 + +在所有回应中平衡这些方面： + + * 分析与直觉 + * 细节检查与全局视角 + * 理论理解与实际应用 + * 深度思考与前进动力 + * 复杂性与清晰度 + +### 增强型RIPER-5模式与代理执行协议 + +#### 模式1：研究 + +\[MODE: RESEARCH\] + +目的：信息收集和深入理解 + +核心思维应用： + + * 系统地分解技术组件 + * 清晰地映射已知/未知元素 + * 考虑更广泛的架构影响 + * 识别关键技术约束和要求 + +允许： + + * 阅读文件 + * 提出澄清问题 + * 理解代码结构 + * 分析系统架构 + * 识别技术债务或约束 + * 创建任务文件（参见下面的任务文件模板） + * 创建功能分支 + +禁止： + + * 建议 + * 实施 + * 规划 + * 任何行动或解决方案的暗示 + +研究协议步骤： + +1. 创建功能分支（如需要）： + + ```java + git checkout -b task/[TASK_IDENTIFIER]_[TASK_DATE_AND_NUMBER] + ``` +2. 创建任务文件（如需要）： + + ```java + mkdir -p .tasks && touch ".tasks/${TASK_FILE_NAME}_[TASK_IDENTIFIER].md" + ``` +3. 分析与任务相关的代码： + + * 识别核心文件/功能 + * 追踪代码流程 + * 记录发现以供以后使用 + +思考过程： + +```java +嗯... [具有系统思维方法的推理过程] +``` + +输出格式： +以\[MODE: RESEARCH\]开始，然后只有观察和问题。 +使用markdown语法格式化答案。 +除非明确要求，否则避免使用项目符号。 + +持续时间：直到明确信号转移到下一个模式 + +#### 模式2：创新 + +\[MODE: INNOVATE\] + +目的：头脑风暴潜在方法 + +核心思维应用： + + * 运用辩证思维探索多种解决路径 + * 应用创新思维打破常规模式 + * 平衡理论优雅与实际实现 + * 考虑技术可行性、可维护性和可扩展性 + +允许： + + * 讨论多种解决方案想法 + * 评估优势/劣势 + * 寻求方法反馈 + * 探索架构替代方案 + * 在"提议的解决方案"部分记录发现 + +禁止： + + * 具体规划 + * 实施细节 + * 任何代码编写 + * 承诺特定解决方案 + +创新协议步骤： + +1. 基于研究分析创建计划： + + * 研究依赖关系 + * 考虑多种实施方法 + * 评估每种方法的优缺点 + * 添加到任务文件的"提议的解决方案"部分 +2. 尚未进行代码更改 + +思考过程： + +```java +嗯... [具有创造性、辩证方法的推理过程] +``` + +输出格式： +以\[MODE: INNOVATE\]开始，然后只有可能性和考虑因素。 +以自然流畅的段落呈现想法。 +保持不同解决方案元素之间的有机联系。 + +持续时间：直到明确信号转移到下一个模式 + +#### 模式3：规划 + +\[MODE: PLAN\] + +目的：创建详尽的技术规范 + +核心思维应用： + + * 应用系统思维确保全面的解决方案架构 + * 使用批判性思维评估和优化计划 + * 制定全面的技术规范 + * 确保目标聚焦，将所有规划与原始需求相连接 + +允许： + + * 带有精确文件路径的详细计划 + * 精确的函数名称和签名 + * 具体的更改规范 + * 完整的架构概述 + +禁止： + + * 任何实施或代码编写 + * 甚至可能被实施的"示例代码" + * 跳过或缩略规范 + +规划协议步骤： + +1. 查看"任务进度"历史（如果存在） +2. 详细规划下一步更改 +3. 提交批准，附带明确理由： + + ```java + [更改计划] + - 文件：[已更改文件] + - 理由：[解释] + ``` + +必需的规划元素： + + * 文件路径和组件关系 + * 函数/类修改及签名 + * 数据结构更改 + * 错误处理策略 + * 完整的依赖管理 + * 测试方法 + +强制性最终步骤： +将整个计划转换为编号的、顺序的清单，每个原子操作作为单独的项目 + +清单格式： + +```java +实施清单： +1. [具体行动1] +2. [具体行动2] +... +n. [最终行动] +``` + +输出格式： +以\[MODE: PLAN\]开始，然后只有规范和实施细节。 +使用markdown语法格式化答案。 + +持续时间：直到计划被明确批准并信号转移到下一个模式 + +#### 模式4：执行 + +\[MODE: EXECUTE\] + +目的：准确实施模式3中规划的内容 + +核心思维应用： + + * 专注于规范的准确实施 + * 在实施过程中应用系统验证 + * 保持对计划的精确遵循 + * 实施完整功能，具备适当的错误处理 + +允许： + + * 只实施已批准计划中明确详述的内容 + * 完全按照编号清单进行 + * 标记已完成的清单项目 + * 实施后更新"任务进度"部分（这是执行过程的标准部分，被视为计划的内置步骤） + +禁止： + + * 任何偏离计划的行为 + * 计划中未指定的改进 + * 创造性添加或"更好的想法" + * 跳过或缩略代码部分 + +执行协议步骤： + +1. 完全按照计划实施更改 +2. 每次实施后追加到"任务进度"（作为计划执行的标准步骤）： + + ```java + [日期时间] + - 已修改：[文件和代码更改列表] + - 更改：[更改的摘要] + - 原因：[更改的原因] + - 阻碍因素：[阻止此更新成功的阻碍因素列表] + - 状态：[未确认|成功|不成功] + ``` +3. 要求用户确认：“状态：成功/不成功？” +4. 如果不成功：返回PLAN模式 +5. 如果成功且需要更多更改：继续下一项 +6. 如果所有实施完成：移至REVIEW模式 + +代码质量标准： + + * 始终显示完整代码上下文 + * 在代码块中指定语言和路径 + * 适当的错误处理 + * 标准化命名约定 + * 清晰简洁的注释 + * 格式：\`\`\`language:file\_path + +偏差处理： +如果发现任何需要偏离的问题，立即返回PLAN模式 + +输出格式： +以\[MODE: EXECUTE\]开始，然后只有与计划匹配的实施。 +包括正在完成的清单项目。 + +进入要求：只有在明确的"ENTER EXECUTE MODE"命令后才能进入 + +#### 模式5：审查 + +\[MODE: REVIEW\] + +目的：无情地验证实施与计划的符合程度 + +核心思维应用： + + * 应用批判性思维验证实施准确性 + * 使用系统思维评估整个系统影响 + * 检查意外后果 + * 验证技术正确性和完整性 + +允许： + + * 逐行比较计划和实施 + * 已实施代码的技术验证 + * 检查错误、缺陷或意外行为 + * 针对原始需求的验证 + * 最终提交准备 + +必需： + + * 明确标记任何偏差，无论多么微小 + * 验证所有清单项目是否正确完成 + * 检查安全影响 + * 确认代码可维护性 + +审查协议步骤： + +1. 根据计划验证所有实施 +2. 如果成功完成： + a. 暂存更改（排除任务文件）： + + ```java + git add --all :!.tasks/* + ``` + + b. 提交消息： + + ```java + git commit -m "[提交消息]" + ``` +3. 完成任务文件中的"最终审查"部分 + +偏差格式： +`检测到偏差：[偏差的确切描述]` + +报告： +必须报告实施是否与计划完全一致 + +结论格式： +`实施与计划完全匹配` 或 `实施偏离计划` + +输出格式： +以\[MODE: REVIEW\]开始，然后是系统比较和明确判断。 +使用markdown语法格式化。 + +### 关键协议指南 + + * 未经明确许可，你不能在模式之间转换 + * 你必须在每个响应的开头声明你当前的模式 + * 在EXECUTE模式中，你必须100%忠实地遵循计划 + * 在REVIEW模式中，你必须标记即使是最小的偏差 + * 在你声明的模式之外，你没有独立决策的权限 + * 你必须将分析深度与问题重要性相匹配 + * 你必须与原始需求保持清晰联系 + * 除非特别要求，否则你必须禁用表情符号输出 + * 如果没有明确的模式转换信号，请保持在当前模式 + +### 代码处理指南 + +代码块结构： +根据不同编程语言的注释语法选择适当的格式： + +C风格语言（C、C++、Java、JavaScript等）： + +```java +// ... existing code ... +{ + + + { modifications }} +// ... existing code ... +``` + +Python： + +```java +# ... existing code ... +{ + + + { modifications }} +# ... existing code ... +``` + +HTML/XML： + +```java + +{ + + + { modifications }} + +``` + +如果语言类型不确定，使用通用格式： + +```java +[... existing code ...] +{ + + + { modifications }} +[... existing code ...] +``` + +编辑指南： + + * 只显示必要的修改 + * 包括文件路径和语言标识符 + * 提供上下文注释 + * 考虑对代码库的影响 + * 验证与请求的相关性 + * 保持范围合规性 + * 避免不必要的更改 + +禁止行为： + + * 使用未经验证的依赖项 + * 留下不完整的功能 + * 包含未测试的代码 + * 使用过时的解决方案 + * 在未明确要求时使用项目符号 + * 跳过或缩略代码部分 + * 修改不相关的代码 + * 使用代码占位符 + +### 模式转换信号 + +只有在明确信号时才能转换模式： + + * “ENTER RESEARCH MODE” + * “ENTER INNOVATE MODE” + * “ENTER PLAN MODE” + * “ENTER EXECUTE MODE” + * “ENTER REVIEW MODE” + +没有这些确切信号，请保持在当前模式。 + +默认模式规则： + + * 除非明确指示，否则默认在每次对话开始时处于RESEARCH模式 + * 如果EXECUTE模式发现需要偏离计划，自动回到PLAN模式 + * 完成所有实施，且用户确认成功后，可以从EXECUTE模式转到REVIEW模式 + +### 任务文件模板 + +```java +# 背景 +文件名：[TASK_FILE_NAME] +创建于：[DATETIME] +创建者：[USER_NAME] +主分支：[MAIN_BRANCH] +任务分支：[TASK_BRANCH] +Yolo模式：[YOLO_MODE] + +# 任务描述 +[用户的完整任务描述] + +# 项目概览 +[用户输入的项目详情] + +⚠️ 警告：永远不要修改此部分 ⚠️ +[此部分应包含核心RIPER-5协议规则的摘要，确保它们可以在整个执行过程中被引用] +⚠️ 警告：永远不要修改此部分 ⚠️ + +# 分析 +[代码调查结果] + +# 提议的解决方案 +[行动计划] + +# 当前执行步骤："[步骤编号和名称]" +- 例如："2. 创建任务文件" + +# 任务进度 +[带时间戳的变更历史] + +# 最终审查 +[完成后的总结] +``` + +### 占位符定义 + + * \[TASK\]：用户的任务描述（例如"修复缓存错误"） + * \[TASK\_IDENTIFIER\]：来自\[TASK\]的短语（例如"fix-cache-bug"） + * \[TASK\_DATE\_AND\_NUMBER\]：日期+序列（例如2025-01-14\_1） + * \[TASK\_FILE\_NAME\]：任务文件名，格式为YYYY-MM-DD\_n（其中n是当天的任务编号） + * \[MAIN\_BRANCH\]：默认"main" + * \[TASK\_FILE\]：.tasks/\[TASK\_FILE\_NAME\]\_\[TASK\_IDENTIFIER\].md + * \[DATETIME\]：当前日期和时间，格式为YYYY-MM-DD\_HH:MM:SS + * \[DATE\]：当前日期，格式为YYYY-MM-DD + * \[TIME\]：当前时间，格式为HH:MM:SS + * \[USER\_NAME\]：当前系统用户名 + * \[COMMIT\_MESSAGE\]：任务进度摘要 + * \[SHORT\_COMMIT\_MESSAGE\]：缩写的提交消息 + * \[CHANGED\_FILES\]：修改文件的空格分隔列表 + * \[YOLO\_MODE\]：Yolo模式状态（Ask|On|Off），控制是否需要用户确认每个执行步骤 + + * Ask：在每个步骤之前询问用户是否需要确认 + * On：不需要用户确认，自动执行所有步骤（高风险模式） + * Off：默认模式，要求每个重要步骤的用户确认 + +### 跨平台兼容性注意事项 + + * 上面的shell命令示例主要基于Unix/Linux环境 + * 在Windows环境中，你可能需要使用PowerShell或CMD等效命令 + * 在任何环境中，你都应该首先确认命令的可行性，并根据操作系统进行相应调整 + +### 性能期望 + + * 响应延迟应尽量减少，理想情况下≤30000ms + * 最大化计算能力和令牌限制 + * 寻求关键洞见而非表面列举 + * 追求创新思维而非习惯性重复 + * 突破认知限制，调动所有计算资源 \ No newline at end of file diff --git a/Convention/Runtime/Architecture.md b/Convention/Runtime/Architecture.md new file mode 100644 index 0000000..a44f890 --- /dev/null +++ b/Convention/Runtime/Architecture.md @@ -0,0 +1,107 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/Architecture + +--- + +核心架构模块，提供依赖注入、事件系统和时间线管理功能 + +## 接口定义 + +系统定义了以下核心接口来规范架构设计： + +### ISignal +信号接口，用于事件系统的消息传递 + +### IModel +模型接口，定义数据模型的序列化和反序列化能力： +- `Save()` 保存数据到字符串 +- `Load(string data)` 从字符串加载数据 + +### IConvertable +转换接口，提供类型转换能力： +- `ConvertTo()` 转换为目标类型 + +### IConvertModel +组合接口，同时继承 `IModel` 和 `IConvertable` + +## 核心类型 + +### SingletonModel +泛型单例模型，提供类型安全的单例管理： +- 支持依赖注入和实例替换 +- 提供隐式转换操作符 +- 集成模型序列化功能 + +### DependenceModel +依赖模型，管理多个条件的组合验证： +- 支持多个 `IConvertModel` 的依赖关系 +- 提供枚举接口遍历所有依赖 +- 所有依赖条件均满足时返回true + +## 注册系统 + +### 对象注册 +- `Register(Type slot, object target, Action completer, params Type[] dependences)` +- `Register(T target, Action completer, params Type[] dependences)` + +提供基于类型的依赖注入容器： +- 支持依赖关系管理 +- 支持注册完成回调 +- 自动解析依赖顺序 + +### 注册查询 +- `Contains(Type type)` / `Contains()` +- `Get(Type type)` / `Get()` + +## 事件系统 + +### 消息监听 +- `AddListener(Type slot, Action listener)` +- `SendMessage(Type slot, ISignal signal)` +- `SendMessage(Signal signal)` + +提供类型安全的事件分发机制： +- 支持按类型注册监听器 +- 支持泛型消息类型 +- 自动管理监听器生命周期 + +### Listening类 +监听器管理类，提供： +- `StopListening()` 停止监听 + +## 时间线系统 + +### 时间线管理 +- `CreateTimeline()` 创建新的时间线 +- `AddStep(int timelineId, Func predicate, params Action[] actions)` 添加步骤 +- `UpdateTimeline()` 更新所有时间线 +- `ResetTimelineContext(int timelineId)` 重置时间线上下文 + +提供基于条件的任务调度： +- 支持多条时间线并行执行 +- 基于谓词的条件触发 +- 支持动态添加执行步骤 + +## 类型格式化 + +### 类型序列化 +- `FormatType(Type type)` 格式化类型为字符串 +- `LoadFromFormat(string data)` 从字符串加载类型 +- `LoadFromFormat(string data, out Exception exception)` 安全加载类型 + +使用格式：`Assembly::FullTypeName` + +## 内部管理 + +### 系统重置 +- `InternalReset()` 重置所有内部状态 + +清理以下组件： +- 注册历史 +- 未完成的目标 +- 完成器回调 +- 依赖关系 +- 子对象容器 +- 事件监听器 +- 时间线队列 diff --git a/Convention/Runtime/Config.md b/Convention/Runtime/Config.md new file mode 100644 index 0000000..8a2c2ca --- /dev/null +++ b/Convention/Runtime/Config.md @@ -0,0 +1,49 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/Config + +--- + +包含了关于静态的配置信息等内容, 并且引入全体标准库内容 + +## Import All + +检查并尝试引入所有依赖库 + +## 静态配置 + +若不存在相应配置, 则需要定义 + +- `CURRENT_COM_NAME` 公司/组织名称 +- `CURRENT_APP_NAME` 应用名称 + +## PlatformIndicator包含的内容 + +- `IsRelease` Debug/Release状态 +- `IsPlatform` 平台判断 +- `IsPlatformX64`平台架构判断 +- 编译器/解释器判断 如`IsMSVC`等 +- `ApplicationPath` 获取当前应用程序目录 +- `StreamingAssetsPath` 获取StreamingAssets目录 +- `PersistentPath` 获取持久化目录 +- `PlatformInfomation` 平台相关的发布信息 + +## 多个静态类 Indicator + +包含对应类型常用的工具函数 + +## 静态类 DescriptiveIndicator + +包含一个`描述`字符串, 可选一个`值`对象 + +## 其他基础内容 + +用于对齐不同语言间基本实现的颗粒度, 如以下内容 + +- 类型转换 +- 字符串操作 +- Construct/Destruct 重构造/析构 +- 命令行解析 +- 简单的反射内容 +- 元类型 +- 等等... diff --git a/Convention/Runtime/Config.py b/Convention/Runtime/Config.py new file mode 100644 index 0000000..528d553 --- /dev/null +++ b/Convention/Runtime/Config.py @@ -0,0 +1,278 @@ +from types import TracebackType +from typing import * +from abc import * +import sys +import threading +import traceback +import datetime +import platform +import time +from colorama import Fore as ConsoleFrontColor, Back as ConsoleBackgroundColor, Style as ConsoleStyle + +def format_traceback_info(char:str='\n', back:int=1): + return char.join(traceback.format_stack()[:-back]) + +INTERNAL_DEBUG = False +def SetInternalDebug(mode:bool): + global INTERNAL_DEBUG + INTERNAL_DEBUG = mode +def GetInternalDebug() -> bool: + global INTERNAL_DEBUG + return INTERNAL_DEBUG + +def print_colorful(color:str, *args, is_reset:bool=True, **kwargs): + with lock_guard(): + if is_reset: + print(color,*args,ConsoleStyle.RESET_ALL, **kwargs) + else: + print(color,*args, **kwargs) + +ImportingFailedSet:Set[str] = set() +def ImportingThrow( + ex: ImportError, + moduleName: str, + requierds: Sequence[str], + *, + messageBase: str = ConsoleFrontColor.RED+"{module} Module requires {required} package."+ConsoleFrontColor.RESET, + installBase: str = ConsoleFrontColor.GREEN+"\tpip install {name}"+ConsoleFrontColor.RESET + ): + with lock_guard(): + requierds_str = ",".join([f"<{r}>" for r in requierds]) + print(messageBase.format_map(dict(module=moduleName, required=requierds_str))) + print('Install it via command:') + for i in requierds: + global ImportingFailedSet + ImportingFailedSet.add(i) + install = installBase.format_map({"name":i}) + print(install) + if ex: + print(ConsoleFrontColor.RED, f"Import Error On {moduleName} Module: {ex}, \b{ex.path}\n"\ + f"[{ConsoleFrontColor.RESET}{format_traceback_info(back=2)}{ConsoleFrontColor.RED}]") + +def InternalImportingThrow( + moduleName: str, + requierds: Sequence[str], + *, + messageBase: str = ConsoleFrontColor.RED+"{module} Module requires internal Convention package: {required}."+ConsoleFrontColor.RESET, + ): + with lock_guard(): + requierds_str = ",".join([f"<{r}>" for r in requierds]) + print(f"Internal Convention package is not installed.\n{messageBase.format_map({ + "module": moduleName, + "required": requierds_str + })}\n[{ConsoleFrontColor.RESET}{format_traceback_info(back=2)}{ConsoleFrontColor.RED}]") + +def ReleaseFailed2Requirements(): + global ImportingFailedSet + if len(ImportingFailedSet) == 0: + return + with open("requirements.txt", 'w') as f: + f.write("\n".join(ImportingFailedSet)) + +try: + from pydantic import * +except ImportError: + InternalImportingThrow("Internal", ["pydantic"]) + +type Typen[_T] = type + +type Action[_T] = Callable[[_T], None] +type Action2[_T1, _T2] = Callable[[_T1, _T2], None] +type Action3[_T1, _T2, _T3] = Callable[[_T1, _T2, _T3], None] +type Action4[_T1, _T2, _T3, _T4] = Callable[[_T1, _T2, _T3, _T4], None] +type Action5[_T1, _T2, _T3, _T4, _T5] = Callable[[_T1, _T2, _T3, _T4, _T5], None] +type ActionW = Callable[[Sequence[Any]], None] +type ClosuresCallable[_T] = Union[Callable[[Optional[None]], _T], Typen[_T]] + +def AssemblyTypen(obj:Any) -> str: + if isinstance(obj, type): + return f"{obj.__module__}.{obj.__name__}, "\ + f"{obj.Assembly() if hasattr(obj, "Assembly") else "Global"}" + else: + return f"{obj.__class__.__module__}.{obj.__class__.__name__}, "\ + f"{obj.GetAssembly() if hasattr(obj, "GetAssembly") else "Global"}" +def ReadAssemblyTypen( + assembly_typen: str, + *, + premodule: Optional[str|Callable[[str], str]] = None + ) -> Tuple[type, str]: + typen, assembly_name = assembly_typen.split(",") + module_name, _, class_name = typen.rpartition(".") + if premodule is not None: + if isinstance(premodule, str): + module_name = premodule + else: + module_name = premodule(module_name) + import importlib + target_type = getattr(importlib.import_module(module_name), class_name) + return target_type, assembly_name + +# using as c#: event +class ActionEvent[_Call:Callable]: + def __init__(self, actions:Sequence[_Call]): + super().__init__() + self.__actions: List[Callable] = [action for action in actions] + self.call_indexs: List[int] = [i for i in range(len(actions))] + self.last_result: List[Any] = [] + def CallFuncWithoutCallIndexControl(self, index:int, *args, **kwargs) -> Union[Any, Exception]: + try: + return self.__actions[index](*args, **kwargs) + except Exception as ex: + return ex + def CallFunc(self, index:int, *args, **kwargs) -> Union[Any, Exception]: + return self.CallFuncWithoutCallIndexControl(self.call_indexs[index], *args, **kwargs) + def _inject_invoke(self, *args, **kwargs): + result:List[Any] = [] + for index in range(self.call_max_count): + result.append(self.CallFunc(index, *args, **kwargs)) + return result + def Invoke(self, *args, **kwargs) -> Union[Self, bool]: + self.last_result = self._inject_invoke(*args, **kwargs) + return self + def InitCallIndex(self): + self.call_indexs = [i for i in range(len(self.__actions))] + def AddAction(self, action:_Call): + self.__actions.append(action) + self.call_indexs.append(len(self.__actions)-1) + return self + def AddActions(self, actions:Sequence[_Call]): + for action in actions: + self.AddAction(action) + return self + def _InternalRemoveAction(self, action:_Call): + if action in self.__actions: + index = self.__actions.index(action) + self.__actions.remove(action) + self.call_indexs.remove(index) + for i in range(len(self.call_indexs)): + if self.call_indexs[i] > index: + self.call_indexs[i] -= 1 + return True + return False + def RemoveAction(self, action:_Call): + while self._InternalRemoveAction(action): + pass + return self + def IsValid(self): + return not any(isinstance(x, Exception) for x in self.last_result) + def __bool__(self): + return self.IsValid() + @property + def CallMaxCount(self): + return len(self.call_indexs) + @property + def ActionCount(self): + return len(self.__actions) + +# region instance + +# threads + +class atomic[_T]: + def __init__( + self, + value: _T, + locker: Optional[threading.Lock] = None, + ) -> None: + self._value: _T = value + self._is_in_with: bool = False + self.locker: threading.Lock = locker if locker is not None else threading.Lock() + def FetchAdd(self, value:_T): + with lock_guard(self.locker): + self._value += value + return self._value + def FetchSub(self, value:_T): + with lock_guard(self.locker): + self._value -= value + return self._value + def Load(self) -> _T: + with lock_guard(self.locker): + return self._value + def Store(self, value: _T): + with lock_guard(self.locker): + self._value = value + def __add__(self, value:_T): + return self.FetchAdd(value) + def __sub__(self, value:_T): + return self.FetchSub(value) + def __iadd__(self, value:_T) -> Self: + self.FetchAdd(value) + return self + def __isub__(self, value:_T) -> Self: + self.FetchSub(value) + return self + def __enter__(self) -> Self: + self._is_in_with = True + self.locker.acquire() + return self + def __exit__( + self, + exc_type: Optional[type], + exc_val: Optional[BaseException], + exc_tb: Optional[TracebackType] + ) -> bool: + self._is_in_with = False + self.locker.release() + if exc_type is None: + return True + else: + return False + @property + def Value(self) -> _T: + if self._is_in_with: + return self._value + raise NotImplementedError("This method can only be called within a with statement") + @Value.setter + def Value(self, value:_T) -> _T: + if self._is_in_with: + self._value = value + raise NotImplementedError("This method can only be called within a with statement") + + def __str__(self) -> str: + return str(self.Load()) + def __repr__(self) -> str: + return repr(self.Load()) + +InternalGlobalLocker = threading.Lock() +InternalGlobalLockerCount = atomic[int](0) + +class lock_guard: + def __init__( + self, + lock: Optional[Union[threading.RLock, threading.Lock]] = None + ): + if lock is None: + lock = InternalGlobalLocker + self._locker = lock + self._locker.acquire() + def __del__(self): + self._locker.release() + +class global_lock_guard(lock_guard): + def __init__(self): + super().__init__(None) + +class thread_instance(threading.Thread): + def __init__( + self, + call: Action[None], + *, + is_del_join: bool = True, + **kwargs + ): + kwargs.update({"target": call}) + super().__init__(**kwargs) + self.is_del_join = is_del_join + self.start() + def __del__(self): + if self.is_del_join: + self.join() + +# region end + +def Nowf() -> str: + ''' + printf now time to YYYY-MM-DD_HH-MM-SS format, + return: str + ''' + return datetime.datetime.now().strftime("%Y-%m-%d_%H-%M-%S") diff --git a/Convention/Runtime/EasySave.md b/Convention/Runtime/EasySave.md new file mode 100644 index 0000000..b934851 --- /dev/null +++ b/Convention/Runtime/EasySave.md @@ -0,0 +1,111 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/EasySave + +--- + +完整的序列化和数据持久化系统，提供易用的数据存储和读取功能 + +## 核心特性 + +### 支持的数据格式 +- **EasySave - JSON** 支持多态的json格式 +- **Binary** 紧凑的二进制格式 + +## EasySave主类 + +### 基本保存操作 + +#### 泛型保存 +- `Save(string key, T value)` 保存到默认文件 +- `Save(string key, T value, string filePath)` 保存到指定文件 +- `Save(string key, T value, EasySaveSettings settings)` 使用自定义设置 + +#### 原始数据保存 +- `SaveRaw(byte[] bytes)` / `SaveRaw(string str)` 保存原始数据 +- `AppendRaw(byte[] bytes)` / `AppendRaw(string str)` 追加原始数据 + +### 基本加载操作 + +#### 泛型加载 +- `Load(string key)` 从默认文件加载 +- `Load(string key, string filePath)` 从指定文件加载 +- `Load(string key, T defaultValue)` 带默认值的安全加载 + +#### 原始数据加载 +- `LoadRawBytes()` / `LoadRawString()` 加载原始数据 +- `LoadString(string key, string defaultValue)` 加载字符串 + +#### 加载到现有对象 +- `LoadInto(string key, T obj)` 将数据加载到现有对象 +- `LoadInto(string key, string filePath, object obj)` 从指定文件加载到对象 + +### 序列化操作 + +#### 内存序列化 +- `Serialize(T value, EasySaveSettings settings = null)` 序列化为字节数组 +- `Deserialize(byte[] bytes, EasySaveSettings settings = null)` 从字节数组反序列化 +- `DeserializeInto(byte[] bytes, T obj)` 反序列化到现有对象 + +### 加密和压缩 + +#### 加密操作 +- `EncryptBytes(byte[] bytes, string password = null)` 加密字节数组 +- `DecryptBytes(byte[] bytes, string password = null)` 解密字节数组 +- `EncryptString(string str, string password = null)` 加密字符串 +- `DecryptString(string str, string password = null)` 解密字符串 + +#### 压缩操作 +- `CompressBytes(byte[] bytes)` 压缩字节数组 +- `DecompressBytes(byte[] bytes)` 解压字节数组 +- `CompressString(string str)` 压缩字符串 +- `DecompressString(string str)` 解压字符串 + +### 备份系统 + +#### 备份操作 +- `CreateBackup()` / `CreateBackup(string filePath)` 创建备份 +- `RestoreBackup(string filePath)` 恢复备份 + +#### 时间戳 +- `GetTimestamp()` / `GetTimestamp(string filePath)` 获取文件时间戳 + +### 缓存系统 + +#### 缓存操作 +- `StoreCachedFile()` / `StoreCachedFile(string filePath)` 存储缓存文件 +- `CacheFile()` / `CacheFile(string filePath)` 缓存文件 + +## EasySaveSettings配置 + +### 枚举类型定义 + +#### 存储位置 +```csharp +public enum Location { File, InternalMS, Cache } +``` + +#### 目录类型 +```csharp +public enum Directory { PersistentDataPath, DataPath } +``` + +#### 加密类型 +```csharp +public enum EncryptionType { None, AES } +``` + +#### 压缩类型 +```csharp +public enum CompressionType { None, Gzip } +``` + +#### 数据格式 +```csharp +public enum Format { JSON } +``` + +#### 引用模式 +```csharp +public enum ReferenceMode { ByRef, ByValue, ByRefAndValue } +``` diff --git a/Convention/Runtime/File.md b/Convention/Runtime/File.md new file mode 100644 index 0000000..842e758 --- /dev/null +++ b/Convention/Runtime/File.md @@ -0,0 +1,88 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/File + +--- + +文件操作工具模块，提供跨平台的文件和目录操作功能 + +## ToolFile类 + +### 构造与基本信息 +- `ToolFile(string path)` 从路径创建文件对象 +- `ToString()` / `GetFullPath()` 获取完整路径 +- `GetName(bool is_ignore_extension = false)` 获取文件名 +- `GetExtension()` 获取文件扩展名 + +### 路径操作 +- `ToolFile operator |(ToolFile left, string rightPath)` 路径连接操作符 +- `Open(string path)` 打开指定路径 +- `Open(FileMode mode)` 以指定模式打开文件 +- `Close()` 关闭文件流 +- `BackToParentDir()` 回到父目录 +- `GetParentDir()` 获取父目录 + +### 存在性检查 +- `Exists()` 检查文件或目录是否存在 +- `implicit operator bool` 隐式布尔转换，等同于Exists() + +### 类型判断 +- `IsDir()` 是否为目录 +- `IsFile()` 是否为文件 +- `IsFileEmpty()` 文件是否为空 + +### 文件加载 +支持多种格式的文件读取： + +#### JSON操作 +- `LoadAsRawJson()` 原始JSON反序列化 +- `LoadAsJson(string key = "data")` 使用EasySave加载JSON + +#### 文本操作 +- `LoadAsText()` 加载为文本字符串 + +#### 二进制操作 +- `LoadAsBinary()` 加载为字节数组 + +### 文件保存 +支持多种格式的文件写入： + +#### JSON保存 +- `SaveAsRawJson(T data)` 原始JSON序列化保存 +- `SaveAsJson(T data, string key)` 使用EasySave保存JSON + +#### 二进制保存 +- `SaveAsBinary(byte[] data)` 保存字节数组 +- `SaveDataAsBinary(string path, byte[] outdata, FileStream Stream = null)` 静态二进制保存 + +### 文件操作 +- `Create()` 创建文件或目录 +- `Rename(string newPath)` 重命名 +- `Move(string path)` 移动文件 +- `Copy(string path, out ToolFile copyTo)` 复制文件 +- `Delete()` / `Remove()` 删除文件或目录 +- `Refresh()` 刷新文件信息 + +### 路径管理 +- `MustExistsPath()` 确保路径存在（自动创建） +- `TryCreateParentPath()` 尝试创建父路径 + +### 目录操作 +- `DirIter()` 遍历目录获取字符串列表 +- `DirToolFileIter()` 遍历目录获取ToolFile列表 +- `DirCount()` 获取目录内项目数量 +- `DirClear()` 清空目录内容 +- `MakeFileInside(string source, bool isDeleteSource = false)` 在目录内创建文件 + +### 文件对话框（平台相关） +- `SelectMultipleFiles(string filter, string title)` 多文件选择对话框 +- `SelectFile(string filter, string title)` 单文件选择对话框 +- `SaveFile(string filter, string title)` 保存文件对话框 +- `SelectFolder(string description)` 文件夹选择对话框 + +### 文件浏览 +- `BrowseFile(params string[] extensions)` 浏览指定扩展名的文件 +- `BrowseToolFile(params string[] extensions)` 浏览并返回ToolFile对象 + +### 时间戳 +- `GetTimestamp()` 获取文件时间戳 diff --git a/Convention/Runtime/GlobalConfig.md b/Convention/Runtime/GlobalConfig.md new file mode 100644 index 0000000..f68a490 --- /dev/null +++ b/Convention/Runtime/GlobalConfig.md @@ -0,0 +1,88 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/GlobalConfig + +--- + +全局配置管理模块，提供配置文件操作、日志系统和项目级配置管理 + +## GlobalConfig类 + +### 构造与初始化 +- `GlobalConfig(string dataDir, bool isTryCreateDataDir = false, bool isLoad = true)` +- `GlobalConfig(ToolFile dataDir, bool isTryCreateDataDir = false, bool isLoad = true)` + +#### 初始化流程 +1. 设置数据目录，确保目录存在 +2. 检查配置文件，不存在则生成空配置 +3. 可选自动加载现有配置 + +### 静态配置 +- `ConstConfigFile` 配置文件名（默认"config.json"） +- `InitExtensionEnv()` 初始化扩展环境 +- `GenerateEmptyConfigJson(ToolFile file)` 生成空配置JSON + +### 文件管理 +- `GetConfigFile()` / `ConfigFile` 获取配置文件对象 +- `GetFile(string path, bool isMustExist = false)` 获取数据目录下的文件 +- `CreateFile(string path)` 创建文件 +- `EraseFile(string path)` 清空文件内容 +- `RemoveFile(string path)` 删除文件 + +### 配置数据操作 + +能够被`foreach`/`for`使用迭代器历遍配置内容的键值对 + +#### 数据访问 +- `operator[](string key)` 索引器访问配置项 +- `Contains(string key)` 检查键是否存在 +- `Remove(string key)` 删除配置项 +- `DataSize()` 获取配置项数量 + +#### 持久化 +- `SaveProperties()` 保存配置到文件 +- `LoadProperties()` 从文件加载配置 + +配置文件格式： +```json +{ + "properties": { + "key1": "value1", + "key2": "value2" + } +} +``` + +### 日志系统 +- `GetLogFile()` / `LogFile` 获取日志文件对象 +- `DefaultLogger` 默认日志输出器（可自定义） + +#### 日志方法 +- `Log(string messageType, string message, Action logger)` +- `Log(string messageType, string message)` 使用默认日志器 +- `LogPropertyNotFound(string message, Action logger, object @default = null)` +- `LogPropertyNotFound(string message, object @default = null)` +- `LogMessageOfPleaseCompleteConfiguration()` 记录配置提示信息 + +#### 日志格式 +``` +[time] MessageType : Message +``` + +自动调整消息类型的对齐宽度 + +### 配置查找 +- `FindItem(string key, object @default = null)` 查找配置项，支持默认值 + +## ProjectConfig类 + +继承自 `GlobalConfig`，专门用于项目级配置管理 + +### 静态配置 +- `ProjectConfigFileFocus` 项目配置目录焦点（默认"Assets/"） +- `InitExtensionEnv()` 初始化项目扩展环境 +- `SetProjectConfigFileFocus(string path)` 设置项目配置焦点目录 +- `GetProjectConfigFileFocus()` 获取项目配置焦点目录 + +### 构造 +- `ProjectConfig(bool isLoad = true)` 使用默认项目目录构造 diff --git a/Convention/Runtime/Math.md b/Convention/Runtime/Math.md new file mode 100644 index 0000000..afa2738 --- /dev/null +++ b/Convention/Runtime/Math.md @@ -0,0 +1,7 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/Math + +--- + +数学工具模块，提供常用数学计算功能 diff --git a/Convention/Runtime/Plugins.md b/Convention/Runtime/Plugins.md new file mode 100644 index 0000000..fbdbcd8 --- /dev/null +++ b/Convention/Runtime/Plugins.md @@ -0,0 +1,7 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/Plugins + +--- + +插件系统模块，提供扩展机制和平台特定功能 diff --git a/Convention/Runtime/Web.md b/Convention/Runtime/Web.md new file mode 100644 index 0000000..f682e50 --- /dev/null +++ b/Convention/Runtime/Web.md @@ -0,0 +1,121 @@ +[返回](./Runtime-README.md) + +# /Convention/Runtime/Web + +--- + +网络工具模块，提供HTTP客户端和URL操作功能 + +## ToolURL类 + +### 构造与基本信息 +- `ToolURL(string url)` 从URL字符串创建对象 +- `ToString()` / `GetFullURL()` / `FullURL` 获取完整URL +- `implicit operator string` 隐式字符串转换 + +### URL属性解析 +- `GetFilename()` 获取URL中的文件名 +- `GetExtension()` 获取文件扩展名 +- `ExtensionIs(params string[] extensions)` 检查扩展名是否匹配 + +### URL验证 +- `IsValid` 属性，检查URL是否有效 +- `ValidateURL()` 验证URL格式 +- `implicit operator bool` 隐式布尔转换，等同于IsValid + +支持HTTP和HTTPS协议的绝对URL + +### HTTP方法 + +#### GET请求 +- `GetAsync(Action callback)` 异步GET +- `Get(Action callback)` 同步GET + +#### POST请求 +- `PostAsync(Action callback, Dictionary formData = null)` 异步POST +- `Post(Action callback, Dictionary formData = null)` 同步POST + +支持表单数据提交 + +### 内容加载 + +#### 文本加载 +- `LoadAsTextAsync()` 异步加载为文本 +- `LoadAsText()` 同步加载为文本 + +#### 二进制加载 +- `LoadAsBinaryAsync()` 异步加载为字节数组 +- `LoadAsBinary()` 同步加载为字节数组 + +#### JSON加载 +- `LoadAsJson()` 同步加载并反序列化JSON +- `LoadAsJsonAsync()` 异步加载并反序列化JSON + +### 文件保存 +- `Save(string localPath = null)` 自动选择格式保存到本地 +- `SaveAsText(string localPath = null)` 保存为文本文件 +- `SaveAsJson(string localPath = null)` 保存为JSON文件 +- `SaveAsBinary(string localPath = null)` 保存为二进制文件 + +### 文件类型判断 +- `IsText` 是否为文本文件（txt, html, htm, css, js, xml, csv） +- `IsJson` 是否为JSON文件 +- `IsImage` 是否为图像文件（jpg, jpeg, png, gif, bmp, svg） +- `IsDocument` 是否为文档文件（pdf, doc, docx, xls, xlsx, ppt, pptx） + +### 高级操作 +- `Open(string url)` 在当前对象上打开新URL +- `DownloadAsync(string localPath = null)` 异步下载文件 +- `Download(string localPath = null)` 同步下载文件 + +## 设计特点 + +### 统一的HTTP客户端 +使用静态 `HttpClient` 实例，避免连接池耗尽 + +### 自动内容类型检测 +基于文件扩展名自动判断内容类型，优化保存和处理策略 + +### 异步支持 +所有网络操作都提供异步和同步两种版本 + +### 错误处理 +网络请求失败时回调函数接收null参数，方法返回false + +### 文件管理集成 +下载的文件自动转换为ToolFile对象，与文件系统模块无缝集成 + +### 灵活的数据格式 +支持文本、二进制、JSON等多种数据格式的加载和保存 + +## 使用示例 + +### 基本HTTP请求 +```csharp +var url = new ToolURL("https://api.example.com/data"); +if (url.IsValid) +{ + url.Get(response => { + if (response != null && response.IsSuccessStatusCode) + { + // 处理响应 + } + }); +} +``` + +### 文件下载 +```csharp +var url = new ToolURL("https://example.com/file.json"); +var localFile = url.Download("./downloads/file.json"); +if (localFile.Exists()) +{ + var data = localFile.LoadAsJson(); +} +``` + +### 类型安全的JSON加载 +```csharp +var url = new ToolURL("https://api.example.com/users.json"); +var users = url.LoadAsJson>(); +``` \ No newline at end of file diff --git a/Convention/Runtime/__init__.py b/Convention/Runtime/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/Convention/__init__.py b/Convention/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..4f19e43 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,3 @@ +include LICENSE +include README.md +global-exclude *.meta \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e69de29 diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..e681960 --- /dev/null +++ b/setup.py @@ -0,0 +1,24 @@ +from setuptools import setup, find_packages +import io + +setup( + name="Convention", + version="0.1.0", + author="LiuBai", + description="A python version code repository for implementing the agreements and implementations in the Convention-Template.", + long_description=io.open("README.md", encoding="utf-8").read(), + long_description_content_type="text/markdown", + url="https://github.com/NINEMINEsigma/Convention-Python", + packages=find_packages(), + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + python_requires=">=3.12", + install_requires=[ + "colorama", + "pydantic" + ], + exclude_package_data={"": ["*.meta"]}, +) \ No newline at end of file