draftgo-cli 3.0.29 → 3.0.33

package/resources/skill/rules/dev-workflow.md

@@ -1,749 +0,0 @@
----
-name: draftgo-dev-workflow
-description: DraftGo 开发流程规范。所有"开发 / 修改 / 新建 / 重构 / 修复"类任务先分级：小修、轻功能、标准功能、高风险，再执行对应流程。
-version: 1.0.0
----
-
-# DraftGo 开发流程规范
-
-> 这份规范不替换 [frontend.md](./frontend.md) 与 [debugging-syntax.md](./debugging-syntax.md)，它们仍然生效。这份规范先做任务分级，保证简单问题不被流程拖慢，复杂问题仍然有完整闭环。
-> 根 `SKILL.md` 是每次激活完整必读的核心规则源；本文件只展开执行细节。若表述冲突，以根 `SKILL.md` 为准，不叠加两套门禁。
-
----
-
-## 总则：四档开发流程
-
-```
-小修       直接定位 → 改 → 轻量证据
-轻功能     范围复述 → 直接做 → 凭证据闭环
-标准功能   轻量确认 → 内部短计划 → 执行闭环
-高风险     完整 Story / 计划 / 验证 / 回读证据
-```
-
-例外：纯工具操作（`/draftgo init`、`/draftgo push`、`/draftgo status`、`/draftgo doctor`、`/draftgo story`、查 API、查页面元数据、读文件、回答问题）**不走开发流程**。
-
----
-
-## 交付追求（强制但不模板化）
-
-DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快速交付高质量项目：
-
-- **开发的急速感**：优先用本地 index、目标文件、现有资源和最小必要规则快速建立上下文；资源关系不清时再用 `draftgo map`。小修和轻功能不要被表格化流程拖慢。
-- **逻辑与实现的完整**：优先考虑真实落地闭环、高可用；默认真实数据、真实入口、真实反馈和必要证据。页面、导航、DB、脚本、权限和后台维护按用户路径闭环推断。
-- **迭代性强**：文件命名、route、数据 schema、组件结构、changelog、Task/lessons 记录要让下一次 AI 或开发者能继续接手。
-- **前端 UI 能力**：平台壳层默认 React + Tailwind；数据库 HTML 页面默认普通 HTML + Tailwind。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用；DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法。
-
-判断一版交付是否合格：用户路径、数据和操作能真实落地，后续继续改不用重猜结构。
-
----
-
-## 真实落地默认原则（强制）
-
-除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都优先考虑真实落地闭环、高可用。
-
-- 不要把功能降级成只有前端展示的假页面；按钮、表单、搜索、筛选、分页、提交、保存、删除、发布、管理等交互默认要有真实效果。
-- 不要用写死数组、静态卡片、空点击事件、只弹 toast 的按钮伪装业务能力；演示数据只能用于加载态、空态或用户明确要求的原型/demo。
-- 如果需求涉及可维护内容或业务记录，优先判断是否可用 DraftGo 动态 DB、已有 db_meta、custom_scripts 或 AIHub 资产完成真实数据闭环，并考虑后续维护、迭代和稳定性。
-- **数据存储选型：业务数据优先用动态 DB 通用库。**
-- 若平台能力、权限、外部依赖或通用动态 DB 都无法支撑该功能，不要继续开发伪功能；向用户说明具体阻塞点和可选替代方案，确有复用价值时在 `.draftgo/lessons/` 记录“无法闭环原因 / 已验证限制 / 后续建议”。
-
-一句话判断：用户没有明确要假，就优先考虑真实落地闭环、高可用；做不了真实闭环，就停下来说明，不写假的。
-
----
-
-## 必经规则摘要（防漏读）
-
-以下规则来自高频、高代价的按需文档，已内联到主流程。执行开发任务时即使没有单独打开最佳实践，也必须经过这组检查：
-
-- **意图先于实现**：新页面、新模块、新功能先判断“解决谁的什么问题”，再决定页面、DB、后台、权限和入口；不要直接从用户一句“做个页面”跳到资源创建。
-- **入口先于完成**：新增页面必须绑定导航栏、首页、后台菜单或相关页面按钮至少一处；用户明确要求隐藏页/草稿页时，完成说明和记录里写清原因。
-- **导航先复用基座**：顶部导航和管理端侧边栏优先读取并复刻/改造现有内置导航资源；若现有结构不适配，再调整方案。管理端侧边栏中的系统内置路由通常保留。
-- **系统页谨慎修改**：登录、设置、系统配置、权限、用户等内置系统页非必要不动；首页不是系统页，可按业务需求改造。
-- **导航状态要完整**：导航通常同时考虑未登录 / 已登录 / 管理员，以及收起 / 展开两种状态；普通用户不显示管理后台入口，管理员可额外看到后台入口。
-- **业务优先考虑管理闭环**：涉及案例、新闻、产品、订单、预约、资料等可维护业务内容时，优先考虑前台展示 + 管理端维护 + 同一份真实数据；确认不需要管理端时写明理由即可。
-- **业务后台按域拆分**：运营日常使用的后台能力优先落到业务域专页并注册到后台侧边栏；`/admin/db` 只保留底层通用数据能力，不默认承接日常运营。
-- **首页默认是门面**：首页通常承担官网介绍、品牌展示和入口聚合；只有用户明确要求“进入即使用”时，才把首页当工作台。
-- **路径地图优先闭环**：标准功能优先明确不同角色的站点地图和访问路径：用户从哪里进入、管理员从哪里维护、数据如何回到前台。
-- **规则先于动手**：开发对应页面、导航、DB、custom_script 或 AIHub 前，优先读本任务触发的规则/spec；不要完全凭记忆写平台语法。
-- **真实数据先于静态展示**：可维护业务内容优先用动态 DB；写 DB 前先读 `.draftgo/db_meta/index.json`，不要硬编码 type、字段或权限。
-- **状态先于视觉完整**：异步页面必须有加载态、空态、错误态、成功态；初始渲染不能空白。
-- **信封先于取值**：调用 DraftGo API 时先判断 `res.code !== 200`，再从 `res.data` 取载荷；列表/后台/大数据场景显式传 `page` + `page_size`。
-- **平台能力先于绕路**：优先动态 DB → custom_script；第三方请求在服务端通过 `ctx.HTTP` 发起，不要在页面里硬编码 API Key、Bearer、业务数据或伪交互。
-- **主题适配先于硬编码颜色**：默认用 `var(--dg-*)` 语义 token；自主配色必须同时考虑浅色与深色。
-- **证据先于完成声明**：没做文件回读、结构检查、API 回读、`draftgo check` 或与任务影响匹配的运行证据，不允许说完成。前端浏览器证据按影响选择，不是所有页面的固定门禁。
-
-若任务触发更具体规则，再读对应文件；这组摘要是主流程硬门，不依赖额外阅读。
-
----
-
-## 轻量任务识别与用户意图翻译
-
-不要把流程做成固定填表。开发前先用 AI 自身判断力做一次轻量识别：这次是小修、轻功能、标准功能，还是高风险系统改动。识别结果用于决定规划深度，不要求每次都输出模板。
-
-当用户用业务语言而不是开发术语描述需求时，先把它翻译成产品结果，再落到开发任务。判断顺序：
-
-1. 看业务对象：案例库、新闻中心、产品中心、服务体系、会员、订单、预约、招聘、资料下载等通常是模块或功能，不是一个孤立静态页。
-2. 看动作词：展示、查看、筛选、搜索、提交、预约、发布、管理、维护、新增、编辑、删除、审核、上下架等决定功能深度。
-3. 看使用角色：访客、普通用户、管理员、运营、审核员、客服、内部人员等决定是否需要前台 / 后台 / 权限。
-4. 看现有项目结构：已有导航、页面命名、db_meta、custom_scripts、角色体系和 Story 都是默认推断依据。
-
-进入陌生项目、资源关系不清、多页面任务或用户描述较模糊时，先运行 `draftgo map` 快速获得资源地图；目标文件明确的小修和局部改动可以跳过。`draftgo map --output json` 可用于机器读取，不替代具体文件阅读。
-
-### 新功能意图锚定
-
-当任务是新增页面、新模块、新后台能力或新业务流程时，先给出一句意图判断：
-
-```
-意图：给 <角色> 解决 <问题>，通过 <核心路径> 完成。
-```
-
-- 能从 Story、现有导航、页面命名、业务对象和用户措辞推断时，直接采用并记录。
-- 推断会明显改变页面数量、数据结构、后台能力或权限时，在轻量确认里前置追问。
-- 普通页面/轻功能不引入完整 PRD；只保留一句可执行的功能意图，作为后续设计和验收锚点。
-- 用户明确要“新系统 / 新板块 / 新模块 / 完整业务”时，进入下方“小 PRD 门”，把意图扩展为可执行页面清单和功能清单。
-
-默认策略：
-
-- 用户说“修改 / 调整 / 优化某个已存在页面” → 默认按单资源改动处理；范围清晰则小修，影响主流程则轻功能或标准功能。
-- 用户说“做 / 新建 / 增加一个页面” → 通常按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定，并优先考虑真实落地闭环、高可用。只有用户明确说“静态页 / 纯页面 / 静态稿 / demo / mock / 假数据 / 伪功能 / 先做效果”时，才允许按静态页面处理。
-- 用户说“做一个功能 / 模块 / 系统能力” → 默认按功能闭环处理，不能自动降级为单个展示页或前端假数据。
-- 用户说“做一个新系统 / 新板块 / 新模块 / 完整业务” → 通常先产出一份轻量 PRD 到 `.draftgo/Task/`，清点页面、功能、数据、管理端和入口，再开始实现。
-- 用户说“管理 / 维护 / 发布 / 审核 / 上下架” → 通常需要后台管理能力和真实数据闭环。
-- 用户说“案例 / 新闻 / 产品 / 订单 / 预约 / 招聘 / 资料下载”等业务内容 → 通常不只是单页面，要同时判断前台展示、后台维护、数据结构和权限。
-- 用户说“官网 / 官方 / 平台 / 系统” → 通常不要做孤立页面；至少考虑导航入口、访问路径和完整用户路径。
-- 用户说“新导航 / 重新做导航栏” → 通常先复制一份现有导航再改，不直接破坏内置导航；同时要考虑登录态、管理员态和收起/展开。
-
-只有当不确定点会明显改变页面数量、数据结构、后台能力、权限或风险时，才向用户确认。确认最多 1-3 个问题，并给出推荐默认值；其余细节由 AI 自主推断，并按任务等级记录到范围复述、内部短计划或 Task 中。
-
-### 用户路径链路（功能任务默认视角）
-
-规划功能时，不要只从“要创建几个页面”看问题，要从完整使用链路倒推资源：
-
-```
-用户打开官网 / 系统入口
-→ 在导航、首页模块、按钮或列表中看见入口
-→ 点击进入目标页面
-→ 浏览 / 搜索 / 筛选 / 查看详情 / 提交表单
-→ 获得成功、失败、空态、权限不足等反馈
-→ 管理员在后台维护同一份数据
-→ 前台再次读取到维护后的真实结果
-```
-
-按这条链路推断需要哪些页面、导航、数据、API、自定义脚本、权限和验证。链路里某一步走不通，就不能把功能声明为完成。
-
----
-
-### 新系统 / 新板块：小 PRD 门
-
-当用户要求开发一个“新的系统”“新的板块”“新的模块”“完整业务能力”，或需求明显包含多页面、多角色、多数据对象时，默认按标准功能或高风险处理，并先在 `.draftgo/Task/` 创建一份轻量 PRD。用户明确说“先做一个静态入口 / 只要单页效果 / 不要规划”时可降级，但要在完成说明里写清。
-
-小 PRD 的目标不是写长文档，而是让开发闭环可执行。内容应包括：
-
-```markdown
-# <系统/板块名> PRD
-
-## 1. 需求理解
-- 用户原话：
-- AI 意图推测：给 <角色> 解决 <问题>，通过 <核心路径> 完成
-- 范围边界：本次做 / 暂不做
-
-## 2. 角色与路径地图
-| 角色 | 入口 | 核心动作 | 结果反馈 |
-|---|---|---|---|
-| 前台用户 | 导航/首页/按钮 | 浏览/搜索/提交 | 看到结果/收到反馈 |
-| 管理员/运营 | 管理端菜单 | 新增/编辑/发布/审核 | 前台同步更新 |
-
-## 3. 页面清单
-| 页面 | 路由 | 面向角色 | 主要功能 | 入口绑定 | 数据来源 |
-|---|---|---|---|---|---|
-| 前台列表页 | /xxx | 用户 | 浏览/搜索/筛选 | 顶部导航/首页 | db:xxx |
-| 前台详情页 | /xxx/detail | 用户 | 查看详情/提交动作 | 列表页 | db:xxx |
-| 管理列表页 | /admin/xxx | 管理员 | 查询/新增/编辑/删除/发布 | 管理侧边栏 | db:xxx |
-
-## 4. 功能清单
-| 功能 | 页面/资源 | 真实行为 | 状态反馈 | 验收证据 |
-|---|---|---|---|---|
-| 搜索筛选 | 前台列表/管理列表 | 调真实 DB/API | 加载/空/错误/成功 | 文件回读 + API/check |
-
-## 5. 数据与权限
-- 动态 DB type：
-- 字段草案：
-- 权限/可见性：
-- 是否需要 custom_script / AIHub：
-
-## 6. 实施任务
-- [ ] T1. 创建/更新 DB meta
-- [ ] T2. 开发前台页面
-- [ ] T3. 开发管理端页面
-- [ ] T4. 更新导航/入口
-- [ ] T5. 验证、push、changelog
-```
-
-生成 PRD 后，通常不要停在文档。除非用户要求先审 PRD，否则继续把 PRD 拆成执行任务并开始开发。若 PRD 中存在会明显改变数据结构、权限、安全或页面数量的关键分叉，再做一次轻量确认。
-
----
-
-## 任务分级（先判级，再执行）
-
-### 小修
-
-**定义：** 范围明确、影响面单一、可在一个资源内完成的小改动。
-
-典型场景：
-- 修一个文字、链接、图标、按钮位置、样式小问题
-- 修一个明确报错或禁区违规（如 `window.location.search`、`App.confirm` 忘 `await`）
-- 调整单个页面的一处文案、颜色 token、空态展示
-- 对单个已知资源执行小范围补丁
-
-流程：
-```
-1. 定位：读目标 index / 文件，确认 resource id 与文件路径
-2. 改：只做最小必要改动
-3. 证据：用与改动匹配的轻量方式确认命中（文件回读 / 语法检查 / diff / 必要的本地检查）
-4. 交付：默认保留本地结果；用户明确要求 push/同步/部署，或必须上云才能完成真实闭环时再推送
-5. 记录：影响可见功能、已 push 或有接手价值时写 changelog
-```
-
-小修不需要 Story 门、需求门、Task 文档，也不需要并行分发。若执行中发现影响面扩大，立即升级为「轻功能」或「标准功能」。
-
-小修优先只读目标资源和最小必要规则；如果执行中发现命中平台禁区、需要新增入口、影响主流程或范围扩大，再补读对应规则并升级分级。
-
-### 轻功能
-
-**定义：** 有明确用户价值、需要真实交互或少量数据联动，但范围集中、资源少、风险低，不需要完整 Task 计划即可顺畅完成。
-
-典型场景：
-- 给现有页面新增一个筛选、提交、跳转、下载、状态反馈等小能力
-- 新增一个简单可用页面，并绑定一个入口
-- 单页面接入一份已有 DB / 自定义服务 / AIHub 能力
-- 补齐一个局部用户路径，但不涉及权限、账号、生产脚本或复杂数据结构
-
-流程：
-```
-1. 范围复述：一句话说明要做什么、入口在哪里、如何验证
-2. 直接做：读目标资源，按最小闭环实现
-3. 推送前只做本地静态/结构/资源检查
-4. 证据闭环：按影响补 check / changelog；用户明确要求云端生效时再 push
-```
-
-轻功能不强制创建 Task 文档，不强制 depends/resource_lock/wave，也不启用并行。若执行中发现需要多个页面协作、后台管理、复杂权限或资源冲突，升级为「标准功能」。
-
-### 标准功能
-
-**定义：** 新增或调整一个可感知的业务能力，需要多个步骤、多资源协作或较多用户体验判断，但不直接触碰权限、账号、生产脚本等高风险资源。
-
-典型场景：
-- 新建页面 / 改造页面主流程
-- 页面联动 DB / 自定义服务 / AIHub
-- 新增导航入口并配套页面
-- 新增普通文档、普通 db_meta、非敏感配置
-- 新系统 / 新板块 / 新模块的轻量 PRD + 页面与功能清单 + 多资源开发
-
-流程：
-```
-1. 若 .draftgo/story.yaml 存在，静默加载；不存在时不阻塞开发，完成后提醒补 Story
-2. 轻量确认：意图翻译 + 必要追问 + 范围复述
-3. 内部短计划：列清资源、入口、数据、关键交互和证据形式；新系统/新板块或跨资源、多页面协作、并行、高风险时创建 Task，并写入轻量 PRD
-4. 执行门：按短计划逐项实现
-5. 闭环门：证据 + 按影响选择 changelog / check；需要云端生效时显式 push；有 Task 时同步标记
-```
-
-标准功能任务最低规划要求：写清楚用户路径链路、页面入口/导航绑定、前台与后台是否需要同一份数据、哪些交互必须真实有效。业务模块通常优先列清关键角色路径（前台用户、管理员/运营，必要时再补审核员/客服），避免只做一个入口不闭环。不要把“页面看起来存在”当成“功能完成”。
-
-### 高风险
-
-**定义：** 可能影响权限、安全、账号、生产自动化、数据结构、已有关键业务流或系统定位的改动。
-
-典型场景：
-- roles / users / 权限策略 / 登录注册 / 支付 / 删除恢复
-- custom_scripts 启停、生产 route 脚本、scheduled 脚本
-- db_meta 结构性变更、批量数据修改、系统配置敏感项
-- 与 `.draftgo/story.yaml` 的 `identity.not` 或 active decision 冲突
-- 首页 `.draftgo/pages/page_1_root.html` 的整站门面重做（见 frontend.md 特例），或任何会改变产品第一印象的重设计
-
-流程：
-```
-1. Story 门：无 .draftgo/story.yaml 必须先构建；有则静默加载并做冲突检测
-2. 完整确认：挖透关键风险、边界和验收，复述确认后才动手
-3. 计划门：Task 文档 + 风险点 + 回滚/验证方案
-4. 执行门：轻量闭环执行；涉及 roles/users/custom_scripts 等资源时先完成本地结构和影响检查，需要云端生效时再按对应脚本推送
-5. 闭环门：真实验证证据 + 回读结果 + 影响范围说明；需要云端生效时补 push 输出
-```
-
----
-
-## Story 门（高风险必走，标准功能可加载）
-
-### 触发
-
-高风险任务必须静默检查 `.draftgo/story.yaml`。标准功能任务若文件存在则静默加载；不存在不阻塞开发。小修和轻功能不触发 Story 门。
-
-### 行为
-
-```
-├─ 文件存在 → 静默加载全文，Story 作为最高优先级上下文锚定 → 过门
-├─ 文件不存在且任务为高风险 → 暂存用户开发请求 → 进入 Story 构建流程
-│   ├─ 有页面/数据 → 路径 A（扫描推断 + 确认）
-│   └─ 空项目     → 路径 B（对话式采集）
-├─ 文件不存在且任务为标准功能 → 继续开发，收尾提醒补 Story
-└─ 构建完成后 → 回到用户原始请求 → 继续走轻量确认 / 完整确认
-```
-
-### Story 构建流程
-
-详见 `{{SKILL_DIR}}/story/SKILL.md`。
-
-### 运行时冲突检测
-
-整个对话过程中，Story 持续生效。当用户请求与 Story 的 `identity.not` 或 active 状态 `decisions` 冲突时：
-- 明确告知冲突点
-- 给出 A) 想法变了 / B) 双轨并行 / C) 只是特例 三个选项
-- 用户选择后更新或不更新 Story
-
-### 主动沉淀
-
-开发过程中检测到方向性决策（拒绝建议、方案选择、调性偏好），主动提议是否记入 `decisions`。
-
-### 红线
-
-- 高风险任务中 Story 门不可跳过、不可拖延
-- 标准功能任务允许先开发后提醒补 Story；小修和轻功能不需要 Story
-- Story 加载失败（yaml 格式损坏）时，尝试自动修复格式错误后继续；无法自动修复时提示用户并继续开发
-
----
-
-## 轻量确认（标准功能 / 高风险）
-
-### 触发
-
-任务分级为「标准功能」或「高风险」时进入确认。小修跳过确认，除非目标文件或验收条件不明确；轻功能只做简短范围复述，不进入完整确认门。
-
-### 标准功能任务：默认推断，少量确认
-
-> **标准功能任务的目标是让 AI 发挥判断力，而不是让用户填产品表。**
-> 先根据用户提示词、现有项目结构和用户路径链路推断合理实现范围；只有关键分叉会明显改变工作量或系统行为时才追问。
-
-必须主动推断：
-- 功能意图：解决谁的什么问题，是否面向前台用户、后台运营或内部人员
-- 这是改现有页面、新增单页面、新增多页面，还是完整功能模块
-- 用户从哪里进入：官网首页、导航栏、列表入口、按钮、后台菜单；若是导航改造，还要区分未登录、已登录、管理员三种可见性
-- 新页面是否要绑定到导航栏 / 首页入口 / 后台菜单 / 相关页面按钮
-- 是否需要前台展示、后台维护、真实数据读写、搜索筛选、详情页、表单提交
-- 是否存在权限、状态流转、上下架、审核等隐含操作
-
-确认规则：
-- 不要为了填满维度而追问；能从上下文合理推断的，直接采用并记录。
-- 只问会改变页面数量、数据结构、权限、后台能力、生产风险的问题。
-- 一次最多 1-3 个问题，必须带推荐默认值。
-- 用户说“你看着办 / 按你理解来 / 直接做”时，按推荐默认值继续，不要反复卡住。
-
-轻量确认写法：
-```
-我理解这是：<页面 / 多页面 / 功能模块>。
-意图是：给 <角色> 解决 <问题>。
-我会按 <推荐范围> 做：<前台入口 + 页面 + 数据 / 后台 / 绑定 / 验证摘要>。
-
-[如有关键分叉]有一个点会影响范围：
-A. <推荐方案>
-B. <更轻方案>
-C. <更完整方案>
-
-你选哪个？或者我理解错了？
-```
-
-### 高风险任务：完整确认
-
-高风险任务仍需更完整确认。按需挖透五维度，但仍然避免机械填表：
-
-```
-☐ 1. 要做什么（目标）
-☐ 2. 不做什么（边界）
-☐ 3. 成功长什么样（验收）
-☐ 4. 已知约束（用户角色 / 权限 / 数据结构 / 现有页面位置）
-☐ 5. 前端 UI 需求（如果用户明确提出）
-```
-
-**追问优先用多选题**，开放题作为兜底。
-
-### 范围复述
-
-```
-我理解你要：
-- 目标：...
-- 意图：解决什么问题，给谁用
-- 范围：在 ... 做 ...
-- 用户路径：从 ... 进入 → ... → ... → 得到 ...
-- 页面 / 入口绑定：...
-- 数据 / 后台：...
-- 不做：...
-- 验收：...
-- 约束 / 风险：...
-
-对吗？
-```
-
-标准功能任务：用户明确点头，或用户授权“按你理解做”，都算过门。
-高风险任务：必须明确点头（"对 / 可以 / 就这样 / 行 / OK"）才算过门；模糊回应要再追一次。
-
-### 红线
-
-- 轻功能 / 标准功能都禁止把用户的“页面”默认当成静态页；除非用户明确说静态 / 纯页面 / demo。
-- 没带推测的追问 = 失职；向非技术用户索要 CRUD、API、路由等术语 = 失职。
-- 高风险任务没复述确认前禁止写代码、写文档、开 Task。
-- 复述完，**之后不再回头打扰用户**（除非执行中遇到真正阻塞）。
-
----
-
-## 计划门（按需 Task / 高风险，一次性产出，不打扰用户）
-
-轻量确认过了之后，AI 先做**内部短计划**并直接执行；只有跨资源、多页面协作、并行开发、需要长期接手或高风险任务，才把设计 + 任务清单落到 `.draftgo/Task/` 文件夹。小修、轻功能和普通标准功能不创建 Task 文档。
-
-### Task 文件位置
-
-```
-<项目根>/.draftgo/
-├── changelog.md                     # 更新日志（单文件，按日期分节）
-├── lessons/                         # 开发经验与问题记录
-└── Task/                            # 任务清单
-    └── YYYY-MM-DD-<topic-slug>.md   # 每个开发任务一个文件
-```
-
-`/draftgo init` 会自动创建 `Task/` 目录。
-
-### Task 文件命名
-
-`YYYY-MM-DD-<topic-slug>.md`
-
-- topic-slug：英文小写 + 短横线连接，描述任务主题
-- 例：`2026-05-16-admin-users-export-button.md`
-
-### Task 文档模板
-
-````markdown
----
-date: YYYY-MM-DD
-status: in_progress       # in_progress | done | aborted
-topic: <一句话主题>
-related_changelog: YYYY-MM-DD
----
-
-# <主题>
-
-## 需求纪要（确认版）
-
-> 来自轻量确认 / 高风险确认的复述结果。**这段不再修改**。
-
-- 目标：...
-- 意图：解决什么问题，给谁用（一句话）
-- 范围：...
-- 用户路径：用户从 ... 进入 → 点击 ... → 完成 ... → 获得 ...
-- 页面 / 入口绑定：新增或修改的页面如何出现在导航栏、首页、后台菜单或相关页面按钮中
-- 数据 / 后台：前台展示与后台维护是否使用同一份真实数据
-- 不做：...
-- 验收：...
-- 约束：...
-- 前端 UI 需求：...
-
-## 设计
-
-**架构定位**：本次改动落在哪一层（壳层 / 页面 HTML / 导航栏 / 后端 API / 自定义脚本 / AIHub 资产 / 系统配置）。
-
-**涉及资源**：
-- 页面：`pages/<file>.html`（page_id=xx）
-- 导航：`navigations/<file>.html`（nav_id=xx）
-- db_meta / aihub / custom_scripts：...
-
-**链路流**：入口（官网 / 导航 / 后台菜单）→ 页面 → 操作 → 数据读写 → 反馈 → 后台维护 → 前台展示
-
-**绑定点**：
-- 导航栏 / 菜单：...
-- 首页 / 列表 / 详情 / 按钮入口：...
-- 路由与 page_id 对应：...
-
-**四态考虑**（前端任务必填，后端可省）：
-- 空态（无数据时）：...
-- 加载态（请求中）：...
-- 错误态（请求失败 / 权限不足 / 校验失败）：...
-- 成功态（成功反馈方式）：...
-
-## 任务清单
-
-- [ ] T1. <任务名>  ⬜
-  - 类型：本地改文件 / 调 API / push / 自定义脚本执行
-  - 文件：`.draftgo/pages/admin-users.html`
-  - 步骤：
-    1. 读取当前文件，定位 X
-    2. 在 Y 位置插入 Z
-    3. 推送前只做本地静态/结构/资源检查：文件回读 / draftgo check
-    4. 用户要求同步/部署或必须云端生效时，调 push 脚本：`python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>`
-    5. 需要接手记录时写更新日志
-  - 验证证据：文件回读 / check / 必要的运行证据；需要云端生效时补 push 输出
-
-- [ ] T2. ... ⬜
-
-## 进度总览
-
-| 任务 | 状态 | 完成时间 | 证据摘要 |
-|-----|------|---------|---------|
-| T1  | ⬜   |         |         |
-| T2  | ⬜   |         |         |
-
-## 完成回顾（全部 ✅ 后填）
-
-- 实际改动：...
-- 偏离计划的地方：...
-- 后续 TODO：...
-````
-
-### 标记五态
-
-```
-⬜ 未开始    🟡 进行中    ✅ 已完成    ❌ 失败    ⏸ 暂停
-```
-
-每完成一个任务**立即两处更新**：
-1. 任务行 `- [ ]` → `- [x]`，状态 ⬜ → ✅
-2. 进度总览表的"完成时间"和"证据摘要"
-
-### 依赖分析与并行规划（按需）
-
-当 Task 清单涉及 3 个及以上任务、多个资源可能并行修改，或准备启用子代理时，为相关任务标注 `depends`、`resource_lock` 和 `wave`：
-
-```markdown
-- [ ] T1. 描述  ⬜
-  - depends: []
-  - resource_lock: pages/admin-users.html
-  - wave: 1
-```
-
-**规则**：
-- `depends: []` = 无依赖，可与其他无依赖任务并行
-- `depends: [T1, T3]` = 必须等 T1、T3 完成后才能开始
-- `resource_lock` = 该任务要修改的文件，同一 resource_lock 的任务不可并行
-- `wave` = 并行批次编号，无依赖任务为 Wave 1，依赖 Wave 1 的为 Wave 2，以此类推
-
-**依赖判定**：同一文件 → 依赖；数据依赖（需要前序产出）→ 依赖；不同文件且无数据关联 → 独立。
-
-单人串行或 1-2 个任务的小计划，不强制填写这些字段；只需写清目标、文件、步骤和验证证据。
-
-详细分发协议见 `{{SKILL_DIR}}/rules/parallel.md`。
-
-### 计划门红线
-
-- 计划禁止占位符：TBD / TODO / "类似 T2" / "做适当处理" / "加错误处理"。
-- 每个任务必须给：精确文件路径、操作类型、可执行步骤、本地检查证据形式。
-- 多任务 / 多代理 / 多资源冲突时必须给：`depends` + `resource_lock` + `wave` 三个字段；单人串行小计划不强制。
-- 新增页面必须有绑定任务或明确说明为什么不需要入口；默认应绑定到导航栏、首页、后台菜单或相关页面按钮之一。
-- 计划写完跑一次自审：**需求纪要每一条、用户路径每一步、页面绑定每一处能不能指到某个任务？** 不能就补任务。
-- 不需要再让用户确认（确认阶段已经定范围）。
-
----
-
-## 执行节奏（轻量闭环）
-
-DraftGo 主要场景是**改 HTML 页面、改导航、调 App API、写 custom_script**。执行时保持小步、可理解、有证据：
-
-```
-Small    小步实现，一次只动清楚的一件事
-Evidence 用文件回读 / check / 与改动匹配的轻量证据确认
-Record   按影响选择 changelog / Task 标记，需要云端生效时显式 push
-```
-
-### 并行分发（Wave 模式）
-
-当任务数 ≥ 3、存在多个 Wave 1 任务（`depends: []` 且 resource_lock 不冲突）、任务边界清晰，且并行收益大于协调成本时，主代理可启用并行：
-
-1. **分发**：为每个 Wave 1 任务生成子代理，携带上下文包（task 定义 + 当前文件 + 禁区摘要）
-2. **子代理执行**：每个子代理独立完成小步实现和证据确认，产出修改文件 + 验证报告；需要接手记录时再产出 changelog 条目
-3. **收集**：主代理收集所有子代理产出，写入文件系统
-4. **批量推送**：用户要求同步/部署或任务必须云端生效时，验证通过后运行 `python {{SKILL_SCRIPTS}}/draftgo_push.py --batch <type1> <id1>,<id2> <type2> <id3>`
-5. **Wave 2**：依赖已完成的任务可以开始，重复上述流程
-6. **闭环**：主代理统一汇总证据；有 Task 文档时再更新标记
-
-**退化条件**：平台不支持子代理 / 任务数不足 / 边界不清 / 协调成本更高 / 用户明确说"串行" → 静默退化为逐任务串行。
-
-详细协议见 `{{SKILL_DIR}}/rules/parallel.md`。
-
-### 每个任务的轻量执行
-
-```
-1. 读 —— 读当前文件状态，理解现状（不读不改）
-        • 资源关系不清 / 陌生项目 / 多页面任务：先跑 `draftgo map`
-        • 涉及页面闭环：读取 pages/index.json、navigations/index.json 和相关 HTML
-2. 改 —— 做最小必要改动，不顺手改无关代码
-3. 证 —— 用与改动匹配的轻量证据确认：
-        • 页面类：文件回读、入口引用、状态结构、关键交互代码路径
-        • API 类：用 `fetch('/api/x/<slug>/...')` / Python urllib / 服务 route 端点真实跑一次
-                  （Windows 环境下 curl 对中文/特殊字符编码易出错，建议优先用 Python urllib/requests）
-        • custom_script：用 POST /api/scripts/{id}/execute 跑一遍
-        • db_meta / aihub：注册或更新后用 GET 回读字段
-4. 录 —— 影响可见功能、跨资源、已 push 或需接手时写更新日志到 .draftgo/changelog.md
-        格式：- [HH:MM] [操作类型] 描述（不超过 30 字）
-5. 交付 —— 默认完成本地静态/结构/资源检查后，运行 `draftgo auto-push [type] [id...]`。该命令只在 `.draftgo/config.json` 的 `auto_push` 严格为 `true` 时执行 `check → push`；开关关闭或未设置时，返回“已验证、未推送”，不修改云端。用户明确要求 push/同步/部署，或资源必须上云才能完成真实闭环时，优先运行 `draftgo deploy`（自动执行 check → push，check 不通过则终止）；预演用 `draftgo deploy --delivery preview`，只做本地门禁用 `draftgo deploy --delivery local`。若只需推特定资源类型，再按资源类型调对应 push 脚本。
-6. 标 —— 有 Task 文档时把对应任务勾掉并记录证据摘要；没有 Task 文档则不补建
-```
-
-### 分段实现原则
-
-复杂或高风险代码应分段实现并验证；不要一次性写入难以检查的大块代码。
-
-1. 按功能模块或逻辑段落拆分，优先保持每段可理解、可验证
-2. 大段 HTML/CSS/JS 写入后及时做语法、结构或静态检查
-3. 批次间保持上下文连贯（闭合标签、函数结尾等不可跨批断开）
-
-**原则**：分段是为了降低错误率，不是为了机械限制行数；清晰、完整、可验证优先。
-
-### DB 操作前置门（强制）
-
-当改动涉及动态数据库（`App.get('db/...')`、`App.post('db/...')`、DB 列表页、DB 表单页）时：
-
-1. **强制先读** `.draftgo/db_meta/index.json` 中对应 type 的 schema
-2. 字段名、字段类型、是否必填 **以 schema 为准**，不凭印象写
-3. 要对某字段做检索/筛选（`filters`）或排序（`order_by`）前，先确认该字段在 schema 里标了 `searchable`，且操作符匹配其检索模式（`exact`→eq/in，`fuzzy`→eq/like/in，`range`→eq/gte/lte/gt/lt/in，`contains`→contains）；未标 searchable 或操作符不匹配后端返回 400
-4. 如果 `db_meta/index.json` 不存在或对应 type 缺失，先 `/draftgo pull db_meta` 刷新
-
-违反后果：字段名写错 → 数据静默丢失 → 排查成本极高。
-
-### custom_script 契约前置门（强制）
-
-当前端要对接某个 custom_script 的 route 端点（`fetch('/api/x/<slug>/...')`、DB 列表/表单页依赖某脚本的读写接口）时，优先以云端正在运行的脚本为准，本地 `code_file` 可能落后于云端：
-
-1. **对接前强制确认"本地 = 云端"**：先 `python {{SKILL_SCRIPTS}}/draftgo_pull.py custom_scripts <id>` 拉云端运行版，或直接探测关键端点（如目标端点返回 404 即说明云端没有该 route）。两者一致才可按本地契约写前端。
-2. **本地领先时先推后接**：若本地脚本已演进但尚未上云，必须先完成推送，不得对着"未上云的本地契约"写前端。
-3. **跳过推送必须留痕**：任何一次跳过 custom_scripts 推送，都要在 changelog 或 Task 里写明"本地脚本 vN 未上云"，避免后续 AI 误判已生效。
-4. **Register 是唯一触发来源**：同一 Go custom service 可用 `app.Route` / `app.On` / `app.Schedule` 声明多个触发器；旧 `triggers` 元数据不参与注册，CLI 不创建也不推送。
-5. **route 端点设计约束**：Go custom service 的 Route 输入位于 `draftgo.Input`（`body`、`query_params`、`headers`、`method`、`path_params`）；`path_params` 只包含 catch-all 的 `{slug, path}`，不会从 route 字符串中解析 `{id}`/`{uid}`。普通身份用 `draftgo.Auth.CurrentUser()`；需要 id 的写操作通过 query/body 传入，不要写 `app.Route("DELETE", "/xxx/{id}", handler)`。
-6. **管理员 SDK 调用契约**：管理员服务要访问管理员资源时，代码逐次显式调用 `draftgo.Admin.*`，例如 `draftgo.Admin.DB.Query(...)`；不添加 `admin_access` 配置，不传 SAT。普通 `draftgo.DB` 调用不自动提权。推送后必须回读一次执行详情，确认 `Admin SDK call` 审计存在。
-6. **权限分层**：`scripts:*` 只控制谁能管理服务；Route 的 `permission` / `route_security` 仍单独控制谁能调用。管理角色不能据此绕过调用权限，也不要因调用范围受限就把代码编辑权授给不可信角色。
-
-违反后果：本地脚本 ≠ 云端运行版 → 前端对错契约 → 列表恒空 / 写读两套存储，排查极隐蔽。
-
-### 执行禁区（继承现有规则）
-
-以下规则在根 [SKILL.md](../SKILL.md) "开发禁区"和 [frontend.md](./frontend.md) 中已有定义，执行时**全部生效**：
-
-- ❌ 境外 CDN（googleapis / jsdelivr / cdnjs / unpkg）
-- ❌ `App()` 写法（App 是对象不是函数）
-- ❌ `const App = () => window.parent?.App`（去掉箭头函数）
-- ❌ `window.location.search` 读参数（用 `window.__DG_ROUTE_CONTEXT__.query`）
-- ❌ `App?.user?.role` 判断管理员（用 `App.isAdmin` 或 `App.currentUser?.role_code`）
-- ❌ `navigate('/login')` 退出（用 `window.location.href = '/login'`）
-- ❌ `window.alert / confirm / prompt`（用 `App.toast / confirm / showModal`）
-- ❌ 只按当前主题硬编码颜色（优先用系统 `var(--dg-*)` token；自主配色必须兼容浅色与深色）
-- ❌ `App.confirm` 不 `await`（详见 [debugging-syntax.md](./debugging-syntax.md) 第 3 条）
-- ❌ `await` 用在非 `async` 函数里（详见 [debugging-syntax.md](./debugging-syntax.md) 第 2 条）
-- ❌ Go custom service 里写 `app.Route("DELETE", "/x/{id}", handler)` 并期待 `ctx.Input["path_params"]["id"]`（`path_params` 只有 `slug/path`，ID 应走 query/body）
-- ❌ 对着未上云的本地 custom_script 契约写前端（先 pull/探测确认本地=云端，见上「custom_script 契约前置门」）
-
-### 调试方法论（升级 debugging-syntax.md 的清单为方法论）
-
-[debugging-syntax.md](./debugging-syntax.md) 是症状清单，本规范补方法论：
-
-```
-取证 → 模式 → 假设 → 修复
-```
-
-1. **取证**：先看文件回读、`.draftgo/changelog.md`、`draftgo check`、API 回读或 push 输出中最贴近问题的证据。**先取证再判断**，禁止靠猜。
-2. **模式**：对照 [debugging-syntax.md](./debugging-syntax.md) 10 大致命缺陷清单。九成"页面静默失效"都在里面。
-3. **假设**：一次只验证一个假设。在关键路径加 `console.log('=== A 点 ===')` 二分定位。
-4. **修复**：修根因，不修表面。改完用与改动匹配的轻量证据确认。
-5. **修复卡住时**：判断是否为基座问题——**基座 bug / 基座局限**：写入 `.draftgo/lessons/`，用最小临时方案绕过，与用户说明；**非基座问题**：继续尝试修复，确实无法修复时再写经验记录并说明阻塞点。
-
----
-
-## 闭环门（无证据不许说完）
-
-### 完成铁律
-
-```
-没看到证据 → 禁止说"完成 / 通过 / 应该 OK / 搞定 / Done / Perfect"。
-```
-
-### 各资源类型的"完成证据"
-
-先做本地静态/结构/资源检查；是否增加浏览器、API 或云端证据由改动影响决定。
-
-- 小修：文件回读确认改动点命中；需要云端生效时再补 push 输出。
-- 轻功能：文件回读、入口引用检查、`draftgo check`；需要云端生效时补 push 输出。
-- 标准功能：文件回读、入口/资源结构检查、`draftgo check`、必要的数据回读；按任务要求补 push 输出和 changelog。
-- 高风险：在标准功能基础上增加影响范围说明、回读验证和回滚 / 兜底方案。
-
-| 资源类型 | 完成证据 |
-|---------|---------|
-| 页面 HTML | 文件回读、入口引用、`draftgo check`；涉及真实运行或布局时再补 `draftgo verify-ui`，需要云端生效时补 push 输出 |
-| 新增页面 / 多页面功能 | ① 页面资源创建或更新成功 ② route 与 page_id 对应 ③ 导航栏 / 首页 / 后台菜单 / 相关页面按钮至少一个入口已绑定 ④ 文件回读或 `draftgo check` 可确认入口引用 ⑤ 关联页面互跳关系清楚 ⑥ 按交付要求决定是否 push |
-| 导航栏 | ① 文件回读确认新链接存在 ② 链接含正确 `data-page-route` ③ 按交付要求决定是否 push |
-| custom_script | ① 在可用环境执行目标 route/execute ② 返回值符合预期 ③ 使用 `draftgo.Admin.*` 时回读执行详情并确认 `Admin SDK call` 审计 ④ 需要云端生效时补 push 输出 |
-| db_meta / aihub / 系统配置 | ① 本地结构或 GET 回读字段对得上 ② 需要云端生效时补 push 输出 |
-| roles / users | ① 影响范围告知用户 ② 用户要求同步时补 push 输出 |
-| 文档 / 文档分类 | ① 文件与元数据回读字段对得上 ② 用户要求同步时补 push 输出 |
-
-### 用户路径回放（轻功能 / 标准功能 / 高风险）
-
-轻功能、标准功能和高风险任务完成前，按本次范围回放用户路径链路：
-
-```
-入口出现 → 点击进入 → 页面加载 → 操作有效 → 反馈明确 → 数据可回读 → 后台可维护（如需要）→ 前台展示更新
-```
-
-如果新页面没有任何导航栏、首页模块、后台菜单或相关页面按钮引用，视为未完成。若任务明确要求“只创建未公开页面”，必须在完成声明中说明该页面暂不绑定导航的原因。
-
-### CLI 闭环体检
-
-涉及页面、导航、DB、脚本或 AIHub 的任务，可按影响运行：
-
-```bash
-draftgo check
-```
-
-- 有 `错误`：与本次改动相关时先修复，不得声明完成。
-- 有 `提醒`：结合任务判断。若是未绑定入口、疑似 mock 数据、缺少真实调用，优先补齐；若是用户明确要求隐藏页 / demo，需在 changelog、Task 或完成说明中写明原因。
-- 需要把提醒也作为失败处理时运行 `draftgo check --strict`。
-
-`draftgo check` 只做本地启发式检查；结合文件回读、静态检查和必要的 API/运行证据形成证据。浏览器验证优先用 `draftgo verify-ui`，不要默认使用 computer use；截图默认只在失败时生成。
-
-### 禁用措辞
-
-- "应该 / 可能 / 看起来 / 大概 / Perfect / Done / 搞定 / 好了 / OK 了"
-- 任何隐含成功但没附证据的句子
-
-### 完成声明附证据
-
-- 命令 / 操作名（哪个文件回读 / 哪个 check / 哪个 push / 哪个 API）
-- 真实输出摘要（HTTP code、关键日志行、计数）
-- 有 Task 文档时说明更新到哪些 ✅；无 Task 文档时不需要补说明
-
-**示例（正确）**：
-> T2 完成。文件回读确认导出按钮绑定 `handleExport()`；`POST /api/scripts/7/execute` 返回 200，CSV 生成 89 行；`python draftgo_push.py pages 123` 返回 `OK pages/123`。Task 文档 T2 已 ✅。
-
-**示例（错误）**：
-> 导出按钮做好了，应该没问题，push 也跑了，你试试看。
-
-### 收尾动作（有 Task 文档时）
-
-1. 把 Task 文档 frontmatter 的 `status` 改为 `done`
-2. 填写"完成回顾"段（实际改动、偏离计划处、后续 TODO）
-3. 需要接手记录时在 changelog.md 写一条总结：`- [HH:MM] [完成] <主题>，详见 Task/<file>.md`
-4. 文件原地归档，不要移动
-
----
-
-## 与现有规则的关系
-
-| 现有规则 | 本规范如何对接 |
-|---------|---------------|
-| 根 [SKILL.md](../SKILL.md) "开发分级" | 本规范提供小修 / 轻功能 / 标准功能 / 高风险分级与执行依据 |
-| 根 [SKILL.md](../SKILL.md) "命令路由" | 增加触发：开发任务前先进本规范做任务分级 |
-| 根 [SKILL.md](../SKILL.md) "开发禁区" / "App API" / "数据库 Schema" / "API 速查" | 继续生效，执行证据依赖它们 |
-| [frontend.md](./frontend.md) | 继续生效，提供 DraftGo 前端运行时、资源、数据、路由、入口绑定和验证方法 |
-| [debugging-syntax.md](./debugging-syntax.md) | 继续生效，本规范第 3 章"调试方法论"在其之上加方法论 |
-| 迭代记录规范（根 SKILL "迭代记录规范"段） | 按影响选择复用 |
-| 错误日志规范（根 SKILL "错误日志规范"段） | 取证阶段复用 |
-| 经验记录规范（根 SKILL "经验记录规范（lessons）"段） | 第 3 章"修复卡住时"逻辑写入 `.draftgo/lessons/`，含基座 bug 与基座局限场景 |
-| 同步规范（根 SKILL "推送规范"段） | 开发任务收尾默认复用 |
-
----
-
-## 一句话总结
-
-> **先分级：小修直接定位改完给轻量证据；轻功能范围复述后直接做；标准功能轻量确认后用内部短计划执行；高风险走完整 Story / 计划 / 验证 / 回读证据。前端 UI 交给本地 Skills，DraftGo 质量靠真实链路和轻量证据。追问必带推测意图，新增页面必须绑定真实入口。**