@taopao/memoir 0.0.0-stage → 0.1.0

package/skill/references//346/225/260/346/215/256/345/217/243/345/276/204.md

@@ -0,0 +1,36 @@
+# 数据口径
+
+字段以 `context <表名>` 的实际返回为准；本文只说明分析时最容易用错的含义。视图定义的主说明在 `packages/db/migrations-pg/0102_views.sql`。
+
+## 消费
+
+| 对象 | 用途 | 关键字段 |
+| --- | --- | --- |
+| `v_spending` | 去重后的消费明细：电商订单按商品行分摊，加上没有可信订单关联的支付账单 | `source_type`（order/order_item/payment）、`source_key`、`platform`、`order_no`、`occurred_at`、`title`、`shop_name`、`category`、`sensitivity`、`amount_cents`、`amount_is_estimated`、`needs_match_review` |
+| `v_me_spending_monthly` | 按月、平台、分类汇总 | `month`（YYYY-MM）、`platform`、`category`、`row_count`、`amount_cents`（已排除待确认）、`exact_cents`、`estimated_cents`、`unknown_amount_count`、`pending_match_count`、`pending_candidate_cents` |
+| `public.orders` / `public.order_items` | 各电商平台的原始订单与商品 | 主键 `(platform, order_no)`；商品行另有 `line_no` |
+| `public.payments` / `v_payments` | 支付宝、微信等支付账单 | 主键 `(platform, txn_id)`；`direction`、`is_refund`、`is_transfer` |
+
+要点：
+
+- `v_spending` 已过滤：隐藏记录、火车票、退款、转账、金额为 0 或负数的行。
+- 一个订单可能拆成多行 `order_item`，统计"订单笔数"时按 `platform || ':' || order_no` 去重；`payment` 行的 `order_no` 为空，用 `source_key` 计数。
+- `occurred_at` 是 `YYYY-MM-DD HH:MM:SS` 文本，按日期范围筛选用 `occurred_at >= '2026-10-01' AND occurred_at < '2026-11-01'`。
+- `v_me_spending_monthly.amount_cents` 只含已确认部分；待确认金额在 `pending_candidate_cents`。
+
+## 其他常用视图
+
+以下视图在 `context` 中可见，使用前先 `context <视图名>` 确认字段：
+
+- 人物：`v_persons_current`
+- 聊天与互动：`v_messages`、`v_utterances`、`v_us_interaction_daily`
+- 时间线与日期：`v_timeline`、`v_us_timeline`、`v_upcoming_dates`
+- 资金往来：`v_money_flow`、`v_us_money_flow`
+- 按受益人统计消费：`v_us_spending_by_beneficiary`、`v_us_spending_unassigned`
+
+Agent 自建的表与视图都在 `public`，`context` 中可见；破坏性结构变更不做备份，删了就找不回。
+
+## 限制
+
+- `context` 的行数是统计估计，不是精确计数，也不代表覆盖的日期范围；需要时用有界查询核实。
+- `query` 只接受单条 SELECT/WITH/VALUES/TABLE 只读语句，默认最多 200 行（上限 2000），默认超时 30 秒（上限 120 秒）。

package/skill/scripts/memoir.mjs

@@ -0,0 +1,82 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * memoir Skill 入口：把参数原样转发给本机 CLI 的 `memoir skill <命令>`。
+ *
+ * CLI 定位顺序：环境变量 MEMOIR_CLI（兼容旧名 RELATION_VAULT_CLI）→ 本机 installation.json 的 entry → 源码仓库相对位置。
+ * 数据库连接由 CLI 读取数据目录 database.json 或环境变量，不经过本脚本、不进入聊天。
+ * 只启动这一次 CLI，不启动模型或后台进程。
+ */
+try {
+  if (Number(process.versions.node.split('.')[0]) < 24) throw new Error('node')
+  const installation = fileURLToPath(
+    new URL('../installation.json', import.meta.url),
+  )
+  const config = existsSync(installation)
+    ? JSON.parse(readFileSync(installation, 'utf8'))
+    : {}
+  const runtime =
+    process.env.MEMOIR_RUNTIME ||
+    process.env.RELATION_VAULT_RUNTIME ||
+    config.runtime ||
+    fileURLToPath(new URL('../../../', import.meta.url))
+  const entry =
+    process.env.MEMOIR_CLI ||
+    process.env.RELATION_VAULT_CLI ||
+    config.entry ||
+    join(runtime, 'apps/cli/src/main.ts')
+  const node = config.node || process.execPath
+  const home = process.env.MEMOIR_HOME || process.env.VAULT_HOME || config.home
+  if (
+    ![entry, node, ...(home ? [home] : [])].every(
+      (path) => typeof path === 'string' && isAbsolute(path),
+    ) ||
+    !existsSync(entry)
+  )
+    throw new Error('path')
+  const args = process.argv.slice(2)
+  const child = spawn(
+    node,
+    [
+      entry,
+      'skill',
+      ...args,
+      ...(home && !args.includes('--home') ? ['--home', home] : []),
+    ],
+    {
+      // 保持调用方当前目录：load/import/files 的相对路径按 Agent 所在目录解析（2026-11-05 评测发现
+      // 之前固定为 CLI 目录，Agent 写在工作目录的 CSV/JSONL 用相对路径会报找不到文件）。
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: 'inherit',
+      shell: false,
+    },
+  )
+  const interrupt = () => child.kill('SIGINT')
+  const terminate = () => child.kill('SIGTERM')
+  process.on('SIGINT', interrupt)
+  process.on('SIGTERM', terminate)
+  child.on('error', () => {
+    process.exitCode = 1
+  })
+  child.on('close', (code) => {
+    process.off('SIGINT', interrupt)
+    process.off('SIGTERM', terminate)
+    process.exitCode = code ?? 1
+  })
+} catch {
+  process.stdout.write(
+    `${JSON.stringify({
+      ok: false,
+      error: {
+        code: 'SKILL_INSTALLATION_INVALID',
+        message:
+          'Skill 找不到 vault CLI：请确认 Node.js 24+，并按 references/安装位置.md 安装 CLI 或设置 MEMOIR_CLI',
+      },
+    })}\n`,
+  )
+  process.exitCode = 1
+}