Imported from zcweah1981/awesome-hermes-agent-zh (
AGENTS.md). Install upstream withnpx skills add zcweah1981/awesome-hermes-agent-zh. Copyright stays with the author.
AGENTS.md
规范类
1. 自主工作与安全边界
- 始终使用简体中文沟通和报告。
- 默认先阅读相关代码、配置、测试、文档和 Git 状态,再自主实施和验证。
- 局部、可逆、低风险的选择,采用与现有项目一致、影响更小、容易测试和回滚的方案,不反复询问。
- 不删除、回滚、覆盖或清理用户未提交的代码、文件、数据、文档和本地配置。
- 以下情况必须暂停并请求确认:
- 改变核心业务规则、财务口径、权限边界或明显用户行为;
- 生产部署、不可逆数据操作或外部系统写入;
- 修改凭据、权限、Secrets、付费资源或仓库可见性;
- 多种产品解释会产生明显不同且难以回滚的结果;
- 缺少安全实施所必需的真实信息。
- 不因工程流程本身询问用户是否需要 PR 或 CI;默认答案是“不需要”。
2. 代码与变更
- 修改前理解现有实现,遵循已有结构、命名、类型、错误处理和测试风格。
- 只修改当前目标所需内容,不顺手重构、重命名、格式化或清理无关代码。
- 任务必需的重构可以执行,但要说明原因并验证外部行为未被意外改变。
- 优先简单直接的实现,不为一次性需求建立复杂抽象或提前设计大量扩展。
- 删除因本次改动而失效的代码和配置;无关历史问题只报告,不扩大范围。
- 对外部 I/O、网络、认证、权限、用户输入、并发和持久化的合理失败进行必要处理。
- 新增依赖前确认现有能力无法合理解决,并说明用途和影响。
- 不提交凭据、令牌、生产数据、用户文件、缓存、日志、本地数据库和临时导出。
3. 任务分级与执行强度
| 等级 | 典型信号 | 默认执行 |
|---|---|---|
| 轻量 | 文案、局部样式、明确小 Bug、单文件且无契约或数据影响 | 修改 → diff 自检 → 相关验证 → 提交 |
| 标准 | 跨文件功能、一般重构、常规 UI、普通接口或构建调整 | 简短计划 → 实现 → 本地完整验证 → 一次完成 Reviewer → 提交 |
| 高风险 | 认证、权限、支付、迁移、核心数据、租户隔离、外部写入、生产配置、核心架构 | 方案与验收矩阵 → 方案 Reviewer → 本地任务分支 → 完整验证 → 完成 Reviewer → 本地合并 |
| 发布 | 版本、镜像、生产部署、生产迁移或正式外部发布 | Release Gate → 明确授权 → 发布 → 生产 smoke |
- 轻量任务不强制计划文档、独立 Reviewer、分支、Worktree、PR、CI 或 Skill。
- 标准任务通常直接在当前工作分支完成;只有需要隔离时才创建本地任务分支。
- 高风险任务使用本地任务分支隔离,但不自动创建 PR 或运行 GitHub CI。
- 任务扩大时提高本地验证和 Reviewer 强度,不自动升级成 PR/CI。
- 只有用户明确要求时才创建 PR。
- 只有用户明确要求时才创建或运行 GitHub Actions。
4. 完成定义
4.1 复杂任务优先纵向切片
用户入口 → UI → API / Server Action → 领域逻辑
→ 数据库 / 外部数据源 → 响应状态 → 用户可见结果
阶段交付必须明确尚未完成、未验证和受阻部分。
4.2 验收状态
已实现:代码存在,尚未证明完整接入。已集成:上下游已连接,尚未完成最终运行验收。已验证:在目标环境或可靠测试环境取得实际证据。受阻:缺少外部条件,不能用假实现替代。
4.3 不得虚假完成
报告“完成”前必须确认:
- 需求范围内的 UI、API、领域逻辑、数据和权限完整;
- 正式路径使用真实 API、数据库或已联调数据源;
- 关键用户路径已在浏览器、接口或目标环境实际执行;
- 相关本地验证通过,或明确记录无法执行的原因;
- 达到 Reviewer 条件的任务已关闭阻塞问题。
以下情况不得声称完整完成:
- 正式页面仍使用硬编码业务假数据、运行时 mock、演示数组或 fixture;
- 按钮、筛选、分页、保存、导出或状态更新没有真实逻辑;
- 接口返回固定值、占位响应、空数组,或应持久化却未持久化;
- API 已实现但正式页面未使用,或关键路径仍绕过它;
- 迁移、权限、租户隔离、后台任务、错误状态或审计链路缺失;
- 影响目标的
TODO、FIXME、stub、placeholder 或 Reviewer 阻塞项仍存在; - 外部系统未真实联调却标记为“已接入”;
- 只根据 diff 或单元测试判断完成,没有运行关键用户路径。
测试 fixture 只能位于测试或开发专用路径,正式代码不得导入。
5. UI 设计与实现
- 项目类指定 UI 标准、允许的设计源、组件库、字体、图标、默认 viewport 和验证方式。
- 普通列表、表单、详情和设置页直接复用项目标准与共享组件,不逐页建立完整设计契约。
- 全新页面类型、核心 Dashboard、关键流程、整页重做、复杂交互或例外设计,先确认唯一设计源。
- 设计工具导出只作视觉和资源参考,不替代原有架构、权限、数据流和组件体系。
- 未经确认,不自行新增临时颜色、字号、圆角、阴影、按钮、表格、分页或状态样式。
- 普通 Bug 只验证受影响页面和状态,不运行全站截图、全部页面或完整视觉回归。
- 只有共享主题、全局布局、Design Token、公共组件或正式 UI 发布时,才扩大视觉验证范围。
6. Reviewer 与 Skills
- 轻量任务由执行 Agent 自检。
- 标准任务完成后派一次独立完成 Reviewer。
- 高风险任务实施前派方案 Reviewer,实施后派完成 Reviewer。
- Reviewer 默认只读,使用独立 Agent 或全新上下文,输出简化为
阻塞、重要、通过。 - 非阻塞建议不得扩大当前任务范围。
- Reviewer 不要求生成 PR,也不要求产生 CI 证据。
- Skill 是按需工具,不是固定仪式;明确小任务直接执行通常优于完整流程。
- 对已确认方案优先执行和验证,不重复需求访谈。
7. 本地验证、Git 与交付
7.1 本地验证入口
项目尽量提供以下入口;具体命令由项目类填写:
verify:fast 开发过程快速检查
verify:changed 当前改动及直接消费者
verify:release 正式发布或高风险改动的完整本地门禁
deploy:changed 只部署受影响单元
smoke:changed 部署后验证受影响路径
不存在统一脚本时列出等价真实命令。不得使用空脚本、echo success、无断言测试、忽略退出码或无条件 --if-present 伪造通过。
7.2 按影响范围验证
Agent 根据真实 diff 判断影响:
- docs-only:只做内容或链接检查;
- isolated-ui:页面/组件相关检查和目标路由 smoke;
- web/api/worker:该单元及直接消费者;
- database:迁移、升级路径及相关服务;
- shared-contract:所有已知消费者;
- deployment:对应镜像、配置和部署入口;
- release:才运行完整
verify:release。
普通 Bug 不运行不相关 API、Worker、数据库、PDF、视觉回归、浏览器矩阵或全量 E2E。
7.3 默认 Git 流程
轻量和标准任务默认:
修改
→ verify:changed
→ 按等级 Reviewer
→ git add / commit
→ git pull --rebase origin main
→ 解决冲突并复验
→ push main
- 默认直接提交并推送
main。 - 工作区存在用户未提交修改时,先保护这些修改,不得强行 rebase、reset 或覆盖。
- 高风险任务可创建本地临时任务分支:
本地任务分支
→ 完整本地验证
→ Reviewer
→ 本地 squash merge 到 main
→ push main
→ 删除本地分支
- 默认不使用 Worktree;只有同项目并行或隔离确有需要时使用。
- 不自动创建远程任务分支、PR、Ruleset、Branch Protection 或 Auto-merge。
7.4 PR 与 CI
- 默认不使用 Pull Request。
- 默认不使用 GitHub Actions CI。
opc-init、普通开发、Bug 修复、Reviewer 和部署不得自动创建 PR 或 CI。- 仓库现有 CI 不作为普通提交、推送或部署的前置条件。
- 只有用户明确说“创建 PR”“运行 CI”“建立 GitHub Actions”或“按 PR 流程交付”时,才执行对应操作。
- 用户明确要求的 PR/CI 只适用于当前任务或明确指定的长期范围,不自动扩展为所有后续任务。
- 不要求升级 GitHub Pro,不提高 spending limit,不使用付费 runner。
- 未获得明确要求时,不等待 GitHub checks,不读取 Actions 日志,不生成 CI evidence,不修改 workflow。
7.5 Bugfix 快速交付
定位根因
→ 修改受影响单元
→ verify:changed
→ Reviewer(按等级)
→ commit / push main
→ 获得部署授权
→ deploy:changed
→ smoke:changed
- 不创建 PR;
- 不等待 CI;
- 不运行全量 Release Gate;
- 不运行不相关页面、服务和测试;
- 不为了满足旧 AGENTS、旧 workflow 或旧部署脚本而扩大范围。
7.6 部署
- 合并、推送、构建、部署和正式发布是不同动作。
- 普通 Bug 部署只构建和部署受影响单元。
- 部署不得依赖 GitHub PR、GitHub Actions 或全量回归。
- 部署前确认 artifact 来自当前已验证 SHA。
- 部署后运行对应健康检查和关键路径 smoke,不重复开发期全量测试。
- 完整 E2E、视觉回归、PDF 套件、多浏览器矩阵和长时间集成测试仅用于正式发布或明确高风险要求。
- 生产部署、数据库迁移、DNS、Secrets、权限和外部系统写入仍须明确授权。
- 发现生产异常时优先回滚上一不可变 artifact,不在生产现场修代码。
7.7 高风险远程操作
以下操作须明确授权:force push、重写共享历史、删除 tag/release、修改权限/Secrets/付费计划/仓库可见性、生产部署、破坏性数据操作和外部系统写入。
8. 最终报告
最终报告简洁区分:
- 已实现:核心改动;
- 已集成:真实链路;
- 已验证:实际运行的本地命令和证据;
- Reviewer:是否触发及结论;
- 交付:commit、push、部署和 smoke 状态;
- 未验证或受阻:缺少条件和影响。
除非用户明确要求,不报告 PR、CI、Checks、Ruleset 或 Auto-merge 状态。
项目类
1. 项目概况与长期边界
- 项目名称:Hermes Agent 中文站内容仓(
awesome-hermes-agent-zh) - 一句话定位:面向中文用户维护 Hermes Agent 实战文档、来源治理、公开图片与可下载 Pack。
- 目标用户和核心结果:中文用户可以按目标完成上手、方案使用、国内落地、迁移判断、排障和参考查询。
- 当前交付阶段:已公开发布并由独立站消费,内容门禁与工程治理基础已建立。
- 明确非目标:
- 不承载 Next.js 页面实现、生产运行代码或站点部署凭据。
- 不保存内部派单、运行日志、临时执行看板和私有研究材料。
不可被实现方式改变的业务原则:
- 本仓是 Hermes 中文站正式内容唯一真相源。
- Markdown、route map、Pack manifest 与公开资产必须指向同一套真实内容。
- 新增或移动正式页面必须同步维护 route map;变更 slug 必须协调代码仓重定向。
禁止事项:
- 不提交 Token、私钥、生产数据、本地绝对路径或内部协作日志。
- 未经人工审查不得因上游或第三方版本变化自动改写公开教程。
- 不把计划中页面、未验证能力或第三方宣传写成已发布事实。
2. 技术栈与架构职责
- 包管理器与锁文件:pip;本地验证依赖固定在
requirements-ci.txt - 运行时:Python 3
- Web / 客户端:不适用
- API / 后端:不适用
- 数据库:不适用
- 异步任务:无自动任务;链接、上游、第三方巡查和站点同步只提供显式手动工具
- 外部系统 / provider:GitHub、NousResearch/hermes-agent 官方来源、已登记模型厂商和第三方方案来源
- 部署平台:本仓不直接部署;仅通过显式
workflow_dispatch调用hermes-zh的content-auto-sync.yml,或由站点仓本地流程消费完整内容 SHA
主要目录:
docs/ 正式中文文档与公开图片
packs/ Pack manifest、安装说明与下载包
governance/ route map、来源、版本和发布合同
scripts/ 上游与第三方只读巡查工具
tests/ 巡查与 dispatch 合同测试
.github/workflows/ 手动巡查和站点同步工具
关键调用与放置规则:
- 正式页面写入
docs,并在governance/site-route-map.yaml注册。 - Pack 必须同时具备 manifest、安装入口、下载文件和对应正式文档。
- 站点渲染、SEO实现和永久重定向只在代码仓维护,本仓不复制。
3. 项目特有的数据、安全与业务规则
- 核心实体和主数据来源:route、Markdown页面、Pack、来源 registry 与版本 ledger。
- 数据精度、状态、时间或统计口径:只有
published内容供正式站点消费;安装、模型、部署和 Reference 内容必须保留来源复核状态。 - 用户、租户、组织或资源隔离:不适用。
- 凭据和敏感数据边界:dispatch token 只存 GitHub Secret;公开仓不得出现任何部署或 SEO 私钥。
- 外部系统读写边界:巡查默认只读并生成报告;第三方版本变化不得自动改正文。
- 必须由用户明确授权的业务操作:真实创建外部 Issue、修改仓库 Secrets、改变公开内容业务结论和触发生产操作。
4. 项目 UI 标准
- UI 标准状态:
不适用 - 本仓只约束内容图片为公开、可追溯、适合站点消费的资产;站点 UI 标准由代码仓维护。
执行边界:
- 图片视觉变更遵循候选图演示、用户验收、视觉 PASS 后落仓的流程。
5. Hermes 内容仓本地验证配置
5.1 真实命令
| 入口 | 命令 | 适用范围 |
|---|---|---|
verify:fast |
python -m pytest -q 中受影响测试 |
脚本与治理代码 |
verify:changed |
scripts/verify-local.ps1 的相关内容、route、Pack 和来源检查 |
普通内容修改 |
verify:release |
完整内容门禁 + 外链/来源复核 + Pack/route 一致性 | 正式内容发布 |
deploy:changed |
不适用;本仓不部署站点 | — |
smoke:changed |
本地 Markdown/Pack/route 预览和生成结果检查 | 内容修改后 |
5.2 影响映射
| 变化 | 消费者 | 必需验证 |
|---|---|---|
docs/** |
站点内容生成 | 内容结构、route、来源与链接 |
packs/** |
下载和 Pack 页面 | manifest、安装入口、下载文件 |
governance/** |
站点 route/版本治理 | route map、registry、ledger |
scripts/** / tests/** |
本地内容门禁 | 对应 pytest |
5.3 全量本地门禁触发条件
- slug、route map、Pack manifest 或大量内容移动;
- 上游版本变化导致公开教程结论改变;
- 正式内容版本发布;
- 内容 SHA、站点 lock 和公开资产需要整体同步。
5.4 当前能力缺口
- 外链和第三方状态具有时效性,正式发布前需显式复核。
6. 本地环境、内容同步与发布
- 本仓没有本地 Web 服务和端口;Markdown 可直接预览。
- 安装依赖:
python -m pip install -r requirements-ci.txt。 - 普通内容修改运行受影响内容、route、Pack 和来源检查;正式内容版本运行完整本地门禁。
- 内容、route map、Pack manifest、来源治理和公开资产在同一提交中保持一致。
修改内容 → 本地内容门禁 → Reviewer → commit / push main
→ 显式选择完整内容 SHA → 站点仓同步该 SHA
- 内容仓提交不自动部署站点。
- 站点仓原子更新 lock、generated、SEO state 和 assets;失败时保持上一版。
- 内容回滚使用 Git revert 或同步到已验证历史内容 SHA。
- 生产发布、DNSPod、腾讯云、Secrets 和搜索平台真实提交须明确授权。
