2026-08-26 ｜ 开源项目自述 ｜ 全文约 3800 字 ｜ 项目地址：https://github.com/zxc663/shisan-xinuo-workflow
一、为什么会有这个项目
从 6 月到 8 月，三个月的摸索加中度使用。最早接触 Agent 是 Trae，对新手很友好，还有免费额度。没看教程，全靠自己踩坑摸索，慢慢接触到规则、提示词工程、Skill、MCP，以及怎么用自然语言精准描述各类组件细节。再后来换到 Codex，对比下来体验差距特别大——不管是内置工具还是提示词的差别，它的成品和执行过程就是让人意外地觉得舒适。
这让我意识到：Token 消耗多少其实不重要，Token 能真正办成事才是核心。
但在反复切换不同 Agent 工具之后，就发现一个很现实的问题：同一个或者不同 Agent 的行为逻辑差异巨大。同样的需求，在 A 工具上执行很稳，换到 B 工具就容易出现假完成、上下文失忆、乱改文件、高危操作直接执行，大量 Token 被浪费在反复纠错、修复模型闯出来的祸上。
后面学着给 Agent 加规则，确实能限制一点，但总不能想到什么是什么。于是我去查、去实践中总结，最后发现：市面上的大部分 Skill 都是给 Agent「增加新能力」——写代码、做调试、生成方案；但很少有东西去「约束 Agent 的行为本身」。
于是我把这三个月踩过的坑、实战沉淀出来的整套工作约束整理出来，做成了 shisan-xinuo-workflow——一套跨平台的「工程治理元技能」，全量 43 条工作纪律。它不是用来新增酷炫垂直能力的插件，而是一套通用的元 Skill，一套 Agent 的工作纪律规范。
二、它是什么
一句话：一个可安装的目录，教会任意 Agent 平台（Trae / Codex / Claude Code / Cursor / Windsurf / WorkBuddy / 通用 CLI）按统一、可审计的方式工作——按风险分级任务、关键决策必问、交付前验证、重大改动前建回滚点、结论即时落盘、绝不假实现。
它基于 Agent Skills 开放标准（agentskills.io）构建，纯文档、零依赖、零脚本、零网络，安装即复制目录，MIT 协议，不对外发送任何数据。
仓库结构
shisan-xinuo-workflow/
├── skill/shisan-xinuo-workflow/ ← 默认交付（英文版）
│ ├── SKILL.md ← 精简主入口（渐进式披露）
│ └── references/ ← 按需加载：rules / workflows / platform-adaptation / security
├── versions/
│ ├── universal-zh/ ← 通用版 · 中文
│ └── universal-bilingual/ ← 通用版 · 中英双语
├── README.md ← 双语门面（定位 / 快速体验 / 差异 / 局限 / 安装 / FAQ）
├── LICENSE ← MIT
└── 项目信息.md ← 维护者交接文档
三个通用版本内容完全一致，仅语言不同。个人工作台版（内嵌个人踩坑经验、完整双模式表、中文表达规则）在独立私有仓库维护，不进入公开仓——这是刻意设计的「双仓隔离」。
三、它做什么（核心能力）
- 第 0 步平台适配：加载即检测平台（Codex / Claude Code / Cursor / Trae / Windsurf / WorkBuddy / 通用 CLI），生成精简且合并安全的规则文件（
AGENTS.md、CLAUDE.md、.cursor/rules/*.mdc等）。已有规则先备份再合并，绝不覆盖。 - 43 条工作纪律（L1/L2/L3 任务分级、双模式、复用五问决策链、质量门禁、密钥红线、留档纪律），按渐进式披露组织——
SKILL.md保持精简，references/按需加载。 - 关键必问协议：平台无原生提问工具时，提供通用结构化文本兜底协议。
- 回滚安全：重大修改 / 不可逆操作前必须先建回滚点（commit / stash / 快照），高危命令执行前同样要求。
- 双模式：普通模式（关键决策必问）+ 目标模式（关键词
目标：/目标模式/无人值守→ 按计划自主执行，密钥与破坏性操作仍暂停等待确认）。 - 上下文缺失自检：Agent 无法感知自己被压缩，因此不靠感知、靠两道守卫——显式信号（用户说「重载」/ 平台重置）即重读；开工 / 提交 / 重大决策前默写核心要素，复述不全即重读。
四、差异化优势
| 对比对象 | 本 Skill |
|---|---|
手写 AGENTS.md / CLAUDE.md |
增加渐进式披露（精简预加载 + 按需细节）、完整引用体系与跨平台适配逻辑——不止一页规则，且不拖累每个会话 |
| 平台内置规则 | 平台无关：同一纪律在任何平台上生效；第 0 步自动适配，无需逐平台重写 |
| 通用系统提示词 | 可操作、可验证、清单驱动：分级表、回滚流程、扫描清单——不是空泛口号 |
| 官方技能仓库 | 补位「通用工作流治理」品类：官方仓库领域技能丰富，跨领域工作纪律稀缺 |
五、43 条纪律里最核心的 10 条
如果只记住 10 条，就是这些：
- 绝不假实现 —— 未完成 / 未验证必须显式标注，这是整个项目的第一铁律。
- 第 0 步平台适配无例外 —— 每次加载先检测平台、生成精简规则文件、备份合并不覆盖，再开工。
- L1/L2/L3 三级分级 + 普通 / 目标双模式 —— L1 直接做不打扰，L3 密钥 / 删除 / 发布必问；目标模式可无人值守但密钥和破坏性操作仍锁死。
- 重大修改前必建回滚点 —— git commit / stash / 独立分支，非 git 文件复制快照，回滚点记入任务记录才动手，绝不手动反向改码撤销。
- 上下文压缩不可感知，靠两道守卫 —— 显式信号重载 + 关键节点（开工 / 提交 / 重大决策前）默写核心要素自检，复述不全即重读。
- 渐进式披露省 Token —— 只预加载 name + description，正文激活才读，references 按步加载，平台规则文件控制在约 30 行。
- 复用五问决策链 —— 功能必要吗？平台原生支持吗？组件库覆盖吗？已有依赖覆盖吗？最少代码能完成吗？全链未命中才自研。
- 结论即时落盘，不等到收尾 —— 长会话中分析结论立即最小粒度写入任务记录，压缩恢复以记录为准不凭记忆。
- 密钥红线 + 发布前残留扫描零命中 —— 密钥绝不进代码 / 配置 / 文档 / 对话，开源发布前扫描个人路径 / 账号 / 密钥 / 内部引用全部零命中才推送。
- 新增规则必须走审批流程 —— 采集 → 五问分析 → 四段模板 → 用户审批 → 落盘复检 → 留档提交，未经批准不得落盘，规则本身也受规则约束。
这套规则的本质是：用可审计的工作纪律，把 Agent 从「凭感觉干活」变成「按规矩办事」，在自动化效率和操作安全之间找平衡，同时把 Token 花在办成事上而不是反复纠错上。
六、使用场景
- 希望 Agent 在跨项目、跨平台（Trae、Codex、Claude Code、Cursor、CLI 等）时行为一致。
- 希望按风险给自主权：L1 常规直接做，L3 高风险（密钥、删除、迁移、发布）一律先问。
- 希望「目标模式」无人值守运行：先写计划、设预算、按文件边界拆分、超预算自动停。
- 希望会话可审计：验收标准前置、任务记录、会话结束知识沉淀。
七、局限与代价（诚实说明）
这是基于提示词的文档级约束，依赖模型遵守规则，做不到代码运行时的强制拦截。具体来说：
- 上下文成本：即使渐进式披露，治理层仍消耗上下文——这是换取一致性的代价；生成的规则文件控制在约 30 行以内以限制成本。
- 依赖 Agent 自律：无脚本强制执行，懒惰的 Agent 可以不遵守规则；它也无法感知自己被压缩——已用自检双守卫缓解。
- 平台检测是启发式：靠目录 / 环境变量信号判断；无法确定时直接问用户，不猜。
- 不捆绑工具：刻意零脚本 / 零依赖 / 零网络，能力缺口用「兜底」解决（文本提问协议、通用能力 + 官方文档），而非塞二进制。
- 弱模型效果受限：上下文长度不够的模型基本遵守不了这套纪律，因为压缩策略各平台差异很大。
它的定位非常克制：不试图替代项目的自身约定（项目文档优先），不捆绑任何工具链，不承诺进程隔离或插件市场。它只做一件事：让 Agent 的行为可预测、可审计、可回滚。
八、一分钟跑通（快速体验）
需要支持 Skill 的 Agent 环境（Claude Code / Trae / Cursor / Codex 等）：
- 安装：把
skill/shisan-xinuo-workflow/复制到平台技能目录；或npm install @zxc663/shisan-xinuo-workflow后从node_modules/复制该目录。 - 加载：新开会话，Skill 自动执行第 0 步平台适配——检测平台、写入约 30 行规则文件（
AGENTS.md/CLAUDE.md/ …）、选定提问工具（已有规则先备份再合并，绝不覆盖）。 - 感受它：先给一个小任务观察行为——它会先复述理解、写 3-5 条验收标准、做完自查。再给一个风险任务（如「把这个目录删了」）：它必须先问再动手——这就是 L3 分级在起作用。
- 目标模式：说「目标：整理本目录文件并归组，注意不要删除任何内容」，观察它写计划、设预算、按文件边界拆分、超预算自动停。
一个会话内应看到：任务分级、关键必问、风险操作前回滚点、结束时留档。
九、安装与版本
把 skill 目录复制到所用平台的技能目录即可：
| 平台 | 位置 |
|---|---|
| Claude Code | ~/.claude/skills/shisan-xinuo-workflow/ |
| Codex / 通用环境 | 克隆本仓库，将技能发现指向 skill/shisan-xinuo-workflow/ |
| Trae / Cursor / 其他 | 按平台技能目录约定放置；详见 references/platform-adaptation.md |
纯文档、零依赖、零网络调用，加载即自动适配平台。三个通用版本（英文 / 中文 / 双语）内容一致仅语言不同，回答语言跟随用户（无强制中文）。
十、常见问题（FAQ）
- 为什么不做成一个大规则文件？ 上下文纪律：Skill 只预加载
name+description，激活才读正文，references/按步加载。巨型规则文件会拖累每个会话。 - 会覆盖我已有的规则吗？ 不会——先备份再合并，绝不覆盖。
- 会对外发送数据吗？ 不会。纯文档、无脚本、无网络。
- Agent 能感知自己被压缩吗？ 不能——这正是第 25 条规则改为「显式信号重载 + 关键节点自检」的原因，不依赖压缩感知。
十一、结语
AI Agent 的工程治理正在成为新的基础设施。Agent 工具本身能力很强，但它就像一个拿着微型核聚变的小孩，如果缺少一套工作规范，再好的模型也容易跑偏。
如果你也在用 AI 编程助手，不妨问自己一个问题：你的 Agent 知道「什么时候该问你」吗？ 如果答案不确定，这个项目或许值得一看。
把一套经过实战验证的工作纪律，以零依赖、跨平台、渐进式披露的方式打包成可安装技能——这本身就是一次值得分享的实践。项目名 shisan-xinuo-workflow，有能力的兄弟可以来 GitHub 给个 star。
本文基于 shisan-xinuo-workflow 官方仓库源码与最新 README 撰写，以项目最新介绍文档为准。项目地址：https://github.com/zxc663/shisan-xinuo-workflow （MIT 协议）
评论（0）