From 00ab9cdda22d559a0c61f022fdbea01256a5863f Mon Sep 17 00:00:00 2001 From: Qiuyi Chen Date: Thu, 28 May 2026 12:12:31 +0800 Subject: [PATCH] Refine BetterGPT skill routing --- skills/BetterGPT/BetterFrontend/SKILL.md | 80 ++--- .../references/banned-content.md | 88 ++---- .../references/page-rules-dashboard.md | 69 ++--- .../references/page-rules-landing.md | 63 ++-- .../references/pre-delivery-checklist.md | 57 ++-- .../references/production-defaults.md | 59 +--- .../BetterFrontend/references/visual-rules.md | 93 ++---- skills/BetterGPT/BetterLanguage/SKILL.md | 135 +++----- .../references/banned-phrases.md | 39 --- .../references/compression-rules.md | 61 ++-- .../references/conversation-pragmatics.md | 32 ++ .../references/environment-branch.md | 38 +-- .../references/natural-chinese.md | 60 ++-- .../references/path-rendering.md | 99 ++---- .../references/terminal-rendering.md | 42 +-- skills/BetterGPT/BetterSubagents/SKILL.md | 292 ++++-------------- .../references/agent-registry.md | 64 ++-- .../references/dispatch-rules.md | 186 +++-------- skills/BetterGPT/BetterTrellis/SKILL.md | 190 +++--------- .../references/codex-workflow.md | 111 ++----- .../BetterTrellis/references/commands.md | 48 +-- .../BetterTrellis/references/init-flow.md | 97 ++---- .../BetterTrellis/references/structure.md | 73 ++--- skills/BetterGPT/BetterVibe/SKILL.md | 8 +- .../references/backend-boundaries.md | 42 +-- .../references/frontend-boundaries.md | 38 +-- .../references/fullstack-boundaries.md | 46 +-- skills/BetterGPT/SKILL.md | 85 ++--- skills/BetterGPT/references/load-policy.md | 45 +-- skills/BetterGPT/references/routing.md | 119 ++----- tests/test_skill_repo.py | 2 +- 31 files changed, 737 insertions(+), 1724 deletions(-) delete mode 100644 skills/BetterGPT/BetterLanguage/references/banned-phrases.md create mode 100644 skills/BetterGPT/BetterLanguage/references/conversation-pragmatics.md diff --git a/skills/BetterGPT/BetterFrontend/SKILL.md b/skills/BetterGPT/BetterFrontend/SKILL.md index 5374942..f165240 100644 --- a/skills/BetterGPT/BetterFrontend/SKILL.md +++ b/skills/BetterGPT/BetterFrontend/SKILL.md @@ -1,67 +1,55 @@ --- name: better-frontend -description: Use when generating, revising, polishing, or reviewing frontend UI, landing pages, dashboards, app screens, marketing pages, or other presentation-layer output that should look like a production-ready product instead of a demo, draft, wireframe, showcase, or developer-facing mockup. Especially use when the request mentions removing AI-like UI, avoiding demo feel, preventing TODO or note text, hiding reasoning or design commentary from users, eliminating placeholder explanations, or making the final interface feel shippable, real, and user-facing. +description: Use for frontend cleanup, dashboards, app screens, or presentation review. Remove TODOs/placeholders/dev reasoning with small diffs; preserve UI language; avoid decorative rewrites. --- # Better Frontend -## Overview +## Scope -把所有前端展示层任务默认当作正式可交付成品处理。 -优先保证用户可见结果可直接落地，而不是像原型、草稿、演示稿或开发中间态。 +Use this skill for user-visible UI work: pages, dashboards, admin/workbench surfaces, app screens, landing pages, and frontend copy. -## Trigger Signals - -当请求或上下文出现以下信号时，应优先使用本 skill： - -- 用户要求做前端页面、落地页、仪表盘、控制台、工作台、营销页、应用界面 -- 用户强调“像正式产品”“能上线”“不要 demo 感”“不要 AI 味” -- 用户要求删除用户可见界面中的开发者备注、思路说明、设计评论、占位解释 -- 用户提到“不准把 TODO / NOTE / mock / placeholder / reasoning 放到页面里” -- 用户要求“润色 UI”“收敛视觉输出”“把页面改得更像真实产品” -- 当前方案明显更像原型、概念稿、样板页、作品集展示，而不是正式成品 - -## When Not to Use - -- 用户明确要求 wireframe、低保真草图、教学示例页、组件演示页 -- 任务只是在写技术文档、设计说明、评审备注，而不是在生成用户可见前端 -- 任务只涉及后端接口、数据库、脚本或 CLI，不涉及展示层输出 +Goal: make the visible product usable and production-ready without turning small cleanup into a redesign. ## Hard Constraints -- 禁止把面向开发者的备注、思维过程、设计评论、实现说明、占位解释输出到用户可见界面。 -- 禁止把“材质感、光影、动效、视觉工艺”的解说型文案写进用户可见副标题、说明文案、卡片描述。 -- 默认按正式产品界面开发，不按 demo、wireframe、概念稿、展示稿思路产出。 -- 优先交付真实用户可理解、可操作、可上线的前端结果。 -- 非用户显式要求时，不向界面中加入“开发中”“示例数据”“后续接接口”“这里可扩展”等说明性文本。 -- 不与当前项目内的 `.trellis/spec/frontend/*` 长期维持两套平行前端规范。 +- Never expose developer notes, TODOs, placeholder explanations, mock/demo labels, implementation plans, design commentary, or reasoning in user-visible UI. +- Preserve the current visible language and product shape unless the user explicitly asks to translate or redesign. +- For an existing page, inspect the current structure and line count before editing. Default to a local diff; do not replace the whole file for copy/demo cleanup. +- For cleanup/productization of a small existing page, keep the result within `max(original_lines + 80, original_lines * 2)` unless the user explicitly asks for a redesign. If that limit is insufficient, explain why before broadening scope. +- Do not use web search for local UI cleanup unless the user asks for external competitors, assets, or current information. +- Dashboard/admin/ops surfaces should be restrained, dense, and scannable; do not use marketing heroes, decorative gradients, glass blur, glow, or large-radius styling as the default way to look polished. +- Cards and panels default to `border-radius <= 8px` unless the project design system already uses larger radii. +- If the project has `.trellis/spec/frontend/`, treat it as the primary frontend rule source; references here are fallback guidance. ## Default Working Rules -1. 先判断哪些内容属于用户可见展示层，哪些内容只应留在代码、注释或对话中。 -2. 对展示层文案做一次泄漏检查，删掉所有开发者视角文本。 -3. 对页面结构做一次产品化检查，确认它像正式成品，而不是演示模板。 -4. 优先收敛界面信息密度、视觉层级、组件用途和文案意图，避免为了“解释设计”而污染界面。 -5. 副标题、说明文案、卡片描述默认必须服务用户任务：解释状态、结果、风险、收益、下一步动作；如果主要是在描述界面怎么好看、材质怎么真实、动效怎么细腻，就不应进入展示层。 -6. 如果页面类型是功能页、工具页、数据页、控制台、工作台，默认禁止把营销页式氛围描写、设计旁白、展示稿话术带入副标题。 -5. 如果当前项目存在 `.trellis/spec/frontend/`，前端规范优先参考该目录；本 skill 自带 references 只做补充，不单独形成第二套平行规范。 +1. Identify the visible UI and the exact request type: cleanup, polish, redesign, or new build. +2. For existing pages, record `wc -l` and make the smallest patch that can satisfy the request. +3. Clean visible copy: remove TODO/FIXME/NOTE, placeholder/mock/demo language, future-backend text, sample disclaimers, and developer-facing explanations. +4. Productize within the current layout first: labels, statuses, actions, spacing, borders, and only the structure needed for the user task. +5. Before final, run narrow checks: + - `wc -l ` and compare against the cleanup line-count budget. + - `rg -n 'TODO|FIXME|NOTE:|placeholder|mock|demo|sample|future backend|developer|reasoning' `. + - For HTML, strip tags and scan visible text when class names cause false positives. + - For dashboard/admin pages, scan CSS for `radial-gradient`, `backdrop-filter`, `filter: blur`, heavy `box-shadow`, or `border-radius` above `8px`. +6. Final report should state the result, checks run, and residual risk only; do not add a generic optional follow-up after a narrow cleanup. ## Read References When Needed -- 需要判断哪些内容绝不能进入展示层时，读 `references/banned-content.md` -- 需要判断默认成品化标准时，读 `references/production-defaults.md` -- 需要判断前端视觉输出约束时，读 `references/visual-rules.md` -- 需要做 dashboard、admin、workbench 等后台页面时，读 `references/page-rules-dashboard.md` -- 需要做 landing page、营销页、品牌展示页时，读 `references/page-rules-landing.md` -- 需要交付前做最终自检时，读 `references/pre-delivery-checklist.md` +- Read `references/banned-content.md` for content that must not appear in visible UI. +- Read `references/production-defaults.md` for default production-readiness standards. +- Read `references/visual-rules.md` for visual output constraints. +- Read `references/page-rules-dashboard.md` for dashboard, admin, and workbench pages. +- Read `references/page-rules-landing.md` for landing pages and brand/product pages. +- Read `references/pre-delivery-checklist.md` before final delivery. ## Red Flags -出现以下任一情况时，先停下并回退： +Stop and revise if any of these appear: -- 页面上出现 TODO、NOTE、placeholder explanation、mock 提示、设计备注 -- 用户可见文案在解释“这个模块是干什么的给开发者看” -- 用户可见副标题或描述文案在解释玻璃、高光、折射、渐变、漂浮、镜面、雾面、霓虹、层叠、虚化等视觉工艺 -- 页面文案读起来像作品集、设计稿旁白、展示稿解说，而不是产品界面语言 -- 页面更像模板站、演示稿、AI 样例，而不像真实产品 -- 为了说明思路，把实现过程、评审说明或设计讨论直接写进 UI +- Visible TODO, NOTE, placeholder explanation, mock/demo label, design note, or implementation plan. +- Visible copy explains the UI to a developer instead of helping the end user act. +- A small cleanup expands into a template rewrite or exceeds the line-count budget without explicit user approval. +- The visible UI language changes without user request. +- Dashboard/admin/ops pages gain a hero, decorative chart, decorative KPI row, right rail, gradient/glass/glow treatment, or many rounded pills just to look busy. diff --git a/skills/BetterGPT/BetterFrontend/references/banned-content.md b/skills/BetterGPT/BetterFrontend/references/banned-content.md index d15cfc0..908795e 100644 --- a/skills/BetterGPT/BetterFrontend/references/banned-content.md +++ b/skills/BetterGPT/BetterFrontend/references/banned-content.md @@ -1,78 +1,28 @@ -# Banned Content in User-Visible UI +# Banned Content In Visible UI -以下内容默认不得进入前端展示层： +Visible UI must serve the end user, not the developer, reviewer, or design process. -## 1. 面向开发者的备注 +## Ban -- TODO -- FIXME -- NOTE: -- 这里后续接接口 -- 这里替换成真实数据 -- 开发阶段先这样 -- 该区域可继续扩展 +- `TODO`, `FIXME`, `NOTE:` +- `mock`, `placeholder`, "sample", "demo" +- "connect backend later" +- "replace with real data" +- "this section demonstrates..." +- "this component shows..." +- "temporary implementation" +- explanations of design decisions or implementation choices +- copy that describes the UI material itself, such as glass, glow, refraction, blur, floating layers, shimmer, or gradient richness -## 2. 思维过程或设计评论 +## Rule -- 我这里这样设计是因为…… -- 为了演示这个能力…… -- 此处用于说明某个技术点…… -- 这个模块展示了…… -- 这里先用一个简单实现…… +If the sentence explains how the interface was built, why it looks good, or what it is demonstrating, keep it out of the visible product surface. -## 2.1 伪产品化的设计旁白 +## Allowed Direction -以下内容即使不出现“TODO / NOTE”，默认也不应进入用户可见界面： +Replace developer/design commentary with user-facing state, outcome, risk, or action. -- 阳光以柔顺渐变铺满界面 -- 卡片表面的镜面高光会随着鼠标移动产生真实折射 -- 冷色玻璃与雨滴动画同步起伏 -- 玻璃表层偏雾面 -- 霓虹反射、层叠、沉浸、质感更强、层次丰富 -- 在描述高光、渐变、折射、镜面、玻璃、虚化、漂浮、扫光、流动时，主语是“界面 / 卡片 / 画面 / 动效”而不是用户任务 +Examples: -判定原则： - -- 如果一句话主要是在解释界面怎么好看、材质怎么真实、动效怎么细腻 - → 它属于设计旁白，不属于产品文案 -- 即使这句话写得很像营销文案，只要它不服务用户状态、任务、结果、风险、收益 - → 也不应进入展示层 - -## 3. 面向评审者或开发者的解释性文本 - -- 点击这里查看组件效果 -- 这是一个示例卡片 -- 下方用于演示布局能力 -- 这段文案仅用于占位 -- 当前使用 mock 数据 - -## 4. 不应直接暴露给终端用户的工程状态 - -- 开发中 -- 待实现 -- 暂未接入后端 -- 未来支持更多功能 -- 可对接 API - -## 处理原则 - -- 用户看得到的地方，只保留服务用户任务的内容。 -- 开发者信息应留在注释、提交说明、对话解释、设计文档或工单里。 -- 如果一句话主要是在向开发者或评审解释实现过程，就不应进入展示层。 -- 如果一句话主要是在向用户“展示这个界面有多会做设计”，也不应进入展示层。 - -## 错误文案 vs 正确文案 - -### 错误 - -- 阳光以柔顺渐变铺满界面 -- 镜面高光会随着鼠标移动产生真实折射 -- 冷色玻璃与雨滴动画同步起伏 -- 玻璃表层偏雾面，雪片在近景和远景之间切换 - -### 正确 - -- 阳光充足，紫外线较强，适合短时户外活动 -- 阵风明显，体感偏低，外出建议增加防风层 -- 降雨持续，能见度下降，通勤请预留更多时间 -- 气温持续低于零度，出行请注意保暖和地面湿滑 +- Instead of visual-material commentary, show weather, finance, workflow, or domain state. +- Instead of "mock data", either wire real data, label a real empty state, or keep the note in code/docs rather than UI. diff --git a/skills/BetterGPT/BetterFrontend/references/page-rules-dashboard.md b/skills/BetterGPT/BetterFrontend/references/page-rules-dashboard.md index 8ee8959..29d716a 100644 --- a/skills/BetterGPT/BetterFrontend/references/page-rules-dashboard.md +++ b/skills/BetterGPT/BetterFrontend/references/page-rules-dashboard.md @@ -1,57 +1,32 @@ -# Dashboard / Admin / Workbench Rules +# Dashboard / Admin / Workbench Pages -## Scope +Use for dashboard, admin, console, workspace, workbench, internal tool, and data-heavy operation pages. -适用于以下页面类型： +## Goal -- dashboard -- admin -- console -- workspace -- workbench -- internal tool -- data-heavy operation page +Make the page efficient, stable, and maintainable. It should support repeated work, not perform like a marketing hero. -## Core Goal +## Prefer -让后台、控制台、工作台看起来像长期可维护的真实产品，而不是营销站首屏、AI 样板后台或为了展示设计能力拼出来的面板墙。 +- Direct sidebar/content or filter/table/list/detail structures. +- First-screen access to the main operation, state, result, or queue. +- Charts only for real trend, comparison, or distribution questions. +- Cards only for meaningful grouping. +- Functional copy for filters, forms, tables, statuses, and feedback. +- In-place cleanup for existing dashboard files: improve copy, spacing, borders, and labels before adding new regions. -## Positive Rules +## Avoid -- 先围绕真实任务路径组织页面，再决定布局 -- 首屏优先展示最重要的操作、状态、列表、过滤、表单或工作结果 -- 信息架构保持直接、稳定、可预期 -- 卡片只在确实需要信息分组时使用 -- 图表只在真实存在趋势、对比、分布需求时使用 -- 页面标题直接表达当前页面职责，不写空泛口号 +- hero sections in admin pages +- KPI-card rows as the default first response +- charts, progress rings, or trend arrows without real data purpose +- command-center or cockpit language for ordinary workflows +- decorative right rails added only to make the page look busy +- repeated oversized rounded cards and pills across every surface +- rewriting a small existing page into a large dashboard template when the user mainly asked to remove demo/placeholder leakage -## Hard No +## Check -- 不要在后台首页放 hero section -- 不要默认做 KPI 卡片横排作为第一反应 -- 不要没有真实业务需求就塞图表、环图、进度条、趋势箭头 -- 不要把后台页面写成“控制中心”“作战台”“指挥舱”式自嗨视觉稿 -- 不要用大段文案解释这个后台多么高效、多么清晰、多么强大 -- 不要在侧边栏、面板、表格、统计卡上重复同一种夸张圆角和装饰风格 -- 不要做左右双 rail + 中间内容的“信息很多但没有任务主线”布局 +The user should quickly see what they can do, where to click, and what state needs attention. -## Common Smells - -- 顶部一整块大横幅 + slogan + 副文案 -- 首屏 4 个以上统计卡，但没有明确主任务入口 -- 没有真实数据结构却硬塞多种图表 -- 右侧做一个“今日安排 / 最近动态 / 系统状态”装饰栏，只是为了显得页面充实 -- 每个模块都像展示组件，而不像用户真正会用的工作区域 - -## Default Layout Bias - -- 优先正常 sidebar + content，或 filter + table / list / detail 的成熟结构 -- 优先直接暴露任务入口，不先演一段视觉概念 -- 优先让用户一眼看清：我能做什么、我该点哪里、当前状态是什么 - -## Copy Bias - -- 标题写页面目的，不写设计口号 -- 副文案只在能减少理解成本时保留 -- 表格、表单、筛选、状态反馈都用直接、真实、功能性语言 -- 不向用户解释“这个模块展示了什么能力” +For cleanup of an existing page, compare the final line count with the original. If it exceeds `max(original_lines + 80, original_lines * 2)`, treat that as a redesign and require explicit user intent or a clear explanation. diff --git a/skills/BetterGPT/BetterFrontend/references/page-rules-landing.md b/skills/BetterGPT/BetterFrontend/references/page-rules-landing.md index 951cef0..3fe187f 100644 --- a/skills/BetterGPT/BetterFrontend/references/page-rules-landing.md +++ b/skills/BetterGPT/BetterFrontend/references/page-rules-landing.md @@ -1,54 +1,27 @@ -# Landing / Marketing Page Rules +# Landing / Marketing Pages -## Scope +Use for landing, marketing, brand, product intro, or feature showcase pages. -适用于以下页面类型： +## Goal -- landing page -- marketing page -- brand page -- product intro page -- feature showcase page +Build a page with clear value, audience, evidence, and action. Visual style may be stronger than an admin tool, but every section must support the story or conversion. -## Core Goal +## Prefer -让营销页或品牌展示页看起来像真实产品团队打磨过的正式页面，而不是 AI 批量生成的“高级感网页模板”。 +- Hero that quickly says what this is, who it is for, and why it matters. +- Specific benefits, proof, scenarios, and differentiators. +- CTA copy that names the action. +- Trust support near conversion points. +- Concrete product language over abstract slogans. -## Positive Rules +## Avoid -- 先明确价值主张、受众、转化动作，再决定视觉表达 -- 页面节奏围绕信息递进、信任建立、行动转化展开 -- 主标题、副标题、证明信息、CTA 各司其职 -- 视觉可以更强，但每个模块都必须服务叙事和转化 -- 文案要具体、有对象、有结果，不说空泛漂亮话 +- generic slogans such as "redefine the future" or "unlock potential" +- a full page of feature cards without a clear product claim +- glass, neon, gradient, glow, badge, pill, or floating-panel excess +- dashboard KPI blocks inserted only for decoration +- abstract buzzwords replacing actual user value -## Hard No +## Check -- 不要靠玻璃拟态、夸张渐变、科技蓝紫光污染来冒充高级感 -- 不要堆一页“功能卡片”但说不清产品到底解决什么问题 -- 不要写空泛口号，例如“重新定义未来”“释放无限潜力”“打造下一代体验” -- 不要把后台式 KPI 模块硬塞进营销页 -- 不要用过多 badge、pill、装饰性 icon、悬浮面板制造设计感 -- 不要用大量抽象词替代真实卖点、证据和使用场景 - -## Common Smells - -- 页面第一屏只有漂亮标题和抽象文案，没有真实价值信息 -- 每个 section 看起来都像 Dribbble 样板 -- 为了显得专业，塞大量渐变块、发光边框、柔和阴影、浮层卡片 -- CTA 附近没有清晰的利益点和信任支撑 -- 用户看完页面，只知道“挺好看”，但不知道产品是什么、适合谁、该不该点 - -## Default Structure Bias - -- hero 只负责快速讲清楚：这是什么、给谁用、为什么值得继续看 -- 中段优先放证据、能力、场景、差异，而不是连续堆视觉样式 -- CTA 前优先补强信任，而不是继续装饰 -- 页面结构要像有销售逻辑，而不是像 UI 样板合集 - -## Copy Bias - -- 标题说人话，不说生成式品牌黑话 -- 副标题优先讲收益、对象、使用结果 -- CTA 要明确，不做模糊邀请 -- 少用“革命性”“智能化”“生态级”“全链路赋能”这类空洞词 +After the first screen, the user should know what the offer is, whether it is for them, and what to do next. diff --git a/skills/BetterGPT/BetterFrontend/references/pre-delivery-checklist.md b/skills/BetterGPT/BetterFrontend/references/pre-delivery-checklist.md index aaf4e53..23910c6 100644 --- a/skills/BetterGPT/BetterFrontend/references/pre-delivery-checklist.md +++ b/skills/BetterGPT/BetterFrontend/references/pre-delivery-checklist.md @@ -1,49 +1,30 @@ # Pre-Delivery Checklist -在宣称前端结果可交付前，至少快速检查以下项目。 +Run this before calling a frontend result deliverable. -## 1. Developer Leakage Check +## Developer Leakage -- 页面里是否出现 TODO、NOTE、FIXME、mock、placeholder、reasoning、设计评论 -- 页面里是否出现“这里后续接接口”“这里替换成真实数据”之类文本 -- 页面里是否出现面向开发者或评审者的解释 -- 页面里是否出现“玻璃、高光、折射、渐变、镜面、雾面、霓虹、漂浮、层叠、虚化、沉浸、质感”这类本该属于设计旁白的词 +- No `TODO`, `FIXME`, `NOTE:`, `mock`, `placeholder`, or developer-facing explanation. +- No text saying the UI is a sample, demo, extensible area, or future backend integration. +- No visible design commentary about glass, glow, gradients, refraction, blur, material, or animation craft. -## 2. Production Readiness Check +## Product Readiness -- 这个页面看起来像正式产品，而不是 demo、原型、草稿、概念稿 -- 页面结构是否围绕真实用户任务，而不是围绕“展示设计能力” -- 文案是否像真实产品文案，而不是 AI 模板话术 +- The first screen supports the main user task. +- Page title and copy describe product state or action, not design intent. +- Empty, loading, error, and success states are credible for the domain. +- Components have a clear reason to exist. +- For existing-page cleanup, the final line count stays within the local-change budget or the task was explicitly a redesign. -## 3. Visual Smell Check +## Visual Smell -- 是否在靠大圆角、渐变、玻璃、发光、阴影堆出所谓高级感 -- 是否出现卡片堆砌、badge 滥用、装饰性图表、无意义统计块 -- 是否存在 hero 化后台、模板化 landing、概念稿式 section 拼盘 +- No dashboard hero by default. +- No decorative KPI cards, charts, badges, or side panels without a real data need. +- No large-radius, glow, blur, or gradient stack used as the main quality signal. +- No language switch in visible UI unless the user requested translation. -## 4. Content Value Check +## Final Gate -- 标题是否直接说明页面目的 -- 副文案是否真的减少理解成本 -- 页面里的每个模块是否有明确任务价值 -- 如果删掉装饰性模块，页面是否仍能成立 +If the page reads like a demo, design explanation, or AI showcase, revise before delivery. -### 4.1 Subtitle Gate - -逐条检查副标题、卡片描述、说明文案： - -- 它是在帮助用户理解状态、结果、风险或下一步吗？ -- 如果删掉“材质感、光影感、动效感”的词，这句话还成立吗？ -- 这句话更像产品文案，还是更像设计稿旁白？ - -如果答案偏向后者，就不应直接交付。 - -## 5. Final Gate - -如果以下任何一项答案为“是”，则不应直接交付： - -- 我是不是把开发者思路写进了 UI -- 我是不是把设计旁白、材质解说、动效解说写进了 UI -- 我是不是在用装饰替代真实信息层级 -- 我是不是做出了 AI 样板感、demo 感、showcase 感 -- 我是不是加入了用户其实不需要的大段解释文案 +For narrow cleanup tasks, final response should be result plus verification only. Do not add generic optional next-step offers. diff --git a/skills/BetterGPT/BetterFrontend/references/production-defaults.md b/skills/BetterGPT/BetterFrontend/references/production-defaults.md index 8c47d67..7900591 100644 --- a/skills/BetterGPT/BetterFrontend/references/production-defaults.md +++ b/skills/BetterGPT/BetterFrontend/references/production-defaults.md @@ -1,52 +1,27 @@ # Production Defaults -默认把前端任务视为正式产品交付，而不是原型展示。 +Treat frontend work as production-facing unless the user explicitly asks for a demo, wireframe, low-fidelity sketch, teaching example, or component gallery. -## 默认假设 +## Defaults -- 默认面向真实用户，而不是面向开发者或评审者 -- 默认页面需要长期存在，而不是一次性演示 -- 默认文案要真实、克制、可理解 -- 默认组件要有明确用途，不能只是“为了展示会做 UI” +- Real users, not reviewers, are the audience. +- The page should look maintainable, not one-off. +- Copy should be short, concrete, and useful. +- Components need a real task or information purpose. +- Empty, loading, form, list, and feedback states should feel product-ready. -## 页面级要求 +## Copy Gate -- 页面结构应围绕真实用户任务组织 -- 空态、列表态、表单态、反馈态要像真实产品 -- 视觉层级应帮助操作，不应服务开发说明 -- 能删掉的装饰性说明就删掉 +Visible text should help the user understand: -## 文案级要求 +- current state +- available action +- result +- risk or limitation +- next required step -- 文案优先表达用户价值和操作结果 -- 不解释实现过程 -- 不解释设计意图 -- 不描述界面材质、视觉工艺、动效质感，除非用户明确要求展示稿或品牌视觉稿 -- 不提醒用户“这是示例”或“这是占位”，除非用户明确要求演示稿 +Remove text that mainly describes visual material, animation, layout craft, or implementation intent. -### 副标题默认规则 +## Boundaries -- 副标题默认必须至少服务以下之一： - - 帮用户理解当前状态 - - 帮用户理解收益或结果 - - 帮用户理解风险、限制或下一步动作 -- 如果一段副标题主要在描述高光、玻璃、折射、渐变、镜面、漂浮、雾面、霓虹、层叠、沉浸感 - → 默认判为无任务价值，不应进入产品界面 - -### 页面类型边界 - -- 营销页 / 品牌页 - → 可有限使用氛围型语言，但仍需服务价值主张和转化 -- 功能页 / 工具页 / 数据页 / 控制台 / 工作台 - → 默认禁止把设计旁白、材质描写、动效自述写进副标题或说明文案 - -## 非默认模式 - -只有在用户明确要求以下产物时，才允许偏离正式成品默认值： - -- demo -- wireframe -- low-fidelity 草图 -- 技术展示页 -- 教学示例页 -- 组件示例画廊 +Marketing pages may use more atmosphere, but still need a value proposition and conversion logic. Tools, dashboards, data pages, and workbenches should stay direct and task-focused. diff --git a/skills/BetterGPT/BetterFrontend/references/visual-rules.md b/skills/BetterGPT/BetterFrontend/references/visual-rules.md index 100431b..0d75a12 100644 --- a/skills/BetterGPT/BetterFrontend/references/visual-rules.md +++ b/skills/BetterGPT/BetterFrontend/references/visual-rules.md @@ -1,74 +1,39 @@ -# Visual Output Rules +# Visual Rules -## Core Goal +Make the surface feel like a maintained product, not a generated showcase. -让界面看起来像真实产品，而不是 AI 生成样例、模板站、演示板或“为了显得高级而过度设计”的前端。 +## Priorities -## Visual Philosophy +1. Clear task path. +2. Stable layout. +3. Useful information hierarchy. +4. Consistent spacing, radius, borders, and shadows. +5. Visual style that supports the domain. -- 先做正常、克制、稳定的产品界面，再谈装饰 -- 先保证信息层级清楚、布局合理、操作明确，再考虑视觉花样 -- 默认追求“像真实团队长期维护的产品”，而不是“像 AI 一次性生成的好看截图” -- 可以参考成熟产品的克制感，但不要把“像某个产品”做成表演性模仿 +## Prefer -## Positive Rules +- Existing design language when present. +- Conservative layout for admin, dashboard, and operational tools. +- Components that expose real user action or real information. +- Short product copy with concrete state, result, or action. +- Cards only for genuine grouping, repeated items, or framed tools. +- Small, local changes when improving an existing page that mainly has copy leakage or demo styling. -- 组件存在必须服务真实信息展示或真实用户操作 -- 视觉层级先服务任务，再服务装饰 -- 页面结构应自然、稳定、可预期，不故意炫技 -- 文案要短、准、自然，贴近真实产品语境 -- 标题、正文、操作区、反馈区要职责清晰 -- 配色应克制，优先使用项目既有设计语言；没有现成设计语言时，选保守、安全、耐看的方案 -- 间距、圆角、边框、阴影保持一致，不要每个模块都想“做得特别一点” +## Avoid -## Hard No +- marketing-style hero sections inside dashboards +- decorative KPI cards without a task need +- badges, pills, charts, and status dots with no information value +- glassmorphism, neon glow, heavy blur, exaggerated gradients, and large rounded rectangles as default polish +- developer notes, implementation explanations, design commentary, or AI-style placeholder copy +- self-important names such as command center or cockpit for ordinary tools -- 不要把大段解释性文字塞进界面 -- 不要把“设计说明”“实现说明”“产品评论”伪装成页面内容 -- 不要堆砌只是为了显得丰富的卡片、标签、统计块、占位图表 -- 不要把开发阶段说明、技术说明、评审提示混进页面 -- 不要把 dashboard 做成带 hero section 的营销页 -- 不要默认使用悬浮玻璃、模糊发光、炫技渐变、大面积蓝紫科技风来冒充质感 -- 不要默认使用过大的圆角、药丸按钮、药丸标签、漂浮侧边栏 -- 不要把 hover 动效、transform 位移、阴影爆炸当成高级感来源 -- 不要为了“像 AI 作品”去加装饰性小标题、眉标、解释型副标题 -- 不要把“控制中心”“指挥台”“运营脉搏”这类自嗨命名塞进普通后台 +## Review -## Common AI-Like Smells +Before delivery, ask: -出现以下模式时，应高度怀疑界面正在变得“很 AI”： - -- 第一反应就是三四个 KPI 卡片横排 -- 页面顶部先来一句装饰性 slogan，再来一段解释文案 -- 明明是内部工作台，却做成营销站首屏 -- 左侧栏、卡片、按钮、面板全部使用同一套大圆角圆润矩形 -- 没有真实数据需求，却硬塞图表、环图、进度条 -- 用大量 muted 灰蓝文字、渐变背景、霓虹强调色伪造高级感 -- 到处都是 badge、状态点、小标签，但没有实际信息价值 -- 页面看起来像模板拼装，而不是围绕真实任务设计 - -## Layout Defaults - -- 后台、控制台、工作台优先采用正常信息架构，不默认做 hero 化首屏 -- 侧边栏使用正常宽度和稳定边界，不做悬浮外壳 -- 内容区先保证主任务路径明确，不在首屏堆满“看起来很多”的内容 -- 卡片只在确实需要分组信息时使用，不把卡片当默认容器 -- 图表只在真实存在趋势、分布、比较需求时出现 - -## Copy Defaults - -- 页面文案服务用户任务，不服务设计解释 -- 标题直接说明页面目的，不写空泛口号 -- 副文案只在真正能降低理解成本时保留 -- 不用“这里统一管理……”“在这里你可以……”这种模板化引导句充版面 -- 不把“这是某个区域/模块/能力”这种开发者视角定义写给用户看 - -## Quick Review Checklist - -交付前至少快速检查一次： - -1. 如果删掉所有装饰性文案，页面是否仍然成立 -2. 如果删掉所有 badge、图表、统计卡，页面是否仍有清晰主任务 -3. 页面首屏是否像真实产品，而不是像营销图或 AI 样板 -4. 页面是否在用渐变、圆角、阴影、动效替代真实层级 -5. 页面中是否混入任何开发者备注、设计评论、实现过程说明 +- Does the first screen support the user's main job? +- Is any decoration replacing real structure? +- Would the UI still work after removing decorative copy and nonessential badges/charts? +- Is any visible text written for developers instead of users? +- Did the edit preserve the page's visible language and avoid unnecessary line-count growth? diff --git a/skills/BetterGPT/BetterLanguage/SKILL.md b/skills/BetterGPT/BetterLanguage/SKILL.md index ecc7606..f432660 100644 --- a/skills/BetterGPT/BetterLanguage/SKILL.md +++ b/skills/BetterGPT/BetterLanguage/SKILL.md @@ -1,119 +1,82 @@ --- name: better-language -description: Use when GPT-5.4 style answers need to be rewritten into concise, natural Chinese with minimal filler, no internet slang or habitual phrasing, and a strict two-part structure that users can scan top-to-bottom at a glance. Especially use when the output should preserve two-part reasoning and solution flow without always printing rigid section titles, allow light line breaks for readability, remove translation-like Chinese, and switch to terminal-friendly rendering when the current surface is CLI or shell rather than an app-style chat surface. +description: Use for final user-facing answers in Chinese after English-first technical work. Keep code, commands, logs, paths, API names, and product names unchanged; add short Chinese explanations for necessary English terms. Avoid rigid templates. --- # Better Language ## Overview -把偏长、偏散、偏有口癖、偏翻译腔的 GPT-5.4 输出，收敛成简洁、自然、可快速扫描的中文回答。 -默认只保留两段结构，但允许段内轻换行： +这是输出层 skill，不是思考层模板。 -1. 原因分析 -2. 解决办法 +默认工作方式： -## Trigger Signals +1. 用英文完成技术判断、代码理解、资料筛选和执行计划。 +2. 不暴露内部推理过程。 +3. 最后只把用户需要看的结果、证据、动作和风险，用自然中文交付。 -当请求或上下文出现以下信号时，优先使用本 skill： +## Core Rule -- 用户要求压缩 GPT-5.4 输出 -- 用户要求去掉口癖、黑话、训练腔、互联网表达 -- 用户要求去掉英文汉化式中文、翻译腔、硬邦邦的书面结构 -- 用户强调“不要长篇大论”“要一目了然”“从上往下读就懂” -- 用户要求输出固定为“原因分析 + 解决办法” -- 当前答案已经明显过长、过散、过度展开 +最终回答默认是中文正文。 -## Hard Constraints +必要英文术语可以保留，但第一次出现时尽量加中文括注。代码、命令、日志、路径、配置键、API 名、模型名、产品名和文件名保持原样。 -- 输出默认只保留两个主段落：`原因分析`、`解决办法` -- 每个主段落默认短而密，但允许 1 到 3 个短句块换行 -- 禁止使用网络黑话、口头禅、训练腔模板句 -- 默认不要在普通汇报中输出绝对路径，但若当前平台、上层系统规则或用户要求必须给出绝对路径，则按上层要求覆盖 -- 禁止额外追加“总结”“补充说明”“延伸建议”“如果你愿意”之类尾巴 -- 禁止在答案末尾主动发起继续对话的邀约 -- 即使不出现“如果你愿意”，也禁止使用同类变体表达 -- 默认最后一句必须可以直接收束全文，而不是把用户往下一轮推 -- 禁止把同一意思换不同说法重复两遍 -- 禁止为了显得完整，自动展开背景、原理、历史、价值判断 -- 禁止写出明显像英文逻辑直译过来的中文句子 +不要把英文推理逐句翻译成中文，也不要为了形式套固定模板。 -## Environment Branch +## Trigger Signals -先判断当前输出面，再决定排版方式： +- 用户要求中文输出，但任务包含代码、命令、日志、论文、API、英文文档或技术判断 +- 用户明确偏好“英文思考，中文交付” +- 用户要求压缩回答、减少口癖、去掉训练腔或翻译腔 +- 用户强调“不要长篇大论”“一眼看懂”“直接说结果” +- 当前展示面更像 CLI / shell / 终端对话，需要纯文本扫读 -- 如果当前更像 app、普通聊天界面、富文本界面 - → 保持 `BetterLanguage` 默认两段式和轻换行 -- 如果当前更像 CLI、terminal、shell、终端对话 - → 继续保留两段式内容结构，但叠加终端友好排版 +## Hard Constraints -环境分支只影响排版和呈现，不改变核心内容约束。 +- 不默认使用固定的 `原因分析 / 解决办法` 两段式 +- 不输出 chain-of-thought、内部草稿、完整思考路线 +- 不为了“中文完整”而翻译技术对象 +- 不自动补背景、原理、历史、价值判断 +- 禁止把同一意思换不同说法重复两遍 +- 不用空泛邀约替代行动；缺关键信息时问一个具体问题，下一步明确时直接给结论或继续推进 ## Default Working Rules -1. 先识别原回答里真正有价值的信息点。 -2. 删除铺垫、复述、寒暄、表演性过渡句。 -3. 把剩余内容压缩到两个段落中。 -4. `原因分析` 只解释为什么会这样。 -5. `解决办法` 只给直接可执行的处理路径。 -6. 能短句说清就不用长句，能一句说清就不用三句。 -7. 段内需要减压时，用轻换行拆成 1 到 3 个短句块。 -8. 优先使用自然中文句法，不照搬英文式抽象表达。 -9. 如果当前是终端型界面，再额外应用终端排版规则。 -10. 汇报文件、命令、产物时，优先显示文件名或项目相对路径；若当前平台或用户要求绝对路径，则按要求展示。 -11. 结尾前检查最后一句，若删除后答案仍完整，则删掉该尾句。 -12. 除非用户明确要求，否则不要用邀约式问句作为结尾。 - -## Read References When Needed - -- 需要判断哪些词句必须禁用时，读 `references\banned-phrases.md` -- 需要判断如何压缩段落和控制展开度时，读 `references\compression-rules.md` -- 需要判断怎样消除翻译腔并改成自然中文时，读 `references\natural-chinese.md` -- 需要判断当前更像 app 还是 CLI 时，读 `references\environment-branch.md` -- 需要在 CLI 中做终端友好排版时，读 `references\terminal-rendering.md` -- 需要判断文件路径、命令、生成产物该如何展示时，读 `references\path-rendering.md` +1. 先用英文技术语境完成判断，不急着生成中文。 +2. 识别用户真正需要看的信息：结果、关键证据、已做动作、剩余风险。 +3. 删除铺垫、复述、寒暄、表演性过渡句。 +4. 把英文判断压缩成自然中文，不逐句翻译。 +5. 能一句说清就不要拆成模板；需要分组时再加短标题。 +6. 汇报文件、命令、产物时，优先显示文件名或项目相对路径；必要时再给绝对路径。 +7. 需要互动时，提出一个能改变方案或执行路径的具体问题；不需要互动时，不把问题推回给用户。 +8. 结尾前检查最后一句，若删除后答案仍完整，则删掉该尾句。 ## Output Contract -默认输出骨架如下： +默认顺序： -```text -[短句块 1] +1. 结果 +2. 关键证据或已做动作 +3. 必要时给剩余风险或未验证项 -[短句块 2，可选] +普通短答可以只有一段。结构化时用短标题，例如 `已完成`、`验证`、`剩余风险`。 ---- - -[短句块 1] - -[短句块 2，可选] -``` - -默认保留两段职责，但不强制每次显式打印“原因分析 / 解决办法”标题。 - -只有在以下情况，才使用显式标题： - -- 用户明确要求固定模板 -- 当前任务确实需要强结构化输出 -- 不加标题会让阅读顺序变模糊 - -默认情况下： - -- 优先直接输出两段内容 -- 段间保留空行 -- 需要增强分隔感时，可使用轻量分隔线 +## Read References When Needed -除非用户明确要求，否则不要新增第三段。 +- 对话语用判断：`references/conversation-pragmatics.md` +- 压缩和展开度：`references/compression-rules.md` +- 自然中文：`references/natural-chinese.md` +- CLI / app 排版分支：`references/environment-branch.md` +- 终端友好排版：`references/terminal-rendering.md` +- 路径、命令、产物展示：`references/path-rendering.md` ## Red Flags -出现以下任一情况时，先回退重写： - -- 出现“简单的说”“一句话总结”“说人话”“如果你愿意”等习惯性句式 -- 结尾出现“如果你要”“如果需要的话”“要不要我继续”之类邀约式变体 +- 中文像把英文分析逐句翻译过来 - 普通状态汇报里连续出现多行绝对路径 -- 解释部分比处理办法还长很多 - 回答读起来像报告、讲稿、教程，而不是直接沟通 -- 一屏内出现太多重复判断、重复转述、重复限定词 -- 句子读起来像英文语序压成中文，抽象词太多，动作和对象太远 -- 当前明明是 CLI，却仍然输出成普通聊天界面的密集排版 +- 为了凑结构，输出用户不需要的背景、原理或建议 +- 迎合式确认制造虚假共识 +- 漂亮总结掩盖任务没有实际推进 +- 为了避开某个词，反而把中文写得不自然 +- 结尾用空泛邀约把下一步责任推回给用户 diff --git a/skills/BetterGPT/BetterLanguage/references/banned-phrases.md b/skills/BetterGPT/BetterLanguage/references/banned-phrases.md deleted file mode 100644 index 4a926a2..0000000 --- a/skills/BetterGPT/BetterLanguage/references/banned-phrases.md +++ /dev/null @@ -1,39 +0,0 @@ -# Banned Phrases - -以下词句默认禁止出现在输出中。 - -## 明确禁用 - -- 砍一刀 -- 收口 -- 简单的说 -- 痛点 -- 一句话总结 -- 如果你愿意 -- 如果你要 -- 如果需要的话 -- 如果需要我可以 -- 要不要我继续 -- 需要的话我可以 -- 我也可以继续帮你 -- 你也可以让我 -- 不靠猜 -- 说人话 - -## 同类表达也应避免 - -- 说白了 -- 本质上 -- 核心在于 -- 直接一点讲 -- 换句话说 -- 其实你这里 -- 当然可以 -- 这是一个很好的问题 -- 让我们一步一步来看 - -## 处理原则 - -- 如果一句话带有明显“网络口癖”“AI 助手模板腔”“互联网黑话”味道，默认删掉或改写。 -- 如果一个词本身不是错误，但会把语气带向油腻、表演、说教，也应避免。 -- 优先改成普通、自然、克制的中文。 diff --git a/skills/BetterGPT/BetterLanguage/references/compression-rules.md b/skills/BetterGPT/BetterLanguage/references/compression-rules.md index 3d7752f..a0229e1 100644 --- a/skills/BetterGPT/BetterLanguage/references/compression-rules.md +++ b/skills/BetterGPT/BetterLanguage/references/compression-rules.md @@ -1,51 +1,34 @@ # Compression Rules -## Core Goal +Deliver the result first, then only the evidence, action, or risk the user needs. -让用户按从上到下的阅读顺序，一眼看懂原因，一眼看懂怎么处理。 +## Keep -## Default Compression Rules +- Result before background. +- One short paragraph per job. +- Evidence only when it supports the result. +- Actions only when they were done or are required next. +- Risk only when something is truly unverified, blocked, external, or behaviorally risky. -- 默认只保留结论相关信息，不自动补背景知识 -- 默认每段只承载一个职责 -- 默认每段 2 到 4 句即可，能更短则更短 -- 默认每个主段落可以拆成 1 到 3 个短句块，避免一整坨 -- 默认优先短句，减少并列修饰和重复限定 -- 默认删除礼貌铺垫、任务复述、风险表演、空泛形容词 -- 默认把大段解释拆成几块可扫读的小段，而不是压成一整块密文 -- 默认保留两段结构，但不强制显式打印段落标题 +## Remove -## Reason Analysis Rules +- Task restatement. +- Polite prefaces. +- Repeated conclusions. +- Generic caveats. +- Full reasoning translated into Chinese. +- Extra suggestions that do not follow from the current task. +- Fixed two-section or report-style templates for small answers. -- 只解释“为什么会这样” -- 不展开到历史、类比、外延讨论 -- 不把原因分析写成教学文 -- 先给判断，再补最必要的支撑 +## Structure -## Solution Rules - -- 只写能直接执行的动作 -- 优先写顺序明确、对象明确、结果明确的动作 -- 不追加无关建议 -- 不把“未来也许可以做什么”写成当前主方案 -- 必要时按从上到下的执行顺序分成两个短句块 - -## Section Rendering Rules - -- 默认两段直接输出，不强制写“原因分析 / 解决办法” -- 如果没有标题也足够清楚，就不要额外加标题 -- 如果需要增强段落边界，可以在两段之间加入轻量分隔 -- 只有用户明确要求模板化或当前内容确实容易混淆时，才输出显式标题 +Use no heading for small answers. Use short headings only when the answer has multiple distinct parts, such as result, verification, and risk. ## Final Check -交付前快速检查： +Before final delivery: -1. 两段之外还有没有第三段 -2. 有没有重复表达同一个判断 -3. 有没有口癖、黑话、模板腔 -4. 用户能否在很短时间内扫完并立刻行动 -5. 每个主段落是不是已经通过换行降低阅读压力 -6. 标题是不是已经过重，导致读起来像表单或报告 -7. 最后一句删掉后，答案是否仍然完整；如果是，删掉它 -8. 结尾是否变成了把用户往下一轮对话推的邀约句；如果是，改成直接收束 +1. Can the user see the result immediately? +2. Is any sentence only explaining your thinking process? +3. Does deleting the last sentence make the answer better? +4. Does the final sentence add useful state, evidence, action, risk, or a concrete question? diff --git a/skills/BetterGPT/BetterLanguage/references/conversation-pragmatics.md b/skills/BetterGPT/BetterLanguage/references/conversation-pragmatics.md new file mode 100644 index 0000000..84762d6 --- /dev/null +++ b/skills/BetterGPT/BetterLanguage/references/conversation-pragmatics.md @@ -0,0 +1,32 @@ +# Conversation Pragmatics + +Do not ban words categorically. Judge each phrase by whether it helps the work move forward. + +## Goal + +The answer should make the task clearer, more executable, or better prepared for the next useful turn. + +## Avoid + +- flattery or agreement that replaces judgment +- filler that delays the result +- fake closure that makes unfinished work sound finished +- empty invitations that push responsibility back to the user +- performative simplification that talks down to the user +- template summaries that add no new information + +## Allow + +Use natural Chinese when it is precise and context-appropriate. A phrase is acceptable if it carries real meaning, names the state accurately, or helps the user act. + +Do not rewrite a good sentence only because one word could sound informal in another context. + +## Interaction Rule + +If the next step is clear, state it or do it. If a missing preference changes the plan, ask one concrete question. If no useful next step remains, stop cleanly. + +## Final Check + +- Did this answer advance the work? +- Did it replace judgment with a slogan? +- Did it ask a real question or just invite another turn? diff --git a/skills/BetterGPT/BetterLanguage/references/environment-branch.md b/skills/BetterGPT/BetterLanguage/references/environment-branch.md index ec91899..060f07d 100644 --- a/skills/BetterGPT/BetterLanguage/references/environment-branch.md +++ b/skills/BetterGPT/BetterLanguage/references/environment-branch.md @@ -1,37 +1,25 @@ # Environment Branch -## Core Goal +Choose the visible format from the surface. The content rules stay the same: result first, concise Chinese delivery, preserved technical tokens. -先判断当前回答落在哪种展示面，再决定排版方式。 +## Terminal Or CLI -## Default Decision +Use the terminal style when the task centers on: -- 普通 app 聊天界面 - → 用 `BetterLanguage` 默认轻量排版 -- CLI / terminal / shell / 终端对话 - → 用 `BetterLanguage` 内容规则 + 终端友好排版 +- `cwd`, `shell`, commands, logs, errors, scripts, paths, or code review output +- plain-text scanability +- command results the user may copy or audit -## Strong Signals For CLI +Prefer short groups, short lines, compact lists, and literal commands/logs. -- 当前上下文里明确出现 `cwd`、`shell`、命令输出、终端日志 -- 用户明确说“终端里看”“CLI 输出”“命令行里阅读” -- 当前任务主要围绕命令、路径、报错、脚本、代码审查输出展开 -- 当前界面明显更依赖纯文本阅读，而不是富文本卡片或图像 +## App Or Chat -## Strong Signals For App +Use normal concise prose when the task is explanation, planning, product discussion, or general conversation. -- 当前界面支持富文本、图片、按钮、directive 或更强的图形化能力 -- 用户正在进行普通聊天，而不是终端导向的任务对话 -- 当前任务重点是解释、规划、产品讨论，而不是终端内操作 +## Fallback -## Fallback Rule +If unclear, use normal `BetterLanguage`. Do not add heavy terminal formatting just because technical terms appear. -如果不能明确判断，就默认走普通 `BetterLanguage`，不要误加过重的终端排版。 +## Boundary -## Important Boundary - -环境分支只改变排版，不改变核心内容规则： - -- 仍然保留两大段 -- 仍然压缩展开度 -- 仍然禁用口癖和翻译腔 +The branch changes presentation only. It does not restore fixed templates, long reasoning, or translated code/log/path text. diff --git a/skills/BetterGPT/BetterLanguage/references/natural-chinese.md b/skills/BetterGPT/BetterLanguage/references/natural-chinese.md index 3bc4ddf..f66d681 100644 --- a/skills/BetterGPT/BetterLanguage/references/natural-chinese.md +++ b/skills/BetterGPT/BetterLanguage/references/natural-chinese.md @@ -1,46 +1,38 @@ -# Natural Chinese Rules +# Natural Chinese -## Core Goal +Think through technical work in English when useful. Deliver only the necessary result in natural Chinese. -把“像英文逻辑翻成中文”的句子，改成自然、直接、顺着中文阅读习惯的表达。 +## Keep Literal -## What Usually Feels Translated +Do not translate: -- 句子重心太靠后 -- 抽象名词太多，动作太少 -- 连接词太硬，像在拼接论证结构 -- 一个句子里塞太多限定条件 -- 明明可以直接说，却先绕一层抽象判断 +- code +- commands +- logs +- file paths +- config keys +- API names +- model names +- product names -## Default Rewriting Rules +Add a short Chinese gloss only when an English term is necessary but may be unclear. -- 优先写“对象 + 动作 + 结果”，少写抽象概念串联 -- 优先直接说结论，少写“这意味着”“这通常表明”“这会导致” -- 优先用短句推进，少用一长句挂很多从句 -- 优先把动作写清，而不是把状态写得很抽象 -- 优先像正常中文对话，少像报告翻译稿 +## Rewrite Direction -## Expressions To Avoid +- Prefer object + action + result. +- Use short direct sentences. +- Say the decision before the explanation. +- Convert abstract reasoning into concrete outcome, evidence, action, or risk. +- Omit the English reasoning path unless the user asks for it. -- 这通常会表现为 -- 这意味着 -- 这本质上说明 -- 从这个角度来说 -- 在这种语境下 -- 其核心问题在于 -- 更准确地说 +## Avoid -## Preferred Direction - -- 把“抽象判断”改成“直接判断” -- 把“概念说明”改成“具体说法” -- 把“长连接句”改成“两个短句” -- 把“翻译腔结构”改成“中文顺句” +- translation-like sentence order +- long chains of abstract nouns +- heavy connectors such as "this means" or "from this perspective" +- meta explanations about how the answer is structured +- template openings, flattery, and empty invitations that do not advance the work ## Final Check -交付前快速检查： - -1. 这句话像不像正常中文会这样说 -2. 去掉抽象连接词后，意思会不会更清楚 -3. 能不能把一个长句拆成两个更自然的短句 +The final answer should read like concise Chinese written for the user, not an English analysis translated line by line. diff --git a/skills/BetterGPT/BetterLanguage/references/path-rendering.md b/skills/BetterGPT/BetterLanguage/references/path-rendering.md index 739e048..27d504c 100644 --- a/skills/BetterGPT/BetterLanguage/references/path-rendering.md +++ b/skills/BetterGPT/BetterLanguage/references/path-rendering.md @@ -1,98 +1,49 @@ # Path Rendering -## Goal +Use the shortest path that still lets the user identify the file. -让文件、命令、生成产物的展示更短、更自然、更适合对话阅读。 +## Priority -## Default Rule +1. File name +2. Project-relative path +3. Absolute path -默认按这个优先级展示路径： +Prefer file names or relative paths in ordinary summaries. Use absolute paths only when required by platform rules, explicit user request, ambiguity, multi-workspace context, or precise evidence. -1. 文件名 -2. 项目相对路径 -3. 绝对路径 +## File Names -普通汇报里，优先使用前两种。 - -## Override Rule - -如果当前平台或上层规则明确要求： - -- 必须输出绝对路径 -- 必须给出精确文件证据 -- 当前界面会把相对路径变成不可点击或不可定位信息 - -则以上默认优先级可以被覆盖，直接使用绝对路径。 - -## When To Use File Name Only - -以下场景优先只显示文件名： - -- 已生成哪些文件 -- 已修改哪些文件 -- 已发现哪些产物 -- 同一目录下文件名不会歧义 - -例如： +Use file names when the directory is obvious and names are unique: ```text -已生成： -- index.md -- journal-1.md +Updated: +- SKILL.md +- routing.md ``` -## When To Use Relative Path - -以下场景优先显示项目相对路径： - -- 需要让用户知道文件位于哪个模块或目录 -- 只写文件名可能歧义 -- 当前任务和目录结构强相关 +## Relative Paths -例如： +Use relative paths when module location matters or file names are ambiguous: ```text -已生成： -- .trellis/workspace/Administrator/index.md -- .trellis/workspace/Administrator/journal-1.md +Updated: +- BetterLanguage/references/path-rendering.md +- BetterSubagents/references/agent-registry.md ``` -## When Absolute Path Is Allowed +## Commands And Logs -只有以下情况，才显示绝对路径： +Keep commands, log text, config keys, API names, and product names literal. Do not translate them. -- 用户明确要求完整路径 -- 正在排查路径冲突 -- 需要做精确证据引用 -- 多个工作区或多个同名文件会导致歧义 -- 当前任务本身就是定位磁盘真实位置 - -## Command Rendering - -命令优先原样保留，但不要为了配合命令，额外重复输出一整段绝对路径。 - -例如： +Prefer: ```text -`python .trellis/scripts/task.py list` 可正常执行，返回 0 task(s)。 +`python .trellis/scripts/task.py list` returned `0 task(s)`. ``` -## Reporting Style - -推荐写法： - -```text -已生成： -- index.md -- journal-1.md - -`python .trellis/scripts/task.py list` 可正常执行，返回 0 task(s)。 -``` +Avoid repeating a full absolute path beside a command unless the path itself is the issue. -不要写成： +## Final Check -```text -已生成 -C:\Users\Administrator\Desktop\Make-GPT-Great-Again\.trellis\workspace\Administrator\index.md -C:\Users\Administrator\Desktop\Make-GPT-Great-Again\.trellis\workspace\Administrator\journal-1.md -``` +- Can the user find the file? +- Did a path become longer than needed? +- Did any command, key, log, or product name get translated? diff --git a/skills/BetterGPT/BetterLanguage/references/terminal-rendering.md b/skills/BetterGPT/BetterLanguage/references/terminal-rendering.md index 0205f6b..f982cb6 100644 --- a/skills/BetterGPT/BetterLanguage/references/terminal-rendering.md +++ b/skills/BetterGPT/BetterLanguage/references/terminal-rendering.md @@ -1,35 +1,23 @@ # Terminal Rendering -## Core Goal +When the user is reading in a CLI or terminal, optimize for fast scanning. -当当前展示面是 CLI 或终端时，让回答更容易扫读，不要挤成普通聊天界面的密文。 +## Use -## Keep +- Short paragraphs. +- Small lists for steps or checked items. +- Brief headings only when they help. +- Literal commands, logs, paths, config keys, API names, and product names. +- File names or relative paths unless absolute paths are needed. -- 继续保留 `原因分析 / 解决办法` 两大段 -- 继续保留轻换行 -- 继续保留自然中文和低展开度 +## Avoid -## Add In CLI +- Dense prose blocks. +- Long single-line explanations. +- Wide tables. +- Full absolute paths unless they are needed. +- Fixed templates such as "cause / solution" when the answer is smaller than that. -- 用简短分组标题，不用 Markdown 多级标题 -- 每个短句块尽量短，减少横向拖长 -- 段与段之间留出明确空行 -- 多步骤内容优先用短列表 -- 路径优先写文件名、相对路径、核心定位，不默认铺完整绝对路径 +## Check -## Avoid In CLI - -- 大段连续文本 -- 超长单句 -- 过宽表格 -- 不必要的完整绝对路径 -- 只有在富文本界面里才容易读的排版方式 - -## Final Check - -交付前快速检查： - -1. 在终端宽度下，是否一眼能扫到两个主段 -2. 有没有哪一块又重新挤成一整坨 -3. 有没有因为排版过重，反而压过内容本身 +The result should be visible in the first few lines, and no technical token should be translated. diff --git a/skills/BetterGPT/BetterSubagents/SKILL.md b/skills/BetterGPT/BetterSubagents/SKILL.md index 10b56d2..67e0e2e 100644 --- a/skills/BetterGPT/BetterSubagents/SKILL.md +++ b/skills/BetterGPT/BetterSubagents/SKILL.md @@ -1,6 +1,6 @@ --- name: better-subagents -description: Use when the task involves subagent selection, delegation strategy, parallel execution, wait and timeout handling, fallback takeover, or how to correctly use the project's local agents together with repository skills and MCP tools. Especially use when the user asks how to orchestrate explorer, worker, reviewer, docs-researcher, code-mapper, frontend-developer, browser-debugger, refactoring-specialist, or other local subagents, or when the main agent needs stronger delegation guardrails. +description: Use for Codex subagent orchestration across callable default, explorer, docs_researcher, reviewer, worker. Map old/framework labels including code-mapper, frontend-developer, browser-debugger, trellis-implement, trellis-check; respect current depth/concurrency limits. --- # Better Subagents @@ -9,266 +9,84 @@ description: Use when the task involves subagent selection, delegation strategy, 这是主代理的 subagent 调度护栏 skill。 -它不负责重复每个 subagent 的完整说明书，而是负责三件事： +它只负责三件事： -1. 识别当前任务是否值得派发 -2. 选择最合适的 subagent 类型 -3. 约束主代理如何等待、介入、回收、接管 +1. 判断是否值得派发 +2. 选择当前可调用的 agent 类型 +3. 约束等待、纠偏、回收和主代理接管 ## Trigger Signals -当请求或上下文出现以下信号时，优先使用本 skill： - - 用户提到 subagent、agent、子代理、派发、委派、并行、编排、调度 -- 用户在问 `explorer`、`worker`、`code-mapper`、`reviewer`、`docs-researcher` -- 用户在问“这个任务该派给谁”“什么时候并行”“什么时候主代理自己做” -- 当前任务已经涉及多个独立子问题，适合拆成多个子代理并行 -- 当前任务出现等待超时、子代理卡住、返回不完整、写集冲突 +- 用户在问 `default`、`explorer`、`docs_researcher`、`reviewer`、`worker` +- 用户在问旧能力标签：`code-mapper`、`search-specialist`、`frontend-developer`、`browser-debugger`、`refactoring-specialist` +- 用户在问外部框架 agent 标签：`trellis-implement`、`trellis-check`、`trellis-research` +- 当前任务有多个独立子问题，适合并行 +- 子代理等待超时、跑偏、返回不完整或写集冲突 ## Core Rule -先判断是否真的值得派发，再判断派给谁： - -1. 如果当前任务是立即阻塞主路径的本地工作 - → 主代理先自己做，不急着派发 -2. 如果当前任务可以拆成独立、明确、边界清晰的子任务 - → 再派发给合适 subagent -3. 如果当前任务边界不清、写集冲突、依赖关系太强 - → 不并行，主代理串行接管 - -## Boundary First Rule - -主代理在派发前，先把子任务压成固定 6 段，不允许裸派发： - -1. 任务类型：搜索 / 路径梳理 / 文档核验 / 风险审查 / 前端实现 / 浏览器复现 / 低风险重构 / 通用实现 -2. 目标：这次子任务到底要解决什么 -3. 边界：只读还是可写；允许哪些文件；禁止碰哪些模块 -4. 输出：结论 / 文件列表 / patch / 风险点 / 验证结果 -5. 约束：命中的 skill、`.trellis/spec/*`、MCP 分工 -6. 退出条件：边界不清、需要改派、卡在权限或依赖时必须回交主代理 - -如果以上 6 段有两段以上说不清，就不要派发。 - -## Agent Registry - -当前工作区默认可用的本地 subagent 分组如下： - -- 调查型 - → `explorer`、`code-mapper`、`search-specialist` -- 审查 / 核验型 - → `reviewer`、`docs-researcher` -- 实现型 - → `worker`、`frontend-developer`、`refactoring-specialist` -- 浏览器取证型 - → `browser-debugger` - -快速映射原则： - -- 代码路径、调用链、owner 边界 - → `code-mapper` -- 快速高信号搜索 - → `search-specialist` -- 纯只读取证、配置核对、行为确认 - → `explorer` -- 风险审查、回归、缺测试 - → `reviewer` -- 官方文档、版本、API 语义核验 - → `docs-researcher` -- 前端实现、页面修复 - → `frontend-developer` -- 低风险结构重构 - → `refactoring-specialist` -- 浏览器复现、前端证据收集 - → `browser-debugger` -- 没有更合适专用 agent 时 - → `worker` 作为实现兜底 - -## Preferred Routing Chains - -为减少重叠，默认按以下优先链判断： - -- 调用链、ownership、主路径梳理 - → `code-mapper` 优先，`explorer` 仅只读兜底 -- 官方文档、默认值、版本差异、API 语义 - → `docs-researcher` 优先，`search-specialist` 不替代文档核验 -- 前端交互异常且需要复现、抓证据、看浏览器行为 - → `browser-debugger` 优先，`frontend-developer` 不先抢 -- 前端页面实现、组件修复、状态与 UI 调整 - → `frontend-developer` 优先，`worker` 仅实现兜底 -- 低风险结构重构、职责拆分、边界收敛 - → `refactoring-specialist` 优先，`worker` 不默认承接 -- 一般外部资料预筛、找入口、快速缩小范围 - → `search-specialist` 优先，但不承担文档语义核验和完整调用链梳理 - -## Default Working Rules - -1. 主代理先识别当前任务的关键路径，急迫阻塞项优先本地处理。 -2. 只把独立、边界清晰、对主任务有实质推进的子任务派发出去。 -3. 读型任务优先派给只读 agent；写型任务优先派给实现型 agent。 -4. 多个写型子代理只能在写集不冲突时并行。 -5. 派发时必须明确： - - 目标 - - 边界 - - 预期输出 - - 是否允许修改文件 - - 是否需要验证 -6. 如果子任务明显落在某个工作区 skill 的领域内，主代理必须在派发说明中显式带上对应 skill 约束。 -7. 如果仓库存在 `.trellis/spec/` 且当前任务能落到对应 spec，主代理必须在派发说明中写明优先参考的 spec 路径。 -8. 如果子任务需要外部搜索、文档核验或代码定位，主代理必须在派发说明中写明优先按工作区 MCP 分工使用工具： - - 外部搜索 → `grok-search` - - 代码搜索 → `ace-tool` - - 第三方文档 → `Context7` - - 已知页面的精确核对 / 官方原文逐页阅读 → 系统 `web` -9. `explorer` / `worker` 是兜底型 agent，不应默认抢占专用 agent 的角色。 - -补充说明： - -- `grok-search` 适合外部资料预筛、多来源归纳、入口发现 -- 如果任务已经给出明确 URL，或要求精确引用、逐页确认、原文核对 - → 不要只停留在 `grok-search` 聚合结果，应优先转到系统 `web` - -## Exclusion Rules +先判断是否值得派发，再判断派给谁。 -为了避免“规范地模糊派发”，主代理还要先判以下排他条件： +- 立即阻塞主路径的本地工作，主代理先做 +- 独立、明确、边界清晰的子任务，才派发 +- 边界不清、写集冲突、依赖太强时，不并行 +- 遵守当前会话和 `~/.codex/config.toml` 的 agent 深度 / 并发限制；当前 `max_depth = 1` 时，子代理不再派生子代理 +- 子代理、reviewer 或黑盒测试暴露当前目标内的明确小修正时，主代理吸收证据后直接修并验证，不把清楚修正退回成“下一轮” +- 实际派发前必须说明目标、边界、输出、验证、skill / spec / tool 约束和退出条件 -- 需要官方文档事实 - → 不先派 `search-specialist` -- 需要完整调用链 / 边界图 - → 不先派 `explorer` -- 需要浏览器重现与证据 - → 不先派 `frontend-developer` -- 需要前端明确实现 - → 不先派 `browser-debugger` -- 需要低风险结构重构 - → 不先派 `worker` +## Callable Agent Map -只有专用 agent 明确不适配、边界过窄或只是极小补丁时，才允许回退到兜底 agent。 +只把当前 `spawn_agent` 暴露的类型写成 `agent_type`： -## Skill Binding Rules +- `default`：轻量只读取证、摘要、入口确认 +- `explorer`：代码路径、调用链、配置核对、实现入口定位 +- `docs_researcher`：OpenAI / Codex 官方文档和 API 语义核验 +- `reviewer`：正确性、回归、安全、缺测试风险审查 +- `worker`：主代理已明确写集后的本地实现 -常见任务与必须绑定的工作区 skill 如下： +旧能力标签只能作为任务意图： -- 前端页面实现、UI 修复、页面成品化 - → 必带 `BetterFrontend` -- 前后端边界、模块拆分、职责治理、低风险重构 - → 必带 `BetterVibe` -- Trellis task、spec、workflow、record-session、hooks - → 必带 `BetterTrellis` +- `code-mapper` → `explorer` +- `search-specialist` → `explorer`，轻量非代码任务可用 `default` +- `frontend-developer` → `worker` + `BetterFrontend` +- `refactoring-specialist` → `worker` + `BetterVibe` +- `browser-debugger` → 主代理本地复现；只读代码或日志取证可拆给 `explorer` -如果一个子任务同时命中多个领域，允许同时携带多个 skill 约束，但不要遗漏主领域。 +外部框架 agent 标签也只能作为任务意图： -## Wait And Intervention Rules +- `trellis-implement` → `worker` + `BetterTrellis`，涉及 UI 时再加 `BetterFrontend` +- `trellis-check` → `reviewer` + `BetterTrellis` +- `trellis-research` → `explorer` 或 `docs_researcher`，取决于目标是本地代码证据还是官方文档核验 -1. 对子代理结果的等待，默认使用 `wait_agent` 语义，不用笼统的“wait”替代。 -2. 只有当主线程下一步真的被该子代理结果阻塞时，才应 `wait_agent`。 -3. 如果主线程还有可做的非重叠工作 - → 先继续本地推进，不要一派发就原地等待。 -4. 默认等待策略是 **最多 3 轮，每轮 120 秒**；这是一组建议默认值，不是“无限等待”。 -5. 第 1 轮 `wait_agent` 超时不等于任务失败，先判断是否只是仍在运行。 -6. 如果第 2 轮、第 3 轮后仍无有效进展、或返回内容明显偏题 - → 主代理应主动检查状态并介入。 -7. 介入优先级： - - 先补充更清晰的边界或目标 - - 再判断是否需要 `send_input` - - 再判断是否需要中断当前任务并重派 - - 再判断是否关闭子代理并本地接管 -8. 如果子代理卡在外部依赖、权限、环境异常 - → 主代理不要被动一直等待，应直接切回主线程处理阻塞点。 -9. 如果多个子代理结果互相冲突 - → 主代理负责回读证据、裁决冲突、统一结论 +## Binding Rules -## Steer Rules +- 前端实现、UI 修复、页面成品化：派 `worker` 时必带 `BetterFrontend` +- 模块拆分、职责治理、低风险重构：派 `worker` 时必带 `BetterVibe` +- Trellis workflow、spec、task、record-session、hooks：派发说明必带 `BetterTrellis` +- 文档核验优先 `docs_researcher`，不要用 `default` / `explorer` 代替 +- 风险审查优先 `reviewer`，不要让 `worker` 自审 -`send_input` 不是“催一下”的工具，而是纠偏工具。 +## Wait And Cleanup -仅在以下情况才使用： - -- 需要补充新的边界、目标或约束 -- 发现子代理明显跑偏 -- 有新证据会改变原任务方向 -- 需要 `interrupt=true` 立即改道 - -以下情况不要随意追加消息： - -- 子代理仍在合理执行窗口内 -- 主代理没有新增事实、没有新增边界、没有新的纠偏信息 -- 只是想确认“你还在吗”或机械催促进度 - -## Close And Cleanup Rules - -子代理生命周期默认遵循“完成即回收”： - -1. 子代理一旦到达 final status，且结果已被主代理读取与整合 - → 应立即 `close_agent` -2. 不因为“后面可能还会用到”而默认保留已完成子代理 -3. 已完成但长期不关闭，会带来： - - 槽位 / 线程占用 - - 误复用 - - 上下文污染 - - 主线程调度噪音 -4. `explorer` / `worker` 这类兜底型 agent 更不应长时间挂起 - -## Reuse Rules - -复用子代理是例外，不是默认。 - -只有以下情况才允许继续复用原 agent： - -- 下一步问题与上一任务高度连续 -- 任务边界没有实质变化 -- 复用原上下文明显比新开 agent 更稳 - -以下情况应优先新开 agent，而不是复用： - -- 任务类型变了 -- skill 绑定变了 -- MCP 分工变了 -- 从调查切到实现 -- 从复现切到修复 -- 从文档核验切到代码改动 -- 主线程目标已切换 - -## Thread Budget Rules - -`agents.max_threads` 代表并发打开的 agent 线程上限，不是摆设。 - -因此主代理应遵循： - -1. 开多少，就要有计划地回收多少 -2. 完成态 agent 不应长期占用线程预算 -3. 不要靠保留旧 agent 充当“缓存池” -4. 不要用递归派发或长期挂起来掩盖主代理边界不清的问题 +- 只有主线程下一步真的被阻塞时，才 `wait_agent` +- 主线程还有非重叠工作时，先继续推进 +- `send_message` / `followup_task` 只用于补边界、纠偏或改道 +- 子代理完成且结果已吸收后，立即 `close_agent` +- 多个结果冲突时，主代理回读证据并裁决 ## Read References When Needed -- 需要看当前本地 subagent 清单与角色映射时，读 `references/agent-registry.md` -- 需要看具体派发、等待、接管规则时，读 `references/dispatch-rules.md` - -## Hard Constraints - -- 不把所有任务都机械地派给子代理 -- 不把 urgent blocking work 丢给子代理后原地空等 -- 不在写集冲突时并行派发多个实现型 agent -- 不让专用 agent 与 `explorer` / `worker` 长期职责重叠不清 -- 不重复抄写各个 agent TOML 里的完整说明书 -- 不把“等待超时”直接当成“子代理失败” -- 不在子代理明显卡住时持续被动等待 -- 不在实际派发时省略 skill / spec / MCP 约束 -- 不让 `explorer` / `worker` 吞掉本应交给专用 agent 的前端、文档核验、浏览器调试或结构重构任务 -- 不用“你去看一下这个问题”这类模糊指令直接派发 -- 不把搜索、梳理、实现、重构、浏览器复现混成一个子任务 -- 不把对子代理的等待写成普通 `wait` 语义，子代理等待要按 `wait_agent` 处理 -- 不把 `send_input` 当成催进度按钮 -- 不让已完成子代理长期占据后台线程或槽位 -- 不在任务边界已经改变后继续复用旧 agent +- 当前 agent 清单与旧标签映射：`references/agent-registry.md` +- 派发模板、等待、接管细则：`references/dispatch-rules.md` ## Red Flags -- 主代理刚拿到任务就先派发，自己不做关键路径判断 -- 明明有专用 agent，却总是只用 `explorer` / `worker` +- 把旧能力标签误写成当前可派发 agent +- 一拿到任务就先派发，主代理不做关键路径判断 - 派发指令没有目标、边界、输出要求 -- 多个实现型 agent 修改同一文件或同一模块 -- 子代理连续超时后，主代理仍然不介入 -- 子代理返回结论互相冲突，但主代理没有做证据裁决 -- 子代理已经完成，但主代理长时间不关闭 -- 主代理频繁给仍在工作中的子代理发送无效催促消息 +- 在 `max_depth = 1` 的会话中要求子代理继续派生子代理 +- 子代理已经暴露明确、低风险、同范围修正，主代理却只汇报建议不实施 +- 多个实现型 agent 修改同一文件或模块 +- 子代理完成后长期不关闭 +- 频繁给正常工作的子代理发送无效催促消息 diff --git a/skills/BetterGPT/BetterSubagents/references/agent-registry.md b/skills/BetterGPT/BetterSubagents/references/agent-registry.md index b0e6298..1b55495 100644 --- a/skills/BetterGPT/BetterSubagents/references/agent-registry.md +++ b/skills/BetterGPT/BetterSubagents/references/agent-registry.md @@ -1,51 +1,39 @@ # Agent Registry -当前工作区本地 `agents/` 目录中的主要 subagent： +Only use `agent_type` values that the current `spawn_agent` tool exposes. Old capability labels are task intents, not callable agent names. -## 调查型 +## Current Callable Types -- `explorer`：通用只读调查兜底 -- `code-mapper`：调用链、执行路径、ownership boundary -- `search-specialist`：高信号搜索与下一步入口发现 +- `default`: lightweight read-only evidence gathering or summary +- `explorer`: read-only codebase, config, path, and execution-flow investigation +- `docs_researcher`: read-only official documentation verification, especially OpenAI / Codex behavior +- `reviewer`: read-only correctness, regression, security, and missing-test review +- `worker`: implementation after the main agent has scoped files, boundaries, and success criteria -## 审查 / 核验型 +## Old Label Mapping -- `reviewer`：风险审查、回归、缺测试 -- `docs-researcher`：官方文档、版本、API 语义核验 +- `code-mapper` -> `explorer` +- `search-specialist` -> `explorer`, or `default` for light non-code prefiltering +- `frontend-developer` -> `worker` with `BetterFrontend` +- `refactoring-specialist` -> `worker` with `BetterVibe` +- `browser-debugger` -> main agent handles browser reproduction; split read-only code/log evidence to `explorer` -## 实现型 +## Framework Label Mapping -- `worker`：通用实现兜底 -- `frontend-developer`：前端实现与 UI 修复 -- `refactoring-specialist`：低风险结构重构 +Framework-provided labels are also intents, not callable names unless the current `spawn_agent` tool exposes them. -## 浏览器取证型 +- `trellis-implement` -> `worker` with `BetterTrellis`; add `BetterFrontend` for UI work +- `trellis-check` -> `reviewer` with `BetterTrellis` +- `trellis-research` -> `explorer` for local evidence, or `docs_researcher` for official docs -- `browser-debugger`：浏览器复现、UI 证据收集、客户端调试 +## Selection Rules -## 优先原则 +- Official docs -> `docs_researcher`. +- Risk review -> `reviewer`. +- Call-chain or repo mapping -> `explorer`. +- Small evidence summary -> `default`. +- Scoped implementation -> `worker`. -1. 有专用 agent 时，优先专用 agent -2. 没有专用 agent 时，再退回 `explorer` / `worker` -3. 读型任务优先只读 agent -4. 写型任务优先实现型 agent +Respect current runtime limits. If `agents.max_depth = 1`, only the main agent should spawn subagents; child agents should not be asked to spawn more children. -## 优先级链 - -- 调用链 / ownership / 主路径 - → `code-mapper` > `explorer` -- 官方文档 / 默认值 / API 语义 - → `docs-researcher` > `search-specialist` -- 浏览器复现 / 前端证据 - → `browser-debugger` > `frontend-developer` -- 前端明确实现 - → `frontend-developer` > `worker` -- 结构重构 / 职责拆分 - → `refactoring-specialist` > `worker` - -## 使用边界 - -- `explorer`：只读兜底，不负责完整调用链梳理、文档语义核验、浏览器复现和代码实施 -- `worker`：实现兜底，不负责替代前端专项和结构重构专项 -- `search-specialist`：负责找入口，不负责文档事实裁定和完整调用链图谱 -- `browser-debugger`：负责复现和证据，不负责默认接管前端实现 +Do not let a `worker` self-review important changes; use `reviewer` or main-agent verification. diff --git a/skills/BetterGPT/BetterSubagents/references/dispatch-rules.md b/skills/BetterGPT/BetterSubagents/references/dispatch-rules.md index 4818c09..26a9ece 100644 --- a/skills/BetterGPT/BetterSubagents/references/dispatch-rules.md +++ b/skills/BetterGPT/BetterSubagents/references/dispatch-rules.md @@ -1,160 +1,74 @@ # Dispatch Rules -## 1. 何时值得派发 - -只有满足以下条件之一时，才优先考虑派发： - -- 子任务独立，且不会阻塞主代理当前下一步 -- 可以并行推进多个互不依赖的问题 -- 需要专用能力，明显比通用 agent 更合适 - -以下情况优先主代理本地处理： - -- 当前下一步就依赖该结果 -- 边界不清，派发成本大于收益 -- 写集明显冲突 -- 只是一个很小的直接操作 - -## 2. 派给谁 - -- 代码定位 / 路径梳理 → `code-mapper` -- 搜索入口 / 预筛命中 → `search-specialist` -- 纯证据调查 → `explorer` -- 风险审查 → `reviewer` -- 文档核验 → `docs-researcher` -- 前端实现 → `frontend-developer` -- 浏览器复现 → `browser-debugger` -- 低风险重构 → `refactoring-specialist` -- 通用实现兜底 → `worker` - -### 2.1 优先级链 - -- 调用链、主路径、ownership boundary - → `code-mapper` > `explorer` -- 官方文档、默认值、版本差异、API 语义 - → `docs-researcher` > `search-specialist` -- 前端交互异常复现、浏览器证据 - → `browser-debugger` > `frontend-developer` -- 前端明确实现、组件修复、状态变更 - → `frontend-developer` > `worker` -- 低风险结构重构、职责拆分 - → `refactoring-specialist` > `worker` - -### 2.2 排他规则 - -- 文档核验任务，不先派 `search-specialist` -- 调用链梳理任务，不先派 `explorer` -- 浏览器复现任务，不先派 `frontend-developer` -- 前端明确实现任务，不先派 `browser-debugger` -- 结构重构任务，不先派 `worker` - -## 3. 派发内容最少要包含 - -- 任务类型 -- 子任务目标 -- 修改边界或只读边界 -- 预期输出 -- 是否需要验证 -- 需要使用的技能或工具约束 -- 需要优先参考的 spec / workflow / 目录路径（若存在） -- 退出条件 - -### 3.0 建议派发模板 +Use subagents only when delegation shortens the path or improves evidence quality. -```text -任务类型： -目标： -边界： -预期输出： -验证要求： -skill / spec / MCP 约束： -退出条件： -``` - -### 3.1 skill 绑定规则 - -- 前端页面实现、视觉成品化、UI 行为修复 - → `BetterFrontend` -- 前后端边界、服务拆分、低风险结构重构 - → `BetterVibe` -- Trellis workflow、spec、task、record-session、hooks - → `BetterTrellis` +## Dispatch When -如果一个子任务同时命中多个领域，派发说明里必须一起写明，不要只写一个泛化目标。 +- The subtask is independent and can run while the main agent continues. +- Several read-only investigations can run in parallel. +- The task needs a current callable type's narrow role: docs verification, repo exploration, risk review, or scoped implementation. -### 3.2 MCP 绑定规则 +Keep the work in the main agent when the next step depends on the answer, the boundary is unclear, the write set may conflict, or the task is small enough to do directly. -- 仓库代码定位、调用链、实现搜索 - → `ace-tool` -- 外部联网搜索、资料预筛 - → `grok-search` -- 第三方库 / SDK / API 文档核验 - → `Context7` -- 已知页面原文核对、逐页阅读、精确引用 - → 系统 `web` +## Callable Type Map -不要把 MCP 分工只留在主代理脑内，派发说明里要写给子代理。 +- Evidence summary -> `default` +- Code path, config, call-chain, repo map -> `explorer` +- Official OpenAI / Codex docs -> `docs_researcher` +- Bugs, regressions, security, missing tests -> `reviewer` +- Scoped implementation -> `worker` -补充： +Old labels map only to intent: -- `grok-search` 默认用于“先搜到入口、先拿到多来源摘要” -- 如果任务已经给出明确页面、要求精确出处、或需要逐页核对原文 - → 应切到系统 `web`，不要只停留在搜索聚合结果 +- `code-mapper` -> `explorer` +- `search-specialist` -> `explorer` or light `default` +- `frontend-developer` -> `worker` + `BetterFrontend` +- `refactoring-specialist` -> `worker` + `BetterVibe` +- `browser-debugger` -> main agent reproduction; read-only evidence may go to `explorer` -## 4. 等待与接管 +Framework labels also map only to intent unless currently exposed by `spawn_agent`: -- 对子代理结果的等待，使用 `wait_agent` -- 只有主线程下一步真的被阻塞时，才 `wait_agent` -- 如果主线程还有可做的非重叠工作，不要一派发就等待 -- 默认最多等待 3 轮，每轮 120 秒 -- 第 1 轮 `wait_agent` 超时：先检查是否仍在推进 -- 第 2 轮等待仍无进展：补充边界或目标，必要时 `send_input` -- 第 3 轮等待后仍卡住：中断 / 关闭并由主代理接管 -- 如果卡点是权限、环境、依赖、共享写集冲突 - → 不继续空等，直接回到主线程处理阻塞 +- `trellis-implement` -> `worker` + `BetterTrellis`; add `BetterFrontend` for UI work +- `trellis-check` -> `reviewer` + `BetterTrellis` +- `trellis-research` -> `explorer` for local evidence, or `docs_researcher` for official docs -### 4.1 纠偏与催促 +## Dispatch Prompt -- `send_input` 只用于补边界、纠偏、打断改道 -- 不用 `send_input` 做“你现在快点”“还没好吗”式催促 -- 没有新增信息时，不要频繁打扰正在正常工作的子代理 +Include only what the subagent needs: -### 4.2 完成后关闭 - -- 子代理一旦完成且结果已被主代理吸收 - → 立即 `close_agent` -- 不因为“也许稍后还会问一句”而默认保留 -- 已完成 agent 若无明确连续追问计划，应及时关闭 +```text +Task type: +Goal: +Boundary: +Expected output: +Verification: +Skill / tool constraints: +Exit condition: +``` -### 4.3 复用条件 +For `worker`, state the files or modules it may edit. For `explorer`, request concrete file/symbol/call-site evidence. For `docs_researcher`, require official sources. -只有以下情况可复用原 agent： +## Runtime Limits -- 后续问题与上一任务高度连续 -- 任务边界、skill 绑定、MCP 分工没有变化 -- 复用原上下文明显优于新开 agent +Respect current Codex agent limits from the active tool surface and config. If `agents.max_depth = 1`, keep orchestration in the main thread and do not ask subagents to spawn follow-on agents. Keep fan-out bounded by the current concurrent-thread limit and by review capacity. -以下情况优先新开 agent： +## Skill Binding -- 从调查转实现 -- 从复现转修复 -- 从文档核验转代码改动 -- 任务目标或边界已变化 +- UI implementation or visual polish -> `BetterFrontend` +- Boundary or layering refactor -> `BetterVibe` +- Trellis workflow, specs, tasks, hooks -> `BetterTrellis` -## 5. 主代理介入条件 +Name these bindings in the dispatch prompt when they apply. -- 子代理连续超时 -- 输出明显偏题 -- 写集冲突 -- 外部依赖阻塞 -- 多个结果冲突 -- 子代理明确报告“更适合其他专用 agent” -- 子代理已完成但仍长期挂在后台 +## Waiting And Takeover -## 6. MCP 使用原则 +- Use `wait_agent` only when the main thread is blocked. +- If useful non-overlapping work remains, continue locally before waiting. +- On timeout, check progress once; then send a clarifying boundary or goal if needed. +- Do not send empty "hurry up" messages. +- If a child result or validation exposes a clear in-scope, low-risk, verifiable fix, the main agent implements and verifies it in the current turn. +- After repeated timeout, wrong direction, write conflict, external blocker, or conflicting results, close or stop relying on the subagent and take over in the main thread. -如果子任务需要工具，默认按工作区分工： +## Cleanup -- 外部搜索 → `grok-search` -- 代码搜索 → `ace-tool` -- 第三方文档 → `Context7` +Close a completed agent after its result is absorbed. Reuse an agent only when the next question is tightly continuous and the boundary/tooling is unchanged. diff --git a/skills/BetterGPT/BetterTrellis/SKILL.md b/skills/BetterGPT/BetterTrellis/SKILL.md index 594d761..88cd86b 100644 --- a/skills/BetterGPT/BetterTrellis/SKILL.md +++ b/skills/BetterGPT/BetterTrellis/SKILL.md @@ -1,195 +1,99 @@ --- name: better-trellis -description: Use when working with Trellis in Codex, especially for soft integration, project initialization, workflow entry, spec and task organization, hooks, generated command structure, or reducing the need to remember Trellis commands manually. Use when the request mentions Trellis init, Codex integration, workflow, spec, task, workspace logs, hooks, update, onboarding, or agent command mapping. +description: Use for Trellis workflow in Codex, including project initialization, spec/task organization, hooks, workspace logs, and command mapping. Focus on stage detection and safe workflow entry; do not dump command lists by default. --- # Better Trellis ## Overview -这是 Trellis 的软接入 skill。 +这是 Trellis 的 Codex 软接入 skill。 -目标不是让模型把一大串命令背下来，而是把 Trellis 在 Codex 下的初始化、进入方式、日常工作流和目录职责整理成稳定入口。 +目标是让主代理判断当前 Trellis 阶段并选择入口，而不是把命令表丢给用户。 ## Trigger Signals -当请求或上下文出现以下信号时，优先使用本 skill： - - 用户提到 `Trellis` - 用户想在 Codex 里接入 Trellis -- 用户提到初始化、软接入、hooks、workflow、spec、task、workspace -- 用户不想记太多命令，希望按流程工作 -- 用户在问 `trellis init`、`trellis update`、`task.py`、`record-session` -- 用户要解释 Trellis 生成的目录和文件分别做什么 +- 用户提到初始化、workflow、spec、task、workspace、hooks +- 用户在问 `trellis init`、`trellis update`、`task.py`、`$start`、`continue`、`$finish-work`、`record-session` - 主入口已经判断当前任务应进入 Trellis 模式 ## Core Rule -先区分“基础可用”与“Codex 自动接入完整”这两个层级，再决定后续动作： +先判断状态，再决定动作： -1. Trellis 基础可用 - → 可以继续按 Trellis 工作流回答与推进 -2. Codex 自动接入完整 - → 可以继续强调 hooks / session 注入 / 自动上下文 -3. Trellis 基础不可用 - → 再走初始化代操作流程 -4. 用户只是问概念或结构 - → 只解释，不执行 +- Trellis 基础可用：继续按 Trellis 工作流推进 +- Codex 接入文件完整：可说明 skills / agents / hooks 接入位齐全 +- Trellis 基础不可用：再走初始化代操作流程 +- 用户只是问概念或结构：只解释，不执行 -另外要单独区分： +明确区分： -- **hooks 接入位已生成** - → 说明 Trellis / Codex 预留了 hooks 相关文件或配置位 -- **hooks 当前平台已生效** - → 只有当前平台真的支持 hooks，且 `hooks.json` / hook 文件可用时，才算已生效 +- hooks 接入位已生成：存在配置位或文件 +- hooks runtime 已验证：当前平台真的支持并正在加载 hook -不要把“有 hooks 配置位”直接说成“当前 hooks 正在工作”。 +不要把“有 hooks 配置位”说成 runtime 已验证，也不要只因接入文件齐全就宣称 session injection 已生效。 ## Mode Activation -`BetterTrellis` 不负责决定“要不要切入 Trellis 模式”这件事本身；那是主入口的职责。 - -一旦主入口已把当前任务交给 `BetterTrellis`，这里默认按以下规则执行： +`BetterTrellis` 不决定是否进入 Trellis 模式；主入口负责这个判断。 -1. 用户显式提到 `Trellis`、`start`、`task.py`、`record-session`、`/trellis:*` - → 视为已明确进入 Trellis 模式，不再额外确认 -2. 用户没有显式提 Trellis，但主入口已确认当前任务要按 Trellis 工作流推进 - → 只在入口处确认一次 -3. 用户确认后，同一任务后续默认持续使用 Trellis 工作流，不重复追问 -4. 用户明确拒绝后，本轮回退到普通流程，不再强推 Trellis +进入后按阶段处理： -## Stage Detection +1. 确认项目能否使用 Trellis +2. 会话或上下文恢复：进入 `$start` / `start` +3. 开发中：围绕当前 `task / spec / context` 推进，必要时用 `continue` +4. 验收或检查：进入 `check` +5. 完工记录：进入 `$finish-work` / `finish-work` / `record-session` -进入 Trellis 模式后，优先判断当前处在哪个阶段，而不是先给命令表： +用户已明确提到 `Trellis`、`$start`、`start`、`continue`、`task.py`、`record-session` 或平台原生命令时，不再重复确认。 -1. 只是确认项目能不能用 - → 回答可用性 / 初始化状态 -2. 刚开始一个开发任务 - → 进入 `start / before-dev / task` -3. 已在开发中 - → 围绕当前 `task / spec / context` 推进 -4. 正在验收或收尾 - → 进入 `check / finish-work / record-session` +## Initialization Check -## Initialization First - -只要请求涉及“接入 Trellis”或“当前项目能不能开始用 Trellis”，默认先检查： +涉及“接入 Trellis”或“当前项目能不能用 Trellis”时，先检查： - `trellis` CLI 是否可用 - 当前项目根目录是否已有 `.trellis/` -- 是否已有基础接入物： - - `AGENTS.md` - - `.agents/skills/` -- 是否已有 Codex 自动接入物： - - `.codex/config.toml` - - `.codex/hooks/session-start.py` - - `.codex/hooks.json` - -还要额外判断当前平台： +- 是否有基础接入物：`AGENTS.md`、`.agents/skills/` +- 是否有 Codex 接入目录：`.codex/agents/`、`.codex/skills/`、`.codex/hooks/` +- 只有诊断 hooks 时，再细查 `.codex/hooks/session-start.py`、`.codex/hooks.json` 和全局 feature flag -- 如果当前是 **Windows 原生 Codex** - → 默认按“**hooks 当前平台不作为已生效能力**”处理 - → 这时 Trellis for Codex 主要依赖 `AGENTS.md`、skills、文档驱动 workflow，而不是把 SessionStart hook 当成当前已工作能力 - → 即使 `codex_hooks = true` 已开启，也不要直接推断 hooks 已在 Windows 上生效 +判定口径： -判定规则默认如下： +- 有 CLI + `.trellis/`：Trellis 基础可用 +- 有 `.trellis/` + 基础接入物但缺 `.codex/*`：Trellis 可用，但 Codex 接入文件不完整 +- `.codex/*` 也齐全：Trellis for Codex 接入文件完整 +- `.trellis/` 与基础接入物都明显缺失：尚未初始化 -1. 如果 `trellis` CLI 可用，且项目中已有 `.trellis/` - → 判定为 **Trellis 基础可用** -2. 如果同时还有 `AGENTS.md`、`.agents/skills/`，但缺少 `.codex/*` - → 仍然判定为 **Trellis 可用，但 Codex 自动接入不完整** -3. 如果 `.codex/config.toml`、`.codex/hooks/session-start.py`、`.codex/hooks.json` 也齐全 - → 判定为 **Trellis for Codex 自动接入完整** -4. 只有在 `.trellis/` 与基础接入物都明显缺失时 - → 才判定为 **尚未完成 Trellis 初始化** +Windows 原生 Codex 下，不把缺少 `.codex/*` 直接判成不可用；默认按文档驱动 workflow + skills 处理。 -Windows 原生 Codex 的特殊口径： +## Init Safety -- `.codex/hooks/session-start.py`、`.codex/hooks.json` 缺失 - → 不应直接判定“当前 Windows 项目不可用” -- 如果当前工作流本身依赖 `AGENTS.md` + skills + 文档驱动即可成立 - → 应判定为 **Trellis 可用，但 hooks 仅为未来兼容占位或未启用能力** -- 只有当用户明确要求“验证 hooks 当前是否真的生效”时，才单独把 hooks 作为当前平台能力核验项 +只有判定为尚未初始化时，才进入初始化代操作流程。 -不要把“缺少 `.codex/*`”直接等同于“当前项目不能使用 Trellis”。 - -只有在判定为“尚未完成 Trellis 初始化”时，才进入初始化代操作流程。 - -必须先明确告知用户将执行： +执行前必须先说明将运行： ```bash trellis init --codex -u ``` -并说明初始化后通常还需要： - -- 重新打开当前项目会话 -- 检查 `~/.codex/config.toml` 是否已启用： - -```toml -[features] -multi_agent = true -codex_hooks = true -``` - -只有在用户明确确认后，才进入实际初始化。 - -## Default Working Rules - -1. 不把 Trellis 当成一堆零散命令来回答。 -2. 优先回答“当前处于哪一阶段”。 -3. 已进入 Trellis 模式后，默认由模型自己判断应该使用哪个 Trellis 入口，不把命令选择压力丢给用户。 -4. 除了首次入口确认外，不反复问用户“要不要用哪个 Trellis 命令”。 -5. 先回答“当前是 Trellis 基础可用，还是 Codex 自动接入完整”，再决定是否需要初始化说明。 -6. 优先告诉用户当前阶段和下一步动作，而不是一次性倾倒全部命令。 -7. 已初始化项目，优先引导到 `spec / task / workflow / check / record-session` 这几条主线。 -8. 解释结构时，要明确区分： - - `.trellis/` 是工作流与项目知识层 - - `AGENTS.md` 是 Codex 入口层 - - `.agents/skills/` 是共享 skill 层 - - `.codex/` 是 Codex 平台接入层 -9. 在 Windows 原生 Codex 下，默认强调 **文档驱动 workflow + skills**，不要把 hooks 当成当前必需已生效项。 -10. 需要解释 hooks 时，先说清“当前平台是否支持”，再说“配置位是否存在”。 - -## Recommended Flow - -在 Codex 场景下，默认按这条顺序理解和使用： - -1. 初始化项目：`trellis init --codex -u ` -2. 写或补 `.trellis/spec/` -3. 需要任务化时，用 `python .trellis/scripts/task.py ...` -4. 进入会话后，按 Trellis 工作流命令推进 -5. 完工后做检查与会话记录 +并提醒初始化后通常要重新打开项目会话、检查 Codex features。 -不要跳过初始化检查，就直接把后续命令堆给用户。 +未得到用户明确确认，不执行初始化。 ## Read References When Needed -- 需要处理初始化与代操作流程时，读 `references\init-flow.md` -- 需要给出官方常用命令时，读 `references\commands.md` -- 需要说明 Codex 下的工作流顺序时，读 `references\codex-workflow.md` -- 需要解释 Trellis 目录和 Codex 接入层职责时，读 `references\structure.md` - -## Hard Constraints - -- 不把 Trellis 回答成“只是另一个 prompts 文件系统” -- 不混淆 `.trellis/`、`AGENTS.md`、`.agents/skills/`、`.codex/` 的职责 -- 不在未确认时擅自执行初始化 -- 不把所有命令一次性展开给用户制造负担 -- 不在已初始化项目里重复指导完整初始化 -- 不把“缺少 `.codex/*`”直接说成“当前项目不能使用 Trellis” -- 不把“基础可用”和“Codex 自动接入完整”混成一个状态 -- 不把“hooks 接入位存在”与“hooks 当前平台已生效”混成一个状态 -- 不在 Windows 原生 Codex 下把 `codex_hooks = true` 直接解释成 SessionStart 已运行 -- 不要求用户自己记忆 Trellis 指令名后再继续对话 -- 不把“该用哪个 Trellis 命令”当成用户必须先做出的决定 -- 用户一旦已确认进入 Trellis 模式，后续默认由模型自动选阶段入口 +- 初始化与代操作：`references/init-flow.md` +- 常用命令：`references/commands.md` +- Codex 工作流顺序：`references/codex-workflow.md` +- 目录职责：`references/structure.md` ## Red Flags -- 一上来就罗列大量命令，没有先判断是否已初始化 +- 一上来罗列大量命令，没有先判断阶段 - 把 Trellis 说成只靠 `AGENTS.md` 生效 -- 把 Codex hooks 是否启用这件事漏掉 -- 任务明明适合 `task.py`，却仍然让用户手工维持上下文 -- 已经有 Trellis 结构，却还按“裸 Codex”方式组织流程 -- 已经进入 Trellis 模式，却还反复问用户“要不要用 start / task.py / finish-work” +- 混淆 `.trellis/`、`AGENTS.md`、`.agents/skills/`、`.codex/` +- 把“基础可用”和“Codex 接入文件完整”混成一个状态 +- 把“hooks 接入位存在”和“hooks runtime 已验证”混成一个状态 +- 已进入 Trellis 模式后，还反复问用户该用哪个命令 diff --git a/skills/BetterGPT/BetterTrellis/references/codex-workflow.md b/skills/BetterGPT/BetterTrellis/references/codex-workflow.md index b5fc142..c390e2e 100644 --- a/skills/BetterGPT/BetterTrellis/references/codex-workflow.md +++ b/skills/BetterGPT/BetterTrellis/references/codex-workflow.md @@ -1,20 +1,13 @@ # Codex Workflow -## Goal +Use this when a Codex session should follow Trellis project workflow. -把 Trellis 在 Codex 下的常用工作流整理成顺序感清楚的入口。 +## Integration Baseline -## Codex Integration Baseline +`trellis init --codex -u ` may create or update: -Codex 初始化命令： - -```bash -trellis init --codex -u -``` - -官方说明中，Codex 集成会生成： - -- 根目录 `AGENTS.md` +- `AGENTS.md` +- `.trellis/` - `.agents/skills/` - `.codex/config.toml` - `.codex/agents/` @@ -22,86 +15,32 @@ trellis init --codex -u - `.codex/hooks/session-start.py` - `.codex/hooks.json` -这组文件表示 **Codex 自动接入完整**。 - -但要注意平台差异： - -- 在支持 hooks 的平台，这组文件可以代表 hooks 自动接入完整 -- 在 **Windows 原生 Codex** 下，不要把它直接等同于“hooks 当前已生效” -- Windows 下当前更稳的口径应是：Codex 主要通过 `AGENTS.md`、skills、文档驱动 workflow 工作，hooks 更偏未来兼容位 - -如果项目里已经有 `.trellis/`、`AGENTS.md`、`.agents/skills/`，但没有完整 `.codex/*`： - -- 仍可判定为 **Trellis 基础可用** -- 只是 SessionStart 自动注入能力不完整 -- 回答时不要把这种状态误说成“当前项目不能使用 Trellis” - -如果当前是 Windows 原生 Codex： - -- 即使 `codex_hooks = true` 已开启，也不要默认把 SessionStart hook 当成当前已运行能力 -- 只有在用户明确要验 hooks 实效时，才单独核对该能力 - -## Session Entry - -Codex 侧 Trellis 的核心价值，在不同平台要分开说： - -- 支持 hooks 的平台 - → 可以通过 SessionStart hook 自动注入工作流、指南和任务上下文 -- Windows 原生 Codex - → 默认更依赖 `AGENTS.md`、skills、文档驱动 workflow，而不是把 SessionStart hook 当成当前已生效能力 - -因此回答时要先判断： - -- hooks 是否真的启用 -- 当前会话是否已经在 Trellis 上下文里 - -## Activation Policy - -对用户暴露的入口应是“是否按 Trellis 工作流接管当前开发任务”，而不是先要求用户记住命令名。 - -默认规则： - -1. 用户显式提到 `Trellis`、`start`、`task.py`、`/trellis:*` - → 直接进入 Trellis 工作流 -2. 用户没有显式提 Trellis，但任务明显是执行型开发任务，且项目存在 `.trellis/` - → 只在入口处确认一次是否按 Trellis 工作流推进 -3. 一旦确认，本轮后续默认由模型自己判断当前阶段和对应入口 -4. 除非用户显式退出，否则不要反复追问是否继续使用 Trellis +Treat these as integration files, not proof that hook runtime behavior is active on every platform. -## Recommended Command Rhythm +## Activation -如果当前项目已经接入，官方工作流可以压缩理解成： +Enter Trellis workflow when: -1. 进入会话 / 恢复上下文 - → `start` -2. 开始开发前加载相关规范 - → `before-dev` -3. 开发过程中按 spec 与 task 推进 -4. 做质量检查 - → `check` -5. 有跨层改动时补做 - → `check-cross-layer` -6. 完工时整理 - → `finish-work` -7. 记录会话 - → `record-session` +- the user mentions `Trellis`, `$start`, `start`, `continue`, `task.py`, `record-session`, or another platform-native Trellis entry +- repo or global instructions require Trellis workflow +- the user confirms Trellis use after `.trellis/` is detected for implementation work -## Response Guidance +Do not enter Trellis only because `.trellis/` exists for pure analysis, review, or architecture discussion. -当用户问“现在该用哪个 Trellis 命令”时，先按阶段回答： +## Stage Rhythm -- 刚开工 - → `start / before-dev` -- 写代码中 - → 继续围绕当前 task 与 spec -- 做验收 - → `check / check-cross-layer` -- 要结束本轮 - → `finish-work / record-session` +- Natural-language task request -> describe the task directly, then let Trellis route by stage +- Session/context restore -> `$start` / `start` +- Advance current workflow step -> `continue` +- Before implementation -> `before-dev` +- During work -> follow current task and relevant specs +- Quality check -> `check` +- Cross-layer work -> `check-cross-layer` +- Finish current work -> `$finish-work` / `finish-work` +- Persist session notes -> `record-session` -## Important Boundary +When the user asks which command to use, answer by current stage first, then name the command. -不同平台的命令外形可能不同，但 Codex 场景里，重点不是死记命令名，而是认清： +## Boundary -- 当前处在 Trellis 生命周期的哪一段 -- 当前上下文是来自 spec、task，还是 session log +Trellis is a workflow and project-memory layer. Do not reduce it to a command list, and do not claim hooks or session injection are active unless runtime evidence confirms them. diff --git a/skills/BetterGPT/BetterTrellis/references/commands.md b/skills/BetterGPT/BetterTrellis/references/commands.md index e613e90..d00d697 100644 --- a/skills/BetterGPT/BetterTrellis/references/commands.md +++ b/skills/BetterGPT/BetterTrellis/references/commands.md @@ -1,17 +1,30 @@ # Commands +Do not dump this table unless the user asks for a command reference. Pick the command that matches the current stage. + ## Install / Init ```bash npm install -g @mindfoldhq/trellis@latest trellis --version -trellis init -trellis init -u trellis init --codex -u -trellis init --cursor -trellis init --claude ``` +Other init targets exist (`trellis init`, `--cursor`, `--claude`), but prefer `--codex` for Codex integration. + +## Codex Workflow Entries + +These are workflow entry names, not shell commands: + +```text +$start +continue +$finish-work +record-session +``` + +Prefer stage-based wording: choose the entry that matches context restore, workflow advance, checking, or finish/journal work. Do not present these as a required sequence for every small edit. + ## Update ```bash @@ -21,30 +34,23 @@ trellis update --force trellis update --migrate ``` -说明： +Use `--dry-run` before risky template updates. `--force` overwrites managed files; do not use it casually. -- `trellis update` 默认只更新未被用户修改过的受管文件 -- `--dry-run` 先预览 -- `--force` 覆盖所有管理文件 -- `--migrate` 处理重命名、删除等结构迁移 - -## Task Workflow +## Tasks ```bash -python .trellis/scripts/task.py create "user-auth" --assignee +python .trellis/scripts/task.py create "task-name" --assignee python .trellis/scripts/task.py start python .trellis/scripts/task.py list python .trellis/scripts/task.py finish python .trellis/scripts/task.py archive ``` -## What To Prefer - -- 项目还没接入 - → 优先 `trellis init --codex -u ` -- 项目已经接入，但版本或模板过旧 - → 优先 `trellis update` -- 工作已经需要明确 PRD、上下文、当前任务 - → 优先 `task.py` +## Preference -不要把命令表直接整段甩给用户，除非用户明确要速查表。 +- missing project setup -> `trellis init --codex -u ` +- current Codex session needs context -> `$start` +- current Trellis task needs the next workflow step -> `continue` +- work is done and needs journaling -> `$finish-work` / `record-session` +- stale managed files -> `trellis update --dry-run`, then update if safe +- work needs explicit task state -> `task.py` diff --git a/skills/BetterGPT/BetterTrellis/references/init-flow.md b/skills/BetterGPT/BetterTrellis/references/init-flow.md index 7debcbf..98b2436 100644 --- a/skills/BetterGPT/BetterTrellis/references/init-flow.md +++ b/skills/BetterGPT/BetterTrellis/references/init-flow.md @@ -1,96 +1,58 @@ # Init Flow -## Goal +Use this only when a project may need Trellis initialization or Codex integration repair. -把 Trellis 的接入判断和初始化代操作流程固定下来，避免每次都临场拼命令。 - -## Step 1: Check CLI - -先确认本机可用： +## Check CLI ```bash trellis --version ``` -如果命令不存在，先明确告知用户需要先安装 CLI。 - -官方安装方式： +If missing, tell the user Trellis CLI is required: ```bash npm install -g @mindfoldhq/trellis@latest ``` -## Step 2: Check Project State - -进入项目根目录后，检查： - -- Trellis 基础： - - `.trellis/` - - `AGENTS.md` - - `.agents/skills/` -- Codex 自动接入： - - `.codex/config.toml` - - `.codex/hooks/session-start.py` - - `.codex/hooks.json` - -但在 **Windows 原生 Codex** 下，要额外区分： - -- hooks 配置位是否存在 -- hooks 当前平台是否真的支持并执行 +## Check Project State -默认不要把这两件事当成同一件事。 +From the project root, inspect only what is needed: -判定规则： +- `.trellis/` +- `AGENTS.md` +- `.agents/skills/` +- `.codex/agents/` +- `.codex/skills/` +- `.codex/hooks/` -- 如果 `trellis` CLI 可用，且 `.trellis/` 已存在 - → 判定为 **Trellis 基础可用** -- 如果基础项存在，但 `.codex/*` 不完整 - → 判定为 **Trellis 可用，但 Codex 自动接入不完整** -- 如果基础项和 `.codex/*` 都完整 - → 判定为 **Trellis for Codex 自动接入完整** -- 只有在 `.trellis/` 与基础接入物都明显缺失时 - → 判定为 **未初始化** +Only inspect hook internals when diagnosing hook behavior: -Windows 原生 Codex 补充口径： +- `.codex/hooks/session-start.py` +- `.codex/hooks.json` +- global Codex feature flags -- 即使 `codex_hooks = true` 已开启，只要当前平台 hooks 仍未实际支持 - → 也不要把 `hooks.json` 缺失直接判定成“当前 Trellis 不可用” -- 这时更准确的说法是： - → **Trellis 基础可用 / Codex workflow 可用，但 hooks 仍属于占位或未来兼容项** +Status wording: -## Step 3: Ask Before Init +- `.trellis/` exists -> Trellis base is available. +- base exists but `.codex/*` is incomplete -> Trellis is usable, Codex integration files are incomplete. +- base and Codex directories exist -> Codex integration files appear complete. +- base is missing -> not initialized. -如果判定为未初始化，不直接执行。 +Do not equate integration files with active hook runtime. Hook support needs compatible platform behavior, enabled feature flags, and runtime evidence. -使用固定语义： +## Ask Before Init -> 检测到当前项目尚未完成 Trellis 初始化，是否现在为当前项目执行初始化？ -> 将执行：`trellis init --codex -u ` -> 初始化完成后，通常需要重开当前项目会话，Trellis 的 hooks / skills / agents 才会完整接入。 - -只有在用户明确回复“是 / 确认 / 继续”后，才继续。 - -## Step 4: Init Command - -在项目根目录执行： +Do not initialize silently. Ask once and name the command: ```bash trellis init --codex -u ``` -如果用户没有指定名字，Trellis 默认可从 `git config user.name` 推断，但在代操作场景下，优先使用用户明确给出的名字。 - -## Step 5: Post-Init Check +Proceed only after explicit user confirmation. -初始化后，回读以下结果： +## Post-Init Check -- `.trellis/` 是否已生成 -- `AGENTS.md` 是否已生成或更新 -- `.agents/skills/` 是否存在 -- `.codex/config.toml` 是否存在 -- `.codex/hooks/session-start.py` 与 `.codex/hooks.json` 是否存在 - -还要提醒用户检查全局 `~/.codex/config.toml`： +After init, verify the expected files above. If hook behavior matters, also check global feature flags: ```toml [features] @@ -98,9 +60,4 @@ multi_agent = true codex_hooks = true ``` -如果 hooks 未启用，就要说明：Trellis 基础结构虽然已经落地，但 SessionStart 自动注入能力不会完整生效。 - -如果当前是 Windows 原生 Codex，还要额外说明： - -- 当前应优先按 `AGENTS.md` + skills + 文档驱动 workflow 理解实际生效路径 -- `codex_hooks = true` 与 hooks 文件更适合作为未来兼容位或占位，不应直接宣称“hooks 已在当前平台生效” +Treat feature flags as required setup, not proof that a hook ran. Report base availability, Codex integration-file status, and hook runtime evidence separately. diff --git a/skills/BetterGPT/BetterTrellis/references/structure.md b/skills/BetterGPT/BetterTrellis/references/structure.md index c0a7bb7..11e4b20 100644 --- a/skills/BetterGPT/BetterTrellis/references/structure.md +++ b/skills/BetterGPT/BetterTrellis/references/structure.md @@ -1,61 +1,36 @@ # Structure -## Core Layers +Use this when explaining what Trellis added to a project. -### 1. `.trellis/` +## Layers -这是 Trellis 的项目知识与工作流层。 +- `.trellis/`: project workflow, specs, tasks, workspace logs, and helper scripts +- `AGENTS.md`: Codex entry context for the project +- `.agents/skills/`: shared agent skills usable beyond Codex +- `.codex/`: Codex-specific agents, skills, hooks, and platform config -常见内容： +Typical `.trellis/` contents: -- `workflow.md`：工作流说明 -- `spec/`：规范库 -- `workspace/`：会话日志 -- `tasks/`：任务系统 -- `scripts/task.py`：任务管理脚本 +- `workflow.md` +- `spec/` +- `workspace/` +- `tasks/` +- `scripts/task.py` -### 2. `AGENTS.md` +Typical `.codex/` contents: -这是 Codex 的入口层。 +- `config.toml` +- `agents/` +- `skills/` +- `hooks/` -在 Trellis for Codex 中，它负责把项目级基础上下文暴露给 Codex，而不是承载全部规范细节。 +## Explanation Rule -### 3. `.agents/skills/` +Say: -这是共享 skill 层。 +- `.trellis/` manages project knowledge and workflow. +- `AGENTS.md` exposes the project entry context. +- `.agents/skills/` stores shared capabilities. +- `.codex/` stores Codex-specific integration: agents, skills, hooks, and related config. -适合放跨平台可复用的 skills，不只服务 Codex，也可供其他兼容 agent 系统使用。 - -### 4. `.codex/` - -这是 Codex 平台接入层。 - -常见内容： - -- `config.toml`：项目级 Codex 配置 -- `agents/`：自定义 agents -- `skills/`：Codex 专属 skills -- `hooks/session-start.py` -- `hooks.json` - -补充说明： - -- `hooks/session-start.py` 与 `hooks.json` 表示 hooks 接入位 -- 但是否“当前已生效”，还取决于平台是否真的支持 hooks -- 在 Windows 原生 Codex 下，默认不要把这两项直接解释成“当前一定在运行” - -## How To Explain It - -对用户解释时，优先用这套分层： - -- `.trellis/` 管知识与流程 -- `AGENTS.md` 管入口 -- `.agents/skills/` 管共享能力 -- `.codex/` 管平台接入 - -如果当前平台是 Windows 原生 Codex，还要补一句： - -- 当前实际工作流优先依赖 `AGENTS.md` + skills + 文档驱动 workflow -- hooks 更适合作为未来兼容位或占位，不要误报为当前已生效能力 - -不要混成一句“这些都是提示词文件”。 +Do not describe all of these as generic prompt files. Do not claim hooks, preludes, or session injection are running unless runtime evidence verifies that behavior. diff --git a/skills/BetterGPT/BetterVibe/SKILL.md b/skills/BetterGPT/BetterVibe/SKILL.md index a4b6bd4..aac6708 100644 --- a/skills/BetterGPT/BetterVibe/SKILL.md +++ b/skills/BetterGPT/BetterVibe/SKILL.md @@ -1,6 +1,6 @@ --- name: better-vibe -description: Use when designing, reviewing, or implementing full-stack application structure and engineering boundaries. Especially use when frontend pages are becoming overloaded, presentation code is mixing with backend concerns, backend services are growing into large coupled modules, or the system needs clearer separation between UI, business logic, persistence, and cross-layer responsibilities. +description: Use for full-stack structure and boundary decisions. Trigger when UI code absorbs business logic, backend services grow coupled, or the system needs clearer separation among presentation, domain logic, persistence, and cross-layer contracts. --- # Better Vibe @@ -48,9 +48,9 @@ description: Use when designing, reviewing, or implementing full-stack applicati ## Read References When Needed -- 需要判断前端页面职责和展示层边界时，读 `references\frontend-boundaries.md` -- 需要判断后端分层、服务边界和副作用隔离时，读 `references\backend-boundaries.md` -- 需要判断前后端如何解耦、如何分配职责时，读 `references\fullstack-boundaries.md` +- 需要判断前端页面职责和展示层边界时，读 `references/frontend-boundaries.md` +- 需要判断后端分层、服务边界和副作用隔离时，读 `references/backend-boundaries.md` +- 需要判断前后端如何解耦、如何分配职责时，读 `references/fullstack-boundaries.md` ## Hard Constraints diff --git a/skills/BetterGPT/BetterVibe/references/backend-boundaries.md b/skills/BetterGPT/BetterVibe/references/backend-boundaries.md index e9f65f8..5e3b85a 100644 --- a/skills/BetterGPT/BetterVibe/references/backend-boundaries.md +++ b/skills/BetterGPT/BetterVibe/references/backend-boundaries.md @@ -1,37 +1,23 @@ # Backend Boundaries -## Core Goal +Keep backend layers clear and side effects explicit. -让后端结构保持分层清楚、职责单一、副作用可控。 +## Layer Rules -## Layering Rules +- Routes/controllers/handlers: transport, validation, orchestration entry. +- Services: domain workflow and business coordination. +- Repositories/DAO/persistence: data access. -- 路由层 / controller / handler 负责接入、校验、调用，不负责堆业务 -- service 层负责业务编排，不负责承载所有东西 -- repository / DAO / persistence 层负责数据访问，不负责业务判断 +Do not let one layer quietly absorb the others. -## Service Discipline +## Data Rules -- 一个 service 只负责一个业务域 -- 跨域流程通过明确编排完成，不要把所有逻辑塞进同一个 service -- 不要把 service 写成“万能入口” +- Keep API DTOs, domain objects, and database models distinct when their responsibilities differ. +- Do not expose storage shape as the API contract by accident. +- Keep side effects such as cache, queue, third-party calls, and persistence updates visible and testable. -## Data Boundary Rules +## Avoid -- API DTO、领域对象、数据库模型不要混用 -- 不要让数据库表结构直接决定接口返回结构 -- 不要把“库里怎么存”直接暴露成“前端怎么拿” - -## Side Effects - -- 缓存、消息、第三方调用、落库、副作用更新要有明确边界 -- 不要让核心业务函数顺手做一堆隐藏副作用 -- 复杂副作用链要能拆解和测试 - -## Anti-Patterns - -- 巨型 controller -- 巨型 service -- 巨型 handler -- 同一个方法里同时做校验、业务、持久化、返回组装 -- 看起来只有一层 service，实际上里面塞了所有系统复杂度 +- giant controllers, handlers, or services +- one method doing validation, business rules, persistence, and response assembly +- a "service layer" that is actually the whole system hidden in one file diff --git a/skills/BetterGPT/BetterVibe/references/frontend-boundaries.md b/skills/BetterGPT/BetterVibe/references/frontend-boundaries.md index ab10906..0a7250e 100644 --- a/skills/BetterGPT/BetterVibe/references/frontend-boundaries.md +++ b/skills/BetterGPT/BetterVibe/references/frontend-boundaries.md @@ -1,33 +1,23 @@ # Frontend Boundaries -## Core Goal +Keep pages focused on presentation, interaction, and local state. -让前端展示层保持清晰、可拆分、可维护。 +## Page Rules -## Page Responsibility Rules - -- 单个页面只应承担一个主任务 -- 页面负责组织展示和交互，不负责承载越来越多的业务编排 -- 页面一旦开始同时处理多个区域、多类状态、多段流程，应优先拆分模块 +- One page should have one main job. +- Split areas that have different business rhythms, state, or test needs. +- Move complex data shaping, permissions, persistence, and domain decisions out of the page layer. +- Keep reusable UI pieces independent enough to understand and test. ## Split Signals -出现以下情况时，应考虑拆分： - -- 一个页面里同时存在多个业务区域，彼此变化节奏不同 -- 页面文件越来越长，逻辑和 JSX/模板相互缠绕 -- 数据加载、筛选、提交、反馈、权限判断都堆在页面层 -- 局部区域已经可以独立理解、独立测试、独立复用 - -## Presentation Purity - -- 展示层优先只关心显示、交互、局部状态 -- 非必要不要把后端能力直接塞进页面 -- 不让页面自己承担复杂数据拼装、领域规则判断、持久化策略 +- The page mixes multiple unrelated workflows. +- Data loading, filtering, submit logic, feedback, and permissions are tangled with markup. +- A local section already has its own state, actions, and failure modes. -## Anti-Patterns +## Avoid -- page 文件变成大一统入口 -- 一个页面里塞多个互相独立的业务流 -- 页面直接决定复杂业务规则 -- 为了图快，把后端返回结构、状态处理、展示逻辑全部糊在一起 +- giant page files +- backend response shapes leaking directly into every component +- page-level code deciding complex business rules +- view code becoming the only place where behavior is understood diff --git a/skills/BetterGPT/BetterVibe/references/fullstack-boundaries.md b/skills/BetterGPT/BetterVibe/references/fullstack-boundaries.md index 75a4c72..3c6fd53 100644 --- a/skills/BetterGPT/BetterVibe/references/fullstack-boundaries.md +++ b/skills/BetterGPT/BetterVibe/references/fullstack-boundaries.md @@ -1,41 +1,23 @@ # Fullstack Boundaries -## Core Goal - -明确前端、后端、边界层各自负责什么，避免为了省事形成长期耦合。 +Use this when a change crosses UI, API, domain logic, persistence, or integration layers. ## Default Split -- 前端负责展示、交互、用户路径、局部状态 -- 后端负责业务规则、权限、一致性、持久化、副作用 -- 边界层只负责必要的聚合、适配和协议转换 - -## Fullstack Coordination Rules - -- 能在前端解决的展示问题，不要丢给后端 -- 能在后端保证的一致性问题，不要丢给前端兜底 -- 不要为了单页方便，就让后端接口变成高度展示耦合的特供结构 -- 不要为了后端省事，就让前端承担本该由服务端保证的业务规则 - -## BFF Boundary - -- BFF 只在确实需要聚合或适配时使用 -- 不把 BFF 写成新的大杂烩业务层 -- BFF 负责整形，不负责吞掉领域服务职责 - -## Change Cost Signal - -如果一个需求改动时： +- Frontend: display, interaction, user path, local state. +- Backend: business rules, authorization, consistency, persistence, side effects. +- Boundary/BFF: aggregation, adaptation, protocol shaping when truly needed. -- 前端要改很多展示逻辑 -- 后端要改很多业务拼装 -- 两边还要同时改接口形状 +## Coordination Rules -那通常说明边界划分已经有问题。 +- Do not push backend consistency problems into frontend workarounds. +- Do not make APIs page-specific unless the product contract really is page-specific. +- Do not turn a BFF into a second business layer. +- Keep cross-layer contracts explicit and small. -## Anti-Patterns +## Warning Signs -- 前端和后端都在做同一份业务判断 -- 后端返回完全为某个页面临时拼接的展示结构 -- 前端为了页面交付不断请求后端增加页面专属小字段 -- 一次需求变更牵连前后端多个大文件一起修改 +- The same business rule appears in frontend and backend. +- A UI change forces broad API and service rewrites. +- Backend responses are shaped for one screen with many temporary fields. +- A small feature change touches several large files across both sides. diff --git a/skills/BetterGPT/SKILL.md b/skills/BetterGPT/SKILL.md index f3aa998..c99fcc8 100644 --- a/skills/BetterGPT/SKILL.md +++ b/skills/BetterGPT/SKILL.md @@ -1,6 +1,6 @@ --- name: better-gpt -description: Use as the workspace-level entry skill for this repository when responses should follow BetterGPT defaults. This skill routes by default to BetterLanguage for language shaping, then applies task-specific enhancements only when needed, such as BetterFrontend for frontend presentation work, BetterVibe for full-stack engineering boundary and maintainability guidance, BetterTrellis for Trellis workflow, Codex soft integration, initialization, spec, task, and hooks-related guidance, and BetterSubagents for subagent delegation, orchestration, wait handling, and takeover guardrails. Use when a single main entry skill should coordinate default loading order and on-demand sub-skill activation. +description: Entry skill for BetterGPT defaults. Load BetterLanguage first, apply concise execution discipline for coding/config changes, then route only when needed to BetterFrontend, BetterVibe, BetterTrellis, or BetterSubagents. Do not replace task-specific skills. --- # BetterGPT @@ -9,62 +9,43 @@ description: Use as the workspace-level entry skill for this repository when res 这是当前工作区的主入口 skill。 -它本身不负责展开所有细节，只负责三件事： +它本身不负责展开所有细节，只负责四件事： 1. 定义默认基础层 2. 定义加载顺序 3. 按任务类型路由到子 skill +4. 为执行型任务提供入口级行为护栏 ## Core Rule -默认先应用 `BetterLanguage`。 +默认先应用 `BetterLanguage`：英文技术工作，中文用户交付。 只有在命中特定场景时，才继续叠加对应子 skill。 -## Load Order +对代码、配置、文档工作流、skill 更新这类执行型任务，还要默认应用“先想清楚再动手”的入口纪律：事实优先、最小正确改动、只碰必要范围、先定义成功标准、再做窄验证。 -默认顺序如下： +## Core Workflow -1. 先进入 `BetterGPT` -2. 默认应用 `BetterLanguage` -3. 再判断当前任务是否是执行型开发任务；若工作区存在 `.trellis/`，先做 Trellis 模式判断 -4. 再判断任务重点属于展示层，还是工程边界 / 职责拆分 -5. 命中展示层任务时叠加 `BetterFrontend` -6. 命中全栈边界、分层、耦合治理任务时叠加 `BetterVibe` -7. 命中 Trellis 初始化、工作流、spec、task、hooks、Codex 软接入问题时叠加 `BetterTrellis` -8. 只要主代理准备实际派发、并行调度、等待、重派、接管 subagent，也必须叠加 `BetterSubagents` -9. 如果当前是 CLI 场景，则由 `BetterLanguage` 内部环境分支决定终端排版 +1. 先应用 `BetterLanguage`。 +2. 对执行型任务应用入口级执行纪律。 +3. 如果工作区有 `.trellis/`，先服从 repository / global instructions 中的 Trellis 入口规则；没有明确规则时，再按 `references/routing.md` 判断是否询问。 +4. 按任务重点按需叠加 `BetterFrontend` / `BetterVibe` / `BetterTrellis`。 +5. 只要准备实际使用 subagent（派发、并行、`wait_agent`、`send_message`、`followup_task`、重派、接管），先叠加 `BetterSubagents`。 +6. 命中多个场景时允许叠加，不互斥。 -## Routing Rules +完整加载和路由细则见 `references/load-policy.md` 与 `references/routing.md`。 -### Decision Order +## Execution Discipline -按以下顺序判断： +仅对执行型任务启用；纯闲聊、翻译、短问答不强行展开。 -1. 默认先应用 `BetterLanguage` -2. 判断当前任务是否属于执行型开发任务 - → 这里默认指改代码、补功能、修缺陷、重构、补测试、明确落地实现 -3. 纯分析、纯代码审查、纯架构讨论、实现前方案比较 - → 不默认进入 Trellis -4. 如果是执行型开发任务，且工作区存在 `.trellis/` - → 先做 Trellis 模式判断，再决定是否叠加 `BetterTrellis` -5. 只要主代理准备实际使用 subagent（包括派发、并行、`wait_agent`、`send_input`、重派、接管） - → 必须叠加 `BetterSubagents` -6. 再判断任务重点更偏展示层，还是更偏工程边界 / 职责拆分 -7. 命中多个场景时允许叠加，不互斥 +- 编辑前：读相关本地 instructions、repo 文档、配置、测试和目标文件；记忆只作线索，便宜可验证的事实要现场验证。 +- 计划时：非平凡改动说明关键假设、取舍、成功标准和验证方式；只有错误假设会造成实质风险时才先问。 +- 编辑时：选择最小正确方案，不加未要求的功能、抽象、依赖或“以防万一”的处理；只碰必要行。 +- 推进时：发现当前目标内、低风险、边界清楚且可验证的小修正，直接完成并验证；不要把清楚修正留成“下一轮建议”。 +- 验证时：bug 修复优先补测试或最小复现；其他改动跑最窄有意义检查，并说明剩余未验证风险。 -### Combination Rules - -- `BetterLanguage` 永远先于其他 skill -- `BetterTrellis` 是流程层，可与 `BetterFrontend`、`BetterVibe` 叠加 -- `BetterSubagents` 是调度层，可与 `BetterTrellis`、`BetterFrontend`、`BetterVibe` 叠加 -- `BetterFrontend` 负责展示层成品化，不负责全栈边界治理 -- `BetterVibe` 负责职责拆分和工程边界，不负责 Trellis 工作流接入 -- 纯分析、纯评审、纯方案比较任务，不因项目存在 `.trellis/` 就默认触发 `BetterTrellis` -- 如果任务同时涉及“页面产品化”和“页面 / 模块过载拆分”，则同时叠加 `BetterFrontend` + `BetterVibe` -- 不因为命中一个 skill 就阻断其他必要 skill - -### Typical Triggers +## Typical Triggers - 普通对话、分析、解释、表达优化 → 默认只走 `BetterLanguage` @@ -81,29 +62,17 @@ description: Use as the workspace-level entry skill for this repository when res ## Hard Constraints -- `BetterGPT` 只做路由，不重复子 skill 的具体规则 +- `BetterGPT` 只做主入口路由和入口级执行纪律，不重复子 skill 的具体规则 +- System、developer、repository、explicit user instructions 覆盖 `BetterGPT` - 默认不在回答结尾追加邀约式下一步引导 -- 这条规则属于全局表达约束，不只由子 skill 自行决定 -- 如果当前是执行型开发任务，且工作区已有 `.trellis/`，主入口必须先判断是否进入 Trellis 工作流 -- 这类入口判断属于主路由职责，不能只依赖 `BetterTrellis` 自己触发 -- 用户一旦明确确认本轮按 Trellis 工作流推进，后续同一任务默认持续按 Trellis 处理，不反复询问 -- 如果用户明确拒绝本轮使用 Trellis，才回退为普通开发流程 -- 只要主代理准备实际使用 subagent，必须先进入 `BetterSubagents`，不能绕过调度层直接派发 -- 进入 `BetterSubagents` 后，派发说明必须带上子任务边界、预期输出、验证要求，以及命中的 skill / spec / MCP 约束 - `BetterLanguage` 是默认基础层 -- `BetterFrontend` 是按需增强层，不是默认常驻层 -- `BetterVibe` 是按需增强层，不是默认常驻层 -- `BetterTrellis` 是按需增强层，不是默认常驻层 -- `BetterSubagents` 是按需增强层，不是默认常驻层 -- 如果一个任务不属于前端，就不要加载 `BetterFrontend` -- 如果一个任务不属于全栈边界或工程分层，就不要加载 `BetterVibe` -- 如果一个任务不属于 Trellis 工作流或软接入，就不要加载 `BetterTrellis` -- 如果一个任务不属于 subagent 调度、委派、等待、接管，就不要加载 `BetterSubagents` +- `BetterFrontend`、`BetterVibe`、`BetterTrellis`、`BetterSubagents` 都是按需增强层，不是默认常驻层 +- 只要主代理准备实际使用 subagent，必须先进入 `BetterSubagents`，不能绕过调度层直接派发 ## Read References When Needed -- 需要看完整路由说明时，读 `references\routing.md` -- 需要看默认加载策略时，读 `references\load-policy.md` +- 需要看完整路由说明时，读 `references/routing.md` +- 需要看默认加载策略时，读 `references/load-policy.md` ## 参考 diff --git a/skills/BetterGPT/references/load-policy.md b/skills/BetterGPT/references/load-policy.md index f82fc84..056d5be 100644 --- a/skills/BetterGPT/references/load-policy.md +++ b/skills/BetterGPT/references/load-policy.md @@ -1,43 +1,28 @@ # Load Policy -## Goal - -把“默认加载”和“按需加载”明确分开，避免所有 skill 都高频常驻。 +Keep the default layer small. The entry skill should route work; it should not preload every BetterGPT sub-skill. ## Default Layer - `BetterLanguage` -这是当前唯一默认基础层。 - -## On-Demand Layer - -- `BetterFrontend` -- `BetterVibe` -- `BetterTrellis` -- `BetterSubagents` +For implementation or configuration work, also apply the entry-level execution discipline in `BetterGPT`: verify local facts, state important assumptions, keep edits small, and run narrow validation. This is not a separate sub-skill. -只有当前任务明确命中对应场景时，才应叠加。 +## On-Demand Layers -- 前端展示层任务 - → `BetterFrontend` -- 全栈架构、职责边界、分层治理任务 - → `BetterVibe` -- Trellis 初始化、workflow、spec、task、hooks、Codex 接入任务 - → `BetterTrellis` -- subagent 委派、并行、等待、回收、主代理接管任务 - → `BetterSubagents` +Load these only when the current task needs them: -## Control Principles +- `BetterFrontend`: visible UI, product polish, frontend presentation review +- `BetterVibe`: frontend/backend boundaries, coupling, layering, responsibility splits +- `BetterTrellis`: Trellis init, workflow, spec/task handling, hooks, Codex integration +- `BetterSubagents`: actual subagent dispatch, waiting, steering, cleanup, fallback takeover -- 默认层数量越少越好 -- description 越宽，误触发越多 -- 默认规则放主入口 -- 具体细节放子 skill -- 需要总是生效的规则，不要只靠子 skill 自己触发 -- “开发任务是否进入 Trellis 工作流”的入口判断，属于主入口规则，不属于子 skill 自治 -- “进入 Trellis 后具体走哪个阶段、用哪个入口”，再交给 `BetterTrellis` +## Control Rules -## Practical Meaning +- Put always-on behavior in the entry skill or higher-level instructions, not in a sub-skill that might not trigger. +- Keep domain detail in the relevant sub-skill or reference file. +- Make `description` narrow enough to trigger reliably without pulling unrelated work into context. +- Decide whether a project should enter Trellis at the entry layer; let `BetterTrellis` handle the workflow after entry. +- Decide whether subagents will actually be used before loading `BetterSubagents`. -如果你要“BetterGPT 总是加载”，真正可控的方式不是把它放在目录里，而是让上层入口明确先经过它。 +If `BetterGPT` must always be active, wire it through AGENTS or another higher-level entry point. A folder on disk is only discoverable; it is not a guarantee of activation. diff --git a/skills/BetterGPT/references/routing.md b/skills/BetterGPT/references/routing.md index 6966d47..9671906 100644 --- a/skills/BetterGPT/references/routing.md +++ b/skills/BetterGPT/references/routing.md @@ -1,106 +1,41 @@ # Routing -## Core Goal +`BetterGPT` is the entry router. It applies the default language layer, adds execution discipline for real work, then loads only the sub-skill needed by the task. -让 `BetterGPT` 成为唯一主入口，由它决定默认层和按需层的加载顺序。 +## Route Order -## Default Route +1. Start with `BetterLanguage`. +2. If the task changes code, config, workflow files, tests, or local state, apply entry execution discipline. +3. If the project has `.trellis/` and the task is implementation work, decide whether Trellis workflow is active. +4. If the main agent will actually call `spawn_agent`, `wait_agent`, `send_message`, `followup_task`, or `close_agent`, load `BetterSubagents`. +5. Add `BetterFrontend` for visible UI work. +6. Add `BetterVibe` for boundary, layering, or coupling work. +7. Add `BetterTrellis` for Trellis init, task/spec workflow, hooks, or Codex integration. -- 默认先走 `BetterLanguage` -- 再按固定顺序判断是否叠加其他子 skill +Multiple sub-skills may apply, but do not load one only because another loaded. -## Current Route +## Sub-Skill Roles -### Language +- `BetterLanguage`: English-first technical work, concise Chinese delivery, preserved technical tokens +- `BetterFrontend`: production-ready UI, no demo leakage, no developer commentary in visible surfaces +- `BetterVibe`: presentation/domain/persistence boundaries, cross-layer contracts, low-risk structure changes +- `BetterTrellis`: project workflow entry, spec/task state, hooks, Trellis command mapping +- `BetterSubagents`: callable agent mapping, scoped delegation, waits, steering, cleanup, fallback takeover -- `BetterLanguage` -- 角色：默认基础层 -- 负责：结构压缩、去口癖、去翻译腔、CLI 分支 +## Trellis Gate -### Frontend +Enter Trellis directly when the user mentions `Trellis`, `start`, `task.py`, `record-session`, `/trellis:*`, or repository instructions require Trellis workflow. -- `BetterFrontend` -- 角色：按需增强层 -- 负责：前端展示层、视觉约束、成品化、去 AI 味 +If `.trellis/` exists but neither the user nor repo instructions specify the workflow, ask once before using Trellis for implementation work. Pure analysis, review, or architecture discussion does not enter Trellis just because `.trellis/` exists. -### Fullstack +## Subagent Gate -- `BetterVibe` -- 角色：按需增强层 -- 负责：前端职责边界、后端分层、前后端解耦、全栈可维护性 +Load `BetterSubagents` only when subagents will be used or the user asks about subagent orchestration. Do not load it for ordinary local exploration. -### Trellis +## Boundaries -- `BetterTrellis` -- 角色：按需增强层 -- 负责：Trellis 初始化、Codex 软接入、workflow、spec、task、hooks、目录职责解释 - -### Subagents - -- `BetterSubagents` -- 角色：按需增强层 -- 负责：subagent 委派、并行、等待、超时介入、结果整合、主代理接管护栏 - -## Decision Order - -主入口按以下顺序判断： - -1. 默认先走 `BetterLanguage` -2. 再判当前任务是否属于执行型开发任务 - → 包括改代码、补功能、修缺陷、重构、补测试、明确落地实现 -3. 纯分析、纯代码审查、纯架构讨论、实现前方案比较 - → 不默认进入 Trellis -4. 如果是执行型开发任务，且项目存在 `.trellis/` - → 先做 Trellis 模式判断 -5. 只要主代理准备实际使用 subagent（派发、并行、`wait_agent`、`send_input`、重派、接管） - → 必须叠加 `BetterSubagents` -6. 再判当前任务重点更偏展示层，还是更偏全栈边界 / 职责拆分 -7. 命中多个场景时允许叠加 - -## Combination Rules - -- `BetterLanguage` 永远先于其他 skill -- `BetterTrellis` 是流程层，可与 `BetterFrontend`、`BetterVibe` 叠加 -- `BetterSubagents` 是调度层，可与 `BetterTrellis`、`BetterFrontend`、`BetterVibe` 叠加 -- `BetterFrontend` 负责展示层成品化 -- `BetterVibe` 负责边界、分层、耦合治理 -- 纯分析 / 评审 / 方案比较任务，不因存在 `.trellis/` 就默认进入 `BetterTrellis` -- 同时涉及页面产品化与页面 / 模块过载拆分时，叠加 `BetterFrontend` + `BetterVibe` -- 不因为命中一个 skill 就阻断其他必要 skill - -## Typical Triggers - -- 如果任务重点是“怎么表达” - → 只走 `BetterLanguage` - -- 如果任务已经是执行型开发，且项目存在 `.trellis/` - → 先做 Trellis 模式判断： - - 用户显式提到 `start`、`task.py`、`record-session`、`/trellis:*`、`Trellis` - → 直接进入 `BetterLanguage` + `BetterTrellis` - - 用户没有显式提 Trellis，但任务明显属于开发执行 - → 先询问一次是否按 Trellis 工作流推进 - -- 如果任务重点是“前端长什么样”“页面太像 demo”“要做成正式产品界面” - → `BetterLanguage` + `BetterFrontend` - -- 如果任务重点是“前后端怎么分层、怎么拆职责、怎么降低耦合”“页面逻辑太重怎么拆” - → `BetterLanguage` + `BetterVibe` - -- 如果任务重点是“该派给哪个 subagent”“什么时候并行”“`wait_agent` 超时后怎么处理”“主代理何时接管” - → `BetterLanguage` + `BetterSubagents` - -- 即使用户没有显式提到 subagent，只要主代理已经决定要调用本地 agent - → 也必须先进入 `BetterSubagents`，再执行派发 - -- 如果任务重点是“终端里怎么排版更好读” - → 走 `BetterLanguage`，并启用其终端分支 - -## Boundary - -- 主入口不直接复制子 skill 规则 -- 子 skill 不应反过来承担主入口路由职责 -- 新增子 skill 时，也应先挂到这里，再决定是否独立触发 -- “是否切入 Trellis 工作流”由主入口判断 -- “切入后如何按阶段执行”由 `BetterTrellis` 判断 -- “是否需要进入 subagent 调度层”由主入口判断 -- “进入后派给谁、派发格式、等待与接管”由 `BetterSubagents` 判断 +- The entry skill may route and enforce broad execution discipline. +- It should not duplicate the detailed rules of child skills. +- Child skills should not redefine entry routing. +- If inspection or validation finds a clear in-scope, low-risk, verifiable fix, implement it in the same turn instead of parking it as a next-round suggestion. +- New child skills must be added here only if they represent a distinct recurring job. diff --git a/tests/test_skill_repo.py b/tests/test_skill_repo.py index 53b1920..b5aa1c7 100644 --- a/tests/test_skill_repo.py +++ b/tests/test_skill_repo.py @@ -21,7 +21,7 @@ "BetterFrontend/references/production-defaults.md", "BetterFrontend/references/visual-rules.md", "BetterLanguage/SKILL.md", - "BetterLanguage/references/banned-phrases.md", + "BetterLanguage/references/conversation-pragmatics.md", "BetterLanguage/references/compression-rules.md", "BetterLanguage/references/environment-branch.md", "BetterLanguage/references/natural-chinese.md",