@starwish-ai/xingyuan-dsh 0.4.0-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 starwish-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en-US.md

@@ -0,0 +1,57 @@
+# XingYuan for DeepSeek Harness
+
+[![npm version](https://img.shields.io/npm/v/@starwish-ai/xingyuan-dsh)](https://www.npmjs.com/package/@starwish-ai/xingyuan-dsh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![CI](https://github.com/starwish-ai/xingyuan-dsh/actions/workflows/ci.yml/badge.svg)](https://github.com/starwish-ai/xingyuan-dsh/actions/workflows/ci.yml)
+
+[简体中文](./README.md) | English
+
+XingYuan is a wish & habit-building companion, shipped as a DeepSeek Harness plugin bundle + agent preset.
+
+## Features
+
+- **Conversation-driven**: create wishes / tasks in natural language with duplicate detection
+- **Opportunity-day check-ins**: check-in, make-up, cancel, and future pre-checks; progress always recomputed against today
+- **Growth system**: levels Lv.1–Lv.10, streak bonuses, stat cards, 30-day bar chart
+- **Session view tabs**: Today / Wishes / Tasks / Calendar / Growth / Memory — buttons call action endpoints directly
+- **Memory**: important memories injected into context (limit configurable), full CRUD
+- **Charts**: 15 chart types rendered as cards
+- **Safe writes**: write operations confirmed by default (configurable); deletion always confirmed
+- **Theming**: light/dark follows the app theme
+
+Tools are only mounted on sessions using the XingYuan preset; other sessions are unaffected.
+
+## Install
+
+```sh
+dsh plugin --profile web add @starwish-ai/xingyuan-dsh
+```
+
+After starting the Web GUI, installation succeeded when「星愿」appears in the agent picker.
+
+## Data & Backup
+
+Business data lives at `~/.dsh/xingyuan/xingyuan.sqlite` and survives uninstall / upgrade; backup is just copying that directory.
+
+## Settings (Web GUI → Settings → XingYuan)
+
+| Option | Description |
+| --- | --- |
+| Coach style | Gentle / humorous / strict |
+| User profile | Nickname, occupation, interests |
+| Write confirmation | Whether create / check-in writes need confirmation (deletion always does) |
+| Memory injection limit | Max memories injected per turn |
+
+## Development
+
+```sh
+pnpm install
+pnpm build   # tsc + tsdown (integration tests depend on lib/)
+pnpm test    # vitest
+```
+
+Releasing: push a `v*` tag to build and publish to npm automatically (prereleases get the `alpha` dist-tag).
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,57 @@
+# 星愿 XingYuan for DeepSeek Harness
+
+[![npm version](https://img.shields.io/npm/v/@starwish-ai/xingyuan-dsh)](https://www.npmjs.com/package/@starwish-ai/xingyuan-dsh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![CI](https://github.com/starwish-ai/xingyuan-dsh/actions/workflows/ci.yml/badge.svg)](https://github.com/starwish-ai/xingyuan-dsh/actions/workflows/ci.yml)
+
+简体中文 | [English](./README.en-US.md)
+
+星愿是一个愿望与习惯养成助手，以 DeepSeek Harness 插件组合包 + Agent Preset 形式交付。
+
+## 功能
+
+- **对话驱动**：自然语言创建愿望 / 任务，自动查重相似项
+- **机会日打卡**：周期任务打卡、补卡、取消、未来预勾，进度跨天恒为最新
+- **成长体系**：等级 Lv.1–Lv.10、连击加成、统计卡与近 30 天柱状图
+- **会话视图页**：今日 / 愿望 / 任务 / 日历 / 成长 / 记忆 六个标签页，页面按钮直连动作接口
+- **记忆**：重要记忆自动注入上下文（上限可配），支持增删改查
+- **图表**：15 种统计图表自动渲染为卡片
+- **安全确认**：写操作默认二次确认（可关闭），删除始终确认
+- **主题适配**：深浅色跟随应用主题
+
+工具只挂载在选择星愿 preset 的会话上，不影响其他会话。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @starwish-ai/xingyuan-dsh
+```
+
+启动 Web GUI 后，agent 选择器出现「星愿」即安装成功。
+
+## 数据与备份
+
+业务数据存于 `~/.dsh/xingyuan/xingyuan.sqlite`，卸载 / 升级均存活，备份只需拷贝该目录。
+
+## 设置（Web GUI → 设置 → 星愿）
+
+| 配置项 | 说明 |
+| --- | --- |
+| 教练风格 | 温柔 / 幽默 / 严格 |
+| 用户画像 | 昵称、职业、兴趣 |
+| 写操作二次确认 | 创建 / 打卡类写操作是否确认（删除始终确认） |
+| 记忆注入上限 | 每次注入上下文的记忆条数上限 |
+
+## 开发
+
+```sh
+pnpm install
+pnpm build   # tsc + tsdown（集成测试依赖 lib/ 产物）
+pnpm test    # vitest
+```
+
+发布：推送 `v*` tag 自动构建并发布到 npm（预发布版本挂 `alpha` tag）。
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# 星愿 bundle 层：只插常驻行（存储后端 / HTTP 路由 / schedule）；preset 由 preset-root.ts 发布到用户根。
+# 语义：`- insert:` 插入新行；裸行按 id 整行替换既有配置（不深合并）。
+# DB 文件固定在 ~/.dsh/xingyuan/：插件卸载 / 升级数据均存活，禁止放入包安装目录。
+- insert:
+    # sqlite 后端：只依赖 storage hub，DB 位于 ~/.dsh/xingyuan/
+    - id: xingyuan-sqlite
+      name: '@starwish-ai/xingyuan-dsh/sqlite'
+      config:
+        path: !!js "dshHomePath('xingyuan', 'xingyuan.sqlite')"
+    # 主行 id 不能与 preset 目录名同名（同为 'xingyuan' 时会话挂载 preset 会死锁），故加 xy- 前缀
+    - id: xy-bundle
+      name: '@starwish-ai/xingyuan-dsh'
+    # 宿主默认组装不含 schedule 行，需补插以满足加载顺序要求
+    - id: schedule
+      name: '@deepseek-ai/dsh-schedule'
+# 领域路由：星愿领域走 sqlite 后端；其余领域维持 json（整行替换须重述 backend）
+- id: storage-domain
+  name: '@deepseek-ai/dsh-storage-domain'
+  config:
+    backend: json
+    routes:
+      xingyuan: sqlite

package/lib/cascade.js

@@ -0,0 +1,37 @@
+import { restartMicroAction } from './micro.js';
+/** 删除任务的全部打卡记录。 */
+export async function removeAllCheckins(store, taskId) {
+    const keys = [];
+    for (const [key, record] of store.domain.table('checkins').entries()) {
+        if (record.taskId === taskId)
+            keys.push(key);
+    }
+    for (const key of keys)
+        await store.domain.table('checkins').delete(key);
+}
+/**
+ * 彻底删除单个任务：打卡记录、微行动状态随任务级联清理。
+ * 返回被删任务快照（供事件补发）；任务不存在时返回 undefined。
+ */
+export async function removeTaskCompletely(store, taskId) {
+    const task = store.domain.table('tasks').get(taskId);
+    if (task === undefined)
+        return undefined;
+    await removeAllCheckins(store, taskId);
+    // 微行动状态复用 restart 的清除语义（存在才清，幂等）
+    await restartMicroAction(store, taskId);
+    await store.domain.table('tasks').delete(taskId);
+    return task;
+}
+/** 彻底删除愿望及其下属全部任务（含各自打卡与微行动状态）；返回被级联的任务。 */
+export async function removeWishCompletely(store, wishId) {
+    const removed = [];
+    for (const [, task] of store.domain.table('tasks').entries()) {
+        if (task.wishId !== wishId)
+            continue;
+        await removeTaskCompletely(store, task.taskId);
+        removed.push(task);
+    }
+    await store.domain.table('wishes').delete(wishId);
+    return removed;
+}

package/lib/category-color.js

@@ -0,0 +1,78 @@
+/**
+ * 愿望分类颜色。
+ *
+ * - 22 个预设 colorKey（5 中性 + 17 彩色）；
+ * - 未设 colorKey 时按分类名哈希到色环取稳定色相，老数据/未选色的分类也有稳定可辨的颜色；
+ * - 颜色以「色相 + 饱和度」CSS 变量下发，亮度由样式表按主题切换：
+ *   壳内跟随 body[data-ds-dark-theme]，独立页走 prefers-color-scheme。
+ */
+/** 分类颜色白名单（与工具 schema enum、Web 预设表同源；顺序即展示顺序）。 */
+export const CATEGORY_COLOR_KEYS = [
+    'slate', 'gray', 'zinc', 'neutral', 'stone',
+    'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan',
+    'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose',
+];
+/** 中性色键（饱和度走低档）。 */
+const NEUTRAL_KEYS = new Set(['slate', 'gray', 'zinc', 'neutral', 'stone']);
+/** 彩色键 → 色相（Web COLOR_HUES 同值）。 */
+const COLOR_HUES = {
+    red: 0, orange: 24, amber: 38, yellow: 55, lime: 78, green: 142, emerald: 160,
+    teal: 175, cyan: 190, sky: 200, blue: 215, indigo: 235, violet: 260, purple: 275,
+    fuchsia: 300, pink: 330, rose: 345,
+};
+const NEUTRAL_HUES = {
+    slate: 215, gray: 220, zinc: 240, neutral: 0, stone: 25,
+};
+/** 色环：未知键哈希落位（由彩色预设值派生，与 Web CATEGORY_COLOR_HUE_RING 恒等）。 */
+const HUE_RING = [...new Set(Object.values(COLOR_HUES))].sort((a, b) => a - b);
+/** djb2 文本哈希（Web hashText 同式）。 */
+function hashText(text) {
+    let h = 5381;
+    for (let i = 0; i < text.length; i += 1)
+        h = ((h * 33) ^ text.charCodeAt(i)) >>> 0;
+    return h;
+}
+export function normalizeColorKey(colorKey) {
+    if (!colorKey)
+        return '';
+    return String(colorKey).trim().toLowerCase();
+}
+/** 预设键/名查表；未命中按种子哈希入色环（Web resolveHueSpecBySeed 同式）。 */
+function hueSpecOf(seed) {
+    if (seed in NEUTRAL_HUES)
+        return { hue: NEUTRAL_HUES[seed], neutral: true };
+    if (seed in COLOR_HUES)
+        return { hue: COLOR_HUES[seed], neutral: false };
+    const index = hashText(seed) % HUE_RING.length;
+    return { hue: HUE_RING[index] ?? HUE_RING[0], neutral: false };
+}
+/**
+ * 解析分类的色相与中性标记：
+ * colorKey 在白名单内 → 预设色相；否则回退到「分类名为种子」的同一解析器
+ * （与 Web getWishCategoryCombinedStyle 一致：名称恰为英文预设键时两端同色；
+ * 空名兜底也用 Web 的 'default' 种子）。
+ */
+export function categoryHue(colorKey, categoryName) {
+    const key = normalizeColorKey(colorKey);
+    if (key !== '')
+        return hueSpecOf(key);
+    const name = (categoryName ?? '').trim();
+    return hueSpecOf(name === '' ? 'default' : name);
+}
+/** 饱和度档（Web CATEGORY_COLOR_THEME / neutral 分支同值；主题无关，只随中性变化）。 */
+const SAT_LIGHT = { bg: 58, fg: 46, border: 46 };
+const SAT_NEUTRAL = { bg: 16, fg: 20, border: 12 };
+/**
+ * 徽章内联 CSS 变量（style 属性用）：JS 拥有主题无关的色相/饱和度，
+ * CSS 拥有各主题的亮度——深浅色翻转零 JS 参与。
+ */
+export function categoryVars(colorKey, categoryName) {
+    const { hue, neutral } = categoryHue(colorKey, categoryName);
+    const sat = neutral ? SAT_NEUTRAL : SAT_LIGHT;
+    return {
+        '--cat-h': String(hue),
+        '--cat-sbg': String(sat.bg),
+        '--cat-sfg': String(sat.fg),
+        '--cat-sbd': String(sat.border),
+    };
+}

package/lib/client/api.js

@@ -0,0 +1,70 @@
+/**
+ * 同源 HTTP 访问层：GET 数据 / POST 动作（页面按钮 = 用户本人授权，不经模型不走 HITL）。
+ * 服务端错误优先取 payload.code 走 i18n 文案（err.* 键），未知 code 回落服务端 message 原文；
+ * 非 JSON 响应兜底本地化文案而非直出英文异常。
+ */
+import { t } from './i18n.js';
+/** 携带稳定 code 的业务错误：message 为中文兜底文案，code 供客户端本地化。 */
+export class ActionError extends Error {
+    code;
+    params;
+    constructor(code, message, params) {
+        super(message);
+        this.name = 'ActionError';
+        this.code = code;
+        this.params = params;
+    }
+}
+/** 服务端 code → i18n 键（编译期校验每个码都有文案）。 */
+const ERROR_KEY = {
+    missing_field: 'err.missing_field',
+    not_found: 'err.not_found',
+    already_checked: 'err.already_checked',
+    not_opportunity_day: 'err.not_opportunity_day',
+    already_claimed: 'err.already_claimed',
+    task_closed: 'err.task_closed',
+    due_past: 'err.due_past',
+    bad_category_name: 'err.bad_category_name',
+    bad_color_key: 'err.bad_color_key',
+    bad_date: 'err.bad_date',
+    overwrite_required: 'err.overwrite_required',
+};
+/** 把任意抛错转成用户可读文案：ActionError 按键本地化；其余直出消息。 */
+export function describeError(e) {
+    if (e instanceof ActionError)
+        return t(ERROR_KEY[e.code], e.params);
+    const message = e instanceof Error ? e.message : String(e);
+    // 兼容旧口径服务端纯中文消息里的「${date} 已打卡」模式（恢复卡片态用）
+    return message;
+}
+export async function postAction(path, body) {
+    return postJson(`/xingyuan/api/action/${path}`, body);
+}
+export async function postJson(path, body) {
+    const response = await fetch(path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    return parsePayload(response, () => t('common.actionFailed'));
+}
+export async function getJson(path) {
+    const response = await fetch(path, { headers: { accept: 'application/json' } });
+    return parsePayload(response, () => t('common.requestFailed'));
+}
+async function parsePayload(response, fallback) {
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error(`${fallback()}（${response.status}）`);
+    }
+    if (!response.ok) {
+        if (typeof payload.code === 'string' && payload.code !== '') {
+            throw new ActionError(payload.code, payload.error ?? fallback(), payload.params);
+        }
+        throw new Error(payload.error ?? `${fallback()}（${response.status}）`);
+    }
+    return payload;
+}

package/lib/client/cards.js

@@ -0,0 +1,205 @@
+/**
+ * 会话卡片渲染组件（愿望/任务/打卡/图表/微行动）。
+ * 渲染器只读 node.data（whole-value 事件），不扫描事件窗口；可回放可分页。
+ * 任务卡带内联领取/打卡动作（本地态防重复，服务端校验兜底）。
+ * 文案经 useXyT()：语言切换由 locale revision 订阅驱动重渲（见 i18n.ts §方案）。
+ */
+import { createElement, useRef, useState } from 'react';
+import {} from '../events.js';
+import { postAction, ActionError, describeError } from './api.js';
+import { toast, toastError } from './ui.js';
+import { localYmd, softConfirm } from './hooks.js';
+import { useXyT, t, activeLocale } from './i18n.js';
+import { categoryVars } from '../category-color.js';
+import { cycleLabel, durationText, dateSuffix } from './pages/format.js';
+function WishView(props) {
+    const t = useXyT();
+    const wish = props.node.data.data;
+    const deleted = wish.op === 'deleted';
+    return createElement('div', { className: `xy-card ${deleted ? 'xy-deleted' : ''}` }, createElement('div', { className: 'xy-card-head' }, createElement('span', {
+        className: 'xy-badge xy-badge-cat',
+        style: categoryVars(wish.wish.colorKey, wish.wish.categoryName),
+    }, t('badge.wish')), createElement('span', { className: 'xy-title' }, deleted ? t('state.deleted', { title: wish.wish.title }) : wish.wish.title)), 
+    // 已删除卡不再渲染活体进度（删除态 × 进度百分比自相矛盾）
+    createElement('div', { className: 'xy-meta' }, deleted
+        ? wish.wish.categoryName
+        : `${wish.wish.categoryName} · ${t('wish.progress', { percent: wish.wish.progress })}`));
+}
+function TaskView(props) {
+    const t = useXyT();
+    const event = props.node.data.data;
+    const task = event.task;
+    // 内联动作（对齐 Web 聊天卡领取/打卡）：点击即本人授权，本地态防重复，服务端仍校验兜底。
+    // 状态机对齐 Web markCardActioned：领取 → 原地转为可打卡；打卡 → 定格「已完成（日期）」。
+    const [phase, setPhase] = useState('idle');
+    const [doneDate, setDoneDate] = useState(undefined);
+    const [busy, setBusy] = useState(false);
+    // 同帧双击守卫：渲染态 busy 在同一事件循环内读不到新值，与页面侧
+    // useActionGuard 的 busyRef 对齐（服务端去重兜底，这里保证不发多余请求）
+    const busyRef = useRef(false);
+    const run = (action) => {
+        if (busyRef.current || phase === 'done')
+            return;
+        const future = task.nextOpportunityDate !== undefined && task.nextOpportunityDate > localYmd(new Date())
+            ? task.nextOpportunityDate
+            : undefined;
+        if (action === 'checkin' && future !== undefined && !softConfirm(t('confirm.futureCheckin', { name: task.name, date: future })))
+            return;
+        busyRef.current = true;
+        setBusy(true);
+        postAction(action, { taskId: task.taskId })
+            .then((payload) => {
+            if (action === 'claim') {
+                setPhase('claimed');
+                toast(t('toast.claimed', { name: task.name }), 'ok');
+            }
+            else {
+                setPhase('done');
+                setDoneDate(typeof payload.date === 'string' ? payload.date : undefined);
+                toast(t('toast.checkinOk') + dateSuffix(typeof payload.date === 'string' ? payload.date : undefined), 'ok');
+            }
+        })
+            .catch((e) => {
+            // 会话重放后本地态丢失，服务端状态是事实：按稳定错误码恢复卡片到真实阶段
+            //（store.ToolError 携带 code 经路由透传；文案按 code 本地化，不依赖中文子串）
+            if (e instanceof ActionError) {
+                if (action === 'claim' && e.code === 'already_claimed') {
+                    setPhase('claimed');
+                    toast(describeError(e), 'info');
+                    return;
+                }
+                if (action === 'checkin' && (e.code === 'already_checked' || e.code === 'task_closed')) {
+                    setPhase('done');
+                    setDoneDate(typeof e.params?.date === 'string' ? e.params.date : undefined);
+                    toast(describeError(e), 'info');
+                    return;
+                }
+            }
+            toastError(e);
+        })
+            .finally(() => {
+            busyRef.current = false;
+            setBusy(false);
+        });
+    };
+    const deleted = event.op === 'deleted';
+    const showClaim = !deleted && phase === 'idle' && task.status === 'pending';
+    const showCheckIn = !deleted && phase !== 'done' && (task.status === 'in_progress' || phase === 'claimed');
+    const preview = event.opportunityPreview.length > 0
+        ? t('task.upcoming', { dates: event.opportunityPreview.join(activeLocale() === 'en' ? ', ' : '、') })
+        : undefined;
+    return createElement('div', { className: `xy-card ${deleted ? 'xy-deleted' : ''}` }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-task' }, t('badge.task')), createElement('span', { className: 'xy-title' }, deleted ? t('state.deleted', { title: task.name }) : task.name), !deleted && phase === 'done'
+        ? createElement('span', { className: 'xy-meta xy-actioned' }, t('state.done') + dateSuffix(doneDate))
+        : null, showClaim
+        ? createElement('button', { className: 'xy-btn xy-btn-inline', disabled: busy, onClick: () => run('claim') }, t('action.claim'))
+        : null, showCheckIn
+        ? createElement('button', { className: 'xy-btn xy-btn-primary xy-btn-inline', disabled: busy, onClick: () => run('checkin') }, t('action.checkin'))
+        : null), createElement('div', { className: 'xy-meta' }, `${cycleLabel(task.checkInCycle)}${task.dueDate !== undefined ? ` · ${t('task.due', { date: task.dueDate })}` : ''} · ${durationText(task.completedDays, task.requiredDays)}`), deleted === false && preview !== undefined
+        ? createElement('div', { className: 'xy-preview' }, preview)
+        : null);
+}
+function MicroView(props) {
+    const t = useXyT();
+    const event = props.node.data.data;
+    const cleared = event.op === 'restarted';
+    const finished = event.op === 'finished' || event.currentStepNumber === null;
+    const doneCount = event.steps.filter((s) => s.completed).length;
+    return createElement('div', { className: 'xy-card xy-micro' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-micro' }, t('badge.micro')), createElement('span', { className: 'xy-title' }, cleared ? t('micro.cleared', { task: event.taskName })
+        : finished ? t('micro.finished', { task: event.taskName })
+            : t('micro.step', { task: event.taskName, current: event.currentStepNumber ?? 0, total: event.steps.length }))), cleared
+        ? null
+        : createElement('ol', { className: 'xy-microsteps' }, ...event.steps.map((step) => createElement('li', {
+            key: step.stepNumber,
+            className: `xy-microstep${step.completed ? ' xy-done' : step.skipped ? ' xy-skipped' : ''}`,
+        }, createElement('span', { className: 'xy-microstepnum' }, String(step.stepNumber)), createElement('span', { className: 'xy-microsteptext' }, step.instruction, step.rationale !== undefined ? createElement('span', { className: 'xy-meta' }, step.rationale) : null), step.completed
+            ? createElement('span', { className: 'xy-meta xy-microstate xy-glyph xy-glyph-ok' }, '✓')
+            : step.skipped
+                ? createElement('span', { className: 'xy-meta xy-microstate' }, t('micro.state.skipped'))
+                : step.stepNumber === event.currentStepNumber
+                    ? createElement('span', { className: 'xy-meta xy-microstate' }, t('micro.state.current'))
+                    : null))), 
+    // 进度行置于 <ol> 之外：列表语义只允许 li 子元素，进度属卡片级信息
+    !cleared && !finished
+        ? createElement('div', { className: 'xy-meta' }, t('micro.progress', { done: doneCount, total: event.steps.length }))
+        : null);
+}
+function CheckinView(props) {
+    const t = useXyT();
+    const event = props.node.data.data;
+    const cancelled = event.op === 'cancelled';
+    return createElement('div', { className: 'xy-card xy-checkin' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: `xy-glyph ${cancelled ? 'xy-glyph-back' : 'xy-glyph-ok'}`, 'aria-hidden': 'true' }, cancelled ? '↩' : '✓'), createElement('span', { className: 'xy-title' }, cancelled
+        ? t('checkin.cancelled', { task: event.taskName, date: event.date })
+        : t('checkin.success', { task: event.taskName }))), createElement('div', { className: 'xy-meta' }, `${event.date}${event.wishName !== undefined ? ` · ${event.wishName}` : ''} · ${durationText(event.completedDays, event.requiredDays)}`));
+}
+function ChartView(props) {
+    const t = useXyT();
+    const event = props.node.data.data;
+    return createElement('div', { className: 'xy-card xy-chart' }, createElement('div', { className: 'xy-card-head' }, createElement('span', { className: 'xy-badge xy-badge-chart' }, t('badge.chart')), createElement('span', { className: 'xy-title' }, event.title), event.subtitle !== undefined ? createElement('span', { className: 'xy-meta' }, event.subtitle) : null), chartBody(event, t('chart.noData')));
+}
+/** 图表卡主体：极简 SVG 柱线混合（颜色走主题变量，深浅色自适应）；分组序列附图例。 */
+function chartBody(event, noDataText) {
+    const { chartType, data } = event;
+    if (data.length === 0)
+        return createElement('div', { className: 'xy-meta' }, noDataText);
+    const max = Math.max(...data.map((d) => d.value), 1);
+    if (chartType === 'arcbars') {
+        const ratio = data[0].ratio ?? 0;
+        return createElement('div', { className: 'xy-arcwrap' }, createElement('div', { className: 'xy-arcnum' }, `${Math.round(ratio * 100)}%`), createElement('div', { className: 'xy-bar' }, createElement('div', { className: 'xy-bar-fill', style: { width: `${Math.round(ratio * 100)}%` } })));
+    }
+    if (chartType === 'pie' || chartType === 'radar') {
+        // 占比分母守卫：总和为 0 时跳过百分比（避免 NaN%）
+        const sum = data.reduce((s, x) => s + x.value, 0);
+        return createElement('ul', { className: 'xy-rows' }, ...data.map((d, i) => createElement('li', { key: i, className: 'xy-row' }, createElement('span', null, d.label), createElement('span', { className: 'xy-rowval' }, `${d.value}${chartType === 'pie' && sum > 0 ? `（${Math.round((d.value / sum) * 100)}%）` : ''}`))));
+    }
+    if (chartType === 'heatmap') {
+        return createElement('div', null, createElement('div', { className: 'xy-heat', 'aria-hidden': 'true' }, ...data.map((d, i) => createElement('span', {
+            key: i,
+            className: 'xy-heatcell',
+            title: `${d.label}：${d.value}`,
+            style: { opacity: String(0.25 + 0.75 * (d.value / max)) },
+        }))), 
+        // 热力格纯视觉（title 不构成可访问名）：数据以屏内隐藏文本整体提供给读屏
+        createElement('span', { className: 'xy-visually-hidden' }, data.map((d) => `${d.label} ${d.value}`).join('；')));
+    }
+    const seriesList = [...new Set(data.map((d) => d.series).filter((s) => s !== undefined))];
+    const seriesColor = (index) => index <= 0 ? 'var(--xyd-accent)' : 'var(--dsw-alias-label-secondary)';
+    const width = 560;
+    const height = 140;
+    const step = width / Math.max(data.length, 1);
+    const bars = data.map((d, i) => {
+        const h = Math.round((d.value / max) * (height - 24));
+        const seriesIdx = d.series !== undefined ? seriesList.indexOf(d.series) : -1;
+        return createElement('rect', {
+            key: i, x: i * step + 2, y: height - 18 - h, width: Math.max(step - 4, 2), height: h,
+            rx: 2,
+            style: { fill: seriesIdx > 0 ? seriesColor(seriesIdx) : 'var(--xyd-accent)', opacity: seriesIdx > 0 ? 0.55 : 0.85 },
+        }, 
+        // 每根柱子带 <title>：悬停可见数值，读屏可逐条播报
+        createElement('title', null, `${d.label}：${d.value}`));
+    });
+    // 标签用原始下标定位：indexOf 会把重复标签（如分组系列的「周一」×2）全部钉到首个位置
+    const labelStep = data.length <= 10 ? 1 : Math.ceil(data.length / 8);
+    const labels = data
+        .map((d, i) => ({ d, i }))
+        .filter(({ i }) => i % labelStep === 0)
+        .map(({ d, i }) => createElement('text', {
+        key: `l${i}`, x: i * step + step / 2, y: height - 4,
+        fontSize: 10, textAnchor: 'middle', style: { fill: 'var(--dsw-alias-label-secondary)' },
+    }, d.label));
+    const legend = seriesList.length > 1
+        ? createElement('div', { className: 'xy-chart-legend' }, ...seriesList.map((name, idx) => createElement('span', { key: name }, createElement('i', { className: 'xy-dot', style: { background: seriesColor(idx), opacity: idx > 0 ? 0.55 : 1 } }), name)))
+        : null;
+    return createElement('div', null, legend, 
+    // 图表整体作为一张图暴露给读屏；柱级数值经 <title> 补充
+    createElement('svg', {
+        viewBox: `0 0 ${width} ${height}`, className: 'xy-svg',
+        role: 'img', 'aria-label': event.title,
+    }, createElement('line', { x1: 0, y1: height - 18, x2: width, y2: height - 18, style: { stroke: 'var(--dsw-alias-border-l2)' } }), ...bars, ...labels));
+}
+export const CARD_VIEWS = {
+    WishView,
+    TaskView,
+    CheckinView,
+    ChartView,
+    MicroView,
+};

package/lib/client/hooks.js

@@ -0,0 +1,105 @@
+/**
+ * 页面共享 Hooks：取数三态（usePageData）、动作防重入（useActionGuard）、
+ * 滚动条槽位稳定（useStableScrollbar）、本地日期口径（localYmd）、近 N 天窗口。
+ * 六页取数样板统一收口——新页面取数 ≤3 行起步（T2-1）。
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getJson, describeError } from './api.js';
+import { toastError } from './ui.js';
+/** 本地时区 yyyy-MM-dd（与机会日计算器的本地「今天」同口径；禁用 toISOString 的 UTC 偏移）。 */
+export function localYmd(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+/** 区间查询用的本地日期窗口（近 n 天，含今天）。 */
+export function recentRangeDays(days) {
+    const now = new Date();
+    return {
+        start: localYmd(new Date(now.getFullYear(), now.getMonth(), now.getDate() - (days - 1))),
+        end: localYmd(now),
+    };
+}
+/**
+ * 取数三态统一：挂载（或 deps 变化）即拉取，error 存本地化文案，
+ * reload 供错误态按钮与动作后刷新复用。path 支持函数形态（如日历按月取参）；
+ * 内置序号守卫：快速翻页/连点时慢的旧响应不得覆盖新状态。
+ */
+export function usePageData(path, deps = []) {
+    const [data, setData] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const seqRef = useRef(0);
+    const pathRef = useRef(path);
+    pathRef.current = path;
+    const load = useCallback(() => {
+        const seq = ++seqRef.current;
+        setError(undefined);
+        return getJson(typeof pathRef.current === 'function' ? pathRef.current() : pathRef.current)
+            .then((payload) => { if (seq === seqRef.current)
+            setData(payload); })
+            .catch((e) => { if (seq === seqRef.current)
+            setError(describeError(e)); });
+    }, deps);
+    useEffect(() => { void load(); }, [load]);
+    return { data, error, reload: load };
+}
+/**
+ * 写操作防重入：busy 期间 guard 直接吞掉重复调用（按钮同时置 disabled），
+ * 结束后自动复位；失败经 toast 非阻塞提示（describeError 本地化）。
+ */
+export function useActionGuard() {
+    const [busy, setBusy] = useState(false);
+    const busyRef = useRef(false);
+    const guardRef = useRef((run) => {
+        if (busyRef.current)
+            return;
+        busyRef.current = true;
+        setBusy(true);
+        run().catch(toastError).finally(() => {
+            busyRef.current = false;
+            setBusy(false);
+        });
+    });
+    return { busy, guard: guardRef.current };
+}
+/**
+ * 把祖先滚动容器的滚动条槽位钉成常驻（scrollbar-gutter: stable）。
+ * 壳的输入框浮层模式会把真实滚动容器（*_scrollBody）的 gutter 放开为 auto，
+ * 经典滚动条按需出现/消失会使页面宽度抖动约 15px，等分布局随之整格跳变。
+ * 因此每次提交后沿祖先链把所有潜在滚动容器全部重钉，卸载时统一还原。
+ */
+export function useStableScrollbar() {
+    const nodeRef = useRef(null);
+    const undoRef = useRef(new Map());
+    const pin = useCallback(() => {
+        const node = nodeRef.current;
+        if (node === null)
+            return;
+        const undo = undoRef.current;
+        let el = node.parentElement;
+        for (let depth = 0; el !== null && depth < 16; depth += 1, el = el.parentElement) {
+            const overflowY = getComputedStyle(el).overflowY;
+            if ((overflowY === 'auto' || overflowY === 'scroll') && !undo.has(el)) {
+                undo.set(el, el.style.scrollbarGutter);
+                el.style.scrollbarGutter = 'stable';
+            }
+        }
+    }, []);
+    // 无依赖数组：每次提交后执行，捕捉壳侧节点替换与结构变化（幂等，已钉的跳过）
+    useEffect(() => { pin(); });
+    // 仅最终卸载时还原，避免逐次提交的样式抖动
+    useEffect(() => () => {
+        for (const [el, prev] of undoRef.current)
+            el.style.scrollbarGutter = prev;
+        undoRef.current.clear();
+        nodeRef.current = null;
+    }, []);
+    return useCallback((node) => {
+        if (node === null)
+            return;
+        nodeRef.current = node;
+        pin();
+    }, [pin]);
+}
+/** 破坏性轻操作的防误触确认（撤销/预勾未来日）；正向操作不拦。 */
+export function softConfirm(message) {
+    return window.confirm(message);
+}