本文档给 darkline 项目管理者和接入方使用。目标是：同事从 git 拉下当前目录后，能导入同一份 seed 数据，并把本地 Codex darkline 技能安装到自己的机器上。
下文所有项目内路径都使用相对路径。执行命令前先进入 darkline 项目根目录。
安装完成后，本机应具备：
1. MySQL 中存在 darkline 的 dl_ 数据表。
2. Codex 本地 skills 目录中存在 darkline 技能。
3. 使用 darkline 关键字时，AI 会按 darkline 方法论、信息收集、信息存储和案例追踪流程执行。
darkline 技能是 AI 的外部信息分析工作流约束。安装后，AI 在处理暗线、新闻、公告、事件链、证据链、案例分析、K线显影、信息拓扑归档时，会优先按 darkline 流程执行。
它会要求 AI 做这些事：
1. 先判断任务模式：广撒网收集 / 暗线专线追踪 / 方法论验证 / 数据整理。
2. 把新闻和事件当作信息叶子，不直接当结论。
3. 反推暗线意图，且暗线必须是意图 / 目标 / 人心 / 组织意志。
4. 按 B/C -> A -> M -> N/L -> 市场输出 -> 实际结果 -> 总结 讲清楚。
5. 连续追问为什么，不能停在第一个表面解释。
6. 记录证据链、应有之线、影响对象、显影、替代解释和链路状态。
7. 新增案例时，按信息拓扑结构入库和校验。
它不会自动保证结论正确，也不会替代人工复核。它的价值是让不同 AI 用同一套流程分析、记录和复核外部信息。
data/mysql_seed_20260624/ MySQL seed 数据包
scripts/import_darkline_mysql_seed.py 导入 seed 数据
scripts/validate_darkline_install.py 校验数据和技能安装结果
skill_package/darkline/ 可复制安装的 Codex 技能包
技能安装目录不强制写死。默认使用：
<用户home>/.codex2/skills/darkline
如果本机 Codex 使用其他技能目录，安装者可以设置环境变量：
$env:DARKLINE_SKILL_DIR="你的技能目录\darkline"
后续安装和校验命令都会优先使用 DARKLINE_SKILL_DIR。
seed 数据包含这些表：
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 修复脚本；只有维护者后续新增或重新导入旧案例后，才需要重新执行修复。
适用场景：同事本地 MySQL 还没有 darkline 数据。
要求：
MySQL 8.x
字符集 utf8mb4
本机能用账号密码连接
推荐数据库名：
tianxia
如果团队成员不想使用 tianxia，也可以在导入和校验命令里通过 --database 指定其他库名。
导入和校验脚本使用 pymysql：
python -m pip install pymysql
在 darkline 项目根目录执行：
python scripts\import_darkline_mysql_seed.py --host 127.0.0.1 --port 3306 --user root --database tianxia --create-database
脚本会提示输入 MySQL 密码。也可以用环境变量避免在命令行里出现密码：
$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
说明：
1. 脚本只导入 dl_ 命名空间表。
2. seed 内的表会按 data/mysql_seed_20260624/schema.sql 重建。
3. seed 数据包不包含任何本机 MySQL 密码。
在 darkline 项目根目录执行：
$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
安装后应存在：
<用户home>/.codex2/skills/darkline/SKILL.md
在 darkline 项目根目录执行：
$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 表示安装成功。
适用场景：本机已经有 dl_ 数据，只需要安装或更新技能。
例如本项目管理者本机已经导入过当前 seed，且 validate_darkline_install.py 校验通过，就不要重复导入数据包，只需要同步技能。
在 darkline 项目根目录执行：
$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"
新增案例不能只写故事，必须能进入信息拓扑结构。
新增案例分两层：
最小层：能让人读懂案例，并能在数据库里找到案例入口。
完整链路层：能让后续 AI 或人复盘暗线假设、证据链、应有之线、现实验证、市场显影和替代解释。
最低要求：
1. 按 B/C -> A -> M -> N/L -> 市场输出 -> 实际结果 -> 总结 写案例正文。
2. 写入 dl_case_record。
3. 写入 dl_darkline_hypothesis。
4. 写入 dl_chain_state。
5. 至少写 1 条 expected_line，说明如果暗线为真，后续应发生什么。
6. 每次判断变化新增版本，不覆盖旧判断。
完整链路要求：
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 等状态，不能为了凑完整链路伪造节点。
案例入口说明：
casebook/案例数据入口说明.md
data_contract/案例数据入库说明.md
维护者在本机新增或修改了 dl_ 数据后，需要重新生成共享数据包。
如果导入或更新了旧案例，先执行 legacy 合规修复：
python scripts\repair_legacy_case_compliance.py --database tianxia
该脚本会把缺失的事件节点、市场显影和替代解释补成显式 GAP_REVIEW，不会伪造事实。
在 darkline 项目根目录执行：
python scripts\export_darkline_mysql_seed.py --database tianxia
重新导出后检查：
data/mysql_seed_20260624/seed_summary.json
data/mysql_seed_20260624/manifest.csv
package_manifest.csv
然后提交当前 darkline 项目根目录到 git。
检查本机技能目录下是否存在：
<用户home>/.codex2/skills/darkline/SKILL.md
并确认文件 frontmatter 中有：
name: darkline
先检查：
MySQL 服务是否启动
账号密码是否正确
数据库名是否正确
是否已安装 pymysql
再单独运行：
python scripts\validate_darkline_install.py --database tianxia
不必须。导入和校验脚本都支持 --database 参数。
团队内部建议统一使用：
tianxia
当前 seed 不是只导入案例标题和结论，而是包含 full archive 链路表。
已包含：
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。