wangcangxing/ai-eight-honors-eight-shames

AI 八荣八耻 · DSH Skill

Awesome DSH Plugin

已在 awesome-dsh-plugin 的 skill 分类收录 —— 条目由 PR #5732 于 2026-09-24 00:57（+08:00）合并。

面向 AI 编码代理的八条工作准则，打包成一个可直接安装的 Agent Skill（SKILL.md 格式）。

它不做别的事：在代理动手写代码、调用不熟悉的接口、判断业务规则、重构既有实现、以及准备说"已完成"之前，提供一组可核对的判据，用来挡住瞎猜、臆想、越权重构、跳过验证和假装理解；并要求每次用户提出需求或问题都在项目根留下简要记录（第 9 条：执行报告-首次运行.md 与 执行报告-变更记录.md；有改动就记改动，没改任何文件就写明）。

八条原文

以瞎猜接口为耻，以认真查询为荣。以模糊执行为耻，以寻求确认为荣。
以臆想业务为耻，以人类确认为荣。以创造接口为耻，以复用现有为荣。
以跳过验证为耻，以主动测试为荣。以破坏架构为耻，以遵循规范为荣。
以假装理解为耻，以诚实无知为荣。以盲目修改为耻，以备份重构为荣。

第 9 条（本仓库追加的交付纪律）

以交付无踪为耻，以留痕成报为荣 —— 报告固定两个文件、放在工作区根。工作区根怎么定（优先级从高到低，不可颠倒）：① 该目录有 .git/package.json 等项目标记、或已有报告 → 就用它；② 它只是容器而任务明确指向某子目录 → 用那个子目录；③ 判不出来才列一次一级目录兜底（不递归）。文件内容：执行报告-首次运行.md（先查找、没有才创建。读取优先级：首次运行.md ＞ 变更记录.md ＞ 实际目录结构。文件在 → 读它当唯一基线、严禁不必要地全量扫描；文件不在 → 受限扫描（跳过 node_modules/.git/dist/build/.vscode 等）后才建立。顶部必须记 最后一次核对时间 / 核对文件数量 / 一级目录；一级目录不符、或核心依赖文件比报告新 → 强制局部刷新并更新报告。且必须含「已知坑点（跨实例警示）」一节：只列至今仍有效的坑，每条写清「坑是什么 / 怎么触发 / 正确做法」，并在顶部元数据区加一行指针。首次运行报告走「体积软触发 + 职责划分」：任务启动时看一次体积，超过 ≈30 KB / ≈200 行就在本次任务提一次整理建议、等人类确认后再动；它只写当前有效内容——版本表只留最近 3 个 tag + 一行指向 gh release list，已失效坑点在下次刷新时删除（变更记录里已留痕））与 执行报告-变更记录.md（有界读：最新条目在最前，只读到覆盖核对时间的那一条，不读全文；不设体积上限，超过 ≈256 KB 才考虑归档；用户每次提出需求或问题都追加一条，把「用户输入」与「做出的更改」成对精简记录；没改动业务文件就写明「除本报告外，本次对话未对任何文件进行修改」——两份报告是元机制，不计入业务文件修改）。不刷时间戳文件；只存本地、不入库（把 执行报告-.md 加进 .gitignore，提交代码时排除这两个文件）。

1. 安装

五种方式任选其一，只装其一即可。推荐方式 1：装一次，所有项目都生效；方式 4 供没有 git、或需要 zip 上传的入口使用；方式 5 给「用插件管理器安装/升级」的 DSH 用户。想让它在每次开工前强制生效，见本节末尾的「附加」。

方式 1 · 用户级（全局生效）

Windows PowerShell：

git clone https://github.com/wangcangxing/ai-eight-honors-eight-shames "$env:USERPROFILE\.dsh\skills\ai-eight-honors-eight-shames"

macOS / Linux：

git clone https://github.com/wangcangxing/ai-eight-honors-eight-shames ~/.dsh/skills/ai-eight-honors-eight-shames

方式 2 · 项目级（只在该项目生效，优先级最高）

克隆到项目根目录下（项目根 = 最近的、包含 .git 的祖先目录；如果没有 .git，则取当前工作目录）：

git clone https://github.com/wangcangxing/ai-eight-honors-eight-shames "\.dsh\skills\ai-eight-honors-eight-shames"

方式 3 · 手工复制（不想用 git）

把本仓库的 SKILL.md 放到：

/ai-eight-honors-eight-shames/SKILL.md

见下表。

方式 4 · 下载 zip（没有 git，或要上传到要求 zip 的平台）

到 Releases 下载，两种结构都给了，按你的入口要求挑一个：

| 资产（ 即 Release 版本号，如 v1.0.1） | zip 内部结构 | 适用场景 |
|---|---|---|
| ai-eight-honors-eight-shames-.zip | ai-eight-honors-eight-shames/SKILL.md | 解压到 skills 根即可用；也是"上传一个技能文件夹"这类入口的常见约定 |
| ai-eight-honors-eight-shames--flat.zip | SKILL.md 位于 zip 根目录 | 给要求 SKILL.md 直接落在 zip 根的入口 |

第一种直接解压到 skills 根；第二种先建目录再解压：

/ai-eight-honors-eight-shames/      一层原则：SKILL.md 与 skills 根之间只能隔一层目录。套成 /a//SKILL.md 就不会被发现。

为什么给两种：各平台对 zip 内部结构的要求并不统一，而我没能核到官方原文（docs.claude.com 已跳转迁移）。两种都给，避免你在某个上传入口前才卡住——如果你的平台只认其中一种，删掉另一个即可。

方式 5 · DSH 插件（dsh plugin add）

本仓库同时是一个可安装的 DSH 插件：package.json 声明 dsh.bundle，cordis.patch.yml 插入一行，由 lib/index.js 把本仓库的 SKILL.md 注册进 ctx.skills。装进某个 profile 后，该 profile 的每个会话都能看到它：
bash
dsh plugin --profile  add github:wangcangxing/ai-eight-honors-eight-shames

- 正文只有一份：插件直接读仓库根目录的 SKILL.md，不复制第二份内容，所以「改正文即时生效」在插件方式下同样成立。
- 与方式 1–4 的关系：同名 skill 只显示一个，胜出顺序见第 2 节的 rank 表（插件注册为 250，高于用户级 400/500，低于项目根 100/200）；两处正文本来就相同，装重了不会出现两个条目。
- 什么时候值得用：你希望用插件管理器统一安装、升级与卸载，或你的入口只接受插件包形态。

附加 · 让它「开工前必读」（AGENTS.md 路线）

skill 是按需加载的：模型在会话目录里看到摘要，自己决定要不要加载。也就是说，只装 skill，它仍然可能“没被想起来”。

如果你希望这些准则每次开工前都必须已经在上下文里，办法不是改 skill，而是把它写进 DSH 的指令文件——这类文件由 @deepseek-ai/dsh-agent-instructions 在每个会话的第一个请求注入为持久基线，早于任何工具调用、早于 skill 目录刷新，模型无从“忘记加载”。本部署里这个插件已随 dsh-base 与 cordis preset 挂载，maxBytes: 65536。

| 作用范围 | 文件 | 说明 |
|---|---|---|
| 全局（所有项目） | $DSH_HOME/AGENTS.md（默认 ~/.dsh/AGENTS.md） | 用户级基线 |
| 单个项目 | /AGENTS.md（或 CLAUDE.md） | 项目根 = 最近的含 .git 的祖先；更具体者优先 |
| 本地覆盖 | /AGENTS.local.md、CLAUDE.local.md | 通常不提交的本地补充 |

写法建议：不要把 SKILL.md 全文复制进去——两处内容会各自漂移，改一处忘了另一处。正确做法是写九条的约束核心 + 一句强制加载指令：
markdown
开工前必读
在写或改任何文件、调用不熟悉的接口、重构、或声明「完成」之前，先用 skill 工具加载
ai-eight-honors-eight-shames，按其全文执行。核心底线：先查证再调用、有歧义先问、
业务只认事实、先复用再新造、结论必须带证据、按约定写、区分事实与推断、可回滚再改、
工作区根怎么定：① 有 .git/package.json 等标记或已有报告 → 用它；② 只是容器而任务指向某子目录 → 用子目录；③ 判不出来才列一次一级目录兜底。首次任务启动先查找 执行报告-首次运行.md：有就以它加变更记录为唯一基线、不再全量扫描；没有才受限扫描（跳过 node_modules/.git/dist/build/.vscode 等）后建立。每次有新需求或提问都留一条简要记录；有改动就记改动，没改动业务文件就写明「除本报告外，本次对话未对任何文件进行修改」（两份报告是元机制，不计入业务文件修改）。报告顶部记核对时间与文件数，过期就局部刷新。执行报告-变更记录.md 有界读：最新条目在最前，只读到覆盖核对时间的那一条，不读全文。执行报告-首次运行.md 超过 ≈30 KB / ≈200 行时本次任务提一次整理建议、等人类确认；它只写当前有效内容（版本表只留最近 3 个 tag + 一行指向 gh release list，已失效坑点下次刷新时删）。变更记录不设体积上限，超过 ≈256 KB 再考虑归档。首次运行报告还必须含「已知坑点（跨实例警示）」一节：只列至今仍有效的坑，每条写清坑是什么 / 怎么触发 / 正确做法，并在元数据区加一行指针。

两点成本说明：

- 基线每个会话注入一次并留在历史里直到压缩，不是每个请求都重发；
- 总量受 maxBytes 限制，超预算时先丢更宽的整份文件，最后才截断最具体的那份。

权威级别：AGENTS.md 属于工作区指导（guidance），不覆盖系统、开发者与用户的直接指令。它比“等模型自己想起某个 skill”强得多，但不是内核级强制。

2. 安装位置与优先级

harness 会扫描若干 skills 根目录，rank 数字小者胜出（同名 skill 由更靠前的根覆盖）：

| rank | 来源 | 路径 | 说明 |
|---|---|---|---|
| 100 | project-dsh | /.dsh/skills | 项目私有 |
| 200 | project-agents | /.agents/skills | 项目内跨 agent 共享 |
| 250 | runtime | 插件注册（dsh plugin add，见方式 5） | 由插件把包内 SKILL.md 注册进 ctx.skills；无目录，正文读的是包内文件 |
| 300 | custom | customSkillDirs 配置项 | 自定义根，需在组合里配置 |
| 400 | user-dsh | /skills（默认 ~/.dsh/skills） | 用户级，全局生效 |
| 500 | user-agents | /skills（默认 ~/.agents/skills） | 跨 agent 共享 |
| 600 | bundled | bundledSkillDir 配置项 | 随发行版打包的 skill |

两个细节：

- user-dsh 根会跳过它的 .system 子目录。
- 想把 skill 只提供给某一个 agent preset，可以配置 bundledSkillDir 指向本仓库。

这些根目录里的 skill 由 @deepseek-ai/dsh-skill-filesystem 发现，它同时监听这些目录：新增、改名、删除 skill（或改 frontmatter）会自动刷新会话里的 skill 目录，不需要重启。

3. 目录结构要求（最容易踩的坑）

发现逻辑只扫一层，只认这两种形态：

/ai-eight-honors-eight-shames/SKILL.md   ✅ 目录包
/ai-eight-honors-eight-shames.md         ✅ 平铺单文件
/foo/ai-eight-honors-eight-shames/SKILL.md  ❌ 嵌套，不会被发现

所以本仓库的根目录就是 skill 包目录：SKILL.md 放在仓库根，clone 到 // 正好落在被扫描的位置。仓库里的 .git、README.md 等都不会被当作 skill 读取，放在一起是安全的。

4. frontmatter 契约（改内容前必读）

SKILL.md 必须以 YAML frontmatter 开头：
markdown

name: ai-eight-honors-eight-shames
description: 一句话说明这个 skill 干什么、什么时候该用，模型靠它决定要不要加载。
whenToUse: 可选，补充触发时机。

正文……

| 字段 | 必填 | 规则 |
|---|---|---|
| name | ✅ | 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)$（小写 kebab-case，不能有大写、下划线、空格） |
| description | ✅ | 会话目录里最多渲染 500 字符，超出会被截断，所以把"什么时候用"写在前面 |
| whenToUse | ✕ | 可选，字符串 |
| metadata | ✕ | 可选，对象 |
| disable-model-invocation | ✕ | 可选，布尔。为 true 时模型看不到它 |
| user-invocable | ✕ | 可选，布尔。为 false 时人类命令里不出现 |

调 surfaces 的四种组合：

| disable-model-invocation | user-invocable | 模型可用 | 人类可用 |
|---|---|---|---|
| 省略 | 省略 | ✅ | ✅ |
| true | false | ❌ | ❌ |
| true | 省略 | ❌ | ✅ |
| 省略 | false | ✅ | ❌ |

布尔值支持 YAML 布尔，以及大小写不敏感的 true/false、yes/no、on/off、1/0。拼错或写成非布尔值，整个 skill 会被丢弃（不只是该字段失效）。

三条硬性失败条件，踩中任何一条该文件都会被静默跳过（只在 harness 日志里 warn，会话目录里表现为"这个 skill 不存在"）：

1. 文件带 UTF-8 BOM —— 首行就不再等于 ---；
2. 文件第一行不是 ---，或缺少结束的 ---；
3. 缺 name / description，或 name 不满足上面的正则。

5. 验证是否生效（装完请做这一步）

1. 看会话目录：新的用户消息里会出现 skill 目录，其中应包含 ai-eight-honors-eight-shames。
2. 直接加载：让代理调用 skill 工具，参数 name = "ai-eight-honors-eight-shames"。加载成功会返回完整正文；失败会报 skill "..." is unknown or no longer available。

不生效时的排查顺序：

| 现象 | 先查这里 |
|---|---|
| 目录里没有它 | 路径层级是否多了一层（第 3 节）； 是否写对 |
| 目录里有、加载报错 | name 是否与调用时完全一致（含连字符） |
| 到处都没有 | frontmatter 是否带 BOM / 首行不是 --- / name 不合正则 |
| 模型看不到它 | 是否被 disable-model-invocation: true 关掉了 |
| 描述被截断 | description 是否超过 500 字符 |

6. 更新与卸载
bash
更新到最新
git -C "/ai-eight-honors-eight-shames" pull

卸载：删掉整个目录即可

用方式 5（插件）装的，则按插件方式管理：
bash
更新
dsh plugin --profile  add github:wangcangxing/ai-eight-honors-eight-shames

卸载
dsh plugin --profile  remove ai-eight-honors-eight-shames

修改内容只需编辑 SKILL.md：

- 改正文：立即生效，每次加载都重新读文件，无需重启、无需清缓存；
- 改 frontmatter：会触发会话 skill 目录刷新。

想加自己的准则，直接在第 9 条后面续写 ## 10. ... 并同步更新末尾的自检清单即可；如果想让它成为你自己账号下的版本，先 fork 再改。

别删：仓库里的赛博纪念碑

执行报告-20260921-1305.md 是本仓库唯一有意保留在仓库里的执行报告，立为赛博纪念碑：
- 它是第 9 条第一次被执行时的原始留痕——第 9 条由那次执行写下，报告也由它产出，等于这份准则的出生证明；
- 自 2026-09-23 起，另两份报告（执行报告-首次运行.md、执行报告-变更记录.md）改为只存本地、不入库；本文件是有意的例外，.gitignore 用 !执行报告-20260921-1305.md 专门把它排除在忽略规则之外；
- 所以它不是漏删、不是「规则缺口」：请勿删除、勿 git rm --cached。真要拿它做别的事，属人类决策；
- 它不随发布 zip 分发（.gitattributes 的 export-ignore）——碑立在仓库里，不在发行物里；若想让它随包分发，删掉 .gitattributes 里那一行 export-ignore 即可；
- 碑下原文除开头「源文件夹」的本机账户名脱敏为  外一字未改，另在顶部加了一段铭文；原始字节由 git 历史保存。

7. 同类项目（不声称首创）

「八荣八耻」在 AI 编码代理圈子里已被多个仓库实现过，本仓库不声称首创这条准则本身。本仓库的差异只有一个：它是 DSH 原生的——安装位置、优先级、frontmatter 契约都按本 harness 的实际发现逻辑（@deepseek-ai/dsh-skill-filesystem）逐条核验过，而不是照搬别的工具的约定。

如果你用的不是 DSH，下面这些项目可能更合适：

| 项目 | 定位 |
|---|---|
| claude-code-eight-principles | Claude Code 向，中英双语，带 eval |
| code-honor-skill | skills 目录 + 测试提示词 |
| cc-eight-honors-and-shames | Claude Code 插件形态 |
| agent-rongchi | 跨 Codex/Claude 的多语言实现 |
| coding-standard-skill | 八荣八耻 + 多编辑器适配 + Git 规范 |

8. 与配套 skill 并用：优先级与裁决

本准则不谈「该写多少代码」——那件事交给配套 skill。推荐 Ponytail（MIT，14 万★ 量级）：它用一条七级阶梯回答「能不能不做 / 能不能一行」。

两段式顺序（先用哪个）

1. 先用本 skill 问「这事该不该做」 —— 第 1 条要查证依据、第 2/3 条要事实与人类确认、第 4 条要「先搜复用」。它决定要不要做、凭什么做。
2. 再用 Ponytail 问「能不能一行做完」 —— 它决定做多小：① 该不该存在 ② 代码库里已有 ③ 标准库 ④ 平台原生特性 ⑤ 已装依赖 ⑥ 一行 ⑦ 最小实现。

顺序不能反：先按 Ponytail 想「怎么最省」，容易把一个还没搞懂的问题草草做小；先按本 skill 把事实与边界弄清，再谈做多小，才安全。（Ponytail 自己也写了这条：「对理解问题绝不偷懒，阶梯只缩短方案，不缩短阅读」。）

冲突裁决（两边都想管同一件事时）

| 冲突点 | 谁赢 | 依据 |
|---|---|---|
| Ponytail「代码优先、解释 ≤3 行」 vs 本 skill 第 9 条要求执行报告 | 本 skill | Ponytail 自己写明：用户明确要求的解释（报告、走查、分阶段笔记）不算债务，应完整给出 |
| Ponytail ultra「先 ship 再质疑」「别停在你能默认的答案上」 vs 本 skill 第 2/3 条「有歧义先问、不臆想业务」 | 本 skill | 需求与业务口径属于「影响结果的分歧」，必须先确认；建议 Ponytail 停在 lite/full |
| 非编码任务 | 本 skill（Ponytail 不覆盖） | Ponytail 明写「非 coding 请求不要用」 |
| 能否省掉校验／错误处理／安全／可访问性 | 都不能 | 两边一致：Ponytail 明写这些永不简化；本 skill 第 5/6 条要求验证与合规 |

安装 Ponytail（DSH 环境）
powershell
1) 克隆留档（便于更新与溯源）
git clone https://github.com/DietrichGebert/ponytail "$env:USERPROFILE\.dsh\third-party\ponytail"

2) 把 6 个 skill 装进 DSH 的 skills 根
Copy-Item "$env:USERPROFILE\.dsh\third-party\ponytail\skills\*" "$env:USERPROFILE\.dsh\skills\" -Recurse -Force

装完多出 6 个 skill：ponytail、ponytail-review、ponytail-audit、ponytail-debt、ponytail-gain、ponytail-help。

⚠️ 一处必须做的改动：Ponytail 主 skill 的 description 原文 826 字符，超过 DSH 会话目录的 500 字符上限，会被截断并丢掉后半段触发词（yagni、do less、过度工程等）。安装时需把该字段压到 500 以内（本机用的是 444 字符版本；其余 frontmatter 字段与正文与上游逐字节一致）。git pull 更新上游后需要重做这一步。

9. 致谢

特别感谢 DietrichGebert/ponytail 项目对本项目给予的灵感。
这份准则原本只关心「怎么把事实弄准、怎么把改动留痕」，对「该不该写、该写多小」没有立场。是 Ponytail 把「屋里最懒的资深工程师」这个视角摆到台面上——最好的代码是你从没写过的代码——并把它做成一条可执行的七级阶梯（该不该存在 → 库里已有 → 标准库 → 平台原生 → 已装依赖 → 一行 → 最小实现）。

它直接影响了本项目的三处：

| 影响 | 落在哪里 |
|---|---|
| 「先问该不该存在」（YAGNI）成为第 4 条的第一级 | SKILL.md 第 4 条 |
| 「刻意的简化要留痕」：写明上限与升级触发条件（借鉴 ponytail: ,  标记） | SKILL.md 第 9 条「借力」 |
| 「两段式顺序」与冲突裁决：先用本准则定「该不该做」，再用 Ponytail 定「能不能一行」 | 本 README 第 8 节 |

同样值得学的是它对自身数据的诚实：README 主动推翻了自己早期「80–94% 更少代码」的宣传，注明那是单发基准下的每任务上限而非平均值，并引用了批评它的 issue #126。这与本准则第 7 条（以假装理解为耻，以诚实无知为荣）同源。

Ponytail 为 MIT 许可（© 2026 DietrichGebert），与本项目许可兼容。本项目是独立实现，未包含也未派生 Ponytail 的代码与文本——这里引用的是它公开文档所描述的机制，属致谢与出处说明。

10. 许可

MIT © 2026 wangcangxing

可自由使用、修改、分发、商用，保留版权与许可声明即可。八条准则的内核来自网络流传的「AI 八荣八耻」说法，MIT 只覆盖本仓库的正文、判据与文档。