sunflowermm/xrk-infrastructure

权威文档与入口

• 可扩展性总览：docs/框架可扩展性指南.md
• 基类与加载器：见下方「基类与加载器一览」；各基类文档在 docs/ 对应同名 md。

基类与加载器一览

| 扩展点 | 基类路径 | 加载器路径 | 扫描目录 | |--------|----------|------------|----------| | 插件 | #infrastructure/plugins/plugin.js | #infrastructure/plugins/loader.js | core/*/plugin/*.js | | HTTP API | #infrastructure/http/http.js | #infrastructure/http/loader.js | core/*/http/*.js | | 工作流 | #infrastructure/aistream/aistream.js | #infrastructure/aistream/loader.js | core/*/stream/*.js | | Tasker | - | #infrastructure/tasker/loader.js | core/*/tasker/*.js | | 事件监听器 | #infrastructure/listener/base.js | #infrastructure/listener/loader.js | core/*/events/*.js | | 配置 | #infrastructure/commonconfig/commonconfig.js | #infrastructure/commonconfig/loader.js | core/*/commonconfig/*.js | | 渲染器 | #infrastructure/renderer/Renderer.js | #infrastructure/renderer/loader.js | src/renderers/* + 配置 |

路径与 # 别名（package.json imports）

• #utils/* → src/utils/*
• #infrastructure/* → src/infrastructure/*
• #factory/* → src/factory/*
• #config/* → config/*
• #data/* → data/*
• #core/* → core/*
• #renderers/* → src/renderers/*
• #modules/* → src/modules/*
• #oicq → src/modules/oicq/index.js（业务层用全局 segment，无需从此导入）

根路径与 core 目录解析：#utils/paths.js（getCoreDirs、root 等）。

• 注意：cfg.aistream 对应 data/server_bots/{port}/aistream.yaml（getServerConfig），不在 server_bots 根目录；与 docs/app-dev.md、docs/aistream.md 一致。

错误处理标准化

• 入口：#utils/error-handler.js
• 使用 errorHandler.handle(error, options) 统一记录与分类；HTTP 层用 HttpResponse.error()，内部会调 error-handler。
• 错误码：ErrorCodes（WORKFLOW_、PLUGIN_、INPUT_VALIDATION_FAILED、SYSTEM_ERROR、NOT_FOUND、CONFIG_* 等）；自定义错误可用 BotError。

底层开发约定

• src/ 只放基础设施与工厂：不写业务逻辑；新增能力优先在 core 内扩展，必须扩展底层时再改 src（如新基类、新加载器）。
• 保持接口稳定：基类与加载器的对外 API（如 routes、deal(e)、process(e, msg)）变更需与文档和现有 core 兼容。
• 日志与工具：底层统一用 BotUtil.makeLog / #utils/botutil.js，错误用 error-handler，不直接 console 打业务日志。

权威入口

• 项目概览：PROJECT_OVERVIEW.md
• 代码入口：src/ 与 core/ 对应子目录
• 相关文档：docs/ 下对应主题文档

适用场景

• 需要定位该子系统的实现路径与配置入口。
• 需要快速给出改动落点与兼容性注意事项。

非适用场景

• 不用于替代其他子系统的实现说明。
• 不在缺少证据时臆造路径或字段。

执行步骤

1. 先确认需求属于该技能的职责边界。
2. 再给出代码路径、配置路径与关键字段。
3. 最后补充风险点、验证步骤与回归范围。

常见陷阱

• 只给概念，不给具体文件路径。
• 文档与代码冲突时未标注以代码为准。
• 忽略配置、Schema 与消费代码的一致性。