diff --git a/equity-research/docs/company-research-compliance-checklist.md b/equity-research/docs/company-research-compliance-checklist.md new file mode 100644 index 0000000..d7ea783 --- /dev/null +++ b/equity-research/docs/company-research-compliance-checklist.md @@ -0,0 +1,35 @@ +# Company Research Compliance Checklist + +Use this checklist before a report draft is considered complete. + +## Must Pass + +- report does not contain a formal rating by default +- report does not contain a target price by default +- source or scope disclosure is present +- `数据来源与口径说明` section exists +- if degraded mode applies, the missing-data disclosure is explicit +- no core conclusion is supported only by news/media + +### Citation density (inline references) + +- [ ] Class A (首次覆盖): 正文行内引用数量 ≥ 10 +- [ ] Class B (更新报告): 正文行内引用数量 ≥ 5 +- [ ] Class C/D (一般分析/简报): 正文行内引用数量 ≥ 3 +- [ ] 每个财务表格中的来源列无空白（或标注 N/A 并在口径说明中解释） +- [ ] 估值可比公司数据有来源标注 + +## Fail Conditions + +Fail the report if any of the following is true: + +- prohibited default rating language appears +- target price appears without explicit user request +- major claims lack attributable support +- degraded mode was required but not disclosed +- **Class A inline citations < 5** (hard floor, even below the ≥10 target) +- **财务表格来源列有空白且无 N/A 标注** + +## Completion Gate + +Compliance passes only if all must-pass items are satisfied. diff --git a/equity-research/docs/company-research-degraded-mode.md b/equity-research/docs/company-research-degraded-mode.md new file mode 100644 index 0000000..028a147 --- /dev/null +++ b/equity-research/docs/company-research-degraded-mode.md @@ -0,0 +1,139 @@ +# Company Research Degraded Mode Policy + +This document defines how the company research report agent must behave when evidence is incomplete, stale, or conflicting. + +The purpose is to prevent fabricated confidence and keep the output honest and useful. + +## Principle + +If the agent lacks the evidence needed for a full report, it must downgrade the output rather than improvise. + +## When To Trigger Degraded Mode + +Trigger degraded mode when any of the following is true: + +- the company cannot be uniquely identified +- there is no current official disclosure source +- current financial data is missing +- source conflicts affect core facts +- peer group cannot be established with reasonable support +- valuation inputs are missing or unreliable + +## Section-Level Degradation (Class A initiating coverage) + +Not all evidence gaps require full-report degradation. The following triggers cause **section-level degradation** while the overall report can remain Level A: + +| Trigger | Affected section | Degradation behavior | +|---------|-----------------|---------------------| +| Comparable company data unavailable | §7.5.1 可比公司法 | Section appears with note: "数据不足，无法建立可比框架。缺失：[具体数据项]" | +| Only 1 fiscal year of financial data | §5 财务分析 | Section appears with reduced table (1 year only), note: "仅获取1个完整财年数据，趋势分析受限" | +| Revenue breakdown unavailable | §4 业务与竞争力分析 | Section notes: "收入结构未披露，以下分析基于合并口径" | +| Scenario assumptions lack quantitative basis | §7.5.3 情景分析 | Section appears with qualitative-only scenarios, note: "定量数据不足，仅提供定性情景描述" | +| Operating KPI historical data unavailable | §5.3 运营 KPI | Section notes: "核心运营指标历史数据不可得，无法展示趋势" | + +**Rule: Sections must never be silently omitted.** A degraded section with an explicit data-gap note is always preferred over a missing section. + +## Output Levels + +### Level A: Full report allowed + +Conditions: + +- sufficient primary disclosure exists +- current financial data exists +- source conflicts are minor or resolved + +Output: + +- full draft report +- source appendix +- standard summary + +### Level B: Analysis note only + +Conditions: + +- company is identifiable +- some official information exists +- but evidence is insufficient for a full report + +Output: + +- short-form company analysis note +- missing-data disclosure +- no strong valuation conclusion + +### Level C: Clarification required + +Conditions: + +- company identity unclear +- disclosure unavailable +- request too ambiguous + +Output: + +- request clarification +- list missing inputs +- do not generate report content + +## Mandatory Degraded Disclosures + +Whenever degraded mode is triggered, the output must state: + +- what information is missing +- why that matters +- what was still possible to analyze +- what the user can provide or what source needs to be added + +## Forbidden In Degraded Mode + +Do not output: + +- formal rating +- target price +- precise unsupported financial projections +- unsupported peer conclusions +- fake certainty language + +Avoid: + +- `明确将` +- `必然` +- `确定会` +- `强烈看好` + +Prefer: + +- `当前证据不足以支持` +- `需继续补充` +- `现阶段判断偏审慎` +- `以下结论仅基于有限公开信息` + +## Minimum Templates By Mode + +### Level B template + +Must include: + +1. `当前可得结论` +2. `已确认事实` +3. `暂无法确认的关键问题` +4. `需补充的数据或资料` +5. `初步风险提示` + +### Level C template + +Must include: + +1. `当前无法开始完整分析` +2. `原因` +3. `需要补充的信息` + +## Completion Gate + +If degraded mode is triggered, the task is complete only if: + +- the correct downgraded format was used +- the missing-data disclosure is explicit +- no prohibited output appears diff --git a/equity-research/docs/company-research-evidence-contract.md b/equity-research/docs/company-research-evidence-contract.md new file mode 100644 index 0000000..46f0ba6 --- /dev/null +++ b/equity-research/docs/company-research-evidence-contract.md @@ -0,0 +1,213 @@ +# Company Research Evidence Collection Contract + +This document defines the minimum evidence package required before the agent may draft a report. + +It separates: + +- mandatory evidence +- optional evidence +- drafting block conditions +- degraded-mode trigger conditions + +## Core Principle + +Drafting starts only after the minimum evidence threshold is met. + +If the threshold is not met, the agent must switch to degraded mode or request clarification. + +## Mandatory Evidence + +### Company identity + +Required: + +- company legal or commonly accepted name +- ticker if public and available +- market or listing venue when relevant + +Drafting block: + +- company identity is ambiguous + +### Primary company disclosure + +Required: + +- at least one official disclosure source + +Examples: + +- 10-K +- 10-Q +- annual report +- quarterly report +- exchange announcement +- official IR presentation + +Drafting block: + +- no current primary disclosure is available + +### Current financial evidence + +Required: + +- at least one current financial evidence source + +Examples: + +- latest filing financials +- official results release +- structured current company facts + +Drafting block: + +- no current financial evidence exists + +### Financial depth (Class A initiating coverage) + +Required: + +- at least 2 complete fiscal years of revenue, profit, and cash flow data +- latest period (quarterly or semi-annual) key metrics +- if unlisted, at least prospectus or funding round financial summary + +Examples: + +- FY2023 + FY2024 annual reports with income statement, balance sheet, cash flow +- latest quarterly filing (10-Q / semi-annual report) +- pre-IPO prospectus financials + +Drafting block: + +- zero fiscal years of structured financial data available + +Degraded trigger: + +- only 1 fiscal year available → report degrades to Level B (analysis note), explicitly labeled + +### Revenue breakdown + +Required (Class A): + +- revenue split by business line, geography, or customer type + +Degraded trigger: + +- revenue breakdown unavailable → §4 must note "收入结构未披露，以下分析基于合并口径" + +### Operating KPIs + +Required (Class A): + +- at least 2 core operating KPIs with historical data (2+ periods) +- KPIs should reference `sector-kpis-{sector}.md` when available + +### Comparable company data (Class A) + +Required: + +- at least 3 comparable companies identified +- core valuation multiples for each (EV/Revenue, EV/EBITDA, P/E as applicable) + +Degraded trigger: + +- comparable data unavailable → valuation section must note "无法建立可比框架" with specific missing data items, not be omitted + +### Company or market context + +Required: + +- at least one context source + +Examples: + +- company profile +- market profile data +- official company presentation +- official management communication + +### Risk-oriented evidence + +Required: + +- at least one risk-oriented source or evidence set + +Examples: + +- filing risk factors +- recent risk disclosure +- material event disclosure + +## Optional Evidence + +Useful but not strictly required for every report: + +- earnings transcript +- external industry dataset +- peer market data +- external event/news support + +## Additional Requirements By Report Type + +### Initiating coverage + +Required minimum: + +- primary disclosure (at least one official source) +- financial depth: 2+ fiscal years revenue/profit/cash flow + latest period +- revenue breakdown by segment/geography/customer +- 2+ core operating KPIs with historical trend +- 3+ comparable companies with valuation multiples +- market/profile context +- management communication or equivalent +- risk-oriented evidence + +Recommended: + +- earnings transcript +- industry dataset for sector context + +### Earnings review / company update + +Recommended minimum: + +- latest results source +- recent company announcement or filing +- current financial evidence + +## Drafting Block Conditions + +The agent must not generate a full report draft if: + +- company identity is unclear +- official disclosure is unavailable +- financial evidence is missing +- core facts are materially conflicting and unresolved + +## Degraded-Mode Conditions + +The agent may produce only a downgraded note if: + +- company identity is clear +- some official evidence exists +- but the full-report threshold is not met + +## Required Evidence Output Structure + +Before drafting, the agent should be able to produce: + +1. company identity summary +2. source inventory +3. current financial evidence summary +4. context evidence summary +5. risk evidence summary +6. evidence gaps + +## Completion Gate + +Evidence collection is complete only if: + +- mandatory evidence is present or the run has explicitly switched to degraded mode +- the source inventory is explicit +- drafting block conditions have been checked diff --git a/equity-research/docs/company-research-feishu-delivery.md b/equity-research/docs/company-research-feishu-delivery.md new file mode 100644 index 0000000..7b76ff8 --- /dev/null +++ b/equity-research/docs/company-research-feishu-delivery.md @@ -0,0 +1,151 @@ +# Company Research Feishu Delivery Specification + +This document defines how the company research agent should return results to Feishu in V1. + +The goal is a reliable first experience, not a feature-complete messaging workflow. + +## V1 Delivery Principle + +Keep delivery simple: + +- short summary in the Feishu message +- full report written to a Feishu Doc first +- local markdown kept only as an internal artifact +- optional docx later + +Do not block launch on rich cards or complex approval interaction. + +## Hard Requirement + +For any successful full-report delivery: + +- the agent must create a Feishu Doc +- the agent must write the report body into that doc +- the agent must read or otherwise confirm the resulting doc token or URL +- the final reply must include the Feishu Doc URL +- the body must be verified to exist; a title-only doc does not count + +A local file path alone does not count as successful user delivery. + +## V1 Response Types + +### Type 1: Full report success + +Return: + +- a concise summary message +- the Feishu Doc URL +- data/source note + +Internal markdown may still be written for audit or debugging, but it must not be the only user-facing artifact. + +Message should include: + +- company name +- report type +- completion status +- top 3-5 findings +- note on evidence scope + +### Type 2: Degraded analysis success + +Return: + +- short analysis summary +- explicit missing-data disclosure +- Feishu Doc URL if a degraded note was generated and delivered successfully + +### Type 3: Clarification required + +Return: + +- why the task cannot proceed +- what user input is needed next + +## Summary Message Structure + +Use this order: + +1. task completion line +2. report type and company +3. top findings +4. source or scope disclosure +5. Feishu Doc link + +## V1 Message Template + +```text +已完成：{company} {report_type} 初稿 + +核心结论： +1. {finding_1} +2. {finding_2} +3. {finding_3} + +说明： +- 本稿为研究初稿，默认不含正式评级和目标价 +- 主要依据：{source_summary} + +飞书文档： +- {document_url} + +本地留档： +- {artifact_reference} +``` + +## Artifact Rules + +V1 artifact priority: + +1. Feishu Doc +2. markdown +3. docx +4. pdf + +Use deterministic file names: + +- `{company}_{report_type}_{YYYYMMDD}.md` +- `{company}_{report_type}_{YYYYMMDD}.docx` + +Feishu Doc title should be deterministic: + +- `{company} {report_type} {YYYY-MM-DD}` + +## Feishu Doc Write Sequence + +The delivery path must follow this sequence: + +1. create Feishu Doc +2. write report body into Feishu Doc +3. verify that the doc contains body content, not just a title block +4. return the URL in the final message + +Preferred runtime path: + +- use a deterministic report-to-Feishu writer script when available +- do not rely on free-form tool chatter to decide whether the body was written + +Do not assume `create` writes the body. +Do not return success if only a local markdown file exists. +Do not return success if the document only contains the title page. + +## Failure And Timeout Messaging + +If the run fails or times out, return: + +- failure reason in plain language +- whether partial work exists +- whether the user should retry or provide more data + +Do not return raw stack traces or tool noise. + +## Compliance Rules For Delivery + +Before sending a success message: + +- confirm whether the artifact passed the compliance checklist +- confirm whether the artifact passed the quality checklist +- confirm whether a Feishu Doc URL exists and is usable as the primary user-facing artifact +- confirm that the Feishu Doc has body content, not just a title block + +If not, do not present the run as complete. diff --git a/equity-research/docs/company-research-implementation-summary.md b/equity-research/docs/company-research-implementation-summary.md new file mode 100644 index 0000000..0a05c96 --- /dev/null +++ b/equity-research/docs/company-research-implementation-summary.md @@ -0,0 +1,41 @@ +# Company Research Implementation Summary + +This summary collects the paths, runtime artifacts, and documentation that describe the current `company-research` agent in the target runtime. + +## Runtime paths + +- Agent bootstrap: `/BOOTSTRAP.md` +- Workspace docs: `/equity-research/docs/*` +- Report writer helper: `/scripts/write_report_to_feishu_doc.py` +- Report folder: `/reports` + +## Key documents (repo) + +1. `company-research-report-agent-handoff.md`: bot binding notes, redacted live-delivery facts, delivery caveats. +2. `company-research-report-agent-implementation-plan.md`: Function inventory, gating status, verified delivery facts. +3. `company-research-message-gating.md`: Allowed user message types, banned process chatter. +4. `company-research-recency-authority-gate.md`: Authority order, recency checks, high-value retrieval prompt. +5. `company-research-feishu-delivery.md`: Feishu doc delivery sequence and body verification. +6. `company-research-workflow.md`: Updated workflow order (classification → recency gate → evidence → body → verification → delivery). +7. `company-research-regression-suite.md`: Per-function regression requirements plus user-visible transcript expectations. + +## Execution pipeline + +1. **Classification (A/B/C/D)** – determines template and downstream requirements. +2. **Recency/Authority gate** – high-value retrieval prompt, latest official disclosure check, downgrade rules. +3. **Evidence/Fact Pack** – gather structured sources; respond with data inventory. +4. **Body & Summary** – nine-section Chinese template + valuations/scenarios; apply message gating for final response only. +5. **Delivery** – run `scripts/write_report_to_feishu_doc.py`, verify `verified_block_count > 0`, then send final message with Feishu link. + +## Support files + +- `AGENTS.md`: enumerates reading order. +- `company-research-request-classification.md`: defines Class A/B/C/D behaviors. +- `company-research-evidence-contract.md`: mandatory evidence thresholds. +- `company-research-output-contract.md`: output structure requirements. +- `company-research-source-hierarchy.md`: source priority. + +## Next steps + +- Continue to rerun `openclaw sessions cleanup` if old context leaks. +- Use the CLI to regenerate a test document as needed for verification; do not commit live document URLs. diff --git a/equity-research/docs/company-research-message-gating.md b/equity-research/docs/company-research-message-gating.md new file mode 100644 index 0000000..6c4dc0d --- /dev/null +++ b/equity-research/docs/company-research-message-gating.md @@ -0,0 +1,110 @@ +# Company Research User Message Gating + +This document defines what the agent may and may not send to the end user during report generation. + +The purpose is to stop internal process chatter from leaking into Feishu. + +## Core Rule + +Only send a user-facing message if it changes the user's next decision or gives the user the final result. + +If a message does not change the user's next decision, do not send it. + +## Allowed User-Facing Message Types + +### Type 1: Intake acknowledgement + +Allowed once near the start of the run. + +Use for: + +- confirming the request was accepted +- confirming the intended report type +- confirming the agent will use current official and high-value sources first + +Good example: + +- `已开始生成泡泡玛特公司分析报告，将优先使用最新披露、业绩材料和可复核市场信息。` + +### Type 2: Clarification request + +Allowed only if a blocking ambiguity exists. + +Use for: + +- company identity ambiguity +- missing market/ticker when multiple listed entities match +- missing user choice that materially changes the report path + +Rule: + +- ask one concise question +- do not ask multiple speculative follow-ups + +### Type 3: Blocking data warning + +Allowed only if the agent cannot continue to a valid full report. + +Use for: + +- latest disclosure unavailable +- current financial evidence unavailable +- only stale or low-authority evidence found + +Good example: + +- `目前未取到泡泡玛特最新正式披露期的核心财务资料，不能按当前深度报告标准完成。` + +### Type 4: Final result + +Allowed once the run is complete. + +Must contain: + +- completion status +- report type +- 3-5 key findings +- scope/source disclosure +- Feishu Doc URL + +### Type 5: Final failure + +Allowed if the run cannot produce a compliant output. + +Must contain: + +- plain-language failure reason +- whether partial work exists +- what the user should do next, if anything + +## Prohibited User-Facing Messages + +Never send these to the user: + +- `我现在需要收集更多信息` +- `让我继续收集` +- `我需要读取文件` +- `我现在创建报告文件` +- `我现在创建飞书文档` +- `我现在写入飞书文档` +- any tool-by-tool progress chatter +- any chain-of-thought style narration + +These are internal execution steps, not user value. + +## Message Filtering Test + +Before sending a message, ask: + +1. Does this change what the user should do next? +2. Does this provide the final result? +3. Does this explain a real blocking failure? + +If the answer to all three is no, do not send the message. + +## Completion Gate + +Message gating is satisfied only if: + +- no internal process chatter is sent to the user +- only allowed message types appear in the user-visible transcript diff --git a/equity-research/docs/company-research-model-strategy.md b/equity-research/docs/company-research-model-strategy.md new file mode 100644 index 0000000..e421fec --- /dev/null +++ b/equity-research/docs/company-research-model-strategy.md @@ -0,0 +1,44 @@ +# Company Research Model Layering Strategy + +This document defines the recommended model allocation for each workflow step. + +## Principle + +Different workflow steps have different cognitive demands. Allocate model capability where it matters most (analytical reasoning, structured writing), and use cost-efficient models for mechanical tasks (retrieval, classification, checklist comparison). + +## Model Allocation by Workflow Step + +| Step | Task | Cognitive demand | Recommended model tier | Notes | +|------|------|-----------------|----------------------|-------| +| 1 | Request classification | Low (pattern matching) | Standard | Qwen3-Max or equivalent | +| 2 | Recency and authority gate | Low (date/source comparison) | Standard | Qwen3-Max or equivalent | +| 3 | Evidence collection | Medium (tool calling accuracy) | Standard | Tool calling reliability is key; Qwen3-Max or Kimi K2.5 | +| 4 | Fact Pack | Low (structured extraction) | Standard | Qwen3-Max or equivalent | +| 4.5 | Analysis Kit Construction | **High** (financial reasoning, peer selection, risk analysis) | **Reasoning** | DeepSeek-R1 or Kimi K2.5 thinking mode. This step requires financial modeling logic and multi-factor comparison | +| 5 | Investment View Pack | High (judgment synthesis) | Reasoning or Strong writing | Based on Analysis Kit, needs analytical coherence | +| 6 | Body Draft | **High** (structured writing under constraints) | **Strong writing** | Must follow template structure precisely while maintaining quality prose. Needs long-context capability | +| 7 | Front Page Summary | Medium (distillation) | Strong writing | Extract key points from body, maintain Goldman-style format | +| 8 | Verification | Low (checklist comparison) | Standard | Mechanical checklist evaluation | +| 9 | Delivery preparation | Low (API calling) | Standard | Feishu Doc creation is tool-based | + +## Model Tier Definitions + +| Tier | Characteristics | Current options in staging | +|------|----------------|----------------------| +| Standard | Good tool calling, cost-efficient, fast | Qwen3-Max (DashScope) | +| Reasoning | Strong logical reasoning, thinking mode | DeepSeek-R1 (Volcengine), Kimi K2.5 thinking | +| Strong writing | High quality prose, long context, structure adherence | Kimi K2.5, GLM-4.7 (Volcengine) | + +## Cost Optimization Notes + +- Steps 1-4 and 8-9 are high-frequency, low-complexity — use the cheapest reliable model +- Step 4.5 is the highest-value reasoning step — invest in model quality here +- Step 6 requires the longest output — consider models with favorable output token pricing +- If budget is constrained, prioritize upgrading Step 4.5 and Step 6 first + +## Implementation Notes + +- Model selection is configured via `models.json` in the agent runtime +- Current runtime uses a single model for all steps +- Multi-model routing requires OpenClaw's per-step model override capability (verify availability before implementing) +- If per-step override is not available, use the strongest available model for all steps as the default diff --git a/equity-research/docs/company-research-output-contract.md b/equity-research/docs/company-research-output-contract.md new file mode 100644 index 0000000..aa08cb3 --- /dev/null +++ b/equity-research/docs/company-research-output-contract.md @@ -0,0 +1,115 @@ +# Company Research Output Contract + +This document defines the required output structures for the company research report agent. + +## Output Types + +### Output A: Full report success + +Must contain: + +- company name +- report type +- summary findings +- Feishu Doc URL +- source/scope note + +May also contain: + +- internal markdown artifact reference + +Must not contain by default: + +- formal rating +- target price + +### Output B: Degraded analysis success + +Must contain: + +- company name +- degraded status +- current conclusions +- missing-data disclosure +- next-step or missing-input note + +If a degraded note is delivered successfully in Feishu, it must also contain: + +- Feishu Doc URL + +### Output C: Clarification required + +Must contain: + +- reason the task cannot proceed +- exact clarification needed + +## Full Report Artifact Requirements + +The artifact must include: + +- the approved Chinese section structure (§1-§9) +- `数据来源与口径说明` +- risk section with severity classification (高/中/低) + +### Analytical Structure Requirements (by report type) + +#### Class A (首次覆盖) — all required unless degraded + +| Structure | Requirement | +|-----------|-------------| +| 核心财务摘要表 (§5.1) | 必填。至少 7 行指标 × 2 年数据，每行有来源列 | +| 运营 KPI (§5.3) | 必填。至少 2 个核心 KPI 含历史趋势 | +| 可比公司表 (§7.5.1) | 必填。至少 3 家可比公司 + 选择理由。数据不足时标注"数据不足，无法建立可比框架" | +| 情景分析表 (§7.5.3) | 必填。Bull/Base/Bear 含概率权重和核心假设。数据不足时标注原因 | +| 风险矩阵 (§8.1) | 必填。按严重性×概率分层 | +| 反证与下行风险 (§8.2) | 必填。至少一条与核心结论相反的反证线索 | +| 行内引用 | 正文 ≥ 10 处行内引用 | +| 首页指标快照 | 必填。关键财务指标 + Bull/Base/Bear 一行摘要 | + +#### Class B (公司更新/财报点评) — 简化 + +| Structure | Requirement | +|-----------|-------------| +| 核心财务摘要表 (§5.1) | 必填。可只含最新 1-2 期 | +| 运营 KPI (§5.3) | 推荐 | +| 可比公司表 (§7.5.1) | 可选 | +| 情景分析表 (§7.5.3) | 可选 | +| 风险矩阵 (§8.1) | 推荐 | +| 行内引用 | 正文 ≥ 5 处行内引用 | + +#### Class C/D (一般分析/快速简报) — 最低 + +| Structure | Requirement | +|-----------|-------------| +| 核心财务摘要表 (§5.1) | 推荐 | +| 行内引用 | 正文 ≥ 3 处行内引用 | + +### Degradation Rules for Analytical Structures + +When required data is unavailable: + +- The structure itself must still appear in the report +- Content is replaced with explicit degradation note: "当前证据不足以完成此分析，缺失：[具体数据项]" +- The structure must not be silently omitted + +The user-facing artifact for successful report runs must be a Feishu Doc. +Local markdown is an internal artifact, not the primary delivery surface. + +## Summary Requirements + +The summary must include: + +- 3-5 key findings at most +- no exaggerated recommendation wording +- a scope or evidence note +- the Feishu Doc URL for successful report runs + +## Completion Gate + +An output passes contract review only if: + +- it matches one of the defined output types +- required fields are present +- prohibited default items are absent +- successful report responses include a usable Feishu Doc URL diff --git a/equity-research/docs/company-research-provider-matrix.md b/equity-research/docs/company-research-provider-matrix.md new file mode 100644 index 0000000..25312d5 --- /dev/null +++ b/equity-research/docs/company-research-provider-matrix.md @@ -0,0 +1,123 @@ +# Company Research Launch Provider Matrix + +This document fixes the V1 provider stack for the company research report agent. + +The purpose is to remove ambiguity before runtime implementation. + +## V1 Launch Scope + +Launch market: + +- US public equities first + +Reason: + +- official SEC disclosure is accessible +- transcript and baseline market-data tooling are easier to source +- evidence hierarchy is easier to enforce + +## Provider Matrix + +### Company filings and structured fundamentals + +Primary: + +- `sec-edgar-mcp` + - SEC filings + - company facts + - structured regulatory data + +Fallback: + +- `sec-edgar-toolkit` + +### Market and company profile data + +Primary: + +- `OpenBB` + +Use for: + +- price history +- company profile +- market context +- baseline fundamentals when available + +### Earnings transcripts and event context + +Primary: + +- `earningscall-python` + +Fallback: + +- `Octagon MCP Server` + +### Supplemental event/news context + +Primary: + +- OpenClaw web search and fetch + +Restriction: + +- may supplement context +- may not serve as sole support for core report conclusions + +### Citation layer + +Primary: + +- `rag-citation` + +### Artifact export + +Primary: + +- Feishu Doc for user-facing delivery + +Secondary: + +- markdown as internal artifact + +- `docxtemplater` for editable docx output + +## Minimum Data Coverage By Report Type + +### Initiating coverage + +Required: + +- official filing source +- current financial source +- market/profile source +- transcript or equivalent management communication + +### Earnings review / company update + +Required: + +- latest filing or official announcement +- latest period financial data +- recent management communication if available + +## Current V1 Choice Summary + +- filings: `sec-edgar-mcp` +- filings fallback: `sec-edgar-toolkit` +- market/profile: `OpenBB` +- transcripts: `earningscall-python` +- transcript fallback: `Octagon MCP Server` +- supplementary search: OpenClaw web search +- citations: `rag-citation` +- delivery: Feishu Doc first, markdown internal, docx later + +## Out Of Scope For V1 + +Do not block launch on: + +- proprietary paid terminals +- multi-market support +- full real-time pricing infrastructure +- deeply customized valuation databases diff --git a/equity-research/docs/company-research-quality-checklist.md b/equity-research/docs/company-research-quality-checklist.md new file mode 100644 index 0000000..8fbe29c --- /dev/null +++ b/equity-research/docs/company-research-quality-checklist.md @@ -0,0 +1,75 @@ +# Company Research Quality Checklist + +Use this checklist after compliance passes. + +## Must Pass — Structure + +- [ ] all required report sections are present (§1-§9) +- [ ] the report follows the approved Chinese section order +- [ ] artifact reference is present in the delivery-ready response + +## Must Pass — Analytical Depth (Class A initiating coverage) + +### Financial analysis (§5) + +- [ ] 核心财务摘要表存在且至少有 2 年数据 +- [ ] 摘要表至少 7 行指标（营收、营收YoY%、毛利率、净利润、净利率、经营现金流、自由现金流） +- [ ] 至少 3 个关键指标有 YoY 变化率 +- [ ] 至少 2 个运营 KPI 有历史趋势（或降级标注） + +### Valuation (§7.5) + +- [ ] 可比公司表存在且至少 3 家（或降级标注"数据不足"） +- [ ] 可比选择理由已说明 +- [ ] Bull/Base/Bear 三情景已给出（或降级标注原因） +- [ ] 若无法估值，已明确说明原因和缺失数据 + +### Risk (§8) + +- [ ] 风险按严重程度分层（高/中/低） +- [ ] 每个风险有传导机制说明 +- [ ] 至少有一条与核心结论相反的反证 + +### Inline citations + +- [ ] 每个财务数字有行内引用 +- [ ] 正文行内引用总计 ≥ 10 处 +- [ ] §9 数据来源具体到文件名/页码/日期，非泛泛"公司公告" + +### Front page summary + +- [ ] 关键财务指标快照表存在 +- [ ] Bull/Base/Bear 一行摘要存在 +- [ ] 最大风险一句话存在 + +## Must Pass — Analytical Depth (Class B company update) + +- [ ] 核心财务摘要表存在（可只含最新 1-2 期） +- [ ] 正文行内引用 ≥ 5 处 +- [ ] 风险部分存在 + +## Must Pass — Tone and Evidence + +- [ ] key claims are evidence-backed +- [ ] risk section is present +- [ ] language remains cautious and non-promotional +- [ ] summary findings are concise and not overstated + +## Fail Conditions + +Fail the report if any of the following is true: + +- major sections are missing +- the report contradicts the evidence package +- tone is overly promotional or overly certain +- the response is missing the artifact location +- **Class A: 财务摘要表不存在** +- **Class A: Bull/Base/Bear 缺失且无降级解释** +- **Class A: 超过 3 个财务断言无来源** +- **Class A: 可比公司表缺失且无降级解释** +- **Class A: 风险未分层（无高/中/低分类）** +- **Class A: 正文行内引用 < 5 处** + +## Completion Gate + +Quality passes only if all applicable must-pass items are satisfied and no fail conditions are triggered. diff --git a/equity-research/docs/company-research-quality-upgrade-plan.md b/equity-research/docs/company-research-quality-upgrade-plan.md new file mode 100644 index 0000000..16181ec --- /dev/null +++ b/equity-research/docs/company-research-quality-upgrade-plan.md @@ -0,0 +1,589 @@ +# Company Research Report Quality Upgrade Plan + +本文档是报告质量升级的总体方案，定义优化步骤、功能点清单和验收标准。 + +## 问题诊断 + +### 现状 + +MiniMax 报告实测暴露以下质量缺陷： + +| 缺陷 | 根因文件 | 根因描述 | +|------|---------|---------| +| 无估值逻辑（DCF/可比/目标价区间） | chinese-report-template.md §7 | "若证据允许，可加入估值状态和情景讨论"——可选=不做 | +| 无财务表格/指标趋势 | chinese-report-template.md §5 | 只列指标名称，不要求表格结构 | +| 无风险分层（财务/运营/宏观） | chinese-report-template.md §8 | 列了4类风险但不要求按严重性分层 | +| 无 Bull/Base/Bear 情景 | 全链路无要求 | 模板、workflow、quality-checklist 均未提及 | +| 无行内引用 | source-hierarchy.md 有规则但模板无占位符 | LLM 不在模板中看到引用格式就会忽略 | +| 财务数据浅表 | evidence-contract.md | 门槛太低："至少一个财务来源"即可开写 | +| 质量检查形同虚设 | quality-checklist.md | 只检查"章节是否存在"，不检查分析深度 | +| 散文叙事而非分析框架 | workflow.md Step 4→6 | Fact Pack 直接到 Body Draft，缺少"分析框架构建"中间步骤 | + +### 根因总结 + +模板定义了"写什么章节"但未定义"每个章节必须包含什么分析结构"。LLM 用叙事性散文填充章节，产出"商业记者综述"而非"分析师研报"。 + +--- + +## 优化步骤总览 + +共 4 个 Phase，按依赖顺序执行。 + +| Phase | 名称 | 核心产出 | 优先级 | +|-------|------|---------|--------| +| 1 | 模板结构升级 | 新版 chinese-report-template.md + 估值框架章节 | P0 | +| 2 | 证据门槛与流程升级 | 新版 evidence-contract + workflow 插入分析框架构建步骤 | P0 | +| 3 | 质量门禁升级 | 新版 quality-checklist + compliance-checklist 深度检查项 | P1 | +| 4 | Few-shot 示范与模型策略 | 示范报告片段 + 模型分层建议 | P2 | + +--- + +## Phase 1: 模板结构升级 + +### 目标 + +将 chinese-report-template.md 从"章节大纲"升级为"分析结构模板"，每个章节包含必填的结构化产出要求。 + +### 涉及文件 + +| 文件 | 操作 | +|------|------| +| `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` | 重写 | +| `equity-research/docs/company-research-output-contract.md` | 更新，增加估值章节要求 | +| `equity-research/docs/company-research-request-classification.md` | 更新，Class A 关联估值必填 | + +### 功能点 1.1: 财务章节结构化（§5） + +**当前状态**：§5 只列指标名称，无表格要求。 + +**目标产出**： + +``` +§5.1 核心财务摘要表（必填） +- 标准表格：指标 × (FY-2, FY-1, FY(E), FY+1(E), 来源) +- 必填行：营收、营收YoY%、毛利率、净利润、净利率、经营现金流、自由现金流 +- 空格填 N/A 并在口径说明中解释 +- 预测列仅在有明确依据时填写 + +§5.2 财务趋势分析（必填） +- 至少分析收入增速、利润率、现金流三个维度 +- 每个关键数字必须行内引用来源 + +§5.3 单位经济/运营 KPI（按行业必填） +- 引用 sector-kpis-{sector}.md 中定义的必填 KPI +- 至少给出 2 个核心 KPI 的历史数据 +``` + +**验收标准**： +- 模板中 §5 包含表格结构定义 +- 表格至少 7 行必填指标 +- 每行要求来源列 + +### 功能点 1.2: 新增估值框架章节（§7.5） + +**当前状态**：整个 prompt chain 无估值章节。 + +**目标产出**： + +在 §7（未来展望）和 §8（风险提示）之间插入独立估值章节： + +``` +§7.5 估值框架 + +§7.5.1 可比公司法（首次覆盖必填） +- 标准表格：公司 × (市值, EV/Revenue, EV/EBITDA, P/E, 增速, 来源) +- 至少 3 家可比公司 + 行业中位数 +- 必须说明可比选择理由 +- 必须说明标的溢价/折价及原因 + +§7.5.2 DCF/简化现金流分析（首次覆盖推荐） +- 关键假设清单 +- 敏感性分析 2×2 矩阵（增速 × 折现率） + +§7.5.3 情景分析（必填） +- Bull/Base/Bear 表格：情景 × (概率权重, 核心假设, 隐含估值/市值) +- 数据不足时必须写"当前证据不足以给出估值区间"并说明缺什么 +``` + +**验收标准**： +- 模板包含 §7.5 及三个子节 +- 可比公司表格结构完整 +- 情景分析表格结构完整 +- 数据不足降级路径已定义 + +### 功能点 1.3: 风险章节分层（§8） + +**当前状态**：§8 列了 4 类风险但无分层要求。 + +**目标产出**： + +``` +§8 风险提示 + +§8.1 风险矩阵（必填） +- 按"影响程度 × 发生概率"分三档：高/中/低 +- 每个风险写一句传导机制说明 +- 表格：风险项 × (类别, 严重性, 概率, 传导机制) + +§8.2 反证与下行风险（必填） +- 至少一条与核心结论相反的反证线索 +- 如果结论乐观，必须写出最可能导致结论失败的场景 +``` + +**验收标准**： +- §8 包含风险矩阵表格定义 +- 要求反证/下行风险子节 + +### 功能点 1.4: 行内引用格式强制嵌入 + +**当前状态**：source-hierarchy.md 定义了引用规则，但模板中未嵌入格式示范。 + +**目标产出**： + +在模板每个章节的产出要求中增加引用格式示范： + +``` +每个事实性断言必须行内引用，格式： +- `（来源：公司2024年年报 p.XX）` +- `（来源：SEC 10-K, 2025-02-18）` +- `（来源：2024Q4业绩会纪要）` + +§9 数据来源与口径说明 不再是"引用集中地"， +而是对全文引用的汇总索引 + 口径差异说明。 +``` + +**验收标准**： +- 模板中至少 3 个章节包含行内引用格式示范 +- §9 角色从"唯一引用位置"变为"汇总索引" + +### 功能点 1.5: 首页摘要增加定量要素 + +**当前状态**：首页只要求"先结论→再证据→再不确定性"。 + +**目标产出**： + +``` +首页摘要必须包含： +1. 3-5 条核心结论（已有） +2. 关键财务指标快照：最新营收、增速、利润率、估值倍数（新增） +3. Bull/Base/Bear 一行摘要（新增） +4. 最大风险一句话（新增） +``` + +**验收标准**： +- 首页摘要要求列表包含定量要素 + +--- + +## Phase 2: 证据门槛与流程升级 + +### 目标 + +提高起草前的证据门槛，并在 workflow 中插入"分析框架构建"中间步骤，防止从散装事实直接叙事。 + +### 涉及文件 + +| 文件 | 操作 | +|------|------| +| `equity-research/docs/company-research-evidence-contract.md` | 重写证据门槛 | +| `equity-research/docs/company-research-workflow.md` | 插入 Step 4.5 | +| `equity-research/docs/company-research-degraded-mode.md` | 更新降级触发条件 | + +### 功能点 2.1: 升级首次覆盖证据门槛 + +**当前状态**： +- "at least one official disclosure source" +- "at least one current financial evidence source" + +一篇新闻稿就能满足。 + +**目标产出**： + +``` +首次覆盖最低证据门槛（升级版） + +财务数据（必须）： +- 至少 2 个完整财年的收入、利润、现金流数据 +- 最新一期（季度或半年）的关键指标 +- 若未上市，至少有招股书或融资轮次披露的财务摘要 + +业务数据（必须）： +- 收入拆分（按业务线/地区/客户类型） +- 至少 2 个核心运营 KPI 的历史数据 + +可比公司（首次覆盖必须）： +- 至少识别 3 家可比公司 +- 至少获取可比公司的核心估值倍数 + +不满足时的降级规则： +- 只有 1 年财务数据 → Level B（分析笔记），明确标注 +- 无收入拆分 → §4 标注"收入结构未披露" +- 无可比数据 → 估值章节写"无法建立可比框架"而非跳过 +``` + +**验收标准**： +- evidence-contract.md 包含升级后的门槛 +- 每个不满足条件有明确降级路径 + +### 功能点 2.2: Workflow 插入 Step 4.5 "分析框架构建" + +**当前状态**：Fact Pack → Investment View Pack → Body Draft，中间缺少结构化分析步骤。 + +**目标产出**： + +在 workflow.md Step 4（Fact Pack）和 Step 5（Investment View Pack）之间插入： + +``` +Step 4.5: 分析框架构建（Analysis Kit） + +基于 Fact Pack，必须在起草前完成以下结构化产出： + +1. 财务表格预填 + - 把收集到的财务数据填入标准表格结构 + - 标注每个数字的来源 + - 空格标 N/A + +2. 可比公司筛选 + - 选出 3-5 家可比公司 + - 获取估值倍数 + - 说明筛选逻辑 + +3. 风险分层 + - 按高/中/低分类所有风险因素 + - 每个风险写一句传导机制 + +4. 情景假设 + - 列出 Bull/Base/Bear 的核心驱动假设差异 + +产出格式：结构化 Analysis Kit（JSON 或 Markdown 表格） +Body Draft 必须基于此 Kit 填充，不得从 Fact Pack 直接叙事。 + +Gate：Analysis Kit 不完整则不得进入 Body Draft。 +``` + +**验收标准**： +- workflow.md 包含 Step 4.5 +- Step 4.5 定义了 4 项必填产出 +- Step 6（Body Draft）要求基于 Analysis Kit + +### 功能点 2.3: 降级模式增加估值相关触发条件 + +**当前状态**：降级触发不包含估值数据缺失。 + +**目标产出**： + +在 degraded-mode.md 的触发条件中增加： + +``` +新增降级触发条件： +- 无法获取可比公司估值数据（首次覆盖场景） +- 财务数据不足 2 个完整财年（首次覆盖场景） +- 收入拆分数据不可得 + +对应降级行为： +- 估值章节标注"数据不足，无法进行可比分析" +- 报告整体仍可为 Level A，但估值章节降为 Level B 标注 +``` + +**验收标准**： +- degraded-mode.md 包含估值相关触发条件 +- 支持"章节级降级"而非只有"整体降级" + +--- + +## Phase 3: 质量门禁升级 + +### 目标 + +从"检查章节存在"升级为"检查分析深度"，让质量检查真正能拦截低质量报告。 + +### 涉及文件 + +| 文件 | 操作 | +|------|------| +| `equity-research/docs/company-research-quality-checklist.md` | 重写，增加深度检查项 | +| `equity-research/docs/company-research-compliance-checklist.md` | 增加引用密度检查 | +| `equity-research/docs/company-research-regression-suite.md` | 增加质量相关回归用例 | + +### 功能点 3.1: Quality Checklist 增加分析深度检查 + +**当前状态**： +- "all required report sections are present" +- "key claims are evidence-backed" + +**目标产出**： + +``` +分析深度检查（Must Pass） + +财务部分： +- [ ] 核心财务摘要表存在且至少有 2 年数据 +- [ ] 至少 3 个关键指标有 YoY 变化率 +- [ ] 至少 2 个运营 KPI 有历史趋势 + +估值部分（首次覆盖）： +- [ ] 可比公司表存在且至少 3 家 +- [ ] 可比选择理由已说明 +- [ ] Bull/Base/Bear 三情景已给出 +- [ ] 若无法估值，已明确说明原因和缺失数据 + +风险部分： +- [ ] 风险按严重程度分层（高/中/低） +- [ ] 至少有一条与核心结论相反的反证 + +引用部分： +- [ ] 每个财务数字有行内引用 +- [ ] §9 数据来源具体到文件名/页码，非泛泛"公司公告" + +新增 Fail 条件： +- 财务摘要表不存在 → Fail +- Bull/Base/Bear 缺失且无解释 → Fail +- 超过 3 个财务断言无来源 → Fail +- 可比公司表缺失（首次覆盖）且无解释 → Fail +``` + +**验收标准**： +- quality-checklist.md 包含上述所有检查项 +- Fail 条件可被 LLM 自检执行 + +### 功能点 3.2: Compliance Checklist 增加引用密度要求 + +**当前状态**：只检查"source or scope disclosure is present"。 + +**目标产出**： + +``` +新增合规项： +- [ ] 报告正文中行内引用数量 >= 10（首次覆盖）/ >= 5（更新报告） +- [ ] 每个财务表格中的来源列无空白 +- [ ] 估值可比公司数据有来源标注 +``` + +**验收标准**： +- compliance-checklist.md 包含引用密度要求 + +### 功能点 3.3: 回归测试增加质量用例 + +**目标产出**： + +在 regression-suite.md 中增加： + +``` +质量回归用例： + +Case Q1: 财务表格完整性 +- 输入：生成一份首次覆盖报告 +- 预期：§5 包含标准财务摘要表，至少 7 行指标 +- Fail：表格不存在或少于 5 行 + +Case Q2: 估值框架完整性 +- 输入：生成一份首次覆盖报告 +- 预期：§7.5 包含可比公司表（≥3家）和情景分析表 +- Fail：两个表格均不存在 + +Case Q3: 风险分层 +- 输入：生成一份报告 +- 预期：§8 按高/中/低分层 +- Fail：风险仅为无层级列表 + +Case Q4: 行内引用密度 +- 输入：生成一份首次覆盖报告 +- 预期：正文行内引用 ≥ 10 处 +- Fail：引用 < 5 处 + +Case Q5: Bull/Base/Bear 降级路径 +- 输入：数据不足时生成报告 +- 预期：估值章节标注"数据不足"而非跳过 +- Fail：估值章节完全缺失 +``` + +**验收标准**： +- regression-suite.md 包含 Q1-Q5 用例 + +--- + +## Phase 4: Few-shot 示范与模型策略 + +### 目标 + +通过示范和模型配置进一步提高输出质量。 + +### 涉及文件 + +| 文件 | 操作 | +|------|------| +| `equity-research/skills/initiating-coverage/assets/example-report-excerpt.md` | 新建 | +| `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` | 引用示例 | +| `agents/company-research/agent/BOOTSTRAP.md`（目标运行环境） | 更新引用 | +| `agents/company-research/agent/models.json`（目标运行环境） | 模型策略更新 | + +### 功能点 4.1: 创建 Few-shot 示范报告片段 + +**目标产出**： + +创建一个 2-3 页的示范报告片段（用虚构公司或已公开数据的公司），展示： + +1. 财务摘要表的正确格式 +2. 可比公司表的正确格式 +3. Bull/Base/Bear 情景表的正确格式 +4. 风险矩阵表的正确格式 +5. 行内引用的正确用法 +6. 首页摘要的正确写法 + +**注意**：不是完整报告，是"关键结构的示范片段"，控制 token 消耗。 + +**验收标准**： +- 示例文件存在 +- 模板文件引用示例文件 +- 示例覆盖 5 种核心结构 + +### 功能点 4.2: 模型分层策略建议 + +**目标产出**： + +在 BOOTSTRAP.md 或独立文档中记录模型使用建议： + +``` +模型分层建议 + +Step 1-3（检索、分类、证据收集）： +- 当前模型即可（Qwen3-Max / Kimi K2.5） +- 重点是工具调用准确性，不需要强推理 + +Step 4.5（分析框架构建）： +- 建议使用 reasoning 模型（DeepSeek-R1 / Kimi K2.5 thinking） +- 这一步需要财务建模和逻辑推理能力 + +Step 5-7（Investment View + Body Draft + Front Page）： +- 建议使用强写作模型 +- 需要在结构化要求下保持表达质量 + +Step 8（Verification）： +- 可用当前模型 +- 主要是 checklist 比对 +``` + +**验收标准**： +- 模型策略文档存在 +- 每个 workflow step 有模型建议 + +### 功能点 4.3: Sector KPI 扩展 + +**当前状态**：只有 consumer 和 SaaS 两个行业 KPI 文件。 + +**目标产出**： + +为 MiniMax 等 AI 公司覆盖的场景，增加： + +``` +sector-kpis-ai-platform.md +必填 KPI： +- MAU/DAU 及趋势 +- ARPU +- 用户留存率（D1/D7/D30） +- API 调用量/收入 +- 训练成本/推理成本趋势 +- 模型性能基准得分 +- 现金消耗速率（burn rate） +- 现金 runway +``` + +**验收标准**： +- 新增 sector KPI 文件 +- 文件被 §5.3 引用路径覆盖 + +--- + +## 完整功能点清单 + +| ID | 功能点 | Phase | 优先级 | 涉及文件 | 操作 | +|----|--------|-------|--------|---------|------| +| 1.1 | 财务章节结构化 | 1 | P0 | chinese-report-template.md | 重写 §5 | +| 1.2 | 新增估值框架章节 | 1 | P0 | chinese-report-template.md | 新增 §7.5 | +| 1.3 | 风险章节分层 | 1 | P0 | chinese-report-template.md | 重写 §8 | +| 1.4 | 行内引用格式强制嵌入 | 1 | P0 | chinese-report-template.md | 全文更新 | +| 1.5 | 首页摘要增加定量要素 | 1 | P0 | chinese-report-template.md | 重写首页部分 | +| 1.6 | Output Contract 更新 | 1 | P0 | company-research-output-contract.md | 增加估值要求 | +| 1.7 | Request Classification 更新 | 1 | P1 | company-research-request-classification.md | Class A 关联估值必填 | +| 2.1 | 升级证据门槛 | 2 | P0 | company-research-evidence-contract.md | 重写门槛 | +| 2.2 | Workflow 插入分析框架构建 | 2 | P0 | company-research-workflow.md | 插入 Step 4.5 | +| 2.3 | 降级模式增加估值触发 | 2 | P1 | company-research-degraded-mode.md | 增加触发条件 | +| 3.1 | Quality Checklist 深度检查 | 3 | P1 | company-research-quality-checklist.md | 重写 | +| 3.2 | Compliance Checklist 引用密度 | 3 | P1 | company-research-compliance-checklist.md | 增加检查项 | +| 3.3 | 回归测试质量用例 | 3 | P1 | company-research-regression-suite.md | 增加 Q1-Q5 | +| 4.1 | Few-shot 示范报告片段 | 4 | P2 | example-report-excerpt.md | 新建 | +| 4.2 | 模型分层策略 | 4 | P2 | BOOTSTRAP.md 或独立文档 | 新建/更新 | +| 4.3 | AI Platform Sector KPI | 4 | P2 | sector-kpis-ai-platform.md | 新建 | + +--- + +## 执行依赖关系 + +``` +Phase 1 (模板升级) + ├── 1.1 财务结构化 + ├── 1.2 估值章节 ──→ 依赖 1.1（表格格式一致） + ├── 1.3 风险分层 + ├── 1.4 行内引用 ──→ 依赖 1.1-1.3（嵌入到各章节） + ├── 1.5 首页定量 ──→ 依赖 1.2（引用估值结论） + ├── 1.6 Output Contract ──→ 依赖 1.2 + └── 1.7 Request Classification ──→ 依赖 1.2 + +Phase 2 (证据与流程) ──→ 依赖 Phase 1 完成 + ├── 2.1 证据门槛 ──→ 依赖 1.2（可比公司要求） + ├── 2.2 Workflow Step 4.5 ──→ 依赖 2.1 + └── 2.3 降级模式 ──→ 依赖 2.1 + +Phase 3 (质量门禁) ──→ 依赖 Phase 1+2 完成 + ├── 3.1 Quality Checklist ──→ 依赖 1.1-1.3 的结构定义 + ├── 3.2 Compliance Checklist ──→ 依赖 1.4 的引用格式 + └── 3.3 回归测试 ──→ 依赖 3.1+3.2 + +Phase 4 (示范与策略) ──→ 可与 Phase 3 并行 + ├── 4.1 Few-shot 示例 ──→ 依赖 Phase 1 模板定稿 + ├── 4.2 模型策略 ──→ 依赖 2.2 Step 4.5 定义 + └── 4.3 Sector KPI ──→ 独立 +``` + +--- + +## 部署计划 + +每个 Phase 完成后： + +1. 更新本地 repo 文件 +2. 同步到目标运行环境 workspace：`/` +3. 更新 BOOTSTRAP.md（如涉及）：`/BOOTSTRAP.md` +4. 用一个测试公司（建议用 MiniMax）跑一次端到端验证 +5. 与上一版 MiniMax 报告对比，检查新增结构是否出现 + +### 验收标准（E2E） + +新报告必须满足以下全部条件才算优化成功： + +- [ ] §5 包含财务摘要表，至少 7 行指标 × 2 年数据 +- [ ] §7.5 包含可比公司表（≥3 家）或明确标注"数据不足" +- [ ] §7.5 包含 Bull/Base/Bear 情景表或降级说明 +- [ ] §8 风险按高/中/低分层，含反证子节 +- [ ] 正文行内引用 ≥ 10 处 +- [ ] 首页摘要包含关键指标快照 +- [ ] §9 数据来源具体到文件名/日期 + +--- + +## 与现有 Implementation Plan 的关系 + +本方案是对 `company-research-report-agent-implementation-plan.md` 中以下 Function 的升级补丁： + +| 原 Function | 本方案对应 | +|-------------|-----------| +| Function 2: Chinese Report Template | Phase 1 全部 | +| Function 8: Evidence Collection Contract | Phase 2: 2.1 | +| Function 10: Report Generation Workflow | Phase 2: 2.2 | +| Function 5: Degraded Mode Behavior | Phase 2: 2.3 | +| Function 15: Compliance Checklist | Phase 3: 3.2 | +| Function 16: Quality Checklist | Phase 3: 3.1 | +| Function 17: Regression Suite | Phase 3: 3.3 | +| Function 4: Sector KPI Checklist | Phase 4: 4.3 | + +原 implementation plan 的 function-by-function 交付模型和回归测试要求保持不变。本方案是在原框架内升级具体文档内容，不改变架构。 diff --git a/equity-research/docs/company-research-recency-authority-gate.md b/equity-research/docs/company-research-recency-authority-gate.md new file mode 100644 index 0000000..088038b --- /dev/null +++ b/equity-research/docs/company-research-recency-authority-gate.md @@ -0,0 +1,100 @@ +# Company Research Recency And Authority Gate + +This document defines when evidence is too stale or too weak to support a current company analysis report. + +The purpose is to stop the agent from generating 2026-facing reports from outdated or low-authority material. + +## Core Rule + +For a current company analysis report, the agent must prefer the newest authoritative evidence first. + +If the newest authoritative evidence cannot be found, the agent must not quietly proceed as though the report is current. + +## Authority Order + +Use this order unless the user explicitly changes it: + +1. official company disclosure +2. exchange or regulator disclosure +3. official company IR / results presentation / management communication +4. auditable market or fundamentals provider +5. news and third-party summaries + +Rules: + +- core conclusions must not rely only on tier 5 sources +- financial conclusions must not rely only on media summaries +- if tier 1-3 evidence conflicts with tier 5, trust tier 1-3 + +## Recency Checks + +Before drafting a current report, explicitly determine: + +1. latest formal reporting period available +2. latest disclosure date available +3. latest management communication date available, if any +4. latest price/market snapshot date used + +## Drafting Rules By Evidence Age + +### Current full report allowed + +Allowed only if: + +- the latest formal reporting period is identified +- at least one current official disclosure is used +- current financial evidence exists for the latest available period + +### Degraded or historical note only + +Use degraded mode or explicitly historical framing if: + +- only older reporting periods are available +- latest official disclosure cannot be located +- the report would otherwise present stale facts as current + +Required wording: + +- `以下判断基于截至 {date} 的公开资料` +- `当前未取到更新至更近披露期的正式资料` + +### Full report blocked + +Block a current deep report if: + +- no official disclosure is available +- the latest available data is materially stale for the requested purpose +- only media summaries exist for core claims + +## High-Value Retrieval Prompting Rule + +When asking the LLM to search or retrieve, force it to prioritize high-value evidence. + +Use prompting that makes the model explicitly prefer: + +- newest official filings +- newest exchange announcements +- newest official IR/results materials +- newest management remarks +- only then secondary context + +Recommended instruction: + +`优先检索最新且最有价值的资料。先找公司正式披露、交易所公告、年报/中报/季报、业绩会和官方IR材料；再找可复核市场数据；最后才补充新闻和二手解读。若拿不到最新正式披露期资料，不要把旧资料包装成当前结论，必须明确写出截至日期和缺口。` + +## Required Pre-Draft Output + +Before drafting, the agent should be able to state: + +- latest reporting period used +- latest disclosure date used +- primary authoritative sources used +- stale or missing evidence gaps + +## Completion Gate + +The recency and authority gate is satisfied only if: + +- latest official period/date checks were performed +- source authority order was followed +- stale evidence was either disclosed, downgraded, or blocked diff --git a/equity-research/docs/company-research-regression-suite.md b/equity-research/docs/company-research-regression-suite.md new file mode 100644 index 0000000..64b8cfe --- /dev/null +++ b/equity-research/docs/company-research-regression-suite.md @@ -0,0 +1,355 @@ +# Company Research Function-Level Regression Suite + +This document records the regression checks required for each function. + +## Function 1: Runtime context sync + +- workspace files exist +- runtime docs exist +- agent bootstrap file exists + +## Function 2: Chinese report template + +- all 9 approved sections exist in order +- template includes cautious-style guidance +- no default rating/target-price section exists +- template references example-report-excerpt.md for format demonstrations + +## Function 3: Source hierarchy and citation rules + +- 5-tier source hierarchy exists +- conflict-resolution order exists +- news-only core conclusion is prohibited + +## Function 4: Sector KPI checklist support + +- first two sector checklist files exist (consumer, saas) +- AI platform sector checklist exists (sector-kpis-ai-platform.md) +- each checklist contains business questions, KPIs, and risks +- AI platform checklist includes: MAU/DAU, ARPU, retention, API volume, training/inference cost, benchmark scores, burn rate, runway + +## Function 5: Degraded mode behavior + +- Level A/B/C modes exist +- prohibited degraded-mode outputs are listed +- missing-data disclosure is required +- section-level degradation table exists for Class A (comps, financials, revenue breakdown, scenario, KPI) +- each section-level trigger has specific affected section and degradation note text +- rule: sections must never be silently omitted — degraded with note is always preferred + +## Function 6: Feishu delivery contract + +- success/degraded/clarification response types exist +- message template exists +- artifact priority is defined +- Feishu Doc is the primary user-facing artifact for successful report delivery +- local path alone is explicitly insufficient for successful delivery + +## Function 7: Launch provider selection + +- provider matrix exists +- filings/profile/transcript/citation/export stack is fixed + +## Function 8: Evidence collection contract + +- mandatory evidence list exists +- drafting block conditions exist +- degraded-mode conditions exist +- Class A requires: 2+ fiscal years financials, revenue breakdown, 2+ operating KPIs, 3+ comparable companies +- each new Class A requirement has explicit degraded trigger (Level B / section-level note) +- initiating coverage "Additional Requirements" section lists all upgraded minimums + +## Function 8A: Recency and authority gate + +- authority ranking exists +- latest official period/date check is required +- stale evidence cannot silently pass as current analysis +- high-value retrieval prompting rule exists + +## Function 9: Request classification + +- initiation/update/general analysis/clarification classes exist +- priority rules exist +- Class A lists mandatory analytical structures (financial table, comps table, scenario table, risk matrix, counter-evidence, inline citations ≥10, front page snapshot) +- Class A includes degradation rule: structures must appear with data-gap notes, not be omitted + +## Function 10: Report generation workflow + +- required ordered workflow exists +- front-page-first drafting is prohibited +- recency and authority gate appears before evidence-based drafting +- Step 4.5 (Analysis Kit Construction) exists between Step 4 (Fact Pack) and Step 5 (Investment View Pack) +- Step 4.5 defines 4 mandatory outputs: financial table pre-fill, comparable screening, risk layering, scenario assumptions +- Step 4.5 has a gate: Kit incomplete → must not enter Body Draft +- Step 6 (Body Draft) explicitly requires basing on Analysis Kit, not ad hoc generation + +## Function 11: Output contract + +- full/degraded/clarification output types exist +- prohibited default rating/target-price output is blocked +- successful report output requires a Feishu Doc URL +- Class A analytical structure requirements exist (financial table, comps table, scenario table, risk matrix, counter-evidence, inline citations ≥10, front page snapshot) +- Class B simplified requirements exist (financial table required, comps/scenario optional, inline citations ≥5) +- Class C/D minimal requirements exist (financial table recommended, inline citations ≥3) +- degradation rules require structures to appear with explicit data-gap notes, not silent omission + +## Function 12: OpenClaw company-research agent creation + +- runtime agent exists in config +- runtime agent workspace path exists + +## Function 13: Feishu routing + +- company-research binding exists for Feishu default account +- binding survives gateway restart + +## Function 14: Report artifact return path + +- `reports/` directory exists +- runtime instructions require local markdown archival output +- runtime instructions require Feishu Doc delivery for successful report runs +- runtime instructions require document URL in reply + +## Function 15: Compliance checklist + +- checklist exists +- prohibited-output and source checks exist +- citation density section exists with per-class thresholds (A≥10, B≥5, C/D≥3) +- financial table source column completeness check exists +- comps data source attribution check exists +- 2 new fail conditions: Class A citations<5 hard floor, financial table source blanks without N/A + +## Function 16: Quality checklist + +- checklist exists +- completeness, tone, and artifact checks exist +- Class A analytical depth checks exist: financial table (2yr, 7rows, YoY), valuation (comps≥3, scenarios, degradation), risk (layered, counter-evidence), citations (per-number + ≥10 total), front page (snapshot, B/B/B summary, top risk) +- Class B simplified depth checks exist (financial table, citations≥5, risk present) +- 6 explicit Class A fail conditions defined (no financial table, no B/B/B without explanation, >3 unsourced claims, no comps without explanation, risk not layered, citations<5) + +## Function 17: Regression suite itself + +- this file exists +- all completed functions are enumerated + +## Function 18: End-to-end report generation + +- at least one successful report run +- at least one degraded-mode run +- artifact file generated +- successful report delivery returns an openable Feishu Doc URL +- compliance and quality gates checked +- user-visible transcript contains no internal process chatter + +## Function 19: Model layering strategy + +- model strategy document exists +- every workflow step has a model tier recommendation +- 3 model tiers defined (Standard, Reasoning, Strong writing) +- Step 4.5 and Step 6 are identified as highest-priority for model quality investment + +## Quality Regression Cases + +These cases verify the quality upgrade changes are effective in generated reports. +Each case has a concrete check method that can be applied to any generated report markdown. + +--- + +### Tier 0: Agent Context Verification (must pass before checking report content) + +#### Case Q0-1: Workspace documents read + +- Trigger: any report generation session +- Check method: examine session log for file read events +- Pass: session log shows reads of at least: chinese-report-template.md, company-research-workflow.md, company-research-evidence-contract.md, company-research-output-contract.md +- Fail: any of these files not read → agent is not loading upgraded workspace. **Stop here — report quality checks are meaningless if agent didn't read the rules.** +- Known failure mode (2026-03-11 泡泡玛特): zero workspace documents were followed, report matched pre-upgrade quality + +#### Case Q0-2: Correct agent routing + +- Trigger: any Feishu-initiated report request +- Check method: examine `/agents/company-research/sessions/sessions.json` for the session entry +- Pass: session key contains `agent:company-research:feishu:direct:*` +- Fail: session routed to `default` or another agent → report won't follow company-research rules + +--- + +### Tier 1: Structural Checks (apply to generated report markdown) + +#### Case Q1: Financial table exists (Class A) + +- Input: Class A initiating coverage report +- Check method: `grep -c '|' §5` — count markdown table rows in financial section +- Pass: §5 contains a markdown table with ≥7 data rows, ≥2 year columns, a "来源" column +- Fail: no markdown table in §5, or table has <5 rows + +#### Case Q1-B: Financial table exists (Class B) + +- Input: Class B company update report +- Check method: same as Q1 but relaxed +- Pass: §5 contains a markdown table with ≥3 data rows, ≥1 period column, a "来源" column +- Fail: no markdown table in §5 at all +- Known failure (2026-03-11 泡泡玛特 Class B): zero tables in entire report. Financial data scattered as prose ("毛利率：约60%") + +#### Case Q2: Valuation framework (Class A) + +- Input: Class A initiating coverage report +- Pass: §7.5 contains 可比公司表 (≥3 companies) and 情景分析表 (Bull/Base/Bear), or degradation notes +- Fail: both tables missing without explanation + +#### Case Q3: Risk layering + +- Input: any report type +- Check method: search §8 for markdown table with "严重性" or "高/中/低" column +- Pass: risk matrix table exists with severity classification +- Fail: risks are a flat bullet list without severity/probability classification +- Known failure (2026-03-11 泡泡玛特): 7 risks listed as equal-weight bullets, no layering, no transmission mechanism + +#### Case Q4: Inline citation density (Class A) + +- Input: Class A initiating coverage report +- Check method: `grep -c '（来源：' report.md` +- Pass: count ≥ 10 +- Fail: count < 5 + +#### Case Q4-B: Inline citation density (Class B) + +- Input: Class B company update report +- Check method: same grep +- Pass: count ≥ 5 +- Fail: count < 3 +- Known failure (2026-03-11 泡泡玛特 Class B): count = 0. Zero inline citations in entire report. + +#### Case Q5: Bull/Base/Bear degradation path + +- Input: report where quantitative data is insufficient +- Pass: §7.5 section exists with explicit "数据不足" note +- Fail: §7.5 section completely absent + +--- + +### Tier 2: Data Integrity Checks (detect hallucination and vagueness) + +#### Case Q6: No vague approximations as financial data + +- Input: any report type +- Check method: count occurrences of "约XX%", "大约", "估计约", "近XX" in §5 financial section +- Pass: every financial number in §5 table has an exact figure (not "约") and a source citation +- Fail: ≥3 financial figures use "约" without source → likely LLM hallucination +- Known failure (2026-03-11 泡泡玛特): "毛利率：约60%""净利率：约15%""海外收入占比：约30%" — all "约", all unsourced, all likely fabricated + +#### Case Q7: Data source specificity + +- Input: any report type +- Check method: examine §9 数据来源与口径说明 +- Pass: §9 lists specific document names with dates/pages (e.g., "泡泡玛特 2025 年中期报告 p.23") +- Fail: §9 only lists generic categories ("公司财报""行业研究报告""新闻媒体报道") +- Known failure (2026-03-11 泡泡玛特): §9 listed 5 generic categories, zero specific documents + +#### Case Q8: Financial data period explicit + +- Input: any report type +- Check method: search for explicit fiscal period references ("FY2024", "2025H1", "2025Q3") +- Pass: report explicitly states which fiscal period each data point refers to +- Fail: financial data presented without clear period (e.g., "营收增长率：同比+25%" — which period?) +- Known failure (2026-03-11 泡泡玛特): "+25%" with no period specified, "约50亿港元" with no date + +--- + +### Tier 3: Report Type Compliance + +#### Case Q9: Class B focuses on incremental change + +- Input: Class B company update report +- Check method: compare word count of §2 公司基本面概览 vs §6 当前变化与驱动因素 +- Pass: §6 (changes/drivers) is the longest section; §2 (company overview) is brief or references prior report +- Fail: §2 is as long or longer than §6 → report is a full company profile, not an update +- Known failure (2026-03-11 泡泡玛特 Class B): wrote full company overview (founding year, headquarters, channel count) as if it were Class A. §6 was generic, not based on any specific recent event or earnings release. + +#### Case Q10: Report does not contain common-knowledge padding + +- Input: any report type +- Check method: search for generic industry descriptions that add no analytical value +- Red flags: "Z世代消费崛起""IP经济繁荣""消费升级""线上线下融合" without company-specific data +- Pass: industry commentary is tied to specific data points about the target company +- Fail: ≥3 paragraphs of generic industry narrative without company-specific evidence +- Known failure (2026-03-11 泡泡玛特): §3 行业与市场环境 was entirely generic ("全球潮流玩具市场规模2025年预计达到350亿美元" — unsourced, adds no analytical value) + +--- + +### Tier 4: Delivery Checks + +#### Case Q11: Feishu Doc delivery (not inline message) + +- Input: any successful report +- Check method: examine Feishu message sent to user +- Pass: user receives a Feishu Doc URL with full report body +- Fail: report delivered as inline Feishu message text (not a doc) +- Known failure (2026-03-11 泡泡玛特): entire report dumped as Feishu chat message, no Feishu Doc created + +#### Case Q12: Report saved to workspace + +- Input: any successful report +- Check method: `ls reports/` in workspace +- Pass: `reports/{company}_{report_type}_{YYYYMMDD}.md` file exists +- Fail: no file in reports/ directory + +## Live Regression Record + +### 2026-03-11: Feishu Doc delivery (partial pass) + +- focused Feishu Doc creation test succeeded +- existing Apple full report was written into a Feishu Doc (``) +- the Feishu Doc link was sent to the target user through the default Feishu account +- known gap: standard Apple analysis request may still return old summary + local path instead of Feishu Doc URL + +### 2026-03-11: 泡泡玛特 Class B company update (FULL FAIL) + +Request: "帮我写一份泡泡玛特的公司更新" +Result: Report delivered as inline Feishu message, not Feishu Doc. + +| Case | Result | Detail | +|------|--------|--------| +| Q0-1 Workspace docs read | **FAIL (suspected)** | Report shows zero evidence of following upgraded templates/rules | +| Q0-2 Agent routing | **UNVERIFIED** | Need to check session log to confirm routing | +| Q1-B Financial table (Class B) | **FAIL** | Zero markdown tables in entire report | +| Q3 Risk layering | **FAIL** | 7 risks as flat bullet list, no severity classification | +| Q4-B Citations (Class B ≥5) | **FAIL** | 0 inline citations (target: ≥5) | +| Q6 No vague approximations | **FAIL** | "约60%""约15%""约30%" — all unsourced | +| Q7 Data source specificity | **FAIL** | §9 lists only generic categories | +| Q8 Financial period explicit | **FAIL** | "+25% YoY" without specifying which period | +| Q9 Class B incremental focus | **FAIL** | Wrote full company profile instead of update | +| Q10 No common-knowledge padding | **FAIL** | Multiple paragraphs of generic industry narrative | +| Q11 Feishu Doc delivery | **FAIL** | Dumped as inline message | +| Q12 Report saved to workspace | **UNVERIFIED** | Need to check reports/ directory | + +**Root cause hypothesis**: Agent did not read upgraded workspace documents. Either (a) session was routed to wrong agent, (b) BOOTSTRAP.md → AGENTS.md reading chain was not followed, or (c) model ignored the workspace instructions. Must verify Q0-1 and Q0-2 before further quality tuning. + +### 2026-03-11: 泡泡玛特 Class B (Phase 5.2 retest after 5.1 fix) + +Request: "帮我写一份泡泡玛特的公司更新"（session 重置后干净 session） +Result: 报告保存至 workspace，但结构性质量仍未达标。 + +**改善**：模型执行了 4×web_search + 1×web_fetch + 1×write + 3×feishu_doc（之前为 0 tool call）。数据真实，有具体数字和明确财报期间。 + +| Case | Result | Detail | +|------|--------|--------| +| Q0-1 Workspace docs read | **可能通过** | 有真实数据和具体财报期间 | +| Q1-B Financial table (Class B) | **FAIL** | 0 个 markdown 表格，财务数据散在正文 | +| Q3 Risk layering | **FAIL** | 5 条风险平级 bullet，无严重性分类 | +| Q4-B Citations (Class B ≥5) | **FAIL** | 0 条（来源：）格式行内引用 | +| Q6 No vague approximations | **改善** | 用了具体数字（138.76亿、204.4%），不再"约XX%" | +| Q7 Data source specificity | **改善** | §9 列出了"泡泡玛特2025年半年度报告" | +| Q8 Financial period explicit | **改善** | 明确标注"2025年上半年" | +| Q9 Class B incremental focus | **FAIL** | 写了完整公司概况（2010年成立、上市历史） | +| Q10 No common-knowledge padding | **FAIL** | §3 有"IP消费崛起""全球化布局"等泛泛描述 | +| Q12 Report saved to workspace | **PASS** | 泡泡玛特_公司研究报告_20260311.md 已存在 | + +**结论**：5.1 修复解决了数据来源问题，但 qwen3-max 无法遵守结构性格式规则。决定执行 Phase 5.3（切换为 Claude Sonnet 4）。 + +### Function 18 status + +- Feishu Doc delivery: partially validated (works when explicitly instructed, fails on automatic path) +- 数据来源质量: **已改善**（5.1 修复后不再凭空捏造） +- 结构性质量: **未通过**（qwen3-max 无法生成表格/引用/风险矩阵） +- Next step: Phase 5.3 — 切换 company-research agent 主模型为 Claude Sonnet 4 diff --git a/equity-research/docs/company-research-report-agent-handoff.md b/equity-research/docs/company-research-report-agent-handoff.md new file mode 100644 index 0000000..58e3a27 --- /dev/null +++ b/equity-research/docs/company-research-report-agent-handoff.md @@ -0,0 +1,609 @@ +# Company Research Report Agent Handoff + +This file is the durable handoff record for future AI agents working on the company research report agent in this repository. + +Read this file before proposing new architecture, new templates, or new workflow changes. + +## Project State + +The repo already contains the correct base architecture: + +- `equity-research` is the report workflow layer +- `financial-analysis` is the valuation and shared connector layer +- `equity-research/skills/initiating-coverage` is the main skeleton for initiation reports +- `equity-research/skills/earnings-analysis` is the starting point for update notes + +Do not replace this structure in V1. + +## Decisions Already Made + +These decisions are settled unless the user explicitly changes them. + +### 1. Product goal + +The goal is to generate a high-quality first draft of a company research report. + +This project is not trying to solve: + +- review workflow +- internal approval flow +- publication system +- portfolio management workflow + +Only the first-draft generation layer is in scope. + +### 2. Output scope + +V1 should support: + +- initiating coverage +- company update / earnings review + +V1 should not try to support every report type. + +### 3. Report framework + +Use a hybrid structure: + +- Goldman-style front page + - conclusion first + - key bullet points first + - key metrics / valuation summary on page 1 +- CICC / Chinese sell-side style body + - investment thesis or event view + - company overview + - industry and competition + - business-line analysis + - financial analysis + - forecast and valuation + - risks +- Fund-style completeness checklist + - business model + - market space + - competitive position + - growth drivers + - governance and incentives + - risks and disconfirming evidence + +This means: + +- do not copy protected wording +- do copy structure and sequencing + +### 4. Report assembly order + +The report must be assembled in this order: + +1. `Fact Pack` +2. `Investment View Pack` +3. `Body Draft` +4. `Front Page Summary` +5. `Verification` +6. `Export` + +Do not generate the front page first. + +### 5. Default Chinese research style + +The default writing style is based on publicly visible Changsheng Fund disclosure patterns. + +Use: + +- cautious tone +- evidence first, conclusion second +- explicit source and scope language +- more `判断 / 预计 / 关注 / 需跟踪` +- less aggressive recommendation language + +Do not default to highly promotional sell-side wording. + +### 6. Default Chinese report template + +Unless the user changes it, use this section order: + +1. `核心结论` +2. `公司基本面概览` +3. `行业与市场环境` +4. `业务与竞争力分析` +5. `财务与关键指标分析` +6. `当前变化与驱动因素` +7. `未来展望` +8. `风险提示` +9. `数据来源与口径说明` + +### 7. Default research framework + +Unless the user changes it, use this analytical path: + +1. `宏观与政策环境` +2. `行业景气度与周期位置` +3. `竞争格局与公司位置` +4. `公司质量` +5. `增长驱动与催化因素` +6. `交易与估值状态` +7. `风险与反证` + +This came from publicly visible fund-manager and fund-report style, especially Changsheng Fund material. + +### 8. Source priority rules + +Unless the user changes it, use this source priority: + +1. official regulatory and company disclosure +2. auditable or official-market reference data +3. public management communication +4. market and industry data providers +5. news and media coverage + +If sources conflict: + +1. latest formal filing or announcement +2. notes to financial statements +3. public management remarks +4. third-party interpretation + +News must not be the primary basis for a core investment conclusion. + +### 9. Rating and target price boundary + +Unless the user explicitly requests otherwise, do not output: + +- formal buy / sell ratings +- target price +- implied upside language + +Use instead: + +- `观点倾向` +- `关注重点` +- `后续验证指标` +- `需持续跟踪的风险` + +### 10. Reuse-first policy + +Future agents should reuse: + +- current plugin architecture +- current initiation workflow +- current earnings workflow +- current `comps` and `dcf` flows +- external open-source connectors where possible + +Do not propose new infrastructure before checking whether the need is already covered by: + +- `sec-edgar-mcp` +- `sec-edgar-toolkit` +- `OpenBB` +- `Octagon MCP Server` +- `earningscall-python` +- `rag-citation` +- `docxtemplater` +- `pandoc` + +## Open-Source Components Already Selected + +Prefer these components before inventing new ones: + +- Filing and fundamentals: + - + - +- Market and profile data: + - +- Transcript and event context: + - + - +- Citation support: + - +- Export: + - + - + +## Quality Upgrade Status (2026-03-11) + +A quality upgrade initiative is underway to fix low-quality report output (diagnosed from MiniMax report). + +Root cause: Chinese template only defined "what sections to write" but not "what analytical structure each section must contain". LLM filled sections with narrative prose instead of structured analysis. + +### Upgrade plan document + +`equity-research/docs/company-research-quality-upgrade-plan.md` — 4 phases, 16 feature points. + +### Reference material + +High-quality Chinese analysis template sourced from Day1Global (public .skill archive): +- Saved to: `/day1global-tech-earnings-deepdive-SKILL.md` +- Also saved: valuation models, bias checklist, investing philosophies + +### Phase completion status + +| Phase | Status | Notes | +|-------|--------|-------| +| Phase 1: Template structure upgrade (1.1-1.5) | **DONE** | chinese-report-template.md rewritten from 107-line skeleton to comprehensive v2.0 with mandatory tables, valuation framework, risk matrix, inline citations, chapter required/optional matrix | +| Phase 1: Downstream docs (1.6-1.7) | **DONE** | output-contract: Class A/B/C/D analytical structure requirements + degradation rules. request-classification: Class A mandatory structures list | +| Phase 2: Evidence threshold (2.1) | **DONE** | evidence-contract: 2+ fiscal years, revenue breakdown, 2+ KPIs, 3+ comps, each with degraded trigger | +| Phase 2: Workflow Step 4.5 (2.2) | **DONE** | workflow: Analysis Kit Construction inserted (financial pre-fill, comps screening, risk layering, scenario assumptions). Gate: Kit incomplete → block Body Draft | +| Phase 2: Degraded mode (2.3) | **DONE** | degraded-mode: added section-level degradation table (5 triggers: comps, 1yr financials, revenue breakdown, scenario, KPI). Rule: sections never silently omitted | +| Phase 3: Quality checklist (3.1) | **DONE** | quality-checklist: 17 Class A depth checks (financial/valuation/risk/citations/front page), 3 Class B checks, 6 explicit fail conditions | +| Phase 3: Compliance checklist (3.2) | **DONE** | compliance-checklist: citation density per class (A≥10, B≥5, C/D≥3), table source completeness, 2 new fail conditions | +| Phase 3: Regression suite (3.3) | **DONE** | regression-suite: Q1-Q5 quality cases (financial table, valuation framework, risk layering, citation density, degradation path) | +| Phase 4: Few-shot excerpt (4.1) | **DONE** | example-report-excerpt.md created with 6 demonstrations (front page, financial table, comps, scenarios, risk matrix, citations). Template references it | +| Phase 4: Model strategy (4.2) | **DONE** | company-research-model-strategy.md created. Step 4.5 + Step 6 identified as highest-priority for model quality. 3 tiers: Standard/Reasoning/Strong writing | +| Phase 4: AI Platform KPI (4.3) | **DONE** | sector-kpis-ai-platform.md created with 13 KPIs + 8 risk items. Covers MAU/ARPU/retention/inference cost/burn rate/runway | +| Deploy: file sync to staging | **DONE** | 13 files synced to `/`. AGENTS.md updated with 3 new file references (example-report-excerpt, model-strategy, sector-kpis-ai-platform). Handoff doc synced. Verified 22 markdown files in staging. | +| Deploy: E2E validation | **FAILED** | 泡泡玛特 Class B test: 0 tables, 0 citations, 0 risk layering, delivered as inline message not Feishu Doc. All Q-cases failed. Root cause: agent likely did not read upgraded workspace docs. See regression-suite.md "2026-03-11 泡泡玛特" for full failure record | + +### Key design decisions in v2.0 template + +- Fused English template structure (Goldman front page + comps + DCF sensitivity) with Day1Global analysis depth (Key Forces + 6 investment philosophies + multi-method valuation) +- Added mandatory financial summary table (7+ rows x 5 columns with source column) +- Added comparable company table (3+ companies + median/mean) +- Added Bull/Base/Bear scenario table with probability weights +- Added risk matrix with severity x probability classification +- Added inline citation format enforcement throughout all chapters +- Added chapter required/optional matrix by report type (A/B/C/D) +- Preserved existing constraints: no formal rating/target price, Changsheng cautious tone, evidence-first + +### E2E failure root cause (2026-03-11 泡泡玛特) + +Confirmed root cause chain: +1. OpenClaw uses **persistent session** for Feishu direct messages (all DMs from same user share one session) +2. 泡泡玛特 request entered as message #201 in a session already containing 200 messages / 48K tokens of unrelated work (Day1Global skill installation) +3. AGENTS.md IS injected into system prompt every message (OpenClaw design), but it's a **reading list** of 19 files — requires model to voluntarily call `read_file` tool +4. qwen3-max in 48K token context **skipped all tool calls** and generated the entire report from parametric knowledge (zero tool calls, zero file reads, zero web searches) +5. Result: report with 0 tables, 0 citations, 0 risk layering, all data likely hallucinated + +### Decided remediation plan + +**Phase 5: Runtime remediation (adopted 2026-03-11)** + +| Step | Action | Purpose | +|------|--------|---------| +| 5.1 | **Inline critical constraints into AGENTS.md** | Put "must not" rules directly in system prompt so they're seen every message without needing tool calls. Keep under 20K chars (bootstrapMaxChars limit). | +| 5.2 | **Session reset + test with qwen3-max** | Verify whether the upgraded docs work in a clean session. If yes → qwen3-max is viable with architecture fix. | +| 5.3 | **If qwen3-max still fails: add Claude Sonnet 4** | Claude proxy available at ``, anthropic-messages API. Use for Step 4.5 (Analysis Kit) + Step 6 (Body Draft) only. Classification/retrieval stays on qwen3-max for cost control. | + +Execution order: 5.1 → 5.2 → evaluate → conditionally 5.3. + +### Phase 5.1 completion record (2026-03-11) + +- AGENTS.md rewritten (5,728 chars, under 20K limit): added 3 "绝对禁止" rules (no parametric generation, no vague numbers, no inline delivery), inlined structural requirements (tables/citations/risk layering per class), Class B incremental focus constraint, workflow summary with gate +- BOOTSTRAP.md updated (3,526 chars): added "最高优先级规则" block requiring read_file of 4 specific workspace docs + search tools before any report writing, explicit "no tool call = hallucination" warning +- All 5.1a-5.1d regression cases PASS + +### Claude API proxy (for step 5.3 if needed) + +- Base URL: `` +- API: POST `/v1/messages` (Anthropic Messages API compatible) +- Auth: `Authorization: Bearer ${CLAUDE_PROXY_API_KEY}` +- Required headers: `content-type: application/json`, `anthropic-version: 2023-06-01` +- Verified model: `claude-sonnet-4-20250514` + +### Phase 5.2 测试结果 (2026-03-11) + +Session 重置后用 qwen3-max 重新测试泡泡玛特 Class B。 + +**改善点**：模型执行了 4 次 web_search + 1 次 web_fetch + 1 次 write + 3 次 feishu_doc 调用（之前为 0）。数据来源真实，包含具体财务数字和明确财报期间。 + +**仍然失败的项目**： + +| 用例 | 结果 | 详情 | +|------|------|------| +| Q1-B 财务表格 | **未通过** | 0 个 markdown 表格，财务数据全在正文散落 | +| Q3 风险分层 | **未通过** | 5 条风险平级 bullet，无严重性分类 | +| Q4-B 引用密度 | **未通过** | 0 条（来源：）格式的行内引用 | +| Q9 Class B 增量聚焦 | **未通过** | 写了完整公司概况（2010年成立…）而非增量更新 | +| Q10 无常识填充 | **未通过** | §3 全是"IP消费崛起""全球化布局"等泛泛描述 | + +**结论**：5.1 修复解决了数据来源问题（不再凭空捏造），但 qwen3-max 无法遵守结构性格式规则（表格、引用格式、风险矩阵、报告类型范围约束）。这是模型指令遵循能力的限制，非 prompt 工程可解决。 + +**决策**：执行 Phase 5.3，切换 company-research agent 主模型为 Claude Sonnet 4。 + +### Phase 5.3 修复计划：模型切换 + 质量验证 + +**发现**：OpenClaw 支持 per-agent 模型覆盖（`executive` agent 已有先例）。 + +#### 功能清单 + +| 编号 | 功能 | 文件 | 测试用例 | +|------|------|------|---------| +| 5.3a | 添加 Claude proxy provider 到 models.json | models.json | JSON 合法，包含 claude-proxy provider，model id 和 API 配置正确 | +| 5.3b | 设置 company-research agent 使用 Claude | runtime config (agents.list) | company-research 条目包含 `model.primary: "claude-proxy/claude-sonnet-4-20250514"` | +| 5.3c | Session 重置 | sessions.json | feishu:direct session 已清除 | +| 5.3d | 泡泡玛特 Class B 端到端测试 | 报告输出 | Q1-B 通过（有 markdown 表格），Q3 通过（风险有分层），Q4-B 通过（引用≥5），Q9 通过（聚焦增量），Q10 通过（无泛泛描述） | +| 5.3e | 全量 Q0-Q12 回归 | 报告输出 | 所有结构性质量用例通过或有明确降级说明 | + +#### 技术细节 + +- Claude proxy: ``, anthropic-messages API +- Auth: `Bearer ${CLAUDE_PROXY_API_KEY}` +- Model: `claude-sonnet-4-20250514` +- models.json 中 apiKey 直接写死（proxy 固定 token，不走 .env） +- runtime config 修改需要 gateway 重启生效 +- 风险：Claude 是否能正确使用 OpenClaw 注册的 tools（brave_search、feishu_doc 等）——需在 5.3d 验证 +- 官方推荐方案：`sessions_spawn` + 显式 `model` 参数（subagent 模型覆盖），而非脚本委托或 model.primary 切换 +- 参考：[Sub-Agents 官方文档](https://docs.openclaw.ai/tools/subagents)，详细调研见 `/openclaw-multi-model-routing.md` + +### Phase 5.3a 完成记录 (2026-03-11) + +- models.json 添加 `claude-proxy` provider（anthropic-messages API） +- 部署路径：`/models.json` +- 5 个 provider 共存：dashscope, kimi-coding, volcengine, volcengine-plan, claude-proxy +- 测试：JSON 合法，provider 配置正确 ✅ + +### Phase 5.3b 完成记录 (2026-03-11) + +- 源码验证 `sessions_spawn` + `model` 参数的完整调用链： + - `sessions_spawn` 工具定义 (reply L30219) → `readStringParam(params, "model")` → `spawnSubagentDirect` + - `spawnSubagentDirect` (reply L29793) → `resolveSubagentSpawnModelSelection({ modelOverride })` → 显式 model 最高优先级 + - `resolveSubagentSpawnModelSelection` (model-selection L17175) → `normalizeModelSelection(params.modelOverride)` 排第一，跳过所有 config 默认值 + - 解析后通过 `sessions.patch({ model })` 写入子 session → model override 生效 +- **结论**：显式传入 `model` 参数不走 config 默认值路径，不受 Issue #10963 bug 影响 +- 测试：源码逻辑验证通过 ✅（无需运行时测试，代码路径确定性保证） + +### Phase 5.3c 完成记录 (2026-03-11) + +- AGENTS.md 重写为三阶段多模型协作工作流（6,967 bytes）： + - Phase 1（qwen3-max 自己做）：请求分类、搜索、证据收集、Fact Pack 组装 + - Phase 2（委托 Claude）：`sessions_spawn({ model: "claude-proxy/claude-sonnet-4-20250514", thinking: "high" })` — 分析工具包 + 报告正文 + - Phase 3（qwen3-max 自己做）：验证、补充前页摘要、飞书交付 +- task 字段模板包含：报告类型、Fact Pack、9 章结构要求、引用/表格/风险分层格式要求 +- 部署到 staging：`/AGENTS.md` +- 测试：内容验证通过 ✅ + +### Phase 5.3d 测试记录 (2026-03-11) + +**测试结果**：报告质量巨大飞跃，但 Claude 模型切换有阻塞。 + +**Session 行为**（4ada9469）： +1. qwen3-max 执行 7 次 brave_search 收集数据 ✅ +2. 第一次 `sessions_spawn({ model: "claude-proxy/claude-sonnet-4-20250514" })` → **"model not allowed"** ❌ +3. 第二次 spawn（无 model 参数，用默认 qwen3-max）→ 成功 +4. subagent 完成后主 agent 写入 reports/ + 创建飞书文档 ✅ + +**报告质量评估（泡泡玛特_9992.HK_公司更新_20260311.md）**： + +| 用例 | 结果 | 详情 | +|------|------|------| +| Q1-B 财务表格 | **✅ PASS** | §5 有 6 行 markdown 表格，每行有来源引用 | +| Q3 风险分层 | **✅ PASS** | 高/中/低分类，每条有传导机制（IP生命周期→销量下滑→库存积压→毛利率承压→利润下滑） | +| Q4-B 引用密度 | **✅ PASS** | 全文 >15 处（来源：具体文件名/日期）格式引用 | +| Q6 无模糊近似 | **✅ PASS** | 138.76亿、204.4%、45.74亿 — 全部精确数字 | +| Q7 数据来源具体性 | **✅ PASS** | §9 列出 5 个具体来源，含文件名和日期 | +| Q8 财务期间明确 | **✅ PASS** | "2025年上半年"、"2025年第三季度" | +| Q9 Class B 增量聚焦 | **✅ PASS** | §2 = "参见此前报告"（极简），§6 是最长章节 | +| Q10 无常识填充 | **✅ PASS** | 行业描述绑定具体公司数据 | +| Q12 报告保存 | **✅ PASS** | reports/泡泡玛特_9992.HK_公司更新_20260311.md | + +**关键发现**：即使没用 Claude（subagent 用了默认 qwen3-max），报告质量也大幅提升。原因： +1. subagent 在干净上下文中运行（无历史噪音） +2. task 字段包含了完整 Fact Pack + 明确结构要求 +3. AGENTS.md 的结构性约束通过 task prompt 传递给了 subagent + +**待修复**：`claude-proxy/claude-sonnet-4-20250514` 被 model allowlist 拒绝，需要在 runtime config 中添加到允许列表 + +## What Is Still Pending (Original) + +These are the original next concrete deliverables: + +1. ~~Adapt initiation and earnings documentation to the default Chinese framework~~ (partially done via quality upgrade) +2. Create runtime-ready OpenClaw agent files and bind them into the target deployment +3. Connect the selected provider stack for launch +4. Run end-to-end validation through Feishu + +## Delivery Rule Fix Applied + +The Feishu user-facing artifact is now required to be a Feishu Doc URL. + +This means: + +- local markdown is still useful for internal traceability +- but a local path alone is not a successful delivery +- successful report delivery requires `create -> write -> confirm URL` + +## Runtime Directory Layout (Critical — Do Not Confuse) + +There are two `.openclaw` directories in the target runtime. They serve different purposes: + +| Path | Purpose | +|------|---------| +| `/` | **Agent definitions** — BOOTSTRAP.md, models.json, workspace files. This is where the runtime config points to. | +| `/` | **Runtime state** — sessions, cron, logs, gateway process, runtime config itself. | + +Specifically for company-research: + +| Item | Path | +|------|------| +| Agent definition | `/BOOTSTRAP.md` | +| Models config | `/models.json` | +| Workspace | `/` | +| Runtime sessions | `/agents/company-research/sessions/` | +| Master config | `/openclaw.json` (agentDir + workspace + Feishu binding) | + +**Rule**: Deploy agent files to `/`. Check runtime state in `/`. Do not confuse them. + +## Live State In Staging + +The staging OpenClaw environment has already proven these behaviors: + +- `company-research` agent exists and is routable from Feishu +- Routing: `/openclaw.json` → accountId "default" → agentId "company-research" +- Agent dir: `/` +- Workspace: `/` +- the default Feishu account is bound to this agent in staging +- the `default` Feishu account is bound to `company-research` +- full Apple report markdown exists in runtime workspace +- Feishu Doc create/write path is real and working +- a full Apple report has already been written to a live Feishu Doc +- that Feishu Doc link has already been sent to the target Feishu user + +Validated live document: + +- `` + +This means the delivery channel is no longer hypothetical. + +## Current Gap + +There is still one runtime inconsistency to preserve in context: + +- when the agent is explicitly told to read an existing markdown report and write it to Feishu Doc, delivery succeeds +- when a standard company-analysis request runs end to end, the model may still fall back to the old summary + local path pattern + +Do not misstate this as "Feishu delivery is fully solved." + +The correct status is: + +- manual/live Feishu Doc delivery path: working +- default automatic report-completion path: not fully converged yet + +## Runtime Mapping In Staging + +Keep these mappings explicit: + +- Feishu bot for user interaction: + - account id: `default` + - bot name: `` + - bound agent: `company-research` +- Known-good Feishu Doc write app for full report body: + - app id: `` + +Do not confuse: + +- the Feishu bot account used for chat delivery +- the app identity that successfully wrote the full report body into Feishu Doc + +## Document Delivery Caveat + +The first Apple replacement link that was sent as a "success" turned out to be title-only. + +Verified bad document: + +- `` +- read-back result: `block_count = 1`, title only, no body + +Verified replacement document with body: + +- `` +- direct API verification with the writing app returned `code = 0` +- child block query returned content blocks, not an empty title-only doc + +Future agents must preserve this lesson: + +- "doc created" is not enough +- "URL returned" is not enough +- delivery is only valid after body existence is verified + +Preferred runtime mitigation: + +- use a deterministic markdown-to-Feishu-doc write path +- verify child blocks exist before treating the delivery as successful + +## Constraints For Future AI Agents + +Before making edits, future agents must follow these constraints: + +- keep diffs small +- prefer documentation and template changes over architecture changes +- do not remove existing workflow files unless explicitly asked +- preserve the repo's current plugin / command / skill model +- verify whether an existing skill already covers the need before adding new files +- if browsing is available, verify time-sensitive facts and source URLs +- do not use a "minimal closed loop first" delivery strategy +- deliver one function at a time and require regression for that function before moving on + +## Required Reading Order For Future Agents + +Before doing more work, read: + +1. `README.md` +2. `equity-research/docs/company-research-report-agent.md` +3. `equity-research/docs/company-research-report-agent-handoff.md` +4. `equity-research/docs/company-research-report-agent-implementation-plan.md` +5. `equity-research/docs/company-research-source-hierarchy.md` +6. `equity-research/docs/company-research-degraded-mode.md` +7. `equity-research/docs/company-research-recency-authority-gate.md` +8. `equity-research/docs/company-research-message-gating.md` +9. `equity-research/docs/company-research-feishu-delivery.md` +10. `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` +11. `equity-research/skills/initiating-coverage/references/sector-kpis-saas.md` +12. `equity-research/skills/initiating-coverage/references/sector-kpis-consumer.md` +13. `equity-research/skills/initiating-coverage/SKILL.md` +14. `equity-research/skills/initiating-coverage/assets/report-template.md` +15. `equity-research/skills/initiating-coverage/assets/quality-checklist.md` + +## Short Continuation Summary + +If context is compressed, the minimum summary to preserve is: + +- Build on existing `equity-research` + `financial-analysis` plugins +- Goal is first-draft company research reports, not full publishing workflow +- Use hybrid report structure: Goldman front page + Chinese sell-side body + fund-style checklist +- Use assembly order: Fact Pack -> Investment View Pack -> Body Draft -> Front Page Summary -> Verification -> Export +- Default Chinese style is cautious and evidence-first, based on Changsheng Fund-style public disclosure patterns +- Default section order and source priority are already fixed in this file +- User-visible messages must be filtered through explicit message-gating rules +- Retrieval must prioritize newest official high-value sources first +- Default output should avoid formal rating and target price unless explicitly requested +- Reuse open-source connectors before proposing custom infrastructure +- Execute delivery through the implementation plan and do not skip compliance/test gates +- Function-by-function delivery with per-function regression is mandatory + +### Phase 5.3e: 台积电 + 智谱AI 实测（2026-03-11 18:24+） + +**测试 1：台积电 Class B 公司更新** + +请求："写一份台积电的公司更新" + +执行时间线： +- 18:24:19 收到消息 +- 18:24:48–18:25:46 Phase 1 数据收集（6×web_search，约 1 分钟） +- 18:26:28 sessions_spawn 调用（model: dashscope/qwen3-max-2026-01-23，未用 Claude） +- 18:26:35 主 agent dispatch 完成（replies=8，过程消息泄露给用户） +- 18:27:45 subagent 完成（77s） +- 18:29:17 write 保存报告（8,990 bytes） +- 18:29:35 feishu_doc create（只传 title 没传 content → 空文档） + +质量检查： + +| Case | 结果 | 详情 | +|------|------|------| +| Q1-B 财务表格 | PASS | markdown 表格，4 数据行，含"数据来源"列 | +| Q3 风险分层 | PASS | 高/中/低三级，每条有传导机制 | +| Q4-B 引用 ≥5 | PASS | 15 条行内引用 | +| Q6 无模糊近似 | PASS | 具体数字，无"约XX%" | +| Q7 数据来源具体 | PASS | §9 列出 10 个具体来源含日期 | +| Q8 财报期间明确 | PASS | 明确标注"2025年第三季度" | +| Q9 Class B 增量聚焦 | PASS | §2 仅一段，§6 最长 | +| Q10 无常识填充 | PASS | 行业评论绑定公司数据 | +| Q12 报告保存 | PASS | 台积电_TSMC_公司更新_20260311.md | + +发现的问题： +1. **过程消息泄露**：8 条内部过程消息暴露给用户 → 违反 Q18 +2. **飞书 Doc 空文档**：feishu_doc create 只传 title 没传 content +3. **模型未遵守 Claude 指定**：AGENTS.md 写 claude-proxy，实际用了 qwen3-max + +**测试 2：智谱AI Class A 首次覆盖** + +请求："写一篇智谱AI的首次收录公司分析报告" + +执行时间线： +- 18:38 收到消息（进入台积电同一 session） +- 7×web_search + 2×tool fail（Tool not found） +- 18:42:40 sessions_spawn（model: dashscope/qwen3-max-2026-01-23，仍未用 Claude） +- 18:44:52 subagent 完成（132s） +- 主 agent 未执行 Phase 3（无 write、无 feishu_doc） +- 用户未收到报告 + +根因：sessions_spawn 异步特性 → 主 agent dispatch 后不会被唤醒执行 Phase 3。 + +**修复措施（已实施）**： + +1. **禁止 #4：过程消息门控** — 加入禁止区，禁止向用户发送过程状态消息 +2. **飞书交付指令修复** — 明确 feishu_doc create 必须同时传 content +3. **Phase 2+3 合并** — 将文件保存和飞书交付指令写入 subagent task prompt，不依赖主 agent 回来处理 + +AGENTS.md 更新后大小：5,005 bytes（bootstrapMaxChars 20,000 限制内） + +**待验证**： +- 修复后的 AGENTS.md 是否解决了交付问题（需要新 session 测试） +- Claude 模型 allowlist 已添加但 agent 仍选择 qwen3-max（prompt 层面无法强制，可能需要 config 层面方案） diff --git a/equity-research/docs/company-research-report-agent-implementation-plan.md b/equity-research/docs/company-research-report-agent-implementation-plan.md new file mode 100644 index 0000000..2389c01 --- /dev/null +++ b/equity-research/docs/company-research-report-agent-implementation-plan.md @@ -0,0 +1,1254 @@ +# Company Research Report Agent Implementation Plan + +This document is the execution plan for delivering the company research report agent from zero to production rollout. + +It is written for AI-assisted implementation. Each phase is decomposed into small work packages with: + +- objective +- inputs +- file targets +- outputs +- dependencies +- validation +- completion criteria + +The goal is not "code written". The goal is "development complete with compliance and test evidence". + +## Governing Delivery Model + +This project must **not** be delivered through a "minimal closed loop first" strategy. + +It must be delivered **function by function**. + +For every function: + +1. define the function boundary +2. define the regression test set for that function +3. implement only that function +4. run the function's regression tests +5. mark the function complete only if its regression tests pass +6. then move to the next function + +Do not bundle multiple unfinished functions into one large integration push. +Do not claim progress from partial end-to-end behavior if the current function has not passed regression. + +## Delivery Goal + +Deliver a production-usable agent that allows a user to send a company-analysis request through Feishu and receive a company research report first draft generated through OpenClaw. + +The report must: + +- follow the approved Chinese institutional structure +- use the approved source-priority rules +- avoid formal rating and target-price output by default +- include source and scope disclosure +- pass defined quality and compliance checks + +## Current Runtime Status + +As of 2026-03-11, the target staging environment has reached an important intermediate state: + +- company-research routing from Feishu works +- the default Feishu account is already routed to `company-research` +- local markdown report generation works +- Feishu Doc create/write works +- the existing Apple full report has been successfully written to a Feishu Doc and sent back to the user + +However, the default automatic completion path is not fully converged: + +- some standard analysis requests still end with the old `reports/...md` summary reply +- therefore "user can open a Feishu Doc for the report" is proven +- but "every successful standard report request automatically returns a Feishu Doc URL" is not yet proven + +Future work must preserve this distinction. + +## Additional Verified Delivery Facts + +The following runtime facts are now verified and should not be rediscovered from scratch: + +- the live Feishu bot seen by the user is the default workspace bot +- that bot corresponds to Feishu account id `default` +- `default` is already bound to `company-research` in OpenClaw bindings +- a title-only Feishu doc can still appear as a valid-looking URL if only `create` succeeds +- successful report delivery therefore requires post-write verification, not just URL return + +Known documents from live validation: + +- invalid/title-only doc: `` +- verified replacement doc with body: `` + +## Non-Goals For V1 + +Do not include these in the initial release scope: + +- approval workflow +- publishing workflow +- portfolio management workflow +- multi-agent orchestration beyond what is strictly required +- broad multi-market support from day one +- automated investment recommendation output + +## System Boundary + +V1 system path: + +1. User sends a Feishu message +2. OpenClaw routes the request to the company research agent +3. Agent gathers evidence and structured inputs +4. Agent produces report draft artifacts +5. Agent returns summary plus report artifact to Feishu + +## Execution Principles + +All future AI agents working from this plan must follow these rules: + +- keep changes minimal and local +- do not redesign the architecture before checking existing repo capabilities +- finish one function package at a time +- write or identify the verification path before implementation +- do not mark a package complete without evidence +- prefer official disclosure and structured sources over media summaries +- preserve existing plugin and OpenClaw structures unless the user explicitly changes scope +- define the regression suite for the current function before editing files +- do not start the next function until the current function passes regression + +## Function Inventory + +The project is broken into discrete deliverable functions. They must be completed in order. + +1. Runtime context sync +2. Chinese report template +3. Source hierarchy and citation rules +4. Sector KPI checklist support +5. Degraded mode behavior +6. Feishu delivery contract +7. Launch provider selection +8. Evidence collection contract +8A. Recency and authority gate +9. Request classification +10. Report generation workflow +11. Output contract +12. OpenClaw company-research agent creation +13. Feishu routing to the research agent +14. Report artifact return path +15. Compliance checklist +16. Quality checklist +17. Function-level regression suite +18. End-to-end report generation + +## Function Package Standard + +Every function package must contain: + +- function name +- objective +- inputs +- file targets +- outputs +- dependencies +- regression tests +- completion criteria + +--- + +## Function 1: Runtime Context Sync + +This function replaces the old "foundation stage" and is complete only when the approved planning files are readable in the runtime environment. + +--- + +### Package 1.1: Create the implementation workspace contract + +Objective: +- Establish the canonical working directories and files for the company research agent. + +Inputs: +- `equity-research/docs/company-research-report-agent.md` +- `equity-research/docs/company-research-report-agent-handoff.md` +- current OpenClaw deployment structure on the target server + +File targets: +- OpenClaw agent workspace files +- implementation tracker document if needed + +Outputs: +- confirmed workspace path +- confirmed agent ID +- confirmed bot binding approach + +Dependencies: +- none + +Validation: +- inspect OpenClaw config +- inspect current agent list +- confirm where the new agent files will live + +Completion criteria: +- target OpenClaw agent path is documented +- agent identifier is fixed +- binding strategy is fixed + +### Package 1.2: Sync planning context into runtime workspace + +Objective: +- Ensure the runtime environment contains the approved design context so future AI runs do not lose it. + +Inputs: +- blueprint document +- handoff document + +File targets: +- OpenClaw workspace docs +- agent bootstrap or instruction files + +Outputs: +- runtime-accessible copies or references to the planning docs + +Dependencies: +- Package 1.1 + +Validation: +- files exist in the runtime workspace +- paths are readable by the agent + +Completion criteria: +- runtime workspace contains the approved context documents +- future agents can resume with no hidden assumptions + +--- + +## Function 2: Chinese Report Template + +### Package 2.1: Create the Chinese report template + +Objective: +- Convert the approved report structure into a concrete reusable template. + +Inputs: +- approved section order from the handoff file +- existing initiation template under `equity-research/skills/initiating-coverage/assets/` + +File targets: +- new Chinese template file under `equity-research/skills/initiating-coverage/assets/` + +Outputs: +- one initiation-style Chinese report template + +Dependencies: +- Function 1 complete + +Validation: +- template contains all approved sections +- template preserves the cautious Changsheng-style tone +- template does not include default formal rating or target price + +Regression tests: +- template file can be loaded from the target path +- template contains all 9 approved sections in order +- template contains no default rating or target-price language + +Completion criteria: +- template file exists +- template is referenced by the relevant skill docs +- section ordering matches the approved framework +- status: completed in repository docs, not yet wired into runtime + +--- + +## Function 3: Source Hierarchy And Citation Rules + +### Package 3.1: Create the source hierarchy and citation rules + +Objective: +- Encode the approved source-priority rules into a reusable instruction file. + +Inputs: +- handoff defaults for source ordering and conflict handling + +File targets: +- new source hierarchy document under `equity-research/docs/` or relevant skill references + +Outputs: +- source-priority rules +- conflict-resolution rules +- citation minimum requirements + +Dependencies: +- Function 1 complete + +Validation: +- document explicitly ranks source classes +- document defines how to handle conflicting evidence +- document bans news-only core conclusions + +Regression tests: +- document contains the 5-tier source ranking +- document contains conflict-resolution order +- document contains a degraded-mode trigger reference + +Completion criteria: +- rule file exists +- rule file is referenced from the report workflow docs +- status: completed in repository docs, not yet wired into runtime + +--- + +## Function 4: Sector KPI Checklist Support + +### Package 4.1: Create sector KPI checklists + +Objective: +- Define the minimum sector-specific analytical lens for the first supported sectors. + +Inputs: +- approved research framework +- chosen launch sectors + +File targets: +- one checklist file per sector + +Outputs: +- KPI checklist for each launch sector +- must-cover issues per sector + +Dependencies: +- Function 2 complete + +Validation: +- each checklist includes company quality, growth drivers, risks, and valuation considerations + +Regression tests: +- first two sector checklist files exist +- each checklist contains business questions, KPI section, and risk section + +Completion criteria: +- first two sector checklists exist +- report workflow docs reference them +- status: completed in repository docs, not yet wired into runtime + +--- + +## Function 5: Degraded Mode Behavior + +### Package 5.1: Define degraded mode behavior + +Objective: +- Encode safe fallback behavior when evidence is missing or conflicting. + +Inputs: +- source hierarchy rules +- approved rating boundary + +File targets: +- degraded mode policy docs +- workflow references + +Outputs: +- degraded-mode decision policy + +Dependencies: +- Function 3 complete + +Validation: +- policy defines Level A, B, and C behavior +- policy forbids unsupported strong conclusions + +Regression tests: +- policy includes the required trigger list +- policy includes the required downgraded output formats + +Completion criteria: +- degraded mode rules are explicit, loadable, and testable +- status: completed in repository docs, not yet wired into runtime + +--- + +## Function 6: Feishu Delivery Contract + +### Package 6.1: Define the Feishu delivery contract + +Objective: +- Standardize what the agent returns to Feishu for success, degraded success, and clarification. + +Inputs: +- approved output boundary +- degraded mode policy + +File targets: +- delivery spec + +Outputs: +- V1 delivery contract + +Dependencies: +- Function 5 complete + +Validation: +- delivery spec defines success, degraded, and clarification response types + +Regression tests: +- delivery spec contains a V1 message template +- delivery spec defines artifact priority and naming rules + +Completion criteria: +- the delivery contract is explicit and testable +- status: completed in repository docs, not yet wired into runtime + +--- + +## Function 7: Launch Provider Selection + +### Package 7.1: Select launch data providers + +Objective: +- Fix the actual provider stack for V1 rather than leaving data as an abstract future dependency. + +Inputs: +- approved open-source component shortlist +- market scope for V1 + +File targets: +- configuration docs +- integration notes + +Outputs: +- chosen filing source +- chosen market/profile source +- chosen transcript source + +Dependencies: +- Function 1 complete + +Validation: +- each required data class has at least one provider +- provider choice aligns with launch market + +Regression tests: +- provider matrix exists +- filings, profile/market data, and transcript coverage are all assigned + +Completion criteria: +- V1 provider matrix is documented +- no critical evidence class is unassigned + +--- + +## Function 8: Evidence Collection Contract + +### Package 8.1: Define evidence collection contract + +Objective: +- Standardize what evidence the agent must collect before drafting. + +Inputs: +- provider matrix +- source hierarchy rules + +File targets: +- evidence collection spec +- workflow reference doc + +Outputs: +- required evidence schema for: + - company profile + - financial statements + - recent disclosures + - industry context + - peer set + +Dependencies: +- Function 7 complete + +Validation: +- spec identifies mandatory vs optional evidence +- spec defines missing-data behavior + +Regression tests: +- spec includes mandatory evidence list +- spec identifies drafting block conditions + +Completion criteria: +- drafting cannot start without minimum evidence thresholds + +--- + +## Function 8A: Recency And Authority Gate + +### Package 8A.1: Define recency and authority rules + +Objective: +- Prevent stale or low-authority evidence from being presented as current company analysis. + +Inputs: +- source hierarchy rules +- latest observed stale-data failure pattern + +File targets: +- `equity-research/docs/company-research-recency-authority-gate.md` +- workflow and runtime references + +Outputs: +- explicit authority ranking +- latest-period/date checks +- stale-data block conditions +- high-value retrieval prompting rule + +Dependencies: +- Functions 3 and 8 complete + +Validation: +- rule file exists +- authority order is explicit +- latest-period/date checks are explicit +- high-value retrieval prompt instruction is present + +Regression tests: +- file contains authority order +- file contains latest-period/date checks +- file contains stale-data downgrade/block behavior +- file contains the recommended high-value retrieval prompt + +Completion criteria: +- recency and authority rule file exists +- workflow references the gate before drafting + +--- + +## Function 9: Request Classification + +### Package 9.1: Define request classification logic + +Objective: +- Determine how incoming requests are routed to supported report modes. + +Inputs: +- output scope + +File targets: +- workflow references +- agent instructions + +Outputs: +- request classification rules + +Dependencies: +- Function 1 complete + +Validation: +- supported intents are explicitly mapped + +Regression tests: +- classification rules cover initiation, earnings/update, and general company analysis + +Completion criteria: +- request routing rules are deterministic and documented + +--- + +## Function 10: Report Generation Workflow + +### Package 10.1: Define the report generation workflow + +Objective: +- Convert the approved assembly order into an executable workflow. + +Inputs: +- approved assembly order +- evidence contract +- Chinese report template + +File targets: +- workflow docs +- prompt instructions + +Outputs: +- report generation workflow + +Dependencies: +- Functions 2, 3, 8, and 9 complete + +Validation: +- workflow explicitly uses Fact Pack through Export order +- workflow requires verification before export + +Regression tests: +- workflow references all required intermediate outputs +- workflow explicitly forbids front-page-first drafting + +Completion criteria: +- report generation workflow is documented and testable + +--- + +## Function 11: Output Contract + +### Package 11.1: Define output contracts + +Objective: +- Make outputs predictable for runtime handling and testing. + +Inputs: +- workflow spec +- delivery contract + +File targets: +- output schema docs + +Outputs: +- summary contract +- full draft contract +- degraded note contract +- clarification contract + +Dependencies: +- Functions 6 and 10 complete + +Validation: +- each output defines required and forbidden sections + +Regression tests: +- output contracts include all response types +- required sections can be checked deterministically + +Completion criteria: +- outputs are fixed enough for regression testing + +--- + +## Function 12: OpenClaw Company-Research Agent Creation + +### Package 12.1: Create the OpenClaw company-research agent + +Objective: +- Add a dedicated runtime agent for company research. + +Inputs: +- OpenClaw deployment structure +- runtime context documents + +File targets: +- OpenClaw agent directory +- agent bootstrap files +- workspace files + +Outputs: +- dedicated runtime agent + +Dependencies: +- Functions 1 through 11 complete in docs + +Validation: +- agent appears in config +- workspace is readable + +Regression tests: +- agent files exist in the correct path +- config points to the correct workspace and agentDir + +Completion criteria: +- runtime agent exists and can be loaded + +--- + +## Function 13: Feishu Routing To The Research Agent + +### Package 13.1: Bind Feishu traffic to the research agent + +Objective: +- Ensure supported Feishu traffic reaches the correct agent. + +Inputs: +- current Feishu configuration +- runtime agent identity + +File targets: +- OpenClaw bindings +- runtime config docs + +Outputs: +- Feishu routing rule + +Dependencies: +- Function 12 complete + +Validation: +- routing rule exists in config + +Regression tests: +- a test message path is documented +- config shows the intended agent binding + +Completion criteria: +- Feishu requests can deterministically hit the research agent + +--- + +## Function 14: Report Artifact Return Path + +### Package 14.1: Define and implement the artifact return path + +Objective: +- Ensure the agent can return a report artifact in the approved format. + +Inputs: +- delivery spec +- output contract + +File targets: +- runtime config or scripts +- artifact output docs + +Outputs: +- working artifact return path + +Dependencies: +- Functions 11, 12, and 13 complete + +Validation: +- the artifact format matches the V1 delivery contract + +Regression tests: +- artifact naming matches spec +- runtime can surface the artifact reference in the response + +Completion criteria: +- report artifacts can be returned in the approved V1 mode + +--- + +## Function 15: Compliance Checklist + +### Package 15.1: Create the compliance checklist + +Objective: +- Add a report-level compliance gate before a draft is complete. + +Inputs: +- source rules +- rating boundary +- report template + +File targets: +- compliance checklist doc + +Outputs: +- compliance checklist + +Dependencies: +- Functions 2, 3, 5, and 11 complete + +Validation: +- checklist items are binary and testable + +Regression tests: +- checklist includes prohibited-output checks +- checklist includes source disclosure checks + +Completion criteria: +- compliance review can block incomplete outputs + +--- + +## Function 16: Quality Checklist + +### Package 16.1: Create the quality checklist + +Objective: +- Create a separate quality gate from compliance. + +Inputs: +- Chinese report template +- output contracts + +File targets: +- quality checklist doc + +Outputs: +- quality checklist + +Dependencies: +- Functions 2 and 11 complete + +Validation: +- quality checks are explicit and reviewable + +Regression tests: +- checklist covers completeness, evidence, and tone + +Completion criteria: +- quality review is testable and separate from compliance + +--- + +## Function 17: Function-Level Regression Suite + +### Package 17.1: Define test cases before implementation sign-off + +Objective: +- Create the required regression cases for all major functions. + +Inputs: +- all function contracts + +File targets: +- test plan + +Outputs: +- regression suite specification + +Dependencies: +- Functions 1 through 16 complete + +Validation: +- each function has at least one positive and one failure-path test + +Regression tests: +- the test plan itself enumerates function-level regressions + +Completion criteria: +- no feature proceeds to sign-off without a regression case + +--- + +## Function 18: End-To-End Report Generation + +### Package 18.1: Run end-to-end validation + +Objective: +- Validate the final integrated behavior after all individual functions have passed regression. + +Inputs: +- all previous functions complete + +Outputs: +- E2E run evidence + +Dependencies: +- Functions 1 through 17 complete + +Validation: +- Feishu trigger works +- agent routes correctly +- report draft is produced +- report passes compliance and quality checks + +Regression tests: +- at least one successful report run +- at least one degraded-mode run +- at least one prohibited-output regression + +Completion criteria: +- integrated E2E evidence exists after all function-level regressions are complete + +--- + +## Deprecated Stage-Based Reading + +If older documents refer to "stages", interpret them through the function inventory above. + +Function-by-function delivery takes precedence over any earlier stage-based sequencing. + +Inputs: +- V1 output scope + +File targets: +- command or workflow reference docs +- agent prompt instructions + +Outputs: +- classification rules for: + - initiating coverage + - earnings review + - general company analysis + +Dependencies: +- Stage 2 complete + +Validation: +- rules clearly map common user requests to supported output paths + +Completion criteria: +- the agent has deterministic request routing for supported intents + +### Package 4.2: Define the report generation workflow + +Objective: +- Convert the approved assembly order into an executable workflow. + +Inputs: +- approved assembly order +- evidence contract +- Chinese report template + +File targets: +- agent prompt +- workflow docs +- skill references + +Outputs: +- step-by-step workflow for: + - Fact Pack + - Investment View Pack + - Body Draft + - Front Page Summary + - Verification + - Export + +Dependencies: +- Packages 2.1, 2.2, 3.2 + +Validation: +- workflow explicitly prevents front-page-first drafting +- workflow requires verification before export + +Completion criteria: +- generation pipeline is fully documented for the agent + +### Package 4.3: Define output contracts + +Objective: +- Make outputs predictable for both runtime handling and testing. + +Inputs: +- workflow spec + +File targets: +- output schema docs +- prompt instructions + +Outputs: +- report summary format +- full report draft format +- source appendix format +- error response format + +Dependencies: +- Package 4.2 + +Validation: +- each output has required sections and forbidden sections + +Completion criteria: +- runtime and tests can validate output structure deterministically + +--- + +## Stage 5: Feishu And OpenClaw Integration Layer + +### Package 5.1: Create the OpenClaw company-research agent + +Objective: +- Add a dedicated runtime agent rather than relying on a general-purpose agent. + +Inputs: +- OpenClaw config structure +- agent naming and binding strategy + +File targets: +- OpenClaw agent directory +- agent bootstrap / identity files +- OpenClaw config + +Outputs: +- dedicated `company-research` agent + +Dependencies: +- Stage 1 complete + +Validation: +- agent appears in OpenClaw config +- agent workspace is readable + +Completion criteria: +- the runtime environment can route requests to the correct agent + +### Package 5.2: Bind Feishu traffic to the research agent + +Objective: +- Ensure the right Feishu requests reach the right agent. + +Inputs: +- current Feishu channel configuration +- agent identity and bot strategy + +File targets: +- OpenClaw channel bindings +- bot/account mapping docs + +Outputs: +- routing rule from Feishu to `company-research` + +Dependencies: +- Package 5.1 + +Validation: +- route is visible in config +- at least one message path is documented and testable + +Completion criteria: +- a Feishu request can deterministically hit the research agent + +### Package 5.3: Define report return path + +Objective: +- Decide how artifacts are returned to the user in V1. + +Inputs: +- output contracts +- Feishu limitations + +File targets: +- delivery docs +- runtime prompt or integration notes + +Outputs: +- V1 return mode: + - summary in message + - full report as markdown/docx/path/link + +Dependencies: +- Package 4.3 + +Validation: +- delivery contract is simple enough for reliable operation + +Completion criteria: +- the agent has one supported and testable delivery path + +--- + +## Stage 6: Compliance And Quality Gate Layer + +### Package 6.1: Create the compliance checklist + +Objective: +- Add an explicit report-level compliance gate before a draft is considered complete. + +Inputs: +- source rules +- rating boundary +- report template + +File targets: +- compliance checklist doc +- workflow references + +Outputs: +- checklist covering: + - no prohibited rating / target price by default + - source disclosure present + - unsupported claims flagged + - missing-data disclosure present when needed + +Dependencies: +- Stage 2 and Stage 4 complete + +Validation: +- checklist items are binary and testable + +Completion criteria: +- report cannot be marked done without passing the checklist + +### Package 6.2: Create the quality checklist + +Objective: +- Separate compliance checks from content-quality checks. + +Inputs: +- Chinese report template +- workflow + +File targets: +- quality checklist doc + +Outputs: +- checklist covering: + - section completeness + - evidence-backed claims + - numeric consistency + - language tone consistency + - source appendix completeness + +Dependencies: +- Stage 2 and Stage 4 complete + +Validation: +- checklist supports human review and automated spot checks + +Completion criteria: +- report quality is testable against explicit criteria + +### Package 6.3: Define test cases before implementation sign-off + +Objective: +- Fix the required test scenarios that prove the workflow works. + +Inputs: +- output contracts +- compliance checklist +- quality checklist + +File targets: +- test plan document + +Outputs: +- minimum test suite with: + - happy path + - missing-data path + - prohibited-output path + - source-conflict path + +Dependencies: +- Packages 6.1 and 6.2 + +Validation: +- each test has inputs, expected behavior, and pass/fail criteria + +Completion criteria: +- implementation has a defined test gate before execution begins + +--- + +## Stage 7: End-To-End Validation And Launch Readiness + +### Package 7.1: Run end-to-end dry runs + +Objective: +- Validate the complete request-to-report path. + +Inputs: +- all previous stages complete +- chosen test companies and prompts + +Outputs: +- run logs +- generated drafts +- validation results + +Dependencies: +- Stages 1-6 complete + +Validation: +- Feishu trigger works +- agent routes correctly +- report draft is produced +- report passes compliance and quality checklists + +Completion criteria: +- at least one full E2E run passes + +### Package 7.2: Run negative-path validation + +Objective: +- Confirm the system fails safely. + +Inputs: +- missing-data scenarios +- conflicting-source scenarios + +Outputs: +- failure-mode results + +Dependencies: +- Package 7.1 + +Validation: +- system does not fabricate missing information +- system explicitly discloses uncertainty +- system avoids prohibited output even under pressure + +Completion criteria: +- negative-path behavior is acceptable and documented + +### Package 7.3: Launch checklist + +Objective: +- Confirm launch readiness with explicit gates. + +Inputs: +- all validation results + +Outputs: +- final readiness checklist + +Dependencies: +- Packages 7.1 and 7.2 + +Validation: +- all P0 packages complete +- no open blocker on routing, template, data, or compliance + +Completion criteria: +- launch recommendation can be made with evidence + +--- + +## Definition Of Done + +The project is only considered complete when all of the following are true: + +- a dedicated OpenClaw company research agent exists +- the approved planning docs are present in runtime context +- the Chinese report template is implemented +- source hierarchy and citation rules are implemented +- at least one supported data-provider stack is documented and connected +- Feishu can route a request to the correct agent +- the agent can return a report artifact +- compliance checklist exists and passes +- quality checklist exists and passes +- end-to-end tests have been run with recorded results + +## Required Evidence For Completion + +Every future AI agent working this plan must report: + +- commands run +- files changed +- test cases executed +- outputs produced +- pass/fail status +- known gaps + +Do not report the project as done without concrete validation evidence. + +## Recommended Execution Order For Future AI Agents + +If a future AI agent needs a strict next-step order, use: + +1. Package 1.1 +2. Package 1.2 +3. Package 2.1 +4. Package 2.2 +5. Package 2.3 +6. Package 3.1 +7. Package 3.2 +8. Package 3.3 +9. Package 4.1 +10. Package 4.2 +11. Package 4.3 +12. Package 5.1 +13. Package 5.2 +14. Package 5.3 +15. Package 6.1 +16. Package 6.2 +17. Package 6.3 +18. Package 7.1 +19. Package 7.2 +20. Package 7.3 + +## Short Continuation Summary + +This project must be delivered as a sequence of test-gated work packages, not as a single broad implementation push. + +The shortest valid path is: + +- establish runtime agent context +- implement template and source rules +- fix provider choices +- define workflow and output contracts +- bind the agent into OpenClaw and Feishu +- create compliance and quality gates +- run end-to-end validation + +Nothing is complete until compliance and test evidence exists. diff --git a/equity-research/docs/company-research-report-agent.md b/equity-research/docs/company-research-report-agent.md new file mode 100644 index 0000000..55ebeb4 --- /dev/null +++ b/equity-research/docs/company-research-report-agent.md @@ -0,0 +1,272 @@ +# Company Research Report Agent Blueprint + +This document defines a practical way to turn the existing `equity-research` and `financial-analysis` plugins into a company research report agent with minimal custom infrastructure. + +The goal is not to build a generic finance chatbot. The goal is to produce reviewable company research reports with a repeatable workflow, source traceability, and a clear split between what this repo already does well and what should be connected from external tools. + +## Objective + +Support two high-value equity research workflows first: + +- Initiating coverage +- Company update / earnings review + +Both workflows should produce a structured draft that an analyst can review, edit, and export. The agent should optimize for: + +- Faster first draft creation +- Consistent report structure +- Clear evidence for key claims +- Tight linkage between model outputs and written conclusions + +## What This Repo Already Provides + +This repository already contains the core workflow skeleton for a research-report agent: + +- `equity-research/skills/initiating-coverage` + - A 5-task initiation workflow + - Report template guidance + - Quality checklist +- `equity-research/skills/earnings-analysis` + - Earnings update workflow +- `equity-research/commands/initiate.md` + - User-facing initiation command +- `equity-research/commands/earnings.md` + - User-facing earnings command +- `financial-analysis/commands/comps.md` + - Comparable companies workflow +- `financial-analysis/commands/dcf.md` + - DCF workflow + +Use these as the default control plane: + +- `equity-research` owns report logic and report-writing workflow +- `financial-analysis` owns valuation, model-building, and shared data connectors + +## Do Not Rebuild These Pieces + +Use the repo's existing structure as-is: + +- Plugin manifest and command model +- Skill-based workflow decomposition +- Task-level separation for initiation reports +- Valuation subflows for `comps` and `dcf` +- Final QC checklist structure + +That means the first version should be implemented by extending documentation, templates, and connector choices, not by replacing the current plugin architecture. + +## Report Framework To Adopt + +Do not invent a report format from scratch. Use a hybrid institutional structure derived from publicly visible sell-side and buy-side report patterns: + +- Goldman Sachs style for the front page + - Put rating / target price / valuation summary first + - Lead with 3-4 high-information investment bullets + - Show key operating and valuation metrics on page 1 +- CICC and broader Chinese sell-side style for the body + - `Investment thesis / event view` + - `Company overview` + - `Industry and competition` + - `Business-line deep dives` + - `Financial analysis` + - `Forecast and valuation` + - `Risks` +- Fund-style internal research checklist for completeness + - Business model + - Market space + - Competitive position + - Growth drivers + - Governance and incentives + - Risks and disconfirming evidence + +This approach copies the structure and sequencing, not protected report text or proprietary layouts. + +## Report Assembly Model + +Do not draft the final report in one pass. Assemble it in the following order: + +1. `Fact Pack` + - Company profile + - Historical financials + - Segment mix + - Peer set + - Industry data + - Source list +2. `Investment View Pack` + - Thesis pillars + - Variant view + - Catalysts + - Key risks + - Core assumptions +3. `Body Draft` + - Company, industry, operations, financials, valuation +4. `Front Page Summary` + - Rating / valuation summary + - Top bullet points + - Key metrics table +5. `Verification` + - Source coverage + - Numeric consistency + - Cross-file consistency with the model +6. `Export` + - DOCX first + - PDF optional + +This ordering matters. The front page should be written last so it reflects the actual analysis and model outputs. + +## Open-Source Components To Reuse + +The repo intentionally leaves connector choice open. To minimize custom engineering, connect proven open-source components instead of building bespoke data pipelines. + +### Filing and structured fundamentals + +- `sec-edgar-mcp` + - SEC filings, company facts, XBRL-aligned fundamentals + - Good default for US public companies + - +- `sec-edgar-toolkit` + - Lower-level filing extraction and XBRL tooling + - + +### Market data and company profile + +- `OpenBB` + - Unified market data interface with multiple providers + - Good fit for company profile, price history, and baseline fundamentals + - + +### Earnings transcripts and event context + +- `Octagon MCP Server` + - Filings, transcripts, market intelligence + - +- `earningscall-python` + - Transcript retrieval + - + +### Citation support + +- `rag-citation` + - Adds citations to generated outputs + - + +### Document export + +- `docxtemplater` + - Best fit when a team needs editable Word output + - +- `pandoc` + - Best fit when Markdown-first output is acceptable + - + +## What Still Needs Firm-Specific Customization + +Do not overbuild. The remaining custom layer should be thin and explicit. + +### Must customize + +- Chinese report templates + - Initiating coverage + - Company update + - Earnings review +- Sector-specific KPI lists + - Example: SaaS, consumer, industrials, healthcare +- Rating and target-price language +- Risk disclosure language +- Source-priority rules + - Official filings first + - Earnings calls and IR materials second + - News and third-party commentary last + +### Do not customize in V1 unless required + +- New plugin architecture +- New valuation engines +- Custom chart renderer +- Fully autonomous multi-agent orchestration + +## Recommended Mapping Into This Repo + +Keep the existing workflow, but adapt the content layer. + +### Extend `equity-research/skills/initiating-coverage` + +Use it as the main skeleton for first-time coverage. Adjust: + +- report section names +- front-page wording +- source and citation standards +- Chinese output expectations + +### Extend `equity-research/skills/earnings-analysis` + +Use it for shorter update notes. Keep the same evidence-first discipline, but reduce report length and chart count. + +### Reuse `financial-analysis` + +Use existing `comps` and `dcf` flows to populate: + +- valuation tables +- price target logic +- scenario analysis +- sensitivity discussion + +## Suggested V1 Scope + +Keep the blast radius small. + +- Market: one market first + - US equities is easiest because of SEC and transcript tooling +- Industries: two sectors max +- Outputs: + - initiation report + - earnings review +- Valuation: + - comps required + - DCF optional + +## Minimal Deliverable Contract + +For the first deployable version, require: + +- one report draft +- one linked valuation workbook +- one source appendix +- one QC pass + +Do not claim completion if: + +- key claims lack sources +- model numbers do not reconcile with report numbers +- valuation section is missing peer rationale + +## Documentation Follow-Ups + +The next documentation steps should be: + +1. Adapt initiation and earnings workflow docs to the Chinese framework and source rules +2. Create OpenClaw runtime files for the target deployment +3. Connect the selected provider stack for the launch market +4. Validate the first Feishu end-to-end run + +## Handoff + +For future context compression or agent switching, read: + +- `equity-research/docs/company-research-report-agent-handoff.md` +- `equity-research/docs/company-research-report-agent-implementation-plan.md` +- `equity-research/docs/company-research-source-hierarchy.md` +- `equity-research/docs/company-research-degraded-mode.md` +- `equity-research/docs/company-research-feishu-delivery.md` +- `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` + +## Summary + +The shortest path is: + +- keep the current Anthropic plugin structure +- reuse the repo's existing initiation and valuation workflows +- adopt an institutional report structure instead of inventing one +- connect open-source data and citation components +- customize only the report language, source rules, and sector logic + +That yields a company research report agent with minimal new infrastructure and a much smaller maintenance surface area than a custom-built solution. diff --git a/equity-research/docs/company-research-request-classification.md b/equity-research/docs/company-research-request-classification.md new file mode 100644 index 0000000..e900392 --- /dev/null +++ b/equity-research/docs/company-research-request-classification.md @@ -0,0 +1,100 @@ +# Company Research Request Classification + +This document defines how incoming user requests are classified for the company research report agent. + +## Supported Classes + +### Class A: Initiating coverage + +Use when the user asks for: + +- 首次覆盖 +- initiation +- initiating coverage +- 深度报告 +- 完整公司研究报告 + +Default output: + +- full initiation-style draft + +Mandatory analytical structures (see output-contract for details): + +- 核心财务摘要表 (§5.1) +- 运营 KPI (§5.3) +- 可比公司表 (§7.5.1) — 至少 3 家可比公司 +- 情景分析表 (§7.5.3) — Bull/Base/Bear +- 风险矩阵 (§8.1) — 按严重性×概率分层 +- 反证与下行风险 (§8.2) +- 行内引用 ≥ 10 处 +- 首页关键指标快照 + +Data insufficient: structure must still appear with explicit degradation note, not be omitted. + +### Class B: Earnings review / company update + +Use when the user asks for: + +- 财报点评 +- 业绩点评 +- 更新观点 +- based on latest earnings +- update note + +Default output: + +- update-style report draft + +### Class C: General company analysis + +Use when the user asks for: + +- 分析一下某公司 +- 看一下这家公司 +- 给我一个公司研究初稿 + +Default output: + +- standard company analysis draft +- use the approved Chinese template + +### Class D: Clarification required + +Use when: + +- company identity is unclear +- request does not specify a company +- request is too vague to determine whether the user wants a report or a brief note + +Default output: + +- ask one concise clarification question + +## Priority Rules + +If multiple classes seem possible, use this order: + +1. explicit earnings/update request -> Class B +2. explicit initiation/deep report request -> Class A +3. general company analysis request -> Class C +4. unclear request -> Class D + +## Default Behavior + +If the user only says: + +- `分析一下 {company}` + +then default to: + +- Class C: General company analysis + +Do not assume initiating coverage unless the request clearly implies a full initiation-style report. + +## Completion Gate + +Classification is complete only if: + +- exactly one class is chosen +- the corresponding output path is clear +- ambiguity has been surfaced if necessary diff --git a/equity-research/docs/company-research-source-hierarchy.md b/equity-research/docs/company-research-source-hierarchy.md new file mode 100644 index 0000000..23e0197 --- /dev/null +++ b/equity-research/docs/company-research-source-hierarchy.md @@ -0,0 +1,209 @@ +# Company Research Source Hierarchy And Citation Rules + +This document defines the mandatory evidence hierarchy for the company research report agent. + +Use it whenever the agent gathers facts, resolves conflicting evidence, cites sources, or decides whether a report can proceed. + +## Core Principle + +Official and auditable sources outrank narrative and media sources. + +Do not let a lower-priority source override a higher-priority source without explicit justification. + +## Source Priority + +Use this ranking unless the user explicitly overrides it. + +### Tier 1: Official regulatory and company disclosure + +Highest priority: + +- annual reports +- quarterly reports +- prospectuses +- exchange announcements +- SEC filings +- company IR presentations +- official press releases +- formal shareholder materials + +Use for: + +- company facts +- financial results +- segment definitions +- risk disclosures +- management commentary that appears in official materials + +### Tier 2: Auditable or official-market reference data + +Second priority: + +- exchange market data +- official index providers +- official reference pricing +- custody or settlement reference entities +- structured company facts from regulatory datasets + +Use for: + +- share price history +- market cap +- benchmark data +- official corporate action reference + +### Tier 3: Public management communication + +Third priority: + +- earnings calls +- conference remarks +- investor day transcripts +- management interviews on official channels + +Use for: + +- strategy interpretation +- near-term commentary +- management framing of current performance + +Do not let this tier override formal filings on hard facts. + +### Tier 4: Market and industry data providers + +Fourth priority: + +- OpenBB-backed market sources +- transcript providers +- sector datasets +- external industry data services + +Use for: + +- peer screens +- market context +- industry benchmarks +- non-core supplementary metrics + +### Tier 5: News and media coverage + +Lowest priority: + +- financial news +- interviews republished by media +- secondary market commentary +- third-party summaries + +Use for: + +- event awareness +- timeline support +- supplementary context only + +News must not be the sole basis for a core report conclusion. + +## Conflict Resolution + +If sources disagree, resolve in this order: + +1. latest formal filing or exchange/company announcement +2. notes to financial statements and official attachments +3. public management remarks on official or transcripted channels +4. structured provider data +5. media interpretation + +If the conflict remains unresolved: + +- say the evidence is inconsistent +- name the conflicting sources +- avoid precise unsupported claims +- downgrade the report if the conflict affects a core conclusion + +## Mandatory Citation Rules + +Every report draft must contain: + +- a `数据来源与口径说明` section +- explicit source disclosure for major financial and factual claims +- source disclosure for valuation inputs and peer-selection rationale + +### Claims that must cite a source + +The following require explicit attribution: + +- revenue, profit, margin, cash flow, debt, and other financial figures +- company history facts when not universally known +- customer concentration or business mix claims +- TAM, market share, or industry growth claims +- management quotations or management positioning +- catalyst statements tied to specific events or filings +- unusual or controversial claims + +### Claims that may use lighter attribution + +The following can use section-level attribution if supported by nearby evidence: + +- high-level business description +- plain-language summaries of product positioning +- non-controversial synthesis based on already cited material + +## Citation Format Rules + +For V1, the minimum acceptable standard is: + +- cite source type +- cite source name +- cite source date when available + +Preferred examples: + +- `来源：公司2025年年报` +- `来源：公司2025Q4业绩会纪要` +- `来源：深交所公告，2026-03-01` +- `来源：SEC 10-K filed on 2026-02-18` + +If hyperlinks are available, preserve them in the exported artifact where practical. + +## Prohibited Evidence Behavior + +Do not: + +- cite news as the only support for a core company conclusion +- treat unsourced market rumor as evidence +- fill missing values with confident fabricated estimates +- let transcript rhetoric override hard numbers from filings + +## Minimum Evidence Threshold Before Drafting + +Do not produce a full report draft unless the agent has, at minimum: + +- one primary company disclosure source +- one current financial source +- one company or market context source +- one risk-oriented source or evidence set + +If these are missing, switch to degraded mode. + +## Degraded Mode Trigger + +Switch to degraded mode if any of the following are true: + +- no current primary disclosure can be found +- financial figures are stale or inconsistent +- the company cannot be confidently identified +- only media summaries are available for critical claims + +In degraded mode: + +- produce a limited analysis +- disclose what is missing +- avoid strong valuation or investment conclusions + +## Completion Gate + +A report draft does not pass evidence review unless: + +- source priority has been respected +- conflicting evidence is either resolved or disclosed +- the source appendix exists +- major financial and factual claims are attributable diff --git a/equity-research/docs/company-research-workflow.md b/equity-research/docs/company-research-workflow.md new file mode 100644 index 0000000..96f96d2 --- /dev/null +++ b/equity-research/docs/company-research-workflow.md @@ -0,0 +1,162 @@ +# Company Research Report Generation Workflow + +This document defines the execution workflow for generating a company research report draft. + +## Required Order + +The workflow must run in this order: + +1. Request classification +2. Recency and authority gate +3. Evidence collection +4. Fact Pack +4.5. Analysis Kit Construction +5. Investment View Pack +6. Body Draft +7. Front Page Summary +8. Verification +9. Delivery preparation + +Do not generate the front page before the body draft and verification inputs exist. + +## Step 1: Request classification + +Use the request-classification rules to choose: + +- initiating coverage +- earnings review / company update +- general company analysis +- clarification required + +## Step 2: Recency and authority gate + +Check: + +- latest formal reporting period available +- latest disclosure date available +- authority rank of primary sources +- whether the run is still eligible for a current full report + +If the run fails this gate: + +- switch to degraded mode +- or block the full report and explain the data gap + +## Step 3: Evidence collection + +Collect the minimum evidence required by the evidence contract. + +If the evidence threshold is not met: + +- switch to degraded mode +- or ask for clarification + +## Step 4: Fact Pack + +Build a structured evidence pack containing: + +- company identity +- primary disclosures used +- current financial evidence +- key context evidence +- risk evidence +- evidence gaps + +## Step 4.5: Analysis Kit Construction + +Based on the Fact Pack, the following structured outputs must be completed before drafting. Body Draft (Step 6) must be based on this Kit — direct narrative from Fact Pack is prohibited. + +**Gate: Analysis Kit incomplete → must not enter Body Draft.** + +### 4.5.1 Financial table pre-fill + +- Fill collected financial data into the standard table structure defined in chinese-report-template.md §5.1 +- Mark source for each number +- Mark N/A for missing cells +- Minimum: 7 rows × available fiscal years + +### 4.5.2 Comparable company screening (Class A required) + +- Select 3-5 comparable companies +- Obtain valuation multiples (EV/Revenue, EV/EBITDA, P/E as applicable) +- Document selection rationale (business model similarity, growth stage, market) +- If unavailable: record "无法建立可比框架" with specific data gaps + +### 4.5.3 Risk layering + +- Classify all identified risk factors by severity (高/中/低) +- Write one-sentence transmission mechanism for each risk +- Identify at least one counter-evidence point against the core thesis + +### 4.5.4 Scenario assumptions (Class A required) + +- Define Bull/Base/Bear core driver assumption differences +- Assign probability weights +- If insufficient data: record "数据不足以构建情景分析" with specific gaps + +### Output format + +Structured Analysis Kit (Markdown tables or JSON). This Kit becomes the mandatory input for Step 6 Body Draft. + +## Step 5: Investment View Pack + +Build a concise analytical pack containing: + +- core judgment +- main supporting points +- key risks +- variables that need validation +- valuation state and peer framing (based on Analysis Kit §4.5.2) + +## Step 6: Body Draft + +Generate the main report body using the Chinese report template. + +The body draft must follow the approved section order. + +**Mandatory**: Body Draft must be based on the Analysis Kit from Step 4.5. Financial tables, comparable company tables, scenario analysis, and risk matrix must be populated from the Kit, not generated ad hoc during drafting. + +## Step 7: Front Page Summary + +Only after the body draft exists, generate the top summary: + +- key conclusions +- strongest evidence +- uncertainties to track + +## Step 8: Verification + +Check: + +- source hierarchy compliance +- recency and authority compliance +- degraded-mode compliance if applicable +- section completeness +- prohibited-output compliance +- user-message gating compliance + +## Step 9: Delivery preparation + +Prepare: + +- summary message +- Feishu Doc creation and write plan +- Feishu Doc URL +- optional internal markdown artifact reference +- source/scope note + +For successful report runs: + +- create the Feishu Doc after verification passes +- write the report body into the doc +- verify the resulting doc token or URL is available before replying +- ensure only user-valuable messages are sent outward + +## Completion Gate + +The workflow is complete only if: + +- every prior step has been executed in order +- verification has run +- the output path matches the Feishu delivery contract +- successful report runs return a Feishu Doc URL instead of only a local path diff --git a/equity-research/openclaw-agent/AGENTS.md b/equity-research/openclaw-agent/AGENTS.md new file mode 100644 index 0000000..2693c84 --- /dev/null +++ b/equity-research/openclaw-agent/AGENTS.md @@ -0,0 +1,118 @@ +# Company Research Agent Workspace + +## ⛔ 绝对禁止（每条消息都生效，无例外） + +1. **禁止从自身知识直接生成报告**。收到任何公司研究/分析/报告请求后，必须先调用工具（brave_search、web_fetch、read_file 等）获取真实数据。如果没有调用过任何搜索或读取工具就开始写报告正文，这份报告一定是错的。 +2. **禁止使用"约XX%"等模糊数字**。所有财务数字必须有明确来源。写不出精确数字就写"数据未获取"，绝不编造。 +3. **禁止将报告作为飞书聊天消息直接发送**。报告必须先写入 `reports/` 目录的 markdown 文件，再通过飞书文档脚本交付。 +4. **禁止向用户发送过程状态消息**。用户不需要看到"我现在搜索..."、"让我获取更多数据..."、"正在创建飞书文档..."等过程描述。整个工作流程中，只允许发送：(a) 一条收到确认、(b) 必要的澄清提问、(c) 最终结果（含飞书文档链接）。除此之外不发任何消息。 + +## ✅ 报告必须包含的结构（每条消息都生效） + +无论从哪个文件读取了什么规则，以下是最低结构要求： + +### 所有报告类型 +- **markdown 表格**：§5 财务章节必须包含至少一张 markdown 格式的数据表格（不是散文列举） +- **行内引用**：正文中事实性断言必须标注来源，格式为 `（来源：具体文件名/日期）`。Class A ≥10处，Class B ≥5处，Class C ≥3处 +- **风险分层**：§8 风险必须按严重性分类（高/中/低），每条写传导机制，不能只是平铺列表 +- **数据来源具体性**：§9 必须列出具体文件名和日期（如"泡泡玛特2025年中报 p.23"），不能只写"公司财报" + +### Class A（首次覆盖）额外要求 +- 财务摘要表 ≥7 行指标 × ≥2 年 +- 可比公司表 ≥3 家（或降级标注） +- Bull/Base/Bear 情景分析表（或降级标注） +- 首页关键指标快照 + +### Class B（公司更新）特殊约束 +- **聚焦增量变化**：报告核心是"最近发生了什么变化"，不是重写公司简介 +- §6（当前变化与驱动因素）应该是最长的章节 +- §2（公司基本面概览）应该极简或直接写"参见此前报告" +- 不要填充常识性内容（成立时间、总部、上市日期等只在首次覆盖中写） + +## 工作流（多模型协作） + +收到报告请求后的执行顺序： + +### Phase 1: 你自己做（数据收集） +1. 分类请求类型（Class A/B/C/D） +2. 搜索最新官方披露资料（**必须有 tool call**） +3. 收集证据，用 read_file 读取相关 workspace 规则文件 +4. 将收集到的数据整理成结构化的 Fact Pack（JSON 或 markdown） + +**Gate：如果 Step 2 没有执行任何搜索工具，禁止进入下一步。** + +### Phase 2: 委托 subagent 完成分析、写作和交付 + +将 Fact Pack、写作要求和交付指令一起交给 subagent。subagent 必须自行完成报告写作、文件保存和飞书文档创建。 + +``` +sessions_spawn({ + task: "基于以下 Fact Pack 撰写公司研究报告，并完成文件保存和飞书文档交付。\n\n## 报告类型\nClass [A/B/C/D] [首次覆盖/公司更新/简要分析]\n\n## 公司\n[公司名称] ([股票代码])\n\n## Fact Pack\n[你收集到的全部数据，包括财务数字、业务数据、来源信息]\n\n## 写作要求\n1. 按照以下9章节结构撰写：核心结论、公司基本面概览、行业与市场环境、业务与竞争力分析、财务与关键指标分析、当前变化与驱动因素、未来展望、风险提示、数据来源与口径说明\n2. §5 必须包含 markdown 格式财务数据表格（不是散文）\n3. 每个事实性断言必须标注（来源：具体文件名/日期）\n4. §8 风险必须按严重性分层（高/中/低），每条写传导机制\n5. §9 必须列出具体数据来源文件名和日期\n6. Class A 额外要求：首页关键指标快照、财务摘要表≥7行×≥2年、可比公司表≥3家、Bull/Base/Bear情景分析表\n7. Class B 报告聚焦增量变化，§6是最长章节，§2极简\n8. 审慎风格，多用'判断/预计/关注/需跟踪'，少用强推荐语言\n9. 不输出正式评级和目标价\n\n## 交付步骤（必须执行）\n1. 将完整报告写入 reports/[公司名]_[类型]_[YYYYMMDD].md\n2. 调用 feishu_doc 创建文档：feishu_doc(action=\"create\", title=\"报告标题\") 获得 doc_token，然后 feishu_doc(action=\"write\", doc_token=\"token\", content=\"完整markdown正文\")。两步都必须执行。\n3. 在最终回复中包含飞书文档 URL。\n\n## 输出格式\n完成上述交付步骤后，回复飞书文档 URL 和报告文件路径。", + model: "claude-proxy/claude-sonnet-4-20250514", + thinking: "high", + runTimeoutSeconds: 600 +}) +``` + +**关键**： +- 把全部 Fact Pack 数据完整放入 task 字段。subagent 只能看到你传入的内容，看不到你的对话历史。 +- 交付步骤（写文件 + 飞书文档）必须写在 task 里，因为 spawn 完成后你不会被唤醒来做后续处理。 +- subagent 完成后，你直接把 subagent 返回的飞书文档 URL 转发给用户即可。 + +### Phase 3: 转发结果 +spawn 完成后，将 subagent 返回的飞书文档 URL 直接发送给用户。不需要额外处理。 +如果 subagent 没有返回飞书 URL，检查 reports/ 目录是否有新文件，手动补做飞书交付。 + +--- + +## 详细规则文件（按需读取） + +以下文件包含完整规则。处理报告请求时，至少读取标 ★ 的文件： + +1. ★ `equity-research/docs/company-research-evidence-contract.md` +2. ★ `equity-research/docs/company-research-request-classification.md` +3. ★ `equity-research/docs/company-research-workflow.md` +4. ★ `equity-research/docs/company-research-output-contract.md` +5. ★ `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` +6. `equity-research/docs/company-research-source-hierarchy.md` +7. `equity-research/docs/company-research-degraded-mode.md` +8. `equity-research/docs/company-research-feishu-delivery.md` +9. `equity-research/docs/company-research-compliance-checklist.md` +10. `equity-research/docs/company-research-quality-checklist.md` +11. `equity-research/skills/initiating-coverage/assets/example-report-excerpt.md` +12. Relevant sector KPI checklist under `equity-research/skills/initiating-coverage/references/` + +## Hard rules + +- Default output must not include formal rating or target price unless explicitly requested. +- Official disclosure outranks media summaries. +- If evidence is incomplete, switch to degraded mode. +- A report is not complete until it passes both compliance and quality checklists. +- A report is not complete until a Feishu Doc URL exists for the final user-facing artifact. +- A title-only Feishu Doc does not count as successful delivery. + +## High-value retrieval rule + +When searching, explicitly prioritize newest high-value sources first: +1. latest official company disclosure / exchange announcement +2. latest official IR/results materials / management remarks +3. auditable market data +4. only then secondary news/context + +Internal instruction: `优先检索最新且最有价值的资料。先找公司正式披露、交易所公告、年报/中报/季报、业绩会和官方IR材料；再找可复核市场数据；最后才补充新闻和二手解读。若拿不到最新正式披露期资料，不要把旧资料包装成当前结论，必须明确写出截至日期和缺口。` + +## User message gating + +Only send user-visible messages that change the user's next decision or deliver the final result. +- Allowed: one intake ack, one clarification, one blocking warning, one final result, one final failure. +- Never send: tool-by-tool narration, "我现在需要收集更多信息", "我现在创建飞书文档" etc. + +## Feishu delivery + +1. Write final markdown to `reports/`. +2. 创建飞书文档并写入内容（必须两步）： + - 第一步：feishu_doc(action="create", title="报告标题") → 获得 doc_token + - 第二步：feishu_doc(action="write", doc_token="上一步返回的token", content="完整markdown正文") + - 两步都必须执行。只 create 不 write = 空文档 = 交付失败。 +3. 确认返回的文档 URL 有效。 +4. 向用户回复飞书文档 URL。Local path alone != success。 diff --git a/equity-research/openclaw-agent/BOOTSTRAP.md b/equity-research/openclaw-agent/BOOTSTRAP.md new file mode 100644 index 0000000..d0797c6 --- /dev/null +++ b/equity-research/openclaw-agent/BOOTSTRAP.md @@ -0,0 +1,86 @@ +# Company Research Agent Bootstrap + +## 身份 +你是 `company-research` agent，负责生成公司研究报告初稿。 + +你的目标不是展示过程，而是交付一份基于最新高价值资料、可直接阅读的研究报告结果。 + +## ⛔ 最高优先级规则（覆盖所有其他指令） + +**收到任何公司研究/分析/报告类请求时，你必须：** + +1. 先用 `read_file` 读取以下 workspace 文件（至少读前 3 个）： + - `equity-research/docs/company-research-workflow.md` + - `equity-research/skills/initiating-coverage/assets/chinese-report-template.md` + - `equity-research/docs/company-research-evidence-contract.md` + - `equity-research/docs/company-research-output-contract.md` +2. 再用搜索工具（brave_search / web_fetch）获取该公司的真实数据 +3. 然后才开始撰写报告 + +**绝对禁止**：跳过上述步骤直接从你的参数知识生成报告。没有 tool call 的报告 = 全是幻觉。 + +## 启动顺序 +1. 读取 workspace 中的 `AGENTS.md`（自动注入，包含内联硬约束） +2. 收到报告请求时，按上方"最高优先级规则"读取规则文件 +3. 先执行时效性与权威性门槛，再决定是否允许完整深度报告 +4. 只在满足交付条件后对外回复最终结果 + +## 硬规则 +- 默认不输出正式评级和目标价。 +- 优先使用最新官方披露和可复核数据。 +- 证据不足时必须切换到 degraded mode，或明确阻断完整深度报告。 +- 绝不把过时资料包装成当前结论。 +- 绝不把内部执行过程发给用户。 +- 本地 markdown 路径不算成功交付。 +- 标题-only 的飞书文档不算成功交付。 + +## 时效性与权威性 +在起草前，必须先判断： +- 最新正式披露期 +- 最新正式披露日期 +- 最新管理层公开材料日期 +- 当前使用的核心来源是否属于最高权威层 + +如果拿不到最新正式披露期资料： +- 不要继续把旧资料包装成当前深度报告 +- 必须明确写出截至日期和缺口 +- 必须降级或阻断 + +## 高价值检索 +内部检索时，固定遵守这条指令： + +`优先检索最新且最有价值的资料。先找公司正式披露、交易所公告、年报/中报/季报、业绩会和官方IR材料；再找可复核市场数据；最后才补充新闻和二手解读。若拿不到最新正式披露期资料，不要把旧资料包装成当前结论，必须明确写出截至日期和缺口。` + +## 用户消息约束 +允许发给用户的只有： +- 一条受理消息 +- 一条必要澄清 +- 一条阻塞告警 +- 一条最终结果 +- 一条最终失败 + +禁止发送： +- `我现在需要收集更多信息` +- `让我继续收集` +- `现在让我搜索` +- `我现在创建报告文件` +- `我现在创建飞书文档` +- `我现在写入飞书文档` +- 任何 tool-by-tool 过程播报 + +判断规则： +- 如果这条消息不改变用户下一步决策，也不是最终结果，就不要发。 + +## 交付约束 +成功交付必须满足全部条件： +1. 生成完整 markdown 报告 +2. 优先通过确定性脚本把 markdown 写入飞书文档： + - `python3 scripts/write_report_to_feishu_doc.py --input --title --json` +3. 创建飞书文档 +4. 写入完整正文 +5. 确认飞书文档 URL 已存在 +6. 确认文档不只是标题，正文确实存在 +7. 只有在脚本返回 `ok=true` 且 `verified_block_count > 0` 时，才算交付成功 +8. 最终回复中给出飞书文档 URL + +如果上述任一步未满足，不得宣称"已完成"。 diff --git a/equity-research/openclaw-agent/README.md b/equity-research/openclaw-agent/README.md new file mode 100644 index 0000000..07175e5 --- /dev/null +++ b/equity-research/openclaw-agent/README.md @@ -0,0 +1,41 @@ +# Company Research OpenClaw Agent + +Runtime configuration files for the `company-research` OpenClaw agent. + +## Files + +| File | Purpose | +|------|---------| +| `AGENTS.md` | Main workflow rules, structural requirements, multi-model orchestration | +| `BOOTSTRAP.md` | Agent startup behavior, priority rules, delivery constraints | +| `models.json` | LLM provider configuration (API keys use placeholders) | + +## Deployment + +These files are deployed to the target OpenClaw runtime: + +``` +AGENTS.md → /AGENTS.md +BOOTSTRAP.md → /BOOTSTRAP.md +models.json → /models.json +``` + +## Architecture + +``` +User (Feishu) → OpenClaw Gateway → company-research agent + ├─ Phase 1: Data collection (qwen3-max, web_search) + ├─ Phase 2: Analysis + writing (subagent via sessions_spawn) + └─ Phase 3: Delivery (Feishu Doc creation) +``` + +## API Key Setup + +Replace placeholders in `models.json` before deploying: + +- `${KIMI_API_KEY}` — Moonshot AI API key +- `${VOLCENGINE_API_KEY}` — ByteDance Volcengine API key +- `${CLAUDE_PROXY_BASE_URL}` — Claude API proxy URL +- `${CLAUDE_PROXY_API_KEY}` — Claude API proxy bearer token + +The `dashscope` provider uses `"inherit"` (inherits from OpenClaw global config). diff --git a/equity-research/openclaw-agent/models.json b/equity-research/openclaw-agent/models.json new file mode 100644 index 0000000..7050ede --- /dev/null +++ b/equity-research/openclaw-agent/models.json @@ -0,0 +1,276 @@ +{ + "providers": { + "dashscope": { + "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", + "apiKey": "inherit", + "api": "openai-completions", + "models": [ + { + "id": "qwen3-max-2026-01-23", + "name": "Qwen3-Max (DashScope)", + "reasoning": true, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 128000, + "maxTokens": 32768, + "api": "openai-completions" + } + ] + }, + "kimi-coding": { + "baseUrl": "https://api.kimi.com/coding/", + "api": "anthropic-messages", + "models": [ + { + "id": "k2p5", + "name": "Kimi for Coding", + "reasoning": true, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 262144, + "maxTokens": 32768, + "compat": { + "requiresOpenAiAnthropicToolPayload": true + } + } + ], + "apiKey": "${KIMI_API_KEY}" + }, + "volcengine": { + "baseUrl": "https://ark.cn-beijing.volces.com/api/v3", + "api": "openai-completions", + "models": [ + { + "id": "doubao-seed-code-preview-251028", + "name": "doubao-seed-code-preview-251028", + "reasoning": false, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "doubao-seed-1-8-251228", + "name": "Doubao Seed 1.8", + "reasoning": false, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "kimi-k2-5-260127", + "name": "Kimi K2.5", + "reasoning": false, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "glm-4-7-251222", + "name": "GLM 4.7", + "reasoning": false, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 200000, + "maxTokens": 4096 + }, + { + "id": "deepseek-v3-2-251201", + "name": "DeepSeek V3.2", + "reasoning": false, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 128000, + "maxTokens": 4096 + } + ], + "apiKey": "${VOLCENGINE_API_KEY}" + }, + "volcengine-plan": { + "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3", + "api": "openai-completions", + "models": [ + { + "id": "ark-code-latest", + "name": "Ark Coding Plan", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "doubao-seed-code", + "name": "Doubao Seed Code", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "glm-4.7", + "name": "GLM 4.7 Coding", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 200000, + "maxTokens": 4096 + }, + { + "id": "kimi-k2-thinking", + "name": "Kimi K2 Thinking", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "kimi-k2.5", + "name": "Kimi K2.5 Coding", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + }, + { + "id": "doubao-seed-code-preview-251028", + "name": "Doubao Seed Code Preview", + "reasoning": false, + "input": [ + "text" + ], + "cost": { + "input": 0.0001, + "output": 0.0002, + "cacheRead": 0, + "cacheWrite": 0 + }, + "contextWindow": 256000, + "maxTokens": 4096 + } + ], + "apiKey": "${VOLCENGINE_API_KEY}" + }, + "claude-proxy": { + "baseUrl": "${CLAUDE_PROXY_BASE_URL}", + "api": "anthropic-messages", + "apiKey": "${CLAUDE_PROXY_API_KEY}", + "models": [ + { + "id": "claude-sonnet-4-20250514", + "name": "Claude Sonnet 4 (Proxy)", + "reasoning": true, + "input": [ + "text", + "image" + ], + "cost": { + "input": 0.003, + "output": 0.015, + "cacheRead": 0.0003, + "cacheWrite": 0.00375 + }, + "contextWindow": 200000, + "maxTokens": 16384, + "api": "anthropic-messages" + } + ] + } + } +} diff --git a/equity-research/scripts/write_report_to_feishu_doc.py b/equity-research/scripts/write_report_to_feishu_doc.py new file mode 100644 index 0000000..806b236 --- /dev/null +++ b/equity-research/scripts/write_report_to_feishu_doc.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +import argparse +import json +import os +import sys +import urllib.request +from pathlib import Path + + +def _load_default_feishu_credentials() -> tuple[str, str]: + env_path = os.getenv("OPENCLAW_CONFIG_PATH", "").strip() + candidates = [] + if env_path: + candidates.append(Path(env_path)) + candidates.append(Path.home() / ".openclaw" / "openclaw.json") + for path in candidates: + if not path.exists(): + continue + try: + obj = json.loads(path.read_text(encoding="utf-8")) + feishu = (((obj.get("channels") or {}).get("feishu") or {})) + default_account = feishu.get("defaultAccount") or "default" + account = (((feishu.get("accounts") or {}).get(default_account) or {})) + app_id = str(account.get("appId") or "").strip() + app_secret = str(account.get("appSecret") or "").strip() + if app_id and app_secret: + return app_id, app_secret + except Exception: + continue + return "", "" + + +def _post_json(url: str, payload: dict, headers: dict[str, str] | None = None) -> dict: + body = json.dumps(payload).encode("utf-8") + req = urllib.request.Request(url, data=body, method="POST") + req.add_header("Content-Type", "application/json") + for k, v in (headers or {}).items(): + req.add_header(k, v) + with urllib.request.urlopen(req, timeout=60) as resp: + return json.loads(resp.read().decode("utf-8")) + + +def _get_json(url: str, headers: dict[str, str] | None = None) -> dict: + req = urllib.request.Request(url, method="GET") + for k, v in (headers or {}).items(): + req.add_header(k, v) + with urllib.request.urlopen(req, timeout=60) as resp: + return json.loads(resp.read().decode("utf-8")) + + +def _tenant_token(app_id: str, app_secret: str) -> str: + obj = _post_json( + "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", + {"app_id": app_id, "app_secret": app_secret}, + ) + token = obj.get("tenant_access_token", "") + if obj.get("code") != 0 or not token: + raise RuntimeError(f"tenant_token_failed: {obj}") + return token + + +def _create_doc(title: str, token: str) -> str: + obj = _post_json( + "https://open.feishu.cn/open-apis/docx/v1/documents", + {"title": title}, + {"Authorization": f"Bearer {token}"}, + ) + data = obj.get("data") or {} + doc = data.get("document") or {} + doc_id = doc.get("document_id") or data.get("document_id") or "" + if obj.get("code") != 0 or not doc_id: + raise RuntimeError(f"create_doc_failed: {obj}") + return str(doc_id) + + +def _line_to_block(line: str) -> dict: + text = line.strip() + if text.startswith("# "): + return { + "block_type": 3, + "heading1": {"elements": [{"text_run": {"content": text[2:].strip()[:2000]}}]}, + } + if text.startswith("## "): + return { + "block_type": 4, + "heading2": {"elements": [{"text_run": {"content": text[3:].strip()[:2000]}}]}, + } + return { + "block_type": 2, + "text": {"elements": [{"text_run": {"content": text[:2000]}}]}, + } + + +def _append_markdown(doc_id: str, markdown_text: str, token: str) -> None: + lines = [line.rstrip() for line in markdown_text.splitlines()] + lines = [line for line in lines if line.strip()] + if not lines: + raise RuntimeError("append_markdown_failed: no_content") + url = f"https://open.feishu.cn/open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children" + headers = {"Authorization": f"Bearer {token}"} + for i in range(0, len(lines), 50): + blocks = [_line_to_block(line) for line in lines[i : i + 50]] + obj = _post_json(url, {"children": blocks, "index": -1}, headers) + if obj.get("code") != 0: + raise RuntimeError(f"append_blocks_failed: {obj}") + + +def _verify_body(doc_id: str, token: str) -> int: + url = f"https://open.feishu.cn/open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children?page_size=20" + obj = _get_json(url, {"Authorization": f"Bearer {token}"}) + items = ((obj.get("data") or {}).get("items") or []) + if obj.get("code") != 0: + raise RuntimeError(f"verify_doc_failed: {obj}") + if not items: + raise RuntimeError("verify_doc_failed: title_only_or_empty") + return len(items) + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--input", required=True) + parser.add_argument("--title", required=True) + parser.add_argument("--app-id", default=os.getenv("FEISHU_APP_ID", "")) + parser.add_argument("--app-secret", default=os.getenv("FEISHU_APP_SECRET", "")) + parser.add_argument("--json", action="store_true") + args = parser.parse_args() + + if not args.app_id or not args.app_secret: + app_id, app_secret = _load_default_feishu_credentials() + args.app_id = args.app_id or app_id + args.app_secret = args.app_secret or app_secret + + if not args.app_id or not args.app_secret: + raise RuntimeError("missing_feishu_credentials") + + markdown = Path(args.input).read_text(encoding="utf-8") + token = _tenant_token(args.app_id, args.app_secret) + doc_id = _create_doc(args.title, token) + _append_markdown(doc_id, markdown, token) + block_count = _verify_body(doc_id, token) + + result = { + "ok": True, + "document_id": doc_id, + "document_url": f"https://feishu.cn/docx/{doc_id}", + "verified_block_count": block_count, + "input_path": args.input, + } + if args.json: + print(json.dumps(result, ensure_ascii=False)) + else: + print(result["document_url"]) + return 0 + + +if __name__ == "__main__": + try: + raise SystemExit(main()) + except Exception as exc: + print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False)) + raise diff --git a/equity-research/skills/initiating-coverage/assets/chinese-report-template.md b/equity-research/skills/initiating-coverage/assets/chinese-report-template.md new file mode 100644 index 0000000..fbc74b5 --- /dev/null +++ b/equity-research/skills/initiating-coverage/assets/chinese-report-template.md @@ -0,0 +1,415 @@ +# 中文公司研究报告模板 v2.0 + +本模板用于公司研究报告初稿。默认适用于： + +- 首次覆盖（Class A） +- 公司更新 / 财报点评（Class B） +- 一般公司分析（Class C） + +## 设计来源 + +本模板融合以下公开可见的机构级报告结构： + +- Goldman Sachs 风格前页（结论先行 + 关键指标快照 + 估值摘要） +- CICC / 中资卖方风格正文（投资论点 → 公司概览 → 行业 → 业务 → 财务 → 估值 → 风险） +- 基金内部研究 checklist（商业模式 / 市场空间 / 竞争位置 / 增长驱动 / 治理 / 反证） +- Day1Global 16 模块分析深度标准（每个模块有明确必答子问题） + +## 风格约束 + +- 审慎表达，证据优先，先事实后判断 +- 默认不输出正式评级和目标价（除非用户明确要求） +- 基于长盛基金公开披露风格：多用"判断 / 预计 / 关注 / 需跟踪"，少用强推荐语言 +- **每个事实性断言必须行内引用来源**（格式见下方引用规范） + +## 行内引用规范（全文强制） + +正文中每个财务数字、关键事实、管理层表态必须在行内标注来源： + +``` +（来源：公司2024年年报 p.XX） +（来源：SEC 10-K, 2025-02-18） +（来源：2024Q4业绩会纪要） +（来源：招股说明书，2025-01） +（来源：深交所公告，2026-03-01） +``` + +§9 数据来源与口径说明是全文引用的**汇总索引 + 口径差异说明**，不是唯一引用位置。 + +**格式示范**：参见 `assets/example-report-excerpt.md`，包含首页摘要、财务表格、可比公司表、情景分析表、风险矩阵、行内引用的完整示范。 + +--- + +## 首页摘要（最后写，但放在最前面） + +首页摘要是报告最重要的一页，采用 Goldman 风格"结论先行"格式。 + +### 必须包含 + +1. **观点倾向**（1 句话）：当前判断的方向和信心水平（审慎表达，非正式评级） +2. **3-5 条核心结论**：每条以**粗体要点标题**开头，后跟 2-3 句支撑说明 +3. **关键财务指标快照表**（必填）： + +``` + FY-2(A) FY-1(A) FY(A/E) FY+1(E) +营收 (亿元/美元) [X] [X] [X] [X] +营收 YoY% X% X% X% X% +毛利率 X% X% X% X% +净利润 [X] [X] [X] [X] +净利率 X% X% X% X% +[核心估值倍数] Xx Xx Xx Xx + +注：A = 实际，E = 预测。预测列仅在有明确依据时填写。 +来源：[具体来源] +``` + +4. **Bull/Base/Bear 一行摘要**：三个情景的隐含估值/市值或关键假设差异 +5. **最大风险一句话**：当前最可能导致结论失败的单一因素 +6. **关键不确定性**：1-2 个需要后续数据验证的变量 + +### 风格约束 + +- 先给结论 → 再给证据 → 再提示不确定性 +- 推荐表达：`我们当前判断` / `从现有公开信息看` / `需继续跟踪` / `若后续数据验证` +- 避免表达：`强烈推荐` / `确定受益` / `必然增长` / `显著低估`（除非有充分估值证据） +- 不要上来直接给强推荐口号 +- 默认不输出目标价 + +--- + +## 1. 核心结论 + +### 必须产出 + +- 本次报告的核心判断方向（1 句话） +- 当前最值得关注的 **3-5 个结论**，每条附核心证据（含行内引用） +- **Key Forces 识别**：未来 3-5 年会根本性改变这家公司价值的 1-3 个决定性力量 + - 可能是：技术范式转移、监管政策、管理层战略转向、竞争格局根本性改变、市场严重误解 +- 结论成立的核心前提假设（显式列出） +- 需要继续验证的关键变量（每个附验证时间窗口） + +### 反模式警告 + +如果核心结论读起来像一份"什么都涉及但什么都不深入"的清单，说明 Key Forces 没找准。与 Key Forces 直接相关的后续章节应获得 2-3 倍篇幅。 + +--- + +## 2. 公司基本面概览 + +### 必须产出 + +- **公司身份摘要**：法律名称、上市地/股票代码（如有）、成立时间、总部、员工规模 +- **商业模式描述**：如何赚钱（用外行人能理解的语言） +- **收入构成拆解**（必须结构化）： + +| 业务线/产品 | FY-1 收入 | 占比 | YoY% | 来源 | +|-----------|---------|------|------|------| +| [业务A] | | | | | +| [业务B] | | | | | +| 合计 | | 100% | | | + +- **地理收入分布**（如可得）：按区域拆分收入占比 +- 发展阶段与规模定位 +- 主要客户群体和客户集中度（前 5/10 大客户占比，如可得） +- **管理层关键信息**：CEO/CFO 背景（1-2 句）、任期、核心管理层稳定性 +- 股权结构（如可得）：主要股东、投票权结构（是否双层股权） + +--- + +## 3. 行业与市场环境 + +### 必须产出 + +- 所处行业定义与产业链位置 +- **行业规模与增速**（必须有数据）： + +| 维度 | 数值 | 来源 | +|------|------|------| +| 当前市场规模 (TAM) | | | +| 预计 CAGR (3-5年) | | | +| 公司市场份额 | | | +| 可触达市场 (SAM) | | | + +- 行业景气度与周期阶段判断 +- 政策、监管或宏观环境对行业的影响 +- 行业内主要驱动因素和约束因素 +- **竞争格局概览**：行业集中度（一家独大 / 寡头 / 分散）、前 3-5 名竞争对手及市场份额 + +### TAM 警告 + +如果公司或分析师声称的 TAM 极大（千亿/万亿级），必须区分 TAM 和实际可触达的 SAM。写出从 TAM 到 SAM 的缩减逻辑。 + +--- + +## 4. 业务与竞争力分析 + +### 必须产出 + +- **核心业务拆解**：每条主要业务线的产品/服务定位、目标客户、定价模式 +- **竞争对手对比表**（必填）： + +| 维度 | 本公司 | 竞争对手A | 竞争对手B | 竞争对手C | 来源 | +|------|--------|----------|----------|----------|------| +| 收入规模 | | | | | | +| 增速 | | | | | | +| 市场份额 | | | | | | +| 毛利率 | | | | | | +| 核心差异化 | | | | | | + +- **护城河评估**：品牌 / 网络效应 / 成本优势 / 转换成本 / 技术壁垒——哪些在变宽、哪些在被侵蚀 +- 护城河的可量化证据（客户留存率、定价权、竞品切换成本） +- 脆弱点：最可能被攻破的竞争维度 + +### 按行业类型补充 + +- **SaaS/云**：NDR（净留存率）、ARR 增速、RPO +- **消费互联网**：DAU/MAU、ARPU、用户参与时长 +- **AI 平台**：API 调用量、模型性能基准、训练/推理成本趋势 +- **半导体/硬件**：Backlog、Book-to-Bill、库存天数、ASP +- **消费品**：门店数/渠道数、同店增长、SKU 数、复购率 + +--- + +## 5. 财务与关键指标分析 + +### 5.1 核心财务摘要表（必填） + +``` +指标 FY-2(A) FY-1(A) FY(A/E) FY+1(E) 来源 +营收 (亿元/美元) [X] [X] [X] [X] [来源] +营收 YoY% X% X% X% X% +毛利润 [X] [X] [X] [X] +毛利率 X% X% X% X% +营业利润 [X] [X] [X] [X] +营业利润率 X% X% X% X% +净利润 [X] [X] [X] [X] +净利率 X% X% X% X% +经营现金流 (OCF) [X] [X] [X] [X] +自由现金流 (FCF) [X] [X] [X] [X] +FCF Margin X% X% X% X% +[行业核心 KPI 1] [X] [X] [X] [X] +[行业核心 KPI 2] [X] [X] [X] [X] + +注：A = 实际，E = 预测。预测列仅在有明确依据时填写，否则标注"无可靠依据"。 +空格填 N/A 并在 §9 口径说明中解释缺失原因。 +``` + +### 5.2 财务趋势分析（必填） + +至少分析以下三个维度的变化方向和驱动因素： + +1. **收入增速趋势**：加速 / 稳定 / 减速？驱动因素是什么？ +2. **利润率趋势**：毛利率、营业利润率、净利率的变化方向及原因 +3. **现金流质量**：OCF vs 净利润的关系（是否长期背离？）、FCF 趋势 + +每个关键数字必须行内引用来源。 + +### 5.3 运营 KPI 分析（按行业必填） + +引用对应行业的 sector-kpis 文件，至少给出 **2-3 个核心运营 KPI 的历史数据和趋势**。 + +| KPI | FY-2 | FY-1 | 最新期 | 趋势方向 | 来源 | +|-----|------|------|--------|---------|------| +| [KPI 1] | | | | 改善/持平/恶化 | | +| [KPI 2] | | | | | | +| [KPI 3] | | | | | | + +### 5.4 财务质量信号（推荐） + +- GAAP vs Non-GAAP 利润差异（差距 >50% 需深挖） +- SBC 占收入比例（科技公司 >15-20% 需标注） +- 应收账款增速 vs 收入增速（前者显著高于后者为红旗） +- 经营现金流 vs 净利润（长期背离为红旗） + +--- + +## 6. 当前变化与驱动因素 + +### 必须产出 + +- 最近一期财报、公告或重大事件的关键数据和影响 +- **Beat/Miss 分析**（如适用）： + +| 维度 | 实际 | 共识预期 | Beat/Miss | 来源 | +|------|------|---------|-----------|------| +| 营收 | | | | | +| 利润 | | | | | +| [关键 KPI] | | | | | + +- 近期经营变化的驱动因素 +- **当前市场分歧点**：市场共识是什么？分歧在哪里？ +- 管理层近期指引和表态的语气变化（与上一期对比） +- 未来 1-4 个季度需跟踪的关键变量清单 + +--- + +## 7. 未来展望与估值框架 + +### 7.1 中短期展望（必填） + +- 中短期经营判断（1-2 年） +- 关键增长驱动因素 +- 主要不确定性 + +### 7.2 可比公司分析（首次覆盖必填 / 更新报告推荐） + +**可比公司表**（至少 3 家）： + +``` +公司 市值 EV/Revenue EV/EBITDA P/E 增速 来源 +[标的公司] [X] [X]x [X]x [X]x X% +[可比1] [X] [X]x [X]x [X]x X% +[可比2] [X] [X]x [X]x [X]x X% +[可比3] [X] [X]x [X]x [X]x X% +行业中位数 — [X]x [X]x [X]x X% + +来源：[具体来源及日期] +``` + +必须说明： +- **可比选择理由**：为什么选这几家（业务模式 / 规模 / 增速相近） +- **溢价/折价判断**：标的相对可比组应该有什么样的溢价或折价？为什么？ + +### 7.3 估值方法（首次覆盖推荐 / 数据不足时可降级） + +根据公司特征选择 **至少 2 种**估值方法： + +| 公司特征 | 首选方法 | 辅助方法 | +|---------|---------|---------| +| 已盈利、成熟型 | EV/EBITDA、PE | DCF（简化） | +| 高增长、已盈利 | PEG、反向 DCF | EV/EBITDA | +| 高增长、未盈利 | EV/Revenue + Rule of 40 | 反向 DCF | + +**关键假设表**（必填，如进行估值）： + +| 假设 | Base | Bull | Bear | 依据 | +|------|------|------|------|------| +| 收入增速 | X% | X% | X% | [依据] | +| 利润率路径 | X% | X% | X% | [依据] | +| 估值倍数 | Xx | Xx | Xx | [依据] | + +**敏感性分析**（推荐，至少 2×2 矩阵）： + +| [关键变量A] \ [关键变量B] | 低 | 中 | 高 | +|--------------------------|-----|-----|-----| +| 低 | [估值] | [估值] | [估值] | +| 中 | [估值] | [估值] | [估值] | +| 高 | [估值] | [估值] | [估值] | + +### 7.4 情景分析（必填） + +| 情景 | 概率权重 | 核心假设 | 隐含估值/市值 | +|------|---------|---------|-------------| +| Bull（乐观） | XX% | [1-2句：什么条件下实现] | [X] | +| Base（基准） | XX% | [1-2句：最可能的路径] | [X] | +| Bear（悲观） | XX% | [1-2句：什么条件下发生] | [X] | + +**数据不足时的降级处理**： +- 如果无法获取可比公司数据：写"当前无法建立可比框架，原因：[具体说明]" +- 如果财务数据不足以支撑定量估值：写"当前证据不足以给出估值区间，缺少：[具体数据]，什么条件下可以给估值：[说明]" +- **绝不跳过估值章节**——即使降级，也要保留章节并说明原因 + +--- + +## 8. 风险提示 + +### 8.1 风险矩阵（必填） + +按"影响程度 × 发生概率"分三档，每个风险写一句传导机制： + +| 风险项 | 类别 | 严重性 | 概率 | 传导机制 | +|--------|------|--------|------|---------| +| [风险1] | 公司/行业/财务/外部 | 高/中/低 | 高/中/低 | [一句话：如何影响公司价值] | +| [风险2] | | | | | +| [风险3] | | | | | +| ... | | | | | + +风险类别至少覆盖： +- **公司层面**：管理层、执行力、客户集中度、产品竞争力 +- **行业层面**：竞争加剧、技术替代、需求变化 +- **财务层面**：现金流、负债、融资依赖 +- **外部环境**：政策监管、宏观经济、地缘政治 + +### 8.2 反证与下行风险（必填） + +- 至少 **1 条**与核心结论相反的反证线索 +- 如果核心结论偏乐观，必须写出最可能导致结论失败的具体场景 +- **Pre-Mortem 问题**：假设 2 年后这笔投资亏了大钱，最可能的失败路径是什么？ + +### 8.3 监控触发条件（推荐） + +| 信号 | 动作建议 | 理由 | +|------|---------|------| +| 如果 [具体可量化的正面条件] | 上调判断 | | +| 如果 [具体可量化的负面条件] | 下调判断 | | +| 如果 [具体可量化的严重负面条件] | 重新评估整体结论 | | + +**关键要求**：每个触发条件必须是具体、可量化、可验证的。"如果增长放缓"不及格，"如果连续 2 个季度收入增速低于 15%"才及格。 + +--- + +## 9. 数据来源与口径说明 + +### 必须产出 + +本节是全文引用的汇总索引，不是唯一引用位置。 + +- **主要来源清单**（具体到文件名和日期）： + +| # | 来源类型 | 来源名称 | 日期 | 用途 | +|---|---------|---------|------|------| +| 1 | 官方披露 | [公司2024年年报] | [日期] | 财务数据、业务描述 | +| 2 | 监管文件 | [SEC 10-K] | [日期] | 风险因素、财务明细 | +| 3 | 管理层沟通 | [2024Q4业绩会] | [日期] | 管理层指引、战略表态 | +| ... | | | | | + +- **口径说明**： + - 货币单位和汇率假设 + - 财务数据的会计准则（GAAP/IFRS） + - 预测数据的假设基础 + - 可比公司数据的截取日期 + +- **数据缺失说明**：哪些数据无法获取，为什么，对结论的影响 + +- **免责声明**：本报告基于公开可获得的信息编制，不构成投资建议。 + +--- + +## 章节必填 / 选填矩阵 + +| 章节 | 首次覆盖(A) | 更新报告(B) | 一般分析(C) | +|------|-----------|-----------|-----------| +| 首页摘要 | 必填 | 必填 | 必填 | +| §1 核心结论 | 必填 | 必填 | 必填 | +| §2 公司概览（含收入拆解表） | 必填 | 简化 | 必填 | +| §3 行业环境（含 TAM 表） | 必填 | 简化 | 必填 | +| §4 竞争力（含竞争对手对比表） | 必填 | 按需 | 必填 | +| §5 财务（含摘要表 + KPI 表） | 必填 | 必填（聚焦最新期） | 必填 | +| §6 当前变化 | 必填 | 必填（核心章节） | 按需 | +| §7.1 展望 | 必填 | 必填 | 必填 | +| §7.2 可比公司表 | 必填 | 推荐 | 推荐 | +| §7.3 估值方法 | 推荐 | 按需 | 按需 | +| §7.4 情景分析 | 必填 | 必填 | 必填 | +| §8.1 风险矩阵 | 必填 | 必填 | 必填 | +| §8.2 反证 | 必填 | 必填 | 必填 | +| §8.3 监控触发 | 推荐 | 推荐 | 按需 | +| §9 数据来源 | 必填 | 必填 | 必填 | + +--- + +## 写作纪律 + +1. **开头直接给结论**，不要"本报告旨在分析..." +2. **80% 以上主动语态** +3. **标题是判断不是名词堆砌**：用"收入增速放缓至 15%，结构性拐点初现"而非"收入分析" +4. **Lead with numbers**："营收同比增长 78% 至 3050 万美元"而非"公司实现了较好的营收增长" +5. **与 Key Forces 直接相关的章节给 2-3 倍篇幅**，其余正常覆盖 +6. **每个表格必须有来源行** +7. **不确定时诚实标注**，不要把不充分的证据包装成确定性结论 +8. **结尾是风险和监控清单**，不是拖沓的总结 + +## 示范报告片段参考 + +如需查看关键结构（财务摘要表、可比公司表、情景分析表、风险矩阵、行内引用）的正确格式示范，请参考： +- `assets/example-report-excerpt.md` +- 英文版参考：`assets/report-template.md` diff --git a/equity-research/skills/initiating-coverage/assets/example-report-excerpt.md b/equity-research/skills/initiating-coverage/assets/example-report-excerpt.md new file mode 100644 index 0000000..4a03375 --- /dev/null +++ b/equity-research/skills/initiating-coverage/assets/example-report-excerpt.md @@ -0,0 +1,104 @@ +# Few-shot 示范报告片段 + +本文件提供关键报告结构的正确格式示范。用于引导 LLM 生成符合模板要求的结构化输出。 + +**注意**：以下示例使用虚构公司"星辰科技"（StarTech Inc.），所有数据为演示用途，不构成任何投资建议。 + +--- + +## 示范 1: 首页摘要 + +**观点倾向**：审慎看好，关注商业化验证节点。 + +| 指标 | 最新值 | 同比变化 | 来源 | +|------|--------|---------|------| +| 营收（FY2025） | 28.3 亿元 | +62% | 公司年报 | +| 毛利率 | 41.2% | +3.5pp | 公司年报 | +| 净亏损 | -4.7 亿元 | 收窄 38% | 公司年报 | +| 经营现金流 | -1.2 亿元 | 收窄 55% | 公司年报 | +| EV/Revenue（TTM） | 8.2x | — | Wind | + +**核心结论**： + +1. **收入增长强劲但依赖单一客户**：FY2025 营收同比增长 62%，但前三大客户贡献 67% 收入（来源：公司年报 p.45），客户集中度风险需持续关注。 +2. **毛利率改善反映规模效应**：毛利率从 37.7% 提升至 41.2%（来源：公司年报 p.23），主要受益于推理成本下降和高毛利 SaaS 收入占比提升。 +3. **现金流转正路径渐清晰**：经营现金流亏损收窄 55%（来源：公司年报 p.31），管理层预计 FY2026H2 实现经营现金流转正（来源：2025Q4 业绩会纪要）。 + +**情景一行摘要**：Bull 50亿市值（高端客户快速拓展） / Base 35亿（维持当前增速） / Bear 18亿（大客户流失+融资困难） + +**最大风险**：前三大客户贡献 67% 收入，任一大客户流失将直接导致收入断崖式下降。 + +--- + +## 示范 2: 核心财务摘要表 (§5.1) + +| 指标 | FY2023 | FY2024 | FY2025 | FY2026E | 来源 | +|------|--------|--------|--------|---------|------| +| 营业收入（亿元） | 10.8 | 17.5 | 28.3 | 42.0E | 公司年报; FY2026E 为管理层指引 | +| 营收 YoY% | +85% | +62% | +62% | +48%E | 计算 | +| 毛利率 | 34.5% | 37.7% | 41.2% | 43.0%E | 公司年报; FY2026E 为管理层指引区间中值 | +| 净利润（亿元） | -12.1 | -7.6 | -4.7 | -1.5E | 公司年报; FY2026E 为卖方一致预期 | +| 净利率 | -112% | -43% | -17% | -4%E | 计算 | +| 经营现金流（亿元） | -5.8 | -2.7 | -1.2 | +0.8E | 公司年报; FY2026E 为管理层指引 | +| 自由现金流（亿元） | -8.3 | -4.9 | -2.8 | N/A | 公司年报; FY2026E 无可靠估算 | + +> 口径说明：营收为合并口径，含 SaaS 订阅 + API 调用 + 定制开发三项。FY2026E 预测列基于管理层公开指引和卖方一致预期，非本报告独立预测。 + +--- + +## 示范 3: 可比公司表 (§7.5.1) + +**可比选择逻辑**：选择同为 AI 平台/应用层公司，业务模式含 API + SaaS，所处增长阶段相近（高增长、未盈利或微利），市值量级可比。 + +| 公司 | 市值（亿元） | EV/Revenue | EV/EBITDA | P/S | 营收增速 | 来源 | +|------|-------------|-----------|-----------|-----|---------|------| +| 智谱 AI | 180 | 12.5x | N/A（亏损） | 12.0x | +80% | Wind, 2025-12 | +| 百川智能 | 120 | 9.8x | N/A（亏损） | 9.5x | +55% | 公司公告, 2025-11 | +| 月之暗面 | 200 | 15.2x | N/A（亏损） | 14.8x | +110% | 36氪融资报道, 2025-09 | +| **中位数** | **180** | **12.5x** | **N/A** | **12.0x** | **80%** | — | +| **星辰科技** | **130** | **8.2x** | **N/A** | **8.0x** | **62%** | — | + +**溢价/折价分析**：星辰科技 EV/Revenue 8.2x，较可比中位数 12.5x 折价 34%。折价原因判断：(1) 客户集中度高于同业（来源：公司年报 p.45）；(2) 尚未证明 SaaS 续约率（来源：管理层 IR 沟通）。若客户拓展取得突破，折价有望收窄。 + +--- + +## 示范 4: Bull/Base/Bear 情景分析表 (§7.5.3) + +| 维度 | Bull（乐观） | Base（基准） | Bear（悲观） | +|------|-------------|-------------|-------------| +| 概率权重 | 25% | 50% | 25% | +| 核心假设 | FY2026 营收增速 60%+，新签 3+ 大客户，SaaS 续约率 >90% | 维持当前增速 45-50%，客户结构小幅改善 | 大客户缩减预算，新客户拓展不及预期，融资环境恶化 | +| 隐含市值区间 | 45-55 亿元 | 30-38 亿元 | 15-20 亿元 | +| 关键验证节点 | FY2026Q1 新客户签约数据 | FY2026H1 营收和续约率 | FY2026Q1 大客户续约情况 | + +> 本情景分析基于可比估值法推导，非精确 DCF 模型输出。概率权重为主观判断，仅供参考框架。 + +--- + +## 示范 5: 风险矩阵 (§8.1) + +| 风险项 | 类别 | 严重性 | 概率 | 传导机制 | +|--------|------|--------|------|---------| +| 前三大客户贡献 67% 收入 | 经营 | 高 | 中 | 任一大客户流失 → 收入缺口 >20% → 现金流转正推迟 → 融资压力加大 | +| AI 行业竞争加剧导致定价下行 | 行业 | 高 | 高 | 模型能力趋同 → API 定价战 → 毛利率回落 → 盈利预期下修 | +| 监管政策收紧（数据安全/AI 治理） | 政策 | 中 | 中 | 合规成本上升 + 部分场景受限 → 增速放缓 | +| 关键技术人才流失 | 经营 | 中 | 低 | 核心研发团队稳定性 → 模型迭代速度 → 产品竞争力 | +| 宏观经济下行抑制企业 IT 支出 | 宏观 | 低 | 中 | 客户预算缩减 → 新签放缓 + 续约率承压 | + +### 反证与下行风险 + +与核心结论"审慎看好"相反的最强反证：**公司尚未证明 SaaS 模式的续约能力**。当前 SaaS 合同大多为首年，FY2026 将迎来首批大规模续约窗口。若续约率低于 70%，收入增长模型将从"复合增长"退化为"重复获客"，估值逻辑需要根本性重估（来源：管理层 IR 沟通，2025-12）。 + +--- + +## 示范 6: 行内引用用法 + +**正确用法（贯穿正文）**： + +> 公司 FY2025 营收达到 28.3 亿元，同比增长 62%（来源：公司2025年年报 p.12）。其中 SaaS 订阅收入占比从 31% 提升至 42%（来源：公司2025年年报 p.18），反映商业模式向高毛利方向转型。管理层在业绩会上表示"预计 FY2026 下半年实现经营现金流转正"（来源：2025Q4业绩会纪要，2026-02-15）。 + +**错误用法（避免）**： + +> ~~公司营收快速增长，毛利率持续提升，现金流也在改善。~~（无任何来源引用） + +> ~~根据公开资料，公司表现良好。~~（"公开资料"不是有效来源标注） diff --git a/equity-research/skills/initiating-coverage/references/sector-kpis-ai-platform.md b/equity-research/skills/initiating-coverage/references/sector-kpis-ai-platform.md new file mode 100644 index 0000000..56a8178 --- /dev/null +++ b/equity-research/skills/initiating-coverage/references/sector-kpis-ai-platform.md @@ -0,0 +1,47 @@ +# AI Platform Sector KPI Checklist + +Use this checklist when the covered company is primarily an AI platform, foundation model provider, or AI application company. + +## Must-Cover Business Questions + +- revenue model: API usage-based, SaaS subscription, licensing, hybrid +- customer type: enterprise, developer, consumer +- model strategy: proprietary, open-source, hybrid +- deployment model: cloud API, on-premise, edge +- competitive moat: data, model capability, distribution, ecosystem + +## Must-Cover KPIs + +- MAU / DAU and growth trend +- ARPU (average revenue per user/customer) +- user retention rate (D1 / D7 / D30) if consumer-facing +- API call volume and revenue +- training cost per model generation +- inference cost trend (per million tokens or equivalent) +- model benchmark performance (MMLU, HumanEval, MT-Bench, or domain-specific) +- cash burn rate (monthly/quarterly) +- cash runway (months remaining at current burn) +- gross margin (distinguish compute vs. total) +- revenue growth rate +- customer count and growth +- net revenue retention (if enterprise SaaS component) + +## Quality Questions + +- is growth driven by genuine adoption or promotional pricing +- are inference costs declining through optimization or just scale +- is the model capability gap vs. competitors widening or narrowing +- how sticky is the user base (switching costs, ecosystem lock-in) +- is revenue quality improving (recurring vs. one-time, enterprise vs. consumer) +- what percentage of revenue comes from the top 3 customers + +## Risk Questions + +- model commoditization: open-source alternatives eroding pricing power +- compute dependency: GPU supply constraints or cost volatility +- regulatory risk: data privacy, AI governance, content liability +- talent concentration: key researcher dependency +- funding risk: burn rate vs. remaining runway vs. market conditions +- customer concentration: single-client revenue dependency +- technology disruption: architectural shifts making current models obsolete +- geopolitical risk: chip export controls, cross-border data restrictions diff --git a/equity-research/skills/initiating-coverage/references/sector-kpis-consumer.md b/equity-research/skills/initiating-coverage/references/sector-kpis-consumer.md new file mode 100644 index 0000000..c698c25 --- /dev/null +++ b/equity-research/skills/initiating-coverage/references/sector-kpis-consumer.md @@ -0,0 +1,37 @@ +# Consumer Sector KPI Checklist + +Use this checklist when the covered company is primarily a consumer brand, retail, or consumer platform business. + +## Must-Cover Business Questions + +- brand positioning and target customer +- channel structure: online, offline, distributor, direct +- category growth and substitution risk +- pricing power and promotional intensity +- supply chain stability + +## Must-Cover KPIs + +- revenue growth +- same-store sales or equivalent channel trend if relevant +- gross margin +- operating margin +- inventory turnover or inventory pressure signals +- channel mix +- average selling price trend if relevant +- cash conversion + +## Quality Questions + +- is growth volume-driven or price-driven +- is margin supported by sustainable brand power +- are channels healthy or dependent on promotions +- is demand concentrated in one category or region + +## Risk Questions + +- weak consumer demand +- price war or promotion pressure +- inventory buildup +- channel conflict +- raw material or supply chain volatility diff --git a/equity-research/skills/initiating-coverage/references/sector-kpis-saas.md b/equity-research/skills/initiating-coverage/references/sector-kpis-saas.md new file mode 100644 index 0000000..5c9f41d --- /dev/null +++ b/equity-research/skills/initiating-coverage/references/sector-kpis-saas.md @@ -0,0 +1,37 @@ +# SaaS Sector KPI Checklist + +Use this checklist when the covered company is primarily a software or SaaS business. + +## Must-Cover Business Questions + +- revenue model: subscription, usage-based, hybrid +- customer type: enterprise, mid-market, SMB +- sales motion: direct, channel, PLG, hybrid +- renewal and expansion quality +- product breadth and integration depth + +## Must-Cover KPIs + +- ARR or recurring revenue base +- revenue growth +- gross margin +- net revenue retention +- customer acquisition efficiency +- payback period if available +- free cash flow trend +- operating leverage trend + +## Quality Questions + +- is growth driven by healthy expansion or discounting +- are margins improving through scale or temporary cuts +- how durable is retention +- how concentrated is the customer base + +## Risk Questions + +- competitive pricing pressure +- demand slowdown in enterprise software budgets +- customer concentration +- elevated sales and marketing burden +- weak cash conversion relative to reported growth