对话笔记直发：7.15 YoShop 风险分级 AI 开发工作流与使用手册。分类：小程序接单。

YoShop 风险分级 AI 开发工作流与使用手册

时间

日期：2026-07-15
项目：/opt/yoshop
场景：成熟的微信商城小程序二次开发项目，包含微信虚拟支付、服务订单、退款、商家后台、总后台和生产部署能力。

用户目标

用户当前使用“Grill Me 澄清需求 → Trellis 接管任务”的工作方式，但遇到两个主要痛点：

修复一个小 Bug、小按钮或局部样式时，AI 仍然经常全盘扫描仓库，浪费时间和 Token。
Trellis 已经接管过很多任务，但历史 Task 并没有自然转化为快速代码导航和可按需加载的项目知识。

用户希望：

判断 grill-with-docs 是否适合对已经成型的项目进行逆向文档提炼；
梳理整个项目当前架构和文档体系；
找到比“每次全仓扫描”更高效的 AI 工作方式；
按讨论结果实际实施改造；
从第一性原理整理一套完整、可长期使用的中文说明书。

背景与上下文

仓库实际包含多个独立应用，但最初 Trellis 仍按 single-repo 处理：

应用	路径	作用
PHP 后端	`yoshop2.0/`	ThinkPHP API、服务、模型、回调、定时任务
微信小程序/H5	`yoshop2.0-uniapp/`	uni-app 小程序与 H5
商家后台	`yoshop2.0-store/`	Vue 2 + Ant Design Vue 商家控制台
平台总后台	`yoshop2.0-admin/`	Vue 2 平台管理端
部署工具	`deploy/`	构建、打包、生产发布、状态和回滚

调查发现：

.trellis/config.yaml 原本没有启用 packages。
.trellis/spec/ 已有约 2440 行规范，但主要解决“找到代码后应该遵守什么”，还不能快速解决“应该从哪个应用、哪个入口开始找”。
当前根 CONTEXT.md 主要描述微信虚拟支付服务订单领域词汇，不是代码架构地图。
当前前端 Spec 同时描述小程序和商家后台，平台总后台覆盖不足。
多个活跃 Task 仍引用 .trellis/spec/backend/*.md 和 .trellis/spec/frontend/*.md，因此不能破坏性移动现有 Spec。
当时存在 8 个活跃任务且没有 current task，任务队列有一定噪声。

第一性原理分析

AI 为什么会全盘扫描

AI 收到“退款按钮有问题”时，并不知道：

属于小程序、商家后台还是总后台；
是页面样式、API 字段、权限还是后端状态机；
哪些是源码，哪些是 dist、vendor、runtime 等无关目录；
这是低风险显示问题还是高风险资金/退款问题；
修改后应运行什么验证。

当缺少低成本路由入口时，全仓搜索是 AI 降低不确定性的自然行为。真正的解决方式不是简单要求“不要扫描”，而是提供更便宜且可靠的求证路径。

文档为什么可能反而增加 Token

文档只有在满足以下条件时才节省上下文：

有短小、稳定的入口；
能根据 package 和领域按需选择；
不默认把所有 README、Task、Spec、历史聊天全部加载。

最终采用渐进式披露模型：

系统地图 → 一个 Package Spec index → 一个专题契约 → 精确源码和测试

流程为什么必须按风险分级

“一行 CSS”和“退款状态机”虽然都可能只改两行，但失败后果完全不同。流程强度应该由影响范围、可逆性、契约变化、资金/权限/数据/生产风险和根因确定程度决定，而不是单纯按文件数决定。

对 Grill With Docs 的结论

grill-with-docs 适合成熟项目，但不适合作为一次性“全项目代码逆向生成器”。

它擅长：

逐个澄清领域术语；
建立 CONTEXT.md / CONTEXT-MAP.md；
在满足“难逆转、反直觉、有真实权衡”时创建 ADR；
核对代码与用户描述是否一致。

它不擅长直接生成：

页面到 API、Controller、Service、Model 的完整导航；
按钮和路由的代码定位索引；
修改字段的影响分析；
每个应用的验证命令。

结论是：

grill-with-docs 用于领域词汇和重大决策；
trellis-spec-bootstrap 用于成熟代码库的 source-backed Spec 逆向提炼；
架构地图负责快速路由；
Fast Fix Skill 负责限制小改动的初始搜索范围。

关键设计决策

1. 三档工作流

Fast Fix

只在用户明确说“快速修复 / 小改动 / 不建任务 / fast fix”时启用，并要求：

能确定一个 owning package；
修改局部、可逆、契约不变；
预计 1–3 个源码文件；
不涉及支付、退款、订单状态、权限、安全、数据库、数据修复、生产或部署。

Standard Task

用于跨层、共享逻辑、API 字段、路由、权限或根因需要调查的普通功能。轻量任务可只有 prd.md，复杂任务使用 prd.md + design.md + implement.md。

High-Risk Task

支付、退款、状态机、权限、安全、数据库、生产配置、发布和回滚必须走完整 Trellis 规划、契约检查和验证门禁，不能因为文件少而降级。

2. 非破坏性 Spec 桥接

没有移动现有 .trellis/spec/backend/*.md 和 .trellis/spec/frontend/*.md，避免破坏活跃和历史 Task JSONL。

新增 package/layer 短入口：

.trellis/spec/backend/server/index.md
.trellis/spec/miniapp/frontend/index.md
.trellis/spec/merchant-console/frontend/index.md
.trellis/spec/admin-console/frontend/index.md
.trellis/spec/deployment/ops/index.md

Package index 只负责：

说明适用目录；
首选搜索入口；
链接相关共享 Spec；
定义最小质量门。

3. 不设置默认 Package

.trellis/config.yaml 没有设置 default_package，防止未分类 Task 静默继承错误业务应用。新单包任务应显式使用 --package。

4. 证据触发扩大范围

Fast Fix 只限制初始调查范围，不禁止合理扩大。出现 API 契约、后端权限、数据库、支付/退款、跨包权威来源、三次精确搜索无命中或修复超过 3 个源码文件时，必须停止 Fast Fix 并升级为 Trellis Task。

执行动作

Trellis Package 化

.trellis/config.yaml 已声明：

packages:
  backend:
    path: yoshop2.0
  miniapp:
    path: yoshop2.0-uniapp
  merchant-console:
    path: yoshop2.0-store
  admin-console:
    path: yoshop2.0-admin
  deployment:
    path: deploy
 
session:
  spec_scope: active_task

解析结果能够列出五个 Package 和对应 Spec layer。

Fast Fix Workflow

修改 .trellis/workflow.md：

新增“Route before loading”；
新增“Match ceremony to risk”；
Request Triage 支持显式 Fast Fix；
[workflow-state:no_task] 能直接路由 $yoshop-fast-fix；
支付/退款/权限/数据库/生产等场景保留完整门禁。

项目本地 Skill

新增：

.agents/skills/yoshop-fast-fix/
├── SKILL.md
├── agents/openai.yaml
└── references/
    ├── routing.md
    └── validation.md

Skill 执行顺序：

保护已有工作区
→ 风险门
→ 只选择一个 Package
→ 最多先进行三次精确搜索
→ 阅读最小依赖闭包
→ 最小一致修改
→ 最窄验证
→ 完成或升级

明确排除：

.git/
.trellis/tasks/archive/
**/node_modules/
**/vendor/
**/dist/
yoshop2.0/runtime/
yoshop2.0/runtim/
yoshop2.0/public/uploads/
yoshop2.0/public/store/
yoshop2.0/public/admin/
deploy/out/
deploy/reports/

架构导航文档

新增：

docs/architecture/system-map.md
docs/architecture/change-routing.md
docs/architecture/verification-matrix.md

分别用于：

系统边界、入口、源码/生成目录区分；
症状到 Package、首查目录和升级条件的映射；
各 Package 的最窄验证与高风险验证矩阵。

完整中文使用说明书

新增：

docs/ai-development-manual.md

共约 423 行，覆盖：

第一性原理；
三档分流；
文档职责；
Fast Fix 标准流程；
Trellis 生命周期；
Grill/Trellis/Spec/CONTEXT/ADR 衔接；
各 Skill 选择矩阵；
可复制提示词；
知识沉淀决策树；
维护制度；
反模式与故障排查；
Token 优化衡量指标。

根 README.md 已增加说明书和系统地图入口。

后续标准用法

小按钮、文案、样式

使用 $yoshop-fast-fix，不创建 Trellis 任务。
商家后台订单详情页的“复制订单号”按钮和左侧文字太近，期望增加 8px 间距。
先只在 merchant-console 范围定位；除非有明确证据，不要搜索后端和其他应用。
修改后做最窄 lint/页面验证。

小程序局部 Bug

使用 $yoshop-fast-fix，不建任务。
小程序用户页在昵称为空时显示 undefined，期望显示“未设置”。
只从 miniapp 页面和字段消费点开始；如果需要修改 API 字段，停止并建议升级 Trellis Task。

普通跨层功能

这是 Standard Trellis Task。请先创建任务并进入规划。
商家订单列表增加“服务中”筛选，需要核对前端筛选值和后端查询语义。
先写 PRD；确认跨前后端契约后补 design 和 implement，评审后实施。

支付与退款

这是高风险虚拟支付任务，不使用 Fast Fix。
使用 Trellis 完整规划，并加载 virtual-payment Skill 和现有虚拟支付/服务订单 Specs。
先列出上游所有权、本地状态机、幂等、回滚和验证矩阵，再进入实施。

新建单 Package Task

python3 ./.trellis/scripts/task.py create "任务标题" \
  --slug concise-slug \
  --package miniapp

可用 Package：

backend
miniapp
merchant-console
admin-console
deployment

执行命令记录

1. 加载 Trellis 项目上下文

python3 ./.trellis/scripts/get_context.py
python3 ./.trellis/scripts/get_context.py --mode phase
python3 ./.trellis/scripts/get_context.py --mode packages

用途：确认开发者、Git 状态、活跃任务、Trellis Phase 和当前 single-repo 状态。最初输出为：

Feng's Blog

探索

7.15 YoShop 风险分级 AI 开发工作流与使用手册