通用准则

始终使用简体中文回复。

这是一个Windows系统，而你在git bash中运行，永远不要使用类似>/dev/null、>nul这样的命令，这会导致建立名为nul的特殊文件，无法删除。

请显式将$HOME替换为C:/Users/Administrator，有些情况下HOME变量为空，会导致工作目录出现严重错误。

永远不要执行“杀死所有Java进程、杀死所有Node进程”这样的操作，请务必根据端口号或文件名精准到筛选出特定进程。

针对比较复杂的网页操作，不要使用playwright来进行测试，既慢又耗费 token，交给用户进行手动测试。简单网页操作不受此条限制。

除非我明确要求，否则不要帮我启动前后端服务。如果为了测试需要启动，测试完成后，关闭服务，由用户手动启动。

涉及耗时操作（大模型调用、文件传输、音视频处理、批量数据导入导出、复杂计算、报表生成、第三方 API 调用、数据库大批量操作、流式处理、缓存预热、索引构建、数据备份恢复、长连接、工作流编排等）必须设置足够长的超时时间（至少30分钟或无限制），因为这些操作的处理时长和响应延迟高度不确定，固定短超时容易中断正常流程。

前后端合并部署：同时包含前后端的项目（前端为网页）应合并部署，前端打包直接输出到后端资源路径（如 SpringBoot 的 static 目录）。部署应参考 fullstack-merge-deploy 技能，必须创建 deploy.sh、deploy.bat、run.sh、run.bat（run 脚本包含部署+运行）。禁止使用 8080、5173 等常用默认端口，端口需询问确认。

编程行为准则

行为准则，旨在减少常见的 LLM 编码错误。可根据项目特定指令按需合并。

权衡： 这些准则倾向于谨慎而非速度。对于简单任务，请自行判断。

1. 先思考，再编码

不要假设。不要掩盖困惑。主动呈现权衡。

在实现之前：

明确陈述你的假设。如果不确定，先问。
如果存在多种理解方式，全部列出来——不要悄悄自作主张。
如果存在更简单的方案，说出来。必要时提出反对意见。
如果有不清楚的地方，停下来。指出困惑之处，然后提问。

2. 简洁优先

用最少的代码解决问题。不做任何投机性设计。

不添加超出需求的功能。
不为一次性代码创建抽象。
不添加未被要求的"灵活性"或"可配置性"。
不为不可能发生的场景编写错误处理。
如果你写了 200 行，但其实 50 行就够了，重写它。

问问自己："资深工程师会认为这过于复杂吗？"如果是，简化它。

3. 精准修改

只改必须改的。只清理自己造成的残留。

编辑现有代码时：

不要"改进"相邻的代码、注释或格式。
不要重构没有问题的部分。
遵循现有风格，即使你的偏好不同。
如果注意到无关的死代码，提一下——但不要删除。

当你的修改产生孤立代码时：

删除因你的修改而变为未使用的导入/变量/函数。
不要删除之前就存在的死代码，除非被要求。

检验标准：每一处改动都应能直接追溯到用户的需求。

4. 目标驱动执行

定义成功标准。循环验证直到达标。

将任务转化为可验证的目标：

"添加验证" → "为无效输入编写测试，然后让测试通过"
"修复 Bug" → "编写一个能复现问题的测试，然后让测试通过"
"重构 X" → "确保重构前后测试都能通过"

对于多步骤任务，陈述简要计划：

1. [步骤] → 验证: [检查方式]
2. [步骤] → 验证: [检查方式]
3. [步骤] → 验证: [检查方式]

明确的成功标准让你能独立循环迭代。模糊的标准（"让它能用就行"）则需要不断确认。

这些准则生效的标志： diff 中不必要改动更少，因过度复杂导致的重写更少，澄清问题出现在实现之前而非犯错之后。

Token 节省准则

@RTK.md

项目专用准则

文档资源目录

项目 docs/ 目录包含 5 类文档，覆盖设计、规划、规格、参考与补丁。实施任何功能前必读相关文档，避免重复设计或遗漏关键约束。

设计文档（design/）

架构设计与技术方案设计，共 11 篇。涵盖：

工作流核心机制：

节点字段与 IO 类型（workflow-node-fields-design.md）
上下文传递机制（workflow-context-passing-design.md）
输出信封化（workflow-output-envelope-design.md）
变量作用域与命名空间（workflow-variable-scope-design.md）

RAG 系统：

整体架构与前瞻性优化（rag-advanced-architecture-design.md）
Graph RAG 设计（graph-rag-design.md）
本地语义切分（local-semantic-chunking-design.md）
结构化数据 RAG（structured-data-rag-design.md）

其他：

Hermes 沙箱隔离设计（hermes-sandbox-design.md）
聊天界面设计（agent-chat-page-design.md）

作用：系统性设计决策的权威文档，实施前必读。

实施计划（plans/）

具体功能实施计划，共 8 篇。包括：

智能体工作流：

AGENTIC 模式（自主智能体工作流）实施（agentic-workflow-plan.md）
AGENTIC 重访决策机制（agentic-revisit-decision-plan.md）

Hermes 相关：

错误检测与重试机制（hermes-error-detection-plan.md）
思考过程展示重构（hermes-thinking-display-overhaul-plan.md）

工作流引擎：

节点上下文按需加载（node-context-ondemand-plan.md）
数据流执行模型（workflow-dataflow-execution-plan.md）
信封严格验证（workflow-envelope-strict-validation-plan.md）
输出模式约束（workflow-output-schema-constraint-plan.md）
调度引擎（workflow-scheduling-engine-plan.md）

作用：分步实施路线图，含需求确认、技术方案、任务拆解。

规格文档（specs/）

接口规范与功能规格，共 3 篇：

外部工作流 API（external-workflow-api-spec.md）
标签系统（tag-system-spec.md）
工作流 CRUD API（workflow-crud-api-spec.md）

作用：API 契约、输入输出约束、校验规则的定义文档。

参考文档（reference/）

外部项目参考与机制说明，共 7 篇：

同类项目参考：

Dify 平台总览（dify-reference.md）
Dify 工作流节点（dify-workflow-nodes-reference.md）
即刻平台（jizhi-platform-reference.md）
Super Mew（super-mew-reference.md）

Hermes 机制：

Hermes-Agent 上游升级（hermes-agent-upgrade-reference.md）
Hermes 上下文压缩与记忆（hermes-context-memory-reference.md）

其他：

RAG 集成参考（rag-integration-reference.md）
技能管理（skills-manage-reference.md）
工作流 vs Dify 对比（workflow-vs-dify-comparison.md）

作用：技术选型依据、同类方案对比、上游依赖评估。

补丁说明（patches/hermes-agent/）

Hermes-Agent 私有修改记录（README.md）。

作用：记录对上游 Hermes 的 fork 与 patch，便于追踪差异、评估升级风险。

使用流程

实施新功能时的标准流程：

查设计文档：理解系统性设计决策与技术约束
查实施计划：确认是否已有计划，避免重复工作
查规格文档：明确接口契约、输入输出、校验规则
查参考文档：参考同类项目实现、上游依赖特性
查补丁说明（若涉及 Hermes）：确认私有修改与上游差异

关键原则：先读文档再动手，设计决策自上而下（design → plans → specs），避免重复设计或遗漏关键约束。

AGENTS.md 7.8 KB Előzmények Nyers