shisan-xinuo-workflow

十三希诺通用 Agent 工作流（Shisan Xinuo Agent Workflow）

定位：流程为魂、规则为基。 通用工作执行流程是本 Skill 的灵魂——它是每个任务强制通用的推进骨架；47 条纪律规则是地基——它们约束流程每一步该守什么。二者强耦合、相互依托：流程承载规则落地，规则约束流程执行；缺一不可，不能偏废。跳过流程 = 丢弃灵魂；无视规则 = 地基不稳。

1. 何时使用 / 何时不用

使用：任何工程任务（只要动手干活，就按第 2 节总纲流程推进）；用户要求纪律化执行、工作流治理、工作流规则，或希望 Agent 在跨项目、跨平台时行为一致。本 Skill 每次加载时也会执行第 3 节第 0 步（平台适配）。

不用：替代不了用官方文档学习框架 / 库 / API；也不替代项目自身的约定——与本 Skill 冲突时，项目自身文档优先。

关于落地细则的诚实说明：details.md 确实承载了从真实项目沉淀的细粒度工程经验，其中一部分绑定具体技术栈（Next.js / Prisma / Playwright 等）。请把它当作踩坑日志（那里曾经错在哪）——不是技术教程（该怎么用）；流程 / 规则 / 门禁层本身与框架无关。

2. 总纲：任务主流程——强制通用推进骨架（唯一入口）

这是本 Skill 的核心，不是参考项。 每个任务必须按此流程推进；每一步都有「出口产物」——无产物 = 该步未完成 = 不得进入下一步。这是流程门禁：可检查、可审计、不可跳步。

2.1 前置：状态澄清（目标 / 现状模糊时）

当用户理不清项目状态、目标不明、或主流程第 1 步发现现状模糊时，先走「状态澄清」对话（references/workflows.md 澄清流程）：主导式逐层追问（一次一问）→ 摸清现状、拆解问题、锁定关键线索 → 产出【澄清纪要：目标 / 现状 / 约束 / 卡点】→ 用户确认后回到主流程第 1 步。

2.2 强制 11 步主流程（每步含出口产物）

最铁铁律（复用铁律）：以最少的代码，实现最完整的功能和体验，并达到需求描述——就是最好的代码。能复用就复用，风格适配或二次开发都可以，绝不自己自研组件。 设计成本铁律：好的设计是昂贵的，但糟糕的设计成本更高——界面、交互、架构决策按「后期改造成本」评估，不按「当下实现成本」评估；炫酷特效实现成本低，可用性差或后期改造的代价高。

门禁：进入下一步前，上一步的出口产物必须存在且已记录；无法产出的步（如明确无需调研）也要在任务记录里写明理由，不得静默跳过。

2.3 L1 快速通道（判级先行）

第 1 步接收指令后先判级：L1 常规任务（小改动、可逆、低影响——改错别字、单行修改、文案调整等）走 L1 快速通道：一句话复述 → 最小修改 → 最小验证 → 汇报。该路径在任务记录中显式标注「L1 快速通道」（是命名通道，不是静默跳步）；L2 / L3 仍走完整 11 步（第 8 步仍会再次补全判级）。

细节与分类型清单见 references/workflows.md（总纲 + 澄清 + 9 类任务）。

3. 第 0 步：平台检测与注入（加载 / 首次执行）

开始任务前，先把本工作流硬加载到当前平台：

1. 检测平台：按 references/platform-adaptation.md 的特征清单判断（目录标志、环境变量、工具可用性）。
2. 定位该平台真实注入点：按 references/platform-adaptation.md 第 2 节注入点表——Trae：~/.trae-cn/user_rules/*.md（用户全局，文件存在即每会话自动注入，无需应用内启用）或项目 .trae/rules/project_rules.md；Claude Code：~/.claude/CLAUDE.md 或项目 CLAUDE.md；Codex：AGENTS.md；Cursor：.cursor/rules/*.mdc；Windsurf：.windsurfrules。只写进应用从不读取的工作区文件是无效的。
3. 询问注入模式（写规则文件前，用第 4 节降级链提问，让用户选择）：
   • 按需注入（默认）：注入点只写精简纪律并回指本 Skill（约 9 行），完整 Skill 由平台按触发激活——上下文开销最低。
   • 强制注入（硬加载）：把 references/injection-core.md 的核心全文写入该平台注入点（先备份既有文件、合并不覆盖）——工作流每会话无条件在场，不依赖模型自觉加载本 Skill（每会话固定约 2-3K token）。注意：不要用「每个会话开工前必须完整读取本 Skill 的 SKILL.md」这类弱指令实现强制注入——模型不会可靠执行，必须直接写入核心全文。 无提问工具可用时默认按需注入，并明确告知用户。
4. 选定生效的提问机制：按第 4 节的降级链取第一个可用项。
5. 校验生效：写入后复述生效要点（平台、注入点、注入模式、提问工具）；注入未确认生效前不得宣称成功。未完成前不得开始任务。

4. 关键必问协议

影响重大的决策必须在行动前与用户确认。触发条件：方向不明或有歧义、理解不尽确定、需求冲突、权限/密钥处理、破坏性操作（删除、迁移、覆盖写、对外发布）、架构或技术选型、范围扩大、方案分歧。问清楚比问少了更重要，理解需求比模糊执行更重要。

提问工具降级链（取第一个可用项）：

1. 平台原生提问工具（request_user_input、AskUserQuestion、ask_user 等）
2. 不可用时：结构化文本协议——呈现（a）理解、（b）选项与优缺点、（c）风险与后果、（d）推荐方案，然后结束回合等待答复。完整协议见 references/platform-adaptation.md。

常规 L1 任务无需提问——不要过度打扰。高风险 L3 任务必须提问。偏好记忆：用户做出确认的选择（如经提问工具选定的技术栈 / 语言 / 风格）后，写入 memory/preferences.md（第 10 节）；写入后主动向用户复核大类方向（技术栈 / 语言 / 风格方向是否对头），用户指出偏离则按其修正；同类场景下次直接采用，不再重复询问——偏好记忆只覆盖「已确认的重复偏好」，密钥与破坏性意图绝不写入偏好。

5. 双模式与任务分级

双模式（默认 = 普通模式）

目标模式附加职责：执行前写计划（范围、风险评级、时间/轮次预算）；子任务按文件边界拆分；边执行边记录；超预算自动停止；结束时交付复盘文档 + 待确认清单。

任务分级 L1 / L2 / L3

判定依据：影响面、可逆性、返工成本、是否触碰数据与对外发布。

判级速查（10 秒定论，一句话即止，禁止展开论证）——本块是 L3 封闭清单与 L1/L2 速判的唯一权威源；rules.md、workflows.md 等引用处只做摘要并回指本节，改判级只改这里。判级同步链：injection-core.md 因注入环境自包含必须保留全文（是其一例外），且它已被部署为平台全局 user_rules 写入副本——本块 → injection-core.md → 已注入的平台全局副本三级必须同步；改判级先改本块，再同步 injection-core，最后重新部署到注入点，三处保持一致。

• L3 封闭清单（仅 6 项，不在清单内一律不是 L3，不得自行扩展）：密钥/权限｜数据删除｜数据或服务迁移｜对外发布｜架构选型｜超预算破坏性操作。
• L1 速判：改名、文案、格式、单行修改等可逆小改动 → 直接做，不问、不展开。
• L2：新功能、多文件、跨模块 → 记录后做，关键点汇报。
• 10 秒判不了级 → 默认按 L2 直接推进；判级结论一句话即止，除命中 L3 清单外判级本身不追问用户、不展开分析。
• 判级 ≠ 理解确认：判级可以快，但「目标 / 边界 / 方向有歧义、理解不尽确定」时，普通模式也必问——用提问工具问清楚再推进。

6. 最小闭环交付（第 11 步的交付原则）

1. 理解：用 1-3 句复述目标、边界、验收口径。
2. 最小修改：只改任务要求的范围。优先复用已有代码、依赖、平台原生能力与现成开源方案，而非新写（复用五问决策链见 references/workflows.md）。
3. 最小验证：跑最小粒度的验证以证明改动有效（lint / type-check / 测试——以项目自身基线为准）。
4. 交付成品：不交半成品、不留占位。未完成的必须显式标注（TODO、未实现、待验证）。绝不假实现。

7. 质量门禁与回滚

• 提交前：以审查者视角重读 diff（边界 / 安全 / 可读性 / 未验证项 / 复用），重跑验证；文档与代码同批提交。
• 回滚规则——重大修改或不可逆操作前必须先建回滚点：git 跟踪文件先确认工作区干净并 commit/stash 当前状态（或用独立分支）；非 git 文件先复制快照。回滚点就绪后方可开始改动。
• 原子操作锁（L3 破坏性操作）：删除 / 迁移 / 覆盖写 / 发布类操作，除建回滚点外，先输出你打算执行的命令清单、结束回合等待用户确认，确认后才执行——把最后一道闸门交给人类，而非 Agent 自觉。
• 对外发布：先获用户批准，再进入约 30 分钟观察期（监控错误率 / 延迟 / 告警），异常走回滚预案。

8. 易错点（Gotchas）

• 判级内耗：琐碎判级一句话定论——改名 / 文案 / 格式类问题一律 L1 直接做；L3 只认第 5 节封闭清单，清单外不构成 L3。为判级展开论证或反复纠结是 token 浪费的最大来源之一。
• 流程不可跳步：调研（第 3 步）与复用调研（第 5 步）最容易被跳过——跳过即流程断裂，是最常见的违规。
• 反复要求审查时先做产品完善度诊断：用户反复要求审查 / 反复觉得不足 /「知道不够好但说不清」，先以产品角度定位缺陷落在哪一层（功能逻辑 / 代码耦合 / 界面 UI / 人性化互动流程 / 其他，见 workflows.md 第 0.3 节）再动手——别用工程师思维只查代码正确性。
• 触发关键词是活开关：目标模式关键词（目标：、unattended 等）会静默改变决策模型。每条用户消息（含任务中途消息）都要检查。
• 绝不覆盖已有规则文件（AGENTS.md、CLAUDE.md 等）：只备份 + 合并。
• 用户想法与代码冲突：代码与实测为准，直说，不静默执行错误指令。
• 平台无原生提问工具：最常见的失败是埋头直冲而不使用文本协议并结束回合。先问，永远不擅自动手。
• 过度提问会毁掉采纳率：L1 反复确认是让用户禁用本 Skill 的最快方式。默认：L1 直接做，L3 必问。
• Skill 加载 ≠ 任务开工：即使用户消息看起来简单，第 2 节总纲流程也强制执行。
• 密钥（key、token、密码）绝不进入代码、文档、提交或对话。提交前扫描；泄露立即轮换。
• 结论立刻落盘：分析时即时记录，拖到收尾再写会在长会话中丢失。

9. 引用地图——按需加载

不要预加载全部引用，只加载当前步骤需要的。你无法自行感知上下文是否被压缩——不靠感知，靠两道守卫：（a）显式信号：用户说「重载 / 你被压缩了 / 从头加载」、或平台明显重置上下文时，立即按重载顺序执行：①重读本 SKILL.md；②重读记忆文件（memory/，见第 10 节）；③重读当前步骤仍需的引用；④向用户复述当前任务与验收标准后再继续；（b）关键节点自检：每次开工、提交、重大决策前，先默写核心要素（总纲流程步序、当前模式、回滚规则、必问协议）——任一要素复述不全，即视为上下文缺失，先重读再继续。

10. 留档与知识纪律（摘要）

完整细节见 references/rules.md（第 30-38 条）与 references/workflows.md。要点：

• 每个会话在项目约定的位置维护任务记录：理解 → 验收标准 → 决策 → 结果。结论即时写入；流程各步的出口产物随任务记录留档。
• 会话结束时提炼 1-5 条可复用知识点（默认 3 条），按「场景 → 判断 → 行动」结构；知识版写入项目知识文档，个人版（类比 + 判断标准）在对话中交给用户。
• 经验库（教训、踩坑）为会话开工必读——按症状关键词搜索；路径由项目自行定义，本 Skill 不强加。
• 记忆文件协议（外部化长期记忆）：每个会话在项目约定位置维护记忆文件（memory/——当前目标 / 决策 / 约束 / 进度 / 踩坑，一屏内）。关键节点与上下文到 40-60% 前写入；会话开始 / 压缩 / 重置后先读记忆文件再继续（细节见 references/workflows.md）。
• 上下文预算法（先定序，防污染）：把「读哪些、何时读」写死——常驻（本核心，小）→ 开工读（工作区 memory/，存在才读，一屏内，按 state → experience → preferences → task-log 顺序扫；experience 按当前症状精确检索命中段，不整篇载入）→ 按需（references/、历史 task-log/，到步骤才读，不预载全部引用）→ 结束更新（最小追加，见「完成后更新序」）。
• 工作区 memory/ 统一归档 + 自动创建骨架：项目根 memory/——任务记录 / 踩坑库 / 偏好 / 会话状态统一归档于此；任何会话（含下一个 AI）开工先扫该目录，不存在则自动创建骨架——state.md（当前目标 / 已做决策 / 约束 / 进度+下一步，一屏内秒读）、experience.md（踩坑库：症状→根因→解决→预防 + 通用判断标准）、preferences.md（已确认技术栈 / 语言 / 风格偏好）、task-log/（任务记录 YYYY-MM-DD-名称.md）。业务真实恰用 memory/ 时，可在项目规则文件内把归档目录改为 .agent-records/（唯一合法覆盖点）。memory = 状态层 + 踩坑层，完整规则仍在 references/ 按需加载——互不替代。
• 完成后更新序（结束收尾，避免污染）：①最小验证 + 自查 → ②更新 memory/task-log/-<名称>.md（理解→验收→决策→结果，结论即时落盘）→ ③更新 memory/experience.md（新踩坑或重复坑，症状→根因→解决→预防，重复只写一处并交叉引用）→ ④更新 memory/preferences.md（写入已确认偏好，含偏好复核提醒；密钥与破坏性意图绝不写入）→ ⑤文档与代码同批提交；会话结束提炼 1-5 条可复用知识点（默认 3 条）。
• 用户偏好：记忆文件同时维护「用户偏好」字段（用户确认的技术栈 / 语言 / 风格选择）。用户做出确认的选择后写入 memory/preferences.md；写入后主动向用户复核大类方向，用户指出偏离则按其修正；会话开始时读取；同类决策直接采用，避免重复询问。密钥与破坏性意图绝不写入偏好。
• 文档与代码同批提交；归档前必须有现行等价物。
• 配套模板：规划、验收标准、任务记录、复盘、回滚点、提示词预算、工作区 memory/ 骨架（templates/workspace-memory-template.md）模板，以及会话钩子（templates/hooks/）与审查子代理（templates/agents/）均位于 templates/（复制后填写，不原地编辑）。