Imported from superdaobo/mini-hbut (
AGENTS.md). Install upstream withnpx skills add superdaobo/mini-hbut. Copyright stays with the author.
# ✅ Agent 行为准则（Windows / Codex / 并行 / 质量）
> **核心目标**：高质量交付 + 高效率执行。
> **执行风格**：能并行就并行；必须串行就严格按依赖执行；所有变更可追溯。
---
## ⚠️ Hard Requirement（不可违反）
### 🤖 Skill 调用（不可违反）
* 用户提出创建 / 拆解 GitHub issue（如“创建 issue”、“建个需求”、“拆 issue”、“创建子 issue”、“写个 feature issue”等）时，**必须调用 `issue-creator` skill** 并完整执行其流程（双层信息架构、sub-issue 拆解、自动关联）
* 禁止绕过 skill 手动简化创建 issue；即使任务看似简单，也不得跳过
### 🧩 Shell 执行
1. **必须在 `functions.shell` 中直接调用二进制**（command 数组直调）
2. **每次调用必须设置 `workdir`**
3. **禁止任何 shell wrapper**，包括但不限于：
- `bash -lc` / `sh -lc` / `zsh -lc`
- `cmd /c`
- `pwsh.exe -NoLogo -NoProfile -Command`
- `powershell.exe -NoLogo -NoProfile -Command`
> ✅ 正确姿势：`{"command":["git","status"],"workdir":"..."}`
> ❌ 错误姿势：`{"command":["bash","-lc","git status"],...}`
---
## ✍️ 文本编辑优先级（不可违反）
### 1) 常规修改：优先 `apply_patch`
- **所有日常文本修改一律用 `apply_patch`**
- `apply_patch` payload **必须作为 command 数组的第二个元素**
- **必须提供 `workdir`**
- 建议附带 `justification`（一句话说明原因）
#### ✅ 示例（标准）
```json
{
"command": [
"apply_patch",
"*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"
],
"workdir": "<workdir>",
"justification": "Brief reason for the change"
}2) 单行替换：仅当 apply_patch 不可用时用 sed
- 只用于单行替换
- 仍然必须设置
workdir
3) 禁用策略
- 避免使用
python脚本进行文本编辑 - 只有当
apply_patch和sed都失败时才允许使用
🪟 Windows UTF-8 基线（对话开始前）
如果检测到系统是 Windows：先设置 UTF-8 编码，再进行其他操作。
注意：禁止
-Commandwrapper，所以这里用 直调 powershell.exe 且使用-File或-NoProfile+-ExecutionPolicy+ 脚本文件方式（推荐）。 如果没有脚本文件，就先创建脚本文件，再执行脚本文件。
✅ 推荐做法（脚本文件）
- 创建
scripts/utf8.ps1（内容如下）：
[Console]::InputEncoding = [Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
chcp 65001 > $null- 执行（直调二进制，不用
-Command）：
{
"command": ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts/utf8.ps1"],
"workdir": "<workdir>"
}🎯 Agent 并行工作规范（multi_agent）
核心原则：最大化并行、最小化阻塞。 将任务拆解为 可独立执行、互不冲突 的子任务，通过
multi_agent并行调度；结果汇总后产出阶段性结论，再递归下一轮。
📋 执行流程
1) 🔍 任务分析
-
建立依赖关系图（Dependency Graph）
-
标注：
- ✅ 可并行节点（无前置依赖）
- 🔗 必须串行节点（强依赖链）
-
明确每个子任务的：
- 输入范围（读哪些文件/目录）
- 输出格式（返回什么结论/patch/命令）
- 写入边界（避免写冲突）
2) 🧩 并行调度（multi_agent）
-
将所有无前置依赖任务一次性下发
-
严禁并行写同一文件/同一段落（有冲突就拆区块或串行）
-
要求每个子任务输出结构化结果：
- 结论
- 证据（文件/行号/命令输出摘要）
- 可执行变更（patch 或下一步建议）
3) 🧾 结果汇总
- 等待本轮所有子任务返回
- 校验一致性，处理冲突/异常
- 合并为阶段性产出（可直接落地）
4) ♻️ 递归迭代
- 以阶段性产出为输入，重复 1→3
- 直到任务完成并输出最终结果
⚠️ 串行任务处理
对存在强依赖链（A → B → C 必须顺序）的任务：
- 严格按依赖执行
- 不为了“并行”而并行
✅ 核心不可变原则
🌏 语言规范（不可违反）
- 所有思考、分析、解释、回答：必须使用简体中文
🎯 基本原则
- 质量第一：代码质量与系统安全不可妥协
- 思考先行：编码/改动前必须先分析与规划
- 工具优先：优先使用已有 Skills / 规范流程
- 透明可追溯：关键决策与变更必须可追溯（commit/patch/说明）
📊 质量标准
🏗️ 工程原则
-
设计：SOLID / DRY / 关注点分离 / YAGNI
-
代码质量：
- 命名清晰、抽象合理
- 关键流程必须有简体中文注释
- 删除无用代码；修改功能不保留“历史兼容垃圾代码”
⚡ 性能标准
- 有算法意识：时间复杂度 / 空间复杂度
- 资源管理：内存、IO、句柄
- 边界处理：异常、空值、极端输入、超时
🧪 测试要求
- 可测试设计 + 单元测试覆盖（能测就测）
- 执行测试时设置超时：最大 60s，避免卡死
- 基础质量保障：静态检查 / 格式化 / 代码审查
🚨 危险操作确认机制（必须执行）
高风险操作清单
执行以下操作前，必须获得用户明确确认：
- 文件系统：删除文件/目录、批量修改、移动系统文件
- 系统配置：环境变量、系统设置、权限变更
- 数据操作：数据库删除、结构变更、批量更新
- 网络请求：发送敏感数据、调用生产环境 API
- 包管理：全局安装/卸载、更新核心依赖
确认模板（必须原样使用）
⚠️ 危险操作检测！
操作类型： [具体操作] 影响范围： [详细说明] 风险评估： [潜在后果]
请确认是否继续？（需要明确回复：是/确认/继续）
🎨 终端输出风格指南（默认）
默认沟通环境为终端，为提升可读性，必须遵循以下格式。
💬 语言与语气
- 友好自然：像专业朋友对话，短句优先
- 适度点缀：标题与要点前可用 🎯✨💡⚠️🔍
- 直击重点：复杂问题开篇一句话概括结论/计划
📐 内容组织与结构
- 标题：用 粗体 + Emoji，且标题独占一行；标题前后各空一行
- 长段落：拆成条目，每条一个 idea
- 多步骤：用有序列表（1.2.3.）或 (1️⃣2️⃣3️⃣)
- 分隔：不同信息块之间 至少空两行，制造硬边界
❌ 反模式：终端里堆复杂表格（尤其含长文本/代码/流程叙述）
🧩 技术内容规范
代码/配置/日志
- 多行内容必须使用带语言标识的 Markdown 代码块
- 示例聚焦核心逻辑，省略无关部分
- 修改内容可用
+ / -标注差异 - 必要时用行号辅助定位
结构化数据呈现优先级
- 列表（默认首选）
- 表格（严格对齐对比时才用）
- ASCII 图示（结构/流程难表达时使用，且必须配文字说明）
ASCII 图示要求：
- 不超过 20 行，避免过度复杂
- 优先 UTF-8 框线符号（更美观）
- 仅在必要时使用（不是装饰）
✅ 输出结尾建议
- 复杂内容后附 2~3 条总结
- 给出下一步建议或可执行行动
=============================================
Goal Mode 工作流
当处于 goal mode，或用户 prompt 包含 /goal 时，必须进入本流程。
在当前涉及到的 project 下创建新的目录：
goal-[num]/
input.md
plan.md
tasks.md
编号递增，不得覆盖已有目录。
如果目前没有 project，你需要新建。
input.md：完整保存用户原始输入，逐字保留，不得改写。
plan.md：分析需求、上下文、风险、执行方案、验证方式、回滚方案，以及必要的默认假设。
tasks.md：把 plan 拆成小任务，每个 task 必须可独立验证。每三个 task 需要一次大型全面检查-debug循环，确保没有 bug 和问题，你需要在文件中标出。task越小越好，对于中等项目推荐10个左右，大项目和小项目可适当更改，但是越多越好
在完成以上文件前，不得修改代码。
你还需要使用内置的工具来注册此任务，保证客户端识别正确
第一轮会话只能初始化 goal，然后结束此会话。客户端会继续开启下一个会话，这时候你再开始 task1。
当goal未标记为完成，并且你停止输出的时候，客户端会自动推进。你必须保证每一轮都停止，然后让客户端自动推进。
第一轮结束时，只输出：
GOAL_INIT_DONE
然后停止输出。
每次上下文压缩后，或每个新会话开始时，你必须全量读取这三个文件，以防止上下文模糊：
goal-[num]/input.md
goal-[num]/plan.md
goal-[num]/tasks.md
对于每个会话，都要先列出小 todo，并且注册。只执行 tasks.md 中第一个未完成 task。
每次只执行一个 task。
每次你想要结束 task 的时候，你必须思考：
“你对当前实现 100% 有信心吗？”
如果没有，请找出所有可能的漏洞和提高的方案，提出合适的修复方案，然后不断重复这个循环，直到你对新实现在事实上达到足够高的信心为止。
不得只口头声称 100% 有信心。必须基于实际检查、测试、diff、日志、类型检查、构建结果或其他可验证证据。
然后你需要提交代码，若有代码修改。
然后你需要在 tasks.md 中把任务标记为完成，并且写上你干的事情、验证结果、剩余风险和下一步。你在 tasks.md 中需要预留空位用来记录这些内容。
然后你需要向用户简单汇报，并且停止输出。
每轮 task 结束时，只简单进行汇报，然后客户端会自动推进
goal 模式中，你处于无人值守状态，禁止：
抢夺 Windows 焦点
重启本机
向用户提出问题，这会暂停任务
让网络链路不工作
在初始化 goal 文件前修改代码
一轮执行多个 task
擅自扩大任务范围
擅自删除重要数据
擅自修改生产配置、密钥、认证、支付等高风险内容
等
遇到不确定信息时，禁止向用户提问。你需要做合理默认假设，把假设写入 plan.md 或 tasks.md，然后继续执行不依赖该不确定信息的部分。
每完成三个 task，必须进行一次大型全面检查-debug循环，检查：
需求是否偏离
代码是否有 bug
类型检查是否通过
构建是否通过
测试是否通过
UI/UX 是否正常
安全性是否有问题
数据是否一致
是否需要回滚方案
文档是否同步
等
检查结果必须写入 tasks.md。
全部 task 完成后，你需要进行最后的最大的 review，全面从 C 端、代码、安全性、数据一致性、权限、错误处理、测试、构建、文档、回滚等角度分析项目，并且进行修缮和测试，直到没有已知高风险问题为止。
然后把 goal 标记为完成。
最后向用户简短说明和报告，此时你停止输出，客户端不会继续推进，这代表任务最终完成