draftgo-cli 3.0.29 → 3.0.33

package/resources/skill/{rules → references}/frontend.md

@@ -8,13 +8,11 @@ version: 2.0.0
 
 > 根 `SKILL.md` 是完整核心规则源；本文件只展开前端实现方法。若表述冲突，以根 `SKILL.md` 为准，不额外叠加固定验收动作。
 
-> 本文件只规定前端**操作性规则**，已剥离的内容见：  
-> 架构原理 → `{{SKILL_DIR}}/core/architecture.md`  
-> App API / Token / 路由 / 运行时 → `{{SKILL_DIR}}/specs/runtime.md` · `{{SKILL_DIR}}/quickref/app-api.md`  
-> 动态 DB / filters → `{{SKILL_DIR}}/specs/data.md`  
-> 开发禁区 → `{{SKILL_DIR}}/specs/security.md`
-
-新建/重做前端界面、明显 UI 设计任务或需要整体视觉判断时，若本地 Agent 存在前端 UI Skills，优先调用；小修、文案、链接、局部样式调整不必调用。
+> 本文件只规定前端**操作性规则**，已剥离的内容见：
+> 架构原理 → `{{SKILL_DIR}}/references/architecture.md`
+> App API / Token / 路由 / 运行时 → `{{SKILL_DIR}}/references/runtime.md` · `{{SKILL_DIR}}/references/app-api.md`
+> 动态 DB / filters → `{{SKILL_DIR}}/references/data.md`
+> 开发禁区 → `{{SKILL_DIR}}/references/security.md`
 
 ---
 
@@ -321,7 +319,7 @@ antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"
 - 导航栏通常要同时考虑未登录 / 已登录 / 管理员三种状态，以及收起 / 展开状态；普通用户不显示管理后台入口，管理员额外显示管理后台入口。
 - 管理端侧边栏通常基于现有内置侧边栏修改，新增业务管理路由优先追加或局部调整；删除系统内置页面入口前先确认影响。
 - 业务页面内可以做局部二级导航或侧边栏，但必须考虑外部导航已存在且可单独配置，避免重复渲染全局导航。
-- 系统内置页面通常不改；确需修改登录、设置、权限、用户、系统配置等页面时，按高风险任务处理并保留管理员功能。
+- 系统内置页面通常不改；确需修改登录、设置、权限、用户、系统配置等页面时，先说明影响、验证方式和保留的管理员能力。
 - 页面风格不要照搬管理侧内置页面；业务前台按业务用户和品牌语境设计，管理侧按操作效率和信息密度设计。
 
 ### 新增页面绑定（强制）
@@ -384,6 +382,7 @@ antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"
 | `/assets/vendor/prism/prism.min.js` | 轻量代码高亮（Prism.js） |
 | `/assets/vendor/dompurify/purify.min.js` | HTML 净化，渲染用户输入前必须过一遍 |
 | `/assets/vendor/html2canvas/html2canvas.min.js` | html2canvas 1.4.1，页面截图 / DOM 导出图片 |
+| `/assets/draftgo-chat.js` | DraftGo Chat SDK 完整版，注册 `<dg-chat>` 与 `DraftGoChat` |
 | `/assets/vendor/gsap/gsap.min.js` | GSAP 核心（先于其他 GSAP 插件加载） |
 | `/assets/vendor/gsap/ScrollTrigger.min.js` | GSAP ScrollTrigger |
 | `/assets/vendor/gsap/ScrollToPlugin.min.js` | GSAP ScrollTo |
@@ -421,6 +420,8 @@ AI 模型 / Provider 品牌图标可以使用 LobeHub 静态图标的 npmmirror
 
 Ant Design 5.29.3 已内置为 UMD 包（`window.antd`），可优先选择使用。
 
+> `Segmented` 的默认样式视觉厚重、组件库感过强，禁止原样用于成品界面；优先根据语义改用 `Tabs`、`Radio.Group` 等更合适的控件，确需使用时必须通过 `ConfigProvider`、design token 或组件公开 API 调整为与页面一致的轻量样式。
+
 ### ① 依赖加载顺序（缺一不可，顺序不可乱）
 
 ```html
@@ -697,18 +698,47 @@ App.setColorScheme('deep-blue-white');
 
 ## AIHub 页面 SDK
 
+新页面需要 AI 对话 UI 时，加载完整版脚本并使用原生 `<dg-chat>`：
+
+```html
+<script src="/assets/draftgo-chat.js"></script>
+<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
+```
+
+需要动态创建时使用 `DraftGoChat.create()`：
+
 ```javascript
-// 聊天
+const chat = DraftGoChat.create('#chat-host', {
+  protocol: 'draftgo-agent',
+  agentId,
+  surface: 'inline',
+  view: 'conversation'
+});
+```
+
+完整配置、协议、事件、历史、扩展与安全约束见 `references/chat-sdk.md`。
+
+`DraftGoAI` 是同一脚本提供的旧代码兼容门面，只用于没有对话 UI 的轻量调用或图片生成：
+
+```javascript
+// 聊天（默认流式；onDelta(delta, full) 每个增量触发，Promise resolve 完整文本）
 const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
 
+// 多轮：传 sessionId 复用会话（→ body.session_id）；Agent 开启“持续对话”后服务端续写历史。不传 = 无状态单轮
+await DraftGoAI.chat(agentId, '接着上一条', handler, { sessionId: threadKey });
+
 // 图片生成（必须用 /images 接口，不要用 /chat）
 const result = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
 
 // 用户选模型
 const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
-await DraftGoAI.chat(agentId, '你好', handler, { model: selectedModel });
+await DraftGoAI.chat(agentId, '你好', handler, { model: selectedModel, sessionId: threadKey });
 ```
 
+- 使用 `DraftGoAI` 前同样必须先加载 `/assets/draftgo-chat.js`；壳层不会默认注入。
+- `DraftGoAI.chat` 内部创建隐藏 `<dg-chat>`，始终流式。新页面的可见对话、附件、模型选择器、推理、历史和重生成直接使用 `<dg-chat>`。
+- Agent 的能力与 `spec` 字段（工具/子智能体/记忆/结构化输出/多模态/持续对话/ttft failover）见 `references/aihub.md`。
+
 ---
 
 ## 退出登录
@@ -755,4 +785,4 @@ const dbRes = await App.get('db/order', params);
 const q = (window.__DG_ROUTE_CONTEXT__ || window.__DG_GET_ROUTE_CONTEXT__?.() || App?.getCurrentRouteContext?.() || { query: {} }).query;
 ```
 
-完整 API 表 → `{{SKILL_DIR}}/quickref/app-api.md`
+完整 API 表 → `{{SKILL_DIR}}/references/app-api.md`

package/resources/skill/{core → references}/modules.md

@@ -12,7 +12,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 | 导航栏 | 数据库 HTML（`navigation.html`） | `.draftgo/navigations/` |
 | 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | `.draftgo/db_meta/` |
 | 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | `.draftgo/custom_scripts/` |
-| AIHub | 配置 AI Agent，页面调用 `DraftGoAI.chat/images` | `.draftgo/aihub/` |
+| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | `.draftgo/aihub/` |
 | 文档中心 | Markdown 文章 + 分类树 | `.draftgo/docs/articles/` |
 | 系统配置 | KV 存储，含全局前端层槽位 | `.draftgo/system_config/` |
 
@@ -35,11 +35,13 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
   → 仅需 KV → sys_config（category 自定义）
 
 要调用 AI？
-  → 聊天/问答 → AIHub + DraftGoAI.chat()
+  → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
+  → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
   → 图片生成 → AIHub + DraftGoAI.images()
+  → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
 
 要调用第三方服务？
-  → 自定义服务（用 `ctx.HTTP` 请求；需要时可用 route/event/scheduled 加工）
+  → 自定义服务（用 `draftgo.HTTP` 请求；需要时可用 route/event/scheduled 加工）
 
 要展示内容文档？
   → 文档中心（Markdown + 分类树）
@@ -53,7 +55,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 
 ## 自定义服务边界
 
-- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、ctx 和 SDK 契约见 `specs/custom-services.md`。
+- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
 - `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，推送后要真实请求验证。
 - `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
 - `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
@@ -61,4 +63,4 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 - 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
 - Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
 - 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
-- 脚本内读动态 DB 用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `specs/custom-services.md`。
+- 脚本内读动态 DB 用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。

package/resources/skill/references/parallel.md

@@ -0,0 +1,48 @@
+# DraftGo 并行执行
+
+## 资源依赖
+
+先为每个工作单元记录：
+
+- `depends`：开始前必须完成的工作单元。
+- `resource_lock`：本单元会修改的文件或 DraftGo 资源。
+- `evidence`：完成后返回的验证证据。
+
+按以下关系建立依赖：
+
+| 资源关系 | 执行顺序 |
+|---|---|
+| 多个实现依赖同一 schema、API、权限或路由 | 先确定共享契约，再并行实现消费者。 |
+| 两个工作单元修改同一文件或资源 | 合并为一个单元，或安排到连续 wave。 |
+| 页面与对应导航入口 | 页面 route 确定后接入导航。 |
+| 不同文件且没有数据或接口依赖 | 放入同一 wave 并行执行。 |
+
+## 工作单元
+
+分发内容包括：
+
+```yaml
+objective: 要完成的结果
+inputs: 当前资源和共享契约
+resource_lock: [允许修改的文件或资源]
+evidence: 返回的检查或运行证据
+delivery_owner: main
+```
+
+工作单元返回修改结果、验证证据和阻塞信息。主代理维护共享契约、推进 wave、汇总资源并执行交付。
+
+## Wave 执行
+
+1. 确定 schema、服务端点、权限、route 和导航结构等共享契约。
+2. 将 `depends` 已满足且 `resource_lock` 不冲突的工作单元放入同一 wave。
+3. 并行执行当前 wave，汇总后回读所有变更资源。
+4. 处理接口接线和入口绑定，再启动依赖已满足的下一 wave。
+5. 统一运行 `draftgo check`、必要的 API/UI 验证，并按交付意图执行批量推送。
+
+某个工作单元失败时，其依赖项等待处理；其余独立分支继续汇总。发现资源锁冲突时，将冲突单元合并或移到后续 wave。
+
+批量交付示例：
+
+```bash
+draftgo auto-push --batch pages 1,2,3 nav 4 custom_scripts 7
+```

package/resources/skill/{specs → references}/runtime.md

@@ -36,7 +36,7 @@ read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问
 
 `app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
 
-完整 API 见 `{{SKILL_DIR}}/quickref/app-api.md`
+完整 API 见 `{{SKILL_DIR}}/references/app-api.md`
 
 ---
 

package/resources/skill/scripts/draftgo_push.py

@@ -17,13 +17,14 @@ DraftGo Push Script
   python draftgo_push.py roles           [role_id ...]
   python draftgo_push.py users           [user_id ...]
 """
-import json, sys, re
+import json, sys, re, datetime
 from pathlib import Path
 import urllib.request, urllib.error
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 PROBE_ROUTES = False
 DRY_RUN = False
+RUN_FAILURES = 0
 
 
 def find_project_root(start: Path) -> Path:
@@ -67,7 +68,9 @@ def _lessons_reminder(cfg):
     print("  未命中则跳过。")
 
 
-def api_call(method, server, token, path, body=None):
+def api_call(method, server, token, path, body=None, acceptable_errors=()):
+    """发起 API 调用，并记录调用方不会恢复的失败。"""
+    global RUN_FAILURES
     data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
     headers = {
         "Authorization": f"Bearer {token}",
@@ -89,8 +92,12 @@ def api_call(method, server, token, path, body=None):
         with urllib.request.urlopen(req, timeout=15) as r:
             return True, r.status, r.read().decode("utf-8", errors="replace")
     except urllib.error.HTTPError as e:
-        return False, e.code, e.read().decode(errors="replace")
+        body_text = e.read().decode(errors="replace")
+        if e.code not in acceptable_errors:
+            RUN_FAILURES += 1
+        return False, e.code, body_text
     except Exception as e:
+        RUN_FAILURES += 1
         return False, None, str(e)
 
 
@@ -201,6 +208,57 @@ def _response_items(body):
     return []
 
 
+def _response_item(body):
+    """解析单资源响应的统一信封。"""
+    try:
+        raw = json.loads(body)
+    except Exception:
+        return None
+    if isinstance(raw, dict) and "data" in raw:
+        raw = raw["data"]
+    return raw if isinstance(raw, dict) else None
+
+
+def _cloud_version_allows_push(server, token, path, local_item, label):
+    """云端优先：本地 pull 基线落后于云端时禁止静默覆盖。
+
+    没有历史 updated_at 的旧缓存保持兼容；404 由调用方按默认重建策略处理。
+    """
+    global RUN_FAILURES
+    baseline = local_item.get("updated_at")
+    if not baseline:
+        return True
+    ok, status, body = api_call("GET", server, token, path, acceptable_errors=(404,))
+    if not ok and status == 404:
+        return True
+    if not ok:
+        return False
+    remote = _response_item(body)
+    remote_updated = remote.get("updated_at") if remote else None
+    if remote_updated and str(remote_updated) != str(baseline):
+        RUN_FAILURES += 1
+        conflict_dir = DEFAULT_ROOT / ".draftgo" / "sync-conflicts"
+        conflict_dir.mkdir(parents=True, exist_ok=True)
+        identity = str(local_item.get("id") or label).replace("/", "_").replace("\\", "_")
+        stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        conflict_path = conflict_dir / f"{identity}-{stamp}.json"
+        conflict_path.write_text(json.dumps({
+            "kind": "remote-newer",
+            "resource_path": path,
+            "baseline_updated_at": baseline,
+            "remote_updated_at": remote_updated,
+            "local": local_item,
+            "remote": remote,
+        }, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+        print(
+            f"  ERR [{label}] 云端版本已变化（local={baseline}, remote={remote_updated}）；"
+            f"云端优先，已保存冲突快照：{conflict_path.relative_to(DEFAULT_ROOT)}。",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
 def _recover_missing_index_entries(
     server, token, items, ids, id_key, type_name, rel_index, endpoint,
     file_spec=None, drop_fields=(),
@@ -359,7 +417,9 @@ def sync_pages(server, token, ids=None):
             "value": {"html": html},
         }
         if pid:
-            ok, status, body = api_call("PUT", server, token, f"/api/pages/{pid}", payload)
+            if not _cloud_version_allows_push(server, token, f"/api/pages/{pid}", page, title):
+                continue
+            ok, status, body = api_call("PUT", server, token, f"/api/pages/{pid}", payload, acceptable_errors=(404,))
             # PUT 404：本地 id 与云端不一致（删了重建 / 跨环境），按 route 自动创建
             if not ok and status == 404:
                 print(f"  WARN [{title}] page_id={pid} 不存在，尝试创建")
@@ -406,7 +466,7 @@ def sync_db_meta(server, token, ids=None):
             "extra": meta.get("extra"),
         }
         if mid:
-            ok, status, body = api_call("PUT", server, token, f"/api/db-meta/{mid}", payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/db-meta/{mid}", payload, acceptable_errors=(404,))
             # 本地 index 的 id 与云端不一致（删了重建 / 跨环境同步）时 PUT 404，按 type 创建
             if not ok and status == 404:
                 print(f"  WARN [{label}] db_meta_id={mid} 不存在，尝试按 type 创建")
@@ -451,7 +511,7 @@ def sync_nav(server, token, ids=None):
             continue
         html = html_file.read_text(encoding="utf-8")
         if nid:
-            ok, status, body = api_call("PUT", server, token, f"/api/navigations/{nid}", {"html": html})
+            ok, status, body = api_call("PUT", server, token, f"/api/navigations/{nid}", {"html": html}, acceptable_errors=(404,))
             if not ok and status == 404:
                 print(f"  WARN [{name}] nav_id={nid} 不存在，尝试创建")
                 nid = None
@@ -502,7 +562,7 @@ def sync_aihub(server, token, ids=None):
             "tags", "describe", "permission", "status",
         ) if it.get(k) is not None}
         if iid:
-            ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload, acceptable_errors=(404,))
             if not ok and status == 404:
                 print(f"  WARN [{name}] aihub_id={iid} 不存在，尝试创建")
                 iid = None
@@ -553,10 +613,10 @@ def sync_system_config(server, token, keys=None):
         # 前端全局层属于系统默认配置，默认字段的描述/分类/状态由基座维护。
         # 推送时只更新值，避免旧 index 中的元信息触发“系统默认字段不允许修改字段描述”。
         payload = value_payload if _is_frontend_global_config(it) else meta_payload
-        ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", payload)
+        ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", payload, acceptable_errors=(404,))
         if not ok and _is_protected_system_config_error(body) and payload != value_payload:
             print(f"  WARN [{ck}] 系统默认字段元信息受保护，改为仅推送 config_value")
-            ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", value_payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", value_payload, acceptable_errors=(404,))
         if not ok and status == 404:
             print(f"  WARN [{ck}] system_config 不存在，尝试创建")
             create_payload = _system_config_create_payload(ck, it, value)
@@ -675,7 +735,7 @@ def sync_docs(server, token, ids=None):
         payload["content"] = content
         payload["content_type"] = "html"
         if aid:
-            ok, status, body = api_call("PUT", server, token, f"/api/docs/articles/{aid}", payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/docs/articles/{aid}", payload, acceptable_errors=(404,))
             if not ok and status == 404:
                 print(f"  WARN [{title}] article_id={aid} 不存在，尝试创建")
                 aid = None
@@ -716,7 +776,7 @@ def sync_doc_categories(server, token, ids=None):
             "name", "slug", "description", "icon", "parent_id", "sort_order", "status",
         ) if it.get(k) is not None}
         if cid:
-            ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload, acceptable_errors=(404,))
             if not ok and status == 404:
                 print(f"  WARN [{name}] category_id={cid} 不存在，尝试创建")
                 cid = None
@@ -783,12 +843,14 @@ def sync_custom_scripts(server, token, ids=None):
             continue
         code = code_path.read_text(encoding="utf-8")
         if sid:
+            if not _cloud_version_allows_push(server, token, f"/api/scripts/{sid}", it, name):
+                continue
             # ScriptUpdate 接受字段（不含 slug/mode，避免误改启停/路由）
             payload = {k: it.get(k) for k in (
                 "name", "description", "config", "permission", "go_mod", "go_sum",
             ) if it.get(k) is not None}
             payload["code"] = code
-            ok, status, body = api_call("PUT", server, token, f"/api/scripts/{sid}", payload)
+            ok, status, body = api_call("PUT", server, token, f"/api/scripts/{sid}", payload, acceptable_errors=(404,))
             if not ok and status == 404:
                 print(f"  WARN [{name}] script_id={sid} 不存在，尝试创建")
                 sid = None
@@ -938,6 +1000,9 @@ def main():
         server, token, cfg = load_config()
         run_batch(server, token, args[1:])
         _lessons_reminder(cfg)
+        if RUN_FAILURES:
+            print(f"ERR: push finished with {RUN_FAILURES} failed request(s)", file=sys.stderr)
+            sys.exit(1)
         return
 
     if args[0] not in HANDLERS:
@@ -948,6 +1013,9 @@ def main():
     server, token, cfg = load_config()
     HANDLERS[mode](server, token, ids)
     _lessons_reminder(cfg)
+    if RUN_FAILURES:
+        print(f"ERR: push finished with {RUN_FAILURES} failed request(s)", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":

package/resources/skill/story/SKILL.md

@@ -1,16 +1,11 @@
 ---
 name: draftgo-story
-description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Required for high-risk development tasks when story.yaml is missing, and used whenever a development decision conflicts with the existing Story."
-version: 1.0.0
-allowed-tools: Read, Write, Glob, Bash(find:*)
+description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Use it when the user requests product-story work, when an existing Story conflicts with a requested product decision, or when preserving a durable product decision is valuable."
 ---
 
 # DraftGo Story System
 
-> **Story 是系统的灵魂档案。高风险开发必须先确认 Story 存在；功能开发若 Story 已存在则静默加载，小修不强制触发 Story。**
->
-> Story 不是文档，不是规范，是创作者对"这个系统是什么、为什么存在、不做什么"的持续叙述。
-> 文件只是理解的副产品。
+> Story 记录产品身份、设计总述、长期决策和当前方向。项目已有 Story 且请求触及定位或既有决策时加载；用户要求或形成需要长期保留的产品决策时创建或更新。
 
 ---
 
@@ -18,11 +13,11 @@ allowed-tools: Read, Write, Glob, Bash(find:*)
 
 | 原则 | 含义 |
 |------|------|
-| Gate, not Doc | 高风险任务没有 Story 就不开发；普通功能把 Story 作为上下文而不是阻塞器 |
+| Decision record | 记录会影响后续取舍的产品定位与决策 |
 | AI 维护，人确认 | 开发者只聊天，AI 负责提炼和写入 |
 | 三层结构 | 身份(稳) → 决策(只增) → 当前(频变) |
 | 决策日志最值钱 | 取舍依据是代码永远表达不了的信息 |
-| 工具无关 | yaml 文件谁都能读，不绑定任何 AI 生态 |
+| 工具无关 | 使用可移植的 YAML 文件 |
 
 ---
 
@@ -43,7 +38,7 @@ identity:
   what: "一句话讲清这是什么，不超过 30 字"
   why: |
     解决什么具体痛点，给谁用。
-    两三句话，要有画面感，不要空话。
+    用两三句具体描述说明使用者和场景。
   not:
     - "不是 XX"
     - "不变成 YY"
@@ -71,7 +66,7 @@ decisions:
 # === 第四层：当前方向（频繁更新）===
 now:
   focus: "当前阶段在做什么"
-  next: "下一步大致方向（粗粒度，不是 TODO）"
+  next: "下一步的大致方向"
   open_questions:
     - "还没想清楚的事"
 ```
@@ -81,12 +76,12 @@ now:
 ## 触发协议
 
 ```
-任何开发对话开始时：
+需要 Story 时：
 
 1. 静默检查 .draftgo/story.yaml
 2. 分流：
-   ├─ 不存在            → 进入「构建流程」，暂存开发请求
-   ├─ maturity = seed   → 加载 + 提示"Story 还稚嫩，开发中会持续补充"
+   ├─ 不存在            → 用户要求创建或需要沉淀关键决策时，进入「构建流程」
+   ├─ maturity = seed   → 加载并把不确定项作为后续判断背景
    └─ growing / stable  → 静默加载，直接开始
 3. 整个对话期间，Story 作为最高优先级上下文锚定
 ```
@@ -141,9 +136,9 @@ now:
 ```
 输出：[ 检测到全新项目，先聊一下你想做什么 ]
 
-对话式采集（不是问卷，是聊天，问到够用就停）：
+通过简短对话采集，信息足够后即进入提炼：
 
-Q1: 这个系统整体是干嘛的？（存在的理由，不是功能列表）
+Q1: 这个系统的整体定位和存在理由是什么？
 Q2: 谁会用它？什么场景下用？
 Q3: 类似的东西可能有哪些？你想做出什么不同？
 Q4: 大致有哪些模块/功能块？它们之间怎么串起来？

package/src/cli.js

@@ -24,7 +24,7 @@ const VALUE_FLAGS = new Set([
 
 function parse(argv) {
   const args = argv.slice();
-  const out = { command: null, positional: [], flags: {} };
+  const out = { command: null, positional: [], flags: {}, errors: [] };
   while (args.length) {
     const a = args.shift();
     if (a === '--') { out.positional.push(...args); break; }
@@ -32,16 +32,22 @@ function parse(argv) {
       const raw = a.slice(2);
       const eq = raw.indexOf('=');
       if (eq >= 0) {
-        out.flags[raw.slice(0, eq)] = raw.slice(eq + 1);
+        const key = raw.slice(0, eq);
+        const value = raw.slice(eq + 1);
+        if (VALUE_FLAGS.has(key) && !value) {
+          out.errors.push(`选项 --${key} 需要一个值。`);
+        } else {
+          out.flags[key] = value;
+        }
       } else {
         const next = args[0];
-        if (next !== undefined && !next.startsWith('-')) {
-          // Only consume next token as value for a known set of flags.
-          if (VALUE_FLAGS.has(raw)) {
+        if (VALUE_FLAGS.has(raw)) {
+          // A declared value flag must never silently become boolean true.
+          if (next === undefined || next === '--' || next.startsWith('--')) {
+            out.errors.push(`选项 --${raw} 需要一个值。`);
+          } else {
             out.flags[raw] = next;
             args.shift();
-          } else {
-            out.flags[raw] = true;
           }
         } else {
           out.flags[raw] = true;

package/src/commandRegistry.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Keep command names, aliases, and dispatch behavior in one place. This avoids
+// aliases silently drifting away from the implementation as the CLI grows.
+const commands = [
+  { name: 'init', run: (dir, args, flags) => require('./commands/init')(dir, args, flags) },
+  { name: 'update', run: (dir, args, flags) => require('./commands/update')(dir, args, flags) },
+  { name: 'uninstall', aliases: ['remove'], run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
+  { name: 'status', run: (dir) => require('./commands/status')(dir) },
+  { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
+  { name: 'check', run: (dir, _args, flags) => require('./commands/check')(dir, flags) },
+  { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUi')(dir, args, flags) },
+  { name: 'api', run: (_dir, args, flags) => require('./commands/api')(args, flags) },
+  { name: 'delete', aliases: ['del', 'rm'], run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
+  { name: 'deploy', run: (dir, args, flags) => require('./commands/deploy')(dir, args, flags) },
+  { name: 'auto-push', aliases: ['autopush'], run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
+  { name: 'pull', run: (dir, args, flags) => require('./commands/sync')(dir, 'pull', args, flags) },
+  { name: 'push', run: (dir, args, flags) => require('./commands/sync')(dir, 'push', args, flags) },
+  { name: 'local', run: (dir, args, flags) => require('./commands/local')(dir, args, flags) },
+  { name: 'list-targets', aliases: ['targets'], run: () => require('./commands/listTargets')() },
+  { name: 'local-dev', aliases: ['localdev'], run: (dir, args, flags) => require('./commands/localDev')(dir, args, flags) },
+  { name: 'connect', aliases: ['login'], run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+];
+
+const aliases = new Map();
+for (const command of commands) {
+  for (const alias of [command.name, ...(command.aliases || [])]) aliases.set(alias, command);
+}
+
+function resolveCommand(name) {
+  return aliases.get(name);
+}
+
+module.exports = { commands, resolveCommand };