@petercjl/taobao-ai-ops 0.1.0 → 0.1.2

package/skills/yuce-category-opportunity-report/references/data-contract.md

@@ -1,40 +0,0 @@
-# 月度数据采集与合并契约
-
-在主流程 Step 3 的 NAS 采集节点或 Step 4A 的 Excel 缓存节点读取。本页规定两种来源的月度数据契约；商业判断进入 Step 5 的知识路由。
-
-## 用户提供 Excel
-
-- 接受一份或多份 `.xlsx`；可为一级、二级、三级各一份，也可是一份含多张对应数据表的工作簿。识别数据表 `一级类目月数据`、`二级类目月数据`、`三级类目月数据`，按表头读取，不按文件名猜类目层级。其他工作表不参与计算。
-- 一级表要求 `月份`、`一级类目`、`成交额（原始值）`；二级表要求 `月份`、`一级类目`、`二级类目`、`总成交额（原始值）`；三级表再要求 `三级类目`。成交量、环比和 `是否有三级类目` 有值时保留原值，不从展示值反算。
-- 同一完整路径、月份的重复记录可以重合，但成交额差异超过 0.01 元即停止生成缓存并报告冲突。一级完整 24 个月是报告必要条件；下级缺月保留为空缺，不当成零。
-- 用户选择 Excel 输入时只读取这些本地文件，不访问 NAS、VPN、yccli，也不自动入库。原始工作簿保持不变。
-
-## 标准化 Excel 缓存
-
-两种输入路径都先运行 `scripts/build_report.py --cache-out`，生成一个新的 `.xlsx`。它只有 `类目月度缓存` 数据表，字段为：`月份`、`层级`、`一级类目`、`二级类目`、`三级类目`、`成交额（原始值）`、`成交额环比（原始值）`、`成交量（原始值）`、`成交量环比（原始值）`、`是否有三级类目`、`来源文件`、`来源SHA256`。每行对应一个完整类目路径和一个自然月。后续 `--cache-xlsx` 分析只读这个本地工作簿，不边查数据库边计算。缓存数据表之外不生成元数据工作表。
-
-## 窗口与命令粒度
-
-- 24 个月窗口是连续自然月，首尾都包含；默认截止到上一个已完成月份，仍要核对 Yuce 的实际可用月份。
-- `yccli` 每条月数据命令要求一个连续起止区间。把缺失月份按连续段合并；不跨越已有月份大量重拉。
-- 一级：每段一次 `first-category-monthly`。二级：一个区间一次 `second-category-monthly`，结果覆盖该一级下所有二级。三级：每个二级父类目、每个连续区间一次 `third-category-monthly`。
-- 只使用新的 JSON 输出路径。文件名可包含类目层级和起止月份，不能覆盖旧采集结果。
-
-## 从数据库覆盖到采集计划
-
-`tbcli db yuce coverage` 的 `categories` 按完整 `path` 列出 `level`、`presentMonthCount`、`missingMonths`。先从一级得到一级缺月；从所有二级路径取缺月并集；逐个二级父路径汇总其三级路径缺月。二级 `hasThirdCategory` 指示该路径是否应有三级数据。若一个应有三级的二级路径没有任何已知三级子路径，按完整窗口采集一次。若新二级出现在刚采集的二级文件中，也为其采集完整窗口的三级数据。
-
-父子类目可能因平台调整而变动。已有数据库类目树只能列出历史已知路径，不能证明平台当期没有新路径；采集到的新路径须按其完整名称保存，不用同名的最后一级名称合并。
-
-## 验证与导入
-
-- 命令回执、`kind`、`category`、`secondCategory`、`months` 和每行路径必须匹配请求。
-- 每个返回文件的 `months` 应与请求的连续区间一致；每个请求月份至少有一条数据。零行、范围缩短或父类目不匹配都不得当成完成。
-- 导入使用 `tbcli yuce categories validate|import`；从一级到三级的顺序保证父路径存在。
-- 一级成交量为 0 且成交额为正时，沿用来源值并保留 `suspect_missing`，不能解读成真实零销量。二、三级没有成交量时是 `not_collected`。
-- 同一完整路径与月份的金额冲突时停止合并并报告来源；入库冲突只回滚该文件，不自动覆盖历史。
-- `scripts/build_report.py` 的缓存步骤接受数据库快照、任意数量的 yccli JSON 或原始 Excel。报告步骤只接受已生成的本地 Excel 缓存作为正常主线输入；只对选定 24 个月内的行计算，来源 SHA-256 和文件名进入分析侧车文件。
-
-## 完成条件
-
-一级每个月都有记录。二、三级缺月必须列示；只有完整 24 个月的下级类目计算完整年度同比。父子金额按同月同层级对账，超过容差时保留异常并在报告中提示。类目重命名、统计口径变化或平台短期数据回补属于后续核实事项。

package/skills/yuce-category-opportunity-report/references/index.md

@@ -1,6 +0,0 @@
-# Knowledge Index
-
-- [Assess a first-category research opportunity](queries/assess-category-opportunity.md): market scale, sustained growth, hierarchy, and white-label decision boundaries.
-- [Opportunity-judgment method](topics/category-opportunity-method.md): the only topic needed for the current analysis node.
-
-Data collection mechanics are in `data-contract.md`, loaded at Main Line Step 3 rather than through this judgment route.

package/skills/yuce-category-opportunity-report/references/log.md

@@ -1,29 +0,0 @@
-# Knowledge Log
-
-## 2026-10-04 · table/chart views
-
-- Every table now has independently selectable table and chart views backed by raw numeric evidence; table remains the default.
-- Monthly series use lines; category comparisons use grouped bars, separate unit/metric groups and selectable series. Full-list charts follow filters/order and disclose paging.
-- Zero baselines, negative values, null gaps, exact-value labels and self-contained SVG are deterministic contracts. Browser visual checks remain separately reportable.
-
-## 2026-10-02 · relative capacity and multiple routes
-
-- User confirmed simultaneous large, medium, and medium-small market research routes and category-relative capacity boundaries.
-- Added distribution diagnostics, reviewable quantiles, boundary sensitivity, independent ranking and full exclusion coverage; competition remains a separate evidence gate.
-- Contract v2 uses strategy-config; former single-queue decision files require migration. Quantile positions and growth-strength index remain provisional methods, not validated commercial success estimates.
-
-## 2026-09-26 · reading-first report
-
-- User accepted a reading-first HTML sample as the development standard for report usability. Compiled its reusable information order—three decisive judgments, compact shortlist comparison, visible selection funnel, deferred formula, and explicit entry-decision boundary—without bundling the accepted example or category-specific conclusions into the runtime Skill.
-
-## 2026-09-26
-
-- User-confirmed report improvements: one submenu per deep-research category, numbered and visually emphasized data interpretations, one filterable/sortable table covering every 三级类目 with 二级 membership, and an explicit size-and-growth ranking indicator shown in that table.
-- Compiled a transparent within-category 持续增量贡献 index and top-N selection rule. Monthly category data supports quantified market reading; product-use scenarios and white-label viability remain separate validation questions.
-
-## 2026-09-25
-
-- Added a content-preserving analysis/output contract: transparent screened pool, reviewed priorities, benchmark, watch/defer evidence, matched-month comparisons, and six report views. The kitchen baseline is development evaluation evidence, not a runtime dependency.
-- Added supplied-Excel input and a shared local Excel-cache analysis path. The Excel route bypasses NAS and yccli; the NAS route creates the same cache after local export/collection.
-- Compiled the user's 24-month first/second/third-category research flow and the white-label research-priority boundary.
-- Added a preliminary quantitative screening method with explicit limits; market signals do not establish product differentiation or operating profit.

package/skills/yuce-category-opportunity-report/references/queries/assess-category-opportunity.md

@@ -1,7 +0,0 @@
-# Query: Which categories deserve deeper research?
-
-Trigger: Main Line Step 5, after normalized 24-month monthly data is available.
-
-Read [category-opportunity-method](../topics/category-opportunity-method.md). Ask: Which subcategories combine meaningful size and sustained growth, which are merely large, and what evidence is still needed before a white-label entry decision?
-
-Output: a traceable research queue, a scale benchmark, counterarguments, data-quality caveats, and next validation questions. Return to Main Line Step 5 to build the analysis JSON and HTML.

package/skills/yuce-category-opportunity-report/references/source-manifest.md

@@ -1,14 +0,0 @@
-# Source Manifest
-
-Compiled: 2026-10-02. Coverage: partial. Runtime does not require the creator's private Wiki.
-
-Source classes (W/U/E/A) distinguish compiled domain knowledge, user-confirmed intent, executable evidence, and provisional assumptions:
-
-- `U`: user-confirmed project purpose—seek sizable, growing category spaces where white-label product differentiation may be researched. The user may provide Excel directly for offline analysis; the NAS route checks stored data, fills only missing months, defaults to incremental import, and asks consent before collection if database reads fail. Both routes first create a local Excel cache and analyze that cache. Current report requirements include a reading-first opening with three clear judgments, a compact shortlist comparison, a visible selection funnel, and a deferred formula; the user accepted an example as the development standard, not as a bundled runtime dependency. Other accepted requirements include a transparent size-and-growth indicator, data-grounded numbered interpretations, one submenu per deep-research category, and one filterable/sortable all-leaf table with 二级 membership. Earlier accepted coverage also includes screening, benchmark, watch/defer, monthly evidence, and explicit next validation.
-- `W`: general ecommerce selection knowledge—market size alone is insufficient; test need, differentiation, margin, supply, and small-batch validation. Compiled from the general Wiki's “市场分层与选品策略” and “产品开发思维与市场机会判断” pages. Report evidence hierarchy and timing were compiled from “电商数据报告内容规范”. Private paths and examples were not copied.
-- `E`: yccli 0.5.0 supports first/second/third monthly JSON. tbcli source checkout provides additive Yuce JSON import and read-only path coverage/export; source tests pass on Codex/macOS. Six existing kitchen workbooks produced a 3852-row, single-sheet 24-month local cache without NAS access; conflict and overwrite tests passed. VPN-connected database access was intermittent, so no continuous-service claim is made.
-- `U`: simultaneous large/medium/medium-small route outputs and capacity defined by each category's characteristics instead of absolute money. Large-market increment research remains an available direction. Size does not establish brand competition.
-- `A`: reviewable P40/P70/P90 capacity boundaries; both annual and six-month growth at least 20%, 10 positive months; independent sustained-increment and sustained-growth-strength ranking. These provisional methods require distribution/sensitivity review and do not estimate future sales or white-label success. No claim is made that the quantiles are commercially optimal.
-- `E`: deterministic v2 tests cover scale invariance, tied boundaries, sparse and empty populations, missing/zero-base periods, policy validation and source/non-overwrite safety. Local historical cache main run outputs all three routes. No new competition observations were collected.
-
-Critical gaps: no product/shop-ranking, brand concentration, price, reviews, costs, or supplier evidence in category monthly data. A 24-month window supports one full-year comparison, not multi-year trend proof. Recompile this knowledge layer when the user approves a different screening standard or validated deeper evidence changes the method.

package/skills/yuce-category-opportunity-report/references/topics/category-opportunity-method.md

@@ -1,39 +0,0 @@
-# Category Opportunity Judgment
-
-## Intent and evidence boundary
-
-Start from a familiar 一级类目 while looking beyond the seller's existing assortment. Always offer large, medium, and medium-small market research routes so users can choose different market sizes. A large growing market may have strong brands; a smaller market may also be highly concentrated. Category monthly totals cannot establish white-label accessibility. This scope and simultaneous-route requirement are user-confirmed. `U`
-
-## Read the market before ranking
-
-Use 24 completed months: latest 12 vs preceding 12, corresponding-month growth counts, and latest six vs the same six last year. Examine first/second-level scale, increment and share shifts, plus third-level distribution and hierarchy reconciliation. Withhold unsupported growth on missing or zero-base data. One 24-month series supports one full-year comparison, not a proven multiyear trajectory. `U/E`
-
-## Relative capacity with category-specific review
-
-Define the population as complete, positive-recent-GMV third-level paths under the same first-level category, preserving full taxonomy paths. Record count, median, p10/p90, top-decile share of this population's GMV, missingness and ties. This measures category-size distribution, not seller or brand concentration. Broad administrative categories and narrow product categories may not be equally granular; name that limitation. `A/E`
-
-Start provisionally at P40/P70/P90: below P40 watch; P40–P70 medium-small; P70–P90 medium; P90+ large. These are reviewable relative positions, not confirmed universal business rules. The current category's observed distribution supplies monetary boundaries. Consider taxonomy granularity, skew, sparse/tied data, sensitivity and the user's sales ambitions when reviewing the positions. Record why they were retained or adjusted. Do not claim statistical adaptivity establishes optimal commercial bands. `A`
-
-Quantiles use linear interpolation of sorted observed annual amounts. Same amounts stay in one band; exact boundary values enter the higher band. Small populations and coincident cutoffs can create empty routes: show them rather than force candidates. Show ±5-point joint quantile-shift sensitivity. Exclude incomplete and nonpositive observations from the quantile population, keeping them in the full table. A lower boundary prevents relative tail selection but does not guarantee enough money for a business; evaluate target revenue divided by category size later as a required-share scenario, not a share forecast. `A`
-
-## Independent research routes
-
-All routes first require complete data, calculable growth, both growth floors and persistent positive months. Reviewable defaults: annual and latest-six-month YoY each at least 20%, at least 10 positive corresponding months. Mixed “其他/其它” classes require decomposition and remain visible outside ranked pools. `A`
-
-- Large-market increment: rank by 100 × max(annual increment,0) / root latest annual GMV × positive months / 12. Retains the original aim of finding substantial new demand.
-- Medium-capacity sustained growth: rank by 100 × min(annual YoY, latest-six-month YoY) × positive months / 12.
-- Medium-small-capacity growth: same strength metric, independently ranked in its own capacity band.
-
-The latter metric gives no extra reward for capacity once the band is satisfied. It is still sensitive to base effects. Annual and half-year periods overlap and are not independent confirmations. All scores are transparent heuristics for research ordering, not profit forecasts or scientific success probabilities. Tie-break on positive months then full path. Output the complete pool and top N per route (default six); never mix different metrics into one global top list. Keep a largest-market benchmark and measured watch/defer counterexamples. `U/A`
-
-## Growth diagnostics and next evidence
-
-Compare first-half and second-half YoY within the recent year to describe acceleration/deceleration; a provisional 3-percentage-point tolerance labels similar speeds. Show top-three positive monthly increments divided by all positive monthly increments; high concentration asks for seasonal/source verification, not automatic rejection. Never turn missing histories into zero or claim a newly observed taxonomy path is a new consumer market. `A/E`
-
-Before deep product research, perform a separately authorized lightweight competition check: product/shop rankings, brand grouping, non-leading sellers' turnover, price bands and sampled coverage. Ranking-sample brand shares do not equal whole-market shares; seller and brand concentration are different concepts. Then investigate demand, product differences, suppliers and full economics. Monthly category data cannot answer those questions. `U/W`
-
-## Reading-first report
-
-Every table is paired with a selectable chart of the same evidence. Preserve exact values in the table and point/bar tooltips; use chronological lines for monthly data, grouped zero-based bars for category comparisons, and separate unit/metric groups rather than misleading shared axes. Charts must follow table filtering and ordering; long lists disclose pagination. Missing data creates gaps, not zeroes. This display requirement is user-confirmed. `U`
-
-Open with three concise data-grounded market judgments and all route summaries. Each route shows its relative band and actual amount boundaries, population/pool/shortlist funnel, distinct metric, and linked candidates. Put full formulas and distribution review in disclosure. Preserve all hierarchy tables, full per-route shortlists, individual submenu pages with 12 month-matched comparisons, benchmark, watch/defer and one searchable, filterable, numerically sortable full third-level table including incomplete paths and exclusion reasons. Selective color, bold and italic support numbered explanations. `U`