awesome-hermes-agent-zh

Imported from zcweah1981/awesome-hermes-agent-zh (AGENTS.md). Install upstream with npx skills add zcweah1981/awesome-hermes-agent-zh. Copyright stays with the author.

AGENTS.md

规范类

1. 自主工作与安全边界

• 始终使用简体中文沟通和报告。
• 默认先阅读相关代码、配置、测试、文档和 Git 状态，再自主实施和验证。
• 局部、可逆、低风险的选择，采用与现有项目一致、影响更小、容易测试和回滚的方案，不反复询问。
• 不删除、回滚、覆盖或清理用户未提交的代码、文件、数据、文档和本地配置。
• 以下情况必须暂停并请求确认：
  • 改变核心业务规则、财务口径、权限边界或明显用户行为；
  • 生产部署、不可逆数据操作或外部系统写入；
  • 修改凭据、权限、Secrets、付费资源或仓库可见性；
  • 多种产品解释会产生明显不同且难以回滚的结果；
  • 缺少安全实施所必需的真实信息。
• 不因工程流程本身询问用户是否需要 PR 或 CI；默认答案是“不需要”。

2. 代码与变更

• 修改前理解现有实现，遵循已有结构、命名、类型、错误处理和测试风格。
• 只修改当前目标所需内容，不顺手重构、重命名、格式化或清理无关代码。
• 任务必需的重构可以执行，但要说明原因并验证外部行为未被意外改变。
• 优先简单直接的实现，不为一次性需求建立复杂抽象或提前设计大量扩展。
• 删除因本次改动而失效的代码和配置；无关历史问题只报告，不扩大范围。
• 对外部 I/O、网络、认证、权限、用户输入、并发和持久化的合理失败进行必要处理。
• 新增依赖前确认现有能力无法合理解决，并说明用途和影响。
• 不提交凭据、令牌、生产数据、用户文件、缓存、日志、本地数据库和临时导出。

3. 任务分级与执行强度

• 轻量任务不强制计划文档、独立 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 不得虚假完成

报告“完成”前必须确认：

1. 需求范围内的 UI、API、领域逻辑、数据和权限完整；
2. 正式路径使用真实 API、数据库或已联调数据源；
3. 关键用户路径已在浏览器、接口或目标环境实际执行；
4. 相关本地验证通过，或明确记录无法执行的原因；
5. 达到 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 真实命令

5.2 影响映射

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 和搜索平台真实提交须明确授权。