Agent 指南

跨层运行协议、真相源优先级、权限与写回边界。如果你是 AI Agent，请优先读取仓库中的 AGENT_GUIDE.md，本页是它的导读。

三层定位：Agent 在每一层能做什么

YMOS 是 Human-in-the-loop 系统，不授权 Agent 自动交易或伪造执行记录：

层	Agent 的工作	禁止
投研层	获取事实、做初始研究、记录来源与失败	把数据形态直接写成个性化交易结论
策略内核层	读取 Profile、分析、发现矛盾、提出建议	替用户设置参数或静默修改稳定内核
操盘层	读取并协助生成计划、门禁与审计 Markdown	代替用户生成已执行、已成交证据

Agents/ 是跨层运行协议，不是四个机器人

Agents/ 定义的是角色协议：谁先读什么、能写哪里、何时算完成。它不会因为文件存在就自动注册任务，也不要求启动四个进程。

MARKDOWN

Market Insight       只看市场，写市场洞察
Investment Radar     把市场事件映射到持仓与 Watchlist
Strategy             按 Profile 和 P 系列分析
Portfolio State      统一状态写回，维护真相源

单 Agent：默认模式是 Single Controller / Multi-Role，一个主控按 ORCHESTRATION.md 的依赖顺序依次扮演四个角色
支持 subagent：可以把四个角色映射成不同执行体，但输入、输出、依赖和唯一写回边界不变
定时任务：提示词必须同时指向角色卡、执行手册和具体 SOP；只写一句「跑投资雷达」不足以激活角色边界

每个任务必须按顺序读取：

MARKDOWN

Agents/<role>-agent.md
  → Agents/EXECUTION_PLAYBOOK.md 对应段落
  → 本次具体 SOP
  → 上游产物与成功条件

❗ 重要

Portfolio State 是唯一 Agent 状态写回者。其他角色再确信也只能「建议改」。Human 通过 Console 确认的真实事件不受这条限制——那是事实来源，不是 Agent 判断。

新会话读取顺序

总入口暗号.md
Brain/策略配置/当前策略_Profile.md（若不存在，读取兼容投影并视为 draft）
持仓与关注/当前关注方向与投资偏好.md（兼容投影，不覆盖当前 Profile）
Brain/买入卖出决策/买卖决策_状态机.md（若存在）
持仓与关注/持仓_状态机.md
持仓与关注/Watchlist_状态机.md
当前任务对应 SOP 和 P 模块

ℹ️ 说明

Strategy Profile 为 draft 时：市场洞察、投资雷达、状态读取和基础事实调研照常运行；不得输出个性化动作建议。动作级请求返回 kernel_not_ready 时，必须把它解释为可恢复的配置状态，并询问用户是否进入快速内核入职——不得只抛状态码。

真相源优先级

事实	真相源
策略与偏好	已获 Human 确认的 Strategy Profile
当前股数、成本、交易状态	`Brain/买入卖出决策/` 单笔生命周期文件
最近价格与账户总览	`买卖决策_状态机.md` 的 `portfolioSnapshot`
持仓/关注身份与研究位置	`持仓_状态机.md`、`Watchlist_状态机.md`
盘前判断和盘中实际	`Brain/交易计划/`
放行与拦截	`Brain/决策审计/`
已提取的执行证据	`Brain/内核审计/优化建议/`
候选认知语料	BrainStorm 与旧投资日志；未审批前不是稳定规则

快照与单笔文件冲突时，以单笔文件为事实源并要求刷新快照。用户口头说的当前仓位，优先级高于状态机里的旧记录——人才是真相源，文件只是人的记账本。

权限边界

类别	范围
允许读取	Eyes、Brain、Agents、BrainStorm 的 SOP 和参考文件；Profile、状态机、个股知识库和运行报告；Console 产生的计划、决策与审计 Markdown
正常流程可写入	Eyes/Brain 的报告目录；用户确认后的个股知识库和身份状态；BrainStorm Raw/Insight 草案；用户确认后的 Profile 与变更提案状态
必须由 Human 操作产生	真实账户资金变动；买入、卖出、加仓、止盈、止损和成交确认；「已经执行」的交易计划记录；规则变更的最终审批

⚠️ 注意

Agent 不得为了让系统看起来闭环而补写这些证据。

Strategy Profile 规则

不从作者案例中复制数值；未填字段保持空白，不发明默认
不创建或激活所谓「通用策略 Profile」；只允许预置 draft、Human 门禁、决策执行分离等结构不变量
不因用户自称某个流派就忽略实际行为证据；发现冲突时展示选择，不替用户拍板
调用 P 模块前必须检查 modules.enabled / disabled / replacements：停用项不读，替换项改读替代模块
P 模块缺少参数时返回 data_incomplete；不得使用文件内示例数值、作者参数或模型常识补齐
Console/rules.json 是 Profile 在操盘层的投影；冲突时以 Human 确认的 Profile 为准

状态驱动分析：别每天全量重跑

日常先读 portfolioSnapshot.accounts / positions / health / agentRouting：

级别	动作
L0	无告警，只输出简报
L1	只打开告警对应的单笔文件
L2	用户明确要求或出现组合异常时才跑完整再平衡

不要每天装载所有单笔文件，也不要在无告警时重跑全部 P 系列。日常持仓分析默认不读取 已平仓/；只有交易复盘、P11 或周期内核审计才读取历史归档。

接到配置或升级请求时：先路由到进阶指南

用户说「帮我配置」「帮我升级」「按我的习惯改」时，必须先完整读取 进阶指南.md，判断需求属于哪一节，再实施：

用户想做什么	先读进阶指南	Agent 的主要动作
配数据源（RSS / Finnhub / Tushare / Market API）	§1	盘点数据缺口；创建/更新 `.env`；测试数据、时间、失败降级
安装问财或其他 Skill	§1 问财部分、§5	使用官方安装说明；配置 `YMOS_SKILL_ROOT`；同时验收宿主注册和 CLI 发现
梳理或升级投资逻辑	§2、§4	先诊断和读取旧日志 / BrainStorm；起草 Profile 或变更提案；参数留给 Human
修改交易计划、门禁或生命周期	§3、§6	从 Profile 投影规则；确认 Human 节点；保持事件只追加
修改 Reader、页面或看板	§3、§6	区分阅读偏好和策略规则；不得让页面成为第二套内核
按个人参数整体升级三层	§6	先整理参数包；分层形成改造清单；分层实施和验收

标准实施流程：

MARKDOWN

理解目标
  → 读取进阶指南对应章节与当前真相源
  → 盘点现状、已知参数、空白和冲突
  → 向 Human 展示分层方案与需要确认的选择
  → 做最小改动
  → 验证正常、空结果、失败和权限边界
  → 把结果与下一步写回约定文档

内核变更协议

每笔平仓后跑平仓复盘归档，把「计划 vs 实际」写入 Brain/内核审计/优化建议/YYYY-MM/。三项与盈亏无关的红旗必须机械检出并记录，赚钱的违规也照记：放宽止损、亏损加仓、绕过门禁。

单笔复盘不修改任何内核文件。积累到重复出现才由周期审计转成变更提案。发现重复错误时先分类：策略正常波动 → 记录不改；执行偏离 → 优先加门禁；规则模糊冲突 → 变更提案；数据问题 → 修驱动。任何内核修改都必须包含反证、复核条件和回滚方案，并由 Human 批准。

失败处理

数据源失败：记录来源、错误和降级，不静默吞掉
Profile 缺失：基础事实流程继续，动作分析降级
状态机缺失：提示通过本地 Console 初始化
快照过期：不能把旧价格写成实时结论
输出路径不存在：只在 SOP 允许的目录内创建
Human 未确认：保留草案或建议，不写真实事实

完成标准

一次任务完成前检查：输入和来源写清；Profile 和事实没有混淆；失败降级可见；产物落到约定路径；不越过 Human 边界；如果修改内核，已有提案、反证与审批；如果配置 Key / Skill，已验证发现、最小调用和无凭据降级，且没有回显 Secret。

💡 提示

Agent 做的是重复劳动（拉数据、扫价格、跑分析链），目的是把用户从信息苦力中解放出来。但投资的认知差来自用户自己的深度研究。Agent 应主动建议用户的深度调研方向，而不是替用户下结论。

完整协议见仓库 AGENT_GUIDE.md、Agents/README.md 与 Agents/ORCHESTRATION.md；定时任务参考见进阶配置。