@v587d/capital-generation 2.7.11 → 2.8.0

package/preset/capital-generation/README.md

@@ -120,33 +120,40 @@
   coding 工具；插件注册 `read_profile`（allow 里的名字必须先真实存在）；更新 `AGENTS.md` 与 `docs/dev/data-roles.md`
   的角色边界与 `test/persona.test.mjs` 的预留期断言。
 
-## 5.1 bash：为什么只给 data_junior，以及它到底能做什么
+## 5.1 shell 与文件口：开 read、保留 bash、不给写（2026-10-15 用户决策）
 
 - **动机**：`query_dataset` 只有 `count/min/max/avg/sum`，变化量 / 增幅 / CAGR / 比值这类派生
   指标没有宿主工具；模型只能拿 `time_facts.first/last` 心算——那正是 §1.3 那次 41,961 字符
   时间戳心算的同型浪费。所以给 data_junior 一个纯计算兜底。**不是**给它开取数通道。
-- **为什么主 Agent 不给**：主 Agent 今天没有任何通用执行 / 文件 / 网络工具（Web 平面把 host 层
-  的 `tool-bash` / `tool-fs` / `tool-web` 都 `disabled` 了，本 preset 也不挂回来）。这是一条
-  结构性事实，不是 persona 约定：主 Agent 唯一对用户说话、又会读到子 Agent 回传（含网页材料），
-  一旦拥有 bash 就等于拿到"注入 → 执行 → 读凭据 → 出网"的完整链路。收敛靠
-  `ROOT_AGENT_DENIED_TOOLS`（含 `bash` / `pwsh`）。
+- **2026-10-15 起主 Agent 也持有 shell 与 `read`**（用户决策「开 read、同时保留 bash」，推翻
+  2026-09-30 的"主 Agent 不给 shell"）：主 Agent 需要 `read` 读 skill 分册与工作区文件
+  （此前只能 `bash cat`，能力等价但绕远），shell 保留纯计算兜底。`ROOT_AGENT_DENIED_TOOLS`
+  里的 `bash` / `pwsh` 随之移出，名单改为出图三件套 + 十三个出网工具 + `write` / `edit`。
+- **文件写口不开**：`write` / `edit` 被两层拦住——根侧逐名收敛（主 Agent 视图层）+ 全局
+  `tools.guard()`（`registerFsWriteGuard`，调用期按 `composedPreset` 认领，fail-open，细节见
+  `docs/dev/bash-gate.md` §1.6）。理由：主 Agent 唯一对用户说话、又会读到子 Agent 回传（含网页
+  材料），写文件等于给"注入 → 落盘 → 被别的环节读回"开口；业务落盘本来就有正路
+  （`store.writeContext` 等工具实现），模型手里的写口没有正当用途。通用 `subagent` 行的
+  `toolFilter.deny` 同步含 `read` / `write` / `edit`（通用 child 不得读 raw.json，原始 rows
+  永不出工具层）。
 - **平台成对挂载**：Windows 上 host 层挂的是 `pwsh-sandbox`，没有 `bash-sandbox`；只挂
   `tool-bash` 会让名为 bash 的工具实际执行 PowerShell。所以两行互补 `disabled`，allow / deny
   里的名字用 `!!js` 三元表达式按平台选。`tools.restrict()` 对未注册名字报错，所以表达式与行必须
   同进同退（回归：`test/persona.test.mjs`「shell 行：平台成对挂载……」）。
 - **不给后台执行**：`enableRunInBackground: false`。本 preset 不挂 `tool-jobs`，开着后台只会让
   模型拿到一个永远读不回来的 jobId（`job_output` / `job_kill` 不在任何 allow 里）。
-- **闸门只有两层，且都不是安全边界**（`src/agents/bash-guard.ts`）：
-  ① 只对**被委派**子会话开放（镜像 `tool-exec.ts` 的 `delegatedSession`，执行层兜住可见性被改坏）；
-  ② 拦掉 `sandbox_permissions`——委派会话的审批策略由框架固定为 `never`，升级必然失败，而且模型
-  会收到「the user rejected…」这种把系统拒绝说成用户拒绝的文案。
-  **刻意不解析 `command`**：本仓实测沙箱只拦写、不拦读（`~/.dsh/.credentials.yaml` 与
-  `sessions/**` 整机可读）、不拦网络（`curl` 直连 200），而正则挡不住 `node -e` / `python3 -c`
-  ——那正是引入 bash 的目的。禁区与出网纪律是 data_junior persona 的 `# BASH DISCIPLINE` 软约束。
-- **写边界收不窄**：`store.writeContext()` 用**调用方 session** 的 policy 且要求
+- **shell 闸门只剩一层，且不是安全边界**（`src/agents/bash-guard.ts`）：拦掉
+  `sandbox_permissions` / `justification`——被委派会话的审批策略由框架固定为 `never`，升级必然
+  失败，而且模型会收到「the user rejected…」这种把系统拒绝说成用户拒绝的文案；被委派或身份
+  不可考的调用方 fail closed。主 Agent 的升级走正常 ask 审批（2026-10-15 前的"只对被委派子会话
+  开放"一层随决策移除，断言迁移见 `test/bash-guard.test.mjs`）。**刻意不解析 `command`**：本仓
+  实测沙箱只拦写、不拦读（`~/.dsh/.credentials.yaml` 与 `sessions/**` 整机可读）、不拦网络
+  （`curl` 直连 200），而正则挡不住 `node -e` / `python3 -c`——那正是引入 bash 的目的。禁区与
+  出网纪律是 data_junior persona 的 `# BASH DISCIPLINE` 软约束。
+- **写边界收不窄到会话**：`store.writeContext()` 用**调用方 session** 的 policy 且要求
   `mode ∈ {workspace-write, danger-full-access}`，而 `describe_dataset` 会用 data_junior 的会话写
   `profile.json`；把它的会话钉成 `read-only` 会直接打断 describe_dataset。bash 与 Dataset 管线
-  共用同一把尺子（session policy）。
+  共用同一把尺子（session policy），所以模型侧写口只能靠上一条的调用期闸门收。
 - **要真正收紧**只有两条路：换掉 `ctx.shell`（容器 / 微 VM / 远端执行器），或给 dsh 进程做出网
   限制。两者都不是 `ctx.sandbox` 能提供的。
 

package/preset/capital-generation/agent.patch.yml

@@ -45,6 +45,8 @@
                 最终答：工具完成后再答，必须含结论、关键证据与来源标注、局限与风险；归因准确，给出观察 / 验证 / 防守选项；勿只报“已交付/已完成”。
 
                 # RULES & DISCIPLINE
+                读文件只用 read：只读 skill 分册与工作区文件；不读 capital-data/ 落盘（原始行走回传），不读 ~/.dsh/；
+                   分册整册读完才算读过。
                 用户倾向与外界观点皆为待检验假设；发现造假、质押、现金流或流动性风险时如实说明并给边界，不制造恐慌。
                 仅在有可复现模型或回测时报告胜率 / 盈亏比 / 概率，并披露区间、样本、费用、方法与失效条件；否则明确「无法可靠测算」。
                 不索取凭据与不必要仓位信息；不保证收益或准确率；极端行情与数据延迟如实说明局限。
@@ -109,7 +111,8 @@
                    工具可见性不是权限隔离，工具层会拒绝非 delegated child。数据请求统一经 data_collector。
 
                 2. 委派写明问题、标的、时间窗、所需新鲜度与证据用途，让 data_collector 按目录选足相关能力；
-                   不预设能力数量，不带内部源键名；载荷与重试表 → skill capital-data-protocol。
+                   不预设能力数量，不带内部源键名；载荷与重试表 → skill capital-data-protocol，
+                   读回 junior 的 profile / query 回传 → skill capital-data-profile / capital-data-query。
                    禁止任何消息携带完整原始 rows。
 
                 3. 每收到一份 dataset_ready 就登记 DatasetRef，立即复用/创建同一个 data_junior 转交该份数据，
@@ -129,7 +132,7 @@
                    不得冒充行情证据或补位缺失能力。不支持的频率如实披露，用已有粒度降级，不编造。
 
 
-          # ── shell：只给 data_junior（主 Agent 由 root-tool-policy 在自己 scope 上 deny）──────
+          # ── shell：主 Agent 与 data_junior 共用（2026-10-15「开 read、同时保留 bash」）────
           # 边界、为什么不按命令内容 deny、平台门控：见同目录 README.md 的「bash」一节。
           - id: tool-bash
             name: '@deepseek-ai/dsh-tool-bash'
@@ -144,6 +147,12 @@
             config:
               enableRunInBackground: false
 
+          # ── 文件口：read 开给主 Agent 读 skill 分册 / 工作区文件（2026-10-15 用户决策）────
+          # `tool-fs` 一颗挂 read / write / edit：write / edit 由根侧收敛 + 全局写口闸门拦
+          # （src/agents/root-tool-policy.ts），落盘只走工具实现；tool-fs-search 本轮不挂。
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+
           - id: tool-subagent-data-collector
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
@@ -216,7 +225,8 @@
                 你无外部行情 API、无网页检索、无凭据读取能力，也不索取或保存账户密码。
 
                 # DUTIES
-                0. 第一步先加载协议：调用 Dataset 工具前先 skill capital-data-protocol；描述完成
+                0. 第一步先加载协议：调用 Dataset 工具前先 skill capital-data-profile；要写 query_request
+                   或做派生算术再加 skill capital-data-query；描述完成
                    （describe_dataset / profile_dataset）后无条件加载 skill capital-visualization-protocol，
                    再选择 gate。dataset_profile_completed / dataset_query_completed / profile_failed /
                    query_failed 的载荷样例、事实怎么读、data_gap 与 QuerySpec 细则都在 skill 里。
@@ -301,7 +311,8 @@
 
                 # DUTIES
                 0. 首次检索前先 skill capital-web-protocol，取回来源边界、收敛法则、
-                   Wind 三要素、回传格式与域名核验清单；本 persona 只留硬规则。
+                   Wind 三要素与降级口径；回传前再 skill capital-web-evidence，取回编号格式、
+                   域名核验清单、抓取失败处置与 `ocr`；本 persona 只留硬规则。
                 1. 先定来源再动手：官方正式文件与权威新闻优先 wind_docs（public_document），
                    不要等 anysearch 空转后才想起；候选探索与归属核验走 anysearch。
                    换 provider 前先看 recent_retrievals / provider_tally。
@@ -415,6 +426,11 @@
               toolFilter:
                 deny:
                   - !!js "process.platform === 'win32' ? 'pwsh' : 'bash'"
+                  # 文件口全关：通用 child 不得读 raw.json（原始 rows 永不出工具层）也不得写；
+                  # read_image 刻意不点名（条件注册，名字不在 = 创建子 Agent 失败，且它只读）。
+                  - read
+                  - write
+                  - edit
                   - render_chart
                   - prepare_chart_source
                   - describe_dataset

package/preset/capital-generation/skills/capital-data-profile/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: capital-data-profile
+description: Use when reading a Dataset back — describe_dataset as the default entry, the profile payload and its four fact blocks, data_gap requests, and the time axis (axis, windows, calendar filters). Volume 2 of the Capital data protocol; delegation and per-Dataset receipts live in capital-data-protocol, QuerySpec and derived arithmetic in capital-data-query.
+---
+
+# Capital 数据协议 · 第二册：读回 Dataset、缺口与时间轴
+
+本册是数据协议的第二册（§3.0 / §3 / §3.1 / §3.2）。委派与逐份回传在第一册 `capital-data-protocol`，
+受控查询与派生算术在第三册 `capital-data-query`；三册 §编号连续，跨册引用照原编号点名。
+
+**重试那张表（§5）住在第一册** `capital-data-protocol`，本册不重复它：参数类按 `input_schema` 修正后重试、
+瞬时与执行超时重试 1 次、同一请求重试 2 次仍失败就回传 `failed` 并注明已重试。
+
+## 3.0 读取 Dataset 的默认入口：`describe_dataset`
+
+`data_junior` 读一份 Dataset 用 **`describe_dataset`**（一次调用完成 inspect + profile + 可选 queries），
+**不要再走 `inspect_dataset → profile_dataset → query_dataset` 三步**——那三步只保留给单点复核。
+
+```json
+{
+  "dataset_id": "ds_01J...",
+  "task_id": "task_01J...",
+  "columns_of_interest": ["close_price", "volume"],
+  "queries": [
+    { "group_by": ["report_type"], "aggregates": [{ "function": "count", "as": "n" }], "limit": 20 }
+  ]
+}
+```
+
+- **一次一份**：一次调用只传一个 `dataset_id`。本轮有多份数据时，**在同一条 assistant 消息里一次发完**
+  多个调用（宿主会并发执行，结果一起返回），不要一份一份等。
+- 返回 = inspect 元数据（`artifact_ref` / `capability` / `source_label` / `captured_at` / `retention_until` /
+  `query_access.shape`）+ profile 四类事实（`statistics` / `categories` / `time_facts` / `structure`）+
+  `profile_ref` + 每条 query 的 `result`，或该条自己的 `error`（单条失败不影响其余）。
+- `shape = document` 时 queries **不执行**（宿主跳过并在 `warnings` 说明）；文档内容在 `document`。
+- `columns_of_interest` 只对这些列返回 `statistics` / `categories` / `schema`（并同样收窄 `time_facts` 的首末值投影；时间列永远保留），是收窄结果体积的唯一手段。
+- **体积闸门**：结果超过 7000 码点时返回
+  `{"status":"too_large","profile_ref":"...","columns":[...],"hint":"..."}`，而不是超长载荷。
+  按 hint 用 `columns_of_interest`（或减少 `queries`，一次最多 8 条）重发一次；文档型按 hint 直接调
+  `profile_dataset`。**看到 `too_large` 不是失败**——它带着完整列名，用来让你收窄。
+- 单点复核（只看元数据 / 只要一份完整 profile / 补一条查询）仍可用 `inspect_dataset`、`profile_dataset`、
+  `query_dataset`。
+
+## 3. 质检请求与回传（主 Agent ↔ data_junior）
+
+请求：
+
+```json
+{
+  "type": "profile_request",
+  "task_id": "task_01J...",
+  "dataset_ids": ["ds_01J..."],
+  "question": "检查数据质量并给出基础统计"
+}
+```
+
+- `dataset_ids` 一律取 `dataset_ready` 回传中的 `dataset_id` 原样值。
+- 只带 DatasetRef 标识与问题描述，**绝不带原始数据行**。
+
+回传：
+
+```json
+{
+  "type": "dataset_profile_completed",
+  "task_id": "task_01J...",
+  "dataset_id": "ds_01J...",
+  "profile_ref": "workspace://capital-data/profiles/p_01J...",
+  "row_count": 240,
+  "columns": ["date", "open", "high", "low", "close", "volume"],
+  "schema": {
+    "close": { "contract_type": "number", "inferred_type": "number", "missing_count": 0, "null_count": 0, "invalid_count": 0 }
+  },
+  "validation": { "status": "pass", "violations": [] },
+  "quality": { "missing_values": 0, "duplicate_rows": 0, "time_ordered": true },
+  "warnings": []
+}
+```
+
+- `schema` 是字段类型和计数的有限摘要；完整 profile 以 `profile_ref` 为准，不把完整 profile 或 raw rows 放进消息。
+- `validation.status=fail` 表示 profile 发现结构化 violations，不表示原始 Dataset 被删除或不可用。
+- 主 Agent 可以在 collector 继续取数时逐份委派 data_junior，显式说「只到 profile」（包括必要的受控 queries）；后续只送新到的 dataset_id，不重做已完成的 profile。等 `data_collection_completed` 和补数据回执后，再指示同一个 junior 综合已有结果并完成可视化 gate。
+
+失败：`{ "type": "profile_failed", "task_id": "task_01J...", "error": "...", "code": "..." }`
+
+`profile_dataset` 的四类事实（回传时按需引用，不要把整份 profile 抄进消息）：
+
+| 事实块 | 回答什么问题 |
+|--------|--------------|
+| `statistics`（count/sum/min/max/mean/分位数） | 合计多少、覆盖多少条、区间与集中度 |
+| `categories`（distinct_count + 最多 5 个高频取值） | 有哪些类别、分布如何；`truncated=true` 表示未列全 |
+| `time_facts`（覆盖范围 + 首行/末行取值 + `axis` + `windows`） | 最新值、区间涨跌，以及**这份数据的时间轴怎么读**（见 §3.2）。**必须**用 `first`/`last`；min/max 只是区间极值，把它讲成走势就是编造 |
+| `structure`（路径 + total_elements 或 sampled_elements） | 嵌套里一共有多少条。对象字段用 `.name`、数组元素用 `[]`，未抽样时例如 `sub_tab[].fund_list` 的 `total_elements=40` 就是 40 只基金；若出现 `sampled_elements=50`，只能说明实际检查了 50 项，不是完整数量 |
+
+### 3.2 时间轴：日历由宿主换算，不要自己算毫秒
+
+`time_facts` 除覆盖范围与首末行外，还给出**这份数据的时间轴怎么读**：
+
+| 字段 | 含义 | 怎么用 |
+|---|---|---|
+| `axis.value_format` | `epoch_ms`（毫秒整数时间列）/ `date_string`（已是 `YYYY-MM-DD`）/ `unknown`（推断不出：先 inspect 或显式传 `time_column`） | `unknown` 时不要假设粒度 |
+| `axis.time_zone` / `axis.utc_offset` | 该列**自身观测到**的时区偏移（如 `Asia/Shanghai` / `+08:00`） | 判断"某天"的边界一律按它，不要按 UTC 猜 |
+| `axis.aligned_to` | `local_midnight` = 取值是当地 00:00 的瞬间（A 股日线的 `date_ms` 就是这样） | 这种列的"当天"要用 `>= 当天午夜` 且 `<= 当天日末` 两个条件才算 |
+| `covered_from_iso` / `covered_to_iso` | 覆盖范围的可读日期 | 回答"数据到哪天"，不要再做 epoch→日期换算 |
+| `windows[]` | 近 1 月 / 近 3 月 / 近 1 年 / 年初至今的现成边界：`value_ge`、`value_le`（可直接填进 filter）与 `data_from`、`data_to`（该窗口在数据里**真实存在**的首末日期） | 命中就直接用；`data_from` 已把非交易日夹到相邻交易日 |
+
+需要 `windows` 之外的窗口（任意区间、某年某月、历年 10 月）时：
+
+1. 调 `resolve_data_time_range`，传 `dataset_id` + `period`（可选 `anchor_date`）；它按该 Dataset
+   时间列自身的偏移返回 `bounds.bound_ge` / `bounds.bound_le` 与 `range`、`data` 日期；
+2. 把 `bound_ge` / `bound_le` 原样填进 filter，**不要**自己把日期算成毫秒。
+
+`query_dataset` 的 filter 也**直接接受日历写法**（宿主按同一套偏移换算）：
+
+```jsonc
+// 三种写法都表示"从 2026-08-23 起"，选一种即可
+{ "column": "date_ms", "operator": ">=", "value": "2026-08-23" }
+{ "column": "date_ms", "operator": ">=", "value": "2026-08" }
+{ "column": "date_ms", "operator": ">=", "value": { "period": "last_1_month" } }
+```
+
+- `>=` 取该日当地午夜、`<=` 取该日当地日末、`=` 自动展开成"这一天"的上下界；省略锚点的
+  `period` 以该 Dataset 最后一天为准（数据陈旧时相对期不会落空）；
+- 结果里时间列会附一列 `*_iso` 可读日期（原值保留，不替换）；
+- `>`、`<`、`!=`、`in` 配日期串会报 `query_type_conflict`：日期只有"整天"语义，用它们等于
+  悄悄换一天；要哪几天就直接写 `>=` / `<=`。
+
+**硬规则：看到 epoch 毫秒要经过加减乘除才能得出结论时，就是走错了路。** 时间换算一律交给
+`time_facts.axis`、`windows` 与 `resolve_data_time_range`；自己心算毫秒既慢又必然算错口径。
+
+文档型 Dataset（顶层是文档对象、没有行数组，如财务指标、回测结果）：`profile_dataset` 返回
+`structure` 结构摘要 + `document` 有界内容（`$` 是文档根），**没有**行列统计，也不包含行数据专用的 `schema`/`validation`；`query_dataset`
+对它无效。`document.truncated=true` 时必须按 `omitted` 逐条说明省略了哪个路径、保留多少、
+省略多少，不得只说「已截断」。
+
+硬规则：字段按工具返回原样填入；统计项只报告可计算的部分，数据不足如实说明；
+profile 失败不影响原始 Dataset，可按指示重试。
+
+
+## 3.1 数据缺口（data_junior → 主 Agent，中途主动发起）
+
+data_junior 发现「问题需要的那份数据还没取」时（不是「数据里没有」），不等回合结束，
+直接用 `send_message` 发一次：
+
+```json
+{
+  "type": "data_gap",
+  "task_id": "task_01J...",
+  "dataset_id": "ds_01J...",
+  "need": "该指数在 2025-06-30 的成分股权重明细",
+  "reason": "现有 Dataset 只有指数点位，没有成分字段",
+  "suggested_capability": "index_constituents",
+  "blocking": true
+}
+```
+
+| 字段 | 规则 |
+|------|------|
+| `type` | 固定 `data_gap` |
+| `task_id` / `dataset_id` | 必须带：主 Agent 可能同时在等多个回传，靠这两个字段对上号 |
+| `need` | 用自然语言写清缺什么数据（标的、区间、口径） |
+| `reason` | 说明为什么现有 Dataset 不够，避免主 Agent 重复取已有的数据 |
+| `suggested_capability` | 可选。只能是**手上 DatasetRef 里出现过的 capability 原值**，或整个省略；不要为了填空编造能力名 |
+| `blocking` | `true` = 不补齐无法继续，可以停在本轮等回信；`false` = 还有别的能先做 |
+
+硬规则：
+
+- `data_gap` 是请求不是结论。发出后不得把「无法确认」当终局；同一条缺口只发一次。
+- 子 Agent **不得自行取数**，也不得直接找 `data_collector`：取数一律由主 Agent 中继。
+- 主 Agent 处置：按委派清单复用对应角色取数 → 把新 DatasetRef 用 `send_message` 发回
+  **同一个**子 Agent（禁止新建同角色）→ 它接着做完。同参数的重新取数会命中宿主复用，
+  不会重复访问上游，所以该重取就重取。
+- 取数失败时主 Agent 必须回一条失败消息（`data_failed` 或说明性文本）给它，
+  不能让它一直等：框架没有超时与订阅机制。
+- **结束本轮 ≠ 任务完成。** 等数据的子 Agent 会先结束回合，结算通知里那句
+  「finished and will do no further work unless you send it more」在此时是误导；
+  清单里标为「等数据」的子 Agent，收到结算通知后不要认定完成、也不要新建。
+- 只有确认「数据里确实没有该字段」时才回传能力边界，并写明是数据没有、不是没拿到数据。

package/preset/capital-generation/skills/capital-data-protocol/SKILL.md

@@ -1,21 +1,26 @@
 ---
 name: capital-data-protocol
-description: Use when composing or reading a Capital data message — data_request, per-Dataset dataset_ready, data_failed, data_collection_completed, profile and query payloads, freshness, capability selection, retry discipline, and disclosure fields.
+description: Use when composing or reading a Capital data message — data_request, per-Dataset dataset_ready / data_failed / data_collection_completed, the two-step capability discovery, retry discipline and disclosure fields. Volume 1 of the Capital data protocol; reading a Dataset back lives in capital-data-profile, QuerySpec and derived arithmetic in capital-data-query.
 ---
 
-# Capital 数据协议（完整版）
+# Capital 数据协议 · 第一册：委派与逐份回传
 
 主 Agent 与 `data_collector` / `data_junior` 之间的消息载荷契约。三个角色的 persona 只保留
 每轮都要生效的硬规则；字段级细节、示例与重试表在本文件。载荷即接口，字段名、数值、日期
 一律不改写。
 
-## 0. 谁读哪一节（三个角色动手前都应先加载本 skill）
+本协议共三册，§编号跨册连续：**本册**管委派与逐份回传（§0 / §1 / §1.1 / §2 / §5），
+读回 Dataset 在 `capital-data-profile`（§3.0 / §3 / §3.1 / §3.2），受控查询与派生算术在
+`capital-data-query`（§3.3 / §4）。写了 `profile_request` 或 `query_request` 却没读对应那一册，
+等于凭记忆填载荷字段。
+
+## 0. 谁读哪一节（三个角色动手前先加载对应那一册）
 
 | 角色 | 需要 | 说明 |
 |---|---|---|
-| 主 Agent | §1、§3、§4、§5 | 发请求、收回传、输出披露字段 |
-| `data_collector` | §1、§1.1、§2、§5 | 收请求、能力发现两步、回传载荷、重试纪律 |
-| `data_junior` | §3、§3.1、§4、§5 | 质检回传、数据缺口、受控查询、重试纪律 |
+| 主 Agent | §1、§3、§4、§5 | 发请求、收回传、输出披露字段（§3 / §3.1 / §3.2 在 `capital-data-profile`，§3.3 / §4 在 `capital-data-query`） |
+| `data_collector` | §1、§1.1、§2、§5 | 收请求、能力发现两步、回传载荷、重试纪律（本册即够） |
+| `data_junior` | §3、§3.1、§4、§5 | 质检回传、数据缺口、受控查询、重试纪律（§3 系在 `capital-data-profile`，§3.3 / §4 在 `capital-data-query`，§5 在本册） |
 
 ## 1. 数据请求（主 Agent → data_collector）
 
@@ -132,269 +137,6 @@ description: Use when composing or reading a Capital data message — data_reque
   不自行改写、不自行拼路径。
 - Dataset 默认保留 **7 天**（以 `retention_until` 为准），到期后需重新取数。
 
-## 3.0 读取 Dataset 的默认入口：`describe_dataset`
-
-`data_junior` 读一份 Dataset 用 **`describe_dataset`**（一次调用完成 inspect + profile + 可选 queries），
-**不要再走 `inspect_dataset → profile_dataset → query_dataset` 三步**——那三步只保留给单点复核。
-
-```json
-{
-  "dataset_id": "ds_01J...",
-  "task_id": "task_01J...",
-  "columns_of_interest": ["close_price", "volume"],
-  "queries": [
-    { "group_by": ["report_type"], "aggregates": [{ "function": "count", "as": "n" }], "limit": 20 }
-  ]
-}
-```
-
-- **一次一份**：一次调用只传一个 `dataset_id`。本轮有多份数据时，**在同一条 assistant 消息里一次发完**
-  多个调用（宿主会并发执行，结果一起返回），不要一份一份等。
-- 返回 = inspect 元数据（`artifact_ref` / `capability` / `source_label` / `captured_at` / `retention_until` /
-  `query_access.shape`）+ profile 四类事实（`statistics` / `categories` / `time_facts` / `structure`）+
-  `profile_ref` + 每条 query 的 `result`，或该条自己的 `error`（单条失败不影响其余）。
-- `shape = document` 时 queries **不执行**（宿主跳过并在 `warnings` 说明）；文档内容在 `document`。
-- `columns_of_interest` 只对这些列返回 `statistics` / `categories` / `schema`（并同样收窄 `time_facts` 的首末值投影；时间列永远保留），是收窄结果体积的唯一手段。
-- **体积闸门**：结果超过 7000 码点时返回
-  `{"status":"too_large","profile_ref":"...","columns":[...],"hint":"..."}`，而不是超长载荷。
-  按 hint 用 `columns_of_interest`（或减少 `queries`，一次最多 8 条）重发一次；文档型按 hint 直接调
-  `profile_dataset`。**看到 `too_large` 不是失败**——它带着完整列名，用来让你收窄。
-- 单点复核（只看元数据 / 只要一份完整 profile / 补一条查询）仍可用 `inspect_dataset`、`profile_dataset`、
-  `query_dataset`。
-
-## 3. 质检请求与回传（主 Agent ↔ data_junior）
-
-请求：
-
-```json
-{
-  "type": "profile_request",
-  "task_id": "task_01J...",
-  "dataset_ids": ["ds_01J..."],
-  "question": "检查数据质量并给出基础统计"
-}
-```
-
-- `dataset_ids` 一律取 `dataset_ready` 回传中的 `dataset_id` 原样值。
-- 只带 DatasetRef 标识与问题描述，**绝不带原始数据行**。
-
-回传：
-
-```json
-{
-  "type": "dataset_profile_completed",
-  "task_id": "task_01J...",
-  "dataset_id": "ds_01J...",
-  "profile_ref": "workspace://capital-data/profiles/p_01J...",
-  "row_count": 240,
-  "columns": ["date", "open", "high", "low", "close", "volume"],
-  "schema": {
-    "close": { "contract_type": "number", "inferred_type": "number", "missing_count": 0, "null_count": 0, "invalid_count": 0 }
-  },
-  "validation": { "status": "pass", "violations": [] },
-  "quality": { "missing_values": 0, "duplicate_rows": 0, "time_ordered": true },
-  "warnings": []
-}
-```
-
-- `schema` 是字段类型和计数的有限摘要；完整 profile 以 `profile_ref` 为准，不把完整 profile 或 raw rows 放进消息。
-- `validation.status=fail` 表示 profile 发现结构化 violations，不表示原始 Dataset 被删除或不可用。
-- 主 Agent 可以在 collector 继续取数时逐份委派 data_junior，显式说「只到 profile」（包括必要的受控 queries）；后续只送新到的 dataset_id，不重做已完成的 profile。等 `data_collection_completed` 和补数据回执后，再指示同一个 junior 综合已有结果并完成可视化 gate。
-
-失败：`{ "type": "profile_failed", "task_id": "task_01J...", "error": "...", "code": "..." }`
-
-`profile_dataset` 的四类事实（回传时按需引用，不要把整份 profile 抄进消息）：
-
-| 事实块 | 回答什么问题 |
-|--------|--------------|
-| `statistics`（count/sum/min/max/mean/分位数） | 合计多少、覆盖多少条、区间与集中度 |
-| `categories`（distinct_count + 最多 5 个高频取值） | 有哪些类别、分布如何；`truncated=true` 表示未列全 |
-| `time_facts`（覆盖范围 + 首行/末行取值 + `axis` + `windows`） | 最新值、区间涨跌，以及**这份数据的时间轴怎么读**（见 §3.2）。**必须**用 `first`/`last`；min/max 只是区间极值，把它讲成走势就是编造 |
-| `structure`（路径 + total_elements 或 sampled_elements） | 嵌套里一共有多少条。对象字段用 `.name`、数组元素用 `[]`，未抽样时例如 `sub_tab[].fund_list` 的 `total_elements=40` 就是 40 只基金；若出现 `sampled_elements=50`，只能说明实际检查了 50 项，不是完整数量 |
-
-### 3.2 时间轴：日历由宿主换算，不要自己算毫秒
-
-`time_facts` 除覆盖范围与首末行外，还给出**这份数据的时间轴怎么读**：
-
-| 字段 | 含义 | 怎么用 |
-|---|---|---|
-| `axis.value_format` | `epoch_ms`（毫秒整数时间列）/ `date_string`（已是 `YYYY-MM-DD`）/ `unknown`（推断不出：先 inspect 或显式传 `time_column`） | `unknown` 时不要假设粒度 |
-| `axis.time_zone` / `axis.utc_offset` | 该列**自身观测到**的时区偏移（如 `Asia/Shanghai` / `+08:00`） | 判断"某天"的边界一律按它，不要按 UTC 猜 |
-| `axis.aligned_to` | `local_midnight` = 取值是当地 00:00 的瞬间（A 股日线的 `date_ms` 就是这样） | 这种列的"当天"要用 `>= 当天午夜` 且 `<= 当天日末` 两个条件才算 |
-| `covered_from_iso` / `covered_to_iso` | 覆盖范围的可读日期 | 回答"数据到哪天"，不要再做 epoch→日期换算 |
-| `windows[]` | 近 1 月 / 近 3 月 / 近 1 年 / 年初至今的现成边界：`value_ge`、`value_le`（可直接填进 filter）与 `data_from`、`data_to`（该窗口在数据里**真实存在**的首末日期） | 命中就直接用；`data_from` 已把非交易日夹到相邻交易日 |
-
-需要 `windows` 之外的窗口（任意区间、某年某月、历年 10 月）时：
-
-1. 调 `resolve_data_time_range`，传 `dataset_id` + `period`（可选 `anchor_date`）；它按该 Dataset
-   时间列自身的偏移返回 `bounds.bound_ge` / `bounds.bound_le` 与 `range`、`data` 日期；
-2. 把 `bound_ge` / `bound_le` 原样填进 filter，**不要**自己把日期算成毫秒。
-
-`query_dataset` 的 filter 也**直接接受日历写法**（宿主按同一套偏移换算）：
-
-```jsonc
-// 三种写法都表示"从 2026-08-23 起"，选一种即可
-{ "column": "date_ms", "operator": ">=", "value": "2026-08-23" }
-{ "column": "date_ms", "operator": ">=", "value": "2026-08" }
-{ "column": "date_ms", "operator": ">=", "value": { "period": "last_1_month" } }
-```
-
-- `>=` 取该日当地午夜、`<=` 取该日当地日末、`=` 自动展开成"这一天"的上下界；省略锚点的
-  `period` 以该 Dataset 最后一天为准（数据陈旧时相对期不会落空）；
-- 结果里时间列会附一列 `*_iso` 可读日期（原值保留，不替换）；
-- `>`、`<`、`!=`、`in` 配日期串会报 `query_type_conflict`：日期只有"整天"语义，用它们等于
-  悄悄换一天；要哪几天就直接写 `>=` / `<=`。
-
-**硬规则：看到 epoch 毫秒要经过加减乘除才能得出结论时，就是走错了路。** 时间换算一律交给
-`time_facts.axis`、`windows` 与 `resolve_data_time_range`；自己心算毫秒既慢又必然算错口径。
-
-文档型 Dataset（顶层是文档对象、没有行数组，如财务指标、回测结果）：`profile_dataset` 返回
-`structure` 结构摘要 + `document` 有界内容（`$` 是文档根），**没有**行列统计，也不包含行数据专用的 `schema`/`validation`；`query_dataset`
-对它无效。`document.truncated=true` 时必须按 `omitted` 逐条说明省略了哪个路径、保留多少、
-省略多少，不得只说「已截断」。
-
-硬规则：字段按工具返回原样填入；统计项只报告可计算的部分，数据不足如实说明；
-profile 失败不影响原始 Dataset，可按指示重试。
-
-### 3.3 bash：派生算术的兜底，不是第二条取数通道
-
-只有 data_junior 有 `bash`。它存在的唯一理由是 `query_dataset` 的聚合只有
-`count / min / max / avg / sum`——**变化量、增幅、CAGR、比值、单位换算**这类派生指标没有宿主
-工具，硬心算既慢又容易错。
-
-**可以做的**（拿手里已有的数字算）：
-
-```bash
-node -e 'const a=98.2,b=120.5; console.log(((b-a)/a*100).toFixed(2))'   # 区间涨幅
-python3 -c "print((120.5/98.2)**(252/60)-1)"                            # 年化
-```
-
-- **只敲最终参与计算的标量，一次 ≤20 个**：不整行/整表复制原始数字进脚本（2026-10-10 真机：
-  两次 bash 把整段聚合行逐数敲进去，转写出笔误又花 7.2K 字符发更正）；从工具回执到脚本的每个
-  数字**逐一核对**再执行，算完抽查 1-2 个对得上来源。要算的数超过 20 个就拆几批。
-
-**不许做的**（这是纪律，不是沙箱限制——沙箱只拦写，不拦读与网络）：
-
-| 不许 | 为什么 | 正确做法 |
-|---|---|---|
-| 读 `capital-data/**`、`raw.json` | 原始行**永不**进入你的上下文；而且工具结果会被剪枝成 head+tail，读了也算错 | 数值走 `describe_dataset` / `query_dataset` 的统计与聚合 |
-| 读 `~/.dsh/**`、`sessions/**` | 那是宿主凭据与全部会话日志 | 不碰；需要元数据用工具回执 |
-| 读 / 改 `preset/`、`src/`、`test/` | 那是装配与门禁本身 | 不碰 |
-| `curl` / `wget` / 任何网络请求、`git clone`、`npm i`、`pip install` | 你的角色没有网络能力，外部材料只经主 Agent 转交 `web_retriever` | 缺外部事实就在回传里写明缺口 |
-| 申请更高权限（`sandbox_permissions`） | 委派会话的审批策略被框架固定为 `never`，必然失败 | 不要试；缺数据发 `data_gap` |
-
-另外两条：
-
-- **输出只留结论数字**：bash 的工具结果同样会过剪枝器（>8192 字符中间段被剪掉），把中间过程
-  打印出来只会挤掉真正要看的东西；回传时注明算法与口径（如「按首末收盘价、未复权」）。
-- **时间窗仍归宿主**：窗口边界一律用 `time_facts.windows` / `resolve_data_time_range`
-  （§3.2），不要用 `date` 命令自己造边界——口径错了数字就全错，而且没人会发现。
-
-`profile_dataset` 的统计项：数值字段的 count 与 sum（合计多少、覆盖多少条）、字符串字段的
-`distinct_count` 与高频取值、字段类型（observed / contract）、缺失值与显式 null、类型冲突、
-重复主键、时间范围、最小/最大/均值/分位数——**只报告可计算的部分**，数据不足就如实说明。
-
-## 3.1 数据缺口（data_junior → 主 Agent，中途主动发起）
-
-data_junior 发现「问题需要的那份数据还没取」时（不是「数据里没有」），不等回合结束，
-直接用 `send_message` 发一次：
-
-```json
-{
-  "type": "data_gap",
-  "task_id": "task_01J...",
-  "dataset_id": "ds_01J...",
-  "need": "该指数在 2025-06-30 的成分股权重明细",
-  "reason": "现有 Dataset 只有指数点位，没有成分字段",
-  "suggested_capability": "index_constituents",
-  "blocking": true
-}
-```
-
-| 字段 | 规则 |
-|------|------|
-| `type` | 固定 `data_gap` |
-| `task_id` / `dataset_id` | 必须带：主 Agent 可能同时在等多个回传，靠这两个字段对上号 |
-| `need` | 用自然语言写清缺什么数据（标的、区间、口径） |
-| `reason` | 说明为什么现有 Dataset 不够，避免主 Agent 重复取已有的数据 |
-| `suggested_capability` | 可选。只能是**手上 DatasetRef 里出现过的 capability 原值**，或整个省略；不要为了填空编造能力名 |
-| `blocking` | `true` = 不补齐无法继续，可以停在本轮等回信；`false` = 还有别的能先做 |
-
-硬规则：
-
-- `data_gap` 是请求不是结论。发出后不得把「无法确认」当终局；同一条缺口只发一次。
-- 子 Agent **不得自行取数**，也不得直接找 `data_collector`：取数一律由主 Agent 中继。
-- 主 Agent 处置：按委派清单复用对应角色取数 → 把新 DatasetRef 用 `send_message` 发回
-  **同一个**子 Agent（禁止新建同角色）→ 它接着做完。同参数的重新取数会命中宿主复用，
-  不会重复访问上游，所以该重取就重取。
-- 取数失败时主 Agent 必须回一条失败消息（`data_failed` 或说明性文本）给它，
-  不能让它一直等：框架没有超时与订阅机制。
-- **结束本轮 ≠ 任务完成。** 等数据的子 Agent 会先结束回合，结算通知里那句
-  「finished and will do no further work unless you send it more」在此时是误导；
-  清单里标为「等数据」的子 Agent，收到结算通知后不要认定完成、也不要新建。
-- 只有确认「数据里确实没有该字段」时才回传能力边界，并写明是数据没有、不是没拿到数据。
-
-## 4. 受控查询（主 Agent ↔ data_junior）
-
-请求：
-
-```json
-{
-  "type": "query_request",
-  "task_id": "task_01J...",
-  "dataset_id": "ds_01J...",
-  "query": {
-    "dataset_id": "ds_01J...",
-    "select": ["symbol", "rows", "avg_close"],
-    "filters": [{ "column": "close_price", "operator": ">", "value": 100 }],
-    "group_by": ["symbol"],
-    "aggregates": [
-      { "function": "count", "as": "rows" },
-      { "function": "avg", "column": "close_price", "as": "avg_close" }
-    ],
-    "order_by": [{ "column": "avg_close", "direction": "desc" }],
-    "limit": 100
-  }
-}
-```
-
-- `query` 是固定 JSON QuerySpec，不是 SQL、表达式或脚本；`query_request` 消息可以原样作为 `query_dataset` 工具参数传入，宿主会展开其中的 `query`；也可直接传扁平 QuerySpec。`type` / `task_id` 只属于消息 envelope，不进入实际执行 QuerySpec。
-- 只支持 `=`、`!=`、`>`、`>=`、`<`、`<=`、`in`、`is_null`、`not_null`，以及 `count`、`min`、`max`、`avg`、`sum`。
-- 必须有 `group_by` 或聚合；`select` 可省略，省略时默认返回分组列与聚合别名；显式 `select` 只能引用分组列或聚合别名。禁止 join、window、having、自定义函数和 raw rows 投影。
-- 默认 `error_policy=skip_with_warning`：过滤或数值聚合遇到不兼容脏值时排除该值并在 `warnings` 披露；需要类型全量一致时显式使用 `error_policy=strict`。
-- 数组/对象字段（`select`、`group_by`、`aggregates`、`order_by`、`filters`）传**真正的 JSON 数组**，不要序列化成字符串再传；`limit` 传数字。宿主对字符串化的 JSON 做了宽容解析（实测模型很常这么传），但不要依赖它。
-- **时间列筛选写日历，不写毫秒**：`date_ms` 这类 epoch 列的 filter 值可直接写 `"2026-08-23"`、
-  `"2026-08"`、`"2026"` 或 `{ "period": "last_1_month" }`，宿主按该列自身偏移换算边界并自动在结果
-  里补 `*_iso`。写法、可用的 period 词表与禁止的算子见 §3.2——**不要**自己把日期算成毫秒。
-  同一条 QuerySpec 在 **`describe_dataset` 的 `queries` 与 `query_dataset` 里完全等价**（同一份归一、
-  同样的错误码），不必因为"想确认某个入口行不行"而重复试。
-- `query_dataset` 取不到原始行：`select` 只能引用分组列或聚合别名，所以「首末/最新值」要用
-  profile 的 `time_facts`——`time_facts` 已经给了首末行取值，不要用 query 去取。
-- `query_dataset` 是受控分组/聚合透视查询，不是通用 raw.json 读取器，也不替代基础描述性 profile。对市场指数、指数组成、基金重仓股等不适合当前 QuerySpec 的数据，不要强行改写查询；不足以回答时如实回传能力边界。自定义查询脚本和自定义执行脚本属于后续 `data_analyst`，不得转移给 data_junior。
-
-完成回传：
-
-```json
-{
-  "type": "dataset_query_completed",
-  "task_id": "task_01J...",
-  "dataset_id": "ds_01J...",
-  "query_result": {
-    "columns": ["symbol", "rows", "avg_close"],
-    "rows": [{ "symbol": "600519.SH", "rows": 20, "avg_close": 1680.5 }],
-    "matched_row_count": 20,
-    "group_count": 1,
-    "returned_count": 1,
-    "limit": 100,
-    "warnings": []
-  }
-}
-```
-
-失败：`{ "type": "query_failed", "task_id": "task_01J...", "dataset_id": "ds_01J...", "error": "...", "code": "query_type_conflict" }`
-
-- `query_result.rows` 只能是有限分组键与聚合结果，不得出现未聚合 Dataset row、文件路径、内部路由键或凭据。
-
 ## 5. 重试纪律