dsh-journey 0.2.1 → 0.2.2

package/AGENT_INSTALL.md

@@ -1,4 +1,6 @@
-# AGENT_INSTALL · dsh-journey
+# AGENT_INSTALL · dsh-journey
+
+> 用户说“把这个插件用起来”时，先读 `AI_GUIDE.md`。
 
 > 给管事的 AI：照这个做，不要猜。
 
@@ -6,7 +8,7 @@
 
 ```
 name: dsh-journey
-version: 0.2.1
+version: 0.2.2
 display: Journey
 ```
 
@@ -30,9 +32,9 @@ profile: %USERPROFILE%\.dsh\profiles\desktop
 3 重启 DSH
 ```
 
-**不要手写 profile 的 journeyWorkspace**：  
-demo 工作区已经随包放在 `demo\`，插件默认读它。  
-包内 `cordis.patch.yml` 不含任何本机路径。
+**需要配置 journeyWorkspace**：  
+npm 包不含 demo；要读本机演示工作区或真实工作区，
+在 profile 的 `cordis.patch.yml` 里给 `journey` 配 `journeyWorkspace`。
 
 ## 验证
 
@@ -58,3 +60,4 @@ GET /wind-chain/journey/api/cards 返回 ok=true
 · 不要手改 profile 里的其他 bundle
 · 接口路径仍是 /wind-chain/journey/api/cards（历史路径，不是包名写错）
 ```
+

package/AI_GUIDE.md

@@ -0,0 +1,210 @@
+# AI_GUIDE · 把一个新下载的 Journey 用起来
+
+> 给任何被用户叫来“把这个插件用起来”的 AI。
+> 先读本文件，再动手；不要猜路径、不要编数据。
+
+## 0 用户只要说一句
+
+用户可以只发：
+
+```
+读 AI_GUIDE.md，把这个插件用起来，生成一个演示工作区，然后告诉我怎么用、有什么问题、下一步建议。
+```
+
+你就按下面走。
+
+## 1 先确认这是什么
+
+```
+Journey（风雨彩虹）
+DSH 只读项目监控面板
+包名：dsh-journey
+入口：DSH 左侧栏 Journey
+数据：读工作区里的 状态.md / 计划.md，不在插件里写死
+```
+
+只读；不派活、不急停、不改项目。
+
+## 2 包结构
+
+```
+dsh-journey\
+  package.json          dsh.bundle + dsh.client
+  cordis.patch.yml      host 注册（不含本机路径）
+  lib\index.js          host：/wind-chain/journey/api/cards
+  lib\client.js         client：侧栏入口 + main
+  lib\journey-data.js   数据层
+  public\index.html     v362+作者页
+  scripts\make-demo.mjs 批量生成演示项目
+  AGENT_INSTALL.md      安装 / 验证 / 卸载
+  AI_GUIDE.md           本文件
+```
+
+npm 包**不包含 demo**；demo 由本脚本生成本地目录。
+
+## 3 安装检查
+
+按 `AGENT_INSTALL.md` 装完并重启 DSH 后，确认：
+
+```
+1 左侧栏有 Journey
+2 点进去不是白屏
+3 GET /wind-chain/journey/api/cards 返回 ok=true
+```
+
+如果白屏：
+
+```
+先看是不是 DSH 共享浏览器渲染卡死
+再 reset 浏览器会话 / 重开面板
+不要先断言页面没内容
+```
+
+## 4 生成演示工作区
+
+用户没有现成工作区时：
+
+```powershell
+node scripts\make-demo.mjs "D:\somewhere\journey-demo" 12
+```
+
+会生成：
+
+```
+P01_潮汐表\
+P02_词根\
+...
+每个项目三件：
+  README.md
+  状态.md      五字段
+  计划.md      阶段 + [x]
+```
+
+然后在 profile 的 `cordis.patch.yml` 里给 Journey 配：
+
+```yaml
+- id: journey
+  name: dsh-journey
+  config:
+    journeyWorkspace: "D:\somewhere\journey-demo"
+```
+
+重启 DSH，面板就会出现 12 张卡。
+
+## 5 数据契约
+
+卡片由目录扫描得到：
+
+```
+id       目录名前缀，如 P01
+title    目录名去掉 P0x_ 前缀
+status   running / paused / done
+current  状态.md 的「当前阶段」
+why      状态.md 的「卡点」
+round    保留字段，demo 为 0
+budget   保留字段，demo 为 0
+logs     当前 demo 为空
+plan     计划.md 的阶段 + 勾选
+demo     true
+```
+
+状态推断：
+
+```
+当前阶段/卡点含「已完成/已归档」→ done
+卡点含「等/未定/未完成」→ paused
+否则 → running
+```
+
+计划格式：
+
+```
+阶段 1 打底
+  [x] 明确输入输出
+  [ ] 跑通最小流程
+```
+
+## 4.1 按用户给的信息建卡
+
+用户说“给我建一张卡 / 按这些项目建卡”时，不要直接写文件，先问五项：
+
+```
+1 标题（项目名）
+2 状态：在跑 / 等我 / 结束
+3 当前在做什么
+4 卡点是什么（没有就写“无”）
+5 计划：几个阶段、每阶段哪些已勾
+```
+
+收到后写 `cards.json`：
+
+```json
+{
+  "cards": [
+    {
+      "id": "P13",
+      "title": "天气角标",
+      "status": "running",
+      "current": "主流程跑通；正在补细节",
+      "blocker": "无",
+      "plan": [
+        { "stage": "阶段 1 打底", "items": [["明确输入输出", true], ["跑通最小流程", true]] },
+        { "stage": "阶段 2 做出来", "items": [["补主功能", false]] }
+      ]
+    }
+  ]
+}
+```
+
+然后：
+
+```powershell
+node scripts\make-cards.mjs "D:\目标演示工作区" cards.json
+```
+
+状态映射：`running` / `paused` / `done`。  
+计划按 `true/false` 写 `[x]` / `[ ]`。  
+刷新面板即可看到新卡。
+
+**原则**：用户没给的信息不要编；缺什么问什么，一次问完。
+
+## 6 验收
+
+```
+1 卡片数量 = 生成的项目数
+2 在跑 / 暂停 计数正确
+3 点一张卡，右栏显示「正在进行 / 卡点」
+4 再点右栏，显示「计划总览」
+5 点标题，作者页能开、能关
+```
+
+## 7 常见问题
+
+```
+刷新键只重绘，不重新拉接口
+→ 切换一次会话/重开面板才会重新加载数据
+
+npm 包不带 demo
+→ 没配 journeyWorkspace 时，面板会空
+
+路由仅本机
+→ 远程访问前必须加 token
+
+v362 是两态显示
+→ 结束归在暂停组，不是缺数据
+```
+
+## 8 给建议时不要越界
+
+```
+能说：数据模型、安装、演示、空态、刷新、真实 A 系列接入方案
+不能说：已经支持急停 / 派活 / 真实项目接入（还没做）
+不能改：A16 的 UI、A07 的材料、用户的项目文件
+```
+
+## 9 一句话
+
+```
+先装、再生成 demo、再验证、最后按数据契约给建议；
+不猜、不编、不把演示壳说成真实项目。
+```

package/README.md

@@ -1,6 +1,8 @@
 # Journey（风雨彩虹）
 
-> 2026-11-13 ｜ DSH 项目监控面板 ｜ v0.2.1
+> 给 AI：先读 `AI_GUIDE.md`。用户说“把这个插件用起来”时，照它做。
+
+> 2026-11-13 ｜ DSH 项目监控面板 ｜ v0.2.2
 > 中文统称：风雨彩虹
 
 ## 是什么
@@ -43,7 +45,7 @@ bundle 加 dsh-journey
 ## 数据源
 
 ```
-demo\ 随包携带，默认读取：
+demo 不再随 npm 包携带；本机演示需配置 journeyWorkspace：
   P01 潮汐表 / P02 词根 / P03 雨声
 ```
 

package/install.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-journey",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "displayName": "Journey",
   "profile": "desktop",
   "install": {

package/lib/index.js

@@ -18,7 +18,6 @@ import { buildDemoJourneyData } from './journey-data.js';
 import { fileURLToPath } from 'node:url';
 
 const JOURNEY_PUBLIC = fileURLToPath(new URL('../public/', import.meta.url));
-const JOURNEY_DEMO = fileURLToPath(new URL('../demo/', import.meta.url));
 
 function isLoopback(req) {
   const addr = String(req?.socket?.remoteAddress || '');
@@ -927,8 +926,10 @@ export function apply(ctx, config) {
           }
         }
         try {
-          const demoRoot = String(config?.journeyWorkspace ?? '').trim() || JOURNEY_DEMO;
-          const data = buildDemoJourneyData({ workspaceRoot: demoRoot });
+          const demoRoot = String(config?.journeyWorkspace ?? '').trim();
+          const data = demoRoot
+            ? buildDemoJourneyData({ workspaceRoot: demoRoot })
+            : { cards: [], counts: { total: 0, running: 0, paused: 0, done: 0, needsHuman: 0 } };
           for (const card of data.cards) {
             const agent = card.sessionId ? ctx.agents.get(card.sessionId) : undefined;
             if (agent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-journey",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Journey（风雨彩虹）：DSH 项目监控面板，查看 A 系列项目卡片、当前动作与计划总览。",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,11 +17,12 @@
   "files": [
     "lib",
     "public",
-    "demo",
     "cordis.patch.yml",
     "README.md",
     "AGENT_INSTALL.md",
-    "install.manifest.json"
+    "install.manifest.json",
+    "AI_GUIDE.md",
+    "scripts"
   ],
   "dsh": {
     "bundle": {

package/scripts/dump-journey.mjs

@@ -0,0 +1,15 @@
+import { buildMappedJourneyData } from '../lib/journey-data.js';
+
+const args = process.argv.slice(2);
+const get = (name, fallback = '') => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+};
+
+const data = buildMappedJourneyData({
+  stateRoot: get('state-root', `${process.env.USERPROFILE}\\.dsh\\wind-chain`),
+  projectRoot: get('project-root', 'D:\\deepseek_work\\Z07_疾风连环'),
+  auditLimit: Number(get('audit-limit', '8')),
+});
+
+process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);

package/scripts/make-cards.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 按用户给的信息建卡片。
+ * 用法：node scripts/make-cards.mjs <目标目录> <cards.json>
+ *
+ * cards.json:
+ * {
+ *   "cards": [
+ *     {
+ *       "id": "P13",
+ *       "title": "天气角标",
+ *       "status": "running",          // running | paused | done
+ *       "current": "主流程跑通；正在补细节",
+ *       "blocker": "无",
+ *       "plan": [
+ *         { "stage": "阶段 1 打底", "items": [["明确输入输出", true], ["跑通最小流程", true]] },
+ *         { "stage": "阶段 2 做出来", "items": [["补主功能", false]] }
+ *       ]
+ *     }
+ *   ]
+ * }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const target = process.argv[2];
+const jsonFile = process.argv[3];
+if (!target || !jsonFile) {
+  console.error('用法：node scripts/make-cards.mjs <目标目录> <cards.json>');
+  process.exit(1);
+}
+const doc = JSON.parse(fs.readFileSync(jsonFile, 'utf8'));
+const cards = Array.isArray(doc?.cards) ? doc.cards : [];
+if (!cards.length) {
+  console.error('cards.json 里没有 cards 数组');
+  process.exit(1);
+}
+fs.mkdirSync(target, { recursive: true });
+
+for (const c of cards) {
+  const id = String(c.id || '').trim();
+  const title = String(c.title || '').trim();
+  if (!id || !title) {
+    console.error('每张卡至少要有 id 和 title');
+    process.exit(1);
+  }
+  const status = ['running', 'paused', 'done'].includes(c.status) ? c.status : 'running';
+  const current = String(c.current || '暂无');
+  const blocker = String(c.blocker || '无');
+  const dir = path.join(target, `${id}_${title}`);
+  fs.mkdirSync(dir, { recursive: true });
+
+  fs.writeFileSync(path.join(dir, 'README.md'), `# ${title}\n\n## 问题\n\n${current}\n`, 'utf8');
+  fs.writeFileSync(path.join(dir, '状态.md'), `# 状态 · ${id}_${title}\n\n> 每次收工覆盖写，不追加；五字段\n\n当前阶段：${current}\n最近一次动作：按用户提供的信息录入\n下一步：按计划继续\n卡点：${blocker}\n最后更新：${new Date().toISOString().slice(0, 10)}\n`, 'utf8');
+
+  const plan = Array.isArray(c.plan) && c.plan.length ? c.plan : [];
+  const lines = [`# 计划 · ${id}_${title}`, '', '```'];
+  for (const stage of plan) {
+    lines.push(String(stage.stage || '阶段'));
+    for (const item of (Array.isArray(stage.items) ? stage.items : [])) {
+      const [text, done] = Array.isArray(item) ? item : [item, false];
+      lines.push(`  [${done ? 'x' : ' '}] ${text}`);
+    }
+    lines.push('');
+  }
+  lines.push('```');
+  fs.writeFileSync(path.join(dir, '计划.md'), lines.join('\n'), 'utf8');
+  console.log(`  ${id}_${title}  ${status}`);
+}
+console.log(`已按用户信息生成 ${cards.length} 张卡：${target}`);

package/scripts/make-demo.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * 批量生成 Journey 演示项目。
+ * 用法：node scripts/make-demo.mjs <目标目录> [数量，默认 12]
+ * 生成：每个项目 README.md / 状态.md / 计划.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const target = process.argv[2];
+const count = Math.max(1, Math.min(24, Number(process.argv[3] || 12)));
+if (!target) {
+  console.error('用法：node scripts/make-demo.mjs <目标目录> [数量]');
+  process.exit(1);
+}
+fs.mkdirSync(target, { recursive: true });
+
+const names = [
+  '潮汐表', '词根', '雨声', '书签整理', '错题地图', '播客剪辑',
+  '植物图鉴', '旧照片修复', '单词卡', '菜谱索引', '地铁换乘', '雨声混音',
+  '天气角标', '票据归档', '步数地图', '菜谱语音', '课程笔记', '桌面收纳',
+  '方言词典', '睡眠记录', '书摘卡片', '路线收藏', '图片压缩', '读书清单',
+];
+const states = ['running', 'paused', 'done'];
+
+for (let i = 0; i < count; i += 1) {
+  const id = `P${String(i + 1).padStart(2, '0')}`;
+  const name = names[i % names.length];
+  const status = states[i % states.length];
+  const dir = path.join(target, `${id}_${name}`);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const current = status === 'done'
+    ? '已完成，产物在 dist\\'
+    : status === 'paused'
+      ? '主流程跑通；等确认范围'
+      : '主流程跑通；正在补细节';
+  const blocker = status === 'done' ? '无' : status === 'paused' ? '等你定范围' : '无';
+
+  fs.writeFileSync(path.join(dir, 'README.md'), `# ${name}
+
+## 问题
+
+给 ${id} 做一个小工具，先跑通最小流程。
+
+## 到哪一步
+
+${current}
+`, 'utf8');
+
+  fs.writeFileSync(path.join(dir, '状态.md'), `# 状态 · ${id}_${name}
+
+> 每次收工覆盖写，不追加；五字段
+
+当前阶段：${current}
+最近一次动作：今天推进了一步
+下一步：按计划继续
+卡点：${blocker}
+最后更新：${new Date().toISOString().slice(0, 10)}
+`, 'utf8');
+
+  fs.writeFileSync(path.join(dir, '计划.md'), `# 计划 · ${id}_${name}
+
+\`\`\`
+阶段 1 打底
+  [x] 明确输入输出
+  [${status === 'paused' ? ' ' : 'x'}] 跑通最小流程
+
+阶段 2 做出来
+  [ ] 补主功能
+  [ ] 补边界情况
+
+阶段 3 收口
+  [${status === 'done' ? 'x' : ' '}] 写 README
+  [ ] 导出可用版本
+\`\`\`
+`, 'utf8');
+  console.log(`  ${id}_${name}  ${status}`);
+}
+console.log(`已生成 ${count} 个演示项目：${target}`);

package/demo/P01_/346/275/256/346/261/220/350/241/250/README.md

@@ -1,28 +0,0 @@
-# P01 潮汐表
-
-> 示例项目（虚构）。用于演示"**在跑**"状态。
-
-## 问题
-
-去海边之前要查潮汐，每次都要在网页上翻半天，还带广告。
-
-## 方案
-
-桌面小工具：读一份离线潮汐表，按日期输出当日高低潮两行。
-
-## 怎么跑
-
-```
-python tide.py --date 2026-11-13
-```
-
-## 到哪一步
-
-解析器写完了，正在做命令行输出。
-
-## 不做什么
-
-```
-· 不做图形界面
-· 不联网（数据是离线表）
-```

package/demo/P01_/346/275/256/346/261/220/350/241/250//347/212/266/346/200/201.md

@@ -1,9 +0,0 @@
-# 状态 · P01_潮汐表
-
-> 每次收工覆盖写，不追加；五字段
-
-当前阶段：解析器完成；正在做命令行输出
-最近一次动作：10:20 跑通 2026 全年数据解析，0 错误
-下一步：把高低潮按日切片，每天输出两行
-卡点：无
-最后更新：2026-11-13

package/demo/P01_/346/275/256/346/261/220/350/241/250//350/256/241/345/210/222.md

@@ -1,17 +0,0 @@
-# 计划 · P01_潮汐表
-
-```
-阶段 1 读数据
-  [x] 拿到离线潮汐表
-  [x] 解析全年数据
-  [ ] 校验闰年边界
-
-阶段 2 出结果
-  [ ] 按日切片
-  [ ] 命令行输出高低潮   ← 下一步
-  [ ] 支持 --date
-
-阶段 3 收口
-  [ ] 写 README
-  [ ] 打包单文件
-```

package/demo/P02_/350/257/215/346/240/271/README.md

@@ -1,28 +0,0 @@
-# P02 词根
-
-> 示例项目（虚构）。用于演示"**停住、等我回一句话**"状态。
-
-## 问题
-
-背单词总在同一个词根上反复栽，散着背记不住。
-
-## 方案
-
-按词根聚类整理，做成可打印的单页——一页纸看完一批。
-
-## 怎么跑
-
-```
-打开 词根.html（单文件，无依赖）
-```
-
-## 到哪一步
-
-数据整理完了，**卡在一个决定上**：收录范围没定，写下去会返工。
-
-## 不做什么
-
-```
-· 不做背单词 App
-· 不做记忆曲线
-```

package/demo/P02_/350/257/215/346/240/271//347/212/266/346/200/201.md

@@ -1,9 +0,0 @@
-# 状态 · P02_词根
-
-> 每次收工覆盖写，不追加；五字段
-
-当前阶段：整理完 120 个词根，等确定收录范围
-最近一次动作：昨日 21:10 出第一版 120 词根表，去重后 96 个
-下一步：确认"只收考试高频"还是"全收"
-卡点：等我说一句话——范围未定，往下写会返工
-最后更新：2026-11-12

package/demo/P02_/350/257/215/346/240/271//350/256/241/345/210/222.md

@@ -1,15 +0,0 @@
-# 计划 · P02_词根
-
-```
-阶段 1 收词
-  [x] 抓 120 个词根
-  [x] 去重到 96
-  [ ] 定收录范围   ← 下一步（等我一句话）
-
-阶段 2 排版
-  [ ] 单页 HTML
-  [ ] 打印预览
-
-阶段 3 收口
-  [ ] 印一页纸交出去
-```

package/demo/P03_/351/233/250/345/243/260/README.md

@@ -1,28 +0,0 @@
-# P03 雨声
-
-> 示例项目（虚构）。用于演示"**已结束**"状态。
-
-## 问题
-
-写东西的时候需要稳定白噪音，现成的播放器都带广告、带推荐。
-
-## 方案
-
-循环播放一段 30 秒雨声，没有界面，只有托盘图标。
-
-## 怎么跑
-
-```
-dist\rain.exe
-```
-
-## 到哪一步
-
-做完了，已归档。
-
-## 不做什么
-
-```
-· 不做歌单
-· 不做在线音源
-```

package/demo/P03_/351/233/250/345/243/260//347/212/266/346/200/201.md

@@ -1,9 +0,0 @@
-# 状态 · P03_雨声
-
-> 每次收工覆盖写，不追加；五字段
-
-当前阶段：已完成，产物在 dist\
-最近一次动作：09:40 打包成单文件，52 KB
-下一步：无（已归档）
-卡点：无
-最后更新：2026-11-11

package/demo/P03_/351/233/250/345/243/260//350/256/241/345/210/222.md

@@ -1,15 +0,0 @@
-# 计划 · P03_雨声
-
-```
-阶段 1 素材
-  [x] 录 30 秒雨声
-  [x] 无缝循环处理
-
-阶段 2 播放器
-  [x] 托盘图标
-  [x] 开机自启开关
-
-阶段 3 收口
-  [x] 单文件打包
-  [x] 说明一页
-```

package/demo//350/257/264/346/230/216.md

@@ -1,48 +0,0 @@
-# 说明 · 演示工作区
-
-> 用途：社团演示只跑这个目录 ｜ 建：2026-11-13 ｜ 归属：A07
-> 性质：**纯示例**。三个虚构项目，不含任何真实项目、日志、隐私
-
-## 为什么要有这个
-
-自用工作区 `D:\deepseek_work` 里有真实项目、日志和隐私，**不能拿去演示**。
-插件必须把"工作区路径"当参数（见 `技术资料\疾风连环_与工作站的关系.md` §6），
-于是我们给它一个干净的小目录：插件装好那一刻，指向这里就能开演。
-
-## 里面有什么
-
-```
-P01_潮汐表   在跑      演"它正在干什么"
-P02_词根     等我说一句 演"为什么停"和"说一句话就能继续"
-P03_雨声     结束      演"收口长什么样"
-```
-
-三个项目在面板上的样子：`◎` 在跑 / `○` 空闲（含"等我"与"已结束"）。
-**v362 没有单独的"结束"标记**——救星查 A16 记录确认，三态是 NEW / 在跑 / 空闲。
-所以 P03 会落在"空闲"组里，靠卡片第一句"已结束，无需处理"表达收口，不靠形状区分。
-演示脚本 §3 的动线就是照这三张卡排的。
-
-## 每个项目固定三件
-
-```
-README.md   问题 / 方案 / 怎么跑 / 到哪一步
-状态.md     五字段（当前阶段 / 最近动作 / 下一步 / 卡点 / 最后更新）
-计划.md     阶段 + 勾选 + ← 下一步
-```
-
-## 和插件的关系
-
-```
-· 插件的工作区路径指向本目录，不指向 D:\deepseek_work
-· 数据格式以插件定稿为准；计划.md 是我方提议格式，
-  若插件定了别的 schema，只改这类文件，不动其他
-· 目录名前缀（P0x）如需改成 A/Z，只改文件夹名
-```
-
-## 三条规矩
-
-```
-· 不往这里拷真实材料（一拷就污染，下次演示还得重来）
-· 演示前先跑一遍：三个状态都要对得上
-· 演完不删，下次彩排还要用
-```