a-share-after-hours-brief-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 a-share-after-hours-brief contributors
+
+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.md

@@ -0,0 +1,169 @@
+# A Share After-Hours Brief Skill
+
+一个面向 Codex / Agent Skills 的 A 股个股盘后复盘 Skill。它聚焦一只或多只指定 A 股，生成移动端友好的 HTML 盘后复盘，并用本地 JSON 记录上一期判断，便于下次自动校验。
+
+This is a Codex / Agent Skill for after-hours reviews of specified China A-share stocks. It generates a mobile-friendly HTML brief and keeps portable JSON history for previous-judgment validation.
+
+## Features
+
+- 指定 A 股个股或股票池盘后复盘
+- 上一期判断校验：`已验证 / 部分验证 / 未验证 / 已失效 / 无法判断`
+- 本地 JSON 历史记录，默认保存到 HTML 输出目录的 `history/`
+- 精简市场和行业背景，用于区分市场、行业和个股因素
+- 重大事项、公告、行业新闻和相关性分析
+- 移动端友好的 HTML 报告模板
+- 可选 Gmail 草稿正文模板
+- 可选持仓纪律检查，仅在用户提供持仓或交易记录时启用
+
+## What This Skill Does Not Do
+
+- 不提供默认买卖建议
+- 不执行交易
+- 不预测 1-3 日价格走势
+- 不做完整全市场复盘
+- 不上传或集中存储用户的历史记录
+- 不内置 Wind、Gmail 或其他服务凭证
+
+## Directory Structure
+
+```text
+a-share-after-hours-brief/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+├── assets/
+│   ├── brief-template.html
+│   └── plain-email-summary-template.md
+├── references/
+│   ├── event-triggers.md
+│   ├── history-and-review.md
+│   ├── html-email.md
+│   ├── industry-news.md
+│   └── wind-data.md
+└── scripts/
+    ├── correlation.py
+    └── review_journal.py
+```
+
+## Requirements
+
+- Python 3.10+
+- A Codex / Agent Skills-compatible client
+- Wind data access if you want live A-share market, announcement, news, and K-line data
+- Gmail connector only if you want draft email delivery
+
+The bundled scripts use Python standard library only.
+
+## Installation
+
+Copy this folder into your Codex skills directory:
+
+```bash
+cp -R a-share-after-hours-brief ~/.codex/skills/
+```
+
+Or keep it in another skills directory that your Agent client can load.
+
+### Install with npm / npx
+
+After this package is published to npm:
+
+```bash
+npx a-share-after-hours-brief-skill install
+```
+
+This installs the Skill to:
+
+```text
+~/.codex/skills/a-share-after-hours-brief/
+```
+
+To overwrite an existing installation:
+
+```bash
+npx a-share-after-hours-brief-skill install --force
+```
+
+To install into a custom skills root:
+
+```bash
+npx a-share-after-hours-brief-skill install --target /path/to/skills
+```
+
+## Usage Examples
+
+```text
+复盘今天的宁德时代
+今天A股股票A和股票B盘后总结，输出HTML
+校验上次判断，列出下一交易日验证条件
+复盘这几只A股，并创建Gmail草稿
+```
+
+## JSON History
+
+By default, history is stored next to the generated HTML report:
+
+```text
+reports/
+├── 2026-06-16_A股盘后复盘.html
+└── history/
+    └── 2026-06-16__300750-SZ_600519-SH.json
+```
+
+History files are portable:
+
+- No absolute local paths are stored.
+- The whole report folder can be moved or backed up.
+- Markdown history is not generated by default.
+- JSON is the only structured history source.
+
+## Scripts
+
+Calculate correlation from two K-line files:
+
+```bash
+python3 scripts/correlation.py stock_a.json stock_b.json
+```
+
+Look up previous history:
+
+```bash
+python3 scripts/review_journal.py lookup \
+  --history-dir ./reports/history \
+  --before-date 2026-06-16 \
+  --stocks 300750.SZ,600519.SH
+```
+
+Build and save a current history record:
+
+```bash
+python3 scripts/review_journal.py build \
+  --input current-draft.json \
+  --output-html ./reports/2026-06-16_A股盘后复盘.html
+```
+
+## Validation
+
+If you have the Skill Creator validation script available:
+
+```bash
+python3 /path/to/skill-creator/scripts/quick_validate.py ./a-share-after-hours-brief
+```
+
+Also check script syntax:
+
+```bash
+python3 -m py_compile scripts/review_journal.py scripts/correlation.py
+```
+
+## Data and Privacy
+
+Do not commit generated reports or `history/*.json` if they contain private research, holdings, or trading information. This repository is intended to publish the reusable Skill logic and templates only.
+
+## Disclaimer
+
+This Skill is for research notes and workflow automation only. It does not provide investment advice, trading instructions, or guaranteed outcomes. All investment decisions remain the user's responsibility.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: a-share-after-hours-brief
+description: Generate one-stock or multi-stock A-share after-hours review briefs as polished mobile-friendly HTML attachments with optional Gmail summary drafts and portable JSON history. Use for requests like “复盘今天的宁德时代”, “今天A股股票A和股票B盘后总结”, “股票池盘后HTML简报”, “校验上次判断”, “Gmail草稿”, “近60日相关性”, or event-triggered A-share updates.
+---
+
+# A 股个股盘后复盘
+
+Create a practical Chinese after-hours review for one or more specified A-share stocks: what changed today, whether the thesis changed, how the previous judgment held up, and what observable conditions matter next session. This is not a full-market debrief. Default output is a polished mobile-friendly `.html` attachment; Gmail delivery uses a short plain summary body plus the HTML attachment.
+
+## Defaults
+
+- Report date: use the user-specified date; otherwise use today's date. Convert relative dates such as `昨天` or `上周五` into concrete dates and show the date in the report.
+- Length: standard multi-stock brief is 2-4 HTML pages; use 1-2 pages only when the user asks for a short version.
+- Correlation: compare the user-specified pair; if omitted, compare the first two stocks and label the assumption.
+- History: `history=on`, `compare_previous=true`. Save JSON under `<HTML output directory>/history/` unless `history_dir` is supplied.
+- Position review: enable only when the user provides holdings/trades or explicitly asks for discipline review.
+- Gmail: create drafts by default; never send until the user explicitly authorizes sending and gives recipients. Do not put rich HTML in the Gmail body.
+- Notion: do not sync.
+
+## Dependencies
+
+- Use `wind-find-finance-skill` if required financial capabilities or routing are uncertain.
+- Use `wind-mcp-skill` for A-share prices, K-line data, announcements, news, company events, and financial facts. Do not replace Wind facts with web search or model memory.
+- Use Gmail tools only for summary drafts/sending; attach the polished HTML file.
+
+## Workflow
+
+1. **Scope**
+   - Identify stocks, report date, output HTML path, optional Gmail recipients, optional correlation pair, history options, and whether position review is triggered.
+
+2. **Wind data**
+   - Use request tiers to protect quota. Start with Tier 1 and escalate only when triggered.
+   - Read `references/wind-data.md` before selecting Wind fields or calling Wind CLI.
+   - Fetch a compact broad-market benchmark and a relevant sector/style benchmark. Market data is context for the specified stocks, not a full-market review.
+   - Use K-line data for the correlation pair and calculate return correlation locally.
+
+3. **Previous review**
+   - Read `references/history-and-review.md`.
+   - Use `scripts/review_journal.py lookup` before writing the report when history and comparison are enabled.
+   - For each overlapping stock, evaluate the previous record's confirmation and invalidation conditions from current Wind facts. Mark each condition `met`, `not_met`, or `unknown`; never infer missing facts.
+   - Use `scripts/review_journal.py build` to calculate the final review status and atomically save the current JSON record.
+
+4. **Industry news**
+   - Use web/current news only as supplemental context when industry news may affect the brief.
+   - Cite links for material external news.
+   - Read `references/industry-news.md` when using external industry news.
+
+5. **Major events**
+   - Check announcements, news, earnings, meeting notes, abnormal moves, and policy/industry shocks.
+   - Call event skills only when trigger conditions are met; do not expand routine disclosures.
+   - Read `references/event-triggers.md` before invoking event skills.
+
+6. **Correlation**
+   - Wind provides K-line series; calculate correlation locally from aligned daily returns.
+   - Use `scripts/correlation.py` when K-line data is saved as JSON/CSV.
+   - If common return observations are fewer than 30, report sample insufficiency and avoid a directional conclusion.
+
+7. **Next-session watch**
+   - For each stock, write observable watch items, confirmation conditions, and invalidation conditions.
+   - Do not predict direction or exact prices. Conditions may reference price/volume behavior, relative strength, disclosures, or sector confirmation when supported by available facts.
+
+8. **Optional position review**
+   - When triggered, compare the user's original thesis and exit conditions with current facts.
+   - State whether an exit condition was triggered and whether the user reports executing it.
+   - Do not invent position size, cost, exit conditions, or transactions.
+
+9. **Write and deliver**
+   - Use `references/html-email.md` for sections, length, HTML attachment, mobile layout, Gmail summary body, and attachment rules.
+   - Use `assets/brief-template.html` for the polished HTML attachment.
+   - Use `assets/plain-email-summary-template.md` for Gmail body.
+
+## Verification
+
+Before delivery, check:
+
+- Stock codes, report date, price data, announcement/news dates, and source labeling.
+- Wind request tier discipline, especially that Tier 3 was only used when triggered.
+- If Tier 3 returned data, it appears in the stock analysis, next-session conditions, or risk caveat.
+- Major-event skill use, if any, matches `references/event-triggers.md`.
+- Correlation uses returns, not raw prices, and reports sample size.
+- Previous-review conditions use current facts and valid IDs from the prior record.
+- History JSON contains no absolute paths or directional outlook fields.
+- Position review appears only when holdings/trades or an explicit request triggered it.
+- HTML opens correctly, is readable on mobile, includes disclaimer, and uses the polished attachment template.
+- Gmail draft, if created, has a readable plain summary body and the HTML attachment; do not imply it was sent.

package/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "A股盘后简报"
+  short_description: "生成带跨日判断校验的A股个股盘后HTML复盘"
+  brand_color: "#2563EB"
+  default_prompt: "请用 $a-share-after-hours-brief 复盘今天的A股股票A和股票B，校验上一期判断，列出下一交易日验证条件，输出HTML并创建Gmail草稿。"
+
+policy:
+  allow_implicit_invocation: true

package/assets/brief-template.html

@@ -0,0 +1,106 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{TITLE}}</title>
+  <style>
+    :root {
+      --ink: #111827;
+      --muted: #64748b;
+      --line: #e2e8f0;
+      --paper: #ffffff;
+      --page: #eef2f7;
+      --blue: #1f4f8f;
+      --blue-soft: #eff6ff;
+      --green-soft: #f0fdf4;
+      --orange-soft: #fff7ed;
+      --yellow-soft: #fefce8;
+      --slate-soft: #f8fafc;
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: var(--page); color: var(--ink); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", Arial, sans-serif; line-height: 1.65; }
+    .page { max-width: 980px; margin: 0 auto; padding: 18px; }
+    .hero { overflow: hidden; border-radius: 18px; background: var(--paper); border: 1px solid #dbe3ef; box-shadow: 0 14px 36px rgba(15, 23, 42, 0.08); }
+    .hero-top { padding: 26px; color: #ffffff; background: linear-gradient(135deg, #1f4f8f 0%, #2563eb 58%, #0f766e 100%); }
+    .eyebrow { color: #bfdbfe; font-size: 13px; font-weight: 800; }
+    h1 { margin: 6px 0 8px; font-size: 28px; line-height: 1.25; letter-spacing: 0; }
+    .hero-meta { color: #dbeafe; font-size: 14px; }
+    .hero-summary { padding: 18px 22px; background: #ffffff; display: flex; gap: 12px; align-items: flex-start; border-bottom: 1px solid var(--line); }
+    .summary-text { margin: 0; font-size: 16px; }
+    h2 { margin: 0 0 12px; font-size: 19px; line-height: 1.35; }
+    h3 { margin: 0 0 8px; font-size: 16px; line-height: 1.4; }
+    .muted { color: var(--muted); font-size: 13px; }
+    .tag { display: inline-block; padding: 5px 11px; border-radius: 999px; font-size: 12px; font-weight: 800; white-space: nowrap; }
+    .tag-positive { background: #dcfce7; color: #166534; }
+    .tag-neutral { background: #e0f2fe; color: #075985; }
+    .tag-cautious { background: #ffedd5; color: #9a3412; }
+    .tag-verify { background: #fef9c3; color: #854d0e; }
+    .section { background: var(--paper); border: 1px solid var(--line); border-radius: 14px; padding: 20px; margin-top: 16px; box-shadow: 0 8px 20px rgba(15, 23, 42, 0.04); }
+    .section-blue { background: var(--blue-soft); border-color: #bfdbfe; }
+    .section-green { background: var(--green-soft); border-color: #bbf7d0; }
+    .section-orange { background: var(--orange-soft); border-color: #fed7aa; }
+    .section-yellow { background: var(--yellow-soft); border-color: #fde68a; }
+    .section-slate { background: var(--slate-soft); border-color: #cbd5e1; }
+    .metric-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px; margin: 12px 0; }
+    .metric-card { border: 1px solid var(--line); background: #ffffff; border-radius: 12px; padding: 12px; }
+    .metric-label { color: var(--muted); font-size: 12px; }
+    .metric { display: block; margin-top: 4px; font-size: 24px; font-weight: 850; line-height: 1.15; letter-spacing: 0; }
+    .cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 14px; }
+    .card { border: 1px solid var(--line); border-radius: 14px; padding: 15px; background: #ffffff; }
+    .card-accent { border-left: 5px solid #2563eb; }
+    table { width: 100%; border-collapse: separate; border-spacing: 0; overflow: hidden; border: 1px solid var(--line); border-radius: 12px; background: #ffffff; font-size: 14px; }
+    th, td { border-bottom: 1px solid var(--line); padding: 11px 10px; text-align: left; vertical-align: top; }
+    tr:last-child td { border-bottom: 0; }
+    th { background: #f8fafc; color: #334155; font-weight: 800; }
+    ul { margin: 8px 0 0 19px; padding: 0; }
+    li { margin: 5px 0; }
+    .footer { margin-top: 16px; color: var(--muted); font-size: 12px; background: #ffffff; border: 1px solid var(--line); border-radius: 12px; padding: 13px 15px; }
+    @media (max-width: 760px) {
+      body { background: #ffffff; }
+      .page { padding: 10px; }
+      .hero { border-radius: 14px; box-shadow: none; }
+      .hero-top { padding: 20px 18px; }
+      h1 { font-size: 23px; }
+      h2 { font-size: 18px; }
+      .hero-summary { display: block; padding: 16px; }
+      .hero-summary .tag { margin-bottom: 10px; }
+      .section { padding: 16px; border-radius: 13px; margin-top: 12px; }
+      .cards, .metric-grid { grid-template-columns: 1fr; }
+      table { display: block; overflow-x: auto; -webkit-overflow-scrolling: touch; font-size: 13px; border-radius: 10px; }
+      th, td { padding: 9px 8px; min-width: 92px; }
+      .metric { font-size: 22px; }
+    }
+    @media print { body { background: #ffffff; } .page { padding: 0; } .section, .hero, .card { break-inside: avoid; box-shadow: none; } }
+  </style>
+</head>
+<body>
+  <main class="page">
+    <section class="hero">
+      <div class="hero-top">
+        <div class="eyebrow">A股盘后研究记录</div>
+        <h1>{{TITLE}}</h1>
+        <div class="hero-meta">{{DATE}} · {{STOCK_LIST}}</div>
+      </div>
+      <div class="hero-summary">
+        <span class="tag {{JUDGMENT_CLASS}}">{{JUDGMENT}}</span>
+        <p class="summary-text">{{ONE_SENTENCE}}</p>
+      </div>
+    </section>
+
+    {{MARKET_CONTEXT_SECTION}}
+    {{PREVIOUS_REVIEW_SECTION}}
+    {{PORTFOLIO_TABLE}}
+    {{STOCK_CARDS}}
+    {{EVENTS_SECTION}}
+    {{INDUSTRY_NEWS_SECTION}}
+    {{CORRELATION_SECTION}}
+    {{NEXT_SESSION_SECTION}}
+    {{POSITION_REVIEW_SECTION}}
+
+    <div class="footer">
+      数据来源于万得 Wind 金融数据服务。仅供研究记录，不构成投资建议。
+    </div>
+  </main>
+</body>
+</html>

package/assets/plain-email-summary-template.md

@@ -0,0 +1,29 @@
+{{TITLE}}
+{{DATE}} · {{STOCK_LIST}}
+
+结论：{{JUDGMENT}}｜{{ONE_SENTENCE}}
+
+市场背景
+{{PLAIN_MARKET_CONTEXT}}
+
+上一期判断验证
+{{PLAIN_PREVIOUS_REVIEW}}
+
+组合概览
+{{PLAIN_PORTFOLIO_SUMMARY}}
+
+重大事项
+{{PLAIN_EVENTS_SUMMARY}}
+
+行业新闻
+{{PLAIN_INDUSTRY_NEWS_SUMMARY}}
+
+相关性
+{{PLAIN_CORRELATION_SUMMARY}}
+
+下一交易日重点观察
+{{PLAIN_NEXT_SESSION}}
+
+{{PLAIN_POSITION_REVIEW}}
+
+完整排版版 HTML 已作为附件附上。数据来源于万得 Wind 金融数据服务。仅供研究记录，不构成投资建议。

package/bin/install.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SKILL_NAME = "a-share-after-hours-brief";
+const REQUIRED_ENTRIES = [
+  "SKILL.md",
+  "agents",
+  "assets",
+  "references",
+  "scripts",
+];
+
+function usage() {
+  console.log(`Usage:
+  a-share-after-hours-brief-skill install [--target <dir>] [--force]
+  a-share-after-hours-brief-skill --dry-run
+
+Options:
+  --target <dir>  Skills root directory. Default: $CODEX_HOME/skills or ~/.codex/skills
+  --force         Overwrite existing ${SKILL_NAME} installation
+  --dry-run       Validate package contents without copying
+`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    command: "install",
+    target: null,
+    force: false,
+    dryRun: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "install") {
+      args.command = "install";
+    } else if (arg === "--target") {
+      const value = argv[i + 1];
+      if (!value) throw new Error("--target requires a directory");
+      args.target = value;
+      i += 1;
+    } else if (arg === "--force") {
+      args.force = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "-h" || arg === "--help") {
+      args.command = "help";
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function packageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+function defaultSkillsRoot() {
+  const codexHome = process.env.CODEX_HOME;
+  if (codexHome) return path.join(codexHome, "skills");
+  return path.join(os.homedir(), ".codex", "skills");
+}
+
+function validatePackage(root) {
+  const missing = REQUIRED_ENTRIES.filter((entry) => !fs.existsSync(path.join(root, entry)));
+  if (missing.length > 0) {
+    throw new Error(`Package is missing required entries: ${missing.join(", ")}`);
+  }
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      if (entry === "__pycache__") continue;
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+    return;
+  }
+  fs.copyFileSync(src, dest);
+}
+
+function removeIfExists(target) {
+  if (fs.existsSync(target)) {
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+}
+
+function install({ target, force, dryRun }) {
+  const root = packageRoot();
+  validatePackage(root);
+  if (dryRun) {
+    console.log(`Dry run OK: package contains ${SKILL_NAME}`);
+    return;
+  }
+
+  const skillsRoot = path.resolve(target || defaultSkillsRoot());
+  const installDir = path.join(skillsRoot, SKILL_NAME);
+  if (fs.existsSync(installDir) && !force) {
+    throw new Error(`${installDir} already exists. Re-run with --force to overwrite.`);
+  }
+
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  removeIfExists(installDir);
+  fs.mkdirSync(installDir, { recursive: true });
+
+  for (const entry of REQUIRED_ENTRIES) {
+    copyRecursive(path.join(root, entry), path.join(installDir, entry));
+  }
+
+  console.log(`Installed ${SKILL_NAME} to ${installDir}`);
+}
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "help") {
+    usage();
+  } else {
+    install(args);
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  usage();
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "a-share-after-hours-brief-skill",
+  "version": "0.1.0",
+  "description": "Codex skill for A-share after-hours stock review with portable JSON history.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SkyBridgeM/a-share-after-hours-brief-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SkyBridgeM/a-share-after-hours-brief-skill/issues"
+  },
+  "homepage": "https://github.com/SkyBridgeM/a-share-after-hours-brief-skill#readme",
+  "bin": {
+    "a-share-after-hours-brief-skill": "bin/install.js"
+  },
+  "files": [
+    "SKILL.md",
+    "agents",
+    "assets",
+    "references",
+    "scripts",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node bin/install.js --dry-run && PYTHONPYCACHEPREFIX=/tmp/a-share-after-hours-brief-skill-pycache python3 -m py_compile scripts/review_journal.py scripts/correlation.py"
+  },
+  "keywords": [
+    "codex",
+    "skill",
+    "agent-skill",
+    "a-share",
+    "stock",
+    "finance",
+    "china"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/references/event-triggers.md

@@ -0,0 +1,43 @@
+# Event Trigger Rules
+
+Use event skills only when there is a real information update. Do not expand routine disclosures into long analysis.
+
+## major-announcement-impact-skill
+
+Trigger for:
+
+- M&A, restructuring, asset sale, spin-off.
+- Private placement, rights issue, convertible bond, large financing.
+- Major shareholder reduction/increase, control change.
+- Major contract/order/cooperation.
+- Litigation, regulatory penalty, investigation.
+- Production capacity, asset impairment, large dividend or buyback if material.
+
+Output should be compressed into the brief: event nature, direct impact, second-order impact, uncertainty, and thesis impact.
+
+## conference-call-takeaway-skill
+
+Trigger for:
+
+- Earnings call, investor communication, roadshow notes, shareholder meeting notes.
+- Management comments with new information on demand, orders, margin, capacity, pricing, policy, or capital allocation.
+
+Compress into: new information, management tone, Q&A focus, warning signal, follow-up variable.
+
+## earnings-analysis
+
+Trigger for:
+
+- Quarterly report, annual report, earnings preannouncement, performance forecast, or results update.
+
+Do not generate an 8-12 page earnings report. Compress into: beat/miss, key metric changes, guidance/forecast implication, thesis impact.
+
+## valuation-pricing-framework
+
+Trigger for:
+
+- Large single-day price move without obvious fundamental news.
+- Valuation multiple reaches notable high/low range.
+- Market appears to reprice growth, cycle, policy, or risk premium.
+
+Compress into: what expectation price now implies, whether valuation moved ahead of fundamentals, and what would trigger re-rating or de-rating.

package/references/history-and-review.md

@@ -0,0 +1,111 @@
+# History and Previous-Review Rules
+
+Use `scripts/review_journal.py` for portable JSON history.
+
+## Storage
+
+- Default directory: `<HTML output directory>/history/`.
+- Override with `history_dir`.
+- JSON is the only history source. Do not generate Markdown logs.
+- Records must not contain absolute paths.
+- File name: `<report-date>__<sorted-stock-codes>.json`.
+- Same date and same stock pool are atomically replaced; other pools are untouched.
+
+## Commands
+
+Look up the latest prior record for each current stock:
+
+```bash
+python3 scripts/review_journal.py lookup \
+  --history-dir /path/to/report/history \
+  --before-date 2026-06-16 \
+  --stocks 300750.SZ,600519.SH
+```
+
+Build and save a current record:
+
+```bash
+python3 scripts/review_journal.py build \
+  --input /path/to/current-draft.json \
+  --output-html /path/to/report/2026-06-16-review.html
+```
+
+Use `--history-dir` to override the default. Use `--history off` to validate and emit the record without saving. Use `--compare-previous false` to skip lookup.
+
+## Condition contract
+
+Each current stock must define next-session conditions with stable IDs:
+
+```json
+{
+  "next_session_watch": {
+    "watch_items": ["成交量能否恢复"],
+    "confirmation_conditions": [
+      {"id": "volume-recovery", "condition": "成交量较本日明显恢复"}
+    ],
+    "invalidation_conditions": [
+      {"id": "thesis-break", "condition": "公司披露否定核心业务假设"}
+    ]
+  }
+}
+```
+
+When a prior record exists, add `condition_results` to the current stock:
+
+```json
+[
+  {
+    "id": "volume-recovery",
+    "outcome": "met",
+    "evidence": "成交量较上一交易日增加 28%"
+  },
+  {
+    "id": "thesis-break",
+    "outcome": "not_met",
+    "evidence": "未发现否定核心假设的公告"
+  }
+]
+```
+
+Allowed outcomes: `met`, `not_met`, `unknown`.
+
+## Status mapping
+
+- Any invalidation condition `met` -> `已失效`.
+- All confirmation conditions `met`, with no invalidation met -> `已验证`.
+- Some confirmation conditions `met` -> `部分验证`.
+- All required conditions are known but no confirmation is met -> `未验证`.
+- Missing facts, missing condition results, or only unknown outcomes -> `无法判断`.
+- No prior record -> `无历史基线`.
+
+The script calculates the status. The agent supplies evidence-backed condition outcomes and a concise adjustment note. Never mark unavailable data as `not_met`; use `unknown`.
+
+## Draft record minimum
+
+```json
+{
+  "schema_version": 1,
+  "report_date": "2026-06-16",
+  "generated_at": "2026-06-16T16:30:00+08:00",
+  "market_context": {},
+  "stocks": [
+    {
+      "code": "300750.SZ",
+      "name": "宁德时代",
+      "facts": {},
+      "attribution": "mixed",
+      "thesis_change": "未改变",
+      "condition_results": [],
+      "review_adjustment": "继续观察量能与行业相对强弱",
+      "next_session_watch": {
+        "watch_items": [],
+        "confirmation_conditions": [],
+        "invalidation_conditions": []
+      }
+    }
+  ],
+  "position_review": null
+}
+```
+
+Allowed attribution values: `market_beta`, `sector`, `stock_specific`, `mixed`, `unknown`.

package/references/html-email.md

@@ -0,0 +1,38 @@
+# HTML and Gmail Delivery
+
+Use concise Chinese. Standard multi-stock reports can be 2-4 HTML pages; use 1-2 pages only when the user asks for a short version.
+
+## Sections
+
+Include these sections in order:
+
+1. Header: title, date, stock list, overall judgment, one-sentence conclusion.
+2. Compact market context: broad benchmark, relevant style/sector benchmark, breadth/turnover when available, and attribution use.
+3. Previous judgment review: one row/card per overlapping stock; show prior date, prior judgment, status, evidence, and adjustment. Show `无历史基线` for new stocks.
+4. Portfolio overview: stock, code, close/change, turnover/turnover rate, key update, thesis impact.
+5. Stock cards: today's performance, information update, attribution, thesis impact.
+6. Major events: whether triggered, event type, event skill used, thesis impact.
+7. Industry news: material sector news, relevance, source links.
+8. Correlation: pair, window, observation count, Pearson correlation, label, caveat.
+9. Next-session watch: observable variables, confirmation conditions, and invalidation conditions. Do not predict direction or price.
+10. Optional position review: original thesis, exit conditions, trigger status, reported execution, and discipline gap.
+11. Source and disclaimer.
+
+## Deliverables
+
+- Polished report: static mobile-friendly `.html` using `assets/brief-template.html`.
+- Gmail draft: plain summary using `assets/plain-email-summary-template.md`, with the polished `.html` attached.
+- Do not send polished HTML as Gmail body through the connector.
+
+## HTML Attachment Rules
+
+- Mobile-first: single-column on phones; avoid wide tables when cards/key-value blocks work better.
+- Use embedded CSS, no remote images/fonts, and print-friendly contrast.
+- Use visual hierarchy: blue hero header, colored panels, metric cards, status pills, accent borders on stock cards.
+- Let important event and condition-check sections breathe; do not compress away useful judgment.
+
+## Gmail Summary Rules
+
+- Keep body short: conclusion, stock list, previous-review summary, key changes, next-session watch, and note to open attachment.
+- Do not include CSS, HTML tables, or rich layout in Gmail body.
+- Always attach the polished `.html` when creating a Gmail draft.

package/references/industry-news.md

@@ -0,0 +1,19 @@
+# Industry News
+
+Use this reference when industry news may explain the specified stocks' after-hours review.
+
+## Source priority
+
+1. Company announcements and exchange disclosures.
+2. Official regulators, ministries, exchanges, and industry associations.
+3. Wind financial news.
+4. Major financial media and credible industry publications.
+
+## Rules
+
+- Prefer recent news from the report date or immediately preceding trading sessions.
+- Include source links for material external references.
+- Mark rumor-like information as unverified and do not build a strong conclusion on it.
+- Do not use web news as a substitute for Wind price, K-line, announcement, or financial data.
+- Explain relevance to the specified stock; do not turn the section into a general market-news digest.
+- Do not use industry news to predict price direction.

package/references/wind-data.md

@@ -0,0 +1,68 @@
+# Wind Data Notes
+
+Use `wind-mcp-skill` for A-share行情、K线、公告、新闻、财务、事件、技术和风险数据. Do not replace these facts with web search or model memory.
+
+## Default Fields
+
+For each A-share, prefer one `stock_data.get_stock_price_indicators` call with only needed fields:
+
+`中文简称`, `最新成交价`, `涨跌幅`, `成交量`, `成交额`, `换手率`, `量比`, `振幅`, `5日涨跌幅`, `10日涨跌幅`, `20日涨跌幅`.
+
+Add `60日涨跌幅` only when medium-term context is needed. Verify exact field names against `wind-mcp-skill/references/indicators.md`.
+
+Use:
+
+- `financial_docs.get_company_announcements` for announcements/reports/disclosures.
+- `financial_docs.get_financial_news` for news and market reports.
+- `stock_data.get_stock_kline` for A-share daily K-line.
+- `index_data.get_index_price_indicators` or `index_data.get_index_kline` for broad/sector index context.
+
+## Request Tiers
+
+Protect Wind quota. Start with Tier 1 and escalate only when triggered.
+
+### Tier 1: Default daily brief
+
+Use for ordinary daily reports and multi-stock pools.
+
+- Per stock: one compact price snapshot call.
+- Per stock: concise date-scoped announcement/news check.
+- For the report: K-line only for the specified correlation pair.
+- Broad market index snapshot only when needed for overall context.
+
+### Tier 2: Context and condition checks
+
+Use when previous-review conditions or next-session watch items require time-series confirmation.
+
+- Add `stock_data.get_stock_kline` for stocks needing K-line confirmation, usually near 60 trading days ending at report date.
+- Add one broad benchmark snapshot and one relevant style/sector benchmark when available.
+- Prefer local calculations from K-line: 5/20/60-day trend, recent high/low, support/resistance, consecutive rise/fall, and return correlation.
+
+### Tier 3: Triggered enrichment
+
+Use only for abnormal movement, major event, unresolved condition checks, or explicit user request.
+
+- `stock_data.get_stock_technicals` for MACD/KDJ/RSI/BOLL.
+- `stock_data.get_risk_metrics` for beta/volatility/risk.
+- Sector/theme index K-line or extra announcements/news beyond date scope.
+
+Triggers include: daily move around 5%+, unusually high turnover/volume ratio, sharp divergence from market/sector, major announcement/earnings/conference call, policy/news shock, or a previous condition that cannot be checked with Tier 1 data.
+
+If Tier 3 is triggered and data is successfully fetched, include those indicators as explicit evidence in the stock analysis, condition check, or risk caveat. Do not leave fetched Tier 3 data unused.
+
+## K-Line and Correlation
+
+K-line params: `windcode` one stock only, `begin_date`/`end_date` as `yyyyMMdd`, `period: "10"` for daily K, `aftime: "0"` for forward-adjusted data when possible.
+
+For two-stock correlation, call K-line separately for each stock, align common trading dates, convert close prices to daily returns, and calculate Pearson correlation locally. If common return observations are fewer than 30, report sample insufficiency.
+
+## Market Context
+
+Fetch compact context only:
+
+- One broad benchmark relevant to the stock pool.
+- One sector/style benchmark relevant to each stock where practical.
+- Prefer `最新成交价`, `涨跌幅`, `成交额`, `上涨家数`, and `下跌家数` when supported for the selected index.
+- Use context to classify the move as mainly market beta, sector influence, stock-specific, or mixed.
+
+If a field is unavailable, continue with available data and state the limitation briefly only when it affects the conclusion.

package/scripts/correlation.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Calculate Pearson correlation from two K-line CSV/JSON files.
+
+Inputs must contain date and close fields. The parser accepts common English and
+Chinese field names so it can handle exported Wind results after light cleanup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+
+DATE_KEYS = ("date", "trade_date", "datetime", "日期", "交易日期", "时间")
+CLOSE_KEYS = ("close", "close_price", "收盘价", "收盘", "前复权收盘价", "复权收盘价")
+
+
+def load_rows(path: Path) -> list[dict[str, Any]]:
+    text = path.read_text(encoding="utf-8-sig")
+    if path.suffix.lower() == ".csv":
+        return list(csv.DictReader(text.splitlines()))
+
+    data = json.loads(text)
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in ("data", "rows", "items", "result"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return value
+    raise ValueError(f"Cannot find row list in {path}")
+
+
+def pick(row: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    for key in keys:
+        if key in row and row[key] not in (None, ""):
+            return row[key]
+    lowered = {str(k).lower(): v for k, v in row.items()}
+    for key in keys:
+        value = lowered.get(key.lower())
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def parse_close(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(str(value).replace(",", "").replace("%", "").strip())
+    except ValueError:
+        return None
+
+
+def close_series(path: Path) -> dict[str, float]:
+    series: dict[str, float] = {}
+    for row in load_rows(path):
+        if not isinstance(row, dict):
+            continue
+        date = pick(row, DATE_KEYS)
+        close = parse_close(pick(row, CLOSE_KEYS))
+        if date is None or close is None or close <= 0:
+            continue
+        series[str(date)[:10]] = close
+    return dict(sorted(series.items()))
+
+
+def returns(series: dict[str, float]) -> dict[str, float]:
+    out: dict[str, float] = {}
+    prev: float | None = None
+    for date, close in sorted(series.items()):
+        if prev and prev > 0:
+            out[date] = close / prev - 1.0
+        prev = close
+    return out
+
+
+def pearson(xs: list[float], ys: list[float]) -> float | None:
+    n = len(xs)
+    if n != len(ys) or n < 2:
+        return None
+    mean_x = sum(xs) / n
+    mean_y = sum(ys) / n
+    cov = sum((x - mean_x) * (y - mean_y) for x, y in zip(xs, ys))
+    var_x = sum((x - mean_x) ** 2 for x in xs)
+    var_y = sum((y - mean_y) ** 2 for y in ys)
+    denom = math.sqrt(var_x * var_y)
+    if denom == 0:
+        return None
+    return cov / denom
+
+
+def label(value: float | None, n: int, min_observations: int) -> str:
+    if value is None or n < min_observations:
+        return "样本不足"
+    if value > 0.75:
+        return "高度正相关"
+    if value >= 0.40:
+        return "中等正相关"
+    if value > -0.40:
+        return "相关性较弱"
+    return "负相关"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("stock_a", type=Path)
+    parser.add_argument("stock_b", type=Path)
+    parser.add_argument("--min-observations", type=int, default=30)
+    args = parser.parse_args()
+
+    ret_a = returns(close_series(args.stock_a))
+    ret_b = returns(close_series(args.stock_b))
+    common_dates = sorted(set(ret_a) & set(ret_b))
+    xs = [ret_a[d] for d in common_dates]
+    ys = [ret_b[d] for d in common_dates]
+    value = pearson(xs, ys)
+    enough = len(common_dates) >= args.min_observations and value is not None
+
+    result = {
+        "observations": len(common_dates),
+        "correlation": round(value, 4) if enough and value is not None else None,
+        "label": label(value, len(common_dates), args.min_observations),
+        "method": "Pearson correlation of aligned daily returns",
+        "common_start": common_dates[0] if common_dates else None,
+        "common_end": common_dates[-1] if common_dates else None,
+    }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/review_journal.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""Maintain portable JSON history for A-share after-hours reviews."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import tempfile
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = 1
+VALID_OUTCOMES = {"met", "not_met", "unknown"}
+VALID_ATTRIBUTIONS = {
+    "market_beta",
+    "sector",
+    "stock_specific",
+    "mixed",
+    "unknown",
+}
+
+
+def parse_bool(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in {"1", "true", "yes", "on"}:
+        return True
+    if lowered in {"0", "false", "no", "off"}:
+        return False
+    raise argparse.ArgumentTypeError(f"Expected true/false, got {value!r}")
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+
+
+def normalize_code(code: str) -> str:
+    value = str(code).strip().upper()
+    if not re.fullmatch(r"\d{6}\.(SH|SZ|BJ)", value):
+        raise ValueError(f"Invalid A-share code: {code!r}")
+    return value
+
+
+def parse_iso_date(value: str) -> date:
+    return date.fromisoformat(value)
+
+
+def history_filename(report_date: str, codes: list[str]) -> str:
+    safe_codes = [code.replace(".", "-") for code in sorted(set(codes))]
+    return f"{report_date}__{'_'.join(safe_codes)}.json"
+
+
+def iter_records(history_dir: Path) -> list[tuple[Path, dict[str, Any]]]:
+    records: list[tuple[Path, dict[str, Any]]] = []
+    if not history_dir.exists():
+        return records
+    for path in sorted(history_dir.glob("*.json")):
+        try:
+            record = load_json(path)
+            parse_iso_date(str(record["report_date"]))
+            if isinstance(record.get("stocks"), list):
+                records.append((path, record))
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+            continue
+    return records
+
+
+def stock_map(record: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    result: dict[str, dict[str, Any]] = {}
+    for stock in record.get("stocks", []):
+        if not isinstance(stock, dict) or "code" not in stock:
+            continue
+        try:
+            result[normalize_code(str(stock["code"]))] = stock
+        except ValueError:
+            continue
+    return result
+
+
+def lookup_previous(
+    history_dir: Path, before_date: str, codes: list[str]
+) -> dict[str, dict[str, Any] | None]:
+    cutoff = parse_iso_date(before_date)
+    normalized = [normalize_code(code) for code in codes]
+    candidates: dict[str, list[tuple[date, str, dict[str, Any]]]] = {
+        code: [] for code in normalized
+    }
+    for _, record in iter_records(history_dir):
+        record_date = parse_iso_date(str(record["report_date"]))
+        if record_date >= cutoff:
+            continue
+        generated_at = str(record.get("generated_at", ""))
+        by_code = stock_map(record)
+        for code in normalized:
+            stock = by_code.get(code)
+            if stock is not None:
+                candidates[code].append((record_date, generated_at, {
+                    "report_date": record["report_date"],
+                    "generated_at": generated_at,
+                    "stock": stock,
+                }))
+    return {
+        code: max(items, key=lambda item: (item[0], item[1]))[2] if items else None
+        for code, items in candidates.items()
+    }
+
+
+def condition_catalog(previous_stock: dict[str, Any]) -> dict[str, str]:
+    watch = previous_stock.get("next_session_watch") or {}
+    catalog: dict[str, str] = {}
+    for kind in ("confirmation_conditions", "invalidation_conditions"):
+        for item in watch.get(kind, []):
+            if not isinstance(item, dict):
+                continue
+            condition_id = str(item.get("id", "")).strip()
+            if not condition_id:
+                raise ValueError(f"Previous {kind} contains a condition without id")
+            if condition_id in catalog:
+                raise ValueError(f"Duplicate previous condition id: {condition_id}")
+            catalog[condition_id] = kind
+    return catalog
+
+
+def evaluate_previous(
+    previous: dict[str, Any] | None,
+    results: list[dict[str, Any]],
+    adjustment: str,
+) -> dict[str, Any]:
+    if previous is None:
+        return {
+            "previous_date": None,
+            "status": "无历史基线",
+            "evidence": [],
+            "adjustment": adjustment,
+        }
+
+    previous_stock = previous["stock"]
+    catalog = condition_catalog(previous_stock)
+    by_id: dict[str, dict[str, Any]] = {}
+    for item in results:
+        if not isinstance(item, dict):
+            raise ValueError("condition_results entries must be objects")
+        condition_id = str(item.get("id", "")).strip()
+        outcome = str(item.get("outcome", "")).strip()
+        if condition_id not in catalog:
+            raise ValueError(f"Unknown previous condition id: {condition_id}")
+        if outcome not in VALID_OUTCOMES:
+            raise ValueError(f"Invalid outcome for {condition_id}: {outcome}")
+        if condition_id in by_id:
+            raise ValueError(f"Duplicate condition result: {condition_id}")
+        by_id[condition_id] = {
+            "id": condition_id,
+            "kind": catalog[condition_id],
+            "outcome": outcome,
+            "evidence": str(item.get("evidence", "")).strip(),
+        }
+
+    if not catalog or set(by_id) != set(catalog):
+        status = "无法判断"
+    else:
+        invalidation_met = any(
+            item["kind"] == "invalidation_conditions" and item["outcome"] == "met"
+            for item in by_id.values()
+        )
+        confirmations = [
+            item for item in by_id.values()
+            if item["kind"] == "confirmation_conditions"
+        ]
+        any_unknown = any(item["outcome"] == "unknown" for item in by_id.values())
+        confirmations_met = sum(item["outcome"] == "met" for item in confirmations)
+
+        if invalidation_met:
+            status = "已失效"
+        elif any_unknown:
+            status = "无法判断"
+        elif confirmations and confirmations_met == len(confirmations):
+            status = "已验证"
+        elif confirmations_met > 0:
+            status = "部分验证"
+        else:
+            status = "未验证"
+
+    return {
+        "previous_date": previous["report_date"],
+        "status": status,
+        "evidence": list(by_id.values()),
+        "adjustment": adjustment,
+    }
+
+
+def validate_next_watch(stock: dict[str, Any]) -> None:
+    watch = stock.get("next_session_watch")
+    if not isinstance(watch, dict):
+        raise ValueError(f"{stock['code']} requires next_session_watch")
+    seen: set[str] = set()
+    for kind in ("confirmation_conditions", "invalidation_conditions"):
+        items = watch.get(kind)
+        if not isinstance(items, list):
+            raise ValueError(f"{stock['code']} {kind} must be a list")
+        for item in items:
+            if not isinstance(item, dict):
+                raise ValueError(f"{stock['code']} {kind} entries must be objects")
+            condition_id = str(item.get("id", "")).strip()
+            condition = str(item.get("condition", "")).strip()
+            if not condition_id or not condition:
+                raise ValueError(f"{stock['code']} conditions require id and condition")
+            if condition_id in seen:
+                raise ValueError(f"{stock['code']} duplicate condition id: {condition_id}")
+            seen.add(condition_id)
+    if not isinstance(watch.get("watch_items"), list):
+        raise ValueError(f"{stock['code']} watch_items must be a list")
+
+
+def build_record(
+    draft: dict[str, Any],
+    history_dir: Path,
+    compare_previous: bool,
+) -> dict[str, Any]:
+    if int(draft.get("schema_version", SCHEMA_VERSION)) != SCHEMA_VERSION:
+        raise ValueError(f"Unsupported schema_version: {draft.get('schema_version')}")
+    report_date = str(draft.get("report_date", ""))
+    parse_iso_date(report_date)
+    stocks = draft.get("stocks")
+    if not isinstance(stocks, list) or not stocks:
+        raise ValueError("stocks must be a non-empty list")
+
+    codes: list[str] = []
+    for stock in stocks:
+        if not isinstance(stock, dict):
+            raise ValueError("stocks entries must be objects")
+        code = normalize_code(str(stock.get("code", "")))
+        stock["code"] = code
+        if code in codes:
+            raise ValueError(f"Duplicate stock code: {code}")
+        codes.append(code)
+        if stock.get("attribution", "unknown") not in VALID_ATTRIBUTIONS:
+            raise ValueError(f"{code} has invalid attribution")
+        validate_next_watch(stock)
+
+    previous = (
+        lookup_previous(history_dir, report_date, codes)
+        if compare_previous
+        else {code: None for code in codes}
+    )
+    for stock in stocks:
+        code = stock["code"]
+        results = stock.pop("condition_results", [])
+        if not isinstance(results, list):
+            raise ValueError(f"{code} condition_results must be a list")
+        adjustment = str(stock.pop("review_adjustment", "")).strip()
+        stock["previous_review"] = evaluate_previous(
+            previous.get(code), results, adjustment
+        )
+
+    draft["schema_version"] = SCHEMA_VERSION
+    draft["stock_codes"] = sorted(codes)
+    draft.setdefault("market_context", {})
+    draft.setdefault("position_review", None)
+    return draft
+
+
+def atomic_write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    except Exception:
+        try:
+            os.unlink(temp_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def default_history_dir(output_html: Path) -> Path:
+    return output_html.expanduser().resolve().parent / "history"
+
+
+def command_lookup(args: argparse.Namespace) -> None:
+    codes = [item for item in args.stocks.split(",") if item.strip()]
+    result = lookup_previous(args.history_dir, args.before_date, codes)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+def command_build(args: argparse.Namespace) -> None:
+    draft = load_json(args.input)
+    history_dir = args.history_dir or default_history_dir(args.output_html)
+    record = build_record(draft, history_dir, args.compare_previous)
+    codes = [stock["code"] for stock in record["stocks"]]
+    target = history_dir / history_filename(record["report_date"], codes)
+    if args.history:
+        atomic_write_json(target, record)
+    print(json.dumps({
+        "saved": args.history,
+        "history_file": str(target) if args.history else None,
+        "record": record,
+    }, ensure_ascii=False, indent=2))
+
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    lookup = subparsers.add_parser("lookup")
+    lookup.add_argument("--history-dir", type=Path, required=True)
+    lookup.add_argument("--before-date", required=True)
+    lookup.add_argument("--stocks", required=True)
+    lookup.set_defaults(func=command_lookup)
+
+    build = subparsers.add_parser("build")
+    build.add_argument("--input", type=Path, required=True)
+    build.add_argument("--output-html", type=Path, required=True)
+    build.add_argument("--history-dir", type=Path)
+    build.add_argument("--history", type=parse_bool, default=True)
+    build.add_argument("--compare-previous", type=parse_bool, default=True)
+    build.set_defaults(func=command_build)
+    return parser
+
+
+def main() -> None:
+    args = make_parser().parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()