elexingyu · elexingyu · Jul 20, 2026 · Jul 20, 2026 · Jul 20, 2026 · Jul 20, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,26 @@
 
 QuantCockpit 的重要变更记录在这里。版本遵循 [Semantic Versioning](https://semver.org/)。
 
+## [0.3.0] - 2026-07-20
+
+### Added
+
+- 可先检测仓位文件结构，再自动采用唯一稳定的 Adapter Pack；首批内置 FDC3 Portfolio 2.2 ticker variant 和 CCXT unified contract positions。
+- 可通过统一 `quantcockpit` CLI 完成 adapter 列表/校验、来源检测、draft、身份补全、只读 preview 和显式 import，只有 import 打开数据库写入路径。
+- 未知格式可选用 OpenAI structured output 生成候选 mapping draft；默认请求不含来源值，并支持先以 0600 权限导出完整 payload 审阅。
+- Adapter Pack 使用纯数据 manifest、有限谓词、正反 fixture、稳定 hash 和严格资源边界，社区可以扩展来源而不向核心加入任意代码。
+
+### Boundaries
+
+- AI 不能填写策略、环境、来源、组合或快照时间，不能执行代码或触发导入；候选必须通过本地路径校验、显式身份补全和 preview。
+- FDC3 仅支持 ticker identifier，CCXT 仅支持 contract quantity；quantity-only 数据不能计算价值集中度、Beta 或因子暴露。IBKR Flex Query 因字段可配置，只提供接入 recipe，不宣称任意 CSV 自动兼容。
+- 尚不提供券商直连、成交重建、AI 报告、定时派发、因子 Beta、VaR、压力测试或订单执行。
+
+### Fixed
+
+- 加固候选文件与 AI payload 的原子写入、完整异常链脱敏和终端控制字符转义，避免并发覆盖或外部文本污染本地终端。
+- 将所有 Adapter Pack 资源限制为单文件 1 MiB，并让文档仓位检测固定采样 50 条且复用结果，避免大数组被重复完整遍历。
+
 ## [0.2.0] - 2026-07-20
 
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,15 +39,19 @@ bun audit
 
 ## 贡献仓位适配
 
-优先贡献声明式映射示例，只有现有 CSV / JSON / JSONL 读取器无法表达时才新增代码适配器。每个新适配必须同时提供：
+优先贡献纯数据 Adapter Pack，只有现有 CSV / JSON / JSONL 读取器和有限转换无法表达时，才讨论修改核心读取器。Pack 契约和命令见 [`docs/adapters.md`](docs/adapters.md)。每个新适配必须同时提供：
 
-- 完全合成且不含品牌、账户或真实标的的最小输入夹具；
-- 固定版本的映射配置，以及确定性的 `mapping_profile_hash` 测试；
-- preview 输出测试和正式导入测试，证明 preview 不写数据库；
-- 缺字段、坏数字、重复标的、半写尾行、超限输入和错误脱敏测试；
-- README 接入命令或独立文档入口，并说明数据来源的时间、方向和币种口径。
+- `adapter.json` manifest、无 provenance 的 `profile-draft.json` 和 pack README；
+- 官方或公开的字段语义链接，以及固定的 `source_schema_version`；
+- 完全合成且不含真实品牌账户、账户值或真实交易活动的 positive 与 negative fixture；
+- required / forbidden / weighted 谓词，以及针对最相似错误格式的 false-positive 测试；
+- 能力和限制声明，尤其说明 quantity、weight、market value 与 exposure value 的币种和方向口径；
+- preview 与导入测试，证明检测、draft、finalize 和 preview 都不写数据库；
+- 缺字段、坏数字、重复标的、半写尾行、超限输入和错误脱敏测试。
 
-不要把特定券商 SDK、凭据读取或订单接口塞进通用导入器。适配器的职责是把已有导出文件变成规范 `position_snapshot`，不是控制交易账户。
+运行 `uv run quantcockpit adapters validate ./path/to/pack --json` 后再提交。不要把特定券商 SDK、凭据读取、动态 import、脚本入口或订单接口塞进 pack 或通用导入器。适配器的职责是把已有导出文件变成规范 `position_snapshot`，不是控制交易账户。
+
+`stable` 不是“看起来能用”。它要求公开语义、确定性正反 fixture、误匹配证据和固定边界。字段集合来自用户自定义报表、无法公开复现或仍依赖推断时，请先标记 `experimental`。
 
 ## 报告问题
 

diff --git a/README.md b/README.md
@@ -97,7 +97,50 @@ uv run scripts/import_demo.py --database ./local.duckdb --data-dir ./path/to/jso
 
 ## 零侵入接入现有仓位文件
 
-你不需要改交易策略或接券商 SDK。先导出现有系统已经保存的 CSV、JSON 或 JSONL，再用一个版本化映射配置说明“哪一列是什么”。零侵入不等于零配置：不同机构没有统一的实盘仓位日志结构，QuantCockpit 把适配成本收敛到可审查、可复用的 JSON 配置，而不是散落在交易代码里的胶水逻辑。
+你不需要改交易策略或接券商 SDK。先导出现有系统已经保存的 CSV、JSON 或 JSONL，QuantCockpit 会先做有界结构探测，再从数据化 Adapter Pack 中确定性匹配。零侵入不等于零配置：不同机构没有统一的实盘仓位日志结构，系统只是把适配成本收敛到可审查、可复用的 JSON，而不是让胶水代码散落在交易策略里。
+
+### 两分钟 adapter-first 路径
+
+仓库内置两个有公开语义依据的稳定 adapter：FDC3 Portfolio 2.2 的 ticker variant，以及 CCXT unified contract positions。先检测合成 CCXT fixture，命令只读取文件结构，不写数据库：
+
+```bash
+uv run quantcockpit positions detect src/quantcockpit/adapters/builtin/ccxt-contract-positions-1/fixtures/positive.json --json
+```
+
+自动采用唯一稳定匹配，显式补齐五个业务身份字段，完成预览后保存 profile：
+
+```bash
+uv run quantcockpit positions preview src/quantcockpit/adapters/builtin/ccxt-contract-positions-1/fixtures/positive.json --adapter auto --set strategy_id=portfolio-demo --set environment=paper --set source=ccxt-fixture --set portfolio_id=book-a --set snapshot_time=2026-07-20T09:30:00Z --save-profile ./ccxt-profile.json --observed-at 2026-07-20T10:00:00Z --json
+```
+
+只有下面的 `import` 命令会打开并写入 DuckDB：
+
+```bash
+uv run quantcockpit positions import src/quantcockpit/adapters/builtin/ccxt-contract-positions-1/fixtures/positive.json --profile ./ccxt-profile.json --database ./quantcockpit.duckdb --observed-at 2026-07-20T10:00:00Z --json
+```
+
+`auto` 只接受得分至少 80、领先第二名至少 10 分且状态为 `stable` 的唯一匹配。歧义、低分、experimental 或结构截断都要求人工选择，不会“猜一个能跑的”。完整 pack 契约、贡献方式和 IBKR Flex Query recipe 见 [`docs/adapters.md`](docs/adapters.md)。
+
+### 未知格式的可选 AI draft
+
+当 catalog 没有匹配时，可以先导出即将发送的请求进行人工审阅。这个 dry-run 不初始化 OpenAI client，不需要 API key，也不会上传数据：
+
+```bash
+uv run quantcockpit positions draft examples/positions/demo-positions.csv --ai openai --export-ai-payload ./mapping-request.json --json
+```
+
+默认 payload 只有路径、字段名、类型、计数、截断状态、adapter 候选和严格输出 schema，来源值数量为零。只有同时传入 `--include-samples --allow-data-upload` 才会附带最多 3 行、每行最多 50 个字段的本地脱敏样本。脱敏降低风险，但不是匿名化保证，发送前仍应查看导出的 payload。
+
+需要真实调用时再安装可选依赖并配置供应商密钥：
+
+```bash
+uv sync --extra ai-openai
+uv run --extra ai-openai quantcockpit positions draft examples/positions/demo-positions.csv --ai openai --output ./position-draft.json --json
+```
+
+AI 只能产生未完成的候选 draft，不能填写 `strategy_id`、`environment`、`source`、`portfolio_id`、`snapshot_time`，不能执行代码，也不能触发导入。输出还要经过本地 Pydantic 契约、来源路径校验、身份补全和 preview；核心安装不含云 SDK，无网络和无密钥时仍可完整使用 adapter 与监控功能。
+
+### 手工 profile 路径
 
 先预览合成示例。`--preview` 只读取、校验和输出最多 5 个安全样本，不创建或修改数据库：
 
@@ -170,7 +213,8 @@ curl -fsS 'http://127.0.0.1:8000/api/v1/portfolios/synthetic-book/exposure?strat
 
 ```text
 examples/data/*.jsonl ──────────────┐
-现有 CSV / JSON / JSONL 仓位文件 ─→ 映射配置 + 安全预览
+现有 CSV / JSON / JSONL 仓位文件 ─→ 结构探测 → Adapter Catalog / 可选 AI Draft
+                                             ↓ 人工补齐身份 + 安全预览
                                     ↓ 校验、幂等、修订、隔离
 DuckDB (events / ingestion_runs / quarantine)
         ↓ current 只读查询
@@ -179,7 +223,7 @@ DuckDB (events / ingestion_runs / quarantine)
         └── 本地 Markdown 报告
 ```
 
-- `src/quantcockpit/`：契约、导入、存储、分析、服务、API 与报告。
+- `src/quantcockpit/`：契约、adapter、可选 AI provider、导入、存储、分析、服务、API 与报告。
 - `frontend/`：Vite + React + TypeScript 观察台。
 - `scripts/`：显式本地导入与报告命令。
 - `tests/`：后端、脚本、安全与前端状态测试。
@@ -198,7 +242,9 @@ make verify
 - 策略收益仍按日频事件处理；仓位是离散快照，不是逐笔成交重建，也不负责交易所日历、停牌或节假日语义。
 - 健康阈值是通用默认值，不替代策略自身的运行手册和告警系统。
 - Pearson 相关性只描述选定窗口内的线性共同变化，不代表因果、未来稳定性或组合风险。
-- v0.2 不含券商直连、因子 Beta、VaR、压力测试、告警派发或 AI 报告运行时；当前报告是确定性的本地模板。
+- v0.3 不含券商直连、因子 Beta、VaR、压力测试、告警派发或 AI 报告运行时；当前 AI 只辅助生成映射 draft，报告仍是确定性的本地模板。
+- FDC3 adapter 只支持 `instrument.id.ticker + holding`；CCXT adapter 只支持 unified contract position 的 `symbol + side + contracts`，不把 spot balance 当仓位，也不把 `notional` 猜成基础币种敞口。
+- 只提供 quantity 的来源可以记录方向和数量，但不能据此计算价值集中度、HHI、gross/net value、Beta 或因子暴露。
 - 前端桌面优先，1024px 可用；低于 900px 会给出明确提示，不提供移动布局。
 - Alpha 不保证契约向后兼容；升级前请保留原始输入文件和映射配置。
 
@@ -208,6 +254,6 @@ make verify
 
 ## 贡献、安全与许可
 
-贡献前请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)，安全问题请遵循 [`SECURITY.md`](SECURITY.md)。项目采用 [Apache License 2.0](LICENSE)。
+贡献前请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`Adapter Pack 指南`](docs/adapters.md)，版本变化见 [`CHANGELOG.md`](CHANGELOG.md)，安全问题请遵循 [`SECURITY.md`](SECURITY.md)。项目采用 [Apache License 2.0](LICENSE)。
 
-设计判断与实施记录：[`v0.2 接入设计`](docs/superpowers/specs/2026-07-20-v0-2-position-ingestion-design.md)、[`v0.2 实施计划`](docs/superpowers/plans/2026-07-20-v0-2-position-ingestion.md)、[`v0.1 加固设计`](docs/superpowers/specs/2026-07-20-v0-1-hardening-design.md)、[`v0.1 加固计划`](docs/superpowers/plans/2026-07-20-v0-1-hardening.md) 和 [`Public Alpha 计划`](docs/superpowers/plans/2026-07-20-public-alpha.md)。这些文件保留“为什么这样做”的上下文，实际命令和支持范围以本 README 为准。
+设计判断与实施记录：[`v0.3 Adapter Assistant 设计`](docs/superpowers/specs/2026-07-20-v0-3-adapter-assistant-design.md)、[`v0.3 实施计划`](docs/superpowers/plans/2026-07-20-v0-3-adapter-assistant.md)、[`v0.2 接入设计`](docs/superpowers/specs/2026-07-20-v0-2-position-ingestion-design.md)、[`v0.2 实施计划`](docs/superpowers/plans/2026-07-20-v0-2-position-ingestion.md)、[`v0.1 加固设计`](docs/superpowers/specs/2026-07-20-v0-1-hardening-design.md)、[`v0.1 加固计划`](docs/superpowers/plans/2026-07-20-v0-1-hardening.md) 和 [`Public Alpha 计划`](docs/superpowers/plans/2026-07-20-public-alpha.md)。这些文件保留“为什么这样做”的上下文，实际命令和支持范围以本 README 为准。
diff --git a/SECURITY.md b/SECURITY.md
@@ -12,7 +12,7 @@ Public Alpha 只支持当前默认分支。尚未承诺长期维护窗口或安
 
 ## 威胁模型与部署边界
 
-QuantCockpit 设计为本机只读观察工具：API 默认只监听 `127.0.0.1`，没有认证，也不应直接暴露到公网。仓位源文件只由本地进程读取，不上传到外部服务；DuckDB 保存校验后的规范事件、来源坐标、映射哈希，以及组成快照的原始记录证据。原始记录不会通过当前 API 返回，但导入前仍应删除与监控无关的敏感列。若自行更改监听地址或部署到共享网络，必须另行提供 TLS、认证、授权、速率限制和日志脱敏；这不在 Public Alpha 的支持范围内。
+QuantCockpit 设计为本机观察工具：API 默认只监听 `127.0.0.1`，没有认证，也不应直接暴露到公网。确定性 adapter、结构检测、preview、导入、分析和报告都在本地运行。DuckDB 保存校验后的规范事件、来源坐标、映射哈希，以及组成快照的原始记录证据。原始记录不会通过当前 API 返回，但导入前仍应删除与监控无关的敏感列。若自行更改监听地址或部署到共享网络，必须另行提供 TLS、认证、授权、速率限制和日志脱敏；这不在 Public Alpha 的支持范围内。
 
 请把以下内容视为敏感并保持在 Git 之外：
 
@@ -23,4 +23,8 @@ QuantCockpit 设计为本机只读观察工具：API 默认只监听 `127.0.0.1`
 
 仓库示例只允许固定、完全合成的 `paper` 数据。发现疑似真实数据或密钥时，请停止传播并按漏洞流程私密报告。
 
-当前版本没有运行 AI 助手，也不会把日志或报告发送给模型提供商。未来若加入 AI 摘要，必须采用显式启用、数据最小化、供应商与保留策略可见、可在不配置模型时完整使用核心监控的设计；在这些边界实现并审计前，文档中的“AI 报告”只属于后续方向。
+v0.3 提供可选的 OpenAI 映射助手，但核心安装不包含云 SDK，也不会自动调用 provider。默认 AI payload 只包含结构摘要、adapter 候选和输出 schema，不含来源值；只有同时传入 `--include-samples --allow-data-upload` 才加入最多 3 行本地脱敏样本。脱敏不是匿名化保证，调用前应使用 `--export-ai-payload` 查看将发送的完整 JSON，并自行核对供应商的数据保留、地域和组织策略。
+
+AI 输出是不可信候选：它不能填写五个业务身份字段，不能执行代码，不能直接写 profile 或数据库，也不能触发 import。输出必须再次通过本地严格 schema、来源路径校验、显式身份补全和 preview。API key 只应通过供应商支持的本地环境配置提供，不要放进命令参数、profile、fixture、日志或仓库。
+
+当前 AI 能力只生成 position mapping draft，不生成报告、交易建议或风险结论。没有安装 extra、没有网络或没有 API key 时，adapter、导入、监控与报告仍应完整工作。