@coralai/sps-cli 0.62.1 → 0.63.1

package/dist/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-cli",
-  "version": "0.62.1",
+  "version": "0.63.1",
   "description": "SPS CLI — AI-driven development pipeline orchestrator",
   "type": "module",
   "main": "dist/main.js",

package/skills/checklist-review/SKILL.md

@@ -3,6 +3,8 @@ name: checklist-review
 description: 清单验收 SOP——独立 reviewer 拿到只读工具后,如何对着真实项目产物逐条核验一张卡的验收清单(每条给 pass/fail + 证据),保守判定、不放水、不越界。
 category: review
 audience: reviewer
+whenToUse: 对着验收清单逐条核验一张卡的真实产物,每条给 pass/fail + 证据(文本/功能/结构类验收)。
+insteadUse: 判游戏截图/画面是否达标→visual-rubric;写清单本身的规范→sps-pipeline。
 ---
 
 # 清单验收作业手册(reviewer 专用)

package/skills/probe-playbook/SKILL.md

@@ -1,8 +1,17 @@
 ---
 name: probe-playbook
-description: 审核自主探查 SOP——拿到只读工具(read_file/list_dir/git_diff)后,如何亲眼核验 worker 产物再下判断,杜绝"凭空要证据"。
+description: 审核自主探查 SOP——拿到只读工具(read_file/list_dir/git_diff)后,如何亲眼核验 worker
+  产物再下判断,杜绝"凭空要证据"。
 category: review
 audience: reviewer
+tags:
+  - docs
+  - process
+whenToUse: 当你是审核/监工角色，需要核验 worker 是否真的完成了改动，且手头有 read_file、list_dir、git_diff
+  等只读工具时选它。典型需求如："先别让对方贴证据，你直接查 workspace 判断是否落地"、"帮我审这卡有没有真实产物"、"按 SOP 看
+  diff、文件是否存在、关键内容是否为空实现后再给 pass/gap"。
+insteadUse: 如果需求是按通用检查清单逐项做质量审查，而不是强调先用只读工具自主探查取证，改用
+  checklist-review；如果需求是依据视觉/界面效果标准打分或审美评估，改用 visual-rubric。
 ---
 
 # 探查作业手册(监工专用)

package/skills/registry.yaml

@@ -11,7 +11,14 @@
 # 分工(三轴正交):
 #   audience = 谁来跑         (系统路由)
 #   category = 哪种知识形态    (一级分类,库的组织)
-#   tags     = 适用什么领域/技术(匹配主键,项目/worker 命中它)
+#   tags     = 适用什么领域/技术(匹配主键·**召回**,项目/worker 命中它)
+#
+# ── 精排判别字段(自由文本,非受控词表;**相似技能靠它区分**)────────────
+#   whenToUse:  触发条件 + 典型需求措辞(正例)。"什么需求该选我"。
+#   insteadUse: 相邻/易混场景该走哪个兄弟技能(负例 + 指针)。
+#               例:genre-rpg → insteadUse: "纯射击→genre-shooter;塔防→genre-td"。
+#   → search_skills(BM25 召回)会把这两行透给 agent,agent 逐条读它们**精排**选一个。
+#   → 相似技能务必成对写清 whenToUse/insteadUse,否则精排排不准。
 # ─────────────────────────────────────────────────────────────────────────
 version: 1
 

package/skills/skill-creator/SKILL.md

@@ -1,7 +1,20 @@
 ---
 name: skill-creator
-description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
+description: Create new skills, modify and improve existing skills, and measure
+  skill performance. Use when users want to create a skill from scratch, edit,
+  or optimize an existing skill, run evals to test a skill, benchmark skill
+  performance with variance analysis, or optimize a skill's description for
+  better triggering accuracy.
 category: meta
+tags:
+  - ai
+  - docs
+  - process
+  - testing
+whenToUse: 当需求是“帮我做一个新 skill / 把这段流程做成 skill / 改写现有 skill / 给 skill 补测试与评估 / 跑
+  benchmark 看效果 / 分析方差与质量 / 优化 skill description 提高触发率”时选它；尤其适合需要从意图梳理、起草
+  SKILL.md、设计测试提示、查看定性/定量结果，再按反馈反复迭代的场景。
+insteadUse: 如果只是想润色提示词、改写单条 prompt、提升一段提示的表达或结构，而不是创建/评估/迭代一个完整 skill，改用 prompt-writer。
 ---
 
 # Skill Creator

package/skills/sps-chat/SKILL.md

@@ -1,8 +1,17 @@
 ---
 name: sps-chat
-description: SPS 控制台 chat 的**机制与分诊路由**(强制注入每个 chat 会话):命令纪律、SPS 工具用法、新建/收编项目、把"要产出什么"路由到卡片驱动。**人设/语气由当前 Output Style 定,不在此**——所以本文件对任何平台(含 gameforge 设计师)都适用。
+description: SPS 控制台 chat 的**机制与分诊路由**(强制注入每个 chat 会话):命令纪律、SPS
+  工具用法、新建/收编项目、把需求路由到"就地做 / 挂 skill / 委托子 agent / 派 worker"四档。**人设/语气由当前 Output
+  Style 定,不在此**——所以本文件对任何平台(含 gameforge 设计师)都适用。
 category: platform
 audience: chat
+tags:
+  - process
+  - docs
+  - ai
+whenToUse: 当需求是“在SPS控制台里这类请求该怎么处理/路由”“什么时候直接做、什么时候挂skill、叫子agent、开项目走pipeline”“如何安全使用SPS工具与命令纪律”“新建或收编项目前该遵循什么机制”时选它。也适合需要统一chat会话操作规则、cwd规则、output产出约定、启动pipeline前确认等场景。
+insteadUse: 如果需求已经明确是在“创建/收编SPS项目、写卡片验收清单、启动与查看流水线”的项目执行规范，请改用
+  sps-pipeline；如果需求重点是“把某个独立子任务隔离出去并调用子agent执行”的具体委托方法，请改用 sps-subagent。
 ---
 
 # SPS 控制台 —— 机制与分诊(人设见你的 Output Style)
@@ -30,19 +39,29 @@ audience: chat
 
 **③ 通则**:命令要么**很快返回**,要么**后台跑 + 立刻返回**;拿不准是否常驻/follow → 默认加 `--no-follow` 或后台跑,别赌。
 
-## 分诊:任何需求 → 先定"怎么产出",再动手
-先分**你能不能自己在当前目录里做出来**:
-1. **你自己就能产出的交付物**(文章 / 文档 / 分析 / 报告 / 数据整理…,凡靠"读/写文件 + 命令"就能完成的)→ **轻路径**:找领域 skill 按其 SOP 做,**把成品写进当前目录的 `output/`**(见「产出到 output/」)。**不建项目、不上流水线。**
-2. **要一支 worker 队伍并行 / 长流程 / 看板管理的大工程**(软件、游戏等)→ **卡片驱动 pipeline**(见「SPS 项目」)。
-3. **管理已有 SPS 项目 / 卡片 / 流水线** → 见「SPS 项目」。
-4. **一次性小事 / 闲聊**(查信息、讲个笑话、跑个命令)→ 直接办,**不产出文件、不升格**。
+## 分诊路由:任何需求 → 先判"谁来做、做多重",再动手
+你是这个会话的**分诊台**。收到需求先归到下面某一档,**别默认走某一条路**:
 
-判断口诀:**能自己做出成品 → 轻路径写 `output/`;要一支队伍长期做 → pipeline;纯问答 → 直接聊。**
+**① 就地做(你自己就是那个 worker)** —— 一次性、几分钟内、无需隔离的活,直接用手上的工具办,不建项目、不派 worker:
+- **文字类交付物**(文章 / 文档 / 分析 / 报告 / 数据整理…,凡"读写文件 + 命令"能完成的)→ 直接做,成品写当前目录的 `output/`(见「产出到 output/」)。
+- **媒体产出(图 / 视频 / 音乐 / 语音 / 3D)→ 直接调 `generate_asset(kind, prompt, size?, referenceUrl?)`**:它按已配置的 provider 就地生成,**产物会自动内联展示给用户**。**这些能力已接通——别再说"没接媒体工具"。**
+  - 🔴🔴 **铁律:回复里绝不提及文件位置**——不说路径、不说文件名、不说目录名(**连 "output/"、"assets/"、"保存在…" 都不许说**)、不说字节数。那是内部实现,用户不关心也不该看到。
+  - **产物本身就是你的最终输出**:末尾让图/音/视频说话,顶多自然地补一句(如"图生好了,要调整说一声"),**不要描述它存哪了**。
+- **一次性小事 / 闲聊**(查信息、讲个笑话、跑个命令)→ 直接办,不产出文件、不升格。
+
+**② 挂 skill 增强后就地做** —— 任务像有现成 SOP(写作、评审…):`search_skills(关键词)` → `load_skill(名字)` 读规范,再按 ① 做。本质还是就地,只是先补方法论。
+
+**③ 委托子 agent(`run_subagent`)** —— 比就地重、但不值得开项目的**独立**小任务:一段调研、一块生成、一个要隔离的子活。就地委托、拿回结果、不建卡。
+
+**④ 派 worker / 流水线** —— 重活 / 多步 / 要并行队伍 / 长跑 / 要看板跟踪与审核的大工程(软件、游戏、成套产出)→ 卡片驱动 pipeline(见「SPS 项目」)。**给卡挂 skill 依 `sps-pipeline` 的挑选纪律**(`search_skills` 发现 → 近义 `match_skill` 消歧 → `load_skill` 核对),别拍脑袋写 skill 名。
+
+**判断口诀**:一次性轻活 → ①(媒体走 `generate_asset`);有 SOP → ②;独立但偏重的小任务 → ③;成体系 / 要跟踪 → ④;纯问答 → 直接聊。
+**🔴 拿不准是"就地做"还是"开项目跟踪" → 用 `present_choices` 反问用户,别替他猜。**
 
 ## 产出到 output/(轻路径:你自己就是那个 worker)
 走轻路径产出交付物时:
 1. **先出计划再动手**:复杂交付物先给用户一个简短提纲/计划(几步、每步产什么),默许后逐步做——这就是"拆卡",只是由**你自己**执行,不建卡、不派 worker。
-2. **找领域 skill**:`search_skills(关键词)`(如「写作」「文档」「报告」)→ `load_skill(名字)` 读 SOP 并遵守;没有对应 skill 就凭常识做,但**别假装能做"需要专门工具却没接"的产出**(如出视频)。
+2. **找领域 skill**:`search_skills(关键词)`(如「写作」「文档」「报告」)→ `load_skill(名字)` 读 SOP 并遵守;没有对应 skill 就凭常识做。**媒体产出(图/视频/音乐/语音/3D)走 `generate_asset`,别写文件糊弄**;只有**既没 skill 又没接工具**的产出(如 PPT 精排)才诚实说"这类还没接"。
 3. **成品落 `output/`**:最终交付物写到当前目录的 **`output/<名字>.<后缀>`**(如 `output/article.md`)。中间草稿/素材放别处或 `output/` 子目录;**最终产物一定在 `output/`**。
 4. **交付说明**:完成后一句话告诉用户产出了什么、在哪(`output/…`)。系统会检测到产物,**把这次对话升格为工作区**留存。
 
@@ -70,8 +89,11 @@ audience: chat
 6. 🔴 **启动流水线必须先问用户确认,绝不建完卡自动跑!** 给三选项:"① 看板里点启动;② 终端 `sps pipeline start <项目>`;③ 要我帮你启动吗?"——**只有用户明确说"启动/帮我跑/要",才调 `start_pipeline`**。
 
 ## 找领域 skills(决定能产出什么)
-- 要产出某类东西 → `search_skills(关键词)` / `list_skills` 找领域 skill;有就按其 SOP 建卡/派活。
-- **没有对应领域 skill 且需要专门工具**(如出视频/出 PPT 而无对应技能)→ **诚实说**"这类产出还没接专门的技能/工具",可选:我直接尽力做(如写作/分析)、或先把这个能力建出来。**绝不假装能做做不了的**(没工具就别承诺出视频)。
+- 要产出某类东西 → `search_skills(需求)` / `list_skills` 找领域 skill;有就按其 SOP 建卡/派活。
+- 🎯 **精准挑一个(相似技能别乱选)→ 用 `match_skill(需求)`**:它自动 BM25 召回 + rerank + LLM 消歧(读 whenToUse/正文),直接返回 `best + 置信 + 理由`。**相似技能分不清时优先用它**,别自己在 `search_skills` 列表里瞎猜。
+  - `match_skill` 给出 best → `load_skill(best)` 拉正文遵循;置信低/理由不对你的场景 → 再人工看 `search_skills` 的 ✅何时用/↪相邻场景 定夺。都不贴切 → 别硬套,凭常识做或诚实说没有。
+- **媒体(图/视频/音乐/语音/3D)已有专门工具 `generate_asset`,直接用**,不必找 skill。
+- **既没领域 skill、又没接专门工具**(如出 PPT 精排)→ **诚实说**"这类产出还没接",可选:我直接尽力做(如写作/分析)、或先把这个能力建出来。**绝不假装能做做不了的。**
 
 ## 底线
 - 拿不准"新建"还是"用已有" → 先探当前目录,再问一句。

package/skills/sps-pipeline/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: sps-pipeline
 description: >
-  SPS pipeline & project management — set up projects, configure YAML pipelines, manage
-  task cards, drive worker lifecycle, run web console. Use when the user asks to "create a
-  pipeline", "set up a project", "add tasks", "start the pipeline", "open console", "check
-  status", or anything in the SPS workflow. (🪸 Coral SPS)
+  SPS pipeline & project management — set up projects, configure YAML pipelines,
+  manage task cards, drive worker lifecycle, run web console. Use when the user
+  asks to "create a pipeline", "set up a project", "add tasks", "start the
+  pipeline", "open console", "check status", or anything in the SPS workflow.
+  (🪸 Coral SPS)
 category: platform
+tags:
+  - ai
+  - process
+whenToUse: 当需求是在 Coral SPS 里推进项目流程时选它：如“创建/初始化一个 SPS 项目”“配置或编辑 YAML
+  pipeline/stages”“新增任务卡/插入修正卡/写 checklist”“启动/停止 pipeline”“打开 web console/看
+  kanban、日志、worker 面板”“查看 status/doctor 排障”。也适用于明确提到 sps
+  project/card/pipeline/console/status 的请求。
+insteadUse: 如果用户只是想直接聊天、讨论方案、让代理回答问题，而不是管理 SPS 项目/卡片/流水线，改用
+  sps-chat；如果需求是把工作拆给其他子代理/并行分工执行，而非在 SPS 中建卡串行推进，改用 sps-subagent。
 ---
 
 # SPS Pipeline
@@ -74,6 +84,18 @@ sps card dashboard <project>       # CLI table;console: /board?project=<name>
 
 卡片状态机、机器管理的生命周期命令(mark-started / reset)、完整标签词表 → `references/cards.md`。
 
+### 给卡挂 skill(决定这张卡「做什么 / 怎么做」)—— 和验收清单并列的一等职责
+
+卡的 `--skill` / `add_card(skills)` = 告诉 worker 用哪套 SOP 产出。**挂错 / 漏挂 = worker 凭空发挥。**
+
+**🔴 别凭记忆猜名字**(库里几十个 skill,你上下文里没有全清单,猜名字容易挂到不存在的):
+1. `search_skills(需求关键词)` —— 看库里有哪些相关,读各自的 ✅何时用 / ↪相邻场景;
+2. **近义分不清**(几个都像:feel/physics、genre-*)→ `match_skill(需求)`,它召回+重排+消歧,直接给 best+置信+理由;
+3. 拿到名字**照抄进 `--skill`**;拿不准正文硬要求 → `load_skill(名字)` 核对再定。
+
+- **只挂这张卡真需要的那几个**,别堆;没贴切的 → 宁缺(worker 凭常识做),别硬套。
+- reviewer 会加载**同一** skill 对照验收(见下),所以卡的 skill 与验收点要指同一套 SOP。
+
 ### 验收清单(审核点)—— 建卡时写,决定这张卡「怎样算做完」
 
 **这是建卡 agent 的一等职责。** 开了 `SPS_REVIEW=on` 的项目:卡带 `## 检查清单` = **开审核**

package/skills/sps-subagent/SKILL.md

@@ -2,11 +2,20 @@
 name: sps-subagent
 description: >
   Delegate a self-contained sub-task to an independent OpenAI sub-agent via the
-  `run_subagent` tool — for scoped work that fits a small specialist agent (asset/image
-  generation, format conversion, one-off transforms). Use when a card step is better done
-  by a focused sub-agent whose result you then fold back into your work. You (the worker)
-  still own the card's lifecycle and completion. (🪸 Coral SPS)
+  `run_subagent` tool — for scoped work that fits a small specialist agent
+  (asset/image generation, format conversion, one-off transforms). Use when a
+  card step is better done by a focused sub-agent whose result you then fold
+  back into your work. You (the worker) still own the card's lifecycle and
+  completion. (🪸 Coral SPS)
 category: platform
+tags:
+  - ai
+  - design
+whenToUse: 当卡片中的某一步是“输入明确→输出明确”的独立小任务时选它，例如“生成一张图片并保存到指定路径”“把文件转成另一种格式”“做一次性批处理/变换”，且你希望用
+  run_subagent
+  让专门小代理在当前项目目录产出真实文件，再由你验收并接回主流程。典型措辞：‘帮我委托一个子代理生成资源/转换文件/产出工件’‘这一步适合单独的小专家代理去做’。
+insteadUse: 如果需求是你自己直接完成当前步骤的常规对话式协作，不需要委托独立子代理，改用
+  sps-chat；如果需求是编排/推进整张卡或多步骤流水线，而不是切出一个有清晰输入输出的独立小块，改用 sps-pipeline。
 ---
 
 # SPS Sub-agent Delegation

package/skills/visual-rubric/SKILL.md

@@ -4,6 +4,8 @@ description: 审核视觉评分卡——按"当前任务该看到什么"分阶
 category: review
 audience: reviewer
 tags: [game, design]
+whenToUse: 按当前任务所处阶段评判游戏截图/视觉产出是否达标(早期框架任务别强求实战可玩)。
+insteadUse: 逐条核验文本/功能类验收清单→checklist-review。
 ---
 
 # 视觉评分卡(游戏类,截图评审专用)

package/skills/writer/SKILL.md

@@ -3,6 +3,8 @@ name: writer
 description: 写作/文档产出 SOP —— 文章、报告、文档、说明、方案、总结等文字交付物。先出提纲(计划)再逐段写,最终成品落 output/<slug>.md。chat 轻路径与 worker 均适用。关键词:写作 文章 文档 报告 方案 总结 blog markdown。
 category: workflow
 tags: [writing, docs]
+whenToUse: 文章/报告/文档/说明/方案/总结等**文字**交付物,先出提纲再逐段写,成品落 output/。
+insteadUse: 出图/视频/音乐/语音/3D→generate_asset 工具;PPT 精排→暂无专门技能,诚实说明。
 ---
 
 # Writer —— 文字交付物产出 SOP

package/dist/console/routes/smartarrange.d.ts

@@ -1,4 +0,0 @@
-import { Hono } from 'hono';
-import type { SmartArrangeService } from '../../services/SmartArrangeService.js';
-export declare function createSmartArrangeRoute(smartarrange: SmartArrangeService): Hono;
-//# sourceMappingURL=smartarrange.d.ts.map

package/dist/console/routes/smartarrange.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"smartarrange.d.ts","sourceRoot":"","sources":["../../../src/console/routes/smartarrange.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAmDjF,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI,CA2C/E"}

package/dist/console/routes/smartarrange.js

@@ -1,107 +0,0 @@
-/**
- * @module        console/routes/smartarrange
- * @description   SmartArrange 编排页数据 + 人工确认。任务清单读 plan.json;
- *                卡片读**统一的 markdown 卡**(cards/<state>/*.md,与看板同源),按 plan.cardSeqs 关联到任务。
- * @layer         console
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { Hono } from 'hono';
-import { loadProjectConf } from '../../core/config.js';
-import { loadPlan } from '../../core/intel/planStore.js';
-import { resolveProjectPaths } from '../../core/paths.js';
-import { createTaskBackend } from '../../providers/registry.js';
-import { toHttpStatus, toProblemJson } from '../../shared/errors.js';
-function intelDir(project) {
-    return join(resolveProjectPaths(project).runtimeDir, 'intel', 'current');
-}
-function planPath(project) {
-    return join(intelDir(project), 'plan.json');
-}
-/** 旧格式兜底:改用 markdown 卡之前的项目仍把卡写在 cards.jsonl(状态:末卡=制作中,余=完成)。 */
-function legacyJsonlCards(project) {
-    const f = join(intelDir(project), 'cards.jsonl');
-    if (!existsSync(f))
-        return [];
-    try {
-        const rows = readFileSync(f, 'utf-8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
-        const maxSeq = rows.reduce((m, r) => Math.max(m, Number(r.seq) || 0), 0);
-        return rows.map((r) => ({
-            seq: Number(r.seq),
-            taskId: String(r.taskId ?? '?'),
-            title: r.title,
-            skills: r.skills ?? [],
-            status: Number(r.seq) >= maxSeq ? 'doing' : 'done',
-            prompt: r.prompt ?? '',
-            at: r.at,
-        }));
-    }
-    catch {
-        return [];
-    }
-}
-/** 卡状态(markdown state)→ 编排页状态点:完成/制作中/待完成。 */
-function stateToStatus(state) {
-    if (state === 'Done')
-        return 'done';
-    if (state === 'Inprogress')
-        return 'doing';
-    return 'todo';
-}
-/** 从 markdown body 的「## 日志」抽第一条时间戳(派发时间,服务器本地)。 */
-function firstLogTs(body) {
-    const m = body?.match(/###\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})/);
-    return m?.[1];
-}
-/** seq → 所属任务 id(从 plan.tasks[].cardSeqs)。 */
-function seqTaskMap(plan) {
-    const m = new Map();
-    for (const t of plan?.tasks ?? [])
-        for (const s of t.cardSeqs)
-            m.set(s, t.id);
-    return m;
-}
-export function createSmartArrangeRoute(smartarrange) {
-    const app = new Hono();
-    // 编排页数据:任务清单 + 卡链路(markdown 卡)
-    app.get('/:project', async (c) => {
-        const project = c.req.param('project');
-        const plan = loadPlan(planPath(project));
-        const seq2task = seqTaskMap(plan);
-        let cards = [];
-        try {
-            const backend = createTaskBackend(loadProjectConf(project));
-            const all = await backend.listAll();
-            cards = all
-                .map((card) => ({ ...card, seqN: Number(card.seq) }))
-                .filter((card) => seq2task.has(card.seqN)) // 只取编排链上的卡(监工产的)
-                .sort((a, b) => a.seqN - b.seqN)
-                .map((card) => ({
-                seq: card.seqN,
-                taskId: seq2task.get(card.seqN) ?? '?',
-                title: card.title,
-                skills: card.skills ?? [],
-                status: stateToStatus(card.state),
-                state: card.state,
-                prompt: card.desc ?? '',
-                at: firstLogTs(card.body),
-            }));
-        }
-        catch {
-            /* conf 缺失/未启动 → 空卡 */
-        }
-        // 旧项目(cards.jsonl,无 markdown 卡)兜底,平滑过渡
-        if (cards.length === 0)
-            cards = legacyJsonlCards(project);
-        return c.json({ plan, cards });
-    });
-    // 人工确认首轮任务清单 → 进入自动流水线(委托 SmartArrangeService,与容器方法同源)
-    app.post('/:project/approve', (c) => {
-        const r = smartarrange.approve(c.req.param('project'));
-        if (!r.ok)
-            return c.json(toProblemJson(r.error), toHttpStatus(r.error));
-        return c.json(r.value);
-    });
-    return app;
-}
-//# sourceMappingURL=smartarrange.js.map

package/dist/console/routes/smartarrange.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"smartarrange.js","sourceRoot":"","sources":["../../../src/console/routes/smartarrange.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAErE,SAAS,QAAQ,CAAC,OAAe;IAC/B,OAAO,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC3E,CAAC;AACD,SAAS,QAAQ,CAAC,OAAe;IAC/B,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED,iEAAiE;AACjE,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;IACjD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;QAC9H,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;YAClB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC;YAC/B,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;YACtB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;YAClD,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;YACtB,EAAE,EAAE,CAAC,CAAC,EAAE;SACT,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,8CAA8C;AAC9C,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACpC,IAAI,KAAK,KAAK,YAAY;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,SAAS,UAAU,CAAC,IAAwB;IAC1C,MAAM,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChB,CAAC;AAED,8CAA8C;AAC9C,SAAS,UAAU,CAAC,IAAsB;IACxC,MAAM,CAAC,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,KAAK,IAAI,EAAE;QAAE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ;YAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,YAAiC;IACvE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IAEvB,+BAA+B;IAC/B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAElC,IAAI,KAAK,GAAc,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,iBAAiB,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YACpC,KAAK,GAAG,GAAG;iBACR,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;iBACpD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB;iBAC3D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;iBAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACd,GAAG,EAAE,IAAI,CAAC,IAAI;gBACd,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG;gBACtC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE;gBACzB,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;gBACjC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBACvB,EAAE,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;aAC1B,CAAC,CAAC,CAAC;QACR,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;QACD,uCAAuC;QACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC1D,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,uDAAuD;IACvD,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,EAAE;QAClC,MAAM,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAQ,CAAC,CAAC;QAC/E,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC"}