Shisan Xinuo Agent Workflow · 十三希诺 Agent 工作流

渐进式工程治理 Skill——不是把整本手册砸进上下文，而是像神经系统：只在任务到达某一步骤时，注入那一步所需的少量规则。
A progressive, on-demand engineering-governance Skill for AI coding agents: it injects only the few rules a step needs, when that step arrives.

一句话定位 · One-line positioning

一个渐进式披露 + 按需注入 + 判级动态路由的工程治理元 Skill：把 43 条纪律规则 + 11 步强制主流程（每步出口产物门禁）+ 203 条落地细则（12 类）+ 配套模板 / 提示词预算 / 会话钩子 / 审查子代理 / 永不清单，打包成跨平台（Trae / Codex / Claude Code / Cursor / Windsurf / WorkBuddy / CLI）可审计的治理层。价值：治理一致性、可审计性、防假实现；代价：依赖平台注入与 Agent 自律，无运行时强制。

A progressive, on-demand, triage-routed governance meta-skill: 43 discipline rules + an 11-step mandatory master sequence (per-step exit-artifact gates) + 203 landing details (12 categories) + templates / prompt budget / session hooks / review sub-agents / NEVER list, packaged into a cross-platform, auditable governance layer. Value: consistency, auditability, no-fake-completions; cost: injection-dependent, zero runtime enforcement.

目录 · Contents

1. 为什么用它 · Why
2. 它为谁解决什么 · Who it's for
3. 工作原理（渐进式 / 状态机）· How it works
4. 功能全景 · Feature map
5. 差异化优势 · Differentiation
6. 架构真相（诚实）· Architecture truths
7. 快速体验 · Quick start
8. 安装 · Install
9. 仓库结构 · Repository layout
10. 版本差异（三语）· Editions
11. 参考项目 · Reference projects
12. 局限与代价 · Limitations
13. 常见问题 · FAQ
14. 来源与依据 · Sources
15. 版本历史 · Changelog
16. 贡献者与许可 · Contributors & License

为什么用它 · Why this

• 把「AI 直觉」变成「工程纪律」：L1/L2/L3 风险分级、关键必问、回滚点、留档纪律——不再靠 Agent 自觉碰运气。Turns AI instinct into auditable engineering discipline.
• 省 token 不丢纪律：渐进式加载 + L1 快速通道——小任务不烧完整流程，大任务不破底线。Saves tokens without losing discipline: on-demand loading + L1 fast lane.
• 跨平台行为一致：同一套治理任何平台生效，第 0 步自动适配，无需逐平台重写。Consistent behavior across platforms; Step 0 adapts instead of rewriting.

它为谁解决什么 · Who it's for

• 重度 AI 编码用户（Cursor / Claude Code / Trae / Codex 深度用户）：希望 Agent 跨项目、跨平台行为一致、可审计，尤其痛恨「假完成 / 伪造测试 / 虚报数据」。Heavy AI-coding users who want consistent, auditable, no-fake-completion behavior.
• 需要按风险放权的人：L1 常规直接做，L3 高风险（密钥、删除、迁移、发布）一律先问。Risk-based autonomy: L1 done directly, L3 always asked first.
• 想要无人值守目标模式的人：目标：… → 写计划、设预算、按文件边界拆分、超预算自动停。Unattended goal mode: plan, budgets, file-boundary isolation, auto-stop.
• 想省 token 又不丢纪律的人：渐进式加载 + L1 快速通道。Token-efficient without losing discipline.
• 做 Agent 生态研究 / 开源设计的人：了解「渐进式 Skill」如何把静态约束变成动态治理。Researchers designing progressive governance skills.

工作原理（渐进式 / 状态机）· How it works

平台适配（第 0 步：检测 → 注入点 → 按需 / 强制注入）
Platform adaptation (Step 0: detect → injection point → on-demand / forced)
        │
        ▼
任务判级（Triage-first，每任务开始）┐
  ├─ L1 常规 → 快速通道：一句话复述 → 最小修改 → 最小验证 → 汇报
  └─ L2 / L3 → 完整 11 步主流程（每步出口产物门禁）：
      ├─ 0.0 状态澄清（目标 / 现状模糊时）· status clarification
      │  0.1 主流程细节 · 0.2 联网调研（可信信号）· online survey
      │  0.3 产品完善度诊断（触发式）· product-polish diagnosis
      │  0.4 强制双调研与规划（规划前必过）· mandatory dual survey
      ├─ 1 接收 → 2 经验库必读 → 3 调研实际资源 → 4 联网调研（必须）
      ├─ 5 复用调研（铁律）→ 6 复述理解 → 7 疑问必问 → 8 产品视角+分级+回滚点
      ├─ 9 规划（双调研后，含 3-5 条可验证验收标准）→ 10 执行 → 11 自查与归档
      └─ 规则（43 条，地基）Rules + 落地细则（203 条 / 12 类，按类按需加载）Details

渐进式（Progressive）体现在三层：

1. 入口精简：平台只预加载 name + description（约几 KB）；激活才读 SKILL.md 正文（<500 行）。
2. 按步加载：references/ 只在对应步骤需要时才读——rules.md（地基）、details.md（按类按需）、workflows.md、security.md、platform-adaptation.md、never-list.md。
3. 动态路由：任务判级前置 → L1 走快速通道（省上下文），L2/L3 走完整主流程（兜底线）；触发式诊断（反复审查 → 产品完善度诊断）。

上下文纪律：SKILL.md 精简；生成的规则文件约 30 行；记忆文件（memory/）一屏内；压缩后先读记忆再继续。

功能全景 · Feature map

差异化优势 · Differentiation

架构真相（诚实）· Architecture truths

供人（和 AI）快速判断它到底是什么、做不到什么。全无脚本 / 无运行时 / 无网络调用——它是一份规范，不是工具。A specification, not a tool.

快速体验 · Quick start

一分钟跑通（需要支持 Skill 的 Agent 环境：Claude Code / Trae / Cursor / Codex 等）· Try it in under a minute (needs a skills-capable agent):

1. 安装 Install：把 skill/shisan-xinuo-workflow/ 复制到平台技能目录（见下方安装）；或从 dist/ 解压发布 zip。
2. 加载 Load：新开会话。Skill 自动执行第 0 步平台适配：检测平台、询问按需 / 强制注入、把约 30 行规则文件（AGENTS.md/CLAUDE.md/…）写入 agent 应用每会话真正自动注入的位置（已有规则先备份再合并，绝不覆盖）；平台要求应用内启用时（如 Trae）引导你在应用设置启用。
3. 感受它 Feel it：给一个小任务观察——先复述理解、写 3-5 条验收标准、做完自查。给风险任务（如「把这个目录删了」）：必须先问再动手——这就是 L3 分级。
4. 目标模式 Goal mode：说 目标：整理本目录文件并归组，注意不要删除任何内容，观察它写计划、设预算、按文件边界拆分、超预算自动停。

一个会话内应看到：任务分级、关键必问、风险操作前回滚点、结束时留档。Expected within one session: triage, ask-before-acting, rollback before risky ops, records at the end.

安装 · Install

把 skill 目录复制到所用平台的技能目录；纯文档、零依赖、零网络调用，加载即自动适配平台。Copy the skill folder into your platform's skills directory; pure documentation, zero deps, zero network — loading is enough, Step 0 adapts it.

仓库结构 · Repository layout

shisan-xinuo-workflow/              ← 仓库根
├── README.md                       ← 本文件（双语 · 中文优先，门面）
├── LICENSE                         ← MIT
├── 项目信息.md                      ← 内部维护文档（供下一个 AI 助手读写）
├── package.json / .npmrc           ← npm 发行物配置（GitHub Packages）
├── dist/                           ← 版本发布 zip（v1.0.0 … v1.5.0）
├── skill/shisan-xinuo-workflow/    ← 默认交付（英文）
│   ├── SKILL.md                    ← 精简入口：定位、总纲主流程、门禁、引用地图、重载顺序
│   ├── templates/                  ← 配套模板（规划/验收/任务记录/复盘/回滚点/提示词预算/会话钩子/审查子代理）
│   └── references/                 ← 按需加载的引用
│       ├── rules.md                ← 43 条规则地基
│       ├── workflows.md            ← 前置 0.0-0.4 + 9 类任务 + 门禁 + 记忆文件协议 + 重载顺序
│       ├── details.md              ← 203 条落地细则 / 12 类（踩坑日志）
│       ├── platform-adaptation.md  ← 注入点、提问降级链、结构化协议、会话钩子协议
│       ├── security.md             ← 安全红线、安装校验、回滚、提示注入、供应链/SBOM、残留扫描
│       └── never-list.md           ← 永不清单（明线禁止，自查用）
└── versions/
    ├── universal-zh/               ← 通用版 · 中文
    └── universal-bilingual/        ← 通用版 · 中英双语

版本差异（三语）· Editions

三个通用版本内容完全一致，仅语言不同；另有独立私有工作台版（不进本公开仓）。The three universal editions are content-identical, differing only in language; a private personal-workstation edition is maintained separately and is not part of this public repo.

参考项目 · Reference projects

按实际情况如实登记：本 Skill 的机制 / 结构 / 细节借鉴自以下协议与同类项目（借鉴机制与结构，非复制代码）。同类项目独立演进，本 Skill 为后发者，差异定位见「差异化优势」。Mechanism borrowing, not code copying; this skill is a later entrant.

协议与规范（必列）· Protocols & standards

同类工程治理项目（机制借鉴）· Peer governance projects (mechanism borrowing)

早期审阅参考（v1.4.0 记入项目信息决策 16）· Earlier review references

• engineering-policies（token / context-rot / 停止规则）
• nadvolod AGENTS.md（风险分级证据 / 人为审查边界）
• ponytail（七级决策阶梯 / 删除优于添加）
• 软件开发准则（DRY / KISS / YAGNI / SoC / LoD）→ 进入 details.md 铁律与纪律类

局限与代价（如实）· Limitations

• 依赖强提示词注入 Strong-prompt-injection dependent：本质是规范而非工具——无运行时、无强制；注入被跳过或描述未命中时，它什么也不会做。It is a specification, not a tool; if injection is skipped or the description fails to match, it does nothing.
• 依赖 Agent 自律 Agent self-discipline：无脚本强制执行；懒惰的 Agent 可以不遵守规则，也无法感知自己被压缩——用自检双守卫 + 显式重载顺序缓解。No scripts enforce anything; mitigated by self-check guards + explicit reload sequence.
• 上下文成本 Context cost：即使渐进式，治理层仍消耗上下文——这是换取一致性的代价；规则文件约 30 行、记忆文件一屏内。A governance layer consumes context — the trade-off for consistency.
• 细则体量大 Detail volume：落地细则 203 条较多——这正是按类按需加载的原因。203 rules is heavy — hence per-category on-demand loading.
• 平台检测是启发式 Detection heuristics：靠目录 / 环境变量信号判断；无法确定时直接问用户，不猜。Best-effort; asks rather than guesses when ambiguous.
• 不捆绑工具 Zero tooling bundled：刻意零脚本 / 零依赖 / 零网络；能力缺口用「兜底」解决。Deliberately zero scripts / dependencies / network; gaps handled by fallbacks.
• 规范演进 Spec evolution：基于 Agent Skills 开放标准构建；不支持 Skill 的旧平台需手动加载。Built on the Agent Skills open standard; older platforms need manual loading.

常见问题 · FAQ

• 为什么不做成一个大规则文件？ 上下文纪律：只预加载 name+description，激活才读正文，references/ 按步加载。Why not one big rule file? Context discipline: only name+description preload; references load per step.
• 会覆盖我已有的规则吗？ 不会——先备份再合并，绝不覆盖。Will it overwrite my rules? No — backup + merge only.
• 会对外发送数据吗？ 不会。纯文档、无脚本、无网络。Does it send data anywhere? No. Pure documentation; no scripts; no network.
• Agent 能感知自己被压缩吗？ 不能——这正是 Skill 用「显式信号重载 + 关键节点自检」的原因。Can the agent detect compaction? No — hence explicit-signal reload + milestone self-checks.
• 上下文压缩后怎么重载？ 用户说「重载 / 你被压缩了 / 从头加载」或平台重置 → ①重读 SKILL.md → ②重读 memory/ → ③重读当前引用 → ④向用户复述任务与验收再继续。How to reload after compaction? Follow the reload sequence.
• 联网调研就是「网上说什么信什么」吗？ 不是——它按权威性分级收集可验证可信信号，并以本地实测兜底。Is the survey just "whatever the web says"? No — verifiable trust signals + local verification.
• 细则层为什么含具体技术栈？ 如实说明：details.md 是真实项目踩坑日志（什么会错），不是技术教程（怎么用）；机制层与框架无关。Honest: it is a pitfall log, not a tutorial; the mechanism layer is framework-agnostic.

来源与依据 · Sources

数据口径（实测）——本 Skill 的 203 条落地细则 / 12 类，提炼自作者真实生产开发沉淀；源文档存放于独立工作项目目录，不随本公开仓 / zip / npm 分发，此处给出可核实的实测数据：

提炼方式：分片子代理审查（覆盖开发日志 / 踩坑库 / AI 知识沉淀 / 交接清单 / 规则文档）→ 去重 → 泛化脱敏 → 形成 details.md 203 条 / 12 类 + 个人经验手册。机制部分按 Agent Skills 开放规范及其最佳实践重写（渐进式披露、Gotchas、Checklist、Plan-Validate-Execute）。

EN — 203 landing details in 12 categories are distilled from real production work (source docs live in a separate working-directory, not shipped here). The main dev-log is 863.6 KB / ~501K chars / 8,299 lines (the basis of the "800KB+ development history" claim); mechanics rewritten against the Agent Skills specification and its best practices.

版本历史 · Changelog

• v1.5.0 — P0/P1 治理完整度补强：templates/（6 模板）+ templates/hooks/（会话钩子）+ templates/agents/（3 子代理）+ references/never-list.md（永不清单）+ security.md 提示注入防御与供应链/SBOM + README 重构（差异化 reposition + 参考项目章节）；三版同步。Governance completeness: templates, hooks, review sub-agents, never-list, security defenses; README rebuilt.
• v1.4.5 — 细则扩展至 203 条 / 12 类（源项目多文档审查提炼，新增第 12 类 17 条）。Details expanded to 203 rules / 12 categories.
• v1.4.4 — 安静模式（安静模式/quiet）+ 偏好记忆（memory/ 用户偏好字段）+ 原子操作锁（L3 先出命令清单等确认）。Quiet mode, preference memory, atomic-operation lock.
• v1.4.3 — 定位升级「渐进式」+ 压缩后显式重载顺序 + README 重构。Positioned as progressive; explicit reload sequence.
• v1.4.2 — 定位诚实话（机制层跨领域 / 细则层踩坑日志）+ L1 快速通道 + 记忆文件协议。Honest layered positioning; L1 fast path; memory-file protocol.
• v1.4.0 — 落地细则（186 条 / 11 类）+ 产品完善度诊断 + 强制双调研 + 五支柱定位 + README 重构。Landing details, product-polish diagnosis, dual survey, five-pillar positioning.
• v1.3.x — 定位翻转「流程为魂、规则为基」+ 11 步主流程门禁 + 联网调研必须 + 可信依据 + 开源安装强制校验。Positioning flip; gated master sequence; mandatory verified survey.
• v1.2.0 — 调研驱动的 11 步任务主流程。Research-driven 11-step master sequence.
• v1.1.0 — 注入点与注入模式（按需 / 强制）。Injection points & modes.
• v1.0 — 首版发布（43 条纪律、双模式、回滚、渐进式披露）。First release.

贡献者与许可 · Contributors & License

• 十三希诺 — 作者与维护者 Author & maintainer（zxc663）
• 欢迎贡献：规则改进、工作流补充、本地化修正请开 issue 或 PR；新增规则需先走 Skill 自带的规则新增流程再合并。Contributions welcome via issue or PR; new rules follow the skill's own rule-addition process.
• 许可 License：MIT，见 LICENSE。