大愚 Agent 是面向买方财报分析的通用 Agent。当前可用的用户入口集中在
dayu-cli：可以初始化工作区、下载或上传财报、预处理文档、进行单次问答、
多轮交互，以及查看和清理 CLI Session。
本文档面向最终使用者。
- 本文档是最终用户使用手册，只写用户完成安装、初始化、配置、财报下载 / 上传 / 预处理、提问、交互式分析、Session 管理、查看日志与排障所需的当前可用操作。
- 更新本文档时必须先核对当前 CLI / Web / WeChat 入口、参数解析、用户可见输出和对应实现；代码真源高于设计文档和历史说明。
- 本文档可以写面向用户的命令、参数、工作区文件位置、输出文件位置、日志定位方式、常见错误和排障步骤。
- 不写 Host / Engine / Service / Runtime / Fins 内部架构、公共契约细节、状态机、测试清单、代码阅读顺序、review / work unit 过程状态或开发者迁移计划。
- 不写未来计划、未落地能力或内部治理术语；若必须提到尚未实现的用户入口，只能作为用户可见限制简短说明。
- 涉及开发者架构、包边界或代码阅读路径时，链接到
dayu/README.md或对应子包 README，不在本文档展开。
开发文档入口：
项目默认和依赖锁定环境是 Python 3.11。Docling 模型栈统一约束为
transformers>=4.57.6,<5.0.0；不要在受控约束上另行升级到 Transformers 5.x，
否则使用 torch 2.2.x 的 macOS Intel 环境无法运行 Docling。
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[test,dev,browser]" \
-c constraints/lock-macos-arm64-py311.txt按平台替换约束文件：
- macOS Intel：
constraints/lock-macos-x64-py311.txt - Linux x64：
constraints/lock-linux-x64-py311.txt - Windows x64：
constraints/lock-windows-x64-py311.txt
如果需要浏览器回退抓取，再安装 Chromium：
playwright install chromiumpython3.11 -m pip install /path/to/dayu_agent-<version>-py3-none-any.whl安装后确认公开入口：
dayu-cli --helpdayu-cli initinit 会交互选择一组普通/思考模型，并把当前配置与 prompt assets 发布到
./workspace/config/。Ollama 与 OpenAI-compatible 自定义模型会继续询问模型名、
endpoint 和上下文窗口；其它选项使用内置的当前模型目录。初始化会用真实配置加载和
scene 校验拒绝无效结果，但不会探测 endpoint、下载模型或发起网络请求。
常用形式：
dayu-cli init --base ./my-workspace
dayu-cli init --base ./my-workspace --overwrite
dayu-cli init --base ./my-workspace --resetinit 通过 --base / -b / --workspace 选择工作区；不传时使用
./workspace。配置固定读取该工作区的 config/，不存在时使用包内默认配置。
init 只有以下四种状态：
- FIRST：
config/不存在且未传覆盖参数，从包内默认配置开始创建。 - PRESERVE：
config/已存在且未传覆盖参数，保留用户配置、文件和自建 manifest；补回 缺失的五个根配置文件与包内 prompt 文件，并把本次明确选择投影到已知模型/manifest 字段。已经存在的文件不会被补缺步骤覆盖。 - OVERWRITE：传
--overwrite，从包内默认配置完整重建config/，不合并旧配置。 - RESET：传
--reset，先列出实际存在的.dayu/、config/并默认选择 No；明确确认后 移走整个.dayu/与旧config/，再从包内默认配置重建。RESET 优先于--overwrite。
四种状态都不会创建、删除或重建 public portfolio/、assets/。为防止写出工作区，
workspace、锁文件、受管树或其子树中的 symlink / Windows reparse entry 会被拒绝。
无覆盖参数时，普通文件占据 config 或 .dayu 也会被拒绝；--overwrite 可以重建被
普通文件占据的 config，--reset 可以重建被普通文件占据的 config 与 .dayu。
symlink、dangling symlink、special file 和非法 lock identity 在所有模式下都拒绝。
模型选择、动态模型名、endpoint、上下文窗口、secret 与 yes/no 输入不合法时会在当前
提示重新输入。RESET 确认输入 No 或直接按 Enter 时退出 0 且不修改工作区；输入 EOF
时退出 1，按 Ctrl-C 时退出 130。需要持久化必需 secret 时，最终确认输入 No、
直接按 Enter 或 EOF 都表示初始化未完成并退出 1，按 Ctrl-C 退出 130；这些路径
都不会发布部分配置。
当所选模型需要 API Key 且当前进程没有对应变量时，init 在真实终端（TTY）隐藏输入值；
stdin 被重定向时，每个 secret 提示写入 stderr，并从 stdin 逐项读取一行，CLI 不把值写回
stdout/stderr。两种方式都在一次最终确认中只展示目标与变量名。POSIX 写入当前 shell 对应的
~/.zshrc 或 ~/.bashrc 的唯一 managed block；Windows 使用当前用户的 setx。可选集成只包括
TAVILY_API_KEY、SERPER_API_KEY、FMP_API_KEY、HF_ENDPOINT、HF_TOKEN。默认 No；拒绝或
持久化失败时不会发布 workspace 配置。secret 值不写入 workspace，也不进入成功/失败输出。
FIRST/RESET 发布成功后会在当前进程中导入 prompt 与 interactive 入口以减少首次冷启动；
该步骤不读取 workspace/env、不装配运行时、不联网。若出现 prewarm warning，配置仍已成功
发布，后续命令会按正常导入路径启动。
.dayu-init.lock 只用于串行多个 init，不会锁住正在运行的 CLI/Web/WeChat/Host。
执行 RESET 前必须先停止这个 workspace 的所有 active Dayu 进程；等待锁时可根据
正在等待此 workspace lock 提示确认命令尚未进入发布阶段。
初始化后的主要目录：
workspace/
├── config/ # 配置 overlay 与 prompt assets
├── portfolio/ # 已导入的财报和材料
└── .dayu/ # Session、运行期状态与 artifacts
也可以在运行 init 前自行设置 API Key。具体模型引用哪个变量，以
workspace/config/models.json 为准。例如：
export MIMO_PLAN_API_KEY="..."
export FMP_API_KEY="..." # 可选：为 ticker context 补充公司名包内默认普通问答与会话压缩都使用 Mimo Token Plan 模型家族。init 选择的普通/思考
模型会投影到全部包内场景，会话压缩与该选择使用相同的 provider、provider 模型、
endpoint 和 credential 引用，但可以使用不同的采样与流式参数。
dayu-cli <command> [参数]
dayu-cli <command> --help当前命令：
| 命令 | 当前行为 |
|---|---|
init |
初始化或重置工作区配置 |
prompt |
提交一次财报分析问题 |
interactive |
进入多轮终端交互 |
download |
下载指定主体的财报 |
upload_filing |
上传或管理单份 filing |
upload_material |
上传或管理补充材料 |
upload_filings_from |
扫描目录并生成可执行的批量上传脚本 |
process |
预处理某主体的文档 |
process_filing |
预处理单份 filing |
process_material |
预处理单份 material |
session |
列出、恢复或清理 CLI Session |
tool_trace |
分析 Tool Trace 并发布诊断报告 |
| 参数 | 说明 |
|---|---|
--base / --workspace |
工作区根目录，默认 ./workspace |
--log-level LEVEL |
可选 debug、verbose、info、warning、error、critical、quiet；warn 与 warning 等价 |
--debug / --verbose / --info / --warning / --error / --critical / --quiet |
对应日志等级的快捷参数；同时保留与 --warning 等价的 --warn |
--debug-stream |
额外打开高频 stream/SSE 诊断，不改变普通日志等级；不可与 quiet 组合 |
--log-file PATH |
把诊断日志追加写入指定文件；可与任意合法日志等级选择组合 |
--log-level 和所有日志等级快捷参数彼此互斥，一次调用只能选择其中一个。
--debug-stream 可以单独使用，也可以与 debug、verbose、info、warn / warning、
error 或 critical 组合。
用户可见回答和进度仍写 stdout/stderr。未传 --log-file 时，诊断日志只保留到
当前 CLI 进程结束；需要排障留档时必须显式指定路径：
dayu-cli prompt "总结主要风险" --ticker AAPL \
--debug --log-file workspace/prompt.log--log-file 不会创建缺失的父目录；请先创建父目录。父目录不存在或目标无法打开时，
CLI 会显示可操作的错误并退出 1，不会开始本次分析。
dayu-cli prompt "总结最新财报的主要风险" --ticker AAPL--ticker 可省略。提供后，它既进入 CLI 请求身份，也通过共享 scene context
作为模型可读的“当前分析对象”；若显式配置了有效 FMP_API_KEY，context 会尝试
补充公司名，解析失败时仍保留 ticker。
常用参数：
--label LABEL：绑定或复用 prompt Session。--model ID/-m ID：只覆盖本次主 Run 的模型配置；不写入 workspace，也不改变 会话压缩模型。即使本次主 Run 显式选择不同的 provider family，会话压缩仍使用init选择的 family；未执行init时使用包内默认 family，不跟随单次 override。interactive与session resume使用相同参数。--temperature FLOAT、--tool-timeout-seconds FLOAT、--max-iterations INT： 覆盖本轮执行参数。--thinking/--no-thinking：控制运行态思考展示。--detail/--no-detail：控制 activity stream 展示。
dayu-cli interactive
dayu-cli interactive --label earnings不传 --label 时，每次启动创建一个新的未绑定 Session；传入 label 时复用
cli.agent.<label> 对应 Session。prompt --label earnings 与
interactive --label earnings 使用同一个 label owner 和同一个 Session；旧
cli.prompt.* / cli.interactive.* slot 不会被自动读取或迁移。interactive
不接受 --ticker；需要指定分析主体时，请直接写在本轮输入中。
TTY 输入中，Enter 提交，Ctrl+J 或支持 xterm Shift+Enter 序列的终端插入换行；
运行期间键入的 draft 会保留到当前任务收口，Enter 最多排入一个后续问题并在当前任务
终态后执行。独立 Escape 或第一次 Ctrl+C 请求取消当前任务；取消收口期间再次
Ctrl+C 只登记“收口后退出”，CLI 仍会等待当前 canonical terminal 和已经 accepted
的唯一后续任务完成，再以 130 退出。CSI、Alt 和 bracketed paste 不会因 Escape 前缀
误触发取消。
空闲且输入为空时，Ctrl-D 正常退出；运行期间 Ctrl-D 不取消任务。stdin 不是 TTY
时，interactive 会读取整个 UTF-8 输入流，只做一次提交，不显示提示符，也不把换行
拆成多个 Run；空白流不提交，非法 UTF-8 作为稳定用法错误退出。
交互会话可以按问题需要下载财报、列出已入库文档并读取财报内容，但不在会话中执行
预处理。需要预处理时，请使用第 5.4 节的 process、process_filing 或
process_material 独立命令。
dayu-cli download --ticker AAPL
dayu-cli download --ticker AAPL --forms 10-K 10-Q --start 2024 --end 2025
dayu-cli download --ticker 600519 --forms FY H1 --start 2024
dayu-cli download --ticker 0700 --rebuild可用参数以 dayu-cli download --help 为准：--forms、--start、--end、
--overwrite 和 --rebuild。命令会先完成静态用法校验，再解析或创建 workspace、
启动下载运行期或访问数据提供方；非法 ticker、表单或日期窗口以用法错误退出码 2
结束，并且不会产生 workspace 或下载运行期副作用。
--ticker 只接受一个 ticker，并统一转换为市场对应的规范写法；--forms 会按市场
规范化并稳定去重，SEC 表单还会统一大小写。--start 与 --end 接受 YYYY、
YYYY-MM 或 YYYY-MM-DD，分别展开为所给期间的起始日和结束日，形成包含边界的日期
窗口。单独年份和年月中的年份必须在 1000..9999；完整日期允许实际公历
0001..9999，月、日可写一位或两位。命令会忽略日期文本首尾空白、校验真实月末与
闰年，并把接受的边界统一显示为补零的 YYYY-MM-DD。下载 SEC 文件前必须提供合规的
User-Agent 身份，例如：
export SEC_USER_AGENT="Your Organization contact@example.com"--overwrite 只替换本轮选中的单个目标文档，不会清空 ticker 下的其它已下载文档；
空结果、失败或取消也不会删除非目标旧文档。--rebuild 只根据已经下载到本地的源文档
重建下载元数据和 manifest，不发送数据提供方请求，也不新增、删除或替换源文档内容。
两者是互斥模式，不能在同一命令中同时使用。
未传 --forms 时，CN 默认请求 FY H1 Q1 Q3；HK 的必需基线是 FY H1，同时会发现
来源实际披露的 Q1～Q4 可选业绩材料。缺失期间只针对当前市场适用的必需基线计算：例如
HK 的中期业绩可显示覆盖 H1，但不能代替独立中期报告消除 H1 missing；末期业绩同样不能
代替独立年报消除 FY missing。
下载、上传和预处理命令会显示执行进度及最终摘要。下载摘要包含规范 ticker、实际表单与
日期窗口、overwrite/rebuild 状态，以及发现、下载、跳过、拒绝、失败和缺失期间信息；
每个下载文档行还会显示来源声明的 covered_fiscal_periods 数组。
下载期间按下 Ctrl-C 会请求协作取消并等待当前操作收口；取消终态使用规范退出码
130，不会用内部取消原因替代用户可见摘要。财报保存在
<workspace>/portfolio/<规范 ticker>/，例如 AAPL 对应
workspace/portfolio/AAPL/。
dayu-cli upload_filing \
--ticker AAPL,APPL \
--action create \
--files ./AAPL-2024-10K.pdf \
--fiscal-year 2024 \
--fiscal-period FY \
--company-name "Apple Inc."
dayu-cli upload_filing \
--ticker AAPL,APPL \
--action create \
--files ./filing/AAPL-2024-10K.pdf ./filing/AAPL-2024-instance.xml \
--primary ./filing/AAPL-2024-10K.pdf \
--fiscal-year 2024 \
--fiscal-period FY \
--company-name "Apple Inc."
dayu-cli upload_material \
--ticker AAPL,APPL \
--action create \
--forms 10-K \
--material-name "Investor Day" \
--files ./investor-day.pdf允许上传的文件后缀和每个 action 的必填字段由命令在执行前校验。查看完整参数：
dayu-cli upload_filing --help
dayu-cli upload_material --helpupload_filing --files 声明同一 filing 的文件集合，文件顺序不决定主文件角色。单文件
filing 可以省略 --primary，省略时唯一文件就是 primary；多文件 filing 必须恰好提供
一次 --primary PATH，且该路径必须精确匹配 --files 中的一个文件。除 primary 外的
文件都是 companions，只按输入内容原样保存；只有 primary 会执行 Docling 转换，后续
预处理与读取也只消费该 primary 的 Docling 结果。不同目录中 basename 相同的文件，或
stem 相同但后缀不同的文件，可以在同一 filing 中共存，不会互相覆盖。XBRL companion
可以随同一批上传并原样保存。.xml 只是 XBRL XML candidate，.json 只是 Docling
JSON candidate；主文件后缀通过只表示具备转换资格，不保证其内容一定转换成功；随附
文件（含 .xsd）只按可随批保存的后缀准入，不做转换。当前支持的格式清单以
dayu-cli upload_filing --help 的即时输出为准；不要将 legacy DOC/PPT/XLS 或 ZIP 视为已支持格式。
以下情况都会在上传任务启动前作为用法错误退出 2，不会发布文件：--files 中包含
解析后相同的重复路径；多文件没有 --primary；重复提供多个 --primary；primary 不在
files 集合内；文件数超过 100；或 delete 携带 --files / --primary。恰好 100 个
不同文件允许上传。
upload_filing 与 upload_material 都会在上传任务启动前校验 --ticker 的逗号分隔值：首项必须是公司的规范主代码，后续项是用户声明、用于查询同一家公司归档的别名；每一项都必须符合支持市场的 ticker 写法，后续别名最多 100 个。ticker 写法非法或别名超过数量限制时，命令会作为用法错误输出一行具体原因并退出 2，不会创建上传任务或发布文件。
upload_filing 还会在任务启动前校验文件与当前目标状态。文件解析、存储或执行失败会输出脱敏的可操作原因并退出 1；filing 的公司信息与文档内容只会一起发布，失败时不会留下只发布一半的结果。已有且仍新鲜的公司信息不会被单次 filing 上传改名；若本次填写的公司名称未被采用，命令仍按成功或跳过结果退出 0，stdout 摘要保持不变，并在 stderr 提示核对上传目标公司。上传成功后，使用主代码或任一已接收别名查询都会进入同一家公司归档；合法的新别名即使 filing 内容因完全相同而跳过，也会与公司信息原子保存。不要重复列出只是写法不同但含义相同的代码。若某个别名已属于工作区中的另一家公司，本次上传会在发布任何文件前拒绝，并提示移除冲突别名后重试。
直接调用 upload_filing 或通过 start_fins_upload 工具上传 filing 时，fiscal_year
必须是 1000..9999 的整数；fiscal_period 只接受 FY、H1、Q1、Q2、Q3、
Q4，输入会忽略首尾空白并统一为大写，US、CN、HK 使用同一规则。CLI 收到其它值时
会输出一行具体原因并以用法错误 2 退出；这两个入口都会在创建上传操作或改动 workspace
前拒绝非法值。可选的 filing_date 与 report_date 若填写，必须是实际
存在、月日补零且无首尾空白的 YYYY-MM-DD，完整日期年份允许 0001..9999。空串、
纯空白、非补零日期和不存在的月日都会在运行期或上传任务创建前拒绝。该严格原始输入
承诺只适用于这两个直接 filing 入口，不覆盖 upload_filings_from 的扫描与脚本生成元数据
处理。
上传终态摘要中的 requested files 是本次已校验的输入文件数，stored files 是本次成功发布的原始文件数；Docling 派生文件不重复计数。空文件、任一原始文件读取失败，或 filing primary / material 任一需要转换的文件内容无法成功转换时，整批上传失败且 stored files 为 0，不会把先处理成功的文件计为已保存；filing 失败时也不会回退为只保存原文件或 companions。stderr 会同时显示触发失败的文件名和有界原因。若 direct 命令遇到无法归入这些已知原因的内部异常，普通 stderr 只显示 命令执行失败，请使用 --log-file PATH 重试并查看日志；按提示为 PATH 选择可写文件并重新执行命令，即可在该文件中保留完整诊断。
三个上传命令的 --action 默认都是 auto。单份上传还可显式使用
create、update 或 delete；批量脚本只会生成 auto、create 或 update。
update 只更新已经存在的同一 filing identity；目标不存在时即使同时传入 --overwrite 也会拒绝，请改用 create。--overwrite 不是 upsert 开关，只允许覆盖已存在的 create 目标或强制重建已存在目标。auto 遇到已逻辑删除的目标会执行 update 并恢复为 active，不会因输入内容相同而跳过；若本地目标已损坏但仍能由本次完整输入安全重建，auto 会原子替换全部原始文件和 Docling 文件并恢复完整索引。此类目标若显式使用 create、update 或 delete 会失败，并提示改用 auto 提供完整文件；无法确认身份或无法安全重建的本地状态也会在发布前失败，并提示先修复工作区。existing update 或安全重建后旧文件名不会残留，失败或发布前取消仍保留完整旧集合。
上传期间第一次按下 Ctrl-C 只会请求一次协作取消，命令会继续等待并展示上传运行期给出的最终结果。若取消在文档发布前生效，最终显示 cancelled 并退出 130，不会先显示 completed；若文档发布或确定的跳过/删除结果已经完成，随后到达的 Ctrl-C 不会把该结果改写为 cancelled，也不会回滚已发布内容。
upload_filings_from 扫描和分类本地文件，生成当前平台可直接执行的脚本；生成阶段不上传文件：
mkdir -p ./workspace/scripts
dayu-cli upload_filings_from \
--base ./workspace \
--ticker AAPL,APPL \
--from ./filings \
--recursive--ticker 接受逗号分隔值：首项是公司的主代码，其余项是用户明确声明的同公司别名，脚本中的每条上传命令都使用同一组值；成功上传后，任一已接收代码都查询同一家公司归档。
--action 默认 auto；需要固定动作时可显式传 --action create 或 --action update。
未传 --output 时，脚本写到 --base 工作区根目录：POSIX 使用
upload_filings_<TICKER>.sh，Windows 使用 upload_filings_<TICKER>.cmd。--output
可以指向工作区内的既有目录，此时仍使用默认文件名；也可以指向工作区内的精确文件路径，命令不会替它补后缀。
显式文件的父目录必须已经存在。例如：
dayu-cli upload_filings_from \
--base ./workspace \
--ticker AAPL \
--from ./filings \
--output ./workspace/scripts/upload-aapl.script需要补全公司名称和 ticker aliases 时，先在当前环境设置 FMP_API_KEY，再显式传
--infer。resolver 只在生成阶段调用；API key 不会写入脚本。生成成功后，stdout
会显示脚本绝对路径、recognized filing、material 和 skipped 数量，并逐项显示业务可读的跳过原因。
执行前先打开脚本检查文件与参数，再按平台运行：
# POSIX
/bin/sh ./workspace/upload_filings_AAPL.sh
# Windows
cmd.exe /d /c .\workspace\upload_filings_AAPL.cmd脚本把调用者追加的参数逐元素追加到每一条上传命令。例如以下 POSIX 调用会让每条命令都收到
--overwrite；Windows 同样把参数放在 .cmd 路径之后：
/bin/sh ./workspace/upload_filings_AAPL.sh --overwrite脚本输出必须留在 --base 工作区内，工作区自身、内部目录和既有目标不能是 symlink。
如果没有生成脚本，先查看摘要中的跳过原因并核对文件名是否含可识别的财年/财期；如果报 output
错误，确认目标父目录已存在且位于工作区内。upload_filings_from --overwrite 控制每条上传命令的
存储覆盖语义，不控制脚本文件替换。
dayu-cli process --ticker AAPL
dayu-cli process --ticker AAPL --document-id filing-1 --document-id filing-2
dayu-cli process_filing --ticker AAPL --document-id filing-1
dayu-cli process_material --ticker AAPL --document-id material-1--overwrite 会请求重建已处理结果。
dayu-cli session list通过 Session id 恢复单次 prompt：
dayu-cli session resume \
--session-id <session-id> \
--mode prompt \
--ticker AAPL \
"继续分析现金流"通过 label 恢复 interactive Session：
dayu-cli session resume \
--label earnings \
--mode interactivelabel selector 不再接受 --kind。--mode 只选择本次输入方式；prompt 模式仍可使用
--ticker，interactive 模式不接受 --ticker。两个模式都从所选工作区的 config/
读取配置；该目录不存在时使用包内默认配置。
清理 Session 需要显式确认；CLI 不会自动 close 或 cancel：
dayu-cli session purge --session-id <session-id> --yes只有已关闭且全部任务都已终态的 Session 才能 purge。
同一个工作区内，若两个 CLI 进程同时选择同一 Session，先进入的进程可以继续提交、改向或取消，
后进入的进程会以只读方式打开，并在尝试修改时得到明确错误。需要在后进入的进程继续操作时，
先在原进程正常退出当前 prompt 或 interactive 会话并等待其关闭完成，再退出并重新执行
session resume；已经打开的只读会话不会在原进程退出后自动变为可写。
tool_trace analyze 只读分析现有 Tool Trace，并在指定目录发布同一次分析得到的
JSON 与 Markdown 报告：
dayu-cli tool_trace analyze ./workspace --output-dir ./reports/tool-traceINPUT 必须显式选择以下一种输入：
- workspace 目录，例如
./workspace； .dayu目录，例如./workspace/.dayu；- tool-trace 目录，例如
./workspace/.dayu/artifacts/tool-trace； - 单个 cold JSONL 文件，例如
./workspace/.dayu/artifacts/tool-trace/tool-trace-cold.jsonl。
成功后输出目录包含：
tool-trace-analysis.json
tool-trace-analysis.md
目录输入会按当前固定布局同时发现可用的 hot SQLite、cold JSONL 和 payload
artifacts；单文件或 tool-trace 目录输入是 cold-only，不会从父目录猜测 hot
数据库或 payload root，因此报告会明确标记相应 limited_signal，而不是把
“无法证明”写成“未发生”。同一输入若同时匹配多个布局会拒绝执行；此时传入更具体的
.dayu 目录或 cold JSONL 文件。工作区路径参数不参与 Analyzer 输入发现。
报告中的 findings 和 limitations 不改变成功退出码。输入路径或布局错误返回 2；
可信读取、分析或发布失败返回 1。发布第二个文件失败时，命令会分别列出本次已发布
路径和失败路径；既有报告不会被主动删除。
默认再次运行 init 会进入 PRESERVE：保留用户文件和自建 manifest，补齐缺失的五个
根配置文件与包内 prompt 文件。需要完全用包内默认配置替换 config/ 时使用
--overwrite；需要同时移除整个 .dayu/ 时使用 --reset，并先停止所有 active
Dayu 进程。
为保证所有写入留在工作区，workspace、.dayu-init.lock、受管树及其子树都必须是普通
目录/文件，不能是 symlink、dangling symlink 或 Windows junction/reparse entry。请改用
工作区内真实目录后重试；不要通过链接绕过检查。
检查所选模型在 workspace/config/models.json 中的 api_key_ref。可在运行 init 前设置
对应变量，或按隐藏输入和最终确认写入 POSIX shell profile / Windows 用户环境。输出只会
显示变量名；如果持久化失败，修复目标 profile/用户环境后重试，workspace 不会半发布。
另一个 init 正持有 <workspace>/.dayu-init.lock。等待方不会使用有限 production timeout，
也不会提前发布配置；让前一个 init 正常完成即可。该锁不代表其它 Dayu 进程已停止，
RESET 前仍必须自行停止 active CLI/Web/WeChat/Host。
FIRST/RESET 的配置已经发布成功，warning 只表示本进程未完成两个 CLI 入口的 import-only
预热，不会触发回滚，也不包含 provider 响应或环境变量值。可直接运行 prompt 或
interactive；若正常导入仍失败，再使用 --debug --log-file <path> 收集诊断。
这是当前设计：未传 --log-file 的诊断流在进程结束时自动清理。重现问题时加上
--debug --log-file <path>；排查高频流式链路时改用 --debug-stream。
先运行 dayu-cli upload_filings_from --help 核对 source、ticker 和 output 参数。源目录必须存在且不能是
symlink；脚本 output 必须位于工作区内。命令输出的 skipped reason 会说明文件因财期信息缺失、同期去重、
数量限制或路径安全检查而未进入脚本的原因。