# 通用准则

**始终使用简体中文回复**。

**这是一个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，便于追踪差异、评估升级风险。

---

## 使用流程

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

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

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