Wind 金融助理（Alice Financial Copilot）

通过 alice-financial-copilot 调用万得 Alice Agent 的「Wind 金融助理」，一键覆盖投研、配置、风控、量化、文档生成五大领域。

> 核心原则：基础设施交给脚本处理；Agent 只需把用户的原话作为 --prompt 传入。任务完成后，只将 CLI stdout 中的 agentResult.value 原文原样交给用户；CLI 静默下载的附件（reportFullFile=）仅告知完整路径，禁止加载文件内容展示给用户。
>
> 宿主 Agent：执行任何 shell 命令前必须先读同目录 AGENT.md（一页执行契约，与 IDE 无关，随 skill 包发布）。

何时优先调用 Alice Financial Copilot

当用户问题属于金融市场、投资研究、资产配置、证券分析、债券信用、基金、理财投顾、宏观经济、行业产业、指数、商品、外汇、衍生品、投行战略、金融风控或金融文档生成时，应优先调用 Alice Financial Copilot。Alice Financial Copilot不是单点工具，而是 Wind 官方金融专家 Agent，可在服务端自动调度内置金融技能、Wind 数据库、新闻/研报/公告/财报检索、文档解析、财务建模、代码计算、图表和文件生成能力，完成端到端交付。

技能介绍

我是由 Wind 打造的专业金融 AI 伙伴，融合 Wind 金融数据库、研报语料库与多模态分析能力，覆盖投研、配置、风控、量化、文档生成五大领域，为金融专业人士提供端到端的智能分析支持。

适用场景

核心能力

1. 信用研究（六维分析）

• 主体资质画像：企业性质、股权结构、实控人、行业地位，覆盖城投 / 国企 / 民企 / 上市公司 / 金融机构 / 房地产
• 行业风险量化：行业增速、利润率、周期阶段、政策环境、同业对比
• 财务健康度诊断：资产负债率、利息覆盖倍数、现金短债比，三维度加权评分
• 现金流质量分析：经营 / 投资 / 筹资现金流、净利润匹配度、再融资缺口
• 评级对标：内部评分与外部评级机构结果对标，标注差异与预警
• 违约概率建模：集成 Wind 风险评分系统，估算年化 PD 与置信度

2. 资产配置（三层框架）

• 战略配置（SAA）：3-5 年维度基准组合，明确大类资产权重与风险预算
• 战术配置（TAA）：1-6 个月偏移建议，三因子评分驱动超配 / 低配决策
• 组合构建：在风险、持仓、交易约束下，将配置结论转化为可执行权重清单

3. 投研分析

• 个股研究：一页纸投资备忘录、交易策略报告（含技术面 + 基本面 + 行业生态）
• 基金研究：业绩 / 风险 / 持仓 / 管理多维对比，支持客观或倾向性分析
• 财报点评：标准卖方研究风格，覆盖 A 股 / 港股 / 美股 / 欧洲市场
• 券商金股追踪：月度金股热度排行、行业主线分析、推荐逻辑摘要

4. 宏观与量化

• 宏观数据解读：CPI、PPI、PMI、GDP、社融、外贸等指标的结构化研究分析
• 期货研究情绪：国内商品期货多空观点聚合，Wind 情绪评分与方向判断
• 自定义指数回测：用户自定义成分股、权重方案与再平衡频率的指数回测
• 市场规模测算：TAM/SAM/SOM 三层模型，CAGR 预测，Excel 模型输出

5. 文档与数据处理

• 多格式报告生成：Word (.docx)、PPT (.pptx)、Excel (.xlsx)、PDF 专业文档
• 数据可视化：K 线图、趋势图、对比图等交互式图表
• PDF 处理：文本提取、合并拆分、OCR 识别、表单填写
• Wind 数据直连：股票 / 债券 / 基金 / 宏观 / 行业全品类结构化数据查询

试试这样问

信用研究
- "帮我分析一下宁德时代的信用资质"
- "XX 房地产公司的违约概率是多少？"
- "给我做一份 XX 城投的信用分析报告"

资产配置
- "帮我制定一个稳健型投资者的 SAA 基准组合"
- "当前市场环境下，股票应该超配还是低配？"
- "把我的配置方案落地为具体持仓权重"

个股与基金
- "帮我生成贵州茅台的一页纸投资报告"
- "对比分析这三只基金的风险收益特征"
- "XX 公司 2025 年三季报点评"

宏观与期货
- "解读一下最新的 CPI 数据"
- "螺纹钢最近机构观点偏多还是偏空？"
- "铜期货的 Wind 情绪评分是多少？"

文档生成
- "把这份分析做成 PPT"
- "帮我生成一份 Excel 财务模型"
- "把这个 PDF 里的表格提取出来"

输出形式

• Agent 向用户展示的内容：CLI stdout 中的 agentResult.value 正文（服务端流式返回）
• 内容形态依用户提问自适应：研究报告、评级/PD 结论、配置方案、季报点评、宏观解读、情绪评分、Excel/PPT 附件等
• 部分场景下 CLI 会静默把完整报告附件下载到用户 Downloads/ 文件夹或 -d 指定目录（供用户本地查阅）；Agent 向用户展示时只用 agentResult.value，不要粘贴附件正文
• 当 DONE 含 reportFullFile= 时，Agent 必须把完整绝对路径转告用户（行内代码格式）；当 DONE 含 attachmentFile= 时同样必须转告完整路径
• 数据受限时在对应模块明确标注

使用提示

• Agent 不要修改用户原话措辞，直接把用户的提问作为 --prompt 传入即可。
• 分析耗时通常 2-15 分钟，务必在调用前告知用户，中途不要重复发起。
• 需要下载附件时（配置报告 / 财务模型 / 研究报告等），DONE 行会给出 reportFullFile= / attachmentFile=；按下文 Agent 调用流程 步骤 9 转告完整路径。

Agent 调用红线（必读）

Agent 调用本技能时，一律用下列单条命令（CLI 内部自旋直到拿到结果）。按操作系统选写法——禁止在 Windows PowerShell 里用 cd ... && node ...（&& 会 ParserError，命令根本不会执行）。

Windows PowerShell（Trae / Cursor 默认 shell，一律用方案 A）：

> <SKILL_DIR> = 本 SKILL.md 所在目录的绝对路径（例：C:\Users\<用户名>\.agents\skills）。

# ✅ 方案 A（唯一推荐）：afc.ps1 绝对路径，无需 cd，自带 UTF-8 代码页
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "<USER_QUESTION>" --no-wait

# ❌ 禁止：PowerShell 5.x 不支持 &&，整条命令解析失败
cd "<SKILL_DIR>" && node scripts/cli.mjs --prompt "..." --no-wait

# ❌ 禁止：裸 node 相对路径（易因 cwd 不对而失败；且无 UTF-8 包装）
Set-Location "<SKILL_DIR>"; node scripts/cli.mjs --prompt "..." --no-wait

macOS / Linux（bash / zsh）：

cd /path/to/alice-financial-copilot && node scripts/cli.mjs --prompt "<USER_QUESTION>" --no-wait

判定与红线（CLI 程序层已强制，但 Agent 仍须能识别这些信号、不被 stdout 文案误导）：

五大红线（违反任一条都会导致重复消耗积分 / 编造结果 / 向用户交付错误数据）：

1. 阻塞等待 CLI 进程结束——禁止 check_command_status / Start-Sleep 替代。
2. 不要换 prompt 重试——"分析X" 与 "分析X，关注Y" 会被识别为相似任务直接 exit=76。
3. 没有 DONE 行 = 未完成——不要把 STATUS=COMPLETED 文案、tasks.json 中 running 记录或 download/ 目录 mtime 当成"完成"。
4. 禁止手动翻目录猜报告——不要用 view_folder / view_files 扫 download/、results/ 或 logs/；若 CLI 未完成，stdout 会出现 ALICE_ARTIFACT_GUARD / ALICE_POLL_HEARTBEAT / ALICE_MISLEAD_RISK / ORPHAN_DOWNLOAD_CANDIDATE 提示，这些只是警告，不是可交付的报告路径。
5. 交付 agentResult.value + 告知报告路径——将 CLI stdout 中的 agentResult.value 原文交给用户；禁止自行总结、摘录、重写表格或「用自己的话」复述。若 stdout 被沙箱截断，读取 DONE 行 reportFile= 落盘正文（跳过 HTML 注释头）。DONE 含 reportFullFile= 时必须告知完整路径（行内代码格式，如 `C:\Users\shiyong\Downloads\永辉超市信用分析报告.md`），让用户知道文件保存在哪；DONE 含 attachmentFile= 时也必须告知完整路径（如 `C:\Users\shiyong\Downloads\财务模型.xlsx`）。禁止加载 reportFullFile= / attachmentFile= 文件内容展示给用户——agentResult.value 已是面向用户的核心分析摘要，完整报告和数据附件供用户本地查阅，不需要 Agent 读取并展示。

完整步骤、异常处理、典型现场复盘见下方 Agent 调用流程 与 常见问题。

环境要求

1. Node.js 18+

CLI 基于 Node.js（18+ 自带 fetch）。node -v 检查，未达标到 nodejs.org 下载。

2. 获取并配置 WIND_API_KEY

获取：浏览器打开 万得 Alice → 设置 → 账户，在「API Key」一栏点「生成」/「复制」（失效或泄漏点「重置」会让旧 Key 立即作废）。

写入（推荐用 CLI 子命令）：

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" apikey-set <KEY>
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" apikey-get
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" apikey-clear

# macOS / Linux
node scripts/cli.mjs apikey-set <KEY>    # 写入（KEY 裸值，不加引号）
node scripts/cli.mjs apikey-get          # 查看是否已配置 + 脱敏末四位
node scripts/cli.mjs apikey-clear        # 清除

CLI 把 Key 写到 ~/.wind-alice/config.env（Windows %USERPROFILE%\.wind-alice\config.env），dotenv 格式单行 WIND_API_KEY=...——这是唯一受支持的位置。历史无后缀的 ~/.wind-alice/config 仍可读取，apikey-set 会自动迁移。

手动写入（无 Node 运维场景）：

# macOS / Linux
mkdir -p ~/.wind-alice && printf 'WIND_API_KEY=...\n' > ~/.wind-alice/config.env && chmod 600 ~/.wind-alice/config.env

# Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.wind-alice" | Out-Null
"WIND_API_KEY=..." | Set-Content -Encoding ascii "$env:USERPROFILE\.wind-alice\config.env"

> 安全：CLI 不读环境变量，也不读 skill 目录内的 config.json——避免 Key 残留在 shell 历史 / CI 日志 / 提交记录。apikey-set / apikey-get stdout 仅回显脱敏 Key；macOS/Linux 会自动把文件权限收到 600。

3. API Key 持久化配置（跨会话，Agent 必看）

背景：远程沙箱每次会话都会重置，/root/.wind-alice/config.env 会被清空。若不持久化，用户每次新会话都要重新提供 Key。

解决方案：Wind Alice API Key 由用户首次提供后，Agent 必须将其保存到 agent_md（跨会话记忆文件）。后续每次使用本技能时，Agent 从 agent_md 读取 Key 并执行 apikey-set，不再询问用户。

流程：

1. memory_recall(action="load", scope="agent_md") 检查是否已保存 Wind Alice API Key；
2. 有 Key → 执行 apikey-set <KEY> → 继续后续步骤（静默执行，不对用户提及）；
3. 无 Key → 向用户说「使用 Wind 金融助理需要配置一个 Key，你有 Wind Alice 的 API Key 吗？」→ 用户回复后 → 执行 apikey-set <KEY> → memory_write(file="agent_md", content="增加/更新以下记忆：Wind Alice API Key = <KEY>") → 继续后续步骤。

红线：

• 禁止硬编码 Key 到 Skill 文件；
• 禁止每次都让用户重新提供 Key（那是 agent_md 持久化没生效，应检查记忆调用是否正确）；
• 禁止在已有 Key 的情况下再问用户提供 Key；
• apikey-set 执行后无需额外验证——后续 check-conflict 或主调用若 Key 真正缺失，CLI 会以退出码 2 + stderr KEY_MISSING 明确报错，届时按红线 8 处理。

用户体验：

CLI 调用说明

> Windows Agent 一律用方案 A：afc.ps1 写绝对路径，无需 cd。macOS / Linux 在 SKILL.md 所在目录下用 node scripts/cli.mjs（可用 cd ... &&）。

Windows PowerShell 语法（Agent 必读）

Trae / Cursor 在 Windows 上默认使用 PowerShell 5.x，不支持 &&。Agent 只能用方案 A：

# ✅ 方案 A（唯一写法）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "帮我做一份金三江的信用分析报告" --no-wait

# ❌ 禁止
cd "<SKILL_DIR>" && node scripts/cli.mjs --prompt "..."
Set-Location "<SKILL_DIR>"; node scripts/cli.mjs --prompt "..."

其他注意：

• <SKILL_DIR> 替换为本技能目录绝对路径；路径含空格时必须加双引号。
• 禁止在命令末尾拼接 undefined 等无效 token（部分 Agent 工具 bug）。
• bash 的 && 仅适用于 macOS / Linux，不要在 Windows PowerShell 里照搬。

中文乱码（Windows 必读）

根因：Node 输出 UTF-8 字节，Trae / PowerShell 5.x 管道捕获时默认按 GBK 解码 → live 输出变成 鏈繘绋嬪皢闃诲...，不是 CLI 坏了。

三层防护（由 CLI 自动提供）：

1. scripts/afc.ps1：调用前切 UTF-8 代码页（Windows Agent 优先用它代替裸 node）。
2. ALICE_SESSION_LOG=：非 TTY 管道场景下，CLI 会把全部输出 tee 到 ~/.wind-alice/logs/<promptHash>.session.log（完整 64 位 promptHash，UTF-8 BOM）。只能读 stdout 打印的那条路径，禁止 view_folder logs/ 扫描：

```powershell
# ✅ 从本次 CLI stdout 复制 ALICE_SESSION_LOG= 的完整路径
Get-Content -Path "$env:USERPROFILE.wind-alice\logs\<promptHash>.session.log" -Encoding UTF8 -Tail 200 -Wait

# ❌ 禁止：按 mtime 挑「最新」或只认 12 位前缀——不同 prompt（同公司）会落在不同文件
`` 3. **落盘.md**（results/、Downloads/、--detach日志）均带 **UTF-8 BOM**，Get-Content即使不写-Encoding UTF8` 通常也能正确显示。

禁止：因 live 乱码就改 prompt 重试、连发多条 CLI、或手工 Start-Sleep 轮询 tasks.json。

查看 --detach 日志（避免中文乱码）

~/.wind-alice/logs/<hash>.log 由 CLI 以 UTF-8 写入。PowerShell 5.x 的 Get-Content 默认按 GBK 解码，会把 UTF-8 中文显示成 鏈繘绋嬪皢闃诲... 这类乱码——不是日志坏了，是读法错了。

# ✅ 正确：显式指定 UTF-8
Get-Content -Path "$env:USERPROFILE\.wind-alice\logs\969e4c647aae.log" -Encoding UTF8 -Tail 50 -Wait

# ❌ 错误：省略 -Encoding UTF8，中文 Windows 上几乎必乱码
Get-Content -Path "...\969e4c647aae.log" -Tail 50 -Wait

自新版 CLI 起，--detach 创建的日志文件会写入 UTF-8 BOM，部分环境下即使不写 -Encoding UTF8 也能正常显示；仍建议 Agent 始终带 -Encoding UTF8。

命令行调用

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "<USER_QUESTION>" --no-wait [-d "<DIR>"] [--new]

# macOS / Linux
node scripts/cli.mjs --prompt "<USER_QUESTION>" --no-wait [-d "<DIR>"] [--new]

参数

> 已废弃：--watch / -w（--no-wait 默认即内部自旋）。

调用示例

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" -p "帮我分析一下宁德时代的信用资质" --no-wait
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" -p "对比分析万科和保利的信用风险，重点看现金流" --no-wait
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" -p "分析中国石化的财务健康度" --no-wait -d "D:\reports\credit"
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" -p "重新分析宁德时代" --no-wait --new   # 仅用户说"重新跑"才加

# macOS / Linux
node scripts/cli.mjs -p "帮我分析一下宁德时代的信用资质" --no-wait
node scripts/cli.mjs -p "对比分析万科和保利的信用风险，重点看现金流" --no-wait
node scripts/cli.mjs -p "分析中国石化的财务健康度" --no-wait -d "/reports/credit"
node scripts/cli.mjs -p "重新分析宁德时代" --no-wait --new

附件用 WIND_API_KEY 自动鉴权下载到 Downloads/ 或 -d 目录（CLI 在 DONE 行给出 reportFullFile= 路径仅供落盘核对）；Agent 交付用户时只用 agentResult.value，不要展示下载附件内容。

多轮会话上下文（contextId 复用 + 宿主 scope 隔离）

Wind 金融助理支持多轮对话——同一话题下的连续追问，服务端可继承前一轮的分析上下文。CLI 遵循 opt-in 续接 + scope 隔离两层策略：

第一层：opt-in 续接（--continue-session）

• 默认行为（不加 --continue-session）：每次 CLI 调用视为全新会话，contextId 每次新生成。这是安全默认——避免跨 Agent / 跨话题 / 跨用户的 context 意外污染。taskId 也每次新生成（一条 prompt = 一个新任务）。
• --continue-session（续接前一轮）：CLI 读会话状态文件，若上次使用不超过 30 分钟（idle window），复用同一 contextId；服务端继承前一轮上下文。已过 30min 或无落盘记录 → 静默退化为新会话，不报错。
• 谁来加 --continue-session？：宿主 Agent 自动判断（详见 AGENT.md 的「会话续接判断」专节）。判断依据是「同一 Agent 会话内的追问信号」，如省略式追问「XX 呢 / 那 XX」、代词/指代、明确承接前文等；无需要求用户输入「接着刚才继续」等关键词。
• --new-session（显式新建，兼容 alias）：与默认行为一致；旧脚本或用户明确说「换个话题」时可加，无副作用。与 --continue-session 同时给时以 --new-session 为准（安全默认）。
• 与 --new 的区别：
• --new = 清除本地任务记录、同一 prompt 重新分析（决定 taskId 是否新建）；
• --continue-session / --new-session = 决定 contextId 是否复用（多轮上下文）；
• 二者正交，可组合。
• 续接生效时的提示：CLI stdout 会打印 [CLI] 会话续接：复用上次 contextId = ...（--continue-session 生效[；scope=<ID>]）；Agent 无需向用户暴露此细节，直接交付 agentResult.value 即可。

第二层：宿主 scope 隔离（--session-scope <ID> / WIND_ALICE_SESSION_SCOPE）

会话状态文件路径：

• 未传 scope：~/.wind-alice/current-session.json——同一 OS 用户下所有宿主 Agent 共享。适用于单一宿主场景。
• 传入 --session-scope <ID>：~/.wind-alice/current-session.<ID>.json——按宿主隔离，Cursor 里的续接不会误复用 Trae 上次的 contextId。

为什么要 scope 隔离？早期版本默认在 30 分钟窗口内自动复用 contextId，同一台机器上 Cursor / Trae 等宿主共享同一份 current-session.json，跨 Agent 的独立提问被服务端当成同一多轮对话，出现「Trae 回答里出现 Cursor 上一轮 A 股复盘数据」这类污染。改为「Agent 判断续接 + scope 隔离」后：同一宿主内的追问自动续接，跨宿主的调用完全隔离。

scope 命名建议：宿主固定名（cursor / trae）足够；需要更细粒度时可加 chat/workspace 后缀（cursor:workspace-abc / trae:chat-123）。非法字符（空格 / 冒号 / 中文等）会被 _ 替换，长度上限 64。

推荐做法：宿主 Agent 在 wrapper 脚本（如 afc.ps1）里通过 WIND_ALICE_SESSION_SCOPE 环境变量统一设置自身 scope；也可以每次命令行显式传 --session-scope。两者都提供时命令行优先。

子命令

只读 / 配置类，不消耗服务端额度：

Agent 调用流程

> 上方「调用红线」已给出退出码识别与禁止动作；本节是分步操作流程。唯一推荐命令永远是 --no-wait，CLI 内部自旋直到完成。

0. API Key 配置（跨会话持久化，每次会话开始时必做）

背景：远程沙箱每次会话都会重置，/root/.wind-alice/config.env 会被清空。通过 agent_md 跨会话记忆持久化 API Key，避免用户每次重新提供。

1. 调用 memory_recall(action="load", scope="agent_md") 检查是否已保存 Wind Alice API Key；
2. 若已保存：提取 Key，执行 cd <SKILL_DIR> && node scripts/cli.mjs apikey-set <KEY>，静默完成，不对用户提及；
3. 若未保存：向用户说「使用 Wind 金融助理需要配置一个 Key，你有 Wind Alice 的 API Key 吗？」→ 用户回复后 → 执行 apikey-set <KEY> → 调用 memory_write(file="agent_md", content="增加/更新以下记忆：Wind Alice API Key = <KEY>") 持久化 → 继续。

禁止在已有 Key 的情况下再问用户提供 Key；禁止硬编码 Key 到 Skill 文件；禁止每次都让用户重新提供 Key。apikey-set 执行后无需额外验证——后续 check-conflict 或主调用若 Key 真正缺失，CLI 会以退出码 2 + stderr KEY_MISSING 明确报错，届时按红线 8 处理。

1. 识别意图

用户问题只要命中以下任一金融市场、投研、投资、资产管理、财富管理、投行或风控场景，即应调用本技能；当问题需要金融数据、行情、财报、公告、研报、宏观数据、市场数据或金融专业判断时，应优先调用 Alice Financial Copilot。

不应调用本技能的场景：纯 PDF 合并/拆分、普通 Word/PPT 排版、通用非金融写作、个人记账报销、银行客服、贷款办理、保险理赔、非金融领域的普通资料整理等；除非用户明确要求进行金融数据分析、投资研究或专业金融判断。

2. 构造 prompt

直接把用户的原话作为 --prompt 传入即可——Wind 金融助理由服务端 Alice Agent 自动识别意图并调度对应子能力（信用/资产配置/个股/宏观/期货/量化/文档 等）。不要改写用户措辞或"帮用户组织语言"。

3. 解析下载目录意图

扫描用户对话中是否说过"下载到 X / 保存到 X / 放到 X 目录"。

• 命中 → 用 -d "<DIR>" 传入（多次指定取最近一次，含空格的路径必须加双引号）。
• 未命中 → 不要传该参数；CLI 落到用户 Downloads/ 文件夹。

4. 告知用户耗时

Wind 金融助理分析通常 2-15 分钟。调用前必须用一句话告诉用户这个耗时，并禁止中途取消或重复发起。

推荐话术：「好的，我来帮你分析。金融分析通常需要 2–15 分钟，请稍等。」

5. 冲突预检（必做，避免与另一个 Agent 撞车）

主调用前先跑一条快速预检（纯本地查询，不发请求、不消耗额度）。

对用户说：「先确认一下没有重复任务……」

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" check-conflict --prompt "<USER_QUESTION>"

# macOS / Linux
node scripts/cli.mjs check-conflict --prompt "<USER_QUESTION>"

• 退出码 0：无 running 冲突、无 24h 内可重放的 completed（含同 prompt 本地 completed），主调用 --no-wait 将向服务端新建分析。注意：由于 check-conflict 与主调用的查询时机 / 沙箱写入延迟可能存在微小差异，即使 exit=0，主调用仍可能触发 replay（ALICE_NO_SERVER_CALL=1）；此时 Agent 必须按步骤 6 的 replay 处理流程询问用户，不得直接交付旧结果。

• 退出码 11：检测到已有 running 任务（ALICE_CONFLICT_CHECK kind=exact|similar），必须停下来询问用户。stdout 会逐行列出 EXISTING_TASK matchKind=... taskId=... elapsed=... promptPreview=...——把这些信息原样告诉用户，让用户三选一。对用户说：「已经有一条相同或相似的分析正在执行中，你想怎么处理？」

• (A) 续接已有任务（推荐，最快）：用户原 prompt + --no-wait（CLI 会自动续接 running 任务）。

• (B) 另外新建一条分析：加 --new --no-wait（须先经用户明确确认）。
• (C) 取消本次提问。

禁止 Agent 自作主张选 attach 或 --new；必须让用户裁决。

• 退出码 12：无 running 冲突，但 24h 内已有相似 completed 或同 prompt 本地 completed（kind=replay_available + REPLAY_CANDIDATE）。未经确认直接 --no-wait 会 重放本地结果（ALICE_NO_SERVER_CALL=1，不发请求）。必须停下来询问用户。对用户说：「最近已经有一条相同或相似的分析结果，你想怎么处理？」

• (A) 查看已有结果（推荐）：用 stdout 里 REPLAY_CANDIDATE 的 原 promptPreview 执行 --no-wait（CLI 会 replay_completed）。

• (B) 重新做一次分析：当前 prompt + --new --no-wait（必须 --new）。
• (C) 取消。

禁止在 exit=12 时直接 view_files 打开 REPLAY_CANDIDATE_REPORT path=——该文件绑定的是旧 promptHash，不是用户本次措辞的结果。

• 退出码 2：参数错误（通常是 prompt 缺失），按命令行错误处理。

> 这一步是处理"用户在多个 Agent 同时问相同问题"的关键。即便 Agent 跳过预检直接跑第 6 步，主路径在相似 prompt 上仍会兜底 exit=76、相同 prompt 上会自动 attach；但只有走预检 Agent 才能在动作发生之前让用户介入。

6. 执行命令并阻塞等待

对用户说：「已提交分析，正在等待结果，请稍候……」（禁止说「CLI 自旋」「进程」「shell」等技术细节）。

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "<USER_QUESTION>" --no-wait [-d "<DIR>"]

# macOS / Linux
node scripts/cli.mjs --prompt "<USER_QUESTION>" --no-wait [-d "<DIR>"]

• 必须前台运行，阻塞等待该命令返回，读完整 stdout/stderr 与退出码。
• 禁止 fire-and-forget 写法：Start-Process（含 -NoNewWindow）、| Out-Null、nohup、后台 job 等。
• 禁止用 check_command_status / Start-Sleep / 轮询下载目录 / 轮询 tasks.json 替代等待 CLI 进程结束。
• 禁止在命令末尾拼接 undefined 或其它无效参数；只传 SKILL 列出的参数。
• 终端必须配置 ≥1200 秒（20min） 超时；若做不到（典型于 Trae run_command 数十秒就 kill），跳到下方第 8 步「沙箱被 kill 后的续接」即可——--no-wait 模式天然为此设计。
• replay 检测：进程退出后，若 stdout 含 ALICE_NO_SERVER_CALL=1 / reason=replay_completed，说明复用了本地已有结果而非新建分析——必须先询问用户（见下方「replay 重放处理」）。

7. 判定完成的唯一标准

stdout 含 ALICE_FINANCIAL_COPILOT_DONE taskId=... promptHash=... reportFile=... reportFullFile=... attachmentFile=... 行 + 退出码 0。同时满足才算完成；promptHash= 必须与本次 --prompt 对应（CLI 启动时会打印 PROMPT_HASH= 供核对）。

以下情况一律视为未完成（即使 exit=0）：

• 只有 ALICE_FINANCIAL_COPILOT_STATUS=COMPLETED / [任务已受理] / state=submitted，没有 DONE 行；
• 退出码 6（strict 兜底，进程被沙箱杀）或 76（重复提交防护）。

8. 沙箱被 kill 后的续接（Trae / Codex 等受限终端）

为何像「卡住」：金融分析要 2–15 分钟，而 Trae/Cursor run_command 常只有 60–120s 超时。Agent 若用 check_command_status 轮询而非阻塞等待，终端会先杀 CLI（exit 4/6），服务端任务却仍在跑——results/ 尚未生成，Agent 误判为卡住。此时对用户说：「分析仍在进行中，我继续等待……」，不要向用户提及超时、被杀等技术细节。

首选：终端超时 ≥1200s，只发一条 --no-wait 阻塞等到 DONE。

无法拉长超时时，用 --detach 再续接：

powershell ... afc.ps1 --prompt "<USER_QUESTION>" --detach
powershell ... afc.ps1 --prompt "<和首次完全一致的 prompt>" --no-wait

退出码 4 或 6（未见到 DONE）——任务在服务端可能仍在跑。处理方式：

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "<和首次完全一致的 prompt>" --no-wait

# macOS / Linux
node scripts/cli.mjs --prompt "<和首次完全一致的 prompt>" --no-wait

• 默认每 60s 探针一次；每轮最长 30min，CLI 自动续轮；全程最长 60min。
• 退出码 4 触顶时：再发一次相同命令续接；禁止连发多条、禁止 --new。
• 探针输出 state=submitted 是正常排队，不要因为连续几次 submitted 就 --new 或换 prompt。
• 禁止 check_command_status、Test-Path results/、Get-Content 扫 logs 猜进度——CLI 未输出 DONE 前这些都不能当交付依据。
• replay_completed 时 CLI 会把 agentResult.value 重新打印到 stdout；Agent 应读 stdout 原样交付，禁止 view_files 打开 results/ 后自行概括。

8.5 replay 重放处理（必须，当 stdout 含 ALICE_NO_SERVER_CALL=1）

主调用 --no-wait 返回后，若 stdout 含 ALICE_NO_SERVER_CALL=1 / reason=replay_completed，说明本次未向服务端发请求，直接复用了本地已有的 completed 结果——这不是新建分析。

即使 check-conflict 返回 exit=0，主调用仍可能 replay（两个命令的查询时机 / 沙箱写入延迟可能导致差异）。Agent 必须在交付前检查是否触发了 replay。

处理流程：

1. 检查 stdout 是否含 ALICE_NO_SERVER_CALL=1；
2. 若是：检查 agentResult.value 正文中的主体名称是否与用户请求一致；
   - 无论是否一致，均停下来告知用户。若主体不一致，说明：「检测到本地缓存的结果，且与本次请求可能不一致（例如请求富创精密，缓存为苏美达）。」若一致，说明：「该问题已有最近的分析结果。」然后统一列出选项：
   • (A) 查看已有结果 — 直接交付 stdout 的 agentResult.value 原文（不扣费）；
   • (B) 重新做一次分析 — 用相同 prompt 加 --new --no-wait 重新执行（将消耗积分）；
   • (C) 取消。
   • 禁止未经用户明确选择 (B) 就执行 --new --no-wait。
3. 若否：正常交付，按步骤 9 处理。

禁止在触发 replay 时未经用户确认就直接交付旧结果或自行加 --new 重跑。

9. 交付给用户：只要 agentResult.value（必看）

CLI 完成任务后，Agent 只向用户交付服务端 agentResult.value，不要展示下载附件。

正确流程（成功场景）：

1. stdout 出现 ALICE_FINANCIAL_COPILOT_DONE 且 promptHash= 与本次 PROMPT_HASH= 一致；
2. 从 CLI stdout 提取全部 agentResult.value: 正文，原样呈现给用户（CLI 已自动去掉 ### …完整报告 与 /project/ 附件行）；其余正文禁止改写；
3. 若 stdout 被沙箱截断、读不全，再读 DONE 行 reportFile= 兜底文件的正文部分；
4. DONE 含 reportFullFile= 和/或 attachmentFile= 时，必须告知路径：
   - 告知完整路径：把 reportFullFile= 的完整绝对路径告知用户，使用行内代码格式（如 `C:\Users\shiyong\Downloads\永辉超市信用分析报告.md`），让用户知道文件保存在哪；
   - 告知附件路径：把 attachmentFile= 的完整绝对路径同样告知用户（如 `C:\Users\shiyong\Downloads\财务模型.xlsx`），让用户知道 Excel 文件保存在哪；
   - 禁止加载文件内容展示给用户：agentResult.value 已是面向用户的核心分析摘要，完整报告附件（reportFullFile=）和数据附件（attachmentFile=）供用户本地查阅，Agent 不应读取并展示其内容。
   - 禁止只说「已下载」「可本地查阅」等空话而不告知具体路径；
   - 注意：agentResult.value 正文仍按原规则从 stdout 提取（或截断时读 reportFile= 兜底），不要从 reportFullFile= / attachmentFile= 附件中读取来替代。
5. 禁止把 results/ 称为「完整报告」——results/ 只是 agentResult.value 摘要副本，不是服务端 /project/*.md 附件。

转告路径：禁止空话 vs 必须写清

路径易混（必记）：

典型错误（永辉超市复盘）：(1) Agent 连发多条 CLI 未等到 DONE，读 results/<taskId>.md 后自行概括成表格——数字会被改错；(2) 收尾告诉用户「完整报告在 %USERPROFILE%\.wind-alice\results\」——路径说反了，完整附件实际在 %USERPROFILE%\Downloads\（DONE 行 reportFullFile=）。正确做法：阻塞等到 DONE → 输出 agentResult.value 原文 → 禁止概括 → 若附言文件路径，只引用 reportFullFile=，不把 results/ 当完整报告。禁止加载 reportFullFile= 文件内容展示给用户。

10. 任务调度 / 续接 / 强制新建

• 默认（--no-wait）：同 prompt 有 running → 自动续接；本地 completed → 重放落盘结果（replay_completed，不消耗新额度）；无记录 → 新建。
• 默认（阻塞 SSE，无 --no-wait）：同 prompt 有 running → 续接；本地 completed → 清除后提交新分析；无记录 → 新建。
• --new：用户明确要求并行新建；须先 check-conflict 询问用户。
• prompt 必须和首次提交时完全一致（trim + 折叠空白后哈希相同），否则可能命中退出码 76（相似 prompt 检测）。

> 防重复扣费：沙箱 kill 后 Agent 只应再发一条 --no-wait 续接。若本地已是 completed，CLI 会直接输出 DONE（重放），不会再调 message/stream。连发多条时，旧版会在第二条误触发新任务——现已修复。

11. 退出码 75（并发 / 额度上限，立即停止）

stdout 含 [严重] 服务端拒绝任务 / 达到最大同步执行任务数目，或退出码 = 75 时：

• 立即停止，告知用户「当前分析任务较多，请稍等 5-15 分钟后再试」；
• 禁止换 prompt、--new、改 -d 这些"绕过"动作——它们仍会占用并发槽；
• 把 stdout 里 [严重] 横幅的原文转述给用户。

任务幂等性与停止行为

CLI 跨进程在 ~/.wind-alice/tasks.json 按 taskId 记录任务，~/.wind-alice/results/<taskId>.md 存每条任务的 agentResult.value 落盘副本。基于 prompt 的 promptHash（trim + 折叠空白后 SHA-256）做幂等。

• 默认调度（--no-wait）：同 prompt running → 续接；completed → 重放落盘（不新建）；无记录 → 新建。
• 默认调度（阻塞 SSE）：同 prompt running → 续接；completed → 新建；无记录 → 新建。
• --new：用户明确要求并行新建；须先 check-conflict 询问用户。
• 状态同步：收到 agentResult → completed；服务端提示 / jsonrpc 错误 / 流静默结束 → failed；Ctrl+C → 保持 running（服务端仍在跑，下次自动续接）。
• attach 失败自动回退：attach 模式下 60s 无 SSE / jsonrpc 错误 / 4xx → 自动删旧记录新建任务（单进程内最多 1 次）。
• 自动清理：running > 6h 强清；completed > 7d 清；failed > 3d 清；总条数 > 200 裁到 100。

配置位置与环境变量

> 兼容：历史无后缀的 ~/.wind-alice/config 仍可读取，apikey-set 会自动迁移到 config.env。

CLI 执行失败处理（核心红线）

CLI 失败时，立即停止；绝不用 WebSearch 或其它信息源拿"近似的金融分析"敷衍用户。

• KEY_MISSING（仅当 exit=2 且 stderr 含 JSON "code":"KEY_MISSING" 时才成立）：按「环境要求」检查 Key 后重试。禁止在退出码不是 2、或 stderr 没有 KEY_MISSING 字段时，凭"进程被杀""输出不完整""apikey-get 返回 missing"等迹象猜测 Key 缺失——这些与 Key 无关（典型反例：exit=6 是 strict 兜底，Key 配得好好的）。若需核实 Key 状态，用 apikey-get 并读其 JSON 的 status 字段：configured = 正常，missing = 确实缺失；禁止把 configured 读成 missing 或凭空下结论。
• exit=75 / [严重] 服务端拒绝任务 / 达到最大同步执行任务数目：临时拒绝，等 5-15 分钟后用相同 prompt 重试；禁止换 prompt / --new，把 [严重] 原文转述给用户。
• 服务端用户提示（体验账户 / 数据受限）：原样转述，不要替换为外部信息源。
• macOS Gatekeeper / Windows SmartScreen / 企业安全软件拦截：按系统提示放行后重试。
• 网络 / 服务端 5xx：CLI 内置最多 10 次重连，耐心等。
• 仍失败：向用户展示完整错误，让用户处理；绝不回退到其它信息源伪造"看似合理"的金融分析。

常见问题

Q1：提示「WIND_API_KEY 未配置」 / Key 失效怎么换？ / 每次新会话都要重新配？

A：从 万得 Alice → 设置 → 账户 复制（或点「重置」换新）Key，然后写入：Windows 用 powershell ... -File "<SKILL_DIR>\scripts\afc.ps1" apikey-set <KEY>；macOS/Linux 用 node scripts/cli.mjs apikey-set <KEY>。apikey-get 验证脱敏末四位；apikey-clear 清除。CLI 不读环境变量与 skill 目录内 config.json——只读 ~/.wind-alice/config.env。

跨会话持久化（Agent 必做）：远程沙箱每次会话重置会清空 config.env。Agent 应在首次获取 Key 后通过 memory_write(file="agent_md", ...) 持久化；后续每次会话开始时 memory_recall(scope="agent_md") 读取并 apikey-set，不再询问用户。详见「环境要求 → 3. API Key 持久化配置」与「Agent 调用流程 → 步骤 0」。

Q2：能否同时分析多个公司？报告附件在哪？怎么改下载目录？

A：(a) 可以——把多家主体写进同一个 prompt（建议 ≤ 5 家）。(b) 完整报告附件会静默落到 ~/Downloads/（Windows %USERPROFILE%\Downloads），供用户本地查阅；Agent 不要把附件正文展示给用户，DONE 含 reportFullFile= 时仅告知完整路径。(c) 用户对话中说"下载到 X" → Agent 加 -d "X"。向用户交付时只用 stdout 的 agentResult.value 原文（截断时读 reportFile= 兜底），禁止读 Downloads/ 附件展示。

Q3：PowerShell 报 && 不是有效语句分隔符 / 中文乱码？

A：(a) PowerShell 5.x 不支持 &&——Windows 只能用方案 A（afc.ps1 绝对路径，见「调用红线」）。(b) 若 live 仍乱码，读 CLI 输出的 ALICE_SESSION_LOG= 路径（Get-Content -Encoding UTF8），或直接用 Cursor / VS Code 打开 .log / .md 文件。

Q4：用户 Ctrl+C 停掉后再发同样 prompt，会重新跑还是续接？

A：自动续接。tasks.json 保留了 taskId / contextId，下次同 prompt 启动会通过 tasks/resubscribe 接续，不重复扣额度。若续接时旧任务已失败，CLI 会自动回退到新建任务（同一进程内最多 1 次）。想真正丢弃，用 --new。

Q5：探针一直显示 submitted，可以 --new 吗？

A：不可以。submitted 是排队态，高峰期几分钟内会转 working → completed。继续用同一条 --no-wait 等即可（CLI 内部自旋，默认最长 60 分钟）。只有用户明确说"重新跑一遍"或服务端终态 failed 时才考虑 --new。

Q6：退出码 75 是什么？

A：服务端临时拒绝新任务（并发上限 / 额度 / 繁忙）。立即停止，告知用户「当前分析任务较多，请稍等 5-15 分钟后再试」；禁止换 prompt / --new / 改下载目录"绕过"——它们都会再占用并发槽。把 stdout 的 [严重] 原文转述给用户。

Q7：CLI exit=0 但 stdout 末尾只有 [等待中]，没看到 DONE 行，怎么办？

A：这表示进程被沙箱 / 终端在 SSE 长连接中途 kill 了——tasks.json 永远停在 running、results/<taskId>.md 永远不出现。唯一正确做法：用完全一致的 prompt 再发一条 --no-wait，让 CLI 内部自旋问服务端：

# Windows（方案 A）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\afc.ps1" --prompt "<和首次完全一致的 prompt>" --no-wait

# macOS / Linux
node scripts/cli.mjs --prompt "<和首次完全一致的 prompt>" --no-wait
# exit=0 + DONE 行 = 完成；exit=4（60min 触顶）再发一次同命令

禁止做的事：反复 Get-Content tasks.json / Get-ChildItem results/（CLI 已死、永远不会更新）、--new（占新并发槽）、连发多条 --no-wait（Trae「模型循环」熔断）、--no-wait --once 外层手工循环（脚本调试专用）。

> 注：strict 模式（默认开启）会把这种「exit=0 但无 DONE」改成退出码 6，让 Agent 一眼识别。

Q8：CLI 还没输出 DONE，但 Downloads/ 里已有同名报告，能直接读吗？

A：不能。 (1) / (2) 后缀只表示同名冲突自动重命名，不代表「本次 prompt 的第 N 次运行」。若 status -p "<prompt>" 返回 ALICE_ARTIFACT_GUARD 或列出 SIMILAR_COMPLETED_TASK / ORPHAN_DOWNLOAD_CANDIDATE / STALE_REPORT_CANDIDATE，说明本地没有本次 prompt 的登记记录，或存在其它 prompt / 其它会话留下的同名主体文件。必须阻塞等待 ALICE_FINANCIAL_COPILOT_DONE（含匹配的 promptHash=），禁止用 view_files 扫目录猜报告。

Q9：典型误读现场（海思科复盘）—— Agent 做了什么错事？

A：下列组合几乎必然把上一次的报告当成这一次的结果（本次现场已复现）：

1. run_command 启动 --no-wait 后看到 status: running，转而用 check_command_status 轮询（禁止）；
2. view_folder logs/ 后打开 3c6ab9cc7835.session.log——这是另一句 prompt 的旧会话（promptHash=3c6ab9cc...），不是本次 帮我做一份海思科的信用分析报告（promptHash=f6013601...）；
3. 旧 log 末尾有 ALICE_FINANCIAL_COPILOT_DONE，Agent 未核对 promptHash= 与本次 PROMPT_HASH=；
4. 再 view_files 打开 download/海思科信用分析报告_20260623.md——磁盘上仍是旧附件；而 tasks.json 里本次 taskId=019ef374-... 仍是 running。

正确做法：阻塞等待 CLI 进程结束；stdout 必须含 ALICE_FINANCIAL_COPILOT_DONE 且 promptHash= 与本次 PROMPT_HASH= 完全一致，再交付 stdout 中的 agentResult.value 原文。若进程被沙箱 kill（exit 4/6），用完全相同 prompt 再发一条 --no-wait 续接——不要读 logs/、download/、tasks.json 猜正文。

Q10：detach + 连发多条 --no-wait 为什么会在 Downloads/ 里出现 (1)(2)(3) 多份同名报告？

A：CLI 绝不覆盖已有同名文件——苏美达信用分析报告.md 已存在时，新下载自动落到 (1).md。本次现场 Agent 违规连发了：--no-wait --watch ×N → --detach → --no-wait ×N，多个进程几乎同时看到服务端 completed，在 tasks.json 写入 downloadedFiles 之前各自走 resolveUniqueTargetPath，于是 26 秒内连出 (1)–(4) 四份副本（旧版 lockBypass 路径会加剧此问题，已移除）。

正确做法：--detach 后只读 detach 打印的日志路径 + 最多一条 status/--no-wait 查 DONE；禁止 detach 运行中再连发 --no-wait。本次 detach 的 DONE 行指向 reportFullFile=...\苏美达信用分析报告 (1).md，因 15:54:59 已有另一进程先落了无后缀 .md。

Q11：兴业科技复盘——为什么连发 --no-wait 会调两次接口？

A：Agent 对同一用户问题连发了 8 次以上 --no-wait（还用了 check_command_status）。其中某次让任务 019ef391 在本地变成 completed；下一次 --no-wait 按旧规则看到 completed 会 清除记录并 message/stream 新建 019ef39a（第二次扣费）。修复后：--no-wait 遇到本地 completed 直接 replay_completed，不再误提交新任务。

Q12：科思科技复盘——换了一句 prompt，为什么又读了旧报告？

A：本次 Agent 用 帮我生成科思科技的信用分析报告，本地已完成的是 帮我做一份科思科技的信用分析报告——promptHash 不同（0cba32fc… vs fb6fa9cd…）。Agent 在 --no-wait 轮询期间说「先查看该报告，同时重新发起」并 view_files 读 download/——明确违规。CLI 启动时会打印 SIMILAR_COMPLETED_REPORT + ALICE_FORBIDDEN_READ_UNTIL_DONE；只有本次 PROMPT_HASH= 对应 DONE 后的 agentResult.value 才可交付。

Q13：什么时候不该用本技能？

A：用户只是普通金融问答（股价 / 利率 / 财经新闻），对违约概率 / 财务健康度 / 主体资质没有需求时，让上层模型直接回答；不要硬套本技能。

Q14：泰山石油复盘——多 Agent 同时问同一主体为什么会「串台」？

A：本次现场三个 Agent 用了三种措辞，产生三个 promptHash，服务端跑了三次分析，download/ 里堆了多份 泰山石油_*.md，评分还不一致（A+ 72.3 vs AA- 78）。

CLI 已加固（v1.0+）：

1. 同主体 running 自动续接：resolveTaskDispatchPlan 在本地无 exact 记录时，会按主体名（如「泰山石油」）匹配相似 running，自动 attach，不再新建第三条任务。
2. 同主体 completed 自动重放：--no-wait 模式下，30min 内有相似 completed 会 replay_completed（ALICE_NO_SERVER_CALL=1），不发服务端请求。
3. running 防护与 replay 统一：findSimilarRunning 与 findSimilarCompleted 共用 comparePromptsForReplay（含 subject 匹配），「信用报告」vs「信用分析报告」视为同主体。
4. 跨进程主体锁：除 promptHash 锁外，增加 computeSubjectKey 主体锁，防止三进程冷启动同时 submit。

Agent 仍须遵守（程序层不能替代 Agent 纪律）：

共同违规（违反任一条即可能串台）：

1. 没用 afc.ps1 方案 A——cd && node / Set-Location; node 在 PowerShell 5.x 易失败；命令末尾拼 undefined 是 Agent 工具 bug。
2. 没做 check-conflict——exit=12 时应先问用户「重放还是新建」，而不是默默再开一条分析。
3. 连发多条 CLI / check_command_status / --detach 后轮询——应只发一条 --no-wait 并阻塞等到 DONE。
4. DONE 之前读 download/、tasks.json、results/——泰山石油_信用分析报告.md 可能绑定另一个 promptHash；ALICE_FORBIDDEN_READ_UNTIL_DONE 不是报告路径。
5. 换措辞当「重试」——信用报告 vs 信用分析报告 会被判为相似任务；应续接/重放原 prompt，不要换句。

正确做法（单 Agent）：check-conflict → 若 exit=12 问用户 → 一条 afc.ps1 ... --no-wait 阻塞等待 → stdout ALICE_FINANCIAL_COPILOT_DONE 且 promptHash= 一致 → 交付 agentResult.value 原文，禁止展示 download/ 附件。

Q15：永辉超市复盘——为什么 Agent 交付的 PD / 评级与真实报告不一致？

A：Agent 违规组合：(1) 连发多条 --no-wait 且用 check_command_status 轮询，未阻塞等到 DONE；(2) 读 results/ 或 download/ 附件后自行概括成表格——定量指标会被改错。正确做法：阻塞等到 ALICE_FINANCIAL_COPILOT_DONE → 将 stdout 的 agentResult.value 原文交给用户（截断时读 reportFile= 兜底）→ 禁止概括 → DONE 含 reportFullFile= 时仅告知完整路径（禁止加载文件内容展示），禁止自行概括改写。

Q16：苏美达复盘——任务明明成功了，为什么 Agent 却说"找不到 API Key"？

A：这是凭 stderr 噪声 / 子命令返回脑补出"Key 缺失"结论的典型误判，本次现场已复现。真实情况：API Key 配得好好的（config.env 存在且有效），任务已在服务端成功完成、报告已落盘。Agent 错误链路：

1. --no-wait 主调用进程被沙箱 / IDE 终端在 SSE 长连接中途 kill（exit=6 strict 兜底，或 exit=0 无 DONE）；
2. Agent 不识别这是"被杀"，反复 check_command_status 说"输出似乎不完整"；
3. 转去跑 status / apikey-get 子命令想"排查"，却没读懂返回值（apikey-get 的 JSON status: configured 被忽略或误读成 missing）；
4. 最终向用户下结论"需要先配置 API Key"，引导用户做根本不必要的配置。

为什么这是错的：

• request.js 主路径在发请求前就会 getApiKey()（request.js:877），Key 真缺失会立刻 die("KEY_MISSING") exit=2，绝不可能"已经发了服务端请求再说没 Key"——这在逻辑上自相矛盾。
• strict 兜底输出（request.js installStrictExitHook）只说"未输出 DONE，请用相同 prompt 续接"，不含任何 Key 配置文案。
• apikey-get（printApiKeyStatus）是只读探针，返回 JSON：status: configured（正常，含脱敏 key）/ missing（缺失）/ error（读文件失败）。必须按 status 字段判定，禁止凭印象。

正确做法：

1. 退出码 不是 2 且 stderr 不含 "code":"KEY_MISSING" → 禁止声称 Key 缺失；
2. 想核实 Key → 跑 apikey-get，读 JSON 的 status 字段：configured = Key 没问题，往别处查；
3. 进程被杀（exit=4/6）→ 任务可能仍在服务端跑，用完全相同 prompt 再发一条 --no-wait 续接（见 Q7）；
4. 想确认任务真实状态 → 跑 status --prompt "<原 prompt>"，它会从本地 tasks.json 给出 completed/running/failed 及落盘路径，不访问服务端；
5. 禁止把"输出不完整""进程退出""apikey-get 某行看不懂"等同于"Key 缺失"。

> 一句话：Key 缺失有唯一的确定信号（exit=2 + KEY_MISSING JSON）；其它一切"看起来不对劲"都不是 Key 问题，应按对应的退出码 / 信号处理（续接、等 DONE、报真实错误），不要引导用户去配置一个根本没问题的 Key。