# darkline 安装文档

本文档给 darkline 项目管理者和接入方使用。目标是：同事从 git 拉下当前目录后，能导入同一份 seed 数据，并把本地 Codex darkline 技能安装到自己的机器上。

下文所有项目内路径都使用相对路径。执行命令前先进入 darkline 项目根目录。

## 1. 安装结果

安装完成后，本机应具备：

```text
1. MySQL 中存在 darkline 的 dl_ 数据表。
2. Codex 本地 skills 目录中存在 darkline 技能。
3. 使用 darkline 关键字时，AI 会按 darkline 方法论、信息收集、信息存储和案例追踪流程执行。
```

## 1A. darkline 技能是做什么的

`darkline` 技能是 AI 的外部信息分析工作流约束。安装后，AI 在处理暗线、新闻、公告、事件链、证据链、案例分析、K线显影、信息拓扑归档时，会优先按 darkline 流程执行。

它会要求 AI 做这些事：

```text
1. 先判断任务模式：广撒网收集 / 暗线专线追踪 / 方法论验证 / 数据整理。
2. 把新闻和事件当作信息叶子，不直接当结论。
3. 反推暗线意图，且暗线必须是意图 / 目标 / 人心 / 组织意志。
4. 按 B/C -> A -> M -> N/L -> 市场输出 -> 实际结果 -> 总结 讲清楚。
5. 连续追问为什么，不能停在第一个表面解释。
6. 记录证据链、应有之线、影响对象、显影、替代解释和链路状态。
7. 新增案例时，按信息拓扑结构入库和校验。
```

它不会自动保证结论正确，也不会替代人工复核。它的价值是让不同 AI 用同一套流程分析、记录和复核外部信息。

## 2. 项目内关键目录

```text
data/mysql_seed_20260624/              MySQL seed 数据包
scripts/import_darkline_mysql_seed.py  导入 seed 数据
scripts/validate_darkline_install.py   校验数据和技能安装结果
skill_package/darkline/                可复制安装的 Codex 技能包
```

技能安装目录不强制写死。默认使用：

```text
<用户home>/.codex2/skills/darkline
```

如果本机 Codex 使用其他技能目录，安装者可以设置环境变量：

```powershell
$env:DARKLINE_SKILL_DIR="你的技能目录\darkline"
```

后续安装和校验命令都会优先使用 `DARKLINE_SKILL_DIR`。

seed 数据包含这些表：

```text
dl_source_document
dl_case_import_batch
dl_case_record
dl_darkline_hypothesis
dl_case_reasoning_step
dl_expected_line
dl_event_node
dl_evidence
dl_evidence_node_link
dl_impact_target
dl_manifestation_bridge
dl_alternative_explanation
dl_chain_state
```

这些表已经包含 legacy 合规修复后的 `GAP_REVIEW` 标记。同事从零导入 seed 时，不需要再额外执行 legacy 修复脚本；只有维护者后续新增或重新导入旧案例后，才需要重新执行修复。

## 3. 从零安装流程

适用场景：同事本地 MySQL 还没有 darkline 数据。

### 3.1 准备 MySQL

要求：

```text
MySQL 8.x
字符集 utf8mb4
本机能用账号密码连接
```

推荐数据库名：

```text
tianxia
```

如果团队成员不想使用 `tianxia`，也可以在导入和校验命令里通过 `--database` 指定其他库名。

### 3.2 安装 Python 依赖

导入和校验脚本使用 `pymysql`：

```powershell
python -m pip install pymysql
```

### 3.3 导入 darkline seed 数据

在 darkline 项目根目录执行：

```powershell
python scripts\import_darkline_mysql_seed.py --host 127.0.0.1 --port 3306 --user root --database tianxia --create-database
```

脚本会提示输入 MySQL 密码。也可以用环境变量避免在命令行里出现密码：

```powershell
$env:DARKLINE_MYSQL_PASSWORD="你的本机MySQL密码"
python scripts\import_darkline_mysql_seed.py --host 127.0.0.1 --port 3306 --user root --database tianxia --create-database
```

说明：

```text
1. 脚本只导入 dl_ 命名空间表。
2. seed 内的表会按 data/mysql_seed_20260624/schema.sql 重建。
3. seed 数据包不包含任何本机 MySQL 密码。
```

### 3.4 安装 darkline 技能

在 darkline 项目根目录执行：

```powershell
$ProjectRoot = (Get-Location).Path
$SkillSrc = Join-Path $ProjectRoot "skill_package\darkline"
$SkillDst = $env:DARKLINE_SKILL_DIR
if ([string]::IsNullOrWhiteSpace($SkillDst)) {
  $SkillDst = Join-Path $HOME ".codex2\skills\darkline"
}
New-Item -ItemType Directory -Force -Path $SkillDst | Out-Null
Copy-Item -Path (Join-Path $SkillSrc "*") -Destination $SkillDst -Recurse -Force
```

安装后应存在：

```text
<用户home>/.codex2/skills/darkline/SKILL.md
```

### 3.5 校验安装

在 darkline 项目根目录执行：

```powershell
$SkillDst = $env:DARKLINE_SKILL_DIR
if ([string]::IsNullOrWhiteSpace($SkillDst)) {
  $SkillDst = Join-Path $HOME ".codex2\skills\darkline"
}
python scripts\validate_darkline_install.py --host 127.0.0.1 --port 3306 --user root --database tianxia --skill-dir "$SkillDst"
```

输出 `overall_status = PASS` 表示安装成功。

## 4. 已经导入数据的机器怎么装

适用场景：本机已经有 `dl_` 数据，只需要安装或更新技能。

例如本项目管理者本机已经导入过当前 seed，且 `validate_darkline_install.py` 校验通过，就不要重复导入数据包，只需要同步技能。

在 darkline 项目根目录执行：

```powershell
$ProjectRoot = (Get-Location).Path
$SkillSrc = Join-Path $ProjectRoot "skill_package\darkline"
$SkillDst = $env:DARKLINE_SKILL_DIR
if ([string]::IsNullOrWhiteSpace($SkillDst)) {
  $SkillDst = Join-Path $HOME ".codex2\skills\darkline"
}
New-Item -ItemType Directory -Force -Path $SkillDst | Out-Null
Copy-Item -Path (Join-Path $SkillSrc "*") -Destination $SkillDst -Recurse -Force
python scripts\validate_darkline_install.py --database tianxia --skill-dir "$SkillDst"
```

## 5. 新增案例怎么记录

新增案例不能只写故事，必须能进入信息拓扑结构。

新增案例分两层：

```text
最小层：能让人读懂案例，并能在数据库里找到案例入口。
完整链路层：能让后续 AI 或人复盘暗线假设、证据链、应有之线、现实验证、市场显影和替代解释。
```

最低要求：

```text
1. 按 B/C -> A -> M -> N/L -> 市场输出 -> 实际结果 -> 总结 写案例正文。
2. 写入 dl_case_record。
3. 写入 dl_darkline_hypothesis。
4. 写入 dl_chain_state。
5. 至少写 1 条 expected_line，说明如果暗线为真，后续应发生什么。
6. 每次判断变化新增版本，不覆盖旧判断。
```

完整链路要求：

```text
dl_case_record：案例正文、来源、hash。
dl_darkline_hypothesis：反推出的暗线意图，必须是意图/目标/人心/组织意志。
dl_case_reasoning_step：每一步推理和关键“为什么”。
dl_expected_line：M/B/C/N/L 这些应有之线。
dl_event_node：已经发生的现实事件节点；没有证据时不能伪造。
dl_evidence：每个事件或判断对应的证据摘录。
dl_evidence_node_link：证据、事件、应有之线之间的关系。
dl_impact_target：影响对象，可能是股票、行业、风格、K线、其他输出层。
dl_manifestation_bridge：市场或输出层显影；没有显影就记录缺口，不硬填。
dl_alternative_explanation：替代解释，至少考虑市场普涨、行业风、单股动能、其他暗线、数据缺口。
dl_chain_state：当前读法、置信度、消费等级和下一步。
```

如果某一层暂时没有证据，必须明确写成 `HELD_BY_EVIDENCE_GAP`、`NO_REALITY_CONFIRMATION_YET`、`MARKET_MANIFESTATION_MISSING` 等状态，不能为了凑完整链路伪造节点。

案例入口说明：

```text
casebook/案例数据入口说明.md
data_contract/案例数据入库说明.md
```

## 6. 更新 seed 数据流程

维护者在本机新增或修改了 `dl_` 数据后，需要重新生成共享数据包。

如果导入或更新了旧案例，先执行 legacy 合规修复：

```powershell
python scripts\repair_legacy_case_compliance.py --database tianxia
```

该脚本会把缺失的事件节点、市场显影和替代解释补成显式 `GAP_REVIEW`，不会伪造事实。

在 darkline 项目根目录执行：

```powershell
python scripts\export_darkline_mysql_seed.py --database tianxia
```

重新导出后检查：

```text
data/mysql_seed_20260624/seed_summary.json
data/mysql_seed_20260624/manifest.csv
package_manifest.csv
```

然后提交当前 darkline 项目根目录到 git。

## 7. 常见问题

### 7.1 技能安装后没有触发

检查本机技能目录下是否存在：

```text
<用户home>/.codex2/skills/darkline/SKILL.md
```

并确认文件 frontmatter 中有：

```text
name: darkline
```

### 7.2 数据导入失败

先检查：

```text
MySQL 服务是否启动
账号密码是否正确
数据库名是否正确
是否已安装 pymysql
```

再单独运行：

```powershell
python scripts\validate_darkline_install.py --database tianxia
```

### 7.3 是否必须叫 tianxia

不必须。导入和校验脚本都支持 `--database` 参数。

团队内部建议统一使用：

```text
tianxia
```

## 8. Full archive 数据包

当前 seed 不是只导入案例标题和结论，而是包含 full archive 链路表。

已包含：

```text
dl_source_document
dl_case_import_batch
dl_case_record
dl_darkline_hypothesis
dl_case_reasoning_step
dl_expected_line
dl_event_node
dl_evidence
dl_evidence_node_link
dl_impact_target
dl_manifestation_bridge
dl_alternative_explanation
dl_chain_state
```

判断 darkline 是否可用时，不只看 `dl_darkline_hypothesis` 行数，还要检查 `dl_case_reasoning_step`、`dl_evidence`、`dl_expected_line`、`dl_manifestation_bridge`、`dl_chain_state` 等表是否能串回同一个 `case_id` / `darkline_hypothesis_id`。